diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d40ec885..192af2ca 100644
--- 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
index 3d6ab37e..cf9add55 100644
--- 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,16 +39,17 @@ 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
@@ -49,11 +57,8 @@ uv sync --extra torch-cu130
 > 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
index ea565f68..13b3120d 100644
--- 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
index b6c40185..7075be49 100644
--- 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
index db60903d..606da55c 100644
--- 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)
diff --git a/docs/cli/play-train.en.md b/docs/cli/play-train.en.md
index afc94058..5890f9b5 100644
--- a/docs/cli/play-train.en.md
+++ b/docs/cli/play-train.en.md
@@ -1,8 +1,8 @@
 # Play and Train
 
-`play` and `train` share a common dispatch path: resolve `<task-id>` against the `TASKS` registry,
-construct its `TaskCfg`, apply any command-line overrides, and hand the configured task to either
-a single rollout (`play`) or the task's RL runner (`train`).
+`play` and `train` share a common dispatch path: resolve `<task-id>` against the `TASKS`
+registry, construct its `TaskCfg`, apply any command-line overrides, and hand the configured
+task to either a single rollout (`play`) or the task's RL runner (`train`).
 
 ## Play
 
@@ -10,9 +10,11 @@ a single rollout (`play`) or the task's RL runner (`train`).
 uv run genelab play <task-id> [SHORT FLAGS] [-- OVERRIDES]
 ```
 
-### Short flags
+Short flags may appear before or after `<task-id>`; the CLI normalises the order internally.
 
-These three short flags rewrite to the corresponding `env.scene.*` overrides:
+### Scene shortcuts
+
+The following short flags rewrite to the corresponding `env.scene.*` overrides:
 
 | Flag | Equivalent override | Effect |
 |------|--------------------|--------|
@@ -20,6 +22,16 @@ These three short flags rewrite to the corresponding `env.scene.*` overrides:
 | `--gpu N` | `env.scene.gpu=N` | Pin the rollout to a single GPU index. |
 | `--steps N` | `env.scene.steps=N` | Cap episode length to `N` steps. |
 
+### Runner flags
+
+When the task carries an RL agent config, `play` also accepts the runner-side flags:
+
+| Flag | Effect |
+|------|--------|
+| `--checkpoint PATH` | Load a trained policy and run inference rollouts. Forces `--agent` to default to `trained`. |
+| `--num-envs N` | Override the registered env count (parallel environments). |
+| `--agent {zero,random,trained}` | Pick the policy source. Defaults to `trained` when `--checkpoint` is set, otherwise `zero`. |
+
 ### Override grammar
 
 After the short flags, any `--<dotted.path> VALUE` argument is parsed as a config override:
@@ -33,13 +45,7 @@ uv run genelab play <task-id> \
 
 The dotted path walks the `TaskCfg` dataclass tree (typically rooted at `env.*`). Values are
 coerced from string using the field's type hint — `int`, `float`, `bool`, `Path`, `list[...]`,
-`tuple[...]` are all supported. See [Configs](../concepts/configs.md) for details on the coercion
-rules and how to handle unions and `Literal`.
-
-!!! tip "Flag ordering"
-    The CLI's `_normalize_run_flags` rewrites `play --steps 5 <task-id> ...` into
-    `play <task-id> --steps 5 ...` so that `argparse.REMAINDER` works. You can keep the short
-    flags before or after the task ID.
+`tuple[...]` are all supported.
 
 ## Train
 
@@ -47,22 +53,21 @@ rules and how to handle unions and `Literal`.
 uv run genelab train <task-id> [SHORT FLAGS] [-- OVERRIDES]
 ```
 
-Train requires the registered task to expose an RL runner (commonly `rsl_rl_lib`). Override syntax
-is identical to `play`. Additional flags:
+Train requires the registered task to expose an RL runner (commonly `rsl_rl_lib`). The
+override syntax is identical to `play`.
 
 | Flag | Effect |
 |------|--------|
-| `--gpus N` | Dispatch via `torchrun` for `N`-process distributed training. |
+| `--gpus N` | Dispatch via `torchrun --standalone --nproc_per_node=N` for distributed training. The task's runner must be `torchrun`-compatible. |
 | `--checkpoint PATH` | Resume training from a checkpoint file. |
+| `--num-envs N` | Override the registered env count (parallel environments). |
+| `--max-iterations N` | Cap the number of PPO learning iterations. |
+| `--seed N` | Override the RNG seed used by the runner. |
+| `--log-dir PATH` | Override the log root; defaults to `logs/<runner>/<experiment>/<run>`. |
+| `--agent {zero,random,trained}` | Forwarded to the runner; mostly useful for diagnostic runs. |
 
-### Multi-GPU
-
-`--gpus N` wraps the underlying training entry point with `torchrun --standalone --nproc_per_node=N`.
-The task's runner must be `torchrun`-compatible; environments that depend on global Genesis state
-typically are.
-
-When `--gpus N` is set, the CLI also masks `CUDA_VISIBLE_DEVICES` to the requested devices so that
-each rank sees a distinct GPU.
+When `--gpus N > 1`, the CLI masks `CUDA_VISIBLE_DEVICES` to the requested devices so each rank
+sees a distinct GPU.
 
 ## Examples
 
@@ -79,5 +84,5 @@ uv run genelab train wuji_hand --checkpoint logs/wuji_hand/run_42/model_100.pt
 
 ## See also
 
-- [Configs](../concepts/configs.md) — full `apply_overrides` semantics.
-- [Registry](../concepts/registry.md) — how tasks resolve from `<task-id>`.
+- [Configs](../concepts/configs.md)
+- [Registry](../concepts/registry.md)
diff --git a/docs/cli/play-train.zh.md b/docs/cli/play-train.zh.md
index aa178704..9e9f3499 100644
--- a/docs/cli/play-train.zh.md
+++ b/docs/cli/play-train.zh.md
@@ -9,9 +9,11 @@
 uv run genelab play <task-id> [短标志] [-- 覆盖项]
 ```
 
-### 短标志
+短标志可放在 `<task-id>` 前或后；CLI 内部会自动整理顺序。
 
-这三个短标志会被改写为对应的 `env.scene.*` override：
+### 场景短标志
+
+下列短标志会被改写为对应的 `env.scene.*` override：
 
 | 标志 | 等价 override | 作用 |
 |------|--------------|------|
@@ -19,6 +21,16 @@ uv run genelab play <task-id> [短标志] [-- 覆盖项]
 | `--gpu N` | `env.scene.gpu=N` | 把 rollout 锁定到指定 GPU。 |
 | `--steps N` | `env.scene.steps=N` | 限制 episode 步数。 |
 
+### 运行时标志
+
+任务携带 RL agent 配置时，`play` 还接受下列 runner 侧标志：
+
+| 标志 | 作用 |
+|------|------|
+| `--checkpoint PATH` | 加载已训练策略并做推理 rollout；会让 `--agent` 默认为 `trained`。 |
+| `--num-envs N` | 覆盖任务注册时的 env 数量（并行环境数）。 |
+| `--agent {zero,random,trained}` | 选择策略来源。设置 `--checkpoint` 时默认 `trained`，否则默认 `zero`。 |
+
 ### Override 语法
 
 短标志之后的任意 `--<dotted.path> VALUE` 都会被当作配置 override：
@@ -30,14 +42,8 @@ uv run genelab play <task-id> \
   --env.observations.include_velocity true
 ```
 
-点路径会沿 `TaskCfg` 的 dataclass 树（通常以 `env.*` 为根）下钻。字符串值按目标字段类型注解
-自动转换 —— 支持 `int`、`float`、`bool`、`Path`、`list[...]`、`tuple[...]`。详细的转换规则
-和如何处理 union 与 `Literal` 见 [配置系统](../concepts/configs.md)。
-
-!!! tip "短标志位置"
-    CLI 内的 `_normalize_run_flags` 会把 `play --steps 5 <task-id> ...` 改写成
-    `play <task-id> --steps 5 ...`，让 `argparse.REMAINDER` 正常工作。短标志放在任务 ID 前后
-    都可以。
+点路径沿 `TaskCfg` 的 dataclass 树（通常以 `env.*` 为根）下钻。字符串值按目标字段类型注解
+自动转换 —— 支持 `int`、`float`、`bool`、`Path`、`list[...]`、`tuple[...]`。
 
 ## train
 
@@ -45,19 +51,20 @@ uv run genelab play <task-id> \
 uv run genelab train <task-id> [短标志] [-- 覆盖项]
 ```
 
-`train` 需要任务暴露一个 RL runner（通常是 `rsl_rl_lib`）。Override 语法与 `play` 一致。额外标志：
+`train` 需要任务暴露一个 RL runner（通常是 `rsl_rl_lib`）。Override 语法与 `play` 一致。
 
 | 标志 | 作用 |
 |------|------|
-| `--gpus N` | 通过 `torchrun` 启动 `N` 进程分布式训练。 |
+| `--gpus N` | 通过 `torchrun --standalone --nproc_per_node=N` 启动分布式训练。任务自身的 runner 必须支持 `torchrun`。 |
 | `--checkpoint PATH` | 从 checkpoint 文件继续训练。 |
+| `--num-envs N` | 覆盖任务注册时的 env 数量（并行环境数）。 |
+| `--max-iterations N` | 限制 PPO 学习迭代次数。 |
+| `--seed N` | 覆盖 runner 使用的随机种子。 |
+| `--log-dir PATH` | 覆盖日志根目录，默认 `logs/<runner>/<experiment>/<run>`。 |
+| `--agent {zero,random,trained}` | 转发给 runner；多用于诊断式运行。 |
 
-### 多 GPU
-
-`--gpus N` 会把底层训练入口包装成 `torchrun --standalone --nproc_per_node=N`。任务自身的 runner
-必须支持 `torchrun`；依赖 Genesis 全局状态的环境通常天然兼容。
-
-设置 `--gpus N` 时 CLI 还会按所选设备掩码 `CUDA_VISIBLE_DEVICES`，让每个 rank 看到独立 GPU。
+当 `--gpus N > 1` 时，CLI 还会按所选设备掩码 `CUDA_VISIBLE_DEVICES`，让每个 rank 看到独立
+GPU。
 
 ## 示例
 
@@ -72,7 +79,7 @@ uv run genelab train wuji_hand --gpus 4 --env.actions.scale 0.3
 uv run genelab train wuji_hand --checkpoint logs/wuji_hand/run_42/model_100.pt
 ```
 
-## 另见
+## See also
 
-- [配置系统](../concepts/configs.md) —— `apply_overrides` 完整语义。
-- [注册表](../concepts/registry.md) —— `<task-id>` 如何解析。
+- [配置系统](../concepts/configs.md)
+- [注册表](../concepts/registry.md)
diff --git a/docs/cli/project-new.en.md b/docs/cli/project-new.en.md
index 9483fd5d..63b43fee 100644
--- a/docs/cli/project-new.en.md
+++ b/docs/cli/project-new.en.md
@@ -1,7 +1,7 @@
 # Project new
 
-`genelab project new` scaffolds a downstream extension package — a self-contained Python project
-that registers robots, environments, and tasks into GeneLab's global registries.
+`genelab project new` scaffolds a downstream extension package — a self-contained Python
+project that registers robots, environments, and tasks into GeneLab's global registries.
 
 ## Usage
 
@@ -18,19 +18,19 @@ uv run genelab project new my_robot_project
 | `--task-id ID` | `<package>/<name>-v0` | The first task ID registered by the scaffold. |
 | `--force` | off | Overwrite an existing target directory. Use with care. |
 
-## What it generates
+## Scaffold output
 
 ```
 my_robot_project/
-├── pyproject.toml          # with [project.entry-points."genelab.extensions"]
+├── pyproject.toml        # with [project.entry-points."genelab.extensions"]
 ├── README.md
 └── src/
     └── my_robot_project/
-        ├── __init__.py     # exposes register() entry-point callable
-        ├── config.py       # task-specific dataclass plugged into TaskCfg.env
-        ├── robots.py       # robot registrations
-        ├── envs.py         # environment registrations
-        └── tasks.py        # task registration (using --task-id)
+        ├── __init__.py   # exposes register() entry-point callable
+        ├── config.py     # task-specific dataclass plugged into TaskCfg.env
+        ├── robots.py     # robot registrations
+        ├── envs.py       # environment registrations
+        └── tasks.py      # task registration (using --task-id)
 ```
 
 The generated `pyproject.toml` declares:
@@ -40,20 +40,19 @@ The generated `pyproject.toml` declares:
 my_robot_project = "my_robot_project:register"
 ```
 
-Once installed (`uv pip install -e ./my_robot_project`), GeneLab discovers the extension on next
-invocation without any `--import` flag.
+Once installed (`uv pip install -e ./my_robot_project`), the extension is discovered on the
+next CLI invocation without any `--import` flag.
 
-## After scaffolding
+## Post-scaffold workflow
 
 ```bash
 cd my_robot_project
-uv pip install -e .          # install your extension into the GeneLab venv
+uv pip install -e .          # install the extension into the GeneLab venv
 uv run genelab list tasks    # confirm the new task ID shows up
 uv run genelab play <task-id> --vis
 ```
 
 ## See also
 
-- [Extensions](../concepts/extensions.md) — the three extension-loading pathways and how to keep
-  loading idempotent.
-- [Configs](../concepts/configs.md) — how to type the `TaskCfg.env` field in your `config.py`.
+- [Extensions](../concepts/extensions.md)
+- [Configs](../concepts/configs.md)
diff --git a/docs/cli/project-new.zh.md b/docs/cli/project-new.zh.md
index 64d9d18d..4e0c3ec6 100644
--- a/docs/cli/project-new.zh.md
+++ b/docs/cli/project-new.zh.md
@@ -1,6 +1,6 @@
 # 新建项目
 
-`genelab project new` 会生成一个下游扩展包骨架 —— 一个独立 Python 项目，把机器人、环境、
+`genelab project new` 生成一个下游扩展包骨架 —— 一个独立 Python 项目，把机器人、环境、
 任务注册进 GeneLab 的全局注册表。
 
 ## 用法
@@ -18,19 +18,19 @@ uv run genelab project new my_robot_project
 | `--task-id ID` | `<package>/<name>-v0` | 骨架注册的首个任务 ID。 |
 | `--force` | 关闭 | 已存在目标目录时覆盖。慎用。 |
 
-## 生成的内容
+## 生成的目录结构
 
 ```
 my_robot_project/
-├── pyproject.toml          # 含 [project.entry-points."genelab.extensions"]
+├── pyproject.toml        # 含 [project.entry-points."genelab.extensions"]
 ├── README.md
 └── src/
     └── my_robot_project/
-        ├── __init__.py     # 暴露 register() entry-point 调用入口
-        ├── config.py       # 接入 TaskCfg.env 的任务专属 dataclass
-        ├── robots.py       # 机器人注册
-        ├── envs.py         # 环境注册
-        └── tasks.py        # 任务注册（使用 --task-id）
+        ├── __init__.py   # 暴露 register() entry-point 调用入口
+        ├── config.py     # 接入 TaskCfg.env 的任务专属 dataclass
+        ├── robots.py     # 机器人注册
+        ├── envs.py       # 环境注册
+        └── tasks.py      # 任务注册（使用 --task-id）
 ```
 
 生成的 `pyproject.toml` 声明：
@@ -40,10 +40,10 @@ my_robot_project/
 my_robot_project = "my_robot_project:register"
 ```
 
-安装后（`uv pip install -e ./my_robot_project`），GeneLab 下次启动会自动发现该扩展，
-无需任何 `--import` 标志。
+安装后（`uv pip install -e ./my_robot_project`），扩展在下次启动 CLI 时被自动发现，无需任何
+`--import` 标志。
 
-## 生成之后
+## 后续步骤
 
 ```bash
 cd my_robot_project
@@ -52,7 +52,7 @@ uv run genelab list tasks    # 确认新任务 ID 出现
 uv run genelab play <task-id> --vis
 ```
 
-## 另见
+## See also
 
-- [扩展加载](../concepts/extensions.md) —— 三种扩展加载路径，以及保持加载幂等的方式。
-- [配置系统](../concepts/configs.md) —— `config.py` 里 `TaskCfg.env` 字段的类型化方法。
+- [扩展加载](../concepts/extensions.md)
+- [配置系统](../concepts/configs.md)
diff --git a/docs/concepts/configs.en.md b/docs/concepts/configs.en.md
index 76a1aea3..0889c9be 100644
--- a/docs/concepts/configs.en.md
+++ b/docs/concepts/configs.en.md
@@ -1,6 +1,6 @@
 # Configs
 
-GeneLab's config system is a small dataclass hierarchy under `genelab.configs`:
+The config system is a small dataclass hierarchy under `genelab.configs`:
 
 ```
 TaskCfg
@@ -15,12 +15,12 @@ TaskCfg
 ```
 
 `TaskCfg.env` is typed `object` on purpose — downstream extensions plug their own env dataclass
-into it without touching core. Most users will subclass `ManagerBasedEnvCfg` for their `env` field.
+into it without touching core. Most users subclass `ManagerBasedEnvCfg` for their `env` field.
 
 ## apply_overrides
 
-The headline function is `apply_overrides(cfg, dict)`, which parses dotted paths and applies them
-to the config tree:
+The headline function is `apply_overrides(cfg, dict)`, which parses dotted paths and applies
+them to the config tree:
 
 ```python
 from genelab.configs import apply_overrides
@@ -35,7 +35,8 @@ apply_overrides(cfg, {
 
 ### Type coercion
 
-Strings are coerced using the field's type hint on the target dataclass. Supported targets:
+String values are coerced using the field's type hint on the target dataclass. Supported
+targets:
 
 | Hint | Accepted strings |
 |------|------------------|
@@ -47,16 +48,16 @@ Strings are coerced using the field's type hint on the target dataclass. Support
 | `tuple[T, ...]` | comma-separated, each element coerced as `T` |
 | `str` | identity |
 
-If a path doesn't resolve to a known field or the value can't be coerced, `apply_overrides` raises
-a descriptive error early — failures surface at config build time, not at simulation runtime.
+When a path does not resolve to a known field or a value cannot be coerced, `apply_overrides`
+raises a descriptive error at config build time, not at simulation runtime.
 
-### CLI integration
+### Forwarding from the CLI
 
-The `play` / `train` subcommands forward every `--<a.b.c> VALUE` flag into `apply_overrides`. The
-three short flags (`--vis`, `--gpu`, `--steps`) rewrite to `env.scene.{vis,gpu,steps}` overrides
-before forwarding. See [Play and Train](../cli/play-train.md).
+The `play` / `train` subcommands forward every `--<a.b.c> VALUE` flag into `apply_overrides`.
+The three scene shortcuts (`--vis`, `--gpu`, `--steps`) rewrite to `env.scene.{vis,gpu,steps}`
+overrides before forwarding.
 
-## API
+## See also
 
-The full auto-generated reference for `genelab.configs` is on the
-[API Reference](../api/reference.md) page.
+- [Play and Train](../cli/play-train.md)
+- [API Reference](../api/reference.md)
diff --git a/docs/concepts/configs.zh.md b/docs/concepts/configs.zh.md
index 97b94634..ff94200d 100644
--- a/docs/concepts/configs.zh.md
+++ b/docs/concepts/configs.zh.md
@@ -15,7 +15,7 @@ TaskCfg
 ```
 
 `TaskCfg.env` 类型刻意写成 `object` —— 下游扩展无需触碰核心即可接入自己的 env dataclass。
-大多数用户会把 `ManagerBasedEnvCfg` 的子类放进 `env` 字段。
+大多数情况下 `env` 字段会是 `ManagerBasedEnvCfg` 的子类。
 
 ## apply_overrides
 
@@ -46,15 +46,15 @@ apply_overrides(cfg, {
 | `tuple[T, ...]` | 逗号分隔，每个元素按 `T` 转换 |
 | `str` | 原样 |
 
-如果点路径无法解析到已知字段，或值无法转换，`apply_overrides` 会在配置构造期就抛出明确错误，
+当点路径无法解析到已知字段，或值无法转换时，`apply_overrides` 在配置构造期就抛出明确错误，
 避免错误延后到仿真运行时才暴露。
 
-### CLI 集成
+### CLI 转发路径
 
-`play` / `train` 把每个 `--<a.b.c> VALUE` 标志转发给 `apply_overrides`。三个短标志
+`play` / `train` 把每个 `--<a.b.c> VALUE` 标志转发给 `apply_overrides`。三个场景短标志
 （`--vis`、`--gpu`、`--steps`）在转发前被改写为 `env.scene.{vis,gpu,steps}`。
-详见 [play 与 train](../cli/play-train.md)。
 
-## API
+## See also
 
-`genelab.configs` 的完整自动生成参考见 [API 参考](../api/reference.md)。
+- [play 与 train](../cli/play-train.md)
+- [API 参考](../api/reference.md)
diff --git a/docs/concepts/extensions.en.md b/docs/concepts/extensions.en.md
index 2c247428..13999d62 100644
--- a/docs/concepts/extensions.en.md
+++ b/docs/concepts/extensions.en.md
@@ -1,23 +1,24 @@
 # Extensions
 
 GeneLab core ships **no** robots, environments, or tasks. All content lives in downstream
-extension packages. The CLI discovers extensions through three pathways, in order of preference:
+extension packages. The CLI discovers extensions through three pathways, in order of
+preference.
 
 ## 1. Entry-point auto-discovery (recommended)
 
-Declare in your extension's `pyproject.toml`:
+Declare in the extension's `pyproject.toml`:
 
 ```toml
 [project.entry-points."genelab.extensions"]
 my_robot_project = "my_robot_project:register"
 ```
 
-The CLI auto-imports every entry point in the `genelab.extensions` group on startup. `register()`
-is a no-argument callable inside your package that performs the actual `ROBOTS.register(...)` /
-`ENVS.register(...)` / `TASKS.register(...)` calls (or simply imports modules that perform them
-as a side effect).
+The CLI auto-imports every entry point in the `genelab.extensions` group on startup.
+`register()` is a no-argument callable at the package top level that performs the actual
+`ROBOTS.register(...)` / `ENVS.register(...)` / `TASKS.register(...)` calls (or simply imports
+modules that perform them as a side effect).
 
-This is the pathway `genelab project new` wires up for you.
+This is the pathway `genelab project new` wires up automatically.
 
 ## 2. Explicit `--import`
 
@@ -25,12 +26,12 @@ This is the pathway `genelab project new` wires up for you.
 uv run genelab --import my_pkg.module1 --import my_pkg.module2 list tasks
 ```
 
-Repeatable. Useful when:
+Repeatable. Common uses:
 
 - The extension does not (yet) ship a `genelab.extensions` entry point.
-- You want a fully explicit, reproducible loading order (combine with `--no-entry-points`).
-- You're iterating on a not-yet-installed package and need to add its source directory to
-  `sys.path` ad-hoc (the CLI also adds the current working directory to `sys.path`).
+- A fully explicit, reproducible loading order is required (combine with `--no-entry-points`).
+- Iterating on a not-yet-installed package while ad-hoc-adding its source directory to
+  `sys.path` (the CLI also adds the current working directory to `sys.path`).
 
 ## 3. Programmatic
 
@@ -40,8 +41,8 @@ from genelab.registry import load_extension_module
 load_extension_module("my_pkg.module")
 ```
 
-Used by tests and embedding scripts. The same idempotency guard applies, so calling it after the
-CLI has already auto-discovered the same module is a no-op.
+Used by tests and embedding scripts. The same idempotency guard applies, so calling it after
+the CLI has already auto-discovered the same module is a no-op.
 
 ## Disabling auto-discovery
 
@@ -49,15 +50,16 @@ CLI has already auto-discovered the same module is a no-op.
 uv run genelab --no-entry-points --import my_pkg list tasks
 ```
 
-This is the most reproducible setup — only the modules you explicitly named are loaded.
+This is the most reproducible setup — only the modules explicitly named are loaded.
 
-## Canonical example
+## Reference extension
 
-`examples/genelab_examples/` is the reference shape: a `pyproject.toml` with the entry point,
-a top-level `register()` callable, and `config.py` / `robots.py` / `envs.py` / `tasks.py` modules.
-`tests/fake_extension.py` is the same shape stripped to bare minimum for the test suite.
+`examples/genelab_examples/` is the reference shape: a `pyproject.toml` with the entry point, a
+top-level `register()` callable, and `config.py` / `robots.py` / `envs.py` / `tasks.py`
+modules. `tests/fake_extension.py` is the same shape stripped to bare minimum for the test
+suite.
 
 ## See also
 
-- [Project new](../cli/project-new.md) — scaffold a new extension package.
-- [Registry](registry.md) — what `register()` actually does.
+- [Project new](../cli/project-new.md)
+- [Registry](registry.md)
diff --git a/docs/concepts/extensions.zh.md b/docs/concepts/extensions.zh.md
index 6c447969..beebfb35 100644
--- a/docs/concepts/extensions.zh.md
+++ b/docs/concepts/extensions.zh.md
@@ -1,7 +1,7 @@
 # 扩展加载
 
-GeneLab 核心**不**自带机器人、环境、任务，所有内容都由下游扩展包提供。CLI 通过三条路径发现
-扩展，按以下优先级：
+GeneLab 核心**不**自带机器人、环境、任务，所有内容由下游扩展包提供。CLI 通过三条路径发现
+扩展，按以下优先级。
 
 ## 1. Entry-point 自动发现（推荐）
 
@@ -16,7 +16,7 @@ CLI 启动时自动 import `genelab.extensions` 组下的每个 entry point。`r
 可调用，位于扩展包顶层，负责真正调用 `ROBOTS.register(...)` / `ENVS.register(...)` /
 `TASKS.register(...)`（或仅 import 一些以副作用方式注册的模块）。
 
-这条路径正是 `genelab project new` 默认替你接好的。
+这条路径正是 `genelab project new` 默认接好的。
 
 ## 2. 显式 `--import`
 
@@ -24,11 +24,11 @@ CLI 启动时自动 import `genelab.extensions` 组下的每个 entry point。`r
 uv run genelab --import my_pkg.module1 --import my_pkg.module2 list tasks
 ```
 
-可重复。适用场景：
+可重复。常见场景：
 
 - 扩展尚未提供 `genelab.extensions` entry point。
-- 想要完全显式、可复现的加载顺序（搭配 `--no-entry-points`）。
-- 调试尚未安装的包，需要把源码目录临时塞进 `sys.path`（CLI 也会把当前工作目录加入 `sys.path`）。
+- 需要完全显式、可复现的加载顺序（搭配 `--no-entry-points`）。
+- 调试尚未安装的包，临时把源码目录塞进 `sys.path`（CLI 也会把当前工作目录加入 `sys.path`）。
 
 ## 3. 程序内调用
 
@@ -38,8 +38,8 @@ from genelab.registry import load_extension_module
 load_extension_module("my_pkg.module")
 ```
 
-测试与嵌入脚本使用。同样的幂等守卫生效，因此即使 CLI 已经自动发现过同一模块，再调用一次
-也是 no-op。
+测试与嵌入脚本使用。同样的幂等守卫生效，即使 CLI 已经自动发现过同一模块，再调用一次也是
+no-op。
 
 ## 关闭自动发现
 
@@ -47,15 +47,15 @@ load_extension_module("my_pkg.module")
 uv run genelab --no-entry-points --import my_pkg list tasks
 ```
 
-这是最可复现的组合 —— 只加载你显式命名的模块。
+这是最可复现的组合 —— 只加载显式命名的模块。
 
-## 参考形态
+## 参考扩展
 
-`examples/genelab_examples/` 是参考形态：`pyproject.toml` 带 entry point、顶层有 `register()`
-可调用、并提供 `config.py` / `robots.py` / `envs.py` / `tasks.py`。`tests/fake_extension.py`
-是同样形态但削减到最小，供测试套件使用。
+`examples/genelab_examples/` 是参考形态：`pyproject.toml` 带 entry point、顶层有
+`register()` 可调用、并提供 `config.py` / `robots.py` / `envs.py` / `tasks.py`。
+`tests/fake_extension.py` 是同样形态但削减到最小，供测试套件使用。
 
-## 另见
+## See also
 
-- [新建项目](../cli/project-new.md) —— 生成新的扩展包骨架。
-- [注册表](registry.md) —— `register()` 实际做了什么。
+- [新建项目](../cli/project-new.md)
+- [注册表](registry.md)
diff --git a/docs/concepts/registry.en.md b/docs/concepts/registry.en.md
index 54f4048a..4e057c80 100644
--- a/docs/concepts/registry.en.md
+++ b/docs/concepts/registry.en.md
@@ -9,13 +9,13 @@ GeneLab provides a generic `Registry[T]` plus three module-level singletons expo
 | `ENVS` | Environment factories. |
 | `TASKS` | Task factories (each task pairs an environment with optional runner / agent config). |
 
-## What an entry looks like
+## Entry shape
 
 A registry entry is a 4-tuple: **`(name, description, factory, cfg_type)`**. The `factory` is a
 callable invoked lazily on `get(name)`, so importing a registration site does not eagerly build
 heavy objects.
 
-## Basic usage
+## API surface
 
 ```python
 from genelab.lab import ROBOTS, ENVS, TASKS, TaskCfg
@@ -34,18 +34,17 @@ ROBOTS.register(
 robot = ROBOTS.get("my_robot")
 ```
 
-The `name` is the canonical lookup key; the `description` shows up in `genelab list robots`.
+The `name` is the canonical lookup key; the `description` is what `genelab list robots`
+displays.
 
 ## Idempotent extension loading
 
-The registry module also tracks `_loaded_extension_modules` and `_loaded_entrypoints` sets so that
-repeated calls to load the same extension are no-ops. This matters when a user combines the entry
-point auto-discovery (default) with explicit `--import` flags — both pathways end up calling
+The registry module tracks `_loaded_extension_modules` and `_loaded_entrypoints` sets so that
+repeated calls to load the same extension are no-ops. This matters when entry-point
+auto-discovery (default) combines with explicit `--import` flags — both pathways end up calling
 `load_extension_module`, but the second call is short-circuited.
 
-See [Extensions](extensions.md) for the three pathways and when to use which.
+## See also
 
-## API
-
-The full auto-generated reference for `genelab.registry` lives on the
-[API Reference](../api/reference.md) page.
+- [Extensions](extensions.md)
+- [API Reference](../api/reference.md)
diff --git a/docs/concepts/registry.zh.md b/docs/concepts/registry.zh.md
index 724f9167..bb4ef964 100644
--- a/docs/concepts/registry.zh.md
+++ b/docs/concepts/registry.zh.md
@@ -8,12 +8,12 @@ GeneLab 提供泛型 `Registry[T]` 与三个由 `genelab.lab` 导出的模块级
 | `ENVS` | 环境工厂。 |
 | `TASKS` | 任务工厂（每个任务把环境与可选 runner / agent 配置打包）。 |
 
-## 一个条目长什么样
+## 条目结构
 
 注册条目是一个四元组：**`(name, description, factory, cfg_type)`**。`factory` 是一个可调用，
 只在 `get(name)` 时才会被调用，因此导入注册位点不会立即构造重型对象。
 
-## 基本用法
+## 接口速览
 
 ```python
 from genelab.lab import ROBOTS, ENVS, TASKS, TaskCfg
@@ -32,16 +32,15 @@ ROBOTS.register(
 robot = ROBOTS.get("my_robot")
 ```
 
-`name` 是规范查找键；`description` 会出现在 `genelab list robots` 输出里。
+`name` 是规范查找键；`description` 出现在 `genelab list robots` 输出里。
 
 ## 幂等扩展加载
 
-注册模块还维护 `_loaded_extension_modules` 和 `_loaded_entrypoints` 两个集合，重复加载同一
-扩展会被短路。当用户同时使用 entry point 自动发现（默认）与显式 `--import` 时，这一点尤其
+注册模块维护 `_loaded_extension_modules` 与 `_loaded_entrypoints` 两个集合，重复加载同一
+扩展会被短路。entry-point 自动发现（默认）与显式 `--import` 同时启用时，这一点尤其
 重要 —— 两条路径最终都会调用 `load_extension_module`，但第二次调用直接返回。
 
-三种路径以及何时使用哪种，详见 [扩展加载](extensions.md)。
+## See also
 
-## API
-
-`genelab.registry` 的完整自动生成参考见 [API 参考](../api/reference.md)。
+- [扩展加载](extensions.md)
+- [API 参考](../api/reference.md)
diff --git a/docs/examples/overview.en.md b/docs/examples/overview.en.md
index 778e7b3e..742f1143 100644
--- a/docs/examples/overview.en.md
+++ b/docs/examples/overview.en.md
@@ -5,42 +5,32 @@ tests for the CLI and registry.
 
 ## genelab_examples
 
-Path: [`examples/genelab_examples/`](https://github.com/KraHsu/GeneLab/tree/main/examples/genelab_examples)
-
-The canonical in-tree extension. Two tasks are wired up:
+The canonical in-tree extension, wiring two tasks:
 
 - **`wuji_hand`** — a hand-manipulation task.
 - **`rubiks`** — a Rubik's cube task.
 
-`pyproject.toml` declares the `genelab.extensions` entry point, so this extension is discovered
-automatically when the package is installed (it is also on `pytest`'s `pythonpath` via the
-project's `pyproject.toml`, allowing the tests to import from it without installation).
+`pyproject.toml` declares the `genelab.extensions` entry point, so the extension is discovered
+automatically once installed. The project's `pyproject.toml` also adds the source directory to
+pytest's `pythonpath`, so tests can import from it without installation. Source at
+`examples/genelab_examples/`.
 
 ## unitree
 
-Path: [`examples/unitree/`](https://github.com/KraHsu/GeneLab/tree/main/examples/unitree)
+Two PPO tasks on the Unitree G1 humanoid — velocity tracking and motion imitation — ported from
+mjlab and adapted to Genesis. Same extension shape as `genelab_examples` (entry point,
+`register()`, per-module registration files). Source at `examples/unitree/`.
 
-A robot example focused on Unitree platforms. Same extension shape as `genelab_examples` —
-entry point, `register()`, and per-module registration files.
+A complete hands-on walkthrough (install, train, checkpoint replay, motion imitation) lives in
+[Quickstart §5](../getting-started/quickstart.md#unitree-g1).
 
 ## external_project
 
-Path: [`examples/external_project/`](https://github.com/KraHsu/GeneLab/tree/main/examples/external_project)
-
-A minimal downstream project template. This is what `genelab project new` produces, kept in-tree
-as a reference for the scaffolding output.
-
-## Using an example
-
-```bash
-# Confirm the example tasks are visible.
-uv run genelab list tasks
-
-# Play a task with visualization.
-uv run genelab play wuji_hand --vis --steps 200
-```
+A minimal downstream project template. `genelab project new` produces a project of the same
+shape; this directory is kept in-tree as a reference for the scaffolding output. Source at
+`examples/external_project/`.
 
 ## See also
 
-- [Project new](../cli/project-new.md) — scaffold your own extension.
-- [Extensions](../concepts/extensions.md) — how extensions are discovered and loaded.
+- [Quickstart](../getting-started/quickstart.md)
+- [Extensions](../concepts/extensions.md)
diff --git a/docs/examples/overview.zh.md b/docs/examples/overview.zh.md
index 41722033..b3ebc2b9 100644
--- a/docs/examples/overview.zh.md
+++ b/docs/examples/overview.zh.md
@@ -4,40 +4,30 @@
 
 ## genelab_examples
 
-路径：[`examples/genelab_examples/`](https://github.com/KraHsu/GeneLab/tree/main/examples/genelab_examples)
-
 仓库内的标准扩展，接通两个任务：
 
 - **`wuji_hand`** —— 手部操作任务。
 - **`rubiks`** —— 魔方任务。
 
-`pyproject.toml` 声明了 `genelab.extensions` entry point，因此安装该包后会被自动发现
-（通过项目 `pyproject.toml` 的 `pythonpath` 设置，测试也可以直接 import，而无需安装）。
+`pyproject.toml` 声明了 `genelab.extensions` entry point，因此安装该包后会被自动发现；
+项目 `pyproject.toml` 的 `pythonpath` 设置也让测试可以直接 import 而无需安装。源码位于
+`examples/genelab_examples/`。
 
 ## unitree
 
-路径：[`examples/unitree/`](https://github.com/KraHsu/GeneLab/tree/main/examples/unitree)
+Unitree G1 人形机器人的两个 PPO 任务 —— 速度跟踪与动作模仿，从 mjlab 移植并适配到 Genesis。
+形态与 `genelab_examples` 相同（entry point、`register()`、按模块拆分的注册文件）。源码位于
+`examples/unitree/`。
 
-聚焦 Unitree 平台的机器人示例。形态与 `genelab_examples` 相同 —— entry point、`register()`、
-按模块拆分的注册文件。
+完整动手教程（安装、训练、checkpoint 回放、动作模仿）见
+[快速开始 §5](../getting-started/quickstart.md#unitree-g1)。
 
 ## external_project
 
-路径：[`examples/external_project/`](https://github.com/KraHsu/GeneLab/tree/main/examples/external_project)
-
-下游项目最小模板。`genelab project new` 生成的内容与之结构一致，留在仓库里作为脚手架输出参考。
-
-## 使用示例
-
-```bash
-# 确认示例任务可见。
-uv run genelab list tasks
-
-# 可视化运行一个任务。
-uv run genelab play wuji_hand --vis --steps 200
-```
+下游项目最小模板。`genelab project new` 生成的内容与之结构一致，留在仓库里作为脚手架输出
+参考。源码位于 `examples/external_project/`。
 
-## 另见
+## See also
 
-- [新建项目](../cli/project-new.md) —— 生成自己的扩展包。
-- [扩展加载](../concepts/extensions.md) —— 扩展如何被发现与加载。
+- [快速开始](../getting-started/quickstart.md)
+- [扩展加载](../concepts/extensions.md)
diff --git a/docs/getting-started/installation.en.md b/docs/getting-started/installation.en.md
index d329d21e..364ae1df 100644
--- a/docs/getting-started/installation.en.md
+++ b/docs/getting-started/installation.en.md
@@ -13,47 +13,47 @@ uv run genelab --help
 ```
 
 `uv sync` creates the project virtual environment, installs GeneLab from this checkout, and
-installs the dependencies pinned by `uv.lock`. `uv run ...` runs commands inside that environment.
-A bare `genelab` command works only after `.venv` is activated or GeneLab is installed into the
-active Python environment.
+installs the dependencies pinned by `uv.lock`. `uv run ...` runs commands inside that
+environment. A bare `genelab` command works only after `.venv` is activated or GeneLab is
+installed into the active Python environment.
 
 ## 2. Pick exactly one PyTorch extra
 
-The `torch-*` extras are **mutually exclusive** — pick one that matches your hardware:
+The `torch-*` extras 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
 ```
 
 !!! warning "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.
+    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. An older
+    `torch` already in the environment can be refreshed with
+    `uv sync --reinstall-package torch --extra torch-cuXXX`.
 
-If you are not sure which CUDA build to use, check `nvidia-smi` and follow the PyTorch
-installation selector for your platform.
+Run `nvidia-smi` to confirm the driver version when unsure which CUDA build to use.
 
 ## 3. Initialize project-local caches
 
-Genesis, Quadrants, and Matplotlib all want a writable cache directory. Create the project-local
-folders and the matching environment variables in one shot:
+Genesis, Quadrants, and Matplotlib all require a writable cache directory. The CLI sets up both
+the directory layout and the matching environment variables:
 
 ```bash
 uv run genelab cache
 ```
 
 This sets `XDG_CACHE_HOME` and `MPLCONFIGDIR` under `.cache/`, so the simulator never writes to
-your home directory.
+the user's home directory.
 
 ## 4. Verify
 
@@ -66,10 +66,12 @@ uv run ruff check
 uv run pyright
 ```
 
-After syncing one of the `torch-*` extras, verify the selected PyTorch build:
+Verify the selected PyTorch build:
 
 ```bash
 uv run python -c "import torch; print(torch.__version__, torch.version.cuda)"
 ```
 
-Next: head over to the [Quickstart](quickstart.md) to run a registered task.
+## See also
+
+- [Quickstart](quickstart.md)
diff --git a/docs/getting-started/installation.zh.md b/docs/getting-started/installation.zh.md
index 3be0ab81..4048b438 100644
--- a/docs/getting-started/installation.zh.md
+++ b/docs/getting-started/installation.zh.md
@@ -12,35 +12,36 @@ uv run genelab --help
 ```
 
 `uv sync` 会创建项目虚拟环境，从当前 checkout 安装 GeneLab，并安装 `uv.lock` 锁定的依赖。
-`uv run ...` 会在该环境中运行命令。裸 `genelab` 命令只有在 `.venv` 已激活、或 GeneLab 已安装
+`uv run ...` 在该环境中运行命令。裸 `genelab` 命令只有在 `.venv` 已激活、或 GeneLab 已安装
 到当前 Python 环境后才可用。
 
-## 2. 挑选一个 PyTorch extra（互斥）
+## 2. 挑选一个 PyTorch extra
 
-`torch-*` extras **互斥**，只能挑选一个匹配你的硬件：
+`torch-*` extras **互斥**：
 
-```bash
-# 仅 CPU 或非 NVIDIA 开发机器。
-uv sync --extra torch-cpu
+| Extra | 目标硬件 |
+|-------|---------|
+| `torch-cpu` | 仅 CPU 或非 NVIDIA 开发机器。 |
+| `torch-cu126` | NVIDIA，CUDA 12.6 驱动。 |
+| `torch-cu128` | NVIDIA，CUDA 12.8 驱动。 |
+| `torch-cu130` | NVIDIA，CUDA 13.0 驱动。 |
 
-# NVIDIA 机器，按驱动支持的 CUDA wheel 挑选。
-uv sync --extra torch-cu126
-uv sync --extra torch-cu128
-uv sync --extra torch-cu130
+```bash
+uv sync --extra torch-cpu        # 从上表挑一个
 ```
 
 !!! warning "PyTorch 版本要求"
     Genesis 要求 `torch>=2.8.0`，旧版本在导入时会报 `'torch<2.8.0' is not supported`，并可能
     破坏 Genesis 的运行时假设。所有 `torch-*` extras 都固定 `torch>=2.8.0`，`uv sync` 会自动
     拉取兼容 wheel。PyTorch 只在 `cpu`、`cu126`、`cu128`、`cu130` 索引提供 2.8+ wheel，因此
-    较旧的 CUDA flavour（`cu118` / `cu121` / `cu124`）不再以 extra 形式提供。如果环境里已经
-    存在旧 torch，可用 `uv sync --reinstall-package torch --extra torch-cuXXX` 刷新。
+    较旧的 CUDA flavour（`cu118` / `cu121` / `cu124`）不再以 extra 形式提供。环境里已存在
+    旧 torch 时，可用 `uv sync --reinstall-package torch --extra torch-cuXXX` 刷新。
 
-不确定使用哪个 CUDA build 时，用 `nvidia-smi` 查看驱动，并参考 PyTorch 官方安装选择器。
+不确定使用哪个 CUDA build 时，用 `nvidia-smi` 查看驱动版本。
 
 ## 3. 初始化项目本地缓存
 
-Genesis、Quadrants、Matplotlib 都需要可写缓存目录。一条命令同时创建项目本地目录和环境变量：
+Genesis、Quadrants、Matplotlib 都需要可写缓存目录。CLI 一条命令完成目录与环境变量配置：
 
 ```bash
 uv run genelab cache
@@ -59,10 +60,12 @@ uv run ruff check
 uv run pyright
 ```
 
-同步任意 `torch-*` extra 后，可验证当前 PyTorch build：
+验证当前 PyTorch build：
 
 ```bash
 uv run python -c "import torch; print(torch.__version__, torch.version.cuda)"
 ```
 
-下一步：阅读 [快速开始](quickstart.md) 运行一个已注册任务。
+## See also
+
+- [快速开始](quickstart.md)
diff --git a/docs/getting-started/quickstart.en.md b/docs/getting-started/quickstart.en.md
index 1169bdc2..50776865 100644
--- a/docs/getting-started/quickstart.en.md
+++ b/docs/getting-started/quickstart.en.md
@@ -1,12 +1,14 @@
 # Quickstart
 
-This walks through the shortest path from a fresh `uv sync` to running a registered task.
+This page covers the full path from a synced environment to running a task, scaffolding a new
+downstream project, and reproducing the bundled Unitree G1 PPO example end-to-end.
 
-## List what's available
+## 1. Listing registered content
 
-The core `genelab` package ships with empty registries — robots, environments, and tasks come from
-extension packages. The example extension under `examples/genelab_examples/` is discovered
-automatically because its `pyproject.toml` declares a `genelab.extensions` entry point.
+The core `genelab` package ships empty registries — robots, environments, and tasks are
+contributed by extension packages. The example extension under `examples/genelab_examples/` is
+discovered automatically because its `pyproject.toml` declares a `genelab.extensions` entry
+point.
 
 ```bash
 uv run genelab list robots
@@ -14,18 +16,19 @@ uv run genelab list envs
 uv run genelab list tasks
 ```
 
-If a registry is empty, install or import an extension (see [Extensions](../concepts/extensions.md)).
+An empty registry means no extension has been imported. Install one with `uv pip install`, or
+pass `--import MODULE` on the command line.
 
-## Play a task
+## 2. Running a task
 
 ```bash
 uv run genelab play <task-id>
 ```
 
-The CLI loads the registered factory for `<task-id>`, applies any config overrides you pass on the
-command line, and runs the rollout in the configured Genesis backend.
+The CLI resolves `<task-id>` against the `TASKS` registry, constructs its `TaskCfg`, applies any
+command-line overrides, and runs the rollout in the configured Genesis backend.
 
-Common shortcuts:
+The three scene shortcuts:
 
 ```bash
 uv run genelab play <task-id> --vis           # enable visualization
@@ -33,13 +36,18 @@ uv run genelab play <task-id> --steps 500     # cap the episode length
 uv run genelab play <task-id> --gpu 1         # pin to a single GPU
 ```
 
-For arbitrary overrides, use the dotted `--a.b.c VALUE` syntax — strings are coerced to the type
-declared on the target dataclass field. See [Play and Train](../cli/play-train.md) for the full
-override grammar.
+Arbitrary overrides use the dotted `--a.b.c VALUE` syntax — strings are coerced to the type
+declared on the target dataclass field:
 
-## Train (when a runner exists)
+```bash
+uv run genelab play <task-id> \
+  --env.scene.dt 0.005 \
+  --env.actions.scale 0.5
+```
 
-If a task ships with an RL runner (rsl_rl, etc.), launch training with:
+## 3. Training
+
+When a task ships an RL runner (`rsl_rl` and similar), training is launched with:
 
 ```bash
 uv run genelab train <task-id>
@@ -47,23 +55,103 @@ uv run genelab train <task-id> --gpus 4       # multi-GPU via torchrun
 uv run genelab train <task-id> --checkpoint path/to/model.pt
 ```
 
-The `--gpus N` flag transparently dispatches through `torchrun` for distributed training; the
-target task's runner needs to be `torchrun`-compatible.
+!!! warning "Distributed training"
+    `--gpus N` transparently dispatches through `torchrun` for distributed training; the target
+    task's runner must be `torchrun`-compatible.
 
-## Start a downstream project
+## 4. Scaffolding a project
 
-When you outgrow the example extension and want your own package:
+A standalone downstream package is generated with:
 
 ```bash
 uv run genelab project new my_robot_project
 ```
 
-This scaffolds `config.py`, `robots.py`, `envs.py`, `tasks.py`, and a `pyproject.toml` with a
-`genelab.extensions` entry point. See [Project new](../cli/project-new.md).
+This produces `config.py`, `robots.py`, `envs.py`, `tasks.py`, and a `pyproject.toml` that
+declares a `genelab.extensions` entry point — the same shape as the bundled example extension.
+
+## 5. Advanced: end-to-end RL on Unitree G1 { #unitree-g1 }
+
+The repository ships a production-grade RL example under `examples/unitree/` — two PPO tasks on
+the Unitree G1 humanoid (velocity tracking and motion imitation), ported from mjlab and adapted
+to Genesis. The following walks through install, training, and checkpoint replay in one
+sitting.
+
+### 5.1 Install the extension
+
+The Unitree extension depends on the `rl` extra (rsl_rl) and pulls in vendored MJCF + meshes
+(~19 MB). Pick the `torch-*` extra that matches your hardware — see *Installation* for the full
+extras table.
+
+```bash
+uv sync --extra rl --extra torch-cu128
+uv pip install -e examples/unitree
+
+uv run genelab list tasks
+# -> Genelab-Velocity-Flat-Unitree-G1-v0
+# -> Genelab-Tracking-Flat-Unitree-G1-v0
+```
+
+### 5.2 Velocity tracking PPO
+
+The velocity-tracking task asks the G1 to follow a commanded body-frame twist. Train, then
+replay the resulting checkpoint:
+
+```bash
+uv run genelab train Genelab-Velocity-Flat-Unitree-G1-v0 \
+    --num-envs 4096 --max-iterations 1500
+
+uv run genelab play  Genelab-Velocity-Flat-Unitree-G1-v0 \
+    --checkpoint logs/rsl_rl/g1_velocity_flat/<run>/model_1500.pt
+```
+
+`--checkpoint` makes `play` route through the RL runner with `--agent trained` by default.
+
+### 5.3 Motion imitation
+
+The tracking task imitates a recorded clip per-body (BeyondMimic-style) and requires a motion
+file in mjlab's NPZ schema (keys: `joint_pos`, `joint_vel`, `body_pos_w`, `body_quat_w`,
+`body_lin_vel_w`, `body_ang_vel_w`). Convert a CSV with
+[`mjlab.scripts.csv_to_npz`](https://github.com/Mujoco-Lab/mjlab/blob/main/src/mjlab/scripts/csv_to_npz.py)
+and pass the resulting file via `--env.commands.motion.motion_file`.
+
+```bash
+# Visualise a clip with no policy: robot reset to clip frames, zero torques.
+uv run genelab play Genelab-Tracking-Flat-Unitree-G1-v0 \
+    --agent zero \
+    --env.commands.motion.motion_file path/to/clip.npz \
+    --vis
+
+# Random-action sanity check (visible perturbation around the reference pose).
+uv run genelab play Genelab-Tracking-Flat-Unitree-G1-v0 \
+    --agent random \
+    --env.commands.motion.motion_file path/to/clip.npz \
+    --vis
+
+# Train.
+uv run genelab train Genelab-Tracking-Flat-Unitree-G1-v0 \
+    --env.commands.motion.motion_file path/to/clip.npz \
+    --num-envs 4096 --max-iterations 30000
+
+# Replay trained policy.
+uv run genelab play Genelab-Tracking-Flat-Unitree-G1-v0 \
+    --agent trained \
+    --checkpoint logs/rsl_rl/g1_tracking_flat/<run>/model_30000.pt \
+    --env.commands.motion.motion_file path/to/clip.npz
+```
+
+### 5.4 `--agent` modes
+
+`--agent` selects the policy source for `play`:
+
+| Value | Policy source |
+|-------|--------------|
+| `zero` | Constant zero action — useful for clip visualisation and sanity checks. |
+| `random` | Uniform-random action sampling — visible perturbation around the reference pose. |
+| `trained` | Load from `--checkpoint`. This is the default whenever `--checkpoint` is set. |
 
-## Next steps
+## See also
 
-- [CLI overview](../cli/overview.md) — all subcommands and global flags.
-- [Registry](../concepts/registry.md) — how `ROBOTS` / `ENVS` / `TASKS` work.
-- [Configs](../concepts/configs.md) — `ManagerBasedEnvCfg` and `apply_overrides`.
-- [Extensions](../concepts/extensions.md) — three ways to register downstream code.
+- [Configs](../concepts/configs.md)
+- [Extensions](../concepts/extensions.md)
+- [Examples](../examples/overview.md)
diff --git a/docs/getting-started/quickstart.zh.md b/docs/getting-started/quickstart.zh.md
index 8d5e0038..b2159337 100644
--- a/docs/getting-started/quickstart.zh.md
+++ b/docs/getting-started/quickstart.zh.md
@@ -1,8 +1,9 @@
 # 快速开始
 
-本节走通从 `uv sync` 到运行已注册任务的最短路径。
+本页覆盖从同步好的环境出发，到运行任务、生成下游项目骨架、并完整跑通仓库自带的 Unitree G1
+PPO 示例的全过程。
 
-## 列出可用项
+## 1. 列出已注册内容
 
 核心 `genelab` 包自带空注册表 —— 机器人、环境、任务都由扩展包贡献。仓库内
 `examples/genelab_examples/` 通过 `pyproject.toml` 中的 `genelab.extensions` entry point
@@ -14,17 +15,19 @@ uv run genelab list envs
 uv run genelab list tasks
 ```
 
-如果某个注册表为空，请安装或导入扩展（详见 [扩展加载](../concepts/extensions.md)）。
+注册表为空意味着没有扩展被导入。可通过 `uv pip install` 安装一个，或在命令行加
+`--import MODULE`。
 
-## 运行一个任务
+## 2. 运行任务
 
 ```bash
 uv run genelab play <task-id>
 ```
 
-CLI 会查找 `<task-id>` 的注册工厂，应用命令行传入的配置 override，然后在 Genesis 后端运行。
+CLI 会在 `TASKS` 注册表中解析 `<task-id>`，构造其 `TaskCfg`，应用命令行 override，然后在
+Genesis 后端跑 rollout。
 
-常用快捷：
+三个场景短标志：
 
 ```bash
 uv run genelab play <task-id> --vis           # 启用可视化
@@ -32,12 +35,18 @@ uv run genelab play <task-id> --steps 500     # 限制单 episode 步数
 uv run genelab play <task-id> --gpu 1         # 锁定到单张 GPU
 ```
 
-任意 override 使用 `--a.b.c VALUE` 点路径写法 —— 字符串会按目标 dataclass 字段的类型注解
-自动转换。完整 override 语法见 [play 与 train](../cli/play-train.md)。
+任意 override 使用 `--a.b.c VALUE` 点路径写法，字符串值按目标 dataclass 字段的类型注解自动
+转换：
 
-## 训练（任务带 runner 时）
+```bash
+uv run genelab play <task-id> \
+  --env.scene.dt 0.005 \
+  --env.actions.scale 0.5
+```
 
-如果任务自带 RL runner（rsl_rl 等），可用：
+## 3. 训练
+
+任务自带 RL runner（`rsl_rl` 等）时，以如下方式启动训练：
 
 ```bash
 uv run genelab train <task-id>
@@ -45,22 +54,99 @@ uv run genelab train <task-id> --gpus 4       # 多 GPU 通过 torchrun 启动
 uv run genelab train <task-id> --checkpoint path/to/model.pt
 ```
 
-`--gpus N` 会透明走 `torchrun` 启动分布式训练，前提是任务自身的 runner 支持 `torchrun`。
+!!! warning "分布式训练"
+    `--gpus N` 会透明走 `torchrun` 启动分布式训练，前提是任务自身的 runner 支持 `torchrun`。
 
-## 新建下游项目
+## 4. 新建下游项目
 
-当示例扩展不够用、想要自己的包时：
+生成一个独立的下游扩展包：
 
 ```bash
 uv run genelab project new my_robot_project
 ```
 
-生成包含 `config.py`、`robots.py`、`envs.py`、`tasks.py` 以及带 `genelab.extensions` entry
-point 的 `pyproject.toml`。详见 [新建项目](../cli/project-new.md)。
+会生成 `config.py`、`robots.py`、`envs.py`、`tasks.py` 以及一份声明了 `genelab.extensions`
+entry point 的 `pyproject.toml` —— 形态与仓库自带示例扩展一致。
+
+## 5. 进阶：在 Unitree G1 上跑通完整 RL 流程 { #unitree-g1 }
+
+仓库在 `examples/unitree/` 下提供一个生产级 RL 示例：两个 Unitree G1 人形机器人的 PPO 任务
+（速度跟踪与动作模仿），从 mjlab 移植并适配到 Genesis。下面给出从安装到训练再到 checkpoint
+回放的全部命令，无需跳页阅读。
+
+### 5.1 安装扩展
+
+unitree 扩展依赖 `rl` extra（rsl_rl），并随包附带 MJCF 与网格资源（约 19 MB）。`torch-*`
+extra 需按硬件挑选 —— 对照表见 *安装*。
+
+```bash
+uv sync --extra rl --extra torch-cu128
+uv pip install -e examples/unitree
+
+uv run genelab list tasks
+# -> Genelab-Velocity-Flat-Unitree-G1-v0
+# -> Genelab-Tracking-Flat-Unitree-G1-v0
+```
+
+### 5.2 速度跟踪 PPO
+
+速度跟踪任务要求 G1 跟随给定的 body-frame twist。训练后再回放训练好的 checkpoint：
+
+```bash
+uv run genelab train Genelab-Velocity-Flat-Unitree-G1-v0 \
+    --num-envs 4096 --max-iterations 1500
+
+uv run genelab play  Genelab-Velocity-Flat-Unitree-G1-v0 \
+    --checkpoint logs/rsl_rl/g1_velocity_flat/<run>/model_1500.pt
+```
+
+`--checkpoint` 会让 `play` 走 RL runner，并把 `--agent` 默认设为 `trained`。
+
+### 5.3 动作模仿
+
+动作模仿任务按 body 跟踪一段录制的动作片段（BeyondMimic 风格），需要一份 mjlab NPZ 格式的
+动作文件（键：`joint_pos`、`joint_vel`、`body_pos_w`、`body_quat_w`、`body_lin_vel_w`、
+`body_ang_vel_w`）。可用
+[`mjlab.scripts.csv_to_npz`](https://github.com/Mujoco-Lab/mjlab/blob/main/src/mjlab/scripts/csv_to_npz.py)
+把 CSV 转换为 NPZ，再通过 `--env.commands.motion.motion_file` 传入。
+
+```bash
+# 不跑策略，机器人按 clip 帧 reset、施加零力矩 —— 用于可视化 clip 本身。
+uv run genelab play Genelab-Tracking-Flat-Unitree-G1-v0 \
+    --agent zero \
+    --env.commands.motion.motion_file path/to/clip.npz \
+    --vis
+
+# 随机动作 sanity check（参考姿态附近可见扰动）。
+uv run genelab play Genelab-Tracking-Flat-Unitree-G1-v0 \
+    --agent random \
+    --env.commands.motion.motion_file path/to/clip.npz \
+    --vis
+
+# 训练。
+uv run genelab train Genelab-Tracking-Flat-Unitree-G1-v0 \
+    --env.commands.motion.motion_file path/to/clip.npz \
+    --num-envs 4096 --max-iterations 30000
+
+# 回放训练好的策略。
+uv run genelab play Genelab-Tracking-Flat-Unitree-G1-v0 \
+    --agent trained \
+    --checkpoint logs/rsl_rl/g1_tracking_flat/<run>/model_30000.pt \
+    --env.commands.motion.motion_file path/to/clip.npz
+```
+
+### 5.4 `--agent` 三种模式
+
+`--agent` 决定 `play` 的策略来源：
+
+| 取值 | 策略来源 |
+|------|---------|
+| `zero` | 恒零动作 —— 适合可视化 clip 与基本健康检查。 |
+| `random` | 均匀随机动作 —— 在参考姿态附近显示可见扰动。 |
+| `trained` | 从 `--checkpoint` 加载。设置 `--checkpoint` 时即为默认。 |
 
-## 下一步
+## See also
 
-- [CLI 总览](../cli/overview.md) —— 所有子命令与全局 flag。
-- [注册表](../concepts/registry.md) —— `ROBOTS` / `ENVS` / `TASKS` 的工作机制。
-- [配置系统](../concepts/configs.md) —— `ManagerBasedEnvCfg` 与 `apply_overrides`。
-- [扩展加载](../concepts/extensions.md) —— 三种注册下游代码的方式。
+- [配置系统](../concepts/configs.md)
+- [扩展加载](../concepts/extensions.md)
+- [示例](../examples/overview.md)
diff --git a/docs/index.en.md b/docs/index.en.md
index 1b48253a..8c2eb9cb 100644
--- a/docs/index.en.md
+++ b/docs/index.en.md
@@ -1,68 +1,34 @@
 # GeneLab
 
 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.
+[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.
 
 ## 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.
-
-## Quick start
-
-<div class="grid cards" markdown>
-
-- :material-download:{ .lg .middle } **Install**
-
-    ---
-
-    Set up `uv`, pick a `torch-*` extra, and verify.
-
-    [:octicons-arrow-right-24: Installation](getting-started/installation.md)
-
-- :material-rocket-launch-outline:{ .lg .middle } **Run**
-
-    ---
-
-    List registered tasks and play one.
-
-    [:octicons-arrow-right-24: Quickstart](getting-started/quickstart.md)
-
-- :material-console-line:{ .lg .middle } **CLI**
-
-    ---
-
-    `play`, `train`, `project new`, and override syntax.
-
-    [:octicons-arrow-right-24: CLI overview](cli/overview.md)
-
-- :material-package-variant-closed:{ .lg .middle } **Extend**
-
-    ---
-
-    Write a downstream extension package.
-
-    [:octicons-arrow-right-24: Extensions](concepts/extensions.md)
-
-</div>
+- 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
 
 - Python 3.12 or newer.
 - [uv](https://docs.astral.sh/uv/) for dependency management.
 
-## At a glance
+## Modules at a glance
 
 - `genelab.registry` — registries, registration helpers, and extension loading.
 - `genelab.configs` — reusable dataclass configs, including `ManagerBasedEnvCfg` and `TaskCfg`.
 - `genelab.lab` — public facade for registry and manager-based environment primitives.
 - `genelab.envs` / `genelab.robots` / `genelab.tasks` — core registry helper namespaces.
-- `genelab.actuator` / `genelab.entity` / `genelab.scene` / `genelab.sensor` / `genelab.terrains` /
-  `genelab.rl` — extension namespaces for robotics research code.
+- `genelab.actuator` / `genelab.entity` / `genelab.scene` / `genelab.sensor` /
+  `genelab.terrains` / `genelab.rl` — extension namespaces for robotics research code.
+
+## See also
 
-See the [API Reference](api/reference.md) for the full auto-generated module documentation.
+- [Installation](getting-started/installation.md)
+- [Quickstart](getting-started/quickstart.md)
+- [API Reference](api/reference.md)
diff --git a/docs/index.zh.md b/docs/index.zh.md
index 05ae6775..6c18fbbc 100644
--- a/docs/index.zh.md
+++ b/docs/index.zh.md
@@ -1,55 +1,17 @@
 # GeneLab
 
 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 调度等组织方式。
 
 ## 目标
 
-- 提供小型机器人、环境和任务注册表。
-- 将核心 API 层与示例资产、演示脚本分离。
-- 使用 manager 风格配置钩子组织 actions、observations、rewards、events 和 terminations。
-- 保持 Genesis 后端集成显式，便于扩展。
+- 小型机器人、环境和任务注册表。
+- 核心 API 层与示例资产、演示脚本分离。
+- 用 manager 风格配置钩子组织 actions、observations、rewards、events、terminations。
+- Genesis 后端集成显式且易于扩展。
 - 通过稳定的包结构与 CLI 支持下游机器人研究项目。
 
-## 快速开始
-
-<div class="grid cards" markdown>
-
-- :material-download:{ .lg .middle } **安装**
-
-    ---
-
-    准备 `uv`，挑选一个 `torch-*` extra，并完成验证。
-
-    [:octicons-arrow-right-24: 安装](getting-started/installation.md)
-
-- :material-rocket-launch-outline:{ .lg .middle } **运行**
-
-    ---
-
-    列出已注册任务并 play 一个。
-
-    [:octicons-arrow-right-24: 快速开始](getting-started/quickstart.md)
-
-- :material-console-line:{ .lg .middle } **CLI**
-
-    ---
-
-    `play`、`train`、`project new` 与 override 语法。
-
-    [:octicons-arrow-right-24: CLI 总览](cli/overview.md)
-
-- :material-package-variant-closed:{ .lg .middle } **扩展**
-
-    ---
-
-    编写下游扩展包接入注册表。
-
-    [:octicons-arrow-right-24: 扩展加载](concepts/extensions.md)
-
-</div>
-
 ## 要求
 
 - Python 3.12 或更新版本。
@@ -64,4 +26,8 @@ GeneLab 是一个面向强化学习与机器人研究的 Isaac Lab 风格 API，
 - `genelab.actuator` / `genelab.entity` / `genelab.scene` / `genelab.sensor` /
   `genelab.terrains` / `genelab.rl`：面向机器人研究代码的扩展命名空间。
 
-完整自动生成的模块文档见 [API 参考](api/reference.md)。
+## See also
+
+- [安装](getting-started/installation.md)
+- [快速开始](getting-started/quickstart.md)
+- [API 参考](api/reference.md)