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

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).