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

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