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
53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
# US09-04 — Write the User Manual with Generated Screenshots
|
|
|
|
Epic: [E09](../E09-documentation.md)
|
|
|
|
As the person actually sorting a photo library, I want a manual that walks the workflow
|
|
screen by screen and tells me what each refusal means, so that I can use the application
|
|
confidently and know what it is about to do to my files before it does it.
|
|
|
|
## Acceptance criteria
|
|
|
|
- One page per workflow stage, in the order the application presents them: discovery and
|
|
inventory, duplicate review, safety review, analysis, album proposals, renames, upload,
|
|
archive, and diagnostics. Each page answers the same four questions: what this stage is
|
|
for, what I have to decide, **what it changes on disk or on the server**, and what it
|
|
refuses to do.
|
|
- A **guided first pass** that takes a new library from scan to a verified upload, naming
|
|
the point of no return in each stage and what is reversible after it.
|
|
- Every stage page carries at least one screenshot of the real application showing the
|
|
state being described.
|
|
- Screenshots are **generated** by a committed Playwright script that seeds a temporary
|
|
fixture library, drives the application, and writes the images. Regenerating them is one
|
|
documented command. No screenshot is captured by hand.
|
|
- Screenshots contain no real library paths, no personal photos, and no secrets — the
|
|
fixture library is synthetic, and this is asserted rather than assumed.
|
|
- An **error and refusal catalogue**: every `error.code` the API can return, with what
|
|
causes it, what the application did or refused to do, and what the operator should do
|
|
next. Refusals that protect data (`lock_held`, `rename_recovery_required`,
|
|
`stale_preflight`, `path_not_allowed`, `host_not_allowed`, `dry_run_not_approved`,
|
|
conflict codes) are explained as intentional, not as faults.
|
|
- A **recovery** page: an interrupted rename, an uncertain upload, a failed migration, a
|
|
restored backup — what the application does by itself and what needs a decision.
|
|
- The work-item safety allow list is extended to permit `docs/images/**`, since the
|
|
repository denies image files by default. This is an explicit, reviewed change, not a
|
|
quiet one, and it stays narrow enough that a real photo still cannot be committed.
|
|
|
|
## Automated tests
|
|
|
|
- Every `error.code` the application can emit is documented, and every code documented
|
|
exists in the code — both directions.
|
|
- Every image referenced by a documentation page exists, and every image under
|
|
`docs/images/` is referenced by a page.
|
|
- The screenshot generator runs end to end in the test environment and produces every
|
|
image the manual references, against a temporary fixture library that is destroyed
|
|
afterwards.
|
|
- Generated screenshots are checked for library paths outside the fixture root and for
|
|
the configured secrets.
|
|
- Browser: each stage page renders in the documentation view with its screenshot loaded
|
|
and no console error.
|
|
|
|
## Dependencies
|
|
|
|
- US09-01
|