torbenandClaude Opus 5.5
d92800f372
Files changed: - CHANGES.md - VERSION - docs/explanation/architecture.md - instructions/publish-cycle.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
---
|
|
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`.
|