feat: persist backdrop preferences so styling stops needing flags

Every backdrop decision required a flag on the command line, which made the
most taste-driven knob in the tool the least reachable one. Closes the Phase 1
half of #27.

`cloche config` stores preferences in ~/.config/cloche/config.json, and both
`capture` and `polish` read them with no flags: pin a palette and scene, or
keep the picker random over a chosen subset of backdrops. `config options`
lists every palette with its gradient/space kind so a menu can be rendered
from the JSON contract rather than from help text.

`polish::style_from_seed_in_pool` takes the allow-lists. Empty lists mean
unconstrained, and the scene draw happens after every other field, so existing
`--style-seed` values keep rendering identically; a test compares composed card
pixels to hold that. Scenes are pinned at the polish layer rather than filtered
inside `Scene::generate`, which blends kinds with its own rolls and would bias
the pool instead of confining it.

`capture` gains `--palette` and `--scene` to match `polish`, on the CLI and on
the MCP tool, so a flag can override a pinned preference. Config names are
validated into warnings rather than errors: a typo in a preferences file should
not cost a screenshot.

Author: solomonneas

CHANGELOG.md

@@ -9,8 +9,26 @@ All notable changes to this project are documented here. The format follows
 ### Added
 - `cloche codex-payload --card` attaches the polished presentation image instead
   of the default raw capture frame.
+- **Persisted backdrop preferences.** `cloche config` stores styling choices in
+  `~/.config/cloche/config.json` (`$XDG_CONFIG_HOME` / `%APPDATA%` honored,
+  `CLOCHE_CONFIG` overrides), and both `cloche capture` and `cloche polish` read
+  them with no flags. Pin a palette and scene with
+  `cloche config set --mode pinned --palette orion-emission --scene jwst`, or
+  keep the picker random over a chosen subset with
+  `cloche config set --palettes carina-hubble,pleiades-reflection --scenes alma,veil`.
+  `cloche config options` lists every palette (with its gradient/space kind) and
+  scene; `cloche config show` prints the effective preferences.
+- **`cloche capture --palette` and `--scene`**, matching the flags `polish`
+  already had, plus the same two arguments on the MCP `capture` tool. Explicit
+  flags override the persisted config.
+- **`cloche schema --for config`** emits the JSON contract for the new command.
 
 ### Changed
+- A named random pool can reach the gradient palettes again. Random styling
+  still defaults to space palettes only, but a palette listed in the config pool
+  is drawn from regardless of its kind.
+- An unreadable or malformed config is reported in the result's `warnings` and
+  falls back to defaults instead of failing the capture.
 - Relicensed from Apache-2.0 to MIT. `LICENSE`, `Cargo.toml`, `CONTRIBUTING.md`,
   and the README badge now agree on MIT.
 - Capture JSON renames `outputDir` to `outDir` to match flat `--out-dir` /

README.md

@@ -147,7 +147,57 @@ cloche polish shot.png --scene cmb --style-seed 42
 Scenes: `nebula`, `jwst`, `hubble`, `galaxy`, `alma`, `ring`, `butterfly`,
 `edge-on`, `sun`, `sdo`, `cluster`, `deep-field`, `lensing`, `veil`, `remnant`,
 `cmb`. `--scene` applies only to space palettes. On a gradient palette it is a
-no-op warning. The same flag is available on the MCP `polish` tool.
+no-op warning. `--palette` and `--scene` are available on `cloche capture`,
+`cloche polish`, and the matching MCP tools.
+
+## Backdrop Preferences
+
+Pinning a look on every invocation gets old, so `cloche config` stores the
+choice once and both `capture` and `polish` read it with no flags:
+
+```bash
+cloche config options                 # every palette (with kind) and scene
+cloche config show                    # current preferences and where they live
+
+# Always use one backdrop.
+cloche config set --mode pinned --palette orion-emission --scene jwst
+
+# Or keep it random, but only across the backdrops you like.
+cloche config set --mode random --palettes carina-hubble,pleiades-reflection
+cloche config set --scenes alma,veil
+
+cloche config set --clear all         # back to defaults
+```
+
+Preferences live at `~/.config/cloche/config.json`
+(`$XDG_CONFIG_HOME`/`%APPDATA%` are honored, and `CLOCHE_CONFIG` overrides the
+path outright):
+
+```json
+{
+  "polish": {
+    "mode": "random",
+    "palette": null,
+    "scene": null,
+    "palettes": ["carina-hubble", "pleiades-reflection"],
+    "scenes": ["alma", "veil"]
+  }
+}
+```
+
+- `mode` is `random` or `pinned`. `pinned` applies `palette`/`scene`; `random`
+  leaves them on file and draws from the pools instead.
+- `palettes` and `scenes` are the random pool. Empty means no constraint: every
+  space palette, and the seed's own scene pick. Naming a gradient palette here
+  is the only way to get the gradient look back into the random rotation.
+- Precedence is flag, then config, then the built-in random pick, so a one-off
+  `--palette` always wins.
+- A missing file means defaults. A malformed one is reported in the result's
+  `warnings` and falls back to defaults rather than costing you the capture.
+
+`cloche config show` and `cloche config options` emit the same JSON contract as
+every other command (`cloche schema --for config`), so a picker UI can read the
+menu and the current selection without parsing help text.
 
 ## Command Reference
 
@@ -161,11 +211,17 @@ cloche capture --target window --title Firefox --out-dir /tmp/cloche-demo --form
 cloche capture --target window --window-id 0x3400003 --out-dir /tmp/cloche-demo --format json
 cloche capture --target window --app firefox --out-dir /tmp/cloche-demo --format json
 cloche capture --target region --presentation both --clipboard --out-dir /tmp/cloche-demo --format json
+cloche capture --target active --palette orion-emission --scene jwst --out-dir /tmp/cloche-demo
 cloche polish /tmp/diff.png --format json
 cloche polish /tmp/diff.png --out /tmp/diff-card.png --palette ember-glow --scene jwst --style-seed 12345
 cloche reels render --input raw.mp4 --out demo.mp4 --cues cues.json --title "Create a project"
 cloche reels render --engine hyperframes --input raw.mp4 --out demo.mp4 --cues cues.json \
   --palette ember-glow --style-seed 12345 --fps 60 --width 1080 --height 1920 --workers 1
+cloche config show
+cloche config options
+cloche config set --mode pinned --palette orion-emission --scene jwst
+cloche config set --mode random --palettes carina-hubble,pleiades-reflection
+cloche config set --clear all
 cloche gallery --limit 10
 cloche gallery --root /tmp --html /tmp/cloche.html --title "My Shots" --open
 cloche latest
@@ -174,6 +230,7 @@ cloche open /tmp/cloche-demo
 cloche schema
 cloche schema --for polish
 cloche schema --for reel-render
+cloche schema --for config
 cloche codex-payload --thread-id THREAD_ID /tmp/cloche-demo
 cloche codex-payload --thread-id THREAD_ID --card /tmp/cloche-demo
 cloche mcp

implementation-notes.md

@@ -507,3 +507,39 @@ so old sidecars still deserialize. MCP `capture` now advertises `format`
 the flat layout; the wrapper still forces `--format json` and rejects other
 values. README Command Reference lists `schema --for reel-render` beside
 polish.
+## Persisted backdrop preferences (2026-07-25)
+
+Issue #27 Phase 1: a config the CLI and MCP paths read so backdrop choice stops
+being a per-invocation flag. Phase 2 (`cloche studio`) is deliberately not here;
+the config is the durable thing a UI would write to, so it lands first.
+
+- **JSON, not TOML.** The `[polish]` sketch in the issue implied TOML, but a
+  TOML crate is a new dependency for one small file. `serde_json` is already in
+  the tree and every other Cloche surface is JSON, so `config.json` it is. Same
+  reasoning as the `setup` agent-config work above.
+- **Pool selection lives in `polish`, not `space.rs`.** `style_from_seed_in_pool`
+  takes palette and scene allow-lists. The scene is picked at the `polish` layer
+  and pinned via the existing `style.scene` field rather than teaching
+  `Scene::generate` about pools: that function blends kinds with its own rolls
+  (a JWST roll can layer onto a galaxy), so filtering inside it would only bias
+  the result, not confine it. Pinning confines it exactly.
+- **Empty pool means unconstrained, and the scene draw happens last.**
+  `style_from_seed(seed)` is now `style_from_seed_in_pool(seed, &[], &[])`, so
+  every existing `--style-seed` had to keep rendering identically. Drawing the
+  scene after every other field keeps the rng sequence untouched when no scene
+  pool is set; `empty_pools_reproduce_the_unconstrained_style` compares composed
+  pixels, not just field values, to hold that.
+- **Config names are validated by the caller, not by `polish`.** Clap
+  pre-validates flags, but a hand-edited config can name anything.
+  `config::resolve_style` filters unknown names into `warnings` and `polish`
+  treats its allow-lists as advisory, falling back to the built-in space pool
+  rather than erroring. A typo in a preferences file should not cost a
+  screenshot.
+- **`run_polish` takes a config path.** Resolving `config::path()` inside it
+  would make every polish test depend on the developer's own preferences file.
+  The path is threaded from `polish()` so tests point at a temp file or a
+  nonexistent one.
+- **Reels are untouched.** `resolve_reel_style` has its own seed/palette pairing
+  for brand continuity with a still card, and the issue scopes the preferences
+  to `capture`/`polish`. Wiring reels to the config would silently change
+  existing reel renders.