feat: docs reference generates a human command reference under docs/reference/ from the command records, one page per group plus exit codes and gates; toc never lands inside another generated region (#188)

Files changed:
- CHANGES.md
- README.md
- VERSION
- docs/reference/README.md
- docs/reference/commands/README.md
- docs/reference/commands/catalog-and-log.md
- docs/reference/commands/content-migrations.md
- docs/reference/commands/distribution-and-versioning.md
- docs/reference/commands/finding-and-checking.md
- docs/reference/commands/git.md
- docs/reference/commands/guideline-export.md
- docs/reference/commands/instance-health.md
- docs/reference/commands/links-and-citations.md
- docs/reference/commands/pages.md
- docs/reference/commands/provenance.md
- docs/reference/commands/raw-material-and-uploads.md
- docs/reference/commands/telemetry.md
- docs/reference/commands/types-instructions-and-docs.md
- docs/reference/commands/workshop-runs-and-session-budget.md
- docs/reference/exit-codes.md
- instructions/dev/doc-pull-through.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/reference_doc.py
- tools/chemenu/tests/test_reference_doc.py
- tools/chemenu/toc.py

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2

tools/CONTRACT.md

@@ -11,7 +11,7 @@ not here.
 **Look up the command you need; do not read this file end to end.** Every
 command carries one data record - name, synopsis, properties, exit status, and
 so on - attached to its function in code (`tools/chemenu/cli_contract.py`).
-Three views render from that one source:
+Three views for an agent render from that one source:
 
 ```bash
 tools/wikitool raw accept -h        # the full record, for one command
@@ -24,6 +24,11 @@ The § Commands section below is `wikitool docs contract`'s output: an index
 as `#### <path>` records, in the same order `wikitool -h` prints. Reading the
 file end to end is for changing the CLI itself.
 
+A fourth view is for a person: `wikitool docs reference` renders the same
+records into one page per group under
+[`docs/reference/commands/`](../docs/reference/commands/README.md), leaving out
+ON FAILURE and NEVER, which address an agent.
+
 <!-- wikitool:toc -->
 ## Contents
 
@@ -140,6 +145,7 @@ docs verify           read  idempotent     budget:counted              exit:0,1
 docs toc              write idempotent     budget:counted              exit:0      Create, refresh or remove the generated table-of-contents region.
 docs prerequisites    write idempotent     budget:counted              exit:0,1    Regenerate `INSTALL.md`'s prerequisites lists from `tools/prerequisites.txt`.
 docs contract         write idempotent     budget:counted              exit:0,1    Regenerate `tools/CONTRACT.md`'s `<!-- wikitool:commands -->` region.
+docs reference        write idempotent     budget:counted              exit:0,1    Regenerate the human command reference under `docs/reference/`.
 eval sessions         read  idempotent     budget:exempt               exit:0      List the sessions that have a trace under `reports/telemetry/`.
 eval score            read  idempotent     budget:exempt               exit:0,1    Score one traced session.
 dist export           write idempotent     budget:counted              exit:0,1    Write a contentless, distributable copy of this repo's machinery.
@@ -2510,6 +2516,8 @@ Check the docs that mirror the code.
 - 1    A type-spec's own frontmatter fails its schema
 - 1    A subtype template `types/<type>.<value>.md` has no type-spec with a `subtype_field:` beside it, names a value outside that field's enum, or carries frontmatter
 - 1    A shipped `.md`/`.template` cites an issue number
+- 1    A region of the human command reference under `docs/reference/` is stale
+- 1    A page of the human command reference is missing or lacks its marker pair, or a page under `docs/reference/commands/` belongs to no group
 - 1    A reference file's table-of-contents region is missing or stale
 - 1    A file sits directly in `docs/`, or in a directory there that is not one of its five areas
 - 1    A reference file's relative markdown link does not resolve to an existing file
@@ -2526,6 +2534,8 @@ Check the docs that mirror the code.
 - A type-spec's own frontmatter fails its schema -> Fix the field, or add a matching line to `types/type-spec.schema.yaml` if the field is legitimately new
 - A subtype template `types/<type>.<value>.md` has no type-spec with a `subtype_field:` beside it, names a value outside that field's enum, or carries frontmatter -> Rename the file to the type and value it was meant for, delete it, or remove its frontmatter block
 - A shipped `.md`/`.template` cites an issue number -> Say what was decided instead of pointing at where, or move the pointer behind a `<!-- dist:strip-start/end -->` block
+- A region of the human command reference under `docs/reference/` is stale -> Run `docs reference --apply`, then re-run
+- A page of the human command reference is missing or lacks its marker pair, or a page under `docs/reference/commands/` belongs to no group -> Create the page with a title, a one-sentence head and the marker pair the message names (or add the pair), then run `docs reference --apply`; `git mv` or `git rm` a page left over from a renamed or removed group
 - A reference file's table-of-contents region is missing or stale -> Run `docs toc --apply`, then re-run
 - A file sits directly in `docs/`, or in a directory there that is not one of its five areas -> Move it (`git mv`) into the area its kind of documentation belongs to, and fix the links that pointed at the old path
 - A reference file's relative markdown link does not resolve to an existing file -> Fix the `../` count or the target's name
@@ -2535,11 +2545,11 @@ Check the docs that mirror the code.
 
 **NEVER**
 
-- Never hand-write a table-of-contents region or the commands region - regenerate it.
+- Never hand-write a table-of-contents region, the commands region or a reference region - regenerate it.
 
 **NOTES**
 
-- Checks the docs that mirror the code. The name is about documentation parity, not the `docs/` directory - it reads that only for its layout, and never requires one.
+- Checks the docs that mirror the code. The name is about documentation parity, not the `docs/` directory - it reads that only for its layout and its generated reference pages, and never requires one.
 - Commands: every command has a `cli_contract` record and is listed in `cli_contract.GROUPS`, in both directions; every command's non-hidden flags appear in its record's SYNOPSIS and vice versa; `tools/CONTRACT.md`'s generated `<!-- wikitool:commands -->` region matches what `docs contract` would write; no command's rendered `--help`/`-h` text cites an issue number.
 - Collections: every directory under `kb/` has a `COLLECTION.md` and no directory outside it does; every collection declares `profile:` and a `required_by_stack:` that agrees with the stack's own list.
 - Types: every type the stack lists (currently `source` and `project`) has a type-spec of that name whose schema requires the field the stack list names (`raw_files:`/`state:`); every file under `types/` declaring `type: types/type-spec.md` validates against `types/type-spec.schema.yaml`; every subtype template `types/<type>.<value>.md` (any `<value>` but `guidance`) sits beside a type-spec declaring `subtype_field:`, names a value that field's schema enum allows, and carries no frontmatter; no pre-migration `type: entity` blocks are left in the contracts.
@@ -2549,6 +2559,7 @@ Check the docs that mirror the code.
 - Every reference file `docs toc` covers carries the current table-of-contents region for its own headings - missing and stale are one check.
 - Every relative markdown link in one of those reference files resolves to an existing file. A target's `#anchor` suffix is stripped first, and code fences and inline code spans are masked before scanning, so link syntax shown as an example is not mistaken for a real reference.
 - Every file under `docs/` sits in one of its areas - `tutorials/`, `how-to/`, `reference/`, `explanation/` or `dev/` - never directly in `docs/` or in another directory.
+- If `docs/` exists: every generated region of the human command reference under `docs/reference/` matches what `docs reference` would write, every `cli_contract.GROUPS` entry has its page under `docs/reference/commands/`, and no page there belongs to no group.
 - `INSTALL.md` carries one generated `<!-- wikitool:prerequisites -->` region per platform value of `tools/prerequisites.txt` (`prerequisites-<platform>` for a platform-specific one), each current; and the `<!-- setup-question: <key> -->` markers in `instructions/setup-instance.md` and `INSTALL.md` name the same set of keys, so a question the agent asks is never one the human guide leaves out, nor the reverse.
 - `VERSION` parses and the newest versioned `CHANGES.md` entry names it. An entry that crosses the compatibility boundary from the last release carries `**Breaking Change:**`, has a migration document or `**Migration:** none required`, and its `**Migration:**` line names every required migration document targeting it.
 - The newest versioned `CHANGES.md` entry is at most 32 000 bytes (UTF-8) as `version notes` prints it, and each of its `###` sections is exactly one paragraph of at most 1 000 bytes, heading line excluded. Older entries and a changelog with no versioned entry are not checked.
@@ -2558,6 +2569,7 @@ Check the docs that mirror the code.
 
 - `wikitool docs toc` - regenerates tables of contents
 - `wikitool docs contract` - regenerates the commands region
+- `wikitool docs reference` - regenerates the human command reference
 - `wikitool docs prerequisites` - regenerates `INSTALL.md`'s prerequisites lists
 - `wikitool instructions verify` - the same kind of check for `instructions/`
 
@@ -2691,8 +2703,58 @@ Regenerate `tools/CONTRACT.md`'s `<!-- wikitool:commands -->` region.
 **SEE ALSO**
 
 - `tools/README.md` § Adding a command - how a command gets its record
+- `wikitool docs reference` - the same records, rendered for a person under `docs/reference/`
 - `wikitool docs verify` - checks the region is current
 
+#### `docs reference`
+
+Regenerate the human command reference under `docs/reference/`.
+
+**SYNOPSIS**
+
+- `wikitool docs reference [--apply]`
+
+**PROPERTIES**
+
+- effect: write
+- idempotent: yes
+- atomic: `--apply` rewrites each page in place, one at a time and idempotently, so a re-run after an interruption converges; the dry-run form is read-only
+- budget: counted
+- network: no
+
+**EXAMPLES**
+
+- `tools/wikitool docs reference`
+- `tools/wikitool docs reference --apply`
+
+**EXIT STATUS**
+
+- 0    success
+- 1    A reference page is missing, or lacks its region's marker pair
+
+**ON FAILURE**
+
+- A reference page is missing, or lacks its region's marker pair -> Not transient - create the page the message names with a title, a one-sentence head and the marker pair, or add the marker pair below its head, then retry
+
+**NEVER**
+
+- Never hand-edit a reference region - change the record in code and re-run this.
+
+**NOTES**
+
+- Rewrites the generated region of every page of the human command reference from the `cli_contract` records: one `docs/reference/commands/<group>.md` per `cli_contract.GROUPS` entry (`<!-- wikitool:reference-commands -->`), the overview in `docs/reference/commands/README.md` (`<!-- wikitool:reference-commands-index -->`), and the gates and exit-42 causes in `docs/reference/exit-codes.md` (`<!-- wikitool:reference-exit-codes -->`).
+- Renders each command's summary, synopsis, options, examples, notes, properties in words, exit codes with their causes and see-also - but not the ON FAILURE reactions or NEVER, which address an agent; `tools/CONTRACT.md` keeps those.
+- Refreshes the table of contents of each page it writes in the same step.
+- Never creates a page or places a region: a page's title and one-sentence head are written by hand. A group's page is named after the group - lower case, every run of other characters one hyphen.
+- Dry-run by default (lists the pages that would change); `--apply` writes.
+- `docs verify` checks the result stays current.
+
+**SEE ALSO**
+
+- `wikitool docs contract` - the same records, rendered for an agent into `tools/CONTRACT.md`
+- `wikitool docs verify` - checks every reference region is current
+- `tools/README.md` § Adding a command - how a command gets its record
+
 ### Telemetry
 
 #### `eval sessions`