ahmed mohammedandClaude Opus 4.7
8b42a0931c
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>
86 lines
4.9 KiB
Markdown
86 lines
4.9 KiB
Markdown
# 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.
|