diff --git a/README.zh-CN.md b/README.zh-CN.md
index 32db216..1e64e2d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -275,9 +275,13 @@ bun run lint
 bun run format:check
 bun run typecheck
 bun run test
+bun run test:container
+bun run test:sandbox
 bun run build
 ```
 
+`bun run test:container` 是本地隔离验证的首选路径，适合在不安装 Modal 的情况下，用干净 Linux 环境验证对宿主机敏感的生命周期检查。它运行的是 Quantex 针对所选 agent 的真实 CLI lifecycle smoke flow，包括采用已预装 agent 和 Quantex 独立二进制自检，不是单元测试套件。`bun run test:sandbox` 会通过 Modal 运行同一套 smoke flow，适合验证远程传输或专用 GitHub Actions workflow。
+
 ## License
 
 Apache-2.0
diff --git a/openspec/changes/sync-public-docs-skill-snapshot/.openspec.yaml b/openspec/changes/sync-public-docs-skill-snapshot/.openspec.yaml
new file mode 100644
index 0000000..93831bd
--- /dev/null
+++ b/openspec/changes/sync-public-docs-skill-snapshot/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-13
diff --git a/openspec/changes/sync-public-docs-skill-snapshot/design.md b/openspec/changes/sync-public-docs-skill-snapshot/design.md
new file mode 100644
index 0000000..fb12c35
--- /dev/null
+++ b/openspec/changes/sync-public-docs-skill-snapshot/design.md
@@ -0,0 +1,39 @@
+## Context
+
+The CLI behavior and catalog are already current. `bun run src/cli.ts capabilities --json` reports 28 supported agents, including `reasonix` and `vtcode`, and the English and Chinese supported-agent README tables already include both entries.
+
+The remaining drift is limited to mirrors that users and agents may read directly:
+
+- `skills/quantex-cli/references/command-recipes.md` maintains a supported-agent snapshot for prompt-time use.
+- `README.zh-CN.md` mirrors the English README but currently omits the newer isolation smoke commands from the maintainer command list.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make the public skill snapshot match the current supported-agent catalog.
+- Make the Simplified Chinese README match the English README for maintainer validation commands.
+- Validate the updated skill and OpenSpec state.
+
+**Non-Goals:**
+
+- Change CLI behavior, schemas, command catalog, or agent metadata.
+- Add new supported agents.
+- Rework skill distribution, runtime boundaries, or archive existing completed OpenSpec changes.
+
+## Decisions
+
+- Keep the skill snapshot as a short mirror rather than replacing it with generated output. The file already tells consumers the running binary remains the source of truth, so the useful fix is to remove known stale omissions while preserving that caveat.
+- Add `reasonix` and `vtcode` in the same order returned by `capabilities --json`.
+- Copy the English README's `test:container` / `test:sandbox` guidance into Simplified Chinese with equivalent meaning, not a new policy.
+
+## Risks / Trade-offs
+
+- [Mirror drift] Manually maintained snapshots can drift again. Mitigation: keep `skills/quantex-cli/scripts/smoke-check.sh` in the validation path and rely on `capabilities --json` as the source of truth during audits.
+- [Scope creep] Public docs work could expand into behavior changes. Mitigation: this change only edits documentation/OpenSpec artifacts and does not touch `src/`.
+
+## Validation Plan
+
+- Run `skills/quantex-cli/scripts/smoke-check.sh`.
+- Run `bun run openspec:validate`.
+- Run the repository doc-change baseline: `bun run lint`, `bun run format:check`, and `bun run typecheck`.
diff --git a/openspec/changes/sync-public-docs-skill-snapshot/proposal.md b/openspec/changes/sync-public-docs-skill-snapshot/proposal.md
new file mode 100644
index 0000000..285c310
--- /dev/null
+++ b/openspec/changes/sync-public-docs-skill-snapshot/proposal.md
@@ -0,0 +1,28 @@
+## Why
+
+The current public Quantex CLI skill snapshot is behind the live agent catalog: `capabilities --json` reports `reasonix` and `vtcode`, while `skills/quantex-cli/references/command-recipes.md` omits both. The Simplified Chinese README also lags behind the English maintainer command list for isolation smoke validation.
+
+This request requires OpenSpec because it updates product-facing documentation and the maintained user-facing skill surface.
+
+## What Changes
+
+- Refresh the public skill command recipes supported-agent snapshot so it matches the current CLI catalog.
+- Sync the Simplified Chinese README maintainer command list with the English README for `test:container` and `test:sandbox`.
+- Keep the user-facing `skills/quantex-cli` and contributor-facing `skills/quantex-agent-runtime` boundary unchanged.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `product-readme`: keep README language variants aligned for current maintainer validation guidance.
+- `project-memory`: keep the public Quantex CLI skill snapshot aligned with the live CLI catalog when it mirrors supported agents.
+
+## Impact
+
+- `README.zh-CN.md` - sync maintainer validation commands and isolation smoke wording.
+- `skills/quantex-cli/references/command-recipes.md` - add missing supported-agent names from the live catalog.
+- `openspec/changes/sync-public-docs-skill-snapshot/` - record the documentation and skill-snapshot contract delta.
diff --git a/openspec/changes/sync-public-docs-skill-snapshot/specs/product-readme/spec.md b/openspec/changes/sync-public-docs-skill-snapshot/specs/product-readme/spec.md
new file mode 100644
index 0000000..a458ba7
--- /dev/null
+++ b/openspec/changes/sync-public-docs-skill-snapshot/specs/product-readme/spec.md
@@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: README Examples Match Current CLI Surface
+
+The root README MUST use command examples and supported-agent references that match the current Quantex CLI surface.
+
+#### Scenario: User copies a README command
+
+- **WHEN** a user copies an install, inspect, ensure, update, upgrade, or execution example from `README.md`
+- **THEN** the command reflects an existing Quantex command or documented alias.
+
+#### Scenario: Maintainer follows localized validation guidance
+
+- **WHEN** a maintainer reads local development commands from `README.zh-CN.md`
+- **THEN** the listed validation commands cover the same current maintainer-facing checks as `README.md`
+- **AND** isolation smoke commands such as `test:container` and `test:sandbox` are documented consistently when they are part of the English README guidance
diff --git a/openspec/changes/sync-public-docs-skill-snapshot/specs/project-memory/spec.md b/openspec/changes/sync-public-docs-skill-snapshot/specs/project-memory/spec.md
new file mode 100644
index 0000000..b164322
--- /dev/null
+++ b/openspec/changes/sync-public-docs-skill-snapshot/specs/project-memory/spec.md
@@ -0,0 +1,24 @@
+## MODIFIED Requirements
+
+### Requirement: Quantex Runtime Skill Is Contributor-Facing
+
+The central Quantex agent runtime skill SHALL be treated as a repository development workflow artifact for contributors and coding agents working inside this repository, not as the normal user-facing skill for operating Quantex.
+
+#### Scenario: Maintainer documents repo-local skills
+
+- **WHEN** repo-local skills are described in project memory or distribution docs
+- **THEN** `skills/quantex-cli` is identified as the user/agent-facing Quantex operation skill
+- **AND** `skills/quantex-agent-runtime` is identified as contributor-facing repository workflow runtime
+
+#### Scenario: User follows normal Quantex skill installation
+
+- **WHEN** a user wants a skill for operating Quantex from an external agent runtime
+- **THEN** the documented default target is `quantex-cli`
+- **AND** the user is not instructed to install `quantex-agent-runtime` unless they are contributing to this repository
+
+#### Scenario: Public skill mirrors supported-agent names
+
+- **WHEN** `skills/quantex-cli` includes a maintained supported-agent snapshot
+- **THEN** that snapshot is checked against the live CLI catalog from `capabilities --json`
+- **AND** known supported agents are not omitted from the skill-facing mirror
+- **AND** the skill still identifies the running binary as the source of truth for current support, flags, and output shapes
diff --git a/openspec/changes/sync-public-docs-skill-snapshot/tasks.md b/openspec/changes/sync-public-docs-skill-snapshot/tasks.md
new file mode 100644
index 0000000..1ee3f02
--- /dev/null
+++ b/openspec/changes/sync-public-docs-skill-snapshot/tasks.md
@@ -0,0 +1,20 @@
+## 1. OpenSpec
+
+- [x] 1.1 Classify the public README and skill snapshot sync as OpenSpec-backed product-facing documentation work
+- [x] 1.2 Add proposal, design, task list, and spec deltas for README/skill mirror alignment
+
+## 2. Documentation
+
+- [x] 2.1 Update the public `quantex-cli` skill command recipes supported-agent snapshot to include all current CLI catalog entries
+- [x] 2.2 Sync the Simplified Chinese README maintainer validation command list with the English README
+
+## 3. Validation
+
+- [x] 3.1 Run the Quantex CLI skill smoke check
+- [x] 3.2 Run OpenSpec validation
+- [x] 3.3 Run `bun run lint`, `bun run format:check`, and `bun run typecheck`
+
+## 4. Delivery
+
+- [x] 4.1 Commit the change on the dedicated branch
+- [x] 4.2 Push the branch and open a pull request with a validated PR body
diff --git a/skills/quantex-cli/references/command-recipes.md b/skills/quantex-cli/references/command-recipes.md
index 9ac01d8..2953213 100644
--- a/skills/quantex-cli/references/command-recipes.md
+++ b/skills/quantex-cli/references/command-recipes.md
@@ -31,7 +31,9 @@ This skill snapshot knows about these Quantex agent names:
 - `pi`
 - `qoder`
 - `qwen`
+- `reasonix`
 - `vibe`
+- `vtcode`
 
 The running binary remains the source of truth. If you are unsure whether the current binary supports a specific agent, command, flag, or output shape, run: