photoanalyzer/delivery_backlog/stories/US09-04-user-manual.md

US09-04 — Write the User Manual with Generated Screenshots

Epic: E09

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