# Distribution and versioning

Exporting, adopting and upgrading an instance, and the version and changelog of the stack itself.

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

- [`dist export`](#dist-export)
- [`dist adopt`](#dist-adopt)
- [`dist upgrade`](#dist-upgrade)
- [`version show`](#version-show)
- [`version check`](#version-check)
- [`version notes`](#version-notes)
- [`version bump`](#version-bump)
- [`version regrade`](#version-regrade)
- [`version release`](#version-release)
<!-- /wikitool:toc -->

<!-- wikitool:reference-commands -->
## `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]`

**Options**

```text
Arguments:
  target  Directory to write the distribution into. Must not exist, or must be
          empty.  [required]

Options:
  --dry-run              List what would be written, without writing anything.
  --source-repo <str>    Repository this export was built from (recorded in the
                         stamp)
  --source-commit <str>  Commit this export was built from (recorded in the
                         stamp)
  --release-url <str>    Release page this export ships as (recorded in the
                         stamp)
  --update-url <str>     Release feed `version check` should ask (recorded in
                         the stamp)
  -h, --help             Show this message and exit.
```

**Examples**

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

**Behaviour**

- Writes a contentless, distributable copy of this repo's machinery into an empty or new `<target>` directory.
- Ships `AGENTS.md`/`README.md`/`INSTALL.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 (minus `docs/dev/`), `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.

**Properties**

- Changes files: yes
- Idempotent: yes
- Atomic: Yes - nothing is written until every file is planned
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `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)

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

**Options**

```text
Arguments:
  templates...  Templates to adopt. Default: every collection contract and page
                type-spec template.

Options:
  --dry-run   List what would be copied, without writing anything.
  -h, --help  Show this message and exit.
```

**Examples**

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

**Behaviour**

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

**Properties**

- Changes files: yes
- Idempotent: yes
- Atomic: No - files are copied one by one; a re-run completes an interrupted one
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

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

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

**Options**

```text
Arguments:
  source  An extracted distribution directory, or a release .tar.gz archive - or
          use --latest

Options:
  --latest              Download the release the feed announces as latest
                        instead of naming a <source>
  --expect <str>        With --latest: refuse, before downloading anything,
                        unless the feed's latest release is this version (the
                        one `version notes` was read for)
  --dry-run             Classify and report, without writing anything
  --keep-local          Proceed even with locally changed files - leave each one
                        untouched rather than aborting
  --take-release <str>  Overwrite this locally changed path with the release's
                        version, discarding the local change. Repeatable, and
                        each path must be one this run reports as locally
                        changed. The counterpart to --keep-local, which keeps
                        the change and reports it again on every future upgrade
  --prune               Accepted and ignored: files the new release no longer
                        ships are now deleted by default when unchanged since
                        install
  --pre                 Allow a pre-release (-beta.N) source tree - release.yml
                        never publishes one
  -h, --help            Show this message and exit.
```

**Examples**

```bash
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
```

**Behaviour**

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

**Properties**

- Changes files: yes
- 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
- Counts toward the session call budget: yes
- Can reach the network: yes

**Exit codes**

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

**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
- `docs/how-to/update-an-instance.md` - 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]`

**Options**

```text
  --json      Print the version and stamp as JSON
  -h, --help  Show this message and exit.
```

**Examples**

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

**Behaviour**

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

**Properties**

- Changes files: no
- Idempotent: yes
- Atomic: Read-only
- Counts toward the session call budget: no
- Can reach the network: no

**Exit codes**

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

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

**Options**

```text
  --url <str>        Release feed to ask (default: the stamp's, else the built-
                     in origin)
  --timeout <float>  Seconds to wait for the feed  [default: 10.0]
  --json             Print the result as JSON
  -h, --help         Show this message and exit.
```

**Examples**

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

**Behaviour**

- 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 (`docs/how-to/update-an-instance.md`).
- Read-only; exempt from the Iteration Budget Gate.

**Properties**

- Changes files: no
- Idempotent: yes
- Atomic: Read-only, no local writes
- Counts toward the session call budget: no
- Can reach the network: yes

**Exit codes**

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

**See also**

- `wikitool dist upgrade` - applies the update this reports
- `wikitool version notes` - prints the release notes
- `docs/how-to/update-an-instance.md` - 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]`

**Options**

```text
  --version <str>    Which entry to print (default: this tree's VERSION)
  --offline          Never ask the release feed: on a distributed instance,
                     whose CHANGES.md carries no entry to print, fail with the
                     release page instead of fetching the notes
  --url <str>        Release feed to ask for the fallback (default: the stamp's,
                     as `version check`)
  --timeout <float>  Seconds to wait for the feed  [default: 10.0]
  -h, --help         Show this message and exit.
```

**Examples**

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

**Behaviour**

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

**Properties**

- Changes files: no
- Idempotent: yes
- Atomic: Read-only
- Counts toward the session call budget: no
- Can reach the network: yes

**Exit codes**

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

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

**Options**

```text
  --major               Bump MAJOR (resets MINOR and PATCH)
  --minor               Bump MINOR (resets PATCH)
  --patch               Bump PATCH
  --title <str>         One-line title for the new/updated CHANGES.md entry
                        [required]
  --breaking <str>      What stops working (recorded in CHANGES.md). Required on
                        the bump that first escalates to a boundary crossing,
                        optional on a later bump of the same crossing candidate
                        - where it joins the reasons already recorded rather
                        than replacing them. Refused on a bump that crosses
                        nothing
  --no-migration <str>  Why the escalation to a boundary crossing needs no
                        content migration (recorded in CHANGES.md)
  --migration-required  Retract this candidate's earlier --no-migration line: a
                        migration is needed after all. Requires a migration
                        document already targeting the new base, and refuses
                        when the entry carries no --no-migration line to
                        retract.
  --impact <str>        high|medium|low - how much this bump matters to a reader
                        of the release notes (default: medium). Grouped into the
                        entry's bump list; `version regrade` corrects it later
                        if the running candidate's own judgment changes.
  --dry-run             Report the change without writing
  -h, --help            Show this message and exit.
```

**Examples**

```bash
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"
```

**Behaviour**

- `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 - a summary and one-paragraph `###` sections, one per topic - is left to the author.
- Whenever a required migration document (`migrates_to:` equal to the candidate's base) exists, every bump writes or refreshes `**Migration:** required - <paths>`, the documents' paths sorted and comma-separated, in place of any `none required` line. The two forms never stand side by side.
- 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` replaces the running candidate's `--no-migration` line with the `required` line; it needs a required 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.

**Properties**

- Changes files: yes
- Idempotent: no
- Atomic: No - `VERSION` then `CHANGES.md`
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `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` - `--no-migration` while a required migration document targets the new base
- `1` - `--migration-required` combined with `--no-migration`, on a bump with no running candidate, with no `--no-migration` line to replace, or without a required migration document already targeting the new base

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

**Options**

```text
Arguments:
  indices...  1-based positions in the rendered bump list to regrade (see the
              bare listing). Omit to just list.

Options:
  --impact <str>  high|medium|low - required together with indices
  -h, --help      Show this message and exit.
```

**Examples**

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

**Behaviour**

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

**Properties**

- Changes files: yes
- Idempotent: no
- Atomic: No - `CHANGES.md` only, and only when indices are given
- Counts toward the session call budget: only when called with arguments
- Can reach the network: no

**Exit codes**

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

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

**Options**

```text
  --title <str>  Replace the entry's heading title (default: the last bump's)
  --dry-run      Report the change without writing
  -h, --help     Show this message and exit.
```

**Examples**

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

**Behaviour**

- 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 `###` section heading. A candidate with exactly one bump is exempt, since there its own paragraph already is the summary. `--dry-run` runs this check too.
- Refuses an entry that would exceed its budget once released: at most 32 000 bytes (UTF-8) as `version notes` prints it, and every `###` section exactly one paragraph of at most 1 000 bytes, heading line excluded. The same check as `docs verify`, run on the released heading; `--dry-run` runs it 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.

**Properties**

- Changes files: yes
- Idempotent: no
- Atomic: No - `VERSION` then `CHANGES.md`
- Counts toward the session call budget: yes
- Can reach the network: no

**Exit codes**

- `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 `###` sections
- `1` - The entry is over 32 000 bytes, or a `###` section has more than one paragraph or a paragraph over 1 000 bytes - the error names each with its size

**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`
<!-- /wikitool:reference-commands -->