From 1c1b97777577129fc2f906692c7cf1a1909dd58a Mon Sep 17 00:00:00 2001
From: sunrioa <sunrioa0721@qq.com>
Date: Tue, 25 Aug 2026 17:44:13 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=94=B6=E6=95=9B=E5=BC=80=E6=BA=90?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=E4=B8=8E=E5=8F=91=E5=B8=83=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md                              |  61 ++++++++++
 CHANGELOG.zh-CN.md                        |  52 ++++++++
 README.en.md                              |  29 +++--
 README.md                                 |  20 ++--
 SECURITY.en.md                            |  15 ++-
 THIRD-PARTY-NOTICES.md                    |  49 ++++++--
 docs/README.md                            |   4 +-
 docs/README.zh-CN.md                      |   4 +-
 docs/host-integration-validation.md       |   2 +-
 docs/host-integration-validation.zh-CN.md |   2 +-
 docs/host-scaffolding.md                  |  25 ++--
 docs/host-scaffolding.zh-CN.md            |  24 ++--
 docs/internal-agent-runtime.md            |  18 +--
 docs/internal-agent-runtime.zh-CN.md      |  12 +-
 docs/mcp-control-plane.md                 |   8 +-
 docs/mcp-control-plane.zh-CN.md           |   8 +-
 docs/milestone-a-validation.md            | 139 ----------------------
 docs/milestone-a-validation.zh-CN.md      | 133 ---------------------
 docs/task-timeline.md                     |   2 +-
 docs/task-timeline.zh-CN.md               |   2 +-
 examples/README.md                        |  21 ++--
 examples/README.zh-CN.md                  |  17 ++-
 examples/terminal-story/README.md         |  17 +--
 examples/terminal-story/README.zh-CN.md   |  11 +-
 sdk/README.md                             |  17 ++-
 sdk/README.zh-CN.md                       |  14 ++-
 sdk/csharp/README.md                      |  14 ++-
 sdk/csharp/README.zh-CN.md                |  10 +-
 sdk/java/README.md                        |  12 +-
 sdk/java/README.zh-CN.md                  |  10 +-
 sdk/javascript/README.md                  |  24 ++--
 sdk/javascript/README.zh-CN.md            |  23 ++--
 sdk/lua/README.md                         |   5 +
 sdk/lua/README.zh-CN.md                   |   4 +
 sdk/python/README.md                      |  15 ++-
 sdk/python/README.zh-CN.md                |  12 +-
 36 files changed, 398 insertions(+), 437 deletions(-)
 delete mode 100644 docs/milestone-a-validation.md
 delete mode 100644 docs/milestone-a-validation.zh-CN.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 59a263b..1ae9d8a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -82,3 +82,64 @@ pin an exact commit or tag for every distribution.
   visual-novel adapters. Installation, save/load, forced termination,
   multiplayer authority, emergency stop, UI, long-play, and character
   naturalness still require human acceptance.
+
+## [0.6.0] - 2026-07-24 - Preview
+
+This entry records the behavior of the `v0.6.0` tag. It describes the retired
+V1 architecture and is retained as release history, not as current V2 usage
+documentation.
+
+### Added
+
+- A game-authoritative Observation -> Proposal -> apply/reject -> Commit
+  lifecycle, including late outcome merging and durable game-side Outbox
+  recovery.
+- Durable, lineage-wide request and event ID history, exact retry results,
+  revision replay, internal replay checkpoints, `rin inspect`, and explicit
+  full-history verification.
+- Feature-gated memory archives, actor-local beliefs and goals, actor activity,
+  world arbitration, and atomic batch outcome reporting.
+- Asynchronous Proposal and structured Generation Jobs with bounded queues,
+  retention, cancellation, provider retries, and circuit breaking.
+- Source-first Python, JavaScript, C#, Java, and Lua clients; an OpenAPI 3.1
+  wire schema; and engine integration examples available at that release.
+
+### Changed
+
+- New Sessions could opt into late outcome reporting while existing Sessions
+  retained their historical reducer and Commit semantics.
+- Restore required an `expected_binding` from the running game's trusted
+  content manifest and checked it against both the imported Snapshot and an
+  existing target Session.
+- `rin.reducer-projection/v2` reconstructed Proposal presentation without
+  rewriting authoritative event bytes.
+- The bundled File Store added lazy Session loading, a revision index, and
+  derived checkpoints while retaining the event log indefinitely.
+
+### Security
+
+- Inline Snapshot JSON was capped at 16 MiB; default request and bundled client
+  response bodies were capped at 32 MiB. Oversized input was rejected rather
+  than truncated.
+- Provider prompts, credentials, and raw HTTP bodies were excluded from errors,
+  logs, and durable Session state.
+- Public HTTP JSON integers used the exact interoperable range, Commit
+  acceptance required an explicit field, and malformed UTF-8 or Unicode in
+  game-facing and successful provider JSON was rejected before decoding.
+- Snapshot, checkpoint, and event hashes were documented as unkeyed checksums,
+  not signatures or proof against an adversarial history rewrite.
+
+### Compatibility notes
+
+- This was a pre-1.0 Preview contract. Distributions needed to pin the Sidecar,
+  client source, and conformance inventory to the same repository revision.
+- Requests rejected unknown fields while clients were expected to tolerate
+  additive response fields. SDKs were source-first and were not published to
+  language registries.
+- Complete Snapshots had no streaming transport. The bundled File Store was
+  supported only on local `darwin` and `linux` filesystems.
+
+## Earlier implementation milestones
+
+Repository history also contains milestones named 0.1 through 0.5. They were
+development phases, not evidence that corresponding public release tags exist.
diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
index ecbadfa..8a3a922 100644
--- a/CHANGELOG.zh-CN.md
+++ b/CHANGELOG.zh-CN.md
@@ -69,3 +69,55 @@ Commit 或 Tag。
 - Rin Go 核心、Race、OpenAPI、五语言 SDK 和三个 V2 示例具备自动化门禁。
 - Minecraft 与视觉小说两个真实 Adapter 的自动契约与跨进程回归已通过；安装、存读档、
   强制终止、多人权限、急停、UI、长时间游玩和角色自然度仍需人工验收。
+
+## [0.6.0] - 2026-07-24 - Preview
+
+本节记录 `v0.6.0` Tag 当时的行为。它描述的是已经退役的 V1 架构，仅作为发布历史
+保留，不是当前 V2 的使用文档。
+
+### 新增
+
+- 由游戏掌握权威的 Observation -> Proposal -> Apply/Reject -> Commit 生命周期，
+  包括延迟 Outcome 合并和游戏侧持久 Outbox 恢复。
+- 覆盖完整 Lineage 的持久 Request/Event ID History、Exact Retry 结果、指定 Revision
+  Replay、内部重放 Checkpoint、`rin inspect` 和显式全历史校验。
+- 由 Feature 控制的 Memory Archive、Actor 本地 Belief 与 Goal、Actor Activity、
+  世界仲裁和原子 Batch Outcome。
+- 具有有界队列、保留、取消、Provider 重试和熔断的异步 Proposal 与结构化
+  Generation Job。
+- 源码优先的 Python、JavaScript、C#、Java、Lua Client、一份 OpenAPI 3.1 Wire
+  Schema，以及该版本发布时提供的引擎接入示例。
+
+### 变化
+
+- 新 Session 可启用延迟 Outcome 上报；既有 Session 保持原有 Reducer 与 Commit
+  语义。
+- Restore 要求提供运行中游戏可信内容 Manifest 的 `expected_binding`，并同时核对
+  导入 Snapshot 与已存在的目标 Session。
+- `rin.reducer-projection/v2` 可重建 Proposal 展示内容，同时不改写权威事件字节。
+- 随附 File Store 增加 Session Lazy Load、Revision Index 和派生 Checkpoint，并继续
+  永久保留事件日志。
+
+### 安全
+
+- Inline Snapshot JSON 上限为 16 MiB；默认请求正文和随附 Client 响应正文上限为
+  32 MiB。超限输入会被拒绝，而不是截断。
+- Provider Prompt、凭据和原始 HTTP 正文不会进入错误、日志或持久 Session State。
+- 公共 HTTP JSON 整数使用可精确跨语言表示的范围；Commit 接受结果要求显式字段；
+  游戏侧请求及成功 Provider JSON 中的非法 UTF-8 或 Unicode 会在解码前被拒绝。
+- Snapshot、Checkpoint 与 Event Hash 被明确视为无密钥 Checksum，而不是签名或对抗
+  历史重写的证明。
+
+### 兼容说明
+
+- 这是 pre-1.0 Preview 契约。分发时需要把 Sidecar、Client 源码和 Conformance
+  Inventory 固定到同一仓库 Revision。
+- 请求拒绝未知字段，Client 则应容忍响应中的增量字段。SDK 采用源码优先分发，未发布
+  到各语言 Registry。
+- 完整 Snapshot 没有流式传输；随附 File Store 仅支持 `darwin` 与 `linux` 的本地
+  文件系统。
+
+## 更早的实施里程碑
+
+仓库历史中还存在名为 0.1 至 0.5 的实施里程碑。它们是开发阶段，不表示存在对应的
+公共 Release Tag。
diff --git a/README.en.md b/README.en.md
index 1566677..e4dfb4a 100644
--- a/README.en.md
+++ b/README.en.md
@@ -59,14 +59,19 @@ Core invariants:
 
 ## Build locally
 
-Go `1.25` or newer is required. Other language runtimes are needed only when
-testing their SDKs.
+Building the core binaries requires Go `1.25` or newer:
 
 ```bash
-make verify
 make build
 ```
 
+The full maintainer verification gate also requires Node.js, Python, the .NET
+SDK, a JDK, and Lua:
+
+```bash
+make verify
+```
+
 The `bin/` directory then contains:
 
 - `rin`: the unified `serve`, `console`, MCP management, Host scaffolding,
@@ -106,6 +111,8 @@ actors, operations, long goals, and a readable task timeline, and it manages the
 shared default persona and common memory cards. Common cards are retrievable by
 internal Agents attached to the same Rin instance; game canon, actor-private
 memory, and an external Agent's private memory do not become cross-game state.
+The Console also manages learned skills, the internal model, optional remote
+embeddings, and general gameplay policy.
 
 ## Connect external Agents
 
@@ -131,9 +138,9 @@ creates a contract skeleton without downloading dependencies or pretending to
 provide an engine integration.
 
 ```bash
-./bin/rin init host -engine custom -runtime java -id my-game-host -output ./my-game-host
-./bin/rin conformance host -project ./my-game-host
-./bin/rin doctor host -project ./my-game-host
+./bin/rin init host -engine custom -runtime java -id my_game_host -output ./my-game-host
+./bin/rin conformance host -path ./my-game-host
+./bin/rin doctor host -path ./my-game-host
 ```
 
 A complete adapter supplies trusted observations, capability discovery, target
@@ -166,15 +173,19 @@ and adapter path.
 - [Roadmap](ROADMAP.en.md)
 
 The OpenAPI files are the sole HTTP route and field sources of truth:
-`api/control-openapi.json` and `api/agent-openapi.json`.
+`api/control-openapi.json`, `api/agent-openapi.json`,
+`api/management-openapi.json`, `api/signal-openapi.json`, and
+`api/task-plan-openapi.json`.
 
 ## Security boundary
 
 Rin does not execute model-generated code, expose engine objects to models, or
 allow controllers to declare effects. The built-in safety kernel denies effects
 for arbitrary code, file access, native calls, authority forgery, and secret
-exposure. API keys enter through process environment only and must never appear
-in Agent configuration, game saves, observations, or MCP output.
+exposure. Model and embedding provider keys must never appear in public Agent
+configuration, game saves, observations, or MCP output. They may come from
+environment variables or a separate mode-`0600` secret file written by the
+local Console; environment variables take precedence.
 
 See [SECURITY.en.md](SECURITY.en.md) for the threat model.
 
diff --git a/README.md b/README.md
index 4a5c14b..248aa0f 100644
--- a/README.md
+++ b/README.md
@@ -52,13 +52,18 @@ flowchart LR
 
 ## 本地构建
 
-要求 Go `1.25` 或更高版本。其他语言运行时只在测试对应 SDK 时需要。
+构建核心二进制要求 Go `1.25` 或更高版本：
 
 ```bash
-make verify
 make build
 ```
 
+运行完整维护者门禁还需要 Node.js、Python、.NET SDK、JDK 和 Lua：
+
+```bash
+make verify
+```
+
 产物位于 `bin/`：
 
 - `rin`：统一入口，包含 `serve`、`console`、MCP 管理、Host 脚手架、Conformance 和 Doctor。
@@ -115,9 +120,9 @@ Console 还可管理 learned Skill、内部模型、可选远程 Embedding 与
 或伪造引擎集成：
 
 ```bash
-./bin/rin init host -engine custom -runtime java -id my-game-host -output ./my-game-host
-./bin/rin conformance host -project ./my-game-host
-./bin/rin doctor host -project ./my-game-host
+./bin/rin init host -engine custom -runtime java -id my_game_host -output ./my-game-host
+./bin/rin conformance host -path ./my-game-host
+./bin/rin doctor host -path ./my-game-host
 ```
 
 完整 Adapter 需要实现可信观察、能力发现、目标绑定、Effect Preview、权威执行、取消和结果验证。
@@ -147,8 +152,9 @@ Control、Policy、Operation 与 Adapter 链路。
 - [路线图](ROADMAP.md)
 
 OpenAPI 文件是 HTTP 字段与路由的唯一事实来源：
-`api/control-openapi.json`、`api/agent-openapi.json` 和
-`api/management-openapi.json`。
+`api/control-openapi.json`、`api/agent-openapi.json`、
+`api/management-openapi.json`、`api/signal-openapi.json` 和
+`api/task-plan-openapi.json`。
 
 ## 安全边界
 
diff --git a/SECURITY.en.md b/SECURITY.en.md
index d25d0b7..fd13585 100644
--- a/SECURITY.en.md
+++ b/SECURITY.en.md
@@ -104,12 +104,21 @@ and adapter pre-execution validation must reject it.
 
 ## Providers and secrets
 
-Internal Agent configuration files must not contain API keys. Credentials enter
-the process only through:
+Internal Agent configuration files must not contain API keys. Credentials can
+enter the process through these environment variables:
 
 - `RIN_CONTROL_TOKEN` for the Control API;
 - `RIN_AGENT_TOKEN` for the Agent Task API, distinct from the Control token;
-- `RIN_AGENT_API_KEY` for an optional model provider, distinct from both daemon tokens.
+- `RIN_AGENT_API_KEY` for an optional model provider, distinct from both daemon tokens;
+- `RIN_AGENT_EMBEDDING_API_KEY` for optional remote embeddings, distinct from both daemon tokens.
+
+The loopback Rin Console can also store the two provider keys in
+`<data>/agent/agent-secrets.json`. This file is separate from public Agent
+configuration, is atomically written in a private directory with mode `0600`,
+and is never returned by the API; responses expose presence only. The matching
+environment variable overrides a saved value. This local store provides only
+operating-system user-level protection and must not be placed in a synchronized
+directory, game save, or repository.
 
 Remote model URLs require HTTPS; only loopback providers may use HTTP. URLs may
 not contain user information. The provider client rejects redirects and bounds
diff --git a/THIRD-PARTY-NOTICES.md b/THIRD-PARTY-NOTICES.md
index 173e272..618cd29 100644
--- a/THIRD-PARTY-NOTICES.md
+++ b/THIRD-PARTY-NOTICES.md
@@ -1,17 +1,44 @@
 # Third-party notices
 
-Rin is licensed under the [MIT License](LICENSE). The Go module also uses the
-following third-party packages under their own terms:
+Rin is licensed under the [MIT License](LICENSE). The table below is the union
+of external Go modules linked by CGO-disabled builds of `cmd/rin`,
+`cmd/rin-control`, and `cmd/rin-mcp` for `darwin/arm64`, `linux/amd64`, and
+`windows/amd64`. It was derived from `go list -deps`; test-only and tool-only
+modules are excluded.
 
-| Module | Version | License | Source and license text |
+License labels are summaries of the license files in the downloaded module
+archives, not replacements for those terms. `all` means the module is in the
+dependency closure of all three commands on at least one evaluated target;
+otherwise the table names the only command that links the module. Target-
+specific dependency pruning can still omit a listed module from one artifact.
+
+| Module | Version | Linked by | License files verified in module archive |
 | --- | --- | --- | --- |
-| `github.com/modelcontextprotocol/go-sdk` | `v1.7.0-pre.3` | MIT | [source](https://github.com/modelcontextprotocol/go-sdk/tree/v1.7.0-pre.3), [license](https://github.com/modelcontextprotocol/go-sdk/blob/v1.7.0-pre.3/LICENSE) |
-| `github.com/santhosh-tekuri/jsonschema/v6` | `v6.0.2` | Apache-2.0 | [source](https://github.com/santhosh-tekuri/jsonschema/tree/v6.0.2), [license](https://github.com/santhosh-tekuri/jsonschema/blob/v6.0.2/LICENSE) |
-| `go.yaml.in/yaml/v3` | `v3.0.5` | MIT and Apache-2.0 | [source](https://github.com/yaml/go-yaml/tree/v3.0.5), [license](https://github.com/yaml/go-yaml/blob/v3.0.5/LICENSE) |
-| `modernc.org/sqlite` | `v1.56.0` | BSD-3-Clause | [source](https://gitlab.com/cznic/sqlite/-/tree/v1.56.0), [license](https://gitlab.com/cznic/sqlite/-/blob/v1.56.0/LICENSE) |
-| `golang.org/x/text` | `v0.39.0` | BSD-3-Clause | [source](https://cs.opensource.google/go/x/text/+/v0.39.0), [license](https://cs.opensource.google/go/x/text/+/v0.39.0:LICENSE) |
+| [`github.com/dustin/go-humanize`](https://pkg.go.dev/github.com/dustin/go-humanize@v1.0.1) | `v1.0.1` | all | MIT (`LICENSE`) |
+| [`github.com/google/jsonschema-go`](https://pkg.go.dev/github.com/google/jsonschema-go@v0.4.3) | `v0.4.3` | `rin-mcp` | MIT (`LICENSE`) |
+| [`github.com/google/uuid`](https://pkg.go.dev/github.com/google/uuid@v1.6.0) | `v1.6.0` | all | BSD-3-Clause (`LICENSE`) |
+| [`github.com/mattn/go-isatty`](https://pkg.go.dev/github.com/mattn/go-isatty@v0.0.24) | `v0.0.24` | all | MIT (`LICENSE`) |
+| [`github.com/modelcontextprotocol/go-sdk`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk@v1.7.0-pre.3) | `v1.7.0-pre.3` | `rin-mcp` | Apache-2.0 and MIT (`LICENSE`) |
+| [`github.com/ncruces/go-strftime`](https://pkg.go.dev/github.com/ncruces/go-strftime@v1.0.0) | `v1.0.0` | all | MIT (`LICENSE`) |
+| [`github.com/remyoudompheng/bigfft`](https://pkg.go.dev/github.com/remyoudompheng/bigfft@v0.0.0-20230129092748-24d4a6f8daec) | `v0.0.0-20230129092748-24d4a6f8daec` | all | BSD-3-Clause (`LICENSE`) |
+| [`github.com/santhosh-tekuri/jsonschema/v6`](https://pkg.go.dev/github.com/santhosh-tekuri/jsonschema/v6@v6.0.2) | `v6.0.2` | all | Apache-2.0 (`LICENSE`) |
+| [`github.com/segmentio/asm`](https://pkg.go.dev/github.com/segmentio/asm@v1.1.3) | `v1.1.3` | `rin-mcp` | MIT (`LICENSE`) |
+| [`github.com/segmentio/encoding`](https://pkg.go.dev/github.com/segmentio/encoding@v0.5.4) | `v0.5.4` | `rin-mcp` | MIT (`LICENSE`) |
+| [`github.com/yosida95/uritemplate/v3`](https://pkg.go.dev/github.com/yosida95/uritemplate/v3@v3.0.2) | `v3.0.2` | `rin-mcp` | BSD-3-Clause (`LICENSE`) |
+| [`go.yaml.in/yaml/v3`](https://pkg.go.dev/go.yaml.in/yaml/v3@v3.0.5) | `v3.0.5` | all | MIT and Apache-2.0 (`LICENSE`, `NOTICE`) |
+| [`golang.org/x/oauth2`](https://pkg.go.dev/golang.org/x/oauth2@v0.35.0) | `v0.35.0` | `rin-mcp` | BSD-3-Clause (`LICENSE`) |
+| [`golang.org/x/sync`](https://pkg.go.dev/golang.org/x/sync@v0.21.0) | `v0.21.0` | `rin-mcp` | BSD-3-Clause (`LICENSE`) |
+| [`golang.org/x/sys`](https://pkg.go.dev/golang.org/x/sys@v0.47.0) | `v0.47.0` | all | BSD-3-Clause (`LICENSE`) |
+| [`golang.org/x/text`](https://pkg.go.dev/golang.org/x/text@v0.39.0) | `v0.39.0` | all | BSD-3-Clause (`LICENSE`) |
+| [`golang.org/x/time`](https://pkg.go.dev/golang.org/x/time@v0.15.0) | `v0.15.0` | `rin-mcp` | BSD-3-Clause (`LICENSE`) |
+| [`modernc.org/libc`](https://pkg.go.dev/modernc.org/libc@v1.74.4) | `v1.74.4` | all | BSD-3-Clause plus component terms (`LICENSE`, `LICENSE-3RD-PARTY.md`) |
+| [`modernc.org/mathutil`](https://pkg.go.dev/modernc.org/mathutil@v1.7.1) | `v1.7.1` | all | BSD-3-Clause (`LICENSE`, `mersenne/LICENSE`) |
+| [`modernc.org/memory`](https://pkg.go.dev/modernc.org/memory@v1.11.0) | `v1.11.0` | all | BSD-3-Clause plus component notices (`LICENSE`, `LICENSE-MMAP-GO`, `LICENSE-GO`, `LICENSE-LOGO`) |
+| [`modernc.org/sqlite`](https://pkg.go.dev/modernc.org/sqlite@v1.56.0) | `v1.56.0` | all | BSD-3-Clause (`LICENSE`) |
 
 The versions in `go.mod` and integrity hashes in `go.sum` are authoritative.
-Go module downloads include each dependency's complete license file. Binary
-distributors must reproduce the applicable license and attribution text in
-their distribution materials.
+Build tags, target operating systems, or dependency changes can alter a
+binary's dependency closure. Release packaging should therefore regenerate
+this inventory for every distributed target and include the complete
+applicable license, notice, copyright, and attribution texts from the exact
+module archives used to build it.
diff --git a/docs/README.md b/docs/README.md
index 1c32796..9dfa499 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -20,8 +20,6 @@ contracts. Documentation examples never replace authoritative game-adapter check
 10. [Signal inbox](signals.md): receive short-lived Host attention hints for internal wake-up or external MCP reads.
 11. [Host scaffolding](host-scaffolding.md): generate a contract skeleton for a language and engine.
 12. [Integration acceptance](host-integration-validation.md): automated gates and human game testing.
-13. [Milestone A validation report](milestone-a-validation.md): current architecture,
-    cross-adapter evidence, performance, and remaining human checks.
 
 Additional material:
 
@@ -36,6 +34,8 @@ Additional material:
 | Host `rin.host/v2` | `host/*.go` |
 | Control `rin.control/v2` | `api/control-openapi.json`, `controlplane/*.go` |
 | Agent Task API `v1` | `api/agent-openapi.json`, `agentapi/*.go` |
+| Management `rin.management/v1` | `api/management-openapi.json`, `managementapi/*.go` |
+| Task Plan `rin.task-plan/v1` | `api/task-plan-openapi.json`, `taskstate/*.go` |
 | Task timeline `v1` | `timeline/*.go`, `api/task-timeline-v1-fixtures.json` |
 | Signal `rin.signal/v1` | `signalbox/*.go`, `api/signal-openapi.json` |
 | MCP tools | `mcpbridge/server.go` |
diff --git a/docs/README.zh-CN.md b/docs/README.zh-CN.md
index 052faeb..07a25bc 100644
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -19,8 +19,6 @@
 10. [Signal 收件箱](signals.zh-CN.md)：由 Host 发布短期注意提示，供内部唤醒或外部 MCP 读取。
 11. [Host 脚手架](host-scaffolding.zh-CN.md)：生成契约骨架并接入自己的语言与引擎。
 12. [集成验收](host-integration-validation.zh-CN.md)：自动门禁与真人游戏测试。
-13. [里程碑 A 验收报告](milestone-a-validation.zh-CN.md)：当前架构、跨 Adapter 证据、性能与
-    仍需真人确认的项目。
 
 补充资料：
 
@@ -35,6 +33,8 @@
 | Host `rin.host/v2` | `host/*.go` |
 | Control `rin.control/v2` | `api/control-openapi.json`、`controlplane/*.go` |
 | Agent Task API `v1` | `api/agent-openapi.json`、`agentapi/*.go` |
+| Management `rin.management/v1` | `api/management-openapi.json`、`managementapi/*.go` |
+| Task Plan `rin.task-plan/v1` | `api/task-plan-openapi.json`、`taskstate/*.go` |
 | Task Timeline `v1` | `timeline/*.go`、`api/task-timeline-v1-fixtures.json` |
 | Signal `rin.signal/v1` | `signalbox/*.go`、`api/signal-openapi.json` |
 | MCP Tool | `mcpbridge/server.go` |
diff --git a/docs/host-integration-validation.md b/docs/host-integration-validation.md
index 8a9e1c3..d28f63e 100644
--- a/docs/host-integration-validation.md
+++ b/docs/host-integration-validation.md
@@ -16,7 +16,7 @@ make build
 
 `make verify` covers:
 
-- Go formatting, vet, race, and all package tests;
+- Go vet and all package tests under the race detector;
 - Host, Control, and Agent OpenAPI consistency;
 - Python, JavaScript, C#, Java, and Lua SDKs;
 - Grid, Story, and Terminal V2 adapter flows;
diff --git a/docs/host-integration-validation.zh-CN.md b/docs/host-integration-validation.zh-CN.md
index 43ec4b1..2398b22 100644
--- a/docs/host-integration-validation.zh-CN.md
+++ b/docs/host-integration-validation.zh-CN.md
@@ -14,7 +14,7 @@ make build
 
 `make verify` 覆盖：
 
-- Go Format、Vet、Race 和全包测试；
+- Go Vet 与 Race Detector 下的全包测试；
 - Host、Control 与 Agent OpenAPI 契约一致性；
 - Python、JavaScript、C#、Java、Lua SDK；
 - Grid、Story、Terminal 三个 V2 Adapter 流程；
diff --git a/docs/host-scaffolding.md b/docs/host-scaffolding.md
index 8a71557..e2f4e9c 100644
--- a/docs/host-scaffolding.md
+++ b/docs/host-scaffolding.md
@@ -9,10 +9,10 @@ code, or pretend to integrate a game engine.
 ## Create
 
 ```bash
-rin init host \
+./bin/rin init host \
   -engine custom \
   -runtime java \
-  -id my-game-host \
+  -id my_game_host \
   -name "My Game Host" \
   -version 0.1.0 \
   -output ./my-game-host
@@ -25,8 +25,8 @@ generic contract, not a completed engine integration.
 Inspect without writing:
 
 ```bash
-rin init host -engine custom -runtime java -id my-game-host -dry-run
-rin init host -list-hosts
+./bin/rin init host -engine custom -runtime java -id my_game_host -dry-run
+./bin/rin init host -list-hosts
 ```
 
 The destination must not exist. The generator never overwrites a path or picks
@@ -36,6 +36,8 @@ a different name automatically.
 
 ```text
 my-game-host/
+  .editorconfig
+  .gitignore
   README.md
   README.zh-CN.md
   LICENSE-RIN.txt
@@ -48,7 +50,8 @@ my-game-host/
 ```
 
 - `rin-host.json`: schema 2, `rin.host/v2`, runtime, durability, and capability directory.
-- `rin-scaffold.json`: generator, project, and SHA-256 for every file, used to detect drift.
+- `rin-scaffold.json`: generator and project metadata plus SHA-256 for every
+  generated file except the manifest itself, used to detect drift.
 - `capabilities/dialogue.say.json`: a sealed `CapabilitySpec` example.
 - `src/README.md`: authority boundaries the concrete game must implement.
 - `LICENSE-RIN.txt`: covers Rin-generated scaffold material only and does not license the game or mod.
@@ -59,11 +62,11 @@ execution, and outcome reporting.
 
 ## Verification commands
 
-Run from the generated directory or pass `-project`:
+Run from the Rin repository root after `make build`:
 
 ```bash
-rin conformance host -project ./my-game-host
-rin doctor host -project ./my-game-host
+./bin/rin conformance host -path ./my-game-host
+./bin/rin doctor host -path ./my-game-host
 ```
 
 Conformance checks:
@@ -93,8 +96,10 @@ contract skeleton, never real game behavior.
 
 Before writing, the generator renders every file and validates total size,
 relative paths, case collisions, reserved names, symlinks, and destination
-existence. It writes a temporary sibling directory and publishes atomically;
-only one concurrent creator of the same destination may succeed.
+existence. It creates the final directory directly, adds
+`.rin-scaffold.incomplete`, exclusively creates and verifies every generated
+file, then removes the marker. Once the marker exists, a later failure retains
+it. Only one concurrent creator of the same destination may succeed.
 
 `rin-scaffold.json` is an integrity inventory, not a signature. Someone able to
 modify files can recalculate SHA-256. Use your own signing and supply-chain
diff --git a/docs/host-scaffolding.zh-CN.md b/docs/host-scaffolding.zh-CN.md
index 9eb413f..fe2847c 100644
--- a/docs/host-scaffolding.zh-CN.md
+++ b/docs/host-scaffolding.zh-CN.md
@@ -8,10 +8,10 @@
 ## 创建
 
 ```bash
-rin init host \
+./bin/rin init host \
   -engine custom \
   -runtime java \
-  -id my-game-host \
+  -id my_game_host \
   -name "My Game Host" \
   -version 0.1.0 \
   -output ./my-game-host
@@ -23,8 +23,8 @@ rin init host \
 先检查而不写文件：
 
 ```bash
-rin init host -engine custom -runtime java -id my-game-host -dry-run
-rin init host -list-hosts
+./bin/rin init host -engine custom -runtime java -id my_game_host -dry-run
+./bin/rin init host -list-hosts
 ```
 
 目标目录必须不存在。生成器不会覆盖已有目录或文件，也不会自动选择另一个名称。
@@ -33,6 +33,8 @@ rin init host -list-hosts
 
 ```text
 my-game-host/
+  .editorconfig
+  .gitignore
   README.md
   README.zh-CN.md
   LICENSE-RIN.txt
@@ -45,7 +47,8 @@ my-game-host/
 ```
 
 - `rin-host.json`：Schema 2、`rin.host/v2`、Runtime、Durability 与能力目录。
-- `rin-scaffold.json`：生成器、项目和每个文件的 SHA-256；用于检测骨架漂移。
+- `rin-scaffold.json`：生成器、项目，以及除 Manifest 自身外每个生成文件的 SHA-256；
+  用于检测骨架漂移。
 - `capabilities/dialogue.say.json`：经过密封的 `CapabilitySpec` 示例。
 - `src/README.md`：必须由具体游戏实现的 Authority 边界。
 - `LICENSE-RIN.txt`：只覆盖 Rin 生成的骨架，不替游戏或 Mod 选择许可证。
@@ -55,11 +58,11 @@ my-game-host/
 
 ## 验证命令
 
-在生成目录或通过 `-project` 指定目录：
+在 Rin 仓库根目录执行 `make build` 后运行：
 
 ```bash
-rin conformance host -project ./my-game-host
-rin doctor host -project ./my-game-host
+./bin/rin conformance host -path ./my-game-host
+./bin/rin doctor host -path ./my-game-host
 ```
 
 Conformance 检查：
@@ -87,8 +90,9 @@ Doctor 输出接入状态和后续工作。两条命令只证明契约骨架有
 ## 安全属性
 
 生成器在写入前一次性渲染所有文件并验证总大小、相对路径、大小写碰撞、保留名称、
-符号链接和目标存在性。文件写入临时同级目录后原子发布；并发创建同一目标时只允许
-一个成功。
+符号链接和目标存在性。它直接创建最终目录，先写入 `.rin-scaffold.incomplete`，再以
+排他方式创建并验证全部生成文件，最后删除 Marker；Marker 创建后的后续步骤失败时，
+它会保留。并发创建同一目标时只允许一个成功。
 
 `rin-scaffold.json` 是完整性清单，不是签名。能修改文件的人也能重算 SHA-256；
 发布产物仍需使用你自己的签名和供应链机制。
diff --git a/docs/internal-agent-runtime.md b/docs/internal-agent-runtime.md
index c7ff011..954c71e 100644
--- a/docs/internal-agent-runtime.md
+++ b/docs/internal-agent-runtime.md
@@ -23,7 +23,7 @@ cooldown, and cancellation path.
 | Agent Client | Configured `client_principal` | Only `task.read`, `task.execute`, and `task.cancel` |
 | Internal Runtime | Created in process and never exposed over HTTP | Only controls Actors with `DecisionAuthority=internal` |
 
-`RIN_CONTROL_TOKEN` and `RIN_AGENT_TOKEN` should use different values. Neither
+`RIN_CONTROL_TOKEN` and `RIN_AGENT_TOKEN` must use different values. Neither
 token can access the other route family. The Agent Client cannot receive
 `host.admin`, `actor.*`, or game-specific scopes.
 
@@ -94,6 +94,8 @@ Only one default is allowed, and it cannot select a controller.
 ```bash
 chmod 600 /absolute/path/agent.json
 export RIN_AGENT_CONFIG=/absolute/path/agent.json
+export RIN_CONTROL_TOKEN="$(openssl rand -hex 32)"
+export RIN_CONTROL_PRINCIPAL="local.player"
 export RIN_AGENT_TOKEN="$(openssl rand -hex 32)"
 export RIN_AGENT_API_KEY="provider-key-from-secret-store"
 export RIN_AGENT_EMBEDDING_API_KEY="embedding-key-from-secret-store"
@@ -162,12 +164,14 @@ table keyed by configured model and content digest. Query vectors use a small
 process-local cache; results are rechecked against current visibility, expiry,
 filters, and content digest before use.
 
-`RIN_AGENT_EMBEDDING_API_KEY` is separate from JSON configuration. Private
-controller domains and text resembling credentials are never sent to the
-embedding endpoint. Timeout, transport failure, rate limiting, invalid model,
-invalid dimensions, or malformed vectors fall back to normal FTS5 and recent
-memory results. Rin does not download or run an embedding model, and the remote
-provider never owns Memory IDs, facts, permissions, or deletion.
+The embedding key is separate from JSON configuration. It may come from
+`RIN_AGENT_EMBEDDING_API_KEY` or the Console-managed secret file; the environment
+variable takes precedence. Private controller domains and text resembling
+credentials are never sent to the embedding endpoint. Timeout, transport
+failure, rate limiting, invalid model, invalid dimensions, or malformed vectors
+fall back to normal FTS5 and recent memory results. Rin does not download or run
+an embedding model, and the remote provider never owns Memory IDs, facts,
+permissions, or deletion.
 
 `rin-control` exclusively owns `<RIN_CONTROL_DATA_DIR>/agent/memory.db`.
 SQLite is the only online source of truth for the Rin Memory domain and uses WAL,
diff --git a/docs/internal-agent-runtime.zh-CN.md b/docs/internal-agent-runtime.zh-CN.md
index 4f872e1..b1f0f8e 100644
--- a/docs/internal-agent-runtime.zh-CN.md
+++ b/docs/internal-agent-runtime.zh-CN.md
@@ -19,7 +19,7 @@ Runtime 当前推进显式创建的 Task，不会仅凭 Persona 的 `initiative_
 | Agent Client | 配置中的 `client_principal` | 仅 `task.read`、`task.execute`、`task.cancel` |
 | Internal Runtime | 进程内创建，不通过 HTTP 暴露 | 仅控制 `DecisionAuthority=internal` 的角色 |
 
-`RIN_CONTROL_TOKEN` 与 `RIN_AGENT_TOKEN` 应使用不同值。任一 Token 都不能访问
+`RIN_CONTROL_TOKEN` 与 `RIN_AGENT_TOKEN` 必须使用不同值。任一 Token 都不能访问
 另一组路由。Agent Client 不能配置 `host.admin`、`actor.*` 或游戏专属 Scope。
 
 ## 配置
@@ -87,6 +87,8 @@ Actor+Controller 绑定和 Actor 绑定优先；只能配置一个默认绑定
 ```bash
 chmod 600 /absolute/path/agent.json
 export RIN_AGENT_CONFIG=/absolute/path/agent.json
+export RIN_CONTROL_TOKEN="$(openssl rand -hex 32)"
+export RIN_CONTROL_PRINCIPAL="local.player"
 export RIN_AGENT_TOKEN="$(openssl rand -hex 32)"
 export RIN_AGENT_API_KEY="provider-key-from-secret-store"
 export RIN_AGENT_EMBEDDING_API_KEY="embedding-key-from-secret-store"
@@ -142,10 +144,10 @@ Consolidate 可以把多条记录压缩为带来源的摘要。
 `memory_embeddings` 表；Query Vector 使用小型进程内缓存。向量候选进入结果前仍会重新校验
 当前可见域、过期、过滤条件和内容摘要。
 
-Embedding 凭据只从 `RIN_AGENT_EMBEDDING_API_KEY` 读取，不进入 JSON。Controller 私有域和
-疑似凭据文本不会外发。超时、断网、限流、模型身份不符、维度变化或非法向量都直接回退到
-FTS5 与近期记忆，不中断游戏任务。Rin 不下载或托管 Embedding 模型；远端 Provider 也不拥有
-Memory ID、事实、权限或删除权。
+Embedding 凭据不进入 JSON，可以来自 `RIN_AGENT_EMBEDDING_API_KEY` 或 Console 管理的
+secret 文件，环境变量优先。Controller 私有域和疑似凭据文本不会外发。超时、断网、限流、
+模型身份不符、维度变化或非法向量都直接回退到 FTS5 与近期记忆，不中断游戏任务。Rin
+不下载或托管 Embedding 模型；远端 Provider 也不拥有 Memory ID、事实、权限或删除权。
 
 `rin-control` 独占 `<RIN_CONTROL_DATA_DIR>/agent/memory.db`。SQLite 是 Rin Memory 域
 唯一的在线事实源，使用 WAL、完整同步和 FTS5；JSONL 仅用于显式的手动交换，不存在并行的
diff --git a/docs/mcp-control-plane.md b/docs/mcp-control-plane.md
index a761def..1b8be7d 100644
--- a/docs/mcp-control-plane.md
+++ b/docs/mcp-control-plane.md
@@ -130,7 +130,7 @@ replacement. A verified binary may also be supplied
 explicitly:
 
 ```bash
-rin mcp update -server /absolute/path/to/new/rin-mcp
+./bin/rin mcp update -server /absolute/path/to/new/rin-mcp
 ```
 
 Windows locks running executable images, so exit Agents using Rin MCP before
@@ -148,14 +148,14 @@ By default, remove all manifest-owned Agent registrations while keeping the
 managed files for easy reinstall, or select clients explicitly:
 
 ```bash
-rin mcp uninstall
-rin mcp uninstall -agents codex,claude
+./bin/rin mcp uninstall
+./bin/rin mcp uninstall -agents codex,claude
 ```
 
 Remove the managed binary, manifest, and private connection config as well:
 
 ```bash
-rin mcp uninstall -purge
+./bin/rin mcp uninstall -purge
 ```
 
 The uninstaller only removes registrations it owns and exact managed regular
diff --git a/docs/mcp-control-plane.zh-CN.md b/docs/mcp-control-plane.zh-CN.md
index ed572d9..becc857 100644
--- a/docs/mcp-control-plane.zh-CN.md
+++ b/docs/mcp-control-plane.zh-CN.md
@@ -115,7 +115,7 @@ export RIN_CONTROL_TOKEN="replace-with-the-same-random-secret"
 Agent 注册或私密连接配置；SHA-256 相同则不重复替换。也可明确指定已验证的二进制：
 
 ```bash
-rin mcp update -server /absolute/path/to/new/rin-mcp
+./bin/rin mcp update -server /absolute/path/to/new/rin-mcp
 ```
 
 Windows 会锁定正在运行的可执行文件，更新前需要退出使用 Rin MCP 的 Agent；
@@ -131,14 +131,14 @@ macOS/Linux 也建议更新后重启 Agent，使已有 STDIO 会话加载新版
 Agent：
 
 ```bash
-rin mcp uninstall
-rin mcp uninstall -agents codex,claude
+./bin/rin mcp uninstall
+./bin/rin mcp uninstall -agents codex,claude
 ```
 
 完全移除托管二进制、安装清单和私密连接配置：
 
 ```bash
-rin mcp uninstall -purge
+./bin/rin mcp uninstall -purge
 ```
 
 卸载器只删除自己记录的注册和固定托管路径，不删除同名未托管配置，也拒绝清理
diff --git a/docs/milestone-a-validation.md b/docs/milestone-a-validation.md
deleted file mode 100644
index 34d9102..0000000
--- a/docs/milestone-a-validation.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# Milestone A Validation Report
-
-[English](milestone-a-validation.md) | [简体中文](milestone-a-validation.zh-CN.md)
-
-Date: 2026-08-19
-Status: automated implementation and regression complete; human acceptance pending  
-Scope: Rin, rin-mi, and ai-galgame
-
-## Conclusion
-
-Rin now provides an engine-neutral execution harness. Internal and external MCP
-agents have separate persona and reasoning entry points, but share controller
-leases, the action gateway, gameplay policy, operations, and authoritative Host
-outcomes. Minecraft and a visual novel exercise the same path as real adapters.
-
-All automated gates pass, but Milestone A is not complete. A locked desktop cannot
-validate GUI behavior, TTS quality, character naturalness, continuous navigation,
-or a real Windows launch. External memory providers, Mem0, Hindsight, and Graphiti
-have not been started.
-
-## Current architecture
-
-```mermaid
-flowchart TB
-    EXT["External Agent<br/>own persona and memory"] --> MCP["rin-mcp<br/>stateless STDIO proxy"]
-    USER["Player"] --> CONSOLE["Rin Console<br/>monitoring, goals, shared cognition"]
-    INT["Internal Agent<br/>Persona / Memory / Skill / Model"] --> LOOP["AgentRuntime<br/>task and decision loop"]
-    SIGNAL["Signal inbox"] --> LOOP
-    MCP --> CTRL["rin-control<br/>resident control process"]
-    CONSOLE --> CTRL
-    LOOP --> CTRL
-    CTRL --> GATE["Action Gateway<br/>identity, lease, target binding"]
-    PLAN["PlanState<br/>coarse complex-task progress"] <--> LOOP
-    MEM["SQLite Memory + FTS5<br/>optional remote embedding"] <--> LOOP
-    SKILL["Skill Catalog<br/>standard SKILL.md"] --> LOOP
-    HOST["Game Host / Adapter"] -->|"Observation + Capability"| GATE
-    GATE -->|"ActionRequest"| HOST
-    HOST -->|"BoundAction + Effect"| POLICY["Gameplay Policy<br/>budgets and minimal rules"]
-    POLICY --> OPS["Operation Store<br/>delivery, cancel, recovery"]
-    OPS <-->|"ACK / Run / Outcome"| HOST
-    HOST --> ENGINE["real-time game controller"]
-    ENGINE --> WORLD["authoritative world / canon"]
-    WORLD --> HOST
-    OPS --> TIMELINE["Task Timeline"]
-    OPS --> MEM
-```
-
-Important boundaries:
-
-- The Adapter owns the world and story canon. Rin Memory is a searchable projection.
-- A model selects a target and capability; the Host binds concrete objects and effects,
-  then policy decides whether execution is allowed.
-- Queued, accepted, and running are not success. Only a Host outcome can set
-  `execution_confirmed=true`.
-- Simple actions bypass planning. Complex tasks use PlanState without invoking a
-  planner for every action.
-- External MCP does not require the internal model, and the internal agent cannot
-  take control while an external controller owns the lease.
-
-## Runtime decomposition
-
-Rin's `AgentRuntime` was reduced from about 1,896 lines to 774 lines. Context
-assembly, task lifecycle, plan and decision orchestration, action and operation
-coordination, and signal wake scheduling now live in focused package-private files.
-
-rin-mi extracted action dispatch, capability projection, agency scheduling,
-operation recovery, and session storage from `CompanionRuntime`. The Ender Dragon
-loop added dedicated portal, dimension, heading, landmark, and boss controllers;
-the runtime is now about 4,260 lines. Real-time logic remains in package-private
-controllers and no Minecraft types enter Rin Core. Further movement waits for
-human trace replay instead of risking a large pre-acceptance refactor.
-
-## Automated evidence
-
-| Scope | Result |
-| --- | --- |
-| Rin Core | `make verify`: contracts, Vet, Race, and all Go packages pass |
-| SDKs | Python, JavaScript, C#, Java, and Lua tests pass |
-| Example adapters | Grid, Story, and Terminal tests pass |
-| Builds | macOS arm64, Windows amd64, and Linux amd64 binaries generated |
-| rin-mi | Core, Skill validation, installer, and 28/28 Fabric GameTests pass |
-| rin-mi process tests | V2 Binding and Internal Agent Macro pass against real `rin-control` |
-| ai-galgame | 328 Python tests, Ren'Py lint, content, and asset checks pass |
-| ai-galgame process tests | External and Internal full-process E2E pass |
-
-The visual-novel smoke suite covers seven chapters, 19 interactive turns, 12
-bridges, 13 bookends, seven core conversations, six quiet moments, and about 150
-planned minutes. Lint reports 285 dialogue blocks, 18 menus, 27 images, and 30 screens.
-
-## Performance and tokens
-
-These local measurements detect regressions; they are not cross-machine guarantees.
-
-| Item | P50 | P95 | Gate |
-| --- | ---: | ---: | ---: |
-| SQLite Memory recall | 8.58ms | 9.59ms | P95 < 250ms |
-| PlanState operation | 0.14ms | 0.23ms | P95 < 100ms |
-
-The scripted provider fixture reports 100 prompt, 40 completion, 64 cache-hit, and
-36 cache-miss tokens per call. This validates Usage-to-Timeline propagation only;
-it does not claim savings from a real provider.
-
-## Breaking cleanup
-
-The retired file memory provider, its tests, and the initial `memory.json` migration
-path were removed as requested. `memory.db` is now the only online source of truth
-inside the Rin Memory domain. JSONL remains an explicit exchange format only.
-
-## Human acceptance still required
-
-1. Run two to four continuous hours: at least 90 minutes in Minecraft, with at least
-   45 minutes each for internal and external control, plus 45 minutes in the visual novel.
-2. Exercise Minecraft gathering, crafting, building, survival, combat, replanning,
-   controller switching, emergency stop, restart, difficult terrain, dimension
-   transfer, fortress/stronghold search, Eye of Ender travel, and a complete fresh-world Dragon run.
-3. Exercise fixed story, AI ScenePacket, critical choice, proactive topic, canon conflict,
-   save/load, rollback, and Internal/External switching; judge dialogue naturalness.
-4. With an unlocked desktop, run native Ren'Py testcases and inspect 1280x720,
-   1536x864, and 1920x1080 UI. Launch the release on real Windows.
-5. Listen to character TTS for Japanese pronunciation, pacing, voice binding, and silent fallback.
-6. Compare task timelines with play and confirm that public reasons, Memory/Skill refs,
-   tokens, policy, and outcomes explain behavior without leaking private context.
-
-## Known limitations
-
-- GameTest can log missing `server.properties`, Yggdrasil timeouts, and upstream
-  deprecation warnings; all 28 required tests still pass.
-- Native Ren'Py window tests cannot run while macOS has no available display.
-- Cross-compilation does not replace execution on the target operating system.
-- Automated traces prove contract and outcome consistency, not subjective character quality.
-
-## Stage commits
-
-Current Rin stages before this report: `ce16d21`, `81f8bb5`, `c70642d`; the
-Console timeline and documentation closure are in the commit containing this
-report. Current rin-mi stages: `28690cd`, `f7f31da`.
-
-Do not start the ExternalMemoryProvider SPI or a concrete external-memory adapter
-until human acceptance is complete and the user explicitly confirms the milestone.
diff --git a/docs/milestone-a-validation.zh-CN.md b/docs/milestone-a-validation.zh-CN.md
deleted file mode 100644
index 49d975a..0000000
--- a/docs/milestone-a-validation.zh-CN.md
+++ /dev/null
@@ -1,133 +0,0 @@
-# 里程碑 A 验收报告
-
-[简体中文](milestone-a-validation.zh-CN.md) | [English](milestone-a-validation.md)
-
-日期：2026-08-19
-状态：自动实现与回归完成，等待真人验收  
-范围：Rin、rin-mi、ai-galgame
-
-## 结论
-
-Rin 已形成一套不依赖具体游戏的执行 Harness。内部 Agent 与外部 MCP Agent 使用不同的
-人格和推理入口，但最终共用同一套 Controller Lease、Action Gateway、Gameplay Policy、
-Operation 和 Host Outcome。Minecraft 与视觉小说已作为两个真实 Adapter 走通这条链路。
-
-自动门禁全部通过，但里程碑 A 尚未完成。锁屏环境无法替代真实 GUI、TTS 听感、角色自然度、
-复杂地形连续操作和 Windows 实机启动，因此当前必须停在真人验收门。外挂记忆 Provider、Mem0、
-Hindsight 和 Graphiti 均未开始。
-
-## 当前架构
-
-```mermaid
-flowchart TB
-    EXT["外部 Agent<br/>自带人格与记忆"] --> MCP["rin-mcp<br/>无状态 STDIO 代理"]
-    USER["玩家"] --> CONSOLE["Rin Console<br/>监控、长目标、共享认知"]
-    INT["内部 Agent<br/>Persona / Memory / Skill / Model"] --> LOOP["AgentRuntime<br/>任务与决策循环"]
-    SIGNAL["Signal 收件箱"] --> LOOP
-    MCP --> CTRL["rin-control<br/>常驻控制进程"]
-    CONSOLE --> CTRL
-    LOOP --> CTRL
-    CTRL --> GATE["Action Gateway<br/>身份、控制租约、目标绑定"]
-    PLAN["PlanState<br/>复杂任务粗粒度进度"] <--> LOOP
-    MEM["SQLite Memory + FTS5<br/>可选远端 Embedding"] <--> LOOP
-    SKILL["Skill Catalog<br/>标准 SKILL.md"] --> LOOP
-    HOST["游戏 Host / Adapter"] -->|"Observation + Capability"| GATE
-    GATE -->|"ActionRequest"| HOST
-    HOST -->|"BoundAction + Effect"| POLICY["Gameplay Policy<br/>预算与最小规则"]
-    POLICY --> OPS["Operation Store<br/>投递、取消、恢复"]
-    OPS <-->|"ACK / Run / Outcome"| HOST
-    HOST --> ENGINE["实时游戏控制器"]
-    ENGINE --> WORLD["权威游戏世界 / Canon"]
-    WORLD --> HOST
-    OPS --> TIMELINE["Task Timeline"]
-    OPS --> MEM
-```
-
-关键边界：
-
-- 游戏世界与剧情 Canon 由 Adapter 持有；Rin Memory 只是可检索投影。
-- 模型选择目标和能力，但 Host 绑定实际对象与 Effect，Policy 决定是否允许。
-- `queued`、`accepted` 和 `running` 都不等于成功；只有 Host Outcome 可令
-  `execution_confirmed=true`。
-- 简单动作直接进入 Gateway；复杂任务才使用 PlanState，且不会每一步重新调用 Planner。
-- 外部 MCP 不依赖内部模型；内部 Agent 不会在外部 Controller 持有控制权时抢占角色。
-
-## 运行时拆分
-
-Rin 的 `AgentRuntime` 从约 1896 行降至 774 行，职责分别位于：
-
-- `context_assembly.go`：Persona、Memory、Skill 与 Observation 上下文装配。
-- `task_lifecycle.go`：任务创建、恢复、暂停和终态。
-- `plan_decision.go`：PlanDraft、模型决策和确定性重规划。
-- `action_operation.go`：动作提交、Operation 等待、Outcome 与下一轮协调。
-- `signal_scheduler.go`：只在内部主动模式下消费 Signal 并唤醒任务。
-
-rin-mi 的 `CompanionRuntime` 已提取动作分派、能力投影、主动调度、Operation 恢复和伙伴
-会话存储。末影龙闭环增加 Portal、跨维度、测向移动、地标搜索和 Boss 控制器后，该文件当前
-约 4260 行；新增实时执行逻辑均位于独立包内控制器，没有把 Minecraft 类型放进 Rin Core。
-进一步拆分必须以真人轨迹回放为保护，不在验收前进行大范围搬迁。
-
-## 自动验收证据
-
-| 范围 | 结果 |
-| --- | --- |
-| Rin Core | `make verify` 通过：契约、Vet、Race、Go 全仓测试 |
-| SDK | Python、JavaScript、C#、Java、Lua 测试通过 |
-| 示例 Adapter | Grid、Story、Terminal 测试通过 |
-| 构建 | macOS arm64、Windows amd64、Linux amd64 可执行文件生成成功 |
-| rin-mi | Core、Skill 校验、安装器、28/28 Fabric GameTest 通过 |
-| rin-mi 跨进程 | 真实 `rin-control` 下 V2 Binding 与 Internal Agent Macro 通过 |
-| ai-galgame | 328 个 Python 测试、Ren'Py Lint、内容与资源检查通过 |
-| ai-galgame 跨进程 | External 与 Internal 两条真实进程 E2E 通过 |
-
-ai-galgame 内容烟测覆盖 7 章、19 个交互回合、12 个桥接、13 个章节收束、7 段核心对话、
-6 个安静时刻和约 150 分钟规划内容。Lint 统计为 285 个对白块、18 个菜单、27 个图像和
-30 个 Screen。
-
-## 性能与 Token
-
-以下数据来自本机自动回归，只用于发现版本回退，不是跨机器性能承诺：
-
-| 项目 | P50 | P95 | 门限 |
-| --- | ---: | ---: | ---: |
-| SQLite Memory 检索 | 8.58ms | 9.59ms | P95 < 250ms |
-| PlanState 操作 | 0.14ms | 0.23ms | P95 < 100ms |
-
-脚本模型 Fixture 每次请求报告 100 Prompt、40 Completion、64 Cache Hit、36 Cache Miss Token。
-该数据证明字段从 Provider 传播到 Timeline，不能代表真实供应商的缓存节省。真实收益必须在
-配置实际模型后，比较同类任务的命中 Token、首 Token 延迟和总费用。
-
-## 破坏性清理
-
-按照“不保留旧版本兼容性”的决定，Rin 已删除文件记忆后端、对应测试和 `memory.json` 首次
-迁移入口。`memory.db` 是 Rin Memory 域唯一在线存储，JSONL 只用于显式导入导出。没有保留
-新旧双路执行。
-
-## 仍需真人验收
-
-1. 连续使用 2 至 4 小时：Minecraft 至少 90 分钟，内部与外部控制各至少 45 分钟；视觉小说
-   至少 45 分钟。
-2. Minecraft 覆盖采集、制作、建造、生存、战斗、重规划、控制权切换、急停和重启；
-   特别检查复杂地形、跨维度迁移、下界要塞/要塞搜索、末影之眼测向和完整末影龙新世界通关。
-3. 视觉小说覆盖固定剧情、AI ScenePacket、关键选择、主动话题、Canon 冲突、存读档、回滚和
-   Internal/External 切换，并判断对白是否自然。
-4. 解锁桌面后运行 Ren'Py 原生 Testcase，检查 1280x720、1536x864、1920x1080 UI；在真实
-   Windows 环境启动发布包。
-5. 真人试听不同角色 TTS，确认日语读音、停顿、音色绑定和无声降级；审阅剧情与美术。
-6. 人工对照 Timeline，确认公开理由、Memory/Skill Ref、Token、Policy 与 Outcome 能解释实际
-   游玩，且没有泄露 Prompt、私有记忆或凭据。
-
-## 已知限制
-
-- GameTest 启动时可能出现缺省 `server.properties`、Yggdrasil 网络超时和上游弃用警告；测试
-  服务仍正常运行，28 个必需用例通过。
-- macOS 锁屏时 Ren'Py 无可用 Display，原生窗口测试没有被标记为通过。
-- 交叉编译只证明可生成 Windows/Linux 二进制，不替代目标系统运行。
-- 自动轨迹证明协议与终态一致，不证明角色“像活人”的主观体验。
-
-## 阶段提交
-
-本报告之前的 Rin 阶段：`ce16d21`、`81f8bb5`、`c70642d`；Console 时间线与文档收口位于
-包含本报告的提交中。本轮 rin-mi：`28690cd`、`f7f31da`。
-
-真人验收完成并由用户确认前，不开始 ExternalMemoryProvider SPI 或任何具体外挂记忆适配器。
diff --git a/docs/task-timeline.md b/docs/task-timeline.md
index d13fe08..8ae1ebd 100644
--- a/docs/task-timeline.md
+++ b/docs/task-timeline.md
@@ -28,7 +28,7 @@ the authoritative Host reported completion.
 Use the local daemon CLI:
 
 ```sh
-RIN_CONTROL_TOKEN='<local-token>' rin tasks timeline <task-id> --follow
+RIN_CONTROL_TOKEN='<local-token>' ./bin/rin tasks timeline <task-id> --follow
 ```
 
 Add `--json` to write one contract page per line. A consumer resumes from the
diff --git a/docs/task-timeline.zh-CN.md b/docs/task-timeline.zh-CN.md
index c4057b1..f9e497b 100644
--- a/docs/task-timeline.zh-CN.md
+++ b/docs/task-timeline.zh-CN.md
@@ -23,7 +23,7 @@ Skill 正文、行动参数或 Host 私有输出。调用方提交的 Goal 和
 通过本地 Daemon CLI 查看：
 
 ```sh
-RIN_CONTROL_TOKEN='<本地令牌>' rin tasks timeline <task-id> --follow
+RIN_CONTROL_TOKEN='<本地令牌>' ./bin/rin tasks timeline <task-id> --follow
 ```
 
 增加 `--json` 后，每行输出一个契约页面。调用方使用不透明的 `next_cursor` 续读，不能把
diff --git a/examples/README.md b/examples/README.md
index a31f1ce..c4661a7 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -20,7 +20,8 @@ go test ./examples/adapters/grid
 
 [adapters/story](adapters/story/) applies the same HostKit contract to
 dialogue, relationship changes, story progress, and enforceable character
-boundaries.
+boundaries. Its integration tests drive the scene through both the internal
+Agent Runtime and an in-memory MCP session.
 
 ~~~sh
 go test ./examples/adapters/story
@@ -29,14 +30,20 @@ go test ./examples/adapters/story
 ## Terminal story
 
 [terminal-story](terminal-story/) is a runnable end-to-end slice. It proves
-that the internal Agent Runtime and an external MCP client share the same
-policy and authoritative Operation path.
+that an embedded Host and an in-process controller carrying external decision
+authority use the shared policy and authoritative Operation path.
 
 ~~~sh
 go run ./examples/terminal-story --line "The light feels familiar." --json
 ~~~
 
-Real game adapters belong in their own repositories. Use "rin init host" for a
-portable contract skeleton, then validate the game-owned authority thread,
-save identity, policy, idempotency, cancellation, restart, and emergency-stop
-boundaries in the actual game.
+Real game adapters belong in their own repositories. Generate a portable
+contract skeleton with the [Host scaffolding workflow](../docs/host-scaffolding.md):
+
+~~~sh
+./bin/rin init host -engine custom -runtime java -id my_game_host -output ./my-game-host
+~~~
+
+Then validate the game-owned authority thread, save identity, policy,
+idempotency, cancellation, restart, and emergency-stop boundaries in the
+actual game.
diff --git a/examples/README.zh-CN.md b/examples/README.zh-CN.md
index 7bb064f..439b6f2 100644
--- a/examples/README.zh-CN.md
+++ b/examples/README.zh-CN.md
@@ -17,7 +17,8 @@ go test ./examples/adapters/grid
 ## Story Adapter
 
 [adapters/story](adapters/story/) 把同一套 HostKit 契约用于对白、关系变化、剧情
-推进和可强制执行的角色边界。
+推进和可强制执行的角色边界。其集成测试会通过内部 Agent Runtime 和 MCP 内存会话
+分别驱动该场景。
 
 ~~~sh
 go test ./examples/adapters/story
@@ -25,12 +26,18 @@ go test ./examples/adapters/story
 
 ## Terminal Story
 
-[terminal-story](terminal-story/) 是可运行的端到端切片，用于证明内部 Agent
-Runtime 与外部 MCP Client 共用相同的策略和权威 Operation 执行链。
+[terminal-story](terminal-story/) 是可运行的端到端切片，用于证明嵌入式 Host 与
+携带外部决策权限的进程内 Controller 会经过共用策略和权威 Operation 执行链。
 
 ~~~sh
 go run ./examples/terminal-story --line "The light feels familiar." --json
 ~~~
 
-真实游戏 Adapter 应位于自己的仓库。先用 "rin init host" 生成可移植契约骨架，再
-在真实游戏中验证权威线程、存档身份、策略、幂等、取消、重启与急停边界。
+真实游戏 Adapter 应位于自己的仓库。按照 [Host 脚手架流程](../docs/host-scaffolding.zh-CN.md)
+生成可移植契约骨架：
+
+~~~sh
+./bin/rin init host -engine custom -runtime java -id my_game_host -output ./my-game-host
+~~~
+
+然后在真实游戏中验证权威线程、存档身份、策略、幂等、取消、重启与急停边界。
diff --git a/examples/terminal-story/README.md b/examples/terminal-story/README.md
index 072e0fe..8f8cfab 100644
--- a/examples/terminal-story/README.md
+++ b/examples/terminal-story/README.md
@@ -2,10 +2,11 @@
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
-Terminal Story is a dependency-free, embedded Control V2 example. It proves
-that a non-combat game can expose dialogue and story progression through the
-same engine-neutral Adapter, Effect Policy, controller lease, Operation, and
-authoritative Outcome path used by other game integrations.
+Terminal Story is a self-contained, embedded Control V2 example that requires
+no model, API key, or external service. It proves that a non-combat game can
+expose dialogue and story progression through the same engine-neutral Adapter,
+Effect Policy, controller lease, Operation, and authoritative Outcome path used
+by other game integrations.
 
 The reference scene offers four typed capabilities:
 
@@ -47,10 +48,10 @@ go run ./examples/terminal-story \
   --task restore-photograph
 ```
 
-The command runs an embedded Host and external semantic controller. It does
-not call a model and requires no API key. The integration tests additionally
-drive the same scene through the internal Agent Runtime and a real in-memory
-MCP session:
+The command runs an embedded Host and an in-process controller carrying
+external decision authority. It does not start the internal Agent Runtime or an
+MCP client. The integration tests additionally drive the same scene through the
+internal Agent Runtime and a real in-memory MCP session:
 
 ```bash
 go test ./examples/adapters/story
diff --git a/examples/terminal-story/README.zh-CN.md b/examples/terminal-story/README.zh-CN.md
index 7c99e21..3169857 100644
--- a/examples/terminal-story/README.zh-CN.md
+++ b/examples/terminal-story/README.zh-CN.md
@@ -2,9 +2,9 @@
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
-终端故事是一个零外部依赖、嵌入式的 Control V2 示例。它用于证明非战斗类游戏也能
-通过引擎无关的 Adapter、Effect Policy、控制权租约、Operation 和权威 Outcome
-接入 Rin，并与其他游戏适配器共用同一条执行链。
+终端故事是一个不需要模型、API Key 或外部服务的自包含嵌入式 Control V2 示例。
+它用于证明非战斗类游戏也能通过引擎无关的 Adapter、Effect Policy、控制权租约、
+Operation 和权威 Outcome 接入 Rin，并与其他游戏适配器共用同一条执行链。
 
 参考场景提供四个强类型能力：
 
@@ -44,8 +44,9 @@ go run ./examples/terminal-story \
   --task restore-photograph
 ```
 
-该命令运行嵌入式 Host 和外部语义控制器，不会调用模型，也不需要 API Key。集成测试
-还会使用内部 Agent Runtime 和真实的 MCP 内存会话驱动同一个场景：
+该命令运行嵌入式 Host，以及携带外部决策权限的进程内 Controller；它不会启动内部
+Agent Runtime 或 MCP Client。集成测试还会使用内部 Agent Runtime 和真实的 MCP
+内存会话驱动同一个场景：
 
 ```bash
 go test ./examples/adapters/story
diff --git a/sdk/README.md b/sdk/README.md
index d55b6eb..711a85a 100644
--- a/sdk/README.md
+++ b/sdk/README.md
@@ -15,9 +15,11 @@ daemon; they do not embed models, policy, or game execution logic.
 | Lua | 5.1+ | callback | engine-supplied HTTP and JSON adapters |
 | Go HostKit | Go 1.25 | `context.Context` | authority dispatch and V2 adapter coordination |
 
-## Common Control operations
+## Shared Control subset
 
-All five clients expose the same route set:
+All five language clients implement this shared client-facing Control subset.
+Additional authenticated Host, Signal, Agent, or task-plan coverage is
+language-specific and is documented in each language guide.
 
 - list worlds, actors, observations, and capabilities;
 - acquire, renew, and release the exclusive controller lease;
@@ -37,9 +39,16 @@ Every client enforces these boundaries:
 - default connection to `http://127.0.0.1:7375` or another explicit loopback origin;
 - a single-line bearer token of at least 32 bytes;
 - no HTTP redirects;
-- bounded timeout, response body, JSON depth, and safe integers;
+- bounded timeout and response body;
+- request-payload limits for JSON depth and safe integers;
 - rejection of invalid UTF-8, non-JSON responses, and contract mismatches;
-- distinct stable configuration, transport, protocol, and API errors.
+- stable error codes and bounded error records; language-specific exception or
+  callback shapes may differ.
+
+Use the [MCP and Host Control quick start](../docs/mcp-control-plane.md) as the
+source of truth for starting the daemon and handling its bearer token. Use the
+[Operation semantics](../docs/operations.md) as the source of truth for waiting,
+timeouts, terminal states, and authoritative outcomes.
 
 `queued`, `accepted`, and `running` are intermediate states. A caller may report
 game execution as complete only when the terminal operation has
diff --git a/sdk/README.zh-CN.md b/sdk/README.zh-CN.md
index 1e2c976..1701de3 100644
--- a/sdk/README.zh-CN.md
+++ b/sdk/README.zh-CN.md
@@ -15,9 +15,10 @@
 | Lua | 5.1+ | Callback | HTTP 与 JSON Adapter 由引擎注入 |
 | Go HostKit | Go 1.25 | `context.Context` | Authority Dispatch 与 V2 Adapter 协调 |
 
-## 公共 Control 操作
+## 共享 Control 子集
 
-五种客户端提供同一组路由：
+五种语言客户端都实现以下面向调用方的 Control 子集。额外的 Host、Signal、Agent
+或任务计划认证接口因语言而异，以各语言指南为准。
 
 - 读取世界、Actor、Observation 和 Capability；
 - 获取、续租和释放独占 Controller Lease；
@@ -36,9 +37,14 @@
 - 默认只连接 `http://127.0.0.1:7375` 或显式回环地址；
 - 要求至少 32 字节、无换行的 Bearer Token；
 - 禁止 HTTP Redirect；
-- 限制超时、响应体大小、JSON 深度和安全整数；
+- 限制超时和响应体大小；
+- 限制请求 Payload 的 JSON 深度和安全整数；
 - 拒绝非法 UTF-8、非 JSON 响应和不匹配的 `rin.control/v2`；
-- 将配置、传输、协议和 API 错误保持为可区分的稳定错误类型。
+- 返回稳定错误码和有界错误记录；具体异常类型或回调形式因语言而异。
+
+Daemon 启动与 Bearer Token 处理以 [MCP 与 Host Control 快速接入](../docs/mcp-control-plane.zh-CN.md)
+为准；等待、超时、终态和权威 Outcome 以 [Operation 语义](../docs/operations.zh-CN.md)
+为准。
 
 SDK 返回的 `queued`、`accepted` 或 `running` 只表示中间状态。调用方必须等待
 终态，并且只有 `execution_confirmed=true` 且存在 Host Outcome 时才可向用户报告
diff --git a/sdk/csharp/README.md b/sdk/csharp/README.md
index 3334016..5682688 100644
--- a/sdk/csharp/README.md
+++ b/sdk/csharp/README.md
@@ -22,8 +22,12 @@ var worlds = await control.ListWorldsAsync();
 
 Methods return `JsonElement`; inputs may be anonymous objects or ordinary DTOs.
 The default endpoint is `http://127.0.0.1:7375`. The client rejects redirects
-and bounds response size, JSON depth, timeout, and JavaScript-safe integers.
-
-Every asynchronous method accepts a `CancellationToken`. Cancellation or
-timeout means that the result is unknown, not that the game did not execute.
-Query the same operation until an authoritative terminal state is available.
+and bounds response size and timeout. Request payloads are limited by JSON
+depth and the JavaScript-safe integer range.
+
+Every asynchronous method accepts a `CancellationToken`. Cancellation or a
+network timeout while submitting or waiting does not prove that the game did
+not execute. If the Operation ID is known, query that Operation; otherwise,
+exactly retry the original submission with the same request and idempotency
+identity. Do not submit a new identity. See the
+[Operation recovery semantics](../../docs/operations.md).
diff --git a/sdk/csharp/README.zh-CN.md b/sdk/csharp/README.zh-CN.md
index ff526c4..ef9389b 100644
--- a/sdk/csharp/README.zh-CN.md
+++ b/sdk/csharp/README.zh-CN.md
@@ -21,8 +21,10 @@ var worlds = await control.ListWorldsAsync();
 ```
 
 方法返回 `JsonElement`，请求参数使用匿名对象或普通 DTO。默认地址是
-`http://127.0.0.1:7375`；客户端禁止 Redirect，并限制响应体、JSON 深度、超时
-和 JavaScript 安全整数范围。
+`http://127.0.0.1:7375`；客户端禁止 Redirect，并限制响应体大小和超时。请求
+Payload 还受 JSON 深度和 JavaScript 安全整数范围约束。
 
-所有异步方法接受 `CancellationToken`。取消或超时只说明结果未知，不能据此报告
-游戏没有执行；应重新查询同一个 Operation，直到得到权威终态。
+所有异步方法接受 `CancellationToken`。提交或等待期间发生取消或网络超时，不能证明
+游戏没有执行。已知 Operation ID 时应查询该 Operation；未知时只能用相同 Request
+和幂等身份精确重试原提交，不能换新身份重发。详见
+[Operation 恢复语义](../../docs/operations.zh-CN.md)。
diff --git a/sdk/java/README.md b/sdk/java/README.md
index 85a8a07..ff3a8fe 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
-The source-first Java 17 SDK contains three surfaces:
+The source-first Java 17 SDK contains four surfaces:
 
 - `RinControlClient`: asynchronous `rin.control/v2` client;
 - `/plans/v1/*` task-plan methods on the same client using raw JSON maps;
@@ -13,6 +13,7 @@ This repository does not promise a published Maven artifact. Pin a source
 revision and compile `src/main/java` into the integration.
 
 ```java
+// Integration sketch: implement this placeholder with the game's JSON library.
 JsonValueCodec codec = new YourJsonCodec();
 RinControlClient control = new RinControlClient(
     System.getenv("RIN_CONTROL_TOKEN"), codec);
@@ -21,10 +22,11 @@ control.info().thenAccept(System.out::println).join();
 control.listWorlds().thenAccept(System.out::println).join();
 ```
 
-The game implements `JsonValueCodec` using its existing JSON library, so Rin
-does not impose Jackson, Gson, or engine-specific serialization. The Control
-client uses the standard `java.net.http.HttpClient`, rejects redirects, bounds
-response bodies and timeouts, and returns `CompletableFuture` values.
+`YourJsonCodec` is a placeholder, not a class shipped by Rin. The game
+implements `JsonValueCodec` using its existing JSON library, so Rin does not
+impose Jackson, Gson, or engine-specific serialization. The Control client uses
+the standard `java.net.http.HttpClient`, rejects redirects, bounds response
+bodies and timeouts, and returns `CompletableFuture` values.
 
 `HostControlSession` only connects the game to the Control Daemon and carries
 V2 Host data. Target resolution, effect previews, authority-thread execution,
diff --git a/sdk/java/README.zh-CN.md b/sdk/java/README.zh-CN.md
index 89d0468..4ed6812 100644
--- a/sdk/java/README.zh-CN.md
+++ b/sdk/java/README.zh-CN.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | [简体中文](README.zh-CN.md)
 
-Java 17 source-first SDK 包含三部分：
+Java 17 source-first SDK 包含四部分：
 
 - `RinControlClient`：异步 `rin.control/v2` 客户端；
 - 同一客户端中的 `/plans/v1/*` 任务计划原始 JSON 方法；
@@ -13,6 +13,7 @@ Java 17 source-first SDK 包含三部分：
 `src/main/java` 编入你的项目。
 
 ```java
+// 集成草图：请用游戏采用的 JSON 库实现这个占位类型。
 JsonValueCodec codec = new YourJsonCodec();
 RinControlClient control = new RinControlClient(
     System.getenv("RIN_CONTROL_TOKEN"), codec);
@@ -21,9 +22,10 @@ control.info().thenAccept(System.out::println).join();
 control.listWorlds().thenAccept(System.out::println).join();
 ```
 
-`JsonValueCodec` 由游戏选择已经使用的 JSON 库实现，Rin 不额外绑定 Jackson、
-Gson 或引擎专用序列化器。Control Client 使用标准 `java.net.http.HttpClient`，
-禁止 Redirect，限制响应体和超时，并返回 `CompletableFuture`。
+`YourJsonCodec` 是占位类型，不是 Rin 提供的类。游戏应通过已经使用的 JSON 库实现
+`JsonValueCodec`，因此 Rin 不额外绑定 Jackson、Gson 或引擎专用序列化器。Control
+Client 使用标准 `java.net.http.HttpClient`，禁止 Redirect，限制响应体和超时，并
+返回 `CompletableFuture`。
 
 `HostControlSession` 只负责连接 Control Daemon 和传递 V2 Host 数据；目标解析、
 Effect Preview、主线程执行、取消和结果验证仍必须由游戏 Adapter 实现。
diff --git a/sdk/javascript/README.md b/sdk/javascript/README.md
index 655fc8b..b3c088d 100644
--- a/sdk/javascript/README.md
+++ b/sdk/javascript/README.md
@@ -6,24 +6,22 @@ A zero-dependency ESM `rin.control/v2` client for Node.js 18 and newer.
 
 The same client exposes the fixed `/plans/v1/*` task-plan routes as raw JSON methods.
 
-```javascript
-import { RinControlClient } from "./sdk/javascript/src/index.js";
+From the repository root, run the checked-in
+[quick start](examples/quickstart.js):
 
-const control = new RinControlClient({
-  token: process.env.RIN_CONTROL_TOKEN,
-});
-
-console.log(await control.info());
-console.log(await control.listWorlds());
+```bash
+node ./sdk/javascript/examples/quickstart.js
 ```
 
-The constructor supports `baseUrl`, `timeoutMs`, `maxResponseBytes`, and an
-injectable `fetch`. It defaults to `http://127.0.0.1:7375`, rejects redirects,
+The supported constructor forms are
+`new RinControlClient({ token, timeoutMs?, maxResponseBytes?, fetch? })` and
+`new RinControlClient(baseUrl, { token, timeoutMs?, maxResponseBytes?, fetch? })`.
+The first form defaults to `http://127.0.0.1:7375`. The client rejects redirects
 and bounds streamed response bodies.
 
-Requests and responses are ordinary JSON objects or arrays. See
-`api/control-openapi.json` for exact fields and `src/index.d.ts` for TypeScript
-declarations.
+Requests use ordinary JSON objects; responses may be JSON objects or arrays. See
+[`api/control-openapi.json`](../../api/control-openapi.json) for exact fields and
+[`src/index.d.ts`](src/index.d.ts) for TypeScript declarations.
 
 A resolved Promise is not proof that a game action completed. After submitting
 an action, use `waitOperation` to reach a terminal state and inspect
diff --git a/sdk/javascript/README.zh-CN.md b/sdk/javascript/README.zh-CN.md
index 38317b9..a846b6c 100644
--- a/sdk/javascript/README.zh-CN.md
+++ b/sdk/javascript/README.zh-CN.md
@@ -6,22 +6,21 @@
 
 同一客户端也通过原始 JSON 方法提供固定的 `/plans/v1/*` 任务计划接口。
 
-```javascript
-import { RinControlClient } from "./sdk/javascript/src/index.js";
+在仓库根目录运行现有的[快速开始](examples/quickstart.js)：
 
-const control = new RinControlClient({
-  token: process.env.RIN_CONTROL_TOKEN,
-});
-
-console.log(await control.info());
-console.log(await control.listWorlds());
+```bash
+node ./sdk/javascript/examples/quickstart.js
 ```
 
-构造器支持 `baseUrl`、`timeoutMs`、`maxResponseBytes` 和可注入的 `fetch`。
-默认只连接 `http://127.0.0.1:7375`，禁止 Redirect，并对流式响应执行大小限制。
+支持的构造形式是
+`new RinControlClient({ token, timeoutMs?, maxResponseBytes?, fetch? })`，或
+`new RinControlClient(baseUrl, { token, timeoutMs?, maxResponseBytes?, fetch? })`。
+第一种形式默认连接 `http://127.0.0.1:7375`。客户端禁止 Redirect，并限制流式
+响应大小。
 
-所有请求和响应都是普通 JSON Object/Array，精确字段见
-`api/control-openapi.json`。TypeScript 声明位于 `src/index.d.ts`。
+请求使用普通 JSON Object，响应可以是 JSON Object 或 Array；精确字段见
+[`api/control-openapi.json`](../../api/control-openapi.json)，TypeScript 声明见
+[`src/index.d.ts`](src/index.d.ts)。
 
 不要把 Promise resolve 等同于游戏执行完成；提交 Action 后应使用
 `waitOperation` 等待终态，并检查 `execution_confirmed` 与 Host `outcome`。
diff --git a/sdk/lua/README.md b/sdk/lua/README.md
index 54a9f31..43398c1 100644
--- a/sdk/lua/README.md
+++ b/sdk/lua/README.md
@@ -1,10 +1,15 @@
 # Rin Lua Control SDK
 
+[English](README.md) | [简体中文](README.zh-CN.md)
+
 This zero-dependency module calls the loopback-only `rin.control/v2` API from
 Lua game runtimes. The host engine supplies asynchronous HTTP and JSON
 adapters, while the SDK owns route selection, bearer authentication, input
 validation, response bounds, redirect rejection, and stable errors.
 
+The following is an engine-adapter integration sketch. The game runtime must
+provide the referenced HTTP, JSON, and logging functions.
+
 ```lua
 local rin = dofile("rin.lua")
 local control = assert(rin.new({
diff --git a/sdk/lua/README.zh-CN.md b/sdk/lua/README.zh-CN.md
index 9ac8141..7903f71 100644
--- a/sdk/lua/README.zh-CN.md
+++ b/sdk/lua/README.zh-CN.md
@@ -1,9 +1,13 @@
 # Rin Lua Control SDK
 
+[English](README.md) | [简体中文](README.zh-CN.md)
+
 这是一个零依赖的 `rin.control/v2` Lua 客户端，供游戏运行时连接本机 Control
 Daemon。游戏引擎负责提供异步 HTTP 和 JSON 编解码器；SDK 负责固定路由、Bearer
 鉴权、输入校验、响应大小限制、拒绝重定向和稳定错误码。
 
+下面是引擎 Adapter 的集成草图；其中的 HTTP、JSON 和日志函数必须由游戏运行时提供。
+
 ```lua
 local rin = dofile("rin.lua")
 local control = assert(rin.new({
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 26c0521..f94f7bf 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -7,6 +7,8 @@ A dependency-free `rin.control/v2` client for Python 3.9 and newer.
 The same client exposes the fixed `/plans/v1/*` task-plan and `/signals/v1/*`
 Signal Inbox routes as raw JSON methods.
 
+From the repository root:
+
 ```bash
 python3 -m pip install -e ./sdk/python
 ```
@@ -24,12 +26,13 @@ The default endpoint is `http://127.0.0.1:7375`. The constructor also accepts
 `base_url`, `timeout`, and `max_response_bytes`, while the URL must remain a
 credential-free loopback HTTP origin with no path.
 
-The client exposes every Control V2 route for worlds, actors, observations,
-capabilities, controller leases, actions, operations, emergency stop, and the
-Host register, publish, poll, acknowledgement, progress, and outcome lifecycle.
-It also configures, publishes, lists, and waits for bounded Actor signals.
-Payloads remain ordinary dictionaries; use the repository's
-`api/control-openapi.json` for exact fields.
+The authenticated routes wrapped by this client cover worlds, actors,
+observations, capabilities, controller leases, actions, operations, emergency
+stop, and the Host register, publish, poll, acknowledgement, progress, and
+outcome lifecycle. The client also wraps bounded Actor signals and task plans;
+it does not cover unauthenticated health endpoints. Payloads remain ordinary
+dictionaries; use the repository-root
+[`api/control-openapi.json`](../../api/control-openapi.json) for exact fields.
 
 Errors are separated into `RinConfigurationError`, `RinTransportError`,
 `RinProtocolError`, and `RinAPIError`. Never treat a timeout or `queued` status
diff --git a/sdk/python/README.zh-CN.md b/sdk/python/README.zh-CN.md
index d0a8941..52bc626 100644
--- a/sdk/python/README.zh-CN.md
+++ b/sdk/python/README.zh-CN.md
@@ -7,6 +7,8 @@
 同一客户端也通过原始 JSON 方法提供固定的 `/plans/v1/*` 任务计划和
 `/signals/v1/*` Signal Inbox 接口。
 
+在仓库根目录执行：
+
 ```bash
 python3 -m pip install -e ./sdk/python
 ```
@@ -23,11 +25,11 @@ print(control.list_worlds())
 默认只连接 `http://127.0.0.1:7375`。构造器可以配置 `base_url`、`timeout`
 和 `max_response_bytes`，但 URL 仍必须是无凭据、无路径的回环 HTTP Origin。
 
-客户端暴露世界、Actor、Observation、Capability、Controller Lease、Action、
-Operation、Emergency Stop，以及 Host 注册、发布、轮询、确认、进度和 Outcome
-生命周期的全部 Control V2 路由，同时支持配置、发布、列出和等待有界 Actor Signal。
-请求参数保持为普通 `dict`，
-字段以仓库根目录的 `api/control-openapi.json` 为准。
+该客户端封装的认证接口覆盖世界、Actor、Observation、Capability、Controller
+Lease、Action、Operation、Emergency Stop，以及 Host 注册、发布、轮询、确认、进度
+和 Outcome 生命周期；它还封装有界 Actor Signal 和任务计划接口，但不覆盖无需认证的
+健康检查端点。请求参数保持为普通 `dict`，字段以仓库根目录的
+[`api/control-openapi.json`](../../api/control-openapi.json) 为准。
 
 异常分为 `RinConfigurationError`、`RinTransportError`、`RinProtocolError` 和
 `RinAPIError`。不要把超时或 `queued` 当作执行成功；等待终态并检查