chemenu/instructions/dev/doc-pull-through.md

type, name, description

type	name	description
types/instruction.md	doc-pull-through	Which document makes a claim about a surface you are about to change - a wikitool command's behaviour, a stage's rules, an AGENTS.md rule/gate/invariant, a README-shaped human doc, a docs/ page's reasoning - and so needs updating in the same session, since tools/wikitool docs verify never reads a cell's prose.

Update every document that makes a claim about the surface you changed

tools/wikitool docs verify is a hard oracle over presence, not content: it checks that a command is listed, that a contract exists, that an ignore canary is (or isn't) caught - never what a table cell, a contract section, or a README paragraph actually says. A command's flag can change, a gate's threshold can move, a contract's wording can go false, and every one of those checks stays green (Gitea #90; Gitea #91 narrows what the command-table check matches, but adds no reading of cell content). Content quality of every document below is therefore session work, the same duty AGENTS.md's Changelog section states for README.md, tools/README.md and the pages under docs/ - this instruction exists because that duty used to stop at the human docs while the contracts rotted next to a green check (ten stale error-contract rows accumulated this way; see Gitea #89 for one).

When to run

Before tools/wikitool docs verify/publish in a build session that changed behaviour - stack-build step 5 sends you here. Read the table below and update every row whose surface you touched; a row that does not apply needs no action.

Steps

1. Name the surface(s) you changed. A wikitool command's flags or behaviour, a stage's rule, an AGENTS.md-level rule/gate/invariant, a workflow a human runs by hand, or the reasoning behind a design decision - one change can touch more than one row.

2. For each surface, update every document the table names - not only the one you were already editing:

   Touched surface	Document(s) that make a claim about it
   A wikitool command's behaviour, flags, or interface	Its cli_contract.CommandRecord (name, synopsis, properties, exit status, retry policy - tools/chemenu/cli_contract.py), then wikitool docs contract --apply to regenerate its copy in tools/CONTRACT.md and wikitool docs reference --apply for the human reference under docs/reference/ (a new group in cli_contract.GROUPS first needs its page there, with a title, a one-sentence head and the marker pair)
   A stage's authoring rules (raw/, kb/, types/, reports/, work/, tools/, instructions/)	The touched <stage>/CONTRACT.md
   A rule, gate, or invariant AGENTS.md itself states	The relevant AGENTS.md section (Invariants, Gates, File naming, Routing, ...)
   A workflow, stage, or command a human operates by hand	Whichever of README.md, tools/README.md, INSTALL.md or the pages under docs/tutorials/, docs/how-to/ and docs/reference/ names it - AGENTS.md § File naming says which document is for which reader. A new page goes into the area its kind of documentation belongs to; that area's README.md says which
   The reasoning behind a gate, boundary, or design decision	The docs/explanation/ page that carries it, if one exists (AGENTS.md § File naming lists all seven reached from AGENTS.md itself, plus an eighth reached only from CLAUDE.md). A decision with no page yet is the gap worth closing: reasoning that lives only in a Gitea issue never ships - dist export carries docs/explanation/ and no issue tracker, so a distributed instance gets the mechanism without the why
   A task-tracker adapter (tools/chemenu/tasks/), its recorded fixtures, or the live suite	instructions/dev/tracker-testing.md, and MANIFEST.json beside the fixtures when they were re-recorded
   A skill's own step sequence or catalogue	The skill's SKILL.md source under instructions/<name>/ or instructions/dev/<name>/; for a shipped skill (not under instructions/dev/) whose name or description changed, or one added or removed, wikitool docs reference --apply for the skill catalogue docs/reference/skills.md
   A section of the tiered settings (wikitool.json, .wikitool-local.json; config_shapes.SETTINGS_SECTIONS)	Its shape - a field, a default, what is required or tolerated - is its record in tools/chemenu/config_shapes.py, which the loader reads; change it there, then wikitool docs reference --apply for its region in docs/reference/configuration.md. What a setting does is the hand-written prose around that region. Also the setup-instance.md decision point that offers the section during setup, and doctor's own row in tools/CONTRACT.md, since doctor is what reports the section's state
   An installation instruction - preflight.md, setup-instance.md, bootstrap.md, upgrade-instance.md - or tools/prerequisites.txt	INSTALL.md, the human guide to the same procedure - for upgrade-instance.md, docs/how-to/update-an-instance.md instead. Read it against the instruction: what to prepare, the sentence for the agent, what the agent asks, where it stops and why. docs verify checks only the two enumerable overlaps - the prerequisites lists, which wikitool docs prerequisites --apply regenerates from the manifest, and the setup questions: a question the agent asks the user carries <!-- setup-question: <key> --> where it is asked in setup-instance.md, and INSTALL.md § "What the agent asks you" names it with the same marker. Every other sentence is this session's to compare. INSTALL.md does not retell the steps, so a change to their order or wording alone moves nothing there
   dev-setup.md, the release workflow (version bump/version release/publish/CI), or another developer-facing process	docs/dev/development.md, read against it the same way - nothing checks this pair at all. A page under docs/dev/ is never shipped, so it may link into instructions/dev/ and cite issue numbers
   A new page type the stack requires, or a new collection	Its type-spec and COLLECTION.md (both as the .template an instance adopts), the collection table in kb/CONTRACT.md, and both adoption paths: setup-instance.md for a fresh instance and upgrade-instance.md for an existing one, where an unadopted template is what docs verify refuses. A new or changed root: kb type-spec or its schema - description, layout:, subtype enum, required fields - also needs wikitool docs reference --apply for docs/reference/page-types.md

3. A heading you changed means a table of contents to regenerate - by the tool, never by hand. Every reference file over 100 lines carries one (AGENTS.md, the stage contracts, kb/CONVENTIONS.md, each COLLECTION.md, the flat instructions/**.md form, the type-specs, the docs/ pages in all five areas - each with the <name>.template it ships as, where one exists, and a SKILL.md the one exception). Adding, renaming, reordering or deleting a ##/### heading in one of them makes its region stale, and docs verify fails on stale exactly as it fails on missing:

   tools/wikitool docs toc          # dry run: which files would change
   tools/wikitool docs toc --apply  # write them
   

   The region is generated, so AGENTS.md invariant 1 applies to it like any other: editing the list by hand is the failure, not the fix - and a hand-written entry survives until the next --apply silently disagrees with it. It is cheap to over-run: --apply is idempotent and a file whose headings did not move is left untouched.

4. Do not re-derive what docs verify already checks mechanically - existence, table-row membership, ignore-canary state. That enumeration lives once, in tools/CONTRACT.md's own docs verify row; copying it here would be a second copy that drifts, the exact failure this instruction exists to describe (Gitea #90). This instruction is only about the prose no check reads.

Decision points

• The change touched no document in the table? Nothing to do - not every stack change moves a claim. A pure bugfix with an unchanged interface is the common case.
• Unsure whether a docs/explanation/ page's reasoning moved? Read it. A docs/ page carries no normative sentence and nothing verifies it by construction (AGENTS.md § File naming), so an unsure guess defaults to reading the page rather than skipping the question - stack-close step 3 asks it again in the closing phase as a backstop, not as the only time it is asked.
• The surface is a whole new stage, collection, or gate? The table's rows are the steady state; a new row-worthy category is itself a change to this instruction - add the row here rather than leaving the next session to rediscover the gap.

Scope

Applies to stack-development sessions only - wiki content changes have their own provenance and cross-reference rules (kb/CONTRACT.md, wiki-manage), which already pull the relevant pages through as part of the normal skill. Not a replacement for stack-close step 3, which re-asks the docs/-staleness question after the green CI run as the second, final check.