---
type: types/instruction.md
name: publish-cycle
description: Close out a change to the wiki - rebuild the provenance index and catalog, append the audit entry, and publish.
---

# Close out a change

Run after any change to pages under `kb/`, in this order. The order matters: the catalog is
built from page frontmatter, and the audit entry should describe a tree that is already
consistent.

## Steps

1. **Rebuild the provenance index** - after any change to a source page or an inline citation:

   ```bash
   tools/wikitool sources rebuild-index
   ```

2. **Rebuild the catalog** - after any page was added, removed, renamed, or had its
   summary/date changed:

   ```bash
   tools/wikitool index rebuild
   ```

   This regenerates `kb/index.md` and every `kb/**/INDEX.md`. Never edit those by hand.

3. **Append the audit entry** - one per operation:

   ```bash
   tools/wikitool log append --op ingest|query|lint|create|update|delete|rename|move \
     --title "<what>" --body "<outcome>"
   ```

   This is the one non-idempotent step. If a previous run's outcome is uncertain, read the
   tail of `kb/log.md` before repeating it.

4. **Publish:**

   ```bash
   tools/wikitool publish --message "<op>: <description>"
   ```

## Decision points

- **Ten or more files changed?** `publish` exits 42. Show the user its output and stop; see
  [gates.md](gates.md).
- **Remote unreachable or not configured?** `publish` ends with exit 1 before it commits:
  nothing is staged, committed or pushed, and the message names the remote. Ask the user whether
  to commit locally with `--no-push`, and run that only on their answer. Never push by hand
  (AGENTS.md invariant 5): the next `publish` that reaches the remote sends the local commit
  together with whatever is new. A local-only instance, which has no remote at all, passes
  `--no-push` on every call ([setup-instance.md](setup-instance.md), step 3).
- **A `WARN` that the machine-data backup failed?** The commit and the push stand, and `publish`
  exited 0. Show the user the line - it names the reason, a synced folder that is not there or not
  writable, say. Do **not** run `publish` again: it would have nothing to push and back nothing up.
  Once the user has fixed the cause, `tools/wikitool backup run` repeats the backup
  ([docs/how-to/back-up-to-a-synced-folder.md](../docs/how-to/back-up-to-a-synced-folder.md)).
- **A `WARN` that a page export failed?** The same: the commit and the push stand, `publish`
  exited 0, and the line names the target and the reason - a page someone edited in the target
  folder, say. Show it to the user and do **not** run `publish` again; once the cause is fixed,
  `tools/wikitool export run` refreshes the target
  ([docs/how-to/export-to-a-synced-folder.md](../docs/how-to/export-to-a-synced-folder.md)).
  An `ERROR` about the `export` section instead stopped `publish` before it committed: the section
  is the user's to fix by hand, and nothing was published.
- **Query or lint pass?** Neither auto-publishes. Run `publish` only if asked to.
- **Nothing under `kb/` changed?** Skip steps 1 and 2; a change to `tools/` or `instructions/`
  does not affect the catalog.

## Scope

This is the close-out for wiki *content*. Changes to skills also need
`tools/wikitool instructions sync` (see [bootstrap.md](bootstrap.md)), and changes to the CLI
or a contract need `tools/wikitool docs verify`.