Merge pull request 'Release: a verdict on a vanished shape revives its row' (#222) from dev into main

classify_shapes(repo=...) and the write-path hook looked only at live rows,
so a shape whose row had vanished got a second provisional row under the
same (project, repo, path, symbol, kind). The unique constraint refused it,
and the whole classify batch was lost as a tool error.

provisional_row() now finds the row under that identity, vanished or not.
A vanished row is revived with a reappeared event and keeps its judgment.
A new row is inserted inside a savepoint, so a concurrent insert of the
same identity falls back to that row instead of failing the transaction.

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

.claude-plugin/marketplace.json

@@ -1,12 +1,12 @@
 {
-  "name": "scribe-plugin",
+  "name": "grimoire-plugin",
   "owner": { "name": "Bryan Van Deusen" },
-  "description": "Scribe ships its own Claude Code plugin from this repo, versioned in lockstep with the app + the /api/plugin/context contract.",
+  "description": "Grimoire ships its own Claude Code plugin from this repo, versioned in lockstep with the app + the /api/plugin/context contract.",
   "plugins": [
     {
-      "name": "scribe",
+      "name": "grimoire",
       "source": "./plugin",
-      "description": "Scribe second brain: MCP tools + session-start push channel + universal process-skills."
+      "description": "Grimoire second brain: MCP tools + session-start push channel + universal process-skills."
     }
   ]
 }

.env.example

@@ -1,4 +1,9 @@
+# An install created before the rename from Scribe keeps its database by
+# setting these, and PGDATA_VOLUME, to the names it was created with.
 POSTGRES_USER=fabled
 POSTGRES_PASSWORD=fabled
-POSTGRES_DB=scribe
-SECRET_KEY=dev-secret-change-me
+POSTGRES_DB=grimoire
+# PGDATA_VOLUME=grimoire_pgdata
+# Grimoire keeps its own SECRET_KEY in the /data volume. Set one here only to
+# use a key you manage yourself; it then wins over the kept one.
+# SECRET_KEY=

.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/') }}
@@ -76,7 +55,7 @@ permissions:
 
 env:
   REGISTRY: git.fabledsword.com
-  IMAGE: git.fabledsword.com/bvandeusen/fabledscribe
+  IMAGE: git.fabledsword.com/bvandeusen/fabledgrimoire
 
 jobs:
   typecheck:
@@ -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 and jq are 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,26 +94,18 @@ 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 is not optional for the smoke test: every hook exits at line 1
-      # without it, so the check would pass while exercising nothing.
+      # Per-job rather than in the image: Grimoire 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
-          apt-get install -y -qq --no-install-recommends jq shellcheck
+          apt-get install -y -qq --no-install-recommends shellcheck
 
       # On main the comparison would be against itself, so only the syntax and
       # pattern checks mean anything there.
@@ -160,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
 
@@ -198,98 +156,66 @@ 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
 
-      # The hook-EXECUTION tests (test_write_path_trigger's nudge pair) run the
-      # real bash hook, which exits silently without jq — and those tests skip
-      # rather than fail when it's absent, so without this step they would
-      # quietly never be verified anywhere (ci-python ships without jq; same
-      # install the Plugin hooks job does).
-      - name: Install jq for hook execution tests
-        run: |
-          apt-get update -qq
-          apt-get install -y -qq --no-install-recommends jq
-
+      # 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
+          POSTGRES_USER: grimoire
           POSTGRES_PASSWORD: ci_integration
-          POSTGRES_DB: scribe_test
+          POSTGRES_DB: grimoire_test
         options: >-
-          --health-cmd "pg_isready -U scribe"
+          --health-cmd "pg_isready -U grimoire"
           --health-interval 10s
           --health-timeout 5s
           --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)
@@ -297,14 +223,20 @@ jobs:
           set -eux
           echo "=== container landscape (diagnostic for the name filter) ==="
           docker ps -a --format '{{.ID}} {{.Image}} -> {{.Names}}'
-          PG=$(docker ps --filter "name=integration" --filter "ancestor=pgvector/pgvector:pg17" -q | head -n1)
-          test -n "$PG"
+          # 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]*-')
+          test -n "$TASK"
+          PG=$(docker ps --filter "name=$TASK" --filter "ancestor=pgvector/pgvector:pg17" -q)
+          test "$(printf '%s\n' "$PG" | grep -c .)" -eq 1
           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.
+          export DATABASE_URL="postgresql+asyncpg://grimoire:ci_integration@${PG_IP}:5432/grimoire_test"
+          # 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):
@@ -323,15 +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.
-    needs: [typecheck, lint, test]
-    # Build on dev, main, and v* tag pushes. dev → :dev, main → :latest,
-    # tag → :latest + :<version>; every build also gets an immutable :<sha>.
+    # `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]
+    # 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:
@@ -342,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"
               ;;
@@ -402,16 +315,10 @@ jobs:
           echo "build_key=$BUILD_KEY" >> $GITHUB_OUTPUT
           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.
-        run: |
-          docker system prune -af || true
-          docker builder prune --keep-storage 5g -f || true
+      # No disk-space prune step: the runner's Docker daemon is shared, and
+      # `docker system prune -af` here deleted images other repos' jobs had
+      # just pulled and were about to start (CI-runner #16). The runner host
+      # prunes nightly instead.
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
@@ -430,19 +337,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
 
@@ -34,28 +31,22 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 # alembic and hypercorn in CMD have to be found there.
 ENV PATH="/app/.venv/bin:$PATH"
 
-COPY --from=build-frontend /build/dist/ src/scribe/static/
+COPY --from=build-frontend /build/dist/ src/grimoire/static/
 COPY alembic.ini .
 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=
@@ -65,5 +56,9 @@ ENV APP_BUILD_KEY=$BUILD_KEY
 ENV APP_CHANNEL=$BUILD_CHANNEL
 ENV APP_COMMIT=$BUILD_COMMIT
 
+# The instance's own SECRET_KEY, the model cache and diagnostics live here.
+# Mount a volume on it so they outlive the container.
+RUN mkdir -p /data
+
 EXPOSE 5000
-CMD ["sh", "-c", "alembic upgrade head && hypercorn 'scribe.app:create_app()' --bind 0.0.0.0:5000 --keep-alive 600"]
+CMD ["sh", "-c", "alembic upgrade head && hypercorn 'grimoire.app:create_app()' --bind 0.0.0.0:5000 --keep-alive 600"]

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

Makefile

@@ -3,24 +3,24 @@
 # --- Docker ---
 
 build:
-	docker compose build
+	docker compose -f docker-compose.dev.yml build
 
 up:
-	docker compose up -d
+	docker compose -f docker-compose.dev.yml up -d
 
 down:
-	docker compose down
+	docker compose -f docker-compose.dev.yml down
 
 logs:
-	docker compose logs -f
+	docker compose -f docker-compose.dev.yml logs -f
 
 health:
 	curl -s http://localhost:5000/api/health
 
 migrate:
-	docker compose exec app alembic upgrade head
+	docker compose -f docker-compose.dev.yml exec app alembic upgrade head
 
-# --- Local dev (requires: pip install -e ".[dev]" and cd frontend && npm ci) ---
+# --- Local dev (requires: uv sync --extra dev and cd frontend && npm ci) ---
 
 lint:
 	ruff check src/
@@ -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

@@ -1,40 +1,150 @@
-# Fabled Scribe
+<p align="center">
+  <img src="frontend/public/favicon.svg" width="96" alt="">
+</p>
 
-A self-hosted work system-of-record for software projects, built to be driven by Claude Code. Notes, tasks, issues, projects, milestones, rules, and stored processes — reachable from Claude via a built-in MCP endpoint and a bundled Claude Code plugin, with a clean web UI for humans. No in-app LLM; Claude is the sole assistant.
+<h1 align="center">Fabled Grimoire</h1>
+
+<p align="center">A self-hosted system of record for the work you do with Claude Code.</p>
+
+Claude records what it learned, decided and built in Grimoire, and that record reaches the next session, so a solution is recalled instead of reinvented. Notes, tasks, plans, rules, lessons and reusable code live in one place. Claude reaches them through a built-in MCP endpoint and the bundled Claude Code plugin, and people read and edit the same records in the web UI. There is no language model inside Grimoire: Claude is the only assistant.
+
+## Deploy
+
+You need Docker with Compose. Save this as `docker-compose.yml` (it is the [`docker-compose.yml`](docker-compose.yml) in this repository), then run `docker compose up -d` beside it:
+
+```yaml
+# Fabled Grimoire: the app and its database.
+#   docker compose up -d
+# Then open http://localhost:5000. The first account registered becomes admin.
+#
+# Keep both volumes. app_data holds the instance's own SECRET_KEY, which seals
+# saved credentials; pgdata holds everything else.
+
+services:
+  app:
+    image: git.fabledsword.com/bvandeusen/fabledgrimoire:latest
+    ports:
+      - "5000:5000"
+    environment:
+      DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-grimoire}:${POSTGRES_PASSWORD:-grimoire}@db:5432/${POSTGRES_DB:-grimoire}"
+      LOG_LEVEL: "${LOG_LEVEL:-INFO}"
+      # Port 5000 is published straight to clients, so no proxy is trusted.
+      # Behind a reverse proxy, set 1 (one per proxy) and BASE_URL:
+      TRUSTED_PROXY_HOPS: "0"
+      # BASE_URL: "https://grimoire.example.com"
+    volumes:
+      - app_data:/data
+    depends_on:
+      - db
+    restart: unless-stopped
+
+  db:
+    # Postgres 17 with the vector extension Grimoire needs.
+    image: pgvector/pgvector:pg17
+    stop_grace_period: 120s
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-grimoire}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-grimoire}
+      POSTGRES_DB: ${POSTGRES_DB:-grimoire}
+    restart: unless-stopped
+
+volumes:
+  app_data:
+  pgdata:
+```
+
+Open `http://localhost:5000`. The first account you register becomes the admin.
+
+Nothing has to be set first. On its first start Grimoire makes its own `SECRET_KEY` and keeps it in the `app_data` volume, so restarts, reboots and updates all use the same key.
+
+To connect Claude, create an API key under **Settings → MCP Access**, then in Claude Code:
+
+```
+/plugin marketplace add https://git.fabledsword.com/bvandeusen/FabledGrimoire.git
+/plugin install grimoire@grimoire-plugin
+```
+
+The plugin asks for your Grimoire URL and the API key. Settings → MCP Access shows the exact commands for your instance.
+
+## Configuration
+
+Everything is optional. Set these in the environment or in a `.env` file beside the compose file:
+
+| Variable | When | What it does |
+|----------|------|--------------|
+| `BASE_URL` | Behind a proxy | The public URL, used in email links and SSO redirects |
+| `TRUSTED_PROXY_HOPS` | Rarely | The starting count of reverse proxies in front of Grimoire (default `1`; the compose file above sets `0` because it publishes the port directly). Check and change it in **Settings → Config → Reverse proxy**, which shows what each count reads for your own request; behind Cloudflare it is usually `2` |
+| `POSTGRES_PASSWORD` | Before the first start | The database password (defaults to `grimoire`; the database is reachable only inside the compose network). Postgres takes it once, when the volume is created |
+| `SECRET_KEY` | Rarely | A key you manage yourself, instead of the one Grimoire keeps. It wins over the kept key; remove it to go back |
+
+Everything else (registration, email, SSO, git forge connections, retrieval tuning, backups) is in **Settings**, or listed in [Configuration](docs/configuration.md).
+
+## Setup pitfalls
+
+- **Keep both volumes.** `pgdata` holds everything Grimoire stores. `app_data` holds the instance's key, and forge tokens and the backup bucket's secret are sealed under it. If the key is lost, Settings asks you to enter those credentials again; nothing else is lost.
+- **The embedding model downloads on first use**, into the `app_data` volume. Without internet access, semantic search falls back to keyword search until the model is in place.
+- **Behind a reverse proxy, turn off response buffering** for `/mcp`, because MCP responses stream. [Configuration](docs/configuration.md#behind-a-reverse-proxy) has an Nginx example.
+
+## Updating and backups
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+Database migrations run when the app starts, and the key stays in its volume. Claude Code updates the plugin from its marketplace; run `/reload-plugins` after an update.
+
+**Settings → Data → Scheduled backups** writes a daily backup of the database to a folder or an S3-compatible bucket, and Settings → Data → Restore from Backup rolls the instance back to one, or brings a new instance back from it. See [Backups](docs/backups.md).
 
 ## Features
 
-Notes and tasks with a Markdown editor, sub-tasks, milestones, issues, and kanban project workspaces. Stored processes, an engineering rulebook system (with an inception step that decides what each project inherits), and semantic search with proactive knowledge-injection into Claude's context. A knowledge graph, per-user/group sharing, and a built-in MCP server (`/mcp`) plus a bundled Claude Code plugin so Claude can record and recall your work directly.
+**Working with Claude**
+- Claude enters a project and gets a short primer: its goal, current plans, open tasks and areas.
+- Your rules reach Claude when its work matches them, or at a moment of work such as finishing a task or pushing code.
+- Before Claude writes a file or runs a command, the plugin shows it the rules, lessons and reusable code that may apply.
+- Stored procedures, such as a drift audit, become Claude Code skills.
 
-## Quick Start
+**Recording the work**
+- Notes in a Markdown editor, with wikilinks, tags and version history.
+- Tasks, issues and time-boxed investigations, with work logs that the next session reads first.
+- Plans as milestones: a design plus ordered steps.
+- Lessons learned the hard way, linked to the rules they illustrate.
+- Duplicate checks, so a new record that matches an existing one updates it instead.
 
-**Prerequisites:** Docker and Docker Compose. No GPU or local model needed — Claude is the sole assistant, reached over MCP.
+**Reusing code**
+- Snippets of reusable code, each with when to reach for it and where it lives in the repo.
+- With a git forge connected, Grimoire tracks every function and style in your repos and shows which ones are still unaccounted for.
+- Ideas shared across projects on the same platform, with each project's answer recorded.
+- Design systems with tokens, inheritance and a generated stylesheet.
 
-Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml) from this repo, then:
+**For people**
+- A web UI to browse, search and edit everything, plus a graph of how notes connect.
+- Sharing with users and groups, as viewer, editor or admin.
+- Email and password sign-in, optional SSO through OIDC, and invite links.
+- Personal export to Markdown or JSON, and admin backup and restore.
+
+The full list is in [Features](docs/features.md).
+
+## Troubleshooting
+
+| What you see | Why | Fix |
+|--------------|-----|-----|
+| `SECRET_KEY is set to the public placeholder` at startup | `SECRET_KEY` is `dev-secret-change-me` or `change-me-in-production` | Remove `SECRET_KEY`, or set a real one |
+| Settings asks for forge tokens or the backup secret again | The instance's key changed: the `app_data` volume was replaced, or `SECRET_KEY` was set or removed | Enter them again, or restore the previous key |
+| `Can't locate revision identified by '…'` at startup | An older image is running against a database a newer one has already migrated | Run the newer image; migrations only move forward |
+| The plugin's tools are missing in Claude Code | The plugin isn't installed, or Claude Code hasn't reloaded it | `/plugin` to install or update it, then `/reload-plugins` |
+| Search finds only exact words | The embedding model hasn't downloaded yet | Give the app internet access once, or wait for the first download to finish |
+
+## Development
 
 ```bash
-# Optional but recommended — set a secret key
-export SECRET_KEY=your-random-secret-here
-
-docker compose -f docker-compose.quickstart.yml up -d
+docker compose -f docker-compose.dev.yml up --build
 ```
 
-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).
+[Development](docs/development.md) covers checks, migrations, the plugin and CI. [Architecture](docs/architecture.md) describes how it is built, and the [API reference](docs/api-reference.md) lists every REST endpoint.
 
-> **Development:** To build from source, see [Development](docs/development.md).
+## Licence
 
-## Documentation
-
-| Doc | Contents |
-|-----|----------|
-| [Architecture](docs/architecture.md) | Stack, design decisions, data models, key services |
-| [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 |
-| [SSO / OAuth](docs/sso-oauth.md) | OIDC setup for Authentik, Keycloak, and other providers |
-| [API Reference](docs/api-reference.md) | All REST API endpoints |
-
-## License
-
-This project is privately maintained.
+Fabled Grimoire is free software under the [GNU Affero General Public License v3.0 only](LICENSE) (`AGPL-3.0-only`). If you run a modified version for other people over a network, the licence requires you to offer them its source.

alembic/env.py

@@ -4,8 +4,9 @@ from logging.config import fileConfig
 from alembic import context
 from sqlalchemy.ext.asyncio import create_async_engine
 
-from scribe.config import Config
-from scribe.models import Base
+from grimoire.config import Config
+from grimoire.models import Base
+from grimoire.services.db_ready import wait_for_database
 
 config = context.config
 if config.config_file_name is not None:
@@ -32,6 +33,7 @@ def do_run_migrations(connection):
 
 
 async def run_async_migrations() -> None:
+    await wait_for_database(Config.DATABASE_URL)
     engine = create_async_engine(Config.DATABASE_URL)
     async with engine.connect() as connection:
         await connection.run_sync(do_run_migrations)

alembic/versions/0043_event_duration_replaces_end_dt.py

@@ -1,13 +1,11 @@
-"""replace events.end_dt with duration_minutes (Fable #160)
+"""replace events.end_dt with duration_minutes
 
 Revision ID: 0043
 Revises: 0042
 Create Date: 2026-04-29
 
-Structural fix for the "end before start" bug class observed on prod
-2026-04-29: an event landed with end_dt 32 days before start_dt due
-to a tool-call mishap, then disappeared from upcoming-list filters.
-Storing duration instead of end_dt makes the invalid state
+Structural fix for the "end before start" bug class: an event whose end_dt
+precedes its start_dt disappears from upcoming-list filters. Storing duration instead of end_dt makes the invalid state
 inexpressible at the schema level (duration_minutes >= 0).
 
 Backfill rules:

alembic/versions/0044_add_note_description_and_consolidated_at.py

@@ -5,7 +5,7 @@ Revises: 0043
 Create Date: 2026-05-13
 
 Adds two columns to the ``notes`` table to support the task-as-durable-record
-design (spec 2026-05-13):
+design:
 
 - ``description``: user-stated goal / initial context. Meaningful when
   ``is_task=true``; left NULL on knowledge notes.

alembic/versions/0048_conversation_last_curator_run.py

@@ -4,7 +4,7 @@ Revision ID: 0048
 Revises: 0047
 Create Date: 2026-05-22
 
-Phase 2 of the conversation+curator architecture (Fable #172). The
+Part of the conversation+curator architecture. The
 scheduler runs every 15 minutes and processes any journal conversation
 with messages newer than its `last_curator_run_at` timestamp. NULL
 means "never run; process all of today on first sweep."

alembic/versions/0049_conversation_curator_summary.py

@@ -4,7 +4,7 @@ Revision ID: 0049
 Revises: 0048
 Create Date: 2026-05-22
 
-Phase 3 of the conversation+curator architecture (Fable #172). The
+Part of the conversation+curator architecture. The
 curator's final summary line (≤ 240 chars) is persisted here so the
 NEXT chat turn can include it in the system prompt. This is the
 feedback loop that closes the architecture — without it, the chat

alembic/versions/0053_drop_chat_journal_push_curator_tables.py

@@ -4,13 +4,11 @@ Revision ID: 0053
 Revises: 0052
 Create Date: 2026-05-27
 
-Phase 9 of the MCP-first pivot. The Python models for these tables were
-deleted in Phase 8 (commit 91bafb6); this migration drops the orphan
+Part of the MCP-first pivot. The Python models for these tables are gone;
+this migration drops the orphan
 SQL tables and cleans up dead per-user setting rows.
 
-Hard-cutover: existing rows in these tables are discarded. The
-accompanying spec at docs/superpowers/specs/2026-05-26-mcp-first-pivot-design.md
-explicitly accepted this loss.
+Hard-cutover: existing rows in these tables are discarded, deliberately.
 """
 from alembic import op
 

alembic/versions/0054_drop_image_cache.py

@@ -4,7 +4,7 @@ Revision ID: 0054
 Revises: 0053
 Create Date: 2026-05-27
 
-The image cache was wired into the LLM image-search tool (removed in Phase 8).
+The image cache was wired into the LLM image-search tool, which is gone.
 With no producer or consumer left, the table is dropped here.
 """
 from alembic import op

alembic/versions/0055_rulebook_tables.py

@@ -6,8 +6,8 @@ Create Date: 2026-05-27
 
 Adds the Scribe Rulebook hierarchy as a fourth top-level entity, sibling
 to Project. Rules carry a structural (statement, why, how_to_apply)
-triple. Projects subscribe to Rulebooks (many-to-many). See the design
-doc at docs/superpowers/specs/2026-05-27-scribe-rulebook-design.md.
+triple. Projects subscribe to Rulebooks (many-to-many; migration 0101
+later drops subscriptions).
 """
 from alembic import op
 import sqlalchemy as sa

alembic/versions/0066_milestone_body.py

@@ -4,7 +4,7 @@ Revision ID: 0066
 Revises: 0065
 Create Date: 2026-06-14
 
-T3 of plan #819. The milestone becomes the plan container: its `body` holds
+The milestone becomes the plan container: its `body` holds
 the design/intent/purpose (markdown), `description` stays the one-liner, and
 individual steps live as first-class child tasks (milestone_id) instead of
 checkboxes crammed into a kind=plan task body. start_planning is reworked to

alembic/versions/0074_design_prose.py

@@ -4,8 +4,7 @@ Revision ID: 0074
 Revises: 0073
 Create Date: 2026-07-31
 
-The operator's shape for #254: prose doesn't live as one-offs, it lives centrally
-on the system. Two fields rather than one per category:
+Prose doesn't live as one-offs; it lives centrally on the system. Two fields rather than one per category:
 
   design_systems.guidance   the narrative a token table cannot hold — aesthetic,
                             voice and tone, what is deliberately out of scope.
@@ -17,7 +16,7 @@ on the system. Two fields rather than one per category:
 
 Free-form rather than a column per category on purpose. A schema with `voice`,
 `aesthetic` and `scope` columns would bake one rulebook's table of contents into
-every install (rule #115), and the next install's design system would have three
+every install, and the next install's design system would have three
 empty columns and nowhere to put what it actually cares about.
 
 Both nullable: a design system with no prose at all is complete, not a draft.

alembic/versions/0076_note_supersessions.py

@@ -4,7 +4,7 @@ Revision ID: 0076
 Revises: 0075
 Create Date: 2026-08-07
 
-Step 1 of milestone #278. Structure only — nothing reads or writes the new
+Structure only — nothing reads or writes the new
 table yet, and nothing behaves differently after this runs.
 
 ## What the table is for
@@ -39,7 +39,7 @@ and not for notes, so the column looked like the notes-side half of that
 feature, modelled and abandoned.
 
 It is dropped rather than repurposed for supersession, and the distinction is
-the point (#2483): consolidation folds several records into one survivor and
+the point: consolidation folds several records into one survivor and
 destroys the originals. Merging two snippets is lossless — one helper, several
 call sites. Folding two dev-logs means writing a summary and losing what each
 actually said. Supersession is the opposite act: both records survive, and the

alembic/versions/0077_chunked_embeddings.py

@@ -1,4 +1,4 @@
-"""Chunked embeddings: one note_embeddings row per chunk (#280)
+"""Chunked embeddings: one note_embeddings row per chunk
 
 Revision ID: 0077
 Revises: 0076

alembic/versions/0078_forge_connections.py

@@ -1,4 +1,4 @@
-"""Forge connections move to the user level (#2778)
+"""Forge connections move to the user level
 
 Revision ID: 0078
 Revises: 0077
@@ -12,7 +12,7 @@ keyring, with an optional per-project pin (projects.forge_connection_id).
 
 The data move carries the existing admin config into a connection row for the
 first admin user (host parsed from the base URL), then deletes the old
-setting keys outright — no legacy dual-read (rule #22). The env-var channel
+setting keys outright — no legacy dual-read. The env-var channel
 (FORGE_KIND/FORGE_BASE_URL/FORGE_TOKEN) is untouched by this migration; it
 survives as an implicit keyring entry for admin users only.
 """

alembic/versions/0079_code_shapes_ledger.py

@@ -1,13 +1,13 @@
-"""The shape ledger: code_shapes (#2787, milestone 294)
+"""The shape ledger: code_shapes
 
 Revision ID: 0079
 Revises: 0078
 Create Date: 2026-08-19
 
-The accounting half of the pattern system (governing note 2786): the snippet
+The accounting half of the pattern system: the snippet
 library records canon (small); this table accounts for EVERY shape the
 coverage extractor finds in a bound repo (total). Rows arrive `unclassified`
-from the coverage sync (step 2) and gain judgments — canonical / instance /
+from the coverage sync and gain judgments — canonical / instance /
 variant / exempt — from audits, hooks, and the mechanical proposer.
 Unclassified IS the todo list.
 """

alembic/versions/0080_code_shape_proposals.py

@@ -1,4 +1,4 @@
-"""Shape fingerprints + the mechanical proposer's columns (#2792, milestone 294)
+"""Shape fingerprints + the mechanical proposer's columns
 
 Revision ID: 0080
 Revises: 0079

alembic/versions/0081_shape_history_and_divergence.py

@@ -1,4 +1,4 @@
-"""Shape history, recheck, and the divergence flag (#2793, milestone 294)
+"""Shape history, recheck, and the divergence flag
 
 Revision ID: 0081
 Revises: 0080

alembic/versions/0082_repo_binding_ref.py

@@ -1,13 +1,13 @@
-"""Per-binding ref — the branch a project's ledger follows (#2873, milestone 294)
+"""Per-binding ref — the branch a project's ledger follows
 
 Revision ID: 0082
 Revises: 0081
 Create Date: 2026-08-21
 
-A repo binding used to imply the repo's default branch; the shape ledger
-therefore only saw work after a merge to main, while the operator's work
-lands on dev (rule 1). `ref` names the branch the coverage refresh reads —
-NULL keeps today's behaviour (the forge's default branch).
+Without a ref, a repo binding implies the repo's default branch, so the shape
+ledger only sees work after a merge — while a project may do its work on a
+dev branch. `ref` names the branch the coverage refresh reads; NULL means the
+forge's default branch.
 """
 import sqlalchemy as sa
 from alembic import op

alembic/versions/0083_code_shape_reason_code.py

@@ -1,4 +1,4 @@
-"""Exempt/variant reason codes — a small fixed catalogue beside the prose (#2874, milestone 294)
+"""Exempt/variant reason codes — a small fixed catalogue beside the prose
 
 Revision ID: 0083
 Revises: 0082

alembic/versions/0084_code_shape_uses.py

@@ -1,4 +1,4 @@
-"""code_shape_uses — consumption edges, separate from conformance (#2870, milestone 294)
+"""code_shape_uses — consumption edges, separate from conformance
 
 Revision ID: 0084
 Revises: 0083

alembic/versions/0085_project_inception.py

@@ -1,4 +1,4 @@
-"""Project inception: the decision record + always-on rulebook exclusions (milestone 297)
+"""Project inception: the decision record + always-on rulebook exclusions
 
 Revision ID: 0085
 Revises: 0084

alembic/versions/0086_code_shape_consumers.py

@@ -1,4 +1,4 @@
-"""code_shape_consumers — the CSS consumer map (milestone 302, note 2917)
+"""code_shape_consumers — the CSS consumer map
 
 Revision ID: 0086
 Revises: 0085

alembic/versions/0087_canonical_systems.py

@@ -1,12 +1,12 @@
 """canonical_systems — the global area vocabulary, promoted from a constant
-to a table (milestone 307 step 1, decision note 3026)
+to a table
 
 Revision ID: 0087
 Revises: 0086
 Create Date: 2026-08-26
 
 The eight standard area names already existed as `STANDARD_SYSTEMS`, a tuple in
-services/systems.py that milestone 297 seeds into a project at inception. A
+services/systems.py that is seeded into a project at inception. A
 constant cannot be referenced: a rule that applies across projects has nothing
 to point at, because `systems.project_id` is NOT NULL and a family rule cannot
 be chained to one project's row. This makes the vocabulary a table so it can be
@@ -35,7 +35,7 @@ depends_on = None
 # service computes (canonical_slug: lowercase, "&" -> "and", non-alphanumerics
 # collapsed to "-"). Charters stay generic on purpose: a project refines its
 # own System's description, never this one. Nothing here names an app, a repo,
-# a vendor or a house convention — the catalog ships to every install (rule 115).
+# a vendor or a house convention — the catalog ships to every install.
 _SEED = (
     ("CI & Release", "ci-and-release",
      "How the project is verified and shipped: pipelines, runners, image/artifact builds, release tagging and rollback."),

alembic/versions/0088_rule_trigger_tier_tags_relations.py

@@ -1,5 +1,4 @@
-"""rules gain a trigger, a tier, canon tags and typed edges (milestone 307
-step 3, decision note 3026)
+"""rules gain a trigger, a tier, canon tags and typed edges
 
 Revision ID: 0088
 Revises: 0087
@@ -31,8 +30,8 @@ down_revision = "0087"
 branch_labels = None
 depends_on = None
 
-# Kept in one place so upgrade and the CHECK agree by construction (rule 36:
-# a whitelisted value means DROP + ADD CONSTRAINT in the same migration —
+# Kept in one place so upgrade and the CHECK agree by construction (a
+# whitelisted value means DROP + ADD CONSTRAINT in the same migration —
 # there is no prior constraint here, so the pair is created together).
 _TIERS = ("always_on", "conditional")
 _RELATION_KINDS = ("co_surfaces", "overrides", "elaborates")

alembic/versions/0089_rule_embeddings.py

@@ -1,5 +1,4 @@
-"""rule_embeddings — rules become findable by meaning (milestone 307 step 4,
-decision note 3026)
+"""rule_embeddings — rules become findable by meaning
 
 Revision ID: 0089
 Revises: 0088

alembic/versions/0090_rule_verification.py

@@ -1,5 +1,4 @@
 """a rule can carry its own check — verify_with, expires_when, verified_at
-(milestone 312 step 1)
 
 Revision ID: 0090
 Revises: 0089
@@ -11,10 +10,9 @@ know they did. A CONSTRAINT is a fact about someone else's software: a
 runner's shell, a bot's config, a tool that exists. Nobody is present when
 that goes false.
 
-Milestone 307's rulebook audit found nine stale sites. Every one was a
-constraint; not one norm had rotted. One of them had been telling every
-session to skip database-backed tests for weeks while the integration lane
-sat green in the workflow.
+What goes stale in a rulebook is the constraints, not the norms — and a
+stale constraint keeps instructing every session that loads it, long after
+the world it described has moved.
 
 Three nullable columns, so a rule can say how to check itself:
 
@@ -31,7 +29,7 @@ none of them. A null `verify_with` is not an omission — it is the honest
 marker of "this one is a decision, and there is nothing to go and check."
 That signal only works if the field stays empty wherever it belongs empty.
 
-No CHECK constraint is involved, so rule 36 does not apply here. Nothing is
+No CHECK constraint is involved. Nothing is
 backfilled: a migration cannot invent a check any more than 0088 could
 invent a trigger.
 """

alembic/versions/0091_task_kind_spike.py

@@ -1,5 +1,4 @@
 """task_kind gains 'spike' — the investigation, not the change
-(milestone 312 step 5)
 
 Revision ID: 0091
 Revises: 0090
@@ -12,12 +11,12 @@ end of it. "Find out whether the runner can be given a bash shell" is not
 work, and filing it as work makes a finished investigation look like an
 abandoned change.
 
-It is the record a failed check asks for. Milestone 312 gave rules a
+It is the record a failed check asks for. Rules carry a
 `verify_with`; when one of those fails, the rule is wrong and the next move
 is often to go and find out what replaced it. `notes.arose_from_id` already
 exists (0065), so that constraint -> spike link needs no further schema.
 
-Rule 36: `task_kind` is gated by a CHECK whitelist, so the value and the
+`task_kind` is gated by a CHECK whitelist, so the value and the
 widened constraint land in the SAME migration — DROP then ADD, exactly as
 0065 did when it introduced 'issue'. Adding the value and constraining it
 later leaves a window where the database accepts anything.

alembic/versions/0092_note_verification.py

@@ -1,5 +1,4 @@
 """a note can carry its own check — verify_with, expires_when, verified_at
-(milestone 317 step 1)
 
 Revision ID: 0092
 Revises: 0091
@@ -32,8 +31,7 @@ Three nullable columns:
 
 WHICH ROWS THESE ARE FOR. `notes` is one table holding notes, tasks,
 snippets and processes, so these columns land on all of them. Only non-task,
-non-snippet records are OFFERED them (milestone 317 decisions 1 and 2, gated
-at the service in step 2): a task's decay is its status, and a snippet
+non-snippet records are OFFERED them (gated at the service): a task's decay is its status, and a snippet
 already carries a richer, location-aware verdict in `data.verification`. The
 columns exist on the other rows and stay null there; a gate that lives in
 the schema would have meant a partial index or a CHECK across three columns
@@ -44,7 +42,7 @@ value of the sweep is that its output is short. A null `verify_with` is not
 an omission; it is the honest marker of "this one is a decision, and there
 is nothing to go and check."
 
-No CHECK constraint is involved, so rule 36 does not apply. Nothing is
+No CHECK constraint is involved. Nothing is
 backfilled: a migration cannot invent a check.
 """
 import sqlalchemy as sa
@@ -69,9 +67,8 @@ def upgrade() -> None:
     #
     # Still a sequential scan's job at this size, and an index on
     # (verified_at) filtered to `verify_with IS NOT NULL` would be maintained
-    # on every note write to serve one operator-initiated query. If step 3's
-    # live acceptance measures otherwise, add it there against a real plan
-    # rather than guessing here.
+    # on every note write to serve one operator-initiated query. If a real
+    # plan says otherwise, add it then rather than guessing here.
 
 
 def downgrade() -> None:

alembic/versions/0093_rule_versions.py

@@ -1,4 +1,4 @@
-"""rules gain an edit history — rule_versions (milestone 323 step 1)
+"""rules gain an edit history — rule_versions
 
 Revision ID: 0093
 Revises: 0092
@@ -7,12 +7,9 @@ Create Date: 2026-08-29
 The sibling `note_versions` has had for a long time. A note's every meaningful
 edit is snapshotted, and the design-system note calls that history "the
 changelog". A RULE — which binds behaviour on every session that loads it —
-had nothing: an edit destroyed what it used to say, with no record anywhere.
-
-Rescoping rule 79 on 2026-08-29 is what surfaced it. The superseded statement
-had to be hand-copied into a task log to survive the edit (#3237), which is
-not a process, it is a person remembering. The more consequential record had
-the weaker protection.
+had nothing: an edit destroyed what it used to say, with no record anywhere,
+and keeping a superseded statement meant a person remembering to copy it
+somewhere. The more consequential record had the weaker protection.
 
 Three things are deliberately NOT copied from note_versions, and each is a
 guard that exists there for a reason that does not hold here:
@@ -31,7 +28,7 @@ guard that exists there for a reason that does not hold here:
 CASCADE: deleting a user must not erase the history of the rules they edited.
 The edit still happened and the rule still binds because of it.
 
-No CHECK constraint, so rule 36 does not apply. Nothing is backfilled — a
+No CHECK constraint is involved. Nothing is backfilled — a
 migration cannot invent the text a rule used to have, and inventing "the
 current text, as of now" would be worse than an empty history, because it
 would look like a record of an edit that never occurred.

alembic/versions/0094_rule_usage_events.py

@@ -1,4 +1,4 @@
-"""add rule_usage_events — was a surfaced rule ever read? (milestone 333 step 1)
+"""add rule_usage_events — was a surfaced rule ever read?
 
 Revision ID: 0094
 Revises: 0093
@@ -9,18 +9,15 @@ table to arrive after `rule_embeddings` and `rule_versions` — each one added
 because the rule side kept inheriting machinery built for notes and getting
 the weaker version of it.
 
-WHAT IT MEASURES. The write-path standing-rule arm is the only retrieval
-surface in Scribe whose usefulness cannot be observed, and — not coincidentally
-— the only one that has never declined to fire. Over 30 days it took 296 calls,
-returned something on every one, and cleared its threshold 100% of the time,
-while every other surface declines most of the time (#3311). That is either a
-perfectly tuned surface or a bar it cannot fail to clear, and `retrieval_logs`
+WHAT IT MEASURES. A standing-rule arm that returns something on every call
+and clears its threshold every time is either a perfectly tuned surface or a
+bar it cannot fail to clear, and `retrieval_logs`
 cannot tell them apart: it records what the ranker scored, never whether the
 hint was any use.
 
 WHY NOT A rule_id COLUMN ON note_usage_events. The row shares no note-specific
 fields and the aggregate readout is the same shape, which is the strongest case
-for sharing that note #3163 admits. What decides against it is identity at
+for sharing there is. What decides against it is identity at
 RESTORE: `note_usage_events`'s importer maps `note_id` through `note_id_map`
 and drops what does not resolve. A rule id parked in that column would come
 back from a backup silently reattached to whatever note took that number —
@@ -34,8 +31,8 @@ and dies with it; telemetry outlives the row it describes. Deleting a rule must
 not erase the evidence that it was surfaced forty times and opened never, since
 that evidence is exactly the case for having deleted it.
 
-No CHECK on `event`, matching the note twin. Rule 36 governs adding a value to
-a column that is already gated; it does not require gating one that never was,
+No CHECK on `event`, matching the note twin. DROP + ADD governs adding a value
+to a column that is already gated; it does not require gating one that never was,
 and a two-member enum whose members are written by two functions in one module
 is not where that discipline earns its cost.
 

alembic/versions/0095_retrieval_log_suppressed_count.py

@@ -1,4 +1,4 @@
-"""add retrieval_logs.suppressed_count — tell a ranker decline from a repeat (#3497)
+"""add retrieval_logs.suppressed_count — tell a ranker decline from a repeat
 
 Revision ID: 0095
 Revises: 0094
@@ -20,9 +20,8 @@ the dropped rows never come back and there is nothing to count.
 NULLABLE, AND THE NULL IS THE POINT. A surface that does not measure
 suppression stores NULL, not 0, and the readout renders it as "not measured"
 rather than "none". Defaulting to 0 would make an unmeasured surface look like
-a perfectly clean one — the exact substitution of an artifact for a
-measurement that #3311 made and that #3497 exists to correct. Doing it again,
-in the migration that fixes it, would be its own small joke.
+a perfectly clean one — the substitution of an artifact for a measurement
+that this column exists to prevent.
 
 No backfill for the same reason: existing rows genuinely do not know, and
 saying so is the honest state. `retrieval_logs` is not restored from backup,

alembic/versions/0096_retrieval_log_best_available_score.py

@@ -1,4 +1,4 @@
-"""add retrieval_logs.best_available_score — the score the bar rejected (#3670)
+"""add retrieval_logs.best_available_score — the score the bar rejected
 
 Revision ID: 0096
 Revises: 0095
@@ -34,7 +34,7 @@ NULLABLE, AND UNBACKFILLED, for the reason 0095 spells out: a row written
 before this shipped genuinely does not know what its best rejected candidate
 scored, and saying so is the honest state. A 0.0 default would read as "the
 corpus had nothing remotely relevant" — an artifact standing in for a
-measurement, which is the whole defect this milestone corrects.
+measurement, which is the defect this column corrects.
 
 `retrieval_logs` is not restored from backup, so no importer changes.
 

alembic/versions/0097_retrieval_log_best_available_id.py

@@ -1,4 +1,4 @@
-"""add retrieval_logs.best_available_id — WHICH record the bar refused (#3807)
+"""add retrieval_logs.best_available_id — WHICH record the bar refused
 
 Revision ID: 0097
 Revises: 0096

alembic/versions/0098_rule_kind.py

@@ -1,4 +1,4 @@
-"""rules gain a `kind` — a preference is a rule that does not bind (#3849)
+"""rules gain a `kind` — a preference is a rule that does not bind
 
 Revision ID: 0098
 Revises: 0097
@@ -37,7 +37,7 @@ install upgrades and every existing row keeps the force it had. That is the
 same reasoning 0088 used for `tier`, and it is the reason both are safe to
 apply without reading the data first.
 
-The CHECK is created with the column (rule 36: there is no prior constraint,
+The CHECK is created with the column (there is no prior constraint,
 so the pair is created together — a value added to it LATER does DROP + ADD
 in one migration).
 

alembic/versions/0099_scrub_secrets_from_retrieval_logs.py

@@ -7,7 +7,7 @@ Create Date: 2026-09-11
 `pre_tool_rule` retrieves against the RAW COMMAND TEXT and `write_path_rule`
 against the code being written, so whatever was on the command line or in the
 buffer is what `record_retrieval` wrote into `retrieval_logs.query`. A command
-that exported a token stored the token (#3925).
+that exported a token stored the token.
 
 `services/retrieval_telemetry.scrub_secrets` closes that going forward — the
 value never reaches the column. It cannot reach BACKWARDS, and this does: it

alembic/versions/0100_drop_always_on_tier.py

@@ -4,14 +4,14 @@ Revision ID: 0100
 Revises: 0099
 Create Date: 2026-09-11
 
-Milestone 394. Every rule now reaches a session by retrieval — because
+Every rule reaches a session by retrieval — because
 something it is about to do made the rule relevant — and the machinery that
 delivered rules unconditionally goes with it.
 
 WHAT GOES, AND WHERE IT CAME FROM
 
   - ``rules.tier`` and its ``ck_rules_tier`` CHECK (migration 0088). Dropping
-    the column takes the constraint with it. Rule 36 is about ADDING a value to
+    the column takes the constraint with it. DROP + ADD is about ADDING a value to
     a live whitelist, which needs DROP + ADD in the same migration; it does not
     speak to removing the column outright, and saying so here is cheaper than
     the next reader wondering whether it was forgotten.

alembic/versions/0101_drop_rulebook_subscriptions.py

@@ -0,0 +1,82 @@
+"""drop rulebook subscriptions and per-project suppressions
+
+Revision ID: 0101
+Revises: 0100
+Create Date: 2026-09-15
+
+A rule lives in a rulebook topic, where it is GLOBAL, or on one project, and
+retrieval reads that home directly. Subscriptions were the last thing that
+pretended a rulebook reached some projects and not others, and with no
+always-on tier they changed nothing a session received — only what a
+project's rule LISTING showed. Global and project-scoped rules cover what
+subscriptions were for.
+
+WHAT GOES
+
+  - ``project_rulebook_subscriptions`` (migration 0058).
+  - ``project_rule_suppressions`` and ``project_topic_suppressions``. They let a
+    project mute rules from a rulebook it subscribed to. With no subscription
+    there is nothing to mute; a project that departs from a global rule writes
+    a project rule with an ``overrides`` relation, which says why.
+  - The ``subscribe_rulebooks`` key inside ``projects.inception.choices``, and
+    the ``exclude_always_on_rulebooks`` key the retired always-on tier left
+    in the same place. Both describe decisions that can no longer be made; a stored
+    record carrying them would be read back as a choice the product offers.
+
+IRREVERSIBLE, AND THE DOWNGRADE SAYS SO
+
+The downgrade recreates the three tables empty. Which projects subscribed to
+which rulebooks, and what they muted, is in what this drops. Restore a backup
+taken before this ran if the prior state matters.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0101"
+down_revision = "0100"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_table("project_topic_suppressions")
+    op.drop_table("project_rule_suppressions")
+    op.drop_table("project_rulebook_subscriptions")
+    op.execute(
+        """
+        UPDATE projects
+        SET inception = jsonb_set(
+            inception, '{choices}',
+            (inception->'choices') - 'subscribe_rulebooks' - 'exclude_always_on_rulebooks'
+        )
+        WHERE inception IS NOT NULL
+          AND jsonb_typeof(inception->'choices') = 'object'
+        """
+    )
+
+
+def _join_table(name: str, other: str, other_table: str) -> None:
+    op.create_table(
+        name,
+        sa.Column(
+            "project_id", sa.BigInteger(),
+            sa.ForeignKey("projects.id", ondelete="CASCADE"),
+            primary_key=True, nullable=False,
+        ),
+        sa.Column(
+            other, sa.BigInteger(),
+            sa.ForeignKey(f"{other_table}.id", ondelete="CASCADE"),
+            primary_key=True, nullable=False,
+        ),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True),
+            server_default=sa.text("now()"), nullable=True,
+        ),
+    )
+
+
+def downgrade() -> None:
+    """Structure only. See the module docstring — the rows are gone."""
+    _join_table("project_rulebook_subscriptions", "rulebook_id", "rulebooks")
+    _join_table("project_rule_suppressions", "rule_id", "rules")
+    _join_table("project_topic_suppressions", "topic_id", "rulebook_topics")

alembic/versions/0102_milestone_embeddings.py

@@ -0,0 +1,59 @@
+"""milestone_embeddings — a plan becomes findable by meaning
+
+Revision ID: 0102
+Revises: 0101
+Create Date: 2026-09-15
+
+`search` covered notes, tasks and rules, and a milestone — the record a plan
+lives in — could not be found at all. So "is there already a plan for this?"
+had no tool, and a project whose roadmap was written as milestones had every
+later plan opened as a new milestone beside the one that already described it.
+
+The sibling of rule_embeddings (0089), for the reasons its model docstring
+gives. The vectors are DERIVED: nothing is backfilled here, the startup
+backfill writes them.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0102"
+down_revision = "0101"
+branch_labels = None
+depends_on = None
+
+# Matches note_embeddings and rule_embeddings — bge-small-en-v1.5, 384-dim.
+_EMBEDDING_DIM = 384
+
+
+def upgrade() -> None:
+    op.create_table(
+        "milestone_embeddings",
+        sa.Column(
+            "milestone_id", sa.Integer(),
+            sa.ForeignKey("milestones.id", ondelete="CASCADE"), primary_key=True,
+        ),
+        sa.Column("chunk_index", sa.Integer(), primary_key=True),
+        sa.Column("chunk_text", sa.Text(), nullable=False),
+        sa.Column("chunker_version", sa.Integer(), nullable=False),
+        sa.Column(
+            "updated_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+    )
+    # Raw DDL for the vector column, as 0067 and 0089 do: the type comes from
+    # the pgvector extension, not SQLAlchemy's type system.
+    op.execute(
+        f"ALTER TABLE milestone_embeddings ADD COLUMN embedding vector({_EMBEDDING_DIM}) NOT NULL"
+    )
+    op.execute(
+        """
+        CREATE INDEX ix_milestone_embeddings_embedding_hnsw
+            ON milestone_embeddings
+         USING hnsw (embedding vector_cosine_ops)
+        """
+    )
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS ix_milestone_embeddings_embedding_hnsw")
+    op.drop_table("milestone_embeddings")

alembic/versions/0103_retrieval_tuning_events.py

@@ -0,0 +1,71 @@
+"""retrieval_tuning_events — why a floor is where it is
+
+Revision ID: 0103
+Revises: 0102
+Create Date: 2026-09-17
+
+Similarity thresholds are not values somebody has to defend: the model that
+reads the surface's own telemetry adjusts them, and the operator can still
+touch them.
+
+The number itself already has a home — the generic settings table. What has no
+home is the ARGUMENT, and once the values move on their own the argument is the
+part an operator needs: what changed, from what to what, who moved it, and on
+what evidence. This table is that trail, and it is what makes the delegation
+reviewable rather than merely automatic.
+
+Nothing is backfilled. A surface with no rows here is sitting on its shipped
+starting point, which is a true and useful thing for the history to say.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0103"
+down_revision = "0102"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "retrieval_tuning_events",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        # FK-free, like retrieval_logs and app_logs: the record of why a number
+        # is where it is must outlive the account that moved it.
+        sa.Column("user_id", sa.Integer(), nullable=True),
+        # Also the surface's `retrieval_logs.source`, so a change can be read
+        # next to what the change did.
+        sa.Column("surface", sa.Text(), nullable=False),
+        sa.Column("dial", sa.Text(), nullable=False),
+        # Nullable: the first change to a surface has no stored predecessor. It
+        # moved off the shipped starting point, which is a different event from
+        # moving off a value somebody chose.
+        sa.Column("old_value", sa.Float(), nullable=True),
+        sa.Column("new_value", sa.Float(), nullable=False),
+        sa.Column(
+            "actor", sa.Text(), nullable=False, server_default=sa.text("'model'")
+        ),
+        # Non-null here; non-BLANK is enforced at the service boundary, because
+        # a column that merely forbids NULL is satisfied by "" and a required
+        # field that accepts "" is a formality.
+        sa.Column("reason", sa.Text(), nullable=False),
+    )
+    # The only read this table has: one surface's history, newest first.
+    op.create_index(
+        "ix_retrieval_tuning_surface_created",
+        "retrieval_tuning_events",
+        ["surface", sa.text("created_at DESC")],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_retrieval_tuning_surface_created", table_name="retrieval_tuning_events"
+    )
+    op.drop_table("retrieval_tuning_events")

alembic/versions/0104_tuning_events_carry_their_calibration.py

@@ -0,0 +1,51 @@
+"""retrieval_tuning_events carries the space each number was measured in
+
+Revision ID: 0104
+Revises: 0103
+Create Date: 2026-09-17
+
+A retrieval floor is a cosine distance in ONE embedding
+model's geometry, computed over documents cut one particular way. Change the
+model and every score moves at once; change the chunker and the same record
+embeds different text. Either way a number chosen before the change is a
+measurement of something that no longer exists — and today nothing records
+which world it was chosen in, so the staleness is unknowable rather than
+merely unknown.
+
+`CHUNKER_VERSION` already solved exactly this for documents: stored per row, so
+the startup backfill re-embeds precisely what is stale instead of wiping the
+table. These two columns are that idea applied to the tuned numbers.
+
+TWO COLUMNS, NOT ONE. A reader has to be able to say WHICH half
+moved: a new embedding model and a re-cut document shape invalidate the same
+numbers for different reasons, and a fused `"<model>@<n>"` could only report
+that something changed.
+
+NULLABLE, and not backfilled. The rows already in this table were written
+under something, but naming it would be inventing a fact — the honest value is
+"unstamped", which is a different answer from a model name that might be wrong.
+`current_settings` reports an unstamped dial as exactly that.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0104"
+down_revision = "0103"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "retrieval_tuning_events",
+        sa.Column("embedding_model", sa.Text(), nullable=True),
+    )
+    op.add_column(
+        "retrieval_tuning_events",
+        sa.Column("shape_version", sa.Integer(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("retrieval_tuning_events", "shape_version")
+    op.drop_column("retrieval_tuning_events", "embedding_model")

alembic/versions/0105_note_usage_events_carry_the_reading_project.py

@@ -0,0 +1,61 @@
+"""note_usage_events records WHICH project the reader was in
+
+Revision ID: 0105
+Revises: 0104
+Create Date: 2026-09-20
+
+`RetrievalLog` has carried `project_id` from the start, so
+"this record was SURFACED on project B" has always been answerable. The usage
+table never had one, so "this record was OPENED on project B" never was — and
+the two cannot be joined to recover it, because there is no session identity
+server-side (see the NoteUsageEvent docstring, which rules that out on
+purpose).
+
+That gap sits exactly on the question lessons exist to answer. A lesson's
+whole claim is that it reaches a session on a project it was not written on:
+"retrieved on a different project, at the moment it applies, AND opened". Surfacing cross-project: answerable. Opening:
+answerable. Both at once: not, until this column.
+
+WHICH PROJECT THIS IS, because the name is ambiguous and the wrong reading
+makes the column useless. It is the project the READER was working in at the
+moment of the event — NOT the project the record belongs to. The record's own
+project is already on `notes.project_id`; copying it here would answer a
+question nobody asked and quietly look like it answered this one.
+
+NULLABLE, and not backfilled. Every existing row was written by a reader who
+was somewhere, but naming it would be inventing a fact. Null means "not
+reported", which is a different answer from a project id that might be wrong —
+the same reasoning 0104 applied to its calibration stamps.
+
+NULL IS ALSO THE ONGOING DEGRADED CASE, not only a historical one. A surfacing
+arm always knows the project it searched; a getter only knows what its caller
+passed. A pull with no project is still a pull and still counts toward "is this
+dead weight" — it simply cannot answer "was it opened away from home".
+
+THE INDEX carries `note_id` first, matching `ix_note_usage_note_event`: every
+readout starts from a set of note ids and narrows, never from a project.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0105"
+down_revision = "0104"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "note_usage_events",
+        sa.Column("project_id", sa.Integer(), nullable=True),
+    )
+    op.create_index(
+        "ix_note_usage_note_project",
+        "note_usage_events",
+        ["note_id", "project_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_note_usage_note_project", table_name="note_usage_events")
+    op.drop_column("note_usage_events", "project_id")

alembic/versions/0106_rule_usage_events_carry_an_outcome.py

@@ -0,0 +1,63 @@
+"""rule_usage_events carry an outcome, not just a read
+
+Revision ID: 0106
+Revises: 0105
+Create Date: 2026-09-20
+
+`rule_usage_events` can say a rule was SURFACED
+and that it was PULLED. It cannot say what happened next, so these two
+sessions leave identical telemetry:
+
+  - a rule surfaced, opened, and followed;
+  - a rule surfaced, opened, and silently ignored.
+
+The second is the more urgent by a distance, and it is the one the readout
+cannot name, and it is what an outcome column is for.
+
+TWO NEW EVENT VALUES, AND NO CHECK MIGRATION. `event` was created in 0094 as
+plain `sa.Text()` with no constraint — checked in the migration itself, not
+assumed from the model — so `applied` and `departed` join `surfaced` and
+`pulled` without a DROP/ADD pair. That pair is for CHECK-whitelisted columns
+and this is not one; noted explicitly because the next reader will reach for
+it here, and should be able to see in one place why it does not apply.
+
+THE THIRD STATE IS DERIVED, AND THAT IS NOT A SHORTCUT. Read-and-silently-
+unchanged is the absence of an outcome, and it has to be: an agent that knew
+it was ignoring a rule would not be ignoring it. There is no honest way to ask
+for that event, so nothing here tries. `applied` and `departed` are reported;
+the third state is what is left over when a rule was pulled and neither
+arrived. A schema that offered an `ignored` value would collect nothing and
+read as though it had measured something — a statistic that cannot vary
+being mistaken for a finding.
+
+`detail` CARRIES THE WHY OF A DEPARTURE, and is the reason this is a column
+rather than two more bare event strings. A departure without its reason is
+indistinguishable from a miss when someone reads the table back, so the two
+states the milestone wants to tell apart would collapse again one layer down.
+Nullable because `applied` needs no argument — following a rule is the
+unremarkable case, and demanding prose for it would make the cheap event
+expensive and stop it being recorded at all.
+
+NO NEW INDEX. Every outcome readout starts from a set of rule ids and narrows
+by event, which is exactly `ix_rule_usage_rule_event` (rule_id, event) from
+0094. Adding a `detail` index would serve no query anyone has — the column is
+read, never filtered on.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0106"
+down_revision = "0105"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "rule_usage_events",
+        sa.Column("detail", sa.Text(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("rule_usage_events", "detail")

alembic/versions/0107_system_embeddings.py

@@ -0,0 +1,66 @@
+"""system_embeddings — a charter becomes an ANSWER, not just a filter
+
+Revision ID: 0107
+Revises: 0106
+Create Date: 2026-09-21
+
+A System's `description` is a charter: several hundred words saying what
+belongs in that area and what does not. It is the answer to "which part of
+this codebase does X live in", and there was no semantic path to it.
+`list_systems` enumerates and `search(system_id=…)` uses a System as a FILTER
+over notes — so a System could narrow a search and could never be the answer
+to one, and an agent asking where a record belonged had to read every charter
+or guess.
+
+The fourth sibling of note_embeddings (0067), rule_embeddings (0089) and
+milestone_embeddings (0102), and for the same reason as the third: the row could be shared, the search cannot. "Where does this belong?"
+is a different question from "what prior art is there?", and no note or rule
+search can answer it, because a charter is not a note.
+
+The vectors are DERIVED: nothing is backfilled here, the startup backfill
+writes them.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0107"
+down_revision = "0106"
+branch_labels = None
+depends_on = None
+
+# Matches its three siblings — bge-small-en-v1.5, 384-dim.
+_EMBEDDING_DIM = 384
+
+
+def upgrade() -> None:
+    op.create_table(
+        "system_embeddings",
+        sa.Column(
+            "system_id", sa.Integer(),
+            sa.ForeignKey("systems.id", ondelete="CASCADE"), primary_key=True,
+        ),
+        sa.Column("chunk_index", sa.Integer(), primary_key=True),
+        sa.Column("chunk_text", sa.Text(), nullable=False),
+        sa.Column("chunker_version", sa.Integer(), nullable=False),
+        sa.Column(
+            "updated_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+    )
+    # Raw DDL for the vector column, as 0067, 0089 and 0102 do: the type comes
+    # from the pgvector extension, not SQLAlchemy's type system.
+    op.execute(
+        f"ALTER TABLE system_embeddings ADD COLUMN embedding vector({_EMBEDDING_DIM}) NOT NULL"
+    )
+    op.execute(
+        """
+        CREATE INDEX ix_system_embeddings_embedding_hnsw
+            ON system_embeddings
+         USING hnsw (embedding vector_cosine_ops)
+        """
+    )
+
+
+def downgrade() -> None:
+    op.execute("DROP INDEX IF EXISTS ix_system_embeddings_embedding_hnsw")
+    op.drop_table("system_embeddings")

alembic/versions/0108_trigger_leaves_the_stored_title.py

@@ -0,0 +1,63 @@
+"""trigger_leaves_the_stored_title — a snippet's and lesson's title is its name
+
+Revision ID: 0108
+Revises: 0107
+Create Date: 2026-09-23
+
+Snippets and lessons stored their title as `subject — trigger`, because the
+join is what makes these kinds rank on the situation they apply to and
+the stored title WAS the embedded one. Every surface that shows a title then
+showed the trigger too: menu lines, lists and search rows ran to 1,500–3,000
+characters, and an injected repeat spent all of it again.
+
+The trigger's home is `data`, and the join happens at embed time (`embeddings.document_title`). This revision
+rewrites the rows already stored.
+
+EXACT-SUFFIX, READ FROM THE ROW'S OWN MIRROR. A title is only rewritten when
+it ends with `' — ' || <that row's trigger>`, so a subject that legitimately
+contains an em dash is never cut, and a row whose title and mirror disagree —
+hand-edited through the generic note door — is left alone. Such a row still
+embeds correctly (`document_title` is idempotent) and merely shows its old
+title; that is the right way round for a data migration to fail.
+
+NO RE-EMBED, AND `updated_at` IS NOT TOUCHED. The embedded text is identical
+before and after, so the vectors are already right. The startup backfill
+re-embeds any row whose `updated_at` is newer than its vectors, and a raw
+UPDATE that leaves `updated_at` alone is what keeps this from queueing the
+whole snippet corpus for work that would produce the same numbers. There is
+no database trigger on `updated_at`; it is set by the ORM only.
+"""
+from alembic import op
+
+revision = "0108"
+down_revision = "0107"
+branch_labels = None
+depends_on = None
+
+# kind → the `data` key its trigger is mirrored under (embeddings._TRIGGER_DATA_KEYS).
+_KINDS = (("snippet", "when_to_use"), ("lesson", "when_to_apply"))
+_SEP = " — "
+
+
+def upgrade() -> None:
+    for note_type, key in _KINDS:
+        op.execute(f"""
+            UPDATE notes
+               SET title = btrim(left(title, length(title) - length('{_SEP}' || (data->>'{key}'))))
+             WHERE note_type = '{note_type}'
+               AND coalesce(btrim(data->>'{key}'), '') <> ''
+               AND right(title, length('{_SEP}' || (data->>'{key}'))) = '{_SEP}' || (data->>'{key}')
+        """)
+
+
+def downgrade() -> None:
+    # Recompose, on the same condition inverted: only where the trigger is not
+    # already on the end, so a downgrade run twice cannot double it.
+    for note_type, key in _KINDS:
+        op.execute(f"""
+            UPDATE notes
+               SET title = title || '{_SEP}' || (data->>'{key}')
+             WHERE note_type = '{note_type}'
+               AND coalesce(btrim(data->>'{key}'), '') <> ''
+               AND right(title, length('{_SEP}' || (data->>'{key}'))) <> '{_SEP}' || (data->>'{key}')
+        """)

alembic/versions/0109_embeddings_record_their_model.py

@@ -0,0 +1,42 @@
+"""embeddings_record_their_model — a vector says whose space it lives in
+
+Revision ID: 0109
+Revises: 0108
+Create Date: 2026-09-23
+
+Every embedding table stamps `chunker_version`, so a change to the document
+shape is caught per row and re-embedded. None stamped the MODEL. The column is
+`vector(384)` — a width, not an identity — so swapping bge-small for any other
+384-dim model would write a second geometry beside the first with no error,
+and search would go on ranking by cosines between the two, which mean nothing.
+
+`embedding_model` is the other half of `calibration_stamp()`, stored per row on
+all four tables. The startup backfill now re-embeds on either half moving.
+
+THE BACKFILL LITERAL IS SAFE BECAUSE NO INSTALL HAS EVER CHANGED MODELS. The
+name is hardcoded in `services/embeddings.py`, and every vector ever written was
+written by it — so stamping every existing row with that name states a fact,
+not a guess. It is frozen here rather than imported: a migration records what
+was true when it ran, and a later model change must not rewrite history.
+"""
+from alembic import op
+
+revision = "0109"
+down_revision = "0108"
+branch_labels = None
+depends_on = None
+
+_TABLES = ("note_embeddings", "rule_embeddings", "milestone_embeddings", "system_embeddings")
+_MODEL = "BAAI/bge-small-en-v1.5"
+
+
+def upgrade() -> None:
+    for table in _TABLES:
+        op.execute(f"ALTER TABLE {table} ADD COLUMN embedding_model text")
+        op.execute(f"UPDATE {table} SET embedding_model = '{_MODEL}'")
+        op.execute(f"ALTER TABLE {table} ALTER COLUMN embedding_model SET NOT NULL")
+
+
+def downgrade() -> None:
+    for table in _TABLES:
+        op.execute(f"ALTER TABLE {table} DROP COLUMN embedding_model")

alembic/versions/0110_task_claims.py

@@ -0,0 +1,38 @@
+"""task_claims — a task can say a session is working it
+
+Revision ID: 0110
+Revises: 0109
+Create Date: 2026-09-23
+
+`status` is durable and nothing clears it, so `in_progress` cannot also mean
+"someone is on this now". The claim is that second meaning, stored as WHO and
+WHEN rather than as a flag, so it can be read as dead without anything having
+cleared it (`services/task_claims.py` has the semantics).
+
+Four nullable columns, no backfill: no existing row has ever been claimed, and
+inventing a claim for one would assert attention nobody observed. No CHECK
+enum is touched.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0110"
+down_revision = "0109"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("notes", sa.Column(
+        "claimed_by", sa.Integer(), sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True,
+    ))
+    op.add_column("notes", sa.Column("claimed_at", sa.DateTime(timezone=True), nullable=True))
+    op.add_column("notes", sa.Column("claim_touched_at", sa.DateTime(timezone=True), nullable=True))
+    op.add_column("notes", sa.Column("claim_session", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("notes", "claim_session")
+    op.drop_column("notes", "claim_touched_at")
+    op.drop_column("notes", "claimed_at")
+    op.drop_column("notes", "claimed_by")

alembic/versions/0111_lesson_rule_links.py

@@ -0,0 +1,53 @@
+"""lesson_rule_links — a lesson points at the rule it is an instance of
+
+Revision ID: 0111
+Revises: 0110
+Create Date: 2026-10-01
+
+One row per (lesson, rule) pair with a state: `suggested` while evidence
+accumulates, `confirmed` or `rejected` once a judgment is made. Only a
+confirmed link changes what surfaces; a rejected one is kept so the pair is not
+proposed again. CASCADE on both ends — a link to a record that no longer exists
+says nothing. No backfill: no lesson has ever been linked, and inventing a link
+would assert a judgment nobody made.
+"""
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from alembic import op
+
+revision = "0111"
+down_revision = "0110"
+branch_labels = None
+depends_on = None
+
+# One place, so the CHECK and the model's LINK_STATES cannot drift (a new
+# value later means DROP + ADD CONSTRAINT in the same migration).
+_STATES = ("suggested", "confirmed", "rejected")
+
+
+def upgrade() -> None:
+    op.create_table(
+        "lesson_rule_links",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column("lesson_id", sa.Integer(), sa.ForeignKey("notes.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("rule_id", sa.BigInteger(), sa.ForeignKey("rules.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("state", sa.Text(), nullable=False, server_default="suggested"),
+        sa.Column("note", sa.Text(), nullable=True),
+        sa.Column("evidence", postgresql.JSONB(), nullable=True),
+        sa.Column("judged_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.UniqueConstraint("lesson_id", "rule_id", name="uq_lesson_rule_links_pair"),
+    )
+    op.create_check_constraint(
+        "ck_lesson_rule_links_state", "lesson_rule_links",
+        "state IN (" + ", ".join(f"'{s}'" for s in _STATES) + ")",
+    )
+    op.create_index("ix_lesson_rule_links_lesson_id", "lesson_rule_links", ["lesson_id"])
+    op.create_index("ix_lesson_rule_links_rule_id", "lesson_rule_links", ["rule_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_lesson_rule_links_rule_id", table_name="lesson_rule_links")
+    op.drop_index("ix_lesson_rule_links_lesson_id", table_name="lesson_rule_links")
+    op.drop_constraint("ck_lesson_rule_links_state", "lesson_rule_links", type_="check")
+    op.drop_table("lesson_rule_links")

alembic/versions/0112_lesson_no_rule.py

@@ -0,0 +1,32 @@
+"""lesson_no_rule — "no rule fits" is a recorded answer
+
+Revision ID: 0112
+Revises: 0111
+Create Date: 2026-10-01
+
+One row per lesson that was judged to fall under no rule, with the reason. A
+lesson with neither a confirmed link nor this row is UNJUDGED, which is what
+`list_lessons(unjudged=true)` lists. CASCADE from the lesson. No backfill: no
+lesson has been judged yet, and writing "no rule fits" for one nobody looked
+at would assert a judgment nobody made.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0112"
+down_revision = "0111"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "lesson_no_rule",
+        sa.Column("lesson_id", sa.Integer(), sa.ForeignKey("notes.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("why", sa.Text(), nullable=False),
+        sa.Column("judged_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("lesson_no_rule")

alembic/versions/0113_system_path_patterns.py

@@ -0,0 +1,33 @@
+"""system_path_patterns — a System names the files that are its area
+
+Revision ID: 0113
+Revises: 0112
+Create Date: 2026-10-02
+
+A JSONB list of globs relative to the repo root. NOT NULL with a `[]`
+default, so an existing System reads as "no paths yet" rather than as NULL. No
+backfill: which files are which area is a judgment, and the charters that name
+directories in prose are not a mapping anyone confirmed.
+"""
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+revision = "0113"
+down_revision = "0112"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "systems",
+        sa.Column(
+            "path_patterns", postgresql.JSONB(), nullable=False,
+            server_default=sa.text("'[]'::jsonb"),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("systems", "path_patterns")

alembic/versions/0114_system_usage_events.py

@@ -0,0 +1,45 @@
+"""system_usage_events — were an area's rulings read once its files were
+touched?
+
+Revision ID: 0114
+Revises: 0113
+Create Date: 2026-10-03
+
+The usage twin for Systems, beside note_usage_events and rule_usage_events and
+separate from both for the same reason they are separate from each other: a
+System id restores through its own map. FK-free like its siblings; no CHECK on
+`event`, like its siblings.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0114"
+down_revision = "0113"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "system_usage_events",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("user_id", sa.BigInteger(), nullable=True),
+        sa.Column("system_id", sa.BigInteger(), nullable=False),
+        sa.Column("event", sa.Text(), nullable=False),
+        sa.Column("source", sa.Text(), nullable=False),
+        sa.Column("project_id", sa.BigInteger(), nullable=True),
+    )
+    op.create_index(
+        "ix_system_usage_system_event", "system_usage_events", ["system_id", "event"]
+    )
+    op.create_index("ix_system_usage_created_at", "system_usage_events", ["created_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_system_usage_created_at", table_name="system_usage_events")
+    op.drop_index("ix_system_usage_system_event", table_name="system_usage_events")
+    op.drop_table("system_usage_events")

alembic/versions/0115_retrieval_judgments.py

@@ -0,0 +1,55 @@
+"""retrieval_judgments — a reviewer's verdict on each line of a logged menu
+
+Revision ID: 0115
+Revises: 0114
+Create Date: 2026-10-03
+
+Whether an injected line RELATED, which the usage tables cannot say: since
+every line carries its matched passage, "not opened" no longer implies "not
+relevant". FK-free like the telemetry tables beside it; no CHECK on `verdict`,
+which the service validates.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0115"
+down_revision = "0114"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "retrieval_judgments",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("user_id", sa.BigInteger(), nullable=True),
+        sa.Column("retrieval_log_id", sa.BigInteger(), nullable=False),
+        sa.Column("source", sa.Text(), nullable=False),
+        sa.Column("query", sa.Text(), nullable=True),
+        sa.Column("record_id", sa.BigInteger(), nullable=False),
+        sa.Column("rank", sa.Integer(), nullable=False),
+        sa.Column("score", sa.Float(), nullable=True),
+        sa.Column("within_budget", sa.Boolean(), nullable=False),
+        sa.Column("verdict", sa.Text(), nullable=False),
+        sa.Column("reason", sa.Text(), nullable=False),
+        sa.Column("opened_after", sa.Boolean(), nullable=True),
+        sa.UniqueConstraint(
+            "retrieval_log_id", "record_id", "user_id",
+            name="uq_retrieval_judgment_line",
+        ),
+    )
+    op.create_index(
+        "ix_retrieval_judgments_source_created", "retrieval_judgments",
+        ["source", "created_at"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_retrieval_judgments_source_created", table_name="retrieval_judgments",
+    )
+    op.drop_table("retrieval_judgments")

alembic/versions/0116_moment_mappings.py

@@ -0,0 +1,47 @@
+"""moment_mappings — an install's own corrections to which actions reach which
+moment
+
+Revision ID: 0116
+Revises: 0115
+Create Date: 2026-10-05
+
+The moments and their default actions are code; this table holds what an
+install adds ("make ship" is a deliver here) and the defaults it switches off.
+User-owned configuration, so it cascades with the user. No CHECK on `effect`,
+which the service validates.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0116"
+down_revision = "0115"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "moment_mappings",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column(
+            "user_id", sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column("tool", sa.Text(), nullable=False),
+        sa.Column("match", sa.Text(), nullable=False, server_default=""),
+        sa.Column("moment", sa.Text(), nullable=False),
+        sa.Column("effect", sa.Text(), nullable=False, server_default="add"),
+        sa.Column("reason", sa.Text(), nullable=False, server_default=""),
+        sa.Column("actor", sa.Text(), nullable=False, server_default="model"),
+        sa.UniqueConstraint(
+            "user_id", "tool", "match", "moment", name="uq_moment_mapping",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("moment_mappings")

alembic/versions/0117_rule_moments.py

@@ -0,0 +1,38 @@
+"""rule_moments — the moments of work a rule arrives at
+
+Revision ID: 0117
+Revises: 0116
+Create Date: 2026-10-05
+
+A rule mounted on a moment is delivered whenever that moment happens, by
+lookup rather than by score. The moment is a catalog name, validated by the
+service; the catalog is code, so there is no table to key it to. Cascades
+with the rule, like rule_systems beside it.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0117"
+down_revision = "0116"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "rule_moments",
+        sa.Column(
+            "rule_id", sa.BigInteger(),
+            sa.ForeignKey("rules.id", ondelete="CASCADE"), primary_key=True,
+        ),
+        sa.Column("moment", sa.Text(), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    # The delivery read asks "which rules are on this moment?", the
+    # opposite direction from the primary key.
+    op.create_index("ix_rule_moments_moment", "rule_moments", ["moment"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_rule_moments_moment", table_name="rule_moments")
+    op.drop_table("rule_moments")

alembic/versions/0118_rule_moment_judgments.py

@@ -0,0 +1,60 @@
+"""rule_moment_judgments — whether a rule belongs on a moment, and who said so
+
+Revision ID: 0118
+Revises: 0117
+Create Date: 2026-10-05
+
+One row per (rule, moment) with a state: `suggested` while a proposal waits
+for a judgment, `confirmed` or `rejected` once one is made. The mount itself
+stays in rule_moments; this records the proposals that are not mounts yet and
+the rejections that must stop them being proposed again. Moment '' is "no
+moment fits this rule". CASCADE on the rule — a judgment about a rule that no
+longer exists says nothing. No backfill: the mounts made before this table
+were judgments too, but recording them now would invent who made them.
+"""
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from alembic import op
+
+revision = "0118"
+down_revision = "0117"
+branch_labels = None
+depends_on = None
+
+# One place each, so the CHECKs and the model's JUDGMENT_STATES / SOURCES
+# cannot drift (a new value later means DROP + ADD CONSTRAINT in the same
+# migration).
+_STATES = ("suggested", "confirmed", "rejected")
+_SOURCES = ("pass", "signal", "edit")
+
+
+def upgrade() -> None:
+    op.create_table(
+        "rule_moment_judgments",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column("rule_id", sa.BigInteger(), sa.ForeignKey("rules.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("moment", sa.Text(), nullable=False),
+        sa.Column("state", sa.Text(), nullable=False, server_default="suggested"),
+        sa.Column("source", sa.Text(), nullable=False, server_default="pass"),
+        sa.Column("note", sa.Text(), nullable=True),
+        sa.Column("evidence", postgresql.JSONB(), nullable=True),
+        sa.Column("judged_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.UniqueConstraint("rule_id", "moment", name="uq_rule_moment_judgments_pair"),
+    )
+    op.create_check_constraint(
+        "ck_rule_moment_judgments_state", "rule_moment_judgments",
+        "state IN (" + ", ".join(f"'{s}'" for s in _STATES) + ")",
+    )
+    op.create_check_constraint(
+        "ck_rule_moment_judgments_source", "rule_moment_judgments",
+        "source IN (" + ", ".join(f"'{s}'" for s in _SOURCES) + ")",
+    )
+    op.create_index("ix_rule_moment_judgments_rule_id", "rule_moment_judgments", ["rule_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_rule_moment_judgments_rule_id", table_name="rule_moment_judgments")
+    op.drop_constraint("ck_rule_moment_judgments_source", "rule_moment_judgments", type_="check")
+    op.drop_constraint("ck_rule_moment_judgments_state", "rule_moment_judgments", type_="check")
+    op.drop_table("rule_moment_judgments")

alembic/versions/0119_rule_moment_misfires.py

@@ -0,0 +1,36 @@
+"""rule_moment_judgments.misfire — a mount reported as arriving where it does
+not apply
+
+Revision ID: 0119
+Revises: 0118
+Create Date: 2026-10-05
+
+The open-after-moment signal proposes a mount; nothing proposed taking one
+off. This column is the evidence for that direction: each time a session says
+a mounted rule arrived at a moment where it did not apply, the report is
+counted here per distinct day, with its reason and the action that reached
+the moment. At the bar it becomes an unmount proposal for the operator.
+
+A column on the judgment row rather than a table of its own: a misfire is
+always about a (rule, moment) pair that is mounted, and that pair already has
+its row. Nullable and no backfill — nobody has reported a misfire yet.
+"""
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from alembic import op
+
+revision = "0119"
+down_revision = "0118"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "rule_moment_judgments",
+        sa.Column("misfire", postgresql.JSONB(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("rule_moment_judgments", "misfire")

alembic/versions/0120_family_canon.py

@@ -0,0 +1,288 @@
+"""family canon — platforms, family ideas, the adoption ledger and its decision
+log
+
+Revision ID: 0120
+Revises: 0119
+Create Date: 2026-10-06
+
+When one project solves something every project on the same platform will
+meet, that solution becomes FAMILY CANON, and every other project on the
+platform answers it: adopted, a variant (with a reason), exempt (with a
+reason), or owed. These tables hold that.
+
+- `platforms` — a GLOBAL catalog, the canonical_systems shape: no owner, slug
+  is the match key. Seeded with generic technology names only. Nothing here
+  names an app, a repo or a house convention: the catalog ships to every
+  install.
+- `project_platforms` — which platforms a project is (declared / detected /
+  rejected). Membership is what makes "is this in family?" a lookup.
+- `family_ideas` — a NOTE's family state. No new record type: any notes row
+  (a note, a snippet, a lesson) becomes an idea by gaining one of these.
+- `family_idea_platforms` — the platforms an idea is for; the only scope
+  source. A linked rule topic takes its scope from the idea.
+- `family_idea_references` — reference implementations (snippets).
+- `family_adoptions` — one row per (project, idea): the project's answer.
+- `family_decisions` — append-only log of every promotion and ledger change.
+
+No backfill. No project has declared a platform and no note is an idea yet;
+inventing either would assert a judgment nobody made. The seed rows are
+written here verbatim rather than imported, so the migration keeps running
+unchanged after any service-side list moves on.
+"""
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+from alembic import op
+
+revision = "0120"
+down_revision = "0119"
+branch_labels = None
+depends_on = None
+
+# One place per whitelist, so each CHECK and the model's tuple cannot drift
+# (a new value later means DROP + ADD CONSTRAINT in one migration).
+_MEMBERSHIP = ("declared", "detected", "rejected")
+_IDEA_STATUSES = ("candidate", "canon", "retired")
+_ADOPTION_STATUSES = ("unassessed", "adopted", "variant", "exempt", "owed")
+_REASONED = ("variant", "exempt")
+_ACTIONS = ("propose", "promote", "revise", "retire", "assess", "undo")
+_DECIDERS = ("agent", "operator", "system")
+
+
+def _in(column: str, values: tuple[str, ...]) -> str:
+    return f"{column} IN (" + ", ".join(f"'{v}'" for v in values) + ")"
+
+
+# (name, slug, description, markers). A marker with no slash matches a file's
+# basename anywhere in a repo; one with a slash matches the repo-relative
+# path. Empty markers = declare-only, for a platform that leaves no reliable
+# file behind. Generic on purpose — an install adds its own.
+_SEED = (
+    ("Android app", "android-app",
+     "A native Android client: an APK or app bundle installed on phones and tablets.",
+     ["AndroidManifest.xml"]),
+    ("iOS app", "ios-app",
+     "A native iOS or iPadOS client built with Xcode.",
+     ["project.pbxproj"]),
+    ("Web frontend", "web-frontend",
+     "A browser client built with a frontend toolchain: single-page apps and server-rendered frontends.",
+     ["vite.config.*", "svelte.config.*", "vue.config.*", "next.config.*",
+      "nuxt.config.*", "angular.json"]),
+    ("Browser extension", "browser-extension",
+     "An extension installed into a web browser and distributed through its add-on store or by file.",
+     []),
+    ("Desktop app", "desktop-app",
+     "A packaged desktop application for Windows, macOS or Linux.",
+     ["tauri.conf.json", "electron-builder.*"]),
+    ("Container image", "container-image",
+     "Ships as an OCI/Docker image that a host pulls and runs.",
+     ["Dockerfile", "Containerfile", "*.Dockerfile"]),
+    ("Go", "go",
+     "Written in Go.",
+     ["go.mod"]),
+    ("Python", "python",
+     "Written in Python.",
+     ["pyproject.toml", "setup.py", "requirements.txt"]),
+    ("Rust", "rust",
+     "Written in Rust.",
+     ["Cargo.toml"]),
+    ("PostgreSQL", "postgresql",
+     "Keeps its data in PostgreSQL.",
+     []),
+    ("GitHub Actions", "github-actions",
+     "Verified and released by GitHub Actions workflows.",
+     [".github/workflows/*"]),
+    ("Gitea / Forgejo Actions", "gitea-actions",
+     "Verified and released by Gitea or Forgejo Actions workflows.",
+     [".gitea/workflows/*", ".forgejo/workflows/*"]),
+)
+
+
+def upgrade() -> None:
+    platforms = op.create_table(
+        "platforms",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.Text(), nullable=False),
+        sa.Column("slug", sa.Text(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("markers", postgresql.JSONB(), nullable=False,
+                  server_default=sa.text("'[]'::jsonb")),
+        sa.Column("order_index", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("deleted_batch_id", sa.Text(), nullable=True),
+    )
+    # Unique among LIVE rows only (the canonical_systems convention).
+    op.create_index(
+        "uq_platforms_slug", "platforms", ["slug"],
+        unique=True, postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+    op.bulk_insert(
+        platforms,
+        [
+            {"name": name, "slug": slug, "description": description,
+             "markers": markers, "order_index": index}
+            for index, (name, slug, description, markers) in enumerate(_SEED)
+        ],
+    )
+
+    op.create_table(
+        "project_platforms",
+        sa.Column("project_id", sa.Integer(),
+                  sa.ForeignKey("projects.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("platform_id", sa.Integer(),
+                  sa.ForeignKey("platforms.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("state", sa.Text(), nullable=False, server_default="declared"),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+    op.create_check_constraint(
+        "ck_project_platforms_state", "project_platforms", _in("state", _MEMBERSHIP),
+    )
+    op.create_index("ix_project_platforms_platform_id", "project_platforms", ["platform_id"])
+
+    op.create_table(
+        "family_ideas",
+        sa.Column("note_id", sa.Integer(),
+                  sa.ForeignKey("notes.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("status", sa.Text(), nullable=False, server_default="candidate"),
+        sa.Column("applies_when", sa.Text(), nullable=True),
+        sa.Column("canon_version", sa.Integer(), nullable=False, server_default="1"),
+        # SET NULL: deleting a topic must not delete the standard it served.
+        sa.Column("topic_id", sa.BigInteger(),
+                  sa.ForeignKey("rulebook_topics.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+    op.create_check_constraint(
+        "ck_family_ideas_status", "family_ideas", _in("status", _IDEA_STATUSES),
+    )
+    # The first promotion criterion, held by the schema: an idea is not canon
+    # until it says, in platform terms, when it applies.
+    op.create_check_constraint(
+        "ck_family_ideas_canon_applies", "family_ideas",
+        "status <> 'canon' OR length(btrim(coalesce(applies_when, ''))) > 0",
+    )
+    op.create_check_constraint(
+        "ck_family_ideas_canon_version", "family_ideas", "canon_version >= 1",
+    )
+    op.create_index(
+        "uq_family_ideas_topic", "family_ideas", ["topic_id"],
+        unique=True, postgresql_where=sa.text("topic_id IS NOT NULL"),
+    )
+    op.create_index("ix_family_ideas_status", "family_ideas", ["status"])
+
+    op.create_table(
+        "family_idea_platforms",
+        sa.Column("note_id", sa.Integer(),
+                  sa.ForeignKey("family_ideas.note_id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("platform_id", sa.Integer(),
+                  sa.ForeignKey("platforms.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+    op.create_index("ix_family_idea_platforms_platform_id", "family_idea_platforms", ["platform_id"])
+
+    op.create_table(
+        "family_idea_references",
+        sa.Column("idea_id", sa.Integer(),
+                  sa.ForeignKey("family_ideas.note_id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("snippet_id", sa.Integer(),
+                  sa.ForeignKey("notes.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+    op.create_index("ix_family_idea_references_snippet_id", "family_idea_references", ["snippet_id"])
+
+    op.create_table(
+        "family_adoptions",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column("project_id", sa.Integer(),
+                  sa.ForeignKey("projects.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("idea_id", sa.Integer(),
+                  sa.ForeignKey("family_ideas.note_id", ondelete="CASCADE"), nullable=False),
+        sa.Column("status", sa.Text(), nullable=False, server_default="unassessed"),
+        sa.Column("reason", sa.Text(), nullable=True),
+        sa.Column("canon_version", sa.Integer(), nullable=True),
+        sa.Column("assessed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("decided_via", sa.Text(), nullable=True),
+        sa.Column("owed_task_id", sa.Integer(),
+                  sa.ForeignKey("notes.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+    op.create_check_constraint(
+        "ck_family_adoptions_status", "family_adoptions", _in("status", _ADOPTION_STATUSES),
+    )
+    # A departure is only a record if it says why.
+    op.create_check_constraint(
+        "ck_family_adoptions_reason", "family_adoptions",
+        "NOT (" + _in("status", _REASONED) + ") "
+        "OR length(btrim(coalesce(reason, ''))) > 0",
+    )
+    op.create_check_constraint(
+        "ck_family_adoptions_decided_via", "family_adoptions",
+        "decided_via IS NULL OR " + _in("decided_via", _DECIDERS),
+    )
+    op.create_index(
+        "uq_family_adoptions_pair", "family_adoptions", ["project_id", "idea_id"], unique=True,
+    )
+    op.create_index("ix_family_adoptions_project_id", "family_adoptions", ["project_id"])
+    op.create_index("ix_family_adoptions_idea_id", "family_adoptions", ["idea_id"])
+
+    op.create_table(
+        "family_decisions",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column("idea_id", sa.Integer(),
+                  sa.ForeignKey("family_ideas.note_id", ondelete="CASCADE"), nullable=False),
+        sa.Column("project_id", sa.Integer(),
+                  sa.ForeignKey("projects.id", ondelete="CASCADE"), nullable=True),
+        sa.Column("action", sa.Text(), nullable=False),
+        sa.Column("reason", sa.Text(), nullable=False),
+        sa.Column("before", postgresql.JSONB(), nullable=True),
+        sa.Column("after", postgresql.JSONB(), nullable=True),
+        sa.Column("evidence", postgresql.JSONB(), nullable=True),
+        sa.Column("precedent_ids", postgresql.JSONB(), nullable=False,
+                  server_default=sa.text("'[]'::jsonb")),
+        sa.Column("decided_via", sa.Text(), nullable=False, server_default="agent"),
+        sa.Column("user_id", sa.Integer(),
+                  sa.ForeignKey("users.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
+    )
+    op.create_check_constraint(
+        "ck_family_decisions_action", "family_decisions", _in("action", _ACTIONS),
+    )
+    op.create_check_constraint(
+        "ck_family_decisions_decided_via", "family_decisions", _in("decided_via", _DECIDERS),
+    )
+    # The reason IS the record — the agent decides with no approval step, so
+    # a decision that cannot say why is not one anybody can review or follow.
+    op.create_check_constraint(
+        "ck_family_decisions_reason", "family_decisions", "length(btrim(reason)) > 0",
+    )
+    op.create_index("ix_family_decisions_idea_id", "family_decisions", ["idea_id"])
+    op.create_index("ix_family_decisions_project_id", "family_decisions", ["project_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_family_decisions_project_id", table_name="family_decisions")
+    op.drop_index("ix_family_decisions_idea_id", table_name="family_decisions")
+    op.drop_table("family_decisions")
+
+    op.drop_index("ix_family_adoptions_idea_id", table_name="family_adoptions")
+    op.drop_index("ix_family_adoptions_project_id", table_name="family_adoptions")
+    op.drop_index("uq_family_adoptions_pair", table_name="family_adoptions")
+    op.drop_table("family_adoptions")
+
+    op.drop_index("ix_family_idea_references_snippet_id", table_name="family_idea_references")
+    op.drop_table("family_idea_references")
+
+    op.drop_index("ix_family_idea_platforms_platform_id", table_name="family_idea_platforms")
+    op.drop_table("family_idea_platforms")
+
+    op.drop_index("ix_family_ideas_status", table_name="family_ideas")
+    op.drop_index("uq_family_ideas_topic", table_name="family_ideas")
+    op.drop_table("family_ideas")
+
+    op.drop_index("ix_project_platforms_platform_id", table_name="project_platforms")
+    op.drop_table("project_platforms")
+
+    op.drop_index("uq_platforms_slug", table_name="platforms")
+    op.drop_table("platforms")

alembic/versions/0121_retire_report_preference.py

@@ -0,0 +1,58 @@
+"""retire the report_preference arm's rows
+
+Revision ID: 0121
+Revises: 0120
+Create Date: 2026-10-09
+
+The fixed-question arm that searched for completion-report preferences when a
+task closed is gone: the reply shapes and the preferences mounted beside them
+now arrive on the moments. Its rows go with it (there is no legacy to
+preserve), because each one would otherwise mean something
+different once the arm is no longer registered:
+
+- `retrieval_logs` / `retrieval_judgments` — a source missing from the
+  registry reads as `unregistered_source`, whose advice is "add it to the
+  registry": the opposite of what happened.
+- `rule_usage_events` — a source missing from `RANKED_SOURCES` reads as
+  ambient, so its surfacings would silently move into the other column of
+  every rule's pull-through.
+- `retrieval_tuning_events` — the tuning history of a surface that no longer
+  exists.
+- `settings` — the arm's floor and budget keys, which nothing reads.
+
+COST IS BOUNDED BY AN INDEX, NOT BY THE TABLE. A migration runs at boot
+against the live tables, which CI never has. `retrieval_logs`
+and `retrieval_judgments` are indexed on `source`. `rule_usage_events` is not,
+so its delete is also bounded by `created_at` (indexed): no row of the arm
+predates `ARM_BORN`, and the scan covers weeks rather than the table's whole history.
+
+Not reversible: the arm is not coming back, so neither are its rows.
+"""
+from alembic import op
+
+revision = "0121"
+down_revision = "0120"
+branch_labels = None
+depends_on = None
+
+SOURCE = "report_preference"
+# A safe floor under the arm's first row (it shipped after 2026-09-14).
+ARM_BORN = "2026-09-01"
+
+
+def upgrade() -> None:
+    op.execute(f"DELETE FROM retrieval_logs WHERE source = '{SOURCE}'")
+    op.execute(f"DELETE FROM retrieval_judgments WHERE source = '{SOURCE}'")
+    op.execute(
+        f"DELETE FROM rule_usage_events WHERE created_at >= '{ARM_BORN}' "
+        f"AND source = '{SOURCE}'"
+    )
+    op.execute(f"DELETE FROM retrieval_tuning_events WHERE surface = '{SOURCE}'")
+    op.execute(
+        "DELETE FROM settings WHERE key IN "
+        "('kb_reportpref_threshold', 'kb_reportpref_top_k')"
+    )
+
+
+def downgrade() -> None:
+    pass

alembic/versions/0122_seal_forge_tokens.py

@@ -0,0 +1,82 @@
+"""Seal forge-connection tokens at rest
+
+Revision ID: 0122
+Revises: 0121
+Create Date: 2026-10-15
+
+A forge token was stored as plain text, so a copy of the database (or of a
+backup tool's snapshot of it) was enough to read every user's forge
+credential. Tokens are now sealed the way the backup destination's S3 secret
+is (services/secrets.py): Fernet under a key derived from SECRET_KEY, which
+lives in the deployment's environment rather than in the data.
+
+The column is renamed `token` -> `token_sealed` in the same step. The name
+says what the bytes are, and every reader has to change with it, so a reader
+missed here fails on a missing attribute instead of quietly sending
+ciphertext to the forge as a token.
+
+THE KEY DERIVATION IS FROZEN HERE, not imported. This revision must seal with
+exactly v1's key forever; importing services.secrets would let a later edit
+there change what an old migration writes. The unit lane checks that what
+this produces is what `secrets.unseal` opens today.
+
+Cost: one row per (user, forge host) — a handful per instance.
+
+Downgrade opens each token back into plain text. A row sealed under a
+different SECRET_KEY cannot be opened and comes back empty; its owner enters
+the token again.
+"""
+import base64
+import hashlib
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0122"
+down_revision = "0121"
+branch_labels = None
+depends_on = None
+
+_LABEL_V1 = b"scribe.secrets.v1\x00"
+
+
+def _fernet():
+    from cryptography.fernet import Fernet
+
+    from grimoire.config import Config
+
+    digest = hashlib.sha256(_LABEL_V1 + Config.SECRET_KEY.encode()).digest()
+    return Fernet(base64.urlsafe_b64encode(digest))
+
+
+def seal_v1(plain: str) -> str:
+    return _fernet().encrypt(plain.encode()).decode()
+
+
+def upgrade() -> None:
+    op.alter_column("forge_connections", "token", new_column_name="token_sealed")
+    bind = op.get_bind()
+    rows = bind.execute(sa.text("SELECT id, token_sealed FROM forge_connections")).all()
+    for row_id, plain in rows:
+        bind.execute(
+            sa.text("UPDATE forge_connections SET token_sealed = :v WHERE id = :id"),
+            {"v": seal_v1(plain or ""), "id": row_id},
+        )
+
+
+def downgrade() -> None:
+    from cryptography.fernet import InvalidToken
+
+    bind = op.get_bind()
+    fernet = _fernet()
+    rows = bind.execute(sa.text("SELECT id, token_sealed FROM forge_connections")).all()
+    for row_id, sealed in rows:
+        try:
+            plain = fernet.decrypt((sealed or "").encode()).decode()
+        except (InvalidToken, ValueError):
+            plain = ""
+        bind.execute(
+            sa.text("UPDATE forge_connections SET token_sealed = :v WHERE id = :id"),
+            {"v": plain, "id": row_id},
+        )
+    op.alter_column("forge_connections", "token_sealed", new_column_name="token")

alembic/versions/0123_drop_user_profiles.py

@@ -0,0 +1,64 @@
+"""drop user_profiles
+
+Revision ID: 0123
+Revises: 0122
+Create Date: 2026-10-22
+
+The Profile settings page asked for a display name, job title, expertise,
+response style, tone, interests and a work schedule, and said an assistant
+used them to personalise chat and a daily journal. Nothing in the app read
+any of it: the page saved to this table and the backup carried it, and that
+was all. The page, its API and the backup section are gone, and the table
+goes with them.
+
+Downgrade recreates the empty table, so the schema steps back cleanly; the
+rows themselves do not come back.
+"""
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import ARRAY, JSONB
+
+revision = "0123"
+down_revision = "0122"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_index("ix_user_profiles_user_id", table_name="user_profiles")
+    op.drop_table("user_profiles")
+
+
+def downgrade() -> None:
+    op.create_table(
+        "user_profiles",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+            unique=True,
+        ),
+        sa.Column("display_name", sa.Text(), nullable=True),
+        sa.Column("job_title", sa.Text(), nullable=True),
+        sa.Column("industry", sa.Text(), nullable=True),
+        sa.Column("expertise_level", sa.Text(), nullable=True),
+        sa.Column("response_style", sa.Text(), nullable=True),
+        sa.Column("tone", sa.Text(), nullable=True),
+        sa.Column("interests", ARRAY(sa.Text()), nullable=True),
+        sa.Column("work_schedule", JSONB(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    op.create_index("ix_user_profiles_user_id", "user_profiles", ["user_id"], unique=True)

alembic/versions/0124_skill_names_follow_the_plugin.py

@@ -0,0 +1,45 @@
+"""skill names follow the plugin's name
+
+Revision ID: 0124
+Revises: 0123
+Create Date: 2026-10-22
+
+The plugin is named `grimoire`, so its skills reach a session as
+`grimoire:<skill>` and stored processes as `grimoire-proc-<slug>`. A rule
+mounted on one of those skills, a judgment about that mount, and an install's
+own action mapping all store the skill's name, and a stored name the harness no
+longer sends never matches again. This rewrites the plugin's earlier prefixes,
+`scribe:` and `scribe-proc-`, to the current ones.
+
+Cost: three small tables, each one row per mount, judgment or mapping.
+"""
+from alembic import op
+
+revision = "0124"
+down_revision = "0123"
+branch_labels = None
+depends_on = None
+
+_MOMENT_TABLES = ("rule_moments", "rule_moment_judgments", "moment_mappings")
+
+
+def _rename(old: str, new: str) -> None:
+    for table in _MOMENT_TABLES:
+        op.execute(
+            f"UPDATE {table} SET moment = regexp_replace(moment, "
+            f"'^skill\\.{old}(:|-proc-)', 'skill.{new}\\1') "
+            f"WHERE moment ~ '^skill\\.{old}(:|-proc-)'"
+        )
+    op.execute(
+        f'UPDATE moment_mappings SET "match" = regexp_replace("match", '
+        f"'skill={old}(:|-proc-)', 'skill={new}\\1', 'g') "
+        f"WHERE \"match\" ~ 'skill={old}(:|-proc-)'"
+    )
+
+
+def upgrade() -> None:
+    _rename("scribe", "grimoire")
+
+
+def downgrade() -> None:
+    _rename("grimoire", "scribe")

alembic/versions/0125_drop_cross_project_reference_uses.py

@@ -0,0 +1,35 @@
+"""drop machine-written uses edges that cross projects
+
+Revision ID: 0125
+Revises: 0124
+Create Date: 2026-10-26
+
+A `uses` edge with basis `reference` is the proposer's by-name reading: the
+shape's body names a canon's symbol. A body never calls a function defined in
+another project's repository, so such an edge across projects is a common
+word matched, not a call. The proposer no longer writes them, and this removes
+the ones it wrote before. Edges a person or an audit judged keep their own
+basis and are left alone. Rows within one project are re-read on the next
+coverage refresh, which replaces their reference edges under the same rule.
+
+Downgrade restores nothing: the removed edges were never facts.
+"""
+from alembic import op
+
+revision = "0125"
+down_revision = "0124"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute(
+        "DELETE FROM code_shape_uses u USING code_shapes s, notes n "
+        "WHERE u.shape_id = s.id AND u.snippet_id = n.id "
+        "AND u.basis = 'reference' "
+        "AND n.project_id IS NOT NULL AND n.project_id <> s.project_id"
+    )
+
+
+def downgrade() -> None:
+    pass

alembic/versions/0126_drop_cross_project_hook_uses.py

@@ -0,0 +1,34 @@
+"""drop write-path uses edges that cross projects
+
+Revision ID: 0126
+Revises: 0125
+Create Date: 2026-10-26
+
+The write path records a `uses` edge with basis `hook` when a session pulled a
+snippet and then wrote code naming its symbol. That is by-name evidence, like
+the proposer's `reference` edges 0125 removed, and a body never calls a
+function defined in another project's repository. The write path now applies
+the same by-name test, so it writes no such edge; this removes the ones it
+wrote before. Judged edges keep their own basis and are left alone.
+
+Downgrade restores nothing: the removed edges were never facts.
+"""
+from alembic import op
+
+revision = "0126"
+down_revision = "0125"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute(
+        "DELETE FROM code_shape_uses u USING code_shapes s, notes n "
+        "WHERE u.shape_id = s.id AND u.snippet_id = n.id "
+        "AND u.basis = 'hook' "
+        "AND n.project_id IS NOT NULL AND n.project_id <> s.project_id"
+    )
+
+
+def downgrade() -> None:
+    pass

alembic/versions/0127_instance_identity.py

@@ -0,0 +1,39 @@
+"""instance identity — the id lineage a backup carries
+
+Revision ID: 0127
+Revises: 0126
+Create Date: 2026-11-05
+
+One row naming this database's id lineage. Every full backup carries it, a
+restore into a fresh instance adopts it (the restore keeps the original ids),
+and rolling a live instance back requires the backup's to match, so a backup's
+ids never land on unrelated rows. Made here with a random value, so every
+instance has one before its first account exists.
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0127"
+down_revision = "0126"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "instance_identity",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("instance_id", sa.Text(), nullable=False),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.CheckConstraint("id = 1", name="ck_instance_identity_single_row"),
+    )
+    op.execute(
+        "INSERT INTO instance_identity (id, instance_id) VALUES (1, gen_random_uuid()::text)"
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("instance_identity")

ci-requirements.md

@@ -1,4 +1,4 @@
-# CI Requirements — FabledScribe
+# CI Requirements — FabledGrimoire
 
 > Spec lives in [`docs/process.md`](https://git.fabledsword.com/bvandeusen/CI-runner/src/branch/main/docs/process.md)
 > in the CI-Runner repo.
@@ -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)
 
@@ -29,15 +28,16 @@ real Postgres), build (docker buildx).
 Anything CI installs at job time that isn't in the image. Promotion
 candidates if more than one project needs them.
 
-- `jq` + `shellcheck` — apt-installed in the **plugin** job, which lints
-  the four 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. Both are small (jq ~1 MB, shellcheck ~20 MB) and would be
-  promotion candidates the moment another project lints shell.
-  **jq is load-bearing for the smoke test specifically**: every hook
-  starts with `command -v jq || exit 0`, so without it the test passes
-  while exercising nothing.
+- `shellcheck` — apt-installed in the **plugin** job, which lints the
+  Claude Code hook scripts and runs their fail-open smoke test. Grimoire 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.
+
+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.dev.yml

@@ -0,0 +1,35 @@
+# Grimoire built from this checkout, for development:
+#   docker compose -f docker-compose.dev.yml up --build
+
+services:
+  app:
+    build: .
+    ports:
+      - "5000:5000"
+    depends_on:
+      - db
+    restart: unless-stopped
+    volumes:
+      - app_data:/data
+      # Or a bind mount, for direct host access to the app's data:
+      # - ./data:/data
+    environment:
+      DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-grimoire}:${POSTGRES_PASSWORD:-grimoire}@db:5432/${POSTGRES_DB:-grimoire}"
+      # Optional: a SearXNG instance to list as the web-search backend in Integrations.
+      # SEARXNG_URL: "http://searxng:8080"
+
+  db:
+    # Postgres 17 with the vector extension Grimoire needs.
+    image: pgvector/pgvector:pg17
+    stop_grace_period: 120s
+    restart: unless-stopped
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-grimoire}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-grimoire}
+      POSTGRES_DB: ${POSTGRES_DB:-grimoire}
+
+volumes:
+  pgdata:
+  app_data:

docker-compose.prod.yml

@@ -1,59 +1,39 @@
 services:
   app:
-    image: git.fabledsword.com/bvandeusen/fabledscribe:latest
+    image: git.fabledsword.com/bvandeusen/fabledgrimoire:latest
     environment:
-      DATABASE_URL: "postgresql+asyncpg://scribe:${DB_PASSWORD}@db:5432/scribe"
+      DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-grimoire}:${DB_PASSWORD}@db:5432/${POSTGRES_DB:-grimoire}"
+      # A Swarm can start the app on another node, away from the key kept in
+      # a node-local /data volume, so a stack sets its key itself (or mounts
+      # a Docker secret and sets SECRET_KEY_FILE to its path).
       SECRET_KEY: "${SECRET_KEY}"
       LOG_LEVEL: "${LOG_LEVEL:-INFO}"
-      TRUST_PROXY_HEADERS: "true"
-      SECURE_COOKIES: "true"
+      # Proxies in front of the app (Traefik = 1). The client address and
+      # HTTPS are read from that far in from the right of X-Forwarded-*.
+      TRUSTED_PROXY_HOPS: "1"
+    volumes:
+      - app_data:/data
     networks:
-      - scribe_backend
-    healthcheck:
-      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/health')"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 30s
-    deploy:
-      restart_policy:
-        condition: on-failure
-        max_attempts: 5
+      - backend
 
   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 Grimoire needs.
     image: pgvector/pgvector:pg17
     stop_grace_period: 120s
     volumes:
       - pgdata:/var/lib/postgresql/data
     environment:
-      POSTGRES_USER: scribe
+      POSTGRES_USER: ${POSTGRES_USER:-grimoire}
       POSTGRES_PASSWORD: "${DB_PASSWORD}"
-      POSTGRES_DB: scribe
+      POSTGRES_DB: ${POSTGRES_DB:-grimoire}
     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.
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U scribe"]
-      interval: 30s
-      timeout: 10s
-      retries: 10
-      start_period: 180s
-    deploy:
-      restart_policy:
-        condition: on-failure
-        delay: 10s
-        max_attempts: 0
-        window: 120s
+      - backend
 
 volumes:
   pgdata:
+    name: ${PGDATA_VOLUME:-grimoire_pgdata}
+  app_data:
 
 networks:
-  scribe_backend:
+  backend:
     driver: overlay

docker-compose.quickstart.yml

@@ -1,59 +0,0 @@
-# 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
-
-services:
-  app:
-    image: git.fabledsword.com/bvandeusen/fabledscribe:latest
-    ports:
-      - "5000:5000"
-    environment:
-      DATABASE_URL: "postgresql+asyncpg://scribe:scribe@db:5432/scribe"
-      SECRET_KEY: "${SECRET_KEY:-change-me-in-production}"
-      LOG_LEVEL: "${LOG_LEVEL:-INFO}"
-    volumes:
-      - app_data:/data
-    depends_on:
-      db:
-        condition: service_healthy
-    restart: unless-stopped
-    healthcheck:
-      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/health')"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-      start_period: 30s
-
-  db:
-    # pgvector image (PG17) — bundles the `vector` extension (migration 0067).
-    image: pgvector/pgvector:pg17
-    stop_grace_period: 120s
-    volumes:
-      - pgdata:/var/lib/postgresql/data
-    environment:
-      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.
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U scribe"]
-      interval: 30s
-      timeout: 10s
-      retries: 10
-      start_period: 180s
-    restart: unless-stopped
-
-volumes:
-  app_data:
-  pgdata:

docker-compose.yml

@@ -1,47 +1,40 @@
+# Fabled Grimoire: the app and its database.
+#   docker compose up -d
+# Then open http://localhost:5000. The first account registered becomes admin.
+#
+# Keep both volumes. app_data holds the instance's own SECRET_KEY, which seals
+# saved credentials; pgdata holds everything else.
+
 services:
   app:
-    build: .
+    image: git.fabledsword.com/bvandeusen/fabledgrimoire:latest
     ports:
       - "5000:5000"
-    depends_on:
-      db:
-        condition: service_healthy
+    environment:
+      DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-grimoire}:${POSTGRES_PASSWORD:-grimoire}@db:5432/${POSTGRES_DB:-grimoire}"
+      LOG_LEVEL: "${LOG_LEVEL:-INFO}"
+      # Port 5000 is published straight to clients, so no proxy is trusted.
+      # Behind a reverse proxy, set 1 (one per proxy) and BASE_URL:
+      TRUSTED_PROXY_HOPS: "0"
+      # BASE_URL: "https://grimoire.example.com"
     volumes:
       - app_data:/data
-      # To use a bind mount instead (gives direct host access to all app 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:
-      # SEARXNG_URL: "http://searxng:8080"
-    healthcheck:
-      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/health')"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 30s
+    depends_on:
+      - db
+    restart: unless-stopped
 
   db:
-    image: postgres:16-alpine
+    # Postgres 17 with the vector extension Grimoire needs.
+    image: pgvector/pgvector:pg17
     stop_grace_period: 120s
-    restart: unless-stopped
     volumes:
       - pgdata:/var/lib/postgresql/data
     environment:
-      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.
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-scribe}"]
-      interval: 30s
-      timeout: 10s
-      retries: 10
-      start_period: 180s
+      POSTGRES_USER: ${POSTGRES_USER:-grimoire}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-grimoire}
+      POSTGRES_DB: ${POSTGRES_DB:-grimoire}
+    restart: unless-stopped
 
 volumes:
-  pgdata:
   app_data:
+  pgdata:

docs/2026-03-23-fable-mcp-design.md

@@ -1,271 +0,0 @@
-# Fable MCP — Design Spec
-
-**Date:** 2026-03-23
-**Status:** Approved
-**Author:** bvandeusen + Claude
-
----
-
-## Overview
-
-A Python MCP (Model Context Protocol) server that lets Claude directly interface with a running Fabled Assistant instance. The goal is two-fold: Claude's stronger reasoning handles planning, documentation, and analysis while Fable remains the authoritative store for notes, tasks, projects, and milestones; and direct API access enables process improvement by letting Claude observe and operate on real data rather than working from descriptions.
-
-The work is split into two sub-projects:
-
-1. **Fable API Key Feature** — additions to the main `scribe` project to support bearer token authentication
-2. **Fable MCP Server** — a new standalone Python package at `fable-mcp/` in the same repo root
-
-A third sub-project (Forgejo MCP for CI/CD automation) is planned as a follow-on after the Fable MCP is working.
-
----
-
-## Sub-project 1: Fable API Key Feature
-
-### Motivation
-
-All existing Fable routes use session-based authentication (`session["user_id"]`). The MCP server runs as a local process and cannot maintain a browser session, so a stateless bearer token mechanism is required. API keys are user-scoped and carry a read/write permission level.
-
-### Database
-
-New table `api_keys` via migration `0027_add_api_keys.py`:
-- `down_revision = "0026"` (the briefing tables migration)
-- `revision = "0027"`
-
-| Column | Type | Notes |
-|--------|------|-------|
-| `id` | Integer PK | |
-| `user_id` | Integer FK → users | CASCADE delete |
-| `name` | Text | Human-readable label |
-| `key_hash` | Text | SHA-256 of the full key, used for lookup |
-| `key_prefix` | Text | First 8 chars (e.g. `fmcp_ab12`), shown in UI |
-| `scope` | Text | `"read"` or `"write"` |
-| `last_used_at` | Timestamp | Nullable, updated on each authenticated request |
-| `created_at` | Timestamp | |
-| `revoked_at` | Timestamp | Nullable — soft delete |
-
-Full keys are generated as `fmcp_<32 random url-safe chars>`, returned once at creation, never stored. Only the SHA-256 hash is persisted.
-
-### Auth Middleware (`auth.py`)
-
-`_check_auth` is updated to check the `Authorization: Bearer <token>` header before falling back to session auth:
-
-1. If header present: hash the token, look up in `api_keys` where `revoked_at IS NULL`
-2. If found: update `last_used_at`, set `g.user` and `g.api_key`
-3. Scope enforcement: if `g.api_key.scope == "read"` and `request.method` is not `GET`, return 403
-4. If header absent: existing session logic runs unchanged
-
-Session auth is untouched — no regression risk for the web UI.
-
-**Admin routes and API keys:** Routes decorated with `admin_required` check `user.role == "admin"` after auth resolves. API keys authenticate as the key owner — so a write-scoped key for a non-admin user will fail admin-protected routes with 403 (role check, not scope check). This is intentional: API keys cannot elevate privilege beyond the user's role.
-
-### Routes (`/api/api-keys`)
-
-New blueprint `api_keys_bp`, registered in `app.py`:
-
-- `GET /api/api-keys` — list caller's keys (prefix, name, scope, last_used_at, created_at — never the hash or full key)
-- `POST /api/api-keys` — create key; body: `{name, scope}`. Returns full key in response **once only**
-- `DELETE /api/api-keys/:id` — revoke by setting `revoked_at = now()`
-
-### Settings UI
-
-New "API Keys" tab in `SettingsView.vue` (added to `VALID_TABS`):
-
-- Create form: name input + read/write radio/toggle + "Generate Key" button
-- After creation: one-time modal displaying the full key with a copy button and a warning that it will not be shown again
-- Keys table: columns for name, scope badge, prefix, last used, revoke button
-- Revoke shows inline confirmation before calling DELETE
-
-### New Search Endpoint
-
-`GET /api/search?q=<query>&content_type=note|task|all&limit=N`
-
-Calls the existing `semantic_search_notes()` service (already in `services/embeddings.py`). The `content_type` parameter maps to the service's `is_task` argument:
-- `content_type=note` → `is_task=False`
-- `content_type=task` → `is_task=True`
-- `content_type=all` (default) → `is_task=None`
-
-Returns:
-
-```json
-{
-  "results": [
-    {"id": 1, "title": "...", "body": "...", "is_task": false, "similarity": 0.87, "tags": [...]}
-  ],
-  "total": 5
-}
-```
-
-This endpoint is needed by the MCP's `search.py` tool module. It reuses existing infrastructure with no new ML work.
-
-### Conversation Type: `"mcp"`
-
-A new conversation type `"mcp"` is added alongside `"chat"` and `"briefing"`. This requires changes in two places in the main app:
-
-**`services/chat.py`** — `create_conversation(user_id, title, model)` gains an optional `conversation_type: str = "chat"` parameter, passed through to the `Conversation` constructor.
-
-**`routes/chat.py`** — `POST /api/chat/conversations` accepts an optional `conversation_type` body field (defaults to `"chat"`), passed to `create_conversation`. `GET /api/chat/conversations` continues to default-filter to `conversation_type="chat"` (excluding `"mcp"` and `"briefing"`); pass `?type=mcp` to retrieve MCP conversations.
-
-**Retention:** `cleanup_old_conversations` in `routes/chat.py` currently deletes conversations regardless of type. It must be updated to exclude `conversation_type="mcp"` from the sweep, so MCP audit-trail conversations are not automatically pruned.
-
-MCP conversations:
-- Are created with a caller-supplied name (e.g., `"MCP Session 2026-03-23"`) or auto-named
-- Are excluded from the default chat list
-- Are accessible via `GET /api/chat/conversations?type=mcp` for inspection
-- Appear in the Fable UI if explicitly navigated to, providing an audit trail of MCP-driven interactions
-
-### Chat SSE Wire Format
-
-The MCP's `chat.py` tool must consume the existing SSE stream. The relevant endpoints and event schema:
-
-- **Create conversation:** `POST /api/chat/conversations` → `{id, title, ...}`
-- **Post message + start generation:** `POST /api/chat/conversations/:id/messages` → `{message_id, ...}`; then connect to:
-- **Stream:** `GET /api/chat/conversations/:id/stream` (SSE)
-
-SSE event format (each line is `data: <json>`):
-- `{"type": "token", "content": "..."}` — streaming token
-- `{"type": "tool_call", "name": "...", "result": {...}}` — tool fired
-- `{"type": "done", "content": "...", "tools_used": [...]}` — generation complete; this is the termination event
-
-The MCP tool reads tokens until it receives `type: "done"`, then returns `response` (full content) and `tools_used` (list of tool names).
-
----
-
-## Sub-project 2: Fable MCP Server
-
-### Location
-
-`fable-mcp/` at the repository root, alongside `src/`, `frontend/`, `alembic/`. It is **not** part of the main Docker build and has no import relationship with `scribe`. It will be extracted to its own Forgejo repo once stable.
-
-### Package Structure
-
-```
-fable-mcp/
-  pyproject.toml            # entry point: fable-mcp = "fable_mcp.server:main"
-  README.md
-  .env.example              # FABLE_URL=http://localhost:8080, FABLE_API_KEY=fmcp_...
-  fable_mcp/
-    __init__.py
-    server.py               # FastMCP instance, imports + registers all tool modules
-    client.py               # FableClient: async httpx wrapper, env var config, FableAPIError
-    tools/
-      __init__.py
-      notes.py              # list_notes, get_note, create_note, update_note, delete_note
-      tasks.py              # list_tasks, get_task, create_task, update_task, delete_task,
-                            #   patch_task_status, add_task_log
-      projects.py           # list_projects, get_project, create_project, update_project,
-                            #   delete_project, get_project_summary
-      milestones.py         # list_milestones, get_milestone, create_milestone,
-                            #   update_milestone, delete_milestone
-      search.py             # semantic_search — calls GET /api/search
-      chat.py               # send_message — creates/continues conversation, returns response
-```
-
-### Dependencies
-
-```toml
-[project]
-dependencies = [
-  "mcp[cli]>=1.0",
-  "httpx>=0.27",
-  "python-dotenv>=1.0",
-]
-```
-
-### `client.py`
-
-`FableClient` is an async context manager wrapping `httpx.AsyncClient`. It reads `FABLE_URL` and `FABLE_API_KEY` from environment variables (with `python-dotenv` fallback to `.env`). All methods are `async def` and return parsed dicts. A `FableAPIError(status_code, message)` exception is raised for any non-2xx response.
-
-A module-level singleton `_client: FableClient` is initialized at server startup and shared across all tool modules.
-
-### `server.py`
-
-Uses `mcp[cli]`'s `FastMCP` class. Imports all tool modules, which register their tools via decorators against the shared `FastMCP` instance. Entry point `main()` calls `mcp.run()` (stdio transport).
-
-### Tool Modules
-
-Each module imports `_client` from `client.py` and defines tools as `async def` functions decorated with `@mcp.tool()`. Tool docstrings serve as the MCP tool descriptions visible to Claude.
-
-**`notes.py`** tools:
-- `list_notes(query, tags, project_id, limit, offset)`
-- `get_note(note_id)`
-- `create_note(title, body, tags, project_id)`
-- `update_note(note_id, title, body, tags, project_id)`
-- `delete_note(note_id)`
-
-**`tasks.py`** tools:
-- `list_tasks(query, project_id, milestone_id, status, priority, limit, offset)`
-- `get_task(task_id)`
-- `create_task(title, body, project_id, milestone_id, priority, status)`
-- `update_task(task_id, title, body, project_id, milestone_id, priority, status)`
-- `delete_task(task_id)`
-- `patch_task_status(task_id, status)`
-- `add_task_log(task_id, content)`
-
-**`projects.py`** tools:
-- `list_projects()`
-- `get_project(project_id)` — includes milestone summary
-- `create_project(title, description, goal, color)`
-- `update_project(project_id, title, description, goal, status, color)`
-- `delete_project(project_id)`
-
-**`milestones.py`** tools:
-- `list_milestones(project_id, status)`
-- `get_milestone(project_id, milestone_id)`
-- `create_milestone(project_id, title, description, order_index)`
-- `update_milestone(project_id, milestone_id, title, description, status, order_index)`
-- `delete_milestone(project_id, milestone_id)`
-
-**`search.py`** tools:
-- `semantic_search(query, content_type, limit)` — `content_type` is `"note"`, `"task"`, or `"all"` (avoids shadowing Python's `type` builtin). Calls `GET /api/search`, returns ranked results with similarity scores.
-
-**`chat.py`** tools:
-- `send_message(message, conversation_name)`:
-  - Looks up or creates a Fable conversation with the given name and `conversation_type="mcp"`
-  - Posts the message via `POST /api/chat/conversations/:id/messages`
-  - Consumes SSE stream from `GET /api/chat/conversations/:id/stream` until `type: "done"`
-  - Returns: `{response: str, tools_used: [str], conversation_id: int}`
-  - MCP conversations are excluded from the normal chat UI list
-
-### Error Handling
-
-`FableAPIError` is caught at each tool boundary and returned as a descriptive string rather than propagating as an exception. This ensures Claude receives a readable error message (e.g., `"Fable API error 403: Read-only key cannot perform write operations."`) rather than a stack trace. Network errors (`httpx.RequestError`) are similarly caught and surfaced as strings.
-
-Scope enforcement lives entirely in Fable's auth middleware — the MCP does not duplicate it.
-
-### Claude Code Registration
-
-After `pip install -e fable-mcp/` (or `uv tool install ./fable-mcp`), add to `~/.claude/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "fable": {
-      "command": "fable-mcp",
-      "env": {
-        "FABLE_URL": "http://localhost:8080",
-        "FABLE_API_KEY": "fmcp_your_key_here"
-      }
-    }
-  }
-}
-```
-
-Claude Code spawns the process over stdio automatically. No Docker, no daemon.
-
----
-
-## Build & Repo Plan
-
-1. Implement and test within `scribe/fable-mcp/`
-2. Once stable, extract to a new Forgejo repo (`bvandeusen/fable-mcp`)
-3. Forgejo MCP (Gitea MCP) added as a second MCP server to automate build/push/config workflows — separate spec when ready
-
----
-
-## Out of Scope (v1)
-
-- MCP resources (browsable URI tree) — tools cover all use cases in Claude Code
-- Forgejo MCP — follow-on spec
-- Rate limiting on API key endpoints
-- Key expiry / TTL
-- Per-resource scope (e.g., key restricted to one project)

docs/2026-03-29-voice-s2s-design.md

@@ -1,200 +0,0 @@
-# Speech-to-Speech (S2S) Design Spec
-
-**Branch:** `feature/voice-s2s`
-**Date:** 2026-03-29
-**Status:** Approved for implementation
-
----
-
-## Decisions
-
-- **STT:** faster-whisper (in-process Python, model size configurable via `STT_MODEL` env var)
-- **TTS:** Kokoro TTS (in-process Python, voice/speed/style configurable per-user)
-- **Input mode:** Push-to-talk (Phase 1); VAD deferred
-- **No browser STT/TTS fallbacks** — self-hosted only, data stays on-server
-- **No Android app** — web only for this implementation
-
----
-
-## New Env Vars (`config.py`)
-
-| Var | Default | Description |
-|---|---|---|
-| `VOICE_ENABLED` | `false` | Feature flag — opt-in |
-| `STT_BACKEND` | `faster-whisper` | Only supported value currently |
-| `STT_MODEL` | `base.en` | `tiny.en` / `base.en` / `small.en` / `medium.en` |
-| `TTS_BACKEND` | `kokoro` | Only supported value currently |
-
----
-
-## Per-User Settings (stored in `settings` table)
-
-| Key | Default | Description |
-|---|---|---|
-| `voice_tts_voice` | `af_heart` | Kokoro voice ID |
-| `voice_tts_speed` | `1.0` | Speech rate, 0.7–1.3 |
-| `voice_speech_style` | `conversational` | `conversational` / `concise` / `detailed` |
-
----
-
-## New Backend Files
-
-### `src/scribe/services/stt.py`
-Lazy singleton `WhisperModel` loader. Public API:
-- `load_stt_model()` — called at startup via `asyncio.create_task`
-- `transcribe(audio_bytes, mime_type) -> str` — runs in `run_in_executor`; writes bytes to `NamedTemporaryFile`, returns concatenated segment text
-- `stt_available() -> bool`
-
-### `src/scribe/services/tts.py`
-Lazy singleton `KPipeline` loader. Public API:
-- `load_tts_model()` — called at startup
-- `synthesise(text, voice, speed) -> bytes` — runs in `run_in_executor`; returns WAV bytes (24kHz, 16-bit mono)
-- `list_voices() -> list[dict]` — returns static list of known Kokoro voice IDs + labels
-- `tts_available() -> bool`
-
-### `src/scribe/routes/voice.py`
-Blueprint at `/api/voice`, all routes `@login_required`.
-
-| Endpoint | Method | Description |
-|---|---|---|
-| `/api/voice/status` | GET | STT/TTS availability; `enabled` false if `VOICE_ENABLED=false` |
-| `/api/voice/voices` | GET | List available Kokoro voices |
-| `/api/voice/transcribe` | POST | multipart `audio` field → `{"transcript": "...", "duration_ms": 123}` |
-| `/api/voice/synthesise` | POST | `{"text", "voice", "speed"}` → WAV bytes |
-
----
-
-## Modified Backend Files
-
-### `src/scribe/app.py`
-- Register `voice_bp` blueprint
-- In `startup()`: `asyncio.create_task(load_stt_model())` + `asyncio.create_task(load_tts_model())` when `VOICE_ENABLED`
-
-### `src/scribe/config.py`
-- Add 4 new env var attributes
-- Add validation in `validate()`
-
-### `src/scribe/services/llm.py`
-- Add `voice_mode: bool = False` and `voice_speech_style: str = "conversational"` to `build_context()`
-- When `voice_mode=True`, prepend: *"Respond naturally as if speaking aloud. No markdown, bullet points, headers, or code blocks. Complete sentences only."*
-- Append style modifier based on `voice_speech_style`
-
-### `src/scribe/services/generation_task.py`
-- Add `voice_mode: bool = False` to `run_generation()`
-- Read `voice_speech_style` from settings when voice_mode; pass both to `build_context()`
-
-### `src/scribe/routes/chat.py`
-- Allow `"voice"` in `conversation_type` whitelist
-
-### `src/scribe/services/chat.py`
-- Exclude `conversation_type == "voice"` from auto-cleanup retention
-
----
-
-## New Frontend Files
-
-### `frontend/src/composables/useVoiceRecorder.ts`
-Wraps `MediaRecorder`. Exports: `recording`, `error`, `isSupported`, `startRecording()`, `stopRecording() -> Promise<Blob>`.
-
-### `frontend/src/composables/useVoiceAudio.ts`
-Wraps `AudioContext`. Exports: `playing`, `isSupported`, `play(blob)`, `stop()`.
-
-### `frontend/src/components/VoiceOverlay.vue`
-Floating PTT button (fixed bottom-right). Creates/reuses a `"voice"` conversation. Full flow: record → transcribe → send → stream → synthesise → play. Space bar hotkey (from `App.vue`). Mounted globally in `App.vue`.
-
----
-
-## Modified Frontend Files
-
-### `frontend/src/api/client.ts`
-Add: `transcribeAudio(blob)`, `synthesiseSpeech(text, voice?, speed?)`, `getVoiceStatus()`, `getVoiceList()`
-
-### `frontend/src/views/BriefingView.vue`
-- "Listen" button: reads latest assistant message aloud via TTS
-- Mic button in input bar: PTT → transcribe → auto-fill input → send
-- Auto-TTS on assistant response when in listen mode
-
-### `frontend/src/views/SettingsView.vue`
-- New "Voice" tab: voice dropdown, speed slider, speech style radio
-- Loads from `/api/settings`, saves via `PUT /api/settings`
-
-### `frontend/src/App.vue`
-- Mount `<VoiceOverlay />`
-- Space bar → `"voice:ptt-toggle"` custom event
-
----
-
-## Audio Format
-
-| Direction | Format | Rationale |
-|---|---|---|
-| Browser → Server | WebM/Opus | Native `MediaRecorder` output; no re-encoding |
-| Server → Browser | WAV (24kHz, 16-bit mono) | Kokoro native; no re-encoding; `decodeAudioData` compatible |
-
----
-
-## Dependencies to Add (`pyproject.toml`)
-
-```toml
-[project.optional-dependencies]
-voice = [
-    "faster-whisper>=1.0",
-    "kokoro>=0.9",
-    "soundfile>=0.12",
-]
-```
-
-Install unconditionally in Docker (activated by `VOICE_ENABLED` at runtime):
-```dockerfile
-RUN pip install faster-whisper kokoro soundfile
-```
-
----
-
-## Database Migration
-
-No schema changes required. `conversation_type` is unconstrained TEXT. Voice settings use existing key-value `settings` table. Optional no-op migration `0034_voice_conversation_type.py` for audit trail.
-
----
-
-## Implementation Phases
-
-### Phase 1 — Backend services + routes
-1. Add env vars to `config.py`
-2. Create `services/stt.py` (faster-whisper)
-3. Create `services/tts.py` (Kokoro)
-4. Create `routes/voice.py` (4 endpoints)
-5. Wire model loading into `app.py` startup
-6. Add `voice_mode` to `build_context()` + `run_generation()`
-7. Allow `"voice"` conversation type in chat route + cleanup exclusion
-
-### Phase 2 — BriefingView listen + voice follow-up
-1. Create `useVoiceRecorder.ts`
-2. Create `useVoiceAudio.ts`
-3. Add voice API functions to `client.ts`
-4. Add "Listen" button + mic button to `BriefingView.vue`
-
-### Phase 3 — VoiceOverlay for general voice chat
-1. Create `VoiceOverlay.vue`
-2. Mount in `App.vue` + Space bar hotkey
-
-### Phase 4 — Settings UI
-1. Add "Voice" tab to `SettingsView.vue`
-
----
-
-## Kokoro Voice Reference
-
-| ID | Character |
-|---|---|
-| `af_heart` | American female, warm (recommended default) |
-| `af_bella` | American female, expressive |
-| `af_nicole` | American female, breathy/intimate |
-| `af_sarah` | American female, clear |
-| `af_sky` | American female, bright |
-| `am_adam` | American male, neutral |
-| `am_michael` | American male, deeper |
-| `bf_emma` | British female |
-| `bf_isabella` | British female, formal |
-| `bm_george` | British male |
-| `bm_lewis` | British male, casual |

docs/2026-04-10-agentic-briefing-design.md

@@ -1,216 +0,0 @@
-# Agentic Briefing — Design Spec
-
-**Date:** 2026-04-10
-**Status:** Proposed
-**Author:** bvandeusen + Claude
-
----
-
-## Problem
-
-The current briefing pipeline hallucinates calendar events, tasks, and news items that do not exist in the user's actual data. Observed examples from production:
-
-- A morning briefing asserting "your dentist appointment is still in progress" when no such event existed
-- An 8am check-in mentioning "a quick meeting at 10:30 AM" with no backing calendar entry
-- A midday check-in inventing "a team huddle at 2:30 PM" and "the Q2 budget draft due by Friday"
-- The model calling `search_images` in response to a clarifying question about a fabricated meeting
-
-These are not bugs in data retrieval — the data gathering code (`_gather_internal`, `_gather_external`) returns correct values. They are a structural consequence of how the briefing context is assembled.
-
-## Root cause — the "no receipt" problem
-
-The current `run_compilation` pipeline does this:
-
-1. Python code gathers data (tasks, events, weather, news) from the database
-2. Python formats the data into a structured text blob as the user-role message: `TODAY'S EVENTS: ...`, `DUE TODAY: ...`, etc.
-3. The LLM is called **once** with `[system_prompt, user_prompt]` and produces prose
-4. Only the prose reply is written to the conversation. **The underlying data is never persisted in the conversation history.**
-
-When the user later chats in the briefing conversation, the chat endpoint loads the full conversation history — which contains the model's *prose* from earlier but not the data that prose was derived from. The model's own prior output becomes the only source of "truth" available for follow-up questions. If that prose asserted a fact (real or hallucinated), the model has no way to distinguish it from ground truth when generating the next reply, and it will double down.
-
-Compounding factors:
-
-- **Empty sections are silently omitted.** If `calendar_events` is empty, the user prompt contains no `TODAY'S EVENTS:` line at all. The model has no explicit "zero events" signal — combined with an imperative system prompt ("note calendar events and tasks"), it interprets the silence as "I should mention some" and fabricates.
-- **Scheduled slot injections append synthetic turns.** `run_slot_injection` writes a fake `[Midday briefing update]` user message and the assistant reply into the persistent conversation. By evening, the chat history contains three separate briefings, each potentially with errors, all treated as equal-weight context on follow-up.
-- **The `search_images` tool is available during briefing chat**, with a negative-instruction description ("Not for factual questions"). Small and mid-sized models frequently ignore negative guidance in tool descriptions and call the tool anyway.
-
-## Solution — agentic briefing (the receipt model)
-
-Replace the one-shot synthesis with a tool-call loop. The briefing is no longer "a text blob synthesized from pre-gathered data." It is **a scheduled agent run**: the LLM is given a system prompt, a curated set of read-only data tools, and a trigger ("generate the morning briefing"). The model must call tools to see what exists. Every tool call and tool result becomes part of the conversation history, where it lives as a permanent, structured receipt.
-
-### Why this fixes the hallucination
-
-When the model calls `list_events(today) → []`, that empty array is now a persistent message in the conversation. On a follow-up question like "what meeting?", the chat endpoint loads the conversation and the model sees its own tool result from the morning showing no events. Answering "you had a meeting at 10:30" would require the model to directly contradict a tool result sitting two messages back — something LLMs are much more reliable at avoiding than contradicting their own prior prose.
-
-In short: **the model cannot fabricate what has a visible receipt proving it does not exist.**
-
-### What the model sees — before vs after
-
-**Before** — the model sees one structured blob and produces prose. The blob is discarded.
-
-```
-[system] You are a personal assistant... weave together what matters...
-[user]   Date: 2026-04-10
-         WEATHER: Home — partly cloudy, 8–16°C
-         DUE TODAY: Fix briefing hallucinations
-         OVERDUE (2 tasks): ...
-[assistant] Morning! Looks like a quiet day with two overdue items...
-```
-
-**After** — the model is given tools and iterates to ground truth.
-
-```
-[system] You are the user's personal assistant giving their morning briefing.
-         Use tools to see what's relevant. Only mention things you learned from
-         tool calls. If a tool returns nothing, say so honestly.
-[user]   Generate the morning briefing.
-[assistant] tool_call: list_tasks(filter="due_today")
-[tool]   [{"id": 81, "title": "Fix briefing hallucinations", ...}]
-[assistant] tool_call: list_tasks(filter="overdue")
-[tool]   [{"id": 42, ...}, {"id": 43, ...}]
-[assistant] tool_call: list_events(today)
-[tool]   []
-[assistant] tool_call: get_weather(location="home")
-[tool]   {"description": "partly cloudy", "temp_min": 8, "temp_max": 16}
-[assistant] tool_call: get_rss_items(max=8)
-[tool]   [...]
-[assistant] Morning! Partly cloudy today, 8 to 16 — nothing on the calendar
-         so it's a clean run at the desk. Two things to keep in mind...
-```
-
-The conversation now contains verifiable receipts: `list_events(today)` returned `[]`, and that result sits in context forever (until pruned). Follow-up questions operate against those receipts.
-
-## Architecture
-
-### Existing infrastructure (reused, not rebuilt)
-
-The codebase already has the agentic primitives — they're used for regular chat:
-
-- **`llm.py::stream_chat_with_tools`** — the streaming tool-use loop that talks to Ollama with a `tools` parameter and yields tool-call chunks
-- **`generation_task.py::_stream_with_retry`** — wraps `stream_chat_with_tools` with retry-on-500 behavior for cold-model races
-- **`tools.py`** — defines 40+ tool schemas and an execution dispatcher
-
-The briefing bypasses all of this and calls a one-shot `_llm_synthesise` helper. The refactor is mainly "route briefings through the same pipeline regular chat already uses."
-
-### New modules
-
-**`briefing_tools.py`** — a small wrapper exposing a curated read-only subset of `tools.py` for briefing runs. This is an **explicit allowlist**, not a blocklist, so newly-added tools must be opted in:
-
-| Tool | Purpose |
-|---|---|
-| `list_tasks` (with filter args) | See what's actionable today, overdue, high priority |
-| `list_events` (today / upcoming) | Know what's on the calendar |
-| `get_weather` | Current/forecast weather |
-| `get_rss_items` | Pull news themes filtered by user preferences |
-| `list_projects` | Understand project context |
-| `search_projects` | Surface active project summaries |
-| `list_notes` (recent) | Capture follow-ups from yesterday |
-
-**Explicitly omitted** from the briefing tool set:
-
-- `search_images`, `search_web`, `research_topic`, `read_article` — external search is not a briefing concern, and `search_images` is the source of the "Peter Kyle Science Secretary" image-search bug
-- All `create_*`, `update_*`, `delete_*` — briefings are read-only; a scheduled background job must not decide to mutate the user's data on its own
-- `set_rag_scope`, `calculate` — not relevant to briefing content
-
-### New briefing function
-
-**`briefing_pipeline.py::run_agentic_briefing(user_id, slot, model, conversation_id)`** replaces `run_compilation`'s body (and eventually `run_slot_injection`). Internally:
-
-1. Build a slot-specific system prompt (see below)
-2. Load the curated briefing tools from `briefing_tools.py`
-3. Seed messages with `[system, user]` where the user message is a simple trigger like `"Generate the morning briefing."`
-4. Enter a tool-call loop (max 8 iterations):
-   - Call `stream_chat_with_tools`
-   - If the model returns `tool_calls`, execute them via the existing dispatcher, append tool results, continue
-   - If the model returns a final assistant message with no pending tool calls, break
-5. Return `(final_prose, full_message_list, metadata)`
-
-The full message list is important: it's written to the conversation along with the final prose, so the tool-call receipts become part of the persistent record.
-
-### Slot-specific system prompts
-
-Compilation (full morning briefing):
-
-```
-You are the user's personal assistant giving their full morning briefing.
-Use the tools available to see what's actually relevant today — tasks due,
-overdue items, events on the calendar, weather, news themes, project state
-— and weave it into a warm, natural-sounding summary.
-
-Rules:
-- Call tools to see the data. Never assert facts you didn't learn from a tool.
-- If a tool returns nothing (no events today, no overdue tasks), say so
-  honestly. Don't fabricate items to fill space.
-- Write flowing prose. No markdown, no headers, no bullet points.
-- Aim for 6–10 sentences. Skip topics that have nothing interesting.
-- Close on one or two concrete, actionable suggestions.
-
-User profile (for tone and preferences):
-{profile_body}
-```
-
-Check-ins (midday, afternoon):
-
-```
-You are the user's personal assistant giving a brief {slot} check-in.
-Use tools to see what's changed since this morning. Focus on progress
-and what's still unaddressed.
-
-Rules:
-- Call tools to see current state. Never assert facts without tool results.
-- If nothing meaningful has changed, say so briefly — don't invent progress.
-- 3–5 sentences, natural prose, no markdown.
-```
-
-### Conversation hygiene — removing the fake user messages
-
-The current scheduler appends two fake messages on every slot injection:
-
-```python
-await post_message(conv.id, "user", f"[{slot.title()} briefing update]")
-await post_message(conv.id, "assistant", text)
-```
-
-Under the agentic model, we drop the fake `"user"` message entirely. Slot updates become plain assistant messages tagged with `metadata.briefing_slot = "midday"`. The chat endpoint's message loader is updated to filter these when building the LLM context on follow-ups, so a user chatting in the briefing conversation doesn't see three earlier briefings smashed into their history. The UI continues to show them as visible timeline entries.
-
-(This is the Option A filter from the earlier discussion — a small, surgical change compared to migrating briefings to a separate sidecar table. Sidecar storage remains a possible future step.)
-
-### Ollama setup compatibility
-
-The existing Ollama deployment uses non-parallel mode across two GPUs, with a concern about context duplication between cards. This is the correct setup for agentic briefings:
-
-- Each tool-call iteration shares the same KV cache on the same GPU, so appending tool results is cheap
-- There is no race where a second iteration could land on a different card with a different cache state
-- The trade-off is serialization: a briefing in progress will block a concurrent user chat request until it finishes, but scheduled briefings are rare enough (4× per day) that this is acceptable
-
-If GPU contention becomes a problem later, the right lever is pinning specific models to specific GPUs (e.g., background tasks on GPU 1, interactive models on GPU 0) — not enabling parallelism.
-
-## Cost & trade-offs
-
-- **Latency:** a briefing now makes 5–7 inference calls (one per tool-call decision plus the final prose) instead of 1. On a local Ollama with a 7B model, expect 15–40s per briefing vs the current 5–10s. Acceptable for a background job; if it becomes painful at the user-facing check-in slots, investigate letting the model batch independent tool calls in a single turn (Ollama supports this).
-- **Model requirements:** the default model must be reliable at tool calling. `qwen2.5:7b`, `llama3.1:8b`, `mistral-small-3:24b`, and similar handle it well. Models in the ≤3B class typically fail — they either emit no tool calls and return empty prose, or hallucinate invalid tool arguments. If a user's `default_model` is too small, agentic mode should fall back to legacy mode with a log warning.
-- **Context growth:** tool results bloat the conversation. At 8 tool calls per compilation × 4 slots per day, a daily briefing conversation can reach 20-30 KB of JSON-heavy history. Fine for a day; aged briefings should be archived/rolled up after 7 days.
-- **Tool subset drift:** someone adds a new mutating tool to `tools.py` and forgets to update the briefing allowlist. Mitigated by the allowlist model — the default for new tools is "not exposed to briefings."
-- **Infinite loop safety:** a buggy model could tool-call forever. Hard cap at 8 iterations, log a warning if hit, return whatever prose was last produced (or a fallback message).
-
-## Migration path
-
-Ship incrementally, each step independently reversible:
-
-**PR 1 — Agentic compilation behind a feature flag.** Add `briefing_tools.py`, add `run_agentic_briefing`, add a per-user setting `briefing_mode: "legacy" | "agentic"` (default legacy). Route only the 4am compilation through the new path when the flag is set. Keep slot-injection on the legacy path. Enable the flag on the author's account first, validate output quality over several days, then flip the default for all users. No DB migration required — the setting lives in the existing `settings` table.
-
-**PR 2 — Agentic slot injections + conversation hygiene.** Migrate midday/afternoon check-ins to the same pipeline. Remove the fake `[Midday briefing update]` user-role message; slot updates become plain assistant messages tagged with `metadata.briefing_slot`. Add a chat-message-loader filter that excludes slot-tagged messages from the LLM context on follow-ups (they remain visible in the UI).
-
-**PR 3 — UI polish.** Collapsed tool-call status row in the briefing card ("✓ checked calendar · ✓ looked at tasks · ✓ pulled weather"), expanding to show tool results on click. Tool-result cards (weather, news, task list) rendered inline where useful.
-
-**PR 4 (optional) — Sidecar storage for briefing snapshots.** If the chat-filter approach in PR 2 feels too hacky, migrate briefings out of the conversations table and into a dedicated `briefing_snapshots` table. Frontend renders them as pinned timeline cards separate from chat. Larger refactor; defer until PR 1–3 prove the approach works.
-
-## Secondary win — tightening the main chat system prompt
-
-The regular chat is already agentic (it uses `stream_chat_with_tools`), but its system prompt does not explicitly require the model to ground factual claims in tool results. The prompt discipline introduced for briefings — *"Never assert facts you didn't learn from a tool. If a tool returns nothing, say so honestly."* — is worth applying to the main chat system prompt in a follow-up PR. The mechanism already works; only the framing needs tightening.
-
-## Out of scope
-
-- The Android Flutter client's failure to render `search_images` tool-result cards. This is a separate rendering gap in the mobile app and does not affect the server-side fix. Tracked separately.
-- Re-evaluating the Ollama parallelism setting. The current non-parallel config is correct for this work.
-- Replacing the background model for title/summary/observation extraction. That model's role is unrelated to briefings.

docs/api-keys-and-mcp.md

@@ -1,8 +1,8 @@
-# API Keys and Scribe MCP
+# API Keys and Grimoire MCP
 
 ## API Keys
 
-API keys let external tools access your Fable data without a browser session. Each key is scoped to a single user — it can only access data that user owns or has been shared with them.
+API keys let external tools access your Grimoire data without a browser session. Each key is scoped to a single user — it can only access data that user owns or has been shared with them.
 
 ### Scopes
 
@@ -15,40 +15,51 @@ Admin-level operations (log access, user management) require a `write`-scoped ke
 
 ### Creating a Key
 
-1. Go to **Settings → API Keys**
+1. Go to **Settings → MCP Access**
 2. Enter a name (e.g. "Claude MCP", "Home Server")
 3. Choose scope
 4. Click **Generate Key**
 5. Copy the key immediately — it is shown only once (the token is `fmcp_`-prefixed)
 
 Paste the key into the `Authorization: Bearer <key>` header of your MCP client
-config (see **Scribe MCP Server** below).
+config (see **Grimoire MCP Server** below).
 
 ### Revoking a Key
 
-Click **Revoke** next to the key in the API Keys table and confirm. Revoked keys are deleted immediately.
+Click **Revoke** next to the key in the keys table and confirm. Revoked keys are deleted immediately.
 
 ---
 
-## Scribe MCP Server
+## Grimoire MCP Server
 
-Scribe exposes itself as a set of MCP tools that Claude (and other MCP clients)
+Grimoire exposes itself as a set of MCP tools that Claude (and other MCP clients)
 can use to read and write your notes, tasks, projects, rulebooks, and more. The
 server is **built into the app** — it is mounted as a streamable-HTTP endpoint
-at **`/mcp`** on the running Scribe instance (`src/scribe/mcp/server.py`). There
+at **`/mcp`** on the running Grimoire instance (`src/grimoire/mcp/server.py`). There
 is nothing to install: no wheel, no separate package, no CLI. You connect a
 client straight to the URL with a Bearer token.
 
 ### Authentication
 
-Authenticate with an API key generated from **Settings → API Keys** (see above),
+Authenticate with an API key generated from **Settings → MCP Access** (see above),
 sent as `Authorization: Bearer fmcp_<key>`. A `read`-scoped key may call only the
 read tools (`get_*`, `list_*`, `search`, `enter_project`, `retrieval_telemetry`);
 any write/delete tool is rejected with `403`. The allow-list is explicit rather
 than derived from the name — see `_READ_ONLY_TOOLS`, which is why the two reads
 without a read-shaped name are spelled out here. A `write`-scoped key may call everything.
 
-### Claude Code (Project-scoped)
+### Claude Code: the plugin (recommended)
+
+The plugin connects the MCP server and adds the hooks and skills that put Grimoire's records in front of Claude as it works. Install it from this repo:
+
+```
+/plugin marketplace add https://git.fabledsword.com/bvandeusen/FabledGrimoire.git
+/plugin install grimoire@grimoire-plugin
+```
+
+It asks for your Grimoire base URL, an API key (kept in your OS keychain) and, optionally, a project id. Settings → MCP Access shows the exact command for your instance. [`plugin/README.md`](../plugin/README.md) describes each hook.
+
+### Claude Code without the plugin
 
 Add a `.mcp.json` at the project root. The server `type` is `http` and the URL is
 your instance's `/mcp` endpoint:
@@ -56,9 +67,9 @@ your instance's `/mcp` endpoint:
 ```json
 {
   "mcpServers": {
-    "scribe": {
+    "grimoire": {
       "type": "http",
-      "url": "https://your-scribe-instance.example.com/mcp",
+      "url": "https://your-grimoire-instance.example.com/mcp",
       "headers": {
         "Authorization": "Bearer fmcp_your-api-key"
       }
@@ -78,23 +89,26 @@ specific project at a dev instance or an admin key.
 
 ### Available Tools
 
-The tool surface is large (~70 tools) and evolves with the app, so the live
-registration in **`src/scribe/mcp/tools/`** is the source of truth rather than a
-table here. The tools are grouped by family:
+There are well over a hundred tools and they change with the app, so the
+registration in **`src/grimoire/mcp/tools/`** is the reference. By family:
 
 | Family | Examples | Purpose |
 |--------|----------|---------|
-| Notes | `create_note`, `get_note`, `update_note`, `delete_note`, `list_notes` | Free-form knowledge |
-| Tasks | `create_task`, `update_task`, `add_task_log`, `start_planning` | Actionable work + plans |
-| Projects / Milestones | `enter_project`, `get_project`, `create_milestone`, … | Containers and outcomes |
-| Search / Recall | `search`, `get_recent`, `list_tags`, `retrieval_telemetry` | Semantic + structured recall, and the readout its thresholds are tuned from |
-| Systems | `create_system`, `list_systems`, `list_system_records` | Reusable per-project subsystems/areas |
-| Rulebooks | `list_rules`, `create_rule`, `create_project_rule`, `subscribe_project_to_rulebook`, … | Engineering/workflow rules |
-| Processes | `list_processes`, `get_process`, `create_process` | Saved prompts/workflows |
+| Notes | `create_note`, `get_note`, `update_note`, `create_records` | Knowledge, and several records that cite each other in one call |
+| Tasks | `create_task`, `update_task`, `add_task_log` | Work, issues and spikes, and their logs |
+| Projects / Milestones | `enter_project`, `start_planning`, `get_milestone` | Projects and their plans |
+| Search / Recall | `search`, `what_might_apply`, `get_recent` | Recall by meaning, and the rules that may apply to an act |
+| Systems | `create_system`, `list_system_records`, `map_system_to_canonical` | A project's areas |
+| Rules | `create_rule`, `create_project_rule`, `relate_rules`, `rule_history`, `list_moments` | Rules, preferences, their relations and moments |
+| Lessons | `create_lesson`, `judge_lesson_link` | Lessons and the rules they instance |
+| Snippets / Shapes | `create_snippet`, `verify_snippet`, `classify_shapes`, `list_shapes` | Prior art and the shape ledger |
+| Design systems | `resolve_design_system`, `get_design_system_stylesheet` | Tokens and guidance for UI work |
+| Family canon | `list_family_ideas`, `assess_family_adoption` | Ideas shared across projects |
+| Processes | `list_processes`, `get_process`, `create_process` | Stored procedures |
+| Retrieval | `retrieval_telemetry`, `tune_retrieval` | What was surfaced, and the thresholds |
 | Trash | `list_trash`, `restore`, `purge_trash` | Recoverable deletes |
-| Admin | `get_app_logs` (write/admin key) | Diagnostics |
 
 Server-level usage guidance — when to reach for each entity, the
 recall-before-acting reflex, and the rulebook conventions — is delivered to the
 client automatically via the MCP server's `instructions` block (defined in
-`src/scribe/mcp/server.py`).
+`src/grimoire/mcp/server.py`).

docs/api-reference.md

@@ -52,6 +52,9 @@ endpoint at `/mcp`, not these REST routes.
 | POST | `/api/notes/:id/versions/:vid/pin` | Pin a version |
 | GET / PUT / DELETE | `/api/notes/:id/draft` | Unsaved-edit draft (restore across page loads) |
 | GET | `/api/notes/graph` | Knowledge-graph nodes/edges |
+| GET | `/api/notes/duplicates` | Near-duplicate notes or tasks, grouped |
+| GET | `/api/notes/due-for-verification` | Notes that carry a check, oldest verification first |
+| POST | `/api/notes/:id/verify` | Record that a note's check was run `{still_true}` |
 
 ## Tasks
 
@@ -77,7 +80,7 @@ endpoint at `/mcp`, not these REST routes.
 |--------|------|-------------|
 | GET / POST | `/api/projects` | List (owned + shared) / create |
 | GET / PATCH / DELETE | `/api/projects/:id` | Read (with `milestone_summary`, `inception`) / update / delete |
-| POST | `/api/projects/:id/inception` | Record what the project inherits `{choices: {subscribe_rulebooks, design_system_id, seed_systems}}` (owner-only; `POST /api/projects` accepts the same under `inception`) |
+| POST | `/api/projects/:id/inception` | Record what the project inherits `{choices: {design_system_id, seed_systems}}` (owner-only; `POST /api/projects` accepts the same under `inception`) |
 | GET | `/api/projects/:id/inception/defaults` | What binds if nobody decides — the inception card's payload |
 | GET | `/api/projects/:id/notes` | Notes + tasks in this project |
 | GET / POST | `/api/projects/:id/milestones` | List / create milestones |
@@ -86,7 +89,55 @@ endpoint at `/mcp`, not these REST routes.
 | GET / POST | `/api/projects/:id/systems` | List / create systems |
 | GET / PATCH / DELETE | `/api/projects/:id/systems/:sid` | Read / update / delete |
 | GET | `/api/projects/:id/systems/:sid/records` | Records linked to a system |
+| PUT | `/api/systems/:sid/canonical` | Map a system to a shared area `{canonical_id}` (`null` unmaps) |
+| GET / POST | `/api/canonical-systems` | List / create shared areas |
+| PATCH | `/api/canonical-systems/:id` | Update a shared area |
 | GET | `/api/projects/:id/issues` | Project issues |
+| PUT | `/api/projects/:id/design-system` | Point the project at a design system `{design_system_id}` (`null` clears) |
+| GET / PUT | `/api/projects/:id/platforms` | The project's platforms `{platforms: {slug: "declared" \| "rejected" \| null}}` |
+| PUT | `/api/projects/:id/forge` | Pin the project to one forge connection, or clear it |
+| GET / POST | `/api/platforms` | Platform catalogue / add a platform |
+| PATCH | `/api/platforms/:id` | Update a platform |
+
+## Snippets and lessons
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET / POST | `/api/snippets` | List / create snippets |
+| GET / PATCH / DELETE | `/api/snippets/:id` | Read / update / delete |
+| POST | `/api/snippets/:id/verify` | Record a drift-check verdict `{status, detail, path}` |
+| GET | `/api/snippets/duplicates` | Near-duplicate snippets, grouped into merge candidates |
+| POST | `/api/snippets/:id/merge` | Merge source snippets into this one |
+| POST | `/api/snippets/:id/unmerge` | Pull one source back out `{source_id}` |
+| GET / POST | `/api/lessons` | List / create lessons |
+| GET / PATCH / DELETE | `/api/lessons/:id` | Read / update / delete (to the trash) |
+| GET | `/api/lessons/rule-candidates` | Rules a draft lesson resembles, before it is saved |
+| GET | `/api/lessons/taught-by/:record_id` | Lessons drawn from one record |
+| PUT | `/api/lessons/:id/rules/:rule_id` | Confirm or reject a lesson → rule link |
+
+## Design systems
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET / POST | `/api/design-systems` | List / create |
+| GET | `/api/design-systems/starter-roles` | Starter token roles for the creation form |
+| GET / PATCH / DELETE | `/api/design-systems/:id` | Read / update / delete |
+| GET | `/api/design-systems/:id/resolved` | The effective token set, inheritance applied |
+| GET | `/api/design-systems/:id/stylesheet` | The generated stylesheet |
+| GET | `/api/design-systems/:id/snippet-check` | Snippets that disagree with the system's sheet |
+| GET / POST | `/api/design-systems/:id/tokens` | This system's own tokens / add one |
+| PATCH / DELETE | `/api/design-tokens/:id` | Update / delete a token |
+
+## Family canon
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/family/ideas` | Family ideas |
+| GET | `/api/family/ideas/:id` | One idea with its references |
+| POST | `/api/family/ideas/:id/propose` · `/promote` · `/retire` | Move an idea through its lifecycle |
+| GET | `/api/family/matrix` | Projects × canon ideas, with each project's answer |
+| GET | `/api/family/decisions` | Promotion and retirement decisions |
+| POST | `/api/family/decisions/:id/undo` | Undo a decision |
 
 ## Knowledge browse
 
@@ -115,11 +166,30 @@ endpoint at `/mcp`, not these REST routes.
 | GET | `/api/rules` | List rules |
 | POST | `/api/rulebook-topics/:tid/rules` | Add a rule to a topic |
 | GET / PATCH / DELETE | `/api/rules/:id` | Read / update / delete a rule |
-| POST | `/api/projects/:id/rulebook-subscriptions` | Subscribe a project to a rulebook |
-| GET | `/api/projects/:id/rules` | Applicable rules for a project |
+| POST | `/api/rules/:id/move` | Move a rule: `{topic_id}` makes it global, `{project_id}` makes it that project's |
+| GET | `/api/projects/:id/rules` | A project's own rules, and the global rules tagged to its areas |
 | POST | `/api/projects/:id/rules` | Create a project-scoped rule |
-| POST / DELETE | `/api/projects/:id/suppressions/rules/:rid` | Suppress / unsuppress a rule |
-| POST / DELETE | `/api/projects/:id/suppressions/topics/:tid` | Suppress / unsuppress a topic |
+| GET | `/api/rules/:id/versions` | A rule's edit history, newest first |
+| GET | `/api/rules/:id/versions/:vid` | One earlier version in full |
+| POST | `/api/rules/:id/versions/:vid/restore` | Put a preference back to an earlier version (preferences only) |
+| GET | `/api/rules/drift` | Preferences that have been rewritten, most recent first |
+| POST | `/api/rules/:id/relations` | Relate this rule to another (`co_surfaces`, `overrides`, `elaborates`) |
+| DELETE | `/api/rule-relations/:id` | Remove a relation |
+| GET | `/api/rules-due-for-verification` | Rules that carry a check, oldest verification first |
+| POST | `/api/rules/:id/verify` | Record that a rule's check was run `{still_true}` |
+
+## Retrieval
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/retrieval/surfaces` | Every tunable surface with its threshold and budget |
+| PUT | `/api/retrieval/surfaces/:surface` | Change one surface's setting, recorded with its reason |
+| GET | `/api/retrieval/tuning-history` | Changes to retrieval on this install, newest first |
+| GET | `/api/retrieval/moments` | The moments of work rules mount on, and the actions that reach each |
+| POST / DELETE | `/api/retrieval/moments/mappings` | Map / unmap an action to a moment |
+| GET | `/api/retrieval/moments/proposals` | Proposed rule → moment mounts awaiting a judgment |
+| POST | `/api/retrieval/moments/proposals/judge` | Confirm or reject proposals |
+| GET | `/api/retrieval/reply-shapes` | The default reply shapes and the moment each arrives at |
 
 ## Sharing
 
@@ -149,13 +219,15 @@ endpoint at `/mcp`, not these REST routes.
 | POST | `/api/notifications/:id/read` | Mark one read |
 | POST | `/api/notifications/read-all` | Mark all read |
 
-## Profile and Settings
+## Settings
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET / PUT | `/api/profile` | Read / update the per-user profile |
 | GET / PUT | `/api/settings` | Read / update key-value settings |
 | GET | `/api/settings/search` | SearXNG configuration status |
+| GET / POST | `/api/settings/forge-connections` | Your git forge connections / add one |
+| PUT / DELETE | `/api/settings/forge-connections/:id` | Update / remove a connection |
+| POST | `/api/settings/forge-connections/:id/test` | Check that the forge is reachable and accepts the token |
 
 ## API keys
 
@@ -166,10 +238,20 @@ endpoint at `/mcp`, not these REST routes.
 
 ## Plugin (Claude Code)
 
+These serve the plugin's hooks.
+
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/plugin/context` | SessionStart context payload (rules + active-project) |
-| GET | `/api/plugin/retrieve` | Title-first knowledge-injection candidates |
+| GET | `/api/plugin/context` | Session-start context: the active project and its state |
+| GET | `/api/plugin/retrieve` | Records and rules matching the operator's prompt |
+| GET | `/api/plugin/tool-rules` | Rules matching a tool call about to run |
+| GET | `/api/plugin/moment-tools` | The tools whose calls can reach a moment |
+| POST | `/api/plugin/moment` | The rules mounted on the moments a tool call reaches |
+| POST | `/api/plugin/reply-rules` | Whether the reply ending a turn is held for one read |
+| POST | `/api/plugin/rule-opened` | Records that a session opened a rule it was shown |
+| GET | `/api/plugin/shape-check` | The end-of-turn question about what this turn wrote |
+| GET | `/api/plugin/claim-session` · `/release-session` | Bind a session to its task claims / release them at session end |
+| GET | `/api/plugin/write-scope` | Which projects a pending act would change (a directory, or an MCP call's `tool` and `input`), and whether a session in its own project may do it. Filing an issue elsewhere is allowed; every other cross-project write is answered `allowed: false` with the reason the operator is asked |
 | GET | `/api/plugin/processes` | Stored Processes for skill-stub sync |
 | GET | `/api/plugin/prior-art` | Write-path hint for the plugin hooks (params: `path`, `code`, `repo`, `shapes`, `exclude_ids`, `exclude_sync_ids`, `exclude_derive`); returns `context`, `note_ids`, `sync_note_ids`, `stamped`, `divergence`, `derive`, `derive_keys` |
 | GET / POST | `/api/projects/<id>/coverage`, `…/coverage/refresh` | Shape-ledger accounting (`pattern_coverage` line, counts, `derive_groups` — css groups carry `consumers`, `derive_new`, `unused_css`, `divergence`, `recheck`) |
@@ -191,19 +273,32 @@ endpoint at `/mcp`, not these REST routes.
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/admin/backup` | Export backup (format v4; `?scope=user` for own data) |
-| POST | `/api/admin/restore` | Restore from a backup |
+| GET | `/api/admin/restore/sources` | The backups at the backup destination, newest first |
+| POST | `/api/admin/restore/preview` | What restoring a backup (`?source=<name>` or an uploaded file) would change; 409 with the reason when it can't apply here |
+| POST | `/api/admin/restore?confirm=rollback` | Put the whole instance back to that backup, after saving the current state |
 | GET / DELETE | `/api/admin/users` · `/api/admin/users/:id` | List / delete users |
 | GET / PUT | `/api/admin/registration` | Get / toggle registration |
 | GET / PUT | `/api/admin/smtp` · POST `/api/admin/smtp/test` | SMTP config + test email |
 | GET | `/api/admin/logs` · `/api/admin/logs/stats` | Log entries + category counts |
 | GET / PUT | `/api/admin/base-url` | Get / set the public base URL |
+| GET / PUT | `/api/admin/proxy` | Get / set how many reverse proxies stand in front of Grimoire (`{"hops": n}`, or `null` for the environment's count), with what each count would read for this request |
 | GET / PUT | `/api/admin/db-maintenance` (+ `/health`, POST `/run`) | VACUUM schedule, health, manual run |
 | POST / GET / DELETE | `/api/admin/invitations` (+ `/:id`) | Create / list / revoke invite links |
+| GET / PUT | `/api/admin/backups` | Scheduled backups: destination, schedule and recent runs |
+| POST | `/api/admin/backups/check` | Ask the destination whether it would accept a backup |
+| POST | `/api/admin/backups/run` | Start a backup now |
+| GET / PUT | `/api/admin/forge-webhook` | The forge push-webhook settings |
 
-## Scribe MCP
+## Webhooks
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/webhooks/forge` | Push events from a git forge, verified with `FORGE_WEBHOOK_SECRET` **(public)** |
+
+## Grimoire MCP
 
 Claude clients connect to the built-in MCP server at `POST /mcp` (streamable HTTP,
-Bearer auth with an `fmcp_` key), served by `src/scribe/mcp/`. It is not a REST
+Bearer auth with an `fmcp_` key), served by `src/grimoire/mcp/`. It is not a REST
 surface — it exposes the same data as typed tools (`create_note`, `create_task`,
 `start_planning`, `search`, `enter_project`, …) with
 server-level usage guidance delivered in the MCP `instructions` block. See

docs/architecture.md

@@ -1,380 +1,95 @@
 # Architecture
 
+Grimoire is one app container and one PostgreSQL container. There is no language model in the stack: Claude works with Grimoire from outside, through the MCP endpoint and the Claude Code plugin, and people use the web UI.
+
 ## Stack
 
-| Layer | Technology | Notes |
-|-------|-----------|-------|
-| Frontend | Vue 3 + TypeScript + Vite + Pinia + Vue Router | SPA served from the same container as the API |
-| Editor | Tiptap (ProseMirror) with custom slash-command extension | |
-| Backend | Python 3.12, Quart (async ASGI) | Serves both API and built frontend static files |
-| Database | PostgreSQL 16, SQLAlchemy 2.0 async, Alembic | asyncpg driver |
-| LLM | Ollama (local) | Any OpenAI-compatible API also works |
-| Search | SearXNG (optional, self-hosted) | Web search + image search |
-| Push | Web Push / VAPID (pywebpush 2.x) | |
-| Deployment | Docker Compose | Single-container app + separate DB + LLM service |
+| Layer | Technology |
+|-------|-----------|
+| Frontend | Vue 3, TypeScript, Vite, Pinia, Vue Router; Tiptap for the editor |
+| Backend | Python 3.14, Quart (async), served by Hypercorn |
+| MCP | The `mcp` SDK's server, mounted in the same app at `/mcp` (streamable HTTP) |
+| Database | PostgreSQL 17 with pgvector; SQLAlchemy 2 (async, asyncpg); Alembic migrations |
+| Embeddings | fastembed running in-process (`BAAI/bge-small-en-v1.5`, 384 dimensions) |
+| Plugin | Claude Code hooks (POSIX shell + awk), skills and a slash command, shipped from this repo |
 
-## High-Level Component Diagram
+## How the pieces fit
 
 ```
-┌─────────────────────────────────────────────┐
-│              Docker Compose                  │
-│                                              │
-│  ┌──────────────────────┐   ┌────────────┐  │
-│  │  scribe     │   │  ollama    │  │
-│  │  ┌────────────────┐  │   │            │  │
-│  │  │  Quart Server  │  │   │  LLM API   │  │
-│  │  │  ┌──────────┐  │  │   │            │  │
-│  │  │  │ Vue SPA  │  │  │   └────────────┘  │
-│  │  │  │ (static) │  │  │         ▲         │
-│  │  │  └──────────┘  │  │         │         │
-│  │  │  ┌──────────┐  │  │    HTTP/REST      │
-│  │  │  │ /api/*   │──┼──┼─────────┘         │
-│  │  │  └──────────┘  │  │                   │
-│  │  │       │        │  │  ┌────────────┐   │
-│  │  │       ▼        │  │  │ PostgreSQL │   │
-│  │  │  ┌──────────┐  │  │  │    16      │   │
-│  │  │  │ asyncpg  │──┼──┼──▶            │   │
-│  │  │  └──────────┘  │  │  └────────────┘   │
-│  │  └────────────────┘  │                   │
-│  └──────────────────────┘                   │
-└─────────────────────────────────────────────┘
+ Claude Code ──── plugin hooks ──── /api/plugin/*  ┐
+      │                                            │
+      └────────── MCP tools ──────── /mcp          ├── Quart app ── PostgreSQL + pgvector
+                                                   │      │
+ Browser ──────── Vue SPA ────────── /api/*        ┘      └── in-process jobs and embedder
 ```
 
-## Project Structure
+- **The web UI** is a Vue single-page app, built into the image and served by Quart. Every unknown path that isn't under `/api/` falls back to `index.html`; `/api/*` always answers JSON.
+- **The REST API** (`src/grimoire/routes/`) backs the UI, one blueprint per resource.
+- **The MCP server** (`src/grimoire/mcp/`) is how Claude reads and writes records. Each module in `mcp/tools/` registers its tools, and the server's instructions and each tool's docstring are the contract an agent reads. Requests authenticate with an API key as a Bearer token.
+- **The plugin** (`plugin/`) runs in the user's Claude Code. Its hooks call `/api/plugin/*` to put the right context in front of Claude at the right moment: the project at session start, matching rules and prior art before a prompt or a tool call, the rules mounted on a moment of work, and a check on the reply that ends a turn. Its skills describe the working practices. See [API Keys & MCP](api-keys-and-mcp.md) to install it.
+- **Services** (`src/grimoire/services/`) hold the logic both doors share. Routes and MCP tools stay thin: parse the request, check access, call a service, return a plain dict.
 
-```
-scribe/
-├── docker-compose.yml           # Development stack
-├── docker-compose.prod.yml      # Production stack (Docker Swarm)
-├── Dockerfile                   # Multi-stage build (Node → Python)
-├── alembic/                     # Database migrations
-│   └── versions/                # Migration files (idempotent raw SQL)
-├── src/scribe/
-│   ├── app.py                   # Quart app factory + blueprint registration
-│   ├── config.py                # Config class (reads env vars)
-│   ├── auth.py                  # login_required decorator, session checks
-│   ├── models/                  # SQLAlchemy models
-│   ├── mcp/                      # In-app MCP server (FastMCP, mounted at /mcp)
-│   │   ├── server.py            # FastMCP instance + instructions + Quart mount
-│   │   └── tools/               # Tool modules (notes, tasks, projects, rulebooks, …)
-│   ├── routes/                  # API blueprints (one file per resource)
-│   ├── services/                # Business logic (access, llm, tools, sharing, …)
-│   └── static/                  # Built Vue SPA (generated at Docker build time)
-└── frontend/
-    └── src/
-        ├── views/               # Page-level Vue components
-        ├── components/          # Reusable UI components
-        ├── composables/         # Vue composables (autosave, shortcuts, …)
-        ├── stores/              # Pinia stores (auth, chat, notes, notifications, …)
-        └── api/                 # Typed API client (client.ts)
-```
+## Data model
 
-## Key Design Decisions
+Most records are rows in one `notes` table, told apart by kind:
 
-**Single container for frontend + API.** Quart serves the Vue.js production build as static files and exposes the REST API under `/api/`. The SPA is built by Vite during the Docker image build.
+- **Notes**, and the specialised kinds that are notes underneath: **snippets** (recorded prior art, with a canonical code location), **lessons** (transferable insights, linked to the rules they instance) and **processes** (stored procedures, synced to Claude Code as skills).
+- **Tasks**: a note with a status. A task's kind is `work`, `issue` or `spike`. Tasks carry work logs, sub-tasks, recurrence and a session claim.
 
-**SPA routing via 404 handler.** `app.py` uses `@app.errorhandler(404)` (not a catch-all route) to serve static files or fall back to `index.html`. API routes (`/api/*`) always return JSON 404. This avoids a catch-all `/<path:path>` route intercepting API GETs.
+Around them:
 
-**Unified note/task model.** A task is just a note with task attributes enabled. `status IS NOT NULL` means it's a task. "Convert to task" sets `status='todo'`; "convert to note" clears `status`, `priority`, `due_date`. No separate table, no cascade complexity.
+- **Projects** group work and carry a goal. **Milestones** are plans: a design body plus ordered step tasks.
+- **Systems** are a project's named areas; records are tagged with them, and each maps to a canonical system shared across projects.
+- **Rulebooks → topics → rules.** A rule in a rulebook is global; a rule on a project applies there only. Rules have a trigger (`when_to_apply`), versions, relations to other rules, and can be mounted on **moments** of work (`work.change`, `reply.report`, ...), which plugin actions reach through moment mappings.
+- **Family canon**: ideas shared across projects on the same platform, and each project's answer to them (adopted, variant, owed).
+- **Design systems**: tokens and guidance, with inheritance; the stylesheet is generated from them.
+- **The shape ledger**: code shapes extracted from bound repos and their classification against snippets.
+- **Embeddings** for notes (chunked), rules, milestones and systems, in pgvector columns.
+- **Telemetry**: retrieval logs, note and rule usage, and the tuning history of retrieval thresholds.
+- **Users, groups, shares and API keys.** Access is decided in the app (`services/access.py`): owners, direct shares and group shares, with read or write permission.
 
-**First-class tag column.** Tags live in a `tags ARRAY[text]` column and are explicitly set by the client — not auto-extracted from body text. Hierarchical tags (`project/webapp`) supported via SQL `unnest + LIKE` prefix matching.
+Deleted records go to the trash first and can be restored until retention purges them.
 
-**Background generation architecture.** LLM streaming runs in a detached `asyncio.Task` that writes into an in-memory `GenerationBuffer`. SSE clients tail the buffer and can reconnect mid-stream without data loss. Buffer has a `cancel_event` for user-initiated stop. Completed buffers are cleaned up after 60s grace period. Periodic DB flushes every 5s preserve partial content. Both chat and AI Assist use this architecture.
+## Retrieval
 
-**SSE over WebSockets for LLM streaming.** SSE clients connect via `GET /api/chat/conversations/:id/generation/stream` with `Last-Event-ID` reconnection support. Frontend uses `fetch()` + `ReadableStream`.
+Search and the plugin's context injection run on the same pipeline (`services/retrieval_pipeline.py`): embed the query, rank stored chunks by cosine similarity in pgvector, keep what clears the surface's threshold, and log what was shown. Each surface (MCP search, auto-inject, the pre-tool rule arm, the write-path prior-art arm, ...) is a spec over those stages with its own thresholds and budget. The thresholds are settings an admin can tune, and every change is recorded with its reason. When the embedder is unavailable, search falls back to keyword matching.
 
-**Context building is server-side.** Backend fetches URL content and searches notes. Frontend sends the message text + optional context note IDs. `build_context()` returns `(messages, context_meta)`; metadata includes auto-found note IDs/titles sent to frontend via a `context` SSE event before streaming begins.
+The embedding model downloads into `FASTEMBED_CACHE_DIR` (default `/data/fastembed-cache`) on first use, so the `/data` volume keeps it across restarts.
 
-**No blocking long-running operations.** Any slow operation (model pulls, LLM calls, URL fetching) must never block app startup or freeze the UI. Backend uses SSE streaming for incremental responses. Model pulls stream NDJSON progress to the frontend.
+## Background work
 
-**SSRF protection.** `services/llm.py` blocks requests to loopback, private, link-local, reserved, and multicast addresses before fetching. `follow_redirects=False` prevents redirect-based bypasses.
+All in-process; there is no separate worker container.
 
-**Session cookie security.** `HttpOnly` and `SameSite=Lax` always set. `Secure` flag controlled by `SECURE_COOKIES` env var.
+- At startup the app records any shipped default that moved in this release, starts its schedulers, and only then backfills missing embeddings, so the backfill never competes with startup for the database.
+- Recurring tasks spawn every 15 minutes. Daily jobs: version auto-pinning (03:00 UTC), trash purge (03:30 UTC), targeted `VACUUM ANALYZE` (04:00 UTC by default). Scheduled backups check hourly whether one is due ([Backups](backups.md)).
+- Log, notification and auth-token retention run on their own loops.
+- A diagnostics heartbeat writes to `/data/diagnostics`.
 
-**Rate limiting.** In-memory sliding-window rate limiter (`rate_limit.py`) applied to auth endpoints: login (10/60s), register (5/300s), forgot-password (5/300s), reset-password (10/60s). Keys are per-IP. `TRUST_PROXY_HEADERS` env var enables `X-Forwarded-For` / `X-Real-IP` when behind a reverse proxy.
-
-**Idempotent migrations.** All Alembic migrations use raw SQL with `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and `DO $$ BEGIN CREATE TYPE ... EXCEPTION WHEN duplicate_object` to allow safe re-runs.
-
-## Data Model
-
-### Users
-
-| Column | Type | Notes |
-|--------|------|-------|
-| `id` | int PK | |
-| `username` | text UNIQUE NOT NULL | |
-| `email` | text nullable | |
-| `password_hash` | text nullable | NULL for OAuth-only accounts |
-| `oauth_sub` | text UNIQUE nullable | OIDC subject identifier |
-| `role` | text NOT NULL DEFAULT 'user' | First user auto-assigned 'admin' |
-| `session_version` | int NOT NULL DEFAULT 1 | Bumped on password change to evict sessions |
-| `created_at` | timestamptz | |
-
-### Notes (unified — includes tasks)
-
-| Column | Type | Notes |
-|--------|------|-------|
-| `id` | int PK | |
-| `title` | text | |
-| `body` | text | Markdown |
-| `tags` | ARRAY[text] | GIN indexed; explicitly set by client |
-| `parent_id` | int FK self nullable | Sub-tasks / sub-notes |
-| `user_id` | int FK users nullable | CASCADE |
-| `project_id` | int FK projects nullable | |
-| `milestone_id` | int FK milestones nullable | |
-| `status` | text nullable | `todo`/`in_progress`/`done` — non-null = task |
-| `priority` | text nullable | `none`/`low`/`medium`/`high` |
-| `due_date` | date nullable | |
-| `created_at`, `updated_at` | timestamptz | |
-
-Indexes: GIN on `tags`, B-tree on `status`, B-tree on `title`.
-
-### Settings
-
-Composite PK `(user_id, key)`. Per-user key-value store. CRUD via `services/settings.py`. Used for: `default_model`, `assistant_name`, `journal_config` (JSON: locations, temp_unit, prep schedule), `user_timezone`, `voice_*`, etc.
-
-### Conversations / Messages
-
-`conversations`: `id`, `title`, `model`, `user_id`, `conversation_type` (`chat`/`journal`/`mcp`), `day_date` (YYYY-MM-DD for journal conversations), `rag_project_id` (nullable int — RAG scope: NULL=orphan-only, -1=all, positive=project), `created_at`, `updated_at`.
-`messages`: `id`, `conversation_id` FK CASCADE, `role` (`user`/`assistant`), `content`, `status` (`done`/`generating`), `created_at`.
-
-Title auto-generated by LLM on first exchange, re-generated every 10th message.
-
-### Projects / Milestones
-
-`projects`: `id`, `user_id`, `title`, `description`, `goal`, `status` (`active`/`completed`/`archived`), `color`, `auto_summary` (nullable text — LLM-generated summary for `search_projects` scoring), `summary_updated_at` (nullable timestamptz), timestamps.
-`milestones`: `id`, `user_id`, `project_id` FK CASCADE, `title`, `description`, `status`, `order_index`, timestamps.
-
-### Sharing & Access
-
-`project_shares`, `note_shares`: each has `shared_with_user_id` OR `shared_with_group_id` (exclusive), `permission` (`viewer`/`editor`/`admin`), `invited_by`.
-
-`groups`, `group_memberships`: platform-wide groups with `member`/`owner` roles.
-
-Permission resolution is centralised in `services/access.py`. `get_project_permission(uid, project_id)` checks ownership → direct share → group-based share → note→project inheritance, returning the highest applicable permission.
-
-### Journal-Related Tables
-
-`weather_cache`: per-user, per-`location_key` cache. Columns: `user_id`, `location_key` (`home`/`work`/etc.), `location_label`, `forecast_json` (Open-Meteo response), `previous_json` (last forecast, used to detect changes), `fetched_at`. Lat/lon are *not* stored on the cache row — they live in the user's `journal_config.locations.{home|work}` setting and are used at refresh time.
-
-### API Keys
-
-`api_keys`: `id`, `user_id` FK CASCADE, `prefix` (first 8 chars, displayed in UI), `key_hash` (SHA-256 of full key — full key never stored), `name`, `scope` (`read`/`write`), `created_at`, `last_used_at`.
-
-### App Logs
-
-`category` (`audit`/`usage`/`error`), `user_id` FK nullable (SET NULL on delete), `username` (denormalised), `action`, `endpoint`, `method`, `status_code`, `duration_ms`, `error_type`, `error_message`, `traceback`, `details` JSONB.
-
-## Detailed File Reference
-
-### Backend (`src/scribe/`)
-
-| File | Responsibility |
-|------|---------------|
-| `app.py` | Quart app factory; SPA via 404 handler; JSON 404/500 for API; request logging; security headers in `after_request` |
-| `auth.py` | `login_required`, `admin_required`, `get_current_user_id` — shared `_check_auth()` helper; accepts session cookie or `Authorization: Bearer <key>` |
-| `config.py` | All config from env vars + Docker secret file support (`_read_secret`); `SECURE_COOKIES`, `TRUST_PROXY_HEADERS`, `OLLAMA_NUM_CTX`; `oidc_enabled()`, `searxng_enabled()` classmethods |
-| `rate_limit.py` | In-memory sliding-window rate limiter (`asyncio.Lock` + `defaultdict`); `is_rate_limited(key, max, window)` |
-| `models/note.py` | Unified Note model (notes + tasks) |
-| `models/user.py` | `id`, `username`, `email`, `password_hash` (nullable — NULL for OAuth-only), `oauth_sub` (unique nullable), `role`, `session_version` |
-| `models/conversation.py` | `Conversation` + `Message` models |
-| `models/app_log.py` | `AppLog` with `category`, denormalised `username`, `details` JSONB |
-| `models/api_key.py` | `ApiKey`: `id`, `user_id`, `prefix`, `key_hash` (SHA-256), `name`, `scope` (`read`/`write`), `created_at`, `last_used_at` |
-| `models/event.py` | Internal events store (`Event` model: `id`, `user_id`, `title`, `description`, `start_dt`, `end_dt`, `all_day`, `location`, `caldav_uid` nullable, `color`, timestamps) |
-| `routes/api.py` | `/api` blueprint; `GET /api/health` (public) |
-| `routes/auth.py` | Register, login, logout, me, password/email change, password reset, invite registration, OAuth login+callback; rate limiting; `LOCAL_AUTH_ENABLED` guards |
-| `routes/admin.py` | Backup, restore, user management, registration toggle, invitations, base URL, SMTP (admin only) |
-| `routes/chat.py` | Conversations CRUD; SSE generation stream; model pull/delete/list/warm |
-| `routes/notes.py` | Notes CRUD + wikilinks + backlinks + assist + link suggestions + version history + drafts |
-| `routes/tasks.py` | Tasks CRUD; `POST` accepts `project` name string (resolved to `project_id`) |
-| `routes/task_logs.py` | Task work log CRUD (`GET/POST/DELETE /api/tasks/:id/logs`) |
-| `routes/projects.py` | Projects CRUD + summary endpoint |
-| `routes/milestones.py` | Milestones CRUD under `/api/projects/:id/milestones` |
-| `routes/settings.py` | Per-user settings key-value (`GET/PUT /api/settings/:key`) |
-| `routes/journal.py` | Journal config CRUD; today/day/days conversation accessors; weather endpoints (cached/current/refresh/geocode); moments CRUD; trigger-prep |
-| `routes/groups.py` | Group CRUD + membership management (admin) |
-| `routes/shares.py` | Share project/note with user or group; revoke; list incoming shares |
-| `routes/in_app_notifications.py` | In-app notification list + mark-read + count |
-| `routes/push.py` | Web Push subscription subscribe/unsubscribe; VAPID public key |
-| `routes/users.py` | User profile; admin user list + delete |
-| `routes/images.py` | Serve cached images at `/api/images/<id>` |
-| `routes/export.py` | `GET /api/export` — personal Markdown ZIP or JSON array download |
-| `routes/api_keys.py` | API key CRUD (`GET/POST/DELETE /api/api-keys`) |
-| `mcp/server.py` | Mounts the in-app FastMCP server at `/mcp` (streamable HTTP, Bearer auth) |
-| `routes/quick_capture.py` | `POST /api/quick-capture` — single-shot natural language item creation |
-| `routes/search.py` | `GET /api/search` — semantic + keyword hybrid search |
-| `services/auth.py` | `create_user`, `authenticate`, user lookups, password reset tokens, invitation tokens |
-| `services/oauth.py` | OIDC discovery (cached), PKCE auth URL, code exchange, `find_or_create_oauth_user` |
-| `services/api_keys.py` | `generate_key()`, `create_api_key()`, `list_api_keys()`, `revoke_api_key()`, `lookup_key()` (SHA-256 hash lookup) |
-| `services/llm.py` | `build_context()`, RAG injection, history summarisation, `stream_chat_with_tools()`, URL fetching, SSRF guard |
-| `services/generation_task.py` | `run_generation()` — full chat pipeline: intent routing, tool loop, SSE fan-out, push notification; `run_assist_generation()` |
-| ~~`services/intent.py`~~ | Removed — intent routing eliminated; the main model handles all tool routing directly |
-| `services/tools/` | LLM tool package — decorator-based registry (`_registry.py`), shared helpers (`_helpers.py`), and one module per domain: `notes.py` (create/update/delete/search/list/read), `tasks.py` (list/log_work), `entities.py` (save_person/save_place/lists), `projects.py`, `calendar.py`, `web.py`, `rag.py`, `profile.py`, `rss.py`, `weather.py`, `utility.py` (calculate). `execute_tool()` and `get_tools_for_user()` are the public API. |
-| `services/projects.py` | Project CRUD + `generate_project_summary()` (Ollama, fire-and-forget) + `backfill_project_summaries()` (startup) |
-| `services/embeddings.py` | `upsert_note_embedding()`, `semantic_search_notes(orphan_only=False)` (pgvector cosine similarity) |
-| `services/generation_buffer.py` | In-memory SSE event buffer; `cancel_event`; 60s cleanup; supports both chat (int keys) and assist (string keys) |
-| `services/notes.py` | Note CRUD, wikilink resolution, backlink queries, tag management |
-| `services/note_versions.py` | Version snapshot on save; restore-from-version; diff metadata |
-| `services/note_drafts.py` | Per-user per-note draft persistence (AI Assist pending state) |
-| `services/settings.py` | `get_setting()`, `set_setting()`, `get_all_settings()` — key-value per user |
-| `services/tag_suggestions.py` | `/api/notes/suggest-tags` — LLM-generated tag suggestions for note body |
-| `services/access.py` | Permission resolution for all shared resources |
-| `services/sharing.py` | Create/revoke shares; list shares; `get_shared_with_me()` |
-| `services/groups.py` | Group CRUD; membership management |
-| `services/notifications.py` | Create/read/mark-read in-app notifications |
-| `services/task_logs.py` | Append/list/delete work log entries on tasks |
-| `services/journal_prep.py` | Deterministic data gather (tasks/events/weather/projects/recent moments/open threads) → LLM prose opener; persisted as the first assistant message of today's journal Conversation |
-| `services/journal_pipeline.py` | System-prompt builder for journal conversations; calls `build_profile_context()` so the LLM sees the user's profile + learned summary |
-| `services/journal_scheduler.py` | APScheduler `BackgroundScheduler`; per-user prep job; live-reschedule via `update_user_schedule()`; catch-up logic for missed runs |
-| `services/journal_search.py`, `services/moments.py` | Moment recording + search across journal history |
-| `services/user_profile.py` | `build_profile_context()` consolidates profile + observations + learned_summary into a system-prompt block |
-| `services/research.py` | SearXNG research pipeline: sub-queries → parallel fetch → outline → section synthesis → executive summary → index note with linked section notes |
-| `services/events.py` | Internal events CRUD: `list_events`, `create_event`, `update_event`, `delete_event`, `get_event`; source of truth for all event LLM tools |
-| `routes/events.py` | `/api/events` — event CRUD routes |
-| `services/caldav.py` | Optional CalDAV sync — user-configured external server; syncs to/from internal store via `caldav_uid` FK; `is_caldav_configured()` guards tool activation |
-| `services/calendar_sync.py` | Dead code — Radicale sync service; was trialled and removed |
-| `services/images.py` | `fetch_and_store_image()` — SHA-256 dedup, content-type validation, 5 MB cap |
-| `services/backup.py` | `export_full_backup()`, `export_user_backup()`, `restore_full_backup()` (version 2 with ID maps) |
-| `services/push.py` | VAPID key auto-generation; `send_push_notification()` fire-and-forget; 410 Gone cleanup |
-| `services/logging.py` | `log_audit`, `log_usage`, `log_error`, `start_log_retention_loop` (hourly cleanup) |
-| `services/email.py` | SMTP email sending for password reset; reads `SMTP_*` env vars |
-| `services/weather.py` | Nominatim geocoding + Open-Meteo forecast + per-user DB cache |
-| `services/rss.py` | feedparser fetch; per-feed DB cache; prune-to-100 items |
-| `services/assist.py` | `build_assist_messages()` — section/whole-doc modes; project context injection |
-
-### Frontend (`frontend/src/`)
-
-| File | Responsibility |
-|------|---------------|
-| `App.vue` | App shell (`100dvh` flex column); global keyboard shortcuts (`g`+key nav, `n/t/c/e///?`); starts status polling + loads settings on mount |
-| `api/client.ts` | `ApiError`, `apiGet/Post/Put/Patch/Delete`, `apiSSEStream` (fetch + ReadableStream), auto 401→login redirect |
-| `stores/auth.ts` | User, `isAuthenticated`, `isAdmin`, `oauthEnabled`, `localAuthEnabled`, login/register/logout/checkAuth |
-| `stores/chat.ts` | Conversation CRUD; `sendMessage()` SSE streaming; `reconnectIfGenerating()`; message queue (localStorage); `streamingStatus` |
-| `stores/notes.ts` | CRUD + tag filter; `resolveTitle`; `convertToTask/Note`; `fetchBacklinks`; `fetchAllTags` |
-| `stores/tasks.ts` | CRUD + status/priority filter; `patchStatus` |
-| `stores/settings.ts` | `assistantName`, `defaultModel`, `installedModels`; `pullModel()`, `deleteModel()` |
-| `stores/push.ts` | `isSupported`, `permission`, `isSubscribed`, `subscribe/unsubscribe` |
-| `stores/notifications.ts` | `count`, `items`, `fetchCount`, `fetchAll`, `markRead`, `markAll` |
-| `views/HomeView.vue` | Chat-first dashboard; 6 task sections (Overdue → Other); 8 recent notes; inline streaming response |
-| `views/ChatView.vue` | `/chat` — SSE streaming; context sidebar (Suggested/In Context); note picker; scope chip (RAG project scope pill above input); message queue; bulk delete |
-| `views/CalendarView.vue` | `/calendar` — FullCalendar v6 month/week/day views; click to create event; click event to open EventSlideOver |
-| `components/EventSlideOver.vue` | Reusable slide-over for event create/edit/delete; used in ToolCallCard, HomeView, CalendarView |
-| `views/WorkspaceView.vue` | `/workspace/:id` — 3-panel (tasks/chat/notes); SSE tool-call watcher; conv persisted to localStorage |
-| `views/GraphView.vue` | `/graph` — D3 force-directed; tag/note/project-hub nodes; physics panel; peek panel |
-| `views/ProjectView.vue` | Kanban grouped by milestone; advance buttons; milestone management |
-| `views/SettingsView.vue` | Tabbed settings (11 tabs); tab state in localStorage |
-| `views/NoteEditorView.vue` | Tiptap editor; 2-column layout; AI assist panel; diff view; version history; autosave |
-| `views/TaskEditorView.vue` | Tiptap editor; 2-column layout; AI assist panel; task log section; sub-tasks |
-| `components/ToolCallCard.vue` | Tool call results; `requires_confirmation` inline confirm/deny; direct POST on "Create anyway" |
-| `components/ChatMessage.vue` | Message bubble; markdown rendering; tool call cards; "Save as Note" |
-| `components/TagInput.vue` | Chip-based tag input; Enter/comma to confirm; autocomplete from `/api/notes/tags` |
-| `components/TiptapEditor.vue` | Tiptap wrapper; markdown↔HTML round-trip; selection change emit; WikilinkDecoration; TagDecoration |
-| `components/ShareDialog.vue` | `<Teleport>` modal; user tab + group tab; current shares list |
-| `components/WorkspaceTaskPanel.vue` | Milestone-grouped task list; detail slide-over |
-| `components/WorkspaceNoteEditor.vue` | List ↔ TipTap editor with autosave |
-| `composables/useAssist.ts` | AI assist: section parsing, SSE streaming, accept/reject, LCS diff, persistent draft |
-| `composables/useAutoSave.ts` | Interval-based autosave (5 min) with dirty/saving guards |
-| `composables/useEditorGuards.ts` | Ctrl+S, `beforeunload` warning, route-leave confirm |
-| `composables/useTagSuggestions.ts` | `/api/notes/suggest-tags` call + suggestion state |
-| `composables/useListKeyboardNavigation.ts` | j/k/Enter list navigation; focus-in-input guard |
-| `extensions/WikilinkDecoration.ts` | ProseMirror decoration plugin highlighting `[[wikilinks]]` |
-| `extensions/TagDecoration.ts` | ProseMirror decoration plugin highlighting `#tags` |
-| `extensions/WikilinkSuggestion.ts` | `@tiptap/suggestion` extension for `[[` autocomplete |
-
-## Key Services
-
-| Service | Responsibility |
-|---------|---------------|
-| `services/access.py` | Permission resolution for all shared resources |
-| `services/llm.py` | `build_context()`, RAG injection, history summarisation |
-| `services/generation_task.py` | SSE streaming, tool-call loop, GenerationBuffer management |
-| `services/tools/` | LLM tool implementations (38 tools across 11 modules); decorator-based registry |
-| `services/embeddings.py` | `upsert_note_embedding()`, `semantic_search_notes()` |
-| `services/journal_prep.py` | Data gather → LLM prose opener; persisted into today's journal conversation |
-| `services/journal_scheduler.py` | APScheduler integration, per-user prep job, catch-up for missed runs |
-| `services/backup.py` | Full and per-user backup export/restore (version 2 format) |
-| `services/weather.py` | Nominatim geocoding + Open-Meteo forecast fetch + DB cache |
-| `services/rss.py` | feedparser-based fetch, per-feed DB cache, prune-to-100 |
+Every database wait on startup has a deadline. Migrations wait for the database to accept connections (up to five minutes) before they run, so the app starts cleanly whatever order the containers come up in.
 
 ## Authentication
 
-**Session cookies** — `HttpOnly`, `SameSite=Lax`, optionally `Secure` (`SECURE_COOKIES` env var). Session includes `session_version`; mismatch with DB value (after password change) results in 401 and session clear.
+- **Sessions**: `HttpOnly`, `SameSite=Lax` cookies, `Secure` on a request the trusted proxy reports as HTTPS, which also gets HSTS (`grimoire/proxy.py`). Changing a password bumps the user's session version and signs out their other sessions.
+- **API keys**: `Authorization: Bearer fmcp_...`, stored hashed. A `read` key may only call read endpoints and read MCP tools.
+- **OIDC** single sign-on with PKCE, optionally replacing local logins ([SSO / OAuth](sso-oauth.md)).
+- **Rate limits** on register, login and forgot-password, per client IP, read from `X-Forwarded-For` by `TRUSTED_PROXY_HOPS`.
 
-**Bearer token / API keys** — `Authorization: Bearer <key>` accepted by `_check_auth()` as an alternative to session cookies. The raw key is SHA-256 hashed and looked up via `services/api_keys.py`. Keys with `scope=read` are rejected on non-safe methods (`POST`/`PATCH`/`DELETE`). Used by Fable MCP and any external API consumers.
+Credentials Grimoire stores for outside services (forge tokens, the backup destination's S3 secret) are sealed under a key derived from `SECRET_KEY`, which the instance makes on first start and keeps in `/data/secret_key` unless one is set.
 
-**Local auth + OIDC/OAuth (PKCE)** — `services/oauth.py` handles discovery and `find_or_create_oauth_user`. On OAuth login: checks existing `oauth_sub` → matching email → creates new user.
+## Repository layout
 
-See [sso-oauth.md](sso-oauth.md) for provider-specific setup instructions.
-
-## LLM Pipeline Internals
-
-### Tool Routing
-
-No separate intent router — the main model handles all tool routing directly via Ollama's structured tool-calling output. The model receives the full tool schema list and decides whether to call a tool or respond conversationally. Extended reasoning (`think=True`) is always on for qwen3-class models: content-based gating was tried but exposed tool-call template fragility on short tool-intent prompts.
-
-### Tool Loop
-
-Multi-round tool loop (max 5 rounds). All implementations in `services/tools/` (decorator-based registry); `execute_tool(user_id, tool_name, arguments, conv_id=None, workspace_project_id=None)` is the dispatcher. `conv_id` and `workspace_project_id` are threaded in from `run_generation()` so tools like `set_rag_scope` can write to the current conversation.
-
-**Unified `create_note` tool** — creates both notes and tasks. Setting `status` (e.g. `"todo"`) creates a task; omitting it creates a knowledge note. All task fields (due_date, priority, milestone, parent_task, recurrence_rule) are available on the single tool.
-
-**Duplicate protection on `create_note`:**
-1. Exact title match (case-insensitive) → hard block, redirect to `update_note`
-2. Fuzzy title match (SequenceMatcher ≥ 82%; punctuation stripped before candidate search) → hard block
-3. Semantic content similarity (threshold 0.90, body ≥ 80 chars) → soft block with `requires_confirmation: true`
-
-**Project resolution** (`_helpers.resolve_project`): 4-step lookup — (1) exact DB match, (2) `query in title` substring, (3) `title in query` reverse substring, (4) SequenceMatcher ≥ 0.55.
-
-### Context Window and Summarisation
-
-`OLLAMA_NUM_CTX` (default 16384) controls the context window for all generation calls. Intent classification always uses `num_ctx=4096` to reduce VRAM pressure.
-
-History summarisation threshold: 30 messages. Keeps 8 recent messages. Summary max 400 tokens.
-
-### Web Research Pipeline
-
-`services/research.py` implements a full autonomous research pipeline:
-1. Intent model generates 5 focused sub-queries
-2. All 5 SearXNG queries run in parallel (200ms stagger to avoid rate limiter)
-3. Up to 15 unique URLs fetched in parallel
-4. LLM generates an outline (2–8 sections with title + focus)
-5. Each section synthesised in parallel from relevant sources
-6. Executive summary generated from all section content
-7. Index note created with executive summary + links to section notes; section notes linked back via `parent_id`
-8. Falls back to single-note synthesis if outline generation fails
-
-SearXNG tip: add the app server IP to `botdetection.ip_lists.pass_ip` in SearXNG `settings.yml` to bypass the rate limiter for trusted backend requests.
-
-### Image Cache
-
-`search_images` tool fetches images server-side via SearXNG, stores them on disk (SHA-256 dedup, content-type validation, 5 MB cap), and serves from `/api/images/<id>`. The user's browser never contacts the original image host.
-
-Config: `IMAGE_CACHE_DIR` (default `/data/images`), `IMAGE_MAX_BYTES` (default 5 MB).
-
-## RAG Pipeline
-
-1. `semantic_search_notes()` — cosine similarity via pgvector, threshold configurable per call; accepts `orphan_only` and `project_id` scope flags.
-2. Notes ≥ 0.60 similarity auto-injected into system prompt (up to 3, 800 chars each).
-3. Notes 0.45–0.60 surfaced in chat sidebar as "Suggested" (user clicks to include).
-4. Explicitly included notes delivered full-body.
-5. `excluded_note_ids` prevents the current note from being injected as its own context.
-
-### RAG Scope (three-value system)
-
-`conversations.rag_project_id` controls which notes are eligible for retrieval:
-
-| Value | Behaviour |
-|-------|-----------|
-| `NULL` (default) | Orphan notes only — notes with `project_id IS NULL` |
-| `-1` | All notes — opt-in to global search |
-| Positive int | That project's notes only |
-
-`build_context()` derives `orphan_only` + `effective_project_id` from this value before calling both the semantic and keyword search paths.
-
-**Scope tools** — Two LLM tools let the model discover and switch scope mid-conversation:
-- `search_projects` — SequenceMatcher scoring over title + description + `auto_summary`; returns top 5 matching projects.
-- `set_rag_scope` — persists the new `rag_project_id` to DB immediately; blocked in workspace view; causes the SSE `done` event to include `new_rag_scope` + `new_rag_scope_label` so the frontend chip updates reactively.
-
-**Project summaries** — `generate_project_summary()` calls Ollama (fire-and-forget) and stores the result in `projects.auto_summary`. Triggered on project update and note saves (debounced 1h). `backfill_project_summaries()` runs at startup.
-
-Embedding model: `nomic-embed-text` via Ollama. Backfill runs 30s after startup (background task).
+```
+├── alembic/versions/      database migrations
+├── src/grimoire/
+│   ├── app.py             app factory, blueprints, startup and shutdown
+│   ├── config.py          environment configuration
+│   ├── models/            SQLAlchemy models
+│   ├── routes/            REST blueprints
+│   ├── mcp/               MCP server and its tool modules
+│   ├── services/          shared logic
+│   └── restore.py         `python -m grimoire.restore`: the restore, from the command line
+├── frontend/src/          views, components, stores, composables, api client
+├── plugin/                Claude Code hooks, skills and commands
+├── scripts/               CI checks and the plugin version minter
+└── tests/                 unit tests, plus `-m integration` against real Postgres
+```

docs/backups.md

@@ -0,0 +1,195 @@
+# Backups
+
+Grimoire can back itself up every day to a **folder** or an **S3-compatible
+bucket**. Each run adds one file; Grimoire never deletes an old one. Keeping and
+thinning the history is the destination's job.
+
+Set it up under **Settings → Data → Scheduled backups** (admins only).
+
+## What a backup is
+
+One file per run, named for the moment it was taken in UTC:
+
+```
+grimoire-20261015T020000Z.tar
+```
+
+Backups written while the app was called Scribe are named `scribe-…tar`.
+They are counted with the rest and restore the same way.
+
+It is a plain, **uncompressed** tar:
+
+- `manifest.json` comes first. It holds the backup format version, the Grimoire
+  version, when the backup was taken, and how many rows each table has.
+- Then there is one `<table>.jsonl` per table, one row per line.
+
+It holds everything the admin **Full Backup** download holds, laid out
+differently. It does **not** hold:
+
+- **Search indexes.** They are rebuilt from the records when Grimoire starts.
+- **Sharing:** groups, project shares and note shares.
+- **Credentials:** API keys and forge connections. After a restore, issue new
+  API keys and add forge connections again. (Forge tokens are also sealed under
+  `SECRET_KEY` in the database itself, so a copy of the database doesn't carry
+  them in readable form either. The key lives in `/data/secret_key`, outside
+  the database.)
+- **Logs and notifications.**
+- **The backup destination's own S3 secret.**
+
+The file contains hashed passwords, so store it somewhere only trusted people
+can read.
+
+### Why it is shaped this way
+
+The file is meant to be copied off-site by a deduplicating tool such as
+restic, which stores a chunk of data only once no matter how many backups
+contain it. Every choice serves that:
+
+- **It is never compressed.** Compression changes every byte after the first
+  edit, so nothing would match the day before. restic compresses its own
+  repository after deduplicating, so nothing is lost.
+- **Rows are in primary-key order, with their keys sorted.** A row that did
+  not change is the same bytes in the same place every day. An edited row
+  changes one line, and new rows land at the end of their table's file.
+- **Each table is its own file**, so a busy table never shifts the bytes of a
+  quiet one.
+- **The parts that change every run are kept in `manifest.json`**: the time
+  and the counts.
+- **Each run gets a new, dated name.** Overwriting one name would keep one
+  copy and no history.
+
+Day to day, the off-site copy then stores roughly what changed, not the whole
+file again.
+
+## Destinations
+
+### A folder
+
+A path **inside the Grimoire container**, normally a share mounted there:
+
+```yaml
+services:
+  grimoire:
+    volumes:
+      - /nfs/backup/grimoire:/backups
+```
+
+Grimoire writes each file under a hidden name (`.grimoire-….tar.part`) and renames
+it once it is complete. A program watching the folder never sees half a
+backup.
+
+### An S3-compatible bucket
+
+You need four things:
+
+- **Address:** the service itself, like `https://backup.example.com`. Don't
+  include the bucket; Grimoire addresses buckets by path.
+- **Bucket.**
+- **Access key.**
+- **Secret key.**
+
+Grimoire uploads and lists, and reads a backup back when you restore from the
+bucket; it never deletes. A key that may **add and read objects but not
+delete them** is therefore enough, and it is the safer key to hand out: a
+stolen one cannot wipe the history. A key that may only add objects still
+takes backups; restore then works by uploading a file or from the command
+line.
+
+The secret is stored encrypted, under a key derived from `SECRET_KEY`. It is
+never shown again, and never included in a backup. If an instance's
+`SECRET_KEY` changes, for example after a restore onto a new instance, the
+page asks for the secret again.
+
+**Test destination** checks the destination without sending a backup:
+
+- a folder: it writes and removes a hidden file;
+- a bucket: it only lists, because an add-only key could never remove a test
+  file.
+
+## Schedule and history
+
+- Backups run once a day at the hour you choose, in UTC. The default is 02:00,
+  before the nightly trash purge and database maintenance.
+- **Back up now** runs one straight away.
+- The page leads with when the last good backup was taken. It says
+  **Overdue** when backups are on and none has worked for 26 hours.
+- It lists the last 30 runs, and gives the reason for each failure in words.
+- A run that hasn't finished after an hour is abandoned and recorded as
+  failed.
+
+## Example: Fabled Archives
+
+[Fabled Archives](https://git.fabledsword.com/bvandeusen/fabledarchives)
+keeps service backups as "backup targets". Either destination works with it.
+
+1. On Archives' **Backups** page, make a target for Grimoire, named `grimoire`
+   for example.
+2. Choose how Grimoire's files arrive:
+   - **S3**: turn on the S3 way in for the target and make an S3 key that
+     may add and read objects but not delete them (an **append-only** key
+     takes backups too, but then Grimoire can't restore from the bucket). In
+     Grimoire, choose **An S3 bucket**:
+     - address: Archives' backup address (`http://<archives>:8081`);
+     - bucket: the target's name;
+     - access key and secret key: the key you just made.
+   - **A folder**: mount the share Archives watches into Grimoire as
+     `/backups/grimoire`, and point the target at that folder. In Grimoire, choose
+     **A folder** with `/backups/grimoire`.
+3. Set the target's **Retention** to **Archives**. Archives then keeps the
+   newest backups and thins the rest by day, week and month. Grimoire only adds.
+4. Give the target an expected cadence of **daily**, so a missed backup turns
+   it late in Archives as well as overdue in Grimoire.
+5. Add an off-site **restic** replication job for the target. The uncompressed
+   layout above is what lets that job send only what changed each day.
+
+## Restoring
+
+A restore puts the **whole instance** back to the moment a backup was taken,
+for every user:
+
+- records edited since go back to how they were;
+- records deleted since come back;
+- anything made since is removed.
+
+It matches records by their ids, so a live instance only restores a backup **of
+its own**. Each instance has an id, and every backup records the one it came
+from. A backup from another instance, or one made before backups recorded it,
+only goes into a new, empty instance, which takes it as it is.
+
+Before changing anything, the restore saves the current state as one more
+backup. It goes to the backup destination when scheduled backups are on, and
+otherwise to `/data/pre-restore`. The result says which file it is, so a
+restore can itself be undone.
+
+What a backup doesn't carry stays as it is wherever its owner survives the
+restore: API keys, forge connections, sharing, logs, and the destination's S3
+secret. The trash isn't in backups, so anything in the trash when the backup
+was taken is gone afterwards. Everyone is signed out, and search is rebuilt.
+
+### From the web
+
+**Settings → Data → Restore from Backup** lists the backups at the backup
+destination. You can pick one of those, or upload a `.tar` or the JSON
+**Full Backup** download (uploads are held to the server's request-size
+limit). The restore then shows what would change: when the backup was taken,
+and how many accounts, projects, plans, notes and rules there are now and will
+be afterwards. Type `roll back` to run it. Then sign in again.
+
+To read backups back from an S3 bucket, the key needs read access as well as
+write. Grimoire never deletes from the bucket.
+
+### From the command line
+
+For a file with no size limit, or a new instance with no backup destination
+yet, copy the file into the container and run:
+
+```sh
+docker exec -it grimoire python -m grimoire.restore /backups/grimoire-20261015T020000Z.tar
+```
+
+It prints what would change and stops. Add `--yes` to restore. It reads the
+JSON download too. Afterwards, **restart Grimoire** so the search indexes are
+rebuilt.
+
+After restoring into a new instance, issue new API keys, add forge connections
+again, and set up any sharing: none of them travel in a backup.

docs/configuration.md

@@ -1,149 +1,129 @@
 # Configuration
 
-Configuration is via environment variables. The `docker-compose.yml` file sets defaults for local development; override them in a `.env` file (gitignored).
+Grimoire reads its configuration from environment variables. Most settings people change day to day (registration, SMTP, retrieval thresholds, backups, forge connections) live in **Settings** in the web UI instead.
 
-## Environment Variables
+Any variable marked *secret* can also be read from a file: set `<NAME>_FILE` to the path, for example a Docker secret at `/run/secrets/grimoire_key`.
+
+## Environment variables
 
 ### Core
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DATABASE_URL` | `postgresql+asyncpg://fabled:fabled@db/scribe` | PostgreSQL async connection string |
-| `SECRET_KEY` | `dev-secret-change-me` | Session signing key — **change this in production** |
-| `SECRET_KEY_FILE` | — | Path to a Docker secret file containing the key (alternative to `SECRET_KEY`) |
-| `LOG_LEVEL` | `INFO` | Logging verbosity (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
-| `SECURE_COOKIES` | `false` | Set `true` when running behind TLS |
-| `BASE_URL` | — | Public URL (e.g. `https://notes.example.com`) — required for OIDC redirect URIs and email links |
+| `DATABASE_URL` *(secret)* | `postgresql+asyncpg://grimoire:grimoire@localhost:5432/grimoire` | PostgreSQL connection string, using the `asyncpg` driver |
+| `SECRET_KEY` *(secret)* | kept in `DATA_DIR` | Signs sessions and seals stored credentials. Unset, the instance makes its own on first start and keeps it in `DATA_DIR/secret_key`. Set it only to manage the key yourself; it wins over the kept one (see below) |
+| `DATA_DIR` | `/data` | Where the instance keeps its own `SECRET_KEY`. Mount a volume here |
+| `BASE_URL` | `http://localhost:5000` | Public URL, used in email links and OIDC redirects |
+| `TRUSTED_PROXY_HOPS` | `1` | The starting count of reverse proxies in front of Grimoire. **Settings → Config → Reverse proxy** is where the count is checked and set, and a count saved there wins over this. The client address and the scheme are read that many entries in from the right of `X-Forwarded-For` and `X-Forwarded-Proto`; `0` ignores both headers. See [Behind a reverse proxy](#behind-a-reverse-proxy) |
+| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING` or `ERROR` |
+| `LOG_RETENTION_DAYS` | `90` | Days of app logs to keep |
+| `FASTEMBED_CACHE_DIR` | `/data/fastembed-cache` | Where the embedding model is stored after its first download |
 
-### LLM / Ollama
+### Sign-in
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `OLLAMA_URL` | `http://ollama:11434` | Ollama API base URL |
-| `OLLAMA_MODEL` | `llama3.2` | Default LLM model (used as fallback; per-user setting overrides this) |
-| `EMBEDDING_MODEL` | `nomic-embed-text` | Model used for semantic search / RAG embeddings |
-| `OLLAMA_NUM_CTX` | `16384` | Context window size passed to Ollama for all generation calls |
-
-### Authentication / OIDC
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LOCAL_AUTH_ENABLED` | `true` | Set `false` to disable local username/password login (SSO-only mode) |
-| `OIDC_ISSUER` | — | OIDC issuer URL (e.g. `https://auth.example.com/application/o/fabled/`) |
+| `LOCAL_AUTH_ENABLED` | `true` | `false` turns off username/password login, leaving SSO only |
+| `OIDC_ISSUER` | — | OIDC issuer URL |
 | `OIDC_CLIENT_ID` | — | OIDC client ID |
-| `OIDC_CLIENT_SECRET` | — | OIDC client secret |
-| `OIDC_CLIENT_SECRET_FILE` | — | Docker secret file alternative to `OIDC_CLIENT_SECRET` |
-| `OIDC_SCOPES` | `openid profile email` | Space-separated OIDC scopes to request |
+| `OIDC_CLIENT_SECRET` *(secret)* | — | OIDC client secret |
+| `OIDC_SCOPES` | `openid profile email` | Scopes to request |
 
-See [sso-oauth.md](sso-oauth.md) for provider-specific setup.
+SSO turns on when the issuer, client ID and secret are all set. See [SSO / OAuth](sso-oauth.md).
 
-### Security / Proxy
+### Email
+
+Admins can set SMTP in **Settings**; these are the defaults until they do.
+
+| Variable | Default |
+|----------|---------|
+| `SMTP_HOST` | — |
+| `SMTP_PORT` | `587` |
+| `SMTP_USERNAME` | — |
+| `SMTP_PASSWORD` *(secret)* | — |
+| `SMTP_FROM_ADDRESS` | — |
+| `SMTP_FROM_NAME` | `Fabled Grimoire` |
+| `SMTP_USE_TLS` | `true` |
+
+### Integrations
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TRUST_PROXY_HEADERS` | `false` | Set `true` when behind a trusted reverse proxy to read real IP from `X-Forwarded-For` / `X-Real-IP` |
+| `PLUGIN_MARKETPLACE_URL` | this repo's git URL | The git URL shown in the plugin install command under Settings → MCP Access. An admin can override it in Settings |
+| `FORGE_KIND`, `FORGE_BASE_URL`, `FORGE_TOKEN` *(secret)* | — | A git forge connection for admins' projects, so a token can live in a Docker secret. Each user can add their own under Settings → Integrations; a stored connection for the same host wins |
+| `FORGE_WEBHOOK_SECRET` *(secret)* | — | Verifies push webhooks from the forge |
+| `SEARXNG_URL` | — | A SearXNG instance, listed as the web-search backend under Settings → Integrations |
 
-### Web Search / Images
+## Running it
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SEARXNG_URL` | — | SearXNG base URL for web search and image search tools |
-| `IMAGE_CACHE_DIR` | `/data/images` | Directory for cached search images |
-| `IMAGE_MAX_BYTES` | `5242880` (5 MB) | Maximum size for cached images |
+### Docker Compose
 
-### Data / Logging
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LOG_RETENTION_DAYS` | `90` | Days to keep app logs before automatic pruning |
-| `DATA_DIR` | `/data` | Root directory for persistent data (VAPID keys, backups) |
-
-## Docker Compose Setup
-
-### Development (`docker-compose.yml`)
+[`docker-compose.yml`](../docker-compose.yml) runs the published image with its own database, and needs nothing set:
 
 ```bash
-# Copy the example env file
-cp .env.example .env
-# Edit .env to set a real SECRET_KEY
-
-# Start the stack
-docker compose up --build
-
-# App available at http://localhost:5000
+docker compose up -d
 ```
 
-The first user to register becomes admin. Registration auto-closes after that (re-enable from Settings → Users).
+Open `http://localhost:5000`. The first account registered becomes the admin; after that, registration stays closed until an admin opens it in Settings or sends an invite.
 
-### Production (`docker-compose.prod.yml`)
+Update with `docker compose pull && docker compose up -d`. The key and the data stay in their volumes.
 
-The production compose file adds:
-- Docker Secrets for `SECRET_KEY_FILE` and `DATABASE_URL_FILE`
-- Network isolation (internal bridge for DB + Ollama; only the app is externally accessible)
-- Health checks and resource limits
+### From source
 
 ```bash
-# Create Docker secrets
-echo "$(python3 -c 'import secrets; print(secrets.token_hex(32))')" | docker secret create fabled_secret_key -
-echo "postgresql+asyncpg://fabled:strongpassword@db/scribe" | docker secret create fabled_db_url -
-
-# Deploy
-docker stack deploy -c docker-compose.prod.yml fabled
+docker compose -f docker-compose.dev.yml up --build
 ```
 
-## Production Deployment
+### Docker Swarm
 
-### Reverse Proxy (Required)
+[`docker-compose.prod.yml`](../docker-compose.prod.yml) is a stack file: the app and database on a private overlay network, trusting one proxy (`TRUSTED_PROXY_HOPS: "1"`). A Swarm can move the app to another node, away from a node-local `/data` volume, so the stack sets its own key: provide `DB_PASSWORD` and `SECRET_KEY` in the environment (or mount a Docker secret and set `SECRET_KEY_FILE`):
 
-Fabled Assistant does **not** handle SSL/TLS. Run it behind a reverse proxy:
+```bash
+DB_PASSWORD=... SECRET_KEY=... docker stack deploy -c docker-compose.prod.yml grimoire
+```
 
-- **Nginx**, **Traefik**, or **Caddy** in front of the app container
-- Terminate TLS at the proxy; forward to port 5000
-- **Do not expose port 5000 directly to the internet**
-- Rate-limit auth endpoints: ≤ 5 req/min per IP on `/api/auth/login` and `/api/auth/register`
+The database user, database and volume default to `grimoire`. An install created under the name Scribe keeps its data by setting `POSTGRES_USER`, `POSTGRES_DB` and `PGDATA_VOLUME` to the names it was created with.
+
+The shipped files leave out healthchecks and restart policies on purpose. The app waits for its database on startup, and the orchestrator's defaults restart it if it ever exits.
+
+### Volumes
+
+- **Database** (`pgdata`): everything Grimoire stores.
+- **App data** (`/data`): the instance's own `SECRET_KEY`, the embedding model cache and diagnostics. Losing it costs the key: Settings then asks for saved forge tokens and the backup secret again, and the model downloads again.
+
+Back up the database with **Settings → Data → Scheduled backups** ([Backups](backups.md)). A database backup doesn't carry the key; to move sealed credentials to a new instance, copy `/data/secret_key` with it.
+
+## Behind a reverse proxy
+
+Grimoire doesn't terminate TLS. Put it behind Nginx, Traefik or Caddy, forward to port 5000, and keep port 5000 off the internet. Set `BASE_URL`, then set the proxy count to the number of proxies a request passes through: one proxy is `1`, the default; Cloudflare's proxied DNS in front of your own proxy is `2`.
+
+**Settings → Config → Reverse proxy** sets the count and checks it against your own request. It shows the address Grimoire reads you as, and what each count from 0 to 3 would read. Pick the count that shows your own address. When a request comes through Cloudflare, the section names the count that reads the address Cloudflare reports, with a button that sets it. `TRUSTED_PROXY_HOPS` in the environment is only the starting value: a count saved in Settings wins, and **Use the environment's** goes back to it.
+
+A count that is too low makes every visitor read as the proxy, so they share one sign-in rate limit and a few bad sign-ins block everyone. The "too many attempts" message says so and points here. The block on sign-ins lifts after a minute; an admin who is already signed in can fix the count at once.
 
-Example Nginx location block:
 ```nginx
 location / {
     proxy_pass http://127.0.0.1:5000;
     proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto $scheme;
 
-    # Required for SSE streaming
+    # MCP responses can stream.
     proxy_buffering off;
     proxy_read_timeout 600s;
-    proxy_send_timeout 600s;
 }
 ```
 
-If using `TRUST_PROXY_HEADERS=true`, ensure your proxy strips any client-supplied `X-Forwarded-For` headers before adding its own.
+Each proxy appends its entry to `X-Forwarded-For` and `X-Forwarded-Proto`, so Grimoire reads the entry that many in from the right: the one your own proxy wrote. Whatever a client puts to the left of it is ignored. A header with fewer entries than that (a LAN road with one proxy beside a Cloudflare road with two) is read at its leftmost entry, the one the first proxy wrote.
 
-### Security Checklist
+When that entry says `https`, the session cookie is marked `Secure` and the response carries `Strict-Transport-Security: max-age=31536000`. Over plain HTTP neither is sent, and Grimoire never redirects to HTTPS, so a LAN install keeps working.
 
-- **Strong `SECRET_KEY`** — generate with:
-  ```bash
-  python3 -c "import secrets; print(secrets.token_hex(32))"
-  ```
-  Or use Docker Secrets via `SECRET_KEY_FILE`.
-- **`SECURE_COOKIES=true`** — must be set when running behind TLS.
-- **`BASE_URL`** — set to your public URL; required for OIDC redirects and email links.
-- **Registration** — auto-closes after the first user (admin). Re-enable from Settings → Users or send invite links.
-- **Session invalidation** — changing or resetting a password bumps `session_version`, evicting all other active sessions. Button also available in Settings → Account.
-- **Keep Ollama on an internal network** — both compose files keep Ollama off the host network. Never expose the Ollama port publicly.
-- **Default SECRET_KEY warning** — the app logs a `WARNING` on startup if the default dev key is in use.
+A hop count higher than the real number of proxies lets a client choose its own address, so count them. With `0`, the headers are ignored and the socket peer is the client: use it when clients reach port 5000 directly.
 
-## Model Management
+## Security checklist
 
-Models are managed through Settings → General → Model Management in the web UI. You can:
-- Pull new models by name (streams progress via SSE)
-- View installed models with size and loaded/unloaded state
-- Delete unused models
-
-The app auto-warms user-preferred models on startup (only models already installed — never auto-pulls). The embedding model (`nomic-embed-text`) is auto-pulled on startup if missing.
-
-Recommended models for 2× 8 GB GPU:
-- **`qwen3:8b`** — strong reasoning + tools, fits in 8 GB, supports thinking mode
-- **`qwen2.5:7b`** — fast, tool-capable, smaller context
-- **`llama3.1:8b`** — reliable baseline, widely tested with tools
+- **Keep the key.** Forge tokens and the backup destination's S3 secret are sealed under a key derived from `SECRET_KEY`, so a copy of the database alone can't read them. Unset, the instance makes a random key and keeps it in `/data/secret_key`, readable by its owner only; keep that volume. If the key changes (say, a restore onto an instance with a different key), Settings marks those credentials and asks for them again; nothing else breaks. The app warns at startup when `SECRET_KEY` is a public placeholder or `/data` is not a mounted volume, and refuses to start with a placeholder key (`dev-secret-change-me`, `change-me-in-production`).
+- **The proxy count** (Settings → Config → Reverse proxy) matches the number of proxies in front of Grimoire, so rate limits and the audit log see the real client and the cookie is `Secure` over HTTPS. The section shows whether it does.
+- **Registration** is open only for the first account. Invite people, or open it briefly from Settings.
+- **Signing everyone else out**: changing a password ends that user's other sessions; Settings → Account has a button for it too.
+- **API keys** are per user, shown once, and can be read-only. Revoke any you no longer use under Settings → MCP Access.

docs/design-system.md

@@ -53,7 +53,7 @@ Parchment is intentionally not pure white — it's slightly warm to feel like ag
 | Bronze | `#8B7355` | Secondary action buttons (Cancel-but-not-destructive, alternate paths) |
 | Pewter | `#3F4651` | Tertiary/ghost buttons |
 
-**Critical rule:** Action button colors are universal across all apps. A Save button in Scribe and a Save button in Minstrel look identical. Per-app accents do not appear on buttons.
+**Critical rule:** Action button colors are universal across all apps. A Save button in Grimoire and a Save button in Minstrel look identical. Per-app accents do not appear on buttons.
 
 ### Semantic colors
 
@@ -71,7 +71,7 @@ Parchment is intentionally not pure white — it's slightly warm to feel like ag
 
 | App | Hex | Mood |
 |---|---|---|
-| Fabled Scribe | `#5B4A8A` | Dusty violet — ink, manuscripts |
+| Fabled Grimoire | `#5B4A8A` | Dusty violet — ink, manuscripts |
 | Minstrel | `#4A6B5C` | Forest teal — music, performance |
 | Fabled Forge | `#8B5A2B` | Forge bronze — creation, craft |
 | Roundtable | `#4A5D7E` | Slate blue — stewardship, infrastructure |
@@ -80,7 +80,7 @@ Parchment is intentionally not pure white — it's slightly warm to feel like ag
 **Accent usage rules:**
 - The accent appears on the app's wordmark and icon.
 - The accent indicates active/current state in nav (the selected page, the active tab).
-- The accent is the cursor color and text-selection color in long-form surfaces (Scribe notes, Forge story drafts).
+- The accent is the cursor color and text-selection color in long-form surfaces (Grimoire notes, Forge story drafts).
 - The accent does NOT appear on primary or secondary action buttons.
 - The accent does NOT appear in body text or chrome.
 - One accent per app. Don't mix accents within a single app.
@@ -101,6 +101,8 @@ All text-on-surface combinations meet WCAG AA at minimum. Parchment on Obsidian
 | Inter | Body, UI, labels | Google Fonts |
 | JetBrains Mono | Code, terminal output, monospaced data | Google Fonts |
 
+All three are served by the app itself, from `frontend/src/assets/fonts/`, with every subset Google Fonts publishes for them. A page never asks a font host for anything, so an instance with no internet still draws in its own type. They are under the SIL Open Font License; the licences sit beside the files.
+
 ### Why this pairing
 
 Fraunces is a contemporary serif with personality — it has the warmth and authority of a book serif without feeling like costume. It signals "this is considered" without signaling "this is a fantasy product." Inter is the workhorse — neutral, ubiquitous, designed for screens, doesn't compete with the serif. JetBrains Mono is the natural choice for any developer-adjacent product and supports ligatures.
@@ -124,7 +126,7 @@ Fraunces is a contemporary serif with personality — it has the warmth and auth
 - **Sentence case everywhere.** Never Title Case for headings, never ALL CAPS except for the Tiny micro-label style.
 - **Two weights only:** 400 regular and 500 medium. Never 600 or 700 — they read heavy in dark mode.
 - **Fraunces only at 18px and above.** Below that it loses too much detail and feels fragile. For h3 and below, use Inter.
-- **Line height** 1.5 for body, 1.3 for headings, 1.7 for long-form reading surfaces (Scribe notes, Forge drafts).
+- **Line height** 1.5 for body, 1.3 for headings, 1.7 for long-form reading surfaces (Grimoire notes, Forge drafts).
 - **Letter-spacing** at default for everything except the Tiny micro-label, which gets `0.08em` letter-spacing and uppercase styling.
 
 ---
@@ -173,7 +175,7 @@ Padding: `8px 16px` for default, `6px 12px` for compact, `10px 20px` for promine
 
 Used for tags, hashtags, code spans, status badges. Background is the accent color at ~15% opacity, text is the accent at full strength. Border-radius 4px, padding `2px 8px`, Inter 11px/500.
 
-In Scribe specifically, hashtags and tags use the dusty violet accent. In Minstrel, they'd use forest teal. The pattern is shared; the color follows the app.
+In Grimoire specifically, hashtags and tags use the dusty violet accent. In Minstrel, they'd use forest teal. The pattern is shared; the color follows the app.
 
 ### Cards
 
@@ -272,9 +274,9 @@ Use **Lucide** (https://lucide.dev) as the base icon set — it matches this sty
 
 ## Per-app application
 
-### Fabled Scribe (#5B4A8A — dusty violet)
+### Fabled Grimoire (#5B4A8A — dusty violet)
 
-A second-brain notes and task management tool. The accent appears in: the wordmark, hashtags and tag pills, the active nav item, text selection color, and the cursor in the editor. Notes are presented on Iron-surfaced cards with generous reading line-height. The hashtag system uses Scribe's accent for visual continuity.
+A second-brain notes and task management tool. The accent appears in: the wordmark, hashtags and tag pills, the active nav item, text selection color, and the cursor in the editor. Notes are presented on Iron-surfaced cards with generous reading line-height. The hashtag system uses Grimoire's accent for visual continuity.
 
 ### Minstrel (#4A6B5C — forest teal)
 
@@ -332,7 +334,7 @@ Home server management. The accent appears on: the wordmark, healthy/online stat
 }
 
 /* Per-app accent — set ONE of these on the root for each app */
-[data-app="scribe"]    { --fs-accent: #5B4A8A; }
+[data-app="grimoire"]    { --fs-accent: #5B4A8A; }
 [data-app="minstrel"]  { --fs-accent: #4A6B5C; }
 [data-app="forge"]     { --fs-accent: #8B5A2B; }
 [data-app="roundtable"]{ --fs-accent: #4A5D7E; }
@@ -354,220 +356,13 @@ If using Tailwind, extend the theme with these tokens rather than relying on def
 
 ---
 
-*Last updated: April 25, 2026. Iterate as the family of apps grows.*
+# Grimoire
 
----
+The design system Grimoire renders with is stored in Grimoire itself: **Grimoire**, which inherits **FabledSword**, edited at `/design-systems`. `frontend/src/assets/theme.css` is generated from it, and CI rejects a `var()` the sheet doesn't define. Where this page and the stored system differ, the stored system is right. Grimoire applies the baseline above with these choices:
 
-# Scribe-specific decisions in progress
-
-> This section tracks decisions made while adapting the FabledSword baseline above for Scribe specifically. Items here are *in progress* — once they feel solid, they get folded into the main body of the document (either as Scribe-specific extensions in the per-app section, or as updates to the universal rules where Scribe's needs reveal a gap in the baseline).
-
-*Iteration started: 2026-04-26. Foundation pass shipped 2026-04-27 in `7a9a8b7` (palette, fonts, light mode, action tokens, hardcoded indigo cleanup, warm-gold deprecation). Surface phase shipped 2026-04-27 across `93a3beb` → `3c1ec40` (Lucide migration, Hybrid-rule button reclassification per surface, long-form line-height, two-weights-only). The system is now applied end-to-end; this section will fold into the main body once the result has had time to settle in real use.*
-
-## Decisions made so far
-
-### Accent footprint — Hybrid rule (not Strict)
-
-The doc baseline says the per-app accent only appears on wordmark, active nav, cursor, and text selection — never on action buttons. Scribe currently uses indigo on essentially every interactive surface (CTAs, scrollbars, glows, borders, focus rings). Hard-cutting to the doc baseline would lose too much identity in one swing.
-
-**Hybrid rule:** the accent reserves a slightly larger footprint than the doc baseline, but still much smaller than today.
-
-- **Accent (dusty violet) lives on:** wordmark; active nav; cursor and text selection in editor surfaces; tags/pills/wikilinks; in-progress task badge; focus rings; **brand-moment CTAs** — chat Send, "Create note" empty-state CTA, journal Send, "Start journaling" empty-state.
-- **Moss (sage-green primary) lives on:** Save / Submit / Confirm in forms and modals; generic affirmative actions where the button just means "do this thing" with no brand pretense.
-- **Bronze (secondary):** Cancel-but-not-destructive, alternative paths.
-- **Oxblood (destructive):** Delete / Remove (paired with an icon).
-- **Pewter ghost:** tertiary actions, "later", "skip", "see also".
-
-**Rule of thumb:** if the user is engaging with a *Scribe-feature moment* (sending a chat, opening a fresh note, jumping into the journal), accent. If they're just *operating the software* (saving an edit, confirming a dialog), Moss.
-
-### Light mode — warm parchment, matched aesthetic
-
-The doc is dark-only. Scribe today supports both light and dark, and we keep both. The light mode is derived to *match* the dark mode aesthetic rather than defaulting to system white-and-ink.
-
-- Page background: in the `#F5F1E8` warm cream family (specific values TBD)
-- Cards: near-white but slightly tinted
-- Text: deep ink `#14171A` (mirroring Obsidian)
-- Accent: same dusty violet `#5B4A8A` (works on both themes)
-
-The metaphor stays consistent across themes: ink on aged paper (light) ↔ parchment text on graphite (dark). Light mode is *not* the system standard look.
-
-**Known downside:** warm parchment backgrounds can fight with embedded color content. Mitigation: code blocks get a slight cool wash in light mode specifically, to keep syntax highlighting readable.
-
-### Status and priority palette — extend the doc's semantic set
-
-The doc's semantic colors (Success / Warning / Error / Info / Destructive) are leaner than what Scribe needs for task management. Rather than running a parallel palette, Scribe extends the doc by mapping its status/priority tokens onto doc primitives where they fit and defining new app-level tokens for the rest.
-
-**Status (task lifecycle):**
-
-| Token | Color | Source | Logic |
-|---|---|---|---|
-| `status-todo` | Pewter `#3F4651` | doc | Neutral, "not started yet" |
-| `status-in-progress` | dusty violet `#5B4A8A` | accent | Active = brand moment per Hybrid |
-| `status-done` | Moss `#4A5D3F` | doc Success | Affirmative completion |
-| `status-cancelled` | Ash `#9C9A92` | doc | Faded, "let go" |
-| `status-paused` | Warning `#8B6F1E` | doc | Stalled, needs attention — replaces the old warm gold treatment |
-
-**Priority (loudness scale):**
-
-| Token | Color | Source | Logic |
-|---|---|---|---|
-| `priority-low` | Info `#3D5A6E` | doc | Cool, FYI — quietest end of the spectrum |
-| `priority-medium` | Warning `#8B6F1E` | doc | Golden, mid-attention |
-| `priority-high` | Error `#C04A1F` | doc | Terracotta, urgent |
-| `priority-none` | Vellum/Ash | doc | No signal |
-
-The priority row reads as a clean cool→warm gradient (slate blue → golden brown → terracotta), which matches the semantic loudness — coherence the current ad-hoc palette doesn't have.
-
-**Other functional tokens:**
-
-| Token | Color | Logic |
-|---|---|---|
-| `wikilink` | dusty violet | Editorial brand moment per Hybrid |
-| `overdue` | Error `#C04A1F` | Same as priority-high — overdue IS a priority signal |
-| `toast-success` | Moss | doc semantic |
-| `toast-error` | Error | doc semantic |
-| `toast-info` | Info | doc semantic |
-| `tag-bg` / `tag-text` | accent at 15% / accent | Per doc pill recipe |
-
-Each token gets a `*-bg` companion at low alpha (matching the existing pattern in `theme.css`).
-
-**Removed:** the warm gold accent (`--color-accent-warm: #b8860b`). Its two jobs split:
-
-- Dates and timestamps (knowledge cards, event details, chat) → use `text-secondary` instead. Dates are metadata, not a brand surface; muted is the correct register.
-- Paused project status → use the new `status-paused` (Warning `#8B6F1E`) row above. Same golden-brown family, semantically aligned.
-
-### Typography — adopt the doc's stack and scale
-
-Adopt the doc's type stack and scale verbatim, with one deferred verification (long-form line-height in practice).
-
-- **Body font: Inter.** Replaces Scribe's current system-stack body font. Doc-defined; no Scribe-specific divergence.
-- **Type scale:** as in the doc table — Display 40 / H1 32 / H2 24 / H3 18 / Body 15 / Body small 13 / Label 12 / Code 13 / Tiny 11.
-- **Two weights only:** 400 regular, 500 medium. No 600/700 (reads heavy in dark mode and against the muted palette).
-- **Family rules:** Fraunces at 18px+ only (Display, H1, H2). H3 and below = Inter. Code = JetBrains Mono.
-- **Line height:** 1.5 body, 1.3 headings, **1.7 for long-form reading surfaces** (notes, journal entries).
-- **Sentence case for everything**, except the Tiny micro-label style which gets uppercase + 0.08em letter-spacing.
-
-Mechanical rollout — value swaps in `theme.css` plus loading Inter and JetBrains Mono from Google Fonts (Fraunces is already loaded).
-
-### Light mode — concrete palette
-
-Fills in the warm-parchment direction picked earlier. Treat these as starting values; tune in practice.
-
-| Token | Hex | Role |
-|---|---|---|
-| Page bg | `#F5F1E8` | Warm cream — the "paper" |
-| Card bg | `#FBF8F0` | Near-white, slightly warm — raised surfaces |
-| Inset bg (inputs, code) | `#EFEAE0` | Slightly darker than page, "inset" feeling |
-| Text primary | `#14171A` | Deep ink — Obsidian inverted |
-| Text secondary | `#5A5852` | Warm mid-grey |
-| Text muted | `#9A9890` | Warm light grey for hints/metadata |
-| Border default | `#D9D6CE` | Warm light pewter, hairline weight |
-
-**Code-block exception:** in light mode specifically, code blocks use a slight cool wash (e.g. `#EBEDF0`) instead of the warm inset bg, so syntax highlighting reads cleanly. This is the mitigation for the "warm bg fights colored content" downside.
-
-The accent (`#5B4A8A` dusty violet), Moss, Bronze, Oxblood, and the semantic color set are **identical across themes** — only the surface and text palettes flip.
-
-### Chat-bubble codification — keep the Illuminated Transcript pattern
-
-The existing chat-bubble pattern (informally called "Illuminated Transcript") gets written into the design system as a documented chat component. Other apps in the family that add a chat surface inherit the pattern; Scribe's existing implementation continues to work with only color shifts.
-
-**User bubble (whisper):**
-- Background: transparent
-- Border: 0.5px Pewter (was: indigo-tinted)
-- Text color: secondary (Vellum dark / `#5A5852` light)
-- Right-aligned, rounded except bottom-right (subtle "from-me" tail)
-
-**Assistant bubble (lit):**
-- Background: card surface (Iron dark / `#FBF8F0` light)
-- Border: none on top/right/bottom; **2px solid accent (dusty violet) on left edge only**
-- Box-shadow: accent-tinted glow + standard depth shadow (formula: `0 4px 28px rgba(<accent>, 0.14), 0 2px 8px rgba(0,0,0,0.4)` in dark; lower alphas in light)
-- Text color: primary (Parchment dark / Obsidian-inverted light)
-- Left-aligned, rounded except bottom-left
-
-The 2px-accent left edge is the "illumination" — like an illuminated capital in a manuscript. The shadow is the lift. Together they make the assistant bubble read as the *primary* voice, while the user bubble is the *margin note*.
-
-**Inline tool-call cards (`ToolCallCard`)** rendered inside an assistant bubble do NOT get their own border (per the border philosophy — the bubble already contains them). They use a slight surface tint to differentiate.
-
-### Iconography — adopt Lucide, enforce a scale
-
-Scribe currently hand-inlines SVG paths in 16+ Vue files, with 5 different stroke weights and 8+ different sizes. The visual style is already outline + rounded caps + `currentColor` stroke (matches the doc's intent), but there's no shared source and no scale discipline.
-
-**Migration policy:**
-
-1. **Install `lucide-vue-next`** as the icon source. Replace hand-inlined SVGs with imported components. Single source of truth.
-2. **Strict size scale: 16px and 24px only.** Today's mix of 12/13/14/15/17/18/20 collapses to those two. 16 for inline-with-text and small affordances; 24 for nav and primary actions.
-3. **Stroke weight per the doc: 1.5 at 24px, 1 at 16px.** Lighter than the current default of 2 — reads more refined, matches the muted palette philosophy. Overrides Lucide's default.
-4. **Outline by default; filled only for active/selected state.** Introduces a new affordance Scribe doesn't currently use — bookmark/pin/star icons can switch outline → filled to indicate active state. Reserve filled style strictly for this.
-5. **No emoji in chrome.** Replace the 3 files' emoji usage in UI labels/buttons/badges/empty states with Lucide equivalents. Emoji remain fine in *user content* (note bodies, chat messages the user typed).
-
-Work cost: ~30-60 individual icon swaps across the 16 files. Mechanical; doesn't require redesign of any component.
-
-### Voice and tone — adopt principles, defer formal audit
-
-The doc's voice register applies to Scribe (understated mythic — plain for functional UI, flavored for empty/error/loading states). No formal sweep of every UI string yet.
-
-**Approach:** apply the voice opportunistically as components are touched in the polish pass — when redesigning a settings tab, an empty state, or an error toast, rewrite the copy at the same time using the doc's register and examples table as the guide. A standalone audit pass is deferred unless drift becomes visible.
-
-### Border philosophy — structural, not decorative
-
-The doc treats borders as *structural* (Pewter neutral hairlines that say "boundary"), not decorative (Scribe today uses indigo-tinted borders that say "branded edge"). That principle suggests removing borders in places where surface tint and spacing already communicate separation.
-
-**Borders to remove:**
-
-- List rows (NotesListView, TasksListView, conversation history) — surface contrast + spacing should separate rows; current border reads as "boxed-in"
-- Inline `ToolCallCard` inside chat bubbles — the bubble is already a container; an extra border feels like double-wrapping
-- Filter chips and search-bar pills with a background tint — background does the work
-- Empty-state callouts with dashed/bordered "nothing here yet" boxes — tinted background reads cleaner
-
-**Borders to keep (genuinely structural):**
-
-- Standalone card containers (Notes viewer, Task viewer, the new daily prep card)
-- Modal / dialog edges
-- Code blocks (separates content type, not just space)
-- Focus rings (accessibility)
-- Major section dividers within a panel
-
-Border weight is not load-bearing for Scribe — happy to use the doc's 0.5px hairline default; the *placement* discipline matters more than the weight.
-
-## Open threads (next iterations)
-
-### Foundation pass — shipped 2026-04-27 (`7a9a8b7`)
-
-Mechanical token + font + light-mode rewrite of `frontend/src/assets/theme.css`, plus a sweep of hardcoded indigo and `--color-accent-warm` references across ~14 component files. Action tokens (`--color-action-primary` Moss, `--color-action-secondary` Bronze, `--color-action-destructive` Oxblood, `--color-action-ghost-border` Pewter) are defined but not yet applied — buttons still flow through `--color-primary` and read as dusty-violet gradients in the meantime, by design. Spec lives at `docs/superpowers/specs/2026-04-27-design-system-polish-foundation-design.md` (gitignored, local-only).
-
-### Surface phase — shipped 2026-04-27 (`93a3beb` → `3c1ec40`)
-
-Bundled as Hybrid (option C from the brainstorm): Lucide cross-cutting first, then surface-by-surface for the judgment work. Spec lives at `docs/superpowers/specs/2026-04-27-design-system-polish-surface-design.md` (gitignored, local-only). Seven PRs landed on `dev`:
-
-| PR | Commit | Surface | Notes |
-|---|---|---|---|
-| 1 | `93a3beb` | Lucide cross-cutting | 60 hand-inlined SVGs across 15 files → `lucide-vue-next`. Every chrome icon at 16 or 24. Emoji-as-icons (`✕`, `✓`, `🎤`, `📎`, `↻`, `↑`, `&times;`, `☀`/`☾`) swept across the chrome. AppLogo wordmark and the GraphView D3 mount kept as the legitimate exceptions. |
-| 2 | `3d916d7` | Journal | Buttons audited; `↻` weather refresh → Lucide `RotateCcw`; assistant bubble line-height bumped; redundant `.journal-title` font-family dropped; dead `.news-section` CSS removed. |
-| 3 | `4192a64` | Chat | `.message-content` long-form 1.7 line-height on assistant bubbles; ToolCallCard outer border removed (bubble already contains it; error state moved to a left-edge accent); bulk-delete recolored to Oxblood with Trash2 icon; `.bulk-link` accent → muted text. |
-| 4 | `efb3534` | Knowledge cluster | `.prose` line-height bumped to 1.7 globally so all reading surfaces inherit. Save → Moss; Delete → Oxblood + Trash2; Edit / Advance → Moss; Convert / Share → Bronze. |
-| 5 | `ff498ce` | Project + Workspace | Project save panel → Moss; milestone confirm/cancel → Moss/Bronze; modal-btn-danger and per-row delete affordances → Oxblood; "Open Workspace" stays accent (project-surface brand moment). |
-| 6 | `541e2ed` | Settings | Densest button surface — every `.btn-save`, `.btn-primary`, `.btn-secondary`, `.btn-danger`, `.btn-danger-outline`, `.btn-toggle-open` reclassified per Hybrid; missing `.btn-danger` style block added (was unstyled before). |
-| 7 | `3c1ec40` | Edge surfaces | Calendar `New Event` → Moss; EventSlideOver Save/Cancel/Delete reclassified; HomeView hero CTA stays accent (brand moment); two-weights-only sweep across Header/Home/Calendar/Graph. |
-
-**Cross-cutting changes folded in as the work touched files:**
-
-- Long-form 1.7 line-height on `.prose` (PR 4) — applies to Note viewer, Task viewer, chat assistant bubbles, anywhere markdown renders into a reading surface.
-- Two-weights-only (400 + 500) — every `font-weight: 600` and `700` snapped to `500` across all surface PRs.
-- Hardcoded `--color-danger` in destructive button contexts → `--color-action-destructive` (Oxblood). `--color-danger` (Error terracotta) preserved for validation/error messages, per the doc's distinction between Error and Destructive.
-- Adjacent `&times;` / `✕` / unicode-arrow emoji swept opportunistically as files were touched (PRs 5, 7).
-
-### Out of scope — deferred indefinitely
-
-Items deliberately not addressed in this round; revisit when a real need surfaces:
-
-- Lucide stroke-weight overrides (doc spec: 1.5 at 24, 1 at 16; current: Lucide default 2). Touched components if they read too heavy in practice.
-- Filled-as-active icon state — no current affordance uses it; introduce when bookmark/pin/star toggles are added.
-- Type-scale / spacing-scale CSS variables — components keep literal values.
-- Token rename to `--fs-*` namespace — Scribe is the only FabledSword app sharing this codebase.
-- FabledSword lockup placement — waiting on the actual heraldic mark to be drawn.
-- Standalone voice/tone audit across every UI string — opportunistic-only; full sweep deferred unless drift becomes visible.
-- A handful of editor utility buttons (`.btn-suggest-tags`, `.btn-link-all`, AI assist generate/proofread/accept/reject set, etc.) — currently ghost-styled and visually compliant; revisited only if they read off in practice.
-
-### Open threads
-
-*New threads will accumulate here as gaps surface in real use.*
+- **Accent footprint.** Dusty violet marks Grimoire's own moments: the wordmark, active navigation, the editor's cursor and selection, tags and wikilinks, in-progress status, focus rings, and the call to action that starts something new (a first note, say). Operating the software uses the action colours: Moss to save or confirm, Bronze for alternatives, Oxblood with an icon to delete, Pewter ghost for tertiary actions.
+- **Light and dark.** Both are supported. Light mode is warm parchment (`#F5F1E8` page, `#FBF8F0` cards, `#14171A` text) rather than white, with a cool wash on code blocks so syntax colours stay readable. The accent, action and semantic colours are the same in both.
+- **Status and priority.** Status: todo Pewter, in progress the accent, done Moss, cancelled Ash, paused Warning. Priority runs cool to warm: low Info, medium Warning, high Error. Overdue uses Error. Each has a low-alpha `-bg` companion.
+- **Type.** Inter for UI and body, Fraunces at 18px and up (display, H1, H2), JetBrains Mono for code. Two weights only, 400 and 500. Line height 1.5 for body, 1.3 for headings, 1.7 on reading surfaces such as a note.
+- **Icons.** Lucide, at 16px inline and 24px for navigation and primary actions; no emoji in the interface.
+- **Borders are structural.** Cards, dialogs, code blocks, focus rings and major dividers get borders; list rows, chips and empty states are separated by surface tint and spacing instead.

docs/development.md

@@ -1,179 +1,87 @@
 # Development
 
-## Workflow
-
-All development is Docker-based. Do not install Python or Node dependencies locally.
+## Running it
 
 ```bash
-# Start the full stack (app + PostgreSQL + Ollama)
-docker compose up --build
+docker compose -f docker-compose.dev.yml up --build       # app + PostgreSQL at http://localhost:5000
+docker compose -f docker-compose.dev.yml up --build app   # rebuild after a change
+docker compose -f docker-compose.dev.yml down -v          # stop and wipe the database
+```
 
-# Rebuild after backend changes (frontend changes require rebuild too)
-docker compose up --build app
+The image builds the frontend, so a frontend change needs a rebuild too. For quicker frontend work, run Vite against the running app; it proxies `/api` to port 5000:
 
-# Reset everything (wipes database)
-docker compose down -v && docker compose up --build
+```bash
+cd frontend && npm ci && npm run dev   # http://localhost:5173
+```
 
-# Run checks (lint, format, typecheck, tests)
-make check
+## Checks
 
-# Individual checks
+CI runs these on every push; locally they need `uv sync --extra dev` and `cd frontend && npm ci`.
+
+```bash
 make lint        # ruff check src/
-make fmt         # ruff format src/
 make typecheck   # vue-tsc --noEmit
 make test        # pytest tests/
+make check       # all three
 ```
 
-## Frontend Hot Reload
+Unit tests run without a database. Tests marked `integration` need a real PostgreSQL and run in CI's integration job, against a schema built by the real migrations.
 
-The Docker setup does not include Vite's hot-reload dev server. After frontend changes, rebuild the image. For faster iteration during active frontend work, you can run Vite locally:
+## Database migrations
+
+The container runs `alembic upgrade head` on every start, after waiting for the database to accept connections.
 
 ```bash
-cd frontend
-npm install
-npm run dev   # Vite dev server at http://localhost:5173
+docker compose -f docker-compose.dev.yml exec app alembic revision -m "short_description"
 ```
 
-Point the Vite dev server at the backend by setting `VITE_API_BASE_URL=http://localhost:5000` (or configure `vite.config.ts` proxy).
+- Number revisions sequentially (`0123_...`). Revision ids must fit in 32 characters, the width of `alembic_version.version_num`.
+- Write both `upgrade()` and `downgrade()`.
+- Adding a value to a `CHECK`-constrained column means dropping and re-adding the constraint in the same migration.
+- Keep migrations to schema changes. Filling a derived table from a large one belongs in a background backfill after startup, where its cost doesn't hold up the boot.
+- A migration that depends on application code (a key derivation, a serialiser) copies what it needs rather than importing it, so a later edit can't change what an old migration does.
 
-## Database Migrations
+## The plugin
 
-Alembic migrations run automatically on container startup (`alembic upgrade head` in the `CMD`).
+`plugin/` ships straight from git: installs fetch it through `.claude-plugin/marketplace.json`, and there is no build step. After changing anything under `plugin/` or `.claude-plugin/`, run `make mint-plugin` before committing. Claude Code only refreshes an installed plugin when its version changes, and CI fails a plugin change that didn't bump it.
 
-To create a new migration:
-```bash
-# Inside the running app container
-docker compose exec app alembic revision -m "description_of_change"
-# Edit the generated file in alembic/versions/
-```
+The hooks must run on a bare machine: POSIX shell, awk, sed and the usual coreutils, plus `git` and `curl`. They fail open, so a slow or unreachable Grimoire never blocks Claude Code.
 
-Migration conventions:
-- Use raw SQL with `IF NOT EXISTS` guards for idempotency
-- Use `DO $$ BEGIN CREATE TYPE … EXCEPTION WHEN duplicate_object THEN NULL; END $$` for enum types
-- Number migrations sequentially (e.g. `0027_add_something.py`)
-- Always provide both `upgrade()` and `downgrade()`
+## CI and releases
 
-## CI/CD
+CI runs on Gitea Actions (workflow in `.forgejo/workflows/ci.yml`) in the shared `ci-python:3.14` image ([`ci-requirements.md`](../ci-requirements.md) lists what it relies on). Six jobs: TypeScript typecheck, plugin hooks, Python lint (plus design-token and dangling-style checks), unit tests, integration tests, and the image build, which waits on all of them except the plugin job.
 
-### Pipeline
+| Push | Image tags |
+|------|-----------|
+| `dev` | `:dev`, `:<sha>` |
+| `main` | `:latest`, `:<sha>` |
+| a `v*` tag | `:latest`, `:<version>`, `:<sha>` |
 
-CI runs on Forgejo Actions, consuming the shared
-[`ci-python:3.14`](https://git.fabledsword.com/bvandeusen/CI-runner) image
-via `container.image` (Python 3.14 + Node 24 + ruff + uv + Docker CLI):
+`:<sha>` never moves, so it is the rollback point. Images publish to `git.fabledsword.com/bvandeusen/fabledgrimoire`, with a registry layer cache at `:cache`. The build needs the `REGISTRY_USER` and `REGISTRY_TOKEN` (a token with `write:packages`) repository secrets.
 
-| Trigger | Jobs | Docker tags pushed |
-|---------|------|--------------------|
-| Push to `dev` | typecheck + lint + test → build | `:dev`, `:<sha>` |
-| Tag `v*` on `main` | typecheck + lint + test → build | `:latest`, `:<version>`, `:<sha>` |
-| Push to `main` | typecheck + lint + test | (no build) |
+Work happens on `dev`. A release merges `dev` into `main` with a plain merge commit; a dated `vYYYY.MM.DD.HHMM` tag, matching the version the image reports, can mark it.
 
-### Release Process
-
-1. Work on `dev` branch — CI validates on every push
-2. When ready, open a PR from `dev` → `main` in Forgejo
-3. Merge the PR
-4. Create a release via the Forgejo UI on `main` with a `v*` tag (e.g. `v26.03.23.1` — CalVer: `YY.MM.DD.N`)
-5. The tag push triggers CI → build job pushes `:latest` + `:<version>` Docker images
-6. After merging to main, sync dev back:
-   ```bash
-   git checkout dev && git merge main && git push origin dev
-   ```
-
-### Runner
-
-CI jobs schedule against the `python-ci` runner label and run inside the
-shared `git.fabledsword.com/bvandeusen/ci-python:3.14` image (see
-`ci-requirements.md` for what this project relies on from the image).
-The runner deployment lives outside this repo; image bumps happen in
-[CI-Runner](https://git.fabledsword.com/bvandeusen/CI-runner) via Renovate.
-
-`infra/runner-compose.yml` + `infra/act-runner-config.yml` document the
-runner-host deployment shape; the source of truth is the deployed
-config on the runner host.
-
-### Docker Registry
-
-Images pushed to: `git.fabledsword.com/bvandeusen/scribe`
-Cache tag: `:cache` (reduces build time ~80%)
-
-Required secrets (repo → Settings → Secrets → Actions):
-- `REGISTRY_USER` — Forgejo username
-- `REGISTRY_TOKEN` — Forgejo PAT with `write:packages` scope
-
-## Migration Chain
-
-Current migration sequence (all idempotent raw SQL):
-
-```
-0001 create_notes_table
-0002 create_tasks_table
-0003 task_note_companion (data migration)
-0004 merge_tasks_into_notes
-0005 add_chat_tables
-0006 add_settings_table
-0007 add_title_and_updated_at_indexes
-0008 add_users_and_user_id
-0009 add_message_status
-0010 add_app_logs_table
-0011 add_password_reset_tokens
-0012 add_invitation_tokens
-0013 add_tool_calls_to_messages
-0014 add_note_embeddings
-0015 add_oauth_fields
-0016 add_image_cache
-0017 add_projects
-0018 add_push_subscriptions
-0019 add_events              (dead code — internal CalDAV/Radicale table; Radicale was removed)
-0020 add_milestones
-0021 add_task_logs
-0022 add_note_versions_and_drafts
-0023 add_tags_to_note_versions
-0024 add_session_version
-0025 add_sharing_and_notifications
-0026 add_briefing_tables
-0027 add_api_keys
-```
-
-**Important:** Do NOT use `op.create_table()` or `sa.Enum()` — SQLAlchemy's event system can fire `CREATE TYPE` even with `create_type=False`, causing failures on re-run. Always use raw SQL with `IF NOT EXISTS` / `DO $$ BEGIN ... EXCEPTION WHEN duplicate_object` guards.
-
-## Project Conventions
+## Conventions
 
 ### Backend
 
-- Services: `async with async_session() as session:` — import from `scribe.models`
-- No `scribe.database` module
-- Blueprint per resource: `routes/notes.py`, `routes/tasks.py`, etc.
-- All business logic in `services/`; routes are thin wrappers
-- Permission checks via `services/access.py` — never inline ownership checks in routes
+- Services open their own session: `async with async_session() as session:` (from `grimoire.models`).
+- Routes and MCP tools stay thin; the logic lives in `services/`, shared by both.
+- Access checks go through `services/access.py`, never inline ownership checks.
+- Every wait on something outside the process has a deadline.
 
 ### Frontend
 
-- API calls via `frontend/src/api/client.ts` typed helpers (`apiGet`, `apiPost`, `apiPatch`, `apiDelete`)
-- Pinia stores for shared state; local `ref()` for component-only state
-- Composables in `composables/` for reusable behaviour (autosave, keyboard nav, tag suggestions, …)
-- Views are page-level components in `views/`; reusable UI in `components/`
+- API calls go through the typed helpers in `frontend/src/api/client.ts`.
+- Pinia stores for shared state, `ref()` for state local to a component; composables for reusable behaviour.
+- Colours, spacing and type come from the design system's tokens in `theme.css`, which is generated, so CI rejects an unknown `var()`.
 
-### Commit Style
+### Commits
 
 ```
-type(scope): short description
+type(scope): what the change does
 
-Longer body if needed.
-
-Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+Why, and anything a reader tracing this change later needs.
 ```
 
-Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
-Scopes: feature area (e.g. `chat`, `journal`, `mcp`, `notes`)
-
-## Testing
-
-```bash
-# Run all tests
-make test
-
-# Run specific test file
-docker compose exec app /opt/venv/bin/pytest tests/test_auth.py -v
-```
-
-Tests are in `tests/`. They run against a real PostgreSQL instance in CI (not mocked). Keep tests integration-style where possible — mock failures have historically masked real migration bugs.
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`. Comments in the code describe how it works today; the history of a change belongs in its commit message.

docs/features.md

@@ -1,170 +1,132 @@
 # Features
 
-Scribe is a self-hosted work system-of-record for software projects, built to be
-driven by Claude Code. There is **no in-app LLM** — Claude is the sole assistant,
-reaching Scribe through a built-in MCP endpoint and a bundled Claude Code plugin. The
-web UI is a clean surface for humans to read and edit the same data.
+Grimoire is a self-hosted system of record for the work you do with Claude Code. Claude records what it learned, decided and built, and that record reaches the next session, so a solution is recalled rather than reinvented. There is no language model inside Grimoire: Claude reaches it through the MCP endpoint and the Claude Code plugin, and the web UI is where people read and edit the same records.
 
 ## Notes
 
-Write in Markdown with a live-preview editor (Tiptap/ProseMirror). Headings, bold,
-italic, lists, code blocks, and task checklists render inline. A slash-command menu
-(`/`) inserts common blocks.
+A Markdown editor (Tiptap) with headings, lists, code blocks and checklists inline, and a `/` menu for blocks.
 
-- **Wikilinks** — Link notes with `[[Title]]` or `[[Title|Display Text]]`. Clicking
-  navigates to (or auto-creates) the referenced note; the editor suggests existing
-  titles while you type `[[`. Backlinks appear in the note viewer sidebar.
-- **Tags** — First-class `ARRAY[text]` column with autocomplete. Hierarchical tags
-  (`area/backend`) supported — filtering by `area` matches all `area/*` children.
-- **Version history** — Every body edit snapshots a version (up to 20 per note).
-  Browse, diff, and restore from the editor's History panel.
-- **Draft recovery** — In-progress edits persist across page loads and are restored
-  when you reopen a note.
-- **Convert freely** — Turn a note into a task (sets `status=todo`) or back again.
+- **Wikilinks**: `[[Title]]` or `[[Title|text]]`, suggested as you type; backlinks show in the viewer.
+- **Tags**, with autocomplete. Hierarchical tags (`area/backend`) match their parent's filter.
+- **Version history**: browse, diff and restore earlier versions of a note.
+- **Draft recovery**: unsaved edits survive a reload.
 
-## Tasks and Issues
+## Tasks
 
-Tasks carry status (`todo` → `in_progress` → `done`/`cancelled`), priority
-(`none`/`low`/`medium`/`high`), due date, milestone assignment, and a parent task
-(sub-tasks). Notes and tasks share one model — a task is a note with a status.
+A task is a note with a status (`todo`, `in_progress`, `done`, `cancelled`), plus priority, due date, milestone and parent task.
 
-- **Work logs** — Append timestamped progress entries (with optional duration) to a
-  task without rewriting its body; shown chronologically in the task view.
-- **Issues** — A task whose `kind` is corrective: a problem you fixed or are fixing,
-  with symptom → root cause → fix in the body. An issue can link the task it arose
-  from and the System(s) it touches.
-- **Recurring tasks** — An interval or calendar recurrence rule spawns the next
-  occurrence when a task is completed (a background job drains due spawns).
-- **Sub-tasks** — Any task can have children via `parent_id`; the viewer shows them
-  inline.
+- **Kinds**: `work`; `issue`, for corrective work, which can link the task it arose from; and `spike`, a time-boxed investigation whose output is an answer.
+- **Work logs**: timestamped entries that record progress without rewriting the body. They are what the next session reads first.
+- **Claims**: a session that logs on a task holds it, so after a context compaction the work comes back to that session, and other sessions can see who is on it.
+- **Recurring tasks** spawn their next occurrence on a schedule.
 
-## Projects and Milestones
+## Projects, milestones and systems
 
-- **Projects** — Group related notes and tasks. Title, description, goal, status
-  (`active`/`paused`/`completed`/`archived`), and a colour.
-- **Milestones** — Ordered stages within a project. A milestone is also the home of a
-  **plan** — its body holds the design (Goal/Approach/Verification) and its child
-  tasks are the steps. Completion percentage is shown on the project page.
-- **Kanban view** — `/projects/:id` groups tasks by milestone in a column layout with
-  status-advance buttons on the cards.
+- **Projects** carry a goal, a status and a colour, and group everything else. Entering a project gives Claude a short primer: its goal, recent plans and their next steps, open tasks, its systems and its design system.
+- **Milestones are plans**: a body holding the design (goal, approach, verification) and ordered step tasks. Starting a plan that matches an active milestone hands back that milestone instead of opening a second one.
+- **Systems** are a project's named areas ("auth", "retrieval"). Records are tagged with them, each has a charter saying what belongs there, and each maps to a canonical area shared across projects.
+- **Duplicate gates**: creating a record that reads like an existing one returns the existing one to update instead.
 
-## Systems
+## Rules, lessons and moments
 
-A **System** is a per-project, reusable, self-describing subsystem or area (e.g.
-"auth", "billing"). Associate any note, task, or issue with a System so research,
-build-work, and fixes for the same area line up and recurring problem-spots surface.
+- **Rulebooks → topics → rules.** A rule in a rulebook applies in every project; a project rule applies only there. A project that departs from a global rule says so with an `overrides` relation.
+- **Rules arrive by retrieval.** Nothing is preloaded: a rule reaches a session when what Claude is about to do matches its trigger (`when_to_apply`), whether that's the operator's message, a command or a file being written.
+- **Moments**: a rule about *when* something is done (finishing a task, reporting back, pushing) can be mounted on a moment of work, and arrives whenever that moment happens, whatever the words look like. Settings → General shows which actions reach each moment.
+- **Versions and verification**: every edit to a rule keeps the text it replaced. A rule that asserts a fact about someone else's software can say how to check it and when it stops being true, and a sweep lists rules due for a check.
+- **Preferences** are rules with the force of guidance rather than obligation.
+- **Lessons** record something learned the hard way, keyed to the situation where it applies, and link to the rules they are instances of.
+- **Reply shapes**: the default shape of Claude's replies (completion report, plan for review, question) arrives at the moment it applies. Settings → General shows them.
 
-## Rules and Rulebooks
+## Snippets and the shape ledger
 
-Scribe stores the operator's engineering and workflow **rules** so Claude follows them
-across sessions.
+- **Snippets** are recorded prior art: a reusable piece of code with when to reach for it, its signature and its canonical location in a repo. Claude searches them before building and is shown matching ones before it writes a file.
+- **Forge integration**: with a git forge connected, Grimoire checks a snippet's cached body against its source and marks it current or diverged. Push webhooks keep that fresh.
+- **The shape ledger**: Grimoire extracts the code shapes from a bound repo and tracks how each is accounted for: an instance of a snippet, a deliberate variant with its reason, or a one-off. Coverage shows what is still unclassified.
 
-- **Rulebooks → topics → rules** — Rules are grouped by topic inside a rulebook.
-- **Rules arrive by retrieval** — Nothing is preloaded. A rule reaches a
-  session when what the agent is about to do matches its trigger: a command,
-  a file being written, or the operator's own message. `when_to_apply` is
-  therefore the field that decides whether a rule is ever seen.
-- **Per-project scope** — A project subscribes to rulebooks, and can add
-  project-scoped rules or suppress individual inherited rules/topics.
+## Family canon
 
-## Stored Processes
+Projects on the same platform (Android apps, Go services, ...) share good ideas. An idea promoted to the family's canon reaches every project on that platform, and each answers it: adopted, a variant with its reason, or owed (filed as a task). `/family` shows the ideas and every project's answers.
 
-Reusable saved prompts (a note with `note_type=process`) — e.g. a drift-audit or a
-DRY pass. The bundled plugin syncs each Process into a local Claude Code skill stub
-(`/scribe:sync`) that auto-surfaces by relevance and fetches the live procedure on
-demand.
+## Design systems
 
-## Search and Knowledge Injection
+Tokens (colour, type, space, motion, ...) and written guidance, with inheritance: a project's design system can extend a house style and record where it departs. Grimoire generates a stylesheet from it, checks code snippets against it, and gives Claude the values to use before it writes UI. `/design-systems` edits them.
 
-- **Semantic search** — pgvector-backed similarity search over notes and tasks
-  (in-process `fastembed` embeddings; no external model).
-- **Proactive knowledge-injection** — the plugin's `UserPromptSubmit` hook surfaces a
-  short, high-confidence menu of maybe-relevant note *titles* into Claude's context
-  each turn; Claude pulls a full body only when it judges it relevant. Gated so it
-  stays quiet on most turns and never repeats within a session.
+## Stored processes
 
-## Knowledge Graph
+Saved procedures, such as a drift audit or a DRY pass. The plugin syncs each one into a Claude Code skill (`/grimoire:sync`), which fetches the live procedure when it is invoked.
 
-`/graph` renders notes, tasks, and tags as a D3 force-directed graph. Tag nodes
-cluster notes that share tags; invisible project hubs attract project members. Physics
-controls (repulsion, link distance/strength, hub pull, gravity); click a node to peek,
-click a tag to filter.
+## Search and context injection
+
+- **Semantic search** over notes, tasks, rules, milestones and systems, with embeddings computed in-process (no external model service). It falls back to keyword search if the embedder is unavailable.
+- **Context injection**: the plugin's hooks show Claude a short menu of possibly relevant records at the moments they matter: rules and prior art when a prompt arrives, before a command or a file write, and when a moment of work is reached. Claude opens a full record only when it judges it relevant.
+- **Tuning**: each surface has its own thresholds and budget, in Settings → General. Every change is logged with its reason, and retrieval telemetry shows what was surfaced and what was opened.
 
 ## Claude via MCP and the plugin
 
-The whole store is reachable by Claude through a built-in **MCP endpoint at `/mcp`**
-(Bearer-auth with an API key). The **Scribe Claude Code plugin** (shipped in this
-repo) wires it up:
+The whole store is reachable through the MCP endpoint at `/mcp`, authenticated with an API key. The Claude Code plugin in this repo adds:
 
-- a `SessionStart` hook that injects active-project
-  context so Scribe surfaces without being asked (fail-open if Scribe is unreachable);
-- universal process-skills — writing-plans, systematic-debugging, verification,
-  brainstorming — that route their output into Scribe;
-- your saved Processes auto-surfaced as skills.
+- hooks for session start, each prompt, before and after tool calls, the end of a turn, compaction and session end, all failing open if Grimoire is unreachable;
+- a project fence: a session belongs to the project its starting directory is bound to. Toward any other project it can read anything and file an issue. Editing that project's files, committing or pushing in its repo, or changing its records first asks you, in every permission mode;
+- skills for the working practices: using Grimoire, writing plans, systematic debugging, verification, brainstorming, reporting back, reusing code, shape accounting and family canon;
+- your stored processes as skills.
 
 See [API Keys & MCP](api-keys-and-mcp.md).
 
-## Sharing and Collaboration
+## The web UI
 
-- **Share** — Share any project, note, or task with users or groups at
-  `viewer`/`editor`/`admin` levels from the viewer/project toolbar.
-- **Groups** — Admins create platform-wide groups and assign `member`/`owner` roles;
-  share a resource with a group in one action.
-- **Shared with me** — `/shared` lists incoming shares with permission badges.
-- **Notifications** — An in-app bell (unread count, polled) fires when a project or
-  note is shared with you or you're added to a group.
+- **Dashboard**: what to work on next. **Knowledge** browses everything.
+- **Graph** (`/graph`): notes, tasks and tags as a force-directed graph, with physics controls and filtering by tag.
+- **Trash**: deleted records wait here until retention purges them, and can be restored.
+- **Installable** as a desktop or mobile app.
 
-Every read and mutation is scoped by owner + direct shares + group shares.
+## Sharing
 
-## Data Export and Backup
+Share a project, note or task with users or groups, as viewer, editor or admin. Admins manage groups. `/shared` lists what has been shared with you, and an in-app bell notifies you of new shares. Every read and write is checked against ownership and shares.
 
-- **Personal export** — download all your notes/tasks as a Markdown ZIP (YAML
-  frontmatter) or a JSON array.
-- **Admin backup** — full application backup/restore (format v4) with ID remapping on
-  restore for cross-instance migration.
+## Export and backup
 
-## Progressive Web App
+- **Personal export**: your notes and tasks as a Markdown ZIP (with YAML frontmatter) or JSON.
+- **Admin backup and restore**: a restore rolls the whole instance back to one of its own backups, after saving the current state, or brings a new instance back from any backup.
+- **Scheduled backups**: a daily, dated, uncompressed tar to a folder or an S3-compatible bucket, laid out so a deduplicating tool such as restic stores only what changed. Restoring is in Settings, or `python -m grimoire.restore`. See [Backups](backups.md).
 
-Installable as a desktop or mobile app; a service worker caches the shell.
+## Sign-in
 
-## Authentication
-
-Native email + password, plus optional **OIDC** sign-in (Authentik, Keycloak, etc.)
-that links to a matching local account. Invite links, a registration toggle, password
-reset, and session invalidation are included. See [SSO / OAuth](sso-oauth.md).
+Email and password, plus optional OIDC single sign-on (Authentik, Keycloak, ...) that links to a matching local account. Invite links, password reset and signing out other sessions are included. See [SSO / OAuth](sso-oauth.md).
 
 ## Settings
 
 | Tab | Contents |
 |-----|----------|
-| General | Instance preferences (key/value) |
-| Account | Email change, password change, session invalidation |
-| Profile | Per-user profile fields |
-| Integrations | SearXNG status |
-| Data | Personal export; backup / restore (admin) |
-| API Keys | Create/revoke `fmcp_` keys for the MCP endpoint |
-| Config (admin) | Base URL, SMTP, DB-maintenance schedule |
-| Users (admin) | User list, invite links, registration toggle |
-| Logs (admin) | Error, audit, and usage logs with search |
-| Groups (admin) | Create/manage groups and membership |
+| General | Timezone, trash retention, retrieval thresholds, moments, reply shapes |
+| Account | Email, password, active sessions |
+| Notifications | Email notifications |
+| Integrations | SearXNG, git forge connections |
+| Data | Export, backup and restore, scheduled backups (admin) |
+| MCP Access | API keys and the command to connect Claude |
+| Config (admin) | What's running, reverse proxy count (checked against your own request), application URL, plugin marketplace, database maintenance, SMTP, forge webhook |
+| Shared areas (admin) | The canonical areas systems map to |
+| Platforms (admin) | The platform catalogue family canon is grouped by |
+| Users (admin) | Registration, invites, users |
+| Logs (admin) | Error, audit and usage logs |
+| Groups (admin) | Groups and membership |
 
-## Keyboard Shortcuts
+## Keyboard shortcuts
 
 | Key | Action |
 |-----|--------|
-| `g` + `h` | Home (dashboard) |
-| `g` + `n` | Notes |
-| `g` + `t` | Knowledge (tasks) |
-| `g` + `p` | Projects |
-| `g` + `r` | Rulebooks |
-| `g` (bare) | Graph |
-| `g` + `x` | Trash |
+| `g` `h` | Dashboard |
+| `g` `n` | Notes |
+| `g` `t` | Knowledge (everything, tasks included) |
+| `g` `p` | Projects |
+| `g` `r` | Rules |
+| `g` `g` | Graph |
+| `g` `x` | Trash |
 | `n` | New note |
 | `t` | New task |
+| `e` | Edit the note you're viewing |
 | `/` | Focus search |
-| `?` | Show shortcuts panel |
-| `j` / `k` | Navigate list items |
-| `Enter` | Open selected item |
-| `e` | Edit current item |
-| `Esc` | Close panel / blur / go home (progressive) |
-| `Ctrl+S` | Save in editor |
+| `?` | Show shortcuts |
+| `j` / `k` | Move through a list |
+| `Enter` | Open the selected item |
+| `Esc` | Close the overlay, leave the field, then go to the dashboard |
+| `Ctrl+S` | Save in the editor |

docs/sso-oauth.md

@@ -1,6 +1,6 @@
 # OAuth / OIDC SSO Setup
 
-Fabled Assistant supports single sign-on via any OpenID Connect provider.
+Grimoire supports single sign-on via any OpenID Connect provider.
 This guide covers Authentik, but the same pattern works with Keycloak, Authelia, Zitadel, etc.
 
 ## 1. Create the provider in Authentik
@@ -8,7 +8,7 @@ This guide covers Authentik, but the same pattern works with Keycloak, Authelia,
 1. Log in to the Authentik admin UI.
 2. Go to **Applications → Providers → Create → OAuth2/OpenID Provider**.
 3. Fill in:
-   - **Name:** `Fabled Assistant` (or whatever you like)
+   - **Name:** `Grimoire` (or whatever you like)
    - **Authorization flow:** your default authorization flow
    - **Client type:** `Confidential`
    - **Redirect URIs:** `https://your-fabled-domain/api/auth/oauth/callback`
@@ -20,7 +20,7 @@ This guide covers Authentik, but the same pattern works with Keycloak, Authelia,
    https://auth.example.com/application/o/fabled-assistant/
    ```
 
-## 2. Configure Fabled Assistant
+## 2. Configure Grimoire
 
 Add the following environment variables to the `app` service in `docker-compose.yml`:
 
@@ -64,7 +64,7 @@ docker compose up --build -d
 
 ## 4. Account Linking
 
-When a user logs in via OAuth for the first time, Fabled checks in this order:
+When a user logs in via OAuth for the first time, Grimoire checks in this order:
 
 1. **Existing OAuth sub** — returns that user immediately.
 2. **Matching email** — if a local account already exists with the same email, the OAuth identity is linked to it automatically. The user retains all their notes and tasks.
@@ -92,4 +92,4 @@ The backend will reject any `POST /api/auth/login` or `POST /api/auth/register`
 | Zitadel | `https://your-instance.zitadel.cloud` |
 | Google | `https://accounts.google.com` |
 
-The OIDC discovery endpoint (`<issuer>/.well-known/openid-configuration`) must be publicly reachable from the Fabled container (server-to-server call at login time).
+The OIDC discovery endpoint (`<issuer>/.well-known/openid-configuration`) must be publicly reachable from the Grimoire container (server-to-server call at login time).

frontend/index.html

@@ -4,13 +4,14 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png">
     <link rel="manifest" href="/manifest.json">
-    <meta name="theme-color" content="#6c63ff">
+    <meta name="theme-color" content="#14171A">
     <meta name="mobile-web-app-capable" content="yes">
     <meta name="apple-mobile-web-app-capable" content="yes">
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
-    <meta name="apple-mobile-web-app-title" content="Scribe">
-    <title>Fabled Scribe</title>
+    <meta name="apple-mobile-web-app-title" content="Grimoire">
+    <title>Fabled Grimoire</title>
   </head>
   <body>
     <div id="app"></div>

frontend/package-lock.json

@@ -1,12 +1,13 @@
 {
-  "name": "scribe-frontend",
+  "name": "grimoire-frontend",
   "version": "0.1.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "scribe-frontend",
+      "name": "grimoire-frontend",
       "version": "0.1.0",
+      "license": "AGPL-3.0-only",
       "dependencies": {
         "@fullcalendar/core": "^6.1.20",
         "@fullcalendar/daygrid": "^6.1.20",

frontend/package.json

@@ -1,6 +1,7 @@
 {
-  "name": "scribe-frontend",
+  "name": "grimoire-frontend",
   "private": true,
+  "license": "AGPL-3.0-only",
   "version": "0.1.0",
   "type": "module",
   "scripts": {

frontend/public/favicon.svg

@@ -1,33 +1,18 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32">
-  <style>
-    .book { fill: #6366f1; stroke: #4f46e5; }
-    .spine { stroke: #4f46e5; }
-    .lines { stroke: #a5b4fc; }
-    @media (prefers-color-scheme: dark) {
-      .book { fill: #e2e8f0; stroke: #cbd5e0; }
-      .spine { stroke: #cbd5e0; }
-      .lines { stroke: #4a5568; }
-    }
-  </style>
-  <!-- Book body -->
-  <path class="book" d="M4 7 C4 7 8 5 16 6 C24 5 28 7 28 7 L28 26 C28 26 24 24 16 25 C8 24 4 26 4 26 Z" stroke-width="0.5"/>
-  <!-- Book spine -->
-  <line class="spine" x1="16" y1="6" x2="16" y2="25" stroke-width="0.8"/>
-  <!-- Left page lines -->
-  <line class="lines" x1="7" y1="11" x2="14" y2="10.5" stroke-width="0.6" stroke-linecap="round"/>
-  <line class="lines" x1="7" y1="14" x2="14" y2="13.5" stroke-width="0.6" stroke-linecap="round"/>
-  <line class="lines" x1="7" y1="17" x2="14" y2="16.5" stroke-width="0.6" stroke-linecap="round"/>
-  <line class="lines" x1="7" y1="20" x2="12" y2="19.5" stroke-width="0.6" stroke-linecap="round"/>
-  <!-- Right page lines -->
-  <line class="lines" x1="18" y1="10.5" x2="25" y2="11" stroke-width="0.6" stroke-linecap="round"/>
-  <line class="lines" x1="18" y1="13.5" x2="25" y2="14" stroke-width="0.6" stroke-linecap="round"/>
-  <line class="lines" x1="18" y1="16.5" x2="25" y2="17" stroke-width="0.6" stroke-linecap="round"/>
-  <!-- Magic spark -->
-  <g transform="translate(24, 5)">
-    <path d="M0 -4 L1 -1 L4 0 L1 1 L0 4 L-1 1 L-4 0 L-1 -1 Z" fill="#f6ad55"/>
-    <path d="M0 -2.5 L0.6 -0.6 L2.5 0 L0.6 0.6 L0 2.5 L-0.6 0.6 L-2.5 0 L-0.6 -0.6 Z" fill="#fbd38d"/>
-  </g>
-  <!-- Secondary sparkles -->
-  <circle cx="20" cy="3" r="0.7" fill="#f6ad55" opacity="0.7"/>
-  <circle cx="27" cy="8" r="0.5" fill="#fbd38d" opacity="0.6"/>
+  <!-- page block, seen at the fore-edge -->
+  <path d="M8.5 4.5 H25.5 Q27 4.5 27 6 V27 Q27 28.5 25.5 28.5 H8.5 Z" fill="#E9DFC6"/>
+  <path d="M25 7 V26.5" stroke="#C9BB97" stroke-width="0.6"/>
+  <!-- cover -->
+  <path d="M5 4 Q5 3 6 3 H24 Q25.5 3 25.5 4.5 V26.5 Q25.5 28 24 28 H6 Q5 28 5 27 Z" fill="#5B4A8A"/>
+  <!-- spine band -->
+  <rect x="5" y="3" width="3.2" height="25" rx="0.6" fill="#47396E"/>
+  <!-- corner fittings -->
+  <path d="M21.5 3 H24 Q25.5 3 25.5 4.5 V7 Z" fill="#D4A94E"/>
+  <path d="M21.5 28 H24 Q25.5 28 25.5 26.5 V24 Z" fill="#D4A94E"/>
+  <!-- clasp across the fore-edge -->
+  <rect x="22.5" y="14" width="5.5" height="3.6" rx="0.8" fill="#D4A94E"/>
+  <circle cx="26.4" cy="15.8" r="0.7" fill="#8A6A22"/>
+  <!-- sigil: a four-pointed star in a ring -->
+  <circle cx="15.5" cy="15.5" r="5.2" fill="none" stroke="#D4A94E" stroke-width="0.9"/>
+  <path d="M15.5 11.4 L16.5 14.5 L19.6 15.5 L16.5 16.5 L15.5 19.6 L14.5 16.5 L11.4 15.5 L14.5 14.5 Z" fill="#F1D48A"/>
 </svg>

frontend/public/manifest.json

@@ -1,17 +1,27 @@
 {
-  "name": "Fabled Scribe",
-  "short_name": "Scribe",
-  "description": "Your self-hosted second brain with AI assistance",
+  "name": "Fabled Grimoire",
+  "short_name": "Grimoire",
+  "description": "A self-hosted work system-of-record for software projects, built to be driven by Claude Code.",
   "start_url": "/",
   "display": "standalone",
-  "background_color": "#1a1a2e",
-  "theme_color": "#6c63ff",
+  "background_color": "#14171A",
+  "theme_color": "#14171A",
   "orientation": "portrait-primary",
   "icons": [
     {
-      "src": "/favicon.ico",
+      "src": "/favicon.svg",
       "sizes": "any",
-      "type": "image/x-icon"
+      "type": "image/svg+xml"
+    },
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png"
     }
   ]
 }

frontend/src/App.vue

@@ -13,11 +13,10 @@ import { fetchVersion } from "@/api/version";
 useTheme();
 
 const router = useRouter();
-// THREE states, not two (#3127 checklist 12). `null` is "not answered yet" and
-// renders nothing; a string renders; `appVersionFailed` renders its own thing.
-// This used to default to the literal "dev" and swallow the error, which meant
-// an instance that could not answer was indistinguishable from a local build
-// that genuinely reports "dev" — a blank standing in for `unknown`, in the one
+// THREE states, not two. `null` is "not answered yet" and renders nothing; a
+// string renders; `appVersionFailed` renders its own thing. Defaulting to the
+// literal "dev" and swallowing the error would make an instance that cannot
+// answer indistinguishable from a local build that genuinely reports "dev" — a blank standing in for `unknown`, in the one
 // readout whose whole job is to say what is running.
 const appVersion = ref<string | null>(null);
 const appVersionFailed = ref(false);
@@ -85,7 +84,7 @@ function onGlobalKeydown(e: KeyboardEvent) {
     switch (e.key) {
       case "h": router.push("/"); break;
       case "n": router.push("/notes"); break;
-      case "t": router.push("/"); break;
+      case "t": router.push("/knowledge"); break;
       case "p": router.push("/projects"); break;
       case "r": router.push("/rules"); break;
       case "g": router.push("/graph"); break;
@@ -182,7 +181,7 @@ onUnmounted(() => {
                 <kbd class="shortcut-key">g</kbd>
                 <span class="shortcut-key-sep">+</span>
                 <kbd class="shortcut-key">h</kbd>
-                <span class="shortcut-desc">Home</span>
+                <span class="shortcut-desc">Dashboard</span>
               </div>
               <div class="shortcut-row">
                 <kbd class="shortcut-key">g</kbd>
@@ -202,6 +201,18 @@ onUnmounted(() => {
                 <kbd class="shortcut-key">p</kbd>
                 <span class="shortcut-desc">Projects</span>
               </div>
+              <div class="shortcut-row">
+                <kbd class="shortcut-key">g</kbd>
+                <span class="shortcut-key-sep">+</span>
+                <kbd class="shortcut-key">r</kbd>
+                <span class="shortcut-desc">Rules</span>
+              </div>
+              <div class="shortcut-row">
+                <kbd class="shortcut-key">g</kbd>
+                <span class="shortcut-key-sep">+</span>
+                <kbd class="shortcut-key">g</kbd>
+                <span class="shortcut-desc">Graph</span>
+              </div>
               <div class="shortcut-row">
                 <kbd class="shortcut-key">g</kbd>
                 <span class="shortcut-key-sep">+</span>
@@ -210,7 +221,7 @@ onUnmounted(() => {
               </div>
               <div class="shortcut-row">
                 <kbd class="shortcut-key">Esc</kbd>
-                <span class="shortcut-desc">Unfocus field → go home</span>
+                <span class="shortcut-desc">Unfocus field → go to the dashboard</span>
               </div>
               <div class="shortcut-row">
                 <kbd class="shortcut-key">?</kbd>

frontend/src/api/backups.ts

@@ -0,0 +1,142 @@
+import { apiGet, apiPost, apiPostRaw, apiPut } from "@/api/client";
+
+/**
+ * Scheduled backups — `/api/admin/backups`. One dated,
+ * uncompressed tar per run, delivered to a folder or an S3 bucket.
+ */
+export interface BackupConfig {
+  enabled: boolean;
+  /** UTC hour the daily backup runs at, 0–23. */
+  hour: number;
+  destination: "folder" | "s3";
+  folder_path: string;
+  s3_endpoint: string;
+  s3_bucket: string;
+  s3_access_key: string;
+  s3_region: string;
+  s3_verify_tls: boolean;
+}
+
+export interface BackupRun {
+  started_at: string;
+  finished_at: string;
+  trigger: "scheduled" | "manual";
+  status: "ok" | "failed";
+  destination?: string;
+  file?: string;
+  size_bytes?: number;
+  where?: string;
+  error?: string;
+  duration_s: number;
+}
+
+export interface BackupsOverview {
+  config: BackupConfig;
+  /** Never the secret itself: whether one is kept, and whether this
+   *  instance can still open it. */
+  secret: { set: boolean; readable: boolean };
+  /** What stops the saved config from sending a backup, in words. */
+  problems: string[];
+  running: boolean;
+  /** Newest first, at most 30. */
+  runs: BackupRun[];
+  last_run: BackupRun | null;
+  last_success: BackupRun | null;
+  overdue: boolean;
+}
+
+/** What the form sends: config fields, plus the secret when one was typed. */
+export type BackupChanges = Partial<BackupConfig> & {
+  s3_secret?: string;
+  clear_s3_secret?: boolean;
+};
+
+export function getBackups(): Promise<BackupsOverview> {
+  return apiGet<BackupsOverview>("/api/admin/backups");
+}
+
+export function saveBackups(changes: BackupChanges): Promise<BackupsOverview> {
+  return apiPut<BackupsOverview>("/api/admin/backups", changes);
+}
+
+/** Ask the destination whether it would take a backup, with the form's
+ *  unsaved values. The server gives the destination 45s; this waits a little
+ *  longer so its own answer, not the client's deadline, is what arrives. */
+export function checkBackupDestination(
+  changes: BackupChanges,
+): Promise<{ ok: boolean; message: string }> {
+  return apiPost<{ ok: boolean; message: string }>("/api/admin/backups/check", changes, { timeoutMs: 60_000 });
+}
+
+export function runBackupNow(): Promise<{ status: string }> {
+  return apiPost<{ status: string }>("/api/admin/backups/run", {});
+}
+
+
+// ── Restore: put the whole instance back to a full backup ─────────────────
+
+export interface StoredBackup {
+  name: string;
+  size_bytes: number;
+}
+
+export interface RestoreCount {
+  kind: string;
+  now: number;
+  after: number;
+}
+
+export interface RestorePreview {
+  /** "fresh": an empty instance takes the backup. "rollback": this instance
+   *  goes back to its own earlier backup. */
+  mode: "fresh" | "rollback";
+  exported_at: string | null;
+  counts: RestoreCount[];
+}
+
+export interface RestoreResult extends RestorePreview {
+  status: "ok";
+  restored: Record<string, number>;
+  safety_backup: { file: string; size_bytes: number; where: string; note?: string };
+}
+
+/** A backup at the destination, by name, or a file picked from this computer. */
+export type RestoreFrom = { source: string } | { file: File };
+
+// Reading, checking and writing the whole store is slow by design; bounded,
+// but in minutes.
+const RESTORE_TIMEOUT_MS = 10 * 60 * 1000;
+
+export function listRestoreSources(): Promise<{ backups: StoredBackup[]; error?: string }> {
+  return apiGet("/api/admin/restore/sources", { timeoutMs: 60_000 });
+}
+
+async function restoreCall<T>(path: string, from: RestoreFrom, query: Record<string, string> = {}): Promise<T> {
+  const params = new URLSearchParams(query);
+  if ("source" in from) {
+    params.set("source", from.source);
+    return apiPostRaw<T>(`${path}?${params}`, null, null, { timeoutMs: RESTORE_TIMEOUT_MS });
+  }
+  const qs = params.toString() ? `?${params}` : "";
+  const isTar = from.file.name.toLowerCase().endsWith(".tar");
+  // The JSON download is parsed first, so a damaged file fails here, before
+  // the upload.
+  const body = isTar ? from.file : JSON.stringify(JSON.parse(await from.file.text()));
+  return apiPostRaw<T>(`${path}${qs}`, body, isTar ? "application/x-tar" : "application/json",
+                       { timeoutMs: RESTORE_TIMEOUT_MS });
+}
+
+export function previewRestore(from: RestoreFrom): Promise<RestorePreview> {
+  return restoreCall<RestorePreview>("/api/admin/restore/preview", from);
+}
+
+export function restoreBackup(from: RestoreFrom): Promise<RestoreResult> {
+  return restoreCall<RestoreResult>("/api/admin/restore", from, { confirm: "rollback" });
+}
+
+/** When a backup named `grimoire-20261015T020000Z.tar` was taken. */
+export function backupTakenAt(name: string): Date | null {
+  const m = /(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z/.exec(name);
+  if (!m) return null;
+  return new Date(Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6]));
+}

frontend/src/api/canonicalSystems.ts

@@ -1,6 +1,6 @@
 /**
  * Canonical systems — the GLOBAL area vocabulary every project's Systems can
- * map onto (milestone 307).
+ * map onto.
  *
  * The mapping is an ASSOCIATION, never a rename: a project's System keeps the
  * name the project gave it, and `canonical_id` only records which shared area

frontend/src/api/client.ts

@@ -41,8 +41,8 @@ async function handleResponse<T>(res: Response, path: string): Promise<T> {
 /**
  * The server's `{"error": "..."}` message from a failed call, or `fallback`
  * when the failure carried none (network error, non-JSON body). The one place
- * the error envelope is unpacked on the client — views used to restate this
- * as a six-line `"body" in e` branch at every catch site.
+ * the error envelope is unpacked on the client, so no view restates it as a
+ * `"body" in e` branch at its catch site.
  */
 export function apiErrorMessage(e: unknown, fallback: string): string {
   if (e && typeof e === "object" && "body" in e) {
@@ -55,21 +55,20 @@ export function apiErrorMessage(e: unknown, fallback: string): string {
 /**
  * How long an ordinary JSON call may wait before it is declared failed.
  *
- * Rule 156: a wait with no deadline is a bug. `fetch`'s own default is to wait
+ * A wait with no deadline is a bug. `fetch`'s own default is to wait
  * as long as the browser will, which is not a deadline — it is the absence of
  * one, and it renders as a spinner that never resolves. There is no state a
  * surface can show for "pending forever" that is not a lie.
  *
  * 30s is chosen to be longer than anything healthy: it has to clear a cold
- * embedding call and a list view under connection-pool contention (#2384 had
- * /api/projects fanning 25 concurrent sessions at a 15-connection pool), so
+ * embedding call and a list view under connection-pool contention, so
  * tripping it means something is genuinely wrong rather than merely busy. Slow
  * BY DESIGN is a different case and passes its own value — see the callers in
  * SettingsView that do.
  */
 const DEFAULT_TIMEOUT_MS = 30_000;
 
-/** HTTP 408. Not a status any Scribe route returns, so it unambiguously means
+/** HTTP 408. Not a status any Grimoire route returns, so it unambiguously means
  *  "the client gave up" rather than anything the server said. */
 const CLIENT_TIMEOUT_STATUS = 408;
 
@@ -118,7 +117,7 @@ export interface RequestOpts {
  * The one place a request is actually made — every verb below goes through
  * here, so the deadline cannot be forgotten by adding a sixth.
  *
- * EXPIRY SURFACES AS AN `ApiError`, which is rule 156's second half: the
+ * EXPIRY SURFACES AS AN `ApiError`, the deadline's second half: the
  * failure has to arrive in the shape the caller already handles. A bare
  * `DOMException: TimeoutError` would reach `apiErrorMessage(e, fallback)` as
  * an object with no `body`, so every catch site in the app would report its
@@ -157,6 +156,15 @@ export function apiPost<T>(path: string, body: unknown, opts?: RequestOpts): Pro
   return request<T>(path, { method: "POST", headers: JSON_HEADERS, body: JSON.stringify(body) }, opts);
 }
 
+/** A POST whose body is sent as it is (a file, or text already serialised),
+ *  under the same deadline and error handling as every other call. */
+export function apiPostRaw<T>(
+  path: string, body: BodyInit | null, contentType: string | null, opts?: RequestOpts,
+): Promise<T> {
+  const headers = contentType ? { "Content-Type": contentType } : undefined;
+  return request<T>(path, { method: "POST", headers, body }, opts);
+}
+
 export function apiPut<T>(path: string, body: unknown, opts?: RequestOpts): Promise<T> {
   return request<T>(path, { method: "PUT", headers: JSON_HEADERS, body: JSON.stringify(body) }, opts);
 }
@@ -501,24 +509,6 @@ export const createApiKey = (name: string, scope: 'read' | 'write') =>
 
 export const revokeApiKey = (id: number) => apiDelete(`/api/api-keys/${id}`)
 
-// ── User Profile ─────────────────────────────────────────────────────────────
-
-export interface UserProfile {
-  display_name: string
-  job_title: string
-  industry: string
-  expertise_level: 'novice' | 'intermediate' | 'expert'
-  response_style: 'concise' | 'balanced' | 'detailed'
-  tone: 'casual' | 'professional' | 'technical'
-  interests: string[]
-  work_schedule: { days?: string[]; start?: string; end?: string }
-}
-
-export const getProfile = () => apiGet<UserProfile>('/api/profile')
-export const updateProfile = (data: Partial<UserProfile>) =>
-  apiPut<UserProfile>('/api/profile', data)
-
-
 // ── Note Versions (pinning) ──────────────────────────────────────────────────
 
 import type { NoteVersion } from '../types/task'

frontend/src/api/designSystems.ts

@@ -1,5 +1,5 @@
 /**
- * Design systems — the stylesheet held as records (milestone #254).
+ * Design systems — the stylesheet held as records.
  *
  * A design system is a named set of tokens with an optional parent. A system
  * with no parent is a "family"; one with a parent holds ONLY what it changes,
@@ -82,8 +82,8 @@ export interface StarterRoleGroup {
 }
 
 /** The starter token ROLES offered at creation — names and purposes, never
- *  values. A default palette would be one install's taste shipped as product
- *  (rule #115), so the values are always the operator's to fill. */
+ *  values. A default palette would be one install's taste shipped as product,
+ *  so the values are always the operator's to fill. */
 export const listStarterRoleGroups = () =>
   apiGet<{ groups: StarterRoleGroup[]; default_prefix: string }>(
     "/api/design-systems/starter-roles",