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>
chore: untrack QA database, the local production plan, and a stray image
2026-09-22 12:14:05 +03:00 · 2026-09-22 11:48:47 +03:00
48 changed files with 3538 additions and 0 deletions
@@ -13,6 +13,7 @@ next-env.d.ts
 # runtime data (sqlite)
 /data
 /.playwright-data
+.qa-data/

 # e2e artifacts
 /.auth
@@ -25,3 +26,6 @@ next-env.d.ts

 # real production plans dropped in for debugging stay out of git
 /plan-*.sqlplan
+
+# generated knowledge graph (regenerate with /understand)
+.ua/
@@ -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/`.
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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]].
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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
@@ -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.