US09-04: Write the User Manual with Generated Screenshots

docs/errors.md

@@ -0,0 +1,95 @@
+# Errors and refusals
+
+[← Documentation index](index.md)
+
+Every error the API returns carries a code:
+
+```json
+{"error": {"code": "lock_held", "message": "a library_write job is already running"}}
+```
+
+Most of them are **refusals, not faults**. This application would rather stop and
+explain than guess about somebody's photographs, so a code below usually means it
+protected something. Each row says what caused it and what to do.
+
+## Access and the trust boundary
+
+| code | cause | what to do |
+|---|---|---|
+| `unauthenticated` | no application session | reload the page; the browser bootstraps one |
+| `access_denied` | wrong or missing access secret | check `PHOTO_PIPELINE_ACCESS_SECRET`. Attempts are logged with the caller's address only |
+| `too_many_attempts` | more than five failed secret attempts in a minute | wait. This is the rate limit, not a lockout |
+| `csrf_failed` | a mutation without the session's token | reload; a stale tab has an old token |
+| `host_not_allowed` | the `Host` header is not a configured name | add the real hostname to `PHOTO_PIPELINE_ALLOWED_HOSTS` |
+| `origin_not_allowed` | the request came from another origin | not something a browser tab of this app produces |
+| `cross_site_blocked` | another site triggered the request | expected — this is the protection working |
+| `payload_too_large` | the body exceeds `PHOTO_PIPELINE_MAX_REQUEST_BYTES` | send less; every endpoint takes small commands |
+| `path_not_allowed` | a path resolved outside the library roots | usually a symlink. Nothing outside the roots is reachable, by design |
+
+## The safety gate
+
+| code | cause | what to do |
+|---|---|---|
+| `dry_run_not_approved` | mutation is gated until a dry run is approved | run `dry-run`, read it, then `approve-dry-run` |
+| `approval_scope_mismatch` | the approval covers different library roots | approve a report for the roots actually configured |
+| `approval_unreadable` | the approval record cannot be read | re-approve; do not edit it by hand |
+
+## Concurrency and staleness
+
+| code | cause | what to do |
+|---|---|---|
+| `lock_held` | a mutating job already holds the lane | wait for it. One at a time is what makes a crash recoverable |
+| `version_conflict` | you acted on a version that changed underneath you | the view re-renders with the server's truth; decide again |
+| `invalid_transition` | a state change that the machine does not allow | usually a stale tab; reload |
+| `job_error` | the job service refused the request | the message says why |
+| `rename_recovery_required` | an interrupted rename is unresolved | resolve it in [Renames](stages/renames.md). Unrelated mutations stay blocked on purpose |
+
+## Stage refusals
+
+| code | cause | what to do |
+|---|---|---|
+| `nothing_to_score` | no photo is eligible for safety scoring | the queue is already decided |
+| `nothing_eligible` | no photo is eligible for analysis | resolve safety decisions first |
+| `nothing_to_plan` | no approved album name to build a plan from | approve a proposal first |
+| `invalid_decision` | the decision is not one this cluster accepts | reload the cluster |
+| `invalid_proposal` | the name is empty, reserved, or has forbidden characters | fix the name; the rules are in [Album proposals](stages/albums.md) |
+| `unknown_album` | the album is not a folder the library knows | rescan |
+| `cannot_apply` | the plan is invalid, stale, or another plan is unresolved | read the blockers in the preview |
+| `cannot_rollback` | the operation is complete or its preconditions no longer hold | rollback is recovery, not undo |
+
+## Upload
+
+| code | cause | what to do |
+|---|---|---|
+| `stale_preflight` | bytes changed between approval and running | re-run preflight; this is the check that stops the wrong bytes being uploaded |
+| `not_runnable` | the batch is in a state that must not be re-run | an uncertain batch is verified, never retried |
+| `requires_verification` | the outcome is unknown; the server may hold the files | verify against Immich, then resolve |
+| `changed_after_upload` | the file changed after a successful upload | uploading again may create or upgrade an asset |
+
+## Operations
+
+| code | cause | what to do |
+|---|---|---|
+| `backup_failed` | the snapshot could not be taken or verified | check free space and the message |
+| `invalid_retention` | a `--keep` value that is not a positive count | the newest backup is never pruned |
+| `not_found` | no such id | usually a stale link |
+
+## Generic
+
+| code | cause |
+|---|---|
+| `invalid_request` | the request body failed validation. Field names only — never the values, which end up in logs and screenshots |
+| `http_error` | a plain HTTP-level refusal, with its status |
+| `internal_error` | an unhandled error. The code is all you get; the traceback is in the server log, because it can carry paths and credentials |
+
+## Diagnostics warnings
+
+Not errors — reported by `diagnostics` and worth acting on. They are listed with
+their meanings in [Diagnostics](stages/diagnostics.md): `disk_low`, `disk_critical`,
+`cache_over_quota`, `wal_growth`, `tool_version_drift`, `legacy_process_active`, and
+`no_roots`.
+
+## Startup refusals
+
+Exit codes 2 to 5 are covered by the installation manual under
+[when it refuses to start](installation.md#when-it-refuses-to-start).

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.

docs/index.md

@@ -15,18 +15,32 @@ repository under `docs/`, on Gitea, and inside the running application under
 2. [Installation and operations](installation.md) — host and container installation,
    every setting, the first-run checklist, upgrades, backup and restore, and what
    each refusal at startup means.
-3. [Architecture](architecture.md) — the context and runtime diagrams, what each
+3. [A guided first pass](first-pass.md) — one library from scan to verified upload,
+   with the point of no return named in each stage.
+4. [Architecture](architecture.md) — the context and runtime diagrams, what each
    module owns, the three journals a restart reads, and where every invariant is
    enforced.
 
-## Being written
+## The stages, one page each
 
-The remaining manuals are accepted work, not aspiration; each is a story in
-[E09](https://git.domverse-berlin.eu/domverse/photoanalyzer/src/branch/main/delivery_backlog/E09-documentation.md)
-and will appear here as it lands.
+Every page answers the same four questions: what the stage is for, what you decide,
+what it changes on disk or on the server, and what it refuses.
 
-- **User manual** — one page per workflow stage with screenshots of the real
-  application, and a catalogue of every error and refusal (US09-04).
+1. [Inventory and discovery](stages/inventory.md)
+2. [Duplicate review](stages/duplicates.md)
+3. [Safety review](stages/safety.md)
+4. [Analysis](stages/analysis.md)
+5. [Album proposals](stages/albums.md)
+6. [Renames](stages/renames.md)
+7. [Upload](stages/uploads.md)
+8. [Archive](stages/archive.md)
+9. [Diagnostics and library statistics](stages/diagnostics.md)
+
+## When something goes wrong
+
+- [Errors and refusals](errors.md) — every error code, what caused it, what to do.
+- [Recovery](recovery.md) — what the application resolves by itself, and what needs
+  you.
 
 ## Conventions
 

docs/overview.md

@@ -72,6 +72,6 @@ python -m photo_pipeline serve      # the API and this browser application
 python -m photo_pipeline worker     # the process that does the long work
 ```
 
-The full procedure, the container path, and every setting belong to the installation
-manual, which is being written next — see
-[the documentation index](index.md#being-written).
+The full procedure, the container path, and every setting are in the
+[installation manual](installation.md); if you would rather start using it, take
+[the guided first pass](first-pass.md).

docs/recovery.md

@@ -0,0 +1,62 @@
+# Recovery
+
+[← Documentation index](index.md)
+
+What the application resolves by itself, and what needs you. The dividing line is
+simple: it resumes when the evidence is unambiguous, and it stops and asks when it is
+not. It never guesses about your files.
+
+## An interrupted rename
+
+A rename records its intent **before** touching the disk, so after a crash the
+journal plus the actual filesystem give a verdict per operation:
+
+| verdict | means | what happens |
+|---|---|---|
+| resumable | the move provably did not happen | reset to planned and run again |
+| rollback-safe | the move happened; the remaining steps can be completed or undone | drive it forward, or roll it back |
+| manual | the evidence is contradictory | left alone, and it keeps blocking |
+
+Open [Renames](stages/renames.md); the recovery panel lists every unresolved
+operation and offers a resolve action only where one is safe. Until then, unrelated
+mutations are refused with `rename_recovery_required` — building new work on a
+half-applied move is how a library becomes unexplainable.
+
+## An uncertain upload
+
+`unknown_requires_verification` means the uploader died after Immich may have
+accepted the files. It is **not** retryable. Verification asks the server whether it
+holds the recorded SHA-1 and answers present, absent, or inconclusive. An
+inconclusive answer is resolved by you, with your evidence and name recorded in the
+batch's history.
+
+## A failed migration
+
+A pending schema change is snapshotted before it is applied. If the upgrade fails,
+the previous database and its `pre-migration` backup are both intact and the error
+log names the backup directory. Stop everything and run the
+[restore drill](installation.md#restoring).
+
+## A restored backup
+
+After restoring, run a scan. Paths are reconciled against the real library and
+identities are preserved where hashes match. Anything that does not match becomes a
+visible `stale` or `divergent` state instead of being quietly accepted.
+
+Mount every archive medium the manifest names before archiving again: the database
+records where archived originals live, it does not contain them.
+
+## A job that will not start
+
+Check, in this order: is a worker running; is another mutating job holding the lane
+(`lock_held`); is an interrupted rename blocking everything
+(`rename_recovery_required`); is the library lock held by a process that is still
+alive (exit code `2` names the holder).
+
+## What is never automatic
+
+No file is deleted, no folder is renamed, no upload is retried, and no archive source
+is removed without either an explicit confirmation from you or a verification the
+application performed itself. If you are reading this page because something happened
+that you did not approve, that is a bug worth reporting — with the diagnostics output
+and the relevant journal, both of which are safe to share: they carry no secrets.

docs/stages/albums.md

@@ -0,0 +1,47 @@
+# Album proposals
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![Reviewing an album proposal](../images/albums.png)
+
+**What it is for.** Turning a folder of analysed photographs into a name a person
+would have chosen, before any folder is touched.
+
+**What you decide.** The final name. The proposal is a starting point with its
+reasoning attached; you edit it, accept it, or ignore it.
+
+**What it changes.** A row per album: proposed name, rationale, confidence, and your
+final name, with a version. **Approving renames nothing.** Not one file moves at this
+stage — approval only marks a name as agreed, and the [rename stage](renames.md) is
+where it becomes a plan you have to confirm separately.
+
+**What it refuses.** A name containing `/ \ : * ? " < > |`, a reserved device name, or
+one that collides with an existing folder is rejected while you type and again on the
+server. Approval is refused when the evidence changed since the proposal was
+generated — the proposal is stale, and regenerating is the honest fix. Editing with a
+stale version returns a conflict and shows you the server's truth rather than
+overwriting it.
+
+## Reading the view
+
+The left pane lists albums with their state: `none`, `proposed`, `edited`,
+`approved`, `error`, or `stale`. The right pane shows the evidence the name was built
+from — date range, dominant tags, locations, counts — then the suggested name, the
+rationale, the confidence, and an editable final name.
+
+The default naming shape is predictable and sortable:
+
+```text
+YYYY-MM — Place — Event
+YYYY — Event
+Place — Event
+```
+
+## While a rename is unresolved
+
+Generating and approving proposals is blocked while an interrupted rename is
+outstanding, with `409 rename_recovery_required`. Resolve the rename first: building
+new names on top of a half-applied move is how a library becomes hard to reason
+about.
+
+Next: [renames](renames.md).

docs/stages/analysis.md

@@ -0,0 +1,39 @@
+# Analysis
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![The analysis view](../images/analysis.png)
+
+**What it is for.** Describing what a photograph shows, so albums can be named from
+evidence and the library can be searched by content.
+
+**What you decide.** When to run it, and over what scope. The descriptions themselves
+come from the configured vision provider.
+
+**What it changes.** For each eligible photo: a stored result — description, tags,
+approximate year, location hint, model and prompt version — and then an EXIF
+checkpoint that merges a **managed caption segment** and additive keywords into the
+file, reads them back, and verifies that nothing else moved. The file's SHA-256 is
+refreshed after the write.
+
+**What it refuses.** Anything not confirmed SFW. Anything not canonical. A malformed
+provider response is quarantined rather than stored. Keywords are only ever added,
+never removed, because EXIF keywords carry no ownership and deleting a generated one
+could delete yours.
+
+## Running it
+
+The view shows eligible, analysed, pending, and error counts, and the job's live
+progress. Starting a second mutating job while it runs is refused — that is the
+one-writer rule, not a queue.
+
+Cancelling drains safely: completed items stay completed, and resuming continues
+rather than restarting. A photo may be sent to the provider twice if a crash happens
+mid-item, but its stored result and its EXIF are written once.
+
+## Costs
+
+Each analysed photo is a provider call. Resolving duplicates first is what keeps that
+number honest, and the counts here are the ones to check before starting a large run.
+
+Next: [album proposals](albums.md).

docs/stages/archive.md

@@ -0,0 +1,43 @@
+# Archive
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![Archive locations and plans](../images/archive.png)
+
+**What it is for.** Moving a finished album out of active storage onto another disk,
+while keeping everything the library knows about it.
+
+**What you decide.** Which album, which destination, and whether to accept the
+reclaimed space in exchange for needing that medium mounted to see the originals
+again.
+
+**What it changes.** Files are copied to the archive location, verified there, and
+only then removed from the library. The asset keeps its id, its hashes, its
+decisions, its analysis, its upload history, and a durable preview thumbnail;
+`current_path` becomes null and availability becomes `archived_online` or
+`archived_offline`.
+
+**What it refuses.** Preflight blocks on: an unverified upload, a checksum that no
+longer matches the uploaded bytes, an unmounted or unwritable destination,
+insufficient free space plus the configured reserve, a destination that already
+holds unexpected paths, a missing durable thumbnail, and any conflicting job. The
+source is **never** removed before the archived copy is verified — not because Immich
+reported success, which is an ingest, not a backup.
+
+## Offline is not missing
+
+An archived photo whose medium is unplugged is `archived_offline`. It still appears
+in search, still participates in duplicate detection through its retained hashes and
+thumbnail, and is never reported as lost. If a full-resolution comparison is needed,
+the application asks you to mount the named medium rather than guessing.
+
+## Restore
+
+Restore is planned and journaled like everything else: the medium must be online, the
+bytes are copied back and verified into a collision-free destination, a new active
+path is registered, and a reconciliation scan follows. Existing safety, analysis,
+EXIF, and upload state stay valid when hashes match — and when they do not, the
+result is a visible `divergent` state rather than silent acceptance of a different
+file.
+
+Next: [diagnostics](diagnostics.md).

docs/stages/diagnostics.md

@@ -0,0 +1,49 @@
+# Diagnostics and library statistics
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![Library statistics](../images/statistics.png)
+
+**What it is for.** Answering "is this installation healthy, and what is in this
+library?" — the first thing to look at when a stage behaves unexpectedly.
+
+**What you decide.** Nothing. Both are read-only.
+
+**What it changes.** Nothing.
+
+**What it refuses.** Nothing — both are reads, and both stay available while a job
+holds the library. That is deliberate: the moment you most need to know what the
+installation is doing is while it is busy.
+
+## Statistics
+
+The Stats view summarises the library itself: how many photos are analysed, the
+common tags, the distribution across albums and years. It answers questions about
+your photographs.
+
+## Diagnostics
+
+Diagnostics answers questions about the *installation*, and lives at
+`GET /api/v1/diagnostics` and on the command line:
+
+```bash
+python -m photo_pipeline diagnostics
+```
+
+It reports the database, write-ahead log, thumbnail cache, uploader reports, backups,
+and logs as separate sizes, plus free space, the tool versions it found against the
+ones the image pinned, and which locks are held and by whom.
+
+Its warnings are the ones worth acting on:
+
+| warning | means |
+|---|---|
+| `disk_low` / `disk_critical` | free space is running out; mutating stages stop before the reserve |
+| `cache_over_quota` | the thumbnail cache exceeds its configured quota |
+| `wal_growth` | the write-ahead log is outgrowing its database — usually a long-running reader |
+| `tool_version_drift` | the installed `exiftool` or `immich-go` is not the version the image pinned |
+| `legacy_process_active` | the frozen command-line tools are writing this library. Stop them |
+| `no_roots` | no library root is configured, so there is nothing to work on |
+
+An empty `warnings` list on a fresh installation is what the
+[first-run checklist](../installation.md#first-run-checklist) is looking for.

docs/stages/duplicates.md

@@ -0,0 +1,36 @@
+# Duplicate review
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![The duplicate cluster list](../images/duplicates.png)
+
+**What it is for.** Deciding which file is *the* copy of a picture, before anything
+expensive or irreversible happens to the others.
+
+**What you decide.** For each cluster: keep the recommended canonical, choose a
+different one, keep everything as variants, declare it not a duplicate, or defer.
+
+**What it changes.** Only the decision, recorded as an auditable event. **No file is
+ever deleted.** Non-canonical copies stay exactly where they are; they are simply
+excluded from analysis and upload.
+
+**What it refuses.** Exact byte and identical-pixel matches may be accepted on the
+recommendation. Anything fuzzy — a crop, a re-encode, a burst frame — requires an
+explicit confirmation, because a perceptual hash is evidence, not proof.
+
+## Reading a cluster
+
+Each member shows its path, role, pHash distance, and size, with synchronised zoom
+across the previews. The recommendation is visible but never pre-applied for fuzzy
+matches. The confidence band tells you how much the machine is claiming.
+
+Rejecting a pair records a negative link, so a later rescan does not keep proposing
+the same wrong match.
+
+## Why first
+
+Resolving duplicates before safety and analysis is what stops you reviewing and
+paying for the same photograph three times. It also means the album evidence is built
+from one copy of each picture rather than a skewed count.
+
+Next: [safety review](safety.md).

docs/stages/inventory.md

@@ -0,0 +1,39 @@
+# Inventory and discovery
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![The inventory view](../images/inventory.png)
+
+**What it is for.** Finding every supported photo in the configured library roots and
+giving each one a permanent identity, so that everything afterwards can refer to a
+picture rather than a path.
+
+**What you decide.** Nothing. This stage is the only one with no judgement in it.
+
+**What it changes.** On disk, nothing at all — discovery reads. In the database it
+records each photo's path, size, timestamps, full-file SHA-256, normalised pixel hash,
+and perceptual hash, and it opens a path-history entry.
+
+**What it refuses.** Anything under an `_IGNORE/` directory is never traversed,
+counted, hashed, or previewed. Unsupported extensions and unreadable files are
+reported rather than skipped silently. Nothing outside the configured roots is
+reachable, including through a symlink.
+
+## Reading the view
+
+Each row is one asset: its current path, availability, whether the file is present,
+and its size. The filter searches paths; the availability selector separates active
+photos from archived ones.
+
+A **rescan** after moving files around outside the application is the normal way to
+reconcile: a file that moved keeps its identity, because identity is the hash and the
+id, not the location.
+
+## What good looks like
+
+The count matches what you expect, `_IGNORE/` contents are absent, and nothing shows
+as missing. A photo listed as missing means the file is no longer at its recorded
+path and no new path matched its hashes — that is a question for you, not something
+the scanner resolves by guessing.
+
+Next: [duplicate review](duplicates.md).

docs/stages/renames.md

@@ -0,0 +1,46 @@
+# Renames
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![The rename plan preview](../images/renames.png)
+
+**What it is for.** Applying approved album names to the actual folders — the first
+stage that changes your filesystem.
+
+**What you decide.** Whether to apply the plan, after reading it. The confirmation
+names the plan, its version, and its checksum, so what you approve is what runs.
+
+**What it changes.** Folders move. For each operation: the intent is journaled
+*before* the disk is touched, the move is made, `assets.current_path` is updated by
+id in one transaction, the old path is closed and a new one opened in path history,
+the result is verified, and only then is the operation complete.
+
+**What it refuses.** A plan is invalid — not merely warned about — when a source is
+missing or changed, two operations target the same destination, a destination already
+exists, a path would leave the library or enter `_IGNORE/`, or a source is a symlink.
+Case-only renames and cross-filesystem moves are allowed but flagged, because they
+take a different, staged route. A plan whose checksum no longer matches is refused
+rather than reinterpreted.
+
+## Reading the preview
+
+Every operation shows both full paths, the kind of move (`rename`, `case-only
+rename`, `cross-filesystem move`), how many photos it affects, its journal state, and
+any issue with its severity. The plan can be exported as JSON before you commit to it.
+
+**A run cannot be stopped part-way.** It can be interrupted — by a crash, a power
+cut, a killed container — and interruption is recoverable, but there is no cancel
+button once it starts. That is stated on the confirmation, not hidden in a manual.
+
+## After an interruption
+
+The recovery panel lists each unresolved operation with a verdict read from the
+journal *and the disk*: resumable, safely rollbackable, or needing a person. It never
+guesses from a missing path alone. Until it is resolved, unrelated mutations are
+refused with `409 rename_recovery_required`.
+
+Rollback is recovery, not undo. A completed operation is terminal — the button only
+appears for operations that are actually reversible. See
+[recovery](../recovery.md).
+
+Next: [upload](uploads.md).

docs/stages/safety.md

@@ -0,0 +1,43 @@
+# Safety review
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![The safety review queue](../images/safety.png)
+
+**What it is for.** Deciding which photographs may be sent to a cloud vision
+provider. This is the privacy gate the rest of the design is built around.
+
+**What you decide.** `sfw`, `nsfw`, or defer — per photo, or in bulk from the filters.
+A local model can score first to order the queue, but the score is a suggestion; the
+decision is yours.
+
+**What it changes.** The decision is stored in the database *and* projected into the
+file: one mutually exclusive `sfw` or `nsfw` keyword written into `Keywords` and
+`Subject`. The write is merged with existing metadata, read back, and verified, and
+the file's SHA-256 is refreshed afterwards.
+
+**What it refuses.** An undecided or deferred photo does not reach the vision
+provider, and does not reach Immich either. If the read-back shows that a field the
+stage does not own has changed, the checkpoint is marked `divergent`, the asset is not
+marked verified, and the next mutating stage is blocked rather than proceeding on
+metadata nobody trusts.
+
+## The rule that matters
+
+> Only a confirmed `sfw` photo may enter cloud content analysis. A confirmed `nsfw`
+> photo skips analysis entirely but remains eligible for upload to Immich once its
+> keyword is verified.
+
+That is why marking something NSFW is not a punishment: it routes the photo around an
+external service while keeping it in your own library workflow.
+
+The gate is re-checked *after* the provider call as well. If a decision flips to NSFW
+while an analysis is in flight, the result is discarded rather than stored.
+
+## Reading the view
+
+The tabs filter by state. Each row shows the path, the model's score, its suggestion,
+your decision, and an `✓ exif` badge once the keyword is verified on disk. A row
+without that badge has a decision the file does not yet carry.
+
+Next: [analysis](analysis.md).

docs/stages/uploads.md

@@ -0,0 +1,45 @@
+# Upload
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![Upload preflight](../images/uploads.png)
+
+**What it is for.** Sending an approved album to Immich through `immich-go`, with an
+audit trail of exactly which bytes went.
+
+**What you decide.** Which albums, and whether to proceed once the preflight has
+listed its blockers. Upload is never an automatic consequence of renaming.
+
+**What it changes.** Nothing locally. On the Immich server, assets appear. Locally a
+batch is recorded: the album, the asset ids, the redacted command, the uploader
+version, the pre-upload SHA-256 **and** the SHA-1 Immich matches on, the output log,
+and the outcome counts.
+
+**What it refuses.** Preflight blocks on: missing credentials, an unreachable server,
+a missing `immich-go`, an unresolved rename, an undecided or deferred safety
+decision, an unverified EXIF checkpoint, incomplete analysis for an SFW photo, a file
+whose bytes changed since it was checkpointed, and a partial scope you have not
+explicitly accepted. The approval is then **re-proved immediately before the uploader
+runs** — bytes edited after you approved fail with `stale_preflight` and the uploader
+never starts.
+
+## Reading the view
+
+The scope shows exactly which albums and how many photos. The command preview is the
+real command with the API key removed; the key never reaches the browser and never
+reaches a log.
+
+## Uncertain is not failed
+
+If the process dies after the server accepted files, the batch becomes
+`unknown_requires_verification` — not "failed", and **not retryable**. The server may
+already hold the photographs, and uploading again would create duplicates or
+upgrades. Verification asks Immich about the recorded SHA-1 and answers present,
+absent, or inconclusive; an inconclusive answer is resolved by you, with the evidence
+recorded.
+
+If a file's bytes change after a successful upload, it is marked
+`changed_after_upload` and you are warned that uploading again may create or upgrade
+an asset rather than doing nothing.
+
+Next: [archive](archive.md).