Maintenance Guide

Documentation spine · Getting started · Personas and journeys · Illustrated manual · Agent guide · Evaluation

This guide keeps the corpus, documentation spine and illustrated manual independently updateable but synchronized.

Source-of-truth map

Surface	Source of truth	Generated or maintained output
work catalogue and facets	official Atom feeds plus `scripts/build_legislation_okf.py`	`legislation/`
provision normalization	`apps/okf-explorer/src/lib/legislation/structure.ts`	live browser CLML tree
answer benchmark	`scripts/build_legislation_evaluation.py`	`evaluation/legislation/questions.json`
documentation spine	`docs/uk-legislation/` and `docs/uk-legislation-okf.md`	Pages `docs/` routes
screenshots	hosted Explorer states in `manifest.json`	`docs/assets/uk-legislation-manual/`

Corpus refresh

uv run --locked python scripts/build_legislation_okf.py --refresh
uv run --locked python scripts/check_legislation_okf.py

Update corpus counts, represented years, type coverage and any upstream-access conflict in the architecture guide and screenshots. Preserve source anomalies as warnings rather than silently rewriting them.

Screenshot refresh contract

Screenshots are 1280×720 JPEG captures unless the manifest declares a deliberate crop. For each item:

open the recorded route;
perform the recorded interactions in order;
wait until every expected_text value is present;
capture the viewport;
crop only when the screenshot's declared crop requires it;
inspect the image at original resolution;
update captured_at, dimensions and corpus generation timestamp in the manifest;
update the manual if the interaction or expected behaviour changed.

Refresh screenshots when:

the Explorer layout or legislation detail card changes;
counts or generation timestamps shown in an image are no longer the intended documentation checkpoint;
search ranking materially changes;
normalized CLML labels or passage actions change;
an image fails visual inspection or no longer matches its user journey.

Do not refresh screenshots merely to erase a documented upstream anomaly.

Documentation review

Check each spine in this order:

Getting started — task steps and labels.
Personas and journeys — needs, risks and success criteria.
Illustrated manual — current states and expected behaviour.
Agent guide — progressive discovery and evidence contract.
Architecture — counts, ontology, access and limitations.
Evaluation — rubric, schema and commands.

Publication checklist

Regenerate deterministic outputs whose source changed.
Run all commands in Evaluation and quality.
Confirm git diff --check and documentation lockstep.
Build _site/ and verify every manual image is copied.
Open the hosted Explorer URL after Pages deployment.
Verify the documentation spine landing page and at least one image URL.
Record the user-visible update in CHANGELOG.md.