feat(state): validation + friendly errors on both write and eval paths (item 11)

'Never has to master Nix' includes the error messages. The tool grows
validate_state (appearance schema = hard errors; settings.* and
unknown keys = warnings so menu writers and newer schemas keep
working), a read-only `validate` subcommand, and validation BEFORE
every write — an invalid set/apply is refused with the on-disk file
untouched. JSON syntax errors now say line, column, and fix. theme.nix
enforces the same schema at eval time (on the post-defaults state, so
sparse/older files still evaluate) and throws a message naming each
field, its got-value, and the fix paths — the hand-edit escape hatch
no longer ends in a Nix stack trace. Doctor's JSON fix-text points at
validate.

V1: new checks.theme-sync-validate fixture corpus green (good state,
trailing comma, bad hex, bad type, unknown key, refused set with
byte-identical file); negative mkFlake eval of a broken scratch
downstream shows the friendly throw; good-path template-home builds.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

agent/BACKLOG.md

@@ -26,15 +26,6 @@ next, in what order*.
 
 ## NEXT
 
-### 11. State-file validation & friendly errors
-New; "the user never has to master Nix" must include *error messages*.
-A hand-edited theme-state.json (trailing comma, wrong type, unknown
-theme slug) today surfaces as a raw Nix eval stack. Add (a) `nomarchy-
-theme-sync validate` + validate-before-write on every set/apply; (b) an
-eval-time schema assertion in `theme.nix` whose message says the field,
-the problem, and the fix in plain language. **Verify:** V1 + a corpus of
-broken-state fixtures round-tripped through validate; V2 if cheap.
-
 ### 12. Screen recording in the Capture submenu
 New; screenshots ship, recording doesn't — a standard workstation need.
 Extend `nomarchy-menu capture`: record region/full → `wl-screenrec`

agent/JOURNAL.md

@@ -17,6 +17,28 @@ Template:
 
 ---
 
+## 2026-07-04 — state-file validation & friendly errors (iteration #21, item 11)
+- **Task:** BACKLOG NEXT#11 — hand-edited state must fail with field +
+  problem + fix, never a Nix stack.
+- **Did:** (a) tool: validate_state() (appearance schema = hard errors;
+  settings.*/unknown keys = warnings), `validate` subcommand,
+  validate-BEFORE-write in write_state (invalid set/apply never touches
+  disk), JSON syntax errors now say line/column/fix. (b) theme.nix:
+  same schema at eval time on `parsed` (post-defaults, so sparse files
+  stay fine); throws a multi-line message naming each field, the got-
+  value, and the three fix paths. Doctor's JSON fix-text now points at
+  `validate`.
+- **Verified:** V0; V1 — new checks.theme-sync-validate GREEN: good
+  template passes, trailing comma → line/col message, bad hex/type →
+  field named, unknown key → warning only, invalid `set` refused with
+  the file byte-identical (cmp). Negative eval of a broken scratch
+  downstream through mkFlake shows the friendly throw (both fields);
+  good-path template-home still builds.
+- **Pending:** nothing — no hardware dependency.
+- **Next suggestion:** NEXT#12 (screen recording) or #13 niceties
+  slice; #12 first (it reshapes the Capture submenu the OCR LATER item
+  waits on).
+
 ## 2026-07-04 — nomarchy-doctor (iteration #20, item 10)
 - **Task:** BACKLOG NEXT#10 — one-shot read-only health check.
 - **Did:** pkgs/nomarchy-doctor (writeShellApplication → shellcheck-