spectoflow 0.27.2 → 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
 
@@ -118,18 +121,20 @@ detected it falls back to claude + codex.
 **Empty project** → your agent asks what to build and runs Intake (brainstorm → analysis → spec → plan).
 **Existing project** → an existing `CLAUDE.md` is preserved as `CLAUDE.md.tomerge` (merged on first run);
 an existing `AGENTS.md` or `GEMINI.md` is kept as-is and gets a short, delimited spectoflow section
-appended (`<!-- spectoflow:start -->` … `<!-- spectoflow:end -->`) pointing to `.spectoflow/AGENTS.md` —
+appended (`<!-- spectoflow:start -->` … `<!-- spectoflow:end -->`) pointing to `.spectoflow/SPECTOFLOW.md` —
 `spectoflow update` adds it too to a project installed before that; existing `plans/*.md` tasks are given
 stable ids.
 
-**Two `AGENTS.md`, on purpose.** The one at your project root is a thin pointer, in the place each agent
-reads natively. The real brain (intent router, workflow, rules) is `.spectoflow/AGENTS.md`, owned by the
-framework and refreshed by `spectoflow update`.
+**Entry files vs. the brain.** `CLAUDE.md`, `AGENTS.md` and `GEMINI.md` at your project root are thin
+pointers, in the place each agent reads natively. The real brain (intent router, workflow, rules) is
+`.spectoflow/SPECTOFLOW.md`, owned by the framework and refreshed by `spectoflow update`. (Before 0.28 it
+was named `.spectoflow/AGENTS.md`, easy to confuse with the root one — `update` renames it, keeping any
+edits you made, and rewrites the old path in your entry files.)
 
 ## Update
 
 `init` is idempotent (it never overwrites), so it can't refresh an installed project. `spectoflow
-update` refreshes **framework-owned** files (engine, `AGENTS.md`, `capabilities.md`, `policy.md`,
+update` refreshes **framework-owned** files (engine, `SPECTOFLOW.md`, `capabilities.md`, `policy.md`,
 default agents & skills) to the CLI's version — retiring the project's own vendored dashboard folder
 along the way for anyone updating from before v0.24 — while **preserving your work** —
 `config.json`, `workflow.md`, `specs/`, `plans/`, and any agent/skill you created or edited are never
@@ -254,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):
 
@@ -277,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).
 
@@ -341,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…).
@@ -353,7 +404,7 @@ INVEST, Playwright E2E, Conventional Commits, and more — not generic one-liner
 ### Clarify before acting
 
 spectoflow is an **expert analyst, not an order-taker**. When a request is vague ("login displays
-badly, users can't sign in"), an always-on **Clarify reflex** — in the agent's memory (`AGENTS.md`)
+badly, users can't sign in"), an always-on **Clarify reflex** — in the agent's memory (`SPECTOFLOW.md`)
 and backed by the `clarify` skill — reflects it back and asks **one targeted question at a time**,
 each with a recommendation anchored in the project's goals and best practices, until the need is
 crisp; then it runs the normal workflow. It's additive: it feeds the router, never replaces it, and

package/bin/spectoflow.js

@@ -133,7 +133,7 @@ async function update() {
   const r = require('../lib/update').runUpdate({ projectRoot: root, templatesDir: TPL, version: VERSION, dryRun, force });
 
   const from = r.fromVersion || 'unknown';
-  const changed = r.refreshed.length + r.created.length + r.adopted.length + r.newSidecar.length + r.forced.length + r.removed.length + r.migration.movedViews.length + r.pointers.length;
+  const changed = r.refreshed.length + r.created.length + r.adopted.length + r.newSidecar.length + r.forced.length + r.removed.length + r.migration.movedViews.length + r.pointers.appended.length + r.pointers.repointed.length + r.migration.repointedUserFiles.length + (r.migration.renamedBrain ? 1 : 0);
   const row = (sym, label, list, painter, note) => {
     if (!list.length) return;
     const n = c.dim(String(list.length).padStart(2));
@@ -150,7 +150,9 @@ async function update() {
   row(c.y('!'), '.new', r.newSidecar, c.y, 'you edited these — new version saved as *.new, merge by hand (or re-run with --force)');
   row(c.dim('−'), 'removed', r.removed, c.dim, 'no longer part of the kit (the dashboard lives in the spectoflow package now)');
   row(c.y('!'), 'kept', r.kept, c.y, 'you modified these and they are no longer part of the kit — delete them yourself when ready');
-  row(c.cy('+'), 'linked', r.pointers, c.cy, `${r.pointers.join(', ')} existed without a pointer — a spectoflow section was appended`);
+  if (r.migration.renamedBrain) console.log(`  ${c.cy('→')}  ${c.cy('renamed'.padEnd(9))} ${c.dim(' 1')}   ${c.dim('.spectoflow/AGENTS.md → .spectoflow/SPECTOFLOW.md (the brain; your edits, if any, came along)')}`);
+  row(c.cy('→'), 'repointed', [...r.pointers.repointed, ...r.migration.repointedUserFiles.map((f) => '.spectoflow/' + f)], c.cy, null);
+  row(c.cy('+'), 'linked', r.pointers.appended, c.cy, `${r.pointers.appended.join(', ')} existed without a pointer — a spectoflow section was appended`);
   if (r.migration.movedViews.length) console.log(`  ${c.cy('→')}  ${c.cy('views'.padEnd(9))} ${c.dim(String(r.migration.movedViews.length).padStart(2))}   ${c.dim('custom views moved to .spectoflow/dashboards/')}`);
   r.migration.conflicts.forEach((f) => console.log(`  ${c.y('!')}  ${c.y('conflict'.padEnd(9))}      ${c.dim(`dashboards/${f} already exists — the old copy stays in dashboard/custom/ for you to merge`)}`));
   if (r.legacyLeftovers.length) console.log(`  ${c.y('!')}  ${c.dim('this project has no install manifest, so nothing was deleted. Safe to remove by hand: ' + r.legacyLeftovers.map((p) => '.spectoflow/' + p).join(', '))}`);
@@ -372,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),
@@ -587,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
@@ -616,7 +656,7 @@ const HELP = {
   ${c.dim('an existing AGENTS.md/GEMINI.md is kept and gets a spectoflow pointer section appended.')}
   ${c.dim('Full list with docs links: the dashboard\'s Documentation tab, or the README.')}`,
   update: `${c.bold('spectoflow update')} ${c.dim('[--dry-run] [--force|-f]')}\n
-  Refresh framework-owned files (engine, default agents & skills, AGENTS.md, policy…)
+  Refresh framework-owned files (engine, default agents & skills, SPECTOFLOW.md, policy…)
   to this CLI's version, ${c.bold('preserving your work')}: config.json, workflow.md, specs/, plans/
   and any agent/skill you edited are never overwritten (an edited file's new version lands as
   ${c.dim('*.new')} for you to merge). ${c.g('--dry-run')} previews without writing.
@@ -660,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')}:
@@ -675,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

@@ -1,6 +1,6 @@
 'use strict';
 /*
- * Per-agent adapters. The canonical brain is .spectoflow/AGENTS.md. Each agent needs a thin entry
+ * Per-agent adapters. The canonical brain is .spectoflow/SPECTOFLOW.md. Each agent needs a thin entry
  * file in the place IT reads, pointing back to the canonical brain — so the framework stays in
  * .spectoflow/ (swappable, no pollution) while every agent still finds its native entry point.
  * (Same pattern OpenSpec uses to support claude/codex/cursor/gemini/…)
@@ -14,7 +14,7 @@ const path = require('path');
 
 const CLAUDE_MD = `# CLAUDE.md — spectoflow
 
-This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+This project uses **spectoflow**. **Read \`.spectoflow/SPECTOFLOW.md\` and follow it** as your operating
 instructions (intent router, workflow, standing rules).
 
 > If \`CLAUDE.md.tomerge\` exists next to this file, it is your previous CLAUDE.md, preserved on
@@ -23,7 +23,12 @@ instructions (intent router, workflow, standing rules).
 
 **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/AGENTS.md\`.
+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
@@ -32,30 +37,40 @@ is clear — then execute. See the Clarify reflex in \`.spectoflow/AGENTS.md\`.
 
 const ROOT_AGENTS_MD = `# AGENTS.md — spectoflow
 
-This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+This project uses **spectoflow**. **Read \`.spectoflow/SPECTOFLOW.md\` and follow it** as your operating
 instructions. Artifacts are markdown in \`specs/\` and \`plans/\`; the workflow is \`.spectoflow/workflow.md\`.
 
 **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/AGENTS.md\`.
+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
 
-This project uses **spectoflow**. **Read \`.spectoflow/AGENTS.md\` and follow it** as your operating
+This project uses **spectoflow**. **Read \`.spectoflow/SPECTOFLOW.md\` and follow it** as your operating
 instructions (intent router, workflow, standing rules). Artifacts are markdown in \`specs/\` and
 \`plans/\`; the workflow is \`.spectoflow/workflow.md\`.
 
 **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/AGENTS.md\`.
+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 = `---
 description: spectoflow — spec-driven control (init / status / or just a request)
 ---
 
-Read \`.spectoflow/AGENTS.md\` and \`.spectoflow/config.json\` first.
+Read \`.spectoflow/SPECTOFLOW.md\` and \`.spectoflow/config.json\` first.
 
 Argument: \`$ARGUMENTS\`
 
@@ -63,7 +78,7 @@ Argument: \`$ARGUMENTS\`
   \`specs/\` and \`plans/\` are empty, greet me, state the mode, and start Intake (brainstorm → analysis
   → spec → plan) by asking what I want to build.
 - \`status\`: summarize progress from \`plans/*.md\` and \`.spectoflow/runtime.json\`.
-- otherwise: treat \`$ARGUMENTS\` as a request and run the Router in \`.spectoflow/AGENTS.md\`.
+- otherwise: treat \`$ARGUMENTS\` as a request and run the Router in \`.spectoflow/SPECTOFLOW.md\`.
 `;
 
 // Priority order = which agent becomes the default when several are detected.
@@ -232,43 +247,60 @@ const POINTER_START = '<!-- spectoflow:start -->';
 const POINTER_END = '<!-- spectoflow:end -->';
 const POINTER_BLOCK = `${POINTER_START}\n${ROOT_AGENTS_MD.replace(/^# .*\n/, '## spectoflow\n').trimEnd()}\n${POINTER_END}\n`;
 
-const hasPointer = (text) => text.includes('.spectoflow/AGENTS.md');
+// The brain was `.spectoflow/AGENTS.md` before 0.28 — renamed so it can't be mistaken for the
+// project-root AGENTS.md. Pointers written back then are rewritten in place, never duplicated.
+const BRAIN = '.spectoflow/SPECTOFLOW.md';
+const LEGACY_BRAIN = '.spectoflow/AGENTS.md';
+const ENTRY_FILES = [...MEMORY_FILES, '.claude/commands/spectoflow.md'];
 
-function appendPointer(fp, dryRun) {
-  const text = fs.readFileSync(fp, 'utf8');
-  if (hasPointer(text)) return false;
-  if (!dryRun) fs.writeFileSync(fp, text.replace(/\s*$/, '') + '\n\n' + POINTER_BLOCK);
-  return true;
+// Bring one existing entry file up to date: rewrite a legacy pointer, then (memory files only)
+// append the pointer section if it still has none. Returns what it did (or would do, on dryRun).
+function linkEntry(fp, rel, dryRun) {
+  const before = fs.readFileSync(fp, 'utf8');
+  let text = before.split(LEGACY_BRAIN).join(BRAIN);
+  const repointed = text !== before;
+  const appended = MEMORY_FILES.includes(rel) && !text.includes(BRAIN);
+  if (appended) text = text.replace(/\s*$/, '') + '\n\n' + POINTER_BLOCK;
+  if ((repointed || appended) && !dryRun) fs.writeFileSync(fp, text);
+  return { repointed, appended };
 }
 
 // Write the native entry-file shims for each selected agent. Shared files (AGENTS.md across
-// codex/cursor) are handled once. A memory file that already exists gets the pointer appended.
+// codex/cursor) are handled once. An entry file that already exists is linked instead (linkEntry).
 function generate(projectRoot, agents) {
   const list = (agents && agents.length ? agents : ['claude', 'codex']).map(byId).filter(Boolean);
-  const written = [], appended = [];
+  const written = [], appended = [], repointed = [], seen = new Set();
   for (const a of list) {
     for (const e of a.entries) {
-      if (written.includes(e.path) || appended.includes(e.path)) continue;
+      if (seen.has(e.path)) continue;
+      seen.add(e.path);
       const fp = path.join(projectRoot, e.path);
       if (!fs.existsSync(fp)) {
         fs.mkdirSync(path.dirname(fp), { recursive: true });
         fs.writeFileSync(fp, e.content);
         written.push(e.path);
-      } else if (MEMORY_FILES.includes(e.path) && appendPointer(fp)) {
-        appended.push(e.path);
+        continue;
       }
+      const r = linkEntry(fp, e.path, false);
+      if (r.appended) appended.push(e.path);
+      if (r.repointed) repointed.push(e.path);
     }
   }
-  return { written, appended };
+  return { written, appended, repointed };
 }
 
-// For `update`: an already-installed project whose existing memory files never got the pointer.
-// Only repairs files that exist — never creates one for an agent the project may not use.
+// For `update`: link every entry file that exists — never creates one for an agent the project may
+// not use.
 function ensurePointers(projectRoot, dryRun = false) {
-  return MEMORY_FILES.filter((rel) => {
+  const out = { appended: [], repointed: [] };
+  for (const rel of ENTRY_FILES) {
     const fp = path.join(projectRoot, rel);
-    return fs.existsSync(fp) && appendPointer(fp, dryRun);
-  });
+    if (!fs.existsSync(fp)) continue;
+    const r = linkEntry(fp, rel, dryRun);
+    if (r.appended) out.appended.push(rel);
+    if (r.repointed) out.repointed.push(rel);
+  }
+  return out;
 }
 
 // { id: runner } defaults for the given agents — used to seed config.runners at init.
@@ -287,4 +319,4 @@ function knownAgents() {
   return REGISTRY.map((a) => ({ id: a.id, label: a.label, bin: a.detect.bin, dirs: a.detect.dirs || [], runner: a.runner, headless: a.headless, docsUrl: a.docsUrl }));
 }
 
-module.exports = { generate, ensurePointers, defaultRunners, REGISTRY, knownAgents };
+module.exports = { generate, ensurePointers, defaultRunners, REGISTRY, knownAgents, BRAIN, LEGACY_BRAIN };

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 };