# 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

```markdown
### 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-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


<!--
### D-2026-01-01-01 — Example: choose Postgres over a document store

- **Status:** accepted
- **Context:** Core data is highly relational; we need transactions and ad-hoc queries.
- **Decision:** Use PostgreSQL as the primary datastore.
- **Alternatives considered:** MongoDB (rejected: relational joins would be app-side and error-prone); SQLite (rejected: concurrent write ceiling).
- **Consequences:** Strong consistency and rich querying; adds an ops dependency and migration discipline.
- **Verification:** Load test the core query path; revisit if write contention appears.
- **Owner / date:** [name], 2026-01-01
-->