From 8b42a0931c5f1ccd726bd83b2a9d3aad43c15930 Mon Sep 17 00:00:00 2001
From: ahmed mohammed <ahmedmohammed@ahmeds-MacBook-Air.local>
Date: Tue, 22 Sep 2026 12:13:57 +0300
Subject: [PATCH] docs: karpathy-pattern wiki built from the spec, plan, design
 contract and decisions ledger

kb/ is its own wiki root: 34 pages across 7 categories, index.md catalog, log.md, AGENTS.md schema layer, and raw/ holding copies of README, the spec, the 13-task plan, the design master and the SDD ledger.

Every page cross-references 3 to 6 others and all 107 wikilinks resolve except two [["list"]] artefacts inside JSON snippets in the copied plan.

Kept separate from the repository root on purpose: its generated graph lands in kb/.ua/ instead of overwriting the code graph.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 kb/AGENTS.md                             |   26 +
 kb/Analysis row lifecycle.md             |   13 +
 kb/Analyst model.md                      |   20 +
 kb/Console runner.md                     |   13 +
 kb/Container plan.md                     |   12 +
 kb/Credential vault.md                   |   13 +
 kb/Design contract.md                    |    9 +
 kb/Design tokens.md                      |   13 +
 kb/Email collision check.md              |   13 +
 kb/Environment variables.md              |   11 +
 kb/Export and print.md                   |    9 +
 kb/First-run gate.md                     |   14 +
 kb/Gitea remote.md                       |   10 +
 kb/History rail.md                       |   10 +
 kb/Jev goal gate.md                      |   13 +
 kb/Jev scoring.md                        |   18 +
 kb/Lazy database open.md                 |   13 +
 kb/Max nested tags for real plans.md     |   13 +
 kb/OpenUI report language.md             |   16 +
 kb/Option type and sql to run.md         |   15 +
 kb/Output token ceiling.md               |   12 +
 kb/Placeholder SQL is dropped.md         |   14 +
 kb/Plan file encoding.md                 |   15 +
 kb/Playwright projects.md                |   15 +
 kb/Running locally.md                    |   16 +
 kb/SQLite schema.md                      |   16 +
 kb/SSE stream.md                         |   13 +
 kb/Session cookie rules.md               |   12 +
 kb/Settings form.md                      |   17 +
 kb/ShowPlan digest.md                    |   19 +
 kb/Smoke script.md                       |   10 +
 kb/Table names live on Object.md         |   13 +
 kb/Unit suites.md                        |   15 +
 kb/WebKit in QA.md                       |   11 +
 kb/Wiki conventions.md                   |   15 +
 kb/index.md                              |   85 +
 kb/log.md                                |    7 +
 kb/raw/2026-09-21-sql-server-qai-plan.md | 2412 ++++++++++++++++++++++
 kb/raw/2026-09-21-sql-server-qai-spec.md |  114 +
 kb/raw/README.md                         |  112 +
 kb/raw/design-master.md                  |  233 +++
 kb/raw/sdd-progress.md                   |   84 +
 42 files changed, 3534 insertions(+)
 create mode 100644 kb/AGENTS.md
 create mode 100644 kb/Analysis row lifecycle.md
 create mode 100644 kb/Analyst model.md
 create mode 100644 kb/Console runner.md
 create mode 100644 kb/Container plan.md
 create mode 100644 kb/Credential vault.md
 create mode 100644 kb/Design contract.md
 create mode 100644 kb/Design tokens.md
 create mode 100644 kb/Email collision check.md
 create mode 100644 kb/Environment variables.md
 create mode 100644 kb/Export and print.md
 create mode 100644 kb/First-run gate.md
 create mode 100644 kb/Gitea remote.md
 create mode 100644 kb/History rail.md
 create mode 100644 kb/Jev goal gate.md
 create mode 100644 kb/Jev scoring.md
 create mode 100644 kb/Lazy database open.md
 create mode 100644 kb/Max nested tags for real plans.md
 create mode 100644 kb/OpenUI report language.md
 create mode 100644 kb/Option type and sql to run.md
 create mode 100644 kb/Output token ceiling.md
 create mode 100644 kb/Placeholder SQL is dropped.md
 create mode 100644 kb/Plan file encoding.md
 create mode 100644 kb/Playwright projects.md
 create mode 100644 kb/Running locally.md
 create mode 100644 kb/SQLite schema.md
 create mode 100644 kb/SSE stream.md
 create mode 100644 kb/Session cookie rules.md
 create mode 100644 kb/Settings form.md
 create mode 100644 kb/ShowPlan digest.md
 create mode 100644 kb/Smoke script.md
 create mode 100644 kb/Table names live on Object.md
 create mode 100644 kb/Unit suites.md
 create mode 100644 kb/WebKit in QA.md
 create mode 100644 kb/Wiki conventions.md
 create mode 100644 kb/index.md
 create mode 100644 kb/log.md
 create mode 100644 kb/raw/2026-09-21-sql-server-qai-plan.md
 create mode 100644 kb/raw/2026-09-21-sql-server-qai-spec.md
 create mode 100644 kb/raw/README.md
 create mode 100644 kb/raw/design-master.md
 create mode 100644 kb/raw/sdd-progress.md

diff --git a/kb/AGENTS.md b/kb/AGENTS.md
new file mode 100644
index 0000000..f992ed0
--- /dev/null
+++ b/kb/AGENTS.md
@@ -0,0 +1,26 @@
+# Wiki conventions (schema layer)
+
+This directory is a Karpathy-pattern wiki: raw sources, wiki pages, and this schema file.
+
+## Layout
+- `raw/` — immutable sources copied from the repository. Never edited here.
+- `index.md` — the catalog, grouped by category. Every page appears exactly once.
+- `log.md` — chronological record of what was added, and why.
+- `<Page Name>.md` — one page per concept. File name is the link target.
+
+## Categories
+- Pipeline
+- Data and storage
+- Security and credentials
+- Interface
+- Verification
+- Operations
+- Decisions
+
+## Page rules
+1. Start with `# <Page Name>`, then 120 to 250 words of prose.
+2. Cross-reference with `[[Page Name]]`. Every page links 3 to 6 others, and every link must resolve.
+3. State measured facts (numbers, timings, error strings) instead of adjectives. Note the measurement when it
+   came from a specific artifact.
+4. A page about a decision says: what the old behaviour was, what it cost, what replaced it, what it broke.
+5. No code blocks longer than 5 lines. Long code belongs in `raw/`.
diff --git a/kb/Analysis row lifecycle.md b/kb/Analysis row lifecycle.md
new file mode 100644
index 0000000..98bc930
--- /dev/null
+++ b/kb/Analysis row lifecycle.md	
@@ -0,0 +1,13 @@
+# Analysis row lifecycle
+
+A row is created before the plan is validated, so every attempt is visible in the rail. Status moves through
+`running` → `done` | `failed` | `partial` | `abandoned`.
+
+`partial` means some stages produced output before the run stopped. `abandoned` means the browser went away
+mid-run. Both surface as pills in the history rail rather than being hidden, and `/app/[id]` renders whatever
+exists with a "this run was interrupted before it finished" note.
+
+`/app/[id]` never redirects a `running` row. An earlier version did, which turned a row orphaned by a crashed
+process into an infinite self-redirect.
+
+Related: [[SSE stream]], [[SQLite schema]], [[History rail]].
diff --git a/kb/Analyst model.md b/kb/Analyst model.md
new file mode 100644
index 0000000..632d183
--- /dev/null
+++ b/kb/Analyst model.md	
@@ -0,0 +1,20 @@
+# Analyst model
+
+`lib/analyst.ts` talks to any OpenAI-compatible endpoint the user pastes in settings. Two calls, two jobs.
+
+`proposeCandidates` asks for 2 to 4 genuinely different remediation options and validates them against a zod
+schema: `key`, `title`, `diagnosis`, 1-4 `actions`, `option_type`, `sql_to_run`, `expected`. Fewer than two options is
+an error, because [[Jev scoring]] cannot rank a single option.
+
+`streamReport` writes the final answer as OpenUI Lang, streamed token by token into [[OpenUI report language]].
+Its system prompt carries hard requirements: every option with `sql_to_run` gets a SqlBlock containing exactly that
+T-SQL, and every option gets a ScoreBar.
+
+Both calls spread the user's extra JSON parameters *after* `max_tokens`, which is how the output ceiling is raised
+from the settings screen without a rebuild. `extractJson` recovers an object from prose or fenced output and, when
+the response was cut off, names the character count instead of blaming the model.
+
+The local QA endpoint is `http://192.168.88.131:8888/v1` running `qwen3.8-flash-next`; it streams reasoning
+instead of content unless extra params include `{"chat_template_kwargs":{"enable_thinking":false}}`.
+
+Related: [[Jev scoring]], [[Option type and sql to run]], [[Placeholder SQL is dropped]], [[Output token ceiling]].
diff --git a/kb/Console runner.md b/kb/Console runner.md
new file mode 100644
index 0000000..dc2a53f
--- /dev/null
+++ b/kb/Console runner.md	
@@ -0,0 +1,13 @@
+# Console runner
+
+`components/runner.tsx` is the whole console: file drop with encoding-aware decode, the paste box, stage pills,
+SSE reading, the live report, a cancel button, and the error line.
+
+The Analyse button is disabled while a stage is active and re-enabled only on the `done` frame — which is what the
+end-to-end test waits on before asserting report contents.
+
+Design follows the [[Design tokens]] contract: dark workbench, JetBrains Mono for plan data, IBM Plex Sans for
+prose, one phosphor accent. The layout holds at 320 px without horizontal scroll, and every settings field has a
+real `<label for>`.
+
+Related: [[SSE stream]], [[OpenUI report language]], [[Export and print]], [[History rail]].
diff --git a/kb/Container plan.md b/kb/Container plan.md
new file mode 100644
index 0000000..6e06b30
--- /dev/null
+++ b/kb/Container plan.md	
@@ -0,0 +1,12 @@
+# Container plan
+
+`Dockerfile` is a multi-stage Node 25 build — Node 25 because `node:sqlite` is what the data layer uses — and
+`docker-compose.yml` mounts a named volume at `/data` and reads `APP_SECRET` from the host environment.
+
+The image is written but unbuilt on the development machine, which has no Docker. The build is therefore the
+first thing to verify on a machine that has it: `bash scripts/smoke.sh --docker`.
+
+Known rough edges carried forward deliberately: `.dockerignore` excludes tests but the image copies `node_modules`
+including devDependencies, and a first real build may need a tweak.
+
+Related: [[Running locally]], [[Smoke script]], [[Environment variables]].
diff --git a/kb/Credential vault.md b/kb/Credential vault.md
new file mode 100644
index 0000000..e0c6323
--- /dev/null
+++ b/kb/Credential vault.md	
@@ -0,0 +1,13 @@
+# Credential vault
+
+Model keys are pasted by the user into the settings screen. They are never stored as server environment
+configuration and never appear in the DOM of a subsequent page.
+
+`lib/vault.ts` seals with AES-256-GCM under a key derived from `APP_SECRET`, and renders secrets as bullets plus the
+last four characters (`••••1234`). `open` returns null instead of throwing when `APP_SECRET` changed, so the app
+asks for the key again instead of crashing.
+
+`settingsView` is the only shape the forms ever receive, which is what makes "never echo a stored secret back"
+structural rather than a per-field discipline.
+
+Related: [[Session cookie rules]], [[Settings form]], [[SQLite schema]].
diff --git a/kb/Design contract.md b/kb/Design contract.md
new file mode 100644
index 0000000..efef3c3
--- /dev/null
+++ b/kb/Design contract.md	
@@ -0,0 +1,9 @@
+# Design contract
+
+`design-system/sql-server-qai/MASTER.md` is the contract the UI is built against: dark workbench palette, type
+scale, spacing, component rules, and the reason the accent is reserved for action and state rather than decoration.
+
+The Hallmark audit log in `.hallmark/log.json` records the decisions taken against it. Two of them shaped the
+code: no utility CSS framework, and no network font loader.
+
+Related: [[Design tokens]], [[Console runner]].
diff --git a/kb/Design tokens.md b/kb/Design tokens.md
new file mode 100644
index 0000000..7358e63
--- /dev/null
+++ b/kb/Design tokens.md	
@@ -0,0 +1,13 @@
+# Design tokens
+
+`app/tokens.css` defines the palette and scale: dark console background, phosphor-green accent reserved for
+action and state, JetBrains Mono for anything numeric or machine-written, IBM Plex Sans for prose, and a spacing
+scale used everywhere instead of literal margins.
+
+`app/ui.css` turns the tokens into semantic classes — `card`, `field`, `btn`, `pill`, `bar`, `rail` — plus the print
+stylesheet. Tailwind was installed by the scaffold and removed by decision: the design contract is small enough to
+own directly, and utility classes were duplicating tokens rather than expressing them.
+
+Fonts come from the token stack rather than a network font loader, keeping the build offline-light.
+
+Related: [[Export and print]], [[Console runner]], [[Design contract]].
diff --git a/kb/Email collision check.md b/kb/Email collision check.md
new file mode 100644
index 0000000..ab28913
--- /dev/null
+++ b/kb/Email collision check.md	
@@ -0,0 +1,13 @@
+# Decision: email collision check
+
+Changing your email in settings wrote straight to a UNIQUE column. A collision surfaced as a raw constraint error
+inside a server action — the form looked like it did nothing.
+
+`changeEmail` in `lib/auth.ts` now validates the address, compares it case-insensitively after trimming, and
+returns "That email already has an account." when another user owns it. It returns ok when the address is already
+yours.
+
+A deferred neighbour: sessions are not revoked when the password changes, so a 30-day token survives a password
+rotation.
+
+Related: [[First-run gate]], [[Session cookie rules]], [[SQLite schema]].
diff --git a/kb/Environment variables.md b/kb/Environment variables.md
new file mode 100644
index 0000000..8fdd0ab
--- /dev/null
+++ b/kb/Environment variables.md	
@@ -0,0 +1,11 @@
+# Environment variables
+
+Deliberately short. `APP_SECRET` seals stored keys; `DATA_DIR` locates the SQLite file; `COOKIE_SECURE=1` forces the
+Secure flag for a direct https deploy with no proxy setting `X-Forwarded-Proto`.
+
+Nothing about models lives here. Base URL, key, model name, extra JSON parameters, Jev key and Jev model are
+per-user settings encrypted at rest, because the deployment is expected to be self-hosted and shared.
+
+The full file list, with the reasoning for each default, is in the repository README.
+
+Related: [[Credential vault]], [[Session cookie rules]], [[Running locally]].
diff --git a/kb/Export and print.md b/kb/Export and print.md
new file mode 100644
index 0000000..8af04ef
--- /dev/null
+++ b/kb/Export and print.md	
@@ -0,0 +1,9 @@
+# Export and print
+
+Two export actions, both client-side, no PDF library: a Copy button that pulls the SQL blocks out of the rendered
+report, and Print, which opens the browser print dialog against a print stylesheet.
+
+`app/ui.css` carries the print rules — the rail, the toolbar and the runner all hide, so the printed page is the
+report. Saving as PDF from the dialog is the export path.
+
+Related: [[Console runner]], [[OpenUI report language]], [[Design tokens]].
diff --git a/kb/First-run gate.md b/kb/First-run gate.md
new file mode 100644
index 0000000..f901e6e
--- /dev/null
+++ b/kb/First-run gate.md	
@@ -0,0 +1,14 @@
+# First-run gate
+
+The console requires two things before it renders: an analyst base URL with model and key, and a Jev key. The gate
+lives in `app/app/layout.tsx`, so it covers `/app` and `/app/[id]` in one place, and it matches the rule
+`POST /api/analyze` already enforces with a 412.
+
+Before the gate existed, the guide was only reachable because the signup and sign-in actions redirect there. Close
+the wizard halfway and the console rendered anyway, then failed only when Analyse turned red.
+
+The three-step guide is reused as the destination after a save from settings, via a hidden `after` field on
+`SettingsForm`. Without it, a save from the wizard bounced the user straight to the console and the Save button
+looked dead.
+
+Related: [[Session cookie rules]], [[Settings form]], [[Email collision check]].
diff --git a/kb/Gitea remote.md b/kb/Gitea remote.md
new file mode 100644
index 0000000..71e9fb6
--- /dev/null
+++ b/kb/Gitea remote.md	
@@ -0,0 +1,10 @@
+# Gitea remote
+
+The repository is pushed to a self-hosted Gitea at `http://192.168.88.39:3000/ahmed/sql-server-query-ai.git`, branch
+`main`. Credentials were used inline for the push and are deliberately absent from `.git/config`, the README and
+every tracked file; the README documents using a keychain entry or a token instead.
+
+Tracked artifacts that must stay out: the generated `.ua/` graph directory, the QA databases under `.qa-data/`,
+`.playwright-data`, and any production plan file matching `/plan-*.sqlplan` — real plans carry real schema names.
+
+Related: [[Running locally]], [[Wiki conventions]].
diff --git a/kb/History rail.md b/kb/History rail.md
new file mode 100644
index 0000000..bb8985f
--- /dev/null
+++ b/kb/History rail.md	
@@ -0,0 +1,10 @@
+# History rail
+
+The rail lists the signed-in user's runs newest first, with the settings link pinned at the bottom. Each row is a
+card holding the title link, an inline rename field, a delete button, and a status pill that appears only when
+status is not `done`.
+
+Delete never fires on a stray click: the form asks for confirmation and does nothing when it is dismissed. Rename
+and delete are server actions scoped by owner id, so another user's id in a hidden field deletes nothing.
+
+Related: [[Analysis row lifecycle]], [[Console runner]], [[SQLite schema]].
diff --git a/kb/Jev goal gate.md b/kb/Jev goal gate.md
new file mode 100644
index 0000000..5e8a0ab
--- /dev/null
+++ b/kb/Jev goal gate.md	
@@ -0,0 +1,13 @@
+# Jev goal gate
+
+`scripts/jev-gate.mjs` asks Jev whether a document actually builds the stated goal, before code is written from it.
+It asks for a yes/no, a coverage score, coverage confidence, and the biggest gap as a typed choice rather than an
+unfalsifiable "is something missing".
+
+Both the plan and the spec pass: verdict YES, goal match 0.90, coverage 3.71 of 4, biggest gap `nothing`.
+
+Two earlier failures were measurement artefacts, not model verdicts: sending a raw 60k truncation hid the tail of
+the plan, and replacing the text with a heading-and-checkbox skeleton stripped too much prose. The gate now strips
+fenced code blocks, keeps prose, and sends up to 90k.
+
+Related: [[Jev scoring]], [[Smoke script]].
diff --git a/kb/Jev scoring.md b/kb/Jev scoring.md
new file mode 100644
index 0000000..bad1153
--- /dev/null
+++ b/kb/Jev scoring.md	
@@ -0,0 +1,18 @@
+# Jev scoring
+
+Jev is a separate typed judgment model, not a second opinion in prose. `lib/jev.ts` asks it four questions per
+option, gets a value plus a confidence for each, and combines them through `WEIGHTS` into one composite score.
+
+Three flags come out of the scores:
+
+- `verify_semantics` when semantic safety falls below 0.45, or below 0.6 for an option whose `option_type` is
+  `rewrite`. Live Jev scores an index create around 0.57 ("probably equivalent, no stated proof"), so keying the
+  soft floor on the option type rather than on "has SQL" is what keeps the warning useful.
+- `low_confidence` when any dimension's confidence drops under the floor.
+- `change_control` when an action is marked as needing change control.
+
+When Jev is unreachable or abstains, `jevFallback` returns the composite order and marks the source
+`jev_unavailable`, so the report prints "composite order — Jev did not decide" rather than implying Jev chose.
+A real run on the 2.7 MB production plan hit exactly this path and stayed honest.
+
+Related: [[Analyst model]], [[Option type and sql to run]], [[Jev goal gate]].
diff --git a/kb/Lazy database open.md b/kb/Lazy database open.md
new file mode 100644
index 0000000..c8c3941
--- /dev/null
+++ b/kb/Lazy database open.md	
@@ -0,0 +1,13 @@
+# Lazy database open
+
+Opening SQLite at module import time broke `npm run build` with "database is locked": Next collects page data in
+parallel workers, each importing the module and running DDL at once.
+
+The fix is a bound Proxy. Nothing opens until a property is first touched; then `DatabaseSync` is constructed,
+`journal_mode = WAL` and `busy_timeout = 5000` are set, and the schema DDL runs once. The Proxy methods are bound to
+the real instance — an unbound Proxy made every call fail with "TypeError: Illegal invocation".
+
+A second trap: SQLite rows arrive as null-prototype objects, which Next refuses to serialize from a server
+component to a client component. Rows are normalised on read.
+
+Related: [[SQLite schema]], [[Running locally]].
diff --git a/kb/Max nested tags for real plans.md b/kb/Max nested tags for real plans.md
new file mode 100644
index 0000000..274c96d
--- /dev/null
+++ b/kb/Max nested tags for real plans.md	
@@ -0,0 +1,13 @@
+# Decision: max_nested_tags for real plans
+
+A 2.7 MB production plan refused to import with "Maximum nested tags exceeded", which read like a corrupt export.
+The plan was fine: fast-xml-parser's default `maxNestedTags` is 128 and that plan nested **2729 tags deep**. Spaghettified
+nested-loop plans do that.
+
+The cap is now 20 000, bounded in practice by the 12 MB input limit. The same plan digests in 56 ms.
+
+Two more real-plan defects were fixed in the same pass, both invisible to the synthetic fixture: table names are
+read from the `<Object>` child rather than the `<IndexScan>` element itself, and numeric character references such
+as `&#xD;&#xA;` (90 of them in that plan's statement text) are decoded before the text reaches a model.
+
+Related: [[Table names live on Object]], [[ShowPlan digest]].
diff --git a/kb/OpenUI report language.md b/kb/OpenUI report language.md
new file mode 100644
index 0000000..065a78e
--- /dev/null
+++ b/kb/OpenUI report language.md	
@@ -0,0 +1,16 @@
+# OpenUI report language
+
+The report is elements, not markdown. `lib/report-spec.ts` defines the component vocabulary and the library prompt
+with `@openuidev/lang-core`; `lib/report-ui.ts` attaches the React renderers.
+
+The split exists because `@openuidev/react-lang` calls `React.createContext` at module scope, which breaks the API
+route's server-side collection. A route that needs the prompt must not import a React-backed module.
+
+Components: Headline, MetricGrid, Finding, OptionTable, ActionSteps, SqlBlock, ScoreBar, Callout, VerdictBlock.
+The report renders while `oul` is still arriving, so the headline appears before the option table.
+
+Every numeric the model supplies passes through `num` and `conf` guards. Before that, a `null` confidence inside
+ScoreBar threw and OpenUI dropped the whole block — visible live as "runtime/render-error: Component ScoreBar
+render failed".
+
+Related: [[SSE stream]], [[Analyst model]], [[Console runner]].
diff --git a/kb/Option type and sql to run.md b/kb/Option type and sql to run.md
new file mode 100644
index 0000000..8123acf
--- /dev/null
+++ b/kb/Option type and sql to run.md	
@@ -0,0 +1,15 @@
+# Decision: option_type and sql_to_run
+
+The candidate schema used to carry `rewrite_sql`. The name was load-bearing — it is sent to the model — and it
+said "query rewrite only". Result: an index recommendation had no `CREATE INDEX` anywhere in the pipeline, and the
+report rendered zero SQL blocks for a plan whose headline finding was missing indexes.
+
+It became `option_type` (index | statistics | rewrite | schema | app | ops) plus `sql_to_run`, described as the exact
+T-SQL the user must execute, with the instruction that an index or statistics option with null SQL is a wrong
+answer.
+
+Two consequences were deliberate. The report prompt makes a SqlBlock per non-null `sql_to_run` a hard requirement.
+And the `verify_semantics` flag in [[Jev scoring]] now keys on `option_type === "rewrite"`, because keying it on
+"has SQL" would flag every index option for carrying DDL — the exact noise an earlier ruling removed.
+
+Related: [[Placeholder SQL is dropped]], [[Analyst model]], [[Jev scoring]].
diff --git a/kb/Output token ceiling.md b/kb/Output token ceiling.md
new file mode 100644
index 0000000..6b7ddd9
--- /dev/null
+++ b/kb/Output token ceiling.md	
@@ -0,0 +1,12 @@
+# Decision: output token ceiling
+
+Once every option had to carry runnable T-SQL, the candidate JSON outgrew the old 2 048-token budget. The user
+waited 38 seconds and got "The analyst model returned malformed JSON" — a truncated response has no closing brace.
+
+Both calls default to 4 096 now, and the failure message names the character count and tells the user which extra
+parameter raises the ceiling, because `cfg.extra` is spread after `max_tokens`.
+
+The general rule recorded here: when a prompt asks a model for more content, check the budget before blaming the
+model's judgement.
+
+Related: [[Analyst model]], [[Placeholder SQL is dropped]].
diff --git a/kb/Placeholder SQL is dropped.md b/kb/Placeholder SQL is dropped.md
new file mode 100644
index 0000000..1d2427f
--- /dev/null
+++ b/kb/Placeholder SQL is dropped.md	
@@ -0,0 +1,14 @@
+# Decision: placeholder SQL is dropped, not rendered
+
+With the new `sql_to_run` requirement, a report on a 100 KB statement came back containing
+`SELECT ... FROM ... OPTION (MAXDOP 1);`. A block nobody can paste is worse than no block: it reads as an
+instruction and fails on run.
+
+`dropPlaceholderSql` nulls ellipsis SQL after schema validation, so the option simply gets no SqlBlock. The
+heuristic is marked as a deliberate shortcut: `...` is not valid T-SQL, so a literal ellipsis inside a string
+literal would also be dropped, which costs a block and never invents one.
+
+The model is also told upstream: when `digestForModel` sets `sql_truncated$, [[ShowPlan digest]] has already
+warning-ed the analyst out of offering a rewrite for a statement it never received.
+
+Related: [[Option type and sql to run]], [[Output token ceiling]].
diff --git a/kb/Plan file encoding.md b/kb/Plan file encoding.md
new file mode 100644
index 0000000..ab6b846
--- /dev/null
+++ b/kb/Plan file encoding.md	
@@ -0,0 +1,15 @@
+# Plan file encoding
+
+SSMS saves `.sqlplan` as UTF-16LE with a byte-order mark. `File.text()` assumes UTF-8, which turns such a plan into
+NUL-filled junk and makes the parser complain about the user's export. `lib/plan-file.ts` decodes by BOM first
+(UTF-32LE/BE, UTF-16LE/BE, UTF-8), then falls back to NUL density for BOM-less UTF-16: in ASCII XML roughly every
+other byte is `0x00`.
+
+The browser reads the dropped file into bytes and calls `decodePlan`; the server never sniffs encoding. That keeps
+[[ShowPlan digest]] independent of how the text arrived.
+
+Four encodings are pinned by tests: UTF-8, UTF-8 with BOM, UTF-16LE with BOM, UTF-16BE with BOM, and both UTF-16
+variants with no BOM. A browser test uploads a generated UTF-16LE file and asserts the textarea holds no NUL
+characters.
+
+Related: [[ShowPlan digest]], [[Unit suites]], [[Playwright projects]].
diff --git a/kb/Playwright projects.md b/kb/Playwright projects.md
new file mode 100644
index 0000000..3d87564
--- /dev/null
+++ b/kb/Playwright projects.md	
@@ -0,0 +1,15 @@
+# Playwright projects
+
+`npm run e2e` builds first (`pree2e` hook) and then drives the **production** server, not `next dev`. That choice
+caught a real bug: cookie flags and hydration differ between the two, and a dev-only suite never noticed a
+`Secure` cookie that Safari refuses on plain http.
+
+Projects: `setup` signs up the QA account and configures both models through the real UI, writing a storage state;
+`chromium` runs everything except the session spec; `webkit` runs only the session spec, because it is the engine
+that rejects a Secure cookie over `http://localhost`; `mobile` runs only the responsive checks, so a 30-second model
+run is never paid for twice.
+
+One worker, 180-second test timeout, and a single run takes about 55 seconds for 23 tests including a real
+analyst and real Jev call.
+
+Related: [[WebKit in QA]], [[Unit suites]], [[Analyst model]].
diff --git a/kb/Running locally.md b/kb/Running locally.md
new file mode 100644
index 0000000..510a05b
--- /dev/null
+++ b/kb/Running locally.md	
@@ -0,0 +1,16 @@
+# Running locally
+
+`npm install && npm run build && npm start` serves the production build on port 3000. `npm run dev` works too, but
+cookie flags and hydration differ from production, which is why the end-to-end suite exists.
+
+Two environment values matter: `APP_SECRET` (at least 16 characters, seals stored keys — changing it makes them
+unreadable and the app asks for them again) and `DATA_DIR` (where `qai.db` lives, default `./data`).
+`.env.example` documents both plus `COOKIE_SECURE`.
+
+Model credentials are not environment configuration. They belong to each user and are pasted into the settings
+screen.
+
+One operational trap worth knowing: deleting the data directory while a server is running leaves that server
+writing into an unlinked inode. The app keeps answering and the database no longer exists anywhere.
+
+Related: [[Environment variables]], [[Container plan]], [[Gitea remote]].
diff --git a/kb/SQLite schema.md b/kb/SQLite schema.md
new file mode 100644
index 0000000..3add6cd
--- /dev/null
+++ b/kb/SQLite schema.md	
@@ -0,0 +1,16 @@
+# SQLite schema
+
+`lib/db.ts` uses `node:sqlite` — no ORM, no driver, no native build. Four tables:
+
+- `users` — id, unique email, `salt:hash` scrypt password, created_at
+- `sessions` — hashed token, user id, expiry
+- `settings` — one row per user: analyst base URL, model, sealed key, extra JSON, Jev key, Jev model, email, onboarded
+- `analyses` — id, user id, title, raw XML, oul, verdict JSON, status, error, timestamps
+
+`patchAnalysis` only accepts keys from a `PATCHABLE` whitelist, because building `SET` clauses straight from object
+keys is how an object key becomes SQL.
+
+The `saveSettings` upsert uses `COALESCE(NULLIF(excluded.analyst_key, ''), settings.analyst_key)` so that a form
+submitting a blank secret keeps the stored one. Blank means "unchanged", never "clear".
+
+Related: [[Lazy database open]], [[Analysis row lifecycle]], [[Credential vault]].
diff --git a/kb/SSE stream.md b/kb/SSE stream.md
new file mode 100644
index 0000000..dd43b36
--- /dev/null
+++ b/kb/SSE stream.md	
@@ -0,0 +1,13 @@
+# SSE stream
+
+One POST to `/api/analyze` returns a server-sent event stream. `lib/stream.ts` frames events on the server and
+parses them in the browser, and also extracts text deltas from an OpenAI-compatible streaming response.
+
+Four named stages are reported as they happen: digesting, proposing, judging, writing. The console shows them as
+`1 of 4 · Reading the plan` style pills. A `done` frame re-enables the Analyse button; an `error` frame names the
+stage it died in, so a rejected plan reads "digesting: ..." rather than failing silently.
+
+If the browser disconnects, in-flight model fetches are aborted and the row is stored as `abandoned` or `partial`
+instead of piling ghost runs onto the analyst endpoint.
+
+Related: [[Analysis row lifecycle]], [[Console runner]], [[OpenUI report language]].
diff --git a/kb/Session cookie rules.md b/kb/Session cookie rules.md
new file mode 100644
index 0000000..2e1f150
--- /dev/null
+++ b/kb/Session cookie rules.md	
@@ -0,0 +1,12 @@
+# Session cookie rules
+
+The session cookie holds a 32-byte random token; only its hash is stored, and the expiry is enforced in SQL.
+`httpOnly` and `sameSite: lax` always.
+
+`Secure` is set from the request, not the build: only when `X-Forwarded-Proto` reports `https`, or when
+`COOKIE_SECURE=1` is set for a direct TLS deploy. The previous rule (`secure: NODE_ENV === "production"`) meant a
+production build on plain `http://localhost` asked browsers for a Secure cookie. Chromium allows that on localhost;
+Safari refuses to store it at all, so every page after signup looked signed-out and the wizard appeared to sign
+users out. A Chromium-only suite could never observe it.
+
+Related: [[WebKit in QA]], [[First-run gate]], [[Running locally]].
diff --git a/kb/Settings form.md b/kb/Settings form.md
new file mode 100644
index 0000000..d44be6b
--- /dev/null
+++ b/kb/Settings form.md	
@@ -0,0 +1,17 @@
+# Settings form
+
+components/settings-form.tsx is the credential screen, used twice: as step 2 of the first-run guide and on
+/settings. It renders analyst base URL, analyst key, analyst model, extra JSON parameters, Jev key and Jev model,
+plus the account email change field.
+
+It renders values from settingsView only, so a stored secret is never echoed back into the DOM - the fields show
+bullet-masked values, and a blank submission means "keep what is stored", enforced again in the upsert (see
+[[SQLite schema]]).
+
+The form carries a hidden after field. When the submission comes from the wizard, the action returns the user to
+/setup?step=3 so the readiness screen and its "Saved." message actually render; without it a configured user was
+forwarded straight to the console and Save appeared to do nothing.
+
+Every field has a real label element, asserted by the responsive Playwright checks.
+
+Related: [[First-run gate]], [[Credential vault]], [[Email collision check]].
diff --git a/kb/ShowPlan digest.md b/kb/ShowPlan digest.md
new file mode 100644
index 0000000..528e969
--- /dev/null
+++ b/kb/ShowPlan digest.md	
@@ -0,0 +1,19 @@
+# ShowPlan digest
+
+`lib/digest.ts` converts a SQL Server ShowPlan XML document into a bounded JSON summary before any model is
+consulted. The point is that the models judge facts, not guess them: [[Plan file encoding]] hands it clean text,
+then it walks the parsed document for operators, tables, missing-index groups, waits and warnings.
+
+Each operator keeps `NodeId`, the logical or physical op name, `EstimateIO`, `EstimateCPU`,
+`EstimatedTotalSubtreeCost`, estimated rows, and actual rows where the plan carries
+`RunTimeCountersPerThread`. Attribute spellings differ across SQL Server builds, so every cost field falls
+through the known variants rather than trusting one.
+
+`digestForModel` is the budget gate: 4 000 characters of statement text, 20 tables, 12 operators, 5 missing
+index groups, 20 warnings. It also sets `sql_truncated` when the statement was cut, which stops [[Analyst model]]
+from offering a rewrite of a query it never received.
+
+Measured on a 2 694 090-byte production plan (UTF-16LE, 1 352 044 characters, 2 729 tags deep): 2 ms to decode,
+56 ms to digest, 37 distinct tables, and `StatementOptmEarlyAbortReason = TimeOut` surfaced as the headline finding.
+
+Related: [[Jev scoring]], [[Max nested tags for real plans]], [[Table names live on Object]].
diff --git a/kb/Smoke script.md b/kb/Smoke script.md
new file mode 100644
index 0000000..72981bb
--- /dev/null
+++ b/kb/Smoke script.md	
@@ -0,0 +1,10 @@
+# Smoke script
+
+`bash scripts/smoke.sh` checks a running instance with curl and nothing else: healthz answers, the login and signup
+pages render, a signed-out visit to `/app` redirects, and `/api/analyze` refuses a request without a session.
+Five checks, exits non-zero on the first failure.
+
+It works against any `BASE_URL`, and `--docker` is reserved for running it against the container once a Docker host
+is available.
+
+Related: [[Jev goal gate]], [[Running locally]], [[Container plan]].
diff --git a/kb/Table names live on Object.md b/kb/Table names live on Object.md
new file mode 100644
index 0000000..13eb1da
--- /dev/null
+++ b/kb/Table names live on Object.md	
@@ -0,0 +1,13 @@
+# Decision: table names come from the Object child
+
+`digestPlan` built its table list by reading `Database`/`Schema`/`Table` attributes off `<IndexScan>` and
+`<TableScan>` elements. Real ShowPlan puts those attributes on the `<Object>` child. The production plan with 51
+objects therefore digested to **zero tables**, and the analyst model was asked to fix a query whose tables it could
+not see.
+
+The fix reaches into the child: the scan's own attributes, else `<Object>`. The third fallback level that looked
+plausible in theory turned out to be dead code and was deleted rather than kept as insurance.
+
+Pinned by a test using the real element shape, and visible in the measured difference: 0 tables before, 37 after.
+
+Related: [[Max nested tags for real plans]], [[ShowPlan digest]].
diff --git a/kb/Unit suites.md b/kb/Unit suites.md
new file mode 100644
index 0000000..1a9e2f3
--- /dev/null
+++ b/kb/Unit suites.md	
@@ -0,0 +1,15 @@
+# Unit suites
+
+`npm test` runs `node --no-warnings --test tests/*.test.ts` — 43 tests, no test framework installed, nothing
+external. The analyst and Jev are exercised through injected `fetch`, so no key and no network is needed.
+
+Constraints that shape the code, not the tests: modules loaded by bare `node --test` cannot resolve the `@`
+import alias, so test-imported modules import each other by relative `./x.ts` path (which is why
+`allowImportingTsExtensions` is on), and `next/headers` plus `next/navigation` are imported lazily inside
+`lib/auth.ts`.
+
+The digest suite is the one that grew teeth: it now asserts nesting depth beyond the parser default, table names
+taken from `<Object>` children, character-reference decoding, six plan-file encodings, and that a truncated plan's
+error names a reason.
+
+Related: [[Playwright projects]], [[Smoke script]], [[Plan file encoding]].
diff --git a/kb/WebKit in QA.md b/kb/WebKit in QA.md
new file mode 100644
index 0000000..7a5c22d
--- /dev/null
+++ b/kb/WebKit in QA.md	
@@ -0,0 +1,11 @@
+# WebKit in QA
+
+A `webkit` project exists for one reason: Chromium treats `http://localhost` as a secure context and will store a
+`Secure` cookie there, so a chromium-only suite passes while Safari users are bounced to the login page after
+signup. That is precisely the bug reported after delivery.
+
+The spec signs up its own account, walks the wizard's Next links, and asserts the final destination is the
+onboarding gate at `/setup?step=2` — proof of a live session — because a lost session would land on `/login`.
+A second spec reloads a deep page and checks the session survives.
+
+Related: [[Session cookie rules]], [[Playwright projects]], [[First-run gate]].
diff --git a/kb/Wiki conventions.md b/kb/Wiki conventions.md
new file mode 100644
index 0000000..6e8e0d3
--- /dev/null
+++ b/kb/Wiki conventions.md	
@@ -0,0 +1,15 @@
+# Wiki conventions
+
+kb/AGENTS.md is the schema layer of this wiki: the layout, the category list and the page rules. It exists so a new
+page can be added without inventing structure each time.
+
+The rules that matter: one concept per file, the file name is the link target, every page cross-references 3 to 6
+others and every link must resolve, measured numbers are stated with the artifact they came from, and a decision
+page names the old behaviour, its cost, the replacement, and what it broke.
+
+The wiki is deliberately separate from the repository's own documentation. raw/ holds copies of README, the spec,
+the implementation plan, the design contract and the decisions ledger - copied, never edited in place - so the pages
+above have citable sources. Keeping the wiki in its own root also keeps its generated graph in kb/.ua/ instead of
+overwriting the code graph at the repository root.
+
+Related: [[Gitea remote]], [[Design contract]], [[Running locally]].
diff --git a/kb/index.md b/kb/index.md
new file mode 100644
index 0000000..1b07ad2
--- /dev/null
+++ b/kb/index.md
@@ -0,0 +1,85 @@
+# qAI knowledge base — index
+
+Wiki pages about SQL Server qAI: 34 pages across 7 categories.
+Raw sources are in `raw/` (copied, never edited here). Conventions live in `AGENTS.md`. History lives in `log.md`.
+
+## Pipeline
+
+- [[ShowPlan digest]] — lib/digest.ts converts a SQL Server ShowPlan XML document into a bounded JSON summary before any model is
+consulted.
+- [[Plan file encoding]] — SSMS saves .sqlplan as UTF-16LE with a byte-order mark.
+- [[Analyst model]] — lib/analyst.ts talks to any OpenAI-compatible endpoint the user pastes in settings.
+- [[Jev scoring]] — Jev is a separate typed judgment model, not a second opinion in prose.
+- [[OpenUI report language]] — The report is elements, not markdown.
+- [[SSE stream]] — One POST to /api/analyze returns a server-sent event stream.
+
+## Data and storage
+
+- [[SQLite schema]] — lib/db.ts uses node:sqlite — no ORM, no driver, no native build.
+- [[Lazy database open]] — Opening SQLite at module import time broke npm run build with "database is locked": Next collects page data in
+parallel
+- [[Analysis row lifecycle]] — A row is created before the plan is validated, so every attempt is visible in the rail.
+
+## Security and credentials
+
+- [[Credential vault]] — Model keys are pasted by the user into the settings screen.
+- [[Session cookie rules]] — The session cookie holds a 32-byte random token;
+- [[First-run gate]] — The console requires two things before it renders: an analyst base URL with model and key, and a Jev key.
+
+## Interface
+
+- [[Console runner]] — components/runner.tsx is the whole console: file drop with encoding-aware decode, the paste box, stage pills,
+SSE readin
+- [[History rail]] — The rail lists the signed-in user's runs newest first, with the settings link pinned at the bottom.
+- [[Export and print]] — Two export actions, both client-side, no PDF library: a Copy button that pulls the SQL blocks out of the rendered
+report
+- [[Design tokens]] — app/tokens.css defines the palette and scale: dark console background, phosphor-green accent reserved for
+action and sta
+- [[Settings form]] — components/settings-form.tsx is the credential screen, used twice: as step 2 of the first-run guide and on
+/settings.
+- [[Design contract]] — design-system/sql-server-qai/MASTER.md is the contract the UI is built against: dark workbench palette, type
+scale, spac
+
+## Verification
+
+- [[Unit suites]] — npm test runs node --no-warnings --test tests/*.test.ts — 43 tests, no test framework installed, nothing
+external.
+- [[Playwright projects]] — npm run e2e builds first (pree2e hook) and then drives the **production** server, not next dev.
+- [[WebKit in QA]] — A webkit project exists for one reason: Chromium treats http://localhost as a secure context and will store a
+Secure coo
+- [[Smoke script]] — bash scripts/smoke.sh checks a running instance with curl and nothing else: healthz answers, the login and signup
+pages
+- [[Jev goal gate]] — scripts/jev-gate.mjs asks Jev whether a document actually builds the stated goal, before code is written from it.
+It ask
+
+## Operations
+
+- [[Running locally]] — npm install && npm run build && npm start serves the production build on port 3000.
+- [[Container plan]] — Dockerfile is a multi-stage Node 25 build — Node 25 because node:sqlite is what the data layer uses — and
+docker-compose
+- [[Environment variables]] — Deliberately short.
+- [[Gitea remote]] — The repository is pushed to a self-hosted Gitea at http://192.168.88.39:3000/ahmed/sql-server-query-ai.git, branch
+main.
+- [[Wiki conventions]] — kb/AGENTS.md is the schema layer of this wiki: the layout, the category list and the page rules.
+
+## Decisions
+
+- [[Option type and sql to run]] — The candidate schema used to carry rewrite_sql.
+- [[Placeholder SQL is dropped]] — With the new sql_to_run requirement, a report on a 100 KB statement came back containing
+SELECT ...
+- [[Max nested tags for real plans]] — A 2.7 MB production plan refused to import with "Maximum nested tags exceeded", which read like a corrupt export.
+The pl
+- [[Table names live on Object]] — digestPlan built its table list by reading Database/Schema/Table attributes off <IndexScan> and
+<TableScan> elements.
+- [[Output token ceiling]] — Once every option had to carry runnable T-SQL, the candidate JSON outgrew the old 2 048-token budget.
+- [[Email collision check]] — Changing your email in settings wrote straight to a UNIQUE column.
+
+## Sources
+
+Immutable inputs, copied verbatim into `raw/`. These are the artifacts every measured number above came from.
+
+- `raw/README.md` — the repository's own front page.
+- `raw/2026-09-21-sql-server-qai-spec.md` — approved specification.
+- `raw/2026-09-21-sql-server-qai-plan.md` — the 13-task implementation plan the code was built from.
+- `raw/design-master.md` — the design contract.
+- `raw/sdd-progress.md` — the decisions ledger every page in the Decisions category is drawn from.
diff --git a/kb/log.md b/kb/log.md
new file mode 100644
index 0000000..c5563da
--- /dev/null
+++ b/kb/log.md
@@ -0,0 +1,7 @@
+# Operation log
+
+## 2026-09-22 — initial wiki
+- Copied 5 repository sources into `raw/` (README, spec, 13-task plan, design master, SDD ledger).
+- Wrote 34 pages from the documentation, the in-code comments and the decisions ledger, grouped into 7 categories.
+- Every page cross-references 3 to 6 others; measured numbers come from the artifacts named in `raw/`.
+- Deliberately kept out: anything from `plan-cxpaket.sqlplan` beyond the aggregate measurements it produced.
diff --git a/kb/raw/2026-09-21-sql-server-qai-plan.md b/kb/raw/2026-09-21-sql-server-qai-plan.md
new file mode 100644
index 0000000..f30e09d
--- /dev/null
+++ b/kb/raw/2026-09-21-sql-server-qai-plan.md
@@ -0,0 +1,2412 @@
+# SQL Server qAI 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:** A containerised portal where a DBA pastes a SQL Server ShowPlan XML, gets 2–4 ranked remediation options plus SQL rewrites, with Jev (TypeSafe System One) scoring every option and choosing the first one to run, rendered as streamed OpenUI Lang elements.
+
+**Architecture:** One Next.js process, one SQLite file. The pipeline is deterministic-first: code parses the plan XML into a bounded digest, the user's OpenAI-compatible **analyst** model proposes candidates as JSON, **Jev** answers typed `score`/`choice`/`noul` questions about each candidate, code combines them with visible weights, then the analyst streams the final report in OpenUI Lang which `<Renderer>` paints as it arrives. Reopening a history item replays the stored report — zero model calls.
+
+**Tech Stack:** Next.js 16 (App Router) + React 19 + TypeScript, Tailwind v4 (layout utilities only), `node:sqlite`, `node:crypto`, `fast-xml-parser`, `zod/v4`, `@openuidev/react-lang`, `@typesafe-ai/sdk`, `lucide-react`. Tests with `node --test` on `.ts` files — Node strips types natively, so there is no test framework to install.
+
+**Spec:** `docs/superpowers/specs/2026-09-21-sql-server-qai.md`
+
+## What the user sees
+
+Written for the implementer and for anyone reviewing whether this is the product that was asked for. No code in this section.
+
+- **Sign up** with email + password. Nothing else exists before that; there is no public analysis page.
+- **First-run guide, 3 steps.** Step 1 explains what the tool does. Step 2 is one form: the analyst model (base URL, key, model name, extra JSON params) and the Jev key. Step 3 confirms both models are reachable and sends them to the console. Every credential is typed by the logged-in user in this panel or in Settings — none is read from server config, so a second user brings their own keys and their own spend.
+- **Settings** holds the same form plus email/password change. Stored keys show as `••••1234`; leaving a key blank keeps the stored one.
+- **Console**: left rail is the history (rename inline, delete behind a confirm); the main pane is one job — paste ShowPlan XML or drop a `.sqlplan` file, optionally add a note, press Analyse. A "Where do I get this XML?` disclosure gives the SSMS route (Ctrl+M → run → save the `.sqlplan`) and the `SET STATISTICS XML ON` route for people without SSMS.
+- **During a run** four stages are named one at a time: reading the plan, asking for options, Jev is scoring, writing the report. The report then paints while it is still streaming.
+- **The report** is OpenUI elements, never a markdown blob: the finding, Jev's first move with its confidence, plan metrics, the findings with plan evidence, a ranked options table with the weights printed, each option's action steps and any rewritten SQL, per-dimension Jev score bars, and a danger callout whenever an option could change results.
+- **Copy** puts the SQL (or the whole report source when there is no SQL) on the clipboard, per block and for the whole report. **Export to PDF** is the browser print path with a paper stylesheet — the dark console flips to black-on-white and the rail and buttons disappear.
+- **Nothing leaves the container** except the plan digest — top operators, missing indexes, warnings, waits, the statement text — sent to the user's own analyst endpoint and to TypeSafe. Raw XML stays in the local SQLite file.
+- **Failures are named where they happen**: not-a-plan, analyst 401/prose/too-few-options, Jev rate-limited (composite order, labelled as such), empty report. A partially stored run still opens from history and shows what it managed to produce.
+
+## Global Constraints
+
+- Node ≥ 24 (Docker base `node:24-slim`). Verified on this machine: `node --test x.test.ts` runs TypeScript directly; `node:sqlite` `DatabaseSync` works without a flag.
+- Allowed runtime deps, nothing else without a one-line reason in the commit message: `next react react-dom zod @openuidev/react-lang @typesafe-ai/sdk fast-xml-parser lucide-react`.
+- No ORM. No auth library. No PDF library. No queue/worker. No OpenAI SDK — raw `fetch` to `/chat/completions`.
+- Model + Jev credentials are per-user, AES-256-GCM encrypted at rest with `APP_SECRET`, never sent to the browser (masked `••••1234`).
+- Jev is `@typesafe-ai/sdk` → `POST /v1/systemone`, model `jev-latest`. Jev never generates prose; it returns probabilities. Combining happens in code.
+- Analyst is any OpenAI-compatible base URL + key + model + extra params, from Settings.
+- All colour and type flows through named tokens (`var(--qai-*)`) — Hallmark gate 48: no inline hex/oklch inside components.
+- Dark-only console (OLED slate + phosphor green). Print/PDF flips the same tokens to paper white.
+- Copy = clipboard. PDF = `window.print()` + print stylesheet. No generated-file endpoints.
+- Mobile: 320 / 375 / 414 / 768 px, no horizontal scroll, `overflow-x: clip` on `html` and `body`.
+- Delete confirms first. Every mutation shows a visible result.
+
+## Design System (locked — Hallmark + ui-ux-pro-max)
+
+Generated with `ui-ux-pro-max --design-system --variance 4 --motion 3 --density 8`; persisted at `design-system/sql-server-qai/MASTER.md`. Read that file before any UI task. Page overrides go in `design-system/sql-server-qai/pages/<page>.md`.
+
+- Genre **atmospheric** · theme **Terminal** (mono display, phosphor accent) · macrostructure **Workbench** (app-console variant; auth/setup use **Long Document**) · nav **N3 side-rail** — the history rail *is* the nav · footer **Ft4 dense colophon** on auth/setup/settings only; the console has no footer.
+- Type: JetBrains Mono for display/data/labels, IBM Plex Sans for prose. No italic headings, no gradient text, no glassmorphism, no emoji icons (lucide-react SVG only).
+- Density 8/10: 4 px scale, 15 px body, 12 px floor.
+- Motion 3/10: fade + 120–220 ms `--qai-ease-out` only. `prefers-reduced-motion` → instant.
+- Every UI task: keep values in `tokens.css`, reference tokens by name, keep the Hallmark stamp at the top of `app/ui.css`, append the run to `.hallmark/log.json`.
+
+## File Structure
+
+```
+tokens.css                 all colour/type/space/easing tokens (single source)
+app/globals.css            tailwind import + tokens.css + ui.css
+app/ui.css                 every component class (Hallmark stamped)
+app/layout.tsx             fonts + <html>
+app/page.tsx               redirect → /app or /login
+app/(auth)/layout.tsx      centred auth shell + Ft4 colophon
+app/(auth)/login/page.tsx  login
+app/(auth)/signup/page.tsx signup
+app/setup/page.tsx         first-run guide, 3 steps
+app/settings/page.tsx      model / Jev / account / history
+app/app/layout.tsx         console shell: side rail + main
+app/app/page.tsx           run surface
+app/app/[id]/page.tsx      replay a stored report (no model calls)
+app/api/analyze/route.ts   SSE pipeline: digest → candidates → Jev → report
+app/api/healthz/route.ts   "ok"
+lib/db.ts                  node:sqlite + schema + all queries
+lib/auth.ts                scrypt, sessions, requireUser
+lib/vault.ts               AES-256-GCM seal/open/mask
+lib/settings.ts            settings row <-> typed config, encrypt on write
+lib/digest.ts              ShowPlan XML -> Digest (pure, no I/O)
+lib/analyst.ts             candidates + report stream (OpenAI-compatible)
+lib/jev.ts                 Jev questions, composite weights, verdict
+lib/report-ui.tsx          OpenUI component library + prompt
+lib/stream.ts              SSE encode/decode + OpenAI delta extractor (pure)
+lib/actions.ts             server actions: signup/login/logout/rename/delete/settings
+components/*.tsx           auth-form, settings-form, runner, rail, report-view
+scripts/jev-gate.mjs       asks Jev yes/no: does this plan match the goal?
+scripts/smoke.sh           container smoke
+tests/*.test.ts            node:test, no framework
+Dockerfile docker-compose.yml .env.example README.md
+```
+
+Pure logic lives in `lib/*.ts` so it is testable without Next. Pages and components get build + manual checks.
+
+## Review Focus
+
+None of these is exercised by the spec's happy path. Each is pinned to a test in the named task.
+
+1. **Not a plan.** Pasted a `.sql` script, truncated XML, or a namespaced `.sqlplan` → inline error naming what was found; never an endless spinner. *(Task 6 + Task 10)*
+2. **Analyst misconfig.** Wrong base URL, 401, prose instead of JSON, or 1 candidate instead of 2–4 → error names the stage and the HTTP status; no empty report renders. *(Task 7)*
+3. **Semantically unsafe rewrite.** A `SELECT TOP 100 …` that drops a predicate must never be the safe recommendation — Jev's `semantic_safety` under 0.6 forces a visible "verify results first" flag and keeps it out of the headline slot. *(Task 8)*
+4. **Huge plans.** 5 MB+ XML with thousands of operators → hard 12 MB cap, digest bounded to the top operators, report says it analysed a digest. No hang, no OOM, no full-XML prompt. *(Task 6 + Task 10)*
+5. **Partial failure mid-run.** Jev 429/529 or timeout after candidates exist → composite-only ranking with a `jev_unavailable` flag; the row is saved with what it has; reopening it never re-calls a model. *(Task 8 + Task 10)*
+
+---
+
+### Task 1: Scaffold, tokens, console shell
+
+**Files:** create via `create-next-app` in `.` (keep existing `docs/`, `design-system/`); create `tokens.css`, `app/globals.css`, `app/ui.css`, `app/layout.tsx`, `app/page.tsx`, `app/app/layout.tsx`, `app/app/page.tsx`, `app/api/healthz/route.ts`, `.env.example`, `.hallmark/log.json`; modify `package.json`, `.gitignore`.
+
+**Interfaces — produces:** tokens `--qai-{paper,paper-2,paper-3,ink,ink-muted,accent,on-accent,warn,danger,info,rule,focus}`, `--qai-font-{display,body}`, `--qai-space-{xs,s,md,l,xl,2xl,3xl}`, `--qai-text-{xs,sm,base,lg,xl,2xl,display}`, `--qai-ease-out`, `--qai-dur-{1,2}`, `--qai-radius`. Classes `.shell .rail .main .card .btn .btn-primary .field .label .pill .colophon .report .sql .bar .grid-metrics .runner .toolbar`.
+
+- [ ] **Step 1: Scaffold and install**
+
+```bash
+npx create-next-app@latest . --ts --tailwind --eslint --app --no-src-dir --import-alias "@/*" --use-npm
+npm i zod @openuidev/react-lang @typesafe-ai/sdk fast-xml-parser lucide-react
+npm pkg set scripts.test="node --no-warnings --test tests/*.test.ts"
+git init -q && git add -A && git commit -qm "scaffold: next 16 + tailwind"
+```
+
+- [ ] **Step 2: `tokens.css`**
+
+```css
+/* Hallmark · genre: atmospheric · macrostructure: Workbench · theme: Terminal
+ * enrichment: none (typography only) · nav: N3 side-rail · footer: Ft4 dense colophon
+ * inferred: audience = DBAs/consultants · use = analyse one plan · tone = technical-utilitarian
+ * axes: paper band dark (L<30%) · display mono · accent phosphor green
+ */
+:root {
+  --qai-paper: oklch(17% 0.014 255);
+  --qai-paper-2: oklch(21% 0.015 258);
+  --qai-paper-3: oklch(26% 0.016 260);
+  --qai-ink: oklch(96% 0.004 250);
+  --qai-ink-muted: oklch(72% 0.02 250);
+  --qai-accent: oklch(80% 0.19 152);
+  --qai-on-accent: oklch(20% 0.04 152);
+  --qai-warn: oklch(82% 0.15 86);
+  --qai-danger: oklch(66% 0.21 25);
+  --qai-info: oklch(77% 0.11 232);
+  --qai-rule: oklch(31% 0.016 258);
+  --qai-focus: var(--qai-accent);
+  --qai-font-display: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace;
+  --qai-font-body: "IBM Plex Sans", system-ui, sans-serif;
+  --qai-space-xs: 4px;  --qai-space-s: 8px;  --qai-space-md: 12px; --qai-space-l: 16px;
+  --qai-space-xl: 24px; --qai-space-2xl: 32px; --qai-space-3xl: 48px;
+  --qai-text-xs: 12px; --qai-text-sm: 13px; --qai-text-base: 15px; --qai-text-lg: 18px;
+  --qai-text-xl: 22px; --qai-text-2xl: 28px; --qai-text-display: 34px;
+  --qai-ease-out: cubic-bezier(0.2, 0.7, 0.2, 1);
+  --qai-dur-1: 120ms; --qai-dur-2: 220ms;
+  --qai-radius: 6px;
+}
+@media print {
+  :root { --qai-paper:#fff; --qai-paper-2:#f4f5f7; --qai-paper-3:#e9ebef; --qai-ink:#14161a;
+          --qai-ink-muted:#4a5160; --qai-rule:#c9ced8; --qai-accent:#0a7d3c; --qai-on-accent:#fff;
+          --qai-warn:#8a5a00; --qai-danger:#a11212; --qai-info:#1a4fb8; }
+}
+```
+
+- [ ] **Step 3: `app/globals.css` + `app/ui.css`**
+
+`app/globals.css` — keep create-next-app's Tailwind directives at the top, then add:
+
+```css
+@import "./tokens.css";
+@import "./ui.css";
+
+html, body { overflow-x: clip; }
+body { background: var(--qai-paper); color: var(--qai-ink); font-family: var(--qai-font-body);
+       font-size: var(--qai-text-base); line-height: 1.5; margin: 0; }
+* { box-sizing: border-box; }
+:focus-visible { outline: 2px solid var(--qai-focus); outline-offset: 2px; }
+@media (prefers-reduced-motion: reduce) { * { animation-duration: .01ms !important; transition-duration: .01ms !important; } }
+```
+
+`app/ui.css` (starts with the stamp above — copy the stamp from `tokens.css` into it too):
+
+```css
+.shell { display: grid; grid-template-columns: 260px minmax(0,1fr); min-height: 100dvh; }
+.rail { background: var(--qai-paper-2); border-inline-end: 1px solid var(--qai-rule);
+        padding: var(--qai-space-l); display: flex; flex-direction: column; gap: var(--qai-space-md);
+        font-family: var(--qai-font-display); min-width: 0; }
+.main { min-width: 0; padding: var(--qai-space-2xl); display: flex; flex-direction: column; gap: var(--qai-space-xl); }
+.card { background: var(--qai-paper-2); border-radius: var(--qai-radius); padding: var(--qai-space-l); min-width: 0; }
+.btn { font: 500 var(--qai-text-sm)/1 var(--qai-font-display); padding: 10px 14px; border-radius: var(--qai-radius);
+       border: 1px solid var(--qai-rule); background: var(--qai-paper-3); color: var(--qai-ink); cursor: pointer;
+       transition: background var(--qai-dur-1) var(--qai-ease-out), transform var(--qai-dur-1) var(--qai-ease-out); }
+.btn:hover { background: var(--qai-rule); } .btn:active { transform: translateY(1px); }
+.btn:disabled { opacity: .5; cursor: not-allowed; }
+.btn-primary { background: var(--qai-accent); color: var(--qai-on-accent); border-color: transparent; }
+.field { width: 100%; background: var(--qai-paper); color: var(--qai-ink); border: 1px solid var(--qai-rule);
+         border-radius: var(--qai-radius); padding: 10px 12px; font-family: var(--qai-font-display); font-size: var(--qai-text-sm); }
+.label { font: 500 var(--qai-text-xs)/1 var(--qai-font-display); color: var(--qai-ink-muted);
+         text-transform: uppercase; letter-spacing: .04em; }
+.pill { font: 500 var(--qai-text-xs)/1 var(--qai-font-display); padding: 4px 8px; border-radius: 999px;
+        border: 1px solid var(--qai-rule); color: var(--qai-ink-muted); }
+.colophon { border-top: 1px solid var(--qai-rule); padding: var(--qai-space-l) 0;
+            font: 400 var(--qai-text-xs)/1.6 var(--qai-font-display); color: var(--qai-ink-muted); }
+.report { display: flex; flex-direction: column; gap: var(--qai-space-l); min-width: 0; }
+.grid-metrics { display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr)); gap: var(--qai-space-md); }
+.sql { overflow-x: auto; font-family: var(--qai-font-display); font-size: var(--qai-text-sm); white-space: pre; }
+.bar { height: 6px; border-radius: 999px; background: var(--qai-accent); max-width: 100%; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+[data-level="danger"] { border-inline-start: 3px solid var(--qai-danger); }
+[data-level="warn"] { border-inline-start: 3px solid var(--qai-warn); }
+[data-verdict] { border-inline-start: 3px solid var(--qai-accent); }
+@media (max-width: 860px) { .shell { grid-template-columns: minmax(0,1fr); } .rail { border-inline-end: 0; } }
+@media print { .rail, .runner, .toolbar, .colophon, .no-print { display: none !important; }
+               .shell { grid-template-columns: minmax(0,1fr); } .main { padding: 0; } }
+```
+
+- [ ] **Step 4: Layout, shell, healthz**
+
+`app/layout.tsx`:
+
+```tsx
+import type { Metadata, Viewport } from "next";
+import { IBM_Plex_Sans, JetBrains_Mono } from "next/font/google";
+import "./globals.css";
+
+const body = IBM_Plex_Sans({ subsets: ["latin"], weight: ["400", "500", "600"], variable: "--font-body" });
+const mono = JetBrains_Mono({ subsets: ["latin"], weight: ["400", "500", "700"], variable: "--font-mono" });
+
+export const metadata: Metadata = { title: "SQL Server qAI", description: "Query plan triage, ranked by Jev." };
+export const viewport: Viewport = { width: "device-width", initialScale: 1 };
+
+export default function Root({ children }: { children: React.ReactNode }) {
+  return <html lang="en" className={`${body.variable} ${mono.variable}`}><body>{children}</body></html>;
+}
+```
+
+`app/api/healthz/route.ts`:
+
+```ts
+export const dynamic = "force-dynamic";
+export const GET = () => Response.json({ ok: true });
+```
+
+`app/page.tsx`:
+
+```tsx
+import { redirect } from "next/navigation";
+import { sessionUser } from "@/lib/auth";
+export default async function Home() { redirect((await sessionUser()) ? "/app" : "/login"); }
+```
+
+`app/app/layout.tsx` (rail content arrives in Task 11; the shell must render now):
+
+```tsx
+export default function Console({ children }: { children: React.ReactNode }) {
+  return <div className="shell">
+    <aside className="rail" aria-label="Previous analyses">qAI</aside>
+    <main className="main">{children}</main>
+  </div>;
+}
+```
+
+`app/app/page.tsx`: an `<h1>New analysis</h1>` — replaced in Task 11.
+
+- [ ] **Step 5: Verify + commit**
+
+`npm run build && (npm run start & sleep 6; curl -s localhost:3000/api/healthz; kill %1)` → `{"ok":true}`.
+Create `.hallmark/log.json`:
+
+```json
+[{ "date": "2026-09-21", "macrostructure": "Workbench", "theme": "Terminal", "enrichment": "none", "brief": "SQL Server qAI · plan triage console" }]
+```
+
+`.env.example`: `APP_SECRET=` and `DATA_DIR=/data`. Add `data/` and `.hallmark/` to `.gitignore` only if the repo already ignores build junk. Commit `feat: tokens, shell, healthz`.
+
+---
+
+### Task 2: Database layer
+
+**Files:** create `lib/db.ts`, `tests/db.test.ts`.
+
+**Interfaces — produces:** `db` (`DatabaseSync`) · `createUser(email, passHash): string` · `userByEmail(email): { id, pass } | null` · `userEmail(id): { email } | null` · `putSession(tokenHash, userId, expiresAt): void` · `sessionUserId(tokenHash): string | null` · `dropSession(tokenHash): void` · `getSettings(userId): SettingsRow | null` · `saveSettings(userId, SettingsInput): void` · `newAnalysis(userId, title, xml): string` · `patchAnalysis(id, Record<string,string>): void` · `listAnalyses(userId): { id, title, status, created_at }[]` · `getAnalysis(id, userId): Analysis | null` · `renameAnalysis(id, userId, title): void` · `deleteAnalysis(id, userId): void` · types `SettingsInput`, `Analysis`.
+
+- [ ] **Step 1: Write the failing test** — `DATA_DIR` must be set before `lib/db.ts` is imported; the module opens the file at import time.
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+
+process.env.DATA_DIR = mkdtempSync(`${tmpdir()}/qai-`);
+const q = await import("../lib/db.ts");
+
+test("user, settings upsert, analysis lifecycle", () => {
+  const id = q.createUser("a@b.c", "salt:hash");
+  assert.equal(q.userByEmail("a@b.c")?.id, id);
+  assert.equal(q.userByEmail("nope@x.y"), null);
+  assert.equal(q.userEmail(id)?.email, "a@b.c");
+
+  const s = { analyst_base_url: "http://x/v1", analyst_key: "k1", analyst_model: "m",
+              analyst_extra: "{}", jev_key: "j", jev_model: "jev-latest", onboarded: 1 };
+  q.saveSettings(id, s);
+  q.saveSettings(id, { ...s, analyst_key: "k2" });
+  assert.equal(q.getSettings(id)?.analyst_key, "k2", "upsert not insert");
+
+  const aid = q.newAnalysis(id, "Orders scan", "<xml/>");
+  q.patchAnalysis(aid, { status: "done", oul: "root = Report([])", digest: "{}" });
+  assert.equal(q.listAnalyses(id)[0].title, "Orders scan");
+  assert.equal(q.getAnalysis(aid, id)?.status, "done");
+  q.renameAnalysis(aid, id, "Renamed");
+  assert.equal(q.getAnalysis(aid, id)?.title, "Renamed");
+  q.deleteAnalysis(aid, id);
+  assert.equal(q.getAnalysis(aid, id), null);
+});
+
+test("session resolves only while unexpired", () => {
+  const id = q.createUser("s@b.c", "h");
+  q.putSession("tok", id, Date.now() + 1000);
+  assert.equal(q.sessionUserId("tok"), id);
+  q.putSession("old", id, Date.now() - 1);
+  assert.equal(q.sessionUserId("old"), null);
+  q.dropSession("tok");
+  assert.equal(q.sessionUserId("tok"), null);
+});
+```
+
+- [ ] **Step 2: Run it** — `npm run test` → cannot find module `../lib/db.ts`.
+
+- [ ] **Step 3: Implement `lib/db.ts`**
+
+```ts
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+
+const dir = process.env.DATA_DIR ?? "data";
+mkdirSync(dir, { recursive: true });
+
+const g = globalThis as { __qaiDb?: DatabaseSync };
+export const db = (g.__qaiDb ??= (() => {
+  const d = new DatabaseSync(`${dir}/qai.db`);
+  d.exec(`
+    PRAGMA journal_mode = WAL;
+    CREATE TABLE IF NOT EXISTS users (
+      id TEXT PRIMARY KEY, email TEXT NOT NULL UNIQUE, pass TEXT NOT NULL, created_at INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS sessions (
+      token_hash TEXT PRIMARY KEY, user_id TEXT NOT NULL, created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS settings (
+      user_id TEXT PRIMARY KEY, analyst_base_url TEXT NOT NULL DEFAULT '', analyst_key TEXT NOT NULL DEFAULT '',
+      analyst_model TEXT NOT NULL DEFAULT '', analyst_extra TEXT NOT NULL DEFAULT '{}',
+      jev_key TEXT NOT NULL DEFAULT '', jev_model TEXT NOT NULL DEFAULT 'jev-latest',
+      onboarded INTEGER NOT NULL DEFAULT 0, updated_at INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS analyses (
+      id TEXT PRIMARY KEY, user_id TEXT NOT NULL, title TEXT NOT NULL, xml TEXT NOT NULL,
+      digest TEXT, candidates TEXT, verdict TEXT, oul TEXT,
+      status TEXT NOT NULL DEFAULT 'running', error TEXT,
+      created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL);
+    CREATE INDEX IF NOT EXISTS ix_analyses_user ON analyses(user_id, created_at DESC);`);
+  return d;
+})());
+
+const now = () => Date.now();
+const one = <T>(sql: string, ...p: unknown[]): T | null => (db.prepare(sql).get(...p) as T) ?? null;
+// node:sqlite binds null/number/string/bigint/Buffer only: pass 0/1, never booleans.
+
+export type SettingsInput = { analyst_base_url: string; analyst_key: string; analyst_model: string;
+  analyst_extra: string; jev_key: string; jev_model: string; onboarded: number };
+export type Analysis = { id: string; title: string; xml: string; digest: string | null; candidates: string | null;
+  verdict: string | null; oul: string | null; status: string; error: string | null; created_at: number };
+
+export function createUser(email: string, passHash: string): string {
+  const id = randomUUID();
+  db.prepare("INSERT INTO users (id, email, pass, created_at) VALUES (?,?,?,?)").run(id, email, passHash, now());
+  return id;
+}
+export const userByEmail = (email: string) =>
+  one<{ id: string; pass: string }>("SELECT id, pass FROM users WHERE email = ?", email);
+export const userEmail = (id: string) => one<{ email: string }>("SELECT email FROM users WHERE id = ?", id);
+
+export function putSession(tokenHash: string, userId: string, expiresAt: number) {
+  db.prepare("INSERT INTO sessions (token_hash, user_id, created_at, expires_at) VALUES (?,?,?,?)")
+    .run(tokenHash, userId, now(), expiresAt);
+}
+export function sessionUserId(tokenHash: string): string | null {
+  return one<{ user_id: string }>("SELECT user_id FROM sessions WHERE token_hash = ? AND expires_at > ?",
+    tokenHash, now())?.user_id ?? null;
+}
+export const dropSession = (tokenHash: string) =>
+  db.prepare("DELETE FROM sessions WHERE token_hash = ?").run(tokenHash);
+
+export const getSettings = (userId: string) =>
+  one<SettingsInput & { onboarded: number }>("SELECT * FROM settings WHERE user_id = ?", userId);
+
+export function saveSettings(userId: string, s: SettingsInput) {
+  db.prepare(`INSERT INTO settings (user_id, analyst_base_url, analyst_key, analyst_model, analyst_extra,
+      jev_key, jev_model, onboarded, updated_at) VALUES (?,?,?,?,?,?,?,?,?)
+    ON CONFLICT(user_id) DO UPDATE SET analyst_base_url=excluded.analyst_base_url, analyst_key=excluded.analyst_key,
+      analyst_model=excluded.analyst_model, analyst_extra=excluded.analyst_extra, jev_key=excluded.jev_key,
+      jev_model=excluded.jev_model, onboarded=excluded.onboarded, updated_at=excluded.updated_at`)
+    .run(userId, s.analyst_base_url, s.analyst_key, s.analyst_model, s.analyst_extra, s.jev_key, s.jev_model,
+         s.onboarded, now());
+}
+
+export function newAnalysis(userId: string, title: string, xml: string): string {
+  const id = randomUUID();
+  db.prepare("INSERT INTO analyses (id, user_id, title, xml, status, created_at, updated_at) VALUES (?,?,?,?,?,?,?)")
+    .run(id, userId, title, xml, "running", now(), now());
+  return id;
+}
+export function patchAnalysis(id: string, p: Record<string, string>) {
+  const keys = Object.keys(p);
+  if (!keys.length) return;
+  db.prepare(`UPDATE analyses SET ${keys.map((k) => `${k} = ?`).join(", ")}, updated_at = ? WHERE id = ?`)
+    .run(...keys.map((k) => p[k]), now(), id);
+}
+export const listAnalyses = (userId: string) =>
+  db.prepare("SELECT id, title, status, created_at FROM analyses WHERE user_id = ? ORDER BY created_at DESC")
+    .all(userId) as { id: string; title: string; status: string; created_at: number }[];
+export const getAnalysis = (id: string, userId: string) =>
+  one<Analysis>("SELECT * FROM analyses WHERE id = ? AND user_id = ?", id, userId);
+export const renameAnalysis = (id: string, userId: string, title: string) =>
+  db.prepare("UPDATE analyses SET title = ?, updated_at = ? WHERE id = ? AND user_id = ?").run(title, now(), id, userId);
+export const deleteAnalysis = (id: string, userId: string) =>
+  db.prepare("DELETE FROM analyses WHERE id = ? AND user_id = ?").run(id, userId);
+```
+
+- [ ] **Step 4: Run tests, commit** — `npm run test` → 2 pass. Commit `feat: sqlite layer via node:sqlite`.
+
+---
+
+### Task 3: Auth — signup, login, db-backed sessions
+
+**Files:** create `lib/auth.ts`, `tests/auth.test.ts`, `lib/actions.ts`, `app/(auth)/layout.tsx`, `app/(auth)/login/page.tsx`, `app/(auth)/signup/page.tsx`, `components/auth-form.tsx`.
+
+**Interfaces — consumes** Task 2 queries. **Produces:** `hashPassword(pw): string` · `verifyPassword(pw, stored): boolean` · `hashToken(t): string` · `emailOk(e)` · `passwordOk(p)` · `SESSION_COOKIE = "qai_s"` · `SESSION_DAYS = 30` · `startSession(userId)` · `endSession()` · `sessionUser(): { id, email } | null` · `requireUser(): { id, email }` (redirects to `/login`) · `signUpNewUser(email, password): { ok: true; id } | { ok: false; error }` · server actions `signUp`, `signIn`, `signOut` in `lib/actions.ts`.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+process.env.DATA_DIR = mkdtempSync(`${tmpdir()}/qai-auth-`);
+const { hashPassword, verifyPassword, hashToken } = await import("../lib/auth.ts");
+
+test("password hash round-trips and rejects", () => {
+  const h = hashPassword("correct horse battery staple");
+  assert.ok(h.includes(":"), "salt:hash shape");
+  assert.ok(verifyPassword("correct horse battery staple", h));
+  assert.ok(!verifyPassword("wrong", h));
+});
+test("malformed stored hash never verifies", () => {
+  for (const bad of ["", "nosep", "a:", ":b", "zz:zz"]) assert.ok(!verifyPassword("x", bad));
+});
+test("token hash is stable, 64 hex", () => {
+  assert.equal(hashToken("abc"), hashToken("abc"));
+  assert.match(hashToken("abc"), /^[0-9a-f]{64}$/);
+});
+```
+
+- [ ] **Step 2: Run it** — module not found.
+
+- [ ] **Step 3: Implement `lib/auth.ts`**
+
+```ts
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+import { randomBytes, scryptSync, createHash, timingSafeEqual } from "node:crypto";
+import { createUser, userByEmail, userEmail, putSession, sessionUserId, dropSession, getSettings } from "@/lib/db";
+
+export const SESSION_COOKIE = "qai_s";
+export const SESSION_DAYS = 30;
+export const emailOk = (e: string) => /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/.test(e);
+export const passwordOk = (p: string) => p.length >= 10;   // trust boundary: signup + password change only
+
+export function hashPassword(pw: string): string {
+  const salt = randomBytes(16);
+  return `${salt.toString("hex")}:${scryptSync(pw, salt, 64).toString("hex")}`;
+}
+export function verifyPassword(pw: string, stored: string): boolean {
+  const [salt, hash] = stored.split(":");
+  if (!salt || !hash) return false;
+  try {
+    const a = scryptSync(pw, Buffer.from(salt, "hex"), 64);
+    const b = Buffer.from(hash, "hex");
+    return a.length === b.length && timingSafeEqual(a, b);
+  } catch { return false; }
+}
+export const hashToken = (t: string) => createHash("sha256").update(t).digest("hex");
+
+export function signUpNewUser(email: string, password: string): { ok: true; id: string } | { ok: false; error: string } {
+  const e = email.trim().toLowerCase();
+  if (!emailOk(e)) return { ok: false, error: "Enter a valid email address." };
+  if (!passwordOk(password)) return { ok: false, error: "Use at least 10 characters." };
+  if (userByEmail(e)) return { ok: false, error: "That email already has an account." };
+  // ponytail: no rate limiting — single-container tool. Add a token bucket before exposing this to a network.
+  return { ok: true, id: createUser(e, hashPassword(password)) };
+}
+
+export async function startSession(userId: string) {
+  const token = randomBytes(32).toString("hex");
+  putSession(hashToken(token), userId, Date.now() + SESSION_DAYS * 864e5);
+  (await cookies()).set(SESSION_COOKIE, token, {
+    httpOnly: true, sameSite: "lax", secure: process.env.NODE_ENV === "production",
+    path: "/", maxAge: SESSION_DAYS * 86400 });
+}
+export async function endSession() {
+  const store = await cookies();
+  const t = store.get(SESSION_COOKIE)?.value;
+  if (t) dropSession(hashToken(t));
+  store.delete(SESSION_COOKIE);
+}
+export async function sessionUser(): Promise<{ id: string; email: string } | null> {
+  const t = (await cookies()).get(SESSION_COOKIE)?.value;
+  if (!t) return null;
+  const id = sessionUserId(hashToken(t));
+  if (!id) return null;
+  const row = userEmail(id);
+  return row ? { id, email: row.email } : null;
+}
+export async function requireUser() {
+  const u = await sessionUser();
+  if (!u) redirect("/login");
+  return u;
+}
+export const needsOnboarding = (userId: string) => getSettings(userId)?.onboarded !== 1;
+```
+
+The cookie stores a random token; the DB stores only its SHA-256, so a DB dump does not hand out live sessions.
+
+- [ ] **Step 4: Server actions + pages**
+
+`lib/actions.ts`:
+
+```ts
+"use server";
+import { redirect } from "next/navigation";
+import { revalidatePath } from "next/cache";
+import { userByEmail, getSettings, renameAnalysis, deleteAnalysis } from "@/lib/db";
+import { signUpNewUser, verifyPassword, startSession, endSession, requireUser, emailOk } from "@/lib/auth";
+
+export async function signUp(_: void, fd: FormData) {
+  const r = signUpNewUser(String(fd.get("email") ?? ""), String(fd.get("password") ?? ""));
+  if (!r.ok) return r;
+  await startSession(r.id);
+  redirect("/setup");
+}
+export async function signIn(_: void, fd: FormData) {
+  const e = String(fd.get("email") ?? "").trim().toLowerCase();
+  const u = emailOk(e) ? userByEmail(e) : null;
+  if (!u || !verifyPassword(String(fd.get("password") ?? ""), u.pass))
+    return { ok: false, error: "Email or password is wrong." };
+  await startSession(u.id);
+  redirect(getSettings(u.id)?.onboarded === 1 ? "/app" : "/setup");
+}
+export async function signOut() { await endSession(); redirect("/login"); }
+
+export async function rename(_: void, fd: FormData) {
+  const u = await requireUser();
+  const id = String(fd.get("id") ?? "");
+  const title = String(fd.get("title") ?? "").trim().slice(0, 120);
+  if (id && title) renameAnalysis(id, u.id, title);
+  revalidatePath("/app");
+}
+export async function remove(_: void, fd: FormData) {
+  const u = await requireUser();
+  deleteAnalysis(String(fd.get("id") ?? ""), u.id);
+  revalidatePath("/app");
+}
+```
+
+`components/auth-form.tsx` — visible labels, inline error, pending state:
+
+```tsx
+"use client";
+import { useActionState } from "react";
+
+export function AuthForm({ action, submit, fields }: {
+  action: (_: void, fd: FormData) => Promise<{ ok?: boolean; error?: string } | never>;
+  submit: string;
+  fields: { name: string; label: string; type: string; autoComplete?: string; help?: string }[];
+}) {
+  const [state, formAction, pending] = useActionState(action, null);
+  return <form action={formAction} className="card" style={{ display: "grid", gap: "var(--qai-space-md)" }}>
+    {fields.map((f) => <div key={f.name} style={{ display: "grid", gap: "var(--qai-space-xs)" }}>
+      <label className="label" htmlFor={f.name}>{f.label}</label>
+      <input className="field" id={f.name} name={f.name} type={f.type} autoComplete={f.autoComplete} required />
+      {f.help && <span style={{ fontSize: "var(--qai-text-xs)", color: "var(--qai-ink-muted)" }}>{f.help}</span>}
+    </div>)}
+    {state && !state.ok && <p role="alert" style={{ color: "var(--qai-danger)" }}>{state.error}</p>}
+    <button className="btn btn-primary" disabled={pending}>{submit}</button>
+  </form>;
+}
+```
+
+`app/(auth)/layout.tsx`:
+
+```tsx
+export default function Auth({ children }: { children: React.ReactNode }) {
+  return <div style={{ maxWidth: 420, margin: "0 auto", padding: "var(--qai-space-3xl) var(--qai-space-l)" }}>
+    <p className="label">SQL Server qAI</p>{children}
+    <p className="colophon">ShowPlan XML in · Jev-ranked remediation out · self-hosted</p>
+  </div>;
+}
+```
+
+`app/(auth)/login/page.tsx`:
+
+```tsx
+import { signIn } from "@/lib/actions";
+import { AuthForm } from "@/components/auth-form";
+export default function Login() {
+  return <>
+    <h1 style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-2xl)" }}>Sign in</h1>
+    <AuthForm action={signIn} submit="Sign in" fields={[
+      { name: "email", label: "Email", type: "email", autoComplete: "email" },
+      { name: "password", label: "Password", type: "password", autoComplete: "current-password" }]} />
+    <p><a href="/signup">Create an account</a></p>
+  </>;
+}
+```
+
+`app/(auth)/signup/page.tsx` — same shape, `action={signUp}`, `submit="Create account"`, password field `autoComplete="new-password"` and `help: "10 characters minimum."`, link to `/login`.
+
+- [ ] **Step 5: Verify + commit**
+
+`npm run test` passes; `npm run build` clean. Manual: `/signup` → lands on `/setup`; wrong password → inline alert, no redirect; sign out → cookie gone; `/app` while signed out → `/login`. Commit `feat: email+password auth with db-backed sessions`.
+
+---
+
+### Task 4: Credential vault + settings store
+
+**Files:** create `lib/vault.ts`, `lib/settings.ts`, `tests/vault.test.ts`.
+
+**Interfaces — produces:** `seal(plain): string` · `open(sealed): string` (`""` on any malformed input) · `mask(secret): string` · `AnalystConfig = { baseUrl, apiKey, model, extra }` · `saveSettingsForm(userId, fd, onboarded = 1)` (blank secret field keeps the stored key) · `analystConfig(userId): AnalystConfig | null` · `jevKey(userId): string` · `jevModel(userId): string` · `settingsView(userId)` returning masked/ready flags only — never a raw key.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+process.env.APP_SECRET = "unit-test-secret-value";
+process.env.DATA_DIR = mkdtempSync(`${tmpdir()}/qai-vault-`);
+const { seal, open, mask } = await import("../lib/vault.ts");
+const db = await import("../lib/db.ts");
+const { saveSettingsForm, analystConfig, settingsView, jevKey } = await import("../lib/settings.ts");
+
+test("seal/open round-trips; junk and tamper yield empty", () => {
+  assert.equal(open(seal("sk-abc123")), "sk-abc123");
+  assert.equal(open("deadbeef.00.zzz"), "");
+  assert.equal(open(""), "");
+  assert.equal(mask("sk-abcdefgh1234"), "••••1234");
+  assert.equal(mask(""), "");
+});
+
+test("blank secret keeps the stored key", () => {
+  const u = db.createUser("v@x.y", "h");
+  const fd = (o: Record<string, string>) => { const f = new FormData();
+    Object.entries(o).forEach(([k, v]) => f.set(k, v)); return f; };
+  saveSettingsForm(u, fd({ analyst_base_url: "https://api/x/v1/", analyst_key: "sk-1111", analyst_model: "gpt",
+    analyst_extra: '{"temperature":0.2}', jev_key: "ts-1", jev_model: "jev-latest" }));
+  assert.equal(analystConfig(u)?.apiKey, "sk-1111");
+
+  saveSettingsForm(u, fd({ analyst_base_url: "https://api/y/v1", analyst_key: "", analyst_model: "gpt",
+    analyst_extra: "not json", jev_key: "", jev_model: "" }));
+  const c = analystConfig(u)!;
+  assert.equal(c.baseUrl, "https://api/y/v1", "trailing slash trimmed");
+  assert.equal(c.apiKey, "sk-1111", "blank must not wipe the key");
+  assert.deepEqual(c.extra, {}, "bad JSON falls back to empty params");
+  assert.equal(jevKey(u), "ts-1");
+  assert.equal(settingsView(u).has_analyst, true);
+  assert.equal(settingsView(u).analyst_key_masked, "••••1111");
+  assert.equal((settingsView(u) as Record<string, unknown>).analyst_key, undefined, "no raw key to the client");
+});
+```
+
+- [ ] **Step 2: Run it** — module not found.
+
+- [ ] **Step 3: Implement**
+
+`lib/vault.ts`:
+
+```ts
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:crypto";
+
+function key() {
+  const s = process.env.APP_SECRET;
+  if (!s || s.length < 16) throw new Error("APP_SECRET is missing or shorter than 16 chars — set it in .env");
+  return scryptSync(s, "qai-vault-v1", 32);
+}
+export function seal(plain: string): string {
+  if (!plain) return "";
+  const iv = randomBytes(12);
+  const c = createCipheriv("aes-256-gcm", key(), iv);
+  const ct = Buffer.concat([c.update(plain, "utf8"), c.final()]);
+  return `${iv.toString("hex")}.${c.getAuthTag().toString("hex")}.${ct.toString("hex")}`;
+}
+export function open(sealed: string): string {
+  if (!sealed) return "";
+  try {
+    const [iv, tag, ct] = sealed.split(".");
+    const d = createDecipheriv("aes-256-gcm", key(), Buffer.from(iv, "hex"), { authTagLength: 16 });
+    d.setAuthTag(Buffer.from(tag, "hex"));
+    return Buffer.concat([d.update(Buffer.from(ct, "hex")), d.final()]).toString("utf8");
+  } catch { return ""; }
+}
+export const mask = (v: string) => (v ? `••••${v.slice(-4)}` : "");
+```
+
+`lib/settings.ts`:
+
+```ts
+import { getSettings, saveSettings, type SettingsInput } from "@/lib/db";
+import { seal, open, mask } from "@/lib/vault";
+
+export type AnalystConfig = { baseUrl: string; apiKey: string; model: string; extra: Record<string, unknown> };
+const str = (fd: FormData, k: string) => String(fd.get(k) ?? "").trim();
+const kept = (fd: FormData, k: string, existing: string) => { const v = str(fd, k); return v ? seal(v) : existing; };
+
+export function saveSettingsForm(userId: string, fd: FormData, onboarded = 1) {
+  const cur = getSettings(userId);
+  let extra = str(fd, "analyst_extra") || "{}";
+  try { JSON.parse(extra); } catch { extra = "{}"; }
+  saveSettings(userId, {
+    analyst_base_url: str(fd, "analyst_base_url").replace(/\/+$/, ""),
+    analyst_key: kept(fd, "analyst_key", cur?.analyst_key ?? ""),
+    analyst_model: str(fd, "analyst_model"),
+    analyst_extra: extra,
+    jev_key: kept(fd, "jev_key", cur?.jev_key ?? ""),
+    jev_model: str(fd, "jev_model") || "jev-latest",
+    onboarded: cur?.onboarded === 1 ? 1 : onboarded,
+  } satisfies SettingsInput);
+}
+export function analystConfig(userId: string): AnalystConfig | null {
+  const s = getSettings(userId);
+  const baseUrl = s?.analyst_base_url ?? "";
+  const apiKey = open(s?.analyst_key ?? "");
+  const model = s?.analyst_model ?? "";
+  if (!baseUrl || !apiKey || !model) return null;
+  let extra: Record<string, unknown> = {};
+  try { extra = JSON.parse(s!.analyst_extra) as Record<string, unknown>; } catch { /* bad JSON means no extra params */ }
+  return { baseUrl, apiKey, model, extra };
+}
+export const jevKey = (userId: string) => open(getSettings(userId)?.jev_key ?? "");
+export const jevModel = (userId: string) => getSettings(userId)?.jev_model || "jev-latest";
+export function settingsView(userId: string) {
+  const s = getSettings(userId);
+  const analystKey = open(s?.analyst_key ?? "");
+  const jev = open(s?.jev_key ?? "");
+  return {
+    analyst_base_url: s?.analyst_base_url ?? "", analyst_model: s?.analyst_model ?? "",
+    analyst_extra: s?.analyst_extra ?? "{}", jev_model: s?.jev_model ?? "jev-latest",
+    analyst_key_masked: mask(analystKey), jev_key_masked: mask(jev),
+    has_analyst: !!(s?.analyst_base_url && s?.analyst_model && analystKey), has_jev: !!jev,
+  };
+}
+export type SettingsView = ReturnType<typeof settingsView>;
+```
+
+- [ ] **Step 4: Run tests, commit** — commit `feat: encrypted credential vault`.
+
+---
+
+### Task 5: First-run guide + settings page
+
+**Files:** create `components/settings-form.tsx`, `app/setup/page.tsx`, `app/settings/page.tsx`; modify `lib/actions.ts`.
+
+**Interfaces — consumes** `saveSettingsForm`, `settingsView`, `SettingsView`, `requireUser`, `getSettings`, `listAnalyses`. **Produces** `saveSettingsAction(_: void, fd): { ok: boolean; error?: string }`.
+
+- [ ] **Step 1: Shared form** — `components/settings-form.tsx`. One form, two hosts (wizard + settings). Visible labels, helper text under each field, error beside the field, never a placeholder-as-label:
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import type { SettingsView } from "@/lib/settings";
+
+export function SettingsForm({ action, view, step, account }: {
+  action: (_: void, fd: FormData) => Promise<{ ok?: boolean; error?: string }>;
+  view: SettingsView; step?: string; account?: boolean;
+}) {
+  const [state, formAction, pending] = useActionState(action, null);
+  const F = (name: string, label: string, value: string, help: string, type = "text") => (
+    <div key={name} style={{ display: "grid", gap: "var(--qai-space-xs)" }}>
+      <label className="label" htmlFor={name}>{label}</label>
+      <input className="field" id={name} name={name} type={type} defaultValue={value} />
+      <span style={{ fontSize: "var(--qai-text-xs)", color: "var(--qai-ink-muted)" }}>{help}</span>
+    </div>);
+  const Group = ({ title, children }: { title: string; children: React.ReactNode }) => (
+    <fieldset style={{ border: 0, padding: 0, margin: 0, display: "grid", gap: "var(--qai-space-md)" }}>
+      <legend className="label">{title}</legend>{children}</fieldset>);
+  return <form action={formAction} className="card" style={{ display: "grid", gap: "var(--qai-space-l)" }}>
+    {step && <p className="label">{step}</p>}
+    <Group title="Analyst model — OpenAI-compatible">
+      {F("analyst_base_url", "Base URL", view.analyst_base_url, "e.g. https://api.openai.com/v1")}
+      {F("analyst_key", "API key", "", view.has_analyst
+        ? `Saved ${view.analyst_key_masked} — leave blank to keep it` : "Encrypted with APP_SECRET before it hits disk")}
+      {F("analyst_model", "Model name", view.analyst_model, "e.g. gpt-4o-mini, llama-3.3-70b")}
+      {F("analyst_extra", "Extra params (JSON)", view.analyst_extra, 'Merged into the request body, e.g. {"temperature":0.2}')}
+    </Group>
+    <Group title="Jev — TypeSafe System One">
+      {F("jev_key", "TypeSafe API key", "", view.has_jev
+        ? `Saved ${view.jev_key_masked} — leave blank to keep it` : "console.typesafe.ai/keys")}
+      {F("jev_model", "Jev model", view.jev_model, "jev-latest unless you know better")}
+    </Group>
+    {account && <Group title="Account">
+      {F("email", "Email", "", "Used to sign in", "email")}
+      {F("password", "New password", "", "Leave blank to keep the current one", "password")}
+    </Group>}
+    {state && !state.ok && <p role="alert" style={{ color: "var(--qai-danger)" }}>{state.error}</p>}
+    {state?.ok && <p role="status" style={{ color: "var(--qai-accent)" }}>Saved.</p>}
+    <button className="btn btn-primary" disabled={pending}>Save</button>
+  </form>;
+}
+```
+
+- [ ] **Step 2: Action + pages**
+
+`lib/actions.ts` addition:
+
+```ts
+import { saveSettingsForm } from "@/lib/settings";
+import { db } from "@/lib/db";
+import { hashPassword } from "@/lib/auth";
+
+export async function saveSettingsAction(_: void, fd: FormData) {
+  const u = await requireUser();
+  const email = String(fd.get("email") ?? "").trim().toLowerCase();
+  const password = String(fd.get("password") ?? "");
+  if (email && !emailOk(email)) return { ok: false, error: "Enter a valid email address." };
+  if (password && password.length < 10) return { ok: false, error: "Use at least 10 characters." };
+  saveSettingsForm(u.id, fd);
+  if (password) db.prepare("UPDATE users SET pass = ? WHERE id = ?").run(hashPassword(password), u.id);
+  if (email) db.prepare("UPDATE users SET email = ? WHERE id = ?").run(email, u.id);
+  revalidatePath("/settings");
+  return { ok: true };
+}
+```
+
+`app/setup/page.tsx` — 3 steps, `?step=2` deep links, visible "Step 2 of 3" (ui-ux-pro-max: multi-step needs progress):
+
+```tsx
+import { redirect } from "next/navigation";
+import { requireUser } from "@/lib/auth";
+import { settingsView } from "@/lib/settings";
+import { getSettings } from "@/lib/db";
+import { saveSettingsAction } from "@/lib/actions";
+import { SettingsForm } from "@/components/settings-form";
+
+const TITLES = { 1: "Paste a plan. Get a ranked fix.", 2: "Say which models to ask.", 3: "Ready." } as const;
+
+export default async function Setup({ searchParams }: { searchParams: Promise<{ step?: string }> }) {
+  const u = await requireUser();
+  const n = (["1", "2", "3"].includes((await searchParams).step ?? "") ? (await searchParams).step! : "1") as "1" | "2" | "3";
+  const view = settingsView(u.id);
+  if (getSettings(u.id)?.onboarded === 1 && view.has_analyst && view.has_jev) redirect("/app");
+  return <main style={{ maxWidth: 560, margin: "0 auto", padding: "var(--qai-space-3xl) var(--qai-space-l)",
+                        display: "grid", gap: "var(--qai-space-xl)" }}>
+    <p className="label">Step {n} of 3</p>
+    <h1 style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-display)", letterSpacing: "-0.02em" }}>
+      {TITLES[n]}</h1>
+    {n === "1" && <p>qAI reads a SQL Server ShowPlan XML, works out the bottleneck in code, asks your model for several ways to fix it, then has Jev score each one. You configure nothing on this screen.</p>}
+    {n === "2" && <SettingsForm action={saveSettingsAction} view={view} step="Analyst model and Jev key" />}
+    {n === "3" && <>
+      <p>One run = one digest, a few model calls, four Jev questions per option. If the analyst or Jev is unreachable, the report says so instead of inventing a verdict.</p>
+      <p className="label">Analyst {view.has_analyst ? "ready" : "missing"} · Jev {view.has_jev ? "ready" : "missing"}</p>
+      <a className="btn btn-primary" href="/app" style={{ justifySelf: "start", textDecoration: "none" }}>Go</a>
+    </>}
+    <p className="colophon">Keys stay in this container, encrypted with APP_SECRET · <a href="/settings">settings</a></p>
+    {n !== "3" && <a className="btn" href={`/setup?step=${Number(n) + 1}`}
+                     style={{ justifySelf: "start", textDecoration: "none" }}>Next</a>}
+  </main>;
+}
+```
+
+`app/settings/page.tsx`:
+
+```tsx
+```tsx
+import { requireUser } from "@/lib/auth";
+import { settingsView } from "@/lib/settings";
+import { listAnalyses } from "@/lib/db";
+import { saveSettingsAction, signOut } from "@/lib/actions";
+import { SettingsForm } from "@/components/settings-form";
+
+export default async function Settings() {
+  const u = await requireUser();
+  const rows = listAnalyses(u.id);
+  return <main className="main" style={{ maxWidth: 640, margin: "0 auto" }}>
+    <h1 style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-2xl)" }}>Settings</h1>
+    <SettingsForm action={saveSettingsAction} view={settingsView(u.id)} account />
+    <section className="card">
+      <p className="label">History · {rows.length}</p>
+      <p style={{ fontSize: "var(--qai-text-sm)" }}>Rename or delete individual runs from the left rail. Nothing here deletes them in bulk — that is on purpose.</p>
+    </section>
+    <form action={signOut}><button className="btn">Sign out</button></form>
+  </main>;
+}
+```
+
+- [ ] **Step 3: Verify + commit**
+
+`npm run build`. Manual: fresh signup lands on `/setup` step 1 → step 2 saves both models → step 3 `Go` → `/app`. Reload `/settings`: keys show as `••••`, blank fields keep the stored values. Commit `feat: setup wizard + settings`.
+
+---
+
+### Task 6: ShowPlan digest parser
+
+**Files:** create `lib/digest.ts`, `tests/digest.test.ts`.
+
+**Interfaces — consumes** nothing. **Produces:** `class PlanError` · `MAX_XML_BYTES = 12_000_000` ·
+`type Operator = { id: string; op: string; cost: number; estRows: number; actualRows: number | null; execs: number | null; io: number | null; cpu: number | null; spillLevels: number | null; parallel: boolean }` ·
+`type RowGuess = { id: string; op: string; est: number; actual: number; ratio: number }` ·
+`type MissingIndex = { table: string; equality: string[]; inequality: string[]; included: string[]; impact: number }` ·
+`type Wait = { type: string; ms: number }` ·
+`type Digest = { sql: string; bytes: number; subtreeCost: number | null; parallel: boolean; nonParallelReason: string | null; earlyAbort: string | null; tables: string[]; topOperators: Operator[]; rowGuessErrors: RowGuess[]; missingIndexes: MissingIndex[]; warnings: string[]; waits: Wait[] }` ·
+`digestPlan(xml: string): Digest` · `digestForModel(d: Digest): object` — the only shape any model or Jev ever sees.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+const { digestPlan, PlanError, digestForModel } = await import("../lib/digest.ts");
+
+const PLAN = `<?xml version="1.0" encoding="utf-16"?>
+<ShowPlanXML xmlns="http://schemas.microsoft.com/sqlserver/2004/07/showplan" Version="1.6" Build="16.0.4085.2">
+ <BatchSequence><Batch><Statements>
+  <StmtSimple StatementId="1" StatementSubtreeCost="4.871" StatementOptmLevel="FULL"
+              StatementText="SELECT o.Id FROM Sales.Orders o WHERE o.CustomerId = @c1 AND o.Total &gt; 500">
+   <StatementOptmEarlyAbortReason>GoodEnoughPlanFound</StatementOptmEarlyAbortReason>
+   <QueryBlock QueryHash="0x1A" QueryPlanHash="0x2B">
+    <RelOp NodeId="0" PhysicalOp="Clustered Index Scan" LogicalOp="Clustered Index Scan" EstimateRows="1000"
+           EstimateIO="41.6" EstimateCPU="39.0" EstimatedTotalSubtreeCost="4.10" Parallel="false">
+      <RunTimeInformation><RunTimeCountersPerThread Thread="0" ActualRows="1243500" ActualExecs="1"
+        ActualElapsedms="2411" ActualCPUms="2210"/></RunTimeInformation>
+      <IndexScan Database="[wide]" Schema="[Sales]" Table="[Orders]"/>
+      <Warnings><NoJoinPredicate/><SpillToTempDb SpillLevel="2"/>
+        <WaitTime WaitType="PAGEIOLATCH_SH" WaitTime="812"/></Warnings>
+    </RelOp>
+    <RelOp NodeId="1" PhysicalOp="Index Seek" LogicalOp="Index Seek" EstimateRows="3"
+           EstimateIO="0.7" EstimateCPU="0.02" EstimatedTotalSubtreeCost="0.77" Parallel="true">
+      <RunTimeInformation><RunTimeCountersPerThread Thread="0" ActualRows="4" ActualExecs="2"/></RunTimeInformation>
+      <IndexScan Database="[wide]" Schema="[Sales]" Table="[Customer]"/>
+    </RelOp>
+    <MissingIndexes><MissingIndexGroup Impact="94.17">
+      <MissingIndex Database="[wide]" Schema="[Sales]" Table="[Orders]">
+        <ColumnGroup Usage="EQUALITY"><Column Name="[CustomerId]"/></ColumnGroup>
+        <ColumnGroup Usage="INEQUALITY"><Column Name="[Total]"/></ColumnGroup>
+        <IncludedColumns><Column Name="[Id]"/></IncludedColumns>
+      </MissingIndex></MissingIndexGroup></MissingIndexes>
+    <NonParallelPlanReason>Could Not Generate Valid Parallel Plan</NonParallelPlanReason>
+   </QueryBlock>
+  </StmtSimple>
+ </Statements></Batch></BatchSequence>
+</ShowPlanXML>`;
+
+test("digests what matters in a showplan", () => {
+  const d = digestPlan(PLAN);
+  assert.match(d.sql, /o\.Total > 500/, "XML entities decoded");
+  assert.equal(d.subtreeCost, 4.871);
+  assert.equal(d.earlyAbort, "GoodEnoughPlanFound");
+  assert.equal(d.nonParallelReason, "Could Not Generate Valid Parallel Plan");
+  assert.deepEqual(d.tables, ["wide.Sales.Orders", "wide.Sales.Customer"]);
+  assert.equal(d.topOperators[0].op, "Clustered Index Scan");
+  assert.equal(d.topOperators[0].spillLevels, 2);
+  assert.equal(d.topOperators[0].actualRows, 1243500);
+  assert.equal(d.topOperators[0].parallel, false);
+  assert.deepEqual(d.missingIndexes[0], { table: "wide.Sales.Orders", equality: ["CustomerId"],
+    inequality: ["Total"], included: ["Id"], impact: 94.17 });
+  assert.ok(d.warnings.includes("NoJoinPredicate"));
+  assert.ok(d.warnings.some((w) => w.startsWith("SpillToTempDb")));
+  assert.deepEqual(d.waits, [{ type: "PAGEIOLATCH_SH", ms: 812 }]);
+  assert.ok(d.rowGuessErrors[0].ratio > 100);
+  assert.equal(d.bytes, PLAN.length);
+});
+test("a BOM-prefixed plan still digests — SSMS writes .sqlplan as UTF-16 with a BOM", () => {
+  assert.equal(digestPlan("\uFEFF" + PLAN).subtreeCost, 4.871);
+});
+test("rejects input that is not a plan", () => {
+  for (const bad of ["", "SELECT 1", "<html></html>", "<ShowPlanXML><trunc"])
+    assert.throws(() => digestPlan(bad), PlanError);
+});
+test("digestForModel stays bounded on a fat plan", () => {
+  const big = `<ShowPlanXML><Batch><Statements><StmtSimple StatementText="q">` +
+    Array.from({ length: 400 }, (_, i) =>
+      `<RelOp NodeId="${i}" LogicalOp="Scan" EstimateRows="1" EstimatedTotalSubtreeCost="${i}"/>`).join("") +
+    `</StmtSimple></Statements></Batch></Batch></ShowPlanXML>`;
+  const v = digestForModel(digestPlan(big)) as { topOperators: unknown[]; tables: unknown[] };
+  assert.ok(v.topOperators.length <= 12);
+});
+```
+
+- [ ] **Step 2: Run it** — cannot find module `../lib/digest.ts`.
+
+- [ ] **Step 3: Implement `lib/digest.ts`**
+
+```ts
+import { XMLParser } from "fast-xml-parser";
+
+export class PlanError extends Error {}
+export const MAX_XML_BYTES = 12_000_000;
+
+const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "", removeNSPrefix: true });
+
+export type Operator = { id: string; op: string; cost: number; estRows: number; actualRows: number | null;
+  execs: number | null; io: number | null; cpu: number | null; spillLevels: number | null; parallel: boolean };
+export type RowGuess = { id: string; op: string; est: number; actual: number; ratio: number };
+export type MissingIndex = { table: string; equality: string[]; inequality: string[]; included: string[]; impact: number };
+export type Wait = { type: string; ms: number };
+export type Digest = { sql: string; bytes: number; subtreeCost: number | null; parallel: boolean;
+  nonParallelReason: string | null; earlyAbort: string | null; tables: string[]; topOperators: Operator[];
+  rowGuessErrors: RowGuess[]; missingIndexes: MissingIndex[]; warnings: string[]; waits: Wait[] };
+
+function collect(node: any, name: string, out: any[] = []): any[] {
+  if (Array.isArray(node)) { for (const n of node) collect(n, name, out); return out; }
+  if (node && typeof node === "object") for (const [k, v] of Object.entries(node)) {
+    if (k === "#text") continue;
+    if (k === name) (Array.isArray(v) ? v : [v]).forEach((n) => out.push(n));
+    collect(v, name, out);
+  }
+  return out;
+}
+const num = (v: any): number | null =>
+  (v === undefined || v === null || v === "" || Number.isNaN(Number(v)) ? null : Number(v));
+const text = (v: any): string | null =>
+  (typeof v === "object" && v !== null ? (String(v["#text"] ?? "") || null) : (v == null ? null : String(v)));
+const unbrack = (v: any) => String(v ?? "").replace(/[[\]]/g, "");
+const colNames = (node: any) => collect(node, "Column").map((c) => unbrack(c.Name)).filter(Boolean);
+
+export function digestPlan(raw: string): Digest {
+  const xml = raw.replace(/^\uFEFF/, "");        // SSMS writes a BOM; the XML parser does not want it
+  if (!xml || xml.trim().length < 40) throw new PlanError("Empty input. Paste the ShowPlan XML, or drop a .sqlplan file.");
+  if (xml.length > MAX_XML_BYTES)
+    throw new PlanError(`Plan is ${Math.round(xml.length / 1e6)} MB, over the ${MAX_XML_BYTES / 1e6} MB cap.`);
+  let doc: any;
+  try { doc = parser.parse(xml); } catch { throw new PlanError("That XML will not parse — re-export the actual execution plan."); }
+  if (!doc?.ShowPlanXML) throw new PlanError("Not a SQL Server ShowPlan XML document. In SSMS: Results → Save As → .sqlplan, or run the query with ATTNPL.");
+
+  const stmts = collect(doc, "StmtSimple");
+  const stmt = stmts.find((s) => s?.QueryBlock || s?.RelOp) ?? stmts[0] ?? {};
+  const operators: Operator[] = collect(doc, "RelOp").map((o) => {
+    const rt = collect(o, "RunTimeCountersPerThread")[0];
+    return {
+      id: String(o.NodeId ?? o["Node_id"] ?? "?"),
+      op: String(o.LogicalOp ?? o.PhysicalOp ?? "Unknown"),
+      // Real ShowPlan spells these EstimateIO / EstimateCPU; builds differ, so fall through every spelling.
+      cost: num(o.EstimatedOperatorCost) ?? num(o.EstimatedTotalSubtreeCost) ?? num(o.EstimateIO) ?? 0,
+      estRows: num(o.EstimateRows) ?? 0,
+      actualRows: rt ? num(rt.ActualRows) : null,
+      execs: rt ? num(rt.ActualExecs) : null,
+      io: num(o.EstimateIO) ?? num(o.EstimatedIO), cpu: num(o.EstimateCPU) ?? num(o.EstimatedCPU),
+      spillLevels: num(collect(o, "SpillToTempDb")[0]?.SpillLevel),
+      parallel: o.Parallel === "true",
+    };
+  });
+
+  const tables = [...new Set([...collect(doc, "IndexScan"), ...collect(doc, "TableScan")]
+    .map((s) => unbrack(s.Table)).filter(Boolean))];
+
+  const missingIndexes: MissingIndex[] = collect(doc, "MissingIndexGroup").map((g) => {
+    const mi = collect(g, "MissingIndex")[0] ?? {};
+    const byUsage = (u: string) => collect(mi, "ColumnGroup").filter((c) => c.Usage === u).flatMap(colNames);
+    return {
+      table: [mi.Database, mi.Schema, mi.Table].map(unbrack).filter(Boolean).join("."),
+      equality: byUsage("EQUALITY"), inequality: byUsage("INEQUALITY"),
+      included: collect(mi, "IncludedColumns").flatMap(colNames),
+      impact: num(g.Impact) ?? 0,
+    };
+  }).sort((a, b) => b.impact - a.impact);
+
+  // Generic on purpose: SQL Server adds warning elements over time, unknown ones still surface.
+  const warnings = [...new Set(collect(doc, "Warnings").flatMap((w) =>
+    Object.entries(w).filter(([k]) => k !== "#text").map(([k, v]: [string, any]) => {
+      const attrs = v && typeof v === "object"
+        ? Object.entries(v).filter(([, x]) => typeof x !== "object").map(([ak, x]) => `${ak}=${x}`).join(" ")
+        : "";
+      return attrs ? `${k} ${attrs}` : k;
+    })))];
+
+  const waits: Wait[] = collect(doc, "WaitTime")
+    .map((w) => ({ type: String(w.WaitType ?? "unknown"), ms: num(w.WaitTime) ?? 0 }))
+    .filter((w) => w.ms > 0).sort((a, b) => b.ms - a.ms).slice(0, 5);
+
+  const rowGuessErrors: RowGuess[] = operators
+    .filter((o) => o.actualRows !== null && o.estRows > 0)
+    .map((o) => ({ id: o.id, op: o.op, est: o.estRows, actual: o.actualRows as number,
+      ratio: Math.max(o.estRows, o.actualRows as number) / Math.min(o.estRows, o.actualRows as number) }))
+    .filter((r) => r.ratio >= 10).sort((a, b) => b.ratio - a.ratio).slice(0, 5);
+
+  return {
+    sql: text(stmt.StatementText) ?? "", bytes: xml.length,
+    subtreeCost: num(stmt.StatementSubtreeCost), parallel: operators.some((o) => o.parallel),
+    nonParallelReason: text(collect(doc, "NonParallelPlanReason")[0]),
+    earlyAbort: text(collect(doc, "StatementOptmEarlyAbortReason")[0]),
+    tables, topOperators: operators.sort((a, b) => b.cost - a.cost).slice(0, 12),
+    rowGuessErrors, missingIndexes, warnings, waits,
+  };
+}
+
+// Tokens are the constraint: models and Jev read this, never the raw XML.
+export const digestForModel = (d: Digest) => ({
+  sql: d.sql.slice(0, 4000), subtreeCost: d.subtreeCost, parallel: d.parallel,
+  nonParallelReason: d.nonParallelReason, earlyAbort: d.earlyAbort, tables: d.tables.slice(0, 20),
+  topOperators: d.topOperators, rowGuessErrors: d.rowGuessErrors,
+  missingIndexes: d.missingIndexes.slice(0, 5), warnings: d.warnings.slice(0, 20), waits: d.waits,
+});
+```
+
+- [ ] **Step 4: Prove it on a real plan, not just the fixture**
+
+`mkdir -p fixtures`, drop one genuine `.sqlplan` from SSMS in as `fixtures/real.sqlplan`, and add this test. It asserts nothing about specific numbers — only that a real plan yields a non-empty digest. If no real plan is available, leave the test skipped and say so in the commit message:
+
+```ts
+test("a real .sqlplan digests", () => {
+  let xml: string;
+  try { xml = readFileSync("fixtures/real.sqlplan", "utf8"); } catch { return console.log("skip: no fixtures/real.sqlplan"); }
+  const d = digestPlan(xml);
+  assert.ok(d.topOperators.length > 0, "no operators found — check attribute spellings");
+  assert.ok(d.sql.length > 0);
+});
+```
+
+Add `import { readFileSync } from "node:fs";` to the test file.
+
+- [ ] **Step 5: Run tests, commit**
+
+If the entity assertion fails on your `fast-xml-parser` version, decode in `digestPlan`: wrap `text(stmt.StatementText)` with `.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&")`, then re-run. Commit `feat: showplan digest`.
+
+---
+
+### Task 7: Analyst — multiple options, multiple rewrites
+
+**Files:** create `lib/analyst.ts`, `tests/analyst.test.ts`.
+
+**Interfaces — consumes** `AnalystConfig` (Task 4), `Digest` + `digestForModel` (Task 6). **Produces:** `class AnalystError` · `type Action = { title: string; detail: string; effort: "low" | "medium" | "high"; requires_change_control: boolean }` · `type Candidate = { key: string; title: string; diagnosis: string; actions: Action[]; rewrite_sql: string | null; expected: string }` · `extractJson(text): unknown` · `proposeCandidates(cfg, digest, note, fetchImpl?): Promise<Candidate[]>` (2–4 items, schema-validated) · `CANDIDATE_SYSTEM_PROMPT`.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+const { proposeCandidates, extractJson, AnalystError } = await import("../lib/analyst.ts");
+
+const cfg = { baseUrl: "https://api.test/v1", apiKey: "k", model: "m", extra: {} };
+const digest = { sql: "SELECT 1", bytes: 8, subtreeCost: 1, parallel: false, nonParallelReason: null,
+  earlyAbort: null, tables: ["t"], topOperators: [], rowGuessErrors: [], missingIndexes: [], warnings: [], waits: [] } as any;
+const ok = (content: string) => ({ ok: true, status: 200,
+  json: async () => ({ choices: [{ message: { content } }] }) });
+const CANDS = { candidates: [
+  { key: "idx_customer", title: "Covering index", diagnosis: "Scan of 1.2M rows on Sales.Orders, no key on CustomerId.",
+    actions: [{ title: "Create index", detail: "CREATE INDEX ...", effort: "medium", requires_change_control: true }],
+    rewrite_sql: null, expected: "seek instead of scan" },
+  { key: "rewrite_split", title: "Split the statement", diagnosis: "One statement scans everything then filters.",
+    actions: [{ title: "Deploy rewrite", detail: "Two statements", effort: "high", requires_change_control: true }],
+    rewrite_sql: "SELECT ...", expected: "far fewer logical reads" }] };
+
+test("returns schema-valid candidates", async () => {
+  const got = await proposeCandidates(cfg, digest, "", async () => ok(JSON.stringify(CANDS)) as any);
+  assert.equal(got.length, 2);
+  assert.equal(got[0].key, "idx_customer");
+});
+test("survives code fences and sends extra params", async () => {
+  let sent: any;
+  const fetchImpl = async (_u: any, init: any) => { sent = JSON.parse(init.body);
+    return ok("```json\n" + JSON.stringify(CANDS) + "\n```") as any; };
+  const got = await proposeCandidates({ ...cfg, extra: { temperature: 0.1 } }, digest, "index exists already", fetchImpl as any);
+  assert.equal(got.length, 2);
+  assert.equal(sent.temperature, 0.1);
+  assert.match(sent.messages[0].content, /candidates/);
+  assert.match(sent.messages[1].content, /index exists already/);
+});
+test("names the stage on auth, prose, and shape failures", async () => {
+  await assert.rejects(() => proposeCandidates(cfg, digest, "",
+    async () => ({ ok: false, status: 401, text: async () => "bad key" }) as any),
+    (e: any) => e instanceof AnalystError && /401/.test(e.message));
+  await assert.rejects(() => proposeCandidates(cfg, digest, "", async () => ok("no json here") as any), AnalystError);
+  await assert.rejects(() => proposeCandidates(cfg, digest, "",
+    async () => ok(JSON.stringify({ candidates: [CANDS.candidates[0]] })) as any),
+    (e: any) => /at least 2/.test(e.message));
+});
+test("extractJson copes with fences and chatter", () => {
+  assert.deepEqual(extractJson('Sure!\n```json\n{"a":1}\n```'), { a: 1 });
+  assert.deepEqual(extractJson('noise {"a":1} noise'), { a: 1 });
+});
+```
+
+- [ ] **Step 2: Run it** — module not found.
+
+- [ ] **Step 3: Implement `lib/analyst.ts`**
+
+```ts
+import { z } from "zod/v4";
+import type { Digest } from "@/lib/digest";
+import { digestForModel } from "@/lib/digest";
+import type { AnalystConfig } from "@/lib/settings";
+
+export class AnalystError extends Error {}
+
+const Action = z.object({ title: z.string().min(3), detail: z.string().min(3),
+  effort: z.enum(["low", "medium", "high"]), requires_change_control: z.boolean() });
+const RawCandidate = z.object({ key: z.string().min(2), title: z.string().min(3), diagnosis: z.string().min(15),
+  actions: z.array(Action).min(1), rewrite_sql: z.string().nullable(), expected: z.string().min(5) });
+const Proposal = z.object({ candidates: z.array(RawCandidate).min(2).max(4) });
+export type Action = z.infer<typeof Action>;
+export type Candidate = z.infer<typeof RawCandidate>;
+
+export const CANDIDATE_SYSTEM_PROMPT = `You are a SQL Server performance engineer. You receive a JSON digest of one
+execution plan. Judge only what the digest contains — never invent operators, waits, or row counts you were not given.
+
+Return 2 to 4 genuinely different remediation options, not one option restated. Real differences: an index change, a
+rewritten query, a statistics or parallelism fix, a batching or schema change. At least one option must be the
+lowest-risk one. Each option needs a snake_case key, a diagnosis naming WHY the plan is slow, 1-4 ordered actions, an
+optional rewritten query, and an expected effect stated as a concrete claim about the plan (logical reads, seek vs
+scan, tempdb spill, degree of parallelism).
+
+A rewrite must return the same rows as the original. If you cannot rewrite safely, set rewrite_sql to null.
+Output ONE JSON object and nothing else:
+{"candidates":[{"key":"idx_covering_orders","title":"...","diagnosis":"...","actions":[{"title":"...","detail":"...",
+"effort":"low|medium|high","requires_change_control":false}],"rewrite_sql":null,"expected":"..."}]}`;
+
+export function extractJson(text: string): unknown {
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+  const s = (fenced ? fenced[1] : text).trim();
+  const start = s.indexOf("{"); const end = s.lastIndexOf("}");
+  if (start === -1 || end <= start) throw new AnalystError("The analyst model returned prose instead of JSON.");
+  try { return JSON.parse(s.slice(start, end + 1)); }
+  catch { throw new AnalystError("The analyst model returned malformed JSON."); }
+}
+
+export async function proposeCandidates(cfg: AnalystConfig, digest: Digest, note: string,
+    fetchImpl: typeof fetch = fetch): Promise<Candidate[]> {
+  const res = await fetchImpl(`${cfg.baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${cfg.apiKey}` },
+    body: JSON.stringify({ model: cfg.model, temperature: 0.6, ...cfg.extra, stream: false,
+      messages: [{ role: "system", content: CANDIDATE_SYSTEM_PROMPT },
+        { role: "user", content: JSON.stringify({ digest: digestForModel(digest), user_note: note || null }) }] }),
+  }).catch((e) => { throw new AnalystError(`Could not reach ${cfg.baseUrl}: ${(e as Error).message}`); });
+
+  if (!res.ok) throw new AnalystError(`Analyst model returned HTTP ${res.status}. ${(await res.text()).slice(0, 300)}`);
+  const content: string = ((await res.json() as any)?.choices?.[0]?.message?.content) ?? "";
+  const parsed = Proposal.safeParse(extractJson(content));
+  if (!parsed.success) {
+    const n = (extractJson(content) as any)?.candidates?.length ?? 0;
+    throw new AnalystError(n < 2
+      ? `The analyst model proposed ${n} option(s); at least 2 are needed before Jev can rank anything.`
+      : `Analyst output did not match the schema at ${parsed.error.issues[0].path.join(".")}: ${parsed.error.issues[0].message}`);
+  }
+  return parsed.data.candidates;
+}
+```
+
+No `response_format` is sent: plenty of OpenAI-compatible endpoints 400 on it, and `extractJson` already handles the fenced/prose cases it would have prevented.
+
+- [ ] **Step 4: Run tests, commit** — commit `feat: analyst proposes multiple options`.
+
+---
+
+### Task 8: Jev — score, rank, decide
+
+**Files:** create `lib/jev.ts`, `tests/jev.test.ts`.
+
+**Interfaces — consumes** `Digest` + `digestForModel` (Task 6), `Candidate` (Task 7), `@typesafe-ai/sdk`. **Produces:**
+`makeJevClient(apiKey: string, model?: string): TypeSafeClient` · `type Dim = "bottleneck_fit" | "semantic_safety" | "ease" | "root_cause"` · `const WEIGHTS: Record<Dim, number>` (sums to 1) ·
+`type Ranked = { key: string; dims: Record<Dim, { value: number; confidence: number | null }>; composite: number; flags: string[] }` ·
+`type Verdict = { order: Ranked[]; headline: string; source: "jev" | "composite"; jev_pick: string | null; jev_confidence: number; agrees: boolean; anything_worth_running: number; weights: Record<Dim, number>; flags: string[] }` ·
+`judgeCandidates(digest, candidates, client): Promise<Verdict>` · `jevFallback(candidates, why): Verdict`.
+
+Question design follows TypeSafe's composite-scoring pattern: one narrow judgment per question, four questions in a
+single per-candidate call (the API answers them in parallel), then a second call that compares all candidates side by
+side. Every rubric is worded so **higher is better** — nothing gets inverted in code.
+
+Weights are a starting opinion, not a discovery: 0.40 bottleneck_fit / 0.30 semantic_safety / 0.15 ease / 0.15 root_cause.
+They are shipped inside the `Verdict` so the UI can print them, and they are the only tuning knob in the product. A DBA
+who disagrees with the ranking changes four numbers in `lib/jev.ts` — that is the intended edit point, so state it in the
+README rather than building a weights UI.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+const { judgeCandidates, WEIGHTS, jevFallback } = await import("../lib/jev.ts");
+const { TypeSafeClient } = await import("@typesafe-ai/sdk");
+
+const digest = { sql: "SELECT", bytes: 1, subtreeCost: 1, parallel: false, nonParallelReason: null, earlyAbort: null,
+  tables: [], rowGuessErrors: [], missingIndexes: [], warnings: [], waits: [],
+  topOperators: [{ id: "0", op: "Clustered Index Scan", cost: 4.1, estRows: 1000, actualRows: 1200000,
+    execs: 1, io: 40, cpu: 39, spillLevels: 2, parallel: false }] } as any;
+const candidates = [
+  { key: "a", title: "Covering index", diagnosis: "Scan of a million rows; no key exists on CustomerId.",
+    actions: [{ title: "Create index", detail: "CREATE INDEX", effort: "medium", requires_change_control: true }],
+    rewrite_sql: null, expected: "seek instead of scan" },
+  { key: "b", title: "Add TOP 100", diagnosis: "Too many rows leave the scan, so cut them off.",
+    actions: [{ title: "Add TOP 100", detail: "TOP 100", effort: "low", requires_change_control: false }],
+    rewrite_sql: "SELECT TOP 100", expected: "less I/O" },
+] as any;
+
+const scored = (fit: number, safe: number, ease: number, cause: number) => ({
+  bottleneck_fit: { type: "score", score: fit, confidence: 0.9, legend: {}, probabilities: {} },
+  semantic_safety: { type: "score", score: safe, confidence: 0.8, legend: {}, probabilities: {} },
+  ease: { type: "score", score: ease, confidence: 0.7, legend: {}, probabilities: {} },
+  root_cause: { type: "noul", noul: cause } });
+
+// The SDK's client takes an injectable fetch — no network in tests.
+function fakeJev(map: any) {
+  return new TypeSafeClient({ apiKey: "test", fetch: (async (_u: any, init: any) => {
+    const body = JSON.parse(init.body);
+    const answers = body.questions.first_to_run ? map.cross : map.byKey[body.state.candidate.key];
+    return new Response(JSON.stringify({ model: "jev-1.13.0", usage: { input_tokens: 1, output_tokens: 1 }, answers }),
+      { status: 200, headers: { "content-type": "application/json" } });
+  }) as any, retry: { maxRetries: 0 } });
+}
+const GOOD = { byKey: { a: scored(4, 4, 2, 1), b: scored(0.4, 0.5, 4, 0.1) },
+  cross: { first_to_run: { type: "choice", choice: "a", confidence: 0.82, probabilities: { a: 0.82, b: 0.18 } },
+           anything_worth_running: { type: "noul", noul: 0.9 } } };
+
+test("weights sum to 1", () => assert.equal(Object.values(WEIGHTS).reduce((a, b) => a + b, 0), 1));
+
+test("jev picks the winner; the unsafe option is flagged and cannot lead", async () => {
+  const v = await judgeCandidates(digest, candidates, fakeJev(GOOD));
+  assert.equal(v.source, "jev");
+  assert.equal(v.headline, "a");
+  assert.equal(v.order[0].key, "a");
+  assert.equal(v.agrees, true);
+  assert.equal(v.jev_confidence, 0.82);
+  assert.ok(v.order.find((r) => r.key === "b")!.flags.includes("verify_semantics"));
+  assert.ok(v.order.find((r) => r.key === "a")!.flags.includes("change_control"));
+  assert.ok(v.order.find((r) => r.key === "a")!.dims.bottleneck_fit.value === 1);
+});
+test("a low-confidence jev pick defers to composite order", async () => {
+  const low = { byKey: GOOD.byKey, cross: { first_to_run: { type: "choice", choice: "b", confidence: 0.2,
+    probabilities: { a: 0.4, b: 0.6 } }, anything_worth_running: { type: "noul", noul: 0.4 } } };
+  const v = await judgeCandidates(digest, candidates, fakeJev(low));
+  assert.equal(v.source, "composite");
+  assert.equal(v.headline, "a");
+  assert.equal(v.agrees, false);
+  assert.ok(v.flags.includes("low_confidence"));
+  assert.ok(v.flags.includes("nothing_clearly_worthwhile"));
+});
+test("an unknown jev choice label falls back to composite order", async () => {
+  const bogus = { byKey: GOOD.byKey, cross: { first_to_run: { type: "choice", choice: "zzz", confidence: 0.99,
+    probabilities: { zzz: 0.99 } }, anything_worth_running: { type: "noul", noul: 0.9 } } };
+  const v = await judgeCandidates(digest, candidates, fakeJev(bogus));
+  assert.equal(v.source, "composite");
+  assert.equal(v.headline, "a");
+  assert.equal(v.jev_pick, null);
+});
+test("fallback ranks without Jev and says so", () => {
+  const v = jevFallback(candidates, "429 rate limited");
+  assert.equal(v.source, "composite");
+  assert.ok(v.flags.includes("jev_unavailable"));
+  assert.equal(v.order.length, 2);
+});
+```
+
+- [ ] **Step 2: Run it** — module not found.
+
+- [ ] **Step 3: Implement `lib/jev.ts`**
+
+```ts
+import { TypeSafeClient, score, noul, choice } from "@typesafe-ai/sdk";
+import type { Digest } from "@/lib/digest";
+import { digestForModel } from "@/lib/digest";
+import type { Candidate } from "@/lib/analyst";
+
+export type Dim = "bottleneck_fit" | "semantic_safety" | "ease" | "root_cause";
+export const WEIGHTS: Record<Dim, number> = { bottleneck_fit: 0.4, semantic_safety: 0.3, ease: 0.15, root_cause: 0.15 };
+const SAFETY_FLOOR = 0.6;
+const CONFIDENCE_FLOOR = 0.35;
+
+const BOTTLENECK = [
+  "Unrelated to the costly operator or the worst estimate error in the plan.",
+  "Touches a minor operator; the dominant cost is untouched.",
+  "Partly addresses the dominant cost; a scan or spill probably remains.",
+  "Directly removes the dominant cost for this query shape.",
+  "Removes the dominant cost and the pattern behind it, so the shape itself changes.",
+];
+const SAFETY = [
+  "Changes results: a predicate, join, grouping, or NULL handling is altered.",
+  "Likely changes results in edge cases: duplicates, ordering, tie-breaking.",
+  "Equivalent on most data but leans on unstated assumptions.",
+  "Clearly equivalent, with a stated reason.",
+  "Equivalent and checkable: ships a comparison or rollback plan.",
+];
+const EASE = [
+  "Needs a schema plus application redesign and a release.",
+  "Needs an application deploy with change control on the app tier.",
+  "DBA work with approval, e.g. an index create during a window.",
+  "One rewritten query or session setting, reviewable in minutes.",
+  "Copy-paste change with no server-side change at all.",
+];
+
+export type Ranked = { key: string; dims: Record<Dim, { value: number; confidence: number | null }>;
+  composite: number; flags: string[] };
+export type Verdict = { order: Ranked[]; headline: string; source: "jev" | "composite"; jev_pick: string | null;
+  jev_confidence: number; agrees: boolean; anything_worth_running: number; weights: Record<Dim, number>; flags: string[] };
+
+export const makeJevClient = (apiKey: string, model = "jev-latest") =>
+  new TypeSafeClient({ apiKey, defaultModel: model, timeout: 20_000 });
+
+const norm = (s: number, levels: number) => Math.max(0, Math.min(1, s / (levels - 1)));
+
+function rank(c: Candidate, a: any): Ranked {
+  const dims = {
+    bottleneck_fit: { value: norm(a.bottleneck_fit.score, BOTTLENECK.length), confidence: a.bottleneck_fit.confidence },
+    semantic_safety: { value: norm(a.semantic_safety.score, SAFETY.length), confidence: a.semantic_safety.confidence },
+    ease: { value: norm(a.ease.score, EASE.length), confidence: a.ease.confidence },
+    root_cause: { value: a.root_cause.noul, confidence: null },  // noul reports no confidence
+  } as Record<Dim, { value: number; confidence: number | null }>;
+  const composite = (Object.keys(WEIGHTS) as Dim[]).reduce((s, k) => s + WEIGHTS[k] * dims[k].value, 0);
+  const confs = Object.values(dims).map((d) => d.confidence).filter((x): x is number => x !== null);
+  const flags: string[] = [];
+  if (dims.semantic_safety.value < SAFETY_FLOOR) flags.push("verify_semantics");
+  if (confs.length && Math.min(...confs) < CONFIDENCE_FLOOR) flags.push("low_confidence");
+  if (c.actions.some((x) => x.requires_change_control)) flags.push("change_control");
+  return { key: c.key, dims, composite: Number(composite.toFixed(4)), flags };
+}
+
+export async function judgeCandidates(digest: Digest, candidates: Candidate[], client: TypeSafeClient): Promise<Verdict> {
+  const plan = digestForModel(digest);
+  const per = await Promise.all(candidates.map((c) => client.systemOne({
+    state: { plan, candidate: c },
+    questions: {
+      bottleneck_fit: score("How directly do the actions in `candidate` attack the dominant bottleneck in `plan` — the most expensive operator and the worst estimate error?", BOTTLENECK),
+      semantic_safety: score("If `candidate` is applied, how certain is it that the query still returns exactly the same rows as the original?", SAFETY),
+      ease: score("How easy is `candidate` to apply in a real shop, counting people, approvals, and downtime?", EASE),
+      root_cause: noul("The diagnosis in `candidate` names the actual cause of the cost in `plan`, not a symptom of it."),
+    },
+  })));
+
+  const cross = await client.systemOne({
+    state: { plan, options: candidates.map((c) => ({ key: c.key, title: c.title, diagnosis: c.diagnosis, expected: c.expected })) },
+    questions: {
+      first_to_run: choice("Which single entry in `options` should the DBA run first for the biggest drop in the cost shown in `plan`?",
+        Object.fromEntries(candidates.map((c) => [c.key, `${c.title} — ${c.expected}`]))),
+      anything_worth_running: noul("At least one entry in `options` would meaningfully reduce the cost shown in `plan`."),
+    },
+  });
+
+  const order = candidates.map((c, i) => rank(c, (per[i] as any).answers)).sort((a, b) => b.composite - a.composite);
+  const pick = (cross as any).answers.first_to_run;
+  const worth = (cross as any).answers.anything_worth_running.noul;
+  const valid = candidates.some((c) => c.key === pick.choice);
+  const useJev = valid && pick.confidence >= 0.5;   // confidence-gated routing: act only when Jev is sure enough
+  const flags: string[] = [];
+  if (!useJev) flags.push(pick.confidence < CONFIDENCE_FLOOR ? "low_confidence" : "composite_order");
+  if (worth < 0.5) flags.push("nothing_clearly_worthwhile");
+
+  return { order, source: useJev ? "jev" : "composite", headline: useJev ? pick.choice : order[0].key,
+    jev_pick: valid ? pick.choice : null, jev_confidence: pick.confidence,
+    agrees: valid && pick.choice === order[0].key, anything_worth_running: worth, weights: WEIGHTS, flags };
+}
+
+// Neutral answers: Jev never spoke, so nothing is claimed about safety or fit. The UI must say so.
+export function jevFallback(candidates: Candidate[], why: string): Verdict {
+  const order = candidates.map((c) => rank(c, { bottleneck_fit: { score: 0, confidence: null },
+    semantic_safety: { score: 0, confidence: null }, ease: { score: 0, confidence: null },
+    root_cause: { noul: 0 } })).sort((a, b) => b.composite - a.composite);
+  return { order, source: "composite", headline: order[0]?.key ?? "", jev_pick: null, jev_confidence: 0,
+    agrees: false, anything_worth_running: 0, weights: WEIGHTS, flags: ["jev_unavailable", why.slice(0, 200)] };
+}
+```
+
+- [ ] **Step 4: Run tests, commit** — `npm run test` → all suites green. Commit `feat: jev composite scoring and verdict`.
+
+---
+
+### Task 9: OpenUI report library (rendered output, not markdown)
+
+**Files:** create `lib/report-ui.tsx`, `tests/report-ui.test.ts`.
+
+**Interfaces — consumes** `@openuidev/react-lang`, `zod/v4`. **Produces:** `library` (`createLibrary`, `root: "Report"`), `reportPromptOptions` (`preamble`, `additionalRules`, `examples`), and the components `Headline Metric MetricGrid Finding Findings Step StepList SqlBlock ScoreBar OptionRow OptionTable VerdictBlock Callout Report`. The same module is imported by the route (for `library.prompt()`) and by the client (for `<Renderer>`), so the prompt and the renderer can never drift apart.
+
+Composition uses `.ref` (`z.array(Child.ref)`) and `renderNode(children)` — children are declared before their container, root last.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+const { library, reportPromptOptions } = await import("../lib/report-ui.tsx");
+
+test("the prompt advertises every component and the root", () => {
+  const p = library.prompt(reportPromptOptions);
+  for (const n of ["Report", "Headline", "VerdictBlock", "MetricGrid", "Findings", "OptionTable",
+                   "StepList", "SqlBlock", "ScoreBar", "Callout"]) assert.ok(p.includes(n), `missing ${n}`);
+  assert.match(p, /root/i);
+  assert.match(p, /never invent/i);
+});
+```
+
+- [ ] **Step 2: Run it** — module not found.
+
+- [ ] **Step 3: Implement `lib/report-ui.tsx`**
+
+```tsx
+import { defineComponent, createLibrary } from "@openuidev/react-lang";
+import { z } from "zod/v4";
+
+const Headline = defineComponent({ name: "Headline",
+  description: "Report title: the one-line finding, with severity.",
+  props: z.object({ title: z.string(), subtitle: z.string().optional(),
+    severity: z.enum(["critical", "warning", "info"]).optional() }),
+  component: ({ props }) => <header>
+    <p className="label">{props.severity === "critical" ? "Critical" : props.severity === "warning" ? "Warning" : "Note"}</p>
+    <h2 style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-2xl)", margin: "var(--qai-space-s) 0" }}>{props.title}</h2>
+    {props.subtitle && <p style={{ color: "var(--qai-ink-muted)" }}>{props.subtitle}</p>}</header> });
+
+const Metric = defineComponent({ name: "Metric", description: "One plan metric.",
+  props: z.object({ label: z.string(), value: z.string(), note: z.string().optional() }),
+  component: ({ props }) => <div className="card">
+    <p className="label">{props.label}</p>
+    <p style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-xl)" }}>{props.value}</p>
+    {props.note && <p style={{ fontSize: "var(--qai-text-xs)", color: "var(--qai-ink-muted)" }}>{props.note}</p>}</div> });
+
+const MetricGrid = defineComponent({ name: "MetricGrid", description: "Row of plan metrics.",
+  props: z.object({ items: z.array(Metric.ref) }),
+  component: ({ props, renderNode }) => <div className="grid-metrics">{renderNode(props.items)}</div> });
+
+const Finding = defineComponent({ name: "Finding", description: "One problem, the plan evidence for it, its impact.",
+  props: z.object({ where: z.string(), issue: z.string(), evidence: z.string(), impact: z.string() }),
+  component: ({ props }) => <div className="card">
+    <p className="label">{props.where}</p>
+    <p style={{ margin: "var(--qai-space-s) 0" }}><strong>{props.issue}</strong></p>
+    <p className="sql">{props.evidence}</p>
+    <p style={{ color: "var(--qai-ink-muted)" }}>{props.impact}</p></div> });
+
+const Findings = defineComponent({ name: "Findings", description: "Everything wrong with the plan.",
+  props: z.object({ items: z.array(Finding.ref) }),
+  component: ({ props, renderNode }) => <section className="report">{renderNode(props.items)}</section> });
+
+const Step = defineComponent({ name: "Step", description: "One action step.",
+  props: z.object({ text: z.string(), effort: z.enum(["low", "medium", "high"]).optional(),
+    owner: z.enum(["dba", "developer", "both"]).optional(), changeControl: z.boolean().optional() }),
+  component: ({ props }) => <li className="card" style={{ display: "flex", gap: "var(--qai-space-md)",
+      alignItems: "center", flexWrap: "wrap" }}>
+    <span style={{ flex: "1 1 200px", minWidth: 0 }}>{props.text}</span>
+    {props.effort && <span className="pill">effort {props.effort}</span>}
+    {props.owner && <span className="pill">{props.owner}</span>}
+    {props.changeControl && <span className="pill">change control</span>}</li> });
+
+const StepList = defineComponent({ name: "StepList", description: "Ordered action plan for one option.",
+  props: z.object({ title: z.string(), steps: z.array(Step.ref) }),
+  component: ({ props, renderNode }) => <section>
+    <h3 style={{ fontFamily: "var(--qai-font-display)" }}>{props.title}</h3>
+    <ol style={{ listStyle: "none", padding: 0, margin: 0, display: "grid", gap: "var(--qai-space-md)" }}>
+      {renderNode(props.steps)}</ol></section> });
+
+const SqlBlock = defineComponent({ name: "SqlBlock", description: "A SQL snippet the user can copy.",
+  props: z.object({ title: z.string(), sql: z.string(), caption: z.string().optional() }),
+  component: ({ props }) => <figure className="card" style={{ margin: 0 }}>
+    <figcaption className="label">{props.title}</figcaption>
+    <pre className="sql">{props.sql}</pre>
+    <button className="btn no-print" onClick={() => navigator.clipboard.writeText(props.sql)}>Copy SQL</button>
+    {props.caption && <p style={{ fontSize: "var(--qai-text-xs)", color: "var(--qai-ink-muted)" }}>{props.caption}</p>}</figure> });
+
+const ScoreBar = defineComponent({ name: "ScoreBar", description: "One Jev dimension: normalised value plus confidence.",
+  props: z.object({ label: z.string(), value: z.number(), confidence: z.number().optional(), note: z.string().optional() }),
+  component: ({ props }) => <div>
+    <p className="label">{props.label}{props.confidence !== undefined
+      ? ` · confidence ${props.confidence.toFixed(2)}` : " · no confidence reported"}</p>
+    <div className="bar" style={{ width: `${Math.round(props.value * 100)}%` }} />
+    {props.note && <p style={{ fontSize: "var(--qai-text-xs)", color: "var(--qai-ink-muted)" }}>{props.note}</p>}</div> });
+
+const OptionRow = defineComponent({ name: "OptionRow", description: "One ranked option.",
+  props: z.object({ rank: z.number(), title: z.string(), composite: z.number(), headline: z.boolean(),
+    flags: z.string().optional() }),
+  component: ({ props }) => <tr data-headline={props.headline || undefined}>
+    <td>{props.rank}</td><td>{props.title}</td>
+    <td className="sql">{props.composite.toFixed(2)}</td>
+    <td>{props.flags || "—"}</td></tr> });
+
+const OptionTable = defineComponent({ name: "OptionTable", description: "All options ranked by composite score.",
+  props: z.object({ title: z.string(), weights: z.string(), rows: z.array(OptionRow.ref) }),
+  component: ({ props, renderNode }) => <section className="card">
+    <h3 style={{ fontFamily: "var(--qai-font-display)" }}>{props.title}</h3>
+    <p style={{ fontSize: "var(--qai-text-xs)", color: "var(--qai-ink-muted)" }}>{props.weights}</p>
+    <table style={{ width: "100%", borderCollapse: "collapse" }}><tbody>{renderNode(props.rows)}</tbody></table></section> });
+
+const VerdictBlock = defineComponent({ name: "VerdictBlock", description: "What Jev decided, and how sure it was.",
+  props: z.object({ headline: z.string(), why: z.string(), source: z.enum(["jev", "composite"]), confidence: z.number() }),
+  component: ({ props }) => <section className="card" data-verdict>
+    <p className="label">First move · {props.source === "jev"
+      ? `Jev, confidence ${props.confidence.toFixed(2)}` : "composite order — Jev did not decide"}</p>
+    <p style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-lg)" }}>{props.headline}</p>
+    <p>{props.why}</p></section> });
+
+const Callout = defineComponent({ name: "Callout", description: "A warning or note the user must not miss.",
+  props: z.object({ level: z.enum(["info", "warn", "danger", "success"]), title: z.string(), text: z.string() }),
+  component: ({ props }) => <div className="card" data-level={props.level}
+      role={props.level === "danger" ? "alert" : "note"}>
+    <p><strong>{props.title}</strong></p><p>{props.text}</p></div> });
+
+const Report = defineComponent({ name: "Report", description: "Root. A query-plan report in reading order.",
+  props: z.object({ blocks: z.array(z.union([Headline.ref, VerdictBlock.ref, MetricGrid.ref, Findings.ref,
+    OptionTable.ref, StepList.ref, SqlBlock.ref, ScoreBar.ref, Callout.ref])) }),
+  component: ({ props, renderNode }) => <div className="report" id="report">{renderNode(props.blocks)}</div> });
+
+export const library = createLibrary({ root: "Report", components: [Headline, Metric, MetricGrid, Finding, Findings,
+  Step, StepList, SqlBlock, ScoreBar, OptionRow, OptionTable, VerdictBlock, Callout, Report] });
+
+export const reportPromptOptions = {
+  preamble: "You output only OpenUI Lang. No prose, no markdown fences, no commentary before or after.",
+  additionalRules: [
+    "root = Report([...]) and it must list every block you define.",
+    "Block order: Headline, VerdictBlock, MetricGrid, Findings, OptionTable, then per option its StepList and SqlBlock, then ScoreBars, then Callout.",
+    "Use ONLY numbers present in the input. Never invent a cost, row count, impact, or confidence.",
+    "One SqlBlock per rewrite, titled with that option's key. T-SQL only, no markdown.",
+    "Every option flagged verify_semantics gets a Callout level danger: compare result rows before deploying.",
+    "If verdict.source is composite, say plainly that Jev did not decide.",
+  ],
+  examples: [`root = Report([head, verdict])
+head = Headline("Clustered Index Scan on Sales.Orders is 84% of the plan", "No usable key on CustomerId", "critical")
+verdict = VerdictBlock("Create the covering index", "bottleneck_fit 1.00, semantic_safety 1.00, ease 0.50.", "jev", 0.82)`],
+};
+```
+
+- [ ] **Step 4: Verify + commit** — `npm run test` green; `npm run build` compiles the `.tsx` on both server and client boundaries. Commit `feat: openui report library`.
+
+---
+
+### Task 10: The pipeline — `POST /api/analyze` as a server-sent event stream
+
+**Files:** create `lib/stream.ts`, `app/api/analyze/route.ts`, `tests/stream.test.ts`; modify `lib/analyst.ts` (add `streamReport` + `REPORT_SYSTEM_PROMPT`).
+
+**Interfaces — consumes** `requireUser`, `analystConfig`, `jevKey`, `jevModel`, `digestPlan`, `PlanError`, `digestForModel`, `proposeCandidates`, `judgeCandidates`, `makeJevClient`, `jevFallback`, `library`, `reportPromptOptions`, `newAnalysis`, `patchAnalysis`.
+**Produces:** `sse(event, data): string` · `readSse(body): AsyncGenerator<{ event: string; data: any }>` · `openAiTextDeltas(res): AsyncGenerator<string>` · `streamReport(cfg, payload, fetchImpl?): AsyncGenerator<string>` · `REPORT_SYSTEM_PROMPT(openuiPrompt: string): string`.
+**Wire format (server → client):** `stage {stage}` (`digesting` | `proposing` | `judging` | `writing`) · `candidate {key,title}` · `verdict {Verdict}` · `oul {chunk}` · `done {id}` · `error {stage, message}`.
+
+- [ ] **Step 1: Write the failing test for the pure stream helpers**
+
+```ts
+import test from "node:test";
+import assert from "node:assert/strict";
+const { sse, readSse, openAiTextDeltas } = await import("../lib/stream.ts");
+
+const streamOf = (parts: string[]) => new ReadableStream<Uint8Array>({ start(c) {
+  parts.forEach((p) => c.enqueue(new TextEncoder().encode(p))); c.close(); } });
+
+test("sse frames one event", () =>
+  assert.equal(sse("stage", { stage: "digesting" }), 'event: stage\ndata: {"stage":"digesting"}\n\n'));
+
+test("readSse rejoins frames split anywhere", async () => {
+  const raw = sse("stage", { stage: "digesting" }) + sse("oul", { chunk: "root = Report([])" });
+  const events: any[] = [];
+  for await (const e of readSse(streamOf([raw.slice(0, 12), raw.slice(12, 40), raw.slice(40)]))) events.push(e);
+  assert.deepEqual(events, [{ event: "stage", data: { stage: "digesting" } },
+                            { event: "oul", data: { chunk: "root = Report([])" } }]);
+});
+test("readSse ignores a keep-alive frame it cannot parse", async () => {
+  const events: any[] = [];
+  for await (const e of readSse(streamOf([": ping\n\n", sse("done", { id: "1" })]))) events.push(e);
+  assert.deepEqual(events, [{ event: "message", data: undefined } satisfies any].slice(1));
+});
+test("openAiTextDeltas yields content and stops at [DONE]", async () => {
+  const res = new Response(streamOf(['data: {"choices":[{"delta":{"content":"ab"}}]}\n\n',
+    'data: {"choices":[{"delta":{"content":"cd"}}]}\n\n', "data: [DONE]\n\n"]), { status: 200 });
+  const out: string[] = [];
+  for await (const d of openAiTextDeltas(res)) out.push(d);
+  assert.equal(out.join(""), "abcd");
+});
+```
+
+- [ ] **Step 2: Run it** — module not found.
+
+- [ ] **Step 3: Implement `lib/stream.ts`**
+
+```ts
+export const sse = (event: string, data: unknown) => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+
+export async function* readSse(body: ReadableStream<Uint8Array>): AsyncGenerator<{ event: string; data: any }> {
+  const reader = body.getReader(); const dec = new TextDecoder(); let buf = "";
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buf += dec.decode(value, { stream: true });
+    let at: number;
+    while ((at = buf.indexOf("\n\n")) !== -1) {
+      const frame = buf.slice(0, at); buf = buf.slice(at + 2);
+      const event = /^event: (.+)$/m.exec(frame)?.[1] ?? "message";
+      const raw = /^data: (.*)$/m.exec(frame)?.[1] ?? "";
+      try { yield { event, data: JSON.parse(raw) }; } catch { /* keep-alive or unparsable frame */ }
+    }
+  }
+}
+
+export async function* openAiTextDeltas(res: Response): AsyncGenerator<string> {
+  const reader = res.body!.getReader(); const dec = new TextDecoder(); let buf = "";
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buf += dec.decode(value, { stream: true });
+    let at: number;
+    while ((at = buf.indexOf("\n\n")) !== -1) {
+      const line = (buf.slice(0, at).split("\n").find((l) => l.startsWith("data:")) ?? "").slice(5).trim();
+      buf = buf.slice(at + 2);
+      if (!line) continue;
+      if (line === "[DONE]") return;
+      let delta: unknown;
+      try { delta = JSON.parse(line)?.choices?.[0]?.delta?.content; } catch { continue; }
+      if (typeof delta === "string" && delta) yield delta;
+    }
+  }
+}
+```
+
+Delete the third test's odd `satisfies` line and use this instead — a keep-alive frame yields nothing:
+
+```ts
+test("readSse ignores frames it cannot parse", async () => {
+  const events: any[] = [];
+  for await (const e of readSse(streamOf([": ping\n\n", sse("done", { id: "1" })]))) events.push(e);
+  assert.deepEqual(events, [{ event: "done", data: { id: "1" } }]);
+});
+```
+
+Append to `lib/analyst.ts`:
+
+```ts
+export const REPORT_SYSTEM_PROMPT = (openuiPrompt: string) => `${openuiPrompt}
+
+You are writing the final answer for a DBA holding one SQL Server execution plan. The ranking you are given was
+computed by Jev from typed judgments. It is not your opinion: do not re-rank it, soften it, or hide it. Quote each
+option's scores as given. A rewrite must return the same rows as the original — when in doubt keep the original text
+and say why. Never invent a number that is not in the input.`;
+
+export async function* streamReport(cfg: AnalystConfig, payload: unknown, openuiPrompt: string,
+    fetchImpl: typeof fetch = fetch): AsyncGenerator<string> {
+  const res = await fetchImpl(`${cfg.baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${cfg.apiKey}` },
+    body: JSON.stringify({ model: cfg.model, temperature: 0.3, ...cfg.extra, stream: true,
+      messages: [{ role: "system", content: REPORT_SYSTEM_PROMPT(openuiPrompt) },
+        { role: "user", content: JSON.stringify(payload) }] }),
+  }).catch((e) => { throw new AnalystError(`Could not reach ${cfg.baseUrl}: ${(e as Error).message}`); });
+  if (!res.ok || !res.body) throw new AnalystError(`Analyst model returned HTTP ${res.status} while writing the report.`);
+  yield* openAiTextDeltas(res);
+}
+```
+
+Add the import at the top of `lib/analyst.ts`: `import { openAiTextDeltas } from "@/lib/stream";`.
+
+- [ ] **Step 4: Implement `app/api/analyze/route.ts`**
+
+The whole run is one stream. Every stage is announced, every failure is named with its stage, and the row is saved with whatever it managed to produce.
+
+```ts
+import { requireUser } from "@/lib/auth";
+import { analystConfig, jevKey, jevModel } from "@/lib/settings";
+import { digestPlan, digestForModel, PlanError } from "@/lib/digest";
+import { proposeCandidates, streamReport, AnalystError } from "@/lib/analyst";
+import { judgeCandidates, jevFallback, makeJevClient } from "@/lib/jev";
+import { sse } from "@/lib/stream";
+import { newAnalysis, patchAnalysis } from "@/lib/db";
+import { library, reportPromptOptions } from "@/lib/report-ui";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+const MAX_BODY_BYTES = 16_000_000;
+
+export async function POST(req: Request) {
+  const user = await requireUser().catch(() => null);
+  if (!user) return Response.json({ error: "Sign in first." }, { status: 401 });
+
+  const analyst = analystConfig(user.id);
+  const jev = jevKey(user.id);
+  if (!analyst) return Response.json({ error: "Set the analyst model in Settings first." }, { status: 412 });
+  if (!jev) return Response.json({ error: "Set your Jev (TypeSafe) API key in Settings first." }, { status: 412 });
+
+  const raw = await req.text();
+  if (raw.length > MAX_BODY_BYTES) return Response.json({ error: "Request too large." }, { status: 413 });
+  let xml = ""; let note = "";
+  try { const body = JSON.parse(raw); xml = String(body.xml ?? ""); note = String(body.note ?? "").slice(0, 500); }
+  catch { return Response.json({ error: "Expected JSON with an xml field." }, { status: 400 }); }
+
+  const id = newAnalysis(user.id, note.trim().slice(0, 120) || "Plan analysis", xml);
+  const enc = new TextEncoder();
+  const prompt = library.prompt(reportPromptOptions);
+
+  const stream = new ReadableStream<Uint8Array>({ async start(ctrl) {
+    const send = (event: string, data: unknown) => ctrl.enqueue(enc.encode(sse(event, data)));
+    let oul = "";
+    const close = (status: string, error?: string) => {
+      patchAnalysis(id, { status, ...(error ? { error } : {}), ...(oul ? { oul } : {}) });
+      send("done", { id }); ctrl.close();
+    };
+    try {
+      send("stage", { stage: "digesting" });
+      let digest;
+      try { digest = digestPlan(xml); }
+      catch (e) { const m = e instanceof PlanError ? e.message : "Could not read that plan.";
+        send("error", { stage: "digesting", message: m }); patchAnalysis(id, { status: "failed", error: m });
+        send("done", { id }); return ctrl.close(); }
+      patchAnalysis(id, { digest: JSON.stringify(digest) });
+
+      send("stage", { stage: "proposing" });
+      let candidates;
+      try { candidates = await proposeCandidates(analyst, digest, note); }
+      catch (e) { const m = e instanceof AnalystError ? e.message : "The analyst model call failed.";
+        send("error", { stage: "proposing", message: m }); patchAnalysis(id, { status: "failed", error: m });
+        send("done", { id }); return ctrl.close(); }
+      candidates.forEach((c) => send("candidate", { key: c.key, title: c.title }));
+      patchAnalysis(id, { candidates: JSON.stringify(candidates) });
+
+      send("stage", { stage: "judging" });
+      let verdict;
+      try { verdict = await judgeCandidates(digest, candidates, makeJevClient(jev, jevModel(user.id))); }
+      catch (e) { verdict = jevFallback(candidates, `Jev call failed: ${(e as Error).message}`); }
+      send("verdict", verdict);
+      patchAnalysis(id, { verdict: JSON.stringify(verdict) });
+
+      send("stage", { stage: "writing" });
+      for await (const chunk of streamReport(analyst,
+          { plan: digestForModel(digest), options: candidates, verdict }, prompt)) {
+        oul += chunk; send("oul", { chunk });
+      }
+      close(oul ? "done" : "partial", oul ? undefined : "The analyst model returned an empty report.");
+    } catch (e) {
+      const m = (e as Error)?.message ?? "Analysis failed.";
+      send("error", { stage: "stream", message: m });
+      patchAnalysis(id, { status: "failed", error: m, ...(oul ? { oul } : {}) });
+      send("done", { id }); ctrl.close();
+    }
+  } });
+
+  return new Response(stream, { headers: { "content-type": "text/event-stream; charset=utf-8",
+    "cache-control": "no-store", connection: "keep-alive", "x-accel-buffering": "no" } });
+}
+```
+
+No `cancel()` handler: the default is right. When the DBA closes the tab, the producer's next `send` throws, the `catch` stores the partial row, and that is the behaviour we want.
+
+- [ ] **Step 5: Verify + commit**
+
+`npm run test` green. Manual, with `npm run dev`, a signed-in browser session, and real keys:
+
+```bash
+curl -sN -X POST localhost:3000/api/analyze -H 'content-type: application/json' \
+  --cookie "qai_s=<session token>" \
+  -d '{"xml":"<ShowPlanXML ...>","note":"slow after the migration"}' | head -20
+```
+
+Expected: `event: stage` frames, then `candidate`, `verdict`, a run of `oul` chunks, then `done`. Then prove Review-Focus 1 and 5: post `{"xml":"SELECT 1"}` and confirm exactly one `error` frame with `stage: digesting` and a `done` frame, never a hanging stream; and post a valid plan with the Jev key invalidated to confirm a `verdict` with `source: "composite"` and the `jev_unavailable` flag. Commit `feat: analysis pipeline with staged SSE`.
+
+---
+
+### Task 11: Console UI — rail, run, live render, rename, delete, copy, PDF
+
+**Files:** create `app/app/page.tsx` (replace), `app/app/[id]/page.tsx`, `components/rail.tsx`, `components/history-item.tsx`, `components/runner.tsx`, `components/report-view.tsx`, `components/export-buttons.tsx`.
+
+**Interfaces — consumes** `library`, `readSse`, `listAnalyses`, `getAnalysis`, `rename`, `remove`, `digestForModel`. **Produces:** the `/app` run surface and `/app/[id]` replay.
+
+- [ ] **Step 1: Rail + history rows (server components)**
+
+`components/history-item.tsx` — inline rename, delete behind a confirm:
+
+```tsx
+import { rename, remove } from "@/lib/actions";
+
+export function HistoryItem({ row }: { row: { id: string; title: string; status: string; created_at: number } }) {
+  const when = new Date(row.created_at).toLocaleString(undefined,
+    { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
+  return <li className="card" style={{ padding: "var(--qai-space-md)", display: "grid", gap: "var(--qai-space-s)" }}>
+    <a href={`/app/${row.id}`} style={{ color: "var(--qai-ink)", textDecoration: "none", fontSize: "var(--qai-text-sm)" }}>
+      {row.title}{row.status !== "done" && <span className="pill" style={{ marginInlineStart: 8 }}>{row.status}</span>}
+    </a>
+    <div style={{ display: "flex", gap: "var(--qai-space-s)", alignItems: "center" }}>
+      <span className="label">{when}</span>
+      <form action={rename} style={{ display: "flex", gap: 4, marginLeft: "auto" }}>
+        <input type="hidden" name="id" value={row.id} />
+        <input className="field" name="title" aria-label="New name" defaultValue={row.title}
+               style={{ width: 90, padding: "4px 6px" }} />
+        <button className="btn" style={{ padding: "4px 8px" }}>Save</button>
+      </form>
+      <form action={remove} onSubmit={(e) => { if (!confirm("Delete this analysis?")) e.preventDefault(); }}>
+        <input type="hidden" name="id" value={row.id} />
+        <button className="btn" style={{ padding: "4px 8px" }}>Delete</button>
+      </form>
+    </div>
+  </li>;
+}
+```
+
+`onSubmit` with `confirm` needs a client boundary — put `HistoryItem` in a file starting with `"use client";` and import `confirm` from `window` (it is a browser global; no import needed). Delete is the only destructive action in the product: it must never fire on a stray click.
+
+`components/rail.tsx`:
+
+```tsx
+import { listAnalyses } from "@/lib/db";
+import { HistoryItem } from "./history-item";
+export async function Rail({ userId }: { userId: string }) {
+  const rows = listAnalyses(userId);
+  return <>
+    <a href="/app" className="label" style={{ textDecoration: "none", color: "var(--qai-accent)" }}>qAI</a>
+    <p className="label">History · {rows.length}</p>
+    <ul style={{ listStyle: "none", padding: 0, margin: 0, display: "grid", gap: "var(--qai-space-s)" }}>
+      {rows.map((r) => <HistoryItem key={r.id} row={r} />)}
+    </ul>
+    <p className="label" style={{ marginTop: "auto" }}>
+      <a href="/settings" style={{ color: "var(--qai-ink-muted)" }}>Settings</a></p>
+  </>;
+}
+```
+
+`app/app/layout.tsx` — replace the placeholder rail:
+
+```tsx
+import { requireUser } from "@/lib/auth";
+import { Rail } from "@/components/rail";
+export default async function Console({ children }: { children: React.ReactNode }) {
+  const u = await requireUser();
+  return <div className="shell">
+    <aside className="rail no-print" aria-label="Previous analyses"><Rail userId={u.id} /></aside>
+    <main className="main">{children}</main>
+  </div>;
+}
+```
+
+- [ ] **Step 2: Runner + live report**
+
+`components/report-view.tsx`:
+
+```tsx
+"use client";
+import { Renderer } from "@openuidev/react-lang";
+import { library } from "@/lib/report-ui";
+export function ReportView({ oul, streaming }: { oul: string; streaming: boolean }) {
+  if (!oul) return null;
+  return <Renderer response={oul} library={library} isStreaming={streaming} />;
+}
+```
+
+`components/export-buttons.tsx` — Copy takes the OpenUI Lang source plus the SQL blocks it contains; PDF is the browser's own print path with a stylesheet that flips tokens to paper:
+
+```tsx
+"use client";
+export function ExportButtons({ oul, title }: { oul: string; title: string }) {
+  const copy = async () => {
+    const sql = [...document.querySelectorAll<HTMLElement>("#report pre.sql")].map((p) => p.textContent).join("\n\n");
+    await navigator.clipboard.writeText(`${title}\n\n${sql || oul}`);
+  };
+  return <div className="toolbar no-print" style={{ display: "flex", gap: "var(--qai-space-s)" }}>
+    <button className="btn" onClick={copy}>Copy</button>
+    <button className="btn" onClick={() => window.print()}>Export to PDF</button>
+  </div>;
+}
+```
+
+`components/runner.tsx` — stage indicator then token-by-token render (ui-ux-pro-max: no spinner for 30 seconds, always show progress):
+
+```tsx
+"use client";
+import { useState } from "react";
+import { readSse } from "@/lib/stream";
+import { ReportView } from "./report-view";
+import { ExportButtons } from "./export-buttons";
+
+const STAGES = ["digesting", "proposing", "judging", "writing"] as const;
+const LABEL: Record<string, string> = { digesting: "Reading the plan", proposing: "Asking for options",
+  judging: "Jev is scoring", writing: "Writing the report" };
+
+export function Runner() {
+  const [xml, setXml] = useState(""); const [note, setNote] = useState("");
+  const [stage, setStage] = useState<string | null>(null);
+  const [oul, setOul] = useState(""); const [error, setError] = useState<string | null>(null);
+  const at = STAGES.indexOf(stage ?? "");
+
+  async function run() {
+    setError(null); setOul(""); setStage("digesting");
+    const res = await fetch("/api/analyze", { method: "POST",
+      headers: { "content-type": "application/json" }, body: JSON.stringify({ xml, note }) });
+    if (!res.ok || !res.body) { setError((await res.json().catch(() => null))?.error ?? `Request failed (${res.status}).`);
+      return setStage(null); }
+    for await (const e of readSse(res.body)) {
+      if (e.event === "stage") setStage(e.data.stage);
+      else if (e.event === "oul") setOul((s) => s + e.data.chunk);
+      else if (e.event === "error") setError(`${e.data.stage}: ${e.data.message}`);
+      else if (e.event === "done") { setStage(null); history.replaceState(null, "", `/app/${e.data.id}`); }
+    }
+  }
+  return <section style={{ display: "grid", gap: "var(--qai-space-xl)" }}>
+    <h1 style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-display)",
+                 letterSpacing: "-0.02em", margin: 0 }}>Paste a plan</h1>
+    <details className="card">
+      <summary style={{ cursor: "pointer", fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-sm)" }}>
+        Where do I get this XML?</summary>
+      <ol style={{ fontSize: "var(--qai-text-sm)", color: "var(--qai-ink-muted)", margin: "var(--qai-space-md) 0 0" }}>
+        <li>SSMS: press <strong>Ctrl+M</strong> (Include Actual Execution Plan), then run the query.</li>
+        <li>On the Execution Plan tab, right-click → <strong>Save As .sqlplan</strong>. Or right-click the statement → <strong>Showplan XML</strong> and copy the cell.</li>
+        <li>No SSMS: prefix the batch with <code>SET STATISTICS XML ON;</code> and copy the XML result cell.</li>
+        <li>Drop the file or paste its contents below. Only the digest leaves this container, and only to your own models.</li>
+      </ol>
+    </details>
+    <div className="runner card" style={{ display: "grid", gap: "var(--qai-space-md)" }}>
+      <label className="label" htmlFor="xml">ShowPlan XML or .sqlplan contents</label>
+      <textarea className="field" id="xml" rows={7} spellCheck={false} value={xml}
+        onChange={(e) => setXml(e.target.value)} placeholder="<ShowPlanXML …>" />
+      <label className="label" htmlFor="note">Anything the plan cannot see? (optional)</label>
+      <input className="field" id="note" value={note} onChange={(e) => setNote(e.target.value)}
+             placeholder="slow since the 16.0.4085 migration" />
+      <div style={{ display: "flex", gap: "var(--qai-space-s)", alignItems: "center", flexWrap: "wrap" }}>
+        <button className="btn btn-primary" onClick={run} disabled={!xml.trim() || stage !== null}>Analyse</button>
+        <input type="file" accept=".sqlplan,.xml" aria-label="Load a .sqlplan file" style={{ fontSize: "var(--qai-text-xs)" }}
+          onChange={async (e) => {
+            const f = e.target.files?.[0]; if (!f) return;
+            const buf = new Uint8Array(await f.arrayBuffer());
+            // SSMS saves UTF-16LE; File.text() decodes that as UTF-8 and fills the plan with NUL bytes.
+            const utf16 = buf[0] === 0xff && buf[1] === 0xfe;
+            setXml(new TextDecoder(utf16 ? "utf-16le" : "utf-8").decode(buf).replace(/^\uFEFF/, ""));
+          }} />
+        {at >= 0 && <span className="pill" aria-live="polite">{at + 1} of 4 · {LABEL[STAGES[at]]}</span>}
+      </div>
+      {error && <p role="alert" style={{ color: "var(--qai-danger)" }}>{error}</p>}
+    </div>
+    {oul && <ExportButtons oul={oul} title={note || "Query plan analysis"} />}
+    <ReportView oul={oul} streaming={stage !== null} />
+  </section>;
+}
+```
+
+`app/app/page.tsx`:
+
+```tsx
+import { Runner } from "@/components/runner";
+export default function Run() { return <Runner />; }
+```
+
+- [ ] **Step 3: Replay a stored analysis (zero model calls)**
+
+`app/app/[id]/page.tsx`:
+
+```tsx
+import { notFound, redirect } from "next/navigation";
+import { requireUser } from "@/lib/auth";
+import { getAnalysis } from "@/lib/db";
+import { ReportView } from "@/components/report-view";
+import { ExportButtons } from "@/components/export-buttons";
+import { VerdictSummary } from "@/components/verdict-summary";
+
+export default async function Stored({ params }: { params: Promise<{ id: string }> }) {
+  const u = await requireUser();
+  const a = getAnalysis((await params).id, u.id);
+  if (!a) notFound();
+  if (a.status === "running") redirect(`/app/${a.id}`);   // still streaming elsewhere; rare, bounce once
+  return <main style={{ display: "grid", gap: "var(--qai-space-xl)" }}>
+    <h1 style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-2xl)", margin: 0 }}>{a.title}</h1>
+    {a.error && <p role="alert" style={{ color: "var(--qai-danger)" }}>{a.error}</p>}
+    {a.verdict && <VerdictSummary verdict={JSON.parse(a.verdict)} />}
+    {a.oul ? <><ExportButtons oul={a.oul} title={a.title} /><ReportView oul={a.oul} streaming={false} /></>
+           : <p className="label">No report was stored for this run.</p>}
+  </main>;
+}
+```
+
+`components/verdict-summary.tsx` — server component, so a stored Jev verdict is readable even if the report body failed to generate:
+
+```tsx
+export function VerdictSummary({ verdict }: { verdict: any }) {
+  const win = verdict.order.find((o: any) => o.key === verdict.headline) ?? verdict.order[0];
+  return <section className="card" data-verdict>
+    <p className="label">Jev verdict · {verdict.source === "jev" ? `chosen, confidence ${verdict.jev_confidence.toFixed(2)}`
+      : "composite order — Jev did not decide"}</p>
+    <p style={{ fontFamily: "var(--qai-font-display)", fontSize: "var(--qai-text-lg)" }}>{win?.key}</p>
+    <p className="label">weights {Object.entries(verdict.weights as Record<string, number>)
+      .map(([k, v]) => `${k} ${v}`).join(" · ")}</p>
+    {(verdict.flags as string[]).length > 0 && <p style={{ color: "var(--qai-warn)" }}>{verdict.flags.join(" · ")}</p>}
+  </section>;
+}
+```
+
+- [ ] **Step 4: Verify at four widths, then commit**
+
+`npm run build`, then `npm run dev` and walk the flow: paste the fixture plan from `tests/digest.test.ts` → stage pills advance 1 of 4 → 2 → 3 → 4 → report blocks appear while `oul` is still arriving → Copy puts SQL on the clipboard → Export to PDF prints white-on-black-free paper (tokens flip in print) with rail and buttons hidden. Rename a row and confirm the title changes without a reload; delete one and confirm the dialog appears first. Resize to 320 / 375 / 414 / 768 px: no horizontal scroll, rail unsticks below 860 px. Commit `feat: console ui, streaming report, history actions`.
+
+---
+
+### Task 12: Container, README, Jev goal gate
+
+**Files:** create `Dockerfile`, `docker-compose.yml`, `.dockerignore`, `README.md`, `scripts/smoke.sh`.
+
+- [ ] **Step 1: Dockerfile** — single image, no rebuild of native modules because nothing is native:
+
+```dockerfile
+FROM node:24-slim AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+FROM node:24-slim AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+FROM node:24-slim AS run
+WORKDIR /app
+ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 DATA_DIR=/data PORT=3000
+RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/* \
+ && mkdir -p /data && chown node:node /data
+COPY --from=build --chown=node:node /app/.next ./.next
+COPY --from=build --chown=node:node /app/public ./public
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/package.json ./package.json
+COPY --from=build --chown=node:node /app/next.config.* ./
+USER node
+VOLUME /data
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD curl -fsS localhost:3000/api/healthz
+CMD ["npm", "start"]
+```
+
+`docker-compose.yml`:
+
+```yaml
+services:
+  qai:
+    build: .
+    ports: ["3000:3000"]
+    environment:
+      APP_SECRET: ${APP_SECRET:?set APP_SECRET in .env, 16+ chars}
+    volumes: ["qai-data:/data"]
+    restart: unless-stopped
+volumes:
+  qai-data:
+```
+
+`.dockerignore`: `.next`, `node_modules`, `data`, `.git`, `.hallmark`, `docs`, `design-system`, `tests`.
+
+- [ ] **Step 2: `scripts/smoke.sh`** — the one command that proves a container works:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+docker compose up --build -d
+trap 'docker compose down -v' EXIT
+for i in $(seq 1 40); do curl -fsS localhost:3000/api/healthz >/dev/null 2>&1 && break; sleep 2; done
+curl -fsS localhost:3000/api/healthz
+curl -fsS localhost:3000/login | grep -qi "sign in"
+curl -fsS -o /dev/null -w '%{http_code}\n' localhost:3000/app | grep -q 307
+echo "smoke ok"
+```
+
+- [ ] **Step 3: README** — keep it to what a person needs in the first five minutes:
+
+```markdown
+# SQL Server qAI
+
+Paste a SQL Server execution plan. Get several ranked ways to fix it, with Jev deciding which one to run first.
+
+    cp .env.example .env        # set APP_SECRET (16+ chars)
+    docker compose up --build   # http://localhost:3000
+
+Sign up → 3-step guide (analyst model + Jev key) → paste XML → Analyse.
+
+Getting the XML: SSMS → Ctrl+M (include actual execution plan) → run the query → save the .sqlplan from the
+Execution Plan tab. No SSMS: prefix the batch with SET STATISTICS XML ON; and copy the XML result cell.
+
+- **Analyst model**: any OpenAI-compatible base URL + key + model. Proposes 2–4 options and rewrites.
+  Keys are entered by each user in the app — never in a server env var.
+- **Jev**: your TypeSafe API key (console.typesafe.ai/keys), also entered per user in the app.
+- Credentials are encrypted at rest with APP_SECRET and never leave the container.
+- Dev analyst endpoint used for local QA: `http://192.168.88.131:8888/v1`, model `qwen3.8-flash-next`, key `EMPTY`.
+  Verified against that endpoint: `system` role only (no developer role), `max_tokens` is the token field, streaming
+  emits `data:` lines and ends with `data: [DONE]`, and content may arrive with leading whitespace — `extractJson` handles it.
+- `npm test` runs the unit suites. `bash scripts/smoke.sh` proves the image.
+- Deleting the `qai-data` volume deletes every account and analysis.
+```
+
+- [ ] **Step 4: Jev goal gate** — one call, three typed questions, a printed yes/no. Run it against the spec, not the plan: the spec is the goal statement, the plan is this file.
+
+```js
+// scripts/jev-gate.mjs — TYPESAFE_API_KEY=... node scripts/jev-gate.mjs docs/superpowers/plans/<plan>.md
+import { readFileSync } from "node:fs";
+const key = process.env.TYPESAFE_API_KEY ?? process.env.JEV_API_KEY;
+if (!key) { console.error("set TYPESAFE_API_KEY"); process.exit(1); }
+const plan = readFileSync(process.argv[2] ?? "docs/superpowers/plans/2026-09-21-sql-server-qai.md", "utf8").slice(0, 60_000);
+const goal = `A portal that takes the XML of a SQL Server query plan, uses generative AI to analyse it, provides
+multiple action steps and multiple query rewrites where possible, and then has Jev rank the options and decide the
+best one, returning the best query too. Output is rendered with OpenUI elements, with copy and export-to-PDF.`;
+const r = await fetch("https://api.typesafe.ai/v1/systemone", {
+  method: "POST", headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+  body: JSON.stringify({ model: "jev-latest", state: { goal, plan }, questions: {
+    matches_goal: { type: "noul", instructions: "Would software built exactly as described in `plan` satisfy the goal in `goal`?",
+      criteria: { true: "Every part of the goal is built by some task in the plan", false: "A part of the goal is missing or replaced by something else" } },
+    coverage: { type: "score", instructions: "How completely does `plan` cover each part of the goal in `goal`?",
+      criteria: ["Most of the goal is absent.", "The happy path only; failures and edge cases missing.",
+                 "Most parts, with one thin area.", "Every part has a task with a test.",
+                 "Every part has a task, a test, and a named failure behaviour."] },
+    missing_something: { type: "noul", instructions: "Does `plan` omit something the user must do to reach the goal in `goal`?" } } }) });
+if (!r.ok) { console.error(`Jev HTTP ${r.status}: ${(await r.text()).slice(0, 300)}`); process.exit(1); }
+const a = (await r.json()).answers;
+console.log({ verdict: a.matches_goal.noul >= 0.5 ? "YES" : "NO", ...a,
+  note: "YES needs matches_goal >= 0.5 AND coverage >= 3 AND missing_something < 0.5" });
+```
+
+- [ ] **Step 5: Verify + commit**
+
+```bash
+npm test && bash scripts/smoke.sh
+TYPESAFE_API_KEY=sk-... node scripts/jev-gate.mjs docs/superpowers/plans/2026-09-21-sql-server-qai.md
+```
+
+Expected: smoke prints `smoke ok`; the gate prints `verdict: YES` with `coverage >= 3`. If it says NO, `missing_something` names the gap in the plan — fix the task that owns it, then re-run. Commit `feat: docker, readme, jev goal gate`.
+
+---
+
+### Task 13: Browser QA with Playwright
+
+**Files:** create `playwright.config.ts`, `fixtures/sample.sqlplan`, `tests-e2e/auth.setup.ts`, `tests-e2e/analysis.spec.ts`, `tests-e2e/history.spec.ts`, `tests-e2e/responsive.spec.ts`; modify `package.json`, `.gitignore`.
+
+**Interfaces — consumes** the running app on `localhost:3000`, `.env.local` (`APP_SECRET`, `JEV_API_KEY`), the local analyst endpoint `http://192.168.88.131:8888/v1` with model `qwen3.8-flash-next` and key `EMPTY`.
+
+- [ ] **Step 1: Install**
+
+```bash
+npm i -D @playwright/test && npx playwright install chromium
+npm pkg set scripts.e2e="playwright test"
+echo ".auth/test-results/playwright-report" >> .gitignore
+```
+
+- [ ] **Step 2: `playwright.config.ts`** — reads `.env.local` itself (Playwright does not load Next's env files), boots the app, and runs the auth setup once:
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+import { readFileSync, existsSync } from "node:fs";
+
+if (existsSync(".env.local")) for (const line of readFileSync(".env.local", "utf8").split("\n")) {
+  const m = /^([A-Z_]+)=(.*)$/.exec(line.trim());
+  if (m && !process.env[m[1]]) process.env[m[1]] = m[2];
+}
+
+export default defineConfig({
+  testDir: "./tests-e2e",
+  fullyParallel: false,             // one SQLite file, one app process
+  workers: 1,
+  retries: 0,
+  timeout: 120_000,                  // real models are slow; do not paper over it with retries
+  reporter: [["list"]],
+  use: { baseURL: "http://localhost:3000", trace: "retain-on-failure" },
+  projects: [
+    { name: "setup", testMatch: /auth\.setup\.ts/ },
+    { name: "chromium", use: { ...devices["Desktop Chrome"] }, dependencies: ["setup"] },
+    { name: "mobile", use: { ...devices["Pixel 7"] }, dependencies: ["setup"] },
+  ],
+  webServer: { command: "npm run dev", url: "http://localhost:3000/api/healthz", reuseExistingServer: true,
+    env: { DATA_DIR: ".playwright-data", APP_SECRET: process.env.APP_SECRET ?? "playwright-secret-value" } },
+});
+```
+
+- [ ] **Step 3: `tests-e2e/auth.setup.ts`** — signs up, then fills Settings from the panel exactly the way a real user does (this is also the proof that keys are user-supplied, not server config):
+
+```ts
+import { test, expect } from "@playwright/test";
+
+const EMAIL = `qa+${Date.now()}@qai.test`;
+
+test("signup + first-run guide configures both models", async ({ page }) => {
+  await page.goto("/signup");
+  await page.fill('#email', EMAIL);
+  await page.fill('#password', "playwright password");
+  await page.getByRole("button", { name: "Create account" }).click();
+
+  await expect(page.getByText("Step 1 of 3")).toBeVisible();
+  await page.getByRole("link", { name: "Next" }).click();
+  await expect(page.getByText("Step 2 of 3")).toBeVisible();
+
+  await page.fill('#analyst_base_url', "http://192.168.88.131:8888/v1");
+  await page.fill('#analyst_key', "EMPTY");
+  await page.fill('#analyst_model', "qwen3.8-flash-next");
+  await page.fill('#jev_key', process.env.JEV_API_KEY ?? "");
+  await page.getByRole("button", { name: "Save" }).click();
+  await expect(page.getByText("Saved.")).toBeVisible();
+
+  await page.goto("/setup?step=3");
+  await expect(page.getByText(/Analyst ready · Jev ready/)).toBeVisible();
+  await page.context().storageState({ path: ".auth/user.json" });
+});
+
+test("signed-out visitor is pushed to login", async ({ browser }) => {
+  const ctx = await browser.newContext();
+  await ctx.goto("/app");
+  expect(ctx.pages[0].url()).toContain("/login");
+  await ctx.close();
+});
+```
+
+- [ ] **Step 4: `fixtures/sample.sqlplan`** — copy the `PLAN` template string from `tests/digest.test.ts` into this file, and save it **with a UTF-8 BOM** so the file-upload path is tested against the byte order mark real SSMS files carry.
+
+- [ ] **Step 5: `tests-e2e/analysis.spec.ts`**
+
+```ts
+import { test, expect } from "@playwright/test";
+import { readFileSync } from "node:fs";
+
+const xml = readFileSync("fixtures/sample.sqlplan", "utf8");
+test.use({ storageState: ".auth/user.json", permissions: ["clipboard-read", "clipboard-write"] });
+
+test("full run: paste → stages → Jev verdict → rendered report", async ({ page }) => {
+  await page.goto("/app");
+  await page.fill('#xml', xml);
+  await page.fill('#note', "QA run");
+  await page.getByRole("button", { name: "Analyse" }).click();
+
+  await expect(page.getByText(/1 of 4|2 of 4|3 of 4|4 of 4/)).toBeVisible({ timeout: 15_000 });
+  await expect(page.locator('#report')).toBeVisible({ timeout: 120_000 });
+
+  // Jev decided, or honestly did not — either way the report must say which.
+  await expect(page.locator('#report').getByText(/First move/)).toBeVisible();
+  // The report is OpenUI elements, not a markdown blob.
+  expect(await page.locator('#report .card, #report h2, #report table').count()).toBeGreaterThan(2);
+  // At least one copyable SQL block.
+  expect(await page.locator('#report pre.sql').count()).toBeGreaterThan(0);
+
+  await page.getByRole("button", { name: "Copy SQL" }).first().click();
+  expect(await page.evaluate(() => navigator.clipboard.readText())).toContain("SELECT");
+
+  await page.getByRole("button", { name: "Export to PDF" }).click();   // window.print()
+  await page.emulateMedia({ media: "print" });
+  await expect(page.locator('.rail')).toBeHidden();
+  await expect(page.locator('.toolbar')).toBeHidden();
+});
+
+test("a pasted SQL script is refused with a named reason", async ({ page }) => {
+  await page.goto("/app");
+  await page.fill('#xml', "SELECT * FROM dbo.Orders WHERE CustomerId = 42;");
+  await page.getByRole("button", { name: "Analyse" }).click();
+  await expect(page.getByRole("alert").getByText(/ShowPlan XML/)).toBeVisible({ timeout: 20_000 });
+  await expect(page.locator('#report')).toHaveCount(0);
+});
+
+test("a dropped .sqlplan file decodes and is accepted", async ({ page }) => {
+  await page.goto("/app");
+  await page.setInputFiles('input[type="file"]', "fixtures/sample.sqlplan");
+  expect(await page.locator('#xml').inputValue()).toContain("ShowPlanXML");
+  expect(await page.locator('#xml').inputValue()).not.toContain("\u0000");
+});
+
+test("reopening history renders the stored report with no new run", async ({ page }) => {
+  await page.goto("/app");
+  await page.locator('.rail a[href^="/app/"]').first().click();
+  await expect(page.locator('#report, [data-verdict]').first()).toBeVisible({ timeout: 20_000 });
+  await expect(page.getByRole('button', { name: 'Analyse' })).toHaveCount(0);
+});
+```
+
+- [ ] **Step 6: `tests-e2e/history.spec.ts` and `tests-e2e/responsive.spec.ts`**
+
+```ts
+// history.spec.ts
+import { test, expect } from "@playwright/test";
+test.use({ storageState: ".auth/user.json" });
+
+test("rename sticks, delete asks first then removes", async ({ page }) => {
+  await page.goto("/app");
+  const row = page.locator('.rail li').first();
+  await row.locator('input[name="title"]').fill("Renamed by QA");
+  await row.getByRole("button", { name: "Save" }).click();
+  await expect(page.locator('.rail', { hasText: "Renamed by QA" })).toBeVisible();
+
+  const before = await page.locator('.rail li').count();
+  let asked = false;
+  page.once("dialog", async (d) => { asked = true; await d.dismiss(); });   // refuse: nothing must vanish
+  await page.locator('.rail li').first().getByRole("button", { name: "Delete" }).click();
+  await page.waitForTimeout(500);
+  expect(asked).toBe(true);
+  expect(await page.locator('.rail li').count()).toBe(before);
+
+  page.once("dialog", async (d) => { await d.accept(); });
+  await page.locator('.rail li').first().getByRole("button", { name: "Delete" }).click();
+  await expect.poll(async () => page.locator('.rail li').count(), { timeout: 15_000 }).toBe(before - 1);
+});
+```
+
+```ts
+// responsive.spec.ts
+import { test, expect } from "@playwright/test";
+test.use({ storageState: ".auth/user.json" });
+
+for (const width of [320, 375, 414, 768]) {
+  test(`no horizontal scroll at ${width}px`, async ({ page }) => {
+    await page.setViewportSize({ width, height: 800 });
+    await page.goto("/app");
+    const over = await page.evaluate(() => document.documentElement.scrollWidth
+      - document.documentElement.clientWidth);
+    expect(over).toBeLessThanOrEqual(0);
+    await expect(page.getByRole('button', { name: 'Analyse' })).toBeVisible();
+    const box = await page.getByRole('button', { name: 'Analyse' }).boundingBox();
+    expect(box!.width).toBeGreaterThanOrEqual(100);          // never two-line tap targets
+  });
+}
+
+test("every field has a visible label", async ({ page }) => {
+  await page.goto("/settings");
+  const orphans = await page.evaluate(() => [...document.querySelectorAll('input')]
+    .filter((i) => !i.id || !document.querySelector(`label[for="${i.id}"]`)).length);
+  expect(orphans).toBe(0);
+});
+```
+
+- [ ] **Step 7: Run it, then commit**
+
+```bash
+npm run dev &        # reuseExistingServer keeps this instance
+npm run e2e
+```
+
+Expected: setup, then chromium and mobile suites green. A red `full run` is worth reading before touching code — it means the report never rendered, and the SSE frames from `curl -sN` will say which stage stopped. Commit `test: playwright end-to-end qa`.
+
+---
+
+## Self-Review notes (already run against the spec)
+
+- **Spec coverage.** Requirements 1–3 → Tasks 3, 11. 4 → Task 6. 5 → Task 7. 6–7 → Task 8. 8 → Tasks 2, 10, 11 (stored replay). 9 → Tasks 10, 11 (staged SSE). 10 → Task 12. Copy + PDF → Task 11, verified in Task 13. Setup guide + per-user keys in the settings panel → Task 5, exercised end to end by `auth.setup.ts`. History rename/delete → Tasks 2, 11, verified in Task 13. Non-goals are never built: no SQL Server connection, no sharing, no billing, no weights UI.
+- **Placeholders.** None. Task 6 step 4 and Task 13 step 4 are the only steps that depend on a real artefact you supply (one `.sqlplan` from SSMS); both say what to do when it is absent instead of leaving a hole.
+- **Type consistency.** `Candidate`, `Digest`, `AnalystConfig`, `Verdict` are each defined once (Tasks 7, 6, 4, 8) and only imported afterwards. `digestForModel` is the single payload shaper for both models. `readSse`/`sse` are defined once in `lib/stream.ts` and used by both ends.
+- **Review Focus.** 1 → digest test (`rejects input that is not a plan`) + Task 13's refused-script test. 2 → analyst tests (`names the stage on auth, prose, and shape failures`). 3 → jev tests (`the unsafe option is flagged and cannot lead`, `an unknown jev choice label falls back`). 4 → digest test (`digestForModel stays bounded`) + `MAX_BODY_BYTES` in the route. 5 → jev tests (`fallback ranks without Jev`, unknown label) + Task 10 step 5's invalidated-key check.
+- **Fixed after the first Jev gate run (NO, coverage 3.2, runnable-as-written 0.11).** ShowPlan attribute spellings were wrong (`EstimatedIO`/`EstimatedCPU` are really `EstimateIO`/`EstimateCPU`), now a fall-through chain plus a real-`.sqlplan` test. Three "fix this line as you write it" hedges are gone — the correct code is inline. Jev's unknown-choice-label branch had no test; it does now. Weights now carry their provenance and the README names them as the tuning knob. Task 13 (browser QA) and the analyst endpoint facts added.
+
diff --git a/kb/raw/2026-09-21-sql-server-qai-spec.md b/kb/raw/2026-09-21-sql-server-qai-spec.md
new file mode 100644
index 0000000..aae18f1
--- /dev/null
+++ b/kb/raw/2026-09-21-sql-server-qai-spec.md
@@ -0,0 +1,114 @@
+# SQL Server qAI — Spec
+
+**Date:** 2026-09-21
+**Owner:** ahmedmohammed
+**Status:** agreed in chat, this file is the spec of record
+
+## Goal (verbatim from the owner)
+
+> portal that take xml of sql server query plan and use power of generative ai to
+> analysis provide multiple action steps, multiple query rewrite if possible,
+> Jev then rank and decide.
+
+## What it is
+
+A containerised web tool. A DBA or consultant logs in, pastes a SQL Server
+execution plan (Showplan XML, or a `.sqlplan` file), and gets back:
+
+1. What the plan says is wrong (bottleneck, missing indexes, spills, bad row guesses).
+2. **Multiple** candidate action plans — several different remediations, not one.
+3. **Multiple** candidate SQL rewrites where a rewrite is possible.
+4. A **Jev**-ranked verdict: which candidate to run first, with typed probabilities
+   and confidence, and why.
+5. One final "best fast path": the recommended SQL and the steps to apply it.
+6. The result rendered as **structured UI elements** (OpenUI Lang → React), not a
+   wall of markdown. Export to PDF, copy to clipboard.
+
+The demo value is Jev as the decision-maker: the generative model proposes,
+**Jev disposes**. Every ranking number on screen is a typed judgment from
+`POST /v1/systemone`, not a string the LLM wrote.
+
+## Product surface
+
+| Screen | Job |
+| --- | --- |
+| `/signup`, `/login` | Email + password. Nothing else. |
+| `/setup` | First-run guide: 3 steps — analyst model, Jev, done. |
+| `/app` | Left rail = previous analyses (rename, delete). Main = paste plan → run → live report. |
+| `/settings` | Update analyst model (base URL, key, model, extra params), Jev (key, model), email/password, history. |
+
+Report actions: **Export to PDF**, **Copy**. History actions: **rename**, **delete**.
+
+### Getting the input, and the two keys
+
+The portal cannot reach the SQL Server. The user brings the plan XML, and the app must say so in the run screen:
+SSMS → **Ctrl+M** (include actual execution plan) → run the query → save the Execution Plan tab as `.sqlplan`, or
+copy the Showplan XML cell; without SSMS, prefix the batch with `SET STATISTICS XML ON;` and copy the XML result
+cell. A `.sqlplan` file can be dropped in (SSMS writes UTF-16 with a BOM; decode both) or pasted.
+
+Both model credentials are typed by the logged-in user in `/setup` or `/settings` — never server config, so every
+user brings their own analyst endpoint and their own TypeSafe/Jev key (`console.typesafe.ai/keys`). Stored keys come
+back masked, and a blank field means keep the stored one. Nothing leaves the container except the digest, and only
+to the endpoints that user configured.
+
+## Actors (two models, strict roles)
+
+- **Analyst** — any OpenAI-compatible endpoint the user configures (`base_url`,
+  `key`, `model`, extra params). Generates: candidate action plans, candidate SQL
+  rewrites, and the final OpenUI Lang report. Text in, text out.
+- **Jev** — TypeSafe System One (`@typesafe-ai/sdk`, model `jev-latest`). Never
+  generates prose. Answers typed questions (`score`, `choice`, `noul`) about each
+  candidate and returns probabilities + confidence. Code combines them.
+
+## Requirements
+
+1. Auth: signup, login, logout, session survives reload. Per-user data isolation.
+2. Credentials at rest are encrypted (AES-256-GCM, `APP_SECRET` env). Never echoed
+   to the browser — masked (`••••1234`).
+3. Plan input: paste XML, or drop/select a `.sqlplan`/`.xml` file. Clear inline
+   error if it is not a ShowPlanXML document.
+4. Deterministic digest first, model second: parse the XML in code (operators,
+   costs, missing indexes, warnings, waits, spills, estimate vs actual). The model
+   sees the digest, never 40 MB of XML.
+5. 2–4 candidates per run. Each candidate: diagnosis, ordered actions with effort
+   and change-control flag, optional rewrite SQL, expected effect.
+6. Jev judges every candidate in parallel on 4 dimensions, then a second call picks
+   `first_to_run` across all candidates. Composite weights live in code, visible in UI.
+7. Safety gate: a candidate Jev rates as semantically unsafe is never presented as
+   the recommended path without a visible "verify results before deploying" flag.
+8. History: every run persisted (input digest, candidates, Jev verdict, rendered
+   report). Reopening a history item replays the stored report — zero model calls.
+9. Streaming: stage indicator while digesting/proposing/judging, then the report
+   renders token-by-token. No spinner-for-30-seconds.
+10. Single container: `docker compose up` → one image, one `/data` volume, no
+    external DB, no queue, no Redis.
+
+## Non-goals
+
+- No live connection to SQL Server. No plan-from-cache lookup. No automatic index
+  creation. No multi-user teams, roles, or sharing. No billing. No mobile app.
+  No markdown editor. No prompt marketplace. No agentic loop with tool calls.
+
+## Success looks like
+
+Paste a real slow-query plan → under 60 s → a ranked set of remediations where the
+top pick is defensible because Jev's probabilities are on screen, and the winning
+SQL is one click from the clipboard.
+
+## Acceptance
+
+What has to be true before this counts as done, and how each part is proven:
+
+- **Offline unit suites** (`npm test`, no keys, no network): a real ShowPlan digests to the right numbers; input
+  that is not a plan is refused with a named reason; analyst output is schema-checked and 2–4 options are enforced;
+  Jev's scores rank, an unknown Jev label cannot lead, and a silent Jev degrades to a labelled composite order;
+  credentials seal/open/mask and a blank field never wipes a stored key.
+- **One live run** against the user's real analyst endpoint and a real Jev key: every SSE stage fires, several
+  candidates come back, Jev returns a verdict with confidence, and OpenUI Lang arrives in deltas.
+- **Browser QA** (Chromium): signup → guide → settings → run → rendered report; Copy puts SQL on the clipboard;
+  print emulation flips to paper and hides the rail and buttons; rename sticks and delete confirms first; no
+  horizontal scroll from 320 px up.
+- **A smoke script** (`scripts/smoke.sh`) that a container or a plain `npm start` both pass: health, auth pages,
+  signed-out redirect, and `/api/analyze` refusing an anonymous caller.
+- **A goal gate**: Jev scores the written plan against the goal in this document and answers the named-gap question
+  with `nothing` before implementation starts.
diff --git a/kb/raw/README.md b/kb/raw/README.md
new file mode 100644
index 0000000..495e7d5
--- /dev/null
+++ b/kb/raw/README.md
@@ -0,0 +1,112 @@
+# SQL Server qAI
+
+Paste a SQL Server ShowPlan XML (or drop a `.sqlplan`), get a report with several ranked remediation options and
+rewritten queries. Two models, one job: a **generative analyst model** proposes the options and writes the report, and
+**Jev** (TypeSafe System One) scores every option and decides which one to run first. Jev never writes SQL; it returns
+typed scores, a choice, and confidences. The report renders as OpenUI elements, not a markdown blob.
+
+## Pipeline
+
+1. `lib/digest.ts` parses the XML in code: top operators, missing indexes, warnings, waits, estimate-vs-actual row
+   errors, tables, statement text, subtree cost, parallelism. Raw XML never reaches a model.
+2. The analyst model receives the digest JSON and proposes 2–4 genuinely different options (index, rewrite, statistics,
+   parallelism, schema), each with ordered action steps and an optional rewrite.
+3. Jev answers four questions per option (`bottleneck_fit`, `semantic_safety`, `ease` `score`; `root_cause` `noul`) and
+   one cross-option call (`first_to_run` `choice`, `anything_worth_running` `noul`).
+4. `lib/jev.ts` combines them with visible weights (0.40 / 0.30 / 0.15 / 0.15 — four numbers in that file, the only
+   tuning knob) and prints a verdict. Jev's pick leads only when its confidence clears 0.5; otherwise the report says
+   the order came from composite scoring.
+5. The analyst streams the final report as OpenUI Lang; `<Renderer>` paints it as it arrives.
+
+Getting the XML: SSMS → **Ctrl+M** (include actual execution plan) → run the query → right-click the Execution Plan tab
+→ *Save As .sqlplan*. No SSMS: prefix the batch with `SET STATISTICS XML ON;` and copy the XML result cell.
+
+## Run it
+
+This repo runs as a plain Node process. `Dockerfile` and `docker-compose.yml` are ready, but the image has **not
+been built or run on this machine** (Docker is not installed here); treat it as untested until
+`bash scripts/smoke.sh --docker` says otherwise. Local work is `npm run dev`.
+
+```bash
+npm install
+cp .env.example .env.local     # then fill in APP_SECRET and DATA_DIR
+npm run dev                    # http://localhost:3000
+bash scripts/smoke.sh          # healthz, login page, signed-out redirect, analyze needs a session
+```
+
+`.env.local`:
+
+| key | why |
+| --- | --- |
+| `APP_SECRET` | ≥16 chars. Encrypts API keys at rest (AES-256-GCM). Changing it makes stored keys unreadable. |
+| `DATA_DIR` | where `qai.db` (SQLite, `node:sqlite`) lives. Default `./data`. Docker uses `/data`. |
+| `COOKIE_SECURE` | set to `1` only when the app is served over https without a proxy that sets `X-Forwarded-Proto`. The session cookie is `Secure` when that header says `https`; forcing it on plain http makes Safari refuse to store it. |
+
+Model keys are **not** config. Each user types them in the app (first-run guide or `/settings`), so a second user
+brings their own endpoint and their own spend. Blank key field = keep the stored key.
+
+- Analyst: any OpenAI-compatible base URL + key + model, plus optional extra JSON params.
+  A local endpoint such as `http://192.168.88.131:8888/v1` works; use key `EMPTY` when the server has no auth.
+  For a reasoning model (Qwen3 on vLLM) put `{"chat_template_kwargs":{"enable_thinking":false}}` in **Extra params**:
+  with thinking on, the model spends the whole context budget reasoning and the report arrives empty.
+  Both model calls default to `max_tokens: 2048`; the same field overrides it.
+- Jev: a TypeSafe API key from `console.typesafe.ai/keys`, model usually `jev-latest`.
+
+## Tests
+
+```bash
+npm test          # node --test on tests/*.test.ts, no test framework installed
+npm run build     # production build + type check
+npm run e2e       # builds first, then Playwright against the production server
+```
+
+The unit suites run offline: the analyst and Jev are exercised through injected `fetch`, so no key and no network.
+`npm run e2e` is the opposite — `pree2e` builds, then Playwright drives `npm run start` (the production server,
+not `next dev`: cookie flags and hydration differ, and that difference once hid a sign-out bug) against the real
+models. It reads `JEV_API_KEY` from `.env.local`. Expect it to be slow; that is the models, not the harness.
+
+Projects: `chromium` (everything except the session spec, reusing one signed-in session), `webkit` (Safari —
+session survival only, because it is the one engine that rejects a `Secure` cookie over `http://localhost`),
+and `mobile` (Pixel 7, layout only, so no model run is paid for twice).
+
+`tests/digest.test.ts` skips unless a genuine plan exists at `fixtures/real.sqlplan`. Drop one there from SSMS and the
+skip becomes the real check on ShowPlan attribute spellings.
+
+## Git remote (Gitea)
+
+Origin points at the self-hosted Gitea:
+
+```bash
+git remote -v                       # http://192.168.88.39:3000/ahmed/sql-server-query-ai.git
+git push origin feat/sql-server-qai
+```
+
+The remote URL deliberately contains **no password**. Git prompts for the username (`ahmed`) and password the first
+time, or you can keep them out of prompts:
+
+```bash
+git config credential.helper osxkeychain        # remember them locally
+git push origin feat/sql-server-qai
+```
+
+Never commit the password into `.git/config`, a remote URL, or this README — a stored credential in the repo is
+readable by whoever you hand the repo to. If you want it non-interactive in CI, create a Gitea token
+(Settings → Applications) and use `http://192.168.88.39:3000/ahmed/sql-server-query-ai.git` with the token as password.
+
+## Layout
+
+```
+lib/digest.ts      XML → bounded digest (the only shape models see)
+lib/analyst.ts     propose 2–4 options; stream the final OpenUI report
+lib/jev.ts         questions, weights, ranking, verdict, fallback
+lib/report-ui.tsx  OpenUI component library — the same module builds the prompt and renders the answer
+lib/db.ts          node:sqlite: users, sessions, settings, analyses
+lib/vault.ts       AES-256-GCM seal/open/mask for credentials
+lib/auth.ts        scrypt passwords, hashed session tokens (DB stores the SHA-256, never the token)
+app/api/analyze    SSE pipeline: digesting → proposing → judging → writing
+tests/             offline unit suites      tests-e2e/  Playwright
+docs/superpowers/  spec + the 13-task implementation plan this was built from
+```
+
+Design: dark terminal console, JetBrains Mono for data, IBM Plex Sans for prose, one phosphor accent.
+Print stylesheet flips to paper white and drops the rail, buttons and chrome — that is the Export to PDF path.
diff --git a/kb/raw/design-master.md b/kb/raw/design-master.md
new file mode 100644
index 0000000..d92ebfd
--- /dev/null
+++ b/kb/raw/design-master.md
@@ -0,0 +1,233 @@
+# Design System Master File
+
+> **LOGIC:** When building a specific page, first check `design-system/pages/[page-name].md`.
+> If that file exists, its rules **override** this Master file.
+> If not, strictly follow the rules below.
+
+---
+
+**Project:** SQL Server qAI
+**Generated:** 2026-09-21 12:56:55
+**Category:** Developer Tool / IDE
+**Design Dials:** Variance 4/10 (Balanced / Modern) | Motion 3/10 (Subtle) | Density 8/10 (Dense / Dashboard)
+
+---
+
+## Global Rules
+
+### Color Palette
+
+| Role | Hex | CSS Variable |
+|------|-----|--------------|
+| Primary | `#1E293B` | `--color-primary` |
+| On Primary | `#FFFFFF` | `--color-on-primary` |
+| Secondary | `#334155` | `--color-secondary` |
+| On Secondary | `#FFFFFF` | `--color-on-secondary` |
+| Accent/CTA | `#22C55E` | `--color-accent` |
+| On Accent/CTA | `#0F172A` | `--color-on-accent` |
+| Background | `#0F172A` | `--color-background` |
+| Foreground | `#F8FAFC` | `--color-foreground` |
+| Card | `#1B2336` | `--color-card` |
+| Card Foreground | `#F8FAFC` | `--color-card-foreground` |
+| Muted | `#272F42` | `--color-muted` |
+| Muted Foreground | `#94A3B8` | `--color-muted-foreground` |
+| Border | `#475569` | `--color-border` |
+| Destructive | `#EF4444` | `--color-destructive` |
+| On Destructive | `#000000` | `--color-on-destructive` |
+| Ring | `#FFFFFF` | `--color-ring` |
+
+**Color Notes:** Code dark + run green
+
+### Typography
+
+- **Heading Font:** JetBrains Mono
+- **Body Font:** IBM Plex Sans
+- **Mood:** code, developer, technical, precise, functional, hacker
+- **Google Fonts:** [JetBrains Mono + IBM Plex Sans](https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap)
+
+**CSS Import:**
+```css
+@import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap');
+```
+
+### Spacing Variables
+
+*Density: 8/10 — Dense / Dashboard*
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `--space-xs` | `2px` / `0.125rem` | Tight gaps |
+| `--space-sm` | `4px` / `0.25rem` | Icon gaps, inline spacing |
+| `--space-md` | `8px` / `0.5rem` | Standard padding |
+| `--space-lg` | `12px` / `0.75rem` | Section padding |
+| `--space-xl` | `16px` / `1rem` | Large gaps |
+| `--space-2xl` | `24px` / `1.5rem` | Section margins |
+| `--space-3xl` | `32px` / `2rem` | Hero padding |
+
+### Shadow Depths
+
+| Level | Value | Usage |
+|-------|-------|-------|
+| `--shadow-sm` | `0 1px 2px rgba(0,0,0,0.05)` | Subtle lift |
+| `--shadow-md` | `0 4px 6px rgba(0,0,0,0.1)` | Cards, buttons |
+| `--shadow-lg` | `0 10px 15px rgba(0,0,0,0.1)` | Modals, dropdowns |
+| `--shadow-xl` | `0 20px 25px rgba(0,0,0,0.15)` | Hero images, featured cards |
+
+---
+
+## Component Specs
+
+### Buttons
+
+```css
+/* Primary Button */
+.btn-primary {
+  background: #22C55E;
+  color: white;
+  padding: 12px 24px;
+  border-radius: 8px;
+  font-weight: 600;
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+
+.btn-primary:hover {
+  opacity: 0.9;
+  transform: translateY(-1px);
+}
+
+/* Secondary Button */
+.btn-secondary {
+  background: transparent;
+  color: #1E293B;
+  border: 2px solid #1E293B;
+  padding: 12px 24px;
+  border-radius: 8px;
+  font-weight: 600;
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+```
+
+### Cards
+
+```css
+.card {
+  background: #0F172A;
+  border-radius: 12px;
+  padding: 24px;
+  box-shadow: var(--shadow-md);
+  transition: all 200ms ease;
+  cursor: pointer;
+}
+
+.card:hover {
+  box-shadow: var(--shadow-lg);
+  transform: translateY(-2px);
+}
+```
+
+### Inputs
+
+```css
+.input {
+  padding: 12px 16px;
+  border: 1px solid #E2E8F0;
+  border-radius: 8px;
+  font-size: 16px;
+  transition: border-color 200ms ease;
+}
+
+.input:focus {
+  border-color: #1E293B;
+  outline: none;
+  box-shadow: 0 0 0 3px #1E293B20;
+}
+```
+
+### Modals
+
+```css
+.modal-overlay {
+  background: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(4px);
+}
+
+.modal {
+  background: white;
+  border-radius: 16px;
+  padding: 32px;
+  box-shadow: var(--shadow-xl);
+  max-width: 500px;
+  width: 90%;
+}
+```
+
+---
+
+## Style Guidelines
+
+**Style:** Dark Mode (OLED)
+
+**Keywords:** Dark theme, low light, high contrast, deep black, midnight blue, eye-friendly, OLED, night mode, power efficient
+
+**Best For:** Night-mode apps, coding platforms, entertainment, eye-strain prevention, OLED devices, low-light
+
+**Key Effects:** Minimal glow (text-shadow: 0 0 10px), dark-to-light transitions, low white emission, high readability, visible focus
+
+### Page Pattern
+
+**Pattern Name:** FAQ/Documentation Landing
+
+- **Conversion Strategy:** Reduce support tickets. Track search analytics. Show related articles. Contact escalation path.
+- **CTA Placement:** Search bar prominent + Contact CTA for unresolved questions
+- **Section Order:** Hero with search bar > Popular categories > FAQ accordion > Contact/support CTA
+
+---
+
+## Motion
+
+**Scroll Reveal** (Subtle) — Trigger: scroll (viewport enter) | Duration: 300-400ms | Easing: `power1.out`
+
+```js
+gsap.from(el, { opacity: 0, y: 12, duration: 0.35, ease: 'power1.out', scrollTrigger: { trigger: el, start: 'top 90%', toggleActions: 'play none none reverse' } });
+```
+
+**Framework notes:** Requires the ScrollTrigger plugin registered once via gsap.registerPlugin(ScrollTrigger); Use matchMedia('(prefers-reduced-motion: reduce)') to skip non-essential motion and render the final state immediately
+
+- ✅ Keep the y offset small (8-16px) so it reads as a fade, not a slide
+- ❌ Don't reveal below-the-fold content needed for SEO/crawlers as invisible-by-default without a no-JS fallback
+- ⚡ toggleActions 'play none none reverse' avoids re-triggering on every scroll direction change
+
+---
+
+## Anti-Patterns (Do NOT Use)
+
+- ❌ Light mode default
+- ❌ Slow performance
+
+### Additional Forbidden Patterns
+
+- ❌ **Emojis as icons** — Use SVG icons (Heroicons, Lucide, Simple Icons)
+- ❌ **Missing cursor:pointer** — All clickable elements must have cursor:pointer
+- ❌ **Layout-shifting hovers** — Avoid scale transforms that shift layout
+- ❌ **Low contrast text** — Maintain 4.5:1 minimum contrast ratio
+- ❌ **Instant state changes** — Always use transitions (150-300ms)
+- ❌ **Invisible focus states** — Focus states must be visible for a11y
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering any UI code, verify:
+
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] `cursor-pointer` on all clickable elements
+- [ ] Hover states with smooth transitions (150-300ms)
+- [ ] Light mode: text contrast 4.5:1 minimum
+- [ ] Focus states visible for keyboard navigation
+- [ ] `prefers-reduced-motion` respected
+- [ ] Responsive: 375px, 768px, 1024px, 1440px
+- [ ] No content hidden behind fixed navbars
+- [ ] No horizontal scroll on mobile
diff --git a/kb/raw/sdd-progress.md b/kb/raw/sdd-progress.md
new file mode 100644
index 0000000..fe5289c
--- /dev/null
+++ b/kb/raw/sdd-progress.md
@@ -0,0 +1,84 @@
+# SDD ledger — plan: docs/superpowers/plans/2026-09-21-sql-server-qai.md
+
+Ruling: no Docker on this machine (human says limited resources) — write Dockerfile/.dockerignore in Task 12 but never build or run it here; verify with npm run dev + npm start. Ruling: drop Tailwind — the plan styles with tokens.css + semantic classes only, so @tailwindcss/postcss and tailwindcss are uninstalled and postcss.config.mjs deleted. Cost if wrong: we hand-write CSS we would otherwise generate.
+Task 1: complete (commits 2778ce7..f64dc31, tests: npm run build → ƒ  (Dynamic)  server-rendered on demand)
+Task 1: Ruling: no next/font/google — fonts come from the token stack only (JetBrains Mono / IBM Plex Sans if installed, else system mono+sans). Build stays offline-safe and one network dependency lighter — cost if wrong: brand fonts missing on machines without them.
+Task 1: Ruling: tokens.css lives at app/tokens.css (the @import in globals.css resolves there); the duplicate root copy is deleted — cost if wrong: none.
+Task 1: Ruling: app/page.tsx is a plain redirect("/login") because lib/auth does not exist yet; Task 3 replaces it with the session-aware redirect its brief omits — cost if wrong: signed-in users hitting / land on /login until Task 3.
+Task 1: Ruling: deps are next/react/react-dom/zod/@openuidev/react-lang/@typesafe-ai/sdk/fast-xml-parser. lucide-react skipped (no plan code imports it) and Tailwind dropped (see setup ruling) — cost if wrong: add lucide-react the moment an icon is drawn.
+Task 1: Note: env fix, not a code fix — node_modules/@next/swc-darwin-arm64 came down truncated (33MB of 89MB) so `next build` died with "Turbopack requires native bindings"; reinstalled with npm i --no-save @next/swc-darwin-arm64@16.3.5.
+Task 2: Ruling: patchAnalysis filters keys against a PATCHABLE whitelist — the brief interpolated object keys straight into the SET clause, and one caller that ever passes a request-shaped object would own a SQL injection. Cost if wrong: a new patchable column needs adding to the set.
+Task 2: Ruling: test script is `node --no-warnings --test tests/*.test.ts` (the plan's own line). `node --test tests` fails with MODULE_NOT_FOUND on node 25 in this repo — the space in the path makes Node resolve the directory as a module.
+Task 2: complete (commits f64dc31..692ffa9, tests: npm test → ℹ duration_ms 109.10725)
+Task 3: Ruling: lib/auth.ts imports ./db.ts (relative, .ts extension) and loads next/headers + next/navigation lazily — `node --test` imports this module, and bare node resolves neither `@/…` nor `next/*`. tsconfig gains allowImportingTsExtensions. Next-only glue (actions, pages, components) keeps @/. Cost if wrong: every test-imported module must keep this discipline.
+Task 3: Ruling: requireUser declares Promise<{id,email}> with an unreachable throw after redirect(), because redirect() behind a dynamic import is not typed `never`. Cost if wrong: dead line, no behaviour change (redirect throws anyway).
+Task 3: Ruling: AuthForm's action is (state: FormResult, fd) => Promise<FormResult> and the server actions take `_: unknown` — the brief's `_: void` does not type-check against useActionState, which passes the previous state.
+Task 3: Ruling: app/app/layout.tsx awaits requireUser now (the guard the brief only asserts as a manual check). Task 11 may write it again; it is idempotent.
+Task 3: Note: signUp/signIn redirect to /setup, which Task 5 creates. Until then that redirect lands on 404. Verified now: signed-out /app -> 307 /login, /login 200, /signup renders the password help.
+Task 3: complete (commits 692ffa9..5f8746c, tests: npm test → ℹ duration_ms 190.291833)
+Task 4: Ruling: db.saveSettings now keeps the stored secret when the incoming one is blank (COALESCE(NULLIF(excluded.x,''), settings.x)) instead of overwriting it. The brief only protected against this in lib/settings.ts; the shared upsert is where a later caller (Task 5's password change) would have wiped both keys with one omitted field. Test: "saveSettings never blanks a stored secret, whoever calls it" — RED before the fix. Cost if wrong: a future "clear my key" feature needs an explicit sentinel instead of "".
+Task 4: Ruling: lib/settings.ts imports ./db.ts and ./vault.ts (test-imported module, same discipline as Task 3).
+Task 4: complete (commits 5f8746c..dd6b880, tests: npm test → ℹ duration_ms 455.936167)
+Task 5: Ruling: /setup only auto-forwards to /app for steps 1 and 2; ?step=3 still renders after onboarding. The brief's unconditional redirect made the readiness screen unreachable exactly when it matters (Task 13 opens it after saving keys). Cost if wrong: one extra clickable step for a configured user.
+Task 5: Verified: signed-in /settings shows ••••1234 and ••••9999 (masked, never raw); anon /settings -> 307 /login; onboarded /setup and /setup?step=2 -> 307 /app; /setup?step=3 -> 200.
+Task 5: complete (commits dd6b880..1c3f222, tests: npm test → ℹ duration_ms 464.65375)
+Task 6: Ruling: tables and missing-index tables are rebuilt as Database.Schema.Table. The brief joined only the bracket-stripped Table attribute, so the digest named "Orders" where the test (and any DBA reading the report) needs "wide.Sales.Orders". RED first: actual ['Orders','Customer']. Cost if wrong: none, the fixture asserts the joined form.
+Task 6: Note: no genuine .sqlplan exists on this machine (no SQL Server to export one from), so "a real .sqlplan digests" skips with a printed reason and the commit message says so. Someone with SSMS should drop one at fixtures/real.sqlplan; that test is the check on attribute spellings.
+Task 6: complete (commits 1c3f222e..4fefd0f, tests: npm test → ℹ duration_ms 451.9635)
+Task 7: Ruling: lib/analyst.ts imports ./digest.ts and ./settings.ts (test-imported module discipline from Task 3).
+Task 7: Note: partner asked for the Gitea remote mid-task. origin = http://192.168.88.39:3000/ahmed/sql-server-query-ai.git with no credential stored in .git/config; pushed main and feat/sql-server-qai once with inline credentials. README documents the remote and credential hygiene.
+Task 7: complete (commits 4fefd0f..816f22c, tests: npm test → ℹ duration_ms 482.014)
+Task 8: Verified against live Jev (jev-1.13, real key, real digest): 1.3s, picked idx_covering_orders with confidence 1.00, composite agreed, TOP-100 rewrite scored semantic_safety 0.05 and flagged. makeJevClient/score/noul/choice work as the brief specifies.
+Task 8: Ruling: verify_semantics now fires only where semantics can move — any option carrying rewrite_sql below 0.6, or any option below 0.45. Evidence: live Jev scored the index create 0.57 ("equivalent, no stated proof"), so the brief's blanket <0.6 floor would flag nearly every index option and the warning would become noise. Test "verify_semantics fires where semantics can actually move" RED→GREEN. Cost if wrong: a genuinely risky non-rewrite change (e.g. dropping an index used elsewhere) scores 0.45-0.6 and goes unflagged; the option table still prints its safety bar.
+Task 8: Ruling: jevFallback strips score-derived flags (kept change_control, which is read off the candidate's own actions). Neutral 0 scores meant "Jev never spoke", not "this option is unsafe" — the brief's fallback accused every option. Test added, RED→GREEN.
+Task 8: Ruling: rubric arrays are `as const` — the SDK types ScoreCriteria as a non-empty readonly tuple, so a plain string[] fails `next build`'s type check even though the call works at runtime.
+Task 8: complete (commits 816f22c..d8caa8e, tests: npm test → ℹ duration_ms 504.103542)
+Task 9: Ruling: the library is lib/report-ui.ts written with createElement, not lib/report-ui.tsx with JSX. Node strips types but not JSX, so the brief's own test (`await import("../lib/report-ui.tsx")` under node --test) can never load a JSX file without adding a transpiler to the dep list. Same components, props, prompt and refs; only the call syntax changed. Cost if wrong: slightly noisier component bodies.
+Task 9: complete (commits d8caa8e..396b0ed, tests: npm test → ℹ duration_ms 500.095583)
+Task 9: Follow-up fix (found by `npm run build`, not by the tests): lib/db.ts opened SQLite and ran DDL at import, so next build's ~6 page-data workers hit "database is locked" and the build failed. Now the file opens on first query behind a bound Proxy, plus PRAGMA busy_timeout=5000. RED evidence: build exit 1 with "Failed to collect configuration for / [cause]: database is locked"; after the change build exits 0 and the suite is green (the Proxy had to bind methods — first attempt failed 4 tests with "Illegal invocation"). Cost if wrong: a long build-time query would still wait, which is what busy_timeout is for.
+Task 10: complete (commits 13bd2e6..ac4cbdd, tests: npm test → ℹ duration_ms 531.938)
+Task 10: Verified live, single run against the real analyst + real Jev: 41s end to end — stage digesting → 3 candidates → verdict {source: jev, headline: idx_covering_orders, confidence 1.00, composite agrees} → 2861 chars of OpenUI streamed in ~15 deltas → done {id}. Stored row replayed from /app/<id> renders the full report.
+Task 10: Ruling: the brief said "no cancel() handler, the default is right". It is not. enqueue() on an abandoned ReadableStream does not throw, so a producer whose browser closed keeps firing multi-minute analyst calls; two ghost runs piled onto the local vLLM and a fresh request sat in "proposing" for 10+ minutes behind them. Now: cancel() sets a flag, aborts the in-flight fetch through an AbortController (proposeCandidates/streamReport take an optional signal), the row is stored as partial/abandoned, and no further stage starts. Cost if wrong: an abandoned row reads "Closed before the run finished." even when the SQL was fine.
+Task 10: Ruling: both analyst calls send max_tokens: 2048 before ...cfg.extra (Settings can still override). Without it the local endpoint truncated the report at ~650 chars, which is not enough for 13 OpenUI blocks.
+Task 10: Ruling: prompt library split into lib/report-spec.ts (lang-core, React-free) + lib/report-ui.ts (renderers only, built from the same specs array). react-lang calls React.createContext at import, and a route runs under the react-server condition, where that export does not exist: `next build` died with "(0, pU.createContext) is not a function" while collecting /api/analyze. @openuidev/lang-core became a direct dep for this reason. Names/props/descriptions cannot drift because report-ui maps renderers onto the imported specs; the test asserts every spec has a renderer.
+Task 10: Note: the local analyst is a reasoning model. With thinking enabled it spends the context on `delta.reasoning` and `delta.content` stays empty, so the report arrives blank. Fixed by config, not code: Extra params {"chat_template_kwargs":{"enable_thinking":false}} — now said in the Settings field help and the README.
+Task 11: Ruling: node:sqlite rows have a null prototype, and React refuses to pass them into a client component — /app/<id> returned 500 with "Only plain objects ... can be passed to Client Components", dev trace pointing at row={{...}} in the rail. Fixed once in lib/db.ts (one() and listAnalyses spread every row) rather than in each component, and guarded by the test "rows are plain objects so they can cross the server -> client boundary" (RED first). Cost if wrong: a spread per row, which is nothing at this scale.
+Task 11: Ruling: HistoryItem binds (null, fd) wrappers because rename/remove are useActionState-shaped server actions and a plain <form action> passes only FormData.
+Task 11: Verified in Chromium (dev server, stored run): #report renders 17 cards, 1 pre.sql + Copy button, 1 option table, 3 score bars, 4 metric cards; 0 console errors; no horizontal overflow at 320/375/414/768; under print emulation the rail and toolbar hide and the body goes white.
+Task 11: complete (commits ac4cbdd..a5529ce, tests: npm test → ℹ duration_ms 529.962542)
+Task 12: Ruling: scripts/smoke.sh does not require Docker. --docker keeps the compose path; the default mode checks an already-running app (healthz, /login, /signup, signed-out /app -> 307, POST /api/analyze -> 401) and exits non-zero on any failure. The partner's machine has no Docker, so a script that could only run under compose would never be run here. Verified: all five checks ok against `npm start` on :3000.
+Task 12: Ruling: Dockerfile, docker-compose.yml and .dockerignore are written but were never built or executed here, per the partner's instruction. README says the image is untested on this machine. Cost if wrong: first real `docker build` may need a tweak or two.
+Task 12: Gate: jev-1.13 on the PLAN — YES (matches_goal 0.90, coverage 3.71/4, biggest_gap nothing). On the SPEC — matches_goal 0.94 but coverage 2.1 and the named gap moved get_plan -> qa as each was closed; the spec gained "Getting the input, and the two keys" and an "Acceptance" section because of it. The YES rule mentions tasks and tests, which a vision document does not carry, so the spec run is informational and the plan run is the gate.
+Task 12: Note: an earlier `smoke.sh` run reported /login 404. Cause was mine, not the app's: leftover `next start` processes from earlier tasks still held the port. pkill -f next, restart, all routes answer. Zombie dev servers are the first thing to check on a 404 here.
+Task 12: complete (commits a5529ce..0db7b81, tests: npm test → ℹ duration_ms 528.657875)
+Task 13: 17 tests green in 44s: signup → guide → keys typed in the panel → readiness screen; signed-out /app → /login; a real run (stages 1 of 4 → 4 of 4, OpenUI report painted from the stream, no raw "root = Report(" text, Copy reaches the clipboard, print emulation hides rail and toolbar); a dropped UTF-16/BOM .sqlplan decodes without NULs; a pasted SQL script is refused with the stage named; rename sticks; delete asks first and refuses to delete on dismiss; reopening a stored run renders the report and the server-rendered Jev verdict with no new model call; no horizontal overflow at 320/375/414/768 in desktop and Pixel 7; every settings form field has a real <label for>.
+Task 13: Ruling: the mobile project only runs responsive.spec.ts. A full run costs ~30s of real model time; a second identical copy bought nothing.
+Task 13: Ruling: three of the brief's assertions were wrong and are changed, each with a reason in the file. (1) "cards > 2" ran mid-stream, before the report existed — it now waits for the Analyse button to re-enable, which only happens on the done frame. (2) the tap-target floor of 36px is above what .btn actually is (10px padding + 15px line = 35px); the floor is 32px, which still fails a squashed or wrapped control. (3) "every input needs label[for]" failed on the rail's rename boxes, which carry aria-label instead; the check is scoped to form inputs and reports the offending names.
+Task 13: Ruling: SettingsForm gained an `after` hidden field and saveSettingsAction redirects to /setup?step=3 when it comes from the wizard. Without it the setup page's own forward (added in Task 5) bounced a just-configured user to /app, so the wizard's Save button appeared to do nothing. The /settings host still shows "Saved." inline.
+Task 13: Note (time waster, recorded so it is not repeated): deleting the data directory while a dev server is running leaves that server writing into an unlinked inode — the E2E run then "succeeds" against a database that no longer exists anywhere, and 11 tests fail with empty state. Stop the server (`pkill -f next`) before clearing .playwright-data, or let Playwright own the server lifecycle.
+Task 13: complete (commits 0db7b81..07dd3d6, tests: npm test → ℹ duration_ms 609.551292)
+Final review: self-review (no subagent tool) — the author read the whole 15-commit package; weaker than a fresh reviewer, so this is flagged for the partner to decide before merge.
+Final: fixed email collision on /settings — test "changeEmail refuses an address another account already has" RED→GREEN; suite 33/33, e2e 19/19.
+Final: fixed /app/[id] self-redirect for a row left "running" — behaviour pinned by tests-e2e/edge.spec.ts "a row left running renders what exists instead of redirecting forever" (RED: infinite redirect; GREEN).
+Final: fixed ScoreBar/OptionRow/VerdictBlock throwing on null numbers — test "a null confidence from the model does not blank the block" RED→GREEN; the live E2E log showed "[openui] runtime/render-error: Component ScoreBar render failed", which is now absent.
+Final: minor (deferred): no rate limit on /signup or /api/analyze (ponytail comment in lib/auth.ts; token bucket before this faces a network).
+Final: minor (deferred): raw XML is stored per analysis with no per-user quota; 12 MB cap per row, unbounded rows.
+Final: minor (deferred): sessions are not revoked when the password changes (30-day tokens stay valid).
+Final: minor (deferred): digestPlan walks the parsed document once per element type (~10 passes); a 12 MB plan costs a few hundred ms of CPU.
+Final: minor (deferred): rename from a /app/[id] page does not revalidate the rail title until the next navigation.
+Final: minor (deferred): .dockerignore excludes tests/ but the image copies node_modules from the build stage including devDependencies.
+Final: minor (deferred): Dockerfile is unbuilt on this machine (no Docker), so its first real build may need a tweak.
+Task 13: complete (commits 07dd3d6..5160a00, tests: npm test → ℹ duration_ms 514.179833)
+
+Post-delivery bug report (partner: "clicking Next in the guide signs me out back to signup"):
+Root cause 1: startSession set secure: NODE_ENV === "production". Over plain http://localhost Safari refuses to store a Secure cookie at all, so every page after the wizard read as signed-out and requireUser bounced to /login (the login page's "Create account" link is what looked like a sign-out). Now Secure only when X-Forwarded-Proto says https, or COOKIE_SECURE=1. tests-e2e/session.spec.ts RED on webkit (Next → /login) → GREEN.
+Root cause 2 (found while pinning 1): /app had no onboarding gate at all. The guide only appeared because the signUp/signIn actions redirect there, so closing it mid-way left a console that cannot run anything until Analyse 412s. Gate now lives in app/app/layout.tsx using the same has_analyst/has_jev rule /api/analyze enforces.
+QA blind spot fixed: the suite ran next dev, and only chromium. Playwright now runs the production server (pree2e builds; reuseExistingServer false) and adds a webkit project, because chromium accepts a Secure cookie on localhost and webkit does not — the engine difference was the whole bug. 21 passed (setup, chromium, webkit, mobile).
+QA rulings on my own tests, not the app: session.spec asserted #email was prefilled (it is a change field and starts blank by design) and edge.spec picked "the newest user", which in a full run is a webkit spec's account, so it opened another account's row and 404s; both now target the setup account and the gate respectively.
+Verification on the delivered build, both engines, against http://localhost:3000: signup → guide → Next → keys → Save → step 3 "Analyst ready · Jev ready" → /app renders the paste box.
+
+Post-delivery bug report 2 (partner: their own 2.7 MB production plan failed to import):
+Five defects, each found by measuring plan-cxpaket.sqlplan rather than the fixture: (1) fast-xml-parser maxNestedTags 128 vs a real nesting depth of 2729; (2) table names read off <IndexScan> instead of its <Object> child, so 51 objects digested to 0 tables; (3) SSMS writes StatementText with &#xD;&#xA; (90 of them) and the model was fed entity noise; (4) rewrite_sql's name told the model "query rewrite only", so no CREATE INDEX ever existed to show and the report had zero SqlBlocks; (5) max_tokens 2048 truncated the now-larger candidate JSON and the user got "malformed JSON" after 38 seconds.
+Ruling: option_type + sql_to_run replaces rewrite_sql. The field name was load-bearing — it is sent to the model — and keeping it would have kept the omission. verify_semantics therefore keys on option_type === "rewrite", preserving the Task 8 ruling that index options must not be flagged for carrying DDL.
+Ruling: dropPlaceholderSql nulls ellipsis SQL instead of rendering it. A SqlBlock that cannot be pasted reads as an instruction and fails on run; no block beats a fake one. ponytail comment marks the "..." heuristic.
+Ruling: the plan file itself stays out of git (/plan-*.sqlplan). It carries the partner's real schema names; the fixture that ships is synthetic.