# 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](../reference/skills.md)), and `tools/wikitool`
does the mechanical part.

## What you say

```text
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](../../tools/CONTRACT.md#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:

```bash
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](../reference/commands/provenance.md).

## 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.

Every gate, and which command it belongs to: [exit codes and gates](../reference/exit-codes.md).
Why they are enforced in code: [why-gates-are-code.md](../explanation/why-gates-are-code.md).

## Related

- [Troubleshoot](troubleshoot.md) - when `doctor` or a command reports a problem with the instance
  itself rather than with its pages.