chemenu/instructions/publish-cycle.md

type, name, description

type	name	description
types/instruction.md	publish-cycle	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:

   tools/wikitool sources rebuild-index
   

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

   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:

   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:

   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.
• 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, 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).
• 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). 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), and changes to the CLI or a contract need tools/wikitool docs verify.