test(store): address migrations by version, not step count (#8)

The up/down migration tests stepped a hard-coded number of Steps(-N)/Steps(+N)
down from HEAD and back. The counts assumed a specific latest migration, so
adding one shifted every count by one and unrelated tests (010/011/014) went
red with confusing off-by-one symptoms — a papercut on every new migration.

Drive the schema to an exact version with m.Migrate(version) via two helpers
(headVersion, migrateTo). Each test now steps to just below its target by
version, asserts the down effect, steps up to the target, asserts the up
effect, then restores to the captured HEAD. A migration added on top changes
HEAD but shifts no count, so no test needs editing.

Verified by adding a throwaway migration 017 on top: all four tests stayed
green with zero edits.

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

.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
 

DECISIONS.md

@@ -1162,6 +1162,158 @@ re-login now rare (30-day idle or explicit logout), it matters far less.
 
 ---
 
+## ADR-030 — Observability: slog timing + Prometheus metrics (AI-focused)
+
+**Status:** Proposed (2026-06-11). Issue #15. **Draft for review — no code yet.**
+
+**Context / requirements.** Nothing measures the activities that drive Tapir's performance and
+UX, and the Stage-0 eval gate (ADR-016) needs a *performance* dimension to sit beside the
+return-usage one. We need timing for: caption fetches (the scarce op), summarization (which model
+won, how long, fallbacks), Q&A latency, LLM token spend, and basic session/usage (request rate,
+latency by route, logins). Requirements:
+- R1: structured `slog` timing at each AI call site (human-readable, already the logging stack).
+- R2: Prometheus metrics for the same, scrapeable by the cluster's prometheus-operator.
+- R3: **AI metrics are the priority** — summarize latency by `model`/`outcome`/`fallback`,
+  caption-fetch latency by `outcome`, chat latency by `model`, and LLM `tokens` by model+kind.
+- R4: HTTP/session metrics via middleware — request count + latency by route, logins.
+- R5: bounded label cardinality (no per-user, no raw-path labels).
+- R6: `/metrics` must NOT be publicly exposed.
+
+**Decision / architecture.**
+1. **New package `internal/metrics`** owns all Prometheus collectors + a typed API
+   (`ObserveSummarize`, `ObserveCaptionFetch`, `ObserveChat`, `RecordTokens`, `IncLogin`,
+   `HTTPMiddleware`, `Handler`). Adapters call this API; they never import prometheus types.
+2. **New dependency `github.com/prometheus/client_golang`.** Justification: it is *the* standard
+   Go Prometheus client and the cluster already runs prometheus-operator; hand-rolling exposition
+   is not worth it. (Needs the dep-justification note in the commit per repo rules.)
+3. **The copied `llm` package stays stdlib-only (ADR-004).** It must not import `internal/metrics`.
+   Token usage is surfaced via an **optional callback** `llm.WithUsageHook(func(model string, prompt, completion int))`
+   set at wiring time (`buildSummarizer`/`buildChat`) to `metrics.RecordTokens`; `llm.Client` only
+   gains parsing of the response `usage` block. Our own adapters (`summarizer`, `youtube`, `chat`)
+   may import `internal/metrics` directly.
+4. **HTTP middleware** reads `r.Pattern` AFTER routing (Go 1.22 sets it during ServeMux match), so
+   the `route` label is the bounded registered pattern (`GET /v/{videoId}`), satisfying R5;
+   unmatched → `other`.
+5. **Dedicated metrics port** (`TAPIR_METRICS_ADDR`, default `:9090`) served by a second
+   `http.Server` in `cmdServe`; `/metrics` is never on the public app mux (R6). A **PodMonitor**
+   in `mathias/infra` scrapes it; the deployment exposes the port.
+6. **slog** elapsed fields are emitted alongside each metric at the call sites (R1).
+
+**Hook points (where the instrumentation lands).**
+- `summarizer.Summarize` — per-endpoint timing + outcome (`success`/`parse_error`/`error`) + fallback flag.
+- `youtube.FetchTranscript` — fetch timing + outcome from `domain.Transcript.Source`.
+- `chat.Service` answer — timing by model.
+- `llm.Client.Complete` — parse `usage`, fire the usage hook.
+- `oidc.handleCallback` — `IncLogin`.
+- `cmdServe` — wrap `Router()` in `metrics.HTTPMiddleware`; start the metrics server.
+
+**Out of scope / later.** Persisting per-summary latency into Postgres for `tapir report`
+(derive UX latency — publish/discovery → summary — from existing timestamps first; only persist
+op-latency if the scrape proves insufficient). SPA view (#16) and visual refresh (#17).
+
+**Reversibility.** Additive: a new package + middleware + a metrics port. Removing the PodMonitor
+stops scraping; the app is unaffected. No schema change.
+
+**Next steps (gated):** on approval of this ADR → BDD scenarios (`docs/use-cases/observability.feature`
++ scenario-coverage map) → TDD → implement → SemVer + docs + PodMonitor.
+
+---
+
+## ADR-031 — SPA-like reader: inline-expand summary + Q&A in the list (HTMX, no framework)
+
+**Status:** Proposed (2026-06-12). Issue #16. **Draft for review — no code yet.**
+
+**Context / requirements.** The reader is multi-page: a list of compact cards (`/`), then a
+navigation to a separate detail page (`/v/{id}`) for the full summary + the docked chat (ADR-027).
+It feels less fluid than a single integrated view. We want the full summary AND the per-video
+Q&A to open **in place in the list**, no page hop. Requirements:
+- R1: clicking a summarized card expands it in place to the full summary (summary/highlights/
+  takeaways) + the chat dock; a collapse returns it to the compact card.
+- R2: **no SPA framework** — stay HTMX + Templ (ADR-003); reuse existing fragments, not a rewrite.
+- R3: **progressive enhancement** — with JS off, the card link still navigates to `/v/{id}`
+  (the detail page stays as the no-JS + deep-link surface). Nothing becomes JS-only.
+- R4: only **summarized** cards expand; pending/rate-limited/no-caption cards keep their current
+  footer behaviour (Summarize button, waiting/none states).
+- R5: chat inside an expanded card works exactly as on the detail page (reuse `chatReveal`/
+  `chatSection` + the existing `/v/{id}/chat` endpoints, unchanged).
+
+**Decision / architecture.**
+1. **Reuse the existing fragments.** `summaryBody(r)` and `chatReveal(videoID)` already exist and
+   render the detail page; a new `expandedCard(r, chatEnabled)` composes the compact header + a
+   collapse control + `summaryBody` + `chatReveal`. `DetailPage` is refactored to also compose
+   `summaryBody` so the two never drift (DRY).
+2. **Two fragment endpoints** (mirroring the existing list/status HTMX fragment pattern):
+   `GET /v/{videoId}/expand` → `expandedCard`; collapse reuses the existing compact `VideoCard`
+   via `GET /v/{videoId}/card`. Both are list-card `<li>` fragments with the SAME `id`
+   (`video-{id}`), swapped `outerHTML` — same mechanism as `processingCard`/`VideoCard` today.
+3. **The compact card's title/"Read" affordance** becomes `hx-get=/v/{id}/expand`,
+   `hx-target=#video-{id}`, `hx-swap=outerHTML`, with `href=/v/{id}` as the no-JS fallback (R3).
+   The expanded card's collapse control is the inverse (`hx-get=/v/{id}/card`).
+4. **Only when `r.Summarized`** does the expand affordance render (R4); the other states are
+   unchanged.
+5. **v1 does NOT push the URL** (`hx-push-url`) — expand/collapse is ephemeral list UI state; the
+   detail page remains the deep-link/shareable URL. Deep-linking the open state via `hx-push-url`
+   is noted as a later option (needs list-state restore on back).
+
+**Out of scope / later.** URL push / deep-linkable open state; the visual refresh (#17) — though
+the expanded-card markup is where #17's TUI/charm styling will land, so they pair.
+
+**Reversibility.** Additive: two fragment endpoints + one templ + an affordance swap on the
+compact card. Removing the affordance reverts to plain list→detail navigation; the detail page is
+untouched. No schema change.
+
+**Next steps (gated):** on approval → BDD (`docs/use-cases/inline_expand.feature` + coverage
+map) → TDD → implement → SemVer + docs.
+
+---
+
+## ADR-032 — Visual refresh: one charm-reader layout, light + dark themes
+
+**Status:** Proposed (2026-06-12). Issue #17. **Draft for review — no code yet.** Follows the
+sketch-first explore step (3 throwaway mockups in `docs/sketches/`, screenshotted for review).
+
+**Context / decision.** The UI is flat. From the mockups, directions **B (light reader + charm)**
+and **C (dark cozy terminal)** are the SAME layout — readable sans body, monospace meta, charm
+palette accents, lipgloss-style bordered cards — in two palettes. Direction A (full-monospace TUI)
+is dropped as too heavy to read long summaries. Decision: ship that one layout with **both a light
+theme (B) and a dark theme (C)**, user-toggleable, defaulting to the OS preference.
+
+**Requirements.**
+- R1: one set of markup/structure; the two themes are pure palette (CSS variables), no duplicate templates.
+- R2: a **theme toggle** persisted across visits; default to `prefers-color-scheme` when no choice stored.
+- R3: charm language in both — mint/purple/pink accents, mono meta + section labels, lipgloss
+  bordered/gradient cards, the (fixed) ASCII tapir; readable sans body.
+- R4: style the existing pieces — list, compact card, **expanded card incl. the already-present
+  video embed (ADR-031/summaryBody)**, detail page, chat dock, the queue note, the charm spinner.
+- R5: WCAG-AA contrast for body text in BOTH themes; keep `prefers-reduced-motion` (already honoured).
+- R6: stay HTMX+Templ; no CSS framework.
+
+**Architecture.**
+1. **Palette as CSS variables.** `:root` holds the light (B) tokens; `:root[data-theme="dark"]`
+   holds the dark (C) tokens; a `prefers-color-scheme: dark` media block sets the dark tokens when
+   no explicit `data-theme` is set. All component CSS references variables only (R1). The existing
+   `CharmMint/Purple/Pink/Cream/Dim` Go consts remain the source for the spinner's inline colours.
+2. **Theme toggle** = a small inline script (a dozen lines, no framework) in `Layout`: on load,
+   apply stored theme (localStorage) or fall through to the media query; a header toggle button
+   flips `data-theme` on `<html>` and stores it. This is the one new bit of JS; everything else
+   stays server-rendered + HTMX. (Considered: cookie + server-render — rejected, a full round-trip
+   per toggle is clunky for a pure presentation flip.)
+3. **Scope = the `styleTag` CSS in `view.go`** (the single style source) plus tiny class hooks in
+   the templ where needed; content/structure are unchanged, so existing view tests keep passing.
+
+**Verification.** The deployed UI is behind auth (web-shot can't log in), so visual review is via
+the mockups now + a styled full-set mockup screenshot before merge, then a live eyeball on device.
+Automated tests stay structural/behavioural (theme tokens present, toggle persists, expanded card
+embeds the video, no-JS still renders a readable default) — colours are not unit-tested.
+
+**Reversibility.** A CSS theme swap + one small script + a few class hooks; revert `styleTag` to
+roll back. No schema, no structural change.
+
+**Next steps (gated):** on approval → BDD (`docs/use-cases/visual_theme.feature` + coverage map)
+→ TDD → implement → SemVer + docs.
+
+---
+
 ## Rejected alternatives
 
 Approaches considered during the 2026-06-02 planning + grill session and **deliberately not

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

@@ -4,7 +4,7 @@ import (
 	"strings"
 	"testing"
 
-	"gitea.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/config"
 )
 
 // TestChatModelsReuseTheChainLocalFirst: the switcher offers the ADR-022 chain in

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/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"
+	"git.d-ma.be/mathias/tapir/internal/adapters/secrets"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/youtube"
+	"git.d-ma.be/mathias/tapir/internal/adapters/youtube"
-	"gitea.d-ma.be/mathias/tapir/internal/auth"
+	"git.d-ma.be/mathias/tapir/internal/auth"
-	"gitea.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/config"
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
+	"git.d-ma.be/mathias/tapir/internal/metrics"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/runner"
-	"gitea.d-ma.be/mathias/tapir/internal/web/oidc"
+	"git.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web/oidc"
 )
 
 func main() {
@@ -310,16 +311,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,17 +5,18 @@ import (
 	"fmt"
 	"strings"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/chat"
+	"git.d-ma.be/mathias/tapir/internal/adapters/chat"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/llm"
+	"git.d-ma.be/mathias/tapir/internal/adapters/llm"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/secrets"
+	"git.d-ma.be/mathias/tapir/internal/adapters/secrets"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/summarizer"
+	"git.d-ma.be/mathias/tapir/internal/adapters/summarizer"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/youtube"
+	"git.d-ma.be/mathias/tapir/internal/adapters/youtube"
-	"gitea.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/config"
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/metrics"
-	"gitea.d-ma.be/mathias/tapir/internal/usecase"
+	"git.d-ma.be/mathias/tapir/internal/ports"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"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
@@ -69,7 +70,7 @@ func buildSummarizer(cfg config.Config) *summarizer.Summarizer {
 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)),
+			Client:   llm.New(cfg.GatewayURL, cfg.GatewayKey, model, cfg.SummarizerTimeout, llm.WithMaxTokens(cfg.SummaryMaxTokens), llm.WithUsageHook(metrics.RecordTokens)),
 			Provider: providerOf(model),
 			Model:    model,
 		}
@@ -150,7 +151,7 @@ func buildChat(cfg config.Config) *chat.Service {
 		return nil
 	}
 	newClient := func(model string) chat.Completer {
-		return llm.New(cfg.GatewayURL, cfg.GatewayKey, model, cfg.SummarizerTimeout, llm.WithMaxTokens(cfg.SummaryMaxTokens))
+		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)
 }

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

cmd/tapir/report.go

@@ -8,7 +8,7 @@ import (
 	"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

cmd/tapir/report_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"
 )
 
 var testSince = time.Date(2026, 6, 11, 0, 0, 0, 0, time.UTC)

cmd/tapir/scheduler.go

@@ -6,13 +6,13 @@ import (
 	"log/slog"
 	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/youtube"
+	"git.d-ma.be/mathias/tapir/internal/adapters/youtube"
-	"gitea.d-ma.be/mathias/tapir/internal/config"
+	"git.d-ma.be/mathias/tapir/internal/config"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/ports"
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
+	"git.d-ma.be/mathias/tapir/internal/runner"
-	"gitea.d-ma.be/mathias/tapir/internal/usecase"
+	"git.d-ma.be/mathias/tapir/internal/usecase"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // buildUserRunner constructs a runner.Runner for one user, reusing the same

cmd/tapir/scheduler_test.go

@@ -11,8 +11,8 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
+	"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,

docs/homelab-integration.md

@@ -227,6 +227,12 @@ knobs plus one load-bearing deployment constraint:
 - `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/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/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/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.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
-github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+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/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=
-github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+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=
+go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI=
-golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
+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/chat/chat.go

@@ -13,8 +13,12 @@ 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
@@ -113,10 +117,14 @@ func (s *Service) Answer(ctx context.Context, req Request) (Reply, error) {
 	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)

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/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,25 +78,15 @@ func TestMigration010LoginEventsUpDown(t *testing.T) {
 	require.True(t, loginEventsExists(t), "login_events must exist at latest migration")
 
 	m := fileMigrator(t)
-	// 011..016 sit above 010; step them down first so 010 is exercised in isolation.
+	head := headVersion(t, m)
-	require.NoError(t, m.Steps(-1), "down 016 drops channel_caption_state, login_events intact")
-	require.True(t, loginEventsExists(t), "016 down leaves login_events intact")
-	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")
 
-	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(7), "up must recreate 010 then re-apply 011..016")
+	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
@@ -93,21 +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 016 drops channel_caption_state")
+	head := headVersion(t, m)
-	require.NoError(t, m.Steps(-1), "down 015 reshapes transcripts")
+
-	require.NoError(t, m.Steps(-1), "down 014 drops channel_title")
+	migrateTo(t, m, 10) // just below 011 — reverts the column default
-	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")
 	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")
+	migrateTo(t, m, head) // restore to HEAD for sibling tests
-	require.NoError(t, m.Steps(1), "up 014 recreates channel_title")
-	require.NoError(t, m.Steps(1), "up 015 reshapes transcripts to shared")
-	require.NoError(t, m.Steps(1), "up 016 recreates channel_caption_state (HEAD)")
 }
 
 // channelTitleExists reports whether videos.channel_title is present.
@@ -127,17 +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 016 drops channel_caption_state, channel_title intact")
+	head := headVersion(t, m)
-	require.True(t, channelTitleExists(t), "016 down leaves channel_title intact")
+
-	require.NoError(t, m.Steps(-1), "down 015 reshapes transcripts, channel_title intact")
+	migrateTo(t, m, 13) // just below 014 — drops channel_title
-	require.True(t, channelTitleExists(t), "015 down leaves channel_title intact")
-	require.NoError(t, m.Steps(-1), "down 014 must drop 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")
+
-	require.NoError(t, m.Steps(1), "up 016 recreates channel_caption_state (HEAD)")
+	migrateTo(t, m, head) // restore to HEAD for sibling tests
 }
 
 // TestMigration012FixAutoSummarizeRLS proves 012 runs cleanly and flips any
@@ -148,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")
+	head := headVersion(t, m)
-	require.NoError(t, m.Steps(1), "up 012 must re-apply cleanly")
+
+	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/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/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

@@ -11,9 +11,9 @@ 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"
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/ports"
 )
 
 // Static check: Store satisfies the Sink port.

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"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/ports"
 )
 
 // Static check: Store satisfies the shared TranscriptStore port (ADR-021).

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

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 {

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"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"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/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/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"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/ports"
 )
 
 // defaultBaseURL is the YouTube Data API v3 root. Overridable via Config.BaseURL

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

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

@@ -143,6 +143,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.
@@ -178,6 +183,7 @@ const (
 	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"
@@ -209,6 +215,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"),

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).

internal/runner/runner.go

@@ -19,9 +19,9 @@ import (
 	"slices"
 	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/ports"
-	"gitea.d-ma.be/mathias/tapir/internal/usecase"
+	"git.d-ma.be/mathias/tapir/internal/usecase"
 )
 
 // passCandidate is a video that passed all pre-filters (seen/manual/backoff)

internal/runner/runner_test.go

@@ -9,9 +9,9 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/runner"
+	"git.d-ma.be/mathias/tapir/internal/runner"
-	"gitea.d-ma.be/mathias/tapir/internal/usecase"
+	"git.d-ma.be/mathias/tapir/internal/usecase"
 )
 
 const testUser = "11111111-1111-1111-1111-111111111111"

internal/usecase/engine.go

@@ -14,8 +14,8 @@ import (
 	"fmt"
 	"sync"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/ports"
+	"git.d-ma.be/mathias/tapir/internal/ports"
 )
 
 // ErrNotImplemented marks scaffold methods awaiting implementation.

internal/usecase/engine_transcript_test.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"testing"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 // These tests pin the ADR-021 read-stored-first behaviour at the engine core:

internal/web/account.go

@@ -3,7 +3,7 @@ package web
 import (
 	"net/http"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // handleAccount renders the account page: the user's display name, the

internal/web/account_test.go

@@ -9,8 +9,8 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // fakeSecrets is a SecretRemover that records the refs it was asked to delete, so

internal/web/chat.go

@@ -6,8 +6,8 @@ import (
 	"net/http"
 	"strings"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/chat"
+	"git.d-ma.be/mathias/tapir/internal/adapters/chat"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // Chatter is the per-video chat backend (ADR-027). *chat.Service satisfies it;

internal/web/chat_handler_test.go

@@ -12,10 +12,10 @@ import (
 	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/chat"
+	"git.d-ma.be/mathias/tapir/internal/adapters/chat"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // videoZ is a video id used by the isolation test for a DIFFERENT user's video.

internal/web/connect.go

@@ -12,8 +12,8 @@ import (
 	"sync"
 	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/auth"
+	"git.d-ma.be/mathias/tapir/internal/auth"
 )
 
 // Connections is the narrow write port the connect flow depends on (Clean

internal/web/connect_test.go

@@ -11,9 +11,9 @@ import (
 	"github.com/stretchr/testify/require"
 	"golang.org/x/oauth2"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/auth"
+	"git.d-ma.be/mathias/tapir/internal/auth"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // fakeWriter is a TokenWriter capturing the persisted (ref, value).

internal/web/handlers.go

@@ -11,8 +11,8 @@ import (
 
 	"github.com/a-h/templ"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 // Store is the read/write surface the web handlers depend on — a narrow port over
@@ -151,6 +151,8 @@ func (a *App) Router() http.Handler {
 	app := http.NewServeMux()
 	app.HandleFunc("GET /{$}", a.handleList)
 	app.HandleFunc("GET /v/{videoId}", a.handleDetail)
+	app.HandleFunc("GET /v/{videoId}/expand", a.handleExpand)
+	app.HandleFunc("GET /v/{videoId}/card", a.handleCard)
 	app.HandleFunc("POST /v/{videoId}/action", a.handleAction)
 	app.HandleFunc("POST /v/{videoId}/summarize", a.handleRequestSummarize)
 	app.HandleFunc("POST /v/{videoId}/retry-now", a.handleRetryNow)
@@ -283,6 +285,48 @@ func (a *App) handleDetail(w http.ResponseWriter, r *http.Request) {
 	a.render(w, r, DetailPage(*row, a.Chat != nil))
 }
 
+// handleExpand returns the inline-expanded card fragment — the full summary +
+// chat dock swapped into the list card in place (ADR-031). Only summarized videos
+// have a summary to expand; a non-summarized id is a 404 (the compact card never
+// offers expand for it).
+func (a *App) handleExpand(w http.ResponseWriter, r *http.Request) {
+	userID, ok := a.currentUserID(w, r)
+	if !ok {
+		return
+	}
+	videoID := r.PathValue("videoId")
+	row, err := a.Store.GetSummaryByVideo(r.Context(), userID, videoID)
+	if errors.Is(err, store.ErrNotFound) {
+		http.NotFound(w, r)
+		return
+	}
+	if err != nil {
+		a.serverError(w, r, "get summary", err)
+		return
+	}
+	a.render(w, r, expandedCard(*row, a.Chat != nil))
+}
+
+// handleCard returns the compact card fragment — the collapse target that returns
+// an expanded card to its compact form in the list (ADR-031).
+func (a *App) handleCard(w http.ResponseWriter, r *http.Request) {
+	userID, ok := a.currentUserID(w, r)
+	if !ok {
+		return
+	}
+	videoID := r.PathValue("videoId")
+	row, err := a.Store.GetVideoRow(r.Context(), userID, videoID)
+	if errors.Is(err, store.ErrNotFound) {
+		http.NotFound(w, r)
+		return
+	}
+	if err != nil {
+		a.serverError(w, r, "get video", err)
+		return
+	}
+	a.render(w, r, VideoCard(*row))
+}
+
 // handleAction toggles one action: re-clicking an active verb clears it, else it
 // is set (the store enforces watched↔skipped exclusion atomically). It returns
 // the refreshed button-group fragment for HTMX; without JS it redirects back to

internal/web/handlers_test.go

@@ -16,9 +16,9 @@ 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"
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // dsn points at the in-process Postgres started in TestMain. Handler tests run
@@ -524,3 +524,12 @@ func TestListAutoModeBannerCopy(t *testing.T) {
 	require.Contains(t, html, "land gradually")
 	require.NotContains(t, html, "are not summarized automatically")
 }
+
+// TestMetricsNotOnPublicMux: the public app router exposes no /metrics route —
+// Prometheus is served on the dedicated metrics port only (ADR-030, security R6).
+func TestMetricsNotOnPublicMux(t *testing.T) {
+	app := newApp(t)
+	resetDB(t, rawPool(t))
+	rec := do(t, app, httptest.NewRequest(http.MethodGet, "/metrics", nil))
+	require.Equal(t, http.StatusNotFound, rec.Code, "/metrics must not be on the public mux")
+}

internal/web/inline_expand_test.go

@@ -0,0 +1,107 @@
+package web_test
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestExpandReturnsSummaryBodyFragment: GET /v/{id}/expand returns the full
+// summary as an in-place card fragment (not a full page) — ADR-031.
+func TestExpandReturnsSummaryBodyFragment(t *testing.T) {
+	ctx := context.Background()
+	app := newApp(t)
+	p := rawPool(t)
+	resetDB(t, p)
+	require.NoError(t, deliver(ctx, app, videoX, "the full summary text"))
+	seedVideo(t, p, videoX, "X Title", "https://x", time.Time{})
+
+	html := body(t, do(t, app, httptest.NewRequest(http.MethodGet, "/v/"+videoX+"/expand", nil)))
+	require.Contains(t, html, "the full summary text")
+	require.Contains(t, html, "Takeaways")
+	require.Contains(t, html, "highlight one")
+	require.Contains(t, html, "card-expanded", "rendered as the expanded card")
+	require.Contains(t, html, "/v/"+videoX+"/card", "carries a collapse affordance")
+	require.NotContains(t, html, "<html", "fragment, not a full page")
+}
+
+// TestCollapseReturnsCompactCard: GET /v/{id}/card returns the compact card with
+// the expand affordance — the collapse target.
+func TestCollapseReturnsCompactCard(t *testing.T) {
+	ctx := context.Background()
+	app := newApp(t)
+	p := rawPool(t)
+	resetDB(t, p)
+	require.NoError(t, deliver(ctx, app, videoX, "summary text"))
+	seedVideo(t, p, videoX, "X Title", "https://x", time.Time{})
+
+	html := body(t, do(t, app, httptest.NewRequest(http.MethodGet, "/v/"+videoX+"/card", nil)))
+	require.Contains(t, html, `class="card"`, "compact card")
+	require.Contains(t, html, "/v/"+videoX+"/expand", "compact card offers expand")
+	require.NotContains(t, html, "card-expanded")
+	require.NotContains(t, html, "<html", "fragment, not a full page")
+}
+
+// TestExpandedCardOffersChatDock: with chat enabled, the expanded card includes
+// the deeper-dive chat affordance.
+func TestExpandedCardOffersChatDock(t *testing.T) {
+	ctx := context.Background()
+	app := newChatApp(t, &fakeChatter{models: []string{"m"}}, nil)
+	p := rawPool(t)
+	resetDB(t, p)
+	require.NoError(t, deliver(ctx, app, videoX, "summary text"))
+	seedVideo(t, p, videoX, "X Title", "https://x", time.Time{})
+
+	html := body(t, do(t, app, httptest.NewRequest(http.MethodGet, "/v/"+videoX+"/expand", nil)))
+	require.Contains(t, html, "/v/"+videoX+"/chat", "expanded card wires the chat dock")
+}
+
+// TestCompactCardExpandOnlyWhenSummarized: a not-yet-summarized card shows its
+// summarize footer and no expand affordance.
+func TestCompactCardExpandOnlyWhenSummarized(t *testing.T) {
+	app := newApp(t)
+	p := rawPool(t)
+	resetDB(t, p)
+	seedVideo(t, p, videoX, "Pending Title", "https://x", time.Time{}) // no summary
+
+	html := body(t, do(t, app, httptest.NewRequest(http.MethodGet, "/v/"+videoX+"/card", nil)))
+	require.Contains(t, html, "Not summarized")
+	require.NotContains(t, html, "/v/"+videoX+"/expand", "pending card offers no expand")
+}
+
+// TestCompactCardHasNoJSDetailFallback: the expand affordance carries an href to
+// the detail page, so JS-off users still reach the full summary.
+func TestCompactCardHasNoJSDetailFallback(t *testing.T) {
+	ctx := context.Background()
+	app := newApp(t)
+	p := rawPool(t)
+	resetDB(t, p)
+	require.NoError(t, deliver(ctx, app, videoX, "summary text"))
+	seedVideo(t, p, videoX, "X Title", "https://x", time.Time{})
+
+	html := body(t, do(t, app, httptest.NewRequest(http.MethodGet, "/v/"+videoX+"/card", nil)))
+	require.Contains(t, html, `href="/v/`+videoX+`"`, "no-JS fallback to the detail page")
+	require.Contains(t, html, "/v/"+videoX+"/expand", "and the HTMX expand for JS users")
+}
+
+// TestDetailAndExpandShareSummaryBody: the detail page and the expanded card render
+// the same summary body (one shared fragment, no drift).
+func TestDetailAndExpandShareSummaryBody(t *testing.T) {
+	ctx := context.Background()
+	app := newApp(t)
+	p := rawPool(t)
+	resetDB(t, p)
+	require.NoError(t, deliver(ctx, app, videoX, "shared summary text"))
+	seedVideo(t, p, videoX, "X Title", "https://x", time.Time{})
+
+	detail := body(t, do(t, app, httptest.NewRequest(http.MethodGet, "/v/"+videoX, nil)))
+	expand := body(t, do(t, app, httptest.NewRequest(http.MethodGet, "/v/"+videoX+"/expand", nil)))
+	for _, want := range []string{"shared summary text", "Takeaways", "highlight one"} {
+		require.Contains(t, detail, want)
+		require.Contains(t, expand, want)
+	}
+}

internal/web/oidc/oidc.go

@@ -27,7 +27,8 @@ import (
 	"github.com/coreos/go-oidc/v3/oidc"
 	"golang.org/x/oauth2"
 
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/metrics"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // Config is the OIDC + session configuration. cmd/tapir maps these from
@@ -253,6 +254,7 @@ func (d *DexAuth) handleCallback(w http.ResponseWriter, r *http.Request) {
 
 	user := web.User{Subject: idToken.Subject, Email: claims.Email}
 	d.setSessionCookie(w, d.encodeSession(user, d.now().Add(d.sessionTTL)))
+	metrics.IncLogin()
 	http.Redirect(w, r, "/", http.StatusFound)
 }
 

internal/web/oidc/oidc_test.go

@@ -14,8 +14,8 @@ import (
 	josev4 "github.com/go-jose/go-jose/v4"
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
-	"gitea.d-ma.be/mathias/tapir/internal/web/oidc"
+	"git.d-ma.be/mathias/tapir/internal/web/oidc"
 )
 
 const (

internal/web/oidc/session.go

@@ -12,7 +12,7 @@ import (
 	"sync"
 	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // randToken returns a URL-safe 256-bit random string for session IDs, OIDC

internal/web/paste_handler_test.go

@@ -11,7 +11,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 // fakeFetcher is a web.VideoFetcher returning a fixed video (or an error),

internal/web/paste_test.go

@@ -3,7 +3,7 @@ package web
 import (
 	"bytes"
 	"context"
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 	"strings"
 	"testing"
 )

internal/web/processing.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"sync"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
 )
 
 // Processor runs the core summarization use case for a single already-discovered

internal/web/processing_handler_test.go

@@ -10,7 +10,7 @@ import (
 	"github.com/jackc/pgx/v5/pgxpool"
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // fakeProcessor records ProcessVideo calls. With block set it parks until the

internal/web/videocard_internal_test.go

@@ -5,7 +5,7 @@ import (
 	"strings"
 	"testing"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 func renderVideoCard(t *testing.T, r store.SummaryRow) string {

internal/web/view.go

@@ -9,7 +9,7 @@ import (
 
 	"github.com/a-h/templ"
 
-	"gitea.d-ma.be/mathias/tapir/internal/adapters/store"
+	"git.d-ma.be/mathias/tapir/internal/adapters/store"
 )
 
 // youtubeIDRe matches a canonical 11-char YouTube video id (the provider's
@@ -190,6 +190,18 @@ func chatURL(videoID string) templ.SafeURL {
 	return templ.SafeURL("/v/" + videoID + "/chat")
 }
 
+// expandURL builds the inline-expand fragment path (GET) — the full summary + chat
+// dock swapped into the list card in place (ADR-031).
+func expandURL(videoID string) templ.SafeURL {
+	return templ.SafeURL("/v/" + videoID + "/expand")
+}
+
+// cardURL builds the compact-card fragment path (GET) — the collapse target that
+// returns an expanded card to its compact form (ADR-031).
+func cardURL(videoID string) templ.SafeURL {
+	return templ.SafeURL("/v/" + videoID + "/card")
+}
+
 // Charmbracelet-inspired palette for the summarizing animation (TapirSpinner) —
 // a charm purple box, pink tapir, mint snout/eyes/progress. Kept as named consts
 // so the inline span colours and the CSS track/fill share one source of truth.
@@ -566,33 +578,71 @@ func (f Filter) apply(rows []store.SummaryRow) []store.SummaryRow {
 // not as template expressions — so the CSS is rendered as a raw node instead).
 var styleTag = "<style>" + stylesheet + "</style>"
 
-// The design system is a small set of CSS custom properties: one accent, a
+// themeScript powers the light/dark toggle (ADR-032). The init runs in <head>
-// 4/8px-derived spacing scale, a single radius, and full light+dark palettes so
+// before paint: if the visitor has a stored choice it is applied as data-theme
-// color-scheme: light dark is actually honoured (review #1). Muted is #595959
+// immediately, so there is no flash of the wrong palette; with no stored choice
-// (~7:1 on white) / #9aa0a8 on dark to clear WCAG AA (review #4).
+// nothing is set and the CSS @media (prefers-color-scheme) default takes over.
+// tapirToggleTheme flips to the opposite of the *effective* theme (reading
+// matchMedia when no explicit choice is set yet) and persists it. localStorage
+// access is guarded so a privacy-locked browser degrades to the OS default.
+const themeScript = `
+(function(){try{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')document.documentElement.setAttribute('data-theme',t);}catch(e){}})();
+function tapirToggleTheme(){var d=document.documentElement,c=d.getAttribute('data-theme');if(!c){c=window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';}var n=c==='dark'?'light':'dark';d.setAttribute('data-theme',n);try{localStorage.setItem('theme',n);}catch(e){}}
+`
+
+// themeScriptTag is the init/toggle script, injected verbatim in <head>.
+var themeScriptTag = "<script>" + themeScript + "</script>"
+
+// themeToggleButton is the header control that calls tapirToggleTheme. Shared by
+// the authenticated and public layouts so the toggle is on every page.
+const themeToggleButton = `<button type="button" class="theme-toggle" onclick="tapirToggleTheme()" aria-label="Toggle light or dark theme" title="Toggle light/dark">◐</button>`
+
+// The design system is one charm-reader layout in two palettes (ADR-032, #17):
+// a warm "reader" light theme (sketch B) and a "cozy terminal" dark theme
+// (sketch C), both expressed as CSS custom properties. The palette is selected
+// three ways, in cascade order: the :root light default; an OS-preference dark
+// block that applies only when the visitor has made no explicit choice
+// (:root:not([data-theme])); and an explicit :root[data-theme="dark"|"light"]
+// set by the persisted toggle, which outranks the media query by specificity.
+// charmDarkVars is declared once and injected in both dark selectors so the two
+// never drift. Muted clears WCAG AA on each background (#5b5968 on cream,
+// #a59cc0 on the dark card). Error/danger shades are tokens so they follow the
+// theme too, instead of needing per-block dark overrides.
+const charmDarkVars = `
+    --bg:#16131d; --card:#1e1a28; --fg:#ece7f5; --muted:#a59cc0; --line:#322b44;
+    --mint:#2ee6b6; --purple:#9d7bff; --pink:#ff6bdb; --cream:#f3ead8;
+    --accent:#9d7bff; --accent-fg:#16131d; --accent-weak:#2a2340;
+    --badge-bg:#caa24a; --badge-fg:#1a1300;
+    --err-bg:#3a1714; --err-fg:#f3b5ae; --err-line:#a6362e;`
+
 const stylesheet = `
 :root {
   color-scheme: light dark;
-  --bg:#fbfbfa; --card:#ffffff; --fg:#1a1a1a; --muted:#595959; --line:#e4e4e1;
+  --bg:#faf7f2; --card:#ffffff; --fg:#1c1b22; --muted:#5b5968; --line:#e7e2d8;
-  --accent:#2b6cb0; --accent-fg:#ffffff; --accent-weak:#eaf1f8;
+  --mint:#0bbf8c; --purple:#6a4cf0; --pink:#e0379a; --cream:#1c1b22;
+  --accent:#6a4cf0; --accent-fg:#ffffff; --accent-weak:#efebfd;
   --badge-bg:#e7a13a; --badge-fg:#2a1d00;
+  --err-bg:#fce8e6; --err-fg:#8a1c10; --err-line:#d9534f;
   --s1:.25rem; --s2:.5rem; --s3:1rem; --s4:1.5rem; --s5:2.5rem; --radius:.5rem;
+  --mono: ui-monospace, SFMono-Regular, Menlo, "Cascadia Code", monospace;
 }
 @media (prefers-color-scheme: dark) {
-  :root {
+  :root:not([data-theme]) {` + charmDarkVars + `
-    --bg:#15171b; --card:#1e2128; --fg:#e7e7e4; --muted:#9aa0a8; --line:#2d313a;
-    --accent:#76aae6; --accent-fg:#0c0f13; --accent-weak:#222b38;
-    --badge-bg:#caa24a; --badge-fg:#1a1300;
   }
 }
+:root[data-theme="dark"] {` + charmDarkVars + `
+}
 * { box-sizing: border-box; }
 body { font: 15px/1.6 system-ui, -apple-system, sans-serif; margin: 0; color: var(--fg); background: var(--bg); }
 a { color: var(--accent); text-decoration: none; }
 a:hover, a:focus-visible { text-decoration: underline; }
 a:visited { color: var(--accent); }
 header { padding: var(--s3) var(--s4); border-bottom: 1px solid var(--line); background: var(--card); display: flex; align-items: center; justify-content: space-between; gap: var(--s3); }
-.brand { font-weight: 700; font-size: 1.05rem; color: var(--accent); }
+.brand { font-weight: 800; font-size: 1.05rem; letter-spacing: -.01em; color: var(--accent); }
-.nav { display: flex; gap: var(--s3); font-size: .9rem; }
+.nav { display: flex; gap: var(--s3); align-items: center; font-size: .9rem; }
+.theme-toggle { font: inherit; font-size: 1rem; line-height: 1; padding: .3rem .5rem; border: 1px solid var(--line); border-radius: 999px; background: var(--card); color: var(--muted); cursor: pointer; }
+.theme-toggle:hover { border-color: var(--accent); color: var(--accent); }
+.theme-toggle:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
 main { max-width: 60rem; margin: 0 auto; padding: var(--s4) var(--s3); }
 .muted { color: var(--muted); }
 
@@ -603,7 +653,7 @@ main { max-width: 60rem; margin: 0 auto; padding: var(--s4) var(--s3); }
 .filters input:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; border-color: var(--accent); }
 .filter-check { flex-direction: row !important; align-items: center; gap: var(--s2) !important; padding-bottom: .45rem; }
 .filter-check input[type=checkbox] { width: 1rem; height: 1rem; min-width: 0; padding: 0; accent-color: var(--accent); cursor: pointer; }
-.btn { font: inherit; font-weight: 600; padding: .45rem 1rem; border: 1px solid var(--accent); border-radius: var(--radius); background: var(--accent); color: var(--accent-fg); cursor: pointer; }
+.btn { font: inherit; font-weight: 600; padding: .45rem 1.1rem; border: 1px solid var(--accent); border-radius: 999px; background: var(--accent); color: var(--accent-fg); cursor: pointer; }
 /* anchors styled as buttons: the generic a{} / a:visited{} colour rules outrank
    .btn on <a>, painting the label accent-on-accent (invisible). Restore the
    button foreground for anchor buttons, visited included. */
@@ -615,14 +665,19 @@ a.btn, a.btn:visited { color: var(--accent-fg); }
 .cards { list-style: none; margin: 0; padding: 0; display: grid; gap: var(--s3); }
 .card { background: var(--card); border: 1px solid var(--line); border-radius: var(--radius); padding: var(--s3) var(--s4); display: flex; flex-direction: column; gap: var(--s2); }
 .card-title { font-size: 1.1rem; font-weight: 600; line-height: 1.3; }
-.card-meta { color: var(--muted); font-size: .85rem; }
+.card-meta { color: var(--muted); font-size: .8rem; font-family: var(--mono); }
 .card-preview { color: var(--muted); font-size: .9rem; line-height: 1.5; display: -webkit-box; -webkit-line-clamp: 1; line-clamp: 1; -webkit-box-orient: vertical; overflow: hidden; }
 .card-foot { display: flex; gap: var(--s2); align-items: center; flex-wrap: wrap; margin-top: var(--s1); }
+/* Inline-expanded card (ADR-031/032): lifted, with a charm accent edge so the
+   open card reads as the focused one in the feed (sketch B/C). */
+.card-expanded { border-color: var(--accent); border-left: 3px solid var(--mint); box-shadow: 0 6px 24px color-mix(in srgb, var(--accent) 14%, transparent); }
+.card-expanded-head { display: flex; justify-content: space-between; align-items: baseline; gap: var(--s2); }
+.card-collapse { font-size: .8rem; font-family: var(--mono); white-space: nowrap; }
 .chip { display: inline-block; padding: .15rem .55rem; border-radius: 999px; background: var(--accent-weak); color: var(--accent); font-size: .72rem; font-weight: 600; }
 /* passive "retrying later" chip: dim/grey (CharmDim), not the accent — it is a
    status, not an action the user can take. */
 .chip-retry { background: rgba(108, 108, 108, .16); color: #6c6c6c; }
-.pipeline-bar { display: flex; gap: var(--s3); align-items: center; flex-wrap: wrap; margin-bottom: var(--s3); font-size: .8rem; color: var(--muted); }
+.pipeline-bar { display: flex; gap: var(--s3); align-items: center; flex-wrap: wrap; margin-bottom: var(--s3); font-size: .78rem; font-family: var(--mono); color: var(--muted); }
 .pipeline-bar span { display: flex; align-items: center; gap: var(--s1); }
 .pipeline-bar span + span::before { content: "·"; margin-right: var(--s1); }
 .pipeline-note { margin: calc(-1 * var(--s2)) 0 var(--s3); font-size: .8rem; line-height: 1.5; max-width: 40rem; }
@@ -708,10 +763,7 @@ a.btn, a.btn:visited { color: var(--accent-fg); }
 /* flash / notification banner */
 .flash { padding: var(--s2) var(--s3); border-radius: var(--radius); margin-bottom: var(--s4); font-size: .92rem; border: 1px solid var(--line); }
 .flash-success { background: var(--accent-weak); color: var(--accent); border-color: var(--accent); }
-.flash-error { background: #fce8e6; color: #8a1c10; border-color: #d9534f; }
+.flash-error { background: var(--err-bg); color: var(--err-fg); border-color: var(--err-line); }
-@media (prefers-color-scheme: dark) {
-  .flash-error { background: #3a1714; color: #f3b5ae; border-color: #a6362e; }
-}
 
 /* htmx loading feedback */
 .htmx-indicator { opacity: 0; transition: opacity .2s; color: var(--muted); font-size: .8rem; }
@@ -721,12 +773,13 @@ a.btn, a.btn:visited { color: var(--accent-fg); }
 .detail { max-width: 38rem; }
 .detail .back { margin: 0 0 var(--s3); font-size: .85rem; }
 .detail h1 { font-size: 1.7rem; line-height: 1.25; margin: 0 0 var(--s2); }
-.detail .meta { color: var(--muted); font-size: .9rem; margin: 0 0 var(--s2); display: flex; gap: var(--s2); align-items: center; flex-wrap: wrap; }
+.detail .meta { color: var(--muted); font-size: .82rem; font-family: var(--mono); margin: 0 0 var(--s2); display: flex; gap: var(--s2); align-items: center; flex-wrap: wrap; }
 .detail .source { margin: 0 0 var(--s4); font-size: .9rem; }
 .detail .embed { margin: 0 0 var(--s4); aspect-ratio: 16 / 9; border-radius: var(--radius); overflow: hidden; background: #000; border: 1px solid var(--line); }
 .detail .embed iframe { display: block; width: 100%; height: 100%; border: 0; }
 .detail section { margin-top: var(--s4); }
-.detail section h2 { font-size: .78rem; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); border-top: 1px solid var(--line); padding-top: var(--s3); margin: 0 0 var(--s2); }
+.detail section h2 { font-size: .72rem; text-transform: uppercase; letter-spacing: .12em; color: var(--accent); display: flex; align-items: center; gap: var(--s2); margin: var(--s4) 0 var(--s2); }
+.detail section h2::after { content: ""; flex: 1; height: 1px; background: var(--line); }
 .detail .body { white-space: pre-wrap; line-height: 1.7; margin: 0; }
 .detail ul { margin: 0; padding-left: 1.2rem; line-height: 1.6; }
 .detail li { margin-bottom: var(--s1); }
@@ -744,8 +797,7 @@ a.btn, a.btn:visited { color: var(--accent-fg); }
 .chat-a { background: var(--card); border: 1px solid var(--line); }
 .chat-a .body { white-space: pre-wrap; line-height: 1.6; }
 .chat-note { margin: 0; font-size: .82rem; font-style: italic; }
-.chat-error { margin: 0; color: #8a1c10; font-size: .9rem; }
+.chat-error { margin: 0; color: var(--err-fg); font-size: .9rem; }
-@media (prefers-color-scheme: dark) { .chat-error { color: #f3b5ae; } }
 .chat-form { display: flex; flex-direction: column; gap: var(--s2); margin: var(--s2) 0 0; }
 .chat-model { flex-direction: column; display: flex; gap: var(--s1); font-size: .78rem; text-transform: uppercase; letter-spacing: .04em; color: var(--muted); align-items: flex-start; }
 .chat-model select { font: inherit; text-transform: none; letter-spacing: 0; padding: .4rem .55rem; border: 1px solid var(--line); border-radius: var(--radius); background: var(--card); color: var(--fg); }
@@ -795,17 +847,13 @@ a.btn, a.btn:visited { color: var(--accent-fg); }
 .danger-zone h2 { border-top-color: #d9534f; }
 .confirm-delete > summary { display: inline-block; list-style: none; cursor: pointer; font: inherit; font-weight: 600; padding: .45rem 1rem; border: 1px solid #d9534f; border-radius: var(--radius); background: transparent; color: #c0392b; }
 .confirm-delete > summary::-webkit-details-marker { display: none; }
-.confirm-delete > summary:hover { background: #fce8e6; }
+.confirm-delete > summary:hover { background: var(--err-bg); }
 .confirm-delete[open] > summary { margin-bottom: var(--s3); }
-.confirm-body { border: 1px solid #d9534f; border-radius: var(--radius); padding: var(--s3); background: #fce8e6; color: #8a1c10; }
+.confirm-body { border: 1px solid #d9534f; border-radius: var(--radius); padding: var(--s3); background: var(--err-bg); color: var(--err-fg); }
 .btn-danger { font: inherit; font-weight: 600; padding: .45rem 1rem; border: 1px solid #d9534f; border-radius: var(--radius); background: #d9534f; color: #fff; cursor: pointer; }
 .btn-danger:hover { filter: brightness(1.05); }
 .btn-danger:focus-visible { outline: 2px solid #d9534f; outline-offset: 1px; }
-@media (prefers-color-scheme: dark) {
+.confirm-delete > summary { color: var(--err-fg); }
-  .confirm-body { background: #3a1714; color: #f3b5ae; }
-  .confirm-delete > summary { color: #f3b5ae; }
-  .confirm-delete > summary:hover { background: #3a1714; }
-}
 
 /* public landing page (/welcome) — the Charm-box mascot hero plus the sign-in CTA */
 .welcome { text-align: center; padding: var(--s5) var(--s3); display: flex; flex-direction: column; align-items: center; gap: var(--s4); }

internal/web/views.templ

@@ -17,13 +17,14 @@ templ Layout(title string) {
 			<meta charset="utf-8"/>
 			<meta name="viewport" content="width=device-width, initial-scale=1"/>
 			<title>{ title }</title>
+			@templ.Raw(themeScriptTag)
 			<script src="/static/htmx.min.js" defer></script>
 			@templ.Raw(styleTag)
 		</head>
 		<body>
 			<header>
 				<a href="/" class="brand">Tapir</a>
-				<nav class="nav"><a href="/account">Account</a><a href="/auth/logout">Log out</a></nav>
+				<nav class="nav"><a href="/account">Account</a><a href="/auth/logout">Log out</a>@templ.Raw(themeToggleButton)</nav>
 			</header>
 			<main>
 				{ children... }
@@ -42,12 +43,14 @@ templ PublicLayout(title string) {
 			<meta charset="utf-8"/>
 			<meta name="viewport" content="width=device-width, initial-scale=1"/>
 			<title>{ title }</title>
+			@templ.Raw(themeScriptTag)
 			<script src="/static/htmx.min.js" defer></script>
 			@templ.Raw(styleTag)
 		</head>
 		<body>
 			<header>
 				<a href="/" class="brand">Tapir</a>
+				<nav class="nav">@templ.Raw(themeToggleButton)</nav>
 			</header>
 			<main>
 				{ children... }
@@ -264,7 +267,16 @@ templ summaryList(b listBuckets, hasConnected bool, autoSummarize bool) {
 templ VideoCard(r store.SummaryRow) {
 	<li class={ "card", templ.KV("card-pending", !r.Summarized) } id={ "video-" + r.VideoID }>
 		if r.Summarized {
-			<div class="card-title"><a href={ videoURL(r.VideoID) }>{ displayTitle(r) }</a></div>
+			// Expand the full summary + Q&A in place (ADR-031); href is the no-JS
+			// fallback to the detail page, so nothing becomes JS-only.
+			<div class="card-title">
+				<a
+					href={ videoURL(r.VideoID) }
+					hx-get={ string(expandURL(r.VideoID)) }
+					hx-target={ "#video-" + r.VideoID }
+					hx-swap="outerHTML"
+				>{ displayTitle(r) }</a>
+			</div>
 		} else {
 			<div class="card-title">{ displayTitle(r) }</div>
 		}
@@ -327,6 +339,32 @@ templ VideoCard(r store.SummaryRow) {
 	</li>
 }
 
+// expandedCard is a summarized list card opened IN PLACE (ADR-031): the full
+// summary body + the deeper-dive chat dock, with a collapse control back to the
+// compact card. It shares the <li id> with VideoCard so HTMX swaps it outerHTML,
+// and reuses summaryBody + chatReveal so it never drifts from the detail page.
+// Note: chatReveal uses a single #chat-section id, so this assumes one card open
+// at a time; a per-video chat id is a follow-up if simultaneous expansion is wanted.
+templ expandedCard(r store.SummaryRow, chatEnabled bool) {
+	<li class="card card-expanded" id={ "video-" + r.VideoID }>
+		<div class="card-expanded-head">
+			<span class="card-title">{ displayTitle(r) }</span>
+			<a
+				href={ videoURL(r.VideoID) }
+				hx-get={ string(cardURL(r.VideoID)) }
+				hx-target={ "#video-" + r.VideoID }
+				hx-swap="outerHTML"
+				class="card-collapse"
+				title="Collapse"
+			>collapse ↑</a>
+		</div>
+		@summaryBody(r)
+		if chatEnabled {
+			@chatReveal(r.VideoID)
+		}
+	</li>
+}
+
 // TapirSpinner is the summarizing animation: a Charmbracelet-style TUI panel —
 // three richly coloured ASCII tapir frames (inline span colours, snout wiggling
 // ∩→∪→~) cross-faded by CSS, plus a lipgloss-style progress bar whose mint fill

internal/web/visual_theme_test.go

@@ -0,0 +1,66 @@
+package web_test
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+)
+
+// page renders any GET path's full HTML (helper for theme/structure assertions).
+func page(t *testing.T, app interface {
+	Router() http.Handler
+}, path string) string {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	app.Router().ServeHTTP(rec, httptest.NewRequest(http.MethodGet, path, nil))
+	return rec.Body.String()
+}
+
+// TestThemeHasLightAndDarkPalettes: one layout, two palettes via CSS variables —
+// a root light palette and a data-theme="dark" dark palette (ADR-032).
+func TestThemeHasLightAndDarkPalettes(t *testing.T) {
+	app := newApp(t)
+	resetDB(t, rawPool(t))
+	html := page(t, app, "/welcome") // public, no DB needed
+	require.Contains(t, html, ":root", "light palette on the root")
+	require.Contains(t, html, `[data-theme="dark"]`, "explicit dark palette override for the toggle")
+}
+
+// TestThemeFollowsOSPreference: with no stored choice, the OS preference applies
+// the dark palette automatically.
+func TestThemeFollowsOSPreference(t *testing.T) {
+	app := newApp(t)
+	html := page(t, app, "/welcome")
+	require.Contains(t, html, "prefers-color-scheme: dark", "OS-preference dark default")
+}
+
+// TestThemeTogglePersists: every page carries a theme toggle control and a small
+// script that flips data-theme and persists the choice.
+func TestThemeTogglePersists(t *testing.T) {
+	app := newApp(t)
+	html := page(t, app, "/welcome")
+	require.Contains(t, html, "theme-toggle", "a theme toggle control")
+	require.Contains(t, html, "localStorage", "the choice is persisted")
+	require.Contains(t, html, "data-theme", "the toggle flips data-theme")
+}
+
+// TestExpandedCardEmbedsVideo: expanding a summarized card with a valid provider id
+// includes the embedded video player (ADR-031/032).
+func TestExpandedCardEmbedsVideo(t *testing.T) {
+	ctx := context.Background()
+	app := newApp(t)
+	p := rawPool(t)
+	resetDB(t, p)
+	require.NoError(t, deliver(ctx, app, videoX, "summary text"))
+	seedVideo(t, p, videoX, "X Title", "https://x", time.Time{})
+
+	html := body(t, do(t, app, httptest.NewRequest(http.MethodGet, "/v/"+videoX+"/expand", nil)))
+	require.Contains(t, html, "<iframe", "expanded card embeds a player")
+	require.True(t, strings.Contains(html, "youtube.com/embed") || strings.Contains(html, "youtube-nocookie.com/embed"),
+		"the embed is the YouTube player")
+}

internal/web/welcome_test.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/stretchr/testify/require"
 
-	"gitea.d-ma.be/mathias/tapir/internal/web"
+	"git.d-ma.be/mathias/tapir/internal/web"
 )
 
 // fakeAuth is a configurable web.Auth for the landing-page tests: it reports a

test/acceptance/scenario_coverage_test.go

@@ -25,6 +25,30 @@ import (
 // fails if a scenario is unmapped, a mapped test is missing, or an entry no
 // longer matches a real non-pending scenario.
 var scenarioCoverage = map[string]string{
+	// inline_expand.feature (ADR-031, #16)
+	"A summarized card expands to the full summary in place":      "TestExpandReturnsSummaryBodyFragment",
+	"An expanded card collapses back to the compact card":         "TestCollapseReturnsCompactCard",
+	"The expanded card offers the Q&A dock":                       "TestExpandedCardOffersChatDock",
+	"Only a summarized card offers expand":                        "TestCompactCardExpandOnlyWhenSummarized",
+	"With JS off the card still reaches the full summary":         "TestCompactCardHasNoJSDetailFallback",
+	"The detail page and the expanded card show the same summary": "TestDetailAndExpandShareSummaryBody",
+
+	// visual_theme.feature (ADR-032, #17)
+	"Light and dark themes share one layout via CSS variables":    "TestThemeHasLightAndDarkPalettes",
+	"Without a stored choice the theme follows the OS preference": "TestThemeFollowsOSPreference",
+	"A persisted toggle switches light and dark":                  "TestThemeTogglePersists",
+	"The expanded card embeds the video player":                   "TestExpandedCardEmbedsVideo",
+
+	// observability.feature (ADR-030, #15)
+	"Summarization latency is recorded per endpoint":            "TestSummarizerRecordsMetric",
+	"A failing summarizer endpoint records its failure outcome": "TestObserveSummarizeRecordsFailureOutcomes",
+	"Caption fetch latency is recorded by outcome":              "TestObserveCaptionFetchByOutcome",
+	"LLM token usage is recorded from the completion":           "TestClient_UsageHookRecordsTokens",
+	"Q&A answer latency is recorded":                            "TestChatAnswerLatencyRecorded",
+	"HTTP requests are counted by route, method, and status":    "TestHTTPMiddlewareRecordsByRoutePattern",
+	"A successful login is counted":                             "TestLoginCounted",
+	"The metrics endpoint is not on the public app port":        "TestMetricsNotOnPublicMux",
+
 	// ai_routing.feature
 	"Local AI produces the summary":                                     "TestSummarize_LocalSucceeds",
 	"Local AI fails and the user has a BYO provider configured":         "TestSummarize_FallsBackToBYO",

test/acceptance/summarize_new_video_test.go

@@ -12,8 +12,8 @@ import (
 	"testing"
 	"time"
 
-	"gitea.d-ma.be/mathias/tapir/internal/domain"
+	"git.d-ma.be/mathias/tapir/internal/domain"
-	"gitea.d-ma.be/mathias/tapir/internal/usecase"
+	"git.d-ma.be/mathias/tapir/internal/usecase"
 )
 
 // --- fake adapters ---------------------------------------------------------