test(audio): opt-in live ffprobe check on hostile playlists and real audio

Skipped unless TAPIR_LIVE_FFPROBE is set. Synthetic/crafted files only.

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

.gitea/build-image.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# Build an OCI image with buildctl and push it to the local registry.
+#
+# CANONICAL COPY: mathias/infra ci-templates/build-image.sh (infra#309).
+# Every repo carries a byte-identical copy at .gitea/build-image.sh, written by
+# `task ci:sync` and held in place by the drift gate. DO NOT EDIT THE COPIES --
+# edit here, re-sync, and the gate will tell you which repos still disagree.
+#
+# Why this exists: this step was hand-copied into a dozen repos, so migrating it
+# off rootless buildah (infra#241) meant eleven near-identical commits, eleven
+# verifications, and three separate rediscoveries of the same fix in the two
+# repo templates and the gitea-ci skill. The differences between the copies were
+# incidental -- a label here, a build-arg there -- never intentional. Those are
+# inputs now, not forks of the implementation.
+#
+# Why buildctl and not buildah: the gitea-runner pod runs with
+# `capabilities: drop [ALL]` and `allowPrivilegeEscalation: false`, which
+# unconditionally blocks the setuid-root exec that rootless buildah's uid/gid
+# remapping needs, and the pod has no OCI runtime at all. buildctl is a thin
+# client -- it hands the build to the host's buildkitd over a socket, so the
+# privileged layer work happens on the host and this pod's securityContext is
+# not in the picture. buildah is absent from the runner image as of baked-v14
+# and its absence is asserted at pod start (infra#308).
+#
+# Inputs, all via environment:
+#
+#   IMAGE            (required) image name, e.g. cobalt-dingo
+#   REGISTRY         default localhost:5000
+#   SHA_TAG          default `git rev-parse --short HEAD`
+#   VERSION_TAG      optional extra tag, e.g. v1.2.3 on a tag build
+#   PUSH_LATEST      default 1; set 0 to skip the :latest tag
+#   CONTEXT          default . -- build context directory
+#   DOCKERFILE_DIR   default $CONTEXT -- directory holding the Dockerfile
+#   DOCKERFILE_NAME  optional, when the file is not named `Dockerfile`
+#   TARGET           optional, multi-stage build target (--opt target=)
+#   BUILD_ARGS       optional, space-separated K=V pairs
+#   BUILD_SECRETS    optional, space-separated buildkit secret specs, each
+#                    `id=NAME,src=PATH`. Pass the SPEC only -- the caller
+#                    writes the secret to PATH itself. A secret VALUE must
+#                    never be passed here: it would land in this script's
+#                    argv and therefore in the CI log.
+#   EXTRA_LABELS     optional, space-separated K=V pairs
+#   GIT_SHA          optional, stamped as org.opencontainers.image.revision
+#   IMAGE_SOURCE     optional, stamped as org.opencontainers.image.source
+#
+# Note on shell style below: every conditional is a full `if` block, never
+# `[ -n "$X" ] && cmd`. Under `set -e` the && form exits the script whenever the
+# test is false, which is a real bug this estate has already shipped once.
+
+set -euo pipefail
+
+if [ -z "${IMAGE:-}" ]; then
+  echo "build-image: IMAGE is required" >&2
+  exit 2
+fi
+
+REGISTRY="${REGISTRY:-localhost:5000}"
+BUILDKIT_HOST="${BUILDKIT_HOST:-unix:///run/buildkit/buildkitd.sock}"
+CONTEXT="${CONTEXT:-.}"
+DOCKERFILE_DIR="${DOCKERFILE_DIR:-$CONTEXT}"
+PUSH_LATEST="${PUSH_LATEST:-1}"
+VERSION_TAG="${VERSION_TAG:-}"
+
+if [ -z "${SHA_TAG:-}" ]; then
+  SHA_TAG="$(git rev-parse --short HEAD)"
+fi
+
+REF="${REGISTRY}/${IMAGE}:${SHA_TAG}"
+
+TAR_FILE="$(mktemp)"
+trap 'rm -f "$TAR_FILE"' EXIT
+
+args=(
+  --frontend dockerfile.v0
+  --local "context=${CONTEXT}"
+  --local "dockerfile=${DOCKERFILE_DIR}"
+)
+
+if [ -n "${DOCKERFILE_NAME:-}" ]; then
+  args+=(--opt "filename=${DOCKERFILE_NAME}")
+fi
+if [ -n "${TARGET:-}" ]; then
+  args+=(--opt "target=${TARGET}")
+fi
+for spec in ${BUILD_SECRETS:-}; do
+  # Opaque id=NAME,src=PATH -- buildkit reads the file, nothing is echoed.
+  args+=(--secret "${spec}")
+done
+if [ -n "${GIT_SHA:-}" ]; then
+  args+=(--opt "label:org.opencontainers.image.revision=${GIT_SHA}")
+fi
+if [ -n "${IMAGE_SOURCE:-}" ]; then
+  args+=(--opt "label:org.opencontainers.image.source=${IMAGE_SOURCE}")
+fi
+for kv in ${BUILD_ARGS:-}; do
+  args+=(--opt "build-arg:${kv}")
+done
+for kv in ${EXTRA_LABELS:-}; do
+  args+=(--opt "label:${kv}")
+done
+
+echo "build-image: building ${REF}"
+buildctl --addr "$BUILDKIT_HOST" build "${args[@]}" --output "type=oci,dest=${TAR_FILE}"
+
+# buildctl has no registry-push equivalent to `buildah push`, so skopeo copies
+# the OCI archive up -- once per tag, from the same archive, so every tag points
+# at bit-identical content.
+push_tag() {
+  echo "build-image: pushing ${1}"
+  skopeo copy --dest-tls-verify=false "oci-archive:${TAR_FILE}" "docker://${1}"
+}
+
+push_tag "$REF"
+if [ "$PUSH_LATEST" = "1" ]; then
+  push_tag "${REGISTRY}/${IMAGE}:latest"
+fi
+if [ -n "$VERSION_TAG" ]; then
+  push_tag "${REGISTRY}/${IMAGE}:${VERSION_TAG}"
+fi
+
+echo "✓ build-image: ${REF} pushed"

.gitea/workflows/ci.yml

@@ -61,33 +61,163 @@ jobs:
             echo "version-tag=${REF#refs/tags/}" >> "$GITHUB_OUTPUT"
           fi
 
+      # infra#241: rootless buildah inside the gitea-runner pod can't remap the
+      # UID/GID range newuidmap/newgidmap need (the pod drops ALL capabilities
+      # and sets allowPrivilegeEscalation:false — both deliberate, it also holds
+      # CI secrets), so extracting a base-image layer that chowns outside the
+      # single available mapping fails with `ApplyLayer ... requested 0:42 for
+      # /etc/gshadow`. Main has been red on exactly this since 2026-08-13.
+      # buildctl instead talks to koala's host buildkitd over the socket the
+      # runner pod already mounts: the privileged extraction happens inside
+      # buildkitd on the host, never in this pod. Same migration agentsquad
+      # (infra#233) and segment-embedder (infra#243) already made — zero
+      # security tradeoff, unlike loosening the pod's capabilities.
+      #
+      # buildctl has no registry-push flag of its own: it writes an OCI archive
+      # and skopeo pushes that, which is also why every tag below is one copy of
+      # a single build rather than a rebuild.
       - name: Build and push to local registry
-        run: |
-          REGISTRY="localhost:5000"
-          REF="${REGISTRY}/${{ env.IMAGE }}:${{ steps.meta.outputs.sha-tag }}"
-          buildah build \
-            --label "org.opencontainers.image.revision=${{ github.sha }}" \
-            --label "org.opencontainers.image.source=${{ github.repositoryUrl }}" \
-            -t ${REF} \
-            -t ${REGISTRY}/${{ env.IMAGE }}:latest \
-            .
-          buildah push --tls-verify=false ${REF}
-          buildah push --tls-verify=false ${REGISTRY}/${{ env.IMAGE }}:latest
-          [[ -n "${{ steps.meta.outputs.version-tag }}" ]] && \
-            buildah push --tls-verify=false \
-              ${REGISTRY}/${{ env.IMAGE }}:${{ steps.meta.outputs.version-tag }} || true
-          echo "Image pushed to ${REF}"
+      # infra#309: implementation lives in .gitea/build-image.sh, a
+      # byte-identical copy of mathias/infra's ci-templates/build-image.sh.
+      # Do not edit it here -- edit the canonical file, run `task ci:sync`,
+      # and infra's drift gate names any repo still carrying an old copy.
+        env:
+          SHA_TAG: ${{ steps.meta.outputs.sha-tag }}
+          VERSION_TAG: ${{ steps.meta.outputs.version-tag }}
+          GIT_SHA: ${{ github.sha }}
+          IMAGE_SOURCE: ${{ github.repositoryUrl }}
+        run: bash .gitea/build-image.sh
 
-      - 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
-          echo "$OUTPUT" | grep -q "tapir" \
-            && echo "Smoke test passed" \
-            || echo "Smoke test inconclusive: $OUTPUT"
+      # The buildah-based smoke test that used to sit here is gone with the
+      # buildctl migration above: `buildah from ${REF}` would pull the image
+      # back into the pod's buildah store and hit the very uid/gid wall the
+      # migration exists to avoid — it would fail the job for a reason that has
+      # nothing to do with the image being good. The `Verify rollout` step in
+      # the deploy job below is the stronger check anyway: it requires the real
+      # pod to reach Ready in-cluster, not just the entrypoint to print its own
+      # name for 5s. Tag builds lose their only image-level check (deploy is
+      # main-push only) — accepted; a tag is always built from a main commit
+      # that already deployed.
 
-  # ── 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#311: fail on an empty tag BEFORE patching anything. The
+          # grep verification further down CANNOT catch it -- with IMAGE_TAG
+          # empty its pattern matches the very corruption it exists to reject.
+          # The result is `image: <repo>:` in the manifest, which is invalid
+          # YAML, so Flux fails the ENTIRE apps Kustomization and every app
+          # stops reconciling, not just this one. That happened on 2026-08-25.
+          [ -n "${IMAGE_TAG:-}" ] || { echo "IMAGE_TAG is empty - refusing to patch"; exit 1; }
+
+          # 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
 
@@ -49,8 +50,11 @@ These caused real mistakes that were caught and corrected; the corrections are l
 - **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 YouTube audio-download + speech-to-text in the core path** — captions-first (ADR-007).
+  That rejection stands. ADR-033 superseded the STT deferral **for user-supplied audio only**:
+  an authenticated user may upload a recording and get a *private* transcript (own RLS table,
+  never the shared `transcripts`). It is off by default (`TAPIR_UPLOADS_ENABLED`) and does not
+  open the door to scraping audio.
 - **No public SaaS / sign-up / billing / Google OAuth verification at scale** — Future C,
   deferred behind the Stage 0 gate (ADR-008).
 
@@ -96,7 +100,7 @@ The repo is **green and shipping** — last tag `v0.15.0`. `task check` passes (
 - Adapters present under `internal/adapters/`: `youtube` (captions-first `VideoSource`,
   timedtext/InnerTube acquisition per ADR-010), `summarizer` + `llm` (the copied AI router,
   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),
+  parse-failure-aware, ADR-004 + ADR-022), `store` (Postgres, golang-migrate migrations 001–017),
   `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
@@ -108,6 +112,12 @@ The repo is **green and shipping** — last tag `v0.15.0`. `task check` passes (
   (`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.
+- Audio upload (ADR-033, migration 017): `internal/uploads` (validation by **probing**, intake,
+  one-at-a-time in-process worker), `internal/adapters/audio` (ffprobe/ffmpeg), and
+  `internal/adapters/transcribe` (gateway client + iguana→berget chain). Transcripts are private
+  in `uploaded_transcripts`; the audio is never retained; chat reuses `chat.Service`. The
+  isolation test pins the **exact set** of non-RLS tables (`TestRowSecurityOffTablesAreExactlyTheKnownSet`).
+  The runtime image does not yet contain ffmpeg — that is a pending decision recorded in ADR-033.
 - `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

@@ -123,7 +123,9 @@ secret surface (see VISION Stage 2); it gets the existing, vetted secret path.
 ## ADR-007 — Captions-first; audio-download + speech-to-text deferred
 
 **Status:** Accepted (2026-06-02). Acquisition mechanism superseded by ADR-010 (Data API
-`captions.download` → player/timedtext baseUrl); captions-first stance and STT deferral stand.
+`captions.download` → player/timedtext baseUrl); captions-first stance and STT deferral stand
+**for YouTube**. STT deferral superseded **for user-supplied audio only** by ADR-033; the
+YouTube audio-download rejection is unchanged.
 
 **Context.** YouTube's Data API does not expose transcripts. Options: official captions
 (clean, limited coverage) vs. audio download + local Whisper (broad coverage, ToS-grey,
@@ -827,10 +829,18 @@ 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) → `koala/phi4-14b` (fallback, local) →
-   `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.
+   `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.
@@ -891,6 +901,624 @@ this is well under the 10k/day cap; at larger scale, batch `videos.list` across
 
 ---
 
+## 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.
+
+---
+
+## ADR-033 — Upload audio, get a private Swedish transcript, discuss it (user-supplied STT)
+
+**Status:** Proposed (2026-10-01). **Decider: Mathias — pending.** Issue #33 (audio-only subset of
+#28). **Supersedes ADR-007's speech-to-text deferral for user-supplied audio only.** The
+YouTube audio-download rejection in ADR-007 **stands untouched**. Builds on ADR-012 (isolation),
+ADR-018 (single replica), ADR-021 (**the constraint**), ADR-022 (endpoint chain), ADR-025
+(honest status), ADR-027 (chat). ADR-014 item 4 ("Whisper reconsideration is a future ADR,
+gated on caption data") is a different question — whether to transcribe YouTube videos with no
+captions — and this ADR does not answer it. Measurements: `docs/research/audio-length-ceiling-2026-10-01.md`.
+
+**Context.** The maintainer has a concrete need: a Swedish Teams voice-only export, 30–90
+minutes, to upload and then *discuss* (what was decided, what is open, who owes what). Every
+piece exists — a Whisper endpoint on the gateway (infra#274), chat-with-transcript (ADR-027) —
+and nothing connects them.
+
+ADR-007 deferred STT for three reasons: yt-dlp fragility, ToS-grey scraping, and GPU contention
+with the JEPA PoC. Upload-STT shares **none** of them: the user owns the file, nothing is
+scraped, there is no caption rate gate, and the contention moved from koala to iguana. What it
+does share is landing Whisper in the codebase, which ADR-007 deferred — so a new ADR is required,
+and ADR-017's process note records the one time a guardrail-reversing change shipped without one.
+
+**The constraint that shapes everything.** ADR-021 made `transcripts` a shared, **non-RLS**
+table on the explicit grounds that it holds only public caption content and nothing
+user-identifying. A recorded internal meeting is the opposite: private third-party content owned
+by one user. The existing isolation test asserts `transcripts` *is* non-RLS, so a naive reuse
+would leak across tenants **and pass CI green**.
+
+**What was measured, not argued** (research doc above):
+- **No transcription ceiling up to 90 minutes.** One 174 MB request through the LiteLLM NodePort
+  took 440 s (~12× realtime). The first failure is the public ingress `llm-api.d-ma.be`
+  returning `413` above roughly 8–10 MB (~5 min of WAV) — not whisper, and not a Metal OOM.
+  The 8:20 failure recorded in #33 is consistent with that cap.
+- **`response_format=srt` survives LiteLLM, wrapped** in a JSON envelope (`{"text": "<srt>"}`).
+- **The two backends differ.** `iguana/kb-whisper` returns whole-second segments;
+  `berget/kb-whisper` returns sub-second times and a different `language` token.
+- **The existing chat path truncates at 18,000 chars (~22 min of speech), keeping the head.**
+  #33 assumed chat "retrieves rather than generates" and so has no length ceiling. It does
+  not retrieve; it stuffs the transcript into the prompt and cuts the tail. Measured against
+  the offered models: `phi4-mini` 400s at ~13k tokens; `gemma4-26b` is right to 90,000 chars and
+  silently drops the head at 120,000.
+
+**Unknowns, stated.** Real-speech accuracy; compressed-input behaviour; concurrent long jobs on
+iguana; and the Metal OOM, deliberately not provoked. (Whether the offered chat models can hold
+an hour of Swedish *was* an unknown here; it is now measured, see decision 8.)
+
+**Decision.**
+
+1. **Audio only; transcript is the only thing kept.** An authenticated user uploads an audio
+   file; Tapir transcribes it and stores the transcript. The audio itself is deleted after
+   transcription (temp file, removed in a `defer`, swept at start-up) — no custody problem to
+   solve, and nothing to hand to #31. Video is rejected with a message naming #28. YouTube
+   audio-download stays rejected. No public/anonymous upload (ADR-008).
+
+2. **Private store: a separate RLS-scoped table, `uploaded_transcripts`** (resolves #28's
+   decision 1). `user_id NOT NULL REFERENCES users ON DELETE CASCADE`, `ENABLE` + `FORCE ROW LEVEL
+   SECURITY`, the same `tapir.current_user_id` policy as every other user-owned table. It carries
+   the transcript text and its timestamped segments (re-transcribing 90 minutes costs ~7
+   minutes; discarding the timestamps is irreversible), `status`, the `endpoint` that served
+   it, `audio_seconds`, and a typed `error_kind`. **Not** a `user_id` column on `transcripts`
+   with a partial policy, even though that would reuse more code: ADR-021's exception is
+   precisely that *that table holds no private row*, the isolation test asserts it has no
+   `user_id`, and a partial policy would turn "single exception" into "single exception, with a
+   private lane inside it" — the shape under which a future query drops the policy clause and
+   leaks. Two tables keep both boundaries independently assertable.
+
+3. **The isolation test asserts both boundaries and the set.** (a) User A cannot read, update or
+   delete user B's uploaded transcript; no GUC set → deny-all. (b) `transcripts` is still
+   non-RLS with no `user_id`. (c) **The set of public-schema tables with row security off is
+   asserted exactly** — so a new table added without RLS fails CI instead of passing it. (c) is
+   new; the existing test only checks the named tables.
+
+4. **Validate by probing, reject clearly.** Format and duration cannot be read from a filename
+   or MIME type — a Teams "voice-only" recording is typically an `.mp4` container with no video
+   stream, which is indistinguishable from video by extension. The upload is probed
+   (`ffprobe`): accept any container with an audio stream and **no** video stream; reject video
+   with "video is #28"; reject unreadable files. Limits, all configurable, all rejected
+   synchronously with a specific message rather than by timeout: **200 MB** upload and
+   **90 minutes** duration. 90 minutes is *the longest length measured*, not a ceiling that was
+   found; raising it is a measurement, not an edit.
+
+5. **Transcode server-side, always, to 16 kHz mono PCM WAV** — even when the input already is,
+   rather than assuming. whisper-server's `--convert` is rejected (its `--tmp-dir` is created at
+   process start and rots under macOS periodic cleanup). The transcoder sits behind a port; the
+   tests use a fake. **This puts `ffmpeg` and `ffprobe` in the runtime image**, which is
+   distroless-static today. **Provisional: copy static ffmpeg/ffprobe binaries into the existing
+   distroless image** (no shell, no package manager retained). This is a heavy new dependency
+   and is **the maintainer's call** — see Open items.
+
+6. **Transcription adapter via the gateway, never the public hostname.** A `Transcriber` port;
+   the implementation calls `POST {TAPIR_GATEWAY_URL}/audio/transcriptions` where the gateway
+   URL is the in-cluster NodePort (`koala:30401/v1`). Primary `iguana/kb-whisper`, fallback
+   `berget/kb-whisper` (immune to iguana contention, which can wedge permanently — infra#273).
+   - **Fallback triggers on any primary failure** (transport error, timeout, non-2xx). It never
+     branches on the body: `{"error":"failed to process audio"}` has had at least five distinct
+     causes.
+   - **`response_format=verbose_json`**, normalised to one segment shape: times clamped to the
+     audio duration (the final segment can end past it), one language token. Not `srt`: the
+     envelope adds a parse step and iguana's segment timing is the same either way.
+   - **No chunking in v1.** Nothing failed to 90 minutes (measured). Chunk-and-stitch is the
+     answer *if* the cap is raised or smaller requests become necessary — see triggers.
+   - **The serving endpoint is recorded per row**, and surfaced, because the two backends
+     differ in timestamp granularity: which one served a transcript is a quality fact.
+   - **Berget is a cloud endpoint.** On fallback the audio of a private meeting leaves the
+     homelab. #33 asks for this fallback; it is configurable (`TAPIR_TRANSCRIBE_FALLBACK_MODEL`,
+     empty disables), recorded per row, and called out in Open items rather than defaulted
+     silently.
+   - Swedish only (`language=sv`). Language detection and routing (#28 decision 2) are not
+     touched.
+   - `-H 'Expect:'`, multipart field `file` — encoded in the adapter and its tests, not rediscovered.
+
+7. **Jobs run in-process, one at a time (ADR-018 stands).** Transcription is minutes (~7.5 min
+   for 90) but a single goroutine behind a one-slot semaphore: two simultaneous 90-minute jobs on
+   iguana were not measured, so concurrency is 1 until they are. No worker, no new deployable,
+   no second replica. Honest status per ADR-025: `queued → transcribing → done | failed`, polled
+   by the same `/status` pattern, every terminal state a rendered card, never a stuck spinner.
+   Audio is not retained, so a restart mid-job **cannot resume**: at start-up any
+   `queued`/`transcribing` row is marked `failed` with `error_kind = interrupted`, and the user
+   re-uploads. The single-replica assumption gains a second dependent (the semaphore is
+   process-local) and is recorded here.
+
+8. **Chat reuses `chat.Service`; it is not forked.** The uploaded-transcript chat handlers
+   look the row up through the RLS-scoped store, so a non-owner gets 404 by the same mechanism
+   as ADR-027's summary gate, **before any model is called**. ADR-027's decisions (ephemeral,
+   switchable models, trust-the-model) carry over unchanged. **Two things must differ, and both
+   were measured** (`docs/research/chat-context-over-long-transcripts-2026-10-01.md`):
+   - **The transcript budget.** The 18,000-char caption default cuts a one-hour meeting to its
+     first third. Uploaded transcripts take their own `TAPIR_MAX_UPLOADED_TRANSCRIPT_CHARS`,
+     default **90,000** — the measured ceiling of the best offered model (`iguana/gemma4-26b`),
+     which answers correctly there but **silently loses the head of a 120,000-char transcript**
+     with no error and no truncation flag. (An earlier draft of this ADR proposed 120,000 as a
+     guess; the measurement refuted it.) The mechanism is a per-request `chat.Request.MaxChars`.
+   - **The opening model.** The offered list leads with the summarizer default `koala/phi4-mini`,
+     whose 8,192-token context returns HTTP 400 on an hour of speech (~13,000 tokens). Chat over
+     an upload opens on `TAPIR_UPLOAD_CHAT_MODEL` (default `iguana/gemma4-26b`); the switcher
+     still lists every model, and picking `phi4-mini` on a long recording fails loudly and
+     inline. A per-model budget is not built.
+   Past ~90,000 chars (≈100 minutes) no offered model can answer by stuffing; see triggers.
+
+9. **Not decided here.** Rich `AVSNITT`/`ALTERNATIV` analysis (gated on #30 — `analyze_srt.py`
+   hardcodes `max_tokens: 6000`); video, keyframes, synced playback (#28); language detection;
+   per-transcript deletion UX (account deletion cascades; see Open items); retention of audio.
+
+**On the sequencing question #28 asks of itself** — *is this the thing that best serves the
+Stage-0 gate, or the most interesting thing to build?* Recorded answer: it proceeds **ahead of
+#32** (the demand test) as the maintainer's explicit, knowing call (#28, comment of 2026-10-01),
+on a concrete need rather than speculation. It is not a return-nudge (ADR-020/027): it adds
+nothing that prompts a user to come back, so it does not contaminate the unprompted-return signal
+ADR-016 measures. The honest risk is the one ADR-016 names: it is larger than anything ADR-020
+deferred. The scope cut — chat first, no rich analysis, no video — is what keeps it bounded.
+
+**Consequences.**
+- **Positive.** The user's request is met end to end with existing parts. ADR-021's exception stays
+  singular and now provably so. The measured ceiling removes chunking from v1. No audio is stored.
+- **Negative / watch.**
+  - Tapir's runtime image gains `ffmpeg`: a larger image and a new CVE surface to patch.
+  - iguana becomes load-bearing for a user-facing feature (#28 decision 3; infra#273 is still the
+    dependency that matters) — a Metal OOM now means *every upload fails over to berget*, i.e.
+    private audio leaving the homelab, silently unless the per-row endpoint is surfaced.
+  - A 90-minute job holds the single slot for ~7.5 minutes; a second user's upload queues behind it.
+  - Chat over a long transcript is bounded by model context, not by anything in Tapir, and the
+    failure at the edge is *silent* for gemma (the head is dropped, no error). The 90,000 default
+    sits just inside the measured limit and is only as good as that single measurement.
+  - **The default chat model for uploads is a large ollama model on iguana — the same host as
+    `iguana/kb-whisper`.** infra#273 is exactly that a large resident ollama model can Metal-OOM
+    whisper-server permanently. Chatting with a transcript can therefore load the model that
+    wedges the transcriber. Not solved here; the berget fallback limits the blast radius.
+  - Tapir's own ingress body limit for a 200 MB upload is **unverified** (it lives in `infra`).
+
+**Validation / resolution triggers** (each observable by someone other than the author):
+- *Chunking*: build it when the duration cap is raised above 90 min, or when a measured
+  request at the current cap fails with whisper-side (not ingress) errors.
+- *Berget-first*: if more than a quarter of uploads in any week are served by the fallback,
+  swap the primary/fallback order and revisit infra#273.
+- *Retrieval chat*: build chunked retrieval when a recording's transcript exceeds the measured
+  90,000-char ceiling (≈100 minutes) — i.e. the moment the duration cap is raised above that, or a
+  real recording turns out denser than the fixture — or when the offered model list changes and
+  the ceiling is re-measured lower.
+- *Worker*: if a transcription job ever degrades the reading UI, or Tapir runs more than one
+  replica, ADR-018 is revisited.
+- *The decision itself*: if the maintainer has not used the feature unprompted within the
+  ADR-016 window, it was the interesting thing, not the useful one — remove it.
+
+**Open items this ADR creates.**
+- **DECISION NEEDED — ffmpeg in the runtime image.** *Options:* (A) static ffmpeg/ffprobe copied
+  into distroless **(recommended — the only option that satisfies "accept m4a/mp3/opus/mp4,
+  validate duration, reject video"; pure-Go decoders cover wav/mp3 only)**; (B) accept WAV
+  only, convert client-side (fails "I just want to upload it"); (C) a transcode sidecar
+  (second deployable, ADR-018's reasoning against). *Blocks:* the Dockerfile slice, not the
+  tests, which use the port.
+- **DECISION NEEDED — berget fallback for private audio.** *Options:* (A) enabled by default as
+  #33 specifies, with the serving endpoint shown **(recommended, matches the issue)**; (B)
+  disabled by default, a failed iguana job fails honestly and the user retries. *Blocks:*
+  the production default only; the adapter ships either way.
+- Verify Tapir's ingress `proxy-body-size` against the 200 MB cap (`infra`).
+- Per-transcript deletion is not built; account deletion cascades. A private-content store
+  without a delete button is a gap worth a ticket, not a silent omission.
+
+**Reversibility.** Additive: one table (down-migration drops it), one adapter, one upload
+surface, one image change. Removing the upload route removes the feature; `transcripts`, `videos`
+and ADR-021 are untouched.
+
+---
+
 ## Rejected alternatives
 
 Approaches considered during the 2026-06-02 planning + grill session and **deliberately not
@@ -914,6 +1542,10 @@ maps to the ADR that settles it.
 | 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 |
+| Uploaded transcripts as a `user_id` column + partial RLS policy on `transcripts` | Turns ADR-021's single exception into an exception with a private lane inside it; the isolation test asserts `transcripts` has no `user_id`. A separate RLS table keeps both boundaries independently assertable | ADR-033 |
+| whisper-server `--convert` for server-side transcode | Its `--tmp-dir` is created at process start and rots under macOS periodic cleanup | ADR-033 |
+| Calling the public `llm-api.d-ma.be` from in-cluster Tapir | Its ingress returns 413 above ~8–10 MB (~5 min of WAV); the NodePort has no such cap | ADR-033 |
 
 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`

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

@@ -5,7 +5,7 @@ import (
 	"log/slog"
 	"sync"
 
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
+	"git.d-ma.be/mathias/tapir/internal/runner"
 )
 
 // discoveryRunner runs one user's discovery pass.

cmd/tapir/discovery_test.go

@@ -10,7 +10,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
+	"git.d-ma.be/mathias/tapir/internal/runner"
 )
 
 // serialize must guarantee at most one discovery pass runs at a time, so a

cmd/tapir/e2e_upload_test.go

@@ -0,0 +1,170 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	embeddedpostgres "github.com/fergusstrange/embedded-postgres"
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/web"
+)
+
+// TestE2E_UploadTranscribeAndChat is the end-to-end check for tapir#33: upload a
+// real audio file, watch it become a transcript through the REAL ffprobe, ffmpeg
+// and gateway, then ask a question and get a grounded answer from a REAL model.
+// It is opt-in — it needs real binaries and the live gateway — and skipped unless
+// TAPIR_E2E_AUDIO is set:
+//
+//	TAPIR_E2E_AUDIO=/path/meeting.m4a TAPIR_E2E_FFMPEG=/path/ffmpeg \
+//	TAPIR_E2E_FFPROBE=/path/ffprobe TAPIR_E2E_QUESTION='Vem ansvarar för virket?' \
+//	TAPIR_E2E_EXPECT=anders op run --env-file ~/.op-env -- \
+//	  go test ./cmd/tapir -run E2E_Upload -v -count=1
+//
+// Use SYNTHETIC audio only: this repo is public, and a fallback to berget sends
+// the audio to a cloud endpoint (#33).
+func TestE2E_UploadTranscribeAndChat(t *testing.T) {
+	audioPath := os.Getenv("TAPIR_E2E_AUDIO")
+	if audioPath == "" {
+		t.Skip("set TAPIR_E2E_AUDIO (and friends) to run the live end-to-end check")
+	}
+	key := os.Getenv("LITELLM_MASTER_KEY")
+	require.NotEmpty(t, key, "LITELLM_MASTER_KEY must be set (via op run)")
+	ctx, cancel := context.WithCancel(context.Background())
+	t.Cleanup(cancel)
+
+	// A private embedded Postgres: nothing here may touch a real database.
+	port := uint32(55000 + os.Getpid()%1000)
+	rt := filepath.Join(os.TempDir(), fmt.Sprintf("tapir-epg-e2e-%d", os.Getpid()))
+	pg := embeddedpostgres.NewDatabase(embeddedpostgres.DefaultConfig().Port(port).
+		RuntimePath(rt).DataPath(filepath.Join(rt, "data")).BinariesPath(filepath.Join(rt, "bin")).
+		CachePath(filepath.Join(os.TempDir(), "tapir-epg-cache")))
+	require.NoError(t, pg.Start())
+	t.Cleanup(func() { _ = pg.Stop(); _ = os.RemoveAll(rt) })
+	dsn := fmt.Sprintf("postgres://postgres:postgres@localhost:%d/postgres?sslmode=disable", port)
+
+	st, err := store.New(ctx, dsn)
+	require.NoError(t, err)
+	t.Cleanup(st.Close)
+	raw, err := pgxpool.New(ctx, dsn)
+	require.NoError(t, err)
+	t.Cleanup(raw.Close)
+	const uid = "11111111-1111-1111-1111-111111111111"
+	_, err = raw.Exec(ctx, `INSERT INTO users (id) VALUES ($1)`, uid)
+	require.NoError(t, err)
+	_, err = raw.Exec(ctx, `INSERT INTO user_identities (dex_subject, user_id) VALUES ('e2e', $1)`, uid)
+	require.NoError(t, err)
+
+	cfg, err := config.Load()
+	require.NoError(t, err)
+	cfg.GatewayKey = key
+	cfg.UploadsEnabled = true
+	cfg.UploadTmpDir = filepath.Join(t.TempDir(), "spool")
+	cfg.FFmpegBin = envOrDefault("TAPIR_E2E_FFMPEG", "ffmpeg")
+	cfg.FFprobeBin = envOrDefault("TAPIR_E2E_FFPROBE", "ffprobe")
+
+	intake, worker, err := buildUploads(ctx, cfg, st, quietLog())
+	require.NoError(t, err)
+	go worker.Run(ctx)
+	app := &web.App{
+		Store: st, Identity: st, Auth: web.StubAuth{U: web.User{Subject: "e2e"}},
+		Chat: buildChat(cfg),
+	}
+	wireUploads(app, cfg, intake) // the same wiring cmdServe uses
+	srv := httptest.NewServer(app.Router())
+	t.Cleanup(srv.Close)
+	noRedirect := &http.Client{CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
+
+	// 1. Upload.
+	f, err := os.Open(audioPath)
+	require.NoError(t, err)
+	defer f.Close()
+	pr, pw := io.Pipe()
+	mw := multipart.NewWriter(pw)
+	go func() {
+		_ = mw.WriteField("title", "E2E recording")
+		fw, _ := mw.CreateFormFile("file", filepath.Base(audioPath))
+		_, _ = io.Copy(fw, f)
+		_ = mw.Close()
+		_ = pw.Close()
+	}()
+	req, err := http.NewRequest(http.MethodPost, srv.URL+"/uploads", pr)
+	require.NoError(t, err)
+	req.Header.Set("Content-Type", mw.FormDataContentType())
+	resp, err := noRedirect.Do(req)
+	require.NoError(t, err)
+	_ = resp.Body.Close()
+	require.Equal(t, http.StatusSeeOther, resp.StatusCode, "an accepted upload redirects to its page")
+	loc := resp.Header.Get("Location")
+	require.True(t, strings.HasPrefix(loc, "/uploads/"), loc)
+	t.Logf("accepted -> %s", loc)
+
+	// 2. Wait for the transcript: unfinished states poll, terminal states do not.
+	var page string
+	require.Eventually(t, func() bool {
+		r, err := http.Get(srv.URL + loc + "/status")
+		if err != nil {
+			return false
+		}
+		b, _ := io.ReadAll(r.Body)
+		_ = r.Body.Close()
+		page = string(b)
+		return !strings.Contains(page, "hx-trigger")
+	}, 12*time.Minute, 3*time.Second, "the upload never reached a terminal state")
+	require.Contains(t, page, "Transcribed", "terminal state was not 'done': %.300s", page)
+
+	var status, endpoint, content string
+	var secs float64
+	require.NoError(t, raw.QueryRow(ctx,
+		`SELECT status, endpoint, content, audio_seconds FROM uploaded_transcripts WHERE user_id = $1`, uid).
+		Scan(&status, &endpoint, &content, &secs))
+	t.Logf("done: endpoint=%s audio_s=%.1f transcript_chars=%d", endpoint, secs, len(content))
+	assert.Equal(t, "done", status)
+	assert.NotEmpty(t, endpoint)
+	assert.NotEmpty(t, content)
+	entries, err := os.ReadDir(cfg.UploadTmpDir)
+	require.NoError(t, err)
+	assert.Empty(t, entries, "the audio must be deleted once transcribed")
+
+	// 3. Ask a question; the answer must come from the transcript.
+	q := envOrDefault("TAPIR_E2E_QUESTION", "Who is responsible for the timber order?")
+	chatResp, err := http.PostForm(srv.URL+loc+"/chat", url.Values{"question": {q}})
+	require.NoError(t, err)
+	answerPage, _ := io.ReadAll(chatResp.Body)
+	_ = chatResp.Body.Close()
+	require.Equal(t, http.StatusOK, chatResp.StatusCode)
+	t.Logf("question: %s", q)
+	if want := os.Getenv("TAPIR_E2E_EXPECT"); want != "" {
+		assert.Contains(t, strings.ToLower(string(answerPage)), strings.ToLower(want),
+			"the answer should be grounded in the transcript")
+	}
+	t.Logf("answer page excerpt: %.600s", afterMarker(string(answerPage), `class="chat-turn chat-a"`))
+}
+
+func envOrDefault(k, d string) string {
+	if v := os.Getenv(k); v != "" {
+		return v
+	}
+	return d
+}
+
+func afterMarker(s, m string) string {
+	if i := strings.Index(s, m); i >= 0 {
+		return s[i:]
+	}
+	return "(no answer turn found)"
+}

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/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

@@ -23,14 +23,15 @@ import (
 	"sync"
 	"time"
 
-	"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/youtube"
-	"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() {
@@ -136,7 +137,8 @@ func cmdRun(ctx context.Context, log *slog.Logger) error {
 
 	r := runner.New(engine.Source, st, engine, cfg.UserID, log,
 		runner.WithBackoff(cfg.FetchBackoff),
-		runner.WithAutoWindow(cfg.AutoSummarizeWindow))
+		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,
@@ -196,6 +198,35 @@ func cmdServe(ctx context.Context, log *slog.Logger) error {
 	secretStore := secrets.NewFileStore(cfg.SecretsFile)
 	app := &web.App{Store: st, Identity: st, Auth: authn, Secrets: secretStore, Log: log, RecencyWindow: cfg.AutoSummarizeWindow}
 
+	// 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))
+	}
+
+	// Audio upload -> private transcript (ADR-033). Off unless TAPIR_UPLOADS_ENABLED:
+	// the image must carry ffmpeg first. The worker is IN-PROCESS and one job at a
+	// time, so it inherits the single-replica assumption below (its queue is
+	// process-local); it stops with the same ctx as the server.
+	intake, worker, err := buildUploads(ctx, cfg, st, log)
+	if err != nil {
+		return err
+	}
+	wireUploads(app, cfg, intake)
+	if intake != nil {
+		go worker.Run(ctx)
+		log.Info("audio upload enabled", "model", cfg.TranscribeModel, "fallback", cfg.TranscribeFallbackModel,
+			"max_mb", cfg.UploadMaxBytes>>20, "max_minutes", int(cfg.UploadMaxDuration.Minutes()))
+		log.Warn("audio upload assumes a SINGLE replica: the transcription queue is process-local (ADR-033, ADR-018)")
+		if cfg.TranscribeFallbackModel != "" {
+			log.Warn("audio upload fallback is a CLOUD endpoint: if the primary fails, private audio leaves the homelab",
+				"fallback", cfg.TranscribeFallbackModel)
+		}
+	}
+
 	// 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.
@@ -252,23 +283,36 @@ func cmdServe(ctx context.Context, log *slog.Logger) error {
 		// 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): after the connect-triggered discovery pass,
-		// summarize up to OnboardSummarizeCount of the user's NEWEST unsummarized
-		// videos so a fresh account gets real summaries in its first session. Hard
-		// cap; explicit, so it bypasses the recency window — but every fetch still
-		// goes through globalFetchGate via the Processor. No-op when disabled
-		// (count 0) or queue-only (no Processor).
+		// 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 || app.Processor == nil {
+			if cfg.OnboardSummarizeCount <= 0 || burstProcessor == nil {
 				return
 			}
-			ids, err := st.NewestUnsummarizedVideoIDs(ctx, userID, cfg.OnboardSummarizeCount)
+			ids, err := st.OnboardBurstVideoIDs(ctx, userID, cfg.OnboardSummarizeCount, cfg.MinVideoSeconds, cfg.OnboardMaxVideoSeconds)
 			if err != nil {
-				log.Warn("onboarding: list newest unsummarized", "user", userID, "err", err)
+				log.Warn("onboarding: list burst candidates", "user", userID, "err", err)
 				return
 			}
 			for _, id := range ids {
-				if err := app.Processor.ProcessVideo(ctx, userID, id); err != nil {
+				if err := burstProcessor.ProcessVideo(ctx, userID, id); err != nil {
 					log.Warn("onboarding: summarize", "user", userID, "video", id, "err", err)
 				}
 			}
@@ -287,16 +331,34 @@ func cmdServe(ctx context.Context, log *slog.Logger) error {
 
 	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

@@ -5,16 +5,18 @@ import (
 	"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/ports"
-	"gitea.d-ma.be/mathias/tapir/internal/usecase"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"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
@@ -51,13 +53,7 @@ func (f videoFetcher) FetchVideo(ctx context.Context, userID, videoID string) (d
 // 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 := func(model string) summarizer.Endpoint {
-		return summarizer.Endpoint{
-			Client:   llm.New(cfg.GatewayURL, cfg.GatewayKey, model, cfg.SummarizerTimeout, llm.WithMaxTokens(cfg.SummaryMaxTokens)),
-			Provider: providerOf(model),
-			Model:    model,
-		}
-	}
+	mk := summarizerEndpoint(cfg)
 	eps := []summarizer.Endpoint{mk(cfg.SummarizerModel)}
 	if cfg.FallbackModel != "" && cfg.FallbackModel != cfg.SummarizerModel {
 		eps = append(eps, mk(cfg.FallbackModel))
@@ -68,6 +64,98 @@ func buildSummarizer(cfg config.Config) *summarizer.Summarizer {
 	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 {
@@ -82,15 +170,7 @@ func buildProcessor(cfg config.Config, st *store.Store) (*usecase.Engine, error)
 		return nil, nil
 	}
 
-	secretStore := secrets.NewFileStore(cfg.SecretsFile)
-	src := youtube.New(youtube.Config{
-		ClientID:           cfg.YTClientID,
-		ClientSecret:       cfg.YTClientSecret,
-		TokenSecretRef:     cfg.YTTokenRef,
-		PreferredLanguages: []string{"en"},
-		MinVideoSeconds:    cfg.MinVideoSeconds,
-	}, secretStore)
-
+	src := newYouTubeSource(cfg, secrets.NewFileStore(cfg.SecretsFile))
 	sum := buildSummarizer(cfg)
 
 	// The store is both the summary sink and the shared transcript cache (ADR-021):
@@ -101,6 +181,38 @@ func buildProcessor(cfg config.Config, st *store.Store) (*usecase.Engine, error)
 	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)
+}
+
+// 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
+	}
+	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
 // the web.Processor port (which works in terms of a stored video id): it loads the
 // video row, runs the engine, and — on a produced summary — clears the manual
@@ -113,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)
@@ -132,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

@@ -6,14 +6,36 @@ import (
 	"io"
 	"os"
 	"text/tabwriter"
+	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"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).
@@ -28,16 +50,24 @@ func runReport(ctx context.Context, _ []string) error {
 	}
 	defer s.Close()
 
-	rows, err := s.ActiveWeeks(ctx)
+	since, err := gateStart()
 	if err != nil {
 		return err
 	}
-	return formatReport(os.Stdout, rows)
+
+	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) error {
+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

cmd/tapir/report_test.go

@@ -3,12 +3,15 @@ package main
 import (
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"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},
@@ -16,9 +19,10 @@ func TestFormatReportColumnsAndGatePass(t *testing.T) {
 	}
 
 	var b strings.Builder
-	require.NoError(t, formatReport(&b, rows))
+	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")
@@ -34,12 +38,12 @@ func TestFormatReportGateNotMet(t *testing.T) {
 	rows := []store.UserActiveWeeks{{UserID: "user-a", ActiveWeeks: 1}}
 
 	var b strings.Builder
-	require.NoError(t, formatReport(&b, rows))
+	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))
+	require.NoError(t, formatReport(&b, nil, testSince))
 	require.Contains(t, b.String(), "no users yet")
 }

cmd/tapir/scheduler.go

@@ -6,13 +6,13 @@ import (
 	"log/slog"
 	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/youtube"
-	"gitea.d-ma.be/mathias/tapir/internal/config"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
-	"gitea.d-ma.be/mathias/tapir/internal/usecase"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"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
@@ -45,7 +45,8 @@ func buildUserRunner(cfg config.Config, st *store.Store, secretStore ports.Secre
 
 	return runner.New(src, st, engine, userID, log,
 		runner.WithBackoff(cfg.FetchBackoff),
-		runner.WithAutoWindow(cfg.AutoSummarizeWindow)), nil
+		runner.WithAutoWindow(cfg.AutoSummarizeWindow),
+		runner.WithCaptionMemory(cfg.ChannelCaptionlessThreshold, cfg.ChannelCaptionlessWindow)), nil
 }
 
 // userLister enumerates every registered user and reports a user's video
@@ -121,6 +122,7 @@ func runDiscoveryPass(
 		"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
 }
@@ -141,8 +143,18 @@ func runScheduler(
 		return // disabled
 	}
 
-	pass := 0
+	// 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()
@@ -151,8 +163,7 @@ func runScheduler(
 		case <-ctx.Done():
 			return
 		case <-ticker.C:
-			pass++
-			runDiscoveryPass(ctx, pass, lister, runUser, log)
+			runPass()
 		}
 	}
 }
@@ -188,6 +199,7 @@ func sumStats(a, b runner.Stats) runner.Stats {
 		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

@@ -11,8 +11,8 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/runner"
 )
 
 func quietLog() *slog.Logger {

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,

cmd/tapir/uploads.go

@@ -0,0 +1,100 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"path/filepath"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/audio"
+	"git.d-ma.be/mathias/tapir/internal/adapters/transcribe"
+	"git.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/uploads"
+	"git.d-ma.be/mathias/tapir/internal/web"
+)
+
+// uploadsStore is the store surface the upload wiring needs. *store.Store
+// satisfies it.
+type uploadsStore interface {
+	uploads.Store
+	uploads.WorkerStore
+	FailInterruptedUploads(ctx context.Context) (int, error)
+}
+
+// buildUploads wires audio upload and private transcription (ADR-033). It returns
+// nils when uploads are disabled — never a typed-nil Intake, which would mount the
+// /uploads routes over nothing. When enabled it, in order: prepares a private spool
+// directory, deletes any audio a crashed run left in it, fails the rows such a run
+// left queued or transcribing (the audio is not retained, so they can never
+// resume), and only then builds the intake and the worker. The caller runs the
+// worker. The fallback endpoint is a cloud service; an empty
+// TAPIR_TRANSCRIBE_FALLBACK_MODEL keeps private audio on the homelab.
+func buildUploads(ctx context.Context, cfg config.Config, st uploadsStore, log *slog.Logger) (*uploads.Intake, *uploads.Worker, error) {
+	if !cfg.UploadsEnabled {
+		return nil, nil, nil
+	}
+	if cfg.GatewayURL == "" {
+		return nil, nil, fmt.Errorf("uploads: TAPIR_UPLOADS_ENABLED is set but there is no TAPIR_GATEWAY_URL to transcribe through")
+	}
+
+	if err := os.MkdirAll(cfg.UploadTmpDir, 0o700); err != nil {
+		return nil, nil, fmt.Errorf("uploads: spool dir: %w", err)
+	}
+	removeSpooledAudio(cfg.UploadTmpDir, log)
+
+	n, err := st.FailInterruptedUploads(ctx)
+	if err != nil {
+		return nil, nil, fmt.Errorf("uploads: fail interrupted rows: %w", err)
+	}
+	if n > 0 {
+		log.Warn("uploads: marked interrupted by a restart (audio is not retained; they must be re-uploaded)", "count", n)
+	}
+
+	// No overall client timeout: a 90 minute recording takes minutes. The deadline
+	// is the worker's per-job context.
+	client := &http.Client{}
+	primary := transcribe.NewGateway(cfg.GatewayURL, cfg.GatewayKey, cfg.TranscribeModel, client)
+	var fallback transcribe.Backend
+	if cfg.TranscribeFallbackModel != "" && cfg.TranscribeFallbackModel != cfg.TranscribeModel {
+		fallback = transcribe.NewGateway(cfg.GatewayURL, cfg.GatewayKey, cfg.TranscribeFallbackModel, client)
+	}
+
+	worker := uploads.NewWorker(st, &audio.FFmpeg{Bin: cfg.FFmpegBin}, transcribe.NewChain(primary, fallback),
+		cfg.UploadTmpDir, cfg.TranscribeTimeout)
+	intake := uploads.NewIntake(st, &audio.FFprobe{Bin: cfg.FFprobeBin}, worker,
+		uploadLimits(cfg), cfg.UploadTmpDir)
+	return intake, worker, nil
+}
+
+func uploadLimits(cfg config.Config) uploads.Limits {
+	return uploads.Limits{MaxBytes: cfg.UploadMaxBytes, MaxDuration: cfg.UploadMaxDuration}
+}
+
+// removeSpooledAudio deletes the spool files this process family creates
+// (upload-*, wav-*) and nothing else.
+func removeSpooledAudio(dir string, log *slog.Logger) {
+	for _, pat := range []string{"upload-*", "wav-*"} {
+		matches, _ := filepath.Glob(filepath.Join(dir, pat))
+		for _, m := range matches {
+			if err := os.Remove(m); err != nil {
+				log.Warn("uploads: remove leftover audio", "path", m, "err", err)
+			}
+		}
+	}
+}
+
+// wireUploads connects a built Intake to the web App: the routes, the limits the
+// form states, and the chat settings for an uploaded recording. A nil intake
+// leaves the App untouched — assigning a nil *Intake to the Uploader interface
+// would produce a non-nil interface and mount the routes over nothing.
+func wireUploads(app *web.App, cfg config.Config, in *uploads.Intake) {
+	if in == nil {
+		return
+	}
+	app.Uploads = in
+	app.UploadLimits = uploadLimits(cfg)
+	app.UploadChatMaxChars = cfg.MaxUploadedTranscriptChars
+	app.UploadChatModel = cfg.UploadChatModel
+}

cmd/tapir/uploads_test.go

@@ -0,0 +1,156 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/web"
+)
+
+// fakeUploadsStore satisfies the store surface buildUploads needs, and counts the
+// start-up sweep.
+type fakeUploadsStore struct {
+	sweeps   int
+	sweepErr error
+}
+
+func (f *fakeUploadsStore) CreateUpload(context.Context, string, string) (string, error) {
+	return "id", nil
+}
+
+func (f *fakeUploadsStore) FailUpload(context.Context, string, string, domain.UploadErrorKind) error {
+	return nil
+}
+
+func (f *fakeUploadsStore) StartTranscribing(context.Context, string, string) error { return nil }
+
+func (f *fakeUploadsStore) CompleteUpload(context.Context, string, string, domain.Transcription) error {
+	return nil
+}
+
+func (f *fakeUploadsStore) FailInterruptedUploads(context.Context) (int, error) {
+	f.sweeps++
+	return 2, f.sweepErr
+}
+
+func uploadCfg(t *testing.T, enabled bool) config.Config {
+	t.Helper()
+	var cfg config.Config
+	cfg.GatewayURL = "http://gateway.invalid/v1"
+	cfg.UploadsEnabled = enabled
+	cfg.UploadMaxBytes = 200 << 20
+	cfg.UploadTmpDir = filepath.Join(t.TempDir(), "spool")
+	cfg.TranscribeModel = "iguana/kb-whisper"
+	cfg.TranscribeFallbackModel = "berget/kb-whisper"
+	return cfg
+}
+
+func TestBuildUploads_DisabledMountsNothingAndSweepsNothing(t *testing.T) {
+	st := &fakeUploadsStore{}
+
+	in, w, err := buildUploads(context.Background(), uploadCfg(t, false), st, quietLog())
+
+	require.NoError(t, err)
+	assert.Nil(t, in, "a typed-nil Intake must never reach web.App.Uploads: it would mount the routes over nothing")
+	assert.Nil(t, w)
+	assert.Zero(t, st.sweeps)
+}
+
+func TestBuildUploads_EnabledFailsInterruptedRowsBeforeAnythingElseStarts(t *testing.T) {
+	st := &fakeUploadsStore{}
+
+	in, w, err := buildUploads(context.Background(), uploadCfg(t, true), st, quietLog())
+
+	require.NoError(t, err)
+	require.NotNil(t, in)
+	require.NotNil(t, w)
+	assert.Equal(t, 1, st.sweeps,
+		"audio is not retained, so rows left queued/transcribing by a restart can never resume: fail them at start-up, not never")
+}
+
+func TestBuildUploads_SweepFailureStopsStartup(t *testing.T) {
+	st := &fakeUploadsStore{sweepErr: errors.New("db down")}
+
+	_, _, err := buildUploads(context.Background(), uploadCfg(t, true), st, quietLog())
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "db down")
+}
+
+func TestBuildUploads_CreatesTheSpoolDirectoryPrivately(t *testing.T) {
+	cfg := uploadCfg(t, true)
+
+	_, _, err := buildUploads(context.Background(), cfg, &fakeUploadsStore{}, quietLog())
+
+	require.NoError(t, err)
+	info, err := os.Stat(cfg.UploadTmpDir)
+	require.NoError(t, err)
+	assert.True(t, info.IsDir())
+	assert.Equal(t, os.FileMode(0o700), info.Mode().Perm(), "spooled audio is private third-party content")
+}
+
+func TestBuildUploads_EnabledWithoutAGatewayIsAnError(t *testing.T) {
+	cfg := uploadCfg(t, true)
+	cfg.GatewayURL = ""
+
+	_, _, err := buildUploads(context.Background(), cfg, &fakeUploadsStore{}, quietLog())
+
+	assert.Error(t, err, "uploads on with nowhere to transcribe must fail loudly at start-up, not at the first upload")
+}
+
+func TestBuildUploads_RemovesAudioLeftBehindByACrash(t *testing.T) {
+	cfg := uploadCfg(t, true)
+	require.NoError(t, os.MkdirAll(cfg.UploadTmpDir, 0o700))
+	leftovers := []string{"upload-123", "wav-456"}
+	for _, n := range leftovers {
+		require.NoError(t, os.WriteFile(filepath.Join(cfg.UploadTmpDir, n), []byte("audio"), 0o600))
+	}
+	unrelated := filepath.Join(cfg.UploadTmpDir, "someone-elses-file")
+	require.NoError(t, os.WriteFile(unrelated, []byte("keep"), 0o600))
+
+	_, _, err := buildUploads(context.Background(), cfg, &fakeUploadsStore{}, quietLog())
+
+	require.NoError(t, err)
+	for _, n := range leftovers {
+		_, err := os.Stat(filepath.Join(cfg.UploadTmpDir, n))
+		assert.True(t, os.IsNotExist(err), "%s: audio is never retained, so a spooled file from a crashed run must not survive start-up", n)
+	}
+	_, err = os.Stat(unrelated)
+	assert.NoError(t, err, "only our own spool files are removed")
+}
+
+func TestWireUploads_SetsEverythingTheWebAppNeedsForUploadsAndChat(t *testing.T) {
+	cfg := uploadCfg(t, true)
+	cfg.UploadMaxDuration = 90 * 60 * 1e9
+	cfg.MaxUploadedTranscriptChars = 90000
+	cfg.UploadChatModel = "iguana/gemma4-26b"
+	in, _, err := buildUploads(context.Background(), cfg, &fakeUploadsStore{}, quietLog())
+	require.NoError(t, err)
+	app := &web.App{}
+
+	wireUploads(app, cfg, in)
+
+	assert.NotNil(t, app.Uploads)
+	assert.Equal(t, cfg.UploadMaxBytes, app.UploadLimits.MaxBytes, "the form states the limits Intake enforces")
+	assert.Equal(t, cfg.UploadMaxDuration, app.UploadLimits.MaxDuration)
+	assert.Equal(t, 90000, app.UploadChatMaxChars,
+		"without this the chat would use the 18,000-char caption default and cut an hour to its first third")
+	assert.Equal(t, "iguana/gemma4-26b", app.UploadChatModel)
+}
+
+func TestWireUploads_NilIntakeLeavesTheAppUntouched(t *testing.T) {
+	app := &web.App{}
+
+	wireUploads(app, uploadCfg(t, false), nil)
+
+	assert.Nil(t, app.Uploads, "a nil *Intake must not become a non-nil interface that mounts the routes")
+	assert.Zero(t, app.UploadChatMaxChars)
+}

docs/architecture/architecture.md

@@ -250,6 +250,32 @@ 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

docs/data-model.md

@@ -18,7 +18,12 @@ only opaque references to them; the secret material lives in ESO/1Password (ADR-
   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.
+  self-contained; `rls_test.go` proves transcripts is the single exception for *content*.
+  **Uploaded-audio transcripts are the opposite of public caption content** (private, owned by
+  one user) and therefore live in their own RLS-scoped `uploaded_transcripts` table, never in
+  `transcripts` (ADR-033). The isolation test now also pins the **exact set** of tables with row
+  security off (`transcripts`, `user_identities`, `invitations`, `schema_migrations`), so a new
+  table added without RLS fails CI.
 - **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
@@ -41,6 +46,7 @@ erDiagram
     VIDEO ||--o| SUMMARY : "has at most one"
     SUMMARY ||--o{ SINK_DELIVERY : "delivered via"
     USER ||--o{ CHANNEL_ERROR : "reports unavailable channels"
+    USER ||--o{ UPLOADED_TRANSCRIPT : "uploads (private, ADR-033)"
 
     USER {
         uuid id PK
@@ -136,12 +142,27 @@ erDiagram
         timestamptz first_seen
         timestamptz last_seen
     }
+    UPLOADED_TRANSCRIPT {
+        uuid id PK
+        uuid user_id FK "-> USER, ON DELETE CASCADE, NOT NULL; RLS ENABLE+FORCE (migration 017)"
+        text title
+        text status "queued | transcribing | done | failed"
+        text content "nullable until done; the transcript text"
+        jsonb segments "nullable until done; [{start,end,text}] in seconds"
+        text endpoint "which backend served it: iguana/... | berget/... (berget = audio left the homelab)"
+        float audio_seconds
+        text error_kind "typed: interrupted | transcription_failed — never a provider string"
+        timestamptz created_at
+        timestamptz finished_at
+    }
 ```
 
 `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`, `channel_errors`.
+`summaries`, `summary_actions`, `video_connections`, `channel_errors`, `uploaded_transcripts`.
+(`transcripts` is deliberately **not** in this list: since ADR-021 it is shared public caption
+content with no `user_id`.)
 `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.
@@ -197,6 +218,14 @@ mechanism.
   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.
+- **UPLOADED_TRANSCRIPTS** (migration 017, ADR-033) — the **private** transcript of audio a user
+  uploaded. Deliberately a separate table from the shared `transcripts`: that one is non-RLS on the
+  grounds that it holds only public caption content, and a recorded meeting is the opposite.
+  `user_id NOT NULL ... ON DELETE CASCADE`, FORCE RLS'd. `status` runs `queued → transcribing →
+  done | failed`; `done` requires `content`, `failed` requires a typed `error_kind` (CHECK
+  constraints). `endpoint` records which backend served it — `berget/...` means the audio left the
+  homelab. The audio itself is never stored. `segments` keeps the timestamps (re-transcribing 90
+  minutes costs ~7). Unlike `summary_actions`/`login_events` it **does** cascade on user deletion.
 - **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").
 
@@ -209,7 +238,10 @@ 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`, `channel_errors`.
+  `summaries`, `summary_actions`, `video_connections`, `channel_errors`, and (migration 017)
+  `uploaded_transcripts`. `transcripts` is **not** one of them: ADR-021 made it shared public
+  content, and migration 003's original per-user `transcripts` policy was dropped with that
+  table in migration 015.
   `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

docs/homelab-integration.md

@@ -12,6 +12,22 @@ it** — endpoints and aliases drift, and this file is a snapshot (2026-06-06),
   - **Off-cluster (host / NodePort):** `http://koala:30401/v1/` — service `litellm-nodeport` (`4000:30401`).
   - NOTE: the earlier `31234` was **wrong** — `31234` is the `llama-swap` NodePort (`8080:31234`),
     not LiteLLM. Use `30401` for off-cluster LiteLLM. `confirm` resolved.
+- **Speech-to-text (ADR-033):** the same gateway serves `POST /v1/audio/transcriptions` for
+  `iguana/kb-whisper` (primary, local) and `berget/kb-whisper` (fallback, EU cloud — private audio
+  leaves the homelab if it is used). **Call it via the NodePort / in-cluster address above, NOT
+  `https://llm-api.d-ma.be`:** that public ingress (openresty) returns `413` for bodies over
+  roughly 8–10 MB (~5 minutes of 16 kHz WAV), while the NodePort took 174 MB (90 minutes) in one
+  request (measured 2026-10-01, `docs/research/audio-length-ceiling-2026-10-01.md`). Send multipart
+  field `file`, `response_format=verbose_json`, no `Expect: 100-continue`. iguana's whisper-server
+  can wedge permanently after a Metal OOM (infra#273); never branch on its
+  `{"error":"failed to process audio"}` string — it has had at least five causes. Tapir's knobs:
+  `TAPIR_UPLOADS_ENABLED` (off by default), `TAPIR_UPLOAD_MAX_MB` (200), `TAPIR_UPLOAD_MAX_MINUTES`
+  (90), `TAPIR_TRANSCRIBE_MODEL`, `TAPIR_TRANSCRIBE_FALLBACK_MODEL` (empty disables the cloud
+  fallback), `TAPIR_TRANSCRIBE_TIMEOUT` (30m), `TAPIR_UPLOAD_TMP_DIR`, `TAPIR_FFMPEG_BIN`,
+  `TAPIR_FFPROBE_BIN`, `TAPIR_MAX_UPLOADED_TRANSCRIPT_CHARS` (90000 — the measured ceiling of
+  `iguana/gemma4-26b`, which silently drops the head above it), `TAPIR_UPLOAD_CHAT_MODEL`
+  (`iguana/gemma4-26b`; `koala/phi4-mini`'s 8,192-token context 400s on an hour of speech). Needs `ffmpeg` + `ffprobe`
+  in the runtime image; Tapir's own ingress body limit for a 200 MB upload is unverified (infra).
 - **Auth key:** treat as a secret via the SecretStore port; do not hardcode in committed code.
   NOTE: the documented `sk-local-123` returned `401` on `30401/v1/models` (2026-06-02) — it is
   stale or the gateway now enforces the `LITELLM_MASTER_KEY` (1Password `op://HomeLab/LITELLM_MASTER_KEY`).
@@ -30,7 +46,9 @@ it** — endpoints and aliases drift, and this file is a snapshot (2026-06-06),
 - **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 `koala/phi4-14b`.** Empty disables it.
+  - `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.
@@ -44,6 +62,11 @@ it** — endpoints and aliases drift, and this file is a snapshot (2026-06-06),
   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):**
@@ -217,6 +240,15 @@ 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`

docs/research/audio-length-ceiling-2026-10-01.md

@@ -0,0 +1,110 @@
+# Audio length ceiling — measured before designing chunking (tapir#33, 2026-10-01)
+
+Question (#33, "the main technical risk"): at what recording length does Swedish
+transcription through the LiteLLM gateway first fail, and with what failure mode?
+Measured **before** any chunking design, with iguana not holding a large ollama model,
+so the result is the ceiling and not the Metal OOM of infra#273.
+
+## Answer
+
+**No transcription ceiling was found at or below 90 minutes.** A single request carrying
+90 minutes of 16 kHz mono PCM (174 MB) transcribed in one pass in 440 s. The first thing
+that actually fails is **not whisper**: it is the public gateway ingress, which rejects the
+upload with `413` at roughly 5.5 minutes of WAV.
+
+| Route | First failure | Failure mode |
+|---|---|---|
+| `https://llm-api.d-ma.be` (openresty ingress) | between 8.0 MB and 10.5 MB body (~4–5.5 min of WAV) | `413 Request Entity Too Large`, HTML body from `openresty`, returned instantly |
+| `http://koala:30401` (LiteLLM NodePort) → `iguana/kb-whisper` | **none up to 90 min / 174 MB** | — |
+| `http://koala:30401` → `berget/kb-whisper` | **none up to 22 min / 42 MB** (largest tried) | — |
+
+The ingress limit is the reason the 8:20 / 15 MB recording in #33 "failed repeatedly" and a
+30-second slice succeeded. That failure was attributed to a Metal OOM; at least in the
+size-dependent form described, a body-size cap explains it without one. (The OOM
+mechanism in infra#273 is separately real; this run did not provoke it.)
+
+The exact ingress cap was bracketed (8.0 MB passed, 10.5 MB failed), not read from the
+ingress configuration, which lives in `infra`. "About 10 MB" is an inference.
+
+## Method
+
+- **Audio.** No known-good Swedish recording is available that is safe to use: the only real
+  one (`IMG_1233.wav`) is the private `/bygge` recording (#31 custody still open) and was
+  deliberately not touched. Instead: macOS `say -v Alva` (Swedish) on iguana, a 1,171-char
+  five-paragraph meeting script → 82.5 s of 16 kHz mono PCM WAV (`ffmpeg -ar 16000 -ac 1`).
+  Concatenated ×4, ×8, ×16, ×32, ×44, ×66 with Python `wave` (the issue's own recipe).
+  Nothing here is a real transcript; none of it is committed.
+- **Request.** `POST /v1/audio/transcriptions`, multipart `file=`, `model=iguana/kb-whisper`,
+  `response_format=verbose_json`, `-H 'Expect:'` (per #33's traps), master key supplied only
+  through `op run` and never on argv.
+- **Confound control.** `ollama /api/ps` on iguana was read before every step. Resident:
+  nothing, or `nomic-embed-text` (0.37 GB). Never a large model.
+
+## Results (`iguana/kb-whisper`, NodePort)
+
+| Audio | WAV size | HTTP | Wall | Realtime factor | Segments | Chars |
+|---|---|---|---|---|---|---|
+| 0:30 | 0.96 MB | 200 | 2.8 s | 11× | — | — |
+| 2:30 / 3:20 / 4:10 | 4.8 / 6.4 / 8.0 MB | 200 (ingress) | 12.9 / 16.0 / 19.9 s | 12× | — | — |
+| 5:30 (×4) | 10.5 MB | **413 ingress**, 200 NodePort in 27 s | 27 s | 12× | 121 | 4,557 |
+| 11:00 (×8) | 21.1 MB | 200 | 53 s | 12× | 241 | 9,094 |
+| 22:00 (×16) | 42.3 MB | 200 | 105 s | 13× | 482 | 18,201 |
+| 44:01 (×32) | 84.5 MB | 200 | 209 s | 13× | 966 | 36,438 |
+| 60:32 (×44) | 116.2 MB | 200 | 291 s | 12× | 1,332 | 50,145 |
+| 90:48 (×66) | 174.3 MB | 200 | 440 s | 12× | 2,005 | 75,165 |
+
+- Throughput is flat at ~12× realtime. 90 minutes costs ~7.5 minutes of wall time. This is
+  a minutes-long job, not a request/response one (see ADR-033 on ADR-018).
+- Segments per source repetition stay at 30.1–30.4 from ×4 to ×66, and segment times are
+  monotonic with `last_end` within 0.2 s of `duration`. No drift and no repetition-loop
+  hallucination appeared across 90 minutes. This is a weak check — the input is a repeated
+  loop and synthetic voice — not evidence of accuracy.
+- **Only `iguana/kb-whisper`'s `x4` run reported `last_end` 360.0 s against `duration`
+  330.2 s.** Whisper's final segment can end past the audio; clamp to `duration`.
+
+## Findings that change the design
+
+1. **Use the NodePort route, not the public hostname.** Tapir runs in-cluster beside the
+   gateway; `llm-api.d-ma.be` is the external door and has a body cap. #33 said "use the
+   gateway, never the host" and named the public URL; the gateway is right, that URL is not.
+   `TAPIR_GATEWAY_URL` already points at `koala:30401/v1`.
+2. **`response_format=srt` survives the LiteLLM hop, but wrapped.** The response is JSON
+   `{"text": "<the SRT>", "usage": …}`, not a bare SRT body — a client that parses the body
+   as SRT gets a parse error on `{`. #33 question 2 is answered: it passes through, inside
+   an envelope.
+3. **The two backends return different timestamp granularity.** `iguana/kb-whisper`
+   segments are **whole seconds** (`0→1`, `1→4`, `4→7`); `berget/kb-whisper` returns real
+   sub-second times (`0.051→1.192`) and a different `language` token (`swedish` vs `sv`).
+   `verbose_json` and the default JSON were byte-identical on iguana. An adapter that
+   falls back between the two must normalise both, and "which endpoint served this" is
+   a quality fact, not just a log line.
+4. **The existing chat path cannot answer about most of a long recording.** At
+   828 chars/min (this fixture; real speech is plausibly a little denser),
+   `TAPIR_MAX_TRANSCRIPT_CHARS`'s default of **18,000** is ~21.7 minutes. A 60-minute
+   transcript is 50 k chars, a 90-minute one 75 k. `chat.Service` truncates by keeping
+   the head (`internal/adapters/chat/chat.go`), so questions about the last two-thirds of
+   a one-hour meeting get an answer from a transcript that does not contain it. #33 says
+   chat "retrieves rather than generates" and therefore has no ceiling; it **stuffs and
+   truncates**, and its ceiling is the model context. See ADR-033.
+5. **Chunking is not needed for v1 on length.** Nothing failed up to 90 minutes. The
+   chunking-and-stitching recipe in #33 (offset timestamps, renumber cues, strip `\r`) is
+   not built. It stays the answer *if* a longer cap is wanted or the OOM mechanism forces
+   smaller requests — see ADR-033's resolution triggers.
+
+## What this did not measure
+
+- **Metal OOM under contention.** Deliberately avoided. A big resident ollama model
+  during a long transcription is still the known way to wedge iguana permanently.
+- **Real speech.** TTS is clean, single-voice, no crosstalk or room noise. WER and
+  speaker overlap in a Teams export are untested. Speed is probably representative;
+  accuracy is not claimed.
+- **Compressed input.** Only WAV was sent. Whether `m4a`/`mp3`/`opus` can reach whisper
+  without a server-side transcode is not established here (ADR-033 treats it as needing one).
+- **Concurrency.** One request at a time. Two simultaneous 90-minute jobs on iguana were
+  not tried.
+- **`berget/kb-whisper` beyond 22 min / 42 MB.** Enough to know the fallback is not
+  size-capped at meeting length for 22 minutes; not proven at 90.
+- **Time-of-day / other tenants.** One afternoon, one run per length.
+
+Scripts were throwaway shell/Python in a session scratchpad and are not committed; the
+method above reproduces them.

docs/research/chat-context-over-long-transcripts-2026-10-01.md

@@ -0,0 +1,66 @@
+# Chat over a long transcript — what the offered models really hold (tapir#33, 2026-10-01)
+
+Question: ADR-033 reuses `chat.Service`, which stuffs the transcript into the prompt and
+cuts the tail. #33 assumed chat "retrieves rather than generates" and so has no length
+ceiling. It does not retrieve, so its ceiling is the model's context. What is it, for the
+models chat actually offers?
+
+## Answer
+
+| Model (via the NodePort gateway) | Result | Limit found |
+|---|---|---|
+| `koala/phi4-mini` | correct to 30,000 chars; **HTTP 400 at 50,000** (13,332 tokens vs an 8,192-token context) | ~22,000 chars in production, where the client adds `max_tokens: 1500` |
+| `iguana/gemma4-26b` | correct at 18k, 50k and **90,000 chars** (26.5 k tokens); **at 120,000 chars it silently loses the head** | **90,000 chars** |
+| `berget/mistral-small` | answered "the transcript does not contain it" for a fact **at the end** of an 18,000-char and a 50,000-char transcript | unreliable here, one run each — see caveats |
+
+The dangerous one is gemma at 120,000 chars: **no error, no truncation flag** — the reported
+prompt tokens fell from 26,548 (90 k chars) to 16,387 (120 k chars), and the model answered
+"it does not say who the chair is" about a sentence at the very start of the transcript. The
+serving layer truncated the prompt from the front. `chat.Service` reports `Truncated: false`
+because *it* did not cut anything.
+
+## What this changes
+
+1. **The budget for an uploaded transcript is 90,000 chars, not a round 120,000.** That is the
+   best offered model's measured limit, ~100 minutes of speech at the fixture's density.
+   `TAPIR_MAX_UPLOADED_TRANSCRIPT_CHARS` defaults to it.
+2. **Chat over an upload must not open on the summarizer default.** The offered list is
+   `[SummarizerModel, FallbackModel, CloudFallbackModel]`, so `koala/phi4-mini` is first — and
+   400s on an hour of speech. `TAPIR_UPLOAD_CHAT_MODEL` (default `iguana/gemma4-26b`) is what
+   the upload chat opens with; the switcher still lists every model.
+3. **A per-model budget does not exist yet.** Someone who switches the dropdown to
+   `phi4-mini` on a long recording gets a loud HTTP 400, shown inline as "couldn't answer".
+   That fails honestly but unhelpfully. Filed as a follow-up.
+4. **The "retrieval chat" trigger in ADR-033 is now concrete:** any recording past 90,000 chars
+   (≈100 min) cannot be answered by stuffing, for any offered model.
+
+## Method
+
+`POST /v1/chat/completions` through `http://koala:30401/v1`, `temperature: 0`,
+`max_tokens: 200` (production sends 1500 for chat via the summary token cap), the same system
+framing as `chat.Service`. The transcript is the 60-minute synthetic fixture from
+`audio-length-ceiling-2026-10-01.md` truncated/repeated to N chars, with one unique sentence
+planted either at the **end** ("lagret på Kvarngatan ska tömmas … av Pelle", question: who/when)
+or at the **head** ("kvällens ordförande är Ingrid", question: who chairs). Needle at the
+end alone would have missed the gemma failure — a serving layer that truncates from the front
+keeps the tail, so the end-needle passed at 120,000 chars; only the head-needle exposed it.
+Grounded = the answer contains the planted fact.
+
+## What this did not measure
+
+- **Real speech**: the fixture is a repeated 82-second script, so retrieval "difficulty" is
+  artificially easy except for the planted needle. One question per run, one run per cell.
+- **`berget/mistral-small`'s failure**: it missed an end-needle at 18,000 chars where the
+  others succeeded. One run; could be the model, the prompt framing, or position bias. Not
+  investigated; do not read it as a ranking.
+- **Latency under load**, **concurrent** chat while whisper is transcribing, and in particular
+  the hazard below.
+- **`koala/qwen36-35b-a3b` or any frontier model** — not in the offered list.
+
+## A hazard this surfaces and does not solve
+
+`iguana/gemma4-26b` is a large ollama model on the same host as `iguana/kb-whisper`. infra#273
+is precisely that a large resident ollama model can Metal-OOM whisper-server permanently. Making
+gemma the default *chat* model for uploads means chatting with a transcript can load the model
+that wedges the transcriber. The primary-fails-over-to-berget design limits the blast radius but
+does not remove it. Recorded in ADR-033 and filed.

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/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/ui-spec.md

@@ -179,4 +179,5 @@ distinguishable.
 | **"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/audio_upload.feature

@@ -0,0 +1,101 @@
+Feature: Upload an audio recording, get a private Swedish transcript, discuss it
+  As someone with a recorded meeting on my computer
+  I want to upload it and then ask questions about what was said
+  So that I can find out what was decided, what is open and who owes what
+
+  # ADR-033, tapir#33. The load-bearing constraint: an uploaded transcript is
+  # PRIVATE content, so it lives in its own RLS-scoped store and never in the
+  # shared public-caption `transcripts` table (ADR-021). Rejection is synchronous,
+  # the audio is never retained, and a failed job ends in a terminal state with a
+  # message — never a spinner (ADR-025). Audio only: video is #28.
+
+  Background:
+    Given I am a registered user with audio upload enabled
+
+  Scenario: The upload form states the limits up front
+    When I open the upload page
+    Then I see the size limit and the length limit before I choose a file
+
+  Scenario: An accepted recording is queued and I am taken to its page
+    When I upload an audio file within the limits
+    Then it is recorded as queued for me
+    And I am redirected to its page
+
+  Scenario: A recording with no title is named after its file
+    When I upload an audio file and give no title
+    Then its title is the filename without its extension
+
+  Scenario: A file containing video is rejected, naming issue 28
+    When I upload a file that has a video track
+    Then it is rejected with a message that video is tracked in issue 28
+    And nothing is recorded
+
+  Scenario: A recording over the length limit is rejected with both lengths
+    When I upload a recording longer than the limit
+    Then it is rejected stating the recording's length and the limit
+    And nothing is recorded
+
+  Scenario: A file over the size limit is rejected as too large
+    When I upload a file larger than the size limit
+    Then it is rejected with 413 and a message about the limit
+    And nothing is recorded
+
+  Scenario: An audio-only MP4 is not mistaken for video
+    When I upload an mp4 container that has an audio stream and no video stream
+    Then it is accepted
+    And an mp3 whose only video stream is cover art is accepted too
+
+  Scenario: A file that is not media is rejected as unreadable
+    When I upload a file ffprobe cannot read
+    Then it is rejected as the file's fault
+
+  Scenario: A broken ffprobe is reported as our fault, not as a bad file
+    When the prober itself fails
+    Then the upload is an error rather than a rejection of my file
+
+  Scenario: A recording becomes a transcript and the audio is deleted
+    Given I have uploaded a recording
+    When it has been transcribed
+    Then the transcript is stored privately for me
+    And the audio is deleted
+
+  Scenario: The endpoint that served a transcript is recorded and shown
+    Given a recording was transcribed by the fallback endpoint
+    When I view its page
+    Then it names the fallback endpoint, because that means the audio left the homelab
+
+  Scenario: The local endpoint is tried first and the fallback only on failure
+    When the primary transcription endpoint fails for any reason
+    Then the fallback endpoint transcribes it
+    But when the primary succeeds the fallback is never contacted
+
+  Scenario: A failed transcription ends in a message, never a spinner
+    When every transcription endpoint fails
+    Then the upload is failed with a typed reason
+    And its page shows that reason and stops polling
+
+  Scenario: A restart fails the jobs it interrupted
+    Given the service restarted while a recording was queued or transcribing
+    When it starts again
+    Then those uploads are failed as interrupted
+    And any audio left in the spool is deleted
+
+  Scenario: Only one recording is transcribed at a time
+    When several recordings are queued
+    Then they are transcribed one after another
+
+  Scenario: My uploads are invisible to other users
+    Given another user has uploaded a recording
+    When I ask for it by its id
+    Then I get 404 and no part of its title or text
+    And the chat for it calls no model
+
+  Scenario: I can ask about my recording and get a grounded answer
+    Given my recording has been transcribed
+    When I ask a question about it
+    Then the answer comes from my transcript through the same chat as a video's
+
+  Scenario: A long recording is not cut to its first third
+    Given my recording's transcript is longer than the caption default
+    When I ask a question about it
+    Then the transcript is sent with the upload budget, not the 18,000-character caption default

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

@@ -24,12 +24,19 @@ Feature: Connect and manage video accounts
     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 newest videos right away
+  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 videos are summarized through the rate gate
+    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

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/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/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

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,23 +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=
@@ -103,6 +121,8 @@ 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/audio/ffmpeg.go

@@ -0,0 +1,47 @@
+package audio
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+)
+
+// FFmpeg converts any audio container to the strict format whisper wants: 16 kHz
+// mono signed 16-bit PCM WAV (ADR-033). It ALWAYS transcodes, even when the input
+// already is that format — a Teams export often is, and the transcode is then
+// nearly free; assuming it would be the bug. This replaces whisper-server's
+// --convert, whose --tmp-dir is created at process start and rots under macOS
+// periodic cleanup.
+type FFmpeg struct {
+	// Bin is the ffmpeg executable ("ffmpeg" resolves via PATH).
+	Bin string
+}
+
+// ToWAV writes src, converted, to dst. Video streams are dropped (-vn): by now the
+// file has already been probed as audio-only, but a cover-art stream must not end
+// up in the WAV.
+func (f *FFmpeg) ToWAV(ctx context.Context, src, dst string) error {
+	bin := f.Bin
+	if bin == "" {
+		bin = "ffmpeg"
+	}
+	// Input restrictions go BEFORE -i: placed after it they would apply to the output.
+	args := append([]string{"-y", "-v", "error"}, inputRestrictions...)
+	args = append(args, "-i", src, "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", "-f", "wav", dst)
+	cmd := exec.CommandContext(ctx, bin, args...)
+	cmd.WaitDelay = killGrace
+	if out, err := cmd.CombinedOutput(); err != nil {
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return fmt.Errorf("audio: ffmpeg: %w", ctxErr)
+		}
+		return fmt.Errorf("audio: ffmpeg: %w: %s", err, strings.TrimSpace(string(out)))
+	}
+	// A zero exit that wrote nothing is still a failure: never hand whisper a
+	// missing file and let the error surface three layers later.
+	if info, err := os.Stat(dst); err != nil || info.Size() == 0 {
+		return fmt.Errorf("audio: ffmpeg wrote no output at %s", dst)
+	}
+	return nil
+}

internal/adapters/audio/ffmpeg_test.go

@@ -0,0 +1,79 @@
+package audio_test
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/audio"
+)
+
+func TestFFmpegToWAV_AsksForSixteenKilohertzMonoPCMAlways(t *testing.T) {
+	// Always transcode, even when the input already is 16 kHz mono: a Teams export
+	// often is, and the point is to not ASSUME (ADR-033). Records the argv.
+	rec := filepath.Join(t.TempDir(), "argv")
+	bin := stub(t, `printf '%s\n' "$@" > `+rec+`
+for a; do last="$a"; done
+printf data > "$last"`)
+
+	err := (&audio.FFmpeg{Bin: bin}).ToWAV(context.Background(), "/spool/in", filepath.Join(t.TempDir(), "out.wav"))
+
+	require.NoError(t, err)
+	raw, err := os.ReadFile(rec)
+	require.NoError(t, err)
+	argv := strings.Split(strings.TrimSpace(string(raw)), "\n")
+	joined := " " + strings.Join(argv, " ") + " "
+	for _, want := range []string{" -ac 1 ", " -ar 16000 ", " -c:a pcm_s16le ", " -vn ", " -i /spool/in "} {
+		assert.Contains(t, joined, want)
+	}
+	assert.True(t, strings.HasSuffix(strings.TrimSpace(joined), "out.wav"), "the output path is the last argument")
+}
+
+func TestFFmpegToWAV_NonzeroExitIsAnErrorCarryingStderr(t *testing.T) {
+	bin := stub(t, `echo "moov atom not found" >&2; exit 1`)
+
+	err := (&audio.FFmpeg{Bin: bin}).ToWAV(context.Background(), "/in", filepath.Join(t.TempDir(), "o.wav"))
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "moov atom not found")
+}
+
+func TestFFmpegToWAV_ZeroExitWithNoOutputIsAnError(t *testing.T) {
+	bin := stub(t, `exit 0`)
+
+	err := (&audio.FFmpeg{Bin: bin}).ToWAV(context.Background(), "/in", filepath.Join(t.TempDir(), "never-written.wav"))
+
+	require.Error(t, err)
+}
+
+func TestFFmpegToWAV_MissingBinaryIsAnError(t *testing.T) {
+	err := (&audio.FFmpeg{Bin: filepath.Join(t.TempDir(), "no-ffmpeg")}).ToWAV(context.Background(), "/in", "/out.wav")
+
+	require.Error(t, err)
+	assert.False(t, errors.Is(err, context.Canceled))
+}
+
+func TestFFmpegToWAV_RestrictsWhatTheFileMayMakeFFmpegOpen(t *testing.T) {
+	rec := filepath.Join(t.TempDir(), "argv")
+	bin := stub(t, `printf '%s\n' "$@" > `+rec+`
+for a; do last="$a"; done
+printf data > "$last"`)
+
+	err := (&audio.FFmpeg{Bin: bin}).ToWAV(context.Background(), "/spool/in", filepath.Join(t.TempDir(), "o.wav"))
+
+	require.NoError(t, err)
+	args := argvOf(t, rec)
+	pw, fw, in := indexOf(args, "-protocol_whitelist"), indexOf(args, "-format_whitelist"), indexOf(args, "-i")
+	require.GreaterOrEqual(t, pw, 0, "argv: %v", args)
+	require.GreaterOrEqual(t, fw, 0, "argv: %v", args)
+	assert.Equal(t, "file,pipe", args[pw+1])
+	assert.Equal(t, audio.AllowedDemuxers, args[fw+1])
+	assert.Less(t, pw, in, "input options must come BEFORE -i or ffmpeg applies them to the output")
+	assert.Less(t, fw, in)
+}

internal/adapters/audio/ffprobe.go

@@ -0,0 +1,109 @@
+// Package audio holds the adapters that inspect and convert user-supplied audio
+// with ffmpeg's tools (ADR-033). They sit behind small ports so the use case is
+// tested with fakes and only this package knows a subprocess is involved.
+package audio
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os/exec"
+	"strconv"
+	"time"
+
+	"git.d-ma.be/mathias/tapir/internal/uploads"
+)
+
+// FFprobe implements uploads.Prober by running ffprobe on the spooled file.
+type FFprobe struct {
+	// Bin is the ffprobe executable ("ffprobe" resolves via PATH).
+	Bin string
+}
+
+// AllowedDemuxers are the input formats an upload may be. The input is
+// attacker-supplied, and a file's CONTENT can tell ffmpeg to open other files or
+// URLs (HLS and concat playlists, image2 sequences, network demuxers). Recent
+// ffmpeg refuses the ones tried (7.0.2: HLS without a .m3u8 name is not sniffed,
+// concat rejects unsafe paths), but that is version luck; this list is not. It
+// holds the containers real recordings use and none of the playlist or network
+// formats. "mov" covers .mp4/.m4a/.3gp; "matroska" covers .webm.
+const AllowedDemuxers = "wav,mov,mp4,m4a,3gp,mp3,ogg,matroska,webm,flac,aac,opus,aiff,amr,asf"
+
+// inputRestrictions are ffmpeg/ffprobe INPUT options and must precede the input.
+// Local files and pipes only: no network, no other protocols.
+var inputRestrictions = []string{"-protocol_whitelist", "file,pipe", "-format_whitelist", AllowedDemuxers}
+
+// killGrace bounds how long Probe waits for a cancelled ffprobe's pipes to close.
+const killGrace = 2 * time.Second
+
+// Probe runs ffprobe and classifies the outcome. A non-zero exit means ffprobe
+// looked at the file and could not read it: that is the FILE's fault and returns
+// uploads.ErrUnreadable. A missing binary, a cancelled context or unparsable
+// output is OURS and is returned as an ordinary error, so it is never reported to
+// the user as their file being bad.
+func (f *FFprobe) Probe(ctx context.Context, path string) (uploads.Probe, error) {
+	bin := f.Bin
+	if bin == "" {
+		bin = "ffprobe"
+	}
+	args := append([]string{"-v", "error"}, inputRestrictions...)
+	args = append(args, "-print_format", "json", "-show_format", "-show_streams", path)
+	cmd := exec.CommandContext(ctx, bin, args...)
+	cmd.WaitDelay = killGrace
+	out, err := cmd.Output()
+	if err != nil {
+		if ctxErr := ctx.Err(); ctxErr != nil {
+			return uploads.Probe{}, fmt.Errorf("audio: ffprobe: %w", ctxErr)
+		}
+		var exit *exec.ExitError
+		if errors.As(err, &exit) {
+			return uploads.Probe{}, fmt.Errorf("%w: ffprobe: %s", uploads.ErrUnreadable, exit.Stderr)
+		}
+		return uploads.Probe{}, fmt.Errorf("audio: run ffprobe: %w", err)
+	}
+	p, err := ParseProbe(out)
+	if err != nil {
+		return uploads.Probe{}, fmt.Errorf("audio: ffprobe output: %w", err)
+	}
+	return p, nil
+}
+
+// probeJSON is the subset of `ffprobe -print_format json` output that matters.
+type probeJSON struct {
+	Streams []struct {
+		CodecType   string `json:"codec_type"`
+		Disposition struct {
+			AttachedPic int `json:"attached_pic"`
+		} `json:"disposition"`
+	} `json:"streams"`
+	Format struct {
+		Duration string `json:"duration"`
+	} `json:"format"`
+}
+
+// ParseProbe turns ffprobe's JSON into a uploads.Probe. A video stream that is
+// only attached cover art (an mp3/m4a with an album picture) is not video. A
+// missing or "N/A" duration yields zero, which uploads.Validate rejects as
+// unreadable rather than accepting an empty recording.
+func ParseProbe(data []byte) (uploads.Probe, error) {
+	var j probeJSON
+	if err := json.Unmarshal(data, &j); err != nil {
+		return uploads.Probe{}, fmt.Errorf("decode: %w", err)
+	}
+	var p uploads.Probe
+	for _, s := range j.Streams {
+		switch s.CodecType {
+		case "audio":
+			p.HasAudio = true
+		case "video":
+			if s.Disposition.AttachedPic == 0 {
+				p.HasVideo = true
+			}
+		}
+	}
+	if secs, err := strconv.ParseFloat(j.Format.Duration, 64); err == nil && secs > 0 {
+		p.Duration = time.Duration(secs * float64(time.Second))
+	}
+	return p, nil
+}

internal/adapters/audio/ffprobe_test.go

@@ -0,0 +1,186 @@
+package audio_test
+
+import (
+	"context"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/audio"
+	"git.d-ma.be/mathias/tapir/internal/uploads"
+)
+
+func TestParseProbe(t *testing.T) {
+	tests := []struct {
+		name string
+		json string
+		want uploads.Probe
+	}{
+		{
+			name: "audio-only m4a",
+			json: `{"streams":[{"codec_type":"audio","disposition":{"attached_pic":0}}],"format":{"duration":"2701.5"}}`,
+			want: uploads.Probe{Duration: 2701*time.Second + 500*time.Millisecond, HasAudio: true},
+		},
+		{
+			name: "mp4 with a real video stream",
+			json: `{"streams":[{"codec_type":"video","disposition":{"attached_pic":0}},{"codec_type":"audio"}],"format":{"duration":"240.0"}}`,
+			want: uploads.Probe{Duration: 240 * time.Second, HasAudio: true, HasVideo: true},
+		},
+		{
+			name: "mp3 whose only video stream is attached cover art is NOT video",
+			json: `{"streams":[{"codec_type":"audio"},{"codec_type":"video","disposition":{"attached_pic":1}}],"format":{"duration":"60"}}`,
+			want: uploads.Probe{Duration: 60 * time.Second, HasAudio: true},
+		},
+		{
+			name: "no streams at all",
+			json: `{"streams":[],"format":{"duration":"10"}}`,
+			want: uploads.Probe{Duration: 10 * time.Second},
+		},
+		{
+			name: "duration absent means zero, which Validate rejects as unreadable",
+			json: `{"streams":[{"codec_type":"audio"}],"format":{}}`,
+			want: uploads.Probe{HasAudio: true},
+		},
+		{
+			name: "duration reported as N/A means zero",
+			json: `{"streams":[{"codec_type":"audio"}],"format":{"duration":"N/A"}}`,
+			want: uploads.Probe{HasAudio: true},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := audio.ParseProbe([]byte(tt.json))
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestParseProbe_GarbageIsAnError(t *testing.T) {
+	_, err := audio.ParseProbe([]byte("not json"))
+	assert.Error(t, err)
+}
+
+// stub writes an executable shell script standing in for ffprobe. This is a fake
+// at the process boundary: the real binary is not on every host (it is not on
+// koala), and what is under test is how Probe drives and interprets a process.
+func stub(t *testing.T, body string) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "ffprobe")
+	require.NoError(t, os.WriteFile(p, []byte("#!/bin/sh\n"+body+"\n"), 0o755))
+	return p
+}
+
+func TestFFprobeProbe_ParsesWhatTheProcessPrints(t *testing.T) {
+	bin := stub(t, `echo '{"streams":[{"codec_type":"audio"}],"format":{"duration":"90"}}'`)
+
+	got, err := (&audio.FFprobe{Bin: bin}).Probe(context.Background(), "/ignored")
+
+	require.NoError(t, err)
+	assert.Equal(t, uploads.Probe{Duration: 90 * time.Second, HasAudio: true}, got)
+}
+
+func TestFFprobeProbe_PassesTheFilePathAsTheLastArgument(t *testing.T) {
+	out := filepath.Join(t.TempDir(), "args")
+	bin := stub(t, `for a; do last="$a"; done; printf '%s' "$last" > `+out+`
+echo '{"streams":[{"codec_type":"audio"}],"format":{"duration":"1"}}'`)
+
+	_, err := (&audio.FFprobe{Bin: bin}).Probe(context.Background(), "/spool/upload-123")
+
+	require.NoError(t, err)
+	got, err := os.ReadFile(out)
+	require.NoError(t, err)
+	assert.Equal(t, "/spool/upload-123", string(got))
+}
+
+func TestFFprobeProbe_NonzeroExitMeansTheFileIsUnreadable(t *testing.T) {
+	bin := stub(t, `echo "Invalid data found when processing input" >&2; exit 1`)
+
+	_, err := (&audio.FFprobe{Bin: bin}).Probe(context.Background(), "/x")
+
+	assert.ErrorIs(t, err, uploads.ErrUnreadable)
+}
+
+func TestFFprobeProbe_MissingBinaryIsOurFaultNotAnUnreadableFile(t *testing.T) {
+	_, err := (&audio.FFprobe{Bin: filepath.Join(t.TempDir(), "no-such-ffprobe")}).Probe(context.Background(), "/x")
+
+	require.Error(t, err)
+	assert.False(t, errors.Is(err, uploads.ErrUnreadable),
+		"a missing ffprobe must not be reported to the user as their file being bad")
+}
+
+func TestFFprobeProbe_StopsWhenTheContextIsCancelled(t *testing.T) {
+	bin := stub(t, `sleep 30`)
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+
+	start := time.Now()
+	_, err := (&audio.FFprobe{Bin: bin}).Probe(ctx, "/x")
+
+	require.Error(t, err)
+	assert.Less(t, time.Since(start), 5*time.Second)
+	assert.False(t, errors.Is(err, uploads.ErrUnreadable), "a timeout is not a verdict on the file")
+}
+
+// argvStub records the arguments it was called with into a file and then behaves as
+// a successful ffprobe, so a test can assert exactly what the process was asked.
+func argvStub(t *testing.T) (bin, argvFile string) {
+	t.Helper()
+	argvFile = filepath.Join(t.TempDir(), "argv")
+	bin = stub(t, `printf '%s\n' "$@" > `+argvFile+`
+echo '{"streams":[{"codec_type":"audio"}],"format":{"duration":"1"}}'`)
+	return bin, argvFile
+}
+
+func argvOf(t *testing.T, file string) []string {
+	t.Helper()
+	raw, err := os.ReadFile(file)
+	require.NoError(t, err)
+	return strings.Split(strings.TrimSpace(string(raw)), "\n")
+}
+
+func indexOf(args []string, want string) int {
+	for i, a := range args {
+		if a == want {
+			return i
+		}
+	}
+	return -1
+}
+
+func TestFFprobeProbe_RestrictsWhatTheFileMayMakeFFmpegOpen(t *testing.T) {
+	// The input is attacker-supplied. ffmpeg can be told by a file's CONTENT to open
+	// other files or URLs (HLS and concat playlists); recent versions refuse by
+	// default, but that is version luck. Pin it: local files and pipes only, and
+	// only the demuxers real audio recordings use.
+	bin, argvFile := argvStub(t)
+
+	_, err := (&audio.FFprobe{Bin: bin}).Probe(context.Background(), "/spool/upload-1")
+
+	require.NoError(t, err)
+	args := argvOf(t, argvFile)
+	pw := indexOf(args, "-protocol_whitelist")
+	require.GreaterOrEqual(t, pw, 0, "argv: %v", args)
+	assert.Equal(t, "file,pipe", args[pw+1])
+	fw := indexOf(args, "-format_whitelist")
+	require.GreaterOrEqual(t, fw, 0, "argv: %v", args)
+	assert.Equal(t, audio.AllowedDemuxers, args[fw+1])
+	assert.Equal(t, "/spool/upload-1", args[len(args)-1], "the path stays the last argument")
+}
+
+func TestAllowedDemuxers_ExcludeThePlaylistFormats(t *testing.T) {
+	for _, bad := range []string{"concat", "hls", "applehttp", "dash", "rtsp", "sdp", "image2"} {
+		assert.NotContains(t, strings.Split(audio.AllowedDemuxers, ","), bad,
+			"%s can make ffmpeg open other files or URLs named inside the upload", bad)
+	}
+	for _, good := range []string{"wav", "mov", "mp4", "m4a", "mp3", "ogg", "matroska", "flac"} {
+		assert.Contains(t, strings.Split(audio.AllowedDemuxers, ","), good)
+	}
+}

internal/adapters/audio/hostile_live_test.go

@@ -0,0 +1,32 @@
+package audio_test
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/audio"
+	"git.d-ma.be/mathias/tapir/internal/uploads"
+)
+
+// TestFFprobeLive_HostilePlaylistsAreRefusedAndRealAudioIsNot runs the REAL ffprobe
+// (opt-in: TAPIR_LIVE_FFPROBE) on crafted concat/HLS files and on a real m4a.
+func TestFFprobeLive_HostilePlaylistsAreRefusedAndRealAudioIsNot(t *testing.T) {
+	bin := os.Getenv("TAPIR_LIVE_FFPROBE")
+	if bin == "" {
+		t.Skip("set TAPIR_LIVE_FFPROBE (and TAPIR_LIVE_HOSTILE_DIR, TAPIR_LIVE_M4A) to run against the real ffprobe")
+	}
+	p := &audio.FFprobe{Bin: bin}
+	for _, name := range []string{"up-concat", "up-hls"} {
+		_, err := p.Probe(context.Background(), os.Getenv("TAPIR_LIVE_HOSTILE_DIR")+"/"+name)
+		assert.ErrorIs(t, err, uploads.ErrUnreadable, name)
+	}
+	got, err := p.Probe(context.Background(), os.Getenv("TAPIR_LIVE_M4A"))
+	require.NoError(t, err)
+	assert.True(t, got.HasAudio)
+	assert.False(t, got.HasVideo)
+	assert.InDelta(t, 82.5, got.Duration.Seconds(), 1)
+}

internal/adapters/chat/chat.go

@@ -0,0 +1,188 @@
+// 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
+	// MaxChars, when positive, overrides the Service's transcript budget for this
+	// request. The Service default is sized for YouTube captions (~22 minutes of
+	// speech); an uploaded recording is much longer, and truncation keeps only the
+	// head (ADR-033). Zero or negative means "use the Service default".
+	MaxChars int
+}
+
+// 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("")
+	}
+
+	budget := s.maxChars
+	if req.MaxChars > 0 {
+		budget = req.MaxChars
+	}
+	transcript, truncated := truncate(req.Transcript, budget)
+	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/chat/maxchars_test.go

@@ -0,0 +1,52 @@
+package chat
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// A Request may carry its own transcript budget. The Service's cap (18,000 chars by
+// default) is sized for YouTube captions; an uploaded recording is much longer
+// (~50,000 chars an hour), and keeping only the head of it would answer questions
+// about the last two-thirds of a meeting from text that does not contain them
+// (ADR-033). The per-request value overrides; zero means "the service default".
+
+func TestAnswerMaxCharsOverridesTheServiceCap(t *testing.T) {
+	tests := []struct {
+		name          string
+		serviceCap    int
+		requestCap    int
+		transcriptLen int
+		wantKept      int
+		wantTruncated bool
+	}{
+		{"request cap above the service cap keeps the whole transcript", 10, 100, 50, 50, false},
+		{"request cap below the service cap bounds tighter", 100, 10, 50, 10, true},
+		{"zero request cap falls back to the service cap", 20, 0, 50, 20, true},
+		{"negative request cap is treated as unset", 20, -1, 50, 20, true},
+		{"request cap exceeded is reported as truncated", 10, 30, 50, 30, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			f := &factory{answer: "answer"}
+			s := New(f.make, []string{"koala/phi4-mini"}, tt.serviceCap)
+
+			reply, err := s.Answer(context.Background(), Request{
+				Model:      "koala/phi4-mini",
+				Transcript: strings.Repeat("x", tt.transcriptLen),
+				Question:   "what was decided?",
+				MaxChars:   tt.requestCap,
+			})
+			if err != nil {
+				t.Fatalf("Answer: %v", err)
+			}
+			if got := strings.Count(f.used.lastSystem, "x"); got != tt.wantKept {
+				t.Errorf("transcript chars sent = %d, want %d", got, tt.wantKept)
+			}
+			if reply.Truncated != tt.wantTruncated {
+				t.Errorf("Truncated = %v, want %v", reply.Truncated, tt.wantTruncated)
+			}
+		})
+	}
+}

internal/adapters/llm/client.go

@@ -32,6 +32,7 @@ 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
@@ -50,6 +51,14 @@ func WithMaxTokens(n int) Option {
 	}
 }
 
+// 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, opts ...Option) *Client {
 	c := &Client{
@@ -81,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.
@@ -152,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

@@ -85,6 +85,30 @@ func TestClient_WithMaxTokens(t *testing.T) {
 	}
 }
 
+// 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/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/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_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 (

internal/adapters/store/migrate_test.go

@@ -3,6 +3,7 @@ package store_test
 import (
 	"context"
 	"database/sql"
+	"errors"
 	"os"
 	"testing"
 
@@ -34,6 +35,30 @@ func fileMigrator(t *testing.T) *migrate.Migrate {
 	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()
@@ -53,23 +78,15 @@ func TestMigration010LoginEventsUpDown(t *testing.T) {
 	require.True(t, loginEventsExists(t), "login_events must exist at latest migration")
 
 	m := fileMigrator(t)
-	// 011..015 sit above 010; step them down first so 010 is exercised in isolation.
-	require.NoError(t, m.Steps(-1), "down 015 reshapes transcripts, login_events intact")
-	require.True(t, loginEventsExists(t), "015 down leaves login_events intact")
-	require.NoError(t, m.Steps(-1), "down 014 drops channel_title, login_events intact")
-	require.True(t, loginEventsExists(t), "014 down leaves login_events intact")
-	require.NoError(t, m.Steps(-1), "down 013 drops channel_errors, login_events intact")
-	require.True(t, loginEventsExists(t), "013 down leaves login_events intact")
-	require.NoError(t, m.Steps(-1), "down 012 is a no-op, login_events intact")
-	require.True(t, loginEventsExists(t), "012 down leaves login_events intact")
-	require.NoError(t, m.Steps(-1), "down 011 must not touch login_events")
-	require.True(t, loginEventsExists(t), "011 down leaves login_events intact")
+	head := headVersion(t, m)
 
-	require.NoError(t, m.Steps(-1), "down 010 must drop login_events")
+	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")
 
-	require.NoError(t, m.Steps(6), "up must recreate 010 then re-apply 011..015")
+	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
@@ -91,19 +108,15 @@ func TestMigration011AutoSummarizeDefaultUpDown(t *testing.T) {
 	require.Equal(t, "true", autoSummarizeDefault(t), "011 sets the default to TRUE")
 
 	m := fileMigrator(t)
-	require.NoError(t, m.Steps(-1), "down 015 reshapes transcripts")
-	require.NoError(t, m.Steps(-1), "down 014 drops channel_title")
-	require.NoError(t, m.Steps(-1), "down 013 drops channel_errors")
-	require.NoError(t, m.Steps(-1), "down 012 is a no-op")
-	require.NoError(t, m.Steps(-1), "down 011 reverts the column default")
+	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")
 
-	require.NoError(t, m.Steps(1), "up 011 re-applies the TRUE default")
+	migrateTo(t, m, 11) // up 011 re-applies the TRUE default
 	require.Equal(t, "true", autoSummarizeDefault(t))
-	require.NoError(t, m.Steps(1), "up 012 runs clean (no FORCE RLS on fresh schema)")
-	require.NoError(t, m.Steps(1), "up 013 creates channel_errors")
-	require.NoError(t, m.Steps(1), "up 014 recreates channel_title")
-	require.NoError(t, m.Steps(1), "up 015 reshapes transcripts to shared")
+
+	migrateTo(t, m, head) // restore to HEAD for sibling tests
 }
 
 // channelTitleExists reports whether videos.channel_title is present.
@@ -123,14 +136,15 @@ func TestMigration014VideoChannelTitleUpDown(t *testing.T) {
 	require.True(t, channelTitleExists(t), "channel_title exists at latest migration")
 
 	m := fileMigrator(t)
-	require.NoError(t, m.Steps(-1), "down 015 reshapes transcripts, channel_title intact")
-	require.True(t, channelTitleExists(t), "015 down leaves channel_title intact")
-	require.NoError(t, m.Steps(-1), "down 014 must drop channel_title")
+	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")
 
-	require.NoError(t, m.Steps(1), "up 014 must recreate channel_title")
+	migrateTo(t, m, 14) // up 014 recreates channel_title
 	require.True(t, channelTitleExists(t), "channel_title must be restored after the up migration")
-	require.NoError(t, m.Steps(1), "up 015 restores the shared transcripts shape (HEAD)")
+
+	migrateTo(t, m, head) // restore to HEAD for sibling tests
 }
 
 // TestMigration012FixAutoSummarizeRLS proves 012 runs cleanly and flips any
@@ -141,7 +155,11 @@ func TestMigration012FixAutoSummarizeRLS(t *testing.T) {
 
 	// Round-trip: down 012, then up 012 — must be idempotent.
 	m := fileMigrator(t)
-	require.NoError(t, m.Steps(-1), "down 012 must not error")
-	require.NoError(t, m.Steps(1), "up 012 must re-apply cleanly")
+	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/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/migrations/017_uploaded_transcripts.down.sql

@@ -0,0 +1,3 @@
+-- Drops the private uploaded-transcript store and every transcript in it. There
+-- is no revert of the data: the original audio was never kept (ADR-033).
+DROP TABLE uploaded_transcripts;

internal/adapters/store/migrations/017_uploaded_transcripts.up.sql

@@ -0,0 +1,48 @@
+-- Migration 017: uploaded_transcripts — PRIVATE transcripts of audio a user
+-- uploaded themselves (ADR-033, tapir#33).
+--
+-- This is deliberately NOT the shared `transcripts` table (migration 015,
+-- ADR-021). That table is non-RLS on the explicit grounds that it holds only
+-- public caption content and nothing user-identifying. A recorded meeting is the
+-- opposite: private third-party content owned by exactly one user. Reusing
+-- `transcripts` — or adding a user_id to it with a partial policy — would put a
+-- private row in the one table the isolation test asserts is shared, and would
+-- pass CI green. A separate table keeps ADR-021's exception singular.
+--
+-- Row-level security follows migration 003 exactly: ENABLE + FORCE (the app
+-- connects as the table owner, which bypasses RLS unless forced), and a policy
+-- keyed off the per-request GUC tapir.current_user_id. With no GUC set the
+-- predicate is NULL and the table is deny-all.
+--
+-- The original audio is never stored (ADR-033): this row is all that is kept.
+-- segments holds the timestamped cues; re-transcribing 90 minutes costs ~7
+-- minutes, so discarding the timestamps would be irreversible.
+CREATE TABLE uploaded_transcripts (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id       UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    title         TEXT NOT NULL,
+    status        TEXT NOT NULL DEFAULT 'queued'
+                  CHECK (status IN ('queued', 'transcribing', 'done', 'failed')),
+    content       TEXT,
+    segments      JSONB,
+    endpoint      TEXT,             -- which backend served it (iguana | berget); a quality fact
+    audio_seconds DOUBLE PRECISION,
+    error_kind    TEXT,             -- typed, never a provider's error string (ADR-033)
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    finished_at   TIMESTAMPTZ,
+    CONSTRAINT uploaded_transcripts_done_has_content
+        CHECK (status <> 'done' OR content IS NOT NULL),
+    CONSTRAINT uploaded_transcripts_failed_has_error_kind
+        CHECK (status <> 'failed' OR error_kind IS NOT NULL)
+);
+
+CREATE INDEX idx_uploaded_transcripts_user ON uploaded_transcripts (user_id, created_at DESC);
+
+ALTER TABLE uploaded_transcripts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE uploaded_transcripts FORCE ROW LEVEL SECURITY;
+CREATE POLICY uploaded_transcripts_isolation ON uploaded_transcripts
+    FOR ALL
+    USING (user_id = current_setting('tapir.current_user_id', true)::uuid);
+
+COMMENT ON TABLE uploaded_transcripts IS
+    'PRIVATE per-user transcripts of user-supplied audio. RLS-scoped (ADR-012). Never merge into the shared transcripts table (ADR-021, ADR-033).';

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

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"sort"
+	"time"
 
 	"github.com/jackc/pgx/v5"
 )
@@ -32,7 +33,12 @@ type UserActiveWeeks struct {
 // 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.
-func (s *Store) ActiveWeeks(ctx context.Context) ([]UserActiveWeeks, error) {
+// 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
@@ -40,7 +46,7 @@ func (s *Store) ActiveWeeks(ctx context.Context) ([]UserActiveWeeks, error) {
 
 	out := make([]UserActiveWeeks, 0, len(userIDs))
 	for _, uid := range userIDs {
-		row, err := s.activeWeeksFor(ctx, uid)
+		row, err := s.activeWeeksFor(ctx, uid, since)
 		if err != nil {
 			return nil, err
 		}
@@ -85,18 +91,18 @@ func (s *Store) identityUserIDs(ctx context.Context) ([]string, error) {
 // 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) (UserActiveWeeks, error) {
+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
+			       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
+			       FROM summary_actions WHERE user_id = $1 AND acted_at >= $2
 			 )
-			 SELECT count(DISTINCT wk) FROM weeks`, userID).Scan(&res.ActiveWeeks); err != nil {
+			 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,

internal/adapters/store/report_test.go

@@ -3,6 +3,7 @@ package store_test
 import (
 	"context"
 	"testing"
+	"time"
 
 	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/stretchr/testify/require"
@@ -54,7 +55,7 @@ func TestActiveWeeksCountsDistinctWeeksAcrossReadsAndActs(t *testing.T) {
 		   ($1, 'vid-2', 'saved',   '2026-01-19T18:00:00Z')`, userA)
 	require.NoError(t, err)
 
-	got, err := s.ActiveWeeks(ctx)
+	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")
 
@@ -72,7 +73,33 @@ func TestActiveWeeksEmptyWhenNoUsers(t *testing.T) {
 	s := newStore(t)
 	resetDB(t, rawPool(t))
 
-	got, err := s.ActiveWeeks(ctx)
+	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/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)
 }
 

internal/adapters/store/summarize_mode_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"
 )
 
 // seedBareVideo inserts a videos row with no summary, so the all-videos read and

internal/adapters/store/transcript.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"
 )
 
 // GetTranscript returns the shared, stored transcript for a video keyed by the

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

@@ -6,9 +6,9 @@ import (
 
 	"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 shared TranscriptStore port (ADR-021).

internal/adapters/store/uploaded_transcripts.go

@@ -0,0 +1,199 @@
+package store
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"git.d-ma.be/mathias/tapir/internal/domain"
+)
+
+// ErrUploadNotFound is returned when an uploaded transcript does not exist OR is
+// not the caller's. The two are deliberately indistinguishable: a non-owner learns
+// nothing about whether someone else's upload exists (ADR-033).
+var ErrUploadNotFound = errors.New("store: uploaded transcript not found")
+
+// Uploaded transcripts are PRIVATE per-user content, stored in their own
+// RLS-scoped table (migration 017) — never in the shared `transcripts` (ADR-021).
+// Every method goes through withUser, so row-level security confines it to the
+// caller's rows; each statement ALSO names user_id in its predicate, so the
+// isolation does not rest on a single mechanism and stays testable under the
+// superuser connection the unit tests use.
+
+// CreateUpload records a new upload in the queued state and returns its id.
+func (s *Store) CreateUpload(ctx context.Context, userID, title string) (string, error) {
+	var id string
+	if err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		return tx.QueryRow(ctx,
+			`INSERT INTO uploaded_transcripts (user_id, title) VALUES ($1, $2) RETURNING id`,
+			userID, title).Scan(&id)
+	}); err != nil {
+		return "", fmt.Errorf("store: create upload: %w", err)
+	}
+	return id, nil
+}
+
+// StartTranscribing moves an upload to transcribing.
+func (s *Store) StartTranscribing(ctx context.Context, userID, id string) error {
+	return s.updateUpload(ctx, userID, id, "start transcribing",
+		`UPDATE uploaded_transcripts SET status = 'transcribing'
+		  WHERE id = $1 AND user_id = $2`)
+}
+
+// CompleteUpload stores the finished transcription and moves the upload to done.
+func (s *Store) CompleteUpload(ctx context.Context, userID, id string, t domain.Transcription) error {
+	segs, err := json.Marshal(t.Segments)
+	if err != nil {
+		return fmt.Errorf("store: complete upload: marshal segments: %w", err)
+	}
+	return s.updateUpload(ctx, userID, id, "complete upload",
+		`UPDATE uploaded_transcripts
+		    SET status = 'done', content = $3, segments = $4, endpoint = $5,
+		        audio_seconds = $6, error_kind = NULL, finished_at = NOW()
+		  WHERE id = $1 AND user_id = $2`,
+		t.Text, segs, t.Endpoint, t.AudioSeconds)
+}
+
+// FailUpload moves an upload to failed with a typed reason.
+func (s *Store) FailUpload(ctx context.Context, userID, id string, kind domain.UploadErrorKind) error {
+	return s.updateUpload(ctx, userID, id, "fail upload",
+		`UPDATE uploaded_transcripts
+		    SET status = 'failed', error_kind = $3, finished_at = NOW()
+		  WHERE id = $1 AND user_id = $2`,
+		string(kind))
+}
+
+// updateUpload runs one UPDATE keyed on ($1 = id, $2 = userID) plus extra args,
+// and maps "no row touched" to ErrUploadNotFound — which is what a write to another
+// user's upload looks like under RLS (the row is invisible, not forbidden).
+func (s *Store) updateUpload(ctx context.Context, userID, id, op, sql string, args ...any) error {
+	all := append([]any{id, userID}, args...)
+	return s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		ct, err := tx.Exec(ctx, sql, all...)
+		if err != nil {
+			return fmt.Errorf("store: %s: %w", op, err)
+		}
+		if ct.RowsAffected() == 0 {
+			return ErrUploadNotFound
+		}
+		return nil
+	})
+}
+
+// GetUpload returns one of the caller's uploads, including the transcript text.
+func (s *Store) GetUpload(ctx context.Context, userID, id string) (*domain.UploadedTranscript, error) {
+	var u domain.UploadedTranscript
+	err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		row := tx.QueryRow(ctx, uploadSelect+` WHERE id = $1 AND user_id = $2`, id, userID)
+		return scanUpload(row, &u, true)
+	})
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, ErrUploadNotFound
+	}
+	if err != nil {
+		return nil, fmt.Errorf("store: get upload: %w", err)
+	}
+	return &u, nil
+}
+
+// ListUploads returns the caller's uploads, newest first, WITHOUT transcript text
+// or segments: a list view must not drag every transcript along.
+func (s *Store) ListUploads(ctx context.Context, userID string) ([]domain.UploadedTranscript, error) {
+	var out []domain.UploadedTranscript
+	err := s.withUser(ctx, userID, func(tx pgx.Tx) error {
+		rows, err := tx.Query(ctx, uploadSelect+` WHERE user_id = $1 ORDER BY created_at DESC, id`, userID)
+		if err != nil {
+			return err
+		}
+		defer rows.Close()
+		for rows.Next() {
+			var u domain.UploadedTranscript
+			if err := scanUpload(rows, &u, false); err != nil {
+				return err
+			}
+			out = append(out, u)
+		}
+		return rows.Err()
+	})
+	if err != nil {
+		return nil, fmt.Errorf("store: list uploads: %w", err)
+	}
+	return out, nil
+}
+
+// FailInterruptedUploads is the start-up sweep. The audio of an upload is never
+// retained (ADR-033), so a job that was queued or transcribing when the process
+// stopped can never resume; leaving it would be a stuck spinner. Every such row,
+// for every user, becomes failed/interrupted and the user re-uploads. It
+// enumerates users from the un-RLS'd identity map and scopes each pass with
+// withUser, exactly as scheduled discovery does (ADR-018). Returns rows failed.
+func (s *Store) FailInterruptedUploads(ctx context.Context) (int, error) {
+	users, err := s.ListAllUsers(ctx)
+	if err != nil {
+		return 0, fmt.Errorf("store: fail interrupted uploads: %w", err)
+	}
+	total := 0
+	for _, u := range users {
+		err := s.withUser(ctx, u.UserID, func(tx pgx.Tx) error {
+			ct, err := tx.Exec(ctx,
+				`UPDATE uploaded_transcripts
+				    SET status = 'failed', error_kind = $2, finished_at = NOW()
+				  WHERE user_id = $1 AND status IN ('queued', 'transcribing')`,
+				u.UserID, string(domain.UploadErrInterrupted))
+			total += int(ct.RowsAffected())
+			return err
+		})
+		if err != nil {
+			return total, fmt.Errorf("store: fail interrupted uploads: user %s: %w", u.UserID, err)
+		}
+	}
+	return total, nil
+}
+
+const uploadSelect = `SELECT id, user_id, title, status, content, segments, endpoint,
+       audio_seconds, error_kind, created_at, finished_at FROM uploaded_transcripts`
+
+// scanUpload scans one uploadSelect row. withText controls whether the transcript
+// body and segments are kept (GetUpload) or dropped (ListUploads).
+func scanUpload(row pgx.Row, u *domain.UploadedTranscript, withText bool) error {
+	var (
+		status, errKind, endpoint, content *string
+		segments                           []byte
+		seconds                            *float64
+		finished                           *time.Time
+	)
+	if err := row.Scan(&u.ID, &u.UserID, &u.Title, &status, &content, &segments, &endpoint,
+		&seconds, &errKind, &u.CreatedAt, &finished); err != nil {
+		return err
+	}
+	u.Status = domain.UploadStatus(deref(status))
+	u.Endpoint = deref(endpoint)
+	u.ErrorKind = domain.UploadErrorKind(deref(errKind))
+	if seconds != nil {
+		u.AudioSeconds = *seconds
+	}
+	if finished != nil {
+		u.FinishedAt = *finished
+	}
+	if !withText {
+		return nil
+	}
+	u.Content = deref(content)
+	if len(segments) > 0 {
+		if err := json.Unmarshal(segments, &u.Segments); err != nil {
+			return fmt.Errorf("unmarshal segments: %w", err)
+		}
+	}
+	return nil
+}
+
+func deref(s *string) string {
+	if s == nil {
+		return ""
+	}
+	return *s
+}

internal/adapters/store/uploaded_transcripts_isolation_test.go

@@ -0,0 +1,196 @@
+package store_test
+
+import (
+	"context"
+	"sort"
+	"testing"
+
+	"github.com/jackc/pgx/v5/pgxpool"
+	"github.com/stretchr/testify/require"
+)
+
+// Isolation proof for ADR-033: an uploaded transcript is PRIVATE content owned by
+// one user, so it lives in its own RLS-scoped table — never in the shared,
+// non-RLS `transcripts` (ADR-021). These tests drive the database directly (raw
+// SQL as the non-superuser `app` role) so they observe row-level security itself,
+// not any application-layer WHERE clause. The superuser pool is used only to seed
+// and to read pg_catalog; it bypasses RLS and so must never be the pool whose
+// answers the assertions rest on.
+
+// seedUploadedTranscript inserts one finished upload for userID as the superuser
+// (RLS bypassed so both users' rows land regardless of any GUC) and returns its id.
+// The text is synthetic — this repo is public, and a real transcript must never
+// appear in it (#33).
+func seedUploadedTranscript(t *testing.T, super *pgxpool.Pool, userID, text string) string {
+	t.Helper()
+	ctx := context.Background()
+	_, err := super.Exec(ctx, `INSERT INTO users (id) VALUES ($1) ON CONFLICT DO NOTHING`, userID)
+	require.NoError(t, err)
+	var id string
+	require.NoError(t, super.QueryRow(ctx,
+		`INSERT INTO uploaded_transcripts (user_id, title, status, content)
+		 VALUES ($1, 'synthetic fixture', 'done', $2) RETURNING id`,
+		userID, text).Scan(&id))
+	return id
+}
+
+func TestUploadedTranscriptsRLS_ScopedReadsSeeOnlyOwnRows(t *testing.T) {
+	newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	seedUploadedTranscript(t, super, userA, "text owned by A")
+	seedUploadedTranscript(t, super, userB, "text owned by B")
+	app := appPool(t, super)
+
+	require.Equal(t, 0, scopedCount(t, app, "", "uploaded_transcripts"),
+		"no tapir.current_user_id must be deny-all: this proves RLS is live, not bypassed")
+	require.Equal(t, 1, scopedCount(t, app, userA, "uploaded_transcripts"),
+		"user A must see exactly its own upload")
+	require.Equal(t, 1, scopedCount(t, app, userB, "uploaded_transcripts"),
+		"user B must see exactly its own upload")
+
+	// Count alone cannot distinguish "A's row" from "B's row" — read the content.
+	var got string
+	ctx := context.Background()
+	tx, err := app.Begin(ctx)
+	require.NoError(t, err)
+	defer tx.Rollback(ctx) //nolint:errcheck
+	_, err = tx.Exec(ctx, `SELECT set_config('tapir.current_user_id', $1, true)`, userA)
+	require.NoError(t, err)
+	require.NoError(t, tx.QueryRow(ctx, `SELECT content FROM uploaded_transcripts`).Scan(&got))
+	require.Equal(t, "text owned by A", got, "A's scoped read must return A's text, never B's")
+}
+
+func TestUploadedTranscriptsRLS_CrossUserWritesAffectZeroRows(t *testing.T) {
+	newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	seedUploadedTranscript(t, super, userA, "text owned by A")
+	bID := seedUploadedTranscript(t, super, userB, "text owned by B")
+	app := appPool(t, super)
+
+	require.Equal(t, int64(0), scopedRowsAffected(t, app, userA,
+		`UPDATE uploaded_transcripts SET content = 'hacked' WHERE id = $1`, bID),
+		"user A scoped UPDATE must touch zero of B's uploads")
+	require.Equal(t, int64(0), scopedRowsAffected(t, app, userA,
+		`DELETE FROM uploaded_transcripts WHERE id = $1`, bID),
+		"user A scoped DELETE must touch zero of B's uploads")
+
+	var content string
+	require.NoError(t, super.QueryRow(context.Background(),
+		`SELECT content FROM uploaded_transcripts WHERE id = $1`, bID).Scan(&content))
+	require.Equal(t, "text owned by B", content, "B's upload must survive A's writes unchanged")
+}
+
+func TestUploadedTranscriptsRLS_InsertForAnotherUserIsRejected(t *testing.T) {
+	newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	seedUploadedTranscript(t, super, userA, "text owned by A")
+	_, err := super.Exec(context.Background(), `INSERT INTO users (id) VALUES ($1)`, userB)
+	require.NoError(t, err)
+	app := appPool(t, super)
+
+	ctx := context.Background()
+	tx, err := app.Begin(ctx)
+	require.NoError(t, err)
+	defer tx.Rollback(ctx) //nolint:errcheck
+	_, err = tx.Exec(ctx, `SELECT set_config('tapir.current_user_id', $1, true)`, userA)
+	require.NoError(t, err)
+
+	// Scoped as A, plant a row that claims to belong to B. The policy's WITH CHECK
+	// (defaulting to USING under FOR ALL) must refuse it.
+	_, err = tx.Exec(ctx,
+		`INSERT INTO uploaded_transcripts (user_id, title, status, content)
+		 VALUES ($1, 'planted', 'done', 'planted')`, userB)
+	require.Error(t, err, "a row scoped as A must not be insertable on behalf of B")
+	require.Contains(t, err.Error(), "row-level security")
+}
+
+func TestUploadedTranscripts_RowSecurityIsEnabledForcedAndKeyedByUser(t *testing.T) {
+	newStore(t)
+	super := rawPool(t)
+	ctx := context.Background()
+
+	var enabled, forced bool
+	require.NoError(t, super.QueryRow(ctx,
+		`SELECT relrowsecurity, relforcerowsecurity FROM pg_class
+		  WHERE oid = 'public.uploaded_transcripts'::regclass`).Scan(&enabled, &forced))
+	require.True(t, enabled, "uploaded_transcripts must have row-level security enabled")
+	require.True(t, forced,
+		"FORCE is what binds the table-owner role tapir; without it the policy is dead in production")
+
+	var userIDNotNull bool
+	require.NoError(t, super.QueryRow(ctx,
+		`SELECT is_nullable = 'NO' FROM information_schema.columns
+		  WHERE table_name = 'uploaded_transcripts' AND column_name = 'user_id'`).Scan(&userIDNotNull))
+	require.True(t, userIDNotNull, "an upload with no owner would match no policy and be unreachable")
+}
+
+func TestUploadedTranscripts_DeleteUserRemovesTheirUploads(t *testing.T) {
+	s := newStore(t)
+	super := rawPool(t)
+	resetDB(t, super)
+	seedUploadedTranscript(t, super, userA, "text owned by A")
+	bID := seedUploadedTranscript(t, super, userB, "text owned by B")
+
+	require.NoError(t, s.DeleteUser(context.Background(), userA))
+
+	var aRows, bRows int
+	ctx := context.Background()
+	require.NoError(t, super.QueryRow(ctx,
+		`SELECT count(*) FROM uploaded_transcripts WHERE user_id = $1`, userA).Scan(&aRows))
+	require.NoError(t, super.QueryRow(ctx,
+		`SELECT count(*) FROM uploaded_transcripts WHERE id = $1`, bID).Scan(&bRows))
+	require.Equal(t, 0, aRows, "deleting a user must remove their private transcripts (ON DELETE CASCADE)")
+	require.Equal(t, 1, bRows, "deleting A must not touch B's transcripts")
+}
+
+// rowSecurityOffTables are the public-schema tables that deliberately have row
+// security OFF. The list is exact on purpose: a NEW table added without RLS must
+// fail this test and force a decision, instead of passing CI by omission — the
+// failure mode ADR-033 names, where a naive reuse "leaks private content across
+// tenants and passes CI green".
+//
+//   - transcripts: shared public caption content, the single exception for CONTENT
+//     (ADR-021). It is the one that must never gain a private row.
+//   - user_identities: the Dex-subject -> user_id map, read at login before any
+//     user is known (migration 004). Holds no user content.
+//   - invitations: exists before the user does, so there is no user to scope by;
+//     the single-use token is the capability (migration 009).
+//   - schema_migrations: golang-migrate bookkeeping.
+//
+// #33 describes `transcripts` as "the only non-RLS table". That is true of content
+// and false of tables; this test asserts the real set.
+var rowSecurityOffTables = []string{
+	"invitations",
+	"schema_migrations",
+	"transcripts",
+	"user_identities",
+}
+
+func TestRowSecurityOffTablesAreExactlyTheKnownSet(t *testing.T) {
+	newStore(t)
+	super := rawPool(t)
+
+	rows, err := super.Query(context.Background(),
+		`SELECT c.relname FROM pg_class c
+		   JOIN pg_namespace n ON n.oid = c.relnamespace
+		  WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p') AND NOT c.relrowsecurity
+		  ORDER BY c.relname`)
+	require.NoError(t, err)
+	defer rows.Close()
+	var got []string
+	for rows.Next() {
+		var name string
+		require.NoError(t, rows.Scan(&name))
+		got = append(got, name)
+	}
+	require.NoError(t, rows.Err())
+
+	want := append([]string{}, rowSecurityOffTables...)
+	sort.Strings(want)
+	require.Equal(t, want, got,
+		"every public table must have row security ON unless it is in rowSecurityOffTables; "+
+			"adding a table here is a decision that needs an ADR")
+}

internal/adapters/store/uploaded_transcripts_test.go

@@ -0,0 +1,188 @@
+package store_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+)
+
+// These exercise the Store API over uploaded_transcripts. The test Store connects
+// as the superuser, which BYPASSES row-level security — so the cross-user cases
+// here prove the query's own user_id predicate (defence in depth), while the
+// database-enforced guarantee is proven separately, as the non-superuser app
+// role, in uploaded_transcripts_isolation_test.go. Text is synthetic; this repo is
+// public and no real transcript may appear in it (#33).
+
+func seedUsers(t *testing.T, ids ...string) {
+	t.Helper()
+	super := rawPool(t)
+	resetDB(t, super)
+	for _, id := range ids {
+		_, err := super.Exec(context.Background(), `INSERT INTO users (id) VALUES ($1)`, id)
+		require.NoError(t, err)
+	}
+}
+
+func TestCreateUpload_StartsQueuedAndIsOwnedByTheCreator(t *testing.T) {
+	s := newStore(t)
+	seedUsers(t, userA)
+	ctx := context.Background()
+
+	id, err := s.CreateUpload(ctx, userA, "Teams export")
+	require.NoError(t, err)
+
+	got, err := s.GetUpload(ctx, userA, id)
+	require.NoError(t, err)
+	assert.Equal(t, id, got.ID)
+	assert.Equal(t, userA, got.UserID)
+	assert.Equal(t, "Teams export", got.Title)
+	assert.Equal(t, domain.UploadQueued, got.Status)
+	assert.Empty(t, got.Content)
+	assert.True(t, got.FinishedAt.IsZero(), "an unfinished upload has no finish time")
+}
+
+func TestUploadLifecycle_CompletedKeepsTextSegmentsEndpointAndDuration(t *testing.T) {
+	s := newStore(t)
+	seedUsers(t, userA)
+	ctx := context.Background()
+	id, err := s.CreateUpload(ctx, userA, "m")
+	require.NoError(t, err)
+
+	require.NoError(t, s.StartTranscribing(ctx, userA, id))
+	mid, err := s.GetUpload(ctx, userA, id)
+	require.NoError(t, err)
+	assert.Equal(t, domain.UploadTranscribing, mid.Status)
+
+	want := domain.Transcription{
+		Text: "God morgon allihopa. Vi går igenom läget.",
+		Segments: []domain.Segment{
+			{Start: 0.0, End: 1.5, Text: "God morgon allihopa."},
+			{Start: 1.5, End: 4.25, Text: "Vi går igenom läget."},
+		},
+		Endpoint:     "iguana/kb-whisper",
+		AudioSeconds: 4.25,
+	}
+	require.NoError(t, s.CompleteUpload(ctx, userA, id, want))
+
+	got, err := s.GetUpload(ctx, userA, id)
+	require.NoError(t, err)
+	assert.Equal(t, domain.UploadDone, got.Status)
+	assert.Equal(t, want.Text, got.Content)
+	assert.Equal(t, want.Segments, got.Segments, "segment times must survive the JSONB round trip")
+	assert.Equal(t, "iguana/kb-whisper", got.Endpoint, "the serving endpoint is a quality fact and is recorded per row")
+	assert.InDelta(t, 4.25, got.AudioSeconds, 1e-9)
+	assert.False(t, got.FinishedAt.IsZero())
+	assert.Empty(t, got.ErrorKind)
+}
+
+func TestUploadLifecycle_FailedRecordsTypedKindAndNoContent(t *testing.T) {
+	s := newStore(t)
+	seedUsers(t, userA)
+	ctx := context.Background()
+	id, err := s.CreateUpload(ctx, userA, "m")
+	require.NoError(t, err)
+	require.NoError(t, s.StartTranscribing(ctx, userA, id))
+
+	require.NoError(t, s.FailUpload(ctx, userA, id, domain.UploadErrTranscriptionFailed))
+
+	got, err := s.GetUpload(ctx, userA, id)
+	require.NoError(t, err)
+	assert.Equal(t, domain.UploadFailed, got.Status)
+	assert.Equal(t, domain.UploadErrTranscriptionFailed, got.ErrorKind)
+	assert.Empty(t, got.Content)
+	assert.False(t, got.FinishedAt.IsZero())
+}
+
+func TestGetUpload_AnotherUsersIDIsNotFound(t *testing.T) {
+	s := newStore(t)
+	seedUsers(t, userA, userB)
+	ctx := context.Background()
+	id, err := s.CreateUpload(ctx, userA, "A's meeting")
+	require.NoError(t, err)
+
+	_, err = s.GetUpload(ctx, userB, id)
+
+	assert.ErrorIs(t, err, store.ErrUploadNotFound,
+		"a non-owner must get not-found, not forbidden: existence is not disclosed")
+}
+
+func TestUploadWrites_ByAnotherUserChangeNothing(t *testing.T) {
+	s := newStore(t)
+	seedUsers(t, userA, userB)
+	ctx := context.Background()
+	id, err := s.CreateUpload(ctx, userA, "A's meeting")
+	require.NoError(t, err)
+
+	assert.ErrorIs(t, s.StartTranscribing(ctx, userB, id), store.ErrUploadNotFound)
+	assert.ErrorIs(t, s.CompleteUpload(ctx, userB, id, domain.Transcription{Text: "planted"}), store.ErrUploadNotFound)
+	assert.ErrorIs(t, s.FailUpload(ctx, userB, id, domain.UploadErrTranscriptionFailed), store.ErrUploadNotFound)
+
+	got, err := s.GetUpload(ctx, userA, id)
+	require.NoError(t, err)
+	assert.Equal(t, domain.UploadQueued, got.Status, "B's writes must leave A's upload exactly as it was")
+	assert.Empty(t, got.Content)
+}
+
+func TestListUploads_ReturnsOnlyTheCallersNewestFirstWithoutTranscriptText(t *testing.T) {
+	s := newStore(t)
+	seedUsers(t, userA, userB)
+	ctx := context.Background()
+	first, err := s.CreateUpload(ctx, userA, "first")
+	require.NoError(t, err)
+	second, err := s.CreateUpload(ctx, userA, "second")
+	require.NoError(t, err)
+	_, err = s.CreateUpload(ctx, userB, "B's")
+	require.NoError(t, err)
+	require.NoError(t, s.StartTranscribing(ctx, userA, first))
+	require.NoError(t, s.CompleteUpload(ctx, userA, first, domain.Transcription{Text: "long text body", Endpoint: "e"}))
+
+	got, err := s.ListUploads(ctx, userA)
+
+	require.NoError(t, err)
+	require.Len(t, got, 2, "A must see only A's uploads")
+	assert.Equal(t, second, got[0].ID, "newest first")
+	assert.Equal(t, first, got[1].ID)
+	assert.Empty(t, got[1].Content, "a list row must not drag the whole transcript along")
+	assert.Equal(t, domain.UploadDone, got[1].Status)
+}
+
+func TestFailInterruptedUploads_FailsOnlyUnfinishedRowsForEveryUser(t *testing.T) {
+	s := newStore(t)
+	seedUsers(t, userA, userB)
+	super := rawPool(t)
+	ctx := context.Background()
+	for subject, uid := range map[string]string{"sub-a": userA, "sub-b": userB} {
+		_, err := super.Exec(ctx, `INSERT INTO user_identities (dex_subject, user_id) VALUES ($1, $2)`, subject, uid)
+		require.NoError(t, err)
+	}
+	queued, err := s.CreateUpload(ctx, userA, "queued")
+	require.NoError(t, err)
+	running, err := s.CreateUpload(ctx, userB, "running")
+	require.NoError(t, err)
+	require.NoError(t, s.StartTranscribing(ctx, userB, running))
+	done, err := s.CreateUpload(ctx, userA, "done")
+	require.NoError(t, err)
+	require.NoError(t, s.StartTranscribing(ctx, userA, done))
+	require.NoError(t, s.CompleteUpload(ctx, userA, done, domain.Transcription{Text: "kept", Endpoint: "e"}))
+
+	n, err := s.FailInterruptedUploads(ctx)
+
+	require.NoError(t, err)
+	assert.Equal(t, 2, n, "the queued and the transcribing row, across both users")
+	for _, c := range []struct{ user, id string }{{userA, queued}, {userB, running}} {
+		got, err := s.GetUpload(ctx, c.user, c.id)
+		require.NoError(t, err)
+		assert.Equal(t, domain.UploadFailed, got.Status)
+		assert.Equal(t, domain.UploadErrInterrupted, got.ErrorKind,
+			"audio is not retained, so a restart cannot resume: the honest state is failed/interrupted")
+	}
+	kept, err := s.GetUpload(ctx, userA, done)
+	require.NoError(t, err)
+	assert.Equal(t, domain.UploadDone, kept.Status, "a finished transcript must survive the sweep")
+	assert.Equal(t, "kept", kept.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,15 +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, channel_title)
-			 VALUES ($1, $2, $3, $4, $5, $6, $7)
+			`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,
-			     channel_title = COALESCE(NULLIF(EXCLUDED.channel_title, ''), videos.channel_title)
+			     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.ChannelTitle,
+			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)
 		}
@@ -74,12 +75,27 @@ func nullTime(t time.Time) *time.Time {
 	return &t
 }
 
-// NewestUnsummarizedVideoIDs returns up to limit of the user's videos that have
-// no summary yet, newest first (published_at DESC, NULLS LAST). It caps the
-// connect-time onboarding burst (Feature 1) at a fixed count: the caller marks
-// these for summarization through the shared rate gate. RLS-scoped via withUser,
-// so it only ever sees the requesting user's rows. limit <= 0 returns nil.
-func (s *Store) NewestUnsummarizedVideoIDs(ctx context.Context, userID string, limit int) ([]string, error) {
+// 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
 	}
@@ -92,16 +108,21 @@ func (s *Store) NewestUnsummarizedVideoIDs(ctx context.Context, userID string, l
 			    AND NOT EXISTS (
 			          SELECT 1 FROM summaries su
 			           WHERE su.user_id = v.user_id AND su.video_id = v.id)
-			  ORDER BY v.published_at DESC NULLS LAST, v.seen_at DESC
-			  LIMIT $2`, userID, limit)
+			    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: newest unsummarized: %w", err)
+			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 newest unsummarized: %w", err)
+				return fmt.Errorf("store: scan onboard burst video: %w", err)
 			}
 			ids = append(ids, id)
 		}

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)
@@ -82,36 +112,55 @@ func TestUpsertVideo_PerUserIsolation(t *testing.T) {
 	require.NotEqual(t, idA, idB, "same provider video for two users must be two distinct rows")
 }
 
-func TestNewestUnsummarizedVideoIDs(t *testing.T) {
+func TestOnboardBurstVideoIDs(t *testing.T) {
 	ctx := context.Background()
 	s := newStore(t)
 	resetDB(t, rawPool(t))
 
-	mk := func(user, pid string, day int) string {
+	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
 	}
 
-	_ = mk(userA, "a1vid000001", 1)
-	id2 := mk(userA, "a2vid000002", 2)
-	id3 := mk(userA, "a3vid000003", 3)
-	id4 := mk(userA, "a4vid000004", 4)
-	mk(userB, "b1vid000009", 9) // userB's newest — must never leak via RLS
+	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 (v4) is summarized, so it's excluded from "unsummarized".
-	require.NoError(t, s.Deliver(ctx, summary(userA, id4, "done")))
+	// The newest video is summarized, so it is excluded from the burst.
+	require.NoError(t, s.Deliver(ctx, summary(userA, summarized, "done")))
 
-	// Cap 2, newest-first unsummarized: v3 then v2 (v4 excluded; userB excluded).
-	got, err := s.NewestUnsummarizedVideoIDs(ctx, userA, 2)
+	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{id3, id2}, got)
+	require.Equal(t, []string{good1, good2, unknown}, got,
+		"known-good first (newest-first), then unknown-duration; junk excluded")
 
-	none, err := s.NewestUnsummarizedVideoIDs(ctx, userA, 0)
+	// Cap is honoured.
+	capped, err := s.OnboardBurstVideoIDs(ctx, userA, 2, minSec, maxSec)
 	require.NoError(t, err)
-	require.Empty(t, none, "limit 0 returns nothing")
+	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) {

internal/adapters/summarizer/summarizer.go

@@ -13,11 +13,13 @@ import (
 	"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.
@@ -95,16 +97,23 @@ func (s *Summarizer) Summarize(ctx context.Context, v domain.Video, t domain.Tra
 
 	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, i > 0, out)
+		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
 	}
 	return domain.Summary{}, fmt.Errorf("summarize: all %d endpoint(s) failed: %w", len(s.endpoints), errors.Join(errs...))

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)
 

internal/adapters/transcribe/chain.go

@@ -0,0 +1,53 @@
+package transcribe
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"git.d-ma.be/mathias/tapir/internal/domain"
+)
+
+// Backend is one transcription endpoint. *Gateway satisfies it; Name is the value
+// recorded as the serving endpoint.
+type Backend interface {
+	Name() string
+	Transcribe(ctx context.Context, wavPath string) (domain.Transcription, error)
+}
+
+// Chain tries a primary (local) backend and, if it fails for ANY reason, a
+// fallback. The fallback exists because iguana can wedge permanently on a Metal
+// OOM (infra#273) — which is also why a fallback is a data-egress decision: the
+// berget endpoint is a cloud service, so the result records which one served it.
+type Chain struct {
+	primary  Backend
+	fallback Backend // nil disables the fallback
+}
+
+// NewChain builds a Chain. A nil fallback means a primary failure is the result.
+func NewChain(primary, fallback Backend) *Chain {
+	return &Chain{primary: primary, fallback: fallback}
+}
+
+// Transcribe returns the first backend's success. It falls back on any primary
+// error — transport, timeout, non-2xx, empty transcript — and never inspects a
+// response body to decide. A cancelled context stops the chain: a job the user or
+// shutdown cancelled must not ship its audio to a cloud endpoint as a last act.
+func (c *Chain) Transcribe(ctx context.Context, wavPath string) (domain.Transcription, error) {
+	t, err := c.primary.Transcribe(ctx, wavPath)
+	if err == nil {
+		t.Endpoint = c.primary.Name()
+		return t, nil
+	}
+	if c.fallback == nil || ctx.Err() != nil {
+		return domain.Transcription{}, fmt.Errorf("%s: %w", c.primary.Name(), err)
+	}
+	t, ferr := c.fallback.Transcribe(ctx, wavPath)
+	if ferr != nil {
+		return domain.Transcription{}, errors.Join(
+			fmt.Errorf("%s: %w", c.primary.Name(), err),
+			fmt.Errorf("%s: %w", c.fallback.Name(), ferr))
+	}
+	t.Endpoint = c.fallback.Name()
+	return t, nil
+}

internal/adapters/transcribe/chain_test.go

@@ -0,0 +1,99 @@
+package transcribe_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/transcribe"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+)
+
+type fakeBackend struct {
+	name  string
+	text  string
+	err   error
+	calls int
+}
+
+func (f *fakeBackend) Name() string { return f.name }
+func (f *fakeBackend) Transcribe(_ context.Context, _ string) (domain.Transcription, error) {
+	f.calls++
+	if f.err != nil {
+		return domain.Transcription{}, f.err
+	}
+	return domain.Transcription{Text: f.text, Endpoint: f.name}, nil
+}
+
+func TestChain_PrimarySuccessNeverTouchesTheFallback(t *testing.T) {
+	primary := &fakeBackend{name: "iguana/kb-whisper", text: "primary text"}
+	fallback := &fakeBackend{name: "berget/kb-whisper", text: "fallback text"}
+
+	got, err := transcribe.NewChain(primary, fallback).Transcribe(context.Background(), "/a.wav")
+
+	require.NoError(t, err)
+	assert.Equal(t, "primary text", got.Text)
+	assert.Equal(t, "iguana/kb-whisper", got.Endpoint)
+	assert.Zero(t, fallback.calls, "audio must not leave the homelab when the local endpoint worked")
+}
+
+func TestChain_AnyPrimaryFailureFallsBackAndRecordsTheFallbackEndpoint(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+	}{
+		{"server error", &transcribe.StatusError{Code: 500}},
+		{"gateway timeout", &transcribe.StatusError{Code: 504}},
+		{"client error", &transcribe.StatusError{Code: 400}},
+		{"transport failure", errors.New("dial tcp: connection refused")},
+		{"empty transcript", transcribe.ErrEmptyTranscript},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			primary := &fakeBackend{name: "iguana/kb-whisper", err: tt.err}
+			fallback := &fakeBackend{name: "berget/kb-whisper", text: "fallback text"}
+
+			got, err := transcribe.NewChain(primary, fallback).Transcribe(context.Background(), "/a.wav")
+
+			require.NoError(t, err)
+			assert.Equal(t, "fallback text", got.Text)
+			assert.Equal(t, "berget/kb-whisper", got.Endpoint,
+				"the row must say berget served it: that means the audio left the homelab")
+		})
+	}
+}
+
+func TestChain_BothFailingReportsBothErrors(t *testing.T) {
+	primary := &fakeBackend{name: "iguana/kb-whisper", err: errors.New("iguana down")}
+	fallback := &fakeBackend{name: "berget/kb-whisper", err: errors.New("berget down")}
+
+	_, err := transcribe.NewChain(primary, fallback).Transcribe(context.Background(), "/a.wav")
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "iguana down")
+	assert.Contains(t, err.Error(), "berget down")
+}
+
+func TestChain_WithoutAFallbackAPrimaryFailureIsTheResult(t *testing.T) {
+	primary := &fakeBackend{name: "iguana/kb-whisper", err: errors.New("iguana down")}
+
+	_, err := transcribe.NewChain(primary, nil).Transcribe(context.Background(), "/a.wav")
+
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "iguana down")
+}
+
+func TestChain_ACancelledJobDoesNotFallBack(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	primary := &fakeBackend{name: "iguana/kb-whisper", err: context.Canceled}
+	fallback := &fakeBackend{name: "berget/kb-whisper", text: "x"}
+
+	_, err := transcribe.NewChain(primary, fallback).Transcribe(ctx, "/a.wav")
+
+	assert.ErrorIs(t, err, context.Canceled)
+	assert.Zero(t, fallback.calls, "a cancelled job must not ship the audio to a cloud endpoint")
+}

internal/adapters/transcribe/gateway.go

@@ -0,0 +1,147 @@
+// Package transcribe turns a WAV file into a timed Swedish transcript by calling
+// the LiteLLM gateway's OpenAI-compatible /audio/transcriptions endpoint
+// (ADR-033). A Gateway is one model alias; a Chain tries a local one and falls
+// back to a second.
+package transcribe
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"os"
+	"strings"
+
+	"git.d-ma.be/mathias/tapir/internal/domain"
+)
+
+// ErrEmptyTranscript is returned when the endpoint answered 200 but with no text.
+// An empty transcript is not a success: chat over it could only answer "nothing".
+var ErrEmptyTranscript = errors.New("transcribe: endpoint returned an empty transcript")
+
+// StatusError is a non-2xx answer from the gateway. Nothing may branch on the
+// body — {"error":"failed to process audio"} has had at least five distinct
+// causes — so only the status code is exposed for logic; Snippet is for logs.
+type StatusError struct {
+	Code    int
+	Snippet string
+}
+
+func (e *StatusError) Error() string {
+	return fmt.Sprintf("transcribe: gateway returned HTTP %d: %s", e.Code, e.Snippet)
+}
+
+// Gateway transcribes through one model alias on the gateway. baseURL is the
+// gateway's /v1 root — the in-cluster NodePort, not the public hostname, whose
+// ingress rejects bodies over ~8-10 MB with 413 (docs/research/audio-length-ceiling).
+type Gateway struct {
+	baseURL string
+	key     string
+	model   string
+	client  *http.Client
+}
+
+// NewGateway builds a Gateway. The client should carry no overall Timeout: a 90
+// minute recording takes minutes, so the deadline belongs to the caller's context.
+func NewGateway(baseURL, key, model string, client *http.Client) *Gateway {
+	return &Gateway{baseURL: strings.TrimRight(baseURL, "/"), key: key, model: model, client: client}
+}
+
+// Name is the model alias; it is what gets recorded as the serving endpoint.
+func (g *Gateway) Name() string { return g.model }
+
+// Transcribe uploads the WAV at path and returns the normalised transcription.
+// The body is streamed from disk with a COMPUTED Content-Length: a 90 minute WAV
+// is ~170 MB, so it is neither buffered in memory nor sent chunked.
+func (g *Gateway) Transcribe(ctx context.Context, path string) (domain.Transcription, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return domain.Transcription{}, fmt.Errorf("transcribe: open audio: %w", err)
+	}
+	defer f.Close()
+	info, err := f.Stat()
+	if err != nil {
+		return domain.Transcription{}, fmt.Errorf("transcribe: stat audio: %w", err)
+	}
+
+	var prefix bytes.Buffer
+	mw := multipart.NewWriter(&prefix)
+	for _, kv := range [][2]string{{"model", g.model}, {"response_format", "verbose_json"}, {"language", "sv"}} {
+		if err := mw.WriteField(kv[0], kv[1]); err != nil {
+			return domain.Transcription{}, fmt.Errorf("transcribe: build request: %w", err)
+		}
+	}
+	// The multipart field is `file`; `audio_file` is rejected as "Invalid request".
+	if _, err := mw.CreateFormFile("file", "audio.wav"); err != nil {
+		return domain.Transcription{}, fmt.Errorf("transcribe: build request: %w", err)
+	}
+	suffix := []byte("\r\n--" + mw.Boundary() + "--\r\n")
+
+	body := io.MultiReader(bytes.NewReader(prefix.Bytes()), f, bytes.NewReader(suffix))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, g.baseURL+"/audio/transcriptions", body)
+	if err != nil {
+		return domain.Transcription{}, fmt.Errorf("transcribe: build request: %w", err)
+	}
+	req.ContentLength = int64(prefix.Len()) + info.Size() + int64(len(suffix))
+	req.Header.Set("Content-Type", mw.FormDataContentType())
+	req.Header.Set("Authorization", "Bearer "+g.key)
+	// No "Expect: 100-continue": it trips the proxy for any body over 1 KB.
+
+	resp, err := g.client.Do(req)
+	if err != nil {
+		return domain.Transcription{}, fmt.Errorf("transcribe: %s: %w", g.model, err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode > 299 {
+		snip, _ := io.ReadAll(io.LimitReader(resp.Body, 200))
+		return domain.Transcription{}, &StatusError{Code: resp.StatusCode, Snippet: strings.TrimSpace(string(snip))}
+	}
+
+	t, err := parseVerbose(resp.Body)
+	if err != nil {
+		return domain.Transcription{}, fmt.Errorf("transcribe: %s: %w", g.model, err)
+	}
+	t.Endpoint = g.model
+	return t, nil
+}
+
+// verboseJSON is the subset of the verbose_json response used. Both backends
+// return it; they differ in segment granularity (iguana: whole seconds, berget:
+// sub-second) and in the language token, neither of which matters here.
+type verboseJSON struct {
+	Text     string  `json:"text"`
+	Duration float64 `json:"duration"`
+	Segments []struct {
+		Start float64 `json:"start"`
+		End   float64 `json:"end"`
+		Text  string  `json:"text"`
+	} `json:"segments"`
+}
+
+// parseVerbose normalises a verbose_json body. Whisper's final window can end past
+// the audio (9.0 s for 4.25 s of audio was observed), so segment ends are clamped
+// to the reported duration.
+func parseVerbose(r io.Reader) (domain.Transcription, error) {
+	var v verboseJSON
+	if err := json.NewDecoder(r).Decode(&v); err != nil {
+		return domain.Transcription{}, fmt.Errorf("decode response: %w", err)
+	}
+	text := strings.TrimSpace(v.Text)
+	if text == "" {
+		return domain.Transcription{}, ErrEmptyTranscript
+	}
+	t := domain.Transcription{Text: text, AudioSeconds: v.Duration}
+	for _, s := range v.Segments {
+		seg := domain.Segment{Start: s.Start, End: s.End, Text: strings.TrimSpace(s.Text)}
+		if v.Duration > 0 {
+			seg.End = min(seg.End, v.Duration)
+			seg.Start = min(seg.Start, seg.End)
+		}
+		t.Segments = append(t.Segments, seg)
+	}
+	return t, nil
+}

internal/adapters/transcribe/gateway_test.go

@@ -0,0 +1,174 @@
+package transcribe_test
+
+import (
+	"bytes"
+	"context"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/transcribe"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+)
+
+// The httptest server stands in for the LiteLLM gateway: it is the process
+// boundary, so a fake here is legitimate. The JSON it returns mirrors what the
+// real gateway returned for iguana/kb-whisper and berget/kb-whisper on 2026-10-01
+// (docs/research/audio-length-ceiling-2026-10-01.md). All text is synthetic.
+
+const verboseJSON = `{
+  "text": " God morgon allihopa.\n Vi går igenom läget.\n",
+  "language": "swedish",
+  "duration": 4.25,
+  "segments": [
+    {"id": 0, "start": 0.0, "end": 1.0, "text": " God morgon allihopa."},
+    {"id": 1, "start": 1.0, "end": 9.0, "text": " Vi går igenom läget."}
+  ]
+}`
+
+func wavFile(t *testing.T, content string) string {
+	t.Helper()
+	p := filepath.Join(t.TempDir(), "a.wav")
+	require.NoError(t, os.WriteFile(p, []byte(content), 0o600))
+	return p
+}
+
+type seen struct {
+	method, path, auth, expect, contentType string
+	contentLength                           int64
+	transferEncoding                        []string
+	fields                                  map[string]string
+	file                                    string
+	fileField                               string
+	bodyLen                                 int
+}
+
+// serve starts a gateway fake that records the request it received and replies
+// with status and body.
+func serve(t *testing.T, status int, reply string, got *seen) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got != nil {
+			got.method, got.path = r.Method, r.URL.Path
+			got.auth = r.Header.Get("Authorization")
+			got.expect = r.Header.Get("Expect")
+			got.contentType = r.Header.Get("Content-Type")
+			got.contentLength = r.ContentLength
+			got.transferEncoding = r.TransferEncoding
+			raw, _ := io.ReadAll(r.Body)
+			got.bodyLen = len(raw)
+			r.Body = io.NopCloser(bytes.NewReader(raw))
+			require.NoError(t, r.ParseMultipartForm(32<<20))
+			got.fields = map[string]string{}
+			for k, v := range r.MultipartForm.Value {
+				got.fields[k] = v[0]
+			}
+			for field, fhs := range r.MultipartForm.File {
+				got.fileField = field
+				f, _ := fhs[0].Open()
+				b, _ := io.ReadAll(f)
+				got.file = string(b)
+			}
+		}
+		w.WriteHeader(status)
+		_, _ = io.WriteString(w, reply)
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestGateway_SendsTheRequestTheGatewayExpects(t *testing.T) {
+	var got seen
+	srv := serve(t, 200, verboseJSON, &got)
+	g := transcribe.NewGateway(srv.URL+"/v1", "secret-key", "iguana/kb-whisper", srv.Client())
+
+	_, err := g.Transcribe(context.Background(), wavFile(t, "RIFF-synthetic-pcm"))
+
+	require.NoError(t, err)
+	assert.Equal(t, http.MethodPost, got.method)
+	assert.Equal(t, "/v1/audio/transcriptions", got.path)
+	assert.Equal(t, "Bearer secret-key", got.auth)
+	assert.Equal(t, "file", got.fileField, "the multipart field is `file`; `audio_file` is rejected as 'Invalid request'")
+	assert.Equal(t, "RIFF-synthetic-pcm", got.file)
+	assert.Equal(t, "iguana/kb-whisper", got.fields["model"])
+	assert.Equal(t, "verbose_json", got.fields["response_format"])
+	assert.Equal(t, "sv", got.fields["language"])
+	assert.Empty(t, got.expect, "no Expect: 100-continue: it trips the proxy for any body over 1 KB")
+}
+
+func TestGateway_SendsAKnownContentLengthNotChunked(t *testing.T) {
+	var got seen
+	srv := serve(t, 200, verboseJSON, &got)
+	g := transcribe.NewGateway(srv.URL+"/v1", "k", "m", srv.Client())
+
+	_, err := g.Transcribe(context.Background(), wavFile(t, "0123456789"))
+
+	require.NoError(t, err)
+	assert.Empty(t, got.transferEncoding, "a 90-minute WAV is ~170 MB: stream it with a computed length, not chunked and not buffered")
+	assert.Equal(t, int64(got.bodyLen), got.contentLength)
+}
+
+func TestGateway_NormalisesTheVerboseJSONResponse(t *testing.T) {
+	srv := serve(t, 200, verboseJSON, nil)
+	g := transcribe.NewGateway(srv.URL+"/v1", "k", "iguana/kb-whisper", srv.Client())
+
+	got, err := g.Transcribe(context.Background(), wavFile(t, "x"))
+
+	require.NoError(t, err)
+	assert.Equal(t, "God morgon allihopa.\n Vi går igenom läget.", got.Text)
+	assert.Equal(t, "iguana/kb-whisper", got.Endpoint, "the serving endpoint is part of the result")
+	assert.InDelta(t, 4.25, got.AudioSeconds, 1e-9)
+	assert.Equal(t, []domain.Segment{
+		{Start: 0, End: 1, Text: "God morgon allihopa."},
+		// The final segment ended at 9.0 s for 4.25 s of audio: whisper's last
+		// window can run past the end. Clamped to the audio duration.
+		{Start: 1, End: 4.25, Text: "Vi går igenom läget."},
+	}, got.Segments)
+}
+
+func TestGateway_ErrorsDoNotDependOnTheBody(t *testing.T) {
+	// {"error":"failed to process audio"} has had at least five distinct causes, so
+	// no code may branch on it. Two different bodies must be treated identically.
+	for _, reply := range []string{`{"error":"failed to process audio"}`, `{"error":"something else entirely"}`} {
+		srv := serve(t, 500, reply, nil)
+		g := transcribe.NewGateway(srv.URL+"/v1", "k", "m", srv.Client())
+
+		_, err := g.Transcribe(context.Background(), wavFile(t, "x"))
+
+		var se *transcribe.StatusError
+		require.ErrorAs(t, err, &se)
+		assert.Equal(t, 500, se.Code)
+	}
+}
+
+func TestGateway_AnEmptyTranscriptIsAFailureNotASuccess(t *testing.T) {
+	srv := serve(t, 200, `{"text":"  ","language":"swedish","duration":3,"segments":[]}`, nil)
+	g := transcribe.NewGateway(srv.URL+"/v1", "k", "m", srv.Client())
+
+	_, err := g.Transcribe(context.Background(), wavFile(t, "x"))
+
+	assert.ErrorIs(t, err, transcribe.ErrEmptyTranscript)
+}
+
+func TestGateway_MalformedJSONIsAnError(t *testing.T) {
+	srv := serve(t, 200, `not json`, nil)
+	g := transcribe.NewGateway(srv.URL+"/v1", "k", "m", srv.Client())
+
+	_, err := g.Transcribe(context.Background(), wavFile(t, "x"))
+
+	assert.Error(t, err)
+}
+
+func TestGateway_MissingAudioFileIsAnError(t *testing.T) {
+	g := transcribe.NewGateway("http://127.0.0.1:1/v1", "k", "m", http.DefaultClient)
+
+	_, err := g.Transcribe(context.Background(), filepath.Join(t.TempDir(), "nope.wav"))
+
+	assert.Error(t, err)
+}

internal/adapters/transcribe/live_test.go

@@ -0,0 +1,49 @@
+package transcribe_test
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"git.d-ma.be/mathias/tapir/internal/adapters/transcribe"
+)
+
+// TestGateway_LiveGateway is an opt-in check against the REAL gateway, because
+// the httptest fake above can only prove what we think the gateway accepts. It
+// is skipped unless TAPIR_LIVE_WAV names a 16 kHz mono WAV and the gateway
+// coordinates are set:
+//
+//	TAPIR_LIVE_WAV=/path/a.wav TAPIR_LIVE_GATEWAY_URL=http://koala:30401/v1 \
+//	TAPIR_LIVE_MODEL=iguana/kb-whisper op run --env-file ~/.op-env -- \
+//	  go test ./internal/adapters/transcribe -run LiveGateway -v
+//
+// Use SYNTHETIC audio only: this repo is public and the gateway may be a cloud
+// endpoint (#33).
+func TestGateway_LiveGateway(t *testing.T) {
+	wav := os.Getenv("TAPIR_LIVE_WAV")
+	url := os.Getenv("TAPIR_LIVE_GATEWAY_URL")
+	if wav == "" || url == "" {
+		t.Skip("set TAPIR_LIVE_WAV and TAPIR_LIVE_GATEWAY_URL to run against the real gateway")
+	}
+	model := os.Getenv("TAPIR_LIVE_MODEL")
+	if model == "" {
+		model = "iguana/kb-whisper"
+	}
+	key := os.Getenv("LITELLM_MASTER_KEY")
+	require.NotEmpty(t, key, "LITELLM_MASTER_KEY must be set (via op run)")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 25*time.Minute)
+	defer cancel()
+	got, err := transcribe.NewGateway(url, key, model, &http.Client{}).Transcribe(ctx, wav)
+
+	require.NoError(t, err)
+	assert.NotEmpty(t, got.Text)
+	assert.NotEmpty(t, got.Segments)
+	assert.Equal(t, model, got.Endpoint)
+	t.Logf("endpoint=%s audio_s=%.1f segments=%d chars=%d", got.Endpoint, got.AudioSeconds, len(got.Segments), len(got.Text))
+}

internal/adapters/youtube/captions.go

@@ -7,10 +7,13 @@ import (
 	"encoding/xml"
 	"fmt"
 	"io"
+	"log/slog"
 	"net/http"
 	"strings"
+	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/metrics"
 )
 
 // defaultPlayerBaseURL is the InnerTube / watch-page host. Overridable via
@@ -43,7 +46,35 @@ const maxCaptionBytes = 16 << 20 // 16 MiB
 // fetch, or an unparseable body all yield SourceNone rather than an error. Only
 // genuine transport (network) faults return an error. Audio download and
 // speech-to-text remain absent (ADR-007).
+// FetchTranscript times the caption fetch and records its latency by outcome
+// (ADR-030) before returning. Transport errors are surfaced to the caller and not
+// recorded as an outcome (logged upstream); the three resolved outcomes
+// captions|none|rate_limited are the ones that consume the scarce fetch budget.
 func (a *Adapter) FetchTranscript(ctx context.Context, v domain.Video) (domain.Transcript, error) {
+	start := time.Now()
+	tr, err := a.fetchTranscript(ctx, v)
+	if err == nil {
+		dur := time.Since(start)
+		outcome := captionOutcome(tr.Source)
+		metrics.ObserveCaptionFetch(outcome, dur)
+		slog.Default().Info("caption fetch", "video", v.ProviderVideoID, "outcome", outcome, "elapsed_ms", dur.Milliseconds())
+	}
+	return tr, err
+}
+
+// captionOutcome maps a transcript source to the metric outcome label.
+func captionOutcome(s domain.TranscriptSource) string {
+	switch s {
+	case domain.SourceCaptions:
+		return "captions"
+	case domain.SourceRateLimited:
+		return "rate_limited"
+	default:
+		return "none"
+	}
+}
+
+func (a *Adapter) fetchTranscript(ctx context.Context, v domain.Video) (domain.Transcript, error) {
 	client := a.plainClient()
 
 	tracks, err := a.captionTracks(ctx, client, v.ProviderVideoID)

internal/adapters/youtube/gate.go

@@ -2,6 +2,7 @@ package youtube
 
 import (
 	"context"
+	"sync/atomic"
 	"time"
 
 	"golang.org/x/time/rate"
@@ -29,9 +30,55 @@ func SetFetchRate(interval time.Duration) {
 	globalFetchGate = rate.NewLimiter(rate.Every(interval), 1)
 }
 
+// foregroundPending counts in-flight foreground (user-initiated) caption fetches.
+// The background sweep yields the gate while this is non-zero so a human waiting
+// on a click gets the next slot — and, on a near-throttled IP, the pre-429 window
+// — instead of competing equally with the firehose (ADR-026, Pillar A). Clicks are
+// rare and bursty, so background barely notices; the win to the click is large.
+var foregroundPending atomic.Int64
+
+// fgCtxKey marks a context as foreground (user-initiated). Unexported; set via
+// ForegroundContext and read via isForeground so only this package owns the key.
+type fgCtxKey struct{}
+
+// ForegroundContext marks ctx as a user-initiated (foreground) fetch so the gate
+// gives it priority. The web "Summarize"/paste/retry path wraps its context with
+// this; the background scheduler leaves it unset.
+func ForegroundContext(ctx context.Context) context.Context {
+	return context.WithValue(ctx, fgCtxKey{}, true)
+}
+
+func isForeground(ctx context.Context) bool {
+	v, _ := ctx.Value(fgCtxKey{}).(bool)
+	return v
+}
+
+// fgYieldPoll is how often a background waiter re-checks whether a foreground
+// fetch is still pending. Short enough to feel immediate, long enough not to spin.
+const fgYieldPoll = 200 * time.Millisecond
+
 // WaitFetchGate blocks until the process-wide gate allows one timedtext fetch,
 // respecting ctx cancellation. Called from httpDo before every live outbound
 // caption fetch so the scheduler and the click-path share the same egress budget.
+//
+// Foreground (user-initiated) fetches take priority: they register as pending and
+// acquire a token immediately. Background fetches first yield — they wait until no
+// foreground fetch is pending — so a live click is never stuck behind the
+// background sweep and gets the cleaner slot against the per-IP limit (ADR-026).
 func WaitFetchGate(ctx context.Context) error {
+	if isForeground(ctx) {
+		foregroundPending.Add(1)
+		defer foregroundPending.Add(-1)
+		return globalFetchGate.Wait(ctx)
+	}
+
+	// Background: defer to any pending foreground fetch before taking a token.
+	for foregroundPending.Load() > 0 {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(fgYieldPoll):
+		}
+	}
 	return globalFetchGate.Wait(ctx)
 }

internal/adapters/youtube/gate_test.go

@@ -82,3 +82,37 @@ func TestSetFetchRateZeroIsUnlimited(t *testing.T) {
 		require.NoError(t, WaitFetchGate(context.Background()))
 	}
 }
+
+func TestForegroundContextMarker(t *testing.T) {
+	require.False(t, isForeground(context.Background()), "plain context is background")
+	require.True(t, isForeground(ForegroundContext(context.Background())), "marked context is foreground")
+}
+
+// TestWaitFetchGateForegroundProceedsImmediately: a foreground fetch acquires a
+// token without yielding, even when background callers exist.
+func TestWaitFetchGateForegroundProceedsImmediately(t *testing.T) {
+	SetFetchRate(0) // unlimited limiter — isolate the yield logic from pacing
+	foregroundPending.Store(0)
+	t.Cleanup(func() { foregroundPending.Store(0) })
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	require.NoError(t, WaitFetchGate(ForegroundContext(ctx)), "foreground proceeds immediately")
+}
+
+// TestWaitFetchGateBackgroundYieldsToForeground: while a foreground fetch is
+// pending, a background fetch yields (does not take a token) until the foreground
+// clears — proven by a background wait timing out against its own deadline, then
+// succeeding once the foreground is done.
+func TestWaitFetchGateBackgroundYieldsToForeground(t *testing.T) {
+	SetFetchRate(0)
+	foregroundPending.Store(1) // simulate a foreground fetch in flight
+	t.Cleanup(func() { foregroundPending.Store(0) })
+
+	ctx, cancel := context.WithTimeout(context.Background(), 250*time.Millisecond)
+	defer cancel()
+	require.Error(t, WaitFetchGate(ctx), "background yields (blocks) while foreground is pending")
+
+	foregroundPending.Store(0) // foreground done
+	require.NoError(t, WaitFetchGate(context.Background()), "background proceeds once foreground clears")
+}

internal/adapters/youtube/videobyid_test.go

@@ -6,7 +6,7 @@ import (
 	"net/http"
 	"testing"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 func TestVideoByID(t *testing.T) {

internal/adapters/youtube/youtube.go

@@ -27,8 +27,8 @@ import (
 
 	"golang.org/x/oauth2"
 
-	"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/ports"
 )
 
 // defaultBaseURL is the YouTube Data API v3 root. Overridable via Config.BaseURL
@@ -302,6 +302,10 @@ func (a *Adapter) filterLowValue(ctx context.Context, client *http.Client, video
 		if m.seconds > 0 && m.seconds < a.cfg.MinVideoSeconds {
 			continue // Short / sub-threshold clip
 		}
+		// Carry the duration we already fetched onto the kept video so the store
+		// can persist it (ADR-028) — the burst's length-aware selection depends on
+		// it. Discarding it here was the gap the onboarding investigation found.
+		v.DurationSeconds = m.seconds
 		kept = append(kept, v)
 	}
 	return kept

internal/adapters/youtube/youtube_test.go

@@ -7,7 +7,7 @@ import (
 	"net/http/httptest"
 	"testing"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 // --- fakes ------------------------------------------------------------------
@@ -224,6 +224,11 @@ func TestNewVideosFiltersShortsAndLive(t *testing.T) {
 	if len(vids) != 1 || vids[0].ProviderVideoID != "long1" {
 		t.Fatalf("expected only long1 to survive the filter, got %+v", vids)
 	}
+	// The duration fetched for the filter is carried onto the kept video so the
+	// store can persist it (ADR-028) instead of discarding it.
+	if vids[0].DurationSeconds != 750 {
+		t.Fatalf("kept video DurationSeconds = %d, want 750 (PT12M30S)", vids[0].DurationSeconds)
+	}
 }
 
 // TestNewVideosNoFilterWhenDisabled: MinVideoSeconds=0 keeps the pre-ADR-023

internal/auth/auth_test.go

@@ -12,7 +12,7 @@ import (
 
 	"golang.org/x/oauth2"
 
-	"gitea.d-ma.be/mathias/tapir/internal/auth"
+	"git.d-ma.be/mathias/tapir/internal/auth"
 )
 
 // fakeWriter is a TokenWriter capturing the persisted (ref, value).

internal/config/config.go

@@ -20,6 +20,9 @@ import (
 
 // Config is Tapir's fully-resolved runtime configuration.
 type Config struct {
+	// UploadConfig is the audio-upload and private-transcription settings (ADR-033).
+	UploadConfig
+
 	// UserID is the Tapir user the run operates as. Stage 0 has exactly one.
 	// It must be a UUID: it keys the UUID user_id/video_id columns (data-model).
 	UserID string
@@ -33,7 +36,10 @@ type Config struct {
 	SummarizerModel string
 	// FallbackModel is the LOCAL fallback alias tried when the primary fails or
 	// returns unparseable output (ADR-022). Kept local so content stays on the
-	// homelab stack. Empty disables it. Default a bigger-context local model.
+	// homelab stack. Default is an IGUANA model (not koala) so the fallback runs
+	// on a different host than the koala primary — koala carries other loads, and
+	// a different host also means a different egress IP for the (rare) fallback.
+	// Empty disables it.
 	FallbackModel string
 	// CloudFallbackModel is the worst-case EXTERNAL fallback alias, tried only
 	// after every local endpoint has failed (ADR-022). For client deployments set
@@ -52,6 +58,14 @@ type Config struct {
 	// budget, ADR-014/ADR-023). Enforced via a cheap Data API videos.list lookup at
 	// discovery, never the rate-limited caption path. 0 disables the filter.
 	MinVideoSeconds int
+
+	// ChannelCaptionlessThreshold is how many consecutive no-caption results a
+	// channel may yield before its videos are suppressed from caption fetching
+	// (ADR-024). 0 disables the per-channel caption memory entirely.
+	ChannelCaptionlessThreshold int
+	// ChannelCaptionlessWindow is how long a suppressed channel stays suppressed
+	// before one video is re-probed (auto-recovery for a channel that adds captions).
+	ChannelCaptionlessWindow time.Duration
 	// SummarizerTimeout bounds a single completion call. Thinking models are
 	// slow, so the default is generous.
 	SummarizerTimeout time.Duration
@@ -109,6 +123,21 @@ type Config struct {
 	// caption rate gate (ADR-014) — the cap bounds count, never the pacing. Default 3.
 	OnboardSummarizeCount int
 
+	// OnboardSummarizerModel is the summarizer alias the connect-time burst leads
+	// its chain with (ADR-028) — a stronger model is affordable on the ≤3 summaries
+	// that form a new user's first impression. It heads a burst-specific chain;
+	// the standard chain (ADR-022) follows as resilience. Empty (or equal to
+	// SummarizerModel) collapses the burst back onto the shared processor — the
+	// reversibility lever. Default iguana/gemma4-26b (the brain-validated model).
+	OnboardSummarizerModel string
+
+	// OnboardMaxVideoSeconds upper-bounds the duration of a video the onboarding
+	// burst will pick (ADR-028), so the burst does not spend a scarce caption fetch
+	// on a multi-hour livestream VOD that passed the live filter once it ended. Only
+	// a KNOWN duration outside [MinVideoSeconds, this] is dropped; a NULL/unknown
+	// duration is kept (degrade-open). 0 disables the upper bound. Default 14400 (4h).
+	OnboardMaxVideoSeconds int
+
 	// DiscoveryInterval, when > 0, makes `serve` run in-process scheduled discovery
 	// for ALL users on that cadence (ADR-018). Zero/unset = disabled, so dev and
 	// tests never auto-fetch. Single-replica assumption — see cmdServe.
@@ -117,6 +146,11 @@ type Config struct {
 	// HTTPAddr is the listen address for `tapir serve` (the Stage-0 web UI).
 	HTTPAddr string
 
+	// MetricsAddr is the listen address for the Prometheus /metrics endpoint
+	// (ADR-030). A SEPARATE port from HTTPAddr so /metrics is never exposed on the
+	// public app — only scraped in-cluster. Empty disables the metrics server.
+	MetricsAddr string
+
 	// PublicURL is the externally-reachable base URL of the deployed service,
 	// e.g. "https://tapir.d-ma.be". Used to build absolute links handed to humans
 	// (the `tapir invite` URL). No trailing slash is assumed — callers trim it.
@@ -140,22 +174,27 @@ func (c Config) DexConfigured() bool { return strings.TrimSpace(c.OIDCIssuer) !=
 const (
 	defaultGatewayURL             = "http://koala:30401/v1"
 	defaultSummarizerModel        = "koala/phi4-mini"
-	defaultFallbackModel         = "koala/phi4-14b"
+	defaultFallbackModel          = "iguana/gemma4-26b"
 	defaultCloudFallbackModel     = "berget/mistral-small"
 	defaultSummaryMaxTokens       = 1500
 	defaultMaxTranscriptChars     = 18000
 	defaultMinVideoSeconds        = 60
+	defaultCaptionlessThreshold   = 5
+	defaultCaptionlessWindow      = 14 * 24 * time.Hour
 	defaultSummarizerTimeout      = 5 * time.Minute
 	defaultYTTokenRef             = "youtube/refresh_token"
 	defaultYTConnectRedirectURL   = "https://tapir.d-ma.be/oauth/youtube/callback"
 	defaultOAuthRedirectAddr      = "localhost:8080"
 	defaultHTTPAddr               = ":8080"
+	defaultMetricsAddr            = ":9090"
 	defaultFetchBackoff           = time.Hour
 	defaultFetchRate              = 2 * time.Second
 	defaultPublicURL              = "https://tapir.d-ma.be"
 	defaultAutoSummarizeWindow    = 7 * 24 * time.Hour
 	defaultOnboardSummarizeCount  = 3
 	maxOnboardSummarizeCount      = 5
+	defaultOnboardSummarizerModel = "iguana/gemma4-26b"
+	defaultOnboardMaxVideoSeconds = 14400 // 4h
 )
 
 // Load reads the environment into a Config, applying defaults. It does not
@@ -168,6 +207,7 @@ func Load() (Config, error) {
 		GatewayURL:             envOr("TAPIR_GATEWAY_URL", defaultGatewayURL),
 		GatewayKey:             os.Getenv("TAPIR_GATEWAY_KEY"),
 		SummarizerModel:        envOr("TAPIR_SUMMARIZER_MODEL", defaultSummarizerModel),
+		OnboardSummarizerModel: lookupOr("TAPIR_ONBOARD_SUMMARIZER_MODEL", defaultOnboardSummarizerModel),
 		FallbackModel:          lookupOr("TAPIR_FALLBACK_MODEL", defaultFallbackModel),
 		CloudFallbackModel:     lookupOr("TAPIR_CLOUD_FALLBACK_MODEL", defaultCloudFallbackModel),
 		DBDSN:                  os.Getenv("TAPIR_DB_DSN"),
@@ -178,6 +218,7 @@ func Load() (Config, error) {
 		SecretsFile:            envOr("TAPIR_SECRETS_FILE", defaultSecretsFile()),
 		OAuthRedirectAddr:      envOr("TAPIR_OAUTH_REDIRECT_ADDR", defaultOAuthRedirectAddr),
 		HTTPAddr:               envOr("TAPIR_HTTP_ADDR", defaultHTTPAddr),
+		MetricsAddr:            lookupOr("TAPIR_METRICS_ADDR", defaultMetricsAddr),
 		PublicURL:              envOr("TAPIR_PUBLIC_URL", defaultPublicURL),
 		OIDCIssuer:             os.Getenv("TAPIR_OIDC_ISSUER"),
 		DexClientID:            os.Getenv("TAPIR_DEX_CLIENT_ID"),
@@ -246,6 +287,21 @@ func Load() (Config, error) {
 	}
 	c.MinVideoSeconds = minVideo
 
+	captionThreshold, err := intOr("TAPIR_CHANNEL_CAPTIONLESS_THRESHOLD", defaultCaptionlessThreshold)
+	if err != nil {
+		return Config{}, err
+	}
+	if captionThreshold < 0 {
+		captionThreshold = 0
+	}
+	c.ChannelCaptionlessThreshold = captionThreshold
+
+	captionWindow, err := durationOr("TAPIR_CHANNEL_CAPTIONLESS_WINDOW", defaultCaptionlessWindow)
+	if err != nil {
+		return Config{}, err
+	}
+	c.ChannelCaptionlessWindow = captionWindow
+
 	onboard, err := intOr("TAPIR_ONBOARD_SUMMARIZE_COUNT", defaultOnboardSummarizeCount)
 	if err != nil {
 		return Config{}, err
@@ -258,6 +314,19 @@ func Load() (Config, error) {
 	}
 	c.OnboardSummarizeCount = onboard
 
+	onboardMax, err := intOr("TAPIR_ONBOARD_MAX_VIDEO_SECONDS", defaultOnboardMaxVideoSeconds)
+	if err != nil {
+		return Config{}, err
+	}
+	if onboardMax < 0 {
+		onboardMax = 0
+	}
+	c.OnboardMaxVideoSeconds = onboardMax
+
+	if c.UploadConfig, err = loadUploadConfig(); err != nil {
+		return Config{}, err
+	}
+
 	return c, nil
 }
 

internal/config/config_test.go

@@ -214,3 +214,62 @@ func TestValidateForAuth_PassesWhenComplete(t *testing.T) {
 		t.Errorf("ValidateForAuth: unexpected error %v", err)
 	}
 }
+
+func TestLoad_OnboardSummarizerModel(t *testing.T) {
+	cases := []struct {
+		name, env string
+		set       bool
+		want      string
+	}{
+		{"default", "", false, defaultOnboardSummarizerModel},
+		{"explicit", "koala/some-model", true, "koala/some-model"},
+		{"empty disables (collapses to shared processor)", "", true, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			env := map[string]string{}
+			if c.set {
+				env["TAPIR_ONBOARD_SUMMARIZER_MODEL"] = c.env
+			}
+			setEnv(t, env)
+			cfg, err := Load()
+			if err != nil {
+				t.Fatalf("Load: %v", err)
+			}
+			if cfg.OnboardSummarizerModel != c.want {
+				t.Fatalf("OnboardSummarizerModel = %q, want %q", cfg.OnboardSummarizerModel, c.want)
+			}
+		})
+	}
+}
+
+func TestLoad_OnboardMaxVideoSeconds(t *testing.T) {
+	cases := []struct {
+		name, env string
+		want      int
+	}{
+		{"default", "", defaultOnboardMaxVideoSeconds},
+		{"explicit", "7200", 7200},
+		{"zero disables", "0", 0},
+		{"negative clamps to zero", "-9", 0},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			setEnv(t, map[string]string{"TAPIR_ONBOARD_MAX_VIDEO_SECONDS": c.env})
+			cfg, err := Load()
+			if err != nil {
+				t.Fatalf("Load: %v", err)
+			}
+			if cfg.OnboardMaxVideoSeconds != c.want {
+				t.Fatalf("OnboardMaxVideoSeconds = %d, want %d", cfg.OnboardMaxVideoSeconds, c.want)
+			}
+		})
+	}
+}
+
+func TestLoad_OnboardMaxVideoSecondsInvalid(t *testing.T) {
+	setEnv(t, map[string]string{"TAPIR_ONBOARD_MAX_VIDEO_SECONDS": "long"})
+	if _, err := Load(); err == nil {
+		t.Fatal("Load: want error for non-numeric TAPIR_ONBOARD_MAX_VIDEO_SECONDS")
+	}
+}

internal/config/uploads.go

@@ -0,0 +1,118 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"time"
+)
+
+// UploadConfig holds the settings for audio upload and private transcription
+// (ADR-033). It is embedded in Config, so its fields read as c.UploadsEnabled etc.
+type UploadConfig struct {
+	// UploadsEnabled mounts the /uploads routes and starts the worker. Off by
+	// default: the runtime image must contain ffmpeg and ffprobe first (ADR-033).
+	UploadsEnabled bool
+	// UploadMaxBytes caps one upload. UploadMaxDuration caps one recording; 90
+	// minutes is the longest length MEASURED, not a ceiling that was found, so
+	// raising it is a measurement, not an edit.
+	UploadMaxBytes    int64
+	UploadMaxDuration time.Duration
+	// TranscribeModel is the primary gateway alias; TranscribeFallbackModel is the
+	// fallback, tried on ANY primary failure. The fallback is a cloud endpoint
+	// (berget): set it EMPTY to keep private audio on the homelab.
+	TranscribeModel         string
+	TranscribeFallbackModel string
+	// TranscribeTimeout bounds one job (conversion + transcription); a 90 minute
+	// recording took ~7.5 minutes on iguana.
+	TranscribeTimeout time.Duration
+	// UploadTmpDir is where uploads are spooled and converted. Audio is deleted
+	// after transcription, so this holds at most the in-flight files.
+	UploadTmpDir string
+	FFmpegBin    string
+	FFprobeBin   string
+	// MaxUploadedTranscriptChars bounds the transcript sent to a chat model for an
+	// UPLOADED recording. The 18,000-char default for captions is ~22 minutes of
+	// speech; an hour of meeting is ~50,000 chars. MEASURED 2026-10-01 against the
+	// real models: iguana/gemma4-26b answers correctly to 90,000 chars but silently
+	// drops the head of a 120,000-char transcript, so 90,000 is the ceiling of the
+	// best model, not a round number.
+	MaxUploadedTranscriptChars int
+	// UploadChatModel is the model chat over an uploaded recording opens with. It is
+	// NOT the summarizer default: koala/phi4-mini has an 8,192-token context and
+	// returns HTTP 400 on an hour of speech (~13,000 tokens).
+	UploadChatModel string
+}
+
+const (
+	defaultUploadMaxMB             = 200
+	defaultUploadMaxMinutes        = 90
+	defaultTranscribeModel         = "iguana/kb-whisper"
+	defaultTranscribeFallbackModel = "berget/kb-whisper"
+	defaultTranscribeTimeout       = 30 * time.Minute
+	defaultMaxUploadedChars        = 90000
+	defaultUploadChatModel         = "iguana/gemma4-26b"
+)
+
+func loadUploadConfig() (UploadConfig, error) {
+	u := UploadConfig{
+		TranscribeModel:         envOr("TAPIR_TRANSCRIBE_MODEL", defaultTranscribeModel),
+		TranscribeFallbackModel: lookupOr("TAPIR_TRANSCRIBE_FALLBACK_MODEL", defaultTranscribeFallbackModel),
+		UploadTmpDir:            envOr("TAPIR_UPLOAD_TMP_DIR", os.TempDir()),
+		FFmpegBin:               envOr("TAPIR_FFMPEG_BIN", "ffmpeg"),
+		FFprobeBin:              envOr("TAPIR_FFPROBE_BIN", "ffprobe"),
+		UploadChatModel:         envOr("TAPIR_UPLOAD_CHAT_MODEL", defaultUploadChatModel),
+	}
+
+	if v := os.Getenv("TAPIR_UPLOADS_ENABLED"); v != "" {
+		on, err := strconv.ParseBool(v)
+		if err != nil {
+			return UploadConfig{}, fmt.Errorf("config: TAPIR_UPLOADS_ENABLED=%q: %w", v, err)
+		}
+		u.UploadsEnabled = on
+	}
+
+	mb, err := positiveInt("TAPIR_UPLOAD_MAX_MB", defaultUploadMaxMB)
+	if err != nil {
+		return UploadConfig{}, err
+	}
+	u.UploadMaxBytes = int64(mb) << 20
+
+	mins, err := positiveInt("TAPIR_UPLOAD_MAX_MINUTES", defaultUploadMaxMinutes)
+	if err != nil {
+		return UploadConfig{}, err
+	}
+	u.UploadMaxDuration = time.Duration(mins) * time.Minute
+
+	timeout, err := durationOr("TAPIR_TRANSCRIBE_TIMEOUT", defaultTranscribeTimeout)
+	if err != nil {
+		return UploadConfig{}, err
+	}
+	if timeout <= 0 {
+		return UploadConfig{}, fmt.Errorf("config: TAPIR_TRANSCRIBE_TIMEOUT must be positive, got %v", timeout)
+	}
+	u.TranscribeTimeout = timeout
+
+	chars, err := intOr("TAPIR_MAX_UPLOADED_TRANSCRIPT_CHARS", defaultMaxUploadedChars)
+	if err != nil {
+		return UploadConfig{}, err
+	}
+	if chars < 0 {
+		chars = 0
+	}
+	u.MaxUploadedTranscriptChars = chars
+	return u, nil
+}
+
+// positiveInt is intOr that refuses zero and negatives: a zero upload limit would
+// reject every file, which is a misconfiguration to fail on, not to run with.
+func positiveInt(key string, fallback int) (int, error) {
+	n, err := intOr(key, fallback)
+	if err != nil {
+		return 0, err
+	}
+	if n <= 0 {
+		return 0, fmt.Errorf("config: %s must be positive, got %d", key, n)
+	}
+	return n, nil
+}

internal/config/uploads_test.go

@@ -0,0 +1,141 @@
+package config
+
+import (
+	"os"
+	"testing"
+	"time"
+)
+
+// clearUploadEnv unsets every upload knob so a test observes the default, not the
+// host environment.
+func clearUploadEnv(t *testing.T) {
+	t.Helper()
+	for _, k := range []string{
+		"TAPIR_UPLOADS_ENABLED", "TAPIR_UPLOAD_MAX_MB", "TAPIR_UPLOAD_MAX_MINUTES",
+		"TAPIR_TRANSCRIBE_MODEL", "TAPIR_TRANSCRIBE_FALLBACK_MODEL", "TAPIR_TRANSCRIBE_TIMEOUT",
+		"TAPIR_UPLOAD_TMP_DIR", "TAPIR_FFMPEG_BIN", "TAPIR_FFPROBE_BIN",
+		"TAPIR_MAX_UPLOADED_TRANSCRIPT_CHARS", "TAPIR_UPLOAD_CHAT_MODEL",
+	} {
+		unset(t, k)
+	}
+}
+
+func TestLoad_UploadDefaults(t *testing.T) {
+	clearUploadEnv(t)
+
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+
+	if c.UploadsEnabled {
+		t.Error("uploads must be OFF by default: the runtime image needs ffmpeg first (ADR-033)")
+	}
+	if c.UploadMaxBytes != 200<<20 {
+		t.Errorf("UploadMaxBytes = %d, want 200 MB", c.UploadMaxBytes)
+	}
+	if c.UploadMaxDuration != 90*time.Minute {
+		t.Errorf("UploadMaxDuration = %v, want 90m (the longest length measured, not a found ceiling)", c.UploadMaxDuration)
+	}
+	if c.TranscribeModel != "iguana/kb-whisper" {
+		t.Errorf("TranscribeModel = %q", c.TranscribeModel)
+	}
+	if c.TranscribeFallbackModel != "berget/kb-whisper" {
+		t.Errorf("TranscribeFallbackModel = %q", c.TranscribeFallbackModel)
+	}
+	if c.TranscribeTimeout != 30*time.Minute {
+		t.Errorf("TranscribeTimeout = %v, want 30m (a 90 min recording took ~7.5 min)", c.TranscribeTimeout)
+	}
+	if c.UploadTmpDir != os.TempDir() {
+		t.Errorf("UploadTmpDir = %q, want os.TempDir()", c.UploadTmpDir)
+	}
+	if c.FFmpegBin != "ffmpeg" || c.FFprobeBin != "ffprobe" {
+		t.Errorf("bins = %q, %q", c.FFmpegBin, c.FFprobeBin)
+	}
+	if c.MaxUploadedTranscriptChars != 90000 {
+		t.Errorf("MaxUploadedTranscriptChars = %d, want 90000: iguana/gemma4-26b answered correctly at 90,000 chars "+
+			"but silently dropped the head of a 120,000-char transcript (docs/research/chat-context)", c.MaxUploadedTranscriptChars)
+	}
+	if c.UploadChatModel != "iguana/gemma4-26b" {
+		t.Errorf("UploadChatModel = %q: koala/phi4-mini has an 8,192-token context and answers HTTP 400 on an hour of speech", c.UploadChatModel)
+	}
+}
+
+func TestLoad_UploadChatModelOverride(t *testing.T) {
+	clearUploadEnv(t)
+	t.Setenv("TAPIR_UPLOAD_CHAT_MODEL", "koala/qwen36-35b-a3b")
+
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+
+	if c.UploadChatModel != "koala/qwen36-35b-a3b" {
+		t.Errorf("UploadChatModel = %q", c.UploadChatModel)
+	}
+}
+
+func TestLoad_UploadValuesAreParsed(t *testing.T) {
+	clearUploadEnv(t)
+	setEnv(t, map[string]string{
+		"TAPIR_UPLOADS_ENABLED":               "true",
+		"TAPIR_UPLOAD_MAX_MB":                 "50",
+		"TAPIR_UPLOAD_MAX_MINUTES":            "30",
+		"TAPIR_TRANSCRIBE_MODEL":              "koala/whisper",
+		"TAPIR_TRANSCRIBE_TIMEOUT":            "10m",
+		"TAPIR_UPLOAD_TMP_DIR":                "/var/spool/tapir",
+		"TAPIR_FFMPEG_BIN":                    "/opt/ffmpeg",
+		"TAPIR_FFPROBE_BIN":                   "/opt/ffprobe",
+		"TAPIR_MAX_UPLOADED_TRANSCRIPT_CHARS": "60000",
+	})
+
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+
+	if !c.UploadsEnabled || c.UploadMaxBytes != 50<<20 || c.UploadMaxDuration != 30*time.Minute ||
+		c.TranscribeModel != "koala/whisper" || c.TranscribeTimeout != 10*time.Minute ||
+		c.UploadTmpDir != "/var/spool/tapir" || c.FFmpegBin != "/opt/ffmpeg" ||
+		c.FFprobeBin != "/opt/ffprobe" || c.MaxUploadedTranscriptChars != 60000 {
+		t.Errorf("values not applied: %+v", c)
+	}
+}
+
+func TestLoad_EmptyTranscribeFallbackDisablesIt(t *testing.T) {
+	clearUploadEnv(t)
+	t.Setenv("TAPIR_TRANSCRIBE_FALLBACK_MODEL", "")
+
+	c, err := Load()
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+
+	if c.TranscribeFallbackModel != "" {
+		t.Errorf("TranscribeFallbackModel = %q: an explicit empty value must disable the cloud fallback, "+
+			"so private audio can be kept on the homelab", c.TranscribeFallbackModel)
+	}
+}
+
+func TestLoad_UploadRejectsInvalidValues(t *testing.T) {
+	tests := []struct{ key, val string }{
+		{"TAPIR_UPLOADS_ENABLED", "maybe"},
+		{"TAPIR_UPLOAD_MAX_MB", "lots"},
+		{"TAPIR_UPLOAD_MAX_MB", "0"},
+		{"TAPIR_UPLOAD_MAX_MB", "-5"},
+		{"TAPIR_UPLOAD_MAX_MINUTES", "0"},
+		{"TAPIR_UPLOAD_MAX_MINUTES", "forever"},
+		{"TAPIR_TRANSCRIBE_TIMEOUT", "soon"},
+		{"TAPIR_TRANSCRIBE_TIMEOUT", "0s"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.key+"="+tt.val, func(t *testing.T) {
+			clearUploadEnv(t)
+			t.Setenv(tt.key, tt.val)
+
+			if _, err := Load(); err == nil {
+				t.Errorf("Load accepted %s=%q; a zero or negative limit would reject every upload", tt.key, tt.val)
+			}
+		})
+	}
+}

internal/domain/domain.go

@@ -77,6 +77,11 @@ type Video struct {
 	URL             string
 	PublishedAt     time.Time
 	SeenAt          time.Time
+	// DurationSeconds is the video length in seconds, when known (fetched by the
+	// ADR-023 videos.list enrichment at discovery). 0 means unknown — the store
+	// preserves a previously-known value rather than overwriting it with 0, and
+	// the onboarding burst (ADR-028) treats unknown as degrade-open (kept).
+	DurationSeconds int
 }
 
 // Transcript is the text of a video (or a record that none was available).
@@ -106,3 +111,62 @@ type Summary struct {
 	FallbackUsed bool
 	CreatedAt    time.Time
 }
+
+// Segment is one timed span of a transcription. Times are seconds from the start
+// of the audio.
+type Segment struct {
+	Start float64 `json:"start"`
+	End   float64 `json:"end"`
+	Text  string  `json:"text"`
+}
+
+// Transcription is the result of transcribing user-supplied audio (ADR-033):
+// the full text, its timed segments, which backend served it, and how long the
+// audio was. Endpoint is recorded because the backends differ in timestamp
+// granularity — which one served a transcript is a quality fact.
+type Transcription struct {
+	Text         string
+	Segments     []Segment
+	Endpoint     string
+	AudioSeconds float64
+}
+
+// UploadStatus is the state of an uploaded-audio transcription job.
+type UploadStatus string
+
+const (
+	UploadQueued       UploadStatus = "queued"
+	UploadTranscribing UploadStatus = "transcribing"
+	UploadDone         UploadStatus = "done"
+	UploadFailed       UploadStatus = "failed"
+)
+
+// UploadErrorKind is the typed reason an upload failed. It is deliberately NOT a
+// provider's error string: the whisper server's "failed to process audio" has had
+// at least five distinct causes, so nothing may branch on it (ADR-033).
+type UploadErrorKind string
+
+const (
+	// UploadErrInterrupted: the process restarted mid-job. The audio is not
+	// retained, so the job cannot resume; the user re-uploads.
+	UploadErrInterrupted UploadErrorKind = "interrupted"
+	// UploadErrTranscriptionFailed: every configured transcription endpoint failed.
+	UploadErrTranscriptionFailed UploadErrorKind = "transcription_failed"
+)
+
+// UploadedTranscript is a user's PRIVATE transcript of audio they uploaded. It is
+// never stored in, or merged with, the shared public-caption Transcript (ADR-021).
+// Content and Segments are empty until Status is UploadDone.
+type UploadedTranscript struct {
+	ID           string
+	UserID       string
+	Title        string
+	Status       UploadStatus
+	Content      string
+	Segments     []Segment
+	Endpoint     string
+	AudioSeconds float64
+	ErrorKind    UploadErrorKind
+	CreatedAt    time.Time
+	FinishedAt   time.Time // zero until the job reaches done or failed
+}

internal/metrics/metrics.go

@@ -0,0 +1,139 @@
+// Package metrics is Tapir's Prometheus instrumentation (ADR-030, issue #15). It
+// owns the collectors and a small typed API the rest of the app calls — adapters
+// never touch prometheus types directly. Two themes:
+//
+//   - HTTP/session: request count + latency by route (the matched pattern, so
+//     cardinality stays bounded), and logins.
+//   - AI (the priority): summarization latency by model/outcome/fallback, caption
+//     fetch latency by outcome, chat latency by model, and LLM token usage.
+//
+// Handler() is served on a dedicated port (never the public app port) so a scrape
+// is in-cluster only. slog timing lines are emitted at the call sites too.
+package metrics
+
+import (
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+// latencyBuckets spans sub-second UI calls up to multi-minute model calls (a cold
+// local model load is tens of seconds; the cloud fallback can be longer).
+var latencyBuckets = []float64{0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 20, 30, 60, 120, 300}
+
+var (
+	httpRequests = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "tapir_http_requests_total",
+		Help: "HTTP requests by method, matched route pattern, and status code.",
+	}, []string{"method", "route", "code"})
+
+	httpDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "tapir_http_request_duration_seconds",
+		Help:    "HTTP request latency by method and matched route pattern.",
+		Buckets: []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2, 5},
+	}, []string{"method", "route"})
+
+	logins = promauto.NewCounter(prometheus.CounterOpts{
+		Name: "tapir_logins_total",
+		Help: "Successful OIDC logins (session established).",
+	})
+
+	summarizeDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "tapir_summarize_duration_seconds",
+		Help:    "Per-endpoint summarization latency by model, outcome (success|parse_error|error), and whether it was a fallback.",
+		Buckets: latencyBuckets,
+	}, []string{"model", "outcome", "fallback"})
+
+	captionFetchDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "tapir_caption_fetch_duration_seconds",
+		Help:    "Caption fetch latency by outcome (captions|none|rate_limited).",
+		Buckets: latencyBuckets,
+	}, []string{"outcome"})
+
+	chatDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
+		Name:    "tapir_chat_duration_seconds",
+		Help:    "Per-video Q&A answer latency by model.",
+		Buckets: latencyBuckets,
+	}, []string{"model"})
+
+	llmTokens = promauto.NewCounterVec(prometheus.CounterOpts{
+		Name: "tapir_llm_tokens_total",
+		Help: "LLM tokens consumed by model and kind (prompt|completion).",
+	}, []string{"model", "kind"})
+)
+
+// Handler serves the Prometheus exposition format. Mount on the dedicated metrics
+// port, never the public app mux.
+func Handler() http.Handler { return promhttp.Handler() }
+
+// IncLogin records a successful login.
+func IncLogin() { logins.Inc() }
+
+// ObserveSummarize records one summarization endpoint attempt.
+func ObserveSummarize(model, outcome string, fallback bool, d time.Duration) {
+	summarizeDuration.WithLabelValues(model, outcome, strconv.FormatBool(fallback)).Observe(d.Seconds())
+}
+
+// ObserveCaptionFetch records one caption fetch by outcome.
+func ObserveCaptionFetch(outcome string, d time.Duration) {
+	captionFetchDuration.WithLabelValues(outcome).Observe(d.Seconds())
+}
+
+// ObserveChat records one Q&A answer latency.
+func ObserveChat(model string, d time.Duration) {
+	chatDuration.WithLabelValues(model).Observe(d.Seconds())
+}
+
+// RecordTokens records LLM token usage from a completion's usage block. Zero
+// counts are skipped so a provider that omits usage adds nothing.
+func RecordTokens(model string, prompt, completion int) {
+	if prompt > 0 {
+		llmTokens.WithLabelValues(model, "prompt").Add(float64(prompt))
+	}
+	if completion > 0 {
+		llmTokens.WithLabelValues(model, "completion").Add(float64(completion))
+	}
+}
+
+// HTTPMiddleware records request count + latency. It reads r.Pattern AFTER the
+// inner handler routes (Go 1.22 sets it during ServeMux matching), so the label is
+// the bounded registered pattern (e.g. "GET /v/{videoId}"), never the raw path
+// with its high-cardinality ids. Unmatched requests bucket as "other".
+func HTTPMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+		sw := &statusWriter{ResponseWriter: w, code: http.StatusOK}
+		next.ServeHTTP(sw, r)
+
+		route := r.Pattern
+		if route == "" {
+			route = "other"
+		}
+		httpRequests.WithLabelValues(r.Method, route, strconv.Itoa(sw.code)).Inc()
+		httpDuration.WithLabelValues(r.Method, route).Observe(time.Since(start).Seconds())
+	})
+}
+
+// statusWriter captures the response status for the request-count label.
+type statusWriter struct {
+	http.ResponseWriter
+	code        int
+	wroteHeader bool
+}
+
+func (s *statusWriter) WriteHeader(code int) {
+	if !s.wroteHeader {
+		s.code = code
+		s.wroteHeader = true
+	}
+	s.ResponseWriter.WriteHeader(code)
+}
+
+func (s *statusWriter) Write(b []byte) (int, error) {
+	s.wroteHeader = true // an implicit 200
+	return s.ResponseWriter.Write(b)
+}

internal/metrics/metrics_test.go

@@ -0,0 +1,92 @@
+package metrics
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/testutil"
+	dto "github.com/prometheus/client_model/go"
+	"github.com/stretchr/testify/require"
+)
+
+// histCount reads a histogram child's observation count (testutil.ToFloat64 only
+// works on counters/gauges; a histogram's WithLabelValues child is an Observer).
+func histCount(t *testing.T, o prometheus.Observer) uint64 {
+	t.Helper()
+	m, ok := o.(prometheus.Metric)
+	require.True(t, ok, "histogram child must be a prometheus.Metric")
+	var d dto.Metric
+	require.NoError(t, m.Write(&d))
+	return d.GetHistogram().GetSampleCount()
+}
+
+// TestObserveSummarizeRecordsModelOutcomeFallback: a success observation lands on
+// the right model/outcome/fallback series.
+func TestObserveSummarizeRecordsModelOutcomeFallback(t *testing.T) {
+	before := histCount(t, summarizeDuration.WithLabelValues("koala/phi4-mini", "success", "false"))
+	ObserveSummarize("koala/phi4-mini", "success", false, 1200*time.Millisecond)
+	after := histCount(t, summarizeDuration.WithLabelValues("koala/phi4-mini", "success", "false"))
+	require.Equal(t, before+1, after, "one success observation recorded for the model")
+}
+
+// TestObserveSummarizeRecordsFailureOutcomes: error and parse_error are distinct
+// series so a fallback chain's failures are visible.
+func TestObserveSummarizeRecordsFailureOutcomes(t *testing.T) {
+	e0 := histCount(t, summarizeDuration.WithLabelValues("m", "error", "false"))
+	p0 := histCount(t, summarizeDuration.WithLabelValues("m", "parse_error", "false"))
+	ObserveSummarize("m", "error", false, time.Second)
+	ObserveSummarize("m", "parse_error", false, time.Second)
+	require.Equal(t, e0+1, histCount(t, summarizeDuration.WithLabelValues("m", "error", "false")))
+	require.Equal(t, p0+1, histCount(t, summarizeDuration.WithLabelValues("m", "parse_error", "false")))
+}
+
+func TestObserveCaptionFetchByOutcome(t *testing.T) {
+	b := histCount(t, captionFetchDuration.WithLabelValues("captions"))
+	ObserveCaptionFetch("captions", 3*time.Second)
+	require.Equal(t, b+1, histCount(t, captionFetchDuration.WithLabelValues("captions")))
+}
+
+func TestChatAnswerLatencyRecorded(t *testing.T) {
+	b := histCount(t, chatDuration.WithLabelValues("iguana/gemma4-26b"))
+	ObserveChat("iguana/gemma4-26b", 2*time.Second)
+	require.Equal(t, b+1, histCount(t, chatDuration.WithLabelValues("iguana/gemma4-26b")))
+}
+
+// TestRecordTokens: prompt + completion land on their kind series; zero is skipped.
+func TestRecordTokens(t *testing.T) {
+	p0 := testutil.ToFloat64(llmTokens.WithLabelValues("m", "prompt"))
+	c0 := testutil.ToFloat64(llmTokens.WithLabelValues("m", "completion"))
+	RecordTokens("m", 100, 40)
+	RecordTokens("m", 0, 0) // skipped, no panic
+	require.Equal(t, p0+100, testutil.ToFloat64(llmTokens.WithLabelValues("m", "prompt")))
+	require.Equal(t, c0+40, testutil.ToFloat64(llmTokens.WithLabelValues("m", "completion")))
+}
+
+func TestLoginCounted(t *testing.T) {
+	b := testutil.ToFloat64(logins)
+	IncLogin()
+	require.Equal(t, b+1, testutil.ToFloat64(logins))
+}
+
+// TestHTTPMiddlewareRecordsByRoutePattern: the request is counted under the bounded
+// registered pattern (r.Pattern after routing), not the raw path with its ids.
+func TestHTTPMiddlewareRecordsByRoutePattern(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET /v/{videoId}", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusTeapot)
+	})
+	h := HTTPMiddleware(mux)
+
+	before := testutil.ToFloat64(httpRequests.WithLabelValues("GET", "GET /v/{videoId}", "418"))
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/v/abc-123", nil))
+
+	require.Equal(t, http.StatusTeapot, rec.Code)
+	after := testutil.ToFloat64(httpRequests.WithLabelValues("GET", "GET /v/{videoId}", "418"))
+	require.Equal(t, before+1, after, "counted under the pattern, not /v/abc-123")
+	require.Equal(t, float64(0), testutil.ToFloat64(httpRequests.WithLabelValues("GET", "/v/abc-123", "418")),
+		"raw path must never be a label value")
+}

internal/ports/ports.go

@@ -7,7 +7,7 @@ package ports
 import (
 	"context"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 // VideoSource is a video platform Tapir watches (YouTube, Vimeo).