KraHsu · May 13, 2026 · May 13, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -23,6 +23,20 @@ GeneLab targets Python `>=3.12`. Write modern code only; do not add compatibilit
 - **`collections.abc` over `typing`** for `Callable`, `Iterable`, `Iterator`, `Sequence`, `Mapping`, etc.
 - **Whitelisted `typing` imports.** Only `Any`, `cast`, `Protocol`, `Literal`, `Final`, `Annotated`, `TYPE_CHECKING`, `runtime_checkable`, `get_args`, `get_origin`, `get_type_hints` are expected to appear. Anything else is suspect.
 
+## Documentation conventions
+
+Docs live under `docs/` and are built by MkDocs Material with the `mkdocs-static-i18n` plugin. Every content page exists in two languages with the `.en.md` / `.zh.md` suffix; the rendered site serves English at `/` and 中文 at `/zh/`. The following rules apply to both languages.
+
+- **Bilingual parity is mandatory.** When a `.en.md` page changes, its `.zh.md` counterpart must change in the same commit. The two files must agree on heading count and order, code blocks (variable placeholders aside), table shape, admonitions, and `See also` entries.
+- **Section headings are noun or gerund phrases**, never imperative directives. Use `Scaffold output` / `生成的目录结构`, `Running a task` / `运行任务` — not `Play a task` / `运行一个任务`. Same rule for `## See also` (not `## Next steps`).
+- **No chatty openers.** Avoid first-paragraph meta-narration about what the page is about (`This walks through…`, `本节走通…`, `In this guide we'll…`). Open with the substantive statement.
+- **Avoid second-person.** Drop `you` / `你` / `您`. Prefer no subject (imperative steps for operational commands) or noun-based phrasing (`The CLI exposes…` / `CLI 暴露…`).
+- **No mid-paragraph cross-page jumps.** Do not insert `see [Foo](...)` / `详见 [Foo](...)` inside body text. Collect related-page pointers in a single `## See also` block at the end of the page, capped at **≤ 3 entries** indexing genuinely supplementary reading (not the next required step — that is the left-hand nav's job).
+- **Admonitions over blockquotes.** Use `!!! warning "Title"` / `!!! tip "Title"` / `!!! note "Title"` for callouts; reserve `>` blockquotes for actual quotations.
+- **Stable explicit anchors** for headings that contain non-ASCII characters, numbered prefixes, or wording likely to change. Append `{ #stable-id }` to the heading, e.g. `## 5. Advanced: end-to-end RL on Unitree G1 { #unitree-g1 }`. Cross-link to the slug, not the auto-generated one.
+- **CJK + ASCII spacing in `.zh.md`.** Leave one space between Chinese characters and adjacent ASCII words, numbers, or inline code (`运行 \`uv sync\``, not `运行\`uv sync\``).
+- **`mkdocs build --strict` must pass.** Install the docs extra with `uv sync --extra docs` and run `uv run mkdocs build --strict` before opening a doc-touching PR. The flag fails the build on any unresolved relative link or anchor.
+
 ## Checks before opening a PR
 
 ```bash

diff --git a/README.md b/README.md
@@ -1,17 +1,24 @@
 # GeneLab
 
+[中文](docs/README_CN.md)|EN
+
 GeneLab is an Isaac Lab-inspired API for RL and robotics research powered by
 [Genesis](https://github.com/Genesis-Embodied-AI/Genesis). It keeps the familiar shape of registered
 robots, environments, tasks, manager-based MDP configuration, and CLI dispatch, while using Genesis
 as the simulation backend.
 
+- [Documentation](https://krahsu.github.io/GeneLab/) — full guides, CLI reference, concepts,
+  and auto-generated API docs. Bilingual (English default, 中文 at `/zh/`).
+- [Examples](examples/README.md) — bundled tasks, demo scripts, config overrides, and downstream
+  project integration.
+
 ## Goals
 
-- Provide small registries for robots, environments, and tasks.
-- Keep core API layers separate from example assets and demo scripts.
-- Use manager-style config hooks for actions, observations, rewards, events, and terminations.
-- Keep Genesis backend integration explicit and easy to extend.
-- Support downstream robotics projects through a stable package layout and CLI.
+- Small registries for robots, environments, and tasks.
+- Core API layers separated from example assets and demo scripts.
+- Manager-style config hooks for actions, observations, rewards, events, and terminations.
+- Explicit, easy-to-extend Genesis backend integration.
+- A stable package layout and CLI for downstream robotics projects.
 
 ## Requirements
 
@@ -20,7 +27,7 @@ as the simulation backend.
 
 ## Setup
 
-Run setup from the repository root:
+From the repository root:
 
 ```bash
 uv sync
@@ -32,28 +39,26 @@ the dependencies pinned by `uv.lock`. `uv run ...` runs commands inside that env
 `genelab` command works only after `.venv` is activated or GeneLab is installed into the active
 Python environment.
 
-If your workflow needs PyTorch directly, install exactly one backend extra:
+Pick exactly one `torch-*` extra — they are **mutually exclusive**:
 
-```bash
-# CPU-only or non-NVIDIA development machines.
-uv sync --extra torch-cpu
+| Extra | Hardware target |
+|-------|----------------|
+| `torch-cpu` | CPU-only or non-NVIDIA development machines. |
+| `torch-cu126` | NVIDIA, CUDA 12.6 driver. |
+| `torch-cu128` | NVIDIA, CUDA 12.8 driver. |
+| `torch-cu130` | NVIDIA, CUDA 13.0 driver. |
 
-# NVIDIA machines; choose the CUDA wheel supported by your driver.
-uv sync --extra torch-cu126
-uv sync --extra torch-cu128
-uv sync --extra torch-cu130
+```bash
+uv sync --extra torch-cpu        # one of the above
 ```
 
 > **PyTorch version requirement.** Genesis requires `torch>=2.8.0` — older builds emit a
 > `'torch<2.8.0' is not supported` warning at import time and may break Genesis runtime
 > assumptions. All `torch-*` extras pin `torch>=2.8.0`, so `uv sync` will pull a compatible
 > wheel automatically. PyTorch only publishes 2.8+ wheels on the `cpu`, `cu126`, `cu128`, and
 > `cu130` indices; older CUDA flavours (`cu118` / `cu121` / `cu124`) are intentionally not
-> offered as extras. If you already have an older `torch` in your environment, run
-> `uv sync --reinstall-package torch --extra torch-cuXXX` to refresh it.
-
-If you are not sure which CUDA build to use, check `nvidia-smi` and follow the PyTorch installation
-selector for your platform.
+> offered as extras. An older `torch` already in the environment can be refreshed with
+> `uv sync --reinstall-package torch --extra torch-cuXXX`.
 
 Create project-local cache folders used by Genesis/Quadrants and Matplotlib:
 
@@ -64,7 +69,6 @@ uv run genelab cache
 ## CLI
 
 ```bash
-uv run genelab
 uv run genelab --help
 uv run genelab list robots
 uv run genelab list envs
@@ -73,30 +77,22 @@ uv run genelab list tasks
 
 ## Core API
 
-- `genelab.registry`: registries, registration helpers, and extension loading.
-- `genelab.configs`: reusable dataclass configs, including `ManagerBasedEnvCfg` and `TaskCfg`.
-- `genelab.lab`: public API facade for registry and manager-based environment primitives.
-- `genelab.envs`, `genelab.robots`, `genelab.tasks`: thin core namespaces for registry helpers.
+- `genelab.registry` — registries, registration helpers, and extension loading.
+- `genelab.configs` — reusable dataclass configs, including `ManagerBasedEnvCfg` and `TaskCfg`.
+- `genelab.lab` — public API facade for registry and manager-based environment primitives.
+- `genelab.envs`, `genelab.robots`, `genelab.tasks` — thin core namespaces for registry helpers.
 - `genelab.actuator`, `genelab.entity`, `genelab.scene`, `genelab.sensor`, `genelab.terrains`,
-  and `genelab.rl`: extension namespaces for robotics research code.
+  and `genelab.rl` — extension namespaces for robotics research code.
 
-Downstream projects should live in their own Python packages and register robots, environments, and
-tasks through GeneLab's registry and extension hooks. See
-[`examples/external_project/`](examples/external_project/README.md) for a minimal package, or start
-one with:
+Downstream projects live in their own Python packages and register robots, environments, and
+tasks through GeneLab's registry and extension hooks. The minimal template lives at
+[`examples/external_project/`](examples/external_project/README.md); a fresh scaffold is
+generated with:
 
 ```bash
 uv run genelab project new my_robot_project
 ```
 
-## Documentation
-
-- [Documentation site](https://krahsu.github.io/GeneLab/) — full guides, CLI reference, concepts,
-  and auto-generated API docs. Bilingual (English default, 中文 at `/zh/`).
-- [Examples](examples/README.md): bundled tasks, demo scripts, config overrides, and downstream
-  project integration.
-- [中文 README](docs/README_CN.md): concise Chinese project overview.
-
 ## Verification
 
 ```bash

diff --git a/docs/README_CN.md b/docs/README_CN.md
@@ -1,101 +1,13 @@
 # GeneLab
 
-> **本文已迁移至 [文档站点（中文）](https://krahsu.github.io/GeneLab/zh/)。**
-> 完整中文文档（CLI 参考、核心概念、API 自动生成参考）请见站点；本文件保留以兼容旧链接。
+中文 | [EN](../README.md)
 
 GeneLab 是一个面向强化学习与机器人研究的 Isaac Lab 风格 API，由
-[Genesis](https://github.com/Genesis-Embodied-AI/Genesis) 提供仿真后端。它保留了机器人、
-环境、任务注册，manager-based MDP 配置，以及 CLI 调度这些常见组织方式。
+[Genesis](https://github.com/Genesis-Embodied-AI/Genesis) 提供仿真后端。注册机器人、环境、
+任务，manager-based MDP 配置，以及 CLI 调度等组织方式与上游保持一致。
 
-## 目标
+- 完整文档（中文）：<https://krahsu.github.io/GeneLab/zh/>。
+- 示例与下游项目集成：[`examples/`](../examples/README.md)。
 
-- 提供小型机器人、环境和任务注册表。
-- 将核心 API 层与示例资产、演示脚本分离。
-- 使用 manager 风格配置钩子组织 actions、observations、rewards、events 和 terminations。
-- 保持 Genesis 后端集成显式，便于扩展。
-- 通过稳定的包结构和 CLI 支持下游机器人研究项目。
-
-## 要求
-
-- Python 3.12 或更新版本。
-- 使用 [uv](https://docs.astral.sh/uv/) 管理依赖。
-
-## 设置
-
-在仓库根目录运行：
-
-```bash
-uv sync
-uv run genelab --help
-```
-
-`uv sync` 会创建项目虚拟环境，从当前 checkout 安装 GeneLab，并安装 `uv.lock` 锁定的依赖。
-`uv run ...` 会在该环境中运行命令。裸 `genelab` 命令只有在已激活 `.venv`，或 GeneLab 已安装到
-当前 Python 环境后才可用。
-
-请只安装一个 backend extra 的 PyTorch：
-
-```bash
-# 仅 CPU 或非 NVIDIA 开发机器。
-uv sync --extra torch-cpu
-
-# NVIDIA 机器；选择驱动支持的 CUDA wheel。
-uv sync --extra torch-cu118
-uv sync --extra torch-cu121
-uv sync --extra torch-cu124
-uv sync --extra torch-cu126
-uv sync --extra torch-cu128
-uv sync --extra torch-cu130
-```
-
-如果不确定应使用哪个 CUDA build，请用 `nvidia-smi` 查看驱动，并参考 PyTorch 官方安装选择器。
-
-创建 Genesis/Quadrants 和 Matplotlib 使用的项目本地缓存目录：
-
-```bash
-uv run genelab cache
-```
-
-## CLI
-
-```bash
-uv run genelab
-uv run genelab --help
-uv run genelab list robots
-uv run genelab list envs
-uv run genelab list tasks
-```
-
-## 核心 API
-
-- `genelab.registry`：注册表、注册 helper 和扩展加载。
-- `genelab.configs`：可复用 dataclass 配置，包括 `ManagerBasedEnvCfg` 和 `TaskCfg`。
-- `genelab.lab`：注册表和 manager-based 环境原语的公共 API facade。
-- `genelab.envs`、`genelab.robots`、`genelab.tasks`：注册 helper 的核心命名空间。
-- `genelab.actuator`、`genelab.entity`、`genelab.scene`、`genelab.sensor`、
-  `genelab.terrains` 和 `genelab.rl`：面向机器人研究代码的扩展命名空间。
-
-下游项目应作为独立 Python 包存在，并通过 GeneLab 的 registry 和 extension hooks 注册机器人、
-环境和任务。示例文档见 [examples/README.md](../examples/README.md)。
-可用以下命令创建基础 external project 骨架：
-
-```bash
-uv run genelab project new my_robot_project
-```
-
-## 验证
-
-```bash
-uv run python -c "import genelab; print(genelab.__version__)"
-uv run python -c "from genelab.lab import ManagerBasedEnvCfg; print(ManagerBasedEnvCfg.__name__)"
-uv run python -c "import genesis; print(genesis.__version__)"
-uv run pytest
-uv run ruff check
-uv run pyright
-```
-
-同步任意一个 `torch-*` extra 后，可验证当前 PyTorch build：
-
-```bash
-uv run python -c "import torch; print(torch.__version__, torch.version.cuda)"
-```
+本文件仅作为仓库根目录的中文入口与跳转占位，详细安装、CLI 参考、核心概念、API 自动参考请前往
+上方文档站点。
diff --git a/docs/cli/overview.en.md b/docs/cli/overview.en.md
@@ -1,7 +1,7 @@
 # CLI overview
 
-`genelab` is exposed as a console script via the `genelab = "genelab.cli:main"` entry point. With
-`uv` you typically invoke it as:
+`genelab` is exposed as a console script via the `genelab = "genelab.cli:main"` entry point.
+With `uv` the canonical invocation is:
 
 ```bash
 uv run genelab [GLOBAL OPTIONS] <subcommand> [ARGS]
@@ -21,26 +21,22 @@ uv run genelab [GLOBAL OPTIONS] <subcommand> [ARGS]
 
 ## Global options
 
-These flags work in front of any subcommand:
+The following flags accept any position in front of the subcommand:
 
-- `--version` — print the GeneLab version and exit.
-- `--import MODULE` — eagerly import an extension module before dispatching. Repeatable. Useful
-  when you want to load an extension that does not (yet) ship a `genelab.extensions` entry point.
-- `--no-entry-points` — skip auto-discovery of installed extensions via the `genelab.extensions`
-  entry-point group. Combine with `--import` for fully explicit, reproducible loading.
+| Flag | Effect |
+|------|--------|
+| `--version` | Print the GeneLab version and exit. |
+| `--import MODULE` | Eagerly import an extension module before dispatching. Repeatable. Useful for extensions that do not (yet) ship a `genelab.extensions` entry point. |
+| `--no-entry-points` | Skip auto-discovery via the `genelab.extensions` entry-point group. Combined with `--import`, produces a fully explicit, reproducible loading order. |
 
-## Extension loading
+## Extension discovery order
 
-When the CLI starts, it discovers extensions in this order:
-
-1. **Entry points** under the `genelab.extensions` group (auto, unless `--no-entry-points`).
-2. **Explicit `--import MODULE` flags** (repeatable).
-3. **Programmatic** `genelab.registry.load_extension_module(...)` (used by tests and embedding
-   scripts).
-
-See [Extensions](../concepts/extensions.md) for details on writing a downstream extension.
+On startup the CLI discovers extensions through three pathways, in order: entry-point
+auto-discovery, explicit `--import MODULE` flags, then programmatic
+`genelab.registry.load_extension_module(...)` calls.
 
 ## See also
 
-- [Play and Train](play-train.md) — config override grammar, multi-GPU training, checkpoints.
-- [Project new](project-new.md) — extension package scaffolding.
+- [Play and Train](play-train.md)
+- [Project new](project-new.md)
+- [Extensions](../concepts/extensions.md)
diff --git a/docs/cli/overview.zh.md b/docs/cli/overview.zh.md
@@ -1,6 +1,7 @@
 # CLI 总览
 
-`genelab` 通过 `genelab = "genelab.cli:main"` entry point 暴露为命令行脚本。配合 `uv` 时通常这样调用：
+`genelab` 通过 `genelab = "genelab.cli:main"` entry point 暴露为命令行脚本。配合 `uv` 时
+通常这样调用：
 
 ```bash
 uv run genelab [全局选项] <子命令> [参数]
@@ -20,25 +21,21 @@ uv run genelab [全局选项] <子命令> [参数]
 
 ## 全局选项
 
-放在任何子命令之前：
+下列标志放在任意子命令之前：
 
-- `--version` —— 打印 GeneLab 版本并退出。
-- `--import MODULE` —— 在派发子命令前显式导入一个扩展模块。可重复多次。适合扩展尚未提供
-  `genelab.extensions` entry point 时使用。
-- `--no-entry-points` —— 跳过通过 `genelab.extensions` entry-point 组的自动发现。
-  与 `--import` 搭配可实现完全显式、可复现的扩展加载。
+| 标志 | 作用 |
+|------|------|
+| `--version` | 打印 GeneLab 版本并退出。 |
+| `--import MODULE` | 在派发子命令前显式导入扩展模块。可重复。适合扩展尚未提供 `genelab.extensions` entry point 时使用。 |
+| `--no-entry-points` | 跳过通过 `genelab.extensions` entry-point 组的自动发现。与 `--import` 搭配可实现完全显式、可复现的扩展加载。 |
 
-## 扩展加载顺序
+## 扩展发现顺序
 
-CLI 启动时按如下顺序发现扩展：
+CLI 启动时按三条路径依次发现扩展：entry-point 自动发现、显式 `--import MODULE`、程序内的
+`genelab.registry.load_extension_module(...)`。
 
-1. **Entry points**：`genelab.extensions` 组的自动发现（除非加 `--no-entry-points`）。
-2. **显式 `--import MODULE`**：可多次。
-3. **程序内调用** `genelab.registry.load_extension_module(...)`（测试与嵌入脚本使用）。
+## See also
 
-写下游扩展的详细方式见 [扩展加载](../concepts/extensions.md)。
-
-## 另见
-
-- [play 与 train](play-train.md) —— override 语法、多 GPU 训练、checkpoint。
-- [新建项目](project-new.md) —— 扩展包骨架生成。
+- [play 与 train](play-train.md)
+- [新建项目](project-new.md)
+- [扩展加载](../concepts/extensions.md)