ssh install tells a missing .ssh from one it cannot enter (closes #10 )

The first sftp connection now lists ~/.ssh before it fetches authorized_keys. The file reads as empty in just two cases: sftp reports ~/.ssh itself as not there, or the listing succeeds and the fetch then reports the file as not there. A directory that is there but cannot be entered, or a file that cannot be read, fails the run and writes nothing, so a ~/.ssh whose mode shuts the user out is no longer read as a host with no file and replaced by one holding the new key alone. The write connection makes ~/.ssh and sets 0700 only when the read found none; an existing directory keeps its mode. Model: opus-4-8
2026-09-21 07:38:26 +00:00
38 changed files with 255 additions and 1242 deletions
@@ -1,65 +1,3 @@
-# .dockerignore does NOT use .gitignore semantics. Docker matches with
+.git
 # moby/patternmatcher: filepath.Match plus `**`, so `*` does not cross
 # `/` and an unprefixed pattern is anchored at the context root. Every
 # depth-independent pattern therefore needs `**/`, or `config/.env` and
 # `certs/server.key` still ship while this file reads as solved. Only
 # genuinely root-anchored entries go unprefixed. Never transplant these
 # into .gitignore, where `**/` is wrong.
 #
 # Matching is case-sensitive, so secrets use character ranges rather
 # than an ALL-CAPS twin, which would still miss `Server.Key`.
 #
 # Extend with this repo's own host-built artifacts, written anchored:
 # `/myapp`, never `**/myapp`, which also matches `cmd/myapp/` and
 # deletes the package directory from the context.
 # .git is sent without its config. Without a VERSION build argument the
 # stage that compiles runs `git describe --tags --always` on .git, which
 # does not need .git/config; that file can hold a credential, such as a
 # password in a remote URL or the token the CI checkout step stores there.
 .git/config
 # Agent scratch: one full checkout of the repo per in-flight agent.
 # Anchored because it occurs once where agents run at the repo root.
 # KNOWN GAP: a repo running agents in subdirectories still ships
 # `services/api/.claude/` and must add its own anchored entry.
 .claude
 # Environment files. `*.env` covers bare `.env` and the `prod.env`
 # convention. Re-include a committed template with a negation if the
 # build needs one: `!docs/example.env`.
 **/*.[eE][nN][vV]
 **/.[eE][nN][vV].*
 **/.[eE][nN][vV][rR][cC]
 # Private keys and the bundles carrying them. Public certificates
 # (*.crt, *.cer) are deliberately absent: they are legitimate inputs.
 **/*.[pP][eE][mM]
 **/*.[kK][eE][yY]
 **/*.[pP]12
 **/*.[pP][fF][xX]
 **/[iI][dD]_[rR][sS][aA]
 **/[iI][dD]_[dD][sS][aA]
 **/[iI][dD]_[eE][cC][dD][sS][aA]
 **/[iI][dD]_[eE][dD]25519
 # Dependencies: restored inside the image, never copied in.
 **/node_modules
 # OS metadata.
 **/.DS_Store
 **/Thumbs.db
 # Editor state: never a build input, and it churns COPY.
 **/*.swp
 **/*.swo
 **/*~
 **/*.bak
 **/.idea
 **/.vscode
 **/*.sublime-*
 # The binary `make build` writes, and the CI workflow, which is not a
 # build input.
 /keyfunc
 .gitea
 /keyfunc
@@ -1,3 +1,6 @@
 # The built binary
 /keyfunc
 # OS
 .DS_Store
 Thumbs.db
@@ -11,38 +14,8 @@ Thumbs.db
 .vscode/
 *.sublime-*
-# Agent scratch (worktrees of this repo, created and destroyed by
+# Environment / secrets
-# in-flight tooling). Unanchored: .gitignore patterns already match at
+.env
-# every depth, so no prefix is wanted here. This is not a .dockerignore
+.env.*
-# entry and must not be given a `**/` prefix on the way into one.
+*.pem
-.claude/
+*.key
 # Node
 node_modules/
 # Secrets. Unanchored like every entry above, so each matches at every
 # depth. Matching is case-sensitive on Linux, so names use character
 # ranges rather than a lowercase form that misses `Server.Key`.
 # Environment files. `*.env` covers bare `.env` and the `prod.env`
 # convention. Only the templates `example.env` and `sample.env` are
 # re-included below. A repository that commits any other template adds
 # its own negation after these lines, for example `!.env.example`.
 *.[eE][nN][vV]
 .[eE][nN][vV].*
 .[eE][nN][vV][rR][cC]
 !example.env
 !sample.env
 # Private keys and the bundles carrying them.
 *.[pP][eE][mM]
 *.[kK][eE][yY]
 *.[pP]12
 *.[pP][fF][xX]
 [iI][dD]_[rR][sS][aA]
 [iI][dD]_[dD][sS][aA]
 [iI][dD]_[eE][cC][dD][sS][aA]
 [iI][dD]_[eE][dD]25519
 # The binary `make build` writes.
 /keyfunc
@@ -10,20 +10,14 @@ run:
 linters:
  default: all
  enable:
    # Successor to the deprecated gomodguard. Named explicitly, rather than
    # left to `default: all`, because it carries the module policy below.
    - gomodguard_v2
  disable:
    # Genuinely incompatible with project patterns
    - exhaustruct      # Requires all struct fields
    - depguard         # Dependency allow/block lists
    - godot            # Requires comments to end with periods
    - wsl              # Deprecated, replaced by wsl_v5
    - wrapcheck        # Too verbose for internal packages
    - varnamelen       # Short names like db, id are idiomatic Go
    # Deprecated: the warning is attached to the old name, so it is
    # silenced by disabling that name, not by enabling the successor.
    - wsl              # Deprecated, replaced by wsl_v5
    - gomodguard       # Deprecated, replaced by gomodguard_v2
  settings:
    lll:
      line-length: 88
@@ -34,64 +28,6 @@ linters:
      max-complexity: 15
    dupl:
      threshold: 100
    depguard:
      # Test-support code must not be compiled into the shipped binary. A
      # test-support package exists to hand a test privileges the program
      # itself must never have, so a file that is not a test must not import
      # one. Test files, and the files inside a package whose directory name
      # ends in `test`, are where that code belongs, and are exempt.
      #
      # The deny list below is the one part of this file a repository is
      # expected to extend, and the only part it may. depguard matches an
      # import path against a list of prefixes, so it cannot be told "any path
      # whose last segment ends in test"; a repository's own test-support
      # packages have to be named here one at a time, by full import path,
      # under a module path that differs from repository to repository. Add
      # them; change nothing else.
      rules:
        test-support:
          list-mode: lax
          files:
            - "$all"
            - "!$test"
            - "!**/*test/**"
          deny:
            - pkg: net/http/httptest
              desc: >-
                Test-support code belongs in test files and in packages whose
                directory name ends in test, not in the shipped binary.
    # Only decisions already recorded in the Go package defaults are
    # listed here. Every entry matches the module path exactly.
    gomodguard_v2:
      blocked:
        - module: github.com/rs/zerolog
          recommendations:
            - log/slog
          reason: "Structured logging is stdlib log/slog."
        # One entry per pre-fork module path, because the later releases
        # are separate paths. A prefix match would be shorter but would
        # also reach github.com/go-redis/redismock, the test double for
        # the successor these entries recommend.
        - module: github.com/go-redis/redis
          recommendations:
            - github.com/redis/go-redis/v9
          reason: "Pre-fork module; use the maintained go-redis v9."
        - module: github.com/go-redis/redis/v7
          recommendations:
            - github.com/redis/go-redis/v9
          reason: "Pre-fork module; use the maintained go-redis v9."
        - module: github.com/go-redis/redis/v8
          recommendations:
            - github.com/redis/go-redis/v9
          reason: "Pre-fork module; use the maintained go-redis v9."
        - module: github.com/sergi/go-diff
          recommendations:
            - github.com/aymanbagabas/go-udiff
          reason: "No unified diff output; use go-udiff."
        - module: github.com/hexops/gotextdiff
          recommendations:
            - github.com/aymanbagabas/go-udiff
          reason: "Unmaintained fork; use go-udiff."
 issues:
  max-issues-per-linter: 0
@@ -1,4 +0,0 @@
 {
    "tabWidth": 4,
    "proseWrap": "always"
 }
@@ -1,48 +1,10 @@
-# The lint phase, the test phase and the build. script/lint and
+# The formatting check, the tests and the build. Linting is not here:
-# script/test each build one phase alone; a plain `docker build .` builds
+# it runs in its own pinned image, see Dockerfile.lint and script/lint,
-# both, because the build stage copies a file from each. Formatting is
+# which script/cibuild runs before this file.
 # checked on the host by script/fmt-check, not here.
 # Lint phase
 # golangci/golangci-lint:v2.12.2, 2026-09-07
 FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 RUN golangci-lint run --config .golangci.yml ./...
 # Test phase
 # golang:1.26-alpine, 2026-09-07
 FROM golang@sha256:ce864e7223ac17b1775e6fd0b4c0db580c2eb50e7953a427916379e4b92a1628 AS test
 # -race needs cgo, and cgo needs a C toolchain.
 RUN apk add --no-cache gcc musl-dev
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 RUN go test -timeout 90s -race -cover ./... || \
    { echo "--- Rerunning with -v for details ---"; \
      go test -timeout 90s -race -v ./...; exit 1; }
 # Build stage. Nothing is wanted from either phase above; the copies
 # are what make BuildKit build them first, so this stage cannot run
 # unless lint and test passed.
 # golang:1.26-alpine, 2026-09-07
 FROM golang@sha256:ce864e7223ac17b1775e6fd0b4c0db580c2eb50e7953a427916379e4b92a1628 AS builder
 COPY --from=lint /src/go.sum /dev/null
 COPY --from=test /src/go.sum /dev/null
 RUN apk add --no-cache make git
 WORKDIR /src
@@ -52,18 +14,9 @@ RUN go mod download
 COPY . .
-# The version stamped into the binary: the VERSION build argument when one
+RUN make fmt-check
-# is given, otherwise `git describe --tags --always` of the .git in the
+RUN make test
-# build context. A context that carries .git and still yields no version
+RUN make build
 # fails the build; with neither, as from a source tarball, it is "dev".
 ARG VERSION
 RUN version="${VERSION:-$(git describe --tags --always || echo dev)}"; \
    if [ -e .git ] && { [ -z "$version" ] || [ "$version" = dev ] || \
        [ "$version" = unknown ]; }; then \
        echo "no version could be derived although the build context carries .git" >&2; \
        exit 1; \
    fi; \
    make build VERSION="$version"
 # alpine:3.23, 2026-09-07
 FROM alpine@sha256:fd791d74b68913cbb027c6546007b3f0d3bc45125f797758156952bc2d6daf40
@@ -0,0 +1,15 @@
 # The linter, pinned by hash, with this repository linted inside it.
 # Building this file is how linting happens; see script/lint. Nothing
 # lints on the host, so the answer is the same everywhere.
 # golangci/golangci-lint:v2.12.2, 2026-09-07
 FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 RUN golangci-lint run --timeout 5m
@@ -1,21 +0,0 @@
 MIT License
 Copyright (c) 2026 sneak
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
@@ -3,7 +3,7 @@
 # which needs the version stamped into the binary.
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
-LDFLAGS := -s -w -X 'sneak.berlin/go/keyfunc/internal/cli.Version=$(VERSION)'
+LDFLAGS := -s -w -X 'git.eeqj.de/sneak/keyfunc/internal/cli.Version=$(VERSION)'
 .PHONY: default bootstrap setup build test lint fmt fmt-check check \
 	docker cibuild hooks clean
@@ -1,79 +1,16 @@
 # keyfunc
-`keyfunc` is an MIT-licensed Go command-line tool by
+`keyfunc` turns a BIP-39 mnemonic into key pairs that can be recreated from
-[@sneak](https://sneak.berlin) that turns a BIP-39 mnemonic into SSH keys, age
+that mnemonic at any time. The same mnemonic, key type and index always give the
-identities and child mnemonics, each of which can be recreated from that
+same key.
 mnemonic at any time. The same mnemonic, key type and index always give the same
 key.
 It uses the BIP-85 entropy deriver from `git.eeqj.de/sneak/secret/pkg/bip85` and
 takes the same steps as that repository's `agehd` package.
-Commands are grouped by what is derived: `keyfunc ssh ...` for ed25519 SSH keys,
+Commands are grouped by what is derived: `keyfunc ssh ...` for ed25519 SSH
-`keyfunc age ...` for age identities and for encrypting and decrypting with
+keys, `keyfunc age ...` for age identities and for encrypting and decrypting
-them, and `keyfunc mnemonic ...` for child mnemonics derived from the main one.
+with them, and `keyfunc mnemonic ...` for child mnemonics derived from the
-
+main one.
 ## Getting Started
 Install with Go:
 ```
 go install sneak.berlin/go/keyfunc/cmd/keyfunc@latest
 ```
 Or build from a clone and run the binary:
 ```
 git clone git@git.eeqj.de:sneak/keyfunc.git
 cd keyfunc
 make build
 ./keyfunc --version
 ```
 `make build` produces `./keyfunc`. Every deriving command needs a mnemonic; see
 [Giving it the mnemonic](#giving-it-the-mnemonic) for where it is read from,
 then for example:
 ```
 ./keyfunc ssh pub -n 0 --mnemonic-command 'secret get foo'
 ```
 ## Rationale
 A key you can derive again never has to be backed up. One mnemonic, kept safe
 once, stands behind every key this tool produces: lose a laptop and the SSH key,
 the age identity and any child mnemonic on it come back from the mnemonic alone,
 at the same index, byte for byte. Nothing else has to be written down, copied
 between machines, or stored in a secret manager, because it can always be
 derived again.
 ## Design
 The entry point is a thin `cmd/keyfunc/main.go` (what `make build` builds) that
 calls into `internal/`. The packages there are:
 - `internal/derive` turns a mnemonic into the 32 bytes a key is made from: it
  walks BIP-39 seed, BIP-32 master key and BIP-85 entropy, and holds the shared
  constants (the byte count and the largest key index).
 - `internal/mnemonic` finds the mnemonic to work from — a command, an
  environment variable, or a terminal prompt — and refuses one that fails the
  BIP-39 checksum.
 - `internal/sshkey` turns the derived bytes into an ed25519 SSH key
  (`sshkey.go`) and serves that key from an in-process SSH agent on a private
  unix socket, keeping it out of any file (`agent.go`).
 - `internal/agekey` turns the derived bytes into an age identity and encrypts
  and decrypts with it.
 - `internal/childmnemonic` derives a child mnemonic from the main one using
  BIP-85's own mnemonic application.
 - `internal/cli` builds the cobra command tree and runs it. Under it,
  `cli/options` holds the flags every command shares, and `cli/ssh`, `cli/age`
  and `cli/mnemonic` are the command groups.
 ### Adding a key type
 Adding a key type is one package under `internal/` that turns the 32 derived
 bytes into that type's key, plus one cobra subcommand under `internal/cli/` that
 groups its commands.
 ## Derivation
@@ -105,12 +42,11 @@ The mnemonic itself is never a command-line argument. It is looked for in this
 order; the first one found wins:
 1. `--mnemonic-command <command>`: a shell command, run with `sh -c`, whose
-   standard output is the mnemonic. Example:
+   standard output is the mnemonic. Example: `--mnemonic-command 'secret get
-   `--mnemonic-command 'secret get foo'`. Whitespace around the output is
+   foo'`. Whitespace around the output is dropped. If the command exits with a
-   dropped. If the command exits with a non-zero status, the tool prints its
+   non-zero status, the tool prints its standard error and exits with status 1.
-   standard error and exits with status 1.
+2. Environment variable `KEYFUNC_MNEMONIC_COMMAND`: the same, as a shell
-2. Environment variable `KEYFUNC_MNEMONIC_COMMAND`: the same, as a shell command
+   command held in the environment.
   held in the environment.
 3. Environment variable `KEYFUNC_MNEMONIC`: the mnemonic itself.
 4. A prompt on the terminal with echo turned off.
@@ -118,18 +54,14 @@ If none of these is available and standard input is not a terminal, the tool
 refuses and exits with status 1. A mnemonic that fails the BIP-39 checksum is
 refused with a message saying so.
 `KEYFUNC_MNEMONIC` and `KEYFUNC_MNEMONIC_COMMAND` are removed from the
 environment before the system `ssh` (`keyfunc ssh to`) and `sftp`
 (`keyfunc ssh install`) are started, so the mnemonic is never handed on to them.
 Every command takes `--index` / `-n` and `--mnemonic-command`, and has `--help`.
-`keyfunc --version` prints the version. `make build` stamps it; a binary
+`keyfunc --version` prints the version set at build time.
 installed with `go install` reports the module version instead.
 ## SSH keys: `keyfunc ssh`
-Only ed25519 keys are produced. The application number is `838372`, so the path
+Only ed25519 keys are produced. The application number is `838372`, so the
-is `m/83696968'/838372'/<n>'`. The 32 bytes from step 4 are the ed25519 seed.
+path is `m/83696968'/838372'/<n>'`. The 32 bytes from step 4 are the ed25519
 seed.
 Test vector, mnemonic
 `abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about`:
@@ -159,24 +91,24 @@ same as for `pub`.
 ### `keyfunc ssh install <[user@]host> [-- sftp options...]`
 Adds the `pub` line to `~/.ssh/authorized_keys` on the host. No command is run
-on the host: the file is fetched, changed here, and written back with the system
+on the host: the file is fetched, changed here, and written back with the
-`sftp` client in batch mode.
+system `sftp` client in batch mode.
-The first connection lists `~/.ssh` and then fetches `~/.ssh/authorized_keys`
+The first connection lists `~/.ssh` and then fetches
-from it. The file reads as empty in two cases only: `sftp` reported `~/.ssh`
+`~/.ssh/authorized_keys` from it. The file reads as empty in two cases only:
-itself as not being there, or the listing came up and the file was not in it.
+`sftp` reported `~/.ssh` itself as not being there, or the listing came up and
-Any other outcome of that connection fails the run — a `~/.ssh` that is there
+the file was not in it. Any other outcome of that connection fails the run — a
-but cannot be entered, an `authorized_keys` that is there but cannot be read, or
+`~/.ssh` that is there but cannot be entered, an `authorized_keys` that is there
-a connection that did not come up — and the tool prints what `sftp` said and
+but cannot be read, or a connection that did not come up — and the tool prints
-exits with status 1 without writing anything, rather than put a file back
+what `sftp` said and exits with status 1 without writing anything, rather than
-holding the new key alone. The listing is what tells a missing directory from
+put a file back holding the new key alone. The listing is what tells a missing
-one shut to the user, which `sftp` reports on a fetch the same way; the wording
+directory from one shut to the user, which `sftp` reports on a fetch the same
-of a missing file elsewhere does not count either, since `ssh` writes
+way; the wording of a missing file elsewhere does not count either, since `ssh`
-`No such file or directory` about an `-i` it cannot find on a session that then
+writes `No such file or directory` about an `-i` it cannot find on a session
-authenticates through the agent. If an identical line is already in the file,
+that then authenticates through the agent. If an identical line is already in
-the tool prints `already present` and connects no further. Otherwise the line is
+the file, the tool prints `already present` and connects no further. Otherwise
-added (after a newline, if the file did not end with one) and a second
+the line is added (after a newline, if the file did not end with one) and a
-connection:
+second connection:
 - makes `~/.ssh` and sets it to mode `0700`, but only when the first connection
  found none; a `~/.ssh` that was already there keeps the mode it had;
@@ -187,14 +119,15 @@ connection:
 The tool then prints `added`. So a run that adds a line connects twice. The
 rename is the step that either happens or does not: the file on the host is
 never half-written. `sftp` does it in one step against servers that offer
-OpenSSH's POSIX rename extension, as OpenSSH's own server does; a server without
+OpenSSH's POSIX rename extension, as OpenSSH's own server does; a server
-it may refuse to rename onto a file that is already there.
+without it may refuse to rename onto a file that is already there.
 If a step fails, the tool prints what `sftp` said, removes nothing, and exits
-with status 1. It names the uploaded file only when the step that failed was the
+with status 1. It names the uploaded file only when the step that failed was
-upload or one after it, which is where a file of that name can be on the host; a
+the upload or one after it, which is where a file of that name can be on the
-failure before the upload names none. Everything `sftp` writes goes to standard
+host; a failure before the upload names none. Everything `sftp`
-error, so the tool's own standard output is only `added` or `already present`.
+writes goes to standard error, so the tool's own standard output is only
 `added` or `already present`.
 Anything after `--` is passed to `sftp` unchanged, which is where the port goes
 (`-P 2222`, not `-p`). How the connection authenticates is up to the user's
@@ -207,26 +140,15 @@ Derives the key, serves it from an SSH agent that runs inside the tool on a unix
 socket in a new private `0700` temporary directory, then runs the system `ssh`
 with `-o IdentityAgent=<that socket>` followed by the host and all remaining
 arguments unchanged. The tool exits with `ssh`'s exit status and removes the
-socket and directory on the way out. The private key is never written to disk. A
+socket and directory on the way out. The private key is never written to disk.
 SIGINT, SIGTERM or SIGHUP ends `ssh` and still removes the socket and directory,
 and the tool then exits with status 1 unless `ssh` reported one of its own.
 ## age identities: `keyfunc age`
 The application number is `657169`, path `m/83696968'/657169'/<n>'`. The 32
-bytes from step 4 are clamped as X25519 requires and become an age identity, the
+bytes from step 4 are clamped as X25519 requires and become an age identity,
-same steps `sneak/secret` takes in its `agehd` package. `secret` derives at a
+the same steps `sneak/secret` takes in its `agehd` package. `secret` derives at
-vendor-specific path today; for its keys to equal this tool's it moves to this
+a vendor-specific path today; for its keys to equal this tool's it moves to
-path, which is a change in `secret`, not here.
+this path, which is a change in `secret`, not here.
 Test vectors, mnemonic
 `abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about`:
 ```
 recipient index 0: age1xwdy9y6ckyfsgjc8k02e9uhsf3fmjy0ufysewlj68kmx5n67e3nsg2mftq
 recipient index 1: age1pmm92sxaf5mazjwvjph7dx2zq9r5p8l3rarfgqm7hmakqhvgyy4q5p3w7j
 identity index 0: AGE-SECRET-KEY-19QKK2P38598XLXMQFFU3P7J9PLDD7527T70JDHGDJ7AMNF3XT44S00JFU5
 ```
 ### `keyfunc age pub`
@@ -254,75 +176,39 @@ says so and exits with status 1.
 ### `keyfunc mnemonic [-n N] [--words 12|18|24]`
 Prints a child mnemonic derived from the main one, using BIP-85's own mnemonic
-application (number `39`, English, path `m/83696968'/39'/0'/<words>'/<n>'`,
+application (number `39`, English, path
-entropy taken as the specification says, not through step 4). Default 12 words.
+`m/83696968'/39'/0'/<words>'/<n>'`, entropy taken as the specification says,
-A child mnemonic is a full mnemonic in its own right: it can seed another
+not through step 4). Default 12 words. A child mnemonic is a full mnemonic in
-`keyfunc`, another wallet, or `secret`, and it never has to be written down,
+its own right: it can seed another `keyfunc`, another wallet, or `secret`, and
-since it can be derived again.
+it never has to be written down, since it can be derived again.
-Test vector: the child-mnemonic step is checked against BIP-85's own published
+## Adding a key type
 vectors, which derive from the specification's master key
 `xprv9s21ZrQH143K2LBWUUQRFXhucrQqBpKdRRxNVq2zBqsx8HVqFk2uYo8kmbaLLHRdqtQpUm98uKfu3vca1LqdGhUtyoFnCNkfmXRyPXLjbKb`.
 At key index 0 the 12-word English child mnemonic is:
-```
+Adding a key type is one package under `internal/` that turns the 32 derived
-girl mad pet galaxy egg matter matrix prison refuse sense ordinary nose
+bytes into that type's key, plus one cobra subcommand under `internal/cli/` that
-```
+groups its commands.
 ## Errors
-Errors go to standard error and the exit status is 1, except for `ssh to`, which
+Errors go to standard error and the exit status is 1, except for `ssh to`,
-passes through `ssh`'s own exit status.
+which passes through `ssh`'s own exit status.
-## Entrypoints
+## Building and running
-The repo adheres to the
+```
-[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+make build    # produces ./keyfunc
-standard: most Makefile targets are thin shims over an executable in `script/`
+make check    # fmt-check, lint (golangci-lint) and tests
-(`build` and `clean` are the exceptions).
+```
- `script/bootstrap` installs everything needed to build and develop (git, make,
+Examples:
  Go, node and yarn), idempotently, from nix, apt, brew or apk, with node at a
  pinned version through nvm when it is not already installed; it then installs
  the pinned prettier with yarn. It does not install the linter, which only runs
  inside Docker.
 - `script/setup` prepares a fresh clone: it runs `bootstrap`, then installs the
  git pre-commit hook.
 - `script/projectname` prints the project name; other scripts call it so they
  stay identical across repos.
 - `script/test` builds the `test` phase of the `Dockerfile` alone, uncached: the
  test suite runs with the race detector inside the build, rerunning verbosely
  if a test fails.
 - `script/lint` builds the `lint` phase of the `Dockerfile` alone, uncached: the
  linter, pinned by hash, runs inside the build, so a complaint fails it and
  leaves no container behind.
 - `script/fmt` formats in place: the Go source with `go fmt`, then every
  Markdown file with prettier (four-space indents, prose wrapped at 80 columns).
 - `script/fmt-check` checks the same files the same way without writing, failing
  if anything is unformatted. Both need the node and yarn that `bootstrap`
  installs.
 - `script/check` runs `test`, `lint` and `fmt-check` and changes no files.
 - `script/docker` builds the Docker image, uncached, tagged with the project
  name and stamped with the version `git describe` gives on the host. The image
  cannot be built unless the `lint` and `test` phases pass, so a plain
  `docker build .` runs them too.
 - `script/cibuild` is the CI build the Gitea workflow calls: it runs
  `bootstrap`, then `check`, then builds the image as `script/docker` does.
 - `script/precommit` is what the git pre-commit hook runs: `go mod tidy` and
  `go fmt`, failing if `go.mod` or `go.sum` changed, then `check`.
 - `script/install-precommit` installs the git pre-commit hook that runs
  `script/precommit`.
-## TODO
+```
-
+keyfunc ssh pub -n 3 --mnemonic-command 'secret get foo'
-The open issues that stand between the tree and a 1.0 release:
+keyfunc ssh priv -n 3 > ~/.ssh/id_bip85_3
-
+keyfunc ssh install -n 3 user@example.com
- [#42 go-bip39 no longer exists upstream: keep it, or copy it into the repo?](https://git.eeqj.de/sneak/keyfunc/issues/42)
+keyfunc ssh to -n 3 user@example.com uptime
-
+keyfunc age pub -n 0
-## License
+keyfunc age encrypt -n 0 --armor -o notes.age notes.txt
-
+keyfunc age decrypt -n 0 notes.age
-MIT. The full text is in [`LICENSE`](LICENSE).
+keyfunc mnemonic -n 1 --words 24
-
+```
 ## Author
 [@sneak](https://sneak.berlin).
@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-10-02
+last_modified: 2026-08-19
 ---
 This document covers repository structure, tooling, and workflow standards. Code
@@ -60,28 +60,17 @@ style conventions are in separate documents:
  prerequisite since nvm requires bash. yarn is then pinned via
  `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
  always exact versions. `script/cibuild` runs the CI build: it changes to the
-  repo root, runs `script/bootstrap`, runs `script/check`, and builds the image
+  repo root and runs `docker build .`; the Gitea workflow calls it. Four further
-  with the version; the Gitea workflow calls it. **`script/cibuild` runs
+  scripts are our own extensions to the standard: `script/check` runs
-  `script/bootstrap` first**, because the workflow checks out the repo and runs
+  `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
-  nothing else, while `script/fmt-check` runs the formatter on the host: on a
+  what the git pre-commit hook runs, and it calls `script/check`;
-  pristine checkout with nothing installed the run dies there, after the
+  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
-  containerised gates have passed. **The bootstrap alone is not enough**:
+  target shims to it); and `script/projectname` (literally that filename) simply
-  `script/bootstrap` installs node and yarn under nvm and leaves neither on the
+  outputs the project's name. Scripts that need the name call
-  `PATH` of the shell that called it, so a bare `yarn` still exits 127. The host
+  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
-  entrypoints that need yarn — `script/fmt` and `script/fmt-check` — therefore
+  so those scripts stay byte-identical across all repos. Repo-type-specific
-  source nvm for the pinned node version before invoking it, exactly as
+  pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
-  `script/bootstrap`'s own install step does. A runner carrying nothing but
+  `script/precommit`, not in the hook itself. Model scripts are at
  docker and git then gets through `script/check`. Four further scripts are our
  own extensions to the standard: `script/check` runs `script/test`,
  `script/lint` and `script/fmt-check`; `script/precommit` is what the git
  pre-commit hook runs, and it calls `script/check`; `script/install-precommit`
  installs the git pre-commit hook (the `make hooks` target shims to it); and
  `script/projectname` (literally that filename) simply outputs the project's
  name. Scripts that need the name call `script/projectname` — e.g.
  `script/docker` assembles its image tag from it — so those scripts stay
  byte-identical across all repos. Repo-type-specific pre-commit extras (e.g.
  `go mod tidy` verification in Go repos) belong in `script/precommit`, not in
  the hook itself. Model scripts are at
  `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
  must document the provided scripts in an **Entrypoints** section (see the
  README requirements below).
@@ -100,164 +89,87 @@ style conventions are in separate documents:
  contributor should be able to understand the entire development workflow by
  reading the Makefile.
- Every repo should have a `Dockerfile`, and it carries the repo's gates: a
+- Every repo should have a `Dockerfile`. All Dockerfiles must run `make check`
-  `lint` phase and a `test` phase, with the final stage depending on both so the
+  as a build step so the build fails if the branch is not green. For non-server
-  image cannot be built unless they pass. For non-server repos the final stage
+  repos, the Dockerfile should bring up a development environment and run
-  brings up a development environment; for server repos it is the runtime image.
+  `make check`. For server repos, `make check` should run as an early build
-  Dockerfiles install development prerequisites by running `script/bootstrap`
+  stage before the final image is assembled. Dockerfiles install development
-  rather than duplicating installs inline; COPY `script/` and the dependency
+  prerequisites by running `script/bootstrap` rather than duplicating installs
-  manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before
+  inline; COPY `script/` and the dependency manifests (`package.json` +
-  running it.
+  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
  layer stays cached until dependencies change.
- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
+- **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
-  no separate lint file. `script/lint` and `script/test` each build one phase
+  repos use a multistage build where linting runs in an independent stage based
-  and nothing else:
+  on the `golangci/golangci-lint` image (pinned by hash). This stage runs
  `make fmt-check` and `make lint` before the full build begins. The build stage
  then declares an explicit dependency on the lint stage via
  `COPY --from=lint /src/go.sum /dev/null`, which forces BuildKit to complete
  linting before proceeding to compilation and tests. This ensures lint failures
  surface in seconds rather than minutes, without blocking on dependency
  download or compilation in the build stage.
-    ```sh
+    The standard pattern for a Go repo Dockerfile is:
    docker build --no-cache --target lint -t "$(script/projectname)-lint" .
    docker build --no-cache --target test -t "$(script/projectname)-test" .
    ```
    **A stage that is not the last one in the file is built only when the final
    stage's chain depends on it, or when `--target` names it.** That is why the
    two gates are always invoked by name here, and why the final stage carries a
    `COPY --from=` of a harmless file from each of them: without that edge a
    plain `docker build .` builds the last stage alone and exits 0 having linted
    and tested nothing.
    **Every `docker build` in `script/` is tagged**, here and in
    `script/cibuild` and `script/docker`. An untagged build leaves a dangling
    image behind on every invocation, on every developer host and every CI
    runner; a tagged one replaces the previous image.
    Inside a phase the tool is invoked directly — `golangci-lint`, `go test`,
    `eslint`, `prettier` — never through `make lint` or `script/test`, which are
    themselves a `docker build` and would recurse into a daemon that does not
    exist in a build step. Formatting is the exception and stays on the host:
    `script/fmt` writes the working tree, and `script/fmt-check` is its
    read-only twin.
    **No lint verdict may come from a host invocation of the linter.** On a
    shared host golangci-lint reads a result cache keyed on file content rather
    than location, so a second checkout of the same content is served the first
    one's findings, and a host-global lock in `$TMPDIR` makes concurrent runs
    exit non-zero with `parallel golangci-lint is running` — a status a caller
    cannot tell from real findings. Both have produced wrong verdicts in this
    org, in both directions. A container has its own cache, its own `TMPDIR` and
    a digest-pinned binary, so neither is reachable.
 - **Any build that runs checks is built with `--no-cache`.** Docker invalidates
  a `COPY` layer only when the copied content changes, so on an unchanged tree
  the check `RUN` is served from cache, nothing executes, and the build still
  exits 0. Every `docker build` in `script/` therefore passes `--no-cache`:
  `script/lint`, `script/test`, `script/cibuild` and `script/docker` are the
  four, and there is no fifth — `script/check` runs the two gate phases and
  `script/fmt-check`, and builds no image of its own. A bare `docker build .` is
  not evidence that anything ran: a sub-second build reporting success is a
  cache hit, not a result. Never invalidate by pruning — `docker builder prune`
  and friends destroy a build cache shared with every other build on the host.
 - **The gate phases are separate stages, and the build stage depends on both.**
  The lint phase is based on the `golangci/golangci-lint` image (pinned by
  hash), so lint failures surface in seconds rather than after a full compile,
  and the test phase is based on the Go image. The canonical Go repo
  `Dockerfile`:
    ```dockerfile
-    # Lint phase
+    # Lint stage — fast feedback on formatting and lint issues
    # golangci/golangci-lint:v2.x.x, YYYY-MM-DD
    FROM golangci/golangci-lint@sha256:... AS lint
    WORKDIR /src
    COPY go.mod go.sum ./
    RUN go mod download
    COPY . .
-    RUN golangci-lint run --config .golangci.yml ./...
+    RUN make fmt-check
    RUN make lint
-    # Test phase
+    # Build stage
    # golang:1.x-alpine, YYYY-MM-DD
    FROM golang@sha256:... AS test
    WORKDIR /src
    COPY go.mod go.sum ./
    RUN go mod download
    COPY . .
    RUN go test -timeout 90s -race -cover ./... || \
        { echo "--- Rerunning with -v for details ---"; \
          go test -timeout 90s -race -v ./...; exit 1; }
    # Build stage. Nothing is wanted from either phase above; the copies
    # are what make BuildKit build them first, so this stage cannot run
    # unless lint and test passed.
    # golang:1.x-alpine, YYYY-MM-DD
    FROM golang@sha256:... AS builder
    COPY --from=lint /src/go.sum /dev/null
    COPY --from=test /src/go.sum /dev/null
    RUN apk add --no-cache git
    WORKDIR /src
    # Force BuildKit to run the lint stage before proceeding
    COPY --from=lint /src/go.sum /dev/null
    COPY go.mod go.sum ./
    RUN go mod download
    COPY . .
    RUN make test
-    # The VERSION build arg when one is given, otherwise
+    ARG VERSION=dev
-    # `git describe --tags --always` on the .git in the build context. With
+    RUN CGO_ENABLED=0 go build -trimpath \
    # .git present, a version that is still empty, dev or unknown fails the
    # build: git is missing or could not read the checkout.
    ARG VERSION
    RUN VERSION="${VERSION:-$(git describe --tags --always)}"; \
        if [ -e .git ]; then \
            case "$VERSION" in ""|dev|unknown) \
                echo "version is '$VERSION' although .git is present" >&2; \
                exit 1 ;; \
            esac; \
        fi; \
        CGO_ENABLED=0 go build -trimpath \
        -ldflags="-s -w -X main.Version=${VERSION}" \
        -o /app ./cmd/app/
-    # Runtime stage, and the last one
+    # Runtime stage
    FROM alpine@sha256:...
    COPY --from=builder /app /usr/local/bin/app
    ENTRYPOINT ["app"]
    ```
    Key points:
-    - The lint phase uses the `golangci/golangci-lint` image directly (it has
+    - The lint stage uses the `golangci/golangci-lint` image directly (it
-      both Go and the linter), so nothing needs installing.
+      includes both Go and the linter), so there is no need to install the
-    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
+      linter separately.
-      purpose is the ordering edge. BuildKit runs stages in parallel by default,
+    - `COPY --from=lint /src/go.sum /dev/null` is a no-op file copy that creates
-      and a stage nothing depends on is not built at all, so without these two
+      a stage dependency. BuildKit runs stages in parallel by default; without
-      lines a red gate would not fail the build.
+      this line, the build stage would not wait for lint to finish and a lint
-    - Keep the runtime stage last, and if you add a stage after it, give it the
+      failure might not fail the overall build.
      same two copies. A plain `docker build .` builds the last stage's chain
      and nothing else.
    - If the project uses `//go:embed` directives that reference build artifacts
-      (e.g. a web frontend compiled in a separate stage), the lint phase must
+      (e.g. a web frontend compiled in a separate stage), the lint stage must
      create placeholder files so the embed directives resolve. Example:
      `RUN mkdir -p web/dist && touch web/dist/index.html web/dist/style.css`.
      The lint stage should not depend on the actual build output — it exists to
      fail fast.
    - If the project requires CGO or system libraries for linting (e.g.
-      `vips-dev`), install them in the lint phase with `apk add`.
+      `vips-dev`), install them in the lint stage with `apk add`.
-    - `.dockerignore` lets `.git` into the build context. It keeps out
+    - The build stage runs `make test` after compilation setup. Tests run in the
-      `.git/config`, which `git describe` does not need and which can hold a
+      build stage, not the lint stage, because they may require compiled
-      credential: a password in a remote URL, or the token the CI checkout step
+      artifacts or heavier dependencies.
      stores there. The stage that compiles has `git` (the Debian Go image has
      it; an alpine one needs `apk add --no-cache git`) and takes the version
      from the `VERSION` build argument when one is given, otherwise from
      `git describe --tags --always`. That gives the tag on a tagged commit; on
      a later commit, the tag, the number of commits since it and the short
      commit (`v1.2.3-4-gabc1234`); and the short commit when no tag is
      reachable. `ARG VERSION` has no default, and the build fails if the
      context carries `.git` and the version still comes out empty, `dev` or
      `unknown`. A plain `docker build .` with no build arguments must succeed;
      a Dockerfile that refuses an empty build argument drops that refusal and
      keeps the argument.
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` on push, and checks out the repo as its only other step.
+  runs `script/cibuild` (which runs `docker build .`) on push. Since the
-  That script bootstraps, runs the gate phases, and then builds the image, so a
+  Dockerfile already runs `make check`, a successful build implies all checks
-  successful run means every check passed; a bare `docker build .` does not
+  pass.
  carry the same guarantee, because its gate phases may come from the cache. The
  image build is uncached and so runs the gate phases a second time. That is the
  price of the rule above, and it is worth paying: the image that ships is built
  from a run of its own gates rather than from a cache entry.
 - Use platform-standard formatters: `black` for Python, `prettier` for
  JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with
@@ -281,17 +193,15 @@ style conventions are in separate documents:
  suite that exceeds it fails. Under 20 seconds is the target. A suite between
  20 and 60 seconds is still green, but the overage must be filed as an
  improvement bug against that repo. Add a 90-second timeout to the test
-  invocation (`go test -timeout 90s`). The backstop deliberately sits above the
+  invocation in the Makefile (`go test -timeout 90s`). The backstop deliberately
-  hard cap so that it catches a genuinely hung test rather than a merely slow
+  sits above the hard cap so that it catches a genuinely hung test rather than a
-  one.
+  merely slow one.
- **The test command should use the conditional verbose rerun pattern.** Run
+- **`make test` should use the conditional verbose rerun pattern.** Run tests
-  tests without `-v` (verbose) first. If tests fail, automatically rerun with
+  without `-v` (verbose) first. If tests fail, automatically rerun with `-v` to
-  `-v` to show full output. This keeps CI logs and `docker build` output clean
+  show full output. This keeps CI logs and `docker build` output clean on
-  on success (just package/suite summaries) while providing full diagnostic
+  success (just package/suite summaries) while providing full diagnostic detail
-  detail on failure (every test case, every assertion). The command lives in the
+  on failure (every test case, every assertion). The general shell pattern:
  `test` phase of the `Dockerfile`, since `script/test` builds that phase; the
  Makefile form below is the same pattern for any repo-local invocation:
    ```makefile
    test:
@@ -304,24 +214,11 @@ style conventions are in separate documents:
    ```makefile
    test:
-    	@go test -count=1 -timeout 90s -race -cover ./... || \
+    	@go test -timeout 90s -race -cover ./... || \
    		{ echo "--- Rerunning with -v for details ---"; \
-    		  go test -count=1 -timeout 90s -race -v ./...; exit 1; }
+    		  go test -timeout 90s -race -v ./...; exit 1; }
    ```
    `-count=1` is required on both invocations: it defeats Go's test _result_
    cache, so the target cannot report a pass it did not earn, and the rerun
    reproduces a failure instead of replaying it. It leaves the build cache
    alone, so it costs the runtime of the suite and no recompilation.
    Note that this is a second, independent cache, stacked below the Docker
    layer cache that [issue #26](https://git.eeqj.de/sneak/prompts/issues/26)
    addresses. `CHECK_EPOCH` guarantees the `RUN make test` _step_ re-executes;
    it does not guarantee `go test` inside that step does any work, because the
    `GOCACHE` baked into earlier image layers survives into the re-executed
    step. They are two separate defects requiring two separate fixes, and a fix
    for one must not be recorded as covering the other.
    Python example:
    ```makefile
@@ -347,84 +244,10 @@ style conventions are in separate documents:
  must be in `.gitignore`. No exceptions.
 - `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`),
-  editor files (`.swp`, `*~`), in-repo agent scratch directories (`.claude/`),
+  editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`.
-  language build artifacts, and `node_modules/`. Fetch the standard `.gitignore`
+  Fetch the standard `.gitignore` from
-  from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when
+  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up
-  setting up a new repo. These patterns are written to `.gitignore`'s own
+  a new repo.
  semantics, in which an unanchored pattern already matches at every depth; they
  are not a `.dockerignore` and must not be transplanted into one unmodified.
 - **`.dockerignore` does not use `.gitignore` semantics, and copying patterns
  across unmodified leaves secrets in the build context.** Docker matches with
  `moby/patternmatcher`: `filepath.Match` semantics plus a `**` extension, so
  `*` does not cross `/` and a pattern without a leading `**/` is anchored at
  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
  therefore excludes only the copies at the repository root, while `config/.env`
  and `certs/server.key` still reach the context and can land in an image layer
  — which is more dangerous than a short file with no secret patterns at all,
  because it reads as solved and stops anyone looking. Give every
  depth-independent pattern the `**/` prefix and leave only genuinely
  root-anchored entries unprefixed: `.claude`, and the repo's own host-built
  binary, written `/myapp` and never `**/myapp`, which would also match
  `cmd/myapp/` and delete the package directory from the context. Matching is
  case-sensitive, and an ALL-CAPS twin per pattern still misses `Server.Key`, so
  secret names use character ranges — `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`,
  and likewise for `.envrc` and the extensionless SSH keys. Where such a pattern
  also catches something the build needs, re-include it with a negation
  (`!docs/example.env`); deleting the pattern reopens the exposure for every
  other file it covers. Fetch the standard `.dockerignore` from
  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
  it with the repo's own artifacts.
 - **In-repo agent scratch belongs in both files, written to each file's own
  semantics.** `.claude/` holds one worktree per in-flight agent — an entire
  additional checkout of the repo — so under `COPY . .` the build context
  inflates by a multiple of the repo and another session's unreviewed work can
  be copied into an image layer. In `.gitignore` the entry is `.claude/`,
  unanchored. In `.dockerignore` it is `.claude`, anchored and with **no** `**/`
  prefix, because the prefixed form would also delete any nested directory of
  that name from the build. Anchoring carries a known gap that the canonical
  `.dockerignore` states in its own comment, since consuming repos receive the
  file and not the tracker: the directory is created in the agent's working
  directory, so a repo running agents in subdirectories still ships
  `services/api/.claude/` and must add its own anchored entry there.
 - **A plain `docker build .` of a clone stamps the version that
  `git describe --tags --always` gives**, derived from the `.git` in the build
  context as the canonical `Dockerfile` above shows. Without its failure check,
  a missing `git` or an unreadable checkout would leave `-X main.Version=` empty
  and the build would still exit 0. `script/docker` and `script/cibuild` pass
  the version they compute on the host; it takes precedence. They do this
  byte-identically across repos:
    ```sh
    # Own line: a failing command substitution inside an argument does not
    # trip `set -e`, so the inline form degrades to an empty constant.
    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
    [ -n "$version" ] || version="unknown"
    docker build --no-cache \
        --build-arg VERSION="$version" \
        -t "$(script/projectname)" .
    ```
    `--always` makes an untagged repo yield an abbreviated commit hash rather
    than failing, and the `[ -n "$version" ]` line is the single place the
    fallback is applied — a live check that fires on a build from an export with
    no `.git` and on a repository with no commits yet. Do not fold it into the
    substitution as `|| echo unknown`, which makes the guard unreachable. The
    Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
    there because `ARG` is stage-scoped; passing `VERSION` to a repo whose
    Dockerfile declares no such `ARG` is ignored and costs nothing, which is why
    the scripts stay byte-identical. One consequence for CI: the standard
    checkout action clones shallow and fetches no tags, so a repo that embeds a
    tag-derived version must set `fetch-depth: 0` on its checkout step.
 - **Verify `.dockerignore` by enumerating the image, not by reading the
  patterns.** Plant files at the root _and_ at least two directories deep, build
  a probe image that does `COPY . .`, and list what actually landed
  (`docker run --rm --entrypoint find IMAGE /app`). The `transferring context`
  size is not a substitute: a nested secret is a few bytes, and BuildKit
  transfers only the delta from the previous build.
 - **No build artifacts in version control.** Code-derived data (compiled
  bundles, minified output, generated assets) must never be committed to the
@@ -446,39 +269,9 @@ style conventions are in separate documents:
  byte-identical, so that no repo can quietly loosen its own linting. Linter
  configuration changes are made to the canonical copy in the `prompts` repo and
  reach consuming repos by re-vendoring; an agent may open a PR against
-  canonical, which only the user merges. One list is exempt from byte-identity,
+  canonical, which only the user merges. The canonical golangci-lint version is
-  because it cannot be written once for every repo: the `deny` list of the
+  v2.12.2 (released 2026-05-06), installed commit-pinned via
-  `test-support` depguard rule, where a repo names its own test-support packages
+  `go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5`.
  by full import path. A repo adds entries there and changes nothing else, and a
  re-vendor carries its entries forward. The canonical golangci-lint version is
  v2.12.2 (released 2026-05-06), pinned as the digest of the lint phase's base
  image
  (`golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240`,
  which reports `2.12.2 built with go1.26.2 from c0d3ddc9`). That digest is the
  only pin, since no repo installs golangci-lint on the host: bumping the
  version means changing it and nothing else.
 - **`script/bootstrap` installs a pinned tool by comparing versions, never by
  testing presence.** An `if ! command -v <tool>; then install; fi` guard tests
  `PATH` only, so on an already-provisioned machine the pin is inert and a
  version bump is a silent no-op — while the Dockerfile, installing into a clean
  image, gets the pinned version, so a local `make check` and `make docker` can
  disagree about what the tool even is. The canonical form:
    - compares the installed version against the pin over the **whole** version
      token; a parser that stops at the first `-` reports `2.12.2` for a host
      running `2.12.2-rc1` and skips the install;
    - treats absent, non-zero, empty or unrecognised `--version` output as a
      mismatch, so the failure direction is a redundant install and never a
      skipped one;
    - after installing, re-resolves the binary the way callers do — `hash -r`,
      then through `PATH`, not through the directory the installer wrote to —
      and fails naming the resolved path, since an install that a shadowing
      binary hides succeeds while changing nothing any caller sees;
    - is actually called, and prints the version on both success paths: a
      function defined and never invoked has the same exit status and the same
      empty output as one that worked.
    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
 - When pinning images or packages by hash, add a comment above the reference
  with the version and date (YYYY-MM-DD).
@@ -4,7 +4,7 @@ package main
 import (
 	"os"
-	"sneak.berlin/go/keyfunc/internal/cli"
+	"git.eeqj.de/sneak/keyfunc/internal/cli"
 )
 func main() {
@@ -1,4 +1,4 @@
-module sneak.berlin/go/keyfunc
+module git.eeqj.de/sneak/keyfunc
 go 1.26.0
@@ -5,9 +5,9 @@ import (
 	"strings"
 	"testing"
 	"git.eeqj.de/sneak/keyfunc/internal/agekey"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"github.com/stretchr/testify/require"
 	"sneak.berlin/go/keyfunc/internal/agekey"
 	"sneak.berlin/go/keyfunc/internal/derive"
 )
 // The recipients the example mnemonic produces at the first two
@@ -5,10 +5,10 @@ import (
 	"errors"
 	"fmt"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"git.eeqj.de/sneak/secret/pkg/bip85"
 	"github.com/btcsuite/btcd/btcutil/hdkeychain"
 	bip39 "github.com/tyler-smith/go-bip39"
 	"sneak.berlin/go/keyfunc/internal/derive"
 )
 // english is the number BIP-85 gives the English word list.
@@ -4,11 +4,11 @@ import (
 	"strings"
 	"testing"
 	"git.eeqj.de/sneak/keyfunc/internal/childmnemonic"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"github.com/btcsuite/btcd/btcutil/hdkeychain"
 	"github.com/stretchr/testify/require"
 	bip39 "github.com/tyler-smith/go-bip39"
 	"sneak.berlin/go/keyfunc/internal/childmnemonic"
 	"sneak.berlin/go/keyfunc/internal/derive"
 )
 // The lengths the tool offers, and one it does not.
@@ -8,10 +8,10 @@ import (
 	"os"
 	"path/filepath"
 	"git.eeqj.de/sneak/keyfunc/internal/agekey"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/options"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"github.com/spf13/cobra"
 	"sneak.berlin/go/keyfunc/internal/agekey"
 	"sneak.berlin/go/keyfunc/internal/cli/options"
 	"sneak.berlin/go/keyfunc/internal/derive"
 )
 // Command returns the age command and everything under it.
@@ -6,9 +6,9 @@ import (
 	"strings"
 	"testing"
 	"git.eeqj.de/sneak/keyfunc/internal/agekey"
 	"git.eeqj.de/sneak/keyfunc/internal/mnemonic"
 	"github.com/stretchr/testify/require"
 	"sneak.berlin/go/keyfunc/internal/agekey"
 	"sneak.berlin/go/keyfunc/internal/mnemonic"
 )
 func TestTheAgeCommandsPrintTheKey(t *testing.T) {
@@ -2,58 +2,31 @@
 package cli
 import (
 	"context"
 	"errors"
 	"fmt"
 	"os"
 	"os/signal"
 	"runtime/debug"
 	"syscall"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/age"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/mnemonic"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/options"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/ssh"
 	"github.com/spf13/cobra"
 	"sneak.berlin/go/keyfunc/internal/cli/age"
 	"sneak.berlin/go/keyfunc/internal/cli/mnemonic"
 	"sneak.berlin/go/keyfunc/internal/cli/options"
 	"sneak.berlin/go/keyfunc/internal/cli/ssh"
 )
-// devVersion is what Version holds until a build stamps a real one.
+// Version is what --version prints. The build sets it.
 const devVersion = "dev"
 // Version is what --version prints. make build stamps it with -ldflags.
 //
 //nolint:gochecknoglobals // set at build time with -ldflags
-var Version = devVersion
+var Version = "dev"
 // resolveVersion chooses what --version reports. A value stamped at
 // build time wins. Otherwise, for a binary from go install, the module
 // version recorded in the build info is used, unless that is empty or
 // the "(devel)" of a local build. When neither names a version, the
 // "dev" fallback stays.
 func resolveVersion(stamped string, info *debug.BuildInfo) string {
 	if stamped != devVersion {
 		return stamped
 	}
 	if info != nil && info.Main.Version != "" &&
 		info.Main.Version != "(devel)" {
 		return info.Main.Version
 	}
 	return devVersion
 }
 // Root returns the whole command tree.
 func Root() *cobra.Command {
 	info, _ := debug.ReadBuildInfo()
 	root := &cobra.Command{
 		Use:   "keyfunc",
 		Short: "derive key pairs from a BIP-39 mnemonic",
 		Long: "keyfunc turns a BIP-39 mnemonic into key pairs that can " +
 			"be recreated from that mnemonic at any time. The same " +
 			"mnemonic, key type and index always give the same key.",
-		Version:       resolveVersion(Version, info),
+		Version:       Version,
 		SilenceUsage:  true,
 		SilenceErrors: true,
 	}
@@ -69,19 +42,8 @@ func Root() *cobra.Command {
 // status of its own, which "ssh to" uses to hand on the status ssh
 // ended with. ssh has already said whatever it had to say in that
 // case, so nothing more is printed.
 //
 // SIGINT, SIGTERM and SIGHUP cancel the command's context instead of
 // killing the process outright, so the child ssh or sftp ends and the
 // deferred cleanup that removes the agent socket and the install
 // working directory still runs.
 func Main() int {
-	ctx, stop := signal.NotifyContext(
+	err := Root().Execute()
 		context.Background(),
 		syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP,
 	)
 	defer stop()
 	err := Root().ExecuteContext(ctx)
 	if err == nil {
 		return 0
 	}
@@ -5,13 +5,13 @@ import (
 	"strings"
 	"testing"
 	"git.eeqj.de/sneak/keyfunc/internal/childmnemonic"
 	"git.eeqj.de/sneak/keyfunc/internal/cli"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"git.eeqj.de/sneak/keyfunc/internal/mnemonic"
 	"github.com/stretchr/testify/require"
 	bip39 "github.com/tyler-smith/go-bip39"
 	"golang.org/x/crypto/ssh"
 	"sneak.berlin/go/keyfunc/internal/childmnemonic"
 	"sneak.berlin/go/keyfunc/internal/cli"
 	"sneak.berlin/go/keyfunc/internal/derive"
 	"sneak.berlin/go/keyfunc/internal/mnemonic"
 )
 // The two lines the README says the example mnemonic produces.
@@ -4,10 +4,10 @@ package mnemonic
 import (
 	"fmt"
 	"git.eeqj.de/sneak/keyfunc/internal/childmnemonic"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/options"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"github.com/spf13/cobra"
 	"sneak.berlin/go/keyfunc/internal/childmnemonic"
 	"sneak.berlin/go/keyfunc/internal/cli/options"
 	"sneak.berlin/go/keyfunc/internal/derive"
 )
 // Command returns the mnemonic command.
@@ -5,8 +5,8 @@ package options
 import (
 	"fmt"
 	"git.eeqj.de/sneak/keyfunc/internal/mnemonic"
 	"github.com/spf13/cobra"
 	"sneak.berlin/go/keyfunc/internal/mnemonic"
 )
 // Add gives a command the flags that every command has. They are
@@ -166,7 +166,6 @@ func session(
 	//nolint:gosec // the options are the user's own, meant for sftp
 	command := exec.CommandContext(cmd.Context(), "sftp", argv...)
 	command.Env = childEnv()
 	command.Stdin = strings.NewReader(strings.Join(batch, "\n") + "\n")
 	command.Stdout = &said
 	command.Stderr = &said
@@ -3,14 +3,11 @@ package ssh
 import (
 	"fmt"
 	"os"
 	"strings"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/options"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"git.eeqj.de/sneak/keyfunc/internal/sshkey"
 	"github.com/spf13/cobra"
 	"sneak.berlin/go/keyfunc/internal/cli/options"
 	"sneak.berlin/go/keyfunc/internal/derive"
 	"sneak.berlin/go/keyfunc/internal/mnemonic"
 	"sneak.berlin/go/keyfunc/internal/sshkey"
 )
 // Command returns the ssh command and everything under it.
@@ -87,26 +84,6 @@ func write(cmd *cobra.Command, text string) error {
 	return nil
 }
 // childEnv is the tool's environment with the mnemonic variables taken
 // out, for the ssh and sftp children it starts. "ssh to" exists so the
 // private key never leaves the tool; the mnemonic, from either variable,
 // must not leave it either.
 func childEnv() []string {
 	environ := os.Environ()
 	kept := make([]string, 0, len(environ))
 	for _, entry := range environ {
 		name, _, _ := strings.Cut(entry, "=")
 		if name == mnemonic.Variable || name == mnemonic.CommandVariable {
 			continue
 		}
 		kept = append(kept, entry)
 	}
 	return kept
 }
 // addComment gives a command its comment flag.
 func addComment(cmd *cobra.Command) {
 	cmd.Flags().String(
@@ -7,7 +7,6 @@ import (
 	"os"
 	"os/exec"
 	"slices"
 	"syscall"
 	"github.com/spf13/cobra"
 )
@@ -71,18 +70,10 @@ func to() *cobra.Command {
 func connect(ctx context.Context, argv []string) error {
 	//nolint:gosec // the arguments are the user's own, meant for ssh
 	command := exec.CommandContext(ctx, "ssh", argv...)
 	command.Env = childEnv()
 	command.Stdin = os.Stdin
 	command.Stdout = os.Stdout
 	command.Stderr = os.Stderr
 	// A cancelled context means a signal ended the tool. Send ssh a
 	// SIGTERM rather than the default kill, so it puts the terminal
 	// back the way it found it before it goes.
 	command.Cancel = func() error {
 		return command.Process.Signal(syscall.SIGTERM)
 	}
 	err := command.Run()
 	if err == nil {
 		return nil
@@ -3,38 +3,18 @@ package cli_test
 import (
 	"bytes"
 	"os"
 	"os/exec"
 	"path/filepath"
 	"slices"
 	"strconv"
 	"strings"
 	"syscall"
 	"testing"
 	"time"
 	"git.eeqj.de/sneak/keyfunc/internal/cli"
 	"git.eeqj.de/sneak/keyfunc/internal/cli/ssh"
 	"git.eeqj.de/sneak/keyfunc/internal/mnemonic"
 	"github.com/stretchr/testify/require"
 	"sneak.berlin/go/keyfunc/internal/cli"
 	"sneak.berlin/go/keyfunc/internal/cli/ssh"
 	"sneak.berlin/go/keyfunc/internal/mnemonic"
 )
 // runAsTool, set in the environment of a re-executed test binary, tells
 // TestMain to run the tool through Main rather than the suite, so the
 // signal test can drive the real signal path in a process it can send a
 // signal to.
 const runAsTool = "KEYFUNC_TEST_RUN_AS_TOOL"
 // TestMain re-executes the test binary as the tool when runAsTool is
 // set, and otherwise runs the suite. The signal test starts the tool
 // this way, as a subprocess it can signal and watch clean up.
 func TestMain(m *testing.M) {
 	if os.Getenv(runAsTool) == "1" {
 		os.Exit(cli.Main())
 	}
 	os.Exit(m.Run())
 }
 // The modes the host is supposed to end up with, and the mode the
 // stand-ins need so that they can be run at all.
 const (
@@ -67,9 +47,6 @@ const (
 	keptIn    = "authorized_keys"
 )
 // remoteCommand is the command the "to" tests hand ssh after the host.
 const remoteCommand = "uptime"
 // The tool's own name, as it stands in the arguments a test hands to
 // Main, the ssh subcommand both commands the tests here drive live
 // under, and the one of those two these tests name most.
@@ -83,19 +60,13 @@ const (
 // an authorized_keys file.
 const keyLine = vectorZero + " keyfunc/ssh/0\n"
 // marker is a variable set beside the mnemonic ones and expected to
 // reach the stand-in, so a scrubbed environment is told apart from an
 // empty one.
 const marker = "KEYFUNC_TEST_MARKER"
 // installer is a stand-in for the system sftp for the install
 // command. It writes down the arguments and every command of the
-// batch it is given, echoes each command as sftp does, writes down its
+// batch it is given, echoes each command as sftp does, and carries
-// own environment when a test asks for it, and carries the commands out
+// the commands out against a directory standing in for the host's
-// against a directory standing in for the host's home directory, so that
+// home directory, so that what keyfunc sends can be watched doing its
-// what keyfunc sends can be watched doing its work. A command that
+// work. A command that begins with a dash may fail; any other failure
-// begins with a dash may fail; any other failure ends the session, as it
+// ends the session, as it does in sftp's own batch mode.
 // does in sftp's own batch mode.
 //
 // The listing and the two ways a get can fail are worded as the
 // OpenSSH client words them, each naming the path the server expanded.
@@ -110,7 +81,6 @@ const marker = "KEYFUNC_TEST_MARKER"
 // draws the warning ssh writes for it, which carries the wording of a
 // missing file into a session that goes on to authenticate.
 const installer = `
 [ -n "$KEYFUNC_TEST_ENVIRONMENT" ] && env > "$KEYFUNC_TEST_ENVIRONMENT"
 previous=
 for argument in "$@"; do
 	printf '%s\n' "$argument" >> "$KEYFUNC_TEST_ARGUMENTS"
@@ -174,11 +144,9 @@ done
 // caller is a stand-in for the system ssh for the to command. It
 // writes down the arguments it was given, notes the agent socket if
-// there really is one at the path it was handed, writes down its own
+// there really is one at the path it was handed, and ends with the
-// environment when a test asks for it, and ends with the status the
+// status the test asked for.
 // test asked for.
 const caller = `
 [ -n "$KEYFUNC_TEST_ENVIRONMENT" ] && env > "$KEYFUNC_TEST_ENVIRONMENT"
 for argument in "$@"; do
 	printf '%s\n' "$argument" >> "$KEYFUNC_TEST_ARGUMENTS"
 done
@@ -189,18 +157,6 @@ fi
 exit "$KEYFUNC_TEST_STATUS"
 `
 // sleeper is a stand-in for the system ssh that notes the agent socket
 // and then blocks, so a test can cancel the context while it is running
 // and watch the tool take the agent down. The wait ends on its own only
 // as a backstop, well after the test has cancelled and looked.
 const sleeper = `
 socket=${2#IdentityAgent=}
 if [ -S "$socket" ]; then
 	printf '%s\n' "$socket" > "$KEYFUNC_TEST_SOCKET"
 fi
 sleep 5
 `
 // pretended is where a stand-in writes down what it was asked to do.
 type pretended struct {
 	// home stands in for the home directory on the host.
@@ -456,7 +412,7 @@ func TestSSHIsPointedAtTheAgentAndItsStatusIsHandedOn(t *testing.T) {
 	arguments, noted := pretendCall(t)
-	_, err := execute(t, subcommand, "to", host, remoteCommand)
+	_, err := execute(t, subcommand, "to", host, "uptime")
 	var passed ssh.StatusError
@@ -465,7 +421,7 @@ func TestSSHIsPointedAtTheAgentAndItsStatusIsHandedOn(t *testing.T) {
 	given := recorded(t, arguments)
 	require.Equal(t, "-o", given[0])
-	require.Equal(t, []string{host, remoteCommand}, given[2:])
+	require.Equal(t, []string{host, "uptime"}, given[2:])
 	// The stand-in wrote the path down only because there really was
 	// a socket there while it ran.
@@ -483,130 +439,11 @@ func TestTheToolEndsWithTheStatusSSHEndedWith(t *testing.T) {
 	t.Cleanup(func() { os.Args = given })
-	os.Args = []string{tool, subcommand, "to", host, remoteCommand}
+	os.Args = []string{tool, subcommand, "to", host, "uptime"}
 	require.Equal(t, failingStatus, cli.Main())
 }
 func TestASignalTakesTheAgentDirectoryDown(t *testing.T) {
 	t.Setenv(mnemonic.Variable, example())
 	// The three signals the tool handles, checked one after another.
 	signals := []struct {
 		name   string
 		signal os.Signal
 	}{
 		{"SIGTERM", syscall.SIGTERM},
 		{"SIGINT", syscall.SIGINT},
 		{"SIGHUP", syscall.SIGHUP},
 	}
 	for _, ending := range signals {
 		signalEndsTheTool(t, ending.name, ending.signal)
 	}
 }
 // signalEndsTheTool runs the tool as a subprocess against a stand-in
 // ssh that blocks, waits until the agent is up and ssh is running
 // against it, sends the tool the signal, and requires the agent socket
 // and its directory to be gone once the tool has ended. The subprocess
 // goes through Main and its signal handling, so with that handling
 // removed the signal kills the tool outright, no deferred cleanup runs,
 // the directory is left behind, and the check fails.
 func signalEndsTheTool(t *testing.T, name string, signal os.Signal) {
 	t.Helper()
 	noted := filepath.Join(t.TempDir(), "socket")
 	t.Setenv("KEYFUNC_TEST_SOCKET", noted)
 	standIn(t, "ssh", sleeper)
 	//nolint:gosec // the binary is this test's own, re-run as the tool
 	command := exec.CommandContext(
 		t.Context(), os.Args[0], subcommand, "to", host, remoteCommand,
 	)
 	command.Env = append(os.Environ(), runAsTool+"=1")
 	require.NoError(t, command.Start())
 	// The stand-in notes the socket only once the agent is up and ssh
 	// is running against it, so this is where the signal lands.
 	socket := waitForSocket(t, noted)
 	require.NoError(t, command.Process.Signal(signal))
 	waitForTool(t, name, command)
 	// The signal ended the tool, and its deferred cleanup still ran:
 	// the agent socket and its directory are gone.
 	require.NoDirExists(t, filepath.Dir(socket), name)
 }
 // waitForTool waits for the subprocess to end, and fails the test if it
 // does not end in time.
 func waitForTool(t *testing.T, name string, command *exec.Cmd) {
 	t.Helper()
 	done := make(chan error, 1)
 	go func() { done <- command.Wait() }()
 	select {
 	case <-done:
 	case <-time.After(10 * time.Second):
 		t.Fatalf("the tool did not end after %s", name)
 	}
 }
 // waitForSocket waits for the stand-in to write down the agent socket
 // and gives back the path, which means the agent is up and ssh is
 // running against it.
 func waitForSocket(t *testing.T, noted string) string {
 	t.Helper()
 	var socket string
 	require.Eventually(t, func() bool {
 		content, err := os.ReadFile(noted) //nolint:gosec // test path
 		if err != nil {
 			return false
 		}
 		socket = strings.TrimSpace(string(content))
 		return socket != ""
 	}, 5*time.Second, 5*time.Millisecond)
 	return socket
 }
 func TestTheMnemonicIsNotHandedToSFTP(t *testing.T) {
 	t.Setenv(mnemonic.CommandVariable, "echo "+example())
 	t.Setenv(mnemonic.Variable, example())
 	t.Setenv(marker, "reaches the stand-in")
 	pretendHost(t)
 	environment := recordEnvironment(t)
 	install(t, host)
 	mnemonicWithheld(t, read(t, environment))
 }
 func TestTheMnemonicIsNotHandedToSSH(t *testing.T) {
 	t.Setenv(mnemonic.CommandVariable, "echo "+example())
 	t.Setenv(mnemonic.Variable, example())
 	t.Setenv(marker, "reaches the stand-in")
 	pretendCall(t)
 	environment := recordEnvironment(t)
 	_, err := execute(t, subcommand, "to", host, remoteCommand)
 	var passed ssh.StatusError
 	require.ErrorAs(t, err, &passed)
 	mnemonicWithheld(t, read(t, environment))
 }
 // pretendHost puts the install stand-in on the path and gives back the
 // places it writes to.
 func pretendHost(t *testing.T) pretended {
@@ -755,28 +592,6 @@ func standIn(t *testing.T, name, body string) {
 	)
 }
 // recordEnvironment asks the stand-in to write its environment down and
 // gives back the file it writes it to.
 func recordEnvironment(t *testing.T) string {
 	t.Helper()
 	path := filepath.Join(t.TempDir(), "environment")
 	t.Setenv("KEYFUNC_TEST_ENVIRONMENT", path)
 	return path
 }
 // mnemonicWithheld requires that neither mnemonic variable reached the
 // stand-in and that the marker set beside them did, so an empty
 // environment does not pass for a scrubbed one.
 func mnemonicWithheld(t *testing.T, environment string) {
 	t.Helper()
 	require.NotContains(t, environment, mnemonic.Variable+"=")
 	require.NotContains(t, environment, mnemonic.CommandVariable+"=")
 	require.Contains(t, environment, marker+"=")
 }
 // read returns what is in a file.
 func read(t *testing.T, path string) string {
 	t.Helper()
@@ -1,37 +0,0 @@
 package cli
 import (
 	"runtime/debug"
 	"testing"
 	"github.com/stretchr/testify/require"
 )
 func TestResolveVersion(t *testing.T) {
 	t.Parallel()
 	release := &debug.BuildInfo{Main: debug.Module{Version: "v1.2.3"}}
 	local := &debug.BuildInfo{Main: debug.Module{Version: "(devel)"}}
 	empty := &debug.BuildInfo{}
 	t.Run("stamped value wins over build info", func(t *testing.T) {
 		t.Parallel()
 		require.Equal(t, "v0.1.0", resolveVersion("v0.1.0", release))
 	})
 	t.Run("go install reports the module version", func(t *testing.T) {
 		t.Parallel()
 		require.Equal(t, "v1.2.3", resolveVersion(devVersion, release))
 	})
 	t.Run("a local build stays dev", func(t *testing.T) {
 		t.Parallel()
 		require.Equal(t, devVersion, resolveVersion(devVersion, local))
 	})
 	t.Run("no version anywhere stays dev", func(t *testing.T) {
 		t.Parallel()
 		require.Equal(t, devVersion, resolveVersion(devVersion, empty))
 		require.Equal(t, devVersion, resolveVersion(devVersion, nil))
 	})
 }
@@ -5,8 +5,8 @@ import (
 	"strings"
 	"testing"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"github.com/stretchr/testify/require"
 	"sneak.berlin/go/keyfunc/internal/derive"
 )
 // application is the number the SSH key type uses.
@@ -4,8 +4,8 @@ import (
 	"strings"
 	"testing"
 	"git.eeqj.de/sneak/keyfunc/internal/mnemonic"
 	"github.com/stretchr/testify/require"
 	"sneak.berlin/go/keyfunc/internal/mnemonic"
 )
 // Two more mnemonics that pass the checksum, so a test can tell which
@@ -7,11 +7,11 @@ import (
 	"strings"
 	"testing"
 	"git.eeqj.de/sneak/keyfunc/internal/derive"
 	"git.eeqj.de/sneak/keyfunc/internal/sshkey"
 	"github.com/stretchr/testify/require"
 	"golang.org/x/crypto/ssh"
 	"golang.org/x/crypto/ssh/agent"
 	"sneak.berlin/go/keyfunc/internal/derive"
 	"sneak.berlin/go/keyfunc/internal/sshkey"
 )
 // agentDirectoryMode is what the directory holding the agent socket
@@ -1,5 +0,0 @@
 {
  "devDependencies": {
    "prettier": "3.8.1"
  }
 }
@@ -3,23 +3,13 @@
 # repo. Idempotent: every install is guarded by a check, so tools that
 # are already there are left alone. Base tooling comes from nix, apt,
 # brew, or apk, detected in that order, and nothing is assumed to be
-# present. Node is used directly if installed; otherwise it is installed
+# present. The linter is not installed here: it only ever runs inside
-# at a pinned version via nvm (installing nvm itself first, from a
+# the image built from Dockerfile.lint, so Docker is what is needed for
-# hash-verified release archive, never curl | sh). The linter is not
+# it, and that is checked for rather than installed.
 # installed here: linting and testing run only as phases of the
 # Dockerfile, so Docker is what is needed for them, and that is checked
 # for rather than installed.
 set -eu
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 # Pinned versions, 2026-07-06
 NODE_VERSION="22.17.0"
 NVM_VERSION="0.40.3"
 # sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
 NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
 YARN_VERSION="1.22.22"
 PKGMGR=""
 SUDO=""
@@ -60,69 +50,6 @@ missing() {
    ! command -v "$1" >/dev/null 2>&1
 }
 # verify_sha256 <file> <expected-hash>
 verify_sha256() {
    if command -v sha256sum >/dev/null 2>&1; then
        actual="$(sha256sum "$1" | cut -d' ' -f1)"
    else
        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
    fi
    if [ "$actual" != "$2" ]; then
        echo "bootstrap: sha256 mismatch for $1" >&2
        echo "  expected: $2" >&2
        echo "  actual:   $actual" >&2
        exit 1
    fi
 }
 # nvm is a bash script; run a command in a bash with nvm loaded
 nvm_sh() {
    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
 }
 ensure_nvm() {
    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
    # nvm prerequisites; nvm itself requires bash
    if missing bash; then pkg_install bash bash bash bash; fi
    if missing curl; then pkg_install curl curl curl curl; fi
    if missing git; then pkg_install git git git git; fi
    tmp="$(mktemp -d)"
    curl -fsSL -o "$tmp/nvm.tar.gz" \
        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
    mkdir -p "$HOME/.nvm"
    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
    rm -rf "$tmp"
 }
 ensure_node() {
    if ! missing node; then return 0; fi
    ensure_nvm
    nvm_sh "nvm install $NODE_VERSION"
 }
 ensure_yarn() {
    if ! missing yarn; then return 0; fi
    if ! missing corepack; then
        corepack enable
        corepack prepare "yarn@$YARN_VERSION" --activate
    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
            corepack prepare yarn@$YARN_VERSION --activate"
    else
        npm install -g "yarn@$YARN_VERSION"
    fi
 }
 install_js_deps() {
    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
            yarn install --frozen-lockfile"
    else
        yarn install --frozen-lockfile
    fi
 }
 main() {
    cd "$ROOT"
@@ -132,12 +59,8 @@ main() {
    go mod download
    ensure_node
    ensure_yarn
    install_js_deps
    if missing docker; then
-        echo "bootstrap: docker is not installed; make lint and make test need it" >&2
+        echo "bootstrap: docker is not installed; make lint needs it" >&2
    fi
    echo "bootstrap complete"
@@ -1,10 +1,8 @@
 #!/bin/sh
-# script/cibuild: run the CI build. It bootstraps first: a CI runner
+# script/cibuild: run the CI build. The linter needs an image of its
-# checks out and runs this and nothing else, and script/fmt-check runs
+# own, so it runs first; the Dockerfile then runs the formatting check,
-# the formatter on the host, which a pristine checkout cannot do.
+# the tests and the build, so a green run here means make check is
-# --no-cache for the same reason as script/docker: the gate phases the
+# green.
 # final stage depends on are RUN steps, and a cached one is a check that
 # did not run.
 set -eu
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -12,17 +10,8 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 main() {
    cd "$ROOT"
-    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/lint"
-    "$SCRIPT_DIR/check"
+    docker build .
    # Own line: a failing command substitution inside an argument does
    # not trip `set -e`, so the inline form degrades silently to an
    # empty constant. The VERSION build argument takes precedence over
    # the version a build stage derives from the .git in the context.
    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
    [ -n "$version" ] || version="unknown"
    docker build --no-cache \
        --build-arg VERSION="$version" \
        -t "$("$SCRIPT_DIR/projectname")" .
 }
 main "$@"
@@ -1,8 +1,6 @@
 #!/bin/sh
 # script/docker: build the Docker image tagged with the project name.
 # Identical in all repos; the tag comes from script/projectname.
 # --no-cache because the gate phases the final stage depends on are RUN
 # steps, and a cached one is a check that did not run.
 set -eu
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -10,15 +8,7 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 main() {
    cd "$ROOT"
-    # Own line: a failing command substitution inside an argument does
+    docker build -t "$("$SCRIPT_DIR/projectname")" .
    # not trip `set -e`, so the inline form degrades silently to an
    # empty constant. The VERSION build argument takes precedence over
    # the version a build stage derives from the .git in the context.
    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
    [ -n "$version" ] || version="unknown"
    docker build --no-cache \
        --build-arg VERSION="$version" \
        -t "$("$SCRIPT_DIR/projectname")" .
 }
 main "$@"
@@ -1,33 +1,12 @@
 #!/bin/sh
-# script/fmt: format all files (writes): the Go source with go fmt, then
+# script/fmt: format all files (writes).
 # the Markdown files with prettier.
 set -eu
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 # Must match the pin in script/bootstrap.
 NODE_VERSION="22.17.0"
 # script/bootstrap installs node and yarn under nvm and leaves neither
 # on the PATH of the shell that called it, so resolve the pinned
 # toolchain here the way bootstrap's own install step does. nvm is a
 # bash script, hence the subshell.
 run_yarn() {
    if command -v yarn >/dev/null 2>&1; then
        exec yarn "$@"
    fi
    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
        echo "fmt: no yarn; run script/bootstrap first" >&2
        exit 1
    fi
    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
 }
 main() {
    cd "$ROOT"
    go fmt ./...
    run_yarn run prettier --write '**/*.md' --tab-width 4 --prose-wrap always
 }
 main "$@"
@@ -5,25 +5,6 @@ set -eu
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 # Must match the pin in script/bootstrap.
 NODE_VERSION="22.17.0"
 # script/bootstrap installs node and yarn under nvm and leaves neither
 # on the PATH of the shell that called it, so resolve the pinned
 # toolchain here the way bootstrap's own install step does. nvm is a
 # bash script, hence the subshell.
 run_yarn() {
    if command -v yarn >/dev/null 2>&1; then
        exec yarn "$@"
    fi
    if [ ! -s "$HOME/.nvm/nvm.sh" ]; then
        echo "fmt-check: no yarn; run script/bootstrap first" >&2
        exit 1
    fi
    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
 }
 main() {
    cd "$ROOT"
    if [ -n "$(gofmt -l .)" ]; then
@@ -31,7 +12,6 @@ main() {
        gofmt -l .
        exit 1
    fi
    run_yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
 }
 main "$@"
@@ -1,13 +1,9 @@
 #!/bin/sh
-# script/lint: run the linter. Linting is a phase of the Dockerfile and
+# script/lint: run the linter. Linting only ever happens inside the
-# this builds that phase alone; the linter is never installed or run on
+# image built from Dockerfile.lint, which pins the linter by hash, so
-# a developer host, where a shared result cache and a host-global lock
+# the answer is the same on every machine and in CI. The linter runs as
-# make its answer untrustworthy.
+# a build step of that image, so a complaint fails the build and no
-#
+# container is left behind.
 # The phase is not the last stage in the file, so it is built only when
 # --target names it. --no-cache because a cached lint layer is a lint
 # that did not run. The tag makes each build replace the previous image
 # instead of leaving a dangling one behind.
 set -eu
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -15,8 +11,7 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 main() {
    cd "$ROOT"
-    docker build --no-cache \
+    docker build --progress=plain -f Dockerfile.lint \
        --target lint \
        -t "$("$SCRIPT_DIR/projectname")-lint" .
 }
@@ -1,19 +1,13 @@
 #!/bin/sh
-# script/test: run the test suite. Testing is a phase of the Dockerfile
+# script/test: run the test suite (vet first, verbose rerun on failure).
 # and this builds that phase alone, on the same terms as script/lint:
 # --target because a phase that is not the last stage is built only when
 # named, --no-cache because a cached test layer is a test that did not
 # run, and a tag so each build replaces the previous image.
 set -eu
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 main() {
    cd "$ROOT"
-    docker build --no-cache \
+    go vet ./...
-        --target test \
+    go test -timeout 90s ./... || go test -timeout 90s -v ./...
        -t "$("$SCRIPT_DIR/projectname")-test" .
 }
 main "$@"
@@ -1,8 +0,0 @@
 # THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
 # yarn lockfile v1
 prettier@3.8.1:
  version "3.8.1"
  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
  integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==
`@@ -1,4 +1,4 @@`
	`module sneak.berlin/go/keyfunc`	`module git.eeqj.de/sneak/keyfunc`

	`go 1.26.0`	`go 1.26.0`