sql-server-query-ai/kb/index.md

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