torbenandClaude Opus 5.5
61e18dc4aa
Files changed: - docs/how-to/ingest-a-source.md - docs/how-to/maintain-the-wiki.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# 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.
|