# 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