docs(development): add LoopX project code tour

[luyufei4521]

What changed

Adds a Chinese, code-linked project guide for developers new to LoopX. It explains the business problem, control-plane layers, CLI/bootstrap path, quota should-run, Turn execution, typed settlement, authority/claims, capabilities/extensions, troubleshooting, and a recommended reading order.

Validation

• git diff --check
• Markdown fence and relative-link scan: 3 Mermaid diagrams, 58 source links, all relative targets exist
• Public/private boundary scan: no credentials, raw logs, private links, or local absolute paths

Scope

Documentation only; no runtime behavior changes.

[huangruiteng]

动机

这个 PR 想解决的是真实问题：LoopX 的架构、控制面与扩展机制分布在多组源码和参考文档里，新贡献者很难快速建立从 Goal/Todo 到 quota、Turn、settlement、authority、capability 与 extension 的完整心智模型。一份中文 code tour 是有价值且边界完整的文档交付。

我按当前 exact head a15a121ded8f15550c35d9b76a09dee0932b18f8 阅读了全部 603 行，并从“新开发者实际如何发现并使用它”的入口反向核验。内容本身已经具备较好的解释密度，但当前提交还没有完成面向目标读者的导航闭环。

改动思路

文档采用一条合理的主线：先解释系统全貌，再依次把 Goal/Todo、quota、Turn、settlement、authority、capability、extension 和 troubleshooting 映射到具体源码路径，最后提供推荐阅读顺序和路径速查表。三个 Mermaid 图也帮助读者把状态、决策和副作用连起来。

这个方案不需要新增文档生成器或第二套目录。现有 docs/development/README.md 已明确是稳定的开发文档入口，并且已有 Start Here / 从这里开始 与 Core References / 核心参考，因此它就是新 guide 的最小、正确导航 owner。

具体改动

关键内容讲解

• 新增 docs/development/project-code-tour.zh-CN.md，用中文把核心概念、模块职责、执行路径和常见调试入口串成一个连续阅读旅程。
• 文档包含 61 个仓库相对链接、32 个成对代码 fence 与 3 个 Mermaid 图；相对文件目标均存在，结构完整，未发现私有环境、内部路径或敏感上下文。
• 当前 exact-head diff 只新增该文件，没有修改任何已有 index。全仓搜索显示该文件除自引用外没有入站链接；从 canonical development README 的 Start Here 或 Core References 均无法发现它。
• 两处源码范围已经超过当前文件末尾：driver.py#L429-L590 指向 561 行文件（出现两次），authority_store.ts#L1-L190 指向 187 行文件。GitHub 仍可能打开文件，但范围表达已经不准确。

本地验证方面，loopx check --scan-path、examples/docs-governance-smoke.py 与 git diff --check 均通过；项目检查只报告了两个与本 PR 无关的既有 Goal-state warning。本轮按 capability 配置没有等待或引用远端 CI。现有检查能证明 Markdown/治理基本完整，但不会发现“新页面无人链接”或“fragment 末端超过 EOF”这两类用户旅程问题。

对主干的风险

P1：新 guide 没有进入 canonical 开发文档导航

触发条件是最常见的新贡献者路径：从 docs/development/README.md 进入，浏览 Start Here 与 Core References。当前提交没有任何入口指向新页面，仓库搜索也证实它是 orphan page。结果是只有已经知道文件名或拿到 PR 直链的人能使用它，主要目标读者仍需手工重建同一套阅读路径；未来架构变化时，孤立页面也更容易漏掉维护。

最小修复：在 docs/development/README.md 的中文 Start Here 和/或 Core References 中加入该 guide，并再次做入站引用搜索及现有 docs 检查。不需要创建新目录或新导航机制。

P2：修正两个越过当前 EOF 的源码范围

把 driver.py#L429-L590 调整到当前函数/文件内（该链接出现两次），把 authority_store.ts#L1-L190 调整到 187 行以内；如果精确范围不稳定，也可以退回文件或更稳定的 symbol-oriented 指针。修复后建议重跑相对路径与行范围扫描。

这两个问题都是 docs-only 且易于回滚，不影响 runtime；但第一个直接阻断了“让新开发者获得 code tour”这一交付目标，因此不应只当成后续 polish。

我的整体评价

内容组织、概念覆盖和源码映射总体扎实，603 行对于这份一站式中文导览是合理体量，不建议为缩短而拆成多个更难发现的碎片。当前结论不是否定 guide，而是要求补齐它与现有文档 owner 的集成：把页面接入 canonical index，并修正两个已失真的行范围后，就具备很清晰的复审路径。

未来向前看，最有价值的相邻优化也是复用现有索引与更稳定的源码指针；没有必要增加新的文档注册框架。请在同一 PR 补齐上述最小修复，我会按更新后的 exact head 复审。

English verdict: REQUEST_CHANGES - head a15a121

[huangruiteng]

这个我感觉挺不错的，看能否从loopx主页更好地导向这个，目前有主页，也有loopx devbook，但感觉信息量还是太大了，也有点散，我感觉你这个甚至可以作为devbook的首屏，并且网站主页以及readme啥的导向devbook

[luyufei4521]

感谢您的反馈，我已按审查意见完成本 PR 的修复，最新提交为 304ac34af11dc5e53cc2c1bf1b8cf93e6621a435。

修复内容：

• 在 docs/development/README.md 的英文和中文 Start Here / 从这里开始 中加入 LoopX 项目代码导读 入口。
• 在 Core References / 核心参考 表格中加入项目架构导读条目，确保从 canonical development README 可以发现这篇文档。
• 将 driver.py#L429-L590 修正为当前实际存在的 driver.py#L429-L561，并同步修正源码索引中的同一链接。
• 将 authority_store.ts#L1-L190 修正为当前实际存在的 authority_store.ts#L1-L187。

验证结果：

• git diff --check
• python3 examples/docs-governance-smoke.py
• loopx check --scan-path .（7 项检查通过，errors=0，warnings=0）
• 相对链接和源码行号范围检查通过
• 凭证、本地绝对路径和私有链接扫描通过

感谢您的关注，这个导航文档也是自己学习使用loopx时让AI帮我总结的，意外发起了PR，希望没给您添麻烦。

主页和 Devbook 首屏导向的建议我也记下了；本次先把当前 PR 的正式审查阻断项和文档发现路径补齐，避免扩大本次文档修复的范围。烦请按新的 exact head 重新审查，谢谢。

[huangruiteng]

动机

本次复审绑定 exact head 304ac34af11dc5e53cc2c1bf1b8cf93e6621a435。这个 PR 解决的是贡献者很难从分散源码和文档中快速建立 LoopX 全局心智模型的问题：新增一份 603 行中文 code tour，把 Goal/Todo、quota、Turn、settlement、authority、capability 与 extension 串成连续阅读路径。

上一轮的两个实际阻塞是：页面没有进入 canonical developer index，只有拿到文件名的人才能发现；两个源码 fragment 的上界越过当前 EOF。新 head 已把这两点完整闭合。维护者提出的“进一步把主页或 Devbook 首屏导向该内容”有产品价值，但那会改变公共首屏并需要单独预览审批，不应把当前 docs-only 导览无限扩张后才允许落地。

改动思路

方案继续复用现有 docs/development/README.md 作为稳定入口，没有建立第二套目录或文档注册机制：英文和中文 Start Here / 从这里开始 都加入 code tour，Core References / 核心参考 再提供主题索引；导览正文则用仓库相对路径连接到真实 owner。

复审增量相对旧 head 只有导航与链接修正，全文架构没有另起一套 authority。正向路径是“开发者入口 → code tour → 具体 source owner”；失败路径由相对链接/行范围扫描直接暴露，不依赖人工猜测。

具体改动

关键内容讲解

• docs/development/README.md 在英文、中文 Start Here 和 Core References 三处加入 project-code-tour.zh-CN.md，因此页面不再是 orphan。
• project-code-tour.zh-CN.md 保留 61 个仓库相对链接、3 个 Mermaid 图和完整执行链讲解；driver.py 两处范围从 L429-L590 修为 L429-L561，与当前 561 行文件一致。
• authority_store.ts 范围从 L1-L190 修为 L1-L187，与当前 187 行文件一致。
• 当前 whole diff 为两个 docs 文件、+620/-12；last-review-to-head 是 +20/-15，只处理上一轮导航和范围问题，没有混入 runtime、schema、权限或私有材料。

我实际运行了 docs governance、loopx check --scan-path .、git diff --check 以及独立的相对链接/行范围扫描。结果为：docs governance 通过；contract check errors=0（两条 warning 是其他 Goal 已存在的 state projection gap）；61 个相对链接无缺失、无越界；当前 merge tree 可生成且无冲突。

对主干的风险

没有发现新的阻断项。最强风险仍是后续源码增长/收缩导致 line fragment 漂移，但当前 exact head 已经精确匹配文件长度，且 docs-only 回滚成本低。更稳定的 symbol anchor 目前并非 GitHub Markdown 的通用可用合同，因此保留精确行范围是可接受折中。

本轮没有把远端 CI 当作证据，也没有等待 CI；当前 capability 明确要求以 repository-native local validation 为准。功能关闭、authority、typed state、guidance/obligation 等 runtime lens 对纯文档增量不适用；全文也未引入新的协议或行为默认值。

我的整体评价

APPROVE。 新 head 已修复上一轮全部 blocker：导览从 canonical developer entrypoint 可发现，两个失真的 source range 已修正，完整链接扫描和 docs 检查通过。603 行体量与“一站式中文代码导读”的目标相称，继续拆碎反而会降低发现性。未来若要把它升级为 Devbook 或网站首屏，应作为单独的第一屏设计变更先给维护者预览，而不是阻塞本 PR。

English verdict: APPROVE - Exact head 304ac34af11dc5e53cc2c1bf1b8cf93e6621a435 makes the Chinese code tour discoverable from the canonical developer index, fixes both stale source ranges, and passes docs governance, repository checks, diff validation, and a 61-link target/range scan.