chore(spike): recover the /bygge toolchain from tmpfs (#28)

analyze_srt.py, build_page.py and transcode.yaml produced the /bygge
prototype. They were sitting in a session scratchpad on tmpfs, one reboot
from gone, while spike issues #29-#31 were written as if they had to be
built from scratch.

Committed as found, defects documented rather than fixed: max_tokens=6000
truncates anything past ~6 minutes of audio, the page title is hardcoded,
and the schema still carries fields no consumer renders.

The four-check validator is the part worth keeping — the coverage-gap and
Swedish-number-grounding checks catch errors that timestamp and citation
checks structurally cannot.

Real transcripts and analyses stay out: this repo is public and the
recordings are a named person discussing a client's project. Only the
synthetic fixture is committed, which exercises all four checks with no
model call.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BeAp5LTscnz2W7Ubt4eJ6m

.env.example

@@ -51,6 +51,24 @@ TAPIR_POLL_INTERVAL=
 # caption endpoint; after it expires the video is retried. 0 = always retry.
 # Go duration; default 1h.
 TAPIR_FETCH_BACKOFF=
+# Recency bound for AUTO summarization: in automatic mode only videos published
+# within this window of now are summarized; older ones are discovered + listed
+# but wait for a manual "Summarize" (so a back-catalogue doesn't self-inflict
+# 429s). An explicit request bypasses it. Go duration; default 168h (~7d).
+# 0 = no bound (summarize every unseen video).
+TAPIR_AUTO_SUMMARIZE_WINDOW=
+# Minimum interval between outbound caption fetches across the WHOLE process —
+# the shared per-egress-IP rate gate (ADR-014). Scheduler runners and the web
+# "Summarize" click-path serialise through it so they cannot collectively trip
+# 429s. Go duration; default 2s. 0 = unlimited (dev/tests).
+TAPIR_FETCH_RATE=
+
+# --- scheduled discovery (tapir serve, ADR-018) ---------------------------
+# When > 0, `serve` runs in-process discovery for ALL users on this cadence
+# (e.g. 2h): one runner pass per user per tick, run-once-on-startup then ticked.
+# Empty/0 = disabled (dev/tests never auto-fetch). SINGLE-REPLICA assumption —
+# >1 replica double-runs discovery. Go duration.
+TAPIR_DISCOVERY_INTERVAL=
 
 # --- invitations (tapir invite) -------------------------------------------
 # Public base URL used to build the invite link `tapir invite <email>` prints.

.gitea/workflows/ci.yml

@@ -78,16 +78,148 @@ jobs:
               ${REGISTRY}/${{ env.IMAGE }}:${{ steps.meta.outputs.version-tag }} || true
           echo "Image pushed to ${REF}"
 
+      # Run the just-built local image briefly via buildah, not k3s ctr —
+      # avoids sudo/host-containerd access so this still works once the
+      # runner itself is containerized (infra#132). Tests the local
+      # buildah-store image directly, no registry round-trip needed.
+      #
+      # Bare `/tapir` (no subcommand) runs the long-running server, same as
+      # the old ctr-based smoke test -- ctr's --rm reliably force-killed it,
+      # but a plain `timeout N buildah run` does NOT: it only signals the
+      # `buildah run` wrapper, and the actual container process can survive
+      # that and keep the output pipe open, hanging the whole job (hit this
+      # live: 14min hang, infra#132). Backgrounding the run + `buildah rm -f`
+      # decouples "is the script blocked" from "did the process exit" --
+      # rm -f forcibly tears down the container regardless of wrapper state.
       - name: Smoke test
         run: |
           REGISTRY="localhost:5000"
           REF="${REGISTRY}/${{ env.IMAGE }}:${{ steps.meta.outputs.sha-tag }}"
-          CNAME="smoke-${{ steps.meta.outputs.sha-tag }}"
-          sudo k3s ctr images pull --plain-http ${REF}
-          OUTPUT=$(timeout 5 sudo k3s ctr run --rm ${REF} ${CNAME} /tapir 2>&1 || true)
-          sudo k3s ctr containers delete ${CNAME} 2>/dev/null || true
+          CONTAINER=$(buildah from ${REF})
+          LOG=$(mktemp)
+          buildah run "$CONTAINER" -- /tapir > "$LOG" 2>&1 &
+          RUNPID=$!
+          sleep 5
+          kill -9 "$RUNPID" 2>/dev/null || true
+          wait "$RUNPID" 2>/dev/null || true
+          buildah rm -f "$CONTAINER" >/dev/null 2>&1 || true
+          OUTPUT=$(cat "$LOG"); rm -f "$LOG"
           echo "$OUTPUT" | grep -q "tapir" \
             && echo "Smoke test passed" \
             || echo "Smoke test inconclusive: $OUTPUT"
 
-  # ── 3. Mirror to GitHub — skipped for now (SSH key rotation pending) ─
+  # ── 3. Deploy via infra repo + Flux ─────────────────────────────────────────
+  # Flux native image-automation can't scan localhost:5000 from inside k3s pods
+  # (mathias/infra k3s/flux/flux-system/image-automation.yaml) — this job
+  # mirrors cobalt-dingo's proven pattern instead: patch the infra repo's
+  # manifest directly on every push to main, then annotate Flux for a fast
+  # reconcile. Fixes infra#111 (image built+pushed but manifest bump was
+  # manual, so merged features silently didn't deploy).
+  deploy:
+    name: Deploy via GitOps
+    needs: build
+    runs-on: self-hosted
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment: staging
+    steps:
+      - name: Update image tag in infra repo
+        env:
+          IMAGE_TAG: ${{ needs.build.outputs.image-tag }}
+          DEPLOY_KEY: ${{ secrets.INFRA_DEPLOY_KEY }}
+        run: |
+          set -euo pipefail
+
+          # INFRA_DEPLOY_KEY is a Gitea org secret (mathias org), already
+          # configured per docs/cd-pipeline.md in the infra repo — same key
+          # cobalt-dingo and brain-gardener use, no new secret needed.
+          mkdir -p ~/.ssh
+          echo "$DEPLOY_KEY" > ~/.ssh/id_infra
+          chmod 600 ~/.ssh/id_infra
+          ssh-keyscan -p 30022 10.0.1.20 >> ~/.ssh/known_hosts 2>/dev/null
+
+          export GIT_SSH_COMMAND="ssh -i ~/.ssh/id_infra -o IdentitiesOnly=yes"
+          rm -rf /tmp/infra
+          git clone -b main ssh://git@10.0.1.20:30022/mathias/infra.git /tmp/infra
+          cd /tmp/infra
+
+          DEPLOYMENT="k3s/apps/tapir/deployment.yaml"
+          # In-place update of the image tag. sed (not yq) so we don't
+          # depend on additional tooling on the runner — same as cobalt-dingo.
+          sed -i "s|image: localhost:5000/tapir:.*|image: localhost:5000/tapir:${IMAGE_TAG}|" "$DEPLOYMENT"
+
+          # Verify the patch took effect.
+          grep -q "localhost:5000/tapir:${IMAGE_TAG}" "$DEPLOYMENT" \
+            || { echo "✗ image tag patch failed"; exit 1; }
+
+          if git diff --quiet "$DEPLOYMENT"; then
+            echo "ℹ image tag unchanged — skipping push"
+          else
+            git -c user.name="tapir CI" \
+                -c user.email="ci@tapir.local" \
+                commit -m "chore(deploy): tapir → ${IMAGE_TAG}" "$DEPLOYMENT"
+            git push origin main
+            echo "✓ pushed to infra repo"
+          fi
+
+          shred -u ~/.ssh/id_infra
+
+      - name: Trigger Flux reconcile (immediate)
+        run: |
+          # Without these annotations, Flux would still pick up the change
+          # within 30s (the apps Kustomization interval). The annotations
+          # cut latency to ~1s.
+          kubectl -n flux-system annotate gitrepository flux-system \
+            reconcile.fluxcd.io/requestedAt="$(date +%s)" --overwrite
+          kubectl -n flux-system annotate kustomization apps \
+            reconcile.fluxcd.io/requestedAt="$(date +%s)" --overwrite
+
+      - name: Wait for Flux to apply new image
+        env:
+          IMAGE_TAG: ${{ needs.build.outputs.image-tag }}
+        run: |
+          # Poll the Deployment spec until it reflects the new tag.
+          # Bound to 60s so a stuck Flux doesn't hang CI.
+          EXPECTED="localhost:5000/tapir:${IMAGE_TAG}"
+          for i in $(seq 1 60); do
+            CURRENT=$(kubectl get deploy tapir -n tapir \
+              -o jsonpath='{.spec.template.spec.containers[0].image}' 2>/dev/null || echo "")
+            if [ "$CURRENT" = "$EXPECTED" ]; then
+              echo "✓ Flux applied new image after ${i}s"
+              break
+            fi
+            sleep 1
+          done
+          # Final assertion (in case the loop exited without matching).
+          kubectl get deploy tapir -n tapir \
+            -o jsonpath='{.spec.template.spec.containers[0].image}' \
+            | grep -qx "$EXPECTED" \
+            || { echo "✗ Flux did not apply new image within 60s"; exit 1; }
+
+      - name: Verify rollout
+        run: |
+          kubectl rollout status deployment/tapir \
+            --namespace tapir \
+            --timeout=120s \
+          || {
+            echo "── pod status ──"
+            kubectl get pods -n tapir -o wide
+            echo "── events ──"
+            kubectl get events -n tapir --sort-by='.lastTimestamp' | tail -20
+            echo "── describe ──"
+            kubectl describe pods -n tapir -l app=tapir | tail -40
+            exit 1
+          }
+
+      - name: Confirm pod running new image
+        env:
+          IMAGE_TAG: ${{ needs.build.outputs.image-tag }}
+        run: |
+          kubectl get pods -n tapir \
+            -l app=tapir \
+            --field-selector=status.phase=Running \
+            -o jsonpath='{.items[*].spec.containers[0].image}' \
+          | grep -q "localhost:5000/tapir:${IMAGE_TAG}" \
+          && echo "✓ pod running new image" \
+          || { echo "✗ pod image mismatch"; exit 1; }
+
+  # ── 4. Mirror to GitHub — skipped for now (SSH key rotation pending) ─

.gitignore

@@ -11,3 +11,14 @@
 .env.*
 !.env.example
 *.local
+
+# Spike media (#28): real recordings, their transcripts and derived analyses are
+# private third-party content and this repo is public. Only synthetic fixtures
+# are committed — see scripts/spike-media/README.md.
+/scripts/spike-media/*.mov
+/scripts/spike-media/*.mp4
+/scripts/spike-media/*.wav
+/scripts/spike-media/*.srt
+/scripts/spike-media/*.json
+/scripts/spike-media/*.html
+!/scripts/spike-media/fixtures/

.mcp.json

@@ -0,0 +1,18 @@
+{
+  "mcpServers": {
+    "brain": {
+      "type": "http",
+      "url": "https://brain-mcp.d-ma.be/mcp",
+      "headers": {
+        "Authorization": "Bearer ${BRAIN_MCP_TOKEN}"
+      }
+    },
+    "gitea": {
+      "type": "http",
+      "url": "https://git-mcp.d-ma.be/mcp",
+      "headers": {
+        "Authorization": "Bearer ${GITEA_MCP_TOKEN}"
+      }
+    }
+  }
+}

CLAUDE.md

@@ -12,6 +12,7 @@ docs it indexes.
 3. `DECISIONS.md` — the ADRs. Decisions are settled here; do not re-litigate without a new ADR.
 4. `docs/architecture/architecture.md`, `docs/data-model.md`, `docs/use-cases/*.feature`.
 5. `docs/homelab-integration.md` — the concrete endpoints/conventions you'll need.
+6. `LANGUAGE.md` — the project vocabulary. Apply the caveman rubric before destructive operations.
 
 ## How to work in this repo
 
@@ -46,8 +47,9 @@ These caused real mistakes that were caught and corrected; the corrections are l
 (See `DECISIONS.md` for full rationale. Listed here so you don't propose them.)
 
 - **No Supabase** — reuse Dex / ESO+1Password / Postgres (ADR-002).
-- **No global cross-tenant video/transcript table** — per-user isolation (data-model). Dedup
-  across users is a Future C concern, not a Stage 0/1 default.
+- **No global cross-tenant *video* table** — videos stay per-user (data-model). Transcripts ARE
+  shared since ADR-021 (public caption content, keyed by `(provider, provider_video_id)`, non-RLS)
+  so re-analysis never re-fetches; the *videos* half of cross-tenant dedup stays a Future C concern.
 - **No audio-download + speech-to-text in the core path** — captions-first (ADR-007). STT is a
   deferred, bounded optional component.
 - **No public SaaS / sign-up / billing / Google OAuth verification at scale** — Future C,
@@ -60,8 +62,14 @@ These caused real mistakes that were caught and corrected; the corrections are l
   stores, and sinks are adapters. Adding a video provider or a sink = a new adapter implementing
   the interface, nothing in the engine changes. This is what keeps "standalone vs homelab" a
   wiring choice (ADR-003).
-- **BDD.** The `docs/use-cases/*.feature` files are the behavior spec. New behavior gets a
-  scenario; the use-case core is tested through fake adapters, not live YouTube/brain.
+- **BDD.** The `docs/use-cases/*.feature` files are the behavior spec (design records — there is
+  no godog runner). New behavior gets a scenario; the use-case core is tested through fake
+  adapters, not live YouTube/brain. A name-coverage gate (`test/acceptance/scenario_coverage_test.go`,
+  `TestScenarioCoverage`) keeps the two from drifting: every non-`@pending` scenario must be
+  mapped to an existing Go test in `scenarioCoverage`. When you add a scenario, either map it to
+  its covering test or tag it `@pending` in the `.feature` with a one-line reason. It checks the
+  *link*, not that the test exercises the scenario — that's the deliberate trade for not running
+  godog (see issue #5 / the BDD-runner decision).
 
 ## Skills (engineering discipline)
 
@@ -79,7 +87,7 @@ Skills live in the canonical library `mathias/skills` and are wired into this re
 
 ## Current build state (start here for the first task)
 
-The repo is **green and shipping** — last tag `v0.4.0`. `task check` passes (fmt, vet, lint,
+The repo is **green and shipping** — last tag `v0.15.0`. `task check` passes (fmt, vet, lint,
 `go test -p 1 ./...`). Go is `1.26.1` (see `go.mod`).
 
 - Clean Architecture core is implemented: `internal/domain` (entities), `internal/ports`
@@ -88,13 +96,19 @@ The repo is **green and shipping** — last tag `v0.4.0`. `task check` passes (f
   green against it.
 - Adapters present under `internal/adapters/`: `youtube` (captions-first `VideoSource`,
   timedtext/InnerTube acquisition per ADR-010), `summarizer` + `llm` (the copied AI router,
-  Primary→Fallback per ADR-004), `store` (Postgres, golang-migrate migrations 001–006),
+  now a resilient endpoint chain — local primary → local fallback → external worst-case,
+  parse-failure-aware, ADR-004 + ADR-022), `store` (Postgres, golang-migrate migrations 001–015),
   `secrets` (file-backed `SecretStore`). The brain HTTP sink (ADR-005) is the remaining
   optional sink.
 - Stage 1 is open (ADR-012): multi-user with **DB-enforced** isolation — Postgres RLS `FORCE`d
   on all user-owned tables (migration 003), two-user isolation test in
   `internal/adapters/store/rls_test.go`. Registration gate, per-user YouTube web connect, and
   account management (disconnect / delete, ADR-013) all shipped.
+- Transcript persistence (ADR-021, migration 015): transcripts are a **shared, non-RLS** store
+  keyed by `(provider, provider_video_id)` — the single exception to the isolation boundary
+  (`TestTranscriptsTableIsSharedNotRLS`). The engine reads stored transcripts before any caption
+  fetch (`usecase.resolveTranscript`), so re-analysis — re-summarize, paste-a-URL, onboarding
+  burst — never re-touches YouTube. Per-user summaries/videos stay RLS-scoped.
 - `cmd/tapir` subcommands: `list`, `show`, `auth` (interactive host-side OAuth), `run` (batch
   watch→summarize), `serve` (the HTMX+Templ web reader/writer under `internal/web`, a new
   transport over the unchanged engine/ports — ADR-003). `tapir env` prints config.

DECISIONS.md

@@ -29,7 +29,9 @@ Go's concurrency model fits the watcher/worker shape).
 
 ## ADR-002 — No Supabase; reuse existing Dex / ESO / Postgres conventions
 
-**Status:** Accepted (2026-06-02)
+**Status:** Accepted (2026-06-02). The "Tapir does not write to the shared identity provider"
+implication is **partially superseded by ADR-017** (invite flow writes Dex Password CRs); the
+no-Supabase / reuse-existing-primitives decision stands.
 
 **Context.** The draft proposed self-hosted Supabase for auth + RLS + secrets (Vault). The
 homelab already runs **Dex** (OIDC), **ESO + 1Password** (secrets), and a **postgres18**
@@ -292,7 +294,11 @@ explicit call, with isolation as the guardrail that keeps it safe.
 
 ## ADR-013 — Account deletion is Tapir-side only; the Dex identity is left intact
 
-**Status:** Accepted (2026-06-03)
+**Status:** Accepted (2026-06-03). The "Tapir never holds write access to the shared identity
+provider" rationale is **partially superseded by ADR-017** (the invite flow now *creates* Dex
+Password CRs). The deletion-behaviour decision itself — delete Tapir-side state, leave the Dex
+identity intact — still stands; ADR-017 only changes the create side, not delete. See ADR-017
+for the now-asymmetric posture (Tapir can create Dex accounts but still does not delete them).
 
 **Context.** Stage 1 (ADR-012) added account deletion. A registered user is two things: a
 `users` row (plus all their data, cascade-linked) in Tapir's Postgres, and a subject identity
@@ -308,7 +314,9 @@ deprovision the Dex identity. The maintainer chose (a).
 - All of that user's secrets in the SecretStore (the per-user YouTube refresh-token refs).
 
 The **Dex identity is deliberately left intact.** Tapir does not deprovision, disable, or
-modify the shared Dex directory.
+modify the shared Dex directory **on deletion**. (Note per ADR-017: Tapir *does* now create Dex
+Password CRs on invite — so the create and delete sides are deliberately asymmetric, and a
+deleted user's Dex Password CR persists. See ADR-017 consequences.)
 
 **Consequences.**
 - **Clean re-registration:** a deleted user who logs in again arrives as a Dex-authenticated
@@ -319,9 +327,13 @@ modify the shared Dex directory.
   the identity carries no Tapir content. **But if Tapir ever moves toward Future C (real
   external/public users), this is a GDPR-shaped gap** — a true "delete my account" there must
   also deprovision or anonymise the Dex identity, which is a new ADR and likely a Dex-admin
-  integration Tapir does not currently have.
-- **Blast radius stays small:** Tapir never holds write access to the shared identity provider,
-  consistent with the estate's blast-radius-minimisation posture (ADR-002, architecture review).
+  integration Tapir does not currently have. **ADR-017 widens this gap:** Tapir now *creates*
+  the Dex Password CR but does not delete it, so a deleted Tapir user leaves an orphaned Dex
+  local-password account. Tracked as a known gap in ADR-017.
+- **Blast radius:** ADR-013 originally claimed "Tapir never holds write access to the shared
+  identity provider." **ADR-017 changes this** — Tapir now holds scoped `create`+`get` on
+  `passwords.dex.coreos.com` in the `auth` namespace. The blast radius is no longer zero; it is
+  bounded by that RBAC. See ADR-017 for the security analysis.
 
 **Reversibility.** Adding Dex deprovisioning later is a superseding ADR; nothing about the
 current choice blocks it. Recorded now because "deletion is partial by design" is a deliberate
@@ -331,7 +343,11 @@ semantic that future-Tapir (and any compliance review) must know was chosen, not
 
 ## ADR-014 — Timedtext 429 handling: per-host backoff + honest in-flight UX, before any Whisper reconsideration
 
-**Status:** Accepted (2026-06-03)
+**Status:** Accepted (2026-06-03). **Partially implemented as of v0.6.0** — see the
+implementation note at the end; the shared per-egress-IP rate gate (decision item 2) may not be
+fully realised. Verify against `internal/runner` + the youtube adapter before treating as done.
+**ADR-018 (in-process scheduled discovery + auto-summarize) makes decision item 2 load-bearing
+and folds its confirm/finish into that build.**
 
 **Context.** ADR-010 acquires captions from the unauthenticated `timedtext` baseUrl. Live runs
 show that endpoint **rate-limits per source IP (HTTP 429) under volume** — many videos fetched
@@ -386,6 +402,22 @@ clean data then tells you whether Whisper is warranted.
 dedicated egress IP / outbound proxy is worth it; CronJob-driven `tapir run` interaction with
 the rate gate (the batch path moves into k3s per the deferred CronJob item).
 
+**Implementation note (2026-06-03, v0.6.0 — added during reconciliation).** A v0.6.0 release
+shipped 429 handling: `domain.SourceRateLimited` (429 no longer collapsed to `SourceNone`),
+youtube adapter maps 429 → `SourceRateLimited`, **migration 007 added `videos.transcript_status`
++ `videos.rate_limited_at`** (durable per-video retry state), `TAPIR_FETCH_BACKOFF` config,
+runner records rate-limited + skips within the backoff window, and a "⏳ Retrying later" badge.
+This realises decision items 1, 3, and 4 well. **Item 2 (a single shared per-egress-IP rate
+gate) appears to be realised as per-*video* backoff state, NOT a process-wide IP gate** —
+multiple videos can still each hit the endpoint and collectively trip the per-IP 429. Treat item
+2 as **not yet confirmed done**; verify in `internal/runner`/youtube adapter and, if absent, it
+remains open. (Resolved during reconciliation: the v0.6.0 report's reference to "migration 008
+videos.rate_limited_at" was a **mislabel** — both columns shipped in migration **007**, not a
+missing 008. No migration was lost; the sequence legitimately skips 008. `rate_limited_at`
+exists and the runner's column reads are sound.) **ADR-018 makes item 2 a hard requirement:
+in-process scheduled discovery + auto-summarize drives all users' fetches through one pod egress,
+so the process-wide gate is confirmed/built as part of that slice.**
+
 ---
 
 ## ADR-015 — Per-user credentials: envelope-encrypted in PG18, not vault-stored
@@ -448,7 +480,8 @@ decision doc (`infra/docs/superpowers/handoffs/`). Build + reboot-validation: in
 
 **Status:** Accepted (2026-06-03). Revises the Stage 0 definition in VISION.md (supersedes the
 original "useful to me, specifically" gate and folds in the old Stage 1 "a trusted user returns"
-test).
+test). **The clock-start is further revised by ADR-018** (starts when scheduled discovery ships,
+since unprompted use was not possible before then).
 
 **Context.** The original Stage 0 gate was "the maintainer reads summaries weekly for four weeks
 and acts on one." The maintainer chose to change it to include friendly users, reasoning that
@@ -481,7 +514,7 @@ evidence the gate passed — use-evidence remains open.
   near-identical to the new test); hardening renumbered to Stage 1.
 - New drift signal added: declaring the gate passed on polite feedback rather than return-usage.
 - The 2026-07-01 check-in now asks "is anyone (me or a friend) coming back unprompted?", not
-  "am I using it weekly?".
+  "am I using it weekly?". (Check-in date itself revised by ADR-018.)
 
 **Reversibility.** A superseding ADR could tighten it back to maintainer-only or raise it to
 require multiple returning users. Recorded with the full rationale (including the self-scrutiny
@@ -489,6 +522,798 @@ about editing a gate while it's unmet) so the reasoning survives, not just the n
 
 ---
 
+## ADR-017 — Invite flow: Tapir creates Dex local-password accounts (write access to the shared identity provider)
+
+**Status:** ~~Accepted~~ **SUPERSEDED by [ADR-019](#adr-019--authentik-owns-invites-tapir-stops-provisioning-accounts) (2026-06-07).** The Dex local-password
+invite provisioning was removed when the homelab IdP migrated Dex→Authentik
+(infra ADR-0001); Authentik now owns invites. Original record below.
+
+Accepted (2026-06-03), **recorded retroactively during reconciliation, then
+deliberately ratified KEEP (2026-06-03).** This capability **shipped in v0.7.0 without an ADR** —
+code, RBAC, and a deployed ServiceAccount landed before any decision record existed. This ADR
+documents what shipped and honestly records that the decision-before-code discipline was not
+followed here (see "Process note"). **Partially supersedes ADR-002 and ADR-013** (the "Tapir
+holds no write access to the shared identity provider" posture).
+
+**Keep-or-reverse, decided (2026-06-03).** After the retroactive recording, the maintainer
+weighed keep vs. reverse (drop the RBAC + invite flow, rely on Google OIDC only). **Decision:
+KEEP.** Deciding fact: not all intended Future-B users have / will use Google accounts, so Google
+OIDC alone *cannot* onboard them — the invite flow is therefore **load-bearing, not a redundant
+convenience**, and reversing it would leave some intended users with no onboarding path. The
+trust-surface cost (scoped `create` on `passwords` in `auth`) is accepted deliberately in
+exchange. The opposing argument (this contradicts ADR-015's "no write credential to shared infra"
+logic, applied there to secrets) was considered and outweighed *only* because the capability is
+genuinely necessary for real users here — it is **not** a precedent for widening the surface
+further. **Explicitly NOT chosen:** adding `delete` to the RBAC to close the orphan gap (that
+widens the surface in the wrong direction; accept the orphan at Future B instead — see open
+items).
+
+**Context.** Stage 1 onboarding needs a way for a friend to get a login. Two paths shipped:
+Google OIDC via Dex (no Tapir code — Dex handles it), and an **invite flow** where Tapir itself
+provisions a Dex **local-password** account. The invite flow is what this ADR is about.
+
+**What shipped (reconstructed from `internal/adapters/dex/dex.go`, `internal/web/invite.go`,
+migration `009_invitations`).**
+1. `tapir invite <email>` (host CLI) writes an `invitations` row: a 32-byte crypto-random,
+   single-use, 7-day-expiry `token` (the token is the capability), `email`, `used_at`.
+   The `invitations` table is deliberately **not** RLS/`user_id`-scoped — the invitee has no
+   user yet and the token itself is the secret. (Sound; documented in the migration.)
+2. Recipient visits `/invite/{token}` (public, no session), sets a password (validated *before*
+   the token is consumed, so a typo doesn't burn it), the token is claimed exactly once.
+3. Tapir bcrypt-hashes (cost 12) and **POSTs a `passwords.dex.coreos.com` Custom Resource into
+   the `auth` namespace** via the in-cluster Kubernetes API, authenticating as the `tapir`
+   ServiceAccount. TLS validated against the mounted cluster CA. Off-cluster (dev) it returns
+   `ErrNotInCluster` and degrades without consuming the invite.
+4. RBAC applied this deploy: the `tapir` ServiceAccount has **`create`+`get` on
+   `passwords.dex.coreos.com` in the `auth` namespace** (and only that).
+5. Dex (kubernetes storage) then serves local-password login for that email; Tapir's
+   registration gate creates the profile on first login.
+
+**Decision (as ratified now).** Accept the invite flow as built: Tapir *may* hold scoped write
+access to Dex's `passwords` resource in the `auth` namespace, for the purpose of invite-based
+local-account creation. This is a deliberate, bounded reversal of the prior "no write access to
+the shared identity provider" posture (ADR-002/013).
+
+**Why this is acceptable (the case for keeping it).**
+- The RBAC is **minimally scoped**: `create`+`get` on one resource type in one namespace, not
+  broad Dex/cluster write. Blast radius is bounded and inspectable.
+- It enables friend onboarding **without Google OAuth app verification** (ADR-008 deferred that),
+  which is genuinely useful for Future B — and necessary for users who won't use Google (the
+  deciding fact in the keep decision above).
+- The code is careful: validate-before-consume, single-use tokens, graceful off-cluster degrade,
+  sentinel errors mapped to clear messages, the base64-bcrypt storage gotcha handled.
+
+**Consequences / known gaps (the case to watch).**
+- **Reverses a load-bearing principle.** ADR-002 and ADR-013 leaned on "Tapir never writes to the
+  shared identity provider" for blast-radius minimisation. That is no longer true. Anyone reading
+  those ADRs without this one would be misled — hence the cross-references added to both.
+- **Create/delete asymmetry → orphaned Dex accounts.** Tapir now *creates* Dex Password CRs but
+  (per ADR-013) does not *delete* them on account deletion. A deleted Tapir user leaves an
+  orphaned Dex local-password account that can still authenticate (though it would hit the
+  registration gate with no profile). This widens the ADR-013 right-to-erasure gap. **Open —
+  accepted for Future B, revisit before Future C (do NOT add `delete` RBAC just to fix this).**
+- **`create` on a shared-namespace identity resource** is a meaningfully larger trust surface than
+  the rest of Tapir. If the `tapir` pod is compromised, the attacker can mint Dex local accounts.
+  Bounded by the namespace/resource scope, but real — worth a deliberate look before Future C.
+- Token custody for invites is in PG (`invitations.token`) in plaintext; single-use + 7-day TTL
+  bound the exposure, but a DB read yields live invite tokens until claimed/expired.
+
+**Process note (why this ADR is retroactive).** This capability was built and deployed by
+parallel agent sessions while the main planning thread was elsewhere, and shipped with no ADR —
+the first time in this project a guardrail-reversing change skipped the decision-before-code
+discipline. Recorded here not to rubber-stamp it but to restore the audit trail: the decision is
+now visible, its principle-reversal is named, and its open gaps (orphaned accounts, the larger
+trust surface) are tracked rather than buried in a release note. The maintainer ratified KEEP
+after the fact (see status block) on the deciding fact that some intended users cannot use Google
+OIDC.
+
+**Open items this ADR creates (tracked in infra):**
+- Confirm the RBAC really is `create`+`get` only (not broader) against the deployed manifest in
+  `infra` — a security claim currently resting on a sibling report, not a verified manifest read.
+- Accept the orphaned-Dex-account gap for Future B; revisit (orphan cleanup + the whole Dex-write
+  surface) before any Future C move. Do **not** add `delete` RBAC solely to fix the orphan.
+- Review the larger trust surface before any Future C move.
+
+---
+
+## ADR-018 — Make Tapir usable unprompted: in-process scheduled discovery, auto-summarize default, gate-clock reset
+
+**Status:** Accepted (2026-06-03)
+
+**Context.** The Stage-0 gate (ADR-016) measures whether the maintainer or a friend *returns and
+reads/acts* over weeks. But the system could not actually be used that way: discovery (`tapir
+run`) was **host-side manual**, so a newly onboarded user saw an empty list and had no reason to
+return. The gate was structurally unmeetable — not because the product failed, but because the
+*workflow* depended on the maintainer SSHing in to trigger each pass. The runner already has a
+`Loop(ctx, interval)` (run-on-start, then every tick) and per-user mode/dedup/backoff; what was
+missing was *invocation* — nothing called it for the deployed users on a schedule.
+
+**Decision.**
+1. **In-process scheduled discovery.** `tapir serve` launches a background goroutine that runs
+   discovery for **all users** on an interval (`TAPIR_DISCOVERY_INTERVAL`; unset/0 = off). It
+   enumerates users (un-RLS'd `user_identities`) and runs each user's pass inside `withUser`,
+   reusing the existing `runner` — not a new scheduler. Stateless timing; ctx-cancellable;
+   per-user failures isolated.
+2. **Auto-summarize default ON** for Future-B users (new registrations default `true`; existing
+   rows updated), so discovery both populates *and* summarizes — the list fills itself. The
+   per-user manual toggle remains.
+3. **Gate-clock reset.** The Stage-0 3–4 week window (ADR-016) **starts when this ships**, because
+   unprompted use was impossible before it. This is starting the clock when the experiment can
+   actually run, **not** a reset to dodge a failing gate (the prior window measured nothing —
+   there was no way to use the system unprompted). The 2026-07-01 check-in moves accordingly to
+   ~3–4 weeks after this deploys.
+
+**Why in-process and not a k8s CronJob.** Maintainer's call: simpler deploy (no second deployable),
+acceptable at Future-B scale (1–3 users). The CronJob's advantage — failure isolation between
+discovery and the web/read path — was weighed and traded away knowingly.
+
+**Consequences / constraints.**
+- **Discovery shares the web process's lifetime and egress.** A wedged discovery pass can degrade
+  the reading UI (the coupling a CronJob would have avoided). Accepted at this scale.
+- **SINGLE-REPLICA ASSUMPTION (load-bearing).** If `tapir serve` ever runs >1 replica, *every*
+  replica runs the discovery loop → every user fetched in parallel (429s + duplicate work). Tapir
+  must stay single-replica while in-process scheduling is enabled, or this is revisited (move to
+  CronJob, or add leader-election). Recorded so a future scale-up doesn't silently double-run.
+- **Makes ADR-014 item 2 (shared per-egress-IP rate gate) load-bearing.** In-process + auto +
+  multi-user drives all caption fetches through one pod egress, concurrent with click-path
+  Summarize. The build confirms/finishes the process-wide rate gate in the same slice; without it
+  the system self-inflicts 429s every cycle. **Auto-summarize ON is gated on the rate gate
+  existing** (fallback: ship discovery with auto OFF until it does).
+
+**Reversibility.** Disable via `TAPIR_DISCOVERY_INTERVAL=0` (reverts to manual `tapir run`).
+Moving to a CronJob later is a superseding ADR; the per-user `runner` is unchanged either way.
+Spec: `docs/specs/scheduled-discovery.md`.
+
+---
+
+## ADR-019 — Authentik owns invites; Tapir stops provisioning accounts
+
+**Status:** Accepted (2026-06-07). **Supersedes ADR-017** (Dex local-password invite
+provisioning).
+
+**Context:** infra ADR-0001 migrated the homelab IdP Dex→Authentik. Authentik provides
+first-class invite flows; the Dex local-password connector never consulted the Password
+CRs Tapir wrote (the defect that triggered the migration). Tapir-web's OIDC issuer now
+points at Authentik (infra ADR-0001 step 3).
+
+**Decision:** Tapir no longer provisions accounts. The Dex-password invite path is removed:
+`internal/adapters/dex`, the public `/invite/{token}` set-password UI (`internal/web/invite.go`),
+the `tapir invite` CLI (`cmd/tapir/invite.go`), the `InvitationStore`/`DexPasswordCreator`
+ports + `App.Invitations`/`App.Dex` wiring, the invite Templ pages, and the
+`tapir invite` Taskfile target. New users are invited via Authentik's flow, log into Tapir
+via OIDC, and are captured by Tapir's existing provider-agnostic `/register` (display name).
+Login + Google moved by config only (Authentik per-app issuer); the OIDC adapter is unchanged.
+
+**Consequences:** smaller Tapir blast surface — no writes to the shared identity provider, no
+configmap/CR access, the dedicated `passwords.dex.coreos.com` RBAC + ServiceAccount are
+removed (infra side, coupled change). The `invitations` table (migration 009) is left in
+place — migrations are append-only and the unused table is harmless; a future migration may
+drop it. The `*_DEX_*` config/identity names (`TAPIR_DEX_CLIENT_*`, `dex_subject`, the
+`DexAuth`/`oidc` package) are now misnomers; renaming is deferred (cosmetic, not behavioural).
+
+**Rejected:** keeping Tapir's `/invite` UI but calling Authentik's API on claim — couples
+Tapir to Authentik's admin API + a token for no real gain; Authentik's own invite flow is
+the supported path.
+
+---
+
+## ADR-020 — Recency-bounded auto-summarize + honest sparse-state surface
+
+**Status:** Accepted (2026-06-08). **Refines ADR-018** (auto-summarize) and **ADR-014**
+(per-IP caption rate gate).
+
+**Context.** Tapir is operational but sparse: at real subscription volume the maintainer's
+account holds ~283 discovered videos, ~15 summarized, ~256 behind the respected per-IP caption
+rate gate, ~12 no-captions. Two problems follow. (1) **Load:** ADR-018 auto-summarizes *every*
+unseen video, so a large back-catalogue re-drives the whole queue through the gate every cycle —
+self-inflicted 429s with no user value (nobody is waiting on a 6-month-old video). (2) **First
+contact:** a new user sees a mostly-empty feed with no moving parts and a UI that implied
+abundance/imminence ("fetching soon" ×256, "Run `tapir run`", "Summarize now"); the Stage-0 gate
+is *return usage*, and the experience died at the first visit. Source: a UX heuristic review
+(`docs/ux-review/UX-REVIEW-stage0-recency.md`).
+
+**Decision.**
+1. **Recency bound on auto-summarize.** In automatic mode the scheduler only summarizes videos
+   published within `TAPIR_AUTO_SUMMARIZE_WINDOW` (default ~7d). Older videos are still discovered
+   and listed but not auto-processed — they keep the manual "Summarize" affordance. An explicit
+   manual request bypasses the bound. `0` disables it (pre-recency behaviour). This bounds auto
+   *load*; it does not fetch harder — the gate (ADR-014) is untouched and the manual path still
+   serialises through it.
+2. **Honest sparse-state surface.** Copy is reframed to surface scarcity truthfully, never to
+   look fuller: "N ready · M in queue · K no captions" (not "fetching soon"); a one-line "captions
+   are fetched slowly on purpose" note; "Summarize" (not "Summarize now"); the empty-connected
+   state stops printing an impossible CLI command.
+3. **Feed IA = one list, noise-collapsed.** Summarized + recent un-summarized cards lead inline;
+   the older un-summarized back-catalogue collapses behind a single "Show N older videos"
+   disclosure; caption-less videos collapse to a one-line count instead of N dead cards. List is
+   ordered summarized-first, then `published_at DESC NULLS LAST`.
+
+**Consequences.** The auto path's per-cycle fetch volume is bounded by recent uploads, not the
+whole back-catalogue, so steady-state 429 pressure drops sharply. Older videos become explicitly
+on-demand — a deliberate honesty trade (the user chooses to spend a scarce fetch on old content).
+The single-replica assumption (ADR-018) is unchanged.
+
+**Deliberately NOT done (premature until the Stage-0 loop is validated).** Return-nudges
+(digest email / push) — a nudge contaminates the *unprompted*-return signal the gate measures
+(ADR-016); building it now poisons the experiment. Also deferred: full-text search, channel
+facets, read/unread, saved views — all need summary abundance to matter.
+
+**Reversibility.** `TAPIR_AUTO_SUMMARIZE_WINDOW=0` restores summarize-every-unseen; the feed
+collapse keys off the same window (`App.RecencyWindow=0` → everything inline).
+
+---
+
+## ADR-021 — Persist transcripts as shared, video-keyed public content (re-analysis never re-fetches)
+
+**Status:** Accepted (2026-06-09). **Reopens the transcripts half of** the "Global cross-tenant
+`videos`/`transcripts` table" rejection (data-model.md). **Builds on ADR-007** (captions-first),
+**ADR-010/ADR-014** (the per-IP caption rate gate), and **ADR-012** (per-user RLS isolation).
+
+**Context.** Every summarization fetches the transcript fresh through the caption path, even when
+the exact same transcript was fetched moments ago — for the same user re-summarizing, or for a
+second user who happens to watch the same video. The caption fetch is the one genuinely scarce,
+genuinely risky operation in the system: YouTube's timedtext endpoint is unofficial and per-IP
+rate-limited (ADR-010), and tripping it risks the maintainer's Google standing (ADR-014). So the
+operation we most want to *avoid repeating* is the one we currently repeat unconditionally. A
+transcript is **public content** — the same words YouTube serves to anyone — and carries nothing
+user-identifying. The per-user isolation that protects summaries, feeds, and tokens (ADR-012) is
+the wrong shape for it: it forces a re-fetch per user for data that is identical across users.
+
+The original rejection ("Global cross-tenant `videos`/`transcripts` table") bundled videos and
+transcripts together and rejected both on the grounds that "at 1–5 users, re-summarizing is
+cheaper than the coupling." That reasoning holds for **videos** (per-user feed rows, genuinely
+user-scoped) but not for **transcripts**: the cost being avoided is not LLM re-summarization, it
+is a *rate-gated, reputation-risky network fetch*, and that cost is paid per re-fetch regardless
+of user count. One re-fetch avoided is strictly worth more than the coupling it removes.
+
+**Decision.**
+1. **A single shared `transcripts` table, keyed by the cross-user dedup key
+   `(provider, provider_video_id)`** — the stable public identity of the video, not Tapir's
+   internal per-user `videos.id`. Columns: the key, `source` (`captions`/`none`), `language`,
+   `content`, `fetched_at`. It holds **only public caption content + the video's public id** —
+   nothing user-identifying — and is therefore **NOT RLS-scoped**: no `user_id`, no policy, no
+   `FORCE ROW LEVEL SECURITY`. This is the deliberate, single exception to the ADR-012 isolation
+   boundary, and the only one.
+2. **Summarize path becomes read-stored-first.** Have a stored transcript for this video? →
+   summarize from the stored text, **no caption fetch**. No stored transcript? → fetch *through
+   the unchanged gate* (ADR-014) → store it → summarize. The gate is neither bypassed nor
+   weakened; persistence reduces how *often* we reach it, never how *fast*.
+3. **De-facto cross-user dedup is the intended behaviour, not a feature with a switch.** Two
+   users who share a video share the one transcript row. A permanent `source = 'none'` (no
+   captions) is stored too, so a known-caption-less video is not re-fetched by anyone. A
+   transient 429 (`SourceRateLimited`) is **never** stored as terminal — it stays a per-user
+   retry via the existing `transcript_status` backoff (ADR-014), so persistence cannot mask a
+   rate-limit into a false "no transcript."
+4. **Per-user `summaries` stay RLS-scoped (ADR-012 unchanged)** and reference the transcript by
+   video id. Videos stay per-user. Only transcripts go shared.
+
+**Consequences.** Re-analysis (re-summarize, different model, paste of an already-seen video,
+onboarding of a second user with overlapping subscriptions) never re-touches YouTube — the
+primary win, and it *reduces* aggregate caption-gate pressure, reinforcing ADR-010/ADR-014 rather
+than straining them. The isolation surface gains exactly one non-RLS table; an isolation test
+asserts the boundary is *exactly* there and has not leaked to any user-owned table (this is the
+proof the public-content classification was implemented as designed). It also unblocks
+multi-model / customizable analysis (re-run analysis on stored text for free) — enabling that is
+this ADR's point; building it is separate.
+
+**Reversibility.** The read-stored-first check is the only behavioural coupling; removing it
+restores fetch-every-time. The down-migration recreates the per-user RLS-scoped transcripts shape
+(001/003). No user-facing surface depends on cross-user sharing — sharing is the *storage shape*,
+never exposed in the UI.
+
+---
+
+## ADR-022 — Summarizer is a resilient endpoint chain, not a single model
+
+**Status:** Accepted (2026-06-10). **Extends ADR-004** (the copied `llm` Primary→Fallback
+routing). Triggered by the first friendly-pilot live run, where a connected user got **zero**
+summaries after 12h.
+
+**Context.** Stage-0 ran a single summarizer model (`koala/phi4-mini`) with no fallback wired
+(`summarizer.New(primary, nil)`). The live run exposed three independent failure modes, each of
+which silently produced no summary:
+
+1. **Context overflow.** `phi4-mini` has an 8k context. Real transcripts (one was 11,602 tokens)
+   exceed it and the gateway returns HTTP 400 — and the request also sent `max_tokens=8192`, so
+   even a short transcript plus the completion budget could overflow the window.
+2. **Malformed model output.** `phi4-mini` intermittently emits `highlights` as a bare string
+   instead of an array, producing `cannot unmarshal string into []string`. The old code returned
+   the parse error **without** trying any other model — a 200-with-bad-JSON short-circuited.
+3. **No fallback existed at all** — any primary failure was terminal for that video.
+
+`phi4-mini` is kept as primary deliberately: it is fast and, on transcripts that fit, correct.
+The fix is resilience around it, not replacing it.
+
+**Decision.**
+1. **Ordered endpoint chain (`summarizer.NewChain`).** Endpoints are tried in order; the first to
+   return a *parseable* summary wins. Default chain:
+   `koala/phi4-mini` (primary, local) → `iguana/gemma4-26b` (fallback, local on a
+   *different host*) → `berget/mistral-small` (worst-case, external). All three are reached through
+   the **one** LiteLLM gateway by alias — the gateway already fronts both llama-swap and berget — so
+   a fallback is a different alias, not a second client config.
+
+   **Update 2026-06-11:** the local fallback moved from `koala/phi4-14b` to `iguana/gemma4-26b`.
+   koala now carries other GPU loads, so keeping the fallback on koala competed with them; iguana
+   (M2 Ultra) has the headroom, and a different host is also a different egress IP for the rare
+   fallback fetch. `gemma4-26b` is the brain-validated homelab general-purpose model (agentsquad
+   H2/H3 executor) and returned valid summary JSON on the real prompt in a smoke test
+   (~37s incl. cold-load — fine for a path hit only when the fast primary fails). Pure config:
+   `TAPIR_FALLBACK_MODEL`.
+2. **A parse failure advances the chain, same as a transport error.** "Reliably summarized" means
+   *parseable summary returned*, not *HTTP 200*. This is the behaviour the old Primary→Fallback
+   shape missed.
+3. **Tolerant parse.** `highlights`/`takeaways` coerce from a bare string (or a mixed scalar
+   array) to `[]string`, so the most common small-model quirk is absorbed **without** spending a
+   fallback round-trip — keeping the fast path fast.
+4. **Transcript truncation (`TAPIR_MAX_TRANSCRIPT_CHARS`, default 18000).** Input is bounded
+   up-front to fit a small-context primary, so overflow is prevented rather than recovered-from.
+5. **Bounded completion budget (`TAPIR_SUMMARY_MAX_TOKENS`, default 1500).** A summary needs few
+   hundred tokens; the old 8192 budget itself contributed to 8k-window overflow.
+
+**Local-first guarantee preserved.** The chain ordering *is* the guarantee: locals are tried
+first, so content reaches the external endpoint only after every local endpoint has failed.
+`TAPIR_CLOUD_FALLBACK_MODEL=""` removes the external endpoint entirely — the lever a
+**client/NDA deployment** pulls so content never leaves the local stack. With no external endpoint
+configured the `ai_routing.feature` "content only local" scenarios hold unchanged.
+
+**Reversibility.** Pure wiring + config. Setting `TAPIR_FALLBACK_MODEL` and
+`TAPIR_CLOUD_FALLBACK_MODEL` empty collapses the chain back to single-primary behaviour; the
+tolerant parse and truncation are strict supersets of the old behaviour (a previously-parseable
+reply still parses; a transcript within budget is unchanged).
+
+---
+
+## ADR-023 — Drop Shorts/livestreams at discovery to protect the caption budget
+
+**Status:** Accepted (2026-06-10). **Builds on ADR-014** (per-IP caption rate limit is the
+binding constraint) and the ADR-022 live-run findings.
+
+**Context.** The scarce resource is the unofficial timedtext caption fetch (per-egress-IP
+429, ~3 successful/pass). The first multi-user run showed the candidate set was mostly noise —
+Shorts, sub-minute clips, and live broadcasts — each of which still consumes a caption-fetch
+attempt (and a "none" result is a *completed* fetch, so it costs budget even when it yields
+nothing). Spending the rate-limited budget on content the user will not read is the waste to
+cut first; it is cheaper and lower-risk than raising the ceiling (multi-IP, Whisper).
+
+Duration and live status are NOT in the playlistItems discovery response, but they ARE in the
+Data API `videos.list` (contentDetails.duration + snippet.liveBroadcastContent) — the official
+**quota-based** API (1 unit/call, 50 ids/call), which is a *different* limit from the timedtext
+429. So one cheap quota call buys a filter that saves many expensive throttled fetches.
+
+**Decision.**
+1. `NewVideos` enriches its candidates with a single `videos.list` call and drops, before
+   returning: videos shorter than `TAPIR_MIN_VIDEO_SECONDS` (default 60) and any `live`/
+   `upcoming` broadcast. Dropped videos are never persisted, so they also declutter the list.
+2. The filter is **degrade-open**: `MinVideoSeconds=0` disables it (no quota call), and a
+   `videos.list` error returns the candidates unfiltered — discovery must never break because a
+   metadata call hiccuped (worst case = pre-ADR-023 behaviour).
+3. The paste-a-URL path (`VideoByID`) is **not** filtered — an explicit user request for a
+   specific video (even a Short) is honoured.
+
+**Reversibility.** Pure discovery-time filter + config. `TAPIR_MIN_VIDEO_SECONDS=0` restores
+the old behaviour. No schema change, no effect on already-stored videos.
+
+**Quota note.** Per-channel enrichment adds ~1 unit/channel/pass. At pilot scale (≤3 users)
+this is well under the 10k/day cap; at larger scale, batch `videos.list` across channels
+(50 ids/call) by collecting all discovered ids per pass before enriching.
+
+---
+
+## ADR-024 — Per-channel caption-availability memory
+
+**Status:** Accepted (2026-06-10). **Builds on ADR-014** (per-IP caption budget), **ADR-021**
+(shared transcript cache), **ADR-023** (Shorts filter).
+
+**Context.** After ADR-021 caches transcripts and ADR-023 drops Shorts, the remaining caption
+waste is the *first* fetch on every new video of a channel that never publishes English captions
+(foreign-language news, music, etc.). Each costs one rate-limited fetch to resolve to "none" —
+and on a throttled IP that fetch may 429 and churn the backoff machinery before it ever gets a
+verdict. A pilot user's feed had several such channels.
+
+**Decision.** Remember, per `(user, channel)`, a streak of consecutive no-caption outcomes
+(`channel_caption_state`, migration 016, RLS-scoped like the rest of the user-owned schema).
+Once the streak reaches `TAPIR_CHANNEL_CAPTIONLESS_THRESHOLD` (default 5) the channel is
+suppressed — its videos are discovered/listed but not caption-fetched — for
+`TAPIR_CHANNEL_CAPTIONLESS_WINDOW` (default 14d), after which one video is re-probed
+(auto-recovery for a channel that starts adding captions). A successful fetch resets the streak;
+a fresh 429 does NOT count (transient, not a caption verdict). An explicit manual request
+bypasses suppression. `threshold = 0` disables the feature.
+
+**Why per-user, not global.** Caption availability is really a channel property (public), so a
+global table would let users share the learning. But subscriptions are per-user (ADR-012) and at
+pilot scale users' channel sets barely overlap, so per-user + RLS keeps it consistent with the
+existing isolation model with no new non-RLS exception to justify. Promoting to a shared table
+(like transcripts, ADR-021) is a future optimisation if channel overlap grows.
+
+**Reversibility.** Migration 016 is a clean drop; `threshold = 0` disables at runtime. The
+memory only ever *suppresses fetches* — it never deletes content or affects already-stored
+summaries.
+
+---
+
+## ADR-025 — Honest, state-aware foreground summarization status
+
+**Status:** Accepted (2026-06-10). **Pillar B of the manual-mode UX work** (Pillar A, foreground
+fetch priority, is a separate follow-up). Builds on ADR-014 (the rate limit the UX must make
+legible).
+
+**Context.** Clicking "Summarize" spawned a background goroutine and polled `/status`, which
+returned only two states: the spinner (in-flight) or the normal card (done). But the web
+`ProcessVideo` only recorded an outcome on *success* — a 429'd or caption-less click left
+`transcript_status` unset, so the next poll silently reverted to the "Summarize" button. The
+user saw either an endless spinner or a button that did nothing useful when clicked again. The
+binding constraint (YouTube's caption rate limit) was completely invisible.
+
+**Decision.**
+1. **Record every outcome on the web path**, mirroring the runner: `ProcessVideo` stamps
+   `rate_limited` / `none` / `fetched`. A rate-limited video keeps its requested flag so the
+   background sweep retries it; `none` and `fetched` are terminal.
+2. **`/status` is state-aware**: summarized → summary card; in-flight → working spinner;
+   `rate_limited` → a calm "waiting, will retry" card that keeps polling (every 30s) so the
+   summary appears on its own when the retry lands — the user never clicks again;
+   `none` → a terminal "no captions" card with no poll and no dead-end button.
+3. **Charm status text** (Claude-Code / Crush inspired): the working spinner cycles playful,
+   tapir-themed gerunds ("Chewing the cud…", "Munching leaves…", "Distilling the gist…") via
+   CSS only — no JS, keeping the HTMX/no-JS ethos. Decorative (aria-hidden) with a stable
+   `role=status` line for assistive tech.
+
+**Principle.** When the system cannot be fast (throttled IP), it is at least honest, and it
+self-resolves without making the user retry. Honesty is the load-bearing half — Pillar A's
+priority lane only improves the odds of a fast slot; it cannot beat an already-hot IP.
+
+**Reversibility.** Pure transport-layer + view change over the unchanged engine/ports. No
+schema change (reuses `transcript_status` from migration 007).
+
+---
+
+## ADR-026 — Foreground caption fetches take priority; the credentials probe is dead
+
+**Status:** Accepted (2026-06-10). **Pillar A of the manual-mode UX work** (Pillar B was
+ADR-025). Builds on ADR-014 (the shared per-IP gate).
+
+**Context.** Every caption fetch — the background sweep and the web click-path — shared one
+process-wide rate gate equally. So a user waiting on a "Summarize" click competed with the
+firehose for both pacing and the scarce pre-429 window; on a busy IP the click was slow or
+429'd while the background churned.
+
+**Decision.** A context-marked priority lane. The web path
+(`engineProcessor.ProcessVideo`) wraps its context with `ForegroundContext`; the gate gives
+foreground fetches a token immediately, while **background fetches yield** — they wait until no
+foreground fetch is pending before taking a token. Threaded via a context value (not new
+signatures) and a process-wide `foregroundPending` counter. Clicks are rare and bursty, so the
+background barely loses throughput; the waiting human gets the next (and cleanest) slot.
+
+**Credentials probe — rejected, not built.** The idea was to fetch captions with the user's
+auth in manual mode to dodge 429s. It is a dead end, already settled by ADR-010 and the code:
+the caption path is *deliberately anonymous* because the InnerTube/timedtext endpoints **reject
+or break on authenticated requests** (`captions.go`: "no OAuth token — it can break the
+timedtext endpoint"). The user's OAuth (a Data API credential) does not authenticate InnerTube
+at all, and the official `captions.download` is owner-only (403 on third-party). So auth cannot
+help here and can actively hurt. No probe needed — building one would only re-confirm the ADR.
+
+**Reversibility.** Context-marker + a yield loop in the gate; removing the marker collapses to
+the prior equal-share behaviour. No schema or API change.
+
+---
+
+## ADR-027 — Chat with a video's stored transcript (deeper-dive, on an already-summarized video)
+
+**Status:** Accepted (2026-06-11). **Consumes ADR-021** (the shared, video-keyed transcript
+store) for the first time beyond summarization; **uses the ADR-022 chain models**; relates to
+ADR-012 (isolation) and ADR-016 (the Stage-0 gate).
+
+**Context — observed demand, not hypothetical.** The maintainer read 10+ real pilot summaries
+and reported the reactions: *many good; some he wanted to dig deeper into; some less useful*
+(the "less useful" split between weak-*model* output and uninteresting-*video* content). The
+middle reaction is the signal: a good summary that makes the reader want *more* is the summary
+succeeding at triage and then hitting a wall — there is nowhere to go deeper short of watching
+the video. That want is the feature. It is also the cheapest possible feature to satisfy
+honestly, because ADR-021 already persists the transcript: the deeper-dive runs entirely on
+stored public-content text + local models, touching **no** caption fetch and **no** YouTube.
+
+**Decision.** Add a per-video chat that lets the user ask questions against a video's stored
+transcript.
+1. **Entry from the summary view only.** A "dig deeper / ask" affordance on a summarized video —
+   the chat lives exactly where the "I want more" reaction happens. No standalone chat surface.
+2. **Stored-transcript-only (load-bearing constraint).** Chat is available **only** for videos
+   that already have a stored transcript. It never triggers a caption fetch, so it cannot touch
+   the rate gate, the 429 surface, or YouTube at all — the entire account-safety constraint that
+   governs the rest of Tapir is satisfied *by construction* here, not by careful gating. (Entry
+   being "from a summary" guarantees the transcript exists.) On-demand fetch for un-stored videos
+   is explicitly deferred.
+3. **Model = the summary's model by default; user-switchable among the ADR-022 chain models**
+   (`phi4-mini` / `gemma4-26b` / `mistral-small` to start). This is deliberate: it doubles as
+   live model-comparison instrumentation — ask the same question of the same transcript under two
+   models and the difference is directly felt. This is the mechanism by which the maintainer
+   learns *which* model is worth defaulting to, and it is the multi-model-analysis direction
+   ADR-021 anticipated, arriving as a user-facing capability.
+   - Chat is a **read-bounded retrieval/QA task** (the user supplies the focus), which is
+     *easier* than summarization (the model must decide what matters). So a model that summarizes
+     mediocrely may chat well — chat is plausibly a partial remedy for the weak-summary case, not
+     an inheritor of it.
+4. **Ephemeral chat (v1).** No persisted history; chat is per-session. Persisting per-user,
+   RLS-scoped history is deferred until there is evidence anyone wants to revisit a conversation.
+5. **Chat-only, trust-the-model (v1) — with a recorded limitation.** The chat does not expose the
+   raw transcript for verification in v1 (kept simple). **Known limitation:** because some
+   summaries were weak-model output, the user has reason not to fully trust a chat answer's
+   fidelity to the transcript, and v1 gives no in-UI way to check. The model-switcher partially
+   compensates (two models disagreeing on the same question is itself a signal). A
+   "show source / view transcript" verification path is the natural **v2** and is *not*
+   foreclosed — ADR-021's stored transcript already makes it cheap. Recorded so v2 is a known
+   next step, not a rediscovery.
+
+**Why this is safe and in-scope.** It adds no caption-fetch surface (stored-only), no new
+non-RLS table (transcripts already shared per ADR-021; ephemeral chat stores nothing), and no
+auth change. It is additive to the read path. The one genuine product expansion — Tapir becomes
+an interactive transcript-QA tool, not only a summarizer — is justified by *observed* demand from
+real reading, which is exactly the kind of evidence the Stage-0 discipline asks for before
+building.
+
+**Relation to the Stage-0 gate.** This is **not** a return-nudge (those stay deferred, ADR-020) —
+it adds nothing that prompts the user to return; it deepens the value *once they are already
+reading*. It does not contaminate the unprompted-return signal. If anything it strengthens the
+"useful to me" case the gate measures, by giving a good summary somewhere to lead.
+
+**Reversibility.** Additive read-path feature over the unchanged engine + the ADR-021 store.
+Removing the summary-view affordance removes the feature; nothing else depends on it. Ephemeral =
+no migration, no stored state to unwind. Spec: `docs/specs/chat-with-transcript.md`.
+
+---
+
+## ADR-028 — Onboarding burst: pick likely-good videos, summarize them with a stronger model
+
+**Status:** Accepted (2026-06-11). **Refines ADR-018** (the connect-time burst) and **ADR-020**
+(recency-bounded auto-summarize). **Builds on ADR-022** (the endpoint chain), **ADR-023**
+(the discovery-time `videos.list` enrichment), and **ADR-021** (the shared transcript cache).
+Triggered by a Phase-1 investigation of the live pilot DB.
+
+**Context.** A new user's first session decides whether they return (the Stage-0 gate, ADR-016).
+The connect-time burst (ADR-018: summarize ≤`TAPIR_ONBOARD_SUMMARIZE_COUNT` newest videos so the
+feed isn't empty) *fires* in production, but a live-DB investigation of the second pilot user
+("Jonte") found it delivers a weak first impression for two reasons, and ruled out a third idea:
+
+1. **Junk picks.** Selection was pure newest-first (`NewestUnsummarizedVideoIDs`,
+   `ORDER BY published_at DESC`) with **no quality signal**. Jonte's live burst-3 were a
+   stock-ticker **livestream** + two regional news clips — newest, not best. The cheap signals
+   that *could* gate this (duration, live status) are fetched by ADR-023's `videos.list`
+   enrichment at discovery and then **thrown away**: the `videos.duration_s` column (migration
+   001) was never written.
+2. **Weakest model on the first impression.** All burst summaries ran on `koala/phi4-mini` — the
+   documented weak link (ADR-022 was born from its failures). The stronger, brain-validated
+   `iguana/gemma4-26b` was never used, even though the burst is only ~3 summaries.
+3. **Cached-first instant summaries — REJECTED.** The idea: skip the fetch, summarize
+   already-cached transcripts (ADR-021) instantly. The pilot numbers kill it — only **11 videos**
+   overlap between the two users (~3% of each ~350–400-video library), **0** cached-and-
+   unsummarized, and a new user's newest-20 unsummarized are **20/20 NOT cached**. Newest-first
+   and cached-first are structurally incompatible: fresh uploads are exactly what nobody has
+   fetched. An empty lever at pilot scale.
+
+**Decision.**
+1. **Persist `duration_s` at discovery.** `filterLowValue` (ADR-023) already has each candidate's
+   duration in hand; carry it onto the kept `domain.Video` and have `UpsertVideo` write it,
+   COALESCE-preserving a known value (the channel-title backfill stance, migration 014). No new
+   migration — the column exists. The connect-triggered discovery pass runs *before* the burst,
+   so a fresh user's candidates are enriched in time.
+2. **Junk-avoiding selection.** A new `OnboardBurstVideoIDs(userID, limit, minSeconds, maxSeconds)`
+   keeps the newest-first order but drops a video when its duration is *known* and outside
+   `[minSeconds, maxSeconds]` — `minSeconds` = `TAPIR_MIN_VIDEO_SECONDS` (60, the Shorts floor),
+   `maxSeconds` = new `TAPIR_ONBOARD_MAX_VIDEO_SECONDS` (default 14400 = 4h, to drop multi-hour
+   livestream VODs that pass the live filter once ended). A NULL duration is **unknown** — kept
+   (degrade-open) but ranked after known-good rows. **has-captions stays un-gateable pre-fetch**
+   (only knowable after a gate fetch or a ~0-probability cache hit); selection only *avoids
+   known-junk*, it does not *promise* captions.
+3. **Stronger model for the burst only.** `TAPIR_ONBOARD_SUMMARIZER_MODEL` (default
+   `iguana/gemma4-26b`) leads a burst-specific summarizer chain (onboard model first, then the
+   standard ADR-022 chain as resilience, deduped), wrapped in a burst-specific processor over the
+   *same* store/cache/sink — a pure wiring choice; the engine and ports are unchanged (ADR-003).
+   Empty or equal-to-primary collapses the burst back onto the shared processor.
+
+**Not a throughput change.** The caption rate gate (ADR-014) and the foreground priority lane
+(ADR-026) are untouched — same pacing, same cap. This changes *which* ≤3 videos the burst spends
+its fetches on and *which model* summarizes them, never how fast or how many. The engine's
+existing read-stored-first (ADR-021) is unchanged and still yields a free instant summary on the
+rare cache hit — we simply do not *select* for cache hits.
+
+**Consequences.** Better odds of a strong first session: the burst avoids the obvious junk and
+runs the better model on the one impression that decides return. The selection improvement is
+forward-looking — existing rows have NULL `duration_s` until their next discovery pass backfills
+it (lazy, like channel_title); a brand-new user benefits immediately because connect-discovery
+runs first. `duration_s` becoming live also unblocks future length-aware features (feed sorting,
+"long read" badges) for free.
+
+**Reversibility.** Pure config + wiring + one column write + one query, no migration.
+`TAPIR_ONBOARD_MAX_VIDEO_SECONDS=0` (and `TAPIR_MIN_VIDEO_SECONDS=0`) restores pure newest-first;
+`TAPIR_ONBOARD_SUMMARIZER_MODEL=""` collapses the burst back to the shared processor.
+Spec: `docs/specs/onboarding-wow-burst.md`.
+
+---
+
+## ADR-029 — Stateless session cookie (survives restarts, browser-close, idle)
+
+**Status:** Accepted (2026-06-11). Triggered by pilot feedback: "lots of clicking to log in again
+on iPhone." Supersedes the in-memory session store in the ADR-011 login.
+
+**Context.** Three compounding causes made users re-login constantly:
+1. **In-memory session store** (`sessionStore` map) — wiped on every pod restart, so each deploy
+   logged everyone out. During the active build period that was ~15 logouts.
+2. **1-hour session TTL** — for a "check back tomorrow" reader, idle > 1h forced a re-login on
+   nearly every visit.
+3. **No cookie Max-Age** — a session cookie (deleted on browser/app close); iPhone Safari closing
+   the tab dropped it.
+Each re-login is the full Dex/Authentik redirect dance — many taps on mobile.
+
+**Decision.** Make the session **stateless**: the identity (subject + email) and an absolute
+expiry live INSIDE the existing HMAC-signed (HS256) cookie — no server-side table. Plus:
+- **30-day sliding TTL** (was 1h), re-signed on each request so an active user never lapses.
+- **Persistent cookie** (`Max-Age` set) so it survives browser/app close.
+The cookie is HttpOnly + Secure + SameSite=Lax; the HMAC (keyed by the stable ESO
+`tapir-session-secret`, which does NOT rotate per deploy) makes it tamper-proof. The payload is
+identity, not secrets — the OIDC access/ID tokens are still discarded after callback.
+
+**Consequences.** A deploy/restart no longer logs anyone out (proven by a test: a cookie issued by
+one instance is accepted by a fresh instance with the same secret); works across replicas for
+free. **Trade:** no server-side revocation — `logout` clears the cookie client-side, but a copied
+cookie stays valid until expiry. Accepted for the Stage-0 reader pilot; revisit (server-side
+revocation list, or shorter TTL + refresh) if it ever holds sensitive actions. Rotating
+`tapir-session-secret` invalidates all sessions — the global logout lever.
+
+**Not addressed here:** the tap-count of the IdP login page itself is Authentik's UX; with
+re-login now rare (30-day idle or explicit logout), it matters far less.
+
+---
+
+## ADR-030 — Observability: slog timing + Prometheus metrics (AI-focused)
+
+**Status:** Proposed (2026-06-11). Issue #15. **Draft for review — no code yet.**
+
+**Context / requirements.** Nothing measures the activities that drive Tapir's performance and
+UX, and the Stage-0 eval gate (ADR-016) needs a *performance* dimension to sit beside the
+return-usage one. We need timing for: caption fetches (the scarce op), summarization (which model
+won, how long, fallbacks), Q&A latency, LLM token spend, and basic session/usage (request rate,
+latency by route, logins). Requirements:
+- R1: structured `slog` timing at each AI call site (human-readable, already the logging stack).
+- R2: Prometheus metrics for the same, scrapeable by the cluster's prometheus-operator.
+- R3: **AI metrics are the priority** — summarize latency by `model`/`outcome`/`fallback`,
+  caption-fetch latency by `outcome`, chat latency by `model`, and LLM `tokens` by model+kind.
+- R4: HTTP/session metrics via middleware — request count + latency by route, logins.
+- R5: bounded label cardinality (no per-user, no raw-path labels).
+- R6: `/metrics` must NOT be publicly exposed.
+
+**Decision / architecture.**
+1. **New package `internal/metrics`** owns all Prometheus collectors + a typed API
+   (`ObserveSummarize`, `ObserveCaptionFetch`, `ObserveChat`, `RecordTokens`, `IncLogin`,
+   `HTTPMiddleware`, `Handler`). Adapters call this API; they never import prometheus types.
+2. **New dependency `github.com/prometheus/client_golang`.** Justification: it is *the* standard
+   Go Prometheus client and the cluster already runs prometheus-operator; hand-rolling exposition
+   is not worth it. (Needs the dep-justification note in the commit per repo rules.)
+3. **The copied `llm` package stays stdlib-only (ADR-004).** It must not import `internal/metrics`.
+   Token usage is surfaced via an **optional callback** `llm.WithUsageHook(func(model string, prompt, completion int))`
+   set at wiring time (`buildSummarizer`/`buildChat`) to `metrics.RecordTokens`; `llm.Client` only
+   gains parsing of the response `usage` block. Our own adapters (`summarizer`, `youtube`, `chat`)
+   may import `internal/metrics` directly.
+4. **HTTP middleware** reads `r.Pattern` AFTER routing (Go 1.22 sets it during ServeMux match), so
+   the `route` label is the bounded registered pattern (`GET /v/{videoId}`), satisfying R5;
+   unmatched → `other`.
+5. **Dedicated metrics port** (`TAPIR_METRICS_ADDR`, default `:9090`) served by a second
+   `http.Server` in `cmdServe`; `/metrics` is never on the public app mux (R6). A **PodMonitor**
+   in `mathias/infra` scrapes it; the deployment exposes the port.
+6. **slog** elapsed fields are emitted alongside each metric at the call sites (R1).
+
+**Hook points (where the instrumentation lands).**
+- `summarizer.Summarize` — per-endpoint timing + outcome (`success`/`parse_error`/`error`) + fallback flag.
+- `youtube.FetchTranscript` — fetch timing + outcome from `domain.Transcript.Source`.
+- `chat.Service` answer — timing by model.
+- `llm.Client.Complete` — parse `usage`, fire the usage hook.
+- `oidc.handleCallback` — `IncLogin`.
+- `cmdServe` — wrap `Router()` in `metrics.HTTPMiddleware`; start the metrics server.
+
+**Out of scope / later.** Persisting per-summary latency into Postgres for `tapir report`
+(derive UX latency — publish/discovery → summary — from existing timestamps first; only persist
+op-latency if the scrape proves insufficient). SPA view (#16) and visual refresh (#17).
+
+**Reversibility.** Additive: a new package + middleware + a metrics port. Removing the PodMonitor
+stops scraping; the app is unaffected. No schema change.
+
+**Next steps (gated):** on approval of this ADR → BDD scenarios (`docs/use-cases/observability.feature`
++ scenario-coverage map) → TDD → implement → SemVer + docs + PodMonitor.
+
+---
+
+## ADR-031 — SPA-like reader: inline-expand summary + Q&A in the list (HTMX, no framework)
+
+**Status:** Proposed (2026-06-12). Issue #16. **Draft for review — no code yet.**
+
+**Context / requirements.** The reader is multi-page: a list of compact cards (`/`), then a
+navigation to a separate detail page (`/v/{id}`) for the full summary + the docked chat (ADR-027).
+It feels less fluid than a single integrated view. We want the full summary AND the per-video
+Q&A to open **in place in the list**, no page hop. Requirements:
+- R1: clicking a summarized card expands it in place to the full summary (summary/highlights/
+  takeaways) + the chat dock; a collapse returns it to the compact card.
+- R2: **no SPA framework** — stay HTMX + Templ (ADR-003); reuse existing fragments, not a rewrite.
+- R3: **progressive enhancement** — with JS off, the card link still navigates to `/v/{id}`
+  (the detail page stays as the no-JS + deep-link surface). Nothing becomes JS-only.
+- R4: only **summarized** cards expand; pending/rate-limited/no-caption cards keep their current
+  footer behaviour (Summarize button, waiting/none states).
+- R5: chat inside an expanded card works exactly as on the detail page (reuse `chatReveal`/
+  `chatSection` + the existing `/v/{id}/chat` endpoints, unchanged).
+
+**Decision / architecture.**
+1. **Reuse the existing fragments.** `summaryBody(r)` and `chatReveal(videoID)` already exist and
+   render the detail page; a new `expandedCard(r, chatEnabled)` composes the compact header + a
+   collapse control + `summaryBody` + `chatReveal`. `DetailPage` is refactored to also compose
+   `summaryBody` so the two never drift (DRY).
+2. **Two fragment endpoints** (mirroring the existing list/status HTMX fragment pattern):
+   `GET /v/{videoId}/expand` → `expandedCard`; collapse reuses the existing compact `VideoCard`
+   via `GET /v/{videoId}/card`. Both are list-card `<li>` fragments with the SAME `id`
+   (`video-{id}`), swapped `outerHTML` — same mechanism as `processingCard`/`VideoCard` today.
+3. **The compact card's title/"Read" affordance** becomes `hx-get=/v/{id}/expand`,
+   `hx-target=#video-{id}`, `hx-swap=outerHTML`, with `href=/v/{id}` as the no-JS fallback (R3).
+   The expanded card's collapse control is the inverse (`hx-get=/v/{id}/card`).
+4. **Only when `r.Summarized`** does the expand affordance render (R4); the other states are
+   unchanged.
+5. **v1 does NOT push the URL** (`hx-push-url`) — expand/collapse is ephemeral list UI state; the
+   detail page remains the deep-link/shareable URL. Deep-linking the open state via `hx-push-url`
+   is noted as a later option (needs list-state restore on back).
+
+**Out of scope / later.** URL push / deep-linkable open state; the visual refresh (#17) — though
+the expanded-card markup is where #17's TUI/charm styling will land, so they pair.
+
+**Reversibility.** Additive: two fragment endpoints + one templ + an affordance swap on the
+compact card. Removing the affordance reverts to plain list→detail navigation; the detail page is
+untouched. No schema change.
+
+**Next steps (gated):** on approval → BDD (`docs/use-cases/inline_expand.feature` + coverage
+map) → TDD → implement → SemVer + docs.
+
+---
+
+## ADR-032 — Visual refresh: one charm-reader layout, light + dark themes
+
+**Status:** Proposed (2026-06-12). Issue #17. **Draft for review — no code yet.** Follows the
+sketch-first explore step (3 throwaway mockups in `docs/sketches/`, screenshotted for review).
+
+**Context / decision.** The UI is flat. From the mockups, directions **B (light reader + charm)**
+and **C (dark cozy terminal)** are the SAME layout — readable sans body, monospace meta, charm
+palette accents, lipgloss-style bordered cards — in two palettes. Direction A (full-monospace TUI)
+is dropped as too heavy to read long summaries. Decision: ship that one layout with **both a light
+theme (B) and a dark theme (C)**, user-toggleable, defaulting to the OS preference.
+
+**Requirements.**
+- R1: one set of markup/structure; the two themes are pure palette (CSS variables), no duplicate templates.
+- R2: a **theme toggle** persisted across visits; default to `prefers-color-scheme` when no choice stored.
+- R3: charm language in both — mint/purple/pink accents, mono meta + section labels, lipgloss
+  bordered/gradient cards, the (fixed) ASCII tapir; readable sans body.
+- R4: style the existing pieces — list, compact card, **expanded card incl. the already-present
+  video embed (ADR-031/summaryBody)**, detail page, chat dock, the queue note, the charm spinner.
+- R5: WCAG-AA contrast for body text in BOTH themes; keep `prefers-reduced-motion` (already honoured).
+- R6: stay HTMX+Templ; no CSS framework.
+
+**Architecture.**
+1. **Palette as CSS variables.** `:root` holds the light (B) tokens; `:root[data-theme="dark"]`
+   holds the dark (C) tokens; a `prefers-color-scheme: dark` media block sets the dark tokens when
+   no explicit `data-theme` is set. All component CSS references variables only (R1). The existing
+   `CharmMint/Purple/Pink/Cream/Dim` Go consts remain the source for the spinner's inline colours.
+2. **Theme toggle** = a small inline script (a dozen lines, no framework) in `Layout`: on load,
+   apply stored theme (localStorage) or fall through to the media query; a header toggle button
+   flips `data-theme` on `<html>` and stores it. This is the one new bit of JS; everything else
+   stays server-rendered + HTMX. (Considered: cookie + server-render — rejected, a full round-trip
+   per toggle is clunky for a pure presentation flip.)
+3. **Scope = the `styleTag` CSS in `view.go`** (the single style source) plus tiny class hooks in
+   the templ where needed; content/structure are unchanged, so existing view tests keep passing.
+
+**Verification.** The deployed UI is behind auth (web-shot can't log in), so visual review is via
+the mockups now + a styled full-set mockup screenshot before merge, then a live eyeball on device.
+Automated tests stay structural/behavioural (theme tokens present, toggle persists, expanded card
+embeds the video, no-JS still renders a readable default) — colours are not unit-tested.
+
+**Reversibility.** A CSS theme swap + one small script + a few class hooks; revert `styleTag` to
+roll back. No schema, no structural change.
+
+**Next steps (gated):** on approval → BDD (`docs/use-cases/visual_theme.feature` + coverage map)
+→ TDD → implement → SemVer + docs.
+
+---
+
 ## Rejected alternatives
 
 Approaches considered during the 2026-06-02 planning + grill session and **deliberately not
@@ -503,13 +1328,16 @@ maps to the ADR that settles it.
 | Lifting shared packages into a `brain-common` module | Couples Tapir's release cycle to the monolith for negligible code savings | ADR-004 |
 | Importing/replicating the filesystem `brain` package | Assumes co-location with the brain git checkout; wrong for a standalone networked service | ADR-005 |
 | Reusing `ingestion`'s `oauth` package for YouTube/Vimeo | Same name, opposite direction — it's inbound MCP-server auth, not outbound provider OAuth | ADR-006 |
-| Global cross-tenant `videos`/`transcripts` table (dedup) | Reintroduces the cross-domain DB coupling the homelab review is removing; at 1–5 users, re-summarizing is cheaper than the coupling | data-model.md |
+| Global cross-tenant `videos`/`transcripts` table (dedup) | Reintroduces the cross-domain DB coupling the homelab review is removing; at 1–5 users, re-summarizing is cheaper than the coupling. **Transcripts half reopened by ADR-021** — the avoided cost there is a rate-gated, reputation-risky *caption fetch*, not LLM re-summarization, so it outweighs the coupling; **videos stay per-user.** | data-model.md, **ADR-021** (transcripts only) |
 | Audio-download + Whisper STT in the core path | ToS-grey, breakage-prone (yt-dlp), contends for koala GPU with the JEPA PoC; captions alone test the core hypothesis | ADR-007 |
 | Building multi-tenant SaaS / Google OAuth verification now | "Real users soon" was lowered to Future B; SaaS machinery before the Stage 0 self-use gate is the primary documented anti-goal | ADR-008, VISION |
 | Delegating the S5 reuse spike to an agent swarm | A 1-hour sequential read-and-judge with a single coupled conclusion; orchestration overhead exceeds the work, and it's Diamond-1 judgment the maintainer wanted to own | (process note) |
 | Vault-write SA for per-user OAuth tokens (ESO as runtime write path) | ESO syncs vault→cluster at deploy time, not a runtime write API; a write-SA widens blast radius to shared infra to store app row-data | ADR-015, infra#88 |
 | Supabase for per-user credential storage | Adds a second datastore for a few encrypted strings PG18 already holds; reopens ADR-002 | ADR-015, infra#88 |
 | Feedback-based Stage 0 gate (friends saying it's useful) | Politeness bias makes asked-for feedback the least reliable signal; return-usage is the real test | ADR-016 |
+| Reverse the Dex-write invite flow (Google OIDC only) | Some intended Future-B users won't use Google; OIDC-only leaves them with no onboarding path — invite flow is load-bearing | ADR-017 |
+| k8s CronJob for scheduled discovery (vs in-process) | At Future-B scale the in-process scheduler is simpler to deploy; CronJob's failure-isolation benefit was weighed and traded away knowingly (revisit if >1 replica or load grows) | ADR-018 |
+| Cached-transcript-first onboarding burst (instant, zero-fetch picks) | Live pilot DB: ~3% cross-user video overlap, 0 cached-and-unsummarized, a new user's newest-20 are 20/20 uncached — newest-first and cached-first are structurally incompatible. Empty lever at pilot scale | ADR-028 |
 
 If a future case genuinely reopens one of these, that's a new ADR superseding the relevant one —
 not a silent reversal.

LANGUAGE.md

@@ -0,0 +1,26 @@
+# Vocabulary (hand-written pilot 2026-06 — will be generated by langgen in Phase 2)
+
+| Term | Means | Never say |
+|---|---|---|
+| transcript | Captions-first text of a video; the source for summarizing. Shared store keyed by `(provider, video_id)`. | "subtitles file", "the audio" |
+| video | Per-user record of a seen video; the unit of work. Not globally deduped. | "the shared video" |
+| subscription | A watched channel on a user's connection that Tapir polls for new videos. | "feed", "follow" |
+| summary | A video's produced output: summary text + highlights + takeaways + AI provenance. | "transcript" |
+| highlight | A notable point pulled from a video (`Summary.Highlights`). | "takeaway" |
+| takeaway | An actionable conclusion from a video (`Summary.Takeaways`). | "highlight" |
+| sink | A delivery destination for a summary (`store`, `brain`). New one = new adapter. | "the database" |
+| AI router | Local-first chain: local Primary → local fallback → external worst-case. | "the API" |
+| BYO-AI fallback | User's own external AI key, used only when local fails; opt-in. Without it, content is never sent externally. | "the default AI" |
+| brain | Persistent homelab knowledge store; in Tapir, one optional HTTP sink (`brain_ingest`), not the filesystem package. | "the database", "the store" |
+| LiteLLM gateway | Local AI gateway (`koala:30401/v1`); the Primary in the AI router. | "piguard:4000", "koala:4000", "the cloud" |
+| connection | A connected video account a user authorizes via OAuth; subscriptions hang off it. | "login", "session" |
+
+## Caveman rubric
+Before any HIGH/CRITICAL operation, output one line:
+`caveman: me <verb> <object>, not <excluded thing>`
+Valid iff: (1) only vocabulary terms + plain verbs, (2) a stranger could identify
+the exact operation, (3) names one thing explicitly NOT being done.
+
+Examples:
+- `caveman: me delete user connection, not the shared transcript`
+- `caveman: me send transcript to BYO-AI fallback, not the LiteLLM gateway`

README.md

@@ -37,7 +37,7 @@ model, behavior specs) remain the source of intent.
 
 ## Running the Stage-0 demo
 
-Tapir runs on **your own** YouTube account: authorize once, then run the
+Tapir runs on your YouTube account(s): authorize once, then run the
 watch→summarize→deliver loop. All configuration is via `TAPIR_*` environment
 variables — copy [`.env.example`](.env.example) to `.env` and fill it in (no
 secrets are committed; at demo time source them from op, e.g. `op run -- ...`).
@@ -56,7 +56,7 @@ go build -o bin/tapir ./cmd/tapir
 ./bin/tapir auth
 
 # 3. run: detect new videos across your subscriptions, summarize, deliver to the
-#    store. Unset TAPIR_POLL_INTERVAL = single pass; set it (e.g. 15m) to loop.
+#    store. Single pass; set TAPIR_DISCOVERY_INTERVAL (e.g. 2h) for the serve loop.
 ./bin/tapir run
 ```
 
@@ -68,6 +68,18 @@ URI matches `TAPIR_OAUTH_REDIRECT_ADDR`. The summarizer model
 (`TAPIR_SUMMARIZER_MODEL`, default `koala/phi4-mini`) is overridable; pick the
 final alias when the gateway is reachable (see `docs/homelab-integration.md`).
 
+### Web surface (`tapir serve`)
+
+`tapir serve` starts the HTMX+Templ web UI on `:8080`. Users log in via Dex OIDC (local
+password or Google); a new Dex subject is routed to `/register` to create a Tapir account.
+Stage 1 is multi-user: each user connects their own YouTube account from the browser and
+manages their own summaries under DB-enforced RLS isolation. When `TAPIR_DISCOVERY_INTERVAL`
+is set (e.g. `2h`), the serve process runs a scheduled discovery pass for every registered
+user automatically — no CronJob required. In auto mode only videos published within
+`TAPIR_AUTO_SUMMARIZE_WINDOW` (default ~7d, ADR-020) are summarised automatically; older videos
+are listed and summarised on demand, so a large back-catalogue doesn't keep re-driving the
+caption rate gate. See `docs/homelab-integration.md` for the full config reference.
+
 ### Headless on koala
 
 koala has no browser and no interactive `op` session, so the two interactive

VISION.md

@@ -90,6 +90,11 @@ to the next stage's ambition until the current stage's test passes.
   table (see infra/Tapir build) answers "returned/read in ≥2 distinct weeks" even without an
   action click — the honest signal for a *reading* product. Login events accrue only from their
   deploy date onward, so the gate window's data begins then.
+- **Gate-clock reset (ADR-018).** The 3–4 week window starts when in-process scheduled discovery
+  + auto-summarize ship — before that, unprompted use was impossible, so the prior window
+  measured nothing (this is starting the clock when the experiment can actually run, not a reset
+  to dodge a failing gate). The 2026-07-01 check-in referenced above moves accordingly to ~3–4
+  weeks after this deploys. See DECISIONS.md ADR-018.
 - **This is the gate.** Hardening (Stage 1) and any SaaS ambition stay deferred until this
   behavioural signal exists. Note: multi-user machinery was deliberately built *ahead* of
   this gate (ADR-012) with isolation enforced — that was an explicit, recorded call, not a

cmd/tapir/chat_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"git.d-ma.be/mathias/tapir/internal/config"
+)
+
+// TestChatModelsReuseTheChainLocalFirst: the switcher offers the ADR-022 chain in
+// order, deduped — primary, local fallback, cloud.
+func TestChatModelsReuseTheChainLocalFirst(t *testing.T) {
+	got := chatModels(config.Config{
+		SummarizerModel:    "koala/phi4-mini",
+		FallbackModel:      "iguana/gemma4-26b",
+		CloudFallbackModel: "berget/mistral-small",
+	})
+	want := []string{"koala/phi4-mini", "iguana/gemma4-26b", "berget/mistral-small"}
+	if strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("chatModels = %v, want %v", got, want)
+	}
+}
+
+// TestChatCloudModelAbsentWhenDisabled: the local-first / NDA lever — with the
+// cloud fallback empty (TAPIR_CLOUD_FALLBACK_MODEL=""), no external model is
+// offered in the switcher, so chat content never leaves the local stack (ADR-027,
+// honouring ADR-022's "content stays local" guarantee).
+func TestChatCloudModelAbsentWhenDisabled(t *testing.T) {
+	got := chatModels(config.Config{
+		SummarizerModel:    "koala/phi4-mini",
+		FallbackModel:      "iguana/gemma4-26b",
+		CloudFallbackModel: "",
+	})
+	for _, m := range got {
+		if strings.HasPrefix(m, "berget/") || strings.Contains(m, "mistral") {
+			t.Fatalf("cloud model %q offered though the cloud fallback is disabled", m)
+		}
+	}
+	want := []string{"koala/phi4-mini", "iguana/gemma4-26b"}
+	if strings.Join(got, ",") != strings.Join(want, ",") {
+		t.Fatalf("chatModels = %v, want %v", got, want)
+	}
+}
+
+// TestChatModelsDedup: a config that reuses one alias across slots collapses to a
+// single switcher entry (no duplicate options).
+func TestChatModelsDedup(t *testing.T) {
+	got := chatModels(config.Config{
+		SummarizerModel:    "koala/phi4-mini",
+		FallbackModel:      "koala/phi4-mini",
+		CloudFallbackModel: "",
+	})
+	if len(got) != 1 || got[0] != "koala/phi4-mini" {
+		t.Fatalf("chatModels = %v, want a single deduped entry", got)
+	}
+}
+
+// TestBuildChatNilWithoutGateway: no gateway → no chat backend (routes unmounted,
+// read path unaffected).
+func TestBuildChatNilWithoutGateway(t *testing.T) {
+	if c := buildChat(config.Config{GatewayURL: ""}); c != nil {
+		t.Fatal("buildChat must return nil without a gateway URL")
+	}
+}

cmd/tapir/discovery.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+
+	"git.d-ma.be/mathias/tapir/internal/runner"
+)
+
+// discoveryRunner runs one user's discovery pass.
+type discoveryRunner func(ctx context.Context, userID string) (runner.Stats, error)
+
+// serialize wraps run so calls never overlap: every discovery pass — scheduled
+// or connect-triggered (#6) — acquires the same lock, preserving the
+// one-fetcher-at-a-time invariant the scheduler relies on (ADR-018, the
+// single-replica assumption). Locking is per-user, so a connect-triggered pass
+// interleaves between the scheduler's users instead of waiting for a whole pass.
+func serialize(mu *sync.Mutex, run discoveryRunner) discoveryRunner {
+	return func(ctx context.Context, userID string) (runner.Stats, error) {
+		mu.Lock()
+		defer mu.Unlock()
+		return run(ctx, userID)
+	}
+}
+
+// discoveryTrigger fires an out-of-band discovery pass for one user without
+// blocking the caller (the connect HTTP handler). The pass runs on the server's
+// long-lived ctx — not the request ctx — so it survives the post-connect
+// redirect. run is the serialized runner, so a trigger never overlaps the
+// scheduler. Satisfies web.DiscoveryTrigger.
+type discoveryTrigger struct {
+	ctx context.Context
+	run discoveryRunner
+	// onboard, when set, runs after the discovery pass to summarize a capped number
+	// of the user's newest videos (Feature 1). Optional.
+	onboard func(ctx context.Context, userID string)
+	log     *slog.Logger
+}
+
+func (t *discoveryTrigger) Enqueue(userID string) {
+	go func() {
+		if _, err := t.run(t.ctx, userID); err != nil {
+			t.log.Warn("discovery: connect-triggered pass had errors", "user", userID, "err", err)
+		}
+		if t.onboard != nil {
+			t.onboard(t.ctx, userID)
+		}
+	}()
+}

cmd/tapir/discovery_test.go

@@ -0,0 +1,62 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/runner"
+)
+
+// serialize must guarantee at most one discovery pass runs at a time, so a
+// connect-triggered pass never fetches concurrently with the scheduler.
+func TestSerializeRunsOneAtATime(t *testing.T) {
+	var active, maxActive int32
+	run := func(_ context.Context, _ string) (runner.Stats, error) {
+		n := atomic.AddInt32(&active, 1)
+		for { // record the high-water mark of concurrent runs
+			m := atomic.LoadInt32(&maxActive)
+			if n <= m || atomic.CompareAndSwapInt32(&maxActive, m, n) {
+				break
+			}
+		}
+		time.Sleep(2 * time.Millisecond)
+		atomic.AddInt32(&active, -1)
+		return runner.Stats{}, nil
+	}
+
+	s := serialize(&sync.Mutex{}, run)
+	var wg sync.WaitGroup
+	for i := 0; i < 20; i++ {
+		wg.Add(1)
+		go func(i int) { defer wg.Done(); _, _ = s(context.Background(), fmt.Sprintf("u%d", i)) }(i)
+	}
+	wg.Wait()
+
+	require.Equal(t, int32(1), atomic.LoadInt32(&maxActive),
+		"serialize must run at most one pass at a time")
+}
+
+// Enqueue runs the user's pass out-of-band (non-blocking) on the trigger's ctx.
+func TestDiscoveryTriggerEnqueueRunsUser(t *testing.T) {
+	done := make(chan string, 1)
+	run := func(_ context.Context, userID string) (runner.Stats, error) {
+		done <- userID
+		return runner.Stats{}, nil
+	}
+	tr := &discoveryTrigger{ctx: context.Background(), run: run, log: quietLog()}
+
+	tr.Enqueue("u1")
+
+	select {
+	case got := <-done:
+		require.Equal(t, "u1", got)
+	case <-time.After(2 * time.Second):
+		t.Fatal("Enqueue did not run the user's pass")
+	}
+}

cmd/tapir/env.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 	"os"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // Env var names for the read-only CLI. DSN and user id are never hardcoded — the

cmd/tapir/format_test.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 func TestFormatListColumnsAndOrdering(t *testing.T) {

cmd/tapir/invite.go

@@ -1,61 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"os"
-	"strings"
-	"time"
-
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/config"
-)
-
-// inviteTTL is how long a minted invite stays claimable. A week is generous for a
-// human to act on an emailed link without leaving a stale capability around.
-const inviteTTL = 7 * 24 * time.Hour
-
-// inviter is the narrow store capability cmdInvite needs — minting an invitation.
-// Defined here (not store) so runInvite is testable with a fake, no Postgres.
-type inviter interface {
-	CreateInvitation(ctx context.Context, email string, ttl time.Duration) (string, error)
-}
-
-// cmdInvite mints an invitation for an email and prints the claim URL. Host-side
-// only (no Dex session): the operator runs it, copies the link, and sends it.
-// Usage: tapir invite <email>.
-func cmdInvite(ctx context.Context, args []string) error {
-	if len(args) < 1 || strings.TrimSpace(args[0]) == "" {
-		return fmt.Errorf("usage: tapir invite <email>")
-	}
-	email := strings.TrimSpace(args[0])
-
-	cfg, err := config.Load()
-	if err != nil {
-		return err
-	}
-	if strings.TrimSpace(cfg.DBDSN) == "" {
-		return fmt.Errorf("missing required config: TAPIR_DB_DSN")
-	}
-
-	st, err := store.New(ctx, cfg.DBDSN)
-	if err != nil {
-		return err
-	}
-	defer st.Close()
-
-	return runInvite(ctx, st, os.Stdout, cfg.PublicURL, email)
-}
-
-// runInvite is the testable core: mint the token and print the absolute claim URL
-// to w. Pure of config/store construction so a fake inviter exercises it.
-func runInvite(ctx context.Context, inv inviter, w io.Writer, publicURL, email string) error {
-	token, err := inv.CreateInvitation(ctx, email, inviteTTL)
-	if err != nil {
-		return fmt.Errorf("create invitation: %w", err)
-	}
-	base := strings.TrimRight(strings.TrimSpace(publicURL), "/")
-	_, err = fmt.Fprintf(w, "Invite URL (valid 7 days):\n%s/invite/%s\n", base, token)
-	return err
-}

cmd/tapir/invite_test.go

@@ -1,59 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/stretchr/testify/require"
-)
-
-// fakeInviter records the mint call and returns a canned token.
-type fakeInviter struct {
-	token     string
-	err       error
-	gotEmail  string
-	gotTTL    time.Duration
-	callCount int
-}
-
-func (f *fakeInviter) CreateInvitation(_ context.Context, email string, ttl time.Duration) (string, error) {
-	f.callCount++
-	f.gotEmail, f.gotTTL = email, ttl
-	return f.token, f.err
-}
-
-func TestRunInvitePrintsURL(t *testing.T) {
-	inv := &fakeInviter{token: "deadbeefcafe"}
-	var out strings.Builder
-
-	err := runInvite(context.Background(), inv, &out, "https://tapir.d-ma.be", "new@example.com")
-	require.NoError(t, err)
-
-	require.Equal(t, "new@example.com", inv.gotEmail)
-	require.Equal(t, inviteTTL, inv.gotTTL)
-	got := out.String()
-	require.Contains(t, got, "https://tapir.d-ma.be/invite/deadbeefcafe")
-	require.Contains(t, got, "valid 7 days")
-}
-
-func TestRunInviteTrimsTrailingSlash(t *testing.T) {
-	inv := &fakeInviter{token: "tok"}
-	var out strings.Builder
-
-	err := runInvite(context.Background(), inv, &out, "https://tapir.d-ma.be/", "x@example.com")
-	require.NoError(t, err)
-	require.Contains(t, out.String(), "https://tapir.d-ma.be/invite/tok")
-	require.NotContains(t, out.String(), "//invite")
-}
-
-func TestRunInvitePropagatesError(t *testing.T) {
-	inv := &fakeInviter{err: errors.New("db down")}
-	var out strings.Builder
-
-	err := runInvite(context.Background(), inv, &out, "https://tapir.d-ma.be", "x@example.com")
-	require.Error(t, err)
-	require.Empty(t, out.String())
-}

cmd/tapir/list.go

@@ -9,7 +9,7 @@ import (
 	"strings"
 	"text/tabwriter"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // runList prints the user's stored summaries as a table, most recent first.

cmd/tapir/main.go

@@ -20,16 +20,18 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"sync"
 	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/dex"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/secrets"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/auth"
-	"gitea.d-ma.be/mathias/tapir/internal/config"
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
-	"gitea.d-ma.be/mathias/tapir/internal/web/oidc"
+	"git.d-ma.be/mathias/tapir/internal/adapters/secrets"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/youtube"
+	"git.d-ma.be/mathias/tapir/internal/auth"
+	"git.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/metrics"
+	"git.d-ma.be/mathias/tapir/internal/runner"
+	"git.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web/oidc"
 )
 
 func main() {
@@ -54,8 +56,8 @@ func main() {
 		err = cmdRun(ctx, log)
 	case "serve":
 		err = cmdServe(ctx, log)
-	case "invite":
-		err = cmdInvite(ctx, os.Args[2:])
+	case "report":
+		err = runReport(ctx, os.Args[2:])
 	default:
 		usage()
 		os.Exit(2)
@@ -74,9 +76,9 @@ usage:
   tapir auth              one-time: authorize YouTube and store a refresh token
   tapir run               detect new videos, summarize, deliver to your store
   tapir serve             run the web UI (read summaries, record watch/skip/save)
-  tapir invite <email>    mint an invitation link for a new user (host-side)
   tapir list [-limit N]   list stored summaries, recent first
   tapir show <video-id>   show one summary in full
+  tapir report            Stage-0 usage gate: per-user distinct active weeks
 
 configuration is via TAPIR_* environment variables (see .env.example).
 `)
@@ -129,10 +131,18 @@ func cmdRun(ctx context.Context, log *slog.Logger) error {
 	if engine == nil {
 		return fmt.Errorf("run: incomplete summarization config (gateway, youtube credentials, secrets file)")
 	}
-	r := runner.New(engine.Source, st, engine, cfg.UserID, log, runner.WithBackoff(cfg.FetchBackoff))
+	// Process-wide caption-fetch rate gate (ADR-014 item 2): the batch path shares
+	// the same per-egress-IP limiter as the web click-path.
+	youtube.SetFetchRate(cfg.FetchRate)
+
+	r := runner.New(engine.Source, st, engine, cfg.UserID, log,
+		runner.WithBackoff(cfg.FetchBackoff),
+		runner.WithAutoWindow(cfg.AutoSummarizeWindow),
+		runner.WithCaptionMemory(cfg.ChannelCaptionlessThreshold, cfg.ChannelCaptionlessWindow))
 
 	log.Info("starting run", "user", cfg.UserID, "model", cfg.SummarizerModel,
-		"gateway", cfg.GatewayURL, "poll_interval", cfg.PollInterval, "fetch_backoff", cfg.FetchBackoff)
+		"gateway", cfg.GatewayURL, "poll_interval", cfg.PollInterval, "fetch_backoff", cfg.FetchBackoff,
+		"fetch_rate", cfg.FetchRate, "auto_window", cfg.AutoSummarizeWindow)
 	return r.Loop(ctx, cfg.PollInterval)
 }
 
@@ -156,6 +166,11 @@ func cmdServe(ctx context.Context, log *slog.Logger) error {
 	}
 	defer st.Close()
 
+	// Process-wide caption-fetch rate gate (ADR-014 item 2): the web click-path
+	// and the scheduled-discovery runners share one per-egress-IP limiter so they
+	// cannot collectively trip 429s. Must be set before either path fetches.
+	youtube.SetFetchRate(cfg.FetchRate)
+
 	// Auth seam (handlers depend on web.Auth only). With Dex configured
 	// (TAPIR_OIDC_ISSUER set) serve uses real OIDC login — any Dex subject may
 	// authenticate, then registers a tapir user (ADR-012); otherwise it falls
@@ -181,22 +196,21 @@ func cmdServe(ctx context.Context, log *slog.Logger) error {
 	// The file-backed SecretStore is shared by the connect flow (writes tokens)
 	// and account management (deletes them on disconnect / delete-account).
 	secretStore := secrets.NewFileStore(cfg.SecretsFile)
-	app := &web.App{Store: st, Identity: st, Auth: authn, Secrets: secretStore, Log: log}
+	app := &web.App{Store: st, Identity: st, Auth: authn, Secrets: secretStore, Log: log, RecencyWindow: cfg.AutoSummarizeWindow}
 
-	// Email-invite onboarding (public /invite/{token}). The store validates and
-	// consumes tokens; the Dex client creates the local-password account. In-cluster
-	// the SA token mount is present and account creation works; off-cluster (dev) it
-	// is nil and the submit handler degrades to a clear "deployed-only" message.
-	app.Invitations = st
-	if dexClient, err := dex.NewPasswordClient(); err == nil {
-		app.Dex = dexClient
-		log.Info("invite account creation enabled (in-cluster dex password client)")
-	} else if errors.Is(err, dex.ErrNotInCluster) {
-		log.Warn("invite account creation disabled: not in-cluster — /invite is deployed-only")
-	} else {
-		return fmt.Errorf("dex password client: %w", err)
+	// Per-video deeper-dive chat over the STORED transcript (ADR-027). Enabled
+	// whenever a gateway is configured — it needs no YouTube credentials because it
+	// never fetches. Guarded so a typed-nil never lands in the interface field
+	// (which would mount the routes over a nil backend).
+	if c := buildChat(cfg); c != nil {
+		app.Chat = c
+		log.Info("web chat enabled (stored-transcript only)", "models", chatModels(cfg))
 	}
 
+	// User onboarding is handled by the IdP (Authentik invite flow), not Tapir —
+	// the Dex local-password provisioning path was removed (ADR-019). An
+	// authenticated subject with no Tapir user is routed to /register.
+
 	// Web-initiated YouTube connect (ADR-006). Mounted only when the OAuth client
 	// credentials are present; the refresh token persists through the SecretStore
 	// under a per-user ref (web.YouTubeTokenRef). Live connect also needs the
@@ -207,7 +221,10 @@ func cmdServe(ctx context.Context, log *slog.Logger) error {
 			ClientSecret: cfg.YTClientSecret,
 			RedirectURL:  cfg.YTConnectRedirectURL,
 		}, secretStore, st, log)
-		log.Info("web youtube connect enabled", "redirect", cfg.YTConnectRedirectURL)
+		// Paste-a-URL (Feature 2): same YouTube credentials, per-user adapter built
+		// per request. Mounting the /paste route keys off app.Fetcher being set.
+		app.Fetcher = videoFetcher{cfg: cfg, secrets: secretStore}
+		log.Info("web youtube connect + paste enabled", "redirect", cfg.YTConnectRedirectURL)
 	}
 
 	// Immediate summarization for the web "Summarize" button. When the engine can
@@ -225,18 +242,103 @@ func cmdServe(ctx context.Context, log *slog.Logger) error {
 		log.Info("web summarization is queue-only (incomplete engine config)")
 	}
 
+	// In-process scheduled discovery (ADR-018): when enabled, a background
+	// goroutine runs a discovery pass for ALL users on TAPIR_DISCOVERY_INTERVAL,
+	// reusing the per-user runner.Runner. Cancelled by the same ctx as the server.
+	//
+	// SINGLE-REPLICA ASSUMPTION (load-bearing): this loop lives in the web process.
+	// Running serve at >1 replica would make every replica fetch every user in
+	// parallel — duplicate work and self-inflicted 429s. replicas: 1 is required in
+	// the deployment manifest; scaling up needs a CronJob or leader election first.
+	if cfg.DiscoveryInterval > 0 {
+		log.Info("scheduled discovery enabled", "interval", cfg.DiscoveryInterval, "fetch_rate", cfg.FetchRate)
+		log.Warn("scheduled discovery assumes a SINGLE replica — running serve at >1 replica double-runs discovery (ADR-018)")
+		rawRunUser := func(ctx context.Context, userID string) (runner.Stats, error) {
+			r, err := buildUserRunner(cfg, st, secretStore, userID, log)
+			if err != nil {
+				return runner.Stats{}, err
+			}
+			return r.RunOnce(ctx)
+		}
+		// One lock shared by the scheduler and connect-triggered passes (#6) so
+		// they never fetch concurrently — the single-fetcher invariant (ADR-018).
+		runUser := serialize(&sync.Mutex{}, rawRunUser)
+		// Onboarding burst (Feature 1, refined by ADR-028): after the connect-triggered
+		// discovery pass, summarize up to OnboardSummarizeCount of the user's newest
+		// LIKELY-GOOD unsummarized videos so a fresh account gets a strong first
+		// session. Selection avoids known-junk (Shorts/over-long/livestream VODs via
+		// the persisted duration); the burst leads its chain with the stronger onboard
+		// model. Hard cap; explicit, so it bypasses the recency window — but every
+		// fetch still goes through globalFetchGate. No-op when disabled (count 0) or
+		// queue-only (no processor).
+		//
+		// burstProcessor leads with the stronger model (ADR-028); it collapses onto the
+		// shared Processor when the onboard model is empty/equal-to-primary or the
+		// engine config is incomplete.
+		burstProcessor := app.Processor
+		if burstEngine, berr := buildBurstProcessor(cfg, st); berr != nil {
+			return berr
+		} else if burstEngine != nil {
+			burstProcessor = &engineProcessor{engine: burstEngine, store: st}
+			log.Info("onboarding burst uses a stronger model", "onboard_model", cfg.OnboardSummarizerModel)
+		}
+		onboard := func(ctx context.Context, userID string) {
+			if cfg.OnboardSummarizeCount <= 0 || burstProcessor == nil {
+				return
+			}
+			ids, err := st.OnboardBurstVideoIDs(ctx, userID, cfg.OnboardSummarizeCount, cfg.MinVideoSeconds, cfg.OnboardMaxVideoSeconds)
+			if err != nil {
+				log.Warn("onboarding: list burst candidates", "user", userID, "err", err)
+				return
+			}
+			for _, id := range ids {
+				if err := burstProcessor.ProcessVideo(ctx, userID, id); err != nil {
+					log.Warn("onboarding: summarize", "user", userID, "video", id, "err", err)
+				}
+			}
+			if len(ids) > 0 {
+				log.Info("onboarding burst complete", "user", userID, "summarized", len(ids), "cap", cfg.OnboardSummarizeCount)
+			}
+		}
+		if app.Connect != nil {
+			app.Connect.Discovery = &discoveryTrigger{ctx: ctx, run: runUser, onboard: onboard, log: log}
+			log.Info("connect-triggered discovery enabled", "onboard_cap", cfg.OnboardSummarizeCount)
+		}
+		go runScheduler(ctx, cfg.DiscoveryInterval, st, runUser, log)
+	} else {
+		log.Info("scheduled discovery disabled (TAPIR_DISCOVERY_INTERVAL unset or 0)")
+	}
+
 	srv := &http.Server{
 		Addr:              cfg.HTTPAddr,
-		Handler:           app.Router(),
+		Handler:           metrics.HTTPMiddleware(app.Router()),
 		ReadHeaderTimeout: 10 * time.Second,
 	}
 
+	// Prometheus /metrics on a SEPARATE port (ADR-030) — never on the public app
+	// mux, so a scrape is in-cluster only. Empty TAPIR_METRICS_ADDR disables it.
+	var metricsSrv *http.Server
+	if cfg.MetricsAddr != "" {
+		mmux := http.NewServeMux()
+		mmux.Handle("GET /metrics", metrics.Handler())
+		metricsSrv = &http.Server{Addr: cfg.MetricsAddr, Handler: mmux, ReadHeaderTimeout: 10 * time.Second}
+		go func() {
+			log.Info("serving metrics", "addr", cfg.MetricsAddr)
+			if err := metricsSrv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+				log.Error("metrics server", "err", err)
+			}
+		}()
+	}
+
 	// Graceful shutdown on signal: stop accepting, drain in-flight requests.
 	go func() {
 		<-ctx.Done()
 		shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 		defer cancel()
 		_ = srv.Shutdown(shutdownCtx)
+		if metricsSrv != nil {
+			_ = metricsSrv.Shutdown(shutdownCtx)
+		}
 	}()
 
 	log.Info("serving web ui", "addr", cfg.HTTPAddr, "user", cfg.UserID)

cmd/tapir/processor.go

@@ -3,17 +3,40 @@ package main
 import (
 	"context"
 	"fmt"
+	"strings"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/llm"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/secrets"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/summarizer"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/youtube"
-	"gitea.d-ma.be/mathias/tapir/internal/config"
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/usecase"
+	"git.d-ma.be/mathias/tapir/internal/adapters/chat"
+	"git.d-ma.be/mathias/tapir/internal/adapters/llm"
+	"git.d-ma.be/mathias/tapir/internal/adapters/secrets"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/summarizer"
+	"git.d-ma.be/mathias/tapir/internal/adapters/youtube"
+	"git.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/metrics"
+	"git.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/usecase"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
+// videoFetcher adapts the YouTube adapter to web.VideoFetcher for the paste flow
+// (Feature 2). It builds a per-user adapter bound to that user's token ref and
+// resolves a single video's metadata via the Data API — ungated; only the later
+// transcript fetch goes through globalFetchGate.
+type videoFetcher struct {
+	cfg     config.Config
+	secrets ports.SecretStore
+}
+
+func (f videoFetcher) FetchVideo(ctx context.Context, userID, videoID string) (domain.Video, error) {
+	a := youtube.New(youtube.Config{
+		ClientID:       f.cfg.YTClientID,
+		ClientSecret:   f.cfg.YTClientSecret,
+		TokenSecretRef: web.YouTubeTokenRef(userID),
+	}, f.secrets)
+	return a.VideoByID(ctx, userID, videoID)
+}
+
 // buildProcessor wires the summarization engine — YouTube source (captions-first),
 // AI-router summarizer, store sink — shared by `tapir run` and the web
 // "Summarize now" path so the wiring lives in one place. It returns (nil, nil) —
@@ -22,28 +45,172 @@ import (
 // queue-only fallback: the web UI keeps working (the button just queues) and
 // `tapir run` reports the gap via its own ValidateForRun. Missing engine config
 // is never an error here.
+// buildSummarizer wires the summarization endpoint chain (ADR-022) shared by the
+// web "Summarize now" path and the scheduler's per-user runners. The chain is:
+// primary (local, fast) → local fallback → cloud fallback (worst case). Each
+// endpoint reaches the same LiteLLM gateway with a different model alias — the
+// gateway fronts both llama-swap and berget — so a fallback is just a different
+// alias, not a second client config. Empty model entries are skipped, so a
+// client deployment can set the cloud fallback empty to keep content local.
+func buildSummarizer(cfg config.Config) *summarizer.Summarizer {
+	mk := summarizerEndpoint(cfg)
+	eps := []summarizer.Endpoint{mk(cfg.SummarizerModel)}
+	if cfg.FallbackModel != "" && cfg.FallbackModel != cfg.SummarizerModel {
+		eps = append(eps, mk(cfg.FallbackModel))
+	}
+	if cfg.CloudFallbackModel != "" && cfg.CloudFallbackModel != cfg.SummarizerModel {
+		eps = append(eps, mk(cfg.CloudFallbackModel))
+	}
+	return summarizer.NewChain(eps, cfg.MaxTranscriptChars)
+}
+
+// summarizerEndpoint returns a constructor for a chain endpoint over the one
+// LiteLLM gateway, varying only the model alias (the gateway fronts both
+// llama-swap and berget). Shared by the standard and burst chains.
+func summarizerEndpoint(cfg config.Config) func(model string) summarizer.Endpoint {
+	return func(model string) summarizer.Endpoint {
+		return summarizer.Endpoint{
+			Client:   llm.New(cfg.GatewayURL, cfg.GatewayKey, model, cfg.SummarizerTimeout, llm.WithMaxTokens(cfg.SummaryMaxTokens), llm.WithUsageHook(metrics.RecordTokens)),
+			Provider: providerOf(model),
+			Model:    model,
+		}
+	}
+}
+
+// burstChainModels is the ordered, deduped model list for the onboarding burst
+// (ADR-028): the stronger onboard model leads, then the standard ADR-022 chain
+// (primary → local fallback → cloud) follows as resilience. Empty entries are
+// dropped and duplicates collapsed, so the NDA lever (empty cloud fallback) keeps
+// the burst chain fully local exactly as the standard chain does.
+func burstChainModels(cfg config.Config) []string {
+	var models []string
+	add := func(m string) {
+		if m == "" {
+			return
+		}
+		for _, e := range models {
+			if e == m {
+				return
+			}
+		}
+		models = append(models, m)
+	}
+	add(cfg.OnboardSummarizerModel)
+	add(cfg.SummarizerModel)
+	add(cfg.FallbackModel)
+	add(cfg.CloudFallbackModel)
+	return models
+}
+
+// buildBurstSummarizer builds the onboarding-burst summarizer chain (ADR-028):
+// the onboard model first, then the standard chain as fallback, deduped.
+func buildBurstSummarizer(cfg config.Config) *summarizer.Summarizer {
+	mk := summarizerEndpoint(cfg)
+	var eps []summarizer.Endpoint
+	for _, m := range burstChainModels(cfg) {
+		eps = append(eps, mk(m))
+	}
+	return summarizer.NewChain(eps, cfg.MaxTranscriptChars)
+}
+
+// chatModels is the ordered, local-first set of models offered in the chat
+// switcher (ADR-027), reusing the ADR-022 chain: primary → local fallback →
+// cloud. Empty entries are dropped and duplicates collapsed, so a client/NDA
+// deployment that sets the cloud fallback empty simply has no external model in
+// the switcher — the same local-first lever the summarizer honours.
+func chatModels(cfg config.Config) []string {
+	var models []string
+	add := func(m string) {
+		if m == "" {
+			return
+		}
+		for _, e := range models {
+			if e == m {
+				return
+			}
+		}
+		models = append(models, m)
+	}
+	add(cfg.SummarizerModel)
+	add(cfg.FallbackModel)
+	add(cfg.CloudFallbackModel)
+	return models
+}
+
+// buildChat wires the per-video chat service (ADR-027): a Completer factory over
+// the SAME LiteLLM gateway the summarizer uses (a different alias per model, not a
+// second client config) and the same transcript-truncation budget. It returns nil
+// when no gateway is configured — chat is simply not mounted, the read path is
+// unaffected. It deliberately takes NO YouTube source: chat is stored-only.
+func buildChat(cfg config.Config) *chat.Service {
+	if cfg.GatewayURL == "" {
+		return nil
+	}
+	models := chatModels(cfg)
+	if len(models) == 0 {
+		return nil
+	}
+	newClient := func(model string) chat.Completer {
+		return llm.New(cfg.GatewayURL, cfg.GatewayKey, model, cfg.SummarizerTimeout, llm.WithMaxTokens(cfg.SummaryMaxTokens), llm.WithUsageHook(metrics.RecordTokens))
+	}
+	return chat.New(newClient, models, cfg.MaxTranscriptChars)
+}
+
+// providerOf maps a model alias to the domain AIProvider recorded on summaries.
+// A "berget/" alias is an external provider; everything else is the local stack.
+func providerOf(model string) string {
+	if strings.HasPrefix(model, "berget/") {
+		return "berget"
+	}
+	return "local"
+}
+
 func buildProcessor(cfg config.Config, st *store.Store) (*usecase.Engine, error) {
 	if cfg.GatewayURL == "" || cfg.YTClientID == "" || cfg.YTClientSecret == "" || cfg.SecretsFile == "" {
 		return nil, nil
 	}
 
-	secretStore := secrets.NewFileStore(cfg.SecretsFile)
-	src := youtube.New(youtube.Config{
+	src := newYouTubeSource(cfg, secrets.NewFileStore(cfg.SecretsFile))
+	sum := buildSummarizer(cfg)
+
+	// The store is both the summary sink and the shared transcript cache (ADR-021):
+	// the engine reads stored transcripts before any caption fetch and writes
+	// resolved ones back, so re-analysis never re-touches YouTube.
+	eng := usecase.NewEngine(src, sum, st)
+	eng.Transcripts = st
+	return eng, nil
+}
+
+// newYouTubeSource builds the captions-first VideoSource shared by the standard
+// and burst processors — same per-process YouTube credentials and ADR-023 Shorts
+// filter; only the summarizer chain differs between them.
+func newYouTubeSource(cfg config.Config, secretStore ports.SecretStore) ports.VideoSource {
+	return youtube.New(youtube.Config{
 		ClientID:           cfg.YTClientID,
 		ClientSecret:       cfg.YTClientSecret,
 		TokenSecretRef:     cfg.YTTokenRef,
 		PreferredLanguages: []string{"en"},
+		MinVideoSeconds:    cfg.MinVideoSeconds,
 	}, secretStore)
+}
 
-	// Local Primary only; no BYO fallback for the demo (fallback nil).
-	primary := summarizer.Endpoint{
-		Client:   llm.New(cfg.GatewayURL, cfg.GatewayKey, cfg.SummarizerModel, cfg.SummarizerTimeout),
-		Provider: "local",
-		Model:    cfg.SummarizerModel,
+// buildBurstProcessor wires a processor whose summarizer leads with the stronger
+// onboard model (ADR-028), used only by the connect-time burst over the SAME
+// store / transcript cache / sink — a wiring choice; the engine and ports are
+// unchanged. Returns (nil, nil) — the collapse lever — when the onboard model is
+// empty or equal to the primary (the burst then reuses the shared processor), or
+// when the engine config is incomplete (queue-only, same as buildProcessor).
+func buildBurstProcessor(cfg config.Config, st *store.Store) (*usecase.Engine, error) {
+	if cfg.OnboardSummarizerModel == "" || cfg.OnboardSummarizerModel == cfg.SummarizerModel {
+		return nil, nil
 	}
-	sum := summarizer.New(primary, nil)
-
-	return usecase.NewEngine(src, sum, st), nil
+	if cfg.GatewayURL == "" || cfg.YTClientID == "" || cfg.YTClientSecret == "" || cfg.SecretsFile == "" {
+		return nil, nil
+	}
+	src := newYouTubeSource(cfg, secrets.NewFileStore(cfg.SecretsFile))
+	eng := usecase.NewEngine(src, buildBurstSummarizer(cfg), st)
+	eng.Transcripts = st
+	return eng, nil
 }
 
 // engineProcessor adapts the engine (which works in terms of a domain.Video) to
@@ -58,6 +225,11 @@ type engineProcessor struct {
 }
 
 func (p *engineProcessor) ProcessVideo(ctx context.Context, userID, videoID string) error {
+	// This is the user-initiated (foreground) path — a click on "Summarize",
+	// "Try now", or a pasted URL. Mark the context so the caption gate gives it
+	// priority over the background sweep (ADR-026, Pillar A).
+	ctx = youtube.ForegroundContext(ctx)
+
 	row, err := p.store.GetVideoRow(ctx, userID, videoID)
 	if err != nil {
 		return fmt.Errorf("load video %q: %w", videoID, err)
@@ -77,7 +249,28 @@ func (p *engineProcessor) ProcessVideo(ctx context.Context, userID, videoID stri
 	if err != nil {
 		return fmt.Errorf("process video %q: %w", videoID, err)
 	}
-	if res.Summary != nil {
+
+	// Record the outcome so the status endpoint can show honest state (ADR-025):
+	// a 429'd or caption-less click used to leave transcript_status unset, so the
+	// poll silently reverted to the "Summarize" button. Mirror the runner: stamp
+	// rate_limited / none / fetched. A rate-limited video keeps its requested flag
+	// so the background sweep retries it; none and fetched are terminal here.
+	switch {
+	case res.Skipped && res.TranscriptSource == string(domain.SourceRateLimited):
+		if err := p.store.SetTranscriptStatus(ctx, userID, videoID, "rate_limited"); err != nil {
+			return fmt.Errorf("set rate_limited status %q: %w", videoID, err)
+		}
+	case res.Skipped:
+		if err := p.store.SetTranscriptStatus(ctx, userID, videoID, "none"); err != nil {
+			return fmt.Errorf("set none status %q: %w", videoID, err)
+		}
+		if err := p.store.ClearSummarizeRequested(ctx, userID, videoID); err != nil {
+			return fmt.Errorf("clear summarize flag %q: %w", videoID, err)
+		}
+	case res.Summary != nil:
+		if err := p.store.SetTranscriptStatus(ctx, userID, videoID, "fetched"); err != nil {
+			return fmt.Errorf("set fetched status %q: %w", videoID, err)
+		}
 		if err := p.store.ClearSummarizeRequested(ctx, userID, videoID); err != nil {
 			return fmt.Errorf("clear summarize flag %q: %w", videoID, err)
 		}

cmd/tapir/processor_test.go

@@ -3,7 +3,7 @@ package main
 import (
 	"testing"
 
-	"gitea.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/config"
 )
 
 // TestBuildProcessorNilOnIncompleteConfig asserts the queue-only fallback: when a
@@ -45,3 +45,65 @@ func TestBuildProcessorNilOnIncompleteConfig(t *testing.T) {
 		})
 	}
 }
+
+// TestBurstChainModelsLeadsWithOnboardModel: the onboarding burst chain (ADR-028)
+// leads with the stronger onboard model, then falls back through the standard
+// ADR-022 chain (primary -> local fallback -> cloud), deduped.
+func TestBurstChainModelsLeadsWithOnboardModel(t *testing.T) {
+	got := burstChainModels(config.Config{
+		OnboardSummarizerModel: "iguana/gemma4-26b",
+		SummarizerModel:        "koala/phi4-mini",
+		FallbackModel:          "iguana/gemma4-26b", // also the onboard model -> dedup
+		CloudFallbackModel:     "berget/mistral-small",
+	})
+	want := []string{"iguana/gemma4-26b", "koala/phi4-mini", "berget/mistral-small"}
+	if len(got) != len(want) {
+		t.Fatalf("burstChainModels = %v, want %v", got, want)
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("burstChainModels = %v, want %v", got, want)
+		}
+	}
+}
+
+// TestBurstChainModelsCloudAbsentWhenDisabled: the NDA lever holds for the burst
+// too — empty cloud fallback keeps the burst chain fully local.
+func TestBurstChainModelsCloudAbsentWhenDisabled(t *testing.T) {
+	got := burstChainModels(config.Config{
+		OnboardSummarizerModel: "iguana/gemma4-26b",
+		SummarizerModel:        "koala/phi4-mini",
+		CloudFallbackModel:     "",
+	})
+	for _, m := range got {
+		if m == "" || m == "berget/mistral-small" {
+			t.Fatalf("cloud model leaked into burst chain: %v", got)
+		}
+	}
+}
+
+// TestBuildBurstProcessorNilWhenCollapsed: an empty or primary-equal onboard model
+// collapses the burst onto the shared processor (buildBurstProcessor returns nil).
+func TestBuildBurstProcessorNilWhenCollapsed(t *testing.T) {
+	base := config.Config{
+		GatewayURL:      "http://gw/v1",
+		YTClientID:      "id",
+		YTClientSecret:  "secret",
+		SecretsFile:     "/tmp/secrets.json",
+		SummarizerModel: "koala/phi4-mini",
+	}
+	t.Run("empty onboard model", func(t *testing.T) {
+		base.OnboardSummarizerModel = ""
+		eng, err := buildBurstProcessor(base, nil)
+		if err != nil || eng != nil {
+			t.Fatalf("buildBurstProcessor = (%v, %v), want (nil, nil)", eng, err)
+		}
+	})
+	t.Run("onboard model equals primary", func(t *testing.T) {
+		base.OnboardSummarizerModel = "koala/phi4-mini"
+		eng, err := buildBurstProcessor(base, nil)
+		if err != nil || eng != nil {
+			t.Fatalf("buildBurstProcessor = (%v, %v), want (nil, nil)", eng, err)
+		}
+	})
+}

cmd/tapir/report.go

@@ -0,0 +1,97 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"text/tabwriter"
+	"time"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+)
+
+// gateThreshold is the Stage-0 gate (VISION/ADR-016): usage in >= 2 distinct
+// weeks. The gate passes when any user reaches it.
+const gateThreshold = 2
+
+// defaultGateStart is the date Stage-0 return-usage tracking begins: the morning
+// the pilot was actually unblocked and summaries started flowing (2026-06-11).
+// Activity before this — testing, the period the pilot was stuck on zero — is
+// noise and must not count toward the gate. Override with TAPIR_USAGE_GATE_START
+// (YYYY-MM-DD). The gate measures whether users RETURN once it genuinely works.
+const defaultGateStart = "2026-06-11"
+
+// gateStart resolves the baseline date from TAPIR_USAGE_GATE_START or the default,
+// parsed as a UTC calendar day.
+func gateStart() (time.Time, error) {
+	v := os.Getenv("TAPIR_USAGE_GATE_START")
+	if v == "" {
+		v = defaultGateStart
+	}
+	t, err := time.Parse("2006-01-02", v)
+	if err != nil {
+		return time.Time{}, fmt.Errorf("TAPIR_USAGE_GATE_START=%q: want YYYY-MM-DD: %w", v, err)
+	}
+	return t, nil
+}
+
+// runReport prints the Stage-0 usage gate: per-user distinct active weeks (reads
+// UNION acts) and the pass/fail verdict. Read-only, cross-user — needs only
+// TAPIR_DB_DSN (not TAPIR_USER_ID; the report enumerates all users itself).
+func runReport(ctx context.Context, _ []string) error {
+	dsn := os.Getenv(envDSN)
+	if dsn == "" {
+		return fmt.Errorf("%s is required", envDSN)
+	}
+	s, err := store.New(ctx, dsn)
+	if err != nil {
+		return err
+	}
+	defer s.Close()
+
+	since, err := gateStart()
+	if err != nil {
+		return err
+	}
+
+	rows, err := s.ActiveWeeks(ctx, since)
+	if err != nil {
+		return err
+	}
+	return formatReport(os.Stdout, rows, since)
+}
+
+// formatReport renders the per-user week counts and the gate verdict. Pure: no DB,
+// no env — so the layout and verdict logic are unit-testable without Postgres.
+func formatReport(w io.Writer, rows []store.UserActiveWeeks, since time.Time) error {
+	if _, err := fmt.Fprintf(w, "Counting usage since %s (Stage-0 gate baseline)\n\n", since.Format("2006-01-02")); err != nil {
+		return err
+	}
+	if len(rows) == 0 {
+		_, err := fmt.Fprintln(w, "no users yet")
+		return err
+	}
+
+	tw := tabwriter.NewWriter(w, 0, 4, 2, ' ', 0)
+	_, _ = fmt.Fprintln(tw, "USER\tNAME\tACTIVE_WEEKS\tGATE")
+	passed := false
+	for _, r := range rows {
+		gate := "-"
+		if r.ActiveWeeks >= gateThreshold {
+			gate = "PASS"
+			passed = true
+		}
+		_, _ = fmt.Fprintf(tw, "%s\t%s\t%d\t%s\n", r.UserID, orDash(r.DisplayName), r.ActiveWeeks, gate)
+	}
+	if err := tw.Flush(); err != nil {
+		return err
+	}
+
+	verdict := fmt.Sprintf("\nGate (usage in >= %d distinct weeks): NOT YET MET\n", gateThreshold)
+	if passed {
+		verdict = fmt.Sprintf("\nGate (usage in >= %d distinct weeks): PASSED\n", gateThreshold)
+	}
+	_, err := fmt.Fprint(w, verdict)
+	return err
+}

cmd/tapir/report_test.go

@@ -0,0 +1,49 @@
+package main
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+)
+
+var testSince = time.Date(2026, 6, 11, 0, 0, 0, 0, time.UTC)
+
+func TestFormatReportColumnsAndGatePass(t *testing.T) {
+	rows := []store.UserActiveWeeks{
+		{UserID: "user-a", DisplayName: "Ada", ActiveWeeks: 3},
+		{UserID: "user-b", DisplayName: "", ActiveWeeks: 1},
+	}
+
+	var b strings.Builder
+	require.NoError(t, formatReport(&b, rows, testSince))
+	out := b.String()
+
+	require.Contains(t, out, "since 2026-06-11", "report states the gate baseline date")
+	require.Contains(t, out, "USER")
+	require.Contains(t, out, "ACTIVE_WEEKS")
+	require.Contains(t, out, "Ada")
+	require.Contains(t, out, "PASSED", "a user at >= 2 weeks passes the gate")
+
+	// The >=2 user is marked PASS; the 1-week user is not.
+	require.Contains(t, lineContaining(t, out, "user-a"), "PASS")
+	require.NotContains(t, lineContaining(t, out, "user-b"), "PASS")
+	require.Contains(t, lineContaining(t, out, "user-b"), "-", "no display name falls back to dash")
+}
+
+func TestFormatReportGateNotMet(t *testing.T) {
+	rows := []store.UserActiveWeeks{{UserID: "user-a", ActiveWeeks: 1}}
+
+	var b strings.Builder
+	require.NoError(t, formatReport(&b, rows, testSince))
+	require.Contains(t, b.String(), "NOT YET MET", "no user at >= 2 weeks fails the gate")
+}
+
+func TestFormatReportEmpty(t *testing.T) {
+	var b strings.Builder
+	require.NoError(t, formatReport(&b, nil, testSince))
+	require.Contains(t, b.String(), "no users yet")
+}

cmd/tapir/scheduler.go

@@ -0,0 +1,206 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/youtube"
+	"git.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/runner"
+	"git.d-ma.be/mathias/tapir/internal/usecase"
+	"git.d-ma.be/mathias/tapir/internal/web"
+)
+
+// buildUserRunner constructs a runner.Runner for one user, reusing the same
+// engine wiring as buildProcessor but bound to that user's own YouTube refresh
+// token (web.YouTubeTokenRef(userID)) — the Stage-1 per-tenant ref, not the
+// Stage-0 single ref. It returns an error (not nil) when the global config can't
+// support live summarization (gateway, YouTube client creds, secrets file), so
+// the scheduler can skip that user gracefully. A user who simply hasn't connected
+// YouTube yet builds fine here; their token ref fails to resolve at RunOnce time,
+// surfacing as a per-user error the scheduler logs and skips.
+func buildUserRunner(cfg config.Config, st *store.Store, secretStore ports.SecretStore, userID string, log *slog.Logger) (*runner.Runner, error) {
+	if cfg.GatewayURL == "" || cfg.YTClientID == "" || cfg.YTClientSecret == "" || cfg.SecretsFile == "" {
+		return nil, fmt.Errorf("buildUserRunner: incomplete summarization config (gateway, youtube credentials, secrets file)")
+	}
+
+	src := youtube.New(youtube.Config{
+		ClientID:           cfg.YTClientID,
+		ClientSecret:       cfg.YTClientSecret,
+		TokenSecretRef:     web.YouTubeTokenRef(userID),
+		PreferredLanguages: []string{"en"},
+		MinVideoSeconds:    cfg.MinVideoSeconds,
+	}, secretStore)
+
+	engine := usecase.NewEngine(src, buildSummarizer(cfg), st)
+	// Share the transcript cache (ADR-021) on the scheduler path too — without
+	// this every scheduled pass re-fetches transcripts it already had, burning the
+	// scarce per-IP caption budget (ADR-014) and starving other users. The web
+	// "Summarize now" path already sets this; the scheduler omitting it was a bug.
+	engine.Transcripts = st
+
+	return runner.New(src, st, engine, userID, log,
+		runner.WithBackoff(cfg.FetchBackoff),
+		runner.WithAutoWindow(cfg.AutoSummarizeWindow),
+		runner.WithCaptionMemory(cfg.ChannelCaptionlessThreshold, cfg.ChannelCaptionlessWindow)), nil
+}
+
+// userLister enumerates every registered user and reports a user's video
+// connections. *store.Store satisfies it via ListAllUsers + ConnectionsForUser.
+// A small local interface keeps the scheduler testable with a fake.
+type userLister interface {
+	ListAllUsers(ctx context.Context) ([]store.UserIdentity, error)
+	ConnectionsForUser(ctx context.Context, userID string) ([]store.Connection, error)
+}
+
+// runDiscoveryPass runs one discovery pass for every user. runUser performs a
+// single user's pass (production: build a runner and RunOnce). Per-user failures
+// — including a buildUserRunner error or a RunOnce error — are logged and skipped
+// so one bad user, channel, or video never aborts the others (ADR-018 failure
+// isolation). Returns the stats summed across users.
+func runDiscoveryPass(
+	ctx context.Context,
+	pass int,
+	lister userLister,
+	runUser func(context.Context, string) (runner.Stats, error),
+	log *slog.Logger,
+) runner.Stats {
+	users, err := lister.ListAllUsers(ctx)
+	if err != nil {
+		log.Error("scheduler: list users failed", "err", err)
+		return runner.Stats{}
+	}
+
+	// Keep only users with a video connection. A pass for a connectionless user
+	// (e.g. a stale Dex-era orphan identity) only tries to resolve a token that
+	// was never minted, logging a spurious "ref not found" every tick. Filtering
+	// here — BEFORE rotation — also keeps fairness honest: rotation is over the
+	// users that actually consume the caption budget, so a dead identity can't eat
+	// a rotation slot and skew the lead share.
+	var connected []store.UserIdentity
+	for _, u := range users {
+		if ctx.Err() != nil {
+			return runner.Stats{} // shutting down
+		}
+		conns, err := lister.ConnectionsForUser(ctx, u.UserID)
+		if err != nil {
+			log.Warn("scheduler: list connections failed", "user", u.UserID, "err", err)
+			continue
+		}
+		if len(conns) == 0 {
+			log.Debug("scheduler: skipping user with no video connections", "user", u.UserID)
+			continue
+		}
+		connected = append(connected, u)
+	}
+
+	// Rotate who goes first each pass. Caption fetches share one per-egress-IP
+	// rate budget (ADR-014); whoever runs first each pass spends the pre-throttle
+	// window, so a FIXED order permanently starves whoever is last (a new pilot
+	// user got 0 fetches for 12h while the first-listed user got all of them).
+	// Rotation over the connected set gives each real user the lead in turn.
+	connected = rotateUsers(connected, pass)
+
+	log.Info("scheduler: starting discovery pass", "users", len(connected))
+	var total runner.Stats
+	for _, u := range connected {
+		if ctx.Err() != nil {
+			break // shutting down: stop enumerating
+		}
+		stats, err := runUser(ctx, u.UserID)
+		total = sumStats(total, stats)
+		if err != nil {
+			log.Warn("scheduler: user discovery pass had errors", "user", u.UserID, "err", err)
+		}
+	}
+	log.Info("scheduler: pass complete",
+		"candidates", total.Candidates, "summarized", total.Summarized,
+		"skipped_seen", total.SkippedSeen, "skipped_no_text", total.SkippedNoText,
+		"skipped_manual", total.SkippedManual, "skipped_too_old", total.SkippedTooOld,
+		"skipped_rate_limited", total.SkippedRateLimited,
+		"skipped_no_caption_channel", total.SkippedNoCaptionChannel,
+		"channel_unavailable", total.ChannelUnavailable, "errors", total.Errors)
+	return total
+}
+
+// runScheduler runs a discovery pass on startup, then once every interval until
+// ctx is cancelled (pod SIGTERM exits the loop cleanly). A non-positive interval
+// disables scheduling entirely (no startup pass) so dev/tests never auto-fetch.
+// It reuses the existing runner.Runner via runUser — the only new behaviour over
+// runner.Loop is iterating all users per tick (ADR-018).
+func runScheduler(
+	ctx context.Context,
+	interval time.Duration,
+	lister userLister,
+	runUser func(context.Context, string) (runner.Stats, error),
+	log *slog.Logger,
+) {
+	if interval <= 0 {
+		return // disabled
+	}
+
+	// Derive the rotation offset from wall-clock, NOT an in-memory counter. A
+	// counter reset to 0 on every pod restart always hands the lead to the
+	// first-listed user — so frequent deploys re-starve whoever is last (exactly
+	// what happened to the first pilot user during a deploy-heavy session). A
+	// time-based offset advances with real time and is identical across restarts,
+	// so the lead rotates fairly regardless of how often the pod bounces.
+	runPass := func() {
+		pass := int(time.Now().Unix() / int64(interval/time.Second))
+		runDiscoveryPass(ctx, pass, lister, runUser, log)
+	}
+
+	runPass()
+
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			runPass()
+		}
+	}
+}
+
+// rotateUsers left-rotates users by pass positions so a different user leads each
+// pass. With n users, user i leads on every pass where pass ≡ i (mod n). A pass
+// offset that is negative or exceeds n is normalised. Order within the rotation
+// is otherwise preserved, so the set of users run is unchanged — only who is
+// first (and thus wins the scarce caption-fetch budget) rotates.
+func rotateUsers(users []store.UserIdentity, pass int) []store.UserIdentity {
+	n := len(users)
+	if n <= 1 {
+		return users
+	}
+	off := ((pass % n) + n) % n
+	if off == 0 {
+		return users
+	}
+	out := make([]store.UserIdentity, 0, n)
+	out = append(out, users[off:]...)
+	out = append(out, users[:off]...)
+	return out
+}
+
+// sumStats adds two passes' stats field-wise, so runDiscoveryPass can report a
+// per-tick aggregate across all users.
+func sumStats(a, b runner.Stats) runner.Stats {
+	return runner.Stats{
+		Candidates:              a.Candidates + b.Candidates,
+		Summarized:              a.Summarized + b.Summarized,
+		SkippedSeen:             a.SkippedSeen + b.SkippedSeen,
+		SkippedNoText:           a.SkippedNoText + b.SkippedNoText,
+		SkippedManual:           a.SkippedManual + b.SkippedManual,
+		SkippedTooOld:           a.SkippedTooOld + b.SkippedTooOld,
+		SkippedRateLimited:      a.SkippedRateLimited + b.SkippedRateLimited,
+		SkippedNoCaptionChannel: a.SkippedNoCaptionChannel + b.SkippedNoCaptionChannel,
+		ChannelUnavailable:      a.ChannelUnavailable + b.ChannelUnavailable,
+		Errors:                  a.Errors + b.Errors,
+	}
+}

cmd/tapir/scheduler_test.go

@@ -0,0 +1,216 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/runner"
+)
+
+func quietLog() *slog.Logger {
+	return slog.New(slog.NewTextHandler(io.Discard, nil))
+}
+
+// fakeLister returns a fixed user set (or an error) for the scheduler under test.
+type fakeLister struct {
+	users  []store.UserIdentity
+	err    error
+	noConn map[string]bool // users that have NOT connected a video source
+}
+
+func (f fakeLister) ListAllUsers(context.Context) ([]store.UserIdentity, error) {
+	return f.users, f.err
+}
+
+// ConnectionsForUser reports a single youtube connection for every user except
+// those in noConn, which return zero — the connection-less case the scheduler
+// must skip instead of running (and failing to resolve a token for).
+func (f fakeLister) ConnectionsForUser(_ context.Context, userID string) ([]store.Connection, error) {
+	if f.noConn[userID] {
+		return nil, nil
+	}
+	return []store.Connection{{Provider: "youtube"}}, nil
+}
+
+// countingRunUser records how many passes each user got, optionally failing for
+// specific users, under a mutex so it is safe across the scheduler goroutine.
+type countingRunUser struct {
+	mu      sync.Mutex
+	calls   map[string]int
+	order   []string // userIDs in the order they were run, across all passes
+	failFor map[string]bool
+}
+
+func newCountingRunUser(failFor ...string) *countingRunUser {
+	c := &countingRunUser{calls: map[string]int{}, failFor: map[string]bool{}}
+	for _, u := range failFor {
+		c.failFor[u] = true
+	}
+	return c
+}
+
+func (c *countingRunUser) run(_ context.Context, userID string) (runner.Stats, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.calls[userID]++
+	c.order = append(c.order, userID)
+	if c.failFor[userID] {
+		return runner.Stats{Errors: 1}, errors.New("boom")
+	}
+	return runner.Stats{Summarized: 1}, nil
+}
+
+func (c *countingRunUser) runOrder() []string {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return append([]string(nil), c.order...)
+}
+
+func (c *countingRunUser) count(userID string) int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.calls[userID]
+}
+
+func (c *countingRunUser) total() int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	n := 0
+	for _, v := range c.calls {
+		n += v
+	}
+	return n
+}
+
+func usersN(ids ...string) []store.UserIdentity {
+	out := make([]store.UserIdentity, len(ids))
+	for i, id := range ids {
+		out[i] = store.UserIdentity{UserID: id, DexSubject: "dex|" + id}
+	}
+	return out
+}
+
+func TestDiscoveryPassRunsEveryUserOnce(t *testing.T) {
+	lister := fakeLister{users: usersN("a", "b", "c")}
+	rc := newCountingRunUser()
+
+	stats := runDiscoveryPass(context.Background(), 0, lister, rc.run, quietLog())
+
+	require.Equal(t, 1, rc.count("a"))
+	require.Equal(t, 1, rc.count("b"))
+	require.Equal(t, 1, rc.count("c"))
+	require.Equal(t, 3, stats.Summarized, "stats are summed across users")
+}
+
+// Caption fetches share one per-IP budget; a fixed user order starves whoever is
+// last. Each pass must rotate which user leads so the lead slot is shared.
+func TestDiscoveryPassRotatesLeadUser(t *testing.T) {
+	lister := fakeLister{users: usersN("a", "b", "c")}
+	rc := newCountingRunUser()
+
+	runDiscoveryPass(context.Background(), 0, lister, rc.run, quietLog())
+	runDiscoveryPass(context.Background(), 1, lister, rc.run, quietLog())
+	runDiscoveryPass(context.Background(), 2, lister, rc.run, quietLog())
+
+	require.Equal(t, []string{"a", "b", "c", "b", "c", "a", "c", "a", "b"}, rc.runOrder(),
+		"each pass left-rotates the user order so every user leads in turn")
+	// Fairness: over a full rotation cycle every user ran the same number of times.
+	require.Equal(t, 3, rc.count("a"))
+	require.Equal(t, 3, rc.count("b"))
+	require.Equal(t, 3, rc.count("c"))
+}
+
+// A connectionless orphan must not consume a rotation slot: rotation is over the
+// connected users only, so two real users alternate the lead 50/50 even with a
+// dead identity listed between them.
+func TestDiscoveryPassRotationIgnoresConnectionlessUsers(t *testing.T) {
+	lister := fakeLister{users: usersN("a", "orphan", "c"), noConn: map[string]bool{"orphan": true}}
+	rc := newCountingRunUser()
+
+	runDiscoveryPass(context.Background(), 0, lister, rc.run, quietLog())
+	runDiscoveryPass(context.Background(), 1, lister, rc.run, quietLog())
+
+	require.Equal(t, []string{"a", "c", "c", "a"}, rc.runOrder(),
+		"only connected users rotate; the orphan never runs and never holds a slot")
+	require.Equal(t, 0, rc.count("orphan"))
+}
+
+func TestDiscoveryPassSkipsUsersWithoutConnections(t *testing.T) {
+	// b never connected a video source (e.g. a stale Dex-era orphan identity).
+	// It must be skipped silently — not run and logged as a token error every pass.
+	lister := fakeLister{users: usersN("a", "b", "c"), noConn: map[string]bool{"b": true}}
+	rc := newCountingRunUser()
+
+	stats := runDiscoveryPass(context.Background(), 0, lister, rc.run, quietLog())
+
+	require.Equal(t, 1, rc.count("a"))
+	require.Equal(t, 0, rc.count("b"), "a user with no connection must be skipped, not run")
+	require.Equal(t, 1, rc.count("c"))
+	require.Equal(t, 2, stats.Summarized, "only connected users contribute")
+	require.Equal(t, 0, stats.Errors, "skipping is silent — no spurious error stat")
+}
+
+func TestDiscoveryPassOneUserFailureDoesNotStopOthers(t *testing.T) {
+	lister := fakeLister{users: usersN("a", "b", "c")}
+	rc := newCountingRunUser("b") // user b's pass errors
+
+	stats := runDiscoveryPass(context.Background(), 0, lister, rc.run, quietLog())
+
+	require.Equal(t, 1, rc.count("a"))
+	require.Equal(t, 1, rc.count("b"))
+	require.Equal(t, 1, rc.count("c"), "a failing user must not abort the rest")
+	require.Equal(t, 2, stats.Summarized) // a + c
+	require.Equal(t, 1, stats.Errors)     // b
+}
+
+func TestDiscoveryPassListerErrorIsContained(t *testing.T) {
+	lister := fakeLister{err: errors.New("db down")}
+	rc := newCountingRunUser()
+
+	stats := runDiscoveryPass(context.Background(), 0, lister, rc.run, quietLog())
+
+	require.Equal(t, 0, rc.total(), "no users enumerated → no passes")
+	require.Equal(t, runner.Stats{}, stats)
+}
+
+func TestSchedulerIntervalZeroDisablesEntirely(t *testing.T) {
+	lister := fakeLister{users: usersN("a", "b")}
+	rc := newCountingRunUser()
+
+	runScheduler(context.Background(), 0, lister, rc.run, quietLog())
+
+	require.Equal(t, 0, rc.total(), "interval 0 must not run even a startup pass")
+}
+
+func TestSchedulerRunsStartupPassThenStopsOnCancel(t *testing.T) {
+	lister := fakeLister{users: usersN("a", "b", "c")}
+	rc := newCountingRunUser()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	done := make(chan struct{})
+	go func() {
+		// A long interval so only the startup pass runs before we cancel.
+		runScheduler(ctx, time.Hour, lister, rc.run, quietLog())
+		close(done)
+	}()
+
+	// The startup pass is synchronous at the top of runScheduler; once all three
+	// users have a pass it has completed and the loop is parked on the ticker.
+	require.Eventually(t, func() bool { return rc.total() == 3 }, time.Second, 5*time.Millisecond)
+
+	cancel()
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("scheduler did not exit after ctx cancel")
+	}
+	require.Equal(t, 3, rc.total(), "no extra passes fired between startup and cancel")
+}

cmd/tapir/show.go

@@ -8,7 +8,7 @@ import (
 	"os"
 	"strings"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // runShow prints the full summary for one video: text, highlights, takeaways,

docs/architecture/architecture.md

@@ -145,16 +145,139 @@ graph TB
   engine in a **background goroutine** inside `serve`; the page HTMX-polls `/v/{id}/status`,
   showing a Charmbracelet spinner while in-flight (and an honest "queued/waiting" state under
   rate-limiting — ADR-014).
-- **Summarization mode** — `users.auto_summarize` (migration 006). Auto: every new video is
-  summarized. Manual (default): new videos appear unsummarized; the button sets
-  `videos.summarize_requested`, which the next `tapir run` processes and clears. Both the click
-  path and the batch `tapir run` drive the same unchanged engine.
+- **Summarization mode** — `users.auto_summarize` (migration 006). Default is **true** for new
+  users (migration 011, ADR-018); all existing rows were back-filled via migration 012. Auto:
+  new videos **published within the recency window** (`TAPIR_AUTO_SUMMARIZE_WINDOW`, default ~7d,
+  ADR-020) are summarized automatically; older videos are discovered and listed but wait for an
+  explicit "Summarize". Manual: new videos appear unsummarized; the button sets
+  `videos.summarize_requested`, which the next `tapir run` processes and clears. A manual request
+  bypasses the recency bound. Both the click path and the batch `tapir run` drive the same
+  unchanged engine.
+- **List surface (ADR-020)** — the list reads `ListVideos` ordered summarized-first, then
+  `published_at DESC NULLS LAST`. The web layer collapses the noise so summaries are not buried:
+  un-summarized videos older than the recency window fold into one "Show N older videos"
+  disclosure, and caption-less videos collapse to a single count line. Copy surfaces scarcity
+  honestly (queue counts, gradual-fill note) — it never implies the feed is fuller than it is.
 
 The engine, ports, and sink adapters are **untouched** by all of the above — the web surface only
 reads the store and triggers the existing engine. Adding it changed wiring, not the core (ADR-003).
 
 ---
 
+## In-process scheduler (ADR-018)
+
+`cmdServe` launches a background goroutine when `TAPIR_DISCOVERY_INTERVAL > 0`. On each tick
+it calls `store.ListAllUsers` (un-RLS'd admin query), builds a per-user `runner.Runner`, and
+calls `RunOnce` for each registered user in sequence.
+
+```mermaid
+sequenceDiagram
+    participant S as Scheduler goroutine
+    participant DB as Postgres (RLS)
+    participant YT as YouTube timedtext
+    participant LLM as LiteLLM gateway
+
+    loop every TAPIR_DISCOVERY_INTERVAL
+        S->>DB: ListAllUsers() [un-RLS'd]
+        loop per user
+            S->>DB: GetAutoSummarize(userID)
+            S->>YT: ListSubscriptions + NewVideos
+            Note over S,DB: auto: skip videos published before<br/>TAPIR_AUTO_SUMMARIZE_WINDOW (ADR-020);<br/>older ones listed, await manual request
+            Note over S,YT: WaitFetchGate(ctx) throttles<br/>all fetches to TAPIR_FETCH_RATE
+            alt transcript available
+                S->>LLM: Summarize
+                S->>DB: Deliver(summary)
+            else 429
+                S->>DB: SetTranscriptStatus(rate_limited)
+            end
+        end
+    end
+```
+
+**Single-replica constraint (load-bearing).** The scheduler lives in the web process;
+`replicas: 1` in the k3s deployment manifest is not cosmetic — running `tapir serve` at
+>1 replica makes every replica run the full discovery loop, causing every registered user
+to be fetched in parallel from the same egress IP (429s + duplicate work). Do not scale
+`serve` past 1 replica without first moving discovery to a k8s CronJob or adding leader
+election. The process logs a `Warn` at startup when scheduled discovery is enabled as a
+reminder.
+
+---
+
+## Process-wide timedtext rate gate
+
+**`internal/adapters/youtube/gate.go`** (ADR-014 item 2): a single `rate.Limiter`
+(`golang.org/x/time/rate`) shared across **all** Adapter instances. Every `httpDo` call for
+a caption fetch passes through `WaitFetchGate(ctx)` before hitting YouTube. This serialises
+the scheduler loop AND the web click-path through the same per-egress-IP budget. Configured
+via `TAPIR_FETCH_RATE` (Go duration, default `2s`). Setting it to `0` disables the gate
+(dev/tests only).
+
+This is the precondition that makes scheduled auto-summarize safe: without the gate, a
+multi-user scheduler pass could fire many concurrent timedtext requests from the same IP
+within seconds, triggering 429s for all users.
+
+### Two-path summarisation model
+
+Both paths share `globalFetchGate` — rate limiting is **respected in both**, not routed around.
+
+| Path | Trigger | Order | Rationale |
+|------|---------|-------|-----------|
+| **Foreground** | User clicks "Summarize" on any non-summarized card (`POST /v/{id}/retry-now` for rate-limited; `POST /v/{id}/summarize` for pending) | Single chosen video | On-demand value: user picks a specific video to read now — bypasses the recency bound |
+| **Background batch** | Scheduled discovery pass every `TAPIR_DISCOVERY_INTERVAL` | **Newest-first across all channels** (see below), **bounded to the recency window** (ADR-020) | Onboarding prioritisation within bounded load: recent videos auto-fill; the older back-catalogue stays on-demand |
+
+The rationale for both paths is **onboarding prioritisation under an honest, bounded load** — a
+new user gets summaries of their most recent videos automatically, while the older back-catalogue
+is listed but summarised only on demand, so it never re-drives the shared rate gate every cycle.
+
+### Newest-first batch ordering (ADR-018)
+
+Within each scheduled pass, `RunOnce` uses a three-phase structure:
+
+1. **Discover + persist**: walk all channels, `UpsertVideo` every candidate (so it appears in
+   the list), apply pre-filters (seen/manual/backoff/**recency**), collect surviving candidates.
+   The recency pre-filter (ADR-020) drops auto-mode videos published before
+   `now - TAPIR_AUTO_SUMMARIZE_WINDOW` unless they are explicitly requested; an undated video is
+   never aged out. They remain persisted/listed — only auto-summarisation is skipped.
+2. **Sort**: order candidates `published_at DESC, NULLS LAST, discovery_pos ASC`. Videos with
+   no publish date (schema 001: nullable) sort after all dated content. The sort is in-memory
+   (`slices.SortStableFunc`) — at current scale this is fine.
+3. **Process**: feed candidates to the engine in sorted order through `globalFetchGate`.
+
+Before (per-channel inline): `[chanA-old, chanA-mid, chanB-new, chanB-null]`
+After  (newest-first):       `[chanB-new, chanA-mid, chanA-old, chanB-null]`
+
+The set of *processed* videos now also excludes auto-mode back-catalogue beyond the recency
+window (those stay listed, summarised on demand); within the processed set, only order changes.
+
+### Connect-time onboarding burst (ADR-018 → ADR-028)
+
+On a successful YouTube connect, `ConnectHandler` enqueues a connect-triggered discovery pass;
+the `discoveryTrigger` runs that pass and then fires the **onboarding burst** — a third entry path
+that summarises up to `TAPIR_ONBOARD_SUMMARIZE_COUNT` (default 3, hard-capped) of the new user's
+videos so the first session is not empty. The burst still flows through `globalFetchGate` (it is
+not a throughput change); ADR-028 sharpened *which* videos and *which model*:
+
+- **Selection** is `OnboardBurstVideoIDs`, not pure newest-first. It keeps newest-first order but
+  excludes a video whose **known** duration is outside `[TAPIR_MIN_VIDEO_SECONDS,
+  TAPIR_ONBOARD_MAX_VIDEO_SECONDS]` (drops Shorts and multi-hour livestream VODs). An unknown
+  (NULL) duration is degrade-open — kept, but ranked after known-good rows. The connect-triggered
+  discovery pass runs *before* the burst, and ADR-023's `videos.list` enrichment now **persists**
+  `duration_s` (instead of discarding it after the Shorts filter), so a fresh user's candidates
+  carry a duration in time for selection.
+- **Model**: the burst runs through a dedicated summarizer chain led by
+  `TAPIR_ONBOARD_SUMMARIZER_MODEL` (default `iguana/gemma4-26b`, the stronger local model), with
+  the standard ADR-022 chain following as fallback. This is a wiring choice — a second
+  `engineProcessor` over the same store / transcript cache / sink; the engine and ports are
+  unchanged. Empty / equal-to-primary collapses it back onto the shared processor.
+
+`has-captions` is deliberately **not** a selection signal — it is only knowable after a gate fetch
+(or a ~0-probability cache hit at pilot scale), so the burst can avoid known-junk but cannot
+promise captions. Cached-transcript-first selection was investigated and rejected (ADR-028:
+~3% cross-user overlap).
+
+---
+
 ## Sequence — core use case: new video summarized
 
 ```mermaid

docs/data-model.md

@@ -10,12 +10,15 @@ only opaque references to them; the secret material lives in ESO/1Password (ADR-
 
 ## Design decisions baked into this model
 
-- **Per-user isolation, not a shared global video table.** The earlier draft proposed a
-  global `videos`/`transcripts` table deduped across tenants. Rejected for Future B: it
-  reintroduces exactly the cross-domain coupling the homelab architecture review is
-  removing, and at 1–5 users the cost of occasionally re-summarizing the same video is
-  trivial compared to the isolation it would cost. Each user's data is self-contained.
-  (Revisit only if Future C makes GPU/transcription cost dominate — a new ADR, not a default.)
+- **Per-user isolation for everything except transcripts.** The earlier draft proposed a
+  global `videos`/`transcripts` table deduped across tenants. **Videos** stay per-user and
+  RLS-scoped — a shared video table reintroduces exactly the cross-domain coupling the homelab
+  architecture review is removing. **Transcripts**, however, are now shared (ADR-021): keyed by
+  `(provider, provider_video_id)`, no `user_id`, **not** RLS-scoped. The cost avoided there is
+  not LLM re-summarization but a rate-gated, reputation-risky caption fetch (ADR-010/014), which
+  is paid per re-fetch regardless of user count — so persisting public caption content once and
+  sharing it strictly beats the coupling it removes. Everything else each user owns is
+  self-contained; `rls_test.go` proves transcripts is the single exception.
 - **Secrets by reference only.** Tables hold a `secret_ref` (opaque string/UUID resolved via
   the `SecretStore` port), never tokens or keys.
 - **The brain sink is just a delivery target.** No brain-specific tables. Whether a summary
@@ -23,7 +26,7 @@ only opaque references to them; the secret material lives in ESO/1Password (ADR-
 
 ## Entities
 
-Solid entities below are **persisted today** (migrations 001–006). `AI_CREDENTIAL` and
+Solid entities below are **persisted today** (migrations 001–013). `AI_CREDENTIAL` and
 `SUBSCRIPTION` are **planned, not yet a table** — kept in the model for intent; see the notes.
 
 ```mermaid
@@ -34,14 +37,15 @@ erDiagram
     USER ||--o{ AI_CREDENTIAL : "has (planned)"
     VIDEO_CONNECTION ||--o{ SUBSCRIPTION : "exposes (planned)"
     SUBSCRIPTION ||--o{ VIDEO : "produces (per user)"
-    VIDEO ||--o| TRANSCRIPT : "has at most one"
+    VIDEO }o--o| TRANSCRIPT : "shares one by (provider, provider_video_id) — not FK (ADR-021)"
     VIDEO ||--o| SUMMARY : "has at most one"
     SUMMARY ||--o{ SINK_DELIVERY : "delivered via"
+    USER ||--o{ CHANNEL_ERROR : "reports unavailable channels"
 
     USER {
         uuid id PK
         text display_name
-        bool auto_summarize "default false -> manual mode out of the box (migration 006)"
+        bool auto_summarize "default true for new users (migration 011, ADR-018)"
         timestamptz created_at
     }
     USER_IDENTITY {
@@ -87,14 +91,16 @@ erDiagram
         text url
         bool summarize_requested "default false -> manual-mode queue flag (migration 006)"
         timestamptz seen_at
+        text transcript_status "none|rate_limited|fetched (migration 007)"
+        timestamptz rate_limited_at "backoff clock for 429 retries (migration 007)"
     }
     TRANSCRIPT {
-        uuid video_id PK_FK
-        uuid user_id FK
+        text provider PK "part of shared key (ADR-021)"
+        text provider_video_id PK "part of shared key — the cross-user dedup key"
         text source "captions | none"
         text language
         text content "null when source = none"
-        timestamptz resolved_at
+        timestamptz fetched_at
     }
     SUMMARY {
         uuid id PK
@@ -123,21 +129,31 @@ erDiagram
         text action "watched | skipped | saved"
         timestamptz acted_at
     }
+    CHANNEL_ERROR {
+        uuid user_id FK
+        text channel_id
+        text channel_name
+        timestamptz first_seen
+        timestamptz last_seen
+    }
 ```
 
 `SUMMARY_ACTION` has `UNIQUE (user_id, video_id, action)`; `VIDEO_CONNECTION` has
 `UNIQUE (user_id, provider)` (one connection per provider — reconnect upserts in place).
 RLS (`ENABLE` + `FORCE`) is on **every solid user-owned table above** — `users`, `videos`,
-`transcripts`, `summaries`, `summary_actions`, `video_connections`. `sink_deliveries` is
-RLS'd via an `EXISTS` on its parent summary; `user_identities` is intentionally **not** RLS'd
-(auth plumbing). See the *Isolation invariant* section for the mechanism.
+`transcripts`, `summaries`, `summary_actions`, `video_connections`, `channel_errors`.
+`sink_deliveries` is RLS'd via an `EXISTS` on its parent summary; `user_identities` is
+intentionally **not** RLS'd (auth plumbing). See the *Isolation invariant* section for the
+mechanism.
 
 ## Notes per entity
 
 - **USER** — one row per registered user (Stage 1, ADR-012; no longer single-row). The Tapir-side
   profile; the Dex identity is held separately in `USER_IDENTITY`, not on this row. `auto_summarize`
-  (migration 006) is the per-user mode flag: `FALSE` (default) = manual, `TRUE` = auto-summarize
-  every new video.
+  (migration 006) is the per-user mode flag: `TRUE` = auto-summarize new videos **published within
+  the recency window** (`TAPIR_AUTO_SUMMARIZE_WINDOW`, default ~7d, ADR-020); older videos are
+  listed but summarised on demand. Default is **true** for new users (migration 011, ADR-018);
+  existing rows were back-filled via migration 012 with RLS bypass.
 - **USER_IDENTITY** (migration 004) — the `dex_subject → user_id` map. `dex_subject` is the PK,
   `user_id` a `UNIQUE` FK to `users` with `ON DELETE CASCADE`. This is the bridge resolved at login
   *before* a `user_id` is known, so it is **deliberately not RLS-enabled** (it holds no user data;
@@ -157,8 +173,15 @@ RLS'd via an `EXISTS` on its parent summary; `user_identities` is intentionally
   decision. The same video seen by two users is two rows. `seen_at` is when Tapir detected it.
   `summarize_requested` (migration 006) is the manual-mode queue flag: the web "Summarize" button
   sets it `TRUE`; the next `tapir run` picks it up, summarizes, and clears it back to `FALSE`.
-- **TRANSCRIPT** — at most one per video. `source = none` records "checked, no usable
-  transcript" so the watcher doesn't reprocess (ADR-007). `content` null in that case.
+  `transcript_status` and `rate_limited_at` (migration 007) track caption-fetch outcomes for
+  rate-limit backoff: `NULL` = not attempted; `rate_limited` = 429 seen, skip until
+  `NOW() - rate_limited_at > TAPIR_FETCH_BACKOFF`; `fetched` = resolved; `none` = no transcript.
+- **TRANSCRIPT** — shared public caption content, one row per `(provider, provider_video_id)`,
+  **not** RLS-scoped and carrying no `user_id` (ADR-021). Two users who watch the same video
+  share the one row; the summarize path reads it before any caption fetch, so re-analysis never
+  re-touches YouTube (ADR-010/014). `source = none` records "checked, no usable transcript" so
+  no one reprocesses (ADR-007); `content` null in that case. A transient 429 is never stored
+  here — it stays a per-user retry via `VIDEO.transcript_status`.
 - **SUMMARY** — at most one per video. `fallback_used` + `ai_provider`/`ai_model` make the
   "is local good enough?" question queryable (the Stage 0 quality signal). `highlights`/
   `takeaways` as jsonb to stay schema-flexible while the output format settles.
@@ -170,6 +193,12 @@ RLS'd via an `EXISTS` on its parent summary; `user_identities` is intentionally
   save) — the column that makes the Stage-0 headline metric ("acts on ≥1 summary") queryable
   (ui-spec.md §5, ADR-011). `video_id` is `TEXT` and **not** FK-constrained, mirroring summaries'
   standalone `(user_id, video_id)` key. `UNIQUE (user_id, video_id, action)`. FORCE RLS'd.
+- **CHANNEL_ERRORS** (migration 013) — channels that returned HTTP 404 (deleted or private) on
+  the most recent discovery pass. Upserted per scheduler pass (`last_seen` refreshed each run);
+  surfaced on the account page as a warning. Cascades on user deletion. Primary key is
+  `(user_id, channel_id)`. FORCE RLS'd.
+- **LOGIN_EVENTS** (migration 010) — throttled one-row-per-(user, date) login stamp. Used by the
+  Stage-0 gate query (VISION §Stage 0: "returned and used in ≥2 distinct weeks").
 
 ## Isolation invariant (Stage 1+) — LIVE
 
@@ -180,8 +209,9 @@ enforcement dormant); **ADR-012 opened Stage 1 and turned enforcement on in the
 Enforcement is **Postgres Row-Level Security** (migration `003_rls.up.sql`):
 
 - RLS is `ENABLE`d **and** `FORCE`d on every user-owned table — `users`, `videos`,
-  `transcripts`, `summaries`, `summary_actions`, `video_connections`. `FORCE` is load-bearing:
-  the app connects as the table **owner** (`tapir` role), and owners bypass RLS unless forced.
+  `transcripts`, `summaries`, `summary_actions`, `video_connections`, `channel_errors`.
+  `FORCE` is load-bearing: the app connects as the table **owner** (`tapir` role), and owners
+  bypass RLS unless forced.
 - Each policy keys off the per-request GUC `tapir.current_user_id`, set transaction-locally by
   the store's `withUser` helper via `set_config('tapir.current_user_id', $1, true)` — it
   auto-resets on commit/rollback, so it never leaks across a pooled connection.
@@ -208,7 +238,8 @@ queue, doesn't replace it). Deferred until there's a reason.
 
 ## Explicitly out of scope (Future C)
 
-- Global cross-tenant video/transcript dedup (rejected above).
+- Global cross-tenant *video* dedup (rejected above). Note: cross-tenant *transcript* sharing
+  is now in scope and shipped (ADR-021); only the videos half stays per-user.
 - Sharding / per-tenant physical databases.
 - Soft-delete + full audit trail on connections/credentials (a Stage 2 hardening item; add
   via ADR when Stage 2 work starts).

docs/homelab-integration.md

@@ -2,7 +2,7 @@
 
 The concrete endpoints, conventions, and identifiers Tapir depends on, so an independent
 session doesn't have to rediscover them. **Verify anything marked "confirm" before relying on
-it** — endpoints and aliases drift, and this file is a snapshot (2026-06-02), not a live source.
+it** — endpoints and aliases drift, and this file is a snapshot (2026-06-06), not a live source.
 
 ## Local AI (the Primary in `llm.Router`)
 
@@ -27,6 +27,30 @@ it** — endpoints and aliases drift, and this file is a snapshot (2026-06-02),
   `iguana/deepseek-r1-14b`) is preferred for summary quality if its latency/output is acceptable.
   The `max_tokens` fix below means thinking models no longer return empty content, so they are now
   viable choices, not blocked ones. Do not assume a coder alias is right for prose.
+- **Summarizer fallback chain (ADR-022).** The primary alias is the *first* of an ordered chain;
+  on failure or unparseable output the summarizer advances to the next model. All reached through
+  the same gateway by alias.
+  - `TAPIR_FALLBACK_MODEL` — local fallback. **Default `iguana/gemma4-26b`** — on iguana, NOT
+    koala, so the fallback does not compete with koala's other GPU loads (and runs from a different
+    egress IP). Empty disables it.
+  - `TAPIR_CLOUD_FALLBACK_MODEL` — worst-case EXTERNAL fallback. **Default `berget/mistral-small`.**
+    **Set this empty (`""`) for any client/NDA deployment** so content never leaves the local
+    stack — the chain then contains only local endpoints.
+  - `TAPIR_SUMMARY_MAX_TOKENS` — per-summary completion budget. **Default `1500`.** Small on
+    purpose: with the old 8192 budget, prompt + completion overflowed `phi4-mini`'s 8k window.
+  - `TAPIR_MAX_TRANSCRIPT_CHARS` — transcript truncation budget sent to the model. **Default
+    `18000`** (~fits an 8k-context model). `0` disables truncation. Prevents the context-overflow
+    HTTP 400 a long transcript caused on `phi4-mini`.
+- **Discovery low-value filter (ADR-023).** `TAPIR_MIN_VIDEO_SECONDS` — **default `60`**. At
+  discovery, `NewVideos` enriches candidates with one cheap `videos.list` call (quota API, NOT
+  the timedtext 429 path) and drops videos shorter than this plus any live/upcoming broadcast,
+  so the scarce caption-fetch budget isn't spent on Shorts. `0` disables the filter. The
+  paste-a-URL path is never filtered.
+- **Per-channel caption memory (ADR-024).** `TAPIR_CHANNEL_CAPTIONLESS_THRESHOLD` — **default
+  `5`** consecutive no-caption results before a channel is suppressed (its videos listed but not
+  caption-fetched). `TAPIR_CHANNEL_CAPTIONLESS_WINDOW` — **default `336h`** (14d) suppression
+  before one video is re-probed. `THRESHOLD=0` disables. A successful fetch resets the channel;
+  a 429 does not count; an explicit manual request bypasses suppression.
 - **Thinking models need an explicit `max_tokens`.** qwen3 / deepseek-r1 spend the budget on
   reasoning and return **empty content** if `max_tokens` is too low (or unset). The summarizer's
   parser treats an empty summary as an error for exactly this reason. **Done (2026-06-02, Worker F):**
@@ -160,7 +184,7 @@ allow per-provider when a user connects one.
 
 ---
 
-_Snapshot date 2026-06-02. Items marked **confirm** were not verified to a pinned source at
+_Snapshot date 2026-06-06. Items marked **confirm** were not verified to a pinned source at
 snapshot time — check brain or the live cluster before depending on them._
 
 ## Stage 1 — multi-user facts (verified 2026-06-03)
@@ -191,3 +215,37 @@ snapshot time — check brain or the live cluster before depending on them._
 - `user_identities(dex_subject → user_id)` table is **intentionally NOT RLS-enabled**
   (it's auth plumbing, holds no user data; data isolation is on the user-owned tables).
   All data access after subject resolution goes through `withUser`.
+
+## Scheduled discovery (ADR-018, verified 2026-06-05)
+
+`tapir serve` runs discovery for **all users** in-process on a timer (no CronJob). Three env
+knobs plus one load-bearing deployment constraint:
+
+- `TAPIR_DISCOVERY_INTERVAL` — Go duration, e.g. `2h`. The cadence the serve process runs a
+  discovery pass for every registered user (run-once-on-startup, then every interval).
+  **Unset or `0` = disabled** (dev/tests never auto-fetch).
+- `TAPIR_USAGE_GATE_START` — `YYYY-MM-DD`, default **`2026-06-11`** (the morning the pilot was
+  unblocked and summaries started flowing). `tapir report` counts return-usage (distinct active
+  weeks, ADR-016) only from this date, so pre-launch testing and the blocked period are excluded.
+- `TAPIR_METRICS_ADDR` — listen address for the Prometheus `/metrics` endpoint (ADR-030).
+  **Default `:9090`** — a SEPARATE port from `TAPIR_HTTP_ADDR` so metrics are never on the public
+  app; scraped in-cluster only (PodMonitor). Empty disables the metrics server. Key series:
+  `tapir_summarize_duration_seconds{model,outcome,fallback}`, `tapir_caption_fetch_duration_seconds{outcome}`,
+  `tapir_chat_duration_seconds{model}`, `tapir_llm_tokens_total{model,kind}`,
+  `tapir_http_request_duration_seconds{method,route}`, `tapir_logins_total`.
+- `TAPIR_FETCH_RATE` — Go duration, default `2s`. The **process-wide per-egress-IP caption-fetch
+  rate gate** (ADR-014 item 2). Every caption fetch — scheduler runners *and* the web "Summarize"
+  click-path — serialises through this one limiter so the pod cannot collectively trip 429s. `0`
+  = unlimited (dev/tests). This is the precondition that makes auto-summarize-on-a-schedule safe;
+  do not raise it aggressively without watching for 429s.
+- `TAPIR_FETCH_BACKOFF=4h` — per-video rate-limit retry window; default `1h`. A video that
+  returns HTTP 429 on a caption fetch is skipped for this duration before being retried. The
+  scheduler checks `NOW() - rate_limited_at > TAPIR_FETCH_BACKOFF` before attempting to fetch
+  a video marked `transcript_status = rate_limited`. Longer values reduce 429 pressure at the
+  cost of slower recovery after a throttling episode.
+- **SINGLE-REPLICA WARNING (load-bearing).** The scheduler lives in the web process, so
+  `replicas: 1` in the deployment manifest is load-bearing: running `tapir serve` at >1 replica
+  makes **every** replica run the discovery loop → every user fetched in parallel from the same
+  egress IP (429s + duplicate work). Do **not** scale `serve` past 1 replica without first moving
+  discovery to a k8s CronJob or adding leader election. The process logs a `Warn` at startup when
+  scheduled discovery is enabled, as a reminder.

docs/sketches/a-tui-panels.html

@@ -0,0 +1,63 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>tapir — A · TUI panels</title>
+<style>
+:root{--bg:#0d0d12;--panel:#14141c;--line:#2a2a3a;--mint:#0EF9B6;--pink:#F740A0;--purple:#7653fc;--cream:#F5E9D6;--dim:#6b6b86;--text:#d9d9e6}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--text);font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,"Cascadia Code",monospace}
+.wrap{max-width:760px;margin:0 auto;padding:18px 14px 60px}
+header{display:flex;align-items:center;gap:10px;border-bottom:1px solid var(--line);padding-bottom:12px;margin-bottom:18px}
+.brand{color:var(--mint);font-weight:700;letter-spacing:.5px}
+.brand b{color:var(--cream)}
+.tip{margin-left:auto;color:var(--dim);font-size:12px}
+.note{color:var(--dim);font-size:12.5px;border-left:2px solid var(--purple);padding:6px 10px;margin:0 0 16px;background:#11111a}
+/* lipgloss-style bordered panel */
+.card{border:1px solid var(--line);border-radius:8px;background:var(--panel);padding:12px 14px;margin:0 0 12px;position:relative}
+.card::before{content:"";position:absolute;left:0;top:10px;bottom:10px;width:3px;border-radius:3px;background:var(--purple)}
+.card.ready::before{background:var(--mint)}
+.title{color:var(--cream);font-size:15px;font-weight:600;margin:0 0 4px}
+.meta{color:var(--dim);font-size:12px}
+.chip{display:inline-block;border:1px solid var(--mint);color:var(--mint);border-radius:4px;padding:0 6px;font-size:11px;margin-left:6px}
+.chip.q{border-color:var(--pink);color:var(--pink)}
+.preview{color:var(--dim);margin:6px 0 0;font-size:13px}
+/* expanded */
+.exp{border-color:var(--purple)}
+.exp .head{display:flex;justify-content:space-between;align-items:baseline}
+.collapse{color:var(--mint);font-size:12px;text-decoration:none;border:1px solid var(--line);border-radius:4px;padding:1px 7px}
+.sec h2{color:var(--mint);font-size:12px;text-transform:uppercase;letter-spacing:1px;margin:16px 0 6px;border-bottom:1px dashed var(--line);padding-bottom:3px}
+.sec ul{margin:0;padding-left:18px}.sec li{margin:3px 0}
+.body{color:var(--text)}
+.dock{margin-top:16px;border-top:1px solid var(--line);padding-top:12px}
+.ask{display:inline-block;background:linear-gradient(90deg,var(--purple),var(--pink));color:#fff;border:0;border-radius:6px;padding:7px 12px;font:inherit;font-size:13px;cursor:pointer}
+pre.tapir{margin:0;color:var(--mint);font-size:10px;line-height:1.05}
+</style></head><body><div class="wrap">
+<header>
+  <pre class="tapir">  ▄█▓▓█▄  ∩
+ █▓( ◕ ◕ )▓█──┘</pre>
+  <span class="brand">◆ <b>tapir</b> · watch less, know more</span>
+  <span class="tip">261 in queue</span>
+</header>
+<p class="note">Tapir fetches captions slowly on purpose, to respect YouTube's limits — new summaries land gradually.</p>
+
+<div class="card ready"><div class="title">How the Attention Economy Rewires Your Brain</div>
+<div class="meta">youtube · 2026-06-11 · 18 min <span class="chip">ready</span></div>
+<div class="preview">A tour of the incentive loops behind infinite feeds and three concrete ways to claw back focus…</div></div>
+
+<article class="card exp ready">
+  <div class="head"><div class="title">Postgres 18 — What's Actually New</div><a class="collapse" href="#">collapse ↑</a></div>
+  <div class="meta">youtube · 2026-06-10 · 42 min · phi4-mini</div>
+  <div class="sec"><h2>Takeaways</h2><ul>
+    <li>Async I/O cuts cold-cache read latency materially on NVMe.</li>
+    <li>Skip-scan makes more multicolumn indexes usable without rewrites.</li>
+    <li>Upgrade path is smooth; test the new planner stats first.</li></ul></div>
+  <div class="sec"><h2>Highlights</h2><ul>
+    <li>Async I/O subsystem (effective_io_concurrency now matters more).</li>
+    <li>B-tree skip scan for leading-column gaps.</li>
+    <li>Better partition-wise joins.</li></ul></div>
+  <div class="sec"><h2>Summary</h2><p class="body">Postgres 18 is an incremental but meaningful release: the headline is the new asynchronous I/O path, with skip-scan and planner improvements close behind. For most homelabs the upgrade is low-risk and worth it for the read-latency wins.</p></div>
+  <div class="dock"><button class="ask">Dig deeper — ask about this video →</button></div>
+</article>
+
+<div class="card"><div class="title">RAG is dead, right?? — Conference Talk</div>
+<div class="meta">youtube · 2026-06-09 · 31 min <span class="chip q">queued</span></div></div>
+</div></body></html>

docs/sketches/b-reader-charm.html

@@ -0,0 +1,62 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>tapir — B · reader + charm accents</title>
+<style>
+:root{--bg:#faf7f2;--card:#fff;--ink:#1c1b22;--soft:#6a6878;--line:#e7e2d8;--mint:#0bbf8c;--purple:#6a4cf0;--pink:#e0379a}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);font:16px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}
+.mono{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+.wrap{max-width:680px;margin:0 auto;padding:20px 16px 60px}
+header{display:flex;align-items:center;gap:10px;margin-bottom:18px}
+.brand{font-weight:800;font-size:18px;letter-spacing:-.3px}
+.brand .dot{color:var(--mint)}
+.tag{color:var(--soft);font-size:13px}
+.tip{margin-left:auto;color:var(--soft);font-size:12px}
+.note{color:var(--soft);font-size:13px;background:#fff;border:1px solid var(--line);border-left:3px solid var(--mint);border-radius:8px;padding:8px 12px;margin:0 0 18px}
+.card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:16px 18px;margin:0 0 14px;box-shadow:0 1px 2px rgba(20,18,40,.04)}
+.title{font-size:18px;font-weight:700;letter-spacing:-.2px;margin:0 0 4px;line-height:1.3}
+.meta{color:var(--soft);font-size:13px}
+.meta .mono{font-size:12.5px}
+.chip{display:inline-block;background:rgba(11,191,140,.12);color:var(--mint);border-radius:999px;padding:1px 9px;font-size:12px;font-weight:600;margin-left:6px}
+.chip.q{background:rgba(224,55,154,.12);color:var(--pink)}
+.preview{color:var(--soft);margin:8px 0 0}
+.exp{border-color:#d9d0ee;box-shadow:0 6px 24px rgba(106,76,240,.10)}
+.head{display:flex;justify-content:space-between;align-items:baseline;gap:10px}
+.collapse{color:var(--purple);font-size:13px;font-weight:600;text-decoration:none;white-space:nowrap}
+.sec h2{font-size:12px;text-transform:uppercase;letter-spacing:1.2px;color:var(--purple);margin:18px 0 6px}
+.sec ul{margin:0;padding-left:20px}.sec li{margin:5px 0}
+.body{line-height:1.7}
+.dock{margin-top:18px;border-top:1px solid var(--line);padding-top:14px}
+.ask{display:inline-flex;align-items:center;gap:6px;background:var(--ink);color:#fff;border:0;border-radius:999px;padding:9px 16px;font:inherit;font-size:14px;font-weight:600;cursor:pointer}
+pre.tapir{margin:0;color:var(--mint);font-size:10px;line-height:1.05}
+</style></head><body><div class="wrap">
+<header>
+  <pre class="tapir">  ▄█▓▓█▄  ∩
+ █▓( ◕ ◕ )▓█──┘</pre>
+  <span class="brand">tapir<span class="dot">.</span></span><span class="tag">watch less, know more</span>
+  <span class="tip mono">261 in queue</span>
+</header>
+<p class="note">Tapir fetches captions slowly on purpose, to respect YouTube's limits — new summaries land gradually.</p>
+
+<div class="card"><div class="title">How the Attention Economy Rewires Your Brain</div>
+<div class="meta mono">youtube · 2026-06-11 · 18 min <span class="chip">ready</span></div>
+<div class="preview">A tour of the incentive loops behind infinite feeds and three concrete ways to claw back focus…</div></div>
+
+<article class="card exp">
+  <div class="head"><div class="title">Postgres 18 — What's Actually New</div><a class="collapse" href="#">collapse ↑</a></div>
+  <div class="meta mono">youtube · 2026-06-10 · 42 min · phi4-mini</div>
+  <div class="sec"><h2>Takeaways</h2><ul>
+    <li>Async I/O cuts cold-cache read latency materially on NVMe.</li>
+    <li>Skip-scan makes more multicolumn indexes usable without rewrites.</li>
+    <li>Upgrade path is smooth; test the new planner stats first.</li></ul></div>
+  <div class="sec"><h2>Highlights</h2><ul>
+    <li>Async I/O subsystem (effective_io_concurrency now matters more).</li>
+    <li>B-tree skip scan for leading-column gaps.</li>
+    <li>Better partition-wise joins.</li></ul></div>
+  <div class="sec"><h2>Summary</h2><p class="body">Postgres 18 is an incremental but meaningful release: the headline is the new asynchronous I/O path, with skip-scan and planner improvements close behind. For most homelabs the upgrade is low-risk and worth it for the read-latency wins.</p></div>
+  <div class="dock"><button class="ask">✦ Ask about this video</button></div>
+</article>
+
+<div class="card"><div class="title">RAG is dead, right?? — Conference Talk</div>
+<div class="meta mono">youtube · 2026-06-09 · 31 min <span class="chip q">queued</span></div></div>
+</div></body></html>

docs/sketches/c-cozy-terminal.html

@@ -0,0 +1,65 @@
+<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>tapir — C · cozy terminal</title>
+<style>
+:root{--bg:#16131d;--card:#1e1a28;--ink:#ece7f5;--soft:#9a92b4;--line:#322b44;--mint:#2ee6b6;--purple:#9d7bff;--pink:#ff6bdb;--cream:#f3ead8}
+*{box-sizing:border-box}
+body{margin:0;background:radial-gradient(1200px 600px at 70% -10%,#231b33,transparent),var(--bg);color:var(--ink);font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Inter,sans-serif}
+.mono{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
+.wrap{max-width:700px;margin:0 auto;padding:20px 16px 60px}
+header{display:flex;align-items:center;gap:12px;margin-bottom:18px}
+.brand{font-weight:800;font-size:18px}.brand .c{color:var(--mint)}
+.tag{color:var(--soft);font-size:13px}
+.tip{margin-left:auto;color:var(--soft);font-size:12px}
+.note{color:var(--soft);font-size:13px;background:#1b1726;border:1px solid var(--line);border-radius:10px;padding:9px 12px;margin:0 0 18px}
+.note b{color:var(--mint);font-weight:600}
+.card{position:relative;background:var(--card);border:1px solid var(--line);border-radius:12px;padding:14px 16px 14px 18px;margin:0 0 13px;overflow:hidden}
+.card::before{content:"";position:absolute;left:0;top:0;bottom:0;width:4px;background:var(--purple)}
+.card.ready::before{background:linear-gradient(var(--mint),var(--purple))}
+.title{font-size:16px;font-weight:700;margin:0 0 4px;color:var(--cream)}
+.meta{color:var(--soft);font-size:12.5px}
+.chip{display:inline-block;border-radius:999px;padding:1px 9px;font-size:11px;font-weight:600;margin-left:6px;background:rgba(46,230,182,.14);color:var(--mint)}
+.chip.q{background:rgba(157,123,255,.18);color:var(--purple)}
+.preview{color:var(--soft);margin:7px 0 0;font-size:14px}
+.exp{border-color:#473a63;box-shadow:0 10px 40px rgba(0,0,0,.35)}
+.head{display:flex;justify-content:space-between;align-items:baseline;gap:10px}
+.collapse{color:var(--mint);font-size:12px;text-decoration:none;border:1px solid var(--line);border-radius:6px;padding:2px 8px;white-space:nowrap}
+.sec h2{font-size:11px;text-transform:uppercase;letter-spacing:1.3px;color:var(--mint);margin:18px 0 7px;display:flex;align-items:center;gap:8px}
+.sec h2::after{content:"";flex:1;height:1px;background:var(--line)}
+.sec ul{margin:0;padding-left:18px}.sec li{margin:5px 0}
+.body{line-height:1.7;color:var(--ink)}
+.dock{margin-top:18px;border-top:1px dashed var(--line);padding-top:14px;display:flex;align-items:center;gap:10px}
+.ask{display:inline-flex;align-items:center;gap:7px;background:linear-gradient(90deg,var(--purple),var(--mint));color:#10101a;border:0;border-radius:999px;padding:9px 16px;font:inherit;font-weight:700;font-size:14px;cursor:pointer}
+.dockhint{color:var(--soft);font-size:12px}
+pre.tapir{margin:0;color:var(--mint);font-size:11px;line-height:1.05}
+</style></head><body><div class="wrap">
+<header>
+  <pre class="tapir">  ▄█▓▓█▄  ∩
+ █▓( ◕ ◕ )▓█──┘</pre>
+  <span class="brand">tapir<span class="c">_</span></span><span class="tag">watch less, know more</span>
+  <span class="tip mono">261 in queue</span>
+</header>
+<p class="note">Tapir fetches captions slowly on purpose, to respect YouTube's limits — <b>new summaries land gradually</b>.</p>
+
+<div class="card ready"><div class="title">How the Attention Economy Rewires Your Brain</div>
+<div class="meta mono">youtube · 2026-06-11 · 18 min <span class="chip">ready</span></div>
+<div class="preview">A tour of the incentive loops behind infinite feeds and three concrete ways to claw back focus…</div></div>
+
+<article class="card exp ready">
+  <div class="head"><div class="title">Postgres 18 — What's Actually New</div><a class="collapse" href="#">collapse ↑</a></div>
+  <div class="meta mono">youtube · 2026-06-10 · 42 min · phi4-mini</div>
+  <div class="sec"><h2>Takeaways</h2><ul>
+    <li>Async I/O cuts cold-cache read latency materially on NVMe.</li>
+    <li>Skip-scan makes more multicolumn indexes usable without rewrites.</li>
+    <li>Upgrade path is smooth; test the new planner stats first.</li></ul></div>
+  <div class="sec"><h2>Highlights</h2><ul>
+    <li>Async I/O subsystem (effective_io_concurrency now matters more).</li>
+    <li>B-tree skip scan for leading-column gaps.</li>
+    <li>Better partition-wise joins.</li></ul></div>
+  <div class="sec"><h2>Summary</h2><p class="body">Postgres 18 is an incremental but meaningful release: the headline is the new asynchronous I/O path, with skip-scan and planner improvements close behind. For most homelabs the upgrade is low-risk and worth it for the read-latency wins.</p></div>
+  <div class="dock"><button class="ask">◆ Ask about this video</button><span class="dockhint mono">answers only from this video's transcript</span></div>
+</article>
+
+<div class="card"><div class="title">RAG is dead, right?? — Conference Talk</div>
+<div class="meta mono">youtube · 2026-06-09 · 31 min <span class="chip q">queued</span></div></div>
+</div></body></html>

docs/specs/chat-with-transcript.md

@@ -0,0 +1,89 @@
+# Spec — Chat with a video's stored transcript (ADR-027)
+
+**Repo:** tapir · **Size:** medium · **Solo session.** Implements ADR-027. Read CLAUDE.md,
+DECISIONS.md (ADR-021 transcript store, ADR-022 model chain, ADR-012 isolation, ADR-027), and
+`docs/ui-spec.md` first. TBD, conventional commits, `task check` green per commit, `templ
+generate` after view changes.
+
+## FIRST: append ADR-027 to DECISIONS.md
+ADR-027 text is provided separately (planning thread). Insert immediately before the
+`## Rejected alternatives` heading, as the first commit, so the decision precedes the build.
+
+## What this is
+A per-video chat letting the user ask questions against a video's **already-stored** transcript,
+entered from the summary view. Born from observed demand: the maintainer read real summaries and
+some made him want to dig deeper — this gives that "I want more" reaction somewhere to go, without
+watching the video.
+
+## HARD CONSTRAINT — stored-transcript-only (the safety property)
+Chat is available **ONLY** for videos that already have a stored transcript (ADR-021). It must
+**never** trigger a caption fetch, never touch the rate gate, never reach YouTube. Entry being
+"from a summarized video" guarantees the transcript exists. If somehow invoked on a video with no
+stored transcript → show "transcript not available for chat", NO fetch. This is what makes the
+feature safe by construction; do not add an on-demand-fetch path (explicitly deferred).
+
+## 1. Entry point
+- A "Dig deeper" / "Ask about this" affordance on the **summary view** of a summarized video
+  (not the list cards — the detail/summary page). Quiet, consistent with the existing card-state
+  styling.
+- Opens a chat panel/view scoped to that one video, with its stored transcript as context.
+
+## 2. The chat
+- Read the stored transcript for the video (via the ADR-021 `TranscriptStore`, keyed by
+  `(provider, provider_video_id)`). No fetch.
+- Send transcript + the user's question + minimal system framing to the chosen model via the
+  **existing LiteLLM gateway** (the same client the summarizer uses — a chat is a different
+  call, not a new integration).
+- Stream or return the answer; render in the chat panel. HTMX/no-JS ethos — match the existing
+  app (the summarize status uses HTMX polling; chat can use a simple POST-and-render or HTMX
+  streaming if clean).
+- **Transcript truncation:** reuse/respect `TAPIR_MAX_TRANSCRIPT_CHARS` (ADR-022) so a long
+  transcript fits the model context. If truncated, the chat should be honest that it's working
+  from a bounded portion (a quiet note), since answers about the tail of a long video may be
+  incomplete.
+
+## 3. Model selection (the instrumentation win)
+- **Default model = the model that produced this video's summary.** (Store/lookup which chain
+  model summarized it — if not already recorded, this is a small addition; if recording it is
+  non-trivial, default to the chain primary and note the gap.)
+- **User can switch** among the ADR-022 chain models (`phi4-mini`, `gemma4-26b`,
+  `mistral-small` to start) via a simple selector in the chat panel. Switching re-runs against
+  the same transcript — this is deliberate model-comparison instrumentation.
+- Respect the local-first / NDA posture: if `TAPIR_CLOUD_FALLBACK_MODEL=""` (cloud disabled),
+  the external model is NOT offered in the switcher — only local models. Chat must honor the same
+  "content stays local" guarantee as ADR-022.
+
+## 4. Ephemeral (v1)
+- No persisted chat history. Conversation lives for the session/page. No new table, no migration.
+- (Multi-turn within a session is fine — keep the running messages in the request/page state —
+  but nothing is written to the DB.)
+
+## 5. Isolation
+- The transcript is shared/non-RLS (ADR-021) — fine, it's public content. But the chat is invoked
+  by a user about a video **in their feed**; confirm the entry path is reachable only for the
+  requesting user's own videos (the summary view is already RLS-scoped). Chat adds no new
+  user-data surface (ephemeral), so there's nothing new to RLS — but the test should confirm a
+  user can only open chat from their own summary view, not arbitrary video ids.
+
+## Tests
+- Chat on a video with a stored transcript → answer returned; assert NO caption-fetch / no
+  YouTube call occurs (the safety property — this is the key assertion).
+- Chat invoked on a video with no stored transcript → honest "not available", NO fetch.
+- Model switch → re-runs against the same transcript with the selected model; cloud model absent
+  from the switcher when `TAPIR_CLOUD_FALLBACK_MODEL=""`.
+- Truncation honored for a long transcript; the bounded-context note shows.
+- Entry is reachable only from the user's own summary view (isolation).
+
+## Out of scope / deferred (record, don't build)
+- **Persisted chat history** (per-user, RLS-scoped) — deferred until evidence anyone revisits a
+  conversation.
+- **Show-source / transcript-verification UI** — the natural v2 (ADR-027 records it); v1 is
+  chat-only/trust-the-model. ADR-021's stored transcript makes v2 cheap when wanted.
+- **On-demand fetch** for un-stored videos — would reintroduce the caption-fetch surface the
+  stored-only constraint removes. Not now.
+- Anything that nudges the user to return (ADR-020 — gate contamination).
+
+## Boundaries
+Stored-transcript-only (HARD). No rate-gate/fetch surface. No auth changes. No new persisted
+state in v1. Reuse the existing gateway client + truncation config; don't build a new model
+integration.

docs/specs/newest-first-ordering.md

@@ -0,0 +1,77 @@
+# Spec — Newest-first batch ordering + honest "Try now" / prioritisation docs
+
+> **Extended by ADR-020 (2026-06-08).** This spec covers the *batch processing* order within a
+> pass. ADR-020 adds (a) a recency pre-filter — auto mode skips videos published before
+> `TAPIR_AUTO_SUMMARIZE_WINDOW`, listed but summarised on demand — and (b) the same
+> `published_at DESC NULLS LAST` ordering on the **list read** (`ListVideos`), which previously
+> sorted by `seen_at`. See `DECISIONS.md` ADR-020.
+
+**Repo:** tapir · **Size:** small · **Solo session.**
+
+**Why.** Product intent (maintainer, 2026-06-06): a new user should get summaries of their
+**newest** videos quickly, while the older back-catalogue fills in behind — all within the one
+shared rate gate. Today the foreground path ("Try now" button) lets a user hand-pick a video,
+but the **background batch processes in subscription/channel order, not newest-first** — so a new
+user with a large candidate set sees the batch summarise whatever channel is first in their
+subscription list, not their newest videos. This slice makes the batch agree with the intent, and
+fixes the docs to describe the real rationale (onboarding prioritisation), not the
+traffic-disguising framing a prior session wrote.
+
+Read `CLAUDE.md` + `DECISIONS.md` (ADR-014, ADR-018) first. TBD, conventional commits,
+`task check` green per commit, `templ generate` if views change.
+
+## 1. Newest-first batch ordering (the build)
+In `internal/runner/runner.go` `RunOnce`: today the loop processes each video inline while
+walking subscriptions channel-by-channel (`for sub → NewVideos → for v → process`). Change so
+that, within a pass, **candidates are processed newest-first across ALL channels**:
+- Collect the candidate videos across channels first (after dedup/seen/manual/rate-limit
+  filtering as today), then **sort by `published_at` descending before processing**, then process
+  in that order through the engine + shared `globalFetchGate`.
+- **`published_at` is nullable** (schema 001). Sort **NULLS LAST** — videos with no publish date
+  must not jump ahead of dated newest videos. Decide a stable tiebreak (e.g. `seen_at DESC`) for
+  equal/again-null dates.
+- Keep all existing behaviour: per-item failure isolation, the rate-limit backoff skip, manual
+  mode, channel-unavailable handling, stats. Ordering is the only change — not what gets
+  processed, just the order.
+- At 868 candidates a collect-then-sort in memory is fine; do **not** build a streaming/external
+  sort. Keep it simple.
+- The shared rate gate (`globalFetchGate`) is unchanged and still governs fetch pacing — ordering
+  does not bypass or weaken it.
+
+**Optional (only if cheap and clearly correct):** a soft cap so the *first* pass for a brand-new
+user summarises the newest N (e.g. 20) quickly and defers the long tail to subsequent passes — so
+onboarding value lands fast without waiting for the whole sorted set. If this adds real
+complexity, SKIP it and just do the newest-first ordering; the ordering alone delivers the intent.
+
+## 2. Tests
+- Given candidates across multiple channels with mixed `published_at` (incl. some NULL), assert
+  the processing order is newest-first, NULLS LAST, with the chosen tiebreak. Use the existing
+  fake VideoStore/Processor pattern in `runner_test.go`.
+- Assert ordering does not change *which* videos are processed vs. today (same set, new order).
+- Rate-gate / backoff / manual-mode behaviour unchanged (existing tests stay green).
+
+## 3. Docs — describe the REAL rationale (replace prior framing)
+The "Try now" button and the discovery batch together implement **onboarding prioritisation**:
+foreground (user-clicked "Try now") summarises a specific video on demand; background batch
+summarises newest-first; both honour the shared rate gate. **Update the docs to state this intent
+— and explicitly REMOVE/replace any framing that describes "Try now" as making traffic "look
+organic to YouTube" or evading rate limits.** That is not the rationale. The rationale is: *get
+the user a few summaries of their newest, most relevant videos fast; process the back-catalogue in
+the background; always within the honest shared rate limit.* Rate limiting is **respected**, not
+evaded.
+- `docs/ui-spec.md`: "Try now" = on-demand foreground summarisation of a chosen (typically newer)
+  video; rationale = fast onboarding value, not traffic shaping.
+- `docs/architecture/architecture.md`: document the two-path model — foreground on-demand vs.
+  background newest-first batch, both through `globalFetchGate` — and the newest-first ordering.
+- Any requirements/use-case doc mentioning discovery order: state newest-first.
+- If a brain note or `wiki` entry captured the "looks organic" rationale, correct it there too.
+
+## Boundaries
+- Do NOT increase fetch rate or weaken the rate gate. Account-safety constraint stands: the
+  caption endpoint is unofficial (ADR-010) and must be treated with honest backoff, never evasion.
+- Do NOT touch RLS, credentials, or the Dex surface.
+- Ordering change is within a pass only — no persisted priority queue, no new table.
+
+## Out of scope
+Per-user configurable ordering; priority weighting beyond newest-first; the soft-cap if it proves
+non-trivial.

docs/specs/onboarding-wow-burst.md

@@ -0,0 +1,128 @@
+# Spec — Onboarding "wow" burst: better picks, stronger model
+
+**Repo:** tapir · **Size:** medium · **Solo session** (not a swarm).
+
+> **Status: built (v0.25.0, ADR-028).** This supersedes the original investigate-first brief
+> (committed as the prior version of this file): Phase 1 was run against the live pilot DB and its
+> findings are folded into "Why this exists" below; Phase 2 was built as described here. The one
+> brief lever NOT built — the honest "the rest fill in over the coming days" framing copy — is
+> listed under *Explicitly NOT in this slice*.
+
+**Why this exists.** A new user's first session decides whether they return (the Stage-0 gate,
+VISION.md). On connect, Tapir fires a capped burst (≤`TAPIR_ONBOARD_SUMMARIZE_COUNT`, default 3)
+that summarizes the user's newest unsummarized videos so the feed isn't empty (the burst itself
+works — wired in `cmd/tapir/discovery.go` → `cmd/tapir/main.go` `onboard`). A Phase-1
+investigation of the live pilot DB found the burst *fires* but delivers a **weak first
+impression** for two concrete reasons, and ruled out a third idea:
+
+1. **Picks are junk.** Selection is pure newest-first (`videos.NewestUnsummarizedVideoIDs`,
+   `ORDER BY published_at DESC`) with **zero quality signal**. Pilot user "Jonte"'s live burst-3
+   were a stock-ticker **livestream** + two regional news clips — the newest, not the best.
+2. **Weakest model on the first impression.** All of Jonte's summaries ran on
+   `koala/phi4-mini` (the documented weak link — ADR-022 was born from its failures). The
+   stronger, brain-validated `iguana/gemma4-26b` was never used for the burst.
+3. **Cached-first is empty at pilot scale — REJECTED.** The idea (summarize already-cached
+   transcripts instantly, zero fetch) dies on the numbers: only **11 videos** overlap between the
+   two pilot users (~3% of each library), **0** cached-and-unsummarized, and a new user's
+   newest-20 unsummarized are **20/20 NOT cached** — newest-first and cached-first are
+   structurally incompatible (fresh uploads are exactly what nobody has fetched yet). Not built.
+
+This is a **curation/latency problem for ~3 videos, NOT a throughput/429 problem** — fetching 3
+captions is nowhere near the rate limit. Nothing here fetches harder or pressures the rate gate;
+it picks the right few videos and runs a better model on them.
+
+Read `CLAUDE.md`, `DECISIONS.md` (esp. ADR-014, ADR-018, ADR-020, ADR-021, ADR-022, ADR-023,
+and the new **ADR-028**), and `VISION.md` (the Stage-0 gate) first. TBD — commit directly to
+`main`, one logical change per commit, conventional commits, `task check` green before each
+commit, `templ generate` if any view changes (none expected).
+
+## Decisions already made (do not reopen)
+- **Not a throughput change.** The caption rate gate (ADR-014) is untouched — same pacing, same
+  priority lane (ADR-026). This slice changes *which* ≤3 videos the burst spends its fetches on
+  and *which model* summarizes them, never how fast or how many.
+- **Cached-first is dropped** (ADR-028, the 3% overlap). The engine's existing read-stored-first
+  (ADR-021, `resolveTranscript`) stays — it already gives a free instant summary on the rare
+  cache hit, transparently. We do not *select* for cache hits.
+- **has-captions is not a pre-fetch signal.** It is only knowable after a gate fetch (or a cache
+  hit, ~0 for new videos). Selection can only *avoid known-junk* (Shorts/live/over-long) — it
+  cannot *guarantee* captions. The spec is honest about this: better odds, not a promise.
+- **No credentialed caption fetch** (ADR-010/ADR-026 dead end). **No client extension.**
+
+## 1. Persist `duration_s` at discovery (the enabling change)
+The `videos.duration_s` column exists (migration 001) but is **never written** — ADR-023's
+`filterLowValue` (`internal/adapters/youtube/youtube.go`) already fetches each candidate's
+duration via the cheap quota `videos.list` call, uses it to drop Shorts/live, then **discards
+it**. Stop discarding:
+- Add `DurationSeconds int` to `domain.Video`.
+- In `filterLowValue`, set `DurationSeconds` on each kept video from the `videos.list` `meta`.
+- `UpsertVideo` writes `duration_s`, **COALESCE-preserving** a known value (never overwrite a
+  real duration with 0/unknown), mirroring the `channel_title` backfill stance (migration 014).
+- No new migration — the column is already there.
+
+Consequence: a fresh user's connect-triggered discovery pass runs **before** the onboard burst
+(`Enqueue`: `run()` then `onboard()`), so duration is populated for the burst's candidates at
+connect. Existing rows backfill on their next discovery pass; until then their `duration_s` is
+NULL and treated as "unknown" (§2).
+
+## 2. Junk-avoiding burst selection
+New store method, RLS-scoped via `withUser`:
+
+```
+OnboardBurstVideoIDs(ctx, userID string, limit, minSeconds, maxSeconds int) ([]string, error)
+```
+
+- Same base as the old `NewestUnsummarizedVideoIDs`: the user's videos with no summary yet,
+  `ORDER BY published_at DESC NULLS LAST, seen_at DESC`, `LIMIT limit`.
+- **Exclude known-junk**: a row is dropped only when `duration_s IS NOT NULL` **and**
+  (`duration_s < minSeconds` OR `duration_s > maxSeconds`). A NULL duration is **unknown** — kept
+  (degrade-open: never starve the burst because metadata is missing), but ordered *after* rows
+  with a known-good duration so a freshly-enriched good pick wins when both exist.
+- `minSeconds` reuses `TAPIR_MIN_VIDEO_SECONDS` (default 60 — the Shorts floor, ADR-023).
+  `maxSeconds` is new: `TAPIR_ONBOARD_MAX_VIDEO_SECONDS` (default 14400 = 4h) — drops the
+  multi-hour livestream VODs that pass the live filter once ended.
+- `minSeconds<=0` and `maxSeconds<=0` each disable that bound (so `0/0` == the old
+  newest-first behaviour, the reversibility lever).
+- The burst switches to this method; `NewestUnsummarizedVideoIDs` is removed (fully superseded —
+  `OnboardBurstVideoIDs(., 0, 0)` is identical pure-newest behaviour).
+
+## 3. Stronger model for the burst
+The burst summarizes only ≤3 videos, so a slower, stronger model is affordable exactly here.
+- New config `TAPIR_ONBOARD_SUMMARIZER_MODEL` (default `iguana/gemma4-26b` — the brain-validated
+  homelab general-purpose model, already the ADR-022 fallback).
+- Build a **burst-specific summarizer chain** that puts the onboard model **first**, then the
+  standard chain (primary → local fallback → cloud) as resilience, deduped. Wrap it in a
+  burst-specific `engineProcessor` reusing the same store/transcript-cache/sink — a pure wiring
+  choice, engine and ports unchanged (Clean Architecture, ADR-003).
+- The `onboard` closure uses the burst processor instead of `app.Processor`.
+- **Collapse cleanly**: when `OnboardSummarizerModel` is empty or equals `SummarizerModel`, the
+  onboard path reuses `app.Processor` (no separate chain) — the reversibility lever.
+- Local-first preserved: the onboard model is a local alias; the cloud endpoint stays last in the
+  chain, so a client/NDA deployment with `TAPIR_CLOUD_FALLBACK_MODEL=""` keeps burst content
+  local too.
+
+## 4. Behaviour spec + docs
+- Add scenarios to `docs/use-cases/connect_account.feature` (the connect → burst flow): burst
+  skips a too-long/live video in favour of a reasonable-length one; burst summarizes with the
+  stronger model first. Map them in `scenarioCoverage` so `TestScenarioCoverage` stays green.
+- Update `docs/architecture/architecture.md` (the onboarding-burst section) to describe the
+  junk-avoiding selection + the burst model override.
+- ADR-028 in `DECISIONS.md` records the rationale (incl. the rejected cached-first lever).
+
+## Success criteria
+- `task check` green (fmt, vet, lint, `go test -p 1 ./...`).
+- A unit test proves `OnboardBurstVideoIDs` drops a known too-long / sub-min video and keeps a
+  good one, newest-first, RLS-scoped, unsummarized-only.
+- A test proves discovery persists `duration_s` and does not clobber it on re-upsert.
+- A test proves the burst chain leads with the onboard model (then the standard chain).
+- Config defaults + bounds tested (`OnboardMaxVideoSeconds`, `OnboardSummarizerModel`).
+- No change to the rate gate, fetch pacing, or burst cap. `0/0` + empty model == prior behaviour.
+
+## Explicitly NOT in this slice
+- Cached-first selection (rejected, ADR-028).
+- Any caption-availability *guarantee* (impossible pre-fetch).
+- **Honest "taster" framing copy** ("summaries of a few of your videos to get you started — the
+  rest fill in over the coming days"). A good lever from the original brief, but it's a UI/copy
+  change with no backend dependency; deferred to a UI pass, tracked as an issue.
+- Backfilling `duration_s` for existing rows via a migration (it backfills lazily on discovery).
+- Return-nudges / digests (ADR-020: poisons the unprompted-return signal).
+- Raising fetch throughput, multi-IP, or Whisper (out of scope; the gate is deliberate).

docs/specs/scheduled-discovery.md

@@ -0,0 +1,92 @@
+# Spec — In-process scheduled discovery + auto-summarize + rate-gate finish
+
+> **Extended by ADR-020 (2026-06-08).** Auto-summarize is no longer "every unseen video": the
+> scheduler now skips videos published before `TAPIR_AUTO_SUMMARIZE_WINDOW` (default ~7d) unless
+> explicitly requested, so a back-catalogue does not re-drive the rate gate every cycle. See
+> `DECISIONS.md` ADR-020.
+
+**Repo:** tapir · **Size:** medium · **Solo session** (not a swarm).
+
+**Why this exists.** The Stage-0 gate ("me or a friend returns and reads/acts in ≥2 separate
+weeks") cannot be met because the system is not usable *unprompted*: discovery (`tapir run`) is
+host-side manual, so a newly onboarded user sees an empty list and never comes back. This slice
+makes Tapir watch on its own — the thing that makes the gate experiment actually runnable.
+
+Read `CLAUDE.md` + `DECISIONS.md` (esp. ADR-012, ADR-014, and the new ADR-018) first. TBD —
+commit directly to `main`, one logical change per commit, conventional commits, `task check`
+green before each commit. `templ generate` if any view changes.
+
+## Decisions already made (do not reopen)
+- **In-process scheduler**, NOT a k8s CronJob (maintainer's call: simpler deploy, acceptable
+  coupling at 3 users). The known cost — discovery shares the web process's lifetime and egress
+  — is accepted and recorded in ADR-018.
+- **Auto-summarize ON** for the maintainer + onboarded friends (zero-friction: the list fills
+  and summarizes itself).
+- **Gate clock resets** to when this ships (ADR-018) — until unprompted use is possible, the
+  prior window measured nothing.
+
+## 1. In-process scheduled discovery (core)
+- In `tapir serve` startup, launch a background goroutine that runs discovery for ALL users on
+  an interval: env `TAPIR_DISCOVERY_INTERVAL` (Go duration, e.g. `2h`). **Unset or 0 = disabled**
+  (so dev/tests never auto-fetch).
+- **Reuse the existing `runner.Runner` + `Loop`/`RunOnce`. Do NOT write a new scheduler.** The
+  per-user Runner already exists; the new work is **iterating users** and running one pass each
+  per tick. Enumerate users from the un-RLS'd `user_identities` (the same enumerate-then-act
+  pattern the login_events gate query established), then run each user's pass **inside that
+  user's RLS scope** (`withUser`).
+- **Stateless timing:** run-once-on-startup, then every interval — exactly the existing `Loop`
+  shape. Do NOT persist schedule state; a pod restart just restarts the cycle. Acceptable at this
+  scale. Do not build cron-in-Go.
+- **Graceful shutdown:** the goroutine respects `ctx` cancellation so a pod term doesn't wedge.
+- **Failure isolation in the loop:** one user's pass failing (or one channel/video) must not
+  abort the other users or crash `serve` — log and continue. (RunOnce already collects per-item
+  errors; preserve that at the per-user level too.)
+
+## 2. Auto-summarize default ON for Future-B users
+- New registrations default `auto_summarize = true` (so onboarded friends get zero-friction);
+  keep the account-page toggle so a user can switch to manual. One-off update existing user rows
+  to `true` as well (maintainer + any current users).
+- Consequence (intended): scheduled discovery both discovers AND summarizes new videos — which
+  is the point, and is why §3 is mandatory in the same slice.
+
+## 3. Finish/confirm the ADR-014 shared per-egress-IP rate gate (NOW load-bearing)
+- In-process scheduling + auto-summarize + multiple users = all caption fetches leave the **one
+  web pod's egress IP**, concurrently with any live "Summarize" button clicks. The timedtext
+  endpoint rate-limits per IP (ADR-010/014). Without a shared gate this self-inflicts 429s every
+  cycle.
+- **Confirm in code whether ADR-014 item 2 (a single PROCESS-WIDE rate gate) exists.**
+  Reconciliation flagged it as possibly built only as per-*video* backoff. If it is not a
+  process-wide gate, **build it now**: ONE shared limiter (token-bucket / min-interval) that
+  every timedtext/caption fetch passes through — scheduler loop AND click-path alike. Per-process,
+  not per-user, not per-video.
+- Keep the existing per-video 429 backoff (`rate_limited_at` + retry window) — complementary: the
+  gate prevents tripping 429; the backoff handles it if one still happens.
+- Honest UX (ADR-014 item 3) still applies: a fetch waiting on the gate shows "queued/waiting",
+  never a stuck spinner.
+
+## 4. Gate-clock reset — already recorded in ADR-018; verify VISION reflects it
+- ADR-018 (committed) resets the Stage-0 3–4 week window to start when this ships, and revises the
+  check-in date. VISION Stage 0 carries a pointer to it. The build doesn't re-decide this; just
+  ensure nothing in docs still implies the clock started earlier.
+
+## Tests
+- **Scheduler:** fake clock + fake Runner → N users each get one pass per tick; one user's failure
+  doesn't stop the others; `ctx` cancel stops the loop; interval=0 disables it entirely.
+- **Rate gate:** concurrent fetches (scheduler + simulated click) are serialized/limited through
+  the ONE gate — assert max-in-flight / min-interval honored regardless of caller.
+- **Auto-summarize default:** new registration → `auto_summarize = true`; account-page toggle
+  still flips it.
+
+## Out of scope / known constraints
+- No CronJob / k8s objects (in-process chosen).
+- **SINGLE-REPLICA ASSUMPTION (load-bearing).** In-process scheduling means if `tapir serve` ever
+  runs >1 replica, every replica runs the discovery loop → every user fetched in parallel (429s +
+  duplicate work). At 3 users this is single-replica, fine — but the build MUST note this
+  constraint in ADR-018 / deploy docs so a future scale-up doesn't silently double-run.
+- No persisted schedules, no multi-pod coordination.
+
+## Fallback if the session runs short
+Ship the scheduler with **auto-summarize OFF** (discovery only; manual Summarize button) until the
+process-wide rate gate (§3) is confirmed/built. NEVER ship auto-summarize-on-a-schedule without the
+gate — that combination self-inflicts 429s for every user every cycle. Auto-summarize ON is gated
+on §3 being done.

docs/specs/video-card-states.md

@@ -0,0 +1,77 @@
+# Spec — Unify video-card states: one "Summarize now" verb, honest no-captions state
+
+> **Superseded in part by ADR-020 (2026-06-08).** The five card states still hold, but the copy
+> changed: the nudge verb is now **"Summarize"** (not "Summarize now"), the rate-limited state
+> reads **"In queue"** (not "Fetching soon…"), and the queued state reads **"summarizing
+> shortly"** (not "waiting for the next run"). The list also now collapses older un-summarized
+> and caption-less videos. See `DECISIONS.md` ADR-020 and `views.templ` (`VideoCard`) for the
+> current copy; this doc is kept as the original design record.
+
+**Repo:** tapir · **Size:** small, **view-layer only** (`views.templ` + a little CSS in
+`view.go`; regenerate `views_templ.go`). No handler, store, or DB change. The two existing
+handlers (`/summarize`, `/retry-now`) stay exactly as they are — only what the card *shows*
+changes.
+
+**Why.** The video card today presents two different verbs — "Try now" (`.btn-retry`, on
+rate-limited videos) and "Summarize" (`.btn-secondary`, on pending videos) — for what the user
+experiences as one intent: *"summarize this video now."* The user doesn't know or care about the
+internal pipeline state (rate-limited vs. manual-queue); two differently-labelled, differently-
+styled buttons leak that state machine into the UI as a choice. Also: a **no-captions video
+(`TranscriptStatus == "none"`) currently falls into the `else` branch and wrongly shows a
+"Summarize" button** that, if clicked, tries and fails — there are no captions to fetch. That's
+the confusing dead-end to remove.
+
+In normal use the maintainer is in **auto mode**, so these buttons are *exceptions*, not the main
+path — videos summarize themselves. So the card should be **status-first**: the state is what the
+user reads constantly; the manual nudge is a small, quiet affordance for impatience, not a
+prominent call-to-action.
+
+## The honest per-state card model (footer of `VideoCard`)
+
+Restructure the footer branch in `VideoCard` (in `internal/web/views.templ`) to these states.
+The branch ORDER matters (summarized first, then terminal/no-action states, then actionable):
+
+1. **Summarized** — preview + provider chip + fallback badge + actions. **No button.** (unchanged)
+2. **No captions** (`r.TranscriptStatus == "none"`) — **NEW branch.** Quiet status text, e.g.
+   `No transcript available` (use a muted `.card-state`/`.chip-retry`-style treatment, NOT a
+   button). This is a terminal honest dead-end — the user can do nothing, so offer nothing.
+3. **Queued / requested** (`r.SummarizeRequested`) — "Queued · waiting for the next run". **No
+   button.** (unchanged)
+4. **Rate-limited** (`r.TranscriptStatus == "rate_limited"`) — quiet status (keep the
+   "fetching soon" sense) + a **quiet "Summarize now"** button POSTing to `retryNowURL` (clears
+   backoff then processes). Same quiet style as state 5.
+5. **Pending** (else — discovered, not yet attempted) — quiet "Not summarized" + a **quiet
+   "Summarize now"** button POSTing to `summarizeURL` (flips the queue flag then processes).
+
+## Unify the verb and the style
+- **One label everywhere a manual nudge is offered: "Summarize now"** (states 4 and 5). Drop the
+  "Try now" wording entirely.
+- **One quiet style** for both: use the understated `.btn-retry` pattern (small, pill, outline,
+  transparent bg) — NOT `.btn-secondary`/`.btn` (heavier). Rename the CSS class to something
+  state-neutral (e.g. `.btn-quiet` or `.btn-summarize-now`) so it no longer reads as
+  "retry"-specific; keep the same visual. The point: the nudge is subtle, status is primary.
+- Keep both `<form>`s posting to their respective existing handler URLs
+  (`retryNowURL` for rate-limited, `summarizeURL` for pending) with the existing HTMX
+  attributes (`hx-post`, `hx-target=#video-{id}`, `hx-swap=outerHTML`) — only the button
+  label/class change. The backend side-effect difference (clear-backoff vs. set-flag) stays
+  invisible to the user, which is correct.
+- Drop the engineer-facing `title="Fetch transcript now through the shared rate gate"` tooltip;
+  if a hint is wanted, make it user-facing ("Summarize this one now").
+
+## Quietness check (the design intent)
+The summary content and the per-state *status* are the card's primary information. The "Summarize
+now" button is a minor affordance. Do not make it a prominent solid-accent CTA — it must read as
+"you can nudge this if you're impatient", not "action required". Status text uses muted styling;
+the button uses the quiet outline style.
+
+## Tests
+- `videocard_internal_test.go` (exists): assert each of the 5 states renders the expected
+  footer — summarized (no button), no-captions (status, NO button, no `summarize`/`retry-now`
+  URL present), queued (no button), rate-limited ("Summarize now" → retry-now URL), pending
+  ("Summarize now" → summarize URL). The key new assertion: **a `none`-status video renders no
+  action button and no POST URL.**
+- Assert the label string "Try now" no longer appears anywhere in rendered output.
+
+## Out of scope
+Handler/DB changes; the detail-page action buttons (watched/skipped/saved — unrelated); the
+pipeline stats bar wording; auto/manual mode behaviour. Verb/label/style/no-captions-state only.

docs/ui-spec.md

@@ -72,7 +72,14 @@ summary_actions
   and join into the existing `SummaryRow` reads so list/detail show current state.
 - This column is what makes the Stage-0 metric ("did I act on a summary?") queryable.
 
-## 6. Auth (Dex OIDC, single-user authz)
+## 6. Auth (Dex OIDC)
+
+Authentication is delegated to the homelab OIDC provider at `TAPIR_OIDC_ISSUER` —
+**Authentik** since the Dex→Authentik migration (infra ADR-0001; ADR-019). It offers a
+Google upstream and Authentik-managed accounts (incl. its invite flow); Tapir no longer
+provisions accounts itself. Any authenticated subject can register a Tapir account
+(ADR-012: allowlist removed). The `oidc`/`DexAuth` package keeps its name for now (rename
+deferred, ADR-019).
 
 - **Flow:** standard Authorization Code. Use `coreos/go-oidc` + `golang.org/x/oauth2`
   (justify the deps in the commit; both are the homelab-standard OIDC libs and small).
@@ -92,7 +99,7 @@ summary_actions
 `TAPIR_OIDC_ISSUER` (`https://auth.d-ma.be`), `TAPIR_DEX_CLIENT_ID`, `TAPIR_DEX_CLIENT_SECRET`,
 `TAPIR_OIDC_REDIRECT_URL` (`https://tapir.d-ma.be/auth/callback`), `TAPIR_SESSION_SECRET`.
 Reuses existing `TAPIR_DB_DSN`, `TAPIR_USER_ID` (the StubAuth dev subject only). No secrets
-committed. (`TAPIR_ALLOWED_SUBJECT` was removed by ADR-012.)
+committed. (`TAPIR_ALLOWED_SUBJECT` was removed by ADR-012; use the keys above.)
 
 ## 8. Deployment — k3s + Flux GitOps
 
@@ -163,12 +170,14 @@ distinguishable.
 | **Registration gate** | A Dex subject with no `users` row is routed to `/register`, which creates the `users` row + a `user_identities` mapping. (§2 listed "sign-up / user CRUD" as a non-goal.) | Explicit registration is how a multi-user surface stays honest — no just-in-time row creation. | ADR-012; `f396e01` |
 | **Per-user YouTube web connect** | `/oauth/youtube/connect` → `/oauth/youtube/callback` stores a per-user refresh-token ref + a `video_connections` row. (The spec assumed a host-side `tapir auth` only.) | Multi-user means each user connects their own account from the browser. | ADR-006, ADR-012; migration 005 (`0c9531a`, `2aad79b`) |
 | **Account management** | `/account` page with **disconnect** and **delete account**; delete removes only Tapir-side state and leaves the Dex identity intact. (§2 listed isolation/CRUD as non-goals.) | A real account needs a way out; deletion semantics are deliberately Tapir-side only. | ADR-013; `22eafcf`, `c7624d9`, `17d5e8c` |
-| **Immediate web summarization** | A "Summarize" button (`POST /v/{id}/summarize`) runs the engine in a background goroutine inside `serve`; the page HTMX-polls `GET /v/{id}/status`. (§2 said "triggering runs from the browser … do NOT build".) | Reading a list you can't act on is half a product; on-demand summarize closes the loop without waiting for a batch `tapir run`. | ADR-012, ADR-014; `25215cb`, `8c6c7ca` |
+| **Immediate web summarization** | A quiet "Summarize now" button on non-summarized video cards. Pending cards POST to `/v/{id}/summarize` (queues + triggers engine); rate-limited cards POST to `/v/{id}/retry-now` (clears backoff + triggers engine). Both use the same `.btn-quiet` style and label — the internal pipeline distinction is invisible to the user. The page HTMX-polls `GET /v/{id}/status` while processing. Videos with `TranscriptStatus == "none"` show "No transcript available" with no button — this is a terminal honest state. (§2 said "triggering runs from the browser … do NOT build".) | Reading a list you can't act on is half a product; on-demand summarize closes the loop without waiting for a batch `tapir run`. | ADR-012, ADR-014; `25215cb`, `8c6c7ca` |
 | **Charmbracelet tapir spinner** | An animated in-flight indicator (charm palette) shown while a summarize is processing; an honest "queued/waiting" state under rate-limiting rather than a stuck spinner. | The spinner must tell the truth when the timedtext endpoint rate-limits (429), not imply imminence. | ADR-014; `25215cb`, `a4aeb5e` |
-| **Auto/manual summarization mode** | Per-user `auto_summarize`; manual (default) lists new videos unsummarized and queues via `summarize_requested`; a mode toggle at `/account/summarize-mode`. | Control over compute/noise — only summarize what the user cares about. | migration 006 (`748d5eb`, `bdbdce7`, `3014ee0`, `a269d4a`) |
+| **Auto/manual summarization mode** | Per-user `auto_summarize`; manual lists new videos unsummarized and queues via `summarize_requested`; a mode toggle at `/account/summarize-mode`. Default is **true** for new users (migration 011, ADR-018); existing rows back-filled via migration 012. | Control over compute/noise — only summarize what the user cares about. | migration 006 (`748d5eb`, `bdbdce7`, `3014ee0`, `a269d4a`); migration 011/012 |
 | **Public landing page** | `/welcome` mounted **outside** the auth guard; unauthenticated `/` redirects there; logout returns there (not `/auth/login`). (The spec guarded everything except `/healthz` and `/auth/*`.) | A first-time visitor needs a public "what is this / get started" page before the login wall. | `d83943c`, `0fdf2f7`, `3a27bf1`, `d208110`, `8ca374e`, `f15f57f` |
-
-The original Stage-0 goals (read summaries, record watch/skip/save actions, Dex login, GitOps
-deploy) still hold — these are additions over that base, not replacements. The architecture
-stance is unchanged: every item above is web-surface or store work; the engine/ports/sinks core
-was not modified (ADR-003).
+| **Invite onboarding** | **Removed from Tapir (ADR-019).** Invites are owned by the IdP (Authentik) now, not Tapir — the Dex local-password provisioning path (`tapir invite` CLI, `/invite/{token}` web flow, `internal/adapters/dex`) was deleted when the homelab migrated Dex→Authentik (infra ADR-0001). A new user is invited via Authentik's invite flow, logs into Tapir via OIDC, and is captured by the existing `/register` (display-name) gate. | Onboarding belongs to the identity provider; keeps Tapir out of the shared identity provider's write path. | ADR-019; infra ADR-0001 |
+| **Summarized-only filter** | `?summarized=1` query param on the list view. When set, only videos with a completed summary (`SummaryRow.Summarized = true`) are shown. Rendered as a "Summarized only" checkbox in the filter form. Summarized videos also sort to the top of the unfiltered list (`ORDER BY (s.id IS NOT NULL) DESC, seen_at DESC`). | Lets users focus on videos that are ready to read; newly landing summaries are visible at the top without filtering. | `internal/web/view.go` (`Filter.OnlySummarized`, `ListVideos` ORDER BY) |
+| **"Summarize now" foreground path** | Unified quiet nudge button on actionable non-summarized cards. Five explicit card states — (1) summarized: chip + no button; (2) no captions (`transcript_status = 'none'`): "No transcript available", no button; (3) queued: "Queued" chip, no button; (4) rate-limited: "Fetching soon…" + "Summarize now" → `POST /v/{id}/retry-now` (clears `rate_limited_at`, triggers engine); (5) pending: "Not summarized" + "Summarize now" → `POST /v/{id}/summarize` (queues + triggers engine). One verb, one style (`.btn-quiet`); backend difference invisible to user. Both handlers call `ProcessVideo` through `globalFetchGate`. Rate gate respected, not bypassed — this is onboarding prioritisation. | Fast onboarding value; honest dead-end for no-captions videos (no button that fails). | `internal/web/handlers.go` (`handleRetryNow`, `handleRequestSummarize`); `internal/web/views.templ` (`VideoCard`) |
+| **Pipeline stats bar** | A one-line status bar above the video list: `N summarized · M fetching soon · K no captions`. Computed from the unfiltered row set; hidden when all videos are summarized. Gives the user a clear read on pipeline state without any interaction. | Replaces the "why is nothing happening?" confusion when most videos are pending or rate-limited. | `internal/web/view.go` (`PipelineStats`, `pipelineStats`) |
+| **Unavailable channels (account page)** | The `/account` page shows a "Unavailable channels" section when any channels returned HTTP 404 on the last discovery pass. Lists channel name, an "unavailable" badge, and the first-seen date. Data sourced from the `channel_errors` table (migration 013). | Surfaces silent failures so users know why some subscribed channels produce no new videos. | migration 013; `internal/web/account.go`; `internal/adapters/youtube/youtube.go` (`domain.ErrChannelUnavailable`) |
+| **Visual refresh — charm-reader theme + light/dark toggle (ADR-032)** | One layout in two palettes expressed as CSS custom properties: a warm "reader" light theme (sketch B) and a "cozy terminal" dark theme (sketch C). Palette is chosen in cascade order — `:root` light default, an OS-preference dark block scoped to `:root:not([data-theme])` so it only applies absent an explicit choice, and `:root[data-theme="dark"\|"light"]` set by a header toggle that outranks the media query and persists in `localStorage` (guarded; degrades to OS default). An init script in `<head>` applies the stored choice before paint (no flash). Charm touches: monospace meta lines, accent uppercase section dividers with a trailing rule, pill buttons, a lifted/accent-edged expanded card. Error/danger shades became `--err-*` tokens so they follow the theme without per-block dark overrides. Sketches kept as the design record under `docs/sketches/`. | The UI read "flat and boring"; the charm/TUI aesthetic makes it distinctive and gives a real light/dark choice rather than OS-only. | ADR-032; `docs/use-cases/visual_theme.feature`; `internal/web/visual_theme_test.go`; `internal/web/view.go` (`stylesheet`, `themeScript`), `internal/web/views.templ` (Layout/PublicLayout) |
+| **Recency window + sparse-state honesty (ADR-020)** | Supersedes the copy/sort in the rows above. Auto-summarize is bounded to videos published within `TAPIR_AUTO_SUMMARIZE_WINDOW` (~7d); older un-summarized videos collapse behind a single "Show N older videos — summarize on demand" disclosure, and caption-less videos collapse to a one-line count (not N cards). List order is now `summarized-first, published_at DESC NULLS LAST`. Copy reframed for honest scarcity: pipeline bar reads "N ready · M in queue · K no captions" (no "fetching soon"); a gradual-fill note explains the rate limit; the nudge verb is "Summarize" (not "Summarize now"); the queued card says "summarizing shortly"; the empty-connected state drops the impossible `tapir run` instruction. Detail leads with Takeaways. Filters slimmed (no date pickers; hidden when empty); watched/skipped segmented; back link on detail; empty terms checkbox removed. | Make the sparse reality legible and honest instead of implying abundance/imminence; bound auto load so the back-catalogue doesn't re-drive the caption gate. Never fetch harder — scarcity is surfaced, not engineered around. | ADR-020; `2384c47`, `3df0459`, `40b703e`, `a1a5217`, `4a0a56e`, `9bf1c31`, `980638d`, `12fb031`, `f775441`, `51aa5d9` |

docs/use-cases/ai_routing.feature

@@ -31,5 +31,17 @@ Feature: Local-first AI with optional BYO fallback
     When any transcript is summarized
     Then my content is only ever sent to the local AI stack
 
-  # "Reliably" is operationalized as: Primary returned without error within timeout.
+  Scenario: A model returns unparseable output and the next endpoint succeeds
+    Given the local AI stack is available
+    But the primary model returns output that cannot be parsed into a summary
+    And a fallback model is configured
+    When a transcript is summarized
+    Then Tapir falls back to the next model in the chain
+    And the summary records fallback_used as true
+
+  # "Reliably" is operationalized as: an endpoint returned a PARSEABLE summary
+  # within timeout. A 200 with malformed JSON (or highlights emitted as a bare
+  # string) counts as a failure and advances the chain (ADR-022). Endpoints are
+  # tried in order, locals first, so the external worst-case model only ever sees
+  # content after every local endpoint has failed.
   # Quality scoring may be added later without changing these scenarios.

docs/use-cases/chat_transcript.feature

@@ -0,0 +1,69 @@
+Feature: Chat with a video's stored transcript
+  As a reader whose summary made me want to dig deeper
+  I want to ask questions about the video without watching it
+  So that I can go further on the ones worth it, without leaving the reader
+
+  # ADR-027. The load-bearing constraint is safety-by-construction: chat runs
+  # ONLY against an already-stored transcript (ADR-021) and never fetches captions,
+  # never touches the rate gate, never reaches YouTube. Entry is from the summary
+  # view of one's OWN video; the conversation is ephemeral (no persisted history).
+
+  Background:
+    Given I have a summarized video with a stored transcript
+
+  Scenario: A summary view offers a deeper-dive into the video
+    When I view the summary
+    Then I see a "dig deeper" affordance that opens a chat about this video
+    And it opens the chat in place, below the summary, without leaving the page
+
+  Scenario: The summary and the chat are on one page
+    When I open the chat
+    Then the summary stays visible alongside the chat
+    And I can read the summary while I ask questions
+
+  Scenario: Ask a question answered from the stored transcript
+    When I ask a question in the chat
+    Then the answer is produced from the stored transcript
+    And no caption fetch and no YouTube call occurs
+
+  Scenario: Chat never fetches captions or reaches YouTube
+    When I ask a question in the chat
+    Then Tapir reads only the stored transcript
+    And the caption-fetch and video-fetch paths are never invoked
+
+  Scenario: A video with no stored transcript offers no chat
+    Given a video that has no stored transcript
+    When I open the chat for it
+    Then I am told chat is not available
+    And no fetch is attempted and no model is called
+
+  Scenario: The default model is the summary's model and is switchable
+    When I open the chat
+    Then the model defaults to the model that produced the summary
+    And I can switch among the offered chain models
+
+  Scenario: Switching models re-runs against the same transcript
+    When I ask a question with a different chain model selected
+    Then the chosen model answers
+    And it answers against the same stored transcript
+
+  Scenario: The cloud model is hidden when cloud is disabled
+    Given the cloud fallback model is disabled
+    Then the chat switcher offers only local models
+
+  Scenario: A long transcript is bounded and the chat says so
+    Given the stored transcript is longer than the model budget
+    When I ask a question
+    Then the answer is produced from a bounded portion
+    And the chat notes that it worked from a bounded portion
+
+  Scenario: A multi-turn conversation is ephemeral
+    When I ask a follow-up question
+    Then the prior turn is carried into the answer
+    And nothing about the conversation is written to the database
+
+  Scenario: Chat is reachable only from my own summary view
+    Given another user has a summarized video with a stored transcript
+    When I try to open the chat for their video
+    Then I get a not-found response
+    And no model is called

docs/use-cases/connect_account.feature

@@ -10,12 +10,33 @@ Feature: Connect and manage video accounts
     And my refresh token is stored only as a secret reference
     And my subscriptions are synced
 
+  @pending
+  # Vimeo connect is not built yet (provider label exists; no connect flow or test).
   Scenario: Connect a Vimeo account
     Given I have no connected video accounts
     When I connect my Vimeo account
     Then the connection is stored with status "active"
     And my subscriptions are synced
 
+  Scenario: Connecting an account discovers videos immediately
+    Given I have no connected video accounts
+    When I connect my YouTube account
+    Then a discovery pass for my account is triggered right away
+    And I do not have to wait for the next scheduled pass to see my videos
+
+  Scenario: Connecting summarizes my best recent videos right away
+    Given I have no connected video accounts
+    When I connect my YouTube account
+    Then up to the onboarding cap of my newest likely-good videos are summarized through the rate gate
+    And videos whose known duration is too short or too long are skipped
+    And the rest are left to the scheduled recency-bounded pass
+
+  Scenario: The onboarding burst summarizes with a stronger model
+    Given I have no connected video accounts
+    When I connect my YouTube account
+    Then the burst summarizes with the stronger onboarding model first
+    And the standard summarizer chain still follows as a fallback
+
   Scenario: Tokens are never stored in the clear
     When I connect any video account
     Then no OAuth token value is stored in the database
@@ -28,6 +49,9 @@ Feature: Connect and manage video accounts
     And no new videos are watched for that connection
     And my existing summaries remain readable
 
+  @pending
+  # Per-provider BYO credential config is not built as a web flow yet (the summarizer
+  # supports a fallback endpoint, but there is no user-facing BYO setup + its test).
   Scenario Outline: BYO AI credential is optional and per-provider
     When I configure a BYO provider "<provider>"
     Then the credential is stored only as a secret reference

docs/use-cases/inline_expand.feature

@@ -0,0 +1,37 @@
+Feature: Inline-expand summary + Q&A in the list (ADR-031, #16)
+  As a reader skimming my summaries
+  I want to open a summary and its Q&A in place in the list
+  So that I get the full read and follow-up without leaving the list (SPA-like, no page hop)
+
+  # HTMX inline-expand, no SPA framework (ADR-031). Each scenario maps to a Go test
+  # in scenario_coverage_test.go (the BDD name-coverage gate).
+
+  Scenario: A summarized card expands to the full summary in place
+    Given a summarized video in my list
+    When I expand its card
+    Then the full summary, highlights, and takeaways are returned as an in-place card fragment, not a full page
+
+  Scenario: An expanded card collapses back to the compact card
+    Given an expanded card
+    When I collapse it
+    Then the compact card fragment is returned in its place
+
+  Scenario: The expanded card offers the Q&A dock
+    Given chat is enabled
+    When a summarized card is expanded
+    Then the expanded card includes the deeper-dive chat affordance for that video
+
+  Scenario: Only a summarized card offers expand
+    Given a discovered but not-yet-summarized card
+    When the card is rendered
+    Then it shows its summarize/queue footer and no expand affordance
+
+  Scenario: With JS off the card still reaches the full summary
+    Given a summarized card
+    When it is rendered
+    Then its expand affordance carries an href to the detail page as a no-JS fallback
+
+  Scenario: The detail page and the expanded card show the same summary
+    Given a summarized video
+    When I view it on the detail page and as an expanded card
+    Then both render the same summary body (one shared fragment, no drift)

docs/use-cases/landing_page.feature

@@ -19,6 +19,9 @@ Feature: Public landing page
     Then I see a link to my summaries
     And I see a way to log out
 
+  @pending
+  # Behaviour ships (logout redirects to /welcome) but is not unit-tested: logout lives in
+  # the OIDC Auth impl and StubAuth has no routes to exercise it cheaply.
   Scenario: Logging out returns to the welcome page
     Given I am logged in
     When I log out

docs/use-cases/observability.feature

@@ -0,0 +1,46 @@
+Feature: Observability — timing and metrics for performance and UX (ADR-030, #15)
+  As the maintainer running Tapir for pilot users
+  I want timing and Prometheus metrics for the activities that drive performance and UX
+  So that I can see latency, model behaviour, and usage — and feed the Stage-0 eval gate
+
+  # AI metrics are the priority (ADR-030 R3). Each scenario maps to a Go test in
+  # test/acceptance/scenario_coverage_test.go (the BDD name-coverage gate).
+
+  Scenario: Summarization latency is recorded per endpoint
+    Given the summarizer runs a transcript through its endpoint chain
+    When an endpoint returns a parseable summary
+    Then the summarize latency is recorded with the model, outcome "success", and whether it was a fallback
+
+  Scenario: A failing summarizer endpoint records its failure outcome
+    Given the summarizer runs a transcript through its endpoint chain
+    When an endpoint errors or returns unparseable output
+    Then the summarize latency is recorded with outcome "error" or "parse_error" before the chain advances
+
+  Scenario: Caption fetch latency is recorded by outcome
+    Given a caption fetch is attempted for a video
+    When it resolves to captions, no captions, or a rate limit
+    Then the caption-fetch latency is recorded labelled by that outcome
+
+  Scenario: LLM token usage is recorded from the completion
+    Given an LLM completion returns a usage block with prompt and completion tokens
+    When the client finishes the call
+    Then the prompt and completion tokens are recorded for that model
+
+  Scenario: Q&A answer latency is recorded
+    Given a user asks a question about a video
+    When the answer is produced from the stored transcript
+    Then the chat answer latency is recorded for the answering model
+
+  Scenario: HTTP requests are counted by route, method, and status
+    Given the metrics HTTP middleware wraps the app
+    When a request is served against a registered route
+    Then it is counted and timed under the bounded route pattern, not the raw path
+
+  Scenario: A successful login is counted
+    Given a user completes the OIDC callback and a session is established
+    Then the login counter is incremented
+
+  Scenario: The metrics endpoint is not on the public app port
+    Given the service is running
+    When the public app mux is inspected
+    Then it exposes no /metrics route — metrics are served on the dedicated metrics port only

docs/use-cases/paste_url.feature

@@ -0,0 +1,30 @@
+Feature: Paste a YouTube URL to summarize any video
+  As a user
+  I want to paste a YouTube link and get a summary
+  So that I can pull the specific video I want now, even from channels I don't follow
+
+  Scenario: Paste a valid YouTube URL
+    Given I am connected
+    When I paste a valid YouTube video URL
+    Then the video is added to my feed scoped to me
+    And it is queued for summarization through the shared rate gate
+
+  Scenario: Pasting an invalid link is rejected
+    When I paste something that is not a YouTube video URL
+    Then I get a clear error and nothing is added
+
+  Scenario: Pasting a video that cannot be found is honest
+    When I paste a URL whose video cannot be found
+    Then I am told it couldn't be found and nothing is added
+
+  Scenario: Pasting the same video twice does not duplicate it
+    Given I have pasted a video
+    When I paste the same video again
+    Then my feed still has exactly one entry for it
+
+  @pending
+  # Covered by the engine's ADR-010 no-transcript terminal state (degrade-never-error);
+  # there is no paste-specific test for it.
+  Scenario: A pasted video with no captions resolves honestly
+    When I paste a video that has no captions
+    Then it resolves to the "no transcript available" terminal state

docs/use-cases/registration.feature

@@ -34,6 +34,9 @@ Feature: Register and manage a multi-user account
     And the other user's data remains intact
     And my Dex identity is left intact
 
+  @pending
+  # Re-registration after delete is supported by design (delete leaves the Dex identity,
+  # ADR-013) but has no dedicated end-to-end test yet.
   Scenario: A deleted user can register again as a fresh account
     Given I deleted my Tapir account but my Dex identity still exists
     When I sign in again

docs/use-cases/summarize_mode.feature

@@ -6,15 +6,25 @@ Feature: Choose how new videos get summarized
   Background:
     Given I am a registered user with a connected video account
 
-  Scenario: Auto mode summarizes every new video
+  Scenario: Auto mode summarizes recent new videos automatically
     Given my summarization mode is "auto"
-    When a subscribed channel posts a new video with captions
+    When a subscribed channel posts a new video with captions within the recency window
     Then Tapir summarizes it without my asking
     And the summary appears in my list
 
-  Scenario: Manual mode is the default and leaves new videos unsummarized
-    Given I have not changed my summarization mode
-    Then my mode is "manual"
+  Scenario: Auto mode lists older videos without summarizing them
+    Given my summarization mode is "auto"
+    When discovery finds a video published before the recency window
+    Then the video appears in my list with no summary
+    And it is not summarized automatically
+    And I can still summarize it on demand with "Summarize"
+
+  Scenario: Automatic is the default for a new user
+    Given I have just registered
+    Then my summarization mode is "auto"
+
+  Scenario: Manual mode leaves new videos unsummarized
+    Given my summarization mode is "manual"
     When a subscribed channel posts a new video with captions
     Then the video appears in my list with no summary
     And nothing is summarized until I request it
@@ -30,3 +40,8 @@ Feature: Choose how new videos get summarized
   # auto_summarize is a per-user setting and summarize_requested is a per-video queue
   # flag (migration 006). The web button sets the flag; `tapir run` processes both the
   # auto videos and the manually queued ones, then clears the flag.
+  #
+  # Recency bound (ADR-020): in auto mode the scheduler only summarizes videos published
+  # within TAPIR_AUTO_SUMMARIZE_WINDOW (default ~7d); older videos are discovered and
+  # listed but wait for an explicit "Summarize" — so a back-catalogue does not re-drive
+  # the per-IP caption gate (ADR-014) every cycle. A manual request bypasses the bound.

docs/use-cases/summarize_new_video.feature

@@ -31,5 +31,16 @@ Feature: Summarize new videos from subscribed channels
     When the watcher sees "Designing for Attention" again
     Then Tapir does not produce a second summary for it
 
+  Scenario: Re-analyzing a stored video does not re-fetch its transcript
+    Given a transcript for "Designing for Attention" is already stored
+    When the video is summarized again
+    Then Tapir reads the stored transcript
+    And Tapir does not fetch captions from YouTube
+
   # Captions-first is the core path (ADR-007). Audio-download + speech-to-text is
   # deferred and intentionally has no scenario here yet.
+  #
+  # Transcript persistence (ADR-021): the stored transcript is shared, keyed by
+  # (provider, provider_video_id) and read before any caption fetch, so the
+  # re-analysis scenario above also covers paste-a-URL and the onboarding burst —
+  # both summarize through the same engine chokepoint.

docs/use-cases/visual_theme.feature

@@ -0,0 +1,29 @@
+Feature: Visual refresh — one charm-reader layout, light + dark themes (ADR-032, #17)
+  As a reader who likes a TUI/charm aesthetic
+  I want a fresh look with a light and a dark theme
+  So that the app feels distinctive and reads well in either mode
+
+  # Direction B (light) + C (dark) are one layout in two palettes (CSS variables),
+  # plus a persisted toggle and an OS-preference default. Colours are reviewed via
+  # the mockups in docs/sketches/, not unit-tested; these scenarios cover the
+  # testable structure. Each maps to a Go test in scenario_coverage_test.go.
+
+  Scenario: Light and dark themes share one layout via CSS variables
+    Given the app stylesheet
+    When it is rendered
+    Then it defines a light palette on the root and a dark palette under data-theme="dark", with no duplicate markup
+
+  Scenario: Without a stored choice the theme follows the OS preference
+    Given a visitor with no saved theme
+    When the page loads
+    Then a prefers-color-scheme dark block applies the dark palette automatically
+
+  Scenario: A persisted toggle switches light and dark
+    Given any page
+    When it is rendered
+    Then it includes a theme-toggle control and a small script that flips data-theme and persists the choice
+
+  Scenario: The expanded card embeds the video player
+    Given a summarized video with a valid provider id
+    When its card is expanded
+    Then the expanded card includes the embedded video player

docs/ux-review/UX-REVIEW-stage0-recency.md

@@ -0,0 +1,207 @@
+# Tapir — Heuristic Review (Stage-0, sparse + recency-bounded)
+
+_Findings document, not a build spec. The maintainer filters; a spec follows separately.
+Reviewed against `VISION.md` (Stage-0 gate), `docs/ui-spec.md`, `internal/web/views.templ` +
+`view.go`, the prior `UX-REVIEW.md` pass, and the current screenshots. Written for the product
+**as it actually is**: ~283 discovered, ~15 summarized, ~256 in queue behind a respected per-IP
+caption rate limit, ~12 no-captions; single-user (maintainer) with friends pending; recency-
+bounded auto-summarize about to ship (auto = recent ~7d, older browsable + manual on demand)._
+
+## Reviewer stance
+
+The Stage-0 gate is **return usage**. So every finding is judged by one question: does this make
+the maintainer (or a friend) come back to an honestly-sparse feed? The visual layer is already
+decent — dark mode, cards, the constrained reader were all fixed in the prior pass. The open
+problems are **expectation-setting, honesty-of-scale, and the recency feed** — not pixels.
+
+**The single biggest risk:** a new user connects, sees `15 summarized · 256 fetching soon`,
+nothing visibly moves, and never returns. The whole gate dies at that moment. Most P0s below
+attack that one moment.
+
+## Tagging
+
+- **`[NOW]`** — improves the product as it is today (sparse, recency-bounded, single-user). Ships
+  in the upcoming bundle.
+- **`[LATER]`** — improves the product we hope it becomes (abundance, engagement, multiple users).
+  Valuable but premature until real usage validates the core loop.
+
+Severity: 🔴 breaks the core loop · 🟠 hurts it · 🟡 noticeable · 🔵 polish.
+
+---
+
+## P0 — fix before/with the recency ship
+
+### 1. 🔴 Empty-connected state tells the user to run a CLI command they can't run — `[NOW]`
+**Problem.** After connecting YouTube, the empty list says: *"Run `tapir run` to discover your
+subscriptions."* A friend on the web has no shell. And post-ADR-018 discovery is an in-process
+scheduled loop — so the instruction is wrong *even for the maintainer*. It is the first thing a
+newly-onboarded user sees, and it is an impossible, stale instruction.
+**Principle.** Match between system and the real world; help users recognize, not be blocked
+(Nielsen #1, #2, #9).
+**Proposal.** Replace with a passive, honest "we're working" state: *"Your account is connected.
+Tapir is finding your subscriptions and fetching captions — summaries appear here gradually. Check
+back later."* No command. No imperative the user can't satisfy.
+**Evidence.** `views.templ` `summaryList` → `.empty-connected`.
+
+### 2. 🔴 No expectation set for *gradual* fill — the return loop breaks at the cliff — `[NOW]`
+**Problem.** Captions are rate-limited by design; the backlog trickles over days. Nothing tells
+the user this. A first visit shows few/no summaries and no "come back" framing. The Stage-0 gate
+is literally about returns, and the product never asks for one or explains why patience is
+warranted.
+**Principle.** Visibility of system status (#1). And: the gate can't be cleared if the UX doesn't
+survive first contact.
+**Proposal.** One honest sentence near the pipeline bar / empty state: *"Tapir fetches captions
+slowly on purpose, to respect YouTube's limits. New summaries land gradually — usually best to
+check back tomorrow."* Turns confusing emptiness into intentional design. Highest-leverage change
+in the review.
+
+### 3. 🟠 "256 fetching soon" overstates imminence — a lie of scale — `[NOW]`
+**Problem.** The pipeline bar and rate-limited cards both say "fetching soon." For 256 items
+behind a per-IP throttle, "soon" is false — they trickle over days/weeks. Exactly the abundance-
+implying language the mandate forbids, inverted: it makes the *queue* look imminent.
+**Principle.** Honesty of scarcity (project mandate); #1.
+**Proposal.** Relabel by scale. Bar: `15 ready · 256 in queue · 12 no captions`. Card state:
+"In queue" / "Waiting its turn", not "Fetching soon…". Reserve "soon" for items actually next.
+**Evidence.** `views.templ` `pipelineBar`; card State 4.
+
+### 4. 🟠 Recency boundary is invisible in the feed — `[NOW, ships with recency]`
+**Problem.** Once auto-summarize is bounded to ~7d, a 6-month-old pending video and a 2-day-old
+pending video render identically ("Not summarized" + button). But only one is in the auto path;
+the other will *never* process unless clicked. The user can't tell "be patient, this is coming"
+from "this is yours to trigger or ignore."
+**Principle.** Visibility of system status; predictability (#1).
+**Proposal.** Bucket the list into two sections: **Recent** (auto, will fill itself) and
+**Older — browse / summarize on demand**. Card status language should encode *which side of the
+line it's on*, not the pipeline internals. Central IA decision of the recency change.
+
+### 5. 🟠 The un-summarized mass buries the ~15 readable summaries — `[NOW]`
+**Problem.** ~268 of 283 cards are not readable (pending / queued / no-captions). Summarized-first
+ordering helps, but the page is still 95% noise below the fold. "Attention is the scarce resource"
+is the product's own principle — and the default view violates it.
+**Principle.** Aesthetic/minimalist design; signal-to-noise (#8).
+**Proposal.** Default view = readable summaries + the Recent bucket. Collapse the older
+un-summarized mass behind *"Show 256 older un-summarized videos."* Collapse the 12 no-caption
+videos into a single line: *"12 videos have no captions"* (terminal, never readable — they don't
+deserve 12 full cards).
+
+---
+
+## P1 — high, near-term
+
+### 6. 🟠 "Summarize now" overpromises against the rate gate — `[NOW]`
+**Problem.** Button says "Summarize now" (title: "Summarize this one now"). Backend queues it
+behind the shared per-IP gate. Click 10 older videos and they all sit at "Fetching soon…". The
+verb sells immediacy the system can't honor.
+**Principle.** Honesty; match system/reality (#1).
+**Proposal.** Drop "now" → "Summarize". On click the card should honestly become "Queued" (it
+already can). Optionally show queue position once the queue is real. Don't engineer the gate
+harder — just stop the verb from lying.
+**Evidence.** `views.templ` card States 4 & 5; `handlers.go` `handleRetryNow`,
+`handleRequestSummarize`.
+
+### 7. 🟠 Welcome-page copy is stale and misleading post-ADR-019 — `[NOW]`
+**Problem.** Landing sub-copy: *"If you have an invite link, it will set up your account
+automatically."* Invites moved to Authentik (ADR-019); Tapir no longer handles invite links. The
+"Get Started" button goes straight to OIDC. The copy promises a flow that no longer exists.
+**Principle.** Match between system and reality (#2); honesty.
+**Proposal.** Rewrite: *"Tapir is invite-only right now. If you've been invited, sign in below."*
+Single CTA. Also set the gradual-fill expectation here (ties to #2) so it lands before the wall,
+not after.
+**Evidence.** `views.templ` `WelcomePage` → `.welcome-sub`.
+
+### 8. 🟡 "Queued · waiting for the next run" leaks system jargon — `[NOW]`
+**Problem.** "the next run" exposes the discovery-loop concept; a user doesn't know what a "run"
+is.
+**Principle.** Speak the user's language (#2).
+**Proposal.** "Queued — summarizing shortly." Hide the scheduler.
+**Evidence.** `views.templ` card State 3.
+
+### 9. 🟡 Filters render before there's anything to filter — `[NOW]`
+**Problem.** The fresh/empty state shows the full Channel/From/To/Filter bar *above* "Connect
+YouTube." Power tooling stacked on top of the one action that matters.
+**Principle.** Progressive disclosure; minimalist design (#8).
+**Proposal.** Hide the filter bar when there are 0 rows (and arguably below ~20). Show the connect
+CTA alone.
+**Evidence.** `fixes/03-empty-fresh.png`; `ListPage` renders `filterForm` unconditionally.
+
+### 10. 🟡 Date-range filters are dead weight at this scale — `[NOW]` demote / `[LATER]` rebuild
+**Problem.** From/To date pickers + a free-text exact-match Channel field are corpus-scale tools.
+With 15 summaries they're noise; channel-as-freetext is unguessable. (Confirm the prior review's
+#7 is resolved — that `Channel` shows a real channel name, not the `provider` string; seeded
+screenshots suggest it is, live data may differ.)
+**Principle.** Match tool to task; minimalist design.
+**Proposal.** `[NOW]`: reduce to the "Summarized only" toggle (+ maybe channel chips derived from
+present rows). Drop date pickers until the corpus justifies them. `[LATER]`: real channel facets +
+search when there's volume.
+
+---
+
+## P2 — reading experience & polish
+
+### 11. 🟡 Detail leads with Summary; the attention-saving payload (Takeaways) is last — `[NOW]`
+**Problem.** Product promise is "decide what's worth your time." The element that answers that —
+Takeaways / verdict — sits at the bottom. The user reads a full summary to reach the point.
+**Principle.** Lead with the user's actual job-to-be-done.
+**Proposal.** Reorder or add a one-line TL;DR/verdict at top. Takeaways → Highlights → Summary, or
+a "Worth watching?" lede. Data already exists; a reorder, not new machinery.
+**Evidence.** `views.templ` `DetailPage`.
+
+### 12. 🔵 No "back to Summaries" on detail — `[NOW]`
+**Problem.** Only the brand returns home, losing any filter context.
+**Proposal.** Explicit "← Summaries" link on the detail page.
+
+### 13. 🔵 Auto/manual toggle copy will be wrong after recency — `[NOW, with recency]`
+**Problem.** Account copy: *"Automatic summarizes every new video as it is discovered."* Becomes
+false once auto is bounded to ~7d.
+**Proposal.** *"Automatic summarizes new videos from the last ~7 days. Older videos stay
+browsable — summarize them on demand."*
+**Evidence.** `views.templ` `AccountPage` summarization section.
+
+### 14. 🔵 Register step asks acceptance of nonexistent terms — `[NOW]`
+**Problem.** "I accept the terms of use" — no terms linked. For a friends-only tool, ceremony
+accepting nothing.
+**Proposal.** Either link real terms or drop the checkbox at this stage.
+**Evidence.** `views.templ` `RegisterPage`.
+
+### 15. 🔵 watched/skipped mutual exclusivity unsignaled — `[NOW]` low
+**Problem.** Three independent-looking buttons; watched↔skipped are exclusive (carryover from
+prior review #14).
+**Proposal.** Segmented control for watched/skipped; keep Saved separate.
+
+---
+
+## `[LATER]` — premature until the core loop is validated
+
+_(abundance / engagement / multiple users)_
+
+- **Return-nudges (digest email / push).** 🔴 **Caution, not just defer.** A notification that
+  drives returns *contaminates the exact signal the gate measures* — VISION wants *unprompted*
+  returns and admits it can't distinguish prompted from organic. Building a nudge now poisons the
+  experiment. Defer until after the gate reads. `[LATER]`
+- **Full-text search across summaries** — needs volume to matter. `[LATER]`
+- **Channel facets / saved filters / sorting** — corpus-scale tooling (#10). `[LATER]`
+- **Read/unread + "new since last visit"** — genuinely helps returns, but only meaningful once
+  there is throughput to be "new." `[LATER]`
+- **Saved/queue view, collections** — engagement surface; no payoff at 15 items. `[LATER]`
+- **Richer card previews (top-takeaway as preview, 2–3 lines)** — triage aid that only pays off
+  with many cards to triage. `[LATER]`
+- **Backlog progress heartbeat ("N summarized this week", queue burn-down)** — rewards returning,
+  but needs real throughput to show motion; a static "last updated X ago" is the only `[NOW]`-worthy
+  slice. `[LATER]`
+- **Onboarding tour / multi-step welcome** — over-built for one user + a few friends. `[LATER]`
+
+---
+
+## What's already right (don't regress)
+
+Pipeline-bar concept, the honest "No transcript available" terminal state, the queued/waiting
+spinner instead of a fake-imminent one, the Unavailable-channels surface, the constrained-width
+reader, dark mode, the account danger-zone behind a disclosure. The honesty instincts are present
+— the P0s are about making that honesty *legible and correctly-scaled*, not adding it.
+
+## Two judgment calls to settle first
+
+1. **#4 (Recent/Older split) and #5 (collapse the older mass) are one decision viewed twice.**
+   Settle the recency-feed IA once and both fall out.
+2. **The return-nudge caution (`[LATER]` list, item 1) is the one to put in writing now** — before
+   someone "helpfully" ships an email digest to juice the gate and destroys the signal.

go.mod

@@ -1,4 +1,4 @@
-module gitea.d-ma.be/mathias/tapir
+module git.d-ma.be/mathias/tapir
 
 go 1.26.1
 
@@ -9,22 +9,33 @@ require (
 	github.com/go-jose/go-jose/v4 v4.1.4
 	github.com/golang-migrate/migrate/v4 v4.19.1
 	github.com/jackc/pgx/v5 v5.9.2
+	github.com/prometheus/client_golang v1.23.2
+	github.com/prometheus/client_model v0.6.2
 	github.com/stretchr/testify v1.11.1
-	golang.org/x/crypto v0.45.0
 	golang.org/x/oauth2 v0.36.0
+	golang.org/x/time v0.15.0
 )
 
 require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/jackc/pgerrcode v0.0.0-20220416144525-469b46aa5efa // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/kylelemons/godebug v1.1.0 // indirect
 	github.com/lib/pq v1.10.9 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/prometheus/common v0.66.1 // indirect
+	github.com/prometheus/procfs v0.16.1 // indirect
 	github.com/rogpeppe/go-internal v1.15.0 // indirect
 	github.com/xi2/xz v0.0.0-20171230120015-48954b6210f8 // indirect
+	go.yaml.in/yaml/v2 v2.4.2 // indirect
 	golang.org/x/sync v0.18.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
 	golang.org/x/text v0.31.0 // indirect
+	google.golang.org/protobuf v1.36.8 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -4,6 +4,10 @@ github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERo
 github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/a-h/templ v0.3.1020 h1:ypAT/L5ySWEnZ6Zft/5yfoWXYYkhFNvEFOeeqecg4tw=
 github.com/a-h/templ v0.3.1020/go.mod h1:A2DlK61v+K+NRoGnhmYbNYVmtYHcFO5/AisMvBdDxTM=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI=
 github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M=
 github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE=
@@ -37,8 +41,8 @@ github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
 github.com/golang-migrate/migrate/v4 v4.19.1 h1:OCyb44lFuQfYXYLx1SCxPZQGU7mcaZ7gH9yH4jSFbBA=
 github.com/golang-migrate/migrate/v4 v4.19.1/go.mod h1:CTcgfjxhaUtsLipnLoQRWCrjYXycRz/g5+RWDuYgPrE=
-github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/jackc/pgerrcode v0.0.0-20220416144525-469b46aa5efa h1:s+4MhCQ6YrzisK6hFJUX53drDT4UsSW3DEhKn0ifuHw=
 github.com/jackc/pgerrcode v0.0.0-20220416144525-469b46aa5efa/go.mod h1:a/s9Lp5W7n/DD0VrVoyJ00FbP2ytTPDVOivvn2bMlds=
 github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
@@ -49,10 +53,14 @@ github.com/jackc/pgx/v5 v5.9.2 h1:3ZhOzMWnR4yJ+RW1XImIPsD1aNSz4T4fyP7zlQb56hw=
 github.com/jackc/pgx/v5 v5.9.2/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
-github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
-github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
+github.com/klauspost/compress v1.18.0/go.mod h1:2Pp+KzxcywXVXMr50+X0Q/Lsb43OQHYWRCY2AiWywWQ=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw=
 github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
@@ -61,6 +69,8 @@ github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
 github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
 github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
 github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
 github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
 github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
 github.com/opencontainers/image-spec v1.1.0 h1:8SG7/vwALn54lVB/0yZ/MMwhFrPYtpEHQb2IpWsCzug=
@@ -70,6 +80,14 @@ github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINE
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
 github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
+github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
+github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
+github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/prometheus/common v0.66.1 h1:h5E0h5/Y8niHc5DlaLlWLArTQI7tMrsfQjHV+d9ZoGs=
+github.com/prometheus/common v0.66.1/go.mod h1:gcaUsgf3KfRSwHY4dIMXLPV0K/Wg1oZ8+SbZk/HH/dA=
+github.com/prometheus/procfs v0.16.1 h1:hZ15bTNuirocR6u0JZ6BAHHmwS1p8B4P6MRqxtzMyRg=
+github.com/prometheus/procfs v0.16.1/go.mod h1:teAbpZRB1iIAJYREa1LsoWUXykVXA1KlTmWl8x/U+Is=
 github.com/rogpeppe/go-internal v1.15.0 h1:D0RCU5rMAp+SpgkiNdrjfJ+LX4J1M32V2NeCY7EJ6hc=
 github.com/rogpeppe/go-internal v1.15.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
@@ -91,8 +109,8 @@ go.opentelemetry.io/otel/trace v1.37.0 h1:HLdcFNbRQBE2imdSEgm/kwqmQj1Or1l/7bW6mx
 go.opentelemetry.io/otel/trace v1.37.0/go.mod h1:TlgrlQ+PtQO5XFerSPUYG0JSgGyryXewPGyayAWSBS0=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
-golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=
-golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
+go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
+go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
 golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
@@ -101,6 +119,10 @@ golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
 golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
 golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
 golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
+google.golang.org/protobuf v1.36.8 h1:xHScyCOEuuwZEc6UtSOvPbAT4zRh0xcNRYekJwfqyMc=
+google.golang.org/protobuf v1.36.8/go.mod h1:fuxRtAxBytpl4zzqUh6/eyUujkJdNiuEkXntxiD/uRU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

internal/adapters/chat/chat.go

@@ -0,0 +1,179 @@
+// Package chat implements the per-video deeper-dive chat (ADR-027): a read-only
+// QA over a video's ALREADY-STORED transcript (ADR-021). It is the enforcement
+// point for the feature's load-bearing safety property — stored-transcript-only:
+// the Service has NO VideoSource and NO caption-fetch dependency, only a
+// Completer factory, so it CANNOT reach YouTube or the rate gate by construction.
+// The caller supplies the stored transcript text; chat never fetches.
+//
+// It reuses the same LiteLLM gateway as the summarizer (a chat is a different
+// call, not a new integration) and the same transcript-truncation discipline
+// (TAPIR_MAX_TRANSCRIPT_CHARS) so a long transcript fits a small-context model.
+package chat
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"git.d-ma.be/mathias/tapir/internal/metrics"
+)
+
+// Completer is the minimal LLM chat surface the Service needs. *llm.Client
+// satisfies it; tests use a fake. It is the SAME surface the summarizer uses.
+type Completer interface {
+	Complete(ctx context.Context, system, user string) (string, error)
+}
+
+// Turn is one completed exchange in an ephemeral, session-only conversation
+// (ADR-027 v1: nothing is persisted).
+type Turn struct {
+	Question string
+	Answer   string
+}
+
+// Request is one chat turn: the chosen model, the stored transcript text, the
+// prior turns (for multi-turn context within the session), and the new question.
+type Request struct {
+	Model      string
+	Transcript string
+	History    []Turn
+	Question   string
+}
+
+// Reply is the model's answer plus whether the transcript was bounded to fit the
+// model context (so the UI can be honest that an answer about the tail of a long
+// video may be incomplete).
+type Reply struct {
+	Answer    string
+	Truncated bool
+}
+
+// Service answers questions against a stored transcript via a switchable set of
+// models. models is the ordered, local-first list offered to the user (the cloud
+// model is simply absent when disabled — see cmd wiring); maxChars bounds the
+// transcript sent to any model (0 = unbounded). newClient builds a Completer for
+// a chosen model alias (the same gateway, a different alias).
+type Service struct {
+	newClient func(model string) Completer
+	models    []string
+	maxChars  int
+}
+
+// New constructs a Service. models must be non-empty and already filtered to the
+// offerable set (cloud excluded when disabled) and de-duplicated by the caller.
+func New(newClient func(model string) Completer, models []string, maxChars int) *Service {
+	return &Service{newClient: newClient, models: models, maxChars: maxChars}
+}
+
+// Models returns a copy of the offerable model list (local-first order).
+func (s *Service) Models() []string {
+	out := make([]string, len(s.models))
+	copy(out, s.models)
+	return out
+}
+
+// offers reports whether model is in the offerable set — the guard that keeps an
+// arbitrary, un-offered alias (e.g. a forged form value) from reaching the gateway.
+func (s *Service) offers(model string) bool {
+	for _, m := range s.models {
+		if m == model {
+			return true
+		}
+	}
+	return false
+}
+
+// DefaultModel resolves the model a fresh chat opens with: the summary's own
+// model when it is still an offered option (the ADR-027 default — chat continues
+// in the model that produced the summary), otherwise the first offered model.
+// Returns "" only when no models are configured.
+func (s *Service) DefaultModel(summaryModel string) string {
+	if summaryModel != "" && s.offers(summaryModel) {
+		return summaryModel
+	}
+	if len(s.models) > 0 {
+		return s.models[0]
+	}
+	return ""
+}
+
+// Answer runs one chat turn. The model is forced back to a default if the request
+// names an un-offered alias, so chat can never call the gateway with an arbitrary
+// model. The transcript is truncated up front (reporting whether it was cut) and
+// passed as system context; the running conversation is the user message.
+func (s *Service) Answer(ctx context.Context, req Request) (Reply, error) {
+	if len(s.models) == 0 {
+		return Reply{}, fmt.Errorf("chat: no models configured")
+	}
+	model := req.Model
+	if !s.offers(model) {
+		model = s.DefaultModel("")
+	}
+
+	transcript, truncated := truncate(req.Transcript, s.maxChars)
+	system := buildSystem(transcript, truncated)
+	user := buildUser(req.History, req.Question)
+
+	start := time.Now()
+	out, err := s.newClient(model).Complete(ctx, system, user)
+	if err != nil {
+		return Reply{}, fmt.Errorf("chat: %s: %w", model, err)
+	}
+	dur := time.Since(start)
+	metrics.ObserveChat(model, dur)
+	slog.Default().Info("chat answer", "model", model, "elapsed_ms", dur.Milliseconds())
+	answer := strings.TrimSpace(out)
+	if answer == "" {
+		return Reply{}, fmt.Errorf("chat: %s returned an empty answer", model)
+	}
+	return Reply{Answer: answer, Truncated: truncated}, nil
+}
+
+const systemPreamble = `You are Tapir, answering questions about ONE video using ONLY the transcript below.
+Ground every answer in the transcript. If the transcript does not contain the answer, say so plainly rather than guessing.`
+
+const truncatedNote = `
+The transcript below is truncated to fit the model — if a question seems to concern something missing, note it may be beyond the available portion.`
+
+// buildSystem frames the model as a transcript-grounded QA assistant and embeds
+// the (possibly truncated) transcript as context.
+func buildSystem(transcript string, truncated bool) string {
+	var b strings.Builder
+	b.WriteString(systemPreamble)
+	if truncated {
+		b.WriteString(truncatedNote)
+	}
+	b.WriteString("\n\nTranscript:\n")
+	b.WriteString(transcript)
+	return b.String()
+}
+
+// buildUser renders the running conversation as the user message: prior turns as
+// Q/A pairs followed by the new question. Folding history into one message keeps
+// the Completer surface (a single system+user call) unchanged — no new llm method.
+func buildUser(history []Turn, question string) string {
+	var b strings.Builder
+	for _, t := range history {
+		fmt.Fprintf(&b, "Q: %s\nA: %s\n\n", t.Question, t.Answer)
+	}
+	fmt.Fprintf(&b, "Q: %s", question)
+	return b.String()
+}
+
+// truncate caps content to max bytes on a UTF-8 rune boundary, reporting whether
+// it cut. It mirrors the summarizer's truncation discipline (ADR-022) but returns
+// the cut flag so the chat UI can be honest about a bounded transcript. A
+// non-positive max (or content already within budget) returns content unchanged.
+func truncate(content string, max int) (string, bool) {
+	if max <= 0 || len(content) <= max {
+		return content, false
+	}
+	cut := max
+	for cut > 0 && !utf8.RuneStart(content[cut]) {
+		cut--
+	}
+	return content[:cut], true
+}

internal/adapters/chat/chat_test.go

@@ -0,0 +1,164 @@
+package chat
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// recordingCompleter captures the system+user it was asked with and returns a
+// canned answer (or error). It also records which model alias built it.
+type recordingCompleter struct {
+	model      string
+	lastSystem string
+	lastUser   string
+	answer     string
+	err        error
+	calls      *int
+}
+
+func (c *recordingCompleter) Complete(_ context.Context, system, user string) (string, error) {
+	*c.calls++
+	c.lastSystem = system
+	c.lastUser = user
+	if c.err != nil {
+		return "", c.err
+	}
+	return c.answer, nil
+}
+
+// factory builds a recordingCompleter per model and records the last one built so
+// the test can assert which model alias was actually used for the gateway call.
+type factory struct {
+	answer string
+	err    error
+	calls  int
+	used   *recordingCompleter
+}
+
+func (f *factory) make(model string) Completer {
+	c := &recordingCompleter{model: model, answer: f.answer, err: f.err, calls: &f.calls}
+	f.used = c
+	return c
+}
+
+func TestModelsAreOfferedLocalFirstAndCopied(t *testing.T) {
+	f := &factory{answer: "ok"}
+	s := New(f.make, []string{"koala/phi4-mini", "iguana/gemma4-26b"}, 0)
+
+	got := s.Models()
+	want := []string{"koala/phi4-mini", "iguana/gemma4-26b"}
+	if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+		t.Fatalf("Models() = %v, want %v", got, want)
+	}
+	// Mutating the returned slice must not corrupt the Service's list.
+	got[0] = "tampered"
+	if s.Models()[0] != "koala/phi4-mini" {
+		t.Fatal("Models() leaked its backing slice")
+	}
+}
+
+func TestDefaultModelIsTheSummarysModelWhenOffered(t *testing.T) {
+	f := &factory{answer: "ok"}
+	s := New(f.make, []string{"koala/phi4-mini", "iguana/gemma4-26b", "berget/mistral-small"}, 0)
+
+	if got := s.DefaultModel("iguana/gemma4-26b"); got != "iguana/gemma4-26b" {
+		t.Fatalf("DefaultModel(summary) = %q, want the summary's model", got)
+	}
+	// A summary model no longer offered (e.g. cloud disabled) falls back to first.
+	if got := s.DefaultModel("berget/old-model"); got != "koala/phi4-mini" {
+		t.Fatalf("DefaultModel(un-offered) = %q, want the first offered model", got)
+	}
+	// No summary model recorded → first offered.
+	if got := s.DefaultModel(""); got != "koala/phi4-mini" {
+		t.Fatalf("DefaultModel(\"\") = %q, want the first offered model", got)
+	}
+}
+
+func TestAnswerGroundsOnTranscriptAndCarriesHistory(t *testing.T) {
+	f := &factory{answer: "  The video is about attention.  "}
+	s := New(f.make, []string{"koala/phi4-mini"}, 0)
+
+	reply, err := s.Answer(context.Background(), Request{
+		Model:      "koala/phi4-mini",
+		Transcript: "ATTENTION-TRANSCRIPT-MARKER",
+		History:    []Turn{{Question: "who", Answer: "the host"}},
+		Question:   "what is it about",
+	})
+	if err != nil {
+		t.Fatalf("Answer: %v", err)
+	}
+	if reply.Answer != "The video is about attention." {
+		t.Fatalf("answer not trimmed: %q", reply.Answer)
+	}
+	if reply.Truncated {
+		t.Fatal("short transcript must not report truncated")
+	}
+	// The transcript rides in the system prompt; the conversation in the user msg.
+	if !strings.Contains(f.used.lastSystem, "ATTENTION-TRANSCRIPT-MARKER") {
+		t.Fatal("transcript not grounded into the system prompt")
+	}
+	if !strings.Contains(f.used.lastUser, "Q: who") || !strings.Contains(f.used.lastUser, "A: the host") {
+		t.Fatalf("history not carried into the user message: %q", f.used.lastUser)
+	}
+	if !strings.Contains(f.used.lastUser, "what is it about") {
+		t.Fatal("new question missing from the user message")
+	}
+}
+
+func TestAnswerTruncatesLongTranscriptAndReportsIt(t *testing.T) {
+	f := &factory{answer: "answer"}
+	s := New(f.make, []string{"koala/phi4-mini"}, 10)
+
+	reply, err := s.Answer(context.Background(), Request{
+		Model:      "koala/phi4-mini",
+		Transcript: strings.Repeat("x", 500),
+		Question:   "summarize",
+	})
+	if err != nil {
+		t.Fatalf("Answer: %v", err)
+	}
+	if !reply.Truncated {
+		t.Fatal("a transcript past maxChars must report Truncated")
+	}
+	if strings.Count(f.used.lastSystem, "x") != 10 {
+		t.Fatalf("transcript not bounded to maxChars: got %d x's", strings.Count(f.used.lastSystem, "x"))
+	}
+}
+
+func TestAnswerForcesAnUnofferedModelBackToDefault(t *testing.T) {
+	f := &factory{answer: "answer"}
+	s := New(f.make, []string{"koala/phi4-mini", "iguana/gemma4-26b"}, 0)
+
+	// A forged/un-offered model must never reach the gateway as-is — it is forced
+	// to the default offered model (the cloud-absent guarantee depends on this).
+	_, err := s.Answer(context.Background(), Request{
+		Model:      "berget/secret-cloud-model",
+		Transcript: "t",
+		Question:   "q",
+	})
+	if err != nil {
+		t.Fatalf("Answer: %v", err)
+	}
+	if f.used.model != "koala/phi4-mini" {
+		t.Fatalf("un-offered model reached the gateway as %q, want the default", f.used.model)
+	}
+}
+
+func TestAnswerPropagatesCompleterError(t *testing.T) {
+	f := &factory{err: errors.New("gateway down")}
+	s := New(f.make, []string{"koala/phi4-mini"}, 0)
+
+	_, err := s.Answer(context.Background(), Request{Model: "koala/phi4-mini", Transcript: "t", Question: "q"})
+	if err == nil {
+		t.Fatal("expected the gateway error to propagate")
+	}
+}
+
+func TestAnswerRejectsEmptyModelSet(t *testing.T) {
+	s := New(func(string) Completer { return nil }, nil, 0)
+	if _, err := s.Answer(context.Background(), Request{Question: "q"}); err == nil {
+		t.Fatal("expected an error when no models are configured")
+	}
+}

internal/adapters/dex/dex.go

@@ -1,180 +0,0 @@
-// Package dex creates Dex local-password accounts by writing
-// passwords.dex.coreos.com custom resources directly against the in-cluster
-// Kubernetes API. This is the write side of the invite flow: a recipient sets a
-// password on /invite/{token}, Tapir bcrypt-hashes it and POSTs a Password CR into
-// the auth namespace, and Dex (configured with kubernetes storage) then serves
-// local-password login for that email.
-//
-// Why the raw API and not kubectl/client-go: the deployed pod already carries a
-// service-account token and the cluster CA at the well-known mount paths, so a
-// single net/http POST needs no extra dependency and no shelling out. Standalone /
-// dev has no such mount — NewPasswordClient returns ErrNotInCluster and the web
-// handler degrades gracefully (account creation only works in the deployed env).
-package dex
-
-import (
-	"bytes"
-	"context"
-	"crypto/tls"
-	"crypto/x509"
-	"encoding/base64"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"net/http"
-	"os"
-	"regexp"
-	"strings"
-	"time"
-)
-
-// Sentinel errors let the web handler turn API outcomes into clear user messages.
-var (
-	// ErrNotInCluster means the service-account token mount is absent, so there is
-	// no in-cluster API to talk to (local dev / tests). Construction-time only.
-	ErrNotInCluster = errors.New("dex: not running in-cluster (no service-account token)")
-	// ErrPasswordExists maps the API's 409 Conflict — a Password CR for this email
-	// already exists. The handler treats it as a benign "log in instead".
-	ErrPasswordExists = errors.New("dex: password already exists")
-	// ErrForbidden maps 401/403 — the tapir ServiceAccount lacks create/get on
-	// passwords.dex.coreos.com in the auth namespace (RBAC not applied).
-	ErrForbidden = errors.New("dex: forbidden — missing RBAC for passwords.dex.coreos.com")
-)
-
-// Well-known in-cluster service-account mount paths (projected by kubelet).
-const (
-	saTokenPath = "/var/run/secrets/kubernetes.io/serviceaccount/token" //nolint:gosec // path, not a secret
-	saCAPath    = "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"
-	// apiServer is the in-cluster API endpoint; its TLS is validated against the
-	// mounted cluster CA.
-	apiServer = "https://kubernetes.default.svc"
-	// passwordsPath is the Dex Password collection in the auth namespace.
-	passwordsPath = "/apis/dex.coreos.com/v1/namespaces/auth/passwords"
-)
-
-// PasswordClient writes Dex Password CRs against the in-cluster API. Construct it
-// with NewPasswordClient; the zero value is not usable.
-type PasswordClient struct {
-	server string
-	token  string
-	http   *http.Client
-}
-
-// NewPasswordClient reads the service-account token and cluster CA from the
-// well-known mount paths and returns a client that authenticates as the pod's
-// ServiceAccount. It returns ErrNotInCluster when the token mount is absent (dev /
-// tests / standalone), so callers can detect "no Dex available" and degrade.
-func NewPasswordClient() (*PasswordClient, error) {
-	token, err := os.ReadFile(saTokenPath)
-	if errors.Is(err, os.ErrNotExist) {
-		return nil, ErrNotInCluster
-	}
-	if err != nil {
-		return nil, fmt.Errorf("dex: read service-account token: %w", err)
-	}
-
-	caPEM, err := os.ReadFile(saCAPath)
-	if err != nil {
-		return nil, fmt.Errorf("dex: read cluster CA: %w", err)
-	}
-	pool := x509.NewCertPool()
-	if !pool.AppendCertsFromPEM(caPEM) {
-		return nil, errors.New("dex: cluster CA is not valid PEM")
-	}
-
-	hc := &http.Client{
-		Timeout: 10 * time.Second,
-		Transport: &http.Transport{
-			TLSClientConfig: &tls.Config{RootCAs: pool, MinVersion: tls.VersionTLS12},
-		},
-	}
-	return newClient(apiServer, strings.TrimSpace(string(token)), hc), nil
-}
-
-// newClient is the injectable constructor shared by NewPasswordClient and tests
-// (which point server at an httptest.Server and pass its TLS client).
-func newClient(server, token string, hc *http.Client) *PasswordClient {
-	return &PasswordClient{server: server, token: token, http: hc}
-}
-
-// password is the wire form of a Dex Password CR. NOTE: Dex's kubernetes storage
-// types the hash as []byte, which Kubernetes JSON-marshals as base64. So the
-// `hash` field must carry the base64 encoding of the bcrypt string, NOT the raw
-// bcrypt string — store the raw string and Dex's base64-decode on login yields
-// garbage and every login fails. CreatePassword does that encoding.
-type password struct {
-	APIVersion string            `json:"apiVersion"`
-	Kind       string            `json:"kind"`
-	Metadata   map[string]string `json:"metadata"`
-	Email      string            `json:"email"`
-	Hash       string            `json:"hash"`
-	Username   string            `json:"username"`
-	UserID     string            `json:"userID"`
-}
-
-// CreatePassword creates a Dex local-password account for email with the given
-// bcrypt hash and Dex user id. The CR name is derived from the email so it is a
-// valid, stable, idempotent Kubernetes object name. Returns ErrPasswordExists on
-// 409 (the account already exists) and ErrForbidden on 401/403 (RBAC missing).
-func (c *PasswordClient) CreatePassword(ctx context.Context, email, bcryptHash, userID string) error {
-	body, err := json.Marshal(password{
-		APIVersion: "dex.coreos.com/v1",
-		Kind:       "Password",
-		Metadata:   map[string]string{"name": passwordName(email), "namespace": "auth"},
-		Email:      email,
-		// base64 of the bcrypt string — see the password type's NOTE.
-		Hash:     base64.StdEncoding.EncodeToString([]byte(bcryptHash)),
-		Username: email,
-		UserID:   userID,
-	})
-	if err != nil {
-		return fmt.Errorf("dex: marshal password: %w", err)
-	}
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.server+passwordsPath, bytes.NewReader(body))
-	if err != nil {
-		return fmt.Errorf("dex: build request: %w", err)
-	}
-	req.Header.Set("Authorization", "Bearer "+c.token)
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("Accept", "application/json")
-
-	resp, err := c.http.Do(req)
-	if err != nil {
-		return fmt.Errorf("dex: create password: %w", err)
-	}
-	defer func() { _ = resp.Body.Close() }()
-
-	switch resp.StatusCode {
-	case http.StatusCreated, http.StatusOK:
-		return nil
-	case http.StatusConflict:
-		return ErrPasswordExists
-	case http.StatusUnauthorized, http.StatusForbidden:
-		return ErrForbidden
-	default:
-		snippet, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
-		return fmt.Errorf("dex: create password: unexpected status %d: %s", resp.StatusCode, strings.TrimSpace(string(snippet)))
-	}
-}
-
-// invalidNameChars matches anything not allowed in an RFC-1123 subdomain segment
-// after the explicit @/. substitutions, so any stray character becomes '-'.
-var invalidNameChars = regexp.MustCompile(`[^a-z0-9-]`)
-
-// passwordName maps an email to a valid, deterministic Kubernetes object name:
-// lowercase, '@' -> '-at-', '.' -> '-dot-', any remaining invalid char -> '-',
-// with leading/trailing '-' trimmed. Deterministic so a re-invite targets the
-// same CR (and so Dex's 409 is meaningful).
-func passwordName(email string) string {
-	n := strings.ToLower(strings.TrimSpace(email))
-	n = strings.ReplaceAll(n, "@", "-at-")
-	n = strings.ReplaceAll(n, ".", "-dot-")
-	n = invalidNameChars.ReplaceAllString(n, "-")
-	n = strings.Trim(n, "-")
-	if n == "" {
-		n = "user"
-	}
-	return n
-}

internal/adapters/dex/dex_test.go

@@ -1,104 +0,0 @@
-package dex
-
-import (
-	"context"
-	"encoding/base64"
-	"encoding/json"
-	"io"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"github.com/stretchr/testify/require"
-)
-
-// newTestClient points a PasswordClient at an httptest server, using that
-// server's TLS client so the in-cluster TLS path is exercised without a real CA.
-func newTestClient(srv *httptest.Server) *PasswordClient {
-	return newClient(srv.URL, "test-token", srv.Client())
-}
-
-func TestCreatePasswordSuccess(t *testing.T) {
-	var gotAuth, gotPath, gotMethod string
-	var gotBody password
-
-	srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotAuth, gotPath, gotMethod = r.Header.Get("Authorization"), r.URL.Path, r.Method
-		b, _ := io.ReadAll(r.Body)
-		_ = json.Unmarshal(b, &gotBody)
-		w.WriteHeader(http.StatusCreated)
-		_, _ = w.Write([]byte(`{"kind":"Password"}`))
-	}))
-	defer srv.Close()
-
-	err := newTestClient(srv).CreatePassword(context.Background(),
-		"New.User@Example.com", "$2a$12$abcdefghijklmnopqrstuv", "user-uuid-1")
-	require.NoError(t, err)
-
-	require.Equal(t, http.MethodPost, gotMethod)
-	require.Equal(t, passwordsPath, gotPath)
-	require.Equal(t, "Bearer test-token", gotAuth)
-
-	// Email/username carry the raw address; the CR name is sanitised + lowercased.
-	require.Equal(t, "New.User@Example.com", gotBody.Email)
-	require.Equal(t, "New.User@Example.com", gotBody.Username)
-	require.Equal(t, "user-uuid-1", gotBody.UserID)
-	require.Equal(t, "new-dot-user-at-example-dot-com", gotBody.Metadata["name"])
-	require.Equal(t, "auth", gotBody.Metadata["namespace"])
-
-	// The hash is the BASE64 of the bcrypt string (Dex stores hash as []byte).
-	decoded, err := base64.StdEncoding.DecodeString(gotBody.Hash)
-	require.NoError(t, err)
-	require.Equal(t, "$2a$12$abcdefghijklmnopqrstuv", string(decoded))
-}
-
-func TestCreatePasswordConflict(t *testing.T) {
-	srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusConflict)
-	}))
-	defer srv.Close()
-
-	err := newTestClient(srv).CreatePassword(context.Background(), "dup@example.com", "$2a$12$x", "u")
-	require.ErrorIs(t, err, ErrPasswordExists)
-}
-
-func TestCreatePasswordForbidden(t *testing.T) {
-	srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusForbidden)
-	}))
-	defer srv.Close()
-
-	err := newTestClient(srv).CreatePassword(context.Background(), "x@example.com", "$2a$12$x", "u")
-	require.ErrorIs(t, err, ErrForbidden)
-}
-
-func TestCreatePasswordUnexpectedStatus(t *testing.T) {
-	srv := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
-		w.WriteHeader(http.StatusInternalServerError)
-		_, _ = w.Write([]byte("boom"))
-	}))
-	defer srv.Close()
-
-	err := newTestClient(srv).CreatePassword(context.Background(), "x@example.com", "$2a$12$x", "u")
-	require.Error(t, err)
-	require.NotErrorIs(t, err, ErrPasswordExists)
-	require.NotErrorIs(t, err, ErrForbidden)
-	require.Contains(t, err.Error(), "500")
-}
-
-func TestNewPasswordClientNotInCluster(t *testing.T) {
-	// In the test environment the SA token mount does not exist.
-	_, err := NewPasswordClient()
-	require.ErrorIs(t, err, ErrNotInCluster)
-}
-
-func TestPasswordName(t *testing.T) {
-	cases := map[string]string{
-		"Alice@Example.com": "alice-at-example-dot-com",
-		"a.b+c@gmail.com":   "a-dot-b-c-at-gmail-dot-com",
-		"UPPER@DOMAIN.IO":   "upper-at-domain-dot-io",
-	}
-	for in, want := range cases {
-		require.Equal(t, want, passwordName(in), in)
-	}
-}

internal/adapters/llm/client.go

@@ -32,17 +32,46 @@ type Client struct {
 	model      string
 	maxTokens  int
 	httpClient *http.Client
+	usageHook  func(model string, prompt, completion int)
+}
+
+// Option configures a Client at construction. Variadic so the existing 4-arg
+// call sites stay valid as new knobs are added.
+type Option func(*Client)
+
+// WithMaxTokens overrides the per-request completion budget. The summarizer uses
+// this to cap completion for small-context models (e.g. koala/phi4-mini, 8k):
+// with the default 8192 budget, prompt + max_tokens overflows an 8k context and
+// the gateway returns HTTP 400. A non-positive n is ignored (keeps the default).
+func WithMaxTokens(n int) Option {
+	return func(c *Client) {
+		if n > 0 {
+			c.maxTokens = n
+		}
+	}
+}
+
+// WithUsageHook registers a callback fired after a successful completion with the
+// model and the prompt/completion token counts from the response usage block. It
+// keeps this copied, stdlib-only package (ADR-004) decoupled from metrics: the
+// caller wires it to internal/metrics, the client imports nothing. nil is ignored.
+func WithUsageHook(fn func(model string, prompt, completion int)) Option {
+	return func(c *Client) { c.usageHook = fn }
 }
 
 // New constructs a Client.
-func New(baseURL, apiKey, model string, timeout time.Duration) *Client {
-	return &Client{
+func New(baseURL, apiKey, model string, timeout time.Duration, opts ...Option) *Client {
+	c := &Client{
 		baseURL:    strings.TrimRight(baseURL, "/"),
 		apiKey:     apiKey,
 		model:      model,
 		maxTokens:  defaultMaxTokens,
 		httpClient: &http.Client{Timeout: timeout},
 	}
+	for _, opt := range opts {
+		opt(c)
+	}
+	return c
 }
 
 type chatRequest struct {
@@ -61,6 +90,10 @@ type chatResponse struct {
 	Choices []struct {
 		Message message `json:"message"`
 	} `json:"choices"`
+	Usage struct {
+		PromptTokens     int `json:"prompt_tokens"`
+		CompletionTokens int `json:"completion_tokens"`
+	} `json:"usage"`
 }
 
 // Complete sends a system + user message and returns the assistant's reply.
@@ -132,5 +165,8 @@ func (c *Client) Complete(ctx context.Context, system, user string) (string, err
 	if len(cr.Choices) == 0 {
 		return "", fmt.Errorf("LLM returned no choices")
 	}
+	if c.usageHook != nil {
+		c.usageHook(c.model, cr.Usage.PromptTokens, cr.Usage.CompletionTokens)
+	}
 	return cr.Choices[0].Message.Content, nil
 }

internal/adapters/llm/client_test.go

@@ -64,6 +64,51 @@ func TestClient_SendsMaxTokens(t *testing.T) {
 	}
 }
 
+// TestClient_WithMaxTokens overrides the completion budget — the summarizer caps
+// it small so prompt + max_tokens fits a small-context model's window (8k).
+func TestClient_WithMaxTokens(t *testing.T) {
+	var body chatRequest
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewDecoder(r.Body).Decode(&body)
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"choices": []map[string]any{{"message": map[string]any{"content": "ok"}}},
+		})
+	}))
+	defer srv.Close()
+
+	c := New(srv.URL, "", "test-model", 10*time.Second, WithMaxTokens(1500))
+	if _, err := c.Complete(context.Background(), "sys", "user"); err != nil {
+		t.Fatalf("Complete: %v", err)
+	}
+	if body.MaxTokens != 1500 {
+		t.Errorf("max_tokens = %d, want 1500", body.MaxTokens)
+	}
+}
+
+// TestClient_UsageHookRecordsTokens: the usage hook fires with the model and the
+// prompt/completion token counts parsed from the response usage block.
+func TestClient_UsageHookRecordsTokens(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"choices": []map[string]any{{"message": map[string]any{"content": "ok"}}},
+			"usage":   map[string]any{"prompt_tokens": 123, "completion_tokens": 45},
+		})
+	}))
+	defer srv.Close()
+
+	var gotModel string
+	var gotPrompt, gotCompletion int
+	c := New(srv.URL, "", "test-model", 10*time.Second, WithUsageHook(func(model string, p, comp int) {
+		gotModel, gotPrompt, gotCompletion = model, p, comp
+	}))
+	if _, err := c.Complete(context.Background(), "sys", "user"); err != nil {
+		t.Fatalf("Complete: %v", err)
+	}
+	if gotModel != "test-model" || gotPrompt != 123 || gotCompletion != 45 {
+		t.Errorf("usage hook got (%q, %d, %d), want (test-model, 123, 45)", gotModel, gotPrompt, gotCompletion)
+	}
+}
+
 func TestClient_ReturnsErrorOnNon200(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "overloaded", http.StatusServiceUnavailable)

internal/adapters/secrets/file.go

@@ -18,7 +18,7 @@ import (
 	"path/filepath"
 	"sync"
 
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/ports"
 )
 
 // FileStore is a SecretStore backed by a single 0600 JSON file mapping opaque

internal/adapters/secrets/file_test.go

@@ -7,7 +7,7 @@ import (
 	"path/filepath"
 	"testing"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/secrets"
+	"git.d-ma.be/mathias/tapir/internal/adapters/secrets"
 )
 
 func TestPutThenGet(t *testing.T) {

internal/adapters/store/account.go

@@ -10,13 +10,17 @@ import (
 // DeleteUser permanently removes a user and all of their data. It runs through
 // withUser so RLS confines every statement to the calling user's own rows.
 //
-// Deleting the users row cascades (ON DELETE CASCADE) to videos, transcripts,
-// summaries (→ sink_deliveries), video_connections, and the user_identities map
-// — referential-integrity cascades bypass RLS, so a user's child rows are removed
-// even though the deleting connection is scoped. summary_actions is the exception:
-// it carries a user_id but has NO foreign key to users (migration 002), so the
-// cascade does not reach it; it is deleted explicitly in the same scoped
-// transaction. Deleting an absent user is a no-op (idempotent).
+// Deleting the users row cascades (ON DELETE CASCADE) to videos, summaries
+// (→ sink_deliveries), video_connections, and the user_identities map —
+// referential-integrity cascades bypass RLS, so a user's child rows are removed
+// even though the deleting connection is scoped. Transcripts are NOT removed:
+// since ADR-021 they are shared public content keyed by (provider,
+// provider_video_id) with no user_id, so another user may still reference the
+// same row — a user deletion must not strip shared caption content. summary_actions and login_events
+// are the exceptions: each carries a user_id but has NO foreign key to users
+// (migrations 002 and 010), so the cascade does not reach them; they are deleted
+// explicitly in the same scoped transaction. Deleting an absent user is a no-op
+// (idempotent).
 //
 // This is tapir-side only (decision 2026-06-03): it removes all tapir data; the
 // Dex login identity is left untouched — a later login simply re-enters
@@ -28,6 +32,10 @@ func (s *Store) DeleteUser(ctx context.Context, userID string) error {
 			`DELETE FROM summary_actions WHERE user_id = $1`, userID); err != nil {
 			return fmt.Errorf("store: delete summary_actions: %w", err)
 		}
+		if _, err := tx.Exec(ctx,
+			`DELETE FROM login_events WHERE user_id = $1`, userID); err != nil {
+			return fmt.Errorf("store: delete login_events: %w", err)
+		}
 		if _, err := tx.Exec(ctx,
 			`DELETE FROM users WHERE id = $1`, userID); err != nil {
 			return fmt.Errorf("store: delete user: %w", err)

internal/adapters/store/channel_caption.go

@@ -0,0 +1,83 @@
+package store
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// CaptionlessChannels returns the set of channel ids currently suppressed for the
+// user — channels whose recent videos all yielded no captions, within their
+// suppression window (ADR-024). The runner skips caption fetches for these
+// channels' videos. A channel whose window has expired is not returned, so its
+// next video is re-probed (auto-recovery).
+func (s *Store) CaptionlessChannels(ctx context.Context, userID string) (map[string]bool, error) {
+	out := map[string]bool{}
+	err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		rows, err := tx.Query(ctx, `
+			SELECT channel_id FROM channel_caption_state
+			WHERE user_id = $1 AND captionless_until IS NOT NULL AND captionless_until > now()`,
+			userID)
+		if err != nil {
+			return fmt.Errorf("store: caption-less channels: %w", err)
+		}
+		defer rows.Close()
+		for rows.Next() {
+			var ch string
+			if err := rows.Scan(&ch); err != nil {
+				return fmt.Errorf("store: scan caption-less channel: %w", err)
+			}
+			out[ch] = true
+		}
+		return rows.Err()
+	})
+	return out, err
+}
+
+// RecordChannelCaptionOutcome updates a channel's caption-availability memory
+// after a fetch attempt (ADR-024). hadCaptions resets the channel (consecutive
+// count to 0, suppression cleared). Otherwise the consecutive no-caption count is
+// incremented; once it reaches threshold the channel is suppressed for window.
+// threshold <= 0 is a no-op (feature disabled). An empty channelID is ignored
+// (some sources may not carry one).
+func (s *Store) RecordChannelCaptionOutcome(ctx context.Context, userID, channelID string, hadCaptions bool, threshold int, window time.Duration) error {
+	if channelID == "" || threshold <= 0 {
+		return nil
+	}
+	return s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		if hadCaptions {
+			_, err := tx.Exec(ctx, `
+				INSERT INTO channel_caption_state (user_id, channel_id, consecutive_none, captionless_until, updated_at)
+				VALUES ($1, $2, 0, NULL, now())
+				ON CONFLICT (user_id, channel_id)
+				DO UPDATE SET consecutive_none = 0, captionless_until = NULL, updated_at = now()`,
+				userID, channelID)
+			if err != nil {
+				return fmt.Errorf("store: reset channel caption state: %w", err)
+			}
+			return nil
+		}
+		// No captions: increment the streak; suppress once it reaches threshold.
+		// captionless_until is set from the NEW count inside the same statement so
+		// the decision is atomic with the increment.
+		until := time.Now().Add(window)
+		_, err := tx.Exec(ctx, `
+			INSERT INTO channel_caption_state (user_id, channel_id, consecutive_none, captionless_until, updated_at)
+			VALUES ($1, $2, 1, CASE WHEN 1 >= $3 THEN $4::timestamptz ELSE NULL END, now())
+			ON CONFLICT (user_id, channel_id)
+			DO UPDATE SET
+				consecutive_none = channel_caption_state.consecutive_none + 1,
+				captionless_until = CASE
+					WHEN channel_caption_state.consecutive_none + 1 >= $3 THEN $4::timestamptz
+					ELSE channel_caption_state.captionless_until
+				END,
+				updated_at = now()`,
+			userID, channelID, threshold, until)
+		if err != nil {
+			return fmt.Errorf("store: record channel no-caption: %w", err)
+		}
+		return nil
+	})
+}

internal/adapters/store/channel_caption_test.go

@@ -0,0 +1,67 @@
+package store_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestChannelCaptionMemory_SuppressesAfterThreshold(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	seedUser(t, super, userA)
+
+	const threshold = 3
+	window := time.Hour
+
+	// Below threshold: not yet suppressed.
+	require.NoError(t, s.RecordChannelCaptionOutcome(ctx, userA, "chanX", false, threshold, window))
+	require.NoError(t, s.RecordChannelCaptionOutcome(ctx, userA, "chanX", false, threshold, window))
+	got, err := s.CaptionlessChannels(ctx, userA)
+	require.NoError(t, err)
+	require.NotContains(t, got, "chanX", "2 < threshold 3: not suppressed yet")
+
+	// Crossing the threshold suppresses the channel.
+	require.NoError(t, s.RecordChannelCaptionOutcome(ctx, userA, "chanX", false, threshold, window))
+	got, err = s.CaptionlessChannels(ctx, userA)
+	require.NoError(t, err)
+	require.Contains(t, got, "chanX", "3 consecutive no-caption results suppress the channel")
+
+	// A successful caption fetch resets it.
+	require.NoError(t, s.RecordChannelCaptionOutcome(ctx, userA, "chanX", true, threshold, window))
+	got, err = s.CaptionlessChannels(ctx, userA)
+	require.NoError(t, err)
+	require.NotContains(t, got, "chanX", "a captioned video clears suppression")
+}
+
+func TestChannelCaptionMemory_WindowExpiryReProbes(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	seedUser(t, super, userA)
+
+	// A negative window means captionless_until lands in the past — modelling an
+	// elapsed suppression window, which must make the channel eligible again.
+	require.NoError(t, s.RecordChannelCaptionOutcome(ctx, userA, "chanY", false, 1, -time.Hour))
+	got, err := s.CaptionlessChannels(ctx, userA)
+	require.NoError(t, err)
+	require.NotContains(t, got, "chanY", "an expired window re-enables the channel for a re-probe")
+}
+
+func TestChannelCaptionMemory_DisabledThresholdIsNoOp(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	seedUser(t, super, userA)
+
+	require.NoError(t, s.RecordChannelCaptionOutcome(ctx, userA, "chanZ", false, 0, time.Hour))
+	got, err := s.CaptionlessChannels(ctx, userA)
+	require.NoError(t, err)
+	require.Empty(t, got, "threshold 0 disables the memory — nothing recorded")
+}

internal/adapters/store/channel_errors.go

@@ -0,0 +1,59 @@
+package store
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// ChannelError is a channel that returned HTTP 404 on a discovery pass.
+type ChannelError struct {
+	ChannelID   string
+	ChannelName string
+	FirstSeen   time.Time
+	LastSeen    time.Time
+}
+
+// UpsertChannelError records (or refreshes) a 404 channel for the current user.
+// Called by the runner inside a withUser scope; RLS guards user isolation.
+func (s *Store) UpsertChannelError(ctx context.Context, userID, channelID, channelName string) error {
+	return s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		_, err := tx.Exec(ctx, `
+			INSERT INTO channel_errors (user_id, channel_id, channel_name)
+			VALUES ($1, $2, $3)
+			ON CONFLICT (user_id, channel_id)
+			DO UPDATE SET channel_name = EXCLUDED.channel_name, last_seen = now()`,
+			userID, channelID, channelName)
+		if err != nil {
+			return fmt.Errorf("store: upsert channel error: %w", err)
+		}
+		return nil
+	})
+}
+
+// ListChannelErrors returns all 404-flagged channels for the user, newest first.
+func (s *Store) ListChannelErrors(ctx context.Context, userID string) ([]ChannelError, error) {
+	var out []ChannelError
+	err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		rows, err := tx.Query(ctx, `
+			SELECT channel_id, channel_name, first_seen, last_seen
+			FROM channel_errors
+			WHERE user_id = $1
+			ORDER BY last_seen DESC`, userID)
+		if err != nil {
+			return fmt.Errorf("store: list channel errors: %w", err)
+		}
+		defer rows.Close()
+		for rows.Next() {
+			var ce ChannelError
+			if err := rows.Scan(&ce.ChannelID, &ce.ChannelName, &ce.FirstSeen, &ce.LastSeen); err != nil {
+				return fmt.Errorf("store: scan channel error: %w", err)
+			}
+			out = append(out, ce)
+		}
+		return rows.Err()
+	})
+	return out, err
+}

internal/adapters/store/connections_test.go

@@ -6,7 +6,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // seedUserRow inserts a bare users row (FK target for a connection) as the

internal/adapters/store/identity.go

@@ -31,6 +31,41 @@ func (s *Store) UserBySubject(ctx context.Context, subject string) (userID strin
 	return userID, true, nil
 }
 
+// UserIdentity is one (userID, dexSubject) pair from the un-RLS'd
+// user_identities map — the unit the scheduler enumerates to run a discovery
+// pass per user (ADR-018).
+type UserIdentity struct {
+	UserID     string
+	DexSubject string
+}
+
+// ListAllUsers returns every (userID, dexSubject) pair from user_identities. It
+// runs as a plain pool query WITHOUT withUser — intentional and legitimate:
+// user_identities is un-RLS'd auth plumbing (like UserBySubject), and the
+// scheduler enumerating all users to run their discovery passes is an admin
+// operation that cannot be scoped to any single user. Order is unspecified.
+func (s *Store) ListAllUsers(ctx context.Context) ([]UserIdentity, error) {
+	rows, err := s.pool.Query(ctx,
+		`SELECT user_id, dex_subject FROM user_identities`)
+	if err != nil {
+		return nil, fmt.Errorf("store: list all users: %w", err)
+	}
+	defer rows.Close()
+
+	var users []UserIdentity
+	for rows.Next() {
+		var u UserIdentity
+		if err := rows.Scan(&u.UserID, &u.DexSubject); err != nil {
+			return nil, fmt.Errorf("store: scan user identity: %w", err)
+		}
+		users = append(users, u)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("store: iterate user identities: %w", err)
+	}
+	return users, nil
+}
+
 // RegisterUser creates the tapir user for a Dex subject and the identity mapping
 // that points to it, returning the new user_id. It errors with
 // ErrSubjectRegistered if the subject already maps.

internal/adapters/store/identity_test.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 const (
@@ -85,6 +85,39 @@ func TestRegisterUserRejectsDuplicateSubject(t *testing.T) {
 	require.Equal(t, first, got)
 }
 
+func TestListAllUsersReturnsEveryIdentity(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+
+	empty, err := s.ListAllUsers(ctx)
+	require.NoError(t, err)
+	require.Empty(t, empty, "no registrations yet → empty slice")
+
+	const subjectC = "dex|carol-789"
+	idA, err := s.RegisterUser(ctx, subjectA, "Alice")
+	require.NoError(t, err)
+	idB, err := s.RegisterUser(ctx, subjectB, "Bob")
+	require.NoError(t, err)
+	idC, err := s.RegisterUser(ctx, subjectC, "Carol")
+	require.NoError(t, err)
+
+	users, err := s.ListAllUsers(ctx)
+	require.NoError(t, err)
+	require.Len(t, users, 3)
+
+	// Order is unspecified; compare as a set of (userID, subject) pairs.
+	got := make(map[string]string, len(users))
+	for _, u := range users {
+		got[u.DexSubject] = u.UserID
+	}
+	require.Equal(t, map[string]string{
+		subjectA: idA,
+		subjectB: idB,
+		subjectC: idC,
+	}, got)
+}
+
 func TestRegisterUserDistinctSubjectsGetDistinctUsers(t *testing.T) {
 	ctx := context.Background()
 	s := newStore(t)

internal/adapters/store/invitations.go

@@ -1,86 +0,0 @@
-package store
-
-import (
-	"context"
-	"crypto/rand"
-	"encoding/hex"
-	"errors"
-	"fmt"
-	"time"
-
-	"github.com/jackc/pgx/v5"
-)
-
-// Invitations are NOT routed through withUser: an invitation exists before its
-// user does, so there is no user_id to scope by and no authenticated context when
-// one is minted (host CLI) or claimed (the public /invite handler). The token is
-// the capability — single-use, time-boxed, crypto-random. The invitations table
-// is deliberately outside RLS for the same reason (see migration 009).
-
-// CreateInvitation mints a single-use invite for email, valid for ttl, and
-// returns its token. The token is 32 bytes of crypto-random entropy, hex-encoded;
-// it is the only secret a recipient needs to claim the invite.
-func (s *Store) CreateInvitation(ctx context.Context, email string, ttl time.Duration) (string, error) {
-	token, err := newInviteToken()
-	if err != nil {
-		return "", err
-	}
-	if _, err := s.pool.Exec(ctx,
-		`INSERT INTO invitations (email, token, expires_at)
-		 VALUES ($1, $2, NOW() + $3::interval)`,
-		email, token, ttl.String()); err != nil {
-		return "", fmt.Errorf("store: create invitation: %w", err)
-	}
-	return token, nil
-}
-
-// PeekInvitation returns the invited email for a token that is real, unexpired,
-// and unused WITHOUT consuming it — the read the /invite form does to validate the
-// link before showing the password fields. Returns ErrNotFound when the token is
-// missing, expired, or already used. Use ClaimInvitation to consume.
-func (s *Store) PeekInvitation(ctx context.Context, token string) (string, error) {
-	var email string
-	err := s.pool.QueryRow(ctx,
-		`SELECT email FROM invitations
-		  WHERE token = $1 AND used_at IS NULL AND expires_at > NOW()`,
-		token).Scan(&email)
-	if errors.Is(err, pgx.ErrNoRows) {
-		return "", ErrNotFound
-	}
-	if err != nil {
-		return "", fmt.Errorf("store: peek invitation: %w", err)
-	}
-	return email, nil
-}
-
-// ClaimInvitation atomically consumes a valid invite and returns its email. The
-// UPDATE ... WHERE used_at IS NULL AND expires_at > NOW() guarded by RETURNING
-// makes the claim a single round-trip race-free check-and-set: two concurrent
-// claims of the same token, only one updates a row, the other gets no rows and so
-// ErrNotFound. Same ErrNotFound for missing/expired/already-used tokens.
-func (s *Store) ClaimInvitation(ctx context.Context, token string) (string, error) {
-	var email string
-	err := s.pool.QueryRow(ctx,
-		`UPDATE invitations
-		    SET used_at = NOW()
-		  WHERE token = $1 AND used_at IS NULL AND expires_at > NOW()
-		 RETURNING email`,
-		token).Scan(&email)
-	if errors.Is(err, pgx.ErrNoRows) {
-		return "", ErrNotFound
-	}
-	if err != nil {
-		return "", fmt.Errorf("store: claim invitation: %w", err)
-	}
-	return email, nil
-}
-
-// newInviteToken returns 32 bytes of crypto-random entropy, hex-encoded (64
-// chars). Hex keeps the token URL-safe with no escaping in /invite/{token}.
-func newInviteToken() (string, error) {
-	var b [32]byte
-	if _, err := rand.Read(b[:]); err != nil {
-		return "", fmt.Errorf("store: invite token: %w", err)
-	}
-	return hex.EncodeToString(b[:]), nil
-}

internal/adapters/store/invitations_test.go

@@ -1,110 +0,0 @@
-package store_test
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	"github.com/jackc/pgx/v5/pgxpool"
-	"github.com/stretchr/testify/require"
-
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
-)
-
-// resetInvitations clears the invitations table between cases. It is not in the
-// shared resetDB TRUNCATE list (invitations is not user-owned and has no FK to
-// users), so the invite tests wipe it themselves.
-func resetInvitations(t *testing.T, p *pgxpool.Pool) {
-	t.Helper()
-	_, err := p.Exec(context.Background(), `TRUNCATE invitations`)
-	require.NoError(t, err)
-}
-
-func TestCreateInvitationReturnsUsableToken(t *testing.T) {
-	s, p := newStore(t), rawPool(t)
-	resetInvitations(t, p)
-	ctx := context.Background()
-
-	token, err := s.CreateInvitation(ctx, "new@example.com", time.Hour)
-	require.NoError(t, err)
-	require.Len(t, token, 64, "32 random bytes hex-encoded")
-
-	// Peek does not consume: the same token previews twice.
-	email, err := s.PeekInvitation(ctx, token)
-	require.NoError(t, err)
-	require.Equal(t, "new@example.com", email)
-	email, err = s.PeekInvitation(ctx, token)
-	require.NoError(t, err)
-	require.Equal(t, "new@example.com", email)
-}
-
-func TestCreateInvitationTokensAreUnique(t *testing.T) {
-	s, p := newStore(t), rawPool(t)
-	resetInvitations(t, p)
-	ctx := context.Background()
-
-	t1, err := s.CreateInvitation(ctx, "a@example.com", time.Hour)
-	require.NoError(t, err)
-	t2, err := s.CreateInvitation(ctx, "b@example.com", time.Hour)
-	require.NoError(t, err)
-	require.NotEqual(t, t1, t2)
-}
-
-func TestClaimInvitationHappyPath(t *testing.T) {
-	s, p := newStore(t), rawPool(t)
-	resetInvitations(t, p)
-	ctx := context.Background()
-
-	token, err := s.CreateInvitation(ctx, "claim@example.com", time.Hour)
-	require.NoError(t, err)
-
-	email, err := s.ClaimInvitation(ctx, token)
-	require.NoError(t, err)
-	require.Equal(t, "claim@example.com", email)
-}
-
-func TestClaimInvitationIsSingleUse(t *testing.T) {
-	s, p := newStore(t), rawPool(t)
-	resetInvitations(t, p)
-	ctx := context.Background()
-
-	token, err := s.CreateInvitation(ctx, "once@example.com", time.Hour)
-	require.NoError(t, err)
-
-	_, err = s.ClaimInvitation(ctx, token)
-	require.NoError(t, err)
-
-	// Second claim fails — already used.
-	_, err = s.ClaimInvitation(ctx, token)
-	require.ErrorIs(t, err, store.ErrNotFound)
-
-	// And a used token no longer previews.
-	_, err = s.PeekInvitation(ctx, token)
-	require.ErrorIs(t, err, store.ErrNotFound)
-}
-
-func TestClaimInvitationExpired(t *testing.T) {
-	s, p := newStore(t), rawPool(t)
-	resetInvitations(t, p)
-	ctx := context.Background()
-
-	// Negative ttl => already expired.
-	token, err := s.CreateInvitation(ctx, "old@example.com", -time.Minute)
-	require.NoError(t, err)
-
-	_, err = s.PeekInvitation(ctx, token)
-	require.ErrorIs(t, err, store.ErrNotFound)
-	_, err = s.ClaimInvitation(ctx, token)
-	require.ErrorIs(t, err, store.ErrNotFound)
-}
-
-func TestClaimInvitationNotFound(t *testing.T) {
-	s, p := newStore(t), rawPool(t)
-	resetInvitations(t, p)
-	ctx := context.Background()
-
-	_, err := s.ClaimInvitation(ctx, "does-not-exist")
-	require.ErrorIs(t, err, store.ErrNotFound)
-	_, err = s.PeekInvitation(ctx, "does-not-exist")
-	require.ErrorIs(t, err, store.ErrNotFound)
-}

internal/adapters/store/login.go

@@ -0,0 +1,41 @@
+package store
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// StampLogin records that the user was active today, throttled to one row per
+// user per day. It is the read-side counterpart to SetAction: the middleware
+// calls it on every authenticated request, but the append happens at most once a
+// day so login_events stays small and the signal clean (one row = one active
+// day, not one request).
+//
+// The check-and-insert is a single atomic statement: the INSERT ... SELECT ...
+// WHERE NOT EXISTS only writes when no row for this user has seen_at in today
+// (date_trunc('day', NOW()), server timezone). It runs through withUser, so the
+// NOT EXISTS probe is itself RLS-scoped to the calling user via the
+// tapir.current_user_id GUC — one user's stamp can never be suppressed or
+// triggered by another user's rows. The explicit user_id predicate also keeps the
+// probe on the (user_id, seen_at) index.
+//
+// A unique constraint is deliberately not used: under concurrent same-day
+// requests the worst case is two rows for one day, which the gate query collapses
+// to a single week bucket anyway — not worth a write-blocking constraint.
+func (s *Store) StampLogin(ctx context.Context, userID string) error {
+	if err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		_, err := tx.Exec(ctx,
+			`INSERT INTO login_events (user_id)
+			 SELECT $1
+			 WHERE NOT EXISTS (
+			     SELECT 1 FROM login_events
+			      WHERE user_id = $1 AND seen_at >= date_trunc('day', NOW())
+			 )`, userID)
+		return err
+	}); err != nil {
+		return fmt.Errorf("store: stamp login: %w", err)
+	}
+	return nil
+}

internal/adapters/store/login_test.go

@@ -0,0 +1,83 @@
+package store_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/stretchr/testify/require"
+)
+
+// countLoginEvents counts a user's login_events via the superuser pool, which
+// bypasses RLS — so the assertion sees the true row count regardless of scope.
+func countLoginEvents(t *testing.T, p *pgxpool.Pool, userID string) int {
+	t.Helper()
+	var n int
+	require.NoError(t, p.QueryRow(context.Background(),
+		`SELECT count(*) FROM login_events WHERE user_id = $1`, userID).Scan(&n))
+	return n
+}
+
+// TestStampLoginThrottlesToOnePerDay: repeated stamps within the same day insert
+// exactly one row — the throttle that keeps login_events one-row-per-active-day.
+func TestStampLoginThrottlesToOnePerDay(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	_, err := super.Exec(ctx, `INSERT INTO users (id) VALUES ($1)`, userA)
+	require.NoError(t, err)
+
+	for i := 0; i < 3; i++ {
+		require.NoError(t, s.StampLogin(ctx, userA))
+	}
+	require.Equal(t, 1, countLoginEvents(t, super, userA),
+		"three same-day stamps must collapse to one row")
+}
+
+// TestStampLoginRecordsOncePerNewDay: with yesterday's row already present, a
+// stamp today is NOT throttled — it appends the day's row, so distinct active days
+// accumulate (the substrate the gate's distinct-week count reads).
+func TestStampLoginRecordsOncePerNewDay(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	_, err := super.Exec(ctx, `INSERT INTO users (id) VALUES ($1)`, userA)
+	require.NoError(t, err)
+
+	// Seed an event dated yesterday (before today's start), so the throttle's
+	// "row exists with seen_at >= start-of-today" probe finds nothing for today.
+	_, err = super.Exec(ctx,
+		`INSERT INTO login_events (user_id, seen_at) VALUES ($1, NOW() - INTERVAL '1 day')`, userA)
+	require.NoError(t, err)
+
+	require.NoError(t, s.StampLogin(ctx, userA))
+	require.Equal(t, 2, countLoginEvents(t, super, userA),
+		"a stamp on a new day must append a second row")
+
+	// A second stamp the same day is throttled again.
+	require.NoError(t, s.StampLogin(ctx, userA))
+	require.Equal(t, 2, countLoginEvents(t, super, userA),
+		"the same-day repeat must not add a third row")
+}
+
+// TestStampLoginIsUserScoped: one user's stamp lands only on that user's rows —
+// the throttle probe is RLS-scoped, so user B's existing same-day row neither
+// suppresses nor is touched by user A's stamp.
+func TestStampLoginIsUserScoped(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	_, err := super.Exec(ctx, `INSERT INTO users (id) VALUES ($1), ($2)`, userA, userB)
+	require.NoError(t, err)
+
+	// B already has a same-day row; it must not throttle A's first stamp.
+	_, err = super.Exec(ctx, `INSERT INTO login_events (user_id) VALUES ($1)`, userB)
+	require.NoError(t, err)
+
+	require.NoError(t, s.StampLogin(ctx, userA))
+	require.Equal(t, 1, countLoginEvents(t, super, userA), "A's stamp must record despite B's same-day row")
+	require.Equal(t, 1, countLoginEvents(t, super, userB), "A's stamp must not touch B's rows")
+}

internal/adapters/store/migrate_test.go

@@ -0,0 +1,165 @@
+package store_test
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"os"
+	"testing"
+
+	"github.com/golang-migrate/migrate/v4"
+	migratepgx "github.com/golang-migrate/migrate/v4/database/pgx/v5"
+	"github.com/golang-migrate/migrate/v4/source/iofs"
+	"github.com/stretchr/testify/require"
+
+	_ "github.com/jackc/pgx/v5/stdlib" // register the "pgx" database/sql driver
+)
+
+// fileMigrator builds a golang-migrate instance from the on-disk migration files
+// (not the embedded FS the production Migrate uses), so a test can step the schema
+// up and down. os.DirFS(".") is rooted at the package dir; the SQL lives under
+// "migrations". Mirrors store.Migrate's construction otherwise.
+func fileMigrator(t *testing.T) *migrate.Migrate {
+	t.Helper()
+	db, err := sql.Open("pgx", dsn)
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = db.Close() })
+
+	drv, err := migratepgx.WithInstance(db, &migratepgx.Config{})
+	require.NoError(t, err)
+	src, err := iofs.New(os.DirFS("."), "migrations")
+	require.NoError(t, err)
+	m, err := migrate.NewWithInstance("iofs", src, "pgx", drv)
+	require.NoError(t, err)
+	t.Cleanup(func() { _, _ = m.Close() })
+	return m
+}
+
+// headVersion reports the current (HEAD) schema version so a test can restore
+// to it after stepping down, without hard-coding what HEAD is. Adding a
+// migration on top changes HEAD but no test that uses this needs editing.
+func headVersion(t *testing.T, m *migrate.Migrate) uint {
+	t.Helper()
+	v, dirty, err := m.Version()
+	require.NoError(t, err)
+	require.False(t, dirty, "schema must not be dirty")
+	return v
+}
+
+// migrateTo drives the schema to an exact version *by version number*, not by
+// step count. This is the whole point of the migrate-test design: a migration
+// added above the target does not shift any count here, so unrelated tests stay
+// green (see issue #8). ErrNoChange (already at that version) is not a failure.
+func migrateTo(t *testing.T, m *migrate.Migrate, version uint) {
+	t.Helper()
+	err := m.Migrate(version)
+	if errors.Is(err, migrate.ErrNoChange) {
+		return
+	}
+	require.NoError(t, err)
+}
+
+// loginEventsExists reports whether the login_events relation is present.
+func loginEventsExists(t *testing.T) bool {
+	t.Helper()
+	var reg *string
+	require.NoError(t, rawPool(t).QueryRow(context.Background(),
+		`SELECT to_regclass('public.login_events')::text`).Scan(&reg))
+	return reg != nil
+}
+
+// TestMigration010LoginEventsUpDown proves migration 010 is reversible: the down
+// migration drops login_events cleanly and the up migration recreates it. A rotten
+// down migration (forgotten DROP, dangling policy) would fail here rather than in
+// production during a rollback. The test restores the schema to latest before
+// returning so the shared embedded-postgres stays at HEAD for sibling tests.
+func TestMigration010LoginEventsUpDown(t *testing.T) {
+	newStore(t) // ensure the schema is migrated to latest (011 applied)
+	require.True(t, loginEventsExists(t), "login_events must exist at latest migration")
+
+	m := fileMigrator(t)
+	head := headVersion(t, m)
+
+	migrateTo(t, m, 9) // just below 010 — everything above steps down
+	require.False(t, loginEventsExists(t), "login_events must be gone after the down migration")
+
+	migrateTo(t, m, 10) // up 010
+	require.True(t, loginEventsExists(t), "login_events must be restored after the up migration")
+
+	migrateTo(t, m, head) // restore to HEAD for sibling tests
+}
+
+// autoSummarizeDefault reads the users.auto_summarize column default as text
+// ("true"/"false"), so the migration's default flip is verifiable directly.
+func autoSummarizeDefault(t *testing.T) string {
+	t.Helper()
+	var def string
+	require.NoError(t, rawPool(t).QueryRow(context.Background(),
+		`SELECT column_default FROM information_schema.columns
+		  WHERE table_name = 'users' AND column_name = 'auto_summarize'`).Scan(&def))
+	return def
+}
+
+// TestMigration011AutoSummarizeDefaultUpDown proves migration 011 is reversible:
+// up sets the auto_summarize column default to TRUE (ADR-018), down restores
+// FALSE. The down intentionally does not revert existing rows — only the default.
+func TestMigration011AutoSummarizeDefaultUpDown(t *testing.T) {
+	newStore(t) // latest (013 applied)
+	require.Equal(t, "true", autoSummarizeDefault(t), "011 sets the default to TRUE")
+
+	m := fileMigrator(t)
+	head := headVersion(t, m)
+
+	migrateTo(t, m, 10) // just below 011 — reverts the column default
+	require.Equal(t, "false", autoSummarizeDefault(t), "default is FALSE after the down migration")
+
+	migrateTo(t, m, 11) // up 011 re-applies the TRUE default
+	require.Equal(t, "true", autoSummarizeDefault(t))
+
+	migrateTo(t, m, head) // restore to HEAD for sibling tests
+}
+
+// channelTitleExists reports whether videos.channel_title is present.
+func channelTitleExists(t *testing.T) bool {
+	t.Helper()
+	var exists bool
+	require.NoError(t, rawPool(t).QueryRow(context.Background(),
+		`SELECT EXISTS (SELECT 1 FROM information_schema.columns
+		  WHERE table_name = 'videos' AND column_name = 'channel_title')`).Scan(&exists))
+	return exists
+}
+
+// TestMigration014VideoChannelTitleUpDown proves 014 is reversible: down drops
+// videos.channel_title, up recreates it.
+func TestMigration014VideoChannelTitleUpDown(t *testing.T) {
+	newStore(t) // latest (014 applied)
+	require.True(t, channelTitleExists(t), "channel_title exists at latest migration")
+
+	m := fileMigrator(t)
+	head := headVersion(t, m)
+
+	migrateTo(t, m, 13) // just below 014 — drops channel_title
+	require.False(t, channelTitleExists(t), "channel_title must be gone after the down migration")
+
+	migrateTo(t, m, 14) // up 014 recreates channel_title
+	require.True(t, channelTitleExists(t), "channel_title must be restored after the up migration")
+
+	migrateTo(t, m, head) // restore to HEAD for sibling tests
+}
+
+// TestMigration012FixAutoSummarizeRLS proves 012 runs cleanly and flips any
+// remaining auto_summarize=FALSE rows to TRUE (the back-fill blocked by RLS in 011).
+func TestMigration012FixAutoSummarizeRLS(t *testing.T) {
+	newStore(t) // apply all migrations including 012
+	require.Equal(t, "true", autoSummarizeDefault(t), "column default is TRUE after 012")
+
+	// Round-trip: down 012, then up 012 — must be idempotent.
+	m := fileMigrator(t)
+	head := headVersion(t, m)
+
+	migrateTo(t, m, 11) // down 012 must not error
+	migrateTo(t, m, 12) // up 012 must re-apply cleanly
+	require.Equal(t, "true", autoSummarizeDefault(t), "default still TRUE after 012 re-applied")
+
+	migrateTo(t, m, head) // restore to HEAD for sibling tests
+}

internal/adapters/store/migrations/010_login_events.down.sql

@@ -0,0 +1,4 @@
+DROP POLICY IF EXISTS login_events_isolation ON login_events;
+ALTER TABLE login_events NO FORCE ROW LEVEL SECURITY;
+ALTER TABLE login_events DISABLE ROW LEVEL SECURITY;
+DROP TABLE IF EXISTS login_events;

internal/adapters/store/migrations/010_login_events.up.sql

@@ -0,0 +1,33 @@
+-- Migration 010: login_events records THAT a user was active (returned and read)
+-- on a given day — the Stage-0 signal summary_actions misses. summary_actions
+-- captures *acts* (watch/skip/save); a reader who logs in weekly and clicks
+-- nothing is otherwise invisible, yet for a reading product that return IS the
+-- signal the gate ("usage in >=2 distinct weeks", VISION/ADR-016) is defined on.
+--
+-- Append-only: one row per user per active day (the request-path throttle in the
+-- web layer enforces that cadence), never updated. Per-user isolation like every
+-- user-owned table.
+--
+-- NO foreign key to users (mirrors summary_actions, migration 002): user_id is
+-- carried for RLS/scoping but the table is decoupled so a stamp never blocks on a
+-- users row. The cost of that decoupling: the users-row cascade does NOT reach
+-- login_events, so DeleteUser must delete it explicitly (see account.go) — the
+-- exact footgun the summary_actions delete work caught.
+CREATE TABLE login_events (
+    id       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id  UUID NOT NULL,
+    seen_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- (user_id, seen_at) serves both the per-user-per-day throttle lookup
+-- (seen_at >= start-of-today) and the gate query's per-user week bucketing.
+CREATE INDEX idx_login_events_user_seen ON login_events(user_id, seen_at);
+
+-- RLS: identical GUC-keyed policy/pattern to migration 003. FORCE so the table
+-- owner (tapir, non-superuser in prod) is subject to it; an unset GUC yields NULL
+-- → no rows match → deny-all.
+ALTER TABLE login_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE login_events FORCE ROW LEVEL SECURITY;
+CREATE POLICY login_events_isolation ON login_events
+    FOR ALL
+    USING (user_id = current_setting('tapir.current_user_id', true)::uuid);

internal/adapters/store/migrations/011_auto_summarize_default.down.sql

@@ -0,0 +1,5 @@
+-- Revert the column default to FALSE. Existing rows are intentionally NOT
+-- reverted: flipping live users back to manual on a rollback would be a
+-- surprising regression (they may have come to rely on auto). The default change
+-- is the reversible part; data stays as the user left it.
+ALTER TABLE users ALTER COLUMN auto_summarize SET DEFAULT FALSE;

internal/adapters/store/migrations/011_auto_summarize_default.up.sql

@@ -0,0 +1,17 @@
+-- Migration 011: flip auto_summarize default to TRUE (ADR-018, Future-B).
+--
+-- Scheduled discovery (ADR-018) makes Tapir watch unprompted. For onboarded
+-- friends that only delivers zero-friction value if the list also SUMMARIZES
+-- itself — a manual default would mean the scheduler discovers videos a user
+-- still has to click through one by one, which is the empty-list problem again.
+-- So new users default to AUTO. The account-page toggle still lets a user switch
+-- to manual (SetAutoSummarize), so this only changes the out-of-the-box state.
+--
+-- Safe only because the process-wide caption-fetch rate gate (ADR-014 item 2)
+-- now exists: auto + scheduled + multi-user would otherwise self-inflict 429s
+-- every cycle. The gate is the precondition for shipping this default.
+ALTER TABLE users ALTER COLUMN auto_summarize SET DEFAULT TRUE;
+
+-- Bring existing rows (maintainer + any current registrations) onto the new
+-- default so they benefit immediately, not just users created after this point.
+UPDATE users SET auto_summarize = TRUE WHERE auto_summarize = FALSE;

internal/adapters/store/migrations/012_fix_auto_summarize_rls.down.sql

@@ -0,0 +1 @@
+-- No data revert: do not flip users back to manual on rollback.

internal/adapters/store/migrations/012_fix_auto_summarize_rls.up.sql

@@ -0,0 +1,6 @@
+-- Migration 011's UPDATE ran without tapir.current_user_id set, so FORCE RLS
+-- blocked all rows and zero users were updated. Temporarily drop FORCE so the
+-- table owner (tapir role) can bypass RLS for this back-fill, then restore it.
+ALTER TABLE users NO FORCE ROW LEVEL SECURITY;
+UPDATE users SET auto_summarize = TRUE WHERE auto_summarize = FALSE;
+ALTER TABLE users FORCE ROW LEVEL SECURITY;

internal/adapters/store/migrations/013_channel_errors.down.sql

@@ -0,0 +1 @@
+DROP TABLE IF EXISTS channel_errors;

internal/adapters/store/migrations/013_channel_errors.up.sql

@@ -0,0 +1,22 @@
+-- channel_errors: channels that returned HTTP 404 (deleted/private) on the most
+-- recent scheduler pass. Surfaced on the account page so users know why some
+-- subscribed channels produce no videos. Upserted per-pass; cleared when the
+-- channel starts returning results again (runner calls UpsertChannelError only
+-- on 404, so a recovered channel simply stops appearing after its row ages out
+-- or the user takes action). ON DELETE CASCADE keeps rows tidy on account deletion.
+CREATE TABLE channel_errors (
+    user_id      UUID        NOT NULL REFERENCES users(id)  ON DELETE CASCADE,
+    channel_id   TEXT        NOT NULL,
+    channel_name TEXT        NOT NULL,
+    first_seen   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    last_seen    TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, channel_id)
+);
+
+CREATE INDEX idx_channel_errors_user_id ON channel_errors(user_id);
+
+ALTER TABLE channel_errors ENABLE ROW LEVEL SECURITY;
+ALTER TABLE channel_errors FORCE ROW LEVEL SECURITY;
+CREATE POLICY channel_errors_isolation ON channel_errors
+    FOR ALL
+    USING (user_id = current_setting('tapir.current_user_id', true)::uuid);

internal/adapters/store/migrations/014_video_channel_title.down.sql

@@ -0,0 +1 @@
+ALTER TABLE videos DROP COLUMN channel_title;

internal/adapters/store/migrations/014_video_channel_title.up.sql

@@ -0,0 +1,8 @@
+-- Store the source channel's title per video so the list can offer a real
+-- channel filter (multi-select of the user's channels) instead of the dead
+-- free-text field that only ever matched the provider string. Nullable: existing
+-- rows backfill on the next discovery pass (UpsertVideo writes it); pasted videos
+-- get it immediately from videos.list. No FK to a channels table at Stage 0 — the
+-- title is a denormalised display/filter value, consistent with the existing
+-- subscription_id-stays-NULL stance (data-model.md).
+ALTER TABLE videos ADD COLUMN channel_title TEXT;

internal/adapters/store/migrations/015_shared_transcripts.down.sql

@@ -0,0 +1,19 @@
+-- Down 015: restore the per-user RLS-scoped transcripts shape (001 + 003).
+DROP TABLE transcripts;
+
+CREATE TABLE transcripts (
+    video_id    UUID PRIMARY KEY REFERENCES videos(id) ON DELETE CASCADE,
+    user_id     UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    source      TEXT NOT NULL,
+    language    TEXT,
+    content     TEXT,
+    resolved_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_transcripts_user_id ON transcripts(user_id);
+
+ALTER TABLE transcripts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE transcripts FORCE ROW LEVEL SECURITY;
+CREATE POLICY transcripts_isolation ON transcripts
+    FOR ALL
+    USING (user_id = current_setting('tapir.current_user_id', true)::uuid);

internal/adapters/store/migrations/015_shared_transcripts.up.sql

@@ -0,0 +1,30 @@
+-- Migration 015: transcripts become SHARED public-content storage (ADR-021).
+--
+-- The per-user transcripts table from 001 (PK videos.id, user_id NOT NULL, RLS
+-- FORCEd in 003) was dead: no application code ever read or wrote it — only the
+-- transcript_status columns on `videos` (007) carried fetch outcomes. ADR-021
+-- repurposes it as the single shared store of public caption content, keyed by
+-- the cross-user dedup key (provider, provider_video_id) — the video's public
+-- identity, not Tapir's per-user videos.id — so re-analysis never re-fetches
+-- from YouTube (ADR-010/014).
+--
+-- It holds ONLY public caption content + the video's public id (nothing
+-- user-identifying), so it is deliberately NOT RLS-scoped: no user_id, no
+-- policy, no FORCE. This is the single, intentional exception to the ADR-012
+-- isolation boundary; rls_test.go asserts the boundary is exactly here and
+-- nowhere else. Dropping the old table drops its RLS policy with it; it held no
+-- real data, so drop+recreate loses nothing.
+DROP TABLE transcripts;
+
+CREATE TABLE transcripts (
+    provider          TEXT NOT NULL,
+    provider_video_id TEXT NOT NULL,
+    source            TEXT NOT NULL, -- 'captions' (content set) | 'none' (no captions; content NULL)
+    language          TEXT,
+    content           TEXT,
+    fetched_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (provider, provider_video_id)
+);
+
+COMMENT ON TABLE transcripts IS
+    'Shared public caption content keyed by (provider, provider_video_id). NOT RLS-scoped — public content only, de-facto cross-user dedup (ADR-021).';

internal/adapters/store/migrations/016_channel_caption_state.down.sql

@@ -0,0 +1 @@
+DROP TABLE channel_caption_state;

internal/adapters/store/migrations/016_channel_caption_state.up.sql

@@ -0,0 +1,30 @@
+-- Migration 016: per-(user, channel) caption-availability memory (ADR-024).
+--
+-- Some channels never publish English captions (foreign-language news, music,
+-- etc.). Each of their new videos still costs ONE rate-limited caption fetch
+-- (ADR-014) before resolving to "none" — and on a throttled egress IP that fetch
+-- may 429 and churn through the backoff machinery first. This table remembers
+-- channels that repeatedly yield no captions so discovery can stop attempting
+-- their videos, freeing the scarce fetch budget for channels that do have them.
+--
+-- consecutive_none counts no-caption outcomes in a row; a successful fetch resets
+-- it to 0. Once it crosses the threshold the channel is suppressed until
+-- captionless_until, after which one video is re-probed (auto-recovery for a
+-- channel that starts adding captions). Per-user + RLS-scoped, consistent with
+-- the rest of the user-owned schema (subscriptions are per-user; ADR-012).
+CREATE TABLE channel_caption_state (
+    user_id           UUID        NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    channel_id        TEXT        NOT NULL,
+    consecutive_none  INT         NOT NULL DEFAULT 0,
+    captionless_until TIMESTAMPTZ,
+    updated_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (user_id, channel_id)
+);
+
+CREATE INDEX idx_channel_caption_state_user_id ON channel_caption_state(user_id);
+
+ALTER TABLE channel_caption_state ENABLE ROW LEVEL SECURITY;
+ALTER TABLE channel_caption_state FORCE ROW LEVEL SECURITY;
+CREATE POLICY channel_caption_state_isolation ON channel_caption_state
+    FOR ALL
+    USING (user_id = current_setting('tapir.current_user_id', true)::uuid);

internal/adapters/store/reads.go

@@ -29,6 +29,7 @@ type SummaryRow struct {
 	ProviderVideoID string    // videos.provider_video_id; empty when no videos row
 	Title           string    // videos.title; empty when no videos row
 	Channel         string    // videos.provider for now; empty when no videos row
+	ChannelTitle    string    // videos.channel_title; the source channel, for display + filtering
 	URL             string    // videos.url; empty when no videos row
 	PublishedAt     time.Time // videos.published_at; zero when absent
 	Summary         string
@@ -137,24 +138,28 @@ const selectVideo = `
 	       COALESCE(s.created_at, v.seen_at),
 	       (s.id IS NOT NULL) AS summarized,
 	       v.summarize_requested,
-	       COALESCE(v.transcript_status, '')
+	       COALESCE(v.transcript_status, ''),
+	       COALESCE(v.channel_title, '')
 	  FROM videos v
 	  LEFT JOIN summaries s ON s.video_id = v.id AND s.user_id = v.user_id`
 
-// ListVideos returns ALL of the user's videos — summarized and not — most recent
-// first by seen_at, capped at limit (non-positive defaults to 50). Unsummarized
+// ListVideos returns ALL of the user's videos — summarized first, then by
+// published_at DESC with undated videos last, then seen_at DESC as a tiebreak —
+// capped at limit (non-positive defaults to 500). The published_at ordering
+// aligns the list with the recency framing (newest content first); seen_at
+// breaks ties and orders same/!undated rows deterministically. Unsummarized
 // videos come back with Summarized=false and empty summary fields, so the list
 // view can render them with a "Summarize" affordance. Scoped by user_id.
 func (s *Store) ListVideos(ctx context.Context, userID string, limit int) ([]SummaryRow, error) {
 	if limit <= 0 {
-		limit = 50
+		limit = 500
 	}
 	var out []SummaryRow
 	if err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
 		rows, err := tx.Query(ctx,
 			selectVideo+`
 			 WHERE v.user_id = $1
-			 ORDER BY v.seen_at DESC
+			 ORDER BY (s.id IS NOT NULL) DESC, v.published_at DESC NULLS LAST, v.seen_at DESC
 			 LIMIT $2`,
 			userID, limit)
 		if err != nil {
@@ -251,6 +256,7 @@ func scanVideoRow(rows pgx.Row) (SummaryRow, error) {
 		&row.Summarized,
 		&row.SummarizeRequested,
 		&row.TranscriptStatus,
+		&row.ChannelTitle,
 	); err != nil {
 		return SummaryRow{}, fmt.Errorf("store: scan video: %w", err)
 	}

internal/adapters/store/reads_test.go

@@ -8,7 +8,7 @@ import (
 	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // seedVideo inserts a videos row whose id matches a summary's video_id, so the

internal/adapters/store/report.go

@@ -0,0 +1,117 @@
+package store
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// UserActiveWeeks is one row of the Stage-0 gate report: how many DISTINCT
+// calendar weeks a user was active in, counting reads (login_events) AND acts
+// (summary_actions) together. The gate (VISION/ADR-016) passes when any user
+// reaches ActiveWeeks >= 2.
+type UserActiveWeeks struct {
+	UserID      string
+	DisplayName string
+	ActiveWeeks int
+}
+
+// ActiveWeeks computes per-user distinct-active-weeks for the gate report, most
+// active first.
+//
+// Why per-user iteration rather than one cross-user GROUP BY: the user-owned
+// tables are FORCE RLS (migration 003/010) and the production role is a non-
+// superuser owner, so a single un-scoped query sees nothing (deny-all). Instead we
+// enumerate users from the deliberately un-RLS'd identity map (user_identities,
+// migration 004) and count each user's weeks inside withUser, where the GUC scopes
+// login_events + summary_actions to that user. No privilege escalation, no policy
+// change — the same isolation seam every other read flows through.
+//
+// Scope note: the enumeration covers users with a Dex identity (the web users the
+// gate is about). A CLI-only user created by the store sink without an identity
+// row would not appear — out of scope for this gate.
+// ActiveWeeks counts each user's distinct active weeks from `since` onward. A zero
+// `since` means no lower bound (count all history). The Stage-0 gate baseline is
+// set by the caller (the report command) to the date real usage tracking began,
+// so pre-launch noise — testing, the period the pilot was blocked — does not count
+// toward the return-usage signal (ADR-016).
+func (s *Store) ActiveWeeks(ctx context.Context, since time.Time) ([]UserActiveWeeks, error) {
+	userIDs, err := s.identityUserIDs(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	out := make([]UserActiveWeeks, 0, len(userIDs))
+	for _, uid := range userIDs {
+		row, err := s.activeWeeksFor(ctx, uid, since)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, row)
+	}
+
+	// Most active first; user_id as a stable tie-break for deterministic output.
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].ActiveWeeks != out[j].ActiveWeeks {
+			return out[i].ActiveWeeks > out[j].ActiveWeeks
+		}
+		return out[i].UserID < out[j].UserID
+	})
+	return out, nil
+}
+
+// identityUserIDs lists every tapir user_id from the un-RLS'd identity map. It
+// runs directly on the pool (no withUser): user_identities carries no user data
+// and is intentionally not RLS-enabled, so it is the one table that can be read
+// pre-scope to discover who exists.
+func (s *Store) identityUserIDs(ctx context.Context) ([]string, error) {
+	rows, err := s.pool.Query(ctx, `SELECT user_id FROM user_identities ORDER BY user_id`)
+	if err != nil {
+		return nil, fmt.Errorf("store: list identity users: %w", err)
+	}
+	defer rows.Close()
+
+	var ids []string
+	for rows.Next() {
+		var id string
+		if err := rows.Scan(&id); err != nil {
+			return nil, fmt.Errorf("store: scan identity user: %w", err)
+		}
+		ids = append(ids, id)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("store: iterate identity users: %w", err)
+	}
+	return ids, nil
+}
+
+// activeWeeksFor counts one user's distinct active weeks (reads UNION acts) and
+// reads their display name, RLS-scoped via withUser. The UNION dedups a week that
+// has both a login and an action so it counts once.
+func (s *Store) activeWeeksFor(ctx context.Context, userID string, since time.Time) (UserActiveWeeks, error) {
+	res := UserActiveWeeks{UserID: userID}
+	if err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		if err := tx.QueryRow(ctx,
+			`WITH weeks AS (
+			     SELECT date_trunc('week', seen_at) AS wk
+			       FROM login_events WHERE user_id = $1 AND seen_at >= $2
+			     UNION
+			     SELECT date_trunc('week', acted_at)
+			       FROM summary_actions WHERE user_id = $1 AND acted_at >= $2
+			 )
+			 SELECT count(DISTINCT wk) FROM weeks`, userID, since).Scan(&res.ActiveWeeks); err != nil {
+			return fmt.Errorf("store: count active weeks: %w", err)
+		}
+		if err := tx.QueryRow(ctx,
+			`SELECT COALESCE(display_name, '') FROM users WHERE id = $1`, userID).Scan(&res.DisplayName); err != nil {
+			return fmt.Errorf("store: read display name: %w", err)
+		}
+		return nil
+	}); err != nil {
+		return UserActiveWeeks{}, err
+	}
+	return res, nil
+}

internal/adapters/store/report_test.go

@@ -0,0 +1,105 @@
+package store_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/stretchr/testify/require"
+)
+
+// seedReportUser inserts a user + its identity mapping (the enumeration source
+// ActiveWeeks reads). display_name is optional.
+func seedReportUser(t *testing.T, p *pgxpool.Pool, userID, subject, name string) {
+	t.Helper()
+	ctx := context.Background()
+	_, err := p.Exec(ctx,
+		`INSERT INTO users (id, display_name) VALUES ($1, NULLIF($2, ''))`, userID, name)
+	require.NoError(t, err)
+	_, err = p.Exec(ctx,
+		`INSERT INTO user_identities (dex_subject, user_id) VALUES ($1, $2)`, subject, userID)
+	require.NoError(t, err)
+}
+
+// TestActiveWeeksCountsDistinctWeeksAcrossReadsAndActs is the gate-query proof.
+// It seeds, with fixed timestamps in known ISO weeks:
+//   - user A: reads in week of Jan 5 and Jan 12, acts in week of Jan 12 (dup) and
+//     Jan 19 → the UNION across both tables collapses the shared week → 3 distinct.
+//   - user B: a single read in the week of Jan 5 → 1 distinct (below the gate).
+//
+// It verifies the count is correct, dedups the cross-table shared week, and orders
+// most-active first.
+func TestActiveWeeksCountsDistinctWeeksAcrossReadsAndActs(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	p := rawPool(t)
+	resetDB(t, p) // TRUNCATE ... users CASCADE also clears user_identities
+
+	seedReportUser(t, p, userA, "subject-a", "Ada")
+	seedReportUser(t, p, userB, "subject-b", "")
+
+	// Reads (login_events) — fixed dates in distinct ISO weeks.
+	_, err := p.Exec(ctx,
+		`INSERT INTO login_events (user_id, seen_at) VALUES
+		   ($1, '2026-01-05T09:00:00Z'),
+		   ($1, '2026-01-12T09:00:00Z'),
+		   ($2, '2026-01-05T09:00:00Z')`, userA, userB)
+	require.NoError(t, err)
+
+	// Acts (summary_actions) — one in A's week-of-Jan-12 (shared with a read, must
+	// dedup) and one in a new week (Jan 19).
+	_, err = p.Exec(ctx,
+		`INSERT INTO summary_actions (user_id, video_id, action, acted_at) VALUES
+		   ($1, 'vid-1', 'watched', '2026-01-12T18:00:00Z'),
+		   ($1, 'vid-2', 'saved',   '2026-01-19T18:00:00Z')`, userA)
+	require.NoError(t, err)
+
+	got, err := s.ActiveWeeks(ctx, time.Time{}) // zero since = no lower bound
+	require.NoError(t, err)
+	require.Len(t, got, 2, "both identity users must appear")
+
+	require.Equal(t, userA, got[0].UserID, "most-active user first")
+	require.Equal(t, "Ada", got[0].DisplayName)
+	require.Equal(t, 3, got[0].ActiveWeeks, "3 distinct weeks across reads+acts, shared week deduped")
+
+	require.Equal(t, userB, got[1].UserID)
+	require.Equal(t, 1, got[1].ActiveWeeks, "single read = 1 distinct week (below gate)")
+}
+
+// TestActiveWeeksEmptyWhenNoUsers: no identities → no rows (not an error).
+func TestActiveWeeksEmptyWhenNoUsers(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+
+	got, err := s.ActiveWeeks(ctx, time.Time{})
+	require.NoError(t, err)
+	require.Empty(t, got)
+}
+
+// TestActiveWeeksExcludesBeforeGateStart proves the baseline cutoff: activity
+// before `since` does not count, so pre-launch noise (testing, the pilot's blocked
+// period) is excluded from the Stage-0 return-usage gate (ADR-016).
+func TestActiveWeeksExcludesBeforeGateStart(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	p := rawPool(t)
+	resetDB(t, p)
+
+	seedReportUser(t, p, userA, "subject-a", "Ada")
+
+	// One read well before the baseline, two reads in distinct weeks after it.
+	_, err := p.Exec(ctx,
+		`INSERT INTO login_events (user_id, seen_at) VALUES
+		   ($1, '2026-05-01T09:00:00Z'),
+		   ($1, '2026-06-12T09:00:00Z'),
+		   ($1, '2026-06-19T09:00:00Z')`, userA)
+	require.NoError(t, err)
+
+	since := time.Date(2026, 6, 11, 0, 0, 0, 0, time.UTC)
+	got, err := s.ActiveWeeks(ctx, since)
+	require.NoError(t, err)
+	require.Len(t, got, 1)
+	require.Equal(t, 2, got[0].ActiveWeeks, "only the two post-baseline weeks count; the May read is excluded")
+}

internal/adapters/store/rls_test.go

@@ -22,9 +22,11 @@ import (
 // (no GUC set → zero rows) proves the enforcement path is live, not bypassed.
 
 // userIsolatedTables are the tables that carry a user_id and whose policy keys
-// directly off the tapir.current_user_id GUC.
+// directly off the tapir.current_user_id GUC. transcripts is deliberately ABSENT
+// — ADR-021 made it shared public content (non-RLS); TestTranscriptsTableIsSharedNotRLS
+// proves that is the only place the isolation boundary moved.
 var userIsolatedTables = []string{
-	"users", "videos", "transcripts", "summaries", "summary_actions", "video_connections",
+	"users", "videos", "summaries", "summary_actions", "login_events", "video_connections",
 }
 
 // allIsolatedTables adds sink_deliveries, whose ownership is derived from its
@@ -38,9 +40,10 @@ type seeded struct {
 	summaryID string
 }
 
-// seedUser inserts one full chain (user → video → transcript → summary →
-// action → delivery) as the superuser pool, which bypasses RLS so both users'
-// data lands regardless of the GUC.
+// seedUser inserts one full chain (user → video → summary → action → delivery)
+// as the superuser pool, which bypasses RLS so both users' data lands regardless
+// of the GUC. Transcripts are NOT seeded here: they are shared, non-RLS public
+// content (ADR-021), so they have no place in a per-user isolation chain.
 func seedUser(t *testing.T, p *pgxpool.Pool, userID string) seeded {
 	t.Helper()
 	ctx := context.Background()
@@ -54,11 +57,6 @@ func seedUser(t *testing.T, p *pgxpool.Pool, userID string) seeded {
 		 VALUES ($1, 'youtube', $2, 'title') RETURNING id`,
 		userID, "vid-"+userID).Scan(&videoID))
 
-	_, err = p.Exec(ctx,
-		`INSERT INTO transcripts (video_id, user_id, source, content)
-		 VALUES ($1, $2, 'captions', 'words')`, videoID, userID)
-	require.NoError(t, err)
-
 	var summaryID string
 	require.NoError(t, p.QueryRow(ctx,
 		`INSERT INTO summaries (user_id, video_id, summary) VALUES ($1, $2, 'sum')
@@ -69,6 +67,10 @@ func seedUser(t *testing.T, p *pgxpool.Pool, userID string) seeded {
 		 VALUES ($1, $2, 'watched')`, userID, videoID)
 	require.NoError(t, err)
 
+	_, err = p.Exec(ctx,
+		`INSERT INTO login_events (user_id) VALUES ($1)`, userID)
+	require.NoError(t, err)
+
 	_, err = p.Exec(ctx,
 		`INSERT INTO sink_deliveries (summary_id, sink, status)
 		 VALUES ($1, 'store', 'delivered')`, summaryID)
@@ -88,9 +90,16 @@ func appPool(t *testing.T, super *pgxpool.Pool) *pgxpool.Pool {
 	t.Helper()
 	ctx := context.Background()
 
-	// Idempotent across test runs (schema/role persist for the TestMain PG).
-	_, _ = super.Exec(ctx, `DROP ROLE IF EXISTS app`)
-	_, err := super.Exec(ctx, `CREATE ROLE app LOGIN PASSWORD 'app'`)
+	// Idempotent across tests AND runs: the role persists for the TestMain PG and
+	// owns granted privileges, so a plain DROP ROLE fails once any GRANT exists
+	// (and more than one test now builds an app pool). Create only if absent; the
+	// GRANTs below are themselves idempotent.
+	_, err := super.Exec(ctx,
+		`DO $$ BEGIN
+		    IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'app') THEN
+		        CREATE ROLE app LOGIN PASSWORD 'app';
+		    END IF;
+		 END $$`)
 	require.NoError(t, err)
 	_, err = super.Exec(ctx, `GRANT USAGE ON SCHEMA public TO app`)
 	require.NoError(t, err)
@@ -182,13 +191,14 @@ func TestRLSEnforcesPerUserIsolation(t *testing.T) {
 		{"update users", `UPDATE users SET display_name = 'hacked' WHERE id = $1`, b.userID},
 		{"update videos", `UPDATE videos SET title = 'hacked' WHERE user_id = $1`, b.userID},
 		{"queue videos summarize", `UPDATE videos SET summarize_requested = TRUE WHERE id = $1`, b.videoID},
-		{"update transcripts", `UPDATE transcripts SET content = 'hacked' WHERE user_id = $1`, b.userID},
 		{"update summaries", `UPDATE summaries SET summary = 'hacked' WHERE user_id = $1`, b.userID},
 		{"update summary_actions", `UPDATE summary_actions SET action = 'skipped' WHERE user_id = $1`, b.userID},
+		{"update login_events", `UPDATE login_events SET seen_at = NOW() WHERE user_id = $1`, b.userID},
 		{"update sink_deliveries", `UPDATE sink_deliveries SET status = 'hacked' WHERE summary_id = $1`, b.summaryID},
 		{"update video_connections", `UPDATE video_connections SET token_ref = 'hacked' WHERE user_id = $1`, b.userID},
 		{"delete summaries", `DELETE FROM summaries WHERE user_id = $1`, b.userID},
 		{"delete summary_actions", `DELETE FROM summary_actions WHERE user_id = $1`, b.userID},
+		{"delete login_events", `DELETE FROM login_events WHERE user_id = $1`, b.userID},
 		{"delete sink_deliveries", `DELETE FROM sink_deliveries WHERE summary_id = $1`, b.summaryID},
 		{"delete video_connections", `DELETE FROM video_connections WHERE user_id = $1`, b.userID},
 	}
@@ -205,17 +215,20 @@ func TestRLSEnforcesPerUserIsolation(t *testing.T) {
 		`SELECT summary FROM summaries WHERE user_id = $1`, b.userID).Scan(&bSummary))
 	require.Equal(t, "sum", bSummary, "B's summary must be untouched by A's writes")
 
-	var bSummaries, bActions, bDeliveries, bConnections int
+	var bSummaries, bActions, bLogins, bDeliveries, bConnections int
 	require.NoError(t, super.QueryRow(ctx,
 		`SELECT count(*) FROM summaries WHERE user_id = $1`, b.userID).Scan(&bSummaries))
 	require.NoError(t, super.QueryRow(ctx,
 		`SELECT count(*) FROM summary_actions WHERE user_id = $1`, b.userID).Scan(&bActions))
+	require.NoError(t, super.QueryRow(ctx,
+		`SELECT count(*) FROM login_events WHERE user_id = $1`, b.userID).Scan(&bLogins))
 	require.NoError(t, super.QueryRow(ctx,
 		fmt.Sprintf(`SELECT count(*) FROM sink_deliveries WHERE summary_id = '%s'`, b.summaryID)).Scan(&bDeliveries))
 	require.NoError(t, super.QueryRow(ctx,
 		`SELECT count(*) FROM video_connections WHERE user_id = $1 AND token_ref <> 'hacked'`, b.userID).Scan(&bConnections))
 	require.Equal(t, 1, bSummaries, "A's DELETE must not have removed B's summary")
 	require.Equal(t, 1, bActions, "A's DELETE must not have removed B's action")
+	require.Equal(t, 1, bLogins, "A's DELETE must not have removed B's login event")
 	require.Equal(t, 1, bDeliveries, "A's DELETE must not have removed B's delivery")
 	require.Equal(t, 1, bConnections, "A's writes must not have touched B's connection")
 
@@ -226,3 +239,55 @@ func TestRLSEnforcesPerUserIsolation(t *testing.T) {
 
 	_ = a // a's ids are seeded for the symmetric read assertions above
 }
+
+// TestTranscriptsTableIsSharedNotRLS is the ADR-021 isolation proof: transcripts
+// is the ONE shared, non-RLS surface, and the public-content classification
+// leaked to nothing else. It is the inverse of TestRLSEnforcesPerUserIsolation —
+// where that asserts deny-all on every user-owned table, this asserts transcripts
+// is readable and writable with no user scope at all, holds no user_id, and is
+// the single table with row-level security switched off.
+func TestTranscriptsTableIsSharedNotRLS(t *testing.T) {
+	newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	app := appPool(t, super)
+	ctx := context.Background()
+
+	// 1. Shared + non-RLS: with NO GUC set, the app role both writes and reads a
+	//    transcript. On an RLS table this would be deny-all (zero rows), exactly as
+	//    the main isolation test asserts for every user-owned table.
+	_, err := app.Exec(ctx,
+		`INSERT INTO transcripts (provider, provider_video_id, source, content)
+		 VALUES ('youtube', 'shared-vid', 'captions', 'public words')`)
+	require.NoError(t, err, "app role must write shared transcript content with no user scope")
+	require.Equal(t, 1, scopedCount(t, app, "", "transcripts"),
+		"transcripts must be readable with NO user scope — it is shared, non-RLS (ADR-021)")
+
+	// 2. No user_id column: the table holds only public caption content + the
+	//    video's public id, nothing user-identifying.
+	var hasUserID bool
+	require.NoError(t, super.QueryRow(ctx,
+		`SELECT EXISTS (SELECT 1 FROM information_schema.columns
+		                 WHERE table_name = 'transcripts' AND column_name = 'user_id')`).Scan(&hasUserID))
+	require.False(t, hasUserID, "transcripts must carry no user_id (ADR-021 public content)")
+
+	// 3. The boundary is EXACTLY here: every user-owned table still has row-level
+	//    security enabled; transcripts alone has it off. This is the proof the
+	//    non-RLS classification was applied to transcripts and leaked nowhere else.
+	for _, table := range allIsolatedTables {
+		require.True(t, rlsEnabled(t, super, table),
+			"%s must still enforce row-level security — isolation must not have regressed", table)
+	}
+	require.False(t, rlsEnabled(t, super, "transcripts"),
+		"transcripts must be the single table with row-level security OFF (the one shared surface)")
+}
+
+// rlsEnabled reports whether a public table has ROW LEVEL SECURITY enabled.
+func rlsEnabled(t *testing.T, p *pgxpool.Pool, table string) bool {
+	t.Helper()
+	var enabled bool
+	require.NoError(t, p.QueryRow(context.Background(),
+		`SELECT relrowsecurity FROM pg_class
+		  WHERE relname = $1 AND relnamespace = 'public'::regnamespace`, table).Scan(&enabled))
+	return enabled
+}

internal/adapters/store/store.go

@@ -24,7 +24,7 @@ import (
 
 	_ "github.com/jackc/pgx/v5/stdlib" // register the "pgx" database/sql driver for migrate
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 //go:embed migrations/*.sql

internal/adapters/store/store_test.go

@@ -4,15 +4,16 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"path/filepath"
 	"testing"
 
 	embeddedpostgres "github.com/fergusstrange/embedded-postgres"
 	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/ports"
 )
 
 // Static check: Store satisfies the Sink port.
@@ -24,11 +25,22 @@ var _ ports.Sink = (*store.Store)(nil)
 var dsn string
 
 func TestMain(m *testing.M) {
-	const port = 54329
+	// Port + runtime/data dirs are per-process (PID-derived) so two concurrent
+	// `go test` invocations — e.g. a push-run and a tag-run firing together in CI —
+	// don't collide on a fixed port or a shared data dir (which silently failed
+	// both runs). CachePath is shared so the PG archive is downloaded once, not
+	// per process. Base 54000 keeps this package's range distinct from web's.
+	port := uint32(54000 + os.Getpid()%1000)
 	dsn = fmt.Sprintf("postgres://postgres:postgres@localhost:%d/postgres?sslmode=disable", port)
 
+	rt := filepath.Join(os.TempDir(), fmt.Sprintf("tapir-epg-store-%d", os.Getpid()))
 	pg := embeddedpostgres.NewDatabase(
-		embeddedpostgres.DefaultConfig().Port(port),
+		embeddedpostgres.DefaultConfig().
+			Port(port).
+			RuntimePath(rt).
+			DataPath(filepath.Join(rt, "data")).
+			BinariesPath(filepath.Join(rt, "bin")).
+			CachePath(filepath.Join(os.TempDir(), "tapir-epg-cache")),
 	)
 	if err := pg.Start(); err != nil {
 		fmt.Fprintf(os.Stderr, "embedded-postgres start: %v\n", err)
@@ -40,6 +52,7 @@ func TestMain(m *testing.M) {
 	if err := pg.Stop(); err != nil {
 		fmt.Fprintf(os.Stderr, "embedded-postgres stop: %v\n", err)
 	}
+	_ = os.RemoveAll(rt)
 	os.Exit(code)
 }
 
@@ -74,7 +87,7 @@ func rawPool(t *testing.T) *pgxpool.Pool {
 func resetDB(t *testing.T, p *pgxpool.Pool) {
 	t.Helper()
 	_, err := p.Exec(context.Background(),
-		`TRUNCATE summary_actions, sink_deliveries, summaries, transcripts, videos, users CASCADE`)
+		`TRUNCATE login_events, summary_actions, sink_deliveries, summaries, transcripts, videos, users CASCADE`)
 	require.NoError(t, err)
 }
 

internal/adapters/store/summarize_mode_test.go

@@ -3,11 +3,12 @@ package store_test
 import (
 	"context"
 	"testing"
+	"time"
 
 	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // seedBareVideo inserts a videos row with no summary, so the all-videos read and
@@ -45,6 +46,27 @@ func TestAutoSummarizeRoundTripDefaultsFalse(t *testing.T) {
 	require.False(t, got, "set back to manual round-trips")
 }
 
+func TestRegisteredUserDefaultsAutoSummarizeOn(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+
+	// A real registration creates the users row, so the column default (migration
+	// 011: TRUE) drives the mode — onboarded friends get auto out of the box.
+	id, err := s.RegisterUser(ctx, subjectA, "Alice")
+	require.NoError(t, err)
+
+	got, err := s.GetAutoSummarize(ctx, id)
+	require.NoError(t, err)
+	require.True(t, got, "new registrations default to auto-summarize (ADR-018)")
+
+	// The account-page toggle still works: a user can switch to manual.
+	require.NoError(t, s.SetAutoSummarize(ctx, id, false))
+	got, err = s.GetAutoSummarize(ctx, id)
+	require.NoError(t, err)
+	require.False(t, got, "the manual toggle still flips it off")
+}
+
 func TestRequestSummarizeSetsFlag(t *testing.T) {
 	ctx := context.Background()
 	s := newStore(t)
@@ -104,6 +126,39 @@ func TestListVideosReturnsSummarizedAndUnsummarized(t *testing.T) {
 	require.True(t, byID[videoY].SummarizeRequested, "queued video carries the flag")
 }
 
+// TestListVideosOrderedByPublishedDescNullsLast: summarized videos sort first
+// (regardless of their date), then unsummarized by published_at DESC with
+// undated (NULL) videos last — the recency-aligned list order (UX review B2).
+func TestListVideosOrderedByPublishedDescNullsLast(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	p := rawPool(t)
+	resetDB(t, p)
+
+	const (
+		vSummOld = "cccccccc-cccc-cccc-cccc-cccccccccccc" // summarized, oldest date
+		vNewer   = "dddddddd-dddd-dddd-dddd-dddddddddddd" // unsummarized, newest
+		vOlder   = "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee" // unsummarized, older
+		vUndated = "ffffffff-ffff-ffff-ffff-ffffffffffff" // unsummarized, no date
+	)
+	// Deliver first so the userA row exists (the videos FK needs it); the
+	// summarized video carries the OLDEST date yet must still sort first because
+	// it is summarized, proving summarized-first dominates the date sort.
+	require.NoError(t, s.Deliver(ctx, summary(userA, vSummOld, "body")))
+	seedVideo(t, p, userA, vSummOld, "Summarized Old", "youtube", "https://s", time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC))
+	seedVideo(t, p, userA, vNewer, "Newer", "youtube", "https://n", time.Date(2026, 3, 1, 0, 0, 0, 0, time.UTC))
+	seedVideo(t, p, userA, vOlder, "Older", "youtube", "https://o", time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC))
+	seedVideo(t, p, userA, vUndated, "Undated", "youtube", "https://u", time.Time{})
+
+	rows, err := s.ListVideos(ctx, userA, 50)
+	require.NoError(t, err)
+	require.Len(t, rows, 4)
+
+	got := []string{rows[0].VideoID, rows[1].VideoID, rows[2].VideoID, rows[3].VideoID}
+	require.Equal(t, []string{vSummOld, vNewer, vOlder, vUndated}, got,
+		"summarized first, then published_at DESC, NULL dates last")
+}
+
 func TestListVideosIsUserScoped(t *testing.T) {
 	ctx := context.Background()
 	s := newStore(t)

internal/adapters/store/transcript.go

@@ -0,0 +1,66 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.d-ma.be/mathias/tapir/internal/domain"
+)
+
+// GetTranscript returns the shared, stored transcript for a video keyed by the
+// cross-user dedup key (provider, providerVideoID), and whether one exists
+// (ADR-021). It reads via the raw pool, NOT withUser: the table holds public
+// content with no user_id and no RLS policy, so it is shared across users by
+// construction. A stored SourceNone is a real hit (ok == true, HasText() ==
+// false) — a known caption-less video, so the caller skips without re-fetching.
+func (s *Store) GetTranscript(ctx context.Context, provider, providerVideoID string) (domain.Transcript, bool, error) {
+	var source, lang, content string
+	err := s.pool.QueryRow(ctx,
+		`SELECT source, COALESCE(language, ''), COALESCE(content, '')
+		   FROM transcripts WHERE provider = $1 AND provider_video_id = $2`,
+		provider, providerVideoID).Scan(&source, &lang, &content)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return domain.Transcript{}, false, nil
+	}
+	if err != nil {
+		return domain.Transcript{}, false, fmt.Errorf("store: get transcript: %w", err)
+	}
+	return domain.Transcript{
+		Source:   domain.TranscriptSource(source),
+		Language: lang,
+		Content:  content,
+	}, true, nil
+}
+
+// SaveTranscript upserts the shared transcript for (provider, providerVideoID).
+// Only terminal outcomes belong here: SourceCaptions (with text) or SourceNone
+// (no captions). A transient SourceRateLimited is rejected so persistence never
+// masks a 429 as a permanent absence — that stays a per-user retry (ADR-014).
+// Last write wins on conflict (a later re-fetch may correct an entry). It writes
+// via the raw pool, NOT withUser — public content, shared, non-RLS (ADR-021).
+func (s *Store) SaveTranscript(ctx context.Context, provider, providerVideoID string, t domain.Transcript) error {
+	switch t.Source {
+	case domain.SourceCaptions, domain.SourceNone:
+		// terminal — persist
+	case domain.SourceRateLimited:
+		return fmt.Errorf("store: refusing to persist transient rate-limited transcript for %s/%s", provider, providerVideoID)
+	default:
+		return fmt.Errorf("store: invalid transcript source %q", t.Source)
+	}
+	_, err := s.pool.Exec(ctx,
+		`INSERT INTO transcripts (provider, provider_video_id, source, language, content)
+		      VALUES ($1, $2, $3, NULLIF($4, ''), NULLIF($5, ''))
+		 ON CONFLICT (provider, provider_video_id)
+		 DO UPDATE SET source     = EXCLUDED.source,
+		               language   = EXCLUDED.language,
+		               content    = EXCLUDED.content,
+		               fetched_at = NOW()`,
+		provider, providerVideoID, string(t.Source), t.Language, t.Content)
+	if err != nil {
+		return fmt.Errorf("store: save transcript: %w", err)
+	}
+	return nil
+}

internal/adapters/store/transcript_status_test.go

@@ -6,7 +6,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 func TestSetTranscriptStatus_RoundTrip(t *testing.T) {

internal/adapters/store/transcript_test.go

@@ -0,0 +1,87 @@
+package store_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/ports"
+)
+
+// Static check: Store satisfies the shared TranscriptStore port (ADR-021).
+var _ ports.TranscriptStore = (*store.Store)(nil)
+
+func TestSaveAndGetTranscript_RoundTrip(t *testing.T) {
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+	ctx := context.Background()
+
+	want := domain.Transcript{Source: domain.SourceCaptions, Language: "en", Content: "the words"}
+	require.NoError(t, s.SaveTranscript(ctx, "youtube", "vid-1", want))
+
+	got, ok, err := s.GetTranscript(ctx, "youtube", "vid-1")
+	require.NoError(t, err)
+	require.True(t, ok, "a saved transcript must be found")
+	require.Equal(t, domain.SourceCaptions, got.Source)
+	require.Equal(t, "en", got.Language)
+	require.Equal(t, "the words", got.Content)
+	require.True(t, got.HasText())
+}
+
+func TestGetTranscript_Miss(t *testing.T) {
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+
+	_, ok, err := s.GetTranscript(context.Background(), "youtube", "absent")
+	require.NoError(t, err, "a miss is not an error")
+	require.False(t, ok)
+}
+
+// A stored "no captions" outcome is a real hit: callers must skip without
+// re-fetching, so ok is true even though there is no text (ADR-021 / ADR-007).
+func TestSaveAndGetTranscript_NoneIsAStoredHit(t *testing.T) {
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+	ctx := context.Background()
+
+	require.NoError(t, s.SaveTranscript(ctx, "youtube", "vid-none", domain.Transcript{Source: domain.SourceNone}))
+
+	got, ok, err := s.GetTranscript(ctx, "youtube", "vid-none")
+	require.NoError(t, err)
+	require.True(t, ok, "a stored SourceNone is a hit, not a miss")
+	require.Equal(t, domain.SourceNone, got.Source)
+	require.False(t, got.HasText())
+}
+
+// A transient 429 must never be persisted as a terminal transcript, or a later
+// read would mask the rate-limit as a permanent "no transcript" (ADR-014).
+func TestSaveTranscript_RejectsRateLimited(t *testing.T) {
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+
+	err := s.SaveTranscript(context.Background(), "youtube", "vid-429",
+		domain.Transcript{Source: domain.SourceRateLimited})
+	require.Error(t, err)
+
+	_, ok, _ := s.GetTranscript(context.Background(), "youtube", "vid-429")
+	require.False(t, ok, "a rejected rate-limited save must leave nothing stored")
+}
+
+func TestSaveTranscript_UpsertLastWriteWins(t *testing.T) {
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+	ctx := context.Background()
+
+	require.NoError(t, s.SaveTranscript(ctx, "youtube", "vid-up", domain.Transcript{Source: domain.SourceNone}))
+	require.NoError(t, s.SaveTranscript(ctx, "youtube", "vid-up",
+		domain.Transcript{Source: domain.SourceCaptions, Language: "en", Content: "now resolved"}))
+
+	got, ok, err := s.GetTranscript(ctx, "youtube", "vid-up")
+	require.NoError(t, err)
+	require.True(t, ok)
+	require.Equal(t, domain.SourceCaptions, got.Source)
+	require.Equal(t, "now resolved", got.Content)
+}

internal/adapters/store/videos.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/jackc/pgx/v5"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 // UpsertVideo persists a video's metadata and returns its durable store id (the
@@ -46,14 +46,16 @@ func (s *Store) UpsertVideo(ctx context.Context, v domain.Video) (string, error)
 		}
 
 		if err := tx.QueryRow(ctx,
-			`INSERT INTO videos (user_id, provider, provider_video_id, title, url, published_at)
-			 VALUES ($1, $2, $3, $4, $5, $6)
+			`INSERT INTO videos (user_id, provider, provider_video_id, title, url, published_at, channel_title, duration_s)
+			 VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
 			 ON CONFLICT (user_id, provider, provider_video_id) DO UPDATE SET
-			     title        = EXCLUDED.title,
-			     url          = EXCLUDED.url,
-			     published_at = EXCLUDED.published_at
+			     title         = EXCLUDED.title,
+			     url           = EXCLUDED.url,
+			     published_at  = EXCLUDED.published_at,
+			     channel_title = COALESCE(NULLIF(EXCLUDED.channel_title, ''), videos.channel_title),
+			     duration_s    = COALESCE(EXCLUDED.duration_s, videos.duration_s)
 			 RETURNING id`,
-			v.UserID, provider, v.ProviderVideoID, v.Title, v.URL, nullTime(v.PublishedAt),
+			v.UserID, provider, v.ProviderVideoID, v.Title, v.URL, nullTime(v.PublishedAt), v.ChannelTitle, nullDuration(v.DurationSeconds),
 		).Scan(&id); err != nil {
 			return fmt.Errorf("store: upsert video: %w", err)
 		}
@@ -72,3 +74,89 @@ func nullTime(t time.Time) *time.Time {
 	}
 	return &t
 }
+
+// nullDuration maps an unknown duration (0) to SQL NULL so the upsert's
+// COALESCE(EXCLUDED.duration_s, videos.duration_s) preserves a previously-known
+// value instead of clobbering it with 0 (ADR-028; the channel_title backfill
+// stance, migration 014).
+func nullDuration(seconds int) *int {
+	if seconds <= 0 {
+		return nil
+	}
+	return &seconds
+}
+
+// OnboardBurstVideoIDs returns up to limit of the user's unsummarized videos for
+// the connect-time onboarding burst (ADR-028), newest-first but quality-aware: a
+// video is excluded when its duration is KNOWN and outside [minSeconds, maxSeconds]
+// — dropping Shorts (below min) and multi-hour livestream VODs (above max) that
+// would waste a scarce caption fetch on a poor first impression. A NULL/unknown
+// duration is kept (degrade-open) but ranked AFTER known-good rows, so a freshly
+// enriched good pick wins when both exist. minSeconds<=0 / maxSeconds<=0 each
+// disable that bound (0/0 == pure newest-first, the reversibility lever).
+// RLS-scoped via withUser; limit <= 0 returns nil.
+func (s *Store) OnboardBurstVideoIDs(ctx context.Context, userID string, limit, minSeconds, maxSeconds int) ([]string, error) {
+	if limit <= 0 {
+		return nil, nil
+	}
+	var ids []string
+	if err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		rows, err := tx.Query(ctx,
+			`SELECT v.id
+			   FROM videos v
+			  WHERE v.user_id = $1
+			    AND NOT EXISTS (
+			          SELECT 1 FROM summaries su
+			           WHERE su.user_id = v.user_id AND su.video_id = v.id)
+			    AND NOT (
+			          v.duration_s IS NOT NULL
+			          AND ( ($3 > 0 AND v.duration_s < $3)
+			             OR ($4 > 0 AND v.duration_s > $4) ))
+			  ORDER BY (v.duration_s IS NOT NULL) DESC,
+			           v.published_at DESC NULLS LAST, v.seen_at DESC
+			  LIMIT $2`, userID, limit, minSeconds, maxSeconds)
+		if err != nil {
+			return fmt.Errorf("store: onboard burst videos: %w", err)
+		}
+		defer rows.Close()
+		for rows.Next() {
+			var id string
+			if err := rows.Scan(&id); err != nil {
+				return fmt.Errorf("store: scan onboard burst video: %w", err)
+			}
+			ids = append(ids, id)
+		}
+		return rows.Err()
+	}); err != nil {
+		return nil, err
+	}
+	return ids, nil
+}
+
+// DistinctChannels returns the user's distinct, non-empty source channel titles
+// (the channels they have videos from), alphabetically — the option list for the
+// feed's channel filter. RLS-scoped via withUser.
+func (s *Store) DistinctChannels(ctx context.Context, userID string) ([]string, error) {
+	var out []string
+	if err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		rows, err := tx.Query(ctx,
+			`SELECT DISTINCT channel_title FROM videos
+			  WHERE user_id = $1 AND channel_title IS NOT NULL AND channel_title <> ''
+			  ORDER BY channel_title`, userID)
+		if err != nil {
+			return fmt.Errorf("store: distinct channels: %w", err)
+		}
+		defer rows.Close()
+		for rows.Next() {
+			var c string
+			if err := rows.Scan(&c); err != nil {
+				return fmt.Errorf("store: scan channel: %w", err)
+			}
+			out = append(out, c)
+		}
+		return rows.Err()
+	}); err != nil {
+		return nil, err
+	}
+	return out, nil
+}

internal/adapters/store/videos_test.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 func ytVideo(userID, provVideoID, title string) domain.Video {
@@ -52,6 +52,36 @@ func TestUpsertVideo_ReturnsStableID(t *testing.T) {
 	require.Equal(t, 1, count, "must not duplicate the row")
 }
 
+func TestUpsertVideo_PersistsAndPreservesDuration(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+
+	// First upsert carries a known duration (ADR-028: discovery enriches it).
+	v := ytVideo(userA, "dur0000001x", "with duration")
+	v.DurationSeconds = 750
+	id, err := s.UpsertVideo(ctx, v)
+	require.NoError(t, err)
+
+	p := rawPool(t)
+	readDuration := func() *int {
+		var d *int
+		require.NoError(t, p.QueryRow(ctx, `SELECT duration_s FROM videos WHERE id = $1`, id).Scan(&d))
+		return d
+	}
+	require.NotNil(t, readDuration())
+	require.Equal(t, 750, *readDuration(), "duration must persist")
+
+	// A later upsert that does NOT know the duration (0) must not clobber it —
+	// the channel_title backfill stance (migration 014): COALESCE-preserve.
+	v2 := ytVideo(userA, "dur0000001x", "title updated, duration unknown")
+	v2.DurationSeconds = 0
+	_, err = s.UpsertVideo(ctx, v2)
+	require.NoError(t, err)
+	require.NotNil(t, readDuration(), "a 0/unknown re-upsert must not erase a known duration")
+	require.Equal(t, 750, *readDuration())
+}
+
 func TestUpsertVideo_IDMatchesSummaryDedup(t *testing.T) {
 	ctx := context.Background()
 	s := newStore(t)
@@ -81,3 +111,80 @@ func TestUpsertVideo_PerUserIsolation(t *testing.T) {
 
 	require.NotEqual(t, idA, idB, "same provider video for two users must be two distinct rows")
 }
+
+func TestOnboardBurstVideoIDs(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+
+	mk := func(user, pid string, day, dur int) string {
+		v := ytVideo(user, pid, pid)
+		v.PublishedAt = time.Date(2026, 6, day, 12, 0, 0, 0, time.UTC)
+		v.DurationSeconds = dur // 0 == unknown (NULL)
+		id, err := s.UpsertVideo(ctx, v)
+		require.NoError(t, err)
+		return id
+	}
+
+	summarized := mk(userA, "summ0000001", 6, 600) // newest known-good, but already summarized
+	good1 := mk(userA, "good0000001", 5, 600)      // 10m, newest UNsummarized known-good
+	tooLong := mk(userA, "toolong0001", 4, 20000)  // > maxSeconds -> dropped
+	tooShort := mk(userA, "tooshort001", 3, 30)    // < minSeconds -> dropped
+	unknown := mk(userA, "unknown0001", 2, 0)      // NULL duration -> kept, ranked last
+	good2 := mk(userA, "good0000002", 1, 800)      // known-good but oldest
+	mk(userB, "bvid0000009", 9, 600)               // userB -> must not leak via RLS
+
+	// The newest video is summarized, so it is excluded from the burst.
+	require.NoError(t, s.Deliver(ctx, summary(userA, summarized, "done")))
+
+	const minSec, maxSec = 60, 14400
+
+	// Known-good ranked before unknown, each newest-first within its group; the
+	// too-long and too-short videos are excluded by their known duration.
+	got, err := s.OnboardBurstVideoIDs(ctx, userA, 5, minSec, maxSec)
+	require.NoError(t, err)
+	require.Equal(t, []string{good1, good2, unknown}, got,
+		"known-good first (newest-first), then unknown-duration; junk excluded")
+
+	// Cap is honoured.
+	capped, err := s.OnboardBurstVideoIDs(ctx, userA, 2, minSec, maxSec)
+	require.NoError(t, err)
+	require.Equal(t, []string{good1, good2}, capped)
+
+	// Bounds disabled (0/0) == pure newest-first, nothing excluded.
+	all, err := s.OnboardBurstVideoIDs(ctx, userA, 10, 0, 0)
+	require.NoError(t, err)
+	require.ElementsMatch(t, []string{good1, tooLong, tooShort, unknown, good2}, all,
+		"0/0 bounds disable the duration filter (prior newest-first behaviour)")
+
+	// limit <= 0 returns nothing.
+	none, err := s.OnboardBurstVideoIDs(ctx, userA, 0, minSec, maxSec)
+	require.NoError(t, err)
+	require.Empty(t, none)
+}
+
+func TestUpsertVideoPersistsChannelAndDistinctChannels(t *testing.T) {
+	ctx := context.Background()
+	s := newStore(t)
+	resetDB(t, rawPool(t))
+
+	mk := func(pid, channel string) {
+		v := ytVideo(userA, pid, pid)
+		v.ChannelTitle = channel
+		_, err := s.UpsertVideo(ctx, v)
+		require.NoError(t, err)
+	}
+	mk("aa11111aaaa", "Acme Talks")
+	mk("bb22222bbbb", "Acme Talks") // same channel
+	mk("cc33333cccc", "Zeta Channel")
+	// userB's channel must not leak.
+	vb := ytVideo(userB, "dd44444dddd", "x")
+	vb.ChannelTitle = "Bravo Only"
+	_, err := s.UpsertVideo(ctx, vb)
+	require.NoError(t, err)
+
+	got, err := s.DistinctChannels(ctx, userA)
+	require.NoError(t, err)
+	require.Equal(t, []string{"Acme Talks", "Zeta Channel"}, got,
+		"distinct, alphabetical, user-scoped (no Bravo Only)")
+}

internal/adapters/summarizer/summarizer.go

@@ -1,19 +1,25 @@
 // Package summarizer implements ports.Summarizer backed by the copied llm
-// package's local-Primary -> BYO-Fallback routing (ADR-004). It is the only
-// place content ever leaves the engine toward an AI model, so it is also the
-// enforcement point for the local-first guarantee in
-// docs/use-cases/ai_routing.feature: a user with no BYO provider configured has
-// their content sent to the local stack and nowhere else.
+// package's routing (ADR-004, extended by ADR-022). It is the only place content
+// ever leaves the engine toward an AI model, so it is also the enforcement point
+// for the local-first guarantee in docs/use-cases/ai_routing.feature: endpoints
+// are tried in order, locals first, so content only reaches an external model
+// after every local endpoint has failed — and never at all when no external
+// endpoint is configured.
 package summarizer
 
 import (
+	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
+	"log/slog"
 	"strings"
 	"time"
+	"unicode/utf8"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/metrics"
 )
 
 // Completer is the minimal LLM chat surface the Summarizer needs.
@@ -29,19 +35,41 @@ type Endpoint struct {
 	Model    string // resolved alias, e.g. "iguana/deepseek-r1-14b"
 }
 
-// Summarizer routes a transcript through the local endpoint first, then the
-// optional BYO endpoint. It owns its routing (rather than delegating to
-// llm.Router) so it can record which provider answered and whether the fallback
-// was used — information llm.Router collapses away.
+// Summarizer routes a transcript through an ordered chain of endpoints, trying
+// each in turn until one returns a parseable summary. It owns its routing
+// (rather than delegating to llm.Router) so it can record which provider answered
+// and whether a fallback was used — information llm.Router collapses away. The
+// chain ordering is the local-first guarantee: callers place local endpoints
+// first and any external endpoint last, so content only reaches an external model
+// after every local endpoint has failed.
 type Summarizer struct {
-	primary  Endpoint
-	fallback *Endpoint // nil => no BYO; primary errors are returned, never sent externally
-	now      func() time.Time
+	endpoints     []Endpoint
+	maxInputChars int // transcript truncation budget; 0 = no limit
+	now           func() time.Time
 }
 
-// New constructs a Summarizer. fallback may be nil (no BYO provider configured).
+// New constructs a Summarizer from a primary endpoint and an optional fallback
+// (the historical local-Primary -> BYO-Fallback shape, ADR-004). A nil fallback
+// means a single-endpoint chain: errors are returned, content never leaves it.
 func New(primary Endpoint, fallback *Endpoint) *Summarizer {
-	return &Summarizer{primary: primary, fallback: fallback, now: time.Now}
+	eps := []Endpoint{primary}
+	if fallback != nil {
+		eps = append(eps, *fallback)
+	}
+	return &Summarizer{endpoints: eps, now: time.Now}
+}
+
+// NewChain constructs a Summarizer over an ordered endpoint chain (ADR-022).
+// endpoints are tried in order; the first to return a parseable summary wins, and
+// FallbackUsed is recorded true for any endpoint past the first. maxInputChars
+// bounds the transcript text sent to every endpoint (0 = unbounded), so a long
+// transcript does not overflow a small-context primary model's window. It panics
+// on an empty chain — a wiring bug, not a runtime condition.
+func NewChain(endpoints []Endpoint, maxInputChars int) *Summarizer {
+	if len(endpoints) == 0 {
+		panic("summarizer: NewChain requires at least one endpoint")
+	}
+	return &Summarizer{endpoints: endpoints, maxInputChars: maxInputChars, now: time.Now}
 }
 
 const systemPrompt = `You are Tapir, a video-summarization assistant.
@@ -53,31 +81,42 @@ Respond with ONLY a JSON object, no prose and no code fences:
 - "takeaways": the actionable conclusions a viewer should leave with.
 Output the JSON object and nothing else.`
 
-// Summarize implements ports.Summarizer.
+// Summarize implements ports.Summarizer. It walks the endpoint chain in order:
+// the first endpoint whose reply parses into a non-empty summary wins. An
+// endpoint is considered failed — and the next one tried — when the model call
+// errors OR when its reply cannot be parsed (a 200 with malformed JSON or a
+// highlights field the model emitted as a bare string). Truncation is applied
+// once, up front, so every endpoint sees the same bounded prompt. When the whole
+// chain fails, the joined error is returned so the engine queues the work for
+// retry and delivers no summary.
 func (s *Summarizer) Summarize(ctx context.Context, v domain.Video, t domain.Transcript) (domain.Summary, error) {
 	if !t.HasText() {
 		return domain.Summary{}, fmt.Errorf("summarize: transcript for video %s has no text", v.ID)
 	}
-	user := buildUserPrompt(v, t)
+	user := buildUserPrompt(v, t, s.maxInputChars)
 
-	// Primary = local stack. Only on its failure is anything sent externally,
-	// and only when a BYO fallback is configured.
-	out, err := s.primary.Client.Complete(ctx, systemPrompt, user)
-	if err == nil {
-		return s.build(v, s.primary, false, out)
+	var errs []error
+	for i, ep := range s.endpoints {
+		fallback := i > 0
+		start := time.Now()
+		out, err := ep.Client.Complete(ctx, systemPrompt, user)
+		dur := time.Since(start)
+		if err != nil {
+			metrics.ObserveSummarize(ep.Model, "error", fallback, dur)
+			errs = append(errs, fmt.Errorf("%s/%s call: %w", ep.Provider, ep.Model, err))
+			continue
+		}
+		sum, perr := s.build(v, ep, fallback, out)
+		if perr != nil {
+			metrics.ObserveSummarize(ep.Model, "parse_error", fallback, dur)
+			errs = append(errs, fmt.Errorf("%s/%s output: %w", ep.Provider, ep.Model, perr))
+			continue
+		}
+		metrics.ObserveSummarize(ep.Model, "success", fallback, dur)
+		slog.Default().Info("summarized", "model", ep.Model, "fallback", fallback, "elapsed_ms", dur.Milliseconds())
+		return sum, nil
 	}
-
-	if s.fallback == nil {
-		// No BYO: content was sent to the local stack only. Surface the error so
-		// the engine can queue the work for retry; deliver no summary.
-		return domain.Summary{}, fmt.Errorf("summarize: local AI failed and no BYO provider configured: %w", err)
-	}
-
-	out, ferr := s.fallback.Client.Complete(ctx, systemPrompt, user)
-	if ferr != nil {
-		return domain.Summary{}, fmt.Errorf("summarize: local AI failed: %w; BYO %s failed: %v", err, s.fallback.Provider, ferr)
-	}
-	return s.build(v, *s.fallback, true, out)
+	return domain.Summary{}, fmt.Errorf("summarize: all %d endpoint(s) failed: %w", len(s.endpoints), errors.Join(errs...))
 }
 
 func (s *Summarizer) build(v domain.Video, ep Endpoint, fallbackUsed bool, raw string) (domain.Summary, error) {
@@ -89,8 +128,8 @@ func (s *Summarizer) build(v domain.Video, ep Endpoint, fallbackUsed bool, raw s
 		UserID:       v.UserID,
 		VideoID:      v.ID,
 		Summary:      parsed.Summary,
-		Highlights:   parsed.Highlights,
-		Takeaways:    parsed.Takeaways,
+		Highlights:   []string(parsed.Highlights),
+		Takeaways:    []string(parsed.Takeaways),
 		AIProvider:   ep.Provider,
 		AIModel:      ep.Model,
 		FallbackUsed: fallbackUsed,
@@ -98,20 +137,94 @@ func (s *Summarizer) build(v domain.Video, ep Endpoint, fallbackUsed bool, raw s
 	}, nil
 }
 
-func buildUserPrompt(v domain.Video, t domain.Transcript) string {
+func buildUserPrompt(v domain.Video, t domain.Transcript, maxInputChars int) string {
 	var b strings.Builder
 	fmt.Fprintf(&b, "Title: %s\n", v.Title)
 	if v.URL != "" {
 		fmt.Fprintf(&b, "URL: %s\n", v.URL)
 	}
-	fmt.Fprintf(&b, "\nTranscript:\n%s", t.Content)
+	fmt.Fprintf(&b, "\nTranscript:\n%s", truncate(t.Content, maxInputChars))
 	return b.String()
 }
 
+// truncate caps content to max bytes on a UTF-8 rune boundary, appending a
+// marker so the model knows the transcript was cut. A non-positive max (or a
+// content already within budget) returns content unchanged. Bounding the input
+// keeps a long transcript from overflowing a small-context model's window — the
+// production failure mode where koala/phi4-mini's 8k context returned HTTP 400 on
+// a 11.6k-token transcript.
+func truncate(content string, max int) string {
+	if max <= 0 || len(content) <= max {
+		return content
+	}
+	cut := max
+	for cut > 0 && !utf8.RuneStart(content[cut]) {
+		cut--
+	}
+	return content[:cut] + "\n…[transcript truncated to fit the model context]"
+}
+
+// flexStrings is a []string that also unmarshals from a single JSON string or a
+// JSON array of scalars. Small local models (koala/phi4-mini) sometimes emit
+// "highlights": "one point" instead of an array, or mix in a number; rather than
+// fail the whole summary on that quirk, coerce to []string. Empty/whitespace
+// elements are dropped.
+type flexStrings []string
+
+func (f *flexStrings) UnmarshalJSON(b []byte) error {
+	b = bytes.TrimSpace(b)
+	if len(b) == 0 || string(b) == "null" {
+		*f = nil
+		return nil
+	}
+	if b[0] == '[' {
+		var raw []json.RawMessage
+		if err := json.Unmarshal(b, &raw); err != nil {
+			return err
+		}
+		out := make([]string, 0, len(raw))
+		for _, r := range raw {
+			s, err := rawToString(r)
+			if err != nil {
+				return err
+			}
+			if strings.TrimSpace(s) != "" {
+				out = append(out, s)
+			}
+		}
+		*f = out
+		return nil
+	}
+	s, err := rawToString(b)
+	if err != nil {
+		return err
+	}
+	if strings.TrimSpace(s) == "" {
+		*f = nil
+	} else {
+		*f = flexStrings{s}
+	}
+	return nil
+}
+
+// rawToString renders a JSON scalar as text: a quoted string is unquoted; any
+// other scalar (number, bool) is kept as its literal source so no content is lost.
+func rawToString(r json.RawMessage) (string, error) {
+	r = bytes.TrimSpace(r)
+	if len(r) > 0 && r[0] == '"' {
+		var s string
+		if err := json.Unmarshal(r, &s); err != nil {
+			return "", err
+		}
+		return s, nil
+	}
+	return string(r), nil
+}
+
 type parsedSummary struct {
-	Summary    string   `json:"summary"`
-	Highlights []string `json:"highlights"`
-	Takeaways  []string `json:"takeaways"`
+	Summary    string      `json:"summary"`
+	Highlights flexStrings `json:"highlights"`
+	Takeaways  flexStrings `json:"takeaways"`
 }
 
 // parse extracts the JSON object from a model reply. Thinking models (qwen3,

internal/adapters/summarizer/summarizer_test.go

@@ -7,13 +7,36 @@ package summarizer
 import (
 	"context"
 	"errors"
+	"net/http"
+	"net/http/httptest"
 	"strings"
 	"testing"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/metrics"
+	"git.d-ma.be/mathias/tapir/internal/ports"
 )
 
+// TestSummarizerRecordsMetric verifies the summarizer→metrics wiring (ADR-030)
+// black-box: after a successful summarize, the public /metrics scrape shows a
+// success observation for that endpoint's model.
+func TestSummarizerRecordsMetric(t *testing.T) {
+	const model = "metrics-test-model"
+	s := New(Endpoint{Client: &fakeClient{reply: goodReply}, Provider: "local", Model: model}, nil)
+	if _, err := s.Summarize(context.Background(), testVideo(), testTranscript()); err != nil {
+		t.Fatalf("Summarize: %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	metrics.Handler().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	body := rec.Body.String()
+	if !strings.Contains(body, `tapir_summarize_duration_seconds`) ||
+		!strings.Contains(body, `model="`+model+`"`) ||
+		!strings.Contains(body, `outcome="success"`) {
+		t.Errorf("metrics scrape missing summarize success for %s", model)
+	}
+}
+
 // compile-time check: Summarizer satisfies the port.
 var _ ports.Summarizer = (*Summarizer)(nil)
 
@@ -129,8 +152,8 @@ func TestSummarize_NoBYO_ContentOnlyLocal(t *testing.T) {
 	local := &fakeClient{reply: goodReply}
 	s := New(Endpoint{Client: local, Provider: "local", Model: "iguana/deepseek-r1-14b"}, nil)
 
-	if s.fallback != nil {
-		t.Fatal("no BYO configured but fallback endpoint is non-nil")
+	if len(s.endpoints) != 1 {
+		t.Fatalf("no BYO configured but chain has %d endpoints, want 1", len(s.endpoints))
 	}
 	for i := 0; i < 3; i++ {
 		sum, err := s.Summarize(context.Background(), testVideo(), testTranscript())
@@ -176,3 +199,97 @@ func TestParse_EmptySummaryRejected(t *testing.T) {
 		t.Fatal("want error for empty summary (thinking model returned no content)")
 	}
 }
+
+// parse tolerates a small model emitting "highlights" as a bare string instead
+// of an array — the production koala/phi4-mini quirk that errored with
+// "cannot unmarshal string into Go struct field ... highlights of type []string".
+func TestParse_ToleratesStringHighlights(t *testing.T) {
+	p, err := parse(`{"summary":"s","highlights":"one big point","takeaways":["a","b"]}`)
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	if len(p.Highlights) != 1 || p.Highlights[0] != "one big point" {
+		t.Errorf("highlights = %v, want [\"one big point\"]", p.Highlights)
+	}
+	if len(p.Takeaways) != 2 {
+		t.Errorf("takeaways = %v, want 2", p.Takeaways)
+	}
+}
+
+// Chain: an endpoint that returns a 200 with unparseable output is treated as a
+// failure, and the next endpoint in the chain is tried. This is the case the old
+// primary->fallback shape missed — a parse error short-circuited instead of
+// falling back.
+func TestSummarize_FallsBackOnMalformedOutput(t *testing.T) {
+	bad := &fakeClient{reply: `{"summary": not json`}
+	good := &fakeClient{reply: goodReply}
+	s := NewChain([]Endpoint{
+		{Client: bad, Provider: "local", Model: "koala/phi4-mini"},
+		{Client: good, Provider: "local", Model: "koala/phi4-14b"},
+	}, 0)
+
+	sum, err := s.Summarize(context.Background(), testVideo(), testTranscript())
+	if err != nil {
+		t.Fatalf("Summarize: %v", err)
+	}
+	if sum.AIModel != "koala/phi4-14b" {
+		t.Errorf("AIModel = %q, want koala/phi4-14b (fell back past malformed primary)", sum.AIModel)
+	}
+	if !sum.FallbackUsed {
+		t.Error("FallbackUsed = false, want true")
+	}
+	if bad.calls != 1 || good.calls != 1 {
+		t.Errorf("calls: bad=%d good=%d, want 1 and 1", bad.calls, good.calls)
+	}
+}
+
+// Chain: when every endpoint fails, no summary is produced and the joined error
+// names each failure so the engine queues the work for retry.
+func TestSummarize_ChainAllEndpointsFail(t *testing.T) {
+	a := &fakeClient{err: errors.New("context overflow")}
+	b := &fakeClient{reply: "not even json"}
+	s := NewChain([]Endpoint{
+		{Client: a, Provider: "local", Model: "m1"},
+		{Client: b, Provider: "berget", Model: "m2"},
+	}, 0)
+
+	if _, err := s.Summarize(context.Background(), testVideo(), testTranscript()); err == nil {
+		t.Fatal("want error when all endpoints fail")
+	}
+	if a.calls != 1 || b.calls != 1 {
+		t.Errorf("calls: a=%d b=%d, want 1 and 1", a.calls, b.calls)
+	}
+}
+
+// A transcript longer than the chain's input budget is truncated before it
+// reaches any model, so a small-context primary does not overflow its window.
+func TestSummarize_TruncatesLongTranscript(t *testing.T) {
+	local := &fakeClient{reply: goodReply}
+	const budget = 100
+	s := NewChain([]Endpoint{{Client: local, Provider: "local", Model: "m"}}, budget)
+
+	long := domain.Transcript{
+		VideoID: "vid-1", UserID: "user-1", Source: domain.SourceCaptions,
+		Content: strings.Repeat("word ", 1000), // 5000 bytes, well over budget
+	}
+	if _, err := s.Summarize(context.Background(), testVideo(), long); err != nil {
+		t.Fatalf("Summarize: %v", err)
+	}
+	// The prompt carries title/URL framing plus the truncation marker, so allow
+	// headroom over the raw transcript budget — but it must be far below 5000.
+	if len(local.lastUser) > budget+300 {
+		t.Errorf("prompt length = %d, want <= %d (transcript not truncated)", len(local.lastUser), budget+300)
+	}
+	if !strings.Contains(local.lastUser, "truncated") {
+		t.Error("truncation marker missing from prompt")
+	}
+}
+
+func TestNewChain_PanicsOnEmptyChain(t *testing.T) {
+	defer func() {
+		if recover() == nil {
+			t.Fatal("want panic on empty endpoint chain")
+		}
+	}()
+	NewChain(nil, 0)
+}