diff --git a/justfile b/justfile
index bf5e254e1ab81d1c70dda827475f6aeb836d0121..c7ce2b705cd36d810b148e470d0983574baf30b7 100644
--- a/justfile
+++ b/justfile
@@ -2,7 +2,7 @@ _default:
     @just --list
 
 # Skills backed up in this repo, installed into ~/.claude/skills (repo -> ~/.claude)
-skills := "sourcehut-ci sourcehut-custom-service"
+skills := "sourcehut-ci sourcehut-ci-cacher sourcehut-custom-service"
 
 # Absolute path to this repo (the SourceHut documentation mirror), substituted
 # into skills for the __SRHT_MIRROR__ placeholder at install time.
diff --git a/skills/sourcehut-ci-cacher/SKILL.md b/skills/sourcehut-ci-cacher/SKILL.md
new file mode 100644
index 0000000000000000000000000000000000000000..74b5e9f3a1175110e8c58cbbf2f0fa4b6130b391
--- /dev/null
+++ b/skills/sourcehut-ci-cacher/SKILL.md
@@ -0,0 +1,362 @@
+---
+name: sourcehut-ci-cacher
+description: Add or fix build caching in a builds.sr.ht manifest with either of the user's two cache backends — `cacher` (go.bigb.es/cacher, straight to Garage S3) or `art cache` (the artifacts.sr.ht client, same bucket through the daemon and no S3 credential in the build). Use whenever a .build.yml needs to cache Go module/build trees, an assembled SCSS tree, a docker image or any other directory between builds; whenever a build is slow because it recompiles or re-clones the same dependencies every time; whenever the user mentions cacher, art cache, cache_restore, cache_save, cache_setup, docker-cache, ci-cacher, `~/.s3-cache-key-id`, `~/.srht-token`, or asks how to cache anything on sourcehut; and whenever a manifest is being moved from cacher to art. Also use when copying cache stages between the `~/data/home/sourcehut-*` sibling repos, since those carry two different generations of the pattern and the older one is easy to copy by mistake. Companion to the `sourcehut-ci` skill, which covers builds.sr.ht itself — upstream sourcehut genuinely has no cache feature, and this is the local answer to that.
+license: BSD-3-Clause
+metadata:
+  audience: developers
+  workflow: ci
+  tags: [ci, sourcehut, builds.sr.ht, cache, cacher, art, artifacts.sr.ht, s3, garage, go]
+  version: 1.1.0
+  author: bigbes
+---
+
+# Build caching on sourcehut
+
+builds.sr.ht has no cache feature: every build is a fresh VM. Two local helpers
+answer that, and they are interchangeable because they address the same objects:
+
+- **`cacher`** (`go.bigb.es/cacher`) tars a directory to S3 under a
+  content-derived key, speaking S3 itself. Needs the Garage key pair.
+- **`art cache`** (the artifacts.sr.ht client) does the same through
+  `artifacts.srht.bigb.es/api/v1/cache`, so the build carries a working token
+  instead of a raw bucket credential. See "The `art` backend" below.
+
+Both land in the Garage `docker-cache` bucket on `s3.bigb.es`. Most of this
+document is about the shape of the cache stages, which is the same either way;
+where a rule differs, it says so.
+
+**Reference implementations:** `__SRHT_FAMILY__/sourcehut-coverage` and
+`__SRHT_FAMILY__/sourcehut-tokens` for the overall shape, but take `cache_restore`
+from `__SRHT_FAMILY__/sourcehut-bench` — the other two still carry a `go mod download
+all` that dirties the tracked `go.sum` (see "Never `go mod download all`"). All
+three keep the reasoning in `docs/ci.md` alongside the manifest; read
+`docs/ci.md#cacher`, `#cache_restore`, `#never-go-mod-download-all` and
+`#cache_save` before writing anything new.
+
+**For `art`:** `__SRHT_FAMILY__/sourcehut-artifacts` carries the switchable
+`cache_setup` and `publish_client`, the task that publishes the binary every
+other build installs — read `docs/ci.md#cache_setup` and `#publish_client` there.
+`__SRHT_FAMILY__/bencher/.build.yml` on `license-free/v0.6.6` is the plain hardwired
+form, and the only non-Alpine consumer.
+
+## Do not copy from the older siblings
+
+`sourcehut-spec`, `sourcehut-dolt` and `sourcehut-compare` still carry the
+pre-v0.2.0 shape. Grepping `cache` across the family returns the stale form
+three times and the current form twice, so a majority vote picks the wrong
+donor.
+
+| stale | current |
+|---|---|
+| hand-written `curl` + `chmod` + `PATH` bootstrap | `curl -sSL …/ci-cacher/install.sh \| sh` |
+| `if ! cacher dir download …; then …; cacher dir upload …; fi` | `cacher dir download <key> <dir> --exec '<script>'` |
+| `cacher dir download … \|\| true` | `cacher dir download … --optional` |
+| `cacher exists "$KEY" \|\| cacher dir upload …` | bare `cacher dir upload` |
+
+The bootstrap change is not cosmetic: `install.sh` verifies the download against
+the release's `checksums.txt`, and the hand-written `curl` + `chmod` verified
+nothing.
+
+## Manifest shape
+
+```yaml
+secrets:
+  # Account-level, shared verbatim by every sourcehut-* repo. Separation
+  # between services is the --prefix below, not the key.
+  - 7dde4219-0783-4581-a67d-c94749de3600   # ~/.s3-cache-key-id
+  - 0e5b3530-6f19-4f30-9b73-9339dd382e46   # ~/.s3-cache-key-secret
+tasks:
+  - cacher_install: |
+      curl -sSL https://bigbes.pages.srht.bigb.es/ci-cacher/install.sh | sh
+  - cacher_init: |
+      cacher init \
+        --endpoint    https://s3.bigb.es \
+        --region      garage \
+        --bucket      docker-cache \
+        --prefix      <repo>/deps \
+        --key-file    ~/.s3-cache-key-id \
+        --secret-file ~/.s3-cache-key-secret
+  - cache_restore: |
+      KEY_MOD=$(cacher key "gomod/{hash}.tar.zst"   --hash-from "$REPO/go.sum")
+      KEY_GOC=$(cacher key "gocache/{hash}.tar.zst" --hash-from "$REPO/go.sum")
+      echo "export KEY_MOD=$KEY_MOD KEY_GOC=$KEY_GOC" >> ~/.buildenv
+      cacher dir download "$KEY_MOD" ~/go/pkg/mod        --optional
+      cacher dir download "$KEY_GOC" ~/.cache/go-build   --optional
+      # see "The half-restored module cache" below — do not drop, do not soften
+      cd "$REPO"
+      chmod -R u+w ~/go/pkg/mod 2>/dev/null || true
+      if ! go mod verify >/dev/null 2>&1; then
+        echo "restored module cache did not verify — discarding it"
+        rm -rf ~/go/pkg/mod
+      fi
+      go mod download          # NEVER `all` — see below
+      go mod verify
+      git status --porcelain   # the tree must still be clean here
+  # … build / test / publish …
+  - cache_save: |
+      cacher dir upload "$KEY_MOD" ~/go/pkg/mod
+      cacher dir upload "$KEY_GOC" ~/.cache/go-build
+```
+
+## The `art` backend
+
+`art cache` is the same cache reached through the artifacts.sr.ht daemon. Two
+reasons to prefer it in a new manifest: the build carries a working token rather
+than the Garage key pair, and that token is usually mounted already for
+`publish_artifacts`, `coverage` or `bench`.
+
+**The two backends address the same objects, so switching keeps the cache warm.**
+`cachex/keys.go:objectKey` is `<cache-ns>/<key>` with no rewriting or content
+addressing, which maps onto cacher one-to-one:
+
+| cacher | art |
+|---|---|
+| `--prefix <repo>/deps` | `--cache-ns <repo>` + every key prefixed `deps/` |
+| `--key-file` / `--secret-file` | `--token-file ~/.srht-token` |
+| `cacher dir download\|upload KEY DIR` | `art cache dir download\|upload KEY DIR` |
+| `cacher docker download KEY IMAGE:TAG` | `art cache docker download KEY IMAGE:TAG` |
+| `cacher key TEMPLATE --hash-from FILE` | `art cache key TEMPLATE --hash-from FILE` |
+
+`--optional`, `--exec`, `--pull` and `{hash}` templates behave the same, so every
+rule below about `--optional`, `--exec` and `cache_save` applies unchanged.
+
+```yaml
+secrets:
+  # Carries artifacts:read (cache reads) AND artifacts:upload (cache writes).
+  - c7968415-1a6d-4ca0-a188-150fb7f57b65   # ~/.srht-token
+environment:
+  ARTIFACTS_ENDPOINT: https://artifacts.srht.bigb.es
+tasks:
+  - install_art: |
+      mkdir -p ~/.local/bin
+      curl -sSL "$ARTIFACTS_ENDPOINT/~bigbes/main/blob/art/art-linux-amd64" \
+        -o ~/.local/bin/art
+      chmod +x ~/.local/bin/art
+      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.buildenv
+      export PATH="$HOME/.local/bin:$PATH"      # ~/.buildenv reaches only LATER tasks
+      art version
+  - art_init: |
+      art init --endpoint "$ARTIFACTS_ENDPOINT" --cache-ns <repo> \
+        --token-file ~/.srht-token
+```
+
+- **The binary is a blob, not an apk and not a build step.** `sr-ht-artifacts`
+  republishes `linux/amd64` `art` to `~bigbes/main/blob/art/art-linux-amd64` on
+  every `master` build (its `publish_client` task). The channel is public, so a
+  consuming build fetches it anonymously and needs the token only for the cache
+  itself. Static `CGO_ENABLED=0`, so Alpine and Ubuntu workers both run it.
+  Note the asymmetry with cacher's `install.sh`: that one verifies the download
+  against `checksums.txt`, while this `curl` verifies nothing. The digest is
+  checked at *publish* time — `art blob push` refuses to report success unless
+  the daemon's sha256 matches what it sent — which is a guarantee about what is
+  stored, not about what a consumer received.
+- **`sr-ht-artifacts` is the one repo that must not fetch it that way** — it
+  builds `art` from its own checkout, so the cache does not depend on the service
+  twice over.
+- **A green `art_init` proves nothing about the token.** Its smoke request is
+  `GET /api/v1/channels`, which succeeds *anonymously* against a public channel.
+  What proves `artifacts:read` is a later `hit <ns>/<key> -> …` line.
+- **Do not reuse cacher-era keys for docker images.** Whether the two tools' zstd
+  framing interoperates has never been measured, and a wrong guess is not a miss:
+  it is `docker load` failing on a hit, with no `--pull` fallback behind it. Name
+  art's keys distinctly (bencher appended `.tar.zst`) and accept one cold build.
+  Directory keys written by `cacher dir upload` are the same tarball either way,
+  so `dir` keys can be carried over.
+- **Before caching a docker image at all**, check the buildx driver: with the
+  `docker-container` driver the builder has its own image store and cannot see
+  what `cache docker download` loads into the host daemon, so the task warms
+  nothing. That is a property of buildx, not of the cache backend — switching
+  cacher→art does not fix it.
+
+For a manifest that must support both, `sr-ht-artifacts` carries a
+`CACHE_BACKEND: cacher|art` switch in `cache_setup` that leaves `$CACHE` and
+`$CACHE_KEY_PREFIX` behind for later tasks. Copy that only when the choice has to
+stay open; bencher hardwires `art` and reads better for it.
+
+## Rules that are load-bearing
+
+**`cacher_install` and `cacher_init` must be two tasks.** builds.sr.ht sources
+`~/.buildenv` *before each task*, so the `PATH` export `install.sh` appends is in
+effect from the NEXT task onward, not in the one that appended it. Merging them
+means re-writing by hand the export the installer exists to remove.
+
+**Restore before the first compiler runs, not before `build`.** If the manifest
+has a `test` task, that is usually where the tree first meets a compiler; a
+restore placed after it warms nothing but the final relink.
+
+**`--optional`, never `|| true`.** `||` fires on every non-zero exit, so it also
+swallows wrong credentials, a deleted bucket and a truncated tarball — each
+becomes one line in the log and a silently cold build forever after.
+`--optional` exits 0 for a missing key and nothing else.
+
+**`cache_save` goes after `publish`, and stays fatal.** It is an optimisation for
+the *next* build and the only step talking to S3 for no reason the current build
+needs; placed earlier, an S3 hiccup fails a build whose artifact was already
+built and signed but not yet published. Keep it fatal so permanently broken
+credentials are noticed rather than quietly making every build cold.
+
+**No `cacher exists "$KEY" ||` guard.** Without `--force`, `cacher dir upload`
+does that check itself and answers `Skipped — <key> already present`, exit 0. The
+guard duplicates it one level up and duplicates it wrongly, since two separate
+commands can disagree about a key uploaded between them.
+
+**The prefix is the only tenant boundary.** Six repos share the bucket and the
+same key pair. Rename a repo and the prefix must follow — a stale prefix is not
+an error, it is a cache that never hits.
+
+## `dir download --exec` for build-it-if-missing
+
+`--exec` replaces the restore-or-build block: on a miss it creates the directory,
+runs the script through `sh -c`, and seeds the cache from what the script leaves
+behind.
+
+```yaml
+      cacher dir download "scss/${CORE_VER}-${BOOTSTRAP_REV}.tar.zst" ~/scss --exec '
+        git clone --depth 1 --branch "$CORE_VER" … /tmp/core
+        cp /tmp/core/scss/*.scss ~/scss/
+      '
+```
+
+Three things about it:
+
+- **Write the key inline; do not hoist it to a variable.** The script runs in a
+  separate shell and sees only exported values — `environment:` entries and
+  whatever an earlier task appended to `~/.buildenv`. A shell-local `KEY=…` in
+  the task body is invisible inside the script. Spelling the template out in the
+  argument lets the *outer* shell expand it before cacher sees it.
+- **Single-quote the whole `--exec` argument.** The script's own `"$VAR"`
+  references must reach `sh -c` unexpanded. Double quotes would expand them
+  outside and happen to produce the same text today — then substitute the wrong
+  thing the day a variable is set inside the script.
+- **`--exec` has no `set -e`.** The LAST command's status decides whether the
+  cache is seeded, not the first failure. That is safe only while each step feeds
+  the next. Add `set -e` at the top of the script the moment it grows a step the
+  following ones do not depend on, or you will seed a half-built tree under a key
+  that claims to be good.
+
+## Never `go mod download all`
+
+`all` resolves the whole module graph — test-only dependencies of dependencies
+included — and **appends their hashes to the TRACKED `go.sum`**. It exits 0 and
+prints nothing, so the only trace is a modified file sitting in the checkout.
+Measured in `sourcehut-bench`: 318 lines to 546.
+
+**`-mod=readonly` does not prevent it.** Readonly governs updates to the module
+*requirements*, not writes to `go.sum`. Any comment claiming otherwise was taken
+from the flag's reputation rather than from a run.
+
+It matters wherever the pipeline reads a VCS stamp: a dirtied `go.sum` makes
+every later `go build` record `vcs.modified=true`, so the packaged binary calls
+itself `<sha>-dirty`. bench's build **#359** died at `check-version` with
+`M go.sum` as the thing in the way, and every binary that pipeline produced
+between the gate landing and the fix was dirty or red.
+
+Plain `go mod download` writes nothing and costs nothing: verified against an
+empty module cache with `GOPROXY=off`, both `go build ./...` and the full
+`go test ./...` suite complete. The `all` was warming modules the build never
+compiles.
+
+Keep a `git status --porcelain` at the end of `cache_restore` regardless. It is
+what makes this class of failure visible at the task that causes it rather than
+three tasks later.
+
+**`sourcehut-coverage` and `sourcehut-tokens` still carry the `all`.** They stamp
+from an exported version string instead of the VCS state, so it never failed
+them — but it dirties their checkouts too. Copy `cache_restore` from
+`sourcehut-bench`, which is the corrected version; the rest of the pattern is
+still theirs.
+
+## The half-restored module cache
+
+The most important paragraph here, and the one that looks like removable
+boilerplate.
+
+Go writes its module cache read-only — module directories are `0555`. The
+tarball preserves those modes, so extraction creates the first module directory
+and is then **denied its own next file inside it**. Everything after that entry
+in tar order never lands. The result is a cache HIT, one swallowed
+`permission denied`, and a handful of packages failing to compile against a
+dependency missing a single file — while unrelated packages pass, so the log
+reads like a code bug. cover.sr.ht build **#284** is that failure.
+
+Two halves to the fix, and both are needed:
+
+- **`-modcacherw`** on the `go build` that populates the cache (in the APKBUILD's
+  `build()` for the apk-packaging repos), so the stored tree is writable at all.
+- **the repair block** in `cache_restore`: `chmod -R u+w`, then `go mod verify`
+  as the gate, then `rm -rf ~/go/pkg/mod` on failure. `go mod verify` recomputes
+  each extracted module's hash and is therefore the only instrument that sees a
+  file missing from a directory Go otherwise trusts on sight — `go mod download`
+  alone takes the directory's existence as proof.
+
+Never soften the verify to `|| true`. A bad restore costs one cold download,
+which is the optimisation failing, not the build failing.
+
+Note the first build after a `go.sum` change can never detect this: a miss
+extracts nothing, `go mod download` fills a clean tree, and `cache_save` then
+stores the tarball that breaks every build after it.
+
+## abuild interaction (apk-packaging repos)
+
+abuild redirects the Go caches into its throwaway `$tmpdir`, so exports from
+`cache_restore` do not survive into the package build. Worse, `abuild.in` reads:
+
+```sh
+export GOCACHE="${GOCACHE:-$tmpdir/go}"
+export GOMODCACHE="${GOCACHE:-$tmpdir/gomod}"   # upstream typo: GOCACHE, not GOMODCACHE
+```
+
+Because `$GOCACHE` is never empty by the second line, `GOMODCACHE` is
+**overwritten with GOCACHE's value** regardless of what the APKBUILD set at top
+level. So the pin has to sit **inside the function that compiles**, not at file
+scope:
+
+```sh
+build() {
+	export GOCACHE="$HOME/.cache/go-build"
+	export GOMODCACHE="$HOME/go/pkg/mod"
+	CGO_ENABLED=0 make build GOFLAGS="-trimpath -modcacherw"
+}
+```
+
+`package()` runs in a *fresh* abuild process under fakeroot and never calls
+`build()`, so nothing `build()` exported reaches it. If `package()` also
+compiles, it compiles from a cold cache — the fix is to make `package()` install
+only, not to copy the exports.
+
+## Cost: the secret-less submission
+
+`cacher init` smoke-tests its credentials, so a manifest carrying these tasks
+**fails at the second task** when submitted without secrets. Manifests written so
+that everything up to a signed artifact needs no secret lose that property. Every
+sibling accepted the trade — a cache that fails loudly beats one that silently
+makes every build cold — but say so in `docs/ci.md` when converting a manifest
+that advertised the old behaviour, and delete the three cache tasks along with
+the `secrets:` block when cutting a genuine scratch manifest.
+
+**`art init` does not give you that for free.** A working token is optional to it
+by design: with none configured it still writes the config and probes the
+endpoint anonymously, because public content is read without a token. So a
+secret-less submission sails past `art_init` and fails later, in whatever task
+first reads the cache. Where the loud early failure is wanted, gate on the file
+yourself, as `sr-ht-artifacts` does:
+
+```sh
+if [ ! -r ~/.srht-token ]; then
+  echo "CACHE_BACKEND=art needs the working token at ~/.srht-token" >&2
+  exit 1
+fi
+```
+
+## Manifest size
+
+builds.sr.ht stores a submitted manifest in a `varchar(16384)`. Cache stages plus
+their comments add roughly 3 KB. Over the cap, `hut builds submit` fails with
+`pq: value too long for type character varying(16384)` — and git.sr.ht's push
+hook fails the same way, which is the dangerous one: not a red build but no
+build, with nobody mailed. Check `wc -c .build.yml` after adding stages, and put
+the reasoning in `docs/ci.md` with a one-line pointer in the manifest.
+
+`sr-ht-artifacts` is the repo where this bites first: it was at 16038 bytes on
+2026-08-17, 346 short of the cap, so a new task there costs a trimmed comment
+somewhere else. Measure before writing, not after.
diff --git a/skills/sourcehut-custom-service/SKILL.md b/skills/sourcehut-custom-service/SKILL.md
index 0e7bfbdfa07b6dfb0190865de881215e868c2f6d..9c39dfa74890b6cd8f9e0a02b5344027a89ed8e8 100644
--- a/skills/sourcehut-custom-service/SKILL.md
+++ b/skills/sourcehut-custom-service/SKILL.md
@@ -118,7 +118,7 @@ - **No stable plugin API.** You couple to `core.sr.ht`/`core-go` internals through forks. An upstream refresh can break you, and tracking it is your job.
 - **The theme is pinned by CI, not vendored.** Your `CORE_VER`/`BOOTSTRAP_REV` must track the deployment's `SRHT_CORE_VER`, or your service silently drifts away from the instance's look. Bumping the shared chrome is a CI-variable change in every service at once.
 - **Nothing auto-propagates.** After a config template edit, every consumer must be re-rendered and restarted deliberately.
 - **`api.sr.ht` federation does not work** — not misconfigured, dead. See `references/federation.md` before promising anyone a unified endpoint.
-- **`sourcehut-epaste` is work in progress**, not a tenth precedent; it has no `go.mod` yet. Don't copy from it.
+- **`sourcehut-snip` is newer than the nine** (it was `sourcehut-epaste` before the rename). It has a `go.mod` and working code, but it has not been reviewed as a precedent — prefer the nine above, and check any pattern you take from it against one of them.
 
 ## The family, for orientation
 
diff --git a/skills/sourcehut-custom-service/references/federation.md b/skills/sourcehut-custom-service/references/federation.md
index a76980585e4d6f0678cf8d3f54b8adebd2b60df9..82a360954ecc9d75814e843b14b24cdc7041bedd 100644
--- a/skills/sourcehut-custom-service/references/federation.md
+++ b/skills/sourcehut-custom-service/references/federation.md
@@ -185,6 +185,34 @@    ```go
    var GrantScopes = []string{metapat.ScopeName(authn.ScopeRead)}
    ```
 
+   **Spell the scope in UPPER CASE.** Upstream derives its scope names from a GraphQL
+   `AccessScope` enum via the `@access` directive, so every stock service publishes
+   `REPOSITORIES`, `TRACKERS`, `PASTES`, `JOBS`, `SECRETS`. A custom service normally has
+   no `@access` directive to derive from, so nothing forces the spelling and it drifts —
+   dolt.sr.ht published lower-case `repos` for months. It drifts *silently* because meta
+   accepts whatever you publish and the service checks its own string, so both ends agree
+   with each other. What breaks is the user who types the grant by hand by analogy with a
+   neighbouring service: `metasrht/blueprints/oauth2.py::validate_grants` tests
+   `scope in service_scopes[svc]` — no case folding, no aliasing — and refuses it.
+
+   Read what any service actually publishes, rather than inferring it:
+
+   ```sh
+   curl -s https://<svc>.srht.bigb.es/query/api-meta.json
+   ```
+
+   **meta reads this file once, at import time** — `access_grants`/`service_scopes` are
+   built at module level in that blueprint, not per request. So changing a scope name is a
+   two-sided deploy: ship the service, **then restart meta.sr.ht**, or meta keeps offering
+   the old name and rejects the new one. And the grant string is baked into the HMAC'd PAT,
+   while `auth.Grants.Has` is an exact map lookup, so a rename invalidates every token
+   already minted — either accept both spellings for a while or tell holders to re-mint.
+
+   The federation gateway is *not* a consumer of any of this: it forwards the client's
+   `Authorization` header verbatim and never fetches `api-meta.json` (checked in both
+   `family::sr-ht-api` and `family::sourcehut-federation`). Scope naming is a meta.sr.ht
+   and hand-written-grant concern only.
+
 3. **Accept a meta.sr.ht personal access token on `/query`, beside your working token.**
    This is the hardest requirement, and four services were changed for it in one pass. A
    gateway forwards **one** client `Authorization` header to every service a federated