Disaster-Terminator · Disaster-Terminator · May 16, 2026 · May 16, 2026 · May 16, 2026 · May 16, 2026
diff --git a/README.en.md b/README.en.md
@@ -196,10 +196,12 @@ pnpm run probe:hermes-retinue
 ## Developer Docs
 
 - [Source install and development](docs/development/SOURCE_INSTALL.md)
+- [Architecture overview](docs/architecture/OVERVIEW.md)
 - [0.1.0 Release Notes](docs/release/v0.1.0_RELEASE_NOTES.md)
 - [0.1.0 Release Notes zh-CN](docs/release/v0.1.0_RELEASE_NOTES.zh-CN.md)
 - [0.1.0 Release Readiness](docs/release/0.1.0_RELEASE_PLAN.md)
 - [Docs index](docs/README.md)
+- [Documentation governance](docs/DOCUMENTATION_GOVERNANCE.md)
 - [Long-Term Vision](docs/LONG_TERM_VISION.md)
 - [Project Boundary](docs/architecture/PROJECT_BOUNDARY.md)
 - [Service Lifecycle](docs/deployment/SERVICE_LIFECYCLE.md)

diff --git a/README.md b/README.md
@@ -195,10 +195,12 @@ pnpm run probe:hermes-retinue
 ## 开发者文档
 
 - [源码安装和开发](docs/development/SOURCE_INSTALL.md)
+- [架构总览](docs/architecture/OVERVIEW.md)
 - [0.1.0 Release Notes](docs/release/v0.1.0_RELEASE_NOTES.md)
 - [0.1.0 发布说明（中文）](docs/release/v0.1.0_RELEASE_NOTES.zh-CN.md)
 - [0.1.0 发布就绪记录](docs/release/0.1.0_RELEASE_PLAN.md)
 - [Docs Index](docs/README.md)
+- [文档治理](docs/DOCUMENTATION_GOVERNANCE.md)
 - [Long-Term Vision](docs/LONG_TERM_VISION.md)
 - [Project Boundary](docs/architecture/PROJECT_BOUNDARY.md)
 - [Service Lifecycle](docs/deployment/SERVICE_LIFECYCLE.md)

diff --git a/docs/DOCUMENTATION_GOVERNANCE.md b/docs/DOCUMENTATION_GOVERNANCE.md
@@ -0,0 +1,104 @@
+# Documentation Governance
+
+Retinue documentation should stay useful for three groups:
+
+1. users who only want to install the Codex plugin and run a child agent;
+2. operators who need deployment defaults, diagnostics, and real-runtime probes;
+3. contributors who need to change the runtime safely.
+
+When one document starts serving multiple audiences, split it or add an audience note near the top.
+
+## Source Of Truth
+
+| Topic | Source of truth | Notes |
+| --- | --- | --- |
+| Product positioning and user quickstart | Root `README.md` and `README.en.md` | Keep these focused on the current user path. |
+| Documentation map | `docs/README.md` | Every durable doc should be reachable from here. |
+| Architecture and boundary | `docs/architecture/OVERVIEW.md` and `docs/architecture/PROJECT_BOUNDARY.md` | Stable concepts, data flow, and non-goals. |
+| OpenCode behavior | `docs/backends/OPENCODE.md` | Default backend behavior, access mode, diagnostics, and adapter notes. |
+| Codex plugin packaging | `docs/deployment/PLUGIN_DEPLOYMENT.md` | Plugin install shape, bundled runtime, cache behavior, and production E2E boundary. |
+| Source development | `docs/development/SOURCE_INSTALL.md` | Contributor setup, build, tests, hooks, and source-tree verification. |
+| Release facts | `docs/release/*` | Versioned release notes and readiness records. Do not silently rewrite old release history. |
+| Agent-facing behavior | `plugins/retinue/skills/retinue/SKILL.md` | Keep aligned with product MCP tools and safety defaults. |
+| Hermes integration | `docs/integrations/HERMES.md` and `integrations/hermes/*` | Hermes is an MCP host integration, not a Retinue backend. |
+
+## Document Types
+
+Use these categories consistently:
+
+- **README / quickstart**: current user path only; avoid implementation history.
+- **Architecture**: stable concepts, data flow, boundaries, and non-goals.
+- **Backend contract**: runtime-specific behavior and environment knobs.
+- **Deployment**: installation shape, packaging, plugin cache, and operational defaults.
+- **Development**: source checkout, tests, local probes, generated artifacts.
+- **Runbook**: concrete steps for a real environment or incident class.
+- **Release**: versioned records; historical once published.
+- **Archive**: old reviews, metadata notes, and superseded records kept for traceability.
+
+Research notes and speculative plans should stay under `docs/research/` or `docs/superpowers/` unless they are promoted into the docs index as current guidance.
+
+## Required Updates When Behavior Changes
+
+| Change | Docs to check |
+| --- | --- |
+| Product MCP tool added or removed | Root READMEs, architecture overview, Retinue skill doc |
+| Backend default or backend selection behavior changes | Root READMEs, architecture overview, backend doc, plugin deployment doc |
+| OpenCode auto-serve, port, timeout, or access-mode behavior changes | OpenCode backend doc, root READMEs, plugin deployment doc, skill doc |
+| Plugin manifest, `.mcp.json`, bootstrap, or cache behavior changes | Plugin deployment doc, source install doc, root READMEs if user-visible |
+| New environment variable | Relevant backend or deployment doc; root README only if normal users need it |
+| State directory, log field, artifact, or diagnostic shape changes | Backend doc, deployment doc, runbooks, verification docs |
+| Release process or package contents change | Release docs, source install doc, plugin deployment doc |
+| Hermes integration changes | Hermes integration docs and `integrations/hermes/*` |
+
+If a change is intentionally internal and not user-visible, say that in the PR body instead of forcing noisy README edits.
+
+## Style Rules
+
+- Prefer current behavior over project history.
+- Put commands in copyable fenced blocks.
+- Mark risky or environment-mutating steps explicitly.
+- Keep secrets, tokens, account names, and API keys out of docs and traces.
+- Use concrete tool names such as `retinue_spawn_agent`.
+- Distinguish product tools from raw adapter/debug tools.
+- Avoid claiming a real-runtime path is verified unless a real probe has passed.
+- Use absolute paths in examples when workspace drift would matter.
+- Keep Chinese and English READMEs semantically aligned when the user-facing install path changes.
+
+## Documentation PR Checklist
+
+```markdown
+## Documentation checklist
+
+- [ ] I identified the audience for each changed doc.
+- [ ] I kept root README changes focused on current user paths.
+- [ ] I updated `docs/README.md` when adding durable docs.
+- [ ] I checked whether the Retinue skill guidance needs the same behavior update.
+- [ ] I did not rewrite historical release notes except for typo/link fixes.
+- [ ] I avoided secrets, local credentials, and unredacted provider details.
+- [ ] I recorded whether verification was docs-only or included runtime gates.
+```
+
+For docs-only PRs, the minimum verification is a link/path review plus Markdown readability. Runtime gates are not required unless the doc claims a command or real probe currently works.
+
+## Archive Policy
+
+Move documents to `docs/archive/` when they are useful for traceability but no longer represent current product guidance. Add a short note at the top when practical:
+
+```markdown
+> Archived: this page records historical context and is not current setup guidance.
+```
+
+Do not delete release records or old review notes just because a newer path exists. Prefer demotion from the docs index to archive over deletion.
+
+## Keeping The Docs Navigable
+
+`docs/README.md` should remain the stable map for durable docs. Keep it grouped by user intent:
+
+- current product and architecture;
+- installation and deployment;
+- development and verification;
+- real-runtime runbooks;
+- release records;
+- archive and research.
+
+A new doc that is not linked from `docs/README.md` should be treated as temporary or incomplete.
diff --git a/docs/README.md b/docs/README.md
@@ -1,37 +1,44 @@
 # Retinue Docs
 
-Start here. Current product guidance is separated from historical notes so the root `docs/`
-directory stays readable.
+Start here when you need more detail than the root README. This index separates current product guidance from deployment notes, development docs, runbooks, release records, and archive material.
 
-## Current Product
+## Current Product And Architecture
 
-- [0.1.0 Release Readiness](release/0.1.0_RELEASE_PLAN.md) - release boundary, closed work, release gate, and deferred issues.
-- [0.1.0 Hardening Record](release/0.1.0_HARDENING_ISSUES.md) - closed smoke/E2E issues and current verification requirements.
-- [v0.1.0 Release Notes](release/v0.1.0_RELEASE_NOTES.md) - user-facing release summary.
-- [v0.1.0 Release Notes zh-CN](release/v0.1.0_RELEASE_NOTES.zh-CN.md) - Chinese reference.
-- [Long-Term Vision](LONG_TERM_VISION.md) - Codex-compatible spawn direction, backend policy, and phased roadmap.
+- [Architecture Overview](architecture/OVERVIEW.md) - runtime shape, product tool surface, lifecycle, backend notes, and safety defaults.
 - [Project Boundary](architecture/PROJECT_BOUNDARY.md) - what Retinue is and is not.
-- [OpenCode Backend](backends/OPENCODE.md) - OpenCode adapter behavior and constraints.
+- [OpenCode Backend](backends/OPENCODE.md) - default backend behavior, auto-serve policy, access mode, diagnostics, and raw adapter surfaces.
+- [Long-Term Vision](LONG_TERM_VISION.md) - Codex-compatible spawn direction, backend policy, and phased roadmap.
+- [Documentation Governance](DOCUMENTATION_GOVERNANCE.md) - source-of-truth map, behavior-change update matrix, style rules, PR checklist, and archive policy.
+
+## Installation And Deployment
+
+- [Plugin Deployment](deployment/PLUGIN_DEPLOYMENT.md) - Codex plugin packaging, installed plugin cache shape, local diagnostics, and production E2E boundary.
+- [Service Lifecycle](deployment/SERVICE_LIFECYCLE.md) - daemon start, inspect, and stop workflow.
 - [Hermes Agent Integration](integrations/HERMES.md) - Hermes native MCP setup for calling Retinue/OpenCode.
 
-## Deployment
+## Development And Verification
 
-- [Plugin Deployment](deployment/PLUGIN_DEPLOYMENT.md) - Codex plugin packaging and install shape.
-- [Source Install And Development](development/SOURCE_INSTALL.md) - contributor setup and source-tree verification.
+- [Source Install And Development](development/SOURCE_INSTALL.md) - contributor setup, source-tree verification, local gates, and probe commands.
 - [Plugin Reload Workflow](development/PLUGIN_RELOAD.md) - fast WSL/Windows cache sync during plugin development.
-- [Service Lifecycle](deployment/SERVICE_LIFECYCLE.md) - daemon start, inspect, and stop workflow.
 - [Verification](VERIFICATION.md) - short test and packaging gates.
 
 ## Real Runtime Runbooks
 
 - [Production OpenCode E2E](runbooks/PRODUCTION_OPENCODE_E2E.md)
-- [Real Claude Code Probes](runbooks/REAL_CLAUDE_PROBES.md)
 - [Real OpenCode Probes](runbooks/REAL_OPENCODE_PROBES.md)
+- [Real Claude Code Probes](runbooks/REAL_CLAUDE_PROBES.md)
+
+## Release Records
+
+- [0.1.0 Release Readiness](release/0.1.0_RELEASE_PLAN.md) - release boundary, closed work, release gate, and deferred issues.
+- [0.1.0 Hardening Record](release/0.1.0_HARDENING_ISSUES.md) - closed smoke/E2E issues and current verification requirements.
+- [v0.1.0 Release Notes](release/v0.1.0_RELEASE_NOTES.md) - user-facing release summary.
+- [v0.1.0 Release Notes zh-CN](release/v0.1.0_RELEASE_NOTES.zh-CN.md) - Chinese reference.
 
-## Archive
+## Archive And Research
 
 - [Verification History](archive/VERIFICATION_HISTORY.md)
 - [PR #58 Static Review](archive/PR58_STATIC_REVIEW.md)
 - [Repository Metadata Notes](archive/REPOSITORY_METADATA.md)
 
-Implementation plans and research notes remain under `docs/superpowers/` and `docs/research/`.
+Implementation plans and research notes remain under `docs/superpowers/` and `docs/research/`. They are not current product guidance unless this index explicitly promotes them into the sections above.
diff --git a/docs/architecture/OVERVIEW.md b/docs/architecture/OVERVIEW.md
@@ -0,0 +1,110 @@
+# Architecture Overview
+
+Retinue is a local subagent lifecycle layer for Codex-like MCP clients. The host agent delegates a coding task to an installed local agent runtime, gets a job handle quickly, and later polls, reads, closes, or cleans that job.
+
+Retinue is intentionally narrow:
+
+- more durable than a one-shot MCP wrapper, because it keeps job state and artifacts;
+- smaller than a platform, because it does not route providers, choose models, host queues, or replace OpenCode / Claude Code.
+
+For the formal scope, see [Project Boundary](PROJECT_BOUNDARY.md).
+
+## Runtime Shape
+
+```text
+Codex or another MCP client
+  -> Retinue skill and MCP tools
+    -> Retinue lifecycle API
+      -> backend adapter
+        -> OpenCode server or Claude Code CLI
+      -> local state and bounded artifacts
+```
+
+Backend choice is deployment configuration. The caller should use the product `retinue_*` tools rather than choosing OpenCode or Claude Code from each request.
+
+## Product Tool Surface
+
+| Tool | Purpose |
+| --- | --- |
+| `retinue_spawn_agent` | Start a child job through the configured backend and return a `jobId` with metadata. |
+| `retinue_wait_agent` | Wait within a host-safe window and return either terminal output or running diagnostics. |
+| `retinue_close_agent` | Close a child job and remove it from the active MCP-session pool. |
+| `retinue_list_agents` | List active child jobs tracked by the current MCP server session. |
+
+Backend-specific `opencode_*` and `claude_*` tools are adapter/debug surfaces. They should stay hidden in normal plugin deployments unless `RETINUE_EXPOSE_BACKEND_TOOLS=1` is deliberately enabled.
+
+## Components
+
+| Component | Owns | Does not own |
+| --- | --- | --- |
+| MCP host | Deciding what to delegate and when to poll or close the child. | Backend profile, provider login, model routing. |
+| Retinue MCP server | Product tools, wait limits, active child-agent slots. | Cloud orchestration or provider choice. |
+| Lifecycle API | Job metadata, status, result, continuation, close, cleanup. | Agent-runtime internals. |
+| Backend adapter | Translating lifecycle operations to OpenCode or Claude Code. | Reimplementing a full agent client. |
+| OpenCode / Claude Code | Provider credentials, model defaults, profile policy, plugins, permissions. | Retinue job-state semantics. |
+| State directory | Metadata, stdout/stderr logs, traces, artifact paths. | Long-term memory or credential storage. |
+
+## Job Lifecycle
+
+A normal product flow is:
+
+1. The host calls `retinue_spawn_agent` with a prompt, task name, and preferably an absolute `cwd`.
+2. Retinue records job metadata and starts or attaches to the configured backend runtime.
+3. Retinue returns a `jobId` without blocking the root agent on the whole child task.
+4. The host calls `retinue_wait_agent` until the job reaches a terminal state.
+5. Running responses include bounded output tails, artifact paths, and compact diagnostics.
+6. Terminal responses include the result or an attention-required status such as failure or stall.
+7. The host calls `retinue_close_agent` when the child is no longer needed.
+
+Each MCP server session keeps a small active child-agent pool. The default is 3 active children, matching the practical shape of three children plus one root thread.
+
+## Backend Notes
+
+OpenCode is the default 0.1.0 backend. The plugin deployment starts or attaches to a loopback OpenCode server and asks OpenCode to use the `plan` agent by default:
+
+```text
+RETINUE_BACKEND=opencode
+RETINUE_OPENCODE_AUTO_SERVE=1
+RETINUE_OPENCODE_HOST=127.0.0.1
+RETINUE_OPENCODE_AGENT=plan
+```
+
+Retinue-managed OpenCode prefers `127.0.0.1:4096` and can fall back through `4097` to `4127` when earlier ports are already used by external services. OpenCode still owns provider configuration, login, model defaults, endpoint routing, plugins, skills, and profile policy. See [OpenCode Backend](../backends/OPENCODE.md).
+
+Claude Code is available as an alternate backend for deployments that set:
+
+```text
+RETINUE_BACKEND=claude-code
+```
+
+Claude Code still owns its own model, endpoint, quota, permission, and profile behavior.
+
+## Safety And Observability Defaults
+
+Retinue defaults to local, bounded behavior:
+
+- prompts are kept out of child-agent process arguments;
+- default status responses do not include full prompts;
+- MCP responses return bounded output tails and artifact paths instead of unbounded logs;
+- OpenCode product spawns are read-only by default;
+- managed local services bind to loopback by default;
+- stale or corrupted state should become an explicit status rather than fake success;
+- real backend probes are still required because static tests cannot catch every local runtime contract drift.
+
+Common diagnostic paths under `RETINUE_STATE_DIR`:
+
+```text
+<stateDir>/logs/retinue.jsonl
+<stateDir>/jobs/<jobId>/meta.json
+<stateDir>/jobs/<jobId>/stdout.log
+<stateDir>/jobs/<jobId>/stderr.log
+```
+
+## What To Read Next
+
+- [Project Boundary](PROJECT_BOUNDARY.md)
+- [OpenCode Backend](../backends/OPENCODE.md)
+- [Plugin Deployment](../deployment/PLUGIN_DEPLOYMENT.md)
+- [Source Install And Development](../development/SOURCE_INSTALL.md)
+- [Hermes Agent Integration](../integrations/HERMES.md)
+- [Documentation Governance](../DOCUMENTATION_GOVERNANCE.md)