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)
  - [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 is the preflight ([`instructions/preflight.md`](../instructions/preflight.md)),
from the repo root:

```bash
tools/preflight.sh
```

From PowerShell 7 on Windows, the twin: `pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1`.

Until it has passed, every `tools/wikitool` call exits 42 and names it.

A release also carries both scripts as assets (`preflight.sh`, `preflight.ps1`) for the very
first install, before there is a tree: run from a folder with no `tools/prerequisites.txt` beside
them, they download and verify the release tarball, unpack it into `chemenu/` next to themselves
(or `--into <path>`), and run the preflight inside the unpacked tree.

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

A call that ends through `_util.fail()` (exit 1) prints its `ERROR` line to stdout as before, then
its record's ON FAILURE reaction(s) to stderr, in the same `<cause> -> <reaction>` form `-h` prints
- so the reaction is in front of the caller without a second `-h` call. A record with no exit-1
cause of its own falls back to a bare `see: wikitool <cmd> -h` pointer.

## 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 fetch             write non-idempotent budget:counted              exit:0,1    Capture a web page the user names into `incoming/`: the HTML as received plus a derived text, for `raw accept` to promote.
raw pending           read  idempotent     budget:counted              exit:0      List what waits in `incoming/`, oldest first, and name the entry an ingest without an argument takes next.
raw accept            write non-idempotent budget:counted              exit:0,1    Promote one or more files, or one folder, 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 prerequisites    write idempotent     budget:counted              exit:0,1    Regenerate `INSTALL.md`'s prerequisites lists from `tools/prerequisites.txt`.
docs contract         write idempotent     budget:counted              exit:0,1    Regenerate `tools/CONTRACT.md`'s `<!-- wikitool:commands -->` region.
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 adopt            write idempotent     budget:counted              exit:0,1    Take shipped templates as this instance's own: copy each to its unsuffixed name.
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`.
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` - `<subdir>` from `entity_type` via the type-spec's `layout:`
- `wikitool new concept --name "<Name>" --set concept_type=<t> ...` - Writes `kb/concepts/<subdir>/<Name>.md` - `<subdir>` from `concept_type` via the type-spec's `layout:`
- `wikitool new source --name "<Name>" --set source_type=<t> --set raw_files=raw/notes/x.md,raw/notes/y.md --set fidelity=<f> --set authority=<a> [--set source_url=<URL>] [--set entities=A,B] [--set concepts=C,D]` - Writes `kb/sources/<subdir>/Source - <Name>.md` (prefix added automatically; `<subdir>` from `source_type` via the type-spec's `layout:`) 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    The title is not a valid file name (forbidden character, control character, reserved name such as `CON` or `Index`, trailing dot or space, empty), collides with another page by case or Unicode normalization, the target file already exists, or the target path is over the 160-character path budget
- 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
- The title is not a valid file name (forbidden character, control character, reserved name such as `CON` or `Index`, trailing dot or space, empty), collides with another page by case or Unicode normalization, the target file already exists, or the target path is over the 160-character path budget -> Not transient - choose another (for the budget: a shorter) title and retry once. Nothing was created, and for `new project` no tracker project either
- 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**

- A title becomes a file name, so it must be valid and unique on Windows and macOS as well as Linux, whichever platform runs the command and whichever root the type writes to. The rule is `kb/CONTRACT.md` § Titles are identifiers; it is checked on the full title, after `title_prefix`.
- The target's path below the instance root may be at most 160 characters, counted in UTF-16 code units the way Windows counts MAX_PATH, so a Windows checkout without long paths keeps working. A longer one is refused, for every root, naming the length and how much shorter it has to get.
- `new` never overwrites: a file already at the target - or one a case-insensitive file system would treat as the same file - is refused for every root, `instructions/` included.
- The type-spec drives everything: fields, directory (`base_dir`/`layout`), title prefix, and template. `types list`/`types describe` show what a type requires.
- The body skeleton is `types/<type>.<value>.md` when that file exists, `<value>` being the page's subtype field value (e.g. `types/entity.person.md` for `entity_type=person`) - it replaces the type-spec's `## Template` block whole. Without such a file, and for a type with no subtype field, the `## Template` block is used as before.
- 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    `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken
- 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
- `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken -> Not transient - fix the path or unset the variable
- 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.
- The tracker configuration is read from `.wikitool-tasks.json`, or from the file `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
- 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
- 1    `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken

**ON FAILURE**

- No `.wikitool-tasks.json` - no tracker configured -> Not transient - configure a tracker first, then retry once
- `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken -> Not transient - fix the path or unset the variable

**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    `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken
- 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
- `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken -> Not transient - fix the path or unset the variable
- 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.
- The tracker configuration is read from `.wikitool-tasks.json`, or from the file `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
- 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 - also by a page that differs only in case or Unicode normalization, or by a file in the page's directory - or is not a valid file name, or would put the page's path over the path budget (see `kb/CONTRACT.md` § Titles are identifiers)
- 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 - also by a page that differs only in case or Unicode normalization, or by a file in the page's directory - or is not a valid file name, or would put the page's path over the path budget (see `kb/CONTRACT.md` § Titles are identifiers) -> Choose another, or a shorter, title and retry once. Checked under `--dry-run` too
- 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.
- Only `--to` is checked against the title rule and the path budget (160 UTF-16 code units for the whole path below the instance root). A page whose current title breaks either (`lint`'s Unportable Titles and Long Paths) can always be renamed away from it, and a title that differs from the page's own only by case (`Foo` to `FOO`) is allowed.

**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 holds an entry with the same name, or one that differs only in case or Unicode normalization (a pre-existing duplicate-stem collision), or its path would be over the path budget - 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 holds an entry with the same name, or one that differs only in case or Unicode normalization (a pre-existing duplicate-stem collision), or its path would be over the path budget - refused rather than silently skipped -> Resolve the collision, or `wikitool rename` the page to a shorter title, 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>`.
- A destination whose path would be over the path budget (160 UTF-16 code units below the instance root) is refused, and `--reconcile` skips such a page and names it, as it does for an occupied destination - `wikitool rename` the page to a shorter title.
- `--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: Yes - a single write to A; B is never touched, and every refusal happens before it
- 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` is missing, not a readable file, or not valid UTF-8

**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` is missing, not a readable file, or not valid UTF-8 -> 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, wikilinks wrapped across a line break, 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.
- Unportable Titles is a hard finding, and hard at every `kb_version`: a page whose title is not a valid file name on Windows and macOS (forbidden character, reserved name, trailing dot or space), or that collides with another page by case or Unicode normalization. `wikitool rename` is the fix.
- Wrapped Wikilinks is a hard finding: a `[[...]]` with a line break inside it. The link graph reads it as the title it folds to (the break and its indentation become one space), so it is not also a broken link unless that title is missing; the fix is to put it back on one line.
- Broken Anchors is advisory: a `[[Page#Section]]` whose page exists but has no heading the anchor names (any level, compared without case, inline-code backticks or extra whitespace; every segment of a nested `[[Page#A#B]]`). The link still reaches the page, so nothing else reports it - typically a section that was promoted to a page of its own or renamed. A missing page is Broken Wikilinks instead.
- 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: Long Paths - a file under `kb/` or `raw/` whose path below the instance root is over 160 UTF-16 code units, the budget that keeps a Windows checkout without long paths working. Reported as `{path, length}`; a corpus over the budget breaks no lint run. `wikitool rename` is the fix for a page.
- Advisory only: quote-limit overages (>2 blockquotes/page).
- Advisory only: Unfilled Template Sections - a page with at least one `##` section whose non-blank lines are all template placeholders (content starting with `TODO`, after an optional list marker, checkbox, table cell or bold field label), reported as `{page, sections}`. Code, generated regions and footnote definitions do not count; an empty section, or one placeholder beside written lines, is no finding. Writing the section from the page's sources or retiring the page is the fix - not a mechanical one.
- 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 rename` - fixes Unportable Titles and, for a page, Long Paths
- `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    `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken
- 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
- `WIKITOOL_TASKS_CONFIG` names a file that does not exist or is broken -> Not transient - fix the path or unset the variable
- 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 the tracker configuration, never from the schema.
- The tracker configuration is read from `.wikitool-tasks.json`, or from the file `WIKITOOL_TASKS_CONFIG` names when that variable is set (so one checkout can be run against several trackers in turn). A set variable that names no file is an error, never "no tracker configured".
- 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 fetch`

Capture a web page the user names into `incoming/`: the HTML as received plus a derived text, for `raw accept` to promote.

**SYNOPSIS**

- `wikitool raw fetch <url> [--name <stem>]` - Fetch the page and write `incoming/<stem>.html` and `incoming/<stem>.md`
- `wikitool raw fetch --html incoming/<file>.html --url <url>` - Derive the `.md` from a page a human saved from their browser - no network access

**PROPERTIES**

- effect: write
- idempotent: no
- atomic: Yes for what it leaves behind - one or two new files in `incoming/`, created exclusively; a failure on the second removes the first
- budget: counted
- network: yes

**EXAMPLES**

- `tools/wikitool raw fetch https://example.org/blog/post`
- `tools/wikitool raw fetch https://example.org/ --name example-start`
- `tools/wikitool raw fetch --html incoming/post.html --url https://example.org/blog/post`

**EXIT STATUS**

- 0    success
- 1    The URL is not `http`/`https` (also after a redirect), or neither or both of `<url>` and `--html` were given
- 1    A target file already exists in `incoming/`
- 1    The server answered with an HTTP error, could not be reached, took longer than 30 s, or sent more than 25 MiB
- 1    raw fetch --html: `--url` is missing, the file is not directly in `incoming/` or does not exist, or `incoming/<stem>.md` already exists

**ON FAILURE**

- The URL is not `http`/`https` (also after a redirect), or neither or both of `<url>` and `--html` were given -> Fix the call and retry once. A local file is dropped into `incoming/` by hand, not fetched
- A target file already exists in `incoming/` -> Nothing was written or overwritten. Accept or remove what is there, or pass `--name <stem>`, then retry once
- The server answered with an HTTP error, could not be reached, took longer than 30 s, or sent more than 25 MiB -> Nothing was written. An HTTP 4xx is not fixed by retrying - check the URL with the user; for a paywall or login, save the page in a browser and use `--html`. An unreachable host or a timeout may be retried once
- raw fetch --html: `--url` is missing, the file is not directly in `incoming/` or does not exist, or `incoming/<stem>.md` already exists -> Fix the named argument and retry once - nothing was written. A saved page inside a subdirectory of `incoming/` is moved up into `incoming/` first

**NEVER**

- Never fetch a URL that a raw file or a fetched page contains - only one the user named in this session.
- Never edit the header or the derived text by hand; a better derivation is a new fetch.

**NOTES**

- Writes into `incoming/` only, never into `raw/`: `raw accept` promotes both files afterwards, in one call, as one bundle under `raw/<YYYY>/<MM>/<stem>/`.
- The `.html` holds the response body byte for byte. The `.md` starts with a fixed header block (`fetched_by`, `url`, `final_url`, `retrieved`, `http_status`, `content_type`, `charset`, `title`, `derived_from`) followed by the derived text.
- Character set, in this order: byte-order mark, the HTTP `Content-Type` charset, a `<meta>` declaration in the first 4 KiB, UTF-8. Undecodable bytes are replaced with U+FFFD and reported; the header names the charset and where it came from.
- Derived text: the content root is `<main>`, else the single `<article>`, else `<body>`; `script`, `style`, `noscript`, `nav`, `header`, `footer`, `aside`, `form`, `template` and `svg` are dropped below it. Headings, lists, code, tables and links (made absolute) become Markdown. The same bytes always give the same text.
- The stem is the URL's last path segment without its extension, else its host name - ASCII, lowercase, `-`-separated, at most 60 characters; `--name` overrides it.
- A `text/plain` or `text/markdown` response is stored as received as `.txt`/`.md`; any other non-HTML response (PDF, image, ...) as received under the extension of its content type. Neither gets a derived file or a header.
- Only `http`/`https`, on every redirect hop too. 30 s for the whole transfer, 25 MiB at most. No cookies, no JavaScript: a derived text under 200 characters is written, with a warning to read it before accepting.
- `--html` derives the `.md` beside a page saved to `incoming/` from a logged-in browser - the way past a paywall or a script-rendered page. Its header carries `derived` (when the text was derived) instead of `retrieved`, `final_url`, `http_status` and `content_type`, and the `.html` is left untouched.
- Success prints the `raw accept` line for the written files and the `source_url` for the source page.

**SEE ALSO**

- `raw/CONTRACT.md` "Getting a URL in: `raw fetch`" - the rules and why
- `wikitool raw accept` - promotes the written files into `raw/`
- `instructions/wiki-ingest/SKILL.md` - where a URL to ingest starts

#### `raw pending`

List what waits in `incoming/`, oldest first, and name the entry an ingest without an argument takes next.

**SYNOPSIS**

- `wikitool raw pending [--json]`

**PROPERTIES**

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

**EXAMPLES**

- `tools/wikitool raw pending`
- `tools/wikitool raw pending --json`

**EXIT STATUS**

- 0    success

**NOTES**

- A candidate is a top-level entry of `incoming/`: a single `file`, a `bundle` of top-level files sharing a stem (a `raw fetch` pair, a PDF and its converted text), or a `folder` with every file below it. Dotfiles, empty directories and their contents are none; `mcp-upload/` is outside `incoming/` and never listed.
- Order: oldest first by modification time. A bundle or folder counts as new as its newest file; a tie goes by name. The mtime is when a document last changed only if it was copied with its timestamps kept (`cp -p`, `rsync -a`, an unpacked archive) - for a download or a `raw fetch` it is merely when it was dropped.
- Each candidate shows its path(s), kind, file count and mtime, and whether `raw accept` would take it as it stands - the same checks, minus `--fidelity`/`--authority`. One it would refuse is listed with the reason and skipped: it needs a human.
- The default is the first candidate `raw accept` would take, and the output names it.
- `--json` prints the same candidates in the same order: `kind`, `paths`, `files`, `mtime`, `acceptable`, `reason`, `default`.
- Reads directory listings and `lstat` only, never a file's content; an empty `incoming/` is exit 0 with nothing to do.

**SEE ALSO**

- `wikitool raw accept` - promotes the chosen candidate
- `instructions/wiki-ingest/SKILL.md` - ingest without an argument starts here
- `raw/CONTRACT.md` "Getting a file in: incoming/" - candidates and order, and why

#### `raw accept`

Promote one or more files, or one folder, 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 incoming/<folder> --fidelity <v> --authority <v> [--dry-run]` - Promote a whole folder as one source, its structure kept, into `raw/<YYYY>/<MM>/<folder>/`
- `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. With a folder: No - one move per file, then one `rmdir` per emptied directory; a half-accepted folder is not resumed. `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/projekt-x --fidelity verbatim --authority reporting`
- `tools/wikitool raw accept incoming/cluster.md --replaces raw/documents/cluster.md`

**EXIT STATUS**

- 0    success
- 1    raw accept: A file does not exist or is not directly in `incoming/`; two files in one call share a filename; a target path already exists; or a target path would be over the path budget (160 UTF-16 code units below the instance root)
- 1    raw accept incoming/<folder>: The folder is not directly in `incoming/`, is combined with another argument, `--page` or `--replaces`, holds no file, or holds a hidden entry, a symlink or a special file; a target path is over the budget; or the folder name is already occupied under `raw/`
- 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 directly in `incoming/`, 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 or is not directly in `incoming/`; two files in one call share a filename; a target path already exists; or a target path would be over the path budget (160 UTF-16 code units below the instance root) -> Fix the named argument and retry once. A file inside a subdirectory of `incoming/` is accepted with its whole folder (`raw accept incoming/<folder>`) or moved up into `incoming/` first. For a path over the budget, rename the file in `incoming/` to something shorter - the refusal comes before anything moves, so `incoming/` and `raw/` are unchanged
- raw accept incoming/<folder>: The folder is not directly in `incoming/`, is combined with another argument, `--page` or `--replaces`, holds no file, or holds a hidden entry, a symlink or a special file; a target path is over the budget; or the folder name is already occupied under `raw/` -> Nothing moved. Fix what the message names and retry once; for an occupied name, rename the folder in `incoming/` - there is no `--replaces` for a folder
- 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 directly in `incoming/`, 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 file argument must sit directly in `incoming/`; a file inside a subdirectory is refused, since a subdirectory is a source of its own.
- A folder argument (`incoming/<folder>`) is one source: every file below it moves to `raw/<YYYY>/<MM>/<folder>/` at the same relative path, and the directories left empty are removed - `incoming/<folder>` no longer exists afterwards. The folder name is the bundle name; two `README.md` in different subfolders are no conflict.
- A folder is accepted alone - no other argument, no `--page`, no `--replaces` - with one `--fidelity`/`--authority` pair for all of it. It is refused, before anything moves, if it is empty, or if a hidden entry (name starting with `.`), a symlink or a special file sits anywhere below it; the refusal names each one.
- 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 raw pending` - what is waiting in `incoming/`, and which entry is next
- `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: yes
- 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 - reported and skipped, not a failure
- 0    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.
- Three messages for a fetch that fails: no remote of that name, a remote that answers but has no such branch yet (a new, empty repository), and a remote that cannot be reached. All three exit 0 here; `publish` stops on the first and the last.
- 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. Every gate runs before staging, except on the one retry of a rejected push, where the rebase-review gate can exit 42 after the commit: nothing is pushed, and the re-run with `--confirm-rebase` pushes that commit
- budget: counted
- network: yes
- 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    No `--no-push`, and the remote is not configured or cannot be reached; nothing was committed
- 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
- No `--no-push`, and the remote is not configured or cannot be reached; nothing was committed -> Show the message to the user and ask whether to commit locally with `--no-push`. Never push by hand - the next `publish` that reaches the remote sends that commit
- `--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.
- Without `--no-push`, a remote that is not configured or cannot be reached ends the call with exit 1 at the reconcile - before the gate, `git add` and the commit, and also on a clean tree. Nothing is committed, the index and the working tree are unchanged, and the message names `--no-push` as the way to a local commit. The next `publish` that reaches the remote pushes that commit along with whatever is new. A remote that answers but has no `<branch>` yet (a new, empty repository) is not this case: the first publish of an instance commits and pushes as before.
- 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 rejected push that finds the remote unreachable on its one retry reports the original push error.
- 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 list is what the commit will hold: it is computed from a scratch copy of the index after `git add -A`, so a path that is staged as deleted and back in the working tree is not counted twice, and a rename counts as its old path deleted plus its new path added. The real index and the working tree are not touched, so a refused publish leaves both byte-identical.
- 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, the blob id of 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.
- Commit message: `--message`, then a `Files changed:` paragraph listing every committed path. When `--message` ends in a paragraph git reads as a trailer block (`Co-Authored-By:` and the like), that block stays the last paragraph and the list goes in front of it, since git reads trailers from the last paragraph only. `git interpret-trailers` decides whether there is such a block, and the list moves only when git reads the same trailers from the result; otherwise it is appended at the end. `--message` is not part of any gate token.
- 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 subtype template `types/<type>.<value>.md` has no type-spec with a `subtype_field:` beside it, names a value outside that field's enum, or carries frontmatter
- 1    A shipped `.md`/`.template` cites an issue number
- 1    A 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
- 1    An `INSTALL.md` prerequisites region is stale
- 1    An `INSTALL.md` prerequisites region is missing, or names a platform no tool has
- 1    A setup question is marked in one of `instructions/setup-instance.md` and `INSTALL.md` but not the other

**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 subtype template `types/<type>.<value>.md` has no type-spec with a `subtype_field:` beside it, names a value outside that field's enum, or carries frontmatter -> Rename the file to the type and value it was meant for, delete it, or remove its frontmatter block
- A shipped `.md`/`.template` cites an issue number -> Say what was decided instead of pointing at where, or move the pointer behind a `<!-- dist:strip-start/end -->` block
- A 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
- An `INSTALL.md` prerequisites region is stale -> Run `docs prerequisites --apply`, then re-run
- An `INSTALL.md` prerequisites region is missing, or names a platform no tool has -> Add the marker pair where that list belongs (or remove the orphaned region and its introducing prose), then run `docs prerequisites --apply`
- A setup question is marked in one of `instructions/setup-instance.md` and `INSTALL.md` but not the other -> Describe the question for the human in `INSTALL.md` with the same marker, or remove the bullet for a question no longer asked

**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`; every subtype template `types/<type>.<value>.md` (any `<value>` but `guidance`) sits beside a type-spec declaring `subtype_field:`, names a value that field's schema enum allows, and carries no frontmatter; no pre-migration `type: entity` blocks are left in the contracts.
- `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.
- `INSTALL.md` carries one generated `<!-- wikitool:prerequisites -->` region per platform value of `tools/prerequisites.txt` (`prerequisites-<platform>` for a platform-specific one), each current; and the `<!-- setup-question: <key> -->` markers in `instructions/setup-instance.md` and `INSTALL.md` name the same set of keys, so a question the agent asks is never one the human guide leaves out, nor the reverse.
- Read-only.

**SEE ALSO**

- `wikitool docs toc` - regenerates tables of contents
- `wikitool docs contract` - regenerates the commands region
- `wikitool docs prerequisites` - regenerates `INSTALL.md`'s prerequisites lists
- `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`, the human docs (`README.md`, `CHANGES.md`, `EVALS.md`, `INSTALL.md`, `tools/README.md`), and every subtype template `types/<type>.<value>.md` - `new` copies it into a page, so it never carries a region whatever its length.
- 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 prerequisites`

Regenerate `INSTALL.md`'s prerequisites lists from `tools/prerequisites.txt`.

**SYNOPSIS**

- `wikitool docs prerequisites [--apply]`

**PROPERTIES**

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

**EXAMPLES**

- `tools/wikitool docs prerequisites`
- `tools/wikitool docs prerequisites --apply`

**EXIT STATUS**

- 0    success
- 1    `INSTALL.md` is missing, or lacks a region the manifest calls for

**ON FAILURE**

- `INSTALL.md` is missing, or lacks a region the manifest calls for -> Not transient - add the marker pair the message names where that list belongs (restore the file if it is gone), then retry

**NEVER**

- Never hand-edit a prerequisites region - change `tools/prerequisites.txt` and re-run this.

**NOTES**

- Rewrites each `<!-- wikitool:prerequisites -->` region in `INSTALL.md` (tools every platform needs) and `<!-- wikitool:prerequisites-<platform> -->` region (tools only that platform needs) from the manifest: one list item per tool, its label and minimum version. The manifest's reason field stays out - it is English prose, and the region sits in a document that need not be.
- Never places a region: where a list belongs in the human guide is that guide's own decision. A region the manifest calls for but the file lacks is an error naming the marker pair to add.
- Dry-run by default (says whether the file would change); `--apply` writes.
- `docs verify` checks the result stays current.

**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
- 1    `tools/CONTRACT.md` is missing

**ON FAILURE**

- `tools/CONTRACT.md` is missing -> Not transient - restore the file, which carries hand-written prose around the region this command does not generate, then retry

**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, their schemas and their subtype templates `types/<type>.<value>.md` re-keyed as `.template`, the stack's own verbatim), `docs/` verbatim, `tools/` (no venv/caches, and not the dev-only test suite `tools/chemenu/tests/` with its `pytest.ini`/`.coveragerc`), 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`/`types/<page-type>.<value>.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.
- A build and test tool: every release is an export packed as a tarball, and an instance is installed from such a release, never from an export directly.
- One-way: no command reconstructs a distributed instance into a dev instance - work on the stack in a clone of the origin repo.
- `--dry-run` lists every file it would write, and writes nothing.

**SEE ALSO**

- `instructions/setup-instance.md` - installs a release, which is this export as a tarball
- `wikitool dist upgrade` - applies a later export to an existing instance
- `wikitool version show` - reads the stamp this writes

#### `dist adopt`

Take shipped templates as this instance's own: copy each to its unsuffixed name.

**SYNOPSIS**

- `wikitool dist adopt [<template>...] [--dry-run]`

**PROPERTIES**

- effect: write
- idempotent: yes
- atomic: No - files are copied one by one; a re-run completes an interrupted one
- budget: counted
- network: no

**EXAMPLES**

- `tools/wikitool dist adopt`
- `tools/wikitool dist adopt types/project.md.template types/project.schema.yaml.template`
- `tools/wikitool dist adopt --dry-run`

**EXIT STATUS**

- 0    success
- 1    A named path does not exist, or is not a collection contract or page type-spec template

**ON FAILURE**

- A named path does not exist, or is not a collection contract or page type-spec template -> Not transient - name a template from the set in NOTES, or call it without a path

**NEVER**

- Never delete a target to make `dist adopt` replace it - a filled file is the instance's own work.

**NOTES**

- Copies `<name>.template` to `<name>` byte for byte; the template stays where it is, as the base the next `dist upgrade` compares against.
- Without a path: every `kb/<collection>/COLLECTION.md.template` and every `types/*.template` (the `root: kb` page type-specs, their schemas and their subtype templates).
- With paths: exactly those templates, each of which has to be one of the set above.
- Never overwrites: a target that already exists is reported as kept and left untouched.
- Not for `kb/CONVENTIONS.md.template` or the personalization templates - those carry a sentinel and are filled in, not copied.
- `--dry-run` lists what it would copy and keep, and writes nothing.

**SEE ALSO**

- `instructions/setup-instance.md` - adopts every template on a fresh instance
- `instructions/upgrade-instance.md` - adopts a template a release added
- `wikitool dist export` - re-keys these files as `.template` in the first place

#### `dist upgrade`

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

**SYNOPSIS**

- `wikitool dist upgrade (<source> | --latest [--expect <version>]) [--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: yes

**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`
- `tools/wikitool dist upgrade --latest --expect 8.0.0 --dry-run`

**EXIT STATUS**

- 0    success
- 0    The source's version equals the installed one - a no-op success
- 1    Both `<source>` and `--latest`, or neither; or `--expect` without `--latest`
- 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    `--latest`: the release feed cannot be reached, or answers with something that is not a release
- 1    `--latest --expect`: the feed's latest release is another version than the one expected; nothing was downloaded
- 1    `--latest`: the release publishes no archive or no `.sha256` under the expected name; nothing was downloaded
- 1    `--latest`: an asset download fails, or the archive fails its `.sha256`
- 1    `--latest`: the downloaded archive's `VERSION` is not the version the feed announced
- 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**

- Both `<source>` and `--latest`, or neither; or `--expect` without `--latest` -> Not transient - name exactly one source, and pass `--expect` only with `--latest`
- Local `VERSION` missing, or no local `.wikitool-release.json` with a `files` block -> Not transient - fix the named precondition and retry. A clone of the origin repo is a development checkout and takes no `dist upgrade` at all
- `.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
- `--latest`: the release feed cannot be reached, or answers with something that is not a release -> Transient - retry once; then report the URL from the message, or take the release page's archive by hand and pass it as `<source>`
- `--latest --expect`: the feed's latest release is another version than the one expected; nothing was downloaded -> Not transient - read `wikitool version notes` for the version the message names, then either expect that one or stop
- `--latest`: the release publishes no archive or no `.sha256` under the expected name; nothing was downloaded -> Not transient - the message lists the assets present and the release page; report it there rather than upgrading without the checksum
- `--latest`: an asset download fails, or the archive fails its `.sha256` -> Retry once; if it fails again, report the exact message - do not fall back to an unchecked archive
- `--latest`: the downloaded archive's `VERSION` is not the version the feed announced -> Not transient - an inconsistent release; report it against the release page
- 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**

- Exactly one of `<source>` and `--latest` names the release. `<source>` is an already-fetched export directory or `.tar.gz` release archive and touches no network: the 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.
- `--latest` asks the release feed (`update_url` of the local stamp, overridable with `$WIKITOOL_UPDATE_URL`; `$WIKITOOL_UPDATE_TOKEN` is sent along) which release is latest, checks that version - `--expect`, a downgrade, a pre-release without `--pre`, already installed - before any download, then downloads the archive and its `.sha256` into a scratch directory removed on every exit. The checksum is mandatory here (a release without one, or an archive that fails it, is an error, not a WARN) and the archive's own `VERSION` must equal the feed's version. The asset URLs are the feed's own `browser_download_url` values, and the token reaches an asset download only if it is on the feed's origin. The checksum protects against transfer errors, not against a feed that is itself compromised - authenticity is the trust in the feed's host.
- `--expect <version>` (only with `--latest`) pins the release the feed may announce: a different latest version is refused before anything is downloaded. Pass the version `wikitool version notes` was read for, in the dry run and in the real run alike.
- 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, re-creates it if it was locally deleted, and deletes it if the release no longer ships it. 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 no longer part of the release. Still unchanged since installation, it is deleted, as silently as an unchanged file is overwritten; changed since, it is locally changed like any other and needs one of the same answers - `--take-release` deletes it, `--keep-local` keeps it as the instance's own file, which no later upgrade reports again. Either way it is decided in this run: the new stamp no longer names the path. What the instance owns (`kb/log.md`, `CHANGES.md`, `.wikitool-kb.json`, ...) is never a candidate, and neither is any file the old stamp does not name.
- A directory left holding nothing - at most a `__pycache__/` of `*.pyc` - once those files are deleted is removed with them, up to but never including the instance root. `--prune` is accepted and ignored; it used to switch the deletion on.
- 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`. With `--latest` it still downloads and verifies the archive - that is the only way to classify - and removes it again.
- 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
- `wikitool version notes` - the notes of the release `--expect` should name
- `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 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`.
- The only command whose whole job is the network call - `version notes` reaches the same feed too, but only as a fallback on a distributed instance, and `dist upgrade --latest` asks it which release to download.
- Never reached implicitly from another command (`dist upgrade` asks only when passed `--latest`), 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

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

**EXAMPLES**

- `tools/wikitool doctor`
- `tools/wikitool doctor --json`

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

- Checks dependencies (Python, ripgrep), author resolution, stack version, git identity/branch/remote, published skills, the kb/raw/reports/work/instructions structure, and generated files.
- Tool paths (`tool-paths`): `.wikitool-tools.json` written by a preflight that finished, every tool `tools/prerequisites.txt` names for this platform recorded, and every recorded path still there - a `FAIL` otherwise, fixed by running `tools/preflight.sh` again (PowerShell 7: `tools/preflight.ps1`).
- Install folder (`install-dir`): on Windows with long paths off, a `FAIL` when the folder holding `tools/` is longer than `tools/prerequisites.txt` allows (95 characters) - the limit the preflight enforces before it sets anything up.
- PowerShell (`execution-policy`, `script-marks`; Windows only, `OK` elsewhere): a `FAIL` when the effective execution policy is `Restricted` or `AllSigned` - the line then says whether a group policy sets it, which only whoever administers the computer can change - and a `FAIL` when a script under `tools/` carries a Mark of the Web from the internet zone, which a browser download unpacked in Explorer leaves behind and `Invoke-WebRequest` plus `tar` do not. `tools/preflight.ps1` checks the same two things before it stops.
- Personalization: `USER.md`/`SOUL.md` present **and** filled - a file still carrying the template's sentinel is a `FAIL`.
- KB conventions: `kb/CONVENTIONS.md` present, unsentinelled, and naming all three tool-owned section headings - a `FAIL` on any of the three.
- Environment note: `ENVIRONMENT.md` is optional, so absent is `OK`; a still-templated one is a `WARN`.
- MCP `submit` tool: whether `.wikitool-upload.json` is present, absent or malformed, its limits, and how many submissions wait in `mcp-upload/`. Absent is `OK` and means the write path does not exist at all; malformed is a `FAIL`.
- Task tracker: `.wikitool-tasks.json` present, absent or malformed - absent is `OK` (no tracker configured), malformed is a `FAIL`. When `WIKITOOL_TASKS_CONFIG` is set, that file is read instead and the finding names it; a set variable that names no file is a `FAIL`, never `OK`.
- For a configured `superproductivity` provider, the configured `access` path's own state: `access: "api"` reports whether its local REST API answers `GET /health` with a ready renderer right now, `access: "snapshot"` whether a backup file is ready. The other access path is never attempted, and neither state is ever a `FAIL`.
- For a configured `caldav` provider, whether the server is reachable and Basic auth succeeds - never a `FAIL`; only a broken config block is.
- Session id source: `OK` for `WIKITOOL_SESSION_ID` or a registered harness variable, `WARN` only for the bare parent-pid fallback.
- Telemetry: on or off and why - installation-form default, `.wikitool-telemetry.json`, or `WIKI_TRACE` - and the current session's count and byte total against both caps; never a `FAIL`.
- Exits 1 only on a `FAIL`; a missing remote, session id or `VERSION` is a `WARN`, not a fault.
- Read-only and exempt from the Iteration Budget Gate.

**SEE ALSO**

- `instructions/setup-instance.md` - the setup steps most findings point back to
- `instructions/preflight.md` - what `tool-paths` and `install-dir` point back to
- `INSTALL.md` § "Konfiguration" - the per-checkout configuration files
- `EVALS.md` - telemetry state and caps
- `instructions/session-setup.md` - setting `WIKITOOL_SESSION_ID`
<!-- /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

The suite and its configuration (`chemenu/tests/`, `pytest.ini`, `.coveragerc`) exist in the
origin repository only - `dist export` leaves them out, because they test that repository's own
type-specs and conventions rather than an instance's. There:

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