2026-08-20proposedprocess

Audience-first documentation quality criteria

以受众为先的文档质量标准

The documentation system has strong placement, freshness, linking, bilingual, and source-equivalence checks, but it does not define “brief, intuitive, and friendly” as reviewable outcomes for users, newcomers, developers, and agents. All `doc-sync` checks and translation pairs pass, while the following design problems remain. The first three findings are the design priorities; the capacity finding explains why adding

.agents/notes/proposed/process/2026-08-20-audience-first-documentation-quality.md

English

Problem

The documentation system has strong placement, freshness, linking, bilingual, and source-equivalence checks, but it does not define “brief, intuitive, and friendly” as reviewable outcomes for users, newcomers, developers, and agents. All doc-sync checks and translation pairs pass, while the following design problems remain. The first three findings are the design priorities; the capacity finding explains why adding more standing rules will not solve them.

Semantic correctness can pass without a current owner

The gates prove structure and generated freshness, not that maintained prose still names the live mechanism. The former dsh-doc-site-sync skill told authors to reuse a nonexistent en-docs sidebar and to add sections to a removed sectionOrder; website/docs.ts owns en-guide, en-develop, en-reference, and sections. The implemented product-first README decision describes an internal-testing notice and ACP, Python, and JSON-RPC surface sections absent from the root README, although implemented Agent Notes must track shipped facts.

The budget policy has the same split. docs/AGENTS.md states a 1,800-word target and 5% headroom for architecture.md, but the budget manifest allows 2,400 words while the file contains 1,313. The budget gate passes because it checks the manifest ceiling, not the target or ratchet rule. High-impact prose therefore needs a named source or a focused check that consumes the source; a second hand-written copy is not a freshness mechanism.

Reader success is implicit rather than testable

The standard classifies pages as tutorials or references and asks authors to classify a tutorial reader privately. It does not require a reviewable statement of the reader’s starting state, desired outcome, shortest successful path, likely failure, or next useful page. A document can therefore satisfy tier placement, links, word limits, and Markdown structure without proving that its intended reader can complete the task.

The public site makes the pressure visible. Each locale publishes 84 pages: 3 guide pages, 17 developer pages, and 63 reference pages. The 13 English files under docs/user/ contain 7,540 words, while 47 subsystem pages contain 100,759 words. The short Web quick start is a good product entry, but no corpus-level criterion verifies that a first-time user, a plugin newcomer, and a maintainer each has one obvious path from entry to outcome and recovery.

Generated accuracy and retrieval quality are conflated

The repository contains 19 fully generated English Markdown files with 49,611 words. Forty-four of 47 subsystem pages also contain generated Cordis regions; those regions contribute 34,622 of the subsystem tier’s 100,759 words. config-catalog.md has 14,807 words, tool-catalog.md has 10,599, and the largest mixed subsystem pages contain 5,600–7,781 words.

These are legitimate exhaustive references, so a blanket word limit would delete value. Their generators prove completeness and freshness, but the standard has no separate retrieval criterion for an agent with a limited context window or a human looking for one answer. A generated reference needs a compact entry layer, stable grouping, direct anchors, and a split rule based on lookup cost; exhaustive detail can remain exhaustive behind that entry layer.

The standard has no room for its next rule

The standing documentation file is 1,320 words against a 1,320-word ceiling and a stated 1,250-word target. Root AGENTS.md is 1,936 words against a 1,600-word target, packages/AGENTS.md is 672 against 650, and packages/README.md is 969 against 600. The frozen ceilings prevent further growth but do not create a place for audience and outcome criteria. Adding more standing prose would deepen the problem the standard is meant to prevent.

Baseline

The audit excludes vendor/, frozen .agents/notes/archived/, recorded snapshots, and fixtures. It counts 1,042 English Markdown files and 986 Chinese counterparts in the maintained corpus, with 1,106,138 English words. Active Agent Notes account for 580 files and 637,850 words; Markdown under packages/ accounts for 276 files and 225,630 words; docs/ accounts for 112 files and 193,456 words. These quantities describe maintenance and retrieval pressure, not defects by themselves.

The system’s strongest properties should remain: one fact owner by tier, canonical Markdown projected into the website without copies, complete bilingual pairing, generated catalogs that fail when source changes, type-equivalent declarations, compilable TypeScript examples, checked links and anchors, and package-local model-experience and limitation contracts. The proposal changes quality criteria and entry structure, not those guarantees.

Proposal

Adopt one audience-first quality contract with five definitions:

Brief means the common path contains only the facts needed for its outcome. Exhaustive contracts remain available through a direct link or generated detail; brevity never means deleting required behavior, failures, ownership, or limitations.
Intuitive means the page establishes its reader’s starting state, introduces prerequisites before dependent concepts, offers one obvious next action, and uses the product or domain terms a reader will search for.
Friendly means a reader can recognize success, understand material risk before acting, recover from the likely failure, and reach the next relevant depth without first learning unrelated architecture.
Accurate means every durable claim has one owner and a verification path appropriate to its risk. Generated facts derive from source; hand-written workflow values link to or consume their owner instead of copying enums and paths.
Agent-readable means headings, anchors, terminology, ownership, and current-versus-proposed status are explicit enough to retrieve the needed section without loading an entire corpus or reconstructing review history.

Prototype rules

The dsh-doc skill owns the first executable version of these rules. The session-persistence-jsonl README pair uses the shipped append, recovery, and encoding behavior as evidence rather than treating its prior prose as authority.

Every authored package README starts with searchable YAML. A Skill-style description and mechanically derived kind are required. Four kinds map one-to-one to four skill templates: package-group (group map), package-reference (plugin or service package), package-library (plain module entry), and package-bundle (dsh.bundle.patch). The counterpart path, hashes, and physical line alignment belong to the merge-safe sidecar and its gate, so README frontmatter contains no i18n block. The title or package manifest already owns the name, the document job expresses its audience, and tags remain absent until a governed taxonomy and search consumer proves value beyond full-text search.
Authored pages start with a three-to-five-sentence Summary, then a linked Table of Contents. An English package README Summary stays within 100 wc -w-style words. It describes reader-visible capability instead of Cordis roles, registrations, or internal components, and omits source identifiers unless readers use them directly in configuration, commands, or a public API. Format-owned Agent Notes, postmortems, generated fragments, and machine files keep their required skeletons.
Each substantive section starts with a short orientation before subsections, tables, or code, and the page progresses from basic user use to advanced developer and maintainer detail.
English technical prose uses an ASD-STE100-inspired, non-certified clarity review: explicit actors and actions, stable terms, direct verbs, separated instructions and conditions, and preserved modality, exceptions, timing, and numbers. The 20-word instruction and 25-word description limits are review prompts. Precision overrides them.
Package contracts remain beside code. Cross-package material moves deliberately toward docs/learn/overview/, docs/learn/cordis/, docs/learn/practices/, docs/user/, docs/developer/, docs/developer/discussion/, docs/scratch/, and the parallel docs/subsystems/ tier.
English and Chinese pages keep equal authority, matching structure, links, code, frontmatter layout, and exact physical line count.
Inline pair metadata is the target replacement for sidecars. The prototype may carry both until the verifier, merge driver, recovery flow, generated-region recorder, and archive checks consume a non-self-referential pair digest.
Repository-root internal links are the target authoring model. The prototype keeps renderer-valid relative links because leading / currently leaves the repository on GitHub, bypasses verify-md-links, and remains unprojected by the website.
Further Exploration is an optional newcomer route to three to seven adjacent pages.
Every authored page ends with Dev Note, the sole place for active rough context. It remains non-authoritative, links rather than duplicates task state, and is promoted or cleaned when work closes.
Independently searchable rules, practices, examples, and decisions use small files under descriptive folders when they have distinct owners or change cadence; tightly coupled obligations stay together.

Criteria by document job

Job	Primary outcome	Required entry information	Verification
Product quick start	Complete one representative task	Prerequisites, one launch path, first success, safety boundary, next step	Built or packaged smoke for the documented path plus link/site checks
User task guide	Complete or recover one user task	Starting UI/API state, ordered actions, observable result, likely failure and recovery	Behavior test, screenshot review when visual state matters, or named manual owner
Contributor tutorial	Reach a checked development state	Supported runtime, setup commands, expected result, narrow follow-up commands	Clean-checkout command smoke on a supported environment
Architecture overview	Reconstruct the system from one page	Product composition, owners, dependency direction, extension points, links to detail	Source-backed package or graph checks plus focused human review
Package or subsystem reference	Look up one contract without reading implementation	Scope, owned types or behavior, failures, lifecycle, limitations, related owners	Existing JSDoc, type-equivalence, generated-region, README, and link checks
Generated reference	Locate one exact item and trust its completeness	Scope, generation owner, grouping/index, stable anchors, related conceptual guide	Deterministic `--check`, completeness fixture, site build, and retrieval-size report
Agent instruction or skill	Apply one workflow without stale copied values	Scope, authority links, required decisions, exact commands only when owned here	Metadata/link checks and focused tests for copied machine values
Proposed or implemented Agent Note	Understand a decision, trade-off, and state	Problem, proposal or decision, alternatives, acceptance or consequences	Existing lifecycle, format, pairing, and supersession checks; review owns semantic currency

The table belongs in one canonical quality reference. docs/AGENTS.md should retain only the short standing orders needed whenever documentation is edited and link to that reference. This creates budget headroom instead of placing another complete standard inside agent context.

Generated-reference entry and detail layers

Every generated reference should expose a compact entry layer before exhaustive output: scope, intended lookup, grouping or index, direct links to conceptual guidance, and the generator/check command. Generators should report page words, entry count, heading count, and largest section. A page crosses a review threshold when one lookup requires scanning unrelated groups or when one page dominates agent context; the owner then splits it by a stable domain already present in source metadata rather than by an arbitrary word slice.

The first prototype should use one large catalog and one mixed subsystem page. It should compare lookup steps, generated diff size, build time, route stability, and agent context needed for representative questions before any corpus-wide split. Existing anchors need aliases when routes move.

Enforcement slices

Create and validate dsh-doc, then rewrite one package README pair as a line-aligned, metadata-bearing prototype without changing runtime claims.
Review the rendered prototype with newcomer, user, developer, and agent tasks; revise the skill before enforcing the format elsewhere.
Add narrow metadata, Summary-length, section-order, line-alignment, link-resolution, and pairing fixtures. Migrate every existing package Summary that violates the accepted entry limit, and keep sidecars until every merge and recovery consumer has replacement support.
Extract accepted standing rules into one canonical quality reference, condense docs/AGENTS.md below its target, and organize one coherent docs/ topic at a time with atomic link/navigation repair.
Prototype generated-reference entry/detail separation on config-catalog.md and docs/subsystems/core.md; apply confirmed patterns elsewhere only after measured lookup cost falls without lost facts or route churn.

This sequence keeps each change independently reviewable. The first three slices improve criteria and package entry points without changing the broader information architecture; the generated-doc prototype supplies evidence before a broader structural change.

Slices 1–3 have shipped in this form: dsh-doc is the consolidated standard (dsh-doc-standards and dsh-doc-site-sync are folded into it, and the site workflow carries the corrected sidebar values), the session-persistence-jsonl README pair is the reference example, and pnpm run test:docs enforces the metadata, pairing, and quick documentation checks. Slices 4–5 remain open.

Non-goals

This proposal does not shorten exhaustive facts, merge audience tiers, publish internal decision records, restore an Agent Note index, split tightly coupled rules for file-count symmetry, or treat the audit as user research. It does not delete current pairing or link infrastructure before its replacement passes equivalent recovery and rendering checks.

Alternatives considered

Apply one word ceiling to every document. Rejected because exhaustive reference rows, public contracts, and decision rationale can be long and correct. Entry-path length and lookup cost are the relevant constraints for those jobs.

Require one universal page template or audience frontmatter. Rejected because it would add ceremony to generated pages, package references, and short instructions without proving reader success. The standard defines outcomes by document job, uses kind only where it selects a concrete package-document standard, and adds only fields that a focused check or reviewer consumes.

Use readability scores as the quality gate. Rejected because formulas penalize exact technical terms and cannot detect wrong ownership, missing failure behavior, stale commands, or a broken reader journey.

Rewrite or split the full documentation corpus immediately. Rejected because the current system is mechanically healthy and many long references are appropriately exhaustive. The bounded package-Summary migration does not alter routes or exhaustive reference content; larger structural changes still require measured evidence.

Keep the existing gates and rely on review for friendliness. Rejected because the stale workflow values and budget-policy mismatch show that review alone does not preserve copied semantic claims, and the current gates do not ask whether a reader can complete a task.

Acceptance criteria

One canonical quality reference defines brief, intuitive, friendly, accurate, and agent-readable documentation by document job.
.agents/skills/dsh-doc validates and directly links its metadata, structure/hierarchy, and review/prototype references without duplicating their detailed rules in SKILL.md.
The session-persistence-jsonl README pair demonstrates searchable YAML, Summary, Table of Contents, user-to-developer progression, Further Exploration, final Dev Note, structural parity, and exact line-count equality while preserving verified package contracts.
Every English package README Summary stays within 100 wc -w-style words; the focused gate reports the measured count and directs failures to dsh-doc and the selected kind template.
docs/AGENTS.md links that reference, remains sufficient as standing instruction, and is below its target with at least 5% headroom.
The root user path, Web quick start, first-plugin tutorial, contributor setup, and architecture overview each name an observable outcome and a verification owner without duplicating implementation detail.
The budget manifest records both target and temporary ceiling, and its check reports or rejects a violated headroom/ratchet state.
The docs-site workflow contains no copied invalid sidebar name or section-owner claim, and a focused test prevents recurrence.
The sidecar remains the single consistency record because it preserves equal authority, last-confirmed-text recovery, automatic merge safety, generated-region recording, and archive sealing without creating owner-file conflicts.
An accepted repository-root link form renders correctly on GitHub and the documentation site and remains locally target/anchor checked before relative links are migrated.
One large standalone catalog and one mixed subsystem page demonstrate a compact entry layer and lower measured lookup cost while preserving exhaustive generated truth, stable links, bilingual pairing, and deterministic freshness.
pnpm run doc-sync, pnpm run lint, the focused new checks, and git diff --check pass.

Risks

Metadata can become boilerplate; the package README check therefore permits only fields with current retrieval, template-selection, or bilingual-consistency consumers.
Hard sentence limits can fragment explanations or separate a condition from its consequence. The controlled-English sentence counts remain review prompts, while the separate 100-word package-Summary ceiling bounds only the entry paragraph and leaves exact contracts in the owning sections.
Exact line alignment can pressure translators into unnatural prose; review must protect meaning and may revise both sides together rather than weaken one.
Splitting generated references can increase routes and link maintenance; prototypes must preserve aliases and measure the trade-off.
A semantic check can become a repository-topology scanner that blocks legitimate changes; checks should cover high-risk copied values and representative journeys, while review owns prose meaning.
Package README quick-reference tables manually repeat selected configuration defaults; until a source-driven check owns them, reviewers must verify changed values against source and the generated config catalog and keep the tables selected rather than exhaustive.
Optimizing for short agent context can make human references fragmented; each split needs one stable conceptual owner and one obvious navigation path.
A permanent Dev Note can become a second queue or stale history dump; completion must promote durable truth and remove resolved chatter.
The audit uses repository structure, gates, and representative pages rather than user research. Before broad rollout, maintainers should validate the proposed reader outcomes with actual newcomer, user, developer, and agent tasks.

中文

问题

文档系统拥有健全的放置、新鲜度、链接、双语和源等价性检查，却没有把「简短、直观、友好」定义成可供用户、新人、开发者和 agent（智能体）评审的结果。全部 doc-sync（文档同步门禁）检查和全部翻译配对均通过，但仍存在以下设计问题。前三项发现是设计重点；容量问题则解释了为什么增加更多常驻规则无法解决它们。

语义正确性可以在没有现行归属者的情况下通过检查

这些门禁证明结构和生成内容的新鲜度，却不能证明维护中的正文仍指向实际机制。以前的 dsh-doc-site-sync 技能曾要求作者复用并不存在的 en-docs 侧边栏，还要求把章节加入已经移除的 sectionOrder；website/docs.ts实际拥有 en-guide、en-develop、en-reference 和 sections。已实现的产品优先 README 决策描述了内部测试说明，以及 ACP、Python 与 JSON-RPC 界面章节，但根 README并无这些内容；与此同时，已实现 Agent Note 必须跟随已交付事实。

预算策略也存在相同的分裂。docs/AGENTS.md为 architecture.md 规定 1,800 词目标和 5% 余量，但预算 manifest（元数据清单）允许 2,400 词，而该文件实际包含 1,313 词。预算门禁之所以通过，是因为它只检查 manifest 上限，不检查目标或棘轮规则。因此，高影响正文需要一个具名真源或消费真源的聚焦检查；第二份手写副本不是新鲜度机制。

读者成功与否是隐含判断，而不是可测试结果

标准把页面分成教程和参考，并要求作者私下判断教程读者的起始水平。标准没有要求留下可供评审的读者起始状态、预期结果、最短成功路径、常见失败或下一篇有用页面。因此，一份文档可以满足层级放置、链接、词数限制和 Markdown 结构，却没有证明目标读者能完成任务。

公共站点直观呈现了这种压力。每种语言发布 84 个页面：3 个指南页面、17 个开发页面和 63 个参考页面。docs/user/ 下的 13 个英文文件共有 7,540 词，而 47 个子系统页面共有 100,759 词。简短的 Web 快速开始是良好的产品入口，但全语料没有标准来验证首次使用者、插件新人和维护者是否都能沿一条明确路径从入口走到结果与故障恢复。

生成内容的准确性与检索质量混为一谈

仓库包含 19 个完全生成的英文 Markdown 文件，共 49,611 词。47 个子系统页面中有 44 个也包含生成的 Cordis 区域；这些区域占子系统层级 100,759 词中的 34,622 词。config-catalog.md 有 14,807 词，tool-catalog.md 有 10,599 词，最大的混合子系统页面则有 5,600–7,781 词。

这些内容是正当的穷尽式参考，因此统一词数限制反而会删除价值。生成器证明完整性和新鲜度，但标准没有为上下文窗口有限的 agent，或只寻找一个答案的人类读者另设检索标准。生成参考需要紧凑的入口层、稳定分组、直接锚点，以及根据查询成本触发的拆分规则；穷尽式细节可以在该入口层之后继续保持穷尽。

标准没有容纳下一条规则的空间

常驻文档标准有 1,320 词，等于 1,320 词上限，并超过声明的 1,250 词目标。根 AGENTS.md 有 1,936 词，目标为 1,600；packages/AGENTS.md 有 672 词，目标为 650；packages/README.md 有 969 词，目标为 600。冻结的上限能阻止进一步增长，却没有为受众和结果标准创造位置。继续增加常驻正文会加深该标准本应防止的问题。

基线

本次审计排除 vendor/、冻结的 .agents/notes/archived/、录制快照和 fixture（测试前置数据）。受维护语料包含 1,042 个英文 Markdown 文件和 986 个中文对侧文件，共 1,106,138 个英文词。活跃 Agent Note 占 580 个文件和 637,850 词；packages/ 下的 Markdown 占 276 个文件和 225,630 词；docs/ 占 112 个文件和 193,456 词。这些数量描述维护和检索压力，本身并不构成缺陷。

系统最强的性质应予保留：按层级为每项事实指定一个归属者；把规范 Markdown 投影到站点而不创建副本；完整双语配对；源变更时快速失败的生成目录；源等价声明；可编译的 TypeScript 示例；受检查的链接与锚点；以及包局部的模型体验与限制约定。提案改变的是质量标准和入口结构，而不是这些保证。

提案

采用一套以受众为先的质量约定，并给出五项定义：

简短表示常用路径只包含达成结果所需的事实。穷尽式约定仍可通过直接链接或生成细节访问；简短绝不意味着删除必要行为、失败、所有权或限制。
直观表示页面会确定读者的起始状态，在依赖概念之前介绍前置知识，提供一个明确的下一步操作，并使用读者会搜索的产品或领域术语。
友好表示读者能识别成功，在操作前理解实质风险，从常见失败中恢复，并在无需先学习无关架构的情况下进入下一层相关细节。
准确表示每项持久事实都有一个归属者和与风险相称的验证路径。生成事实来自源；手写工作流值链接或消费其归属者，而不是复制枚举和路径。
便于 agent 阅读表示标题、锚点、术语、所有权以及当前与提议状态足够明确，无需加载整个语料或重建评审历史即可检索所需章节。

原型规则

dsh-doc skill 负责这些规则的首个可执行版本。session-persistence-jsonl README 对以已交付的追加、恢复与编码行为为证据，而不把其旧版正文当作权威。

每个撰写型包 README 都以可搜索 YAML 开头。Skill 风格的 description 与按机制推导的 kind 为必填字段。四种 kind 与四个技能模板一一对应：package-group（组地图）、package-reference（插件或服务包）、package-library（纯模块入口）与 package-bundle（dsh.bundle.patch）。对照文件路径、哈希与物理行对齐由支持自动合并的 sidecar 及其门禁负责，因此 README frontmatter 不包含 i18n 块。名称已由标题或包 manifest 归属，受众已由文档职责表达；在受治理的标签分类与搜索消费方证明其价值超过全文检索之前，不加入标签。
撰写型页面先写三至五句的 Summary，再写带链接的 Table of Contents。英文包 README 的 Summary 不超过 100 个按 wc -w 语义统计的词。它描述读者可见能力，而不是 Cordis 角色、注册项或内部组件；除非读者会在配置、命令或公开 API 中直接使用某个源码标识符，否则不得写入该标识符。由格式约束的 Agent Note、事故复盘、生成片段和机器文件保留其必需骨架。
每个实质章节在子章节、表格或代码之前先给出简短引导，页面则从基础用户用法逐步进入高级开发者与维护者细节。
英文技术正文采用受 ASD-STE100 启发但不宣称认证的清晰度评审：明确行动者与动作，稳定使用术语，使用直接动词，拆分指令与条件，并完整保留情态、例外、时序与数值。指令 20 词和描述 25 词的限制仅作评审提示。准确性高于句长。
包约定留在代码旁。跨包材料有计划地向 docs/learn/overview/、docs/learn/cordis/、docs/learn/practices/、docs/user/、docs/developer/、docs/developer/discussion/、docs/scratch/ 和平行的 docs/subsystems/ 层级迁移。
英文和中文页面保持同等权威，并在结构、链接、代码、frontmatter 布局和精确物理行数上一一对应。
内联配对元数据是伴随文件的目标替代方案。在验证器、合并驱动、恢复流程、生成区域记录器和归档检查消费非自引用配对摘要之前，原型可以同时保留两者。
仓库根级内部链接是目标撰写模型。原型保留渲染器可用的相对链接，因为前导 / 当前会在 GitHub 上离开仓库、绕过 verify-md-links，并且不会由站点投影。
Further Exploration 是可选的新人路径，链接三至七个相邻页面。
每个撰写型页面都以 Dev Note 结尾，作为活跃粗略上下文的唯一位置。它保持非权威状态，只链接而不复制任务状态，并在工作结束时完成提升或清理。
可独立搜索的规则、实践、示例和决策在拥有不同归属者或变更节奏时，使用描述性目录下的小文件；紧密耦合的义务保留在一起。

按文档职责划分的标准

职责	主要结果	必需入口信息	验证
产品快速开始	完成一项有代表性的任务	前置条件、一个启动路径、首次成功、安全边界、下一步	文档路径的构建或打包冒烟测试，加链接和站点检查
用户任务指南	完成一项用户任务或从中恢复	起始 UI／API 状态、有序操作、可观察结果、常见失败及恢复	行为测试；涉及视觉状态时评审截图；或指定人工归属者
贡献者教程	进入通过检查的开发状态	支持的运行时、设置命令、预期结果、聚焦的后续命令	在受支持环境中对干净检出运行命令冒烟测试
架构概览	从一个页面重建系统	产品组合、归属者、依赖方向、扩展点、细节链接	由源支持的包或图检查，加聚焦人工评审
包或子系统参考	无需阅读实现即可查到一项约定	范围、归属的类型或行为、失败、生命周期、限制、相关归属者	既有 JSDoc、类型等价、生成区域、README 和链接检查
生成参考	找到一个精确条目并信任其完整性	范围、生成归属者、分组或索引、稳定锚点、相关概念指南	确定性 `--check`、完整性 fixture、站点构建和检索规模报告
Agent 指令或 skill（技能）	在没有陈旧复制值的情况下执行一项工作流	范围、权威链接、必需决策、仅在此处归属时写入精确命令	元数据或链接检查，以及针对复制机器值的聚焦测试
提议或已实现 Agent Note	理解决策、取舍与状态	问题、提案或决策、备选方案、验收或后果	既有生命周期、格式、配对和取代检查；语义时效性由评审负责

该表应归属一份规范质量参考。docs/AGENTS.md 只保留每次编辑文档都需要的简短常驻规则，并链接到该参考。这样可以创造预算余量，而不是把另一份完整标准放进 agent 上下文。

生成参考的入口层与细节层

每份生成参考都应在穷尽式输出之前提供紧凑入口层：范围、预期查询、分组或索引、概念指南的直接链接，以及生成器或检查命令。生成器应报告页面词数、条目数、标题数和最大章节。当一次查询需要扫描无关分组，或单页主导 agent 上下文时，该页面便跨过评审阈值；随后，归属者按照源元数据中已有的稳定领域拆分页面，而不是按任意词数切片。

首个原型应选择一个大型目录和一个混合子系统页面。在进行全语料拆分前，它应比较查询步骤、生成 diff 大小、构建时间、路由稳定性，以及代表性问题所需的 agent 上下文。路由移动时，既有锚点需要保留别名。

执行切片

创建并验证 dsh-doc，再把一组 package README 对改写为行对齐、带元数据的原型，同时不改变运行时事实。
用新人、用户、开发者和 agent 任务评审渲染后的原型；先修订 skill，再在其他位置强制执行该格式。
添加聚焦的元数据、Summary 长度、章节顺序、行对齐、链接解析和配对 fixture。迁移所有违反已接受入口上限的既有包 Summary；在每个合并与恢复消费方都有替代支持前，保留伴随文件。
把已接受的常驻规则提取到一份规范质量参考，将 docs/AGENTS.md 精简到目标以下，并且一次只组织一个内聚的 docs/ 主题，同时原子地修复链接与导航。
在 config-catalog.md 和 docs/subsystems/core.md 上制作生成参考入口层与细节层分离的原型；只有实测查询成本下降且没有丢失事实或造成路由扰动，才把确认后的模式应用到其他位置。

该顺序使每项变更都能独立评审。前三个切片改进标准与包入口，而不改变更广的信息架构；生成文档原型则在更广的结构变更前提供证据。

切片 1–3 已按此形式交付：dsh-doc 成为合并后的标准（dsh-doc-standards 与 dsh-doc-site-sync 已并入其中，站点工作流携带修正后的侧边栏值），session-persistence-jsonl README 对是参考示例，pnpm run test:docs 强制执行元数据、配对与快速文档检查。切片 4–5 仍待完成。

非目标

本提案不缩减穷尽式事实，不合并受众层级，不发布内部决策记录，不恢复 Agent Note 索引，不为了文件数对称而拆分紧密耦合的规则，也不把此次审计当作用户研究。在替代方案通过等价的恢复与渲染检查前，本提案不删除现有配对或链接基础设施。

考虑过的备选方案

**为每份文档设置统一词数上限。**不予采纳，因为穷尽式参考条目、公开约定和决策理由可以既长又正确。对这些文档职责而言，入口路径长度与查询成本才是相关约束。

**强制使用统一页面模板或受众前置元数据。**不予采纳，因为这会给生成页面、包参考和简短指令增加形式，却不能证明读者成功。标准按文档职责定义结果，仅在 kind 能选择具体包文档标准时使用它，并且只添加聚焦检查或评审会消费的字段。

**把可读性分数作为质量门禁。**不予采纳，因为公式会惩罚精确技术术语，却无法发现错误所有权、遗漏失败行为、陈旧命令或破损的读者路径。

**立即重写或拆分全部文档语料。**不予采纳，因为现有系统在机制上健康，许多长参考也确实应保持穷尽。范围受限的包 Summary 迁移不会改变路由或穷尽式参考内容；更大的结构变更仍需实测证据。

**保留现有门禁，让评审负责友好程度。**不予采纳，因为陈旧工作流值和预算策略不一致说明，仅凭评审无法保留复制的语义事实，而现有门禁也不询问读者是否能完成任务。

验收标准

一份规范质量参考按文档职责定义简短、直观、友好、准确和便于 agent 阅读的文档。
.agents/skills/dsh-doc 通过验证，并直接链接其元数据、结构或层级及评审或原型参考，而不在 SKILL.md 中复制这些参考的详细规则。
session-persistence-jsonl README 对展示可搜索 YAML、Summary、Table of Contents、从用户到开发者的渐进结构、Further Exploration、结尾 Dev Note、结构一致性和精确行数相等，同时保留已验证的包约定。
每个英文包 README Summary 都不超过 100 个按 wc -w 语义统计的词；聚焦门禁报告实测词数，并引导失败项阅读 dsh-doc 与所选 kind 模板。
docs/AGENTS.md 链接该参考，仍足以充当常驻指令，并低于其目标且至少保留 5% 余量。
根级用户路径、Web 快速开始、第一个插件教程、贡献者设置和架构概览各自给出一个可观察结果与验证归属者，同时不复制实现细节。
预算 manifest 同时记录目标与临时上限，其检查会报告或拒绝违反余量或棘轮规则的状态。
文档站工作流不再包含复制的无效侧边栏名称或章节归属声明，并有聚焦测试防止复发。
sidecar 继续作为唯一一致性记录，因为它能保留同等权威、上次确认文本恢复、自动合并安全、生成区域记录和归档封存，同时不会在正文文件中制造冲突。
一个已接受的仓库根级链接格式在迁移相对链接前能在 GitHub 与文档站正确渲染，并继续接受本地目标或锚点检查。
一个大型独立生成目录页和一个混合子系统页面展示紧凑入口层与更低的实测查询成本，同时保留穷尽式生成事实、稳定链接、双语配对和确定性新鲜度。
pnpm run doc-sync、pnpm run lint、聚焦的新检查和 git diff --check 均通过。

风险

元数据可能沦为样板；因此包 README 检查只允许具有现行检索、模板选择或双语一致性消费方的字段。
硬性句长限制可能割裂说明，或把条件与后果分开。受控英语的句长仅作评审提示；单独的 100 词包 Summary 上限只约束入口段落，精确约定仍保留在其归属章节。
精确行对齐可能迫使译者写出不自然的正文；评审必须保护含义，并可同时修订两侧，而不是削弱其中一侧。
拆分生成参考可能增加路由与链接维护；原型必须保留别名并衡量取舍。
语义检查可能膨胀成阻塞正当变更的仓库拓扑扫描器；检查应覆盖高风险复制值和代表性路径，而正文含义仍由评审负责。
包 README 的快速参考表会手工重复部分配置默认值；在源驱动检查接管之前，评审者必须对照源码和生成配置目录验证变更值，并让这些表保持精选而非穷尽。
为缩短 agent 上下文而优化可能使人类参考变得碎片化；每次拆分都需要一个稳定概念归属者和一条明确导航路径。
永久的 Dev Note 可能变成第二份队列或陈旧历史堆积；完成工作时必须提升持久事实并删除已解决的过程内容。
本次审计使用仓库结构、门禁和代表性页面，而不是用户研究。在广泛推广之前，维护者应通过真实的新人、用户、开发者和 agent 任务验证提议的读者结果。