US09-04: Write the User Manual with Generated Screenshots (#110)

docs/first-pass.md

@@ -0,0 +1,66 @@
+# A guided first pass
+
+[← Documentation index](index.md)
+
+One library, from nothing to a verified upload. Each stage links to its own page; this
+is the order, and — more importantly — where the points of no return are.
+
+![The workflow home, with every stage and its counts](images/workflow.png)
+
+The workflow page is the home view and the honest summary: each stage shows its state,
+its counts, why it is blocked if it is, and the one action that moves it forward.
+
+| # | stage | reversible afterwards? |
+|---|---|---|
+| 0 | [Inventory](stages/inventory.md) | nothing was changed |
+| 1 | [Duplicate review](stages/duplicates.md) | yes — decisions can be changed, no file is deleted |
+| 2 | [Safety review](stages/safety.md) | the decision, yes; the EXIF keyword is a file write |
+| 3 | [Analysis](stages/analysis.md) | the result, yes; the caption and keywords are a file write |
+| 4 | [Album proposals](stages/albums.md) | yes — approving renames nothing |
+| 5 | [Renames](stages/renames.md) | **your folders move.** Recoverable, journaled, but real |
+| 6 | [Upload](stages/uploads.md) | **assets exist on the Immich server.** Not undone from here |
+| 7 | [Archive](stages/archive.md) | **originals leave active storage.** Restorable while the medium is reachable |
+| — | [Diagnostics](stages/diagnostics.md) | read-only, any time |
+
+## Before the first run
+
+Take a backup of the photo library itself. This application is careful — it previews,
+journals, and verifies — but it is the first time you are pointing it at your
+photographs, and a backup is cheaper than confidence.
+
+If the library is irreplaceable, turn on `PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL`
+before anything else. Every mutating request is then refused until you have produced
+a read-only reconciliation report and approved it by name.
+
+## The pass
+
+1. **Scan.** Inventory → *Rescan*. Reads only. Check the count, and check that
+   nothing under `_IGNORE/` appears.
+2. **Resolve duplicates.** Exact byte matches can be accepted as recommended; anything
+   fuzzy gets looked at. Resolving first is what stops you paying to analyse the same
+   photo twice.
+3. **Decide safety.** Every canonical photo becomes `sfw` or `nsfw`. Nothing reaches
+   the vision provider until it is confirmed SFW — this is the gate the whole design
+   exists around.
+4. **Analyse.** Only confirmed-SFW photos. Each result is written to the database and
+   projected into EXIF, then read back and verified.
+5. **Propose album names.** Evidence from what was analysed. Edit anything you disagree
+   with. Approving changes no file.
+6. **Build the rename plan, read it, apply it.** The preview shows every old → new
+   path. This is where folders move.
+7. **Rescan.** Paths are reconciled; identities are unchanged.
+8. **Upload.** Preflight lists every blocker. The command is previewed without the API
+   key. One album at a time.
+9. **Verify.** An uncertain upload is not a failure and not a success — ask the server.
+10. **Archive** (optional). Copy, verify, and only then reclaim the space.
+
+Stop anywhere. Every stage is resumable, and closing the browser cancels nothing.
+
+## Two rules worth internalising
+
+**The application refuses more than it warns.** A refusal is not a fault; it is the
+design working. [Errors and refusals](errors.md) explains each one.
+
+**One long job at a time.** Browsing stays available while a job runs, but a second
+mutating job is refused — that is what makes a crash recoverable rather than
+ambiguous.