docs(capabilities): clarify outcome and extension paths

[huangruiteng]

Summary

• keep LoopX architecture-first while defining Kernel, Capability, Provider, and Extension as distinct linked boundaries
• add outcome-first routes from the README to six representative registered capabilities and their authoritative capability show readbacks
• turn the capability index into a user-facing outcome map, while retaining the domain-lane and Kernel-authority rules for contributors
• add the missing Extensions and Capabilities entry to the reference index

The Hero and opening navigation are unchanged. This is a documentation and information-architecture change only; it does not add a runtime registry, alter capability state, or grant provider authority.

Validation

• loopx canary premerge --from-git-diff --git-diff-base origin/main --tier standard --format json --no-progress: passed; 13 selected checks, 0 failures, 0 warnings, no manual holds
• python3 examples/issue-fix-capability-guide-smoke.py: passed
• python3 examples/capability-extension-placement-doc-smoke.py: passed
• python3 examples/docs-governance-smoke.py: passed
• python3 examples/public_entry/readme-demo-surface-smoke.py: passed
• six documented loopx capability show <id> --format json readbacks: passed
• public/private boundary scan: 4 changed public files, 0 hits
• git diff --check: passed

Full MkDocs rendering was not run because the system Python environment does not provide the optional mkdocs module. Repository-owned documentation and public-entry smokes passed.

Public boundary

Only public documentation is included. The PR excludes local state, credentials, private links, raw benchmark material, generated logs, and unrelated primary-worktree artifacts.

[huangruiteng]

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

精确评审头（Exact Head）: 3242@9cc599942ca6e24d7f793f7469e1900f34acf836
Base: main | 类型: docs / 信息架构（4 files, +174/-51） | 作者: huangruiteng（owner，GitHub 阻止正式 self-approval，故以 COMMENTED 记录 APPROVE 结论）

---

详细中文评审

动机

此前 README 的 Capabilities 段落把能力折叠成「五个问题」，docs/capabilities/README.md 则是一份按能力目录平铺的清单；读者很难区分 Kernel / Capability / Provider / Extension 这些边界，也难以从「我要的结果」出发找到对应能力与权威 readback。本 PR 的动机是真实的信息架构缺陷：把「架构边界」与「产品结果路径」分开，并用 loopx capability list/show 作为权威事实源，避免文档与实现漂移。就近小修（只加几行链接）解决不了「术语边界混乱 + 文档冒充实现事实」的问题，因此重组两个 README 是恰当的最小范围。

改动思路

主线清晰：先立边界表（Kernel 拥有持久化事实、Capability 提供 provider-neutral 结果合同、Provider 执行有界外部操作、Extension 打包并运维可选 Provider），再给用户两条互补入口——README 里按「你需要……」的结果路径直达 6 个代表能力并附 capability show 命令；能力索引按 Engineering Delivery / Research And Decision Continuity / Operations And Projection 分组。文档自始至终强调「CLI 注册表是权威，目录/文档存在不等于 shipped capability」，「host 声明（如 --available-capability shell）是 runtime capacity 而非产品能力或权限授予」。这与仓库实际的 capability 生命周期语义和 AGENTS.md 的 capability 放置规则一致。

具体改动

• README.md（+48/-4）：新增 Kernel/Capability/Provider/Extension 边界表；原「Capabilities」段改为「Core Control-Plane Promises」；新增「Product Capability Paths」结果表（6 个能力 + capability show 命令）。改动从第 285 行起，Hero 与开头导航未变。
• README.zh-CN.md（+37/-1）：中文镜像，结构一致；有中文版的子页用中文链接，无中文版的（Change Quality / Integration Branch / Periodic Report）指向英文页。
• docs/capabilities/README.md（+138 行重构）：能力定义与四边界区分、「Inspect What This Release Can Do」、「Choose By Outcome」三组结果表、「From Capability To Provider」双向流程、「Architecture Rule: Domain Lanes, Not Kernel Columns」（保留原规则并强化「至少一个真实 CLI entrypoint + 一个 durable smoke」门槛）。
• docs/reference/README.md（+2）：新增 Extensions and capabilities 索引条目。

关键内容讲解

1. 边界表（README「Capabilities」首段）：把 Kernel / Capability / Provider / Extension 定义为「不同边界而非可互换插件」，并明确 --available-capability shell 只是已观测执行能力、不是产品能力也不是权限授予——这与 runtime capability reentry 语义（能力标志需真实 callsite 验证）一致，避免用户把 host 声明误当权限。

2. Product Capability Paths 结果表：六行「你需要…… → 能力 → capability show <id>」。每个 id 我都对照 exact head 的 loopx/capabilities/catalog.py 验证存在（issue-fix、change-quality-qualification、integration-branch-reconcile、explore、decision-context、periodic-report），且 loopx capability list/show 子命令在 exact head 的 CLI 中真实存在——文档没有虚构命令。

3. “Inspect What This Release Can Do”：明确「目录与文档不因存在而成为 shipped capability；运行时注册表是权威」，并给出 capability list/show 作为唯一事实入口。这消除了「文档冒充实现」的旧风险（对比 PR #3201 正是该反模式的例子）。

4. “From Capability To Provider” 双向流程：Agent -> Capability -> Provider -> external system 与 readback -> transition proposal -> Kernel 反向回路，并声明「安装 extension 不授予新 authority」——与仓库扩展生命周期文档一致。

5. Domain Lanes 规则保留：capability 可增加领域 lane，但不得创建平行 todo 或调度权威；新增路径必须有真实 CLI entrypoint + durable smoke。规则与 AGENTS.md 的 capability/extension 放置决策一致。

正向路径

用户在 README 看到「我需要把公开 issue 变成可审查变更」→ 点 Issue Fix → 运行 loopx capability show issue-fix --format json → 读回用户价值、成熟度、entry commands、write boundary、protocols、持久验证 → 再决定是否启用高级路径或可选 Provider。全程以 CLI 注册表为准，文档不承诺未实现能力。

负向路径

若用户把 --available-capability shell 当作权限授予 → 文档明确声明这只是 runtime capacity，真正执行前 Capability 仍会应用自己的 policy/authority check（负向语义正确）；若某个能力目录存在但没有 CLI entrypoint/smoke → 文档明确它不进入能力索引，未来想法留在 planning docs（不会冒充 shipped）。

对主干的风险

无阻断项。P2 注意点：

1. 评审时刻 checks 未全绿：Sign-off（DCO）与 build 均为 IN_PROGRESS（dependency-review SUCCESS）。新 commit 已带 Signed-off-by（旧 head 的 DCO 失败应已被修复），但合并前请确认两项变绿。
2. 中英链接不对称是有意的：Change Quality / Integration Branch / Periodic Report 没有中文版页面，中文 README 指向英文页；已逐一验证所有链接目标存在，无死链。若后续新增 zh 页面，记得同步替换链接。
3. README 首屏未变：diff 从第 285 行（zh 第 258 行）开始，Hero 与开头导航未改，不触发 first-screen review gate。

验证矩阵（exact head 实测）：

场景	结果
README 引用的 3 个深层文档（architecture.md / capabilities/README.md / reference/extensions.md）	全部存在
能力索引引用的 18 个能力子页（EN/ZH）	全部存在
6 个 capability show <id> 的 id	catalog 中全部存在
loopx capability list/show CLI	exact head 中真实注册
首屏/Hero 改动	无（diff 从第 285 行起）
评审时刻 checks	dependency-review SUCCESS；Sign-off、build IN_PROGRESS

我的整体评价

这是一份质量很高的文档/信息架构改动：边界表准确、结果路径真实可执行、能力索引按结果分组、权威事实始终指向 CLI，且与仓库 capability 生命周期语义完全一致。所有链接与命令 id 都通过 exact head 验证，首屏未动。P2 注意点（等待 Sign-off/build 变绿、未来 zh 页同步）不构成阻塞。结论：APPROVE（author-owned PR，以 COMMENTED 记录批准结论）。

---

English Verdict

Verdict: APPROVE (author-owned PR; recorded as COMMENTED because GitHub blocks formal self-approval)

Exact head: 3242@9cc599942ca6e24d7f793f7469e1900f34acf836

Summary: Docs/information-architecture change clarifying Kernel / Capability / Provider / Extension boundaries, adding outcome-first capability paths in the README with authoritative capability show readbacks, and restructuring the capability index into outcome groups. Verified at the exact head: all referenced docs and capability pages exist, all six capability ids exist in the catalog, loopx capability list/show commands are registered, hero/opening navigation is unchanged, and no dead links were found. No blockers.

P2 (non-blocking): Sign-off (DCO) and build were still IN_PROGRESS at review time (dependency-review SUCCESS); confirm green before merge. The new commit carries Signed-off-by, so the earlier DCO failure is expected to be resolved. If Chinese mirrors are added later for Change Quality / Integration Branch / Periodic Report, update the zh links accordingly.