klypix-mcp 1.70.0 → 1.72.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).
@@ -64,7 +71,7 @@ const CODEX_CONFIG = path.join(HOME, '.codex', 'config.toml');
 const HOOK_MARK = 'global-brain-hook';
 const exists = (p) => { try { fs.statSync(p); return true; } catch { return false; } };
 const fwd = (p) => p.replace(/\\/g, '/');
-const copyRetrySleepSync = (ms) => {
+const retrySleepSync = (ms) => {
     try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
     catch { /* best effort */ }
 };
@@ -74,7 +81,7 @@ function copyFileRobust(src, dest, tries = 8) {
         catch (error) {
             const retryable = ['EBUSY', 'EPERM', 'EACCES'].includes(error?.code);
             if (!retryable || attempt === tries) throw error;
-            copyRetrySleepSync(20 * attempt);
+            retrySleepSync(20 * attempt);
         }
     }
 }
@@ -167,6 +174,44 @@ function reportCodex(result) {
 // update hook runs install per project, so every project heals once). Only the
 // known npx/node launch is migrated; a hand-customized command / invalid JSON is
 // left untouched, and the original is backed up. Best-effort, never throws.
+// ── Windows rename hardening (1.71.1) ───────────────────────────────────────
+// Every atomic commit in this installer is a rename-over-destination, and on
+// Windows that throws EPERM/EBUSY/EACCES while ANY process briefly holds the
+// target — an AV scan, an indexer, or, routinely on a developer machine, the
+// live MCP servers reading the very bundle we are replacing. Measured 2026-08-15:
+// three failures in one session with 7-14 servers live, on .mcp-runtime.json and
+// brain-history.mjs; each retry succeeded immediately.
+//
+// The failure is loud rather than silent, and a manual re-run fixes it — but
+// this is the FIRST command a new user types, and a raw EPERM stack at that
+// moment is a bad first contact. So the installer now outlasts a transient
+// holder using the SAME bounded backoff the brain write funnel has used since
+// 1.68.0 (klypix-format.mjs atomicWrite): ~2.7s total, then rethrow. A
+// persistent holder still fails loudly — delayed is acceptable, silently wrong
+// is not, and pretending we wrote a file we did not would be far worse.
+const RENAME_RETRYABLE_CODES = new Set(['EPERM', 'EBUSY', 'EACCES']);
+const RENAME_BACKOFF_MS = [40, 120, 300, 700, 1500];
+/** fs.renameSync that outlasts a transient Windows lock on the destination. */
+function renameSyncWithBackoff(from, to) {
+    for (let attempt = 0; ; attempt++) {
+        try { return fs.renameSync(from, to); }
+        catch (e) {
+            if (attempt >= RENAME_BACKOFF_MS.length || !RENAME_RETRYABLE_CODES.has(e?.code)) {
+                // Name the real cause: "EPERM: operation not permitted" tells a
+                // user nothing actionable, and the fix is usually to close the
+                // editors whose servers hold the bundle.
+                if (RENAME_RETRYABLE_CODES.has(e?.code)) {
+                    e.message = `${e.message}\n  ↳ ${path.basename(to)} is held by another process after ~2.7s of retries.`
+                        + '\n    On Windows this is normally a running MCP server, an antivirus scan, or an indexer.'
+                        + '\n    Close your editors (or quit KLYPIX) and run the command again — nothing was left half-written.';
+                }
+                throw e;
+            }
+            retrySleepSync(RENAME_BACKOFF_MS[attempt]);
+        }
+    }
+}
+
 function migrateProjectMcpConfig() {
     try {
         const file = path.join(process.cwd(), '.mcp.json');
@@ -355,7 +400,7 @@ try {
     } catch { /* .prev rollback snapshot is best-effort */ }
     const renameOrder = staged.slice().sort((a, b) => (a.dst === 'global-brain-hook.mjs' ? 1 : 0) - (b.dst === 'global-brain-hook.mjs' ? 1 : 0));
     let n = 0;
-    for (const st of renameOrder) { fs.renameSync(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }
+    for (const st of renameOrder) { renameSyncWithBackoff(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }
 
     // 3) mark the dir an ESM package
     fs.writeFileSync(path.join(BRAIN_DIR, 'package.json'), JSON.stringify({ name: 'klypix-project-brain', private: true, type: 'module' }, null, 2));
@@ -390,7 +435,7 @@ try {
         const tmp = SETTINGS + '.klypix-tmp';
         fs.writeFileSync(tmp, JSON.stringify(settings, null, 2), 'utf8');
         JSON.parse(fs.readFileSync(tmp, 'utf8'));   // verify before swap
-        fs.renameSync(tmp, SETTINGS);
+        renameSyncWithBackoff(tmp, SETTINGS);
     }
 
     // 6) Commit the runtime pointer and version receipt atomically while the
@@ -417,7 +462,7 @@ try {
     };
     const runtimePath = path.join(BRAIN_DIR, '.mcp-runtime.json');
     fs.writeFileSync(runtimePath + '.klypix-new', JSON.stringify(runtime, null, 2) + '\n', 'utf8');
-    fs.renameSync(runtimePath + '.klypix-new', runtimePath);
+    renameSyncWithBackoff(runtimePath + '.klypix-new', runtimePath);
     // A tagged-but-DIRTY checkout keeps via:'npm' (the tag still names the
     // payload identity, and dev:true would stop auto-update from healing the
     // machine back to clean released bytes) but stamps dirty:true + the audit
@@ -430,7 +475,7 @@ try {
             : { brainVersion: VERSION, via: 'npm', dirty: false, installedAt };
     const versionPath = path.join(BRAIN_DIR, '.brain-version.json');
     fs.writeFileSync(versionPath + '.klypix-new', JSON.stringify(versionStamp, null, 2), 'utf8');
-    fs.renameSync(versionPath + '.klypix-new', versionPath);
+    renameSyncWithBackoff(versionPath + '.klypix-new', versionPath);
 
     // 7) migrate THIS project's .mcp.json off npx onto the now-installed local bundle
     //    (heals an existing stale config so the next MCP server spawn runs current).
@@ -480,6 +525,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/bin/klypix-worker.mjs

@@ -876,7 +876,8 @@ server.registerTool('brain_sync', {
     releaseIntent: z.object({
       version: z.string().max(64).describe('The version this session intends to release (e.g. "1.70.0").'),
       ref: z.string().max(200).describe('The git ref (branch or tag) the release will be cut from.'),
-    }).optional().describe('Declare EXCLUSIVE intent to prepare a release of this project. The first declarer takes a ~2h lease (refreshed by checkpoints, freed by phase "complete", by expiry, or when the holder session ends); a second declarer gets a structured hard conflict naming the holder, version, and ref. While any lease is active every peer\'s sync gains a "release in preparation" footer line.'),
+      acknowledge: z.array(z.string().max(40)).max(64).optional().describe('Commit shas this release DELIBERATELY leaves behind. Only needed after a refusal: if the ref would drop finished work, the lease is refused and the response names every sha. Re-declare with those shas here to proceed — and tell the user what they are first.'),
+    }).optional().describe('Declare EXCLUSIVE intent to prepare a release of this project. The first declarer takes a ~2h lease (refreshed by checkpoints, freed by phase "complete", by expiry, or when the holder session ends); a second declarer gets a structured hard conflict naming the holder, version, and ref. While any lease is active every peer\'s sync gains a "release in preparation" footer line. A NEW declaration is also checked against what the release would LEAVE BEHIND: if the ref is missing commits that are on trunk or on a branch a live peer session is working on, the lease is REFUSED (nothing is changed) and the response lists them — report those commits to the user, then re-declare with acknowledge:[...] naming each sha if the release should go ahead without them.'),
   },
 }, async ({ project, intent, files, phase, include_context, results, releaseIntent }, extra) => {
   const totalStartedAt = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.70.0",
+  "version": "1.72.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/install-rename-backoff.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/release-ancestry.mjs && node test/release-handshake.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 };