From 8670a545331d52e2da4bb4db8d4b6c000cbe2046 Mon Sep 17 00:00:00 2001 From: Ronald Lokers Date: Mon, 7 Sep 2026 03:44:30 +0200 Subject: [PATCH 1/3] fix: the two runbook commands that do not work MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both were found by running them. Neither is exercised by anything: the recovery runbooks are the only documents here that are never executed, so they rot silently and the moment you find out is the worst possible one. docs/revocation.md:70, step one of "the bootstrap PAT leaked" — the command whose entire job is to revoke a token that reads the whole vault: $ pass-cli pat delete --personal-access-token-name foo error: unexpected argument '--personal-access-token-name' found tip: a similar argument exists: '--personal-access-token-id' delete takes the id; only renew takes a name. `pat list` is what supplies it, which is why it is already the step before. README.md, step one of rotating the signing key — `ssh-keygen -f /dev/stdout` does not stream a key to stdout. ssh-keygen treats -f as a path to create, finds /dev/stdout already there, and blocks: /dev/stdout already exists. Overwrite (y/n)? Answer y and it still exits 255 writing /dev/stdout.pub, with the error text landing in the middle of the key. Replaced with a mktemp -d under $XDG_RUNTIME_DIR, which is a tmpfs at mode 700 — so "keep it off disk", the point of the original, actually holds, and holds better than /dev/stdout would have if it had worked. check-agreement.sh grows a `runbook-flags` check so the first class cannot recur: every pass-cli flag the docs name must appear in that subcommand's own --help. Skipped when pass-cli is absent, which is CI — a local check that runs beats a CI check that cannot. That check needed mutating twice to be worth having. The first version piped grep into `while read`, so `fail` set its rc inside a subshell: it printed FAIL and exited 0. Reading the exit status rather than the output is what caught it. Now: $ sh scripts/check-agreement.sh . runbook-flags # docs reverted FAIL ./docs/revocation.md says `pass-cli pat delete --personal-access-token-name` but --personal-access-token-name is not in that subcommand's --help rc=1 Claude-Session: https://claude.ai/code/session_01AvRzDyMZ6VYoz9tPUqLYb7 --- README.md | 17 +++++++++-- docs/revocation.md | 6 +++- scripts/check-agreement.sh | 60 +++++++++++++++++++++++++++++++++++++- 3 files changed, 79 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index dba657e..1a6e697 100644 --- a/README.md +++ b/README.md @@ -265,10 +265,23 @@ the commits it already signed keep verifying while it cannot vouch for anything newer. git compares against the *commit's* timestamp, which is what makes that work. Do the steps in this order: -1. Mint the replacement, and do not write it to disk: +1. Mint the replacement, and keep it off disk: ```sh - ssh-keygen -t ed25519 -C git-signing -f /dev/stdout -N '' -q + d="$(mktemp -d -p "$XDG_RUNTIME_DIR")" + ssh-keygen -t ed25519 -C git-signing -N '' -q -f "$d/k" + cat "$d/k.pub"; cat "$d/k" # copy both into the vault item + rm -rf "$d" ``` + `$XDG_RUNTIME_DIR` is a tmpfs owned by you at mode 700, so the key lives in + RAM and goes away at logout even if the `rm` never runs. + + This used to read `-f /dev/stdout`, which does not work: `ssh-keygen` treats + `-f` as a path to create, finds `/dev/stdout` already there, and blocks on + `Overwrite (y/n)?` — a prompt nothing here mentions. Answer `y` and it still + exits 255 trying to write `/dev/stdout.pub` next to it, with the error text + landing in the middle of the key. A command in this runbook is read once, in + a hurry, months from now. + Or generate it wherever you normally would — what matters is that it lands in the vault and nowhere else. 2. Replace the **`git signing key`** item in the Dotfiles vault with it. diff --git a/docs/revocation.md b/docs/revocation.md index a398692..ff4e6df 100644 --- a/docs/revocation.md +++ b/docs/revocation.md @@ -67,8 +67,12 @@ entire vault. ```sh pass-cli login pass-cli pat list - pass-cli pat delete --personal-access-token-name + pass-cli pat delete --personal-access-token-id ``` + `delete` takes the **id**, not the name — `--personal-access-token-name` is + valid on `renew` and nowhere else, and passing it here fails with + `error: unexpected argument` instead of revoking anything. `pat list` is + what gives you the id, which is why it is the step before. 2. Mint a replacement and put it in `~/.config/pass-cli-bootstrap-pat` (0600) on each machine, plus the `bootstrap PAT` vault item. Check each machine for a `~/.config/pass-cli-bootstrap-pat.rejected` while you are there and delete diff --git a/scripts/check-agreement.sh b/scripts/check-agreement.sh index 98021c2..a54d17f 100644 --- a/scripts/check-agreement.sh +++ b/scripts/check-agreement.sh @@ -29,7 +29,7 @@ set -eu # below. It was three, and they had already drifted: the usage text listed six # checks while the dispatch knew seven. all_checks="chezmoi-pins vault-name container-markers pat-expiry graphify-pin -pat-path shellcheck-targets" +pat-path shellcheck-targets runbook-flags" is_check() { for _ic in $all_checks; do @@ -255,6 +255,63 @@ check_graphify_pin() { fi } +# --- the flags the runbooks tell you to type --------------------------------- +# The recovery runbooks are the only documents here that are never executed: +# every other path in this repo runs daily, on a timer, or in CI, while +# README's "Rotating the signing key" and docs/revocation.md are read once, in +# an emergency, months after they were written. So they rot silently, and the +# moment you find out is the worst possible one. +# +# Two had rotted by 2026-09-07. `pass-cli pat delete --personal-access-token-name` +# — step one of "the bootstrap PAT leaked", the command whose whole job is to +# revoke a token that reads the entire vault — fails with `error: unexpected +# argument`, because delete takes an id and only `renew` takes a name. And the +# key-rotation one-liner used `ssh-keygen -f /dev/stdout`, which blocks on an +# undocumented `Overwrite (y/n)?` prompt and then exits 255. +# +# This closes the first class: every `pass-cli` flag the docs name has to exist +# in that subcommand's own `--help`. Skipped when pass-cli is absent, which is +# the CI case — this is a local check, and a local check that runs is worth more +# than a CI check that cannot. +check_runbook_flags() { + command -v pass-cli >/dev/null 2>&1 || return 0 + for doc in "$root/README.md" "$root/docs/revocation.md"; do + [ -r "$doc" ] || continue + # Every `pass-cli ...` invocation carrying at least one long flag. + # + # Through a file rather than a pipe, and that is the whole reason this + # is not two lines shorter: `grep | while read` runs the loop in a + # subshell, so `fail` sets its rc there and the parent still exits 0. + # The check printed FAIL and passed. Caught by mutating the doc back to + # the broken flag and reading the exit status rather than the output. + matches="${TMPDIR:-/tmp}/check-agreement-runbook.$$" + grep -hoE 'pass-cli [a-z-]+( [a-z-]+)* --[a-z-]+([ =][^ `]*)?' \ + "$doc" >"$matches" 2>/dev/null || true + while read -r line; do + sub="" + flags="" + for tok in $line; do + case "$tok" in + pass-cli) ;; + --*) flags="$flags ${tok%%=*}" ;; + -*) ;; + *) [ -z "$flags" ] && sub="$sub $tok" ;; + esac + done + [ -n "$sub" ] || continue + # shellcheck disable=SC2086 + help="$(pass-cli $sub --help 2>&1 || true)" + for f in $flags; do + case "$help" in + *"$f"*) ;; + *) fail "$doc says \`pass-cli$sub $f\` but $f is not in that subcommand's --help" ;; + esac + done + done <"$matches" + rm -f "$matches" + done +} + # --- the cached bootstrap PAT's path ---------------------------------------- # proton-ssh-load writes it; dotfiles-secrets-check now reads it to establish a # session before calling its absence a fault. Two scripts, one path, and a @@ -383,6 +440,7 @@ for want in "$@"; do graphify-pin) check_graphify_pin ;; pat-path) check_pat_path ;; shellcheck-targets) check_shellcheck_targets ;; + runbook-flags) check_runbook_flags ;; *) echo "check-agreement: unknown check: $want" >&2 usage >&2 From 76daa9f1bd61d641c4dec4025fb0794d9a05a5bd Mon Sep 17 00:00:00 2001 From: Ronald Lokers Date: Mon, 7 Sep 2026 03:47:01 +0200 Subject: [PATCH 2/3] docs: correct two stale claims and record the theme's reasoning MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The hook counts. README's layout table said modify_settings.json installs "nine entries, seven categories". Running the modifier — it is a bash script that prints JSON, so what it emits is the only honest source — gives 11 and 8: $ printf '{}' | bash home/dot_claude/modify_settings.json | jq '...' { "categories": 8, "entries": 11 } cd11bbe added PermissionRequest, SessionEnd and two more matchers for moshi-hook and left the sentence alone. check-agreement.sh grows a `hook-counts` check so the two cannot drift again; both its branches were mutation-proved. The vault name. home/dot_claude/CLAUDE.md said secrets live in "Proton Pass (Dotfiles vault)" without qualification, which stopped being true when 0c383ca gave a work machine its own vault. This is not the restatement a previous review deliberately kept — that decision was that the global agent file has to carry the secrets story standalone, and it still does. It is that the standalone copy names the wrong vault on half the machines it describes. The theme. docs/design-notes.md had nothing about the lokilabs theme, though the reasoning was written out in full in #212's commit message: the palette is derived from the site's own design.json and its ANSI escapes rather than picked by eye, the ground is calibrated one step under the wallpaper's darkest field, three files are hand-authored because the generated ones were wrong for a violet system, and the wallpaper is q92 4:4:4 JPEG because a gradient is the worst thing to store losslessly in git. That is exactly what CLAUDE.md says belongs here rather than only in a commit. The section carries what a review measured afterwards, too: red and orange are 0.7 degrees apart in hue, and two meaning-carrying pairs sit under 4.5:1 before dim_inactive takes another 15% off one of them. Not an argument against deriving the palette — an argument that "traceable to a token" and "legible on this ground at this size" are different claims, and only the first was made. Claude-Session: https://claude.ai/code/session_01AvRzDyMZ6VYoz9tPUqLYb7 --- README.md | 2 +- docs/design-notes.md | 58 ++++++++++++++++++++++++++++++++++++++ home/dot_claude/CLAUDE.md | 2 +- scripts/check-agreement.sh | 38 ++++++++++++++++++++++++- 4 files changed, 97 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1a6e697..f67b1f5 100644 --- a/README.md +++ b/README.md @@ -316,7 +316,7 @@ Four pieces, three of them applied automatically: | Piece | Where | | --- | --- | | `moshi-hook` daemon | `.chezmoiexternals/moshi-hook.toml`, pinned and checksummed | -| Claude Code hooks | `dot_claude/modify_settings.json` — nine entries, seven categories | +| Claude Code hooks | `dot_claude/modify_settings.json` — 11 entries, 8 categories | | sshd on the tailnet | `.chezmoiscripts/run_after_21-ssh-over-tailnet.sh.tmpl` | | Pairing | by hand, once — see below | diff --git a/docs/design-notes.md b/docs/design-notes.md index f03d983..cc216a8 100644 --- a/docs/design-notes.md +++ b/docs/design-notes.md @@ -1454,6 +1454,64 @@ declared-but-disabled rather than removed, so its marketplace entry survives and re-enabling is one line. `tests/modify-settings.bats` pins both halves of that, since nothing else would notice the swap reverting. +## The lokilabs theme + +The palette is derived, not chosen. lokilabs.nl carries its own design system +in `.impeccable/design.json` — tokens and tonal ramps — and the site's ANSI code +blocks are written with truecolor escapes, so most of the terminal set already +existed somewhere authoritative. Ember Light `#f67d51` is the accent because it +is the site's own accent; the lavender and green are the exact values those +code blocks use. Only yellow and cyan are invented, and only because the system +has no token for either: both sit on axes that already exist (the Paper warm +neutral, Violet Tint 4) at the chroma the rest of the system uses, rather than +being picked to look right next to the others. + +Ground and accent are calibrated to the boot-log wallpaper the theme ships +with. Its field runs `#351a5a` to `#562c8b` and its prompt glyph is Ember Light +unmodified, so `background` sits one step under the wallpaper's darkest field. +That is what makes windows read as resting on the wallpaper rather than being +punched out of it, and it is why the ground is not simply the darkest value +available. + +Three files are hand-authored that Omarchy would otherwise generate, each +because the generated one was wrong for this palette specifically: + +- `btop.theme` — the stock template runs every gauge cyan to blue to magenta, + which in a violet system is three shades of the same colour. +- `shell.bar.toml` — the bar takes the site's Deep Violet nav band rather than + the terminal ground, so bar and desktop agree instead of the bar looking like + a docked terminal. +- the Hyprland border keys in `colors.toml` — the site never uses a flat fill + where a gradient belongs, and the generated theme has no way to express one. + +The wallpaper is JPEG at q92 with 4:4:4 chroma: 49.4 dB PSNR against the PNG +original, 243 KB against 1.1 MB. A gradient is the worst possible thing to +store losslessly in git, because no future delta will ever compress it and +every clone carries the megabyte forever. + +### What a review found afterwards + +Two things this derivation did not check, both measured on 2026-09-06: + +`red #e9622e` and `orange #f67d51` are **0.7° apart in hue**. Both trace +honestly back to the Ember ramp, which is how they got here — but they are the +two colours a diff, a test runner and `btop` use to mean different things, and +only lightness separates them. Deriving each colour correctly in isolation does +not make the set legible as a set; that is a separate question, and it was not +asked. Green sits 98° clear of both, so the failure is specific to red-versus- +orange rather than general. + +Two pairs that carry meaning also fall below 4.5:1: the bar's active colour +`#f67d51` on the bar ground `#562c8b` at **3.74**, and `muted #967bbd` on +`background #2f1950` at **4.26** — the latter being comment text in every +terminal on the machine. `looknfeel.lua` then sets `dim_inactive` with +`dim_strength = 0.15`, so an unfocused window's 4.26 becomes roughly 3.6, and +the unfocused window is the one being read out of the corner of an eye. + +Neither is an argument against deriving the palette from the site. Both are an +argument that "traceable to a token" and "legible on this ground at this size" +are different claims, and only the first one was made. + ## Zen Browser preferences `run_after_24-seed-zen-prefs.sh.tmpl` writes a fixed list of Zen preferences diff --git a/home/dot_claude/CLAUDE.md b/home/dot_claude/CLAUDE.md index 672ad3c..a8c9951 100644 --- a/home/dot_claude/CLAUDE.md +++ b/home/dot_claude/CLAUDE.md @@ -10,7 +10,7 @@ - Commit subjects use conventional-commit style: `fix: ...`, `feat: ...` — lowercase, imperative. ## Secrets -- Secrets live in Proton Pass (Dotfiles vault), fetched by `pass-cli` during `chezmoi apply`; SSH keys go straight into the ssh-agent and never hit disk. Nothing secret belongs in the dotfiles repo — no `.age` blobs, no `encrypted_` files. Never write a secret plaintext to a repo; flag if found. +- Secrets live in Proton Pass — the `Dotfiles` vault on a personal machine, `Work` on a work one — fetched by `pass-cli` during `chezmoi apply`; SSH keys go straight into the ssh-agent and never hit disk. Nothing secret belongs in the dotfiles repo — no `.age` blobs, no `encrypted_` files. Never write a secret plaintext to a repo; flag if found. ## Model routing diff --git a/scripts/check-agreement.sh b/scripts/check-agreement.sh index a54d17f..2371e64 100644 --- a/scripts/check-agreement.sh +++ b/scripts/check-agreement.sh @@ -29,7 +29,7 @@ set -eu # below. It was three, and they had already drifted: the usage text listed six # checks while the dispatch knew seven. all_checks="chezmoi-pins vault-name container-markers pat-expiry graphify-pin -pat-path shellcheck-targets runbook-flags" +pat-path shellcheck-targets runbook-flags hook-counts" is_check() { for _ic in $all_checks; do @@ -312,6 +312,41 @@ check_runbook_flags() { done } +# --- the hook counts the README quotes ------------------------------------- +# README's layout table states how many hooks dot_claude/modify_settings.json +# installs. It said "nine entries, seven categories" while the script emitted +# eleven and eight: cd11bbe added PermissionRequest, SessionEnd and two more +# matchers for moshi-hook and left the sentence alone. Nobody noticed because +# nothing reads both. +# +# Counted by running the modifier rather than by parsing it — it is a bash +# script that prints JSON, so the number it produces is the only honest source. +# Empty stdin is what chezmoi hands it on a machine with no settings.json yet. +check_hook_counts() { + command -v jq >/dev/null 2>&1 || return 0 + m="$root/home/dot_claude/modify_settings.json" + [ -r "$m" ] || return 0 + counts="$(printf '{}' | bash "$m" 2>/dev/null | + jq -r '"\(.hooks|length) \([.hooks[]|length]|add)"' 2>/dev/null || true)" + cats="${counts%% *}" + entries="${counts##* }" + if [ -z "$cats" ] || [ -z "$entries" ] || [ "$cats" = "null" ]; then + fail "could not count the hooks modify_settings.json emits" + return + fi + stated="$(grep -oE 'modify_settings\.json` — [0-9]+ entries, [0-9]+ categories' \ + "$root/README.md" 2>/dev/null || true)" + if [ -z "$stated" ]; then + fail "README no longer states the modify_settings.json hook counts" + return + fi + r_entries="$(printf '%s' "$stated" | grep -oE '[0-9]+ entries' | grep -oE '[0-9]+')" + r_cats="$(printf '%s' "$stated" | grep -oE '[0-9]+ categories' | grep -oE '[0-9]+')" + if [ "$r_entries" != "$entries" ] || [ "$r_cats" != "$cats" ]; then + fail "hook counts disagree: the script emits $entries entries in $cats categories, README says $r_entries in $r_cats" + fi +} + # --- the cached bootstrap PAT's path ---------------------------------------- # proton-ssh-load writes it; dotfiles-secrets-check now reads it to establish a # session before calling its absence a fault. Two scripts, one path, and a @@ -441,6 +476,7 @@ for want in "$@"; do pat-path) check_pat_path ;; shellcheck-targets) check_shellcheck_targets ;; runbook-flags) check_runbook_flags ;; + hook-counts) check_hook_counts ;; *) echo "check-agreement: unknown check: $want" >&2 usage >&2 From 96a66de272fc2778d8a612120035d5d25ad6d33e Mon Sep 17 00:00:00 2001 From: Ronald Lokers Date: Fri, 6 Nov 2026 16:06:07 +0100 Subject: [PATCH 3/3] fix: keep replacement signing key out of scrollback --- README.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index f67b1f5..0a77161 100644 --- a/README.md +++ b/README.md @@ -265,28 +265,37 @@ the commits it already signed keep verifying while it cannot vouch for anything newer. git compares against the *commit's* timestamp, which is what makes that work. Do the steps in this order: -1. Mint the replacement, and keep it off disk: +1. Log in with the browser flow, then generate the replacement directly inside + Proton Pass under a temporary title: ```sh - d="$(mktemp -d -p "$XDG_RUNTIME_DIR")" - ssh-keygen -t ed25519 -C git-signing -N '' -q -f "$d/k" - cat "$d/k.pub"; cat "$d/k" # copy both into the vault item - rm -rf "$d" + pass-cli login + pass-cli item create ssh-key generate \ + --vault-name Dotfiles \ + --title 'git signing key replacement' \ + --comment git-signing ``` - `$XDG_RUNTIME_DIR` is a tmpfs owned by you at mode 700, so the key lives in - RAM and goes away at logout even if the `rm` never runs. + Proton generates and stores both halves in the vault. The private key never + reaches a local file, command argument, clipboard or terminal scrollback. This used to read `-f /dev/stdout`, which does not work: `ssh-keygen` treats `-f` as a path to create, finds `/dev/stdout` already there, and blocks on `Overwrite (y/n)?` — a prompt nothing here mentions. Answer `y` and it still exits 255 trying to write `/dev/stdout.pub` next to it, with the error text landing in the middle of the key. A command in this runbook is read once, in - a hurry, months from now. - - Or generate it wherever you normally would — what matters is that it lands - in the vault and nowhere else. -2. Replace the **`git signing key`** item in the Dotfiles vault with it. + a hurry, months from now. Printing a working replacement with `cat` would be + no better: the private key would survive in terminal scrollback. +2. Retire the old item, then move the temporary title into its place: + ```sh + pass-cli item update --vault-name Dotfiles \ + --item-title 'git signing key' \ + --field "title=git signing key retired $(date -I)" + pass-cli item update --vault-name Dotfiles \ + --item-title 'git signing key replacement' \ + --field 'title=git signing key' + ``` `signing-pubkey` reads `public_key` from that item, so nothing in this repo - names the key itself. + names the key itself. If the second rename fails, rerun it before applying; + the temporary title is the only thing that changed. 3. Set `$retiredBefore` in `home/dot_config/git/allowed_signers.tmpl` to the day you are doing this, then `chezmoi apply`. Both entries should now render — check with