fix(docs): restore capability-aware frontstage builds

[huangruiteng]

Summary

• Install the current LoopX checkout before capability-aware MkDocs hooks run.
• Keep root capability-generation hooks scoped out of Developer Book builds.
• Restore the writer-to-reader conformance introduced by refactor(capabilities): colocate docs with implementations #3265 without weakening strict docs validation.

Validation

• Root MkDocs strict build.
• Chinese and English Developer Book strict builds.
• python examples/dev-book-publication-smoke.py --site-dir <combined-site>/docs/book.
• loopx canary premerge --from-git-diff: 11/11 selected checks passed, no manual holds.
• Public/private boundary scan passed.

This fixes the Frontstage Pages regression first observed while qualifying #3261.

[huangruiteng]

Summary

• Install the current LoopX checkout before capability-aware MkDocs hooks run.
• Keep root capability-generation hooks scoped out of Developer Book builds.
• Restore the writer-to-reader conformance introduced by refactor(capabilities): colocate docs with implementations #3265 without weakening strict docs validation.

Validation

• Root MkDocs strict build.
• Chinese and English Developer Book strict builds.
• python examples/dev-book-publication-smoke.py --site-dir <combined-site>/docs/book.
• loopx canary premerge --from-git-diff: 11/11 selected checks passed, no manual holds.
• Public/private boundary scan passed.

This fixes the Frontstage Pages regression first observed while qualifying #3261.

[huangruiteng]

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

精确评审头（Exact Head）: 3268@920b358451067ec70a4f5e51bf4df68dd64c8788
Base: main | 类型: Frontstage Pages docs 构建修复（3 files, +8/-0）
作者: huangruiteng（owner）

---

详细中文评审

动机

main 的 Frontstage Pages（docs build）自 #3265 起持续红色：mkdocs hook rewrite_capability_links.py 导入 loopx.capabilities.catalog 时 ModuleNotFoundError: loopx，因为 CI 的 docs 步骤只装 docs/requirements-docs.txt，没有安装当前 checkout。本 PR 直接修复该回归。

改动思路

两点最小修复：(1) Frontstage Pages workflow 在安装 docs 依赖后追加 pip install -e .，让 capability-aware hook 能导入本地 loopx；(2) 两本 Developer Book 的 mkdocs 配置显式声明 plugins: [search] 与 hooks: []，把根站点的能力页生成 hook 限定在根 docs site，避免被子站构建继承执行。

具体改动

• .github/workflows/frontstage-pages.yml（+2）：Install docs dependencies 步骤追加 python -m pip install --disable-pip-version-check -e .。
• docs/book/mkdocs.en.yaml / mkdocs.zh.yaml（各 +6）：显式覆盖继承的 plugins/hooks，注释说明能力页归属根站点。

关键内容讲解

1. 回归根因：hook 在构建期 import loopx，但 CI 未安装包；pip install -e . 一行修复，与本地 uv run 场景一致。
2. hook 作用域：Developer Book 配置原本会继承根 mkdocs.yaml 的 gen-files/hooks；显式 hooks: [] + 仅 search 插件，避免子站构建执行能力页生成与链接重写。
3. 无行为放宽：strict 校验保持不变（未删任何校验），只是让构建环境具备真实运行时。

对主干的风险

无阻断项。改动只触及 CI 安装步骤与两个子站 mkdocs 配置，不改变文档内容、运行时或能力契约。此前评审中标记的 Frontstage Pages 红色检查正是本 PR 的修复目标。

验证矩阵（exact head 实测）

场景	结果
根 mkdocs build --strict（含 gen-files + 链接重写 hook，loopx 可导入）	PASS
docs/book/mkdocs.en.yaml mkdocs build --strict	PASS
docs/book/mkdocs.zh.yaml mkdocs build --strict	PASS
dev-book-publication-smoke（完整合并站点）	作者侧 PASS（需完整 control-plane course 管线，本 checkout 无 course 产物，未在本轮独立复跑）
Sign-off / dependency-review	SUCCESS（GitHub）
build（CI）	IN_PROGRESS（评审时刻）

我的整体评价

小而准的 CI/文档构建修复：装上运行时 + 隔离子站 hook 作用域，直接消除我此前标记的 main 既有红色检查；三个 strict 构建本地全部通过。结论：APPROVE（author-owned PR，以 COMMENTED 记录批准结论；合并前确认 CI build 绿）。

---

English Verdict

Verdict: APPROVE (author-owned PR; recorded as COMMENTED because GitHub blocks formal self-approval). The PR surgically fixes the pre-existing Frontstage Pages docs-build regression: CI now installs the current checkout (pip install -e .) before capability-aware MkDocs hooks run, and the Developer Book configs explicitly scope out root capability-generation hooks. Root and both book mkdocs build --strict pass at the exact head; Sign-off and dependency-review are green, and CI build was still in progress at review time.