chemenu/tools/CONTRACT.md

# tools/ - Compiler Contract

`wikitool` is a deterministic CLI for Chemenu, used by agents (and humans) so
mechanical wiki operations - frontmatter, index statistics, cross-references, log
formatting, git publishing - never have to be re-derived by
an LLM. The root [`AGENTS.md`](../AGENTS.md) holds the invariants that say when
using these commands is mandatory; this file is the full reference. Changes to
`wikitool` itself are tracked in the repo root [`CHANGES.md`](../CHANGES.md),
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:

```bash
tools/wikitool raw accept -h        # the full record, for one command
tools/wikitool -h | grep '^raw accept'   # the index line, for a cross-command question
grep -n '^#### `raw accept`' tools/CONTRACT.md   # this file's own copy, generated
```

The § Commands section below is `wikitool docs contract`'s output: an index
(one line per command, `grep`-stable) followed by each `###` group's commands
as `#### <path>` records, in the same order `wikitool -h` prints. Reading the
file end to end is for changing the CLI itself.

<!-- wikitool:toc -->
## Contents

- [Setup (one time)](#setup-one-time)
- [Usage](#usage)
- [Commands](#commands)
  - [Pages](#pages)
  - [Links and citations](#links-and-citations)
  - [Catalog and log](#catalog-and-log)
  - [Finding and checking](#finding-and-checking)
  - [Provenance](#provenance)
  - [Raw material and uploads](#raw-material-and-uploads)
  - [Git](#git)
  - [Workshop runs and session budget](#workshop-runs-and-session-budget)
  - [Types, instructions and docs](#types-instructions-and-docs)
  - [Telemetry](#telemetry)
  - [Distribution and versioning](#distribution-and-versioning)
  - [Content migrations](#content-migrations)
  - [Private instances](#private-instances)
  - [Instance health](#instance-health)
- [Design notes](#design-notes)
- [Tests](#tests)
- [Maintenance schedule](#maintenance-schedule)
- [Future considerations (not implemented)](#future-considerations-not-implemented)
<!-- /wikitool:toc -->

## Setup (one time)

Full bootstrap for a fresh clone - including publishing the skills, which are not
committed - is [`instructions/bootstrap.md`](../instructions/bootstrap.md). The
environment alone:

```bash
cd tools
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

## Usage

Run from the repo root:

```bash
tools/wikitool <command> -h
```

`-h` and `--help` are identical and TTY-independent - the same plain, unframed text either
way, for a human or an agent. Bare `tools/wikitool -h` prints the index below plus a pointer back
to this form.

## Commands

<!-- wikitool:commands -->
```
new                   write non-idempotent budget:counted              exit:0,1,42 Scaffold a new wiki page of any type.
task new              write non-idempotent budget:counted              exit:0,1    Create one open item in the configured task tracker - never a kb/ page.
task list             read  idempotent     budget:counted              exit:0,1    List a project's open items - id, title, and whether each carries the WAITING status.
task close            write idempotent     budget:counted              exit:0,1    Mark one tracker item done - never delete it.
touch                 write idempotent     budget:counted              exit:0,1    Bump a page's `modified:` date and optionally rewrite its other frontmatter fields.
rename                write idempotent     budget:counted              exit:0,1    Rename a page, or repoint references that name a page that never existed.
rm                    write non-idempotent budget:counted              exit:0,1    Delete a page and mechanically de-link it from the rest of the wiki.
move                  write idempotent     budget:counted              exit:0,1    Move a page (or every misplaced page) to the directory its type-spec computes.
xref add              write idempotent     budget:counted              exit:0,1    Declare that A <rel> B.
xref remove           write idempotent     budget:counted              exit:0,1    Remove a cross-reference: the inverse of `xref add`.
xref link-source      write idempotent     budget:counted              exit:0,1    Batch-link a source page to every entity/concept it mentions.
links show            read  idempotent     budget:exempt               exit:0,1    Show the edges out of and into a page.
cite id               read  idempotent     budget:exempt               exit:0      Print the deterministic footnote id `cite add` would use for this (title, file) pair.
cite add              write idempotent     budget:counted              exit:0,1    Upsert a `[^cite-id]: [[Source - X]]` definition in a page's footnotes region.
cite sync             write idempotent     budget:counted              exit:0,1    Reconcile each page's footnotes region against its actual `[^id]` references.
index rebuild         write idempotent     budget:counted              exit:0,1    Regenerate the catalog from every page's frontmatter.
log append            write non-idempotent budget:counted              exit:0,1    Append a formatted entry to `kb/log.md`.
log status            read  idempotent     budget:counted              exit:0      Read-only: count `ingest` entries logged since the last `lint` entry.
lint                  write idempotent     budget:counted              exit:0,1    Run structural lint checks against kb/.
search                read  idempotent     budget:exempt               exit:0,1    Find pages in `kb/` by text and/or frontmatter.
review                read  idempotent     budget:exempt               exit:0,1    The GTD weekly review.
sources coverage      read  idempotent     budget:counted              exit:0      List raw files with no source page, broken `raw_files:` references, and legacy directory/URL-only source pages.
sources trace         read  idempotent     budget:counted              exit:0,1    Trace provenance in either direction: raw file, or page.
sources rebuild-index write idempotent     budget:counted              exit:0,1    Regenerate the `kb/provenance.md` reverse index.
raw accept            write non-idempotent budget:counted              exit:0,1    Promote one or more files from `incoming/` into `raw/`.
upload list           read  idempotent     budget:counted              exit:0      List every MCP submission currently waiting in the quarantine (`mcp-upload/`).
upload show           read  idempotent     budget:counted              exit:0,1    Print one submission's manifest in full.
upload accept         write non-idempotent budget:counted              exit:0,1,42 **Upload Review Gate:** promote a submission's file from quarantine into `incoming/`.
upload reject         write non-idempotent budget:counted              exit:0,1    Delete a submission's material, keeping only its ledger trail.
sync                  write idempotent     budget:counted              exit:0,1,42 Fetch `<remote>/<branch>` and bring the local branch up to date with it.
publish               write non-idempotent budget:counted              exit:0,1,42 Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.
work new              write non-idempotent budget:counted              exit:0,1    Scaffold `work/<runkey>/` for one workshop run.
work close            write non-idempotent budget:counted              exit:0,1    Delete a finished workshop.
budget status         read  idempotent     budget:exempt               exit:0      Show the current session's `wikitool` call count and recent command history.
budget reset          write non-idempotent budget:counted              exit:0,1    Clear the current session's (or every session's) iteration budget state.
types list            read  idempotent     budget:counted              exit:0      List every type-spec under `types/`.
types describe        read  idempotent     budget:counted              exit:0,1    Print one type's full contract.
instructions sync     write idempotent     budget:counted              exit:0,1    Publish every `instructions/<name>/SKILL.md` into the harness skill directories.
instructions verify   read  idempotent     budget:counted              exit:0,1    Check the instruction layer.
instructions list     read  idempotent     budget:counted              exit:0      List the flat instructions with their descriptions.
docs verify           read  idempotent     budget:counted              exit:0,1    Check the docs that mirror the code.
docs toc              write idempotent     budget:counted              exit:0      Create, refresh or remove the generated table-of-contents region.
docs contract         write idempotent     budget:counted              exit:0      Regenerate `tools/CONTRACT.md`'s `<!-- wikitool:commands -->` region.
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.
dist upgrade          write non-idempotent budget:counted              exit:0,1    Apply a stack update `dist export` produced - the write half of `version check`.
version show          read  idempotent     budget:exempt               exit:0,1    Print this instance's stack version and where it came from.
version check         read  idempotent     budget:exempt               exit:0,1    Ask the origin's release feed whether a newer stack exists.
version notes         read  idempotent     budget:exempt               exit:0,1    Print one version's release notes.
version bump          write non-idempotent budget:counted              exit:0,1    Raise or continue the one running candidate between two releases.
version regrade       write non-idempotent budget:exempt_without_args  exit:0,1    List the running candidate's bump titles with their impact grade, or change one or more of them.
version release       write non-idempotent budget:counted              exit:0,1    Fix the running candidate: strip `VERSION`'s `-beta.N` suffix and close its `CHANGES.md` entry.
migrate list          read  idempotent     budget:exempt               exit:0      List every migration document under `instructions/migrations/`.
migrate status        read  idempotent     budget:exempt               exit:0,1    Show the migrations this instance still owes, in the order they must run.
migrate verify        read  idempotent     budget:exempt               exit:0,1    Compare `kb/` against a git revision on the invariants a content migration must not change.
migrate done          write non-idempotent budget:counted              exit:0,1    Record one migration as applied, advancing `kb_version` in `.wikitool-kb.json`.
migrate baseline      write idempotent     budget:counted              exit:0,1    Declare `kb_version` once, for an instance predating `.wikitool-kb.json`.
upstream merge        write non-idempotent budget:counted              exit:0,1    Take a stack update into a private instance's branch, machinery only.
upstream verify       read  idempotent     budget:exempt               exit:0,1    Compare two revisions: did anything under a content stage change except through a stack-owned path?
doctor                read  idempotent     budget:exempt               exit:0,1    Check that this instance is correctly configured.
```

### Pages

#### `new`

Scaffold a new wiki page of any type.

**SYNOPSIS**

- `wikitool new <type-name> --name "<Name>" [--type <path>] [--set field=value ...]` - Any type; its type-spec decides fields, directory, title prefix and template.
- `wikitool new entity --name "<Name>" --set entity_type=<t> [--set tags=a,b] [--set related=X,Y] [--set sources="Source - Z"] [--set provenance=sourced|general|mixed]` - Writes `kb/entities/<subdir>/<Name>.md`
- `wikitool new concept --name "<Name>" --set concept_type=<t> ...` - Writes `kb/concepts/<Name>.md`
- `wikitool new source --name "<Name>" --set raw_files=raw/notes/x.md,raw/notes/y.md [--set source_url=<URL>] [--set entities=A,B] [--set concepts=C,D]` - Writes `kb/sources/Source - <Name>.md` (prefix added automatically) with a `raw_files:` list; rejects paths that don't exist
- `wikitool new comparison --name "X vs Y" --set entities=X,Y` - Writes `kb/comparisons/X vs Y.md`
- `wikitool new project --name "<Name>" --set responsibility=<bereich> [--resume]` - Writes `kb/gtd/<bereich>/<Name>.md` and, with a task tracker configured, a same-named tracker project

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: `new <type>`: Yes - single file write. `new project`: **No** for the tracker-configured case - a tracker-project write (or its human-clearance request) happens before the kb/ page write, so a failure between the two leaves a tracker project with no page (a state `review`'s check 3 already reports), never a page with no tracker project. Still a single file write when no tracker is configured
- budget: counted
- network: no
- gates: human-intervention-required (`new project` only)

**EXAMPLES**

- `tools/wikitool new entity --name "Docker" --set entity_type=tool --set tags=containers`
- `tools/wikitool new source --name "Docker Cheatsheet" --set raw_files=raw/2026/09/docker-cheatsheet.md --set fidelity=verbatim --set authority=reporting`
- `tools/wikitool new project --name "Homelab migration" --set responsibility=infrastruktur --resume    # re-run after exit 42, once the user created the tracker project`

**EXIT STATUS**

- 0    success
- 1    A page with this title already exists, the type is unknown, or a `--set` value is invalid
- 1    A `raw_files` path does not exist
- 1    A capture field the type-spec requires is missing, or set to `unknown`
- 1    `--resume` with a type other than `project`
- 1    new project: The name is already taken in the tracker (case-insensitively; for `caldav` against every list in the account)
- 1    new project: The configured access path has no write path (Super Productivity's `access: "snapshot"`)
- 1    new project: The page write failed after the tracker project was confirmed to exist
- 42   new project: The provider cannot create the project itself (Super Productivity's `access: "api"`); the output says what a human has to create

**ON FAILURE**

- A page with this title already exists, the type is unknown, or a `--set` value is invalid -> Not transient - fix the argument and retry once
- A `raw_files` path does not exist -> Not transient - fix the path and retry once
- A capture field the type-spec requires is missing, or set to `unknown` -> Pass it explicitly (e.g. `--set fidelity=verbatim --set authority=reporting`), then retry once
- `--resume` with a type other than `project` -> Drop `--resume` and retry once
- new project: The name is already taken in the tracker (case-insensitively; for `caldav` against every list in the account) -> Not transient - choose another name. If an earlier run of this exact command asked a human to create the project and they did, re-run with `--resume`
- new project: The configured access path has no write path (Super Productivity's `access: "snapshot"`) -> Not transient - point at the `access: "api"` instance the error names. A `--resume` retry refuses the same way, since nothing about the config changes by asking again
- new project: The page write failed after the tracker project was confirmed to exist -> Fix the write error, then re-run with `--resume` - a plain re-run is refused as a tracker collision
- new project: The provider cannot create the project itself (Super Productivity's `access: "api"`); the output says what a human has to create -> Show the user the command's full output verbatim and stop. Once they have created the project, re-run the same command with `--resume`; it re-verifies and exits 42 again, unchanged, if the tracker still does not have it

**NEVER**

- Never hand-craft the page, or its frontmatter, instead.

**NOTES**

- The type-spec drives everything: fields, directory (`base_dir`/`layout`), title prefix, and template. `types list`/`types describe` show what a type requires.
- A schema `default:` is materialized only for a field the schema also lists in `required:`.
- `--set` is repeatable, and comma-separated values fill array fields. An element that itself contains a comma is written `\,`, or passed as its own repeated `--set` for that field - repeating an array field appends.
- A capture field the type-spec requires (a source's `fidelity`/`authority`) must be passed with `--set`; `new` never guesses it and refuses `unknown` for it.
- Produces structurally correct frontmatter and a body skeleton only - the prose (Description, Summary, judgment calls about relationships) is written afterwards.
- `new project`: with `.wikitool-tasks.json` configuring a task tracker, also makes sure a same-named tracker project exists - one name, one identity. No tracker configured is a legitimate, explicitly announced state: page only.
- `new project`: tracker before page. The tracker side is settled first, so a failure past that point leaves a tracker project with no page - a state `review`'s check 3 reports - never a page with no tracker project.
- `new project`: a name already taken, case-insensitively, in `kb/` or the tracker is refused outright, naming where it was found, and creates nothing. For `caldav` the tracker check covers every list in the account, not only the ones counted as projects.
- `new project`: a provider whose configured access path has no write path (Super Productivity's `access: "snapshot"`) refuses entirely with exit 1, naming the `access: "api"` instance to use instead - neither the tracker project nor the page is created, and `--resume` behaves the same.
- `new project`: a provider that could write but has no project-creation call of its own (Super Productivity's `access: "api"` - `GET /projects` exists, `POST /projects` does not) prints instructions for a human and exits 42, creating nothing. That is not one of the named gates, but the same exit code and the same handling. `caldav` never does this: `MKCALENDAR` creates the list, so a valid, non-colliding name always creates it.
- `--resume` is how a later run tells the command a human has done what that message asked: it re-verifies through the tracker's read path before continuing to page creation, rather than trusting the claim, and exits 42 again if the tracker still does not have the project. `--resume` on any other type is refused.

**SEE ALSO**

- `wikitool types describe <type>` - what a type requires and where it lands
- `wikitool touch` - changes a page's own frontmatter afterwards
- `wikitool task new` - a tracker item without a page
- `docs/knowledge-and-commitment.md` - why a project is a page and a tracker project

#### `task new`

Create one open item in the configured task tracker - never a kb/ page.

**SYNOPSIS**

- `wikitool task new --title "<Title>" (--project "<Name>" | --inbox) [--waiting [--follow-up-at YYYY-MM-DD]] [--notes "..."]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: Yes - a single API call, made only once every precondition (the project's own id, the WAITING tag's own id) is confirmed to exist, so a missing one never leaves a half-written item behind
- budget: counted
- network: yes

**EXAMPLES**

- `tools/wikitool task new --title "Renew the TLS certificate" --project "Homelab migration"`
- `tools/wikitool task new --title "Quote from the electrician" --project "Homelab migration" --waiting --follow-up-at 2026-10-05`
- `tools/wikitool task new --title "Read the qmd README" --inbox --notes "from [[Source - qmd - GitHub Repository]]"`

**EXIT STATUS**

- 0    success
- 1    No `.wikitool-tasks.json` - no tracker configured
- 1    Neither or both of `--project`/`--inbox`, or a `--follow-up-at` without `--waiting` or not `YYYY-MM-DD`
- 1    A `--project` name matching no tracker project
- 1    `--waiting` against a provider with no way to represent it right now (Super Productivity: the `waiting` tag does not exist)
- 1    A read-only access path (Super Productivity's `access: "snapshot"`)

**ON FAILURE**

- No `.wikitool-tasks.json` - no tracker configured -> Not transient - configure a tracker first
- Neither or both of `--project`/`--inbox`, or a `--follow-up-at` without `--waiting` or not `YYYY-MM-DD` -> Fix the argument and retry once
- A `--project` name matching no tracker project -> Create the tracker project first, or fix the name, then retry once
- `--waiting` against a provider with no way to represent it right now (Super Productivity: the `waiting` tag does not exist) -> Create the tag in the tracker first, then retry once
- A read-only access path (Super Productivity's `access: "snapshot"`) -> Point at the `access: "api"` instance the error names, then retry once

**NEVER**

- Never fall back to `--inbox`, or to another project, when `--project` does not match.

**NOTES**

- Creates one open item in the configured task tracker; never touches `kb/`.
- Exactly one of `--project` or `--inbox` is required; an omitted `--project` refuses rather than silently falling into the inbox.
- `--project` names an existing tracker project, matched case-insensitively - never created, and never searched or guessed.
- `--inbox` files into the tracker's own inbox. An item filed there never appears in `review`, since every one of its checks reaches items through a project name.
- `--waiting` sets the WAITING status `review`'s waiting-overdue check reads. `--follow-up-at` is refused without `--waiting` - it is never a due date on its own.
- `--notes` carries a freetext backref (e.g. to the `kb/` source page the item came from), stored verbatim, never parsed.
- No `.wikitool-tasks.json` fails immediately with a "no tracker configured" message.
- A provider whose configured access path has no write path (Super Productivity's `access: "snapshot"`) refuses entirely with exit 1, naming the `access: "api"` instance to use instead.
- **Never exits 42.** A `--project` matching no tracker project, or `--waiting` against a provider that cannot represent it right now (Super Productivity: the `waiting` tag does not exist yet, and its API cannot create tags), are ordinary exit-1 refusals that create nothing.
- Not idempotent: every successful run creates another item.

**SEE ALSO**

- `wikitool task list` - a project's open items and their ids
- `wikitool task close` - marks an item done
- `wikitool new project` - a project page and its tracker project
- `docs/knowledge-and-commitment.md` - why commitments live in the tracker, not in `kb/`

#### `task list`

List a project's open items - id, title, and whether each carries the WAITING status.

**SYNOPSIS**

- `wikitool task list --project "<Name>"`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Yes - read-only, nothing to leave half-written
- budget: counted
- network: yes

**EXAMPLES**

- `tools/wikitool task list --project "Homelab migration"`

**EXIT STATUS**

- 0    success
- 0    A `--project` matching no tracker project - prints "No open items", not an error
- 1    No `.wikitool-tasks.json` - no tracker configured

**ON FAILURE**

- No `.wikitool-tasks.json` - no tracker configured -> Not transient - configure a tracker first, then retry once

**NOTES**

- Lists one tracker project's open items: id, title, and whether each carries the WAITING status.
- The id source `task close` and `review`'s `waiting_overdue`/`someday_stale` findings need, without running `review` first.
- Works on every access path a provider offers, read-only ones included.
- A `--project` matching no tracker project prints "No open items": the tracker read does not distinguish an empty project from an unknown one.
- Read-only.

**SEE ALSO**

- `wikitool task close` - closes an item by the id listed here
- `wikitool review` - the findings that name items

#### `task close`

Mark one tracker item done - never delete it.

**SYNOPSIS**

- `wikitool task close --id <item-id>`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: Yes - a single API call; an unknown id is rejected by the provider itself (Super Productivity: `404 TASK_NOT_FOUND`) before anything is written
- budget: counted
- network: yes

**EXAMPLES**

- `tools/wikitool task close --id <item-id>`

**EXIT STATUS**

- 0    success
- 1    No `.wikitool-tasks.json` - no tracker configured
- 1    An `--id` matching no tracker item right now
- 1    A read-only access path (Super Productivity's `access: "snapshot"`)

**ON FAILURE**

- No `.wikitool-tasks.json` - no tracker configured -> Not transient - configure a tracker first
- An `--id` matching no tracker item right now -> Get a current id from `task list` or `review`, then retry once
- A read-only access path (Super Productivity's `access: "snapshot"`) -> Point at the `access: "api"` instance the error names, then retry once

**NEVER**

- Never pass a title as `--id`.

**NOTES**

- Marks one tracker item done. It never deletes or moves an item - the only closing write this stack makes.
- `--id` is the provider's own item id, from `task list` or a `review` finding - never a title.
- No `.wikitool-tasks.json` fails with a "no tracker configured" message.
- A provider whose configured access path has no write path (Super Productivity's `access: "snapshot"`) refuses entirely with exit 1, naming the `access: "api"` instance to use instead.
- **Never exits 42.**

**SEE ALSO**

- `wikitool task list` - where the id comes from
- `wikitool review` - findings that carry item ids

#### `touch`

Bump a page's `modified:` date and optionally rewrite its other frontmatter fields.

**SYNOPSIS**

- `wikitool touch --page "<Title>" [--summary "..."] [--provenance <v>] [--date YYYY-MM-DD] [--set field=value ...] [--add field=value ...] [--remove field=value ...] [--no-date] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: Yes - single file write, and every refusal happens before it
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool touch --page "Docker" --summary "Container runtime and image format"`
- `tools/wikitool touch --page "Docker" --add tags=containers --no-date`
- `tools/wikitool touch --page "Source - Docker Cheatsheet" --date 2026-09-01 --dry-run`

**EXIT STATUS**

- 0    success
- 1    Page not found
- 1    An invalid value for a field it writes, or a `raw_files:` path that doesn't exist
- 1    A field owned by another command (`type:`, a page-ref array) or absent from the type's schema
- 1    `--add`/`--remove` on a non-array field

**ON FAILURE**

- Page not found -> Fix the title and retry once
- An invalid value for a field it writes, or a `raw_files:` path that doesn't exist -> Fix the argument and retry once
- A field owned by another command (`type:`, a page-ref array) or absent from the type's schema -> Use the command the error names, or a field from the list it prints
- `--add`/`--remove` on a non-array field -> Use `--set` for a scalar field, then retry once

**NEVER**

- Never edit `type:` or a page-ref array (`related:`/`sources:`/`entities:`/`concepts:`) by hand - `type:` changes go through the page-lifecycle procedure, page-ref arrays through `xref`.

**NOTES**

- Bumps `modified:` to today and optionally rewrites any other field the page's type declares.
- `--summary`/`--provenance` are shorthands; `--set` reaches every other field and **replaces** its value, while `--add`/`--remove` change single elements of an array field (removing an absent element succeeds and says so).
- Repeating `--set` for one array field appends *within the call*, and `\,` is a literal comma.
- Refused, naming the command that owns them instead: `type:` (the page-lifecycle procedure) and the page-ref arrays `related:`/`sources:`/`entities:`/`concepts:` (`xref`). Everything else the schema declares is settable, and an unknown field is refused with the list of fields the page actually has.
- Schema-validates the fields it writes; `raw_files:` entries must exist on disk.
- A source page declares `date:` instead of `modified:`: the *publication* date of the raw material. It is never bumped to today and changes only when `--date` names a value explicitly.
- `--no-date` changes only the given fields and leaves the date alone; `--dry-run` previews the new frontmatter without writing.
- Safe to re-run as-is: `--set` and `--add` are idempotent, and `--remove` of an already-absent element succeeds while reporting it.

**SEE ALSO**

- `wikitool xref add` / `wikitool xref remove` - the page-ref arrays
- `instructions/page-lifecycle.md` - changing a page's `type:`

#### `rename`

Rename a page, or repoint references that name a page that never existed.

**SYNOPSIS**

- `wikitool rename --from "<Old>" --to "<New>" [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - one write per referencing page, then the file move
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool rename --from "act_runner" --to "Act Runner" --dry-run`
- `tools/wikitool rename --from "Docker Engine" --to "Docker"`

**EXIT STATUS**

- 0    success
- 1    `--from` equals `--to`
- 1    Neither `--from` nor `--to` is a page
- 1    The `--to` title is already taken
- 1    A page write failed partway; nothing was renamed on disk

**ON FAILURE**

- `--from` equals `--to` -> Fix the arguments and retry once
- Neither `--from` nor `--to` is a page -> Create the page first with `wikitool new`, or drop the reference with `wikitool xref remove`
- The `--to` title is already taken -> Choose another title and retry once
- A page write failed partway; nothing was renamed on disk -> Check `git status`, resolve the write failure (permissions/disk), then re-run the full command - safe, since each page's rewrite is idempotent

**NEVER**

- Never fix up references by hand instead.

**NOTES**

- Renames a page and repoints every reference to it: body `[[wikilinks]]` (aliases and anchors preserved), a `[^cite-id]` whose id was derived from the old title (refreshed to match the new one, both in its Footnotes definition and every reference to it), the page's own H1, and every page-ref frontmatter array declared by the type's `page_ref_fields:`.
- If `--from` is *not* a page but is referenced, it instead repoints those references onto the existing `--to` page and moves nothing - the fix for a reference spelled `act_runner` when the page is `Act Runner`.
- Each page's rewrite is idempotent, so a re-run as-is is safe. If a write fails midway, nothing is renamed on disk and the error lists what was updated.
- `--dry-run` lists every page it would change; run it first to see the blast radius.

**SEE ALSO**

- `instructions/page-lifecycle.md` - renaming, moving and deleting a page
- `wikitool move` - changes a page's directory, not its title
- `wikitool rm` - deletes a page

#### `rm`

Delete a page and mechanically de-link it from the rest of the wiki.

**SYNOPSIS**

- `wikitool rm --page "<Title>" [--yes] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: No - one write per referencing page, then the delete
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool rm --page "Old Draft" --dry-run`
- `tools/wikitool rm --page "Old Draft" --yes    # after the user approved the inbound list`

**EXIT STATUS**

- 0    success
- 1    Page not found
- 1    Other pages still reference it and `--yes` was not passed
- 1    A de-link write failed partway; the page was not deleted

**ON FAILURE**

- Page not found -> Fix the title and retry once
- Other pages still reference it and `--yes` was not passed -> Show the user the inbound list, get approval, then re-run with `--yes`
- A de-link write failed partway; the page was not deleted -> Check `git status`, resolve the write failure, then re-run

**NEVER**

- Never pass `--yes` before the user has seen the inbound list and approved it.

**NOTES**

- Deletes a page and de-links it from the rest of the wiki: strips page-ref array entries and bare `- [[Title]]` / `- **label:** [[Title]]` bullets pointing at it.
- Leaves prose references and inline citations in place and reports them afterwards; those are an editorial fix, not a reason to retry.
- Refuses without `--yes` while other pages still reference it, listing them.
- If a de-link write fails midway, the page is not deleted, so nothing is orphaned and a re-run is safe.
- `--dry-run` lists what would change, without writing.
- Not idempotent: once the page is gone, a second run finds nothing to delete.

**SEE ALSO**

- `instructions/page-lifecycle.md` - when a page is deleted rather than renamed
- `wikitool rename` - repoints references instead of removing them

#### `move`

Move a page (or every misplaced page) to the directory its type-spec computes.

**SYNOPSIS**

- `wikitool move --page "<Title>"`
- `wikitool move --reconcile [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: `--page`: yes, a single file move. `--reconcile`: no - one file move per page, each idempotent
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool move --page "Docker"`
- `tools/wikitool move --reconcile --dry-run`
- `tools/wikitool move --reconcile`

**EXIT STATUS**

- 0    success
- 1    Neither or both of `--page`/`--reconcile` given
- 1    The named page is not found, or has no `type:` to compute a placement from
- 1    The destination already exists (a pre-existing duplicate-stem collision) - refused rather than silently skipped
- 1    `--reconcile` failed partway

**ON FAILURE**

- Neither or both of `--page`/`--reconcile` given -> Fix the arguments and retry once
- The named page is not found, or has no `type:` to compute a placement from -> Fix the title, or give the page its `type:`, then retry once
- The destination already exists (a pre-existing duplicate-stem collision) - refused rather than silently skipped -> Resolve the collision, then retry
- `--reconcile` failed partway -> Safe to retry as-is - `--reconcile` only re-moves what is still misplaced

**NEVER**

- Never choose a directory by hand instead.

**NOTES**

- Moves a page to the directory its type-spec computes for its current frontmatter (`base_dir` + `layout`, the same rule `new` places a page by) - never to a hand-chosen destination; there is no `--to <dir>`.
- `--reconcile` applies it corpus-wide: every misplaced page moves in one call, and a second run reports nothing left to do. It fixes `lint`'s `Misplaced Pages` (advisory) and `Nested Pages` (hard) findings.
- Neither mode touches a body or a frontmatter field, and the page's title - its only identity in the wiki - never changes; only the file moves.
- A directory a move empties is removed with it, so a page nested below its area leaves no leftover directory behind.
- A page already at its computed location is reported and left alone, and `--reconcile` only re-moves what is still misplaced, so a re-run is safe.
- `--dry-run` (with `--reconcile`) lists the moves; run it first to see the blast radius.
- Run `wikitool index rebuild` afterwards.

**SEE ALSO**

- `wikitool lint` - reports Misplaced and Nested Pages
- `wikitool index rebuild` - run after moving
- `instructions/page-lifecycle.md` - moving, renaming and deleting a page

### Links and citations

#### `xref add`

Declare that A <rel> B.

**SYNOPSIS**

- `wikitool xref add --a "<A>" --b "<B>" --rel <label> [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - writes A then B, but both edits are idempotent, and both refusals happen before either write
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool xref add --a "Gitea Actions" --b "Act Runner" --rel depends-on`
- `tools/wikitool xref add --a "Gitea Actions" --b "Act Runner" --rel depends-on --dry-run`

**EXIT STATUS**

- 0    success
- 1    Page A or B not found
- 1    A's type declares no `related:` field
- 1    `<label>` is not authorised for this collection pair, or the source collection authorises no labels into the target's collection at all

**ON FAILURE**

- Page A or B not found -> Fix the title and retry once - re-running never duplicates a link
- A's type declares no `related:` field -> For a source page use `xref link-source`; otherwise there is nothing to link from this page
- `<label>` is not authorised for this collection pair, or the source collection authorises no labels into the target's collection at all -> Pick a label from the authorised set the refusal lists, then retry once

**NEVER**

- Never create the missing page just to force the link through.
- Never hand-write a reference field the type does not declare.
- Never edit a collection's `outbound:` block just to get past a label refusal - authorising a further label is a deliberate edit of its own.

**NOTES**

- Declares **one** edge, `A <label> B`: written into A's `related:` as `- <label>: B` and rendered into A's generated links region.
- B is not touched and does not point back - its inbound view is rendered from the graph.
- Idempotent; re-running with a different label *relabels* rather than appending, since one page asserts one thing about another.
- Refuses before writing when A's type does not declare `related:` - a source page declares `entities:`/`concepts:` instead, and the refusal names them and points at `xref link-source`.
- Refuses before writing when `<label>` is not authorised by the source collection's `outbound:` block for the target's collection; the refusal lists the authorised set and points at `instructions/link-taxonomy.md`.
- `--dry-run` reports the edge without writing.

**SEE ALSO**

- `wikitool xref remove` - removes a reference
- `wikitool links show` - the edges out of and into a page
- `instructions/link-taxonomy.md` - the labels and what each asserts

#### `xref remove`

Remove a cross-reference: the inverse of `xref add`.

**SYNOPSIS**

- `wikitool xref remove --a "<A>" --b "<B>" [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - writes A then B, both idempotent
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool xref remove --a "Gitea Actions" --b "act_runner"`
- `tools/wikitool xref remove --a "Gitea Actions" --b "Act Runner" --dry-run`

**EXIT STATUS**

- 0    success
- 1    Page A not found (B is allowed not to exist)

**ON FAILURE**

- Page A not found (B is allowed not to exist) -> Fix the title; safe to retry freely

**NEVER**

- Never hand-edit a page-ref array to remove a reference.

**NOTES**

- Clears the reference in **both** directions: the cleanup command for a deleted or hand-renamed page rather than the strict inverse of a one-directional `xref add`.
- Clears `<B>` from every page-ref frontmatter field `<A>`'s type declares (`related:`, `sources:`, `entities:`, `concepts:`) plus the matching bullets.
- Also sweeps a page-ref field the type does *not* declare but some other type does, and drops that key once empty.
- `--b` need not still exist as a page, so this clears a reference left by a hand-deleted or hand-renamed page without hand-editing frontmatter.
- Idempotent: removing an absent link is a no-op. `--dry-run` reports without writing.

**SEE ALSO**

- `wikitool xref add` - declares an edge
- `wikitool rm` - deletes a page and de-links it

#### `xref link-source`

Batch-link a source page to every entity/concept it mentions.

**SYNOPSIS**

- `wikitool xref link-source --source "Source - X" --entities A,B,C [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - one write per entity plus one for the source page, idempotent per page
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool xref link-source --source "Source - Docker Cheatsheet" --entities Docker,Podman --dry-run`
- `tools/wikitool xref link-source --source "Source - Docker Cheatsheet" --entities Docker,Podman`

**EXIT STATUS**

- 0    success
- 1    Source page not found
- 1    A page in `--entities` does not exist, or a target could not be written; the others were linked
- 1    The source page itself could not be written after its targets were

**ON FAILURE**

- Source page not found -> Fix the title and retry once
- A page in `--entities` does not exist, or a target could not be written; the others were linked -> Fix the named pages and re-run - safe, since every write is idempotent. `sources trace --page "<Title>"` shows who is already linked
- The source page itself could not be written after its targets were -> Fix the write failure and re-run (idempotent)

**NOTES**

- Each target gets the source page in its `sources:`, and the source page records each target in its own `entities:` or `concepts:`. No body bullet is written on either side - `sources:` *is* the record.
- Which field a target lands in follows its collection (`kb/entities/` -> `entities:`), so a new collection needs no code change.
- A target whose collection matches no reference field the source type declares is linked one way and named in the output.
- A target that does not exist is skipped and named; the others are still linked, and the run then exits 1.
- Idempotent in both directions. `--dry-run` reports what would be linked.

**SEE ALSO**

- `wikitool sources trace` - who a source is already linked to
- `wikitool xref add` - one labelled edge between two pages
- `wiki-ingest` skill - where a source is linked after it is written

#### `links show`

Show the edges out of and into a page.

**SYNOPSIS**

- `wikitool links show --page "<Title>" [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool links show --page "Act Runner"`
- `tools/wikitool links show --page "Act Runner" --json`

**EXIT STATUS**

- 0    success
- 1    Page not found

**ON FAILURE**

- Page not found -> Check the exact title with `search`; a wikilink target is not always the page's stem

**NOTES**

- Shows the declared graph around one page in both directions: the edges it asserts (from its own `related:`, with labels) and the edges other pages assert about it.
- The inbound half is computed across the corpus on every call, never stored, so it is complete.
- `--json` prints both halves as JSON.
- Read-only; exempt from the Iteration Budget Gate.

**SEE ALSO**

- `wikitool xref add` / `wikitool xref remove` - change the outbound edges
- `wikitool search` - finds the exact title

#### `cite id`

Print the deterministic footnote id `cite add` would use for this (title, file) pair.

**SYNOPSIS**

- `wikitool cite id --title "Source - X" [--file <qualifier>]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool cite id --title "Source - Docker Cheatsheet"`

**EXIT STATUS**

- 0    success

**NEVER**

- Never paste an id from here into a page by hand - `cite add` writes the definition and prints the marker to paste.

**NOTES**

- Prints the footnote id `cite add` would use for this (title, file) pair.
- A preview only: it does not check that the id is free on any given page.
- Never fails; safe to retry freely. Read-only and exempt from the Iteration Budget Gate.

**SEE ALSO**

- `wikitool cite add` - writes the definition

#### `cite add`

Upsert a `[^cite-id]: [[Source - X]]` definition in a page's footnotes region.

**SYNOPSIS**

- `wikitool cite add --page "<Title>" --source "Source - X" [--file <qualifier>] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: Yes - single file write
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool cite add --page "Docker" --source "Source - Docker Cheatsheet"`
- `tools/wikitool cite add --page "Docker" --source "Source - Docker Cheatsheet" --file part-2`

**EXIT STATUS**

- 0    success
- 1    The page is not found
- 1    The source page is not found - citing it would be a dangling reference

**ON FAILURE**

- The page is not found -> Fix the title and retry once
- The source page is not found - citing it would be a dangling reference -> Fix the source title, or create the source page first, then retry once

**NEVER**

- Never compute or type a `[^cite-id]` or its definition by hand - paste the marker this prints.

**NOTES**

- Upserts a `[^cite-id]: [[Source - X]]` definition in the page's generated footnotes region, creating the region between `<!-- wikitool:footnotes -->` markers if absent.
- Reuses the id when the page already cites this exact source/file pair, so a repeat changes nothing.
- Adds `Source - X` to the page's frontmatter `sources:`.
- Prints the `[^cite-id]` marker; pasting it into the prose is a manual, editorial step.
- `--dry-run` reports without writing.

**SEE ALSO**

- `wikitool cite sync` - prunes and re-orders the region
- `wikitool cite id` - previews an id

#### `cite sync`

Reconcile each page's footnotes region against its actual `[^id]` references.

**SYNOPSIS**

- `wikitool cite sync [--page "<Title>" | --all] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - one write per page, each idempotent
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool cite sync --page "Docker"`
- `tools/wikitool cite sync --all --dry-run`

**EXIT STATUS**

- 0    success
- 1    Neither or both of `--page`/`--all` given, or the page is not found
- 1    A page write failed partway

**ON FAILURE**

- Neither or both of `--page`/`--all` given, or the page is not found -> Fix the arguments and retry once
- A page write failed partway -> Resolve the write failure and re-run - each page's re-render is idempotent

**NOTES**

- Prunes definitions nothing references any more, re-renders the region in first-reference order, and reports every `[^id]` reference left with no definition.
- An undefined-reference report is not a failure: fix the reference, or run `cite add`, and re-run.
- A page still carrying the pre-4.0.0 undelimited footnote block is converted to a marked region in the same pass.
- Each page's re-render is idempotent; safe to retry freely. `--dry-run` reports without writing.

**SEE ALSO**

- `wikitool cite add` - writes a definition

### Catalog and log

#### `index rebuild`

Regenerate the catalog from every page's frontmatter.

**SYNOPSIS**

- `wikitool index rebuild [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - each catalog file (the map plus one shard per collection/area) is rewritten independently, then stale shards are removed; an interruption can leave some regenerated and others not
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool index rebuild`
- `tools/wikitool index rebuild --dry-run`

**EXIT STATUS**

- 0    success
- 1    An I/O error while writing or removing a catalog file (rare)

**ON FAILURE**

- An I/O error while writing or removing a catalog file (rare) -> Safe to retry freely - the plan is always recomputed from the pages currently on disk, so a re-run converges

**NEVER**

- Never hand-edit `kb/index.md` or an `INDEX.md` - re-run this command instead.

**NOTES**

- Rewrites `kb/index.md` as a map: statistics, one row per collection and per area, and links to the shards - no page rows.
- Writes the page tables to a generated `INDEX.md` in each collection. An area with more than 50 rows gets its own `INDEX.md` in its directory.
- Deletes stale shards - an `INDEX.md` of a collection or area that no longer exists - in the same pass.
- Warns about every page nested more than one directory below its collection; it is still catalogued, folded into its area.
- `--dry-run` prints every file it would write and every stale shard it would remove, and writes nothing.

**SEE ALSO**

- `wikitool search` - finds a page without reading the catalog
- `wikitool lint` - its Nested Pages finding is what the warning previews
- `instructions/publish-cycle.md` - where a write session runs this

#### `log append`

Append a formatted entry to `kb/log.md`.

**SYNOPSIS**

- `wikitool log append --op ingest|query|lint|create|update|delete|rename|move --title "..." [--body "..."|--body-file path]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: Yes - single append
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool log append --op ingest --title "raw/articles/docker-cheatsheet.md" --body "Created [[Docker]]; updated [[Container]]."`
- `tools/wikitool log append --op lint --title "2026-09-26" --body-file lint-summary.md`

**EXIT STATUS**

- 0    success
- 1    `--op` is not one of ingest, query, lint, create, update, delete, rename, move
- 1    `--body-file` cannot be read

**ON FAILURE**

- `--op` is not one of ingest, query, lint, create, update, delete, rename, move -> Nothing was written - fix the argument and retry once
- `--body-file` cannot be read -> Nothing was written - fix the path and retry once

**NEVER**

- Never re-run after an uncertain outcome without first checking the tail of `kb/log.md` - a second run appends a second entry.

**NOTES**

- Appends one entry to `kb/log.md`: a `## [YYYY-MM-DD] <op> | <title>` heading, the body if one is given, and a `---` separator.
- Not idempotent: every successful run appends a new entry, including a repeated one.

**SEE ALSO**

- `wikitool log status` - counts the ingests logged since the last lint
- `instructions/publish-cycle.md` - where a write session runs this

#### `log status`

Read-only: count `ingest` entries logged since the last `lint` entry.

**SYNOPSIS**

- `wikitool log status`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool log status`

**EXIT STATUS**

- 0    success
- 0    `kb/log.md` is missing or empty - reported as nothing logged, not a failure

**NOTES**

- Counts the `ingest` entries in `kb/log.md` after the most recent `lint` entry, or since the start of the log if it was never linted, and the total number of entries.
- At 10 or more it prints that the `wiki-lint` skill is due next - the every-10-sources full lint of the Maintenance Schedule.
- Read-only; safe to retry freely.

**SEE ALSO**

- `wikitool log append` - writes the entries this counts
- `wiki-lint` skill - what the threshold asks for
- `tools/CONTRACT.md` § Maintenance schedule - the cadence this reports on

### Finding and checking

#### `lint`

Run structural lint checks against kb/.

**SYNOPSIS**

- `wikitool lint [--json] [--markdown out.md] [--full] [--fail-on-error]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: Writes one report file (single atomic write) unless `--json`
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool lint`
- `tools/wikitool lint --json`
- `tools/wikitool lint --fail-on-error`

**EXIT STATUS**

- 0    success
- 1    Only with `--fail-on-error`: hard findings exist

**ON FAILURE**

- Only with `--fail-on-error`: hard findings exist -> Act on the findings - exit 1 here means "act on the findings", not "the tool is broken". Re-running is safe, but only to re-*measure* after a fix

**NEVER**

- Never re-run just to re-read the findings - the printed path holds the full report.

**NOTES**

- Structural and provenance checks over `kb/`: broken wikilinks, dangling frontmatter references, orphan pages, index drift, schema gaps, duplicate titles, title mismatches, uncovered raw files, broken `raw_files:` refs, raw files claimed by more than one source page, unmarked provenance, citation/frontmatter drift, and unbalanced generated-region markers.
- Pages nested more than one directory below their collection are a hard finding - the generated catalog folds these into their area silently rather than merely reading it.
- Edges whose label is missing or not authorised by the source collection's `outbound:` are both hard once `kb_version` has reached the release that introduced labelled edges, and advisory below it.
- Advisory only: `see-also` edges whose reverse direction already carries a specific label - never migration-gated.
- Advisory only: a collection past the catalog's per-area shard threshold that has no areas to shard, reported with the split its subtype field would produce, and only when that split puts every resulting area at or under the threshold.
- Advisory only: source pages sitting in the `unclassified` catalog slot.
- Advisory only: quote-limit overages (>2 blockquoted lines/page).
- Prints only the sections that found something and always writes the full report to `reports/Lint Report <date>.md` (or `--markdown`), naming the path. `--full` prints everything; `--json` prints the findings and writes nothing.
- Exits 0 whatever it finds unless `--fail-on-error` is passed.

**SEE ALSO**

- `wiki-lint` skill - the procedure that runs this
- `wikitool move --reconcile` - fixes Misplaced and Nested Pages
- `wikitool log status` - whether a full lint is due

#### `search`

Find pages in `kb/` by text and/or frontmatter.

**SYNOPSIS**

- `wikitool search ["<text>"] [--field <predicate> ...] [--kind/--subtype/--collection/--tag <v>] [--regex] [--limit N] [--sort [-]<field>] [--backend <name>] [--matches] [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool search "act runner"`
- `tools/wikitool search --field entity_type=system --field '!sources'`
- `tools/wikitool search "docker" --collection entities --limit 10 --json`

**EXIT STATUS**

- 0    success
- 1    `rg` is not installed
- 1    `rg` did not finish within 30 s
- 1    A malformed `--field` predicate, or an unknown `--backend`
- 1    An unknown field name; the error lists the fields that exist

**ON FAILURE**

- `rg` is not installed -> Not transient - install `rg`, then retry
- `rg` did not finish within 30 s -> A timeout is a pathological pattern or an unresponsive corpus directory, not a slow answer - narrow the query or drop `--regex` rather than retrying it unchanged
- A malformed `--field` predicate, or an unknown `--backend` -> Fix the argument and retry
- An unknown field name; the error lists the fields that exist -> Pick a field from that list and retry

**NEVER**

- Never retry a timed-out query unchanged.
- Never grep `kb/` yourself instead - it can add no page this misses, only the generated files it excludes.

**NOTES**

- Finds pages in `kb/` without reading the catalog. Text search runs through a pluggable backend (`rg` today).
- `--field` predicates are evaluated on frontmatter - `f=v`, `f~substring`, `'f>=v'`, `'f:*'` (present), `'!f'` (absent) - repeatable and ANDed. With no text this is a pure structured query.
- One hit per line, ` | `-separated as `score | kind/subtype | title | path | summary`. **Title and path are never truncated** - the title is the identifier `touch`/`xref`/`cite` take. The summary, the one lossy field and the only one that may contain the separator, goes last, so splitting on `" | "` with `maxsplit=4` is unambiguous.
- Scope is pages: the backend walks `kb/` but drops the kb-root meta files, every `COLLECTION.md` and every generated `INDEX.md` - a hand-run grep over `kb/` can add none of them but those.
- `--limit` defaults to 50 (`0` for no limit), and **a truncated result says so**: `50 of 182 result(s)` in the table, `total`/`truncated`/`limit` beside `count` in `--json`, where `count` stays the number of results in the payload. `api.search` and the MCP `search` tool carry the same default and the same fields.
- A page whose frontmatter does not parse can match no positive predicate, so it is **named** rather than dropped: `--json` always carries an `unreadable` list of `{path, reason}` (usually empty), and the table form writes the same lines to stderr.
- An unknown field name is reported with the list of fields that do exist - never answered with an empty result, which would read as "no such pages".
- `--regex` is applied by `rg` alone, whose engine is linear; the ranking boosts for title and summary are literal-containment only, so a non-literal pattern is ranked by match count.
- `rg` is killed after 30 s and reported as a failure.
- Read-only, and **exempt from the Iteration Budget Gate**.

**SEE ALSO**

- `wikitool links show` - the edges around a page once found
- `wiki-query` skill - answering a question from the wiki

#### `review`

The GTD weekly review.

**SYNOPSIS**

- `wikitool review [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: yes

**EXAMPLES**

- `tools/wikitool review`
- `tools/wikitool review --json`

**EXIT STATUS**

- 0    success
- 1    No `.wikitool-tasks.json`, or a malformed one - a clear "no tracker configured" message
- 1    The provider was reachable at config-parse time but a read call failed mid-run; the full report (findings plus which checks ran) was printed first

**ON FAILURE**

- No `.wikitool-tasks.json`, or a malformed one - a clear "no tracker configured" message -> Not fixed by retrying unchanged - configure or repair `.wikitool-tasks.json` first
- The provider was reachable at config-parse time but a read call failed mid-run; the full report (findings plus which checks ran) was printed first -> Start the unreachable provider (e.g. the tracker app), then retry plainly

**NEVER**

- Never present a report that exited 1 as complete.

**NOTES**

- Joins the configured task-tracker provider against `kb/gtd/` project pages over the case-normalized project name, at read time, storing nothing - not even a `reports/` file.
- **stalled**: a tracker project with zero open items whose `kb/` page is `state: active`; `dormant`/`completed`/`abandoned` never fire.
- **waiting-overdue**: a `WAITING` item whose `follow_up_at` is older than `thresholds.stalled_waiting_days`.
- **unpaged-project**: a tracker project with no matching `kb/` page, older than `thresholds.unpaged_project_weeks`.
- **no-open-loop**: a `kb/` page `state: active` with no matching tracker project, or one with zero open items - the reverse direction of unpaged-project, so a rename on either side surfaces on both.
- **someday-stale**: a someday/maybe item untouched for longer than `thresholds.someday_stale_months`.
- A value a provider genuinely cannot supply - a `WAITING` item with no `follow_up_at`, a tracker project with no determinable creation date - is its own finding (`waiting_no_follow_up`/`project_age_unknown`) rather than a silent skip.
- Thresholds come from `.wikitool-tasks.json`, never from the schema.
- Text output is one `[check] project: message` line per finding, preceded by a `Source:` line naming which access path answered and, for `superproductivity`'s `access: "snapshot"`, the snapshot's age. `--json` carries the same findings plus `checks_run`/`checks_skipped`/`kb_project_count`/`complete`/`source` (`{"kind": ..., "detail": ...}` or `null`).
- A provider that cannot be reached mid-run degrades only the checks that needed the failing call; the report is printed in full, then exit 1 follows - never rendered as if it were complete.
- Re-reads everything fresh on every call, so nothing is ever stale to re-fetch.
- Read-only, and **exempt from the Iteration Budget Gate**.

**SEE ALSO**

- `gtd-weekly-review` skill - turns the findings into decisions
- `wikitool task list` / `wikitool task close` - act on an item
- `wikitool new project` - a project page and its tracker project

### Provenance

#### `sources coverage`

List raw files with no source page, broken `raw_files:` references, and legacy directory/URL-only source pages.

**SYNOPSIS**

- `wikitool sources coverage [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool sources coverage`
- `tools/wikitool sources coverage --json`

**EXIT STATUS**

- 0    success

**NOTES**

- Lists raw files with no source page, broken `raw_files:` references, and legacy directory/URL-only source pages.
- `--json` prints the same lists as JSON.
- Never fails; read-only and safe to retry freely.

**SEE ALSO**

- `wikitool sources trace` - follows one file or page
- `wiki-ingest` skill - turns an uncovered raw file into a source page

#### `sources trace`

Trace provenance in either direction: raw file, or page.

**SYNOPSIS**

- `wikitool sources trace --raw <path> | --page "<Title>"`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool sources trace --page "Docker"`
- `tools/wikitool sources trace --raw "raw/articles/llm-wiki.md"`

**EXIT STATUS**

- 0    success
- 1    Neither or both of `--raw`/`--page` given, or `--page` names an unknown page
- 1    `--raw` names a file no source page covers - reported as a plain finding plus exit 1, not the usual `ERROR`-prefixed rejection

**ON FAILURE**

- Neither or both of `--raw`/`--page` given, or `--page` names an unknown page -> Fix the argument and retry
- `--raw` names a file no source page covers - reported as a plain finding plus exit 1, not the usual `ERROR`-prefixed rejection -> Nothing to retry: the file is uncovered. Ingest it, or check the path

**NOTES**

- `--raw <path>`: raw file -> the source page(s) covering it -> the pages citing those.
- `--page "<Title>"`: page -> its sources -> their raw files.
- Read-only.

**SEE ALSO**

- `wikitool sources coverage` - every uncovered raw file at once
- `wikitool xref link-source` - links a source page to what it mentions

#### `sources rebuild-index`

Regenerate the `kb/provenance.md` reverse index.

**SYNOPSIS**

- `wikitool sources rebuild-index [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: Yes - the single provenance file is regenerated from scratch
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool sources rebuild-index`
- `tools/wikitool sources rebuild-index --dry-run`

**EXIT STATUS**

- 0    success
- 1    An I/O error while writing `kb/provenance.md` (rare)

**ON FAILURE**

- An I/O error while writing `kb/provenance.md` (rare) -> Safe to retry freely

**NEVER**

- Never hand-edit `kb/provenance.md` - re-run this command instead.

**NOTES**

- Regenerates the `kb/provenance.md` reverse index (raw file -> source page -> citing pages) from scratch.
- `--dry-run` prints the result instead of writing `kb/provenance.md`.

**SEE ALSO**

- `wikitool index rebuild` - the page catalog, rebuilt alongside
- `instructions/publish-cycle.md` - where a write session runs this

### Raw material and uploads

#### `raw accept`

Promote one or more files from `incoming/` into `raw/`.

**SYNOPSIS**

- `wikitool raw accept <file> [<file> ...] --fidelity <v> --authority <v> [--page "<Title>"] [--dry-run]` - Promote one or more files from `incoming/` into today's `raw/<YYYY>/<MM>/` shard
- `wikitool raw accept <file> --replaces <raw-path> [--fidelity <v>] [--authority <v>] [--dry-run]` - Overwrite one existing raw file in place with a new edition

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: `raw accept`: No - one filesystem move per file, then (with `--page`) one page write. `raw accept --replaces`: No - one `unlink()` + one `rename()`, plus (if `--fidelity`/`--authority` was given) one page write
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool raw accept incoming/docker-cheatsheet.md --fidelity verbatim --authority reporting`
- `tools/wikitool raw accept incoming/part-2.md --fidelity verbatim --authority reporting --page "Source - Docker Cheatsheet"`
- `tools/wikitool raw accept incoming/cluster.md --replaces raw/documents/cluster.md`

**EXIT STATUS**

- 0    success
- 1    raw accept: A file does not exist, is not under `incoming/`, or is nested more than one level below it; two files in one call share a filename; or a target path already exists
- 1    raw accept: `--fidelity`/`--authority` is missing, or names `unknown` or a value outside the schema's enum
- 1    raw accept: The target name is already occupied anywhere under `raw/` by something the call does not own
- 1    raw accept: `--page` names an unknown page or one with no `raw_files:` yet, an existing `raw_files:` entry is missing on disk, a file to be moved has more than one owning page, or `--page` would overwrite an already-set `fidelity`/`authority` with a different value
- 1    raw accept --replaces: More than one incoming file, or `--page` also given
- 1    raw accept --replaces: The incoming file does not exist or is not under `incoming/` (or is nested more than one level below it), its filename differs from the target's, or the target does not lie under `raw/` or does not exist
- 1    raw accept --replaces: `--fidelity`/`--authority` names `unknown` or a value outside the schema's enum, or the target has more than one owning source page

**ON FAILURE**

- raw accept: A file does not exist, is not under `incoming/`, or is nested more than one level below it; two files in one call share a filename; or a target path already exists -> Fix the named argument and retry once
- raw accept: `--fidelity`/`--authority` is missing, or names `unknown` or a value outside the schema's enum -> Pass both with a valid value, then retry once
- raw accept: The target name is already occupied anywhere under `raw/` by something the call does not own -> Not fixed by retrying: the refusal names `--replaces` (same source, new edition) and renaming in `incoming/` (a separate source) as the two routes, and neither is the tool's to pick. Show the message to the user and wait
- raw accept: `--page` names an unknown page or one with no `raw_files:` yet, an existing `raw_files:` entry is missing on disk, a file to be moved has more than one owning page, or `--page` would overwrite an already-set `fidelity`/`authority` with a different value -> Fix the named argument and retry once; a different capture value on an existing page is a new edition - `--replaces`
- raw accept --replaces: More than one incoming file, or `--page` also given -> A replacement is one file for one file - fix the call and retry once
- raw accept --replaces: The incoming file does not exist or is not under `incoming/` (or is nested more than one level below it), its filename differs from the target's, or the target does not lie under `raw/` or does not exist -> Fix the named argument and retry once - every check runs before the filesystem is touched, so both files are exactly as they were
- raw accept --replaces: `--fidelity`/`--authority` names `unknown` or a value outside the schema's enum, or the target has more than one owning source page -> Fix the named argument and retry once; nothing was touched

**NEVER**

- Never choose the destination under `raw/` by hand, and never move a file into `raw/` yourself.
- Never pick between `--replaces` and renaming on your own initiative after a name-occupied refusal - the user tells the two intents apart.

**NOTES**

- Promotes files from `incoming/` into `raw/<YYYY>/<MM>/`, computed from the accept date rather than chosen by hand. A subdirectory under `incoming/` is tolerated and ignored, not inspected - `raw/` does not address by type.
- One file promoted alone lands with no directory of its own; several files in one call nest under `raw/<YYYY>/<MM>/<stem>/`, named after the first file's stem.
- `--fidelity`/`--authority` are required on a plain accept (`types describe source` lists the values); `unknown` is refused - it is backfill-only.
- `--page "<Title>"` additionally extends that existing source page's `raw_files:` in the same call and writes both capture fields onto it - refused if it already carries a different value, since a capture field is fixed once.
- If `--page` raises the page past one file, its already-promoted file is folded into a bundle at *its own* parent directory, not today's shard, so a bundle never mixes an old and a new capture date - after checking that file has no other owner.
- Every name occupied anywhere under `raw/` - file stems and bundle directory names alike, old type directories and date shards together - stays unique: a promote whose target name already belongs to something this call does not itself own is refused, naming `--replaces` and renaming in `incoming/` as the two routes, without recommending either.
- `--replaces <raw-path>` overwrites that file in place with the single incoming file (same filename required), leaves every page's `raw_files:` untouched and writes no `kb/` page; the previous edition survives only in `git log --follow <raw-path>`.
- With `--replaces`, `--fidelity`/`--authority` are optional, and passing one overwrites the owning page's already-set value - the one path the fixed-once rule does not block.
- `--replaces` refuses a target with more than one owning source page; with none, it replaces anyway and says so. It cannot be combined with `--page` or with more than one incoming file.
- `--replaces` prints the source page (if any) and its citing pages, so their update lands in the same commit as the replacement.
- A file already at its computed destination is what "already exists" reports, not a partial prior run to resume - safe to retry as-is once a cause is fixed.
- `--dry-run` reports the moves without making them.

**SEE ALSO**

- `raw/CONTRACT.md` "Getting a file in: incoming/" - the rules and why
- `wikitool types describe source` - the capture field values
- `wikitool new source` - the source page for a promoted file

#### `upload list`

List every MCP submission currently waiting in the quarantine (`mcp-upload/`).

**SYNOPSIS**

- `wikitool upload list [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool upload list`
- `tools/wikitool upload list --json`

**EXIT STATUS**

- 0    success

**NOTES**

- Lists every submission waiting in `mcp-upload/`, oldest id first: id, filename, size, submitter.
- Only ever non-empty when `.wikitool-upload.json` opts the checkout into the MCP server's `submit` tool.
- A submission directory with a corrupt manifest is silently skipped.
- Never fails; read-only and safe to retry freely.

**SEE ALSO**

- `wikitool upload show` - one submission's manifest
- `INSTALL-MCP.md` § "Schritt 7: Optional - den `submit`-Pfad freischalten"

#### `upload show`

Print one submission's manifest in full.

**SYNOPSIS**

- `wikitool upload show <id> [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool upload show <id>`

**EXIT STATUS**

- 0    success
- 1    Unknown or malformed submission id

**ON FAILURE**

- Unknown or malformed submission id -> Fix the id (see `upload list`) and retry

**NOTES**

- Prints one submission's manifest in full: filename, size, sha256, submitter, submitter source (the header name, not a claim the header was honest), submission time.
- What a reviewer reads before `upload accept`.
- Read-only.

**SEE ALSO**

- `wikitool upload accept` - promotes it after review
- `wikitool upload reject` - declines it

#### `upload accept`

**Upload Review Gate:** promote a submission's file from quarantine into `incoming/`.

**SYNOPSIS**

- `wikitool upload accept <id> [--confirm TOKEN]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: No - one filesystem move, one directory delete, one ledger append; the gate check runs first, before any of them
- budget: counted
- network: no
- gates: upload-review

**EXAMPLES**

- `tools/wikitool upload accept <id>`
- `tools/wikitool upload accept <id> --confirm <token>    # re-run after exit 42, once the user approved the manifest`

**EXIT STATUS**

- 0    success
- 1    Unknown or malformed submission id, or the submission's file is missing from `mcp-upload/<id>/`
- 1    `incoming/<filename>` already exists
- 42   Upload Review Gate: `--confirm` is absent or does not match the manifest's current token

**ON FAILURE**

- Unknown or malformed submission id, or the submission's file is missing from `mcp-upload/<id>/` -> Fix the named argument and retry once
- `incoming/<filename>` already exists -> Not fixed by retrying unchanged - rename or clear it first
- Upload Review Gate: `--confirm` is absent or does not match the manifest's current token -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state

**NEVER**

- Never pass a `--confirm` token the user has not seen and approved.

**NOTES**

- Promotes a submission's file from `mcp-upload/<id>/` into `incoming/`, deletes the quarantine directory, and appends an `accepted` event to `mcp-upload/ledger.jsonl`.
- Upload Review Gate: without a matching `--confirm`, exits 42 and prints the manifest in full plus the exact re-run line - one submission at a time. The gate check runs before anything is moved.
- The token digests id, filename, size, sha256 and submitter, so an edited or superseded manifest invalidates it.
- An occupied `incoming/<filename>` is an ordinary validation error, not the gate.

**SEE ALSO**

- `wikitool upload show` - the manifest to review
- `wikitool raw accept` - the next step for the file in `incoming/`
- `instructions/gates.md` - the gate procedure

#### `upload reject`

Delete a submission's material, keeping only its ledger trail.

**SYNOPSIS**

- `wikitool upload reject <id> --reason "<why>"`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: No - one ledger append, then one recursive delete; the ledger write happens first, so an interruption still leaves the reason on record
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool upload reject <id> --reason "duplicate of raw/articles/llm-wiki.md"`

**EXIT STATUS**

- 0    success
- 1    Unknown or malformed submission id, or an empty `--reason`

**ON FAILURE**

- Unknown or malformed submission id, or an empty `--reason` -> Fix the argument and retry once. After a first successful call, "unknown id" is confirmation, not a failure

**NOTES**

- Appends an append-only `rejected` event naming the reason and the sha256 of what was declined, then deletes the submission's material.
- The ledger write happens first, so an interruption still leaves the reason on record.
- No gate - rejecting needs no clearance, only accepting does.
- Not idempotent: a second call with the same id reports "unknown id", which confirms the first call worked.

**SEE ALSO**

- `wikitool upload show` - the manifest to review

### Git

#### `sync`

Fetch `<remote>/<branch>` and bring the local branch up to date with it.

**SYNOPSIS**

- `wikitool sync [--remote origin] [--branch main] [--confirm-rebase TOKEN]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - fetch, then at most one merge/rebase attempt, aborted cleanly on failure
- budget: counted
- network: no
- gates: rebase-review

**EXAMPLES**

- `tools/wikitool sync`
- `tools/wikitool sync --confirm-rebase <token>    # re-run after exit 42, once the user approved`

**EXIT STATUS**

- 0    success
- 0    No remote configured, or the remote cannot be reached - reported and skipped, not a failure
- 1    The automatic rebase hit a real conflict (git failed); it is aborted cleanly
- 42   Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff

**ON FAILURE**

- The automatic rebase hit a real conflict (git failed); it is aborted cleanly -> Do not retry and do not force - resolve the conflict manually, then re-run
- Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm-rebase <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state

**NEVER**

- Never retry a conflict unchanged, and never force past it.
- Never pass a `--confirm-rebase` token the user has not seen and approved.

**NOTES**

- Fetches `<remote>/<branch>`, then: fast-forwards when only the remote moved; rebases the local commits on top when both sides moved but touched disjoint files; exits 42 (rebase-review gate) when both sides touched the same file.
- A refused call performs no rebase attempt and leaves the branch where it was.
- The `--confirm-rebase` token covers the exact upstream state and the set of files touched on both sides; either one moving makes it stale.
- Makes no commit, no push, and no forced operation of any kind.
- Run it once at the start of a writing session.

**SEE ALSO**

- `wikitool publish` - runs the same reconcile before it commits and pushes
- `instructions/session-setup.md` - where a session runs `sync`
- `instructions/gates.md` - the gate procedure

#### `publish`

Reconcile with `<remote>/<branch>`, then stage all changes, commit, and push.

**SYNOPSIS**

- `wikitool publish --message "<op>: <desc>" [--no-push] [--confirm TOKEN] [--confirm-rebase TOKEN] [--threshold N] [--remote origin] [--branch main] [--path P ...]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: No - sequential git operations, but every gate runs before staging
- budget: counted
- network: no
- gates: mass-update, publish-remote, rebase-review

**EXAMPLES**

- `tools/wikitool publish --message "ingest: docker-cheatsheet"`
- `tools/wikitool publish --confirm <token> --message "ingest: docker-cheatsheet"    # re-run after a Mass-Update exit 42, once the user approved`
- `tools/wikitool publish --confirm-rebase <token> --message "ingest: docker-cheatsheet"    # re-run after a rebase-review exit 42, once the user approved`

**EXIT STATUS**

- 0    success
- 1    git failed - `git add`, `git commit`, `git push`, or the reconcile's automatic rebase
- 1    The push target (`--branch`) is not the checked-out branch, or HEAD is detached; the unborn branch of a fresh `git init` is not this case
- 1    `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error
- 1    `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list
- 42   Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset
- 42   Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff
- 42   Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL

**ON FAILURE**

- git failed - `git add`, `git commit`, `git push`, or the reconcile's automatic rebase -> Do not retry and do not force - report and ask the user. `publish` has already made its one retry of a rejected push itself, where a reconcile resolved the rejection
- The push target (`--branch`) is not the checked-out branch, or HEAD is detached; the unborn branch of a fresh `git init` is not this case -> Check out the branch you mean to publish, or pass `--branch <checked-out branch>`, then retry once
- `--yes`/`-y` was passed - the flag does not exist and fails with an explicit error -> Drop it. The Mass-Update Gate is cleared only with `--confirm <token>` from the gate's own refusal output
- `.wikitool-remotes.json` is unreadable or has no usable `allowed_push_urls` list -> Show the error to the user and stop - a malformed file is not permission, and fixing or deleting it is theirs to do
- Mass-Update Gate: `--threshold` (default 10) or more counted files would be committed, or the `--confirm` token does not match this changeset -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
- Rebase-review gate: `<remote>/<branch>` moved and both sides changed the same file; the output lists the upstream commits, the overlapping files and their diff -> Show the user the command's full output verbatim and stop. Once they have approved it, run the re-run line the output prints, which carries `--confirm-rebase <token>`. Without that token, or with a wrong, invented or superseded one, it exits 42 again with the current state
- Publish-Remote Gate: `.wikitool-remotes.json` exists and the push URL of `--remote` is not listed in it, or `--remote` resolves to no push URL -> Show the user the push URL it names and the allowed ones, and stop. This gate has no token and no flag: only the user resolves it, by adding the URL to that file

**NEVER**

- Never retry a failed git step unchanged, and never force (`--force`, `--force-with-lease`).
- Never pass a `--confirm` or `--confirm-rebase` token the user has not seen and approved.
- Never edit `.wikitool-remotes.json` to get past a Publish-Remote refusal - that is opening a gate on your own initiative.

**NOTES**

- Order: branch check and Publish-Remote Gate, then the reconcile with `<remote>/<branch>`, then the Mass-Update Gate, then `git add -A`, commit and push. `--no-push` skips all but the Mass-Update Gate and the commit.
- Reconcile: fetches `<remote>/<branch>`, fast-forwards when only the remote moved, rebases the local commits on top when both sides moved but touched disjoint files, and exits 42 (rebase-review gate) when both sides touched the same file. A refused reconcile performs no rebase attempt. The `--confirm-rebase` token covers the exact upstream state and the set of files touched on both sides.
- The push target must be the checked-out branch; this is checked before anything is staged. The unborn branch of a fresh `git init -b main` counts as checked out, so the first publish of a new instance works; a real detached HEAD is refused.
- With nothing new to stage, a local commit the remote lacks is still pushed: one left behind by an earlier publish whose push failed, or every commit when the remote answers but does not have the branch yet (a new, empty remote repository).
- A remote that cannot be reached is not read as lacking the branch: on a clean tree `publish` reports "Nothing to commit" and attempts no push.
- A rejected push gets exactly one more reconcile-and-push; never more than one.
- Mass-Update Gate: counts the files that would be committed, refuses with exit 42 at `--threshold` (default 10) or more, and prints a review report - a scale line (file count, total lines added/removed, status breakdown), attention notes where they apply (deletions by name, control-plane and harness-config touches, published pages, the largest single change, binaries), and every counted path grouped by area with its status and churn. The gate is evaluated before anything is staged, so a refused publish leaves the working tree untouched.
- Never counted and never shown for approval, but committed like everything else: anything under `work/`, and the files `wikitool` generates itself (`kb/index.md`, `kb/log.md`, `kb/provenance.md`, every `INDEX.md`). The refusal line accounts for both, by reason.
- The `--confirm` token covers each counted path, its contents and the publish target: a different file list or edited contents need a new clearance.
- Publish-Remote Gate: when the checkout carries `.wikitool-remotes.json` and the push URL of `--remote` is not listed in it, exits 42 before the reconcile fetches anything. The URL is read with `git remote get-url --push`, so a repointed remote does not pass on its name. An absent file means unrestricted; a malformed one is an error, not permission.
- `--path` (repeatable) scopes the whole operation - gate count, staging and commit - to that subtree.
- After a successful commit or push whose changed files include `tools/`, `types/`, `instructions/`, `AGENTS.md` or a path ending in `CONTRACT.md`, prints one reminder line: the phase past this point (an issue-body rewrite, `docs/` staleness, a changelog entry's accuracy) is not covered by `docs verify`, `instructions verify` or `pytest`. It is not a gate: no exit code change, nothing to clear, and silent for an ordinary content publish.

**SEE ALSO**

- `wikitool sync` - the same reconcile on its own, without committing or pushing
- `instructions/gates.md` - the gate procedure
- `instructions/setup-instance.md` - the first publish of a new instance

### Workshop runs and session budget

#### `work new`

Scaffold `work/<runkey>/` for one workshop run.

**SYNOPSIS**

- `wikitool work new (--input <raw path> | --key <run key>) [--again] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: Yes - one directory with two files
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool work new --input raw/2026/09/handbuch`
- `tools/wikitool work new --key migrate-7.0.0`
- `tools/wikitool work new --input raw/2026/09/handbuch --again`

**EXIT STATUS**

- 0    success
- 1    Neither or both of `--input`/`--key` given, or a `--key` that is empty or starts with `ingest-`
- 1    `--input` is outside `raw/`, does not exist, or is `raw/` itself (an empty run key)
- 1    The workshop already exists

**ON FAILURE**

- Neither or both of `--input`/`--key` given, or a `--key` that is empty or starts with `ingest-` -> Fix the argument and retry once
- `--input` is outside `raw/`, does not exist, or is `raw/` itself (an empty run key) -> Point `--input` at material under `raw/`, or use `--key` for a run with no raw input
- The workshop already exists -> A collision is not transient: resume the existing run instead, or pass `--again` if the tree itself changed

**NEVER**

- Never create a numbered variant of a run key by hand.

**NOTES**

- Creates `work/<runkey>/` with the required `README.md` and `plan.md`.
- `--input` derives the run key from the path below `raw/` (an ingest); `--key` names it outright for a run with no raw input - a migration or a sweep across `kb/` - and may not start with `ingest-`, which stays reserved for derived keys. Exactly one of the two.
- Refuses a collision instead of suffixing it.
- `--again` opens a dated second pass (`<runkey>-<date>`) over a tree that has itself changed.
- `--dry-run` reports the run key and files without writing.

**SEE ALSO**

- `work/CONTRACT.md` - run keys, required files, how a run closes
- `wikitool work close` - deletes the run when it is done
- `instructions/ingest-large-tree.md` - the ingest that opens a run

#### `work close`

Delete a finished workshop.

**SYNOPSIS**

- `wikitool work close --run-key <name> [--yes] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: No - a recursive delete
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool work close --run-key ingest-2026-09-handbuch --dry-run`
- `tools/wikitool work close --run-key ingest-2026-09-handbuch --yes`

**EXIT STATUS**

- 0    success
- 1    Unknown run key
- 1    `--yes` was not passed - the output lists what would be lost

**ON FAILURE**

- Unknown run key -> Check `ls work/` for the open runs, then retry once
- `--yes` was not passed - the output lists what would be lost -> Check the listed files are no longer needed, confirm the conclusions are in `kb/`, then re-run with `--yes`

**NEVER**

- Never pass `--yes` before the run's conclusions are in `kb/`.

**NOTES**

- Deletes `work/<run-key>/` recursively.
- Without `--yes` it lists what would be lost and refuses: nothing in a workshop is recoverable from the rest of the repo, so the durable conclusions must already be in `kb/`.
- `--dry-run` lists the files without deleting.
- Not idempotent: once deleted, the run key is unknown.

**SEE ALSO**

- `work/CONTRACT.md` - how a run closes
- `wikitool work new` - opens a run

#### `budget status`

Show the current session's `wikitool` call count and recent command history.

**SYNOPSIS**

- `wikitool budget status`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool budget status`

**EXIT STATUS**

- 0    success

**NOTES**

- Shows the current session's `wikitool` call count and its recent command history.
- Never counted against the budget; never fails; safe to retry freely.

**SEE ALSO**

- `instructions/session-setup.md` - scoping the budget to a task
- `instructions/gates.md` - what to do when the Iteration Budget Gate refuses

#### `budget reset`

Clear the current session's (or every session's) iteration budget state.

**SYNOPSIS**

- `wikitool budget reset --yes [--all]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: Read/rewrite of one JSON file (or its deletion, with `--all`)
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool budget reset --yes    # only after the user approved it`

**EXIT STATUS**

- 0    success
- 1    `--yes` not passed

**ON FAILURE**

- `--yes` not passed -> Get the user's approval, then re-run with `--yes`

**NEVER**

- Never run it on your own initiative to get past a budget or loop-breaker refusal.

**NOTES**

- Clears the current session's iteration budget state; `--all` deletes every session's.
- Requires `--yes`: clearing the counter is itself a way around the Iteration Budget Gate, so it needs the same explicit human approval.
- Counted against the budget like any other call.

**SEE ALSO**

- `wikitool budget status` - the current count
- `instructions/gates.md` - why `budget reset` is not the escape hatch

### Types, instructions and docs

#### `types list`

List every type-spec under `types/`.

**SYNOPSIS**

- `wikitool types list [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool types list`
- `tools/wikitool types list --json`

**EXIT STATUS**

- 0    success

**NEVER**

- Never pick a page's directory by hand - `types describe` and `new` compute it.

**NOTES**

- Lists every type-spec under `types/`: name, schema path, subtype field, and description - which page types exist, without reading `types/*.md` directly.
- Never fails; read-only and safe to retry freely.

**SEE ALSO**

- `wikitool types describe <name>` - one type's full contract

#### `types describe`

Print one type's full contract.

**SYNOPSIS**

- `wikitool types describe <name> [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool types describe source`
- `tools/wikitool types describe project --json`

**EXIT STATUS**

- 0    success
- 1    Unknown type name

**ON FAILURE**

- Unknown type name -> Fix the name (see `types list`) and retry

**NOTES**

- Prints one type's full contract: required and optional frontmatter fields with enums, its subtype field (if any), and its authoring body.
- Where the type-spec declares `guidance:`, the stack-owned `types/<name>.guidance.md` is composed in, so a `root: kb` type's contract reads as one answer even though it may live in two files. `--json` reports it separately as `guidance`/`guidance_path`, absent for a type with none.
- The generated table-of-contents region a long type-spec (or guidance file) carries is stripped from this output.
- Read-only.

**SEE ALSO**

- `wikitool types list` - every type
- `wikitool new <type>` - scaffolds a page of the type

#### `instructions sync`

Publish every `instructions/<name>/SKILL.md` into the harness skill directories.

**SYNOPSIS**

- `wikitool instructions sync [--force]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - one directory copy per skill per target (`.agents/skills/`, `.claude/skills/`); each copy is idempotent, so a re-run converges even after a partial failure
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool instructions sync`

**EXIT STATUS**

- 0    success
- 1    No skills found under `instructions/`
- 1    A target directory is not a published skill (no `SKILL.md`) and `--force` was not passed

**ON FAILURE**

- No skills found under `instructions/` -> Fix the named cause and retry
- A target directory is not a published skill (no `SKILL.md`) and `--force` was not passed -> Check whether the flagged target holds anything worth keeping, then re-run with `--force` if not

**NEVER**

- Never hand-edit a published copy under `.agents/skills/` or `.claude/skills/` - edit the source and re-run this.

**NOTES**

- Publishes every `instructions/<name>/SKILL.md` into `.agents/skills/` and `.claude/skills/` as **copies**, and deletes published skills whose source is gone.
- Both targets are gitignored, so a fresh clone runs this once.
- Re-running repairs a drifted copy: the source always wins.
- `--force` is required only to replace a target directory that is not a published skill at all (no `SKILL.md` in it).
- Each copy is idempotent, so a re-run converges even after a partial failure.

**SEE ALSO**

- `instructions/bootstrap.md` - the fresh-clone procedure that runs this
- `wikitool instructions verify` - checks the copies match

#### `instructions verify`

Check the instruction layer.

**SYNOPSIS**

- `wikitool instructions verify`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool instructions verify`

**EXIT STATUS**

- 0    success
- 1    Nothing found under `instructions/` at all, or a malformed instruction or `SKILL.md`
- 1    A `SKILL.md` carries a relative markdown link
- 1    A published copy drifted from its source
- 1    An instruction nothing references, or a `manual: true` one that IS linked from AGENTS.md, CLAUDE.md or a skill and so risks running implicitly
- 1    Something under `instructions/dev/` is referenced from outside it and outside a `dist:strip` block

**ON FAILURE**

- Nothing found under `instructions/` at all, or a malformed instruction or `SKILL.md` -> Fix the flagged file, then re-run
- A `SKILL.md` carries a relative markdown link -> Rewrite it as a repo-root-relative plain path, then re-run
- A published copy drifted from its source -> Re-run `instructions sync` - the source under `instructions/` always wins
- An instruction nothing references, or a `manual: true` one that IS linked from AGENTS.md, CLAUDE.md or a skill and so risks running implicitly -> Link it from where it is used, or drop the link to a manual one, then re-run
- Something under `instructions/dev/` is referenced from outside it and outside a `dist:strip` block -> Remove the reference or wrap it in a `dist:strip` block, then re-run

**NEVER**

- Never fix drift by hand-editing the published copy.

**NOTES**

- Flat instructions validate against `types/instruction.schema.yaml`, and each `SKILL.md` carries the frontmatter its harness reads.
- No `SKILL.md` carries a relative markdown link: `sync` copies it to a different depth than the source, so a `SKILL.md` references a target as a repo-root-relative plain path instead (`instructions/CONTRACT.md` § "A skill's outbound reference is a plain path, not a link").
- Every published copy is byte-identical to its source. Missing *every* copy is reported as "run sync", not as drift - that is a clean checkout.
- No instruction is left that nothing references; one marked `manual: true` must instead not be linked from AGENTS.md, CLAUDE.md or a skill.
- Nothing under `instructions/dev/` is referenced from outside it; a `<!-- dist:strip-start/end -->` block is exempt (`instructions/CONTRACT.md`).
- Read-only.

**SEE ALSO**

- `wikitool instructions sync` - publishes the copies
- `instructions/CONTRACT.md` - the rules this checks

#### `instructions list`

List the flat instructions with their descriptions.

**SYNOPSIS**

- `wikitool instructions list [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool instructions list`
- `tools/wikitool instructions list --json`

**EXIT STATUS**

- 0    success

**NOTES**

- Lists the flat instructions with their descriptions - how the instruction layer is discovered; `search` covers `kb/` only.
- Never fails: an empty `instructions/` prints "No instructions found." Read-only and safe to retry freely.

**SEE ALSO**

- `wikitool search` - the same question for `kb/`

#### `docs verify`

Check the docs that mirror the code.

**SYNOPSIS**

- `wikitool docs verify`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool docs verify`

**EXIT STATUS**

- 0    success
- 1    A command, contract, or type-form mismatch
- 1    The `<!-- wikitool:commands -->` region of `tools/CONTRACT.md` is stale
- 1    A type-spec's own frontmatter fails its schema
- 1    A shipped `.md`/`.template` cites an issue number
- 1    A reference file's table-of-contents region is missing or stale
- 1    A reference file's relative markdown link does not resolve to an existing file

**ON FAILURE**

- A command, contract, or type-form mismatch -> Fix the documentation it names, then re-run
- The `<!-- wikitool:commands -->` region of `tools/CONTRACT.md` is stale -> Run `docs contract --apply`, then re-run
- 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 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 reference file's table-of-contents region is missing or stale -> Run `docs toc --apply`, then re-run
- A reference file's relative markdown link does not resolve to an existing file -> Fix the `../` count or the target's name

**NEVER**

- Never hand-write a table-of-contents region or the commands region - regenerate it.

**NOTES**

- Checks the docs that mirror the code. The name is about documentation parity, not the `docs/` directory - it neither reads nor 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`; no pre-migration `type: entity` blocks are left in the contracts.
- `kb/CONVENTIONS.md`, if it exists at all, names all three tool-owned section headings; every stage contract is present.
- The `.gitignore` canaries clear in both directions: nothing ignored under `raw/`/`kb/`, `incoming/` ignored, everything ignored under `reports/` and the published skill directories.
- No `.md`/`.template` file `dist export` would ship cites an issue number. A `<!-- dist:strip-start/end -->` region is exempt: the check reads the export plan's text, from which it is already gone.
- 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.
- Read-only.

**SEE ALSO**

- `wikitool docs toc` - regenerates tables of contents
- `wikitool docs contract` - regenerates the commands region
- `wikitool instructions verify` - the same kind of check for `instructions/`

#### `docs toc`

Create, refresh or remove the generated table-of-contents region.

**SYNOPSIS**

- `wikitool docs toc [--apply]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: `--apply` rewrites each named file in place, one at a time and idempotently, so a re-run after an interruption converges rather than doubling a region; the dry-run form is read-only
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool docs toc`
- `tools/wikitool docs toc --apply`

**EXIT STATUS**

- 0    success
- 0    Never fails on content: a file with no `##` heading, or one at or under the threshold, is simply left without a region

**NEVER**

- Never hand-write or hand-edit a table-of-contents region.

**NOTES**

- Creates, refreshes or removes the generated table-of-contents region on every reference file over 100 lines: `AGENTS.md`, every stage contract, `kb/CONVENTIONS.md`, every `kb/*/COLLECTION.md`, every flat `instructions/**.md` file, every `types/*.md` type-spec, and every `docs/` page - each together with the `<name>.template` it ships as, where one exists.
- The scope is computed from those categories rather than listed, so a file added later is in scope without a code change.
- Out of scope: every `SKILL.md`, and the human docs (`README.md`, `CHANGES.md`, `EVALS.md`, `INSTALL.md`, `tools/README.md`).
- Dry-run by default (prints which files would change); `--apply` writes. Idempotent: a re-run after an interruption converges rather than doubling a region.
- If `docs verify` still reports a stale region after `--apply`, the file's `##` headings changed in between; run it again.

**SEE ALSO**

- `wikitool docs verify` - checks every region is current

#### `docs contract`

Regenerate `tools/CONTRACT.md`'s `<!-- wikitool:commands -->` region.

**SYNOPSIS**

- `wikitool docs contract [--apply]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: Yes - the whole region is rewritten in one file write
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool docs contract`
- `tools/wikitool docs contract --apply`

**EXIT STATUS**

- 0    success

**NEVER**

- Never hand-edit the region - change the record in code and re-run this.

**NOTES**

- Rebuilds the region from every `cli_contract` record: the index (one line per command, `GROUPS` order) followed by each `###` group's commands as `#### <path>` man-page-shaped sections.
- Dry-run by default (says whether the file would change); `--apply` writes.
- `docs verify` checks the result stays current.

**SEE ALSO**

- `tools/README.md` § Adding a command - how a command gets its record
- `wikitool docs verify` - checks the region is current

### Telemetry

#### `eval sessions`

List the sessions that have a trace under `reports/telemetry/`.

**SYNOPSIS**

- `wikitool eval sessions [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool eval sessions`
- `tools/wikitool eval sessions --json`

**EXIT STATUS**

- 0    success

**NOTES**

- Lists the sessions that have a trace under `reports/telemetry/`, most recent first.
- Never fails; an empty list is a valid answer.
- Read-only and exempt from the Iteration Budget Gate.

**SEE ALSO**

- `wikitool eval score` - scores one of them
- `EVALS.md` - how telemetry and evaluation work

#### `eval score`

Score one traced session.

**SYNOPSIS**

- `wikitool eval score [--session <id>] [--json] [--markdown out.md] [--save] [--fail-on-error]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only, apart from the files `--save`/`--markdown` write
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool eval score`
- `tools/wikitool eval score --session wiki-1727330000 --save`

**EXIT STATUS**

- 0    success
- 1    No trace exists for the named session
- 1    Only with `--fail-on-error`: the tree has hard errors or an invariant was violated

**ON FAILURE**

- No trace exists for the named session -> Run `eval sessions` to see which ids exist; check with `doctor` whether telemetry is on
- Only with `--fail-on-error`: the tree has hard errors or an invariant was violated -> Act on the scorecard; re-run only to re-measure

**NOTES**

- Scores one traced session: structural state from `lint`'s own checks (L1) plus trajectory rules over the trace (L2) - was a refused call repeated unchanged, was a gate flag passed without that gate having refused anything, did a publish of `kb/` pages go unlogged.
- Defaults to the current session; `--session <id>` picks another.
- `--save` writes `reports/evals/<date>/<session>.{json,md}`; `--markdown` writes the report to the named file.
- A session records nothing when telemetry is off - `WIKI_TRACE=0`, or a distributed instance with no opt-in (`wikitool doctor` says which) - so an absent trace is not necessarily a fault.
- Read-only over `kb/`, safe to retry, and exempt from the Iteration Budget Gate.

**SEE ALSO**

- `wikitool eval sessions` - which session ids exist
- `EVALS.md` - the scoring levels

### Distribution and versioning

#### `dist export`

Write a contentless, distributable copy of this repo's machinery.

**SYNOPSIS**

- `wikitool dist export <target> [--dry-run] [--source-repo U] [--source-commit SHA] [--release-url U] [--update-url U]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: Yes - nothing is written until every file is planned
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool dist export ../my-wiki --dry-run`
- `tools/wikitool dist export ../my-wiki`

**EXIT STATUS**

- 0    success
- 1    `<target>` exists and is not empty, or is not a directory
- 1    The tree has no readable `VERSION`
- 1    A licence file is missing from the source tree
- 1    The plan would carry this instance's own data (a filled personalization, conventions or page type-spec file)

**ON FAILURE**

- `<target>` exists and is not empty, or is not a directory -> Point `<target>` at an empty (or new) directory and retry
- The tree has no readable `VERSION` -> Fix `VERSION`, then retry
- A licence file is missing from the source tree -> Restore it, then retry
- The plan would carry this instance's own data (a filled personalization, conventions or page type-spec file) -> Report it: it is an allowlist bug in `dist export`, not something to work around by deleting files from the target

**NEVER**

- Never merge an export into a non-empty directory by hand.

**NOTES**

- Writes a contentless, distributable copy of this repo's machinery into an empty or new `<target>` directory.
- Ships `AGENTS.md`/`README.md`/`EVALS.md` with any `dist:strip-start`...`dist:strip-end` marker region removed, `instructions/` (minus `instructions/dev/`), `types/` (the `root: kb` page type-specs and their schemas re-keyed as `.template`, the stack's own verbatim), `docs/` verbatim, `tools/` (no venv/caches), the `.github/hooks/`+`.vibe/` session-tracing config plus `.claude/settings.json`, `kb/CONTRACT.md` (no pages, no areas) and `VERSION`.
- Ships `raw/` and `incoming/` as flat roots, each with a `.gitkeep` and no subdirectories. `incoming/.gitkeep` is trackable and survives becoming a git repository, so a plain clone gets the directory without any bootstrap step.
- Ships templates, never the filled files: `USER.md.template`/`SOUL.md.template`, `kb/CONVENTIONS.md.template`, and each collection's contract re-keyed as `kb/<name>/COLLECTION.md.template`. The filled `USER.md`/`SOUL.md`/`kb/CONVENTIONS.md`/`kb/<name>/COLLECTION.md`/`types/<page-type>.md` bind their instance; `find_leaks` refuses a plan carrying one.
- Writes a generated `.wikitool-release.json` stamp: version, export date, origin, and a sha256 per exported file - the base a later upgrade compares against.
- The four origin options only fill stamp fields: `export` never calls git and cannot discover them.
- One-way: no command reconstructs a distributed instance into a dev instance - work on the stack in the origin repo, or in a new dev instance exported from it.
- `--dry-run` lists every file it would write, and writes nothing.

**SEE ALSO**

- `instructions/setup-instance.md` - what comes after the export
- `wikitool dist upgrade` - applies a later export to an existing instance
- `wikitool version show` - reads the stamp this writes

#### `dist upgrade`

Apply a stack update `dist export` produced - the write half of `version check`.

**SYNOPSIS**

- `wikitool dist upgrade <source> [--dry-run] [--keep-local] [--take-release <path>]... [--prune] [--pre]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: Yes for every refusal - nothing is written. Once writing starts it is a plain sequential file copy with no partial-state cleanup: an interruption mid-copy (killed process, disk full) can leave the tree part-old, part-new
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz --dry-run`
- `tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz`
- `tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz --take-release tools/README.md`

**EXIT STATUS**

- 0    success
- 0    The source's version equals the installed one - a no-op success
- 1    Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block
- 1    `.wikitool-kb.json` is missing
- 1    A migration is already outstanding against the *installed* machinery
- 1    The working tree is dirty
- 1    `<source>` does not exist, fails its `.sha256`, or does not unpack to exactly one top-level directory
- 1    The source carries no `VERSION`, `.wikitool-release.json` or `files` block
- 1    The source's version is older than the installed one, or a pre-release without `--pre`
- 1    A `--take-release` path this run does not classify as locally changed - the one refusal a `--dry-run` also raises
- 1    Locally changed files that neither `--keep-local` nor a `--take-release` answers for; nothing was written

**ON FAILURE**

- Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block -> Not transient - fix the named precondition and retry. A checkout with shared git history takes stack updates with `wikitool upstream merge` instead
- `.wikitool-kb.json` is missing -> Run `wikitool migrate baseline <version>`, then retry
- A migration is already outstanding against the *installed* machinery -> Finish it first - `wikitool migrate status` names it - then retry
- The working tree is dirty -> Commit or stash first, then retry
- `<source>` does not exist, fails its `.sha256`, or does not unpack to exactly one top-level directory -> Fix the path or re-download the release archive, then retry
- The source carries no `VERSION`, `.wikitool-release.json` or `files` block -> Point `<source>` at a distribution export, then retry
- The source's version is older than the installed one, or a pre-release without `--pre` -> Not transient - choose another source, or pass `--pre` for a pre-release
- A `--take-release` path this run does not classify as locally changed - the one refusal a `--dry-run` also raises -> Correct it against the locally-changed list the refusal prints, then retry
- Locally changed files that neither `--keep-local` nor a `--take-release` answers for; nothing was written -> Choose one of the three answers the refusal names, re-run lines filled in: `--take-release <path>` to write the release's version over it (ends the divergence), `--keep-local` to leave them untouched (reported again on every later run until they stop diverging), or reconcile by hand and retry

**NEVER**

- Never treat any of the three answers to locally changed files as the default.

**NOTES**

- Never downloads anything: `<source>` is an already-fetched export directory or `.tar.gz` release archive. An archive is verified against a sibling `.sha256` if one is present (a missing one is a WARN, not a block) and must unpack to exactly one top-level directory - the shape `.gitea/workflows/release.yml` packs.
- The write set is exactly the *new* `.wikitool-release.json`'s `files` block, minus what an export re-seeds from a blank template every time (`kb/log.md`, `raw/.gitkeep`) or seeds once and the instance owns from then on (`.wikitool-kb.json`, `CHANGES.md`), plus the stamp itself, always rewritten.
- Every candidate path is classified against the *local* `.wikitool-release.json`'s recorded digest: unchanged is overwritten silently, absent from the old stamp is created, and locally modified or locally deleted is **never** silently overwritten.
- Locally changed files abort the run with the full list; the abort text names the three answers with the command line filled in, and none of them is the default.
- `--keep-local` proceeds and leaves every locally changed file untouched. The new stamp is still written whole, recording the release's digest for files that were not written, so a skipped file keeps diverging and is reported again on every later run.
- `--take-release <path>` (repeatable) writes the release's version over the named path, discarding the local change, and re-creates it if it was locally deleted. The path then matches the stamp and stops being reported.
- The two are decided per path and compose on one call: without `--keep-local`, a locally changed path that no `--take-release` names still aborts the run.
- A path in the old stamp but not the new one is reported as no longer part of the release and left alone, unless `--prune` is passed, which removes it only if it is still unchanged since installation.
- Reports the migration chain the new machinery would owe, but never runs any of it - there is no `migrate run`.
- Reports, but does not block on, a crossed compatibility boundary.
- The local preconditions - `VERSION`, the release stamp, `.wikitool-kb.json`, no outstanding migration, a clean working tree - are checked before the source is read. Not being a git repository at all is a WARN, not a refusal.
- Never touches git - no commit, no push.
- `--dry-run` classifies and reports without writing; a pre-release (`-beta.N`) source needs `--pre`.
- An interrupted write is not resumed automatically: compare the tree against the printed classification and finish or revert by hand.
- The closing report names `instructions/upgrade-instance.md`, which carries the order for everything after the swap and resumes at `instructions sync`.

**SEE ALSO**

- `wikitool version check` - finds out whether an update exists
- `instructions/upgrade-instance.md` - the order after the swap
- `INSTALL.md` § "Version und Updates" - which release, whether to take it, where the tarball comes from
- `wikitool upstream merge` - the update path for a checkout with shared git history
- `wikitool migrate status` - the migrations the report names

#### `version show`

Print this instance's stack version and where it came from.

**SYNOPSIS**

- `wikitool version show [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool version show`
- `tools/wikitool version show --json`

**EXIT STATUS**

- 0    success
- 1    `VERSION` is missing or unparseable

**ON FAILURE**

- `VERSION` is missing or unparseable -> Fix `VERSION` and retry

**NOTES**

- Prints `VERSION` and where this tree came from: "development tree" without a release stamp, otherwise the export date, source commit and repository from `.wikitool-release.json`, plus the release page when the stamp records one.
- `--json` prints the version, its compatibility key, the stamp and the update URL.
- Bare `wikitool version` is an alias for this.
- Read-only and offline; exempt from the Iteration Budget Gate.

**SEE ALSO**

- `wikitool version check` - asks whether a newer stack exists
- `wikitool version notes` - prints a version's release notes

#### `version check`

Ask the origin's release feed whether a newer stack exists.

**SYNOPSIS**

- `wikitool version check [--url U] [--timeout S] [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only, no local writes
- budget: exempt
- network: yes

**EXAMPLES**

- `tools/wikitool version check`
- `tools/wikitool version check --json`

**EXIT STATUS**

- 0    success
- 1    `VERSION` is missing or unparseable
- 1    The feed could not be reached, answered non-JSON, or carried no `tag_name`

**ON FAILURE**

- `VERSION` is missing or unparseable -> Fix `VERSION` and retry
- The feed could not be reached, answered non-JSON, or carried no `tag_name` -> A network failure is transient - retry once, then report it. HTTP 401/403 names `$WIKITOOL_UPDATE_TOKEN`; 404 means no release exists yet or the URL points at the wrong repo

**NEVER**

- Never report "up to date" for a check that failed - an unreachable feed is not that answer.

**NOTES**

- Asks the release feed for its latest release and compares it with `VERSION`: `state` is `current`, `update`, `migration` (the step crosses a compatibility boundary) or `ahead`.
- One of the **two** commands in `wikitool` that make a network call, and the only one whose whole job it is - `version notes` is the other, and only on a distributed instance.
- Never reached implicitly from another command, needs no key, and times out after `--timeout` seconds (default 10).
- The feed is `--url`, else `$WIKITOOL_UPDATE_URL`, else the release stamp's, else the built-in origin. `$WIKITOOL_UPDATE_TOKEN` is only needed if that feed is not readable anonymously.
- For `update` or `migration` it prints that applying the release is a separate, manual step (`INSTALL.md` § "Eine Instanz aktualisieren").
- Read-only; exempt from the Iteration Budget Gate.

**SEE ALSO**

- `wikitool dist upgrade` - applies the update this reports
- `wikitool version notes` - prints the release notes
- `INSTALL.md` § "Version und Updates" - what the operator decides before an update

#### `version notes`

Print one version's release notes.

**SYNOPSIS**

- `wikitool version notes [--version X.Y.Z] [--offline] [--url U] [--timeout S]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: yes

**EXAMPLES**

- `tools/wikitool version notes`
- `tools/wikitool version notes --version 7.0.0`
- `tools/wikitool version notes --offline`

**EXIT STATUS**

- 0    success
- 1    `--version` is unparseable, `VERSION` is unreadable when `--version` is omitted, or `CHANGES.md` is missing
- 1    No entry for the requested version in a tree with no release stamp (a dev checkout)
- 1    No entry for the requested version, and `--offline` was passed
- 1    No entry for the requested version, and the feed could not be reached or returned a release with an empty `body`

**ON FAILURE**

- `--version` is unparseable, `VERSION` is unreadable when `--version` is omitted, or `CHANGES.md` is missing -> Fix the named argument or file, then retry
- No entry for the requested version in a tree with no release stamp (a dev checkout) -> Write the entry, or run `version bump`
- No entry for the requested version, and `--offline` was passed -> Read the release page the error names
- No entry for the requested version, and the feed could not be reached or returned a release with an empty `body` -> A feed failure is transient - retry once, then read the release page the error names

**NOTES**

- Prints the `CHANGES.md` entry for `--version` (default: this tree's `VERSION`).
- With no such entry, in a tree with a release stamp (a `dist export` tree) and without `--offline`, it prints the release feed's latest release notes instead. A tree without a stamp (a dev checkout) never asks the feed.
- Only the feed's latest release can be asked for. When that is a different version than requested, stderr names it and the notes are printed anyway - the expected case before an upgrade, where `VERSION` still names the release being left.
- stdout carries nothing but the notes; the line naming the feed being asked and the one naming the release that answered go to stderr. `release.yml` redirects stdout into the file it posts as the release body.
- `--offline` never asks the feed and fails with the stamp's `release_url` instead.
- Every failure names the stamp's `release_url` where it has one, so a run that cannot read the notes is still told where they are.
- Read-only, safe to retry, and exempt from the Iteration Budget Gate.

**SEE ALSO**

- `wikitool version check` - asks the same feed whether a newer stack exists
- `wikitool version bump` - writes the entry this prints

#### `version bump`

Raise or continue the one running candidate between two releases.

**SYNOPSIS**

- `wikitool version bump --major|--minor|--patch --title "<...>" [--impact high|medium|low] [--breaking "<what breaks>"] [--no-migration "<reason>"] [--migration-required] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: No - `VERSION` then `CHANGES.md`
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool version bump --patch --title "Fix the lint report path" --impact low`
- `tools/wikitool version bump --minor --title "New command: wikitool review" --dry-run`
- `tools/wikitool version bump --major --title "Rename --gate-file to --remotes-file" --breaking "--gate-file is gone; scripts must pass --remotes-file" --no-migration "no content changes"`

**EXIT STATUS**

- 0    success
- 1    Not exactly one of `--major`/`--minor`/`--patch`, an empty `--title`, or an unknown `--impact`
- 1    `VERSION` or `CHANGES.md` is missing, or `VERSION` and the changelog's newest entry name different versions
- 1    An escalation to a boundary crossing without `--breaking`, or with neither a migration document targeting the new base nor `--no-migration`
- 1    `--breaking` or `--no-migration` on a bump that crosses nothing
- 1    `--migration-required` combined with `--no-migration`, on a bump with no running candidate, with no `--no-migration` line to retract, or without a migration document already targeting the new base

**ON FAILURE**

- Not exactly one of `--major`/`--minor`/`--patch`, an empty `--title`, or an unknown `--impact` -> Nothing was written - fix the argument and retry once
- `VERSION` or `CHANGES.md` is missing, or `VERSION` and the changelog's newest entry name different versions -> Nothing was written - fix whichever is wrong, then retry
- An escalation to a boundary crossing without `--breaking`, or with neither a migration document targeting the new base nor `--no-migration` -> Nothing was written - add what the error asks for, or, if nothing actually breaks, choose a smaller part
- `--breaking` or `--no-migration` on a bump that crosses nothing -> Nothing was written - drop the flag and retry
- `--migration-required` combined with `--no-migration`, on a bump with no running candidate, with no `--no-migration` line to retract, or without a migration document already targeting the new base -> Nothing was written - write the migration document or fix the combination, then retry

**NEVER**

- Never re-run after an uncertain outcome without first reading `VERSION` and the top of `CHANGES.md` - a second run escalates or continues the candidate again.
- Never hand-edit `VERSION` or the machine-written parts of the entry (heading, bump list, breaking and migration lines); `--migration-required` is the only way to take the migration line back.

**NOTES**

- `VERSION` gets a `-beta.N` suffix: one running candidate between two releases, never a fresh number per bump.
- `--major`/`--minor`/`--patch` is **max-wins escalation** against the last release (patch < minor < major): a `--patch` on a MINOR candidate only advances `N`, and escalation never steps back down.
- The first bump of a candidate opens its `CHANGES.md` entry - heading, date, author, and a machine-managed `<!-- wikitool:bumps -->` list of every `--title` collected so far, graded by `--impact` (default `medium`). Every later bump of the same candidate updates that entry in place: one entry per candidate, not one per bump.
- The bump list renders grouped under `**High/Medium/Low impact**` headings, empty groups omitted - except while every bump is `medium`, where it stays one flat list. `version regrade` corrects a grade after the fact.
- Writes the heading, the bump list and the breaking/migration lines; the entry's prose is left to the author.
- Compatibility follows the **leftmost non-zero component** of the candidate's base, which for this stack (at `1.0.0` and up) means MAJOR: PATCH is a fix, MINOR a compatible capability, MAJOR a version that is **not a drop-in replacement** - any hand-work on update, or a downgrade that no longer works. Whether content must be migrated is a second, independent question.
- The bump that first escalates a candidate past the boundary requires `--breaking "<what stops working>"` and, on top of it, a migration document targeting the candidate's base or `--no-migration "<reason>"`. Both are anchored just above the bump list, persist over later bumps of the same candidate without being repeated, and are refused on a bump that crosses nothing at all.
- On a later crossing of the same candidate, a further `--breaking` **joins** the reasons already recorded (flat on the marker line while there is one, bullets under a bare marker from the second on; repeating a reason verbatim is a no-op), while a further `--no-migration` **replaces** the single migration line.
- `--migration-required` retracts the running candidate's `--no-migration` line; it needs a migration document already targeting the new base. Nothing retracts a recorded `--breaking` reason.
- Enforces that a crossing documents itself, never that the part was chosen correctly.
- Not idempotent: every successful run escalates or continues the candidate again.
- `--dry-run` reports the step without writing.

**SEE ALSO**

- `wikitool version regrade` - corrects an `--impact` grade
- `wikitool version release` - fixes the candidate into a release
- `instructions/migrate-corpus.md` - how a migration document is written

#### `version regrade`

List the running candidate's bump titles with their impact grade, or change one or more of them.

**SYNOPSIS**

- `wikitool version regrade [INDICES...] [--impact high|medium|low]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: No - `CHANGES.md` only, and only when indices are given
- budget: exempt_without_args
- network: no

**EXAMPLES**

- `tools/wikitool version regrade`
- `tools/wikitool version regrade 3 7 --impact high`

**EXIT STATUS**

- 0    success
- 1    `VERSION` or `CHANGES.md` is missing, `VERSION` and the changelog's newest entry name different versions, or the topmost entry has no bump list
- 1    An index outside the rendered list's range, indices given without `--impact`, or an unknown `--impact`

**ON FAILURE**

- `VERSION` or `CHANGES.md` is missing, `VERSION` and the changelog's newest entry name different versions, or the topmost entry has no bump list -> Nothing was written - fix whichever is wrong, then retry
- An index outside the rendered list's range, indices given without `--impact`, or an unknown `--impact` -> Nothing was written - list again with the bare command, then retry once with corrected arguments

**NEVER**

- Never re-run the same indices after a write without listing again first - the positions may have moved.

**NOTES**

- Without arguments: lists the running candidate's bump titles with their grade, numbered by 1-based position in the rendered list (High before Medium before Low, chronological within a grade). Read-only and exempt from the Iteration Budget Gate.
- With indices and `--impact`: sets the grade of every named position in one call, all resolved against a single read of the current list - `version regrade 3 7 --impact high` grades what is at 3 and 7 now, not 7 after 3 has moved. Writes `CHANGES.md` and is counted by the Iteration Budget Gate.
- The correction path for an `--impact` grade judged at bump time.
- Touches only the topmost entry's bump list - never `VERSION`, never any other part of `CHANGES.md`.
- A write is not idempotent against a changed list: after a first success, the same indices may name different bumps.

**SEE ALSO**

- `wikitool version bump` - sets the grade in the first place
- `wikitool version release` - refuses without a summary above this list

#### `version release`

Fix the running candidate: strip `VERSION`'s `-beta.N` suffix and close its `CHANGES.md` entry.

**SYNOPSIS**

- `wikitool version release [--title "<...>"] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: No - `VERSION` then `CHANGES.md`
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool version release --dry-run`
- `tools/wikitool version release --title "Command records rewritten for agents"`

**EXIT STATUS**

- 0    success
- 1    `VERSION` is already a release - there is no running candidate to fix
- 1    `VERSION` or `CHANGES.md` is missing, or `VERSION` and the changelog's newest entry name different versions
- 1    Two or more bumps and no summary paragraph above the changesets

**ON FAILURE**

- `VERSION` is already a release - there is no running candidate to fix -> After an uncertain run this means it already ran; otherwise there is nothing to release
- `VERSION` or `CHANGES.md` is missing, or `VERSION` and the changelog's newest entry name different versions -> Fix whichever is wrong, then retry
- Two or more bumps and no summary paragraph above the changesets -> Write a short summary paragraph right below the bump list, then retry

**NEVER**

- Never retry after an uncertain outcome without reading `VERSION` first - a release-shaped `VERSION` means it already ran.

**NOTES**

- Strips `VERSION`'s `-beta.N` suffix - the candidate's base becomes the release - and closes the candidate's `CHANGES.md` entry.
- Without `--title` the heading keeps whichever bump last set it; `--title` replaces it - the normal case for a candidate that collected several bumps, whose entry wants a summarising heading rather than the most recent one.
- Leaves the entry's machine-managed bump list untouched, as the record of what happened.
- From two bumps on, requires a summary paragraph (at least 200 non-whitespace characters) between the bump list and the first `### <bump title>` changeset heading. A candidate with exactly one bump is exempt, since there its own changeset already is the summary. `--dry-run` runs this check too.
- Commits nothing and pushes nothing. The following `publish` moves `VERSION` onto `main`, which `release.yml` reacts to.
- Not idempotent: a second run fails once the suffix is gone.

**SEE ALSO**

- `wikitool version bump` - opens and continues the candidate
- `wikitool version regrade` - shows the bump list the summary sits under
- `wikitool publish` - moves the released `VERSION` onto `main`

### Content migrations

#### `migrate list`

List every migration document under `instructions/migrations/`.

**SYNOPSIS**

- `wikitool migrate list [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool migrate list`

**EXIT STATUS**

- 0    success

**NOTES**

- 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**.

**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]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool migrate status`
- `tools/wikitool migrate status --json`

**EXIT STATUS**

- 0    success
- 1    `.wikitool-kb.json` is missing - the content version is undeclared
- 1    `VERSION` is unreadable

**ON FAILURE**

- `.wikitool-kb.json` is missing - the content version is undeclared -> Run `migrate baseline <version>` once, then retry
- `VERSION` is unreadable -> Fix `VERSION`, then retry

**NOTES**

- 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.

**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]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXAMPLES**

- `tools/wikitool migrate verify --from HEAD`
- `tools/wikitool migrate verify --from HEAD --path kb/concepts --expect-body-change`

**EXIT STATUS**

- 0    success
- 1    Only with `--fail-on-error`: an invariant changed
- 1    `--from` is not a revision in this repository

**ON FAILURE**

- Only with `--fail-on-error`: an invariant changed -> Act on the findings - exit 1 here means "act on the findings", not "the tool is broken". A finding names a page and what changed on it; it is never fixed by re-running
- `--from` is not a revision in this repository -> Fix the revision and retry

**NEVER**

- Never re-run to make a finding go away - fix the page it names.

**NOTES**

- 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.

**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]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: Yes - single file write
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool migrate done 7.0.0 --pages 42 --dry-run`
- `tools/wikitool migrate done 7.0.0 --pages 42`

**EXIT STATUS**

- 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

**ON FAILURE**

- Unknown version, no `.wikitool-kb.json`, or nothing outstanding -> Check `migrate status`, fix the argument, then retry once
- A *required* version that is not the next link in the chain -> Run `migrate status` and apply the migrations in the order it prints

**NEVER**

- Never force the order of required migrations.
- Never hand-edit `.wikitool-kb.json` to advance the version.

**NOTES**

- 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.

**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]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: Yes - single file write
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool migrate baseline 6.2.0`

**EXIT STATUS**

- 0    success
- 1    Unparseable version
- 1    A declaration already exists and `--force` was not passed

**ON FAILURE**

- Unparseable version -> Fix the version and retry
- A declaration already exists and `--force` was not passed -> It is almost always `migrate done` that was wanted

**NEVER**

- Never use `--force` to advance the version past a migration - that is `migrate done`.

**NOTES**

- 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.

**SEE ALSO**

- `wikitool migrate done` - advances the version after a migration
- `wikitool migrate status` - what is owed from the declared version

### Private instances

#### `upstream merge`

Take a stack update into a private instance's branch, machinery only.

**SYNOPSIS**

- `wikitool upstream merge [--remote upstream] [--branch main] [--no-fetch]`

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: **No** - can leave an open, uncommitted merge behind on refusal after fetching
- budget: counted
- network: no

**EXIT STATUS**

- 0    success
- 1    Dirty working tree, a merge already in progress, the remote does not resolve, git refused to open the merge at all (unrelated histories), or a real conflict remains in `tools/`/`types/`/`instructions/` after the content stages and stack-owned paths were restored

**ON FAILURE**

- Dirty working tree, a merge already in progress, the remote does not resolve, git refused to open the merge at all (unrelated histories), or a real conflict remains in `tools/`/`types/`/`instructions/` after the content stages and stack-owned paths were restored -> **Not idempotent, and not safe to retry unchanged.** For a dirty tree or an in-progress merge: fix the named precondition and retry once. For a real conflict: **do not retry, do not force** - resolve the named paths by hand (take the upstream side, or re-file the local change as an issue against the public repo per `instructions/private-instance.md`) and either `git commit --no-edit` yourself or `git merge --abort`. If the postcheck after commit finds a leak, the merge commit already exists and is **not** rolled back automatically - inspect it by hand; this is a bug report, not a retry

**NOTES**

The code procedure behind `instructions/private-instance.md` § "Taking a stack update". Refuses on a dirty working tree, a merge already in progress, or a remote that does not resolve; WARNs (does not block) when `.wikitool-remotes.json` is absent, pointing at the setup step that arms it. Fetches `<remote>/<branch>` (unless `--no-fetch`) and reports "already up to date" if nothing new exists. Otherwise opens `git merge --no-commit --no-ff <remote>/<branch>` - and stops, untouched, if git refused to open a merge at all (unrelated histories), since without a `MERGE_HEAD` every stack path would read as "the upstream deleted it". Then forces every content stage (`kb/`, `raw/`, `work/`, `reports/`) back to the local side by removing **only the paths tracked in either tree** and checking `HEAD`'s back out - never the stage directory wholesale, because `reports/` is gitignored apart from its contract and holds local, non-recomputable data (telemetry traces `eval score` reads, saved eval and lint reports) that no merge has business deleting. Then restores from the upstream side exactly the paths `chemenu.ownership.is_stack_owned` recognises as machinery (`<stage>/CONTRACT.md`, and anything ending `.template` under a content stage) - including a deletion, if the upstream removed one. A real conflict left in `tools/`, `types/` or `instructions/` after that leaves the merge open, uncommitted, and exits 1 rather than guessing. Commits with `git commit --no-edit`, then re-checks the resulting range with the same logic as `upstream verify`; a finding there is a loud, uncommitted-nothing-rolled-back error, because the merge commit already exists and needs a human's eyes, not an automatic repair. Never pushes. Not idempotent - see the tool error contract below

#### `upstream verify`

Compare two revisions: did anything under a content stage change except through a stack-owned path?

**SYNOPSIS**

- `wikitool upstream verify --since <rev> [--until HEAD]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: no

**EXIT STATUS**

- 0    success
- 1    A leak was found (content changed under a content stage through a path that is not stack-owned), or `--since`/`--until` is not a revision in this repository

**ON FAILURE**

- A leak was found (content changed under a content stage through a path that is not stack-owned), or `--since`/`--until` is not a revision in this repository -> A finding is not fixed by re-running - it names the paths that leaked. Fix the revision argument and retry for the second case

**NOTES**

Shares its check with `upstream merge`'s own postcheck, so a hand-resolved merge conflict, or a `dist upgrade`, can be verified the same way. Exit 1 with the offending paths if anything leaked; otherwise reports which stack-owned paths legitimately moved. Read-only and exempt from the Iteration Budget Gate, like `migrate verify`

### Instance health

#### `doctor`

Check that this instance is correctly configured.

**SYNOPSIS**

- `wikitool doctor [--json]`

**PROPERTIES**

- effect: read
- idempotent: yes
- atomic: Read-only
- budget: exempt
- network: yes

**EXIT STATUS**

- 0    success
- 1    At least one check reported `FAIL` (a `WARN`, e.g. no remote or no `WIKITOOL_SESSION_ID`, does not exit 1)

**ON FAILURE**

- At least one check reported `FAIL` (a `WARN`, e.g. no remote or no `WIKITOOL_SESSION_ID`, does not exit 1) -> Each finding names its own fix command; re-run after applying it

**NOTES**

Dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, kb/raw/reports/work/instructions structure, personalization (`USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`, since a renamed template is not a filled one), the KB conventions (`kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three, because `xref`/`cite` write out of it), the environment note (`ENVIRONMENT.md` - optional, so absent is `OK`; a still-templated one is a `WARN`), generated files, whether the MCP `submit` tool is armed (`.wikitool-upload.json` present/absent/malformed, its limits, and how many submissions are waiting in `mcp-upload/` - absent is `OK` and means the write path does not exist at all, malformed is the one `FAIL` here, since a broken opt-in must not silently disable the limits it exists to enforce), the task-tracker provider (`.wikitool-tasks.json` present/absent/malformed - absent is `OK` and means no tracker is configured, malformed is `FAIL` for the same reason the upload opt-in is; for a configured `superproductivity` provider, also its configured `access` path's own state - `access: "api"` reports whether its local REST API answers `GET /health` right now, `access: "snapshot"` reports whether a backup file is ready; the *other* access path is never attempted and is not a finding - and neither ever `FAIL`s, an app that is simply not running is not a fault; for a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - also never a `FAIL`, only a broken config block is), the session id source (`OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare parent-pid fallback - see `chemenu.session`), and telemetry state (on/off, why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session count/byte total against both caps; never `FAIL`, see `EVALS.md`). Read-only, exit 1 only on a `FAIL` (a missing remote, session id, or `VERSION` is a `WARN`, not a fault). Exempt from the Iteration Budget Gate
<!-- /wikitool:commands -->
## Design notes

- All commands operate on the real repo, so they can be run from any working
  directory. The root is resolved by precedence - an explicit argument, then
  `$CHEMENU_ROOT`, then a walk up from the package's own location - and the
  walk-up is the default, so `tools/wikitool` with no variable set behaves
  exactly as it always has. Nothing under the root is bound at import time:
  `KB_DIR`, `RAW_DIR` and the rest follow whatever `ROOT` currently is, which
  is what makes the half-repointed state (a moved `ROOT` with a stale `KB_DIR`)
  unconstructible rather than merely discouraged.
- **The library boundary.** `chemenu.api.Corpus` is the in-process entry point:
  it takes a corpus root, returns the same structures the `--json` forms print,
  and raises `ChemenuError` where the CLI prints `ERROR` and exits 1. It is
  read-only *structurally* - nothing under `chemenu.commands` is imported from
  it, so `new`, `publish` and the rest are not reachable, rather than filtered.
  The cores it calls (`search/service.py`, `lint_core.py`, `types_core.py`)
  import no `typer` and no `rich`; the modules under `commands/` are the
  terminal adapters over them. A second consumer is therefore a second adapter,
  not a second implementation.
- **The MCP server** (`chemenu/mcp/`) is that second adapter: `search`,
  `types`, `describe_type`, `lint` and `status` over `chemenu.api`, on `stdio`
  or `streamable-http`. Its dependency is optional and lives in
  `requirements-mcp.txt`, so a CLI-only instance does not install it. Five of
  its tools are structurally read-only - nothing under
  `commands/` is importable from the server, so `new`/`touch`/`xref`/`cite`/
  `publish`/`migrate` are unreachable rather than filtered - and every
  response carries the commit it was computed from. The one exception is
  `submit` (opt-in via `.wikitool-upload.json` - absent means the
  tool is not registered at all): the server may write, but by a **positive
  list** rather than an absence - `chemenu.upload._write_atomic_within`
  resolves every target and refuses anything outside `mcp-upload/`, the one
  directory the process may touch. The *reviewer* commands that move a
  submission out of that quarantine (`upload accept`/`upload reject`) keep
  the original absence property: they live under `commands/`, not reachable
  from the server, same as every other write command. Running the server,
  and keeping its checkout current, is
  [instructions/mcp-read-server.md](../instructions/mcp-read-server.md);
  reviewing a submission is
  [instructions/ingest-queue.md](../instructions/ingest-queue.md).
  Authentication and rate limiting are middleware in front of the process,
  not code here; the Iteration Budget Gate is deliberately not applied to any
  of the six tools, because it bounds an agent session rather than a user.
- `new`/`xref`/`log append` only produce structurally-correct frontmatter and
  body skeletons/edits - the prose (Description, Summary, judgment calls
  about relationships) is still written by the LLM afterwards.
- `lint` only reports what's mechanically verifiable. Contradictions, staleness
  judgment, and "what's worth writing next" remain the LLM's job; `lint`
  produces a markdown skeleton with a "Semantic Review" section for that.
- **Iteration Budget Gate / Loop-Breaker** (see the root `AGENTS.md` "Gates"
  section): every invocation is recorded and checked in `main()` (`cli.py`)
  before Typer dispatches to any subcommand, so it applies uniformly without
  each command needing its own opt-in. State lives in the gitignored
  `tools/.wikitool_session/budget.json`, keyed by `chemenu.session`'s fallback
  chain (`WIKITOOL_SESSION_ID`, else a registered harness session variable,
  else the caller's parent process id), so a new terminal/session starts with
  a clean budget - and a bucket whose recorded origin no longer matches the
  current one starts a fresh count rather than inheriting a stranger's.
  Default ceiling: 60 calls/session, or 3
  identical calls in a row (whichever trips first). A call that left through
  `_util.fail()` - a rejected argument, or a read-only check reporting
  findings - is refunded: it declined instead of acting, and the contract's own
  answer to a rejected argument is "retry once", which would otherwise cost two
  slots for one operation. The call stays in the loop-breaker's history. `budget status` is exempt
  so the situation stays reportable after the gate trips; `budget reset` is
  not, and additionally requires `--yes`. Bypass only with
  `--override-budget`, and only after explicit human approval - never on the
  agent's own initiative.

## Tests

```bash
cd tools
.venv/bin/pip install pytest pytest-cov   # one time; pytest-cov is optional
.venv/bin/python -m pytest -q             # add --cov for a coverage report
```

Neither is in `requirements.txt`, and `pytest-cov` is CI-only by intent - see
[README.md](README.md#tests) and [EVALS.md](../EVALS.md).

## Maintenance schedule

Run by the LLM through the skills, on this cadence:

| Task | Frequency | Command |
|------|-----------|---------|
| Log append | Every operation | `log append --op <type> --title "..."` |
| Index rebuild | Every page change | `index rebuild` |
| Provenance index rebuild | After any source/citation change | `sources rebuild-index` |
| Publish | After any change worth persisting | `publish --message "<op>: <desc>"` |
| Full lint | Every 10 sources (checked via `log status`), or on request | `lint`, then carry the semantic findings into `kb/log.md` via `log append --op lint` - the report itself is gitignored |
| Raw coverage check | Every 10 sources | `sources coverage` |
| Docs/instruction verification | After changing the CLI, a contract, or an instruction | `docs verify`, `instructions verify` |
| Budget check | Any time a session feels long | `budget status` |
| Retention review | Every 90 days | Manual |

## Future considerations (not implemented)

- A pre-commit hook running `wikitool lint --fail-on-error` before every
  `wikitool publish`. CI already runs it on every push
  (`.gitea/workflows/ci.yml`), which catches it after the fact rather than
  before.