herdr-gentle-shell 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DESIGN.md CHANGED
@@ -989,10 +989,10 @@ report with a higher seq lands. Parity contract: `working` carries the specific
989
989
 
990
990
  The package ships one CLI switch command,
991
991
  `node bin/gentle-sidebar.js (enable|disable|status|toggle)` (§7), and one in-Pi
992
- command, `/herdr-gentle:customize`, with exactly two switches: the managed
993
- sidebar agent rows and the Moshi notification channel. The command registers
994
- before the `enabled()` pane gate, so both switches stay reachable from a plain
995
- Pi session outside a Herdr pane. It owns no state of its own and reimplements
992
+ command, `/herdr-gentle:customize`, with exactly three switches: the managed
993
+ sidebar agent rows, the Moshi notification channel and the Herdr theme sync
994
+ (§12). The command registers before the `enabled()` pane gate, so every switch
995
+ stays reachable from a plain Pi session outside a Herdr pane. It owns no state of its own and reimplements
996
996
  nothing:
997
997
 
998
998
  - `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js` —
@@ -1161,9 +1161,9 @@ exactly one mechanism writes each piece of state.
1161
1161
  panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
1162
1162
  ship. This package publishes the Herdr producer sidecar and the Moshi channel
1163
1163
  only; `bin/gentle-sidebar.js` is its one CLI and `/herdr-gentle:customize`
1164
- its one in-Pi command, carrying just the sidebar-rows and Moshi switches.
1165
- Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]` stays
1166
- removed, so no other extension renders those two switches.
1164
+ its one in-Pi command, carrying just the sidebar-rows, Moshi and theme-sync
1165
+ switches. Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
1166
+ stays removed, so no other extension renders those switches.
1167
1167
  - Rollback: disable this plugin → producer stops writing; consumer sweeps
1168
1168
  only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
1169
1169
  `↳N` behavior with zero data migration.
@@ -1251,3 +1251,95 @@ confirming each criterion has a normative section:
1251
1251
  Task closes when V1–V6 are all traceable above and the file re-read reports
1252
1252
  path + line count. Any untraceable cell → `status: partial` with the gap
1253
1253
  list, not silent.
1254
+
1255
+ ## 12. Theme sync (Pi palette → Herdr theme)
1256
+
1257
+ Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
1258
+ pinned while the sync is off (S1–S5). The switch lives with the other two in
1259
+ `/herdr-gentle:customize`; the user-facing reference is
1260
+ [docs/theme-sync.md](docs/theme-sync.md). Three modules with three owners, and
1261
+ one direction of data:
1262
+
1263
+ | Module | Package | Owns |
1264
+ |---|---|---|
1265
+ | `lib/theme-store.js` | Pi (`herdr-gentle-shell`) | The one persisted document (`gentle-theme.json`): the state-dir resolution copied verbatim from the sidecar's Moshi flag, a normalised read, and the atomic replace. |
1266
+ | `lib/theme-projection.js` | Pi | The pure translation: assignable Herdr theme names, Herdr token order, `HERDR_ROLE_SOURCES`, `projectPalette`, `paletteFingerprint`, and the `null`/`Off` spelling the panel paints. No filesystem, no host import. |
1267
+ | `herdr-plugin/lib/gentle-theme-config.js` + `bin/configure-theme.js` | Herdr plugin | Everything that touches `config.toml`: payload validation, the managed block, the refusals, the atomic write with its own `.bak`, and the optional reload. |
1268
+
1269
+ Two thin glue layers sit above them and own no state: the follower
1270
+ `extensions/herdr-theme-sync.ts` (tick, fingerprint, one spawn per change,
1271
+ notices) and the switch in `extensions/gentle-herdr-state.ts` plus
1272
+ `lib/customize-panel.js` (`applyThemeSync`, `applyThemeSelection`,
1273
+ `customize status`). Pi colours become hex strings in the follower through
1274
+ `colorToHex` from `@earendil-works/pi-tui`, which is why the follower is its own
1275
+ extension rather than a section of the state sidecar: the sidecar is loaded by
1276
+ every suite as a renamed copy with one stubbed host import, and the projection
1277
+ needs no host at all.
1278
+
1279
+ **The state file is the only persisted truth.** `gentle-theme.json` holds
1280
+ `{sync, theme, updatedAt}` and nothing else is cached, mirrored or inferred: the
1281
+ panel and the follower read the same document, so the row, the switch and the
1282
+ applied palette can never disagree. Missing is inert (`sync:false`,
1283
+ `theme:null`); a document that cannot be read or parsed is a refusal — `ok:false`,
1284
+ painted `Unknown`, follower silent — never a guess, and it is written over only
1285
+ when the user acts. The default install (sync off, no theme) therefore writes
1286
+ nothing at all (S7), while a stored pin is carried across a sync toggle so
1287
+ turning the sync off restores that choice instead of unassigning it.
1288
+
1289
+ **Tick and fingerprint.** The host publishes no theme-change event, so the
1290
+ palette is a pull-read of `ctx.ui.theme` (or `ctx.ui.getTheme(name)` for a pin):
1291
+ one immediate evaluation on `session_start` and then one every 500 ms, on an
1292
+ unreferenced timer so an idle follower never keeps Pi alive. Each evaluation
1293
+ computes two identities — the requested `[sync, chosen]` and the palette
1294
+ fingerprint (`[theme name, sorted token/hex pairs]`) — and acts only when one
1295
+ differs from the last one it recorded, so a theme recoloured in place (same
1296
+ name, new colours) is noticed without a restart, and the same palette is never
1297
+ applied twice. The observation is recorded **before** the spawn, so a failed or
1298
+ refused apply is never retried on the next tick and never blocks the next real
1299
+ change either. One apply is in flight at a time, each spawn is capped at 60 s,
1300
+ and the apply is exactly
1301
+ `<plugin>/bin/configure-theme.js --apply --json --reload` with the projection on
1302
+ stdin. Nothing on shutdown writes, removes or reloads: Herdr keeps the last
1303
+ applied palette (S5). There is deliberately no Herdr pane gate — the config is
1304
+ the user's own and outlives any pane — and no automatic repair of a config the
1305
+ user also edits.
1306
+
1307
+ **Managed block and refusal policy.** The writer owns a second marker-delimited
1308
+ block (`# BEGIN herdr-gentle-theme (managed; do not edit)` …
1309
+ `# END herdr-gentle-theme`) holding `[theme] name = "one-dark"` and a
1310
+ `[theme.custom]` table, in a fixed token order with lower-cased hex, so the same
1311
+ palette is always the same bytes, `current` is a no-op answer, and a refusal can
1312
+ never be mistaken for a change. It reuses `bin/configure.js`'s
1313
+ `herdrConfigPath`/`readConfig`/`writeAtomic`/`removeBlock`/`appendBlock`/
1314
+ `reloadConfig` primitives rather than copying them, so both blocks fail, back up
1315
+ and reload identically — but shares no marker bytes and no backup file, because
1316
+ two writers that share markers each treat the other's block as their own and the
1317
+ last one erases the first. Validation happens before disk: an unknown theme
1318
+ name, an unknown token or a non-`#rrggbb` value is a refusal, not a file Herdr
1319
+ would reject or silently ignore. A `[theme]` or `[theme.custom]` table outside
1320
+ the markers is user config: refuse, never adopt, merge or overwrite. Malformed
1321
+ markers (lone begin, lone end, end before begin, a second pair) refuse instead
1322
+ of guessing where the block ends. `--remove` on an absent block is `absent` and
1323
+ exits 0 even when a foreign table exists, because uninstall must not touch user
1324
+ config. Every refusal guarantees no write, no reload and unchanged config bytes;
1325
+ exit 1 means a stale `--check` or a reload that failed after a successful write.
1326
+
1327
+ **Limits** (the §10 style, none of them a promise this design makes):
1328
+
1329
+ - The 500 ms tick is the whole observation granularity — there is no event to
1330
+ subscribe to, so a theme change is noticed within one tick and not sooner.
1331
+ - The automated evidence is a stubbed Pi host plus a real CLI stand-in on disk;
1332
+ **no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
1333
+ `getAllThemes`, `select` and `notify` are used as documented, and a host
1334
+ missing one degrades to "nothing changed" rather than to a guess.
1335
+ - Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
1336
+ `selection_bg`, `surface*`) and `peach` are never written: Pi names
1337
+ foregrounds and accents, not panel backgrounds, so backgrounds and status
1338
+ colours stay with the Herdr base theme.
1339
+ - One machine: another Herdr client reads its own `config.toml`, so this is a
1340
+ local sync and not a fleet setting.
1341
+ - Plugin-root resolution goes through `herdr plugin list --json` and fails
1342
+ closed on zero or ambiguous matches; that refusal is reported once per session
1343
+ and retried silently afterwards.
1344
+ - The CLI requires Node 18 or newer; an older runtime exits 1 before reading
1345
+ anything.
package/README.md CHANGED
@@ -484,10 +484,11 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
484
484
  managed Herdr rows and records the owned native-extension exclusion;
485
485
  `disable` removes only our owned rows and exclusion, never a user table.
486
486
  See [docs/sidebar-control.md](docs/sidebar-control.md).
487
- - In-Pi switches (`/herdr-gentle:customize`): two switches, both local
488
- state and both reachable from a plain Pi session outside a Herdr pane. With
487
+ - In-Pi switches (`/herdr-gentle:customize`): three switches, all local
488
+ state and all reachable from a plain Pi session outside a Herdr pane. With
489
489
  no argument the command opens the floating panel in Gentle Shell's own
490
- layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`)
490
+ layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
491
+ `Herdr Theme`)
491
492
  and one right pane headed `<Category> · n/m` with its setting rows, each row
492
493
  painting the stored value with `●` and the other with `○`; one line above the
493
494
  footer describes the focused setting (`<setting> — <what it changes>`), and
@@ -499,11 +500,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
499
500
  it is a key the panel answers to, and a narrow card compacts it instead of
500
501
  wrapping. Pointer input still works without being advertised — a click on a
501
502
  category selects it, a click on a row applies it, and a click outside the
502
- panes is ignored. Each category owns exactly one switch: `Herdr Sidebar`
503
+ panes is ignored. Each category owns its own rows: `Herdr Sidebar`
503
504
  shows the single `Sidebar agent rows` row, and the only Moshi switch is the
504
- `Notifications` row under `Moshi notifications`. The two are never mixed —
505
- `Sidebar agent rows` neither reads nor writes `gentle-moshi.json`, so turning
506
- the agent rows off never turns the notification channel off. Herdr's own
505
+ `Notifications` row under `Moshi notifications`, while `Herdr Theme` owns
506
+ both theme rows (the `Theme sync` toggle and the non-toggle
507
+ `Gentle Shell theme` value row described in the subsection below). The
508
+ sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
509
+ reads nor writes `gentle-moshi.json`, so turning the agent rows off never
510
+ turns the notification channel off. Herdr's own
507
511
  done/ask attention (the finished and needs-attention pop-ups and their
508
512
  sound) is Herdr's native behavior, configured in Herdr itself — its config
509
513
  and its settings — and this package deliberately offers no switch for it:
@@ -518,7 +522,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
518
522
  `settings.json`, running the `moshi-hook` pairing gate before enabling (a
519
523
  refusal writes nothing) and reloading Pi only when that settings entry
520
524
  actually changed. `/herdr-gentle:customize status` prints one read-only line
521
- (`customize status: sidebar=<on|off|unknown> moshi=<on|off>`); an unknown
525
+ (`customize status: sidebar=<on|off|unknown> moshi=<on|off>
526
+ theme-sync=<on|off|unknown> theme=<name|none|unknown>`); an unknown
522
527
  argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
523
528
  `unknown` is never a refusal: the panel says the state is unknown and
524
529
  choosing `On` still runs the apply step, reporting that step's own error
@@ -588,6 +593,22 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
588
593
  reached through `/herdr-gentle:customize`. See
589
594
  [docs/herdr-session-open.md](docs/herdr-session-open.md).
590
595
 
596
+ ### Theme sync (Herdr palette follows Pi)
597
+
598
+ `/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned value.
599
+ `Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
600
+ palette of the theme Pi is showing, and it follows a theme change while Pi keeps
601
+ running. While it is off, `Gentle Shell theme` assigns one Gentle Shell / Pi
602
+ theme by name and the picker's `Off (no theme assigned)` entry clears the pin; the row is refused while the sync is on
603
+ (`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
604
+ nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
605
+ whose sync is off and whose theme is unassigned writes nothing at all. State is
606
+ one file, `gentle-theme.json`, beside `gentle-moshi.json`; the palette reaches
607
+ Herdr through the plugin's own `bin/configure-theme.js`, which owns a marked
608
+ `[theme]` block and refuses to touch a `[theme]` table you maintain yourself.
609
+ See [docs/theme-sync.md](docs/theme-sync.md) for the projection, the CLI and
610
+ the limits.
611
+
591
612
  ## Documentation
592
613
 
593
614
  | Your task | Start here |
@@ -598,6 +619,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
598
619
  | Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
599
620
  | Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
600
621
  | Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
622
+ | Theme sync (Pi palette → Herdr theme) | [docs/theme-sync.md](docs/theme-sync.md) |
601
623
  | Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
602
624
  | Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
603
625
 
@@ -0,0 +1,284 @@
1
+ # Theme sync (Herdr palette follows the active Pi theme)
2
+
3
+ Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
4
+ pinned while the sync is off. This page covers the switch, the one state file,
5
+ the managed `[theme]` block, the writer CLI and the limits. Protocol context is
6
+ in [DESIGN.md](../DESIGN.md) §12; the switch is described beside the sidebar and
7
+ Moshi switches in [README.md](../README.md).
8
+
9
+ ## The switch
10
+
11
+ `/herdr-gentle:customize` → `Herdr Theme` holds two rows. The row's note and
12
+ the extension's refusal carry the same words, so the panel and the apply path
13
+ cannot tell you different things.
14
+
15
+ - `Theme sync` is a pill toggle and is **OFF by default**. `On` makes Herdr's
16
+ palette the palette of the theme Pi is showing, and it follows a change of
17
+ the active theme while Pi keeps running. Turning the sync off stops following and leaves
18
+ Herdr with the palette it already has: nothing is removed from Herdr's
19
+ config, so the last applied palette survives Pi closing.
20
+ - `Gentle Shell theme` is the card's only non-toggle row (`Select…`): it opens
21
+ the host's theme list plus the unassign entry `Off (no theme assigned)`, which shifts
22
+ by a numeric suffix if a theme literally carries that spelling. It is painted dim, denied the selection
23
+ band and refused while the sync is on, with
24
+ `Turn Theme sync off to pick a specific theme.` Picking `Off` clears the pin
25
+ (`theme: null`); picking a name stores it. The stored pin is carried across a
26
+ sync toggle untouched, so turning the sync off restores that choice instead of
27
+ unassigning it.
28
+ - Esc, a cancelled menu, an unknown argument and a host without
29
+ `getAllThemes()` all write nothing. The plain two-step menu stays as the
30
+ fallback when the TUI helpers or `ctx.ui.custom` are unavailable, and offers
31
+ the same two rows.
32
+
33
+ The notices are fixed strings:
34
+
35
+ | Action | Notice |
36
+ | --- | --- |
37
+ | Sync turned on | `Theme sync on; Herdr's palette follows the theme active in Pi.` |
38
+ | Sync turned off | `Theme sync off; Herdr keeps the palette it was last given.` |
39
+ | Toggle already in that state | `Theme sync already on/off; nothing was changed.` |
40
+ | Theme row while the sync is on | `Turn Theme sync off to pick a specific theme.` |
41
+ | Theme assigned | `Gentle Shell theme set to <name>.` |
42
+ | Pin cleared | `Gentle Shell theme set to Off; Herdr keeps the palette it was last given.` (the stored value and the row read `Off`; only the picker entry is spelled `Off (no theme assigned)`) |
43
+ | Host exposes no theme list | `Could not read Pi's theme list (this host exposes no getAllThemes()); nothing was changed.` |
44
+ | Theme store missing | `Could not reach the theme store (lib/theme-store.js is unavailable); nothing was changed.` |
45
+ | State file not writable | `Could not write the theme store: <detail>; nothing was changed.` |
46
+
47
+ `/herdr-gentle:customize status` prints one read-only line and writes nothing:
48
+
49
+ ```text
50
+ customize status: sidebar=<on|off|unknown> moshi=<on|off> theme-sync=<on|off|unknown> theme=<name|none|unknown>
51
+ ```
52
+
53
+ ## State file
54
+
55
+ One document is the only persisted truth: `gentle-theme.json`.
56
+
57
+ ```json
58
+ {
59
+ "sync": true,
60
+ "theme": null,
61
+ "updatedAt": "2026-09-19T10:00:00.000Z"
62
+ }
63
+ ```
64
+
65
+ It lives in the directory `gentle-moshi.json` already uses: `GENTLE_STATUS_STATE_DIR`
66
+ when set, else `$XDG_STATE_HOME/herdr/plugins/herdr-gentle-agents` (else
67
+ `~/.local/state/herdr/plugins/herdr-gentle-agents`), unless the stored
68
+ directory holds no file of ours and the newer `herdr-gentle-shell` directory
69
+ does — then that one is used. `sync` is the switch, `theme` is the pinned name
70
+ or `null`, and `updatedAt` is stamped by the writer — a caller cannot record a
71
+ timestamp it made up. Writes are atomic (temporary file in the same directory,
72
+ then rename), preserve an existing file's mode and create a new one as `0600`.
73
+
74
+ - **Missing file** is an inert document (`sync: false`, `theme: null`): a fresh
75
+ install writes nothing, so nothing is what it reads.
76
+ - **Unreadable or unparsable file** is a refusal, never a guess: the sync row
77
+ reads `Unknown`, no theme name is shown, and the follower does nothing. It is
78
+ written over only when you act — toggling the sync writes a fresh document,
79
+ and the pinned-theme row is refused only by a *stored* `sync: true`.
80
+ - **`sync: false` with `theme: null`** is the default install: the follower
81
+ spawns nothing, writes nothing and removes nothing (S7).
82
+ - A blank or non-string `theme` normalises to `null`; nothing is trimmed into a
83
+ theme name that no install has.
84
+
85
+ ## What gets written
86
+
87
+ The writer owns one marker-delimited block in Herdr's config
88
+ (`$HERDR_CONFIG_PATH`, else `<XDG_CONFIG_HOME>/herdr/config.toml`, else
89
+ `~/.config/herdr/config.toml`; `%APPDATA%\herdr\config.toml` on Windows):
90
+
91
+ ```toml
92
+ # BEGIN herdr-gentle-theme (managed; do not edit)
93
+ [theme]
94
+ name = "one-dark"
95
+
96
+ [theme.custom]
97
+ accent = "#89b4fa"
98
+ text = "#cdd6f4"
99
+ red = "#f38ba8"
100
+ green = "#a6e3a1"
101
+ subtext0 = "#7c7f93"
102
+ overlay0 = "#7c7f93"
103
+ overlay1 = "#9399b2"
104
+ mauve = "#cba6f7"
105
+ yellow = "#f9e2af"
106
+ blue = "#89b4fa"
107
+ teal = "#94e2d5"
108
+ # END herdr-gentle-theme
109
+ ```
110
+
111
+ The hex values above are illustrative; the token set, their order and the base
112
+ theme name are not. Tokens are emitted in Herdr's own order (`accent`, `text`,
113
+ `red`, `green`, `subtext0`, `overlay0`, `overlay1`, `mauve`, `yellow`, `blue`,
114
+ `teal`) and lower-cased, so the same palette always renders the same bytes and a
115
+ re-apply of the same palette is a no-op (`current`, no write, no reload). A
116
+ `[theme.custom]` table is omitted entirely when no token survives conversion:
117
+ an empty table would still be an override.
118
+
119
+ The projection is exactly `HERDR_ROLE_SOURCES` in `lib/theme-projection.js`:
120
+
121
+ | Herdr token | Pi theme token |
122
+ | --- | --- |
123
+ | `accent` | `accent` |
124
+ | `text` | `text` |
125
+ | `red` | `error` |
126
+ | `green` | `success` |
127
+ | `yellow` | `warning` |
128
+ | `blue` | `mdLink` |
129
+ | `teal` | `syntaxType` |
130
+ | `subtext0` | `muted` |
131
+ | `overlay0` | `muted` |
132
+ | `overlay1` | `thinkingText` |
133
+ | `mauve` | `borderAccent` |
134
+
135
+ `muted` paints two Herdr surfaces on purpose: they are converted once and always
136
+ emitted together, never half-applied. Herdr's surface tokens — `sidebar_bg`,
137
+ `panel_bg`, `active_row_bg`, `selection_bg`, `surface0`, `surface1`,
138
+ `surface_dim` — and `peach` are **never written**: backgrounds and status
139
+ colours stay with the Herdr base theme (`one-dark`) because a Pi theme names
140
+ foregrounds and accents, not panel surfaces, and a guessed background would
141
+ paint a colour nobody chose. A Pi token that is empty (Pi's "terminal default",
142
+ which has no hex spelling) or that does not convert to `#rrggbb` is dropped for
143
+ that apply; the rest of the palette still lands.
144
+
145
+ The block is a *second* managed block, distinct from the sidebar override's
146
+ `herdr-gentle-agents` block, with its own backup file
147
+ `<config>.herdr-gentle-theme.bak`. The two writers share no marker bytes and no
148
+ backup, so each can only ever rewrite its own block.
149
+
150
+ ## The writer CLI
151
+
152
+ ```bash
153
+ node herdr-plugin/bin/configure-theme.js [--apply | --remove | --check] [--reload] [--json]
154
+ ```
155
+
156
+ `--apply` is the default verb. It reads a payload on stdin
157
+ (`{"theme":{"name":"<herdr-theme>","custom":{"<token>":"#rrggbb"}}}`); the Pi
158
+ follower sends exactly that, and a terminal stdin (no pipe) reads as "no
159
+ payload". Accepted names are `catppuccin`, `terminal`, `tokyo-night`, `dracula`,
160
+ `nord`, `gruvbox`, `one-dark`, `solarized`, `kanagawa`, `rose-pine`, `vesper`;
161
+ accepted tokens are the nineteen in
162
+ `herdr-plugin/lib/gentle-theme-config.js` `CUSTOM_TOKENS`.
163
+
164
+ | Verb | Meaning |
165
+ | --- | --- |
166
+ | `--apply` | Validate the payload and write (or repair) the managed block. |
167
+ | `--remove` | Remove the managed block; absent means nothing to do, and a foreign table is left alone. |
168
+ | `--check` | Read-only: `0` when the block is present and current, or absent, `1` when it is stale, `2` when refused. Never writes. Without a payload it round-trips the block on its own; a block that does not match the rendered form is `stale`. |
169
+ | `--reload` | Run `herdr server reload-config` — only after a write. |
170
+ | `--json` | One JSON line on stdout (`op`, `status`, `file`, `theme`, `changed`, plus `reloaded` under `--reload` and `error` on a refusal) instead of a sentence. |
171
+
172
+ Exit codes: `0` applied/current/removed/absent (and `--check` current or
173
+ absent), `1` `--check` found a stale block **or** a requested reload failed
174
+ after a successful write, `2` refused or bad argv. A payload or config refusal
175
+ prints exactly one `configure-theme: …` line on stderr, in every output mode
176
+ (an argv error adds the usage block), and it **guarantees no write, no reload
177
+ and config bytes unchanged**. Node 18 or newer is required; older runtimes exit
178
+ `1` before reading anything.
179
+
180
+ ## Refusals
181
+
182
+ Every one of these exits `2` with the config untouched:
183
+
184
+ - **A `[theme]` or `[theme.custom]` table outside the markers** is user config:
185
+ `refusing --apply: a [theme] or [theme.custom] table already exists outside
186
+ the managed markers. This tool only manages its marked block; move or delete
187
+ that table, then re-run.` It is never adopted, merged or overwritten. A bare
188
+ `theme = …` key inside another table is a different key path and is not
189
+ matched.
190
+ - **Malformed markers** — a lone begin, a lone end, end before begin, or a
191
+ second pair — refuse instead of guessing where the block ends:
192
+ `refusing --<verb>: managed theme markers are malformed (unterminated); fix
193
+ them manually.`
194
+ - **An unknown theme name**, an unknown custom token, a non-`#rrggbb` value, an
195
+ extra top-level key or an unknown `theme` key:
196
+ `refusing malformed payload: …`, naming the exact problem.
197
+ - **No payload** for `--apply`, or invalid JSON on stdin.
198
+ - **An unreadable or unwritable config**: `cannot read <file>: …`, or
199
+ `write failed, original untouched: …`.
200
+ - **Argv**: an unknown flag, or more than one verb
201
+ (`choose exactly one of --apply, --remove, --check`).
202
+
203
+ `--remove` on a config with no managed block is `absent` and exits `0` even when
204
+ a foreign `[theme]` table exists: there is nothing of ours to take away, and an
205
+ uninstall must not touch user config.
206
+
207
+ ## Failure modes and notices
208
+
209
+ The Pi follower (`extensions/herdr-theme-sync.ts`) applies the palette; it never
210
+ reports success, only failures:
211
+
212
+ - **Plugin root unresolvable** — no `herdr plugin list --json` match, an
213
+ ambiguous or non-absolute root, or no `bin/configure.js` there — notifies
214
+ once per session: `Could not apply the palette to Herdr: <reason> The palette
215
+ Herdr has was left untouched.` and retries on later ticks silently.
216
+ - **Assigned theme not installed** — `ctx.ui.getTheme(name)` returns nothing —
217
+ notifies once per session: `The Pi theme "<name>" is not installed, so Herdr's
218
+ palette was left unchanged; pick an installed theme in /herdr-gentle:customize.`
219
+ A later install of that exact theme is picked up without a restart.
220
+ - **CLI failure** — non-zero exit, a spawn failure or a start error — notifies
221
+ `Could not apply the palette to Herdr: configure-theme exited <status>[: <last
222
+ stderr line>]` (or `<script> could not start (<detail>)`), once per distinct
223
+ message. A success clears the memo, so the same refusal after a good apply is
224
+ reported again. The last stderr line is capped at 300 characters.
225
+ - **A failed apply is never retried automatically.** The observation is recorded
226
+ *before* the spawn, so the next tick acts only on a new palette (or a new
227
+ failure text). One apply is in flight at a time, and a spawn is capped at 60 s.
228
+ - **A theme whose colours cannot be read at all** skips the tick instead of
229
+ stripping Herdr's custom block: an unreadable palette is not evidence that you
230
+ have no palette.
231
+
232
+ ## Environment
233
+
234
+ - `HERDR_CONFIG_PATH` — the config file the writer edits and reports.
235
+ - `XDG_CONFIG_HOME` — default config directory (`<xdg>/herdr/config.toml`) when
236
+ `HERDR_CONFIG_PATH` is unset.
237
+ - `HERDR_BIN_PATH` — Herdr binary (default `herdr`) for `plugin list --json`
238
+ (plugin-root lookup) and `server reload-config` (the optional reload).
239
+ - `GENTLE_HERDR_PLUGIN_ROOT` — skip the `plugin list` lookup and name the
240
+ installed plugin root directly (isolated runs).
241
+ - `GENTLE_STATUS_STATE_DIR` — state directory override for `gentle-theme.json`
242
+ and every other file this package writes there.
243
+ - `GENTLE_THEME_SYNC_LIB_DIR` — the directory the follower requires
244
+ `theme-store.js` and `theme-projection.js` from (defaults to this package's
245
+ `lib/`).
246
+ - `GENTLE_CUSTOMIZE_LIB_DIR` — the directory the state sidecar loads the panel
247
+ and the theme store from, so the switch and the follower read the same files.
248
+
249
+ ## Limits
250
+
251
+ - **The observation tick is 500 ms**, because the host publishes no
252
+ theme-change event: the palette is a pull-read of `ctx.ui.theme`, evaluated
253
+ once immediately on session start and then every 500 ms. A change is noticed
254
+ within one tick, and a theme recoloured in place (same name, new colours) is
255
+ caught by the palette fingerprint, not only by its name. The timer is
256
+ unreferenced, so an idle follower never keeps Pi alive.
257
+ - **Not proven against a live Pi TUI.** The automated evidence is a stubbed Pi
258
+ host plus a real CLI stand-in on disk; no live-TUI run is recorded.
259
+ `ctx.ui.theme`, `getTheme()`, `getAllThemes()`, `select()` and `notify()` are
260
+ used as the host documents them, and a host that lacks one degrades to
261
+ "nothing changed" rather than a guess.
262
+ - **Herdr keeps the last applied palette** when Pi closes: nothing on shutdown
263
+ writes, removes or reloads. Backgrounds and status colours stay with the Herdr
264
+ base theme, so the sync recolours a sidebar's text and accent surfaces, not
265
+ the whole app chrome.
266
+ - **One machine.** A Herdr client on another host reads its own `config.toml`;
267
+ the sync is local to the machine where Pi runs. There is no pane gate either:
268
+ a Pi session started outside a Herdr pane still updates the config.
269
+ - **No automatic repair.** A `[theme]` table you also maintain by hand outside
270
+ the markers is never reconciled — the writer refuses until you move or delete
271
+ it. Managed markers you edit by hand become "malformed" and stop the writer
272
+ until they are fixed.
273
+
274
+ ## Implementation
275
+
276
+ | File | Role |
277
+ | --- | --- |
278
+ | `lib/theme-store.js` | The state document: directory resolution, normalized read, atomic write. |
279
+ | `lib/theme-projection.js` | The pure projection: theme names, token order, `HERDR_ROLE_SOURCES`, `projectPalette`, `paletteFingerprint`, the `Off` label. |
280
+ | `extensions/herdr-theme-sync.ts` | The follower: tick, fingerprint, one `configure-theme.js --apply --json --reload` per change, once-per-failure notices. |
281
+ | `extensions/gentle-herdr-state.ts` | The switch: `applyThemeSync`, `applyThemeSelection`, `customize status`. |
282
+ | `lib/customize-panel.js` | The `Herdr Theme` category and its two rows. |
283
+ | `herdr-plugin/lib/gentle-theme-config.js` | Payload validation, the managed block, refusals, backup and reload. |
284
+ | `herdr-plugin/bin/configure-theme.js` | The CLI verbs, exit codes and output modes. |