@kinqs/brainrouter-mcp-server 0.3.4 → 0.3.6

package/.env.example

@@ -1,26 +1,37 @@
-# BrainRouter MCP server — environment
+# BrainRouter MCP server — environment template
 #
-# Copy to brainrouter/.env. Loaded automatically by `dotenv/config` when the
-# MCP server starts (the CLI sets the spawned child's cwd to this folder so
-# stdio-launched MCPs also pick it up).
+# Copy to `brainrouter/.env`. Loaded automatically by `dotenv/config` when
+# the MCP server starts. The CLI sets the spawned child's cwd to this
+# folder so stdio-launched MCPs also pick it up.
 #
 # This file is for MCP-SERVER concerns only:
-#   - cognitive extraction / synthesis LLM
-#   - embedding provider
-#   - reranker provider
-#   - memory engine knobs (decay, sweeper, focus, identity)
-#   - server auth (JWT, admin seed, CORS)
+#   1. LLM credentials & endpoint        (shared by every LLM-driven step)
+#   2. Retrieval pipeline stages         (embeddings, reranker, judge)
+#   3. Memory engine knobs               (storage, decay, distillation, sweeper)
+#   4. Skill pre-warming
+#   5. Server auth                       (JWT, admin seed, CORS, HTTP MCP key)
 #
 # CLI agent knobs (sandbox, tool loop limits, web search, etc.) live in
-# brainrouter-cli/.env.example. Keep them separate so the two processes
+# `brainrouter-cli/.env.example`. Keep them separate so the two processes
 # can be configured independently.
-
-# ==========================================
-# LLM (cognitive extraction + synthesis)
-# ==========================================
-# Used by L1 extraction, contradiction checks, graph extraction, L2 scenes,
-# L3 persona synthesis. Falls back to OPENAI_API_KEY.
-BRAINROUTER_LLM_API_KEY=your_api_key_here
+#
+# All values in this template are blank placeholders. Fill in only what
+# you actually need — most settings have sensible defaults.
+
+
+# =============================================================================
+# 1. LLM (cognitive extraction + synthesis + judging)
+# =============================================================================
+# Shared credential and endpoint for every LLM-driven step on the MCP side:
+#   - cognitive extraction   (turn raw conversation into structured memories)
+#   - contradiction checks   (detect when a new memory conflicts with an old one)
+#   - graph extraction       (pull entities + relations into the knowledge graph)
+#   - focus-scene summaries  (group related memories under a scene heading)
+#   - persona synthesis      (cross-session identity / "who is this user")
+#   - relevance judging      (Stage 3 of retrieval — see section 2 below)
+#
+# Falls back to OPENAI_API_KEY when BRAINROUTER_LLM_API_KEY is unset.
+BRAINROUTER_LLM_API_KEY=
 
 # OpenAI-compatible chat-completions endpoint.
 # Examples:
@@ -29,116 +40,155 @@ BRAINROUTER_LLM_API_KEY=your_api_key_here
 #   LM Studio:  http://localhost:1234/v1/chat/completions
 #   Ollama:     http://localhost:11434/v1/chat/completions
 BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
-
 BRAINROUTER_LLM_MODEL=gpt-4o-mini
 
-# Optional model split.
+# Optional per-task model split. Both inherit BRAINROUTER_LLM_MODEL.
+#   - EXTRACTION_MODEL: high-volume, can be cheap/local
+#   - SYNTHESIS_MODEL: lower-volume but benefits from smarter models
 # BRAINROUTER_EXTRACTION_MODEL=gpt-4o-mini
 # BRAINROUTER_SYNTHESIS_MODEL=gpt-4o
 
-# Per-call timeout for MCP-side LLM calls. Default: 120000.
+# Per-call timeout for MCP-side LLM calls. Default 120000 (2 min).
 # BRAINROUTER_LLM_TIMEOUT_MS=120000
 
 # Cap on concurrent in-flight LLM calls FROM THE MCP PROCESS.
-# Default: 2 (set to 1 on consumer hardware running LM Studio with a single model).
+# Default 2. Set to 1 on consumer hardware running LM Studio with a single
+# model; raise to 10+ for cloud APIs.
 # BRAINROUTER_LLM_MAX_CONCURRENT=2
 
-# ==========================================
-# Embeddings (vector search)
-# ==========================================
-# Falls back to BRAINROUTER_LLM_API_KEY when omitted.
-# Vector search is disabled if no key is available.
+
+# =============================================================================
+# 2. Retrieval pipeline (three optional stages)
+# =============================================================================
+# Each stage layers on top of the always-on FTS5 keyword search. Add them in
+# order — every stage raises relevance but also adds latency.
+#
+#   Stage 1: Embeddings   — semantic vector recall (fused with keyword via RRF)
+#   Stage 2: Reranker     — cross-encoder reorders the candidate pool
+#   Stage 3: Judge        — LLM approves/rejects each finalist for relevance
+#
+# Skip any stage by leaving its credentials unset.
+
+# --- Stage 1: Embeddings ----------------------------------------------------
+# Vector search runs when an embedding key is available; otherwise the
+# pipeline falls back to keyword-only. Falls back to BRAINROUTER_LLM_API_KEY
+# when BRAINROUTER_EMBEDDING_API_KEY is unset.
 # BRAINROUTER_EMBEDDING_API_KEY=
 BRAINROUTER_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
 BRAINROUTER_EMBEDDING_MODEL=text-embedding-3-small
 BRAINROUTER_EMBEDDING_DIMENSIONS=1536
 
-# ==========================================
-# Reranker (optional)
-# ==========================================
-# Disabled unless a key is present.
+# --- Stage 2: Reranker (optional) -------------------------------------------
+# Cross-encoder rescores the candidate pool. Disabled unless a key is set.
+# Compatible with Cohere /v1/rerank or any vLLM-style /v1/rerank endpoint.
 # BRAINROUTER_RERANKER_API_KEY=
 # BRAINROUTER_RERANKER_ENDPOINT=https://api.cohere.com/v1/rerank
 # BRAINROUTER_RERANKER_MODEL=rerank-english-v3.0
 # BRAINROUTER_RERANKER_TOP_N=10
 
-# ==========================================
-# Storage
-# ==========================================
+# --- Stage 3: Relevance judge (optional, off by default) --------------------
+# LLM-as-judge gate that runs AFTER the reranker and drops candidates that
+# aren't actually relevant to the query. The reranker only re-orders; it
+# never filters — so a memory sharing vocabulary with the query but about
+# a different subject still makes it through. The judge fixes that.
+#
+# Adds one extra LLM call per recall: ~500ms-1s on a small/fast model.
+# Falls back to BRAINROUTER_LLM_* unless explicitly overridden, so a single
+# credential covers extraction, synthesis, and judging by default.
+# BRAINROUTER_RELEVANCE_JUDGE_ENABLED=true
+# BRAINROUTER_RELEVANCE_JUDGE_API_KEY=
+# BRAINROUTER_RELEVANCE_JUDGE_ENDPOINT=https://api.openai.com/v1/chat/completions
+# BRAINROUTER_RELEVANCE_JUDGE_MODEL=gpt-4o-mini
+# Max candidates sent to the judge in a single batched call. Default 10.
+# BRAINROUTER_RELEVANCE_JUDGE_MAX_CANDIDATES=10
+# Per-call timeout in ms. Default 15000.
+# BRAINROUTER_RELEVANCE_JUDGE_TIMEOUT_MS=15000
+
+
+# =============================================================================
+# 3. Memory engine
+# =============================================================================
+
+# --- Storage paths ----------------------------------------------------------
 # SQLite memory store path. Default: ~/.brainrouter/memory.db.
-# BRAINROUTER_MEMORY_DB=/Users/you/.brainrouter/memory.db
-
+# BRAINROUTER_MEMORY_DB=/path/to/memory.db
 # Override per-user state root. Default: ~/.brainrouter.
 # BRAINROUTER_HOME=/path/to/state
-
 # Workspace root when MCP --root is omitted.
 # BRAINROUTER_LOCAL_ROOT=/path/to/your/project
 
-# ==========================================
-# Memory engine
-# ==========================================
-# Set false to disable GraphRAG (2-hop entity expansion). Default: true.
+# --- Knowledge graph + contradictions ---------------------------------------
+# Disable GraphRAG (2-hop entity expansion) by setting to false. Default true.
 # BRAINROUTER_GRAPH_ENABLED=true
 # BRAINROUTER_GRAPH_TIMEOUT_MS=120000
 # BRAINROUTER_CONTRADICTION_TIMEOUT_MS=60000
 
-# Memories recalled this many times without citation are auto-archived.
-# 0 disables. Default: 10.
+# --- ACE feedback (auto-archive uncited memories) ---------------------------
+# Memories surfaced in recall this many times without being cited by the
+# agent get auto-archived. 0 disables. Default 10.
 # BRAINROUTER_ACE_ARCHIVE_THRESHOLD=10
 
-# Focus-scene distillation trigger (new records before scenes rebuild).
+# --- Distillation triggers --------------------------------------------------
+# Focus-scene summary — groups related cognitives under a scene heading.
+# Fires once every N new cognitive records.
 # BRAINROUTER_FOCUS_TRIGGER_N=10
 # BRAINROUTER_MAX_FOCUS_SCENES=20
 
-# Identity (persona) distillation trigger.
+# Persona synthesis — cross-session identity summary ("who is this user").
+# Fires once every N new cognitive records.
 # BRAINROUTER_IDENTITY_TRIGGER_N=50
+# In-memory persona cache lifetime. Default 3600000 (1h).
 # BRAINROUTER_PERSONA_CACHE_TTL_MS=3600000
 
-# ==========================================
-# Skill pre-warming
-# ==========================================
-# BRAINROUTER_PREWARM_ENABLED=false
+# --- Extraction backlog sweeper ---------------------------------------------
+# Background job that runs cognitive extraction over sensory rows the
+# per-turn extractor missed (errored, skipped, or interrupted).
+# BRAINROUTER_DISABLE_EXTRACTION_SWEEPER=true
+# BRAINROUTER_EXTRACTION_SWEEP_INTERVAL_MS=300000   # floor: 30000
+# BRAINROUTER_EXTRACTION_SWEEP_MIN_AGE_MS=120000
+# BRAINROUTER_EXTRACTION_MAX_FAILURES=5
+
+
+# =============================================================================
+# 4. Skill pre-warming (optional, off by default)
+# =============================================================================
+# Memetic skill activation — repeatedly invoking a skill heats it up so its
+# memory hints get pre-injected into context. Half-life decay keeps cold
+# skills from polluting the prompt.
+# BRAINROUTER_PREWARM_ENABLED=true
 # BRAINROUTER_SKILL_HALF_LIFE_MINUTES=10
 # BRAINROUTER_SKILL_MIN_TURN_DECAY=0.05
 # BRAINROUTER_SKILL_PREWARM_THRESHOLD=0.3
 # BRAINROUTER_SKILL_SPIKE_AMOUNT=1.0
 # BRAINROUTER_SKILL_MAX_POTENTIAL=4.0
 
-# ==========================================
-# Extraction backlog sweeper
-# ==========================================
-# BRAINROUTER_DISABLE_EXTRACTION_SWEEPER=false
-# BRAINROUTER_EXTRACTION_SWEEP_INTERVAL_MS=300000   # floored at 30000
-# BRAINROUTER_EXTRACTION_SWEEP_MIN_AGE_MS=120000
-# BRAINROUTER_EXTRACTION_MAX_FAILURES=5
 
-# ==========================================
-# Server auth
-# ==========================================
+# =============================================================================
+# 5. Server auth (HTTP MCP + dashboard)
+# =============================================================================
+# Only needed if you run the HTTP MCP transport or the web dashboard.
+# Stdio MCP (the default transport) doesn't use any of these.
+
 # Seeded admin (used when the users table is empty and by scripts/setup-admin.js).
 BRAINROUTER_DEFAULT_ADMIN_USER_ID=admin
 BRAINROUTER_ADMIN_EMAIL=admin@example.com
-BRAINROUTER_ADMIN_PASSWORD=change_me_before_use
+# Set on first boot to seed the admin password — leave blank afterward.
+BRAINROUTER_ADMIN_PASSWORD=
 
-# JWT signing key for dashboard sessions.
-# Generate one with:
+# JWT signing key for dashboard sessions. Generate with:
 #   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-# If unset, the server generates a random secret per boot — sessions do not survive restarts.
-BRAINROUTER_JWT_SECRET=replace_with_a_long_random_secret
+# If unset, the server generates a random secret per boot and sessions do
+# not survive restarts.
+BRAINROUTER_JWT_SECRET=
 # BRAINROUTER_JWT_EXPIRES_SECS=86400
 
 # Dashboard CORS allowlist.
 BRAINROUTER_CORS_ORIGIN=http://localhost:3000
 
-# API key for HTTP MCP transport clients. Usually set in the client config,
-# not here. Reset with: npm run setup:admin -- --reset --userId admin.
-# BRAINROUTER_API_KEY=br_your_api_key
+# API key for HTTP MCP transport clients. Usually configured in the client,
+# not here. Reset with: npm run setup:admin -- --reset --userId admin
+# BRAINROUTER_API_KEY=
 
 # Stdio fallback user id when no authenticated user mapping is available.
 # Prefer BRAINROUTER_API_KEY instead.
 # BRAINROUTER_USER_ID=default
-
-# ==========================================
-# Dashboard (read by web/, not by this server)
-# ==========================================
-# NEXT_PUBLIC_API_URL=http://localhost:3747

package/README.md

@@ -1,6 +1,14 @@
-# @kinqs/brainrouter-mcp-server
+# `@kinqs/brainrouter-mcp-server`
 
-The cognitive memory engine behind [BrainRouter](https://github.com/kinqsradiollc/BrainRouter) — exposed as a [Model Context Protocol](https://modelcontextprotocol.io/) server so any MCP-speaking agent (Claude Desktop, Cursor, [`@kinqs/brainrouter-cli`](https://www.npmjs.com/package/@kinqs/brainrouter-cli), custom clients) can recall, capture, and reason over long-term memory.
+The cognitive memory engine behind [BrainRouter](https://github.com/kinqsradiollc/BrainRouter)
+— exposed as a [Model Context Protocol](https://modelcontextprotocol.io/)
+server so any MCP-speaking agent (Claude Desktop, Cursor,
+[`@kinqs/brainrouter-cli`](https://www.npmjs.com/package/@kinqs/brainrouter-cli),
+custom clients) can recall, capture, and reason over long-term memory.
+
+Ships the `brainrouter-mcp` binary.
+
+---
 
 ## What it gives you
 
@@ -10,46 +18,111 @@ The cognitive memory engine behind [BrainRouter](https://github.com/kinqsradioll
 - **Skill catalogue** — `list_skills`, `get_skill`, `search_skills`, `get_persona` — ships with 70+ canonical skills bundled at publish time.
 - **HTTP and stdio transports** — run as a hosted service (HTTP/SSE) or spawn as a stdio child from any MCP client.
 
+---
+
 ## Install
 
 ```bash
-npm install @kinqs/brainrouter-mcp-server
+npm install -g @kinqs/brainrouter-mcp-server
 ```
 
-## Run
+The `-g` flag is required so `brainrouter-mcp` lands on your `$PATH`.
+See [`@kinqs/brainrouter-cli`'s README](https://www.npmjs.com/package/@kinqs/brainrouter-cli)
+for the sudo / nvm caveats — the same rules apply.
 
-```bash
-# HTTP transport on :3747
-npx brainrouter-mcp --http --port 3747
+Verify:
 
-# stdio (default — for clients that spawn the server themselves)
-npx brainrouter-mcp
+```bash
+which brainrouter-mcp
+brainrouter-mcp --version    # prints 0.3.5
 ```
 
+---
+
 ## Configure
 
-Copy `.env.example` to `.env` and set at minimum:
+The server reads its config from a `.env` file. The challenge for a
+globally-installed package is that you don't know where the package
+lives, and even if you did, it's typically in a path you can't easily
+edit (`/usr/local/lib/node_modules/...` or similar). To fix that, the
+server looks for `.env` in three places, in order:
+
+1. `$BRAINROUTER_ENV_FILE` — explicit override (set this when you want a
+   per-project or per-deployment config).
+2. `~/.config/brainrouter/server.env` — the canonical user location.
+3. `./.env` — current working directory (matches the classic dotenv
+   behavior; useful for monorepo dev).
+
+At startup the server prints which path it loaded from, so there's never
+any ambiguity:
+
+```
+env: loaded 17 vars from /Users/you/.config/brainrouter/server.env
+```
+
+### One-time setup
 
 ```bash
+brainrouter-mcp init             # scaffolds ~/.config/brainrouter/server.env
+$EDITOR ~/.config/brainrouter/server.env
+```
+
+`init` copies the package's bundled `.env.example` to
+`~/.config/brainrouter/server.env` and chmods it to `0600`. It won't
+overwrite an existing file.
+
+### Minimum fields to set
+
+```bash
+# Cognitive extraction LLM (any OpenAI-compatible endpoint:
+# OpenAI, OpenRouter, LM Studio, Ollama, vLLM…)
 BRAINROUTER_LLM_API_KEY=sk-...
 BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
 BRAINROUTER_LLM_MODEL=gpt-4o-mini
 
+# Embeddings — required for vector recall. Key falls back to BRAINROUTER_LLM_API_KEY.
 BRAINROUTER_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
 BRAINROUTER_EMBEDDING_MODEL=text-embedding-3-small
 BRAINROUTER_EMBEDDING_DIMENSIONS=1536
 
+# Server auth — change before exposing the server
 BRAINROUTER_ADMIN_PASSWORD=change_me_before_use
-BRAINROUTER_JWT_SECRET=replace_with_a_long_random_secret
+BRAINROUTER_JWT_SECRET=replace_with_a_long_random_secret  # `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
+```
+
+Full knob list (reranker, prewarming, focus-scene triggers, sweep
+intervals, JWT, CORS) lives in the bundled `.env.example` — view it
+after `init` ran, or directly with:
+
+```bash
+cat "$(npm root -g)/@kinqs/brainrouter-mcp-server/.env.example"
 ```
 
-Full knob list (reranker, prewarming, focus-scene triggers, sweep intervals, JWT, CORS) lives in `.env.example` next to this README.
+---
+
+## Run
+
+```bash
+# HTTP transport on :3747 — what the CLI connects to via login
+brainrouter-mcp --http --port 3747
+
+# stdio transport — for clients that spawn the server themselves
+brainrouter-mcp
+```
+
+The server writes logs to stderr. To leave it running detached, use a
+process manager (launchd / systemd / tmux / `nohup`) of your choice.
+
+---
 
 ## Docs
 
-- [BrainRouter overview](https://github.com/kinqsradiollc/BrainRouter)
-- [What the memory engine does](https://github.com/kinqsradiollc/BrainRouter/blob/main/BRAINROUTER.md)
-- [Deep dives](https://github.com/kinqsradiollc/BrainRouter/tree/main/brainrouter-docs)
+- **Repo**: <https://github.com/kinqsradiollc/BrainRouter>
+- **Memory engine deep-dive**: [BRAINROUTER.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/BRAINROUTER.md)
+- **Maintainer runbook**: [SETUP.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/SETUP.md)
+- **Bugs / requests**: <https://github.com/kinqsradiollc/BrainRouter/issues>
+
+---
 
 ## License
 

package/dist/__tests__/cognitive-extractor.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { extractCognitiveMemories } from "../memory/pipeline/cognitive-extractor.js";
+function makeMessage(messageText) {
+    const recordedAt = new Date().toISOString();
+    return {
+        id: "sensory_test",
+        userId: "user_test",
+        sessionKey: "session_test",
+        sessionId: "session_test",
+        role: "user",
+        messageText,
+        recordedAt,
+        timestamp: Date.parse(recordedAt),
+        skillTag: "",
+    };
+}
+function makeRunner(raw) {
+    return {
+        run: async () => raw,
+    };
+}
+function memory(content) {
+    return `{
+    "type": "episodic",
+    "content": "${content}",
+    "priority": 50,
+    "sourceKind": "model_inference",
+    "verificationStatus": "unverified"
+  }`;
+}
+async function extractContents(raw) {
+    const result = await extractCognitiveMemories({
+        messages: [makeMessage("capture these paths")],
+        userId: "user_test",
+        sessionKey: "session_test",
+        sessionId: "session_test",
+        llmRunner: makeRunner(raw),
+    });
+    expect(result.success).toBe(true);
+    return result.records.map((record) => record.content);
+}
+describe("cognitive extractor JSON escape repair", () => {
+    it("round-trips ambiguous path backslashes without interpreting them as escapes", async () => {
+        const raw = String.raw `[
+      {
+        "scene_name": "Path repair",
+        "memories": [
+          ${memory(String.raw `C:\users\file`)},
+          ${memory(String.raw `C:\bin\node.exe`)},
+          ${memory(String.raw `/repos/\target/release`)},
+          ${memory(String.raw `\release\foo.txt`)},
+          ${memory(String.raw `line1\nline2`)}
+        ]
+      }
+    ]`;
+        await expect(extractContents(raw)).resolves.toEqual([
+            String.raw `C:\users\file`,
+            String.raw `C:\bin\node.exe`,
+            String.raw `/repos/\target/release`,
+            String.raw `\release\foo.txt`,
+            String.raw `line1\nline2`,
+        ]);
+    });
+    it("keeps legitimate JSON escapes on the happy path", async () => {
+        const raw = String.raw `[
+      {
+        "scene_name": "Happy path",
+        "memories": [
+          ${memory(String.raw `line1\nline2`)}
+        ]
+      }
+    ]`;
+        await expect(extractContents(raw)).resolves.toEqual(["line1\nline2"]);
+    });
+    it("decodes \\uXXXX unicode escapes on the happy path", async () => {
+        // The input JSON contains the literal 6-char sequence é (an
+        // escape sequence as text). When the JSON is well-formed, the first
+        // JSON.parse handles the escape and we get the actual é code point.
+        // Locks down the contract for content like "café" / "résumé" /
+        // non-ASCII names emitted by LLMs that escape non-ASCII output.
+        const raw = String.raw `[
+      {
+        "scene_name": "Unicode happy",
+        "memories": [
+          ${memory(String.raw `café done`)}
+        ]
+      }
+    ]`;
+        await expect(extractContents(raw)).resolves.toEqual(["café done"]);
+    });
+    it("preserves \\uXXXX literally when repair fires (paths win the tie-break)", async () => {
+        // If anything in the batch forces the repair branch (here: a Windows
+        // path with \u + non-hex), then ALL ambiguous backslashes — including
+        // otherwise-valid \uXXXX unicode escapes elsewhere in the payload —
+        // become literal. Deliberate tradeoff: silent path corruption is
+        // worse than a one-off escaped unicode that doesn't decode. The
+        // resulting content has a literal `é` (6 chars) instead of "é".
+        const raw = String.raw `[
+      {
+        "scene_name": "Unicode + path collision",
+        "memories": [
+          ${memory(String.raw `C:\users\file`)},
+          ${memory(String.raw `café collateral`)}
+        ]
+      }
+    ]`;
+        await expect(extractContents(raw)).resolves.toEqual([
+            String.raw `C:\users\file`,
+            String.raw `café collateral`,
+        ]);
+    });
+});

package/dist/__tests__/crypto.test.js

@@ -22,7 +22,14 @@ describe("crypto auth helpers", () => {
     });
     it("verifyJwt returns null for tampered signature", () => {
         const token = signJwt({ userId: "u1" }, "secret", 60);
-        const tampered = `${token.slice(0, -1)}x`;
+        // Pick a replacement char that is GUARANTEED to differ from the
+        // original last char. The previous version hard-coded "x"; whenever
+        // the JWT's base64url signature happened to end in "x" (~1/64 odds),
+        // the "tampered" token equalled the original and verification
+        // succeeded — flaky failure. See PR #22 CI run 26323691062.
+        const lastChar = token.slice(-1);
+        const replacement = lastChar === "A" ? "B" : "A";
+        const tampered = token.slice(0, -1) + replacement;
         expect(verifyJwt(tampered, "secret")).toBeNull();
     });
 });

package/dist/__tests__/working-memory.test.js

@@ -197,4 +197,71 @@ describe("short-term working memory tools", () => {
         expect(existsSync(join(resolve("abc123abc123"), ".brainrouter"))).toBe(false);
         rmSync(result.state.workDir, { recursive: true, force: true });
     });
+    it("round-trips kind:\"reasoning\" through offload → context", async () => {
+        // 0.3.6 item 2c: agents now offload a structured "Why: …" step after
+        // every non-trivial tool batch. The kind field is free-form on the
+        // schema, so a regression that silently dropped or overwrote the value
+        // (e.g. always-default to "tool_output") would erase the entire
+        // audit-trail surface. Pin the round-trip explicitly.
+        const workspacePath = mkdtempSync(join(tmpdir(), "brainrouter-working-reasoning-"));
+        const userId = "user-1";
+        const sessionKey = "reasoning-session";
+        const offload = parseToolJson(await handleMemoryWorkingTool("memory_working_offload", {
+            workspacePath,
+            userId,
+            sessionKey,
+            payload: "Decided to refactor canvas.ts because rendering by kind was missing.",
+            title: "Why: refactor canvas for kind-aware rendering",
+            summary: "Picked the dashed-border style for reasoning nodes.",
+            kind: "reasoning",
+        }));
+        expect(offload.state.injectedState.currentNode.kind).toBe("reasoning");
+        const context = parseToolJson(await handleMemoryWorkingTool("memory_working_context", {
+            workspacePath,
+            userId,
+            sessionKey,
+        }));
+        expect(context.steps).toHaveLength(1);
+        expect(context.steps[0].kind).toBe("reasoning");
+        expect(context.state.injectedState.recentSteps[0].kind).toBe("reasoning");
+    });
+    it("renders reasoning-kind nodes with a distinct Mermaid style in the canvas", async () => {
+        // The canvas needs to visually separate reasoning ("why") nodes from
+        // tool_output ("what came back") and compressed_summary ("the older
+        // history got rolled up") nodes, so a human inspecting `canvas.mmd`
+        // can see the decision trail at a glance. Pin the style emission so a
+        // future refactor of canvas.ts can't silently flatten all kinds back
+        // to a single shape.
+        const workspacePath = mkdtempSync(join(tmpdir(), "brainrouter-working-canvas-kind-"));
+        const userId = "user-1";
+        const sessionKey = "canvas-kind-session";
+        const tool = parseToolJson(await handleMemoryWorkingTool("memory_working_offload", {
+            workspacePath,
+            userId,
+            sessionKey,
+            payload: "tool output payload",
+            title: "Tool result",
+            summary: "Read repo files",
+            kind: "tool_output",
+        }));
+        const reason = parseToolJson(await handleMemoryWorkingTool("memory_working_offload", {
+            workspacePath,
+            userId,
+            sessionKey,
+            payload: "Chose dashed-border style because reasoning is conceptually different from tool output.",
+            title: "Why: dashed style for reasoning",
+            summary: "Visual separation of why vs. what.",
+            kind: "reasoning",
+        }));
+        const context = parseToolJson(await handleMemoryWorkingTool("memory_working_context", {
+            workspacePath,
+            userId,
+            sessionKey,
+        }));
+        // Reasoning node must carry a distinct stroke-dasharray style line.
+        // Tool-output node must NOT carry that same dashed style — otherwise
+        // the "distinct" claim is meaningless.
+        expect(context.canvas).toMatch(new RegExp(`style ${reason.nodeId} [^\\n]*stroke-dasharray`));
+        expect(context.canvas).not.toMatch(new RegExp(`style ${tool.nodeId} [^\\n]*stroke-dasharray`));
+    });
 });

package/dist/env-loader.js

@@ -0,0 +1,47 @@
+// Side-effect module: imported FIRST in src/index.ts so it sets process.env
+// from the right .env file BEFORE any other module evaluates and tries to
+// read those vars.
+//
+// Priority order (first hit wins):
+//   1. $BRAINROUTER_ENV_FILE              (explicit user override)
+//   2. ~/.config/brainrouter/server.env   (canonical user location — the
+//                                          one a globally-installed
+//                                          `npm i -g @kinqs/brainrouter-mcp-server`
+//                                          user should write to)
+//   3. ./.env                              (cwd — matches dotenv default,
+//                                          keeps monorepo dev working)
+//
+// The third entry matches dotenv's classic behavior, so existing
+// `cd brainrouter/ && npm run start:http` workflows keep loading
+// `brainrouter/.env` exactly as before. The first two are the additions
+// that fix the global-install UX (users no longer need to cd anywhere
+// special).
+import dotenv from 'dotenv';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+function resolveEnvFile() {
+    const candidates = [
+        process.env.BRAINROUTER_ENV_FILE,
+        path.join(os.homedir(), '.config', 'brainrouter', 'server.env'),
+        path.join(process.cwd(), '.env'),
+    ].filter(Boolean);
+    for (const file of candidates) {
+        if (fs.existsSync(file))
+            return file;
+    }
+    return null;
+}
+const envFile = resolveEnvFile();
+if (envFile) {
+    const result = dotenv.config({ path: envFile });
+    const count = Object.keys(result.parsed ?? {}).length;
+    process.stderr.write(`env: loaded ${count} var${count === 1 ? '' : 's'} from ${envFile}\n`);
+}
+else {
+    process.stderr.write(`env: no .env file found — looked at:\n` +
+        `  $BRAINROUTER_ENV_FILE  (${process.env.BRAINROUTER_ENV_FILE ? 'set, but missing' : 'unset'})\n` +
+        `  ~/.config/brainrouter/server.env\n` +
+        `  ${path.join(process.cwd(), '.env')}\n` +
+        `Run 'brainrouter-mcp init' to scaffold one (or set BRAINROUTER_LLM_API_KEY and friends in your shell).\n`);
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+import './init.js';
+import './env-loader.js';