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

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.