docs: add documentation governance and architecture overview

[Disaster-Terminator]

Superseded by #63, rebuilt on the latest main baseline (f05b156). Closing this older PR to avoid reviewing a stale branch.

[qodo-code-review]

Qodo reviews are paused for this user.

Troubleshooting steps vary by plan Learn more →

On a Teams plan?
Reviews resume once this user has a paid seat and their Git account is linked in Qodo.
Link Git account →

Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center?
These require an Enterprise plan - Contact us
Contact us →

[sourcery-ai]

审阅者指南

新增两篇文档（架构总览和文档治理指南），并重新组织文档索引和根目录 README，以便更好地呈现这些文档，并更清晰地映射产品、部署、开发和历史文档，而不改变任何运行时行为。

文件级变更

变更	详情	文件
引入一份详细的架构总览，描述 Retinue 的运行时形态、组件、任务生命周期、后端配置，以及安全性/可观测性的默认设置。	记录从 MCP 宿主到 Retinue 工具，再到后端和本地状态的高层运行时数据流。 定义产品的 MCP 工具界面，并澄清与后端相关的调试/适配器工具。 描述 MCP 宿主、 Retinue server、生命周期 API、后端以及状态目录之间的组件职责和所有权边界。 明确正常任务生命周期步骤、活动子任务上限以及后端选择行为（OpenCode 为默认，Claude Code 为可选）。 记录安全默认值、可观测性路径以及推荐的下一步阅读文档。	docs/architecture/OVERVIEW.md
建立文档治理指南，包括事实来源、文档类型、行为变更时的必要更新、风格、PR 清单、归档策略以及文档索引的所有权。	为关键主题定义权威位置，例如产品定位、架构、后端行为、部署、开发、发布事实以及技能使用指引。 标准化文档类别（README、架构、后端契约、部署、开发、运行手册、发布、归档、研究）。 引入一个针对运行时和产品变更的「变更类型 → 文档更新」矩阵。 设定文档风格规则，以及双语 README 对齐和安全卫生方面的期望。 添加可复用的以文档为中心的 PR 检查清单和归档策略，包括对 docs/README 作为稳定导航图的预期。	docs/DOCUMENTATION_GOVERNANCE.md
将文档索引重新组织为更清晰、基于意图的导航图，并澄清哪些文档属于当前产品指引，哪些属于研究/归档。	重新命名并分组章节为：当前产品与架构、安装与部署、开发与验证、真实运行时运行手册、发布记录，以及归档与研究。 在合适的章节中链接新的架构总览和文档治理文档。 增强现有链接描述（Project Boundary、OpenCode Backend、Plugin Deployment、Source Install 以及运行手册），以更好地反映内容和目标读者。 澄清研究/“superpowers” 文档不属于当前产品指引，除非已通过索引显式提升为此用途。	docs/README.md
在英文和中文根目录 README 中同时呈现新的架构总览和文档治理文档，以保持开发者入口的一致性。	在英文 README 的 Developer Docs 部分添加指向架构总览和文档治理文档的链接。 在中文 README 的开发者文档部分添加对应链接（架构总览、文档治理），以保持语义一致。	README.en.md README.md

---

提示与命令

与 Sourcery 交互

• 触发新评审： 在 pull request 上评论 @sourcery-ai review。
• 继续讨论： 直接回复 Sourcery 的评审评论。
• 从评审评论生成 GitHub issue： 在评审评论下回复，请求 Sourcery 从该评论创建 issue。你也可以直接回复评审评论 @sourcery-ai issue 来从中创建 issue。
• 生成 pull request 标题： 在 pull request 标题中任意位置写上 @sourcery-ai，即可随时生成标题。你也可以在 pull request 中评论 @sourcery-ai title 来（重新）生成标题。
• 生成 pull request 摘要： 在 pull request 正文任意位置写上 @sourcery-ai summary，即可在该位置生成 PR 摘要。你也可以在 pull request 中评论 @sourcery-ai summary 来（重新）生成摘要。
• 生成审阅者指南： 在 pull request 上评论 @sourcery-ai guide，即可随时（重新）生成审阅者指南。
• 解决所有 Sourcery 评论： 在 pull request 上评论 @sourcery-ai resolve，即可标记解决所有 Sourcery 评论。适用于你已经处理完所有评论且不再希望看到它们的情况。
• 撤销所有 Sourcery 评审： 在 pull request 上评论 @sourcery-ai dismiss，即可撤销所有现有 Sourcery 评审。当你想从头开始新的评审时特别有用——别忘了再评论 @sourcery-ai review 来触发新评审！

自定义使用体验

访问你的 控制面板 以：

• 启用或禁用评审功能，例如 Sourcery 生成的 pull request 摘要、审阅者指南等。
• 更改评审语言。
• 添加、删除或编辑自定义评审说明。
• 调整其他评审设置。

获取帮助

• 如有问题或反馈，请联系我们的支持团队。
• 访问我们的文档以获取详细指南和信息。
• 通过关注我们的 X/Twitter、LinkedIn 或 GitHub 与 Sourcery 团队保持联系。

Original review guide in English

Reviewer's Guide

Adds two new docs (an architecture overview and a documentation governance guide) and reorganizes the docs index and root READMEs to surface them and better map product, deployment, development, and historical documentation, without changing any runtime behavior.

File-Level Changes

Change	Details	Files
Introduce a detailed architecture overview describing Retinue’s runtime shape, components, job lifecycle, backend configuration, and safety/observability defaults.	Document high-level runtime data flow from MCP host through Retinue tools to backends and local state. Define the product MCP tool surface and clarify backend-specific debug/adaptor tools. Describe component responsibilities and ownership boundaries across MCP host, Retinue server, lifecycle API, backends, and state directory. Specify normal job lifecycle steps, active-child limits, and backend selection behavior (OpenCode default, Claude Code optional). Record safety defaults, observability paths, and suggested next-docs to read.	docs/architecture/OVERVIEW.md
Establish documentation governance guidelines, including sources of truth, doc types, required updates on behavior changes, style, PR checklist, archiving, and docs index ownership.	Define authoritative locations for key topics such as product positioning, architecture, backend behavior, deployment, development, release facts, and skill guidance. Standardize documentation categories (README, architecture, backend contract, deployment, development, runbook, release, archive, research). Introduce a change-type_to-doc-update matrix for runtime and product changes. Set documentation style rules and expectations for bilingual README alignment and security hygiene. Add a reusable documentation-focused PR checklist and archive policy, including expectations around docs/README as the stable map.	docs/DOCUMENTATION_GOVERNANCE.md
Reorganize the docs index into a clearer, intent-based navigation map and clarify which docs count as current product guidance versus research/archive.	Retitle and regroup sections into Current Product and Architecture, Installation and Deployment, Development and Verification, Real Runtime Runbooks, Release Records, and Archive and Research. Link the new architecture overview and documentation governance docs in the appropriate sections. Enhance existing link descriptions for Project Boundary, OpenCode Backend, Plugin Deployment, Source Install, and runbooks to better reflect content and audience. Clarify that research/superpowers docs are not current product guidance unless explicitly promoted via the index.	docs/README.md
Surface the new architecture overview and documentation governance docs from both English and Chinese root READMEs to keep developer entry points aligned.	Add links to the architecture overview and documentation governance docs in the English README’s Developer Docs section. Add corresponding links (架构总览, 文档治理) in the Chinese README’s developer docs section to maintain semantic parity.	README.en.md README.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - 我在这里给了一些高层次的反馈：

• 在 docs/architecture/OVERVIEW.md 中，你提到了 RETINUE_STATE_DIR 和状态目录，但没有说明它的默认值是什么，或者它通常在磁盘上的位置——如果能补充一小段关于默认位置或它是如何推导出来的说明，将会让诊断部分更直接有用。
• 新增的 OVERVIEW.md 和 DOCUMENTATION_GOVERNANCE.md 文件在正文中谈到了读者对象的定位，但根据治理指南，如果能在每个文件顶部附近添加一行明确的读者说明（例如：“Audience: operators and contributors”），就能帮助读者快速判断该页面是给谁看的。

供 AI 代理使用的提示

Please address the comments from this code review:

## Overall Comments
- In `docs/architecture/OVERVIEW.md`, you reference `RETINUE_STATE_DIR` and state directories but don’t say what the default is or where it typically lives on disk—adding a short note about the default location or how it’s derived would make the diagnostics section more immediately useful.
- The new `OVERVIEW.md` and `DOCUMENTATION_GOVERNANCE.md` files talk about audience targeting in the body, but per the governance guidance it would help to add an explicit, one-line audience note near the top of each file (e.g., “Audience: operators and contributors”) so readers can quickly tell who the page is for.

---

Sourcery 对开源项目是免费的——如果你觉得我们的评审对你有帮助，欢迎分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论上点击 👍 或 👎，我会根据你的反馈来改进后续的评审。}

Original comment in English

Hey - I've left some high level feedback:

• In docs/architecture/OVERVIEW.md, you reference RETINUE_STATE_DIR and state directories but don’t say what the default is or where it typically lives on disk—adding a short note about the default location or how it’s derived would make the diagnostics section more immediately useful.
• The new OVERVIEW.md and DOCUMENTATION_GOVERNANCE.md files talk about audience targeting in the body, but per the governance guidance it would help to add an explicit, one-line audience note near the top of each file (e.g., “Audience: operators and contributors”) so readers can quickly tell who the page is for.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `docs/architecture/OVERVIEW.md`, you reference `RETINUE_STATE_DIR` and state directories but don’t say what the default is or where it typically lives on disk—adding a short note about the default location or how it’s derived would make the diagnostics section more immediately useful.
- The new `OVERVIEW.md` and `DOCUMENTATION_GOVERNANCE.md` files talk about audience targeting in the body, but per the governance guidance it would help to add an explicit, one-line audience note near the top of each file (e.g., “Audience: operators and contributors”) so readers can quickly tell who the page is for.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}