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/renames.md
+++ b/docs/stages/renames.md
@@ -0,0 +1,46 @@
+# Renames
+
+[← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
+
+![The rename plan preview](../images/renames.png)
+
+**What it is for.** Applying approved album names to the actual folders — the first
+stage that changes your filesystem.
+
+**What you decide.** Whether to apply the plan, after reading it. The confirmation
+names the plan, its version, and its checksum, so what you approve is what runs.
+
+**What it changes.** Folders move. For each operation: the intent is journaled
+*before* the disk is touched, the move is made, `assets.current_path` is updated by
+id in one transaction, the old path is closed and a new one opened in path history,
+the result is verified, and only then is the operation complete.
+
+**What it refuses.** A plan is invalid — not merely warned about — when a source is
+missing or changed, two operations target the same destination, a destination already
+exists, a path would leave the library or enter `_IGNORE/`, or a source is a symlink.
+Case-only renames and cross-filesystem moves are allowed but flagged, because they
+take a different, staged route. A plan whose checksum no longer matches is refused
+rather than reinterpreted.
+
+## Reading the preview
+
+Every operation shows both full paths, the kind of move (`rename`, `case-only
+rename`, `cross-filesystem move`), how many photos it affects, its journal state, and
+any issue with its severity. The plan can be exported as JSON before you commit to it.
+
+**A run cannot be stopped part-way.** It can be interrupted — by a crash, a power
+cut, a killed container — and interruption is recoverable, but there is no cancel
+button once it starts. That is stated on the confirmation, not hidden in a manual.
+
+## After an interruption
+
+The recovery panel lists each unresolved operation with a verdict read from the
+journal *and the disk*: resumable, safely rollbackable, or needing a person. It never
+guesses from a missing path alone. Until it is resolved, unrelated mutations are
+refused with `409 rename_recovery_required`.
+
+Rollback is recovery, not undo. A completed operation is terminal — the button only
+appears for operations that are actually reversible. See
+[recovery](../recovery.md).
+
+Next: [upload](uploads.md).