dsh-plugin-dev-kb 1.8.0 → 1.8.1

package/kb/README.md

@@ -1,88 +1,88 @@
-# DeepSeek Harness 文档知识库
-
-本地镜像的 DeepSeek Harness 官方文档知识库，用于辅助 Harness **插件开发**。内容抓取自官方文档站点
-<https://deepseek-harness.github.io/deepseek-harness/>，并以**仓库内原始 Markdown**（`deepseek-ai/deepseek-harness` 的 `docs/` 目录）重建，比抓取渲染后的 HTML 保真度更高、链接与代码块完整。
-
-## 目录结构
-
-```
-knowledge/deepseek-harness/
-├── README.md         本文件：总览与使用指南
-├── INDEX.md          全部页面的 站点 URL ↔ 本地文件 对照索引（自动生成）
-├── site/             线上站点的完整镜像（中英双语，链接已按站点路由重写）
-│   ├── index.md            中文首页（/deepseek-harness/）
-│   ├── guide/              入门：quickstart / providers / python-sdk / github-review /
-│   │                       schedule / mcp-memory
-│   ├── develop/            开发：basic(第一个插件/tool/config/publish)、
-│   │                       framework(生命周期/service/事件)、practice、cordis-tutorial(7 章)
-│   ├── reference/          参考：架构、capability-seams、config-catalog、tool-catalog、
-│   │                       api-gateway、cordis-api、cookbook、subsystems(46 个子系统页)…
-│   └── en/                 英文站镜像（/deepseek-harness/en/...），结构同上
-├── extra/            仓库 docs/ 中未发布到站点的补充文档（开发参考）
-│   ├── glossary.md         术语表（capability seam 等核心概念）
-│   ├── defensive-patterns.md / testing.md / development.md / rescope.md …
-│   ├── module-graph.md     模块依赖全景图（125KB）
-│   ├── cookbook/           adding-a-vendored-package 等仓库内 cookbook
-│   ├── upgrade-guide/      各版本升级指南（0.1.7-rc.2 / 0.2.0-rc.2 …）
-│   ├── persistence-changes/ 持久化格式变更记录（releases/、historical-formats/）
-│   ├── subsystems/         未发布进站点的子系统文档（boot / browser-use / ssh / otel …）
-│   ├── postmortem/         事故复盘
-│   └── i18n/               文档双语规范与术语
-└── meta/
-    ├── source.json         来源信息：仓库 commit、抓取时间、统计
-    └── site-pages.txt      线上站点页面清单（由投影结果生成，188 页）
-```
-
-## 插件开发学习路径（从 `site/` 开始）
-
-1. **第一个插件** — `site/develop/basic/index.md`（插件 = 导出 `apply(ctx)` 的模块，`ctx.effect()` 自动清理）
-2. **开发一个 Tool** — `site/develop/basic/tool.md`（工具定义 DSL）
-3. **插件配置** — `site/develop/basic/config.md`；**打包安装** — `site/develop/basic/publish.md`
-4. **框架能力** — `site/develop/framework/index.md`（生命周期）、`service.md`（服务与依赖注入）、`events.md`（事件系统）
-5. **Cordis 框架教程** — `site/develop/cordis-tutorial/`（7 章：插件/生命周期/服务/事件/配置/组合与热重载/进入 Harness）
-6. **实战** — `site/develop/practice/index.md`（能力三层拆分）、`llm-adapter.md`、`dynamic-cordis.md`（运行时动态装配 Cordis）
-7. **按需查阅** — `site/reference/`：
-   - 架构总览 `reference/index.md`；能力服务 `reference/capability-seams.md`；Agent 生命周期 `reference/agent-lifecycle.md`
-   - 插件配置目录 `reference/config-catalog.md`；Tool Schema 目录 `reference/tool-catalog.md`；持久化事件 `reference/persistence-catalog.md`；API Gateway `reference/api-gateway.md`（Typert Remote 方法/RPC 约定）
-   - Cordis API `reference/cordis-api/`（Context / Events / Fiber / Registry / Service / 继承接口面）
-   - Cookbook `reference/cookbook/`（新增 package / tool / LLM adapter / 设置卡片 / 扩展模式）
-   - 子系统 `reference/subsystems/`（core / scope / session / tools / shell / filesystem / subagent / sandbox / approval / conversation / slots / web-client … 共 46 页）
-
-## 更新方法
-
-**一键刷新（推荐）**：`npm run refresh-kb`（克隆上游 → 投影 → 覆盖 site/extra → 重建索引与元数据），
-完成后 `npm run selfcheck` 自检。GitHub Action（`.github/workflows/refresh-kb.yml`）每周一自动执行同一
-脚本，有变更即自动提交；README 顶部「kb sync」badge 数据来自 `meta/source.json`。
-
-以下为手动步骤（理解流程 / 非 Windows 环境参考）。知识库与仓库 `master` 分支对齐
-（见 `meta/source.json` 的 commit）。需要刷新时：
-
-```sh
-# 1. 重新克隆仓库
-git clone --depth 1 https://github.com/deepseek-ai/deepseek-harness.git <tmp>
-
-# 2. 安装投影依赖（mdast 三个包）。仓库本身是 pnpm workspace（package.json 含
-#    workspace: 协议），npm 无法直接在其内安装；装到克隆目录的上级，Node 的 ESM
-#    解析沿 node_modules 向上查找时即可命中。
-cd <tmp>/.. && npm install --no-save --no-package-lock mdast-util-from-markdown mdast-util-gfm micromark-extension-gfm
-
-# 3. 运行站点投影器（Node ≥ 22.19；24 默认启用 type stripping）。
-#    上游已无 run-projector.ts，改为调用 scripts/project-doc-site.ts 的 projectDocs()：
-cd <tmp> && node --input-type=module -e "import('./scripts/project-doc-site.ts').then(m => { m.projectDocs(); console.log('projected') })"
-#    输出到 website/.generated/
-
-# 4. 用 website/.generated/ 覆盖本插件的 kb/site/；
-#    用 <tmp>/docs/ 中未发布的 Markdown 刷新 kb/extra/（对照 website/docs.ts 的
-#    docsPages source/sourceAliases 集合求差集）
-
-# 5. 在本插件根目录重新生成索引与 INDEX.md，并更新 meta/source.json 与统计
-node scripts/rebuild-index.mjs
-```
-
-站点投影逻辑为仓库内 `website/docs.ts`（发布清单）+ `scripts/project-doc-site.ts`（链接重写/图片复制，由 `website/.vitepress/config.ts` 在构建时调用）。
-
-## 统计
-
-- 站点页面：192 个 Markdown，4 张图片
-- 补充文档：468 个 Markdown（`extra/`）
-- 来源 commit：`fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159`（master，2026-11-07 同步）
+# DeepSeek Harness 文档知识库
+
+本地镜像的 DeepSeek Harness 官方文档知识库，用于辅助 Harness **插件开发**。内容抓取自官方文档站点
+<https://deepseek-harness.github.io/deepseek-harness/>，并以**仓库内原始 Markdown**（`deepseek-ai/deepseek-harness` 的 `docs/` 目录）重建，比抓取渲染后的 HTML 保真度更高、链接与代码块完整。
+
+## 目录结构
+
+```
+knowledge/deepseek-harness/
+├── README.md         本文件：总览与使用指南
+├── INDEX.md          全部页面的 站点 URL ↔ 本地文件 对照索引（自动生成）
+├── site/             线上站点的完整镜像（中英双语，链接已按站点路由重写）
+│   ├── index.md            中文首页（/deepseek-harness/）
+│   ├── guide/              入门：quickstart / providers / python-sdk / github-review /
+│   │                       schedule / mcp-memory
+│   ├── develop/            开发：basic(第一个插件/tool/config/publish)、
+│   │                       framework(生命周期/service/事件)、practice、cordis-tutorial(7 章)
+│   ├── reference/          参考：架构、capability-seams、config-catalog、tool-catalog、
+│   │                       api-gateway、cordis-api、cookbook、subsystems(46 个子系统页)…
+│   └── en/                 英文站镜像（/deepseek-harness/en/...），结构同上
+├── extra/            仓库 docs/ 中未发布到站点的补充文档（开发参考）
+│   ├── glossary.md         术语表（capability seam 等核心概念）
+│   ├── defensive-patterns.md / testing.md / development.md / rescope.md …
+│   ├── module-graph.md     模块依赖全景图（125KB）
+│   ├── cookbook/           adding-a-vendored-package 等仓库内 cookbook
+│   ├── upgrade-guide/      各版本升级指南（0.1.7-rc.2 / 0.2.0-rc.2 …）
+│   ├── persistence-changes/ 持久化格式变更记录（releases/、historical-formats/）
+│   ├── subsystems/         未发布进站点的子系统文档（boot / browser-use / ssh / otel …）
+│   ├── postmortem/         事故复盘
+│   └── i18n/               文档双语规范与术语
+└── meta/
+    ├── source.json         来源信息：仓库 commit、抓取时间、统计
+    └── site-pages.txt      线上站点页面清单（由投影结果生成，188 页）
+```
+
+## 插件开发学习路径（从 `site/` 开始）
+
+1. **第一个插件** — `site/develop/basic/index.md`（插件 = 导出 `apply(ctx)` 的模块，`ctx.effect()` 自动清理）
+2. **开发一个 Tool** — `site/develop/basic/tool.md`（工具定义 DSL）
+3. **插件配置** — `site/develop/basic/config.md`；**打包安装** — `site/develop/basic/publish.md`
+4. **框架能力** — `site/develop/framework/index.md`（生命周期）、`service.md`（服务与依赖注入）、`events.md`（事件系统）
+5. **Cordis 框架教程** — `site/develop/cordis-tutorial/`（7 章：插件/生命周期/服务/事件/配置/组合与热重载/进入 Harness）
+6. **实战** — `site/develop/practice/index.md`（能力三层拆分）、`llm-adapter.md`、`dynamic-cordis.md`（运行时动态装配 Cordis）
+7. **按需查阅** — `site/reference/`：
+   - 架构总览 `reference/index.md`；能力服务 `reference/capability-seams.md`；Agent 生命周期 `reference/agent-lifecycle.md`
+   - 插件配置目录 `reference/config-catalog.md`；Tool Schema 目录 `reference/tool-catalog.md`；持久化事件 `reference/persistence-catalog.md`；API Gateway `reference/api-gateway.md`（Typert Remote 方法/RPC 约定）
+   - Cordis API `reference/cordis-api/`（Context / Events / Fiber / Registry / Service / 继承接口面）
+   - Cookbook `reference/cookbook/`（新增 package / tool / LLM adapter / 设置卡片 / 扩展模式）
+   - 子系统 `reference/subsystems/`（core / scope / session / tools / shell / filesystem / subagent / sandbox / approval / conversation / slots / web-client … 共 46 页）
+
+## 更新方法
+
+**一键刷新（推荐）**：`npm run refresh-kb`（克隆上游 → 投影 → 覆盖 site/extra → 重建索引与元数据），
+完成后 `npm run selfcheck` 自检。GitHub Action（`.github/workflows/refresh-kb.yml`）每周一自动执行同一
+脚本，有变更即自动提交；README 顶部「kb sync」badge 数据来自 `meta/source.json`。
+
+以下为手动步骤（理解流程 / 非 Windows 环境参考）。知识库与仓库 `master` 分支对齐
+（见 `meta/source.json` 的 commit）。需要刷新时：
+
+```sh
+# 1. 重新克隆仓库
+git clone --depth 1 https://github.com/deepseek-ai/deepseek-harness.git <tmp>
+
+# 2. 安装投影依赖（mdast 三个包）。仓库本身是 pnpm workspace（package.json 含
+#    workspace: 协议），npm 无法直接在其内安装；装到克隆目录的上级，Node 的 ESM
+#    解析沿 node_modules 向上查找时即可命中。
+cd <tmp>/.. && npm install --no-save --no-package-lock mdast-util-from-markdown mdast-util-gfm micromark-extension-gfm
+
+# 3. 运行站点投影器（Node ≥ 22.19；24 默认启用 type stripping）。
+#    上游已无 run-projector.ts，改为调用 scripts/project-doc-site.ts 的 projectDocs()：
+cd <tmp> && node --input-type=module -e "import('./scripts/project-doc-site.ts').then(m => { m.projectDocs(); console.log('projected') })"
+#    输出到 website/.generated/
+
+# 4. 用 website/.generated/ 覆盖本插件的 kb/site/；
+#    用 <tmp>/docs/ 中未发布的 Markdown 刷新 kb/extra/（对照 website/docs.ts 的
+#    docsPages source/sourceAliases 集合求差集）
+
+# 5. 在本插件根目录重新生成索引与 INDEX.md，并更新 meta/source.json 与统计
+node scripts/rebuild-index.mjs
+```
+
+站点投影逻辑为仓库内 `website/docs.ts`（发布清单）+ `scripts/project-doc-site.ts`（链接重写/图片复制，由 `website/.vitepress/config.ts` 在构建时调用）。
+
+## 统计
+
+- 站点页面：192 个 Markdown，4 张图片
+- 补充文档：554 个 Markdown（`extra/`）
+- 来源 commit：`39163dd30f703a79079e2d2446545cff3c453738`（master，2026-11-14 同步）

package/kb/extra/AGENTS.md

@@ -1,77 +1,77 @@
-# AGENTS.md — The documentation standard
-
-This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [archived doc-tiers Agent Note](../.agents/notes/archived/process/2026-07-04-doc-tiers-and-budgets.md) records the historical rationale.
-
-## Document structure
-
-These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
-
-Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
-
-Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
-
-Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
-
-## The tier taxonomy: one home per fact
-
-Each fact has one home: the tier whose job it is; elsewhere, link there.
-
-| Tier | Job | Does NOT belong there |
-|---|---|---|
-| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
-| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
-| [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
-| [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
-| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
-| [defensive-patterns/](defensive-patterns/README.md) | Rules this repository enforces in review, split by artifact: one general bug-class page plus per-domain pages | Type definitions and semantics (→ subsystems), decision rationale (→ Agent Notes) |
-| [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
-| [Persistence history](persistence-changes/README.md) and [format references](persistence-changes/historical-formats/README.md) | Type-change acknowledgements, release comparisons, and complete historical format schemas | Behavior-only changes; current runtime contracts |
-| [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
-| [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
-| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
-| [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
-| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md), [cli-help](cli-help.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
-| Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
-
-Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link; review-enforced rules → `defensive-patterns/`.
-
-## Writing rules
-
-- **Document current state.** Keep history in commits, PRs, Agent Notes, postmortems, or scoped persistence records. Other prose names live mechanisms, not changes or stack positions. General Session-format prose links [version/status authority](session-format-status.md); retain numbers for version-specific contracts, examples, or evidence.
-- **Apply the Agent Note creation criteria.** Mechanical/local edits are exempt, including local UI changes; keep existing owning notes accurate ([scope](../.agents/notes/README.md#when-to-write-one)).
-- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
-- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../scripts/verify-subsystem-pages.ts)).
-- **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
-- **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Write directly: name actors and facts ([reference](../.agents/skills/dsh-prose-standard/SKILL.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
-
-## Wordcount Budgets
-
-[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
-
-When the gate goes red:
-
-1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
-2. **Condense** content that belongs here but can be shorter.
-3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
-
-Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 2,080; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 810 and this file ≤ 1,430; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
-
-## The slop checklist
-
-Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
-
-- Duplicated rules: search a distinctive phrase; keep one home and link the rest.
-- History outside its permitted tier: state current facts and link the historical owner.
-- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
-- Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
-- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
-- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
-- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
-- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
-- Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
-
-## Repository references
-
-Use relative Markdown links for current files and tags or PR numbers for historical references. `verify-md-links` checks local targets. [Reference validation](../scripts/verify-repository-references.ts) rejects commit identifiers containing a hexadecimal letter and disallowed organization URLs in maintained files. Decimal-only tokens are ignored to avoid collisions with numeric data, even when they identify commits.
+# AGENTS.md — The documentation standard
+
+This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc-writing](../.agents/skills/dsh-doc-writing/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [archived doc-tiers Agent Note](../.agents/notes/archived/process/2026-07-04-doc-tiers-and-budgets.md) records the historical rationale.
+
+## Document structure
+
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+
+Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
+
+Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
+
+Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
+
+## The tier taxonomy: one home per fact
+
+Each fact has one home: the tier whose job it is; elsewhere, link there.
+
+| Tier | Job | Does NOT belong there |
+|---|---|---|
+| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
+| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
+| [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
+| [defensive-patterns/](defensive-patterns/README.md) | Rules this repository enforces in review, split by artifact: one general bug-class page plus per-domain pages | Type definitions and semantics (→ subsystems), decision rationale (→ Agent Notes) |
+| [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
+| [Persistence history](persistence-changes/README.md) and [format references](persistence-changes/historical-formats/README.md) | Type-change acknowledgements, release comparisons, and complete historical format schemas | Behavior-only changes; current runtime contracts |
+| [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
+| [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
+| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
+| [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md), [cli-help](cli-help.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
+| Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
+
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link; review-enforced rules → `defensive-patterns/`.
+
+## Writing rules
+
+- **Document current state.** Keep history in commits, PRs, Agent Notes, postmortems, or scoped persistence records. Other prose names live mechanisms, not changes or stack positions. General Session-format prose links [version/status authority](session-format-status.md); retain numbers for version-specific contracts, examples, or evidence.
+- **Apply the Agent Note creation criteria.** Mechanical/local edits are exempt, including local UI changes; keep existing owning notes accurate ([scope](../.agents/notes/README.md#when-to-write-one)).
+- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
+- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../scripts/verify-subsystem-pages.ts)).
+- **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
+- **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
+- Write directly: name actors and facts ([reference](../.agents/skills/dsh-prose-standard/SKILL.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
+
+## Wordcount Budgets
+
+[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
+
+When the gate goes red:
+
+1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
+2. **Condense** content that belongs here but can be shorter.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 2,080; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 810 and this file ≤ 1,430; `packages/README.md` ≤ 1,100; plus `cordis-primer.md` 600, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+
+## The slop checklist
+
+Hunt these in any doc; [dsh-doc-writing](../.agents/skills/dsh-doc-writing/SKILL.md) runs this list as an audit:
+
+- Duplicated rules: search a distinctive phrase; keep one home and link the rest.
+- History outside its permitted tier: state current facts and link the historical owner.
+- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
+- Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
+- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
+- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
+- Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
+
+## Repository references
+
+Use relative Markdown links for current files and tags or PR numbers for historical references. `verify-md-links` checks local targets. [Reference validation](../scripts/verify-repository-references.ts) rejects commit identifiers containing a hexadecimal letter and disallowed organization URLs in maintained files. Decimal-only tokens are ignored to avoid collisions with numeric data, even when they identify commits.