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
|