diff --git a/docs/superpowers/plans/2026-04-23-block2-security-plan.md b/docs/superpowers/plans/2026-04-23-block2-security-plan.md
new file mode 100644
index 0000000..f1032bb
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-23-block2-security-plan.md
@@ -0,0 +1,1110 @@
+# Block 2 — Security & Auth Hardening Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Harden the docsiq HTTP boundary and config loader — reject malformed config early, scrub secrets from debug logs, enforce browser-side CSP + baseline security headers, and thread the existing request ID into slog for operator-friendly log correlation.
+
+**Architecture:** Five independent server-side changes, four of them behind an existing middleware chain (`loggingMiddleware → recoveryMiddleware → bearerAuthMiddleware → projectMiddleware → mux`). Tasks 1–2 touch `internal/config`; Tasks 3–4 add a single new `securityHeadersMiddleware` placed as the outermost wrapper so every response (including 404s and errors) carries the headers; Task 5 adds a small `ContextLogger(ctx)` helper next to the existing `RequestIDFromContext` and updates a curated set of handler log sites.
+
+**Tech Stack:** Go 1.22+ standard `net/http`, `log/slog`, `reflect`, Viper + mapstructure. No new third-party dependencies.
+
+**Scope check:** Five items, one subsystem (HTTP + config). No sub-plan decomposition needed.
+
+**Self-contained:** Block 1 (PR #60) is a soft prerequisite only because Block 2 builds on the same middleware chain. None of Block 2 touches workq, the session cookie path, or the entity-fetch scoping from Block 1.
+
+---
+
+## File Structure
+
+### Create
+- `internal/api/security_headers.go` — `securityHeadersMiddleware(cfg *config.Config) func(http.Handler) http.Handler`; returns a handler that sets CSP + baseline headers on every response.
+- `internal/api/security_headers_test.go` — header-presence assertions under `GET /health`, `OPTIONS /api/ping`, and authenticated `GET /api/stats`.
+- `internal/api/log_context.go` — `ContextLogger(ctx context.Context) *slog.Logger` helper that enriches `slog.Default()` with `req_id` when the context carries one.
+- `internal/api/log_context_test.go` — captures slog output via a `slog.NewTextHandler(&buf, nil)` default, asserts `req_id=xxxx` is present on emitted records.
+- `internal/config/redact.go` — `(c *Config) Redact() *Config`; deep-copies and zeroes every string field tagged `secret:"true"` via `reflect`.
+- `internal/config/redact_test.go` — round-trip test: load a config with known secrets, serialize the redacted copy to YAML, assert no secret substring appears.
+
+### Modify
+- `internal/config/config.go:48-128` — add `secret:"true"` struct tags on API-key fields in `ServerConfig`, `OpenAIConfig`, `AzureConfig`, `AzureServiceConfig`.
+- `internal/config/config.go:256` — swap `viper.Unmarshal(&cfg)` for `viper.UnmarshalExact(&cfg)`; add call to `validateLLM(&cfg)` before returning.
+- `internal/config/config.go` (new function at end) — `validateLLM(cfg *Config) error` with provider switch.
+- `internal/config/config.go:145-152` — add `HSTSEnabled bool `mapstructure:"hsts_enabled"`` to `ServerConfig` (no `secret` tag).
+- `internal/config/config.go:238-241` — add `viper.BindEnv("server.hsts_enabled")`.
+- `internal/config/config_test.go` (existing file; append) — tests for `validateLLM` + `UnmarshalExact` rejection of unknown keys.
+- `internal/api/router.go:167-170` — wrap the existing middleware chain with `securityHeadersMiddleware(cfg)` as the new outermost layer.
+- `internal/api/handlers.go` (representative sites) — replace 3–5 `slog.Warn` / `slog.Error` calls in request handlers with `ContextLogger(r.Context()).Warn(...)` equivalents.
+
+---
+
+## Task 1: Strict config unmarshal + LLM consistency (2.4)
+
+**Files:**
+- Modify: `internal/config/config.go:256` (Unmarshal → UnmarshalExact)
+- Modify: `internal/config/config.go` — append `validateLLM(cfg *Config) error`
+- Modify: `internal/config/config_test.go` — append new tests
+
+- [ ] **Step 1: Read current state**
+
+Confirm the current load pattern:
+
+```bash
+sed -n '250,265p' internal/config/config.go
+grep -n 'UnmarshalExact\|Unmarshal' internal/config/config.go
+```
+
+Expected: one existing `viper.Unmarshal(&cfg)` call at line 256 (give or take 3 lines if the file has drifted), no existing `UnmarshalExact`.
+
+- [ ] **Step 2: Write the failing tests (TDD red)**
+
+Append to `internal/config/config_test.go`:
+
+```go
+func TestLoad_RejectsUnknownKey(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	f := filepath.Join(dir, "config.yaml")
+	must := func(err error) { t.Helper(); if err != nil { t.Fatal(err) } }
+	must(os.WriteFile(f, []byte("server:\n  api_key: s3cret\n  unknown_key: oops\n"), 0o600))
+
+	_, err := Load(f)
+	if err == nil {
+		t.Fatal("Load should reject unknown_key")
+	}
+	if !strings.Contains(err.Error(), "unknown_key") {
+		t.Fatalf("error should name the offending key; got %q", err)
+	}
+}
+
+func TestLoad_ValidatesLLMProvider(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name    string
+		yaml    string
+		wantErr string
+	}{
+		{
+			name:    "unknown_provider",
+			yaml:    "llm:\n  provider: not_a_real_one\n",
+			wantErr: "provider",
+		},
+		{
+			name:    "azure_missing_endpoint",
+			yaml:    "llm:\n  provider: azure\n  azure:\n    api_key: k\n",
+			wantErr: "azure",
+		},
+		{
+			name:    "openai_missing_api_key",
+			yaml:    "llm:\n  provider: openai\n  openai:\n    base_url: https://api.openai.com/v1\n",
+			wantErr: "openai",
+		},
+		{
+			name:    "ollama_missing_base_url",
+			yaml:    "llm:\n  provider: ollama\n",
+			wantErr: "ollama",
+		},
+	}
+
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			dir := t.TempDir()
+			f := filepath.Join(dir, "config.yaml")
+			must := func(err error) { t.Helper(); if err != nil { t.Fatal(err) } }
+			must(os.WriteFile(f, []byte("server:\n  api_key: s3cret\n"+tc.yaml), 0o600))
+
+			_, err := Load(f)
+			if err == nil {
+				t.Fatalf("Load should have rejected %s", tc.name)
+			}
+			if !strings.Contains(strings.ToLower(err.Error()), tc.wantErr) {
+				t.Fatalf("error should mention %q; got %q", tc.wantErr, err)
+			}
+		})
+	}
+}
+
+func TestLoad_AcceptsValidProviders(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name string
+		yaml string
+	}{
+		{"azure", "llm:\n  provider: azure\n  azure:\n    endpoint: https://x.openai.azure.com\n    api_key: k\n    api_version: 2024-02-15-preview\n    chat:\n      model: gpt-4o\n    embed:\n      model: text-embedding-3-small\n"},
+		{"openai", "llm:\n  provider: openai\n  openai:\n    api_key: k\n    chat_model: gpt-4o\n    embed_model: text-embedding-3-small\n"},
+		{"ollama", "llm:\n  provider: ollama\n  ollama:\n    base_url: http://127.0.0.1:11434\n    chat_model: llama3\n    embed_model: nomic-embed-text\n"},
+	}
+
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			dir := t.TempDir()
+			f := filepath.Join(dir, "config.yaml")
+			must := func(err error) { t.Helper(); if err != nil { t.Fatal(err) } }
+			must(os.WriteFile(f, []byte("server:\n  api_key: s3cret\n"+tc.yaml), 0o600))
+
+			cfg, err := Load(f)
+			if err != nil {
+				t.Fatalf("valid %s config should load: %v", tc.name, err)
+			}
+			if cfg.LLM.Provider != tc.name {
+				t.Fatalf("provider not round-tripped: got %q", cfg.LLM.Provider)
+			}
+		})
+	}
+}
+```
+
+Ensure the test file's import block includes `"os"`, `"path/filepath"`, `"strings"`, `"testing"`. Add any missing.
+
+- [ ] **Step 3: Run the tests (red)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/config/ -run 'TestLoad_RejectsUnknownKey|TestLoad_ValidatesLLMProvider|TestLoad_AcceptsValidProviders' -v
+```
+
+Expected: `TestLoad_RejectsUnknownKey` FAILs (viper.Unmarshal accepts unknown keys silently). `TestLoad_ValidatesLLMProvider` subtests FAIL (no validator exists yet). Valid-provider tests should PASS already.
+
+- [ ] **Step 4: Swap to UnmarshalExact**
+
+Edit `internal/config/config.go` around line 256:
+
+```go
+// OLD
+if err := v.Unmarshal(&cfg); err != nil {
+    return nil, fmt.Errorf("unmarshal config: %w", err)
+}
+
+// NEW
+if err := v.UnmarshalExact(&cfg); err != nil {
+    return nil, fmt.Errorf("unmarshal config: %w", err)
+}
+```
+
+- [ ] **Step 5: Add `validateLLM`**
+
+Append to the end of `internal/config/config.go`:
+
+```go
+// validateLLM enforces that the selected LLM provider has the minimum
+// fields needed to make any request. Called from Load after
+// UnmarshalExact so the "unknown key" and "missing required field"
+// errors land in a consistent spot. Error messages name the offending
+// provider so an operator can grep logs → yaml key immediately.
+func validateLLM(cfg *Config) error {
+	switch cfg.LLM.Provider {
+	case "":
+		// Provider unset is allowed — search paths that don't need an LLM
+		// (e.g. pure-FTS search) still work. Fail only if someone later
+		// tries to construct an LLM client with an empty provider string.
+		return nil
+	case "azure":
+		a := cfg.LLM.Azure
+		chatOK := a.Chat.Endpoint != "" || a.Endpoint != ""
+		chatOK = chatOK && (a.Chat.APIKey != "" || a.APIKey != "")
+		embedOK := a.Embed.Endpoint != "" || a.Endpoint != ""
+		embedOK = embedOK && (a.Embed.APIKey != "" || a.APIKey != "")
+		if !chatOK && !embedOK {
+			return fmt.Errorf("llm.azure: neither chat nor embed has a resolvable endpoint+api_key (set shared llm.azure.{endpoint,api_key} or per-service overrides)")
+		}
+		if a.APIVersion == "" && a.Chat.APIVersion == "" && a.Embed.APIVersion == "" {
+			return fmt.Errorf("llm.azure.api_version: required (shared or per-service)")
+		}
+	case "openai":
+		if cfg.LLM.OpenAI.APIKey == "" {
+			return fmt.Errorf("llm.openai.api_key: required when llm.provider=openai")
+		}
+	case "ollama":
+		if cfg.LLM.Ollama.BaseURL == "" {
+			return fmt.Errorf("llm.ollama.base_url: required when llm.provider=ollama")
+		}
+	default:
+		return fmt.Errorf("llm.provider: unknown value %q (valid: azure, openai, ollama)", cfg.LLM.Provider)
+	}
+	return nil
+}
+```
+
+Now wire it into `Load`. Inside `Load`, after the `UnmarshalExact` call and before the final `return &cfg, nil`, add:
+
+```go
+if err := validateLLM(&cfg); err != nil {
+    return nil, fmt.Errorf("config validation: %w", err)
+}
+```
+
+- [ ] **Step 6: Run tests (green)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/config/ -v
+```
+
+Expected: all new tests PASS, existing config tests still PASS.
+
+If `TestLoad_RejectsUnknownKey` still fails: viper's `UnmarshalExact` may not catch nested unknown keys in all versions. Verify the error message content. If it rejects but doesn't name the offending key, the test's `strings.Contains(err.Error(), "unknown_key")` assertion needs to match what viper actually reports — inspect the error and adjust the substring.
+
+- [ ] **Step 7: Run full Go suite**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s ./...
+```
+
+Expected: all pass.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add internal/config/config.go internal/config/config_test.go
+git commit -m "$(cat <<'EOF'
+feat(config): reject unknown keys and invalid LLM provider configs
+
+- Load now uses viper.UnmarshalExact, surfacing typos and stale keys
+  at startup instead of at first-use.
+- validateLLM enforces per-provider minimums (azure endpoint+api_key
+  and api_version; openai api_key; ollama base_url). Error messages
+  name the offending yaml key so an operator can grep → fix in one
+  hop.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 2: `Config.Redact()` + audit logged config (2.3)
+
+**Files:**
+- Create: `internal/config/redact.go`
+- Create: `internal/config/redact_test.go`
+- Modify: `internal/config/config.go` — add `secret:"true"` tags on API-key fields
+- Modify: `internal/config/config_test.go` — minor imports if needed (no new tests in this file)
+- Modify: zero-to-three call sites in `internal/config` / `internal/llm` / `internal/api` that log config (audit step; see Step 7)
+
+- [ ] **Step 1: Tag the secret fields**
+
+Edit `internal/config/config.go`. Add `secret:"true"` to the following fields (keep existing `mapstructure` tags):
+
+- `ServerConfig.APIKey`:
+  ```go
+  APIKey string `mapstructure:"api_key" secret:"true"`
+  ```
+- `OpenAIConfig.APIKey`:
+  ```go
+  APIKey string `mapstructure:"api_key" secret:"true"`
+  ```
+- `AzureConfig.APIKey`:
+  ```go
+  APIKey string `mapstructure:"api_key" secret:"true"`
+  ```
+- `AzureServiceConfig.APIKey` (used by both `Chat` and `Embed`):
+  ```go
+  APIKey string `mapstructure:"api_key" secret:"true"`
+  ```
+
+- [ ] **Step 2: Write the failing test**
+
+Create `internal/config/redact_test.go`:
+
+```go
+package config
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestConfig_Redact_ZeroesSecrets(t *testing.T) {
+	t.Parallel()
+	in := &Config{}
+	in.Server.APIKey = "server-secret"
+	in.LLM.Provider = "azure"
+	in.LLM.Azure.APIKey = "azure-shared-secret"
+	in.LLM.Azure.Chat.APIKey = "azure-chat-secret"
+	in.LLM.Azure.Embed.APIKey = "azure-embed-secret"
+	in.LLM.OpenAI.APIKey = "openai-secret"
+
+	redacted := in.Redact()
+
+	b, err := json.Marshal(redacted)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, s := range []string{
+		"server-secret",
+		"azure-shared-secret",
+		"azure-chat-secret",
+		"azure-embed-secret",
+		"openai-secret",
+	} {
+		if strings.Contains(string(b), s) {
+			t.Fatalf("redacted output still contains %q:\n%s", s, b)
+		}
+	}
+
+	// Original must be untouched.
+	if in.Server.APIKey != "server-secret" {
+		t.Fatalf("Redact mutated the original Config")
+	}
+}
+
+func TestConfig_Redact_PreservesNonSecretFields(t *testing.T) {
+	t.Parallel()
+	in := &Config{}
+	in.Server.Host = "127.0.0.1"
+	in.Server.Port = 8080
+	in.Server.APIKey = "s3cret"
+	in.LLM.Provider = "openai"
+	in.LLM.OpenAI.BaseURL = "https://api.openai.com/v1"
+	in.LLM.OpenAI.ChatModel = "gpt-4o"
+
+	r := in.Redact()
+	if r.Server.Host != "127.0.0.1" {
+		t.Errorf("Host lost")
+	}
+	if r.Server.Port != 8080 {
+		t.Errorf("Port lost")
+	}
+	if r.LLM.Provider != "openai" {
+		t.Errorf("Provider lost")
+	}
+	if r.LLM.OpenAI.BaseURL != "https://api.openai.com/v1" {
+		t.Errorf("BaseURL lost")
+	}
+	if r.LLM.OpenAI.ChatModel != "gpt-4o" {
+		t.Errorf("ChatModel lost")
+	}
+	if r.Server.APIKey != "" {
+		t.Errorf("Server.APIKey should be zeroed; got %q", r.Server.APIKey)
+	}
+}
+```
+
+- [ ] **Step 3: Run tests (red)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/config/ -run TestConfig_Redact -v
+```
+
+Expected: FAIL — `*Config has no method Redact`.
+
+- [ ] **Step 4: Implement `Redact`**
+
+Create `internal/config/redact.go`:
+
+```go
+package config
+
+import "reflect"
+
+// Redact returns a deep copy of c with every string field tagged
+// secret:"true" zeroed. The original c is not mutated. Safe for logging
+// and for serializing config for introspection endpoints.
+//
+// Nested structs are walked recursively. Slices, maps, and pointers to
+// structs are supported, though config.Config uses only direct struct
+// nesting today — the broader coverage is cheap insurance.
+func (c *Config) Redact() *Config {
+	if c == nil {
+		return nil
+	}
+	dup := *c
+	zeroSecrets(reflect.ValueOf(&dup).Elem())
+	return &dup
+}
+
+func zeroSecrets(v reflect.Value) {
+	switch v.Kind() {
+	case reflect.Struct:
+		for i := 0; i < v.NumField(); i++ {
+			f := v.Field(i)
+			tag := v.Type().Field(i).Tag.Get("secret")
+			if tag == "true" && f.Kind() == reflect.String && f.CanSet() {
+				f.SetString("")
+				continue
+			}
+			zeroSecrets(f)
+		}
+	case reflect.Ptr, reflect.Interface:
+		if !v.IsNil() {
+			zeroSecrets(v.Elem())
+		}
+	case reflect.Slice, reflect.Array:
+		for i := 0; i < v.Len(); i++ {
+			zeroSecrets(v.Index(i))
+		}
+	case reflect.Map:
+		for _, k := range v.MapKeys() {
+			// Maps in Go reflect are not addressable; copy out, zero, put back.
+			elem := reflect.New(v.Type().Elem()).Elem()
+			elem.Set(v.MapIndex(k))
+			zeroSecrets(elem)
+			v.SetMapIndex(k, elem)
+		}
+	}
+}
+```
+
+- [ ] **Step 5: Run tests (green)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/config/ -run TestConfig_Redact -v
+```
+
+Expected: both tests PASS.
+
+- [ ] **Step 6: Audit — find existing config log sites**
+
+```
+grep -rn 'slog\.\(Debug\|Info\|DebugContext\|InfoContext\).*cfg\b' internal/ || true
+grep -rn 'slog\.\(Debug\|Info\|DebugContext\|InfoContext\).*config\b' internal/ || true
+grep -rn 'fmt\.Printf.*cfg\.' internal/ || true
+grep -rn 'fmt\.Println.*cfg\.' internal/ || true
+```
+
+For each hit that logs a `*Config` value OR the full `cfg` struct:
+- Replace `slog.Info("loaded config", "cfg", cfg)` → `slog.Info("loaded config", "cfg", cfg.Redact())`
+- Replace `slog.Debug("config", "value", cfg)` → `slog.Debug("config", "value", cfg.Redact())`
+
+If a site logs only specific non-secret fields (e.g., `slog.Info("host", "host", cfg.Server.Host)`), leave it alone. Only change sites that log the struct as a whole.
+
+If NO call sites are found, record that finding in the commit message and move on — the helper is still valuable as an available tool for future code.
+
+- [ ] **Step 7: Re-run full config + full Go suite**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/config/... -v
+CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s ./...
+```
+
+Expected: all pass. The `secret:"true"` tag addition is purely additive and should not affect any existing behavior.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add internal/config/config.go internal/config/redact.go internal/config/redact_test.go
+# Plus any audited log-site edits from Step 6:
+# git add internal/config/<...>.go internal/api/<...>.go internal/llm/<...>.go
+git commit -m "$(cat <<'EOF'
+feat(config): redact helper zeroes fields tagged secret:"true"
+
+Config.Redact() returns a deep copy with api_key fields cleared. Uses
+the new secret:"true" struct tag so future additions opt in simply by
+tagging the field. Audited existing log sites that printed the full
+Config; piped them through Redact() so debug logs no longer leak
+keys.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 3: Content-Security-Policy middleware (2.1)
+
+**Files:**
+- Create: `internal/api/security_headers.go`
+- Create: `internal/api/security_headers_test.go`
+- Modify: `internal/api/router.go:167-170` — add the wrapper
+
+- [ ] **Step 1: Write the failing test**
+
+Create `internal/api/security_headers_test.go`:
+
+```go
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/RandomCodeSpace/docsiq/internal/config"
+)
+
+func TestSecurityHeaders_CSPOnEveryResponse(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+	cfg := &config.Config{}
+	h := securityHeadersMiddleware(cfg)(next)
+
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, req)
+
+	csp := rr.Header().Get("Content-Security-Policy")
+	if csp == "" {
+		t.Fatal("CSP header missing")
+	}
+	for _, want := range []string{
+		"default-src 'self'",
+		"script-src 'self' 'wasm-unsafe-eval'",
+		"style-src 'self' 'unsafe-inline'",
+		"connect-src 'self'",
+		"img-src 'self' data:",
+		"font-src 'self'",
+		"frame-ancestors 'none'",
+		"base-uri 'self'",
+	} {
+		if !strings.Contains(csp, want) {
+			t.Errorf("CSP missing directive %q: got %q", want, csp)
+		}
+	}
+}
+
+func TestSecurityHeaders_SkipsOPTIONS(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusNoContent)
+	})
+	cfg := &config.Config{}
+	h := securityHeadersMiddleware(cfg)(next)
+
+	req := httptest.NewRequest(http.MethodOptions, "/api/ping", nil)
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, req)
+
+	if rr.Header().Get("Content-Security-Policy") != "" {
+		t.Errorf("CSP should not be set on OPTIONS; got %q", rr.Header().Get("Content-Security-Policy"))
+	}
+	if rr.Code != http.StatusNoContent {
+		t.Errorf("OPTIONS should pass through; got status %d", rr.Code)
+	}
+}
+
+func TestSecurityHeaders_PreservesExistingHeaders(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("X-Custom", "xyz")
+		w.WriteHeader(http.StatusOK)
+	})
+	cfg := &config.Config{}
+	h := securityHeadersMiddleware(cfg)(next)
+
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, req)
+
+	if rr.Header().Get("X-Custom") != "xyz" {
+		t.Errorf("downstream header clobbered")
+	}
+}
+```
+
+- [ ] **Step 2: Run tests (red)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestSecurityHeaders -v
+```
+
+Expected: FAIL — `undefined: securityHeadersMiddleware`.
+
+- [ ] **Step 3: Implement the middleware (CSP only for now)**
+
+Create `internal/api/security_headers.go`:
+
+```go
+package api
+
+import (
+	"net/http"
+
+	"github.com/RandomCodeSpace/docsiq/internal/config"
+)
+
+// contentSecurityPolicy is deliberately strict for the air-gapped
+// deployment posture: no CDN origins, no inline scripts, WASM allowed
+// (shiki uses it for syntax highlighting), no iframing. Inline styles
+// are permitted because Tailwind + shadcn/ui emit them.
+const contentSecurityPolicy = "default-src 'self'; " +
+	"script-src 'self' 'wasm-unsafe-eval'; " +
+	"style-src 'self' 'unsafe-inline'; " +
+	"connect-src 'self'; " +
+	"img-src 'self' data:; " +
+	"font-src 'self'; " +
+	"frame-ancestors 'none'; " +
+	"base-uri 'self'"
+
+// securityHeadersMiddleware sets browser-side hardening headers on every
+// response that actually carries a body (i.e. non-OPTIONS). Task 4
+// extends this middleware with baseline security headers
+// (nosniff, Referrer-Policy, Permissions-Policy, HSTS). Keeping both
+// sets in one middleware keeps response-header side-effects colocated.
+func securityHeadersMiddleware(_ *config.Config) func(http.Handler) http.Handler {
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Method == http.MethodOptions {
+				next.ServeHTTP(w, r)
+				return
+			}
+			w.Header().Set("Content-Security-Policy", contentSecurityPolicy)
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+```
+
+- [ ] **Step 4: Run tests (green)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestSecurityHeaders -v
+```
+
+Expected: all three PASS.
+
+- [ ] **Step 5: Wire into router**
+
+Edit `internal/api/router.go` around line 167. Current:
+
+```go
+return loggingMiddleware(
+    recoveryMiddleware(
+        bearerAuthMiddleware(cfg.Server.APIKey,
+            projectMiddleware(cfg, registry, mux))))
+```
+
+Change to:
+
+```go
+return securityHeadersMiddleware(cfg)(
+    loggingMiddleware(
+        recoveryMiddleware(
+            bearerAuthMiddleware(cfg.Server.APIKey,
+                projectMiddleware(cfg, registry, mux)))))
+```
+
+Rationale: security headers must be applied to every response, including panic recoveries and 401s. Wrapping outside `loggingMiddleware` also means the logged response status already reflects the final body; no functional reorder.
+
+- [ ] **Step 6: Run full Go suite + new middleware tests**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -v
+CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s ./...
+```
+
+Expected: all pass. Any existing test that asserts on header ABSENCE (e.g. auth_test.go assertions) must still pass because we only add headers.
+
+- [ ] **Step 7: Run UI Playwright smokes to check the SPA still loads under CSP**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test smoke.spec.ts --reporter=list --workers=1
+```
+
+Expected: 5/5 pass. If any smoke fails with a browser console error about CSP violation, collect the exact violation from the Playwright trace; most likely an inline `<script>` or `<style>` the bundler generates. The CSP directive includes `'unsafe-inline'` for styles but NOT for scripts — Vite's production build should not emit inline scripts (all are hashed-module), but verify.
+
+If the smoke fails due to a CSP violation from `style-src`, the test is passing under a browser that didn't previously enforce CSP; investigate the specific violation line from the Playwright `--reporter=list` output. If it's a Vite dev-server artifact that leaked into the production build, adjust the bundler; do not widen CSP.
+
+If Playwright is not installed in this environment, skip Step 7 and note it in the commit message. The CI Playwright job will catch any regression.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add internal/api/security_headers.go internal/api/security_headers_test.go internal/api/router.go
+git commit -m "$(cat <<'EOF'
+feat(api): Content-Security-Policy middleware
+
+Sets a strict CSP matching the air-gapped deployment posture on every
+non-OPTIONS response: default-src 'self' everywhere; inline scripts
+banned; WASM allowed for shiki; inline styles allowed for Tailwind/
+shadcn; frame-ancestors 'none' to block clickjacking. Wired as the
+outermost router wrapper so 401/500/404 responses also carry the
+header.
+
+Task 4 will extend the same middleware with baseline security headers
+(nosniff, Referrer-Policy, Permissions-Policy, HSTS).
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 4: Baseline security headers + conditional HSTS (2.2)
+
+**Files:**
+- Modify: `internal/api/security_headers.go` — extend the middleware to set nosniff, Referrer-Policy, Permissions-Policy, HSTS conditional
+- Modify: `internal/api/security_headers_test.go` — add assertions
+- Modify: `internal/config/config.go` — add `HSTSEnabled bool` to `ServerConfig`
+- Modify: `internal/config/config.go` — add `viper.BindEnv("server.hsts_enabled")` next to existing server env bindings
+
+- [ ] **Step 1: Add HSTSEnabled config field**
+
+Edit `internal/config/config.go` — extend the `ServerConfig` struct (currently ends around line 152):
+
+```go
+type ServerConfig struct {
+    Host           string `mapstructure:"host"`
+    Port           int    `mapstructure:"port"`
+    APIKey         string `mapstructure:"api_key" secret:"true"`  // already tagged in Task 2
+    MaxUploadBytes int64  `mapstructure:"max_upload_bytes"`
+    WorkqWorkers   int    `mapstructure:"workq_workers"`
+    WorkqDepth     int    `mapstructure:"workq_depth"`
+    HSTSEnabled    bool   `mapstructure:"hsts_enabled"`
+}
+```
+
+And bind the env var near the existing server BindEnv calls (around lines 238-241):
+
+```go
+_ = v.BindEnv("server.hsts_enabled")
+```
+
+(Use whichever prefix + delimiter pattern the neighbors use — verify with a quick `sed -n '235,245p' internal/config/config.go`.)
+
+- [ ] **Step 2: Write the failing tests**
+
+Append to `internal/api/security_headers_test.go`:
+
+```go
+func TestSecurityHeaders_BaselineHeaders(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+	cfg := &config.Config{}
+	h := securityHeadersMiddleware(cfg)(next)
+
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, req)
+
+	if got := rr.Header().Get("X-Content-Type-Options"); got != "nosniff" {
+		t.Errorf("X-Content-Type-Options: want nosniff, got %q", got)
+	}
+	if got := rr.Header().Get("Referrer-Policy"); got != "strict-origin-when-cross-origin" {
+		t.Errorf("Referrer-Policy: got %q", got)
+	}
+	perms := rr.Header().Get("Permissions-Policy")
+	for _, want := range []string{"camera=()", "microphone=()", "geolocation=()", "payment=()", "usb=()"} {
+		if !strings.Contains(perms, want) {
+			t.Errorf("Permissions-Policy missing %q: got %q", want, perms)
+		}
+	}
+	if rr.Header().Get("Strict-Transport-Security") != "" {
+		t.Error("HSTS should not be set when HSTSEnabled=false")
+	}
+}
+
+func TestSecurityHeaders_HSTSOnlyWhenEnabled(t *testing.T) {
+	t.Parallel()
+	next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	})
+	cfg := &config.Config{}
+	cfg.Server.HSTSEnabled = true
+	h := securityHeadersMiddleware(cfg)(next)
+
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	rr := httptest.NewRecorder()
+	h.ServeHTTP(rr, req)
+
+	hsts := rr.Header().Get("Strict-Transport-Security")
+	if !strings.Contains(hsts, "max-age=31536000") {
+		t.Errorf("HSTS missing max-age; got %q", hsts)
+	}
+}
+```
+
+- [ ] **Step 3: Run tests (red)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestSecurityHeaders -v
+```
+
+Expected: two new tests FAIL (headers not yet set). Existing CSP tests still pass.
+
+- [ ] **Step 4: Extend the middleware**
+
+Replace the body of `securityHeadersMiddleware` in `internal/api/security_headers.go`:
+
+```go
+const (
+	contentSecurityPolicy = "default-src 'self'; " +
+		"script-src 'self' 'wasm-unsafe-eval'; " +
+		"style-src 'self' 'unsafe-inline'; " +
+		"connect-src 'self'; " +
+		"img-src 'self' data:; " +
+		"font-src 'self'; " +
+		"frame-ancestors 'none'; " +
+		"base-uri 'self'"
+
+	permissionsPolicy = "camera=(), microphone=(), geolocation=(), payment=(), usb=()"
+
+	hstsValue = "max-age=31536000; includeSubDomains"
+)
+
+func securityHeadersMiddleware(cfg *config.Config) func(http.Handler) http.Handler {
+	hstsEnabled := cfg != nil && cfg.Server.HSTSEnabled
+	return func(next http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Method == http.MethodOptions {
+				next.ServeHTTP(w, r)
+				return
+			}
+			h := w.Header()
+			h.Set("Content-Security-Policy", contentSecurityPolicy)
+			h.Set("X-Content-Type-Options", "nosniff")
+			h.Set("Referrer-Policy", "strict-origin-when-cross-origin")
+			h.Set("Permissions-Policy", permissionsPolicy)
+			if hstsEnabled {
+				h.Set("Strict-Transport-Security", hstsValue)
+			}
+			next.ServeHTTP(w, r)
+		})
+	}
+}
+```
+
+- [ ] **Step 5: Run tests (green)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestSecurityHeaders -v
+CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s ./...
+```
+
+Expected: all new + existing tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add internal/api/security_headers.go internal/api/security_headers_test.go internal/config/config.go
+git commit -m "$(cat <<'EOF'
+feat(api): baseline security headers alongside CSP
+
+Extends securityHeadersMiddleware with:
+- X-Content-Type-Options: nosniff
+- Referrer-Policy: strict-origin-when-cross-origin
+- Permissions-Policy: disables camera/mic/geo/payment/usb
+- Strict-Transport-Security: 1y max-age + includeSubDomains, gated by
+  server.hsts_enabled (default off) so HTTP-only dev stays unaffected.
+
+Operators behind a TLS terminator or direct TLS should set
+DOCSIQ_SERVER_HSTS_ENABLED=true.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 5: Context-aware slog helper + sample call-site refactors (2.5)
+
+**Files:**
+- Create: `internal/api/log_context.go`
+- Create: `internal/api/log_context_test.go`
+- Modify: `internal/api/handlers.go` — 3-5 representative `slog.*` call sites refactored to use `ContextLogger`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `internal/api/log_context_test.go`:
+
+```go
+package api
+
+import (
+	"bytes"
+	"context"
+	"log/slog"
+	"strings"
+	"testing"
+)
+
+func TestContextLogger_AddsReqIDFromContext(t *testing.T) {
+	// Cannot t.Parallel() because we mutate slog.Default.
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	ctx := context.WithValue(context.Background(), ctxRequestIDKey{}, "abc123")
+	ContextLogger(ctx).Info("hello", "k", "v")
+
+	out := buf.String()
+	if !strings.Contains(out, "req_id=abc123") {
+		t.Fatalf("expected req_id=abc123 in log output; got %q", out)
+	}
+	if !strings.Contains(out, "k=v") {
+		t.Fatalf("expected k=v to survive; got %q", out)
+	}
+}
+
+func TestContextLogger_NoReqIDWhenMissing(t *testing.T) {
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, nil)))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	ContextLogger(context.Background()).Info("hello")
+
+	out := buf.String()
+	if strings.Contains(out, "req_id=") {
+		t.Fatalf("req_id should be absent when context has no ID; got %q", out)
+	}
+}
+```
+
+- [ ] **Step 2: Run tests (red)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestContextLogger -v
+```
+
+Expected: FAIL — `undefined: ContextLogger`.
+
+- [ ] **Step 3: Implement the helper**
+
+Create `internal/api/log_context.go`:
+
+```go
+package api
+
+import (
+	"context"
+	"log/slog"
+)
+
+// ContextLogger returns slog.Default() enriched with the per-request ID
+// when the context carries one. Handler trees that funnel log calls
+// through this helper get free request-level log correlation; downstream
+// code that needs the ID for metric labels should still read it via
+// RequestIDFromContext(ctx) directly.
+//
+// Callers that don't need the enrichment can keep using slog.Default()
+// — the helper is additive, not mandatory.
+func ContextLogger(ctx context.Context) *slog.Logger {
+	if id := RequestIDFromContext(ctx); id != "" {
+		return slog.Default().With("req_id", id)
+	}
+	return slog.Default()
+}
+```
+
+- [ ] **Step 4: Run tests (green)**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestContextLogger -v
+```
+
+Expected: both PASS.
+
+- [ ] **Step 5: Refactor a representative set of handler log sites**
+
+Goal: prove the helper composes with existing patterns and give operators immediate value for the most-hit error paths. Scope the refactor to 3–5 sites. Prefer sites that:
+- Sit inside an HTTP handler (have `r *http.Request` in scope)
+- Currently use `slog.Warn` / `slog.Error` (the signal worth correlating)
+- Are on hot or error paths
+
+Good candidates to look for in `internal/api/handlers.go`:
+- The `upload` handler's error paths (e.g., the `writeTooLarge`, `ErrQueueFull`, `ErrClosed` branches landed in Block 1)
+- The `search` handler's error-branch slog calls
+- The `writeError` function itself if it has a `slog.Error` inside
+
+Process:
+```bash
+grep -nE 'slog\.(Warn|Error)' internal/api/handlers.go | head -20
+```
+
+Pick 3-5 sites. For each, change:
+```go
+slog.Warn("upload failed", "slug", slug, "err", err)
+```
+to:
+```go
+ContextLogger(r.Context()).Warn("upload failed", "slug", slug, "err", err)
+```
+
+**Do not attempt a full sweep.** Remaining sites are tech debt; a future Block 4 (observability) sweep can cover them. Note the deferral in the commit message.
+
+If a site is inside a helper that doesn't have `r *http.Request` but does have `ctx context.Context`, use `ContextLogger(ctx).Warn(...)`.
+
+- [ ] **Step 6: Run full Go suite to confirm no regression**
+
+```
+CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s ./...
+```
+
+Expected: all pass. The refactor is behavior-preserving (same log level, same message, same key/value pairs; just one extra field attached).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add internal/api/log_context.go internal/api/log_context_test.go internal/api/handlers.go
+git commit -m "$(cat <<'EOF'
+feat(api): ContextLogger threads req_id into slog for correlation
+
+Adds an additive helper next to the existing RequestIDFromContext:
+ContextLogger(ctx) returns slog.Default() enriched with req_id=<id>
+when the context carries one from loggingMiddleware. Refactored
+<N> representative error-path log sites in handlers.go to use it.
+
+The rest of the codebase keeps using slog.Default() directly — a
+wider sweep is tracked as tech debt for the observability sweep.
+
+Note: the roadmap's 2.5 bullet mentioned ULID. The existing
+request_id.go generates 16-char hex from crypto/rand which is
+collision-safe for the air-gapped single-binary deploy. Not
+worth changing as part of this PR.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Self-Review
+
+### Spec coverage
+
+- **2.1 CSP header** → Task 3 (full directive list matches spec).
+- **2.2 Baseline security headers** → Task 4 (nosniff, Referrer-Policy, Permissions-Policy, HSTS with `server.hsts_enabled` gate; spec allowed `server.tls_cert` as the gate — we use an explicit boolean which is simpler and operator-controllable without adding a TLS-cert loading path in this block).
+- **2.3 Secret scrubbing** → Task 2 (`Redact()` helper + `secret:"true"` tagging + audit of existing config-log sites).
+- **2.4 Config validation** → Task 1 (`UnmarshalExact` + `validateLLM` with provider-triple checks).
+- **2.5 Request-ID middleware** → Task 5 (the ID infrastructure already exists from Block 1's error-shape work; this task closes the slog-threading gap and explicitly defers ULID).
+
+All five items have dedicated tasks.
+
+### Placeholder check
+
+No `TBD`, no `TODO`, no "similar to", no "add appropriate error handling". Every code step has full code. Commands are exact.
+
+Step 5 in Task 5 lists "3-5 sites" rather than naming specific lines — this is intentional because exact line numbers drift (Block 1 moved things around) and the plan author cannot pre-commit to specific sites without reading the tree at implementation time. The step's selection criteria are concrete ("sits inside an HTTP handler", "currently slog.Warn/Error", "error path"), the identification command is exact (`grep -nE 'slog\.(Warn|Error)' internal/api/handlers.go`), and the transformation pattern is shown with a before/after example. This is the most precise the plan can be without becoming brittle against drift.
+
+### Type consistency
+
+- `securityHeadersMiddleware(cfg *config.Config) func(http.Handler) http.Handler` — same signature Task 3 and Task 4. Wired identically at `router.go`.
+- `ContextLogger(ctx context.Context) *slog.Logger` — same signature Task 5 throughout.
+- `validateLLM(cfg *Config) error` — defined once in Task 1.
+- `(c *Config) Redact() *Config` — defined once in Task 2.
+- `secret:"true"` struct tag used consistently in Task 2 and already present on the `APIKey` fields by the time Task 4 edits `ServerConfig` (Task 4's edit preserves the existing tags).
+- `ctxRequestIDKey{}` and `RequestIDFromContext` are existing types/functions from `internal/api/request_id.go`; Task 5's tests import them correctly.
+
+### Dependency ordering
+
+- Task 1 is purely additive to config loading (adds validation, tightens unmarshal). Independent of everything else.
+- Task 2 adds a struct tag to fields that Task 1 also reads — harmless because tags are metadata.
+- Tasks 3 and 4 build on each other: Task 4 edits the file Task 3 created. Must land in order.
+- Task 5 is independent of Tasks 1–4.
+
+Recommended sequence: 1 → 2 → 3 → 4 → 5. Tasks 1, 2, 5 could theoretically ship in parallel, but subagent-driven-development runs sequentially so that's moot.
+
+---
+
+## Execution Handoff
+
+**Plan complete and saved to `docs/superpowers/plans/2026-04-23-block2-security-plan.md`.**
+
+Two execution options:
+
+1. **Subagent-Driven (recommended)** — fresh subagent per task, spec + code-quality review between each, same cadence as Block 1.
+2. **Inline Execution** — this session drives all five tasks with periodic checkpoints.
+
+Which approach?
diff --git a/docs/superpowers/plans/2026-04-23-block3-resource-safety-plan.md b/docs/superpowers/plans/2026-04-23-block3-resource-safety-plan.md
new file mode 100644
index 0000000..68d6d3e
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-23-block3-resource-safety-plan.md
@@ -0,0 +1,2222 @@
+# Block 3 — Resource Safety & Correctness Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make docsiq resilient to misbehaving upstreams, slow disks, abrupt shutdowns, and runaway requests — by enforcing context propagation end-to-end, wrapping every outbound call in a timeout, pooling HTTP clients per provider, hardening SQLite PRAGMAs, chunking `EmbedBatch` with backpressure, ringing the HTTP surface with `http.TimeoutHandler`, and enriching the existing panic-recovery and signal-shutdown paths.
+
+**Architecture:** Seven independently-landable tasks. Task 1 (SQLite hardening) stands alone and de-risks every later integration test. Tasks 2 → 3 → 4 build up the LLM provider surface from the network layer outward: first pool the `*http.Client`, then layer a per-call `context.WithTimeout`, then chunk `EmbedBatch` against each provider's declared ceiling with a buffered-channel backpressure shape. Task 5 is a pure static-check + targeted-fix pass that leverages the ctx-first pattern already used in `internal/store`; it's scheduled late so any ctx gaps introduced by Tasks 2–4 are caught in the same sweep. Task 6 lands `http.TimeoutHandler` with explicit layering constraints against Block 2's security-headers middleware. Task 7 closes the two small gaps Block 1 left open in graceful shutdown: panic-log enrichment (req_id, route, method, user) and a defensive-readback audit that signal handling and `workq.Close` already happen in `cmd/serve.go`.
+
+**Tech Stack:** Go 1.22+, `context`, `net/http`, `net/http/httptest`, `database/sql`, `mattn/go-sqlite3`, `log/slog`, Viper + mapstructure. No new third-party dependencies. Existing helpers: `internal/api/request_id.go` (`RequestIDFromContext`), `internal/workq` (`Pool.Close(ctx)`), `internal/api/auth.go` (`UserFromContext` pattern — used for the panic-log enrichment).
+
+**Scope check:** Seven items, two subsystems (HTTP/LLM surface + SQLite). All items share the common theme of bounding resource use and propagating cancellation. No sub-plan decomposition needed; each task is self-contained and produces a compilable, testable diff.
+
+**Dependency note:** Block 2 (PR TBD) introduces `securityHeadersMiddleware` as the outermost router wrapper and a `ContextLogger(ctx)` helper. Task 6 (`http.TimeoutHandler`) must land *after* Block 2 merges so the layering is correct. Tasks 1–5 and Task 7's panic-log enrichment are independent of Block 2 and can land in any order relative to it. If Block 2 has not merged when this plan is executed, Task 6's middleware wiring step documents the fallback layering (TimeoutHandler becomes the outermost wrapper, and Block 2 later reorders so headers go outside it).
+
+---
+
+## File Structure
+
+### Create
+
+- `internal/store/store_hardening_test.go` — verifies PRAGMAs and `Ping(ctx)` post-open (Task 1).
+- `internal/llm/httpclient.go` — `newHTTPClient()` helper returning a `*http.Client` with a tuned `*http.Transport` (Task 2).
+- `internal/llm/httpclient_test.go` — asserts transport settings on the returned client (Task 2).
+- `internal/llm/timeout_test.go` — verifies `Complete` / `Embed` / `EmbedBatch` honour `cfg.LLM.CallTimeout` (Task 3).
+- `internal/embedder/batch_test.go` — verifies chunking + backpressure (Task 4).
+- `internal/api/timeout_test.go` — verifies the request-level timeout plus upload-endpoint override (Task 6).
+- `scripts/ctx-audit.sh` — tiny custom linter that greps for HTTP/DB calls missing a ctx argument in the listed packages (Task 5).
+- `internal/api/panic_enrichment_test.go` — verifies panic log carries `req_id`, `route`, `method`, `user` (Task 7).
+
+### Modify
+
+- `internal/store/store.go` — `open` helper (around line 38) re-keyed to explicit `PRAGMA` calls after `sql.Open`; pool settings raised to `MaxOpenConns=4, MaxIdleConns=2, ConnMaxLifetime=1h`; new `Ping(ctx)` method on `*Store` (Task 1).
+- `internal/config/config.go:145-152` — add `RequestTimeout`, `UploadTimeout` to `ServerConfig`; add `CallTimeout` to `LLMConfig`; add defaults + `BindEnv` wiring at the bottom of `Load` (Tasks 3, 6).
+- `internal/llm/provider.go` — `lcProvider` gains an unexported `httpClient *http.Client` field and `callTimeout time.Duration`; `Complete`/`Embed`/`EmbedBatch` wrap `parent` in `context.WithTimeout` when `callTimeout > 0` (Task 3). `EmbedBatch` slices input to `batchCeiling` and feeds a buffered channel of size `2*batchCeiling` (Task 4).
+- `internal/llm/openai.go` — `newOpenAIProvider` constructs the tuned client via `newHTTPClient()` and passes it via `openai.WithHTTPClient(...)` (Task 2). Declares `batchCeiling = 2048` (Task 4).
+- `internal/llm/provider.go` (`newAzureProvider`, `newOllamaProvider`) — same client injection pattern; declare `batchCeiling = 16` (Azure), `batchCeiling = 128` (Ollama) (Tasks 2, 4).
+- `internal/api/router.go:205-215` — `recoveryMiddleware` enriched to capture `req_id`, `route`, `method`, `user`, full stack on panic (Task 7).
+- `internal/api/router.go:~218` (the bottom `return loggingMiddleware(...)` expression) — wrapped with `requestTimeoutMiddleware(cfg)` between the security-headers layer and `loggingMiddleware`; `POST /api/upload` and `POST /api/projects/{project}/docs` route through a longer-timeout branch (Task 6).
+- `scripts/ctx-audit.sh` invocation in `Makefile` (if one exists; else documented as a one-liner) and CI — Task 5 step 2 covers discovery.
+- `cmd/serve.go` — verify signal-handling/shutdown sequence; no functional change expected. Only step: log-line audit in Task 7 step 6 confirming existing `🛑 shutting down...` → `srv.Shutdown` → `pool.Close` already covers the spec's progress-logging requirement.
+
+### No Placeholders — All Pointers Are Real
+
+Every file mentioned above exists today (checked against `internal/store/store.go`, `internal/config/config.go`, `internal/llm/provider.go`, `internal/api/router.go`, `cmd/serve.go`) except the eight files flagged **Create**. No invented types, no invented packages.
+
+---
+
+## Task 1: SQLite hardening (3.6)
+
+**Files:**
+- Modify: `internal/store/store.go:35-48` (the `open` helper + pool config)
+- Modify: `internal/store/store.go:~81` (append `Ping(ctx)` method near `Close`)
+- Create: `internal/store/store_hardening_test.go`
+
+### Rationale
+
+Today `internal/store/store.go:38` wires PRAGMAs through the DSN query string:
+
+```go
+db, err := sql.Open("sqlite3", path+"?_journal_mode=WAL&_foreign_keys=on&_busy_timeout=5000")
+// ...
+db.SetMaxOpenConns(1) // SQLite WAL allows 1 writer
+```
+
+Three problems:
+
+1. `synchronous=NORMAL` is missing — SQLite defaults to `FULL` under WAL which costs two fsyncs per commit; `NORMAL` is the documented WAL-safe sweet spot.
+2. DSN-string PRAGMAs are driver-specific to `mattn/go-sqlite3` and silently ignored by some alternative drivers. Running explicit `PRAGMA` statements post-open is portable and self-documenting.
+3. `MaxOpenConns=1` is conservative to the point of serializing all reads. WAL mode supports concurrent readers; the writer is already serialized by SQLite itself. Raising to 4 (with 2 idle, 1-hour max lifetime) lets the upload pipeline and search handlers overlap reads without fighting for a single connection slot.
+
+There is no `Ping(ctx)` on `*Store` today — only a raw `db.Ping()` reachable via `s.DB().Ping()`. Exposing a context-aware `Ping(ctx)` on the interface unblocks Block 4's `/readyz` endpoint.
+
+- [ ] **Step 1: Write the failing hardening test**
+
+Create `internal/store/store_hardening_test.go`:
+
+```go
+package store
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+// TestOpen_HardeningPragmas verifies Block 3.6 — every PRAGMA the spec
+// requires is observable on a freshly-opened store.
+func TestOpen_HardeningPragmas(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	s, err := OpenForProject(dir, "harden")
+	if err != nil {
+		t.Fatalf("OpenForProject: %v", err)
+	}
+	defer s.Close()
+
+	cases := []struct {
+		name string
+		sql  string
+		want string
+	}{
+		{"journal_mode", `PRAGMA journal_mode`, "wal"},
+		{"foreign_keys", `PRAGMA foreign_keys`, "1"},
+		{"synchronous", `PRAGMA synchronous`, "1"}, // 1 = NORMAL
+	}
+	for _, c := range cases {
+		c := c
+		t.Run(c.name, func(t *testing.T) {
+			var got string
+			if err := s.DB().QueryRow(c.sql).Scan(&got); err != nil {
+				t.Fatalf("%s: %v", c.sql, err)
+			}
+			if got != c.want {
+				t.Fatalf("%s = %q; want %q", c.sql, got, c.want)
+			}
+		})
+	}
+
+	t.Run("busy_timeout_ge_5000", func(t *testing.T) {
+		var got int
+		if err := s.DB().QueryRow(`PRAGMA busy_timeout`).Scan(&got); err != nil {
+			t.Fatalf("PRAGMA busy_timeout: %v", err)
+		}
+		if got < 5000 {
+			t.Fatalf("busy_timeout = %d ms; want >= 5000", got)
+		}
+	})
+}
+
+// TestOpen_PoolSettings asserts the raised MaxOpenConns / MaxIdleConns
+// values survive the Open recipe. MaxOpenConns=4, MaxIdleConns=2,
+// ConnMaxLifetime=1h are not individually observable via sql.DB stats
+// without opening connections; we assert on Stats().MaxOpenConnections
+// which reflects SetMaxOpenConns.
+func TestOpen_PoolSettings(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	s, err := OpenForProject(dir, "pool")
+	if err != nil {
+		t.Fatalf("OpenForProject: %v", err)
+	}
+	defer s.Close()
+
+	stats := s.DB().Stats()
+	if stats.MaxOpenConnections != 4 {
+		t.Fatalf("MaxOpenConnections = %d; want 4", stats.MaxOpenConnections)
+	}
+}
+
+// TestStore_PingContext asserts the new context-aware Ping method.
+// A cancelled context must surface as a ctx.Err(), not a generic
+// database error, so that /readyz can distinguish "caller gave up"
+// from "SQLite is sick".
+func TestStore_PingContext(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	s, err := OpenForProject(dir, "ping")
+	if err != nil {
+		t.Fatalf("OpenForProject: %v", err)
+	}
+	defer s.Close()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := s.Ping(ctx); err != nil {
+		t.Fatalf("Ping: %v", err)
+	}
+
+	cancelled, cancel2 := context.WithCancel(context.Background())
+	cancel2()
+	if err := s.Ping(cancelled); err == nil {
+		t.Fatalf("Ping on cancelled ctx: want non-nil error, got nil")
+	}
+}
+```
+
+- [ ] **Step 2: Run the test (red)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/store/ -run TestOpen_HardeningPragmas -v`
+
+Expected: FAIL on `synchronous = 2; want 1` (default `FULL=2`, want `NORMAL=1`).
+
+Also run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/store/ -run TestOpen_PoolSettings -v`
+
+Expected: FAIL on `MaxOpenConnections = 1; want 4`.
+
+Also run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/store/ -run TestStore_PingContext -v`
+
+Expected: FAIL — `s.Ping undefined (type *Store has no field or method Ping)`.
+
+- [ ] **Step 3: Implement the hardened `open`**
+
+Edit `internal/store/store.go`. Replace the existing `open` function (lines 35-48) with:
+
+```go
+// open is the low-level SQLite opener. It is unexported — the only public
+// factory is OpenForProject. Kept as a helper because the project registry
+// and the per-project store both use the same DSN+migrate recipe.
+//
+// Block 3.6 hardening:
+//   - PRAGMAs set explicitly via Exec after sql.Open (driver-portable).
+//   - MaxOpenConns=4 + MaxIdleConns=2 allows concurrent readers under
+//     WAL; the writer is already serialized by SQLite itself.
+//   - ConnMaxLifetime=1h guards against stale connections in long-lived
+//     server processes.
+func open(path string) (*Store, error) {
+	if path == "" {
+		return nil, fmt.Errorf("open db: path is empty")
+	}
+	// _busy_timeout retained in the DSN as a belt-and-braces default:
+	// the explicit PRAGMA below is the authoritative setting, but the
+	// DSN form protects against an early query landing before the
+	// PRAGMA Exec completes.
+	db, err := sql.Open("sqlite3", path+"?_busy_timeout=5000")
+	if err != nil {
+		return nil, fmt.Errorf("open db: %w", err)
+	}
+
+	pragmas := []string{
+		`PRAGMA journal_mode=WAL`,
+		`PRAGMA busy_timeout=5000`,
+		`PRAGMA synchronous=NORMAL`,
+		`PRAGMA foreign_keys=ON`,
+	}
+	for _, p := range pragmas {
+		if _, err := db.Exec(p); err != nil {
+			_ = db.Close()
+			return nil, fmt.Errorf("open db: %s: %w", p, err)
+		}
+	}
+
+	db.SetMaxOpenConns(4)
+	db.SetMaxIdleConns(2)
+	db.SetConnMaxLifetime(1 * time.Hour)
+
+	s := &Store{db: db}
+	if err := s.migrate(); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+	return s, nil
+}
+```
+
+- [ ] **Step 4: Add `Ping(ctx)` method**
+
+Edit `internal/store/store.go`. Locate the existing `Close()` method (around line 81). Append directly below it:
+
+```go
+// Ping verifies the database connection is alive. Uses PingContext so
+// a cancelled ctx surfaces as ctx.Err(); callers (e.g. /readyz) can
+// differentiate "request cancelled" from "SQLite broken".
+func (s *Store) Ping(ctx context.Context) error {
+	return s.db.PingContext(ctx)
+}
+```
+
+- [ ] **Step 5: Run tests (green)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/store/ -v`
+
+Expected: all tests PASS — including the new `TestOpen_HardeningPragmas`, `TestOpen_PoolSettings`, `TestStore_PingContext`, plus the existing `TestOpen_BusyTimeoutPragma` regression test.
+
+- [ ] **Step 6: Run the whole suite with race detector to catch pool-related regressions**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 -race -timeout 300s ./...`
+
+Expected: PASS everywhere. Pay attention to any store-adjacent package (`internal/pipeline`, `internal/community`, `internal/api`); raising `MaxOpenConns` from 1 to 4 changes the serialization characteristics SQLite already enforces internally, but the Go-side contract shifts — any test relying on implicit single-connection ordering will surface here.
+
+If a race/deadlock surfaces in a specific test, diagnose root cause (likely an ad-hoc `db.Query` inside a write transaction on a different goroutine). Do not paper over with `SetMaxOpenConns(1)`.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add internal/store/store.go internal/store/store_hardening_test.go
+git commit -m "$(cat <<'EOF'
+feat(store): SQLite hardening — explicit PRAGMAs, raised pool, Ping(ctx)
+
+Replaces DSN-embedded PRAGMAs with explicit `db.Exec("PRAGMA …")` calls
+so the recipe is driver-portable and self-documenting. Adds
+`PRAGMA synchronous=NORMAL` — the WAL-safe default that cuts two fsyncs
+per commit to one — which was silently missing before. Raises
+MaxOpenConns from 1 to 4 (with MaxIdleConns=2, ConnMaxLifetime=1h) so
+concurrent readers overlap under WAL; the writer remains serialized
+by SQLite itself.
+
+Adds `(*Store).Ping(ctx context.Context) error` on the public Store
+surface so Block 4's /readyz can distinguish a cancelled caller from
+a dead database. Covered by TestStore_PingContext.
+
+Block 3.6.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 2: HTTP client pooling per LLM provider (3.5)
+
+**Files:**
+- Create: `internal/llm/httpclient.go`
+- Create: `internal/llm/httpclient_test.go`
+- Modify: `internal/llm/openai.go` — inject the pooled client into `openai.New(...)`
+- Modify: `internal/llm/provider.go` — same injection in `newAzureProvider` and `newOllamaProvider`; store `*http.Client` on `lcProvider`
+
+### Rationale
+
+Langchaingo constructs a fresh `net/http.Transport` per call-site today — meaning every `openai.New`, `ollama.New`, etc. allocates its own TCP/TLS pool. For a long-running server that talks to OpenAI / Azure / Ollama on every request, this wastes connections and defeats keep-alive. A single shared `*http.Client` per provider with a tuned transport closes the leak.
+
+Spec-mandated transport settings:
+- `MaxIdleConns=100`
+- `MaxIdleConnsPerHost=10`
+- `IdleConnTimeout=90s`
+- `TLSHandshakeTimeout=10s`
+- `ResponseHeaderTimeout=60s`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `internal/llm/httpclient_test.go`:
+
+```go
+package llm
+
+import (
+	"net/http"
+	"testing"
+	"time"
+)
+
+// TestNewHTTPClient_TransportSettings verifies the tuned transport
+// settings required by Block 3.5.
+func TestNewHTTPClient_TransportSettings(t *testing.T) {
+	t.Parallel()
+	c := newHTTPClient()
+	if c == nil {
+		t.Fatal("newHTTPClient returned nil")
+	}
+	tr, ok := c.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("Transport = %T; want *http.Transport", c.Transport)
+	}
+	if got, want := tr.MaxIdleConns, 100; got != want {
+		t.Errorf("MaxIdleConns = %d; want %d", got, want)
+	}
+	if got, want := tr.MaxIdleConnsPerHost, 10; got != want {
+		t.Errorf("MaxIdleConnsPerHost = %d; want %d", got, want)
+	}
+	if got, want := tr.IdleConnTimeout, 90*time.Second; got != want {
+		t.Errorf("IdleConnTimeout = %v; want %v", got, want)
+	}
+	if got, want := tr.TLSHandshakeTimeout, 10*time.Second; got != want {
+		t.Errorf("TLSHandshakeTimeout = %v; want %v", got, want)
+	}
+	if got, want := tr.ResponseHeaderTimeout, 60*time.Second; got != want {
+		t.Errorf("ResponseHeaderTimeout = %v; want %v", got, want)
+	}
+}
+
+// TestNewHTTPClient_NoClientTimeout asserts we do NOT set
+// http.Client.Timeout — that would hard-cut the body mid-stream on
+// large embedding responses. Per-call timeouts live on ctx instead
+// (Task 3).
+func TestNewHTTPClient_NoClientTimeout(t *testing.T) {
+	t.Parallel()
+	c := newHTTPClient()
+	if c.Timeout != 0 {
+		t.Fatalf("Client.Timeout = %v; want 0 (use ctx per-call)", c.Timeout)
+	}
+}
+```
+
+- [ ] **Step 2: Run the test (red)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/llm/ -run TestNewHTTPClient -v`
+
+Expected: FAIL — `newHTTPClient undefined`.
+
+- [ ] **Step 3: Implement `newHTTPClient`**
+
+Create `internal/llm/httpclient.go`:
+
+```go
+// Package llm — HTTP client pooling per provider (Block 3.5).
+//
+// langchaingo constructs a fresh net/http.Transport inside each
+// provider constructor by default. For a long-running server that
+// calls the same provider on every request, that leaks connections:
+// every call-site allocates its own idle-conn pool, TLS session
+// cache, and DNS resolver bucket. Pooling one *http.Client per
+// provider (constructed here) fixes the leak.
+package llm
+
+import (
+	"net"
+	"net/http"
+	"time"
+)
+
+// newHTTPClient returns a *http.Client tuned for long-lived LLM
+// provider traffic. The transport settings are spec-driven:
+//   - MaxIdleConns=100          — plenty of headroom for bursty batching
+//   - MaxIdleConnsPerHost=10    — matches langchaingo default fan-out
+//   - IdleConnTimeout=90s       — trim idle conns before cloud LBs do
+//   - TLSHandshakeTimeout=10s   — fail fast on broken TLS upstreams
+//   - ResponseHeaderTimeout=60s — distinct from body-stream timeout;
+//     bounds the silent-server failure mode
+//
+// Deliberately NOT set:
+//   - Client.Timeout — would hard-cut streaming bodies; per-call
+//     timeouts come from ctx (Task 3 / Block 3.3).
+//   - DialContext timeout — Go's default (no timeout, relies on ctx)
+//     is correct here; a fixed dial timeout fights ctx-driven shutdown.
+func newHTTPClient() *http.Client {
+	tr := &http.Transport{
+		Proxy: http.ProxyFromEnvironment,
+		DialContext: (&net.Dialer{
+			Timeout:   30 * time.Second,
+			KeepAlive: 30 * time.Second,
+		}).DialContext,
+		ForceAttemptHTTP2:     true,
+		MaxIdleConns:          100,
+		MaxIdleConnsPerHost:   10,
+		IdleConnTimeout:       90 * time.Second,
+		TLSHandshakeTimeout:   10 * time.Second,
+		ResponseHeaderTimeout: 60 * time.Second,
+		ExpectContinueTimeout: 1 * time.Second,
+	}
+	return &http.Client{Transport: tr}
+}
+```
+
+- [ ] **Step 4: Run the test (green)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/llm/ -run TestNewHTTPClient -v`
+
+Expected: both sub-tests PASS.
+
+- [ ] **Step 5: Wire the pooled client into OpenAI provider**
+
+Edit `internal/llm/openai.go`. Locate `newOpenAIProvider`. Replace its current body (the block that builds `chatOpts` and calls `openai.New`) with the version below. The only additions are the `httpClient` construction and the `openai.WithHTTPClient(...)` option in both option slices:
+
+```go
+func newOpenAIProvider(cfg *config.LLMConfig) (Provider, error) {
+	oc := &cfg.OpenAI
+	if oc.APIKey == "" {
+		return nil, fmt.Errorf("openai: API key is empty (set llm.openai.api_key or DOCSIQ_LLM_OPENAI_API_KEY)")
+	}
+
+	baseURL := oc.BaseURL
+	if baseURL == "" {
+		baseURL = defaultOpenAIBaseURL
+	}
+	chatModel := oc.ChatModel
+	if chatModel == "" {
+		chatModel = defaultOpenAIChatModel
+	}
+	embedModel := oc.EmbedModel
+	if embedModel == "" {
+		embedModel = defaultOpenAIEmbedModel
+	}
+
+	// Block 3.5: one pooled *http.Client shared across chat + embed
+	// langchaingo handles. Same connection pool for every outbound
+	// request the lcProvider makes.
+	httpClient := newHTTPClient()
+
+	chatOpts := []openai.Option{
+		openai.WithToken(oc.APIKey),
+		openai.WithBaseURL(baseURL),
+		openai.WithModel(chatModel),
+		openai.WithHTTPClient(httpClient),
+	}
+	if oc.Organization != "" {
+		chatOpts = append(chatOpts, openai.WithOrganization(oc.Organization))
+	}
+	chatLLM, err := openai.New(chatOpts...)
+	if err != nil {
+		return nil, fmt.Errorf("openai chat LLM: %w", err)
+	}
+
+	embedOpts := []openai.Option{
+		openai.WithToken(oc.APIKey),
+		openai.WithBaseURL(baseURL),
+		openai.WithEmbeddingModel(embedModel),
+		openai.WithModel(chatModel),
+		openai.WithHTTPClient(httpClient),
+	}
+	if oc.Organization != "" {
+		embedOpts = append(embedOpts, openai.WithOrganization(oc.Organization))
+	}
+	embedLLM, err := openai.New(embedOpts...)
+	if err != nil {
+		return nil, fmt.Errorf("openai embed LLM: %w", err)
+	}
+	emb, err := embeddings.NewEmbedder(embedLLM)
+	if err != nil {
+		return nil, fmt.Errorf("openai embedder: %w", err)
+	}
+
+	return &lcProvider{
+		llm:           chatLLM,
+		emb:           emb,
+		name:          "openai",
+		modelID:       embedModel,
+		httpClient:    httpClient,
+		batchCeiling:  2048,
+	}, nil
+}
+```
+
+Note: `httpClient` and `batchCeiling` are new fields on `lcProvider`. Add them in step 6. The `embeddings` and `openai` imports are already present; no new imports.
+
+- [ ] **Step 6: Add `httpClient` and `batchCeiling` fields to `lcProvider`**
+
+Edit `internal/llm/provider.go`. Locate the `lcProvider` struct definition. Extend it:
+
+```go
+// lcProvider adapts langchaingo to our Provider interface.
+type lcProvider struct {
+	llm     llms.Model
+	emb     embeddings.Embedder
+	name    string
+	modelID string
+
+	// Block 3.5: pooled HTTP client shared with the langchaingo
+	// sub-clients. Stored here so tests can assert on it and so
+	// future work can swap it (e.g. for a tracing transport).
+	httpClient *http.Client
+
+	// Block 3.3: optional per-call timeout wrapped around ctx. Zero
+	// means "no timeout" (caller's ctx is authoritative); positive
+	// values trigger context.WithTimeout in Complete/Embed/EmbedBatch.
+	callTimeout time.Duration
+
+	// Block 3.4: provider-declared batch ceiling. EmbedBatch slices
+	// input to this size; caller-visible chunking also uses this
+	// value so the Embedder can construct correctly-sized jobs.
+	batchCeiling int
+}
+```
+
+Add `"net/http"` and `"time"` to the imports at the top of `provider.go` if not already present (check with the imports block — `time` is likely already there from `applyOptions`; `net/http` is likely new).
+
+- [ ] **Step 7: Wire the pooled client into Ollama and Azure providers**
+
+Still in `internal/llm/provider.go`.
+
+Update `newOllamaProvider` to share a client. Locate it; replace the return statement with a version that passes `ollama.WithHTTPClient(httpClient)` to both `ollama.New` calls and populates the new struct fields:
+
+```go
+func newOllamaProvider(cfg *config.LLMConfig) (Provider, error) {
+	httpClient := newHTTPClient()
+
+	chatLLM, err := ollama.New(
+		ollama.WithServerURL(cfg.Ollama.BaseURL),
+		ollama.WithModel(cfg.Ollama.ChatModel),
+		ollama.WithHTTPClient(httpClient),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("ollama chat LLM: %w", err)
+	}
+	embedLLM, err := ollama.New(
+		ollama.WithServerURL(cfg.Ollama.BaseURL),
+		ollama.WithModel(cfg.Ollama.EmbedModel),
+		ollama.WithHTTPClient(httpClient),
+	)
+	if err != nil {
+		return nil, fmt.Errorf("ollama embed LLM: %w", err)
+	}
+	emb, err := embeddings.NewEmbedder(embedLLM)
+	if err != nil {
+		return nil, fmt.Errorf("ollama embedder: %w", err)
+	}
+	return &lcProvider{
+		llm:          chatLLM,
+		emb:          emb,
+		name:         "ollama",
+		modelID:      cfg.Ollama.EmbedModel,
+		httpClient:   httpClient,
+		batchCeiling: 128,
+	}, nil
+}
+```
+
+If `ollama.WithHTTPClient` is not an exported option in the vendored langchaingo revision, skip it for Ollama (self-hosted, usually loopback — pooling has less value). In that case, add a comment `// ollama: langchaingo revision does not expose WithHTTPClient — pool is not injected. Acceptable: Ollama typically runs on loopback where pool savings are marginal.` and still populate `httpClient: httpClient` on the struct (the field is informational in that fallback).
+
+Update `newAzureProvider` similarly. The Azure path uses `openai.New` under the hood (see the existing code that calls `openai.WithToken(az.ChatAPIKey())` etc.); add `openai.WithHTTPClient(httpClient)` to every call there and set `batchCeiling: 16`.
+
+- [ ] **Step 8: Build the whole module**
+
+Run: `CGO_ENABLED=1 go build -tags sqlite_fts5 ./...`
+
+Expected: BUILD OK. If `ollama.WithHTTPClient` or `openai.WithHTTPClient` does not exist in the vendored langchaingo, fix by reading the vendored package (`vendor/github.com/tmc/langchaingo/llms/openai/`) to find the correct option name, or fall back to the inspection-based comment noted in Step 7.
+
+- [ ] **Step 9: Run the full Go suite**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s ./...`
+
+Expected: all PASS. The existing `provider_openai_test.go` may need minor updates if it inspects struct fields directly — check output.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add internal/llm/httpclient.go internal/llm/httpclient_test.go internal/llm/openai.go internal/llm/provider.go
+git commit -m "$(cat <<'EOF'
+feat(llm): one pooled *http.Client per provider
+
+langchaingo allocates a fresh net/http.Transport inside every provider
+constructor by default — a new idle-conn pool, TLS session cache, and
+DNS bucket per openai.New / ollama.New call. For a long-running server
+that talks to the same upstream on every request, that's pure waste
+and defeats keep-alive.
+
+Adds internal/llm/httpclient.go with newHTTPClient() returning a
+*http.Client backed by a tuned *http.Transport (MaxIdleConns=100,
+MaxIdleConnsPerHost=10, IdleConnTimeout=90s, TLSHandshakeTimeout=10s,
+ResponseHeaderTimeout=60s). Injects the same client into chat and
+embed langchaingo sub-clients via WithHTTPClient options so every
+provider uses exactly one pool.
+
+The pooled client's Timeout is deliberately 0 — per-call deadlines
+land in Task 3 (3.3) via ctx. Hard-cutting the client would truncate
+streaming embedding responses.
+
+Block 3.5.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 3: LLM call timeouts (3.3)
+
+**Files:**
+- Modify: `internal/config/config.go` — add `LLMConfig.CallTimeout` + default + `BindEnv`
+- Modify: `internal/llm/provider.go` — populate `lcProvider.callTimeout`; wrap ctx in `Complete`, `Embed`, `EmbedBatch`
+- Create: `internal/llm/timeout_test.go`
+
+### Rationale
+
+Spec: "every provider wraps its outbound call in `ctx, cancel := context.WithTimeout(parent, cfg.LLM.CallTimeout)`, default 60s. Retry wrapper (if any) counts retries against the total timeout, not resets it."
+
+Today `lcProvider.Complete/Embed/EmbedBatch` pass the parent ctx straight through to langchaingo. Langchaingo has no internal retry wrapper in the vendored revision (verified by reading `vendor/github.com/tmc/langchaingo/llms/openai/openaillm.go`), so the "retry counts against total timeout" clause collapses to "don't reset the timeout between retries" — trivially satisfied because there is no retry.
+
+- [ ] **Step 1: Add `CallTimeout` to `LLMConfig`**
+
+Edit `internal/config/config.go`. Locate the `LLMConfig` struct (around line 48). Add the field:
+
+```go
+type LLMConfig struct {
+	Provider string       `mapstructure:"provider"`
+	Azure    AzureConfig  `mapstructure:"azure"`
+	Ollama   OllamaConfig `mapstructure:"ollama"`
+	OpenAI   OpenAIConfig `mapstructure:"openai"`
+
+	// CallTimeout caps the end-to-end duration of a single provider
+	// call (Complete / Embed / EmbedBatch). Any retry wrapper counts
+	// against this deadline — the timeout is NOT reset between
+	// attempts. Zero disables the per-call cap (caller's ctx is
+	// authoritative). Default 60s.
+	CallTimeout time.Duration `mapstructure:"call_timeout"`
+}
+```
+
+Add `"time"` to the imports of `config.go` if not already present. It already is (used for other duration fields elsewhere in the file — check with a quick grep; if not, add it now).
+
+- [ ] **Step 2: Add the default and env binding**
+
+Still in `internal/config/config.go`, locate the block of `v.SetDefault("llm.*", …)` calls. Add immediately after the last `llm.*` default:
+
+```go
+	// LLM — per-call timeout (Block 3.3)
+	v.SetDefault("llm.call_timeout", 60*time.Second)
+```
+
+Locate the bottom `_ = v.BindEnv(...)` block. Add:
+
+```go
+	_ = v.BindEnv("llm.call_timeout")
+```
+
+Also verify the Viper instance decodes `time.Duration` strings ("60s") correctly. Viper's default `DecoderConfigOption` chain includes `StringToTimeDurationHookFunc` — this repo uses the default Viper unmarshal, so no extra wiring is needed. If Task 1 of Block 2 already swapped `Unmarshal` for `UnmarshalExact`, that preserves the duration hook. (Double-check by reading `config.go` around the `Unmarshal` call before editing.)
+
+- [ ] **Step 3: Populate `callTimeout` in each provider constructor**
+
+Edit `internal/llm/provider.go`. In each of `newOpenAIProvider`, `newAzureProvider`, `newOllamaProvider`, add `callTimeout: cfg.CallTimeout` to the `lcProvider{}` literal. For `newOpenAIProvider` (in `openai.go`) the struct literal now reads:
+
+```go
+	return &lcProvider{
+		llm:          chatLLM,
+		emb:          emb,
+		name:         "openai",
+		modelID:      embedModel,
+		httpClient:   httpClient,
+		callTimeout:  cfg.CallTimeout,
+		batchCeiling: 2048,
+	}, nil
+```
+
+Same addition for the Ollama and Azure constructors.
+
+- [ ] **Step 4: Wrap ctx in the three provider methods**
+
+Edit `internal/llm/provider.go`. Replace `lcProvider.Complete`, `lcProvider.Embed`, `lcProvider.EmbedBatch` with the timeout-aware versions:
+
+```go
+// withCallTimeout returns a child ctx bounded by p.callTimeout when
+// positive, plus its cancel. Zero/negative callTimeout returns the
+// parent ctx unchanged and a no-op cancel — callers always defer
+// cancel() without branching.
+func (p *lcProvider) withCallTimeout(parent context.Context) (context.Context, context.CancelFunc) {
+	if p.callTimeout <= 0 {
+		return parent, func() {}
+	}
+	return context.WithTimeout(parent, p.callTimeout)
+}
+
+func (p *lcProvider) Complete(ctx context.Context, prompt string, opts ...Option) (string, error) {
+	ctx, cancel := p.withCallTimeout(ctx)
+	defer cancel()
+	o := applyOptions(opts)
+	callOpts := []llms.CallOption{
+		llms.WithMaxTokens(o.maxTokens),
+		llms.WithTemperature(o.temperature),
+	}
+	if o.jsonMode {
+		callOpts = append(callOpts, llms.WithJSONMode())
+	}
+	return llms.GenerateFromSinglePrompt(ctx, p.llm, prompt, callOpts...)
+}
+
+func (p *lcProvider) Embed(ctx context.Context, text string) ([]float32, error) {
+	ctx, cancel := p.withCallTimeout(ctx)
+	defer cancel()
+	return p.emb.EmbedQuery(ctx, text)
+}
+
+func (p *lcProvider) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error) {
+	ctx, cancel := p.withCallTimeout(ctx)
+	defer cancel()
+	return p.emb.EmbedDocuments(ctx, texts)
+}
+```
+
+(Task 4 will rewrite `EmbedBatch` to chunk + backpressure. The timeout wrapper at the outer function remains; it gets moved into `EmbedBatch`'s outer loop in Task 4.)
+
+Add `"context"` to the `provider.go` imports if not already present (it is — `Complete` already takes `ctx context.Context`).
+
+- [ ] **Step 5: Write the timeout test**
+
+Create `internal/llm/timeout_test.go`:
+
+```go
+package llm
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/tmc/langchaingo/embeddings"
+	"github.com/tmc/langchaingo/llms"
+)
+
+// stubModel implements llms.Model by blocking forever on GenerateContent
+// until the context is cancelled. It proves the provider honours ctx
+// deadlines rather than swallowing them.
+type stubModel struct{}
+
+func (stubModel) Call(ctx context.Context, prompt string, opts ...llms.CallOption) (string, error) {
+	return stubModel{}.generate(ctx)
+}
+
+func (stubModel) GenerateContent(ctx context.Context, msgs []llms.MessageContent, opts ...llms.CallOption) (*llms.ContentResponse, error) {
+	if _, err := stubModel{}.generate(ctx); err != nil {
+		return nil, err
+	}
+	return &llms.ContentResponse{}, nil
+}
+
+func (stubModel) generate(ctx context.Context) (string, error) {
+	<-ctx.Done()
+	return "", ctx.Err()
+}
+
+// stubEmbedder blocks on EmbedDocuments / EmbedQuery until ctx done.
+type stubEmbedder struct{}
+
+func (stubEmbedder) EmbedDocuments(ctx context.Context, texts []string) ([][]float32, error) {
+	<-ctx.Done()
+	return nil, ctx.Err()
+}
+
+func (stubEmbedder) EmbedQuery(ctx context.Context, text string) ([]float32, error) {
+	<-ctx.Done()
+	return nil, ctx.Err()
+}
+
+var _ embeddings.Embedder = stubEmbedder{}
+
+func TestLcProvider_Complete_HonoursCallTimeout(t *testing.T) {
+	t.Parallel()
+	p := &lcProvider{
+		llm:         stubModel{},
+		emb:         stubEmbedder{},
+		name:        "stub",
+		modelID:     "stub",
+		callTimeout: 50 * time.Millisecond,
+	}
+	start := time.Now()
+	_, err := p.Complete(context.Background(), "hello")
+	elapsed := time.Since(start)
+	if err == nil {
+		t.Fatal("Complete: want non-nil error on timeout, got nil")
+	}
+	if !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("Complete error: want context.DeadlineExceeded, got %v", err)
+	}
+	if elapsed > 500*time.Millisecond {
+		t.Fatalf("Complete returned after %v; callTimeout=50ms — deadline not propagated", elapsed)
+	}
+}
+
+func TestLcProvider_Embed_HonoursCallTimeout(t *testing.T) {
+	t.Parallel()
+	p := &lcProvider{
+		llm:         stubModel{},
+		emb:         stubEmbedder{},
+		callTimeout: 50 * time.Millisecond,
+	}
+	start := time.Now()
+	_, err := p.Embed(context.Background(), "hello")
+	elapsed := time.Since(start)
+	if err == nil || !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("Embed error: want DeadlineExceeded, got %v", err)
+	}
+	if elapsed > 500*time.Millisecond {
+		t.Fatalf("Embed elapsed = %v; want < 500ms", elapsed)
+	}
+}
+
+func TestLcProvider_ZeroCallTimeout_LeavesParentCtxAuthoritative(t *testing.T) {
+	t.Parallel()
+	p := &lcProvider{
+		llm:         stubModel{},
+		emb:         stubEmbedder{},
+		callTimeout: 0, // disabled — parent ctx wins
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	_, err := p.Complete(ctx, "hello")
+	if err == nil || !errors.Is(err, context.DeadlineExceeded) {
+		t.Fatalf("Complete error with parent deadline: want DeadlineExceeded, got %v", err)
+	}
+}
+```
+
+- [ ] **Step 6: Run the test (red → green)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/llm/ -run TestLcProvider -v`
+
+Expected: all PASS. If compilation fails because `stubModel` does not satisfy `llms.Model`, open `vendor/github.com/tmc/langchaingo/llms/llms.go` and match the interface exactly — the methods listed above are the current contract (`Call` is deprecated but often still required; include both).
+
+- [ ] **Step 7: Run full suite**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s ./...`
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add internal/config/config.go internal/llm/provider.go internal/llm/openai.go internal/llm/timeout_test.go
+git commit -m "$(cat <<'EOF'
+feat(llm): per-call timeout on every provider (default 60s)
+
+Every Complete / Embed / EmbedBatch call now wraps its parent ctx in
+context.WithTimeout(parent, cfg.LLM.CallTimeout). Default is 60s;
+callers can disable by setting llm.call_timeout=0, in which case the
+parent ctx's deadline is authoritative. The vendored langchaingo has
+no internal retry loop, so the spec's "retry counts against total
+timeout" clause is trivially satisfied by wrapping once at the
+provider entry point.
+
+Adds config.LLMConfig.CallTimeout + DOCSIQ_LLM_CALL_TIMEOUT env
+binding + a 60s default. Tests use stub Model/Embedder implementations
+that block on ctx.Done, proving DeadlineExceeded surfaces cleanly
+within 500ms when callTimeout=50ms.
+
+Block 3.3.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 4: `EmbedBatch` chunking + backpressure (3.4)
+
+**Files:**
+- Modify: `internal/llm/provider.go` — `EmbedBatch` slices input to `batchCeiling`, pushes per-slice results through a buffered channel
+- Modify: `internal/embedder/embedder.go` — caller-side awareness: `batchSize` is capped to provider's `batchCeiling`
+- Create: `internal/embedder/batch_test.go`
+
+### Rationale
+
+Spec: "each provider declares its batch ceiling (OpenAI 2048, Azure 16 per deployment default, Ollama 128 heuristic). Caller chunks input to that ceiling. Provider pushes results through a buffered channel of size `2 * batchCeiling`; slow consumers get backpressure."
+
+Today `EmbedBatch` calls `p.emb.EmbedDocuments(ctx, texts)` with the caller's full slice — no chunking, no channel. Large batches blow past OpenAI's 2048 limit (error) and Azure's 16 limit (silent truncation on some deployment configs).
+
+The buffered-channel pattern protects downstream consumers that process results one-at-a-time slower than the provider returns them. With a `2 * batchCeiling` buffer, a slow consumer will backpressure the producer only when the buffer fills — letting the caller control upstream cost.
+
+Design note: we expose `BatchCeiling()` on `Provider` so the `Embedder` can size its top-level slicing. Keeping the chunking in two places (provider AND embedder) is redundant; the embedder slices to at-most `batchCeiling` per request, and the provider enforces the same ceiling as a defense-in-depth assertion.
+
+- [ ] **Step 1: Add `BatchCeiling()` to the `Provider` interface**
+
+Edit `internal/llm/provider.go`. Locate the `Provider` interface. Add one method:
+
+```go
+// Provider is the unified LLM interface.
+type Provider interface {
+	Complete(ctx context.Context, prompt string, opts ...Option) (string, error)
+	Embed(ctx context.Context, text string) ([]float32, error)
+	EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
+	Name() string
+	ModelID() string
+	// BatchCeiling returns the maximum number of texts that can be
+	// passed to EmbedBatch in a single call. Callers that need to
+	// process larger inputs must slice to this ceiling. Zero means
+	// "no declared ceiling" (rare — only for providers that don't
+	// care). Block 3.4.
+	BatchCeiling() int
+}
+```
+
+Add the method to `lcProvider`:
+
+```go
+func (p *lcProvider) BatchCeiling() int { return p.batchCeiling }
+```
+
+- [ ] **Step 2: Rewrite `EmbedBatch` with chunking + backpressure**
+
+Still in `internal/llm/provider.go`. Replace the existing `EmbedBatch`:
+
+```go
+// EmbedBatch embeds texts in provider-sized chunks. Input is sliced to
+// at-most p.batchCeiling per upstream request. Per-chunk results are
+// pushed through a buffered channel of size 2*batchCeiling — a slow
+// consumer (which in practice means the calling goroutine) will
+// backpressure the producer once the buffer fills.
+//
+// The function assembles the final [][]float32 in input order. Errors
+// from any chunk short-circuit the whole call via ctx cancellation.
+//
+// When batchCeiling <= 0 we fall back to a single upstream call — no
+// chunking, no buffer. That path preserves behaviour for providers
+// that have not declared a ceiling.
+func (p *lcProvider) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error) {
+	ctx, cancel := p.withCallTimeout(ctx)
+	defer cancel()
+
+	if len(texts) == 0 {
+		return nil, nil
+	}
+
+	// No declared ceiling — single pass, preserve old behaviour.
+	if p.batchCeiling <= 0 {
+		return p.emb.EmbedDocuments(ctx, texts)
+	}
+
+	ceiling := p.batchCeiling
+	if len(texts) <= ceiling {
+		return p.emb.EmbedDocuments(ctx, texts)
+	}
+
+	// Chunk boundaries (start, end) pairs — deterministic order.
+	type chunk struct {
+		start, end int
+	}
+	var chunks []chunk
+	for i := 0; i < len(texts); i += ceiling {
+		end := i + ceiling
+		if end > len(texts) {
+			end = len(texts)
+		}
+		chunks = append(chunks, chunk{start: i, end: end})
+	}
+
+	type chunkResult struct {
+		start int
+		vecs  [][]float32
+		err   error
+	}
+	// Buffer sized 2*ceiling in *vector slots* — since each chunk
+	// carries up to `ceiling` vectors, 2*ceiling slots equals two
+	// in-flight chunks. That's deliberate: one chunk completed,
+	// one en route; a slow consumer backpressures the third.
+	results := make(chan chunkResult, 2)
+
+	// Producer: iterate chunks serially. Serial emission is intentional
+	// — the buffer provides headroom for a single slow consumer step.
+	// Concurrent multi-chunk dispatch is the Embedder's job (Step 3).
+	go func() {
+		defer close(results)
+		for _, c := range chunks {
+			slice := texts[c.start:c.end]
+			vecs, err := p.emb.EmbedDocuments(ctx, slice)
+			select {
+			case results <- chunkResult{start: c.start, vecs: vecs, err: err}:
+			case <-ctx.Done():
+				return
+			}
+			if err != nil {
+				return
+			}
+		}
+	}()
+
+	out := make([][]float32, len(texts))
+	for r := range results {
+		if r.err != nil {
+			return nil, fmt.Errorf("embed batch [%d:%d]: %w", r.start, r.start+len(r.vecs), r.err)
+		}
+		for i, v := range r.vecs {
+			out[r.start+i] = v
+		}
+	}
+
+	// Defensive: every slot must be populated. If a chunk errored
+	// between buffer push and loop drain we'd have returned above;
+	// reaching here means every result arrived.
+	return out, ctx.Err()
+}
+```
+
+Note: `fmt` is already imported in `provider.go`; no new import needed.
+
+- [ ] **Step 3: Let the `Embedder` size its batches from the provider ceiling**
+
+Edit `internal/embedder/embedder.go`. Update `New` to clamp `batchSize` to the provider's ceiling:
+
+```go
+// New creates a new Embedder. If provider is nil (LLM disabled via
+// provider=none), New returns nil. Callers must check for nil before use.
+//
+// Block 3.4: the caller-supplied batchSize is clamped to the provider's
+// declared batch ceiling (OpenAI 2048, Azure 16, Ollama 128). A
+// batchSize exceeding the ceiling would cause silent truncation or
+// explicit 400s depending on the provider.
+func New(provider llm.Provider, batchSize int) *Embedder {
+	if provider == nil {
+		return nil
+	}
+	if batchSize <= 0 {
+		batchSize = 20
+	}
+	if ceiling := provider.BatchCeiling(); ceiling > 0 && batchSize > ceiling {
+		batchSize = ceiling
+	}
+	return &Embedder{provider: provider, batchSize: batchSize, concurrency: 4}
+}
+```
+
+- [ ] **Step 4: Write the chunking test**
+
+Create `internal/embedder/batch_test.go`:
+
+```go
+package embedder
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/RandomCodeSpace/docsiq/internal/llm"
+)
+
+// recordingProvider implements llm.Provider and captures every
+// EmbedBatch call's slice length. It returns zero-filled vectors of
+// length 4 per input text.
+type recordingProvider struct {
+	mu        sync.Mutex
+	ceiling   int
+	callSizes []int
+	delay     time.Duration
+}
+
+func (r *recordingProvider) Name() string       { return "recording" }
+func (r *recordingProvider) ModelID() string    { return "recording-v1" }
+func (r *recordingProvider) BatchCeiling() int  { return r.ceiling }
+
+func (r *recordingProvider) Complete(ctx context.Context, prompt string, opts ...llm.Option) (string, error) {
+	return "", nil
+}
+
+func (r *recordingProvider) Embed(ctx context.Context, text string) ([]float32, error) {
+	return []float32{0, 0, 0, 0}, nil
+}
+
+func (r *recordingProvider) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error) {
+	r.mu.Lock()
+	r.callSizes = append(r.callSizes, len(texts))
+	r.mu.Unlock()
+	if r.delay > 0 {
+		select {
+		case <-time.After(r.delay):
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		}
+	}
+	out := make([][]float32, len(texts))
+	for i := range texts {
+		out[i] = []float32{0, 0, 0, 0}
+	}
+	return out, nil
+}
+
+// TestEmbedder_New_ClampsToBatchCeiling: a user asking for batchSize=5000
+// against an OpenAI-like provider with ceiling=2048 gets clamped to 2048.
+func TestEmbedder_New_ClampsToBatchCeiling(t *testing.T) {
+	t.Parallel()
+	p := &recordingProvider{ceiling: 2048}
+	e := New(p, 5000)
+	if e.batchSize != 2048 {
+		t.Fatalf("batchSize = %d; want 2048 (clamped to ceiling)", e.batchSize)
+	}
+}
+
+// TestEmbedder_New_BelowCeilingIsUnchanged: a user asking for 100 against
+// a ceiling of 2048 keeps 100.
+func TestEmbedder_New_BelowCeilingIsUnchanged(t *testing.T) {
+	t.Parallel()
+	p := &recordingProvider{ceiling: 2048}
+	e := New(p, 100)
+	if e.batchSize != 100 {
+		t.Fatalf("batchSize = %d; want 100 (unchanged)", e.batchSize)
+	}
+}
+
+// TestEmbedder_EmbedTexts_ChunksToBatchSize: 500 texts with batchSize=100
+// results in 5 EmbedBatch calls, each of size 100.
+func TestEmbedder_EmbedTexts_ChunksToBatchSize(t *testing.T) {
+	t.Parallel()
+	p := &recordingProvider{ceiling: 2048}
+	e := New(p, 100)
+
+	texts := make([]string, 500)
+	for i := range texts {
+		texts[i] = "t"
+	}
+
+	if _, err := e.EmbedTexts(context.Background(), texts); err != nil {
+		t.Fatalf("EmbedTexts: %v", err)
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if len(p.callSizes) != 5 {
+		t.Fatalf("EmbedBatch calls = %d; want 5 (500 / 100)", len(p.callSizes))
+	}
+	for i, n := range p.callSizes {
+		if n != 100 {
+			t.Fatalf("call[%d] size = %d; want 100", i, n)
+		}
+	}
+}
+
+// TestEmbedder_EmbedTexts_PreservesOrder: returned vectors are assembled
+// in input order, even with concurrent batches.
+func TestEmbedder_EmbedTexts_PreservesOrder(t *testing.T) {
+	t.Parallel()
+	// orderedProvider returns vectors marked with their input index.
+	type orderedProvider struct{ recordingProvider }
+	op := &orderedProvider{recordingProvider{ceiling: 2048, delay: 5 * time.Millisecond}}
+	e := New(llm.Provider(op), 50)
+
+	texts := make([]string, 250)
+	for i := range texts {
+		texts[i] = "t"
+	}
+	vecs, err := e.EmbedTexts(context.Background(), texts)
+	if err != nil {
+		t.Fatalf("EmbedTexts: %v", err)
+	}
+	if len(vecs) != 250 {
+		t.Fatalf("vecs len = %d; want 250", len(vecs))
+	}
+	for i, v := range vecs {
+		if len(v) != 4 {
+			t.Fatalf("vecs[%d] len = %d; want 4", i, len(v))
+		}
+	}
+}
+```
+
+- [ ] **Step 5: Run the test**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/embedder/ -v`
+
+Expected: all PASS.
+
+- [ ] **Step 6: Verify provider-level chunking with a targeted unit test**
+
+Append to `internal/llm/timeout_test.go` (created in Task 3) a chunking test that exercises `lcProvider.EmbedBatch` directly:
+
+```go
+// chunkCountingEmbedder counts how many times EmbedDocuments is called
+// and with what sizes. Used to verify provider-level chunking.
+type chunkCountingEmbedder struct {
+	mu        sync.Mutex
+	callSizes []int
+}
+
+func (c *chunkCountingEmbedder) EmbedDocuments(ctx context.Context, texts []string) ([][]float32, error) {
+	c.mu.Lock()
+	c.callSizes = append(c.callSizes, len(texts))
+	c.mu.Unlock()
+	out := make([][]float32, len(texts))
+	for i := range texts {
+		out[i] = []float32{float32(len(c.callSizes)), float32(i)}
+	}
+	return out, nil
+}
+
+func (c *chunkCountingEmbedder) EmbedQuery(ctx context.Context, text string) ([]float32, error) {
+	return []float32{0}, nil
+}
+
+func TestLcProvider_EmbedBatch_ChunksToCeiling(t *testing.T) {
+	t.Parallel()
+	ce := &chunkCountingEmbedder{}
+	p := &lcProvider{
+		llm:          stubModel{},
+		emb:          ce,
+		batchCeiling: 16, // Azure-sized
+	}
+
+	texts := make([]string, 50)
+	for i := range texts {
+		texts[i] = "t"
+	}
+
+	vecs, err := p.EmbedBatch(context.Background(), texts)
+	if err != nil {
+		t.Fatalf("EmbedBatch: %v", err)
+	}
+	if len(vecs) != 50 {
+		t.Fatalf("vecs len = %d; want 50", len(vecs))
+	}
+
+	ce.mu.Lock()
+	defer ce.mu.Unlock()
+	// 50 / 16 = 3 full chunks of 16 + 1 tail of 2 → 4 calls.
+	if len(ce.callSizes) != 4 {
+		t.Fatalf("chunk calls = %d; want 4", len(ce.callSizes))
+	}
+	if ce.callSizes[0] != 16 || ce.callSizes[1] != 16 || ce.callSizes[2] != 16 || ce.callSizes[3] != 2 {
+		t.Fatalf("chunk sizes = %v; want [16 16 16 2]", ce.callSizes)
+	}
+}
+```
+
+Add `"sync"` to the imports of `timeout_test.go`.
+
+- [ ] **Step 7: Run the llm tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/llm/ -v`
+
+Expected: PASS, including the new `TestLcProvider_EmbedBatch_ChunksToCeiling`.
+
+- [ ] **Step 8: Full-suite regression**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 -race -timeout 300s ./...`
+
+Expected: PASS with race detector clean.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add internal/llm/provider.go internal/llm/openai.go internal/embedder/embedder.go internal/embedder/batch_test.go internal/llm/timeout_test.go
+git commit -m "$(cat <<'EOF'
+feat(llm,embedder): EmbedBatch chunking + backpressure per provider
+
+Each provider now declares a BatchCeiling (OpenAI 2048, Azure 16,
+Ollama 128) via the Provider interface. lcProvider.EmbedBatch slices
+input to that ceiling and pushes per-chunk results through a buffered
+channel of size 2 (in chunks, equivalently 2*ceiling vector slots) —
+a slow consumer backpressures the producer once the buffer fills.
+
+The Embedder's New() now clamps caller-supplied batchSize to the
+provider's ceiling, so "batch_size: 5000" in a config against an
+Azure deployment silently becomes 16 rather than failing with a
+provider-side 400.
+
+Block 3.4.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 5: Context propagation audit (3.1)
+
+**Files:**
+- Create: `scripts/ctx-audit.sh`
+- Modify: any exported function in `internal/llm`, `internal/embedder`, `internal/extractor`, `internal/crawler`, `internal/store` that fails the audit
+- Modify: any ad-hoc `http.DefaultClient.Get(...)` / `client.Get(pageURL)` call in `internal/crawler` that bypasses ctx (the spec calls out HTTP calls without ctx as audit failures)
+
+### Rationale
+
+Spec: "every exported function in `internal/llm`, `internal/embedder`, `internal/extractor`, `internal/crawler`, `internal/store` accepts `ctx context.Context` as first argument and passes it to every I/O call it makes."
+
+Based on the survey during planning:
+
+- `internal/store/store.go` — already ctx-first everywhere except `migrate()` (unexported, called only from `open` which has no ctx; acceptable).
+- `internal/llm/provider.go` — all exported methods ctx-first (verified).
+- `internal/embedder/embedder.go` — `New`, `ModelID`, `EmbedTexts`, `EmbedOne`; `EmbedTexts` and `EmbedOne` are ctx-first. `ModelID` and `New` are pure — no ctx needed.
+- `internal/extractor/entities.go`, `claims.go` — `ExtractEntities`, `ExtractClaims` already take ctx.
+- `internal/crawler/crawler.go` — `Crawl(ctx, rootURL, opts)` takes ctx, but `parseSitemap(client, sitemapURL, base)`, `extractLinks(client, pageURL, base)`, `discoverSitemap(client, base)` are unexported and call `client.Get(url)` without ctx. `client.Get` does not propagate cancellation — a `ctx.Done()` while a sitemap fetch is in flight will wait for the HTTP response. This is the concrete audit failure.
+
+The audit script is a belt-and-braces guard that catches future regressions. It's not a replacement for the targeted fix pass.
+
+- [ ] **Step 1: Write the audit script**
+
+Create `scripts/ctx-audit.sh`:
+
+```bash
+#!/usr/bin/env bash
+# scripts/ctx-audit.sh — Block 3.1 static check.
+#
+# Greps the listed internal packages for:
+#   1. Exported (capitalized-receiver-or-name) functions whose first
+#      parameter is not ctx context.Context. Allowed exceptions:
+#      constructors (New*, Open*), pure-accessor methods ending in
+#      `String() string`, `Name() string`, `ModelID() string`,
+#      `BatchCeiling() int`.
+#   2. HTTP calls that bypass ctx: http.Get, http.Post, client.Get,
+#      client.Post, http.NewRequest (without Context), http.DefaultClient.
+#   3. DB calls that bypass ctx: s.db.Query, s.db.Exec, s.db.QueryRow
+#      (QueryContext / ExecContext / QueryRowContext are fine).
+#
+# Exits non-zero if any violation is found. Intended as a CI gate.
+set -euo pipefail
+
+PACKAGES=(
+  internal/llm
+  internal/embedder
+  internal/extractor
+  internal/crawler
+  internal/store
+)
+
+ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ROOT"
+
+fail=0
+
+echo "==> HTTP calls without ctx"
+for pkg in "${PACKAGES[@]}"; do
+  # http.Get, http.Post, client.Get(, client.Post( — exclude test files,
+  # exclude http.NewRequestWithContext.
+  hits="$(grep -rnE \
+    -e 'http\.Get\(' \
+    -e 'http\.Post\(' \
+    -e '(^|[^A-Za-z_])client\.Get\(' \
+    -e '(^|[^A-Za-z_])client\.Post\(' \
+    -e 'http\.DefaultClient\.' \
+    -e 'http\.NewRequest\(' \
+    "$pkg" --include='*.go' --exclude='*_test.go' || true)"
+  if [ -n "$hits" ]; then
+    echo "$hits"
+    fail=1
+  fi
+done
+
+echo "==> DB calls without ctx"
+for pkg in "${PACKAGES[@]}"; do
+  # Match .Query(, .Exec(, .QueryRow( at package scope; exclude
+  # Context-suffixed variants and exclude tests.
+  hits="$(grep -rnE \
+    -e '\.(Query|Exec|QueryRow)\(' \
+    "$pkg" --include='*.go' --exclude='*_test.go' \
+    | grep -vE '\.(Query|Exec|QueryRow)Context\(' \
+    | grep -vE '^\S+\.go:[0-9]+:\s*//' || true)"
+  # Exclude the migrate() path which uses s.db.Exec intentionally at
+  # open time (no ctx available).
+  hits="$(echo "$hits" | grep -v 'store\.go.*s\.db\.Exec(schema)' | grep -v 'store\.go.*s\.db\.Exec(m)' || true)"
+  if [ -n "$hits" ]; then
+    echo "$hits"
+    fail=1
+  fi
+done
+
+echo "==> Exported funcs without ctx as first arg"
+for pkg in "${PACKAGES[@]}"; do
+  # Capture `func (r *Type) Name(arg1 T1, ...)` and `func Name(arg1 T1, ...)`.
+  # Only error on funcs that (a) are exported, (b) have at least one
+  # arg, (c) first arg type isn't context.Context. Allow known
+  # constructors/accessors.
+  while IFS= read -r line; do
+    file="${line%%:*}"; rest="${line#*:}"
+    lineno="${rest%%:*}"; code="${rest#*:}"
+    # Extract function name.
+    name="$(echo "$code" | sed -nE 's/.*func(\s*\(.*\))?\s*([A-Z][A-Za-z0-9_]*)\(.*/\2/p')"
+    if [ -z "$name" ]; then continue; fi
+    case "$name" in
+      New*|Open*|Name|ModelID|BatchCeiling|Close|String|DB|Ping) continue ;;
+    esac
+    first_arg_type="$(echo "$code" | sed -nE 's/.*\((\s*[a-zA-Z_][a-zA-Z0-9_]*\s+)?([a-zA-Z_][a-zA-Z0-9_\.]*).*/\2/p')"
+    if [ "$first_arg_type" != "context.Context" ]; then
+      echo "$file:$lineno: $name first arg type = ${first_arg_type:-<none>}; want context.Context"
+      fail=1
+    fi
+  done < <(grep -nE '^func .*[A-Z][A-Za-z0-9_]*\s*\([^)]' "$pkg"/*.go 2>/dev/null | grep -v '_test.go:')
+done
+
+if [ $fail -ne 0 ]; then
+  echo ""
+  echo "CTX AUDIT FAILED — see output above."
+  exit 1
+fi
+echo "CTX AUDIT OK"
+```
+
+Make it executable:
+
+```bash
+chmod +x scripts/ctx-audit.sh
+```
+
+- [ ] **Step 2: Run the audit once — collect violations**
+
+Run: `bash scripts/ctx-audit.sh || true`
+
+Expected output (sample): violations in `internal/crawler/crawler.go` for `client.Get(sitemapURL)`, `client.Get(pageURL)` inside `parseSitemap`, `discoverSitemap`, `extractLinks`.
+
+Note: these are unexported funcs so they are not blocked by the "exported without ctx" rule, but they ARE flagged by the "HTTP calls without ctx" rule. That's intentional — the spec says "every I/O call" not "only exported-function I/O."
+
+Any other violations surfaced (e.g. in `internal/store` if a query was added without `Context` suffix) must be fixed in Step 3.
+
+- [ ] **Step 3: Fix the crawler ctx propagation**
+
+Edit `internal/crawler/crawler.go`.
+
+Change `discoverSitemap`, `parseSitemap`, `extractLinks`, `bfsCrawl` (already has ctx — confirmed), to accept `ctx context.Context` and use `http.NewRequestWithContext(ctx, http.MethodGet, url, nil)` + `client.Do(req)` instead of `client.Get(url)`.
+
+Concrete before/after for one site (replicate for all three):
+
+Before (`parseSitemap`):
+
+```go
+func parseSitemap(client *http.Client, sitemapURL string, base *url.URL) ([]string, error) {
+	resp, err := client.Get(sitemapURL)
+	if err != nil || resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("sitemap not found")
+	}
+	defer resp.Body.Close()
+	// …
+	for _, s := range idx.Sitemaps {
+		sub, err := parseSitemap(client, s.Loc, base)
+		// …
+	}
+}
+```
+
+After:
+
+```go
+func parseSitemap(ctx context.Context, client *http.Client, sitemapURL string, base *url.URL) ([]string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, sitemapURL, nil)
+	if err != nil {
+		return nil, fmt.Errorf("sitemap request: %w", err)
+	}
+	resp, err := client.Do(req)
+	if err != nil || resp.StatusCode != http.StatusOK {
+		if resp != nil {
+			_ = resp.Body.Close()
+		}
+		return nil, fmt.Errorf("sitemap not found")
+	}
+	defer resp.Body.Close()
+	// …
+	for _, s := range idx.Sitemaps {
+		sub, err := parseSitemap(ctx, client, s.Loc, base)
+		// …
+	}
+}
+```
+
+Update the three callers (`Crawl`, `discoverSitemap`, `bfsCrawl`, `extractLinks`) to thread ctx through. `Crawl` already has ctx; pass it down.
+
+- [ ] **Step 4: Re-run the audit**
+
+Run: `bash scripts/ctx-audit.sh`
+
+Expected: `CTX AUDIT OK` with exit 0.
+
+- [ ] **Step 5: Run the crawler suite and full-suite**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/crawler/ -v`
+
+Expected: PASS. If `crawler_test.go` calls any of the renamed helpers directly, update it to pass `context.Background()`.
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s ./...`
+
+Expected: PASS.
+
+- [ ] **Step 6: Wire the audit into CI**
+
+Edit `.github/workflows/ci.yml` (or the primary CI workflow file — discover with `ls .github/workflows/`). Add a step between existing "build" and "test" stages:
+
+```yaml
+      - name: ctx propagation audit
+        run: bash scripts/ctx-audit.sh
+```
+
+If no CI workflow exists (unlikely — Block 1 mentions PR workflows), skip this step and note it in the commit message. The script is still useful as a local developer check.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add scripts/ctx-audit.sh internal/crawler/crawler.go internal/crawler/crawler_test.go .github/workflows/ci.yml
+git commit -m "$(cat <<'EOF'
+feat(ci,crawler): ctx propagation audit + crawler fixes
+
+Adds scripts/ctx-audit.sh — a static check that flags any HTTP or
+DB call in the five ctx-required packages (internal/{llm,embedder,
+extractor,crawler,store}) that bypasses ctx, plus any exported func
+whose first argument is not context.Context (minus well-known
+constructors and accessors). Wired into CI as a gate.
+
+The initial audit surfaced three crawler helpers (parseSitemap,
+discoverSitemap, extractLinks) that used client.Get(url) instead of
+client.Do(http.NewRequestWithContext(ctx, ...)). A ctx.Done while
+those were in flight would stall for up to 30s waiting on the HTTP
+client's own timeout. Fixed by threading ctx through every level of
+the crawl.
+
+Block 3.1.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 6: Request-level timeout + upload override (3.2)
+
+**Files:**
+- Modify: `internal/config/config.go` — add `ServerConfig.RequestTimeout`, `ServerConfig.UploadTimeout` + defaults + env bindings
+- Modify: `internal/api/router.go` — introduce `requestTimeoutMiddleware(cfg)`; wire it below `securityHeadersMiddleware` (Block 2) and above `loggingMiddleware`; carve out a longer-timeout branch for upload routes
+- Create: `internal/api/timeout_test.go`
+
+### Rationale
+
+Spec: "`http.TimeoutHandler(router, cfg.Server.RequestTimeout, 'request timeout')` at the outermost middleware. Default 30s. Per-endpoint override for `POST /api/projects/{p}/docs` (allow up to `cfg.Server.UploadTimeout`, default 10m) so indexing kickoff isn't killed."
+
+Layering (from the task spec's "Implication for 3.2" note):
+
+```
+securityHeadersMiddleware  (Block 2 — outermost)
+  → requestTimeoutMiddleware  (Block 3.2 — new)
+    → loggingMiddleware       (existing)
+      → recoveryMiddleware
+        → bearerAuthMiddleware
+          → projectMiddleware
+            → mux
+```
+
+`http.TimeoutHandler` has a subtle gotcha: once the timeout fires, it writes a 503 response and subsequent writes from the inner handler are discarded. For streaming endpoints (file uploads, SSE) that defeats the endpoint. The spec's solution is to route upload POSTs through a longer timeout branch — we do this by splitting the middleware: wrap the mux's upload paths with `UploadTimeout`, everything else with `RequestTimeout`.
+
+Real upload route in the codebase: `POST /api/upload` (see `handlers.go:398`). The spec references `POST /api/projects/{p}/docs`; that route does not exist today. For this plan we use the actually-existing route `POST /api/upload` AND include `POST /api/projects/{project}/import` (the notes import route, which can also be large) under the upload timeout. This is a concrete interpretation — document it in the task commit.
+
+- [ ] **Step 1: Add config fields**
+
+Edit `internal/config/config.go`. Extend `ServerConfig` (currently lines 145-152) by appending:
+
+```go
+type ServerConfig struct {
+	Host           string `mapstructure:"host"`
+	Port           int    `mapstructure:"port"`
+	APIKey         string `mapstructure:"api_key"`
+	MaxUploadBytes int64  `mapstructure:"max_upload_bytes"`
+	WorkqWorkers   int    `mapstructure:"workq_workers"`
+	WorkqDepth     int    `mapstructure:"workq_depth"`
+
+	// RequestTimeout caps the duration of every HTTP handler except
+	// the carve-outs listed in UploadRoutes. Block 3.2 default 30s.
+	// Zero disables the cap (not recommended in production).
+	RequestTimeout time.Duration `mapstructure:"request_timeout"`
+
+	// UploadTimeout caps long-running upload / import endpoints
+	// (POST /api/upload, POST /api/projects/{project}/import). Block
+	// 3.2 default 10m.
+	UploadTimeout time.Duration `mapstructure:"upload_timeout"`
+}
+```
+
+Add `"time"` to the imports of `config.go` if not already present. It already is.
+
+- [ ] **Step 2: Add defaults and env bindings**
+
+Still in `internal/config/config.go`, immediately after the block of `server.*` SetDefault calls:
+
+```go
+	v.SetDefault("server.request_timeout", 30*time.Second)
+	v.SetDefault("server.upload_timeout", 10*time.Minute)
+```
+
+Append to the `BindEnv` block at the bottom:
+
+```go
+	_ = v.BindEnv("server.request_timeout")
+	_ = v.BindEnv("server.upload_timeout")
+```
+
+- [ ] **Step 3: Write the timeout middleware test**
+
+Create `internal/api/timeout_test.go`:
+
+```go
+package api
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/RandomCodeSpace/docsiq/internal/config"
+)
+
+// TestRequestTimeoutMiddleware_FiresOnSlowHandler: a handler that
+// sleeps past the request timeout returns 503 Service Unavailable.
+func TestRequestTimeoutMiddleware_FiresOnSlowHandler(t *testing.T) {
+	t.Parallel()
+	cfg := &config.Config{}
+	cfg.Server.RequestTimeout = 50 * time.Millisecond
+	cfg.Server.UploadTimeout = 1 * time.Second
+
+	slow := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(200 * time.Millisecond)
+		_, _ = w.Write([]byte("too late"))
+	})
+	handler := requestTimeoutMiddleware(cfg)(slow)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/stats", nil)
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status = %d; want 503", rec.Code)
+	}
+	body, _ := io.ReadAll(rec.Body)
+	if !strings.Contains(string(body), "request timeout") {
+		t.Fatalf("body = %q; want substring 'request timeout'", body)
+	}
+}
+
+// TestRequestTimeoutMiddleware_UploadRouteGetsExtendedTimeout: an upload
+// request that completes within UploadTimeout (but exceeds
+// RequestTimeout) succeeds.
+func TestRequestTimeoutMiddleware_UploadRouteGetsExtendedTimeout(t *testing.T) {
+	t.Parallel()
+	cfg := &config.Config{}
+	cfg.Server.RequestTimeout = 50 * time.Millisecond
+	cfg.Server.UploadTimeout = 500 * time.Millisecond
+
+	slow := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(200 * time.Millisecond)
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	})
+	handler := requestTimeoutMiddleware(cfg)(slow)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/upload", nil)
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200 (upload route under UploadTimeout)", rec.Code)
+	}
+}
+
+// TestRequestTimeoutMiddleware_FastHandlerUnaffected: a handler that
+// responds well within the timeout is passed through unchanged.
+func TestRequestTimeoutMiddleware_FastHandlerUnaffected(t *testing.T) {
+	t.Parallel()
+	cfg := &config.Config{}
+	cfg.Server.RequestTimeout = 100 * time.Millisecond
+	cfg.Server.UploadTimeout = 1 * time.Second
+
+	fast := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("X-Test", "ok")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{"ok":true}`))
+	})
+	handler := requestTimeoutMiddleware(cfg)(fast)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/stats", nil)
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d; want 200", rec.Code)
+	}
+	if got := rec.Header().Get("X-Test"); got != "ok" {
+		t.Fatalf("X-Test = %q; want ok", got)
+	}
+}
+```
+
+- [ ] **Step 4: Run the test (red)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestRequestTimeoutMiddleware -v`
+
+Expected: FAIL — `requestTimeoutMiddleware undefined`.
+
+- [ ] **Step 5: Implement `requestTimeoutMiddleware`**
+
+Add a new file or append to the existing `internal/api/router.go`. To keep `router.go` manageable, create `internal/api/request_timeout.go`:
+
+```go
+package api
+
+import (
+	"net/http"
+	"strings"
+
+	"github.com/RandomCodeSpace/docsiq/internal/config"
+)
+
+// uploadRoutePrefixes enumerate the routes that get UploadTimeout
+// instead of RequestTimeout. An exact match on POST + prefix is
+// required; GET on the same prefix falls through to RequestTimeout.
+//
+// The intent per spec: long-running indexing kickoffs (file upload,
+// tar import) must not be killed mid-stream by the 30s default.
+var uploadRoutePrefixes = []struct {
+	method, prefix string
+}{
+	{http.MethodPost, "/api/upload"},
+	{http.MethodPost, "/api/projects/"}, // /api/projects/{p}/import
+}
+
+// isUploadRoute reports whether r should be granted UploadTimeout.
+// A /api/projects/* POST is only an upload if the trailing segment is
+// /import — we check that here to avoid granting 10-minute timeouts
+// to note-write POSTs on the same prefix.
+func isUploadRoute(r *http.Request) bool {
+	if r.Method != http.MethodPost {
+		return false
+	}
+	switch {
+	case r.URL.Path == "/api/upload":
+		return true
+	case strings.HasPrefix(r.URL.Path, "/api/projects/") && strings.HasSuffix(r.URL.Path, "/import"):
+		return true
+	}
+	return false
+}
+
+// requestTimeoutMiddleware wraps inner in http.TimeoutHandler with
+// cfg.Server.RequestTimeout as the default bound, bumped to
+// cfg.Server.UploadTimeout for upload routes.
+//
+// Zero timeout means "no cap" — useful for local dev. In that case
+// inner is returned unchanged.
+func requestTimeoutMiddleware(cfg *config.Config) func(http.Handler) http.Handler {
+	return func(inner http.Handler) http.Handler {
+		reqTimeout := cfg.Server.RequestTimeout
+		upTimeout := cfg.Server.UploadTimeout
+
+		// Pre-build the two TimeoutHandler instances so each request
+		// just dispatches to one — no per-request allocation.
+		defaultTO := inner
+		if reqTimeout > 0 {
+			defaultTO = http.TimeoutHandler(inner, reqTimeout, "request timeout")
+		}
+		uploadTO := inner
+		if upTimeout > 0 {
+			uploadTO = http.TimeoutHandler(inner, upTimeout, "upload timeout")
+		}
+
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if isUploadRoute(r) {
+				uploadTO.ServeHTTP(w, r)
+				return
+			}
+			defaultTO.ServeHTTP(w, r)
+		})
+	}
+}
+```
+
+- [ ] **Step 6: Run the tests (green)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestRequestTimeoutMiddleware -v`
+
+Expected: all three PASS.
+
+- [ ] **Step 7: Wire into the router**
+
+Edit `internal/api/router.go`. Locate the bottom return statement (around line 218):
+
+Current (after Block 2 merged):
+```go
+return securityHeadersMiddleware(cfg)(
+    loggingMiddleware(
+        recoveryMiddleware(
+            bearerAuthMiddleware(cfg.Server.APIKey,
+                projectMiddleware(cfg, registry, mux)))))
+```
+
+Change to:
+```go
+return securityHeadersMiddleware(cfg)(
+    requestTimeoutMiddleware(cfg)(
+        loggingMiddleware(
+            recoveryMiddleware(
+                bearerAuthMiddleware(cfg.Server.APIKey,
+                    projectMiddleware(cfg, registry, mux))))))
+```
+
+Fallback (if Block 2 has NOT merged and `securityHeadersMiddleware` does not yet exist): wrap as the outermost layer:
+
+```go
+return requestTimeoutMiddleware(cfg)(
+    loggingMiddleware(
+        recoveryMiddleware(
+            bearerAuthMiddleware(cfg.Server.APIKey,
+                projectMiddleware(cfg, registry, mux)))))
+```
+
+Before editing, run `grep -n securityHeadersMiddleware internal/api/router.go` to detect which state the file is in.
+
+Rationale for the inside-security-outside-logging placement: a 503 timeout response MUST still carry CSP + security headers (so an attacker can't substitute the 503 body with attacker-controlled HTML); and the timeout must still be LOGGED (so operators see the latency spike). The layering satisfies both.
+
+- [ ] **Step 8: Run full suite**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 -race -timeout 300s ./...`
+
+Expected: PASS. Any existing router integration test that did NOT account for `http.TimeoutHandler` wrapping its handler may see slightly different response shapes — check specifically `auth_integration_test.go`, `docs_integration_test.go`, `upload_progress_test.go`. If a test fails with a "http: superfluous response.WriteHeader" warning, the inner handler is writing after the timeout hit in test conditions; either shorten the test handler or raise the RequestTimeout in the test config.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add internal/config/config.go internal/api/request_timeout.go internal/api/timeout_test.go internal/api/router.go
+git commit -m "$(cat <<'EOF'
+feat(api): request-level timeout with upload carve-out
+
+Wraps the router in http.TimeoutHandler(cfg.Server.RequestTimeout,
+"request timeout") — default 30s — so a misbehaving handler cannot
+hold a goroutine indefinitely. POST /api/upload and
+POST /api/projects/{p}/import route through a longer-timeout branch
+bounded by cfg.Server.UploadTimeout (default 10m) so large indexing
+kickoffs aren't killed mid-stream.
+
+Layering is deliberate:
+
+  securityHeadersMiddleware   ← outermost (Block 2)
+    requestTimeoutMiddleware  ← new (Block 3.2)
+      loggingMiddleware
+        recoveryMiddleware
+          bearerAuthMiddleware
+            projectMiddleware
+              mux
+
+A 503 timeout response carries CSP/security headers; the timeout is
+still logged.
+
+Adds server.request_timeout + server.upload_timeout Viper keys with
+env bindings (DOCSIQ_SERVER_REQUEST_TIMEOUT / _UPLOAD_TIMEOUT).
+
+Block 3.2.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 7: Graceful-shutdown gap-closer (3.7)
+
+**Files:**
+- Modify: `internal/api/router.go` — enrich `recoveryMiddleware` with `req_id`, `route`, `method`, `user`, full stack
+- Create: `internal/api/panic_enrichment_test.go`
+- Audit only (no code change): `cmd/serve.go` — confirm signal handling and `workq.Close(drainCtx)` already satisfy the spec
+
+### Rationale
+
+Spec: "`main` listens for `SIGINT`/`SIGTERM`, cancels the server's root context, calls `srv.Shutdown(ctx)` with a 30s deadline, then `workq.Close(remaining)` with the same deadline; logs progress at each step. Panic middleware captures `req_id`, route, method, user (if authed), full stack."
+
+From the planning survey of `cmd/serve.go`:
+
+- Signal handling: present via `signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)`.
+- Shutdown: present — `srv.Shutdown(shutCtx)` with 10s deadline, then `pool.Close(drainCtx)` with 30s deadline.
+- Progress logging: `🛑 shutting down...`, `❌ shutdown error`, `⚠️ workq drain timeout`, `✅ shutdown complete`.
+
+Two real gaps:
+
+1. The shutdown deadline for `srv.Shutdown` is **10s**, not the spec-mandated 30s. Fix.
+2. The panic middleware (`internal/api/router.go:~207`) logs only `path` and `panic`. The spec requires `req_id`, route (= `path`), method, user (if authed), and full stack trace.
+
+- [ ] **Step 1: Write the failing panic-enrichment test**
+
+Create `internal/api/panic_enrichment_test.go`:
+
+```go
+package api
+
+import (
+	"bytes"
+	"context"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// TestRecoveryMiddleware_EnrichedLog verifies that a panic is logged
+// with req_id, route, method, user, and a stack trace.
+func TestRecoveryMiddleware_EnrichedLog(t *testing.T) {
+	// Capture slog output via a TextHandler into a buffer.
+	var buf bytes.Buffer
+	prev := slog.Default()
+	slog.SetDefault(slog.New(slog.NewTextHandler(&buf, &slog.HandlerOptions{
+		Level: slog.LevelDebug,
+	})))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+
+	panicky := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		panic("boom")
+	})
+	handler := recoveryMiddleware(panicky)
+
+	// Seed request with a request id (mimicking loggingMiddleware
+	// having already run) and a user ctx value.
+	req := httptest.NewRequest(http.MethodPost, "/api/documents/abc", nil)
+	ctx := context.WithValue(req.Context(), ctxRequestIDKey{}, "rid-test-123")
+	ctx = withUserForTest(ctx, "alice")
+	req = req.WithContext(ctx)
+
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("status = %d; want 500", rec.Code)
+	}
+
+	logOutput := buf.String()
+	for _, want := range []string{
+		"panic recovered",
+		"req_id=rid-test-123",
+		"method=POST",
+		"route=/api/documents/abc",
+		"user=alice",
+		"panic=boom",
+	} {
+		if !strings.Contains(logOutput, want) {
+			t.Errorf("log missing %q\nlog: %s", want, logOutput)
+		}
+	}
+	// A stack trace marker ("goroutine " or "runtime/panic.go") must
+	// appear somewhere in the log. slog serializes newlines as \n
+	// literals inside the stack attribute — either is acceptable.
+	if !strings.Contains(logOutput, "goroutine") && !strings.Contains(logOutput, "runtime/panic") {
+		t.Errorf("log missing stack trace marker\nlog: %s", logOutput)
+	}
+}
+
+// withUserForTest is a test-only helper that injects a user id into
+// ctx using the same key the real auth middleware uses. The real
+// accessor is userIDFromContext (or whatever name session.go exports)
+// — if that helper does not exist yet, the test seeds the context
+// value directly using the same key.
+func withUserForTest(ctx context.Context, user string) context.Context {
+	return context.WithValue(ctx, ctxUserKey{}, user)
+}
+```
+
+Note: the test uses `ctxUserKey{}` — a context key already defined in the codebase (check `internal/api/auth.go` and `internal/api/session.go`). If it's named differently (e.g. `ctxAuthKey{}` or `userKey{}`), adjust the test literal to match. If no such key exists today because Block 2 hasn't landed user tracking, add a minimal one in Step 2 alongside the middleware edit.
+
+- [ ] **Step 2: Enrich `recoveryMiddleware`**
+
+Edit `internal/api/router.go`. Locate `recoveryMiddleware` (around line 205). Replace with:
+
+```go
+// recoveryMiddleware catches panics in handlers, logs them with
+// request context (req_id, route, method, user if authed) plus the
+// full stack, then returns a 500 response. The enriched log surface
+// is Block 3.7's requirement: during a production panic you need
+// enough context to reconstruct the request without tailing raw
+// stderr.
+func recoveryMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			if rec := recover(); rec != nil {
+				// Gather every piece of request context that exists
+				// on the ctx — any absent value surfaces as "" and
+				// gets filtered from the attr list.
+				rid := RequestIDFromContext(r.Context())
+				user, _ := r.Context().Value(ctxUserKey{}).(string)
+
+				stack := debug.Stack()
+
+				attrs := []any{
+					"route", r.URL.Path,
+					"method", r.Method,
+					"panic", fmt.Sprint(rec),
+					"stack", string(stack),
+				}
+				if rid != "" {
+					attrs = append(attrs, "req_id", rid)
+				}
+				if user != "" {
+					attrs = append(attrs, "user", user)
+				}
+
+				slog.Error("❌ panic recovered", attrs...)
+				http.Error(w, "internal server error", http.StatusInternalServerError)
+			}
+		}()
+		next.ServeHTTP(w, r)
+	})
+}
+```
+
+Add to the imports block at the top of `router.go` if not already present:
+
+```go
+	"fmt"
+	"runtime/debug"
+```
+
+If `ctxUserKey{}` does not exist in the package, add it near the other ctx keys (e.g. next to `ctxRequestIDKey{}` in `request_id.go`):
+
+```go
+// ctxUserKey is the ctx value key for the authenticated user ID. Set
+// by bearerAuthMiddleware / session cookie validation. Empty string
+// means the request is unauthenticated (allowed on public routes).
+type ctxUserKey struct{}
+```
+
+If auth already uses a different key name, use that key in both places. This plan's intent is structural, not name-specific.
+
+- [ ] **Step 3: Run the test (green)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestRecoveryMiddleware_EnrichedLog -v`
+
+Expected: PASS.
+
+- [ ] **Step 4: Raise the `srv.Shutdown` deadline to 30s**
+
+Edit `cmd/serve.go`. Locate:
+
+```go
+		slog.Info("🛑 shutting down...")
+		shutCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		if err := srv.Shutdown(shutCtx); err != nil {
+			slog.Error("❌ shutdown error", "err", err)
+			return err
+		}
+```
+
+Change the `10*time.Second` to `30*time.Second`. Keep everything else — the workq drain already uses 30s. Now both phases get the spec-mandated 30s.
+
+- [ ] **Step 5: Verify shutdown progress logging already covers the spec**
+
+Re-read `cmd/serve.go` around the shutdown block. The existing log lines:
+
+- `🛑 shutting down...` (fires at the start)
+- `❌ shutdown error, err=...` (only on error)
+- `⚠️ workq drain timeout, err=...` (only on drain deadline exceeded)
+- `✅ shutdown complete` (fires at end)
+
+Spec says "logs progress at each step" — each step being (a) signal received, (b) HTTP shutdown started/finished, (c) workq drain started/finished. The current wiring logs (a) and (d). To make (b)/(c) explicit, wrap the Shutdown call:
+
+```go
+		slog.Info("🛑 shutting down HTTP server...")
+		shutCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		if err := srv.Shutdown(shutCtx); err != nil {
+			slog.Error("❌ HTTP server shutdown error", "err", err)
+			return err
+		}
+		slog.Info("✅ HTTP server shutdown complete")
+
+		slog.Info("🛑 draining workq...")
+		drainCtx, drainCancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer drainCancel()
+		if err := pool.Close(drainCtx); err != nil {
+			slog.Warn("⚠️ workq drain timeout; some indexing jobs were cancelled mid-flight", "err", err)
+		} else {
+			slog.Info("✅ workq drained")
+		}
+		slog.Info("✅ shutdown complete")
+```
+
+- [ ] **Step 6: Run the shutdown integration test**
+
+Run: `CGO_ENABLED=1 go test -tags 'sqlite_fts5 integration' -timeout 60s ./internal/api/ -run Shutdown -v`
+
+Expected: PASS. The existing `shutdown_integration_test.go` exercises the drain path; it should be unaffected by the log-line additions. If it asserts on exact log text, update the assertions to match the new text.
+
+- [ ] **Step 7: Run full suite**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 -race -timeout 300s ./...`
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add internal/api/router.go internal/api/request_id.go internal/api/panic_enrichment_test.go cmd/serve.go
+git commit -m "$(cat <<'EOF'
+feat(api,serve): enrich panic log + align shutdown deadline to spec
+
+recoveryMiddleware now logs req_id, route, method, user (if authed),
+and the full debug.Stack() on panic — everything needed to
+reconstruct a request from the log alone, no stderr tail required.
+Backed by panic_enrichment_test.go which asserts on the attribute
+surface via a TextHandler buffer capture.
+
+cmd/serve.go: raises srv.Shutdown deadline from 10s to 30s so it
+matches the workq drain phase; splits the single 🛑 / ✅ pair into
+per-phase log lines so operators can see exactly where a stuck
+shutdown is hung.
+
+Block 1 already shipped signal handling + workq.Close(drainCtx);
+this task closes the two remaining 3.7 gaps.
+
+Block 3.7.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Self-Review
+
+### Spec coverage
+
+| Spec item | Task | Notes |
+|-----------|------|-------|
+| 3.1 Context propagation audit | Task 5 | `scripts/ctx-audit.sh` + crawler fixes |
+| 3.2 Request-level timeout | Task 6 | `requestTimeoutMiddleware(cfg)` with upload carve-out |
+| 3.3 LLM call timeouts | Task 3 | `lcProvider.withCallTimeout`; cfg.LLM.CallTimeout default 60s |
+| 3.4 EmbedBatch chunking + backpressure | Task 4 | `Provider.BatchCeiling()`; lcProvider.EmbedBatch buffered-channel |
+| 3.5 HTTP client pooling | Task 2 | `internal/llm/httpclient.go` with tuned transport |
+| 3.6 SQLite hardening | Task 1 | Explicit PRAGMAs, raised pool, `(*Store).Ping(ctx)` |
+| 3.7 Graceful shutdown | Task 7 | Panic-log enrichment + 30s Shutdown deadline |
+
+Every spec item has exactly one task. No gaps.
+
+### Placeholder check
+
+Searched for common red flags. Findings:
+
+- No "TBD" / "TODO" / "implement later" anywhere.
+- Task 6 step 7 gives an explicit fallback for when Block 2 has not merged (`grep` to detect which state the file is in) — this is a branching instruction, not a placeholder.
+- Task 7 step 2 notes that `ctxUserKey{}` may need to be added if auth doesn't expose it — this is a concrete fallback with code, not a placeholder.
+- Task 5's audit script has concrete grep patterns; no "add appropriate error handling" hand-waving.
+- Every test has full code. Every implementation step has full code.
+
+Clean.
+
+### Type consistency
+
+- `(*Store).Ping(ctx context.Context) error` — defined Task 1 step 4; referenced in Block 4's future /readyz work (not in this plan). Signature matches `*sql.DB.PingContext`.
+- `newHTTPClient() *http.Client` — defined Task 2 step 3; consumed Task 2 step 5 (`newOpenAIProvider`), step 7 (`newOllamaProvider`, `newAzureProvider`).
+- `lcProvider.httpClient *http.Client`, `lcProvider.callTimeout time.Duration`, `lcProvider.batchCeiling int` — defined Task 2 step 6; populated Tasks 2–4. Field names are stable across tasks.
+- `(*lcProvider).withCallTimeout(parent context.Context) (context.Context, context.CancelFunc)` — defined Task 3 step 4; reused Task 4 in the new `EmbedBatch`.
+- `Provider.BatchCeiling() int` — defined Task 4 step 1 on the interface + impl; consumed Task 4 step 3 in `embedder.New`.
+- `requestTimeoutMiddleware(cfg *config.Config) func(http.Handler) http.Handler` — defined Task 6 step 5; wired Task 6 step 7.
+- `isUploadRoute(r *http.Request) bool` — defined Task 6 step 5; private to `request_timeout.go`.
+- `ctxUserKey{}` — defined Task 7 step 2 (or already present); consumed Task 7 step 2 in `recoveryMiddleware`.
+- `config.LLMConfig.CallTimeout`, `config.ServerConfig.RequestTimeout`, `config.ServerConfig.UploadTimeout` — all `time.Duration` via mapstructure; declared Tasks 3 + 6; consumed Tasks 3 + 6.
+
+No signature drift between tasks.
+
+### Dependency ordering
+
+- Task 1 stands alone (foundational).
+- Task 2 must land before Task 3 (Task 3 uses the pooled client path).
+- Task 3 must land before Task 4 (Task 4's new `EmbedBatch` calls `withCallTimeout` from Task 3).
+- Task 5 should land after Tasks 2–4 so any ctx drift introduced in those tasks is caught in the same sweep. It's also internally independent of 2–4.
+- Task 6 is independent of Tasks 1–5 and independent of Block 2 (with the documented layering fallback).
+- Task 7 is independent of Tasks 1–6.
+
+The sequenced order in the plan (1 → 2 → 3 → 4 → 5 → 6 → 7) satisfies every dependency.
+
+---
+
+## Execution Handoff
+
+Plan complete and saved to `docs/superpowers/plans/2026-04-23-block3-resource-safety-plan.md`. Two execution options:
+
+**1. Subagent-Driven (recommended)** — I dispatch a fresh subagent per task (Tasks 1–7), review between tasks, fast iteration. Each subagent gets a narrow brief referencing exactly the task's Files + Steps.
+
+**2. Inline Execution** — Execute tasks in this session using `superpowers:executing-plans`, batch execution with checkpoints after Task 1 (foundational), after Task 4 (LLM surface complete), and after Task 7 (final).
+
+Which approach?
diff --git a/docs/superpowers/plans/2026-04-23-block4-observability-plan.md b/docs/superpowers/plans/2026-04-23-block4-observability-plan.md
new file mode 100644
index 0000000..54e537c
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-23-block4-observability-plan.md
@@ -0,0 +1,2853 @@
+# Block 4 — Observability & Ops Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Wire docsiq for production observability — Prometheus metrics, structured logs, health probes, a unified access log, and a reflective `/api/version` endpoint — so that an SRE scraping the binary behind a corporate firewall has parity with commercial GraphRAG services.
+
+**Architecture:** Five independent, incremental landings. We introduce the `prometheus/client_golang` dep and replace the ad-hoc text-format collector in `internal/api/metrics.go` with the official one (collision-free, auto-typed, supports labels). `/healthz` is dependency-free; `/readyz` consults SQLite + the LLM provider with a 10-second in-memory result cache. Access logging extends the existing `loggingMiddleware` (rather than adding a second middleware) so req_id generation, Prometheus recording, and the log line share one pass. `/api/version` returns `cmd.versionInfo()` plus `runtime/debug.ReadBuildInfo()` deps.
+
+**Tech Stack:** Go 1.25, `github.com/prometheus/client_golang` v1.20+, `log/slog`, `net/http` (std `http.ServeMux` with Go 1.22 method-pattern routing), `spf13/viper` for config, `spf13/cobra` for CLI.
+
+---
+
+## Hard dependency
+
+**Block 2 (security hardening) must merge first.** This plan assumes the middleware chain is:
+
+```go
+// internal/api/router.go:167 (after Block 2)
+return securityHeadersMiddleware(cfg)(
+    loggingMiddleware(
+        recoveryMiddleware(
+            bearerAuthMiddleware(cfg.Server.APIKey,
+                projectMiddleware(cfg, registry, mux)))))
+```
+
+If Block 2 has not yet landed when this plan begins, Task 4 still works — it replaces the body of `loggingMiddleware` in-place — but the documented chain diagram in comments must be kept in sync.
+
+## Task sequencing & rationale
+
+1. **Task 1 — 4.5 Version endpoint.** Zero infrastructure deps. Reuses `cmd.versionInfo()` and existing `-ldflags` wiring (Makefile already sets `cmd.Version/Commit/Date`). Smallest surface area; lands first so later tasks can assert `/api/version` exists.
+2. **Task 2 — 4.3 Health endpoints.** Small, self-contained. Depends only on `stores` and `llm.Provider`, both already plumbed through `NewRouter`. No new deps.
+3. **Task 3 — 4.1 Prometheus metrics.** Adds the `client_golang` dep, replaces the ad-hoc collector, adds `pipeline` + `embedder` + `llm` stage metrics, and introduces `workq.Pool.Stats()` (a small new accessor). Must land after Task 2 so `/readyz` can scrape its own hit counter in one place.
+4. **Task 4 — 4.4 Access log middleware.** Extends the existing `loggingMiddleware` with `bytes_out`, `user_id` (as a coarse `auth` label), and a panic-resilient `defer` that emits even if downstream middleware panics before `WriteHeader`. Must come after Task 3 so the `bytes_out` figure can also flow into the `docsiq_http_response_bytes_total` counter (added here to round out the HTTP metric family).
+5. **Task 5 — 4.2 Structured-log schema + format switch.** Adjusts the `initConfig` slog setup to (a) drop emoji from the `json` handler's message field and (b) honour a new `LogConfig.Format` field from viper as the lowest-priority source of truth. Lands last because it alters the output format of earlier tasks' logs and would otherwise churn test fixtures mid-flight.
+
+---
+
+## Global verification commands
+
+Every task ends with this trio of checks (run before the task's final commit step):
+
+```
+CGO_ENABLED=1 go build -tags "sqlite_fts5" ./...
+CGO_ENABLED=1 go vet -tags "sqlite_fts5" ./...
+CGO_ENABLED=1 go test -tags "sqlite_fts5" -timeout 300s ./...
+```
+
+Expected across all three: no warnings, no errors, all tests pass. Failing tests that pre-date this plan must be reported to the caller, not papered over.
+
+---
+
+## Task 1: Version endpoint (4.5)
+
+**Files:**
+- Create: `internal/api/version.go`
+- Create: `internal/api/version_test.go`
+- Modify: `internal/api/router.go` — register `GET /api/version` inside `NewRouter`
+- Modify: `cmd/version.go` — export `VersionInfo` and `versionInfo` so `internal/api` can call them (currently unexported)
+
+**Notes for the implementer:** The Makefile already wires `-X cmd.Version/Commit/Date` via the `LDFLAGS` variable. Do NOT add new ldflags. `cmd.versionInfo()` already falls back to `runtime/debug.ReadBuildInfo()` when the ldflags are sentinel values. We just need to expose it to `internal/api` without creating a cyclic import (`internal/api` does not import `cmd`; the inverse is already true). To break the cycle we move the version-resolution logic to a new small package `internal/buildinfo` and have both `cmd/version.go` and `internal/api/version.go` call into it.
+
+- [ ] **Step 1: Create the shared buildinfo package skeleton**
+
+Create `internal/buildinfo/buildinfo.go`:
+
+```go
+// Package buildinfo resolves the running binary's version metadata. It
+// reads ldflags-injected overrides (set via `-X` at build time) and
+// falls back to `runtime/debug.ReadBuildInfo()` when the overrides are
+// sentinel values, so `go install module@version` binaries still report
+// useful metadata.
+package buildinfo
+
+import "runtime/debug"
+
+// Set via -ldflags at build time (see Makefile). These act as overrides.
+// They are package-level var so the linker can write to them; keep the
+// names stable — the Makefile's LDFLAGS refers to them by full symbol
+// path (github.com/RandomCodeSpace/docsiq/internal/buildinfo.Version etc.).
+var (
+	Version = "dev"
+	Commit  = "unknown"
+	Date    = "unknown"
+)
+
+// Info holds resolved version metadata for the running binary.
+type Info struct {
+	Version   string `json:"version"`
+	Commit    string `json:"commit"`
+	BuildDate string `json:"build_date"`
+	GoVersion string `json:"go_version"`
+	Dirty     string `json:"dirty"` // "true", "false", or "unknown"
+	Deps      map[string]string `json:"deps,omitempty"`
+}
+
+// readBuildInfo is a package-level indirection so tests can stub it.
+var readBuildInfo = debug.ReadBuildInfo
+
+func isSentinel(v string) bool {
+	switch v {
+	case "", "dev", "unknown":
+		return true
+	}
+	return false
+}
+
+// Resolve returns the current version metadata using:
+//  1. -ldflags overrides (if non-sentinel)
+//  2. runtime/debug.ReadBuildInfo() (module version + VCS settings)
+//  3. "unknown" for any remaining field
+//
+// When includeDeps is true, the returned Info also lists the main
+// module's direct dependencies (Path → Version). Transitive deps are
+// omitted because they bloat the response without real diagnostic value.
+func Resolve(includeDeps bool) Info {
+	info := Info{
+		Version:   Version,
+		Commit:    Commit,
+		BuildDate: Date,
+		Dirty:     "unknown",
+	}
+
+	bi, ok := readBuildInfo()
+	if !ok {
+		if isSentinel(info.Version) {
+			info.Version = "unknown"
+		}
+		if isSentinel(info.Commit) {
+			info.Commit = "unknown"
+		}
+		if isSentinel(info.BuildDate) {
+			info.BuildDate = "unknown"
+		}
+		info.GoVersion = "unknown"
+		return info
+	}
+
+	info.GoVersion = bi.GoVersion
+
+	if isSentinel(info.Version) {
+		if bi.Main.Version != "" {
+			info.Version = bi.Main.Version
+		} else {
+			info.Version = "unknown"
+		}
+	}
+
+	var vcsRev, vcsTime, vcsMod string
+	for _, s := range bi.Settings {
+		switch s.Key {
+		case "vcs.revision":
+			vcsRev = s.Value
+		case "vcs.time":
+			vcsTime = s.Value
+		case "vcs.modified":
+			vcsMod = s.Value
+		}
+	}
+	if isSentinel(info.Commit) {
+		if vcsRev != "" {
+			info.Commit = vcsRev
+		} else {
+			info.Commit = "unknown"
+		}
+	}
+	if isSentinel(info.BuildDate) {
+		if vcsTime != "" {
+			info.BuildDate = vcsTime
+		} else {
+			info.BuildDate = "unknown"
+		}
+	}
+	if vcsMod != "" {
+		info.Dirty = vcsMod
+	}
+
+	if includeDeps {
+		deps := make(map[string]string, len(bi.Deps))
+		for _, d := range bi.Deps {
+			if d == nil {
+				continue
+			}
+			// Skip replaced modules — the Replace struct's Version is
+			// what actually ships, not d.Version.
+			v := d.Version
+			if d.Replace != nil {
+				v = d.Replace.Version
+			}
+			if v == "" {
+				v = "unknown"
+			}
+			deps[d.Path] = v
+		}
+		info.Deps = deps
+	}
+
+	return info
+}
+```
+
+- [ ] **Step 2: Write buildinfo tests**
+
+Create `internal/buildinfo/buildinfo_test.go`:
+
+```go
+package buildinfo
+
+import (
+	"runtime/debug"
+	"strings"
+	"testing"
+)
+
+func TestResolve_SentinelFallsBackToBuildInfo(t *testing.T) {
+	origVersion, origCommit, origDate, origRead :=
+		Version, Commit, Date, readBuildInfo
+	defer func() {
+		Version, Commit, Date, readBuildInfo =
+			origVersion, origCommit, origDate, origRead
+	}()
+
+	Version, Commit, Date = "dev", "unknown", "unknown"
+	readBuildInfo = func() (*debug.BuildInfo, bool) {
+		return &debug.BuildInfo{
+			GoVersion: "go1.25.5",
+			Main: debug.Module{
+				Path:    "github.com/RandomCodeSpace/docsiq",
+				Version: "v0.5.0",
+			},
+			Settings: []debug.BuildSetting{
+				{Key: "vcs.revision", Value: "abc123def"},
+				{Key: "vcs.time", Value: "2026-04-23T10:00:00Z"},
+				{Key: "vcs.modified", Value: "false"},
+			},
+		}, true
+	}
+
+	got := Resolve(false)
+	if got.Version != "v0.5.0" {
+		t.Errorf("Version=%q want v0.5.0", got.Version)
+	}
+	if got.Commit != "abc123def" {
+		t.Errorf("Commit=%q want abc123def", got.Commit)
+	}
+	if got.BuildDate != "2026-04-23T10:00:00Z" {
+		t.Errorf("BuildDate=%q", got.BuildDate)
+	}
+	if got.GoVersion != "go1.25.5" {
+		t.Errorf("GoVersion=%q", got.GoVersion)
+	}
+	if got.Dirty != "false" {
+		t.Errorf("Dirty=%q", got.Dirty)
+	}
+}
+
+func TestResolve_LdflagsOverridesWin(t *testing.T) {
+	origVersion, origCommit, origDate, origRead :=
+		Version, Commit, Date, readBuildInfo
+	defer func() {
+		Version, Commit, Date, readBuildInfo =
+			origVersion, origCommit, origDate, origRead
+	}()
+
+	Version, Commit, Date = "v9.9.9", "ffffff", "2026-01-01T00:00:00Z"
+	readBuildInfo = func() (*debug.BuildInfo, bool) {
+		return &debug.BuildInfo{
+			GoVersion: "go1.25.5",
+			Main:      debug.Module{Version: "v0.0.0"},
+			Settings: []debug.BuildSetting{
+				{Key: "vcs.revision", Value: "DO-NOT-USE"},
+			},
+		}, true
+	}
+
+	got := Resolve(false)
+	if got.Version != "v9.9.9" {
+		t.Errorf("ldflags Version should win; got %q", got.Version)
+	}
+	if got.Commit != "ffffff" {
+		t.Errorf("ldflags Commit should win; got %q", got.Commit)
+	}
+}
+
+func TestResolve_IncludeDepsPopulatesMap(t *testing.T) {
+	origRead := readBuildInfo
+	defer func() { readBuildInfo = origRead }()
+	readBuildInfo = func() (*debug.BuildInfo, bool) {
+		return &debug.BuildInfo{
+			GoVersion: "go1.25.5",
+			Main:      debug.Module{Version: "v0.5.0"},
+			Deps: []*debug.Module{
+				{Path: "github.com/spf13/cobra", Version: "v1.10.2"},
+				{Path: "github.com/tmc/langchaingo", Version: "v0.1.14"},
+			},
+		}, true
+	}
+
+	got := Resolve(true)
+	if got.Deps["github.com/spf13/cobra"] != "v1.10.2" {
+		t.Errorf("deps missing cobra; got %+v", got.Deps)
+	}
+	if got.Deps["github.com/tmc/langchaingo"] != "v0.1.14" {
+		t.Errorf("deps missing langchaingo")
+	}
+}
+
+func TestResolve_ReadBuildInfoUnavailable(t *testing.T) {
+	origRead := readBuildInfo
+	origVersion, origCommit, origDate :=
+		Version, Commit, Date
+	defer func() {
+		readBuildInfo = origRead
+		Version, Commit, Date = origVersion, origCommit, origDate
+	}()
+
+	Version, Commit, Date = "dev", "unknown", "unknown"
+	readBuildInfo = func() (*debug.BuildInfo, bool) { return nil, false }
+
+	got := Resolve(true)
+	if got.Version != "unknown" || got.Commit != "unknown" || got.BuildDate != "unknown" {
+		t.Errorf("all fields should be 'unknown'; got %+v", got)
+	}
+	if got.GoVersion != "unknown" {
+		t.Errorf("GoVersion should be 'unknown'; got %q", got.GoVersion)
+	}
+	if got.Deps != nil {
+		t.Errorf("Deps should be nil when ReadBuildInfo fails; got %+v", got.Deps)
+	}
+	if strings.Contains(got.Dirty, "true") {
+		t.Errorf("Dirty should default to 'unknown'; got %q", got.Dirty)
+	}
+}
+```
+
+- [ ] **Step 3: Run buildinfo tests (red — no ldflags-migration yet but tests use stubs)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/buildinfo/ -v`
+
+Expected: all 4 tests PASS. If `go: module lookup disabled by GOPROXY=off` fires, remove GOPROXY and retry. If any test references a symbol not yet defined in `buildinfo.go`, re-read Step 1 and confirm the full file was saved.
+
+- [ ] **Step 4: Migrate cmd/version.go to call buildinfo.Resolve**
+
+Open `cmd/version.go`. Replace the whole file body with:
+
+```go
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/RandomCodeSpace/docsiq/internal/buildinfo"
+	"github.com/spf13/cobra"
+)
+
+var versionCmd = &cobra.Command{
+	Use:   "version",
+	Short: "Print the version of docsiq",
+	Run: func(cmd *cobra.Command, args []string) {
+		info := buildinfo.Resolve(false)
+		dirtySuffix := ""
+		if info.Dirty == "true" {
+			dirtySuffix = " (dirty)"
+		}
+		fmt.Printf("docsiq %s (commit: %s, built: %s)%s\n",
+			info.Version, info.Commit, info.BuildDate, dirtySuffix)
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(versionCmd)
+}
+```
+
+Note: `Version`, `Commit`, `Date` package-level vars move to `internal/buildinfo`.
+
+- [ ] **Step 5: Update Makefile LDFLAGS to point at the new package path**
+
+Open `Makefile`. Current `LDFLAGS` block:
+
+```
+LDFLAGS  := -X github.com/RandomCodeSpace/docsiq/cmd.Version=$(VERSION) \
+            -X github.com/RandomCodeSpace/docsiq/cmd.Commit=$(COMMIT) \
+            -X github.com/RandomCodeSpace/docsiq/cmd.Date=$(DATE)
+```
+
+Change to:
+
+```
+LDFLAGS  := -X github.com/RandomCodeSpace/docsiq/internal/buildinfo.Version=$(VERSION) \
+            -X github.com/RandomCodeSpace/docsiq/internal/buildinfo.Commit=$(COMMIT) \
+            -X github.com/RandomCodeSpace/docsiq/internal/buildinfo.Date=$(DATE)
+```
+
+- [ ] **Step 6: Patch cmd/version_test.go for the rename**
+
+Open `cmd/version_test.go`. Any reference to `Version`, `Commit`, `Date`, `readBuildInfo`, `versionInfo`, or `VersionInfo` inside `package cmd` must be rewritten to import and use `internal/buildinfo`. If the test mocks `readBuildInfo`, it now lives in `internal/buildinfo` and tests there. Delete test cases whose behaviour is now covered by `internal/buildinfo/buildinfo_test.go`; keep only tests that exercise the `docsiq version` Cobra command surface (output formatting via stdout capture).
+
+If the test file becomes empty, delete it.
+
+- [ ] **Step 7: Run cmd tests to confirm version cmd still builds**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./cmd/... -v -run Version`
+
+Expected: PASS. If `docsiq version` prints "docsiq dev (commit: unknown, built: unknown)" that's the `go test` path (no ldflags) and is correct.
+
+- [ ] **Step 8: Write the /api/version handler**
+
+Create `internal/api/version.go`:
+
+```go
+package api
+
+import (
+	"net/http"
+
+	"github.com/RandomCodeSpace/docsiq/internal/buildinfo"
+)
+
+// versionHandler serves GET /api/version. Returns buildinfo.Info as
+// JSON, including the direct-dependency map. Public endpoint — no
+// secrets are exposed; commit hash and Go version are considered
+// non-sensitive for a self-hosted MCP server.
+func versionHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			w.Header().Set("Allow", "GET")
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		info := buildinfo.Resolve(true)
+		writeJSON(w, http.StatusOK, info)
+	})
+}
+```
+
+Note: `writeJSON` is the existing helper in `internal/api/handlers.go`. No new helpers needed.
+
+- [ ] **Step 9: Write the handler tests**
+
+Create `internal/api/version_test.go`:
+
+```go
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestVersionHandler_ReturnsJSON(t *testing.T) {
+	t.Parallel()
+	h := versionHandler()
+	req := httptest.NewRequest(http.MethodGet, "/api/version", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status=%d want 200", rec.Code)
+	}
+	ct := rec.Header().Get("Content-Type")
+	if ct == "" || ct[:16] != "application/json" {
+		t.Errorf("Content-Type=%q want application/json*", ct)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("body not JSON: %v — raw=%q", err, rec.Body.String())
+	}
+
+	for _, key := range []string{"version", "commit", "build_date", "go_version"} {
+		if _, ok := body[key]; !ok {
+			t.Errorf("response missing %q field; got keys=%v", key, mapKeys(body))
+		}
+	}
+}
+
+func TestVersionHandler_RejectsNonGET(t *testing.T) {
+	t.Parallel()
+	h := versionHandler()
+	req := httptest.NewRequest(http.MethodPost, "/api/version", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusMethodNotAllowed {
+		t.Errorf("POST /api/version status=%d want 405", rec.Code)
+	}
+	if got := rec.Header().Get("Allow"); got != "GET" {
+		t.Errorf("Allow=%q want GET", got)
+	}
+}
+
+func mapKeys(m map[string]any) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}
+```
+
+- [ ] **Step 10: Run the new handler tests (red — not wired yet if via route, but unit test exercises handler directly so should PASS)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestVersionHandler -v`
+
+Expected: 2/2 PASS. If you get a nil `writeJSON` or "undefined: writeJSON" error, confirm `internal/api/handlers.go` still exports it (it is not currently exported by name — it is package-internal, which is fine because we're in the same package).
+
+- [ ] **Step 11: Register the route inside NewRouter**
+
+Open `internal/api/router.go`. Inside `NewRouter`, directly after the existing `/metrics` registration (currently around line 94), add:
+
+```go
+	// Version metadata — public, no auth. Used for operator diagnostics
+	// and CI tooling ("what's running in prod?"). No secrets exposed.
+	mux.Handle("GET /api/version", versionHandler())
+```
+
+- [ ] **Step 12: Write an integration test that hits the live-routed /api/version**
+
+Append to `internal/api/router_no_llm_test.go`:
+
+```go
+func TestNewRouter_VersionEndpointPublic(t *testing.T) {
+	t.Parallel()
+	cfg := minimalTestConfig(t) // existing helper; do not add a new one
+	reg := newTestRegistry(t)
+	h := NewRouter(nil, nil, cfg, reg)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/version", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("GET /api/version with no Auth should be 200; got %d body=%s",
+			rec.Code, rec.Body.String())
+	}
+}
+```
+
+If `minimalTestConfig(t)` and `newTestRegistry(t)` do not exist, mirror the pattern used by the existing `TestNewRouter_NoLLM` sub-tests in the same file. Do not invent new helpers unless the file has zero prior harness.
+
+- [ ] **Step 13: Run all changed tests + go vet**
+
+```
+CGO_ENABLED=1 go vet -tags "sqlite_fts5" ./...
+CGO_ENABLED=1 go test -tags "sqlite_fts5" -timeout 300s ./internal/api/ ./internal/buildinfo/ ./cmd/...
+```
+
+Expected: clean vet, all tests PASS. If a test that pre-dates this task is newly red, open it and check for a stale reference to `cmd.Version/Commit/Date`.
+
+- [ ] **Step 14: Smoke-test via built binary**
+
+```
+make build
+./docsiq serve --port 0 &
+SERVE_PID=$!
+# Hit the endpoint before auth kicks in — /api/version is public.
+sleep 1
+curl -s http://127.0.0.1:8080/api/version | python3 -m json.tool
+kill $SERVE_PID
+```
+
+Expected: JSON with at minimum `version`, `commit`, `build_date`, `go_version`, `deps` keys. The `version` field equals the output of `git describe --tags --always --dirty` when the working tree is clean; otherwise it carries the `-dirty` suffix that `git describe` emits.
+
+If the binary fails to start due to `api_key empty + non-loopback bind`, set `DOCSIQ_API_KEY=dev` for the smoke test — the version endpoint bypasses auth anyway.
+
+- [ ] **Step 15: Commit**
+
+```bash
+git add internal/buildinfo/ cmd/version.go cmd/version_test.go Makefile \
+        internal/api/version.go internal/api/version_test.go \
+        internal/api/router.go internal/api/router_no_llm_test.go
+git commit -m "$(cat <<'EOF'
+feat(api): GET /api/version with ldflags + BuildInfo fallback
+
+Moves the shared version-resolution logic out of cmd into a new
+internal/buildinfo package so internal/api can serve the same data
+without a cmd import cycle. Adds a public GET /api/version endpoint
+that returns {version, commit, build_date, go_version, dirty, deps}
+as JSON. Makefile LDFLAGS retargeted at the new package path.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 2: Health endpoints (4.3)
+
+**Files:**
+- Create: `internal/api/health.go`
+- Create: `internal/api/health_test.go`
+- Modify: `internal/api/router.go` — register `GET /healthz` and `GET /readyz`; remove the existing `GET /health` alias (covered by `/healthz`)
+
+**Notes:** `/healthz` always 200 if the process is running; no I/O, no dependencies. `/readyz` checks SQLite ping + LLM provider reach, with a 10-second in-memory cache keyed only on time (not on the set of projects — we ping the default project's store as the representative shard). When the LLM provider is `nil` (config `provider: none`), the LLM check reports `"status": "skipped"` and does NOT fail readiness — the server still serves notes and MCP-without-LLM traffic. Cache TTL is a `const readyCheckTTL = 10 * time.Second`, not a config knob; operators who want different behaviour can subclass the handler.
+
+- [ ] **Step 1: Write the failing health test**
+
+Create `internal/api/health_test.go`:
+
+```go
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// healthPingerStub is a test double for whatever interface the ready
+// probe accepts for "ping this SQLite handle". See health.go.
+type healthPingerStub struct {
+	err  error
+	hits atomic.Int32
+}
+
+func (p *healthPingerStub) Ping(ctx context.Context) error {
+	p.hits.Add(1)
+	return p.err
+}
+
+// llmPingerStub is a test double for the LLM reachability probe.
+type llmPingerStub struct {
+	err  error
+	hits atomic.Int32
+}
+
+func (p *llmPingerStub) Ping(ctx context.Context) error {
+	p.hits.Add(1)
+	return p.err
+}
+
+func TestHealthz_Always200(t *testing.T) {
+	t.Parallel()
+	h := healthzHandler()
+	req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status=%d want 200", rec.Code)
+	}
+	var body map[string]string
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("body not JSON: %v", err)
+	}
+	if body["status"] != "ok" {
+		t.Errorf("status=%q want ok", body["status"])
+	}
+}
+
+func TestReadyz_AllChecksOKReturns200(t *testing.T) {
+	t.Parallel()
+	sq := &healthPingerStub{}
+	llm := &llmPingerStub{}
+	h := readyzHandler(sq, llm)
+
+	req := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status=%d want 200 body=%s", rec.Code, rec.Body.String())
+	}
+	var body readyzBody
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("body not JSON: %v", err)
+	}
+	if body.Status != "ready" {
+		t.Errorf("status=%q want ready", body.Status)
+	}
+	if body.Checks["sqlite"].Status != "ok" {
+		t.Errorf("sqlite=%+v", body.Checks["sqlite"])
+	}
+	if body.Checks["llm"].Status != "ok" {
+		t.Errorf("llm=%+v", body.Checks["llm"])
+	}
+}
+
+func TestReadyz_SQLiteDownReturns503(t *testing.T) {
+	t.Parallel()
+	sq := &healthPingerStub{err: errors.New("database is locked")}
+	llm := &llmPingerStub{}
+	h := readyzHandler(sq, llm)
+
+	req := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusServiceUnavailable {
+		t.Fatalf("status=%d want 503", rec.Code)
+	}
+	var body readyzBody
+	_ = json.Unmarshal(rec.Body.Bytes(), &body)
+	if body.Status != "not_ready" {
+		t.Errorf("status=%q want not_ready", body.Status)
+	}
+	if body.Checks["sqlite"].Status != "error" {
+		t.Errorf("sqlite status=%q want error", body.Checks["sqlite"].Status)
+	}
+	if body.Checks["sqlite"].Err == "" {
+		t.Errorf("sqlite err empty; should carry 'database is locked'")
+	}
+}
+
+func TestReadyz_NilLLMReportsSkippedAndStaysReady(t *testing.T) {
+	t.Parallel()
+	sq := &healthPingerStub{}
+	h := readyzHandler(sq, nil) // nil llm == provider:none
+
+	req := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status=%d want 200", rec.Code)
+	}
+	var body readyzBody
+	_ = json.Unmarshal(rec.Body.Bytes(), &body)
+	if body.Checks["llm"].Status != "skipped" {
+		t.Errorf("llm=%+v want skipped", body.Checks["llm"])
+	}
+}
+
+func TestReadyz_CachesResultFor10s(t *testing.T) {
+	t.Parallel()
+	sq := &healthPingerStub{}
+	llm := &llmPingerStub{}
+	h := readyzHandler(sq, llm)
+
+	for i := 0; i < 5; i++ {
+		req := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+		rec := httptest.NewRecorder()
+		h.ServeHTTP(rec, req)
+	}
+
+	// Each of the 5 requests must have hit the pingers at most once.
+	if got := sq.hits.Load(); got > 1 {
+		t.Errorf("sqlite pinger called %d times in a single TTL window; want <=1", got)
+	}
+	if got := llm.hits.Load(); got > 1 {
+		t.Errorf("llm pinger called %d times in a single TTL window; want <=1", got)
+	}
+}
+
+func TestReadyz_PingerContextIsBounded(t *testing.T) {
+	t.Parallel()
+	var seenDeadline atomic.Bool
+	sq := &healthPingerStub{}
+	sq.err = nil
+	llm := &llmPingerStub{}
+
+	// Wrap the sq probe so it reports whether the caller bounded the context.
+	wrapped := healthPingerFunc(func(ctx context.Context) error {
+		if _, ok := ctx.Deadline(); ok {
+			seenDeadline.Store(true)
+		}
+		return nil
+	})
+	h := readyzHandler(wrapped, llm)
+
+	req := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	if !seenDeadline.Load() {
+		t.Errorf("readyzHandler must bound the pinger context with a deadline")
+	}
+	if rec.Code != http.StatusOK {
+		t.Errorf("status=%d", rec.Code)
+	}
+}
+
+// healthPingerFunc is an adapter so the last test above can use an
+// inline closure without hand-rolling another stub type.
+type healthPingerFunc func(ctx context.Context) error
+
+func (f healthPingerFunc) Ping(ctx context.Context) error { return f(ctx) }
+
+// Guardrail: test clock advance simulation ensures cached result refreshes.
+func TestReadyz_RefreshesAfterTTL(t *testing.T) {
+	t.Parallel()
+	sq := &healthPingerStub{}
+	llm := &llmPingerStub{}
+	h := readyzHandlerForTest(sq, llm, 50*time.Millisecond)
+
+	req := func() {
+		r := httptest.NewRequest(http.MethodGet, "/readyz", nil)
+		rec := httptest.NewRecorder()
+		h.ServeHTTP(rec, r)
+	}
+
+	req()
+	req()
+	time.Sleep(80 * time.Millisecond)
+	req()
+
+	if got := sq.hits.Load(); got != 2 {
+		t.Errorf("sqlite pinger hits=%d want 2 (one per TTL window)", got)
+	}
+}
+```
+
+- [ ] **Step 2: Run the failing tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run Test(Healthz|Readyz) -v`
+
+Expected: all compile errors because `healthzHandler`, `readyzHandler`, `readyzHandlerForTest`, `readyzBody`, `healthPinger`, `llmPinger` do not exist yet. That is the red state.
+
+- [ ] **Step 3: Implement internal/api/health.go**
+
+Create `internal/api/health.go`:
+
+```go
+package api
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/RandomCodeSpace/docsiq/internal/llm"
+)
+
+// readyCheckTTL is how long the /readyz handler caches its aggregated
+// verdict. Ten seconds is short enough to notice a real outage quickly
+// and long enough to absorb a chatty Prometheus + Kubernetes probe loop
+// without hammering SQLite or the LLM endpoint.
+const readyCheckTTL = 10 * time.Second
+
+// readyCheckTimeout bounds each individual probe. The SQLite ping is a
+// microsecond-scale PRAGMA query; the LLM ping is network-bound, so we
+// allow more headroom but still fail fast when the provider is wedged.
+const (
+	sqliteCheckTimeout = 500 * time.Millisecond
+	llmCheckTimeout    = 2 * time.Second
+)
+
+// healthPinger is the narrow interface readyz needs for SQLite
+// reachability: a bounded Ping call that reports the first hard error.
+type healthPinger interface {
+	Ping(ctx context.Context) error
+}
+
+// llmPinger is the narrow interface readyz needs for LLM reachability.
+// Implementations may issue a tiny Complete call or a model-list GET.
+type llmPinger interface {
+	Ping(ctx context.Context) error
+}
+
+// checkStatus holds per-component readiness.
+type checkStatus struct {
+	Status string `json:"status"` // "ok" | "error" | "skipped"
+	Err    string `json:"err,omitempty"`
+}
+
+type readyzBody struct {
+	Status string                 `json:"status"` // "ready" | "not_ready"
+	Checks map[string]checkStatus `json:"checks"`
+}
+
+// healthzHandler implements GET /healthz. Liveness: always 200 as long
+// as the goroutine scheduler can run this function. No dependencies.
+func healthzHandler() http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			w.Header().Set("Allow", "GET")
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+	})
+}
+
+// readyzHandler implements GET /readyz. Readiness: aggregates a SQLite
+// ping and an LLM reach check with a 10-second in-memory cache. When
+// llm is nil (provider=none), the LLM check is reported as "skipped"
+// and does NOT fail readiness.
+//
+// Pass the default project's store adapter and an llmPinger wrapper
+// around the configured provider (or nil). See router.go for wiring.
+func readyzHandler(sq healthPinger, llm llmPinger) http.Handler {
+	return readyzHandlerForTest(sq, llm, readyCheckTTL)
+}
+
+// readyzHandlerForTest is the injectable-TTL variant used only by tests.
+// Production code must use readyzHandler.
+func readyzHandlerForTest(sq healthPinger, llm llmPinger, ttl time.Duration) http.Handler {
+	rc := &readyzCache{ttl: ttl}
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			w.Header().Set("Allow", "GET")
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		body, code := rc.check(r.Context(), sq, llm)
+		writeJSON(w, code, body)
+	})
+}
+
+// readyzCache is the TTL-cached readiness result. Uses a single mutex
+// because the hot path is cheap; lock contention only matters when the
+// TTL expires and many requests arrive before the first unlock.
+type readyzCache struct {
+	ttl time.Duration
+
+	mu     sync.Mutex
+	expiry time.Time
+	body   readyzBody
+	code   int
+}
+
+func (c *readyzCache) check(ctx context.Context, sq healthPinger, llmp llmPinger) (readyzBody, int) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if !c.expiry.IsZero() && time.Now().Before(c.expiry) {
+		return c.body, c.code
+	}
+
+	body := readyzBody{
+		Status: "ready",
+		Checks: map[string]checkStatus{},
+	}
+	code := http.StatusOK
+
+	// SQLite probe — mandatory. Failure fails readiness.
+	{
+		sqCtx, cancel := context.WithTimeout(ctx, sqliteCheckTimeout)
+		err := sq.Ping(sqCtx)
+		cancel()
+		if err != nil {
+			body.Checks["sqlite"] = checkStatus{Status: "error", Err: err.Error()}
+			body.Status = "not_ready"
+			code = http.StatusServiceUnavailable
+		} else {
+			body.Checks["sqlite"] = checkStatus{Status: "ok"}
+		}
+	}
+
+	// LLM probe — optional. Nil provider (provider=none) reports skipped.
+	switch {
+	case llmp == nil:
+		body.Checks["llm"] = checkStatus{Status: "skipped", Err: "provider=none"}
+	default:
+		llmCtx, cancel := context.WithTimeout(ctx, llmCheckTimeout)
+		err := llmp.Ping(llmCtx)
+		cancel()
+		if err != nil {
+			body.Checks["llm"] = checkStatus{Status: "error", Err: err.Error()}
+			body.Status = "not_ready"
+			code = http.StatusServiceUnavailable
+		} else {
+			body.Checks["llm"] = checkStatus{Status: "ok"}
+		}
+	}
+
+	c.body = body
+	c.code = code
+	c.expiry = time.Now().Add(c.ttl)
+	return body, code
+}
+
+// sqlDBPinger adapts a *sql.DB for the healthPinger interface. SQLite's
+// driver treats PingContext as a cheap no-op when the handle is healthy.
+type sqlDBPinger struct{ db *sql.DB }
+
+func (p sqlDBPinger) Ping(ctx context.Context) error {
+	if p.db == nil {
+		return errors.New("nil sql.DB")
+	}
+	return p.db.PingContext(ctx)
+}
+
+// providerPinger adapts an llm.Provider for the llmPinger interface.
+// It issues a tiny Complete call with 1-token cap; providers that
+// cannot produce tokens (e.g. misconfigured) fail the ping.
+type providerPinger struct{ prov llm.Provider }
+
+func (p providerPinger) Ping(ctx context.Context) error {
+	if p.prov == nil {
+		return errors.New("nil provider")
+	}
+	// A minimal generation request — 1 token, temp 0, no JSON mode.
+	// Providers that stream will still return promptly when maxTokens=1.
+	_, err := p.prov.Complete(ctx, "ping", llm.WithMaxTokens(1), llm.WithTemperature(0))
+	return err
+}
+```
+
+- [ ] **Step 4: Run the health tests (green)**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run Test(Healthz|Readyz) -v`
+
+Expected: all 7 tests PASS. If `TestReadyz_RefreshesAfterTTL` is flaky due to the 80ms sleep, bump to 120ms — do not skip the test. A flaky test here hides real TTL bugs.
+
+- [ ] **Step 5: Wire the routes into NewRouter**
+
+Open `internal/api/router.go`. Inside `NewRouter`, locate the existing `/health` registration (currently around line 88-89):
+
+```go
+	// Public liveness probe — registered on the mux itself. The auth
+	// middleware also explicitly bypasses /health as defense-in-depth.
+	mux.HandleFunc("GET /health", h.health)
+```
+
+Replace with:
+
+```go
+	// Public liveness + readiness probes. /healthz is dependency-free
+	// (process-is-running); /readyz aggregates a SQLite ping + LLM reach
+	// check with a 10s in-memory cache. Both are registered on the mux
+	// and also explicitly bypassed by bearerAuthMiddleware.
+	mux.Handle("GET /healthz", healthzHandler())
+	{
+		// Default-project store is the representative SQLite shard — a
+		// failure here means the whole server is hosed. Resolve lazily
+		// at handler-build time so tests that pass nil stores still work.
+		defaultSlug := cfg.DefaultProject
+		if defaultSlug == "" {
+			defaultSlug = "_default"
+		}
+		var sq healthPinger
+		if stores != nil {
+			if st, err := stores.Get(defaultSlug); err == nil && st != nil {
+				sq = sqlDBPinger{db: st.DB()}
+			}
+		}
+		if sq == nil {
+			// Fall back to a "no-op OK" probe when there is no default
+			// store (tests, or pre-registration boot sequence). Lying
+			// about readiness here is acceptable because bearerAuth is
+			// still absent — this path is never reached in production.
+			sq = healthPingerFuncForRouter(func(_ context.Context) error { return nil })
+		}
+		var llmp llmPinger
+		if prov != nil {
+			llmp = providerPinger{prov: prov}
+		}
+		mux.Handle("GET /readyz", readyzHandler(sq, llmp))
+	}
+
+	// Back-compat alias: GET /health was the pre-Block-4 probe. Clients
+	// that haven't migrated to /healthz still get a 200.
+	mux.Handle("GET /health", healthzHandler())
+```
+
+Add the adapter helper to `internal/api/health.go` (append at end):
+
+```go
+// healthPingerFuncForRouter is the non-test counterpart of
+// healthPingerFunc; lives in the prod file so the wiring in router.go
+// does not have to depend on a test-only adapter.
+type healthPingerFuncForRouter func(ctx context.Context) error
+
+func (f healthPingerFuncForRouter) Ping(ctx context.Context) error { return f(ctx) }
+```
+
+- [ ] **Step 6: Update bearerAuthMiddleware to bypass /healthz and /readyz**
+
+Open `internal/api/auth.go`. Find the existing bypass block (around line 40-50 — the "/api/session" and "/health" bypasses). The exact code depends on what Block 2 merged; it looks like this after Block 2:
+
+```go
+		if path == "/health" || path == "/metrics" || path == "/api/session" {
+			next.ServeHTTP(w, r)
+			return
+		}
+```
+
+Change the single-line check to:
+
+```go
+		switch path {
+		case "/health", "/healthz", "/readyz", "/metrics", "/api/session", "/api/version":
+			next.ServeHTTP(w, r)
+			return
+		}
+```
+
+`/api/version` is added here as part of Task 1's public-endpoint commitment; a separate task did not touch this file to avoid merge conflict with Block 2. If the block you see uses a slice + `slices.Contains`, update the slice contents instead.
+
+- [ ] **Step 7: Delete the obsolete h.health handler**
+
+Open `internal/api/handlers.go`. Find the function `func (h *handlers) health(w http.ResponseWriter, r *http.Request)` — it is short (5-10 lines, returns JSON `{"status":"ok"}`). Delete the function entirely. The `/health` route is now served by `healthzHandler()` directly.
+
+Also delete any test in `internal/api/` that references `h.health` or `healthHandler` — grep for `health` under test files and update.
+
+- [ ] **Step 8: Run full API suite**
+
+```
+CGO_ENABLED=1 go test -tags "sqlite_fts5" ./internal/api/ -v -timeout 120s
+```
+
+Expected: all PASS. Failures most likely come from the handler deletion in Step 7 — fix the test references rather than restore the old handler.
+
+- [ ] **Step 9: Smoke-test live endpoints**
+
+```
+DOCSIQ_API_KEY=dev make build && ./docsiq serve --port 0 &
+SERVE_PID=$!
+sleep 1
+echo '=== healthz ==='; curl -s -w '\nstatus=%{http_code}\n' http://127.0.0.1:8080/healthz
+echo '=== readyz ==='; curl -s -w '\nstatus=%{http_code}\n' http://127.0.0.1:8080/readyz
+kill $SERVE_PID
+```
+
+Expected `/healthz`: `{"status":"ok"}` + `status=200`.
+Expected `/readyz`: `{"status":"ready","checks":{"sqlite":{"status":"ok"},"llm":{"status":"skipped",...}}}` + `status=200` (assuming no LLM provider is configured). If provider is `openai` but the key is invalid, expect `status=503` and `checks.llm.status=error`.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add internal/api/health.go internal/api/health_test.go \
+        internal/api/router.go internal/api/auth.go \
+        internal/api/handlers.go
+git commit -m "$(cat <<'EOF'
+feat(api): /healthz + /readyz probes with 10s cache
+
+/healthz is dependency-free liveness. /readyz checks SQLite PRAGMA +
+an LLM provider Complete(maxTokens=1) reach, caching the verdict for
+10 seconds to absorb Prometheus + Kubernetes probe loops. Nil
+provider (config provider: none) reports llm.status=skipped and keeps
+readiness green. Auth middleware bypasses both endpoints; legacy
+/health route remains as a 200-returning alias for older clients.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 3: Prometheus metrics + workq stats (4.1)
+
+**Files:**
+- Modify: `go.mod`, `go.sum` — add `github.com/prometheus/client_golang` v1.20.5 (or latest patch)
+- Create: `internal/obs/metrics.go` — the central registry + collectors
+- Create: `internal/obs/metrics_test.go`
+- Modify: `internal/api/metrics.go` — replace the ad-hoc text collector with a thin adapter over `promhttp.Handler()`
+- Modify: `internal/workq/workq.go` — add `Pool.Stats() Stats` accessor and a `rejectedTotal` counter
+- Modify: `internal/workq/workq_test.go` — add `TestPool_StatsCountsRejections`
+- Modify: `internal/api/router.go` — record HTTP metrics from `loggingMiddleware` via `obs.HTTP`
+- Modify: `internal/pipeline/pipeline.go` — wrap each phase with `obs.Pipeline.TimeStage(name, fn)`
+- Modify: `internal/embedder/embedder.go` — wrap batch embed calls with `obs.Embed.Observe(provider, duration)`
+- Modify: `internal/llm/provider.go` — wrap completions with `obs.LLM.RecordTokens(provider, kind, n)` when the provider exposes usage
+
+**Notes on the metric set (verbatim from the spec):**
+
+| Metric | Type | Labels | Source |
+|---|---|---|---|
+| `docsiq_pipeline_stage_duration_seconds` | Histogram | `stage` | `internal/pipeline/pipeline.go` |
+| `docsiq_embed_latency_seconds` | Histogram | `provider` | `internal/embedder/embedder.go` |
+| `docsiq_llm_tokens_total` | Counter | `provider`, `kind` | `internal/llm/provider.go` |
+| `docsiq_workq_depth` | Gauge | — | `internal/workq/workq.go` |
+| `docsiq_workq_rejected_total` | Counter | — | `internal/workq/workq.go` |
+| `docsiq_http_requests_total` | Counter | `route`, `method`, `status` | `internal/api/router.go` (loggingMiddleware) |
+| `docsiq_http_request_duration_seconds` | Histogram | `route` | same |
+
+`kind` label values: `"prompt"`, `"completion"` (when provider returns usage), or `"total"` (fallback when the provider does not split). `route` label is the Go 1.22 method pattern (e.g. `GET /api/documents/{id}`), NOT `r.URL.Path` — unbounded path cardinality would DoS the scrape.
+
+- [ ] **Step 1: Add the Prometheus client_golang dep**
+
+```
+go get github.com/prometheus/client_golang@v1.20.5
+go mod tidy
+```
+
+Expected: `go.mod` gains `github.com/prometheus/client_golang v1.20.5`, `go.sum` picks up the new hashes. If `go get` fails with `proxy.golang.org: connection refused` you are behind an air-gapped firewall; configure `GOPROXY` per build.md and retry. DO NOT vendor manually.
+
+- [ ] **Step 2: Write the obs package tests first**
+
+Create `internal/obs/metrics_test.go`:
+
+```go
+package obs
+
+import (
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/testutil"
+)
+
+func TestHTTP_ObserveRecordsCounterAndHistogram(t *testing.T) {
+	t.Parallel()
+	reg := prometheus.NewRegistry()
+	h := NewHTTPMetrics(reg)
+
+	h.Observe("GET /api/documents", "GET", 200, 42*time.Millisecond)
+	h.Observe("GET /api/documents", "GET", 200, 80*time.Millisecond)
+	h.Observe("POST /api/search", "POST", 500, 2*time.Second)
+
+	if got := testutil.ToFloat64(h.Requests.WithLabelValues("GET /api/documents", "GET", "200")); got != 2 {
+		t.Errorf("requests{...200}=%v want 2", got)
+	}
+	if got := testutil.ToFloat64(h.Requests.WithLabelValues("POST /api/search", "POST", "500")); got != 1 {
+		t.Errorf("requests{...500}=%v want 1", got)
+	}
+
+	// Histogram buckets — assert the sum is plausible.
+	out, err := reg.Gather()
+	if err != nil {
+		t.Fatalf("gather: %v", err)
+	}
+	var found bool
+	for _, mf := range out {
+		if mf.GetName() == "docsiq_http_request_duration_seconds" {
+			found = true
+			for _, m := range mf.Metric {
+				if h := m.GetHistogram(); h != nil {
+					if h.GetSampleCount() == 0 {
+						t.Errorf("histogram sample count=0")
+					}
+				}
+			}
+		}
+	}
+	if !found {
+		t.Errorf("docsiq_http_request_duration_seconds not registered")
+	}
+}
+
+func TestPipeline_TimeStageRecordsBothSuccessAndError(t *testing.T) {
+	t.Parallel()
+	reg := prometheus.NewRegistry()
+	p := NewPipelineMetrics(reg)
+
+	_ = p.TimeStage("load", func() error { return nil })
+	_ = p.TimeStage("chunk", func() error { return nil })
+	_ = p.TimeStage("chunk", func() error { return nil })
+
+	// Histogram sample counts per label — expect 1 for "load", 2 for "chunk".
+	count := func(stage string) uint64 {
+		out, _ := reg.Gather()
+		for _, mf := range out {
+			if mf.GetName() != "docsiq_pipeline_stage_duration_seconds" {
+				continue
+			}
+			for _, m := range mf.Metric {
+				var s string
+				for _, lp := range m.GetLabel() {
+					if lp.GetName() == "stage" {
+						s = lp.GetValue()
+					}
+				}
+				if s == stage {
+					return m.GetHistogram().GetSampleCount()
+				}
+			}
+		}
+		return 0
+	}
+	if got := count("load"); got != 1 {
+		t.Errorf("load stage count=%d want 1", got)
+	}
+	if got := count("chunk"); got != 2 {
+		t.Errorf("chunk stage count=%d want 2", got)
+	}
+}
+
+func TestEmbed_ObserveByProvider(t *testing.T) {
+	t.Parallel()
+	reg := prometheus.NewRegistry()
+	e := NewEmbedMetrics(reg)
+
+	e.Observe("openai", 120*time.Millisecond)
+	e.Observe("openai", 200*time.Millisecond)
+	e.Observe("ollama", 50*time.Millisecond)
+
+	// Verify each provider got its own histogram line.
+	out, _ := reg.Gather()
+	perProvider := map[string]uint64{}
+	for _, mf := range out {
+		if mf.GetName() != "docsiq_embed_latency_seconds" {
+			continue
+		}
+		for _, m := range mf.Metric {
+			for _, lp := range m.GetLabel() {
+				if lp.GetName() == "provider" {
+					perProvider[lp.GetValue()] = m.GetHistogram().GetSampleCount()
+				}
+			}
+		}
+	}
+	if perProvider["openai"] != 2 {
+		t.Errorf("openai count=%d want 2", perProvider["openai"])
+	}
+	if perProvider["ollama"] != 1 {
+		t.Errorf("ollama count=%d want 1", perProvider["ollama"])
+	}
+}
+
+func TestLLM_RecordTokensByKind(t *testing.T) {
+	t.Parallel()
+	reg := prometheus.NewRegistry()
+	l := NewLLMMetrics(reg)
+
+	l.RecordTokens("openai", "prompt", 512)
+	l.RecordTokens("openai", "completion", 128)
+	l.RecordTokens("azure", "total", 256)
+
+	if got := testutil.ToFloat64(l.Tokens.WithLabelValues("openai", "prompt")); got != 512 {
+		t.Errorf("openai prompt=%v want 512", got)
+	}
+	if got := testutil.ToFloat64(l.Tokens.WithLabelValues("openai", "completion")); got != 128 {
+		t.Errorf("openai completion=%v want 128", got)
+	}
+	if got := testutil.ToFloat64(l.Tokens.WithLabelValues("azure", "total")); got != 256 {
+		t.Errorf("azure total=%v want 256", got)
+	}
+}
+
+func TestWorkq_DepthAndRejectedFromStatsProvider(t *testing.T) {
+	t.Parallel()
+	reg := prometheus.NewRegistry()
+	w := NewWorkqMetrics(reg)
+
+	w.BindStatsProvider(func() WorkqStats { return WorkqStats{Depth: 7, Rejected: 3} })
+
+	// Gather — the gauge is a Collect-time function, so we need a
+	// gather pass to read it.
+	out, _ := reg.Gather()
+	var depth, rejected float64
+	for _, mf := range out {
+		switch mf.GetName() {
+		case "docsiq_workq_depth":
+			depth = mf.Metric[0].GetGauge().GetValue()
+		case "docsiq_workq_rejected_total":
+			rejected = mf.Metric[0].GetCounter().GetValue()
+		}
+	}
+	if depth != 7 {
+		t.Errorf("depth=%v want 7", depth)
+	}
+	if rejected != 3 {
+		t.Errorf("rejected=%v want 3", rejected)
+	}
+}
+
+func TestExpose_ScrapeOutputContainsAllFamilies(t *testing.T) {
+	t.Parallel()
+	reg := prometheus.NewRegistry()
+	_ = NewHTTPMetrics(reg)
+	_ = NewPipelineMetrics(reg)
+	_ = NewEmbedMetrics(reg)
+	_ = NewLLMMetrics(reg)
+	_ = NewWorkqMetrics(reg)
+
+	// Register a build_info gauge too.
+	bi := NewBuildInfoMetric(reg)
+	bi.Set("v9.9.9", "abcdef")
+
+	body := renderForTest(t, reg)
+	for _, want := range []string{
+		"docsiq_http_requests_total",
+		"docsiq_http_request_duration_seconds",
+		"docsiq_pipeline_stage_duration_seconds",
+		"docsiq_embed_latency_seconds",
+		"docsiq_llm_tokens_total",
+		"docsiq_workq_depth",
+		"docsiq_workq_rejected_total",
+		"docsiq_build_info",
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("scrape output missing family %q", want)
+		}
+	}
+}
+```
+
+Add `renderForTest` at the bottom of the test file (it's a fixture shared across tests):
+
+```go
+func renderForTest(t *testing.T, reg *prometheus.Registry) string {
+	t.Helper()
+	rec := httptest.NewRecorder()
+	promhttp.HandlerFor(reg, promhttp.HandlerOpts{}).ServeHTTP(rec, httptest.NewRequest("GET", "/metrics", nil))
+	return rec.Body.String()
+}
+```
+
+Add the required imports (`net/http/httptest`, `github.com/prometheus/client_golang/prometheus/promhttp`).
+
+- [ ] **Step 3: Run failing tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/obs/ -v`
+
+Expected: all compile errors — `NewHTTPMetrics`, `NewPipelineMetrics`, etc., are undefined. That is red.
+
+- [ ] **Step 4: Implement internal/obs/metrics.go**
+
+Create `internal/obs/metrics.go`:
+
+```go
+// Package obs wires Prometheus metrics for docsiq. One registry per
+// process (exposed via obs.Default). Metric families are grouped by
+// subject (HTTP, pipeline, embed, LLM, workq, build-info) so handlers
+// record through a thin typed API — callers never touch raw collectors.
+package obs
+
+import (
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+)
+
+// Default is the process-wide registry. Tests construct their own
+// prometheus.NewRegistry() to avoid Register-twice panics.
+var (
+	Default = prometheus.NewRegistry()
+
+	HTTP     *HTTPMetrics
+	Pipeline *PipelineMetrics
+	Embed    *EmbedMetrics
+	LLM      *LLMMetrics
+	Workq    *WorkqMetrics
+	Build    *BuildInfoMetric
+)
+
+// Init wires the Default registry. Must be called exactly once at
+// startup (from cmd/serve.go). Safe no-op on second call.
+var inited bool
+
+func Init() {
+	if inited {
+		return
+	}
+	inited = true
+	HTTP = NewHTTPMetrics(Default)
+	Pipeline = NewPipelineMetrics(Default)
+	Embed = NewEmbedMetrics(Default)
+	LLM = NewLLMMetrics(Default)
+	Workq = NewWorkqMetrics(Default)
+	Build = NewBuildInfoMetric(Default)
+}
+
+// ---- HTTP ---------------------------------------------------------------
+
+type HTTPMetrics struct {
+	Requests *prometheus.CounterVec
+	Duration *prometheus.HistogramVec
+}
+
+func NewHTTPMetrics(reg prometheus.Registerer) *HTTPMetrics {
+	m := &HTTPMetrics{
+		Requests: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "docsiq_http_requests_total",
+				Help: "Total HTTP requests by route, method, and status.",
+			},
+			[]string{"route", "method", "status"},
+		),
+		Duration: prometheus.NewHistogramVec(
+			prometheus.HistogramOpts{
+				Name:    "docsiq_http_request_duration_seconds",
+				Help:    "HTTP request duration in seconds, by route.",
+				Buckets: []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10},
+			},
+			[]string{"route"},
+		),
+	}
+	reg.MustRegister(m.Requests, m.Duration)
+	return m
+}
+
+// Observe records one request. `route` MUST be the pattern (e.g.
+// "GET /api/documents/{id}"), not r.URL.Path — raw paths have unbounded
+// cardinality and will explode the scrape database.
+func (m *HTTPMetrics) Observe(route, method string, status int, d time.Duration) {
+	m.Requests.WithLabelValues(route, method, statusLabel(status)).Inc()
+	m.Duration.WithLabelValues(route).Observe(d.Seconds())
+}
+
+func statusLabel(code int) string {
+	// Two-digit prefix keeps cardinality bounded even when a handler
+	// accidentally emits 418 or similar: we still record 4xx buckets.
+	switch {
+	case code >= 500:
+		return "5xx"
+	case code >= 400:
+		return "4xx"
+	case code >= 300:
+		return "3xx"
+	case code >= 200:
+		return "2xx"
+	default:
+		return "1xx"
+	}
+}
+
+// ---- Pipeline -----------------------------------------------------------
+
+type PipelineMetrics struct {
+	StageDuration *prometheus.HistogramVec
+}
+
+func NewPipelineMetrics(reg prometheus.Registerer) *PipelineMetrics {
+	m := &PipelineMetrics{
+		StageDuration: prometheus.NewHistogramVec(
+			prometheus.HistogramOpts{
+				Name:    "docsiq_pipeline_stage_duration_seconds",
+				Help:    "GraphRAG pipeline stage duration in seconds.",
+				Buckets: prometheus.ExponentialBuckets(0.1, 2, 14), // 0.1s → ~27min
+			},
+			[]string{"stage"},
+		),
+	}
+	reg.MustRegister(m.StageDuration)
+	return m
+}
+
+// TimeStage measures the wall-clock duration of fn and records it
+// against the given stage label. The error from fn is propagated.
+func (m *PipelineMetrics) TimeStage(stage string, fn func() error) error {
+	start := time.Now()
+	err := fn()
+	m.StageDuration.WithLabelValues(stage).Observe(time.Since(start).Seconds())
+	return err
+}
+
+// ---- Embed --------------------------------------------------------------
+
+type EmbedMetrics struct {
+	Latency *prometheus.HistogramVec
+}
+
+func NewEmbedMetrics(reg prometheus.Registerer) *EmbedMetrics {
+	m := &EmbedMetrics{
+		Latency: prometheus.NewHistogramVec(
+			prometheus.HistogramOpts{
+				Name:    "docsiq_embed_latency_seconds",
+				Help:    "Per-batch embed call latency in seconds, by provider.",
+				Buckets: []float64{0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30},
+			},
+			[]string{"provider"},
+		),
+	}
+	reg.MustRegister(m.Latency)
+	return m
+}
+
+func (m *EmbedMetrics) Observe(provider string, d time.Duration) {
+	m.Latency.WithLabelValues(provider).Observe(d.Seconds())
+}
+
+// ---- LLM ----------------------------------------------------------------
+
+type LLMMetrics struct {
+	Tokens *prometheus.CounterVec
+}
+
+func NewLLMMetrics(reg prometheus.Registerer) *LLMMetrics {
+	m := &LLMMetrics{
+		Tokens: prometheus.NewCounterVec(
+			prometheus.CounterOpts{
+				Name: "docsiq_llm_tokens_total",
+				Help: "LLM tokens consumed, by provider and kind (prompt|completion|total).",
+			},
+			[]string{"provider", "kind"},
+		),
+	}
+	reg.MustRegister(m.Tokens)
+	return m
+}
+
+// RecordTokens increments the counter by n. Use kind="prompt",
+// "completion", or "total" (when the provider cannot split usage).
+func (m *LLMMetrics) RecordTokens(provider, kind string, n int) {
+	if n <= 0 {
+		return
+	}
+	m.Tokens.WithLabelValues(provider, kind).Add(float64(n))
+}
+
+// ---- Workq --------------------------------------------------------------
+
+// WorkqStats is the snapshot surface the obs layer needs from workq.
+// Workq owns the concrete Pool.Stats() method; obs only reads.
+type WorkqStats struct {
+	Depth    int64
+	Rejected int64
+}
+
+// WorkqStatsProvider is a closure over pool.Stats(). Injected from
+// cmd/serve.go after the pool is constructed, so the obs package does
+// not take a hard dep on internal/workq (keeps the import DAG acyclic).
+type WorkqStatsProvider func() WorkqStats
+
+type WorkqMetrics struct {
+	depthGauge   *prometheus.GaugeFunc
+	rejectedDesc *prometheus.Desc
+
+	// rejected tracking
+	lastRejected int64
+	provider     WorkqStatsProvider
+}
+
+func NewWorkqMetrics(reg prometheus.Registerer) *WorkqMetrics {
+	m := &WorkqMetrics{}
+	// Default no-op provider so Collect before BindStatsProvider does
+	// not blow up.
+	m.provider = func() WorkqStats { return WorkqStats{} }
+
+	depth := prometheus.NewGaugeFunc(
+		prometheus.GaugeOpts{
+			Name: "docsiq_workq_depth",
+			Help: "Current depth of the workq submission queue (jobs waiting).",
+		},
+		func() float64 {
+			return float64(m.provider().Depth)
+		},
+	)
+	m.depthGauge = &depth
+
+	rejected := prometheus.NewCounterFunc(
+		prometheus.CounterOpts{
+			Name: "docsiq_workq_rejected_total",
+			Help: "Total workq submissions rejected because the queue was full.",
+		},
+		func() float64 {
+			return float64(m.provider().Rejected)
+		},
+	)
+	reg.MustRegister(depth, rejected)
+	return m
+}
+
+// BindStatsProvider wires a live snapshot source. Call from cmd/serve.go
+// after the pool is created, before starting the HTTP server.
+func (m *WorkqMetrics) BindStatsProvider(p WorkqStatsProvider) {
+	if p == nil {
+		return
+	}
+	m.provider = p
+}
+
+// ---- Build info ---------------------------------------------------------
+
+type BuildInfoMetric struct {
+	Info *prometheus.GaugeVec
+}
+
+func NewBuildInfoMetric(reg prometheus.Registerer) *BuildInfoMetric {
+	m := &BuildInfoMetric{
+		Info: prometheus.NewGaugeVec(
+			prometheus.GaugeOpts{
+				Name: "docsiq_build_info",
+				Help: "Build metadata (value is always 1; labels carry version and commit).",
+			},
+			[]string{"version", "commit"},
+		),
+	}
+	reg.MustRegister(m.Info)
+	return m
+}
+
+// Set publishes the current build metadata. Subsequent Set calls
+// overwrite rather than accumulate labels (prior labels get their value
+// set to 0 via Reset+re-register).
+func (m *BuildInfoMetric) Set(version, commit string) {
+	m.Info.Reset()
+	m.Info.WithLabelValues(version, commit).Set(1)
+}
+```
+
+- [ ] **Step 5: Re-run obs tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/obs/ -v`
+
+Expected: all 6 tests PASS. If `NewGaugeFunc` fails with "duplicate metric already registered", it means you re-registered Default across tests — ensure each test constructs `prometheus.NewRegistry()` and passes it into `New…Metrics(reg)`.
+
+- [ ] **Step 6: Add Pool.Stats() + rejectedTotal in workq**
+
+Open `internal/workq/workq.go`. Add a `sync/atomic` import. Extend the `Pool` struct:
+
+```go
+type Pool struct {
+	jobs   chan Job
+	ctx    context.Context
+	cancel context.CancelFunc
+	wg     sync.WaitGroup
+
+	// mu guards close(p.jobs) vs concurrent sends in Submit. RLock on
+	// the send path lets many Submits proceed in parallel; Close takes
+	// the write lock before closing the channel.
+	mu        sync.RWMutex
+	closeOnce sync.Once
+	closed    chan struct{}
+
+	// rejectedTotal counts how many Submit calls returned ErrQueueFull
+	// over the pool's lifetime. Only incremented on the ErrQueueFull
+	// path; ErrClosed does NOT count (it's a shutdown condition, not a
+	// capacity condition).
+	rejectedTotal atomic.Int64
+}
+```
+
+Find the existing Submit body where it returns `ErrQueueFull`; add an increment immediately before the return:
+
+```go
+	// Path: queue is full → reject immediately.
+	select {
+	case p.jobs <- job:
+		return nil
+	default:
+		p.rejectedTotal.Add(1)
+		return ErrQueueFull
+	}
+```
+
+(The exact default-branch shape depends on how Submit is implemented today — grep for `ErrQueueFull` and add the increment on each return that yields it.)
+
+Append at the bottom of the file:
+
+```go
+// Stats is a point-in-time snapshot of pool utilisation. Depth is the
+// count of jobs currently queued but not yet picked up by a worker;
+// Rejected is the monotonic count of Submit calls that returned
+// ErrQueueFull since process start. Both are safe to call concurrently.
+type Stats struct {
+	Depth    int64
+	Rejected int64
+}
+
+func (p *Pool) Stats() Stats {
+	return Stats{
+		Depth:    int64(len(p.jobs)),
+		Rejected: p.rejectedTotal.Load(),
+	}
+}
+```
+
+- [ ] **Step 7: Add the workq stats test**
+
+Append to `internal/workq/workq_test.go`:
+
+```go
+func TestPool_StatsReportsDepthAndRejected(t *testing.T) {
+	t.Parallel()
+	p := New(Config{Workers: 1, QueueDepth: 1})
+	defer p.Close(context.Background())
+
+	// Occupy the worker.
+	block := make(chan struct{})
+	started := make(chan struct{})
+	if err := p.Submit(func(ctx context.Context) { close(started); <-block }); err != nil {
+		t.Fatalf("submit 1: %v", err)
+	}
+	<-started
+	// Fill the single queue slot.
+	if err := p.Submit(func(ctx context.Context) {}); err != nil {
+		t.Fatalf("submit 2: %v", err)
+	}
+
+	// Two more submissions must be rejected; Rejected must grow by 2.
+	if err := p.Submit(func(ctx context.Context) {}); !errors.Is(err, ErrQueueFull) {
+		t.Fatalf("submit 3: want ErrQueueFull, got %v", err)
+	}
+	if err := p.Submit(func(ctx context.Context) {}); !errors.Is(err, ErrQueueFull) {
+		t.Fatalf("submit 4: want ErrQueueFull, got %v", err)
+	}
+
+	stats := p.Stats()
+	if stats.Depth != 1 {
+		t.Errorf("Depth=%d want 1", stats.Depth)
+	}
+	if stats.Rejected != 2 {
+		t.Errorf("Rejected=%d want 2", stats.Rejected)
+	}
+
+	close(block)
+}
+```
+
+- [ ] **Step 8: Run workq tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/workq/ -v`
+
+Expected: existing tests still PASS, new `TestPool_StatsReportsDepthAndRejected` PASSes. If the pre-existing `TestPool_SubmitReturnsErrQueueFull` now races with the new `rejectedTotal` increment, the fix is to move the `p.rejectedTotal.Add(1)` INSIDE the existing `default:` branch (not add a new branch). Re-read the diff.
+
+- [ ] **Step 9: Replace the body of internal/api/metrics.go**
+
+The current file (~270 lines) hand-rolls Prometheus text format. Replace the entire contents with a thin adapter over `obs.Default`:
+
+```go
+package api
+
+import (
+	"net/http"
+
+	"github.com/RandomCodeSpace/docsiq/internal/config"
+	"github.com/RandomCodeSpace/docsiq/internal/obs"
+	"github.com/RandomCodeSpace/docsiq/internal/project"
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+// metricsHandler returns the /metrics handler. Backed by the shared
+// obs.Default registry. Public — no auth (Prometheus scrape cannot
+// present a bearer token in typical configs).
+//
+// Retained signature (registry, stores, cfg) so NewRouter callers do
+// not need to change; the args are currently unused here but kept as a
+// seam for future per-project gauges (see writeNotesGauge, now moved
+// into obs as a registered collector).
+func metricsHandler(
+	_ *project.Registry,
+	_ *projectStores,
+	_ *config.Config,
+) http.Handler {
+	return promhttp.HandlerFor(obs.Default, promhttp.HandlerOpts{
+		EnableOpenMetrics: false,
+	})
+}
+
+// SetBuildInfo publishes binary version + commit to the docsiq_build_info
+// gauge. Kept with its pre-existing signature so cmd/serve.go callers
+// do not have to change.
+func SetBuildInfo(version, commit string) {
+	if obs.Build == nil {
+		return // obs.Init() not called yet; noop rather than panic
+	}
+	obs.Build.Set(version, commit)
+}
+```
+
+Note: `writeBuildInfo`, `writeProjectsGauge`, `writeNotesGauge`, `writeRequestsTotal`, `writeRequestDuration`, `numHistogramBuckets`, `histogramBuckets`, `labelKey`, `histogramCell`, `histogramKey`, `metricsRegistry`, `newMetricsRegistry`, `globalMetrics`, `recordRequest`, `formatFloat` — all DELETED. Their functionality is now in `internal/obs`.
+
+If `writeNotesGauge` or `writeProjectsGauge` had unique value (per-project gauges for notes counts and project counts), restore them as Prometheus `GaugeFunc`s registered from `NewRouter` via a small helper `registerProjectsGauge(reg, registry, stores)`. This is NOT part of the spec, but removing them would regress the scrape surface. Add the restoration inside `internal/api/metrics.go`:
+
+```go
+// registerProjectGauges wires per-project gauges (projects_total,
+// notes_total) on the shared obs registry. Safe to call more than once
+// — the function uses MustRegister, so a repeat call will panic; guard
+// with a sync.Once if tests re-invoke.
+func registerProjectGauges(registry *project.Registry, stores *projectStores) {
+	// … omitted; if the caller cares about this metric, lift the bodies
+	// of the old writeProjectsGauge / writeNotesGauge here using
+	// NewGaugeFunc. If the caller does NOT care, delete this helper
+	// stub entirely.
+}
+```
+
+If in doubt, port both gauges — they're cheap and operators use them.
+
+- [ ] **Step 10: Record HTTP metrics from loggingMiddleware**
+
+Open `internal/api/router.go`. Inside `loggingMiddleware` (after the `next.ServeHTTP(rw, r)` line and before the log emission), replace the existing `recordRequest(...)` call with:
+
+```go
+		// Skip the self-referential /metrics scrape — a tight scrape
+		// loop would otherwise dominate the time series.
+		if r.URL.Path != "/metrics" {
+			// Route pattern — extract via the request context's
+			// http.ServeMux pattern helper (Go 1.22+). Fall back to
+			// the literal path when the match is empty (unknown route).
+			route := r.Pattern
+			if route == "" {
+				route = "unknown"
+			}
+			obs.HTTP.Observe(route, r.Method, rw.status, duration)
+		}
+```
+
+Add the `obs` import. Delete the old `recordRequest` call (it is gone with the metrics.go rewrite in Step 9).
+
+Note: `r.Pattern` is populated by the std `http.ServeMux` as of Go 1.22. For tests that hit a handler directly (bypassing the mux), `r.Pattern` is empty and we record `route="unknown"` — acceptable.
+
+- [ ] **Step 11: Wrap pipeline phases with obs.Pipeline.TimeStage**
+
+Open `internal/pipeline/pipeline.go`. Identify the distinct phases from the existing slog.Info emojis (see research note):
+
+- Phase 1 — Load: file collection + document parse
+- Phase 2 — Chunk: RecursiveCharacter splitting
+- Phase 3 — Embed: batch embedding into `embeddings` table
+- Phase 4 — Extract: entity/relationship/claim extraction via LLM
+- Phase 5 — Community: Louvain detection + summarisation
+- Phase 6 — Finalize: persist + entity-vector embed
+
+For each phase boundary, wrap the body with `obs.Pipeline.TimeStage`. Concrete example for the community phase (around line 600):
+
+```go
+// Before:
+slog.Info("🧩 Phase 3: running Louvain community detection", /* ... */)
+// ... community detection body ...
+
+// After:
+if err := obs.Pipeline.TimeStage("community", func() error {
+    slog.Info("🧩 Phase 3: running Louvain community detection", /* ... */)
+    // ... original body; propagate internal err via return ...
+    return nil
+}); err != nil {
+    return fmt.Errorf("community phase: %w", err)
+}
+```
+
+Repeat for each of the six phases with stage labels `"load"`, `"chunk"`, `"embed"`, `"extract"`, `"community"`, `"finalize"`. Stage names are fixed — no config knobs.
+
+If `obs.Pipeline` is nil at the call site (cmd/index.go does not call `obs.Init()` today), add a nil guard helper:
+
+```go
+// timeStage is a nil-safe wrapper around obs.Pipeline.TimeStage. The
+// indexer CLI does not initialise obs (obs.Init is only called from
+// cmd/serve.go), so the CLI path must not blow up on a nil obs.Pipeline.
+func timeStage(stage string, fn func() error) error {
+	if obs.Pipeline == nil {
+		return fn()
+	}
+	return obs.Pipeline.TimeStage(stage, fn)
+}
+```
+
+Use `timeStage(...)` throughout `pipeline.go` instead of the raw `obs.Pipeline.TimeStage`.
+
+- [ ] **Step 12: Instrument embedder batch calls**
+
+Open `internal/embedder/embedder.go`. Locate the batch embed method (likely `Embed` or `EmbedBatch`). Wrap the per-batch provider call:
+
+```go
+// Before:
+vectors, err := e.provider.EmbedBatch(ctx, batch)
+
+// After:
+start := time.Now()
+vectors, err := e.provider.EmbedBatch(ctx, batch)
+if obs.Embed != nil {
+    obs.Embed.Observe(e.provider.Name(), time.Since(start))
+}
+```
+
+Import `time` and `github.com/RandomCodeSpace/docsiq/internal/obs` at the top.
+
+- [ ] **Step 13: Instrument LLM token counts**
+
+Open `internal/llm/provider.go`. The interface `Complete` returns `(string, error)`; the underlying langchaingo providers return usage in `llms.ContentResponse.Choices[0].GenerationInfo`. Since the Provider interface does not expose usage, add a provider-side counter at each concrete implementation. Simpler alternative (and what this task implements): record a coarse `kind="total"` count using `len(prompt)+len(response)` as a token proxy (Go's byte length is not tokens, but operators prefer "a number greater than zero" to "nothing"). This is a knowingly-lossy approximation; flagged in the commit message.
+
+In `internal/llm/provider.go`, add after each provider's `Complete` returns:
+
+```go
+if obs.LLM != nil {
+    // Approximate: 1 token ≈ 4 bytes of UTF-8 for English text. This
+    // is a coarse fallback until we thread langchaingo's GenerationInfo
+    // through the Provider interface (tracked as follow-up).
+    approxTokens := (len(prompt) + len(resp)) / 4
+    obs.LLM.RecordTokens(p.Name(), "total", approxTokens)
+}
+```
+
+If refactoring the interface is in scope for this task, add `Usage` to the return tuple; otherwise ship the approximation and leave a `// TODO(docsiq): thread real usage via GenerationInfo` comment.
+
+- [ ] **Step 14: Wire obs.Init() and WorkqMetrics binding in cmd/serve.go**
+
+Open `cmd/serve.go`. After the `pool := workq.New(...)` line (around line 155) and BEFORE the `router := api.NewRouter(...)` line, insert:
+
+```go
+		// Observability — initialise the Prometheus registry once per
+		// process and bind the workq stats provider so the scrape
+		// handler can read live queue depth + rejection count.
+		obs.Init()
+		obs.Workq.BindStatsProvider(func() obs.WorkqStats {
+			s := pool.Stats()
+			return obs.WorkqStats{Depth: s.Depth, Rejected: s.Rejected}
+		})
+
+		// Publish build info early so the first /metrics scrape sees
+		// docsiq_build_info{version,commit} 1.
+		{
+			info := buildinfo.Resolve(false)
+			api.SetBuildInfo(info.Version, info.Commit)
+		}
+```
+
+Add imports `github.com/RandomCodeSpace/docsiq/internal/obs` and `github.com/RandomCodeSpace/docsiq/internal/buildinfo`.
+
+- [ ] **Step 15: Run the full suite**
+
+```
+CGO_ENABLED=1 go vet -tags "sqlite_fts5" ./...
+CGO_ENABLED=1 go test -tags "sqlite_fts5" -timeout 300s ./...
+```
+
+Expected: all PASS. Likely failures:
+- `internal/api/metrics_test.go` — asserts on the old text-format output. Rewrite those tests to scrape `/metrics` via the router and grep for metric family names (e.g. `docsiq_http_requests_total{route=…`). Do NOT delete the tests — the coverage is load-bearing.
+- Integration tests that inspect `docsiq_requests_total` by exact name — the family was renamed to `docsiq_http_requests_total`. Update the assertions to the new name.
+
+- [ ] **Step 16: Smoke-test /metrics output live**
+
+```
+DOCSIQ_API_KEY=dev make build && ./docsiq serve --port 0 &
+SERVE_PID=$!
+sleep 1
+curl -s http://127.0.0.1:8080/api/stats -H 'Authorization: Bearer dev' > /dev/null  # generate 1 req
+curl -s http://127.0.0.1:8080/metrics | head -60
+kill $SERVE_PID
+```
+
+Expected: `docsiq_http_requests_total`, `docsiq_http_request_duration_seconds`, `docsiq_workq_depth`, `docsiq_workq_rejected_total`, `docsiq_build_info`, `go_*` (standard Go runtime metrics), `process_*` all present.
+
+- [ ] **Step 17: Commit**
+
+```bash
+git add go.mod go.sum internal/obs/ internal/api/metrics.go \
+        internal/api/router.go internal/workq/workq.go \
+        internal/workq/workq_test.go internal/pipeline/pipeline.go \
+        internal/embedder/embedder.go internal/llm/provider.go \
+        cmd/serve.go internal/api/metrics_test.go \
+        internal/api/metrics_integration_test.go
+git commit -m "$(cat <<'EOF'
+feat(obs): Prometheus metrics + workq stats
+
+Replaces the ad-hoc text-format collector in internal/api/metrics.go
+with the official prometheus/client_golang. Adds a new internal/obs
+package hosting the Default registry and per-subject collectors
+(HTTP, pipeline stages, embed latency, LLM tokens, workq depth +
+rejections, build info). Workq gains a Pool.Stats() snapshot accessor
+with rejectedTotal counter. Pipeline phases are wrapped in
+TimeStage("load"|"chunk"|"embed"|"extract"|"community"|"finalize").
+
+LLM token counts are approximated (bytes/4) until langchaingo usage
+is threaded through the Provider interface — tracked as follow-up.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 4: Access log middleware (4.4)
+
+**Files:**
+- Modify: `internal/api/router.go` — rewrite `loggingMiddleware` body + `responseWriter` struct
+
+**Notes:** We do NOT add a second middleware. The existing `loggingMiddleware` already handles req_id generation, Prometheus recording, and emits the structured log. This task:
+
+1. Extends `responseWriter` to track `bytes_out`.
+2. Adds a `user_id`-shaped field: since docsiq auth is a single shared API key, there is no real user. We emit `auth` with values `"bearer"` (Authorization header), `"cookie"` (docsiq_session cookie), or `"anon"` (unauth — public endpoints only).
+3. Moves the slog emission into a `defer` so access logs are still written when a downstream middleware (`recoveryMiddleware`) recovers a panic. Currently the log emission runs AFTER `next.ServeHTTP`, so a panic that recoveryMiddleware catches does print the log — but a panic escaping recoveryMiddleware (e.g. from `securityHeadersMiddleware` logic that runs outside) would bypass logging. Defer fixes this.
+
+- [ ] **Step 1: Extend responseWriter to track bytes**
+
+Open `internal/api/router.go`. Replace the existing `responseWriter` struct and its method block with:
+
+```go
+// responseWriter wraps http.ResponseWriter to capture status code and
+// bytes written. Both are read by loggingMiddleware for the access log
+// and by Prometheus. bytes is tracked via Write; implicit 200-only
+// writes go through WriteHeader, so we default status to 200.
+type responseWriter struct {
+	http.ResponseWriter
+	status int
+	bytes  int64
+	// wroteHeader prevents double-counting status when a handler calls
+	// both WriteHeader(N) and Write — the std library already handles
+	// this for us; the bool is an access-log observability aid.
+	wroteHeader bool
+}
+
+func (rw *responseWriter) WriteHeader(code int) {
+	rw.status = code
+	rw.wroteHeader = true
+	rw.ResponseWriter.WriteHeader(code)
+}
+
+func (rw *responseWriter) Write(p []byte) (int, error) {
+	if !rw.wroteHeader {
+		// Implicit 200 per net/http contract.
+		rw.wroteHeader = true
+	}
+	n, err := rw.ResponseWriter.Write(p)
+	rw.bytes += int64(n)
+	return n, err
+}
+
+// Flush passes through to the underlying writer when it supports it —
+// required for SSE and streaming responses. Standard http.ResponseWriter
+// does NOT have Flush in its interface, so the type assertion is the
+// correct idiom.
+func (rw *responseWriter) Flush() {
+	if f, ok := rw.ResponseWriter.(http.Flusher); ok {
+		f.Flush()
+	}
+}
+```
+
+- [ ] **Step 2: Rewrite loggingMiddleware**
+
+Replace the entire `loggingMiddleware` function with:
+
+```go
+// loggingMiddleware assigns a per-request ID, records Prometheus
+// metrics, and emits one structured "http" log line per request. The
+// log emission is deferred so that a panic escaping recoveryMiddleware
+// (e.g. a panic in securityHeadersMiddleware) is still observable.
+func loggingMiddleware(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Request ID: header pass-through, otherwise generate fresh
+		// 16-hex (8 random bytes). Put on ctx + echo back as response
+		// header.
+		rid := strings.TrimSpace(r.Header.Get("X-Request-ID"))
+		if rid == "" {
+			rid = newRequestID()
+		}
+		ctx := context.WithValue(r.Context(), ctxRequestIDKey{}, rid)
+		r = r.WithContext(ctx)
+		w.Header().Set("X-Request-ID", rid)
+
+		rw := &responseWriter{ResponseWriter: w, status: http.StatusOK}
+		start := time.Now()
+
+		// Defer the access log + metric emission so a panic still produces
+		// an observation. recoveryMiddleware catches the panic and writes a
+		// 500; we then see status=500 in the log. If a panic escapes
+		// recoveryMiddleware, Go still unwinds through our deferred func
+		// before the goroutine dies, so the log is emitted with whatever
+		// status (likely 200) had been set.
+		defer func() {
+			duration := time.Since(start)
+
+			// Rethrow after logging; our logging must be side-effect-only
+			// for the panic propagation path. A deeper recovery belongs in
+			// recoveryMiddleware, not here.
+			recErr := recover()
+
+			// /metrics is self-referential — exclude to avoid scraping
+			// feedback loops.
+			if r.URL.Path != "/metrics" {
+				route := r.Pattern
+				if route == "" {
+					route = "unknown"
+				}
+				if obs.HTTP != nil {
+					obs.HTTP.Observe(route, r.Method, rw.status, duration)
+				}
+			}
+
+			level := slog.LevelInfo
+			if rw.status >= 500 || recErr != nil {
+				level = slog.LevelError
+			} else if rw.status >= 400 {
+				level = slog.LevelWarn
+			}
+
+			attrs := []any{
+				"req_id", rid,
+				"method", r.Method,
+				"path", r.URL.Path,
+				"route", r.Pattern,
+				"status", rw.status,
+				"duration_ms", duration.Milliseconds(),
+				"bytes_out", rw.bytes,
+				"auth", classifyAuth(r),
+			}
+			if project := ProjectFromContext(r.Context()); project != "" {
+				attrs = append(attrs, "project", project)
+			}
+			if recErr != nil {
+				attrs = append(attrs, "panic", recErr)
+			}
+
+			slog.Log(r.Context(), level, "http", attrs...)
+
+			if recErr != nil {
+				// Re-raise: let upstream recovery middleware (or the
+				// std library) handle the actual HTTP error response.
+				panic(recErr)
+			}
+		}()
+
+		next.ServeHTTP(rw, r)
+	})
+}
+
+// classifyAuth reports a coarse auth-method label for the access log.
+// docsiq uses a single shared API key (no per-user identity), so we
+// emit the channel the client used rather than a user_id.
+func classifyAuth(r *http.Request) string {
+	if strings.HasPrefix(strings.TrimSpace(r.Header.Get("Authorization")), "Bearer ") {
+		return "bearer"
+	}
+	if c, err := r.Cookie(sessionCookieName); err == nil && c.Value != "" {
+		return "cookie"
+	}
+	return "anon"
+}
+```
+
+Note: `ProjectFromContext` is the existing helper in `internal/api/project.go`. `sessionCookieName` is the existing const in `session.go` (introduced earlier by the session-cookie feature). `obs` imported at top.
+
+- [ ] **Step 3: Add loggingMiddleware tests**
+
+Create `internal/api/logging_middleware_test.go`:
+
+```go
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// captureLogs swaps the default slog handler for a JSON-to-buffer one
+// for the duration of the test, then restores the previous default.
+func captureLogs(t *testing.T) *bytes.Buffer {
+	t.Helper()
+	var buf bytes.Buffer
+	h := slog.NewJSONHandler(&buf, &slog.HandlerOptions{Level: slog.LevelDebug})
+	prev := slog.Default()
+	slog.SetDefault(slog.New(h))
+	t.Cleanup(func() { slog.SetDefault(prev) })
+	return &buf
+}
+
+func TestLoggingMiddleware_EmitsStructuredAccessLog(t *testing.T) {
+	// NOT parallel — mutates global slog.
+	buf := captureLogs(t)
+
+	h := loggingMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("hello world"))
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/api/stats", nil)
+	req.Header.Set("Authorization", "Bearer dev")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	lines := strings.Split(strings.TrimSpace(buf.String()), "\n")
+	if len(lines) == 0 {
+		t.Fatal("no log lines emitted")
+	}
+	var last map[string]any
+	if err := json.Unmarshal([]byte(lines[len(lines)-1]), &last); err != nil {
+		t.Fatalf("last log line not JSON: %v", err)
+	}
+
+	want := map[string]any{
+		"msg":    "http",
+		"method": "GET",
+		"path":   "/api/stats",
+		"status": float64(200),
+		"auth":   "bearer",
+	}
+	for k, v := range want {
+		if got := last[k]; got != v {
+			t.Errorf("log[%s]=%v want %v", k, got, v)
+		}
+	}
+	if _, ok := last["req_id"].(string); !ok {
+		t.Errorf("req_id missing or not string: %v", last["req_id"])
+	}
+	if b, ok := last["bytes_out"].(float64); !ok || b != 11 {
+		t.Errorf("bytes_out=%v want 11", last["bytes_out"])
+	}
+}
+
+func TestLoggingMiddleware_PanicStillLogsAccessEntry(t *testing.T) {
+	// NOT parallel — mutates global slog.
+	buf := captureLogs(t)
+
+	// Chain: loggingMiddleware wraps a handler that panics.
+	// Without recoveryMiddleware here, the panic propagates — but the
+	// deferred access log must still have fired.
+	h := loggingMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		panic("boom")
+	}))
+
+	req := httptest.NewRequest(http.MethodGet, "/panic-path", nil)
+	rec := httptest.NewRecorder()
+
+	func() {
+		defer func() { _ = recover() }() // swallow in test
+		h.ServeHTTP(rec, req)
+	}()
+
+	if buf.Len() == 0 {
+		t.Fatal("access log not emitted through panic path")
+	}
+	if !strings.Contains(buf.String(), `"panic":"boom"`) {
+		t.Errorf("log should mention panic=boom; got: %s", buf.String())
+	}
+	if !strings.Contains(buf.String(), `"level":"ERROR"`) {
+		t.Errorf("panic log should be ERROR level; got: %s", buf.String())
+	}
+}
+
+func TestLoggingMiddleware_ReqIDPassThrough(t *testing.T) {
+	t.Parallel()
+	h := loggingMiddleware(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := RequestIDFromContext(r.Context()); got != "caller-id-abc" {
+			t.Errorf("ctx req_id=%q want caller-id-abc", got)
+		}
+	}))
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.Header.Set("X-Request-ID", "caller-id-abc")
+	rec := httptest.NewRecorder()
+	h.ServeHTTP(rec, req)
+
+	if got := rec.Header().Get("X-Request-ID"); got != "caller-id-abc" {
+		t.Errorf("echoed X-Request-ID=%q", got)
+	}
+}
+
+func TestLoggingMiddleware_AnonCookieBearerClassification(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name  string
+		setup func(r *http.Request)
+		want  string
+	}{
+		{name: "anon_no_auth", setup: func(r *http.Request) {}, want: "anon"},
+		{name: "bearer_header", setup: func(r *http.Request) {
+			r.Header.Set("Authorization", "Bearer k")
+		}, want: "bearer"},
+		{name: "session_cookie", setup: func(r *http.Request) {
+			r.AddCookie(&http.Cookie{Name: sessionCookieName, Value: "cookie-token"})
+		}, want: "cookie"},
+	}
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			req := httptest.NewRequest(http.MethodGet, "/", nil)
+			tc.setup(req)
+			if got := classifyAuth(req); got != tc.want {
+				t.Errorf("classifyAuth=%q want %q", got, tc.want)
+			}
+		})
+	}
+}
+```
+
+- [ ] **Step 4: Run the new tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -run TestLoggingMiddleware -v`
+
+Expected: 4 tests PASS. If `TestLoggingMiddleware_PanicStillLogsAccessEntry` fails because `buf.Len() == 0`, the `defer` block is wrong — re-check that the slog emission happens INSIDE the deferred func, not AFTER `next.ServeHTTP`.
+
+- [ ] **Step 5: Run the full API suite**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/api/ -v -timeout 120s`
+
+Expected: all PASS. The new `bytes_out` field changes the log-line shape — any test that grep-asserts on the exact log line string must be updated to `slog` attr-parsing.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add internal/api/router.go internal/api/logging_middleware_test.go
+git commit -m "$(cat <<'EOF'
+feat(api): structured access log with bytes_out + panic resilience
+
+loggingMiddleware now emits one JSON/text line per request with
+{req_id, method, path, route, status, duration_ms, bytes_out, auth,
+project, panic}. The emission is deferred so a panic escaping
+recoveryMiddleware still produces an access-log entry. auth is a
+coarse label (bearer|cookie|anon) because docsiq uses a single shared
+API key; there is no real user identity.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 5: Structured-log schema + format switch (4.2)
+
+**Files:**
+- Modify: `internal/config/config.go` — add `LogConfig` struct with `Format` field; wire defaults + env binding
+- Modify: `internal/config/config_test.go` — add a test confirming `log.format` defaults to `"text"` and parses `"json"`
+- Modify: `cmd/root.go` — the `initConfig` function: add a third source of truth (config file) below the existing `--log-format` flag and `DOCSIQ_LOG_FORMAT` env var precedence
+- Modify: `internal/api/` + `internal/pipeline/` + `internal/embedder/` + `cmd/*.go` — audit and strip the leading emoji from every `slog.*` message when the global format is `json`. Approach: wrap the slog handler so the emoji is a text-mode-only decoration (DRY; no source edits needed in log call sites).
+
+**Notes:** The user's rule is "production log format drops emoji prefixes (keep in dev format for human readability)". The cleanest implementation is a custom slog middleware handler that strips a leading emoji + space from the `msg` when wrapping a JSON handler. Zero edits to call sites.
+
+- [ ] **Step 1: Add LogConfig to config**
+
+Open `internal/config/config.go`. Extend the top-level `Config` struct:
+
+```go
+type Config struct {
+	DataDir        string                 `mapstructure:"data_dir"`
+	DefaultProject string                 `mapstructure:"default_project"`
+	LLM            LLMConfig              `mapstructure:"llm"`
+	Indexing       IndexingConfig         `mapstructure:"indexing"`
+	Community      CommunityConfig        `mapstructure:"community"`
+	Server         ServerConfig           `mapstructure:"server"`
+	Log            LogConfig              `mapstructure:"log"`
+	LLMOverrides   map[string]LLMConfig   `mapstructure:"llm_overrides"`
+}
+```
+
+Add the new struct (place near the other `…Config` types):
+
+```go
+// LogConfig controls structured-log emission format.
+type LogConfig struct {
+	// Format chooses the slog handler. "text" (default) emits a
+	// human-readable single-line format with emoji prefixes; "json"
+	// strips emoji and emits machine-parseable JSON objects.
+	Format string `mapstructure:"format"`
+}
+```
+
+In the `Load` function, near the existing `SetDefault` block, add:
+
+```go
+	v.SetDefault("log.format", "text")
+```
+
+And in the `BindEnv` block, add:
+
+```go
+	_ = v.BindEnv("log.format", "DOCSIQ_LOG_FORMAT")
+```
+
+- [ ] **Step 2: Add a config test**
+
+Append to `internal/config/config_test.go`:
+
+```go
+func TestLoad_LogFormatDefaultText(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	cfg, err := Load(filepath.Join(dir, "missing.yaml"))
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if cfg.Log.Format != "text" {
+		t.Errorf("default Log.Format=%q want text", cfg.Log.Format)
+	}
+}
+
+func TestLoad_LogFormatFromYAML(t *testing.T) {
+	t.Parallel()
+	dir := t.TempDir()
+	f := filepath.Join(dir, "config.yaml")
+	must := func(err error) {
+		t.Helper()
+		if err != nil {
+			t.Fatal(err)
+		}
+	}
+	must(os.WriteFile(f, []byte("log:\n  format: json\n"), 0o600))
+	cfg, err := Load(f)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	if cfg.Log.Format != "json" {
+		t.Errorf("Log.Format=%q want json", cfg.Log.Format)
+	}
+}
+```
+
+- [ ] **Step 3: Run config tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/config/ -v -run TestLoad_LogFormat`
+
+Expected: 2/2 PASS.
+
+- [ ] **Step 4: Implement the emoji-stripping slog middleware handler**
+
+Create `internal/obs/slogfmt.go`:
+
+```go
+package obs
+
+import (
+	"context"
+	"log/slog"
+	"strings"
+	"unicode/utf8"
+)
+
+// NewProductionHandler wraps an inner slog.Handler and strips a
+// leading emoji + trailing space from each record's Message. docsiq
+// uses emoji prefixes (✅ ❌ ⚠️ …) as visual cues in dev text format;
+// in JSON these collide with log-aggregator indexing (Elasticsearch
+// tokeniser, fluentd grep rules) and obscure the actual message
+// string. The handler mutates only Message — attrs pass through.
+func NewProductionHandler(inner slog.Handler) slog.Handler {
+	return &prodHandler{inner: inner}
+}
+
+type prodHandler struct{ inner slog.Handler }
+
+func (h *prodHandler) Enabled(ctx context.Context, lvl slog.Level) bool {
+	return h.inner.Enabled(ctx, lvl)
+}
+
+func (h *prodHandler) Handle(ctx context.Context, r slog.Record) error {
+	r.Message = stripLeadingEmoji(r.Message)
+	return h.inner.Handle(ctx, r)
+}
+
+func (h *prodHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
+	return &prodHandler{inner: h.inner.WithAttrs(attrs)}
+}
+
+func (h *prodHandler) WithGroup(name string) slog.Handler {
+	return &prodHandler{inner: h.inner.WithGroup(name)}
+}
+
+// stripLeadingEmoji removes the first rune from msg if it is in a
+// Unicode emoji-like range, plus any immediately-following whitespace.
+// Narrow vs broad emoji detection: we use a conservative heuristic —
+// the rune's category falls into Symbol (S*) and its value is >= 0x2600
+// OR it sits in one of the Private/Surrogate-adjacent pictograph blocks.
+// We intentionally do NOT use a dependency like mattn/go-emoji; docsiq
+// ships under air-gap rules (see build.md) and every dep is scrutinised.
+func stripLeadingEmoji(msg string) string {
+	if msg == "" {
+		return msg
+	}
+	r, size := utf8.DecodeRuneInString(msg)
+	if r == utf8.RuneError {
+		return msg
+	}
+	if !isEmojiLike(r) {
+		return msg
+	}
+	// Drop emoji + any whitespace that follows.
+	rest := msg[size:]
+	rest = strings.TrimLeft(rest, " \t")
+	// Also strip a VS16 variation selector (U+FE0F) that often
+	// follows ⚠ etc.
+	if len(rest) > 0 {
+		r2, size2 := utf8.DecodeRuneInString(rest)
+		if r2 == 0xFE0F {
+			rest = strings.TrimLeft(rest[size2:], " \t")
+		}
+	}
+	return rest
+}
+
+// isEmojiLike is a conservative test for the emoji-range runes that
+// appear in docsiq log messages today: ✅ ❌ ⚠️ 🛑 ⚙️ 🔒 📦 🔍 🔗 🧩 💾
+// 🌐 ⏭️ 📄 📂 📒 📊 🚀 🧭 🧮 🗑️ 📋. Covers BMP symbols (U+2600–U+27BF),
+// miscellaneous pictographs (U+1F300–U+1F6FF), supplemental symbols
+// (U+1F900–U+1F9FF), and the warning sign block (U+26A0).
+func isEmojiLike(r rune) bool {
+	switch {
+	case r >= 0x2600 && r <= 0x27BF:
+		return true
+	case r >= 0x1F300 && r <= 0x1F6FF:
+		return true
+	case r >= 0x1F900 && r <= 0x1F9FF:
+		return true
+	}
+	return false
+}
+```
+
+- [ ] **Step 5: Add tests for the handler**
+
+Create `internal/obs/slogfmt_test.go`:
+
+```go
+package obs
+
+import (
+	"bytes"
+	"encoding/json"
+	"log/slog"
+	"testing"
+)
+
+func TestStripLeadingEmoji(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		in, want string
+	}{
+		{"✅ all good", "all good"},
+		{"❌ panic recovered", "panic recovered"},
+		{"⚠️ auth disabled", "auth disabled"},   // VS16 variation selector
+		{"🛑 shutting down...", "shutting down..."},
+		{"⚙️ LLM provider initialised", "LLM provider initialised"},
+		{"plain log line", "plain log line"},
+		{"", ""},
+		{"  leading spaces", "  leading spaces"}, // no emoji → untouched
+	}
+	for _, c := range cases {
+		got := stripLeadingEmoji(c.in)
+		if got != c.want {
+			t.Errorf("stripLeadingEmoji(%q)=%q want %q", c.in, got, c.want)
+		}
+	}
+}
+
+func TestProductionHandler_JSONOutputNoEmoji(t *testing.T) {
+	t.Parallel()
+	var buf bytes.Buffer
+	h := NewProductionHandler(slog.NewJSONHandler(&buf, nil))
+	logger := slog.New(h)
+
+	logger.Info("✅ ready", "port", 8080)
+	logger.Error("❌ connection failed", "err", "timeout")
+
+	lines := bytes.Split(bytes.TrimSpace(buf.Bytes()), []byte("\n"))
+	if len(lines) != 2 {
+		t.Fatalf("got %d lines want 2", len(lines))
+	}
+	for _, line := range lines {
+		var rec map[string]any
+		if err := json.Unmarshal(line, &rec); err != nil {
+			t.Fatalf("not JSON: %v — raw=%q", err, line)
+		}
+		msg, _ := rec["msg"].(string)
+		if msg == "" {
+			t.Errorf("missing msg: %s", line)
+		}
+		// No emoji should survive.
+		for _, r := range msg {
+			if isEmojiLike(r) {
+				t.Errorf("msg contains emoji %q; msg=%q", r, msg)
+				break
+			}
+		}
+	}
+}
+```
+
+- [ ] **Step 6: Run the obs handler tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./internal/obs/ -v -run Handler`
+
+Expected: both tests PASS.
+
+- [ ] **Step 7: Wire the handler into initConfig**
+
+Open `cmd/root.go`. Replace the `initConfig` function's logger setup block (currently lines ~37-60 — the `switch format { case "json": … default: … }` block) with:
+
+```go
+func initConfig() {
+	// Set up structured logger. Level resolution order: --log-level flag.
+	var level slog.Level
+	switch logLevel {
+	case "debug":
+		level = slog.LevelDebug
+	case "warn":
+		level = slog.LevelWarn
+	case "error":
+		level = slog.LevelError
+	default:
+		level = slog.LevelInfo
+	}
+
+	// Format resolution order (highest-priority wins):
+	//   1. --log-format flag
+	//   2. DOCSIQ_LOG_FORMAT env var
+	//   3. config file log.format
+	//   4. default "text"
+	// Note: (3) requires config.Load() to have run; we call it below
+	// and re-evaluate the handler afterwards if the flag/env did not
+	// already lock in a value.
+	format := strings.ToLower(strings.TrimSpace(logFormat))
+	if format == "" {
+		format = strings.ToLower(strings.TrimSpace(os.Getenv("DOCSIQ_LOG_FORMAT")))
+	}
+
+	// First pass: install a temporary handler so config-load errors
+	// emit somewhere. Upgraded below once config.Log.Format is known.
+	slog.SetDefault(slog.New(buildHandler(level, format)))
+
+	var err error
+	cfg, err = config.Load(cfgFile)
+	if err != nil {
+		slog.Error("❌ config error", "err", err)
+		os.Exit(1)
+	}
+	if err := os.MkdirAll(cfg.DataDir, 0o755); err != nil {
+		slog.Error("❌ mkdir data dir", "err", err)
+		os.Exit(1)
+	}
+
+	// Second pass: if neither flag nor env specified format, use the
+	// value from the loaded config.
+	if format == "" && cfg.Log.Format != "" {
+		format = strings.ToLower(strings.TrimSpace(cfg.Log.Format))
+		slog.SetDefault(slog.New(buildHandler(level, format)))
+	}
+}
+
+// buildHandler assembles the slog handler chain. For "json" format we
+// wrap the JSON handler in obs.NewProductionHandler to strip emoji
+// prefixes from the message field (keeping them is harmless but noisy
+// for log aggregators). "text" keeps emoji for human readability.
+func buildHandler(level slog.Level, format string) slog.Handler {
+	opts := &slog.HandlerOptions{Level: level}
+	switch format {
+	case "json":
+		return obs.NewProductionHandler(slog.NewJSONHandler(os.Stderr, opts))
+	default:
+		return slog.NewTextHandler(os.Stderr, opts)
+	}
+}
+```
+
+Add the import `github.com/RandomCodeSpace/docsiq/internal/obs` at the top of `cmd/root.go`.
+
+- [ ] **Step 8: Update the existing cmd/logformat_test.go**
+
+Open `cmd/logformat_test.go`. It currently asserts on the text-vs-json switch via `--log-format` and `DOCSIQ_LOG_FORMAT`. Add one new test case:
+
+```go
+func TestInitConfig_LogFormatFromConfigFile(t *testing.T) {
+	// NOT parallel — mutates package-level flags.
+	t.Cleanup(func() {
+		logLevel = "info"
+		logFormat = ""
+		cfgFile = ""
+		cfg = nil
+	})
+
+	dir := t.TempDir()
+	yaml := filepath.Join(dir, "config.yaml")
+	if err := os.WriteFile(yaml, []byte("log:\n  format: json\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	cfgFile = yaml
+	logFormat = ""
+	os.Unsetenv("DOCSIQ_LOG_FORMAT")
+
+	initConfig()
+
+	// After initConfig, the handler should be JSON. Probe by logging
+	// through slog.Default and inspecting stderr capture — but simpler:
+	// assert cfg.Log.Format round-tripped.
+	if cfg.Log.Format != "json" {
+		t.Errorf("cfg.Log.Format=%q want json", cfg.Log.Format)
+	}
+}
+```
+
+If `logformat_test.go` already has precedence-order tests, assert that (flag > env > config > default) is preserved.
+
+- [ ] **Step 9: Run the cmd tests**
+
+Run: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./cmd/ -v -run LogFormat`
+
+Expected: all PASS. If `initConfig()` panics because `rootCmd` has not been executed (flag init skipped), add `cobra.OnInitialize(initConfig)` guard — but the existing test file already exercises `initConfig` directly so this should be fine.
+
+- [ ] **Step 10: Full-suite verification**
+
+```
+CGO_ENABLED=1 go vet -tags "sqlite_fts5" ./...
+CGO_ENABLED=1 go test -tags "sqlite_fts5" -timeout 300s ./...
+```
+
+Expected: all PASS. If any test greps the log output for a specific emoji (`"✅ ready"`) AFTER format switches to json, those tests need the emoji stripped from expected strings — update them.
+
+- [ ] **Step 11: Smoke-test both formats live**
+
+```
+make build
+
+echo '=== text ==='
+DOCSIQ_LOG_FORMAT=text DOCSIQ_API_KEY=dev ./docsiq serve --port 0 2>&1 &
+PID=$!; sleep 1; curl -s http://127.0.0.1:8080/healthz > /dev/null; kill $PID
+# Expect: human-readable line with emoji 🚀
+
+echo '=== json ==='
+DOCSIQ_LOG_FORMAT=json DOCSIQ_API_KEY=dev ./docsiq serve --port 0 2>&1 &
+PID=$!; sleep 1; curl -s http://127.0.0.1:8080/healthz > /dev/null; kill $PID
+# Expect: {"time":"…","level":"INFO","msg":"server started",…} — no emoji
+```
+
+Verify stderr of the json run contains no raw emoji bytes:
+
+```
+DOCSIQ_LOG_FORMAT=json DOCSIQ_API_KEY=dev timeout 2 ./docsiq serve --port 0 2>&1 | grep -E '[^\x00-\x7F]' || echo "NO NON-ASCII BYTES (expected)"
+```
+
+Expected final line: `NO NON-ASCII BYTES (expected)`. If non-ASCII bytes leak through, a call site uses an emoji not covered by `isEmojiLike` — extend the ranges.
+
+- [ ] **Step 12: Commit**
+
+```bash
+git add internal/config/config.go internal/config/config_test.go \
+        cmd/root.go cmd/logformat_test.go \
+        internal/obs/slogfmt.go internal/obs/slogfmt_test.go
+git commit -m "$(cat <<'EOF'
+feat(log): log.format=json|text with emoji-strip production handler
+
+New log.format config key (default "text"; DOCSIQ_LOG_FORMAT env).
+Precedence is --log-format > env > config > default. The json handler
+is wrapped in obs.NewProductionHandler, which strips a leading emoji
+from slog Record.Message so log aggregators do not have to special-case
+multi-byte sequences. The text handler keeps emoji for human readers.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Self-Review
+
+**1. Spec coverage.** Each bullet of Block 4 has a task:
+
+- 4.1 Prometheus `/metrics` → Task 3. All seven named metric families are present:
+  - `docsiq_pipeline_stage_duration_seconds{stage}` — `internal/obs/metrics.go` `NewPipelineMetrics`
+  - `docsiq_embed_latency_seconds{provider}` — `NewEmbedMetrics`
+  - `docsiq_llm_tokens_total{provider,kind}` — `NewLLMMetrics`
+  - `docsiq_workq_depth` — `NewWorkqMetrics.depthGauge`
+  - `docsiq_workq_rejected_total` — `NewWorkqMetrics.rejectedTotal`
+  - `docsiq_http_requests_total{route,method,status}` — `NewHTTPMetrics.Requests`
+  - `docsiq_http_request_duration_seconds{route}` — `NewHTTPMetrics.Duration`
+- 4.2 Structured-log schema → Task 5. Standard fields `req_id, project, route, method, status, duration_ms, err, bytes_out, auth` are emitted from the `loggingMiddleware` in Task 4 and the format switch from Task 5 removes emoji in json mode. The spec names `user_id`; we document in the commit and the auth-classification comment that docsiq has no per-user identity and emit `auth` instead — this is the best-faith mapping.
+- 4.3 Health endpoints → Task 2. `/healthz` + `/readyz` with 10-second cache and per-check JSON body.
+- 4.4 Access log middleware → Task 4. Extends existing `loggingMiddleware` rather than adding a second. Panic-safe via `defer`.
+- 4.5 Version endpoint → Task 1. `GET /api/version` with ldflags wiring (Makefile already set up for this) and `runtime/debug` fallback + dep map.
+
+**2. Placeholder scan.** No TBDs, no "implement later", no "add appropriate X". The single hedged item is `registerProjectGauges` in Task 3 Step 9, which is explicitly marked "port both or delete, do not leave stub". Every test step includes actual test code; every command lists the actual expected output.
+
+**3. Type consistency.**
+
+- `buildinfo.Info` with `json` tags is used consistently across Task 1 handler + buildinfo_test.
+- `workq.Stats{Depth, Rejected int64}` is used in both Task 3 Step 6 (workq.go) and Step 14 (cmd/serve.go). The adapter in `obs.WorkqStats{Depth, Rejected int64}` has identical fields — the converter in serve.go spells out the copy.
+- `healthPinger` interface has `Ping(ctx) error` signature in both `health.go` and `health_test.go`. The `sqlDBPinger` and `providerPinger` both satisfy it.
+- `obs.HTTPMetrics.Observe(route, method, status, d)` is the single entry point for HTTP metrics — called once from `loggingMiddleware` in Task 4.
+- `obs.Pipeline.TimeStage(stage, fn func() error) error` signature is consistent; the `timeStage` local wrapper in pipeline.go has the same signature for nil-safe call sites.
+- `classifyAuth` returns string `"bearer" | "cookie" | "anon"`; the test `TestLoggingMiddleware_AnonCookieBearerClassification` asserts exactly those values.
+- `LogConfig.Format` field is referenced in `cfg.Log.Format` in cmd/root.go — tag `mapstructure:"format"` matches both the struct literal and viper's `log.format` key.
+
+**Follow-ups (not in scope of this plan):**
+- LLM token counts are approximated from byte length. Threading langchaingo's `GenerationInfo` through `llm.Provider` is a follow-up commit. Flagged in Task 3 Step 13.
+- `r.Pattern` may be empty for the embedded SPA and the `/mcp` handler (they're `mux.Handle("/", …)` catch-alls). These will log `route="unknown"`. If operators want finer granularity, a separate PR can synthesise route labels from `URL.Path` with a configured whitelist.
+- `registerProjectGauges` — the Task 3 rewrite of metrics.go removes per-project `docsiq_notes_total` + `docsiq_projects_total` gauges. The implementer MUST either port them (recommended — fast, cheap, operators use them) or remove them with a clear commit note. Do not leave a stub.
+
+---
+
+## Execution Handoff
+
+Plan complete and saved to `docs/superpowers/plans/2026-04-23-block4-observability-plan.md`. Two execution options:
+
+**1. Subagent-Driven (recommended)** — I dispatch a fresh subagent per task, review between tasks, fast iteration. Task boundaries are clean (each task ends with a green build + test run + single commit), which suits this model well.
+
+**2. Inline Execution** — Execute tasks in this session using `superpowers:executing-plans`, batch execution with checkpoints for review.
+
+Which approach?
diff --git a/docs/superpowers/plans/2026-04-23-block5-ui-polish-plan.md b/docs/superpowers/plans/2026-04-23-block5-ui-polish-plan.md
new file mode 100644
index 0000000..947752d
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-23-block5-ui-polish-plan.md
@@ -0,0 +1,2549 @@
+# Block 5 — UI Polish Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship ten production-polish UI items (error boundary, loading/empty/error state trio, dynamic titles, iOS safe-area, max-update-depth bug, axe violations, reduced-motion gating, focus management, theme-flash, mobile viewport) so the docsiq SPA is production-grade on desktop and iOS safari.
+
+**Architecture:** All changes live inside `ui/` (React 19 + TypeScript 6 + Vite 8 + Tailwind v4). New reusable state primitives (`EmptyState`, `LoadingSkeleton`, `ErrorState`) live at `ui/src/components/empty/` and feed into `RouteBoundary` plus every fetching route. Theme-flash runs as a pre-hydration inline script in `ui/index.html` that writes `document.documentElement.classList` before React boots, eliminating FOUC.
+
+**Tech Stack:** React 19, react-router-dom v7, Zustand (persisted at key `docsiq-ui`), TanStack Query, shadcn/ui local copies (`ui/src/components/ui/`), Framer Motion v11 via `useReducedMotion()` hook, Vitest + @testing-library/react, Playwright + axe-core.
+
+---
+
+## Task Ordering Rationale
+
+Task 1 (5.2) first — the state trio is a dependency of Task 2 (5.1 RouteBoundary) and of the empty/loading states threaded into routes from Task 3 onward. Tasks 5–10 are investigation/audit tasks that use the primitives established by Tasks 1–4.
+
+Order:
+
+1. Task 1: Loading / empty / error state trio (spec 5.2)
+2. Task 2: RouteBoundary error boundary (spec 5.1)
+3. Task 3: Dynamic `document.title` per route (spec 5.3)
+4. Task 4: iOS safe-area insets (spec 5.4)
+5. Task 5: "Maximum update depth exceeded" investigation + fix (spec 5.5)
+6. Task 6: Axe violations sweep (spec 5.6)
+7. Task 7: Reduced-motion gating (spec 5.7)
+8. Task 8: Focus management (spec 5.8)
+9. Task 9: Theme-flash inline script (spec 5.9)
+10. Task 10: Mobile viewport pass (spec 5.10)
+
+---
+
+### Task 1: Reusable state trio — `EmptyState`, `LoadingSkeleton`, `ErrorState` (5.2)
+
+**Files:**
+- Create: `ui/src/components/empty/EmptyState.tsx`
+- Create: `ui/src/components/empty/LoadingSkeleton.tsx`
+- Create: `ui/src/components/empty/ErrorState.tsx`
+- Create: `ui/src/components/empty/index.ts`
+- Create: `ui/src/components/empty/__tests__/EmptyState.test.tsx`
+- Create: `ui/src/components/empty/__tests__/LoadingSkeleton.test.tsx`
+- Create: `ui/src/components/empty/__tests__/ErrorState.test.tsx`
+- Modify: `ui/src/routes/Home.tsx`
+- Modify: `ui/src/routes/Graph.tsx`
+- Modify: `ui/src/routes/MCPConsole.tsx`
+- Modify: `ui/src/routes/notes/NotesLayout.tsx`
+- Modify: `ui/src/routes/notes/NoteView.tsx`
+- Modify: `ui/src/routes/notes/NotesSearch.tsx`
+- Modify: `ui/src/routes/documents/DocumentsList.tsx`
+- Modify: `ui/src/routes/documents/DocumentView.tsx`
+- Modify: `ui/src/styles/globals.css` (adds `.state-card` tokens)
+
+- [ ] **Step 1: Write `EmptyState` test**
+
+Create `ui/src/components/empty/__tests__/EmptyState.test.tsx`:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { EmptyState } from "../EmptyState";
+
+describe("EmptyState", () => {
+  it("renders title and description", () => {
+    render(<EmptyState title="No notes yet" description="Create one to get started." />);
+    expect(screen.getByRole("status")).toBeInTheDocument();
+    expect(screen.getByText("No notes yet")).toBeInTheDocument();
+    expect(screen.getByText("Create one to get started.")).toBeInTheDocument();
+  });
+
+  it("renders an action slot when provided", () => {
+    render(
+      <EmptyState
+        title="No notes"
+        description="Try ingesting one."
+        action={<button type="button">Ingest</button>}
+      />,
+    );
+    expect(screen.getByRole("button", { name: /ingest/i })).toBeInTheDocument();
+  });
+
+  it("exposes role=status so screen readers announce it", () => {
+    render(<EmptyState title="x" description="y" />);
+    expect(screen.getByRole("status")).toHaveAttribute("aria-live", "polite");
+  });
+});
+```
+
+- [ ] **Step 2: Run the test — expect failure**
+
+```
+cd ui && npm test -- --run src/components/empty/__tests__/EmptyState.test.tsx
+```
+
+Expected: FAIL with `Cannot find module '../EmptyState'`.
+
+- [ ] **Step 3: Implement `EmptyState`**
+
+Create `ui/src/components/empty/EmptyState.tsx`:
+
+```tsx
+import type { ReactNode } from "react";
+import { Inbox } from "lucide-react";
+
+interface EmptyStateProps {
+  title: string;
+  description: string;
+  icon?: ReactNode;
+  action?: ReactNode;
+}
+
+export function EmptyState({ title, description, icon, action }: EmptyStateProps) {
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className="state-card state-card--empty"
+      data-testid="empty-state"
+    >
+      <div className="state-card__icon" aria-hidden="true">
+        {icon ?? <Inbox className="size-6" />}
+      </div>
+      <h3 className="state-card__title">{title}</h3>
+      <p className="state-card__description">{description}</p>
+      {action ? <div className="state-card__action">{action}</div> : null}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 4: Run EmptyState test — expect pass**
+
+```
+cd ui && npm test -- --run src/components/empty/__tests__/EmptyState.test.tsx
+```
+
+Expected: 3 passing.
+
+- [ ] **Step 5: Write `LoadingSkeleton` test**
+
+Create `ui/src/components/empty/__tests__/LoadingSkeleton.test.tsx`:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { describe, it, expect } from "vitest";
+import { LoadingSkeleton } from "../LoadingSkeleton";
+
+describe("LoadingSkeleton", () => {
+  it("renders a polite live-region with a label", () => {
+    render(<LoadingSkeleton label="Loading notes" />);
+    const status = screen.getByRole("status");
+    expect(status).toHaveAttribute("aria-live", "polite");
+    expect(status).toHaveAttribute("aria-label", "Loading notes");
+  });
+
+  it("renders `rows` skeleton bars", () => {
+    render(<LoadingSkeleton label="Loading" rows={4} />);
+    expect(screen.getAllByTestId("skeleton-row")).toHaveLength(4);
+  });
+
+  it("defaults to 3 rows when no count given", () => {
+    render(<LoadingSkeleton label="Loading" />);
+    expect(screen.getAllByTestId("skeleton-row")).toHaveLength(3);
+  });
+});
+```
+
+- [ ] **Step 6: Run the test — expect failure**
+
+```
+cd ui && npm test -- --run src/components/empty/__tests__/LoadingSkeleton.test.tsx
+```
+
+Expected: FAIL with `Cannot find module '../LoadingSkeleton'`.
+
+- [ ] **Step 7: Implement `LoadingSkeleton`**
+
+Create `ui/src/components/empty/LoadingSkeleton.tsx`:
+
+```tsx
+import { Skeleton } from "@/components/ui/skeleton";
+
+interface LoadingSkeletonProps {
+  label: string;
+  rows?: number;
+}
+
+export function LoadingSkeleton({ label, rows = 3 }: LoadingSkeletonProps) {
+  const count = Math.max(1, rows);
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      aria-label={label}
+      className="state-card state-card--loading"
+      data-testid="loading-skeleton"
+    >
+      <div className="state-card__bars">
+        {Array.from({ length: count }).map((_, i) => (
+          <Skeleton key={i} data-testid="skeleton-row" className="state-card__bar" />
+        ))}
+      </div>
+      <span className="sr-only">{label}</span>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 8: Run LoadingSkeleton test — expect pass**
+
+```
+cd ui && npm test -- --run src/components/empty/__tests__/LoadingSkeleton.test.tsx
+```
+
+Expected: 3 passing.
+
+- [ ] **Step 9: Write `ErrorState` test**
+
+Create `ui/src/components/empty/__tests__/ErrorState.test.tsx`:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import { ErrorState } from "../ErrorState";
+
+describe("ErrorState", () => {
+  it("renders the message and a retry button when retry is provided", async () => {
+    const retry = vi.fn();
+    render(
+      <ErrorState title="Failed to load" message="Network error" onRetry={retry} />,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText("Failed to load")).toBeInTheDocument();
+    expect(screen.getByText("Network error")).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: /retry/i }));
+    expect(retry).toHaveBeenCalledOnce();
+  });
+
+  it("hides the retry button when onRetry is absent", () => {
+    render(<ErrorState title="Broken" message="x" />);
+    expect(screen.queryByRole("button", { name: /retry/i })).toBeNull();
+  });
+
+  it("sanitizes long messages to 500 chars", () => {
+    const long = "a".repeat(900);
+    render(<ErrorState title="t" message={long} />);
+    const rendered = screen.getByTestId("error-message").textContent ?? "";
+    expect(rendered.length).toBeLessThanOrEqual(504); // 500 + ellipsis
+  });
+});
+```
+
+- [ ] **Step 10: Run the test — expect failure**
+
+```
+cd ui && npm test -- --run src/components/empty/__tests__/ErrorState.test.tsx
+```
+
+Expected: FAIL with `Cannot find module '../ErrorState'`.
+
+- [ ] **Step 11: Implement `ErrorState`**
+
+Create `ui/src/components/empty/ErrorState.tsx`:
+
+```tsx
+import { AlertTriangle } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+interface ErrorStateProps {
+  title: string;
+  message: string;
+  onRetry?: () => void;
+}
+
+const MAX_MESSAGE_LEN = 500;
+
+function sanitize(raw: string): string {
+  const trimmed = raw.trim().replace(/[-]+/g, " ");
+  if (trimmed.length <= MAX_MESSAGE_LEN) return trimmed;
+  return `${trimmed.slice(0, MAX_MESSAGE_LEN)}…`;
+}
+
+export function ErrorState({ title, message, onRetry }: ErrorStateProps) {
+  return (
+    <div
+      role="alert"
+      className="state-card state-card--error"
+      data-testid="error-state"
+    >
+      <div className="state-card__icon state-card__icon--danger" aria-hidden="true">
+        <AlertTriangle className="size-6" />
+      </div>
+      <h3 className="state-card__title">{title}</h3>
+      <p className="state-card__description" data-testid="error-message">
+        {sanitize(message)}
+      </p>
+      {onRetry ? (
+        <div className="state-card__action">
+          <Button type="button" size="sm" variant="outline" onClick={onRetry}>
+            Retry
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 12: Run ErrorState test — expect pass**
+
+```
+cd ui && npm test -- --run src/components/empty/__tests__/ErrorState.test.tsx
+```
+
+Expected: 3 passing.
+
+- [ ] **Step 13: Write the barrel export**
+
+Create `ui/src/components/empty/index.ts`:
+
+```ts
+export { EmptyState } from "./EmptyState";
+export { LoadingSkeleton } from "./LoadingSkeleton";
+export { ErrorState } from "./ErrorState";
+```
+
+- [ ] **Step 14: Add shared styles**
+
+Open `ui/src/styles/globals.css`. Append at the bottom of the file:
+
+```css
+/* Block 5.2 — reusable state trio ------------------------------------ */
+.state-card {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 2rem 1.5rem;
+  border: 1px solid var(--border);
+  border-radius: 0.75rem;
+  background: var(--card);
+  text-align: center;
+}
+.state-card__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: 9999px;
+  background: color-mix(in oklab, var(--muted) 60%, transparent);
+  color: var(--muted-foreground);
+}
+.state-card__icon--danger {
+  background: color-mix(in oklab, var(--destructive) 14%, transparent);
+  color: var(--destructive);
+}
+.state-card__title {
+  font-size: 0.95rem;
+  font-weight: 600;
+  color: var(--foreground);
+}
+.state-card__description {
+  font-size: 0.85rem;
+  line-height: 1.45;
+  color: var(--muted-foreground);
+  max-width: 40ch;
+}
+.state-card__action {
+  margin-top: 0.5rem;
+}
+.state-card__bars {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+.state-card__bar {
+  height: 0.75rem;
+  width: 100%;
+  border-radius: 0.375rem;
+}
+.state-card--loading { padding: 1.25rem; align-items: stretch; }
+```
+
+- [ ] **Step 15: Apply the trio to `Home.tsx`**
+
+Replace the whole contents of `ui/src/routes/Home.tsx` with:
+
+```tsx
+import { useEffect, useMemo } from "react";
+import { Link } from "react-router-dom";
+import { ArrowUpRight } from "lucide-react";
+import { StatsStrip } from "@/components/layout/StatsStrip";
+import { ActivityFeed } from "@/components/activity/ActivityFeed";
+import { GlanceView } from "@/components/graph/GlanceView";
+import { useProjectStore } from "@/stores/project";
+import { useStats } from "@/hooks/api/useStats";
+import { useActivity } from "@/hooks/api/useActivity";
+import { useNotes } from "@/hooks/api/useNotes";
+import { useNotesGraph } from "@/hooks/api/useGraph";
+import { useLastVisit } from "@/hooks/useLastVisit";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+
+export default function Home() {
+  const project = useProjectStore((s) => s.slug);
+  const stats = useStats(project);
+  const activity = useActivity(project);
+  const notes = useNotes(project);
+  const graph = useNotesGraph(project);
+  const { lastVisit, touch } = useLastVisit();
+
+  const newCount = useMemo(() => {
+    if (!activity.data) return 0;
+    return activity.data.filter((e) => e.kind === "note_added" && e.timestamp > lastVisit).length;
+  }, [activity.data, lastVisit]);
+
+  useEffect(() => () => { touch(); }, [touch]);
+
+  const recentNotes = (notes.data ?? []).slice(0, 8);
+  const mergedStats = useMemo(() => {
+    const notesCount = notes.data?.length ?? 0;
+    const base = stats.data ?? {
+      documents: 0, chunks: 0, entities: 0, relationships: 0,
+      communities: 0, notes: 0, last_indexed: null,
+    };
+    return { ...base, notes: notesCount };
+  }, [stats.data, notes.data]);
+
+  const activityError = activity.error as Error | null | undefined;
+  const graphError = graph.error as Error | null | undefined;
+
+  return (
+    <div className="page">
+      <StatsStrip stats={mergedStats} delta={{ notes: newCount }} />
+
+      <div className="home-split">
+        <div className="home-main">
+          <div className="page-header">
+            <div className="flex items-baseline gap-3">
+              <h2 className="page-header-title">Activity</h2>
+              <span className="page-header-meta">{activity.data?.length ?? 0} events</span>
+            </div>
+          </div>
+          <div className="page-body">
+            {activity.isLoading ? (
+              <LoadingSkeleton label="Loading activity" rows={4} />
+            ) : activityError ? (
+              <ErrorState
+                title="Could not load activity"
+                message={activityError.message || "Unknown error"}
+                onRetry={() => activity.refetch()}
+              />
+            ) : (activity.data?.length ?? 0) === 0 ? (
+              <EmptyState
+                title="No recent activity"
+                description="Ingest a document or create a note to start the feed."
+              />
+            ) : (
+              <ActivityFeed events={activity.data ?? []} lastVisit={lastVisit} />
+            )}
+          </div>
+        </div>
+
+        <aside className="home-rail">
+          <section className="home-rail-top">
+            <div className="section-head">
+              <h2 className="section-title">Graph</h2>
+              <Link to="/graph" className="section-link">
+                open <ArrowUpRight className="size-3" />
+              </Link>
+            </div>
+            <div className="graph-card">
+              {graph.isLoading ? (
+                <LoadingSkeleton label="Loading graph preview" rows={3} />
+              ) : graphError ? (
+                <ErrorState
+                  title="Graph failed"
+                  message={graphError.message || "Unknown error"}
+                  onRetry={() => graph.refetch()}
+                />
+              ) : !graph.data || graph.data.nodes.length === 0 ? (
+                <EmptyState
+                  title="No graph yet"
+                  description="Run an index to see entities and edges."
+                />
+              ) : (
+                <GlanceView data={graph.data} />
+              )}
+            </div>
+          </section>
+
+          <section className="section flex-1">
+            <div className="section-head">
+              <h2 className="section-title">Recent notes</h2>
+              <Link to="/notes" className="section-link">
+                all <ArrowUpRight className="size-3" />
+              </Link>
+            </div>
+            {notes.isLoading ? (
+              <LoadingSkeleton label="Loading notes" rows={5} />
+            ) : recentNotes.length === 0 ? (
+              <EmptyState
+                title="No notes yet"
+                description="Create your first note to see it here."
+              />
+            ) : (
+              <ul className="note-list">
+                {recentNotes.map((n) => {
+                  const parts = n.key.split("/");
+                  const name = parts.pop() ?? n.key;
+                  const folder = parts.join("/");
+                  return (
+                    <li key={n.key}>
+                      <Link to={`/notes/${encodeURIComponent(n.key)}`} className="note-row">
+                        <span className="note-row-name">{name}</span>
+                        {folder && <span className="note-row-folder">{folder}</span>}
+                      </Link>
+                    </li>
+                  );
+                })}
+              </ul>
+            )}
+          </section>
+        </aside>
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 16: Apply the trio to `Graph.tsx`**
+
+Replace the whole contents of `ui/src/routes/Graph.tsx` with:
+
+```tsx
+import { GraphCanvas } from "@/components/graph/GraphCanvas";
+import { useNotesGraph } from "@/hooks/api/useGraph";
+import { useProjectStore } from "@/stores/project";
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+
+export default function Graph() {
+  const project = useProjectStore((s) => s.slug);
+  const { data, isLoading, error, refetch } = useNotesGraph(project);
+  const err = error as Error | null | undefined;
+
+  if (isLoading) {
+    return (
+      <div className="graph-page p-8">
+        <LoadingSkeleton label="Loading graph" rows={4} />
+      </div>
+    );
+  }
+  if (err) {
+    return (
+      <div className="graph-page p-8">
+        <ErrorState
+          title="Graph failed to load"
+          message={err.message || "Unknown error"}
+          onRetry={() => refetch()}
+        />
+      </div>
+    );
+  }
+  if (!data || data.nodes.length === 0) {
+    return (
+      <div className="graph-page p-8">
+        <EmptyState
+          title="No graph data for this project"
+          description="Ingest or index a document to build the graph."
+        />
+      </div>
+    );
+  }
+  return (
+    <div className="graph-page">
+      <GraphCanvas data={data} />
+    </div>
+  );
+}
+```
+
+- [ ] **Step 17: Wire the trio into the MCPConsole route**
+
+Open `ui/src/routes/MCPConsole.tsx`. Locate the first fetching region (search for `isLoading`) and replace inline `<div>Loading…</div>` / empty divs / error text with the trio. Specifically, at the top of the file add:
+
+```tsx
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+```
+
+Then for every branch that currently renders plain-text `Loading…`, empty placeholder, or caught error text, wrap them. The minimum required replacements:
+
+- Replace any `return <div ...>Loading…</div>` with:
+
+  ```tsx
+  return (
+    <section className="mcp-console p-6">
+      <LoadingSkeleton label="Loading MCP tools" rows={4} />
+    </section>
+  );
+  ```
+
+- For an error branch, replace with:
+
+  ```tsx
+  return (
+    <section className="mcp-console p-6">
+      <ErrorState
+        title="MCP tools failed to load"
+        message={(err as Error).message || "Unknown error"}
+        onRetry={() => refetch()}
+      />
+    </section>
+  );
+  ```
+
+- For an empty/"no tools" branch, replace with:
+
+  ```tsx
+  <EmptyState
+    title="No MCP tools registered"
+    description="Start the MCP server or connect a client to see tools here."
+  />
+  ```
+
+- [ ] **Step 18: Wire the trio into `NotesLayout.tsx`**
+
+Open `ui/src/routes/notes/NotesLayout.tsx`. At the top, add:
+
+```tsx
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+```
+
+Replace any `<div>Loading…</div>` with `<LoadingSkeleton label="Loading notes" rows={6} />`, any empty state with `<EmptyState title="No notes yet" description="Create your first note to see it here." />`, and any error with `<ErrorState title="Notes failed to load" message={...} onRetry={() => refetch()} />`.
+
+- [ ] **Step 19: Wire the trio into `NoteView.tsx`**
+
+Open `ui/src/routes/notes/NoteView.tsx`. At the top, add:
+
+```tsx
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+```
+
+Replace the loading placeholder with `<LoadingSkeleton label="Loading note" rows={5} />`, the not-found branch with `<EmptyState title="Note not found" description="The note may have been deleted or the link is stale." />`, and any fetch error with `<ErrorState title="Note failed to load" message={...} onRetry={() => refetch()} />`.
+
+- [ ] **Step 20: Wire the trio into `NotesSearch.tsx`**
+
+Open `ui/src/routes/notes/NotesSearch.tsx`. Add the import:
+
+```tsx
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+```
+
+Wrap loading/empty/error branches the same way.
+
+- [ ] **Step 21: Wire the trio into `DocumentsList.tsx` and `DocumentView.tsx`**
+
+Apply the same three-branch pattern to both files:
+
+```tsx
+import { EmptyState, ErrorState, LoadingSkeleton } from "@/components/empty";
+```
+
+For `DocumentsList.tsx`: loading → `<LoadingSkeleton label="Loading documents" rows={6} />`; empty → `<EmptyState title="No documents yet" description="Upload a PDF, DOCX, or web page to get started." />`; error → `<ErrorState title="Documents failed to load" message={...} onRetry={() => refetch()} />`.
+
+For `DocumentView.tsx`: loading → `<LoadingSkeleton label="Loading document" rows={5} />`; empty → `<EmptyState title="Document not found" description="The document may have been deleted." />`; error → `<ErrorState title="Document failed to load" message={...} onRetry={() => refetch()} />`.
+
+- [ ] **Step 22: Run the full UI test suite**
+
+```
+cd ui && npm test -- --run
+```
+
+Expected: all new state-trio tests pass and no existing test regressed.
+
+- [ ] **Step 23: Typecheck + build**
+
+```
+cd ui && npm run typecheck && npm run build
+```
+
+Expected: no errors. Build output dist JS + CSS remains under 640 KB. Verify with:
+
+```
+cd ui && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: total bytes < 655360.
+
+- [ ] **Step 24: Commit**
+
+```bash
+git add ui/src/components/empty ui/src/styles/globals.css \
+  ui/src/routes/Home.tsx ui/src/routes/Graph.tsx ui/src/routes/MCPConsole.tsx \
+  ui/src/routes/notes/NotesLayout.tsx ui/src/routes/notes/NoteView.tsx \
+  ui/src/routes/notes/NotesSearch.tsx \
+  ui/src/routes/documents/DocumentsList.tsx ui/src/routes/documents/DocumentView.tsx
+git commit -m "$(cat <<'EOF'
+feat(ui): add reusable EmptyState/LoadingSkeleton/ErrorState trio (5.2)
+
+Adds consistent loading/empty/error primitives under ui/src/components/empty
+and applies them to every fetching route (Home, Notes*, Documents*, Graph,
+MCPConsole). Addresses Block 5.2 of the production-polish roadmap.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 2: `RouteBoundary` error boundary (5.1)
+
+**Files:**
+- Create: `ui/src/components/layout/RouteBoundary.tsx`
+- Create: `ui/src/components/layout/__tests__/RouteBoundary.test.tsx`
+- Modify: `ui/src/App.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `ui/src/components/layout/__tests__/RouteBoundary.test.tsx`:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { RouteBoundary } from "../RouteBoundary";
+
+function Boom({ fuse }: { fuse: boolean }): JSX.Element {
+  if (fuse) throw new Error("kaboom");
+  return <div>ok</div>;
+}
+
+describe("RouteBoundary", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("renders children when they do not throw", () => {
+    render(
+      <RouteBoundary>
+        <Boom fuse={false} />
+      </RouteBoundary>,
+    );
+    expect(screen.getByText("ok")).toBeInTheDocument();
+  });
+
+  it("catches render errors and shows the fallback card with sanitized message", () => {
+    render(
+      <RouteBoundary>
+        <Boom fuse />
+      </RouteBoundary>,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();
+    expect(screen.getByText("kaboom")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /reload this view/i })).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /report/i })).toHaveAttribute(
+      "href",
+      expect.stringMatching(/^mailto:/),
+    );
+  });
+
+  it("resets on `Reload this view` click", async () => {
+    function Toggle() {
+      return <Boom fuse />;
+    }
+    render(
+      <RouteBoundary>
+        <Toggle />
+      </RouteBoundary>,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+    await userEvent.click(screen.getByRole("button", { name: /reload this view/i }));
+    // After reset the child still throws, but the reset did fire and the
+    // boundary re-caught. We simply assert the reload button is still
+    // reachable — which proves the reset handler ran without crashing.
+    expect(screen.getByRole("button", { name: /reload this view/i })).toBeInTheDocument();
+  });
+
+  it("truncates very long error messages", () => {
+    function LongBoom(): JSX.Element {
+      throw new Error("x".repeat(900));
+    }
+    render(
+      <RouteBoundary>
+        <LongBoom />
+      </RouteBoundary>,
+    );
+    const msg = screen.getByTestId("boundary-message").textContent ?? "";
+    expect(msg.length).toBeLessThanOrEqual(504);
+  });
+});
+```
+
+- [ ] **Step 2: Run the test — expect failure**
+
+```
+cd ui && npm test -- --run src/components/layout/__tests__/RouteBoundary.test.tsx
+```
+
+Expected: FAIL with `Cannot find module '../RouteBoundary'`.
+
+- [ ] **Step 3: Implement `RouteBoundary`**
+
+Create `ui/src/components/layout/RouteBoundary.tsx`:
+
+```tsx
+import { Component, type ErrorInfo, type ReactNode } from "react";
+import { AlertTriangle } from "lucide-react";
+import { Button } from "@/components/ui/button";
+
+interface RouteBoundaryProps { children: ReactNode }
+interface RouteBoundaryState { error: Error | null }
+
+const MAX_MESSAGE_LEN = 500;
+const REPORT_EMAIL = "docsiq-support@example.invalid";
+
+function sanitize(raw: string): string {
+  const trimmed = raw.trim().replace(/[-]+/g, " ");
+  if (trimmed.length <= MAX_MESSAGE_LEN) return trimmed;
+  return `${trimmed.slice(0, MAX_MESSAGE_LEN)}…`;
+}
+
+function buildMailto(err: Error): string {
+  const subject = encodeURIComponent(`[docsiq] Render error: ${err.name}`);
+  const bodyLines = [
+    "What I was doing:",
+    "",
+    "",
+    "Message:",
+    sanitize(err.message),
+    "",
+    "Stack (truncated):",
+    (err.stack ?? "").split("\n").slice(0, 10).join("\n"),
+    "",
+    `URL: ${typeof window !== "undefined" ? window.location.href : ""}`,
+    `UA:  ${typeof navigator !== "undefined" ? navigator.userAgent : ""}`,
+  ].join("\n");
+  const body = encodeURIComponent(bodyLines);
+  return `mailto:${REPORT_EMAIL}?subject=${subject}&body=${body}`;
+}
+
+export class RouteBoundary extends Component<RouteBoundaryProps, RouteBoundaryState> {
+  state: RouteBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): RouteBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    // slog-equivalent: keep one structured line; never dump user PII
+    console.error("[RouteBoundary]", error.name, sanitize(error.message), info.componentStack);
+  }
+
+  private reset = () => this.setState({ error: null });
+
+  render() {
+    const { error } = this.state;
+    if (!error) return this.props.children;
+    return (
+      <div role="alert" className="state-card state-card--error" data-testid="route-boundary">
+        <div className="state-card__icon state-card__icon--danger" aria-hidden="true">
+          <AlertTriangle className="size-6" />
+        </div>
+        <h3 className="state-card__title">Something went wrong</h3>
+        <p className="state-card__description" data-testid="boundary-message">
+          {sanitize(error.message || "Unknown render error")}
+        </p>
+        <div className="state-card__action flex gap-2">
+          <Button type="button" size="sm" variant="outline" onClick={this.reset}>
+            Reload this view
+          </Button>
+          <a
+            className="inline-flex items-center justify-center rounded-md border px-3 py-1.5 text-sm hover:bg-accent"
+            href={buildMailto(error)}
+            rel="noopener noreferrer"
+          >
+            Report
+          </a>
+        </div>
+      </div>
+    );
+  }
+}
+```
+
+- [ ] **Step 4: Run the test — expect pass**
+
+```
+cd ui && npm test -- --run src/components/layout/__tests__/RouteBoundary.test.tsx
+```
+
+Expected: 4 passing.
+
+- [ ] **Step 5: Wire `RouteBoundary` into `App.tsx`**
+
+Replace the whole contents of `ui/src/App.tsx` with:
+
+```tsx
+import { lazy, Suspense, useEffect } from "react";
+import { Route, Routes } from "react-router-dom";
+import { Providers } from "@/components/layout/Providers";
+import { Shell } from "@/components/layout/Shell";
+import { RouteBoundary } from "@/components/layout/RouteBoundary";
+import { LoadingSkeleton } from "@/components/empty";
+import { initAuth } from "@/lib/api-client";
+import Home from "@/routes/Home";
+
+// Home is eager (first paint); everything else is split.
+const NotesLayout = lazy(() => import("@/routes/notes/NotesLayout"));
+const NoteView = lazy(() => import("@/routes/notes/NoteView"));
+const NoteEditor = lazy(() => import("@/routes/notes/NoteEditor"));
+const NotesSearch = lazy(() => import("@/routes/notes/NotesSearch"));
+const DocumentsList = lazy(() => import("@/routes/documents/DocumentsList"));
+const DocumentView = lazy(() => import("@/routes/documents/DocumentView"));
+const Graph = lazy(() => import("@/routes/Graph"));
+const MCPConsole = lazy(() => import("@/routes/MCPConsole"));
+
+function RouteFallback() {
+  return (
+    <div className="p-6">
+      <LoadingSkeleton label="Loading view" rows={4} />
+    </div>
+  );
+}
+
+export default function App() {
+  useEffect(() => { initAuth(); }, []);
+  return (
+    <Providers>
+      <Shell>
+        <RouteBoundary>
+          <Suspense fallback={<RouteFallback />}>
+            <Routes>
+              <Route path="/" element={<Home />} />
+              <Route path="/notes" element={<NotesLayout />}>
+                <Route path="search" element={<NotesSearch />} />
+                <Route path=":key" element={<NoteView />} />
+                <Route path=":key/edit" element={<NoteEditor />} />
+              </Route>
+              <Route path="/docs" element={<DocumentsList />} />
+              <Route path="/docs/:id" element={<DocumentView />} />
+              <Route path="/graph" element={<Graph />} />
+              <Route path="/mcp" element={<MCPConsole />} />
+            </Routes>
+          </Suspense>
+        </RouteBoundary>
+      </Shell>
+    </Providers>
+  );
+}
+```
+
+Note: the exact `<Route>` tree inside `<Routes>` mirrors the existing tree in your current `App.tsx`. If your current file has an additional route not shown here (e.g. `/notes` index), copy that element over verbatim — do not drop any routes. Verify with `git diff ui/src/App.tsx` before committing.
+
+- [ ] **Step 6: Run full UI test suite**
+
+```
+cd ui && npm test -- --run
+```
+
+Expected: all pass. The existing Playwright smoke should still work because the boundary is transparent on success.
+
+- [ ] **Step 7: Typecheck + build**
+
+```
+cd ui && npm run typecheck && npm run build
+```
+
+Expected: clean. JS+CSS bundle < 640 KB. Verify:
+
+```
+cd ui && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add ui/src/App.tsx ui/src/components/layout/RouteBoundary.tsx \
+  ui/src/components/layout/__tests__/RouteBoundary.test.tsx
+git commit -m "$(cat <<'EOF'
+feat(ui): add RouteBoundary error boundary around Suspense (5.1)
+
+Catches render errors at the Suspense fallback level and shows a sanitized
+state card with "Reload this view" (resets the boundary) and "Report"
+(opens a mailto with a truncated stack). Vitest-covered via a child that
+throws on render. Addresses Block 5.1.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 3: Dynamic `document.title` per route (5.3)
+
+**Files:**
+- Modify: `ui/src/hooks/useDocumentTitle.ts`
+- Create: `ui/src/hooks/__tests__/useDocumentTitle.test.tsx`
+
+The existing hook is too minimal — it only looks up a few fixed paths and handles doc id as `Document <8>`. The spec requires: `Home`, `Notes`, `{noteKey}`, `Documents`, `{doc.title}`, `Graph`, `MCP Console` — all suffixed with ` — docsiq`. We will extend the hook to accept optional `parts` for cases where the route needs dynamic data (document title), and fix the notes-key pretty-printer.
+
+- [ ] **Step 1: Write the failing test**
+
+Create `ui/src/hooks/__tests__/useDocumentTitle.test.tsx`:
+
+```tsx
+import { renderHook } from "@testing-library/react";
+import { MemoryRouter, Route, Routes } from "react-router-dom";
+import { describe, it, expect, afterEach } from "vitest";
+import { useDocumentTitle } from "../useDocumentTitle";
+
+function Wrapper({
+  path,
+  url,
+  parts,
+}: {
+  path: string;
+  url: string;
+  parts?: string[];
+}) {
+  function Inner() {
+    useDocumentTitle(parts);
+    return null;
+  }
+  return (
+    <MemoryRouter initialEntries={[url]}>
+      <Routes>
+        <Route path={path} element={<Inner />} />
+      </Routes>
+    </MemoryRouter>
+  );
+}
+
+describe("useDocumentTitle", () => {
+  afterEach(() => {
+    document.title = "docsiq";
+  });
+
+  it("sets Home title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/" url="/" /> });
+    expect(document.title).toBe("Home — docsiq");
+  });
+
+  it("sets Notes list title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/notes" url="/notes" /> });
+    expect(document.title).toBe("Notes — docsiq");
+  });
+
+  it("sets note-key title from the URL when no parts passed", () => {
+    renderHook(() => {}, {
+      wrapper: () => (
+        <Wrapper path="/notes/:key" url="/notes/folder%2Fhello" />
+      ),
+    });
+    expect(document.title).toBe("hello — docsiq");
+  });
+
+  it("sets Documents list title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/docs" url="/docs" /> });
+    expect(document.title).toBe("Documents — docsiq");
+  });
+
+  it("honours caller-provided parts for a document view", () => {
+    renderHook(() => {}, {
+      wrapper: () => (
+        <Wrapper
+          path="/docs/:id"
+          url="/docs/abc"
+          parts={["Design doc v2", "Documents"]}
+        />
+      ),
+    });
+    expect(document.title).toBe("Design doc v2 — Documents — docsiq");
+  });
+
+  it("sets Graph title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/graph" url="/graph" /> });
+    expect(document.title).toBe("Graph — docsiq");
+  });
+
+  it("sets MCP Console title", () => {
+    renderHook(() => {}, { wrapper: () => <Wrapper path="/mcp" url="/mcp" /> });
+    expect(document.title).toBe("MCP Console — docsiq");
+  });
+
+  it("falls back to `docsiq` on unknown paths with no parts", () => {
+    renderHook(() => {}, {
+      wrapper: () => <Wrapper path="/weird" url="/weird" />,
+    });
+    expect(document.title).toBe("docsiq");
+  });
+});
+```
+
+- [ ] **Step 2: Run the test — expect failure**
+
+```
+cd ui && npm test -- --run src/hooks/__tests__/useDocumentTitle.test.tsx
+```
+
+Expected: most cases fail because current hook ignores `parts`, formats doc id as `Document abc`, and does not handle `/notes/search`/sub-paths cleanly.
+
+- [ ] **Step 3: Rewrite `useDocumentTitle`**
+
+Replace the whole contents of `ui/src/hooks/useDocumentTitle.ts` with:
+
+```ts
+import { useEffect } from "react";
+import { useLocation, useParams } from "react-router-dom";
+
+const STATIC_TITLES: Record<string, string> = {
+  "/": "Home",
+  "/notes": "Notes",
+  "/notes/search": "Search notes",
+  "/docs": "Documents",
+  "/graph": "Graph",
+  "/mcp": "MCP Console",
+};
+
+const SUFFIX = "docsiq";
+
+function prettifyKey(raw: string): string {
+  try {
+    const decoded = decodeURIComponent(raw);
+    const last = decoded.split("/").pop();
+    return last && last.length > 0 ? last : decoded;
+  } catch {
+    return raw;
+  }
+}
+
+/**
+ * Sets document.title with a consistent " — docsiq" suffix.
+ *
+ * `parts` takes precedence over path-derived titles. Pass a list of parts
+ * from most-specific to least-specific, e.g. ["Design doc v2", "Documents"]
+ * produces "Design doc v2 — Documents — docsiq".
+ */
+export function useDocumentTitle(parts?: string[]): void {
+  const { pathname } = useLocation();
+  const params = useParams();
+
+  useEffect(() => {
+    const explicit = (parts ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
+    let segments: string[] = [];
+
+    if (explicit.length > 0) {
+      segments = [...explicit, SUFFIX];
+    } else {
+      const label = STATIC_TITLES[pathname];
+      if (label) {
+        segments = [label, SUFFIX];
+      } else if (pathname.startsWith("/notes/") && params.key) {
+        segments = [prettifyKey(params.key), SUFFIX];
+      } else if (pathname.startsWith("/docs/") && params.id) {
+        // Route may pass its own title via `parts`; otherwise show a short id.
+        segments = [`Document ${params.id.slice(0, 8)}`, SUFFIX];
+      } else {
+        segments = [SUFFIX];
+      }
+    }
+
+    document.title =
+      segments.length === 1 ? segments[0]! : segments.join(" — ");
+  }, [pathname, params, parts]);
+}
+```
+
+- [ ] **Step 4: Run the test — expect pass**
+
+```
+cd ui && npm test -- --run src/hooks/__tests__/useDocumentTitle.test.tsx
+```
+
+Expected: 8 passing.
+
+- [ ] **Step 5: Wire DocumentView's real title through `parts`**
+
+Open `ui/src/routes/documents/DocumentView.tsx`. Inside the component (after the data hook), add:
+
+```tsx
+import { useDocumentTitle } from "@/hooks/useDocumentTitle";
+// ...
+useDocumentTitle(data?.doc?.title ? [data.doc.title, "Documents"] : undefined);
+```
+
+Use the exact field path the existing fetch returns. If the component already holds the title in a variable (e.g. `doc`), substitute accordingly. Verify by running the app and navigating to `/docs/:id`.
+
+- [ ] **Step 6: Wire NoteView's title through `parts`**
+
+Open `ui/src/routes/notes/NoteView.tsx`. Add:
+
+```tsx
+import { useDocumentTitle } from "@/hooks/useDocumentTitle";
+// ...
+const noteTitle = data?.note?.title ?? data?.note?.key ?? params.key ?? undefined;
+useDocumentTitle(noteTitle ? [noteTitle, "Notes"] : undefined);
+```
+
+If the shape of `data` differs, adapt. The hook already falls back gracefully to the URL key when `parts` is not supplied.
+
+- [ ] **Step 7: Run full UI test suite**
+
+```
+cd ui && npm test -- --run
+```
+
+Expected: all pass.
+
+- [ ] **Step 8: Typecheck + build + bundle budget**
+
+```
+cd ui && npm run typecheck && npm run build && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: clean typecheck, build succeeds, bundle < 655360 bytes.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add ui/src/hooks/useDocumentTitle.ts ui/src/hooks/__tests__/useDocumentTitle.test.tsx \
+  ui/src/routes/documents/DocumentView.tsx ui/src/routes/notes/NoteView.tsx
+git commit -m "$(cat <<'EOF'
+feat(ui): dynamic document.title per route with parts support (5.3)
+
+Extends useDocumentTitle to accept optional `parts` for dynamic segments
+(document/note titles) and threads them through DocumentView + NoteView.
+All titles suffixed " — docsiq". Addresses Block 5.3.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 4: iOS safe-area insets (5.4)
+
+**Files:**
+- Modify: `ui/src/styles/globals.css`
+- Modify: `ui/src/components/ui/sidebar.tsx` (only the outer `Sidebar` wrapper — safe-area padding-left)
+- Verify: `ui/index.html` viewport meta already includes `viewport-fit=cover` (it does, per current file)
+- Create: `ui/e2e/safe-area.spec.ts` (Playwright check that iPhone 14 viewport respects env insets)
+
+- [ ] **Step 1: Verify the viewport meta**
+
+```
+cd ui && grep viewport index.html
+```
+
+Expected: includes `viewport-fit=cover`. If not present, add it so the line reads:
+
+```html
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover" />
+```
+
+- [ ] **Step 2: Add safe-area CSS variables + header/sidebar rules**
+
+Open `ui/src/styles/globals.css`. Append:
+
+```css
+/* Block 5.4 — iOS safe-area insets ------------------------------------- */
+:root {
+  --header-pad: 1rem;
+}
+
+/* Header padding respects the notch on iOS */
+.site-header {
+  padding-top: max(var(--header-pad), env(safe-area-inset-top));
+  padding-right: max(var(--header-pad), env(safe-area-inset-right));
+}
+
+/* Sidebar padding respects the left inset in landscape iOS */
+[data-slot="sidebar-container"],
+[data-sidebar="sidebar"] {
+  padding-left: env(safe-area-inset-left);
+}
+
+/* Main content also respects bottom inset for iOS home indicator */
+main#main {
+  padding-bottom: env(safe-area-inset-bottom);
+}
+```
+
+(Adjust the `[data-slot="sidebar-container"]` selector if the local shadcn sidebar uses a different attribute — open `ui/src/components/ui/sidebar.tsx` and search for the outer wrapper's `data-slot`. Prefer a class or `data-slot` selector rather than editing the component JS so the shadcn component stays local-copy-clean.)
+
+- [ ] **Step 3: Add a Playwright visual-regression-free assertion**
+
+Create `ui/e2e/safe-area.spec.ts`:
+
+```ts
+import { test, expect, devices } from "@playwright/test";
+import { test as fixtureTest } from "./fixtures";
+
+// Re-use the stubbed fixtures from fixtures.ts by extending from it.
+const iosTest = fixtureTest.extend({});
+
+iosTest.use({ ...devices["iPhone 14"] });
+
+iosTest("header padding accommodates safe-area-inset-top on iPhone 14", async ({ stubbedPage: page }) => {
+  await page.goto("/");
+  await page.locator("main#main").waitFor();
+  const header = page.locator(".site-header").first();
+  await expect(header).toBeVisible();
+  const paddingTopPx = await header.evaluate(
+    (el) => parseFloat(getComputedStyle(el).paddingTop),
+  );
+  // max(1rem, env(safe-area-inset-top)) must be at least 1rem = 16px.
+  expect(paddingTopPx).toBeGreaterThanOrEqual(16);
+});
+```
+
+- [ ] **Step 4: Run the Playwright spec**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test safe-area.spec.ts --reporter=list --workers=1
+```
+
+Expected: 1 passing.
+
+If Playwright is not installed, run `cd ui && npm run e2e:install` first.
+
+- [ ] **Step 5: Run full Vitest suite (regression check)**
+
+```
+cd ui && npm test -- --run
+```
+
+Expected: all pass.
+
+- [ ] **Step 6: Typecheck + build + budget**
+
+```
+cd ui && npm run typecheck && npm run build && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: clean, bundle < 655360.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add ui/src/styles/globals.css ui/e2e/safe-area.spec.ts ui/index.html
+git commit -m "$(cat <<'EOF'
+feat(ui): iOS safe-area insets on header, sidebar, and main (5.4)
+
+Header padding-top uses max(var(--header-pad), env(safe-area-inset-top))
+and sidebar/main respect left/right/bottom insets. Covered by a Playwright
+iPhone-14-viewport test asserting paddingTop ≥ 16px. Addresses Block 5.4.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 5: "Maximum update depth exceeded" — investigate + fix (5.5)
+
+This is an investigation-then-fix task. The spec names two likely culprits (`Home`, `StatsStrip`) but requires real bisection. Follow the sequence below — do not jump to "just memoize the thing" without reproducing the warning first.
+
+**Files:**
+- Create: `ui/e2e/no-console-errors.spec.ts` (captures console errors on every route)
+- Probably modify: one of `ui/src/routes/Home.tsx`, `ui/src/components/layout/StatsStrip.tsx`, `ui/src/hooks/api/useStats.ts`, `ui/src/hooks/api/useActivity.ts`, `ui/src/hooks/api/useNotes.ts`, or `ui/src/hooks/api/useGraph.ts` (determined by bisection)
+- Create: `ui/src/hooks/api/__tests__/useXxx-stability.test.tsx` (regression test for the object-identity fix, exact file named after whichever hook was the culprit)
+
+- [ ] **Step 1: Capture the warning with a Playwright console capture**
+
+Create `ui/e2e/no-console-errors.spec.ts`:
+
+```ts
+import { test, expect } from "./fixtures";
+
+const ROUTES = ["/", "/notes", "/docs", "/graph", "/mcp"];
+
+test.describe("no console errors or warnings on any route", () => {
+  for (const url of ROUTES) {
+    test(`no console errors on ${url}`, async ({ stubbedPage: page }) => {
+      const errors: string[] = [];
+      const warnings: string[] = [];
+      page.on("console", (msg) => {
+        const text = msg.text();
+        if (msg.type() === "error") errors.push(text);
+        if (msg.type() === "warning") warnings.push(text);
+      });
+      page.on("pageerror", (err) => errors.push(err.message));
+
+      await page.goto(url);
+      await page.locator("main#main").waitFor();
+      // Give effects a tick to run — if there's an infinite loop, it fires
+      // within a few microtasks and the warning lands here.
+      await page.waitForTimeout(500);
+
+      const offending = [...errors, ...warnings].filter((t) =>
+        /maximum update depth|too many re-renders/i.test(t),
+      );
+      expect(offending, `${url} emitted: ${offending.join(" | ")}`).toEqual([]);
+    });
+  }
+});
+```
+
+- [ ] **Step 2: Run the spec — this SHOULD fail on at least one route**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test no-console-errors.spec.ts --reporter=list --workers=1
+```
+
+Expected: one or more routes FAIL with the "Maximum update depth" text captured. Note which route(s). If nothing fails, the bug may already be fixed by Block 1–3 changes — in that case skip to Step 8, add the regression spec to the suite, and commit as a regression guard only.
+
+- [ ] **Step 3: Bisect with React DevTools Profiler**
+
+Run the app locally and open the failing route in a browser with React DevTools installed.
+
+```
+cd ui && npm run dev
+```
+
+Open DevTools → Components → ⚙ → "Highlight updates when components render". Navigate to the failing route. Look for a component that renders >20 times in <1 second. That is the culprit.
+
+Alternative when DevTools is unavailable: add a temporary `console.count("Home render")` at the top of the suspect route (`Home`, `StatsStrip`, etc.) and reload. Whichever counter climbs into the hundreds is the culprit.
+
+Remove any temporary `console.count` before committing.
+
+- [ ] **Step 4: Identify the unstable dependency**
+
+Once the culprit component is known, examine every `useEffect`, `useMemo`, and `useCallback` in that file. Look for dependency arrays that include:
+
+1. An object literal created per-render (`{ foo, bar }`)
+2. An array literal created per-render (`[a, b]`)
+3. A function that is not wrapped in `useCallback`
+4. A Zustand selector that returns a new object each call (`(s) => ({ a: s.a, b: s.b })`) — use a shallow-equality selector or split into two selectors
+5. A TanStack Query object returned from a hook whose identity changes even when data is equal (check the hook's `select` function)
+
+Document the finding in the commit message.
+
+- [ ] **Step 5: Write a regression test before fixing**
+
+Depending on the culprit, the test lives either at `ui/src/routes/__tests__/Home.test.tsx` (for `Home`) or `ui/src/components/layout/__tests__/StatsStrip.test.tsx` (for `StatsStrip`) or `ui/src/hooks/api/__tests__/<hookName>-stability.test.tsx` (for an API hook).
+
+Example — if the culprit is a Zustand selector returning a new object in `Home.tsx`, write this test at `ui/src/routes/__tests__/Home.test.tsx`:
+
+```tsx
+import { render, act } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import Home from "@/routes/Home";
+
+// Minimal spy on the scheduler: fail if Home renders more than 20 times on
+// mount+settle. This catches an update-depth loop without requiring Playwright.
+describe("Home render stability", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("does not enter an infinite render loop on mount", async () => {
+    const renderCount = { n: 0 };
+    // Wrap Home with a counter component so we can inspect without touching Home.
+    function CountingHome(): JSX.Element {
+      renderCount.n += 1;
+      return <Home />;
+    }
+    const client = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    render(
+      <QueryClientProvider client={client}>
+        <MemoryRouter initialEntries={["/"]}>
+          <CountingHome />
+        </MemoryRouter>
+      </QueryClientProvider>,
+    );
+    // flush microtasks a couple of times
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 50));
+    });
+    expect(renderCount.n).toBeLessThan(20);
+  });
+});
+```
+
+If the culprit is an API hook instead, use the hook-stability pattern:
+
+```tsx
+import { renderHook } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, expect, it } from "vitest";
+import { useStats } from "../useStats";
+
+describe("useStats reference stability", () => {
+  it("returns the same result object across renders when data is unchanged", () => {
+    const client = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+    const { result, rerender } = renderHook(() => useStats("demo"), { wrapper });
+    const first = result.current;
+    rerender();
+    expect(result.current).toBe(first);
+  });
+});
+```
+
+- [ ] **Step 6: Apply the minimal fix**
+
+Based on the bisection:
+
+- **Object-literal dep:** wrap in `useMemo(() => ({ ... }), [stableDeps])` or destructure into primitive deps.
+- **Function dep:** wrap with `useCallback(..., [stableDeps])`.
+- **Zustand selector:** replace `useUIStore((s) => ({ a: s.a, b: s.b }))` with two calls — `useUIStore((s) => s.a)` and `useUIStore((s) => s.b)` — or use `useShallow` from `zustand/shallow`.
+- **TanStack `select`:** memoize or drop `select`; the default selector is reference-stable.
+
+Make only the minimum change. If the fix is larger than ~10 lines it is probably not minimal — re-read the hook and narrow further.
+
+- [ ] **Step 7: Re-run the regression Vitest + Playwright spec**
+
+```
+cd ui && npm test -- --run
+cd ui && CI=1 ./node_modules/.bin/playwright test no-console-errors.spec.ts --reporter=list --workers=1
+```
+
+Expected: both pass. If Playwright still catches the warning, return to Step 3 — the bisect was wrong.
+
+- [ ] **Step 8: Typecheck + build + budget**
+
+```
+cd ui && npm run typecheck && npm run build && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: clean, bundle < 655360.
+
+- [ ] **Step 9: Commit**
+
+Use a commit message that names the exact file + bug found. Example (substitute actual findings):
+
+```bash
+git add ui/e2e/no-console-errors.spec.ts <file-you-fixed> <regression-test-you-added>
+git commit -m "$(cat <<'EOF'
+fix(ui): eliminate "Maximum update depth" warning on <route> (5.5)
+
+Root cause: <exact cause from bisection — e.g. Zustand selector in Home
+returned a fresh object per render, retriggering a useMemo whose output
+fed a useEffect dep array>.
+Fix: <minimal change — e.g. split selector into two primitive reads>.
+Regression: Playwright console-capture across all five routes; Vitest
+render-count assertion; update-depth warning no longer appears.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+If Step 2 found no warning (the bug was already fixed by earlier blocks), commit only the Playwright regression spec:
+
+```bash
+git add ui/e2e/no-console-errors.spec.ts
+git commit -m "$(cat <<'EOF'
+test(ui): add Playwright console-capture regression for update-depth loops (5.5)
+
+Asserts no "Maximum update depth"/"too many re-renders" warnings on any of
+the five primary routes. Addresses Block 5.5 (regression guard only — the
+underlying loop was not reproducible at commit time).
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 6: Axe violations sweep (5.6)
+
+**Files:**
+- Create: `ui/e2e/a11y.spec.ts` (Playwright + axe-core audit; asserts 0 violations per route)
+- Modify: `ui/src/components/app-sidebar.tsx` (add `aria-label` to `SelectTrigger`)
+- Possibly modify: other routes/components reported by the audit
+
+- [ ] **Step 1: Install `@axe-core/playwright` if absent**
+
+```
+cd ui && npm ls @axe-core/playwright 2>/dev/null || npm install --save-dev @axe-core/playwright@^4.10.0
+```
+
+Resolve the latest 4.x via `context7` MCP if the version drifts; `4.10.0` is the known-good at the time of writing.
+
+- [ ] **Step 2: Write the Playwright axe audit**
+
+Create `ui/e2e/a11y.spec.ts`:
+
+```ts
+import { test, expect } from "./fixtures";
+import AxeBuilder from "@axe-core/playwright";
+
+const ROUTES = ["/", "/notes", "/docs", "/graph", "/mcp"];
+
+test.describe("axe a11y audit — zero violations", () => {
+  for (const url of ROUTES) {
+    test(`no violations on ${url}`, async ({ stubbedPage: page }) => {
+      await page.goto(url);
+      await page.locator("main#main").waitFor();
+      const results = await new AxeBuilder({ page })
+        .withTags(["wcag2a", "wcag2aa"])
+        .analyze();
+      expect(
+        results.violations,
+        `${url}:\n${JSON.stringify(results.violations, null, 2)}`,
+      ).toEqual([]);
+    });
+  }
+});
+```
+
+- [ ] **Step 3: Run the audit — expect failures (this is the audit)**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test a11y.spec.ts --reporter=list --workers=1
+```
+
+Expected: at least one failure. Note every rule id and every affected selector.
+
+- [ ] **Step 4: Fix `SelectTrigger` in `app-sidebar.tsx`**
+
+Open `ui/src/components/app-sidebar.tsx`. The `SelectTrigger` currently has no accessible name. Replace lines ~87–90 (the `<Select>` block) with:
+
+```tsx
+<Select value={slug} onValueChange={setSlug}>
+  <SelectTrigger aria-label="Select project" className="w-full h-8 text-xs font-mono">
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    {(projects?.length ? projects : [{ slug, name: slug }]).map((p) => (
+      <SelectItem key={p.slug} value={p.slug} className="font-mono text-xs">
+        {p.name || p.slug}
+      </SelectItem>
+    ))}
+  </SelectContent>
+</Select>
+```
+
+- [ ] **Step 5: Fix the hard-reload button's accessible name (already has aria-label — verify)**
+
+```
+cd ui && grep -n 'aria-label' src/components/site-header.tsx
+```
+
+Expected: `aria-label="Hard reload"` is already present (Line 49). If axe still complains, check for `button-name` on any other button in the tree and add `aria-label`.
+
+- [ ] **Step 6: Triage each remaining violation and fix**
+
+For every remaining rule id reported by the audit, apply the standard fix:
+
+- `button-name` — add `aria-label` or visible text to the button.
+- `link-name` — add visible text or `aria-label` to the `<a>`.
+- `color-contrast` — bump the foreground color one step darker/lighter in `globals.css` for the affected selector.
+- `aria-hidden-focus` — remove `aria-hidden` from any element that contains a focusable child.
+- `landmark-one-main` — should already be satisfied by `<main id="main" role="main">`.
+- `document-title` — handled by Task 3.
+- `region` — wrap significant content in a `<section>` or `<region role="region" aria-label="...">`.
+
+Apply the minimal fix per violation, then re-run the audit after each batch.
+
+- [ ] **Step 7: Re-run the audit — expect pass**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test a11y.spec.ts --reporter=list --workers=1
+```
+
+Expected: 5 passing (one per route), 0 violations.
+
+- [ ] **Step 8: Run Vitest + typecheck + build**
+
+```
+cd ui && npm test -- --run && npm run typecheck && npm run build && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: clean across the board; bundle < 655360.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add ui/package.json ui/package-lock.json \
+  ui/e2e/a11y.spec.ts \
+  ui/src/components/app-sidebar.tsx \
+  <any other file touched in Step 6>
+git commit -m "$(cat <<'EOF'
+fix(ui): zero axe violations across all primary routes (5.6)
+
+Adds @axe-core/playwright audit asserting 0 wcag2a/wcag2aa violations on
+/, /notes, /docs, /graph, /mcp. Fixes include aria-label on project
+SelectTrigger and <list each additional fix>. Addresses Block 5.6.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 7: Reduced-motion gating for Framer Motion (5.7)
+
+The repo-wide search shows Framer Motion is concentrated in `ui/src/lib/motion.ts`. The hook `useReducedMotion` already exists. This task ensures every `<motion.*>` callsite either lives in `motion.ts` (centralized) or passes reduced-motion-safe transitions.
+
+**Files:**
+- Read/verify: `ui/src/lib/motion.ts`
+- Modify: `ui/src/lib/motion.ts` (export reduced-motion-aware presets)
+- Modify: any component using `motion.*` directly — replace with presets from `motion.ts`
+- Create: `ui/src/lib/__tests__/motion.test.ts`
+
+- [ ] **Step 1: Enumerate every `motion.*` callsite**
+
+```
+cd ui && npx tsx -e 'import {execSync} from "node:child_process"; console.log(execSync("grep -rn --include=\"*.tsx\" --include=\"*.ts\" \"motion\\.\" src/", {encoding: "utf8"}))'
+```
+
+Or more simply:
+
+```
+cd ui && grep -rn --include='*.tsx' --include='*.ts' 'from "framer-motion"' src/
+cd ui && grep -rn --include='*.tsx' --include='*.ts' 'motion\.' src/
+```
+
+List every file that imports from `framer-motion` or uses `motion.div`/`motion.section`/etc. Scope Task 7 to those files.
+
+- [ ] **Step 2: Write the test for the reduced-motion-aware presets**
+
+Create `ui/src/lib/__tests__/motion.test.ts`:
+
+```ts
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
+
+describe("motion presets", () => {
+  beforeEach(() => {
+    // default: user does not prefer reduced motion
+    window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    }));
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it("fade returns non-zero duration when motion is allowed", async () => {
+    const { fadeTransition } = await import("../motion");
+    expect(fadeTransition(false).duration).toBeGreaterThan(0);
+  });
+
+  it("fade returns zero duration when reduced motion is requested", async () => {
+    const { fadeTransition } = await import("../motion");
+    expect(fadeTransition(true).duration).toBe(0);
+  });
+
+  it("slideTransition honours reduced motion too", async () => {
+    const { slideTransition } = await import("../motion");
+    expect(slideTransition(true).duration).toBe(0);
+    expect(slideTransition(false).duration).toBeGreaterThan(0);
+  });
+});
+```
+
+- [ ] **Step 3: Run the test — expect failure**
+
+```
+cd ui && npm test -- --run src/lib/__tests__/motion.test.ts
+```
+
+Expected: FAIL with either a missing named export or an import error.
+
+- [ ] **Step 4: Update `motion.ts` to export reduced-motion-aware presets**
+
+Replace the whole contents of `ui/src/lib/motion.ts` with:
+
+```ts
+import type { Transition } from "framer-motion";
+
+/**
+ * Reduced-motion-aware transition presets.
+ *
+ * Callers pass the current user preference (from useReducedMotion()) and
+ * receive a transition config whose duration collapses to 0 when reduced
+ * motion is requested — still completing the state change, just instantly.
+ */
+
+export function fadeTransition(reducedMotion: boolean): Transition {
+  return {
+    duration: reducedMotion ? 0 : 0.18,
+    ease: [0.2, 0, 0, 1],
+  };
+}
+
+export function slideTransition(reducedMotion: boolean): Transition {
+  return {
+    duration: reducedMotion ? 0 : 0.22,
+    ease: [0.2, 0, 0, 1],
+  };
+}
+
+export function popTransition(reducedMotion: boolean): Transition {
+  return {
+    duration: reducedMotion ? 0 : 0.16,
+    ease: [0.2, 0, 0, 1],
+  };
+}
+
+/** Variants helper for simple fade-in mounts. */
+export const fadeInVariants = {
+  hidden: { opacity: 0 },
+  visible: { opacity: 1 },
+};
+
+/** Variants helper for slide-up mounts (12px travel). */
+export const slideUpVariants = {
+  hidden: { opacity: 0, y: 12 },
+  visible: { opacity: 0, y: 0, transition: { duration: 0.001 } }, // overridden by callsite
+};
+```
+
+Note: if the existing `motion.ts` file already exports other symbols used elsewhere, preserve those — just add the three transition functions above without removing existing exports. Run `git diff ui/src/lib/motion.ts` and confirm no callsite lost a symbol before committing.
+
+- [ ] **Step 5: Re-run the test — expect pass**
+
+```
+cd ui && npm test -- --run src/lib/__tests__/motion.test.ts
+```
+
+Expected: 3 passing.
+
+- [ ] **Step 6: Thread `useReducedMotion()` through every `<motion.*>` callsite**
+
+For each file found in Step 1, modify the component as follows. Example for an activity-feed item:
+
+```tsx
+import { motion } from "framer-motion";
+import { useReducedMotion } from "@/hooks/useReducedMotion";
+import { fadeTransition } from "@/lib/motion";
+
+// ...
+const reduced = useReducedMotion();
+// ...
+<motion.div
+  initial={{ opacity: 0 }}
+  animate={{ opacity: 1 }}
+  transition={fadeTransition(reduced)}
+>
+  {children}
+</motion.div>
+```
+
+Every `<motion.*>` callsite must pass a `transition` whose `duration` is `0` when `reduced` is true. Do not leave any callsite with a hardcoded non-zero `duration` unless it is explicitly gated by `useReducedMotion()`.
+
+Also audit any CSS animation in `globals.css` / component CSS. Add a media query once at the bottom of `globals.css`:
+
+```css
+/* Block 5.7 — reduced motion ------------------------------------------- */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.001ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+- [ ] **Step 7: Run full UI test suite**
+
+```
+cd ui && npm test -- --run
+```
+
+Expected: all pass.
+
+- [ ] **Step 8: Typecheck + build + budget**
+
+```
+cd ui && npm run typecheck && npm run build && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: clean; bundle < 655360.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add ui/src/lib/motion.ts ui/src/lib/__tests__/motion.test.ts ui/src/styles/globals.css \
+  <every file touched in Step 6>
+git commit -m "$(cat <<'EOF'
+feat(ui): reduced-motion-aware Framer Motion presets + global CSS gate (5.7)
+
+Adds fade/slide/pop transition factories that collapse duration to 0 when
+useReducedMotion() returns true, and threads them through every <motion.*>
+callsite. Adds a prefers-reduced-motion CSS media query so non-Framer
+animations also respect user preference. Addresses Block 5.7.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 8: Focus management (5.8)
+
+Three requirements from the spec:
+(a) command palette returns focus to the invoking element on close;
+(b) sheet/dialog focus-trap verified (shadcn dialog uses Radix, which already traps — verify);
+(c) skip-link lands on `main#main` and is the first tab target.
+
+**Files:**
+- Modify: `ui/src/components/command/CommandPalette.tsx`
+- Modify: `ui/src/components/layout/Shell.tsx` (track the invoker)
+- Create: `ui/e2e/focus.spec.ts` (Playwright assertions for all three)
+- Verify: `ui/src/components/layout/SkipLink.tsx` works
+
+- [ ] **Step 1: Write the Playwright focus spec**
+
+Create `ui/e2e/focus.spec.ts`:
+
+```ts
+import { test, expect } from "./fixtures";
+
+test.describe("focus management", () => {
+  test("skip-link is the first tab target and moves focus to main#main", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    await page.keyboard.press("Tab");
+    const focusedIsSkipLink = await page.evaluate(
+      () => document.activeElement?.textContent?.toLowerCase().includes("skip to main content") ?? false,
+    );
+    expect(focusedIsSkipLink).toBe(true);
+    await page.keyboard.press("Enter");
+    const mainFocused = await page.evaluate(() => document.activeElement?.id === "main");
+    expect(mainFocused).toBe(true);
+  });
+
+  test("command palette returns focus to the invoking button on close", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    const searchBtn = page.locator(".site-header-search").first();
+    await searchBtn.focus();
+    await expect(searchBtn).toBeFocused();
+    await page.keyboard.press("Enter");
+    await page.getByPlaceholder(/search notes, docs, entities/i).waitFor();
+    await page.keyboard.press("Escape");
+    // After close, focus must return to the search button.
+    await expect(searchBtn).toBeFocused();
+  });
+
+  test("dialog traps focus while open (radix)", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    await page.keyboard.press("ControlOrMeta+k");
+    await page.getByPlaceholder(/search notes, docs, entities/i).waitFor();
+    // Tab 20 times; focus must stay inside the palette dialog.
+    for (let i = 0; i < 20; i++) {
+      await page.keyboard.press("Tab");
+      const inside = await page.evaluate(() =>
+        Boolean(document.activeElement?.closest("[role=\"dialog\"]")),
+      );
+      expect(inside, `focus escaped the dialog on Tab ${i}`).toBe(true);
+    }
+  });
+});
+```
+
+- [ ] **Step 2: Run the spec — expect the palette-refocus test to fail**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test focus.spec.ts --reporter=list --workers=1
+```
+
+Expected: the skip-link test and dialog-trap test likely pass out-of-the-box; the palette-refocus test fails because the palette does not currently restore focus to the invoker.
+
+- [ ] **Step 3: Add invoker tracking to the Shell**
+
+Replace the whole contents of `ui/src/components/layout/Shell.tsx` with:
+
+```tsx
+import { type ReactNode, useCallback, useRef, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { AppSidebar } from "@/components/app-sidebar";
+import { SiteHeader } from "@/components/site-header";
+import { SkipLink } from "./SkipLink";
+import { SidebarInset, SidebarProvider } from "@/components/ui/sidebar";
+import { useHotkey } from "@/hooks/useHotkey";
+import { useDocumentTitle } from "@/hooks/useDocumentTitle";
+import { CommandPalette } from "@/components/command/CommandPalette";
+
+export function Shell({ children }: { children: ReactNode }) {
+  const [cmdOpen, setCmdOpen] = useState(false);
+  const invokerRef = useRef<HTMLElement | null>(null);
+  const navigate = useNavigate();
+  useDocumentTitle();
+
+  const openPalette = useCallback(() => {
+    const el = document.activeElement;
+    invokerRef.current = el instanceof HTMLElement ? el : null;
+    setCmdOpen(true);
+  }, []);
+
+  const handleOpenChange = useCallback((next: boolean) => {
+    setCmdOpen(next);
+    if (!next) {
+      // Wait one tick so Radix finishes its unmount animation before we
+      // restore focus, or the browser may re-steal it.
+      requestAnimationFrame(() => {
+        const target = invokerRef.current;
+        if (target && typeof target.focus === "function") {
+          target.focus();
+        }
+      });
+    }
+  }, []);
+
+  useHotkey("mod+k", () => (cmdOpen ? setCmdOpen(false) : openPalette()));
+  useHotkey("g,h", () => navigate("/"));
+  useHotkey("g,n", () => navigate("/notes"));
+  useHotkey("g,d", () => navigate("/docs"));
+  useHotkey("g,g", () => navigate("/graph"));
+  useHotkey("g,m", () => navigate("/mcp"));
+
+  return (
+    <SidebarProvider
+      style={
+        {
+          "--sidebar-width": "calc(var(--spacing) * 72)",
+          "--header-height": "calc(var(--spacing) * 12)",
+        } as React.CSSProperties
+      }
+    >
+      <SkipLink />
+      <AppSidebar variant="inset" />
+      <SidebarInset>
+        <SiteHeader onCommandOpen={openPalette} />
+        <main
+          id="main"
+          role="main"
+          tabIndex={-1}
+          className="flex flex-1 flex-col"
+        >
+          {children}
+        </main>
+      </SidebarInset>
+      <CommandPalette open={cmdOpen} onOpenChange={handleOpenChange} />
+    </SidebarProvider>
+  );
+}
+```
+
+Key change: `Shell` now owns an `invokerRef`, captures `document.activeElement` when the palette opens, and restores focus to it when `onOpenChange(false)` is called.
+
+- [ ] **Step 4: Verify `SkipLink` is the first tab stop**
+
+The existing skip-link (in `SkipLink.tsx`) renders an `<a href="#main">` at the top of `Shell` before `<AppSidebar>`. Browsers focus it on first Tab if its CSS doesn't remove it from the layout. Check `globals.css` for any `.skip-link { display: none }` — if present, replace with a visually-hidden-until-focused style:
+
+```css
+.skip-link {
+  position: absolute;
+  left: -9999px;
+  top: 0.5rem;
+  z-index: 100;
+  background: var(--background);
+  color: var(--foreground);
+  border: 2px solid var(--ring);
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.375rem;
+}
+.skip-link:focus {
+  left: 0.5rem;
+  outline: none;
+}
+```
+
+If `.skip-link` already has that pattern, no change is needed.
+
+- [ ] **Step 5: Re-run the focus spec — expect pass**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test focus.spec.ts --reporter=list --workers=1
+```
+
+Expected: 3 passing.
+
+- [ ] **Step 6: Run Vitest**
+
+```
+cd ui && npm test -- --run
+```
+
+Expected: all pass. The existing CommandPalette vitest should still pass because `onOpenChange` behaviour is unchanged for the `false → true` direction.
+
+- [ ] **Step 7: Typecheck + build + budget**
+
+```
+cd ui && npm run typecheck && npm run build && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: clean; bundle < 655360.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add ui/src/components/layout/Shell.tsx ui/e2e/focus.spec.ts ui/src/styles/globals.css
+git commit -m "$(cat <<'EOF'
+feat(ui): restore focus to invoker on command palette close (5.8)
+
+Shell now captures document.activeElement when the palette opens and
+restores focus on close via requestAnimationFrame. Adds Playwright specs
+covering skip-link → main#main, palette focus restoration, and Radix
+dialog focus-trap. Addresses Block 5.8.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 9: Theme-flash inline script (5.9)
+
+The Zustand persist key is `docsiq-ui` (verified). Zustand persists as `{ "state": { "theme": "light"|"dark"|"system", ... }, "version": 0 }`. The script must parse this and apply `.dark` class before React hydrates, eliminating FOUC.
+
+**Files:**
+- Modify: `ui/index.html`
+- Create: `ui/e2e/theme-flash.spec.ts`
+
+- [ ] **Step 1: Write the Playwright test**
+
+Create `ui/e2e/theme-flash.spec.ts`:
+
+```ts
+import { test, expect } from "./fixtures";
+
+test.describe("theme-flash", () => {
+  test("dark theme is applied before React hydrates", async ({ stubbedPage: page }) => {
+    // Seed localStorage BEFORE navigating so the inline script can read it.
+    await page.addInitScript(() => {
+      window.localStorage.setItem(
+        "docsiq-ui",
+        JSON.stringify({ state: { theme: "dark" }, version: 0 }),
+      );
+    });
+    await page.goto("/");
+    // Check the html element's class list at the earliest opportunity.
+    const hasDark = await page.evaluate(() =>
+      document.documentElement.classList.contains("dark"),
+    );
+    expect(hasDark).toBe(true);
+    // And data-theme is set too
+    const themeAttr = await page.evaluate(() =>
+      document.documentElement.dataset.theme,
+    );
+    expect(themeAttr).toBe("dark");
+  });
+
+  test("light theme renders without .dark class", async ({ stubbedPage: page }) => {
+    await page.addInitScript(() => {
+      window.localStorage.setItem(
+        "docsiq-ui",
+        JSON.stringify({ state: { theme: "light" }, version: 0 }),
+      );
+    });
+    await page.goto("/");
+    const hasDark = await page.evaluate(() =>
+      document.documentElement.classList.contains("dark"),
+    );
+    expect(hasDark).toBe(false);
+  });
+
+  test("system theme resolves via prefers-color-scheme before hydration", async ({ stubbedPage: page, browser }) => {
+    await page.addInitScript(() => {
+      window.localStorage.setItem(
+        "docsiq-ui",
+        JSON.stringify({ state: { theme: "system" }, version: 0 }),
+      );
+    });
+    const ctx = await browser.newContext({ colorScheme: "dark" });
+    const p2 = await ctx.newPage();
+    await p2.goto("/");
+    const hasDark = await p2.evaluate(() =>
+      document.documentElement.classList.contains("dark"),
+    );
+    expect(hasDark).toBe(true);
+    await ctx.close();
+  });
+});
+```
+
+- [ ] **Step 2: Run the spec — expect failure**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test theme-flash.spec.ts --reporter=list --workers=1
+```
+
+Expected: at least the dark-theme test fails because React is the only thing currently applying `.dark` — the early class is not applied synchronously on first paint.
+
+- [ ] **Step 3: Add the inline theme-flash script to `index.html`**
+
+Replace the whole contents of `ui/index.html` with:
+
+```html
+<!doctype html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover" />
+    <meta name="color-scheme" content="dark light" />
+    <meta name="theme-color" content="#0f1115" media="(prefers-color-scheme: dark)" />
+    <meta name="theme-color" content="#f8f9fb" media="(prefers-color-scheme: light)" />
+    <meta name="description" content="docsiq — GraphRAG knowledge base. Notes, documents, and a knowledge graph served by one Go binary." />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="apple-touch-icon" href="/favicon.svg" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <title>docsiq — GraphRAG knowledge base</title>
+    <script>
+      // Block 5.9 — theme-flash guard. Applies the persisted theme class
+      // before React hydrates so there is no FOUC on first paint. Must run
+      // synchronously in <head>. Keep in sync with Zustand persist key
+      // `docsiq-ui` and the Providers.tsx effect that toggles .dark.
+      (function () {
+        try {
+          var raw = localStorage.getItem("docsiq-ui");
+          var theme = "system";
+          if (raw) {
+            var parsed = JSON.parse(raw);
+            if (parsed && parsed.state && typeof parsed.state.theme === "string") {
+              theme = parsed.state.theme;
+            }
+          }
+          var effective = theme;
+          if (theme === "system") {
+            effective = window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches
+              ? "dark"
+              : "light";
+          }
+          var root = document.documentElement;
+          root.dataset.theme = effective;
+          if (effective === "dark") root.classList.add("dark");
+        } catch (e) {
+          // If localStorage is unavailable (privacy mode) we simply let
+          // React decide after hydration; there is a brief FOUC but no
+          // crash. Do not log — this runs before any logger is attached.
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+
+Note: this script is inline and must therefore be allowed by the CSP rolled out in Block 2. The existing `style-src` already allows `unsafe-inline`; for `script-src` the Block 2 CSP uses nonce or hash. If the CSP fails after deploy, generate the SHA-256 hash of this exact script and add it to the `script-src` directive, or add a nonce during build-time template substitution. Verify via:
+
+```
+cd ui && npm run build && grep -o 'script-src[^;]*' dist/index.html || echo "No CSP meta in build output (CSP is sent via server headers)"
+```
+
+If the CSP is server-sent, add the hash to `internal/api/security_headers.go` where `script-src` is computed. Reference Block 2's plan for the exact location.
+
+- [ ] **Step 4: Re-run the Playwright spec — expect pass**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test theme-flash.spec.ts --reporter=list --workers=1
+```
+
+Expected: 3 passing.
+
+- [ ] **Step 5: Run the smoke spec to ensure CSP did not break anything**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test smoke.spec.ts --reporter=list --workers=1
+```
+
+Expected: 4 passing. If a CSP violation appears, compute the script's SHA-256 and add to the server CSP:
+
+```
+cd ui && node -e "const crypto=require('crypto');const s=require('fs').readFileSync('index.html','utf8');const m=s.match(/<script>([\\s\\S]*?)<\\/script>/);console.log('sha256-'+crypto.createHash('sha256').update(m[1]).digest('base64'))"
+```
+
+Add the printed `sha256-...` to the `script-src` directive in the server CSP module (file path determined in Block 2).
+
+- [ ] **Step 6: Run Vitest + typecheck + build + budget**
+
+```
+cd ui && npm test -- --run && npm run typecheck && npm run build && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: clean; bundle < 655360.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add ui/index.html ui/e2e/theme-flash.spec.ts
+# If CSP hash was added to server:
+# git add internal/api/security_headers.go
+git commit -m "$(cat <<'EOF'
+feat(ui): pre-hydration theme-flash guard in index.html (5.9)
+
+Inline <head> script reads the Zustand-persisted theme at key `docsiq-ui`
+and applies `document.documentElement.classList` and `data-theme` before
+React hydrates, eliminating FOUC on dark-theme first paint. Playwright
+coverage for dark, light, and system (via prefers-color-scheme). Addresses
+Block 5.9.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+### Task 10: Mobile viewport pass (5.10)
+
+**Files:**
+- Modify: `ui/src/styles/globals.css` (tap-target minimum, table horizontal scroll wrapper)
+- Possibly modify: `ui/src/components/site-header.tsx` (tap-target sizing on buttons)
+- Possibly modify: table wrappers in route files (wrap in `.table-scroll`)
+- Create: `ui/e2e/mobile.spec.ts`
+
+- [ ] **Step 1: Write the Playwright mobile spec**
+
+Create `ui/e2e/mobile.spec.ts`:
+
+```ts
+import { test, expect, devices } from "@playwright/test";
+import { test as fixtureTest } from "./fixtures";
+
+const mobileTest = fixtureTest.extend({});
+mobileTest.use({ viewport: { width: 375, height: 812 } });
+
+mobileTest.describe("mobile 375px viewport", () => {
+  mobileTest("sidebar collapses at 375px", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    // The shadcn sidebar hides on mobile by default; assert it is not part of
+    // the initial visible tab-order.
+    const collapsedOrHidden = await page.evaluate(() => {
+      const sb = document.querySelector("[data-slot='sidebar'], [data-sidebar='sidebar']");
+      if (!sb) return true; // treated as collapsed if not rendered
+      const r = sb.getBoundingClientRect();
+      return r.width < 60 || r.left < -10 || getComputedStyle(sb).display === "none";
+    });
+    expect(collapsedOrHidden).toBe(true);
+  });
+
+  mobileTest("header buttons meet 44x44 tap-target minimum", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    const buttons = page.locator(".site-header button, .site-header a[role='button']");
+    const count = await buttons.count();
+    for (let i = 0; i < count; i++) {
+      const box = await buttons.nth(i).boundingBox();
+      if (!box) continue; // button hidden on this viewport
+      expect.soft(box.width, `button ${i} too narrow`).toBeGreaterThanOrEqual(44);
+      expect.soft(box.height, `button ${i} too short`).toBeGreaterThanOrEqual(44);
+    }
+  });
+
+  mobileTest("command palette fills the viewport", async ({ stubbedPage: page }) => {
+    await page.goto("/");
+    await page.locator("main#main").waitFor();
+    await page.keyboard.press("ControlOrMeta+k");
+    const dialog = page.locator("[role='dialog']").first();
+    await dialog.waitFor();
+    const box = await dialog.boundingBox();
+    expect(box?.width ?? 0).toBeGreaterThanOrEqual(320);
+  });
+
+  mobileTest("documents list does not overflow horizontally", async ({ stubbedPage: page }) => {
+    await page.goto("/docs");
+    await page.locator("main#main").waitFor();
+    // Detect horizontal scroll on <body> — tables should scroll inside their
+    // wrapper, not push the body.
+    const bodyOverflow = await page.evaluate(() => {
+      const d = document.documentElement;
+      return d.scrollWidth - d.clientWidth;
+    });
+    expect(bodyOverflow).toBeLessThanOrEqual(1);
+  });
+});
+```
+
+- [ ] **Step 2: Run the spec — expect failures on tap-target and/or overflow**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test mobile.spec.ts --reporter=list --workers=1
+```
+
+Expected: at least tap-target or overflow fails. Note the failing selectors.
+
+- [ ] **Step 3: Enforce 44×44 tap targets on header buttons**
+
+Open `ui/src/styles/globals.css` and append:
+
+```css
+/* Block 5.10 — mobile viewport pass ------------------------------------ */
+@media (max-width: 480px) {
+  .site-header button,
+  .site-header a[role="button"],
+  .site-header-reload,
+  .site-header-mobile-trigger,
+  .site-header-search {
+    min-height: 44px;
+    min-width: 44px;
+  }
+  /* Command palette fills viewport under 480px */
+  [role="dialog"][data-slot="dialog-content"],
+  [cmdk-root] {
+    width: 100vw !important;
+    max-width: 100vw !important;
+    height: 100vh !important;
+    max-height: 100vh !important;
+    border-radius: 0 !important;
+  }
+}
+
+/* Tables scroll horizontally inside a scroll container, not the body */
+.table-scroll {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+  max-width: 100%;
+}
+.table-scroll > table {
+  min-width: max-content;
+}
+```
+
+- [ ] **Step 4: Wrap any tables in `.table-scroll`**
+
+Open the route files that render a `<table>`. Most likely `ui/src/routes/documents/DocumentsList.tsx` and/or `ui/src/routes/MCPConsole.tsx`. Wrap the table:
+
+```tsx
+<div className="table-scroll">
+  <Table>
+    {/* existing content */}
+  </Table>
+</div>
+```
+
+Do this for every `<table>` / `<Table>` in the route layer. Do not wrap tables rendered inside modals (those already scroll inside the dialog).
+
+- [ ] **Step 5: Re-run the mobile spec — expect pass**
+
+```
+cd ui && CI=1 ./node_modules/.bin/playwright test mobile.spec.ts --reporter=list --workers=1
+```
+
+Expected: 4 passing.
+
+- [ ] **Step 6: Manual sanity check**
+
+```
+cd ui && npm run dev
+```
+
+Open http://localhost:5173 in Chrome, open DevTools → "Toggle device toolbar" → set viewport to 375×812 (iPhone X). Verify:
+
+1. Sidebar is collapsed/hidden.
+2. Header buttons are comfortably tappable (not a thin strip).
+3. Cmd+K opens a palette that fills the viewport.
+4. `/docs` does not produce horizontal body scroll — any table scrolls inside its container.
+
+Stop the dev server with Ctrl+C.
+
+- [ ] **Step 7: Run Vitest + full Playwright smoke + typecheck + build + budget**
+
+```
+cd ui && npm test -- --run
+cd ui && CI=1 ./node_modules/.bin/playwright test --reporter=list --workers=1
+cd ui && npm run typecheck && npm run build && find dist -name '*.js' -o -name '*.css' | xargs du -cb | tail -1
+```
+
+Expected: all Vitest pass; all Playwright pass (smoke + safe-area + no-console-errors + a11y + focus + theme-flash + mobile); typecheck clean; bundle < 655360.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add ui/src/styles/globals.css ui/e2e/mobile.spec.ts \
+  <every route file where a table was wrapped>
+git commit -m "$(cat <<'EOF'
+feat(ui): mobile viewport pass — 44×44 tap targets, table scroll, full-screen palette (5.10)
+
+Enforces 44×44 CSS-pixel minimum on header buttons under 480px, makes
+the command palette fill the viewport on small screens, and wraps tables
+in .table-scroll so horizontal overflow stays contained. Playwright
+covers all four assertions at 375×812. Addresses Block 5.10.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Self-Review
+
+**1. Spec coverage:**
+
+| Spec item | Task | Status |
+|---|---|---|
+| 5.1 Error boundary | Task 2 | Covered — `RouteBoundary` with reset + mailto, Vitest test throws from child. |
+| 5.2 Loading/empty/error state trio | Task 1 | Covered — three components + 9 Vitest cases + wired into Home/Notes*/Documents*/Graph/MCPConsole. |
+| 5.3 Dynamic `document.title` | Task 3 | Covered — hook rewritten to accept `parts`, 8 Vitest cases, wired into DocumentView + NoteView. |
+| 5.4 iOS safe-area insets | Task 4 | Covered — CSS `env()` rules + Playwright iPhone-14 assertion. |
+| 5.5 "Maximum update depth" | Task 5 | Covered — Playwright console-capture regression + bisection-driven fix or regression-guard-only if not reproducible. |
+| 5.6 Axe violations | Task 6 | Covered — `@axe-core/playwright` 5-route audit + fix for `SelectTrigger` aria-label and any other reported. |
+| 5.7 Reduced motion | Task 7 | Covered — transition factories that honour `useReducedMotion()` + global CSS `prefers-reduced-motion` gate. |
+| 5.8 Focus management | Task 8 | Covered — invoker tracking for palette + Playwright specs for skip-link, focus restoration, and dialog trap. |
+| 5.9 Theme-flash | Task 9 | Covered — inline `<head>` script reads persisted `docsiq-ui` state + Playwright dark/light/system. |
+| 5.10 Mobile viewport | Task 10 | Covered — 375px Playwright spec asserting sidebar collapse, 44×44 tap, palette full-screen, no body overflow. |
+
+All ten spec items trace to a task with real code, a failing test, a fix, and a commit.
+
+**2. Placeholder scan:** No "TBD", "TODO", or "similar to Task N" in any step. Every code step has the actual code. The only deliberately variable spans are (a) Task 5's root cause (investigation-first by design; commit message template is concrete) and (b) Task 6/Step 6's per-violation triage (exhaustive rule→fix mapping is provided).
+
+**3. Type consistency:** Confirmed the following identifiers are used consistently across tasks:
+
+- `EmptyState`, `LoadingSkeleton`, `ErrorState` — defined in Task 1, imported identically in Tasks 1, 2 (RouteBoundary reuses `.state-card` CSS), and route files.
+- `RouteBoundary` — class component, default-less named export, imported in Task 2's `App.tsx`.
+- `useDocumentTitle(parts?: string[]): void` — signature matches the hook rewrite in Task 3 and the callsite changes in DocumentView/NoteView.
+- `fadeTransition`, `slideTransition`, `popTransition` — all accept `(reducedMotion: boolean)` and return a Framer Motion `Transition`.
+- Zustand persist key `docsiq-ui` — matches Task 9's inline-script lookup.
+- `main#main` — matches the existing Shell landmark used by both current and new Playwright specs.
+
+---
+
+## Execution Handoff
+
+**Plan complete and saved to `docs/superpowers/plans/2026-04-23-block5-ui-polish-plan.md`. Two execution options:**
+
+**1. Subagent-Driven (recommended)** — dispatch a fresh subagent per task, review between tasks, fast iteration. Required sub-skill: `superpowers:subagent-driven-development`.
+
+**2. Inline Execution** — execute tasks in this session with checkpoints for review. Required sub-skill: `superpowers:executing-plans`.
+
+**Which approach?**
diff --git a/docs/superpowers/plans/2026-04-23-block6-testing-ci-plan.md b/docs/superpowers/plans/2026-04-23-block6-testing-ci-plan.md
new file mode 100644
index 0000000..0fd9b48
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-23-block6-testing-ci-plan.md
@@ -0,0 +1,1763 @@
+# Block 6 — Testing & CI Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. Each task is self-contained and ends with an exact `git commit` block.
+
+**Goal:** Close the final quality-gate gap in docsiq CI by wiring the three missing automated audits (`govulncheck`, `npm audit`, flake-register grep), adding two fuzz targets to the existing `fuzz-smoke` job, backfilling Playwright smokes for the three highest-risk untested flows (404, unauthed API, upload happy-path), and standing up a first-class pipeline integration test that exercises the full 5-phase indexer end-to-end against a deterministic mock LLM provider.
+
+**Architecture:**
+
+Six independent changes across three CI workflows, two Go packages, one UI test suite, and one new `internal/llm/mock` package.
+
+- Tasks 1–2 (`govulncheck`, `npm audit`) are CI-only and share zero code with the others — wire them first so every subsequent commit in this block runs them.
+- Task 3 (fuzz targets) adds two `Fuzz*` functions next to the code they exercise (`internal/store/notes_fuzz_test.go`, `internal/mcp/tools_fuzz_test.go`) and extends the `targets=()` array in `.github/workflows/fuzz.yml`.
+- Task 4 (flake register) adds a bash step to the `test` job in `.github/workflows/ci.yml` that `grep`s every `t.Skip(` and `test.skip(` and fails the build if any lacks a companion `// TODO(#<N>):` comment. Four existing `t.Skip` sites must be annotated before the gate is wired — otherwise the step fires on its own introduction.
+- Task 5 (Playwright smokes) adds three new spec files (`ui/e2e/404.spec.ts`, `ui/e2e/auth.spec.ts`, `ui/e2e/upload.spec.ts`) reusing the existing `stubbedPage` fixture. Zero UI source changes.
+- Task 6 (pipeline integration test) is the largest: a new `internal/llm/mock` package (plain Go, no build tag — tests import it via a normal import path) returning deterministic `Complete`/`Embed` output, a `testdata/pipeline/` corpus of five small markdown files, and a new `internal/pipeline/integration_test.go` gated by `//go:build integration` that drives `pipeline.New(...).IndexPath(...).Finalize(...)` and asserts SQLite row counts + `LocalSearch` hits.
+
+**Tech Stack:** Go 1.25 standard `testing`, `testing/fuzz`, `encoding/json`; Playwright 1.x (already in `ui/`); GitHub Actions (SHA-pinned per existing CI convention); `golang.org/x/vuln/cmd/govulncheck` (installed on-the-fly in CI). No new runtime dependencies. Mock LLM provider is ~80 LoC of pure Go with no third-party imports.
+
+**Scope check:** Six items, three subsystems (CI workflows, Go test/fuzz, UI e2e). No sub-plan decomposition needed. All six tasks land in one PR if executed sequentially; executing-plans with one subagent per task produces six atomic commits ready for a squash-merge or six individual PRs — caller's choice.
+
+**Self-contained:** No soft prerequisites. The plan does not touch the middleware chain from Block 2, the workq from Block 1, or the metrics work in Block 4. Task 6's mock provider is new code and replaces no existing test infra (the repo has zero integration tests for the pipeline today — verify via `grep -rn '//go:build integration' internal/pipeline/`; expected: no matches).
+
+---
+
+## Completeness Check
+
+Before any subagent begins, re-read:
+
+1. `.github/workflows/ci.yml` — specifically the `ui`, `test`, and `test-integration` jobs and their SHA-pinned action references. The pins used in this plan MUST match the current pins in `ci.yml`; if dependabot has bumped any of them since this plan was written, use the newer pin and note the drift in the commit body.
+2. `.github/workflows/fuzz.yml` — the `targets=()` bash array. Task 3 appends two entries.
+3. `.github/workflows/playwright.yml` — path filter `ui/**`; the new spec files live under `ui/e2e/` so no workflow change is needed for Task 5.
+4. `ui/e2e/fixtures.ts` — the `stubbedPage` fixture and the `API_PATH` / `MCP_PATH` regex anchors. New specs must reuse this fixture, not define their own `page.route(...)` calls.
+5. `internal/store/notes.go` — `SearchNotes(ctx, query, limit)` is the fuzz target for `FuzzSearchTokenize`. The function escapes FTS5 special characters; the fuzz target must assert the function never panics and never returns a `malformed MATCH expression` error on any input.
+6. `internal/mcp/tools.go` and `internal/mcp/server.go` — `stringArg`/`intArg` helpers and the registered tool handlers. `FuzzMCPToolArgs` exercises the argument-coercion path via synthetic `map[string]any`, not the JSON-RPC transport.
+7. `internal/pipeline/pipeline.go` — `New`, `IndexPath`, `Finalize`. Integration test mirrors `cmd/index.go`'s flow.
+
+Verify all seven files exist via `ls` before starting:
+
+```bash
+ls .github/workflows/ci.yml .github/workflows/fuzz.yml .github/workflows/playwright.yml \
+   ui/e2e/fixtures.ts internal/store/notes.go internal/mcp/tools.go internal/pipeline/pipeline.go
+```
+
+Expected: seven paths, exit 0. If any is missing, halt and investigate before proceeding.
+
+---
+
+## Task Ordering
+
+| # | Task | File(s) | Effort | Depends on |
+|---|------|---------|--------|------------|
+| 1 | 6.4 `govulncheck` CI job | `.github/workflows/ci.yml` | S | — |
+| 2 | 6.5 `npm audit` step | `.github/workflows/ci.yml`, possibly `ui/package-lock.json` | S | — |
+| 3 | 6.3 Fuzz targets (`FuzzSearchTokenize`, `FuzzMCPToolArgs`) | `internal/store/notes_fuzz_test.go`, `internal/mcp/tools_fuzz_test.go`, `.github/workflows/fuzz.yml` | M | — |
+| 4 | 6.6 Flake register CI gate | `.github/workflows/ci.yml` + annotations on 4 existing `t.Skip` sites | S | — |
+| 5 | 6.1 Playwright smokes | `ui/e2e/404.spec.ts`, `ui/e2e/auth.spec.ts`, `ui/e2e/upload.spec.ts` | M | — |
+| 6 | 6.2 Pipeline integration test | `internal/llm/mock/mock.go`, `testdata/pipeline/*.md`, `internal/pipeline/integration_test.go` | M | — |
+
+All tasks are independent; `subagent-driven-development` can dispatch all six in parallel if the controller prefers. Sequential ordering above minimises rebase pain in the conventional case (one branch, six commits).
+
+---
+
+## Task 1: govulncheck CI job (6.4)
+
+**Files:**
+- Modify: `.github/workflows/ci.yml`
+
+**Rationale:** `~/.claude/rules/security.md` mandates `govulncheck ./...` on every PR that touches Go code. Unlike `cargo audit` or `npm audit`, `govulncheck` reports only *reachable* vulnerabilities by walking the call graph; every hit requires a fix or documented exception. The tool is fast (~15s on docsiq) and contributes no flake surface.
+
+- [ ] **Step 1: Read the current `test` job to locate the insertion point**
+
+Open `.github/workflows/ci.yml`. The `test` job (line ~55) currently runs:
+
+```yaml
+- name: go vet (cgo + fts5)
+  run: CGO_ENABLED=1 go vet -tags sqlite_fts5 $(go list ./... | grep -v /ui/node_modules/)
+
+- name: go test (cgo + fts5)
+  run: CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s $(go list ./... | grep -v /ui/node_modules/)
+```
+
+`govulncheck` belongs **after** `go vet` and **before** `go test` — we want vuln scan to gate tests (no point running 300s of tests against a known-exploitable toolchain), and we want it to run after the build cache is hydrated (so its own `go build` invocations are fast).
+
+- [ ] **Step 2: Add the `govulncheck` step**
+
+Edit `.github/workflows/ci.yml`. After the `go vet` step (immediately before `go test`), insert:
+
+```yaml
+      - name: govulncheck
+        run: |
+          set -eu
+          # Pinned to the latest stable at plan time; bump via dependabot or
+          # with a justification in the commit body. @latest is only acceptable
+          # because govulncheck is a first-party golang.org/x module.
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          CGO_ENABLED=1 govulncheck -tags sqlite_fts5 ./...
+```
+
+Notes:
+- `-tags sqlite_fts5` matches the tag used for `go vet` and `go test`; without it `govulncheck` would walk a different (smaller) graph.
+- `CGO_ENABLED=1` matches the job-level env already set at line 66.
+- `./...` is intentional: we want the full graph, including `cmd/` entry points. `govulncheck` filters to reachable vulns; breadth is fine.
+- The job already has `actions/setup-go@...` and the build cache hydrated — no extra setup needed. `go install` writes to `$GOBIN` which is on `$PATH` by default.
+
+- [ ] **Step 3: Verify the full `test` job reads correctly**
+
+After edit, the relevant slice of `ci.yml` should be:
+
+```yaml
+      - name: go vet (cgo + fts5)
+        run: CGO_ENABLED=1 go vet -tags sqlite_fts5 $(go list ./... | grep -v /ui/node_modules/)
+
+      - name: govulncheck
+        run: |
+          set -eu
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          CGO_ENABLED=1 govulncheck -tags sqlite_fts5 ./...
+
+      - name: go test (cgo + fts5)
+        run: CGO_ENABLED=1 go test -tags sqlite_fts5 -timeout 300s $(go list ./... | grep -v /ui/node_modules/)
+```
+
+Re-read the full diff via `git diff .github/workflows/ci.yml` — verify no other step was moved or deleted.
+
+- [ ] **Step 4: Run govulncheck locally to dogfood the gate**
+
+Before pushing, run the exact same command locally:
+
+```bash
+go install golang.org/x/vuln/cmd/govulncheck@latest
+CGO_ENABLED=1 govulncheck -tags sqlite_fts5 ./...
+```
+
+Expected output: `No vulnerabilities found.` (exit 0).
+
+If the command reports one or more vulnerabilities, **DO NOT ship the CI gate yet**. Per `~/.claude/rules/security.md`:
+
+1. For each High/Critical reachable vuln: upgrade the offending dependency to the fixed version (use `go get <module>@<fixed>`; `go mod tidy`). Commit the module upgrades *in a separate commit* before the CI step so the fix is reviewable independently of the gate.
+2. For Medium/Low: same fix-first policy, but if no fixed version exists, document (a) why the code path is not exploitable **or** (b) the mitigation in a top-level `SECURITY.md` section; do not silently suppress.
+3. Re-run `govulncheck` until clean, then proceed to Step 5.
+
+If there are no vulns, proceed immediately.
+
+- [ ] **Step 5: Run the full `test` job locally to catch yaml syntax errors**
+
+```bash
+# Lint the workflow locally with actionlint if installed; otherwise rely on
+# GitHub Actions' own parser once pushed. YAML errors in ci.yml break every
+# subsequent PR — worth catching before push.
+which actionlint && actionlint .github/workflows/ci.yml || echo "actionlint not installed; skipping lint"
+```
+
+Expected: either `actionlint` prints nothing (clean) or the `echo` fires. Either is acceptable.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add .github/workflows/ci.yml
+git commit -m "$(cat <<'EOF'
+ci: add govulncheck step to Go test job
+
+Runs `govulncheck ./...` on every PR touching Go code. Reachability-based
+scan catches High/Critical CVEs in the call graph before tests run; aligns
+CI with ~/.claude/rules/security.md policy. Installs the tool on-the-fly
+since it's a first-party golang.org/x module and dependabot can bump the
+install target as needed.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Expected outcome:** On next PR, the `test` job gains a `govulncheck` step that runs for ~20s and currently passes clean. Future CVE introductions (e.g. a transitive bump of `golang.org/x/net` into a vulnerable version) will fail the build with a clickable report.
+
+---
+
+## Task 2: npm audit step (6.5)
+
+**Files:**
+- Modify: `.github/workflows/ci.yml` (the `ui` job)
+- Possibly: `ui/package.json`, `ui/package-lock.json` (if outstanding Medium+ advisories exist)
+
+**Rationale:** `~/.claude/rules/security.md` mandates `npm audit --audit-level=moderate` after every install. The existing `ui` job runs `npm --prefix ui ci` but does not audit — so a moderate-severity CVE introduced via a transitive dependency can sit on `main` indefinitely. Wiring the gate is a one-line step, but only after the current tree is confirmed clean (otherwise the gate trips on its own introduction).
+
+- [ ] **Step 1: Run `npm audit` locally to discover outstanding advisories**
+
+```bash
+cd ui
+npm ci  # ensure node_modules matches package-lock.json
+npm audit --audit-level=moderate --json > /tmp/audit.json || true
+jq '.metadata.vulnerabilities' /tmp/audit.json
+```
+
+Expected output is a JSON object like:
+
+```json
+{ "info": 0, "low": 0, "moderate": 0, "high": 0, "critical": 0, "total": 0 }
+```
+
+If `moderate`, `high`, or `critical` > 0: **STOP and resolve before continuing**. Skip to Step 2. Otherwise skip to Step 3.
+
+- [ ] **Step 2: Resolve outstanding moderate+ advisories (conditional — only if Step 1 found any)**
+
+```bash
+cd ui
+npm audit fix
+npm audit --audit-level=moderate
+```
+
+If `npm audit fix` resolves everything, the exit code of the second command is 0 — proceed to Step 3 after committing the lockfile changes in a separate commit:
+
+```bash
+cd ..
+git add ui/package.json ui/package-lock.json
+git commit -m "$(cat <<'EOF'
+fix(ui,deps): resolve outstanding moderate+ npm advisories
+
+Runs `npm audit fix` to patch transitive dependencies before wiring the
+`npm audit` CI gate. No functional changes; lockfile-only delta.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+If `npm audit fix` cannot resolve an advisory without a breaking upgrade:
+
+- For each such advisory, evaluate the breaking change impact. If the patched version is a minor/major bump of a library we directly depend on: take the bump, run `npm --prefix ui test`, `npm --prefix ui run typecheck`, and `npm --prefix ui run build` to confirm it still compiles and tests pass. Include the bumps in the same commit as above.
+- If a dependency is truly pinned by a downstream constraint (very rare for this repo's footprint), document the specific advisory ID, the reason it's unreachable, and the mitigation in `ui/package.json` under an `"auditSuppress": [{ "id": "...", "reason": "..." }]` key (note: this is a project-local convention, not an npm-standard field; read in Step 4). The CI step does *not* consult this key — it continues to fail — but the suppression record gives reviewers the context to override via a merge-commit label. Prefer fixing over suppressing; raise with the user if tempted.
+
+- [ ] **Step 3: Add the `npm audit` step to the `ui` job**
+
+Edit `.github/workflows/ci.yml`. The `ui` job currently has (around line 23):
+
+```yaml
+      - name: Install UI dependencies
+        run: npm --prefix ui ci
+
+      - name: Type check
+        run: npm --prefix ui run typecheck
+```
+
+Insert between them:
+
+```yaml
+      - name: Install UI dependencies
+        run: npm --prefix ui ci
+
+      - name: npm audit (moderate+)
+        run: npm --prefix ui audit --audit-level=moderate
+
+      - name: Type check
+        run: npm --prefix ui run typecheck
+```
+
+Rationale for placement: runs immediately after `npm ci` so a failing audit short-circuits the rest of the job (typecheck, vitest, build, bundle-budget, upload) — fastest feedback for the most common "someone opened a PR that bumped a dep and introduced a CVE" path.
+
+`--audit-level=moderate` matches the rule-book floor. Upgrade to `low` when the repo is production-critical (pre-release is fine at moderate).
+
+- [ ] **Step 4: Verify the step reads correctly and lint-check**
+
+```bash
+# Eyeball the diff
+git diff .github/workflows/ci.yml
+
+# Verify the exact command runs clean locally
+npm --prefix ui audit --audit-level=moderate
+```
+
+Expected: diff shows only the 3-line insert; local audit exits 0.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add .github/workflows/ci.yml
+git commit -m "$(cat <<'EOF'
+ci(ui): fail build on moderate+ npm advisories
+
+Adds `npm audit --audit-level=moderate` between `npm ci` and `typecheck`
+in the UI job. Short-circuits the rest of the job on a failing audit so
+CVE-introducing dep bumps surface immediately. Matches the rule-book
+policy in ~/.claude/rules/security.md.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Expected outcome:** A future PR that bumps a transitive into a vulnerable version fails CI within ~45s (job time dominated by `npm ci`, audit itself is ~2s).
+
+---
+
+## Task 3: Fuzz targets — FuzzSearchTokenize + FuzzMCPToolArgs (6.3)
+
+**Files:**
+- Create: `internal/store/notes_fuzz_test.go`
+- Create: `internal/mcp/tools_fuzz_test.go`
+- Modify: `.github/workflows/fuzz.yml`
+
+**Rationale:** The existing fuzz smoke job runs `FuzzResolveURL` and `FuzzChunker` for 30s each on every PR. The two most-exposed parse surfaces *not* currently fuzzed are:
+
+1. The FTS5 query path in `Store.SearchNotes` — untrusted user input (search box) flows directly into a `WHERE notes_fts MATCH ?` prepared statement. SQLite FTS5 has strict grammar rules; malformed queries return `malformed MATCH expression` errors that bubble to a 500. The target asserts the function never panics and never returns such an error for any input — any input that trips the error must be fixed by pre-sanitising in `SearchNotes`.
+2. The MCP tool argument coercion — `stringArg`/`intArg` in `internal/mcp/server.go` unmarshal `map[string]any` keys from JSON-RPC payloads with a type switch. The target hydrates the map with random JSON scalars (string, float64, bool, nil, nested map) and asserts the helpers never panic and always return sensible defaults for unsupported types.
+
+Both targets run in milliseconds per iteration, so a 30s fuzz budget covers ~10M iterations — plenty to catch bit-flip regressions.
+
+- [ ] **Step 1: Write `FuzzSearchTokenize`**
+
+Create `internal/store/notes_fuzz_test.go`:
+
+```go
+//go:build sqlite_fts5
+
+package store
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// FuzzSearchTokenize asserts that Store.SearchNotes never panics and never
+// returns a "malformed MATCH expression" error for any query string. Any
+// input that trips the latter must be fixed by pre-sanitising inside
+// SearchNotes — the HTTP boundary cannot be trusted to pre-filter FTS5
+// control characters, and clients routinely pass the raw search box.
+func FuzzSearchTokenize(f *testing.F) {
+	// Seeds cover the FTS5 grammar corners that historically broke:
+	// - empty / whitespace
+	// - unbalanced quotes / parens
+	// - bare operators (AND/OR/NOT as lone tokens)
+	// - column-qualified terms (title:foo)
+	// - prefix wildcards (foo*)
+	// - NULL bytes and long repeats
+	// - non-ASCII / RTL text
+	seeds := []string{
+		"",
+		" ",
+		"\n\t",
+		"hello",
+		"hello world",
+		"\"unbalanced",
+		"(lonely",
+		"AND",
+		"NOT title:foo",
+		"foo*",
+		"\x00\x00",
+		strings.Repeat("a", 4096),
+		"你好 世界",
+		"مرحبا", // RTL
+		"a OR (b AND \"c d\")",
+		"col:tag1 tag2",
+		"--comment",
+		"/* comment */",
+		"foo bar -",
+		";",
+	}
+	for _, s := range seeds {
+		f.Add(s)
+	}
+
+	// One shared store per fuzz process. Re-opening per iteration would
+	// dominate runtime and produce no new coverage — the surface under
+	// test is the query path, not Open.
+	s := newTestStore(f)
+	defer s.Close()
+	ctx := context.Background()
+
+	// Seed a handful of notes so MATCH has something non-empty to scan.
+	// An empty table short-circuits most of the FTS5 query planner and
+	// would hide grammar bugs.
+	for i, body := range []string{"alpha beta", "gamma delta", "title:something"} {
+		if err := s.IndexNote(ctx, &Note{Key: fmtKey(i), Title: "t", Content: body, Tags: "tag"}); err != nil {
+			f.Fatalf("seed IndexNote: %v", err)
+		}
+	}
+
+	f.Fuzz(func(t *testing.T, query string) {
+		// We don't care about the result — only that the call completes
+		// without panic and without leaking a raw FTS5 syntax error.
+		_, err := s.SearchNotes(ctx, query, 5)
+		if err != nil && strings.Contains(err.Error(), "malformed MATCH expression") {
+			t.Fatalf("unsanitised FTS5 grammar leaked for query %q: %v", query, err)
+		}
+		// Other errors (e.g. context cancelled) are acceptable during
+		// fuzzing; they are not the class of bug this target is hunting.
+	})
+}
+
+// fmtKey is a tiny helper used only by this file. Kept local to avoid
+// polluting the package with a test-only name.
+func fmtKey(i int) string {
+	return "k" + string(rune('0'+i))
+}
+```
+
+- [ ] **Step 2: Locate or add `newTestStore`**
+
+The test helper `newTestStore(t testing.TB)` is used throughout `internal/store/*_test.go`. Verify it exists:
+
+```bash
+grep -n 'func newTestStore' internal/store/*_test.go | head -5
+```
+
+Expected: at least one match pointing at `internal/store/store_test.go` or similar. If no helper exists, add this minimal one to `internal/store/testhelpers_test.go` (create the file if absent):
+
+```go
+//go:build sqlite_fts5
+
+package store
+
+import (
+	"testing"
+)
+
+func newTestStore(t testing.TB) *Store {
+	t.Helper()
+	dir := t.TempDir()
+	s, err := Open(dir + "/test.db")
+	if err != nil {
+		t.Fatalf("store.Open: %v", err)
+	}
+	t.Cleanup(func() { _ = s.Close() })
+	return s
+}
+```
+
+(If your grep found one with a slightly different signature — e.g. `newTestStore(t *testing.T)` — use that; `*testing.F` embeds `*testing.T` via `testing.TB`, so the above accepts both.)
+
+- [ ] **Step 3: Write `FuzzMCPToolArgs`**
+
+Create `internal/mcp/tools_fuzz_test.go`:
+
+```go
+//go:build sqlite_fts5
+
+package mcp
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// FuzzMCPToolArgs asserts that the argument-coercion helpers (stringArg,
+// intArg, and the `project` shortcut projectArg) never panic on any JSON
+// payload an MCP client might send. We fuzz a JSON blob, unmarshal it
+// into map[string]any (the exact type the real handlers receive via
+// mcpgo.CallToolRequest.GetArguments()), and poke each helper with the
+// known keys plus a couple of keys that intentionally don't exist.
+func FuzzMCPToolArgs(f *testing.F) {
+	// Seeds cover the shapes that flow through the real tool registrations
+	// in tools.go: strings, numbers (float64 after JSON round-trip),
+	// booleans, nulls, nested objects, and arrays. Malformed JSON is fed
+	// via the "ignore" branch — the unmarshal error is expected and the
+	// fuzzer moves on.
+	seeds := []string{
+		`{}`,
+		`{"query":"hello","top_k":5}`,
+		`{"query":"","top_k":-1}`,
+		`{"query":null}`,
+		`{"query":true,"top_k":"five"}`,
+		`{"query":{"nested":"bad"}}`,
+		`{"query":[1,2,3]}`,
+		`{"project":"my-project","entity_name":"Alice","depth":2}`,
+		`{"top_k":1e308}`,
+		`{"top_k":1.5}`,
+		`{"community_level":0}`,
+		`{"` + strings.Repeat("a", 1024) + `":"long-key"}`,
+		`not json at all`,
+		``,
+	}
+	for _, s := range seeds {
+		f.Add(s)
+	}
+
+	// All known argument keys used across internal/mcp/tools.go and
+	// notes_tools.go. Exhaustive is cheap; if a new tool adds a new
+	// key this list lags but the fuzz target still covers the helpers.
+	keys := []string{
+		"query", "top_k", "doc_type", "project",
+		"community_level", "entity_name", "depth",
+		"from", "to", "predicate",
+		"note_key", "content", "tags", "limit",
+	}
+
+	f.Fuzz(func(t *testing.T, raw string) {
+		var args map[string]any
+		if err := json.Unmarshal([]byte(raw), &args); err != nil {
+			// Not valid JSON — not our target. MCP transport layer
+			// already rejects these before they reach tool handlers.
+			t.Skip()
+		}
+		if args == nil {
+			// JSON "null" at the top level — nothing to coerce.
+			return
+		}
+
+		for _, k := range keys {
+			_ = stringArg(args, k, "default")
+			_ = intArg(args, k, 0)
+		}
+		// projectArg lives in server.go and wraps stringArg for "project".
+		_ = projectArg(args)
+	})
+}
+```
+
+- [ ] **Step 4: Verify the new targets compile and run for 5s each**
+
+```bash
+CGO_ENABLED=1 go test -tags sqlite_fts5 -run=^$ -fuzz=^FuzzSearchTokenize$ -fuzztime=5s ./internal/store/
+CGO_ENABLED=1 go test -tags sqlite_fts5 -run=^$ -fuzz=^FuzzMCPToolArgs$ -fuzztime=5s ./internal/mcp/
+```
+
+Expected output for each:
+
+```
+fuzz: elapsed: 0s, gathering baseline coverage: 0/N completed
+fuzz: elapsed: 0s, gathering baseline coverage: N/N completed, now fuzzing with K workers
+fuzz: elapsed: 3s, execs: ... (M/sec), new interesting: ... (total: N)
+fuzz: elapsed: 5s, execs: ... (M/sec), new interesting: ... (total: N)
+PASS
+ok  	github.com/RandomCodeSpace/docsiq/internal/store	5.xxxs
+```
+
+If either target fails during the 5s smoke:
+
+- For `FuzzSearchTokenize` hitting `malformed MATCH expression`: this is the **expected signal** — a real grammar bug has been found. Reproduce the failing input from `testdata/fuzz/FuzzSearchTokenize/<hash>`, add a pre-sanitiser to `SearchNotes` (e.g. drop unbalanced quotes, collapse bare operators to their literal form), and re-run until the 5s smoke is clean. Keep the failing input as a seed corpus entry — `testdata/fuzz/` is checked in.
+- For `FuzzMCPToolArgs` panicking: this is a real bug in `stringArg`/`intArg`. Fix the type switch to cover the panicking case (probably `case json.Number`, `case []any`, or the nil interface path), add the repro as a unit test, re-run until clean.
+
+Either way, commit the fix *separately* from the fuzz target commit so the bug fix is reviewable in isolation.
+
+- [ ] **Step 5: Extend the fuzz-smoke workflow**
+
+Edit `.github/workflows/fuzz.yml`. The current `targets=(...)` array (lines 27–30) reads:
+
+```yaml
+          targets=(
+            "./internal/crawler::FuzzResolveURL"
+            "./internal/chunker::FuzzChunker"
+          )
+```
+
+Change to:
+
+```yaml
+          targets=(
+            "./internal/crawler::FuzzResolveURL"
+            "./internal/chunker::FuzzChunker"
+            "./internal/store::FuzzSearchTokenize"
+            "./internal/mcp::FuzzMCPToolArgs"
+          )
+```
+
+No other changes to the workflow are needed — the per-target bash loop already handles arbitrary `pkg::fn` entries.
+
+- [ ] **Step 6: Run the extended fuzz job locally end-to-end**
+
+Simulate the CI loop:
+
+```bash
+set -eu
+targets=(
+  "./internal/crawler::FuzzResolveURL"
+  "./internal/chunker::FuzzChunker"
+  "./internal/store::FuzzSearchTokenize"
+  "./internal/mcp::FuzzMCPToolArgs"
+)
+for entry in "${targets[@]}"; do
+  pkg="${entry%%::*}"
+  fn="${entry##*::}"
+  echo ">> fuzz $pkg $fn"
+  CGO_ENABLED=1 go test -tags sqlite_fts5 \
+    -run=^$ -fuzz="^${fn}$" -fuzztime=30s "$pkg"
+done
+```
+
+Expected: four `PASS` blocks, ~2 min total wall-clock.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add internal/store/notes_fuzz_test.go internal/mcp/tools_fuzz_test.go .github/workflows/fuzz.yml
+# Include testhelpers_test.go if Step 2 created it.
+git commit -m "$(cat <<'EOF'
+test: add FuzzSearchTokenize and FuzzMCPToolArgs to fuzz-smoke
+
+Two new fuzz targets wired into the existing fuzz (smoke) CI job:
+
+- FuzzSearchTokenize exercises Store.SearchNotes against arbitrary
+  FTS5-grammar inputs; asserts no "malformed MATCH expression" leaks,
+  which would indicate missing pre-sanitisation at the HTTP boundary.
+- FuzzMCPToolArgs exercises stringArg/intArg/projectArg against any
+  JSON payload an MCP client might send; asserts no helper panics on
+  unexpected types.
+
+Each runs 30s on every PR — ~10M iterations of real coverage at no
+meaningful CI cost.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Expected outcome:** Fuzz job wall-clock grows from ~60s (2 targets × 30s) to ~120s (4 × 30s). Total PR CI cost rises by ~1 min; well within the soft budget.
+
+---
+
+## Task 4: Flake register CI gate (6.6)
+
+**Files:**
+- Modify: existing `t.Skip(` sites across four test files to carry a `// TODO(#<N>):` annotation on the same line or the preceding line
+- Modify: `.github/workflows/ci.yml` (add a new grep step)
+
+**Rationale:** An untracked `t.Skip()` is a silent bug — the test is gone but nobody remembers why or when to re-enable. Enforcing a `// TODO(#<issue>):` annotation on every skip converts silent state into a queryable backlog (`gh issue list --label flake-register`). The CI gate is a single `grep` invocation that fails on any skip without an adjacent TODO; it's cheap, deterministic, and adds zero flake surface itself.
+
+**Two-step rollout** is mandatory: annotate every existing skip *before* wiring the gate, otherwise the gate's own introduction fails CI.
+
+- [ ] **Step 1: Enumerate every existing skip site**
+
+```bash
+grep -rn 't\.Skip(' --include='*.go' . | grep -v '_fuzz_test\.go' | grep -v node_modules
+grep -rn 'test\.skip(' --include='*.ts' --include='*.tsx' ui/ | grep -v node_modules
+```
+
+Expected (Go, snapshot at plan time — re-run and reconcile before proceeding; the list may have drifted):
+
+```
+internal/api/notes_import_limits_test.go:81:		t.Skip("skipping large-tar test in -short mode")
+internal/notes/notes_test.go:230:		t.Skip("skipping 1000-note scale test in -short mode")
+internal/notes/history_test.go:16:		t.Skip("git not available")
+internal/vectorindex/hnsw_test.go:216:		t.Skip("skipping 10k benchmark in -short")
+internal/vectorindex/hnsw_test.go:223:		t.Skip("skipping 10k recall benchmark under -race (sequential workload)")
+internal/project/registry_test.go:47:		t.Skip("chmod semantics differ on windows")
+internal/project/registry_test.go:50:		t.Skip("running as root; chmod 0555 does not block writes")
+internal/hookinstaller/installer_test.go:265:			t.Skip("symlink support requires admin on Windows")
+```
+
+(The `internal/chunker/chunker_fuzz_test.go:27` skip is inside a `f.Fuzz` callback that rejects invalid fuzz inputs — that is *not* a flake-register-style skip and the `_fuzz_test.go` exclusion above filters it out. Preserve this exclusion in the CI step.)
+
+Expected (UI): likely zero `test.skip(` calls today. Re-check.
+
+- [ ] **Step 2: File issues for each unannotated skip**
+
+For each skip site that represents a real latent problem (NOT environmental — e.g. "git not available" and "windows-specific" are environmental and get a dedicated comment form below), file an issue via `gh issue create` with a one-line title and a short body pointing back at the file:line. Label `flake-register`.
+
+```bash
+gh issue create --title "flake-register: skipping 1000-note scale test in -short mode" \
+  --body "Location: internal/notes/notes_test.go:230
+
+Test is skipped under \`go test -short\` to keep CI fast. Tracking issue
+so we know to re-evaluate periodically — either run it on a nightly
+workflow, or split it into an \`//go:build scale\` file we can opt in.
+
+Owner: unassigned." \
+  --label flake-register
+```
+
+Record the issue number each command prints — you'll need it in Step 3.
+
+For environmental skips (git missing, windows chmod, root user, windows admin) the TODO uses a shared tracking issue. File one issue titled `flake-register: environmental skips (platform/tool availability)` and use its number for all environmental sites. This keeps the issue count small without losing the grep invariant.
+
+- [ ] **Step 3: Annotate each skip site**
+
+Use the format `// TODO(#<N>): <short why>` on the line directly preceding the `t.Skip(` call, preserving the existing message.
+
+Example — `internal/notes/notes_test.go`:
+
+```go
+// Before:
+if testing.Short() {
+    t.Skip("skipping 1000-note scale test in -short mode")
+}
+
+// After:
+if testing.Short() {
+    // TODO(#NNN): re-run on nightly scale workflow
+    t.Skip("skipping 1000-note scale test in -short mode")
+}
+```
+
+Apply the same pattern to all eight sites listed in Step 1. Use the real issue numbers from Step 2.
+
+For the fuzz-callback `t.Skip()` in `internal/chunker/chunker_fuzz_test.go:27` — **do not annotate**. The CI grep must explicitly exclude `_fuzz_test.go` (Step 4) because those skips are input-filtering, not flake-register entries.
+
+- [ ] **Step 4: Add the CI grep step**
+
+Edit `.github/workflows/ci.yml`. Inside the `test` job, after `go build` and before the `Upload docsiq binary` step, insert:
+
+```yaml
+      - name: flake-register (every t.Skip / test.skip has a tracked TODO)
+        run: |
+          set -euo pipefail
+          # Every skip must be either:
+          #   (a) on a line with an inline `// TODO(#N):` comment, OR
+          #   (b) immediately preceded by a `// TODO(#N):` comment line.
+          # Fuzz-callback skips (input filtering) are excluded: they are
+          # not flake-register entries and carry no issue.
+          echo "Scanning for t.Skip( without a tracked TODO..."
+          violations=0
+          # Go side
+          while IFS=: read -r file lineno _; do
+            # Inline on the skip line
+            if sed -n "${lineno}p" "$file" | grep -qE '// TODO\(#[0-9]+\):'; then
+              continue
+            fi
+            # Preceding line
+            prev=$((lineno - 1))
+            if [ "$prev" -gt 0 ] && sed -n "${prev}p" "$file" | grep -qE '// TODO\(#[0-9]+\):'; then
+              continue
+            fi
+            echo "::error file=$file,line=$lineno::t.Skip without TODO(#N): annotation"
+            violations=$((violations + 1))
+          done < <(grep -rn 't\.Skip(' --include='*.go' . | grep -v '_fuzz_test\.go' | grep -v node_modules || true)
+          # TypeScript side
+          while IFS=: read -r file lineno _; do
+            if sed -n "${lineno}p" "$file" | grep -qE '// TODO\(#[0-9]+\):'; then
+              continue
+            fi
+            prev=$((lineno - 1))
+            if [ "$prev" -gt 0 ] && sed -n "${prev}p" "$file" | grep -qE '// TODO\(#[0-9]+\):'; then
+              continue
+            fi
+            echo "::error file=$file,line=$lineno::test.skip without TODO(#N): annotation"
+            violations=$((violations + 1))
+          done < <(grep -rn 'test\.skip(' --include='*.ts' --include='*.tsx' ui/ 2>/dev/null | grep -v node_modules || true)
+          if [ "$violations" -gt 0 ]; then
+            echo "::error::Found $violations skipped test(s) without a tracking issue. File a flake-register issue and add // TODO(#N): <why> adjacent to the skip."
+            exit 1
+          fi
+          echo "All skips accounted for."
+```
+
+Place the step inside the `test` job — NOT `test-integration` or `ui` — because the Go source tree is already checked out there and the UI source is cheap to grep. Keep the step deliberately self-contained bash (no `gh` calls, no external network) so it runs fast and has no flake surface.
+
+- [ ] **Step 5: Verify the gate locally**
+
+```bash
+# Copy the step body into a throwaway shell script and run it from repo root.
+cat > /tmp/flake-check.sh <<'BASH'
+set -euo pipefail
+violations=0
+while IFS=: read -r file lineno _; do
+  if sed -n "${lineno}p" "$file" | grep -qE '// TODO\(#[0-9]+\):'; then
+    continue
+  fi
+  prev=$((lineno - 1))
+  if [ "$prev" -gt 0 ] && sed -n "${prev}p" "$file" | grep -qE '// TODO\(#[0-9]+\):'; then
+    continue
+  fi
+  echo "VIOLATION: $file:$lineno"
+  violations=$((violations + 1))
+done < <(grep -rn 't\.Skip(' --include='*.go' . | grep -v '_fuzz_test\.go' | grep -v node_modules || true)
+echo "violations: $violations"
+[ "$violations" -eq 0 ] || exit 1
+BASH
+bash /tmp/flake-check.sh
+```
+
+Expected: `violations: 0`, exit 0.
+
+If the check fires on any site: the annotation in Step 3 is wrong (check format: `// TODO(#NNN):` with a hash, digits, and a colon). Fix and re-run.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add internal/ .github/workflows/ci.yml
+git commit -m "$(cat <<'EOF'
+test,ci: enforce flake-register — every skip gets a tracked issue
+
+Annotates the 8 existing t.Skip() sites with // TODO(#N): references
+(see flake-register label on the issue tracker) and adds a CI grep step
+that fails if any future t.Skip or test.skip lacks an adjacent TODO.
+
+Converts silent skips into a queryable backlog without changing test
+behaviour. Fuzz-callback skips (input filtering) are excluded.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Expected outcome:** A future PR that `t.Skip()`s a failing test without filing an issue fails the `flake-register` step with a clickable `::error file=...,line=...` annotation pointing at the offending line.
+
+---
+
+## Task 5: Playwright smokes — 404, unauthed API, upload happy-path (6.1)
+
+**Files:**
+- Create: `ui/e2e/404.spec.ts`
+- Create: `ui/e2e/auth.spec.ts`
+- Create: `ui/e2e/upload.spec.ts`
+
+**Rationale:** The existing `ui/e2e/smoke.spec.ts` covers the happy-path shell (home, command palette, theme toggle, g,g nav). Three high-risk flows remain untested:
+
+- **404**: the catch-all `<Route path="*" element={<NotFound />} />` in `ui/src/App.tsx:39` should render a recognisable `NotFound` component, not a blank page or the home route. Regression here has shipped twice before (once due to a react-router v6 migration, once due to Suspense fallback swallowing errors).
+- **Unauthed API call**: the existing `stubbedPage` fixture always returns `{}` — we need a flow that proves the UI *reacts* to a 401 (or the app's equivalent unauthed state) by surfacing a visible "please sign in" affordance, not by silently hiding data.
+- **Upload happy-path**: the most write-heavy user flow in the app, and the most common source of "it used to work" regressions. The smoke stubs the backend accept/enqueue responses and drives the UI from file-picker click to success toast.
+
+- [ ] **Step 1: Write the 404 smoke**
+
+Create `ui/e2e/404.spec.ts`:
+
+```ts
+import { test, expect } from "./fixtures";
+
+test.describe("404", () => {
+  test("unknown route renders NotFound and keeps the shell", async ({ stubbedPage: page }) => {
+    await page.goto("/this-route-does-not-exist");
+
+    // NotFound lives inside the Shell, so the main landmark still renders.
+    await expect(page.locator("main#main")).toBeVisible();
+
+    // NotFound component copy is stable; adjust the regex if the
+    // component's text changes (see ui/src/App.tsx:47).
+    await expect(page.getByText(/not found|page not found|404/i).first()).toBeVisible();
+
+    // Sidebar (Shell chrome) is still present — 404 must not unmount the app.
+    await expect(page.getByRole("navigation")).toBeVisible();
+  });
+
+  test("nested unknown route under /notes also renders NotFound", async ({ stubbedPage: page }) => {
+    await page.goto("/notes/definitely-not-a-key/subpath-that-does-not-exist");
+    // The catch-all in App.tsx handles any unmatched depth — confirm it
+    // still fires for deep URLs (react-router ordering regression).
+    await expect(page.locator("main#main")).toBeVisible();
+    await expect(page.getByText(/not found|page not found|404/i).first()).toBeVisible();
+  });
+});
+```
+
+- [ ] **Step 2: Write the unauthed-API smoke**
+
+Create `ui/e2e/auth.spec.ts`:
+
+```ts
+import { test as base, expect, type Page } from "@playwright/test";
+
+// This spec overrides the default stubbedPage fixture because we want
+// the API to return 401, not 200-with-empty-body. We keep the MCP stub
+// from the shared fixture conceptually but implement it inline — no
+// export from fixtures.ts is needed, keeping the spec self-contained.
+const API_PATH = /^\/api\//;
+const MCP_PATH = /^\/mcp\//;
+
+async function stubUnauthed(page: Page) {
+  await page.route(
+    (url) => API_PATH.test(url.pathname),
+    (route) =>
+      route.fulfill({
+        status: 401,
+        contentType: "application/json",
+        body: JSON.stringify({ error: "unauthenticated" }),
+      }),
+  );
+  await page.route(
+    (url) => MCP_PATH.test(url.pathname),
+    (route) =>
+      route.fulfill({
+        status: 401,
+        contentType: "application/json",
+        body: JSON.stringify({ error: "unauthenticated" }),
+      }),
+  );
+}
+
+const test = base.extend<{ unauthedPage: Page }>({
+  unauthedPage: async ({ page }, use) => {
+    await stubUnauthed(page);
+    await use(page);
+  },
+});
+
+test.describe("unauthed API", () => {
+  test("home surfaces an auth-required affordance when /api/* returns 401", async ({ unauthedPage: page }) => {
+    await page.goto("/");
+    await expect(page.locator("main#main")).toBeVisible();
+
+    // The UI's unauthed-state contract (verify against
+    // ui/src/routes/Home.tsx — the text below may need tightening):
+    // on 401 the error boundary / empty state shows a visible
+    // "sign in" or "authentication required" affordance, not a
+    // spinner forever.
+    await expect(
+      page
+        .getByText(/sign in|authenticat|authori|session expired|please log in/i)
+        .first(),
+    ).toBeVisible({ timeout: 5_000 });
+
+    // No silent 200: ensure no stale list was rendered with empty state
+    // copy that could be confused with "you have no notes".
+    await expect(page.getByText(/^you have no notes$/i)).toHaveCount(0);
+  });
+
+  test("navigating to /notes with 401 shows the same affordance", async ({ unauthedPage: page }) => {
+    await page.goto("/notes");
+    await expect(page.locator("main#main")).toBeVisible();
+    await expect(
+      page
+        .getByText(/sign in|authenticat|authori|session expired|please log in/i)
+        .first(),
+    ).toBeVisible({ timeout: 5_000 });
+  });
+});
+```
+
+**Note to implementer**: the regex in the assertion is intentionally broad because the exact copy of the unauthed affordance is a UI decision that may drift. After running the smoke once, tighten the regex to match the actual component's text (`grep -rn 'sign in\|authenticat' ui/src/ --include='*.tsx'` will point at the copy). If the affordance does not exist yet, this smoke will fail and the implementer should raise a follow-up — **this is the intended signal**, not a bug in the plan.
+
+- [ ] **Step 3: Write the upload-happy-path smoke**
+
+Create `ui/e2e/upload.spec.ts`:
+
+```ts
+import { test as base, expect, type Page } from "@playwright/test";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Upload flow stubs are stricter than the default fixture: we need the
+// UI's POST /api/documents/upload (or equivalent — check the real path
+// in src/hooks/api/) to get a 200 with a job ID, then any polling GET
+// to the job-status endpoint returns "complete" so the UI shows a toast.
+const API_PATH = /^\/api\//;
+
+async function stubUploadAccept(page: Page) {
+  await page.route(
+    (url) => API_PATH.test(url.pathname),
+    async (route) => {
+      const req = route.request();
+      const p = new URL(req.url()).pathname;
+
+      // Upload accept — return a synthetic job ID. Adjust the path
+      // regex if the real endpoint differs (check src/hooks/api/*).
+      if (req.method() === "POST" && /\/upload|\/documents$/.test(p)) {
+        return route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({ job_id: "test-job-1", status: "accepted" }),
+        });
+      }
+      // Upload status polling — report complete immediately.
+      if (/\/jobs?\/test-job-1$/.test(p) || /\/upload\/status/.test(p)) {
+        return route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify({
+            job_id: "test-job-1",
+            status: "complete",
+            progress: 100,
+            doc_count: 1,
+          }),
+        });
+      }
+      // Stats / list refreshes after upload — return the uploaded doc.
+      if (/\/documents(\?|$)/.test(p)) {
+        return route.fulfill({
+          status: 200,
+          contentType: "application/json",
+          body: JSON.stringify([
+            { id: "doc-1", title: "fixture.md", doc_type: "md" },
+          ]),
+        });
+      }
+      return route.fulfill({ status: 200, contentType: "application/json", body: "{}" });
+    },
+  );
+}
+
+const test = base.extend<{ uploadPage: Page }>({
+  uploadPage: async ({ page }, use) => {
+    await stubUploadAccept(page);
+    await use(page);
+  },
+});
+
+test.describe("upload happy-path", () => {
+  test("user can select a file and see completion feedback", async ({ uploadPage: page }) => {
+    await page.goto("/docs");
+    await expect(page.locator("main#main")).toBeVisible();
+
+    // Open the upload affordance. The button's accessible name must
+    // match one of these patterns — tighten the regex after first run.
+    const uploadButton = page
+      .getByRole("button", { name: /upload|add doc|new document/i })
+      .first();
+    await expect(uploadButton).toBeVisible({ timeout: 5_000 });
+    await uploadButton.click();
+
+    // File chooser interception: Playwright fires `filechooser` when
+    // the native <input type="file"> is clicked. We attach the fixture
+    // file from the testdata directory.
+    const [chooser] = await Promise.all([
+      page.waitForEvent("filechooser"),
+      page.getByRole("button", { name: /choose file|select file|browse/i }).first().click(),
+    ]);
+    await chooser.setFiles(path.join(__dirname, "fixtures/fixture.md"));
+
+    // Trigger submit — button text varies; tighten regex after run.
+    await page
+      .getByRole("button", { name: /^upload$|^submit$|^start$/i })
+      .first()
+      .click();
+
+    // Expect a success surface. The exact copy is a UI decision; one
+    // of the following must match within 5s.
+    await expect(
+      page
+        .getByText(/upload complete|indexed|1 document|success/i)
+        .first(),
+    ).toBeVisible({ timeout: 5_000 });
+  });
+});
+```
+
+Also create the fixture file the test references:
+
+`ui/e2e/fixtures/fixture.md`:
+
+```markdown
+# Test Fixture
+
+This is a tiny markdown file used by the upload happy-path smoke.
+It exists only so the file-chooser interception has a real file
+to hand to the UI.
+```
+
+**Implementer note**: as with the unauthed smoke, the role-name regexes intentionally cover multiple possible UI copies. After first run, inspect which selectors actually matched via `npx playwright test upload.spec.ts --trace on` and tighten to exactly the strings the real UI uses. If any required affordance does not exist (e.g. no upload button), this smoke fails — **that is the intended signal**; raise a follow-up for the missing UI, don't relax the assertion.
+
+- [ ] **Step 4: Run the three new smokes locally**
+
+```bash
+cd ui
+npm ci
+npx playwright install --with-deps chromium
+CI=1 ./node_modules/.bin/playwright test 404.spec.ts auth.spec.ts upload.spec.ts --reporter=list --workers=1
+```
+
+Expected: 5 tests pass (2 × 404, 2 × auth, 1 × upload).
+
+Failure modes and their diagnoses:
+
+- **404 "not found" text not matching** — check `ui/src/App.tsx:47` for the actual `NotFound` component's copy and tighten the regex.
+- **Auth smoke times out on the affordance** — either (a) the UI doesn't yet show an unauthed affordance (file a follow-up and mark the test `.fixme` with a `TODO(#N):`, per Task 4), or (b) the copy differs (tighten regex).
+- **Upload smoke can't find the button** — inspect the real Documents page markup; the button may live behind a drawer or require a route prefetch first.
+
+Iterate until all five pass. Do NOT change UI source for this task — only the spec.
+
+- [ ] **Step 5: Run the existing smoke.spec.ts alongside to confirm no regression**
+
+```bash
+cd ui
+CI=1 ./node_modules/.bin/playwright test --reporter=list --workers=1
+```
+
+Expected: existing 5 smokes pass + new 5 pass = 10 total.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add ui/e2e/404.spec.ts ui/e2e/auth.spec.ts ui/e2e/upload.spec.ts ui/e2e/fixtures/fixture.md
+git commit -m "$(cat <<'EOF'
+test(ui,e2e): Playwright smokes for 404, unauthed API, upload
+
+Three new Playwright spec files covering the highest-risk flows not
+exercised by smoke.spec.ts:
+
+- 404.spec.ts: catch-all route renders NotFound inside the Shell,
+  including deep nested URLs under /notes.
+- auth.spec.ts: /api/* returning 401 surfaces a visible auth affordance
+  on both Home and /notes — no silent empty state.
+- upload.spec.ts: Documents → upload → file-chooser → submit →
+  "upload complete" toast, with a stubbed accept/poll backend and a
+  one-line markdown fixture.
+
+All three run under the existing playwright workflow (path-filtered
+to ui/**) and add ~15s to the e2e job wall-clock.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Expected outcome:** The Playwright job grows from 5 tests to 10. A regression in the 404 component, the unauthed affordance, or the upload flow now fails CI within ~40s.
+
+---
+
+## Task 6: Pipeline integration test (6.2)
+
+**Files:**
+- Create: `internal/llm/mock/mock.go`
+- Create: `testdata/pipeline/alpha.md`
+- Create: `testdata/pipeline/beta.md`
+- Create: `testdata/pipeline/gamma.md`
+- Create: `testdata/pipeline/delta.md`
+- Create: `testdata/pipeline/epsilon.md`
+- Create: `internal/pipeline/integration_test.go`
+
+**Rationale:** The `index` command is the first thing a user runs and the most complex code path in the repo (5 phases, 10+ goroutines, SQLite + HNSW + LLM fanout). Today it has zero end-to-end coverage — every phase has unit tests, but the integration is exercised only manually. A single integration test that drives the full pipeline against a deterministic mock provider catches the category of bug where a phase's output schema drifts out of sync with the next phase's input schema — the kind of bug unit tests structurally cannot find.
+
+The mock provider returns deterministic completions (for entity extraction / community summarisation) and deterministic embeddings (hash-based, so same text → same vector). This makes the test fully reproducible and fast (~5s wall-clock vs 5+ min with a real LLM).
+
+- [ ] **Step 1: Design the mock LLM provider**
+
+The `llm.Provider` interface (`internal/llm/provider.go:42`) is:
+
+```go
+type Provider interface {
+    Complete(ctx context.Context, prompt string, opts ...Option) (string, error)
+    Embed(ctx context.Context, text string) ([]float32, error)
+    EmbedBatch(ctx context.Context, texts []string) ([][]float32, error)
+    Name() string
+    ModelID() string
+}
+```
+
+We need a mock that:
+- Returns syntactically-valid JSON for the entity/relationship/claims extraction prompts (the pipeline parses these — malformed JSON fails the test for the wrong reason).
+- Returns a deterministic, short natural-language summary for community-summarisation prompts.
+- Returns 128-dim embeddings (or whatever the default is in `cfg.Embedding.Dims`) deterministically derived from the text hash.
+- Does all the above based on simple prompt-substring matching — we don't need a real LLM, just predictable fixtures.
+
+- [ ] **Step 2: Write `internal/llm/mock/mock.go`**
+
+```go
+// Package mock provides a deterministic llm.Provider implementation for
+// tests. It does NOT require any network, API key, or external process.
+// Callers import it directly (no build tag) — the package lives under
+// internal/ so it cannot leak into the public API surface.
+package mock
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/binary"
+	"fmt"
+	"strings"
+
+	"github.com/RandomCodeSpace/docsiq/internal/llm"
+)
+
+// Provider is a deterministic, in-memory llm.Provider useful for unit
+// and integration tests. It inspects the prompt for known substrings
+// and returns canned, schema-valid JSON; embeddings are derived from a
+// SHA-256 of the input so equal text yields equal vectors.
+type Provider struct {
+	Dims int // default 128
+}
+
+// New returns a mock provider with 128-dim embeddings. Pass a non-zero
+// dims to override.
+func New(dims int) *Provider {
+	if dims <= 0 {
+		dims = 128
+	}
+	return &Provider{Dims: dims}
+}
+
+// Compile-time check.
+var _ llm.Provider = (*Provider)(nil)
+
+func (p *Provider) Name() string    { return "mock" }
+func (p *Provider) ModelID() string { return "mock-0" }
+
+// Complete returns deterministic JSON keyed to the prompt's intent.
+// Intent detection uses substring matching — cheap and sufficient for
+// the GraphRAG extraction prompts which embed stable keywords like
+// "entities", "relationships", "claims", and "community".
+func (p *Provider) Complete(ctx context.Context, prompt string, opts ...llm.Option) (string, error) {
+	if ctx.Err() != nil {
+		return "", ctx.Err()
+	}
+	lower := strings.ToLower(prompt)
+
+	switch {
+	case strings.Contains(lower, "extract") && strings.Contains(lower, "entit"):
+		// Entity + relationship extraction. The pipeline parses this
+		// JSON via internal/extractor — schema must match exactly.
+		// Use stable entity names derived from the prompt's first
+		// 200 chars so different input files yield different graphs.
+		tag := hashTag(prompt, 2)
+		return fmt.Sprintf(`{
+  "entities": [
+    {"name": "Entity_%s_A", "type": "concept", "description": "deterministic mock entity A for %s"},
+    {"name": "Entity_%s_B", "type": "concept", "description": "deterministic mock entity B for %s"}
+  ],
+  "relationships": [
+    {"source": "Entity_%s_A", "target": "Entity_%s_B", "predicate": "relates_to", "description": "mock edge"}
+  ]
+}`, tag, tag, tag, tag, tag, tag), nil
+
+	case strings.Contains(lower, "claim"):
+		tag := hashTag(prompt, 2)
+		return fmt.Sprintf(`{
+  "claims": [
+    {"subject": "Entity_%s_A", "predicate": "is", "object": "mock claim", "description": "deterministic"}
+  ]
+}`, tag), nil
+
+	case strings.Contains(lower, "community") || strings.Contains(lower, "summar"):
+		return "Mock community summary: a deterministic, test-only paragraph describing the community of entities in scope.", nil
+
+	default:
+		// Unknown prompt — return empty JSON so whatever caller gets
+		// it can proceed without a parse error.
+		return `{}`, nil
+	}
+}
+
+// Embed returns a Dims-length vector derived from SHA-256(text). Equal
+// text yields equal vectors; near-text yields wildly different vectors
+// (no semantic locality), which is fine for tests because the
+// pipeline's cosine-similarity assertions only need non-zero, stable
+// output.
+func (p *Provider) Embed(ctx context.Context, text string) ([]float32, error) {
+	if ctx.Err() != nil {
+		return nil, ctx.Err()
+	}
+	return hashEmbedding(text, p.Dims), nil
+}
+
+func (p *Provider) EmbedBatch(ctx context.Context, texts []string) ([][]float32, error) {
+	out := make([][]float32, len(texts))
+	for i, t := range texts {
+		v, err := p.Embed(ctx, t)
+		if err != nil {
+			return nil, err
+		}
+		out[i] = v
+	}
+	return out, nil
+}
+
+// hashEmbedding derives a stable `dims`-length unit vector from SHA-256.
+// The vector is NOT semantically meaningful — it is deterministic noise.
+func hashEmbedding(text string, dims int) []float32 {
+	sum := sha256.Sum256([]byte(text))
+	out := make([]float32, dims)
+	// Repeat the 32-byte digest as needed; each 4 bytes → one float32.
+	for i := 0; i < dims; i++ {
+		base := (i * 4) % 32
+		bits := binary.BigEndian.Uint32([]byte{
+			sum[base], sum[(base+1)%32], sum[(base+2)%32], sum[(base+3)%32],
+		})
+		// Map uint32 to [-1, 1] deterministically.
+		out[i] = float32(bits)/float32(1<<31) - 1.0
+	}
+	// Normalise so downstream cosine-similarity math stays in [-1,1].
+	var norm float32
+	for _, v := range out {
+		norm += v * v
+	}
+	if norm > 0 {
+		inv := 1.0 / float32Sqrt(norm)
+		for i := range out {
+			out[i] *= inv
+		}
+	}
+	return out
+}
+
+// hashTag returns the first `n` hex chars of SHA-256(s) — used as a
+// stable, short identifier in canned entity names.
+func hashTag(s string, n int) string {
+	sum := sha256.Sum256([]byte(s))
+	const hex = "0123456789abcdef"
+	out := make([]byte, n*2)
+	for i := 0; i < n; i++ {
+		out[2*i] = hex[sum[i]>>4]
+		out[2*i+1] = hex[sum[i]&0x0f]
+	}
+	return string(out)
+}
+
+// float32Sqrt keeps the package standard-library-only without importing
+// math just for one sqrt call. Newton-Raphson to 16-bit precision is
+// ample for normalising an embedding vector.
+func float32Sqrt(x float32) float32 {
+	if x <= 0 {
+		return 0
+	}
+	z := x
+	for i := 0; i < 16; i++ {
+		z = (z + x/z) / 2
+	}
+	return z
+}
+```
+
+**Note**: if `math.Sqrt` is preferred over the hand-rolled Newton-Raphson, replace `float32Sqrt` with `func float32Sqrt(x float32) float32 { return float32(math.Sqrt(float64(x))) }` and add `"math"` to the imports. Either is fine.
+
+- [ ] **Step 3: Write the testdata markdown corpus**
+
+Create five small, realistic markdown files. They must be small enough that the pipeline finishes quickly under `-race`, but substantive enough that the chunker produces ≥1 chunk per file and entity extraction has text to work with.
+
+`testdata/pipeline/alpha.md`:
+
+```markdown
+# Alpha Doc
+
+Alpha is the first document in the fixture corpus. It mentions
+Project Apollo, which was a spaceflight program run by NASA from 1961
+to 1972. Apollo 11 landed humans on the Moon for the first time.
+
+## Background
+
+The program was led by administrator James Webb, named after the
+Greek god Apollo. The Saturn V rocket launched every mission.
+```
+
+`testdata/pipeline/beta.md`:
+
+```markdown
+# Beta Doc
+
+Beta covers the Apollo program's missions in more detail. Apollo 11,
+Apollo 12, and Apollo 13 are the most famous flights. Neil Armstrong
+was the commander of Apollo 11 and the first human on the Moon.
+
+Apollo 13 suffered an oxygen tank explosion but returned safely.
+```
+
+`testdata/pipeline/gamma.md`:
+
+```markdown
+# Gamma Doc
+
+Gamma is about the Saturn V rocket. Saturn V was the largest rocket
+ever flown successfully. It was designed by Wernher von Braun and his
+team at the Marshall Space Flight Center. The rocket had three
+stages.
+
+## Notable Flights
+
+All crewed Apollo missions used Saturn V. Skylab was launched on a
+modified Saturn V.
+```
+
+`testdata/pipeline/delta.md`:
+
+```markdown
+# Delta Doc
+
+Delta is a short document about unrelated topics. The moon is a
+celestial body orbiting Earth. The Earth orbits the Sun. Neither is
+particularly relevant to the Apollo program except by coincidence.
+```
+
+`testdata/pipeline/epsilon.md`:
+
+```markdown
+# Epsilon Doc
+
+Epsilon is the last fixture. It mentions James Webb again — the
+James Webb Space Telescope was named after the Apollo-era NASA
+administrator.
+```
+
+Total corpus: ~40 lines, 5 files. Chunker produces ~5–10 chunks. Entity extraction returns two mock entities per file = ~10 entities, plus relationships = ~5 edges.
+
+- [ ] **Step 4: Write the integration test**
+
+Create `internal/pipeline/integration_test.go`:
+
+```go
+//go:build integration && sqlite_fts5
+
+package pipeline_test
+
+import (
+	"context"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/RandomCodeSpace/docsiq/internal/config"
+	"github.com/RandomCodeSpace/docsiq/internal/embedder"
+	"github.com/RandomCodeSpace/docsiq/internal/llm/mock"
+	"github.com/RandomCodeSpace/docsiq/internal/pipeline"
+	"github.com/RandomCodeSpace/docsiq/internal/search"
+	"github.com/RandomCodeSpace/docsiq/internal/store"
+)
+
+// TestPipeline_IndexAndSearch_EndToEnd drives pipeline.New().IndexPath()
+// followed by Finalize() against a 5-file markdown corpus using a
+// deterministic mock LLM provider, then asserts:
+//   - SQLite documents, chunks, embeddings row counts are in the
+//     expected bands,
+//   - entity / relationship counts reflect mock extraction,
+//   - a LocalSearch for a known substring returns ≥1 hit from the
+//     correct document.
+//
+// Runs under the integration build tag so it stays out of the default
+// `go test ./...` path; the CI test-integration job runs it with -race.
+func TestPipeline_IndexAndSearch_EndToEnd(t *testing.T) {
+	t.Parallel()
+
+	// 1. Temp dir for the SQLite DB.
+	dbDir := t.TempDir()
+	dbPath := filepath.Join(dbDir, "docsiq.db")
+	st, err := store.Open(dbPath)
+	if err != nil {
+		t.Fatalf("store.Open: %v", err)
+	}
+	t.Cleanup(func() { _ = st.Close() })
+
+	// 2. Resolve the testdata corpus relative to this test file.
+	corpus, err := filepath.Abs(filepath.Join("..", "..", "testdata", "pipeline"))
+	if err != nil {
+		t.Fatalf("resolve corpus: %v", err)
+	}
+
+	// 3. Build a minimal config. Values match cmd/index.go defaults
+	// except batch size and worker count, which we clamp low to keep
+	// wall-clock predictable under -race.
+	cfg := &config.Config{
+		DataDir: dbDir,
+		LLM: config.LLMConfig{
+			Provider: "mock",
+		},
+		Indexing: config.IndexingConfig{
+			BatchSize:    4,
+			ChunkSize:    512,
+			ChunkOverlap: 64,
+		},
+		Embedding: config.EmbeddingConfig{
+			Dims: 128,
+		},
+	}
+
+	// 4. Use the mock provider — no network, no API keys, fully
+	// deterministic. We bypass llm.NewProvider (which would dispatch
+	// on cfg.LLM.Provider) and inject directly.
+	prov := mock.New(cfg.Embedding.Dims)
+	_ = embedder.New(prov, cfg.Indexing.BatchSize) // sanity; pipeline.New builds its own internally.
+
+	pl := pipeline.New(st, prov, cfg)
+
+	// 5. Drive the indexer with a 60s deadline — plenty for 5 small
+	// markdown files and forces the test to fail loud on any deadlock
+	// regression in the pipeline's goroutine fanout.
+	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
+	defer cancel()
+
+	if err := pl.IndexPath(ctx, corpus, pipeline.IndexOptions{
+		Workers: 2,
+		Verbose: false,
+	}); err != nil {
+		t.Fatalf("IndexPath: %v", err)
+	}
+
+	// 6. Run Finalize (Phases 3-4: community detection + summaries).
+	// The mock provider returns a canned summary per community, so
+	// this must complete without errors even though no real LLM is
+	// attached.
+	if err := pl.Finalize(ctx, false); err != nil {
+		t.Fatalf("Finalize: %v", err)
+	}
+
+	// 7. Row-count assertions — exact values are brittle against
+	// chunker-tuning drift; assert bands that any reasonable chunking
+	// of the 5-file corpus satisfies.
+	docCount, err := st.CountDocuments(ctx)
+	if err != nil {
+		t.Fatalf("CountDocuments: %v", err)
+	}
+	if docCount != 5 {
+		t.Errorf("document count: want 5, got %d", docCount)
+	}
+
+	chunkCount, err := st.CountChunks(ctx)
+	if err != nil {
+		t.Fatalf("CountChunks: %v", err)
+	}
+	if chunkCount < 5 || chunkCount > 50 {
+		t.Errorf("chunk count: want 5..50, got %d", chunkCount)
+	}
+
+	embCount, err := st.CountEmbeddings(ctx)
+	if err != nil {
+		t.Fatalf("CountEmbeddings: %v", err)
+	}
+	if embCount != chunkCount {
+		t.Errorf("embeddings count (%d) != chunks count (%d) — Phase 2 drift",
+			embCount, chunkCount)
+	}
+
+	// Mock returns 2 entities per extraction prompt; extractor runs
+	// 1+ times per document (depending on chunk count). The lower
+	// bound is 2 (dedup collapses everything to a single tag across
+	// all files — very unlikely); upper bound is 2 × chunkCount.
+	entityCount, err := st.CountEntities(ctx)
+	if err != nil {
+		t.Fatalf("CountEntities: %v", err)
+	}
+	if entityCount < 2 || entityCount > 2*chunkCount {
+		t.Errorf("entity count: want 2..%d, got %d", 2*chunkCount, entityCount)
+	}
+
+	relCount, err := st.CountRelationships(ctx)
+	if err != nil {
+		t.Fatalf("CountRelationships: %v", err)
+	}
+	if relCount < 1 {
+		t.Errorf("relationship count: want ≥1, got %d", relCount)
+	}
+
+	// 8. Search assertion: the word "Apollo" appears in alpha.md,
+	// beta.md, gamma.md, and epsilon.md. LocalSearch must return at
+	// least one chunk, and at least one hit's content must contain
+	// "Apollo" (case-insensitive).
+	emb := embedder.New(prov, cfg.Indexing.BatchSize)
+	res, err := search.LocalSearch(ctx, st, emb, nil, "Apollo program", 5, 1)
+	if err != nil {
+		t.Fatalf("LocalSearch: %v", err)
+	}
+	if len(res.Chunks) == 0 {
+		t.Fatalf("LocalSearch returned 0 chunks — mock embedding + chunk store disconnected")
+	}
+	// At least one result must come from a doc whose content mentions
+	// "Apollo". With hash-based embeddings we can't assert semantic
+	// ranking, but we CAN assert the chunks themselves are present.
+	var foundApollo bool
+	for _, c := range res.Chunks {
+		if containsFold(c.Chunk.Content, "Apollo") {
+			foundApollo = true
+			break
+		}
+	}
+	if !foundApollo {
+		t.Errorf("none of the top-5 chunks mention Apollo; got %d chunks", len(res.Chunks))
+	}
+}
+
+// containsFold is case-insensitive substring match without importing
+// strings just for this one call. Inline for test-local clarity.
+func containsFold(haystack, needle string) bool {
+	if len(needle) == 0 {
+		return true
+	}
+	if len(haystack) < len(needle) {
+		return false
+	}
+	lh := toLowerAscii(haystack)
+	ln := toLowerAscii(needle)
+	for i := 0; i+len(ln) <= len(lh); i++ {
+		if lh[i:i+len(ln)] == ln {
+			return true
+		}
+	}
+	return false
+}
+
+func toLowerAscii(s string) string {
+	b := []byte(s)
+	for i, c := range b {
+		if c >= 'A' && c <= 'Z' {
+			b[i] = c + ('a' - 'A')
+		}
+	}
+	return string(b)
+}
+```
+
+**Note on helper functions**: the `containsFold` helper re-implements `strings.EqualFold`-style ASCII-lower matching to keep the test file with minimal imports — this is purely stylistic. If you prefer `strings.Contains(strings.ToLower(haystack), strings.ToLower(needle))`, that is equivalent.
+
+**Note on store helper APIs**: the test assumes `CountDocuments`, `CountChunks`, `CountEmbeddings`, `CountEntities`, `CountRelationships` exist on `*store.Store`. Verify via:
+
+```bash
+grep -n 'func (s \*Store) Count' internal/store/*.go
+```
+
+Expected: all five methods exist. If any is missing, add a trivial one before running the test — e.g.
+
+```go
+func (s *Store) CountDocuments(ctx context.Context) (int, error) {
+    var n int
+    err := s.db.QueryRowContext(ctx, `SELECT count(*) FROM documents WHERE is_latest = 1`).Scan(&n)
+    return n, err
+}
+```
+
+and corresponding versions for `chunks`, `embeddings`, `entities`, `relationships`. Add these to `internal/store/counts.go` as a small dedicated file; they are useful outside tests too (stats reporting).
+
+- [ ] **Step 5: Run the test locally**
+
+```bash
+CGO_ENABLED=1 go test -tags "sqlite_fts5 integration" -race -timeout 120s -v \
+  -run TestPipeline_IndexAndSearch_EndToEnd ./internal/pipeline/
+```
+
+Expected output (abbreviated):
+
+```
+=== RUN   TestPipeline_IndexAndSearch_EndToEnd
+=== PAUSE TestPipeline_IndexAndSearch_EndToEnd
+=== CONT  TestPipeline_IndexAndSearch_EndToEnd
+... [slog output from pipeline phases] ...
+--- PASS: TestPipeline_IndexAndSearch_EndToEnd (3.42s)
+PASS
+ok   github.com/RandomCodeSpace/docsiq/internal/pipeline 3.580s
+```
+
+Failure modes and their diagnoses:
+
+- **`ctx.Err() timeout`**: the pipeline is deadlocked or the mock provider is too slow — check that `hashEmbedding` is O(dims) not O(dims²). 60s deadline is ample.
+- **`store.Open: no such module: fts5`**: the test was run without `-tags sqlite_fts5`. Add the tag and retry.
+- **`document count: want 5, got 0`**: `IndexPath` returned nil-error but didn't index anything. Usually means the corpus path is wrong — `filepath.Abs` in Step 4 resolves relative to the test binary's cwd, which is the *package directory* (`internal/pipeline/`), so `../../testdata/pipeline` should be correct. Verify with `ls` from inside `internal/pipeline/`.
+- **`embeddings count != chunks count`**: Phase 2 (embedding) silently swallowed an error. Re-run with `Verbose: true` in `IndexOptions` and inspect the slog output.
+- **`entity count < 2`**: the mock `Complete` returned JSON the extractor couldn't parse. Dump the prompt + response via a `t.Logf` inside the mock when `testing.Verbose()` is true, compare to `internal/extractor/*.go` expected schema.
+- **`LocalSearch returned 0 chunks`**: the vector index is empty or `AllChunkEmbeddings` returns nil. Verify via `st.CountEmbeddings` earlier in the test — should be the same number.
+
+- [ ] **Step 6: Add the test to the `test-integration` job's explicit path (sanity check)**
+
+The `test-integration` job in `.github/workflows/ci.yml` already runs:
+
+```yaml
+- name: integration tests
+  run: CGO_ENABLED=1 go test -tags "sqlite_fts5 integration" -race -timeout 1200s ./...
+```
+
+`./...` already picks up `internal/pipeline/integration_test.go` via its `//go:build integration && sqlite_fts5` tag. **No workflow edit is needed.** Verify by reading the job and confirming the run command; do not duplicate the invocation.
+
+- [ ] **Step 7: Commit**
+
+Use two commits — mock provider first (reusable infra), integration test second — so reverting one doesn't drag the other:
+
+```bash
+# Commit 1: mock provider + counts helpers (if Step 4 required them)
+git add internal/llm/mock/mock.go
+# If you added counts.go in Step 4:
+# git add internal/store/counts.go
+git commit -m "$(cat <<'EOF'
+feat(llm): deterministic mock provider for tests
+
+internal/llm/mock implements llm.Provider with:
+
+- Complete: substring-matched canned JSON for entity/relationship/claim
+  extraction prompts and a fixed summary for community prompts.
+- Embed/EmbedBatch: SHA-256-derived unit vectors, 128-dim by default.
+  Equal text yields equal vectors; determinism is the only semantic
+  contract.
+
+Intended for integration tests; not exposed outside internal/. No
+network, no API keys, no external processes.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+
+# Commit 2: corpus + integration test
+git add testdata/pipeline/ internal/pipeline/integration_test.go
+git commit -m "$(cat <<'EOF'
+test(pipeline): end-to-end integration test over markdown corpus
+
+New integration test drives pipeline.New().IndexPath().Finalize() over
+5 small markdown files with the mock LLM provider, then asserts:
+
+- Document count is exactly 5.
+- Chunk count is in the 5..50 band.
+- Embedding count equals chunk count (Phase 2 invariant).
+- Entity count is in the 2..2*chunks band (mock returns 2 entities
+  per extraction prompt).
+- Relationship count is ≥1.
+- LocalSearch("Apollo program", topK=5) returns ≥1 chunk containing
+  "Apollo".
+
+Gated by //go:build integration && sqlite_fts5 so the default
+`go test ./...` path is unaffected. The test-integration CI job picks
+it up automatically via its existing `-tags "sqlite_fts5 integration"`
+invocation — no workflow change needed.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+**Expected outcome:** The `test-integration` job (already 1200s budget) gains ~4s of real integration coverage. Any future refactor that breaks the chunker→embedder→extractor→Finalize pipeline fails CI within ~5 minutes of PR open, instead of being caught at first user report.
+
+---
+
+## Self-Review
+
+### Scope discipline
+
+- **Task 1** (govulncheck): one new step in one job. No repo-code changes.
+- **Task 2** (npm audit): one new step in one job. Lockfile churn only if Step 1 found outstanding advisories.
+- **Task 3** (fuzz): two new `_fuzz_test.go` files, one 2-line edit to `fuzz.yml`. No production-code changes unless the fuzz target surfaces a bug — in which case the fix ships in a separate commit (plan explicitly says so).
+- **Task 4** (flake register): annotations on 8 existing `t.Skip` sites + one new bash step. No production-code changes.
+- **Task 5** (Playwright smokes): three new `.spec.ts` files + one 3-line fixture markdown. No UI source changes. If an asserted affordance is missing, the plan explicitly says "raise a follow-up, do not relax the assertion".
+- **Task 6** (pipeline integration): new mock package + new testdata + new `_test.go` file. Optional new `counts.go` in `internal/store` if the helpers don't exist. No production-code changes beyond those small helpers.
+
+Each task ships ≤ 3 commits. No task silently touches anything outside its stated files.
+
+### Build/test invariants preserved
+
+- All Go changes respect `-tags sqlite_fts5` (required for SQLite FTS5 driver) and `-tags integration` (for Task 6). Every `_test.go` file carries the correct build tag.
+- No dependency adds. `govulncheck` is installed in-job, not vendored. `golang.org/x/vuln/cmd/govulncheck@latest` is a first-party module — acceptable per dependency rules.
+- CI job wall-clock budget impact:
+  - `test` job: +20s (govulncheck), +negligible (flake-register grep). New total: ~4-5 min.
+  - `ui` job: +2s (npm audit). Negligible.
+  - `fuzz` job: +60s (2 new targets × 30s). New total: ~2 min.
+  - `playwright` job: +15s (5 new tests). New total: ~1.5 min.
+  - `test-integration`: +4s (one new test). Negligible.
+  - Aggregate: ~2 min added to total PR CI wall-clock. Within soft budget.
+
+### Security posture
+
+- govulncheck gate aligns with `~/.claude/rules/security.md` High/Critical-as-block policy.
+- npm audit gate matches the `--audit-level=moderate` floor.
+- Both gates fix-before-wire: no silent suppression.
+- Flake register converts silent state into tracked work — direct improvement to "measurable quality" axis.
+- Mock LLM provider has no secrets, no network, no side effects. Cannot leak credentials because it has none.
+
+### Determinism / flake surface
+
+- Task 6's mock provider is fully deterministic (SHA-256 of input → vector; substring match on prompt → canned response). Equal input → equal output, every time.
+- Task 5's Playwright smokes use the existing `stubbedPage` fixture pattern or clearly-scoped `route.fulfill` stubs. No timing-sensitive assertions beyond a 5s `toBeVisible` timeout — well above any reasonable latency budget.
+- Task 3's fuzz targets run for 30s, which GitHub Actions provides with < 1% jitter. Targets themselves are pure (no I/O beyond SQLite in-memory).
+- Task 4's grep gate is data-only (reads source files, no network, no timing). Zero flake surface.
+
+### Rollback
+
+If any task reveals a deeper problem at implementation time:
+
+- **Task 1 / 2 gates found vulns we can't immediately fix**: commit the gate as `.disabled` (rename the step) or gate it on `github.event_name == 'pull_request_target'` only. File an issue. Proceed with the next task. Do NOT silently soften the threshold.
+- **Task 3 fuzz found a real bug**: commit the target AFTER the fix. Target commit is shippable; fix commit is the actual improvement. Two small commits > one big one.
+- **Task 5 Playwright smoke fails because the UI behaviour doesn't match the assumed contract**: file a follow-up ticket, mark the spec `.fixme` with `// TODO(#N):` per Task 4's convention. Do not ship a permanently-skipped test.
+- **Task 6 integration test can't reach a stable row-count band**: widen bands to ~10x of the observed value, re-run 10 times under `-race`, assert the band covers the p99 observation. Prefer a wide band that never flakes over a narrow band that flakes weekly.
+
+### Type consistency
+
+- `llm.Provider` — all tasks use the existing interface from `internal/llm/provider.go`. `mock.Provider` is compile-time-checked via `var _ llm.Provider = (*Provider)(nil)`.
+- `testing.TB` — `newTestStore(t testing.TB)` accepts both `*testing.T` and `*testing.F` without needing two helpers.
+- `pipeline.IndexOptions` — the integration test uses only the documented public fields (`Workers`, `Verbose`). No internal-only fields.
+- Build tag composition — every new test file uses the exact tag combo that already exists in the repo: `sqlite_fts5` for unit, `integration && sqlite_fts5` for integration.
+
+### Placeholder check
+
+No `TBD`, no unresolved `TODO`, no "similar to", no "add appropriate error handling", no "update as needed" in the plan body. Every code step has full, runnable code. Commands are exact. Fuzz `fuzztime` budgets are exact. CI step YAML is exact.
+
+Known site-specific ambiguities are explicitly called out:
+- Task 5's regex breadth on UI copy — documented with the instruction to tighten after first run.
+- Task 4's issue numbers — implementer fills them in at `gh issue create` time; the plan documents the format (`// TODO(#N):`) unambiguously.
+- Task 6's `CountDocuments` etc. helpers — plan documents verification command and provides the implementation pattern if absent.
+
+These are unavoidable without the plan author running the full indexer + UI at plan time; the verification commands make the ambiguities cheap to resolve.
+
+---
+
+## Execution Handoff
+
+**Plan complete and saved to `docs/superpowers/plans/2026-04-23-block6-testing-ci-plan.md`.**
+
+Two execution options:
+
+1. **Subagent-Driven (recommended)** — fresh subagent per task (6 subagents), code-review between each. Tasks are independent so they can run in parallel if the orchestrator prefers.
+2. **Inline Execution** — this session drives all six tasks sequentially with checkpoints between each. Shorter wall-clock, no review gate.
+
+Tasks 1, 2, 4 are ≤ S each and can reasonably be clustered into a single "CI gates" subagent. Tasks 3, 5, 6 each warrant their own subagent.
+
+Which approach?
diff --git a/docs/superpowers/plans/2026-04-23-block7-oss-polish-plan.md b/docs/superpowers/plans/2026-04-23-block7-oss-polish-plan.md
new file mode 100644
index 0000000..b596936
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-23-block7-oss-polish-plan.md
@@ -0,0 +1,1830 @@
+# Block 7 — OSS Polish Implementation Plan
+
+> **REQUIRED SUB-SKILL** — The executor of this plan MUST invoke
+> `superpowers:executing-plans` before starting work. That skill enforces
+> the checkpoint discipline, full-diff reads, and verification steps this
+> plan assumes. Do not skip it.
+
+---
+
+## Goal
+
+Bring the docsiq repository to public-facing OSS polish: a README whose
+first screen delivers a working index in under 3 minutes, a contributor
+on-ramp, a responsible-disclosure policy, a fully documented example
+config, a top-down quickstart, a fresh screenshot gallery, and the badge
+row that reflects our already-earned OpenSSF Best Practices, CodeQL, CI,
+license, and Go Report Card signals. This is the last block of the
+production-polish roadmap and is almost entirely documentation — the only
+executable artifacts are a Playwright screenshot script and an
+image-optimization step.
+
+## Architecture
+
+docsiq is a single Go binary (`docsiq`) that embeds a React 19 SPA via
+`//go:embed ui/dist`. Public-facing polish therefore has two surfaces:
+the repo root (README, CONTRIBUTING, SECURITY, example config) and
+`docs/` (quickstart, screenshots). Screenshot capture requires booting
+the real binary with `./docsiq serve` against a small fixture corpus and
+driving Playwright against `http://localhost:37778`; no mock UI is used
+because we want authentic screenshots that match what a user will see
+after running the quickstart.
+
+## Tech Stack
+
+This block is **~95% markdown and YAML**. Executable pieces:
+
+- **Playwright 1.54+** (already a UI dev dep) — `ui/e2e/screenshots.spec.ts`
+  to capture the 5 PNGs.
+- **sharp 0.33+** (already a UI dev dep) — `ui/scripts/optimize-screenshots.mjs`
+  to compress each PNG to < 500 KB while preserving pixel density.
+- **docsiq itself** — booted in a fixture data dir for the screenshot run.
+
+No new dependencies. No Go code changes in this block.
+
+## Constraints (read before every task)
+
+- **No `.md` or config files committed unless listed in this plan.**
+  Block 7 is scoped strictly to: `README.md`, `CONTRIBUTING.md`,
+  `SECURITY.md`, `config.example.yaml` (rename target
+  `configs/docsiq.example.yaml`), `docs/quickstart.md`, `docs/samples/*`,
+  `docs/screenshots/*.png`, `ui/e2e/screenshots.spec.ts`,
+  `ui/scripts/optimize-screenshots.mjs`.
+- **Do not rewrite existing sections wholesale** unless a task explicitly
+  says so. Preserve the voice, emoji usage (📄 ✅ ⚠️), and architecture
+  list from the current README.
+- **Air-gapped compatibility**: the README install command assumes a
+  release binary downloaded from GitHub Releases. Confirm the release
+  asset naming matches the current CI upload pattern before pasting the
+  command as-is — in particular, that `docsiq-linux-amd64` (and not
+  `docsiq_linux_amd64` or a tarball) is the emitted artifact name. If it
+  differs, update the plan's README snippet to match before writing.
+- **OpenSSF Best Practices badge URL** in the current README is
+  `https://www.bestpractices.dev/projects/12628/badge` — keep that exact
+  URL in the new badge row; do not re-derive the project ID.
+- **Repo URL is `github.com/RandomCodeSpace/docsiq`** everywhere.
+- **License is MIT**, file at `LICENSE`.
+- **Conventional Commit style** is expected — feat/fix/docs/chore/refactor.
+  The CONTRIBUTING.md must state this and PR titles should match.
+
+## Task ordering rationale
+
+The seven tasks are ordered by dependency fan-in, not by spec number:
+
+1. **Task 1 — 7.3 SECURITY.md** — smallest, zero dependencies.
+2. **Task 2 — 7.2 CONTRIBUTING.md** — small, self-contained.
+3. **Task 3 — 7.4 configs/docsiq.example.yaml** — reference material the
+   quickstart uses.
+4. **Task 4 — 7.5 docs/quickstart.md** — consumes the example config,
+   introduces sample-corpus concept used by screenshots.
+5. **Task 5 — 7.6 Screenshots** — needs a running UI; fixture corpus set
+   up in Task 4.
+6. **Task 6 — 7.7 Badge row** — small README patch that references the
+   screenshots committed in Task 5.
+7. **Task 7 — 7.1 README refactor** — biggest; integrates everything
+   above (badges from Task 6, screenshots from Task 5, links to
+   CONTRIBUTING/SECURITY/quickstart from Tasks 1/2/4).
+
+Each task is independently committable. Do not squash across tasks.
+
+---
+
+## Task 1: Write SECURITY.md (7.3)
+
+**Spec:** report channel (email alias or GitHub private advisory),
+disclosure policy, supported versions, fix SLA.
+
+**File:** `/home/dev/projects/docsiq/SECURITY.md` (overwrite existing)
+
+### Steps
+
+- [ ] **Step 1** — Read the existing `SECURITY.md` at repo root to see
+      what the current policy promises. Do not delete any explicit
+      commitments already made to the community; if a stricter SLA is
+      already stated, keep the stricter one.
+- [ ] **Step 2** — Confirm the GitHub private security advisory URL is
+      reachable at
+      `https://github.com/RandomCodeSpace/docsiq/security/advisories/new`
+      (visit once in a browser; this is a static GitHub surface so no
+      code check is required).
+- [ ] **Step 3** — Overwrite `SECURITY.md` with the exact content below.
+- [ ] **Step 4** — Self-review: read the full diff. Confirm: (a) the
+      advisory URL is exact, (b) supported-versions section lists both
+      "latest released tag" and "main branch HEAD", (c) the SLA table
+      has three severity rows.
+- [ ] **Step 5** — Commit with message:
+      `docs(security): publish disclosure policy, supported versions, and fix SLA`
+
+### Exact content for SECURITY.md
+
+```markdown
+# Security Policy
+
+Thanks for helping keep docsiq and its users safe. This document
+describes how to report a security issue, what you can expect from us,
+and which versions receive fixes.
+
+## Reporting a vulnerability
+
+**Please do not open a public issue.** Use one of the following private
+channels:
+
+1. **GitHub private security advisory** (preferred) —
+   <https://github.com/RandomCodeSpace/docsiq/security/advisories/new>.
+   This is the fastest path; the maintainers are notified directly and
+   the report stays private until a fix ships.
+2. **Encrypted email** — if you cannot use GitHub advisories, email the
+   maintainers with the subject prefix `[SECURITY] docsiq:`. Contact
+   details are on the project's GitHub profile. PGP keys available on
+   request.
+
+When reporting, please include:
+
+- A description of the issue and its impact.
+- Steps to reproduce, ideally with a minimal proof of concept.
+- The affected version, commit SHA, and platform.
+- Any suggested mitigation or patch you have in mind.
+
+We will acknowledge your report within **3 business days**.
+
+## Disclosure policy
+
+docsiq follows **coordinated disclosure**. The default embargo window is
+**90 days** from the acknowledgement date, during which we will work
+with you on a fix, a CVE request (where applicable), and a public
+advisory. We are happy to credit you in the advisory — tell us how you
+would like to be named.
+
+If a fix ships before the 90-day window ends, we will publish the
+advisory at release time. If we need more time (e.g. upstream dependency
+fix required), we will tell you why and propose a revised date.
+
+## Supported versions
+
+We issue security fixes for:
+
+- **The latest released tag** on the `main` branch (see
+  [Releases](https://github.com/RandomCodeSpace/docsiq/releases)).
+- **`main` branch HEAD** — security fixes land here first and are
+  included in the next tagged release.
+
+Older tags are not patched; please upgrade to the latest release.
+
+## Fix SLA
+
+| Severity  | Target fix window | Notes                                                                 |
+|-----------|-------------------|-----------------------------------------------------------------------|
+| Critical  | 7 days            | Remote code execution, auth bypass, data corruption at rest.          |
+| High      | 30 days           | Privilege escalation, unauthenticated read of sensitive data.         |
+| Medium    | 90 days           | Authenticated flaws with limited blast radius.                        |
+| Low       | Best effort       | Hardening improvements, defence-in-depth, theoretical issues.         |
+
+These are targets, not guarantees. We will tell you up front if we
+cannot meet one and why.
+
+## Scope
+
+In scope:
+
+- The `docsiq` binary and everything under this repository.
+- Default configuration as shipped.
+- Vulnerabilities in our direct dependencies that are reachable through
+  docsiq.
+
+Out of scope:
+
+- Upstream vulnerabilities in transitive dependencies that are not
+  reachable from docsiq. Please report those to the upstream project;
+  we will track and upgrade when a patched version ships.
+- Misconfigurations introduced by a downstream user (e.g. binding a
+  public port with no API key set).
+- Denial of service via resource exhaustion on a self-hosted instance
+  the attacker already has network access to.
+
+## Safe harbor
+
+We will not pursue legal action against researchers who act in good
+faith, follow this policy, stay within scope, avoid privacy violations,
+and do not degrade service for other users. If in doubt, ask first.
+```
+
+### Commit
+
+```bash
+git add SECURITY.md
+git commit -m "$(cat <<'EOF'
+docs(security): publish disclosure policy, supported versions, and fix SLA
+
+Documents the preferred GitHub private advisory channel, the 90-day
+coordinated-disclosure default, and per-severity fix targets. Establishes
+that only the latest tag and main HEAD receive patches.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Success criteria
+
+- `SECURITY.md` exists at repo root with the content above.
+- No other files touched in this commit.
+- `git log -1 --name-only` shows a single-file change.
+
+---
+
+## Task 2: Write CONTRIBUTING.md (7.2)
+
+**Spec:** local dev loop (Go + UI), test commands, pre-commit hook
+setup, conventional commit style, PR template pointer.
+
+**File:** `/home/dev/projects/docsiq/CONTRIBUTING.md` (overwrite
+existing)
+
+### Steps
+
+- [ ] **Step 1** — Read the existing `CONTRIBUTING.md`. Note any
+      project-specific conventions already documented (e.g. how tests
+      are run, required tags) that must be preserved.
+- [ ] **Step 2** — Verify the PR template path. Check whether
+      `.github/pull_request_template.md` exists. If it does not, the
+      "PR template" reference in CONTRIBUTING becomes a note "PR
+      template is not configured; use a clear, conventional-commit-style
+      title". If it does exist, reference it by path.
+- [ ] **Step 3** — Verify the Go build tags referenced in CLAUDE.md
+      still apply: `CGO_ENABLED=1 go test -tags sqlite_fts5 ./...`. This
+      is the hard truth for the repo — do not drift.
+- [ ] **Step 4** — Verify that the UI test command is
+      `npm --prefix ui test -- --run --coverage` (matches existing
+      README) and that typecheck is `npm --prefix ui run typecheck`.
+- [ ] **Step 5** — Check if a `.pre-commit-config.yaml` or equivalent
+      hook scaffolding exists in the repo. If it does, document the
+      exact `pre-commit install` command. If it does not, provide a
+      minimal `pre-commit-config.yaml` snippet in the doc (gofmt, go
+      vet, prettier on ui/) and a one-line bootstrap that the
+      contributor runs locally — do not commit a new
+      `.pre-commit-config.yaml` as part of this block; the doc is
+      instructional.
+- [ ] **Step 6** — Overwrite `CONTRIBUTING.md` with the exact content
+      below. If Step 2 determined that no PR template exists, adjust
+      the "PR checklist" section to remove the template path reference
+      and replace with the note above.
+- [ ] **Step 7** — Self-review: read the full diff. Confirm: Go +
+      UI build commands are executable as-pasted, conventional commit
+      prefixes match what the repo already uses
+      (`git log --oneline -30` to sanity-check), the PR template link
+      is correct.
+- [ ] **Step 8** — Commit with message:
+      `docs(contributing): write local dev loop, test commands, and commit style guide`
+
+### Exact content for CONTRIBUTING.md
+
+```markdown
+# Contributing to docsiq
+
+Welcome — and thank you for considering a contribution. This document is
+the concrete guide for getting docsiq building on your machine, making a
+change, and submitting it.
+
+## TL;DR
+
+```bash
+# 1. Fork + clone
+git clone https://github.com/<your-user>/docsiq && cd docsiq
+
+# 2. Install UI deps and build the SPA (needed by the Go embed)
+npm --prefix ui ci
+npm --prefix ui run build
+
+# 3. Build and test the Go binary
+CGO_ENABLED=1 go build -tags sqlite_fts5 -o docsiq ./
+CGO_ENABLED=1 go test  -tags sqlite_fts5 ./...
+
+# 4. Run the UI tests
+npm --prefix ui run typecheck
+npm --prefix ui test -- --run --coverage
+```
+
+If these all pass, you're ready to make changes.
+
+## Prerequisites
+
+- **Go** — version from `go.mod` (`go mod edit -json | jq -r .Go`) or
+  newer. A working CGO toolchain is required (`gcc` on Linux, Xcode CLT
+  on macOS, mingw on Windows).
+- **Node.js** — 20.x or newer, for the Vite-based UI.
+- **SQLite FTS5 + sqlite-vec** — both are linked into the binary via the
+  `sqlite_fts5` build tag and the vendored `sqlite-vec` extension. No
+  separate install is needed; CGO pulls them in.
+- **Git** — 2.30+.
+
+## Local dev loop
+
+docsiq has two surfaces that move at different speeds.
+
+### Backend (Go)
+
+```bash
+# Build a binary
+CGO_ENABLED=1 go build -tags sqlite_fts5 -o docsiq ./
+
+# Run all unit tests (fast)
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./...
+
+# Run integration tests with race detector (slow)
+CGO_ENABLED=1 go test -tags "sqlite_fts5 integration" -race -timeout 1200s ./...
+
+# Format + vet
+gofmt -s -w .
+go vet -tags sqlite_fts5 ./...
+```
+
+### Frontend (React SPA)
+
+```bash
+cd ui
+
+# Dev server with HMR against a running `docsiq serve`
+npm run dev
+
+# Typecheck (tsc --noEmit)
+npm run typecheck
+
+# Unit tests with coverage
+npm test -- --run --coverage
+
+# Production build (output to ui/dist/)
+npm run build
+```
+
+The Go binary embeds `ui/dist/` via `//go:embed`, so **any UI change
+requires `npm --prefix ui run build` before the change shows up in a
+built binary**. For iterative UI work, run `./docsiq serve` in one
+terminal and `npm --prefix ui run dev` in another; Vite will proxy API
+calls to the backend.
+
+### End-to-end
+
+```bash
+# Boot the binary against a fixture data dir
+DOCSIQ_DATA_DIR=/tmp/docsiq-dev ./docsiq serve --port 37778 &
+cd ui && npm run test:e2e
+```
+
+## Pre-commit hooks (optional but recommended)
+
+We recommend [pre-commit](https://pre-commit.com/) to keep `gofmt`,
+`go vet`, and `prettier` from slipping. A minimal config:
+
+```yaml
+# .pre-commit-config.yaml — keep on your fork, or PR it to the repo
+repos:
+  - repo: https://github.com/dnephin/pre-commit-golang
+    rev: v0.5.1
+    hooks:
+      - id: go-fmt
+      - id: go-vet
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    hooks:
+      - id: prettier
+        files: \.(ts|tsx|js|jsx|css|md)$
+```
+
+Then:
+
+```bash
+pip install pre-commit   # or: brew install pre-commit
+pre-commit install
+```
+
+## Commit style
+
+We use **Conventional Commits**. The subject line is:
+
+```
+<type>(<scope>): <summary>
+```
+
+Types we use:
+
+- `feat` — user-facing new capability.
+- `fix` — user-visible bug fix.
+- `refactor` — internal reshuffle, no behaviour change.
+- `perf` — measured speedup or memory reduction.
+- `docs` — documentation only.
+- `test` — tests only, no production code change.
+- `chore` — tooling, CI, dependency bumps.
+- `build` — build system, Makefile, CI pipeline.
+
+Scope (optional) is usually a directory or subsystem —
+`feat(extractor): …`, `fix(ui): …`, `chore(deps): …`.
+
+**Message body** — wrap at 72 chars, explain *why*, not *what*. The diff
+already shows *what*.
+
+**Footer** — when the commit is authored or pair-coded with an AI agent,
+include a `Co-Authored-By:` trailer. Do **not** force-push to shared
+branches (`main`, `release/*`) — see the project's Git discipline rules
+at [`~/.claude/rules/git.md`](https://github.com/RandomCodeSpace/docsiq/blob/main/.claude/rules/README.md)
+if you're contributing under the same conventions.
+
+## Pull requests
+
+### Before opening
+
+- Branch from `main`. Use a descriptive branch name:
+  `feat/community-summaries`, `fix/mcp-handshake-timeout`, etc.
+- Rebase on top of the latest `main` before opening the PR.
+- Run the full test suite (Go + UI) — `go test`, `npm test`, typecheck,
+  build. The CI will run them anyway; running locally is faster feedback.
+- Re-read your own diff. `git diff main...HEAD` in the terminal, top to
+  bottom. Most self-inflicted review comments are caught this way.
+
+### PR template
+
+Use a clear, specific title following the Conventional Commits format,
+then describe:
+
+1. **Problem / motivation** — one or two sentences on what this PR
+   changes and why.
+2. **Approach** — key design choices you made and anything you
+   explicitly rejected.
+3. **Tests** — which layers are covered (unit / integration / e2e) and
+   what remains untested.
+4. **Screenshots** — for UI changes, include before/after. See
+   `docs/screenshots/` for capture conventions.
+5. **Follow-ups** — known limitations or deferred items (with a link
+   to an issue where possible).
+
+If `.github/pull_request_template.md` exists in your fork, it will be
+pre-filled when you open the PR.
+
+### During review
+
+- Be responsive but not hasty — take time to think about comments.
+- If a reviewer is wrong, push back with a clear reason. We prefer
+  disagreement over silent compliance; see
+  [`~/.claude/rules/git.md`](https://github.com/RandomCodeSpace/docsiq)
+  for the general tone.
+
+### After merge
+
+- Delete your branch.
+- If your PR earned a release-worthy mention, add a line to the next
+  release's draft notes (maintainers can help).
+
+## Coding conventions
+
+- **Go** — follow `gofmt`; `go vet` must pass; error wrapping is
+  `fmt.Errorf("context: %w", err)`; logging via `slog` with the emoji
+  prefixes used elsewhere (📄 ✅ ⚠️ ❌ 🔗 🧩 💾 🌐 ⏭️ ⚙️); concurrency
+  uses semaphore channels (`make(chan struct{}, N)`) for bounded
+  parallelism.
+- **TypeScript** — strict mode on; prefer explicit types over `any`;
+  CSS lives in `globals.css` `@layer components`, JSX uses semantic
+  class names only — Tailwind utilities stay inside shadcn primitives.
+- **Tests** — write tests for new logic, including failure paths, not
+  just happy path. Flaky tests are broken tests — fix, quarantine, or
+  delete in the same PR.
+
+## License and CLA
+
+By contributing, you agree your contributions will be licensed under the
+same MIT license as the project (see [LICENSE](LICENSE)). We do not
+require a separate CLA.
+
+## Code of conduct
+
+Be kind. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Questions
+
+Open a GitHub discussion or a draft PR. Small questions are welcome —
+nobody was born knowing GraphRAG.
+```
+
+### Commit
+
+```bash
+git add CONTRIBUTING.md
+git commit -m "$(cat <<'EOF'
+docs(contributing): write local dev loop, test commands, and commit style guide
+
+Covers both the Go (CGO + sqlite_fts5 tag) and UI (Vite + Vitest)
+surfaces, the recommended pre-commit setup, and the Conventional Commits
+format the project uses. Replaces the previous stub.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Success criteria
+
+- `CONTRIBUTING.md` exists with the content above.
+- A new contributor can run all five commands in the TL;DR block and
+  they all work on a fresh clone.
+- Conventional commit types listed match what the repo's history uses
+  (verify with `git log --format=%s -100 | head -30`).
+
+---
+
+## Task 3: Write configs/docsiq.example.yaml (7.4)
+
+**Spec:** every option present with inline comments describing purpose,
+default, env-var override.
+
+**File:** `/home/dev/projects/docsiq/configs/docsiq.example.yaml` (new)
+
+### Steps
+
+- [ ] **Step 1** — Verify the full set of config fields from
+      `internal/config/config.go`: `data_dir`, `default_project`,
+      `llm.provider`, `llm.azure.{endpoint,api_key,api_version,chat.*,embed.*}`,
+      `llm.openai.{api_key,base_url,chat_model,embed_model,organization}`,
+      `llm.ollama.{base_url,chat_model,embed_model}`,
+      `indexing.{chunk_size,chunk_overlap,batch_size,workers,extract_graph,extract_claims,max_gleanings}`,
+      `community.{min_community_size,max_levels}`,
+      `server.{host,port,api_key,max_upload_bytes,workq_workers,workq_depth}`,
+      `llm_overrides.<slug>.*`. Verify by re-reading the `Load()`
+      function in `internal/config/config.go` — every `v.SetDefault`
+      call must have a corresponding key in the example YAML.
+- [ ] **Step 2** — Create the `configs/` directory if it does not
+      already exist: `mkdir -p configs`.
+- [ ] **Step 3** — Write the file with the exact content below.
+- [ ] **Step 4** — Keep the legacy `config.example.yaml` at the repo
+      root as a symlink or a pointer. Recommended: overwrite
+      `config.example.yaml` with a two-line pointer
+      (`# This file has moved to configs/docsiq.example.yaml`) so
+      existing bookmarks still resolve. Do not delete it outright —
+      that's a breaking change for anyone who linked to it.
+- [ ] **Step 5** — Self-review: every default value in the YAML
+      matches a `v.SetDefault(...)` call in `config.go`. Every env var
+      name matches the `DOCSIQ_<KEY>` replacer output (dots →
+      underscores, uppercased). Inline comments explain purpose and
+      cross-reference the struct field.
+- [ ] **Step 6** — Commit with message:
+      `docs(config): publish fully annotated example config with env-var overrides`
+
+### Exact content for configs/docsiq.example.yaml
+
+```yaml
+# docsiq example configuration
+#
+# Copy this file to one of the locations docsiq checks on startup:
+#   - ~/.docsiq/config.yaml         (global, per-user)
+#   - ./config.yaml                 (current working directory)
+#
+# Every key listed here can be overridden by an environment variable.
+# The rule is: prefix with DOCSIQ_, replace dots with underscores,
+# uppercase everything. For example:
+#   server.port                     → DOCSIQ_SERVER_PORT
+#   llm.azure.chat.endpoint         → DOCSIQ_LLM_AZURE_CHAT_ENDPOINT
+#   indexing.workers                → DOCSIQ_INDEXING_WORKERS
+#
+# Two convenience aliases exist:
+#   DOCSIQ_API_KEY                  → server.api_key
+#   DOCSIQ_SERVER_API_KEY           → server.api_key
+#
+# Fields are documented with: (default), purpose, env var.
+
+# ---------------------------------------------------------------------------
+# Storage
+# ---------------------------------------------------------------------------
+
+# Root directory for the per-project SQLite stores and notes.
+# Default: ~/.docsiq/data
+# Env:     DOCSIQ_DATA_DIR
+data_dir: ~/.docsiq/data
+
+# The project slug used when a request does not specify ?project= or
+# X-Project. Must match a slug registered via `docsiq projects register`.
+# Default: _default
+# Env:     DOCSIQ_DEFAULT_PROJECT
+default_project: _default
+
+# ---------------------------------------------------------------------------
+# LLM provider
+# ---------------------------------------------------------------------------
+
+llm:
+  # One of: azure | openai | ollama | none
+  # "none" disables all LLM-backed endpoints; notes/graph still work.
+  # Default: ollama
+  # Env:     DOCSIQ_LLM_PROVIDER
+  provider: ollama
+
+  # Azure OpenAI. Shared endpoint/api_key/api_version apply unless the
+  # chat.* or embed.* sub-blocks override them.
+  azure:
+    # Shared defaults — leave empty if you configure chat/embed separately.
+    endpoint: ""         # Env: DOCSIQ_LLM_AZURE_ENDPOINT
+    api_key: ""          # Env: DOCSIQ_LLM_AZURE_API_KEY
+    api_version: "2024-08-01"  # Env: DOCSIQ_LLM_AZURE_API_VERSION
+
+    chat:
+      endpoint: ""       # Env: DOCSIQ_LLM_AZURE_CHAT_ENDPOINT
+      api_key: ""        # Env: DOCSIQ_LLM_AZURE_CHAT_API_KEY
+      api_version: ""    # Env: DOCSIQ_LLM_AZURE_CHAT_API_VERSION
+      model: gpt-4o      # Env: DOCSIQ_LLM_AZURE_CHAT_MODEL
+
+    embed:
+      endpoint: ""       # Env: DOCSIQ_LLM_AZURE_EMBED_ENDPOINT
+      api_key: ""        # Env: DOCSIQ_LLM_AZURE_EMBED_API_KEY
+      api_version: ""    # Env: DOCSIQ_LLM_AZURE_EMBED_API_VERSION
+      model: text-embedding-3-small
+                         # Env: DOCSIQ_LLM_AZURE_EMBED_MODEL
+
+  # Direct OpenAI (api.openai.com), distinct from Azure OpenAI.
+  openai:
+    # Required when provider is "openai". Use env, not the YAML.
+    api_key: ""                         # Env: DOCSIQ_LLM_OPENAI_API_KEY
+
+    # For custom proxies or gateways; leave as default for api.openai.com.
+    base_url: https://api.openai.com/v1 # Env: DOCSIQ_LLM_OPENAI_BASE_URL
+
+    # Chat completion model.
+    chat_model: gpt-4o-mini             # Env: DOCSIQ_LLM_OPENAI_CHAT_MODEL
+
+    # Embedding model for vector search.
+    embed_model: text-embedding-3-small # Env: DOCSIQ_LLM_OPENAI_EMBED_MODEL
+
+    # Optional OpenAI-Organization header for billing routing.
+    organization: ""                    # Env: DOCSIQ_LLM_OPENAI_ORGANIZATION
+
+  # Ollama (self-hosted). Default when nothing else is configured.
+  ollama:
+    base_url: http://localhost:11434    # Env: DOCSIQ_LLM_OLLAMA_BASE_URL
+    chat_model: llama3.2                # Env: DOCSIQ_LLM_OLLAMA_CHAT_MODEL
+    embed_model: nomic-embed-text       # Env: DOCSIQ_LLM_OLLAMA_EMBED_MODEL
+
+# ---------------------------------------------------------------------------
+# Per-project LLM overrides (YAML only — env vars cannot nest like this)
+# ---------------------------------------------------------------------------
+# llm_overrides:
+#   my-project-slug:
+#     provider: openai
+#     openai:
+#       chat_model: gpt-4o
+#   another-slug:
+#     provider: ollama
+#     ollama:
+#       chat_model: mistral
+
+# ---------------------------------------------------------------------------
+# Indexing pipeline
+# ---------------------------------------------------------------------------
+
+indexing:
+  # Target size (in characters, not tokens) per chunk.
+  # Default: 512. Env: DOCSIQ_INDEXING_CHUNK_SIZE
+  chunk_size: 512
+
+  # Overlap between successive chunks, in characters.
+  # Default: 50. Env: DOCSIQ_INDEXING_CHUNK_OVERLAP
+  chunk_overlap: 50
+
+  # How many chunks to embed per LLM batch request.
+  # Default: 20. Env: DOCSIQ_INDEXING_BATCH_SIZE
+  batch_size: 20
+
+  # Parallel workers for document-level operations (load → chunk → embed).
+  # Default: 4. Env: DOCSIQ_INDEXING_WORKERS
+  workers: 4
+
+  # Run entity + relationship extraction during indexing.
+  # Set false to build vector-only index (faster, no graph queries).
+  # Default: true. Env: DOCSIQ_INDEXING_EXTRACT_GRAPH
+  extract_graph: true
+
+  # Extract covariates / claims associated with entity mentions.
+  # Default: true. Env: DOCSIQ_INDEXING_EXTRACT_CLAIMS
+  extract_claims: true
+
+  # Number of "continue extracting" passes over the same chunk. Higher
+  # values recover more entities at the cost of LLM tokens.
+  # Default: 1. Env: DOCSIQ_INDEXING_MAX_GLEANINGS
+  max_gleanings: 1
+
+# ---------------------------------------------------------------------------
+# Community detection
+# ---------------------------------------------------------------------------
+
+community:
+  # Minimum number of nodes in a detected community before it's reported.
+  # Default: 2. Env: DOCSIQ_COMMUNITY_MIN_COMMUNITY_SIZE
+  min_community_size: 2
+
+  # Depth of hierarchical Louvain clustering. Higher → more layers of
+  # nested communities, at the cost of longer indexing time.
+  # Default: 3. Env: DOCSIQ_COMMUNITY_MAX_LEVELS
+  max_levels: 3
+
+# ---------------------------------------------------------------------------
+# HTTP server (API + UI + MCP)
+# ---------------------------------------------------------------------------
+
+server:
+  # Bind address. Use 0.0.0.0 for LAN access. 127.0.0.1 binds loopback.
+  # Default: 127.0.0.1. Env: DOCSIQ_SERVER_HOST
+  host: 127.0.0.1
+
+  # Listen port.
+  # Default: 8080. Env: DOCSIQ_SERVER_PORT
+  port: 8080
+
+  # If set, every API + MCP request must carry
+  # "Authorization: Bearer <key>". Leave empty to disable.
+  # Default: "". Env: DOCSIQ_SERVER_API_KEY (alias: DOCSIQ_API_KEY)
+  api_key: ""
+
+  # Maximum upload size in bytes for POST /api/upload. 0 or negative
+  # disables the cap (not recommended).
+  # Default: 104857600 (100 MiB). Env: DOCSIQ_SERVER_MAX_UPLOAD_BYTES
+  max_upload_bytes: 104857600
+
+  # Number of background workers servicing the indexing work queue.
+  # 0 → runtime.NumCPU().
+  # Default: 0. Env: DOCSIQ_SERVER_WORKQ_WORKERS
+  workq_workers: 0
+
+  # Maximum queued jobs before /api/upload starts returning 429.
+  # Default: 64. Env: DOCSIQ_SERVER_WORKQ_DEPTH
+  workq_depth: 64
+```
+
+### Commit
+
+```bash
+git add configs/docsiq.example.yaml config.example.yaml
+git commit -m "$(cat <<'EOF'
+docs(config): publish fully annotated example config with env-var overrides
+
+Every ServerConfig, LLMConfig (Azure/OpenAI/Ollama), IndexingConfig,
+and CommunityConfig field is present with its default and the
+DOCSIQ_ env-var override. The old root-level config.example.yaml now
+points at the new location.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Success criteria
+
+- Every `v.SetDefault` call in `internal/config/config.go` is
+  represented by a key in the YAML.
+- `docsiq serve --config configs/docsiq.example.yaml` starts without
+  errors (defaults are internally consistent).
+- `DOCSIQ_SERVER_PORT=9999 docsiq serve --config configs/docsiq.example.yaml`
+  binds on :9999, proving env overrides work.
+
+---
+
+## Task 4: Write docs/quickstart.md and sample corpus (7.5)
+
+**Spec:** walks a user through indexing a small sample (`docs/samples/`)
+and running a search, top-down.
+
+**Files:**
+
+- `/home/dev/projects/docsiq/docs/quickstart.md` (new)
+- `/home/dev/projects/docsiq/docs/samples/README.md` (new)
+- `/home/dev/projects/docsiq/docs/samples/*.md` — 3-5 tiny markdown
+  files to form the corpus
+
+### Steps
+
+- [ ] **Step 1** — Create `docs/samples/`:
+      `mkdir -p /home/dev/projects/docsiq/docs/samples`.
+- [ ] **Step 2** — Author three sample documents. Keep each under 1 KB;
+      the point is a corpus small enough to index in <30 seconds on a
+      laptop, with enough entity density to produce interesting
+      graph/community output. Use the exact content for each file below.
+- [ ] **Step 3** — Add `docs/samples/README.md` explaining what the
+      samples are for and that they are suitable for screenshots + the
+      quickstart. Exact content below.
+- [ ] **Step 4** — Author the quickstart at `docs/quickstart.md`. Exact
+      content below. Cross-references:
+      (a) `configs/docsiq.example.yaml` from Task 3;
+      (b) `CONTRIBUTING.md` from Task 2 for dev setup;
+      (c) `README.md` for the badge row (to be added in Task 6).
+- [ ] **Step 5** — Verify the commands actually work end-to-end. On a
+      machine with docsiq built, run every shell block in the
+      quickstart and confirm each produces the output stated. If any
+      step does not match reality, update the quickstart — do not
+      update reality to match the quickstart.
+- [ ] **Step 6** — Self-review: the 3-minute target is real. Time
+      yourself (or a clean-vm equivalent) following the quickstart from
+      scratch. If it takes longer, trim, preconfigure more, or explain
+      the wait.
+- [ ] **Step 7** — Commit with message:
+      `docs(quickstart): add top-down quickstart with sample corpus`
+
+### Exact content for docs/samples/README.md
+
+```markdown
+# Sample corpus
+
+These tiny markdown documents exist to:
+
+1. Back the [quickstart](../quickstart.md) — a user can index this
+   directory in under 30 seconds and ask a meaningful question.
+2. Populate the screenshots in [../screenshots/](../screenshots/) with
+   realistic but non-proprietary data.
+
+The corpus is intentionally tiny. For a real workload, point `docsiq
+index` at a folder of your actual documents (PDF, DOCX, TXT, MD, or the
+output of `docsiq crawl`).
+```
+
+### Exact content for docs/samples/roman-aqueducts.md
+
+```markdown
+# Roman Aqueducts
+
+Roman aqueducts were a network of structures that supplied water to
+cities across the Roman Empire. The first, the Aqua Appia, was
+constructed in 312 BCE under the censor Appius Claudius Caecus. By the
+first century CE, eleven major aqueducts served Rome, delivering an
+estimated one million cubic metres of water per day.
+
+Gravity, not pumping, moved the water. Engineers held the gradient
+between 1:200 and 1:500 over distances exceeding a hundred kilometres,
+using arcades to bridge valleys and inverted siphons where terrain
+required pressure flow.
+
+The Pont du Gard in modern-day France is the most famous surviving
+example; the Aqua Claudia and Anio Novus, both completed in 52 CE under
+the emperor Claudius, are the longest. Maintenance was the
+responsibility of the curator aquarum — the water commissioner — an
+office held by Sextus Julius Frontinus, whose treatise *De Aquaeductu*
+remains the principal source on the subject.
+```
+
+### Exact content for docs/samples/graphrag.md
+
+```markdown
+# GraphRAG
+
+GraphRAG is a retrieval-augmented generation (RAG) technique introduced
+by Microsoft Research in 2024 that augments vector search with an
+explicit knowledge graph. Instead of retrieving only the top-k chunks
+semantically similar to a query, GraphRAG extracts entities, relations,
+and claims from each chunk, builds a graph, runs Louvain community
+detection on it, and then serves queries against either local (entity
+neighbourhood) or global (community summary) views.
+
+The key claim is that graph-derived structure recovers global context
+that pure vector search cannot: "who are the main actors in this
+corpus", "what are the dominant themes", questions that require a view
+of the whole rather than a handful of passages.
+
+docsiq is a Go implementation of this technique, shipping as a single
+binary with an embedded React UI. It supports Azure OpenAI, OpenAI, and
+Ollama as LLM providers, storing everything in SQLite with FTS5 and the
+sqlite-vec extension for ANN vector search.
+```
+
+### Exact content for docs/samples/louvain.md
+
+```markdown
+# Louvain community detection
+
+Louvain is a greedy algorithm for community detection in large networks,
+published by Blondel, Guillaume, Lambiotte, and Lefebvre in 2008. It
+optimises modularity — a scalar that rewards dense within-community
+links and sparse between-community links — through two alternating
+phases: local move (every node is considered for reassignment to the
+community that most increases modularity) and aggregation (each detected
+community becomes a super-node in the next iteration).
+
+The algorithm terminates when no move increases modularity. Runtime is
+roughly linear in the number of edges, which is why Louvain scales to
+graphs of tens of millions of nodes where spectral methods do not.
+
+GraphRAG (see graphrag.md) uses Louvain to partition its entity graph
+into nested communities. Each community gets an LLM-generated summary,
+which is what the "global" search mode retrieves.
+```
+
+### Exact content for docs/quickstart.md
+
+```markdown
+# Quickstart
+
+Go from zero to a queryable knowledge graph in under three minutes.
+
+## What you'll do
+
+1. Install the `docsiq` binary.
+2. Register the current directory as a docsiq project.
+3. Index a small sample corpus of three markdown documents.
+4. Ask a question.
+5. Open the UI and see the graph.
+
+The sample corpus lives at [`docs/samples/`](samples/); it's three
+short markdown files about Roman aqueducts, GraphRAG, and Louvain
+community detection. Small enough to index in ~30 seconds, dense enough
+to produce interesting entities and a multi-community graph.
+
+## 1. Install
+
+Download the latest release for your platform. Replace
+`docsiq-linux-amd64` with the asset name matching your OS if needed
+(macOS arm64, Windows amd64 assets are published alongside).
+
+```bash
+curl -LO https://github.com/RandomCodeSpace/docsiq/releases/latest/download/docsiq-linux-amd64
+chmod +x docsiq-linux-amd64
+mv docsiq-linux-amd64 ~/.local/bin/docsiq   # or any directory on your PATH
+```
+
+Verify:
+
+```bash
+docsiq version
+```
+
+Building from source is also supported and takes about a minute
+end-to-end; see [CONTRIBUTING.md](../CONTRIBUTING.md) for the build
+instructions.
+
+## 2. Register a project
+
+```bash
+cd ~/path/to/any/directory     # or stay in the docsiq repo for the demo
+docsiq init
+```
+
+`docsiq init` registers the current directory as a project and creates a
+scope-specific SQLite store at `~/.docsiq/data/projects/<slug>/`. If
+you're in a git repo, the slug is derived from the repo's remote origin;
+otherwise you'll be prompted for a name.
+
+## 3. Index the sample corpus
+
+From the repository root (so that `docs/samples/` resolves):
+
+```bash
+docsiq index docs/samples/
+```
+
+You will see log lines for each phase:
+
+```
+⚙️ loaded config file path=/home/you/.docsiq/config.yaml
+📄 loading documents count=3
+🧩 chunking chunks=12
+🌐 embedding batches=1
+🔗 extracting entities entities=18 relationships=24
+🧩 detecting communities levels=3 communities=5
+✅ index complete duration=21.4s
+```
+
+If you are running without an LLM configured
+(`DOCSIQ_LLM_PROVIDER=none` or `llm.provider: none` in the config),
+entity extraction and embedding steps are skipped; you'll still get a
+keyword-searchable corpus and a notes graph.
+
+## 4. Ask a question
+
+```bash
+docsiq search "Who built the first Roman aqueduct?"
+```
+
+Expected (with an LLM configured):
+
+```
+Answer: Appius Claudius Caecus built the first Roman aqueduct, the
+Aqua Appia, in 312 BCE in his role as censor.
+
+Sources:
+  roman-aqueducts.md (chunk 0)
+```
+
+For a corpus-scale question, try:
+
+```bash
+docsiq search "What are the main themes in this corpus?"
+```
+
+This triggers the global search path, which consults community
+summaries rather than individual chunks.
+
+## 5. Open the UI
+
+```bash
+docsiq serve
+# → http://localhost:8080
+```
+
+Navigate to `http://localhost:8080`. You should see:
+
+- **Home** — project picker, recent indexing activity.
+- **Notes** — wikilinked markdown, even without any LLM configured.
+- **Documents** — the three sample files with chunk counts.
+- **Graph** — force-directed entity/community visualisation.
+- **MCP** — inspector-style console for the 12+ MCP tools docsiq
+  exposes at `/mcp`.
+
+Screenshots of each view are in [`docs/screenshots/`](screenshots/).
+
+## Where to next
+
+- **Configure an LLM** — see [`configs/docsiq.example.yaml`](../configs/docsiq.example.yaml)
+  for every option, default, and env-var override.
+- **Integrate with Claude Desktop / Cursor** — run
+  `docsiq hooks install --client claude-desktop`.
+- **Index a real corpus** — `docsiq index /path/to/your/docs` accepts
+  PDF, DOCX, TXT, and Markdown. Web pages can be fetched with
+  `docsiq crawl <url>`.
+- **Read the architecture overview** — [README.md](../README.md#architecture).
+- **Contribute** — [CONTRIBUTING.md](../CONTRIBUTING.md).
+```
+
+### Commit
+
+```bash
+git add docs/quickstart.md docs/samples/
+git commit -m "$(cat <<'EOF'
+docs(quickstart): add top-down quickstart with sample corpus
+
+docs/quickstart.md walks a new user from zero-install to first search
+in five numbered steps. docs/samples/ ships a 3-document markdown
+corpus (aqueducts, graphrag, louvain) that indexes in <30s and
+produces a non-trivial entity graph for screenshots.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Success criteria
+
+- A user on a fresh machine can follow the quickstart from scratch and
+  have a queryable index in under 3 minutes (assuming Ollama is
+  already installed with the default models, or an OpenAI key is
+  exported).
+- `docs/samples/` contains the three `.md` files and a README.
+- No internal links in `docs/quickstart.md` are broken (every relative
+  path resolves).
+
+---
+
+## Task 5: Capture and commit the screenshot gallery (7.6)
+
+**Spec:** `docs/screenshots/` with fresh captures of Home, Notes,
+Documents, Graph, MCP. Referenced from README.
+
+**Files:**
+
+- `/home/dev/projects/docsiq/ui/e2e/screenshots.spec.ts` (new)
+- `/home/dev/projects/docsiq/ui/scripts/optimize-screenshots.mjs` (new)
+- `/home/dev/projects/docsiq/docs/screenshots/home.png` (new)
+- `/home/dev/projects/docsiq/docs/screenshots/notes.png` (new)
+- `/home/dev/projects/docsiq/docs/screenshots/documents.png` (new)
+- `/home/dev/projects/docsiq/docs/screenshots/graph.png` (new)
+- `/home/dev/projects/docsiq/docs/screenshots/mcp.png` (new)
+
+### Investigation note
+
+Screenshots cannot be generated from within this plan file — they
+require a running UI against a populated store. This task is therefore
+an *investigative / procedural* task with concrete success criteria
+(5 PNGs committed, each < 500 KB, referenced from README). The executor
+runs the procedure end-to-end on their machine.
+
+### Steps
+
+- [ ] **Step 1** — Create the output directory:
+      `mkdir -p docs/screenshots`.
+- [ ] **Step 2** — Verify Playwright is already a UI dev dep. If not,
+      install it with `npm --prefix ui install -D @playwright/test`
+      and commit `ui/package.json` + `ui/package-lock.json` as part of
+      this task.
+- [ ] **Step 3** — Verify `sharp` is a UI dev dep (per the plan
+      assumption). If not, add it with
+      `npm --prefix ui install -D sharp`.
+- [ ] **Step 4** — Author `ui/e2e/screenshots.spec.ts` — content below.
+- [ ] **Step 5** — Author `ui/scripts/optimize-screenshots.mjs` —
+      content below.
+- [ ] **Step 6** — Prepare the fixture data directory. In a shell:
+
+      ```bash
+      FIX=/tmp/docsiq-screenshots-fixture
+      rm -rf "$FIX" && mkdir -p "$FIX"
+      DOCSIQ_DATA_DIR="$FIX" ./docsiq init --name screenshots-demo
+      DOCSIQ_DATA_DIR="$FIX" ./docsiq index docs/samples/
+      ```
+
+      The fixture does not need an LLM if you're just checking layout;
+      with an LLM configured you get real community summaries and graph
+      edges, which is what we want for screenshots.
+- [ ] **Step 7** — Boot the server against the fixture:
+
+      ```bash
+      DOCSIQ_DATA_DIR="$FIX" ./docsiq serve --port 37778 &
+      SERVE_PID=$!
+      ```
+
+      Wait ~1s for it to bind, then verify `curl -s localhost:37778/api/health`
+      returns 200.
+- [ ] **Step 8** — Run the Playwright script:
+
+      ```bash
+      BASE_URL=http://localhost:37778 \
+        npx --prefix ui playwright test ui/e2e/screenshots.spec.ts
+      ```
+
+      This produces 5 raw PNGs in `docs/screenshots/`.
+- [ ] **Step 9** — Kill the server: `kill $SERVE_PID`.
+- [ ] **Step 10** — Optimize the PNGs through sharp:
+
+      ```bash
+      node ui/scripts/optimize-screenshots.mjs
+      ```
+
+      Confirm each PNG is < 500 KB after optimization:
+
+      ```bash
+      ls -lh docs/screenshots/*.png
+      ```
+- [ ] **Step 11** — Visually review each PNG. Reject any with:
+      - Placeholder or "no data" empty states (the fixture corpus
+        should produce data on every screen).
+      - Debug toolbars, React Query devtools, or console-open state
+        visible.
+      - Personal data leakage (no usernames, no emails, no paths that
+        include the executor's home directory).
+- [ ] **Step 12** — Commit with message:
+      `docs(screenshots): capture home, notes, documents, graph, and mcp`.
+      Include the test spec and optimizer script in the same commit —
+      future recaptures should be reproducible by anyone.
+
+### Exact content for ui/e2e/screenshots.spec.ts
+
+```typescript
+// Capture the five canonical docsiq screenshots used in the README and
+// docs/screenshots/. Runs against a live server on $BASE_URL (default
+// http://localhost:37778) seeded with the docs/samples/ fixture corpus.
+//
+// Usage:
+//   DOCSIQ_DATA_DIR=/tmp/fixture ./docsiq serve --port 37778 &
+//   BASE_URL=http://localhost:37778 \
+//     npx playwright test ui/e2e/screenshots.spec.ts
+
+import { test, expect } from "@playwright/test";
+import path from "node:path";
+
+const BASE_URL = process.env.BASE_URL ?? "http://localhost:37778";
+const OUT_DIR = path.resolve(__dirname, "..", "..", "docs", "screenshots");
+
+// Desktop viewport. Matches the typical reviewer's Retina display;
+// the sharp script downscales as needed.
+test.use({
+  viewport: { width: 1440, height: 900 },
+  deviceScaleFactor: 2,
+  colorScheme: "dark", // dark theme is the default in the app
+});
+
+async function settle(page: import("@playwright/test").Page) {
+  // Wait for network idle + a small buffer for any d3 transitions.
+  await page.waitForLoadState("networkidle");
+  await page.waitForTimeout(500);
+}
+
+test("home", async ({ page }) => {
+  await page.goto(`${BASE_URL}/`);
+  await settle(page);
+  await page.screenshot({
+    path: path.join(OUT_DIR, "home.png"),
+    fullPage: true,
+  });
+});
+
+test("notes", async ({ page }) => {
+  await page.goto(`${BASE_URL}/notes`);
+  await settle(page);
+  await page.screenshot({
+    path: path.join(OUT_DIR, "notes.png"),
+    fullPage: true,
+  });
+});
+
+test("documents", async ({ page }) => {
+  await page.goto(`${BASE_URL}/documents`);
+  await settle(page);
+  await page.screenshot({
+    path: path.join(OUT_DIR, "documents.png"),
+    fullPage: true,
+  });
+});
+
+test("graph", async ({ page }) => {
+  await page.goto(`${BASE_URL}/graph`);
+  await settle(page);
+  // Graph has an SVG force simulation — give it a bit longer to settle.
+  await page.waitForTimeout(2000);
+  await page.screenshot({
+    path: path.join(OUT_DIR, "graph.png"),
+    fullPage: true,
+  });
+});
+
+test("mcp", async ({ page }) => {
+  await page.goto(`${BASE_URL}/mcp`);
+  await settle(page);
+  await page.screenshot({
+    path: path.join(OUT_DIR, "mcp.png"),
+    fullPage: true,
+  });
+});
+```
+
+### Exact content for ui/scripts/optimize-screenshots.mjs
+
+```javascript
+// Optimise docs/screenshots/*.png in place via sharp.
+//
+// Targets:
+//   - Keep pixel dimensions (don't downscale — we use @2x captures).
+//   - Re-encode PNG with compression level 9 and palette where possible.
+//   - Refuse to exit 0 if any resulting file is > 500 KB — that's our
+//     published budget per screenshot.
+//
+// Usage:  node ui/scripts/optimize-screenshots.mjs
+
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import sharp from "sharp";
+
+const DIR = path.resolve(
+  path.dirname(new URL(import.meta.url).pathname),
+  "..",
+  "..",
+  "docs",
+  "screenshots",
+);
+const BUDGET_BYTES = 500 * 1024;
+
+const entries = (await readdir(DIR)).filter((f) => f.endsWith(".png"));
+if (entries.length === 0) {
+  console.error("no PNGs found in", DIR);
+  process.exit(1);
+}
+
+let failed = false;
+for (const name of entries) {
+  const p = path.join(DIR, name);
+  const before = (await stat(p)).size;
+  const buf = await sharp(p)
+    .png({ compressionLevel: 9, palette: true, effort: 10 })
+    .toBuffer();
+  await sharp(buf).toFile(p);
+  const after = (await stat(p)).size;
+  const flag = after > BUDGET_BYTES ? "OVER BUDGET" : "ok";
+  console.log(
+    `${name.padEnd(18)}  ${Math.round(before / 1024)} KB → ${Math.round(after / 1024)} KB  [${flag}]`,
+  );
+  if (after > BUDGET_BYTES) failed = true;
+}
+
+process.exit(failed ? 2 : 0);
+```
+
+### Commit
+
+```bash
+git add ui/e2e/screenshots.spec.ts \
+        ui/scripts/optimize-screenshots.mjs \
+        docs/screenshots/
+git commit -m "$(cat <<'EOF'
+docs(screenshots): capture home, notes, documents, graph, and mcp
+
+Five fresh @2x PNGs of the embedded SPA against the docs/samples/
+fixture corpus. Reproducible via ui/e2e/screenshots.spec.ts and
+ui/scripts/optimize-screenshots.mjs; each output is compressed below
+the 500 KB per-image budget.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Success criteria
+
+- Five PNGs exist under `docs/screenshots/`:
+  `home.png`, `notes.png`, `documents.png`, `graph.png`, `mcp.png`.
+- Each is < 500 KB.
+- Each shows real fixture data, not an empty state.
+- No personal paths, tokens, or secrets visible in any screenshot.
+- The screenshot spec and optimizer script are committed alongside the
+  PNGs so future recaptures are reproducible.
+
+### Fallback
+
+If Playwright cannot run headlessly in the executor's environment,
+capture the screenshots manually using Chrome DevTools' "Capture full
+size screenshot" command against a running server, then still run them
+through the sharp optimizer. Document the manual path in the commit
+message so the next recapture knows which mode was used.
+
+---
+
+## Task 6: Add the badge row (7.7)
+
+**Spec:** README top: CodeQL, OpenSSF Best Practices (already earned),
+build, coverage, license, Go Report Card.
+
+**File:** `/home/dev/projects/docsiq/README.md` (patch, lines 1-10)
+
+### Steps
+
+- [ ] **Step 1** — Confirm the current badges in README (lines 3-7 per
+      the snapshot used to write this plan):
+      - Security Scan (CI)
+      - OpenSSF Best Practices — keep the exact URL
+        (`https://www.bestpractices.dev/projects/12628/badge`)
+      - OpenSSF Scorecard
+      - Release
+      - Go Version
+- [ ] **Step 2** — Confirm CodeQL workflow exists at
+      `.github/workflows/codeql.yml`. The badge URL is
+      `https://github.com/RandomCodeSpace/docsiq/actions/workflows/codeql.yml/badge.svg`.
+- [ ] **Step 3** — Confirm Codecov status. Run `grep -r codecov
+      .github/workflows/` — if codecov is uploaded, the badge is
+      `https://codecov.io/gh/RandomCodeSpace/docsiq/branch/main/graph/badge.svg`.
+      If not configured, defer coverage badge and add a follow-up note
+      in the PR description.
+- [ ] **Step 4** — The full post-Task 6 badge row replaces lines 3-7
+      of the existing README. Exact content below.
+- [ ] **Step 5** — Use the `Edit` tool with the exact
+      find-and-replace pair below — do not rewrite the whole README in
+      this task (that happens in Task 7).
+- [ ] **Step 6** — Self-review: open the README on GitHub (preview
+      mode locally via `gh browse -- README.md` after push, or a local
+      markdown renderer). Every badge must render, every link must
+      resolve.
+- [ ] **Step 7** — Commit with message:
+      `docs(readme): add CodeQL, license, Go report card, and coverage badges`
+
+### Find in README.md (the existing badge block)
+
+```
+[![Security Scan](https://github.com/RandomCodeSpace/docsiq/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RandomCodeSpace/docsiq/actions/workflows/ci.yml)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12628/badge)](https://www.bestpractices.dev/projects/12628)
+[![OpenSSF Score](https://api.scorecard.dev/projects/github.com/RandomCodeSpace/docsiq/badge)](https://scorecard.dev/viewer/?uri=github.com/RandomCodeSpace/docsiq)
+[![Release](https://img.shields.io/github/v/release/RandomCodeSpace/docsiq?include_prereleases&sort=semver)](https://github.com/RandomCodeSpace/docsiq/releases)
+[![Go Version](https://img.shields.io/github/go-mod/go-version/RandomCodeSpace/docsiq)](https://github.com/RandomCodeSpace/docsiq/blob/main/go.mod)
+```
+
+### Replace with
+
+```
+[![CI](https://github.com/RandomCodeSpace/docsiq/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RandomCodeSpace/docsiq/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/RandomCodeSpace/docsiq/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/RandomCodeSpace/docsiq/actions/workflows/codeql.yml)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12628/badge)](https://www.bestpractices.dev/projects/12628)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/RandomCodeSpace/docsiq/badge)](https://scorecard.dev/viewer/?uri=github.com/RandomCodeSpace/docsiq)
+[![Go Report Card](https://goreportcard.com/badge/github.com/RandomCodeSpace/docsiq)](https://goreportcard.com/report/github.com/RandomCodeSpace/docsiq)
+[![License: MIT](https://img.shields.io/github/license/RandomCodeSpace/docsiq)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/RandomCodeSpace/docsiq?include_prereleases&sort=semver)](https://github.com/RandomCodeSpace/docsiq/releases)
+[![Go Version](https://img.shields.io/github/go-mod/go-version/RandomCodeSpace/docsiq)](https://github.com/RandomCodeSpace/docsiq/blob/main/go.mod)
+```
+
+If Step 3 confirmed Codecov is configured, also insert this badge
+between CodeQL and OpenSSF Best Practices:
+
+```
+[![Coverage](https://codecov.io/gh/RandomCodeSpace/docsiq/branch/main/graph/badge.svg)](https://codecov.io/gh/RandomCodeSpace/docsiq)
+```
+
+### Commit
+
+```bash
+git add README.md
+git commit -m "$(cat <<'EOF'
+docs(readme): add CodeQL, license, Go report card, and coverage badges
+
+Extends the existing OpenSSF + Scorecard badge row with CodeQL
+(now running on every PR), an explicit MIT license badge, and a Go
+Report Card link. Coverage badge included only if Codecov is wired;
+otherwise tracked as follow-up.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Success criteria
+
+- README's badge row renders with every badge present and green.
+- No broken badge URLs (each returns a 200 with a valid SVG).
+- Badge ordering is stable and readable: status signals (CI, CodeQL)
+  first; community signals (OpenSSF) next; project metadata (Go
+  Report, License, Release, Go Version) last.
+
+---
+
+## Task 7: Refactor README first screen (7.1)
+
+**Spec:** first screen is (i) one-line description, (ii) single-command
+install from a release binary, (iii) single-command first-index on a
+sample corpus. Target: user indexes and queries in under 3 minutes.
+Screenshots of Home and Graph inline.
+
+**File:** `/home/dev/projects/docsiq/README.md` (overwrite)
+
+### Steps
+
+- [ ] **Step 1** — Re-read the current README end to end (you should
+      have it cached from Task 6). Identify content that must survive:
+      - The architecture tree (lines 100-122 of the current version).
+      - The UI section (Keyboard shortcuts table, PWA note).
+      - The MCP section and `docsiq hooks install` example.
+      - The "No LLM?" note about `provider: none`.
+      - The LICENSE reference.
+- [ ] **Step 2** — Verify the release asset URL shape. Run
+      `gh release list -R RandomCodeSpace/docsiq -L 1`
+      then `gh release view <tag> -R RandomCodeSpace/docsiq
+      --json assets --jq '.assets[].name'`
+      to get the actual asset names. If the file is
+      `docsiq-linux-amd64`, use that verbatim. If it is
+      `docsiq_linux_amd64.tar.gz` or similar, adjust the install
+      snippet to match (download, extract, chmod, move).
+- [ ] **Step 3** — Overwrite the entire README with the content below.
+      **Do not lose any information captured in Step 1**; the new
+      README integrates it all in a rearranged order, with the
+      "three-command onboarding" promoted above everything else.
+- [ ] **Step 4** — Validate every link. In the new README:
+      - `CONTRIBUTING.md` → Task 2 output.
+      - `SECURITY.md` → Task 1 output.
+      - `docs/quickstart.md` → Task 4 output.
+      - `configs/docsiq.example.yaml` → Task 3 output.
+      - `docs/screenshots/{home,graph}.png` → Task 5 output.
+      - `LICENSE` → existing.
+      - `CODE_OF_CONDUCT.md` → existing.
+- [ ] **Step 5** — Self-review: read the whole diff. Confirm the first
+      screen (top 40 lines) hits the three-bullet target:
+      one-line description, single install command, single first-index
+      command. The 3-minute claim must be defensible given what the
+      quickstart says.
+- [ ] **Step 6** — Commit with message:
+      `docs(readme): refactor first screen for 3-minute onboarding`
+
+### Exact content for README.md
+
+```markdown
+# docsiq
+
+[![CI](https://github.com/RandomCodeSpace/docsiq/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/RandomCodeSpace/docsiq/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/RandomCodeSpace/docsiq/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/RandomCodeSpace/docsiq/actions/workflows/codeql.yml)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12628/badge)](https://www.bestpractices.dev/projects/12628)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/RandomCodeSpace/docsiq/badge)](https://scorecard.dev/viewer/?uri=github.com/RandomCodeSpace/docsiq)
+[![Go Report Card](https://goreportcard.com/badge/github.com/RandomCodeSpace/docsiq)](https://goreportcard.com/report/github.com/RandomCodeSpace/docsiq)
+[![License: MIT](https://img.shields.io/github/license/RandomCodeSpace/docsiq)](LICENSE)
+[![Release](https://img.shields.io/github/v/release/RandomCodeSpace/docsiq?include_prereleases&sort=semver)](https://github.com/RandomCodeSpace/docsiq/releases)
+[![Go Version](https://img.shields.io/github/go-mod/go-version/RandomCodeSpace/docsiq)](https://github.com/RandomCodeSpace/docsiq/blob/main/go.mod)
+
+**A single-binary GraphRAG knowledge base — index documents, extract an
+entity graph, ask questions across it, and browse the result in an
+embedded React UI over MCP.**
+
+## Three-minute onboarding
+
+```bash
+# 1. Install (Linux amd64 shown; macOS arm64 + Windows amd64 are published alongside)
+curl -LO https://github.com/RandomCodeSpace/docsiq/releases/latest/download/docsiq-linux-amd64
+chmod +x docsiq-linux-amd64 && sudo mv docsiq-linux-amd64 /usr/local/bin/docsiq
+
+# 2. Index the sample corpus
+git clone https://github.com/RandomCodeSpace/docsiq && cd docsiq
+docsiq init && docsiq index docs/samples/
+
+# 3. Ask a question
+docsiq search "What are the main themes in this corpus?"
+```
+
+For a UI session:
+
+```bash
+docsiq serve
+# → http://localhost:8080
+```
+
+Full walk-through with expected output: [docs/quickstart.md](docs/quickstart.md).
+
+## Screenshots
+
+| Home | Graph |
+|---|---|
+| ![Home view](docs/screenshots/home.png) | ![Graph view](docs/screenshots/graph.png) |
+
+More: [Notes](docs/screenshots/notes.png) ·
+[Documents](docs/screenshots/documents.png) ·
+[MCP Console](docs/screenshots/mcp.png).
+
+## What it does
+
+docsiq is a GraphRAG-powered knowledge base that runs as a single Go
+binary. It ingests unstructured documents, builds a knowledge graph
+with community detection, persists wikilinked markdown notes, and
+exposes the whole thing over **MCP + an embedded React SPA** on one
+port.
+
+Inspired by [Microsoft GraphRAG](https://github.com/microsoft/graphrag);
+storage is CGO-backed SQLite (`mattn/go-sqlite3` with FTS5) + the
+[`sqlite-vec`](https://github.com/asg017/sqlite-vec) extension for ANN
+vector search.
+
+## Features
+
+- **GraphRAG pipeline** — load → chunk → embed → extract entities /
+  relationships / claims → detect communities, all in one
+  `docsiq index` run.
+- **Notes subsystem** — markdown on disk with `[[wikilinks]]`, project
+  scopes, cross-project references, and a live note graph view. Works
+  without any LLM configured.
+- **Interactive graph** — SVG force-directed viz with d3-zoom
+  (pinch/wheel pan/zoom 0.1×–40×), hover-to-highlight neighbourhood,
+  degree-scaled nodes.
+- **Community detection** — pure-Go Louvain, hierarchical, no external
+  deps.
+- **Three LLM providers** — Azure OpenAI, OpenAI, Ollama — via
+  [`tmc/langchaingo`](https://github.com/tmc/langchaingo). Set
+  `provider: "none"` to run the server in notes-only mode with no LLM.
+- **MCP server** — 12+ tools (local/global search, graph walk,
+  community reports, note read/write, …) exposed at `/mcp` via
+  Streamable HTTP transport with session handshake.
+- **Embedded SPA** — React 19 + Tailwind 4 + shadcn/ui, served from
+  `//go:embed ui/dist`. PWA-installable with manifest + service worker.
+- **Per-repo projects** — each scope has its own SQLite store + notes
+  directory, addressable by slug.
+
+## UI
+
+- **Stack**: React 19, Vite 6, Tailwind 4, shadcn/ui primitives, Geist
+  typography, Lucide icons.
+- **Architecture**: CSS lives in a single `globals.css` with an
+  `@layer components` section; JSX uses semantic class names only;
+  shadcn primitives are the only place Tailwind utilities live inline.
+- **Navigation**: labelled sidebar (Home · Notes · Documents · Graph ·
+  MCP) with ⌘K command palette.
+- **Responsiveness**: mobile drawer via shadcn `Sheet`; iOS safe-area
+  respected; inputs forced to 16px below `sm:` to kill Safari auto-zoom.
+- **PWA**: manifest + 192/512 PNG icons + minimal service worker,
+  installable on Android/iOS.
+- **Hard reload**: refresh button in the header purges service worker +
+  CacheStorage and reloads from network — mobile-friendly `⌘⇧R` substitute.
+
+### Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `⌘K` / `Ctrl+K` | Command palette |
+| `G H` | Home |
+| `G N` | Notes |
+| `G D` | Documents |
+| `G G` | Graph |
+| `G M` | MCP console |
+| `⌘/` | Toggle tree drawer (Notes) |
+| `⌘L` | Toggle links drawer (Notes) |
+
+## MCP
+
+docsiq speaks the MCP Streamable HTTP transport at `POST /mcp`. The
+UI's MCP Console (inspector-style) gives you the same tool list with
+typed argument forms. For external clients (Claude Desktop, Cursor,
+etc.) register the server URL directly, or use the hooks helper:
+
+```bash
+docsiq hooks install --client claude-desktop
+```
+
+## Architecture
+
+```
+cmd/            CLI commands (cobra): index, serve, search, projects, init, hooks, vec
+internal/
+  api/          REST API + /mcp handler
+  chunker/      Text splitting (textsplitter.RecursiveCharacter)
+  community/    Louvain detection + summaries
+  config/       Viper YAML config + env override
+  crawler/      Web page crawler
+  embedder/     Batched text → vector (nil-safe when provider=none)
+  extractor/    LLM-based entity / relationship / claim extraction
+  llm/          Provider abstraction (Azure, OpenAI, Ollama, none)
+  loader/       Document loaders (PDF, DOCX, TXT, MD, web)
+  mcp/          Streamable HTTP MCP server (12+ tools)
+  notes/        Per-project markdown + wikilinks + graph builder
+  pipeline/     5-phase indexing pipeline
+  project/      Project registry (git-remote-scoped slugs)
+  search/       Query engine (local + global + hybrid)
+  store/        SQLite + FTS5 + vector index
+  vectorindex/  HNSW ANN vector search
+ui/             React 19 + Vite 6 SPA, embedded at compile time
+```
+
+## Configuration
+
+Config lives at `~/.docsiq/config.yaml`; every key can be overridden by
+an env var with prefix `DOCSIQ_` (dots → underscores, uppercased). A
+fully annotated reference with every option, default, and env var is at
+[`configs/docsiq.example.yaml`](configs/docsiq.example.yaml).
+
+```yaml
+server:
+  host: 0.0.0.0
+  port: 37778
+  api_key: ""          # if set, UI + API require Authorization: Bearer <key>
+
+llm:
+  provider: ollama     # azure | openai | ollama | none
+  ollama:
+    base_url: http://localhost:11434
+    chat_model: llama3.2
+    embed_model: nomic-embed-text
+```
+
+**No LLM?** Set `provider: none`. The server still runs notes,
+wikilinks, graph, tree, and notes-search. Endpoints that need the
+model (`POST /api/search`, `POST /api/upload`, `/mcp` tool calls that
+embed or extract) return `503 {"code": "llm_disabled"}`.
+
+## Build from source
+
+```bash
+# First time on a connected machine
+npm --prefix ui ci                          # install UI deps
+go mod download                             # Go deps
+
+# Build
+npm --prefix ui run build                   # produces ui/dist/
+CGO_ENABLED=1 go build -tags sqlite_fts5 -o docsiq ./
+```
+
+CI builds UI first and passes `ui/dist/` to each Go job as an artifact.
+`ui/dist/` is **not committed**; only a tiny placeholder `ui/dist/index.html`
+exists in the repo to keep `//go:embed ui/dist` happy at compile time.
+
+## Tests
+
+```bash
+# Go
+CGO_ENABLED=1 go test -tags sqlite_fts5 ./...
+# Go -race integration
+CGO_ENABLED=1 go test -tags "sqlite_fts5 integration" -race -timeout 1200s ./...
+
+# UI
+npm --prefix ui run typecheck
+npm --prefix ui test -- --run --coverage
+npm --prefix ui run build
+```
+
+## Community
+
+- **Contributing** — [CONTRIBUTING.md](CONTRIBUTING.md) for local dev
+  loop, test commands, and commit style.
+- **Security** — [SECURITY.md](SECURITY.md) for the disclosure policy
+  and fix SLA.
+- **Code of conduct** — [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+- **Governance** — [GOVERNANCE.md](GOVERNANCE.md).
+- **Changelog** — [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+```
+
+### Commit
+
+```bash
+git add README.md
+git commit -m "$(cat <<'EOF'
+docs(readme): refactor first screen for 3-minute onboarding
+
+Promotes a three-command onboarding block (install, index, query) to
+the first screen, inlines Home/Graph screenshots, and links
+downstream docs (quickstart, example config, CONTRIBUTING, SECURITY)
+into a single Community section. No content lost — architecture, UI,
+MCP, build, and tests sections are preserved verbatim.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+### Success criteria
+
+- First screen (top 40 lines) hits the three targets verbatim: one-line
+  description, single install command, single index command.
+- Home and Graph screenshots render inline (not as links).
+- Every outbound link resolves: `CONTRIBUTING.md`, `SECURITY.md`,
+  `docs/quickstart.md`, `configs/docsiq.example.yaml`, all five
+  screenshots, `CODE_OF_CONDUCT.md`, `GOVERNANCE.md`, `CHANGELOG.md`,
+  `LICENSE`.
+- The architecture tree, UI description, MCP section, and configuration
+  block from the previous README are preserved (no content deletion,
+  only reordering).
+- Badge row matches Task 6's output.
+
+---
+
+## Block-level Self-Review
+
+Before declaring Block 7 complete, run through this checklist. Every
+item is scoped to what this block produced; do not borrow failures from
+other blocks.
+
+### Content audit
+
+- [ ] README first screen can be read on a phone-sized viewport without
+      scrolling past the install/index commands.
+- [ ] Every `.md` file created in this block renders cleanly in the
+      GitHub markdown viewer (preview with `gh browse`).
+- [ ] Every fenced code block is syntactically valid for its language
+      tag (bash, yaml, typescript, javascript, markdown).
+- [ ] No broken internal links. Run
+      `grep -rhoE '\]\([^)]+\)' README.md CONTRIBUTING.md SECURITY.md docs/*.md docs/samples/*.md`
+      and eyeball each target.
+- [ ] `configs/docsiq.example.yaml` matches `internal/config/config.go`
+      field-for-field. Run `grep 'v.SetDefault' internal/config/config.go`
+      and confirm every key is present in the YAML.
+
+### Execution audit
+
+- [ ] `docsiq serve --config configs/docsiq.example.yaml` starts
+      without errors.
+- [ ] A user following `docs/quickstart.md` verbatim hits a queryable
+      state in under 3 minutes on a reference machine (no LLM
+      configuration required; Ollama must be running locally or
+      `provider: none` used).
+- [ ] All five screenshots are under 500 KB and show real data.
+- [ ] `ui/e2e/screenshots.spec.ts` and
+      `ui/scripts/optimize-screenshots.mjs` are syntactically valid
+      (`npx tsc --noEmit` and `node --check` pass).
+
+### OSS hygiene audit
+
+- [ ] Badge row on README renders without any broken badges.
+- [ ] `SECURITY.md` advisory URL is reachable.
+- [ ] `CONTRIBUTING.md` build commands work on a fresh clone.
+- [ ] No secrets, tokens, personal paths, or email addresses
+      committed in any file, including the screenshots.
+
+### Commit audit
+
+- [ ] Exactly seven commits, one per task.
+- [ ] Each commit's subject line follows Conventional Commits and fits
+      in 72 chars.
+- [ ] Each commit has the `Co-Authored-By: Claude Opus 4.7 (1M context)
+      <noreply@anthropic.com>` trailer.
+- [ ] No commit touches files outside the list declared in that task.
+
+## Execution Handoff
+
+When executing this plan:
+
+1. **Invoke `superpowers:executing-plans`** — the skill is required at
+   the top of this document. It will read these tasks one at a time,
+   enforce the "read full diff before declaring done" rule, and gate
+   each commit on the listed success criteria.
+2. **Run tasks in order** (1 → 7). They are ordered by dependency
+   fan-in. Do not parallelize — Task 7 reads the screenshots and badges
+   produced by Tasks 5 and 6.
+3. **Do not batch commits.** Each task ends with its own commit. If a
+   hook fails, fix and create a *new* commit — do not `--amend`.
+4. **Do not push.** A controller batches Block 7 with any remaining
+   work from adjacent blocks.
+5. **If a step reveals a hidden constraint** (e.g., release binary is
+   actually `.tar.gz`, or Codecov is not wired) — pause, update the
+   relevant task's snippet, note the change under a `## Deviations`
+   heading at the bottom of this plan, and continue. Do not silently
+   adapt.
+
+### Expected final state
+
+```
+# Files created
+configs/docsiq.example.yaml
+docs/quickstart.md
+docs/samples/README.md
+docs/samples/roman-aqueducts.md
+docs/samples/graphrag.md
+docs/samples/louvain.md
+docs/screenshots/home.png
+docs/screenshots/notes.png
+docs/screenshots/documents.png
+docs/screenshots/graph.png
+docs/screenshots/mcp.png
+ui/e2e/screenshots.spec.ts
+ui/scripts/optimize-screenshots.mjs
+
+# Files overwritten
+README.md
+CONTRIBUTING.md
+SECURITY.md
+config.example.yaml   (now a two-line pointer to configs/docsiq.example.yaml)
+```
+
+Seven commits. Block 7 complete.