LexAI/docs/DECISIONS.md

Decisions

Lightweight ADRs (Architecture Decision Records). One entry per material decision: what was decided, why, what was rejected, and when. Newest at the top. Never rewrite history — supersede instead.

How to use

Add an entry when a choice is hard to reverse, shapes future work, or a future maintainer would otherwise ask "why is it like this?" Skip trivial or easily reversible choices. When a decision is replaced, set the old entry's status to superseded by [ID] rather than deleting it.

Decision template

### D-YYYY-MM-DD-NN — [short decision title]

- **Status:** proposed | accepted | superseded by [ID] | reversed
- **Context:** [the forces and constraints that made a decision necessary]
- **Decision:** [what we chose, stated plainly]
- **Alternatives considered:** [options rejected, with the reason each lost]
- **Consequences:** [what this makes easy, what it makes hard, new risks]
- **Verification:** [how we'll know it was right — metric, test, or review date]
- **Owner / date:** [who decided, when]

Log

D-2026-09-04-01 — Commit each landed task; graphify update at session end

• Status: accepted
• Context: Graph and git lagged behind work (SEO sat uncommitted; graph needed a manual deep rebuild).
• Decision: After every completed task, commit landed files (never secrets or graphify-out/). Do not push unless asked. At session end, run graphify update ..
• Alternatives considered: Commit only when asked (lost work); full /graphify --mode deep every session (too expensive).
• Consequences: More small commits on dev. Graph stays AST-current; docs/images still need an occasional deep extract.
• Verification: Session-start hook reminds the workflow; graphify-out/ stays gitignored.
• Owner / date: John Kevin, 2026-09-04

D-2026-09-03-01 — Website path URLs for Google indexing

• Status: accepted
• Context: The marketing site used HashRouter (/#/docs). Google does not treat hash fragments as indexable URLs. Production already had SPA fallbacks.
• Decision: Switch to BrowserRouter; prerender unique HTML for /, /docs, /contribute, /community; ship /robots.txt and /sitemap.xml; unknown paths return HTTP 404; rewrite legacy #/… hashes on load.
• Alternatives considered: Keep hashes (rejected: not crawlable as pages); full SSR (rejected: extra stack for a static brochure).
• Consequences: Coolify/nginx must keep SPA fallback for the four routes. Old social posts with #/docs still work via the hash rewrite.
• Verification: npm run website:build; GET /robots.txt, /sitemap.xml, /docs 200 with unique titles; GET /no-such-page 404.
• Owner / date: John Kevin / lead, 2026-09-03

D-2026-08-13-01 — VS Code port: shared src/lib + native v1 UX

• Status: accepted
• Context: Need a VS Code twin of LexAI without forking provider/prompt logic or blocking the Chrome WXT app.
• Decision: Keep Chrome at repo root; add packages/vscode that esbuild-bundles @lib/providers|actions|types. v1 uses Command Palette + editor context submenu + lexai.* settings + Secret Storage for the API key. Defer floating toolbar, Prompt Builder UI, Copy As, and relocating Chrome into packages/chrome.
• Alternatives considered: Separate repo (rejected: prompt/provider drift); full npm workspaces + move Chrome (rejected: high break risk for WXT); Chrome-like webview toolbar in v1 (rejected: slower path to usable editor replace).
• Consequences: One prompt/provider source of truth; two settings stores (not synced); VS Code feature gap vs Chrome until a later phase.
• Verification: npm run vscode:typecheck + npm run vscode:build; manual F5 / VSIX select→replace smoke.
• Owner / date: John Kevin / lead, 2026-08-13