docs: the plan record carries the reference page and why it exists

Author: speak-agent

.agents/docs/2026-10-01-ecosystem-build-plugin-framework-plan.md

@@ -214,6 +214,23 @@ sha256 `40b9fa16be5628a5d277824f961faa33dadbf84d9520cff9fe2aeb9b0b217ebf`(下载
 `arm64e.x1`,`macos-15` 对照两者皆成功。官方 23.1.2 的 macOS 包确实带 libc++ 头文件、
 库与 `std` 模块源码(与 §12 R20a 的疑问相反)。
 
+## 4.1 面向两类读者的参考文档（2026-10-02 追加）
+
+`docs/tool-sources.md`(372 行,README 与 plugin-development.md 各有入口)。写它的理由是:
+机制此前在三处分别被记下——引擎的键在 mcpp docs/23、模块的接口在 plugin-development.md、
+每个成员的选项在各自页面——而**没有一处说出必须同时成立的那两半**:
+`build.mcpp` 里的 `tool::choice` 只有在插件把该载荷声明为 `provision = "on-request"` 时才等于
+「不下载」,因为 eager 的载荷在任何构建程序运行之前就已供给。这正是 mcpp#755 的原始症状,
+也是两类读者真正会问的那个问题。
+
+按场景组织:使用者七个场景(什么都不写、点名机器上的工具、写在清单里、为一次 CI 任务替换、
+多工程共享、离线构建与审计、自带整条工具链),作者七个场景(三块代码、那一对、只在某条分支上
+用到的载荷、一棵树而不是一个程序、历史环境变量、只看不要、如何在不安装任何东西的前提下证明),
+以及设计侧的取舍。末尾一张表列出每个驱动工具的官方成员、它的声明方式与理由——这样 eager 的
+那些不会被读成遗漏。
+
+全部论断都对清单与源码核对过;删掉了一处无来源的「80% 用户」数字,改为陈述事实。
+
 ## 5. 生态级 review
 
 按「这条机制在生态的每个接缝处是否闭合」来看,而不是按仓库看。