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 01:55:14 +00:00
18 changed files with 298 additions and 1459 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
-# case-sensitive on Linux, so names use character ranges rather than a
-# lowercase form that misses `Server.Key`.
+# 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
@@ -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
-# system packages. script/ passes a new value on every build. That value
-# 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.
+# Every stage declares ARG CACHEBUST first: script/ passes a new value on
+# every build, which reruns every RUN step after it.
 #
-# alpine 3.24.3, 2026-11-04
-FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS lint
-RUN apk add --no-cache git make nodejs-current yarn
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS lint
 ARG CACHEBUST

 WORKDIR /app

 COPY script/ script/
-COPY package.json yarn.lock .yarnrc.yml ./
-COPY .yarn/releases/ .yarn/releases/
+COPY package.json yarn.lock ./
 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
-FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a AS test
-RUN apk add --no-cache git make nodejs-current yarn
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS test
 ARG CACHEBUST

 WORKDIR /app

 COPY script/ script/
-COPY package.json yarn.lock .yarnrc.yml ./
-COPY .yarn/releases/ .yarn/releases/
+COPY package.json yarn.lock ./
 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
-FROM alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a
-RUN apk add --no-cache git make nodejs-current yarn
+# node 22-alpine, 2026-02-22
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
 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
-# packages.
+# script/bootstrap installs all prerequisites. Manifests are copied
+# first so that layer stays cached until dependencies change.
 COPY script/ script/
-COPY package.json yarn.lock .yarnrc.yml ./
-COPY .yarn/releases/ .yarn/releases/
+COPY package.json yarn.lock ./
 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
-after `FROM` in every stage, above `ARG CACHEBUST`. `script/bootstrap` installs
-the node packages below that line, because check builds keep system packages but
+mounts. This repo's own `Dockerfile` declares `ARG CACHEBUST` right after `FROM`
+in every stage: each stage installs system packages and node packages together
+in one `script/bootstrap` step, and check builds may keep system packages but
 not node packages.

 ## Rationale
@@ -21,45 +21,6 @@ fmt-check, and commit.

 # Completed Steps

- 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
@@ -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
-   distribution.
+1. Use LTS node versions.

 1. Use `prettier` for code formatting, with four spaces for indentation.

@@ -81,17 +81,11 @@ with your task.
    - pipenv and its dependencies
    - the packages from `Pipfile.lock`

-    It creates a virtual environment at `$HOME/.pipenv` 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. It installs pipenv and its dependencies by hash, with
+    It installs pipenv and its 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
+    development packages. It installs no Python there, because the tests use the
+    base image's. 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`

@@ -164,39 +158,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/`,
-          `.gitattributes`, `.prettierrc`, `.prettierignore` (fetch the last two
-          from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc`
-          and
-          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`).
-    - [ ] JS: `yarn.lock` 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. Name any package that must run its install script in `package.json`,
-           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.
+    - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
+          (fetch from
+          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc` and
+          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`)
    - [ ] Python: `pyproject.toml`
    - [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)

@@ -231,20 +196,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
-      `yarn.lock` is in the tree. node and yarn come from the distribution when
-      they are missing. It installs the node packages with
-      `yarn install --immutable`. The distribution's yarn only starts the
-      release file that `yarnPath` in `.yarnrc.yml` names, and that file does
-      the work.
- [ ] 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/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/fmt` and `script/fmt-check` pick their `yarn` with the same test
+      as `script/bootstrap`: the `yarn` on `PATH` when the node on `PATH` has
+      the pinned major version, and otherwise yarn under the pinned node, with
+      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.
 - [ ] `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
@@ -272,16 +230,8 @@ with your task.
      is a package from the distribution's own package index, which needs no
      version and no hash. Pulling that index is also allowed. In a
      `Dockerfile`, the distribution is the pinned base image's. On a host, it
-      is the host's, and the host's package manager stands for it, nix and brew
-      included. A package source that a `Dockerfile` adds itself does not get
-      this exception
- [ ] 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
+      is the host's. A package source that a `Dockerfile` adds itself does not
+      get this exception
 - [ ] Using `yarn`, not `npm` (JS projects)

 # Directory Structure
@@ -310,12 +260,11 @@ with your task.
 # Final

 - [ ] `make check` passes
- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has.
-      That host is the runner image
-      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
-      node 24. Take any yarn off `PATH` first. The run must show that the checks
-      executed. A sub-second build means nothing ran. So does `CACHED` on a step
-      that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has
+      (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker,
+      git and node 24, with no yarn on `PATH`), and demonstrably executed the
+      checks — a sub-second build, or `CACHED` on a step that lints or tests,
+      one of the `RUN` steps below `ARG CACHEBUST`, means nothing ran. Above
      that line, these steps are expected to show `CACHED`:
    - the steps that install system packages
    - the steps that download Go's modules
@@ -148,20 +148,13 @@ Template files can be fetched from:
        - pipenv and its dependencies
        - the packages from `Pipfile.lock`

-        It creates a virtual environment at `$HOME/.pipenv` 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. It installs pipenv and its
-        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`
+        It installs pipenv and its 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 installs no Python there,
+        because the tests use the base image's. 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
@@ -179,21 +172,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: make the first `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.
+    - [ ] JS: `yarn init`, `yarn add --dev prettier`
    - [ ] Python: `pyproject.toml`

 ## Configure script/ Entrypoints and Makefile
@@ -204,23 +183,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,
-      idempotently, and assumes nothing is present:
-    - It detects the package manager: nix, apt, brew or apk.
-    - It installs node, yarn and the node packages only when `yarn.lock` is in
-      the tree. node and yarn come from that package manager when they are
-      missing.
-    - It installs the node packages with `yarn install --immutable`. The
-      distribution's yarn only starts the release file that `yarnPath` in
-      `.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/bootstrap` / `make bootstrap` — installs all dependencies,
+      idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
+      node used if its major version is the pinned one, else pinned version via
+      nvm from a hash-verified archive, with yarn and the packages installed
+      under it; pinned yarn via corepack); a non-server repo's development
+      environment stage runs it instead of inline installs; a gate phase or the
+      build stage installs what its base image lacks either inline or by running
+      it
 - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
      then `install-precommit`, plus repo-specific init
 - [ ] `script/test` / `make test` —
@@ -250,10 +220,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
-      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/fmt` and `script/fmt-check` pick their `yarn` with the same test
+      as `script/bootstrap`: the `yarn` on `PATH` when the node on `PATH` has
+      the pinned major version, and otherwise yarn under the pinned node, with
+      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
@@ -268,12 +241,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.
-      That host is the runner image
-      `docker.gitea.com/runner-images:ubuntu-latest`, which has docker, git and
-      node 24. Take any yarn off `PATH` first. The run must show that the checks
-      executed. A sub-second build means nothing ran. So does `CACHED` on a step
-      that lints or tests, one of the `RUN` steps below `ARG CACHEBUST`. Above
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has
+      (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker,
+      git and node 24, with no yarn on `PATH`), and demonstrably executed the
+      checks — a sub-second build, or `CACHED` on a step that lints or tests,
+      one of the `RUN` steps below `ARG CACHEBUST`, means nothing ran. Above
      that line, these steps are expected to show `CACHED`:
    - the steps that install system packages
    - the steps that download Go's modules
@@ -287,16 +259,8 @@ are thin shims calling them. Model scripts:
 - [ ] No mutable image/package references. The one exception is a package from
      the distribution's own package index, which needs no version and no hash.
      Pulling that index is also allowed. In a `Dockerfile`, the distribution is
-      the pinned base image's. On a host, it is the host's, and the host's
-      package manager stands for it, nix and brew included. A package source
+      the pinned base image's. On a host, it is the host's. A package source
      that a `Dockerfile` adds itself does not get this exception
- [ ] 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
 - [ ] No unnecessary files in repo root
 - [ ] All dates written as YYYY-MM-DD

@@ -25,7 +25,6 @@ style conventions are in separate documents:
  a remote source, including:
    - Docker base images
    - Go modules
-    - Python packages
    - npm packages
    - GitHub Actions

@@ -34,49 +33,29 @@ style conventions are in separate documents:
    dependency by its content hash:
    - Docker: `@sha256:...`
    - Go: the module hash in `go.sum`
-    - Python: the package hash in `Pipfile.lock`
-    - npm: the `checksum` in `yarn.lock`
+    - npm: the integrity hash in the lockfile
    - GitHub Actions: `@<commit-sha>`

-    This also means never `curl | bash` to install a tool such as rustup.
-    Instead, download a specific release archive from GitHub, verify its hash,
-    and only then install. The hash is hardcoded in the Dockerfile or script.
-    Unverified install scripts are arbitrary remote code execution. Double-check
-    every external reference in every file before committing.
+    This also means never `curl | bash` to install tools like pyenv, nvm,
+    rustup, etc. Instead, download a specific release archive from GitHub,
+    verify its hash, and only then install. The hash is hardcoded in the
+    Dockerfile or script. Unverified install scripts are arbitrary remote code
+    execution. Double-check every external reference in every file before
+    committing.

    There is one exception: a package from the distribution's own package index
    needs no version and no hash. Pulling that index is also allowed. 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. These commands are
-    examples:
+    distribution. On a host, it is the host's. These commands are examples:
    - `apt-get update`
    - `apt-get install`
    - `apk update`
    - `apk add`

-    These come from the distribution wherever possible:
-    - node, meaning the distribution's newest Node package, such as
-      `nodejs-current` on Alpine 3.24
-    - yarn
-    - npm
-    - python
-    - pip and venv, the installer tools bundled with python
-
-    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
@@ -120,58 +99,18 @@ 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
-    apk, detected in that order; apt runs noninteractive. Each one is installed
-    only when it is missing. A tool from outside the distribution is never
-    installed as "latest" or "lts"; it is always an exact version.
-
-    `script/bootstrap` installs node, yarn and the node packages only when
-    `yarn.lock` is in the tree. With no `yarn.lock`, it installs no node and no
-    yarn. It installs the node packages with `yarn install --immutable`. That
-    install fails when a package's `checksum` is wrong, or when `package.json`
-    is out of step with `yarn.lock`.
-
-    Each repository commits the yarn that runs. `yarnPath` in `.yarnrc.yml`
-    points at the release file in `.yarn/releases/`. The distribution's yarn
-    only starts that file, and that file does the work. Alpine packages yarn 1,
-    and Debian 13 packages yarn 4.1. The same committed yarn does the work on
-    both. Corepack never runs, and no yarn is downloaded.
-
-    `.yarnrc.yml` holds these settings:
-    - `yarnPath`
-    - `nodeLinker: node-modules`
-    - `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.
+    nothing is present. Base tools come from nix, apt, brew, or apk, detected in
+    that order; apt runs noninteractive. For node it uses the installed node
+    only when its major version is the pinned one. When node is missing or has
+    another major, it installs the PINNED node version via nvm, and installs
+    yarn and the packages under it. The CI runner image ships node 24, for
+    example. 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
+    because 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/cibuild` runs the CI build, and the Gitea workflow calls it. The
    script changes to the repo root, runs `script/bootstrap`, runs
@@ -179,7 +118,15 @@ style conventions are in separate documents:
    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.
+    after the containerised gates have passed. **The bootstrap alone is not
+    enough.** When `script/bootstrap` installs node and yarn under nvm, it
+    leaves neither on the `PATH` of the shell that called it. A bare `yarn` then
+    either exits 127 or runs under another node. The host 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 pinned major version,
+    they run the `yarn` on `PATH`. Otherwise they load nvm through
+    `$HOME/.nvm/nvm.sh` and run yarn under the pinned node. A runner carrying
+    nothing but 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`.
@@ -203,12 +150,6 @@ style conventions are in separate documents:
  instead of invoking the underlying tools directly. The Makefile is the single
  source of truth for how these operations are run.

-    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 make targets. 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:
    - running a local development server (`make run`, `make dev`)
@@ -234,16 +175,14 @@ style conventions are in separate documents:
      does for its yarn packages

    The development environment stage installs development prerequisites by
-    running `script/bootstrap`. Only system packages may be installed inline
-    above it, so that check builds keep them; the `prompts` repo's own
-    `Dockerfile` does this. A stage that runs `script/bootstrap` COPYs `script/`
-    and the dependency manifests it needs before running it. These are examples:
-    - `package.json`, `yarn.lock`, `.yarnrc.yml` and `.yarn/releases/`
-    - `go.mod` and `go.sum`
+    running `script/bootstrap` rather than duplicating its installs inline. A
+    stage that runs `script/bootstrap` COPYs `script/` and the dependency
+    manifests (`package.json` + `yarn.lock`, `go.mod` + `go.sum`, etc.) before
+    running it.

- **The lint and test gates run in Docker, as phases of the `Dockerfile`.**
-  There is no separate lint file. `script/lint` and `script/test` each build one
-  phase and nothing else:
+- **Linting and testing run in Docker, as phases of the `Dockerfile`.** There is
+  no separate lint file. `script/lint` and `script/test` each build one phase
+  and nothing else:

    ```sh
    docker build --build-arg CACHEBUST="$(date +%s)-$$" \
@@ -552,18 +491,10 @@ style conventions are in separate documents:
        - pipenv and its dependencies
        - the packages from `Pipfile.lock`

-        `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`.
+        `script/bootstrap` installs no Python there: the tests use the base
+        image's Python, which the image's hash pins. 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
@@ -573,65 +504,37 @@ style conventions are in separate documents:
        - installs only what `Pipfile.lock` names
        - checks every package against the lockfile's hashes
        - fails when the lockfile is out of date with `Pipfile`
-    - `script/bootstrap` sets `PIP_ONLY_BINARY=:all:` for both installs, and
-      pipenv passes it on to pip. A package with no ready-built wheel for the
-      image then stops the install. Without the setting, pip builds that package
-      from source and downloads the build tools without a hash check.
    - A kept layer holds nothing a new install would refuse: pip checked the
      hashes of pipenv and its dependencies, and pipenv checked the hashes of
      the lockfile's packages. pipenv creates its virtual environment with the
      `virtualenv` package. The packages that `virtualenv` adds come from wheels
-      inside that package, so the hash pip checked for it covers them. System
-      packages, Python among them, are not fixed by a hash. They keep the
-      versions the package manager gave when the layer was built; a new install
-      may get newer ones.
+      inside that package, so the hash pip checked for it covers them. Two
+      things in the layer are not fixed by a hash:
+        - A package with no ready-built wheel for the image is built from
+          source. pip downloads the build tools without a hash check, so a kept
+          layer's build of such a package may differ from a new one.
+        - System packages keep the 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
-    the last `echo`. The `ensurepip` test fails when python is missing, and also
-    when Debian's venv package is missing:
-
-    ```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.
+    In the example below, `script/bootstrap` does all of these:
+    - finds `make` and `git` already installed
+    - installs pipenv and its dependencies by hash
+    - runs `pipenv install --dev --deploy`

    ```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
-    FROM debian@sha256:... AS test
-    # Python, pip and venv come from the distribution, which is trusted, so
-    # they need no version and no hash. make and git are base tools that
-    # script/bootstrap installs when they are missing. Installed here, they
-    # stay in their own layer when script/ changes.
+    # python:3.x-slim, YYYY-MM-DD
+    FROM python@sha256:... AS test
+    # make and git are base tools that script/bootstrap installs when they
+    # are missing. Installed here, they stay in their own layer when
+    # script/ changes.
    RUN apt-get update \
-        && apt-get install -y --no-install-recommends ca-certificates make git \
-            python3 python3-venv \
+        && apt-get install -y --no-install-recommends make git \
        && 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 ./
@@ -766,16 +669,16 @@ style conventions are in separate documents:

    ```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
@@ -799,7 +702,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
@@ -821,16 +723,16 @@ style conventions are in separate documents:
  Such a `.dockerignore` 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. Those are `.claude`, `.yarn/*`,
-  `!.yarn/releases`, and the repo's own host-built binary. The binary is 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 copy of each 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
+  root-anchored entries unprefixed. Those are `.claude`, and the repo's own
+  host-built binary. The binary is 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 copy of each 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.

@@ -955,8 +857,10 @@ style conventions are in separate documents:
      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
-    when it is missing. make, git, node and yarn are such tools.
+    Node is the exception to the whole-token comparison. The canonical
+    `script/bootstrap` compares only node's major version. That is because the
+    `Dockerfile` stages start from a node 22 alpine image, which is not the
+    exact pin, and nvm cannot install a prebuilt node on alpine.

    Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.

@@ -1134,8 +1038,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/`,
-      `.gitattributes`, `.prettierrc`, `.prettierignore`
+    - JS: `package.json`, `yarn.lock`, `.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,
-# apt, brew, or apk (detected in that order), with no version and no
-# hash, because the distribution is trusted. It installs node, yarn and
-# the node packages only when yarn.lock is in the tree. The
-# distribution's yarn only starts the release file that yarnPath in
-# .yarnrc.yml names, and that file does the work. So git pins the yarn
-# that runs. Assumes nothing is present.
+# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# or apk (detected in that order); assumes nothing is present. The
+# installed node is used only when its major version is the pinned one;
+# otherwise (node missing, or another major) the pinned version is
+# installed via nvm (installing nvm itself first, from a hash-verified
+# release archive, never curl | sh), and yarn and the packages are
+# 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.
-run_yarn() {
-    if command -v yarn >/dev/null 2>&1; then
-        yarn "$@"
-    elif command -v yarnpkg >/dev/null 2>&1; then
-        yarnpkg "$@"
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
    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.
-    if [ -f yarn.lock ]; then
-        if missing node; then pkg_install nodejs_latest nodejs node nodejs-current; fi
-        if missing yarn && missing yarnpkg; then
-            pkg_install yarn yarnpkg yarn yarn
-        fi
-
-        run_yarn install --immutable
-    fi
+    ensure_node
+    ensure_yarn
+    install_js_deps

    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
-        yarn "$@"
-    elif command -v yarnpkg >/dev/null 2>&1; then
-        yarnpkg "$@"
-    else
-        echo "no yarn; run script/bootstrap first" >&2
+    if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if node_is_pinned_major || [ ! -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() {
@@ -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
-        yarn "$@"
-    elif command -v yarnpkg >/dev/null 2>&1; then
-        yarnpkg "$@"
-    else
-        echo "no yarn; run script/bootstrap first" >&2
+    if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then
+        exec yarn "$@"
+    fi
+    if node_is_pinned_major || [ ! -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() {
@@ -1,23 +1,8 @@
-# This file is generated by running "yarn install" inside your project.
-# Manual changes might be lost - proceed with caution!
+# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+# yarn lockfile v1

-__metadata:
-  version: 10
-  cacheKey: 10c0

-"prettier@npm:3.8.1":
-  version: 3.8.1
-  resolution: "prettier@npm:3.8.1"
-  bin:
-    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
+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==