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
This commit is contained in:
torbenandClaude Opus 5.5 committed
1 parent
01c888d3cd
commit
53383e7e9b
29 files changed
+5079
-29
No files matched your search
@@ -0,0 +1,267 @@
|
||||
# Content migrations
|
||||
|
||||
The migrations a release may require of an instance's content, and recording that they ran.
|
||||
|
||||
<!-- wikitool:toc -->
|
||||
## Contents
|
||||
|
||||
- [`migrate list`](#migrate-list)
|
||||
- [`migrate status`](#migrate-status)
|
||||
- [`migrate verify`](#migrate-verify)
|
||||
- [`migrate done`](#migrate-done)
|
||||
- [`migrate baseline`](#migrate-baseline)
|
||||
<!-- /wikitool:toc -->
|
||||
|
||||
<!-- wikitool:reference-commands -->
|
||||
## `migrate list`
|
||||
|
||||
List every migration document under `instructions/migrations/`.
|
||||
|
||||
**Synopsis**
|
||||
|
||||
- `wikitool migrate list [--json]`
|
||||
|
||||
**Options**
|
||||
|
||||
```text
|
||||
--json Print the migrations as JSON
|
||||
-h, --help Show this message and exit.
|
||||
```
|
||||
|
||||
**Examples**
|
||||
|
||||
```bash
|
||||
tools/wikitool migrate list
|
||||
```
|
||||
|
||||
**Behaviour**
|
||||
|
||||
- Lists every migration document under `instructions/migrations/`, oldest target first, with its kind and obligation.
|
||||
- Never fails. Read-only and **exempt from the Iteration Budget Gate**.
|
||||
|
||||
**Properties**
|
||||
|
||||
- Changes files: no
|
||||
- Idempotent: yes
|
||||
- Atomic: Read-only
|
||||
- Counts toward the session call budget: no
|
||||
- Can reach the network: no
|
||||
|
||||
**Exit codes**
|
||||
|
||||
- `0` - success
|
||||
|
||||
**See also**
|
||||
|
||||
- `wikitool migrate status` - which of them this instance still owes
|
||||
- `instructions/migrate-corpus.md` - how a migration is run
|
||||
|
||||
## `migrate status`
|
||||
|
||||
Show the migrations this instance still owes, in the order they must run.
|
||||
|
||||
**Synopsis**
|
||||
|
||||
- `wikitool migrate status [--json]`
|
||||
|
||||
**Options**
|
||||
|
||||
```text
|
||||
--json Print the chain as JSON
|
||||
-h, --help Show this message and exit.
|
||||
```
|
||||
|
||||
**Examples**
|
||||
|
||||
```bash
|
||||
tools/wikitool migrate status
|
||||
tools/wikitool migrate status --json
|
||||
```
|
||||
|
||||
**Behaviour**
|
||||
|
||||
- Shows every **required** migration whose `migrates_to` lies in `(kb_version, VERSION]`, in the order it must run.
|
||||
- `offered` migrations are listed separately above the chain: they never block, never count as owed, and are bounded by the applied ledger rather than by `kb_version` - taking one does not move the version.
|
||||
- With a release stamp present, also reports which shipped files this instance has since edited (from the per-file sha256 in `.wikitool-release.json`) - which says whether an offer may be copied over or has to be reconciled by hand. Without a stamp that question is reported as unanswerable rather than answered.
|
||||
- Exits 1 only when the content version is undeclared (`.wikitool-kb.json` missing) or `VERSION` is unreadable; it never guesses the content's shape.
|
||||
- Read-only, safe to retry freely, and exempt from the Iteration Budget Gate.
|
||||
|
||||
**Properties**
|
||||
|
||||
- Changes files: no
|
||||
- Idempotent: yes
|
||||
- Atomic: Read-only
|
||||
- Counts toward the session call budget: no
|
||||
- Can reach the network: no
|
||||
|
||||
**Exit codes**
|
||||
|
||||
- `0` - success
|
||||
- `1` - `.wikitool-kb.json` is missing - the content version is undeclared
|
||||
- `1` - `VERSION` is unreadable
|
||||
|
||||
**See also**
|
||||
|
||||
- `wikitool migrate done` - records one as applied
|
||||
- `instructions/migrate-corpus.md` - how a migration is run
|
||||
- `instructions/upgrade-instance.md` - where an upgrade checks this
|
||||
|
||||
## `migrate verify`
|
||||
|
||||
Compare `kb/` against a git revision on the invariants a content migration must not change.
|
||||
|
||||
**Synopsis**
|
||||
|
||||
- `wikitool migrate verify --from <rev> [--path P ...] [--expect-body-change] [--json] [--fail-on-error]`
|
||||
|
||||
**Options**
|
||||
|
||||
```text
|
||||
--from <str> Git revision to compare against, e.g. HEAD [required]
|
||||
--path <str> Limit to a subtree, repeatable (e.g. kb/concepts)
|
||||
--expect-body-change Also report pages whose body did not change at all
|
||||
--json Print the diff as JSON
|
||||
--fail-on-error Exit 1 if any invariant changed
|
||||
-h, --help Show this message and exit.
|
||||
```
|
||||
|
||||
**Examples**
|
||||
|
||||
```bash
|
||||
tools/wikitool migrate verify --from HEAD
|
||||
tools/wikitool migrate verify --from HEAD --path kb/concepts --expect-body-change
|
||||
```
|
||||
|
||||
**Behaviour**
|
||||
|
||||
- Compares `kb/` against the revision `--from` on the invariants a content migration must not change: wikilink and citation **counts** (not sets), footnote definitions, H1, structural frontmatter, and the **count of generated-region marker pairs**.
|
||||
- Pages are matched by **title**, not path, so a page `move` (or `move --reconcile`) relocated compares as itself - reported separately as `moved` - rather than as a removed-and-added pair.
|
||||
- Reports added and removed pages without failing on them.
|
||||
- `--expect-body-change` additionally flags a page whose body did not change at all.
|
||||
- Not migration-specific: worth running after any bulk rewrite.
|
||||
- Exits 0 whatever it finds unless `--fail-on-error` is passed.
|
||||
- Read-only and exempt from the Iteration Budget Gate.
|
||||
|
||||
**Properties**
|
||||
|
||||
- Changes files: no
|
||||
- Idempotent: yes
|
||||
- Atomic: Read-only
|
||||
- Counts toward the session call budget: no
|
||||
- Can reach the network: no
|
||||
|
||||
**Exit codes**
|
||||
|
||||
- `0` - success
|
||||
- `1` - Only with `--fail-on-error`: an invariant changed
|
||||
- `1` - `--from` is not a revision in this repository
|
||||
|
||||
**See also**
|
||||
|
||||
- `instructions/migrate-corpus.md` - where a migration runs this
|
||||
- `wikitool lint` - the single-revision checks
|
||||
|
||||
## `migrate done`
|
||||
|
||||
Record one migration as applied, advancing `kb_version` in `.wikitool-kb.json`.
|
||||
|
||||
**Synopsis**
|
||||
|
||||
- `wikitool migrate done <version> [--pages N] [--dry-run]`
|
||||
|
||||
**Options**
|
||||
|
||||
```text
|
||||
Arguments:
|
||||
version The migration's target version, e.g. 1.4.0 [required]
|
||||
|
||||
Options:
|
||||
--pages <int> How many pages it touched
|
||||
--dry-run Report without writing
|
||||
-h, --help Show this message and exit.
|
||||
```
|
||||
|
||||
**Examples**
|
||||
|
||||
```bash
|
||||
tools/wikitool migrate done 7.0.0 --pages 42 --dry-run
|
||||
tools/wikitool migrate done 7.0.0 --pages 42
|
||||
```
|
||||
|
||||
**Behaviour**
|
||||
|
||||
- Records one migration as applied, advancing `kb_version` in `.wikitool-kb.json` to its target.
|
||||
- **Refuses any required version that is not the next link in the chain.**
|
||||
- An `offered` migration is recorded in the applied ledger *without* moving `kb_version` and with no ordering rule applied. Re-recording one already in the ledger is a no-op, not an error - idempotent and safe to repeat.
|
||||
- Not idempotent for a required migration: it advances the chain.
|
||||
- `--dry-run` reports without writing.
|
||||
|
||||
**Properties**
|
||||
|
||||
- Changes files: yes
|
||||
- Idempotent: no
|
||||
- Atomic: Yes - single file write
|
||||
- Counts toward the session call budget: yes
|
||||
- Can reach the network: no
|
||||
|
||||
**Exit codes**
|
||||
|
||||
- `0` - success
|
||||
- `1` - Unknown version, no `.wikitool-kb.json`, or nothing outstanding
|
||||
- `1` - A *required* version that is not the next link in the chain
|
||||
|
||||
**See also**
|
||||
|
||||
- `wikitool migrate status` - the order to apply them in
|
||||
- `instructions/migrate-corpus.md` - the migration procedure
|
||||
|
||||
## `migrate baseline`
|
||||
|
||||
Declare `kb_version` once, for an instance predating `.wikitool-kb.json`.
|
||||
|
||||
**Synopsis**
|
||||
|
||||
- `wikitool migrate baseline <version> [--force]`
|
||||
|
||||
**Options**
|
||||
|
||||
```text
|
||||
Arguments:
|
||||
version The shape this instance's content is already in [required]
|
||||
|
||||
Options:
|
||||
--force Overwrite an existing declaration (not a substitute for `done`)
|
||||
-h, --help Show this message and exit.
|
||||
```
|
||||
|
||||
**Examples**
|
||||
|
||||
```bash
|
||||
tools/wikitool migrate baseline 6.2.0
|
||||
```
|
||||
|
||||
**Behaviour**
|
||||
|
||||
- Declares `kb_version` once, for an instance predating `.wikitool-kb.json`.
|
||||
- Refuses to overwrite an existing declaration without `--force`. Advancing the version after a migration is `migrate done`, which checks the chain; this command does not.
|
||||
- Safe to re-run with the same version.
|
||||
|
||||
**Properties**
|
||||
|
||||
- Changes files: yes
|
||||
- Idempotent: yes
|
||||
- Atomic: Yes - single file write
|
||||
- Counts toward the session call budget: yes
|
||||
- Can reach the network: no
|
||||
|
||||
**Exit codes**
|
||||
|
||||
- `0` - success
|
||||
- `1` - Unparseable version
|
||||
- `1` - A declaration already exists and `--force` was not passed
|
||||
|
||||
**See also**
|
||||
|
||||
- `wikitool migrate done` - advances the version after a migration
|
||||
- `wikitool migrate status` - what is owed from the declared version
|
||||
<!-- /wikitool:reference-commands -->
|
||||
Reference in new issue
Block a user