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

Dockerfile

@@ -12,11 +12,8 @@ RUN npm run build
 FROM python:3.14-slim AS runtime
 WORKDIR /app
 
-# Installed from uv.lock, exactly like CI (issue #2194). This used to be
-# `COPY pyproject.toml .` + `pip install .`, which never even copied the lock:
-# the shipped image resolved its own dependency set, so CI could be green on one
-# set of versions while the published image ran another. On 2026-07-28 that
-# class of drift turned `main` red when mcp 2.0.0 shipped mid-session.
+# Installed from uv.lock, exactly like CI, so the image runs the dependency
+# versions CI tested.
 RUN --mount=type=cache,target=/root/.cache/pip \
     pip install --no-cache-dir uv
 
@@ -41,21 +38,15 @@ COPY alembic/ alembic/
 # Ensure Python finds the source tree (where static files live) before site-packages
 ENV PYTHONPATH=/app/src
 
-# THREE VALUES, NEVER FOLDED TOGETHER (rule 149), plus the commit.
-#
-# BUILD_VERSION is the NAME (YYYY.MM.DD.HHMM, from COMMIT time) — the same
-#   string on every lane for the same source, so it answers "is this the same
-#   code?" rather than "which lane built it?".
-# BUILD_KEY is the ORDERING KEY (minutes since 2020-01-01, from BUILD time) —
-#   the only value anything may compare to decide what is newer.
-# BUILD_CHANNEL is its own field. Never a suffix, never a segment of the name.
-# BUILD_COMMIT lets the artifact's self-report be checked against the :<sha>
-#   it was published under (rule 145).
-#
-# Each defaults to empty rather than to a placeholder, EXCEPT the name: a
-# local build genuinely has no ordering key or channel, and the endpoint says
-# so by omitting them. Inventing values would make a local image claim a
-# position in an update order it is not part of.
+# Three values kept separate, plus the commit:
+# BUILD_VERSION is the name (YYYY.MM.DD.HHMM from commit time), the same on
+#   every lane for the same source.
+# BUILD_KEY is the ordering key (minutes since 2020-01-01 from build time), the
+#   only value compared to decide which build is newer.
+# BUILD_CHANNEL is its own field, never part of the name.
+# BUILD_COMMIT lets the image's self-report be checked against its :<sha> tag.
+# A local build leaves the key and channel empty: it has no place in an update
+# order, and /api/version omits them.
 ARG BUILD_VERSION=dev
 ARG BUILD_KEY=
 ARG BUILD_CHANNEL=

Makefile

@@ -39,9 +39,8 @@ check: lint typecheck test
 
 # --- Plugin ---
 
-# Run this after changing anything under plugin/ or .claude-plugin/, BEFORE
-# committing. The plugin ships straight from git with no build step, so its
-# version is minted here rather than stamped by CI; the lane fails if you
-# forget, but this is what makes remembering cheap.
+# Run after changing plugin/ or .claude-plugin/, before committing: the plugin
+# ships from git with no build step, so its version is minted here. CI fails if
+# the version wasn't bumped.
 mint-plugin:
 	python3 scripts/mint_plugin_version.py

README.md

@@ -19,7 +19,7 @@ export SECRET_KEY=your-random-secret-here
 docker compose -f docker-compose.quickstart.yml up -d
 ```
 
-Open `http://localhost:5000`. The first user to register becomes admin. To connect Claude, create an API key under **Settings → API Keys** and install the Claude Code plugin — see [API Keys & MCP](docs/api-keys-and-mcp.md).
+Open `http://localhost:5000`. The first user to register becomes admin. To connect Claude, create an API key under **Settings → MCP Access** and install the Claude Code plugin — see [API Keys & MCP](docs/api-keys-and-mcp.md).
 
 > **Development:** To build from source, see [Development](docs/development.md).
 
@@ -31,7 +31,7 @@ Open `http://localhost:5000`. The first user to register becomes admin. To conne
 | [Configuration](docs/configuration.md) | Environment variables, Docker Compose, production setup, security |
 | [Features](docs/features.md) | Detailed feature breakdown and keyboard shortcuts |
 | [Development](docs/development.md) | Dev workflow, CI/CD, migrations, release process |
-| [API Keys & MCP](docs/api-keys-and-mcp.md) | API key management and Fable MCP install guide |
+| [API Keys & MCP](docs/api-keys-and-mcp.md) | API keys and installing the Claude Code plugin |
 | [SSO / OAuth](docs/sso-oauth.md) | OIDC setup for Authentik, Keycloak, and other providers |
 | [API Reference](docs/api-reference.md) | All REST API endpoints |
 

ci-requirements.md

@@ -16,11 +16,10 @@ real Postgres), build (docker buildx).
 ## Image deps used
 
 - python 3.14
-- node 24 (used for `npm ci` + `vue-tsc` in the typecheck job, and as the
-  frontend builder stage inside the production `Dockerfile`)
-- ruff (lint job runs `ruff check src/` with zero install overhead)
-- uv (test + integration jobs run `uv sync --locked`; installed in the
-  image since the ci-python Dockerfile started pip-installing it)
+- node 24 (`npm ci` + `vue-tsc` in the typecheck job; the production
+  `Dockerfile` builds the frontend on `node:22-alpine`)
+- ruff (lint job runs `ruff check src/ scripts/` with zero install overhead)
+- uv (test + integration jobs run `uv sync --locked`)
 - docker CLI + buildx (build job pushes the production image to the
   Fabled-Git registry)
 
@@ -30,24 +29,15 @@ Anything CI installs at job time that isn't in the image. Promotion
 candidates if more than one project needs them.
 
 - `shellcheck` — apt-installed in the **plugin** job, which lints the
-  Claude Code hook scripts and runs their fail-open smoke test. Per
-  `docs/process.md`'s decision checkpoint, single-consumer deps stay
-  per-job until a second consumer wants them; Scribe is the only one so
-  far. It is small (~20 MB) and would be a promotion candidate the moment
-  another project lints shell.
+  Claude Code hook scripts and runs their fail-open smoke test. Scribe is
+  its only consumer, so per `docs/process.md` it stays per-job. It is small
+  (~20 MB) and a promotion candidate once another project lints shell.
 
-- `jq` — **no longer installed anywhere, and should not be promoted.**
-  It was installed in two jobs, and this file used to record it as "load-
-  bearing for the smoke test specifically", because every hook opened
-  `command -v jq || exit 0` and the test would otherwise pass while
-  exercising nothing. That was the tail wagging the dog: the hooks ship to
-  users, jq is absent by default on macOS, the Debian/Ubuntu slim images,
-  Alpine and most CI containers, and a machine without it got no context,
-  no rules, no prior art and no process sync in silence. #4107 removed the
-  dependency rather than documenting it, so the smoke test now runs on a
-  bare image — which is the condition it was always meant to assert. The
-  hooks use only POSIX tools (awk, sed, tr, od, cut, head, tail, grep,
-  sort, date, printf) plus `git` and `curl`.
+The hooks ship to users' machines, so they use only POSIX tools (awk, sed,
+tr, od, cut, head, tail, grep, sort, date, printf) plus `git` and `curl`.
+The smoke test runs on a bare image to keep it that way: a tool such as `jq`
+is missing on macOS, slim Debian/Ubuntu and Alpine, and a hook that needed it
+would give those machines nothing.
 
 ## Notes
 

docker-compose.prod.yml

@@ -21,10 +21,7 @@ services:
         max_attempts: 5
 
   db:
-    # pgvector image (Debian/glibc, PG17) — bundles the `vector` extension that
-    # migration 0067 enables. Moved off postgres:16-alpine via logical
-    # dump/restore (which doubles as the PG16->PG17 major upgrade); see the
-    # TRANSITION runbook in the PR.
+    # Postgres 17 with the vector extension Scribe needs.
     image: pgvector/pgvector:pg17
     stop_grace_period: 120s
     volumes:
@@ -35,9 +32,8 @@ services:
       POSTGRES_DB: scribe
     networks:
       - scribe_backend
-    # Lenient by design: a transient host exec/healthcheck stall (incident:
-    # runc setns failures -> "unhealthy" -> SIGKILL -> crash loop) must never
-    # escalate to killing the DB. Health here only gates app startup order.
+    # Lenient on purpose: health only orders app startup, so a stalled check
+    # must not get the database killed.
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U scribe"]
       interval: 30s

docker-compose.quickstart.yml

@@ -1,16 +1,7 @@
-# Fabled Scribe — Quick Start
-#
-# No build required. Pulls the latest pre-built image from the registry.
-#
-# Usage:
-#   1. Download this file
-#   2. docker compose -f docker-compose.quickstart.yml up -d
-#   3. Open http://localhost:5000 — the first account registered becomes admin
-#   4. Go to Settings → MCP Access and connect Claude (Code or Desktop) via the
-#      bearer-token URL shown there.
-#
-# Set SECRET_KEY via environment variable or a .env file alongside this file:
-#   SECRET_KEY=your-random-secret-here
+# Fabled Scribe from the pre-built image:
+#   docker compose -f docker-compose.quickstart.yml up -d
+# Then open http://localhost:5000 (the first account registered becomes admin)
+# and connect Claude from Settings → MCP Access.
 
 services:
   app:
@@ -19,6 +10,7 @@ services:
       - "5000:5000"
     environment:
       DATABASE_URL: "postgresql+asyncpg://scribe:scribe@db:5432/scribe"
+      # Set SECRET_KEY in the environment or a .env file beside this one.
       SECRET_KEY: "${SECRET_KEY:-change-me-in-production}"
       LOG_LEVEL: "${LOG_LEVEL:-INFO}"
     volumes:
@@ -35,7 +27,7 @@ services:
       start_period: 30s
 
   db:
-    # pgvector image (PG17) — bundles the `vector` extension (migration 0067).
+    # Postgres 17 with the vector extension Scribe needs.
     image: pgvector/pgvector:pg17
     stop_grace_period: 120s
     volumes:
@@ -44,8 +36,8 @@ services:
       POSTGRES_USER: scribe
       POSTGRES_PASSWORD: scribe
       POSTGRES_DB: scribe
-    # Lenient by design: a transient host exec/healthcheck stall must never
-    # escalate to killing the DB. Health here only gates app startup order.
+    # Lenient on purpose: health only orders app startup, so a stalled check
+    # must not get the database killed.
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U scribe"]
       interval: 30s

docker-compose.yml

@@ -8,13 +8,12 @@ services:
         condition: service_healthy
     volumes:
       - app_data:/data
-      # To use a bind mount instead (gives direct host access to all app data):
+      # Or a bind mount, for direct host access to the app's data:
       # - ./data:/data
     environment:
       DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-scribe}:${POSTGRES_PASSWORD:-scribe}@db:5432/${POSTGRES_DB:-scribe}"
       SECRET_KEY: "${SECRET_KEY:-dev-secret-change-me}"
-      # Uncomment if you have a SearXNG instance you want to surface in the
-      # Integrations tab as a configured web-search backend:
+      # Optional: a SearXNG instance to list as the web-search backend in Integrations.
       # SEARXNG_URL: "http://searxng:8080"
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/health')"]
@@ -33,8 +32,8 @@ services:
       POSTGRES_USER: ${POSTGRES_USER:-scribe}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-scribe}
       POSTGRES_DB: ${POSTGRES_DB:-scribe}
-    # Lenient by design: a transient host exec/healthcheck stall must never
-    # escalate to killing the DB. Health here only gates app startup order.
+    # Lenient on purpose: health only orders app startup, so a stalled check
+    # must not get the database killed.
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-scribe}"]
       interval: 30s