chemenu/docs/how-to/maintain-the-wiki.md

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.

Related

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