Documentation maintenance

Content and generated outputs

The original user guide is authored in docs/lookout/guide.json. Additional manuals live in docs/lookout/content/*.json. The build script generates Markdown, HTML, a search index and reference artifacts. Do not edit generated files directly.

The measure dictionary, source/code tables and role/route inventories are generated from checked fixtures and implementation exports. The OpenAPI document covers the U4 tract endpoints. Reference paths and hashes are recorded in a provenance manifest so a change in source evidence is detectable.

Screenshots live under public/assets/docs and must carry a caption stating their synthetic-fixture provenance. Public portal content must not include secret paths, passwords, private account documents or project exports.

npm run docs:build
npm run docs:check
npm run docs:test

Responsibilities

These are responsibilities to assign, not a claim that named staff or a support rotation already exist. Keep the organization’s private escalation roster outside public generated content.

Per-change review checklist

1. Identify whether the change affects a live feature, an optional configuration, a local rehearsal or planned work. Use that status explicitly.
2. Update the manual source and its repository references. Regenerate affected dictionaries/contracts rather than typing values from memory.
3. Verify all local links, anchors, code references, generated hashes and image captions. Keep API examples free of real credentials and preserve decimal strings/null semantics.
4. Run browser checks for search, keyboard access, responsive layouts, print and CSP. A static render check alone is not a usable-page check.
5. Update release notes and evidence. For UI changes, refresh relevant screenshots; do not use an old image to claim current behavior.
6. Publish through a new reviewed application release. Do not patch the immutable public image or sealed U4 controls in place.

Publishing and compatibility

The portal is a set of root-level documentation-*.html pages plus files under assets/docs. Vite copies them, and the existing built-frontend inventory admits those directories/types under its normal CSP. No server authorization change is needed to serve general documentation.

Search runs locally in the browser against the generated text index; it sends no query to an external service and stores no user query. Without JavaScript, the manuals, navigation and browser Find remain available.

For a portal release, bind generated asset verification to the image build, verify the header link and same-origin page serving, and perform the applicable public smoke checks. The guide’s source version badge is not a substitute for the deployed image digest.

Evidence limitations to preserve

Documentation can describe a recovery process and its acceptance criteria; it cannot manufacture a missing backup, prove restore performance, create an on-call team or certify accessibility/security. Keep those operational acceptance items visible until the responsible team records evidence.

The released U4 workflow is the supported baseline. Broader repository modules remain described as optional unless current configuration and acceptance evidence establishes otherwise.