# THREADS.md

Everything that is **not yet locked**: open questions, in-flight work, parked ideas, and the reasoning behind each.

A thread lives here while it is being decided. Once it is settled and built, the outcome moves into `PROJECT.md`, `ARCHITECTURE.md`, or `CLAUDE.md`, and the thread moves to §5.

*Last updated: 2026-09-08.*

## Where things stand

| Thread | State |
|--------|-------|
| **T-12** Retention drops data with no export | ⚠️ **Decision needed.** First run deleted `agent_executions` 2026-03…06. |
| **T-13** Agents other than the Conversational Agent cannot run | ⚠️ Decision needed. No platform key, and only the Conversational Agent has key fields. |
| **T-02** Query template parameterization | 🔨 Open. Nine items, QTP-01…09, none started. |
| **T-03** Widget build, hashing, cache busting | 🔨 Open. More urgent now the widget carries an inlined font. |
| **T-04** Makefiles and dockerisation | ✅ Landed (PR #17). Four smaller items still open. |
| **T-05** Test infrastructure | 🔨 Open. Rules agreed, no runner stood up. |
| **T-06** CI | 🔨 Open. Blocked on T-05. |
| **T-07** README and COSTING corrections | 🔨 Open. |
| **T-08** `db-schema-i3.md` is unreadable | 🔨 Open. |
| **T-09** 27 eslint warnings | 🔨 Open. Errors are at zero (PR #18); warnings untouched. |
| **T-14** Own-key and rate-limit follow-ups | 🔨 Open. Production still needs the new embedding worker deployed; the rest are small. |

Shipped on 2026-09-08: the four project documents, `.gitignore` env hardening, dockerisation, the root `Makefile`, the font migration (PR #17), the eslint error cleanup (PR #18), and the Storage editor / Analytics search / skeletons work (PR #19). Detail in §5.

T-01 (partitions) was fixed live on 2026-09-09 by migration `0037`; own LLM keys and rate limiting landed 2026-10-11 (`0038`). Both are in §5.

---

## 1. Decisions locked on 2026-09-08

Recorded so they are not re-litigated.

| Decision | Outcome |
|----------|---------|
| Is `README.md` accurate? | **No.** `PROJECT.md` is the source of truth. `README.md` will be narrowed to a short public overview. |
| Vercel + Render, or DigitalOcean? | **DigitalOcean App Platform.** Vercel + Render was planning only and is dropped. |
| Who deploys? | **DevOps.** Our work ends at the merge into `main`. We do not deploy, configure hosting, or run release infrastructure. |
| Where does the widget live? | **Stays in `apps/web/public/`.** No separate CDN or deployment. But it must gain a real build with content hashing and cache busting. |
| Testing scope | **All five rules adopted** — see `CLAUDE.md` §9. |
| `docs/cursor-history/` | **Deleted** (173 files, 18 MB, untracked). |
| Migration naming | **`NNNN-YYYY-MM-DD-description.sql`, starting at `0035`.** Legacy 34 keep their names; true order recorded in `ARCHITECTURE.md` §6. |
| Supabase CLI | **Repo linked** to project `Agent Engine` (`xbkcqtqrgrnbepunsayc`). |
| `AGENTS.md` | Rules consolidated into `CLAUDE.md`; `AGENTS.md` becomes a pointer. |
| App font | **Plus Jakarta Sans**, self-hosted through `next/font/local`, set on `<body>` as the app-wide default. `next/font/google` is banned — see `CLAUDE.md` §6. |
| Widget font delivery | **Inlined into the widget as base64 woff2**, not served by URL from our origin. Removes a second request on a customer's page and a CORS header whose deletion would fail silently. |
| Widget font registration | **`document.fonts.add(new FontFace(...))`**, never an injected `@font-face`. Font faces are document-scoped; a rule inside a shadow root is ignored silently. |
| `make help` presentation | **The self-documenting `##` pattern**, matching the Rancho project: the list is generated by grep+awk from each target's own comment, so it cannot drift. |

---

## 2. Active threads

### T-12 — Retention drops data with no export ⚠️ *decision needed*

**What we know.** The pg_cron jobs `archive-executions` (90 days) and `archive-messages` (365 days) were scheduled before anyone wrote `archive_old_partitions`, and failed every month until `0037` created it. The spec (`db-schema-i3.md`, `sql-queries.md` §7) says "drop partitions older than N days", and that is what the function does — nothing is exported first.

**What happened.** First successful run, 2026-10-01 02:00 UTC: `agent_executions_2026_03…06` dropped (the table had rows up to 2026-06-22). `messages` lost nothing — its 365-day horizon is 2027-03. Verified in `cron.job_run_details` and `pg_inherits`.

**Open.** Keep the policy, lengthen the horizons, or export to Storage before dropping. `agent_executions` feeds the plan execution quota (current month only), so 90 days is harmless for quota but loses usage history.

**Next step.** Decide. Until then the next run is 2026-11-01 and will drop `agent_executions_2026_07` (empty).

---

### T-13 — Agents other than the Conversational Agent cannot run ⚠️

**What we know.** Since 2026-10-11 there is no platform LLM key: the RAG agent refuses any project agent without its own keys (`LLM_NOT_CONFIGURED`), and only the Conversational Agent (`agent_types.name = 'rag'`) has key fields in the card. The other four agents (General Chatbot, SEO, Follow-up, Lead Qualification) have five connections and **zero messages ever**, so nothing that worked has broken — but their embed script still renders and would answer "not set up yet".

**Open.** Give them the same AI PROVIDER section, or hide their script until they have a runtime of their own.

---

### T-14 — Own-key and rate-limit follow-ups

- **Fixed-window counter.** A visitor can send up to 2×N across a window boundary. Fine for abuse control; switch to a sliding window if exact limits matter.
- **Key cache.** The RAG agent caches a project's client for 60 s, so replacing one working key with another takes up to a minute to apply. A project with no key is never cached.
- **Encryption at rest.** Keys sit in `project_agent_llm_secrets` in plaintext behind RLS + service role, the same as `database_connection_secrets`. Supabase Vault would add encryption at rest for both.
- **`apps/web` has no `env.example`.** Pre-existing gap against `CLAUDE.md` §4; the worker got one on 2026-10-11.
- **Old embedding workers polling this database.** On 2026-10-11 a worker on a machine named `aif` (not this repo's compose stack) claimed a test upload within seconds and embedded it with old code: platform key, `cost_usd` filled, no `documents.embedding_model`. It had also claimed jobs on 2026-09-08. It was stopped the same day, and the next upload was claimed by the new worker. Two other hosts appear in `document_processing_jobs.locked_by` — `atmiyauni` (last job 2026-05-21) and `asp-lp-07-Latitude-5420` (2026-04-01) — and have claimed nothing since; if either still runs, it would embed with a platform key. Production needs the new worker deployed.
- **Not yet tested through the UI** (the rest was browser-tested on 2026-10-11):
  - *Preview exemption from the rate limit.* Checked only with a direct `POST /api/public/rag/chat` carrying `x-ae-preview-token`. The dashboard preview loads its widget from `urls.rag_agent_widget_script_src`, which points at production, so a local preview runs production's widget and the browser blocked it (CORS). Retest in the dashboard preview once the new code is deployed, or point that row at a local URL while testing.
  - *OpenAI and Anthropic.* Only Google was tested with a real key, for both the LLM and embeddings. Save-time key validation, chat and (for OpenAI) embedding still need a real-key run for each provider.
- **Web unit tests.** `lib/connected-agents/agent-ai-settings.ts` was verified with a throwaway `node --test` harness (24 cases); it needs a committed runner — T-05.

---

### T-02 — Query template parameterization *(migrated from `docs/task-queue/pending.md`)*

The largest in-flight feature. Tracking sheet: `docs/task-queue/query-template-parameterization-test-cases.md`.

| ID | Item |
|----|------|
| **QTP-01** | **Web — parameter schema table UI.** In the Add/Edit Query Template dialogs, after the SQL / query-document input, auto-detect placeholder names and show editable structured rows: name prefilled, user fills type, default, required, nullable, description, constraints. Logic in `.ts`, rendering in `.tsx`. |
| **QTP-02** | **Web — placeholder detection and schema sync.** Deterministic parser for SQL `:param_name` and Mongo `{{param_name}}`; merge with existing rows without destructive overwrite; surface new / removed / unchanged state and warn on drift. |
| **QTP-03** | **Contract — canonical `parameter_schema`.** Finalize the shape for SQL and Mongo templates; client- and server-side validation; enforce that every query placeholder exists in the schema and reject invalid defaults and types. |
| **QTP-04** | **RAG — parameter extraction and coercion.** Extract values from the visitor's question, coerce and validate against `parameter_schema` (type, enum, min/max), apply defaults, log resolved parameters. |
| **QTP-05** | **RAG — missing required parameters.** In template modes, when required parameters remain unresolved, ask the visitor targeted clarification questions and resume once answered. |
| **QTP-06** | **RAG — safe parameter binding.** Replace raw placeholder execution with bound parameters for SQL and safe substitution for Mongo, including limit guards and a null-handling strategy. |
| **QTP-07** | **RAG — pre-validator alias fix.** Snapshot-backed qualified-reference validation must resolve table aliases from `FROM`/`JOIN` (`property p`, `city c`) before checking columns, so valid alias-based templates stop failing. |
| **QTP-08** | **Observability — execution diagnostics.** Logs must show template pick outcome, resolved parameters, validator decisions, the final query or query-spec, and the `db_answer` context, so a `template_only` run can be debugged quickly. |
| **QTP-09** | **RAG — scope `conversationExcludedColumns`.** Runtime filters excluded columns whenever exclusions exist. Align with the UI's intent: apply exclusions only in conversational mode (`carouselEnabled = false`); carousel-enabled template flows keep full mapped card context. |

**Context.** `parameter_schema` (JSONB) already exists on `database_connection_query_templates` and the create/update APIs accept `parameterSchema`, but no dialog collects it yet. Schema reference: migration #23, `2026-04-10-database-connection-query-templates-and-mode.sql`.

**Related restriction.** Only `template_only` is accepted for query mode — enforced in the dialog and in the server guard in `database-connection-query-templates-server.ts`. `template_preferred` and `generated` remain in the codebase, intentionally blocked. Rollback: remove the backend allowlist check and re-enable the frontend options. Detail: `docs/task-queue/temporary-query-mode-restriction.md`.

**Open.** Whether the mode restriction lifts once QTP-01…09 land, or stays as a product decision.

---

### T-03 — Widget build, hashing, cache busting

**Decided.** The widget stays in `apps/web/public/` and ships with the web app. It must be built and content-hashed — `rag-agent-widget.<hash>.js` — with the stable embed URL customers already pasted continuing to resolve to the current build. Immutable long-lived caching on the hashed file, short caching on the stable entry point.

**Now more urgent.** The widget is 136 KB (52 KB gzipped) since the font was inlined, and it already has one generated section maintained by `apps/web/scripts/build-widget-font.py`. An unhashed 136 KB file that customers cache indefinitely, with a generated block inside it, is exactly the thing that wants a real build.

**Open.**
- Which bundler — esbuild is the obvious fit for a dependency-free single file, but it introduces the repo's first frontend build step outside Next.
- How the stable URL resolves to the hashed file: a redirect, a tiny loader shim, or a rewrite in `next.config.ts`.
- Whether to move the source out of `public/` into a `widget-src/` and emit into `public/`, which would also make it lintable and testable, and would let the font generator emit a module instead of rewriting a marked block in place.

**Worth copying.** The Rancho project ships versioned widget builds at `dist/scripts/<version>/widget.js`, which solves the same problem a different way — an explicit version in the path rather than a content hash. Look at it before choosing.

**Next step.** Pick the bundler and the stable-URL mechanism.

---

### T-04 — Makefiles and Dockerisation

**Done.** All three services are dockerised, one container each, managed by `docker-compose.yml` and driven entirely from the root `Makefile`: `up` · `down` · `restart` · `logs` · `status` · `ps` · `build`, each for one service or all, plus `make help` and `make help <command>`. Verified end to end — images build, all three containers run, `web` reaches `rag-agent` by service name over the compose network (`/health` → 200), the dashboard serves on `localhost:3001`, every container runs non-root, and `make down` removes containers and network leaving no bound ports. Documented in `CLAUDE.md` §5 and §6.

**Still open.**
- **`web` image is ~3.0 GB**, most of it the Playwright chromium layer needed by the Connected Agents live-website preview. Options: keep it, split the preview into its own small service, or drop chromium and accept that one feature erroring (the import is dynamic and already handles absence). `rag-agent` 838 MB, `embedding-worker` 406 MB.
- **No hot-reload path in containers.** The web image runs a production build, so a code change means `make build-web && make up-web`. If day-to-day dev needs hot reload, add a compose override that bind-mounts the source and runs `next dev`.
- **Playwright's chromium download is the remaining non-hermetic build step.** It hit DNS failures during this work, retried, and succeeded — but `npx playwright install` does not fail the build when a download fails, so a silently chromium-less image is possible. Either assert the binary exists after install, or drop chromium (see the image-size item).
- Remaining Make targets — `setup`, `lint`, `test`, `clean`. `lint` is now worth adding first: the repo reached zero eslint errors in PR #18 and a target makes it cheap to keep there.

*Not our thread:* where the containers actually run is DevOps' call. We hand over merged code on `main`.

---

### T-05 — Test infrastructure

**Decided.** All five rules in `CLAUDE.md` §9 apply.

**Open.** Runner choices and where tests live. Suggested: Vitest for `apps/web/src/lib`, pytest for both Python services, Playwright (already a dependency, used for widget preview) for the end-to-end smoke test.

**Next step.** Stand up the two runners and write rule 4 — the security regression tests — first. Those guard controls that already exist and are currently unguarded.

---

### T-06 — CI

There is no `.github/`, no pipeline, nothing runs on push.

**Open.** Whether CI is GitHub Actions, and what the gate is on a PR into `dev` — at minimum lint plus `npm run build`, growing to the T-05 suites.

**Next step.** Blocked on T-05.

---

### T-07 — README and COSTING corrections

`README.md` describes Upstash queues, Twilio SMS/WhatsApp, SendGrid, OpenRouter as primary, a lead-qualification agent, a follow-up agent, and Vercel + Render + Cloudflare. None of it is real. `COSTING.md` prices that same abandoned stack at $170/month.

**Next step.** Narrow `README.md` to a short public overview pointing at `PROJECT.md`; reprice `COSTING.md` for DigitalOcean + Supabase + Gemini.

---

### T-08 — `docs/db-schema/db-schema-i3.md` is unreadable

1,717 lines exported from a document tool: inline base64 images, `#anchor-N` links, and **no markdown headings at all**, so nothing can navigate it. The content is valuable — soft-delete strategy, UUID v7, partitioning, scale reasoning.

**Open.** Convert to real markdown, or extract the decisions that still hold into `ARCHITECTURE.md` and archive the original.

---

### T-09 — 27 eslint warnings remain

PR #18 took the repo to **zero eslint errors**. 27 warnings are left, untouched and pre-existing.

**Open.** Whether to fix them, or promote the ones worth enforcing to errors and leave the rest. Doing nothing is also a choice — but then `make lint` can never be a CI gate on warnings, only on errors.

**Next step.** Read the 27 and sort them into "fix", "promote to error", and "accept". Blocks the strictest version of T-06.

---

### Fixed 2026-09-09 — T-10, and a loading flash it exposed

**Stale highlight: verified, no defect.** Opening a conversation from a chat hit rings exactly one message; reopening the same conversation from the visitor row's "Open conversation" rings **zero** and starts at the top. The control had been unfindable in earlier attempts because it is labelled "Open conversation", not a visitor action.

**Cold-load skeleton: verified by gating audit, not by frame capture.** The frame remains unsamplable — `browser_navigate` returns only after load and the first `evaluate` lands ~1s later, by which time data has arrived. Since `loading` is true at first paint by construction, the only real failure mode is a container gated on data that arrives later, which is exactly what broke API Keys. All nine surfaces were audited: no skeleton sits behind such a gate, and eight of nine loading flags start `true`.

**The ninth was Analytics, and it was a real bug.** `visitorsLoading` started `false`, so between picking an agent and the fetch starting there was one render with an agent selected, no rows and no loading flag — "No visitors found for this connected agent" flashed before the skeleton. Initialising to `true` did not fix it: the mount-time load sets it false again while no agent is selected. It is now derived by comparing the agent the rows belong to against the selected one, which has no gap to leak through. Verified: skeleton peaks at 70 blocks, no empty-state frame, rows arrive, skeleton clears.

---

## 3. Deferred *(migrated from `docs/task-queue/pending.md`)*

- **Project Overview integration snippet.** A `fetch` / `curl` example with `X-API-Key`, base URL, and env-var and security notes. Uses a placeholder for the key, or points at the API Keys tab. Placeholder helper already exists: `lib/projects/project-overview-snippet-placeholder.ts`.
- **Topbar Help.** `TopbarHelpButton` renders next to Feedback on the dashboard and project layouts with a deliberate no-op `onClick`. Build a `/help` route or panel and drop the "coming soon" `title`.
- **Organization profile and address.** Let users edit `country_id`, `state_id`, `city`, `zipcode`, `address_line_1`, `address_line_2` on `public.organizations`. Nullable in the DB and deliberately left out of onboarding to keep it short.
- **Organization-level subscriptions.** `public.subscriptions` ties `organization_id` + `plan_id`. Today org creation only sets `organizations.plan_id`. The full lifecycle — checkout, subscription row, invoices, payment gateway — is specified in `docs/db-schema/revenue-model-i3.md` and unbuilt.
- **Widget preview pseudo-scroll.** The Playwright fallback renders a static snapshot. Add `scrollY` (and viewport params) to the snapshot API, apply `window.scrollTo(0, scrollY)` before capture, and expose debounced slider / page-up-down controls so users can inspect below-the-fold sections.

---

## 4. Placeholder tabs with no thread yet

**Agent Flow**, **Logs**, **API Docs**, **Integrations**, **Advisors** each render a title and a sentence. Each needs a scope decision before it becomes a thread.

Of these, **Logs** is the most defensible next build — T-01 and the QTP-08 diagnostics both need somewhere for a customer to see what their agent actually did.

---

## 5. Closed

### Done 2026-10-11 — own LLM keys and per-visitor rate limiting (migration `0038`)

- **Per-project AI settings for the Conversational Agent** in the Connected Agents card: LLM provider / model / key, embedding provider / model / key, rate limit (per second or minute, 1–1000, per visitor + 5× per IP). Keys are write-only, test-called on save, stored in `project_agent_llm_secrets`.
- **No platform key anywhere.** The RAG agent and the worker no longer read `*_LLM_API_KEY`; every LLM / embedding call uses the project's key. No key → no script, no preview, no uploads, chat answers "not set up yet".
- **Embedding model switches** are refused while documents embedded with another model exist (`documents.embedding_model`, backfilled for existing documents).
- **Usage logging fixed.** `record-agent-execution.ts` swallowed every insert failure; it now logs them. `agent_executions.model_id` and `embedding_usage_events.worker_model_id` are nullable, with a free-text model name, and no cost is recorded.
- **Provider compatibility.** OpenAI / Anthropic calls retry once without a parameter the model rejects (`temperature`, `top_p`, `max_tokens` → `max_completion_tokens`); JSON replies are unfenced.
- **Tests.** 20 new pytest cases in `tests/test_project_llm_config.py` (56 total), including the no-fallback and key-never-echoed guards.

### Fixed 2026-09-09 — T-01, monthly partitions ran out (migration `0037`)

`messages`, `agent_executions`, and `audit_logs` had monthly children only for 2026-03…06 and no `DEFAULT` partition, so every insert with a current timestamp failed. Confirmed live while testing the widget: a chat send returned `no partition of relation "messages" found for row`.

`0037` created partitions through 2027-12 plus a `DEFAULT` partition on all three tables, wrote `create_next_month_partitions` and `archive_old_partitions`, and scheduled `create-monthly-partitions` (03:00 UTC on the 25th). The two archive jobs turned out to be scheduled already, failing monthly for want of the function — see T-12.

### Merged 2026-09-08 — PR #17

- **Project documents.** `CLAUDE.md`, `PROJECT.md`, `ARCHITECTURE.md`, `THREADS.md`. `AGENTS.md` reduced to a pointer; `docs/task-queue/{pending,completed}.md` folded into this file.
- **`.gitignore` env hardening.** The pattern was the literal filename `.env`, which does not match `.env.bak` — a `cp .env .env.bak` was committable. Widened to every variant and backup, with `env.example` still trackable.
- **Dockerisation.** One container per service, multi-stage, non-root, own build context and `.dockerignore` each, wired by `docker-compose.yml`. Verified: all three run, `web` → `rag-agent` `/health` → 200 over the compose network, no `.env` in any image. Remaining items live in T-04.
- **Root `Makefile`.** `up` / `down` / `restart` / `logs` / `status` / `ps` / `build`, per service or all, plus `make help` and `make help <command>`. Two traps found and documented in `CLAUDE.md` §5: GNU Make does not apply pattern rules to phony targets, and a backgrounded compound command records the subshell's pid rather than the service's process group.
- **Fonts.** Both surfaces stopped fetching from Google. Dashboard on `next/font/local`; widget font inlined as base64 woff2 via `apps/web/scripts/build-widget-font.py`. Verified in a browser: the widget face reports `status: "loaded"`, weight 600 resolves off the variable axis, `font-mono` is not overridden by the body default, and zero requests reach `fonts.googleapis.com` or `fonts.gstatic.com`.

### Fixed 2026-09-09 — retired Gemini models

Four of the six Gemini rows in `public.models` no longer existed at the provider and returned **404 NOT_FOUND**. This was not a fallback-only problem as first thought: **5 agents and 4 plan defaults pointed at dead models**, so those agents failed on every message.

| Model | Was | Agents | Plan defaults |
|---|---|---|---|
| `gemini-2.0-flash` | retired | 1 | 1 |
| `gemini-1.5-flash` | retired | 0 | 2 |
| `gemini-1.5-pro` | retired | 0 | 0 |
| `gemini-3-pro-preview` | retired | 4 | 1 |

Migration `0036` adds `gemini-3.6-flash` and `gemini-2.5-pro`, repoints every agent and plan, and deactivates the dead rows rather than deleting them so `agent_executions` history still resolves. Tier was preserved — pro-tier agents moved to `gemini-2.5-pro`, not down to flash. Verified: **0 agents remain on a retired model**.

Config followed: `settings.py`, `env.example`, `README.md` and the runtime `.env` moved off `gemini-2.0-flash` and `gemini-3-pro-preview`.

### Merged 2026-09-08 — PR #19

- **Storage file editing.** Edit action in the ⋮ menu for `.txt` / `.md` / `.log`, disabled with a reason for everything else and while a document is being embedded. Line-numbered editor with Markdown highlighting; saving overwrites after confirmation, deletes the document's chunks and re-queues embedding so the agent never answers from replaced text. Both rules enforced server-side, not just in the UI.
- **`documents.content_modified_at`** (migration `0035`) and a **Modified** column. A separate column rather than `updated_at`, which the `trg_set_updated_at` trigger moves on renames and on the worker's status writes — none of which change a byte of the file. Reads "Not modified yet" until a real edit.
- **Conversation search in Analytics.** A message index loads once per agent in the background and is searched in the browser, so typing stays instant; matching chats list under the visitor table with visitor name, role, timestamp and the match highlighted, and clicking one opens that conversation scrolled to the message. Capped at 5,000 messages with the cap surfaced in the UI.
- **First/Last message date filters**, independent, with presets. Boundaries are whole local days, built from date components rather than `new Date('YYYY-MM-DD')` — that parses as UTC and then `setHours` mixes zones, which silently shifts the boundary a day west of UTC. 36 tests pass under five timezones.
- **Animated skeletons** on all five tables and all four card grids, matching real page sizes; sweep disabled under `prefers-reduced-motion`. Fixed a pre-existing bug where the API Keys table rendered *nothing* while loading, because its container was gated on `canManage`, which is only known once the request resolves.

### Merged 2026-09-08 — PR #18

- **Seven eslint errors**, all pre-existing: an unescaped apostrophe, a `prefer-const`, three `no-explicit-any` in the Playwright snapshot path (fixed with `import type`, which is erased at compile time so the package stays genuinely optional), and two `react-hooks/set-state-in-effect` fixed by adjusting during render rather than suppressing the rule. Verified with eslint (0 errors), `tsc --noEmit` (exit 0), a container build, and a clean boot.

  **Follow-up, not yet done:** the two hook changes live in the analytics page, which is behind auth, so their runtime behaviour was never exercised. Someone logged in should confirm that switching the agent filter resets to page 1, and that removing a connected agent snaps the filter back to "All connected agents".
- **Stale `/.run` ignore entry**, left over from the host-process Makefile that dockerisation replaced.

### Earlier

- **Project API Keys tab** (`/project/[projectId]/api-keys`) — server-generated keys in `public.project_api_keys` (`key_hash` + `key_prefix`), list, search, pagination, optional expiry, one active key per project with confirmation before rotating, one-time plaintext reveal. The integration snippet was deliberately left off this screen; it lives in the deferred Project Overview item in §3.
