Rewrite REPO_POLICIES.md sentence by sentence (closes #136 )

Every sentence of prompts/REPO_POLICIES.md is rewritten against the sentence rules: one idea per sentence, about 30 words at most, lists as bulleted lists, subject and verb early, the main rule before any exception. No rule's meaning changed: nothing is added, removed, loosened or tightened, every reason stays, and code blocks, digests, URLs, file names, commands and quoted strings are unchanged. Both repo checklists carry the same rewrite of the sentences they quote word for word. Model: fable-5-1
2026-11-04 00:29:53 +00:00
18 changed files with 464 additions and 1678 deletions
@@ -35,12 +35,6 @@
 # `services/api/.claude/` and must add its own anchored entry.
 .claude
 # yarn's install state and cache stay out, and its release file stays
 # in. Docker obeys the last matching line, so these two lines sit above
 # the secret patterns, which must win under .yarn/releases/.
 .yarn/*
 !.yarn/releases
 # 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`.
@@ -2,6 +2,3 @@
 # both sides instead of conflicting. Git never reports a conflict here: read
 # the merged entries after every merge or rebase.
 TODO.md merge=union
 # yarn's release file is one opaque file in diffs and merges.
 .yarn/releases/** binary
@@ -19,12 +19,10 @@ Thumbs.db
 # Node
 node_modules/
 .yarn/*
 !.yarn/releases
-# Secrets. Unanchored, so each matches at every depth. Matching is
+# Secrets. Unanchored like every entry above, so each matches at every
-# case-sensitive on Linux, so names use character ranges rather than a
+# depth. Matching is case-sensitive on Linux, so names use character
-# lowercase form that misses `Server.Key`.
+# 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
@@ -1,3 +1,2 @@
 node_modules/
 .yarn/
 yarn.lock
@@ -1,5 +0,0 @@
 enableTelemetry: false
 nodeLinker: node-modules
 yarnPath: .yarn/releases/yarn-4.18.1.cjs
@@ -2,24 +2,17 @@
 # lint` or `script/lint`, which are themselves a docker build and would
 # recurse into a daemon that does not exist in a build step.
 #
-# In every stage, ARG CACHEBUST comes right after the step that installs
+# Every stage declares ARG CACHEBUST first: script/ passes a new value on
-# system packages. script/ passes a new value on every build. That value
+# every build, which reruns every RUN step after it.
 # reruns every RUN step below the ARG line, and the install step keeps
 # its layer. node and yarn come from the distribution, which is trusted,
 # so they need no version and no hash. That yarn only starts the release
 # file in .yarn/releases/, so every stage copies that file and
 # .yarnrc.yml before it runs script/bootstrap.
 #
-# alpine 3.24.3, 2026-11-04
+# node 22-alpine, 2026-02-22
-FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS lint
 RUN apk add --no-cache git make nodejs-current yarn
 ARG CACHEBUST
 WORKDIR /app
 COPY script/ script/
-COPY package.json yarn.lock .yarnrc.yml ./
+COPY package.json yarn.lock ./
 COPY .yarn/releases/ .yarn/releases/
 RUN script/bootstrap
 COPY . .
@@ -28,16 +21,14 @@ RUN yarn run prettier --check '**/*.md' --tab-width 4 --prose-wrap always
 # Test phase, same shape and for the same reason.
 #
-# alpine 3.24.3, 2026-11-04
+# node 22-alpine, 2026-02-22
-FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS test
 RUN apk add --no-cache git make nodejs-current yarn
 ARG CACHEBUST
 WORKDIR /app
 COPY script/ script/
-COPY package.json yarn.lock .yarnrc.yml ./
+COPY package.json yarn.lock ./
 COPY .yarn/releases/ .yarn/releases/
 RUN script/bootstrap
 COPY . .
@@ -50,9 +41,8 @@ RUN echo "No tests defined."
 # this image cannot be produced unless lint and test passed. A stage
 # appended after this one would drop all three out of a plain build.
 #
-# alpine 3.24.3, 2026-11-04
+# node 22-alpine, 2026-02-22
-FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
 RUN apk add --no-cache git make nodejs-current yarn
 ARG CACHEBUST
 WORKDIR /app
@@ -60,11 +50,10 @@ WORKDIR /app
 COPY --from=lint /app/package.json /dev/null
 COPY --from=test /app/package.json /dev/null
-# script/bootstrap finds the system packages above and installs the node
+# script/bootstrap installs all prerequisites. Manifests are copied
-# packages.
+# first so that layer stays cached until dependencies change.
 COPY script/ script/
-COPY package.json yarn.lock .yarnrc.yml ./
+COPY package.json yarn.lock ./
 COPY .yarn/releases/ .yarn/releases/
 RUN script/bootstrap
 COPY . .
@@ -111,7 +111,7 @@ development workflow, and the Makefile targets are thin shims that call them.
 The scripts are POSIX sh (not bash) so they run in minimal containers such as
 alpine. We provide:
- `script/bootstrap` — install all dependencies (`yarn install --immutable`)
+- `script/bootstrap` — install all dependencies (yarn install)
 - `script/setup` — set up the repo for development after a fresh clone: runs
  `script/bootstrap`, then `script/install-precommit`
 - `script/projectname` — output the project name (our own extension); used by
@@ -156,9 +156,9 @@ A stage with none of these steps declares `ARG CACHEBUST` right after `FROM`.
 The `script/` builds pass a new `CACHEBUST` value on every build, which reruns
 every `RUN` step after that line and leaves the layers above it and the cache
 mounts in place; `--no-cache` would build those layers again and empty the
-mounts. This repo's own `Dockerfile` installs git, make, node and yarn right
+mounts. This repo's own `Dockerfile` declares `ARG CACHEBUST` right after `FROM`
-after `FROM` in every stage, above `ARG CACHEBUST`. `script/bootstrap` installs
+in every stage: each stage installs system packages and node packages together
-the node packages below that line, because check builds keep system packages but
+in one `script/bootstrap` step, and check builds may keep system packages but
 not node packages.
 ## Rationale
@@ -21,51 +21,7 @@ fmt-check, and commit.
 # Completed Steps
- 2026-11-06: The pinning rule in `prompts/REPO_POLICIES.md` now opens with its
+- 2026-11-03: Rewrote `prompts/REPO_POLICIES.md` sentence by sentence
  scope: what we download and install ourselves in scripts and Dockerfiles
  (https://git.eeqj.de/sneak/prompts/issues/154). Distribution packages are
  outside the rule, and updating and upgrading them is allowed. Both checklists
  say the same.
 - 2026-11-04: Each repository now commits yarn 4 and installs with
  `yarn install --immutable` (https://git.eeqj.de/sneak/prompts/issues/149), on
  sneak's ruling at
  https://git.eeqj.de/sneak/prompts/issues/149#issuecomment-167558. Product
  repositories convert when they next have work. These changed:
    - This repository carries `.yarn/releases/yarn-4.18.1.cjs`, and its
      `yarn.lock` is in yarn 4's format.
    - `script/bootstrap` no longer stops on yarn's major version.
    - Node comes from the distribution's newest Node package, which on Alpine
      3.24 is `nodejs-current`.
    - A `Dockerfile` stage that needs yarn also copies `.yarnrc.yml` and
      `.yarn/releases/`, and may start from any distribution that packages node
      and yarn.
    - Both checklists give the steps, and the ignore files keep yarn's install
      state out of git and the build context.
 - 2026-11-04: An agent whose work is confined to one package may run `go test`
  directly on that package's suite, or on individual tests in it, while
  iterating (https://git.eeqj.de/sneak/prompts/issues/51), on sneak's ruling at
  https://git.eeqj.de/sneak/prompts/issues/51#issuecomment-167600. The full
  `make check` is still required before every push, and the `Makefile` gains
  nothing. The rule on Docker now names the lint and test gates, because a run
  while iterating is not one.
 - 2026-11-04: node, yarn, npm, python, pip and venv now come from the
  distribution with no version and no hash
  (https://git.eeqj.de/sneak/prompts/issues/146), on sneak's ruling at
  https://git.eeqj.de/sneak/prompts/issues/146#issuecomment-166033. Third-party
  packages stay pinned by hash. These changed:
    - `script/bootstrap` no longer uses nvm or corepack, and stops when yarn's
      major version is not 1.
    - `script/bootstrap` installs node, yarn and the node packages only when
      `yarn.lock` is in the tree.
    - `script/bootstrap`, `script/fmt` and `script/fmt-check` run `yarn` or
      `yarnpkg`, whichever is present.
    - This repository's `Dockerfile` starts from Alpine 3.24.
    - The Python `test` phase example starts from `debian:trixie-slim`.
    - A Python repository's `script/bootstrap` creates its virtual environment
      at `$HOME/.pipenv`, so it works on a host and in a `Dockerfile`.
    - `PIP_ONLY_BINARY=:all:` stops a package with no wheel, so pip downloads no
      build tools without a hash check.
 - 2026-11-04: Rewrote `prompts/REPO_POLICIES.md` sentence by sentence
  (https://git.eeqj.de/sneak/prompts/issues/136), on sneak's yes at
  https://git.eeqj.de/sneak/prompts/issues/136#issuecomment-165193. Every rule
  keeps its meaning and its place, and `must` and `should` stay as they were.
@@ -2,6 +2,5 @@
  "private": true,
  "devDependencies": {
    "prettier": "3.8.1"
-  },
+  }
  "packageManager": "yarn@4.18.1"
 }
@@ -1,6 +1,6 @@
 ---
 title: Code Styleguide — JavaScript
-last_modified: 2026-11-04
+last_modified: 2026-02-22
 ---
 1. Use `const` for everything. If you need to reassign, use `let`. Never use
@@ -8,8 +8,7 @@ last_modified: 2026-11-04
 1. Use yarn for package management, avoid using npm.
-1. Install node from the distribution. If its version is too old, use a newer
+1. Use LTS node versions.
   distribution.
 1. Use `prettier` for code formatting, with four spaces for indentation.
@@ -1,6 +1,6 @@
 ---
 title: Existing Repo Checklist
-last_modified: 2026-11-06
+last_modified: 2026-11-03
 ---
 Use this checklist when beginning work in a repo that may not yet conform to our
@@ -56,14 +56,14 @@ with your task.
    - the step that runs `script/bootstrap` to install a Python `test` phase's
      packages from `Pipfile.lock`
 - [ ] A stage with none of these steps declares `ARG CACHEBUST` right after
-      `FROM`. A step that also installs anything else comes after
+      `FROM`. A step that installs anything else as well, such as a
-      `ARG CACHEBUST` too. A `script/bootstrap` that also installs node packages
+      `script/bootstrap` that also installs node packages, comes after it too.
-      is one. The `script/` builds pass a new `CACHEBUST` value on every build,
+      The `script/` builds pass a new `CACHEBUST` value on every build, which
-      which reruns every `RUN` step after that line and leaves the layers above
+      reruns every `RUN` step after that line and leaves the layers above it and
-      it and the cache mounts in place; `--no-cache` would build those layers
+      the cache mounts in place; `--no-cache` would build those layers again and
-      again and empty the mounts. A stage without the `ARG` line is served from
+      empty the mounts. A stage without the `ARG` line is served from cache on
-      cache on an unchanged tree, so the scripts and the `ARG` lines are
+      an unchanged tree, so the scripts and the `ARG` lines are re-vendored in
-      re-vendored in one commit.
+      one commit.
 - [ ] Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
      `RUN go mod download`) above `ARG CACHEBUST`; the steps that compile
      (`golangci-lint run`, `go test`, `go build`) mount Go's build cache
@@ -76,25 +76,15 @@ with your task.
 - [ ] Python: a `test` phase that installs its packages from `Pipfile.lock` does
      it above `ARG CACHEBUST`, with `COPY script/ script/`,
      `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
-      `script/bootstrap` runs in that step, it installs nothing beyond these:
+      `script/bootstrap` runs in that step, it installs nothing beyond system
-    - system packages
+      packages, pipenv and its dependencies, and the packages from
-    - pipenv and its dependencies
+      `Pipfile.lock`. It installs pipenv and its dependencies by hash, with
-    - the packages from `Pipfile.lock`
+      `pip install --require-hashes`. It installs the packages from
-
+      `Pipfile.lock` with `pipenv install --deploy`, plus `--dev` when the tests
-    It creates a virtual environment at `$HOME/.pipenv` with `python3 -m venv`
+      need the development packages. It installs no Python there, because the
-    when it is missing, then uses that environment's `pip` and `pipenv`. On a
+      tests use the base image's. The tests run after `ARG CACHEBUST`, and every
-    host, it first installs the distribution's python and venv packages when
+      other stage installs its Python packages after it, as in the Python `test`
-    they are missing. It installs pipenv and its dependencies by hash, with
+      phase example in `REPO_POLICIES.md`
    `pip install --require-hashes`. It installs the packages from `Pipfile.lock`
    with `pipenv install --deploy`, plus `--dev` when the tests need the
    development packages. It sets `PIP_ONLY_BINARY=:all:` for both installs, so
    a package with no wheel for the image stops the install. In that step it
    installs no Python, because a step above it already did. `Pipfile` names no
    `python_version`, because `--deploy` stops when the distribution's Python
    differs from it. The tests run after `ARG CACHEBUST`, and every other stage
    installs its Python packages after it, as in the Python `test` phase example
    in `REPO_POLICIES.md`
 - [ ] The gate phases invoke their tools directly, never through `make lint` or
      `script/test` — those are themselves a `docker build` and would recurse
      inside a build step
@@ -121,14 +111,13 @@ with your task.
    - that of a submodule keeping its own `.git` directory
    `git describe` does not need them, and each can hold a credential: a
-    password in a remote URL, or the token the CI checkout step stores there.
+    password in a remote URL, or the token the CI checkout step stores there. A
-    Some submodule names have a `config` segment, as in `config`,
+    submodule whose name has a `config` segment (`config`, `deploy/config`,
-    `deploy/config` or `config/lib`. Such a submodule loses its whole git
+    `config/lib`) loses its whole git directory to `**/.git/modules/**/config`,
-    directory to `**/.git/modules/**/config`, and Go's version stamping then
+    and Go's version stamping then fails the build. Give it a name without that
-    fails the build. Give it a name without that segment
+    segment (`git submodule add --name`). The stage that compiles has `git`: the
-    (`git submodule add --name`). The stage that compiles has `git`: the Debian
+    Debian Go image has it, and an alpine one needs `apk add --no-cache git`. It
-    Go image has it, and an alpine one needs `apk add --no-cache git`. That
+    takes the version from the `VERSION` build argument when one is given,
    stage 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
    - the tag, the number of commits since it and the short commit
@@ -164,39 +153,10 @@ with your task.
          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and,
          in the same commit, set the lint phase digest to the one named in the
          `.golangci.yml` paragraph of `REPO_POLICIES.md`)
-    - [ ] JS: `package.json`, `yarn.lock`, `.yarnrc.yml`, `.yarn/releases/`,
+    - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
-          `.gitattributes`, `.prettierrc`, `.prettierignore` (fetch the last two
+          (fetch from
-          from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc`
+          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc` and
-          and
+          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`)
          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`).
    - [ ] Any repository with `yarn.lock`: that file is in yarn 4's format. If
          its second line says `yarn lockfile v1`, convert it with the steps
          below. Do them in one commit with the re-vendored scripts, because
          yarn 1 ignores `--immutable` and exits 0 on a tree with no
          `.yarnrc.yml`. Run them with any distribution's node and yarn, and use
          `yarnpkg` on Debian and Ubuntu.
        1. Read the version from `yarnPath` in
           `https://git.eeqj.de/sneak/prompts/raw/branch/main/.yarnrc.yml`.
        2. Run `yarn set version <version>`. It writes
           `.yarn/releases/yarn-<version>.cjs`, `yarnPath` in `.yarnrc.yml`, and
           `packageManager` in `package.json`.
        3. Add `nodeLinker: node-modules` and `enableTelemetry: false` to
           `.yarnrc.yml`.
        4. Run `yarn install` once. It converts `yarn.lock`, and each package
           keeps its version and gains a `checksum`.
        5. Delete `approvedGitRepositories`, `enableScripts` and
           `npmMinimalAgeGate` from `.yarnrc.yml`. The conversion wrote them.
           They allow install scripts, any git repository and packages of any
           age, which yarn otherwise refuses.
        6. In `package.json`, name any package that must run its install script,
           as `"dependenciesMeta": { "<name>": { "built": true } }`, and run
           `yarn install` again.
        7. Add `.yarn/*` and `!.yarn/releases` above the secret patterns in
           `.gitignore` and `.dockerignore`. Docker obeys the last matching
           line, and the secret patterns must win. Add `.yarn/` to
           `.prettierignore`, and `.yarn/releases/** binary` to
           `.gitattributes`.
        8. Run `yarn install --immutable`. It must pass and change nothing.
    - [ ] Python: `pyproject.toml`
    - [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)
@@ -231,20 +191,13 @@ with your task.
      `docker build` in `script/`. Without the bootstrap the CI run dies in
      `script/fmt-check`, which runs the formatter on the host and finds nothing
      installed.
- [ ] `script/bootstrap` installs node, yarn and the node packages only when
+- [ ] `script/fmt` and `script/fmt-check` pick their `yarn` with the same test
-      `yarn.lock` is in the tree. node and yarn come from the distribution when
+      as `script/bootstrap`: the `yarn` on `PATH` when the node on `PATH` has
-      they are missing. It installs the node packages with
+      the pinned major version, and otherwise yarn under the pinned node, with
-      `yarn install --immutable`. The distribution's yarn only starts the
+      nvm loaded through `$HOME/.nvm/nvm.sh`. `script/bootstrap` leaves the node
-      release file that `yarnPath` in `.yarnrc.yml` names, and that file does
+      and yarn it installs under nvm off the `PATH` of the shell that called it,
-      the work.
+      so a bare `yarn` exits 127 on a runner carrying nothing but docker and
- [ ] A `Dockerfile` stage that needs yarn may start from any distribution that
+      git, or runs under another node.
      packages node and yarn. It copies `package.json`, `yarn.lock`,
      `.yarnrc.yml` and `.yarn/releases/` before it runs `script/bootstrap`. A
      stage that needs no yarn copies none of them.
 - [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
      whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
      neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
      saying to run `script/bootstrap`, and exit 1.
 - [ ] `script/bootstrap` installs no linter of its own — delete the block, its
      version variables and its call site. A JS repo's `yarn install` stays; it
      brings a linter along with every other dependency, and no verdict is taken
@@ -267,21 +220,13 @@ with your task.
 - [ ] Pre-commit hook is installed (`make hooks`)
 - [ ] No secrets in the repo (`.env`, keys, credentials)
- [ ] No mutable references (tags, `@latest`) to what the repo downloads and
+- [ ] No mutable references in Dockerfiles or scripts (tags, `@latest`) — all
-      installs itself in scripts and Dockerfiles — all pinned by cryptographic
+      pinned by cryptographic hash with version/date comment. The one exception
-      hash with version/date comment. Distribution packages are outside this
+      is a package from the distribution's own package index, which needs no
-      rule. They need no version and no hash, and updating and upgrading them is
+      version and no hash. Pulling that index is also allowed. In a
-      fine too. In a `Dockerfile`, the distribution is the pinned base image's.
+      `Dockerfile`, the distribution is the pinned base image's. On a host, it
-      On a host, it is the host's, and the host's package manager stands for it,
+      is the host's. A package source that a `Dockerfile` adds itself does not
-      nix and brew included. A package source that a `Dockerfile` adds itself is
+      get this exception
      not the distribution's own, so its packages are pinned
 - [ ] node, yarn, npm, python, pip and venv come from the distribution wherever
      possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the
      distribution's version is too old, use a newer distribution. node means
      the distribution's newest Node package, such as `nodejs-current` on Alpine
      3.24
 - [ ] yarn's release file is in git under `.yarn/releases/`, written once by
      `yarn set version` with an exact version (repositories with `yarn.lock`)
 - [ ] Using `yarn`, not `npm` (JS projects)
 # Directory Structure
@@ -310,12 +255,11 @@ with your task.
 # Final
 - [ ] `make check` passes
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has
-      That host is the runner image
+      (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker,
-      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
+      git and node 24, with no yarn on `PATH`), and demonstrably executed the
-      node 24. Take any yarn off `PATH` first. The run must show that the checks
+      checks — a sub-second build, or `CACHED` on a step that lints or tests,
-      executed. A sub-second build means nothing ran. So does `CACHED` on a step
+      one of the `RUN` steps below `ARG CACHEBUST`, means nothing ran. Above
      that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
      that line, these steps are expected to show `CACHED`:
    - the steps that install system packages
    - the steps that download Go's modules
@@ -1,6 +1,6 @@
 ---
 title: New Repo Checklist
-last_modified: 2026-11-06
+last_modified: 2026-11-03
 ---
 Use this checklist when creating a new repository from scratch. Follow the steps
@@ -82,13 +82,12 @@ Template files can be fetched from:
        `git describe` does not need them, and each can hold a credential: a
        password in a remote URL, or the token the CI checkout step stores
-        there. Some submodule names have a `config` segment, as in `config`,
+        there. A submodule whose name has a `config` segment (`config`,
-        `deploy/config` or `config/lib`. Such a submodule loses its whole git
+        `deploy/config`, `config/lib`) loses its whole git directory to
-        directory to `**/.git/modules/**/config`, and Go's version stamping then
+        `**/.git/modules/**/config`, and Go's version stamping then fails the
-        fails the build. Give it a name without that segment
+        build. Give it a name without that segment (`git submodule add --name`).
-        (`git submodule add --name`). The stage that compiles has `git`: the
+        The stage that compiles has `git`: the Debian Go image has it, and an
-        Debian Go image has it, and an alpine one needs
+        alpine one needs `apk add --no-cache git`. It takes the version from the
        `apk add --no-cache git`. That stage 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
@@ -123,14 +122,14 @@ Template files can be fetched from:
        - the step that runs `script/bootstrap` to install a Python `test`
          phase's packages from `Pipfile.lock`
    - A stage with none of these steps declares `ARG CACHEBUST` right after
-      `FROM`. A step that also installs anything else comes after
+      `FROM`. A step that installs anything else as well, such as a
-      `ARG CACHEBUST` too. A `script/bootstrap` that also installs node packages
+      `script/bootstrap` that also installs node packages, comes after it too.
-      is one. The `script/` builds pass a new `CACHEBUST` value on every build,
+      The `script/` builds pass a new `CACHEBUST` value on every build, which
-      which reruns every `RUN` step after that line and leaves the layers above
+      reruns every `RUN` step after that line and leaves the layers above it and
-      it and the cache mounts in place; `--no-cache` would build those layers
+      the cache mounts in place; `--no-cache` would build those layers again and
-      again and empty the mounts. A stage without the `ARG` line is served from
+      empty the mounts. A stage without the `ARG` line is served from cache on
-      cache on an unchanged tree, so the scripts and every stage's
+      an unchanged tree, so the scripts and every stage's `ARG CACHEBUST` line
-      `ARG CACHEBUST` line are added in the same commit.
+      are added in the same commit.
    - Go: each Go stage downloads the modules (`COPY go.mod go.sum ./`,
      `RUN go mod download`) above `ARG CACHEBUST`; the steps that compile
      (`golangci-lint run`, `go test`, `go build`) mount Go's build cache
@@ -143,26 +142,15 @@ Template files can be fetched from:
    - Python: a `test` phase that installs its packages from `Pipfile.lock` does
      it above `ARG CACHEBUST`, with `COPY script/ script/`,
      `COPY Pipfile Pipfile.lock ./` and `RUN script/bootstrap`. When
-      `script/bootstrap` runs in that step, it installs nothing beyond these:
+      `script/bootstrap` runs in that step, it installs nothing beyond system
-        - system packages
+      packages, pipenv and its dependencies, and the packages from
-        - pipenv and its dependencies
+      `Pipfile.lock`. It installs pipenv and its dependencies by hash, with
-        - the packages from `Pipfile.lock`
+      `pip install --require-hashes`. It installs the packages from
-
+      `Pipfile.lock` with `pipenv install --deploy`, plus `--dev` when the tests
-        It creates a virtual environment at `$HOME/.pipenv` with
+      need the development packages. It installs no Python there, because the
-        `python3 -m venv` when it is missing, then uses that environment's `pip`
+      tests use the base image's. The tests run after `ARG CACHEBUST`, and every
-        and `pipenv`. On a host, it first installs the distribution's python and
+      other stage installs its Python packages after it, as in the Python `test`
-        venv packages when they are missing. It installs pipenv and its
+      phase example in `REPO_POLICIES.md`
        dependencies by hash, with `pip install --require-hashes`. It installs
        the packages from `Pipfile.lock` with `pipenv install --deploy`, plus
        `--dev` when the tests need the development packages. It sets
        `PIP_ONLY_BINARY=:all:` for both installs, so a package with no wheel
        for the image stops the install. In that step it installs no Python,
        because a step above it already did. `Pipfile` names no
        `python_version`, because `--deploy` stops when the distribution's
        Python differs from it. The tests run after `ARG CACHEBUST`, and every
        other stage installs its Python packages after it, as in the Python
        `test` phase example in `REPO_POLICIES.md`
    - Server: the final stage builds and runs the application
    - Non-server: the final stage brings up the dev environment
    - Image pinned by sha256 hash with version/date comment
@@ -179,22 +167,7 @@ Template files can be fetched from:
          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml` and,
          in the same commit, set the lint phase digest to the one named in the
          `.golangci.yml` paragraph of `REPO_POLICIES.md`)
-    - [ ] JS, or any repository that runs prettier through yarn: make the first
+    - [ ] JS: `yarn init`, `yarn add --dev prettier`
          `yarn.lock` with the steps below. `script/bootstrap` installs no yarn
          until `yarn.lock` exists, so run them with any distribution's node and
          yarn, such as Alpine's (`apk add nodejs-current yarn`). Use `yarnpkg`
          on Debian and Ubuntu.
        1. Read the version from `yarnPath` in
           `https://git.eeqj.de/sneak/prompts/raw/branch/main/.yarnrc.yml`.
        2. Run `yarn set version <version>`. It writes
           `.yarn/releases/yarn-<version>.cjs`, `.yarnrc.yml` and
           `package.json`.
        3. Add `nodeLinker: node-modules` and `enableTelemetry: false` to
           `.yarnrc.yml`.
        4. Add `"private": true` to `package.json`.
        5. Run `yarn add --dev prettier`. It writes `yarn.lock`.
        6. Add `.yarn/releases/** binary` to `.gitattributes`.
        7. Run `yarn install --immutable`. It must pass and change nothing.
    - [ ] Python: `pyproject.toml`
 ## Configure script/ Entrypoints and Makefile
@@ -205,23 +178,14 @@ are thin shims calling them. Model scripts:
 - [ ] scripts are POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run on
      alpine images without bash
- [ ] `script/bootstrap` / `make bootstrap` installs all dependencies,
+- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies,
-      idempotently, and assumes nothing is present:
+      idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
-    - It detects the package manager: nix, apt, brew or apk.
+      node used if its major version is the pinned one, else pinned version via
-    - It installs node, yarn and the node packages only when `yarn.lock` is in
+      nvm from a hash-verified archive, with yarn and the packages installed
-      the tree. node and yarn come from that package manager when they are
+      under it; pinned yarn via corepack); a non-server repo's development
-      missing.
+      environment stage runs it instead of inline installs; a gate phase or the
-    - It installs the node packages with `yarn install --immutable`. The
+      build stage installs what its base image lacks either inline or by running
-      distribution's yarn only starts the release file that `yarnPath` in
+      it
      `.yarnrc.yml` names, and that file does the work.
    - A non-server repo's development environment stage runs it, with only
      system packages installed inline above it.
    - A gate phase or the build stage installs what its base image lacks, either
      inline or by running it.
 - [ ] A `Dockerfile` stage that needs yarn may start from any distribution that
      packages node and yarn. It copies `package.json`, `yarn.lock`,
      `.yarnrc.yml` and `.yarn/releases/` before it runs `script/bootstrap`. A
      stage that needs no yarn copies none of them.
 - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
      then `install-precommit`, plus repo-specific init
 - [ ] `script/test` / `make test` —
@@ -251,10 +215,13 @@ are thin shims calling them. Model scripts:
      from `script/projectname`, each assigned on its own line before the build.
      The bootstrap is required: CI checks out and runs this alone, and
      `script/fmt-check` runs the formatter on the host.
- [ ] `script/bootstrap`, `script/fmt` and `script/fmt-check` run yarn by
+- [ ] `script/fmt` and `script/fmt-check` pick their `yarn` with the same test
-      whichever name is present: `yarn`, or `yarnpkg` on Debian and Ubuntu. With
+      as `script/bootstrap`: the `yarn` on `PATH` when the node on `PATH` has
-      neither name on `PATH`, `script/fmt` and `script/fmt-check` print one line
+      the pinned major version, and otherwise yarn under the pinned node, with
-      saying to run `script/bootstrap`, and exit 1.
+      nvm loaded through `$HOME/.nvm/nvm.sh`. `script/bootstrap` leaves the node
      and yarn it installs under nvm off the `PATH` of the shell that called it,
      so a bare `yarn` exits 127 on a runner carrying nothing but docker and
      git, or runs under another node.
 - [ ] No `docker build` in `script/` leaves a dangling image behind:
      `script/lint` and `script/test` write no image, and `script/docker` and
      `script/cibuild` tag theirs
@@ -269,12 +236,11 @@ are thin shims calling them. Model scripts:
 - [ ] `make check` passes
 - [ ] `make docker` succeeds
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has
-      That host is the runner image
+      (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker,
-      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
+      git and node 24, with no yarn on `PATH`), and demonstrably executed the
-      node 24. Take any yarn off `PATH` first. The run must show that the checks
+      checks — a sub-second build, or `CACHED` on a step that lints or tests,
-      executed. A sub-second build means nothing ran. So does `CACHED` on a step
+      one of the `RUN` steps below `ARG CACHEBUST`, means nothing ran. Above
      that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
      that line, these steps are expected to show `CACHED`:
    - the steps that install system packages
    - the steps that download Go's modules
@@ -285,20 +251,11 @@ are thin shims calling them. Model scripts:
      final stage is missing its `COPY --from=` edge to the gate phases.
 - [ ] No secrets in repo, and none in the build context: enumerate a probe image
      rather than reading `.dockerignore`
- [ ] No mutable references to what the repo downloads and installs itself in
+- [ ] No mutable image/package references. The one exception is a package from
-      scripts and Dockerfiles. Distribution packages are outside this rule. They
+      the distribution's own package index, which needs no version and no hash.
-      need no version and no hash, and updating and upgrading them is fine too.
+      Pulling that index is also allowed. In a `Dockerfile`, the distribution is
-      In a `Dockerfile`, the distribution is the pinned base image's. On a host,
+      the pinned base image's. On a host, it is the host's. A package source
-      it is the host's, and the host's package manager stands for it, nix and
+      that a `Dockerfile` adds itself does not get this exception
      brew included. A package source that a `Dockerfile` adds itself is not the
      distribution's own, so its packages are pinned
 - [ ] node, yarn, npm, python, pip and venv come from the distribution wherever
      possible, never from nvm, pyenv, corepack or `npm install -g yarn`. If the
      distribution's version is too old, use a newer distribution. node means
      the distribution's newest Node package, such as `nodejs-current` on Alpine
      3.24
 - [ ] yarn's release file is in git under `.yarn/releases/`, written once by
      `yarn set version` with an exact version (repositories with `yarn.lock`)
 - [ ] No unnecessary files in repo root
 - [ ] All dates written as YYYY-MM-DD
@@ -1,6 +1,6 @@
 ---
 title: Repository Policies
-last_modified: 2026-11-06
+last_modified: 2026-11-03
 ---
 This document covers repository structure, tooling, and workflow standards. Code
@@ -16,73 +16,51 @@ style conventions are in separate documents:
 ---
- Cross-project documentation (such as this file) must include
+- Cross-project documentation, such as this file, must include
-  `last_modified: YYYY-MM-DD` in the YAML front matter so it can be kept in sync
+  `last_modified: YYYY-MM-DD` in its YAML front matter. The date is how a copy
-  with the authoritative source as policies evolve.
+  is kept in sync with the authoritative source as policies evolve.
 - **External references must be pinned by cryptographic hash.** This is the
-  single most important rule in this document. It covers what we download and
+  single most important rule in this document. It covers everything fetched from
-  install ourselves in scripts and Dockerfiles:
+  a remote source, including:
    - Docker base images
    - Go modules
    - Python packages from PyPI
    - npm packages
    - GitHub Actions
    - release archives fetched with `curl` or `wget`
    Packages from the distribution's own package manager are outside this rule.
    They need no version and no hash, because the distribution is trusted. In a
    `Dockerfile`, it is the pinned base image's distribution. On a host, it is
    the host's. The host's package manager stands for its distribution, and that
    includes nix and brew. Updating the package index and upgrading installed
    packages are fine too. This command, for example, is allowed:
    ```sh
    apt update && apt upgrade -y && apt install -y build-essential
    ```
    A package source that a `Dockerfile` adds itself is not the distribution's
    own, so its packages are pinned like any other download.
    A version tag such as `@v4`, `@latest` or `:3.21` is server-mutable, and
    therefore a remote code execution vulnerability. Reference an external
    dependency by its content hash:
    - Docker: `@sha256:...`
    - Go: the module hash in `go.sum`
-    - Python: the package hash in `Pipfile.lock`
+    - npm: the integrity hash in the lockfile
    - npm: the `checksum` in `yarn.lock`
    - GitHub Actions: `@<commit-sha>`
-    This also means never `curl | bash` to install a tool such as rustup.
+    This also means never `curl | bash` to install tools like pyenv, nvm,
-    Instead, download a specific release archive from GitHub, verify its hash,
+    rustup, etc. Instead, download a specific release archive from GitHub,
-    and only then install. The hash is hardcoded in the Dockerfile or script.
+    verify its hash, and only then install. The hash is hardcoded in the
-    Unverified install scripts are arbitrary remote code execution. Double-check
+    Dockerfile or script. Unverified install scripts are arbitrary remote code
-    every external reference in every file before committing.
+    execution. Double-check every external reference in every file before
    committing.
-    These come from the distribution wherever possible:
+    There is one exception: a package from the distribution's own package index
-    - node, meaning the distribution's newest Node package, such as
+    needs no version and no hash. Pulling that index is also allowed. The
-      `nodejs-current` on Alpine 3.24
+    distribution is trusted. In a `Dockerfile`, it is the pinned base image's
-    - yarn
+    distribution. On a host, it is the host's. These commands are examples:
-    - npm
+    - `apt-get update`
-    - python
+    - `apt-get install`
-    - pip and venv, the installer tools bundled with python
+    - `apk update`
-
+    - `apk add`
    If the distribution's version is too old, use a newer distribution, never a
    download. That rules out all of these:
    - nvm
    - pyenv
    - corepack
    - `npm install -g yarn`
    yarn's release file is third-party code, and git pins it. `yarn set version`
    writes it to `.yarn/releases/` once, given an exact version.
    These are not trusted, so everything from them stays pinned by hash:
    - Docker Hub
    - PyPI
-    - the npm registry
+    - npm
    - `go get`
    A package source that a `Dockerfile` adds itself is not the distribution's
    own, so the exception does not cover it.
 - Every repo with software must have a root `Makefile` with these targets:
    - `make bootstrap`
    - `make setup`
@@ -110,10 +88,10 @@ style conventions are in separate documents:
    - `script/check`
    - `script/docker`
-    The scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they
+    The scripts must be POSIX sh: `#!/bin/sh`, `set -eu`, no bashisms. That is
-    run in minimal containers; alpine images, for example, have no bash. Locate
+    so they run in minimal containers; alpine images, for example, have no bash.
-    the repo root with `$(cd "$(dirname "$0")/.." && pwd -P)`, and `cd` there
+    Locate the repo root with `$(cd "$(dirname "$0")/.." && pwd -P)`, and `cd`
-    before acting.
+    there before acting.
    From the standard's canonical set we use `bootstrap`, `setup`, `test`, and
    `cibuild`. `setup` makes the repo ready for development after a fresh clone:
@@ -121,66 +99,35 @@ style conventions are in separate documents:
    initialization.
    `script/bootstrap` installs all dependencies idempotently and assumes
-    nothing is present. Base tools, node and yarn come from nix, apt, brew, or
+    nothing is present. Base tools come from nix, apt, brew, or apk, detected in
-    apk, detected in that order; apt runs noninteractive. Each one is installed
+    that order; apt runs noninteractive. For node it uses the installed node
-    only when it is missing. A tool from outside the distribution is never
+    only when its major version is the pinned one. When node is missing or has
-    installed as "latest" or "lts"; it is always an exact version.
+    another major, it installs the PINNED node version via nvm, and installs
    yarn and the packages under it. The node 24 the CI runner image ships is one
    such other major. nvm itself is installed first if missing, from a
    hash-verified GitHub release archive, never `curl | sh`. bash is installed
    as an explicit prerequisite, since nvm requires bash. Only the major version
    is compared, for two reasons. The `Dockerfile` stages start from a node
    image whose exact version is not the pin, and nvm cannot install a prebuilt
    node on alpine. yarn is pinned via
    `corepack prepare yarn@<version> --activate`. Never install "latest" or
    "lts"; always exact versions.
-    `script/bootstrap` installs node, yarn and the node packages only when
+    `script/cibuild` runs the CI build, and the Gitea workflow calls it. It
-    `yarn.lock` is in the tree. With no `yarn.lock`, it installs no node and no
+    changes to the repo root, runs `script/bootstrap`, runs `script/check`, and
-    yarn. It installs the node packages with `yarn install --immutable`. That
+    builds the image with the version. **`script/cibuild` runs
-    install fails when a package's `checksum` is wrong, or when `package.json`
+    `script/bootstrap` first.** The workflow checks out the repo and runs
-    is out of step with `yarn.lock`.
+    nothing else, while `script/fmt-check` runs the formatter on the host.
-
+    Without the bootstrap, on a pristine checkout with nothing installed, the
-    Each repository commits the yarn that runs. `yarnPath` in `.yarnrc.yml`
+    run dies there, after the containerised gates have passed. **The bootstrap
-    points at the release file in `.yarn/releases/`. The distribution's yarn
+    alone is not enough.** When `script/bootstrap` installs node and yarn under
-    only starts that file, and that file does the work. Alpine packages yarn 1,
+    nvm, it leaves neither on the `PATH` of the shell that called it. A bare
-    and Debian 13 packages yarn 4.1. The same committed yarn does the work on
+    `yarn` then either exits 127 or runs under another node. The host
-    both. Corepack never runs, and no yarn is downloaded.
+    entrypoints that need yarn, `script/fmt` and `script/fmt-check`, therefore
-
+    use the same test as `script/bootstrap`. When the node on `PATH` has the
-    `.yarnrc.yml` holds these settings:
+    pinned major version, they run the `yarn` on `PATH`. Otherwise they load nvm
-    - `yarnPath`
+    through `$HOME/.nvm/nvm.sh` and run yarn under the pinned node. A runner
-    - `nodeLinker: node-modules`
+    carrying nothing but docker and git then gets through `script/check`.
    - `enableTelemetry: false`, because yarn otherwise sends usage reports from
      any host that is not CI
    By default, yarn runs no dependency's install script. A dependency that must
    run one is named in `package.json`, as
    `"dependenciesMeta": { "<name>": { "built": true } }`.
    `.gitattributes` carries `.yarn/releases/** binary`, so diffs and merges
    treat the release file as one opaque file.
    yarn 1 ignores `--immutable` and exits 0, so on a tree with no `.yarnrc.yml`
    the install is not frozen. A repository therefore re-vendors
    `script/bootstrap` and converts its `yarn.lock` in one commit.
    Debian and Ubuntu name the yarn command `yarnpkg`. `script/bootstrap`,
    `script/fmt` and `script/fmt-check` each carry the same small function that
    runs whichever name is present. With neither name on `PATH`, `script/fmt`
    and `script/fmt-check` print one line saying to run `script/bootstrap`, and
    exit 1.
    A `Dockerfile` stage that needs yarn may start from any distribution that
    packages node and yarn. It copies all of these before it runs
    `script/bootstrap`:
    - `package.json`
    - `yarn.lock`
    - `.yarnrc.yml`
    - `.yarn/releases/`
    With only `package.json` and `yarn.lock`, the install fails. Alpine's yarn 1
    then says to enable corepack; never do that, and copy the missing files
    instead. The Python and Go stages below need no yarn and copy no
    `yarn.lock`, so `script/bootstrap` installs no node and no yarn there.
    `script/cibuild` runs the CI build, and the Gitea workflow calls it. The
    script changes to the repo root, runs `script/bootstrap`, runs
    `script/check`, and builds the image with the version. **`script/cibuild`
    runs `script/bootstrap` first**, because the workflow checks out the repo
    and runs nothing else, while `script/fmt-check` runs the formatter on the
    host. On a pristine checkout with nothing installed, the run dies there,
    after the containerised gates have passed.
    Four further scripts are our own extensions to the standard:
    - `script/check` runs `script/test`, `script/lint` and `script/fmt-check`.
@@ -200,16 +147,9 @@ style conventions are in separate documents:
    README must document the provided scripts in an **Entrypoints** section (see
    the README requirements below).
- Run the repo's own entrypoints, never the underlying tools directly. The
+- Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.)
-  `script/` scripts are the single source of truth for how each operation runs.
+  instead of invoking the underlying tools directly. The Makefile is the single
-  Calling them directly is fine, and so is calling the Makefile targets. The
+  source of truth for how these operations are run.
  Makefile targets must still exist, as the thin shims described above.
    An agent whose work is confined to one package may run `go test` directly on
    that package's suite, or on individual tests in it, while iterating. This is
    the only exception to this rule. `go build`, `go vet` and the linter still
    go through the entrypoints. A run while iterating is not a gate, so the full
    `make check` is still required before every push.
 - The Makefile is authoritative documentation for how the repo is used. Beyond
  the required targets above, it should have targets for every common operation:
@@ -230,22 +170,20 @@ style conventions are in separate documents:
  cannot be built unless they pass. For non-server repos the final stage brings
  up a development environment; for server repos it is the runtime image. The
  gate phases and the build stage start from their pinned base images and
-  install what those images lack in either of these ways:
+  install what those images lack. They do that in one of two ways:
    - inline, as the canonical Go `Dockerfile` below does for `git`
    - by running `script/bootstrap`, as the `prompts` repo's own `Dockerfile`
      does for its yarn packages
    The development environment stage installs development prerequisites by
-    running `script/bootstrap`. Only system packages may be installed inline
+    running `script/bootstrap` rather than duplicating its installs inline. A
-    above it, so that check builds keep them; the `prompts` repo's own
+    stage that runs `script/bootstrap` COPYs `script/` and the dependency
-    `Dockerfile` does this. A stage that runs `script/bootstrap` COPYs `script/`
+    manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before
-    and the dependency manifests it needs before running it. These are examples:
+    running it.
    - `package.json`, `yarn.lock`, `.yarnrc.yml` and `.yarn/releases/`
    - `go.mod` and `go.sum`
- **The lint and test gates run in Docker, as phases of the `Dockerfile`.**
+- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
-  There is no separate lint file. `script/lint` and `script/test` each build one
+  no separate lint file. `script/lint` and `script/test` each build one phase
-  phase and nothing else:
+  and nothing else:
    ```sh
    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
@@ -256,9 +194,9 @@ style conventions are in separate documents:
    **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
+    two gates are always invoked by name here. It is also why the final stage
-    `COPY --from=` of a harmless file from each of them. Without that
+    carries a `COPY --from=` of a harmless file from each of them. Without that
-    dependency, a plain `docker build .` builds the last stage alone and exits 0
+    edge, a plain `docker build .` builds the last stage alone and exits 0
    having linted and tested nothing.
    **The gate builds write no image.** With `--output type=cacheonly` the phase
@@ -267,12 +205,12 @@ style conventions are in separate documents:
    image holds the toolchain. A build given neither `--output` nor `-t` writes
    an untagged image and leaves it dangling, on every developer host and every
    CI runner. `script/cibuild` and `script/docker` build the image that ships
-    and tag it, so each build replaces the previous image. Each script assigns
+    and tag it, so each build replaces the previous image. Each assigns the tag
-    the tag on its own line before the build, so `set -e` stops it where
+    on its own line before the build, so `set -e` stops it where
    `script/projectname` fails.
    Inside a phase the tool is invoked directly: `golangci-lint`, `go test`,
-    `eslint`, `prettier`. The tool is never invoked through `make lint` or
+    `eslint`, `prettier`. It is never invoked through `make lint` or
    `script/test`. Those 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
@@ -286,11 +224,9 @@ style conventions are in separate documents:
    caller cannot tell from real findings. Both have produced wrong verdicts in
    this org, in both directions. A container has its own `TMPDIR`, so the lock
    is out of reach. The lint phase does keep golangci-lint's cache between
-    check builds (below), but it lints every checkout at `/src`. A finding is
+    check builds (below). But it lints every checkout at `/src`, and a finding
-    taken from that cache only when all of these are the same:
+    is taken from that cache only for the same files, settings and golangci-lint
-    - the files
+    version.
    - the settings
    - the golangci-lint version
 - **Any build that runs checks is given a new `CACHEBUST` value.** Docker
  invalidates a `COPY` layer only when the copied content changes. On an
@@ -298,7 +234,8 @@ style conventions are in separate documents:
  executes, and the build still exits 0. Every `docker build` in `script/`
  therefore passes `--build-arg CACHEBUST="$(date +%s)-$$"`, the time and the
  script's process id. So no two builds share a value, not even the three in one
-  `script/cibuild`. Four scripts do this, and there is no fifth:
+  `script/cibuild`. The scripts that run `docker build` are these four, and
  there is no fifth:
    - `script/lint`
    - `script/test`
    - `script/cibuild`
@@ -314,17 +251,13 @@ style conventions are in separate documents:
      packages from `Pipfile.lock`
    A stage with none of these steps declares `ARG CACHEBUST` right after
-    `FROM`. A step that also installs anything else comes after `ARG CACHEBUST`
+    `FROM`. A step that installs anything else as well, such as a
-    too. A `script/bootstrap` that also installs node packages is one. A new
+    `script/bootstrap` that also installs node packages, comes after it too. A
-    value reruns every `RUN` step after that line; `COPY` steps are compared by
+    new value reruns every `RUN` step after that line; `COPY` steps are compared
-    content and need nothing. Docker keeps the layers above the line until one
+    by content and need nothing. Docker keeps the layers above the line until
-    of these changes:
+    the base image, their own lines or the files they copy change. A stage
-    - the base image
+    without the `ARG` line is served from cache on an unchanged tree, so a
-    - their own lines
+    repository re-vendors the scripts and adds the `ARG` lines in one commit.
    - the files they copy
    A stage without the `ARG` line is served from cache on an unchanged tree, so
    a repository re-vendors the scripts and adds the `ARG` lines in one commit.
    The scripts do not pass `--no-cache`. That flag reruns every step too, but
    it also builds the layers above the line again and empties every cache
    mount. Go's build cache and golangci-lint's would then start empty every
@@ -333,19 +266,14 @@ style conventions are in separate documents:
    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. When a check is added
-    or changed, prove it works:
+    or changed, prove it works: plant a defect it must catch, watch the run fail
-    - plant a defect it must catch
+    on it, then revert the defect. A green run alone shows neither that the
-    - watch the run fail on it
+    check ran nor that it covers what it should.
    - revert the defect
    A green run alone shows neither that the check ran nor that it covers what
    it should.
 - **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
+  The lint phase is based on the `golangci/golangci-lint` image, pinned by hash,
-  hash), so lint failures surface in seconds rather than after a full compile.
+  so lint failures surface in seconds rather than after a full compile. The test
-  The test phase is based on the Debian Go image. The canonical Go repo
+  phase is based on the Debian Go image. The canonical Go repo `Dockerfile`:
  `Dockerfile`:
    ```dockerfile
    # In every stage ARG CACHEBUST comes right after the steps that install
@@ -439,22 +367,22 @@ style conventions are in separate documents:
    - The lint phase uses the `golangci/golangci-lint` image directly, so
      nothing needs installing: it has both Go and the linter.
    - `COPY --from=<phase> /src/go.sum /dev/null` is a no-op copy whose only
-      purpose is the dependency on that phase. BuildKit runs stages in parallel
+      purpose is the ordering edge. BuildKit runs stages in parallel by default,
-      by default, and a stage nothing depends on is not built at all. Without
+      and a stage nothing depends on is not built at all. Without these two
-      these two lines a red gate would not fail the build.
+      lines a red gate would not fail the build.
    - Keep the runtime stage last. If you add a stage after it, give it the same
-      two copies. A plain `docker build .` builds the last stage's chain and
+      two copies: a plain `docker build .` builds the last stage's chain and
      nothing else.
    - Check builds keep these, and none of them can hand back a stale result:
        - The layers above `ARG CACHEBUST`: the system packages and Go's
          modules. Docker installs the packages again when the base image or the
-          install line changes. Docker downloads the modules again when `go.mod`
+          install line changes. It downloads the modules again when `go.mod` or
-          or `go.sum` changes. Go checks every module against `go.sum` as it
+          `go.sum` changes. Go checks every module against `go.sum` as it
          downloads it, and no later build can change a kept layer. The modules
-          are kept in a layer rather than a cache mount. A cache mount is shared
+          are kept in a layer rather than a cache mount, for two reasons. A
-          by every build on the host, and Go builds from whatever files the
+          cache mount is shared by every build on the host. And Go builds from
-          mount holds without checking them again (only `go mod verify` does). A
+          whatever files it holds without checking them again (only
-          file changed there would go unnoticed.
+          `go mod verify` does), so a file changed there would go unnoticed.
        - Go's build cache (`/root/.cache/go-build`, where Go keeps it for
          root), mounted on the steps that compile: `golangci-lint run`, both
          `go test` runs and `go build`. Go reuses a compiled package only when
@@ -503,13 +431,12 @@ style conventions are in separate documents:
        `git describe` does not need them, and each can hold a credential: a
        password in a remote URL, or the token the CI checkout step stores
-        there. Some submodule names have a `config` segment, as in `config`,
+        there. A submodule whose name has a `config` segment (`config`,
-        `deploy/config` or `config/lib`. Such a submodule loses its whole git
+        `deploy/config`, `config/lib`) loses its whole git directory to
-        directory to `**/.git/modules/**/config`, and Go's version stamping then
+        `**/.git/modules/**/config`, and Go's version stamping then fails the
-        fails the build. Give it a name without that segment
+        build. Give it a name without that segment (`git submodule add --name`).
-        (`git submodule add --name`). The stage that compiles has `git`: the
+        The stage that compiles has `git`: the Debian Go image has it, and an
-        Debian Go image has it, and an alpine one needs
+        alpine one needs `apk add --no-cache git`. It takes the version from the
        `apk add --no-cache git`. That stage 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
@@ -549,91 +476,48 @@ style conventions are in separate documents:
    The tests run after `ARG CACHEBUST`, on every check build. In every other
    stage, a step that installs Python packages comes after `ARG CACHEBUST`.
    - When `script/bootstrap` runs in that step, it installs nothing beyond
-      these:
+      system packages, pipenv and its dependencies, and the packages from
-        - system packages
+      `Pipfile.lock`. It installs no Python there: the tests use the base
-        - pipenv and its dependencies
+      image's Python, which the image's hash pins. If it installs anything else
-        - the packages from `Pipfile.lock`
+      there, the step goes after `ARG CACHEBUST`.
        `script/bootstrap` installs no Python there: the tests use the
        distribution's Python, which a step above it installs. If it installs
        anything else there, the step goes after `ARG CACHEBUST`.
    - Debian's Python refuses a system-wide `pip install`, so pipenv goes in a
      virtual environment at `$HOME/.pipenv`. `script/bootstrap` creates it with
      `python3 -m venv` when it is missing, then uses that environment's `pip`
      and `pipenv`. On a host, it first installs the distribution's python and
      venv packages when they are missing. One script then works on a host and
      in a `Dockerfile`. `Pipfile` names no `python_version`, because
      `pipenv install --deploy` stops when the distribution's Python differs
      from it.
    - PyPI is not trusted, so `script/bootstrap` installs pipenv and its
      dependencies by hash. It does so with `pip install --require-hashes -r`
      and a requirements file in `script/` that lists each of them with `==` and
      its `--hash`. pip refuses to install a dependency the file does not list.
-    - `script/bootstrap` then runs `pipenv install --deploy`, with `--dev` when
+    - It then runs `pipenv install --deploy`, with `--dev` when the tests need
-      the tests need the development packages. `--deploy` does all of these:
+      the development packages. `--deploy` installs only what `Pipfile.lock`
-        - installs only what `Pipfile.lock` names
+      names, checks every package against the lockfile's hashes, and fails when
-        - checks every package against the lockfile's hashes
+      the lockfile is out of date with `Pipfile`.
-        - fails when the lockfile is out of date with `Pipfile`
+    - A kept layer holds nothing a new install would refuse: pip checked pipenv
-    - `script/bootstrap` sets `PIP_ONLY_BINARY=:all:` for both installs, and
+      and its dependencies, and pipenv checked the lockfile's packages, against
-      pipenv passes it on to pip. A package with no ready-built wheel for the
+      their hashes. pipenv creates its virtual environment with the `virtualenv`
-      image then stops the install. Without the setting, pip builds that package
+      package. The packages that `virtualenv` adds come from wheels inside that
-      from source and downloads the build tools without a hash check.
+      package, so the hash pip checked for it covers them. Two things in the
-    - A kept layer holds nothing a new install would refuse: pip checked the
+      layer are not fixed by a hash:
-      hashes of pipenv and its dependencies, and pipenv checked the hashes of
+        - A package with no ready-built wheel for the image is built from
-      the lockfile's packages. pipenv creates its virtual environment with the
+          source. pip downloads the build tools without a hash check, so a kept
-      `virtualenv` package. The packages that `virtualenv` adds come from wheels
+          layer's build of such a package may differ from a new one.
-      inside that package, so the hash pip checked for it covers them. System
+        - System packages keep the versions the package manager gave when the
-      packages, Python among them, are not fixed by a hash. They keep the
+          layer was built; a new install may get newer ones.
      versions the package manager gave when the layer was built; a new install
      may get newer ones.
    - As with Go's modules, the packages are kept in a layer, not a cache mount.
      A cache mount is shared by every build on the host, and nothing checks its
      files again.
-    A Python repository's `script/bootstrap` adds these lines in `main`, above
+    In this example, `script/bootstrap` finds `make` and `git` already
-    the last `echo`. The `ensurepip` test fails when python is missing, and also
+    installed, installs pipenv and its dependencies by hash, and runs
-    when Debian's venv package is missing:
+    `pipenv install --dev --deploy`:
    ```sh
    if [ ! -x "$HOME/.pipenv/bin/pip" ]; then
        if ! python3 -m ensurepip --version >/dev/null 2>&1; then
            pkg_install python3 python3-venv python3 python3
        fi
        python3 -m venv "$HOME/.pipenv"
    fi
    export PIP_ONLY_BINARY=:all:
    "$HOME/.pipenv/bin/pip" install --require-hashes -r script/requirements.txt
    "$HOME/.pipenv/bin/pipenv" install --dev --deploy
    ```
    Make `script/requirements.txt` once, with
    `echo pipenv | pip-compile --generate-hashes --allow-unsafe -o script/requirements.txt -`.
    `pip-compile` comes from Alpine's `py3-pip-tools` package; Debian and Ubuntu
    do not package `pip-tools`. Make the first `Pipfile.lock` with
    `$HOME/.pipenv/bin/pipenv lock`, after the `pip install` line has installed
    pipenv.
    In the example below, `script/bootstrap` finds `make`, `git`, python and
    venv already installed. The example copies no `yarn.lock`, so
    `script/bootstrap` installs no node and no yarn.
    ```dockerfile
    # Test phase. Both pytest runs share one 90-second timeout, so a hang
    # uses it once and gets no rerun.
-    # debian:trixie-slim, YYYY-MM-DD
+    # python:3.x-slim, YYYY-MM-DD
-    FROM debian@sha256:... AS test
+    FROM python@sha256:... AS test
-    # Python, pip and venv come from the distribution, which is trusted, so
+    # make and git are base tools that script/bootstrap installs when they
-    # they need no version and no hash. make and git are base tools that
+    # are missing. Installed here, they stay in their own layer when
-    # script/bootstrap installs when they are missing. Installed here, they
+    # script/ changes.
    # stay in their own layer when script/ changes.
    RUN apt-get update \
-        && apt-get install -y --no-install-recommends ca-certificates make git \
+        && apt-get install -y --no-install-recommends make git \
            python3 python3-venv \
        && rm -rf /var/lib/apt/lists/*
    # script/bootstrap installs pipenv in a virtual environment at
    # $HOME/.pipenv, and the tests below run that pipenv.
    ENV PATH=/root/.pipenv/bin:$PATH
    WORKDIR /app
    COPY script/ script/
    COPY Pipfile Pipfile.lock ./
@@ -646,12 +530,12 @@ style conventions are in separate documents:
    ```
 - Every repo should have a Gitea Actions workflow (`.gitea/workflows/`) that
-  runs `script/cibuild` on push. The workflow's only other step checks out the
+  runs `script/cibuild` on push. Its only other step checks out the repo, with
-  repo, with `persist-credentials: false`. `script/cibuild` needs no token, and
+  `persist-credentials: false`. `script/cibuild` needs no token, and without
-  without that setting the checkout leaves the job's token in `.git/config` for
+  that setting the checkout leaves the job's token in `.git/config` for every
-  every later step. The checkout step also sets `fetch-depth: 0`, which fetches
+  later step. The checkout step also sets `fetch-depth: 0`, which fetches the
-  the tags `git describe` needs. By default it clones shallow with no tags, and
+  tags `git describe` needs. By default it clones shallow with no tags, and a
-  a tagged repository's CI build would stamp a bare short commit id. The
+  tagged repository's CI build would stamp a bare short commit id. The
  workflow's `concurrency` block groups runs by workflow and branch
  (`${{ github.workflow }}-${{ github.ref }}`) with `cancel-in-progress: true`.
  A new push then cancels the older run on the same branch, queued or running,
@@ -665,7 +549,7 @@ style conventions are in separate documents:
  entry. The `check` job sets `timeout-minutes: 20`, so a hung build frees the
  shared runner after 20 minutes. That allows for the three Docker builds
  described above, each held to the 5-minute Docker build limit below, plus the
-  bootstrap. Those builds are the test phase, the lint phase, then the image. A
+  bootstrap. The three are the test phase, the lint phase, then the image. A
  separate workflow limited to `main` by a `branches` list under `on: push`
  cannot be checked by review. To try a change to it, add the feature branch to
  that list and push, then remove the branch from the list again before merging.
@@ -759,25 +643,25 @@ style conventions are in separate documents:
    passing result in its cache directory (`GOCACHE`). When the same tests run
    again on unchanged code, it prints that result, marked `(cached)`, without
    running them. The directory lasts from one run to the next on a developer's
-    machine, where this target runs. The directory also lasts in the `test`
+    machine, where this target runs. It also lasts in the `test` phase of the
-    phase of the `Dockerfile`, which mounts it to keep compiled packages between
+    `Dockerfile`, which mounts it to keep compiled packages between check
-    check builds, so the phase's `go test` runs carry `-count=1` too. A new
+    builds, so the phase's `go test` runs carry `-count=1` too. A new
    `CACHEBUST` value (above) is what makes that step run on an unchanged tree.
    Python example:
    ```makefile
    test:
-    	@timeout 90 sh -c 'pipenv run pytest || { \
+    	@timeout 90 sh -c 'python -m pytest || { \
    		echo "--- Rerunning with -v for details ---"; \
-    		pipenv run pytest -v; exit 1; }'
+    		python -m pytest -v; exit 1; }'
    ```
    Both pytest runs share that one 90-second timeout, as in the `Dockerfile`
    example above, so a hang uses it once and gets no rerun. Ctrl-C does not
    stop a running `make test`, which goes on until the tests end or the 90
    seconds run out. On a Mac without `timeout`, the target fails until it is
-    installed. On a host, the target needs `$HOME/.pipenv/bin` on `PATH`.
+    installed.
    The `exit 1` ensures the target always fails after a rerun. The first run
    already proved the tests are broken, so the build must not pass even if a
@@ -801,7 +685,6 @@ style conventions are in separate documents:
    - editor files (`.swp`, `*~`)
    - in-repo agent scratch directories (`.claude/`)
    - `node_modules/`
    - `.yarn/*`, with `!.yarn/releases` so that git keeps yarn's release file
    - the repo's own build outputs
    Fetch the standard `.gitignore` from
@@ -820,19 +703,19 @@ style conventions are in separate documents:
  the build-context root. A `.dockerignore` listing `.env`, `*.pem` and `*.key`
  therefore excludes only the copies at the repository root. `config/.env` and
  `certs/server.key` still reach the context and can land in an image layer.
-  Such a `.dockerignore` is more dangerous than a short file with no secret
+  That is more dangerous than a short file with no secret patterns at all,
-  patterns at all, because it reads as solved and stops anyone looking. Give
+  because it reads as solved and stops anyone looking. Give every
-  every depth-independent pattern the `**/` prefix, and leave only genuinely
+  depth-independent pattern the `**/` prefix, and leave only genuinely
-  root-anchored entries unprefixed. Those are `.claude`, `.yarn/*`,
+  root-anchored entries unprefixed. Those are `.claude`, and the repo's own
-  `!.yarn/releases`, and the repo's own host-built binary. The binary is written
+  host-built binary. The binary is written `/myapp` and never `**/myapp`, which
-  `/myapp` and never `**/myapp`, which would also match `cmd/myapp/` and delete
+  would also match `cmd/myapp/` and delete the package directory from the
-  the package directory from the context. Matching is case-sensitive, and an
+  context. Matching is case-sensitive, and an ALL-CAPS twin per pattern still
-  all-caps copy of each pattern still misses `Server.Key`. So secret names use
+  misses `Server.Key`. So secret names use character ranges:
-  character ranges: `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`, and likewise for
+  `**/*.[kK][eE][yY]`, `**/*.[pP][eE][mM]`, and likewise for `.envrc` and the
-  `.envrc` and the extensionless SSH keys. Where such a pattern also catches
+  extensionless SSH keys. Where such a pattern also catches something the build
-  something the build needs, re-include it with a negation
+  needs, re-include it with a negation (`!docs/example.env`). Deleting the
-  (`!docs/example.env`). Deleting the pattern reopens the exposure for every
+  pattern reopens the exposure for every other file it covers. Fetch the
-  other file it covers. Fetch the standard `.dockerignore` from
+  standard `.dockerignore` from
  `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore` and extend
  it with the repo's own artifacts.
@@ -843,12 +726,11 @@ style conventions are in separate documents:
  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. The canonical
+  that name from the build. Anchoring carries a known gap, which the canonical
-  `.dockerignore` states the gap in its own comment, since consuming repos
+  `.dockerignore` states in its own comment, since consuming repos receive the
-  receive the file and not the tracker. The gap is that the directory is created
+  file and not the tracker. The directory is created in the agent's working
-  in the agent's working directory. A repo running agents in subdirectories
+  directory, so a repo running agents in subdirectories still ships
-  therefore still ships `services/api/.claude/` and must add its own anchored
+  `services/api/.claude/` and must add its own anchored entry there.
  entry there.
 - **A plain `docker build .` of a clone stamps the version that
  `git describe --tags --always` gives.** The version is derived from the `.git`
@@ -872,10 +754,10 @@ style conventions are in separate documents:
    `--always` makes an untagged repo yield an abbreviated commit hash rather
    than failing. The `[ -n "$version" ]` line is the single place the fallback
-    is applied. That line is a live check that fires on a build from an export
+    is applied. It is a live check that fires on a build from an export with no
-    with no `.git`, and on a repository with no commits yet. Do not fold it into
+    `.git`, and on a repository with no commits yet. Do not fold it into the
-    the substitution as `|| echo unknown`, which makes the guard unreachable.
+    substitution as `|| echo unknown`, which makes the guard unreachable. The
-    The Dockerfile's side is `ARG VERSION` in the stage that compiles, declared
+    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
@@ -890,15 +772,11 @@ style conventions are in separate documents:
  transfers only the delta from the previous build.
 - **No build artifacts in version control.** Code-derived data must never be
-  committed to the repository if it can be avoided. Code-derived data includes:
+  committed to the repository if it can be avoided: compiled bundles, minified
-    - compiled bundles
+  output, generated assets. The build process (e.g. Dockerfile, Makefile) should
-    - minified output
+  generate these at build time. Notable exception: Go protobuf generated files
-    - generated assets
+  (`.pb.go`) ARE committed. Repos need to work with `go get`, which downloads
-
+  code but does not execute code generation.
    The build process (e.g. Dockerfile, Makefile) should generate these at build
    time. Notable exception: Go protobuf generated files (`.pb.go`) ARE
    committed because repos need to work with `go get`, which downloads code but
    does not execute code generation.
 - Never use `git add -A` or `git add .`. Always stage files explicitly by name.
@@ -918,8 +796,8 @@ style conventions are in separate documents:
  `test-support` depguard rule. There a repo names its own test-support packages
  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.15.0 (released 2026-10-16). The version is pinned as the digest of the lint
+  v2.15.0 (released 2026-10-16). It is pinned as the digest of the lint phase's
-  phase's base image,
+  base image,
  `golangci/golangci-lint@sha256:fbfcfd12a6f8d7f1b97b3362ca80fc2a244d46863148c73cb88e7793af96c481`,
  which reports `2.15.0 built with go1.27.0 from 25c5369a`. A module's `go`
  directive must not name a newer Go minor version than the one golangci-lint
@@ -939,26 +817,22 @@ style conventions are in separate documents:
  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.
+      running `2.12.2-rc1` and skips the install;
-    - treats `--version` output as a mismatch when it is any of these:
+    - treats absent, non-zero, empty or unrecognised `--version` output as a
-        - absent
+      mismatch, so the failure direction is a redundant install and never a
-        - non-zero
+      skipped one;
        - empty
        - unrecognised
        So a failure causes a redundant install, never a skipped one.
    - after installing, re-resolves the binary the way callers do, with
      `hash -r` and then through `PATH`, not through the directory the installer
-      wrote to. A shadowing binary can hide an install, which then succeeds
+      wrote to. It fails naming the resolved path, since an install that a
-      while no caller sees any change. In that case it fails and names the
+      shadowing binary hides succeeds while changing nothing any caller sees;
      resolved path.
    - 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.
-    A tool from the distribution has no pin, so `script/bootstrap` installs it
+    Node is the exception to the whole-token comparison. The canonical
-    when it is missing. make, git, node and yarn are such tools.
+    `script/bootstrap` compares only its major version, for two reasons. The
    node 22 alpine image the `Dockerfile` stages start from is not the exact
    pin, and nvm cannot install a prebuilt node on alpine.
    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
@@ -1026,15 +900,9 @@ style conventions are in separate documents:
          an explicit allowlist of known origins. Wildcard (`*`) is acceptable
          only for public, unauthenticated read-only APIs.
    - **Error handling:**
-        - Internal errors must never leak implementation details to the client.
+        - Internal errors must never leak stack traces, SQL queries, file paths,
-          Those details include:
+          or other implementation details to the client. Return generic error
-            - stack traces
+          messages in production; detailed errors only when `DEBUG` is enabled.
            - SQL queries
            - file paths
            Return generic error messages in production; detailed errors only
            when `DEBUG` is enabled.
    - **TLS:**
        - Services never terminate TLS directly. They are always deployed behind
          a TLS-terminating reverse proxy. The service itself listens on plain
@@ -1136,8 +1004,7 @@ style conventions are in separate documents:
    - `Dockerfile`, `.dockerignore`
    - `.gitea/workflows/check.yml`
    - Go: `go.mod`, `go.sum`, `.golangci.yml`
-    - JS: `package.json`, `yarn.lock`, `.yarnrc.yml`, `.yarn/releases/`,
+    - JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
      `.gitattributes`, `.prettierrc`, `.prettierignore`
    - Python: `pyproject.toml`
 - Guidance for coding agents lives in one `AGENTS.md` at the repository root. It
@@ -1,17 +1,24 @@
 #!/bin/sh
 # script/bootstrap: install all dependencies needed to build and develop
 # this repo. Idempotent: every install is guarded by a check so already
-# installed tools are skipped. Base tools, node and yarn come from nix,
+# installed tools are skipped. Base tooling comes from nix, apt, brew,
-# apt, brew, or apk (detected in that order), with no version and no
+# or apk (detected in that order); assumes nothing is present. The
-# hash, because the distribution is trusted. It installs node, yarn and
+# installed node is used only when its major version is the pinned one;
-# the node packages only when yarn.lock is in the tree. The
+# otherwise (node missing, or another major) the pinned version is
-# distribution's yarn only starts the release file that yarnPath in
+# installed via nvm (installing nvm itself first, from a hash-verified
-# .yarnrc.yml names, and that file does the work. So git pins the yarn
+# release archive, never curl | sh), and yarn and the packages are
-# that runs. Assumes nothing is present.
+# installed under it.
 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=""
 APT_UPDATED=""
@@ -60,33 +67,99 @@ missing() {
    ! command -v "$1" >/dev/null 2>&1
 }
-# Debian and Ubuntu name the yarn command yarnpkg.
+# verify_sha256 <file> <expected-hash>
-run_yarn() {
+verify_sha256() {
-    if command -v yarn >/dev/null 2>&1; then
+    if command -v sha256sum >/dev/null 2>&1; then
-        yarn "$@"
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
    elif command -v yarnpkg >/dev/null 2>&1; then
        yarnpkg "$@"
    else
-        echo "no yarn; run script/bootstrap first" >&2
+        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"
 }
 # True when the node on PATH has the pinned major version. Only the
 # major is compared: the Dockerfile stages start from a node 22 alpine
 # image whose exact version is not the pin, and nvm cannot install a
 # prebuilt node on alpine. Another major is not used: the pinned yarn 1
 # prints a deprecation warning under node 24. script/fmt and
 # script/fmt-check carry this function unchanged, to run the yarn
 # installed here.
 node_is_pinned_major() {
    if ! command -v node >/dev/null 2>&1; then return 1; fi
    installed="$(node --version)"
    installed="${installed#v}"
    [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
 }
 ensure_node() {
    if node_is_pinned_major; then
        echo "bootstrap: using node $(node --version)"
        return 0
    fi
    ensure_nvm
    nvm_sh "nvm install $NODE_VERSION"
    nvm_sh "nvm use $NODE_VERSION >/dev/null && \
        echo \"bootstrap: using node \$(node --version)\""
 }
 ensure_yarn() {
    if ! node_is_pinned_major; then
        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
            corepack prepare yarn@$YARN_VERSION --activate"
        return 0
    fi
    if ! missing yarn; then return 0; fi
    if ! missing corepack; then
        corepack enable
        corepack prepare "yarn@$YARN_VERSION" --activate
    else
        npm install -g "yarn@$YARN_VERSION"
    fi
 }
 install_js_deps() {
    if node_is_pinned_major; then
        yarn install --frozen-lockfile
    else
        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
            yarn install --frozen-lockfile"
    fi
 }
 main() {
    cd "$ROOT"
    if missing make; then pkg_install gnumake make make make; fi
    if missing git; then pkg_install git git git git; fi
-    # A Dockerfile stage that needs no yarn copies no yarn.lock.
+    ensure_node
-    if [ -f yarn.lock ]; then
+    ensure_yarn
-        if missing node; then pkg_install nodejs_latest nodejs node nodejs-current; fi
+    install_js_deps
        if missing yarn && missing yarnpkg; then
            pkg_install yarn yarnpkg yarn yarn
        fi
        run_yarn install --immutable
    fi
    echo "bootstrap complete"
 }
@@ -4,16 +4,33 @@ set -eu
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-# Debian and Ubuntu name the yarn command yarnpkg.
+# Must match the pin in script/bootstrap.
 NODE_VERSION="22.17.0"
 # True when the node on PATH has the pinned major version: the same
 # function as in script/bootstrap, which uses it to decide where it
 # installs yarn.
 node_is_pinned_major() {
    if ! command -v node >/dev/null 2>&1; then return 1; fi
    installed="$(node --version)"
    installed="${installed#v}"
    [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
 }
 # Run the yarn script/bootstrap installed: the yarn on PATH when the
 # node on PATH has the pinned major version, and otherwise yarn under
 # the pinned node in nvm, which bootstrap leaves off the PATH of the
 # shell that called it. nvm is a bash script, hence the subshell.
 run_yarn() {
-    if command -v yarn >/dev/null 2>&1; then
+    if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then
-        yarn "$@"
+        exec yarn "$@"
-    elif command -v yarnpkg >/dev/null 2>&1; then
+    fi
-        yarnpkg "$@"
+    if node_is_pinned_major || [ ! -s "$HOME/.nvm/nvm.sh" ]; then
-    else
+        echo "fmt: no yarn; run script/bootstrap first" >&2
        echo "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() {
@@ -4,16 +4,33 @@ set -eu
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-# Debian and Ubuntu name the yarn command yarnpkg.
+# Must match the pin in script/bootstrap.
 NODE_VERSION="22.17.0"
 # True when the node on PATH has the pinned major version: the same
 # function as in script/bootstrap, which uses it to decide where it
 # installs yarn.
 node_is_pinned_major() {
    if ! command -v node >/dev/null 2>&1; then return 1; fi
    installed="$(node --version)"
    installed="${installed#v}"
    [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
 }
 # Run the yarn script/bootstrap installed: the yarn on PATH when the
 # node on PATH has the pinned major version, and otherwise yarn under
 # the pinned node in nvm, which bootstrap leaves off the PATH of the
 # shell that called it. nvm is a bash script, hence the subshell.
 run_yarn() {
-    if command -v yarn >/dev/null 2>&1; then
+    if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then
-        yarn "$@"
+        exec yarn "$@"
-    elif command -v yarnpkg >/dev/null 2>&1; then
+    fi
-        yarnpkg "$@"
+    if node_is_pinned_major || [ ! -s "$HOME/.nvm/nvm.sh" ]; then
-    else
+        echo "fmt-check: no yarn; run script/bootstrap first" >&2
        echo "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() {
@@ -1,23 +1,8 @@
-# This file is generated by running "yarn install" inside your project.
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
-# Manual changes might be lost - proceed with caution!
+# yarn lockfile v1
 __metadata:
  version: 10
  cacheKey: 10c0
-"prettier@npm:3.8.1":
+prettier@3.8.1:
-  version: 3.8.1
+  version "3.8.1"
-  resolution: "prettier@npm:3.8.1"
+  resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.8.1.tgz#edf48977cf991558f4fcbd8a3ba6015ba2a3a173"
-  bin:
+  integrity sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==
    prettier: bin/prettier.cjs
  checksum: 10c0/33169b594009e48f570471271be7eac7cdcf88a209eed39ac3b8d6d78984039bfa9132f82b7e6ba3b06711f3bfe0222a62a1bfb87c43f50c25a83df1b78a2c42
  languageName: node
  linkType: hard
 "root-workspace-0b6124@workspace:.":
  version: 0.0.0-use.local
  resolution: "root-workspace-0b6124@workspace:."
  dependencies:
    prettier: "npm:3.8.1"
  languageName: unknown
  linkType: soft