feat(docs): add bilingual English/Chinese documentation support

- Add language switcher with page-pair metadata (lang, page_key, lang_ref)
- Create zh/ directory with Chinese counterparts for all public pages
- Refresh README.md and README.zh-CN.md with unified structure
- Update _config.yml for bilingual navigation
- Add language-toggle.js and switcher styles
- Update pages.yml workflow triggers for zh/** and _includes/**

OpenSpec change: bilingual-docs-closeout

Author: LessUp

.github/workflows/pages.yml

@@ -12,7 +12,9 @@ on:
       - 'CONTRIBUTING.md'
       - 'index.md'
       - '_config.yml'
+      - '_includes/**'
       - 'docs/**'
+      - 'zh/**'
       - 'specs.md'
       - 'assets/**'
       - '_sass/**'

README.md

@@ -2,30 +2,30 @@
 
 [![CI](https://github.com/LessUp/sgemm-optimization/actions/workflows/ci.yml/badge.svg)](https://github.com/LessUp/sgemm-optimization/actions/workflows/ci.yml)
 [![Pages](https://github.com/LessUp/sgemm-optimization/actions/workflows/pages.yml/badge.svg)](https://lessup.github.io/sgemm-optimization/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 ![CUDA](https://img.shields.io/badge/CUDA-11.0+-76B900?logo=nvidia&logoColor=white)
 ![C++](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white)
 
 English | [简体中文](README.zh-CN.md)
 
-Progressive CUDA SGEMM tutorial and reference implementation. The repository contains five hand-written kernel variants, cuBLAS-backed verification, a benchmark harness, and OpenSpec-governed repository rules for keeping the project compact and trustworthy.
+Progressive CUDA SGEMM tutorial and reference implementation, from naive kernels to Tensor Core WMMA. Includes cuBLAS-backed verification, benchmark harness, and OpenSpec-governed repository rules.
 
 ## Why this repository exists
 
-- **Show the optimization ladder clearly**: naive -> tiled -> bank-conflict-free -> double-buffered -> Tensor Core WMMA
-- **Stay readable**: each optimization lives in its own kernel file and keeps a consistent launch interface
-- **Stay verifiable**: kernels are checked against cuBLAS, with separate tolerances for FP32 and Tensor Core paths
-- **Stay maintainable**: the repository uses OpenSpec to keep docs, workflow, and validation rules aligned
+- **Show the optimization ladder clearly**: naive → tiled → bank-conflict-free → double-buffer → Tensor Core WMMA
+- **Stay readable**: each optimization lives in its own kernel file with a consistent launch interface
+- **Stay verifiable**: kernels are checked against cuBLAS with separate tolerances for FP32 and Tensor Core paths
+- **Stay maintainable**: OpenSpec keeps docs, workflow, and validation rules aligned
 
-## Kernel progression
+## Optimization ladder
 
-| Stage | File | Main idea |
-|-------|------|-----------|
-| Naive | `src/kernels/naive_sgemm.cuh` | Baseline triple-loop mapping |
-| Tiled | `src/kernels/tiled_sgemm.cuh` | Shared-memory blocking |
-| Bank-Free | `src/kernels/bank_conflict_free_sgemm.cuh` | `[TILE_SIZE][TILE_SIZE+1]` padding |
-| Double Buffer | `src/kernels/double_buffer_sgemm.cuh` | Tile staging overlap and latency hiding |
-| Tensor Core | `src/kernels/tensor_core_sgemm.cuh` | WMMA path with safe FP32 fallback |
+| Stage | Kernel | What you learn |
+|------:|--------|----------------|
+| 1 | [Naive](docs/kernel-naive) | Thread-to-output mapping and baseline cost |
+| 2 | [Tiled](docs/kernel-tiled) | Shared-memory blocking and data reuse |
+| 3 | [Bank-Free](docs/kernel-bank-free) | Padding away 32-way bank conflicts |
+| 4 | [Double Buffer](docs/kernel-double-buffer) | Latency hiding through staged tiles |
+| 5 | [Tensor Core](docs/kernel-tensor-core) | WMMA usage with guarded FP32 fallback |
 
 ## Quick start
 
@@ -47,21 +47,22 @@ make benchmark
 make test
 ```
 
-## Validation model
+## Where to start
 
-- **Local GPU machine**: runtime tests, correctness checks, and benchmarking
-- **GitHub Actions**: format/style, CUDA compile validation, OpenSpec/repository checks, and Pages deployment
+| If you want to... | Start here |
+|-------------------|------------|
+| Build and run once | [Getting Started](docs/getting-started) |
+| Learn the optimization path | [Learning Path](docs/learning-path) |
+| Understand repository structure | [Architecture](docs/architecture) |
+| See performance context | [Benchmark Results](docs/benchmark-results) |
+| Inspect governance rules | [Specifications](specs) |
 
-Standard FP32 kernels use `rtol=1e-3`, `atol=1e-4`. The Tensor Core path uses `rtol=5e-2`, `atol=1e-2`.
+## Validation boundary
 
-## Read next
+- **Local GPU machine**: runtime tests, correctness checks, benchmarking
+- **GitHub Actions**: format/style, CUDA compile, OpenSpec checks, Pages deployment
 
-- [Getting Started](docs/getting-started.md)
-- [Learning Path](docs/learning-path.md)
-- [Architecture Overview](docs/architecture.md)
-- [Benchmark Notes](docs/benchmark-results.md)
-- [Specifications Index](specs.md)
-- [GitHub Pages site](https://lessup.github.io/sgemm-optimization/)
+Standard FP32 kernels: `rtol=1e-3`, `atol=1e-4`. Tensor Core path: `rtol=5e-2`, `atol=1e-2`.
 
 ## Repository layout
 
@@ -72,22 +73,22 @@ src/
 └── main.cu         # Benchmark entry point
 tests/
 └── test_sgemm.cu   # Google Test suite
-docs/               # Public learning-oriented documentation
-openspec/           # Stable specs, changes, and workflow guidance
+docs/               # Learning-oriented documentation
+openspec/           # Stable specs, changes, workflow guidance
 ```
 
-## Development workflow
+## Project status
 
-Non-trivial repository changes are expected to follow:
+This repository is in **archive-ready** state. All kernel implementations are complete, tests pass, and documentation is aligned. Non-trivial changes follow the OpenSpec workflow:
 
-1. `/opsx:explore`
-2. `/opsx:propose "description"`
-3. `/opsx:apply`
-4. `/review`
-5. `/opsx:archive`
+1. `/opsx:explore` — clarify scope and trade-offs
+2. `/opsx:propose "description"` — create change artifacts
+3. `/opsx:apply` — implement tasks
+4. `/review` — quality gate
+5. `/opsx:archive` — merge and close
 
-The stable authoritative specs live under `openspec/specs/`. Active implementation plans live under `openspec/changes/<change>/`.
+Stable specs: `openspec/specs/`. Active changes: `openspec/changes/<change>/`.
 
 ## License
 
-MIT. See [LICENSE.md](LICENSE.md).
+MIT. See [LICENSE](LICENSE).

README.zh-CN.md

@@ -8,24 +8,24 @@
 
 [English](README.md) | 简体中文
 
-这是一个渐进式 CUDA SGEMM 教程与参考实现仓库。项目用 5 个手写 kernel 展示从最朴素矩阵乘法到 Tensor Core WMMA 的优化路径，并配套 cuBLAS 对标验证、benchmark 工具，以及基于 OpenSpec 的仓库治理流程。
+渐进式 CUDA SGEMM 教程与参考实现，从朴素 kernel 到 Tensor Core WMMA。包含 cuBLAS 对标验证、benchmark 工具，以及 OpenSpec 仓库治理流程。
 
 ## 为什么值得看
 
-- **优化链条完整**：naive -> tiled -> bank-conflict-free -> double-buffer -> Tensor Core
-- **代码可读性强**：每一级优化都独立成文件，并保持统一的 launch 接口
-- **验证链路完整**：用 cuBLAS 做正确性对照，并区分标准 FP32 与 Tensor Core 容差
-- **工程边界清晰**：仓库通过 OpenSpec 管理规范、文档、workflow 和收尾整理
+- **优化链条完整**：naive → tiled → bank-conflict-free → double-buffer → Tensor Core WMMA
+- **代码可读性强**：每级优化独立成文件，保持统一的 launch 接口
+- **验证链路完整**：cuBLAS 正确性对照，区分标准 FP32 与 Tensor Core 容差
+- **工程边界清晰**：OpenSpec 管理规范、文档、workflow 和收尾整理
 
-## Kernel 演进
+## 优化阶梯
 
-| 阶段 | 文件 | 核心思路 |
-|------|------|----------|
-| Naive | `src/kernels/naive_sgemm.cuh` | 基础三层循环映射 |
-| Tiled | `src/kernels/tiled_sgemm.cuh` | 共享内存分块 |
-| Bank-Free | `src/kernels/bank_conflict_free_sgemm.cuh` | `[TILE_SIZE][TILE_SIZE+1]` padding 消除 bank 冲突 |
-| Double Buffer | `src/kernels/double_buffer_sgemm.cuh` | tile staging 重叠与延迟隐藏 |
-| Tensor Core | `src/kernels/tensor_core_sgemm.cuh` | WMMA 路径与安全 FP32 回退 |
+| 阶段 | Kernel | 学习重点 |
+|-----:|--------|----------|
+| 1 | [Naive](zh/docs/kernel-naive) | 线程到输出的映射与基线代价 |
+| 2 | [Tiled](zh/docs/kernel-tiled) | 共享内存分块与数据复用 |
+| 3 | [Bank-Free](zh/docs/kernel-bank-free) | Padding 消除 32 路 bank 冲突 |
+| 4 | [Double Buffer](zh/docs/kernel-double-buffer) | 分阶段 tile 加载与延迟隐藏 |
+| 5 | [Tensor Core](zh/docs/kernel-tensor-core) | WMMA 使用与安全的 FP32 回退 |
 
 ## 快速开始
 
@@ -47,21 +47,22 @@ make benchmark
 make test
 ```
 
-## 验证边界
+## 从哪里开始
 
-- **本地 GPU 机器**：运行时测试、正确性验证、benchmark
-- **GitHub Actions**：格式/风格、CUDA 编译验证、OpenSpec/仓库结构校验、Pages 部署
+| 如果你想... | 从这里开始 |
+|-------------|-----------|
+| 编译运行一次 | [快速上手](zh/docs/getting-started) |
+| 学习优化路径 | [学习路径](zh/docs/learning-path) |
+| 了解仓库结构 | [架构概览](zh/docs/architecture) |
+| 查看性能数据 | [Benchmark 结果](zh/docs/benchmark-results) |
+| 查看治理规则 | [规范索引](zh/specs) |
 
-标准 FP32 kernel 使用 `rtol=1e-3`、`atol=1e-4`；Tensor Core 路径使用 `rtol=5e-2`、`atol=1e-2`。
+## 验证边界
 
-## 建议继续阅读
+- **本地 GPU 机器**：运行时测试、正确性验证、benchmark
+- **GitHub Actions**：格式/风格、CUDA 编译、OpenSpec 校验、Pages 部署
 
-- [快速上手](docs/getting-started.md)
-- [学习路径](docs/learning-path.md)
-- [架构概览](docs/architecture.md)
-- [Benchmark 说明](docs/benchmark-results.md)
-- [规范索引](specs.md)
-- [GitHub Pages 站点](https://lessup.github.io/sgemm-optimization/)
+标准 FP32 kernel：`rtol=1e-3`、`atol=1e-4`。Tensor Core 路径：`rtol=5e-2`、`atol=1e-2`。
 
 ## 仓库结构
 
@@ -76,17 +77,17 @@ docs/               # 面向读者的学习型文档
 openspec/           # 稳定 specs、变更和流程说明
 ```
 
-## 开发流程
+## 项目状态
 
-涉及仓库结构、规范或文档的非小改动，默认遵循：
+本仓库处于**归档就绪**状态。所有 kernel 实现已完成，测试通过，文档对齐。非小改动遵循 OpenSpec 工作流：
 
-1. `/opsx:explore`
-2. `/opsx:propose "description"`
-3. `/opsx:apply`
-4. `/review`
-5. `/opsx:archive`
+1. `/opsx:explore` — 明确范围与权衡
+2. `/opsx:propose "描述"` — 创建变更文档
+3. `/opsx:apply` — 实施任务
+4. `/review` — 质量门禁
+5. `/opsx:archive` — 合并并关闭
 
-稳定规范位于 `openspec/specs/`，活动实现计划位于 `openspec/changes/<change>/`。
+稳定规范：`openspec/specs/`。活动变更：`openspec/changes/<change>/`。
 
 ## 许可证
 

_config.yml

@@ -12,8 +12,8 @@ plugins:
 
 title: SGEMM Optimization
 description: >-
-  Learn CUDA SGEMM optimization from a readable baseline to Tensor Core WMMA,
-  with verification, benchmarks, and compact engineering guidance.
+  Bilingual CUDA SGEMM optimization tutorial and reference implementation,
+  from naive kernels to Tensor Core WMMA.
 repository: LessUp/sgemm-optimization
 author: LessUp
 lang: en
@@ -31,7 +31,9 @@ aux_links_new_tab: true
 aux_links:
   "GitHub":
     - "//github.com/LessUp/sgemm-optimization"
-  "README (中文)":
+  "English README":
+    - "//github.com/LessUp/sgemm-optimization/blob/master/README.md"
+  "中文 README":
     - "//github.com/LessUp/sgemm-optimization/blob/master/README.zh-CN.md"
 
 nav_external_links:

_includes/head_custom.html

@@ -0,0 +1 @@
+<script src="{{ '/assets/js/language-toggle.js' | relative_url }}" defer></script>

_includes/nav_footer_custom.html

@@ -0,0 +1,14 @@
+<div class="language-switcher"
+     data-page-key="{{ page.page_key | default: 'unknown' }}"
+     data-lang="{{ page.lang | default: 'en' }}"
+     data-lang-ref="{{ page.lang_ref | default: '' }}">
+  <span class="language-switcher-label">Lang:</span>
+  <button type="button" data-lang-choice="en"
+          class="{% if page.lang == 'en' or page.lang == nil %}is-active{% endif %}">
+    EN
+  </button>
+  <button type="button" data-lang-choice="zh-CN"
+          class="{% if page.lang == 'zh-CN' %}is-active{% endif %}">
+    中文
+  </button>
+</div>

_sass/custom/custom.scss

@@ -651,3 +651,59 @@ div.aux-nav {
     grid-template-columns: 1fr;
   }
 }
+
+// ============================================
+// LANGUAGE SWITCHER
+// ============================================
+
+.language-switcher {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin: 0.75rem 0;
+  padding: 0.5rem;
+  background-color: var(--bg-tertiary);
+  border-radius: 6px;
+  border: 1px solid var(--border-subtle);
+}
+
+.language-switcher-label {
+  color: var(--text-muted);
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-right: 0.25rem;
+}
+
+.language-switcher button {
+  padding: 0.25rem 0.75rem;
+  border: 1px solid var(--border-subtle);
+  border-radius: 4px;
+  background: transparent;
+  color: var(--text-secondary);
+  cursor: pointer;
+  font-size: 0.875rem;
+  font-weight: 500;
+  transition: all 0.2s ease;
+}
+
+.language-switcher button:hover {
+  border-color: var(--nvidia-green);
+  color: var(--nvidia-green);
+  background-color: rgba(118, 185, 0, 0.05);
+}
+
+.language-switcher button.is-active {
+  border-color: var(--nvidia-green);
+  color: var(--nvidia-green);
+  background-color: rgba(118, 185, 0, 0.1);
+  font-weight: 600;
+}
+
+// Mobile adjustments for language switcher
+@media (max-width: 800px) {
+  .language-switcher {
+    justify-content: center;
+    margin: 1rem 0;
+  }
+}