Wiki update — how it works

This page documents the built-in wiki-update job: what it does, what it picks up, and what it does not. It is the operational companion to wiki-update-prompt.md (which is the procedure the agent follows; this page is the mechanism around it).

1. Overview

The wiki is a set of hand-structured Markdown pages in docs/wiki/ with a small YAML front matter: title, sources: (the code paths a page is responsible for), and verified_at (last time its prose was checked against code).

The wiki-update job is a diff-driven refresh: it diffs the git history since the wiki's last recorded commit, works out which pages are affected, and re-runs a single agent whose goal is the procedure in docs/wiki/wiki-update-prompt.md. After a successful run, a mechanical (not LLM) post-step writes a review diff to docs/wiki/history/ and advances docs/wiki/.wiki-state.json to the current HEAD.

Short answer to "does it pick up code changes and new features":

• Code changes — yes, but only committed ones. The agent's input is git diff <last_commit>..HEAD. It maps changed paths to wiki pages via each page's sources: front matter and rewrites only the intersecting pages.
• New features — yes, three ways: new/changed tools and routes regenerate the AUTO tables in tools.md / web-ui-api.md; user-facing behavior (UI tabs, endpoints, settings, shortcuts, workflows) is caught by the "help-sync" pass that edits templates/help.html.
• Uncommitted work — no. Working-tree changes are captured in the diff artifact for review only; the agent does not edit wiki/help pages for them.
• Brand-new subsystems — only if a page already lists them. The job edits existing pages whose sources: intersect the diff; it does not create new wiki pages.

2. Components

3. Registration and scheduling

register_wiki_update_job(scheduler) runs at harness construction and is idempotent:

• Registers a workflow wiki-update (name "Wiki update") with a single AGENT step (agent_type = "react"), whose goal_template is the text of wiki-update-prompt.md after its leading --- marker. Step timeout 1800 s; workflow timeout 45 min.
• Seeds a default INTERVAL schedule wiki-update-weekly (7 days), with last_run = now so the first automatic run fires one full week after boot. Existing user state (retimed/disabled/last_run) on disk is preserved, never clobbered.

4. Triggering a run

Two ways, both via the Jobs/Workflows page (routes_scheduler.py):

• Scheduled — the engine's interval trigger fires wiki-update-weekly.
• Manual — POST /api/schedules/<sid>/run runs the workflow immediately (the "run now" button). It records a per-run cost row (job_runs) and, on status == "completed", invokes the diff writer. Failed/cancelled runs leave no diff artifact.

The manual-run endpoint also special-cases profile-loop (redirects to the cockpit button) and profile-optimize (proposal/eval post-steps), but wiki-update only needs the diff post-step.

5. The agent procedure (the 6 steps)

From wiki-update-prompt.md (the goal the react agent executes):

1. Read docs/wiki/.wiki-state.json for last_commit; run git diff --stat <last_commit>..HEAD (fall back to git log -5 --oneline if the file/sha is missing).
2. For each wiki page, compare the changed paths against the page's sources: front matter. Only edit pages whose sources intersect the diff — never rewrite unaffected pages.
3. For each affected page: read the current code at the changed paths, update prose to match reality, set verified_at: to today's date. Keep pages under ~250 lines; keep mermaid diagrams valid (≤15 nodes, no double-quoted labels).
4. If the diff touched model_harness/tools/ or any routes_*.py / app.py, run venv\Scripts\python.exe scripts\wiki_tables.py to regenerate the AUTO tables.
5. Help-sync pass: review the incoming changes for user-facing behavior or features (new/changed UI tabs, API endpoints, settings, shortcuts, workflows). If any exist, update templates/help.html — it is hand-authored with a <nav class="help-toc">; match its style/structure and only touch the relevant sections (add a TOC entry when adding a section).
6. Finish with a summary: which pages changed and why, then a "Help impact" heading listing every help.html change — or "Help impact: none".

The agent is explicitly told it does not need to create diff files or touch .wiki-state.json — the harness does that itself.

6. The post-run diff writer (mechanical, not LLM)

write_update_diff(execution_id) runs after a completed wiki-update. It is pure git plumbing and never raises (fail-open: git errors yield empty strings):

1. Read last_commit from .wiki-state.json.
2. git diff <last_commit>..HEAD → "Committed since last wiki refresh" (truncated to 50 KB).
3. git diff HEAD + untracked-file listing (excluding docs/wiki/history/) → "Working-tree changes (uncommitted, incl. this run)".
4. Then advance .wiki-state.json to the current HEAD — so the next run diffs against this point. (The writer owns this file, not the agent.)
5. If both sections are empty, skip. Otherwise write docs/wiki/history/<YYYYMMDD-HHMMSS>-wiki-update[-exec_<id>].diff.

The result is a human-reviewable artifact, not an input to the next run. The committed section shows what the agent should have incorporated; the working-tree section shows what the run itself just edited (plus any unrelated uncommitted work in the tree at run time).

7. What the diff scope means in practice

• The agent's editing is driven only by committed changes (last_commit..HEAD). Work sitting uncommitted in the tree is recorded in the diff artifact but does not trigger wiki or help edits.
• New tools → scripts/wiki_tables.py rewrites the <!-- AUTO:tools --> block in tools.md (every registered builtin + ported tool).
• New/changed routes → the same script rewrites <!-- AUTO:routes --> in web-ui-api.md (every Flask route except /static).
• New user-facing features → only the help-sync pass (step 5) touches help.html, and only if the agent judges them user-facing.
• The job does not add new pages and does not notice code that no existing page's sources: covers.

8. Rendering and the reader

routes_pages.py serves the wiki:

• GET /wiki → renders INDEX.md; GET /wiki/<slug> → one page.
• _wiki_pages() lists docs/wiki/*.md (skipping wiki-update-prompt).
• _wiki_changed_pages() scans history/*.diff (newest-first, ≤20 files, ≤7-day window) for diff --git a/docs/wiki/<page>.md and ?? docs/wiki/<page>.md lines, marking pages changed within 2 days as "recent" for the sidebar.
• GET /api/wiki/search?q= backs the floating quick-search panel.
• The Jobs page serves GET /api/wiki/history and /api/wiki/history/<name> to browse past diffs.

9. Gotchas and limitations

1. Commit before you expect it to reflect. Only committed changes drive edits. To capture work-in-progress, commit it (or run the job again after committing) — the last_commit pointer only advances on a completed run.
2. Failed runs advance nothing. status != "completed" → no diff, no state advance; the next run re-diffs the same range.
3. Truncation. Diff sections cap at 50 KB each; a huge change set may be truncated in the artifact (the agent still sees the raw git diff, so this only affects review).
4. Sources coverage is manual. A new subsystem needs a page (or an updated sources: list) before the job will maintain it.
5. help.html is hand-authored. The help-sync pass is the only automated touch; it matches existing style and section structure and is scoped to the relevant sections. Large feature additions still benefit from a manual pass.
6. AUTO tables are the only mechanical text. Everything else (prose, help.html) depends on the agent's judgment of the diff.

verified against code: 2026-09-01