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