Skip to content

fix: the runbook commands that do not work, and two stale docs claims - #236

Merged
ronaldlokers merged 3 commits into
mainfrom
fix/runbook-commands
Nov 6, 2026
Merged

ronaldlokers merged 3 commits into
mainfrom
fix/runbook-commands

Conversation

@ronaldlokers

@ronaldlokers ronaldlokers commented Sep 7, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • fix the Proton bootstrap PAT revocation command
  • generate replacement Git signing keys directly inside Proton Pass, without writing or printing the private key
  • correct the documented hook counts and vault selection
  • preserve the lokilabs theme reasoning in the design notes
  • add agreement checks for documented pass-cli flags and hook counts

Signing-key safety

pass-cli item create ssh-key generate creates both halves inside the vault under a temporary title. The runbook retires the old item and gives the replacement the canonical title, so the private key never reaches a local file, command argument, clipboard, or terminal scrollback.

Validation

  • mise run lint
  • mise run test (603 tests)

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
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
@ronaldlokers
ronaldlokers merged commit cb99000 into main Nov 6, 2026
7 checks passed
@ronaldlokers
ronaldlokers deleted the fix/runbook-commands branch November 6, 2026 15:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant