klypix-mcp 1.70.0 → 1.71.0

package/README.md

@@ -85,28 +85,55 @@ It verifies 15 required coordination behaviours — not the 26 tools, and not th
 
 ## Quick start
 
-**Claude Code + Codex:**
+Run this **inside your project**:
 
 ```bash
 npx klypix-mcp install
 ```
 
-This copies the engine and a local MCP runtime into `~/.claude/project-brain`, wires Claude Code's
-four lifecycle hooks, writes Codex's global `~/.codex/AGENTS.md` guidance block, and wires Codex's
-MCP connection **for the project you run it in**.
+One command, every editor. It finds the project root (walking up, so running it from `src/` is
+fine), gives the project a brain if it doesn't have one, wires the agent tools you actually have
+installed, registers the lossless `.klypix` merge driver if it's a git repo, and then **proves the
+result** before it exits:
+
+```text
+  project   E:\work\api  (git repository root)
+  brain     created brain.klypix — a starter brain, ready for its first decision
+  editors   Claude Code · Cursor · Codex · Gemini CLI · Antigravity · VS Code
+  wired     9 file(s) · 9 updated   (skipped 5 for tools you don't have)
+  git       lossless .klypix merge driver registered
+  verified  ✓ 26 tools reachable via .mcp.json (892ms)
+```
+
+That last line is the point. MCP config fails **silently** — a wrong entry means the server never
+starts, the agent quietly loses every brain verb, and nothing reports an error. So `install` opens
+a real stdio handshake against the config it just wrote and counts the tools that answered. A
+broken entry dies in ~100ms with `Connection closed` and is reported, not shipped.
+
+What goes where:
+
+- **Machine-global, once** — the engine + runtime in `~/.claude/project-brain`, Claude Code's four
+  lifecycle hooks in `~/.claude/settings.json`, and the `~/.codex/AGENTS.md` guidance block. Claude
+  Code is therefore covered in every project on that machine that has a `./brain.klypix`.
+- **Per project** — MCP config and rules for Cursor, Codex, Cline, Windsurf, Copilot, Gemini CLI /
+  Antigravity and Aider. Run `install` once inside each project.
 
-Be precise about what "machine-global" covers:
+Three things it deliberately will **not** do:
 
-- **Machine-global** — the engine + runtime in `~/.claude/project-brain`, the four Claude Code
-  hooks in `~/.claude/settings.json`, and the `~/.codex/AGENTS.md` guidance. Claude Code is
-  therefore covered in every project on that machine that has a `./brain.klypix`.
-- **Per project** — Codex's MCP connection. `install` writes it into `<cwd>/.codex/config.toml`,
-  only when that directory has a `brain.klypix`, and it deliberately **removes** any *global*
-  `~/.codex/config.toml` KLYPIX entry (a global entry resolves its `--vault` from the wrong
-  directory and binds the wrong brain). Run `install` — or `link` — once inside each brain project
-  you want Codex wired to.
+- **Write for editors you don't have.** Config is projected only for hosts detected on this
+  machine — a two-person team using one editor no longer commits rules for six they never opened.
+  A file your project *already* carries stays maintained regardless, so you can't silently stop
+  updating your team's committed configs.
+- **Wire a directory that isn't a project.** It refuses your home folder, a drive root, and
+  anything with no brain, no git repo and no project manifest. A mistyped command can't seed a
+  brain into `C:\Users\you`.
+- **Replace a project-owned server.** A repo-relative launch like
+  `node scripts/klypix-mcp-server.mjs` is deliberate — it resolves offline and rides a bundle the
+  repo version-gates — so it's left byte-identical and reported. An explicit `link` still rewrites
+  everything: an action you didn't ask for stays more conservative than one you did.
 
-It does **not** set up Cursor, Cline, Windsurf, Copilot, Gemini CLI or Aider — those need `link`.
+Opt out with `--no-project` (CI images, scripted provisioning). `--json` emits the report as
+structured data; `--verify-all` handshakes every written config instead of one.
 
 Optional, opt-in, and approved inside Codex itself:
 
@@ -119,15 +146,16 @@ file-overlap warning. Codex owns the trust decision and will ask you to review t
 `brain_doctor` reports this layer separately as off, execution-unverified, or active. Even with it
 on, **Codex never captures decisions automatically** — the Codex hook never writes the brain.
 
-**Every other agent tool — one command per project:**
+**Re-project everything explicitly:**
 
 ```bash
 npx klypix-mcp link
 ```
 
-Writes 14 managed, hash-stamped files: MCP server config for six hosts, plus rules files for
-eight. Managed blocks are merged into your existing instruction files and never clobber your
-content.
+`install` already does this for the editors you have. Reach for `link` when you want all 14
+managed, hash-stamped files regardless of what's installed — MCP server config for six hosts plus
+rules files for eight — or to repair drift. Managed blocks are merged into your existing
+instruction files and never clobber your content.
 
 ```bash
 npx klypix-mcp link --check    # audits without writing; exits non-zero on drift
@@ -481,8 +509,8 @@ The MCP verbs below are what agents call. These are what **you** call:
 | Command | What it does |
 |---|---|
 | `npx klypix-mcp init` | Seed a starter `brain.klypix` here and print an MCP config |
-| `npx klypix-mcp install` | Install the engine + Claude Code hooks on this machine (see Quick start) |
-| `npx klypix-mcp link` | Wire this project for Cursor, Cline, Windsurf, Copilot, Gemini CLI, Aider (`--check` audits) |
+| `npx klypix-mcp install` | Set up everything: machine engine + hooks, then this project — brain, config for the editors you have, merge driver, verified (see Quick start) |
+| `npx klypix-mcp link` | Re-project all 14 managed files regardless of what is installed (`--check` audits) |
 | `npx klypix-mcp doctor` | One verdict: version, hosts, live sessions, tool count, drift. Exits non-zero — usable as a CI gate |
 | `npx klypix-mcp runtime` | Passive per-connection process/RAM attribution (`--json`, optional `--watch seconds`); never kills or deduplicates |
 | `npx klypix-mcp conformance` | Launch two real MCP clients against this build and verify coordination behaviour |

package/bin/klypix-install.mjs

@@ -34,6 +34,7 @@ import {
 import { brainInstallDecision, deploySourceDecision } from '../src/install-version.mjs';
 import { acquireInstallLockSync, releaseInstallLockSync } from '../src/install-lock.mjs';
 import { collectRepoState } from '../src/repo-state.mjs';
+import { runSetup, renderBrief } from '../src/setup.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -48,6 +49,12 @@ const VERSION = (() => { try { return JSON.parse(fs.readFileSync(path.join(PKG_R
 const FORCE = process.argv.includes('--force');
 const CODEX_HOOKS = process.argv.includes('--codex-hooks');
 const RUNTIME_ONLY = process.argv.includes('--runtime-only');
+// Project wiring is the default because it is the step users did not know
+// existed. These opt OUT for the cases that genuinely want machine-only:
+// CI images, scripted provisioning, and anyone wiring the project by hand.
+const NO_PROJECT = process.argv.includes('--no-project');
+const VERIFY_ALL = process.argv.includes('--verify-all');
+const SETUP_JSON = process.argv.includes('--json');
 // Released-tag deploy-guard acknowledgement. Deliberately a SEPARATE axis from
 // --force: --force is destination authority (overwrite what is installed),
 // this is source authority (knowingly deploy an untagged working tree).
@@ -480,6 +487,24 @@ try {
         console.log('  Enhanced Codex auto-context + pre-edit overlap guard: re-run with `--codex-hooks`, then approve/review KLYPIX once in a Codex surface that supports hook trust.');
     }
     console.log('  Compatible brain-core updates hot-swap behind the same MCP connection. Only the one-time legacy→supervisor migration, a supervisor change, or an intentionally breaking tool/protocol change needs reconnect.');
+
+    // 9) PROJECT setup (1.71.0) — the step users never knew they had to take.
+    //    `install` wired the machine; without this it wired nothing a Cursor,
+    //    Antigravity, Codex, Cline or Copilot user could see, and the failure
+    //    was silent. A runtime-only refresh deliberately skips it: that path
+    //    exists to preserve every host/project config byte.
+    if (!RUNTIME_ONLY && !NO_PROJECT) {
+        try {
+            const report = await runSetup({ verifyAll: VERIFY_ALL });
+            if (SETUP_JSON) console.log(JSON.stringify(report, null, 2));
+            else console.log(renderBrief(report));
+        } catch (e) {
+            // The machine install already succeeded and is independently
+            // useful; a project-wiring failure must report itself, not undo it.
+            console.error(`⚠ project setup could not finish: ${e?.message || e}`);
+            console.error('  The machine install is intact — re-run inside your project, or use `npx klypix-mcp link`.');
+        }
+    }
     console.log('  Verify anytime: `npx klypix-mcp doctor`; prove two-client behavior with `npx klypix-mcp conformance`.');
 } catch (e) {
     releaseInstallLockSync(installLock);

package/bin/klypix-mcp.mjs

@@ -25,7 +25,8 @@ const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
   '',
   'Verbs:',
-  '  install [--force] [--codex-hooks]   install/update this machine\'s brain engine + Claude Code hooks',
+  '  install [--force] [--codex-hooks]   set up everything: machine engine + Claude hooks, then THIS project —',
+  '          [--no-project] [--json]     brain, config for the editors you actually have, merge driver, verified',
   '  link [dir] [--check]                project this project\'s 14 managed agent config files (--check audits, writes nothing, exits 1 on drift)',
   '  doctor [--npm] [--all] [--json]     read-only self-check; exits 1 on drift',
   '  runtime [--json] [--watch seconds]  passive MCP process/RAM attribution; never terminates a process',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.70.0",
+  "version": "1.71.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -84,7 +84,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/remote-client.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/remote-client.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/agent-rules.mjs

@@ -660,46 +660,73 @@ function classifyMcp(file, wrapKey, projectDir) {
 
 // The projection map — the single source of truth shared by WRITE (linkProject) and
 // CHECK (auditProject), so the two can never disagree about what's projected where.
+//
+// `editors` (1.71.0) names which detected hosts justify writing each file, so a
+// project stops collecting managed config for tools nobody on the machine has.
+// `standard: true` marks the cross-tool AGENTS.md convention — justified by ANY
+// agent host rather than one specific id. Filtering only happens when a caller
+// passes an explicit editor set; the default projects everything, exactly as
+// before, so every existing caller is unaffected.
 function targets(projectDir) {
   const j = (...p) => path.join(projectDir, ...p);
   return {
     rules: [
-      { tool: 'Codex / AGENTS.md standard', file: j('AGENTS.md'), kind: 'merge' },
-      { tool: 'Cursor', file: j('.cursor', 'rules', 'klypix-brain.mdc'), kind: 'dedicated', frontmatter: '---\ndescription: KLYPIX project brain — read at task start, capture decisions\nalwaysApply: true\n---' },
-      { tool: 'Windsurf', file: j('.windsurf', 'rules', 'klypix-brain.md'), kind: 'dedicated', frontmatter: '---\ntrigger: always_on\n---' },
-      { tool: 'Cline', file: j('.clinerules', 'klypix-brain.md'), kind: 'dedicated', frontmatter: '' },
-      { tool: 'GitHub Copilot', file: j('.github', 'copilot-instructions.md'), kind: 'merge' },
+      { tool: 'Codex / AGENTS.md standard', file: j('AGENTS.md'), kind: 'merge', editors: ['codex'], standard: true },
+      { tool: 'Cursor', file: j('.cursor', 'rules', 'klypix-brain.mdc'), kind: 'dedicated', editors: ['cursor'], frontmatter: '---\ndescription: KLYPIX project brain — read at task start, capture decisions\nalwaysApply: true\n---' },
+      { tool: 'Windsurf', file: j('.windsurf', 'rules', 'klypix-brain.md'), kind: 'dedicated', editors: ['windsurf'], frontmatter: '---\ntrigger: always_on\n---' },
+      { tool: 'Cline', file: j('.clinerules', 'klypix-brain.md'), kind: 'dedicated', editors: ['cline'], frontmatter: '' },
+      { tool: 'GitHub Copilot', file: j('.github', 'copilot-instructions.md'), kind: 'merge', editors: ['copilot'] },
       // Added 1.13.0 — close the "not generated at all" coverage gap the audit flagged.
-      { tool: 'Gemini CLI', file: j('GEMINI.md'), kind: 'merge' },
-      { tool: 'Aider', file: j('CONVENTIONS.md'), kind: 'dedicated', frontmatter: '' },
+      { tool: 'Gemini CLI', file: j('GEMINI.md'), kind: 'merge', editors: ['gemini-cli', 'antigravity'] },
+      { tool: 'Aider', file: j('CONVENTIONS.md'), kind: 'dedicated', editors: ['aider'], frontmatter: '' },
       // Added 1.29.1 — Antigravity (Gemini IDE) reads .agents/AGENTS.md; the desktop
       // app already writes it (projectBrainConnect.ts), this adds CLI audit coverage.
       // kind:'merge' so the fenced block coexists with any existing content.
-      { tool: 'Antigravity', file: j('.agents', 'AGENTS.md'), kind: 'merge' },
+      { tool: 'Antigravity', file: j('.agents', 'AGENTS.md'), kind: 'merge', editors: ['antigravity'] },
       // Intentionally NO project CLAUDE.md target. Claude receives the same task
       // contract mechanically through lifecycle hooks + MCP tool instructions;
       // the desktop legacy connector still owns CLAUDE.md, so a second Core
       // writer here would create duelling managed blocks and update churn.
     ],
     mcp: [
-      { tool: 'Codex', file: j('.codex', 'config.toml'), format: 'toml' },
-      { tool: 'Claude Code', file: j('.mcp.json'), wrapKey: 'mcpServers', withType: false },
-      { tool: 'Cursor', file: j('.cursor', 'mcp.json'), wrapKey: 'mcpServers', withType: false },
-      { tool: 'Cline', file: j('.cline', 'mcp.json'), wrapKey: 'mcpServers', withType: false },
-      { tool: 'Gemini CLI / Antigravity', file: j('.gemini', 'settings.json'), wrapKey: 'mcpServers', withType: false },
-      { tool: 'VS Code (Copilot/Continue)', file: j('.vscode', 'mcp.json'), wrapKey: 'servers', withType: true },
+      { tool: 'Codex', file: j('.codex', 'config.toml'), format: 'toml', editors: ['codex'] },
+      { tool: 'Claude Code', file: j('.mcp.json'), wrapKey: 'mcpServers', withType: false, editors: ['claude-code'] },
+      { tool: 'Cursor', file: j('.cursor', 'mcp.json'), wrapKey: 'mcpServers', withType: false, editors: ['cursor'] },
+      { tool: 'Cline', file: j('.cline', 'mcp.json'), wrapKey: 'mcpServers', withType: false, editors: ['cline'] },
+      { tool: 'Gemini CLI / Antigravity', file: j('.gemini', 'settings.json'), wrapKey: 'mcpServers', withType: false, editors: ['gemini-cli', 'antigravity'] },
+      { tool: 'VS Code (Copilot/Continue)', file: j('.vscode', 'mcp.json'), wrapKey: 'servers', withType: true, editors: ['vscode', 'copilot'] },
     ],
   };
 }
 
+/**
+ * Should this target be projected, given the hosts detected on the machine?
+ *
+ * Three independent yeses, in order of strength:
+ *  1. a detected host reads it;
+ *  2. it is the cross-tool AGENTS.md standard and SOME agent host is present;
+ *  3. the file already exists in the project — a teammate committed it, so it
+ *     stays current whether or not THIS machine has that editor. Without this
+ *     rule a one-editor developer would silently stop maintaining the configs
+ *     the rest of their team depends on.
+ */
+function targetJustified(target, editors, anyEditor) {
+  if (!editors) return true;                                        // unfiltered: project everything
+  if ((target.editors || []).some((id) => editors.has(id))) return true;
+  if (target.standard && anyEditor) return true;
+  return exists(target.file);
+}
+
 const relFile = (projectDir, abs) => path.relative(projectDir, abs).replace(/\\/g, '/');
 
 /**
  * Wire a project so EVERY agent tool reads + captures its brain automatically — or,
  * with { check:true }, AUDIT the projection without touching disk.
  * @param {string} projectDir absolute project root (holds ./brain.klypix)
- * @param {{ version?: string, check?: boolean }} [opts]
- * @returns {{ rules: Array, mcp: Array, hasBrain: boolean, version: string, check: boolean }}
+ * @param {{ version?: string, check?: boolean, editors?: Set<string>|string[] }} [opts]
+ *   editors — when supplied, project only what a detected host actually reads
+ *   (plus files the project already carries). Omit for the legacy write-all.
+ * @returns {{ rules, mcp, hasBrain, version, check, skipped: Array }}
  */
 export function linkProject(projectDir, opts = {}) {
   const version = opts.version || resolveVersion();
@@ -707,6 +734,29 @@ export function linkProject(projectDir, opts = {}) {
   const t = targets(projectDir);
   const hasBrain = exists(path.join(projectDir, 'brain.klypix')) || exists(path.join(projectDir, 'brain.any'));
 
+  const editors = opts.editors == null ? null
+    : (opts.editors instanceof Set ? opts.editors : new Set(opts.editors));
+  const anyEditor = !!editors && editors.size > 0;
+  // Files the caller has decided not to touch at all — used by the automatic
+  // setup path to leave a project-owned (vendored, repo-relative) server alone.
+  // An explicitly typed `link` still rewrites everything; an action the user
+  // did not ask for should be more conservative than one they did.
+  const exclude = opts.exclude instanceof Set ? opts.exclude
+    : new Set(Array.isArray(opts.exclude) ? opts.exclude : []);
+  const skipped = [];
+  const keep = (target) => {
+    const file = relFile(projectDir, target.file);
+    if (exclude.has(file)) {
+      skipped.push({ tool: target.tool, file, why: 'project-owned server — left untouched' });
+      return false;
+    }
+    if (targetJustified(target, editors, anyEditor)) return true;
+    skipped.push({ tool: target.tool, file, why: 'not installed on this machine' });
+    return false;
+  };
+  t.rules = t.rules.filter(keep);
+  t.mcp = t.mcp.filter(keep);
+
   const rules = t.rules.map((r) => {
     const file = relFile(projectDir, r.file);
     try {
@@ -761,7 +811,7 @@ export function linkProject(projectDir, opts = {}) {
     }
   });
 
-  return { rules, mcp, hasBrain, version, check };
+  return { rules, mcp, hasBrain, version, check, skipped };
 }
 
 /**

package/src/editor-detect.mjs

@@ -0,0 +1,117 @@
+// Which agent tools does this machine ACTUALLY have?
+//
+// Before 1.71 `link` projected all 14 managed files into every project, for
+// every supported host, whether or not the user had ever installed it. Those
+// files get COMMITTED, so a two-person team using one editor shipped rules and
+// MCP config for six they had never opened — repo clutter that reads as noise
+// in review and makes the tool look presumptuous on first contact.
+//
+// This module answers the narrower question the projection should have been
+// asking: is this host present on this machine? Detection is deliberately
+// EVIDENCE-BASED and conservative — every positive names the path or variable
+// that produced it (`why`), so a wrong answer is auditable rather than
+// mysterious. Absence is never proof; the caller pairs this with the
+// project-level signal (a target file already committed) and keeps projecting
+// anything a teammate already relies on.
+//
+// Pure except for fs existence checks, and every environment input is
+// injectable so the whole matrix is testable without touching a real home dir.
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+/** Roaming-config root per platform — where Electron editors keep their profile. */
+export function appDataDir({ platform = process.platform, home = os.homedir(), env = process.env } = {}) {
+  if (platform === 'win32') return env.APPDATA || path.join(home, 'AppData', 'Roaming');
+  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support');
+  return env.XDG_CONFIG_HOME || path.join(home, '.config');
+}
+
+// Extension hosts whose extension folders we scan for editor PLUGINS (Cline,
+// Copilot). VS Code forks keep the same `<publisher>.<name>-<version>` layout.
+const EXTENSION_ROOTS = ['.vscode', '.vscode-insiders', '.cursor', '.windsurf', '.vscode-oss'];
+
+/**
+ * The detection matrix. Each entry lists independent signals; ANY hit is a
+ * positive, because a user may have a CLI without the GUI or vice versa.
+ *  - home:  dot-dirs/files directly under the home directory
+ *  - app:   profile directory names under the platform's roaming-config root
+ *  - ext:   installed-extension id patterns (for plugin-shaped hosts)
+ *  - env:   environment variables an editor exports into its own terminal —
+ *           the strongest signal available, since it means we are running
+ *           INSIDE that editor right now
+ */
+const EDITORS = [
+  { id: 'claude-code', name: 'Claude Code', home: ['.claude'], env: ['CLAUDE_CODE_SESSION_ID', 'CLAUDE_PID'] },
+  { id: 'cursor', name: 'Cursor', home: ['.cursor'], app: ['Cursor'], env: ['CURSOR_SESSION_ID', 'CURSOR_TRACE_ID'] },
+  { id: 'codex', name: 'Codex', home: ['.codex'], env: ['CODEX_THREAD_ID'] },
+  { id: 'gemini-cli', name: 'Gemini CLI', home: ['.gemini'] },
+  { id: 'antigravity', name: 'Antigravity', home: ['.antigravity'], app: ['Antigravity'] },
+  { id: 'vscode', name: 'VS Code', home: ['.vscode', '.vscode-insiders'], app: ['Code', 'Code - Insiders', 'VSCodium'] },
+  { id: 'windsurf', name: 'Windsurf', home: ['.windsurf'], app: ['Windsurf'], env: ['WINDSURF_SESSION_ID'] },
+  { id: 'cline', name: 'Cline', ext: [/^saoudrizwan\.claude-dev/i], env: ['CLINE_SESSION_ID'] },
+  { id: 'copilot', name: 'GitHub Copilot', ext: [/^github\.copilot/i] },
+  { id: 'aider', name: 'Aider', home: ['.aider', '.aider.conf.yml', '.aider.model.settings.yml'] },
+];
+
+const exists = (p) => { try { return fs.existsSync(p); } catch { return false; } };
+
+/** Installed extension ids across every VS Code-shaped host on this machine. */
+function installedExtensions(home) {
+  const ids = [];
+  for (const root of EXTENSION_ROOTS) {
+    const dir = path.join(home, root, 'extensions');
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      ids.push({ id: e.name, from: `${root}/extensions/${e.name}` });
+    }
+  }
+  return ids;
+}
+
+/**
+ * Detect the agent tools present on this machine.
+ * @param {{ home?: string, platform?: string, env?: object }} [opts]
+ * @returns {{ present: Map<string,{id,name,why}>, absent: Array<{id,name}>, all: Array }}
+ */
+export function detectEditors(opts = {}) {
+  const home = opts.home || os.homedir();
+  const platform = opts.platform || process.platform;
+  const env = opts.env || process.env;
+  const appRoot = appDataDir({ platform, home, env });
+
+  // Scanned once — readdir on up to five extension roots is the only
+  // non-trivial cost in this module, and most machines have one or two.
+  let extensions = null;
+  const getExtensions = () => (extensions ??= installedExtensions(home));
+
+  const present = new Map();
+  const absent = [];
+
+  for (const ed of EDITORS) {
+    let why = null;
+
+    for (const key of ed.env || []) {
+      if (env[key]) { why = `running inside it (${key})`; break; }
+    }
+    if (!why) for (const dir of ed.home || []) {
+      if (exists(path.join(home, dir))) { why = `~/${dir}`; break; }
+    }
+    if (!why) for (const dir of ed.app || []) {
+      if (exists(path.join(appRoot, dir))) { why = `${path.basename(appRoot)}/${dir}`; break; }
+    }
+    if (!why && ed.ext) {
+      const hit = getExtensions().find((x) => ed.ext.some((re) => re.test(x.id)));
+      if (hit) why = hit.from;
+    }
+
+    if (why) present.set(ed.id, { id: ed.id, name: ed.name, why });
+    else absent.push({ id: ed.id, name: ed.name });
+  }
+
+  return { present, absent, all: EDITORS.map((e) => ({ id: e.id, name: e.name })) };
+}
+
+export { EDITORS };

package/src/mcp-presence.mjs

@@ -541,6 +541,15 @@ const publicSession = (session, now) => {
   };
 };
 
+// Freshness floor for "is this undeclared connection actually WORKING?".
+// Only real prompt/tool work stamps activityAt; heartbeats deliberately
+// preserve it, so a fresh stamp means work, not merely a live socket.
+const UNDECLARED_ACTIVE_MS = 10 * 60 * 1000;
+const isUndeclaredActive = (session, now) =>
+  !isTaskSession(session)
+  && Number(session?.activityAt || 0) > 0
+  && now - Number(session.activityAt) < UNDECLARED_ACTIVE_MS;
+
 export function buildPresenceSnapshot(sessions, selfId, { now = Date.now() } = {}) {
   const connected = Array.isArray(sessions) ? sessions : [];
   const self = connected.find((session) => session.id === selfId) || null;
@@ -548,25 +557,46 @@ export function buildPresenceSnapshot(sessions, selfId, { now = Date.now() } = {
   const others = connected.filter((session) => session.id !== selfId && !isSuspectedTwin(session, self));
   const twinCount = connected.length - 1 - others.length;
   const tasks = others.filter(isTaskSession);
+  // 1.71.0 — "background" conflated two very different things: a connection
+  // sitting idle, and a session actively editing this repo that never declared
+  // a scope. Only the second one falsifies the coordination promise, because a
+  // peer reading this snapshot cannot see the work it is doing. Doctor has
+  // drawn that line since 1.70; the sync response buried it in one number.
+  const undeclaredActive = others.filter((session) => isUndeclaredActive(session, now));
   return {
     connectionCount: connected.length - Math.max(0, twinCount),
     activeTaskCount: tasks.length + (self && isTaskSession(self) ? 1 : 0),
-    // "background" here means SYNC-SILENT, not idle: a connection that never
-    // declared a task may still be actively working — say so, don't bury it.
+    // Retained verbatim for every existing reader: idle + undeclared-active.
     backgroundConnectionCount: others.length - tasks.length,
+    // ADDITIVE: the subset that is provably working without declaring scope.
+    undeclaredActiveCount: undeclaredActive.length,
+    idleConnectionCount: Math.max(0, others.length - tasks.length - undeclaredActive.length),
     suspectedTwinCount: Math.max(0, twinCount),
     self: self ? publicSession(self, now) : null,
     peers: tasks.map((session) => publicSession(session, now)),
+    // Named, not just counted — a peer can address them with brain_message.
+    undeclaredActive: undeclaredActive.map((session) => publicSession(session, now)),
   };
 }
 
-function formatTaskPresence(snapshot, now = Date.now()) {
+export function formatTaskPresence(snapshot, now = Date.now()) {
   const taskWord = snapshot.activeTaskCount === 1 ? 'task' : 'tasks';
   const connectionWord = snapshot.connectionCount === 1 ? 'connection' : 'connections';
+  // The undeclared-ACTIVE count is stated separately and first among the
+  // caveats: it is the only figure here that means "work you cannot see".
+  const unseen = Number(snapshot.undeclaredActiveCount || 0);
+  const idle = Number(snapshot.idleConnectionCount ?? snapshot.backgroundConnectionCount ?? 0);
+  const caveats = [];
+  if (unseen) caveats.push(`${unseen} working WITHOUT declared scope — real edits you cannot see`);
+  if (idle) caveats.push(`${idle} connected but idle`);
   const lines = [
     `KLYPIX task presence: ${snapshot.activeTaskCount} active ${taskWord} across ${snapshot.connectionCount} live ${connectionWord}`
-      + (snapshot.backgroundConnectionCount ? ` (${snapshot.backgroundConnectionCount} connected without a declared task — presence known, scope unknown)` : '') + '.',
+      + (caveats.length ? ` (${caveats.join('; ')})` : '') + '.',
   ];
+  if (unseen) {
+    lines.push(`⚠ Overlap detection covers DECLARED scope only, so ${unseen === 1 ? 'that session is' : 'those sessions are'} invisible to it.`
+      + ' Treat a clean conflict report as incomplete, and coordinate directly (brain_message) before touching shared files.');
+  }
   if (!snapshot.peers.length) {
     lines.push('No other DECLARED task is active; connections that never called brain_sync are not listed here — they may still be working (see the connection count above).');
     return lines.join('\n');
@@ -2462,6 +2492,11 @@ export function createMcpPresence({
         connections: snapshot.connectionCount,
         activeTasks: snapshot.activeTaskCount,
         backgroundConnections: snapshot.backgroundConnectionCount,
+        // 1.71.0 — the half of `backgroundConnections` that is actually
+        // WORKING. A caller that reports "no conflicts" while this is non-zero
+        // is reporting an incomplete search, not a clear one.
+        undeclaredActive: snapshot.undeclaredActiveCount,
+        idleConnections: snapshot.idleConnectionCount,
       },
       peers: snapshot.peers,
       conflicts,

package/src/mcp-verify.mjs

@@ -0,0 +1,136 @@
+// Prove the config we just wrote actually starts a server.
+//
+// The recorded lesson this exists to enforce: CONFIG WHOSE BREAKAGE MODE IS
+// SILENCE NEEDS A GATE, NOT VIGILANCE. When a klypix entry is wrong the MCP
+// server simply does not start — no error, no warning; the agent quietly loses
+// every brain verb and degrades to whatever static context it already had. A
+// project once lost all 17 verbs for five days that way, and the only thing
+// that ever proved it was driving a REAL stdio handshake from the config
+// file's own values (broken config: dead in 101ms; fixed: ~1s, 17 tools).
+//
+// So this module never trusts what the writer believes it wrote. It re-reads
+// the file from disk, extracts the command and args the EDITOR will use, and
+// speaks JSON-RPC to whatever that launches. A pass means a real client would
+// connect; anything else is reported with the reason rather than swallowed.
+import fs from 'fs';
+import path from 'path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { safeReadCodexConfig } from './agent-rules.mjs';
+
+const isKlypix = (name) => /klypix/i.test(String(name || ''));
+
+/** Pull a TOML array-of-strings value (args = ["a", "b"]) out of a table block. */
+function parseTomlArgs(block) {
+  const m = String(block || '').match(/^[ \t]*args[ \t]*=[ \t]*\[([\s\S]*?)\]/m);
+  if (!m) return [];
+  const out = [];
+  const re = /(["'])((?:\\.|(?!\1)[^\\])*)\1/g;
+  let hit;
+  while ((hit = re.exec(m[1]))) out.push(hit[2].replace(/\\(["'\\])/g, '$1'));
+  return out;
+}
+
+/**
+ * Read a written MCP config and return the launch spec an editor would use.
+ * @returns {{ ok: boolean, command?: string, args?: string[], cwd?: string, why?: string }}
+ */
+export function readLaunchSpec(file) {
+  if (!fs.existsSync(file)) return { ok: false, why: 'config file not written' };
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); }
+  catch (e) { return { ok: false, why: `unreadable: ${e?.message || e}` }; }
+
+  if (/\.toml$/i.test(file)) {
+    const parsed = safeReadCodexConfig(file);
+    if (!parsed.ok) return { ok: false, why: parsed.error };
+    const name = Object.keys(parsed.servers).find(isKlypix);
+    if (!name) return { ok: false, why: 'no klypix server entry' };
+    const entry = parsed.servers[name];
+    if (!entry.command) return { ok: false, why: 'entry has no command' };
+    return { ok: true, command: entry.command, args: parseTomlArgs(entry.raw), cwd: entry.cwd || undefined };
+  }
+
+  let cfg;
+  try { cfg = JSON.parse(raw); }
+  catch (e) { return { ok: false, why: `invalid JSON: ${e?.message || e}` }; }
+  // `.vscode/mcp.json` uses `servers`; everyone else uses `mcpServers`.
+  const bag = (cfg && typeof cfg === 'object')
+    ? (cfg.mcpServers && typeof cfg.mcpServers === 'object' ? cfg.mcpServers
+      : cfg.servers && typeof cfg.servers === 'object' ? cfg.servers : null)
+    : null;
+  if (!bag) return { ok: false, why: 'no mcpServers/servers block' };
+  const name = Object.keys(bag).find(isKlypix);
+  if (!name) return { ok: false, why: 'no klypix server entry' };
+  const entry = bag[name] || {};
+  if (!entry.command) return { ok: false, why: 'entry has no command' };
+  return {
+    ok: true,
+    command: String(entry.command),
+    args: Array.isArray(entry.args) ? entry.args.map(String) : [],
+    cwd: entry.cwd ? String(entry.cwd) : undefined,
+  };
+}
+
+/**
+ * Launch the server exactly as the editor would and count the tools it offers.
+ *
+ * `cwd` defaults to the project root because several hosts resolve a relative
+ * `--vault .` against the session's working directory, not the config file's
+ * location — verifying from anywhere else would test a path no editor uses.
+ *
+ * @param {{ file: string, projectDir: string, timeoutMs?: number, env?: object }} opts
+ * @returns {Promise<{ ok: boolean, toolCount?: number, ms?: number, why?: string, hasBrainSync?: boolean }>}
+ */
+export async function verifyMcpConfig({ file, projectDir, timeoutMs = 25_000, env = process.env }) {
+  const spec = readLaunchSpec(file);
+  if (!spec.ok) return { ok: false, why: spec.why };
+
+  const started = Date.now();
+  let client = null;
+  try {
+    const childEnv = Object.fromEntries(
+      Object.entries({ ...env, KLYPIX_AUTO_UPDATE: '0', KLYPIX_RERANK: '0' })
+        .filter(([, v]) => typeof v === 'string'),
+    );
+    const transport = new StdioClientTransport({
+      command: spec.command,
+      args: spec.args,
+      cwd: spec.cwd || projectDir,
+      env: childEnv,
+      stderr: 'pipe',
+    });
+    client = new Client({ name: 'klypix-setup-verify', version: '1.0.0' });
+
+    // A hung child must not hang setup. The race leaves the transport to the
+    // finally block, which closes it either way.
+    const connected = await Promise.race([
+      client.connect(transport).then(() => 'ok'),
+      new Promise((r) => setTimeout(() => r('timeout'), timeoutMs)),
+    ]);
+    if (connected === 'timeout') return { ok: false, why: `no response within ${Math.round(timeoutMs / 1000)}s` };
+
+    const listed = await Promise.race([
+      client.listTools().then((t) => t),
+      new Promise((r) => setTimeout(() => r(null), timeoutMs)),
+    ]);
+    if (!listed) return { ok: false, why: 'connected but never listed its tools' };
+
+    const tools = Array.isArray(listed.tools) ? listed.tools : [];
+    return {
+      ok: tools.length > 0,
+      toolCount: tools.length,
+      hasBrainSync: tools.some((t) => t?.name === 'brain_sync'),
+      ms: Date.now() - started,
+      ...(tools.length ? {} : { why: 'server started but offered no tools' }),
+    };
+  } catch (e) {
+    // The classic broken-config signature is an immediate "Connection closed".
+    const why = String(e?.message || e).replace(/\s+/g, ' ').slice(0, 200);
+    return { ok: false, why, ms: Date.now() - started };
+  } finally {
+    try { await client?.close(); } catch { /* the child is exiting anyway */ }
+  }
+}
+
+export { parseTomlArgs };

package/src/setup.mjs

@@ -0,0 +1,286 @@
+// One command that knows where it is.
+//
+// Until 1.71 a user had to know three things nobody told them: that `install`
+// wires the machine but not the project, that `link` writes the per-editor
+// config, and that `init` seeds the brain. Miss the middle one — as the website
+// invited people to — and seven of eight editors showed an empty MCP panel with
+// no error. A promise is only as true as its quietest step, so this module
+// deletes the steps instead of documenting them.
+//
+// It deliberately DELEGATES rather than reimplements: the brain seed comes from
+// the existing `init` verb and the merge driver from `git-driver install`, both
+// already tested and both idempotent (init refuses to overwrite an existing
+// brain; the driver re-registers harmlessly). Running them as child processes
+// keeps their exact behaviour and keeps this file thin — a duplicated seed is a
+// second source of truth waiting to drift.
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execFile } from 'child_process';
+import { detectEditors } from './editor-detect.mjs';
+import { linkProject } from './agent-rules.mjs';
+import { verifyMcpConfig, readLaunchSpec } from './mcp-verify.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.join(__dirname, '..', 'bin', 'klypix-mcp.mjs');
+const BRAIN_NAMES = ['brain.klypix', 'brain.any'];
+const exists = (p) => { try { return fs.existsSync(p); } catch { return false; } };
+
+function runCli(args, cwd, timeout = 60_000) {
+  return new Promise((resolve) => {
+    execFile(process.execPath, [CLI, ...args], { cwd, timeout, windowsHide: true }, (error, stdout, stderr) => {
+      resolve({ ok: !error, out: String(stdout || ''), err: String(stderr || ''), code: error?.code ?? 0 });
+    });
+  });
+}
+
+/**
+ * Where does this project actually start?
+ *
+ * Users run commands from wherever they happen to be — `src/`, `admin/`, a
+ * package folder — so cwd is the wrong answer more often than it is the right
+ * one. An existing brain wins over the git root, because a monorepo may keep
+ * per-package brains; the git root is the fallback that makes a fresh repo seed
+ * its brain beside the code rather than three levels down.
+ */
+export function resolveProjectRoot(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+  const chain = [];
+  for (let i = 0; i < 40; i++) {
+    chain.push(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  for (const d of chain) {
+    for (const name of BRAIN_NAMES) if (exists(path.join(d, name))) return { root: d, why: `found ${name}` };
+  }
+  for (const d of chain) {
+    if (exists(path.join(d, '.git'))) return { root: d, why: 'git repository root' };
+  }
+  return { root: path.resolve(startDir), why: 'current directory' };
+}
+
+// Manifests that mark a directory as somebody's project even without git.
+// Non-developers are a first-class audience here, so "no repo" must not mean
+// "no brain" — but it does mean we need SOME positive signal before writing.
+const PROJECT_MANIFESTS = [
+  'package.json', 'pyproject.toml', 'requirements.txt', 'Cargo.toml', 'go.mod',
+  'pom.xml', 'build.gradle', 'Gemfile', 'composer.json', 'CMakeLists.txt',
+  'README.md', 'AGENTS.md', 'CLAUDE.md',
+];
+
+/**
+ * Is it safe and sensible to wire this directory?
+ *
+ * `install` is run from wherever the user happens to be standing, and the
+ * failure we must never ship is seeding a brain into a home directory or a
+ * drive root because someone typed the command in the wrong window. A refusal
+ * is cheap; an unexpected brain.klypix in C:\Users\me is not.
+ */
+export function projectSignal(root, { home = null } = {}) {
+  const resolved = path.resolve(root);
+  const homeDir = path.resolve(home || (process.env.USERPROFILE || process.env.HOME || ''));
+  if (homeDir && resolved === homeDir) return { ok: false, why: 'this is your home folder, not a project' };
+  if (path.dirname(resolved) === resolved) return { ok: false, why: 'this is a drive root, not a project' };
+
+  for (const name of BRAIN_NAMES) if (exists(path.join(resolved, name))) return { ok: true, why: `has ${name}` };
+  if (exists(path.join(resolved, '.git'))) return { ok: true, why: 'git repository' };
+  for (const name of PROJECT_MANIFESTS) if (exists(path.join(resolved, name))) return { ok: true, why: `has ${name}` };
+  return { ok: false, why: 'no project files found here' };
+}
+
+// Every MCP config this project could carry, relative to its root. Kept beside
+// the projection map's own list so the ownership check covers all six hosts,
+// not just the Claude Code one the original migration knew about.
+const MCP_FILES = [
+  '.mcp.json', '.cursor/mcp.json', '.cline/mcp.json',
+  '.gemini/settings.json', '.vscode/mcp.json', '.codex/config.toml',
+];
+
+/**
+ * Is this config pinned to a server the PROJECT owns?
+ *
+ * A repo-relative node launch (`scripts/klypix-mcp-server.mjs`) is a deliberate
+ * choice: it resolves offline, is identical on every machine, and rides a
+ * vendored bundle the repo version-gates, so the running server can never skew
+ * from what the repo ships. Replacing it with a machine-specific ~/.claude path
+ * would break exactly the property it was chosen for — and silently. The
+ * existing `.mcp.json` migration has always honoured this; automatic setup must
+ * honour it across every host.
+ */
+export function isProjectOwnedMcp(file) {
+  const spec = readLaunchSpec(file);
+  if (!spec.ok) return false;
+  const first = spec.args?.[0];
+  return /(^|[\\/])node(\.exe)?$/i.test(spec.command)
+    && typeof first === 'string'
+    && first !== '-e'
+    && !first.startsWith('-')
+    && !path.isAbsolute(first);
+}
+
+/** The written config most worth proving — the host we are running inside, if any. */
+function pickVerifyTarget(written, present) {
+  const inside = [...present.values()].find((e) => /running inside it/.test(e.why));
+  const byEditor = (id) => written.find((w) => (w.editors || []).includes(id));
+  return (inside && byEditor(inside.id))
+    || byEditor('claude-code')
+    || byEditor('cursor')
+    || written[0]
+    || null;
+}
+
+/**
+ * Wire this project end to end, then prove it.
+ * @param {{ cwd?, verifyAll?, skipVerify?, timeoutMs? }} [opts]
+ * @returns {Promise<object>} a structured report (also the `--json` payload)
+ */
+export async function runSetup(opts = {}) {
+  const started = Date.now();
+  const { root, why: rootWhy } = resolveProjectRoot(opts.cwd || process.cwd());
+  const report = {
+    schema: 1,
+    project: root,
+    rootReason: rootWhy,
+    brain: null,
+    editors: { present: [], skippedTargets: [] },
+    wrote: [],
+    gitDriver: null,
+    verified: null,
+    warnings: [],
+  };
+
+  // 0) Refuse politely rather than write into somewhere that isn't a project.
+  const signal = projectSignal(root);
+  if (!signal.ok) {
+    report.skipped = signal.why;
+    report.ms = Date.now() - started;
+    return report;
+  }
+  report.rootReason = `${rootWhy}`;
+
+  // 1) A brain, or there is nothing to wire.
+  const brainPath = BRAIN_NAMES.map((n) => path.join(root, n)).find(exists);
+  if (brainPath) {
+    report.brain = { path: brainPath, created: false };
+  } else {
+    const seeded = await runCli(['init'], root);
+    const madePath = BRAIN_NAMES.map((n) => path.join(root, n)).find(exists);
+    if (!madePath) {
+      report.brain = { path: null, created: false, error: (seeded.err || seeded.out).trim().slice(0, 300) || 'init produced no brain' };
+      report.warnings.push('No brain could be created — nothing else could be wired.');
+      report.ms = Date.now() - started;
+      return report;
+    }
+    report.brain = { path: madePath, created: true };
+  }
+
+  // 2) Which hosts does this machine actually have?
+  const detected = detectEditors();
+  report.editors.present = [...detected.present.values()];
+
+  // 3) Project config for those hosts only — plus anything the project already
+  // carries, so a one-editor developer keeps their team's files current.
+  const projectOwned = MCP_FILES.filter((rel) => isProjectOwnedMcp(path.join(root, rel)));
+  const linked = linkProject(root, { editors: detected.present.keys(), exclude: projectOwned });
+  report.editors.skippedTargets = linked.skipped;
+  report.wrote = [...linked.rules, ...linked.mcp]
+    .filter((t) => t.status !== 'error' && t.action !== 'skipped')
+    .map((t) => ({ tool: t.tool, file: t.file, action: t.action || t.status || 'ok' }));
+  for (const t of [...linked.rules, ...linked.mcp]) {
+    if (t.status === 'error' || (t.action === 'skipped' && t.why)) {
+      report.warnings.push(`${t.file}: ${t.why || 'could not be written'}`);
+    }
+  }
+
+  // 4) The merge driver, silently — never a settings panel with an Install
+  // button. Only meaningful inside a git repo.
+  if (exists(path.join(root, '.git'))) {
+    const drv = await runCli(['git-driver', 'install', root], root, 30_000);
+    report.gitDriver = { ok: drv.ok, detail: (drv.out || drv.err).split('\n').find((l) => l.trim())?.trim() || null };
+    if (!drv.ok) report.warnings.push('Could not register the .klypix merge driver — brain merges will need manual conflict resolution.');
+  }
+
+  // 5) Prove it. Writing a config is not evidence that a server starts, and the
+  // failure mode of a wrong entry is silence, so setup does not exit until a
+  // real client has connected and counted tools.
+  if (!opts.skipVerify) {
+    // linkProject reports per-file results, not the editor ids behind them, so
+    // re-attach them here purely to choose WHICH config to prove.
+    const idFor = {
+      '.codex/config.toml': ['codex'], '.mcp.json': ['claude-code'], '.cursor/mcp.json': ['cursor'],
+      '.cline/mcp.json': ['cline'], '.gemini/settings.json': ['gemini-cli', 'antigravity'], '.vscode/mcp.json': ['vscode', 'copilot'],
+    };
+    const mcpWritten = linked.mcp
+      .filter((m) => m.status !== 'error' && m.action !== 'skipped')
+      .map((m) => ({ ...m, editors: idFor[m.file] || [] }));
+    // A project-owned config is left untouched but is still what the editor
+    // will launch — and an unverified vendored path is precisely how a repo
+    // once lost every brain verb for five days. Prove it too.
+    for (const rel of projectOwned) {
+      mcpWritten.push({ tool: `${rel} (project-owned)`, file: rel, editors: idFor[rel] || [] });
+    }
+
+    const chosen = opts.verifyAll ? mcpWritten : [pickVerifyTarget(mcpWritten, detected.present)].filter(Boolean);
+    const results = [];
+    for (const target of chosen) {
+      const res = await verifyMcpConfig({
+        file: path.join(root, target.file),
+        projectDir: root,
+        timeoutMs: opts.timeoutMs || 25_000,
+      });
+      results.push({ tool: target.tool, file: target.file, ...res });
+      if (!res.ok) report.warnings.push(`${target.file} did not start a server: ${res.why}`);
+    }
+    report.verified = results;
+  }
+
+  report.ms = Date.now() - started;
+  return report;
+}
+
+/** The five-line brief a human reads after the command finishes. */
+export function renderBrief(report) {
+  const L = [];
+  const rel = (p) => path.relative(report.project, p).replace(/\\/g, '/') || path.basename(p);
+  L.push('');
+  if (report.skipped) {
+    L.push(`  No project wired — ${report.skipped}.`);
+    L.push(`  Run this again inside your project folder: cd <your project> && npx klypix-mcp install`);
+    L.push('');
+    return L.join('\n');
+  }
+  L.push(`  project   ${report.project}  (${report.rootReason})`);
+  L.push(report.brain?.created
+    ? `  brain     created ${rel(report.brain.path)} — a starter brain, ready for its first decision`
+    : report.brain?.path ? `  brain     ${rel(report.brain.path)} (already here — left untouched)`
+      : '  brain     ✗ none');
+
+  const names = report.editors.present.map((e) => e.name);
+  L.push(`  editors   ${names.length ? names.join(' · ') : 'none detected'}`);
+
+  const changed = report.wrote.filter((w) => w.action && !/^(ok|unchanged|current)$/i.test(w.action));
+  L.push(`  wired     ${report.wrote.length} file(s)${changed.length ? ` · ${changed.length} updated` : ' · all current'}`
+    + (report.editors.skippedTargets.length ? `   (skipped ${report.editors.skippedTargets.length} for tools you don't have)` : ''));
+
+  if (report.gitDriver) {
+    L.push(`  git       ${report.gitDriver.ok ? 'lossless .klypix merge driver registered' : '✗ merge driver not registered'}`);
+  }
+
+  for (const v of report.verified || []) {
+    L.push(v.ok
+      ? `  verified  ✓ ${v.toolCount} tools reachable via ${v.file} (${v.ms}ms)`
+      : `  verified  ✗ ${v.file} — ${v.why}`);
+  }
+
+  L.push('');
+  if (report.warnings.length) {
+    for (const w of report.warnings) L.push(`  ⚠ ${w}`);
+    L.push('');
+  } else if ((report.verified || []).some((v) => v.ok)) {
+    L.push('  Open the project in your editor and ask it: "sync with the KLYPIX brain."');
+    L.push('');
+  }
+  return L.join('\n');
+}