fix: finalize whitepaper rebuild safeguards

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: LessUp

docs/.vitepress/config.ts

@@ -9,6 +9,8 @@ const base = rawBase
     : `/${rawBase}/`
   : '/sgemm-optimization/'
 
+const asset = (relativePath: string) => `${base}${relativePath.replace(/^\/+/, '')}`
+
 function localeNav(prefix: '/en/' | '/zh/') {
   if (prefix === '/en/') {
     return [
@@ -183,9 +185,9 @@ export default withMermaid(defineConfig({
   head: [
     ['meta', { name: 'theme-color', content: '#76b900' }],
     ['meta', { property: 'og:type', content: 'website' }],
-    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/sgemm-optimization/favicon.svg' }],
-    ['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: '/sgemm-optimization/favicon-32x32.png' }],
-    ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: '/sgemm-optimization/apple-touch-icon.png' }],
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: asset('favicon.svg') }],
+    ['link', { rel: 'icon', type: 'image/png', sizes: '32x32', href: asset('favicon-32x32.png') }],
+    ['link', { rel: 'apple-touch-icon', sizes: '180x180', href: asset('apple-touch-icon.png') }],
   ],
 
   ignoreDeadLinks: [

docs/en/architecture/index.md

@@ -22,14 +22,17 @@ SGEMM optimization on modern NVIDIA hardware is a sequence of bottleneck-class m
 
 | Component | Layer | Primary responsibility |
 |-----------|-------|------------------------|
-| `src/main.cu` | Driver | Dispatch, size validation, timing harness, output |
-| `src/kernels/naive.cuh` | Kernel | FP32 baseline with full global-memory load cost |
-| `src/kernels/tiled.cuh` | Kernel | Cooperative tile load into shared memory; SMEM reuse |
-| `src/kernels/bank_free.cuh` | Kernel | Padding eliminates shared-memory bank conflicts |
-| `src/kernels/double_buffer.cuh` | Kernel | Async prefetch overlaps next-tile staging with active compute |
-| `src/kernels/tensor_core.cuh` | Kernel | WMMA fragment accumulation on hardware-aligned tiles |
-| `src/utils/cuda_check.cuh` | Utility | CUDA error checking and RAII device-resource guards |
-| `tests/test_sgemm.cu` | Test | Correctness verification under reference tolerance |
+| `src/main.cu` | Driver | Entry point that delegates CLI parsing and benchmark orchestration |
+| `src/cli_parser.cuh` | Driver support | Parses mode flags, shapes, and runtime options into `BenchmarkConfig` |
+| `src/benchmark_runner.cuh` | Driver support | Runs configured benchmark and verification flows through one binary |
+| `src/kernels/naive_sgemm.cuh` | Kernel | FP32 baseline with full global-memory load cost |
+| `src/kernels/tiled_sgemm.cuh` | Kernel | Cooperative tile load into shared memory; SMEM reuse |
+| `src/kernels/bank_conflict_free_sgemm.cuh` | Kernel | Padding eliminates shared-memory bank conflicts |
+| `src/kernels/double_buffer_sgemm.cuh` | Kernel | Overlaps next-tile staging with active compute |
+| `src/kernels/tensor_core_sgemm.cuh` | Kernel | WMMA fragment accumulation on hardware-aligned tiles |
+| `src/utils/cuda_utils.cuh` | Utility | CUDA error macros, RAII device-memory wrappers, device metadata |
+| `src/utils/verify.cuh` | Utility | cuBLAS-backed correctness verification and tolerance policy |
+| `tests/test_sgemm.cu` | Test | GPU-side correctness verification under cuBLAS reference tolerance |
 
 ## Memory-hierarchy data flow
 
@@ -88,7 +91,7 @@ The project separates what two different environments can prove:
 
 | Claim | Local CUDA GPU | Hosted CI |
 |-------|----------------|-----------|
-| Compilation succeeds | ✓ | ✓ (structure check only) |
+| Compilation succeeds | ✓ | ✗ |
 | Output correctness vs. cuBLAS | ✓ | ✗ |
 | Benchmark performance claims | ✓ | ✗ |
 | Repository structure and docs | ✓ | ✓ |

docs/en/architecture/system-blueprint.md

@@ -18,14 +18,17 @@ This page is a full component-level blueprint of the SGEMM optimization system.
 
 | Component | Role | Constraints |
 |---|---|---|
-| `main.cu` entry | Parses arguments, selects kernel variant, routes to benchmarking or correctness check | Must not hard-code a variant; selection is runtime |
-| `kernels/sgemm_naive.cuh` | Baseline FP32, one thread per output element | Establishes the cost model; no shared memory |
-| `kernels/sgemm_tiled.cuh` | Tiled FP32 with shared-memory staging | Tile size is a compile-time template parameter |
-| `kernels/sgemm_bank_free.cuh` | Tiled FP32 with padding to eliminate bank conflicts | Padding is the only structural difference from tiled |
-| `kernels/sgemm_double_buffer.cuh` | Overlapped staging and compute using double buffering | Requires at least two staging buffers in shared memory |
-| `kernels/sgemm_tensor_core.cuh` | WMMA-based computation with FP32 entry path | Guarded by device capability and shape divisibility |
-| `utils/cuda_check.h` | RAII-based error propagation for CUDA API and kernel calls | Throws `std::runtime_error` on failure; no silent returns |
-| `utils/matrix.h` | Host-side matrix initialization and reference computation | Row-major layout; reference uses CPU BLAS or naive FP64 loop |
+| `src/main.cu` | Parses arguments, delegates to `CliParser` and `BenchmarkRunner` | Must keep one runtime-controlled entry path |
+| `src/cli_parser.cuh` | Maps CLI flags to benchmark/verification modes | Shape labels and mode switches stay centralized |
+| `src/benchmark_runner.cuh` | Routes each configured run through benchmarking and reporting | Shared host orchestration keeps cross-kernel comparisons consistent |
+| `src/kernels/naive_sgemm.cuh` | Baseline FP32, one thread per output element | Establishes the cost model; no shared memory |
+| `src/kernels/tiled_sgemm.cuh` | Tiled FP32 with shared-memory staging | Tile size is a compile-time template parameter |
+| `src/kernels/bank_conflict_free_sgemm.cuh` | Tiled FP32 with padding to eliminate bank conflicts | Padding is the only structural difference from tiled |
+| `src/kernels/double_buffer_sgemm.cuh` | Overlapped staging and compute using double buffering | Requires two staging buffers in shared memory |
+| `src/kernels/tensor_core_sgemm.cuh` | WMMA-based computation for aligned Tensor Core shapes | Guarded by device capability and shape divisibility |
+| `src/kernels/tensor_core_fallback.cuh` | Safe mixed-precision entry and fallback logic | Must preserve FP32 correctness on unsupported shapes |
+| `src/utils/cuda_utils.cuh` | CUDA error macros, RAII device memory, device metadata | Uses `CUDA_CHECK` / `CUBLAS_CHECK`; no silent failure path |
+| `src/utils/verify.cuh` | cuBLAS-backed oracle verification and tolerance policy | Reference is computed against cuBLAS on the active GPU |
 | `tests/test_sgemm.cu` | cuBLAS-backed oracle correctness suite | Runs only on GPU; not included in hosted CI |
 | Docs site | Narrative layer — architecture, academy, validation, research | VitePress with bilingual routes; no runtime GPU dependency |
 
@@ -56,7 +59,7 @@ Correctness check against cuBLAS oracle (local GPU only)
 
 ### RAII error handling
 
-All CUDA API calls and kernel launches are wrapped in `cudaCheck()`. This ensures that any failure path immediately terminates with a traceable error rather than silently propagating incorrect results through the pipeline.
+All CUDA API calls and kernel launches are wrapped in `CUDA_CHECK`, and cuBLAS calls are wrapped in `CUBLAS_CHECK`. This ensures that any failure path immediately terminates with a traceable error rather than silently propagating incorrect results through the pipeline.
 
 **Consequence:** Test code cannot accidentally swallow an error and then compare incorrect output against the cuBLAS oracle, which would make a failing kernel appear to pass.
 
@@ -85,7 +88,7 @@ The blueprint explicitly separates compile-time-verifiable invariants from runti
 | Invariant class | Verifiable where |
 |---|---|
 | File structure, docs, OpenSpec alignment | Hosted CI |
-| CUDA code compiles without warning | Hosted CI (compile-only) |
+| CUDA code compiles and runs on a real CUDA toolchain | Local GPU-capable machine |
 | Correctness under cuBLAS oracle | Local GPU run |
 | Benchmark numbers and speedup ratios | Local GPU run with named hardware |
 

docs/public/figures/whitepaper-system-light.svg

@@ -1,6 +1,6 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -47,11 +47,14 @@ for (const locale of ['en', 'zh']) {
   test(`${locale} curated figures use the shared theme-aware component`, () => {
     const homepage = readFileSync(path.join(docsRoot, locale, 'index.md'), 'utf8')
     const architecture = readFileSync(path.join(docsRoot, locale, 'architecture', 'index.md'), 'utf8')
+    const blueprint = readFileSync(path.join(docsRoot, locale, 'architecture', 'system-blueprint.md'), 'utf8')
 
     assert.equal(homepage.includes('<ThemedFigure'), true)
     assert.equal(architecture.includes('<ThemedFigure'), true)
+    assert.equal(blueprint.includes('<ThemedFigure'), true)
     assert.equal(homepage.includes('<picture>'), false)
     assert.equal(architecture.includes('<picture>'), false)
+    assert.equal(blueprint.includes('<picture>'), false)
   })
 }
 
@@ -65,3 +68,15 @@ test('whitepaper figure assets exist for both light and dark themes', () => {
 test('shared theme-aware figure component exists', () => {
   assert.equal(existsSync(path.join(docsRoot, '.vitepress', 'components', 'ThemedFigure.vue')), true)
 })
+
+test('figure SVGs do not contain malformed spaced hex colors', () => {
+  const figureDir = path.join(docsRoot, 'public', 'figures')
+
+  for (const file of readdirSync(figureDir)) {
+    if (!file.endsWith('.svg'))
+      continue
+
+    const svg = readFileSync(path.join(figureDir, file), 'utf8')
+    assert.equal(/#[0-9A-Fa-f]{2,}\s+[0-9A-Fa-f]+/.test(svg), false, `${file} contains a malformed hex color`)
+  }
+})

docs/tests/architecture-routes.test.mjs

@@ -22,14 +22,17 @@ title: 架构概述
 
 | 组件 | 层次 | 主要职责 |
 |------|------|----------|
-| `src/main.cu` | 驱动层 | 分发、尺寸验证、计时框架、输出 |
-| `src/kernels/naive.cuh` | Kernel | FP32 基线，承受完整全局内存加载代价 |
-| `src/kernels/tiled.cuh` | Kernel | 协作式 tile 加载入共享内存；SMEM 复用 |
-| `src/kernels/bank_free.cuh` | Kernel | Padding 消除共享内存 bank 冲突 |
-| `src/kernels/double_buffer.cuh` | Kernel | 异步预取将下一 tile 的 staging 与当前计算重叠 |
-| `src/kernels/tensor_core.cuh` | Kernel | 在硬件对齐的 tile 上执行 WMMA fragment 累加 |
-| `src/utils/cuda_check.cuh` | 工具 | CUDA 错误检查与 RAII 设备资源守卫 |
-| `tests/test_sgemm.cu` | 测试 | 在参考误差容限内验证正确性 |
+| `src/main.cu` | 驱动层 | 程序入口，负责把 CLI 解析和 benchmark 编排接起来 |
+| `src/cli_parser.cuh` | 驱动支撑 | 把模式标志、shape 和运行参数解析成 `BenchmarkConfig` |
+| `src/benchmark_runner.cuh` | 驱动支撑 | 用同一个二进制执行 benchmark 与 verification 流程 |
+| `src/kernels/naive_sgemm.cuh` | Kernel | FP32 基线，承受完整全局内存加载代价 |
+| `src/kernels/tiled_sgemm.cuh` | Kernel | 协作式 tile 加载入共享内存；SMEM 复用 |
+| `src/kernels/bank_conflict_free_sgemm.cuh` | Kernel | Padding 消除共享内存 bank 冲突 |
+| `src/kernels/double_buffer_sgemm.cuh` | Kernel | 将下一 tile 的 staging 与当前计算重叠 |
+| `src/kernels/tensor_core_sgemm.cuh` | Kernel | 在硬件对齐的 tile 上执行 WMMA fragment 累加 |
+| `src/utils/cuda_utils.cuh` | 工具 | CUDA 错误宏、RAII 设备内存封装与设备信息 |
+| `src/utils/verify.cuh` | 工具 | 基于 cuBLAS 的正确性校验与容差策略 |
+| `tests/test_sgemm.cu` | 测试 | 基于 GPU 和 cuBLAS 参考的正确性测试 |
 
 ## 内存层级数据流
 
@@ -88,7 +91,7 @@ Memory Flow 页面将以具体的地址、stride、tile 维度和加载模式呈
 
 | 主张 | 本地 CUDA GPU | 托管 CI |
 |------|---------------|---------|
-| 编译成功 | ✓ | ✓（仅结构检查）|
+| 编译成功 | ✓ | ✗ |
 | 输出正确性 vs. cuBLAS | ✓ | ✗ |
 | Benchmark 性能结论 | ✓ | ✗ |
 | 仓库结构与文档 | ✓ | ✓ |

docs/zh/architecture/index.md

@@ -18,14 +18,17 @@ title: 系统蓝图
 
 | 组件 | 作用 | 约束 |
 |---|---|---|
-| `main.cu` 入口 | 解析参数、选择 kernel 变体、路由到 benchmark 或正确性检查 | 不得硬编码变体，选择在运行时完成 |
-| `kernels/sgemm_naive.cuh` | 基线 FP32，每个线程处理一个输出元素 | 建立代价模型；不使用共享内存 |
-| `kernels/sgemm_tiled.cuh` | 使用共享内存 staging 的 tiled FP32 | tile 大小是编译期模板参数 |
-| `kernels/sgemm_bank_free.cuh` | 通过 padding 消除 bank 冲突的 tiled FP32 | Padding 是与 tiled 版本的唯一结构差异 |
-| `kernels/sgemm_double_buffer.cuh` | 使用双缓冲重叠 staging 与 compute | 共享内存中至少需要两个 staging buffer |
-| `kernels/sgemm_tensor_core.cuh` | 基于 WMMA 的计算，带 FP32 入口路径 | 受设备能力和 shape 整除性保护 |
-| `utils/cuda_check.h` | CUDA API 和 kernel 调用的 RAII 错误传播 | 失败时抛出 `std::runtime_error`，不静默返回 |
-| `utils/matrix.h` | 主机侧矩阵初始化与参考计算 | 行主序布局；参考使用 CPU BLAS 或 naive FP64 循环 |
+| `src/main.cu` | 解析参数，并委托给 `CliParser` 与 `BenchmarkRunner` | 必须保持单一的运行时入口路径 |
+| `src/cli_parser.cuh` | 把 CLI 标志映射到 benchmark / verification 模式 | shape 标签和模式开关集中管理 |
+| `src/benchmark_runner.cuh` | 将每次配置好的运行路由到 benchmark 与结果报告 | 统一主机侧编排保证跨 kernel 对比一致 |
+| `src/kernels/naive_sgemm.cuh` | 基线 FP32，每个线程处理一个输出元素 | 建立代价模型；不使用共享内存 |
+| `src/kernels/tiled_sgemm.cuh` | 使用共享内存 staging 的 tiled FP32 | tile 大小是编译期模板参数 |
+| `src/kernels/bank_conflict_free_sgemm.cuh` | 通过 padding 消除 bank 冲突的 tiled FP32 | Padding 是与 tiled 版本的唯一结构差异 |
+| `src/kernels/double_buffer_sgemm.cuh` | 使用双缓冲重叠 staging 与 compute | 共享内存中需要两个 staging buffer |
+| `src/kernels/tensor_core_sgemm.cuh` | 面向对齐 Tensor Core shape 的 WMMA 计算 | 受设备能力和 shape 整除性保护 |
+| `src/kernels/tensor_core_fallback.cuh` | 安全的混合精度入口与回退逻辑 | 必须在不满足条件时保持 FP32 正确性 |
+| `src/utils/cuda_utils.cuh` | CUDA 错误宏、RAII 设备内存与设备信息 | 使用 `CUDA_CHECK` / `CUBLAS_CHECK`，不允许静默失败 |
+| `src/utils/verify.cuh` | 基于 cuBLAS 的 oracle 校验与容差策略 | 参考结果在活跃 GPU 上通过 cuBLAS 计算 |
 | `tests/test_sgemm.cu` | 基于 cuBLAS oracle 的正确性测试套件 | 只在 GPU 上运行；不包含在托管 CI 中 |
 | Docs 站点 | 叙事层——架构、学院、验证、研究 | VitePress 双语路由；无运行时 GPU 依赖 |
 
@@ -56,7 +59,7 @@ cudaMemcpy D→H
 
 ### RAII 错误处理
 
-所有 CUDA API 调用和 kernel 启动都通过 `cudaCheck()` 包装。这确保任何失败路径都会立即以可追踪的错误终止，而不会把错误结果静默地传递下去。
+所有 CUDA API 调用和 kernel 启动都通过 `CUDA_CHECK` 包装，cuBLAS 调用则通过 `CUBLAS_CHECK` 包装。这确保任何失败路径都会立即以可追踪的错误终止，而不会把错误结果静默地传递下去。
 
 **影响：** 测试代码不会意外吞掉错误然后用错误输出与 cuBLAS oracle 比较，避免了"失败的 kernel 看起来通过了测试"的问题。
 
@@ -85,7 +88,7 @@ Tensor Core 变体在提交 WMMA 计算之前检查设备能力和 shape 整除
 | 约束类别 | 可验证环境 |
 |---|---|
 | 文件结构、文档、OpenSpec 对齐 | 托管 CI |
-| CUDA 代码编译无警告 | 托管 CI（仅编译） |
+| CUDA 代码在真实 CUDA 工具链上完成编译与运行 | 本地 GPU 机器 |
 | cuBLAS oracle 正确性 | 本地 GPU 运行 |
 | Benchmark 数字和加速比 | 带命名硬件的本地 GPU 运行 |
 

docs/zh/architecture/system-blueprint.md

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-18