Merge branch 'docs-whitepaper-overhaul'

# Please enter a commit message to explain why this merge is necessary,
# especially if it merges an updated upstream into a topic branch.
#
# Lines starting with '#' will be ignored, and an empty message aborts
# the commit.

Author: LessUp

.github/workflows/ci-docs.yml

@@ -17,21 +17,27 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    env:
+      VITEPRESS_BASE: /cpp-high-performance-guide/
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
       - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "22"
+          node-version: "20"
           cache: npm
           cache-dependency-path: docs/package-lock.json
 
       - name: Install docs dependencies
         working-directory: docs
         run: npm ci
 
+      - name: Run docs regression tests
+        working-directory: docs
+        run: npm test
+
       - name: Build docs
         working-directory: docs
-        run: npm run build
+        run: npm run build:pages

.github/workflows/pages.yml

@@ -1,4 +1,4 @@
-name: Docs
+name: Docs (GitHub Pages)
 
 on:
   push:
@@ -18,49 +18,61 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build:
+  deploy:
+    # Only run on the original repository, not on forks
+    if: github.repository == 'LessUp/cpp-high-performance-guide'
     runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
     steps:
-      - name: Checkout
+      - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Configure GitHub Pages
-        id: pages
-        uses: actions/configure-pages@v5
-
-      - name: Setup Node.js
+      - name: Set up Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: '20'
           cache: npm
           cache-dependency-path: docs/package-lock.json
 
-      - name: Install dependencies
+      - name: Configure GitHub Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Set VitePress base
+        shell: bash
+        env:
+          BASE_PATH: ${{ steps.pages.outputs.base_path }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${BASE_PATH}" ]]; then
+            base="/"
+          else
+            base="${BASE_PATH%/}/"
+          fi
+          echo "VITEPRESS_BASE=${base}" >> "$GITHUB_ENV"
+
+      - name: Install docs dependencies
         working-directory: docs
         run: npm ci
 
+      - name: Run docs regression tests
+        working-directory: docs
+        run: npm test
+
       - name: Build docs
         working-directory: docs
-        env:
-          VITEPRESS_BASE: ${{ steps.pages.outputs.base_path }}
-        run: |
-          npm run build
-          touch .vitepress/dist/.nojekyll
+        run: npm run build:pages
+
+      - name: Add .nojekyll
+        run: touch docs/.vitepress/dist/.nojekyll
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs/.vitepress/dist
 
-  deploy:
-    # Only run on the original repository, not on forks
-    if: github.repository == 'LessUp/cpp-high-performance-guide'
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
       - name: Deploy to GitHub Pages
-        id: deployment
+        id: deploy
         uses: actions/deploy-pages@v4

.gitignore

@@ -55,6 +55,8 @@ cachegrind.out.*
 massif.out.*
 *.svg
 flamegraph*.svg
+!docs/public/logo.svg
+!docs/public/og-card.svg
 
 # Benchmark results
 *_bench.json

DESIGN.md

@@ -0,0 +1,50 @@
+# Design System
+
+## Overview
+
+The docs site should read like a modern engineering monograph: structured, typographically confident, and visually
+precise. The primary scene is an expert reader reviewing architecture and implementation details on a laptop or large
+monitor in normal daylight, so the main experience should privilege a bright paper-like surface with a disciplined
+dark companion theme for late-night review.
+
+## Visual Direction
+
+- Whitepaper / lab notebook aesthetic, not product-marketing SaaS
+- Restrained color strategy with cool neutrals and one committed cobalt signal color
+- Strong typographic hierarchy, generous rhythm, and figure-like diagram framing
+- Minimal motion, mostly opacity and transform, never decorative layout animation
+
+## Color
+
+- Primary accent: deep cobalt in OKLCH, used for links, active states, figures, and emphasis
+- Neutrals: slightly blue-tinted paper, ink, and steel tones, never pure black or white
+- States: success, warning, and danger should stay muted and publication-like rather than dashboard-bright
+- Dark theme should invert contrast without turning diagrams into neon-on-black
+
+## Typography
+
+- Use the system sans stack for maintainability
+- Let hierarchy come from scale, weight, and spacing rather than decorative font mixing
+- Keep body measure around 70ch
+- Headings should feel compressed and authoritative, body copy should feel calm and readable
+
+## Layout
+
+- Prefer sectional composition and editorial rhythm over repeated equal cards
+- Use panels, callout rows, figure frames, and structured index blocks as reusable primitives
+- Keep the docs landing page asymmetric where it helps emphasis, but preserve clarity over spectacle
+- Treat sidebars and top navigation as orientation tools, not decorative chrome
+
+## Components
+
+- Bilingual language switcher integrated into the nav
+- Section index blocks for academy / architecture / research navigation
+- Figure shell for Mermaid and SVG diagrams with caption and note support
+- Reference list and comparison table styles for citations and related-work sections
+- Hero rail with thesis, validation signals, and route entry points
+
+## Motion
+
+- Very light fades and lifts for interactive affordances
+- No animated gradients
+- No motion that blocks reading or competes with code and diagrams

PRODUCT.md

@@ -0,0 +1,43 @@
+# Product
+
+## Register
+
+brand
+
+## Users
+
+The primary readers are strict interviewers, advanced GitHub developers, and future maintainers evaluating the
+repository as a serious engineering artifact. They arrive in a browser, often from GitHub, and want fast evidence of
+architectural depth, technical rigor, validation discipline, and documentation quality.
+
+## Product Purpose
+
+This project teaches high-performance C++ through runnable examples, but the docs site must do more than teach. It
+must frame the repository as an archive-ready technical whitepaper, academy, and architecture guide that explains why
+the code exists, how the modules connect, how claims are validated, and where the project fits in the broader systems
+ecosystem.
+
+## Brand Personality
+
+Rigorous, scholarly, exacting. The tone should feel calm, credible, and opinionated, with enough visual character to
+avoid looking like a generic docs template.
+
+## Anti-references
+
+Do not look like a default GitBook clone, a card-farm SaaS landing page, a glassy AI-generated template, or a
+cyberpunk dashboard. Avoid ornamental gradients, gimmicky hero metrics, and any layout that signals "marketing site"
+before "engineering publication".
+
+## Design Principles
+
+1. Show evidence, not slogans.
+2. Make reading flow as strong as visual style.
+3. Treat diagrams as arguments, not decoration.
+4. Keep bilingual entry surfaces structurally equivalent.
+5. Favor durable, low-maintenance design primitives over one-off flair.
+
+## Accessibility & Inclusion
+
+Target WCAG AA contrast on both themes. Support reduced-motion users by keeping motion subtle and non-essential.
+Maintain strong readability for long-form technical content, including diagram captions, code-adjacent reference
+surfaces, and bilingual navigation.

README.md

@@ -42,7 +42,7 @@ Every major topic is meant to be **readable, buildable, and measurable**.
 | `examples/03-modern-cpp/` | constexpr, move semantics, reserve, ranges |
 | `examples/04-simd-vectorization/` | auto-vectorization, intrinsics, SIMD wrappers |
 | `examples/05-concurrency/` | atomics, lock-free queue, OpenMP |
-| `docs/` | bilingual learning path, profiling guide, troubleshooting, reference |
+| `docs/` | bilingual Pages whitepaper covering academy, architecture, playbook, reference, research |
 | `openspec/` | spec-driven development workflow and change history |
 
 ## Quick start
@@ -61,8 +61,9 @@ Run one benchmark:
 ./build/release/examples/02-memory-cache/aos_soa_bench
 ```
 
-Need sanitizer-specific guidance after the quick start? See
-[`docs/en/guides/validation.md`](docs/en/guides/validation.md).
+Need the redesigned docs route after the quick start? Start with
+[`docs/en/playbook/index.md`](docs/en/playbook/index.md), then continue to
+[`docs/en/guides/validation.md`](docs/en/guides/validation.md) for sanitizer-specific guidance.
 
 ## Validation commands
 
@@ -75,13 +76,17 @@ cmake --preset=tsan && cmake --build build/tsan && ctest --preset=tsan
 cmake --preset=ubsan && cmake --build build/ubsan && ctest --preset=ubsan
 ```
 
-## Documentation and learning path
+## Documentation entry points
 
 - **Docs site:** <https://lessup.github.io/cpp-high-performance-guide/>
-- **Quick start:** `docs/en/getting-started/quickstart.md`
-- **Learning path:** `docs/en/guides/learning-path.md`
-- **Profiling guide:** `docs/en/guides/profiling-guide.md`
-- **Validation & sanitizers:** `docs/en/guides/validation.md`
+- **Academy:** [`docs/en/academy/index.md`](docs/en/academy/index.md)
+- **Architecture:** [`docs/en/architecture/index.md`](docs/en/architecture/index.md)
+- **Playbook:** [`docs/en/playbook/index.md`](docs/en/playbook/index.md)
+- **Reference:** [`docs/en/reference/index.md`](docs/en/reference/index.md)
+- **Research:** [`docs/en/research/index.md`](docs/en/research/index.md)
+- **Quick start inside the playbook:** [`docs/en/getting-started/quickstart.md`](docs/en/getting-started/quickstart.md)
+- **Profiling guide:** [`docs/en/guides/profiling-guide.md`](docs/en/guides/profiling-guide.md)
+- **Validation & sanitizers:** [`docs/en/guides/validation.md`](docs/en/guides/validation.md)
 - **Chinese entry:** `README.zh-CN.md` and `docs/zh/`
 
 ## Development workflow

README.zh-CN.md

@@ -42,7 +42,7 @@
 | `examples/03-modern-cpp/` | constexpr、移动语义、reserve、ranges |
 | `examples/04-simd-vectorization/` | 自动向量化、intrinsics、SIMD 封装 |
 | `examples/05-concurrency/` | 原子操作、无锁队列、OpenMP |
-| `docs/` | 双语学习路径、profiling、排障、参考文档 |
+| `docs/` | 双语 Pages 白皮书，覆盖学院 / 架构 / 实践手册 / 参考 / 研究 |
 | `openspec/` | 规格驱动开发流程与 change 历史 |
 
 ## 快速开始
@@ -61,8 +61,9 @@ cmake --build build/release
 ./build/release/examples/02-memory-cache/aos_soa_bench
 ```
 
-如果你想在快速开始之后直接使用 sanitizer，请查看
-[`docs/zh/guides/validation.md`](docs/zh/guides/validation.md)。
+如果你想在快速开始之后进入新的文档主路径，请先查看
+[`docs/zh/playbook/index.md`](docs/zh/playbook/index.md)，再进入
+[`docs/zh/guides/validation.md`](docs/zh/guides/validation.md) 了解 sanitizer 相关说明。
 
 ## 常用验证命令
 
@@ -75,13 +76,18 @@ cmake --preset=tsan && cmake --build build/tsan && ctest --preset=tsan
 cmake --preset=ubsan && cmake --build build/ubsan && ctest --preset=ubsan
 ```
 
-## 文档与学习路径
+## 文档入口
 
 - **文档站：** <https://lessup.github.io/cpp-high-performance-guide/>
-- **快速开始：** `docs/zh/getting-started/quickstart.md`
-- **学习路径：** `docs/zh/guides/learning-path.md`
-- **性能分析指南：** `docs/zh/guides/profiling-guide.md`
-- **验证与 Sanitizer：** `docs/zh/guides/validation.md`
+- **学院：** [`docs/zh/academy/index.md`](docs/zh/academy/index.md)
+- **架构：** [`docs/zh/architecture/index.md`](docs/zh/architecture/index.md)
+- **实践手册：** [`docs/zh/playbook/index.md`](docs/zh/playbook/index.md)
+- **参考：** [`docs/zh/reference/index.md`](docs/zh/reference/index.md)
+- **研究：** [`docs/zh/research/index.md`](docs/zh/research/index.md)
+- **实践手册内的快速开始：** [`docs/zh/getting-started/quickstart.md`](docs/zh/getting-started/quickstart.md)
+- **学习路径：** [`docs/zh/guides/learning-path.md`](docs/zh/guides/learning-path.md)
+- **性能分析指南：** [`docs/zh/guides/profiling-guide.md`](docs/zh/guides/profiling-guide.md)
+- **验证与 Sanitizer：** [`docs/zh/guides/validation.md`](docs/zh/guides/validation.md)
 - **英文入口：** `README.md` 与 `docs/en/`
 
 ## 开发流程

docs/.vitepress/config-helpers.js

@@ -0,0 +1 @@
+export const englishReferenceHub = '/en/reference/'