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

2026-08-23 23:37:31 +02:00
parent 282e8b51e6
commit f1442527a2
34 changed files with 997 additions and 37 deletions
--- a/docs/stages/safety.md
+++ b/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).