@kinqs/brainrouter-cli 0.3.5 → 0.3.7

package/README.md

@@ -6,8 +6,6 @@ recall, skills, and capture.
 
 Ships the `brainrouter` binary.
 
----
-
 ## Install
 
 ```bash
@@ -23,52 +21,44 @@ command not found`.
 
 | How Node is installed | Use `sudo`? |
 |---|---|
-| Homebrew (`brew install node`) | ❌ No — global prefix is user-writable |
-| nvm / asdf / fnm | ❌ No — same reason |
-| System Node on macOS / Linux | ✅ Yes — global prefix is `/usr/local/...` |
-
-Check yours:
-
-```bash
-npm config get prefix
-```
+| Homebrew (`brew install node`) | No — global prefix is user-writable |
+| nvm / asdf / fnm | No — same reason |
+| System Node on macOS / Linux | Yes — global prefix is `/usr/local/...` |
 
-If the path is under `/Users/...`, `/opt/homebrew/...`, or your home dir
-→ no sudo. If it's `/usr/local/...` → use sudo.
+Check yours: `npm config get prefix`. If the path is under `/Users/...`,
+`/opt/homebrew/...`, or your home dir — no sudo. If it's `/usr/local/...` — use sudo.
 
 Verify the install:
 
 ```bash
 which brainrouter           # prints the path to the binary
-brainrouter --version       # prints 0.3.5
+brainrouter --version       # prints 0.3.7
 ```
 
----
-
 ## Configure
 
-Two configuration surfaces, both one-time:
-
-### 1. The chat LLM and MCP server profile
+Run `brainrouter` for the first time and the **setup wizard** starts
+automatically:
 
-```bash
-brainrouter config          # interactive — set LLM provider, model, key, endpoint
-brainrouter login           # interactive — set MCP server URL + API key
+```
+Welcome → Theme → Provider → API key → Model → MCP → AGENT.md → Done
 ```
 
-Both write to `~/.config/brainrouter/config.json`.
+It writes everything to `~/.config/brainrouter/config.json` — no manual
+file editing needed.
 
-For local-model setups (LM Studio / Ollama), point the LLM endpoint at
-`http://localhost:1234/v1/chat/completions` or `http://localhost:11434/v1/chat/completions`.
+To re-run the wizard later: type `/init` inside the REPL.
 
-### 2. (Optional) Runtime knobs — `~/.config/brainrouter/cli.env` or `./brainrouter-cli.env`
+To change a single setting: use `/config <key> <value>` or the `/config`
+home panel. To re-configure the MCP server connection: use `/login`.
 
-Only needed if you want to tune sandbox, tool-loop limits, trace logging,
-or web-search backend. See the [`.env.example`](.env.example) bundled with
-this package for the full list. LLM credentials do **not** go here — they
-live in `config.json`.
+For local-model setups (LM Studio / Ollama), point the LLM endpoint at
+`http://localhost:1234/v1/chat/completions` or `http://localhost:11434/v1/chat/completions`.
 
----
+**Runtime knobs** (sandbox, trace log, web-search backend, tool-loop limits)
+are set as shell environment variables. See
+[`brainrouter-docs/configuration.md`](https://github.com/kinqsradiollc/BrainRouter/blob/main/brainrouter-docs/configuration.md)
+for the full list.
 
 ## Run
 
@@ -83,22 +73,15 @@ Inside the REPL, type `/help` for the full slash-command list (60+
 commands across session / memory / workflow / orchestration / observability
 surfaces).
 
-### Offline mode
-
-If the MCP server isn't reachable, the CLI still boots — but only local
-tools (file edits, shell, web fetch, `spawn_agent`) work. Memory recall,
-capture, and skills are disabled until the server is back. The startup
-banner shows `⚠️  OFFLINE MODE` when this happens. Pass `--strict-mcp` to
+**Offline mode** — if the MCP server isn't reachable, the CLI still boots
+with only local tools (file edits, shell, web fetch, `spawn_agent`). Memory
+recall, capture, and skills are disabled until the server is back. The
+startup banner shows `offline` when this happens. Pass `--strict-mcp` to
 make the CLI exit instead of degrading.
 
-### Stdio mode
-
-If you'd rather have the CLI spawn the MCP server as a child process
-instead of running it separately, use `brainrouter config` → "Set Active
-Server Profile" → `default` (the bundled stdio profile). You don't need
-to run anything else — the CLI manages the server's lifecycle.
-
----
+**Stdio mode** — to have the CLI spawn the MCP server as a child process
+instead of running it separately: open `/config`, go to MCP settings, and
+pick the bundled `stdio` profile. The CLI manages the server's lifecycle.
 
 ## Workspace detection
 
@@ -113,8 +96,6 @@ BRAINROUTER_WORKSPACE=/absolute/path/to/project brainrouter
 
 Inside the REPL, run `/workspace` to confirm the active root and session key.
 
----
-
 ## What you also probably want
 
 A BrainRouter MCP server for the cognitive memory. The CLI works without
@@ -127,9 +108,7 @@ $EDITOR ~/.config/brainrouter/server.env          # set BRAINROUTER_LLM_API_KEY,
 brainrouter-mcp --http --port 3747                # in a separate terminal
 ```
 
-Then `brainrouter login` and point at `http://localhost:3747/mcp`.
-
----
+Then run `/login` inside the REPL and point at `http://localhost:3747/mcp`.
 
 ## Docs
 
@@ -138,8 +117,6 @@ Then `brainrouter login` and point at `http://localhost:3747/mcp`.
 - **Maintainer runbook**: [SETUP.md](https://github.com/kinqsradiollc/BrainRouter/blob/main/SETUP.md)
 - **Bugs / requests**: <https://github.com/kinqsradiollc/BrainRouter/issues>
 
----
-
 ## License
 
 MIT

package/agents/architect.json

@@ -0,0 +1,18 @@
+{
+  "id": "architect",
+  "displayName": "Architect",
+  "whenToUse": "Design alternatives and tradeoffs for a feature or system change. No file writes.",
+  "prompt": "## Role: Architect\nYou design solutions; you do not write production code.\n\n### Memory-first opening (mandatory)\n- `memory_search` and `memory_graph_query` for the feature/domain — past architecture decisions often constrain new ones.\n- `memory_contradictions` (action: list) — if prior designs contradict the proposed change, flag it.\n- Cite any architecture_decision records you find with their recordId.\n\nAlways present at least two design alternatives with explicit tradeoffs (complexity, blast radius, reversibility, test cost).\nEnd with a clear recommendation and the smallest first vertical slice.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "read",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_architect",
+  "tier": "reasoning",
+  "outputContract": null
+}

package/agents/explorer.json

@@ -0,0 +1,18 @@
+{
+  "id": "explorer",
+  "displayName": "Explorer",
+  "whenToUse": "Read-only codebase investigation. Returns concrete file paths, line ranges, and a short list of facts.",
+  "prompt": "## Role: Explorer\nYou are a read-only investigator. Do not edit files or run shell commands.\nGoal: map the relevant code, return concrete file paths with line ranges, and surface the few facts the parent needs to decide.\n\n### Memory-first opening (mandatory)\n- Step 1: `memory_search` for the topic of investigation. Past explorers may have mapped this already — do not re-discover what BrainRouter already knows.\n- Step 2: `memory_graph_query` with the dominant feature/entity name to surface related memories across 2 hops.\n- Step 3: `memory_file_history` for any file the parent specifically mentions.\n- Cite every recordId you build on. Your output begins with a `### Memory consulted` block listing the record IDs and what they told you.\n\nOutput structure: 1) Memory consulted, 2) Summary (3-5 bullets), 3) Key files with line ranges, 4) Open questions, 5) Suggested next probe.\nNever claim work is complete without naming actual files you read AND showing the memory you consulted.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "read",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_explorer",
+  "tier": "reasoning",
+  "outputContract": null
+}

package/agents/reviewer.json

@@ -0,0 +1,18 @@
+{
+  "id": "reviewer",
+  "displayName": "Reviewer",
+  "whenToUse": "Code review stance; findings first, severity-ordered. Read-only.",
+  "prompt": "## Role: Reviewer\nYou review changes critically. Findings first; severity-ordered (blocker, major, minor, nit).\n\n### Memory-first opening (mandatory)\n- `memory_search` for prior reviews on the same files or feature — never re-flag an issue another reviewer already decided is acceptable.\n- `memory_file_history` for each file in the diff — known regressions and prior bug fixes inform your verdict.\n- Cite related recordIds inline in each finding so the parent can see the precedent.\n\nFor each finding: file:line, what is wrong, why it matters, suggested fix.\nDo not make edits. The parent will decide what to apply.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "read",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_reviewer",
+  "tier": "reasoning",
+  "outputContract": null
+}

package/agents/verifier.json

@@ -0,0 +1,18 @@
+{
+  "id": "verifier",
+  "displayName": "Verifier",
+  "whenToUse": "Runs tests and checks; reports pass/fail with evidence.",
+  "prompt": "## Role: Verifier\nYou verify that recent changes work. Run the smallest useful set of tests/typechecks.\n\n### Memory-first opening (mandatory)\n- `memory_search` for prior failure modes on these tests — flaky tests, environment caveats, and known-bad commands live in memory.\n- `memory_file_history` for any test file involved — past fixes for the same suite are highly relevant.\n\nReport: which command(s) you ran, exit codes, failing output (trimmed), and a clear PASS/FAIL verdict.\nNever claim PASS without actually executing a check. On failure, call `memory_task_update` with the blocker so the next worker can pick it up.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "shell",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_verifier",
+  "tier": "worker",
+  "outputContract": null
+}

package/agents/worker.json

@@ -0,0 +1,18 @@
+{
+  "id": "worker",
+  "displayName": "Worker",
+  "whenToUse": "Implementation-focused. May edit files when granted write access.",
+  "prompt": "## Role: Worker\nYou implement a single bounded task. Keep edits minimal and scoped.\n\n### Memory-first opening (mandatory)\n- `memory_recall` for the task topic — past instructions, conventions, and tool_preference records often dictate HOW to implement.\n- `memory_file_history` for the files you intend to touch — known fragility lives there.\n- If the parent gave you `seedRecordIds`, treat those as authoritative context.\n- `memory_task_state` if this looks like a continuation — pick up where prior work left off.\n\nRead before editing. Prefer edit_file over write_file when possible. Prefer apply_patch for multi-file edits.\nOn completion call `memory_task_update` with the outcome, then report exactly which files you changed and any follow-ups the verifier should run.",
+  "model": null,
+  "effort": null,
+  "defaultAccess": "write",
+  "toolScope": { "local": ["*"], "mcp": ["memory_*"] },
+  "disallowedTools": [],
+  "maxIterations": 30,
+  "timeoutMs": 120000,
+  "maxResultChars": 8000,
+  "subagents": [],
+  "delegateName": "delegate_worker",
+  "tier": "worker",
+  "outputContract": null
+}

package/bin/cli.cjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * Thin CommonJS shim that runs BEFORE the real ESM CLI entrypoint.
+ *
+ * Why CJS for the bin: ESM hoists all `import` statements above any
+ * top-level code in the module that owns them. The CLI imports
+ * `node:sqlite` transitively via `config/config.ts`, which triggers
+ * Node's `ExperimentalWarning` the FIRST time the module is touched —
+ * and that happens during import resolution, before any line of code
+ * in `src/index.ts` runs. So a warning filter installed inside that
+ * file always fires too late.
+ *
+ * This shim does three things synchronously, with zero ESM imports
+ * blocking it, and only then hands off:
+ *
+ *   1. Remove Node's default "warning" printer.
+ *   2. Install a filtered listener that drops `ExperimentalWarning`
+ *      (sqlite, ESM in older Node) and dotenv self-promotion lines.
+ *   3. Override `process.emitWarning` so future direct callers also
+ *      route through the same filter.
+ *
+ * Anything BrainRouter itself emits via `process.emitWarning('…',
+ * 'BrainRouterWarning')` (or any non-suppressible type) flows through
+ * unchanged. NODE_NO_WARNINGS=1 would silence those too, which is why
+ * we don't just set that env.
+ *
+ * The shim then dynamically imports the ESM entry. Dynamic `import()`
+ * is the only way to load ESM from CJS; it returns a promise we await
+ * so an unhandled rejection during boot still surfaces as an error.
+ */
+
+function isSuppressibleWarning(message, type) {
+  const looksExperimental =
+    type === 'ExperimentalWarning' ||
+    /experimental feature|SQLite is an experimental/i.test(message);
+  const looksDotenvNoise = /dotenv@\d|dotenvx|dotenv\.org/i.test(message);
+  return looksExperimental || looksDotenvNoise;
+}
+
+for (const listener of process.listeners('warning')) {
+  process.removeListener('warning', listener);
+}
+process.on('warning', (warning) => {
+  const message = (warning && warning.message) || '';
+  const type = (warning && warning.name) || '';
+  if (isSuppressibleWarning(message, type)) return;
+  process.stderr.write(`(node:${process.pid}) ${type || 'Warning'}: ${message || warning}\n`);
+});
+
+const originalEmitWarning = process.emitWarning.bind(process);
+process.emitWarning = function emitWarning(warning, ...rest) {
+  const message = typeof warning === 'string' ? warning : (warning && warning.message) || '';
+  const type =
+    typeof rest[0] === 'string' ? rest[0] :
+    (rest[0] && typeof rest[0] === 'object' && 'type' in rest[0]) ? rest[0].type :
+    (warning && warning.name) || '';
+  if (isSuppressibleWarning(message, type)) return;
+  return originalEmitWarning(warning, ...rest);
+};
+
+// Path to the compiled ESM entry, resolved relative to this shim.
+const path = require('node:path');
+const url = require('node:url');
+const entry = path.resolve(__dirname, '..', 'dist', 'index.js');
+import(url.pathToFileURL(entry).href).catch((err) => {
+  // Surface boot-time errors verbatim — a silent exit would just look like
+  // the CLI never started.
+  process.stderr.write(`brainrouter: failed to load CLI entrypoint: ${(err && err.stack) || err}\n`);
+  process.exit(1);
+});