docs: compose files, Dockerfile, CI workflow, README and ci-requirements describe the build, briefly

Comment-only pilot for the comment standard (rule 32, milestone 544).
Issue and rule numbers, dates, run ids and incident stories come out;
the constraint each one guarded stays as a present-tense sentence.

History removed from the files, kept here:
- Dockerfile/CI: installing from uv.lock replaced pip/uv-pip installs that
  ignored the lock (#2194, the mcp 2.0.0 break on 2026-07-28); --locked
  then caught pgvector missing from the lock.
- CI: plugin paths were added after #2198/#2209 reached a live install;
  `integration` joined the build's needs after run 8212 published
  :latest with integration red (#4958); the `[[ ]]` tag step failed
  silently on dash (2a374d9); BUILD_VERSION carried the channel until
  2026-08-31 (#3298).
- jq was removed from the hooks in #4107.
- prod compose: the lenient DB healthcheck followed a runc setns crash
  loop; pgvector arrived with migration 0067 via a PG16->17 dump/restore.

Corrections to match the code: README names the Settings tab
"MCP Access"; ci-requirements says the Dockerfile builds on node:22
and lint covers scripts/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.forgejo/workflows/ci.yml

@@ -4,27 +4,15 @@
 # Push to main:       typecheck + lint + test + build :latest + :<sha>
 # Tag v* (release):   typecheck + lint + test + build :latest + :<version> + :<sha>
 #
-# Both dev and main are gated AND built. dev pushes move :dev; main pushes move
-# :latest — main IS the production line, so :latest tracks main's tip and there
-# is no separate :main tag. Every push also gets an immutable :<sha> (the
-# rollback point). A v* release tag additionally publishes the dated :<version>;
-# since main already moved :latest, the release tag's distinct job is that
-# :<version> marker (it refreshes :latest too, harmlessly).
+# main is the production line, so :latest tracks main's tip. Every push also
+# gets an immutable :<sha>, the rollback point. A release (a v* tag created on
+# main in the Forgejo UI) adds the dated :<version>.
 #
-# Successive pushes to the SAME ref supersede each other (see concurrency
-# below), so rapid pushes don't stack identical work; dev and main runs are
-# independent refs and never cancel one another.
+# A newer push to the same ref cancels the older run; dev and main never cancel
+# each other. Pull requests don't trigger runs: branch pushes already gate.
 #
-# To cut a release:
-#   Create a release via the Forgejo UI on main with a v* tag name.
-#   The tag push triggers this workflow; build job pushes :latest + :<version>.
-#
-# PRs aren't triggered on purpose — this is a solo dev→main flow, so
-# gating on branch push is already enough.
-#
-# NOTE on the `if:` guards below: Forgejo Actions does not consistently
-# honor `on.push.branches` as a filter, so every job repeats the ref check
-# explicitly — permitting dev, main, and v* tags, rejecting anything else.
+# Forgejo Actions doesn't reliably honour `on.push.branches` as a filter, so
+# every job repeats the ref check in its `if:`.
 #
 # Required secrets (repo → Settings → Secrets → Actions):
 #   REGISTRY_USER   — your Forgejo username
@@ -40,31 +28,22 @@ on:
       - "frontend/**"
       - "tests/**"
       - "pyproject.toml"
-      # The lock now determines what gets installed, so a lock-only change has
-      # to trigger a run — otherwise a dependency bump lands untested.
+      # The lock decides what is installed, so a lock-only change must run CI.
       - "uv.lock"
       - "alembic/**"
       - "alembic.ini"
       - "Dockerfile"
-      # The plugin ships straight from this repo — installs fetch it via
-      # .claude-plugin/marketplace.json, NOT from the image. So a push here is
-      # the release, with no build step in between. Omitting these paths meant
-      # plugin changes triggered no workflow at all, which is how #2198's three
-      # broken hooks and then #2209's missing version bump both reached a live
-      # install. See the `plugin` job below.
+      # The plugin ships straight from git (via .claude-plugin/marketplace.json),
+      # not in the image, so a push here is its release. See the `plugin` job.
       - "plugin/**"
       - ".claude-plugin/**"
       - "scripts/check_plugin.py"
       - ".forgejo/workflows/ci.yml"
-  # Manual trigger from the Forgejo Actions UI. Useful when an image has
-  # been built but the deployment didn't pick it up, or when re-running
-  # against the same source produces different upstream behaviour
-  # (e.g. a transient HF download flake during the voice-bundle step).
+  # Manual run from the Forgejo Actions UI, e.g. to rebuild an image.
   workflow_dispatch: {}
 
-# Cancel older runs on the same branch when a newer push lands. Tag runs
-# get their own group implicitly (refs/tags/v1.2.3 ≠ refs/heads/dev) and
-# are never cancelled, so a release build can't kill itself mid-flight.
+# A newer push cancels the older run on the same branch. Tag runs are never
+# cancelled, so a release build can't be cut off mid-flight.
 concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
@@ -91,10 +70,7 @@ jobs:
 
       - name: Cache npm download cache
         uses: actions/cache@v4
-        # Non-fatal: a transient cache-backend hiccup must NOT fail the whole
-        # typecheck job (it was skipping install + type check and reporting red
-        # on backend-only pushes — see issue task #828). On cache miss/error the
-        # job just installs without the cache.
+        # Non-fatal: a cache-backend error just means installing without it.
         continue-on-error: true
         with:
           path: ~/.npm
@@ -110,8 +86,7 @@ jobs:
         working-directory: frontend
 
   # Guards the one part of this repo that ships to users without a build step.
-  # See scripts/check_plugin.py for what it checks and, as importantly, what it
-  # can't check yet (shellcheck is absent from ci-python).
+  # scripts/check_plugin.py says what it checks and what it can't.
   plugin:
     name: Plugin hooks
     if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
@@ -119,25 +94,14 @@ jobs:
     container:
       image: git.fabledsword.com/bvandeusen/ci-python:3.14
     steps:
-      # Bare `uses:`, no `with:` block. Adding one made this action fail to
-      # extract on the act_runner ("Cannot find module .../dist/index.js") while
-      # every bare checkout in the same run succeeded — see run 3027. Nothing
-      # here needs `fetch-depth: 0` anyway: the version check diffs two trees,
-      # and a tree diff needs both trees, not a common ancestor. A depth-1 fetch
-      # of main's tip is enough, and cheaper.
+      # Keep this a bare `uses:`: with a `with:` block the action fails to
+      # extract on act_runner ("Cannot find module .../dist/index.js"). The
+      # version check diffs two trees, so a depth-1 fetch of main is enough.
       - uses: actions/checkout@v6
 
-      # Per-job, not in the image, per CI-runner's docs/process.md: "If only one
-      # project needs the dep, prefer that project installing it per-job in
-      # their workflow — at least until a second consumer arrives." Scribe is
-      # the only consumer today. Promotion into ci-python is filed as an issue
-      # on CI-runner rather than assumed here.
-      #
-      # jq WAS installed here too, because every hook exited at line 1 without
-      # it and the smoke test would have passed while exercising nothing. The
-      # hooks need no jq since #4107 — they use only what POSIX guarantees — so
-      # the smoke test now runs on a bare image, which is the condition it is
-      # actually meant to be asserting.
+      # Per-job rather than in the image: Scribe is shellcheck's only consumer.
+      # Install nothing else here; the hooks use only POSIX tools, and the
+      # smoke test runs on a bare image to prove it.
       - name: Install shell tooling
         run: |
           apt-get update -qq
@@ -163,28 +127,19 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
-      # ruff is pre-installed in the ci-python image — no install
-      # step needed, lint runs in ~2s.
+      # ruff is pre-installed in the ci-python image.
       - name: Lint
         run: ruff check src/ scripts/
 
-      # Design tokens: does the frontend's CSS agree with the stylesheet the
-      # design system generates? Fails only on an unresolvable var() reference —
-      # that count is at zero, so this is a ratchet rather than a backlog. The
-      # literal findings are printed, not gated; hundreds exist and a
-      # permanently-red job is one nobody reads.
-      #
-      # Stdlib only, no install, no network: the source of truth is theme.css,
-      # which is generated from the design system and committed.
+      # Checks the frontend's CSS against the committed, generated theme.css.
+      # Fails only on an unresolvable var() reference; hard-coded literals are
+      # reported, not gated.
       - name: Design token check
         run: python3 scripts/check_design_tokens.py --report-literals
 
-      # Dangling styles: an element whose classes have only modifier rules and
-      # no base — a deleted CSS rule that left its `:hover` behind. Two shipped
-      # this way (a link rendering as raw browser blue, a flex row whose parent
-      # was gone so every child stacked). Neither is visible to vue-tsc; a dead
-      # style typechecks perfectly. Reported, not gated — a bare wrapper is
-      # legitimate, so the signal is the count growing.
+      # Reports elements whose classes have modifier rules but no base rule,
+      # which vue-tsc can't see. Not gated: a bare wrapper is legitimate, so
+      # the signal is the count growing.
       - name: Dangling style check
         run: python3 scripts/check_dangling_styles.py
 
@@ -201,63 +156,41 @@ jobs:
         uses: actions/cache@v4
         with:
           path: ~/.cache/uv
-          # Keyed on the LOCK, not pyproject: the lock is what determines the
-          # installed set now, and a pyproject edit that doesn't change
-          # resolution shouldn't throw the cache away.
+          # Keyed on the lock, which decides the installed set.
           key: uv-${{ hashFiles('uv.lock') }}
           restore-keys: uv-
 
-      # Installs exactly what uv.lock pins, and resolves nothing itself.
-      #
-      # This replaced `uv pip install -e ".[dev]"`, which resolved from the
-      # pyproject constraints and ignored the lock entirely. Every dependency
-      # floated: on 2026-07-28 mcp 2.0.0 shipped mid-session and turned `main`
-      # red with no repo change (issue #2194). Green CI has to mean "these exact
-      # versions passed", or it isn't evidence of anything.
-      #
-      # `--locked` also FAILS when uv.lock is stale against pyproject, so a
-      # dependency edit has to go through a deliberate `uv lock` — it can't
-      # arrive on its own. That check earned its place immediately: it caught
-      # that the lock had been missing `pgvector` entirely (added to pyproject,
-      # never re-locked), which the old install path had been silently papering
-      # over by resolving from pyproject instead.
+      # Installs exactly what uv.lock pins, so green means these exact versions
+      # passed. `--locked` fails if the lock is stale against pyproject, so a
+      # dependency change needs a deliberate `uv lock`.
       - name: Install locked dependencies
         env:
           UV_PROJECT_ENVIRONMENT: /opt/venv
         run: uv sync --locked --extra dev
 
-      # An "Install jq for hook execution tests" step stood here. The hook
-      # EXECUTION tests run the real bash hook, which exited silently without
-      # jq and skipped rather than failed, so the step existed to stop them
-      # being silently unverified. Since #4107 the hooks need no jq, so the
-      # step is gone and those tests run against a bare image — and the point
-      # of removing a dependency is lost if CI keeps installing it anyway.
+      # The hook execution tests run on a bare image (no jq), like a user's
+      # machine might be.
       - name: Run tests
         # Integration tests (real Postgres) run in the `integration` job below.
         run: /opt/venv/bin/python -m pytest tests/ -q -m "not integration"
 
-  # Real-Postgres lane (family rule 6). Exercises the async SQLAlchemy connection
-  # path the unit stubs can't reach — the un-awaited execution_options regression
-  # that made every VACUUM report 0/6 lived here. Like `test`, it runs for
-  # visibility and does NOT gate the build.
+  # Real Postgres, built by the real migrations: covers the async SQLAlchemy
+  # paths unit stubs can't reach.
   #
-  # Job key stays separator-free ("integration"): act_runner derives the service-
-  # container name from the (truncated) job display name and the discovery step
-  # filters `docker ps` by it. Service hostnames aren't routable on this runner,
-  # so the step resolves the Postgres container's bridge IP. No `name:` on purpose.
+  # Service hostnames aren't routable on this runner, so the step finds the
+  # Postgres container's bridge IP. The job has no `name:` and a separator-free
+  # key because act_runner names service containers after it.
   integration:
     if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
     runs-on: python-ci
     container:
       image: git.fabledsword.com/bvandeusen/ci-python:3.14
     env:
-      # Config + the module engine read these at import time. DATABASE_URL itself
-      # is built from the discovered service IP in the run step.
+      # Read at import time. DATABASE_URL is built from the discovered IP below.
       SECRET_KEY: ci_integration_placeholder
     services:
       postgres:
-        # pgvector image so `alembic upgrade head` can run migration 0067
-        # (CREATE EXTENSION vector). PG17 — matches the prod/quickstart image.
+        # Same image as the shipped compose files: Postgres 17 with pgvector.
         image: pgvector/pgvector:pg17
         env:
           POSTGRES_USER: scribe
@@ -270,25 +203,19 @@ jobs:
           --health-retries 10
     steps:
       - uses: actions/checkout@v6
-      # Same locked install as the unit lane — the two must agree on versions,
-      # or "unit green, integration red" stops being a signal about the code.
+      # Same locked install as the unit lane, so both test the same versions.
       - name: Install locked dependencies
         env:
           UV_PROJECT_ENVIRONMENT: /opt/venv
         run: uv sync --locked --extra dev
-      # Standing answers to the checks carried by rules 81 and 79 — two facts
-      # about THIS runner that conditional rules assert as fact, and that
-      # otherwise need a throwaway job to confirm (#3237). Printing them on
-      # every integration run makes the next rulebook sweep a log read.
-      # Rule 80's evidence is the container listing the next step already
-      # prints. Every command is guarded: a diagnostic that can break the lane
-      # it observes is worse than no diagnostic.
-      - name: Runner facts (rules 79 and 81)
+      # Prints two facts about the runner that the steps below depend on.
+      # Every command is guarded so the diagnostic can't fail the lane.
+      - name: Runner facts (shell, service hostnames)
         run: |
-          echo "--- rule 81: which shell runs a run: step ---"
+          echo "--- which shell runs a run: step ---"
           readlink -f /bin/sh || echo "/bin/sh: not a symlink"
           ps -p $$ -o comm= || true
-          echo "--- rule 79: is a service reachable by its hostname yet? ---"
+          echo "--- is a service reachable by its hostname? ---"
           getent hosts postgres \
             || echo "no — 'postgres' does not resolve; the bridge-IP lookup is still required"
       - name: Integration suite (resolve service IP, migrate, test)
@@ -296,12 +223,10 @@ jobs:
           set -eux
           echo "=== container landscape (diagnostic for the name filter) ==="
           docker ps -a --format '{{.ID}} {{.Image}} -> {{.Names}}'
-          # Only THIS job's services. The runner's docker daemon is shared, so another
-          # repo's job can be running beside this one, and a job-name filter matches its
-          # containers too (Steward run 8358 and Inkwell run 8653 each took another repo's
-          # Postgres). act names every container of a task GITEA-ACTIONS-TASK-<n>-...: read
-          # <n> from our own container (its id is in the /etc/hostname bind mount) and
-          # require exactly one match.
+          # Only this job's services: the docker daemon is shared, so a job-name
+          # filter can match another repo's Postgres. act names a task's containers
+          # GITEA-ACTIONS-TASK-<n>-...; read <n> from our own container (its id is in
+          # the /etc/hostname bind mount) and require exactly one match.
           SELF=$(grep -o '/containers/[0-9a-f]\{64\}/' /proc/self/mountinfo | head -n1 | cut -d/ -f3 || true)
           SELF=${SELF:-$(hostname)}
           TASK=$(docker inspect -f '{{.Name}}' "$SELF" | grep -o 'GITEA-ACTIONS-TASK-[0-9]*-')
@@ -311,9 +236,7 @@ jobs:
           PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG")
           test -n "$PG_IP"
           export DATABASE_URL="postgresql+asyncpg://scribe:ci_integration@${PG_IP}:5432/scribe_test"
-          # Wait for Postgres to accept connections. The run: shell is dash
-          # (/bin/sh -> /usr/bin/dash on this Debian-based image, confirmed by
-          # the step above) — no bash /dev/tcp, so use Python.
+          # Wait for Postgres. The run: shell is dash (no bash /dev/tcp), so use Python.
           /opt/venv/bin/python - "$PG_IP" <<'PY'
           import socket, sys, time
           for _ in range(30):
@@ -332,21 +255,12 @@ jobs:
 
   build:
     name: Build & push image
-    # `plugin` is deliberately NOT in needs. The plugin isn't in the image —
-    # installs fetch it from git — so gating the server image on a hook lint
-    # would couple two things that don't ship together, and blocking the build
-    # wouldn't un-publish a bad hook anyway: the push already did that. A failed
-    # `plugin` job still turns the whole run red, which is the signal that
-    # matters.
-    #
-    # `integration` IS in needs (rule 177, #4958). It was added after this
-    # gate and left out of it, so on 2026-10-05 main run 8212 published
-    # :latest with integration red. The image carries the migrations and the
-    # queries that lane runs against real Postgres; a red integration run is
-    # a red image.
+    # `plugin` is not in needs: the plugin ships from git, not in the image, so
+    # holding the image back wouldn't stop a bad hook. A red `plugin` job still
+    # turns the run red. `integration` is: the image carries the migrations and
+    # queries that lane tests.
     needs: [typecheck, lint, test, integration]
-    # Build on dev, main, and v* tag pushes. dev → :dev, main → :latest,
-    # tag → :latest + :<version>; every build also gets an immutable :<sha>.
+    # dev → :dev, main → :latest, tag → :latest + :<version>; all get :<sha>.
     if: github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
     runs-on: python-ci
     container:
@@ -357,53 +271,37 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          # Rule 149 asks for this on any job deriving the version NAME. The
-          # name here comes from HEAD's commit TIME, which a depth-1 clone
-          # already has — but the rule states it unconditionally because the
-          # failure it guards is silent (a too-low value, every lane green),
-          # and a later change to how the name is derived would inherit the
-          # landmine rather than the guard.
+          # Full history for the version derivation. Today it needs only HEAD's
+          # commit time, but a shallow clone fails silently (a too-low value) if
+          # the derivation ever reads further back.
           fetch-depth: 0
 
       - name: Generate image tags and version
         id: tags
-        # POSIX `case` instead of bash `[[ ]]` because act_runner invokes
-        # `sh -e` (dash on the ci-python:3.14 image, which has no bash on
-        # the default PATH for /bin/sh). Previous `[[ ]]` form failed
-        # silently — only the SHA tag got appended, so :dev / :latest
-        # never updated in the registry and the deployed stack kept
-        # pulling stale images. Verified via `[[: not found` lines in
-        # the runner log on commit 2a374d9.
+        # POSIX `case`, not bash `[[ ]]`: the run: shell is dash, where `[[`
+        # fails silently and only the :<sha> tag would be pushed.
         run: |
           TAGS="${{ env.IMAGE }}:${{ github.sha }}"
 
-          # THREE VALUES, NEVER FOLDED TOGETHER (rule 149). Until 2026-08-31
-          # BUILD_VERSION was the CHANNEL — "dev" / "main" / the tag — so the
-          # image self-reported {"version":"main"}, a channel name where a
-          # build identifier belongs. That cost a debugging session: with the
-          # deploy misbehaving, nothing on the running instance could say
-          # which commit was serving it.
+          # Three values kept separate; the Dockerfile describes each.
 
-          # 1. ORDERING KEY — BUILD time, monotonic by construction. Minutes
-          #    since 2020-01-01. Never a commit count (not monotonic across
-          #    branches) and never commit time (goes DOWN when an older
-          #    commit is rebuilt).
+          # 1. Ordering key: build time in minutes since 2020-01-01, so it only
+          #    goes up. Commit time would go down when an older commit is
+          #    rebuilt; a commit count isn't monotonic across branches.
           BUILD_KEY=$(( ( $(date -u +%s) - 1577836800 ) / 60 ))
 
-          # 2. NAME — COMMIT time, so the same source reports the same string
-          #    on every lane and the channel is the only thing that differs.
+          # 2. Name: commit time, so the same source reads the same on every lane.
           COMMIT_TS=$(git log --format=%ct -1 HEAD)
           BUILD_NAME=$(date -u -d "@$COMMIT_TS" +%Y.%m.%d.%H%M)
 
-          # 3. CHANNEL — its own value. Never a suffix, never a segment.
+          # 3. Channel: its own value, never part of the name.
           CHANNEL="dev"
           case "${{ github.ref }}" in
             refs/heads/dev)
               TAGS="$TAGS,${{ env.IMAGE }}:dev"
               ;;
             refs/heads/main)
-              # main IS the production line: publish :latest (plus the :<sha>
-              # set above). No separate :main tag.
+              # main is the production line, so it publishes :latest.
               TAGS="$TAGS,${{ env.IMAGE }}:latest"
               CHANNEL="stable"
               ;;
@@ -418,12 +316,8 @@ jobs:
           echo "channel=$CHANNEL" >> $GITHUB_OUTPUT
 
       - name: Free disk space
-        # Self-hosted runner housekeeping. Two-step cleanup:
-        # 1. Prune dangling containers/images globally (stops the runner
-        #    from accumulating cruft from past failed builds).
-        # 2. Trim the BuildKit layer cache to a 5GB ceiling so the pip
-        #    mount cache survives but old intermediate layers don't
-        #    accumulate indefinitely.
+        # Prunes unused containers and images, and caps the BuildKit cache at
+        # 5 GB so the package caches survive but old layers don't pile up.
         run: |
           docker system prune -af || true
           docker builder prune --keep-storage 5g -f || true
@@ -445,19 +339,13 @@ jobs:
           push: true
           provenance: false
           tags: ${{ steps.tags.outputs.value }}
-          # All three, plus the commit — rule 145: the registry's identity for
-          # a build (:<sha>) and the artifact's identity for itself must
-          # agree, and they can only be checked against each other if the
-          # artifact says which commit it is.
+          # The commit lets the image's self-report be checked against :<sha>.
           build-args: |
             BUILD_VERSION=${{ steps.tags.outputs.build_name }}
             BUILD_KEY=${{ steps.tags.outputs.build_key }}
             BUILD_CHANNEL=${{ steps.tags.outputs.channel }}
             BUILD_COMMIT=${{ github.sha }}
-          # Registry-backed layer cache. Pull from :cache to prime
-          # BuildKit, push updated layers back to :cache so the next
-          # build starts warm even if the runner's local cache was
-          # pruned. `mode=max` exports all intermediate layers, not
-          # just the final image, which is what gives the ~80% speedup.
+          # Layer cache kept in the registry, so a build starts warm even after
+          # the runner prunes. `mode=max` caches intermediate layers too.
           cache-from: type=registry,ref=${{ env.IMAGE }}:cache
           cache-to: type=registry,ref=${{ env.IMAGE }}:cache,mode=max,ignore-error=true