photoanalyzer/delivery_backlog/stories/US09-01-docs-in-app.md

US09-01 — Serve the Documentation Inside the Application

Epic: E09

As an operator who was handed a URL and an access secret, I want the manuals inside the application I am looking at, so that understanding it does not require a repository checkout or an internet connection.

Acceptance criteria

• Documentation lives as markdown under docs/, with an index that names every page and the order it is meant to be read in. The same files render on Gitea without modification.
• The application serves a /docs view reachable from the main navigation, listing the pages and rendering the selected one.
• Rendering uses a vendored, version-pinned markdown library committed under frontend/js/vendor/. It is not fetched from a CDN, not bundled by a build step, and not written by hand. The build records the version and a checksum of the vendored file.
• Diagrams written as mermaid fenced blocks render as diagrams. Mermaid is vendored the same way.
• script-src in the Content-Security-Policy is unchanged: no 'unsafe-eval', no 'unsafe-inline'. Only style-src gains 'unsafe-inline', and the reason is recorded where the policy is defined.
• Links between documents work in the app: a relative ../foo.md#section link navigates to that page and heading rather than downloading a file or leaving the application. Every heading has a stable anchor, and a deep link to an anchor scrolls to it.
• An unknown page renders a documentation-specific not-found message with a link back to the index, and never exposes a filesystem path.
• Documentation is readable without an access secret or behind the same session as the rest of the application — whichever is chosen is stated explicitly in the story's implementation notes and covered by a test, because an operator locked out by a configuration mistake is exactly who needs the troubleshooting page.
• The view works with no outbound network access at all.

Automated tests

• Unit: heading-anchor slugs (duplicates, punctuation, non-ASCII), and the rewriting of relative markdown links into in-app routes.
• Integration: every markdown file under docs/ is reachable from the index; every internal link in every document resolves to a file and, where an anchor is given, to a heading that exists; the vendored library files match their recorded checksums.
• Browser: the documentation view renders a page, follows an internal link, deep-links to an anchor, renders a mermaid diagram to an SVG, and shows the not-found message for an unknown page — all with zero console errors and zero CSP violations, asserted, not eyeballed.

Dependencies

• None beyond the delivered application.