diff --git a/delivery_backlog/E09-documentation.md b/delivery_backlog/E09-documentation.md new file mode 100644 index 0000000..d2c2cad --- /dev/null +++ b/delivery_backlog/E09-documentation.md @@ -0,0 +1,77 @@ +# E09 — Product Documentation + +Concept phase: none. Like [E08](E08-container-deployment.md), this epic is a delivery +addition rather than a product-scope change: the same application, documented well +enough that somebody who did not build it can install it, understand it, and operate it +without reading the source. + +It does not change the product scope in +[`INTEGRATED_PIPELINE_CONCEPT.md`](../INTEGRATED_PIPELINE_CONCEPT.md). No safety +invariant moves, no schema changes, no new runtime capability. The one change to the +running application is a documentation view and the static assets it needs. + +## Why the application serves its own documentation + +The manuals describe an application that is reached over HTTP behind an access secret. +Documentation that lives only in the repository is unreachable from the deployment it +describes: an operator who has just been handed a URL and a secret has no Gitea account +in front of them. So the same markdown files are both the repository's documentation and +the deployment's `/docs` view, and neither is a copy of the other. + +## Decisions made in this epic + +**Markdown is the source.** Everything is written as markdown under `docs/`, so it is +reviewable in a diff, readable on Gitea, and renderable in the app. No documentation +format that only a tool can read. + +**The renderer is vendored, not written and not fetched.** `marked` (MIT, no +dependencies, ships an ES module) is pinned and committed under +`frontend/js/vendor/`. A CDN is not an option: the application is deployed to a network +whose outbound access is not assumed, and `default-src 'self'` forbids it. + +**Diagrams are mermaid, rendered client-side, with the script boundary intact.** The +claim that mermaid requires `'unsafe-eval'` was tested rather than believed: mermaid 11's +bundle contains no `eval(` and no `new Function` — only a lodash `Function("return this")` +global-detection fallback that short-circuits on `globalThis` and never executes. +Rendered under this application's exact CSP, a flowchart produced a 15.8 KB SVG and +raised **no `script-src` violation**. What it does raise is `style-src`: mermaid styles +its output with an injected `