krino: release 0.0.1 — man pages, install, examples, cross and release, README, changelogv0.0.1

Also: undo removes the directories its run created; a hardlink is never a
duplicate of its own other name; a flag written before "undo" is honoured;
--version prints no leading v. Duplicate conditions with different scopes
not sharing an original is documented as a known limitation.

30 files changed, 2939 insertions, 50 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b5adf3e..5bd80c8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,4 +2,34 @@
 
 ## Unreleased
 
-- Initial development: config language, `krino init`, `krino new`, `krino check`, `krino explain`, and the `-n` dry run.
+## 0.0.1 — 2026-09-13
+
+- Per-directory rule files, a main file listing which directories run, and a
+  template for new ones.
+- Conditions with `and`, `or` and `not` over type, name, path, content, size,
+  age and duplicates.
+- Actions copy, move, rename and delete (to Trash by default), chained.
+- Plan, review and approve — all files or per file — with `-y` to skip
+  review.
+- A log of every step, and `krino undo`.
+- Placeholders in destinations and new names.
+- Builds for Linux, FreeBSD and OpenBSD.
+
+Performance: no threshold or target for 0.0.1. These were measured during
+development and are reported rather than promised — throughput is dominated
+by external content extractors, not by krino itself:
+
+- Full plans over a real folder of about 265 files, 164 of them needing text
+  extraction through `pdftotext` at roughly 80 ms each, measured between
+  about 13 and 20 s across runs.
+- A synthetic benchmark during development planned a generated tree of 4,405
+  files needing no extraction in 1.09 s. That benchmark is not `make bench`,
+  whose generated tree is smaller.
+
+Files that share a byte size but differ in content — six templated invoices,
+for instance — are still told apart, because the duplicate check hashes the
+first and last 64 KiB and then the whole file rather than trusting size.
+
+Known limitation: `(duplicate)` conditions with different scopes can elect
+different originals for the same content, and within one directory's rules
+this can select every copy for deletion — see `krino.conf(5)`, DUPLICATES.
diff --git a/Makefile b/Makefile
index 9dfc7d4..62e2b7e 100644
--- a/Makefile
+++ b/Makefile
@@ -4,11 +4,15 @@
 DESTDIR ?=
 PREFIX  ?= $(HOME)/.local
 BINDIR   = $(DESTDIR)$(PREFIX)/bin
+SHAREDIR = $(DESTDIR)$(PREFIX)/share
+MANDIR   = $(SHAREDIR)/man
+DOCDIR   = $(SHAREDIR)/doc/krino
 BIN      = krino
 VERSION != git describe --tags --always --dirty 2>/dev/null || echo dev
 LDFLAGS  = -s -w -X main.version=$(VERSION)
+CROSS_PLATFORMS = linux/amd64 linux/arm64 freebsd/amd64 openbsd/amd64
 
-.PHONY: all help build install uninstall test vet fmt ci install-hooks clean
+.PHONY: all help build install uninstall test vet fmt lint ci bench cross dist release deps install-hooks clean
 
 all: build
 
@@ -17,16 +21,36 @@ help: ## show this help
 	  awk 'BEGIN {FS = ":.*## "}; {printf "  %-10s %s\n", $$1, $$2}'
 	@echo "  version: $(VERSION)   prefix: $(PREFIX)"
 
-build: ## build ./krino; Go fetches module dependencies itself
+build: ## build ./krino; Go fetches module dependencies itself; reports missing optional extractors
 	CGO_ENABLED=0 go build -trimpath -ldflags "$(LDFLAGS)" -o $(BIN) ./cmd/krino
+	@missing=""; \
+	for t in pdftotext antiword catdoc xls2csv catppt; do \
+	  command -v "$$t" >/dev/null 2>&1 || missing="$$missing $$t"; \
+	done; \
+	if [ -n "$$missing" ]; then \
+	  echo "optional extractors not found:$$missing (needed for some content rules; run 'make deps' or install by hand)"; \
+	else \
+	  echo "all optional extractors found: pdftotext antiword catdoc xls2csv catppt"; \
+	fi
 
-install: build ## install to $(PREFIX)/bin
-	mkdir -p $(BINDIR)
+install: build ## install binary, man pages and examples under $(PREFIX)
+	mkdir -p $(BINDIR) $(MANDIR)/man1 $(MANDIR)/man5 $(DOCDIR)/examples
 	rm -f $(BINDIR)/$(BIN)
 	install -m 755 $(BIN) $(BINDIR)/$(BIN)
+	install -m 644 man/krino.1 $(MANDIR)/man1/krino.1
+	install -m 644 man/krino.conf.5 $(MANDIR)/man5/krino.conf.5
+	install -m 644 examples/*.conf $(DOCDIR)/examples/
+	install -m 644 docs/sexp-primer.md $(DOCDIR)/sexp-primer.md
 
-uninstall: ## remove the installed binary
+uninstall: ## remove everything install placed, and nothing else
 	rm -f $(BINDIR)/$(BIN)
+	rm -f $(MANDIR)/man1/krino.1
+	rm -f $(MANDIR)/man5/krino.conf.5
+	rm -f $(DOCDIR)/sexp-primer.md
+	for f in examples/*.conf; do \
+	  rm -f $(DOCDIR)/examples/$$(basename "$$f"); \
+	done
+	-rmdir $(DOCDIR)/examples $(DOCDIR) 2>/dev/null
 
 test: ## run the tests
 	go test ./...
@@ -37,7 +61,10 @@ vet: ## go vet
 fmt: ## gofmt the tree
 	gofmt -w .
 
-ci: ## the gate: gofmt, vet, tests, dependencies, no personal data staged
+lint: ## lint the man pages
+	scripts/man-lint
+
+ci: ## the gate: gofmt, vet, tests, dependencies, no personal data staged, man page lint
 	@test -z "$$(gofmt -l .)" || { echo "gofmt needed:"; gofmt -l .; exit 1; }
 	go vet ./...
 	GOOS=freebsd CGO_ENABLED=0 go vet ./...
@@ -46,8 +73,72 @@ ci: ## the gate: gofmt, vet, tests, dependencies, no personal data staged
 	@deps=$$(go list -deps ./... | grep -E '^[a-z0-9-]+\.[a-z]+/' | grep -vE '^golang\.org/x/(term|text|sys)(/|$$)' || true); \
 	  test -z "$$deps" || { echo "unexpected dependencies:"; echo "$$deps"; exit 1; }
 	@scripts/leak-check
+	@scripts/man-lint
 	@echo "ci ok"
 
+bench: ## run the Go benchmarks on generated trees
+	go test -run '^$$' -bench . -benchmem ./...
+
+cross: ## cross-compile linux/amd64, linux/arm64, freebsd/amd64, openbsd/amd64 into dist/krino-$(VERSION)-<os>-<arch>/
+	@case '$(VERSION)' in \
+	  ''|*[!A-Za-z0-9._+-]*) \
+	    echo "refusing: VERSION must contain only letters, digits, and the characters . - _ +" >&2; \
+	    exit 1 ;; \
+	esac
+	@for t in $(CROSS_PLATFORMS); do \
+	  os=$${t%/*}; arch=$${t#*/}; \
+	  dir=dist/krino-$(VERSION)-$$os-$$arch; \
+	  case "$$dir" in \
+	    dist/krino-*) rm -rf "$$dir" ;; \
+	    *) echo "refusing to remove unexpected path: $$dir" >&2; exit 1 ;; \
+	  esac; \
+	  mkdir -p "$$dir"; \
+	  echo "cross: $$os/$$arch -> $$dir/$(BIN)"; \
+	  CGO_ENABLED=0 GOOS=$$os GOARCH=$$arch go build -trimpath -ldflags "$(LDFLAGS)" -o "$$dir/$(BIN)" ./cmd/krino || exit 1; \
+	  for f in README.md LICENSE CHANGELOG.md man/krino.1 man/krino.conf.5 docs/sexp-primer.md; do \
+	    test -f "$$f" && cp "$$f" "$$dir/$$(basename "$$f")"; \
+	  done; \
+	  test -d examples && cp -r examples "$$dir/examples"; \
+	done
+
+# dist: cross plus tarballs and SHA256SUMS, no tag. Undocumented plumbing so
+# `make release` is verifiable without tagging; deliberately absent from
+# `make help` (no `## ` comment).
+dist: cross
+	@command -v sha256sum >/dev/null 2>&1 && SUM=sha256sum || SUM="sha256 -r"; \
+	  tarballs=""; \
+	  cd dist && \
+	  for t in $(CROSS_PLATFORMS); do \
+	    os=$${t%/*}; arch=$${t#*/}; \
+	    name=krino-$(VERSION)-$$os-$$arch; \
+	    tar czf "$$name.tar.gz" "$$name" || exit 1; \
+	    tarballs="$$tarballs $$name.tar.gz"; \
+	  done && \
+	  $$SUM $$tarballs > SHA256SUMS
+
+release: ## make cross + tarballs + SHA256SUMS in dist/, then tag v$(VERSION) (annotated; never pushes) - usage: make release VERSION=0.0.1
+	@case '$(VERSION)' in \
+	  ''|*[!A-Za-z0-9._+-]*) \
+	    echo "refusing: VERSION must contain only letters, digits, and the characters . - _ +" >&2; \
+	    exit 1 ;; \
+	esac
+	@default_version=$$(git describe --tags --always --dirty 2>/dev/null || echo dev); \
+	  test -n "$(VERSION)" && test "$(VERSION)" != "$$default_version" || \
+	  { echo "refusing: pass an explicit VERSION, e.g. make release VERSION=0.0.1"; exit 1; }
+	@test -z "$$(git status --porcelain)" || \
+	  { echo "refusing: working tree is not clean (git status --porcelain)"; exit 1; }
+	@git rev-parse -q --verify refs/tags/v$(VERSION) >/dev/null 2>&1 && \
+	  { echo "refusing: tag v$(VERSION) already exists"; exit 1; } || true
+	@test -f README.md || \
+	  { echo "refusing: README.md is missing"; exit 1; }
+	$(MAKE) ci
+	$(MAKE) dist VERSION=$(VERSION)
+	git tag -a "v$(VERSION)" -m "krino v$(VERSION)"
+	@echo "release v$(VERSION) built in dist/; tag v$(VERSION) created, not pushed"
+
+deps: ## install the optional content extractors; may ask for privileges
+	scripts/deps
+
 install-hooks: ## install the pre-commit hook that runs the leak check
 	install -m 755 scripts/hooks/pre-commit "$$(git rev-parse --git-path hooks)/pre-commit"
 
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4b7d4c3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,214 @@
+# krino
+
+krino sorts the files in one or more directories by rules: conditions on a
+file's type, name, path, size, age, text content or duplicate status,
+combined with `and` / `or` / `not`, that trigger actions — copy, move,
+rename, delete (to the Trash by default), chained in the order written. It
+shows the plan before touching anything, lets you approve all of it or file
+by file, logs every step, and can undo a run. Version 0.0.1 is the engine
+and this command-line interface: per-directory rule files, placeholders in
+destinations and new names, and builds for Linux, FreeBSD and OpenBSD. It is
+not a GUI (that comes later), a watch mode, OCR, EXIF dates, macOS or
+Windows support, a content cache, a shell-command action, or a way to look
+inside archives.
+
+## Install
+
+```
+make && make install
+```
+
+`make` builds `./krino`; Go fetches the module dependencies itself. `make
+install` puts the binary in `$PREFIX/bin` (default `~/.local/bin`), the man
+pages in `$PREFIX/share/man`, and the examples and `docs/sexp-primer.md` in
+`$PREFIX/share/doc/krino`.
+
+Some `(content ...)` tests need external extractors — `pdftotext` for PDF,
+`antiword`/`catdoc` for legacy Word, `xls2csv`/`catppt` for legacy Excel and
+PowerPoint. `make build` reports which of these are missing; install them
+with:
+
+```
+make deps
+```
+
+`make deps` is the only target that asks for privileges — it calls the
+system package manager (`apt-get`, `pkg`, or `pkg_add`, depending on the
+OS). Plain `make` never does.
+
+## The 60-second quickstart
+
+Everything below happens in `/tmp/krino-demo` and a scratch config under
+`/tmp/krino-xdg`, so it never touches a real directory or your real krino
+config. Copy-paste it as written and your output should match what's pasted
+here, except for the run id and timestamps, which are different every time.
+
+Create a handful of files of different types:
+
+```
+mkdir -p /tmp/krino-demo
+cd /tmp/krino-demo
+for f in acme-invoice.pdf photo.jpg podcast.mp3 archive.zip app.deb notes.txt; do
+  printf 'demo file: %s\n' "$f" >"$f"
+done
+```
+
+Point krino at a scratch config for this walkthrough:
+
+```
+export XDG_CONFIG_HOME=/tmp/krino-xdg/config
+export XDG_STATE_HOME=/tmp/krino-xdg/state
+export XDG_DATA_HOME=/tmp/krino-xdg/data
+```
+
+Set it up:
+
+```
+$ krino init
+created /tmp/krino-xdg/config/krino/krino.conf
+created /tmp/krino-xdg/config/krino/template.conf
+next: krino new NAME PATH, for example: krino new downloads ~/Downloads
+$ krino new demo /tmp/krino-demo
+created /tmp/krino-xdg/config/krino/dirs/demo.conf and added "demo" to include
+edit its rules, then check them with: krino check demo
+```
+
+`krino new` copied the template to `dirs/demo.conf` and filled in the path.
+Replace its body with a small rule. The built-in `min-age` is 2 minutes
+(files skip as "busy" while they might still be downloading), which the
+demo files we just created are younger than, so this also turns it down to
+0 for this directory:
+
+```
+cat > "$XDG_CONFIG_HOME/krino/dirs/demo.conf" <<'EOF'
+;; -*- mode: lisp -*-
+;; vim: set ft=lisp :
+
+(path "/tmp/krino-demo")
+(min-age 0s)                       ; demo files are seconds old; built-in is 2m
+
+(rule "acme"
+  (when (name "acme"))
+  (move "Filed/Acme"))
+EOF
+```
+
+This one rule matches any file whose name contains "acme" and moves it into
+`Filed/Acme`. See what it would do, without changing anything:
+
+```
+$ krino -n demo
+krino: demo  /tmp/krino-demo
+6 scanned · 1 to act on · 0 warnings · 0.00s
+
+  #  file              actions                rule
+  1  acme-invoice.pdf  move    → Filed/Acme/  acme  name "acme"
+
+not acted on: 5 unmatched   (-v lists them)
+```
+
+Without `-n` or `-y`, `krino demo` shows the same plan and then asks, one
+key at a time, no Enter needed:
+
+```
+[a] apply all  [c] choose per file  [s] skip this directory  [q] quit
+```
+
+`c` asks about each file in turn:
+
+```
+  [y] yes  [n] no  [a] yes to this and all remaining  [d] done, apply chosen so far  [q] quit, apply nothing
+```
+
+Approval is per file: a file's whole chain runs, or none of it. A README
+can't paste a session it didn't actually run in a terminal, so here we
+apply directly with `-y`, which shows the same plan and applies it without
+asking:
+
+```
+$ krino -y demo
+krino: demo  /tmp/krino-demo
+6 scanned · 1 to act on · 0 warnings · 0.00s
+
+  #  file              actions                rule
+  1  acme-invoice.pdf  move    → Filed/Acme/  acme  name "acme"
+
+not acted on: 5 unmatched   (-v lists them)
+1 applied · 0 failed · 0 declined
+```
+
+`acme-invoice.pdf` is now in `Filed/Acme/`. Every run is logged:
+
+```
+$ krino log
+20260913T005509-db14  2026-09-13 00:55  demo  1 moved
+```
+
+And every run can be undone — `undo` alone would show its own plan and ask
+the same way, with a menu of its own:
+
+```
+[a] apply all  [c] choose per file  [s] skip  [q] quit
+```
+
+`-y` applies it directly:
+
+```
+$ krino undo -y
+krino: undo 20260913T005509-db14
+1 files · 1 to reverse · 0 refused
+
+  #  file                   steps
+  1  demo/acme-invoice.pdf  undo-move      → /tmp/krino-demo/acme-invoice.pdf
+                            undo-mkdir     /tmp/krino-demo/Filed/Acme
+                            undo-mkdir     /tmp/krino-demo/Filed
+1 applied · 0 failed · 0 declined
+```
+
+`/tmp/krino-demo` is back exactly as the first `printf` loop left it — that
+is what `krino undo` is for. Delete both scratch directories when you're
+done: `rm -rf /tmp/krino-demo /tmp/krino-xdg`.
+
+## Configuration
+
+Rules are s-expressions. `docs/sexp-primer.md` is a short tutorial on the
+syntax with no Lisp background assumed; `krino.conf(5)` (`man/krino.conf.5`
+in the source, installed as a man page) is the reference for every form,
+setting and condition. `examples/` has four worked rule files: by type, by
+content (invoices), by age (old installers), and renaming (screenshots).
+
+Rules live in `$XDG_CONFIG_HOME/krino` (default `~/.config/krino`) —
+**never in this repository**. A leak check guards that: it runs in `make ci`,
+and on every commit only after `make install-hooks`. It refuses staged files
+that contain your home directory's path or an email address, and it catches
+rule content only when a private pattern list is configured with
+`git config krino.leakpatterns FILE`.
+
+## Safety
+
+- `(delete)` moves a file to the freedesktop.org Trash by default, not
+  `unlink(2)` — recoverable, by hand or with `krino undo`. `(delete
+  permanent)` is the explicit opt-out, and undo can never reverse it.
+- Every step of every run is appended to `$XDG_STATE_HOME/krino/krino.log`
+  (default `~/.local/state/krino/krino.log`), tab-separated and
+  `grep`-able.
+- `krino undo` reverses the most recent run, or a specific one by id from
+  `krino log`. A reversal that the world has moved on since (the target is
+  gone, changed, or the original path is occupied again) is refused for
+  that file rather than guessed at.
+- `-n` prints the plan and changes nothing, ever — no config is written, no
+  file is touched, nothing is logged.
+
+## Status
+
+**0.0.1, local only.** The module path is `krino`; `go install
+krino@v0.0.1` only works once a remote is chosen and the imports are
+renamed to match (`docs/design.md`, §18). Until then, build from a clone.
+`krino -n --json`'s output shape is unstable before krino 1.0 — don't
+script against it yet.
+
+## License
+
+Everything in this repository — code, man pages, examples and the embedded
+templates — is GPL-3.0-or-later. Full text in `LICENSE`. Go files, shell
+scripts and man pages carry an SPDX identifier.
diff --git a/cmd/krino/history_test.go b/cmd/krino/history_test.go
index 2667b63..23b1e5f 100644
--- a/cmd/krino/history_test.go
+++ b/cmd/krino/history_test.go
@@ -315,3 +315,66 @@ func TestReviewUndoInvalidKeyReprompts(t *testing.T) {
 		t.Errorf("no mention of the rejected key:\n%s", out)
 	}
 }
+
+// TestGlobalDryRunBeforeUndo: -n written before the subcommand, the way
+// krino.1 teaches flags, is a dry run of the undo. It shows the plan,
+// exits 0, and moves nothing back.
+func TestGlobalDryRunBeforeUndo(t *testing.T) {
+	h := matchingFixture(t)
+	if code, _, errOut := runCLI(t, "-y"); code != 0 {
+		t.Fatalf("apply: %d %s", code, errOut)
+	}
+	filed := filepath.Join(h, "dl", "Work", "Acme", "inv1.txt")
+
+	code, out, errOut := runCLI(t, "-n", "undo")
+	if code != 0 || !strings.Contains(out, "undo-move") {
+		t.Errorf("-n undo: %d %q\n%s", code, errOut, out)
+	}
+	if _, err := os.Stat(filed); err != nil {
+		t.Errorf("-n undo moved a file: %v", err)
+	}
+	if _, out, _ = runCLI(t, "log"); strings.Contains(out, "undone") {
+		t.Errorf("-n undo marked the run undone:\n%s", out)
+	}
+}
+
+// TestGlobalDryRunBeforeUndoConflictsWithYes: -n before the subcommand and
+// -y after it is the same conflict as both after it: exit 2, nothing
+// changed.
+func TestGlobalDryRunBeforeUndoConflictsWithYes(t *testing.T) {
+	h := matchingFixture(t)
+	if code, _, errOut := runCLI(t, "-y"); code != 0 {
+		t.Fatalf("apply: %d %s", code, errOut)
+	}
+	filed := filepath.Join(h, "dl", "Work", "Acme", "inv1.txt")
+
+	code, _, errOut := runCLI(t, "-n", "undo", "-y")
+	if code != 2 || !strings.Contains(errOut, "-y and -n cannot be used together") {
+		t.Errorf("-n undo -y: %d %q", code, errOut)
+	}
+	if _, err := os.Stat(filed); err != nil {
+		t.Errorf("-n undo -y moved a file: %v", err)
+	}
+	if _, out, _ := runCLI(t, "log"); strings.Contains(out, "undone") {
+		t.Errorf("-n undo -y marked the run undone:\n%s", out)
+	}
+}
+
+// TestGlobalYesBeforeUndo: -y before the subcommand applies the undo.
+func TestGlobalYesBeforeUndo(t *testing.T) {
+	h := matchingFixture(t)
+	if code, _, errOut := runCLI(t, "-y"); code != 0 {
+		t.Fatalf("apply: %d %s", code, errOut)
+	}
+	filed := filepath.Join(h, "dl", "Work", "Acme", "inv1.txt")
+
+	if code, _, errOut := runCLI(t, "-y", "undo"); code != 0 {
+		t.Fatalf("-y undo: %d %s", code, errOut)
+	}
+	if _, err := os.Stat(filepath.Join(h, "dl", "inv1.txt")); err != nil {
+		t.Errorf("-y undo did not put the file back: %v", err)
+	}
+	if _, err := os.Stat(filed); !os.IsNotExist(err) {
+		t.Error("the filed copy survived -y undo")
+	}
+}
diff --git a/cmd/krino/main.go b/cmd/krino/main.go
index e204b5f..f5fdfea 100644
--- a/cmd/krino/main.go
+++ b/cmd/krino/main.go
@@ -9,12 +9,32 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"runtime/debug"
 	"strings"
 )
 
 // version is stamped by the Makefile with -ldflags "-X main.version=...".
 var version = "dev"
 
+// displayVersion returns the version to print for --version. The Makefile
+// stamps a git tag, which carries a leading "v" (required for
+// go install ...@v0.0.1, per design.md §14); that "v" belongs on the tag,
+// not in the output, so it is stripped here. A "go install" build carries no
+// ldflags, leaving version at its built-in "dev"; in that case fall back to
+// the build info Go embeds automatically.
+func displayVersion() string {
+	v := version
+	if v == "dev" {
+		if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" && info.Main.Version != "(devel)" {
+			v = info.Main.Version
+		}
+	}
+	if len(v) > 1 && v[0] == 'v' && v[1] >= '0' && v[1] <= '9' {
+		v = v[1:]
+	}
+	return v
+}
+
 const usage = `usage: krino [-y | -n] [-v] [--json] [-c FILE] [NAME...]
        krino init
        krino new NAME PATH
@@ -63,7 +83,7 @@ func run(args []string, stdout, stderr io.Writer) int {
 		return code
 	}
 	if *showVersion {
-		fmt.Fprintf(stdout, "krino %s\n", version)
+		fmt.Fprintf(stdout, "krino %s\n", displayVersion())
 		return 0
 	}
 	rest := fs.Args()
diff --git a/cmd/krino/main_test.go b/cmd/krino/main_test.go
index 1c01fa0..6e4df44 100644
--- a/cmd/krino/main_test.go
+++ b/cmd/krino/main_test.go
@@ -62,3 +62,24 @@ func TestSortNoConfig(t *testing.T) {
 		t.Fatalf("got %d %q", code, errOut)
 	}
 }
+
+func TestVersionStripsTheTagPrefix(t *testing.T) {
+	old := version
+	t.Cleanup(func() { version = old })
+	for _, tc := range []struct{ stamped, want string }{
+		{"v0.0.1", "krino 0.0.1\n"},
+		{"v0.0.1-3-gabc1234", "krino 0.0.1-3-gabc1234\n"},
+		{"v0.0.1-dirty", "krino 0.0.1-dirty\n"},
+		{"0.0.1", "krino 0.0.1\n"},
+		{"dev", "krino dev\n"},
+	} {
+		version = tc.stamped
+		var out, errOut strings.Builder
+		if code := run([]string{"--version"}, &out, &errOut); code != 0 {
+			t.Errorf("%s: exit %d", tc.stamped, code)
+		}
+		if out.String() != tc.want {
+			t.Errorf("stamped %q: got %q, want %q", tc.stamped, out.String(), tc.want)
+		}
+	}
+}
diff --git a/cmd/krino/sort_test.go b/cmd/krino/sort_test.go
index e482f44..fa9a7ca 100644
--- a/cmd/krino/sort_test.go
+++ b/cmd/krino/sort_test.go
@@ -110,3 +110,66 @@ func TestAllSkippedDirectoryReportsZeroAndLogsNothing(t *testing.T) {
 		t.Errorf("journal gained entries for a directory with nothing to act on:\n%s", data)
 	}
 }
+
+// TestPermanentDeleteOfDuplicatesUnderOverlappingDirKeepsACopy drives the
+// whole run end to end on the shape where a (duplicate "DIR") overlaps the
+// scanned tree: a recursive root holding Archive/x.pdf and a loose, older
+// x-copy.pdf with the same bytes, and a rule that permanently deletes
+// duplicates of anything under Archive. Whatever the verdicts, applying
+// the plan must leave the content on disk; the expected outcome is that
+// the archived copy stays and only the loose one goes.
+func TestPermanentDeleteOfDuplicatesUnderOverlappingDirKeepsACopy(t *testing.T) {
+	h := home(t)
+	dl := filepath.Join(h, "dl")
+	content := []byte("%PDF acme statement")
+	archived := filepath.Join(dl, "Archive", "x.pdf")
+	loose := filepath.Join(dl, "x-copy.pdf")
+	old := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+	for p, mt := range map[string]time.Time{archived: old.Add(time.Hour), loose: old} {
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, content, 0o644); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Chtimes(p, mt, mt); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if code, _, errOut := runCLI(t, "init"); code != 0 {
+		t.Fatal(errOut)
+	}
+	if code, _, errOut := runCLI(t, "new", "dl", dl); code != 0 {
+		t.Fatal(errOut)
+	}
+	rules := "(path \"~/dl\")\n(recursive yes)\n(min-age 0s)\n" +
+		"(rule \"dups\" (when (duplicate \"Archive\")) (delete permanent))\n"
+	if err := os.WriteFile(filepath.Join(h, ".config", "krino", "dirs", "dl.conf"), []byte(rules), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	code, out, errOut := runCLI(t, "-y")
+
+	var copies []string
+	err := filepath.WalkDir(dl, func(p string, d os.DirEntry, err error) error {
+		if err != nil || !d.Type().IsRegular() {
+			return err
+		}
+		if b, err := os.ReadFile(p); err == nil && string(b) == string(content) {
+			copies = append(copies, p)
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(copies) == 0 {
+		t.Fatalf("every copy was deleted (exit %d)\nstdout:\n%s\nstderr:\n%s", code, out, errOut)
+	}
+	if code != 0 {
+		t.Fatalf("run: %d %s", code, errOut)
+	}
+	if len(copies) != 1 || copies[0] != archived {
+		t.Errorf("copies left = %v, want only %s", copies, archived)
+	}
+}
diff --git a/cmd/krino/undo.go b/cmd/krino/undo.go
index 7ffe428..c773f9a 100644
--- a/cmd/krino/undo.go
+++ b/cmd/krino/undo.go
@@ -41,8 +41,10 @@ func init() { commands["undo"] = cmdUndo }
 // approval here is keyed by index rather than by name.
 func cmdUndo(g *globals, args []string, stdout, stderr io.Writer) int {
 	fs := flagSet("undo", g)
-	fs.BoolVar(&g.yes, "y", false, "")
-	fs.BoolVar(&g.dry, "n", false, "")
+	// The defaults are the values run() already parsed, so -y or -n written
+	// before "undo" survives registering them again here.
+	fs.BoolVar(&g.yes, "y", g.yes, "")
+	fs.BoolVar(&g.dry, "n", g.dry, "")
 	if code, ok := parse(fs, args, stdout, stderr); !ok {
 		return code
 	}
diff --git a/docs/design.md b/docs/design.md
index 8e4e914..9a15425 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -1,6 +1,6 @@
 # krino design
 
-Status: draft for review, 2026-09-11. Target release: **0.0.1**.
+Status: describes krino 0.0.1, 2026-09-13.
 
 krino (from Greek κρίνω, "to separate, to judge, to decide") sorts files in
 chosen directories by rules. A rule tests a file's type, name, path, size,
@@ -216,12 +216,22 @@ Candidates are the scanned files plus, for `(duplicate "DIR"...)`, every
 regular file under those directories (symlinks skipped). Files are grouped
 by size. Only groups of two or more are hashed: first the first and last
 64 KiB, then SHA-256 of the whole file. Empty files are never duplicates.
+Two names for the same file — the same device and inode, as a hardlink
+creates — are never duplicates of each other; they may still both be
+duplicates of a separate identical file.
 
 The **original** in each group is, in order of preference: a file under one
 of the given DIRs, then the oldest by mtime, then the shortest name, then
 the name that sorts first. `(duplicate)` is true for every other scanned
 file in the group.
 
+`(duplicate)` conditions with different scopes do not share an original:
+two conditions electing from different candidate sets can each treat a
+different file as the original of the same content, and within one
+directory's rules this can select every copy in a group for deletion. A
+run-wide election that keeps at least one copy of every group is not in
+0.0.1.
+
 ## 6. Content extraction
 
 | Format | Method |
@@ -427,9 +437,10 @@ not logged; declined files are.
 ## 10. Undo
 
 - `krino log` lists recent runs: id, time, directories, counts.
-- `krino undo` reverses the most recent run that has not been undone, in
-  every directory it touched; `krino undo RUN` a specific one. Undo runs
-  cannot themselves be undone.
+- `krino undo` reverses the most recent run, in every directory it
+  touched; if that run is itself an undo run, it is refused. An older run
+  is undone by naming it: `krino undo RUN`. Undo runs cannot themselves be
+  undone.
 - Undo builds a plan like any other, shown and approved the same way
   (`-y` and `-n` apply).
 
@@ -526,17 +537,19 @@ Rules for the GUI to come:
 - Measured before release on a real downloads directory of a few hundred
   files, about half of them PDFs, and reported in the release notes.
   **No performance target for 0.0.1.** Measured throughput is dominated by the
-  external extractors, not by krino: on a real folder of 265 files, 164 of them
-  needing `pdftotext` at roughly 80 ms each, a full plan takes 12-17 s, while a
-  synthetic tree of 4405 files needing no extraction takes 1.09 s. A single
-  threshold would therefore describe poppler's speed and the shape of one
-  folder rather than anything about krino, and would fail or pass for reasons
-  outside its control. Report the measurement; promise nothing. `make bench`
-  runs the Go benchmarks on generated trees.
+  external extractors, not by krino: on a real folder of about 265 files, 164
+  of them needing `pdftotext` at roughly 80 ms each, full plans measured
+  between about 13 and 20 s across runs, while a synthetic tree of 4405 files
+  needing no extraction takes 1.09 s. A single threshold would therefore
+  describe poppler's speed and the shape of one folder rather than anything
+  about krino, and would fail or pass for reasons outside its control.
+  Report the measurement; promise nothing. `make bench` runs the Go
+  benchmarks on generated trees.
 
 ## 14. Build, dependencies, release
 
-- Go 1.24 or newer. `CGO_ENABLED=0`: static binaries.
+- Go 1.24 or newer. `CGO_ENABLED=0`: static binaries on Linux and FreeBSD;
+  on OpenBSD Go links against the system libc, as that platform requires.
 - Go dependencies: `golang.org/x/term` (key-at-a-time input) and
   `golang.org/x/text` (Unicode normalisation for `fold`). Everything else is
   the standard library, including the s-expression reader and the gitignore
@@ -571,8 +584,7 @@ Repository contents for 0.0.1: `README.md` (60-second quickstart),
 `LICENSE`, `CHANGELOG.md`, `Makefile`, `go.mod`, `cmd/`, `internal/`, `scripts/`,
 `man/krino.1`, `man/krino.conf.5`, `docs/design.md`,
 `docs/sexp-primer.md`, `examples/` (by type, invoices by tax number with
-placeholder numbers, screenshots by date, cleaning up old installers),
-`testdata/`.
+placeholder numbers, screenshots by date, cleaning up old installers).
 
 ## 15. Testing
 
@@ -583,8 +595,10 @@ placeholder numbers, screenshots by date, cleaning up old installers),
   path against `git check-ignore --no-index` (skipped if git is absent).
 - **Conditions:** truth tables; a property test that random condition trees
   give the same result with and without cost reordering.
-- **Extraction:** small fixtures in `testdata/` for each format; PDF and
-  legacy-format tests skip when the tool is missing.
+- **Extraction:** the tests generate their fixtures in temporary
+  directories and use fake tools for PDF and the legacy formats (doc, xls,
+  ppt); the real `pdftotext` test skips when the tool is missing. Real
+  office-suite files and real legacy-tool runs are not tested in 0.0.1.
 - **Plan, apply, undo:** in temporary directories: build a tree, plan,
   apply, check; undo; check the tree is identical to the start (paths,
   contents, modes, mtimes). A cross-filesystem move test runs when a tmpfs is
@@ -629,8 +643,9 @@ keyword. Its defects shaped these decisions:
    remote is chosen, `go mod edit -module <path>` and one `sed` over the
    `"krino/internal/...` imports rename it; nothing else depends on it.
    `go install ...@v0.0.1` works only after that.
-2. **License: GPL-3.0-or-later.** Full text in `LICENSE`; every source file
-   carries `// SPDX-License-Identifier: GPL-3.0-or-later`.
+2. **License: GPL-3.0-or-later.** Full text in `LICENSE`; every Go file,
+   shell script and man page carries an
+   `SPDX-License-Identifier: GPL-3.0-or-later` line.
 
 ## Appendix A: type groups
 
diff --git a/examples/by-type.conf b/examples/by-type.conf
new file mode 100644
index 0000000..5b363df
--- /dev/null
+++ b/examples/by-type.conf
@@ -0,0 +1,55 @@
+;; -*- mode: lisp -*-
+;; vim: set ft=lisp :
+;;
+;; by-type.conf — file everything into one folder per type group.
+;;
+;; Demonstrates: (type ...) with the built-in type groups, (move ...), and
+;; (stop) so a file already claimed by one rule is never moved again by a
+;; later one. The six groups below happen not to overlap each other, but
+;; krino's type groups can (a .json file is both "code" and "text", for
+;; instance — see TYPE GROUPS in krino.conf(5)), so (stop) is worth keeping
+;; once you add rules of your own.
+;;
+;; To use: copy this to dirs/<name>.conf, fix (path ...) below, and add
+;; <name> to (include ...) in krino.conf — or just run:
+;;   krino new <name> ~/wherever
+;; and paste the (rule ...) forms in below the generated header. A short
+;; tutorial on the syntax is docs/sexp-primer.md in the source repository,
+;; installed alongside this file at
+;; $PREFIX/share/doc/krino/sexp-primer.md; every form is described in
+;; krino.conf(5).
+
+(path "~/Downloads")            ; CHANGE THIS to the directory to sort
+
+;; Leave partial downloads and dotfiles alone.
+(ignore "*.part" "*.crdownload" "*.aria2" ".*")
+
+(rule "images"
+  (when (type image))
+  (move "Filed/Images")
+  (stop))
+
+(rule "documents"
+  (when (type document))
+  (move "Filed/Documents")
+  (stop))
+
+(rule "spreadsheets"
+  (when (type spreadsheet))
+  (move "Filed/Spreadsheets")
+  (stop))
+
+(rule "presentations"
+  (when (type presentation))
+  (move "Filed/Presentations")
+  (stop))
+
+(rule "archives"
+  (when (type archive))
+  (move "Filed/Archives")
+  (stop))
+
+(rule "audio-video"
+  (when (or (type audio) (type video)))
+  (move "Filed/Media")
+  (stop))
diff --git a/examples/invoices.conf b/examples/invoices.conf
new file mode 100644
index 0000000..9fca018
--- /dev/null
+++ b/examples/invoices.conf
@@ -0,0 +1,33 @@
+;; -*- mode: lisp -*-
+;; vim: set ft=lisp :
+;;
+;; invoices.conf — file invoices by content, into a folder per year.
+;;
+;; Demonstrates: (content ...) matching text pulled out of PDFs and other
+;; documents (see krino.conf(5), CONTENT EXTRACTION), and the {mtime:%Y}
+;; placeholder in a (move ...) destination.
+;;
+;; 0000000000 below is a placeholder, not an issued Polish NIP — no such
+;; number is ever assigned. The conditions in (when ...) must all hold, and
+;; one (content ...) is true when any of its keywords appears, so the rule
+;; needs a keyword AND the number. Replace the number with your supplier's
+;; or your own NIP to narrow the rule to that tax number, or delete the
+;; (content "0000000000") condition to match on keywords alone.
+;;
+;; To use: copy this to dirs/<name>.conf, fix (path ...) below, and add
+;; <name> to (include ...) in krino.conf. A short tutorial on the syntax is
+;; docs/sexp-primer.md in the source repository, installed alongside this
+;; file at $PREFIX/share/doc/krino/sexp-primer.md; every form is described
+;; in krino.conf(5).
+
+(path "~/Downloads")            ; CHANGE THIS to the directory to sort
+
+;; Leave partial downloads and dotfiles alone.
+(ignore "*.part" "*.crdownload" "*.aria2" ".*")
+
+(rule "acme-invoices"
+  (when (type document)
+        (content "faktura" "invoice")
+        (content "0000000000"))         ; 0000000000: fake NIP, see above
+  (move "Filed/Invoices/{mtime:%Y}")
+  (stop))
diff --git a/examples/old-installers.conf b/examples/old-installers.conf
new file mode 100644
index 0000000..6ad63e7
--- /dev/null
+++ b/examples/old-installers.conf
@@ -0,0 +1,26 @@
+;; -*- mode: lisp -*-
+;; vim: set ft=lisp :
+;;
+;; old-installers.conf — clean up old installers with (age ...) and (delete).
+;;
+;; Demonstrates: (type package), (age ...) by modification time, and
+;; (delete) — which moves a matched file to the desktop trash
+;; ($XDG_DATA_HOME/Trash), NOT a permanent delete; recover a mistake from
+;; there. Use (delete permanent) instead only if you really want an unlink
+;; that undo cannot reverse — see krino.conf(5), ACTIONS.
+;;
+;; To use: copy this to dirs/<name>.conf, fix (path ...) below, and add
+;; <name> to (include ...) in krino.conf. A short tutorial on the syntax is
+;; docs/sexp-primer.md in the source repository, installed alongside this
+;; file at $PREFIX/share/doc/krino/sexp-primer.md; every form is described
+;; in krino.conf(5).
+
+(path "~/Downloads")            ; CHANGE THIS to the directory to sort
+
+;; Leave partial downloads and dotfiles alone.
+(ignore "*.part" "*.crdownload" "*.aria2" ".*")
+
+(rule "old-installers"
+  (when (type package)
+        (age > 90d))
+  (delete))
diff --git a/examples/screenshots.conf b/examples/screenshots.conf
new file mode 100644
index 0000000..6532bab
--- /dev/null
+++ b/examples/screenshots.conf
@@ -0,0 +1,27 @@
+;; -*- mode: lisp -*-
+;; vim: set ft=lisp :
+;;
+;; screenshots.conf — rename screenshots by date, then file them by year.
+;;
+;; Demonstrates: (rename ...) with the {mtime:FMT} placeholder run before
+;; (move ...) — a rule's steps run in the order written, and a later step
+;; sees the name or path an earlier one just produced — so the date lands
+;; in the file's own name, not only in its destination.
+;;
+;; To use: copy this to dirs/<name>.conf, fix (path ...) below, and add
+;; <name> to (include ...) in krino.conf. A short tutorial on the syntax is
+;; docs/sexp-primer.md in the source repository, installed alongside this
+;; file at $PREFIX/share/doc/krino/sexp-primer.md; every form is described
+;; in krino.conf(5).
+
+(path "~/Pictures")             ; CHANGE THIS to the directory to sort
+
+;; Leave partial downloads and dotfiles alone.
+(ignore "*.part" "*.crdownload" "*.aria2" ".*")
+
+(rule "screenshots"
+  (when (type image)
+        (name "screenshot"))    ; case-insensitive by default; adjust to taste
+  (rename "{mtime:%Y-%m-%d}_{name}")
+  (move "Filed/Screenshots/{mtime:%Y}")
+  (stop))
diff --git a/internal/apply/apply.go b/internal/apply/apply.go
index 2cd52e4..f177a17 100644
--- a/internal/apply/apply.go
+++ b/internal/apply/apply.go
@@ -153,7 +153,7 @@ func runFileStep(step plan.Step) StepResult {
 	case plan.Move:
 		err = moveFile(step.Src, dst)
 	case plan.Rename:
-		err = os.Rename(step.Src, dst)
+		err = renameFile(step.Src, dst)
 	}
 	if err != nil {
 		return StepResult{Step: step, Status: "failed", Detail: err.Error(), Made: made, DisplacedEntry: displacedEntry}
diff --git a/internal/apply/apply_test.go b/internal/apply/apply_test.go
index 64b0176..4bf6c30 100644
--- a/internal/apply/apply_test.go
+++ b/internal/apply/apply_test.go
@@ -250,3 +250,45 @@ func TestChainMadeIsOutermostFirstForNestedDirectories(t *testing.T) {
 		t.Errorf("Made = %v, want %v (outermost first)", got[0].Made, want)
 	}
 }
+
+// TestMoveFileRefusesOccupiedDestination is item 16 (fix round 2026-09-12,
+// plan 5 Task 2): moveFile must refuse an occupied destination on its own,
+// not merely rely on runFileStep having already checked - the exact
+// arrangement that produced plan 4's Task 5 Critical, where a helper that
+// replaced silently was trusted because some caller had checked. Called
+// directly, bypassing runFileStep's own pre-check entirely.
+func TestMoveFileRefusesOccupiedDestination(t *testing.T) {
+	dir := t.TempDir()
+	src := write(t, filepath.Join(dir, "x.pdf"), "source", 0o644)
+	dst := write(t, filepath.Join(dir, "y.pdf"), "already there", 0o644)
+
+	if err := moveFile(src, dst); err == nil {
+		t.Fatal("moveFile overwrote an existing destination")
+	}
+	if b, err := os.ReadFile(src); err != nil || string(b) != "source" {
+		t.Errorf("moveFile touched its source: %q, %v", b, err)
+	}
+	if b, err := os.ReadFile(dst); err != nil || string(b) != "already there" {
+		t.Errorf("moveFile touched its destination: %q, %v", b, err)
+	}
+}
+
+// TestRenameFileRefusesOccupiedDestination is item 16's other half:
+// runFileStep's bare os.Rename call for the Rename kind was just as
+// unguarded in itself as moveFile was. renameFile is the helper that now
+// carries the same independent guard, called directly here.
+func TestRenameFileRefusesOccupiedDestination(t *testing.T) {
+	dir := t.TempDir()
+	src := write(t, filepath.Join(dir, "x.pdf"), "source", 0o644)
+	dst := write(t, filepath.Join(dir, "y.pdf"), "already there", 0o644)
+
+	if err := renameFile(src, dst); err == nil {
+		t.Fatal("renameFile overwrote an existing destination")
+	}
+	if b, err := os.ReadFile(src); err != nil || string(b) != "source" {
+		t.Errorf("renameFile touched its source: %q, %v", b, err)
+	}
+	if b, err := os.ReadFile(dst); err != nil || string(b) != "already there" {
+		t.Errorf("renameFile touched its destination: %q, %v", b, err)
+	}
+}
diff --git a/internal/apply/fs.go b/internal/apply/fs.go
index 205089f..823d5c8 100644
--- a/internal/apply/fs.go
+++ b/internal/apply/fs.go
@@ -108,6 +108,16 @@ func moveFile(src, dst string) error {
 	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
 		return err
 	}
+	// Item 16 (fix round 2026-09-12, plan 5 Task 2): this guard must hold
+	// independently of runFileStep's own pre-check, layered rather than
+	// moved - the exact arrangement that produced plan 4's Task 5 Critical,
+	// where a helper that replaced silently was trusted because some caller
+	// had checked. Placed immediately before the operation that would
+	// otherwise clobber dst, the same way copyFile's own guard sits right
+	// before its rename into place.
+	if err := refuseIfExists(dst); err != nil {
+		return err
+	}
 	err := os.Rename(src, dst)
 	if err == nil {
 		return nil
@@ -121,6 +131,31 @@ func moveFile(src, dst string) error {
 	return os.Remove(src)
 }
 
+// renameFile renames src to dst, refusing on its own when dst already
+// exists rather than trusting that a caller checked first (item 16, same
+// reasoning as moveFile's guard above): a bare os.Rename silently replaces
+// an occupied destination, and runFileStep's own pre-check must not be the
+// only thing standing between a rename step and that.
+func renameFile(src, dst string) error {
+	if err := refuseIfExists(dst); err != nil {
+		return err
+	}
+	return os.Rename(src, dst)
+}
+
+// refuseIfExists reports an error naming dst if something is already there
+// (os.Lstat succeeds, following no symlink), and propagates any other stat
+// failure. A nil return means dst was confirmed absent at the moment of the
+// check.
+func refuseIfExists(dst string) error {
+	if _, err := os.Lstat(dst); err == nil {
+		return fmt.Errorf("destination already exists: %s", dst)
+	} else if !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
 // maxSuffixAttempts bounds nextFreeName. internal/plan/conflict.go and
 // internal/trash/trash.go each have their own cap of the same size, for the
 // same reason given below: nextFreeName solves yet another, independent
diff --git a/internal/config/skel/krino.conf b/internal/config/skel/krino.conf
index 48780ea..dbd883b 100644
--- a/internal/config/skel/krino.conf
+++ b/internal/config/skel/krino.conf
@@ -1,8 +1,9 @@
 ;; -*- mode: lisp -*-
 ;; vim: set ft=lisp :
 ;;
-;; krino's main configuration. The syntax is explained in
-;; docs/sexp-primer.md; every form is described in krino.conf(5).
+;; krino's main configuration. The syntax is explained in sexp-primer.md,
+;; installed as share/doc/krino/sexp-primer.md under the install prefix,
+;; which is ~/.local by default; every form is described in krino.conf(5).
 
 ;; The directories to sort, in this order. Each NAME has its rules in
 ;; dirs/NAME.conf. Add one with: krino new NAME PATH
diff --git a/internal/config/skel/template.conf b/internal/config/skel/template.conf
index 867b681..c3af09d 100644
--- a/internal/config/skel/template.conf
+++ b/internal/config/skel/template.conf
@@ -1,8 +1,9 @@
 ;; -*- mode: lisp -*-
 ;; vim: set ft=lisp :
 ;;
-;; krino rules for one directory. The syntax is explained in
-;; docs/sexp-primer.md; every form is described in krino.conf(5).
+;; krino rules for one directory. The syntax is explained in sexp-primer.md,
+;; installed as share/doc/krino/sexp-primer.md under the install prefix,
+;; which is ~/.local by default; every form is described in krino.conf(5).
 
 (path "@PATH@")
 
diff --git a/internal/dup/dup.go b/internal/dup/dup.go
index e3c7424..32bcfb0 100644
--- a/internal/dup/dup.go
+++ b/internal/dup/dup.go
@@ -174,18 +174,47 @@ func (x *Index) Lookup(path string) (original string, dup bool, err error) {
 		return path, false, nil
 	}
 	orig := x.candidates[x.original(identical)].path
-	return orig, orig != path, nil
+	if orig == path {
+		return orig, false, nil
+	}
+	// Spec §5.5: two names for one file are never duplicates of each other.
+	// The other name may be a hardlink, or path itself indexed a second time
+	// under a DIR that overlaps the scanned tree. identicalTo gives every
+	// member of the content class the same set, so every lookup elects the
+	// same original, and no name for that original's file is reported as a
+	// duplicate: its content always keeps at least one name. Portable:
+	// os.SameFile, never a Stat_t.Dev/Ino read (that field's type differs
+	// across freebsd/openbsd, which `make ci` vets).
+	origInfo, err := os.Lstat(orig)
+	if err != nil {
+		return "", false, err
+	}
+	pathInfo, err := os.Lstat(path)
+	if err != nil {
+		return "", false, err
+	}
+	if os.SameFile(origInfo, pathInfo) {
+		return orig, false, nil
+	}
+	return orig, true, nil
 }
 
 // identicalTo returns the indexes in group (which all share idx's size,
 // idx included) whose content matches candidates[idx]: same partial hash,
-// then, only for those that collide, the same full hash. idx is the file
-// Lookup was asked about; a failure hashing it propagates, since Lookup can
-// answer nothing without it. A failure hashing any other candidate in group
-// only removes that candidate from consideration: a vanished candidate
-// (errors.Is fs.ErrNotExist) is dropped silently, any other failure is
-// recorded on the Index (see recordCandidateError) so the caller can warn
-// about it once matching is done.
+// then, only for those that collide, the same full hash. Every candidate
+// with identical bytes is included, whatever its path or inode: a hardlink
+// of idx, and idx's own path indexed a second time under an overlapping
+// extra directory, are both members. That keeps the set the same whichever
+// member Lookup was asked about, so every member elects the same original;
+// Lookup, not this function, decides that a name for the elected original's
+// own file is not a duplicate of it.
+//
+// idx is the file Lookup was asked about; a failure hashing it propagates,
+// since Lookup can answer nothing without it. A failure hashing any other
+// candidate in group only removes that candidate from consideration: a
+// vanished candidate (errors.Is fs.ErrNotExist) is dropped silently, any
+// other failure is recorded on the Index (see recordCandidateError) so the
+// caller can warn about it once matching is done.
 func (x *Index) identicalTo(idx int, group []int) ([]int, error) {
 	idxPartial, err := x.partialHash(x.candidates[idx].path)
 	if err != nil {
@@ -219,9 +248,10 @@ func (x *Index) identicalTo(idx int, group []int) ([]int, error) {
 			x.recordCandidateError(x.candidates[j].path, err)
 			continue
 		}
-		if jFull == idxFull {
-			same = append(same, j)
+		if jFull != idxFull {
+			continue
 		}
+		same = append(same, j)
 	}
 	return same, nil
 }
diff --git a/internal/dup/dup_test.go b/internal/dup/dup_test.go
index 5d2621c..ed7c1a3 100644
--- a/internal/dup/dup_test.go
+++ b/internal/dup/dup_test.go
@@ -352,3 +352,229 @@ func TestExtraDirSymlinkNotFollowed(t *testing.T) {
 		t.Errorf("symlinked extra dir was indexed despite the error: dup=%v orig=%s", dup, orig)
 	}
 }
+
+// linked builds a scan.File for a hardlink of an already-put file: same
+// inode, so same content and metadata by construction, under a new name.
+func linked(t *testing.T, dir, name string, target scan.File) scan.File {
+	t.Helper()
+	p := filepath.Join(dir, name)
+	if err := os.Link(target.Path, p); err != nil {
+		t.Fatal(err)
+	}
+	fi, err := os.Stat(p)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return scan.File{Path: p, Rel: name, Name: name, Size: fi.Size(), ModTime: fi.ModTime()}
+}
+
+// TestHardlinksAreNotDuplicatesOfEachOther is R10 (plan 5 Task 2, added to
+// the task outside the brief): spec §5.5 groups duplicate candidates by size
+// and hash, with no inode check, so two hardlinked names - one inode, byte-
+// identical by construction - were judged a duplicate pair. A rule of
+// (when (duplicate)) (delete) would then remove a name the user relies on
+// even though nothing was ever actually copied. os.SameFile must stop a
+// file being judged a duplicate of itself under another name.
+func TestHardlinksAreNotDuplicatesOfEachOther(t *testing.T) {
+	d := t.TempDir()
+	a := put(t, d, "a.pdf", []byte("same content"), 0)
+	b := linked(t, d, "b.pdf", a)
+
+	x, errs := NewIndex([]scan.File{a, b}, nil)
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	if orig, dup := lookup(t, x, a); dup {
+		t.Errorf("a.pdf reported as a duplicate of its own hardlink b.pdf (orig=%s)", orig)
+	}
+	if orig, dup := lookup(t, x, b); dup {
+		t.Errorf("b.pdf reported as a duplicate of its own hardlink a.pdf (orig=%s)", orig)
+	}
+}
+
+// TestHardlinksAreStillDuplicatesOfASeparateIdenticalFile is R10's other
+// direction, and the one a naive "same size+hash means never a duplicate"
+// fix would get wrong: a.pdf and b.pdf are hardlinks of one inode, but
+// c.pdf is a genuinely separate, byte-identical copy under an extra
+// (duplicate "DIR") directory, so spec §5.5 prefers it as the original.
+// Deleting a.pdf and b.pdf then leaves the content intact in c.pdf - they
+// really are duplicates, of c.pdf, and must still be reported as such.
+func TestHardlinksAreStillDuplicatesOfASeparateIdenticalFile(t *testing.T) {
+	scanned, filed := t.TempDir(), t.TempDir()
+	a := put(t, scanned, "a.pdf", []byte("same content"), 0)
+	b := linked(t, scanned, "b.pdf", a)
+	put(t, filed, "c.pdf", []byte("same content"), 0) // extra-dir copy: preferred as the original regardless of mtime
+
+	x, errs := NewIndex([]scan.File{a, b}, []string{filed})
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	cPath := filepath.Join(filed, "c.pdf")
+	if orig, dup := lookup(t, x, a); !dup || orig != cPath {
+		t.Errorf("a.pdf: dup=%v orig=%s, want a real duplicate of %s", dup, orig, cPath)
+	}
+	if orig, dup := lookup(t, x, b); !dup || orig != cPath {
+		t.Errorf("b.pdf: dup=%v orig=%s, want a real duplicate of %s", dup, orig, cPath)
+	}
+}
+
+// TestHardlinkUnderExtraDirWithNoOtherCopyIsNotADuplicate is R10 extended
+// to extra-directory candidates: a candidate is never a duplicate of a
+// candidate that is the same file, and extra-directory candidates are
+// candidates - the rule is not scanned-vs-scanned only. This is the shape
+// (duplicate "DIR") exists for: (duplicate "~/backup") means "the backup
+// already holds a copy, so the local name can go", but if ~/backup/a.pdf is
+// a hardlink of ~/dl/a.pdf, the backup holds no copy at all, just the same
+// file under a second name - judging the scanned file a duplicate would
+// delete the only copy while the user believes it is backed up.
+//
+// Lookup's os.SameFile check compares the elected original with the file
+// asked about whether the original was scanned or found under an extra
+// directory, so this case needs no special handling; the test pins it as
+// its own named case.
+func TestHardlinkUnderExtraDirWithNoOtherCopyIsNotADuplicate(t *testing.T) {
+	scanned, backup := t.TempDir(), t.TempDir()
+	a := put(t, scanned, "a.pdf", []byte("same content"), 0)
+	backupPath := filepath.Join(backup, "a.pdf")
+	if err := os.Link(a.Path, backupPath); err != nil {
+		t.Fatal(err)
+	}
+
+	x, errs := NewIndex([]scan.File{a}, []string{backup})
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	if orig, dup := lookup(t, x, a); dup {
+		t.Errorf("a.pdf reported as a duplicate of its own hardlink under the extra dir (orig=%s)", orig)
+	}
+}
+
+// TestThreeWayHardlinksAreNotDuplicatesOfEachOther is the direct
+// generalisation of TestHardlinksAreNotDuplicatesOfEachOther to N names for
+// one inode: three names, one inode, no other copy anywhere - none of them
+// is a duplicate of either of the others. No special-casing for N > 2: all
+// three elect the same original, and Lookup's SameFile check finds each
+// name to be that original's own file.
+func TestThreeWayHardlinksAreNotDuplicatesOfEachOther(t *testing.T) {
+	d := t.TempDir()
+	a := put(t, d, "a.pdf", []byte("same content"), 0)
+	b := linked(t, d, "b.pdf", a)
+	c := linked(t, d, "c.pdf", a)
+
+	x, errs := NewIndex([]scan.File{a, b, c}, nil)
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	for _, f := range []scan.File{a, b, c} {
+		if orig, dup := lookup(t, x, f); dup {
+			t.Errorf("%s reported as a duplicate (orig=%s)", f.Name, orig)
+		}
+	}
+}
+
+// dupVerdicts looks up every file in fs and returns the paths reported as
+// not a duplicate, and the originals the duplicates were reported against.
+func dupVerdicts(t *testing.T, x *Index, fs ...scan.File) (kept []string, origs map[string]string) {
+	t.Helper()
+	origs = make(map[string]string)
+	for _, f := range fs {
+		orig, dup := lookup(t, x, f)
+		if dup {
+			origs[f.Path] = orig
+		} else {
+			kept = append(kept, f.Path)
+		}
+	}
+	return kept, origs
+}
+
+// TestExtraDirIsTheScannedRoot: (duplicate "DIR") where DIR is the scanned
+// root itself, so every scanned file is also indexed as an extra-directory
+// candidate under the same path. Two identical files are one duplicate and
+// one original, never two duplicates of each other: a (delete) rule must
+// leave one copy.
+func TestExtraDirIsTheScannedRoot(t *testing.T) {
+	d := t.TempDir()
+	a := put(t, d, "a.pdf", []byte("same content"), 0) // older: the original
+	b := put(t, d, "b.pdf", []byte("same content"), 5)
+
+	x, errs := NewIndex([]scan.File{a, b}, []string{d})
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	kept, origs := dupVerdicts(t, x, a, b)
+	if len(kept) != 1 || kept[0] != a.Path {
+		t.Errorf("kept = %v, want exactly %s (duplicates: %v)", kept, a.Path, origs)
+	}
+	if origs[b.Path] != a.Path {
+		t.Errorf("b.pdf: original = %q, want %s", origs[b.Path], a.Path)
+	}
+}
+
+// TestExtraDirInsideRecursiveRoot: DIR is a subdirectory of a recursively
+// scanned root, the "the archive already holds a copy, so the loose one can
+// go" shape. The copy under DIR is the original even though it is newer;
+// only the copy outside DIR is a duplicate.
+func TestExtraDirInsideRecursiveRoot(t *testing.T) {
+	d := t.TempDir()
+	archived := put(t, d, "Archive/x.pdf", []byte("same content"), 5)
+	loose := put(t, d, "x-copy.pdf", []byte("same content"), 0) // older, but not under DIR
+
+	x, errs := NewIndex([]scan.File{archived, loose}, []string{filepath.Join(d, "Archive")})
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	kept, origs := dupVerdicts(t, x, archived, loose)
+	if len(kept) != 1 || kept[0] != archived.Path {
+		t.Errorf("kept = %v, want exactly %s (duplicates: %v)", kept, archived.Path, origs)
+	}
+	if origs[loose.Path] != archived.Path {
+		t.Errorf("x-copy.pdf: original = %q, want %s", origs[loose.Path], archived.Path)
+	}
+}
+
+// TestExtraDirIsAnAncestorOfTheRoot: DIR contains the scanned root, as
+// (duplicate "~") would for a root under the home directory.
+func TestExtraDirIsAnAncestorOfTheRoot(t *testing.T) {
+	parent := t.TempDir()
+	root := filepath.Join(parent, "dl")
+	a := put(t, root, "a.pdf", []byte("same content"), 0) // older: the original
+	b := put(t, root, "b.pdf", []byte("same content"), 5)
+
+	x, errs := NewIndex([]scan.File{a, b}, []string{parent})
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	kept, origs := dupVerdicts(t, x, a, b)
+	if len(kept) != 1 || kept[0] != a.Path {
+		t.Errorf("kept = %v, want exactly %s (duplicates: %v)", kept, a.Path, origs)
+	}
+	if origs[b.Path] != a.Path {
+		t.Errorf("b.pdf: original = %q, want %s", origs[b.Path], a.Path)
+	}
+}
+
+// TestThreeCopiesWithOverlappingExtraDirKeepOne: two copies under DIR and a
+// third outside it, all scanned. Exactly one of the three is not a
+// duplicate, it lies under DIR, and every duplicate names that same file as
+// its original.
+func TestThreeCopiesWithOverlappingExtraDirKeepOne(t *testing.T) {
+	d := t.TempDir()
+	x1 := put(t, d, "Archive/x1.pdf", []byte("same content"), 3)
+	x2 := put(t, d, "Archive/x2.pdf", []byte("same content"), 4)
+	loose := put(t, d, "x-copy.pdf", []byte("same content"), 0)
+
+	x, errs := NewIndex([]scan.File{x1, x2, loose}, []string{filepath.Join(d, "Archive")})
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	kept, origs := dupVerdicts(t, x, x1, x2, loose)
+	if len(kept) != 1 || kept[0] != x1.Path {
+		t.Fatalf("kept = %v, want exactly %s (duplicates: %v)", kept, x1.Path, origs)
+	}
+	for p, orig := range origs {
+		if orig != x1.Path {
+			t.Errorf("%s: original = %q, want %s", p, orig, x1.Path)
+		}
+	}
+}
diff --git a/internal/engine/apply.go b/internal/engine/apply.go
index c74414d..878cb18 100644
--- a/internal/engine/apply.go
+++ b/internal/engine/apply.go
@@ -9,6 +9,7 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 	"syscall"
 	"time"
@@ -660,6 +661,50 @@ func refuseIfSrcExists(us UndoStep, proj *undoProjection) string {
 // declined - a single pass, not two, so the two kinds of file interleave in
 // the log exactly as the run touched them, the same as Apply's own
 // approved-and-declined chains do.
+//
+// Task 1 (plan 5): after every file's reversal has been attempted, a second,
+// run-wide pass retries the directory removals that were refused as
+// non-empty. planUndoFile puts the undo-mkdir step for a shared destination
+// on whichever file's chain first created it (spec §9: only the step that
+// actually created a directory logs a "mkdir" entry, so only that file's
+// reversal carries the matching undo-mkdir); when that file reverses first,
+// its siblings are usually still inside, the removal is correctly refused as
+// non-empty (spec §10), and - without this pass - nothing ever retries it,
+// leaving empty directories behind even though every file came back. This
+// mirrors planUndoFile's own undoProjection insight (see its comment) one
+// level up: a removal judged too early is judging the wrong world, whether
+// that "too early" is mid-file (what the projection fixes) or mid-run (what
+// this retry fixes).
+//
+// The retry is a run-level tidy-up, never a re-run of a step: it does not
+// touch what the first undo-mkdir attempt already logged (that entry, ok or
+// failed, stands exactly as it was written), and a directory the retry does
+// manage to remove gets an ADDITIONAL journal entry - never a rewrite - so
+// the log never disagrees with reality (my ruling on the point the brief
+// left open: spec §9 logs every step, and a directory removed while the log
+// still says its removal was refused would be a false record). Because
+// journal.ranAnyUndoStep already excludes "undo-mkdir" from what marks a run
+// "(undone)", this extra "ok" entry cannot change that marking either -
+// TestApplyUndoRetryLogsBothMkdirEntriesAndStillMarksOriginalRunUndone pins
+// it rather than assuming it. A retried removal is likewise never folded
+// into ApplyResult: it is
+// collected from candidates whose first attempt already went through
+// tallyFile once (via isFileAffecting's exemption), and counting it again
+// here would double-count a directory that failed once and then quietly
+// tidied itself away.
+//
+// Candidates are collected only from directories this run's own reversal
+// created - by construction, since every candidate comes from an undo-mkdir
+// step, and an undo-mkdir step exists only for a directory the forward run's
+// Made recorded - never a directory the retry merely happens to find empty.
+// They are retried deepest path first (retryDirRemovals), so a nested
+// directory - e.g. Work/Sub under Work - is removed before its
+// now-possibly-empty parent, the same outermost-created/innermost-removed
+// discipline logStep and undoFile already keep within one file's own chain,
+// applied here across files. A directory still non-empty at retry time
+// genuinely holds something else (or the retry runs before every sibling
+// happens to have reversed, on a later undo of a different run) and simply
+// stays, with its original refusal the only record of it.
 func (e *Engine) ApplyUndo(ctx context.Context, up *UndoPlan, j *journal.Writer, run string) (*ApplyResult, error) {
 	result := &ApplyResult{}
 
@@ -695,6 +740,7 @@ func (e *Engine) ApplyUndo(ctx context.Context, up *UndoPlan, j *journal.Writer,
 		return result, fmt.Errorf("engine: apply undo: %w", err)
 	}
 
+	var retries []dirRetry
 	for _, f := range actionable {
 		if err := ctx.Err(); err != nil {
 			return result, err
@@ -714,6 +760,15 @@ func (e *Engine) ApplyUndo(ctx context.Context, up *UndoPlan, j *journal.Writer,
 		}
 		result.Files = append(result.Files, fr)
 		tallyFile(result, fr.Steps, func(i int) bool { return isFileAffecting(f.Steps[i].Action) })
+		for i, us := range f.Steps {
+			if us.Action == "undo-mkdir" && fr.Steps[i].Status == "failed" {
+				retries = append(retries, dirRetry{dir: us.Src, dirName: f.Dir, file: f.File, step: i + 1})
+			}
+		}
+	}
+
+	if err := e.retryDirRemovals(j, run, retries); err != nil {
+		return result, fmt.Errorf("engine: apply undo: %w", err)
 	}
 
 	if err := j.Append(journal.Entry{Time: e.Now(), Run: run, Action: "run-end", Status: "ok"}); err != nil {
@@ -722,6 +777,69 @@ func (e *Engine) ApplyUndo(ctx context.Context, up *UndoPlan, j *journal.Writer,
 	return result, nil
 }
 
+// dirRetry names one directory whose undo-mkdir was refused (as non-empty)
+// during ApplyUndo's main pass, kept for the run-wide retry once every
+// file's reversal has been attempted. file and dirName are the file and
+// config directory name that owned the original undo-mkdir step, carried
+// forward so retryDirRemovals's journal entry - if the retry succeeds -
+// names the same file and directory the original refusal did, not an
+// arbitrary one; step is that same step's 1-based index, so the two entries
+// (the original "failed" and, if the retry succeeds, this "ok") read
+// together under the same File/Step in the log.
+type dirRetry struct {
+	dir     string
+	dirName string
+	file    string
+	step    int
+}
+
+// retryDirRemovals is ApplyUndo's run-wide second pass (Task 1, plan 5): once
+// every file's reversal has run, some directories an undo-mkdir step could
+// not remove earlier may now be empty, because a sibling file that shared
+// the directory has since reversed too. candidates is sorted deepest path
+// first (by descending path-segment count) so a nested directory is removed
+// before its parent, exactly the order a real cleanup needs; a directory
+// still non-empty at its turn genuinely holds something else and is left
+// exactly as its first attempt recorded it - no second entry, no error.
+//
+// This never rewrites or removes the original undo-mkdir entry (ok or
+// failed, whichever the first attempt logged): a directory the retry does
+// manage to remove gets one ADDITIONAL entry instead (my ruling on the point
+// the brief left open - see ApplyUndo's comment), so the log always agrees
+// with what is actually on disk. The new entry's own Action is still
+// "undo-mkdir", so journal.ranAnyUndoStep - which excludes that action on
+// principle, not by accident (see its own comment) - continues to treat this
+// exactly like any other undo-mkdir for the purpose of marking a run
+// "(undone)": tidying up an empty directory, on the first attempt or the
+// retry, is still not a restoration.
+func (e *Engine) retryDirRemovals(j *journal.Writer, run string, candidates []dirRetry) error {
+	sort.SliceStable(candidates, func(i, j int) bool {
+		return pathDepth(candidates[i].dir) > pathDepth(candidates[j].dir)
+	})
+	for _, c := range candidates {
+		if err := os.Remove(c.dir); err != nil {
+			// Still not empty (or gone, or otherwise unremovable): the
+			// original refusal already recorded this, and it stands.
+			continue
+		}
+		if err := j.Append(journal.Entry{
+			Time: e.Now(), Run: run, Dir: c.dirName, File: c.file, Step: c.step,
+			Action: "undo-mkdir", Status: "ok", Src: c.dir,
+		}); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// pathDepth counts path's separators after cleaning it, so retryDirRemovals
+// can sort deepest first: a nested directory (more separators) is always
+// removed before the parent it sits under, whatever the two paths' common
+// root.
+func pathDepth(path string) int {
+	return strings.Count(filepath.Clean(path), string(filepath.Separator))
+}
+
 // declineUndoFile logs f's reversal as declined without carrying out any of
 // it - spec §9's "declined files are logged even though nothing happens to
 // them", extended to undo (fix round 2026-09-12, item 2 of Task 8's review):
diff --git a/internal/engine/apply_test.go b/internal/engine/apply_test.go
index 42724a0..a54bffc 100644
--- a/internal/engine/apply_test.go
+++ b/internal/engine/apply_test.go
@@ -1180,3 +1180,246 @@ func TestTallyFileCountsMixedOutcomesOnceEach(t *testing.T) {
 		t.Errorf("result = %+v, want one of each", result)
 	}
 }
+
+// --- Plan 5, Task 1 ---
+
+// sharedDestUndoFixture builds a downloads directory with three pdf files
+// (a.pdf, b.pdf, c.pdf) and a single rule moving all of them into dest,
+// applies the move, and returns the sandbox home, the loaded engine, the
+// journal's path and the forward run's ID.
+//
+// All three files landing on one destination that this one run creates is
+// the shape that exercises the run-wide directory retry (Task 1, plan 5):
+// whichever file's chain first creates dest carries its undo-mkdir step(s),
+// and that file's own reversal typically runs while its siblings still
+// occupy dest - refusing the removal correctly, at first. dest may name a
+// nested path ("Work/Sub"): apply.mkdirAllTracked then records every
+// directory the move had to create, outermost first, and every one of them
+// still lands on that same first file's chain.
+//
+// Extracted per fix round 1 (Important 2): TestApplyUndoRemovesSharedDirectoryAfterEveryFileReverses
+// and TestApplyUndoRetryLogsBothMkdirEntriesAndStillMarksOriginalRunUndone
+// used to duplicate this setup verbatim; TestApplyUndoRetryRemovesNestedDirectoriesDeepestFirst
+// needed the identical shape with only dest varying, which is what named the
+// parameter rather than hard-coding "Filed" here.
+func sharedDestUndoFixture(t *testing.T, dest string) (h string, e *Engine, logPath string, run string) {
+	t.Helper()
+	h = sandbox(t)
+	dl := filepath.Join(h, "dl")
+	if err := os.MkdirAll(dl, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// Three files that all move into ONE created destination. The bug this
+	// task fixes is that only the file whose chain first creates it ever
+	// carries the undo-mkdir step, and that step is attempted while its
+	// siblings are still inside.
+	for _, n := range []string{"a.pdf", "b.pdf", "c.pdf"} {
+		if err := os.WriteFile(filepath.Join(dl, n), []byte(n), 0o640); err != nil {
+			t.Fatal(err)
+		}
+	}
+	main := writeConfig(t, h, `(include "dl")`, map[string]string{"dl": `
+(path "~/dl")
+(min-age 0s)
+(rule "pdfs" (when (type pdf)) (move "` + dest + `"))
+`})
+	loaded, errs := Load(main)
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	e = loaded
+	dp, err := e.Plan(context.Background(), e.Dirs[0], plan.NewClaims())
+	if err != nil {
+		t.Fatal(err)
+	}
+	approved := map[string]bool{}
+	for _, c := range dp.Chains {
+		approved[c.File.Rel] = true
+	}
+	logPath = filepath.Join(h, ".local", "state", "krino", "krino.log")
+	j, err := journal.Open(logPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	run = journal.NewRunID(time.Now())
+	if _, err := e.Apply(context.Background(), dp, approved, j, run); err != nil {
+		t.Fatal(err)
+	}
+	j.Close()
+	return h, e, logPath, run
+}
+
+func TestApplyUndoRemovesSharedDirectoryAfterEveryFileReverses(t *testing.T) {
+	h, e, logPath, run := sharedDestUndoFixture(t, "Filed")
+	dl := filepath.Join(h, "dl")
+	filed := filepath.Join(dl, "Filed")
+	if _, err := os.Stat(filed); err != nil {
+		t.Fatalf("apply did not create the directory: %v", err)
+	}
+
+	up, err := e.PlanUndo(run)
+	if err != nil {
+		t.Fatal(err)
+	}
+	j2, err := journal.Open(logPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err := e.ApplyUndo(context.Background(), up, j2, journal.NewRunID(time.Now()))
+	if err != nil {
+		t.Fatal(err)
+	}
+	j2.Close()
+	if res.Failed != 0 {
+		t.Fatalf("undo reported %d failures: %+v", res.Failed, res)
+	}
+	if _, err := os.Stat(filed); !os.IsNotExist(err) {
+		t.Errorf("undo left the created directory behind: %v", err)
+	}
+	for _, n := range []string{"a.pdf", "b.pdf", "c.pdf"} {
+		if _, err := os.Stat(filepath.Join(dl, n)); err != nil {
+			t.Errorf("%s did not come back: %v", n, err)
+		}
+	}
+}
+
+// TestApplyUndoRetryRemovesNestedDirectoriesDeepestFirst pins fix round 1's
+// Important 1: retryDirRemovals must retry deepest path first. All three
+// files move into Work/Sub, so Apply's single mkdirAllTracked call creates
+// both Work and Work/Sub on the FIRST file's own chain (outermost first),
+// which means that one file's reversal carries two undo-mkdir steps, one for
+// each directory - and both are refused on that file's own turn, since the
+// other two files still sit in Work/Sub at that point.
+//
+// Retried deepest first, Work/Sub empties out and is removed, and Work -
+// now itself empty - is removed right after. Retried shallowest first
+// instead, Work is tried while Work/Sub (now empty, but not yet removed)
+// still sits inside it, so Work is refused as non-empty and never retried
+// again in this run; Work/Sub is then removed, leaving the outer Work
+// directory behind. So end state alone - no directory left over - already
+// distinguishes correct (deepest-first) ordering from inverted or dropped
+// ordering; unlike the flat-destination tests above, where only one
+// directory ever entered `retries`, this is the case built to tell the two
+// apart.
+func TestApplyUndoRetryRemovesNestedDirectoriesDeepestFirst(t *testing.T) {
+	h, e, logPath, run := sharedDestUndoFixture(t, "Work/Sub")
+	dl := filepath.Join(h, "dl")
+	work := filepath.Join(dl, "Work")
+	sub := filepath.Join(work, "Sub")
+	if _, err := os.Stat(sub); err != nil {
+		t.Fatalf("apply did not create the nested directory: %v", err)
+	}
+
+	up, err := e.PlanUndo(run)
+	if err != nil {
+		t.Fatal(err)
+	}
+	j2, err := journal.Open(logPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	res, err := e.ApplyUndo(context.Background(), up, j2, journal.NewRunID(time.Now()))
+	if err != nil {
+		t.Fatal(err)
+	}
+	j2.Close()
+	if res.Failed != 0 {
+		t.Fatalf("undo reported %d failures: %+v", res.Failed, res)
+	}
+	if _, err := os.Stat(sub); !os.IsNotExist(err) {
+		t.Errorf("undo left the nested directory behind: %v", err)
+	}
+	if _, err := os.Stat(work); !os.IsNotExist(err) {
+		t.Errorf("undo left the outer directory behind - retryDirRemovals is not retrying deepest path first: %v", err)
+	}
+	for _, n := range []string{"a.pdf", "b.pdf", "c.pdf"} {
+		if _, err := os.Stat(filepath.Join(dl, n)); err != nil {
+			t.Errorf("%s did not come back: %v", n, err)
+		}
+	}
+}
+
+// TestApplyUndoRetryLogsBothMkdirEntriesAndStillMarksOriginalRunUndone pins
+// the journal half of the ruling on the point Task 1's brief left open: when
+// retryDirRemovals succeeds in removing a directory, it appends an
+// ADDITIONAL journal entry for it - the original "failed" undo-mkdir entry,
+// recorded on whichever file's chain first created the directory, is never
+// rewritten or removed - and, because that entry's Action is still
+// "undo-mkdir" like the first, journal.ranAnyUndoStep continues to exclude
+// it from what marks a run "(undone)" (the brief's constraint: it "cannot
+// change whether a run shows as (undone); confirm that rather than assume
+// it").
+func TestApplyUndoRetryLogsBothMkdirEntriesAndStillMarksOriginalRunUndone(t *testing.T) {
+	_, e, logPath, run := sharedDestUndoFixture(t, "Filed")
+
+	up, err := e.PlanUndo(run)
+	if err != nil {
+		t.Fatal(err)
+	}
+	j2, err := journal.Open(logPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	undoRun := journal.NewRunID(time.Now())
+	res, err := e.ApplyUndo(context.Background(), up, j2, undoRun)
+	if err != nil {
+		t.Fatal(err)
+	}
+	j2.Close()
+	if res.Failed != 0 {
+		t.Fatalf("undo reported %d failures: %+v", res.Failed, res)
+	}
+
+	entries, err := journal.Entries(logPath, undoRun)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var failed, ok *journal.Entry
+	var mkdirCount int
+	for i := range entries {
+		en := &entries[i]
+		if en.Action != "undo-mkdir" {
+			continue
+		}
+		mkdirCount++
+		switch en.Status {
+		case "failed":
+			failed = en
+		case "ok":
+			ok = en
+		}
+	}
+	if mkdirCount != 2 {
+		t.Fatalf("undo-mkdir entries = %d, want exactly 2 (the original refusal plus the retry's addition): %+v", mkdirCount, entries)
+	}
+	if failed == nil {
+		t.Fatal("the original refused undo-mkdir entry is missing - it must never be rewritten or removed")
+	}
+	if ok == nil {
+		t.Fatal("no successful undo-mkdir entry was appended for the retry")
+	}
+	if failed.Src != ok.Src {
+		t.Errorf("failed.Src = %q, ok.Src = %q; want the same directory", failed.Src, ok.Src)
+	}
+	if failed.File != ok.File {
+		t.Errorf("failed.File = %q, ok.File = %q; want the retry entry to carry the file that owned the original undo-mkdir", failed.File, ok.File)
+	}
+	if failed.Dir != ok.Dir {
+		t.Errorf("failed.Dir = %q, ok.Dir = %q; want the same directory name", failed.Dir, ok.Dir)
+	}
+
+	runs, err := e.Runs(0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	byID := map[string]bool{}
+	for _, r := range runs {
+		byID[r.ID] = r.Undone
+	}
+	if !byID[run] {
+		t.Errorf("original run %q not marked Undone, though every file came back", run)
+	}
+	if byID[undoRun] {
+		t.Errorf("the undo run %q itself must never read as Undone", undoRun)
+	}
+}
diff --git a/internal/engine/plan_bench_test.go b/internal/engine/plan_bench_test.go
new file mode 100644
index 0000000..a3d08bb
--- /dev/null
+++ b/internal/engine/plan_bench_test.go
@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package engine
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"krino/internal/plan"
+)
+
+// BenchmarkPlan measures krino's own cost of planning: walking a tree,
+// matching rules and building action chains (Engine.Plan, which wraps
+// Engine.Match and plan.Build). It does NOT measure krino's real-world
+// throughput - spec §13 is explicit that there is no performance target
+// for 0.0.1, because a full run's wall time is dominated by the external
+// extractors (pdftotext and friends), not by krino itself. This benchmark
+// therefore uses a config with no (content ...) test, so no extractor
+// ever runs and the result is identical on any machine, with or without
+// poppler installed.
+//
+// The tree is built once in b.TempDir(), before the timer starts; each
+// iteration re-plans the same on-disk tree with a fresh plan.Claims, so
+// iterations are independent and repeatable.
+func BenchmarkPlan(b *testing.B) {
+	root := b.TempDir()
+	scanRoot := filepath.Join(root, "Filed")
+	buildBenchTree(b, scanRoot)
+
+	mainFile := filepath.Join(root, "krino.conf")
+	if err := os.WriteFile(mainFile, []byte(`(include "dl")`), 0o644); err != nil {
+		b.Fatal(err)
+	}
+	dirsDir := filepath.Join(root, "dirs")
+	if err := os.MkdirAll(dirsDir, 0o755); err != nil {
+		b.Fatal(err)
+	}
+	// Type-only rules (no content test), one per group present in the
+	// generated tree, mirroring examples/by-type.conf; "dat" files match
+	// none of them and take the unmatched path through Match.
+	dirConf := fmt.Sprintf(`
+(path %q)
+(recursive yes)
+(min-age 0s)
+(rule "images" (when (type image)) (move "Sorted/Images") (stop))
+(rule "documents" (when (type document)) (move "Sorted/Documents") (stop))
+(rule "spreadsheets" (when (type spreadsheet)) (move "Sorted/Spreadsheets") (stop))
+(rule "archives" (when (type archive)) (move "Sorted/Archives") (stop))
+(rule "media" (when (or (type audio) (type video))) (move "Sorted/Media") (stop))
+`, scanRoot)
+	if err := os.WriteFile(filepath.Join(dirsDir, "dl.conf"), []byte(dirConf), 0o644); err != nil {
+		b.Fatal(err)
+	}
+
+	e, errs := Load(mainFile, "dl")
+	if len(errs) > 0 {
+		b.Fatalf("config errors: %v", errs)
+	}
+
+	ctx := context.Background()
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := e.Plan(ctx, e.Dirs[0], plan.NewClaims()); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+// benchTreeDirs * benchFilesPerDir files are generated, spread over
+// nested directories so the walk itself is exercised, not just a single
+// flat directory read.
+const (
+	benchTreeDirs    = 12
+	benchFilesPerDir = 150
+)
+
+// buildBenchTree creates a synthetic tree under root for BenchmarkPlan:
+// nested "Sub" directories holding files that cycle through extensions
+// spanning several of Appendix A's type groups, plus one extension
+// ("dat") that matches no rule. Names are neutral (Sub, a<N>.<ext>) -
+// never anything from a real folder, per the leak-check patterns.
+func buildBenchTree(b *testing.B, root string) {
+	b.Helper()
+	exts := []string{"pdf", "jpg", "xlsx", "zip", "mp3", "dat"}
+	old := time.Now().Add(-time.Hour)
+	n := 0
+	for d := 0; d < benchTreeDirs; d++ {
+		dir := filepath.Join(root, fmt.Sprintf("Sub%d", d), "Nested")
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			b.Fatal(err)
+		}
+		for f := 0; f < benchFilesPerDir; f++ {
+			ext := exts[n%len(exts)]
+			p := filepath.Join(dir, fmt.Sprintf("a%04d.%s", n, ext))
+			if err := os.WriteFile(p, []byte("x"), 0o644); err != nil {
+				b.Fatal(err)
+			}
+			if err := os.Chtimes(p, old, old); err != nil {
+				b.Fatal(err)
+			}
+			n++
+		}
+	}
+}
diff --git a/internal/journal/read_test.go b/internal/journal/read_test.go
index 3ffa14d..2f0f40f 100644
--- a/internal/journal/read_test.go
+++ b/internal/journal/read_test.go
@@ -196,6 +196,220 @@ func TestRunsDoesNotMarkUndoneWhenOnlyOkEntryIsMkdir(t *testing.T) {
 	}
 }
 
+// TestEntriesCrashedRunReturnsNilError is item 1: a run-start present,
+// run-end absent, and otherwise clean is exactly the crashed-run shape
+// Entries' own doc comment says it must accept - "to end of file when there
+// is no run-end (a crashed run, which is precisely when corruption is
+// likely)". Pinning it as its own test, rather than leaving it implicit in
+// tests about something else, is the point of the item.
+func TestEntriesCrashedRunReturnsNilError(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "krino.log")
+	w, _ := Open(path)
+	at := time.Date(2026, 9, 12, 8, 0, 0, 0, time.UTC)
+	if err := w.Append(Entry{Time: at, Run: "A", Action: "run-start", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "A", Dir: "dl", File: "x.pdf", Step: 1,
+		Action: "move", Status: "ok", Src: "/a/x.pdf", Dst: "/b/x.pdf"}); err != nil {
+		t.Fatal(err)
+	}
+	// No run-end: the process crashed right here.
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := Entries(path, "A")
+	if err != nil {
+		t.Fatalf("a crashed but otherwise clean run returned an error: %v", err)
+	}
+	if len(got) != 2 || got[0].Action != "run-start" || got[1].Action != "move" {
+		t.Errorf("entries = %+v, want [run-start, move]", got)
+	}
+}
+
+// TestEntriesIntactRunReturnsNilError is item 2: a complete, clean run -
+// run-start, a step, run-end, nothing corrupt - must read back with a nil
+// error. Every other test in this file needs this to be true along the way,
+// but none of them state it as their own point; this one does.
+func TestEntriesIntactRunReturnsNilError(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "krino.log")
+	w, _ := Open(path)
+	at := time.Date(2026, 9, 12, 8, 0, 0, 0, time.UTC)
+	if err := w.Append(Entry{Time: at, Run: "A", Action: "run-start", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "A", Dir: "dl", File: "x.pdf", Step: 1,
+		Action: "move", Status: "ok", Src: "/a/x.pdf", Dst: "/b/x.pdf"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "A", Action: "run-end", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := Entries(path, "A")
+	if err != nil {
+		t.Fatalf("a fully intact run returned an error: %v", err)
+	}
+	if len(got) != 3 || got[0].Action != "run-start" || got[1].Action != "move" || got[2].Action != "run-end" {
+		t.Errorf("entries = %+v, want [run-start, move, run-end]", got)
+	}
+}
+
+// TestEntriesBothFailureModesReportsBadLineFirst is item 3: a run that both
+// has an unparsable line inside its window AND lacks a readable run-start
+// must surface as the unparsable-line error, not the missing-run-start one -
+// Entries checks badLine before sawRunStart. The run-start line here is
+// destroyed unattributably (as in TestEntriesFailsClosedOnMissingRunStart),
+// and a second, still-attributable line is separately corrupted so badLine
+// is set via the runFieldOf fallback rather than the window check.
+func TestEntriesBothFailureModesReportsBadLineFirst(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "krino.log")
+	w, _ := Open(path)
+	at := time.Date(2026, 9, 12, 8, 0, 0, 0, time.UTC)
+	if err := w.Append(Entry{Time: at, Run: "A", Action: "run-start", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "A", Dir: "dl", File: "x.pdf", Step: 1,
+		Action: "move", Status: "ok", Src: "/a/x.pdf", Dst: "/b/x.pdf"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "A", Action: "run-end", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	lines := strings.Split(strings.TrimRight(string(raw), "\n"), "\n")
+	if len(lines) != 3 {
+		t.Fatalf("fixture has %d lines, want 3", len(lines))
+	}
+	// Line 1 (run-start): destroyed unattributably - no tabs at all, so
+	// runFieldOf cannot even recover its Run column.
+	lines[0] = "totally-mangled-no-tabs-here"
+	// Line 2 (move): corrupt its Step column only - it keeps its tabs and
+	// its Run column ("A") stays readable via runFieldOf's fallback.
+	fields := strings.Split(lines[1], "\t")
+	fields[4] = "not-a-number"
+	lines[1] = strings.Join(fields, "\t")
+	if err := os.WriteFile(path, []byte(strings.Join(lines, "\n")+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := Entries(path, "A")
+	if err == nil {
+		t.Fatal("Entries returned no error with both a bad line and a missing run-start present")
+	}
+	if !strings.Contains(err.Error(), "unparsable line 2") {
+		t.Errorf("error = %q, want it to report the unparsable line (line 2), not the missing run-start", err)
+	}
+	if len(got) != 1 || got[0].Action != "run-end" {
+		t.Errorf("entries = %+v, want just the surviving run-end", got)
+	}
+}
+
+// TestEntriesAdjacentRunStartsOneCorrupted is item 4. Ruling R2: this pins
+// what journal.Entries does TODAY for two runs whose run-start lines are
+// adjacent, one of them corrupted - it does not assert an invented "correct"
+// result, and internal/journal is not touched by this task. The log here is
+// exactly:
+//
+//	1  run-start A          (good)
+//	2  run-start B          (corrupted: no tabs, unattributable)
+//	3  move      A          (good)
+//	4  run-end   A          (good)
+//	5  move      B          (good)
+//	6  run-end   B          (good)
+//
+// Observed behaviour, traced by hand against Entries and confirmed by this
+// test: Entries(path, "A") fails closed with the unparsable-line error,
+// because line 2 falls inside A's own window (opened by line 1, not yet
+// closed by a run-end) even though the corrupted line was actually B's
+// run-start, not A's - this is exactly the "residual risk... a false
+// refusal, not a false success" the function's own doc comment already
+// names. Entries(path, "B"), in contrast, never sees line 2 as inside its
+// window (B's window has not opened - its own run-start is the corrupted
+// line), so it reaches the end of the file with no badLine, and instead
+// fails on B's missing run-start.
+//
+// Concern (not fixed here, per R2 - flagged for judgement, not code
+// change): the SAME corrupted line produces two different error shapes
+// depending only on which run asks, which is a surprising inconsistency in
+// the message a caller sees, even though both directions correctly fail
+// closed.
+func TestEntriesAdjacentRunStartsOneCorrupted(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "krino.log")
+	w, _ := Open(path)
+	at := time.Date(2026, 9, 12, 8, 0, 0, 0, time.UTC)
+	if err := w.Append(Entry{Time: at, Run: "A", Action: "run-start", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "B", Action: "run-start", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "A", Dir: "dl", File: "x.pdf", Step: 1,
+		Action: "move", Status: "ok", Src: "/a/x.pdf", Dst: "/b/x.pdf"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "A", Action: "run-end", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "B", Dir: "dl", File: "y.pdf", Step: 1,
+		Action: "move", Status: "ok", Src: "/a/y.pdf", Dst: "/b/y.pdf"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Append(Entry{Time: at, Run: "B", Action: "run-end", Status: "ok"}); err != nil {
+		t.Fatal(err)
+	}
+	if err := w.Close(); err != nil {
+		t.Fatal(err)
+	}
+
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	lines := strings.Split(strings.TrimRight(string(raw), "\n"), "\n")
+	if len(lines) != 6 {
+		t.Fatalf("fixture has %d lines, want 6", len(lines))
+	}
+	// Line 2, B's run-start, adjacent to A's on line 1: destroyed
+	// unattributably.
+	lines[1] = "totally-mangled-no-tabs-here"
+	if err := os.WriteFile(path, []byte(strings.Join(lines, "\n")+"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	gotA, errA := Entries(path, "A")
+	if errA == nil {
+		t.Fatal("Entries(A) returned no error; pinned behaviour expects one (the corrupted adjacent line falls inside A's window)")
+	}
+	if !strings.Contains(errA.Error(), "unparsable line 2") {
+		t.Errorf("Entries(A) error = %q, want it to name the unparsable line 2", errA)
+	}
+	if len(gotA) != 3 || gotA[0].Action != "run-start" || gotA[1].Action != "move" || gotA[2].Action != "run-end" {
+		t.Errorf("Entries(A) = %+v, want A's own [run-start, move, run-end]", gotA)
+	}
+
+	gotB, errB := Entries(path, "B")
+	if errB == nil {
+		t.Fatal("Entries(B) returned no error; pinned behaviour expects one (B's own run-start is the corrupted line)")
+	}
+	if !strings.Contains(errB.Error(), "no readable run-start") {
+		t.Errorf("Entries(B) error = %q, want it to name the missing run-start", errB)
+	}
+	if len(gotB) != 2 || gotB[0].Action != "move" || gotB[1].Action != "run-end" {
+		t.Errorf("Entries(B) = %+v, want B's surviving [move, run-end]", gotB)
+	}
+}
+
 // TestEntriesReportsAMangledLine: a corrupt line that is not the log's
 // final line must not be silently dropped by Entries the way Runs drops it
 // - PlanUndo needs to know a step went missing so it can refuse the whole
diff --git a/internal/tui/tui.go b/internal/tui/tui.go
index 96bb728..c9f1241 100644
--- a/internal/tui/tui.go
+++ b/internal/tui/tui.go
@@ -36,9 +36,9 @@ func Colour(w io.Writer) bool {
 	return !noColour
 }
 
-// Height is the terminal's row count, 0 when it is not a terminal or the
+// height is the terminal's row count, 0 when it is not a terminal or the
 // size cannot be read.
-func Height(w io.Writer) int {
+func height(w io.Writer) int {
 	f, ok := w.(*os.File)
 	if !ok || !isTerminal(int(f.Fd())) {
 		return 0
@@ -73,7 +73,7 @@ func Page(w io.Writer, text string) error {
 // the terminal the pager would inherit, not the writer text is otherwise
 // sent to.
 func fitsWithoutPaging(text string) bool {
-	h := Height(os.Stdout)
+	h := height(os.Stdout)
 	if h <= 0 {
 		return true
 	}
diff --git a/internal/tui/tui_test.go b/internal/tui/tui_test.go
index 6918859..a3640ac 100644
--- a/internal/tui/tui_test.go
+++ b/internal/tui/tui_test.go
@@ -37,8 +37,8 @@ func TestColourNeedsTerminalAndNoNOCOLOR(t *testing.T) {
 
 func TestHeight(t *testing.T) {
 	var buf bytes.Buffer
-	if h := Height(&buf); h != 0 {
-		t.Errorf("Height on a non-terminal writer = %d, want 0", h)
+	if h := height(&buf); h != 0 {
+		t.Errorf("height on a non-terminal writer = %d, want 0", h)
 	}
 
 	oldT, oldS := isTerminal, termSize
@@ -46,8 +46,8 @@ func TestHeight(t *testing.T) {
 	isTerminal = func(fd int) bool { return true }
 	termSize = func(fd int) (int, int, error) { return 80, 24, nil }
 
-	if h := Height(os.Stdout); h != 24 {
-		t.Errorf("Height = %d, want 24", h)
+	if h := height(os.Stdout); h != 24 {
+		t.Errorf("height = %d, want 24", h)
 	}
 }
 
diff --git a/man/krino.1 b/man/krino.1
new file mode 100644
index 0000000..627a2ee
--- /dev/null
+++ b/man/krino.1
@@ -0,0 +1,348 @@
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.Dd September 13, 2026
+.Dt KRINO 1
+.Os
+.Sh NAME
+.Nm krino
+.Nd sort files in a directory by rules
+.Sh SYNOPSIS
+.Nm
+.Op Fl y | Fl n
+.Op Fl v
+.Op Fl -json
+.Op Fl c Ar file
+.Op Ar name ...
+.Pp
+.Nm
+.Cm init
+.Pp
+.Nm
+.Cm new
+.Ar name path
+.Pp
+.Nm
+.Cm check
+.Op Ar name ...
+.Pp
+.Nm
+.Cm explain
+.Ar file
+.Pp
+.Nm
+.Cm log
+.Op Fl n Ar count
+.Pp
+.Nm
+.Cm undo
+.Op Ar run
+.Sh DESCRIPTION
+.Nm
+sorts the files in one or more configured directories according to rules
+kept in
+.Xr krino.conf 5 .
+For each directory in turn it scans the files, evaluates every rule against
+every file, and builds a plan: the chain of actions
+.Pq Ic copy , Ic move , Ic rename , Ic delete
+that the file's matching rules add up to.
+.Pp
+Every rule that matches a file adds its actions to that file's chain, in
+the order the rules are written;
+.Sy (stop)
+on a matching rule ends the chain for that file, so a later rule is never
+even evaluated against it.
+A rule with no actions besides
+.Sy (stop)
+is an exclusion.
+.Pp
+Every test sees the file as it was when the directory was scanned: name,
+path, size, modification time and content.
+Actions already added to a file's chain by an earlier rule never change
+what a later rule's tests see, so the whole plan for a directory can be
+computed, shown, and approved before anything is touched.
+.Pp
+With no
+.Fl y
+or
+.Fl n ,
+.Nm
+prints the plan and asks how to proceed
+.Pq Sx REVIEW .
+.Fl y
+applies the plan without asking;
+.Fl n
+prints it and changes nothing.
+If standard input is not a terminal and neither is given,
+.Nm
+refuses rather than guess.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl y
+Apply the plan without asking.
+Cannot be combined with
+.Fl n .
+.It Fl n
+Dry run: print the plan and exit without changing anything.
+.It Fl v
+Also list files that were skipped as unmatched, ignored or busy, and show
+the full reason a test matched or not.
+.It Fl -json
+With
+.Fl n ,
+print the plan as JSON instead of the table.
+Refused unless
+.Fl n
+is also given.
+The document's own
+.Ic note
+field says its shape is unstable before krino 1.0; a script that reads it
+should expect it to change before then.
+.It Fl c Ar file
+Use
+.Ar file
+in place of
+.Pa $XDG_CONFIG_HOME/krino/krino.conf .
+.It Fl h , Fl -help
+Print usage and exit.
+.It Fl -version
+Print
+.Dq krino Ar version
+and exit.
+.El
+.Sh SUBCOMMANDS
+.Bl -tag -width Ds
+.It Ic init
+Create the config directory with a commented
+.Pa krino.conf
+and
+.Pa template.conf .
+Refuses if
+.Pa krino.conf
+already exists, and leaves an existing
+.Pa template.conf
+alone.
+.It Ic new Ar name path
+Copy
+.Pa template.conf
+to
+.Pa dirs/ Ns Ar name Ns Pa .conf ,
+fill in
+.Ar path ,
+and append
+.Ar name
+to
+.Ic include
+in
+.Pa krino.conf ,
+keeping its comments.
+.It Ic check Op Ar name ...
+Validate the configuration, list each included directory's rules, and list
+which content-extraction tools
+.Pq Xr krino.conf 5 , Sx CONTENT EXTRACTION
+are available.
+With no
+.Ar name ,
+checks every included directory.
+.It Ic explain Ar file
+Evaluate every rule of
+.Ar file Ns 's
+directory against it and show each test's result, so a rule that should
+match but does not
+.Pq or the reverse
+can be diagnosed test by test.
+See
+.Sx KNOWN LIMITATIONS .
+.It Ic log Op Fl n Ar count
+List the most recent runs, newest first
+.Pq Ar count No defaults to 10 :
+the run id, its start time, the directories it touched, and what it did.
+A run that a later
+.Ic undo
+has reversed at least one file of is marked
+.Pq undone .
+.It Ic undo Op Ar run
+Reverse
+.Ar run .
+With no
+.Ar run ,
+reverse the most recent run; if that run is itself an undo, it is refused.
+An older run is undone by naming it.
+See
+.Sx UNDO .
+.El
+.Sh REVIEW
+With neither
+.Fl y
+nor
+.Fl n ,
+after showing one directory's plan
+.Nm
+asks:
+.Bd -literal -offset indent
+[a] apply all  [c] choose per file  [s] skip this directory  [q] quit
+.Ed
+.Pp
+.Ic a
+applies every step of every chain shown.
+.Ic s
+applies nothing in this directory and moves on to the next one.
+.Ic q
+stops
+.Nm
+entirely; directories already applied earlier in this run stay applied and
+can be reversed with
+.Ic undo .
+.Pp
+.Ic c
+asks about each file in turn:
+.Bd -literal -offset indent
+  [y] yes  [n] no  [a] yes to this and all remaining  [d] done, apply chosen so far  [q] quit, apply nothing
+.Ed
+.Pp
+Approval is per file: a file's whole chain runs, or none of it.
+.Ic d
+stops asking and applies whatever was already chosen, declining the rest.
+.Ic q
+here aborts the review for this directory entirely, discarding even a file
+already marked
+.Ic yes ,
+and folds into the top-level
+.Ic q
+above.
+.Sh UNDO
+.Ic krino undo
+reverses a run's steps, last step first within each file, after building
+and showing a plan of its own
+.Pq shown and approved the same way as a sort plan; Fl y No and Fl n No apply .
+One undo plan covers every directory the run touched, so its menu has no
+per-directory skip;
+.Ic s
+and
+.Ic q
+both apply nothing:
+.Bd -literal -offset indent
+[a] apply all  [c] choose per file  [s] skip  [q] quit
+.Ed
+.Pp
+An undo run cannot itself be undone: naming it to
+.Ic undo
+is refused.
+.Pp
+A step's reversal is refused when the world has moved on since the step ran
+.Pq its target is gone or has changed, or the original path is occupied again ;
+a refused file has nothing of its chain reversed, so no file is left half
+undone.
+An exception is a created directory found non-empty at its own turn: that
+alone does not refuse the rest of the file's reversal, since it means
+another file still lives there, not that something unexpected changed
+underfoot.
+Every created directory still empty once every file in the run has had its
+turn is then removed, deepest path first, so an undo does not leave the
+empty directories it made behind.
+.Pp
+A permanent delete,
+.Sy (delete permanent) ,
+is never undoable; it is shown in the plan with that reason and nothing is
+attempted for it.
+.Pp
+.Ic krino log
+marks a run
+.Pq undone
+once its undo run has reversed at least one file's chain \(em not that
+every file in it was restored: a run left partly reversed, because some
+files were declined during the undo's own review, is still shown as
+.Pq undone
+in full.
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev XDG_CONFIG_HOME
+Base of the configuration directory
+.Pq Pa $XDG_CONFIG_HOME/krino ;
+default
+.Pa ~/.config .
+.It Ev XDG_STATE_HOME
+Base of the log and the per-directory lock files
+.Pq Pa $XDG_STATE_HOME/krino ;
+default
+.Pa ~/.local/state .
+.It Ev XDG_DATA_HOME
+Base of the trash a
+.Sy (delete)
+step uses
+.Pq Pa $XDG_DATA_HOME/Trash ;
+default
+.Pa ~/.local/share .
+.It Ev PAGER
+Used to show a plan taller than the terminal; default
+.Dq less -FRX .
+Never used for
+.Fl -json
+output.
+.It Ev NO_COLOR
+When set, disables the ANSI colour
+.Nm
+otherwise uses on a terminal for a permanent delete and a refused undo
+step.
+.El
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa $XDG_CONFIG_HOME/krino/krino.conf
+The main configuration file: which directories run, defaults, the log
+path.
+.It Pa $XDG_CONFIG_HOME/krino/template.conf
+Copied by
+.Ic krino new
+for each new directory.
+.It Pa $XDG_CONFIG_HOME/krino/dirs/ Ns Ar name Ns Pa .conf
+One file per configured directory.
+.It Pa $XDG_STATE_HOME/krino/krino.log
+The append-only log every run writes to.
+.It Pa $XDG_STATE_HOME/krino/ Ns Ar name Ns Pa .lock
+Held for the duration of a run against directory
+.Ar name ,
+so a second
+.Nm
+against the same directory waits, or fails immediately with
+.Fl y .
+.It Pa $XDG_DATA_HOME/Trash
+The freedesktop.org trash a
+.Sy (delete)
+step moves files into.
+.El
+.Sh EXIT STATUS
+.Bl -tag -width Ds
+.It 0
+Success, including a run that found nothing to do, or one whose plan was
+entirely declined at review.
+.It 1
+A step failed, a directory's lock was already held by another
+.Nm ,
+or a configured directory could not be read.
+.It 2
+A usage mistake or a configuration error.
+Flags must come before any directory name on the command line: a flag
+found after a directory name is a usage error rather than a guess.
+.It 130
+Interrupted
+.Pq Ic Ctrl-C
+or terminated; the current step, if any, is finished and logged first.
+.El
+.Sh KNOWN LIMITATIONS
+.Ic krino explain
+evaluates every test of every rule's condition against the file, without
+the cost-ordered short-circuiting a real run uses within an
+.Sy and/or .
+It can therefore run a content-extraction tool, and report a
+.Dq content unreadable
+warning, for a test that a real run would never reach because an earlier,
+cheaper test in the same condition already decided the rule did not match.
+.Ic explain
+is a full trace of every test, not a cost-faithful preview of what
+.Fl n
+would actually spend time on.
+.Sh SEE ALSO
+.Xr krino.conf 5
+.Pp
+.Pa docs/sexp-primer.md
+in the source repository
+.Pq installed at Pa $PREFIX/share/doc/krino/sexp-primer.md
+is a short tutorial on the configuration syntax.
diff --git a/man/krino.conf.5 b/man/krino.conf.5
new file mode 100644
index 0000000..fbd1c06
--- /dev/null
+++ b/man/krino.conf.5
@@ -0,0 +1,696 @@
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.Dd September 13, 2026
+.Dt KRINO.CONF 5
+.Os
+.Sh NAME
+.Nm krino.conf
+.Nd krino's configuration language and files
+.Sh DESCRIPTION
+.Xr krino 1 Ns 's
+configuration is written in s-expressions: each form is a list inside
+parentheses, holding an operation optionally followed by its arguments.
+A short tutorial is
+.Pa docs/sexp-primer.md
+in the source repository, installed at
+.Pa $PREFIX/share/doc/krino/sexp-primer.md .
+This page is the reference for every form.
+.Pp
+.Bl -bullet -compact
+.It
+.Sy List :
+.Ql \&(
+items separated by whitespace
+.Ql \&) .
+.It
+.Sy String :
+.Ql \&"...\&" .
+A backslash escapes only
+.Ql \&"
+and
+.Ql \e ;
+any other backslash is kept literally, so
+.Ql \&"\ebacme\eb\&"
+is the regex
+.Ql \ebacme\eb .
+Strings may span lines.
+.It
+.Sy Symbol :
+any other run of characters except whitespace,
+.Ql \&( ,
+.Ql \&) ,
+.Ql \&" ,
+.Ql \&; .
+.It
+.Sy Comment :
+.Ql \&;
+to end of line.
+.El
+.Pp
+Encoding is UTF-8 only.
+There is no other syntax: no quote characters, no dotted pairs, no block
+comments.
+Paths, keywords, regexes and rule names must be strings; settings values,
+type names, operators, sizes and durations are symbols.
+.Pp
+Every list and atom's byte offset, line and column is recorded, so
+.Ic krino new
+can splice a name into
+.Ic include
+without disturbing anything else in the file, and a syntax error is
+reported as
+.Ar file : Ns Ar line : Ns Ar col .
+.Sh FILES
+.Ss krino.conf
+The main file, read first:
+.Bd -literal -offset indent
+(include "downloads" "invoices")   ; dirs/\*(Ltname\*(Gt.conf, run in this order
+(log "~/.local/state/krino/krino.log")   ; optional
+(defaults                          ; optional; any setting below
+  (min-age 5m))
+.Ed
+.Bl -tag -width Ds
+.It Ic (include Ar name No ...)
+The directories to sort, in the order given.
+Each
+.Ar name
+has its rules in
+.Pa dirs/ Ns Ar name Ns Pa .conf .
+.It Ic (log Ar path )
+Where the log goes.
+Optional; defaults to
+.Pa $XDG_STATE_HOME/krino/krino.log .
+.It Ic (defaults Ar setting No ...)
+Defaults for every directory; a directory's own file, and a rule inside
+it, can override them.
+See
+.Sx SETTINGS .
+.El
+.Ss dirs/name.conf
+One file per configured directory:
+.Bd -literal -offset indent
+(path "~/downloads")                     ; required
+(recursive no)                           ; any setting from SETTINGS
+(ignore "*.part" "*.aria2" ".*")         ; may repeat; patterns accumulate in order
+
+(rule "acme"
+  (when (type document)
+        (or (content "acme ltd" "0000000000")
+            (name "(^|[^a-z0-9])acme([^a-z0-9]|$)"))
+        (not (name "^draft")))
+  (move "Work/Acme/{mtime:%Y}")
+  (stop))
+.Ed
+.Pp
+Top-level forms may appear in any order, except that rules run in the
+order written.
+.Bl -tag -width Ds
+.It Ic (path Ar dir )
+Required.
+The directory this file sorts.
+.Ar ~
+expands.
+.It Ic (ignore Ar pattern No ...)
+May repeat; patterns accumulate in order.
+Gitignore syntax:
+.Ql * ,
+.Ql ** ,
+.Ql \&? ,
+.Ql [...] ;
+a leading
+.Ql /
+anchors to the root; a trailing
+.Ql /
+matches directories only;
+.Ql \&!
+re-includes; a pattern with no
+.Ql /
+matches at any depth; the last matching pattern wins.
+An ignored directory is not descended into.
+.It Ic (rule Ar name item No ...)
+See
+.Sx RULES .
+.El
+.Sh SETTINGS
+Each setting may appear in
+.Ic (defaults ...) ,
+at the top of a directory file, or, where marked
+.Pq rule ,
+inside a
+.Ic rule
+form.
+The most specific wins: rule, then directory, then defaults, then the
+built-in default below.
+Durations are an integer plus
+.Ql s m h d w ;
+sizes an integer plus an optional
+.Ql K M G T
+.Pq powers of 1024 .
+.Bl -tag -width Ds
+.It Ic case
+.Pq rule .
+.Sy ignore
+or
+.Sy strict :
+case sensitivity for
+.Ic name , path
+and
+.Ic content .
+Built-in:
+.Sy ignore .
+.It Ic fold
+.Pq rule .
+.Sy yes
+or
+.Sy no :
+strip diacritics before comparing
+.Po
+a with an ogonek becomes plain a, an l with a stroke becomes plain l,
+e acute becomes plain e, u with diaeresis becomes plain u,
+and so on for every Latin letter
+.Pc .
+Built-in:
+.Sy yes .
+.It Ic recursive
+.Sy yes
+or
+.Sy no .
+Built-in:
+.Sy no .
+.It Ic max-depth
+An integer;
+.Sy 1
+means the root only.
+Built-in: unlimited.
+.It Ic min-age
+A duration.
+Files modified more recently are skipped as busy.
+Built-in:
+.Sy 2m .
+.It Ic max-read
+A size.
+No content is extracted from a file above this size.
+Built-in:
+.Sy 50M .
+.It Ic busy
+One or more suffixes.
+A file is skipped when its own name with one of these suffixes appended
+also exists beside it, e.g.
+.Pa report.pdf.part
+beside
+.Pa report.pdf .
+Built-in:
+.Sy .part .aria2 .crdownload .
+.It Ic on-conflict
+.Pq rule .
+.Sy suffix , skip
+or
+.Sy overwrite :
+see
+.Sx Conflicts .
+Built-in:
+.Sy suffix .
+.El
+.Sh RULES
+.Bd -literal -offset indent
+(rule NAME ITEM...)
+.Ed
+.Pp
+Items, in any order except that actions run in the order written:
+.Bl -tag -width Ds
+.It Ic (when Ar cond No ...)
+The condition; see
+.Sx CONDITIONS .
+Several conditions means all must hold.
+A rule with no
+.Ic when
+matches every file.
+An empty
+.Ic (when)
+is an error.
+.It Ic case , Ic fold , Ic on-conflict
+Rule-level settings; see
+.Sx SETTINGS .
+.It Ic (copy Ar dest )
+Copy the file into directory
+.Ar dest .
+.It Ic (move Ar dest )
+Move the file into directory
+.Ar dest .
+.It Ic (rename Ar name )
+Rename in place.
+.Ar name
+must not contain
+.Ql / .
+.It Ic (delete)
+Move to the trash.
+.It Ic (delete permanent)
+Unlink.
+Cannot be undone.
+.It Ic (stop)
+Once this rule matches, evaluate no further rules for this file.
+.El
+.Pp
+A rule with only
+.Ic (stop)
+is an exclusion: files it matches receive no actions from later rules.
+.Pp
+.Ar dest
+is a directory: a relative path is relative to the root,
+.Ql ~
+expands, an absolute path is allowed, and it is created if missing.
+.Ar dest
+and
+.Ar name
+take placeholders; see
+.Sx Placeholders .
+.Sh CONDITIONS
+.Ss Operators
+.Ic (and Ar cond No ...) ,
+.Ic (or Ar cond No ...) ,
+.Ic (not Ar cond ) .
+.Ic and
+and
+.Ic or
+take one or more arguments;
+.Ic not
+exactly one.
+.Ss Tests
+.Bl -tag -width Ds
+.It Ic (type Ar t No ...)
+True when the name ends in
+.Ql \&. Ns Ar t
+for any
+.Ar t ,
+case-insensitively.
+.Ar t
+may be a type group
+.Po
+e.g.\&
+.Ic document ;
+see
+.Sx TYPE GROUPS
+.Pc
+or a multi-part suffix like
+.Ic tar.gz .
+.It Ic (name Ar re No ...)
+True when the file name matches any of the regexes.
+.It Ic (path Ar re No ...)
+True when the path relative to the root matches any of the regexes.
+.It Ic (content Ar keyword No ...)
+True when the extracted text contains any of the keywords; see
+.Sx CONTENT EXTRACTION .
+.It Ic (size Ar op size )
+.Ar op
+is one of
+.Ql > >= < <= = .
+.It Ic (age Ar op duration )
+Age by modification time.
+.It Ic (duplicate)
+True when another scanned file has identical content and this one is not
+the chosen original; see
+.Sx DUPLICATES .
+.It Ic (duplicate Ar dir No ...)
+The same, also comparing against every regular file under
+.Ar dir .
+.It Ic (matched)
+True when an earlier rule already matched this file.
+.El
+.Pp
+Regexes use Go's RE2 syntax: POSIX extended regular expressions plus
+.Ql \ed \ew \es \eb ,
+non-greedy quantifiers, and the inline flags
+.Ql (?i)
+and
+.Ql (?-i) ;
+there are no backreferences and no lookaround.
+.Ss Case, folding and word boundaries
+.Ic case
+and
+.Ic fold
+apply to
+.Ic name , path
+and
+.Ic content ,
+in both the file's data and the pattern;
+.Ic type
+is always case-insensitive.
+A regex can override
+.Ic case
+locally with
+.Ql (?i)
+or
+.Ql (?-i) .
+.Pp
+.Sy RE2 treats
+.Ql _
+as a word character.
+.Ql \eb
+is the boundary between a word character and a non-word character, so
+.Ql \ebacme\eb
+does
+.Em not
+match
+.Ar ACME_REPORT_2026.pdf :
+the
+.Ql E
+before the underscore and the underscore itself are both word characters,
+so there is no boundary there for
+.Ql \eb
+to match.
+Use a character class instead of
+.Ql \eb
+when the name may be glued to the rest with an underscore or a digit:
+.Bd -literal -offset indent
+(name "(^|[^a-z0-9])acme([^a-z0-9]|$)")
+.Ed
+matches
+.Ar ACME_REPORT_2026.pdf
+.Pq case-insensitively, by default
+because it treats anything that is not a lowercase letter or digit,
+including
+.Ql _ ,
+as a separator.
+.Sh TYPE GROUPS
+A group name in
+.Ic (type ...)
+stands for every extension listed for it:
+.Bl -tag -width "presentation"
+.It Ic image
+jpg jpeg png gif webp bmp tif tiff heic heif avif svg ico raw cr2 nef arw dng
+.It Ic video
+mp4 mkv webm mov avi m4v mpg mpeg wmv flv 3gp
+.It Ic audio
+mp3 flac ogg opus m4a aac wav wma aiff
+.It Ic archive
+zip tar gz tgz bz2 tbz2 xz txz zst 7z rar lz lzma cpio
+.It Ic document
+pdf doc docx odt rtf txt md tex
+.It Ic spreadsheet
+xls xlsx ods csv tsv
+.It Ic presentation
+ppt pptx odp
+.It Ic ebook
+epub mobi azw azw3 fb2 djvu
+.It Ic code
+go c h cpp hpp py sh js ts rs java rb pl lua html css json yaml yml toml xml sql
+.It Ic text
+txt md log csv tsv json yaml yml toml xml ini conf
+.It Ic package
+deb rpm apk appimage exe msi flatpak snap
+.It Ic font
+ttf otf woff woff2
+.El
+.Pp
+Groups overlap; a file can belong to several.
+.Sh CONTENT EXTRACTION
+.Bl -tag -width "presentation"
+.It Sy text
+Known text extensions, or detected from the first 8 KiB: valid UTF-8, or
+UTF-16 with a BOM, and no NUL bytes.
+.It Sy pdf
+.Ic pdftotext
+.Pq 30 second timeout .
+.It Sy docx, xlsx, pptx, odt, ods, odp, epub
+Zip plus streaming XML, Go standard library only.
+.It Sy html, xml
+Tags removed, entities decoded.
+.It Sy doc
+.Ic antiword ,
+else
+.Ic catdoc .
+.It Sy xls / ppt
+.Ic xls2csv
+or
+.Ic catppt
+.Pq both from catdoc .
+.It Sy anything else
+No content.
+.El
+.Pp
+External tools are optional and looked up once per run;
+.Ic krino check
+lists which were found.
+A file above
+.Ic max-read
+is not extracted.
+Tools run without a shell and are given absolute paths only, so a file
+name starting with
+.Ql -
+is never read as an option, and each is killed at its timeout.
+.Pp
+Before matching, text and keywords are normalised the same way: case
+.Pq if Sy ignore ,
+folding
+.Pq if Sy yes ,
+and runs of whitespace collapsed to one space, so a keyword split across
+lines in a PDF still matches.
+Matching is substring:
+.Ql \&"acme\&"
+matches
+.Ql \&"acmeco\&" .
+Words hyphenated across lines in a PDF are not rejoined.
+.Sh ACTIONS
+.Ss Chains
+A file's chain is the actions of every matching rule, in rule order, and
+within a rule in the order written.
+.Ic copy
+leaves the file where it is;
+.Ic rename
+changes its name and
+.Ic move
+its directory, and later steps use the new path;
+.Ic delete
+ends the chain, and steps after it are shown in the plan as
+.Dq skipped: deleted by rule Ar x .
+.Pp
+The plan warns when a chain moves a file more than once; that is usually
+a missing
+.Ic (stop) .
+.Ss How each action runs
+.Bl -tag -width Ds
+.It Ic move
+.Xr rename 2
+when source and destination share a filesystem; otherwise a copy to a
+temporary file in the destination, fsync, rename into place, then the
+source is removed.
+If any step fails the source is untouched and the temporary file is
+removed.
+.It Ic copy
+To a temporary file in the destination, then renamed into place.
+Mode and modification time are preserved.
+.It Ic rename
+.Xr rename 2
+within the same directory.
+.It Ic delete
+Into the freedesktop.org trash at
+.Pa $XDG_DATA_HOME/Trash .
+A file on a different filesystem from the trash is not trashed: the step
+fails with a message suggesting
+.Ic (delete permanent)
+or a move.
+.It Ic (delete permanent)
+.Xr unlink 2 .
+.El
+.Pp
+Before each step, the executor checks that the source still exists with
+the size and modification time recorded in the plan; if not, the step
+fails as
+.Dq changed since plan
+and the rest of that file's chain is skipped.
+.Ss Placeholders
+.Bl -tag -width "{mtime:FMT}"
+.It Ic {name}
+The current file name.
+.It Ic {stem}
+The name without its last extension.
+.It Ic {ext}
+The last extension with its dot, e.g.
+.Ql .pdf ;
+empty if none.
+.It Ic {1} No ... Ic {9}
+Capture groups of the first
+.Ic name
+test, not inside a
+.Ic not ,
+that matched while evaluating this rule.
+.Ic krino check
+refuses a rule that uses
+.Ic { Ns Ar n Ns Ic }
+unless every such
+.Ic name
+test in it has at least
+.Ar n
+groups, and refuses one that uses
+.Ic { Ns Ar n Ns Ic }
+with no
+.Ic name
+test at all.
+.It Ic {mtime:FMT}
+The file's modification time.
+.It Ic {now:FMT}
+The start of the run.
+.It Ic {{ No and Ic }}
+A literal
+.Ql {
+or
+.Ql } .
+.El
+.Pp
+.Ar FMT
+is a strftime subset:
+.Ql %Y %m %d %H %M %S %j %% .
+.Ss Conflicts
+When the computed target already exists:
+.Bl -tag -width Ds
+.It Ic suffix
+.Pq default .
+Use
+.Pa stem_1.ext , stem_2.ext ,
+and so on.
+.It Ic skip
+Skip this step; the chain continues from the file's current path.
+.It Ic overwrite
+Move the existing target to the trash first
+.Pq logged, so undo restores it ,
+then proceed.
+.El
+.Pp
+A
+.Ic copy
+whose target already has identical content is skipped as
+.Dq already there ,
+whatever the policy, so a backup rule can run every time.
+A step whose target is the file itself
+.Pq a Ar dest No that resolves to the file's own directory, or a Ic rename No to its current name
+is skipped as
+.Dq already there
+as well; a directory whose destination's first path component is a
+placeholder relies on this to avoid re-filing its own output \(em see
+.Sx KNOWN LIMITATIONS .
+.Pp
+Conflicts between files in the same plan are resolved when planning, so
+the plan shows final names; an in-plan claim is never displaced.
+The claim set spans the whole run, so two configured directories cannot
+plan the same final name.
+The executor re-checks at execution time; if the name has to change, the
+log records the actual name used.
+.Sh DUPLICATES
+Candidates are the scanned files plus, for
+.Ic (duplicate Ar dir ) ,
+every regular file under
+.Ar dir
+.Pq symlinks skipped .
+Files are grouped by size; only groups of two or more are hashed, first
+the first and last 64 KiB, then SHA-256 of the whole file.
+Empty files are never duplicates.
+.Pp
+Two names for the same file
+.Pq the same device and inode, as a hard link creates
+are never duplicates of
+.Em each other ;
+they may still both independently be duplicates of a separate file with
+identical content.
+.Pp
+The
+.Em original
+in each group is, in order of preference: a file under one of the given
+.Ar dir
+arguments, then the oldest by modification time, then the shortest name,
+then the name that sorts first.
+.Ic (duplicate)
+is true for every other scanned file in the group.
+.Pp
+.Sy Warning:
+.Ic (duplicate)
+cannot tell a deliberate second copy from an accidental one.
+Byte-identical content is byte-identical either way; the distinction
+between
+.Dq I meant to keep two
+and
+.Dq this should not exist twice
+exists only in the user's intent, not in the files.
+Pairing
+.Ic (duplicate)
+with
+.Ic (delete)
+over a directory that may hold intentional copies
+.Pq a mirror, a staging queue, anything another tool manages
+will delete things the user meant to keep.
+Keep such a rule on a directory scoped narrowly enough that every
+byte-identical pair in it really is an accident.
+.Pp
+.Sy Warning:
+each
+.Ic (duplicate)
+or
+.Ic (duplicate Ar dir )
+condition elects its own original from its own candidates; two conditions
+with different scopes can therefore elect
+.Em different
+originals for the same content.
+Within one directory's rules
+.Pq one rule combining conditions with Ic or , or two separate rules ,
+this can make every copy in a group selected by some condition, and with
+.Ic (delete permanent)
+every copy selected is gone for good.
+.Ic krino
+plans and applies one directory at a time, so a directory already applied
+in the run stays applied while a later directory is planned; a
+.Fl n
+run only ever plans, so it shows every directory's plan as if none of the
+others had been applied.
+Two files in different directories that a
+.Fl n
+plan each lists as a duplicate of the other are therefore not necessarily
+both deleted when the same run is applied with
+.Fl y :
+deleting the first can remove the very original the second file was a
+duplicate of, leaving the second no longer a duplicate by the time its own
+directory is planned.
+Use one duplicate scope for rules that delete within a directory; prefer
+.Ic (delete)
+to
+.Ic (delete permanent)
+with
+.Ic (duplicate) ;
+and within one directory's rules, two files each listed as a duplicate of
+the other in the
+.Fl n
+plan means both would be deleted.
+.Sh KNOWN LIMITATIONS
+A
+.Ar dest
+whose
+.Em first
+path component is itself a placeholder
+.Pq e.g. Ic {ext} No or Ic {mtime:%Y}
+has no static prefix, so nothing under it can be excluded from the walk
+before scanning starts, and a recursive directory walks into
+.Ic krino Ns 's
+own output.
+A file already sitting at its own computed destination is a no-op,
+.Dq already there
+.Pq Sx Conflicts ,
+rather than being re-filed on every run, but the walk still visits it,
+which a
+.Ic (duplicate)
+or
+.Ic content
+test in another rule can also see.
+Give such a rule its own narrow
+.Ic ignore
+pattern, or a
+.Ar dest
+whose first path component is a literal string, when that matters.
+.Pp
+.Ic (duplicate)
+conditions with different scopes do not share an original: two conditions
+electing from different candidate sets can each treat a different file as
+the original of the same content
+.Pq Sx DUPLICATES .
+.Sh SEE ALSO
+.Xr krino 1
+.Pp
+.Pa docs/sexp-primer.md
+in the source repository
+.Pq installed at Pa $PREFIX/share/doc/krino/sexp-primer.md .
diff --git a/scripts/deps b/scripts/deps
new file mode 100755
index 0000000..06faaa2
--- /dev/null
+++ b/scripts/deps
@@ -0,0 +1,99 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# scripts/deps: install krino's optional content extractors with the host's
+# system package manager, per docs/design.md §14.
+#
+# --print prints the exact command this script would run (and the reason,
+# when one platform's package list differs from the others), then exits
+# without running anything and without asking for privileges. `make deps`
+# calls this script with no flag; plain `make`/`make build` never calls it
+# at all, so plain `make` never asks for privileges (§14).
+#
+# Detection:
+#   - Debian family - /etc/os-release's ID *or* ID_LIKE names "debian" as
+#     one of its (possibly multi-word) values. Devuan is ID=devuan,
+#     ID_LIKE=debian: keying on ID=debian alone would leave it unrecognised.
+#     -> apt-get install poppler-utils catdoc antiword
+#   - FreeBSD (uname -s) -> pkg install poppler-utils antiword. catdoc is
+#     left out on purpose: it pulls in tcl/tk.
+#   - OpenBSD (uname -s) -> pkg_add poppler-utils catdoc antiword
+#   - anything else: print what is needed and exit non-zero. This script
+#     never guesses a package manager.
+#
+# Privileges: doas if present, else sudo; if neither exists (and we are not
+# already root), the command is printed for the user to run as root
+# themselves, rather than attempting it unprivileged and failing silently.
+
+set -eu
+
+print_only=0
+case "${1:-}" in
+	--print) print_only=1 ;;
+	"") ;;
+	*)
+		echo "usage: $0 [--print]" >&2
+		exit 2
+		;;
+esac
+
+# is_debian_family: true if /etc/os-release's ID or ID_LIKE contains
+# "debian" as one of its space-separated words.
+is_debian_family() {
+	[ -r /etc/os-release ] || return 1
+	(
+		. /etc/os-release
+		for word in ${ID:-} ${ID_LIKE:-}; do
+			[ "$word" = "debian" ] && exit 0
+		done
+		exit 1
+	)
+}
+
+# privileged CMD...: CMD prefixed with doas or sudo, whichever is found
+# first; unprefixed if we are already root or if neither exists (the
+# caller decides what to do in that last case).
+privileged() {
+	if [ "$(id -u)" = 0 ]; then
+		printf '%s\n' "$*"
+	elif command -v doas >/dev/null 2>&1; then
+		printf 'doas %s\n' "$*"
+	elif command -v sudo >/dev/null 2>&1; then
+		printf 'sudo %s\n' "$*"
+	else
+		printf '%s\n' "$*"
+	fi
+}
+
+note=""
+if is_debian_family; then
+	pkgcmd="apt-get install poppler-utils catdoc antiword"
+elif [ "$(uname -s)" = "FreeBSD" ]; then
+	pkgcmd="pkg install poppler-utils antiword"
+	note="catdoc left out on FreeBSD: it pulls in tcl/tk."
+elif [ "$(uname -s)" = "OpenBSD" ]; then
+	pkgcmd="pkg_add poppler-utils catdoc antiword"
+else
+	echo "krino's optional extractors: poppler-utils (pdftotext), catdoc, antiword" >&2
+	echo "no supported package manager detected (uname -s: $(uname -s), no debian-family /etc/os-release)" >&2
+	echo "install them yourself with whatever this system uses" >&2
+	exit 1
+fi
+
+cmd=$(privileged $pkgcmd)
+
+[ -n "$note" ] && echo "$note"
+
+if [ "$print_only" = 1 ]; then
+	echo "$cmd"
+	exit 0
+fi
+
+if [ "$(id -u)" != 0 ] && ! command -v doas >/dev/null 2>&1 && ! command -v sudo >/dev/null 2>&1; then
+	echo "neither doas nor sudo found; run this yourself as root:" >&2
+	echo "$cmd" >&2
+	exit 1
+fi
+
+echo "$cmd"
+exec $cmd
diff --git a/scripts/man-lint b/scripts/man-lint
new file mode 100755
index 0000000..7b563b7
--- /dev/null
+++ b/scripts/man-lint
@@ -0,0 +1,68 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# man-lint: check the mdoc man pages for real errors, not just "did it run".
+#
+# Prefers `mandoc -Tlint -Wwarning`. -W sets the lowest message level that
+# mandoc reports and counts in its exit status, so this fails (exit 2 or
+# higher) on any WARNING, ERROR or UNSUPP message. STYLE and BASE messages
+# (for example "referenced manual not found" for pages not yet installed)
+# are below that level: not shown, and never a failure. -Werror would not
+# do: it hides warnings and exits 0 on them.
+#
+# Falls back to `groff -ww -z -mdoc` when mandoc is not installed. Two traps
+# with that fallback, both deliberate here:
+#   - the pages are written in the mdoc macro package, not man(7), so this
+#     must ask groff for -mdoc specifically; the wrong package produces
+#     noise (or silently accepts things mdoc would reject);
+#   - groff exits 0 whether or not it complained - -z asks it to run only
+#     the diagnostics pass (no formatted output), so anything at all on its
+#     stderr, not its exit code, is what "failed" means here.
+#
+# Skips with a printed notice, exit 0, when neither tool is installed: a
+# machine with no man toolchain must not fail this gate, the same way
+# internal/ignore's git-oracle test skips itself when git is absent.
+#
+# Usage: scripts/man-lint [FILE...]   (default: man/*.[15])
+
+set -eu
+
+cd "$(git rev-parse --show-toplevel)"
+
+if [ "$#" -gt 0 ]; then
+	# shellcheck disable=SC2124 # deliberately captured as one word list below
+	files="$*"
+else
+	files='man/*.[15]'
+fi
+# shellcheck disable=SC2086 # $files is a glob pattern or an arg list, meant to split/expand
+set -- $files
+if [ "$#" -eq 0 ] || [ ! -e "$1" ]; then
+	echo "man-lint: no man pages found ($files)" >&2
+	exit 1
+fi
+
+if command -v mandoc >/dev/null 2>&1; then
+	echo "man-lint: mandoc -Tlint -Wwarning $*"
+	exec mandoc -Tlint -Wwarning "$@"
+fi
+
+if command -v groff >/dev/null 2>&1; then
+	fail=0
+	for f in "$@"; do
+		echo "man-lint: groff -ww -z -mdoc $f"
+		out=$(groff -ww -z -mdoc "$f" 2>&1 >/dev/null) || true
+		if [ -n "$out" ]; then
+			printf 'man-lint: %s:\n%s\n' "$f" "$out" | sed '2,$s/^/  /' >&2
+			fail=1
+		fi
+	done
+	if [ "$fail" -ne 0 ]; then
+		echo "man-lint: groff reported the warnings above; it exits 0 regardless, so stderr output alone is the failure signal here" >&2
+		exit 1
+	fi
+	exit 0
+fi
+
+echo "man-lint: neither mandoc nor groff is installed; skipping man page lint" >&2
+exit 0