diff --git a/README.md b/README.md
index 46a84c7..7ffd4b9 100644
--- a/README.md
+++ b/README.md
@@ -1,186 +1,198 @@
-# llmdoc V3
+# llmdoc
 
-[中文说明](README.zh-CN.md)
+[简体中文](README.zh-CN.md)
 
-`llmdoc` is persistent external context for a codebase: architecture, constraints, and working knowledge that AI should not have to rediscover every session.
+Persistent engineering context that helps coding agents understand a repository
+without rediscovering its architecture every session.
 
-## Requirements
+- Preserve decisions, constraints, and cross-module contracts that source code
+  does not explain cheaply.
+- Retrieve only the context a task needs, then verify exact facts against the
+  live repository.
+- Recheck knowledge semantically as code evolves instead of accumulating stale
+  implementation notes.
 
-- Node.js 18 or newer
-- run `@tokenroll/llmdoc` as external tooling through npx
-- git for validity, delta, and rollback semantics
+## Start in 60 seconds
 
-Start without adding anything to the project's dependencies:
+You need Node.js 18 or newer and a Git repository. Choose the path that matches
+your repository and agent.
 
-```bash
-npx -y @tokenroll/llmdoc tree
-```
+### New repository with Claude Code
 
-If you prefer to download the CLI to your machine explicitly, install it globally rather than adding it to a project:
+Add the marketplace and install the plugin:
 
-```bash
-npm install --global @tokenroll/llmdoc
-llmdoc tree
+```text
+/plugin marketplace add TokenRollAI/llmdoc
+/plugin install llmdoc@llmdoc-plugin
 ```
 
-This optional machine-wide install does not modify the consumer repository's `package.json` or lockfile. Append an exact version to the package name when needed, for example `npm install --global @tokenroll/llmdoc@3.2.0`.
-
-V3 assumes the CLI is always present. Navigation, search, validation, delta detection, hook signals, and workflow entrypoints come from `npx @tokenroll/llmdoc`.
-
-> Always invoke with the full scoped name `npx @tokenroll/llmdoc <cmd>` — never a bare `npx llmdoc`, which would resolve to an unrelated third-party npm package. `npx -y` fetches a missing CLI into the npm cache without modifying the consumer repository's `package.json` or lockfile. When a workflow needs a fixed version, pin it in the package spec, for example `npx -y @tokenroll/llmdoc@3.2.0 tree`; do not install llmdoc as a project dependency.
-
-
-## Public Surface
-
-- Claude Code canonical plugin surface at the repository root:
-  - `.claude-plugin/`
-  - `skills/` (operating skill + explicit workflow skills)
-  - `agents/`
-  - `hooks/hooks.json`
-- CLI runtime: `npx @tokenroll/llmdoc <command>`
-- Explicit workflows:
-  - `init`
-  - `update`
-  - `prune`
-  - `upgrade`
-- Three roles:
-  - `investigator`: gathers evidence into `.llmdoc-tmp/investigations/`
-  - `reflector`: captures high-signal corrections and verified mistakes into `.llmdoc-tmp/reflections/pending/`
-  - `recorder`: the only writer of tracked `llmdoc/` knowledge and `llmdoc/meta.json`
+If the install summary says `Run /reload-plugins to activate.`, run that
+command. If the reload warns about rereading the conversation, rerun it as
+`/reload-plugins --force`. Once the plugin is active, initialize the repository:
 
-Claude is the canonical authoring surface. Codex packaging is generated from that surface through ACPlugin conversion. Other platforms use a thin `AGENTS.md` recipe plus `npx @tokenroll/llmdoc`.
-
-## Knowledge Model
-
-V3 uses `.mdx` documents with pure Markdown, YAML front matter, and one optional minimal enhancement: `<CodeRef>`.
-
-- path is the document ID
-- `kind` lives in front matter, not in directory names
-- the tracked knowledge tree is fixed to two levels:
-  - root singleton documents such as `llmdoc/architecture.mdx`
-  - one-level topic folders such as `llmdoc/api-client/retry-policy.mdx`
-- topics are plain folders: no `index.mdx` entry node; topic summaries come from `llmdoc tree`
-- nested topic folders are not allowed
-- the root map is generated by `llmdoc tree`; V2-style root `index.md` is gone
-
-Tracked validity lives in `llmdoc/meta.json`.
+```text
+/llmdoc:init
+```
 
-- `validatedRevision` is git-based
-- dirty working tree state is an extra signal, not a separate truth system
-- writes follow a git-based protocol: validate after changes, and revert through git if validation fails
+### New repository with Codex
 
-Temporary process records live under `.llmdoc-tmp/` and are not part of tracked knowledge.
+Add the marketplace and start Codex from the repository:
 
-Stable bodies are decision-bearing memory, not implementation inventories. Keep decisions and rationale, boundaries, invariants, cross-module contracts, non-obvious failures, and risky repeatable workflows. A `delta` hit requires review; it does not require a prose change. Facts that are cheap to reconstruct from source, schema, help, tests, or generated configuration stay in those canonical surfaces.
+```bash
+codex plugin marketplace add TokenRollAI/llmdoc
+codex
+```
 
-## CLI Commands
+Inside Codex, run `/plugins`, open the `llmdoc-plugin` marketplace, and install
+`llmdoc`. Review the plugin and its hooks before enabling them. Then start a new
+Codex session in the repository and ask:
 
-| Command | Purpose |
-|---|---|
-| `npx @tokenroll/llmdoc tree` | dynamic root map of root singletons and topics |
-| `npx @tokenroll/llmdoc index [--topic ...] [--kind ...]` | front-matter projection for document discovery |
-| `npx @tokenroll/llmdoc show <path...>` | read selected document bodies |
-| `npx @tokenroll/llmdoc search <query>` | lexical search across knowledge |
-| `npx @tokenroll/llmdoc context --files <src...>` | map source files to recommended docs |
-| `npx @tokenroll/llmdoc status` | current validity, baseline, dirty, and growth signals |
-| `npx @tokenroll/llmdoc delta` | changed code to impacted-doc closure |
-| `npx @tokenroll/llmdoc validate` | schema, structure, relation, link, and code-path validation |
-| `npx @tokenroll/llmdoc fingerprint --update <path...> \| --all` | refresh validated revisions in `llmdoc/meta.json` |
-| `npx @tokenroll/llmdoc commit [--verified <path...> \| --all]` | validate, commit any prose changes, and refresh changed or verified-unchanged revisions |
-| `npx @tokenroll/llmdoc new <path> --kind <kind>` | scaffold a new V3 doc |
-| `npx @tokenroll/llmdoc adopt <path...>` | register existing docs into `llmdoc/meta.json` without rewriting bodies |
-| `npx @tokenroll/llmdoc mv <from> <to>` | move a doc and update references |
-| `npx @tokenroll/llmdoc prune --report` | convergence report without writing docs |
-| `npx @tokenroll/llmdoc upgrade` | explicit V2 to V3 migration entrypoint |
-| `npx @tokenroll/llmdoc hook session-start` | startup signal for hosts |
-| `npx @tokenroll/llmdoc hook stop` | stop-time reminder signal |
-| `npx @tokenroll/llmdoc hook compact` | compaction-state emission |
+```text
+Use the llmdoc:init skill to initialize this repository.
+```
 
-## Workflow Semantics
+### Repository that already has `llmdoc/`
 
-### `init`
+Open its knowledge map immediately—no plugin is required for direct CLI use:
 
-Creates the first V3 knowledge set for a repository that does not already have llmdoc.
+```bash
+npx -y @tokenroll/llmdoc tree
+npx -y @tokenroll/llmdoc search "revision"
+```
 
-- the assistant may suggest it when llmdoc is missing
-- running it authorizes the full initialization scope for that invocation
-- if the repository already has V2 knowledge, use `upgrade` instead
+`@tokenroll/llmdoc` is external tooling. Do not add it to the consumer project's
+`package.json` or lockfile, and never use the unrelated bare package name
+`npx llmdoc`. For reproducible runs, pin the package spec:
+`npx -y @tokenroll/llmdoc@<version> <command>`. The package exposes the `llmdoc`
+bin; the scoped npx form keeps it outside the consumer repository.
 
-### `update`
+## How it works
 
-Semantically verifies tracked knowledge against the current repository state.
+```mermaid
+flowchart LR
+    K[Stable knowledge in llmdoc/] --> R[Task-scoped retrieval]
+    R --> S[Source verification]
+    S --> U[Semantic maintenance]
+    U --> K
+```
 
-- the assistant should suggest it after meaningful durable knowledge changes, but only after user confirmation
-- after confirmation, the workflow may complete without repeated confirmation unless the scope expands materially
-- `--reflection` consumes pending high-signal correction or failure candidates even when source delta is empty
-- CLI signals choose the lightest sufficient evidence path, not whether prose must change
-- the recorder rewrites only claims that changed or pass the stable-knowledge gate
-- docs that remain true are finalized as verified unchanged instead of accumulating new evidence
+`llmdoc/` stores durable engineering meaning—not a copy of the repository. An
+agent first retrieves the smallest useful knowledge set, uses source and tests
+for current facts, and later verifies affected knowledge. A code change creates
+a review obligation; it does not automatically create a documentation rewrite.
 
-### `prune`
+## Two operating layers
 
-Reduces duplicate, fragmented, bloated, or cheaply reconstructable knowledge after update.
+- **Agent workflows** own judgment and safe closeout. Invoke them through the
+  host's command or skill interface.
+- **Runtime CLI** owns retrieval and deterministic mechanics. Call it with the
+  scoped npx command, directly or from a workflow.
 
-- explicit command only
-- may be suggested when the growth gate is hit
-- a clean duplicate report does not replace semantic density review
-- requires confirmation before execution
+The workflows are not four equivalent CLI commands:
 
-### `upgrade`
+- `init` creates a small, high-value V3 knowledge surface when none exists.
+- `update` semantically verifies affected knowledge; unchanged documents can be
+  recorded as verified without inventing prose changes.
+- `prune` reduces duplicate, fragmented, or cheaply reconstructable knowledge;
+  the CLI only supplies a read-only report.
+- `upgrade` migrates legacy/V2 knowledge. It runs only when the user explicitly
+  asks for it and must never be suggested or folded into another workflow.
 
-Migrates a repository from V2 to V3.
+Every explicit workflow reports exactly one result state: `success`,
+`no_change`, `dry_run`, `incomplete`, or `failed`.
 
-- explicit command only
-- never suggested proactively
-- should run in a dedicated git-backed migration step so the whole change can be reverted cleanly
+## Daily use
 
-## Result States
+Apply this routing gate before broad exploration and again when entering a new
+subsystem:
 
-All explicit workflows report one exact result name:
+- Concept, contract, term, or “where is X?” → `search <query>`
+- Context for concrete source files → `context --files <path...>`
+- Cold start or unclear scope → `tree`
+- Known topic or kind → `index --topic <topic>` / `index --kind <kind>`
+- Bodies already identified → `show <path...>`
 
-- `success`
-- `no_change`
-- `dry_run`
-- `incomplete`
-- `failed`
+These are alternatives, not a fixed sequence. Once llmdoc narrows the working
+set, use native tools for exact source text, line numbers, test behavior,
+counts, and Git state.
 
-## Progressive Reading
+```bash
+# Map the knowledge surface
+npx -y @tokenroll/llmdoc tree --docs
 
-Daily use is CLI-first:
+# Find relevant knowledge
+npx -y @tokenroll/llmdoc search "revision" --limit 5
+npx -y @tokenroll/llmdoc context --files cli/src/cli.ts
 
-1. `npx @tokenroll/llmdoc tree`
-2. run `npx @tokenroll/llmdoc index --topic <t>` for document metadata
-3. use `npx @tokenroll/llmdoc context --files ...` or `npx @tokenroll/llmdoc search ...`
-4. use `npx @tokenroll/llmdoc show ...` only for the documents that matter
+# Read only the selected bodies
+npx -y @tokenroll/llmdoc show architecture.mdx cli-runtime/retrieval-and-mutation.mdx
 
-There is no V2 startup pack, root router document, worker, tracked reflection kind, or `sync.md` contract in V3. The CLI is the entrypoint; the restored `reflector` writes only temporary promotion candidates.
+# Browse the knowledge surface locally
+npx -y @tokenroll/llmdoc serve
+```
 
-## Install And Verify
+Use `npx -y @tokenroll/llmdoc --help` or
+`npx -y @tokenroll/llmdoc help <command>` for the complete, current CLI
+reference. `status` and `delta` assess validity and impact; they are not
+retrieval steps.
+
+## Knowledge and safety boundaries
+
+- Stable knowledge belongs in tracked `llmdoc/`; investigations, caches, and
+  reflection candidates belong in local `.llmdoc-tmp/`.
+- V3 documents are pure Markdown `.mdx` with YAML front matter and optional
+  `<CodeRef>` anchors. The path is the document ID, and `kind` lives in front
+  matter rather than directory names.
+- The tree contains root singleton documents and one level of topic folders. It
+  has no `index.mdx` topic nodes and no nested topic folders.
+- `llmdoc/meta.json` is a Git-revision validity ledger, not documentation. Dirty
+  worktree state is an additional signal, not a second truth system. Never
+  hand-edit the ledger; use the CLI's guarded mutation and commit operations.
+- Within agent workflows, `investigator` gathers temporary evidence, `reflector`
+  captures privacy-safe lesson candidates, and `recorder` is the only role that
+  writes tracked knowledge.
+- Every workflow authorizes knowledge maintenance only, not source-code edits.
+  Structural writes are validated and confined to the repository's `llmdoc/`
+  boundary.
+- Hooks emit read-only, fail-open signals through the scoped CLI. Review hooks
+  and trust the plugin source before enabling them.
+- A `delta` match means “review this claim,” not “rewrite this document.”
+  Preserve decisions, rationale, boundaries, invariants, contracts, and
+  non-obvious failure semantics; leave reconstructable facts in source, schemas,
+  help, tests, or generated configuration.
+
+## Platform integration
 
 ### Claude Code
 
-Repository-verified plugin installation entrypoint:
-
-```bash
-/plugin marketplace add https://github.com/TokenRollAI/llmdoc
-/plugin install llmdoc@llmdoc-plugin
-```
+The repository-root Claude plugin is the canonical authored surface. It provides
+the operating skill, four explicit workflows, three roles, and lifecycle hooks.
+Use the installation flow above, or manage it from Claude Code's plugin UI. See
+the [Claude Code plugin documentation](https://code.claude.com/docs/en/discover-plugins)
+for current installation behavior.
 
 ### Codex
 
-Add this repository as a plugin marketplace source, then install `llmdoc` from the Plugins Directory (per the [official plugin docs](https://developers.openai.com/plugins/build/plugins)):
+The Codex plugin is generated from the Claude surface and exposes equivalent
+skills, roles, and hooks. You can also run `/plugins` in Codex CLI to browse the
+Plugins Directory. Start a new session after installation, and inspect
+third-party hooks before trusting them. Codex IDE extensions do not currently
+support plugins. See the
+[official Codex plugin documentation](https://developers.openai.com/codex/plugins)
+for current installation behavior.
 
-```bash
-codex plugin marketplace add TokenRollAI/llmdoc
-```
+### Other agents
 
-The marketplace catalog is `.agents/plugins/marketplace.json`; the plugin manifest is `.codex-plugin/plugin.json` with skills under `.agents/skills/` and hooks at the default `hooks/hooks.json` location. Codex packaging is generated from the Claude surface through ACPlugin conversion — do not hand-edit it.
+Agents without a native plugin system can use the same runtime and operating
+contract. Copy the portable
+[`AGENTS.md` integration recipe](docs/agent-integration.md) into the consumer
+repository.
 
-Codex requires users to review and trust non-managed plugin hooks before they run; inspect them with `/hooks` after installation.
+## Develop this repository
 
-### Repository Development
-
-Typical local verification commands for this repository:
+The repository root is a private development workspace; the public consumer
+artifact is the `@tokenroll/llmdoc` CLI. Claude skills and agents are canonical,
+while the Codex surface is generated—do not hand-edit generated packaging.
 
 ```bash
 npm install
@@ -192,82 +204,16 @@ npm run validate:dogfood
 npm run check:prompts
 ```
 
-Install from the repository root so the local `llmdoc` bin is linked before validation. `validate:dogfood` validates this repository's dogfood `llmdoc/` surface.
-
-## Repository Shape
-
-```text
-.
-├── .claude-plugin/
-├── .codex-plugin/          # generated from the Claude surface
-├── agents/
-│   ├── investigator.md
-│   ├── reflector.md
-│   └── recorder.md
-├── cli/
-├── hooks/
-│   └── hooks.json
-├── skills/
-│   ├── llmdoc/          # operating skill
-│   ├── init/
-│   ├── update/
-│   ├── prune/
-│   └── upgrade/
-├── llmdoc/
-│   ├── meta.json
-│   ├── architecture.mdx
-│   └── <topic>/*.mdx
-└── .llmdoc-tmp/
-    ├── cache/
-    ├── investigations/
-    ├── reflections/pending/
-    └── records/
-```
-
-## Other Platforms
-
-Claude Code and Codex users get all of this from the plugin (hooks, operating skill, workflow commands). For tools without a native plugin system, invoke `@tokenroll/llmdoc` on demand through npx and paste this recipe into the project's `AGENTS.md`:
-
-```markdown
-# llmdoc
-
-This project uses llmdoc V3 as persistent engineering context.
-
-- Treat `@tokenroll/llmdoc` as external tooling: call it as
-  `npx -y @tokenroll/llmdoc ...`; never add it to this project's `package.json`
-  or lockfile. Pin the version in the npx package spec when needed.
-- Before the first discovery action, and again when entering a new subsystem,
-  choose the matching entry point: concept/contract/“where is X?” → `search`;
-  concrete source files → `context --files`; unclear scope → `tree`; known
-  topic/kind → `index`; identified document bodies → `show`.
-- Broad native discovery means recursive or cross-directory exploration outside
-  the working set identified by llmdoc. Apply the routing above before doing it.
-- Once llmdoc narrows the working set, use native tools for exact source text,
-  line numbers, tests, counts, git state, and other live facts. Do not run every
-  retrieval command as a fixed sequence; stop when the task has enough context.
-- `init` / `update` / `prune` / `upgrade` are explicit workflows: suggest them
-  when relevant, run only after user confirmation; never suggest `upgrade`.
-- Stable knowledge lives in `llmdoc/`; never hand-edit `llmdoc/meta.json`.
-  A delta hit requires review, not prose. Keep decisions, boundaries, invariants,
-  contracts, and non-obvious failure semantics; leave reconstructable evidence in
-  source, schema, help, tests, or `.llmdoc-tmp/`. Finalize unchanged reviewed docs
-  with `commit --verified`, which validates and fingerprints them without inventing
-  a body diff. Other ledger changes go through `commit` / `fingerprint` / `new` /
-  `adopt` / `mv`.
-- Treat an explicit user correction, a verified approach failure, major rework,
-  or an instruction violation as a reflection signal when it exposes a reusable
-  lesson. Capture a privacy-safe candidate under
-  `.llmdoc-tmp/reflections/pending/`; never store the full transcript.
-- A pending reflection candidate is an update signal even with no code delta.
-  After user confirmation, run the update workflow with `--reflection`; verify
-  the candidate, apply the same stable-knowledge gate, and merge only a durable
-  rule into its existing architecture or guide owner.
-- After work that changes durable architecture, contracts, or workflows,
-  suggest running the update workflow.
-```
+Install from the repository root so the local `llmdoc` bin is linked before
+validation. Changes to CLI semantics must remain synchronized with both host
+surfaces, the bilingual READMEs, design documentation, and dogfood knowledge.
 
-## Example Prompts
+## Reference
 
-- “Load llmdoc, inspect this repo, and tell me which topic docs I should read first.”
-- “Run the llmdoc update workflow after these architecture changes.”
-- “Upgrade this repository from llmdoc V2 to V3.”
+- [Portable Agent integration recipe](docs/agent-integration.md)
+- [V3 design notes](docs/v3-design/README.md) (currently marked draft)
+- [Operating protocol](skills/llmdoc/SKILL.md)
+- Workflow contracts: [`init`](skills/init/SKILL.md),
+  [`update`](skills/update/SKILL.md), [`prune`](skills/prune/SKILL.md), and
+  [`upgrade`](skills/upgrade/SKILL.md)
+- Runtime reference: `npx -y @tokenroll/llmdoc --help`
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 95f6550..cc722d1 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,186 +1,176 @@
-# llmdoc V3
+# llmdoc
 
 [English](README.md)
 
-`llmdoc` 是代码仓库的持久化外置上下文：把 AI 不该每次会话都重新恢复的架构、约束和工作知识放进可检索、可验证、可演进的文档层。
+持久化工程上下文，让 coding agent 不必在每次会话中重新恢复仓库架构。
 
-## 运行要求
+- 保存源码难以低成本解释的决策、约束和跨模块契约。
+- 只检索当前任务需要的上下文，再回到实时仓库核对精确事实。
+- 代码演进后做语义复核，而不是不断堆积过时的实现笔记。
 
-- Node.js 18 或更新版本
-- 通过 npx 把 `@tokenroll/llmdoc` 作为项目外部工具运行
-- git 作为有效性、delta 与回滚语义的基础
+## 60 秒开始
 
-无需向项目添加任何依赖，直接运行：
+你需要 Node.js 18 或更新版本，以及一个 Git 仓库。请选择与你的仓库和 Agent
+匹配的路径。
 
-```bash
-npx -y @tokenroll/llmdoc tree
-```
+### 新仓库 + Claude Code
 
-如果希望把 CLI 明确下载到本机，请安装到全局环境，而不是加入某个业务项目：
+添加 marketplace 并安装插件：
 
-```bash
-npm install --global @tokenroll/llmdoc
-llmdoc tree
+```text
+/plugin marketplace add TokenRollAI/llmdoc
+/plugin install llmdoc@llmdoc-plugin
 ```
 
-这个可选的本机安装方式不会修改业务项目的 `package.json` 或 lockfile。需要固定版本时直接追加版本号，例如 `npm install --global @tokenroll/llmdoc@3.2.0`。
-
-V3 假定 CLI 始终存在。导航、检索、校验、delta 检测、hook 信号和工作流入口都来自 `npx @tokenroll/llmdoc`。
-
-> 一律使用完整 scoped 名调用：`npx @tokenroll/llmdoc <cmd>`，永远不要用裸的 `npx llmdoc`——后者会解析到 npm 上一个无关的第三方包。`npx -y` 会把缺失的 CLI 获取到 npm 缓存，不会修改业务项目的 `package.json` 或 lockfile。需要固定版本时直接写在包名后，例如 `npx -y @tokenroll/llmdoc@3.2.0 tree`；不要把 llmdoc 安装为项目依赖。
-
-
-## 公开接口
-
-- Claude Code 的 canonical 插件表面位于仓库根：
-  - `.claude-plugin/`
-  - `skills/` (operating skill + explicit workflow skills)
-  - `agents/`
-  - `hooks/hooks.json`
-- CLI runtime：`npx @tokenroll/llmdoc <command>`
-- 显式工作流：
-  - `init`
-  - `update`
-  - `prune`
-  - `upgrade`
-- 三个角色：
-  - `investigator`：把证据调查写入 `.llmdoc-tmp/investigations/`
-  - `reflector`：把强信号用户纠正和已验证错误写入 `.llmdoc-tmp/reflections/pending/`
-  - `recorder`：唯一允许写入 tracked `llmdoc/` 知识和 `llmdoc/meta.json` 的角色
+如果安装摘要提示 `Run /reload-plugins to activate.`，请运行该命令；如果 reload
+警告需要重新读取对话，请改用 `/reload-plugins --force`。插件生效后，初始化仓库：
 
-Claude 是唯一手工维护的准源。Codex 插件表面由它通过 ACPlugin 转换生成。其他平台只需要一份精简 `AGENTS.md` 加 `npx @tokenroll/llmdoc`。
-
-## 知识模型
-
-V3 使用 `.mdx` 文档，内容是纯 Markdown、YAML front matter，以及一个可选的最小增强 `<CodeRef>`。
-
-- 路径就是文档 ID
-- `kind` 只存在于 front matter，不体现在目录名里
-- tracked 知识树固定为两层：
-  - 根级单例文档，例如 `llmdoc/architecture.mdx`
-  - 一层 topic 文件夹，例如 `llmdoc/api-client/retry-policy.mdx`
-- topic 就是纯目录：没有 `index.mdx` 入口节点，topic 摘要由 `llmdoc tree` 聚合
-- 不允许 topic 嵌套
-- 根级地图由 `llmdoc tree` 动态生成，V2 那种根 `index.md` 已移除
-
-tracked 有效性记录在 `llmdoc/meta.json`：
+```text
+/llmdoc:init
+```
 
-- `validatedRevision` 基于 git revision
-- dirty worktree 只是附加信号，不是第二套真相系统
-- 写入遵循 git-based 协议：修改后校验，失败时通过 git 回退
+### 新仓库 + Codex
 
-临时过程记录放在 `.llmdoc-tmp/`，不属于 tracked knowledge。
+添加 marketplace，然后从仓库目录启动 Codex：
 
-稳定正文是承载决策的工程记忆，不是实现库存。优先保留决策及理由、边界、不变量、跨模块契约、非显然失败语义和高风险可重复工作流。`delta` 命中只要求复核，不要求改正文；能从源码、schema、help、测试或生成配置快速恢复的事实留在这些 canonical surface。
+```bash
+codex plugin marketplace add TokenRollAI/llmdoc
+codex
+```
 
-## CLI 命令表
+在 Codex 中运行 `/plugins`，打开 `llmdoc-plugin` marketplace 并安装
+`llmdoc`。启用前先审查插件及其 hooks，然后在仓库中打开新的 Codex 会话并提出：
 
-| 命令 | 作用 |
-|---|---|
-| `npx @tokenroll/llmdoc tree` | 动态根地图，列出根单例和 topics |
-| `npx @tokenroll/llmdoc index [--topic ...] [--kind ...]` | 输出文档发现用的 front matter 投影 |
-| `npx @tokenroll/llmdoc show <path...>` | 读取指定文档正文 |
-| `npx @tokenroll/llmdoc search <query>` | 在知识层做词法检索 |
-| `npx @tokenroll/llmdoc context --files <src...>` | 从源码文件反查推荐阅读文档 |
-| `npx @tokenroll/llmdoc status` | 输出当前有效性、baseline、dirty 与 growth 信号 |
-| `npx @tokenroll/llmdoc delta` | 从代码变更推导受影响文档闭包 |
-| `npx @tokenroll/llmdoc validate` | 校验 schema、结构、关系、链接与 code paths |
-| `npx @tokenroll/llmdoc fingerprint --update <path...> \| --all` | 刷新 `llmdoc/meta.json` 中的 validated revisions |
-| `npx @tokenroll/llmdoc commit [--verified <path...> \| --all]` | 校验、提交必要正文，并刷新正文变化或 verified-unchanged 文档的 revision |
-| `npx @tokenroll/llmdoc new <path> --kind <kind>` | 脚手架生成新的 V3 文档 |
-| `npx @tokenroll/llmdoc adopt <path...>` | 无损登记已有文档到 `llmdoc/meta.json`(不改正文) |
-| `npx @tokenroll/llmdoc mv <from> <to>` | 移动文档并更新引用 |
-| `npx @tokenroll/llmdoc prune --report` | 输出收敛报告但不写文档 |
-| `npx @tokenroll/llmdoc upgrade` | 显式的 V2 到 V3 迁移入口 |
-| `npx @tokenroll/llmdoc hook session-start` | 给宿主提供启动信号 |
-| `npx @tokenroll/llmdoc hook stop` | 给宿主提供停止时提醒信号 |
-| `npx @tokenroll/llmdoc hook compact` | 输出 compact 状态 |
+```text
+Use the llmdoc:init skill to initialize this repository.
+```
 
-## 工作流语义
+### 已有 `llmdoc/` 的仓库
 
-### `init`
+可以直接打开知识地图——只使用 CLI 不需要先安装插件：
 
-为一个还没有 llmdoc 的仓库创建第一版 V3 知识。
+```bash
+npx -y @tokenroll/llmdoc tree
+npx -y @tokenroll/llmdoc search "revision"
+```
 
-- 当仓库缺少 llmdoc 时，assistant 可以建议执行
-- 用户一旦调用，就授权本次初始化范围
-- 如果仓库里已有 V2 知识，应改用 `upgrade`
+`@tokenroll/llmdoc` 是项目外部工具。不要把它加入消费项目的
+`package.json` 或 lockfile，也不要使用会解析到无关第三方包的裸命令
+`npx llmdoc`。需要可复现运行时，请在包名中固定版本：
+`npx -y @tokenroll/llmdoc@<version> <command>`。这个包暴露的 bin 名为
+`llmdoc`；使用 scoped npx 形式可以让它留在消费仓库的依赖之外。
 
-### `update`
+## 工作原理
 
-对照当前仓库状态做 tracked knowledge 的语义复核与同步。
+```mermaid
+flowchart LR
+    K[llmdoc/ 中的稳定知识] --> R[按任务检索]
+    R --> S[源码精确核对]
+    S --> U[语义维护]
+    U --> K
+```
 
-- assistant 应该在出现可持久化的新知识后建议执行，但必须先得到一次确认
-- 确认后，除非 scope 实质性扩张，否则流程可以完整跑完而不重复确认
-- `--reflection` 会消费强信号纠正或失败候选，即使代码 delta 为空也会触发更新判断
-- CLI 信号只决定最轻且足够的取证路径，不决定正文是否必须变化
-- recorder 只改写已经失效或通过稳定知识准入门槛的内容
-- 原文仍成立时按 verified unchanged 收尾，不把新证据追加进正文
+`llmdoc/` 保存的是持久化工程语义，不是仓库副本。Agent 先检索最小且足够的
+知识集，再用源码和测试核对当前事实，最后复核受影响的知识。
+代码变化会产生复核义务，但不会自动产生文档改写。
 
-### `prune`
+## 两层操作面
 
-在 update 之后收敛重复、碎片、膨胀或可快速重建的知识。
+- **Agent workflows** 负责判断和安全收尾，通过宿主的命令或 skill 接口调用。
+- **Runtime CLI** 负责检索和确定性操作，直接或由 workflow 通过 scoped npx
+  命令调用。
 
-- 只允许显式调用
-- 命中 growth gate 时可以被建议
-- 没有重复候选不等于知识密度合格，仍需语义审查
-- 执行前需要一次确认
+四条 workflow 不是四个等价的 CLI 命令：
 
-### `upgrade`
+- `init` 在仓库没有 llmdoc 时创建一小组高价值 V3 知识。
+- `update` 对受影响知识做语义复核；仍然成立的文档可以标记为已验证，无需制造
+  正文改动。
+- `prune` 收敛重复、碎片化或可低成本重建的知识；CLI 只提供只读报告。
+- `upgrade` 迁移 legacy/V2 知识。它只能在用户显式要求时运行，绝不能被主动
+  建议或折入其他 workflow。
 
-把仓库从 V2 迁移到 V3。
+每条显式 workflow 只报告一种结果状态：`success`、`no_change`、`dry_run`、
+`incomplete` 或 `failed`。
 
-- 只允许显式调用
-- 永不主动建议
-- 应在独立的 git 迁移步骤中执行，保证整次迁移可整体回滚
+## 日常使用
 
-## 结果状态
+在广泛探索之前，以及每次进入新子系统时，先应用下面的路由门：
 
-所有显式工作流都只报告以下一个精确结果名：
+- 概念、契约、术语或“X 在哪里？” → `search <query>`
+- 具体源码文件的背景或影响面 → `context --files <path...>`
+- 冷启动或范围不明 → `tree`
+- 已知 topic 或文档 kind → `index --topic <topic>` / `index --kind <kind>`
+- 已经定位的文档正文 → `show <path...>`
 
-- `success`
-- `no_change`
-- `dry_run`
-- `incomplete`
-- `failed`
+这些入口是备选关系，不是固定步骤。llmdoc 圈定工作集后，再使用原生工具核对
+源码原文、行号、测试行为、计数和 Git 状态。
 
-## 渐进读取
+```bash
+# 展开知识地图
+npx -y @tokenroll/llmdoc tree --docs
 
-日常使用以 CLI 为入口：
+# 查找相关知识
+npx -y @tokenroll/llmdoc search "revision" --limit 5
+npx -y @tokenroll/llmdoc context --files cli/src/cli.ts
 
-1. `npx @tokenroll/llmdoc tree`
-2. 用 `npx @tokenroll/llmdoc index --topic <t>` 看文档元数据
-3. 用 `npx @tokenroll/llmdoc context --files ...` 或 `npx @tokenroll/llmdoc search ...`
-4. 仅对真正需要的文档执行 `npx @tokenroll/llmdoc show ...`
+# 只读取已经选中的正文
+npx -y @tokenroll/llmdoc show architecture.mdx cli-runtime/retrieval-and-mutation.mdx
 
-V3 不再保留 V2 的 startup pack、根路由文档、`worker`、tracked reflection kind 或 `sync.md` 契约。CLI 本身就是入口；恢复后的 `reflector` 只写临时晋升候选。
+# 在本地浏览知识面
+npx -y @tokenroll/llmdoc serve
+```
 
-## 安装与验证
+完整且最新的 CLI reference 以 `npx -y @tokenroll/llmdoc --help` 和
+`npx -y @tokenroll/llmdoc help <command>` 为准。`status` 与 `delta`
+用于评估有效性和影响面，不是检索步骤。
+
+## 知识与安全边界
+
+- 稳定知识属于 tracked `llmdoc/`；调查、缓存和反思候选属于本地 `.llmdoc-tmp/`。
+- V3 文档是带 YAML front matter 的纯 Markdown `.mdx`，可以包含可选的 `<CodeRef>`
+  锚点。路径就是文档 ID，`kind` 位于 front matter，而不是目录名。
+- 文档树由根级单例和一层 topic 文件夹组成；不设 `index.mdx` topic 节点，也不
+  允许嵌套 topic。
+- `llmdoc/meta.json` 是基于 Git revision 的有效性台账，不是文档。dirty
+  worktree 只是附加信号，不是第二套真相系统。不要手工编辑台账；结构变化和
+  提交应使用 CLI 的受保护操作。
+- 在 Agent workflows 中，`investigator` 收集临时证据，`reflector` 捕获隐私
+  安全的经验候选，`recorder` 是唯一写入 tracked knowledge 的角色。
+- 每条 workflow 都只授权知识维护，不授权源码编辑。结构写入会经过校验，并被限制在
+  仓库的 `llmdoc/` 边界内。
+- Hooks 通过 scoped CLI 发出只读、fail-open 的信号。启用前先审查 hooks，并
+  确认插件来源可信。
+- `delta` 命中表示“复核这条结论”，不是“改写这篇文档”。保留决策及理由、
+  边界、不变量、契约和非显然失败语义；可重建事实应留在源码、schema、help、
+  测试或生成配置中。
+
+## 平台集成
 
 ### Claude Code
 
-仓库内已验证的插件安装入口：
-
-```bash
-/plugin marketplace add https://github.com/TokenRollAI/llmdoc
-/plugin install llmdoc@llmdoc-plugin
-```
+仓库根的 Claude 插件是手工维护的 canonical surface，包含 operating skill、
+四条显式 workflows、三个角色和 lifecycle hooks。使用上面的安装流程，或通过
+Claude Code 插件 UI 管理。安装行为以
+[Claude Code 插件文档](https://code.claude.com/docs/en/discover-plugins)为准。
 
 ### Codex
 
-按[官方插件文档](https://developers.openai.com/plugins/build/plugins)把本仓库添加为 plugin marketplace 源，然后在 Plugins Directory 中安装 `llmdoc`：
+Codex 插件由 Claude surface 生成，提供等价的 skills、角色和 hooks。也可以在
+Codex CLI 中运行 `/plugins` 浏览 Plugins Directory。安装后请打开新会话，并在
+信任第三方 hooks 前先审查它们。Codex IDE extension 当前不支持 plugins。
+安装行为以
+[OpenAI 官方 Codex 插件文档](https://developers.openai.com/codex/plugins)为准。
 
-```bash
-codex plugin marketplace add TokenRollAI/llmdoc
-```
+### 其他 Agents
 
-marketplace 目录是 `.agents/plugins/marketplace.json`；插件 manifest 是 `.codex-plugin/plugin.json`，skills 位于 `.agents/skills/`，hooks 在默认位置 `hooks/hooks.json`。Codex 打包由 Claude 表面经 ACPlugin 转换生成，请勿手工编辑。
+没有原生插件系统的 Agent 也可以使用相同的 runtime 和操作契约。把可移植的
+[`AGENTS.md` 集成配方](docs/agent-integration.md)复制到消费仓库即可。
 
-Codex 要求用户在非托管插件 hooks 运行前审查并信任它们；安装后用 `/hooks` 检查。
+## 开发本仓库
 
-### 本仓库开发验证
-
-这个仓库常用的本地验证命令：
+仓库根目录是私有开发工作区；面向消费方的公开产物是 `@tokenroll/llmdoc` CLI。
+Claude skills 和 agents 是准源，Codex surface 是生成产物——不要手工编辑生成的
+打包文件。
 
 ```bash
 npm install
@@ -192,75 +182,16 @@ npm run validate:dogfood
 npm run check:prompts
 ```
 
-请从仓库根目录安装依赖，确保本地 `llmdoc` bin 在校验前已建立链接。`validate:dogfood` 用于校验本仓库 dogfood 的 `llmdoc/` 知识面。
-
-## 仓库形态
-
-```text
-.
-├── .claude-plugin/
-├── .codex-plugin/          # 由 Claude 表面转换生成
-├── agents/
-│   ├── investigator.md
-│   ├── reflector.md
-│   └── recorder.md
-├── cli/
-├── hooks/
-│   └── hooks.json
-├── skills/
-│   ├── llmdoc/          # operating skill
-│   ├── init/
-│   ├── update/
-│   ├── prune/
-│   └── upgrade/
-├── llmdoc/
-│   ├── meta.json
-│   ├── architecture.mdx
-│   └── <topic>/*.mdx
-└── .llmdoc-tmp/
-    ├── cache/
-    ├── investigations/
-    ├── reflections/pending/
-    └── records/
-```
-
-## 其他平台
-
-Claude Code 与 Codex 用户由插件承担这一切（hooks、operating skill、工作流命令）。没有原生插件系统的工具，通过 npx 按需调用 `@tokenroll/llmdoc`，并把下面这份配方贴进项目的 `AGENTS.md` 即可：
-
-```markdown
-# llmdoc
-
-本项目使用 llmdoc V3 作为持久化工程上下文。
-
-- 把 `@tokenroll/llmdoc` 当作项目外部工具，以
-  `npx -y @tokenroll/llmdoc ...` 调用；绝不将它写入本项目的 `package.json`
-  或 lockfile。需要时在 npx 包名中固定版本。
-- 第一次发现式检索前，以及每次进入新子系统时，按意图选择入口：概念、
-  契约或“X 在哪里”→ `search`；具体源码文件 → `context --files`；范围不明 →
-  `tree`；已知 topic/kind → `index`；已定位的文档正文 → `show`。
-- 广泛原生探索指递归或跨目录搜索 llmdoc 尚未圈定的工作集；执行前必须重新
-  应用上面的路由。
-- llmdoc 圈定工作集后，可以用原生工具核对源码、行号、测试、计数、git 状态
-  等实时事实。不要把所有检索命令跑成固定序列；上下文足够就停。
-- `init` / `update` / `prune` / `upgrade` 是显式工作流：可以建议、须经用户
-  确认后执行；永不主动建议 `upgrade`。
-- 稳定知识在 `llmdoc/`；不要手工编辑 `llmdoc/meta.json`。`delta` 命中要求复核，
-  不要求改正文；正文只保留决策、边界、不变量、契约和非显然失败语义，可重建
-  证据留在源码、schema、help、测试或 `.llmdoc-tmp/`。复核后正文未变的文档用
-  `commit --verified` 收尾；其他台账变更走 `commit` / `fingerprint` / `new` /
-  `adopt` / `mv`。
-- 当用户明确纠正、验证证明方案错误、发生重大返工或违反项目指令，且其中
-  暴露出可复用经验时，将它视为反思强信号；只在
-  `.llmdoc-tmp/reflections/pending/` 保存隐私安全的候选，不保存完整对话。
-- pending 反思候选即使没有代码 delta 也会触发 update 判断。获得用户确认后，
-  用 `--reflection` 运行 update，验证候选并应用同一稳定知识准入门槛，只把耐久规则
-  合并到既有 architecture 或 guide owner。
-- 完成改变架构、契约或工作流的任务后，建议执行 update 工作流。
-```
+请从仓库根目录安装依赖，确保本地 `llmdoc` bin 在校验前已建立链接。CLI
+语义变化必须与两端宿主 surface、双语 README、设计文档和 dogfood knowledge
+保持同步。
 
-## 示例提示词
+## 参考
 
-- “先加载 llmdoc，检查这个仓库，并告诉我应该先读哪些 topic 文档。”
-- “在这些架构改动之后执行 llmdoc update 工作流。”
-- “把这个仓库从 llmdoc V2 升级到 V3。”
+- [可移植 Agent 集成配方](docs/agent-integration.md)
+- [V3 设计说明](docs/v3-design/README.md)（目前标记为 draft）
+- [Operating protocol](skills/llmdoc/SKILL.md)
+- Workflow contracts：[`init`](skills/init/SKILL.md)、
+  [`update`](skills/update/SKILL.md)、[`prune`](skills/prune/SKILL.md) 和
+  [`upgrade`](skills/upgrade/SKILL.md)
+- Runtime reference：`npx -y @tokenroll/llmdoc --help`
diff --git a/docs/agent-integration.md b/docs/agent-integration.md
new file mode 100644
index 0000000..2a1df9f
--- /dev/null
+++ b/docs/agent-integration.md
@@ -0,0 +1,111 @@
+# Portable Agent Integration
+
+[Back to the llmdoc README](../README.md)
+
+Use this recipe when an agent host does not have a native llmdoc plugin. It
+gives the agent the same retrieval, maintenance, and safety boundaries while
+keeping `@tokenroll/llmdoc` outside the consumer repository's dependencies.
+
+Copy the following block into the consumer repository's `AGENTS.md`:
+
+```markdown
+# llmdoc
+
+This project uses llmdoc V3 as persistent engineering context.
+
+## CLI boundary
+
+- Treat `@tokenroll/llmdoc` as external tooling. Run it as
+  `npx -y @tokenroll/llmdoc <command>`; never add it to this project's
+  `package.json` or lockfile, and never call the unrelated bare package
+  `npx llmdoc`. When reproducibility matters, pin the package spec:
+  `npx -y @tokenroll/llmdoc@<version> <command>`.
+- If the CLI is unavailable, report the degraded path and continue only with
+  narrowly scoped native inspection.
+- If hooks are available, keep them read-only and fail-open. They may signal
+  startup context, update needs, or compact state; they must not mutate
+  knowledge or source code.
+
+## Retrieval gate
+
+- Before the first broad discovery action, and again when entering a new
+  subsystem, choose the one entry point that matches the intent:
+  - concept, contract, term, or “where is X?” → `search <query>`
+  - background or blast radius of concrete source files →
+    `context --files <path...>`
+  - cold start or unclear scope → `tree`
+  - known topic or document kind → `index --topic <topic>` or
+    `index --kind <kind>`
+  - bodies of documents already identified → `show <path...>`
+- These entry points are alternatives, not a fixed sequence. Stop when the task
+  has enough context.
+- Broad native discovery means recursive or cross-directory exploration outside
+  the working set identified by llmdoc. After llmdoc narrows that set, use
+  native tools for exact source text, line numbers, test behavior, counts, Git
+  state, and other live facts.
+- `status` and `delta` assess staleness and impact; they are not retrieval
+  steps.
+
+## Knowledge boundary
+
+- Stable knowledge lives in tracked `llmdoc/`. Temporary investigations, caches,
+  and reflection candidates live in local `.llmdoc-tmp/`; validate a scratch
+  report before reusing it. Never hand-edit `llmdoc/meta.json`.
+- Keep decisions and rationale, boundaries, invariants, cross-module contracts,
+  non-obvious failure semantics, and risky repeatable workflows. Leave facts
+  that are cheap to reconstruct in source, schemas, CLI help, tests, or
+  generated configuration.
+- A `delta` hit creates a review obligation, not a prose-edit instruction. When
+  reviewed knowledge remains true, finalize it as verified unchanged instead of
+  inventing a body diff.
+- In agent workflows, `investigator` gathers temporary evidence, `reflector`
+  writes temporary privacy-safe lesson candidates, and `recorder` is the only
+  role that writes tracked `llmdoc/` knowledge.
+- Use guarded CLI operations for the validity ledger and structural changes:
+  `commit`, `fingerprint`, `new`, `adopt`, and `mv`.
+
+## Workflow boundary
+
+- `llmdoc:init`, `llmdoc:update`, `llmdoc:prune`, and `llmdoc:upgrade` are
+  judgment-bearing Agent workflows, not four equivalent CLI subcommands. The
+  runtime CLI supplies deterministic retrieval, diagnostics, validation, and
+  guarded mutation primitives.
+- On a host without the native plugin, treat those names as workflow intents in
+  Agent instructions, not as slash commands or commands supplied by the runtime
+  CLI. They become callable skill entry points only when the host integration
+  defines them.
+- Align with the user before non-trivial plans or edits. A workflow invocation
+  authorizes knowledge maintenance only; it does not authorize source-code
+  changes.
+- Suggest `init` when no valid V3 knowledge surface exists. If V3 already
+  exists, use `update` instead.
+- Suggest `update` after work that changes durable architecture, contracts, or
+  workflows, then wait for user confirmation. Treat source delta and pending
+  reflections as review inputs, not automatic writes.
+- Run `prune` only with user confirmation. Its CLI report supplies mechanical
+  signals; an Agent must still judge semantic density and ownership.
+- Never suggest `upgrade`. Run it only when the user explicitly asks for it by
+  name; its CLI command diagnoses legacy/V2 migration needs but does not perform
+  the semantic migration by itself.
+- After knowledge changes, validate and close out through the workflow's commit
+  protocol. If validation fails and cannot be repaired, revert only the current
+  documentation write set.
+- Report exactly one workflow result: `success`, `no_change`, `dry_run`,
+  `incomplete`, or `failed`.
+
+## Reflection gate
+
+- Treat an explicit user correction, a verified approach failure, major rework,
+  or an instruction violation as a reflection signal only when it exposes a
+  reusable lesson. Skip transient failures, trivial mistakes, and one-task
+  preferences.
+- Capture a privacy-safe candidate under `.llmdoc-tmp/reflections/pending/`;
+  never store the transcript.
+- A pending candidate is an update signal even when source delta is empty. After
+  user confirmation, verify it and apply the same stable-knowledge gate; merge
+  only a durable rule into its existing architecture or guide owner.
+```
+
+The recipe intentionally delegates exact command flags and schemas to the
+installed CLI. Use `npx -y @tokenroll/llmdoc --help` for the current runtime
+reference.
diff --git a/llmdoc/meta.json b/llmdoc/meta.json
index ea7f86a..b9ebc21 100644
--- a/llmdoc/meta.json
+++ b/llmdoc/meta.json
@@ -6,7 +6,7 @@
   },
   "documents": {
     "architecture.mdx": {
-      "validatedRevision": "0157d17e0cca2eb0ed0aaf20da41b80035be3a2e"
+      "validatedRevision": "5474197ed1cee62eaee541f93e1830b97474c0db"
     },
     "cli-runtime/state-and-validation.mdx": {
       "validatedRevision": "61ef5822ec305f61ebf41bb826e143a889c31e5e"
@@ -15,10 +15,10 @@
       "validatedRevision": "61ef5822ec305f61ebf41bb826e143a889c31e5e"
     },
     "plugin-packaging/claude-and-codex.mdx": {
-      "validatedRevision": "0157d17e0cca2eb0ed0aaf20da41b80035be3a2e"
+      "validatedRevision": "5474197ed1cee62eaee541f93e1830b97474c0db"
     },
     "plugin-packaging/development-and-release.mdx": {
-      "validatedRevision": "832bcf943c10528b60f01a02a7d8ce607ea44699"
+      "validatedRevision": "5474197ed1cee62eaee541f93e1830b97474c0db"
     },
     "workflows/init-and-update.mdx": {
       "validatedRevision": "61ef5822ec305f61ebf41bb826e143a889c31e5e"
diff --git a/llmdoc/plugin-packaging/development-and-release.mdx b/llmdoc/plugin-packaging/development-and-release.mdx
index 016fedc..b6c6882 100644
--- a/llmdoc/plugin-packaging/development-and-release.mdx
+++ b/llmdoc/plugin-packaging/development-and-release.mdx
@@ -10,6 +10,7 @@ code:
     - .github/workflows/release.yml
     - README.md
     - README.zh-CN.md
+    - docs/agent-integration.md
 ---
 
 # 开发、验证与发布
@@ -27,3 +28,7 @@ code:
 CLI 命令或输出语义变化必须在同一 change-set 同步：canonical skills/agents、生成的 Codex 表面、版本与 lockfile、双语 README/design docs，以及 dogfood `llmdoc/`。精确文件数量由自动化维护，不在正文复制。
 
 `scripts/check-codex-surface.mjs` 负责版本、身份与生成正文 parity；CI 还运行 lint、typecheck、test、build、prompt budget、dogfood validate 和消费者安装 smoke。自动化通过后仍需审查语义是否在所有公开表面一致，特别是宿主 UI policy 与授权边界。
+
+## 外部宿主指引复核不变量
+
+公开的外部宿主安装或启用指导在发布前必须依据宿主当时的官方用户文档复核。仓库中存在或本地可调用的命令，不足以单独成为主快速入门路径的依据；可选、恢复性或其他条件性步骤必须保留其条件语义。具体命令、UI 文案与步骤序列属于易变事实，不在稳定知识中固定。