Skip to content

mcts-cpu-validate docs site PRD

1. Purpose

This PRD defines how the docs-site/ documentation site should be built for mcts-cpu-validate.

The repository already has a detailed specs/ directory for implementation work. That is not the same as an onboarding path. The docs site exists to explain what the project does, why its rules are intentionally simplified, how Rust and Python divide responsibilities, where run data is stored, and how a reader should navigate the repository without guessing.

The goal is not a decorative website. The goal is a durable, readable documentation system that explains the project and does not fork existing Markdown into duplicate copies.

2. Project context

mcts-cpu-validate is not a full Go engine and not a generic deep learning starter kit. It is an experiment system built around a 15x15 simplified Go-like ruleset with a closed loop that includes:

  • Rust for rules, bitboard operations, MCTS, self-play, and game record generation
  • Python for training, checkpoints, metrics, hardware selection, and recovery
  • Run outputs written under data/runs/<run_id>/
  • Tooling that can inspect saved data after the fact

The docs site must explain that flow in plain language. It should not assume that naming a component is enough.

3. Build goals

The documentation site must:

  1. Use a standard MkDocs structure.
  2. Enable i18n with a real language switcher for Chinese and English.
  3. Store Chinese docs under docs-site/docs/zh/.
  4. Store English docs under docs-site/docs/en/.
  5. Put every published page into the MkDocs navigation.
  6. Add a GitHub repository link to the top navigation bar.
  7. Stay DRY by reusing existing repository Markdown through symlinks when possible.
  8. Treat the renamed root README.zh.md as the Chinese root README source.
  9. Separate project explanation, developer-facing notes, and docs-site specifications.
  10. Rename the root Chinese README with mv README.md README.zh.md instead of replacing it with a copied rewrite.
  11. Use patch-based incremental edits for every file change except explicitly required mv rename operations.
  12. Keep build output such as docs-site/site/ in place and add it to .gitignore.

4. Non-goals

This docs-site work must not:

  • modify files under specs/
  • turn specs/ into marketing copy
  • duplicate specs/ into a second parallel source of truth
  • change project code
  • introduce heavy frontend customization unrelated to documentation
  • treat docs-site/site/ build output as authored source content

5. Target readers

The site has three main readers.

5.1 First-time repository readers

They need clear answers to:

  • what this project is
  • why it is not standard Go
  • why the project uses both Rust and Python
  • where outputs are written
  • what to read next

5.2 People who want to run the project

They need to understand:

  • which document is the operational entry point
  • what configuration files control
  • what the training and recovery inputs and outputs are
  • how to tell whether a run looks normal

5.3 Maintainers

They need a Chinese developer section that explains:

  • why specs/ is authoritative but not the public entry point
  • how documentation boundaries are split across root docs, specs/, and docs-site/
  • why the docs site must stay DRY
  • how to add pages without breaking bilingual structure

The English side still needs corresponding entry points, but it does not need to mirror every Chinese maintainer detail line by line.

6. Information architecture

The site should organize content around how the project works, not around raw filenames.

Recommended top-level sections:

  • Home
  • Project overview
  • Running and configuration
  • Data and recovery
  • Developer notes
  • Docs-site specifications

6.1 Home

The home page should answer five questions:

  • What is this project?
  • What problem is it trying to solve?
  • Why is the system split between Rust and Python?
  • How does the docs site relate to the root documents?
  • What should the reader open next?

6.2 Project overview

This section should explain the simplified rules, training loop, MCTS role, and data recording goals. Each technical topic should cover:

  • what it is
  • why this project needs it
  • how it is used here
  • what goes in
  • what comes out
  • what a normal result looks like

6.3 Running and configuration

This section should complement STEP_BY_STEP_GUIDE and CONFIGURATION without copying them. The site should:

  • explain what each source document is for
  • bring those documents into the site with symlinks
  • add context that helps readers use them

6.4 Data and recovery

This section should explain:

  • why all outputs must live under data/runs/<run_id>/
  • what a run directory contains
  • what checkpoints, game records, and metrics are for
  • what readers should expect to see when a run is healthy

6.5 Developer notes

This section exists for maintainers. It is not a replacement for specs/ and it should not spill into the repository root. It should explain:

  • why the docs site must stay DRY
  • which documents are symlinked and which are written directly in docs-site/docs/
  • why specs/ is not being translated and duplicated here
  • how to keep bilingual navigation stable

6.6 Docs-site specifications

This section should include this PRD and the GitHub Actions PRD. They define how the documentation project is built, not how the training system works.

7. Source strategy

Documentation sources must be routed before they are published.

7.1 Documents to reuse directly

These repository Markdown files should be reused through symlinks instead of copied:

  • root README.zh.md
  • root English README.md
  • CONFIGURATION.md
  • STEP_BY_STEP_GUIDE.md
  • data/README.md

They are already source documents. The docs site should provide navigation and context, not a duplicate copy.

If a source Markdown file lives outside docs-site/, it should still be brought into the docs site through a symlink before any copy-based fallback is considered.

7.2 Documents to author inside the site

These pages should be written directly under docs-site/docs/:

  • home pages
  • project overview
  • rules and training loop explanation
  • data and recovery explanation
  • developer notes
  • docs-site specification guide pages

These pages exist to explain, not to mirror existing text.

7.3 Documents that should not be duplicated

The specs/ directory can be referenced and explained, but it should not be copied into docs-site/ as another working copy. The Chinese developer notes can tell readers which specs matter and why.

8. Bilingual requirements

8.1 Language directories

Use:

docs-site/docs/zh/
docs-site/docs/en/

8.2 Naming

  • Chinese pages use .zh.md
  • English pages use .md without an en suffix

8.3 Consistency

Consistency means:

  • shared navigation structure
  • corresponding entry points in both languages
  • enough context on the English side for navigation and maintenance
  • a Chinese page and an English page for every documentation topic that appears in site navigation

English pages do not need to mirror every Chinese maintainer-only detail, but they cannot be missing entirely.

9. MkDocs and i18n requirements

9.1 Framework

Use standard MkDocs.

9.2 Multilingual support

Use a mature i18n plugin and expose a visible language switcher.

9.3 Navigation

Every published document must appear in navigation, including:

  • authored explanatory pages
  • symlinked repository docs
  • docs-site PRDs

The top navigation must include:

  • GitHub repository: https://github.com/billzi2016/mcts-cpu-validate

The main README documents must include:

  • docs site URL: https://billzi2016.github.io/mcts-cpu-validate/

10. GitHub Pages deployment boundary

The site is expected to publish at:

https://billzi2016.github.io/mcts-cpu-validate/

That means the docs configuration should align with:

  • site_url set to that address
  • a deployment workflow triggered only by docs-related changes
  • a build output compatible with GitHub Pages

11. Writing requirements

The writing must explain itself.

Before authoring documentation, read /Users/bizi/Desktop/humanizer-skill and apply its constraints against AI-sounding filler, empty enthusiasm, concept stacking, and vague phrasing.

For each important technical topic, the docs should answer:

  1. What is it?
  2. Why does this project need it?
  3. How is it used here?
  4. What are the inputs?
  5. What are the outputs?
  6. How can a reader tell whether the result looks normal?

Avoid pages that only name terms such as MCTS, bitboard, or three-slot checkpoints without explaining what they mean in this repository.

The tone should also avoid:

  • inflated claims
  • concept stacking without explanation
  • synthetic enthusiasm
  • vague AI-sounding filler
  • descriptions of what exists without why it exists
  • words that expose writing intent, such as "science popularization", "HR", or "interview"

If a passage exists mainly to explain behavior, boundaries, inputs, outputs, or how to judge a normal result, it belongs under docs-site/docs/ instead of the repository root.

12. Acceptance criteria

This PRD is satisfied when:

  1. docs-site/ is a valid MkDocs project.
  2. Chinese and English language switching works.
  3. Every published document appears in navigation.
  4. Existing authority Markdown is reused through symlinks instead of copied.
  5. Chinese developer notes explain the boundary between specs/, root docs, and docs-site/.
  6. Both main README files contain the docs site URL.
  7. The top navigation includes the GitHub repository link.
  8. The content explains the project instead of listing filenames and jargon.

13. Explicit instructions for implementation

When implementing this PRD:

  • do not modify specs/
  • do not create a second source of truth
  • prefer symlinks to copies
  • keep maintainer-facing Chinese guidance under docs-site/docs/zh/
  • keep English entry pages in place even when details are lighter
  • rename the root README with mv README.md README.zh.md
  • use patch-based edits for everything except the explicitly required mv README.md README.zh.md
  • do not replace patch-based edits with whole-file rewrites
  • do not delete docs-site/site/, and add it to .gitignore