@kinqs/brainrouter-mcp-server 0.3.5 → 0.3.7

package/dist/memory/recall.js

@@ -51,10 +51,12 @@ export class MemoryRecallPipeline {
     store;
     embeddingService;
     rerankerService;
-    constructor(store, embeddingService, rerankerService) {
+    relevanceJudge;
+    constructor(store, embeddingService, rerankerService, relevanceJudge) {
         this.store = store;
         this.embeddingService = embeddingService;
         this.rerankerService = rerankerService;
+        this.relevanceJudge = relevanceJudge;
     }
     async recall(params) {
         const startTime = Date.now();
@@ -270,6 +272,35 @@ export class MemoryRecallPipeline {
                 console.error("[BrainRouter] Reranker failed during recall, falling back to RRF:", e.message);
             }
         }
+        // Stage 4 — LLM Relevance Judge (semantic approve/reject gate)
+        //
+        // The reranker orders candidates by a learned relevance score but never
+        // *filters* — so a memory that shares vocabulary with the query but is
+        // about a different subject still makes the cut. The judge fixes that by
+        // asking a fast LLM "is each of these actually relevant?" and dropping
+        // the rejects. On any failure we keep the reranker output unchanged so a
+        // flaky judge call never breaks recall.
+        let judgeUsed = false;
+        let judgeApproved = 0;
+        let judgeRejected = 0;
+        let judgeVerdicts;
+        if (this.relevanceJudge?.isReady() && topResults.length > 0) {
+            try {
+                const judgeCandidates = topResults.map(r => ({
+                    id: r.record.record_id,
+                    content: r.record.content,
+                }));
+                const judgeResult = await this.relevanceJudge.judge({ query, candidates: judgeCandidates });
+                judgeUsed = true;
+                judgeVerdicts = judgeResult.verdicts;
+                judgeApproved = judgeResult.approvedIndices.length;
+                judgeRejected = topResults.length - judgeApproved;
+                topResults = judgeResult.approvedIndices.map((i) => topResults[i]);
+            }
+            catch (e) {
+                console.error("[BrainRouter] Relevance judge failed during recall, keeping reranker output:", e.message);
+            }
+        }
         // 5. Format for context
         const memoryLines = topResults.map(({ record }) => {
             const tag = record.scene_name ? `${record.type}|${record.scene_name}` : record.type;
@@ -279,7 +310,13 @@ export class MemoryRecallPipeline {
             }
             return line;
         });
-        const prependContext = `<relevant-memories>\n  The following memories are relevant to this query. Reference only if helpful:\n\n  ${memoryLines.join("\n  ")}\n</relevant-memories>`;
+        // If the judge rejected everything, skip the prepend block entirely —
+        // an empty <relevant-memories> tag is worse than no tag because it
+        // implies "we looked and nothing helped," which the agent should infer
+        // from the absence of the block.
+        const prependContext = memoryLines.length > 0
+            ? `<relevant-memories>\n  The following memories are relevant to this query. Reference only if helpful:\n\n  ${memoryLines.join("\n  ")}\n</relevant-memories>`
+            : undefined;
         // Build appendSystemContext with Contextual Focus Navigation + tools guide
         const topScenes = this.store.getTopContextualFocus(userId, 3);
         let appendSystemContext = "";
@@ -329,9 +366,10 @@ export class MemoryRecallPipeline {
             recordId: r.record.record_id,
             skillTag: r.record.skill_tag
         }));
-        const recallStrategy = vecResults.length > 0
+        const baseStrategy = vecResults.length > 0
             ? (usedReranker ? "hybrid+rerank" : "hybrid")
             : (usedReranker ? "keyword+rerank" : (filePathResults.length > 0 ? "keyword+file" : "keyword"));
+        const recallStrategy = judgeUsed ? `${baseStrategy}+judge` : baseStrategy;
         const durationMs = Date.now() - startTime;
         const recallExplanation = {
             ftsHits: ftsResults.length,
@@ -342,6 +380,10 @@ export class MemoryRecallPipeline {
             typeBoosts,
             skillBoostApplied,
             rerankerUsed: usedReranker,
+            judgeUsed,
+            judgeApproved,
+            judgeRejected,
+            judgeVerdicts,
             graphExpansion: hasGraphExpansion,
             citationBoosts,
             durationMs,
@@ -388,6 +430,9 @@ export class MemoryRecallPipeline {
                     vecHits: explanation?.vecHits ?? 0,
                     intentDetected: explanation?.intentDetected ?? "none",
                     rerankerUsed: explanation?.rerankerUsed ?? false,
+                    judgeUsed: explanation?.judgeUsed ?? false,
+                    judgeApproved: explanation?.judgeApproved ?? 0,
+                    judgeRejected: explanation?.judgeRejected ?? 0,
                 },
             });
         }

package/dist/memory/store/relevance-judge.d.ts

@@ -0,0 +1,51 @@
+import type { RelevanceJudgeServiceConfig, RelevanceVerdict } from "@kinqs/brainrouter-types";
+export interface JudgeCandidate {
+    /** Stable id used for logging — typically the memory's record_id. */
+    id: string;
+    /** Memory content the judge will read. */
+    content: string;
+}
+export interface JudgeResult {
+    /** Verdicts in the order returned by the judge. */
+    verdicts: RelevanceVerdict[];
+    /** Indices the judge approved as relevant. */
+    approvedIndices: number[];
+}
+/**
+ * LLM-as-judge stage that approves or rejects retrieved memories based on
+ * actual semantic relevance to the user query — sits between the reranker and
+ * context formatting, dropping candidates that share keywords but aren't
+ * genuinely about the query subject.
+ *
+ * Failure mode is "skip the gate": if the call errors out, callers fall back
+ * to the unfiltered reranker output. We never want a flaky judge call to
+ * crash a recall.
+ */
+export declare class RelevanceJudgeService {
+    private readonly enabled;
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly maxCandidates;
+    private readonly timeoutMs;
+    private readonly ready;
+    constructor(config: RelevanceJudgeServiceConfig);
+    isReady(): boolean;
+    getMaxCandidates(): number;
+    /**
+     * Grade a batch of candidates against the query. Returns verdicts and the
+     * subset of indices approved as relevant. Throws on transport/parsing
+     * failure — callers are expected to fall back to pre-judge results.
+     */
+    judge(params: {
+        query: string;
+        candidates: JudgeCandidate[];
+    }): Promise<JudgeResult>;
+    /**
+     * Defensive JSON parse — strips code fences, picks the first valid JSON
+     * object/array, and tolerates either {"verdicts":[…]} or a bare array.
+     * Returns one verdict per candidate; missing entries default to "rejected"
+     * so a malformed response can't silently approve everything.
+     */
+    private parseVerdicts;
+}

package/dist/memory/store/relevance-judge.js

@@ -0,0 +1,196 @@
+import { fetchWithExternalRetry } from "../retry.js";
+import { acquireLLMSlot } from "../llm-semaphore.js";
+/**
+ * LLM-as-judge stage that approves or rejects retrieved memories based on
+ * actual semantic relevance to the user query — sits between the reranker and
+ * context formatting, dropping candidates that share keywords but aren't
+ * genuinely about the query subject.
+ *
+ * Failure mode is "skip the gate": if the call errors out, callers fall back
+ * to the unfiltered reranker output. We never want a flaky judge call to
+ * crash a recall.
+ */
+export class RelevanceJudgeService {
+    enabled;
+    endpoint;
+    apiKey;
+    model;
+    maxCandidates;
+    timeoutMs;
+    ready;
+    constructor(config) {
+        this.enabled = config.enabled ?? false;
+        this.endpoint = config.endpoint ?? "https://api.openai.com/v1/chat/completions";
+        this.apiKey = config.apiKey ?? "";
+        this.model = config.model ?? "gpt-4o-mini";
+        this.maxCandidates = Math.max(1, config.maxCandidates ?? 10);
+        this.timeoutMs = Math.max(1000, config.timeoutMs ?? 15_000);
+        this.ready = this.enabled && !!this.apiKey;
+        if (this.enabled && !this.apiKey) {
+            console.error("[BrainRouter] Relevance judge enabled but no API key set. Stage 4 judging will be skipped.");
+        }
+    }
+    isReady() {
+        return this.ready;
+    }
+    getMaxCandidates() {
+        return this.maxCandidates;
+    }
+    /**
+     * Grade a batch of candidates against the query. Returns verdicts and the
+     * subset of indices approved as relevant. Throws on transport/parsing
+     * failure — callers are expected to fall back to pre-judge results.
+     */
+    async judge(params) {
+        if (!this.ready) {
+            throw new Error("RelevanceJudgeService is not ready (disabled or missing API key)");
+        }
+        if (params.candidates.length === 0) {
+            return { verdicts: [], approvedIndices: [] };
+        }
+        const candidates = params.candidates.slice(0, this.maxCandidates);
+        const safeQuery = params.query.length > 800 ? params.query.slice(0, 800) + "…" : params.query;
+        const candidateBlock = candidates
+            .map((c, i) => {
+            const text = c.content.length > 600 ? c.content.slice(0, 600) + "…" : c.content;
+            return `[${i}] ${text.replace(/\s+/g, " ").trim()}`;
+        })
+            .join("\n");
+        const systemPrompt = [
+            "You are a strict relevance judge for a memory retrieval system.",
+            "For each candidate memory, decide whether it is actually relevant to the user's query.",
+            "A memory is RELEVANT only if it provides information that directly helps answer, contextualize, or inform the query.",
+            "It is NOT relevant if it merely shares keywords, is about a different subject, or is generic background.",
+            "When in doubt, reject — false positives pollute the agent's context window.",
+            "Respond with strict JSON only, no prose.",
+        ].join(" ");
+        const userPrompt = [
+            `Query: ${safeQuery}`,
+            "",
+            "Candidates:",
+            candidateBlock,
+            "",
+            "Respond with exactly this JSON shape:",
+            `{"verdicts":[{"index":0,"relevant":true,"reason":"…"}, …]}`,
+            "Include one verdict per candidate. Keep each reason under 120 chars.",
+        ].join("\n");
+        const doFetch = () => fetchWithExternalRetry(this.endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${this.apiKey}`,
+            },
+            // Deliberately omitting `response_format` — OpenAI accepts
+            // `{type:"json_object"}`, but LM Studio / llama.cpp-style backends
+            // reject anything except `json_schema` or `text` with a 400, and
+            // Ollama / vLLM each have their own quirks. The system prompt is
+            // explicit about strict-JSON output and the parser below strips
+            // code fences + tolerates surrounding prose, so dropping the hint
+            // is cheaper than per-provider branching.
+            body: JSON.stringify({
+                model: this.model,
+                messages: [
+                    { role: "system", content: systemPrompt },
+                    { role: "user", content: userPrompt },
+                ],
+                temperature: 0,
+            }),
+            signal: AbortSignal.timeout(this.timeoutMs),
+        }, {
+            label: "Relevance Judge API",
+        });
+        const release = await acquireLLMSlot();
+        let raw;
+        try {
+            let res = await doFetch();
+            // LM Studio quirk: idle models auto-unload and the first call after
+            // unload returns 400 with "Model is unloaded" / "No models loaded".
+            // The backend then loads the model in the background, so a retry
+            // ~1.5s later usually succeeds. Mirrors ModelLLMRunner in engine.ts.
+            if (res.status === 400) {
+                const errorBody = await res.text();
+                if (/model\s+(is\s+)?unloaded|model\s+not\s+loaded|no\s+models?\s+loaded/i.test(errorBody)) {
+                    await new Promise((resolve) => setTimeout(resolve, 1500));
+                    res = await doFetch();
+                    if (!res.ok) {
+                        const retryBody = await res.text().catch(() => "(no body)");
+                        throw new Error(`Relevance Judge API failed after LM Studio reload retry: HTTP ${res.status} ${res.statusText} - ${retryBody}`);
+                    }
+                }
+                else {
+                    throw new Error(`Relevance Judge API failed: HTTP ${res.status} ${res.statusText} - ${errorBody}`);
+                }
+            }
+            else if (!res.ok) {
+                const err = await res.text().catch(() => "(no body)");
+                throw new Error(`Relevance Judge API failed: HTTP ${res.status} ${res.statusText} - ${err}`);
+            }
+            const data = await res.json();
+            if (data?.error) {
+                const errMsg = typeof data.error === "string" ? data.error : (data.error.message ?? JSON.stringify(data.error).slice(0, 400));
+                throw new Error(`Relevance Judge endpoint returned an error envelope: ${errMsg}`);
+            }
+            const choice = data?.choices?.[0];
+            const content = choice?.message?.content ?? choice?.delta?.content;
+            if (typeof content !== "string") {
+                throw new Error(`Relevance Judge returned no usable content. Response: ${JSON.stringify(data).slice(0, 400)}`);
+            }
+            raw = content;
+        }
+        finally {
+            release();
+        }
+        const parsed = this.parseVerdicts(raw, candidates.length);
+        const approvedIndices = [];
+        for (const v of parsed) {
+            if (v.relevant && v.index >= 0 && v.index < candidates.length) {
+                approvedIndices.push(v.index);
+            }
+        }
+        return { verdicts: parsed, approvedIndices };
+    }
+    /**
+     * Defensive JSON parse — strips code fences, picks the first valid JSON
+     * object/array, and tolerates either {"verdicts":[…]} or a bare array.
+     * Returns one verdict per candidate; missing entries default to "rejected"
+     * so a malformed response can't silently approve everything.
+     */
+    parseVerdicts(raw, candidateCount) {
+        let text = raw.trim();
+        text = text.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/i, "").trim();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            const objMatch = text.match(/\{[\s\S]*\}/);
+            const arrMatch = text.match(/\[[\s\S]*\]/);
+            const candidate = objMatch?.[0] ?? arrMatch?.[0];
+            if (!candidate) {
+                throw new Error(`Relevance Judge produced non-JSON output: ${text.slice(0, 200)}`);
+            }
+            parsed = JSON.parse(candidate);
+        }
+        const list = Array.isArray(parsed)
+            ? parsed
+            : Array.isArray(parsed?.verdicts) ? parsed.verdicts : [];
+        const byIndex = new Map();
+        for (const item of list) {
+            if (!item || typeof item !== "object")
+                continue;
+            const index = Number(item.index);
+            if (!Number.isFinite(index))
+                continue;
+            byIndex.set(index, {
+                index,
+                relevant: Boolean(item.relevant),
+                reason: typeof item.reason === "string" ? item.reason.slice(0, 200) : "",
+            });
+        }
+        const out = [];
+        for (let i = 0; i < candidateCount; i++) {
+            out.push(byIndex.get(i) ?? { index: i, relevant: false, reason: "no verdict returned" });
+        }
+        return out;
+    }
+}

package/dist/memory/working/canvas.js

@@ -24,6 +24,17 @@ export function buildAnnotatedCanvas(steps, activeNodeId) {
     for (let index = 1; index < steps.length; index += 1) {
         lines.push(`  ${steps[index - 1].nodeId} --> ${steps[index].nodeId}`);
     }
+    // Reasoning steps ("Why: …" decisions emitted via memory_working_offload
+    // with kind:"reasoning") get a dashed border so the audit trail is
+    // visually separable from tool_output and compressed_summary nodes when
+    // a human (or the dashboard) inspects canvas.mmd. Emitted before the
+    // active-node fill so the active highlight overrides the dashed style
+    // when the same node happens to be both.
+    for (const step of steps) {
+        if (step.kind === "reasoning") {
+            lines.push(`  style ${step.nodeId} stroke-dasharray:4 4,stroke:#9f7aea,stroke-width:2px`);
+        }
+    }
     if (activeNodeId && steps.some((step) => step.nodeId === activeNodeId)) {
         lines.push(`  style ${activeNodeId} fill:#2b6cb0,stroke:#3182ce,stroke-width:2px,color:#fff`);
     }

package/docs/specs/0.3.7-terminal-ui-redesign.md

@@ -0,0 +1,259 @@
+# Spec: 0.3.7 Item 6 — Terminal UI redesign + in-terminal config wizard
+
+> Status: drafted, awaiting implementation. See [Tasks.md](../../Tasks.md)
+> for live progress. Pairs with [`brainrouter-roadmap/0.3.7.md`](../../brainrouter-roadmap/0.3.7.md)
+> as the headline feature of the 0.3.7 cycle.
+
+## Objective
+
+Make BrainRouter's CLI feel like Claude Code / OpenCode / Codex / Grok-CLI
+/ DeepSeek-TUI — **especially around in-terminal, picker-driven
+configuration**. Today a first-run user has to:
+
+1. Run `brainrouter login` outside the REPL → answers a sequence of
+   `inquirer` text prompts → exits.
+2. Run `brainrouter config` outside the REPL → answers another sequence
+   of text prompts → exits.
+3. Then start `brainrouter` (the chat REPL) and discover everything else
+   (`/theme`, `/personality`, `/effort`, `/mode`, statusline) via
+   `/help` or by hand-editing JSON.
+
+Peer CLIs do this differently:
+
+- **Claude Code** — `/config` opens a tabbed settings panel; `/theme`,
+  `/model`, `/login` are arrow-key pickers; first-run shows a welcome
+  card → onboarding wizard with a step counter.
+- **Codex** — `Step::{Welcome, Auth, TrustDirectory}` state machine
+  drives the onboarding; one modal owns multiple sub-states (`PickMode`
+  → `ApiKeyEntry`) via an enum.
+- **DeepSeek-TUI** — `/config` is verb-overloaded: bare opens a picker,
+  `<key>` shows, `<key> <val>` sets session, `<key> <val> --save`
+  persists. Provider picker uses a single modal with `Stage::{List,
+  KeyEntry}`; selecting an un-configured provider transitions the same
+  modal into key entry.
+- **Grok-CLI** — first-run is a render-time `ApiKeyModal` overlay
+  inside the REPL, not a separate `login` subcommand. Each settings
+  surface (`/models`, `/mcp`, `/sandbox`, `/wallet`) is its own modal
+  that merges through a single `saveUserSettings(partial)`.
+
+We adopt the **render-time modal** + **state-enum** + **verb-overloaded
+slash command** patterns, on top of our existing
+`brainrouter-cli/src/cli/cliPrompt.ts` picker primitive.
+
+## Non-goals
+
+- A full Ratatui/Ink-style fullscreen renderer. That's the 0.5.0 cycle.
+- Replacing `readline` as the REPL composer. We extend the existing
+  raw-mode picker; we do not rewrite the input loop.
+- Multi-provider OAuth flows. v0.3.7 keeps API-key auth; OAuth /
+  device-code can be a follow-up once the wizard skeleton lands.
+- Touching the MCP server's config (`~/.config/brainrouter/server.env`).
+  The wizard reads/writes only the CLI-owned files:
+  `~/.config/brainrouter/config.json` and
+  `<workspace>/.brainrouter/cli/preferences.json`.
+
+## Tech stack
+
+- Same as the rest of `brainrouter-cli/`: TypeScript on Node 22+, ESM,
+  Vitest, `chalk` for color, our own `cliPrompt.askChoice` for the
+  arrow-key picker.
+- `inquirer` is deliberately **removed from the new flows** — its
+  competing readline interface is the bug that motivated `cliPrompt.ts`
+  in the first place. Legacy `brainrouter login` / `brainrouter config`
+  subcommands stay (for back-compat) but the docs steer users at the
+  new in-REPL flows.
+
+## Slash command surface
+
+Following the verb-overload pattern from DeepSeek-TUI:
+
+| Command | Behaviour |
+| --- | --- |
+| `/init` | Re-runs the first-run onboarding wizard (theme → provider → model → MCP → done). Idempotent; safe to re-run. **Aliased from the old `/init` which only wrote `AGENT.md`** — that one-shot is folded into the wizard's final step as an opt-in toggle so we don't regress for users who relied on it. |
+| `/config` | Bare — opens the **settings home panel** (picker over: LLM, MCP, Theme, Statusline, Effort, Mode, Quiet, Personality, Editor mode, View raw config). |
+| `/config <key>` | Show current value for `<key>` (e.g. `/config theme` → `theme: dark (preference)`). |
+| `/config <key> <value>` | Set `<key>` to `<value>` and persist (writes to `~/.config/brainrouter/config.json` for LLM/MCP knobs, `<workspace>/.brainrouter/cli/preferences.json` for prefs). |
+| `/login` | NEW slash alias for the old `brainrouter login` flow — opens the **MCP profile editor** in-REPL (transport picker → fields → reachability test → save). The standalone `brainrouter login` CLI subcommand stays for first-run-before-REPL use. |
+| `/logout` | Already exists; unchanged. Clears API keys from the active profile. |
+| `/theme` | Already exists. Extended with `/theme` (bare) opening the picker (live-preview the banner + prompt accent on cursor-change), confirming via ENTER, restoring on Esc. |
+| `/model` | Already exists. Extended with bare-`/model` opening a picker over a curated short-list (gpt-4o-mini, gpt-4o, gpt-5, claude-sonnet-4, deepseek-v4, qwen3-coder, …) + "Other" for free-text. |
+
+The bare `/config` panel is the **settings home** — it's the screen
+that lets users discover every knob without needing to memorise the
+slash vocabulary.
+
+## Onboarding wizard (`/init`)
+
+State machine — same shape as Codex `Step` and DeepSeek
+`OnboardingState`:
+
+```
+Welcome → Theme → Provider → ApiKey → Model → MCP → AgentMd → Done
+```
+
+- **Welcome** — a single boxed card (~5 lines) introducing
+  BrainRouter, what gets configured, and where (path of
+  `~/.config/brainrouter/config.json`). ENTER continues, q quits
+  without writing.
+- **Theme** — arrow-key picker over `dark / light / mono / auto`,
+  with **live preview**: on cursor-change, redraw the banner accent so
+  the user sees the change before confirming. Persists to
+  `preferences.theme` on confirm.
+- **Provider** — picker over a curated provider list:
+  `OpenAI · DeepSeek · OpenRouter · Anthropic (via gateway) · Gemini
+  (OpenAI-compat) · LM Studio (local) · Ollama (local) · Custom…`.
+  Each row shows a one-line hint (endpoint, "(local)" / "(cloud)",
+  needs-key indicator). Pre-detects from env vars
+  (`OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `OPENROUTER_API_KEY`, etc.)
+  — pre-selects the row whose key is already present in the shell.
+- **ApiKey** — free-text entry (re-uses the picker's `awaitingOther`
+  free-text mode). Pre-filled from env when available. Validation
+  tier `Accept{warning?}` / `Reject(reason)`: empty for local
+  endpoints is OK; non-empty with `sk-`-shape prefix or vendor-known
+  shape is OK; everything else is **accepted with a warning** (not
+  rejected — vendors invent new prefixes all the time). Mask to last
+  4 chars after entry.
+- **Model** — picker over the provider's curated short-list +
+  "Other" for free-text. Defaults: OpenAI → `gpt-4o-mini`, DeepSeek
+  → `deepseek-chat`, OpenRouter → `anthropic/claude-sonnet-4`,
+  LM Studio → blank (user picks from loaded models), etc.
+- **MCP** — picker over `Local stdio (brainrouter-mcp on PATH) ·
+  Local HTTP (http://localhost:3747/mcp) · Remote HTTP… (free-text
+  URL) · Skip (offline-only)`. On confirm, run a single
+  `mcpClient.listTools()` reachability test (5s timeout); on success
+  save the profile and mark it active; on failure offer "save
+  anyway" / "try a different transport" / "skip".
+- **AgentMd** — yes/no: "Write AGENT.md to this workspace? (helps
+  agents understand your repo conventions)". Defaults to **yes** if
+  no `AGENT.md` / `CLAUDE.md` exists yet, **no** otherwise. This is
+  the toggle that absorbs the old `/init` behaviour.
+- **Done** — summary card showing the saved config (with API keys
+  masked) + next steps (`/help`, `/config`, `/where`). Marker file
+  written to `~/.config/brainrouter/.onboarded` so subsequent CLI
+  starts skip the wizard. Re-running `/init` is always allowed.
+
+**Skip semantics.** At any step `Esc` backs out one state; `q`
+aborts the whole wizard with **no changes saved** (everything is
+journalled in-memory until the Done step commits the write).
+
+**Auto-trigger.** When the user runs `brainrouter` (the chat command)
+and no `~/.config/brainrouter/config.json` exists, instead of the
+current "Run \`brainrouter login\` …" error-and-exit, we drop them
+**straight into the wizard inside the REPL** (no separate subcommand).
+This is the grok-cli `ApiKeyModal` pattern — the modal IS the
+onboarding.
+
+## Settings home panel (`/config`)
+
+Picker over the settings categories. Each row shows the current value
+on the right so the user can scan the state at a glance:
+
+```
+┌─ ⚙️  BrainRouter Config ────────────────────────────────────────┐
+│                                                                 │
+│  ▶ LLM provider       openai · gpt-4o-mini                      │
+│    MCP profile        default · http · 🟢 online                │
+│    Theme              dark                                      │
+│    Statusline         mode,branch,workflow,goal                 │
+│    Reasoning effort   medium                                    │
+│    Execution mode     planning                                  │
+│    Review policy      request                                   │
+│    Quiet mode         off                                       │
+│    Personality        standard                                  │
+│    Editor mode        emacs                                     │
+│                                                                 │
+│    View raw config                                              │
+│    Quit (Esc)                                                   │
+│                                                                 │
+│  ↑/↓ navigate  ·  ENTER edit  ·  Esc to quit                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Selecting a row opens the appropriate sub-picker (provider picker,
+theme picker, etc.). On confirm, returns to the home panel with the
+new value visible. Esc backs out one level (sub-picker → home → exit).
+
+The "View raw config" row prints the scrubbed JSON (today's bare
+`/config` behaviour) so users who prefer the JSON view can still get
+it without leaving the panel.
+
+## Persistence contract
+
+One central writer per file. No scattered `fs.writeFileSync` calls.
+
+| File | Wrapper | Owns |
+| --- | --- | --- |
+| `~/.config/brainrouter/config.json` | `saveConfig(partial)` in [`config/config.ts`](../../brainrouter-cli/src/config/config.ts) — existing function, called with the merged result. | LLM provider, MCP profiles, active profile. |
+| `<workspace>/.brainrouter/cli/preferences.json` | `writePreferences(workspaceRoot, partial)` in [`state/preferencesStore.ts`](../../brainrouter-cli/src/state/preferencesStore.ts) — existing function; already merges. | Theme, statusline, effort, exec mode, review policy, quiet, personality, editor, sandbox grants. |
+| `~/.config/brainrouter/.onboarded` | New `markOnboarded()` helper alongside `config/config.ts`. | Empty file; presence = wizard has run at least once. |
+
+The wizard accumulates intent in an in-memory `Draft` object across
+all steps; the commit happens **once** at the Done step. Aborting via
+`q` discards the draft.
+
+## Picker primitive — additions to `cliPrompt.ts`
+
+Today's `askChoice` is sufficient for confirm-only pickers; the
+redesign needs two new behaviours we can fold in as optional fields:
+
+1. **`onCursorChange(index)` callback** — fired by `reducePicker` after
+   an `up`/`down` keystroke if the option list moved. Theme picker
+   uses it to repaint the banner accent live.
+2. **`prefilledOther?: string`** — when the wizard wants to drop the
+   user straight into the `awaitingOther` free-text input pre-filled
+   with the env-var value (so ENTER accepts the env-derived default,
+   editing overrides it).
+
+Both are additive; existing callers keep working with `undefined`.
+
+## Boundary rules (per `spec-driven-skill`)
+
+- **Always:** route all settings persistence through
+  `saveConfig` / `writePreferences`; mask API keys to last 4 chars on
+  every render; pause the parent `rl` while a picker is active; close
+  with the cursor visible.
+- **Ask first:** changing `~/.config/brainrouter/config.json` shape
+  (any new top-level key) — needs explicit user sign-off because it
+  surfaces in `/debug-config`.
+- **Never:** write API keys to disk in plain text under the workspace
+  (only under `~/.config/brainrouter/`); silently overwrite an
+  existing config without confirmation; default to option 1 in
+  non-TTY mode (mirrors the existing `NoTTYError` contract).
+
+## Definition of Done
+
+1. `brainrouter` started against a clean `$HOME` (no `~/.config/brainrouter/`)
+   drops into the wizard automatically — no `brainrouter login`
+   needed.
+2. `/init` re-runs the wizard at any time inside the REPL.
+3. `/config` (bare) opens the settings home panel; arrow-keys
+   navigate; ENTER opens a sub-picker; Esc backs out.
+4. `/config theme dark` sets theme to dark and prints the new value
+   without opening any picker.
+5. Theme picker live-previews on cursor-change and restores the
+   original theme if the user presses Esc.
+6. Tests: pure-function tests for the wizard reducer (`stepReducer`,
+   `Draft` shape, validation tier), `Vitest` tests for the
+   `/config` argument parser (bare / get / set), and one
+   `cliPrompt.ts` test for the new `onCursorChange` callback.
+7. Docs: `brainrouter-docs/cli.md` and `brainrouter-docs/configuration.md`
+   are updated end-to-end. README's "First-time setup" section
+   collapses to "run `brainrouter`; the wizard takes over."
+8. No regressions: `npm run test --workspace brainrouter-cli` stays
+   green; the legacy `brainrouter login` / `brainrouter config`
+   subcommands still work for users who scripted around them.
+
+## Open questions
+
+- **Should `/init` skip the wizard if the marker file exists**, or
+  always re-run? Current answer: always re-run when invoked
+  explicitly; only **auto-trigger on REPL start** when the marker is
+  missing. This matches Codex's "explicit `--login` always honoured"
+  contract.
+- **Should the MCP step probe both stdio and HTTP**, or just the
+  user's pick? Current answer: just the pick. Probing both adds 5s
+  to the wizard for unclear payoff. Users can re-run `/init` if they
+  want to try the other transport.
+- **Should the wizard offer to install missing system deps** (gh,
+  jq, ripgrep)? Current answer: no. Out of scope for v0.3.7. A
+  future `/doctor --fix` could handle it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinqs/brainrouter-mcp-server",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "BrainRouter MCP server — the cognitive memory engine. Exposes recall, capture, focus scenes, persona, contradictions, skills, and graph queries as MCP tools for any MCP-speaking agent.",
   "type": "module",
   "main": "dist/index.js",
@@ -45,7 +45,7 @@
     "gray-matter": "^4.0.3",
     "sqlite-vec": "^0.1.9",
     "zod": "^3.22.4",
-    "@kinqs/brainrouter-types": "^0.3.5"
+    "@kinqs/brainrouter-types": "^0.3.6"
   },
   "engines": {
     "node": ">=22.0.0"

package/dist/memory/config.d.ts

@@ -1,2 +0,0 @@
-export type BrainRouterLlmMode = "server" | "agent";
-export declare function getBrainRouterLlmMode(): BrainRouterLlmMode;

package/dist/memory/config.js

@@ -1,3 +0,0 @@
-export function getBrainRouterLlmMode() {
-    return process.env.BRAINROUTER_LLM_MODE === "agent" ? "agent" : "server";
-}

package/dist/memory/pipeline/l1-contradiction.d.ts

@@ -1,7 +0,0 @@
-import type { IMemoryStore } from "@brainrouter/types";
-import type { LLMRunner, L1Record } from "@brainrouter/types";
-export declare function detectContradictions(params: {
-    newRecord: L1Record;
-    store: IMemoryStore;
-    llmRunner: LLMRunner;
-}): Promise<void>;