Table of Contents

Maintain the wiki

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Generated from docs/how-to/maintain-the-wiki.md at v10.1.0 – edit the repository, not this wiki.

Maintain the wiki

Keep the wiki healthy: find broken links, orphan pages, raw files no page covers yet, contradictions and stale claims, then repair what can be repaired mechanically. The agent does this with the wiki-lint skill (skill catalogue), and tools/wikitool does the mechanical part.

What you say

Lint the wiki

Do this periodically. The agent suggests it on its own every ten sources. The full schedule - which task runs how often, and with which command - is the maintenance schedule in tools/CONTRACT.md, next to the command records it depends on.

What you get back

A deterministic structural scan by tools/wikitool lint: broken wikilinks, orphan pages, catalog drift, schema gaps, raw files without a source page, and citations that disagree with frontmatter.
The judgment half, which no command can do: contradictions between pages, stale claims, subjects that deserve a page of their own, and a rule stated in two places.
Repairs for what is mechanical, a rebuilt catalog and provenance index, and an entry in kb/log.md.
A report under reports/, which is gitignored and never published. The agent carries the findings that need you into its reply.

For a quick look without a full pass, say Wiki status instead. That is read-only.

Provenance: where a claim came from

Every fact should trace back to a raw file. A source page lists its raw files, and other pages cite specific claims inline with a footnote that points at a source page. You can ask the questions yourself:

tools/wikitool sources coverage                  # raw files no source page covers yet
tools/wikitool sources trace --raw raw/2026/09/x.md     # which pages rest on this file
tools/wikitool sources trace --page "HA Integration"    # which raw files this page rests on

kb/provenance.md is the generated reverse index. The commands are in the provenance reference.

Where the agent stops

Publishing ten or more files stops at the Mass-Update Gate (exit 42); the generated indexes, kb/log.md and kb/provenance.md are not counted. A lint pass that repairs many pages does this routinely. The agent shows you the full file list and the --confirm line, and publishes only after you approve. The token is a digest of that file list, so your approval never covers a changeset you did not see.
The call budget. Every wikitool call counts against a per-session budget: 60 calls, or 3 identical calls in a row. Past it, calls are refused. The agent stops and summarises where it is. If you want it to go on, tell it so. Only then may it pass --override-budget on the command it needs. A refusal usually means the task should be split, not pushed through.
No reachable remote. Without --no-push, publish refuses with exit 1 before committing when the remote is not configured or cannot be reached. An instance that is meant to stay local passes --no-push on every publish - or, without a git server, pushes to a synced folder instead: back-up-to-a-synced-folder.md.
A failed machine-data backup. With a backup into a synced folder, a publish that pushed also copies this machine's files that are not in git. If that copy fails, publish prints a WARN line and still succeeds - the commit and the push stand. Fix what the line names, then run tools/wikitool backup run; another publish does not repeat the copy.

Every gate, and which command it belongs to: exit codes and gates. Why they are enforced in code: why-gates-are-code.md.

Troubleshoot - when doctor or a command reports a problem with the instance itself rather than with its pages.

Maintain the wiki

What you say

What you get back

Provenance: where a claim came from

Where the agent stops

Related