domverse
792134c72d
Adds the installation manual, architecture overview, and illustrated user manual as a five-story epic, plus the acceptance gate that keeps them true. The documentation is markdown under docs/, so the same files are readable in the repository and rendered by the deployed application at /app/#/docs. An operator who was handed a URL and an access secret has no repository checkout in front of them, and the network the application is deployed to is not assumed to reach a CDN. Two decisions are recorded in the epic rather than left to implementation: - The renderer is vendored (marked), not written and not fetched. - Diagrams are mermaid, rendered client-side, with script-src untouched. Whether mermaid needs 'unsafe-eval' was measured rather than assumed: its bundle contains no eval( and no new Function, and rendered under this application's exact CSP it produced an SVG with no script-src violation. What it does violate is style-src, which gains 'unsafe-inline'. With script-src, img-src, connect-src, and font-src all unchanged, that leaves defacement rather than execution or exfiltration. The alternative -- pre-rendering diagrams to committed SVG with the already-installed Playwright -- is recorded as the migration if that trade is ever refused. Screenshots are generated from the running application, never pasted, and every documented setting, command, exit code, error code, and state is cross-checked against the code that implements it, so stale documentation fails a test instead of misleading an operator. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015csGY8XV1M92fHfKnMmjtu
1.8 KiB
1.8 KiB
US09-05 — Automate Documentation Acceptance
Epic: E09
As a release owner, I want one gate that proves the documentation still describes the application, so that a change to the code cannot quietly make the manuals wrong.
Acceptance criteria
- One documented command runs every documentation check and retains its evidence, in the shape the release and container gates already use.
- The gate fails when: an internal link or anchor is dead; a page is unreachable from the index; an image is referenced but missing or present but unreferenced; a documented setting, command, exit code, error code, or state does not exist in the code; a code path exists that the documentation is required to cover and does not.
- The gate regenerates the screenshots and fails when a regenerated image no longer matches the committed one beyond a stated tolerance, so a UI change that invalidates the manual is a red build rather than a discovery months later.
- The gate renders every documentation page in a real browser and fails on any console
error or CSP violation, and asserts that
script-srccontains neither'unsafe-eval'nor'unsafe-inline'. - The checks run on a
phase_imarker; CI runs the gate, and the earlier epic suites keep running unchanged. - The README and the application's documentation index point at each other, so neither is the forgotten copy.
- Documentation stories are mapped in the story traceability matrix like every other story.
Automated tests
- The gate's own contract is testable without a browser: a seeded broken link, a missing image, an undocumented error code, and a stale screenshot each fail it, and a clean tree passes.
- The full documentation suite runs on
phase_iin CI.
Dependencies
- US09-01 through US09-04