Turtle
03e70034e6
* feat(release): publish package source, declaration maps, and documentation Every release member publishes its TypeScript source and the declaration maps that resolve into it, and @deepseek-ai/dsh publishes the repository Markdown documentation staged from docs/ at prepack time. The ./src/* export most members already declared now resolves for an installed consumer, and a consumer editor follows a declaration to the implementation. Bundled JavaScript maps stay unpublished; the vendored family and the Desktop runtime file policy are unchanged. Rationale: .agents/notes/implemented/process/2026-10-08-published-source-and-docs.md * feat(release): publish JavaScript maps and compress bundles Every emitted JavaScript map ships beside the bundle it describes, and the workspace build and the client preset compress bundles without mangling identifiers. The documentation payload now mirrors the website publication manifest and is removed again by `postpack`; Desktop and the Python executable exclude the published source, documentation, and maps; `clean` removes a staged copy. Typert's publication contract gains the Remote declaration map. * fix(release): keep node bundles readable for the worker image The browser worker image lowers `yield*` only as a whole statement and rewrites `for await` loops by their source layout, so compressed node-side entries either fail that lowering or lower to unparseable code. Only the browser bundles keep compression, which removes about a third of their text. The bundle-purity assertion now matches the module-loader call regardless of the quote style compression picks, and the release-pack fixture exercises the installed package's new documentation requirement. * feat(release): publish the whole documentation tree `@deepseek-ai/dsh` copies `docs/` in full instead of the website's page set: the maintainer documents, the generated migration records, the translation guidelines, and the `*.i18n.yaml` consistency records ship with the installed package, so the documentation's own links resolve without a checkout. * feat(release): publish the upgrade guides with the documentation The staged documentation keeps the website's page set and adds every `docs/upgrade-guide/` document, which is what an installed reader consults when a released change breaks something. The rest of the maintainer tree stays out. * feat(agent-preset): ship plugin artwork skill with creator mode * docs(skills): clarify artwork icon lookup and official review steps * refactor(agent-preset): fold plugin artwork into cordis plugin development * feat(agent-preset): require detail documents for creator bundles * test(release): expect source and maps in master's new payload cases * refactor(agent-preset): consolidate creator skills into dsh-doc * feat(release): keep installed docs and source readable in Desktop Desktop keeps the published src/ and docs/ trees inside app.asar, and every model shell call receives DSH_INSTALL_DIR and DSH_NODE_EXECUTABLE so an agent can read them through Electron's Node mode. Staging also generates docs/upgrade-guide/README.md, an index of the upgrade guides grouped by the release they upgrade from. Minified client bundles print string literals with backticks: the worker image packer now recognizes those chunk requests, client license banners are prepended after minification so their text survives, and the affected artifact tests accept either quote. * docs(agent-preset): add dsh-doc install, upgrade, and fallback guidance * docs(agent-preset): align dsh-doc archive reads and upgrade start versions * docs(agent-preset): bound dsh-doc upgrade index reads and test documented commands * test(desktop): read archived docs through the Windows PowerShell form Regenerate the config catalog for the shifted shell-env source line. * docs(upgrade-guide): correct dsh-doc session verification step * test(agent-preset): use a block body for dsh-doc fixture cleanup * test(desktop): wait for the GUI-subsystem Electron process from PowerShell * docs(agent-preset): read the running DSH version from the installation * build(release): publish source and maps from the message-quotes package * docs(agent-preset): document the verified PowerShell runtime invocation * docs(agent-preset): keep PowerShell runtime output streams and exit code * docs(tool-cordis): describe the shipped dsh-doc skill * docs(skills): load configuration guidance separately * fix(skills): declare shared template details in every locale * fix(skills): verify dsh-doc guidance through recorded sessions * test(skills): retain current runtime reminder in dsh-doc replay * test(snapshot): refresh terminal panel runtime context
11 KiB
AGENTS.md — The documentation standard
This file defines document structure, Markdown tiers, writing rules, and verify-doc-budgets ceilings. Use dsh-doc-writing for placement and validation, and dsh-prose-standard for required coverage and editorial judgment; the archived doc-tiers Agent Note records the historical rationale.
Document structure
These rules apply to human-facing documentation; Agent Notes remain outside their scope. A postmortem 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 | 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/ | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
| Agent Notes | 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/ | 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/ | Incident stories — the only tier where war-story narrative belongs | — |
| Persistence history and format references | Type-change acknowledgements, release comparisons, and complete historical format schemas | Behavior-only changes; current runtime contracts |
| cookbook/ | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
| user/ | 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 | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
| development.md | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the i18n contract | 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/, the Cordis core API + inherited tier, tool-catalog, config-catalog, persistence-catalog, module-graph.md, cli-help |
Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the pairing workflow | 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; 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).
- 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
tsblocks 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). - The owning subsystems page updates in the same change that reshapes a documented type.
verify-type-equivcatches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page (page scoping). - Pairs update together: Terminology-guided, single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records;
dsh-translate-docsremains user-invoked (contract). - 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 for details.
- Write directly: name actors and facts (reference). Reserve
seamfor 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 sets standing-doc ceilings; pnpm run verify-doc-budgets rejects excess or missing files.
When the gate goes red:
- Relocate content that belongs in another tier; leave a one-line link if needed.
- Condense content that belongs here but can be shorter.
- 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-writing 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.
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 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.