Add renovate.json

Roundtable's card rendered ~35 milestone bars and ran several viewport-heights
tall, so one tile dwarfed the grid and stopped being scannable — which is the
whole job of a card (#2391).

Now 10 bars, ordered OPEN WORK FIRST and newest first within each group, with
"+25 more milestones" beneath.

Ordering by recency alone would have been wrong, and the operator's call was to
lead with open work: a long-running project's oldest milestones are usually its
finished ones, so the ten most recent could easily have been ten completed bars
while the three in flight were the ones hidden. A card answers "what is
happening", not "what happened".

Three details that are the actual work:

- The palette index is captured from the FULL list before slicing. Colour keyed
  to visible position would have recoloured every bar on the card each time a
  milestone closed or was added.
- Computed once per load into a Map rather than called from the template. A
  helper invoked inside v-for re-runs on every render, and this one sorts.
- The overflow notice is plain text, not a link. The whole card already
  navigates to the project, and a link nested inside a clickable region is a
  trap for keyboard and screen-reader users.

Saying the count matters more than the cap: a list that simply stops reads as a
rendering bug, while a count reads as a summary.

Payload is unchanged — the API still returns every milestone. Capping
server-side would also need the total to travel with it, or the "+N" has
nothing to count from; not worth it while the response is two queries (#2384).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UaYUaouG9jjhATyuxCKrQs

.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "scribe-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.",
+  "plugins": [
+    {
+      "name": "scribe",
+      "source": "./plugin",
+      "description": "Scribe second brain: MCP tools + session-start push channel + universal process-skills."
+    }
+  ]
+}

.env.example

@@ -1,4 +1,4 @@
 POSTGRES_USER=fabled
 POSTGRES_PASSWORD=fabled
-POSTGRES_DB=fabledassistant
+POSTGRES_DB=scribe
 SECRET_KEY=dev-secret-change-me

.forgejo/workflows/ci.yml

@@ -1,13 +1,31 @@
 # CI runs first; build only proceeds if all checks pass.
 #
-# Push to dev:       typecheck + lint + test → build :dev + :<sha>
-# Tag v* (release):  typecheck + lint + test → build :latest + :<sha> + :<version>
-# Pull request:      no CI run — code is validated on dev push before any PR is opened
+# Push to dev:        typecheck + lint + test + build :dev + :<sha>
+# 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).
+#
+# 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.
 #
 # 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.
+#
 # Required secrets (repo → Settings → Secrets → Actions):
 #   REGISTRY_USER   — your Forgejo username
 #   REGISTRY_TOKEN  — Forgejo PAT with write:packages scope
@@ -15,38 +33,75 @@ name: CI & Build
 
 on:
   push:
-    branches: [dev]
+    branches: [dev, main]
     tags: ["v*"]
     paths:
       - "src/**"
       - "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.
+      - "uv.lock"
       - "alembic/**"
       - "alembic.ini"
       - "Dockerfile"
       - "assets/**"
       - "fable-mcp/**"
+      # 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.
+      - "plugin/**"
+      - ".claude-plugin/**"
+      - "scripts/check_plugin.py"
       - ".forgejo/workflows/ci.yml"
-  # pull_request trigger intentionally omitted — all changes go through dev
-  # first, where CI already runs on push. PR runs would be redundant duplication.
+  # 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).
+  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.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
+
+# Least-privilege default. Jobs that need more (build pushes to the
+# registry) upgrade explicitly.
+permissions:
+  contents: read
 
 env:
   REGISTRY: git.fabledsword.com
-  IMAGE: git.fabledsword.com/bvandeusen/fabledassistant
+  IMAGE: git.fabledsword.com/bvandeusen/fabledscribe
 
 jobs:
   typecheck:
     name: TypeScript typecheck
-    runs-on: py3.12-node22
+    # Gate dev, main, and v* tags; reject any other ref (see header note).
+    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
     steps:
       - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v6
+      - 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.
+        continue-on-error: true
         with:
-          node-version: "22"
-          cache: "npm"
-          cache-dependency-path: frontend/package-lock.json
+          path: ~/.npm
+          key: npm-cache-${{ hashFiles('frontend/package-lock.json') }}
+          restore-keys: npm-cache-
 
       - name: Install dependencies
         run: npm ci
@@ -56,71 +111,245 @@ jobs:
         run: npx vue-tsc --noEmit
         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).
+  plugin:
+    name: Plugin hooks
+    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
+    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.
+      - 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.
+      - name: Install shell tooling
+        run: |
+          apt-get update -qq
+          apt-get install -y -qq --no-install-recommends jq shellcheck
+
+      # On main the comparison would be against itself, so only the syntax and
+      # pattern checks mean anything there.
+      - name: Check plugin hooks and manifest
+        run: |
+          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            python3 scripts/check_plugin.py --no-version
+          else
+            git fetch --no-tags --depth=1 origin main:refs/remotes/origin/main
+            python3 scripts/check_plugin.py
+          fi
+
   lint:
     name: Python lint
-    runs-on: py3.12-node22
+    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
     steps:
       - uses: actions/checkout@v6
 
-      - name: Install ruff
-        run: pip install --break-system-packages ruff
-
+      # ruff is pre-installed in the ci-python image — no install
+      # step needed, lint runs in ~2s.
       - name: Lint
-        run: ruff check src/
+        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.
+      - name: Design token check
+        run: python3 scripts/check_design_tokens.py --report-literals
 
   test:
     name: Python tests
-    runs-on: py3.12-node22
+    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
     steps:
       - uses: actions/checkout@v6
 
-      # Python 3.12 is pre-installed in the runner-base image (py3.12-node22).
-      - name: Cache pip wheels
-        uses: actions/cache@v3
+      - name: Cache uv packages
+        uses: actions/cache@v4
         with:
-          path: ~/.cache/pip
-          key: pip-${{ hashFiles('pyproject.toml') }}
-          restore-keys: pip-
+          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.
+          key: uv-${{ hashFiles('uv.lock') }}
+          restore-keys: uv-
 
-      - name: Create virtual environment
-        run: python3.12 -m venv /opt/venv
-
-      - name: Install package with dev deps
-        run: |
-          /opt/venv/bin/pip install --upgrade pip setuptools wheel
-          /opt/venv/bin/pip install --no-build-isolation http-ece
-          /opt/venv/bin/pip install -e ".[dev]"
+      # 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.
+      - name: Install locked dependencies
+        env:
+          UV_PROJECT_ENVIRONMENT: /opt/venv
+        run: uv sync --locked --extra dev
 
       - name: Run tests
-        run: /opt/venv/bin/python -m pytest tests/ -v
+        # 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.
+  #
+  # 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.
+  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.
+      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.
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: scribe
+          POSTGRES_PASSWORD: ci_integration
+          POSTGRES_DB: scribe_test
+        options: >-
+          --health-cmd "pg_isready -U scribe"
+          --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.
+      - name: Install locked dependencies
+        env:
+          UV_PROJECT_ENVIRONMENT: /opt/venv
+        run: uv sync --locked --extra dev
+      - name: Integration suite (resolve service IP, migrate, test)
+        run: |
+          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"
+          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 (busybox sh — the runner
+          # default — has no bash /dev/tcp, so use Python).
+          /opt/venv/bin/python - "$PG_IP" <<'PY'
+          import socket, sys, time
+          for _ in range(30):
+              try:
+                  socket.create_connection((sys.argv[1], 5432), timeout=2).close()
+                  break
+              except OSError:
+                  time.sleep(1)
+          else:
+              sys.exit("postgres did not become reachable")
+          PY
+          # Real migrations build the schema; the maintenance tests then run
+          # VACUUM (ANALYZE) and read pg_stat_user_tables against it.
+          /opt/venv/bin/alembic upgrade head
+          /opt/venv/bin/python -m pytest tests/ -v -m integration
 
   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 branch pushes and version tag pushes only.
-    # main branch pushes run CI for safety but do not build —
-    # the release tag (v*) is the sole trigger for a production image.
-    if: |
-      github.event_name == 'push' &&
-      (github.ref == 'refs/heads/dev' || startsWith(github.ref, 'refs/tags/'))
-    runs-on: py3.12-node22
+    # Build on dev, main, and v* tag pushes. dev → :dev, main → :latest,
+    # tag → :latest + :<version>; every build also gets an immutable :<sha>.
+    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
+    permissions:
+      contents: read
+      packages: write
     steps:
       - uses: actions/checkout@v6
 
       - 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.
         run: |
           TAGS="${{ env.IMAGE }}:${{ github.sha }}"
           BUILD_VERSION="dev"
-          if [[ "${{ github.ref }}" == "refs/heads/dev" ]]; then
-            TAGS="$TAGS,${{ env.IMAGE }}:dev"
-          elif [[ "${{ github.ref }}" == refs/tags/* ]]; then
-            TAGS="$TAGS,${{ env.IMAGE }}:latest,${{ env.IMAGE }}:${{ github.ref_name }}"
-            BUILD_VERSION="${{ github.ref_name }}"
-          fi
+          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.
+              TAGS="$TAGS,${{ env.IMAGE }}:latest"
+              BUILD_VERSION="main"
+              ;;
+            refs/tags/*)
+              TAGS="$TAGS,${{ env.IMAGE }}:latest,${{ env.IMAGE }}:${{ github.ref_name }}"
+              BUILD_VERSION="${{ github.ref_name }}"
+              ;;
+          esac
           echo "value=$TAGS" >> $GITHUB_OUTPUT
           echo "build_version=$BUILD_VERSION" >> $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
+
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -136,5 +365,13 @@ jobs:
         with:
           context: .
           push: true
+          provenance: false
           tags: ${{ steps.tags.outputs.value }}
           build-args: BUILD_VERSION=${{ steps.tags.outputs.build_version }}
+          # 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.
+          cache-from: type=registry,ref=${{ env.IMAGE }}:cache
+          cache-to: type=registry,ref=${{ env.IMAGE }}:cache,mode=max,ignore-error=true

.gitignore

@@ -22,7 +22,9 @@ settings.local.json
 
 # Claude Code
 .claude/
-docs/superpowers/specs/.brainstorm/
+docs/superpowers/
+docs/plans/
+docs/specs/
 
 # Environment
 .env

.remember/tmp/save-session.pid

@@ -0,0 +1 @@
+1425947

Dockerfile

@@ -1,3 +1,4 @@
+# syntax=docker/dockerfile:1
 # Stage 1: Build Vue frontend
 FROM node:22-alpine AS build-frontend
 WORKDIR /build
@@ -7,21 +8,33 @@ COPY frontend/ .
 RUN npm run build
 
 # Stage 2: Python runtime
-FROM python:3.12-slim AS runtime
+# Tracks CI image (ci-python:3.14) so test results stay representative.
+FROM python:3.14-slim AS runtime
 WORKDIR /app
 
-COPY pyproject.toml .
+# 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.
+RUN --mount=type=cache,target=/root/.cache/pip \
+    pip install --no-cache-dir uv
+
+# Dependencies before source, so the expensive layer is cached on every build
+# that doesn't change the lock.
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev --no-install-project
+
 COPY src/ src/
-RUN pip install --no-cache-dir .
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --locked --no-dev
 
-# Build the fable-mcp wheel so it can be served for download
-COPY fable-mcp/ fable-mcp/
-RUN pip install --no-cache-dir build hatchling \
-    && python -m build --wheel ./fable-mcp --outdir /app/dist/ \
-    && pip uninstall -y build \
-    && rm -rf fable-mcp/ /root/.cache/pip
+# uv sync installs into a project venv rather than the system interpreter, so
+# alembic and hypercorn in CMD have to be found there.
+ENV PATH="/app/.venv/bin:$PATH"
 
-COPY --from=build-frontend /build/dist/ src/fabledassistant/static/
+COPY --from=build-frontend /build/dist/ src/scribe/static/
 COPY alembic.ini .
 COPY alembic/ alembic/
 
@@ -34,4 +47,4 @@ ARG BUILD_VERSION=dev
 ENV APP_VERSION=$BUILD_VERSION
 
 EXPOSE 5000
-CMD ["sh", "-c", "alembic upgrade head && hypercorn 'fabledassistant.app:create_app()' --bind 0.0.0.0:5000 --keep-alive 600"]
+CMD ["sh", "-c", "alembic upgrade head && hypercorn 'scribe.app:create_app()' --bind 0.0.0.0:5000 --keep-alive 600"]

README.md

@@ -1,14 +1,14 @@
-# Fabled Assistant
+# Fabled Scribe
 
-A self-hosted second brain and project management application with integrated LLM capabilities. Write, organise, and act on your notes and tasks with the help of a local AI assistant — all running on your own hardware.
+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.
 
 ## Features
 
-Notes and tasks with a Markdown editor, sub-tasks, milestones, and kanban project workspaces. AI chat with streaming responses, RAG over your notes, and tool use (web search, calendar, weather). A daily briefing that digests your tasks, RSS feeds, and weather on a schedule. Knowledge graph, per-user/group sharing, PWA with push notifications, an MCP server for external AI clients, and an Android companion app.
+Notes and tasks with a Markdown editor, sub-tasks, milestones, issues, and kanban project workspaces. Stored processes, an engineering rulebook system, 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.
 
 ## Quick Start
 
-**Prerequisites:** Docker and Docker Compose. 8 GB+ RAM recommended for LLM inference.
+**Prerequisites:** Docker and Docker Compose. No GPU or local model needed — Claude is the sole assistant, reached over MCP.
 
 Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml) from this repo, then:
 
@@ -19,9 +19,7 @@ export SECRET_KEY=your-random-secret-here
 docker compose -f docker-compose.quickstart.yml up -d
 ```
 
-Open `http://localhost:5000`. The first user to register becomes admin. Go to **Settings → General** to pull an LLM model — `qwen3:8b` or `llama3.1:8b` are good starting points.
-
-> **GPU:** Ollama runs CPU-only by default. See the comments in `docker-compose.quickstart.yml` to enable NVIDIA GPU passthrough.
+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:** To build from source, see [Development](docs/development.md).
 
@@ -36,7 +34,6 @@ Open `http://localhost:5000`. The first user to register becomes admin. Go to **
 | [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 |
-| [Android App](docs/android-app.md) | Flutter companion app architecture and feature status |
 
 ## License
 

alembic/env.py

@@ -4,8 +4,8 @@ from logging.config import fileConfig
 from alembic import context
 from sqlalchemy.ext.asyncio import create_async_engine
 
-from fabledassistant.config import Config
-from fabledassistant.models import Base
+from scribe.config import Config
+from scribe.models import Base
 
 config = context.config
 if config.config_file_name is not None:

alembic/versions/0034_add_user_profiles.py

@@ -0,0 +1,53 @@
+"""Add user_profiles table for structured per-user preferences."""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import ARRAY, JSONB
+
+revision = "0034"
+down_revision = "0033"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> 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("learned_summary", sa.Text(), nullable=True),
+        sa.Column("observations_raw", JSONB(), nullable=True),
+        sa.Column("observations_updated_at", sa.DateTime(timezone=True), 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)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_user_profiles_user_id", table_name="user_profiles")
+    op.drop_table("user_profiles")

alembic/versions/0035_add_rss_item_embeddings.py

@@ -0,0 +1,28 @@
+"""Add rss_item_embeddings table for semantic news search."""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision = "0035"
+down_revision = "0034"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "rss_item_embeddings",
+        sa.Column("rss_item_id", sa.Integer(), sa.ForeignKey("rss_items.id", ondelete="CASCADE"), primary_key=True),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("embedding", JSONB(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.func.now()),
+    )
+    op.create_index("ix_rss_item_embeddings_user_id", "rss_item_embeddings", ["user_id"])
+    op.create_index("ix_rss_item_embeddings_rss_item_id", "rss_item_embeddings", ["rss_item_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_rss_item_embeddings_rss_item_id", table_name="rss_item_embeddings")
+    op.drop_index("ix_rss_item_embeddings_user_id", table_name="rss_item_embeddings")
+    op.drop_table("rss_item_embeddings")

alembic/versions/0036_add_note_type_and_metadata.py

@@ -0,0 +1,28 @@
+"""Add note_type and metadata columns to notes table for entity types."""
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision = "0036"
+down_revision = "0035"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "notes",
+        sa.Column("note_type", sa.Text(), nullable=False, server_default="note"),
+    )
+    op.add_column(
+        "notes",
+        sa.Column("metadata", JSONB(), nullable=True),
+    )
+    op.create_index("ix_notes_note_type", "notes", ["note_type"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_notes_note_type", table_name="notes")
+    op.drop_column("notes", "metadata")
+    op.drop_column("notes", "note_type")

alembic/versions/0037_add_event_reminders.py

@@ -0,0 +1,29 @@
+"""Add reminder_minutes and reminder_sent_at to events.
+
+Revision ID: 0037
+Revises: 0036
+Create Date: 2026-04-04
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0037"
+down_revision = "0036"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("events", sa.Column("reminder_minutes", sa.Integer(), nullable=True))
+    op.add_column(
+        "events",
+        sa.Column("reminder_sent_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("events", "reminder_sent_at")
+    op.drop_column("events", "reminder_minutes")

alembic/versions/0038_add_rss_item_full_content.py

@@ -0,0 +1,34 @@
+"""Add content_full and context_prepared caches to rss_items.
+
+Revision ID: 0038
+Revises: 0037
+Create Date: 2026-04-13
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0038"
+down_revision = "0037"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("rss_items", sa.Column("content_full", sa.Text(), nullable=True))
+    op.add_column(
+        "rss_items",
+        sa.Column("context_prepared", sa.Text(), nullable=True),
+    )
+    op.add_column(
+        "rss_items",
+        sa.Column("content_fetched_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("rss_items", "content_fetched_at")
+    op.drop_column("rss_items", "context_prepared")
+    op.drop_column("rss_items", "content_full")

alembic/versions/0039_add_rss_item_discussion_note.py

@@ -0,0 +1,38 @@
+"""Link rss_items to their discussion-summary note.
+
+Revision ID: 0039
+Revises: 0038
+Create Date: 2026-04-14
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0039"
+down_revision = "0038"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "rss_items",
+        sa.Column("discussion_note_id", sa.BigInteger(), nullable=True),
+    )
+    op.create_foreign_key(
+        "fk_rss_items_discussion_note_id",
+        "rss_items",
+        "notes",
+        ["discussion_note_id"],
+        ["id"],
+        ondelete="SET NULL",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint(
+        "fk_rss_items_discussion_note_id", "rss_items", type_="foreignkey"
+    )
+    op.drop_column("rss_items", "discussion_note_id")

alembic/versions/0040_rename_briefing_date_drop_briefing_data.py

@@ -0,0 +1,26 @@
+"""rename briefing_date to day_date and drop existing briefing conversations
+
+Revision ID: 0040
+Revises: 0039
+Create Date: 2026-04-25
+
+This is a hard-cut migration accompanying the Journal feature. The user
+has accepted destruction of existing briefing data per the design spec.
+"""
+from alembic import op
+
+
+revision = "0040"
+down_revision = "0039"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("DELETE FROM conversations WHERE conversation_type = 'briefing'")
+    op.alter_column("conversations", "briefing_date", new_column_name="day_date")
+    op.execute("DELETE FROM settings WHERE key = 'briefing_config'")
+
+
+def downgrade() -> None:
+    op.alter_column("conversations", "day_date", new_column_name="briefing_date")

alembic/versions/0041_add_moments.py

@@ -0,0 +1,128 @@
+"""add moments + junction tables + moment embeddings
+
+Revision ID: 0041
+Revises: 0040
+Create Date: 2026-04-25
+
+People, Places, Tasks, and Notes all live in the `notes` table (distinguished
+by note_type and is_task). The four junction tables FK to notes(id) but stay
+separate so per-link-kind queries don't require a discriminator filter.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import ARRAY, JSONB
+
+
+revision = "0041"
+down_revision = "0040"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "moments",
+        sa.Column("id", sa.Integer, primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer,
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "conversation_id",
+            sa.Integer,
+            sa.ForeignKey("conversations.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column(
+            "source_message_id",
+            sa.Integer,
+            sa.ForeignKey("messages.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("day_date", sa.Date, nullable=False),
+        sa.Column("occurred_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column(
+            "recorded_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("content", sa.Text, nullable=False),
+        sa.Column("raw_excerpt", sa.Text, nullable=True),
+        sa.Column(
+            "tags",
+            ARRAY(sa.Text),
+            nullable=False,
+            server_default=sa.text("'{}'::text[]"),
+        ),
+        sa.Column(
+            "pinned",
+            sa.Boolean,
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )
+    op.create_index("ix_moments_user_day", "moments", ["user_id", "day_date"])
+    op.create_index("ix_moments_user_occurred", "moments", ["user_id", "occurred_at"])
+
+    # Four junction tables, all FK to notes(id). Separate (vs. one merged
+    # table with a discriminator) so per-kind queries don't need a filter.
+    for table_name, fk_col in [
+        ("moment_people", "person_id"),
+        ("moment_places", "place_id"),
+        ("moment_tasks", "task_id"),
+        ("moment_notes", "note_id"),
+    ]:
+        op.create_table(
+            table_name,
+            sa.Column(
+                "moment_id",
+                sa.Integer,
+                sa.ForeignKey("moments.id", ondelete="CASCADE"),
+                primary_key=True,
+            ),
+            sa.Column(
+                fk_col,
+                sa.Integer,
+                sa.ForeignKey("notes.id", ondelete="CASCADE"),
+                primary_key=True,
+            ),
+        )
+        op.create_index(f"ix_{table_name}_{fk_col}", table_name, [fk_col])
+
+    op.create_table(
+        "moment_embeddings",
+        sa.Column(
+            "moment_id",
+            sa.Integer,
+            sa.ForeignKey("moments.id", ondelete="CASCADE"),
+            primary_key=True,
+        ),
+        sa.Column("user_id", sa.Integer, nullable=False),
+        sa.Column("embedding", JSONB, nullable=False),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+    )
+    op.create_index("ix_moment_embeddings_user", "moment_embeddings", ["user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_moment_embeddings_user", table_name="moment_embeddings")
+    op.drop_table("moment_embeddings")
+    for table_name, fk_col in [
+        ("moment_notes", "note_id"),
+        ("moment_tasks", "task_id"),
+        ("moment_places", "place_id"),
+        ("moment_people", "person_id"),
+    ]:
+        op.drop_index(f"ix_{table_name}_{fk_col}", table_name=table_name)
+        op.drop_table(table_name)
+    op.drop_index("ix_moments_user_occurred", table_name="moments")
+    op.drop_index("ix_moments_user_day", table_name="moments")
+    op.drop_table("moments")

alembic/versions/0042_drop_rss.py

@@ -0,0 +1,36 @@
+"""drop RSS infrastructure (tables + leftover briefing settings)
+
+Revision ID: 0042
+Revises: 0041
+Create Date: 2026-04-26
+
+Hard-cut removal of the RSS feature. Drops rss_feeds, rss_items,
+rss_item_reactions, rss_item_embeddings, and clears the leftover
+briefing-era settings rows that referenced RSS topic preferences.
+"""
+from alembic import op
+
+
+revision = "0042"
+down_revision = "0041"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Drop in dependency order — children first.
+    op.execute("DROP TABLE IF EXISTS rss_item_embeddings CASCADE")
+    op.execute("DROP TABLE IF EXISTS rss_item_reactions CASCADE")
+    op.execute("DROP TABLE IF EXISTS rss_items CASCADE")
+    op.execute("DROP TABLE IF EXISTS rss_feeds CASCADE")
+    op.execute(
+        "DELETE FROM settings WHERE key IN "
+        "('rss_enabled', 'briefing_include_topics', 'briefing_exclude_topics')"
+    )
+
+
+def downgrade() -> None:
+    # No downgrade — this is a destructive cleanup. The original RSS tables
+    # would have to be recreated by replaying migrations 0026, 0028, 0035,
+    # 0038, 0039 manually (and the data would not come back).
+    raise NotImplementedError("RSS feature is permanently removed in 0042")

alembic/versions/0043_event_duration_replaces_end_dt.py

@@ -0,0 +1,73 @@
+"""replace events.end_dt with duration_minutes (Fable #160)
+
+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
+inexpressible at the schema level (duration_minutes >= 0).
+
+Backfill rules:
+  - end_dt valid (end_dt > start_dt) → duration_minutes = total minutes
+  - end_dt == start_dt → duration_minutes = 0 (zero-duration point)
+  - end_dt NULL OR end_dt < start_dt → duration_minutes = NULL (corrupt
+    or open-ended; treated as a point event from here on)
+
+Existing API consumers continue to receive `end_dt` in responses — the
+field is now derived from `start_dt + duration_minutes` in
+``Event.to_dict()`` rather than stored.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0043"
+down_revision = "0042"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "events",
+        sa.Column("duration_minutes", sa.Integer(), nullable=True),
+    )
+    op.create_check_constraint(
+        "events_duration_minutes_non_negative",
+        "events",
+        "duration_minutes IS NULL OR duration_minutes >= 0",
+    )
+    # Backfill: convert valid end_dt into a minute count; leave NULL for
+    # corrupt or absent end_dt. Bad rows (end_dt <= start_dt) collapse
+    # cleanly to point events instead of forcing a recovery guess.
+    op.execute(
+        """
+        UPDATE events
+        SET duration_minutes = CAST(
+            EXTRACT(EPOCH FROM (end_dt - start_dt)) / 60 AS INTEGER
+        )
+        WHERE end_dt IS NOT NULL AND end_dt >= start_dt
+        """
+    )
+    op.drop_column("events", "end_dt")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "events",
+        sa.Column("end_dt", sa.DateTime(timezone=True), nullable=True),
+    )
+    # Restore end_dt = start_dt + duration_minutes minutes for rows that
+    # had a duration. NULL duration → NULL end_dt (point event).
+    op.execute(
+        """
+        UPDATE events
+        SET end_dt = start_dt + (duration_minutes || ' minutes')::interval
+        WHERE duration_minutes IS NOT NULL
+        """
+    )
+    op.drop_constraint("events_duration_minutes_non_negative", "events")
+    op.drop_column("events", "duration_minutes")

alembic/versions/0044_add_note_description_and_consolidated_at.py

@@ -0,0 +1,48 @@
+"""add note.description and note.consolidated_at
+
+Revision ID: 0044
+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):
+
+- ``description``: user-stated goal / initial context. Meaningful when
+  ``is_task=true``; left NULL on knowledge notes.
+- ``consolidated_at``: timestamp of the most recent auto-summary pass. NULL
+  until the first consolidation runs.
+
+Backfill: for existing tasks we copy ``body`` into ``description`` so the
+user's original goal text is preserved when ``body`` is later overwritten by
+the auto-summary pipeline. The brief duplication window between
+``body`` and ``description`` is harmless and resolves on the first
+consolidation pass.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0044"
+down_revision = "0043"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("notes", sa.Column("description", sa.Text(), nullable=True))
+    op.add_column(
+        "notes",
+        sa.Column("consolidated_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    # is_task is a Python property (status IS NOT NULL); there's no DB column
+    # of that name. Backfill description from body for everything that
+    # qualifies as a task at the model layer.
+    op.execute(
+        "UPDATE notes SET description = body "
+        "WHERE status IS NOT NULL AND body IS NOT NULL"
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("notes", "consolidated_at")
+    op.drop_column("notes", "description")

alembic/versions/0045_add_note_version_pin_columns.py

@@ -0,0 +1,35 @@
+"""add pin_kind and pin_label to note_versions
+
+Revision ID: 0045
+Revises: 0044
+Create Date: 2026-05-13
+
+Two additive columns on note_versions to support tiered retention:
+
+- pin_kind: NULL (rolling autosave), 'auto' (system-declared via stability
+  scan), 'manual' (user-declared with optional commit-note label).
+- pin_label: NULL for rolling. Auto-generated for 'auto'; user-supplied
+  for 'manual' (may be NULL).
+
+No backfill — every existing row stays rolling. The auto-pin scan
+(services/version_pinning_scheduler.py, daily 03:00 UTC) will catch up on
+the first scheduled run after deploy.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0045"
+down_revision = "0044"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("note_versions", sa.Column("pin_kind", sa.Text(), nullable=True))
+    op.add_column("note_versions", sa.Column("pin_label", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("note_versions", "pin_label")
+    op.drop_column("note_versions", "pin_kind")

alembic/versions/0046_add_generation_tool_log.py

@@ -0,0 +1,103 @@
+"""generation_tool_log: per-turn tool-call telemetry
+
+Revision ID: 0046
+Revises: 0045
+Create Date: 2026-05-21
+
+Captures one row per assistant turn, recording which tools the model
+could have used, which it attempted, which fired successfully, and
+which failed (with error details). The empirical surface for
+evaluating model swaps and answering "does model X actually fire
+record_moment when it should?" without relying on anecdote.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import ARRAY, JSONB
+
+
+revision = "0046"
+down_revision = "0045"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "generation_tool_log",
+        sa.Column("id", sa.Integer, primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer,
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "conv_id",
+            sa.Integer,
+            sa.ForeignKey("conversations.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        # SET NULL (not CASCADE) so the telemetry row survives if the
+        # underlying assistant message is later deleted — we want to keep
+        # the per-turn outcome record for retrospective analysis.
+        sa.Column(
+            "assistant_message_id",
+            sa.Integer,
+            sa.ForeignKey("messages.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("model", sa.Text, nullable=False),
+        sa.Column("think_enabled", sa.Boolean, nullable=False),
+        sa.Column(
+            "tools_available",
+            ARRAY(sa.Text),
+            nullable=False,
+            server_default=sa.text("'{}'::text[]"),
+        ),
+        sa.Column(
+            "tools_attempted",
+            ARRAY(sa.Text),
+            nullable=False,
+            server_default=sa.text("'{}'::text[]"),
+        ),
+        sa.Column(
+            "tools_succeeded",
+            ARRAY(sa.Text),
+            nullable=False,
+            server_default=sa.text("'{}'::text[]"),
+        ),
+        # JSONB array of {name, error} objects so failed-tool details are
+        # queryable without a separate failure table.
+        sa.Column(
+            "tools_failed",
+            JSONB,
+            nullable=False,
+            server_default=sa.text("'[]'::jsonb"),
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+    )
+    # Common query: "recent tool outcomes for this user, filterable by model."
+    op.create_index(
+        "ix_generation_tool_log_user_created",
+        "generation_tool_log",
+        ["user_id", sa.text("created_at DESC")],
+    )
+    # Per-conversation lookup for the journal page's own retrospection.
+    op.create_index(
+        "ix_generation_tool_log_conv",
+        "generation_tool_log",
+        ["conv_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_generation_tool_log_conv", table_name="generation_tool_log")
+    op.drop_index(
+        "ix_generation_tool_log_user_created", table_name="generation_tool_log"
+    )
+    op.drop_table("generation_tool_log")

alembic/versions/0047_reset_voice_tts_settings.py

@@ -0,0 +1,38 @@
+"""reset voice_tts_voice and voice_tts_blend settings for piper migration
+
+Revision ID: 0047
+Revises: 0046
+Create Date: 2026-05-22
+
+The TTS backend swapped from kokoro to piper. Kokoro voice IDs
+(`af_heart`, `am_adam`, etc.) don't map to piper voice files
+(`en_US-amy-medium`, etc.) and there's no sensible auto-translation.
+Clear the stored voice selection so every user falls back to the piper
+default the next time they synthesize.
+
+`voice_tts_blend` goes away entirely — piper has no voice-blending
+equivalent. The TTS service accepts the field for backward compat but
+ignores it; clearing the rows makes the DB match reality.
+
+Both settings re-default cleanly on read, so this migration just deletes
+the rows without backfilling anything.
+"""
+from alembic import op
+
+
+revision = "0047"
+down_revision = "0046"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute(
+        "DELETE FROM settings WHERE key IN ('voice_tts_voice', 'voice_tts_blend')"
+    )
+
+
+def downgrade() -> None:
+    # No-op. The deleted settings just re-default on read; restoring the
+    # kokoro IDs wouldn't help anyway since kokoro is gone.
+    pass

alembic/versions/0048_conversation_last_curator_run.py

@@ -0,0 +1,47 @@
+"""conversations.last_curator_run_at — tracks scheduler progress per-conversation
+
+Revision ID: 0048
+Revises: 0047
+Create Date: 2026-05-22
+
+Phase 2 of the conversation+curator architecture (Fable #172). 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."
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0048"
+down_revision = "0047"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "conversations",
+        sa.Column(
+            "last_curator_run_at",
+            sa.DateTime(timezone=True),
+            nullable=True,
+        ),
+    )
+    # Indexed because the scheduler's selection query is
+    # WHERE conversation_type='journal' AND (last_curator_run_at IS NULL OR ...)
+    # which benefits from a partial index narrowed to journal rows.
+    op.create_index(
+        "ix_conversations_journal_last_curator",
+        "conversations",
+        ["last_curator_run_at"],
+        postgresql_where=sa.text("conversation_type = 'journal'"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_conversations_journal_last_curator",
+        table_name="conversations",
+    )
+    op.drop_column("conversations", "last_curator_run_at")

alembic/versions/0049_conversation_curator_summary.py

@@ -0,0 +1,36 @@
+"""conversations.curator_summary — feeds curator output back to the chat model
+
+Revision ID: 0049
+Revises: 0048
+Create Date: 2026-05-22
+
+Phase 3 of the conversation+curator architecture (Fable #172). 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
+model has no awareness of what the curator extracted, and conversations
+risk circling back to topics already captured.
+
+NULL means "no curator pass has produced a summary yet." The chat
+pipeline reads this column when building the journal system prompt;
+missing column = no injection, no failure.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0049"
+down_revision = "0048"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "conversations",
+        sa.Column("curator_summary", sa.Text, nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("conversations", "curator_summary")

alembic/versions/0050_drop_think_enabled_setting.py

@@ -0,0 +1,27 @@
+"""drop stored think_enabled rows — setting was removed
+
+Revision ID: 0050
+Revises: 0049
+Create Date: 2026-05-23
+
+The `think_enabled` user setting was retired with the chat+curator
+architecture: chat has tools=[] and curator hardcodes think=False, so
+the toggle was dead weight. Any rows already in `settings` for that
+key are now unread by the app; this migration clears them.
+"""
+from alembic import op
+
+
+revision = "0050"
+down_revision = "0049"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("DELETE FROM settings WHERE key = 'think_enabled'")
+
+
+def downgrade() -> None:
+    # No-op. The setting is dead; restoring NULL rows wouldn't help.
+    pass

alembic/versions/0051_pending_curator_actions.py

@@ -0,0 +1,98 @@
+"""pending_curator_actions — curator-proposed mutations awaiting user approval
+
+Revision ID: 0051
+Revises: 0050
+Create Date: 2026-05-23
+
+Architecture: the curator runs unattended and can be confidently wrong.
+Additive operations (create_*, record_moment, log_work, save_person)
+land directly because adds are easily undone. Mutating operations
+(update_*, delete_*) are proposed to this table instead — the user
+sees them in a "Needs Review" panel and approves or rejects each one.
+
+A proposed action stores:
+  - The action type (`update_task`, `delete_note`, etc.) — drives which
+    handler gets re-executed on approval.
+  - The target id + type for display ("update task 42", "delete note 17").
+  - The proposed arguments (`payload`) — what the curator wanted to do.
+  - A snapshot of the target's state at proposal time (`current_snapshot`)
+    — so the review UI can render a real before/after diff even if other
+    work modified the entity since.
+  - The status (`pending` / `approved` / `rejected`) and review timestamp.
+
+Approval replays the original tool call via execute_tool with
+authority="user" so the request bypasses the curator interceptor and
+just runs.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+revision = "0051"
+down_revision = "0050"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "pending_curator_actions",
+        sa.Column("id", sa.Integer, primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer,
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "conv_id",
+            sa.Integer,
+            sa.ForeignKey("conversations.id", ondelete="SET NULL"),
+            nullable=True,
+        ),
+        sa.Column("action_type", sa.Text, nullable=False),
+        sa.Column("target_type", sa.Text, nullable=True),
+        sa.Column("target_id", sa.Integer, nullable=True),
+        sa.Column("target_label", sa.Text, nullable=True),
+        sa.Column("payload", JSONB, nullable=False, server_default=sa.text("'{}'::jsonb")),
+        sa.Column(
+            "current_snapshot",
+            JSONB,
+            nullable=False,
+            server_default=sa.text("'{}'::jsonb"),
+        ),
+        sa.Column(
+            "status",
+            sa.Text,
+            nullable=False,
+            server_default=sa.text("'pending'"),
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=True),
+        sa.CheckConstraint(
+            "status IN ('pending', 'approved', 'rejected')",
+            name="pending_curator_actions_status_check",
+        ),
+    )
+    # Pending-only index — the Needs Review panel fetches "user's pending"
+    # constantly, history rows just accumulate.
+    op.create_index(
+        "ix_pending_curator_actions_user_pending",
+        "pending_curator_actions",
+        ["user_id", sa.text("created_at DESC")],
+        postgresql_where=sa.text("status = 'pending'"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_pending_curator_actions_user_pending",
+        table_name="pending_curator_actions",
+    )
+    op.drop_table("pending_curator_actions")

alembic/versions/0052_clear_note_embeddings_for_fastembed.py

@@ -0,0 +1,33 @@
+"""clear note_embeddings for fastembed swap
+
+Revision ID: 0052
+Revises: 0051
+Create Date: 2026-05-26
+
+Embeddings stored in `note_embeddings.embedding` (JSONB) were generated by
+Ollama's nomic-embed-text model (768-dim). The fastembed swap uses
+BAAI/bge-small-en-v1.5 (384-dim). Mixed-dim vectors would break the
+Python-side cosine similarity (length mismatch), so we wipe the table.
+
+The startup hook `services.embeddings.backfill_note_embeddings` regenerates
+everything at the new dimension on next boot. There's no column-type change
+because the column is JSONB — dimensionless on the storage side.
+
+Downgrade is the same operation: a fresh deployment of the prior code would
+backfill with the old model. No data is lost that the next boot won't restore.
+"""
+from alembic import op
+
+
+revision = "0052"
+down_revision = "0051"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("DELETE FROM note_embeddings")
+
+
+def downgrade() -> None:
+    op.execute("DELETE FROM note_embeddings")

alembic/versions/0053_drop_chat_journal_push_curator_tables.py

@@ -0,0 +1,82 @@
+"""drop chat / journal / push / curator / weather tables
+
+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
+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.
+"""
+from alembic import op
+
+
+revision = "0053"
+down_revision = "0052"
+branch_labels = None
+depends_on = None
+
+
+# Order: junction tables first so the parent tables don't trip FK drops
+# even with CASCADE — keeps the migration readable.
+_DEAD_TABLES = [
+    # Moments + junction tables (journal entity links)
+    "moment_notes",
+    "moment_tasks",
+    "moment_places",
+    "moment_people",
+    "moment_embeddings",
+    "moments",
+    # Chat / generation telemetry
+    "generation_tool_log",
+    "messages",
+    "conversations",
+    # Curator approval queue
+    "pending_curator_actions",
+    # Push notifications
+    "push_subscriptions",
+    # Weather cache (journal-prep background fetcher)
+    "weather_cache",
+    # Legacy RSS-item embeddings (pre-MCP pivot, briefly experimented with)
+    "rss_item_embeddings",
+]
+
+
+# Specific setting keys to drop. Anything matching the LIKE patterns in
+# upgrade() is also nuked; the explicit list catches one-off keys that
+# don't fit the namespaced patterns.
+_DEAD_SETTING_KEYS = [
+    "default_model",
+    "background_model",
+    "assistant_name",
+    "auto_consolidate_tasks",
+    "chat_retention_days",
+    "think_enabled",
+    "rag_default_scope",
+]
+
+
+def upgrade() -> None:
+    for table in _DEAD_TABLES:
+        op.execute(f"DROP TABLE IF EXISTS {table} CASCADE")
+
+    keys_csv = ",".join(f"'{k}'" for k in _DEAD_SETTING_KEYS)
+    op.execute(
+        "DELETE FROM settings WHERE "
+        "key LIKE 'voice_%' OR "
+        "key LIKE 'journal_%' OR "
+        "key LIKE 'briefing_%' OR "
+        "key LIKE 'curator_%' OR "
+        f"key IN ({keys_csv})"
+    )
+
+
+def downgrade() -> None:
+    raise NotImplementedError(
+        "No downgrade — hard cutover per the MCP-first pivot spec. "
+        "Rolling back is not supported at the database layer."
+    )

alembic/versions/0054_drop_image_cache.py

@@ -0,0 +1,26 @@
+"""drop image_cache table
+
+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).
+With no producer or consumer left, the table is dropped here.
+"""
+from alembic import op
+
+
+revision = "0054"
+down_revision = "0053"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("DROP TABLE IF EXISTS image_cache CASCADE")
+
+
+def downgrade() -> None:
+    raise NotImplementedError(
+        "No downgrade — hard cutover per the MCP-first pivot spec."
+    )

alembic/versions/0055_rulebook_tables.py

@@ -0,0 +1,153 @@
+"""rulebook tables: rulebooks, rulebook_topics, rules, project_rulebook_subscriptions
+
+Revision ID: 0055
+Revises: 0054
+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.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0055"
+down_revision = "0054"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "rulebooks",
+        sa.Column("id", sa.BigInteger, primary_key=True),
+        sa.Column(
+            "owner_user_id",
+            sa.BigInteger,
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("title", sa.Text, nullable=False),
+        sa.Column("description", sa.Text),
+        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_index("ix_rulebooks_owner", "rulebooks", ["owner_user_id"])
+
+    op.create_table(
+        "rulebook_topics",
+        sa.Column("id", sa.BigInteger, primary_key=True),
+        sa.Column(
+            "rulebook_id",
+            sa.BigInteger,
+            sa.ForeignKey("rulebooks.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("title", sa.Text, nullable=False),
+        sa.Column("description", sa.Text),
+        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.UniqueConstraint("rulebook_id", "title", name="uq_topic_per_rulebook"),
+    )
+    op.create_index(
+        "ix_rulebook_topics_rulebook", "rulebook_topics", ["rulebook_id"],
+    )
+
+    op.create_table(
+        "rules",
+        sa.Column("id", sa.BigInteger, primary_key=True),
+        sa.Column(
+            "topic_id",
+            sa.BigInteger,
+            sa.ForeignKey("rulebook_topics.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("title", sa.Text, nullable=False),
+        sa.Column("statement", sa.Text, nullable=False),
+        sa.Column("why", sa.Text),
+        sa.Column("how_to_apply", sa.Text),
+        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.UniqueConstraint("topic_id", "title", name="uq_rule_per_topic"),
+    )
+    op.create_index("ix_rules_topic", "rules", ["topic_id"])
+
+    op.create_table(
+        "project_rulebook_subscriptions",
+        sa.Column(
+            "project_id",
+            sa.BigInteger,
+            sa.ForeignKey("projects.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "rulebook_id",
+            sa.BigInteger,
+            sa.ForeignKey("rulebooks.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.PrimaryKeyConstraint("project_id", "rulebook_id"),
+    )
+    op.create_index(
+        "ix_project_rulebook_subs_rulebook",
+        "project_rulebook_subscriptions",
+        ["rulebook_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(
+        "ix_project_rulebook_subs_rulebook",
+        table_name="project_rulebook_subscriptions",
+    )
+    op.drop_table("project_rulebook_subscriptions")
+    op.drop_index("ix_rules_topic", table_name="rules")
+    op.drop_table("rules")
+    op.drop_index("ix_rulebook_topics_rulebook", table_name="rulebook_topics")
+    op.drop_table("rulebook_topics")
+    op.drop_index("ix_rulebooks_owner", table_name="rulebooks")
+    op.drop_table("rulebooks")

alembic/versions/0056_task_kind.py

@@ -0,0 +1,35 @@
+"""task_kind column on notes: distinguishes plan-tasks from work-tasks
+
+Revision ID: 0056
+Revises: 0055
+Create Date: 2026-05-28
+
+A plan is a Task (a note with non-null status) marked task_kind='plan'.
+The CHECK constraint lands in the same migration as the value set, per the
+'new CHECK-enum values need a same-change migration' rule.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0056"
+down_revision = "0055"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "notes",
+        sa.Column(
+            "task_kind", sa.Text(), nullable=False, server_default="work",
+        ),
+    )
+    op.create_check_constraint(
+        "notes_task_kind_check", "notes", "task_kind IN ('work','plan')",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("notes_task_kind_check", "notes", type_="check")
+    op.drop_column("notes", "task_kind")

alembic/versions/0057_soft_delete.py

@@ -0,0 +1,38 @@
+"""soft-delete: deleted_at + deleted_batch_id on 7 tables
+
+Revision ID: 0057
+Revises: 0056
+Create Date: 2026-05-28
+
+Recoverable deletes: each soft-deletable table gains a nullable deleted_at
+timestamp (NULL = live) and a deleted_batch_id (text UUID) stamped per delete
+operation so a cascaded delete restores as a unit. A daily cron purges rows
+past the retention window.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0057"
+down_revision = "0056"
+branch_labels = None
+depends_on = None
+
+_TABLES = (
+    "notes", "events", "projects", "milestones",
+    "rulebooks", "rulebook_topics", "rules",
+)
+
+
+def upgrade() -> None:
+    for t in _TABLES:
+        op.add_column(t, sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True))
+        op.add_column(t, sa.Column("deleted_batch_id", sa.Text(), nullable=True))
+        op.create_index(f"ix_{t}_deleted_at", t, ["deleted_at"])
+
+
+def downgrade() -> None:
+    for t in reversed(_TABLES):
+        op.drop_index(f"ix_{t}_deleted_at", table_name=t)
+        op.drop_column(t, "deleted_batch_id")
+        op.drop_column(t, "deleted_at")

alembic/versions/0058_rulebook_always_on.py

@@ -0,0 +1,39 @@
+"""rulebook always_on flag
+
+Revision ID: 0058
+Revises: 0057
+Create Date: 2026-06-01
+
+Adds a boolean `always_on` to the `rulebooks` table. Rules from rulebooks
+flagged always_on are loaded at session start by the new
+`list_always_on_rules` MCP tool — they apply regardless of which project
+(if any) is in scope. Seeds the FabledSword family rulebook to always_on
+because that's the cross-project standards rulebook by design.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0058"
+down_revision = "0057"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "rulebooks",
+        sa.Column(
+            "always_on",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )
+    op.execute(
+        "UPDATE rulebooks SET always_on = TRUE WHERE title = 'FabledSword family'"
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("rulebooks", "always_on")

alembic/versions/0059_rule_project_scope.py

@@ -0,0 +1,49 @@
+"""project-scoped rules
+
+Revision ID: 0059
+Revises: 0058
+Create Date: 2026-06-01
+
+Rules can now belong to either a rulebook topic (cross-project standard) or
+a single project (project-scoped). Adds `rules.project_id`, makes `topic_id`
+nullable, and adds a CHECK constraint enforcing exactly-one. The previous
+unique constraint on (topic_id, title) still applies because PostgreSQL
+treats NULL as distinct — two project-scoped rules with the same title and
+NULL topic_id remain unique.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0059"
+down_revision = "0058"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "rules",
+        sa.Column(
+            "project_id",
+            sa.BigInteger(),
+            sa.ForeignKey("projects.id", ondelete="CASCADE"),
+            nullable=True,
+        ),
+    )
+    op.alter_column("rules", "topic_id", nullable=True)
+    op.create_index("ix_rules_project_id", "rules", ["project_id"])
+    op.create_check_constraint(
+        "ck_rule_topic_xor_project",
+        "rules",
+        "(topic_id IS NULL) <> (project_id IS NULL)",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("ck_rule_topic_xor_project", "rules", type_="check")
+    op.drop_index("ix_rules_project_id", table_name="rules")
+    # Any rule with NULL topic_id will block re-tightening. Operator must
+    # migrate or delete project-scoped rules before downgrading.
+    op.alter_column("rules", "topic_id", nullable=False)
+    op.drop_column("rules", "project_id")

alembic/versions/0060_project_rule_suppressions.py

@@ -0,0 +1,73 @@
+"""project rule + topic suppressions
+
+Revision ID: 0060
+Revises: 0059
+Create Date: 2026-06-01
+
+Lets a project mute specific rules or whole topics from rulebooks it
+subscribes to, without unsubscribing the rulebook. Two pure many-to-many
+association tables; FKs CASCADE so removing a project / rule / topic
+cleans the suppression rows automatically.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0060"
+down_revision = "0059"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "project_rule_suppressions",
+        sa.Column(
+            "project_id",
+            sa.BigInteger(),
+            sa.ForeignKey("projects.id", ondelete="CASCADE"),
+            primary_key=True,
+            nullable=False,
+        ),
+        sa.Column(
+            "rule_id",
+            sa.BigInteger(),
+            sa.ForeignKey("rules.id", ondelete="CASCADE"),
+            primary_key=True,
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+    )
+    op.create_table(
+        "project_topic_suppressions",
+        sa.Column(
+            "project_id",
+            sa.BigInteger(),
+            sa.ForeignKey("projects.id", ondelete="CASCADE"),
+            primary_key=True,
+            nullable=False,
+        ),
+        sa.Column(
+            "topic_id",
+            sa.BigInteger(),
+            sa.ForeignKey("rulebook_topics.id", ondelete="CASCADE"),
+            primary_key=True,
+            nullable=False,
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("project_topic_suppressions")
+    op.drop_table("project_rule_suppressions")

alembic/versions/0061_partial_unique_topic_rule_titles.py

@@ -0,0 +1,49 @@
+"""partial-unique topic/rule titles (ignore soft-deleted rows)
+
+Revision ID: 0061
+Revises: 0060
+Create Date: 2026-06-02
+
+Topics and rules are soft-deleted (SoftDeleteMixin), but uq_topic_per_rulebook
+and uq_rule_per_topic were plain UNIQUE constraints. Trashing a topic/rule
+named "X" then creating a new "X" — or restoring into a reused title slot —
+collided with the dead row and raised an unhandled 500. Replace the full
+UNIQUE constraints with partial unique indexes that only consider live
+(deleted_at IS NULL) rows.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0061"
+down_revision = "0060"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_constraint("uq_topic_per_rulebook", "rulebook_topics", type_="unique")
+    op.create_index(
+        "uq_topic_per_rulebook",
+        "rulebook_topics",
+        ["rulebook_id", "title"],
+        unique=True,
+        postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+    op.drop_constraint("uq_rule_per_topic", "rules", type_="unique")
+    op.create_index(
+        "uq_rule_per_topic",
+        "rules",
+        ["topic_id", "title"],
+        unique=True,
+        postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("uq_rule_per_topic", table_name="rules")
+    op.create_unique_constraint("uq_rule_per_topic", "rules", ["topic_id", "title"])
+    op.drop_index("uq_topic_per_rulebook", table_name="rulebook_topics")
+    op.create_unique_constraint(
+        "uq_topic_per_rulebook", "rulebook_topics", ["rulebook_id", "title"]
+    )

alembic/versions/0062_drop_userprofile_curator_columns.py

@@ -0,0 +1,41 @@
+"""drop dead UserProfile curator columns
+
+Revision ID: 0062
+Revises: 0061
+Create Date: 2026-06-02
+
+learned_summary, observations_raw, and observations_updated_at were written by
+the curator/LLM-profile machinery removed in the Phase-8 MCP pivot. Nothing has
+populated them since; the profile API returned permanently-empty fields. Drop
+the columns.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+revision = "0062"
+down_revision = "0061"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_column("user_profiles", "learned_summary")
+    op.drop_column("user_profiles", "observations_raw")
+    op.drop_column("user_profiles", "observations_updated_at")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "user_profiles",
+        sa.Column("observations_updated_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "user_profiles",
+        sa.Column("observations_raw", postgresql.JSONB(), nullable=True),
+    )
+    op.add_column(
+        "user_profiles",
+        sa.Column("learned_summary", sa.Text(), nullable=True),
+    )

alembic/versions/0063_drop_project_auto_summary.py

@@ -0,0 +1,34 @@
+"""drop dead Project.auto_summary columns
+
+Revision ID: 0063
+Revises: 0062
+Create Date: 2026-06-03
+
+auto_summary + summary_updated_at were written by generate_project_summary
+(Ollama), removed in the MCP pivot. Nothing has populated them since; the
+field was stale-or-NULL. Drop the columns.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0063"
+down_revision = "0062"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.drop_column("projects", "auto_summary")
+    op.drop_column("projects", "summary_updated_at")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "projects",
+        sa.Column("summary_updated_at", sa.DateTime(timezone=True), nullable=True),
+    )
+    op.add_column(
+        "projects",
+        sa.Column("auto_summary", sa.Text(), nullable=True),
+    )

alembic/versions/0064_repo_bindings.py

@@ -0,0 +1,58 @@
+"""repo -> project bindings
+
+Revision ID: 0064
+Revises: 0063
+Create Date: 2026-06-10
+
+Maps a git repository (by its normalized remote, `repo_key`) to the Scribe
+project it represents, so the SessionStart hook can resolve the active project
+from the working repo instead of a project id pinned in plugin config. FKs
+CASCADE so deleting a user or project removes the stale binding automatically.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0064"
+down_revision = "0063"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "repo_bindings",
+        sa.Column("id", sa.BigInteger(), primary_key=True, autoincrement=True),
+        sa.Column(
+            "user_id",
+            sa.BigInteger(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column(
+            "project_id",
+            sa.BigInteger(),
+            sa.ForeignKey("projects.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("repo_key", sa.Text(), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("user_id", "repo_key", name="uq_repo_bindings_user_repo"),
+    )
+    op.create_index("ix_repo_bindings_user_id", "repo_bindings", ["user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_repo_bindings_user_id", table_name="repo_bindings")
+    op.drop_table("repo_bindings")

alembic/versions/0065_issues_and_systems.py

@@ -0,0 +1,103 @@
+"""issues + systems: task_kind=issue, systems, record_systems, arose_from_id
+
+Revision ID: 0065
+Revises: 0064
+Create Date: 2026-06-14
+
+Adds the corrective-work 'issue' task_kind (same-change CHECK expand per the
+'new CHECK-enum values need a same-change migration' rule), a per-project
+self-describing System entity, a many-to-many record<->system join (any
+note/task/issue), and an issue->originating-task provenance FK.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0065"
+down_revision = "0064"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # 1. task_kind gains 'issue' (corrective work). DROP+ADD the CHECK in the
+    #    same change that introduces the value.
+    op.drop_constraint("notes_task_kind_check", "notes", type_="check")
+    op.create_check_constraint(
+        "notes_task_kind_check", "notes", "task_kind IN ('work','plan','issue')",
+    )
+
+    # 2. Provenance: an issue can point back at the task/feature it arose from.
+    #    Distinct from parent_id (sub-task hierarchy).
+    op.add_column("notes", sa.Column("arose_from_id", sa.Integer(), nullable=True))
+    op.create_foreign_key(
+        "fk_notes_arose_from_id", "notes", "notes",
+        ["arose_from_id"], ["id"], ondelete="SET NULL",
+    )
+    op.create_index("ix_notes_arose_from_id", "notes", ["arose_from_id"])
+
+    # 3. systems: per-project, reusable, self-describing subsystem/area.
+    op.create_table(
+        "systems",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id", sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column(
+            "project_id", sa.Integer(),
+            sa.ForeignKey("projects.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column("name", sa.Text(), nullable=False, server_default=""),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("color", sa.Text(), nullable=True),
+        sa.Column("status", sa.Text(), nullable=False, server_default="active"),
+        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),
+    )
+    op.create_index("ix_systems_project_id", "systems", ["project_id"])
+    op.create_check_constraint(
+        "systems_status_check", "systems", "status IN ('active','archived')",
+    )
+
+    # 4. record_systems: M2M join — any note/task/issue <-> system.
+    op.create_table(
+        "record_systems",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "note_id", sa.Integer(),
+            sa.ForeignKey("notes.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column(
+            "system_id", sa.Integer(),
+            sa.ForeignKey("systems.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.UniqueConstraint("note_id", "system_id", name="uq_record_systems_note_system"),
+    )
+    op.create_index("ix_record_systems_note_id", "record_systems", ["note_id"])
+    op.create_index("ix_record_systems_system_id", "record_systems", ["system_id"])
+
+
+def downgrade() -> None:
+    op.drop_table("record_systems")
+    op.drop_table("systems")
+    op.drop_index("ix_notes_arose_from_id", table_name="notes")
+    op.drop_constraint("fk_notes_arose_from_id", "notes", type_="foreignkey")
+    op.drop_column("notes", "arose_from_id")
+    op.drop_constraint("notes_task_kind_check", "notes", type_="check")
+    op.create_check_constraint(
+        "notes_task_kind_check", "notes", "task_kind IN ('work','plan')",
+    )

alembic/versions/0066_milestone_body.py

@@ -0,0 +1,32 @@
+"""milestone-as-plan-container: milestones.body holds the plan/design
+
+Revision ID: 0066
+Revises: 0065
+Create Date: 2026-06-14
+
+T3 of plan #819. 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
+create a milestone instead of a kind=plan task (hard retirement going forward;
+the 'plan' task_kind enum value stays valid so the historical plan-tasks are
+left readable in place — no body-shredding backfill).
+
+Schema change is just one nullable column; no data migration.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0066"
+down_revision = "0065"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("milestones", sa.Column("body", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("milestones", "body")

alembic/versions/0067_pgvector_note_embeddings.py

@@ -0,0 +1,73 @@
+"""pgvector: note_embeddings.embedding JSONB -> vector(384) + HNSW index
+
+Revision ID: 0067
+Revises: 0066
+Create Date: 2026-06-22
+
+Moves semantic search off the full-table Python cosine scan onto a native
+pgvector column so ranking + top-k run as an indexed `ORDER BY embedding <=> :q
+LIMIT k` in Postgres (see services/embeddings.semantic_search_notes).
+
+Requires a Postgres image that bundles the `vector` extension — the stack moved
+from postgres:16-alpine to pgvector/pgvector:pg16 in the same change (compose +
+CI). `CREATE EXTENSION IF NOT EXISTS vector` below is the in-db half.
+
+Embeddings are DERIVED data (regenerated from note text by
+backfill_note_embeddings at startup), so this migration is free to drop any row
+it can't cleanly convert: only rows whose stored JSONB array is exactly 384-dim
+are carried over (guarding against stale vectors from an earlier model — the
+same mixed-dim hazard _cosine_similarity defended against). Dropped rows are
+re-embedded on next boot.
+"""
+from alembic import op
+
+
+revision = "0067"
+down_revision = "0066"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.execute("CREATE EXTENSION IF NOT EXISTS vector")
+
+    # New native-vector column, populated only from cleanly-convertible rows.
+    # A JSONB array like [0.1, 0.2, ...] renders to text that is exactly
+    # pgvector's input literal, so (embedding::text)::vector is a direct cast.
+    op.execute("ALTER TABLE note_embeddings ADD COLUMN embedding_vec vector(384)")
+    op.execute(
+        """
+        UPDATE note_embeddings
+           SET embedding_vec = (embedding::text)::vector
+         WHERE jsonb_array_length(embedding) = 384
+        """
+    )
+    # Stale-dim rows (couldn't convert) are derived data — drop and let the
+    # startup backfill regenerate them at the current dimension.
+    op.execute("DELETE FROM note_embeddings WHERE embedding_vec IS NULL")
+
+    op.execute("ALTER TABLE note_embeddings ALTER COLUMN embedding_vec SET NOT NULL")
+    op.execute("ALTER TABLE note_embeddings DROP COLUMN embedding")
+    op.execute("ALTER TABLE note_embeddings RENAME COLUMN embedding_vec TO embedding")
+
+    # HNSW index for cosine distance — matches Vector.cosine_distance (`<=>`).
+    op.execute(
+        """
+        CREATE INDEX ix_note_embeddings_embedding_hnsw
+            ON note_embeddings
+         USING hnsw (embedding vector_cosine_ops)
+        """
+    )
+
+
+def downgrade() -> None:
+    # Back to JSONB. pgvector renders a vector to a text literal that is a valid
+    # JSON array, so the reverse cast is symmetric. The `vector` extension is
+    # intentionally left installed (other objects may depend on it; dropping an
+    # extension is the riskier, rarely-wanted direction).
+    op.execute("DROP INDEX IF EXISTS ix_note_embeddings_embedding_hnsw")
+    op.execute("ALTER TABLE note_embeddings ADD COLUMN embedding_json jsonb")
+    op.execute("UPDATE note_embeddings SET embedding_json = (embedding::text)::jsonb")
+    op.execute("ALTER TABLE note_embeddings ALTER COLUMN embedding_json SET NOT NULL")
+    op.execute("ALTER TABLE note_embeddings DROP COLUMN embedding")
+    op.execute("ALTER TABLE note_embeddings RENAME COLUMN embedding_json TO embedding")

alembic/versions/0068_retrieval_logs.py

@@ -0,0 +1,60 @@
+"""retrieval_logs: per-call semantic-retrieval telemetry for KB-injection tuning
+
+Revision ID: 0068
+Revises: 0067
+Create Date: 2026-06-22
+
+One row per semantic-retrieval call (MCP search tool, REST search route, and —
+once it lands — the title-first auto-inject path). Captures the effective query
+params and the score distribution of the results so the similarity threshold
+and top-k can be tuned from real usage. FK-free on user_id (mirrors app_logs):
+telemetry should outlive the row it describes.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+revision = "0068"
+down_revision = "0067"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "retrieval_logs",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True), nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("user_id", sa.Integer(), nullable=True),
+        sa.Column("source", sa.Text(), nullable=False),
+        sa.Column("query", sa.Text(), nullable=True),
+        sa.Column("threshold", sa.Float(), nullable=True),
+        sa.Column("limit_n", sa.Integer(), nullable=True),
+        sa.Column("project_id", sa.Integer(), nullable=True),
+        sa.Column("is_task", sa.Boolean(), nullable=True),
+        sa.Column("result_count", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("top_score", sa.Float(), nullable=True),
+        sa.Column("min_score", sa.Float(), nullable=True),
+        sa.Column("result_ids", JSONB(), nullable=False, server_default=sa.text("'[]'::jsonb")),
+        sa.Column("duration_ms", sa.Float(), nullable=True),
+    )
+    op.create_index("ix_retrieval_logs_created_at", "retrieval_logs", ["created_at"])
+    op.create_index("ix_retrieval_logs_user_id", "retrieval_logs", ["user_id"])
+    op.create_index("ix_retrieval_logs_source", "retrieval_logs", ["source"])
+    op.create_index(
+        "ix_retrieval_logs_source_created_at",
+        "retrieval_logs",
+        ["source", sa.text("created_at DESC")],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_retrieval_logs_source_created_at", table_name="retrieval_logs")
+    op.drop_index("ix_retrieval_logs_source", table_name="retrieval_logs")
+    op.drop_index("ix_retrieval_logs_user_id", table_name="retrieval_logs")
+    op.drop_index("ix_retrieval_logs_created_at", table_name="retrieval_logs")
+    op.drop_table("retrieval_logs")

alembic/versions/0069_drop_events_and_entity_metadata.py

@@ -0,0 +1,82 @@
+"""drop events table + notes.metadata column (retire calendar + entity surfaces)
+
+Revision ID: 0069
+Revises: 0068
+Create Date: 2026-07-19
+
+The personal-assistant surfaces (calendar/events + CalDAV, and the typed
+person/place/list entities that stored structured fields in notes.metadata)
+were removed when Scribe narrowed to a Claude-Code work system-of-record.
+This migration drops their storage:
+
+  - the `events` table (all calendar/CalDAV data)
+  - the `notes.metadata` (entity_meta) JSONB column — it only ever held
+    person/place/list structured fields. The `note_type` column STAYS: it
+    also distinguishes 'process' notes.
+  - orphan CalDAV settings rows (nothing reads them after the removal)
+
+Downgrade recreates the table + column structure at its pre-removal shape.
+The dropped data itself is not recoverable.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+revision = "0069"
+down_revision = "0068"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Entity metadata column (person/place/list structured fields). The
+    # note_type column is intentionally kept — it also marks 'process' notes.
+    op.drop_column("notes", "metadata")
+
+    # Calendar / CalDAV storage. Dropping the table drops its indexes + the
+    # duration CHECK constraint with it.
+    op.drop_table("events")
+
+    # Orphan CalDAV integration settings — no code reads them post-removal.
+    op.execute("DELETE FROM settings WHERE key LIKE 'caldav%'")
+
+
+def downgrade() -> None:
+    # Recreate the events table at its pre-removal schema (empty — the data is
+    # gone). Mirrors the model as of 0037 (reminders) + 0043 (duration_minutes)
+    # + 0057 (soft-delete columns/index).
+    op.create_table(
+        "events",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("user_id", sa.Integer(),
+                  sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("project_id", sa.Integer(),
+                  sa.ForeignKey("projects.id", ondelete="SET NULL"), nullable=True),
+        sa.Column("uid", sa.Text(), nullable=False),
+        sa.Column("title", sa.Text(), nullable=False, server_default=""),
+        sa.Column("start_dt", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("duration_minutes", sa.Integer(), nullable=True),
+        sa.Column("all_day", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column("description", sa.Text(), nullable=False, server_default=""),
+        sa.Column("location", sa.Text(), nullable=False, server_default=""),
+        sa.Column("caldav_uid", sa.Text(), nullable=False, server_default=""),
+        sa.Column("color", sa.Text(), nullable=False, server_default=""),
+        sa.Column("recurrence", sa.Text(), nullable=True),
+        sa.Column("reminder_minutes", sa.Integer(), nullable=True),
+        sa.Column("reminder_sent_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True),
+                  nullable=False, server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True),
+                  nullable=False, server_default=sa.func.now()),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("deleted_batch_id", sa.Text(), nullable=True),
+        sa.CheckConstraint(
+            "duration_minutes IS NULL OR duration_minutes >= 0",
+            name="events_duration_minutes_non_negative",
+        ),
+    )
+    op.create_index("ix_events_deleted_at", "events", ["deleted_at"])
+
+    # Re-add the entity metadata column.
+    op.add_column("notes", sa.Column("metadata", JSONB(), nullable=True))

alembic/versions/0070_notes_data_jsonb.py

@@ -0,0 +1,60 @@
+"""add notes.data JSONB — queryable structured fields for typed records
+
+Revision ID: 0070
+Revises: 0069
+Create Date: 2026-07-26
+
+Snippets (note_type='snippet') carry structured fields — name, language,
+signature, and a list of canonical locations (repo · path · symbol). Those were
+stored as a markdown body-convention, which reads well and feeds the embedding
+but cannot be QUERIED: answering "which snippets live in this file?" meant
+scanning every snippet and regexing its body.
+
+This adds a general `data` JSONB column plus a GIN index, so those fields become
+indexable. The body stays exactly as it was — it is still the human-readable
+form and still what gets embedded. `data` is a queryable mirror of the same
+facts, not a replacement, and the code itself is deliberately NOT copied into it
+(the body already holds it; duplicating a blob to index fields around it would
+be waste).
+
+Relationship to 0069: that migration DROPPED `notes.metadata`, a JSONB column
+which only ever held person/place/list entity fields, when those surfaces were
+removed. This is not a revival of it — different name, different purpose, and
+nothing reads the old shape. The column is named `data` rather than `metadata`
+because `metadata` collides with SQLAlchemy's declarative `Base.metadata`, which
+is why the old model had to map an awkward `entity_metadata` attribute onto it.
+
+Nullable with no backfill, deliberately: rows written before this migration keep
+working because the service falls back to parsing the body when `data` is
+absent. That means no migration deadline and no risk of a backfill mangling a
+hand-edited body.
+
+Downgrade drops the index and the column. Any structured fields it held remain
+recoverable from the body convention, which is the same source they mirror.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+revision = "0070"
+down_revision = "0069"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("notes", sa.Column("data", JSONB, nullable=True))
+    # GIN supports containment (`data @> '{"locations":[{"repo":"x"}]}'`), which
+    # covers exact repo/path/symbol and language lookups. Path PREFIX matching
+    # ("everything under frontend/src/") is not an index-served operation here
+    # and still filters after the fact — acceptable while snippet counts are
+    # small, and a generated column is the escape hatch if that changes.
+    op.create_index(
+        "ix_notes_data_gin", "notes", ["data"], postgresql_using="gin",
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_notes_data_gin", table_name="notes")
+    op.drop_column("notes", "data")

alembic/versions/0071_note_usage_events.py

@@ -0,0 +1,72 @@
+"""add note_usage_events — did anyone actually open what we surfaced?
+
+Revision ID: 0071
+Revises: 0070
+Create Date: 2026-07-28
+
+`retrieval_logs` records what the ranker returned and with what scores, which is
+the right substrate for tuning a similarity threshold. It cannot answer the
+different question the snippet corpus needs: was a surfaced snippet ever pulled
+in full? A snippet nobody opens still competes for the injection budget on every
+turn, so the surfaced:pulled ratio is what makes dead weight visible.
+
+Two reasons this is its own table rather than columns on `notes` or rows in
+`retrieval_logs`:
+
+  - Counters on `notes` would answer "how many" but not "when, from where, and
+    by which arm" — and the place arm vs semantic arm comparison is precisely
+    what was missing (the write-path place arm surfaced snippets while leaving
+    no trace anywhere).
+  - Folding un-scored surfacing into `retrieval_logs` would corrupt the score
+    distribution that table exists to capture. Location hits have no score.
+
+Grain is one row per note per event, which is what the per-snippet readout needs
+and what `retrieval_logs.result_ids` (a JSONB array, one row per *call*) cannot
+be indexed at.
+
+FK-free on note_id and user_id, matching retrieval_logs and app_logs: telemetry
+should outlive what it describes. Deleting a note must not erase the evidence
+that it was surfaced forty times and opened none.
+
+Downgrade drops the table outright. The data is purely observational — nothing
+reads it for correctness, so losing it costs history and no behavior.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0071"
+down_revision = "0070"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "note_usage_events",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now()"),
+        ),
+        sa.Column("user_id", sa.Integer(), nullable=True),
+        sa.Column("note_id", sa.Integer(), nullable=False),
+        sa.Column("event", sa.Text(), nullable=False),
+        sa.Column("source", sa.Text(), nullable=False),
+    )
+    # Every readout is "these note ids, split by event", so the composite is the
+    # one that actually gets used; the others serve pruning and per-user views.
+    op.create_index(
+        "ix_note_usage_note_event", "note_usage_events", ["note_id", "event"]
+    )
+    op.create_index("ix_note_usage_created_at", "note_usage_events", ["created_at"])
+    op.create_index("ix_note_usage_user_id", "note_usage_events", ["user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_note_usage_user_id", table_name="note_usage_events")
+    op.drop_index("ix_note_usage_created_at", table_name="note_usage_events")
+    op.drop_index("ix_note_usage_note_event", table_name="note_usage_events")
+    op.drop_table("note_usage_events")

alembic/versions/0072_design_systems.py

@@ -0,0 +1,138 @@
+"""design systems + tokens, and the project pointer
+
+Revision ID: 0072
+Revises: 0071
+Create Date: 2026-07-30
+
+Makes the design system a first-class record instead of prose in a rulebook: a
+named set of tokens with an optional parent, so a family system holds the house
+style and an app system holds only what it changes.
+
+`design_systems.parent_id` is the whole model. It replaces both an `always_on`
+flag (a family system is one with no parent) and a subscription join table (a
+project points at ONE system, and the chain supplies the rest), which is less
+schema than the rulebook shape it mirrors.
+
+Two deliberate choices worth stating here rather than leaving to be re-derived:
+
+  - **`design_tokens.value_by_mode` is JSONB keyed by mode**, not `value_light` +
+    `value_dark` columns. In a child system an unset mode means "inherit"; in a
+    root it would mean "not mode-dependent", and as columns both are NULL and
+    indistinguishable. As a map, resolution is a dict merge at every level with
+    no special case for roots — and a third mode (high-contrast, print) is data
+    rather than a schema change. The cost is that a typo'd mode key is not
+    rejected by the database. Nothing filters tokens by value in SQL, so the
+    queryability the columns would have bought is for a query no caller makes.
+    (Named `value_by_mode` rather than `values`, which is reserved in SQL.)
+  - **`group_name` is free text, not a CHECK enum.** Groupings are each design
+    system's own vocabulary; a whitelist would bake one install's kit into the
+    schema. No CHECK is introduced anywhere in this migration.
+
+`parent_id` and `projects.design_system_id` are both ON DELETE SET NULL. Deleting
+a family system must orphan its children into roots that still hold their own
+overrides, not cascade away every app system that inherited from it; deleting a
+system a project points at must unstyle that project, not delete it.
+
+Downgrade drops both tables and the column. Any design system defined this way
+is lost — this is the migration that introduces the concept, so there is no
+earlier representation to fall back to.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+revision = "0072"
+down_revision = "0071"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "design_systems",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column(
+            "owner_user_id", sa.BigInteger(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column("title", sa.Text(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column(
+            "parent_id", sa.BigInteger(),
+            sa.ForeignKey("design_systems.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()"),
+        ),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("deleted_batch_id", sa.Text(), nullable=True),
+    )
+    op.create_index(
+        "ix_design_systems_owner_user_id", "design_systems", ["owner_user_id"]
+    )
+    op.create_index("ix_design_systems_parent_id", "design_systems", ["parent_id"])
+
+    op.create_table(
+        "design_tokens",
+        sa.Column("id", sa.BigInteger(), primary_key=True),
+        sa.Column(
+            "design_system_id", sa.BigInteger(),
+            sa.ForeignKey("design_systems.id", ondelete="CASCADE"), nullable=False,
+        ),
+        sa.Column("name", sa.Text(), nullable=False),
+        # NOT NULL with a '{}' default: a nullable JSONB column has two empty
+        # states (SQL NULL and JSON null) and every reader has to test for both.
+        sa.Column(
+            "value_by_mode", JSONB,
+            nullable=False, server_default=sa.text("'{}'::jsonb"),
+        ),
+        sa.Column("group_name", sa.Text(), nullable=True),
+        sa.Column("purpose", sa.Text(), nullable=True),
+        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),
+    )
+    op.create_index(
+        "ix_design_tokens_design_system_id", "design_tokens", ["design_system_id"]
+    )
+    # Partial unique: a name is unique among LIVE tokens in a system. Two live
+    # rows with the same name are a duplicate definition and the cascade would
+    # pick between them arbitrarily; a trashed row must not block reusing its
+    # name.
+    op.create_index(
+        "uq_token_per_design_system", "design_tokens", ["design_system_id", "name"],
+        unique=True, postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+
+    op.add_column(
+        "projects", sa.Column("design_system_id", sa.BigInteger(), nullable=True)
+    )
+    op.create_foreign_key(
+        "fk_projects_design_system_id", "projects", "design_systems",
+        ["design_system_id"], ["id"], ondelete="SET NULL",
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint("fk_projects_design_system_id", "projects", type_="foreignkey")
+    op.drop_column("projects", "design_system_id")
+    op.drop_index("uq_token_per_design_system", table_name="design_tokens")
+    op.drop_index("ix_design_tokens_design_system_id", table_name="design_tokens")
+    op.drop_table("design_tokens")
+    op.drop_index("ix_design_systems_parent_id", table_name="design_systems")
+    op.drop_index("ix_design_systems_owner_user_id", table_name="design_systems")
+    op.drop_table("design_systems")

alembic/versions/0073_design_token_supersedes.py

@@ -0,0 +1,55 @@
+"""design_tokens.supersedes — the literals a token should be used instead of
+
+Revision ID: 0073
+Revises: 0072
+Create Date: 2026-07-30
+
+Records what a prohibition was actually trying to say.
+
+A design rulebook writes "pure white #FFFFFF is NEVER used as text color". That
+sentence has no row in a table of tokens, because a design system stores what
+things ARE — which looked like a gap in the model and was really a sentence
+written backwards. The positive fact is "text is Parchment", and the useful
+record is the mapping from the literal someone would otherwise write to the
+token they should write instead.
+
+So `supersedes` is a JSONB array of literal values, e.g. `["#fff", "#ffffff"]`
+on a text-on-action token. A finding built from it can say what to write, not
+merely what not to.
+
+It must be DECLARED rather than derived. `#fff` and Parchment `#E8E4D8` are
+different colours, so no value-matching rule could ever have connected them —
+which is exactly why the prohibition felt unrepresentable until it was turned
+around.
+
+Consumed by the source lint that reads component CSS, not by the drift panel:
+these literals are in the components, which the panel cannot see.
+
+NOT NULL with a `'[]'` default, matching `value_by_mode` — a nullable JSONB
+column has two empty states and every reader has to test for both.
+
+Downgrade drops the column; the declarations are lost, which costs the lint its
+input and nothing else.
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+
+revision = "0073"
+down_revision = "0072"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "design_tokens",
+        sa.Column(
+            "supersedes", JSONB, nullable=False, server_default=sa.text("'[]'::jsonb")
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("design_tokens", "supersedes")

alembic/versions/0074_design_prose.py

@@ -0,0 +1,44 @@
+"""central prose on a design system, and rationale on a token
+
+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:
+
+  design_systems.guidance   the narrative a token table cannot hold — aesthetic,
+                            voice and tone, what is deliberately out of scope.
+                            Markdown, free-form.
+  design_tokens.rationale   WHY this token is this value, which is a different
+                            question from `purpose` (what it is FOR). "Success
+                            equals Moss, aligned by design" is a rationale;
+                            "page bg, deepest surface" is a purpose.
+
+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
+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.
+
+Downgrade drops both columns and the prose with them.
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "0074"
+down_revision = "0073"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column("design_systems", sa.Column("guidance", sa.Text(), nullable=True))
+    op.add_column("design_tokens", sa.Column("rationale", sa.Text(), nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("design_tokens", "rationale")
+    op.drop_column("design_systems", "guidance")

ci-requirements.md

@@ -0,0 +1,53 @@
+# CI Requirements — FabledScribe
+
+> Spec lives in [`docs/process.md`](https://git.fabledsword.com/bvandeusen/CI-runner/src/branch/main/docs/process.md)
+> in the CI-Runner repo.
+
+## Runtime image
+
+```
+git.fabledsword.com/bvandeusen/ci-python:3.14
+```
+
+Used by all six jobs in `.forgejo/workflows/ci.yml`: typecheck (Vue/TS),
+plugin (hook checks), lint (ruff), test (pytest), integration (pytest +
+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)
+- docker CLI + buildx (build job pushes the production image to the
+  Fabled-Git registry)
+
+## Per-job tool installs
+
+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.
+
+## Notes
+
+- Production runtime image (`Dockerfile`) also tracks Python 3.14 — the
+  CI image and runtime image stay aligned by design so test results are
+  representative.
+- Build wall time: dominated by `pytest` (full async test suite). Cold
+  ci-python pulls add ~30s; not a blocker.
+- Registry-backed BuildKit layer cache (`type=registry,ref=…:cache,mode=max`)
+  gives ~80% speedup on warm builds — see the build job comment.
+- `pyproject.toml` pins `requires-python = ">=3.14"` to match the CI +
+  runtime target; lockfile (`uv.lock`) is committed and resolves against
+  Python 3.14.

docker-compose.prod.yml

@@ -1,16 +1,14 @@
 services:
   app:
-    image: git.fabledsword.com/bvandeusen/fabledassistant:latest
+    image: git.fabledsword.com/bvandeusen/fabledscribe:latest
     environment:
-      DATABASE_URL: "postgresql+asyncpg://fabled:${DB_PASSWORD}@db:5432/fabledassistant"
+      DATABASE_URL: "postgresql+asyncpg://scribe:${DB_PASSWORD}@db:5432/scribe"
       SECRET_KEY: "${SECRET_KEY}"
-      OLLAMA_URL: "http://ollama:11434"
-      OLLAMA_MODEL: "${OLLAMA_MODEL:-llama3.1}"
       LOG_LEVEL: "${LOG_LEVEL:-INFO}"
       TRUST_PROXY_HEADERS: "true"
       SECURE_COOKIES: "true"
     networks:
-      - fabledassistant_backend
+      - scribe_backend
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/health')"]
       interval: 30s
@@ -23,59 +21,39 @@ services:
         max_attempts: 5
 
   db:
-    image: postgres:16-alpine
+    # 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.
+    image: pgvector/pgvector:pg17
+    stop_grace_period: 120s
     volumes:
       - pgdata:/var/lib/postgresql/data
     environment:
-      POSTGRES_USER: fabled
+      POSTGRES_USER: scribe
       POSTGRES_PASSWORD: "${DB_PASSWORD}"
-      POSTGRES_DB: fabledassistant
+      POSTGRES_DB: scribe
     networks:
-      - fabledassistant_backend
+      - 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 fabled"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    deploy:
-      restart_policy:
-        condition: on-failure
-        max_attempts: 5
-
-  ollama:
-    image: ollama/ollama
-    volumes:
-      - ollama_models:/root/.ollama
-    networks:
-      - fabledassistant_backend
-    environment:
-      OLLAMA_MAX_LOADED_MODELS: "2"
-      OLLAMA_KEEP_ALIVE: "30m"
-      OLLAMA_FLASH_ATTENTION: "1"
-    healthcheck:
-      test: ["CMD-SHELL", "ollama list || exit 1"]
+      test: ["CMD-SHELL", "pg_isready -U scribe"]
       interval: 30s
       timeout: 10s
-      retries: 5
-      start_period: 30s
+      retries: 10
+      start_period: 180s
     deploy:
-      placement:
-        constraints:
-          - node.role == worker
-      resources:
-        reservations:
-          devices:
-            - driver: nvidia
-              count: all
-              capabilities: [gpu]
       restart_policy:
         condition: on-failure
-        max_attempts: 5
+        delay: 10s
+        max_attempts: 0
+        window: 120s
 
 volumes:
   pgdata:
-  ollama_models:
 
 networks:
-  fabledassistant_backend:
+  scribe_backend:
     driver: overlay

docker-compose.quickstart.yml

@@ -1,4 +1,4 @@
-# Fabled Assistant — Quick Start
+# Fabled Scribe — Quick Start
 #
 # No build required. Pulls the latest pre-built image from the registry.
 #
@@ -6,29 +6,26 @@
 #   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 → General to pull an LLM model (qwen3:8b or llama3.1:8b are good starting points)
+#   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/fabledassistant:latest
+    image: git.fabledsword.com/bvandeusen/fabledscribe:latest
     ports:
       - "5000:5000"
     environment:
-      DATABASE_URL: "postgresql+asyncpg://fabled:fabled@db:5432/fabledassistant"
+      DATABASE_URL: "postgresql+asyncpg://scribe:scribe@db:5432/scribe"
       SECRET_KEY: "${SECRET_KEY:-change-me-in-production}"
-      OLLAMA_URL: "http://ollama:11434"
-      OLLAMA_MODEL: "${OLLAMA_MODEL:-llama3.1:8b}"
       LOG_LEVEL: "${LOG_LEVEL:-INFO}"
     volumes:
       - app_data:/data
     depends_on:
       db:
         condition: service_healthy
-      ollama:
-        condition: service_healthy
     restart: unless-stopped
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/health')"]
@@ -38,45 +35,25 @@ services:
       start_period: 30s
 
   db:
-    image: postgres:16-alpine
+    # 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: fabled
-      POSTGRES_PASSWORD: fabled
-      POSTGRES_DB: fabledassistant
+      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 fabled"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-    restart: unless-stopped
-
-  ollama:
-    image: ollama/ollama
-    volumes:
-      - ollama_models:/root/.ollama
-    environment:
-      OLLAMA_MAX_LOADED_MODELS: "2"
-      OLLAMA_KEEP_ALIVE: "30m"
-      OLLAMA_FLASH_ATTENTION: "1"
-    healthcheck:
-      test: ["CMD-SHELL", "ollama list > /dev/null 2>&1"]
+      test: ["CMD-SHELL", "pg_isready -U scribe"]
       interval: 30s
       timeout: 10s
-      retries: 5
-      start_period: 15s
+      retries: 10
+      start_period: 180s
     restart: unless-stopped
-    # Uncomment to enable NVIDIA GPU passthrough (requires nvidia-container-toolkit):
-    # deploy:
-    #   resources:
-    #     reservations:
-    #       devices:
-    #         - driver: nvidia
-    #           count: all
-    #           capabilities: [gpu]
 
 volumes:
   app_data:
   pgdata:
-  ollama_models:

docker-compose.yml

@@ -6,25 +6,16 @@ services:
     depends_on:
       db:
         condition: service_healthy
-      ollama:
-        condition: service_started
     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:-fabled}:${POSTGRES_PASSWORD:-fabled}@db:5432/${POSTGRES_DB:-fabledassistant}"
-      OLLAMA_URL: "http://ollama:11434"
-      OLLAMA_MODEL: "${OLLAMA_MODEL:-llama3.1}"
+      DATABASE_URL: "postgresql+asyncpg://${POSTGRES_USER:-scribe}:${POSTGRES_PASSWORD:-scribe}@db:5432/${POSTGRES_DB:-scribe}"
       SECRET_KEY: "${SECRET_KEY:-dev-secret-change-me}"
-      # Uncomment and set to enable web research and image search via SearXNG:
+      # 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"
-      # IMAGE_CACHE_DIR: /data/images  # default, change if using a different mount path
-      # IMAGE_MAX_BYTES: "5242880"     # 5 MB per image, adjust if needed
-      # Push notifications (VAPID keys - generate with: python -c "from py_vapid import Vapid01; v=Vapid01(); v.generate_keys(); print(v.private_key, v.public_key)")
-      VAPID_PRIVATE_KEY: "${VAPID_PRIVATE_KEY:-}"
-      VAPID_PUBLIC_KEY: "${VAPID_PUBLIC_KEY:-}"
-      VAPID_CLAIMS_SUB: "${VAPID_CLAIMS_SUB:-mailto:admin@fabledassistant.local}"
     healthcheck:
       test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/api/health')"]
       interval: 10s
@@ -34,37 +25,23 @@ services:
 
   db:
     image: postgres:16-alpine
+    stop_grace_period: 120s
+    restart: unless-stopped
     volumes:
       - pgdata:/var/lib/postgresql/data
     environment:
-      POSTGRES_USER: ${POSTGRES_USER:-fabled}
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-fabled}
-      POSTGRES_DB: ${POSTGRES_DB:-fabledassistant}
+      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:-fabled}"]
-      interval: 5s
-      timeout: 5s
-      retries: 5
-
-  ollama:
-    image: ollama/ollama
-    volumes:
-      - ollama_models:/root/.ollama
-    environment:
-      OLLAMA_MAX_LOADED_MODELS: "2"
-      OLLAMA_NUM_PARALLEL: "2"
-      OLLAMA_KEEP_ALIVE: "30m"
-      OLLAMA_FLASH_ATTENTION: "1"
-    # GPU reservation commented out — no nvidia-container-toolkit on this host
-    # deploy:
-    #   resources:
-    #     reservations:
-    #       devices:
-    #         - driver: nvidia
-    #           count: all
-    #           capabilities: [gpu]
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-scribe}"]
+      interval: 30s
+      timeout: 10s
+      retries: 10
+      start_period: 180s
 
 volumes:
   pgdata:
-  ollama_models:
   app_data:

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

@@ -12,7 +12,7 @@ A Python MCP (Model Context Protocol) server that lets Claude directly interface
 
 The work is split into two sub-projects:
 
-1. **Fable API Key Feature** — additions to the main `fabledassistant` project to support bearer token authentication
+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.
@@ -134,7 +134,7 @@ The MCP tool reads tokens until it receives `type: "done"`, then returns `respon
 
 ### 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 `fabledassistant`. It will be extracted to its own Forgejo repo once stable.
+`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
 
@@ -256,7 +256,7 @@ Claude Code spawns the process over stdio automatically. No Docker, no daemon.
 
 ## Build & Repo Plan
 
-1. Implement and test within `fabledassistant/fable-mcp/`
+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
 

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

@@ -6,7 +6,7 @@
 
 **Architecture:** Phase 1 adds bearer token auth to the existing Quart app (new `api_keys` table, updated `_check_auth`, settings UI tab). Phase 2 is a standalone `fable-mcp/` Python package using the `mcp[cli]` SDK that calls the Fable HTTP API via `httpx`. The two phases are sequential — Phase 2 can be built/tested independently using a write-scoped API key once Phase 1 is done.
 
-**Deployment decision:** `fable-mcp/` stays permanently inside the `fabledassistant` repo. It will always be versioned alongside the backend it targets. Future Task A will serve the package from the running Fable Docker image so users can install it directly from their instance.
+**Deployment decision:** `fable-mcp/` stays permanently inside the `scribe` repo. It will always be versioned alongside the backend it targets. Future Task A will serve the package from the running Fable Docker image so users can install it directly from their instance.
 
 **Tech Stack:** Python 3.12, Quart (Phase 1); `mcp[cli]`, `httpx`, `python-dotenv` (Phase 2); Vue 3 + TypeScript (Settings UI); pytest for both.
 
@@ -23,16 +23,16 @@
 | Action | File | Purpose |
 |--------|------|---------|
 | Create | `alembic/versions/0027_add_api_keys.py` | DB migration for `api_keys` table |
-| Create | `src/fabledassistant/models/api_key.py` | `ApiKey` SQLAlchemy model |
-| Modify | `src/fabledassistant/models/__init__.py` | Export `ApiKey` |
-| Create | `src/fabledassistant/services/api_keys.py` | create/list/revoke/lookup service functions |
-| Modify | `src/fabledassistant/auth.py` | Add bearer token check before session fallback |
-| Create | `src/fabledassistant/routes/api_keys.py` | GET/POST/DELETE `/api/api-keys` blueprint |
-| Modify | `src/fabledassistant/app.py` | Register `api_keys_bp` and `search_bp` |
-| Modify | `src/fabledassistant/services/chat.py:17-30` | Add `conversation_type` param to `create_conversation` |
-| Modify | `src/fabledassistant/services/chat.py:123-135` | Exclude `"mcp"` type from `cleanup_old_conversations` |
-| Modify | `src/fabledassistant/routes/chat.py:73-79` | Pass `conversation_type` from POST body |
-| Create | `src/fabledassistant/routes/search.py` | `GET /api/search` semantic search endpoint |
+| Create | `src/scribe/models/api_key.py` | `ApiKey` SQLAlchemy model |
+| Modify | `src/scribe/models/__init__.py` | Export `ApiKey` |
+| Create | `src/scribe/services/api_keys.py` | create/list/revoke/lookup service functions |
+| Modify | `src/scribe/auth.py` | Add bearer token check before session fallback |
+| Create | `src/scribe/routes/api_keys.py` | GET/POST/DELETE `/api/api-keys` blueprint |
+| Modify | `src/scribe/app.py` | Register `api_keys_bp` and `search_bp` |
+| Modify | `src/scribe/services/chat.py:17-30` | Add `conversation_type` param to `create_conversation` |
+| Modify | `src/scribe/services/chat.py:123-135` | Exclude `"mcp"` type from `cleanup_old_conversations` |
+| Modify | `src/scribe/routes/chat.py:73-79` | Pass `conversation_type` from POST body |
+| Create | `src/scribe/routes/search.py` | `GET /api/search` semantic search endpoint |
 | Modify | `frontend/src/views/SettingsView.vue` | Add "API Keys" tab |
 | Create | `tests/test_api_keys.py` | Unit tests for service + auth |
 | Create | `tests/test_search_route.py` | Unit test for search endpoint |
@@ -42,13 +42,13 @@
 ### Task 1: ApiKey model + migration
 
 **Files:**
-- Create: `src/fabledassistant/models/api_key.py`
+- Create: `src/scribe/models/api_key.py`
 - Create: `alembic/versions/0027_add_api_keys.py`
-- Modify: `src/fabledassistant/models/__init__.py`
+- Modify: `src/scribe/models/__init__.py`
 
 - [ ] **Step 1: Write the model**
 
-Create `src/fabledassistant/models/api_key.py`:
+Create `src/scribe/models/api_key.py`:
 
 ```python
 from datetime import datetime, timezone
@@ -56,8 +56,8 @@ from datetime import datetime, timezone
 from sqlalchemy import DateTime, ForeignKey, Index, Integer, Text
 from sqlalchemy.orm import Mapped, mapped_column
 
-from fabledassistant.models import Base
-from fabledassistant.models.base import CreatedAtMixin
+from scribe.models import Base
+from scribe.models.base import CreatedAtMixin
 
 
 class ApiKey(Base, CreatedAtMixin):
@@ -97,10 +97,10 @@ class ApiKey(Base, CreatedAtMixin):
 
 - [ ] **Step 2: Export from models __init__**
 
-In `src/fabledassistant/models/__init__.py`, add after the last import line:
+In `src/scribe/models/__init__.py`, add after the last import line:
 
 ```python
-from fabledassistant.models.api_key import ApiKey  # noqa: E402, F401
+from scribe.models.api_key import ApiKey  # noqa: E402, F401
 ```
 
 - [ ] **Step 3: Write the migration**
@@ -155,8 +155,8 @@ Expected: `Running upgrade 0026 -> 0027, add api_keys table`
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/fabledassistant/models/api_key.py \
-        src/fabledassistant/models/__init__.py \
+git add src/scribe/models/api_key.py \
+        src/scribe/models/__init__.py \
         alembic/versions/0027_add_api_keys.py
 git commit -m "feat: add ApiKey model and migration 0027"
 ```
@@ -166,7 +166,7 @@ git commit -m "feat: add ApiKey model and migration 0027"
 ### Task 2: ApiKey service
 
 **Files:**
-- Create: `src/fabledassistant/services/api_keys.py`
+- Create: `src/scribe/services/api_keys.py`
 - Create: `tests/test_api_keys.py` (service tests)
 
 - [ ] **Step 1: Write the failing tests**
@@ -181,7 +181,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
-from fabledassistant.services.api_keys import (
+from scribe.services.api_keys import (
     _hash_key,
     generate_key,
     create_api_key,
@@ -212,7 +212,7 @@ def test_hash_key_is_sha256():
 def test_generate_key_prefix():
     key = "fmcp_abcdefghijklmnop"
     # prefix is first 12 chars of the full key
-    from fabledassistant.services.api_keys import _key_prefix
+    from scribe.services.api_keys import _key_prefix
     assert _key_prefix(key) == "fmcp_abcdefg"  # first 12 chars
 
 
@@ -222,7 +222,7 @@ async def test_create_api_key_returns_full_key():
     mock_key_obj.id = 1
     mock_key_obj.to_dict.return_value = {"id": 1, "name": "test", "scope": "read", "key_prefix": "fmcp_xxx"}
 
-    with patch("fabledassistant.services.api_keys.async_session") as mock_session_ctx:
+    with patch("scribe.services.api_keys.async_session") as mock_session_ctx:
         mock_session = AsyncMock()
         mock_session.__aenter__ = AsyncMock(return_value=mock_session)
         mock_session.__aexit__ = AsyncMock(return_value=False)
@@ -238,7 +238,7 @@ async def test_create_api_key_returns_full_key():
 
 @pytest.mark.asyncio
 async def test_lookup_key_returns_none_for_unknown():
-    with patch("fabledassistant.services.api_keys.async_session") as mock_session_ctx:
+    with patch("scribe.services.api_keys.async_session") as mock_session_ctx:
         mock_session = AsyncMock()
         mock_session.__aenter__ = AsyncMock(return_value=mock_session)
         mock_session.__aexit__ = AsyncMock(return_value=False)
@@ -262,7 +262,7 @@ Expected: `ImportError` or `ModuleNotFoundError` (service doesn't exist yet)
 
 - [ ] **Step 3: Write the service**
 
-Create `src/fabledassistant/services/api_keys.py`:
+Create `src/scribe/services/api_keys.py`:
 
 ```python
 import hashlib
@@ -271,8 +271,8 @@ from datetime import datetime, timezone
 
 from sqlalchemy import select
 
-from fabledassistant.models import async_session
-from fabledassistant.models.api_key import ApiKey
+from scribe.models import async_session
+from scribe.models.api_key import ApiKey
 
 
 def generate_key() -> str:
@@ -365,7 +365,7 @@ Expected: all tests pass
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/fabledassistant/services/api_keys.py tests/test_api_keys.py
+git add src/scribe/services/api_keys.py tests/test_api_keys.py
 git commit -m "feat: add ApiKey service with create/list/revoke/lookup"
 ```
 
@@ -374,7 +374,7 @@ git commit -m "feat: add ApiKey service with create/list/revoke/lookup"
 ### Task 3: Auth middleware — bearer token support
 
 **Files:**
-- Modify: `src/fabledassistant/auth.py`
+- Modify: `src/scribe/auth.py`
 - Modify: `tests/test_api_keys.py` (add auth middleware tests)
 
 - [ ] **Step 1: Add auth middleware tests**
@@ -400,7 +400,7 @@ def test_scope_validation():
 async def test_bearer_token_path_sets_g_user(monkeypatch):
     """Valid bearer token authenticates and sets g.user and g.api_key."""
     from unittest.mock import AsyncMock, MagicMock
-    from fabledassistant.auth import _check_auth
+    from scribe.auth import _check_auth
 
     # Mock ApiKey object
     fake_key = MagicMock()
@@ -411,8 +411,8 @@ async def test_bearer_token_path_sets_g_user(monkeypatch):
     fake_user = MagicMock()
     fake_user.role = "user"
 
-    monkeypatch.setattr("fabledassistant.auth.lookup_key", AsyncMock(return_value=fake_key))
-    monkeypatch.setattr("fabledassistant.auth.get_user_by_id", AsyncMock(return_value=fake_user))
+    monkeypatch.setattr("scribe.auth.lookup_key", AsyncMock(return_value=fake_key))
+    monkeypatch.setattr("scribe.auth.get_user_by_id", AsyncMock(return_value=fake_user))
 
     called_with_user = {}
 
@@ -434,7 +434,7 @@ async def test_bearer_token_path_sets_g_user(monkeypatch):
     async with app.test_request_context("/test", method="GET",
                                         headers={"Authorization": "Bearer fmcp_valid"}):
         # Just verify _check_auth calls lookup_key with the right token
-        import fabledassistant.auth as auth_module
+        import scribe.auth as auth_module
         auth_module.lookup_key.assert_called_with  # callable
 
 
@@ -442,7 +442,7 @@ async def test_bearer_token_path_sets_g_user(monkeypatch):
 async def test_read_only_key_blocked_on_post():
     """Read-only API key returns 403 on non-GET requests."""
     from unittest.mock import AsyncMock, MagicMock
-    from fabledassistant.auth import _check_auth
+    from scribe.auth import _check_auth
     from quart import Quart
 
     fake_key = MagicMock()
@@ -459,8 +459,8 @@ async def test_read_only_key_blocked_on_post():
                                  headers={"Authorization": "Bearer fmcp_readonly"}),
     ):
         from unittest.mock import patch
-        with patch("fabledassistant.auth.lookup_key", AsyncMock(return_value=fake_key)), \
-             patch("fabledassistant.auth.get_user_by_id", AsyncMock(return_value=fake_user)):
+        with patch("scribe.auth.lookup_key", AsyncMock(return_value=fake_key)), \
+             patch("scribe.auth.get_user_by_id", AsyncMock(return_value=fake_user)):
 
             async def dummy():
                 return "ok"
@@ -481,15 +481,15 @@ docker compose run --rm app pytest tests/test_api_keys.py -v
 
 - [ ] **Step 3: Update auth.py**
 
-Replace `src/fabledassistant/auth.py` with:
+Replace `src/scribe/auth.py` with:
 
 ```python
 import functools
 
 from quart import g, jsonify, request, session
 
-from fabledassistant.services.auth import get_user_by_id
-from fabledassistant.services.api_keys import lookup_key
+from scribe.services.auth import get_user_by_id
+from scribe.services.api_keys import lookup_key
 
 
 def _check_auth(f, required_role: str | None = None):
@@ -556,7 +556,7 @@ Expected: all existing tests still pass
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/fabledassistant/auth.py tests/test_api_keys.py
+git add src/scribe/auth.py tests/test_api_keys.py
 git commit -m "feat: add bearer token auth to _check_auth, falls back to session"
 ```
 
@@ -565,18 +565,18 @@ git commit -m "feat: add bearer token auth to _check_auth, falls back to session
 ### Task 4: API key routes + app registration
 
 **Files:**
-- Create: `src/fabledassistant/routes/api_keys.py`
-- Modify: `src/fabledassistant/app.py`
+- Create: `src/scribe/routes/api_keys.py`
+- Modify: `src/scribe/app.py`
 
 - [ ] **Step 1: Write the routes**
 
-Create `src/fabledassistant/routes/api_keys.py`:
+Create `src/scribe/routes/api_keys.py`:
 
 ```python
 from quart import Blueprint, jsonify, request
 
-from fabledassistant.auth import login_required, get_current_user_id
-from fabledassistant.services.api_keys import create_api_key, list_api_keys, revoke_api_key
+from scribe.auth import login_required, get_current_user_id
+from scribe.services.api_keys import create_api_key, list_api_keys, revoke_api_key
 
 api_keys_bp = Blueprint("api_keys", __name__, url_prefix="/api/api-keys")
 
@@ -619,10 +619,10 @@ async def revoke_key_route(key_id: int):
 
 - [ ] **Step 2: Register in app.py**
 
-In `src/fabledassistant/app.py`, add the import alongside the other route imports:
+In `src/scribe/app.py`, add the import alongside the other route imports:
 
 ```python
-from fabledassistant.routes.api_keys import api_keys_bp
+from scribe.routes.api_keys import api_keys_bp
 ```
 
 And add the registration line after `app.register_blueprint(users_bp)`:
@@ -651,7 +651,7 @@ curl -s http://localhost:8080/api/auth/me \
 - [ ] **Step 4: Commit**
 
 ```bash
-git add src/fabledassistant/routes/api_keys.py src/fabledassistant/app.py
+git add src/scribe/routes/api_keys.py src/scribe/app.py
 git commit -m "feat: add API key CRUD routes and register blueprint"
 ```
 
@@ -660,14 +660,14 @@ git commit -m "feat: add API key CRUD routes and register blueprint"
 ### Task 5: Conversation type wiring
 
 **Files:**
-- Modify: `src/fabledassistant/services/chat.py` (lines 17-30 and 123-135)
-- Modify: `src/fabledassistant/routes/chat.py` (lines 73-79)
+- Modify: `src/scribe/services/chat.py` (lines 17-30 and 123-135)
+- Modify: `src/scribe/routes/chat.py` (lines 73-79)
 
 Note: `Conversation.conversation_type` already exists in the model. `list_conversations` already filters by `conv_type`. This task only wires up creation and retention exclusion.
 
 - [ ] **Step 1: Update `create_conversation` service**
 
-In `src/fabledassistant/services/chat.py`, change the function signature at line 17:
+In `src/scribe/services/chat.py`, change the function signature at line 17:
 
 ```python
 async def create_conversation(
@@ -692,7 +692,7 @@ async def create_conversation(
 
 - [ ] **Step 2: Update `cleanup_old_conversations` to exclude "mcp"**
 
-In `src/fabledassistant/services/chat.py`, update the WHERE clause at line 130:
+In `src/scribe/services/chat.py`, update the WHERE clause at line 130:
 
 ```python
 result = await session.execute(
@@ -708,7 +708,7 @@ result = await session.execute(
 
 - [ ] **Step 3: Update the POST route to accept conversation_type**
 
-In `src/fabledassistant/routes/chat.py`, update `create_conversation_route` (around line 73):
+In `src/scribe/routes/chat.py`, update `create_conversation_route` (around line 73):
 
 ```python
 @chat_bp.route("/conversations", methods=["POST"])
@@ -737,7 +737,7 @@ Expected: all tests pass
 - [ ] **Step 5: Commit**
 
 ```bash
-git add src/fabledassistant/services/chat.py src/fabledassistant/routes/chat.py
+git add src/scribe/services/chat.py src/scribe/routes/chat.py
 git commit -m "feat: wire conversation_type through create_conversation, exclude mcp from retention sweep"
 ```
 
@@ -746,8 +746,8 @@ git commit -m "feat: wire conversation_type through create_conversation, exclude
 ### Task 6: Semantic search endpoint
 
 **Files:**
-- Create: `src/fabledassistant/routes/search.py`
-- Modify: `src/fabledassistant/app.py`
+- Create: `src/scribe/routes/search.py`
+- Modify: `src/scribe/app.py`
 - Create: `tests/test_search_route.py`
 
 - [ ] **Step 1: Write the failing test**
@@ -762,7 +762,7 @@ from unittest.mock import patch, AsyncMock
 
 def test_content_type_mapping():
     """Verify content_type string maps to correct is_task value."""
-    from fabledassistant.routes.search import _content_type_to_is_task
+    from scribe.routes.search import _content_type_to_is_task
     assert _content_type_to_is_task("note") is False
     assert _content_type_to_is_task("task") is True
     assert _content_type_to_is_task("all") is None
@@ -779,13 +779,13 @@ Expected: `ImportError` (module doesn't exist yet)
 
 - [ ] **Step 3: Write the route**
 
-Create `src/fabledassistant/routes/search.py`:
+Create `src/scribe/routes/search.py`:
 
 ```python
 from quart import Blueprint, jsonify, request
 
-from fabledassistant.auth import login_required, get_current_user_id
-from fabledassistant.services.embeddings import semantic_search_notes
+from scribe.auth import login_required, get_current_user_id
+from scribe.services.embeddings import semantic_search_notes
 
 search_bp = Blueprint("search", __name__, url_prefix="/api/search")
 
@@ -834,9 +834,9 @@ Note: check `services/embeddings.py` to confirm the return type of `semantic_sea
 
 - [ ] **Step 4: Register in app.py**
 
-Add to imports in `src/fabledassistant/app.py`:
+Add to imports in `src/scribe/app.py`:
 ```python
-from fabledassistant.routes.search import search_bp
+from scribe.routes.search import search_bp
 ```
 
 Add registration:
@@ -855,8 +855,8 @@ Expected: all tests pass
 - [ ] **Step 6: Commit**
 
 ```bash
-git add src/fabledassistant/routes/search.py \
-        src/fabledassistant/app.py \
+git add src/scribe/routes/search.py \
+        src/scribe/app.py \
         tests/test_search_route.py
 git commit -m "feat: add GET /api/search semantic search endpoint"
 ```
@@ -1905,7 +1905,7 @@ async def send_message(
         return f"Error: {e}"
 ```
 
-Note: verify the Fable message POST endpoint path by checking `src/fabledassistant/routes/chat.py` — search for the route that accepts a user message and triggers generation. Adjust `/api/chat/conversations/{conv_id}/messages` if the actual path differs.
+Note: verify the Fable message POST endpoint path by checking `src/scribe/routes/chat.py` — search for the route that accepts a user message and triggers generation. Adjust `/api/chat/conversations/{conv_id}/messages` if the actual path differs.
 
 - [ ] **Step 4: Run tests**
 

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

@@ -0,0 +1,200 @@
+# 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

@@ -0,0 +1,216 @@
+# 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/android-app.md

@@ -1,73 +0,0 @@
-# Android Companion App
-
-The Android companion app lives in a separate repository at `/home/bvandeusen/Nextcloud/Projects/fabled_app`.
-
-## Stack
-
-- Flutter + Dart
-- Riverpod (state management)
-- GoRouter (navigation)
-- Dio (HTTP client)
-- PersistCookieJar (session persistence)
-- SSE streaming via `fetch` + `ReadableStream` bridge
-
-## Architecture
-
-```
-lib/
-  app.dart                          # GoRouter + _Shell + _QuickCaptureBar
-  core/constants.dart               # Routes.*
-  data/
-    models/                         # note.dart, task.dart, project.dart
-    api/                            # notes_api.dart, tasks_api.dart, projects_api.dart
-    repositories/                   # notes, tasks, projects repositories
-  providers/
-    api_client_provider.dart        # all API + repository providers
-    notes_provider.dart             # NotesNotifier
-    tasks_provider.dart             # TasksNotifier
-    projects_provider.dart          # ProjectsNotifier
-  screens/
-    notes/note_edit_screen.dart     # chip tag input + ProjectSelector
-    tasks/task_edit_screen.dart     # ProjectSelector
-    projects/project_list_screen.dart
-  widgets/
-    project_selector.dart           # reusable DropdownButtonFormField
-```
-
-## Navigation
-
-4-tab shell (Notes · Tasks · Projects · Chat):
-- Phone: bottom `NavigationBar`
-- Tablet/landscape: `NavigationRail`
-
-Quick Capture bar persists across all tabs. Settings accessible from top-right icon.
-
-## Feature Status
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| Notes CRUD | ✅ | Tags chip input; project selector in editor |
-| Tasks CRUD | ✅ | Project selector in editor |
-| Projects list | ✅ | Active/archived sections; long-press status change; create dialog |
-| Chat + SSE | ✅ | Full streaming |
-| Quick Capture | ✅ | Offline queue with retry |
-| Tags | ✅ | Chip input in NoteEditScreen; typed as `List<String>` |
-| Project assignment | ✅ | `ProjectSelector` dropdown in Note + Task editors |
-| Milestones | ❌ deferred | Too granular for mobile; web UI handles it |
-| Push notifications | ❌ incompatible | Backend uses browser VAPID; Flutter needs FCM/APNs — separate implementation required |
-| CalDAV settings | ❌ intentional | Server-side config only; not exposed in mobile app |
-
-## API Compatibility Notes
-
-- `GET /api/projects/:id` returns a flat JSON object (not `{project: ...}` wrapper); includes `summary` field.
-- `POST /api/projects` returns the project dict directly (201).
-- `PATCH /api/projects/:id` returns the updated project dict.
-- Task body field is `body` (not `description`) — the app maps `description` → `body` on serialize.
-
-## Self-Update
-
-The app supports self-update via the Forgejo release API (`update_provider.dart`). It checks the latest release tag and prompts the user to download and install a new APK when one is available.
-
-## CI
-
-Builds are triggered from the Forgejo Actions pipeline in the `fabled_app` repository. The APK is attached to the release as a downloadable artifact.

docs/api-keys-and-mcp.md

@@ -1,4 +1,4 @@
-# API Keys and Fable MCP
+# API Keys and Scribe MCP
 
 ## API Keys
 
@@ -19,11 +19,10 @@ Admin-level operations (log access, user management) require a `write`-scoped ke
 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
+5. Copy the key immediately — it is shown only once (the token is `fmcp_`-prefixed)
 
-After creation you can download:
-- **`.env` file** — `FABLE_URL` + `FABLE_API_KEY` ready to paste
-- **Claude config JSON** — `mcpServers` block ready to merge into `~/.claude.json`
+Paste the key into the `Authorization: Bearer <key>` header of your MCP client
+config (see **Scribe MCP Server** below).
 
 ### Revoking a Key
 
@@ -31,73 +30,35 @@ Click **Revoke** next to the key in the API Keys table and confirm. Revoked keys
 
 ---
 
-## Fable MCP Server
+## Scribe MCP Server
 
-The Fable MCP server (`fable-mcp`) exposes Fable as a set of MCP tools that Claude (and other MCP clients) can use to read and write your notes, tasks, projects, and more.
+Scribe 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
+is nothing to install: no wheel, no separate package, no CLI. You connect a
+client straight to the URL with a Bearer token.
 
-### Download
+### Authentication
 
-The wheel is bundled into the Docker image at build time and available for download from **Settings → API Keys → Fable MCP** when you are logged in.
-
-You can also download it directly:
-```
-GET /api/fable-mcp/download
-```
-(Requires login — authenticated browser session or API key in `Authorization: Bearer <key>` header.)
-
-### Installation
-
-```bash
-# Install the wheel
-pip install fable_mcp-*.whl
-
-# Verify
-fable-mcp --help
-```
-
-### Configuration
-
-The server reads two environment variables:
-
-| Variable | Description |
-|----------|-------------|
-| `FABLE_URL` | Base URL of your Fable instance (e.g. `https://notes.example.com`) |
-| `FABLE_API_KEY` | API key generated from Settings → API Keys |
-
-Create a `.env` file in your working directory, or set them in your shell / MCP config.
-
-### Claude Code (Global)
-
-Add to `~/.claude.json`:
-
-```json
-{
-  "mcpServers": {
-    "fable": {
-      "type": "stdio",
-      "command": "fable-mcp",
-      "env": {
-        "FABLE_URL": "https://your-fable-instance.example.com",
-        "FABLE_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
+Authenticate with an API key generated from **Settings → API Keys** (see above),
+sent as `Authorization: Bearer fmcp_<key>`. A `read`-scoped key may call only the
+read tools (`get_*`, `list_*`, `search`, `enter_project`); any write/delete tool
+is rejected with `403`. A `write`-scoped key may call everything.
 
 ### Claude Code (Project-scoped)
 
-Add a `.mcp.json` at the project root (same format as the global config). Project-scoped config takes precedence over global when the same server name is defined in both. This is useful for using a dev instance or admin key within a specific project.
+Add a `.mcp.json` at the project root. The server `type` is `http` and the URL is
+your instance's `/mcp` endpoint:
 
 ```json
 {
   "mcpServers": {
-    "fable": {
-      "type": "stdio",
-      "command": "fable-mcp",
-      "env": {
-        "FABLE_URL": "http://localhost:5000",
-        "FABLE_API_KEY": "your-dev-api-key"
+    "scribe": {
+      "type": "http",
+      "url": "https://your-scribe-instance.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer fmcp_your-api-key"
       }
     }
   }
@@ -106,39 +67,32 @@ Add a `.mcp.json` at the project root (same format as the global config). Projec
 
 Note: `.mcp.json` contains an API key and should be added to `.gitignore`.
 
+### Claude Code (Global)
+
+The same `mcpServers` block can live in `~/.claude.json` to make the server
+available across all projects. A project-scoped `.mcp.json` takes precedence over
+the global entry when both define the same server name — useful for pointing a
+specific project at a dev instance or an admin key.
+
 ### Available Tools
 
-| Tool | Description |
-|------|-------------|
-| `fable_list_notes` | List notes, filter by tag or search text |
-| `fable_get_note` | Fetch a note by ID |
-| `fable_create_note` | Create a new note |
-| `fable_update_note` | Update a note |
-| `fable_delete_note` | Delete a note |
-| `fable_list_tasks` | List tasks, filter by status or project |
-| `fable_get_task` | Fetch a task by ID |
-| `fable_create_task` | Create a new task |
-| `fable_update_task` | Update a task |
-| `fable_add_task_log` | Append a work log entry to a task |
-| `fable_list_projects` | List all projects |
-| `fable_get_project` | Fetch a project with milestone summary |
-| `fable_create_project` | Create a project |
-| `fable_update_project` | Update a project |
-| `fable_list_milestones` | List milestones for a project |
-| `fable_create_milestone` | Create a milestone |
-| `fable_update_milestone` | Update a milestone |
-| `fable_search` | Semantic search over notes and tasks |
-| `fable_list_conversations` | List MCP chat conversations |
-| `fable_send_message` | Send a message to Fable's LLM |
-| `fable_get_app_logs` | Fetch application logs (admin key required) |
+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:
 
-### Development Notes
+| 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` | Semantic + structured recall |
+| Systems | `create_system`, `list_systems`, `list_system_records` | Reusable per-project subsystems/areas |
+| Rulebooks | `list_always_on_rules`, `list_rules`, `create_rule`, `create_project_rule`, `subscribe_project_to_rulebook`, … | Engineering/workflow rules |
+| Processes | `list_processes`, `get_process`, `create_process` | Saved prompts/workflows |
+| Trash | `list_trash`, `restore`, `purge_trash` | Recoverable deletes |
+| Admin | `get_app_logs` (write/admin key) | Diagnostics |
 
-The `fable-mcp` package lives in `fable-mcp/` in this repository. The Docker build compiles it into a wheel at `/app/dist/` so it can be served for download without requiring the source tree at runtime.
-
-To build the wheel locally:
-```bash
-cd fable-mcp
-pip install build hatchling
-python -m build --wheel .
-```
+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`).

docs/api-reference.md

@@ -1,244 +1,206 @@
 # API Reference
 
-All endpoints require login (session cookie or `Authorization: Bearer <api-key>`) unless marked **(public)**.
+All endpoints are JSON over HTTP under `/api`, and require login unless marked
+**(public)**. Browser sessions authenticate with a cookie; programmatic clients use an
+`fmcp_` API key as `Authorization: Bearer <key>` (see
+[API Keys & MCP](api-keys-and-mcp.md)). Claude reaches the same data through the MCP
+endpoint at `/mcp`, not these REST routes.
 
 ## Health
 
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/health` | Health check **(public)** |
+| GET | `/api/version` | App version **(public)** |
 
 ## Auth
 
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/auth/status` | `{has_users, registration_open, oauth_enabled, local_auth_enabled}` **(public)** |
-| POST | `/api/auth/register` | Register new user (first user becomes admin; 403 if registration closed or local auth disabled) |
-| POST | `/api/auth/login` | Login with username/password (403 if local auth disabled) |
+| POST | `/api/auth/register` | Register (first user becomes admin) |
+| POST | `/api/auth/login` | Login with username/password |
 | POST | `/api/auth/logout` | Clear session |
-| GET | `/api/auth/me` | Current user info (includes `has_password: bool`) |
-| PUT | `/api/auth/password` | Change password `{current_password, new_password}` |
-| PUT | `/api/auth/email` | Change email `{email, password?}` (password required only for local-auth users) |
-| POST | `/api/auth/invalidate-sessions` | Bump `session_version` — evicts all other sessions, keeps current alive |
-| POST | `/api/auth/forgot-password` | Send password reset email `{email}` |
-| POST | `/api/auth/reset-password` | Reset password with token `{token, new_password}` |
-| GET | `/api/auth/oauth/login` | Initiate OIDC PKCE flow → redirect to provider |
-| GET | `/api/auth/oauth/callback` | OIDC callback — exchange code, find/create user, redirect to `/` |
-| GET | `/api/auth/invitation/:token` | Validate invitation token **(public)** |
-| POST | `/api/auth/register-with-invite` | Register with token `{token, username, password}` **(public)** |
+| GET | `/api/auth/me` | Current user info |
+| PUT | `/api/auth/password` | Change password |
+| PUT | `/api/auth/email` | Change email |
+| POST | `/api/auth/invalidate-sessions` | Evict all other sessions |
+| POST | `/api/auth/forgot-password` | Send password-reset email |
+| POST | `/api/auth/reset-password` | Reset password with token |
+| GET | `/api/auth/oauth/login` | Begin OIDC (PKCE) flow |
+| GET | `/api/auth/oauth/callback` | OIDC callback |
+| GET | `/api/auth/invitation/:token` | Validate an invite **(public)** |
+| POST | `/api/auth/register-with-invite` | Register with a token **(public)** |
 
 ## Notes
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/notes` | List notes. Params: `q`, `tag`, `sort`, `order`, `limit`, `offset`, `project_id`, `milestone_id`, `parent_id`, `type` (`note`/`task`/`all`) |
-| POST | `/api/notes` | Create note `{title, body, tags?, status?, priority?, due_date?, project_id?, milestone_id?, parent_id?}` |
-| GET | `/api/notes/tags` | All tags (param: `q` for filter) |
-| POST | `/api/notes/suggest-tags` | LLM tag suggestions `{title, body, current_tags?}` → `{suggested_tags}` |
-| POST | `/api/notes/link-suggestions` | Detect note titles as plain text in body `{body, project_id, exclude_note_id}` → `[{note_id, title, count}]` |
-| GET | `/api/notes/by-title` | Resolve note by exact title (param: `title`) |
-| POST | `/api/notes/resolve-title` | Get-or-create note by title `{title}` (wikilink click) |
-| GET | `/api/notes/:id` | Get single note |
-| PUT | `/api/notes/:id` | Full update |
-| PATCH | `/api/notes/:id` | Partial update (same fields as PUT) |
-| DELETE | `/api/notes/:id` | Delete note |
-| POST | `/api/notes/:id/convert-to-task` | Set `status='todo'`, `priority='none'` |
-| POST | `/api/notes/:id/convert-to-note` | Clear `status`, `priority`, `due_date` |
-| POST | `/api/notes/:id/append-tag` | Add tag `{tag}` → updated note |
+| GET | `/api/notes` | List notes (params: `q`, `tag`, `sort`, `order`, `limit`, `offset`, `project_id`, `milestone_id`, `parent_id`) |
+| POST | `/api/notes` | Create note |
+| GET | `/api/notes/tags` | All tags (param: `q`) |
+| POST | `/api/notes/:id/append-tag` | Add a tag `{tag}` |
+| POST | `/api/notes/link-suggestions` | Detect note titles as plain text → wikilink candidates |
+| GET | `/api/notes/by-title` | Resolve note by exact title |
+| POST | `/api/notes/resolve-title` | Get-or-create by title (wikilink click) |
+| GET / PUT / PATCH / DELETE | `/api/notes/:id` | Read / replace / patch / delete |
+| POST | `/api/notes/:id/convert-to-task` | Note → task |
+| POST | `/api/notes/:id/convert-to-note` | Task → note |
 | GET | `/api/notes/:id/backlinks` | Notes/tasks with `[[Title]]` references to this note |
-| GET | `/api/notes/:id/versions` | List note version history |
-| GET | `/api/notes/:id/versions/:vid` | Get a specific version |
-| GET | `/api/notes/:id/draft` | Get current AI draft |
-| PUT | `/api/notes/:id/draft` | Save AI draft |
-| DELETE | `/api/notes/:id/draft` | Delete AI draft |
-| POST | `/api/notes/assist` | Launch AI assist generation → 202 `{body, target_section?, instruction, whole_doc?}` |
-| GET | `/api/notes/assist/stream` | SSE stream for assist (Last-Event-ID reconnect; events: `chunk`, `done`, `error`) |
+| GET | `/api/notes/:id/versions` | Version history |
+| GET | `/api/notes/:id/versions/:vid` | A specific version |
+| 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 |
 
 ## Tasks
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/tasks` | List tasks. Params: `q`, `tag`, `status`, `priority`, `due_before`, `due_after`, `sort`, `order`, `limit`, `offset` |
-| POST | `/api/tasks` | Create task (accepts `project` name string → resolved to `project_id`) |
-| GET | `/api/tasks/:id` | Get task (includes `parent_title`) |
-| PUT | `/api/tasks/:id` | Full update |
+| GET | `/api/tasks` | List tasks (params: `q`, `tag`, `status`, `priority`, `overdue`, `sort`, `order`, `limit`, `offset`) |
+| POST | `/api/tasks` | Create task (accepts a `project` name string → resolved to `project_id`) |
+| POST | `/api/tasks/planning` | Start a plan (milestone + steps) |
+| GET / PUT / PATCH / DELETE | `/api/tasks/:id` | Read / update / delete |
 | PATCH | `/api/tasks/:id/status` | Quick status update `{status}` |
-| DELETE | `/api/tasks/:id` | Delete task |
-| GET | `/api/tasks/:id/logs` | List work logs |
-| POST | `/api/tasks/:id/logs` | Create log `{content, duration_minutes?}` |
-| PATCH | `/api/tasks/:id/logs/:log_id` | Update log |
-| DELETE | `/api/tasks/:id/logs/:log_id` | Delete log |
+| GET | `/api/tasks/:id/recurrence-preview` | Preview next recurrence occurrences |
 
-## Projects & Milestones
+**Task work logs**
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/projects` | List projects (owned + shared) |
-| POST | `/api/projects` | Create project |
-| GET | `/api/projects/:id` | Get project with `milestone_summary` |
-| PATCH | `/api/projects/:id` | Update project |
-| DELETE | `/api/projects/:id` | Delete project |
+| GET / POST | `/api/tasks/:id/logs` | List / append a work log `{content, duration_minutes?}` |
+| PATCH / DELETE | `/api/tasks/:id/logs/:log_id` | Update / delete a log |
+
+## Projects, Milestones, Systems, Issues
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET / POST | `/api/projects` | List (owned + shared) / create |
+| GET / PATCH / DELETE | `/api/projects/:id` | Read (with `milestone_summary`) / update / delete |
 | GET | `/api/projects/:id/notes` | Notes + tasks in this project |
-| GET | `/api/projects/:id/milestones` | List milestones |
-| POST | `/api/projects/:id/milestones` | Create milestone |
-| PATCH | `/api/projects/:id/milestones/:mid` | Update milestone |
-| DELETE | `/api/projects/:id/milestones/:mid` | Delete milestone |
+| GET / POST | `/api/projects/:id/milestones` | List / create milestones |
+| GET / PATCH / DELETE | `/api/projects/:id/milestones/:mid` | Read / update / delete |
+| GET | `/api/projects/:id/milestones/:mid/tasks` | Tasks in a milestone |
+| 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 |
+| GET | `/api/projects/:id/issues` | Project issues |
+
+## Knowledge browse
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/knowledge` | Unified note/task/plan/process feed (params: `type`, `tags`, `sort`, `q`, `limit`, `offset`) |
+| GET | `/api/knowledge/ids` | ID-only page (two-tier pagination) |
+| GET | `/api/knowledge/batch` | Fetch items by id |
+| GET | `/api/knowledge/tags` | Tags in scope |
+| GET | `/api/knowledge/counts` | Per-type counts |
+
+## Search
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/search` | Semantic + keyword search over notes/tasks (params: `q`, `type`, `limit`) |
+
+## Rulebooks and rules
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET / POST | `/api/rulebooks` | List / create rulebooks |
+| GET / PATCH / DELETE | `/api/rulebooks/:id` | Read / update / delete |
+| GET / POST | `/api/rulebooks/:id/topics` | List / create topics |
+| PATCH / DELETE | `/api/rulebook-topics/:tid` | Edit / delete a topic |
+| 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/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 |
 
 ## Sharing
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/projects/:id/shares` | List project shares |
-| POST | `/api/projects/:id/shares` | Create project share `{user_id?, group_id?, permission}` |
-| PATCH | `/api/projects/:id/shares/:sid` | Update permission |
-| DELETE | `/api/projects/:id/shares/:sid` | Remove share |
-| GET | `/api/notes/:id/shares` | List note shares |
-| POST | `/api/notes/:id/shares` | Create note share |
-| PATCH | `/api/notes/:id/shares/:sid` | Update permission |
-| DELETE | `/api/notes/:id/shares/:sid` | Remove share |
+| GET / POST | `/api/projects/:id/shares` | List / add project shares `{user_id?, group_id?, permission}` |
+| PATCH / DELETE | `/api/projects/:id/shares/:sid` | Update permission / remove |
+| GET / POST | `/api/notes/:id/shares` | List / add note shares |
+| PATCH / DELETE | `/api/notes/:id/shares/:sid` | Update permission / remove |
 | GET | `/api/shared-with-me` | All resources shared with the current user |
 
 ## Groups
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/groups` | List all groups (admin only) |
-| POST | `/api/groups` | Create group `{name, description?}` |
-| PATCH | `/api/groups/:id` | Update group |
-| DELETE | `/api/groups/:id` | Delete group |
-| GET | `/api/groups/:id/members` | List members |
-| POST | `/api/groups/:id/members` | Add member `{user_id, role}` |
-| PATCH | `/api/groups/:id/members/:uid` | Update member role |
-| DELETE | `/api/groups/:id/members/:uid` | Remove member |
-
-## Chat
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/chat/conversations` | List conversations (params: `limit`, `offset`) |
-| POST | `/api/chat/conversations` | Create conversation `{title?, model?}` |
-| POST | `/api/chat/conversations/bulk-delete` | Delete multiple conversations `{ids: number[]}` |
-| GET | `/api/chat/conversations/:id` | Get conversation with all messages |
-| PATCH | `/api/chat/conversations/:id` | Update title or model |
-| DELETE | `/api/chat/conversations/:id` | Delete conversation (cascades to messages) |
-| POST | `/api/chat/conversations/:id/messages` | Start generation → 202. Body: `{content, context_note_id?, include_note_ids?, rag_project_id?, workspace_project_id?, think?}` |
-| GET | `/api/chat/conversations/:id/generation/stream` | SSE stream (Last-Event-ID reconnect; events: `context`, `chunk`, `tool_call`, `status`, `done`, `error`) |
-| POST | `/api/chat/conversations/:id/generation/cancel` | Cancel active generation |
-| POST | `/api/chat/messages/:id/save-as-note` | Save assistant message as note |
-| POST | `/api/chat/conversations/:id/summarize` | Summarize conversation → note |
-| GET | `/api/chat/status` | Ollama availability + model state `{ollama, model, default_model}` |
-| GET | `/api/chat/models` | List installed Ollama models (includes `loaded: bool`, `modified_at`) |
-| POST | `/api/chat/models/pull` | Pull model (SSE NDJSON progress) `{model}` |
-| POST | `/api/chat/models/delete` | Delete model `{model}` |
-| GET | `/api/chat/ps` | Currently loaded (hot) models |
-| POST | `/api/chat/warm` | Pre-load model into VRAM `{model}` → 202 |
-
-## Quick Capture
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/api/quick-capture` | Classify + create item from natural language `{text}` → `{success, type, message, data}` |
-
-## Search
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/search` | Semantic + keyword search across notes and tasks. Params: `q`, `type` (`note`/`task`/`all`), `limit` |
-
-## Briefing
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/briefing/config` | Get briefing configuration |
-| PUT | `/api/briefing/config` | Save briefing configuration |
-| GET | `/api/briefing/feeds` | List RSS feeds |
-| POST | `/api/briefing/feeds` | Add RSS feed `{url, name?, category?}` |
-| DELETE | `/api/briefing/feeds/:id` | Delete feed |
-| POST | `/api/briefing/feeds/refresh` | Trigger immediate feed refresh → `{feeds_refreshed, new_items}` |
-| GET | `/api/briefing/weather` | Get weather configuration |
-| PUT | `/api/briefing/weather` | Save weather locations |
-| POST | `/api/briefing/weather/geocode` | Geocode address `{query}` → `{lat, lon, label}` |
-| POST | `/api/briefing/trigger` | Manually fire a briefing slot `{slot}` |
-| GET | `/api/briefing/conversations` | List past briefing conversations |
-| GET | `/api/briefing/conversations/today` | Get/create today's briefing conversation |
-| GET | `/api/briefing/conversations/:id/messages` | Get messages for a briefing conversation |
-
-## Settings
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/settings` | All settings as `{key: value}` |
-| PUT | `/api/settings` | Update settings `{key: value, ...}` |
-| GET | `/api/settings/models` | Installed models + defaults |
-| GET | `/api/settings/search` | Proxy SearXNG search (params: `q`) |
-
-## API Keys
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/api-keys` | List user's API keys |
-| POST | `/api/api-keys` | Create key `{name, scope}` → `{key, ...}` (key shown once) |
-| DELETE | `/api/api-keys/:id` | Revoke key |
-
-## Fable MCP Distribution
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/fable-mcp/info` | `{available: bool, filename: string\|null}` |
-| GET | `/api/fable-mcp/download` | Download wheel file |
+| GET / POST | `/api/groups` | List / create groups |
+| GET / PATCH / DELETE | `/api/groups/:id` | Read / update / delete |
+| GET / POST | `/api/groups/:id/members` | List / add members `{user_id, role}` |
+| PATCH / DELETE | `/api/groups/:id/members/:uid` | Update role / remove |
 
 ## Notifications
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/notifications` | List notifications |
+| GET | `/api/notifications` | List in-app notifications |
 | GET | `/api/notifications/count` | Unread count |
-| POST | `/api/notifications/:id/read` | Mark read |
+| POST | `/api/notifications/:id/read` | Mark one read |
 | POST | `/api/notifications/read-all` | Mark all read |
 
-## Push
+## Profile and Settings
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/push/vapid-public-key` | VAPID public key for subscription |
-| POST | `/api/push/subscribe` | Register push subscription |
-| DELETE | `/api/push/subscribe` | Unregister push subscription |
+| 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 |
 
-## Images
+## API keys
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/images/:id` | Serve cached image **(no auth required — IDs are opaque SHA-256)** |
+| GET / POST | `/api/api-keys` | List / create `fmcp_` keys (key shown once) |
+| DELETE | `/api/api-keys/:id` | Revoke a key |
 
-## Users
+## Plugin (Claude Code)
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/users/search` | Search users by username/email prefix (param: `q`, min 2 chars, excludes self) |
+| GET | `/api/plugin/context` | SessionStart context payload (rules + active-project) |
+| GET | `/api/plugin/retrieve` | Title-first knowledge-injection candidates |
+| GET | `/api/plugin/processes` | Stored Processes for skill-stub sync |
+| GET / PUT | `/api/plugin/marketplace-url` | Read / set the plugin marketplace URL |
 
-## Export
+## Dashboard, Export, Trash, Users
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/export` | Export data. Params: `format=markdown` (ZIP with `.md` + YAML frontmatter) or `format=json` |
+| GET | `/api/dashboard` | Home dashboard payload |
+| GET | `/api/export` | Personal export (`format=markdown` ZIP or `format=json`) |
+| GET | `/api/trash` | List trashed items, grouped by delete batch |
+| POST | `/api/trash/:batch/restore` | Restore a batch |
+| DELETE | `/api/trash/:batch` | Purge a batch (irreversible) |
+| GET | `/api/users/search` | Search users by prefix (for sharing) |
 
 ## Admin
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/admin/backup` | Export backup (`?scope=user` for own data; full requires admin) |
-| POST | `/api/admin/restore` | Restore from JSON backup |
-| GET | `/api/admin/users` | List all users |
-| DELETE | `/api/admin/users/:id` | Delete user (cannot delete self) |
-| GET | `/api/admin/registration` | Get registration open/closed state |
-| PUT | `/api/admin/registration` | Toggle registration `{open: bool}` |
-| POST | `/api/admin/invitations` | Create invitation `{email}` → sends email |
-| GET | `/api/admin/invitations` | List pending invitations |
-| DELETE | `/api/admin/invitations/:id` | Revoke invitation |
-| GET | `/api/admin/logs` | Log entries. Params: `category`, `user_id`, `search`, `date_from`, `date_to`, `limit`, `offset` |
-| GET | `/api/admin/logs/stats` | Log category counts |
-| GET | `/api/admin/base-url` | Get base URL setting |
-| PUT | `/api/admin/base-url` | Set base URL `{base_url}` |
-| GET | `/api/admin/smtp` | Get SMTP config (password masked) |
-| PUT | `/api/admin/smtp` | Save SMTP config |
-| POST | `/api/admin/smtp/test` | Send test email `{recipient}` |
+| GET | `/api/admin/backup` | Export backup (format v4; `?scope=user` for own data) |
+| POST | `/api/admin/restore` | Restore from a backup |
+| 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/db-maintenance` (+ `/health`, POST `/run`) | VACUUM schedule, health, manual run |
+| POST / GET / DELETE | `/api/admin/invitations` (+ `/:id`) | Create / list / revoke invite links |
+
+## Scribe 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
+surface — it exposes the same data as typed tools (`create_note`, `create_task`,
+`start_planning`, `search`, `enter_project`, `list_always_on_rules`, …) with
+server-level usage guidance delivered in the MCP `instructions` block. See
+[API Keys & MCP](api-keys-and-mcp.md).

docs/architecture.md

@@ -20,7 +20,7 @@
 │              Docker Compose                  │
 │                                              │
 │  ┌──────────────────────┐   ┌────────────┐  │
-│  │  fabledassistant     │   │  ollama    │  │
+│  │  scribe     │   │  ollama    │  │
 │  │  ┌────────────────┐  │   │            │  │
 │  │  │  Quart Server  │  │   │  LLM API   │  │
 │  │  │  ┌──────────┐  │  │   │            │  │
@@ -43,22 +43,20 @@
 ## Project Structure
 
 ```
-fabledassistant/
+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)
-├── fable-mcp/                   # Fable MCP server package
-│   └── fable_mcp/
-│       ├── server.py            # FastMCP tool registrations
-│       ├── client.py            # FableClient (httpx wrapper)
-│       └── tools/               # Tool modules (notes, tasks, projects, …)
-├── src/fabledassistant/
+├── 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)
@@ -133,11 +131,11 @@ 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`, `briefing_enabled`, `briefing_locations`, `office_days`, etc.
+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`/`briefing`/`mcp`), `briefing_date`, `rag_project_id` (nullable int — RAG scope: NULL=orphan-only, -1=all, positive=project), `created_at`, `updated_at`.
+`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.
@@ -155,11 +153,9 @@ Title auto-generated by LLM on first exchange, re-generated every 10th message.
 
 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.
 
-### Briefing-Related Tables
+### Journal-Related Tables
 
-`rss_feeds`: `id`, `user_id`, `url`, `name`, `category`, `last_fetched_at`.
-`rss_items`: `id`, `feed_id` FK, `guid`, `title`, `url`, `summary`, `pub_date`.
-`weather_cache`: per-user cache with `lat`, `lon`, `location_name`, `forecast_json`, `fetched_at`.
+`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
 
@@ -171,7 +167,7 @@ Permission resolution is centralised in `services/access.py`. `get_project_permi
 
 ## Detailed File Reference
 
-### Backend (`src/fabledassistant/`)
+### Backend (`src/scribe/`)
 
 | File | Responsibility |
 |------|---------------|
@@ -188,14 +184,14 @@ Permission resolution is centralised in `services/access.py`. `get_project_permi
 | `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; briefing conversation routes |
+| `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/briefing.py` | Briefing conversation + reply + history; RSS feed management |
+| `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 |
@@ -204,7 +200,7 @@ Permission resolution is centralised in `services/access.py`. `get_project_permi
 | `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`) |
-| `routes/fable_mcp_dist.py` | `GET /api/fable-mcp/info` + `GET /api/fable-mcp/download` — package distribution |
+| `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 |
@@ -212,8 +208,8 @@ Permission resolution is centralised in `services/access.py`. `get_project_permi
 | `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` | `classify_intent()` — fast non-streaming LLM call; intent skip heuristic; `_PRIOR_WORK_REFS` fast-path |
-| `services/tools.py` | All LLM tool definitions + `execute_tool(user_id, tool_name, arguments, conv_id=None, workspace_project_id=None)` dispatcher; duplicate guards; `_resolve_project()` 4-step lookup; `search_projects` and `set_rag_scope` tools |
+| ~~`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) |
@@ -227,11 +223,12 @@ Permission resolution is centralised in `services/access.py`. `get_project_permi
 | `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/briefing_pipeline.py` | Two-lane parallel gather → LLM synthesis → `GenerationBuffer` stream |
-| `services/briefing_scheduler.py` | APScheduler `BackgroundScheduler`; slots with catch-up logic; async-safe via `asyncio.create_task` |
-| `services/briefing_conversations.py` | Briefing conversation persistence and history queries |
-| `services/briefing_profile.py` | Per-user profile note that the assistant updates over time |
-| `services/research.py` | SearXNG research pipeline: 5 sub-queries → parallel fetch → synthesis; `search_images` for image category |
+| `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 |
@@ -291,10 +288,10 @@ Permission resolution is centralised in `services/access.py`. `get_project_permi
 | `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.py` | All LLM tool implementations (`create_note`, `search_notes`, `get_weather`, …) |
+| `services/tools/` | LLM tool implementations (38 tools across 11 modules); decorator-based registry |
 | `services/embeddings.py` | `upsert_note_embedding()`, `semantic_search_notes()` |
-| `services/briefing_pipeline.py` | Two-lane parallel gather → LLM synthesis → briefing output |
-| `services/briefing_scheduler.py` | APScheduler integration, catch-up logic for missed slots |
+| `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 |
@@ -311,26 +308,22 @@ See [sso-oauth.md](sso-oauth.md) for provider-specific setup instructions.
 
 ## LLM Pipeline Internals
 
-### Intent Routing
+### Tool Routing
 
-Before the main model runs, a lightweight intent classifier (`services/intent.py`) runs concurrently with `build_context()`. It makes a fast non-streaming call using a smaller dedicated model (`OLLAMA_INTENT_MODEL`, default `qwen2.5:7b`) to determine if the message requires a tool call.
-
-**Skip heuristic** — Intent classification is skipped entirely for short messages (≤10 words) with no action/object keywords, saving 400–800ms on conversational replies.
-
-**Prior-work fast-path** — `_PRIOR_WORK_REFS` regex detects phrases like "research you did", "note you made", "using your research" and returns no-tool immediately, preventing `search_web` from firing when the user references existing notes.
-
-If a tool is detected, the intent's one-sentence `ack` field is streamed as the first chunk (TTFT), the tool executes, then the main model generates a follow-up with the tool result. For chat-only responses the main model streams directly.
+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.py`; `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.
+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.
 
-**Duplicate protection on `create_note` / `create_task`:**
+**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 ≥ 200 chars) → soft block with `requires_confirmation: true`
+3. Semantic content similarity (threshold 0.90, body ≥ 80 chars) → soft block with `requires_confirmation: true`
 
-**Project resolution** (`_resolve_project`): 4-step lookup — (1) exact DB match, (2) `query in title` substring, (3) `title in query` reverse substring, (4) SequenceMatcher ≥ 0.55.
+**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
 
@@ -344,8 +337,11 @@ History summarisation threshold: 30 messages. Keeps 8 recent messages. Summary m
 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. Up to 12 sources passed to synthesis LLM
-5. Result saved as a note with `tags=["research"]`
+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.
 

docs/configuration.md

@@ -8,7 +8,7 @@ Configuration is via environment variables. The `docker-compose.yml` file sets d
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DATABASE_URL` | `postgresql+asyncpg://fabled:fabled@db/fabledassistant` | PostgreSQL async connection string |
+| `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`) |
@@ -58,12 +58,6 @@ See [sso-oauth.md](sso-oauth.md) for provider-specific setup.
 | `LOG_RETENTION_DAYS` | `90` | Days to keep app logs before automatic pruning |
 | `DATA_DIR` | `/data` | Root directory for persistent data (VAPID keys, backups) |
 
-### Fable MCP Distribution
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `FABLE_MCP_DIST_DIR` | `/app/dist` | Directory where the bundled `fable-mcp` wheel is placed at build time |
-
 ## Docker Compose Setup
 
 ### Development (`docker-compose.yml`)
@@ -91,7 +85,7 @@ The production compose file adds:
 ```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/fabledassistant" | docker secret create fabled_db_url -
+echo "postgresql+asyncpg://fabled:strongpassword@db/scribe" | docker secret create fabled_db_url -
 
 # Deploy
 docker stack deploy -c docker-compose.prod.yml fabled

docs/design-system.md

@@ -0,0 +1,573 @@
+# FabledSword Design System
+
+A house-style design system for the FabledSword family of self-hosted applications. FabledSword is the umbrella identity; individual apps share a common visual language but each carries its own signature accent color.
+
+## Brand model
+
+FabledSword is a **house style**, not a single brand. Apps share:
+
+- Typography
+- Surfaces and dark-mode foundation
+- Component shapes (pills, cards, buttons)
+- Spacing system
+- Semantic colors (success, warning, error, info)
+- Action button colors (moss primary, bronze secondary)
+- Voice and tone
+
+Each public app has its own **signature accent** used for: the wordmark, the app icon, active nav state, "you are here" indicators, cursor/selection color, and key brand moments. Accents do **not** appear on action buttons — those stay system-wide.
+
+## Aesthetic direction
+
+Modern mythic with heraldic restraint. Tech-forward execution, but the visual language borrows from manuscripts, heraldry, and forged objects rather than from gaming or fantasy iconography. Dark-mode-first because that's where these apps live.
+
+The reference points: a well-printed book, a well-kept armory, a steward's ledger. Not: a fantasy novel cover, a tabletop RPG character sheet, a Renaissance Faire poster.
+
+---
+
+## Color system
+
+### Universal surfaces (dark mode foundation)
+
+| Token | Hex | Usage |
+|---|---|---|
+| Obsidian | `#14171A` | Page background, deepest surface |
+| Iron | `#1E2228` | Card surfaces, raised elements |
+| Slate | `#2C313A` | Hovered surfaces, secondary elevation |
+| Pewter | `#3F4651` | Borders, dividers, ghost button outlines |
+
+### Universal text and parchment
+
+| Token | Hex | Usage |
+|---|---|---|
+| Parchment | `#E8E4D8` | Primary text on dark surfaces |
+| Vellum | `#C2BFB4` | Secondary text, captions |
+| Ash | `#9C9A92` | Tertiary text, hints, metadata |
+
+Parchment is intentionally not pure white — it's slightly warm to feel like aged paper. Pure white (#FFFFFF) is never used as text color.
+
+### Universal action colors
+
+| Token | Hex | Usage |
+|---|---|---|
+| Moss | `#4A5D3F` | Primary action buttons (Save, Submit, Confirm) |
+| 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.
+
+### Semantic colors
+
+| Token | Hex | Usage |
+|---|---|---|
+| Success | `#4A5D3F` | Success states (same as Moss — they're aligned by design) |
+| Warning | `#8B6F1E` | Warnings, caution states |
+| Error | `#C04A1F` | Error messages, validation failures |
+| Info | `#3D5A6E` | Informational callouts |
+| Destructive | `#6B2118` | Destructive action buttons (Delete, Remove, irreversible) |
+
+**Why error and destructive are different:** Error is the orange-red used in alerts and validation messages. Destructive (oxblood) is reserved for buttons that perform irreversible actions — it carries more weight precisely because it's used sparingly. Pair destructive buttons with an icon (trash, X) so color is reinforcement, not the only signal.
+
+### Per-app signature accents
+
+| App | Hex | Mood |
+|---|---|---|
+| Fabled Scribe | `#5B4A8A` | Dusty violet — ink, manuscripts |
+| Minstrel | `#4A6B5C` | Forest teal — music, performance |
+| Fabled Forge | `#8B5A2B` | Forge bronze — creation, craft |
+| Roundtable | `#4A5D7E` | Slate blue — stewardship, infrastructure |
+| FabledSword (umbrella) | `#6B2118` | Oxblood — house identity, ceremonial use only |
+
+**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 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.
+
+### Color contrast
+
+All text-on-surface combinations meet WCAG AA at minimum. Parchment on Obsidian is the maximum-contrast pairing; Vellum on Iron is the lowest-contrast pairing still considered acceptable for body text. Ash is for hints only — never load-bearing information.
+
+---
+
+## Typography
+
+### Type families
+
+| Family | Role | Source |
+|---|---|---|
+| Fraunces | Display, headings, wordmarks | Google Fonts |
+| Inter | Body, UI, labels | Google Fonts |
+| JetBrains Mono | Code, terminal output, monospaced data | Google Fonts |
+
+### 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.
+
+### Type scale
+
+| Token | Size | Weight | Family | Usage |
+|---|---|---|---|---|
+| Display | 40px | 500 | Fraunces | App wordmark, hero text |
+| H1 | 32px | 500 | Fraunces | Page titles |
+| H2 | 24px | 500 | Fraunces | Section headings |
+| H3 | 18px | 500 | Inter | Subsection headings, card titles |
+| Body | 15px | 400 | Inter | Paragraphs, default text |
+| Body small | 13px | 400 | Inter | Captions, metadata |
+| Label | 12px | 500 | Inter | Buttons, form labels, badges |
+| Code | 13px | 400 | JetBrains Mono | Inline code, code blocks |
+| Tiny | 11px | 500 | Inter | Micro-labels (`UPPERCASE LETTERSPACED`) |
+
+### Typography rules
+
+- **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).
+- **Letter-spacing** at default for everything except the Tiny micro-label, which gets `0.08em` letter-spacing and uppercase styling.
+
+---
+
+## Spacing and layout
+
+### Spacing scale (px)
+
+`4, 8, 12, 16, 20, 24, 32, 48, 64, 96`
+
+Use rem units for vertical rhythm in long-form content (paragraph spacing). Use px for component-internal spacing (padding, gaps).
+
+### Border radius
+
+| Token | Size | Usage |
+|---|---|---|
+| Small | 4px | Pills, tags, code spans |
+| Medium | 8px | Buttons, inputs, small cards |
+| Large | 12px | Cards, panels, modals |
+| Extra large | 16px | Hero containers, major surfaces |
+
+### Borders
+
+- Default border: `0.5px solid Pewter` (#3F4651)
+- Hovered/emphasized border: `0.5px solid Vellum` at 30% opacity
+- Featured/active border: `2px solid [accent]` (only for emphasizing a selected card or active tab)
+
+The 0.5px default is deliberate — it reads as a hairline at most pixel densities and avoids the heavy "boxed-in" feeling that 1px+ borders create on dark backgrounds.
+
+---
+
+## Components
+
+### Buttons
+
+| Variant | Background | Text | Border |
+|---|---|---|---|
+| Primary | Moss `#4A5D3F` | Parchment | None |
+| Secondary | Bronze `#8B7355` | Parchment | None |
+| Ghost | Transparent | Parchment | 0.5px Pewter |
+| Destructive | Oxblood `#6B2118` | Parchment | None — pair with icon |
+
+Padding: `8px 16px` for default, `6px 12px` for compact, `10px 20px` for prominent. Border-radius: 8px. Font: Inter 12px/500 with default letter-spacing.
+
+### Pills and tags
+
+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.
+
+### Cards
+
+- Background: Iron (#1E2228)
+- Border: 0.5px Pewter
+- Border-radius: 12px
+- Padding: 20px
+
+For featured/selected cards, swap to a 2px solid accent border. Don't change the background.
+
+### Inputs
+
+- Background: Obsidian (#14171A) — darker than the page surface to feel "inset"
+- Border: 0.5px Pewter
+- Border-radius: 8px
+- Padding: 8px 12px
+- Focus state: 2px solid accent ring (using `box-shadow: 0 0 0 2px [accent]` to avoid layout shift)
+
+### Code blocks
+
+- Background: Obsidian (#14171A)
+- Border: 0.5px Pewter
+- Border-radius: 8px
+- Padding: 12px 16px
+- Font: JetBrains Mono 13px/400
+- Inline code: same family, with 4px-radius pill background using the app accent at 15% opacity
+
+---
+
+## The FabledSword lockup
+
+A small, persistent FS mark appears in the navigation chrome of every app — the way an Apple logo persists across macOS apps. This is the only place oxblood appears in normal app usage.
+
+**Specification:**
+- 16-20px height in nav contexts
+- Oxblood (#6B2118) on dark surfaces
+- Positioned in the bottom-left of nav rails or top-left when there's no rail
+- Hover/click reveals a small menu: link to other apps in the family, link to FabledSword.com, version info
+
+The lockup itself is a small heraldic mark — a stylized FS monogram — *not* a literal sword icon. We're avoiding sword imagery in app chrome because it would clash with the restrained, modern-mythic aesthetic. The wordmark "FabledSword" appears only on the umbrella site and in About/Settings dialogs.
+
+---
+
+## Voice and tone
+
+The FabledSword voice is **understated mythic** — it borrows the register of stewardship, craft, and considered making, but never tips into roleplay or affectation.
+
+### Do
+
+- Use plain language for everything functional. ("Save", "Cancel", "Add note")
+- Reserve flavored language for moments where the user is *waiting* or *failing* — loading states, empty states, error pages, 404s.
+- Borrow vocabulary from craft and stewardship: "draft", "ledger", "kept", "set aside", "to come", "in progress", "abandoned".
+- Be brief. The mythic register is undermined by verbosity.
+
+### Don't
+
+- Don't use thee/thou/thy or pseudo-archaic spelling.
+- Don't address the user as "traveler", "wanderer", "adventurer", or any RPG-adjacent epithet.
+- Don't use sword/blade/forge metaphors in error messages. ("Your save was forged successfully" — no.)
+- Don't make the user feel like they're playing a game when they're just trying to use software.
+
+### Examples
+
+| Context | Plain | FabledSword voice |
+|---|---|---|
+| Empty list | "No items yet" | "Nothing kept here yet." |
+| 404 | "Page not found" | "This page is not in the ledger." |
+| Loading | "Loading..." | "Fetching..." (just keep it plain — the mythic note is reserved for moments with more space) |
+| Save success | "Saved!" | "Saved." (plain — success doesn't need flavor) |
+| Save error | "Error saving" | "Couldn't save. The change has been kept locally — try again in a moment." |
+| Delete confirm | "Delete this?" | "Remove this from the ledger? This can't be undone." |
+
+The pattern: action-adjacent language stays plain; absence/failure/waiting gets the flavor.
+
+---
+
+## Iconography
+
+### Style
+
+- Stroke-based, 1.5px stroke weight at 24px, 1px at 16px
+- Rounded line caps and joins
+- 24px or 16px grid
+- Outline style by default; filled style only for active/selected states
+
+Use **Lucide** (https://lucide.dev) as the base icon set — it matches this style exactly and is open-source. Only commission custom icons for app-specific concepts that Lucide doesn't cover.
+
+### Don't
+
+- No filled icons in default UI (reserve for active states)
+- No icon styles that mix stroke and fill chaotically
+- No literal medieval imagery (swords, scrolls with curls, banners) in functional UI
+- No emoji as icons
+
+---
+
+## Per-app application
+
+### Fabled Scribe (#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.
+
+### Minstrel (#4A6B5C — forest teal)
+
+Self-hosted music. The accent appears on: now-playing indicators, active track highlights, the wordmark, equalizer/visualization elements. Album art dominates visually, so the accent should appear in chrome and metadata, never overlapping cover imagery.
+
+### Fabled Forge (#8B5A2B — forge bronze)
+
+Story-building and worldbuilding tool. The accent appears on: the wordmark, character/location/object markers in story trees, the editor cursor, "kept/canon" indicators distinguishing finalized story elements from drafts. This app benefits from Fraunces being used more aggressively — for entity titles, chapter headings, etc.
+
+### Roundtable (#4A5D7E — slate blue)
+
+Home server management. The accent appears on: the wordmark, healthy/online status indicators, the active dashboard panel border. Status colors here are critical — green for healthy, amber for warning, red (the orange-red error tone, not oxblood) for failed. The accent itself indicates "this is the panel I'm currently looking at."
+
+**Naming note:** "Roundtable" leans the wrong direction — its connotation is *equal participants in discussion* rather than *one steward managing a domain*. Consider "Steward" or "Castellan" if you revisit naming. Castellan in particular is good — it specifically means "the officer in charge of a castle."
+
+---
+
+## Implementation notes
+
+### CSS custom properties
+
+```css
+:root {
+  /* Surfaces */
+  --fs-obsidian: #14171A;
+  --fs-iron: #1E2228;
+  --fs-slate: #2C313A;
+  --fs-pewter: #3F4651;
+
+  /* Text */
+  --fs-parchment: #E8E4D8;
+  --fs-vellum: #C2BFB4;
+  --fs-ash: #9C9A92;
+
+  /* Action */
+  --fs-moss: #4A5D3F;
+  --fs-bronze: #8B7355;
+
+  /* Semantic */
+  --fs-warning: #8B6F1E;
+  --fs-error: #C04A1F;
+  --fs-info: #3D5A6E;
+  --fs-oxblood: #6B2118;
+
+  /* Typography */
+  --fs-font-display: 'Fraunces', Georgia, serif;
+  --fs-font-body: 'Inter', system-ui, sans-serif;
+  --fs-font-mono: 'JetBrains Mono', ui-monospace, monospace;
+
+  /* Layout */
+  --fs-radius-sm: 4px;
+  --fs-radius-md: 8px;
+  --fs-radius-lg: 12px;
+  --fs-radius-xl: 16px;
+}
+
+/* Per-app accent — set ONE of these on the root for each app */
+[data-app="scribe"]    { --fs-accent: #5B4A8A; }
+[data-app="minstrel"]  { --fs-accent: #4A6B5C; }
+[data-app="forge"]     { --fs-accent: #8B5A2B; }
+[data-app="roundtable"]{ --fs-accent: #4A5D7E; }
+```
+
+### Tailwind integration
+
+If using Tailwind, extend the theme with these tokens rather than relying on default colors. The default Tailwind palette will fight this system — you'll get drift back toward bright defaults if you don't lock down the palette explicitly.
+
+---
+
+## What this kit deliberately does NOT include
+
+- **Logo files.** The lockup design is described conceptually but the actual mark needs to be drawn. Hire a designer or use Claude Design to iterate on a heraldic FS monogram.
+- **Marketing site design.** This kit is for application UI. The umbrella marketing site (FabledSword.com) can use this system but will need additional patterns (hero layouts, feature grids, etc.).
+- **Email templates.** Different constraints, different problem.
+- **Print collateral.** Not in scope.
+- **Mobile native app patterns.** This is web-first. iOS/Android conventions would override several choices here (button shapes, navigation patterns).
+
+---
+
+*Last updated: April 25, 2026. Iterate as the family of apps grows.*
+
+---
+
+# 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.*

docs/development.md

@@ -57,7 +57,9 @@ Migration conventions:
 
 ### Pipeline
 
-CI runs on Forgejo Actions with a custom runner base image (`py3.12-node22`):
+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):
 
 | Trigger | Jobs | Docker tags pushed |
 |---------|------|--------------------|
@@ -77,17 +79,21 @@ CI runs on Forgejo Actions with a custom runner base image (`py3.12-node22`):
    git checkout dev && git merge main && git push origin dev
    ```
 
-### Custom Runner
+### Runner
 
-Runner base image: `infra/Dockerfile.runner-base` (Ubuntu 24.04 + Python 3.12 + Node 22 LTS).
-Runner config: `infra/act-runner-config.yml` (label: `py3.12-node22`).
-Runner compose: `infra/runner-compose.yml`.
+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.
 
-To activate a new runner registration, copy `infra/act-runner-config.yml` to the runner's config directory, delete the `.runner` registration file in the runner container, and restart the stack.
+`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/fabledassistant`
+Images pushed to: `git.fabledsword.com/bvandeusen/scribe`
 Cache tag: `:cache` (reduces build time ~80%)
 
 Required secrets (repo → Settings → Secrets → Actions):
@@ -134,8 +140,8 @@ Current migration sequence (all idempotent raw SQL):
 
 ### Backend
 
-- Services: `async with async_session() as session:` — import from `fabledassistant.models`
-- No `fabledassistant.database` module
+- 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
@@ -158,7 +164,7 @@ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 ```
 
 Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
-Scopes: feature area (e.g. `chat`, `briefing`, `fable-mcp`, `notes`)
+Scopes: feature area (e.g. `chat`, `journal`, `mcp`, `notes`)
 
 ## Testing
 

docs/features.md

@@ -1,154 +1,168 @@
 # 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.
+
 ## 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.
+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.
 
-**Wikilinks** — Link notes with `[[Title]]` or `[[Title|Display Text]]` syntax. Clicking a wikilink navigates to (or auto-creates) the referenced note. The editor suggests existing note titles as candidate links while typing `[[`. Backlinks appear in the note viewer sidebar.
+- **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.
 
-**Tags** — First-class `ARRAY[text]` column. Tag autocomplete in the editor sidebar suggests existing tags. Hierarchical tags (`project/webapp`) supported — filtering by `project` matches all `project/*` children. Tags are browsable via the knowledge graph.
+## Tasks and Issues
 
-**Version history** — Every body edit snapshots a version (up to 20 per note). Browse and restore from the editor's History panel. Diff view shows changes against the current body.
+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.
 
-**AI writing assist** — Select a passage or work on the full document. Give an instruction ("make this more concise", "add examples"). The assistant streams a proposal; a diff view shows changes to accept or reject. Drafts persist across page loads.
-
-**Link suggestions** — The editor detects note titles appearing as plain text in the body and suggests converting them to wikilinks.
-
-## Tasks
-
-Tasks carry status (`todo` → `in_progress` → `done`), priority (`none`/`low`/`medium`/`high`), due date, milestone assignment, and a parent task (sub-tasks).
-
-**Task work logs** — Append progress log entries to a task with optional duration. Time tracking is visible in the task editor sidebar.
-
-**Sub-tasks** — Any task can have child tasks via `parent_id`. The task viewer shows sub-tasks inline.
-
-**Convert freely** — Convert a note to a task (sets `status=todo`) or a task back to a note from the viewer toolbar.
+- **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.
 
 ## Projects and Milestones
 
-**Projects** — Group related notes and tasks. Each project has a title, description, goal, status (`active`/`completed`/`archived`), and a colour.
+- **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.
 
-**Milestones** — Ordered stages within a project. Tasks are assigned to milestones. Milestone completion percentage shown on the project page.
+## Systems
 
-**Kanban view** — `/projects/:id` groups tasks by milestone in a kanban-style column layout with status-advance buttons directly on cards (→ advance, ✓ complete).
+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.
 
-**Project Workspace** — `/workspace/:projectId` opens a three-panel environment (tasks / chat / notes) locked to a project. The AI assistant creates and updates content directly in the workspace; new notes auto-load in the editor and the task list refreshes automatically after tool calls.
+## Rules and Rulebooks
+
+Scribe stores the operator's engineering and workflow **rules** so Claude follows them
+across sessions.
+
+- **Rulebooks → topics → rules** — Rules are grouped by topic inside a rulebook.
+- **Always-on rules** — A rulebook can be flagged always-on; its rules load at the
+  start of every session through the plugin's push channel.
+- **Per-project scope** — A project subscribes to rulebooks, and can add
+  project-scoped rules or suppress individual inherited rules/topics.
+
+## Stored Processes
+
+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.
+
+## Search and Knowledge Injection
+
+- **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.
 
 ## Knowledge Graph
 
-`/graph` renders all notes, tasks, and tags as a D3 force-directed graph. Tag nodes cluster notes that share tags; invisible project hub nodes attract project members. Physics controls: repulsion, link distance, link strength, hub pull, gravity. Click any node to open a slide-in peek panel. Click a tag node to filter the notes list.
+`/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.
 
-## AI Chat
+## Claude via MCP and the plugin
 
-Full conversation history with SSE streaming. Features:
-- **RAG** — Semantically relevant notes (≥ 0.60 cosine similarity) auto-injected as context. Notes 0.45–0.60 shown in sidebar as "Suggested."
-- **Attach notes** — Paperclip icon to include specific notes in context.
-- **RAG scope chip** — Pill above the input bar shows the current note scope. Click to switch: "Orphan notes only" (default — project notes stay out of general chat), any active project, or "All notes." Scope is persisted per conversation. The AI can also call `search_projects` and `set_rag_scope` mid-conversation to switch scope automatically; the chip pulses when this happens.
-- **Tool calls** — The assistant can create/update notes, tasks, projects, milestones, search the web, check weather, read RSS, query calendar events, and more. Tool calls display inline with confirm/deny for creates.
-- **Thinking mode** — Toggle extended reasoning for complex questions.
-- **Abort** — Stop button cancels in-flight generation.
-- **Message queue** — Messages sent while generation is in progress are queued and drained sequentially.
-- **Save to note** — Save any assistant reply directly as a note.
-- **Bulk delete** — Select and delete multiple conversations.
-- **Retention** — Conversations auto-pruned after configurable days (default 90).
+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:
 
-## Daily Briefing
+- a `SessionStart` hook that injects the operator's always-on rules + 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.
 
-`/briefing` is a scheduled, dialogue-based morning briefing. The assistant compiles tasks, calendar events, projects, weather forecast, and RSS digest at configurable times, then checks in throughout the day. You can reply interactively.
-
-**Schedule** — Configurable slots: morning (default 4am compile), midday (8am check-in), evening (12pm check-in), night (4pm). Scheduler catches up missed slots on startup.
-
-**Configuration** — Settings → Briefing: enable toggle, location geocoding, office days, time slot toggles, RSS feed management, push notification toggle.
-
-**RSS feeds** — Add feed URLs with optional name and category. Feeds are fetched and cached; the briefing digest includes recent items. Category badges shown in the UI. Feeds can be manually refreshed.
-
-**Weather** — Location-based forecast via Open-Meteo. Multiple locations supported (home, work, or any city name). Geocoding via Nominatim.
-
-**Profile note** — The assistant maintains a profile note for each user that it updates based on briefing conversations, improving personalisation over time.
-
-## Web Research
-
-The assistant can search the web (SearXNG) and fetch pages, synthesising findings into notes. A lightweight `search_web` tool answers quick questions inline without saving. Requires `SEARXNG_URL` to be configured.
-
-## Calendar
-
-`/calendar` shows a full FullCalendar view (month, week, day). Click an empty slot to create an event; click an existing event to edit or delete it via a slide-over panel.
-
-**Internal events store** — Events are stored in the app database (`events` table), making them available without any external calendar. Fields: title, description, start/end datetime, all-day toggle, location, colour.
-
-**AI tools** — `create_event`, `list_events`, `search_events`, `update_event`, `delete_event` all operate on the internal store. Tool-call result cards in chat are clickable and open the same EventSlideOver for editing.
-
-**HomeView widget** — The dashboard shows today's and the next 7 days' events as clickable cards above the hero project.
-
-**CalDAV sync (optional)** — Connect an external CalDAV server (Nextcloud, Radicale, etc.) in Settings → Integrations. Events sync bidirectionally via a `caldav_uid` field.
+See [API Keys & MCP](api-keys-and-mcp.md).
 
 ## Sharing and Collaboration
 
-**Share** — Share any project or note/task with users or groups at `viewer`/`editor`/`admin` permission levels. Share button in the viewer/project toolbar opens a dialog.
+- **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.
 
-**Groups** — Admins create platform-wide groups and assign users `member`/`owner` roles. Share a resource with a group in one action.
-
-**Shared with me** — `/shared` lists all incoming shared projects and notes with permission badges.
-
-**Notifications** — Bell icon in nav shows unread count (60s polling). Notifications generated for: project shared, note shared, added to group. Click navigates to the resource.
-
-**Push notifications** — Web Push (VAPID) notifies when AI generation completes, even in another tab. Works over HTTPS only. Configurable per-user.
-
-## Quick Capture
-
-Quick capture from the Android app routes to the intent classifier. It creates notes, tasks, or projects based on content — using the user's configured model, not the hardcoded default.
+Every read and mutation is scoped by owner + direct shares + group shares.
 
 ## Data Export and Backup
 
-- **Personal export** — Settings → Data: download all notes/tasks as a Markdown ZIP (with YAML frontmatter) or JSON array.
-- **Admin backup** — Full application backup (version 2): includes projects, milestones, task logs, AI drafts, note versions, push subscriptions. ID remapping on restore for cross-instance migration.
+- **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.
 
-## PWA
+## Progressive Web App
 
-Installable as a desktop or mobile app. Service worker caches the shell; push notifications are suppressed when the relevant tab is already focused. Works over HTTPS only in Firefox.
+Installable as a desktop or mobile app; a service worker caches the shell.
+
+## 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).
 
 ## Settings
 
-Settings are tabbed:
-
 | Tab | Contents |
 |-----|----------|
-| General | Assistant name, default model, model management (pull/delete) |
+| General | Instance preferences (key/value) |
 | Account | Email change, password change, session invalidation |
-| Notifications | Push notification subscription, briefing push toggle |
-| Integrations | CalDAV configuration, SearXNG status |
-| Data | Personal export, backup/restore (admin) |
-| Briefing | Enable, location, office days, slots, RSS feeds, weather |
-| API Keys | Create/revoke API keys, Fable MCP download and install |
-| Config (admin) | Base URL, SMTP, OIDC settings |
+| 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 |
 
-## Roadmap
-
-- Email integration (read/send via IMAP/SMTP tools in chat)
-- Session invalidation on user deletion
-- Flutter push notifications (requires FCM/APNs — separate from web VAPID)
-- Flutter milestone support in project view
-
 ## Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| `g` + `h` | Go to Home |
-| `g` + `n` | Go to Notes |
-| `g` + `t` | Go to Tasks |
-| `g` + `p` | Go to Projects |
-| `g` + `c` | Go to Chat |
-| `g` (bare) | Go to Graph |
+| `g` + `h` | Home (dashboard) |
+| `g` + `n` | Notes |
+| `g` + `t` | Knowledge (tasks) |
+| `g` + `p` | Projects |
+| `g` + `r` | Rulebooks |
+| `g` (bare) | Graph |
+| `g` + `x` | Trash |
 | `n` | New note |
 | `t` | New task |
-| `c` | Focus chat input |
-| `e` | Edit current item |
-| `/` | Search |
+| `/` | Focus search |
 | `?` | Show shortcuts panel |
 | `j` / `k` | Navigate list items |
 | `Enter` | Open selected item |
-| `Escape` | Close panel / blur / go home (progressive) |
+| `e` | Edit current item |
+| `Esc` | Close panel / blur / go home (progressive) |
 | `Ctrl+S` | Save in editor |

docs/plans/2026-03-11-backup-rewrite.md

@@ -1,538 +0,0 @@
-# Backup Service Rewrite Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Rewrite `services/backup.py` so that full and user backup/restore correctly includes every model added since the original implementation (projects, milestones, task logs, drafts, versions), with correct FK re-mapping on restore.
-
-**Architecture:** Bump backup JSON format to version 2. Export is additive — all new tables exported. Restore builds an ID map for each table and patches FK references in the correct dependency order. V1 backups continue to restore via the existing code path.
-
-**Tech Stack:** Python/SQLAlchemy 2.0 async, no new dependencies.
-
-**Spec:** `docs/superpowers/specs/2026-03-11-backup-rewrite-design.md`
-
-**Dependency note:** This plan can be split into Part A (pre-sharing models) and Part B (sharing models). Part A is independent and should be done first.
-
----
-
-## Task 1: Extend export — full backup
-
-**Files:**
-- Modify: `src/fabledassistant/services/backup.py`
-
-- [ ] **Step 1: Read the current `export_full_backup()` function**
-
-Understand what is currently exported: users, notes (partial fields), conversations+messages, settings.
-
-- [ ] **Step 2: Rewrite `export_full_backup()` to version 2**
-
-Add all missing models to the import list at the top of `backup.py`:
-```python
-from fabledassistant.models.project import Project
-from fabledassistant.models.milestone import Milestone
-from fabledassistant.models.task_log import TaskLog
-from fabledassistant.models.note_draft import NoteDraft
-from fabledassistant.models.note_version import NoteVersion
-from fabledassistant.models.push_subscription import PushSubscription
-```
-
-Rewrite `export_full_backup()`:
-```python
-async def export_full_backup() -> dict:
-    async with async_session() as session:
-        users = (await session.execute(select(User))).scalars().all()
-        projects = (await session.execute(select(Project))).scalars().all()
-        milestones = (await session.execute(select(Milestone))).scalars().all()
-        notes = (await session.execute(select(Note))).scalars().all()
-        task_logs = (await session.execute(select(TaskLog))).scalars().all()
-        note_drafts = (await session.execute(select(NoteDraft))).scalars().all()
-        note_versions = (await session.execute(select(NoteVersion).order_by(NoteVersion.note_id, NoteVersion.version_number))).scalars().all()
-        conversations = (await session.execute(
-            select(Conversation).options(selectinload(Conversation.messages))
-        )).scalars().all()
-        settings = (await session.execute(select(Setting))).scalars().all()
-        push_subs = (await session.execute(select(PushSubscription))).scalars().all()
-
-        return {
-            "version": 2,
-            "scope": "full",
-            "exported_at": datetime.now(timezone.utc).isoformat(),
-            "_security_notice": (
-                "This backup contains hashed passwords and push subscription keys. "
-                "Store it securely and restrict access."
-            ),
-            "users": [
-                {
-                    "id": u.id,
-                    "username": u.username,
-                    "email": u.email,
-                    "password_hash": u.password_hash,
-                    "oauth_sub": u.oauth_sub,
-                    "role": u.role,
-                    "session_version": u.session_version,
-                    "created_at": u.created_at.isoformat(),
-                }
-                for u in users
-            ],
-            "projects": [
-                {
-                    "id": p.id,
-                    "user_id": p.user_id,
-                    "title": p.title,
-                    "description": p.description,
-                    "goal": p.goal,
-                    "status": p.status,
-                    "color": p.color,
-                    "created_at": p.created_at.isoformat(),
-                    "updated_at": p.updated_at.isoformat(),
-                }
-                for p in projects
-            ],
-            "milestones": [
-                {
-                    "id": m.id,
-                    "user_id": m.user_id,
-                    "project_id": m.project_id,
-                    "title": m.title,
-                    "description": m.description,
-                    "status": m.status,
-                    "order_index": m.order_index,
-                    "created_at": m.created_at.isoformat(),
-                    "updated_at": m.updated_at.isoformat(),
-                }
-                for m in milestones
-            ],
-            "notes": [
-                {
-                    "id": n.id,
-                    "user_id": n.user_id,
-                    "title": n.title,
-                    "body": n.body,
-                    "tags": n.tags or [],
-                    "parent_id": n.parent_id,
-                    "project_id": n.project_id,
-                    "milestone_id": n.milestone_id,
-                    "is_task": n.is_task,
-                    "status": n.status,
-                    "priority": n.priority,
-                    "due_date": n.due_date.isoformat() if n.due_date else None,
-                    "is_starred": getattr(n, "is_starred", False),
-                    "is_pinned": getattr(n, "is_pinned", False),
-                    "created_at": n.created_at.isoformat(),
-                    "updated_at": n.updated_at.isoformat(),
-                }
-                for n in notes
-            ],
-            "task_logs": [
-                {
-                    "id": tl.id,
-                    "user_id": tl.user_id,
-                    "note_id": tl.note_id,
-                    "description": tl.description,
-                    "duration_minutes": tl.duration_minutes,
-                    "logged_at": tl.logged_at.isoformat() if tl.logged_at else None,
-                    "created_at": tl.created_at.isoformat(),
-                }
-                for tl in task_logs
-            ],
-            "note_drafts": [
-                {
-                    "id": nd.id,
-                    "user_id": nd.user_id,
-                    "note_id": nd.note_id,
-                    "title": nd.title,
-                    "body": nd.body,
-                    "saved_at": nd.saved_at.isoformat() if nd.saved_at else None,
-                }
-                for nd in note_drafts
-            ],
-            "note_versions": [
-                {
-                    "id": nv.id,
-                    "user_id": nv.user_id,
-                    "note_id": nv.note_id,
-                    "title": nv.title,
-                    "body": nv.body,
-                    "version_number": nv.version_number,
-                    "created_at": nv.created_at.isoformat(),
-                }
-                for nv in note_versions
-            ],
-            "conversations": [
-                {
-                    "id": c.id,
-                    "user_id": c.user_id,
-                    "title": c.title,
-                    "created_at": c.created_at.isoformat(),
-                    "updated_at": c.updated_at.isoformat(),
-                    "messages": [
-                        {
-                            "id": m.id,
-                            "role": m.role,
-                            "content": m.content,
-                            "context_note_id": m.context_note_id,
-                            "created_at": m.created_at.isoformat(),
-                        }
-                        for m in c.messages
-                    ],
-                }
-                for c in conversations
-            ],
-            "settings": [
-                {"user_id": s.user_id, "key": s.key, "value": s.value}
-                for s in settings
-            ],
-            "push_subscriptions": [
-                {
-                    "user_id": ps.user_id,
-                    "endpoint": ps.endpoint,
-                    "p256dh": ps.p256dh,
-                    "auth": ps.auth,
-                    "created_at": ps.created_at.isoformat(),
-                }
-                for ps in push_subs
-            ],
-        }
-```
-
-Check what exact field names exist on each model before assuming. Use `getattr(obj, "field", default)` for fields that may not exist on older DB versions.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/fabledassistant/services/backup.py
-git commit -m "feat(backup): v2 full export with projects, milestones, task_logs, drafts, versions"
-```
-
----
-
-## Task 2: Extend export — user backup
-
-**Files:**
-- Modify: `src/fabledassistant/services/backup.py`
-
-- [ ] **Step 1: Rewrite `export_user_backup(user_id)`**
-
-Same structure as full backup but filtered to `WHERE user_id = uid`. Apply same field additions. Omit sensitive fields (password_hash, oauth_sub) from user self-export.
-
-```python
-async def export_user_backup(user_id: int) -> dict:
-    async with async_session() as session:
-        user = await session.get(User, user_id)
-        projects = (await session.execute(select(Project).where(Project.user_id == user_id))).scalars().all()
-        milestones = (await session.execute(select(Milestone).where(Milestone.user_id == user_id))).scalars().all()
-        notes = (await session.execute(select(Note).where(Note.user_id == user_id))).scalars().all()
-        task_logs = (await session.execute(select(TaskLog).where(TaskLog.user_id == user_id))).scalars().all()
-        note_drafts = (await session.execute(select(NoteDraft).where(NoteDraft.user_id == user_id))).scalars().all()
-        note_versions = (await session.execute(
-            select(NoteVersion).where(NoteVersion.user_id == user_id)
-            .order_by(NoteVersion.note_id, NoteVersion.version_number)
-        )).scalars().all()
-        conversations = (await session.execute(
-            select(Conversation).options(selectinload(Conversation.messages))
-            .where(Conversation.user_id == user_id)
-        )).scalars().all()
-        settings = (await session.execute(select(Setting).where(Setting.user_id == user_id))).scalars().all()
-
-        return {
-            "version": 2,
-            "scope": "user",
-            "exported_at": datetime.now(timezone.utc).isoformat(),
-            "user": {
-                "id": user.id,
-                "username": user.username,
-                "email": user.email,
-                "role": user.role,
-                "created_at": user.created_at.isoformat(),
-            } if user else None,
-            "projects": [...],   # same as full but user-filtered
-            "milestones": [...],
-            "notes": [...],
-            "task_logs": [...],
-            "note_drafts": [...],
-            "note_versions": [...],
-            "conversations": [...],
-            "settings": [...],
-        }
-```
-
-- [ ] **Step 2: Commit**
-
-```bash
-git add src/fabledassistant/services/backup.py
-git commit -m "feat(backup): v2 user backup with all models"
-```
-
----
-
-## Task 3: Rewrite restore for v2
-
-**Files:**
-- Modify: `src/fabledassistant/services/backup.py`
-
-- [ ] **Step 1: Add version dispatch to `restore_full_backup`**
-
-```python
-async def restore_full_backup(data: dict) -> dict:
-    version = data.get("version", 1)
-    if version == 1:
-        return await _restore_v1(data)
-    return await _restore_v2(data)
-```
-
-Move existing restore code into `_restore_v1(data)` with no changes.
-
-- [ ] **Step 2: Implement `_restore_v2(data)` with full FK re-mapping**
-
-Restore order (respects FK dependencies):
-1. Users → build `user_id_map`
-2. Projects (fk: user_id) → build `project_id_map`
-3. Milestones (fk: user_id, project_id) → build `milestone_id_map`
-4. Notes — first pass: insert without `parent_id` (fk: user_id, project_id, milestone_id) → build `note_id_map`
-5. Notes — second pass: patch `parent_id` using `note_id_map`
-6. TaskLogs (fk: user_id, note_id via note_id_map)
-7. NoteDrafts (fk: user_id, note_id via note_id_map)
-8. NoteVersions (fk: user_id, note_id via note_id_map) — export only, no restore by default (skip unless flag set)
-9. Conversations (fk: user_id) → Messages (fk: conversation_id, context_note_id via note_id_map)
-10. Settings (fk: user_id)
-
-```python
-async def _restore_v2(data: dict) -> dict:
-    from datetime import date, datetime, timezone
-
-    stats = {
-        "users": 0, "projects": 0, "milestones": 0, "notes": 0,
-        "task_logs": 0, "note_drafts": 0, "conversations": 0,
-        "messages": 0, "settings": 0
-    }
-
-    async with async_session() as session:
-        user_id_map: dict[int, int] = {}
-        project_id_map: dict[int, int] = {}
-        milestone_id_map: dict[int, int] = {}
-        note_id_map: dict[int, int] = {}
-
-        # 1. Users
-        for u_data in data.get("users", []):
-            old_id = u_data["id"]
-            user = User(
-                username=u_data["username"],
-                email=u_data.get("email"),
-                password_hash=u_data.get("password_hash"),
-                oauth_sub=u_data.get("oauth_sub"),
-                role=u_data.get("role", "user"),
-                session_version=u_data.get("session_version", 1),
-                created_at=datetime.fromisoformat(u_data["created_at"]) if u_data.get("created_at") else datetime.now(timezone.utc),
-            )
-            session.add(user)
-            await session.flush()
-            user_id_map[old_id] = user.id
-            stats["users"] += 1
-
-        # 2. Projects
-        for p_data in data.get("projects", []):
-            mapped_uid = user_id_map.get(p_data.get("user_id", 0))
-            if mapped_uid is None:
-                continue
-            proj = Project(
-                user_id=mapped_uid,
-                title=p_data.get("title", ""),
-                description=p_data.get("description"),
-                goal=p_data.get("goal"),
-                status=p_data.get("status", "active"),
-                color=p_data.get("color"),
-                created_at=datetime.fromisoformat(p_data["created_at"]) if p_data.get("created_at") else datetime.now(timezone.utc),
-                updated_at=datetime.fromisoformat(p_data["updated_at"]) if p_data.get("updated_at") else datetime.now(timezone.utc),
-            )
-            session.add(proj)
-            await session.flush()
-            project_id_map[p_data["id"]] = proj.id
-            stats["projects"] += 1
-
-        # 3. Milestones
-        for m_data in data.get("milestones", []):
-            mapped_uid = user_id_map.get(m_data.get("user_id", 0))
-            mapped_pid = project_id_map.get(m_data.get("project_id", 0))
-            if mapped_uid is None:
-                continue
-            ms = Milestone(
-                user_id=mapped_uid,
-                project_id=mapped_pid,
-                title=m_data.get("title", ""),
-                description=m_data.get("description"),
-                status=m_data.get("status", "open"),
-                order_index=m_data.get("order_index", 0),
-                created_at=datetime.fromisoformat(m_data["created_at"]) if m_data.get("created_at") else datetime.now(timezone.utc),
-                updated_at=datetime.fromisoformat(m_data["updated_at"]) if m_data.get("updated_at") else datetime.now(timezone.utc),
-            )
-            session.add(ms)
-            await session.flush()
-            milestone_id_map[m_data["id"]] = ms.id
-            stats["milestones"] += 1
-
-        # 4. Notes — first pass (no parent_id)
-        note_objects: list[tuple[int, int]] = []  # (old_parent_id, new_note_id)
-        for n_data in data.get("notes", []):
-            mapped_uid = user_id_map.get(n_data.get("user_id", 0))
-            if mapped_uid is None:
-                continue
-            due = None
-            if n_data.get("due_date"):
-                due = date.fromisoformat(n_data["due_date"])
-            note = Note(
-                user_id=mapped_uid,
-                title=n_data.get("title", ""),
-                body=n_data.get("body", ""),
-                tags=n_data.get("tags", []),
-                parent_id=None,  # patched in second pass
-                project_id=project_id_map.get(n_data.get("project_id")) if n_data.get("project_id") else None,
-                milestone_id=milestone_id_map.get(n_data.get("milestone_id")) if n_data.get("milestone_id") else None,
-                is_task=n_data.get("is_task", False),
-                status=n_data.get("status"),
-                priority=n_data.get("priority"),
-                due_date=due,
-                created_at=datetime.fromisoformat(n_data["created_at"]) if n_data.get("created_at") else datetime.now(timezone.utc),
-                updated_at=datetime.fromisoformat(n_data["updated_at"]) if n_data.get("updated_at") else datetime.now(timezone.utc),
-            )
-            session.add(note)
-            await session.flush()
-            note_id_map[n_data["id"]] = note.id
-            if n_data.get("parent_id"):
-                note_objects.append((n_data["parent_id"], note.id))
-            stats["notes"] += 1
-
-        # 5. Notes — second pass: patch parent_id
-        for old_parent_id, new_note_id in note_objects:
-            new_parent_id = note_id_map.get(old_parent_id)
-            if new_parent_id:
-                note_row = await session.get(Note, new_note_id)
-                if note_row:
-                    note_row.parent_id = new_parent_id
-
-        # 6. TaskLogs
-        for tl_data in data.get("task_logs", []):
-            mapped_uid = user_id_map.get(tl_data.get("user_id", 0))
-            mapped_nid = note_id_map.get(tl_data.get("note_id", 0))
-            if mapped_uid is None or mapped_nid is None:
-                continue
-            from fabledassistant.models.task_log import TaskLog
-            tl = TaskLog(
-                user_id=mapped_uid,
-                note_id=mapped_nid,
-                description=tl_data.get("description", ""),
-                duration_minutes=tl_data.get("duration_minutes"),
-                logged_at=datetime.fromisoformat(tl_data["logged_at"]) if tl_data.get("logged_at") else None,
-                created_at=datetime.fromisoformat(tl_data["created_at"]) if tl_data.get("created_at") else datetime.now(timezone.utc),
-            )
-            session.add(tl)
-            stats["task_logs"] += 1
-
-        # 7. NoteDrafts
-        for nd_data in data.get("note_drafts", []):
-            mapped_uid = user_id_map.get(nd_data.get("user_id", 0))
-            mapped_nid = note_id_map.get(nd_data.get("note_id", 0))
-            if mapped_uid is None or mapped_nid is None:
-                continue
-            from fabledassistant.models.note_draft import NoteDraft
-            nd = NoteDraft(
-                user_id=mapped_uid,
-                note_id=mapped_nid,
-                title=nd_data.get("title", ""),
-                body=nd_data.get("body", ""),
-                saved_at=datetime.fromisoformat(nd_data["saved_at"]) if nd_data.get("saved_at") else None,
-            )
-            session.add(nd)
-            stats["note_drafts"] += 1
-
-        # 8. Conversations + Messages
-        for c_data in data.get("conversations", []):
-            mapped_uid = user_id_map.get(c_data.get("user_id", 0))
-            if mapped_uid is None:
-                continue
-            conv = Conversation(
-                user_id=mapped_uid,
-                title=c_data.get("title", ""),
-                created_at=datetime.fromisoformat(c_data["created_at"]) if c_data.get("created_at") else datetime.now(timezone.utc),
-                updated_at=datetime.fromisoformat(c_data["updated_at"]) if c_data.get("updated_at") else datetime.now(timezone.utc),
-            )
-            session.add(conv)
-            await session.flush()
-            stats["conversations"] += 1
-            for m_data in c_data.get("messages", []):
-                msg = Message(
-                    conversation_id=conv.id,
-                    role=m_data["role"],
-                    content=m_data.get("content", ""),
-                    context_note_id=note_id_map.get(m_data["context_note_id"]) if m_data.get("context_note_id") else None,
-                    created_at=datetime.fromisoformat(m_data["created_at"]) if m_data.get("created_at") else datetime.now(timezone.utc),
-                )
-                session.add(msg)
-                stats["messages"] += 1
-
-        # 9. Settings
-        for s_data in data.get("settings", []):
-            mapped_uid = user_id_map.get(s_data.get("user_id", 0))
-            if mapped_uid is None:
-                continue
-            setting = Setting(user_id=mapped_uid, key=s_data["key"], value=s_data.get("value", ""))
-            session.add(setting)
-            stats["settings"] += 1
-
-        await session.commit()
-
-    logger.info("Restored v2 backup: %s", stats)
-    return stats
-```
-
-- [ ] **Step 3: Add missing imports at top of file**
-
-```python
-from datetime import datetime, timezone
-from fabledassistant.models.project import Project
-from fabledassistant.models.milestone import Milestone
-```
-
-- [ ] **Step 4: Test restore round-trip**
-
-```bash
-# Export
-curl -s -b cookies.txt "http://localhost:5000/api/admin/backup?scope=full" -o /tmp/backup_v2.json
-# Inspect structure
-python3 -c "import json; d=json.load(open('/tmp/backup_v2.json')); print(list(d.keys()))"
-# Expected keys: version, scope, exported_at, users, projects, milestones, notes, task_logs, ...
-```
-
-- [ ] **Step 5: Typecheck**
-
-```bash
-docker compose exec app python -m py_compile src/fabledassistant/services/backup.py
-```
-Expected: No errors.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/fabledassistant/services/backup.py
-git commit -m "feat(backup): v2 restore with full FK re-mapping; v1 restore preserved"
-```
-
----
-
-## Task 4: Verification
-
-- [ ] **Step 1: Full round-trip test**
-
-1. Export full backup as admin
-2. Verify JSON has `"version": 2` and all expected top-level keys
-3. Verify notes have `project_id`, `milestone_id`, `is_task` fields
-4. Verify `task_logs` array has entries (create a task log entry first if needed)
-5. Restore backup to a clean test instance (or verify restore code path runs without error in dry-run)
-
-- [ ] **Step 2: V1 backward compat test**
-
-Take an old v1 backup JSON (or construct one without the `version` key) and run restore. Verify it takes the v1 path and doesn't error.
-
-- [ ] **Step 3: Commit final verification note**
-
-```bash
-git commit --allow-empty -m "chore(backup): v2 backup rewrite verified"
-```

docs/specs/2026-03-25-briefing-improvements-design.md

@@ -1,285 +0,0 @@
-# Briefing Service Improvements — Design Spec
-
-**Date:** 2026-03-25
-**Status:** Approved
-**Scope:** Web-first (no Android changes in this cycle)
-
----
-
-## Problem Statement
-
-The daily briefing has several usability issues:
-
-1. **Task repetition** — tasks are restated identically every day regardless of whether anything changed, making the briefing feel stale and hard to scan.
-2. **RSS repetition** — the same news stories resurface across days with no mechanism to learn what the user cares about.
-3. **No path to sources** — news items are summarised in prose with no link to the original article.
-4. **Stale weather** — if the weather cache is outdated, the briefing silently uses old data rather than failing gracefully. The current prose weather format is also hard to scan.
-5. **No feedback loop** — there is no way to teach the briefing what topics are interesting or uninteresting.
-
----
-
-## Approach
-
-**Pre-processing pipeline with explicit state tracking.** Rather than relying on the synthesis LLM to handle deduplication and filtering, we add deterministic pre-processing steps before synthesis runs. Each concern is isolated: task change detection, RSS topic classification and filtering, weather staleness gating. The synthesis LLM receives pre-filtered, structured input and focuses on tone and flow.
-
----
-
-## Data Model
-
-### Migration: `0028_add_briefing_improvements`
-
-**`rss_items` table — two new columns**
-
-```sql
-ALTER TABLE rss_items ADD COLUMN IF NOT EXISTS topics TEXT[] DEFAULT '{}';
-ALTER TABLE rss_items ADD COLUMN IF NOT EXISTS classified_at TIMESTAMPTZ;
-```
-
-`topics` stores LLM-assigned topic tags (e.g. `["technology", "ai"]`). `classified_at` is NULL until classification runs, allowing backfill queries. The `RssFeed` / `RssItem` SQLAlchemy model (`models/rss_feed.py`) must also be updated to add these two mapped columns and expose them in `to_dict()`.
-
-**`messages` table — new metadata column**
-
-```sql
-ALTER TABLE messages ADD COLUMN IF NOT EXISTS metadata JSONB;
-```
-
-The briefing pipeline populates this when it creates the compiled message. The frontend reads it when loading the conversation to render the `WeatherCard` and attach reaction buttons. No SSE events are needed — structured data travels with the message record.
-
-Schema stored in `metadata`:
-```json
-{
-  "weather": {
-    "location": "Berlin",
-    "fetched_at": "2026-03-25T06:00:00Z",
-    "current_temp": 12,
-    "condition": "Partly Cloudy",
-    "today_high": 16,
-    "today_low": 8,
-    "yesterday_high": 14,
-    "yesterday_low": 9,
-    "forecast": [
-      {"day": "Wed", "condition": "Sunny", "high": 18, "low": 10},
-      {"day": "Thu", "condition": "Cloudy", "high": 14, "low": 9}
-    ]
-  },
-  "rss_item_ids": [42, 17, 89, 103, 55]
-}
-```
-
-If weather is unavailable, `metadata.weather` is `null` and the card renders a failure placeholder. The `Message` SQLAlchemy model (`models/conversation.py`) must be updated to add the `metadata` mapped column.
-
-**New table: `rss_item_reactions`**
-
-```sql
-CREATE TABLE IF NOT EXISTS rss_item_reactions (
-    id          SERIAL PRIMARY KEY,
-    user_id     INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    rss_item_id INTEGER NOT NULL REFERENCES rss_items(id) ON DELETE CASCADE,
-    reaction    TEXT NOT NULL CHECK (reaction IN ('up', 'down')),
-    created_at  TIMESTAMPTZ DEFAULT NOW(),
-    UNIQUE (user_id, rss_item_id)
-);
-CREATE INDEX IF NOT EXISTS ix_rss_item_reactions_user_id ON rss_item_reactions(user_id);
-```
-
-One reaction per user per item. A second click on the same button removes the reaction; clicking the opposite button flips it.
-
-**New table: `briefing_task_snapshot`**
-
-```sql
-CREATE TABLE IF NOT EXISTS briefing_task_snapshot (
-    id            SERIAL PRIMARY KEY,
-    user_id       INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-    task_id       INTEGER NOT NULL REFERENCES notes(id) ON DELETE CASCADE,
-    snapshot_hash TEXT NOT NULL,
-    last_briefed  TIMESTAMPTZ DEFAULT NOW(),
-    UNIQUE (user_id, task_id)
-);
-CREATE INDEX IF NOT EXISTS ix_briefing_task_snapshot_user_id ON briefing_task_snapshot(user_id);
-```
-
-`snapshot_hash` is `SHA-256(status + priority + due_date + title)`. The pipeline diffs current task state against these rows to detect what has changed since the last briefing.
-
-**Settings keys (existing key-value store — no new table)**
-
-- `briefing_include_topics` — JSON array of topic strings to prioritise
-- `briefing_exclude_topics` — JSON array of topics to hard-exclude from briefings
-
----
-
-## Pipeline Changes
-
-### Pre-processing Stage (new, runs before parallel gather)
-
-Three sequential steps added to `services/briefing_pipeline.py`. Note: `_gather_internal` currently serialises tasks as dicts without `id`. It must be updated to include `task_id` in each serialised task dict (the `Note` ORM object has `.id` available) so the post-briefing snapshot upsert has the required FK value.
-
-**1. Task change detection**
-
-For each of the user's current tasks, compute `SHA-256(status + priority + due_date + title)` and compare against `briefing_task_snapshot`. Split into:
-- `changed_tasks` — new hash or no snapshot row (included fully in briefing)
-- `unchanged_count` — integer count passed to the synthesis prompt as context
-
-The synthesis prompt receives `changed_tasks` and the instruction: "N tasks are unchanged since the last briefing — acknowledge this briefly rather than listing them."
-
-**2. RSS item filtering**
-
-Load the user's `briefing_include_topics` and `briefing_exclude_topics` settings, plus reaction history (last 30 days, aggregated per topic as a net score). Score each recent classified item:
-- Hard-remove items tagged with any excluded topic
-- Boost items tagged with any included or positively-reacted topic
-- Penalise items from negatively-reacted topics
-- Sort by score, take top 10
-
-Items with `classified_at IS NULL` pass through unfiltered (new feeds not yet classified) and are queued for background classification.
-
-**3. Weather staleness gate**
-
-Check `weather_cache.fetched_at`. If older than 24 hours: skip weather entirely, set `weather_unavailable = True`. The frontend renders a `WeatherCard` placeholder in the failure state. If fresh: pass the forecast JSON (including `past_days=1` data) to the pipeline for card rendering.
-
-### RSS Classification (background, triggered at fetch time)
-
-When `services/rss.py` stores new items, it queues a fire-and-forget async task to classify them. Classification is a fast, non-streaming LLM call processing batches of up to 10 items:
-
-```
-Classify each news item into 1-3 topics from this vocabulary:
-technology, science, politics, business, health, environment,
-local, entertainment, sports, other, [user_defined_topics]
-Return JSON: {"item_id": ["topic1", "topic2"]}
-```
-
-The vocabulary is extended with the user's declared preference topics so custom interests can be matched. Results are written to `rss_items.topics` and `classified_at`.
-
-Model: the user's `default_model` setting (same as chat). If the LLM is unavailable or classification fails, the item is stored with `topics = []` and `classified_at` left NULL — it will be retried the next time new items are fetched. No retry loop; classification is best-effort.
-
-### Post-briefing Stage (new, runs after `post_message()` returns)
-
-1. **Upsert task snapshots** — upsert `briefing_task_snapshot` rows for all tasks included in this briefing so the next run can diff against current state.
-2. **Populate message metadata** — the `metadata` dict (`weather` + `rss_item_ids`) is assembled during pre-processing and passed through to `post_message()`, which writes it to the `Message.metadata` column. No separate post-step is needed — the metadata is stored atomically with the message.
-
----
-
-## Weather Card
-
-The weather section is no longer generated as prose by the synthesis LLM. Instead:
-
-- `services/weather.py` is updated to request `past_days=1` from Open-Meteo, including yesterday's high/low in the same API response.
-- The pipeline parses the forecast into the `metadata.weather` schema (defined in the Data Model section) and stores it on the `Message` record when `post_message()` is called.
-- `BriefingView.vue` reads `message.metadata.weather` when loading the conversation and renders `WeatherCard.vue` above the message text if the field is present.
-- The synthesis LLM's weather section is suppressed entirely — the prompt instructs it to skip weather since it is handled by the card.
-
-**`WeatherCard.vue` displays:**
-- Location name and "as of" timestamp
-- Current temperature and condition
-- Today's high / low
-- Yesterday's high / low with delta ("3° warmer than yesterday")
-- Compact 3–5 day forecast strip (day name, condition, high/low)
-
-**Failure state:** If `metadata.weather` is `null`, the same card position renders a muted placeholder: "Weather data unavailable — will retry at next slot."
-
----
-
-## News Cards
-
-### Format
-
-The synthesis LLM is instructed to format each included news item as:
-
-```markdown
-**[Headline text](source_url)**
-*Outlet Name · Day Month*
-One or two sentence summary of the story.
-```
-
-No prose wrapper between cards. The synthesis prompt must explicitly instruct the LLM to **present news items in the exact order provided** — `metadata.rss_item_ids` records this order and the frontend maps reaction buttons positionally. Reordering by the LLM would break the mapping.
-
-The briefing message structure becomes:
-1. Greeting / task summary
-2. `WeatherCard` (rendered from `message.metadata.weather`, not prose)
-3. News cards (markdown blocks with links)
-4. Calendar / other sections
-
-### Reaction Buttons
-
-`BriefingView.vue` reads `message.metadata.rss_item_ids` when loading the conversation. The ordered list of IDs maps directly to the news cards in the rendered message (cards appear in synthesis output in the same order). A 👍 / 👎 pair is rendered below each card. Reaction buttons are only shown in the briefing view — not in message history exports.
-
-Clicking a reaction:
-1. Optimistic UI update (button enters selected state immediately)
-2. `POST /api/briefing/rss-reactions` — `{rss_item_id, reaction}`
-3. Backend validates ownership: joins through `rss_items → rss_feeds` to confirm `rss_feeds.user_id = g.user.id` before upserting
-4. Upserts into `rss_item_reactions` — same reaction removes it, opposite flips it
-
-**New endpoints in `routes/briefing.py`:**
-- `POST /api/briefing/rss-reactions` — upsert or remove reaction (ownership-checked)
-- `DELETE /api/briefing/rss-reactions/:item_id` — explicit removal (useful for MCP/external API consumers that cannot use the toggle behaviour of POST)
-
----
-
-## Topic Preferences UI
-
-**Settings → Briefing tab — new "News Preferences" subsection** (added below existing RSS feed management):
-
-Two chip-input fields using the existing `TagInput.vue` component:
-- **Interested in** → `briefing_include_topics` setting
-- **Not interested in** → `briefing_exclude_topics` setting
-
-A collapsed hint lists the standard topic vocabulary so users know valid terms. Custom terms are accepted — the RSS classifier will attempt to match them.
-
-Saved via the existing `PUT /api/settings/:key` endpoint.
-
----
-
-## MCP Tool Additions
-
-New file: `fable-mcp/fable_mcp/tools/briefing.py`
-
-Three tools registered in `server.py`:
-
-| Tool | Description |
-|------|-------------|
-| `add_rss_feed(url, title=None, category=None)` | Adds a feed to the user's RSS list. `title` is optional — the feed title is auto-populated from feed metadata after the first fetch, but an override can be passed. Returns the created feed object. |
-| `list_rss_feeds()` | Returns current feed list with id, title, url, category, last_fetched_at. |
-| `remove_rss_feed(feed_id)` | Removes a feed by ID. |
-
-These call existing RSS endpoints in `routes/briefing.py` via `FableClient`. No new backend routes required.
-
----
-
-## New Backend Files
-
-| File | Purpose |
-|------|---------|
-| `services/briefing_preferences.py` | Load/compute topic preference weights; apply to RSS item scoring |
-| `services/rss_classifier.py` | Batch LLM classification of RSS items; background task management |
-
-## Modified Backend Files
-
-| File | Changes |
-|------|---------|
-| `services/briefing_pipeline.py` | Add pre-processing and post-briefing stages; carry `task_id` through serialised task dicts; pass `metadata` dict to `post_message()` |
-| `services/rss.py` | Trigger background classification after storing new items |
-| `services/weather.py` | Add `past_days=1` to Open-Meteo request; expose parsed yesterday data |
-| `routes/briefing.py` | Add `POST/DELETE /api/briefing/rss-reactions` endpoints |
-| `models/rss_feed.py` | Add `topics` and `classified_at` mapped columns to `RssItem`; expose in `to_dict()` |
-| `models/conversation.py` | Add `metadata` JSONB mapped column to `Message`; update `to_dict()` to include `metadata` in the returned dict |
-| `services/briefing_conversations.py` | Extend `post_message(conversation_id, role, content)` signature to accept an optional `metadata: dict \| None = None` parameter; pass it to the `Message(...)` constructor |
-
-## New Frontend Files
-
-| File | Purpose |
-|------|---------|
-| `components/WeatherCard.vue` | Weather display card (current, today, yesterday delta, 3-5 day strip, failure state) |
-
-## Modified Frontend Files
-
-| File | Changes |
-|------|---------|
-| `views/BriefingView.vue` | Read `message.metadata.weather` on conversation load → render `WeatherCard.vue` above message text; read `message.metadata.rss_item_ids` → attach reaction buttons to news cards in order |
-| `views/SettingsView.vue` | Add "News Preferences" subsection with two `TagInput` fields |
-| `api/client.ts` | Add `postRssReaction()`, `deleteRssReaction()` helpers |
-
----
-
-## Out of Scope
-
-- Android companion app changes (web-first; parity deferred)
-- Full numeric scoring system (Approach C) — can evolve to this once reaction data accumulates
-- Push notification integration for briefing reactions

docs/specs/2026-03-25-internal-calendar-design.md

@@ -1,214 +0,0 @@
-# Internal Calendar with CalDAV Sync — Design Spec
-
-## Goal
-
-Add an internal event store to Fable's database, a full calendar UI (month/week grid), and a best-effort push sync to the user's existing external CalDAV server. Fable becomes the source of truth for events; CalDAV is an optional downstream target.
-
-## Background
-
-The existing `services/caldav.py` lets the AI assistant create, update, and delete events directly on an external CalDAV server (Nextcloud, etc.) via tool calls. There is no calendar UI and no internal event storage — all reads go to CalDAV at query time. The `events` DB table and `models/event.py` exist as dead code from an abandoned Radicale integration (created in migration `0019_add_events`); the table exists in the database but all columns are empty.
-
-This design revives the internal event store, adds a REST API and calendar view, and re-wires the AI tools to write through the internal DB so all events are accessible regardless of CalDAV availability.
-
----
-
-## Architecture
-
-### Source of Truth
-
-Fable's `events` DB table is the single source of truth. CalDAV sync is a best-effort push: after every create, update, or delete, a background task attempts to mirror the change to the user's configured CalDAV server. If CalDAV is unconfigured or unreachable, the operation still succeeds and the event remains in Fable.
-
-### Timezone Handling
-
-- **Storage:** `start_dt` / `end_dt` stored as UTC (`TIMESTAMPTZ`).
-- **Display:** FullCalendar configured with `timeZone: 'local'` — renders in the browser's IANA timezone automatically.
-- **Input:** Frontend datetime inputs are in local time; converted to a timezone-aware ISO string (with UTC offset) before the API call. Backend parses to UTC.
-- **CalDAV push:** Uses the user's `caldav_timezone` setting for iCal `DTSTART`/`DTEND`, consistent with existing behaviour.
-- **AI tools:** The LLM receives the user's timezone in the system prompt and sends timezone-aware strings, as today.
-
----
-
-## Data Model
-
-### `events` table (existing since migration 0019, extend via migration 0029)
-
-| Column | Type | Notes |
-|--------|------|-------|
-| `id` | `SERIAL PK` | |
-| `user_id` | `INT FK users CASCADE` | |
-| `project_id` | `INT FK projects SET NULL` nullable | Optional link to a Fable project |
-| `uid` | `TEXT` | iCal UID — UUID generated on `create_event`, embedded in CalDAV push |
-| `caldav_uid` | `TEXT DEFAULT ''` | **New.** Same value as `uid` after a successful CalDAV push (confirms sync); empty if never synced |
-| `title` | `TEXT` | |
-| `start_dt` | `TIMESTAMPTZ` | UTC |
-| `end_dt` | `TIMESTAMPTZ` nullable | UTC; null for open-ended events |
-| `all_day` | `BOOLEAN DEFAULT false` | When true, time component is ignored in display |
-| `description` | `TEXT DEFAULT ''` | |
-| `location` | `TEXT DEFAULT ''` | |
-| `color` | `TEXT DEFAULT ''` | **New.** Hex colour for calendar display (e.g. `#6366f1`) |
-| `recurrence` | `TEXT` nullable | iCal RRULE string — stored and forwarded to CalDAV; not exposed in the UI slide-over |
-| `created_at` | `TIMESTAMPTZ` | |
-| `updated_at` | `TIMESTAMPTZ` | |
-
-**Migration `0029_add_calendar_columns`:** `ALTER TABLE events ADD COLUMN IF NOT EXISTS caldav_uid TEXT DEFAULT ''` and `ADD COLUMN IF NOT EXISTS color TEXT DEFAULT ''`. Raw SQL with `IF NOT EXISTS` guards (table already exists from migration 0019).
-
-**`models/event.py`:** Add two `mapped_column` declarations to the `Event` class:
-```python
-caldav_uid: Mapped[str] = mapped_column(Text, default="")
-color: Mapped[str] = mapped_column(Text, default="")
-```
-Update `to_dict()` to include `"caldav_uid": self.caldav_uid` and `"color": self.color`.
-
----
-
-## Service Layer
-
-**`src/fabledassistant/services/events.py`** — owns all event CRUD and CalDAV push coordination.
-
-### Public functions
-
-```
-create_event(user_id, title, start_dt, end_dt, all_day, description, location,
-             color, recurrence, project_id,
-             duration, reminder_minutes, attendees, calendar_name) → Event
-get_event(user_id, event_id) → Event
-list_events(user_id, date_from, date_to) → list[Event]
-search_events(user_id, query, days_ahead=90) → list[Event]
-update_event(user_id, event_id, **fields) → Event
-delete_event(user_id, event_id) → None
-find_events_by_query(user_id, query) → list[Event]
-```
-
-`duration`, `reminder_minutes`, `attendees`, and `calendar_name` are accepted by `create_event` for forwarding to CalDAV (they are not stored in the DB). `find_events_by_query` does a case-insensitive `ILIKE` search on `title` and is used by the AI `update_event` / `delete_event` tools.
-
-### CalDAV push — UID strategy
-
-`create_event` generates a UUID and stores it as the event's `uid`. This same UUID must be embedded as the iCal `UID` field when pushing to CalDAV. To enable this, `services/caldav.py`'s `create_event` function is **minimally modified** to accept an optional `uid: str | None = None` parameter; when provided, `event.add("uid", uid)` is called before `cal.add_component(event)`. All other CalDAV functions are unchanged.
-
-On a successful push, `caldav_uid` is set to the same UUID value in the DB (confirming sync). This means `caldav_uid` is Fable's own UID confirmed-as-pushed, not a server-assigned value — which is fine since we generated it.
-
-After every write to the DB:
-
-- `create_event` → `asyncio.create_task(_push_create(event, user_id, extra_fields))`
-- `update_event` → `asyncio.create_task(_push_update(event, user_id))`
-- `delete_event` → `asyncio.create_task(_push_delete(caldav_uid, user_id))` if `caldav_uid` is set
-
-Each push function calls the relevant function in `services/caldav.py`, marks `caldav_uid` on success, and logs a warning on failure. CalDAV being unconfigured is treated as a no-op (not an error).
-
-### Match policy for AI update/delete tools
-
-`find_events_by_query` returns all events where `title ILIKE '%query%'`. The calling tool applies the same match-count policy as the existing CalDAV tools: zero matches → raise `ValueError("No event found matching '…'.")`; more than 3 matches → raise `ValueError("Too many matches (N) for '…'. Be more specific. Found: …")`. One or two matches use the first result.
-
----
-
-## REST API
-
-**`src/fabledassistant/routes/events.py`** — new blueprint, registered in `app.py`.
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/api/events?from=&to=` | List events in ISO datetime range |
-| `POST` | `/api/events` | Create event |
-| `GET` | `/api/events/:id` | Get single event |
-| `PATCH` | `/api/events/:id` | Partial update |
-| `DELETE` | `/api/events/:id` | Delete event |
-
-All routes require `@login_required`. Ownership enforced in the service layer (404 if event not owned by requesting user).
-
----
-
-## AI Tool Rewiring
-
-Calendar tools in `services/tools.py` are updated to call `services/events.py` instead of `services/caldav.py` directly. The `is_caldav_configured` gate that currently hides these tools is **removed** — calendar tools are always available since the internal DB is always present. The tool definitions currently grouped under `_CALDAV_TOOLS` (appended to the tools list only when `is_caldav_configured` is true) must be moved into the unconditional `_CORE_TOOLS` list (or equivalent always-included list). The tool parameter names and LLM-facing descriptions do not change.
-
-| Tool | Change |
-|------|--------|
-| `create_event` | Calls `events.create_event(...)` — all existing params forwarded |
-| `list_events` | Calls `events.list_events(...)` |
-| `search_events` | Calls `events.search_events(...)` |
-| `update_event` | Calls `events.find_events_by_query(...)`, then `events.update_event(...)` |
-| `delete_event` | Calls `events.find_events_by_query(...)`, then `events.delete_event(...)` |
-
----
-
-## Frontend
-
-### Dependencies
-
-```
-@fullcalendar/vue3
-@fullcalendar/daygrid      # month view
-@fullcalendar/timegrid     # week / day view
-@fullcalendar/interaction  # drag-to-move, resize, click-to-create
-```
-
-All MIT licensed.
-
-### Components
-
-**`frontend/src/views/CalendarView.vue`** — main view at `/calendar`:
-- FullCalendar instance with `timeZone: 'local'`, `initialView: 'dayGridMonth'`, header toolbar toggling between month and week
-- Loads events for the visible date range via `GET /api/events?from=&to=`
-- Re-fetches when the visible range changes
-- Click on empty date cell → opens `EventSlideOver` in create mode, pre-filled with the clicked date
-- Click on existing event → opens `EventSlideOver` in edit mode
-- Drag event to new date/time → `PATCH /api/events/:id` with updated times (optimistic update, revert on error)
-- Resize event → same
-
-**`frontend/src/components/EventSlideOver.vue`** — reusable slide-over panel (same pattern as the workspace task slide-over):
-- Fields: title (required), start date/time, end date/time, all-day toggle, location, description, colour picker, optional project selector
-- `recurrence` is **not** a form field — it is stored and pushed to CalDAV via AI tools only
-- Create mode: `POST /api/events`
-- Edit mode: `PATCH /api/events/:id` + delete button (`DELETE /api/events/:id`)
-- Closes on save, cancel, or Escape
-
-**`frontend/src/api/client.ts`** — add typed helpers and `EventEntry` / `CreateEventBody` interfaces:
-
-```typescript
-interface EventEntry {
-  id: number; uid: string; title: string;
-  start_dt: string; end_dt: string | null;
-  all_day: boolean; description: string; location: string;
-  color: string; recurrence: string | null;
-  project_id: number | null; caldav_uid: string;
-  created_at: string; updated_at: string;
-}
-
-listEvents(from: string, to: string): Promise<EventEntry[]>
-createEvent(body: CreateEventBody): Promise<EventEntry>
-getEvent(id: number): Promise<EventEntry>
-updateEvent(id: number, body: Partial<CreateEventBody>): Promise<EventEntry>
-deleteEvent(id: number): Promise<void>
-```
-
-### Navigation
-
-- `/calendar` added to Vue Router
-- Sidebar nav item added
-- Keyboard shortcut: `g` + `l` (ca**l**endar) — `c` is already taken by chat
-
----
-
-## Error Handling
-
-- CalDAV push failures are logged at `WARNING` level and do not surface to the user
-- If CalDAV is unconfigured, push is skipped silently
-- Drag-to-move/resize failures (PATCH error) revert the event to its previous position in FullCalendar's UI via the `revert` callback
-- 404 returned for event access by non-owner
-
----
-
-## Testing
-
-- `tests/test_events_service.py` — unit tests for `create_event`, `list_events`, `search_events`, `update_event`, `delete_event`, `find_events_by_query` with mocked DB session; separate test verifying CalDAV push background task is fired
-- `tests/test_events_routes.py` — route tests for all five endpoints verifying ownership enforcement and correct status codes
-- TypeScript check (`make typecheck`) after all frontend changes
-
----
-
-## Out of Scope
-
-- Pull sync (importing events from CalDAV into Fable) — possible future upgrade
-- Recurring event expansion in the UI (RRULE stored and forwarded to CalDAV via AI tools only)
-- Shared calendars / multi-user event invites
-- Event notifications / reminders in the Fable push system

docs/specs/2026-03-25-rag-scoping-design.md

@@ -1,236 +0,0 @@
-# RAG Scoping and Context Isolation Design
-
-> **For agentic workers:** Use superpowers:executing-plans or superpowers:subagent-driven-development to implement this plan task-by-task.
-
-**Goal:** Prevent project-associated notes from polluting global chat RAG, and give the LLM tools to discover and switch project scope during a conversation.
-
-**Problem being solved:** Users with multiple projects (e.g. scifi worldbuilding, personal productivity) find that semantic search pulls notes from whichever project has the most content, contaminating general-purpose chat context. Project notes should be siloed by default.
-
----
-
-## Architecture
-
-### Default RAG behavior change
-
-Currently `rag_project_id=None` in `build_context()` searches all notes. After this change the semantics become a three-value system:
-
-- `rag_project_id = None` → search only orphan notes (`project_id IS NULL`)
-- `rag_project_id = <positive int>` → search only that project's notes
-- `rag_project_id = -1` → search all notes (explicit opt-in to current global behavior)
-
-**`semantic_search_notes()` change** (`services/embeddings.py`): add `orphan_only: bool = False` parameter. When `True`, add `.where(Note.project_id.is_(None))` to the SQLAlchemy query.
-
-**`search_notes_for_context()` change** (`services/notes.py`): add `orphan_only: bool = False` parameter with the same filter.
-
-**`build_context()` change** (`services/llm.py`): compute the flags before calling search:
-
-```python
-# rag_project_id=None → orphan only; -1 → all notes; positive int → that project
-orphan_only = rag_project_id is None
-effective_project_id = rag_project_id if (rag_project_id is not None and rag_project_id != -1) else None
-
-for score, note in await semantic_search_notes(
-    user_id, user_message, exclude_ids=search_exclude or None, limit=8,
-    project_id=effective_project_id,
-    orphan_only=orphan_only,
-):
-    ...
-```
-
-The same `orphan_only` / `effective_project_id` pattern applies to the keyword fallback call to `search_notes_for_context()`.
-
-### Conversation scope persistence
-
-**New DB column:** `conversations.rag_project_id INTEGER` (nullable, default `NULL`).
-
-Semantics match the three-value system above. `NULL` is the default for all new and existing conversations after migration — existing conversations transparently gain orphan-only scoping.
-
-**Model change** (`models/conversation.py`):
-```python
-rag_project_id: Mapped[int | None] = mapped_column(Integer, nullable=True, default=None)
-```
-
-`to_dict()` must include `"rag_project_id": self.rag_project_id`.
-
-**Route change** (`routes/chat.py`): `PATCH /api/chat/conversations/:id` must accept `rag_project_id` in the request body and call `update_conversation(conv_id, user_id, rag_project_id=value)`. `GET /api/chat/conversations/:id` returns `rag_project_id` via `to_dict()`.
-
-**Service change** (`services/chat.py`): `update_conversation()` must accept and persist `rag_project_id`.
-
-### Project summarization background job
-
-**New DB columns** on `projects`:
-```python
-auto_summary: Mapped[str | None] = mapped_column(Text, nullable=True)
-summary_updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
-```
-
-**`generate_project_summary(user_id: int, project_id: int) -> None`** (`services/projects.py`):
-- Fetches project metadata (title, description, goal)
-- Fetches up to 10 notes for that project: `SELECT title, body[:200] FROM notes WHERE project_id=? ORDER BY updated_at DESC LIMIT 10`
-- Builds an Ollama prompt: "Summarize this project in 3-4 sentences covering its purpose, themes, and content. Title: {title}. Description: {description}. Goal: {goal}. Recent notes: {sample}"
-- Calls Ollama (same `generate_completion()` helper used elsewhere, `stream=False`)
-- Stores result in `project.auto_summary` and `project.summary_updated_at = datetime.now(UTC)`
-- On Ollama failure: log debug message, return without updating (graceful degradation)
-
-**`backfill_project_summaries() -> None`** (`services/projects.py`): fire-and-forget, called at startup alongside `backfill_note_embeddings()`. Generates summaries for all projects where `auto_summary IS NULL`.
-
-**Trigger from `update_project()`**: after committing, call `asyncio.create_task(generate_project_summary(user_id, project_id))` unconditionally.
-
-**Trigger from note saves**: in `create_note()` and `update_note()` within `services/notes.py`, when `project_id` is not None, check `project.summary_updated_at`. If `None` or more than 1 hour old, fire `asyncio.create_task(generate_project_summary(user_id, project_id))`. This avoids flooding Ollama during heavy note-editing sessions.
-
-`generate_project_summary` and `backfill_project_summaries` are **internal background tasks only**, not exposed as LLM tools.
-
-### New LLM tools
-
-Both tools are added to `_CORE_TOOLS` in `services/tools.py`.
-
-**`search_projects(query: str)`**:
-- Loads all projects for the user from the DB (title, description, goal, auto_summary)
-- Scores each project: `SequenceMatcher(None, query.lower(), combined_text.lower()).ratio()` where `combined_text = f"{title} {description or ''} {auto_summary or ''}"`, plus keyword overlap bonus
-- Returns top 5 as `[{id, title, summary_snippet, score}]` where `summary_snippet` is `auto_summary[:200]` or `description[:200]`
-- Tool result type: `"projects_list"`
-
-**`set_rag_scope(project_id: int | None)`**:
-- `project_id = <positive int>` → scope to that project
-- `project_id = null` → orphan-only
-- `project_id = -1` → all notes
-- **Workspace guard:** if `workspace_project_id` is set on the current generation context, return `{success: false, error: "Cannot change RAG scope in workspace view"}` and make no changes
-- Validates positive project_id exists and belongs to user (returns error if not)
-- Calls `await update_conversation(conv_id, user_id, rag_project_id=project_id)` to persist immediately
-- Returns `{success: true, type: "rag_scope_set", scope_label: "<human-readable>"}` e.g. `"Orphan notes only"`, `"SciFi Project"`, `"All notes"`
-
-**`conv_id` threading** (`services/tools.py`, `services/generation_task.py`):
-
-Current `execute_tool()` signature:
-```python
-async def execute_tool(user_id: int, tool_name: str, arguments: dict) -> dict
-```
-
-Updated signature:
-```python
-async def execute_tool(
-    user_id: int,
-    tool_name: str,
-    arguments: dict,
-    conv_id: int | None = None,
-    workspace_project_id: int | None = None,
-) -> dict
-```
-
-In `generation_task.py`, the call site in the tool execution loop must pass `conv_id=conv_id, workspace_project_id=workspace_project_id` — both are already available as local variables in `run_generation()`.
-
-**SSE `new_rag_scope` wiring:**
-
-In `generation_task.py`, after each tool call returns, check `if result.get("type") == "rag_scope_set" and result.get("success")`. Store `new_rag_scope = arguments["project_id"]` and `new_rag_scope_label = result["scope_label"]`.
-
-When emitting the final SSE `done` event (currently `{"done": True, "message_id": msg_id, "timing": timing}`), add the scope fields when present:
-
-```python
-done_payload = {"done": True, "message_id": msg_id, "timing": timing}
-if new_rag_scope_label is not None:
-    done_payload["new_rag_scope"] = new_rag_scope        # raw int or None
-    done_payload["new_rag_scope_label"] = new_rag_scope_label
-yield f"data: {json.dumps(done_payload)}\n\n"
-```
-
-In `stores/chat.ts`, the SSE `done` handler must check `event.data.new_rag_scope !== undefined` and set `currentConversation.value.rag_project_id = event.data.new_rag_scope`.
-
-### Frontend scope indicator
-
-**Chat store** (`stores/chat.ts`):
-- `currentConversation` already holds the full conversation object; add `rag_project_id: number | null` to the conversation interface
-- Add a computed `ragProjectId` that reads `currentConversation.value?.rag_project_id ?? null`
-- Add `async updateRagScope(convId: number, ragProjectId: number | null)` that calls `PATCH /api/chat/conversations/:id { rag_project_id }` and updates `currentConversation.value.rag_project_id` locally on success
-- In the SSE `done` handler, if `event.data.new_rag_scope !== undefined`, set `currentConversation.value.rag_project_id = event.data.new_rag_scope`
-
-**ChatView** (`views/ChatView.vue`):
-- Remove the existing `ProjectSelector` from the sidebar RAG scope section
-- Add a scope chip just above the message input. Shows: `⊙ Orphan notes` (null) / `⊙ All notes` (-1) / `⊙ {project title}` (positive int)
-- Clicking opens a compact dropdown: "Orphan notes only", all active projects by title, "All notes"
-- On selection, call `chatStore.updateRagScope(convId, selectedValue)`
-- When `chatStore.ragProjectId` changes (from SSE or UI), briefly apply a CSS pulse animation to the chip
-- Load the projects list once on mount via `apiGet("/api/projects?status=active")`
-
-**WorkspaceView** — no change. It hardcodes `ragProjectId` to the workspace project's id (positive int). Scope chip is not shown in workspace view.
-
----
-
-## Files Changed
-
-### Backend
-
-| File | Change |
-|------|--------|
-| `alembic/versions/0030_rag_scoping.py` | Add `conversations.rag_project_id`, `projects.auto_summary`, `projects.summary_updated_at` |
-| `models/conversation.py` | Add `rag_project_id: Mapped[int \| None]`; include in `to_dict()` |
-| `models/project.py` | Add `auto_summary: Mapped[str \| None]`, `summary_updated_at: Mapped[datetime \| None]` |
-| `services/projects.py` | Add `generate_project_summary()`, `backfill_project_summaries()`; trigger from `update_project()` |
-| `services/notes.py` | Add `orphan_only` param to `search_notes_for_context()`; trigger summary regen from note saves |
-| `services/embeddings.py` | Add `orphan_only: bool = False` param to `semantic_search_notes()` |
-| `services/llm.py` | Compute `orphan_only` + `effective_project_id` from `rag_project_id`; pass to both search calls |
-| `services/tools.py` | Add `search_projects` and `set_rag_scope` definitions and handlers; update `execute_tool()` signature |
-| `services/generation_task.py` | Pass `conv_id` + `workspace_project_id` to `execute_tool()`; capture scope change; emit in SSE done |
-| `services/chat.py` | Add `rag_project_id` parameter to `update_conversation()` |
-| `routes/chat.py` | Accept `rag_project_id` in PATCH body; return in GET responses via `to_dict()` |
-| `app.py` | Call `backfill_project_summaries()` at startup |
-
-### Frontend
-
-| File | Change |
-|------|--------|
-| `api/client.ts` | Conversation type includes `rag_project_id`; helpers accept it |
-| `stores/chat.ts` | `ragProjectId` computed; `updateRagScope()` method; SSE done handler updates scope |
-| `views/ChatView.vue` | Replace sidebar `ProjectSelector` with scope chip above input bar |
-
----
-
-## Data Flow
-
-```
-User changes scope via chip
-  → chatStore.updateRagScope(convId, value)
-  → PATCH /api/chat/conversations/:id { rag_project_id: value }
-  → DB updated; currentConversation.rag_project_id updated locally
-  → chip re-renders immediately
-
-User sends message
-  → sendMessage() reads chatStore.ragProjectId → passes as rag_project_id in POST body
-  → build_context() derives orphan_only + effective_project_id
-  → RAG results scoped accordingly
-
-Model calls set_rag_scope(3) during generation
-  → execute_tool(conv_id=X, workspace_project_id=None) writes rag_project_id=3 to DB
-  → returns { success: true, type: "rag_scope_set", scope_label: "SciFi Project" }
-  → generation_task stores new_rag_scope=3, new_rag_scope_label="SciFi Project"
-  → SSE done event: { done: true, new_rag_scope: 3, new_rag_scope_label: "SciFi Project", ... }
-  → chat store done handler: currentConversation.rag_project_id = 3
-  → chip pulses → "⊙ SciFi Project"
-
-User opens existing conversation
-  → GET /api/chat/conversations/:id returns rag_project_id
-  → chat store sets currentConversation; ragProjectId computed picks it up
-  → chip renders correct scope immediately
-```
-
----
-
-## Error Handling
-
-- **Ollama unavailable during summary gen:** log debug, return without updating; old summary (or null) retained; `search_projects` falls back to title + description matching
-- **`set_rag_scope` called in workspace:** return `{success: false, error: "Cannot change RAG scope in workspace view"}`; no DB write
-- **`set_rag_scope` with unknown positive project_id:** return `{success: false, error: "Project not found"}`; scope unchanged
-- **`search_projects` with no summaries yet:** score on title + description only; still returns results
-- **Existing conversations after migration:** `rag_project_id` defaults to `NULL` → orphan-only; behavior silently improves without user action
-
----
-
-## Testing
-
-- Unit: `semantic_search_notes(orphan_only=True)` returns only notes where `project_id IS NULL`
-- Unit: `semantic_search_notes(project_id=3, orphan_only=False)` returns only notes for project 3
-- Unit: `build_context()` passes correct `orphan_only` / `effective_project_id` for all three `rag_project_id` values (None, -1, positive)
-- Unit: `search_projects()` scoring ranks correct project first for representative queries; degrades gracefully with no summaries
-- Unit: `generate_project_summary()` builds correct Ollama prompt; handles Ollama failure gracefully
-- Integration: `set_rag_scope()` handler writes to DB, returns correct scope_label, rejects in workspace context
-- Integration: SSE `done` event includes `new_rag_scope` when scope changes mid-conversation
-- Frontend: scope chip reflects loaded conversation scope; updates reactively on model tool call

docs/superpowers/specs/2026-03-27-news-briefing-redesign.md

@@ -1,398 +0,0 @@
-# News Feed & Briefing View Redesign
-
-> **For agentic workers:** Use superpowers:executing-plans or superpowers:subagent-driven-development to implement this spec task-by-task.
-
-**Goal:** Extend RSS article retention to 90 days, introduce a unified news API, redesign the briefing view into a 3-column layout (weather · chat · news), add deep article Q&A in briefing chat, and add a `/news` archive view.
-
----
-
-## Architecture
-
-### Data layer
-`rss_items` and `rss_item_reactions` already exist and contain everything needed. No new tables or migrations required. The only DB change is extending the prune window from 14 to 90 days.
-
-### Unified news API
-A single `GET /api/briefing/news` endpoint serves both the briefing side panel (short window, no pagination) and the news archive view (full history, paginated). Both consumers share the same response shape and reaction logic.
-
-### Briefing view
-`BriefingView.vue` restructures from a single-column `max-width: 760px` layout to a full-width CSS grid with three independently scrolling columns. Weather and news are fetched directly — no longer read from message metadata.
-
-### News archive view
-A new `NewsView.vue` at `/news`, added to the sidebar nav, uses the same `/api/briefing/news` endpoint with `days=90` and offset-based pagination.
-
-### Deep article Q&A
-`build_context()` in `llm.py` detects briefing conversations and injects the source article content from today's briefing into the system prompt, giving follow-up chat messages access to the full article text.
-
----
-
-## Section 1 — Data & API layer
-
-### 1a. Article retention (90 days)
-
-**File:** `src/fabledassistant/services/rss.py`
-
-Change the module-level constant:
-```python
-ITEM_MAX_AGE_DAYS = 90
-```
-
-Update the SQL in `_prune_old_items`:
-```python
-AND published_at < NOW() - INTERVAL '90 days'
-```
-
-### 1b. Unified news endpoint
-
-**File:** `src/fabledassistant/routes/briefing.py`
-
-Add `GET /api/briefing/news` endpoint (registered on `briefing_bp` which has prefix `/api/briefing`):
-
-```python
-@briefing_bp.route("/news", methods=["GET"])
-@_REQUIRE
-async def list_news():
-    days = min(int(request.args.get("days", 2)), 90)
-    limit = min(int(request.args.get("limit", 40)), 100)
-    offset = max(int(request.args.get("offset", 0)), 0)
-    feed_id = request.args.get("feed_id", type=int)
-
-    from sqlalchemy import text as _text
-    async with async_session() as session:
-        result = await session.execute(
-            _text("""
-                SELECT
-                    i.id, i.title, i.url, i.content, i.published_at,
-                    i.topics, f.title AS feed_title,
-                    r.reaction
-                FROM rss_items i
-                JOIN rss_feeds f ON f.id = i.feed_id
-                LEFT JOIN rss_item_reactions r
-                    ON r.rss_item_id = i.id AND r.user_id = :uid
-                WHERE f.user_id = :uid
-                  AND (:feed_id IS NULL OR f.id = :feed_id)
-                  AND i.published_at >= NOW() - make_interval(days => :days)
-                ORDER BY i.published_at DESC NULLS LAST
-                LIMIT :limit OFFSET :offset
-            """).bindparams(uid=g.user.id, days=days, limit=limit,
-                            offset=offset, feed_id=feed_id)
-        )
-        rows = result.mappings().all()
-
-    items = [
-        {
-            "id": r["id"],
-            "title": r["title"],
-            "url": r["url"],
-            "snippet": (r["content"] or "")[:300],
-            "published_at": r["published_at"].isoformat() if r["published_at"] else None,
-            "topics": r["topics"] or [],
-            "source": r["feed_title"],
-            "reaction": r["reaction"],
-        }
-        for r in rows
-    ]
-    return jsonify({"items": items, "offset": offset, "limit": limit})
-```
-
----
-
-## Section 2 — Briefing view redesign
-
-### 2a. Layout restructure
-
-**File:** `frontend/src/views/BriefingView.vue`
-
-**Layout change:** Replace `.briefing-shell` (single column, max-width 760px) with a full-width 3-column grid:
-
-```css
-.briefing-shell {
-  display: grid;
-  grid-template-rows: auto 1fr;
-  grid-template-columns: 1fr 2fr 1fr;
-  height: 100%;
-  min-height: 0;
-}
-
-.briefing-header {
-  grid-column: 1 / -1; /* spans all three columns */
-}
-
-.briefing-left {
-  grid-column: 1;
-  border-right: 1px solid var(--color-border);
-  overflow-y: auto;
-  padding: 1rem;
-  display: flex;
-  flex-direction: column;
-  gap: 0.75rem;
-}
-
-.briefing-center {
-  grid-column: 2;
-  display: flex;
-  flex-direction: column;
-  min-height: 0;
-}
-
-.briefing-right {
-  grid-column: 3;
-  border-left: 1px solid var(--color-border);
-  overflow-y: auto;
-  padding: 1rem;
-  display: flex;
-  flex-direction: column;
-  gap: 0.5rem;
-}
-
-@media (max-width: 900px) {
-  .briefing-shell {
-    grid-template-columns: 1fr;
-    grid-template-rows: auto auto 1fr auto;
-  }
-  .briefing-header { grid-column: 1; }
-  .briefing-left, .briefing-right {
-    border: none;
-    border-bottom: 1px solid var(--color-border);
-    max-height: 200px;
-  }
-}
-```
-
-### 2b. Weather panel (left column)
-
-Remove `WeatherCard` from the message flow. Load weather independently on mount:
-
-Extract the existing weather shape from `MessageMetadata` into a standalone `WeatherData` interface at the top of `BriefingView.vue` (same fields: `location`, `current_temp`, `condition`, `today_high`, `today_low`, `yesterday_high`, `yesterday_low`, `forecast[]`). The `MessageMetadata` interface can then be removed since `rss_items`/weather are no longer read from message metadata.
-
-```typescript
-const weatherData = ref<WeatherData[]>([])
-
-async function loadWeather() {
-  try {
-    const data = await apiGet<{ locations: WeatherData[] }>('/api/briefing/weather')
-    weatherData.value = data.locations ?? []
-  } catch { /* silent */ }
-}
-```
-
-Render in left column:
-```html
-<div class="briefing-left">
-  <div class="panel-label">Weather</div>
-  <template v-if="weatherData.length">
-    <WeatherCard v-for="loc in weatherData" :key="(loc as WeatherData).location" :weather="loc" />
-  </template>
-  <div v-else class="panel-empty">No weather configured</div>
-</div>
-```
-
-### 2c. News panel (right column)
-
-Load on mount and on background refresh:
-
-```typescript
-const newsItems = ref<NewsItem[]>([])
-
-async function loadNews() {
-  try {
-    const data = await apiGet<{ items: NewsItem[] }>('/api/briefing/news?days=2&limit=40')
-    newsItems.value = data.items
-  } catch { /* silent */ }
-}
-```
-
-Render in right column using the existing `news-card` markup and `handleReaction` function. Remove the inline `news-cards` block from the message loop.
-
-### 2d. Auto-scroll to bottom on mount
-
-After messages load, scroll the center messages container to the bottom:
-
-```typescript
-const messagesEl = ref<HTMLElement | null>(null)
-
-function scrollToBottom() {
-  nextTick(() => {
-    if (messagesEl.value) {
-      messagesEl.value.scrollTop = messagesEl.value.scrollHeight
-    }
-  })
-}
-```
-
-Call `scrollToBottom()` after `loadAll()` completes and after the streaming watcher fires.
-
-### 2e. Remove inline weather/news from message flow
-
-In the message loop template, remove:
-- The `<WeatherCard>` block rendered above assistant messages
-- The `<div class="news-cards">` block rendered below assistant messages
-
-The `msgMetadata()` helper and `MessageMetadata` interface can be removed entirely since they're no longer used in the template.
-
----
-
-## Section 3 — Deep article Q&A in briefing chat
-
-**File:** `src/fabledassistant/services/llm.py` (the `build_context()` function)
-
-After the existing RAG context is assembled, check if the conversation is a briefing and inject article content:
-
-```python
-# Inject briefing article content for follow-up Q&A
-if conversation and getattr(conversation, "conversation_type", None) == "briefing":
-    article_context = await _build_briefing_article_context(conversation.id)
-    if article_context:
-        system_parts.append(article_context)
-```
-
-New helper function in `llm.py`:
-
-```python
-async def _build_briefing_article_context(conv_id: int) -> str:
-    """
-    Fetch article content from today's briefing message and return
-    a formatted context block for injection into the system prompt.
-    Capped at 10 articles × 500 chars to keep token use reasonable.
-    """
-    from sqlalchemy import select, text as _text
-    from fabledassistant.models import async_session
-    from fabledassistant.models.conversation import Message
-    import json
-
-    async with async_session() as session:
-        # Get most recent assistant briefing message with rss_item_ids
-        result = await session.execute(
-            select(Message)
-            .where(
-                Message.conversation_id == conv_id,
-                Message.role == "assistant",
-            )
-            .order_by(Message.created_at.desc())
-            .limit(10)
-        )
-        messages = result.scalars().all()
-
-    rss_item_ids: list[int] = []
-    for msg in messages:
-        meta = msg.metadata or {}
-        if isinstance(meta, str):
-            try:
-                meta = json.loads(meta)
-            except Exception:
-                continue
-        ids = meta.get("rss_item_ids") or []
-        if ids:
-            rss_item_ids = ids
-            break
-
-    if not rss_item_ids:
-        return ""
-
-    async with async_session() as session:
-        result = await session.execute(
-            _text("""
-                SELECT i.title, i.url, i.content, f.title AS feed_title
-                FROM rss_items i
-                JOIN rss_feeds f ON f.id = i.feed_id
-                WHERE i.id = ANY(:ids)
-                ORDER BY i.published_at DESC NULLS LAST
-                LIMIT 10
-            """).bindparams(ids=rss_item_ids[:10])
-        )
-        rows = result.mappings().all()
-
-    if not rows:
-        return ""
-
-    lines = ["ARTICLE CONTEXT (source articles from today's briefing):"]
-    for row in rows:
-        lines.append(f"\n[{row['feed_title']}] {row['title']}")
-        if row["url"]:
-            lines.append(f"URL: {row['url']}")
-        if row["content"]:
-            lines.append(row["content"][:500])
-    return "\n".join(lines)
-```
-
----
-
-## Section 4 — News archive view
-
-### 4a. Frontend type
-
-**File:** `frontend/src/types/news.ts` (new)
-
-```typescript
-export interface NewsItem {
-  id: number
-  title: string
-  url: string
-  snippet: string
-  published_at: string | null
-  topics: string[]
-  source: string
-  reaction: 'up' | 'down' | null
-}
-```
-
-### 4b. NewsView component
-
-**File:** `frontend/src/views/NewsView.vue` (new)
-
-- Loads feeds list from `GET /api/briefing/feeds` for the filter dropdown
-- Loads items from `GET /api/briefing/news?days=90&limit=40&offset=0&feed_id=X`
-- "Load more" button appends next page (increments offset by 40)
-- Each card: source label, title as `<a target="_blank">`, snippet, relative date, 👍/👎 buttons
-- Reactions call existing `POST /api/briefing/rss-reactions` / `DELETE /api/briefing/rss-reactions/:id`
-- Local `reactions` map tracks optimistic state (same pattern as `BriefingView.vue`)
-
-```typescript
-const items = ref<NewsItem[]>([])
-const offset = ref(0)
-const hasMore = ref(true)
-const selectedFeedId = ref<number | null>(null)
-const loading = ref(false)
-
-async function loadMore() {
-  if (loading.value || !hasMore.value) return
-  loading.value = true
-  try {
-    const params = new URLSearchParams({
-      days: '90', limit: '40', offset: String(offset.value)
-    })
-    if (selectedFeedId.value) params.set('feed_id', String(selectedFeedId.value))
-    const data = await apiGet<{ items: NewsItem[] }>(`/api/briefing/news?${params}`)
-    items.value = [...items.value, ...data.items]
-    offset.value += data.items.length
-    hasMore.value = data.items.length === 40
-  } finally {
-    loading.value = false
-  }
-}
-
-function onFeedChange() {
-  items.value = []
-  offset.value = 0
-  hasMore.value = true
-  loadMore()
-}
-```
-
-### 4c. Router and nav
-
-**File:** `frontend/src/router/index.ts`
-```typescript
-{ path: '/news', component: () => import('@/views/NewsView.vue') }
-```
-
-**File:** `frontend/src/App.vue` (nav links section)
-Add `<router-link to="/news">News</router-link>` alongside Notes/Tasks/Projects.
-
----
-
-## What is NOT in scope
-
-- Topic-based filtering in the news archive (reactions shape preferences; filtering can come later)
-- Inline article display / full-text reader (links open to source)
-- Changes to the RSS feed management UI in Settings
-- Push notifications for new articles

fable-mcp/.env.example

@@ -1,2 +0,0 @@
-FABLE_URL=http://localhost:5000
-FABLE_API_KEY=fmcp_your_key_here

fable-mcp/fable_mcp/client.py

@@ -1,124 +0,0 @@
-"""Async HTTP client for the Fable Assistant API."""
-from __future__ import annotations
-
-import os
-from typing import Any, AsyncIterator
-
-import httpx
-
-
-class FableAPIError(Exception):
-    """Raised when the Fable API returns a non-2xx response."""
-
-    def __init__(self, status_code: int, message: str) -> None:
-        self.status_code = status_code
-        super().__init__(f"Fable API error {status_code}: {message}")
-
-
-class FableClient:
-    """Async wrapper around httpx for the Fable REST API."""
-
-    def __init__(self) -> None:
-        url = os.environ.get("FABLE_URL", "").rstrip("/")
-        key = os.environ.get("FABLE_API_KEY", "")
-        if not url:
-            raise ValueError("FABLE_URL environment variable is required")
-        if not key:
-            raise ValueError("FABLE_API_KEY environment variable is required")
-        self.base_url = url
-        self._headers = {
-            "Authorization": f"Bearer {key}",
-            "Content-Type": "application/json",
-        }
-        self._client: httpx.AsyncClient | None = None
-
-    async def __aenter__(self) -> "FableClient":
-        self._client = httpx.AsyncClient(
-            base_url=self.base_url,
-            headers=self._headers,
-            timeout=30.0,
-        )
-        return self
-
-    async def __aexit__(self, *args: Any) -> None:
-        if self._client:
-            await self._client.aclose()
-            self._client = None
-
-    def _http(self) -> httpx.AsyncClient:
-        if self._client is None:
-            raise RuntimeError("FableClient must be used as an async context manager")
-        return self._client
-
-    @staticmethod
-    def _raise_for_status(response: httpx.Response) -> None:
-        if response.is_error:
-            try:
-                message = response.json().get("error", response.text)
-            except Exception:
-                message = response.text
-            raise FableAPIError(response.status_code, message)
-
-    async def get(self, path: str, **kwargs: Any) -> Any:
-        response = await self._http().get(path, **kwargs)
-        self._raise_for_status(response)
-        return response.json()
-
-    async def post(self, path: str, **kwargs: Any) -> Any:
-        response = await self._http().post(path, **kwargs)
-        self._raise_for_status(response)
-        return response.json()
-
-    async def patch(self, path: str, **kwargs: Any) -> Any:
-        response = await self._http().patch(path, **kwargs)
-        self._raise_for_status(response)
-        return response.json()
-
-    async def put(self, path: str, **kwargs: Any) -> Any:
-        response = await self._http().put(path, **kwargs)
-        self._raise_for_status(response)
-        return response.json()
-
-    async def delete(self, path: str, **kwargs: Any) -> Any:
-        response = await self._http().delete(path, **kwargs)
-        if response.status_code == 204:
-            return None
-        self._raise_for_status(response)
-        if response.content:
-            return response.json()
-        return None
-
-    async def stream_get(self, path: str, **kwargs: Any) -> AsyncIterator[str]:
-        """Yield non-empty lines from a streaming GET response (SSE)."""
-        async with self._http().stream("GET", path, **kwargs) as response:
-            self._raise_for_status(response)
-            async for line in response.aiter_lines():
-                if line:
-                    yield line
-
-
-# ---------------------------------------------------------------------------
-# Module-level singleton
-# ---------------------------------------------------------------------------
-
-_client: FableClient | None = None
-
-
-def init_client() -> FableClient:
-    """Initialise the module-level FableClient singleton (reads env vars)."""
-    global _client
-    _client = FableClient()
-    return _client
-
-
-def get_client() -> FableClient:
-    """Return the singleton client; raises RuntimeError if not initialised."""
-    if _client is None:
-        raise RuntimeError("Call init_client() before get_client()")
-    return _client
-
-
-def _reset_client() -> None:
-    """Reset the singleton — used by tests only."""
-    global _client
-    _client = None

fable-mcp/fable_mcp/server.py

@@ -1,643 +0,0 @@
-"""Fable MCP server — exposes Fable Assistant as MCP tools via stdio transport."""
-from __future__ import annotations
-
-from mcp.server.fastmcp import FastMCP
-from dotenv import load_dotenv
-
-from fable_mcp.client import FableClient
-from fable_mcp.tools import notes, tasks, projects, milestones, search, chat, admin, briefing
-
-load_dotenv()
-
-_INSTRUCTIONS = """
-Fable Assistant is a self-hosted second-brain and project management system with LLM integration.
-
-## Data model
-
-The hierarchy is: Project → Milestone → Task/Note.
-
-- **Notes** and **Tasks** share the same underlying model. Tasks are notes with `is_task=True`.
-  The note tools (fable_*_note) operate on notes; the task tools (fable_*_task) operate on tasks.
-  Do not use note tools to manipulate tasks or vice versa.
-
-- **Projects** group related work. A project has a title, description, goal, status, and an
-  auto-generated summary used for semantic search. Status values: `active`, `archived`.
-
-- **Milestones** belong to a project and group tasks within it. Status values: `active`, `done`.
-
-- **Tasks** belong to a project and optionally a milestone. They support sub-tasks via `parent_id`.
-  - Status values: `todo`, `in_progress`, `done`, `cancelled`
-  - Priority values: `low`, `normal`, `high`
-
-- **Notes** are free-form markdown documents. They can belong to a project or be standalone
-  (orphan notes). Orphan notes are included in the default RAG scope for chat conversations.
-
-## Tags
-
-Tags are plain strings — do NOT include a `#` prefix. Example: `["python", "architecture"]`.
-Tags are stored as an array on the note/task. Passing `tags=[]` clears all tags; omitting `tags`
-leaves existing tags unchanged on updates.
-
-## Integer-or-none fields
-
-Due to MCP type constraints, optional integer fields (project_id, milestone_id, parent_id)
-use `0` to mean "not set / no association". Pass `0` to leave the field unset.
-
-## Search
-
-`fable_search` performs semantic (embedding-based) search over notes and tasks. Use it to find
-relevant content by meaning rather than exact keywords. Returns results ranked by cosine
-similarity with id, title, a body snippet, and tags.
-
-## Chat / LLM delegation
-
-`fable_send_message` sends a natural-language message to Fable's built-in LLM (Ollama). Fable
-handles its own tool use, RAG context injection, and conversation history internally.
-
-Use `fable_send_message` when:
-- The request is conversational or requires Fable's internal reasoning across many records
-- You want Fable's RAG to surface relevant notes automatically
-
-Use the direct CRUD tools when:
-- You know exactly what to create/read/update/delete
-- You need structured data back (IDs, field values) for further processing
-- You are populating Fable programmatically from another system
-
-## Task logs
-
-Use `fable_add_task_log` to append time-stamped progress notes to a task without overwriting
-its main body. Suitable for recording work sessions, decisions, or status updates over time.
-
-## RSS / Briefing
-
-Fable runs a daily briefing that summarises tasks, calendar events, and RSS feed items.
-Use `fable_add_rss_feed` / `fable_remove_rss_feed` to manage the feeds included in that briefing.
-
-## Admin logs
-
-`fable_get_app_logs` requires an admin-scoped API key. Regular user keys will be rejected.
-"""
-
-mcp = FastMCP("fable", instructions=_INSTRUCTIONS)
-
-
-# ---------------------------------------------------------------------------
-# Notes
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-async def fable_list_notes(
-    limit: int = 20,
-    offset: int = 0,
-    tag: str = "",
-    search_text: str = "",
-) -> dict:
-    """List notes (non-task documents) stored in Fable.
-
-    Optionally filter by a single tag (plain string, no # prefix) or a keyword search
-    against title and body. Results are ordered by last-updated descending.
-
-    Use fable_search for semantic/meaning-based lookup instead of exact keyword search.
-    """
-    async with FableClient() as client:
-        return await notes.list_notes(
-            client,
-            limit=limit,
-            offset=offset,
-            tag=tag or None,
-            search=search_text or None,
-        )
-
-
-@mcp.tool()
-async def fable_get_note(note_id: int) -> dict:
-    """Fetch the full content of a single Fable note by its ID.
-
-    Returns id, title, body (markdown), tags, project_id, created_at, updated_at.
-    """
-    async with FableClient() as client:
-        return await notes.get_note(client, note_id=note_id)
-
-
-@mcp.tool()
-async def fable_create_note(
-    title: str,
-    body: str = "",
-    tags: list[str] | None = None,
-    project_id: int = 0,
-) -> dict:
-    """Create a new note in Fable.
-
-    Args:
-        title: Note title (required).
-        body: Markdown content. Supports [[wikilinks]] to other notes by title.
-        tags: List of plain-string tags without # prefix, e.g. ["python", "ideas"].
-        project_id: Associate with a project (use 0 for no project / orphan note).
-
-    Returns the created note object including its assigned id.
-    """
-    async with FableClient() as client:
-        return await notes.create_note(
-            client,
-            title=title,
-            body=body,
-            tags=tags,
-            project_id=project_id or None,
-        )
-
-
-@mcp.tool()
-async def fable_update_note(
-    note_id: int,
-    title: str = "",
-    body: str = "",
-    tags: list[str] | None = None,
-    project_id: int = 0,
-) -> dict:
-    """Update an existing Fable note. Only explicitly provided fields are changed.
-
-    Args:
-        note_id: ID of the note to update.
-        title: New title, or omit to leave unchanged.
-        body: New markdown body, or omit to leave unchanged.
-        tags: Replaces the full tag list. Pass [] to clear all tags. Omit to leave unchanged.
-        project_id: New project association (0 = remove from project). Omit to leave unchanged.
-    """
-    async with FableClient() as client:
-        return await notes.update_note(
-            client,
-            note_id=note_id,
-            title=title or None,
-            body=body or None,
-            tags=tags,
-            project_id=project_id or None,
-        )
-
-
-@mcp.tool()
-async def fable_delete_note(note_id: int) -> str:
-    """Permanently delete a Fable note by ID. This cannot be undone."""
-    async with FableClient() as client:
-        await notes.delete_note(client, note_id=note_id)
-    return f"Note {note_id} deleted."
-
-
-# ---------------------------------------------------------------------------
-# Tasks
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-async def fable_list_tasks(
-    limit: int = 20,
-    offset: int = 0,
-    status: str = "",
-    project_id: int = 0,
-) -> dict:
-    """List tasks in Fable.
-
-    Args:
-        status: Filter by status — one of: todo, in_progress, done, cancelled. Omit for all.
-        project_id: Filter to a specific project. Use 0 for no filter.
-
-    Results are ordered by last-updated descending.
-    """
-    async with FableClient() as client:
-        return await tasks.list_tasks(
-            client,
-            limit=limit,
-            offset=offset,
-            status=status or None,
-            project_id=project_id or None,
-        )
-
-
-@mcp.tool()
-async def fable_get_task(task_id: int) -> dict:
-    """Fetch a single Fable task by ID.
-
-    Returns id, title, body, status, priority, tags, project_id, milestone_id,
-    parent_id, parent_title, due_date, created_at, updated_at.
-    """
-    async with FableClient() as client:
-        return await tasks.get_task(client, task_id=task_id)
-
-
-@mcp.tool()
-async def fable_create_task(
-    title: str,
-    body: str = "",
-    status: str = "todo",
-    priority: str = "",
-    project_id: int = 0,
-    milestone_id: int = 0,
-    parent_id: int = 0,
-    tags: list[str] | None = None,
-) -> dict:
-    """Create a new task in Fable.
-
-    Args:
-        title: Task title (required).
-        body: Markdown description / notes for the task.
-        status: Initial status — one of: todo (default), in_progress, done, cancelled.
-        priority: One of: low, normal, high. Omit for no priority.
-        project_id: Associate with a project (0 = no project).
-        milestone_id: Place within a project milestone (0 = no milestone).
-        parent_id: Make this a sub-task of another task (0 = top-level).
-        tags: List of plain-string tags without # prefix.
-
-    Returns the created task object including its assigned id.
-    """
-    async with FableClient() as client:
-        return await tasks.create_task(
-            client,
-            title=title,
-            body=body,
-            status=status,
-            priority=priority or None,
-            project_id=project_id or None,
-            milestone_id=milestone_id or None,
-            parent_id=parent_id or None,
-            tags=tags,
-        )
-
-
-@mcp.tool()
-async def fable_update_task(
-    task_id: int,
-    title: str = "",
-    body: str = "",
-    status: str = "",
-    priority: str = "",
-    project_id: int = 0,
-    milestone_id: int = 0,
-) -> dict:
-    """Update an existing Fable task. Only explicitly provided fields are changed.
-
-    Args:
-        task_id: ID of the task to update.
-        title: New title, or omit to leave unchanged.
-        body: New markdown body, or omit to leave unchanged.
-        status: New status — one of: todo, in_progress, done, cancelled.
-        priority: New priority — one of: low, normal, high.
-        project_id: New project (0 = remove from project). Omit to leave unchanged.
-        milestone_id: New milestone (0 = remove from milestone). Omit to leave unchanged.
-    """
-    async with FableClient() as client:
-        return await tasks.update_task(
-            client,
-            task_id=task_id,
-            title=title or None,
-            body=body or None,
-            status=status or None,
-            priority=priority or None,
-            project_id=project_id or None,
-            milestone_id=milestone_id or None,
-        )
-
-
-@mcp.tool()
-async def fable_add_task_log(task_id: int, body: str) -> dict:
-    """Append a timestamped progress log entry to a Fable task.
-
-    Use this to record work sessions, decisions, or status updates over time without
-    overwriting the task's main body. Each entry is stored separately and shown
-    chronologically in the task view.
-    """
-    async with FableClient() as client:
-        return await tasks.add_task_log(client, task_id=task_id, body=body)
-
-
-# ---------------------------------------------------------------------------
-# Projects
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-async def fable_list_projects() -> dict:
-    """List all Fable projects for the current user.
-
-    Returns id, title, description, goal, status (active/archived), color,
-    and a short auto-generated summary for each project.
-    """
-    async with FableClient() as client:
-        return await projects.list_projects(client)
-
-
-@mcp.tool()
-async def fable_get_project(project_id: int) -> dict:
-    """Fetch a Fable project by ID, including its milestone summary.
-
-    Returns full project fields plus a milestone_summary list with each milestone's
-    id, title, status, and task counts.
-    """
-    async with FableClient() as client:
-        return await projects.get_project(client, project_id=project_id)
-
-
-@mcp.tool()
-async def fable_create_project(
-    title: str,
-    description: str = "",
-    goal: str = "",
-    status: str = "active",
-    color: str = "",
-) -> dict:
-    """Create a new project in Fable.
-
-    Args:
-        title: Project name (required).
-        description: Short summary of what the project is.
-        goal: The desired outcome or definition of done for the project.
-        status: active (default) or archived.
-        color: Optional hex colour for the project card (e.g. "#6366f1").
-
-    Returns the created project object including its assigned id.
-    """
-    async with FableClient() as client:
-        return await projects.create_project(
-            client,
-            title=title,
-            description=description,
-            goal=goal or None,
-            status=status,
-            color=color or None,
-        )
-
-
-@mcp.tool()
-async def fable_update_project(
-    project_id: int,
-    title: str = "",
-    description: str = "",
-    goal: str = "",
-    status: str = "",
-    color: str = "",
-) -> dict:
-    """Update an existing Fable project. Only explicitly provided fields are changed.
-
-    Args:
-        project_id: ID of the project to update.
-        title: New title, or omit to leave unchanged.
-        description: New description, or omit to leave unchanged.
-        goal: New goal/definition-of-done, or omit to leave unchanged.
-        status: New status — active or archived.
-        color: New hex colour, or omit to leave unchanged.
-    """
-    async with FableClient() as client:
-        return await projects.update_project(
-            client,
-            project_id=project_id,
-            title=title or None,
-            description=description or None,
-            goal=goal or None,
-            status=status or None,
-            color=color or None,
-        )
-
-
-# ---------------------------------------------------------------------------
-# Milestones
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-async def fable_list_milestones(project_id: int) -> dict:
-    """List milestones for a Fable project, ordered by order_index.
-
-    Returns id, title, description, status (active/done), order_index, and task counts.
-    """
-    async with FableClient() as client:
-        return await milestones.list_milestones(client, project_id=project_id)
-
-
-@mcp.tool()
-async def fable_create_milestone(
-    project_id: int,
-    title: str,
-    description: str = "",
-    status: str = "active",
-) -> dict:
-    """Create a milestone within a Fable project.
-
-    Args:
-        project_id: The project this milestone belongs to (required).
-        title: Milestone name (required).
-        description: Optional description of what this milestone covers.
-        status: active (default) or done.
-
-    Returns the created milestone including its assigned id.
-    """
-    async with FableClient() as client:
-        return await milestones.create_milestone(
-            client,
-            project_id=project_id,
-            title=title,
-            description=description,
-            status=status,
-        )
-
-
-@mcp.tool()
-async def fable_update_milestone(
-    project_id: int,
-    milestone_id: int,
-    title: str = "",
-    description: str = "",
-    status: str = "",
-    order_index: int = -1,
-) -> dict:
-    """Update a Fable milestone. Only explicitly provided fields are changed.
-
-    Args:
-        project_id: Project the milestone belongs to.
-        milestone_id: ID of the milestone to update.
-        title: New title, or omit to leave unchanged.
-        description: New description, or omit to leave unchanged.
-        status: New status — active or done.
-        order_index: New display position (0-based). Use -1 to leave unchanged.
-    """
-    async with FableClient() as client:
-        return await milestones.update_milestone(
-            client,
-            project_id=project_id,
-            milestone_id=milestone_id,
-            title=title or None,
-            description=description or None,
-            status=status or None,
-            order_index=order_index if order_index >= 0 else None,
-        )
-
-
-# ---------------------------------------------------------------------------
-# Search
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-async def fable_search(
-    q: str,
-    content_type: str = "all",
-    limit: int = 10,
-) -> dict:
-    """Semantic search over Fable notes and tasks using embedding similarity.
-
-    Finds content by meaning rather than exact keywords. Use this to discover
-    relevant records when you don't know the exact title or tags.
-
-    Args:
-        q: Natural-language query string.
-        content_type: "note", "task", or "all" (default).
-        limit: Maximum number of results (default 10).
-
-    Returns results ordered by cosine similarity, each with id, title, body snippet, and tags.
-    """
-    async with FableClient() as client:
-        return await search.search(client, q=q, content_type=content_type, limit=limit)
-
-
-# ---------------------------------------------------------------------------
-# Chat
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-async def fable_list_conversations(limit: int = 20, offset: int = 0) -> dict:
-    """List chat conversations stored in Fable, ordered by last activity.
-
-    Returns id, title, message_count, created_at, updated_at for each conversation.
-    Use the id with fable_send_message to continue a specific conversation.
-    """
-    async with FableClient() as client:
-        return await chat.list_conversations(client, limit=limit, offset=offset)
-
-
-@mcp.tool()
-async def fable_send_message(
-    message: str,
-    conversation_id: str = "",
-    think: bool = False,
-) -> dict:
-    """Send a natural-language message to Fable's built-in LLM and receive the full response.
-
-    Fable handles tool use, RAG context injection, and conversation history internally.
-    The LLM can create/update notes and tasks, search, manage projects, and more — all
-    driven by natural language without you needing to call individual tools.
-
-    Use this when:
-    - The request is conversational or exploratory
-    - You want Fable's RAG to automatically surface relevant notes as context
-    - The task is complex enough to benefit from Fable's internal reasoning
-
-    Use the direct CRUD tools (fable_create_note, etc.) instead when you need
-    structured data back or are performing bulk/programmatic operations.
-
-    Args:
-        message: The user message to send.
-        conversation_id: Continue an existing conversation by passing its id.
-                         Omit to start a new conversation.
-        think: Enable extended reasoning mode for complex multi-step requests.
-
-    Returns conversation_id (for follow-up messages), the assistant response text,
-    and a list of any tool_call events that fired during generation.
-    """
-    async with FableClient() as client:
-        return await chat.send_message(
-            client,
-            message=message,
-            conversation_id=conversation_id or None,
-            think=think,
-        )
-
-
-# ---------------------------------------------------------------------------
-# Admin / observability
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-async def fable_get_app_logs(
-    category: str = "error",
-    limit: int = 20,
-    search: str = "",
-) -> dict:
-    """Fetch Fable application logs. Requires an admin-scoped API key.
-
-    Args:
-        category: Log category — "error" (default), "audit", or "usage".
-        limit: Maximum number of log entries to return.
-        search: Optional keyword filter matched against action, endpoint, username, details.
-
-    Returns a list of log entries ordered by most recent first.
-    Regular user API keys will receive a 403 — only admin keys are accepted.
-    """
-    async with FableClient() as client:
-        return await admin.get_app_logs(
-            client,
-            category=category,
-            limit=limit,
-            search=search or None,
-        )
-
-
-# ---------------------------------------------------------------------------
-# Briefing / RSS
-# ---------------------------------------------------------------------------
-
-
-@mcp.tool()
-async def fable_list_rss_feeds() -> dict:
-    """List all RSS/Atom feeds configured in Fable for the current user.
-
-    Returns id, title, url, category, and last_fetched_at for each feed.
-    These feeds are summarised in the user's daily briefing.
-    """
-    async with FableClient() as client:
-        return await briefing.list_rss_feeds(client)
-
-
-@mcp.tool()
-async def fable_add_rss_feed(
-    url: str,
-    title: str = "",
-    category: str = "",
-) -> dict:
-    """Add an RSS or Atom feed to Fable's daily briefing.
-
-    Args:
-        url: The RSS/Atom feed URL (required).
-        title: Optional display name. If omitted, auto-populated from feed metadata.
-        category: Optional category label to group feeds (e.g. "news", "tech", "finance").
-
-    Returns the created feed object including its assigned id.
-    """
-    async with FableClient() as client:
-        return await briefing.add_rss_feed(
-            client,
-            url=url,
-            title=title or None,
-            category=category or None,
-        )
-
-
-@mcp.tool()
-async def fable_remove_rss_feed(feed_id: int) -> dict:
-    """Remove an RSS feed from Fable by its ID."""
-    async with FableClient() as client:
-        return await briefing.remove_rss_feed(client, feed_id=feed_id)
-
-
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
-
-
-def main() -> None:
-    # Validate env vars at startup — raises ValueError with a clear message if missing.
-    FableClient()
-    mcp.run(transport="stdio")
-
-
-if __name__ == "__main__":
-    main()

fable-mcp/fable_mcp/tools/admin.py

@@ -1,20 +0,0 @@
-"""Admin tools: application log access (requires admin API key)."""
-from __future__ import annotations
-
-from fable_mcp.client import FableClient
-
-
-async def get_app_logs(
-    client: FableClient,
-    category: str = "error",
-    limit: int = 20,
-    search: str | None = None,
-) -> dict:
-    """Fetch application logs from Fable. Requires an admin-scoped API key.
-
-    category: "error" | "audit" | "usage" (default: "error")
-    """
-    params: dict = {"category": category, "limit": limit}
-    if search:
-        params["search"] = search
-    return await client.get("/api/admin/logs", params=params)

fable-mcp/fable_mcp/tools/briefing.py

@@ -1,32 +0,0 @@
-"""MCP tools for Fable RSS feed management."""
-from __future__ import annotations
-
-from typing import Any
-
-from fable_mcp.client import FableClient
-
-
-async def list_rss_feeds(client: FableClient) -> dict[str, Any]:
-    """List the user's RSS feeds."""
-    return await client.get("/api/briefing/feeds")
-
-
-async def add_rss_feed(
-    client: FableClient,
-    *,
-    url: str,
-    title: str | None = None,
-    category: str | None = None,
-) -> dict[str, Any]:
-    """Add a new RSS feed. Title is optional — auto-populated from feed metadata."""
-    payload: dict[str, Any] = {"url": url}
-    if title:
-        payload["title"] = title
-    if category:
-        payload["category"] = category
-    return await client.post("/api/briefing/feeds", json=payload)
-
-
-async def remove_rss_feed(client: FableClient, *, feed_id: int) -> dict[str, Any]:
-    """Remove an RSS feed by ID."""
-    return await client.delete(f"/api/briefing/feeds/{feed_id}")

fable-mcp/fable_mcp/tools/chat.py

@@ -1,75 +0,0 @@
-"""MCP tools for Fable chat — create conversations and stream responses."""
-from __future__ import annotations
-
-import json
-from typing import Any
-
-from fable_mcp.client import FableClient
-
-
-async def list_conversations(
-    client: FableClient,
-    *,
-    limit: int = 20,
-    offset: int = 0,
-) -> dict[str, Any]:
-    """List MCP chat conversations."""
-    params: dict[str, Any] = {"limit": limit, "offset": offset, "type": "mcp"}
-    return await client.get("/api/chat/conversations", params=params)
-
-
-async def send_message(
-    client: FableClient,
-    *,
-    message: str,
-    conversation_id: str | None = None,
-    think: bool = False,
-) -> dict[str, Any]:
-    """Send a message to Fable and return the full assistant response.
-
-    Creates a new MCP conversation if conversation_id is None.
-    Streams the SSE response and accumulates token chunks into a single string.
-
-    Returns:
-        Dict with:
-          - "conversation_id": str
-          - "response": str (full assistant message)
-          - "tool_calls": list of any tool_call events observed
-    """
-    if conversation_id is None:
-        conv = await client.post(
-            "/api/chat/conversations",
-            json={"conversation_type": "mcp"},
-        )
-        conversation_id = conv["id"]
-
-    # Build SSE stream URL with message as query param
-    params: dict[str, Any] = {"message": message}
-    if think:
-        params["think"] = "true"
-
-    tokens: list[str] = []
-    tool_calls: list[Any] = []
-
-    stream_path = f"/api/chat/conversations/{conversation_id}/stream"
-    async for raw_line in client.stream_get(stream_path, params=params):
-        if not raw_line.startswith("data: "):
-            continue
-        payload_str = raw_line[len("data: "):]
-        try:
-            event = json.loads(payload_str)
-        except json.JSONDecodeError:
-            continue
-        event_type = event.get("type")
-        if event_type == "token":
-            tokens.append(event.get("content", ""))
-        elif event_type == "tool_call":
-            tool_calls.append(event)
-        elif event_type == "done":
-            break
-
-    return {
-        "conversation_id": conversation_id,
-        "response": "".join(tokens),
-        "tool_calls": tool_calls,
-    }

fable-mcp/fable_mcp/tools/milestones.py

@@ -1,53 +0,0 @@
-"""MCP tools for Fable milestones."""
-from __future__ import annotations
-
-from typing import Any
-
-from fable_mcp.client import FableClient
-
-
-async def list_milestones(client: FableClient, *, project_id: int) -> dict[str, Any]:
-    """List milestones for a project."""
-    return await client.get(f"/api/projects/{project_id}/milestones")
-
-
-async def create_milestone(
-    client: FableClient,
-    *,
-    project_id: int,
-    title: str,
-    description: str = "",
-    status: str = "active",
-) -> dict[str, Any]:
-    """Create a milestone within a project."""
-    payload: dict[str, Any] = {
-        "title": title,
-        "description": description,
-        "status": status,
-    }
-    return await client.post(f"/api/projects/{project_id}/milestones", json=payload)
-
-
-async def update_milestone(
-    client: FableClient,
-    *,
-    project_id: int,
-    milestone_id: int,
-    title: str | None = None,
-    description: str | None = None,
-    status: str | None = None,
-    order_index: int | None = None,
-) -> dict[str, Any]:
-    """Update an existing milestone."""
-    payload: dict[str, Any] = {}
-    if title is not None:
-        payload["title"] = title
-    if description is not None:
-        payload["description"] = description
-    if status is not None:
-        payload["status"] = status
-    if order_index is not None:
-        payload["order_index"] = order_index
-    return await client.patch(
-        f"/api/projects/{project_id}/milestones/{milestone_id}", json=payload
-    )

fable-mcp/fable_mcp/tools/notes.py

@@ -1,72 +0,0 @@
-"""MCP tools for Fable notes."""
-from __future__ import annotations
-
-from typing import Any
-
-from fable_mcp.client import FableClient
-
-
-async def list_notes(
-    client: FableClient,
-    *,
-    limit: int = 20,
-    offset: int = 0,
-    tag: str | None = None,
-    search: str | None = None,
-) -> dict[str, Any]:
-    """List notes with optional filtering."""
-    params: dict[str, Any] = {"limit": limit, "offset": offset}
-    if tag:
-        params["tag"] = tag
-    if search:
-        params["search"] = search
-    return await client.get("/api/notes", params=params)
-
-
-async def get_note(client: FableClient, *, note_id: int) -> dict[str, Any]:
-    """Fetch a single note by ID."""
-    return await client.get(f"/api/notes/{note_id}")
-
-
-async def create_note(
-    client: FableClient,
-    *,
-    title: str,
-    body: str = "",
-    tags: list[str] | None = None,
-    project_id: int | None = None,
-) -> dict[str, Any]:
-    """Create a new note."""
-    payload: dict[str, Any] = {"title": title, "body": body}
-    if tags is not None:
-        payload["tags"] = tags
-    if project_id is not None:
-        payload["project_id"] = project_id
-    return await client.post("/api/notes", json=payload)
-
-
-async def update_note(
-    client: FableClient,
-    *,
-    note_id: int,
-    title: str | None = None,
-    body: str | None = None,
-    tags: list[str] | None = None,
-    project_id: int | None = None,
-) -> dict[str, Any]:
-    """Update an existing note."""
-    payload: dict[str, Any] = {}
-    if title is not None:
-        payload["title"] = title
-    if body is not None:
-        payload["body"] = body
-    if tags is not None:
-        payload["tags"] = tags
-    if project_id is not None:
-        payload["project_id"] = project_id
-    return await client.patch(f"/api/notes/{note_id}", json=payload)
-
-
-async def delete_note(client: FableClient, *, note_id: int) -> None:
-    """Delete a note by ID."""
-    await client.delete(f"/api/notes/{note_id}")

fable-mcp/fable_mcp/tools/projects.py

@@ -1,59 +0,0 @@
-"""MCP tools for Fable projects."""
-from __future__ import annotations
-
-from typing import Any
-
-from fable_mcp.client import FableClient
-
-
-async def list_projects(client: FableClient) -> dict[str, Any]:
-    """List all projects for the authenticated user."""
-    return await client.get("/api/projects")
-
-
-async def get_project(client: FableClient, *, project_id: int) -> dict[str, Any]:
-    """Fetch a project by ID (includes milestone summary)."""
-    return await client.get(f"/api/projects/{project_id}")
-
-
-async def create_project(
-    client: FableClient,
-    *,
-    title: str,
-    description: str = "",
-    goal: str | None = None,
-    status: str = "active",
-    color: str | None = None,
-) -> dict[str, Any]:
-    """Create a new project."""
-    payload: dict[str, Any] = {"title": title, "description": description, "status": status}
-    if goal is not None:
-        payload["goal"] = goal
-    if color is not None:
-        payload["color"] = color
-    return await client.post("/api/projects", json=payload)
-
-
-async def update_project(
-    client: FableClient,
-    *,
-    project_id: int,
-    title: str | None = None,
-    description: str | None = None,
-    goal: str | None = None,
-    status: str | None = None,
-    color: str | None = None,
-) -> dict[str, Any]:
-    """Update an existing project."""
-    payload: dict[str, Any] = {}
-    if title is not None:
-        payload["title"] = title
-    if description is not None:
-        payload["description"] = description
-    if goal is not None:
-        payload["goal"] = goal
-    if status is not None:
-        payload["status"] = status
-    if color is not None:
-        payload["color"] = color
-    return await client.patch(f"/api/projects/{project_id}", json=payload)

fable-mcp/fable_mcp/tools/search.py

@@ -1,30 +0,0 @@
-"""MCP tool for semantic search across Fable notes and tasks."""
-from __future__ import annotations
-
-from typing import Any
-
-from fable_mcp.client import FableClient
-
-
-async def search(
-    client: FableClient,
-    *,
-    q: str,
-    content_type: str = "all",
-    limit: int = 10,
-) -> dict[str, Any]:
-    """Semantic search over notes and/or tasks.
-
-    Args:
-        q: Search query string.
-        content_type: One of "note", "task", or "all" (default).
-        limit: Maximum number of results to return.
-
-    Returns:
-        Dict with "results" list and "total" count.
-        Each result has: id, title, body, is_task, tags, similarity.
-    """
-    params: dict[str, Any] = {"q": q, "limit": limit}
-    if content_type != "all":
-        params["content_type"] = content_type
-    return await client.get("/api/search", params=params)

fable-mcp/fable_mcp/tools/tasks.py

@@ -1,93 +0,0 @@
-"""MCP tools for Fable tasks."""
-from __future__ import annotations
-
-from typing import Any
-
-from fable_mcp.client import FableClient
-
-
-async def list_tasks(
-    client: FableClient,
-    *,
-    limit: int = 20,
-    offset: int = 0,
-    status: str | None = None,
-    project_id: int | None = None,
-) -> dict[str, Any]:
-    """List tasks with optional filtering."""
-    params: dict[str, Any] = {"limit": limit, "offset": offset}
-    if status:
-        params["status"] = status
-    if project_id is not None:
-        params["project_id"] = project_id
-    return await client.get("/api/tasks", params=params)
-
-
-async def get_task(client: FableClient, *, task_id: int) -> dict[str, Any]:
-    """Fetch a single task by ID (includes parent_title)."""
-    return await client.get(f"/api/tasks/{task_id}")
-
-
-async def create_task(
-    client: FableClient,
-    *,
-    title: str,
-    body: str = "",
-    status: str = "todo",
-    priority: str | None = None,
-    project_id: int | None = None,
-    milestone_id: int | None = None,
-    parent_id: int | None = None,
-    tags: list[str] | None = None,
-) -> dict[str, Any]:
-    """Create a new task."""
-    payload: dict[str, Any] = {"title": title, "body": body, "status": status}
-    if priority is not None:
-        payload["priority"] = priority
-    if project_id is not None:
-        payload["project_id"] = project_id
-    if milestone_id is not None:
-        payload["milestone_id"] = milestone_id
-    if parent_id is not None:
-        payload["parent_id"] = parent_id
-    if tags is not None:
-        payload["tags"] = tags
-    return await client.post("/api/tasks", json=payload)
-
-
-async def update_task(
-    client: FableClient,
-    *,
-    task_id: int,
-    title: str | None = None,
-    body: str | None = None,
-    status: str | None = None,
-    priority: str | None = None,
-    project_id: int | None = None,
-    milestone_id: int | None = None,
-) -> dict[str, Any]:
-    """Update an existing task."""
-    payload: dict[str, Any] = {}
-    if title is not None:
-        payload["title"] = title
-    if body is not None:
-        payload["body"] = body
-    if status is not None:
-        payload["status"] = status
-    if priority is not None:
-        payload["priority"] = priority
-    if project_id is not None:
-        payload["project_id"] = project_id
-    if milestone_id is not None:
-        payload["milestone_id"] = milestone_id
-    return await client.patch(f"/api/tasks/{task_id}", json=payload)
-
-
-async def add_task_log(
-    client: FableClient,
-    *,
-    task_id: int,
-    body: str,
-) -> dict[str, Any]:
-    """Append a log entry to a task."""
-    return await client.post(f"/api/tasks/{task_id}/logs", json={"body": body})

fable-mcp/pyproject.toml

@@ -1,24 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "fable-mcp"
-version = "0.1.0"
-description = "MCP server for Fabled Assistant"
-requires-python = ">=3.12"
-dependencies = [
-  "mcp[cli]>=1.0",
-  "httpx>=0.27",
-  "python-dotenv>=1.0",
-]
-
-[project.scripts]
-fable-mcp = "fable_mcp.server:main"
-
-[project.optional-dependencies]
-dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21"]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]

fable-mcp/tests/conftest.py

@@ -1,12 +0,0 @@
-"""Shared pytest fixtures for fable-mcp tests."""
-from unittest.mock import AsyncMock, MagicMock
-import pytest
-
-
-@pytest.fixture
-def mock_client():
-    """A mock FableClient that returns empty responses by default."""
-    client = AsyncMock()
-    client.__aenter__ = AsyncMock(return_value=client)
-    client.__aexit__ = AsyncMock(return_value=False)
-    return client

fable-mcp/tests/test_client.py

@@ -1,142 +0,0 @@
-"""Tests for FableClient."""
-import os
-import pytest
-import respx
-import httpx
-from unittest.mock import patch
-
-from fable_mcp.client import FableClient, FableAPIError, get_client, init_client, _reset_client
-
-
-@pytest.fixture(autouse=True)
-def reset_singleton():
-    """Reset the module-level client singleton between tests."""
-    _reset_client()
-    yield
-    _reset_client()
-
-
-@pytest.fixture
-def base_env(monkeypatch):
-    monkeypatch.setenv("FABLE_URL", "http://fable.test")
-    monkeypatch.setenv("FABLE_API_KEY", "fmcp_testkey")
-
-
-class TestFableClientInit:
-    def test_missing_fable_url_raises(self, monkeypatch):
-        monkeypatch.delenv("FABLE_URL", raising=False)
-        monkeypatch.setenv("FABLE_API_KEY", "fmcp_testkey")
-        with pytest.raises(ValueError, match="FABLE_URL"):
-            FableClient()
-
-    def test_missing_api_key_raises(self, monkeypatch):
-        monkeypatch.setenv("FABLE_URL", "http://fable.test")
-        monkeypatch.delenv("FABLE_API_KEY", raising=False)
-        with pytest.raises(ValueError, match="FABLE_API_KEY"):
-            FableClient()
-
-    def test_trailing_slash_stripped(self, base_env):
-        with patch.dict(os.environ, {"FABLE_URL": "http://fable.test/"}):
-            client = FableClient()
-            assert client.base_url == "http://fable.test"
-
-    def test_auth_header_set(self, base_env):
-        client = FableClient()
-        assert client._headers["Authorization"] == "Bearer fmcp_testkey"
-
-
-class TestFableClientHTTP:
-    @respx.mock
-    @pytest.mark.asyncio
-    async def test_get_returns_json(self, base_env):
-        respx.get("http://fable.test/api/notes").mock(
-            return_value=httpx.Response(200, json={"notes": []})
-        )
-        async with FableClient() as client:
-            data = await client.get("/api/notes")
-        assert data == {"notes": []}
-
-    @respx.mock
-    @pytest.mark.asyncio
-    async def test_non_2xx_raises_fable_api_error(self, base_env):
-        respx.get("http://fable.test/api/notes").mock(
-            return_value=httpx.Response(401, json={"error": "Unauthorized"})
-        )
-        async with FableClient() as client:
-            with pytest.raises(FableAPIError) as exc_info:
-                await client.get("/api/notes")
-        assert exc_info.value.status_code == 401
-
-    @respx.mock
-    @pytest.mark.asyncio
-    async def test_post_sends_json(self, base_env):
-        respx.post("http://fable.test/api/notes").mock(
-            return_value=httpx.Response(201, json={"id": 1, "title": "Test"})
-        )
-        async with FableClient() as client:
-            data = await client.post("/api/notes", json={"title": "Test"})
-        assert data["id"] == 1
-
-    @respx.mock
-    @pytest.mark.asyncio
-    async def test_patch_sends_json(self, base_env):
-        respx.patch("http://fable.test/api/notes/1").mock(
-            return_value=httpx.Response(200, json={"id": 1, "title": "Updated"})
-        )
-        async with FableClient() as client:
-            data = await client.patch("/api/notes/1", json={"title": "Updated"})
-        assert data["title"] == "Updated"
-
-    @respx.mock
-    @pytest.mark.asyncio
-    async def test_delete_returns_none_on_204(self, base_env):
-        respx.delete("http://fable.test/api/notes/1").mock(
-            return_value=httpx.Response(204)
-        )
-        async with FableClient() as client:
-            result = await client.delete("/api/notes/1")
-        assert result is None
-
-    @respx.mock
-    @pytest.mark.asyncio
-    async def test_fable_api_error_includes_message(self, base_env):
-        respx.get("http://fable.test/api/notes").mock(
-            return_value=httpx.Response(404, json={"error": "Not found"})
-        )
-        async with FableClient() as client:
-            with pytest.raises(FableAPIError) as exc_info:
-                await client.get("/api/notes")
-        assert "Not found" in str(exc_info.value)
-        assert exc_info.value.status_code == 404
-
-
-class TestSingleton:
-    def test_get_client_before_init_raises(self):
-        with pytest.raises(RuntimeError, match="init_client"):
-            get_client()
-
-    def test_init_client_returns_instance(self, base_env):
-        client = init_client()
-        assert isinstance(client, FableClient)
-
-    def test_get_client_after_init_returns_same(self, base_env):
-        init_client()
-        c1 = get_client()
-        c2 = get_client()
-        assert c1 is c2
-
-
-class TestStreamGet:
-    @respx.mock
-    @pytest.mark.asyncio
-    async def test_stream_get_yields_lines(self, base_env):
-        sse_body = b"data: line1\n\ndata: line2\n\n"
-        respx.get("http://fable.test/api/stream").mock(
-            return_value=httpx.Response(200, content=sse_body)
-        )
-        lines = []
-        async with FableClient() as client:
-            async for line in client.stream_get("/api/stream"):
-                lines.append(line)
-        assert "data: line1" in lines
-        assert "data: line2" in lines

fable-mcp/tests/test_tools_chat.py

@@ -1,58 +0,0 @@
-"""Tests for chat MCP tools."""
-import json
-import pytest
-from unittest.mock import AsyncMock, MagicMock, patch
-
-
-@pytest.fixture
-def client(mock_client):
-    return mock_client
-
-
-@pytest.mark.asyncio
-async def test_send_message_creates_conversation_and_streams(client):
-    from fable_mcp.tools.chat import send_message
-
-    client.post = AsyncMock(return_value={"id": "conv-1"})
-
-    async def fake_stream(path, **kwargs):
-        for line in [
-            'data: {"type": "token", "content": "Hello"}',
-            'data: {"type": "token", "content": " world"}',
-            'data: {"type": "done"}',
-        ]:
-            yield line
-
-    client.stream_get = fake_stream
-
-    result = await send_message(client, message="Hi", conversation_id=None)
-    assert result["conversation_id"] == "conv-1"
-    assert "Hello world" in result["response"]
-
-
-@pytest.mark.asyncio
-async def test_send_message_reuses_existing_conversation(client):
-    from fable_mcp.tools.chat import send_message
-
-    async def fake_stream(path, **kwargs):
-        for line in [
-            'data: {"type": "token", "content": "Reply"}',
-            'data: {"type": "done"}',
-        ]:
-            yield line
-
-    client.stream_get = fake_stream
-
-    result = await send_message(client, message="Hi", conversation_id="existing-conv")
-    # Should not call post to create a conversation
-    client.post.assert_not_called()
-    assert result["conversation_id"] == "existing-conv"
-
-
-@pytest.mark.asyncio
-async def test_list_conversations_calls_get(client):
-    from fable_mcp.tools.chat import list_conversations
-    client.get = AsyncMock(return_value={"conversations": []})
-    await list_conversations(client)
-    client.get.assert_called_once()
-    assert "/api/chat/conversations" in client.get.call_args[0][0]

fable-mcp/tests/test_tools_milestones.py

@@ -1,35 +0,0 @@
-"""Tests for milestones MCP tools."""
-import pytest
-from unittest.mock import AsyncMock
-
-
-@pytest.fixture
-def client(mock_client):
-    return mock_client
-
-
-@pytest.mark.asyncio
-async def test_list_milestones_calls_correct_endpoint(client):
-    from fable_mcp.tools.milestones import list_milestones
-    client.get = AsyncMock(return_value={"milestones": []})
-    await list_milestones(client, project_id=3)
-    client.get.assert_called_once_with("/api/projects/3/milestones")
-
-
-@pytest.mark.asyncio
-async def test_create_milestone_posts_to_project_endpoint(client):
-    from fable_mcp.tools.milestones import create_milestone
-    client.post = AsyncMock(return_value={"id": 10, "title": "M1"})
-    await create_milestone(client, project_id=3, title="M1")
-    path = client.post.call_args[0][0]
-    assert path == "/api/projects/3/milestones"
-    assert client.post.call_args[1]["json"]["title"] == "M1"
-
-
-@pytest.mark.asyncio
-async def test_update_milestone_patches(client):
-    from fable_mcp.tools.milestones import update_milestone
-    client.patch = AsyncMock(return_value={"id": 10, "status": "completed"})
-    await update_milestone(client, project_id=3, milestone_id=10, status="completed")
-    path = client.patch.call_args[0][0]
-    assert "/api/projects/3/milestones/10" in path

fable-mcp/tests/test_tools_notes.py

@@ -1,56 +0,0 @@
-"""Tests for notes MCP tools."""
-import pytest
-from unittest.mock import AsyncMock
-
-
-@pytest.fixture
-def client(mock_client):
-    return mock_client
-
-
-@pytest.mark.asyncio
-async def test_list_notes_calls_get(client):
-    from fable_mcp.tools.notes import list_notes
-    client.get = AsyncMock(return_value={"notes": [], "total": 0})
-    result = await list_notes(client, limit=10)
-    client.get.assert_called_once()
-    call_args = client.get.call_args
-    assert "/api/notes" in call_args[0][0]
-
-
-@pytest.mark.asyncio
-async def test_get_note_calls_correct_endpoint(client):
-    from fable_mcp.tools.notes import get_note
-    client.get = AsyncMock(return_value={"id": 42, "title": "Hello"})
-    result = await get_note(client, note_id=42)
-    client.get.assert_called_once_with("/api/notes/42")
-    assert result["id"] == 42
-
-
-@pytest.mark.asyncio
-async def test_create_note_posts_payload(client):
-    from fable_mcp.tools.notes import create_note
-    client.post = AsyncMock(return_value={"id": 1, "title": "My Note"})
-    result = await create_note(client, title="My Note", body="Content")
-    client.post.assert_called_once()
-    call_kwargs = client.post.call_args[1]
-    assert call_kwargs["json"]["title"] == "My Note"
-    assert call_kwargs["json"]["body"] == "Content"
-
-
-@pytest.mark.asyncio
-async def test_update_note_patches_payload(client):
-    from fable_mcp.tools.notes import update_note
-    client.patch = AsyncMock(return_value={"id": 1, "title": "Updated"})
-    result = await update_note(client, note_id=1, title="Updated")
-    client.patch.assert_called_once()
-    path = client.patch.call_args[0][0]
-    assert "/api/notes/1" in path
-
-
-@pytest.mark.asyncio
-async def test_delete_note_calls_delete(client):
-    from fable_mcp.tools.notes import delete_note
-    client.delete = AsyncMock(return_value=None)
-    await delete_note(client, note_id=5)
-    client.delete.assert_called_once_with("/api/notes/5")

fable-mcp/tests/test_tools_projects.py

@@ -1,42 +0,0 @@
-"""Tests for projects MCP tools."""
-import pytest
-from unittest.mock import AsyncMock
-
-
-@pytest.fixture
-def client(mock_client):
-    return mock_client
-
-
-@pytest.mark.asyncio
-async def test_list_projects_calls_get(client):
-    from fable_mcp.tools.projects import list_projects
-    client.get = AsyncMock(return_value={"projects": []})
-    await list_projects(client)
-    client.get.assert_called_once_with("/api/projects")
-
-
-@pytest.mark.asyncio
-async def test_get_project_calls_correct_endpoint(client):
-    from fable_mcp.tools.projects import get_project
-    client.get = AsyncMock(return_value={"id": 2, "title": "Proj"})
-    result = await get_project(client, project_id=2)
-    client.get.assert_called_once_with("/api/projects/2")
-
-
-@pytest.mark.asyncio
-async def test_create_project_posts_payload(client):
-    from fable_mcp.tools.projects import create_project
-    client.post = AsyncMock(return_value={"id": 4, "title": "New"})
-    await create_project(client, title="New", description="Desc")
-    call_kwargs = client.post.call_args[1]
-    assert call_kwargs["json"]["title"] == "New"
-    assert call_kwargs["json"]["description"] == "Desc"
-
-
-@pytest.mark.asyncio
-async def test_update_project_patches(client):
-    from fable_mcp.tools.projects import update_project
-    client.patch = AsyncMock(return_value={"id": 4, "status": "active"})
-    await update_project(client, project_id=4, status="active")
-    assert "/api/projects/4" in client.patch.call_args[0][0]

fable-mcp/tests/test_tools_tasks.py

@@ -1,54 +0,0 @@
-"""Tests for tasks MCP tools."""
-import pytest
-from unittest.mock import AsyncMock
-
-
-@pytest.fixture
-def client(mock_client):
-    return mock_client
-
-
-@pytest.mark.asyncio
-async def test_list_tasks_calls_get(client):
-    from fable_mcp.tools.tasks import list_tasks
-    client.get = AsyncMock(return_value={"tasks": [], "total": 0})
-    await list_tasks(client)
-    client.get.assert_called_once()
-    assert "/api/tasks" in client.get.call_args[0][0]
-
-
-@pytest.mark.asyncio
-async def test_get_task_calls_correct_endpoint(client):
-    from fable_mcp.tools.tasks import get_task
-    client.get = AsyncMock(return_value={"id": 7, "title": "Fix bug"})
-    result = await get_task(client, task_id=7)
-    client.get.assert_called_once_with("/api/tasks/7")
-
-
-@pytest.mark.asyncio
-async def test_create_task_posts_payload(client):
-    from fable_mcp.tools.tasks import create_task
-    client.post = AsyncMock(return_value={"id": 3, "title": "New task"})
-    await create_task(client, title="New task")
-    call_kwargs = client.post.call_args[1]
-    assert call_kwargs["json"]["title"] == "New task"
-
-
-@pytest.mark.asyncio
-async def test_update_task_patches(client):
-    from fable_mcp.tools.tasks import update_task
-    client.patch = AsyncMock(return_value={"id": 3, "status": "done"})
-    await update_task(client, task_id=3, status="done")
-    client.patch.assert_called_once()
-    assert "/api/tasks/3" in client.patch.call_args[0][0]
-
-
-@pytest.mark.asyncio
-async def test_add_task_log_posts_to_logs_endpoint(client):
-    from fable_mcp.tools.tasks import add_task_log
-    client.post = AsyncMock(return_value={"id": 1, "body": "progress"})
-    await add_task_log(client, task_id=9, body="progress")
-    client.post.assert_called_once()
-    path = client.post.call_args[0][0]
-    assert path == "/api/tasks/9/logs"
-    assert client.post.call_args[1]["json"]["body"] == "progress"

frontend/index.html

@@ -9,8 +9,8 @@
     <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="Fabled">
-    <title>Fabled Assistant</title>
+    <meta name="apple-mobile-web-app-title" content="Scribe">
+    <title>Fabled Scribe</title>
   </head>
   <body>
     <div id="app"></div>

frontend/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "fabledassistant-frontend",
+  "name": "scribe-frontend",
   "private": true,
   "version": "0.1.0",
   "type": "module",
@@ -14,6 +14,7 @@
     "@fullcalendar/interaction": "^6.1.20",
     "@fullcalendar/timegrid": "^6.1.20",
     "@fullcalendar/vue3": "^6.1.20",
+    "@ricky0123/vad-web": "^0.0.30",
     "@tiptap/core": "^3.0.0",
     "@tiptap/extension-link": "^3.0.0",
     "@tiptap/extension-list": "^3.0.0",
@@ -24,6 +25,7 @@
     "@tiptap/vue-3": "^3.0.0",
     "d3": "^7",
     "dompurify": "^3.1.0",
+    "lucide-vue-next": "^0.469.0",
     "marked": "^17.0.0",
     "pinia": "^3.0.0",
     "vue": "3.5.30",
@@ -35,6 +37,7 @@
     "@vitejs/plugin-vue": "^6.0.0",
     "typescript": "~5.9.0",
     "vite": "^7.0.0",
+    "vite-plugin-static-copy": "^4.0.1",
     "vue-tsc": "^3.0.0"
   }
 }

frontend/public/manifest.json

@@ -1,6 +1,6 @@
 {
-  "name": "Fabled Assistant",
-  "short_name": "Fabled",
+  "name": "Fabled Scribe",
+  "short_name": "Scribe",
   "description": "Your self-hosted second brain with AI assistance",
   "start_url": "/",
   "display": "standalone",

frontend/public/sw.js

@@ -1,45 +1,11 @@
-// Service Worker for push notifications and PWA support
-self.addEventListener('push', event => {
-  if (!event.data) return;
-  const data = event.data.json();
-  const notifUrl = data.url || '/';
+// Service Worker — PWA installability shell only.
+//
+// The push and notificationclick listeners were removed alongside the chat
+// generation pipeline (they only fired when the internal LLM finished a
+// response). The empty fetch handler is preserved as the installability
+// surface required for "Add to Home Screen" in some browsers; offline
+// caching is intentionally not implemented yet.
 
-  event.waitUntil(
-    clients.matchAll({ type: 'window', includeUncontrolled: true }).then(clientList => {
-      // Suppress notification if the user already has the relevant page focused
-      for (const client of clientList) {
-        if (client.visibilityState === 'visible' && client.url.includes(notifUrl)) {
-          return;
-        }
-      }
-      return self.registration.showNotification(data.title || 'Fabled Assistant', {
-        body: data.body || '',
-        icon: '/favicon.ico',
-        badge: '/favicon.ico',
-        data: { url: notifUrl },
-      });
-    })
-  );
-});
-
-self.addEventListener('notificationclick', event => {
-  event.notification.close();
-  event.waitUntil(
-    clients.matchAll({ type: 'window', includeUncontrolled: true }).then(clientList => {
-      const url = event.notification.data.url;
-      for (const client of clientList) {
-        if (client.url.includes(url) && 'focus' in client) {
-          return client.focus();
-        }
-      }
-      if (clients.openWindow) {
-        return clients.openWindow(url);
-      }
-    })
-  );
-});
-
-// PWA: serve cached assets for offline support (minimal)
-self.addEventListener('fetch', event => {
+self.addEventListener('fetch', () => {
   // Pass-through — no offline caching in v1
 });

frontend/src/App.vue

@@ -6,7 +6,6 @@ import ToastNotification from "@/components/ToastNotification.vue";
 import { useTheme } from "@/composables/useTheme";
 import { useShortcuts } from "@/composables/useShortcuts";
 import { useAuthStore } from "@/stores/auth";
-import { useChatStore } from "@/stores/chat";
 import { useSettingsStore } from "@/stores/settings";
 import { apiGet, apiPut } from "@/api/client";
 
@@ -15,19 +14,17 @@ useTheme();
 const router = useRouter();
 const appVersion = ref("dev");
 const authStore = useAuthStore();
-const chatStore = useChatStore();
 const settingsStore = useSettingsStore();
 const { showShortcuts, toggleShortcuts, closeShortcuts } = useShortcuts();
 
 function startAppServices() {
-  chatStore.startStatusPolling();
   settingsStore.fetchSettings();
   // Sync browser timezone to the server on every login/page load.
   apiPut("/api/settings", { user_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone }).catch(() => {});
 }
 
 function stopAppServices() {
-  chatStore.stopStatusPolling();
+  // no-op for now; kept as a hook for future per-session teardown
 }
 
 function isInputActive(): boolean {
@@ -80,11 +77,11 @@ function onGlobalKeydown(e: KeyboardEvent) {
     switch (e.key) {
       case "h": router.push("/"); break;
       case "n": router.push("/notes"); break;
-      case "t": router.push("/tasks"); break;
+      case "t": router.push("/"); break;
       case "p": router.push("/projects"); break;
-      case "c": router.push("/chat"); break;
+      case "r": router.push("/rules"); break;
       case "g": router.push("/graph"); break;
-      case "l": router.push("/calendar"); break;
+      case "x": router.push("/trash"); break;
     }
     return;
   }
@@ -112,13 +109,6 @@ function onGlobalKeydown(e: KeyboardEvent) {
       e.preventDefault();
       document.dispatchEvent(new CustomEvent("shortcut:focus-search"));
       break;
-    case "c":
-      if (router.currentRoute.value.name === "home") {
-        document.dispatchEvent(new CustomEvent("shortcut:focus-chat"));
-      } else {
-        router.push("/chat");
-      }
-      break;
   }
 }
 
@@ -191,7 +181,7 @@ onUnmounted(() => {
                 <kbd class="shortcut-key">g</kbd>
                 <span class="shortcut-key-sep">+</span>
                 <kbd class="shortcut-key">t</kbd>
-                <span class="shortcut-desc">Tasks</span>
+                <span class="shortcut-desc">Knowledge (tasks)</span>
               </div>
               <div class="shortcut-row">
                 <kbd class="shortcut-key">g</kbd>
@@ -202,14 +192,8 @@ onUnmounted(() => {
               <div class="shortcut-row">
                 <kbd class="shortcut-key">g</kbd>
                 <span class="shortcut-key-sep">+</span>
-                <kbd class="shortcut-key">c</kbd>
-                <span class="shortcut-desc">Chat</span>
-              </div>
-              <div class="shortcut-row">
-                <kbd class="shortcut-key">g</kbd>
-                <span class="shortcut-key-sep">+</span>
-                <kbd class="shortcut-key">l</kbd>
-                <span class="shortcut-desc">Calendar</span>
+                <kbd class="shortcut-key">x</kbd>
+                <span class="shortcut-desc">Trash</span>
               </div>
               <div class="shortcut-row">
                 <kbd class="shortcut-key">Esc</kbd>
@@ -252,23 +236,6 @@ onUnmounted(() => {
                 <span class="shortcut-desc">Edit current item (viewer)</span>
               </div>
             </div>
-            <div class="shortcuts-section">
-              <div class="shortcuts-section-title">Chat</div>
-              <div class="shortcut-row">
-                <kbd class="shortcut-key">c</kbd>
-                <span class="shortcut-desc">Focus chat (home) / go to chat</span>
-              </div>
-              <div class="shortcut-row">
-                <kbd class="shortcut-key">Enter</kbd>
-                <span class="shortcut-desc">Send message</span>
-              </div>
-              <div class="shortcut-row">
-                <kbd class="shortcut-key">Shift</kbd>
-                <span class="shortcut-key-sep">+</span>
-                <kbd class="shortcut-key">Enter</kbd>
-                <span class="shortcut-desc">New line</span>
-              </div>
-            </div>
           </div>
         </div>
       </div>
@@ -288,7 +255,7 @@ onUnmounted(() => {
   z-index: 9999;
   padding: 0.4rem 0.75rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-radius: 0 0 4px 4px;
   font-size: 0.875rem;
   text-decoration: none;
@@ -313,7 +280,7 @@ onUnmounted(() => {
   min-height: 0;
   overflow-y: auto;
 }
-.app-content:has(.workspace-root) {
+.app-content:has(.knowledge-root) {
   overflow: hidden;
 }