spectoflow 0.28.0 → 0.29.0

package/README.md

@@ -91,6 +91,9 @@ spectoflow dashboard init [--path=<dir>]       create/move the dashboard workspa
 spectoflow dashboard validate <file>           check a custom-view JSON against the block schema
 spectoflow config [get|set <key> [<value>]]    global defaults + dashboard URL/path (~/.spectoflow/config.json)
 
+spectoflow brain                               your second brain: entries, and which agents can reach it
+spectoflow brain setup [--dry-run]             connect your installed agents to it (once per machine)
+
 spectoflow skill create "..." | --auto         generate a project skill
 spectoflow agent create "..." | --auto         generate a project agent
 
@@ -256,7 +259,7 @@ it grows one extra, optional connection outward:
 | `spectoflow dashboard logout` | your machine | unlink the machine entirely |
 
 The header bar always shows the brand, the **active agent**, autonomy mode, language, a global-progress
-meter, a sync dot, and a **Run** quick-action. Thirteen tabs — and **which ones you see, and in what
+meter, a sync dot, and a **Run** quick-action. Fourteen tabs — and **which ones you see, and in what
 order, is up to you** (Personalize → *Navigation tabs*: enable / disable / reorder; two of them ship
 off by default):
 
@@ -279,6 +282,8 @@ off by default):
 - **Info** — a project-at-a-glance summary.
 - **Documentation** — the live supported-agents table (your own install status + links) plus the CLI
   command reference.
+- **Second brain** — what spectoflow has learned about you, shared by all your projects: read, add, fix,
+  confirm (see [Second brain](#second-brain)). Local only.
 - **Personalize** — autonomy mode, language, design, the active agent, **navigation tabs**, **slash
   commands**, and **Extend spectoflow** (see *Customize* below).
 
@@ -343,6 +348,50 @@ spectoflow agent create "owns accessibility review"          # or: --auto
 spectoflow dashboard create "a KPI overview for support"     # or: --auto
 ```
 
+## Second brain
+
+spectoflow learns about **you** as you work, and remembers it across all your projects: your role, your
+preferences, how you like to work, what to avoid. Every agent session starts with it, whatever the agent.
+
+```
+  you work, in any project, with any agent
+        │  "commit messages in English, always"
+        ▼
+  the agent records it ── brain_learn ──►  ~/.spectoflow/brain.md   (one file, yours, never in a repo)
+                                                   │
+        ┌──────────────────────────────────────────┼─────────────────────────────┐
+        ▼                                          ▼                             ▼
+  next session, any project:             dashboard → Second brain tab:   you can edit the file
+  the agent starts with it               read, add, fix, confirm         by hand, too
+```
+
+**One-time setup, per machine:**
+
+```bash
+spectoflow brain setup --dry-run   # see what it would change
+spectoflow brain setup             # connect every coding agent installed on this machine
+```
+
+It registers a small MCP server, `spectoflow mcp`, in each installed agent's **user-level** config (Claude
+Code, Codex, Cursor, Gemini, OpenCode, Kiro, Antigravity, Copilot, Amazon Q, Droid, Auggie, Kimi; Goose
+gets a snippet to paste). It never touches an existing entry and never rewrites a file it can't parse. The
+agents then read and grow your second brain through that server: nothing is copied into your projects.
+
+- **Four categories:** Profile, Preferences, Working style, Avoid.
+- **Facts an agent records through MCP are added directly by default.** To review them first, untick *Add what the agent learns
+  directly* on the page, or run `spectoflow config set brain.autoAdd false`: new facts then wait in
+  *To confirm*.
+- **What gets recorded:** durable facts only. Never secrets, credentials or sensitive personal data, never
+  a one-off instruction. The rule is written in every agent's instructions and in the MCP tools themselves.
+- **Runs launched from the dashboard:** non-interactive agents often refuse MCP tools, so the agent prints a
+  `::spectoflow learn category=… msg=…` line instead. Those always wait in *To confirm*, whatever the setting:
+  that output also carries command output and file contents, so a line hidden in a repository can't slip
+  in unseen.
+- **Private:** the Second brain tab and its API answer this machine only — not the online dashboard
+  (`server/` refuses them for everyone, the project owner included), and not other machines on your network.
+  A run started from either of those can't write into it, and a learned fact never goes into a project's chat
+  log.
+
 ## Agents vs skills
 
 Agents (`.spectoflow/agents/`) are **stable team personas** (Product Manager, Developer, QA Engineer…).

package/bin/spectoflow.js

@@ -374,6 +374,40 @@ function configCmd() {
   } catch (e) { console.log(`${c.y('!')} ${e.message}`); process.exitCode = 1; }
 }
 
+// ---- brain: the user's second brain (~/.spectoflow/brain.md), shared by every project ----
+function brainCmd() {
+  const brain = require('../lib/brain');
+  const brainSetup = require('../lib/brain-setup');
+  const tilde = (p) => (p.startsWith(os.homedir()) ? '~' + p.slice(os.homedir().length) : p);
+  if (argv[1] === 'setup') {
+    const dryRun = argv.includes('--dry-run');
+    const rows = brainSetup.setup({ binPath: __filename, dryRun });
+    console.log(wordmark());
+    console.log(`  ${c.bold('spectoflow brain setup')}${dryRun ? c.dim('   (dry-run)') : ''}   ${c.dim('registers the spectoflow MCP server in each installed agent (user level, once per machine)')}\n`);
+    if (!rows.length) { console.log(`  ${c.y('!')} No supported coding agent found on PATH.\n`); return; }
+    const w = Math.max(...rows.map((r) => r.label.length));
+    const sym = { created: c.cy('+'), added: c.g('✓'), exists: c.dim('·'), skipped: c.y('!'), manual: c.y('!'), failed: c.y('✗') };
+    for (const r of rows) {
+      console.log(`  ${sym[r.status] || '?'}  ${r.label.padEnd(w)}  ${r.status.padEnd(8)}  ${c.dim(r.via || tilde(r.file))}`);
+      if (r.status === 'skipped') console.log(c.dim(`       couldn't parse this file (comments?) — left untouched; add a "spectoflow" server running: spectoflow mcp`));
+      if (r.status === 'manual') console.log(c.dim(r.id === 'goose' ? `       YAML isn't edited automatically — add this to ${tilde(r.file)}:\n` : `       this file already mentions spectoflow in a form we can't read safely — check it, and add this if it's missing:\n`) + r.manual.split('\n').map((l) => '         ' + l).join('\n'));
+      if (r.status === 'failed') console.log(c.dim(`       ${r.detail || 'failed'}${r.manual ? `\n       run it yourself: ${r.manual}` : ''}`));
+    }
+    const changed = rows.filter((r) => ['created', 'added'].includes(r.status)).length;
+    console.log(`\n  ${dryRun ? c.dim('(dry-run — nothing was written)') : changed ? c.g(`✓ ${changed} agent(s) wired`) + c.dim(' — start a new agent session to load it') : c.dim('Nothing to change')}\n`);
+    return;
+  }
+  const r = brain.read();
+  console.log(wordmark());
+  console.log(`  ${c.bold('Second brain')}   ${c.dim(tilde(brain.brainPath()))}`);
+  console.log(`  ${r.entries.length} entr${r.entries.length === 1 ? 'y' : 'ies'}${r.pending.length ? c.y(` · ${r.pending.length} to confirm`) : ''}   ${c.dim('learned facts: ' + (r.autoAdd ? 'added directly' : 'wait for your confirmation') + ' (spectoflow config set brain.autoAdd true|false)')}\n`);
+  const agents = brainSetup.status();
+  if (!agents.length) console.log(`  ${c.y('!')} No supported coding agent found on PATH.`);
+  agents.forEach((a) => console.log(`  ${a.wired ? c.g('●') : c.dim('○')} ${a.label}${a.wired ? '' : c.dim('  not wired')}`));
+  if (agents.some((a) => !a.wired)) console.log(`\n  ${c.dim('wire them:')} ${c.g('spectoflow brain setup')} ${c.dim('[--dry-run]')}`);
+  console.log('');
+}
+
 // ---- Customize: `spectoflow skill/agent/dashboard create` — the CLI mirror of the dashboard's
 // Settings → Customize UI. Both surfaces build the same natural-language prompt (customize-prompts.js)
 // and post it through the same pipeline (runner.js's startRun — the function /api/run itself calls),
@@ -589,6 +623,10 @@ ${c.bold('Dashboard')}
   ${c.g('dashboard login')} ${c.dim('--url=<u> --token=<t>')}  connect this machine to an online dashboard ${c.dim('(logout · publish · unpublish)')}
   ${c.g('projects')} ${c.dim('[remove <id>]')}     list every project seen so far
 
+${c.bold('Second brain')} ${c.dim('— what spectoflow learns about you, shared by all your projects')}
+  ${c.g('brain')}                       what it holds, and which agents can reach it
+  ${c.g('brain setup')} ${c.dim('[--dry-run]')}   register the spectoflow MCP server in your installed agents
+
 ${c.bold('Customize')} ${c.dim('— same as Settings → Customize, from the terminal')}
   ${c.g('skill create')} ${c.dim('"<description>" | --auto')}      generate a project skill
   ${c.g('agent create')} ${c.dim('"<description>" | --auto')}      generate a project agent
@@ -662,6 +700,14 @@ const HELP = {
   agents: `${c.bold('spectoflow agents')}\n  List the stable team personas (name · capability · role).`,
   skills: `${c.bold('spectoflow skills')}\n  List the evolving procedures (name · capability · what it does).`,
   workflow: `${c.bold('spectoflow workflow')}\n  Show the pipeline steps, marking which are enabled (●) or disabled (○).`,
+  brain: `${c.bold('spectoflow brain')} ${c.dim('[setup [--dry-run]]')}\n
+  Your second brain — what spectoflow has learned about you (profile, preferences, working style,
+  things to avoid), in ${c.dim('~/.spectoflow/brain.md')}, shared by all your projects and editable in the
+  dashboard's ${c.bold('Second brain')} tab. Agents read and grow it through the ${c.g('spectoflow mcp')} server.
+    ${c.g('brain')}          show it: entries, entries to confirm, and which installed agents are wired
+    ${c.g('brain setup')}    register the MCP server in each installed agent's USER-level config (once
+                   per machine; never touches an existing entry; Goose gets a snippet to paste)
+  Learned facts are added directly by default: ${c.g('spectoflow config set brain.autoAdd false')} to confirm them first.`,
   stop: `${c.bold('spectoflow stop')}\n  Stop the running dashboard (alias for ${c.g('spectoflow dashboard stop')}).`,
   config: `${c.bold('spectoflow config')} ${c.dim('[get <key> | set <key> <value>]')}\n
   Global settings that apply to every project on this machine, stored in ${c.dim('~/.spectoflow/config.json')}:
@@ -677,6 +723,8 @@ const fns = {
   init, update, dashboard, stop: stopDashboard, status, list: listAll, help, version,
   projects: projectsCmd,
   config: configCmd,
+  mcp: () => require('../lib/mcp-server').serve({ version: VERSION }),
+  brain: brainCmd,
   agents: () => { console.log(wordmark()); printAgents(false); },
   skills: () => { console.log(wordmark()); printSkills(false); },
   workflow: () => { console.log(wordmark()); printWorkflow(false); },

package/lib/adapters.js

@@ -25,6 +25,11 @@ instructions (intent router, workflow, standing rules).
 reflect it back and ask **one targeted question at a time** (each with a recommendation) until the need
 is clear — then execute. See the Clarify reflex in \`.spectoflow/SPECTOFLOW.md\`.
 
+**Second brain.** Durable facts about the user come from the \`spectoflow\` MCP server — apply them. When you
+learn one (a stated preference, a correction of how you work, their role), record it with \`brain_learn\`, or print
+\`::spectoflow learn category=<profile|preferences|workflow|avoid> msg=<fact>\` if that tool is unavailable. Never
+secrets or sensitive data.
+
 - Command: \`/spectoflow\` (\`init\` / \`status\` / or just a request).
 - Dashboard: \`spectoflow dashboard\` → http://localhost:4319
 - Artifacts are markdown in \`specs/\` and \`plans/\`; volatile state in \`.spectoflow/runtime.json\`.
@@ -38,6 +43,11 @@ instructions. Artifacts are markdown in \`specs/\` and \`plans/\`; the workflow
 **Be an expert analyst, not an order-taker.** When a request is ambiguous, **clarify before acting**:
 reflect it back and ask **one targeted question at a time** (each with a recommendation) until the need
 is clear — then execute. See the Clarify reflex in \`.spectoflow/SPECTOFLOW.md\`.
+
+**Second brain.** Durable facts about the user come from the \`spectoflow\` MCP server — apply them. When you
+learn one (a stated preference, a correction of how you work, their role), record it with \`brain_learn\`, or print
+\`::spectoflow learn category=<profile|preferences|workflow|avoid> msg=<fact>\` if that tool is unavailable. Never
+secrets or sensitive data.
 `;
 
 const GEMINI_MD = `# GEMINI.md — spectoflow
@@ -49,6 +59,11 @@ instructions (intent router, workflow, standing rules). Artifacts are markdown i
 **Be an expert analyst, not an order-taker.** When a request is ambiguous, **clarify before acting**:
 reflect it back and ask **one targeted question at a time** (each with a recommendation) until the need
 is clear — then execute. See the Clarify reflex in \`.spectoflow/SPECTOFLOW.md\`.
+
+**Second brain.** Durable facts about the user come from the \`spectoflow\` MCP server — apply them. When you
+learn one (a stated preference, a correction of how you work, their role), record it with \`brain_learn\`, or print
+\`::spectoflow learn category=<profile|preferences|workflow|avoid> msg=<fact>\` if that tool is unavailable. Never
+secrets or sensitive data.
 `;
 
 const SLASH_CMD = `---

package/lib/brain-setup.js

@@ -0,0 +1,165 @@
+'use strict';
+/*
+ * `spectoflow brain setup` — registers the `spectoflow mcp` server (lib/mcp-server.js) in the
+ * USER-LEVEL MCP config of every coding agent installed on this machine, once per machine. User level
+ * because the second brain is personal, and because project-level MCP config is unreliable or absent
+ * for several agents (trusted-projects-only in Codex, ignored by Antigravity, missing in Goose/Kimi).
+ *
+ * Paths and entry shapes come from each agent's own docs (research pass 2026-09-16, see
+ * docs/second-brain-design.md). Same rules as lib/mcp.js: an existing entry is never touched, a file
+ * that can't be parsed is never rewritten. Claude Code is the one agent wired through its own CLI —
+ * it rewrites ~/.claude.json constantly, so editing that file directly could lose the write.
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { REGISTRY } = require('./adapters');
+const detect = require('./detect');
+const { mergeMcpServer } = require('./mcp');
+
+const NAME = 'spectoflow';
+
+// `spectoflow mcp` when the `spectoflow` on PATH is this very install; otherwise node + this bin's
+// absolute path (running from a clone, or another version on PATH). Always node + path on Windows: there
+// `spectoflow` is an npm .cmd shim, which MCP hosts that spawn without a shell can't start.
+function serverCommand({ binPath, env = process.env, platform = process.platform } = {}) {
+  const found = findOnPath('spectoflow', env, platform);
+  let same = false;
+  if (found && platform !== 'win32') { try { same = fs.realpathSync(found) === fs.realpathSync(binPath); } catch { same = false; } }
+  const cmd = same ? { command: 'spectoflow', args: ['mcp'] } : { command: process.execPath, args: [binPath, 'mcp'] };
+  if (env.SPECTOFLOW_HOME) cmd.env = { SPECTOFLOW_HOME: env.SPECTOFLOW_HOME };
+  return cmd;
+}
+function findOnPath(bin, env, platform) {
+  const exts = platform === 'win32' ? ['', ...(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)] : [''];
+  for (const d of (env.PATH || env.Path || '').split(path.delimiter).filter(Boolean)) {
+    for (const e of exts) { const fp = path.join(d, bin + e); if (fs.existsSync(fp)) return fp; }
+  }
+  return null;
+}
+
+const home = () => os.homedir();
+const appData = () => process.env.APPDATA || path.join(home(), 'AppData', 'Roaming');
+
+// id → how to wire it. `file` is resolved lazily (tests point HOME elsewhere).
+const TARGETS = {
+  claude: { kind: 'claude-cli', file: () => path.join(process.env.CLAUDE_CONFIG_DIR || home(), '.claude.json') },
+  codex: { kind: 'toml', file: () => path.join(process.env.CODEX_HOME || path.join(home(), '.codex'), 'config.toml') },
+  cursor: { kind: 'json', file: () => path.join(home(), '.cursor', 'mcp.json') },
+  gemini: { kind: 'json', file: () => path.join(home(), '.gemini', 'settings.json') },
+  opencode: { kind: 'opencode', file: () => path.join(home(), '.config', 'opencode', 'opencode.json') },
+  kiro: { kind: 'json', file: () => path.join(home(), '.kiro', 'settings', 'mcp.json') },
+  antigravity: { kind: 'json', file: () => path.join(home(), '.gemini', 'config', 'mcp_config.json') },
+  copilot: { kind: 'json', extra: { type: 'local', tools: ['*'] }, file: () => path.join(process.env.COPILOT_HOME || path.join(home(), '.copilot'), 'mcp-config.json') },
+  'amazon-q': { kind: 'json', file: () => path.join(home(), '.aws', 'amazonq', 'mcp.json') },
+  droid: { kind: 'json', file: () => path.join(home(), '.factory', 'mcp.json') },
+  auggie: { kind: 'json', file: () => path.join(home(), '.augment', 'settings.json') },
+  goose: { kind: 'yaml-snippet', file: () => (process.platform === 'win32' ? path.join(appData(), 'Block', 'goose', 'config', 'config.yaml') : path.join(home(), '.config', 'goose', 'config.yaml')) },
+  kimi: { kind: 'json', file: () => path.join(home(), '.kimi', 'mcp.json') },
+};
+
+const tomlString = (s) => JSON.stringify(String(s));
+function tomlBlock(cmd) {
+  const lines = [`[mcp_servers.${NAME}]`, `command = ${tomlString(cmd.command)}`, `args = [${cmd.args.map(tomlString).join(', ')}]`];
+  if (cmd.env) lines.push(`env = { ${Object.entries(cmd.env).map(([k, v]) => `${k} = ${tomlString(v)}`).join(', ')} }`);
+  return lines.join('\n') + '\n';
+}
+function yamlBlock(cmd) {
+  const q = (s) => JSON.stringify(String(s));
+  const lines = ['extensions:', `  ${NAME}:`, '    type: stdio', `    name: ${NAME}`, '    enabled: true', `    cmd: ${q(cmd.command)}`, `    args: [${cmd.args.map(q).join(', ')}]`, '    timeout: 300'];
+  if (cmd.env) lines.push(`    envs: { ${Object.entries(cmd.env).map(([k, v]) => `${k}: ${q(v)}`).join(', ')} }`);
+  return lines.join('\n') + '\n';
+}
+const readText = (fp) => { try { return fs.readFileSync(fp, 'utf8'); } catch { return null; } };
+
+// Is a `spectoflow` MCP server declared in this Codex TOML, in any of the forms TOML allows:
+// [mcp_servers.spectoflow] (bare or quoted key, trailing comment), a dotted key, or a key inside [mcp_servers].
+function tomlHasServer(text) {
+  const key = `(["']?)${NAME}\\1`;
+  if (new RegExp(`^\\s*\\[\\s*mcp_servers\\s*\\.\\s*${key}\\s*(\\.[^\\]]*)?\\]\\s*(#.*)?$`, 'm').test(text)) return true;
+  if (new RegExp(`^\\s*mcp_servers\\s*\\.\\s*${key}\\s*[.=]`, 'm').test(text)) return true;
+  let inTable = false;
+  for (const line of text.split(/\r?\n/)) {
+    const h = line.match(/^\s*\[\s*([^\]]+?)\s*\]/);
+    if (h) { inTable = h[1].replace(/\s+/g, '') === 'mcp_servers'; continue; }
+    if (inTable && new RegExp(`^\\s*${key}\\s*[.=]`).test(line)) return true;
+  }
+  return false;
+}
+
+// Is the spectoflow server already registered for this agent? (true/false; null = can't tell)
+function isWired(id) {
+  const t = TARGETS[id]; if (!t) return null;
+  const fp = t.file(), text = readText(fp);
+  if (text === null) return false;
+  if (t.kind === 'toml') return tomlHasServer(text);
+  if (t.kind === 'yaml-snippet') return /^extensions:\s*$/m.test(text) && new RegExp(`^ {2}${NAME}:\\s*$`, 'm').test(text);
+  try {
+    const doc = JSON.parse(text);
+    const map = t.kind === 'opencode' ? doc.mcp : doc.mcpServers;
+    return !!(map && typeof map === 'object' && Object.prototype.hasOwnProperty.call(map, NAME));
+  } catch { return null; }
+}
+
+function wireOne(id, cmd, { dryRun, run }) {
+  const t = TARGETS[id], fp = t.file();
+  if (t.kind === 'claude-cli') {
+    if (isWired(id)) return { status: 'exists', file: fp };
+    // Name before --env: --env takes several values and would swallow the name otherwise.
+    const args = ['mcp', 'add', '--scope', 'user', NAME, ...Object.entries(cmd.env || {}).flatMap(([k, v]) => ['--env', `${k}=${v}`]), '--', cmd.command, ...cmd.args];
+    if (dryRun) return { status: 'added', file: fp, via: `claude ${args.join(' ')}` };
+    const r = run('claude', args);
+    const out = `${r.stderr || ''}${r.stdout || ''}`.trim();
+    if (r.status === 0) return { status: 'added', file: fp, via: 'claude mcp add' };
+    if (/already exists/i.test(out)) return { status: 'exists', file: fp };
+    return { status: 'failed', file: fp, detail: out || (r.error && r.error.message) || 'failed', manual: `claude ${args.join(' ')}` };
+  }
+  if (t.kind === 'json') return { status: mergeMcpServer(fp, NAME, { ...(t.extra || {}), command: cmd.command, args: cmd.args, ...(cmd.env ? { env: cmd.env } : {}) }, { dryRun }), file: fp };
+  if (t.kind === 'opencode') return { status: mergeMcpServer(fp, NAME, { type: 'local', command: [cmd.command, ...cmd.args], enabled: true, ...(cmd.env ? { environment: cmd.env } : {}) }, { key: 'mcp', dryRun }), file: fp };
+  if (t.kind === 'toml') {
+    const text = readText(fp);
+    if (text !== null && isWired(id)) return { status: 'exists', file: fp };
+    // Any other mention of spectoflow is a form we can't classify: appending could declare the table twice,
+    // and a duplicate key makes Codex refuse its whole config. Hand the user the block instead.
+    if (text !== null && text.includes(NAME)) return { status: 'manual', file: fp, manual: tomlBlock(cmd) };
+    // `mcp_servers = { … }` (an inline table) can't be extended by a [mcp_servers.x] header either.
+    if (text !== null && /^\s*mcp_servers\s*=/m.test(text)) return { status: 'manual', file: fp, manual: tomlBlock(cmd) };
+    if (!dryRun) {
+      fs.mkdirSync(path.dirname(fp), { recursive: true });
+      fs.writeFileSync(fp, text === null ? tomlBlock(cmd) : text.replace(/\s*$/, '') + '\n\n' + tomlBlock(cmd));
+    }
+    return { status: text === null ? 'created' : 'added', file: fp };
+  }
+  // Goose: YAML can't be edited safely without a parser — hand the user the exact block instead.
+  if (isWired(id)) return { status: 'exists', file: fp };
+  return { status: 'manual', file: fp, manual: yamlBlock(cmd) };
+}
+
+// No shell on POSIX. On Windows `claude` is a .cmd shim, which needs cmd.exe — with every argument quoted,
+// or a path like C:\\Program Files\\nodejs\\node.exe would be split.
+function defaultRun(bin, args) {
+  if (process.platform !== 'win32') return spawnSync(bin, args, { encoding: 'utf8', windowsHide: true });
+  const q = (a) => `"${String(a).replace(/"/g, '""')}"`;
+  return spawnSync('cmd.exe', ['/d', '/s', '/c', `"${[bin, ...args].map(q).join(' ')}"`], { encoding: 'utf8', windowsHide: true, windowsVerbatimArguments: true });
+}
+
+// → [{ id, label, status: created|added|exists|skipped|manual|failed, file, manual?, detail? }]
+// for every agent installed on this machine. `agents` overrides detection (tests, explicit choice).
+function setup({ binPath, dryRun = false, agents, run = defaultRun, env = process.env } = {}) {
+  const cmd = serverCommand({ binPath, env });
+  const ids = agents || REGISTRY.filter((a) => TARGETS[a.id] && detect.binOnPath(a.detect.bin, { env })).map((a) => a.id);
+  return ids.filter((id) => TARGETS[id]).map((id) => {
+    const label = (REGISTRY.find((a) => a.id === id) || {}).label || id;
+    try { return { id, label, ...wireOne(id, cmd, { dryRun, run }) }; }
+    catch (e) { return { id, label, status: 'failed', file: TARGETS[id].file(), detail: e.message }; }
+  });
+}
+
+// For the dashboard page: each installed agent and whether the server is registered for it.
+function status({ env = process.env } = {}) {
+  return REGISTRY.filter((a) => TARGETS[a.id] && detect.binOnPath(a.detect.bin, { env }))
+    .map((a) => ({ id: a.id, label: a.label, wired: isWired(a.id) === true }));
+}
+
+module.exports = { setup, status, isWired, serverCommand, TARGETS, NAME };

package/lib/brain.js

@@ -0,0 +1,257 @@
+'use strict';
+/*
+ * The second brain — what spectoflow has learned about the user, shared by all their projects.
+ * One markdown file, ~/.spectoflow/brain.md (never inside a project, never copied), read and written
+ * by the dashboard page, the `spectoflow mcp` server and the `::spectoflow learn` run line. Zero
+ * dependency.
+ *
+ *   # Second brain
+ *   ## Profile
+ *   - Scrum master and full-stack developer <!-- id:b7k2 by:agent at:2026-09-16 -->
+ *   ## To confirm
+ *   - [preferences] Prefers pnpm over npm <!-- id:b7k6 by:agent at:2026-09-16 -->
+ *
+ * The file is the user's too: every line spectoflow doesn't change is written back byte for byte —
+ * titles, blank lines, comments, code blocks, unknown sections and their order, hand-written entries.
+ * Writers in different processes (hub, MCP servers, runs) take a lock file, then write-then-rename.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const globalConfig = require('./global-config');
+
+const CATEGORIES = ['profile', 'preferences', 'workflow', 'avoid'];
+const HEADINGS = { profile: 'Profile', preferences: 'Preferences', workflow: 'Working style', avoid: 'Avoid' };
+const PENDING = 'To confirm';
+const MAX_TEXT = 500;
+const FALLBACK_CATEGORY = 'preferences';
+
+function brainPath() { return path.join(globalConfig.homeDir(), 'brain.md'); }
+
+const normCategory = (c) => (CATEGORIES.includes(String(c || '').trim().toLowerCase()) ? String(c).trim().toLowerCase() : FALLBACK_CATEGORY);
+// One line, no HTML-comment delimiters (they would break the metadata), capped.
+function cleanText(t) {
+  return String(t == null ? '' : t).replace(/<!--|-->/g, '').replace(/\s+/g, ' ').trim().slice(0, MAX_TEXT);
+}
+const newId = () => 'b' + Date.now().toString(36) + crypto.randomBytes(3).toString('hex');
+// A hand-written line has no id: derive a stable one. `n` tells identical lines of a category apart.
+const derivedId = (category, text, n) => 'h' + crypto.createHash('sha1').update(`${category}\n${text}\n${n}`).digest('hex').slice(0, 10);
+const today = () => new Date().toISOString().slice(0, 10);
+const isBlank = (it) => it.raw !== undefined && !it.raw.trim();
+
+function headingKind(title) {
+  const t = title.trim().toLowerCase();
+  if (t === PENDING.toLowerCase()) return { kind: 'pending' };
+  const cat = CATEGORIES.find((c) => c === t || HEADINGS[c].toLowerCase() === t);
+  return cat ? { kind: 'category', id: cat } : { kind: 'unknown' };
+}
+
+const ENTRY_RE = /^-\s+(?:\[([\w-]+)\]\s+)?(.*?)\s*(?:<!--\s*(.*?)\s*-->)?\s*$/;
+function parseMeta(s) {
+  const out = {};
+  for (const m of String(s || '').matchAll(/(\w+):(\S+)/g)) out[m[1]] = m[2];
+  return out;
+}
+
+// → { title, blocks: [{ kind: preamble|category|pending|unknown, id?, heading?, items: [...] }] }
+// item = { raw } (a line kept verbatim) or an entry { id, category, text, by, at, status, line }.
+function parse(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
+  const model = { title: null, eol: /\r\n/.test(String(text || '')) ? '\r\n' : '\n', blocks: [{ kind: 'preamble', items: [] }] };
+  let block = model.blocks[0], inFence = false;
+  const seen = new Map();
+  for (const line of lines) {
+    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; block.items.push({ raw: line }); continue; }
+    if (inFence) { block.items.push({ raw: line }); continue; }
+    if (model.title === null && model.blocks.length === 1 && block.items.every(isBlank) && /^#\s+/.test(line)) { model.title = line; continue; }
+    const h = line.match(/^##\s+(.*)$/);
+    if (h) {
+      block = { ...headingKind(h[1]), heading: line, items: [] };
+      model.blocks.push(block);
+      continue;
+    }
+    const m = (block.kind === 'category' || block.kind === 'pending') && line.match(ENTRY_RE);
+    const meta = m ? parseMeta(m[3]) : null;
+    // A trailing comment is never part of the fact (a user's own comment stays hidden: the line itself is
+    // written back verbatim while the entry is untouched; editing the entry replaces the line).
+    const body = m ? m[2] : '';
+    if (m && cleanText(body)) {
+      const pending = block.kind === 'pending';
+      const category = pending ? normCategory(m[1]) : block.id;
+      const entryText = cleanText(pending || !m[1] ? body : `[${m[1]}] ${body}`);
+      let id = meta.id;
+      if (!id) { const k = `${category}\n${entryText}`; const n = seen.get(k) || 0; seen.set(k, n + 1); id = derivedId(category, entryText, n); }
+      block.items.push({ id, category, text: entryText, by: meta.by || 'user', at: meta.at || null, status: pending ? 'pending' : 'confirmed', line });
+    } else {
+      block.items.push({ raw: line });
+    }
+  }
+  return model;
+}
+
+function entryLine(e) {
+  const meta = `id:${e.id} by:${e.by}${e.at ? ' at:' + e.at : ''}`;
+  return `- ${e.status === 'pending' ? `[${e.category}] ` : ''}${e.text} <!-- ${meta} -->`;
+}
+function serialize(model) {
+  const out = [model.title || '# Second brain'];
+  for (const b of model.blocks) {
+    if (b.kind === 'pending' && !b.items.some((it) => it.raw === undefined) && b.items.every(isBlank)) continue;
+    if (b.kind !== 'preamble') {
+      if (out[out.length - 1].trim()) out.push(''); // a section always follows a blank line
+      out.push(b.heading || `## ${b.kind === 'pending' ? PENDING : HEADINGS[b.id]}`);
+    }
+    for (const it of b.items) out.push(it.raw !== undefined ? it.raw : (it.line && !it.dirty ? it.line : entryLine(it)));
+  }
+  while (out.length > 1 && !out[out.length - 1].trim()) out.pop();
+  const eol = model.eol || '\n';
+  return out.join(eol) + eol;
+}
+
+function emptyModel() {
+  return { title: null, blocks: [{ kind: 'preamble', items: [] }, ...CATEGORIES.map((id) => ({ kind: 'category', id, heading: null, items: [] }))] };
+}
+function load(file = brainPath()) {
+  let text = '';
+  try { text = fs.readFileSync(file, 'utf8'); } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  return text.trim() ? parse(text) : emptyModel();
+}
+function save(model, file = brainPath()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  fs.writeFileSync(tmp, serialize(model));
+  fs.renameSync(tmp, file);
+}
+
+// Cross-process lock: the hub, any number of `spectoflow mcp` processes and runs may write in the
+// same instant. A lock older than 10s is a crashed writer's and is taken over.
+const sleepSync = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+function withLock(file, fn) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const lock = `${file}.lock`, deadline = Date.now() + 3000;
+  for (;;) {
+    try { fs.writeFileSync(lock, String(process.pid), { flag: 'wx' }); break; }
+    catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      try { if (Date.now() - fs.statSync(lock).mtimeMs > 10000) { fs.unlinkSync(lock); continue; } } catch (_) {}
+      if (Date.now() > deadline) throw Object.assign(new Error('The second brain is busy, try again.'), { status: 503 });
+      sleepSync(15);
+    }
+  }
+  try { return fn(); } finally { try { fs.unlinkSync(lock); } catch (_) {} }
+}
+// Read, change, save — under the lock. `fn` returns { result, changed }.
+function mutate(file, fn) {
+  return withLock(file, () => {
+    const model = load(file);
+    const { result, changed } = fn(model);
+    if (changed) save(model, file);
+    return result;
+  });
+}
+
+const entriesOf = (model) => model.blocks.flatMap((b) => b.items.filter((it) => it.raw === undefined));
+function find(model, id) {
+  for (const b of model.blocks) {
+    const i = b.items.findIndex((it) => it.raw === undefined && it.id === id);
+    if (i >= 0) return { block: b, i, entry: b.items[i] };
+  }
+  return null;
+}
+// Append before the block's trailing blank lines, so the spacing before the next heading stays.
+function append(block, entry) {
+  let i = block.items.length;
+  while (i > 0 && isBlank(block.items[i - 1])) i--;
+  block.items.splice(i, 0, entry);
+}
+function blockFor(model, status, category) {
+  const want = status === 'pending' ? (b) => b.kind === 'pending' : (b) => b.kind === 'category' && b.id === category;
+  let b = model.blocks.find(want);
+  if (!b) {
+    b = status === 'pending' ? { kind: 'pending', heading: null, items: [] } : { kind: 'category', id: category, heading: null, items: [] };
+    const at = status === 'pending' ? -1 : model.blocks.findIndex((x) => x.kind === 'pending');
+    if (at < 0) model.blocks.push(b); else model.blocks.splice(at, 0, b);
+  }
+  return b;
+}
+const notFound = () => Object.assign(new Error('Entry not found.'), { status: 404 });
+const emptyText = () => Object.assign(new Error('Text is required.'), { status: 400 });
+
+// { entries (confirmed, in category order), pending, autoAdd }
+function read(file = brainPath()) {
+  const all = entriesOf(load(file));
+  return {
+    entries: CATEGORIES.flatMap((c) => all.filter((e) => e.status === 'confirmed' && e.category === c)),
+    pending: all.filter((e) => e.status === 'pending'),
+    autoAdd: autoAdd(),
+  };
+}
+
+// Adds one fact. status 'confirmed' or 'pending'. A case-insensitive duplicate of any entry is not
+// added again: → { duplicate: true, entry: <the existing one> }.
+function add({ category, text, by = 'user', status = 'confirmed' }, file = brainPath()) {
+  const t = cleanText(text);
+  if (!t) throw emptyText();
+  return mutate(file, (model) => {
+    const existing = entriesOf(model).find((e) => e.text.toLowerCase() === t.toLowerCase());
+    if (existing) return { result: { duplicate: true, entry: existing }, changed: false };
+    const entry = { id: newId(), category: normCategory(category), text: t, by, at: today(), status: status === 'pending' ? 'pending' : 'confirmed' };
+    append(blockFor(model, entry.status, entry.category), entry);
+    return { result: { duplicate: false, entry }, changed: true };
+  });
+}
+
+// What the agent learned through MCP: confirmed right away, or "to confirm", per brain.autoAdd.
+function learn({ category, text }, file = brainPath()) {
+  return add({ category, text, by: 'agent', status: autoAdd() ? 'confirmed' : 'pending' }, file);
+}
+
+function update(id, { text, category } = {}, file = brainPath()) {
+  const t = text === undefined ? undefined : cleanText(text);
+  if (text !== undefined && !t) throw emptyText();
+  return mutate(file, (model) => {
+    const hit = find(model, id); if (!hit) throw notFound();
+    const e = hit.entry;
+    if (t !== undefined) e.text = t;
+    if (category !== undefined) {
+      const c = normCategory(category);
+      if (c !== e.category && e.status === 'confirmed') { hit.block.items.splice(hit.i, 1); append(blockFor(model, 'confirmed', c), e); }
+      e.category = c;
+    }
+    e.dirty = true;
+    return { result: e, changed: true };
+  });
+}
+
+function remove(id, file = brainPath()) {
+  return mutate(file, (model) => {
+    const hit = find(model, id); if (!hit) throw notFound();
+    hit.block.items.splice(hit.i, 1);
+    return { result: { ok: true }, changed: true };
+  });
+}
+
+function confirm(id, file = brainPath()) {
+  return mutate(file, (model) => {
+    const hit = find(model, id); if (!hit) throw notFound();
+    if (hit.entry.status !== 'pending') return { result: hit.entry, changed: false };
+    hit.block.items.splice(hit.i, 1);
+    hit.entry.status = 'confirmed'; hit.entry.dirty = true;
+    append(blockFor(model, 'confirmed', hit.entry.category), hit.entry);
+    return { result: hit.entry, changed: true };
+  });
+}
+
+// Confirmed entries as markdown, grouped by category — what an agent is given.
+function renderForAgent(file = brainPath()) {
+  const { entries } = read(file);
+  return CATEGORIES.map((c) => {
+    const items = entries.filter((e) => e.category === c);
+    return items.length ? `## ${HEADINGS[c]}\n${items.map((e) => `- ${e.text}`).join('\n')}` : '';
+  }).filter(Boolean).join('\n\n');
+}
+
+function autoAdd() { return globalConfig.get('brain.autoAdd').value !== false; }
+
+module.exports = { CATEGORIES, HEADINGS, MAX_TEXT, brainPath, parse, serialize, read, add, learn, update, remove, confirm, renderForAgent, autoAdd };