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

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.