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

docs/reference/commands/guideline-export.md

@@ -0,0 +1,77 @@
+# Guideline export
+
+Writing the generated `GUIDELINES.md` into the repositories the wiki has captured.
+
+<!-- wikitool:reference-commands -->
+## `export guidelines`
+
+Render the guideline pages into one generated `GUIDELINES.md`, or push it into the captured repositories that opted in (**Guideline Push Gate**).
+
+**Synopsis**
+
+- `wikitool export guidelines [--field <predicate> ...] [--kind/--subtype/--collection/--tag <v>]` - Prints the file to stdout; no network.
+- `wikitool export guidelines <predicates> --push [--bundle <raw-bundle> ...] [--confirm TOKEN]` - Writes it into the captured repositories, behind the gate.
+
+**Options**
+
+```text
+  -f, --field <str>   Frontmatter predicate, repeatable (AND) - the same forms
+                      as `search --field`.
+  --kind <str>        Shorthand for --field kind=<value>.
+  --subtype <str>     Shorthand for --field subtype=<value>.
+  --collection <str>  Shorthand for --field collection=<value>.
+  --tag <str>         Shorthand for --field tags=<value>.
+  --push              Write the file into the captured repositories (Guideline
+                      Push Gate).
+  --bundle <path>     Only the repository of this captured bundle under raw/;
+                      repeatable.
+  --confirm <str>     The token from a prior exit 42, once a human has approved
+                      it.
+  -h, --help          Show this message and exit.
+```
+
+**Examples**
+
+```bash
+tools/wikitool export guidelines --tag guideline
+tools/wikitool export guidelines --tag guideline --push
+tools/wikitool export guidelines --confirm <token> --push --field tags=guideline    # re-run after exit 42, once the user approved every diff
+```
+
+**Behaviour**
+
+- Selects pages with `search`'s own predicates and no text: `--field` (repeatable, AND), `--kind`, `--subtype`, `--collection`, `--tag`. Which filter selects this instance's guidelines is written down in `kb/CONVENTIONS.md`.
+- Renders mechanically: line 1 is `<!-- wikitool:export kind=guidelines instance=<origin URL without userinfo, or local> commit=<newest commit touching a selected page> - generated, do not edit by hand -->`; then each page sorted by title, as `# <title>` and its text without frontmatter, the generated links and footnote blocks, citation markers (`[^id]`, legacy `^[[...]]`), with `[[Title|Text]]` as `Text` and `[[Title]]` as `Title`. A leading H1 of the page is replaced by the title heading. Code is never rewritten. LF endings, no timestamp: the same pages give the same bytes.
+- Refuses before printing or pushing anything: no predicate, no match, an unknown field, any page under `kb/` with unreadable frontmatter, uncommitted changes in `kb/` or `types/` (untracked files included), or no git checkout.
+- `--push` targets every captured repository - each `(repo, ref)` from a `_capture.json` under `raw/`, `--bundle` narrowing it. A target is skipped with its reason when its ref rule is a tag pattern, it cannot be reached or has no such branch, its root has no `GUIDELINES.md` (not opted in), its `GUIDELINES.md` has no export header (hand-written), or the header names another `instance=`. A header line alone is the opt-in.
+- Guideline Push Gate: `--push` without a matching `--confirm` fetches and builds everything, pushes nothing, and exits 42 with each target's status (`new`, `changed`, `unchanged`, `skipped`), the diff for every target it would write, and the re-run line. The token digests URL, branch, old tip and new blob of every target to write.
+- With a matching token, each target gets exactly one commit on the fetched tip changing only `GUIDELINES.md`, authored as the instance checkout's `user.name`/`user.email`, pushed without force; one line per target: `unchanged`, `written <old> -> <new>`, `skipped (<reason>)`, `rejected (<reason>)` or `failed (<reason>)`.
+- Nothing to write (every target unchanged or skipped) ends with exit 0 and no gate. A second run after a successful one finds every target unchanged.
+- The target repository's own `AGENTS.md` points at the file (Claude Code: `@GUIDELINES.md`); that belongs to the repository, not to this command.
+
+**Properties**
+
+- Changes files: yes
+- Idempotent: yes
+- Atomic: Per target - one commit pushed without force, or nothing; targets already written stay written when a later one fails
+- Counts toward the session call budget: yes
+- Can reach the network: yes
+- Gates: guideline-push - see [exit codes and gates](../exit-codes.md)
+
+**Exit codes**
+
+- `0` - success
+- `0` - A target was skipped - tag rule, not reachable, not opted in, hand-written file, another instance's file
+- `1` - No predicate, no page matches, a malformed predicate or an unknown field
+- `1` - A page under `kb/` has unreadable frontmatter, `kb/` or `types/` has uncommitted changes, or the instance is not a git checkout
+- `1` - `--push` with no `user.name` or `user.email` in the instance checkout's git configuration - checked before any target is fetched
+- `1` - `--bundle` names no captured bundle under `raw/`, or `--bundle`/`--confirm` was given without `--push`
+- `1` - A target rejected the push (its branch moved since the fetch) or a git call failed - the other targets were still served
+- `42` - Guideline Push Gate: `--push` without `--confirm`, or with a token that does not match the current set of targets
+
+**See also**
+
+- `wikitool search` - the same predicates, to preview the selection
+- `wikitool raw capture` - how a repository becomes a target
+- `instructions/gates.md` - the gate procedure
+<!-- /wikitool:reference-commands -->