# US09-01 — Serve the Documentation Inside the Application

Epic: [E09](../E09-documentation.md)

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.