feat(ci): gate documentation drift, and make docs a pre-tag release step

Five doc claims had rotted by v1.9.0, all the same shape: a value written once by hand, in a file nothing verifies, about a number that lives elsewhere and moved. README pin table wrong on all three rows; a "Planned" section describing something already shipped; DOCKER_HUB.md claiming Node v22 against Node 24. DOCKER_HUB.md is why this is a gate and not a resolution to be careful: it is PUBLISHED (update-description POSTs it as Docker Hub full_description on every tag), it had gone eight releases untouched, nothing generates it, and it is read from the TAG -- so the stale page shipped with v1.9.0 regardless. scripts/check-doc-drift.sh: seven checks, all repo-local (no network, token, image, or sibling clone). Exit 0/1/2 matching lint-shell.sh; a renamed ARG is a red 2, not a green tick. Wired as a fourth lint.yml job so "the docs lie" is its own red name. Verified with 15 controls, including two false-positive controls: the first placeholder check flagged README.md:900, a Go template in a legitimate `docker inspect --format` example. The gate was wrong, not the doc, so the pattern is now anchored to the UPPER_SNAKE convention CI substitutes. Not gated, deliberately: counts/sizes needing a running image (they belong in smoke-test.sh -- a guessing gate is worse than none), and Dockerfile.base BASE_REBUILD_DATE, because base_tag hashes that file content-wise and demanding it be current would force a ~60 min rebuild on releases that touch no base files. Free during a rebuild, expensive otherwise. AGENTS.md step 3 rewritten around the mechanism: checkout@v4 with no ref: means every job reads github.ref, the tag. Docs must be right BEFORE tagging.
docs(hub): the Docker Hub page claimed Node v22; v1.9.0 ships Node 24
2026-09-10 22:01:49 +02:00 · 2026-09-10 21:43:17 +02:00 · 2026-09-10 21:33:07 +02:00 · 2026-09-10 21:21:09 +02:00 · 2026-09-10 20:58:42 +02:00 · 2026-09-10 20:30:16 +02:00
13 changed files with 1225 additions and 28 deletions
@@ -92,7 +92,7 @@ jobs:

      - name: Install actionlint (pinned)
        env:
-          ACTIONLINT_VERSION: 1.7.7
+          ACTIONLINT_VERSION: 1.7.12
        run: |
          curl -fsSL \
            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz" \
@@ -127,7 +127,7 @@ jobs:

      - name: Install hadolint (pinned)
        env:
-          HADOLINT_VERSION: 2.14.0
+          HADOLINT_VERSION: 2.15.1
        run: |
          curl -fsSL \
            "https://github.com/hadolint/hadolint/releases/download/v${HADOLINT_VERSION}/hadolint-Linux-x86_64" \
@@ -137,3 +137,81 @@ jobs:

      - name: Run hadolint
        run: hadolint Dockerfile.base Dockerfile.variant
+
+  skill-floor:
+    # Gate the VENDORED pi-extensions skill snapshot in rootfs/ against the
+    # package repo it is a snapshot of. Its own job rather than a step in
+    # `actionlint`, so "the floor is stale" is a distinct red name in the runs
+    # list instead of being buried in a lint job that is about something else.
+    #
+    # The gap it closes, measured 2026-09-10: the floor sat at 34284 B, untouched
+    # since fa04d20 (2026-07-30), while the package copy was 38973 B.
+    # Dockerfile.variant copies the fresh package copy over the SERVED path but
+    # never writes back to the floor, so nothing in the repo ever noticed. That
+    # matters because the floor is a FALLBACK: the copy is guarded by
+    # `if [ -f /opt/pi-extensions/skill/SKILL.md ]`, so a build whose clone
+    # yields no skill/ ships the vendored snapshot and still goes green, with no
+    # manifest flag or label saying which copy was served.
+    #
+    # Gating on another repo is normally a smell; it is proportionate here
+    # because the check compares the skill DIRECTORY hash, so it can only fire
+    # when that directory actually changed — which is exactly when the floor has
+    # gone stale. pi-extensions commits that leave skill/ alone cannot turn this
+    # red. No secret is needed either: the repo is anonymously clonable (verified
+    # 2026-09-10 with `git ls-remote` and no credentials), so this cannot start
+    # failing when a token expires.
+    #
+    # Exit codes are 0 in sync / 1 drift / 2 cannot-run, matching
+    # scripts/lint-shell.sh: a gate that cannot run must not pass, so an
+    # unreachable package repo is a red 2 rather than a green tick.
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Vendored pi-extensions skill floor matches the package
+        run: bash scripts/check-skill-floor.sh
+
+  doc-drift:
+    # Gate hand-maintained doc claims against the build files they describe.
+    # Its own job for the same reason as skill-floor: "the docs lie" should be a
+    # distinct red name, not a line buried in a job about workflow syntax.
+    #
+    # The gap it closes, measured 2026-09-10 while preparing v1.9.0 — five
+    # claims had rotted, every one of them a fact written by hand in a file
+    # nothing verified:
+    #   * README.md's "Version pins" table was wrong on ALL THREE rows (pi
+    #     0.84.4 vs 0.85.1, pi-atelier v0.10.0 vs v0.10.1, mempalace 3.8.0 vs
+    #     3.9.0) — and that table exists specifically to be the reviewable
+    #     record of what the repo freezes on purpose, so a wrong row destroys
+    #     the only thing it is for.
+    #   * README.md listed already-shipped typst PDF export under "Planned for
+    #     an upcoming minor release", marked "(shipped in Unreleased/base)".
+    #   * DOCKER_HUB.md claimed "Node.js v22" while v1.9.0 ships Node 24.
+    #
+    # DOCKER_HUB.md is why this is a gate and not a habit. It is PUBLISHED —
+    # update-description POSTs it to Docker Hub as full_description on every tag
+    # — and it had gone eight releases (v1.8.6 -> v1.9.0) untouched. Nothing
+    # generates it and nothing checked it, so the only thing keeping it true was
+    # someone remembering. It is also read from the TAG, so a fix pushed to main
+    # after tagging never reaches the published page.
+    #
+    # Cheap and hermetic on purpose: every check compares a doc string against a
+    # value that exists in this repo, so no network, no token, no built image,
+    # and no sibling clone. Claims that genuinely need a running container (image
+    # sizes, the "N mempalace_* tools" count) are deliberately left out — a gate
+    # that cannot evaluate a claim honestly would have to guess, and a guessing
+    # gate is worse than none. Assert those in scripts/smoke-test.sh instead.
+    #
+    # Exit codes 0 in sync / 1 drift / 2 cannot-run, matching lint-shell.sh and
+    # check-skill-floor.sh. A renamed ARG makes the gate blind, so that is a red
+    # 2, not a green tick.
+    runs-on: ubuntu-latest
+    container:
+      image: catthehacker/ubuntu:act-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Doc claims match the build files
+        run: bash scripts/check-doc-drift.sh
@@ -92,7 +92,44 @@ re-brand of opencode-devbox's `pi-only` variant.
   is hashed into `base_tag`, so it costs a base rebuild (~67 min); and if the
   section the phrase canary names has changed, re-pin it in
   `scripts/smoke-test.sh`.
-3. Update `CHANGELOG.md` Unreleased → vX.Y.Z section.
+3. **Update the docs this release makes stale — BEFORE you tag.** Rename
+   `CHANGELOG.md`'s `## Unreleased` to `## vX.Y.Z — YYYY-MM-DD` (em dash, as
+   every prior release heading uses), then run the gate:
+
+   ```bash
+   bash scripts/check-doc-drift.sh      # 0 in sync / 1 drift / 2 cannot run
+   ```
+
+   It compares README.md's version-pin table against the ARGs it names, and
+   DOCKER_HUB.md's Node claim against `ARG NODE_VERSION`, plus Hub's
+   25 000-char limit, unsubstituted `{{PLACEHOLDERS}}`, and stale `Unreleased`
+   pointers in user-facing docs.
+
+   **Why before and not after:** `docker-publish.yml` runs `actions/checkout@v4`
+   with no `ref:`, so every job reads `github.ref` — the **tag**. A doc fix
+   pushed to `main` after tagging does not reach the release, and for
+   `DOCKER_HUB.md` it does not reach the published Hub page either, because
+   `update-description` POSTs that file as Docker Hub's `full_description` from
+   the tag's tree. Getting it in afterwards means re-pointing the tag, which is
+   its own hazard (v1.8.14 went `601fc98` → `361babd` and broke deploy
+   verification until `git fetch --tags --force`).
+
+   The gate is deliberately narrow — it only checks claims verifiable from files
+   in this repo. Still eyeball, because these are NOT gated:
+   - counts and sizes (`~1.1 GB`, "N `mempalace_*` tools", "7 extensions") —
+     they need a running image; assert them in `scripts/smoke-test.sh` instead
+   - feature prose that quietly became false, e.g. a "Planned for an upcoming
+     release" section describing something that already shipped
+   - `Dockerfile.base`'s `# BASE_REBUILD_DATE:` marker. Ungated on purpose:
+     `base_tag` hashes Dockerfile.base's content, comments included, so
+     demanding it be current would force a ~60 min base rebuild on a release
+     that touched no base files. **Fix it when the base is already rebuilding —
+     then it is free.**
+
+   Measured cost of skipping this, 2026-09-10 (v1.9.0): five stale claims, one
+   of them published. README's pin table was wrong on all three rows, and
+   DOCKER_HUB.md — untouched for eight releases — still said Node v22 while the
+   image shipped Node 24.
 4. Verify `docker compose up` works locally with the current `latest` image
   if you're upgrading users from a previous version. Then run the
   **post-recreate sanity check** inside the running container to confirm
@@ -11,6 +11,327 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`).

 ---

+## Unreleased
+
+**A gate for documentation drift, because five claims rotted in one release and
+one of them was published.** Preparing v1.9.0 turned up a cluster of stale
+facts, all the same shape — a value written once by hand, in a file nothing
+verifies, about a number that lives somewhere else and moved:
+
+- `README.md`'s "Version pins" table was wrong on **all three rows**: pi
+  `0.84.4` vs `ARG PI_VERSION=0.85.1`, pi-atelier `v0.10.0` vs `v0.10.1`,
+  mempalace `3.8.0` vs `3.9.0`. That table is the worst possible place for this,
+  because it exists *specifically* to be the reviewable record of what the repo
+  freezes deliberately — so a wrong row destroys the only thing it is for.
+- `README.md` listed already-shipped typst PDF export under "Planned for an
+  upcoming minor release", carrying the self-contradicting marker "(shipped in
+  Unreleased/base)". The **fourth** instance of the stale-`Unreleased`-pointer
+  class this changelog already documented three of.
+- `DOCKER_HUB.md` claimed "Node.js v22" while v1.9.0 ships Node 24.
+
+The last one is why this became a gate rather than a resolution to be careful.
+`DOCKER_HUB.md` is **published**: `update-description` POSTs it to Docker Hub as
+`full_description` on every tag. It had gone **eight releases** (v1.8.6 →
+v1.9.0) without a touch. Nothing generates it — CI only substitutes
+`{{PI_VERSION}}` — and nothing checked it, so the sole mechanism keeping it true
+was whoever remembered. Worse, it is read from the **tag**, so the stale page
+published with v1.9.0 anyway and the fix could only ride the next release.
+
+**New: `scripts/check-doc-drift.sh` + a `doc-drift` job in `lint.yml`.** Seven
+checks, all comparing a doc string to a value that exists in this repo, so it
+needs no network, no token, no built image, and no sibling clone:
+
+- README's three pin-table rows vs the ARGs they name *by name*
+- `DOCKER_HUB.md`'s Node claim vs `ARG NODE_VERSION`
+- placeholders CI will not substitute — the publish step greps for leftovers of
+  `{{PI_VERSION}}` only, so any *second* token sails through and publishes
+  literally
+- `DOCKER_HUB.md` under Docker Hub's 25 000-char `full_description` limit
+  (previously discoverable only as a non-200 *after* the full build)
+- `Unreleased` appearing in a user-facing doc, which is always a pointer that
+  outlived what it pointed at
+
+Exit codes match `lint-shell.sh` and `check-skill-floor.sh`: `0` in sync, `1`
+drift, `2` cannot run — a renamed ARG makes the gate blind, which is a red `2`,
+never a green tick. Verified with **15 controls**: every check fails when its
+claim is broken, the real v1.9.0 Node bug is caught, and two false-positive
+controls pass — the first version of the placeholder check wrongly flagged
+`README.md:900`'s `docker inspect --format '{{json .Config.Labels}}'`, a Go
+template in a legitimate example, so the pattern is now anchored to the
+UPPER_SNAKE convention CI actually substitutes. **The gate was wrong, not the
+doc** — which is the whole reason a gate gets negative controls.
+
+Deliberately **not** gated, and the reasons matter more than the list:
+
+- Counts and sizes (`~1.1 GB`, "N `mempalace_*` tools", "7 extensions") need a
+  running image. A gate that cannot evaluate a claim honestly would have to
+  guess, and a guessing gate is worse than none — assert these in
+  `scripts/smoke-test.sh`, where a real image exists.
+- `Dockerfile.base`'s `# BASE_REBUILD_DATE:` marker, itself stale (2026-07-13,
+  three base rebuilds ago). `base_tag` hashes Dockerfile.base's *content*,
+  comments included, so demanding it be current would force a ~60 min base
+  rebuild on a release that touched no base files at all. It is free to fix
+  while the base is *already* rebuilding, and expensive at any other moment.
+  That cost asymmetry is now written into the release checklist rather than
+  enforced.
+
+**Release checklist step 3 rewritten** (`AGENTS.md`) around the mechanism that
+made this expensive: `docker-publish.yml` runs `actions/checkout@v4` with no
+`ref:`, so every job reads `github.ref` — the tag. Docs must be correct *before*
+tagging; afterwards the only routes are re-pointing the tag (its own hazard —
+v1.8.14 went `601fc98` → `361babd` and broke deploy verification until
+`git fetch --tags --force`) or waiting for the next release. The step now also
+names what the gate cannot see, so "gate is green" is not mistaken for "docs are
+true". The same reflex went into the `ci-release-watcher` skill, as the first
+correctness rule — it is the only one that expires once the tag exists.
+
+Also fixed in passing: README's `pi-devbox-version` sample was v1.5.0-era and
+structurally outdated (it predated the `palace:` line the surrounding prose
+advertises, the `pi-atelier` component, and the whole `skills:` block). Replaced
+with real observed output rather than hand-written text. `DOCKER_HUB.md`'s "7
+user-facing extensions" was **verified correct**; its "29 `mempalace_*` tools"
+is stale (a live client shows 45) but left alone rather than corrected on a
+guess, since that count cannot be attributed to the baked 3.9.0 server without
+measuring it.
+
+## v1.9.0 — 2026-09-10
+
+**`shellcheck` is now in the image, because the release gate it depends on could
+not be run by anyone.** v1.8.14 made shell lint a release gate: `scripts/lint-shell.sh`
+became the single source of truth for `lint.yml` and a new `lint-gate` job that
+`resolve-versions` depends on, and it deliberately exits 2 when `shellcheck` is
+absent — *a gate that cannot run must not pass*. Measured on v1.8.14 on
+2026-09-09, by three routes (`command -v`, `dpkg -l`, a filesystem search):
+**`shellcheck` was not in the image at all.** So `bash scripts/lint-shell.sh`
+exited 2 in every devbox container, and the only place the gate could ever run
+was CI. The developer loop was therefore write-shell → push → wait for CI →
+discover — which is the loop the gate was added to shorten, after v1.8.14's first
+attempt burned ~46 minutes on a tree whose lint had already been red for 24
+hours. Added to the `apt-get` block in `Dockerfile.base`: `shellcheck 0.10.0-1`,
+~39 MB installed (`Installed-Size` 40112 KB), and measured to pull **zero**
+additional packages under `--no-install-recommends` because its three deps
+(`libc6`, `libffi8`, `libgmp10`) are already present. **This forces one full base
+rebuild** — `base-decide` hashes `Dockerfile.base` + `rootfs/`, so unlike a
+`scripts/` change it cannot reuse the existing `base-` layer.
+
+**A client-side pre-push lint gate: `hooks/pre-push`.** Opt-in per clone with
+`git config core.hooksPath hooks`, bypass with `git push --no-verify`, matching
+the idiom the `skillset` and `myconfigs` repos already use. It is a thin wrapper
+that `exec`s `scripts/lint-shell.sh` — the same script CI runs, one copy, because
+a duplicated check that drifts is the failure this repo keeps paying for (the
+`pi-extensions` skill mirror sat 9579 B behind for weeks; the shell-lint logic
+was extracted to one file for exactly this reason).
+
+> **Why this repo had no hooks at all, which is worth stating because it was
+> reported as drift and is not.** A fleet peer asked `tor-ms22` to report
+> `git config core.hooksPath` per clone on the premise that an unset value meant
+> "no secret-scan and no shell-lint hook locally", leaving the drift/secret gates
+> unverified. Measured: `pi-devbox` **unset**, `skillset` `hooks`, `myconfigs`
+> `common/hooks`, `pi-toolkit` **unset**. But `git ls-files | grep -i hook` is
+> **empty** in both `pi-devbox` and `pi-toolkit` — neither repo tracked a single
+> hook file, so there was nothing for `core.hooksPath` to point at on any machine
+> and unset was the only correct value. The two repos that do ship hooks were
+> already wired correctly. This entry closes the real half of that gap for
+> `pi-devbox`; `pi-toolkit` still ships none.
+
+**The hook is verified to catch the defect that motivated it, not merely to
+exist.** Three measurements, each with the expected result written down first:
+
+- **Refusal paths.** With `shellcheck` absent (the state of every container built
+  before this change) the hook exits **2** and names the remedy; with
+  `scripts/lint-shell.sh` missing it also exits **2**. It never waves a push
+  through on the assumption that CI will catch it.
+- **The hook is actually in the scan set.** `lint-shell.sh` reports `Checking 14
+  shell file(s)` with `hooks/pre-push` present and **13** with it moved aside — so
+  the extensionless file is discovered by the shebang half of the linter's
+  two-signal union, rather than being silently skipped. This check exists because
+  the first attempt at it was ambiguous: a planted `[ $UNSET_VAR = "x" ]` was not
+  reported, which could equally have meant "file not scanned" or "defect below
+  `-S error`". It was the latter. A count that moves is unambiguous; a clean run
+  is not.
+- **It catches the real v1.8.14 defect.** Planting the exact failing shape — an
+  apostrophe inside a single-quoted string, `echo 'the fleet\'s thing'` — in
+  `hooks/pre-push` produces `SC1073`/`SC1072` at severity **error** and `rc=1`.
+  That is the defect that closed a string, truncated an `exec_test` body, sent its
+  tail to the runner's shell, and cost a 46-minute build.
+
+**The gate earned its keep inside the commit that added it.** The first version of
+the `smoke-test.sh` assertion above carried a comment beginning `# shellcheck is a
+GATE DEPENDENCY…`. A comment whose first word is the tool's name is parsed as a
+**shellcheck directive**, not a comment, so the new gate immediately failed with
+`SC1073`/`SC1072` at severity error — on the change that introduced it. Same family
+as the v1.8.14 apostrophe: a line that reads as prose to a human and as syntax to
+the parser. Before this change that defect would have been discovered in CI.
+
+**Also queued, not yet pinned:** the `mempalace-toolkit` owed-set derivation now
+honours a requester withdrawing its *own* ask (`isWithdrawn`, RFC 003 §3.3
+clause 4, with `scripts/test-owed-withdrawal.sh`) — toolkit commit **`e2b060a`**,
+which is the minimum revision for the behaviour. This image still pins `e45f6b4`.
+Until an image bakes `e2b060a` or later, a sender must assume its withdrawal has
+no effect on the recipient's mailbox — measured cost of the gap: a withdrawn
+v1.8.13 rollout ask was still being reported as owed on `tor-ms22` 41 hours later,
+for a release that device never installed. The same commit also anchors the
+derivation's `mine` query at the newest end (`order: "desc"`); with the previous
+default `asc` + `limit: 100`, a device passing 100 authored events would have its
+recent replies fall out of the join window and see answered asks resurface.
+
+**Four small packages, each chosen from a gap that was measured rather than
+imagined.** All four were picked by looking back at a real session — the
+`gitea.egl.lan`/FreeIPA debugging of 2026-09-09..10 — and asking which absences
+actually cost time, not which tools sound useful. `bind9-dnsutils` (~6.1 MB, 10
+packages): `dig`, `host` **and** `nslookup` were all absent, so the container
+could resolve names but had no way to interrogate a *specific* nameserver —
+`getent hosts` only follows the resolver's default path, so diagnosing "gateway
+`172.16.88.1` NXDOMAINs the `egl.lan` zone while `10.20.253.1` is authoritative
+for it" had to be hand-rolled in `python3`. Note the package name: plain
+`dnsutils` is transitional in trixie. `ldap-utils` (1244 KB, **zero** extra deps):
+the fleet authenticates against FreeIPA, yet every LDAP probe had to be run by
+SSHing to an already-enrolled host; this gives simple binds only, since GSSAPI
+would additionally need `krb5-user` + `libsasl2-modules-gssapi-mit`, which is a
+Kerberos-client decision rather than a tool. `xxd` (198 KB) is frank convenience
+— `od -c` already does the job. `python3-yaml` (552 KB, zero extra deps) is the
+shellcheck story repeating exactly: `scripts/check-workflow-shell.sh`, the guard
+against the Gitea `sh`/dash footgun that broke `resolve-versions` (`ed49b8d`) and
+`promote-base-latest` (`b7197e8`), hard-exits with "python3 yaml module missing"
+without it — and `lint.yml` installing it explicitly in CI was the evidence the
+image lacked it. **`netcat-openbsd` was proposed and deliberately rejected**:
+measured redundant, because `socat` is already baked and bash's `/dev/tcp` does
+reachability checks with zero packages. The reason is recorded in
+`Dockerfile.base` so the omission reads as a decision rather than an oversight.
+
+**The vendored `pi-extensions` skill floor was 41 days stale, and is now gated so
+it cannot silently rot again.** `rootfs/usr/local/share/pi-devbox/skills/pi-extensions/`
+sat at 34284 B, untouched since `fa04d20` (2026-07-30), while the package copy
+was 38973 B — four copies of one skill existed across the fleet with three
+different sizes. `Dockerfile.variant` copies the freshly-cloned package copy over
+the **served** path but never writes back to the repo floor, so nothing in the
+repo ever noticed. That is worse than ordinary staleness because the floor is a
+**fallback**: the copy is guarded by `if [ -f /opt/pi-extensions/skill/SKILL.md ]`,
+so a build whose clone yields no `skill/` keeps the vendored snapshot and still
+goes **green**, with no manifest flag and no label recording which copy was
+served — the image would ship a July skill and nothing would say so. The floor is
+refreshed here from `pi-extensions@c64c122`, and the new `skill-floor` job in
+`lint.yml` runs `scripts/check-skill-floor.sh` to keep it that way.
+
+The check compares the **directory** hash, using the same `tree_sha256` pipeline
+`Dockerfile.variant` uses for `skillset_snapshot_tree_sha256` and for the same
+documented reason: a `sha256sum SKILL.md` answers "did this one file change", not
+"is this the same skill", and `pi-extensions` ships two files. That is not
+hypothetical — it was **verified by negative control**: with `SKILL.md` left
+byte-identical and only `evaluate-extension-usage.py` edited, the directory check
+correctly fails while a file-only compare would have passed. Exit codes are `0`
+in sync / `1` drift / `2` cannot-run, matching `scripts/lint-shell.sh`, so an
+unreachable package repo is a red `2` rather than a green tick. Gating on another
+repo is normally a smell; it is proportionate here because the check can only
+fire when `skill/` itself changed — which is exactly when the floor has gone
+stale — and it needs no secret, since `pi-extensions` is anonymously clonable
+(verified with `git ls-remote` and no credentials).
+
+> **What this does *not* fix, stated so nobody reads more into it than is there.**
+> The floor is now fresh and guarded, but the *silent-fallback* half remains:
+> if the build-time copy is ever absent, the build still succeeds with no
+> manifest flag or OCI label recording that the vendored snapshot was served
+> instead of the package copy. The durable fix for that is a manifest field
+> alongside the existing `skillset_snapshot_tree_sha256`, which this change does
+> not add.
+
+**Four pinned dependencies bumped, after an audit of everything the image gets
+from outside apt.** The audit itself is the useful part: of ~23 externally-managed
+components, the 19 that resolve `latest` at build time were already current or
+refresh themselves on the next rebuild, and the hard pins for `pi` (0.85.1),
+`mempalace` (3.9.0) and `pi-atelier` (v0.10.1) were all already the newest
+available. Only four needed a human.
+
+**`NODE_VERSION` 22 → 24 (LTS "Krypton") — this one was a latent defect, not
+housekeeping.** `agent-browser` publishes `engines.node ">=24.0.0"`, so the image
+was *below a declared requirement*: v1.8.14 shipped node 22.23.2 with
+`agent-browser` 0.37.1, meaning every build installed it with an npm `EBADENGINE`
+warning and then ran the baked browser automation outside its supported range.
+The other two npm consumers are satisfied either way — `pi` declares `>=22.19.0`,
+`playwright` `>=20`. Verified before bumping, because a missing NodeSource suite
+would break every architecture at once: `setup_24.x` returns HTTP 200 and the
+`node_24.x` suite advertises `Architectures: amd64 arm64 armhf x86_64`, covering
+both the arm64 fleet and the amd64 CI runners. Nothing else in the repo pinned the
+node major.
+
+**`actionlint` 1.7.7 → 1.7.12 and `hadolint` 2.14.0 → 2.15.1**, each run against
+the current tree at the new version *before* being pinned — both clean, no new
+findings. That ordering is the point: a linter bump is the one dependency update
+that can turn CI red on unchanged code, so discovering it locally costs a minute
+and discovering it in CI costs a round trip.
+
+**`SKILLSET_SNAPSHOT_REF` `e9e09d9` → `4d7c0ea`**, via
+`scripts/vendor-mempalace-skill.sh` rather than by hand, because that script is
+the only thing that may write the ARG — a `cp` without a matching bump produces a
+manifest that confidently lies. This turned out to be **provenance-only**: the
+recorded ref was 6 commits behind, but `skills/mempalace/SKILL.md` is byte-identical
+at both (`3675bfab…`), so the vendored snapshot was already correct and only its
+recorded origin was stale. Consequently no `rootfs/` bytes changed, the
+smoke-test phrase canary stays valid, and this ARG alone would not have forced a
+base rebuild — the node bump does that anyway.
+
+**The silent-fallback hole is closed: the image now records WHICH `pi-extensions`
+skill copy it shipped.** This was the half deliberately left open by the
+`skill-floor` gate above, and it is the more important half, because "the floor is
+currently fresh" is a fact with a shelf life while "the image says which copy it
+got" keeps working. The refresh step in `Dockerfile.variant` is guarded by
+`if [ -f /opt/pi-extensions/skill/SKILL.md ]`, so a build whose clone predates the
+co-located skill kept the vendored floor and still succeeded **green**, with
+nothing in the manifest, the labels or the logs distinguishing that from a normal
+build. The two outcomes are indistinguishable by inspection afterwards — same
+path, same filenames, same permissions — which is exactly how the floor went
+unnoticed from 2026-07-30 to 2026-09-10.
+
+`build-manifest.json` gains `pi_extensions_skill_source` and
+`pi_extensions_skill_tree_sha256`, both **measured rather than passed in as
+build-args**, per the ground-truth rule the rest of that block already follows —
+and necessarily so here, since the outcome depends on the clone's contents and no
+ARG could express it. Three values, because two would force a lie:
+`package` (served bytes equal the clone's `skill/`), `vendored-floor` (the clone
+had no `skill/` at this ref, so the fallback shipped), and `divergent` — both
+exist but differ, e.g. the clone ships `SKILL.md` but not
+`evaluate-extension-usage.py`, leaving the served directory a genuine **mix** of
+package and floor. No OCI label mirrors these, deliberately: `LABEL` cannot take a
+value computed in a `RUN`, and a label fed from an ARG would be precisely the
+claim-not-measurement this change exists to remove.
+
+Two `scripts/smoke-test.sh` assertions turn the record into a gate: one that the
+source is named and is `package` — `vendored-floor` **fails** rather than warns,
+since these images track `main` where the package has co-located `skill/` since
+`fa04d20`, so a fallback means the clone did not resolve as intended — and one
+that recomputes the tree hash over the served directory, because a recorded hash
+that is never recompared is a claim rather than a measurement. `pi-devbox-version`
+also annotates the line: `pi-extensions  baked (package copy)` on the normal path,
+and a yellow `(FALLBACK: vendored floor — clone had no skill/)` otherwise. Its
+existing skill section reports which copy is being **read** at runtime; this is
+the one fact that is decided at **build** time and cannot be recovered later.
+Older images degrade cleanly — the field is absent, `jq // empty` yields nothing,
+and the line prints plain `baked` exactly as before.
+
+**This image also carries a real fix for the recurring
+`[mempalace ext] feed (tick) failed: mine timed out after 30000ms` message** that
+has been appearing in the pi TUI across the fleet since August
+(`mempalace-toolkit` `309980b` + `e68ee20`, picked up because CI resolves
+`MEMPALACE_TOOLKIT_REF` to a commit SHA at build time). It was parked as cosmetic
+on 2026-08-27 and it was not cosmetic: `lastFeedAt` was recorded only after a
+*successful* wait, but the extension's `Promise.race` abandons only the **wait**
+and cannot cancel the mine, so a timeout left the 10-minute debounce clock stale
+— and with `feedInFlight` already cleared, **both** guards stood open and every
+following settled turn started another mine on top of the one still running.
+Overlapping writers on a single-writer palace, each making the next slower and
+the next timeout likelier, which is why the message appeared many times per
+session instead of at most once per debounce window. Simulated over ten minutes
+of settled turns with a 60s mine: **16 mines launched, 15 of them overlapping**
+before; **2 and 0** after. Nothing was ever lost — the transcript is staged
+before the mine and `mine --mode convos` is idempotent — so this was wasted work
+and a misleading error, not data loss. The deadline also rose from 30s to 5
+minutes: the mine is the slowest call the extension makes (30–60s normally) yet
+carried the tightest deadline, 4x tighter than the `prepare` before it and 10x
+tighter than the init handshake. On a healthy fleet the message should now be
+absent; if it appears it is informative — a mine exceeding five minutes.
+
+---
+
 ## v1.8.14 — 2026-09-08

 > **First release attempt failed; fixed in this same entry.** The `smoke` and
@@ -94,7 +94,7 @@ The entrypoint deploys/registers all of these on first container start. Re-runni
  uv run --with jupyterlab jupyter lab --no-browser --port 8888
  uv run --with marimo marimo edit
  ```
- **Node.js** v22 + npm (used by pi itself)
+- **Node.js** v24 LTS + npm (used by pi itself)
 - **Rust** — `rustup-init` is on PATH; install toolchains on demand
 - **Go** — opt-in via `--build-arg INSTALL_GO=true` if rebuilding from source

@@ -101,6 +101,80 @@ ENV DEBIAN_FRONTEND=noninteractive
 #                  container: `ss` lands at /usr/bin/ss, `ip` at /usr/sbin/ip
 #                  (both already on the developer PATH), and `portcheck --all`
 #                  then correctly identifies the socat listener on 8765.
+#   shellcheck   — shell linter. Added 2026-09-09 to close a CAPABILITY gap, not
+#                  a style preference. `scripts/lint-shell.sh` is the release
+#                  GATE (the `lint-gate` job that `resolve-versions` depends
+#                  on), and it correctly refuses to pass when shellcheck is
+#                  missing — "a gate that cannot run must not pass". Measured on
+#                  v1.8.14: shellcheck was absent from this image by all three
+#                  routes (PATH, dpkg, filesystem), so `bash
+#                  scripts/lint-shell.sh` exited 2 in EVERY devbox container and
+#                  no developer could run the release gate locally at all. The
+#                  loop was therefore write-shell → push → wait for CI → discover,
+#                  which is the loop the gate was added to shorten: v1.8.14's
+#                  first attempt burned ~46 min on a tree whose lint had already
+#                  been red for 24 h. This is also what makes a client-side
+#                  pre-push hook possible (see hooks/pre-push); without the
+#                  binary that hook would refuse every push. ~39 MB installed
+#                  (Installed-Size 40112 KB, shellcheck 0.10.0-1) and measured
+#                  to pull ZERO additional packages under
+#                  --no-install-recommends: its deps (libc6, libffi8, libgmp10)
+#                  are already present. NOTE this file feeds the base-decide
+#                  hash (Dockerfile.base + rootfs/), so adding it forces one
+#                  full base rebuild.
+#   bind9-dnsutils — `dig` and `nslookup`. Added 2026-09-10 to close a
+#                  DIAGNOSTIC gap measured during the gitea.egl.lan/FreeIPA
+#                  work: the container could resolve names but had NO way to
+#                  ask a SPECIFIC nameserver anything. `getent hosts` only
+#                  follows the resolver's default path, so the whole "gateway
+#                  172.16.88.1 returns NXDOMAIN for the egl.lan zone while
+#                  10.20.253.1 is authoritative for it" diagnosis had to be
+#                  hand-rolled in python3 — dig, host AND nslookup were all
+#                  absent. `dig @10.20.253.1 freeipa-4.egl.lan` is the
+#                  one-liner that replaces it, and split-horizon DNS is a
+#                  recurring class of bug on this fleet, not a one-off. NOTE
+#                  the package to name is bind9-dnsutils: plain `dnsutils` is
+#                  a transitional package in trixie. ~6.1 MB total (6210 KB
+#                  measured): bind9-dnsutils 721 KB + bind9-host 161 KB +
+#                  bind9-libs 3804 KB plus 7 small libs (libfstrm0,
+#                  libjson-c5, liblmdb0, libmaxminddb0, libprotobuf-c1,
+#                  liburcu8t64, libuv1t64) under --no-install-recommends.
+#   ldap-utils   — `ldapsearch`/`ldapmodify`. Added 2026-09-10. This fleet
+#                  authenticates against FreeIPA (EGL.LAN), and every LDAP
+#                  probe during the Gitea auth work had to be run by SSHing to
+#                  an already-enrolled host because the container had no LDAP
+#                  client at all. 1244 KB and pulls NOTHING extra under
+#                  --no-install-recommends — its deps (libldap, libsasl2) are
+#                  already present. CAVEAT: this gives SIMPLE binds only,
+#                  which is what Gitea itself uses and what most probes need.
+#                  GSSAPI binds (`ldapsearch -Y GSSAPI`) additionally require
+#                  krb5-user + libsasl2-modules-gssapi-mit, deliberately NOT
+#                  added here — that is a Kerberos-client decision with
+#                  /etc/krb5.conf implications, not just a tool.
+#   xxd          — hex dump. 198 KB, no extra deps. Convenience, and honestly
+#                  marginal: `od -c` from coreutils is always present and does
+#                  the same job. Earned its place because verifying that
+#                  git-crypt actually encrypted a staged blob (the \0GITCRYPT\0
+#                  magic) is a recurring check in myconfigs and xxd is the
+#                  muscle-memory command for it.
+#                  NOT added — netcat-openbsd (133 KB): measured redundant on
+#                  2026-09-10, because socat is already baked above AND bash's
+#                  /dev/tcp does reachability checks with zero packages
+#                  (verified against gitea.egl.lan:3000). Recorded here so the
+#                  omission reads as a decision rather than an oversight.
+#   python3-yaml — PyYAML. Added 2026-09-10 for precisely the same reason as
+#                  shellcheck above: a gate this repo ALREADY OWNS could not be
+#                  run locally by anyone. scripts/check-workflow-shell.sh — the
+#                  guard that catches the "bash-only syntax under Gitea's default
+#                  sh/dash shell" footgun that broke resolve-versions (ed49b8d)
+#                  and promote-base-latest (b7197e8) — hard-exits with "ERROR:
+#                  python3 yaml module missing" without it. lint.yml installs it
+#                  explicitly in CI (`shellcheck python3-yaml`), which is itself
+#                  the evidence that the image lacked it. Measured 2026-09-10
+#                  while wiring the skill-floor job: the guard could not be run
+#                  before pushing — the same write → push → wait-for-CI loop that
+#                  shellcheck was baked to shorten. 552 KB, and pulls ZERO extra
+#                  packages under --no-install-recommends.
 RUN apt-get update && \
    apt-get upgrade -y --no-install-recommends && \
    apt-get install -y --no-install-recommends \
@@ -120,6 +194,7 @@ RUN apt-get update && \
    make \
    patch \
    diffutils \
+    shellcheck \
    git-crypt \
    age \
    file \
@@ -141,6 +216,10 @@ RUN apt-get update && \
    kitty-terminfo \
    ncurses-term \
    iproute2 \
+    bind9-dnsutils \
+    ldap-utils \
+    xxd \
+    python3-yaml \
    && ln -s /usr/bin/fdfind /usr/local/bin/fd \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*
@@ -554,7 +633,17 @@ ENV COLORTERM=truecolor
 ENV PATH="/home/developer/.local/bin:/home/developer/.cargo/bin:${PATH}"

 # ── Node.js (required for pi + MCP servers + tldr) ──
-ARG NODE_VERSION=22
+# 24 (LTS "Krypton"), raised from 22 on 2026-09-10 because the image was BELOW a
+# DECLARED requirement, not merely behind the newest release: `agent-browser`
+# publishes engines.node ">=24.0.0", so every build on 22 installed it with an npm
+# EBADENGINE warning and then ran it outside its supported range — measured on
+# v1.8.14, which shipped node 22.23.2 with agent-browser 0.37.1. The other two npm
+# consumers are satisfied either way: pi declares ">=22.19.0" and playwright
+# ">=20". Verified before bumping, because a missing NodeSource suite would break
+# the build for every arch at once: deb.nodesource.com/setup_24.x returns HTTP 200
+# and the node_24.x suite advertises `Architectures: amd64 arm64 armhf x86_64`, so
+# both the arm64 fleet and the amd64 CI runners resolve.
+ARG NODE_VERSION=24
 RUN curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors https://deb.nodesource.com/setup_${NODE_VERSION}.x | bash - && \
    apt-get install -y --no-install-recommends nodejs && \
    rm -rf /var/lib/apt/lists/*
@@ -392,7 +392,7 @@ ARG MEMPALACE_TOOLKIT_REF=main
 # no ~67-minute base rebuild. (scripts/check-base-hash.sh scans only
 # Dockerfile.base, so no folding into the base hash is required — nor would
 # it be correct, since this ARG changes nothing about the base's contents.)
-ARG SKILLSET_SNAPSHOT_REF=e9e09d95f92670536a199fc986dfa24d787f18d1
+ARG SKILLSET_SNAPSHOT_REF=4d7c0ea9caeb3a1d6d9b04cf34f3fca5f9df4985

 # Dockerfile.base sets description="pi-devbox — base image (variant-independent)"
 # and every variant INHERITS it, so both published images used to advertise
@@ -473,6 +473,44 @@ RUN set -e; \
    if [ -d "$_snap_dir" ] && [ -n "$(find "$_snap_dir" -type f -print -quit)" ]; then \
      SKILL_SNAP="\"$(tree_sha256 "$_snap_dir")\""; \
    fi; \
+    # ── WHICH pi-extensions skill copy actually shipped ──
+    # Closes the silent-fallback hole. The refresh step above is guarded by
+    # `[ -f /opt/pi-extensions/skill/SKILL.md ]`, so a build whose clone predates
+    # the co-located skill (or a fork pointing at a mirror without it) keeps the
+    # vendored floor and still succeeds — GREEN, with nothing anywhere recording
+    # that a snapshot shipped instead of the package copy. Measured 2026-09-10:
+    # the floor had been stale since 2026-07-30, so that fallback would have
+    # shipped a six-week-old skill silently. The floor is fresh now and gated by
+    # the skill-floor CI job, but "the fallback is currently harmless" is not the
+    # same as "you can tell which copy you got", and only the second survives.
+    #
+    # MEASURED, never claimed, per the ground-truth rule above: the branch
+    # condition is re-derived from the same test the refresh step used, and the
+    # served bytes are then compared against the clone. A build-arg could not
+    # express this at all, since the outcome depends on the clone's contents.
+    #   package        served bytes == the clone's skill/  (the normal path)
+    #   vendored-floor the clone has no skill/ at this ref  (fallback shipped)
+    #   divergent      both exist but differ — e.g. the clone ships SKILL.md but
+    #                  not evaluate-extension-usage.py, so the served directory is
+    #                  a MIX of package and floor. Worth its own value: it is the
+    #                  one state neither of the other two names honestly.
+    # No OCI label mirrors this, deliberately: LABEL cannot take a value computed
+    # in a RUN, and a label fed from an ARG would be exactly the claim-not-
+    # measurement this block exists to avoid.
+    _px_dir=/usr/local/share/pi-devbox/skills/pi-extensions; \
+    PIEXT_SRC='null'; PIEXT_HASH='null'; \
+    if [ -d "$_px_dir" ] && [ -n "$(find "$_px_dir" -type f -print -quit)" ]; then \
+      PIEXT_HASH="\"$(tree_sha256 "$_px_dir")\""; \
+      if [ -f /opt/pi-extensions/skill/SKILL.md ]; then \
+        if [ "$(tree_sha256 "$_px_dir")" = "$(tree_sha256 /opt/pi-extensions/skill)" ]; then \
+          PIEXT_SRC='"package"'; \
+        else \
+          PIEXT_SRC='"divergent"'; \
+        fi; \
+      else \
+        PIEXT_SRC='"vendored-floor"'; \
+      fi; \
+    fi; \
    { \
      echo '{'; \
      echo "  \"release_tag\": \"${RELEASE_TAG}\","; \
@@ -493,6 +531,8 @@ RUN set -e; \
      # vendored skill directory, not one file — see tree_sha256() above.
      echo "  \"skillset_snapshot_ref\": \"${SKILLSET_SNAPSHOT_REF}\","; \
      echo "  \"skillset_snapshot_tree_sha256\": ${SKILL_SNAP},"; \
+      echo "  \"pi_extensions_skill_source\": ${PIEXT_SRC},"; \
+      echo "  \"pi_extensions_skill_tree_sha256\": ${PIEXT_HASH},"; \
      echo "  \"components\": {"; \
      echo "    \"pi-toolkit\": \"$(rev /opt/pi-toolkit)\","; \
      echo "    \"pi-extensions\": \"$(rev /opt/pi-extensions)\","; \
@@ -175,12 +175,10 @@ Currently published:
 | `joakimp/pi-devbox:latest-studio` | `latest` + [pi-studio](https://github.com/omaclaren/pi-studio) (browser prompt editor, KaTeX/Mermaid preview, tmux-backed literate REPLs) | ~3.25 GB |
 | `joakimp/pi-devbox:vX.Y.Z-studio` | pinned-version studio equivalent | ~3.25 GB |

-Planned for an upcoming minor release:
-
- *(shipped in Unreleased/base)* **PDF export from Studio/pandoc** now works:
-  the base image ships **`typst`** as the PDF engine (`pandoc --pdf-engine=typst`),
-  a single ~30 MB static binary — no separate `-tex` variant needed.
-  `texlive-xetex` stays the higher-fidelity fallback (install on demand).
+Both variants ship **`typst`** as the pandoc PDF engine
+(`pandoc --pdf-engine=typst`), a single ~30 MB static binary, so PDF export from
+Studio/pandoc works out of the box — no separate `-tex` variant needed.
+`texlive-xetex` stays the higher-fidelity fallback (install on demand).

 ## Using pi-studio (`-studio` variant)

@@ -919,16 +917,23 @@ through `jq` yourself:

 ```console
 $ pi-devbox-version
-pi-devbox v1.5.0
-  built:  2026-07-13T17:53:16Z  (source d68674d11e06)
-  pi:     0.80.6
+pi-devbox v1.8.14
+  built:  2026-09-08T21:54:07Z  (source 361babd4fd61)
+  pi:     0.85.1
+  palace: 3.9.0
  components:
-    pi-toolkit: 9a8f6faeaa08
-    pi-extensions: 61c98e004e3d
-    pi-fork: 4a09af4ef527
-    pi-observational-memory: 27a5195eaf90
-    mempalace-toolkit: 96699f2a1781
-    pi-studio: 2ef38ef31cea
+    pi-toolkit: adfb553f5c8a
+    pi-extensions: 2610545c83bb
+    pi-fork: e69725c39603
+    pi-observational-memory: ce9fc982b3a2
+    pi-atelier: 734258bbcb62
+    mempalace-toolkit: e45f6b430181
+    pi-studio: e04fc7aa3275
+  skills:
+    credential-incident-response baked
+    mempalace              live /workspace/skillset @ 4d7c0ea  (identical to baked snapshot)
+    pi-devbox-environment  baked
+    pi-extensions          baked
 ```

 It also flags **live drift** — if `pi --version` no longer matches what was
@@ -1093,7 +1098,7 @@ persisted volumes survived, and pi runtime wiring is intact:
 ```bash
 ./scripts/recreate-sanity-check.sh                              # auto-detects variant
 ./scripts/recreate-sanity-check.sh --expected-image-version 1.8.9  # assert the pi-devbox release tag
-./scripts/recreate-sanity-check.sh --expected-version 0.84.4        # assert the pi coding agent version
+./scripts/recreate-sanity-check.sh --expected-version 0.85.1        # assert the pi coding agent version
 ```

 Those are **two different versions**, and the flags are not interchangeable:
@@ -1132,9 +1137,9 @@ resolved to `latest` at build time:

 | Component | Pin | Where |
 |---|---|---|
-| pi | `0.84.4` | `ARG PI_VERSION` — `Dockerfile.variant` |
-| pi-atelier | `v0.10.0` | `ARG PI_ATELIER_REF` — `Dockerfile.variant` |
-| mempalace | `3.8.0` | `ARG MEMPALACE_VERSION` — `Dockerfile.base` |
+| pi | `0.85.1` | `ARG PI_VERSION` — `Dockerfile.variant` |
+| pi-atelier | `v0.10.1` | `ARG PI_ATELIER_REF` — `Dockerfile.variant` |
+| mempalace | `3.9.0` | `ARG MEMPALACE_VERSION` — `Dockerfile.base` |

 The objective is **not** to freeze versions. Bumping is routine — usually one
 line plus a changelog note. The objective is that adopting a new upstream
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Pre-push gate for pi-devbox: shellcheck every shell script before it leaves
+# this clone. Thin wrapper — all logic lives in scripts/lint-shell.sh, which is
+# the SAME script the CI release gate runs. One copy, not two: a duplicated
+# check that drifts is the failure this repo keeps paying for.
+#
+# Install per clone:  git config core.hooksPath hooks
+# Bypass this gate:   git push --no-verify   (a guard, not a wall)
+#
+# WHY THIS HOOK EXISTS
+#   v1.8.14's first release attempt died at scripts/smoke-test.sh:770 after
+#   build-base had already spent ~46 minutes. shellcheck had ALREADY caught the
+#   defect — SC2289 at severity error, on the very push that introduced it — and
+#   the lint job stayed red for 24 hours, unread, across three runs. The fix at
+#   the time was to gate the release on the same script (the `lint-gate` job).
+#   This hook is the cheaper end of that: the same finding, before the push,
+#   in seconds rather than after a 40 s CI gate or a 46 min build.
+#
+# WHY IT COULD NOT EXIST UNTIL NOW
+#   Measured on v1.8.14 (2026-09-09): shellcheck was absent from the devbox
+#   image by all three routes — PATH, dpkg and a filesystem search. So
+#   lint-shell.sh exited 2 in every container, and a hook calling it would have
+#   refused EVERY push rather than gating anything. `shellcheck` was added to
+#   Dockerfile.base in the same change that added this file; on an image built
+#   before that, enable this hook and you will simply be told the gate cannot
+#   run. That is the correct behaviour, but it is not a working hook — so do not
+#   set core.hooksPath on a container older than the release that bakes it.
+#
+# NOTE ON SCOPE: this lints the WORKING TREE, not the exact commit range being
+# pushed. That is deliberate and matches what the CI gate does to the tagged
+# tree. It means a defect you have staged-but-not-committed is also reported,
+# which is noisy in the safe direction.
+set -euo pipefail
+
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$HOOK_DIR/.." && pwd)"
+LINTER="$REPO_ROOT/scripts/lint-shell.sh"
+tag="[lint-shell]"
+
+# Same rule the gate itself applies, applied one level up: a missing check is
+# not a pass. If the script is gone, the push is refused rather than waved
+# through on the assumption that CI will catch it.
+if [ ! -r "$LINTER" ]; then
+    echo "$tag refusing the push: $LINTER is missing, so the gate cannot" >&2
+    echo "$tag run. A gate that cannot run must not pass." >&2
+    exit 2
+fi
+
+# Point the message at the actual remedy when the binary is absent, because the
+# linter's own message ("install it or run this in CI") is written for a CI
+# runner and is misleading inside a container the developer cannot apt-install
+# into persistently.
+if ! command -v shellcheck >/dev/null 2>&1; then
+    echo "$tag refusing the push: shellcheck is not installed, so the gate" >&2
+    echo "$tag cannot run. A gate that cannot run must not pass." >&2
+    echo "$tag" >&2
+    echo "$tag This container predates the image that bakes shellcheck." >&2
+    echo "$tag Either recreate onto an image that has it, or unset the hook:" >&2
+    echo "$tag   git config --unset core.hooksPath" >&2
+    echo "$tag To push this once without the gate: git push --no-verify" >&2
+    exit 2
+fi
+
+exec bash "$LINTER" "$REPO_ROOT"
@@ -157,6 +157,11 @@ if [ "$SHOW_SKILLS" = "yes" ] && [ -d "$BAKED_SKILLS" ] && [ -d "$SKILLS_DIR" ];
  # is not hypothetical.
  snap_ref=$(jq -r '.skillset_snapshot_ref // empty' "$MANIFEST")
  snap_sha=$(jq -r '.skillset_snapshot_tree_sha256 // empty' "$MANIFEST")
+  # Which pi-extensions copy the BUILD baked. Distinct from everything else in
+  # this section, which reports which copy is being READ at runtime: for
+  # pi-extensions the baked tree is itself one of two possible copies, and that
+  # choice was made at build time and is not recoverable by inspection.
+  px_src=$(jq -r '.pi_extensions_skill_source // empty' "$MANIFEST")
  # Same pipeline Dockerfile.variant uses to measure the baked directory at
  # build time: relative paths in `find | sort` order, each hashed, the whole
  # listing folded into one sha256. Keep the two definitions identical — they
@@ -187,7 +192,28 @@ if [ "$SHOW_SKILLS" = "yes" ] && [ -d "$BAKED_SKILLS" ] && [ -d "$SKILLS_DIR" ];
    _target=$(readlink -f "$_link" 2>/dev/null || echo "$_link")
    case "$_target" in
      "$BAKED_SKILLS"/*|"$BAKED_SKILLS")
-        printf '    %-22s baked\n' "$_name"
+        # "baked" alone used to be the whole story. For pi-extensions it is not:
+        # the baked tree holds EITHER the package copy that Dockerfile.variant
+        # lays over the snapshot, OR the vendored floor, when the clone had no
+        # skill/ at that ref. The two are indistinguishable by inspection — same
+        # path, same filenames, same permissions — so the build records which one
+        # it used and this reports it. Without this line a six-week-stale
+        # fallback skill looks exactly like a current one, which is precisely how
+        # the floor went unnoticed from 2026-07-30 to 2026-09-10.
+        if [ "$_name" = "pi-extensions" ] && [ -n "$px_src" ]; then
+          case "$px_src" in
+            package)
+              printf '    %-22s baked (package copy)\n' "$_name" ;;
+            vendored-floor)
+              printf '    %-22s baked  \033[33m(FALLBACK: vendored floor — clone had no skill/)\033[0m\n' "$_name" ;;
+            divergent)
+              printf '    %-22s baked  \033[33m(MIXED: part package, part floor)\033[0m\n' "$_name" ;;
+            *)
+              printf '    %-22s baked\n' "$_name" ;;
+          esac
+        else
+          printf '    %-22s baked\n' "$_name"
+        fi
        continue
        ;;
    esac
@@ -1,7 +1,7 @@
 ---
 name: pi-extensions
 description: >-
-  Use the pi extensions (pi-fork, pi-observational-memory, ssh-controlmaster) effectively in the pi coding agent harness. Load this skill only when running inside pi (detection - `fork` and `recall` are present in your tool list, or `pi --ssh` was used to start the session). pi-fork dispatches focused subtasks to forked agents at fast/balanced/deep effort tiers; pi-observational-memory compacts long sessions into recallable observations + reflections; ssh-controlmaster rewires pi's read/write/edit/bash tools to execute on a remote host over a multiplexed SSH connection. This skill covers tier selection, task design, boundary discipline, when to use recall, and remote-pi mechanics.
+  Use the pi extensions (pi-fork, pi-observational-memory, ssh-controlmaster) effectively in the pi coding agent harness. Load this skill only when running inside pi (detection - `fork` and `recall` are present in your tool list, or `pi --ssh` was used to start the session). pi-fork dispatches focused subtasks to forked agents at fast/balanced/deep effort tiers; pi-observational-memory compacts long sessions into recallable observations + reflections; ssh-controlmaster rewires pi's read/write/edit/bash tools to execute on a remote host over a multiplexed SSH connection. Also covers the context ladder L0-L4 and when to reach for the separate `pi-task` CLI instead of `fork` - isolated child, immutable spec, machine-checked envelope, write-boundary diff. This skill covers tier selection, task design, boundary discipline, when to use recall, and remote-pi mechanics.
 ---

 # Pi Extensions: pi-fork, pi-observational-memory, ssh-controlmaster
@@ -161,6 +161,68 @@ The "three" things it completed were exactly the main thread's pending todos, vi
 - Distrust **quantities** and **provenance claims** in fork prose specifically ("all N sessions", "shipped with the image", "as expected") — those are the slots confabulation fills.
 - The fact that the fork was "right anyway" is not the same as the fork having followed instructions.

+### The context ladder — and the second dispatch mechanism (`pi-task`)
+
+Everything above describes a child that inherits everything. That is not a fixed
+cost of delegation — **how much context a child gets is a choice**, and `fork`
+sits at one extreme of it. Five rungs:
+
+| rung | what the child sees | mechanism | built? |
+|---|---|---|---|
+| **L0** | nothing but the goal | `pi-task` default: fresh `--session-id pitask-<id>-<stamp>` in a private `--session-dir` | yes |
+| **L1** | goal + **names** of files/commands to read itself | `pi-task` spec `context.files` / `context.commands` (`bin/pi-task:154,157`) | yes |
+| **L2** | goal + an **excerpt the parent curated** | `pi-task` spec `context.facts`, pasted verbatim (`bin/pi-task:151`) | yes |
+| **L3** | a **truncated tail** of the parent branch | *nothing implements this* — would need a new spec key plus `--session <trimmed snapshot>` | **no** |
+| **L4** | the **entire** parent branch | `fork(task=…)` — `getHeader()+getBranch()`, no offset or limit anywhere in the call chain | yes |
+
+**`pi-task` is a CLI, not an extension — it will never appear in your tool list.**
+Invoke it with `bash`: `/opt/pi-toolkit/bin/pi-task run <spec.json>` (source at
+`/workspace/pi-toolkit/bin/pi-task`, `schema` subcommand prints the spec fields).
+It reads an immutable JSON spec, and "inherit the session" is not expressible in
+that schema — the isolation is structural, not a request.
+
+**Choose the lowest rung that can do the job:**
+
+- **`fork` (L4)** when the subtask only makes sense against this conversation,
+  when you want several independent opinions in parallel from one message, or for
+  read-only exploration whose detail you will discard. Everything in "Boundary
+  discipline" above applies in full.
+- **`pi-task` (L0–L2)** when the brief contains a **prohibition** (the inherited
+  transcript is exactly what overrides those), when you want a **pass/fail**
+  result instead of prose, when you need an **audit trail**, or when writes
+  outside an authorised set must be caught.
+- **Neither** for trivial work, iterative work (both are one-shot), or judgement
+  that needs context only you have.
+
+**What `pi-task` gets you that no brief can.** The envelope must parse or the run
+FAILED, however fluent the prose. `roots[]` is the WATCHED set and
+`write_allowed` the CHANGEABLE subset, diffed before and after with git
+`--porcelain --ignored`. That `--ignored` flag is load-bearing: in the T4 test the
+child obeyed its brief perfectly and still tripped the detector, because
+`py_compile` wrote `__pycache__` into a watched-but-not-writable root — a
+gitignored path that plain `--porcelain` reports as clean. Note the structural
+point that test exposed: under `read_only: true` a write is *defiance*, so a
+well-behaved child never produces a delta and the detector is never exercised.
+Splitting WATCHED from WRITABLE is what lets an **obedient** child reveal a
+violation, which is the realistic hazard.
+
+**What it does not fix.** `--no-extensions` removes extensions, not the core
+`read`/`write`/`edit`/`bash` tools — exactly as described above — so the boundary
+diff is post-hoc **detection, not prevention**. And a fresh L0 context removes the
+*narrative* failures (parent voice, invented continuity) without removing
+confabulation: given an under-specified spec built on a false premise, the child
+still filled the `deliverable` slot with a confident shape. The envelope's own
+structure creates that pressure. Verify decisive claims from the filesystem
+regardless of which rung you used.
+
+**Trap — the capability floor is inverted from intuition.** `runner.ts:188` reads
+`if (extensions !== null) args.push("--no-extensions")`. So `pi-fork.extensions:
+[]` passes the flag and the floor is **on**; setting it to `null` — documented in
+`settings.json` as the way to "restore normal extension loading" — passes nothing
+and the floor is **off**, restoring palace writes inside every fork child.
+Changing `[]` to `null` as a tidy-up re-arms what was deliberately disarmed.
+`pi-task` hardcodes the flag and cannot drift this way.
+
 ### Anti-patterns

 - **Forking trivial work.** A fork has overhead. If the task takes < 30 seconds in your main thread, just do it.
@@ -230,7 +292,7 @@ When entries conflict, **the most recent observation reflects the latest known s
 ## Quick Reference

 ```
-fork(task=..., effort=fast|balanced|deep)
+fork(task=..., effort=fast|balanced|deep)      # L4: child inherits your WHOLE branch
  - state decision authority explicitly
  - pass verified context up front
  - specify deliverable shape
@@ -240,6 +302,13 @@ fork(task=..., effort=fast|balanced|deep)
  - write-capable? demand "What I did NOT do", then verify from git/fs, not the report
  - prohibition in the brief => not a `fast` task

+bash: /opt/pi-toolkit/bin/pi-task run <spec>   # L0-L2: isolated child, NOT a tool
+  - schema | selftest | run [--dry-run]
+  - context.facts (pasted) / .files (names only) / .commands
+  - roots[] = WATCHED, write_allowed[] = CHANGEABLE subset
+  - envelope must parse or the run FAILED
+  - audit + cost: ~/.pi/agent/pi-task/<stamp>-<id>/result.json
+
 recall(id=<12-char-hex>)
  - only when stakes justify the cost
  - id must already be visible in your context
@@ -0,0 +1,246 @@
+#!/usr/bin/env bash
+# check-doc-drift.sh — fail when a hand-maintained doc claim contradicts the
+# build files it describes.
+#
+# THE DEFECT CLASS THIS EXISTS TO CATCH, measured 2026-09-10 while preparing
+# v1.9.0. Five separate claims had rotted, all of them the same shape: a fact
+# written once by hand, in a file nothing verifies, about a value that lives
+# somewhere else and moved.
+#
+#   1..3. README.md's "Version pins" table was wrong on EVERY row — pi `0.84.4`
+#         vs ARG PI_VERSION=0.85.1, pi-atelier `v0.10.0` vs v0.10.1, mempalace
+#         `3.8.0` vs 3.9.0. That table is the worst possible place for this: it
+#         exists precisely to be the reviewable record of what is deliberately
+#         frozen, so when it lies, the review it enables is worthless.
+#   4.    README.md carried a "Planned for an upcoming minor release" section
+#         listing typst PDF export, which had ALREADY SHIPPED, tagged with a
+#         self-contradicting "(shipped in Unreleased/base)" marker. The
+#         CHANGELOG had already documented three earlier instances of exactly
+#         this stale-"Unreleased"-pointer class (see its v1.8.7 notes).
+#   5.    DOCKER_HUB.md claimed "Node.js v22" while this release ships Node 24.
+#         This one is the reason the gate exists at all: DOCKER_HUB.md is
+#         PUBLISHED. `update-description` in docker-publish.yml POSTs it to Hub
+#         as full_description on every tag, so unlike README.md — which no
+#         workflow or gate reads — a stale claim here is what users see.
+#
+# WHY A GATE AND NOT "REMEMBER TO CHECK". DOCKER_HUB.md had gone eight releases
+# (v1.8.6 → v1.9.0) without a touch. Nothing generates it and nothing verifies
+# it; the only mechanism keeping it true was whoever remembered. That is the
+# same failure mode check-skill-floor.sh was written for, and the same fix:
+# convert "someone remembers" into "CI refuses".
+#
+# WHY THESE FIVE CHECKS AND NOT MORE. Every check here compares a doc string to
+# a value that EXISTS IN THIS REPO, so it can never be wrong about the world and
+# needs no network, no token, and no built image. Claims that require a running
+# container to verify (image sizes, the "N mempalace_* tools" count) are
+# deliberately NOT gated: a check that cannot be evaluated honestly at lint time
+# would either be skipped or guessed, and a guessing gate is worse than none.
+# If you want those, assert them in scripts/smoke-test.sh where a real image is
+# available.
+#
+# DELIBERATELY NOT GATED: Dockerfile.base's `# BASE_REBUILD_DATE:` comment, which
+# is also stale (2026-07-13, three base rebuilds ago). base_tag is a hash of
+# Dockerfile.base's CONTENT plus rootfs/, comments included, so a gate that
+# demanded that comment be current would force a ~60 min base rebuild on any
+# release that touched no base files at all. Fix it when you are already
+# rebuilding the base — then it is free. This is a real cost asymmetry, not
+# laziness.
+#
+# EXIT CODES (same contract as lint-shell.sh and check-skill-floor.sh):
+#   0  every checked claim matches
+#   1  at least one claim has drifted
+#   2  cannot run (a file or ARG this gate reads is missing/unparseable)
+# A gate that cannot run must not pass, so a missing input is 2, never 0.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+README="README.md"
+HUB="DOCKER_HUB.md"
+DF_VARIANT="Dockerfile.variant"
+DF_BASE="Dockerfile.base"
+
+# Docker Hub rejects a full_description longer than this. docker-publish.yml has
+# no size check of its own; it only notices via a non-200 from the API, i.e.
+# after paying the whole build. Catching it here makes it a 2-second failure.
+HUB_MAX_CHARS=25000
+
+WARN_ONLY=0
+FAILURES=0
+
+usage() {
+  cat <<'EOF'
+Usage: check-doc-drift.sh [--warn-only] [-h|--help]
+
+Compares hand-written claims in README.md and DOCKER_HUB.md against the build
+files they describe (Dockerfile.base, Dockerfile.variant).
+
+  --warn-only   Report drift but exit 0 (advisory use, e.g. a local pre-push hook).
+
+Exit: 0 = in sync, 1 = drift, 2 = cannot run.
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --warn-only) WARN_ONLY=1; shift ;;
+    -h|--help)   usage; exit 0 ;;
+    *) echo "::error::unknown argument: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+for f in "$README" "$HUB" "$DF_VARIANT" "$DF_BASE"; do
+  if [ ! -f "$f" ]; then
+    echo "::error::$f not found (cwd $PWD). Cannot evaluate doc drift, so this is exit 2, not a pass."
+    exit 2
+  fi
+done
+
+# Read `ARG NAME=value` from a Dockerfile. Exit 2 when absent: if the ARG this
+# gate is built around has been renamed, the gate is measuring nothing and must
+# say so rather than silently comparing against an empty string.
+read_arg() {
+  local file="$1" name="$2" value
+  value="$(sed -n "s/^ARG ${name}=\\(.*\\)\$/\\1/p" "$file" | head -1)"
+  if [ -z "$value" ]; then
+    echo "::error::ARG ${name} not found in ${file}. It was probably renamed;" >&2
+    echo "::error::update check-doc-drift.sh to match, because this gate is now blind." >&2
+    exit 2
+  fi
+  printf '%s' "$value"
+}
+
+# One row of README's "Version pins" table: `| pi | `0.85.1` | ... |`
+read_pin_row() {
+  sed -n "s/^| $1 | \`\\([^\`]*\`*\\)\` |.*/\\1/p" "$README" | head -1
+}
+
+fail() {
+  FAILURES=$((FAILURES + 1))
+  echo "::error::$1"
+}
+
+ok() { printf '  OK    %s\n' "$1"; }
+
+echo "Checking hand-maintained doc claims against the build files they describe."
+echo
+
+# ---------------------------------------------------------------------------
+# 1-3. README's version-pin table vs the ARGs it names by name.
+# ---------------------------------------------------------------------------
+check_pin() {
+  local label="$1" documented="$2" actual="$3" where="$4"
+  if [ -z "$documented" ]; then
+    fail "README.md: no '| $label |' row found in the version-pin table. Either the
+      table was restructured (update this gate) or the row was dropped (restore it)."
+    return
+  fi
+  if [ "$documented" != "$actual" ]; then
+    fail "README.md version-pin table is stale for $label: says '$documented',
+      $where says '$actual'. Fix the table — it is the reviewable record of what
+      this repo deliberately freezes, so a wrong row defeats its only purpose."
+    return
+  fi
+  ok "README pin $label = $actual"
+}
+
+PI_ACTUAL="$(read_arg "$DF_VARIANT" PI_VERSION)"
+ATELIER_ACTUAL="$(read_arg "$DF_VARIANT" PI_ATELIER_REF)"
+MEMPALACE_ACTUAL="$(read_arg "$DF_BASE" MEMPALACE_VERSION)"
+
+check_pin pi              "$(read_pin_row pi)"          "$PI_ACTUAL"        "ARG PI_VERSION in $DF_VARIANT"
+check_pin pi-atelier      "$(read_pin_row pi-atelier)"  "$ATELIER_ACTUAL"   "ARG PI_ATELIER_REF in $DF_VARIANT"
+check_pin mempalace       "$(read_pin_row mempalace)"   "$MEMPALACE_ACTUAL" "ARG MEMPALACE_VERSION in $DF_BASE"
+
+# ---------------------------------------------------------------------------
+# 4. DOCKER_HUB.md's Node claim vs ARG NODE_VERSION. This is the published page,
+#    so it is the one whose staleness reaches users.
+# ---------------------------------------------------------------------------
+NODE_ACTUAL="$(read_arg "$DF_BASE" NODE_VERSION)"
+NODE_DOCUMENTED="$(sed -n 's/.*\*\*Node\.js\*\* v\([0-9][0-9]*\).*/\1/p' "$HUB" | head -1)"
+if [ -z "$NODE_DOCUMENTED" ]; then
+  fail "$HUB: could not find a '**Node.js** vNN' claim. If the wording changed,
+      update this gate; do not leave the published page unverified."
+elif [ "$NODE_DOCUMENTED" != "$NODE_ACTUAL" ]; then
+  fail "$HUB claims Node v$NODE_DOCUMENTED but ARG NODE_VERSION=$NODE_ACTUAL.
+      This file is PUBLISHED to Docker Hub by update-description on every tag,
+      and it is read from the TAG — so fix it before tagging, not after."
+else
+  ok "$HUB Node claim = v$NODE_ACTUAL"
+fi
+
+# ---------------------------------------------------------------------------
+# 5. Placeholders CI will not substitute. docker-publish.yml substitutes exactly
+#    {{PI_VERSION}} and then greps for leftovers of that ONE token, so any other
+#    {{...}} sails through the guard and is published literally.
+# ---------------------------------------------------------------------------
+UNKNOWN_PLACEHOLDERS="$(grep -o '{{[A-Za-z0-9_]*}}' "$HUB" | sort -u | grep -v '^{{PI_VERSION}}$' || true)"
+if [ -n "$UNKNOWN_PLACEHOLDERS" ]; then
+  fail "$HUB contains placeholders CI does not substitute, which would be
+      published verbatim: $(echo "$UNKNOWN_PLACEHOLDERS" | tr '\n' ' ')
+      docker-publish.yml only fills {{PI_VERSION}}; add substitution there first."
+else
+  ok "$HUB has no placeholders beyond {{PI_VERSION}}"
+fi
+
+# Match only the UPPER_SNAKE placeholder convention CI uses. A bare '{{' search
+# is WRONG here, and the first version of this check proved it by failing on
+# README.md:900 — `docker inspect --format '{{json .Config.Labels}}'`, a Go
+# template in a legitimate example, not a placeholder. The gate was wrong, not
+# the doc. Keep this anchored to [A-Z] so Go/Jinja/Handlebars examples pass.
+README_PLACEHOLDERS="$(grep -o '{{[A-Z][A-Z0-9_]*}}' "$README" | sort -u || true)"
+if [ -n "$README_PLACEHOLDERS" ]; then
+  fail "$README contains placeholder(s) nothing substitutes, so they would render
+      literally for every reader: $(echo "$README_PLACEHOLDERS" | tr '\n' ' ')
+      Only DOCKER_HUB.md gets substitution, and only for {{PI_VERSION}}."
+else
+  ok "$README has no unsubstituted placeholders"
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Hub full_description length.
+# ---------------------------------------------------------------------------
+HUB_CHARS="$(wc -c < "$HUB" | tr -d ' ')"
+if [ "$HUB_CHARS" -gt "$HUB_MAX_CHARS" ]; then
+  fail "$HUB is $HUB_CHARS chars, over Docker Hub's $HUB_MAX_CHARS-char
+      full_description limit. update-description would fail with a non-200 AFTER
+      the full build. Trim it — this file is the essentials-only page, and
+      README.md is the long form on purpose."
+else
+  ok "$HUB is $HUB_CHARS chars (limit $HUB_MAX_CHARS)"
+fi
+
+# ---------------------------------------------------------------------------
+# 7. Stale "Unreleased" pointers. "Unreleased" is a CHANGELOG-only concept; in
+#    a user-facing doc it is always a pointer that outlived what it pointed at.
+#    This class has now bitten five times, hence a gate rather than vigilance.
+# ---------------------------------------------------------------------------
+STALE_MARKERS="$(grep -n 'Unreleased' "$README" "$HUB" || true)"
+if [ -n "$STALE_MARKERS" ]; then
+  fail "'Unreleased' appears in a user-facing doc, which is always a stale
+      pointer once the thing ships (it has happened five times here):
+${STALE_MARKERS//$'\n'/$'\n'        }
+      State the fact directly, or move it to CHANGELOG.md where 'Unreleased' means something."
+else
+  ok "no stale 'Unreleased' pointers in $README or $HUB"
+fi
+
+echo
+if [ "$FAILURES" -eq 0 ]; then
+  echo "OK: every checked doc claim matches the build files."
+  exit 0
+fi
+
+echo "::error::$FAILURES doc claim(s) have drifted from the build files."
+echo
+echo "Docs are read from the TAG, not from main: docker-publish.yml checks out"
+echo "github.ref, so a fix pushed after tagging does not reach the release or the"
+echo "Hub page. Update the docs BEFORE you tag."
+
+if [ "$WARN_ONLY" -eq 1 ]; then
+  echo "(--warn-only: exiting 0 anyway)"
+  exit 0
+fi
+exit 1
@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# check-skill-floor.sh — fail when the vendored pi-extensions skill snapshot in
+# rootfs/ ("the floor") has drifted from the package repo it is a snapshot of.
+#
+# THE DEFECT THIS EXISTS TO CATCH, measured 2026-09-10.
+# rootfs/usr/local/share/pi-devbox/skills/pi-extensions/ ships a vendored copy
+# of the pi-extensions skill so the skill is ALWAYS present in the image.
+# Dockerfile.variant then copies the freshly-cloned package copy OVER the served
+# path at /usr/local/share/... — but it never writes back to the repo floor. So
+# the floor only silently rots, and it had: 34284 B, untouched since fa04d20
+# (2026-07-30), while the package copy was 38973 B. Four copies existed with
+# three different sizes.
+#
+# Why that is worse than ordinary staleness: the floor is a FALLBACK. The copy
+# step is guarded by `if [ -f /opt/pi-extensions/skill/SKILL.md ]`, so a build
+# where the package clone yields no skill/ keeps the vendored snapshot and still
+# succeeds — green, with no manifest flag and no label saying which copy was
+# served. The image would ship a July skill and nothing would say so. Keeping
+# the floor fresh means that fallback is harmless instead of a silent regression.
+#
+# WHY A DIRECTORY HASH AND NOT `sha256sum SKILL.md`.
+# The same pipeline Dockerfile.variant uses for skillset_snapshot_tree_sha256,
+# and for the same documented reason: a file-only compare answers "did this one
+# file change", not "is this the same skill". pi-extensions ships TWO files
+# (SKILL.md + evaluate-extension-usage.py), so a sibling-file edit would pass a
+# file-only check. If you change the pipeline here, change it there too.
+#
+# WHY GATING ON ANOTHER REPO IS PROPORTIONATE HERE, since that is normally a
+# smell: this fires only when the package's skill/ DIRECTORY HASH changes, which
+# is exactly and only when the floor has genuinely gone stale. pi-extensions
+# commits that do not touch skill/ leave the hash alone and cannot turn this red.
+# The repo is also anonymously clonable (verified 2026-09-10 with `git ls-remote`
+# and no credentials), so this needs no secret and cannot break on token expiry.
+#
+# Exit codes — deliberately three, matching scripts/lint-shell.sh's philosophy
+# that a gate which cannot run must not pass:
+#   0  in sync (or the package legitimately has no skill/ at this ref)
+#   1  DRIFT — the floor differs from the package
+#   2  cannot run — no package copy could be obtained
+set -euo pipefail
+
+REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+FLOOR_DIR="${REPO_ROOT}/rootfs/usr/local/share/pi-devbox/skills/pi-extensions"
+
+# Defaults mirror Dockerfile.variant's ARGs so this checks what the build builds.
+PI_EXTENSIONS_REPO="${PI_EXTENSIONS_REPO:-https://gitea.jordbo.se/joakimp/pi-extensions.git}"
+PI_EXTENSIONS_REF="${PI_EXTENSIONS_REF:-main}"
+
+PACKAGE_DIR=""
+WARN_ONLY=0
+TMPDIR_CLONE=""
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/check-skill-floor.sh [options]
+
+  --package-dir DIR   Compare against an existing skill directory instead of
+                      cloning. In a devbox container use /opt/pi-extensions/skill
+                      for a fully offline run.
+  --warn-only         Report drift but exit 0 (advisory use, e.g. a local hook).
+  -h, --help          This text.
+
+Environment: PI_EXTENSIONS_REPO, PI_EXTENSIONS_REF (default main) — both mirror
+the Dockerfile.variant ARGs of the same name.
+EOF
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --package-dir) PACKAGE_DIR="${2:-}"; shift 2 ;;
+    --warn-only)   WARN_ONLY=1; shift ;;
+    -h|--help)     usage; exit 0 ;;
+    *) echo "::error::unknown argument: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+cleanup() {
+  if [ -n "$TMPDIR_CLONE" ]; then rm -rf "$TMPDIR_CLONE"; fi
+}
+trap cleanup EXIT
+
+# Identical to Dockerfile.variant's tree_sha256(): relative paths + per-file
+# sha256 over a sorted `find`, folded into one digest. Deterministic, never
+# readdir order.
+tree_sha256() {
+  ( cd "$1" && find . -type f -print | LC_ALL=C sort | xargs -r sha256sum ) \
+    2>/dev/null | sha256sum | cut -d' ' -f1
+}
+
+if [ ! -d "$FLOOR_DIR" ]; then
+  echo "::error::floor directory is missing: ${FLOOR_DIR}"
+  echo "::error::rootfs/ is supposed to guarantee the skill is always in the image."
+  exit 2
+fi
+
+SOURCE_DESC=""
+if [ -n "$PACKAGE_DIR" ]; then
+  if [ ! -d "$PACKAGE_DIR" ]; then
+    echo "::error::--package-dir does not exist: ${PACKAGE_DIR}"
+    exit 2
+  fi
+  SOURCE_DESC="local directory ${PACKAGE_DIR}"
+else
+  command -v git >/dev/null 2>&1 || { echo "::error::git not found; cannot obtain the package copy."; exit 2; }
+  TMPDIR_CLONE=$(mktemp -d)
+  # Fetch the single ref shallowly. `git fetch <ref>` accepts a branch, a tag
+  # and (on Gitea) a reachable commit, which is why this is not `clone --branch`
+  # — CI resolves PI_EXTENSIONS_REF to a 40-hex SHA before the build.
+  if ! ( cd "$TMPDIR_CLONE" \
+          && git init -q . \
+          && git remote add origin "$PI_EXTENSIONS_REPO" \
+          && git fetch -q --depth 1 origin "$PI_EXTENSIONS_REF" \
+          && git checkout -q FETCH_HEAD ) 2>/dev/null; then
+    echo "::error::could not fetch ${PI_EXTENSIONS_REF} from ${PI_EXTENSIONS_REPO}"
+    echo "::error::Cannot determine whether the floor is stale, so this is exit 2, not a pass."
+    echo "::error::For an offline run, pass --package-dir /opt/pi-extensions/skill"
+    exit 2
+  fi
+  PACKAGE_SHA=$( cd "$TMPDIR_CLONE" && git rev-parse --short HEAD )
+  PACKAGE_DIR="${TMPDIR_CLONE}/skill"
+  SOURCE_DESC="${PI_EXTENSIONS_REPO} @ ${PI_EXTENSIONS_REF} (${PACKAGE_SHA})"
+fi
+
+# A ref with no skill/ is the documented fallback case: Dockerfile.variant keeps
+# the vendored snapshot and the build succeeds. Nothing to compare, so this is
+# not drift — but it IS the exact condition under which the floor ships, so say
+# so loudly rather than printing a silent green tick.
+if [ ! -d "$PACKAGE_DIR" ]; then
+  echo "::warning::package has no skill/ at this ref — the vendored floor is what will ship."
+  echo "  source : ${SOURCE_DESC}"
+  echo "  floor  : $(tree_sha256 "$FLOOR_DIR")"
+  exit 0
+fi
+
+FLOOR_HASH=$(tree_sha256 "$FLOOR_DIR")
+PKG_HASH=$(tree_sha256 "$PACKAGE_DIR")
+
+if [ "$FLOOR_HASH" = "$PKG_HASH" ]; then
+  echo "OK: vendored pi-extensions floor matches the package."
+  echo "  source     : ${SOURCE_DESC}"
+  echo "  tree_sha256: ${FLOOR_HASH}"
+  exit 0
+fi
+
+# `set -e` interacts badly with `[ … ] && x` as a bare statement, so both of
+# these are explicit if-blocks rather than AND-lists.
+LEVEL="error"
+if [ "$WARN_ONLY" -eq 1 ]; then LEVEL="warning"; fi
+
+echo "::${LEVEL}::vendored pi-extensions skill floor has DRIFTED from the package."
+echo "  source            : ${SOURCE_DESC}"
+echo "  floor tree_sha256 : ${FLOOR_HASH}"
+echo "  pkg   tree_sha256 : ${PKG_HASH}"
+echo ""
+echo "  per-file differences:"
+diff -rq "$FLOOR_DIR" "$PACKAGE_DIR" 2>&1 | sed 's/^/    /' || true
+echo ""
+echo "  Remedy — re-sync the floor and commit it:"
+echo "    cp -a <pi-extensions>/skill/. ${FLOOR_DIR}/"
+echo "    git add ${FLOOR_DIR#"${REPO_ROOT}/"} && git commit"
+echo ""
+echo "  NOTE this forces one full base rebuild: base_tag hashes Dockerfile.base"
+echo "  + rootfs/, and that rebuild is what re-bakes the refreshed floor."
+
+if [ "$WARN_ONLY" -eq 1 ]; then exit 0; fi
+exit 1
@@ -105,6 +105,18 @@ else
  run "node"            "node --version"
 fi
 run "git"             "git --version"
+# NOTE: the shellcheck binary is a GATE DEPENDENCY, not a convenience.
+# scripts/lint-shell.sh is the release gate (the lint-gate job resolve-versions
+# depends on) and it exits 2 when the binary is missing, by design — "a gate that
+# cannot run must not pass". Measured on v1.8.14: it was absent from the image, so
+# that gate could not be run by a developer in ANY container, only in CI.
+# Asserted here so its absence fails a build instead of being discovered by a hook
+# that then refuses every push (hooks/pre-push).
+#
+# This comment must not BEGIN with the tool's name: a line starting with
+# `# shellcheck` is parsed as a DIRECTIVE, not a comment (SC1073/SC1072). The
+# gate added in this same change caught that here, before the push.
+run "shellcheck (lint gate dependency)" "shellcheck --version | grep -qE '^version: [0-9]'"
 run "aws"             "aws --version"
 run "uv"              "uv --version"
 run "nvim"            "nvim --version"
@@ -514,6 +526,50 @@ run "manifest skill fingerprint matches the baked snapshot" '
  echo "manifest=[$m] actual=[$a]" >&2
  [ -n "$m" ] && [ "$m" = "$a" ]
 '
+
+# ── Which pi-extensions skill copy shipped ──────────────────────────────
+# Closes the silent-fallback hole. The refresh in Dockerfile.variant is guarded
+# by `[ -f /opt/pi-extensions/skill/SKILL.md ]`, so a build whose clone predates
+# the co-located skill keeps the vendored floor and still succeeds GREEN, with
+# nothing recording that a snapshot shipped instead of the package copy. Measured
+# 2026-09-10: the floor had been stale since 2026-07-30, so that path would have
+# shipped a six-week-old skill in silence. The floor is fresh now and gated by the
+# skill-floor lint job, but "the fallback is currently harmless" is a fact with a
+# shelf life, whereas "the image says which copy it got" keeps working.
+#
+# vendored-floor FAILS here rather than merely warning: these images track main,
+# where the package has co-located skill/ since fa04d20, so a fallback means the
+# clone did not resolve as intended and that is a defect to investigate. A fork
+# deliberately pointing at a mirror without skill/ is the one case that should
+# edit this assertion — which is the honest place for that decision to surface.
+run "manifest names which pi-extensions skill copy shipped" '
+  j=/etc/pi-devbox/build-manifest.json
+  s=$(jq -r ".pi_extensions_skill_source // empty" $j)
+  h=$(jq -r ".pi_extensions_skill_tree_sha256 // empty" $j)
+  echo "source=[$s] tree_sha256=[$h]" >&2
+  printf "%s" "$h" | grep -qxE "[0-9a-f]{64}" || {
+    echo "pi_extensions_skill_tree_sha256 is not a 64-hex digest" >&2; exit 1; }
+  case "$s" in
+    package) ;;
+    vendored-floor)
+      echo "FALLBACK: clone had no skill/ at this ref, so the image ships the committed floor" >&2; exit 1 ;;
+    divergent)
+      echo "MIXED: served directory is part package and part floor" >&2; exit 1 ;;
+    *)
+      echo "pi_extensions_skill_source absent or unrecognised" >&2; exit 1 ;;
+  esac
+'
+
+# Same shape as the mempalace fingerprint check above, and for the same reason: a
+# recorded hash that is never recomputed is a claim, not a measurement.
+run "recorded pi-extensions skill hash matches the served bytes" '
+  j=/etc/pi-devbox/build-manifest.json
+  d=/usr/local/share/pi-devbox/skills/pi-extensions
+  m=$(jq -r ".pi_extensions_skill_tree_sha256 // empty" $j)
+  a=$( (cd "$d" && find . -type f -print | LC_ALL=C sort | xargs -r sha256sum) | sha256sum | cut -d" " -f1)
+  echo "manifest=[$m] actual=[$a]" >&2
+  [ -n "$m" ] && [ "$m" = "$a" ]
+'
 # OCI labels live in the image config, not the container fs — inspect them
 # from the host docker rather than via `docker run`.
 LBL=$(docker inspect --format '{{ index .Config.Labels "se.jordbo.pi-devbox.pi-extensions-ref" }}' "$IMAGE" 2>/dev/null || true)