@theronap/cortex-mcp 0.9.43 → 0.9.45

package/bin/cortex-mcp.mjs

@@ -41,7 +41,8 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `This wires your Claude config so your AI sees your Cortex context and your\n` +
     `sessions flow into the org automatically. Restart Claude Code after.\n\n` +
     `Subcommands:\n` +
-    `  setup <token>   wire MCP server + capture hook into ~/.claude config\n` +
+    `  setup <token>   wire MCP server + capture hook into ~/.claude config (single editor)\n` +
+    `  install [<token>] [--editor auto|all|<id,...>]  wire Cortex into EVERY detected editor + write the capability manifest\n` +
     `  repair          re-run setup at the latest version using your existing token (no token needed)\n` +
     `  uninstall       remove ALL Cortex wiring (MCP, hooks, skills, launchd, cron). --dry-run to preview, --purge to also wipe ~/.cortex + npx cache\n` +
     `  doctor          live health check — confirm your token works (no restart needed)\n` +
@@ -70,6 +71,13 @@ if (cmd === 'setup') {
   await runSetup(rest, VERSION)
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'install') {
+  // The cross-editor hub installer: wire Cortex into every detected editor via the adapter
+  // registry, then write the capability manifest (~/.cortex/editors.json). Superset of `setup`.
+  const { runInstall } = await import('../lib/install.mjs')
+  await runInstall(rest, VERSION)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'uninstall' || cmd === 'remove') {
   // Full reverse of setup: strip every Cortex touch-point (MCP entries, hooks, skills, launchd, cron).
   // --dry-run prints the plan and changes nothing; --purge also removes ~/.cortex, the npx cache, and
@@ -115,7 +123,7 @@ if (cmd === 'setup') {
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
 } else if (cmd === 'grep') {
-  // Literal substring search over the viewer's visible brain wiki (thin client of /api/grep).
+  // Ranked keyword (fts) search by default; --substring/--literal for exact lookups. Thin client of /api/grep.
   const { runGrep } = await import('../lib/grep_cli.mjs')
   process.exitCode = await runGrep(rest)
   const { closeFetch } = await import('../lib/diagnose.mjs')

package/lib/editors/_fsutil.mjs

@@ -0,0 +1,31 @@
+// Shared file helpers for editor adapters. These MIRROR setup.mjs's private helpers exactly so an
+// extracted wire() writes byte-identical output (same backup name, same JSON formatting).
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+/** Parse a JSON config, tolerating absent/empty files; THROWS on malformed (caller decides). */
+export function readJson(path) {
+  if (!existsSync(path)) return {}
+  const raw = readFileSync(path, 'utf8').trim()
+  if (!raw) return {}
+  return JSON.parse(raw)
+}
+
+/** Copy path → path.cortex-bak before mutating. Returns the backup path, or null if nothing to back up. */
+export function backupFile(path) {
+  if (!existsSync(path)) return null
+  const bak = `${path}.cortex-bak`
+  copyFileSync(path, bak)
+  return bak
+}
+
+/** Ensure the parent directory of `path` exists. */
+export function ensureDir(path) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+/** Write an object as pretty JSON — the exact formatting setup.mjs uses (2-space indent). */
+export function writeJson(path, obj) {
+  writeFileSync(path, JSON.stringify(obj, null, 2))
+}

package/lib/editors/antigravity.mjs

@@ -0,0 +1,123 @@
+// Editor adapter: Antigravity. P0-b task 4 — deterministic artifact generators + wire().
+//
+// Antigravity has no in-editor hook; sync is a launchd agent (com.cortex.antigravity-sync) that
+// WatchPaths the trajectory store and runs a one-shot sync. wire() generates the two artifacts
+// (the sync.sh + the launchd plist) deterministically. It does NOT run `launchctl load` here
+// (an unverifiable system mutation) and it flags the PORTABILITY BLOCKER below.
+//
+// ⚠ BLOCKER (surfaced P0-b task 4): antigravity-sync.sh runs the sync from a LOCAL DEV CHECKOUT
+// ($HOME/dev/cortex/packages/cortex-agent via `bun run src/index.ts antigravity-sync`). A coworker
+// has no ~/dev/cortex, so Antigravity capture is bespoke to the author's machine and is NOT yet
+// installable for a real seat. Making it portable requires a published `antigravity-sync` entrypoint
+// (npx @theronap/cortex-mcp antigravity-sync, or a published cortex-agent) — a prerequisite this
+// adapter cannot satisfy alone. Until then wire() writes the artifacts + returns a blocking warning.
+import { homedir } from 'node:os'
+import { writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs'
+import { join } from 'node:path'
+
+const AG_STATE = ['Library', 'Application Support', 'Antigravity']
+const AG_WATCH = [...AG_STATE, 'User', 'globalStorage']
+
+/** The launchd plist, home-substituted. Deterministic — golden-testable byte-for-byte. */
+export function renderAntigravityPlist({ home = homedir() } = {}) {
+  const sh = join(home, '.cortex', 'antigravity-sync.sh')
+  const watch = join(home, ...AG_WATCH)
+  const logp = join(home, '.cortex', 'antigravity-sync.launchd.log')
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.cortex.antigravity-sync</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>${sh}</string>
+  </array>
+  <key>WatchPaths</key>
+  <array>
+    <string>${watch}</string>
+  </array>
+  <key>RunAtLoad</key>
+  <false/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  <string>${logp}</string>
+  <key>StandardErrorPath</key>
+  <string>${logp}</string>
+</dict>
+</plist>
+`
+}
+
+/** The sync.sh. Self-resolves paths via $HOME at runtime, so it is a static template.
+ *  NOTE the AGENT_DIR line is the portability blocker documented above. */
+export function renderAntigravitySyncSh() {
+  return `#!/bin/bash
+# Cortex ⇄ Antigravity one-shot sync, triggered by launchd WatchPaths on the Antigravity
+# trajectory store. There is no resident daemon — launchd wakes this on change and it exits.
+# Token is resolved from the wired MCP config at runtime (never stored in plist/script).
+# ⚠ AGENT_DIR points at a local dev checkout — see antigravity.mjs BLOCKER note (not coworker-portable).
+set -o pipefail
+LOG="$HOME/.cortex/antigravity-sync.log"
+NODE="/usr/local/bin/node"
+BUN="$HOME/.bun/bin/bun"
+AGENT_DIR="$HOME/dev/cortex/packages/cortex-agent"
+
+stamp() { date -u +%FT%TZ; }
+
+TOKEN="$("$NODE" -e "try{console.log(JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude.json','utf8'))?.mcpServers?.cortex?.env?.CORTEX_TOKEN||'')}catch(e){process.exit(0)}" 2>/dev/null)"
+if [ -z "$TOKEN" ]; then echo "$(stamp) no CORTEX_TOKEN wired, skipping" >> "$LOG"; exit 0; fi
+if [ ! -d "$AGENT_DIR" ]; then echo "$(stamp) agent dir missing: $AGENT_DIR" >> "$LOG"; exit 0; fi
+
+cd "$AGENT_DIR" || exit 0
+CORTEX_TOKEN="$TOKEN" CORTEX_WATCH="$HOME/.cortex-agent" "$BUN" run src/index.ts antigravity-sync >> "$LOG" 2>&1
+echo "$(stamp) exit=$?" >> "$LOG"
+exit 0
+`
+}
+
+/** @type {import('./index.mjs').EditorAdapter} */
+export default {
+  id: 'antigravity',
+  displayName: 'Antigravity',
+
+  detect({ home = homedir(), exists = existsSync } = {}) {
+    return exists(join(home, ...AG_STATE))
+  },
+
+  capabilities: {
+    promptTimeInjection: false,  // no in-editor injection possible today
+    sessionStart: false,
+    captureHook: true,           // post-sync, via antigravity-sync.sh
+    skillDir: null,
+    docTrigger: 'watch',
+  },
+
+  // Writes the two artifacts deterministically. Does NOT launchctl-load (unverifiable side effect) and
+  // returns a BLOCKING warning about the dev-checkout dependency — honest about not-yet-installable.
+  async wire({ home = homedir(), log = () => {} } = {}) {
+    const wrote = [], skipped = [], warnings = []
+    const cortexDir = join(home, '.cortex')
+    const shPath = join(cortexDir, 'antigravity-sync.sh')
+    const plistPath = join(home, 'Library', 'LaunchAgents', 'com.cortex.antigravity-sync.plist')
+
+    try { // non-fatal: an IO error must not abort sibling editors
+      mkdirSync(cortexDir, { recursive: true })
+      writeFileSync(shPath, renderAntigravitySyncSh())
+      try { chmodSync(shPath, 0o755) } catch { /* non-fatal on non-posix */ }
+      wrote.push(shPath)
+
+      mkdirSync(join(home, 'Library', 'LaunchAgents'), { recursive: true })
+      writeFileSync(plistPath, renderAntigravityPlist({ home }))
+      wrote.push(plistPath)
+      log(`  ✓ Antigravity artifacts → ${shPath}, ${plistPath}`)
+    } catch (e) {
+      warnings.push(`Antigravity artifact write skipped: ${e.message}`)
+    }
+
+    warnings.push('Antigravity NOT fully wired: (1) run `launchctl load ' + plistPath + '` to activate the watcher; (2) BLOCKER — the sync runs from a local dev checkout (~/dev/cortex/packages/cortex-agent), so it will not work on a machine without that checkout until a published antigravity-sync entrypoint exists.')
+    return { wrote, skipped, warnings }
+  },
+}

package/lib/editors/claude.mjs

@@ -0,0 +1,125 @@
+// Editor adapter: Claude Code. P0-b task 2 — wire() + the pure merge functions extracted from
+// setup.mjs. setup.mjs imports THESE SAME functions (and re-exports them), so the config bytes are
+// structurally identical, not merely "supposed to match".
+import { homedir } from 'node:os'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { readJson, backupFile, ensureDir, writeJson } from './_fsutil.mjs'
+
+/** Merge the Cortex MCP server into a ~/.claude.json object. Pure + idempotent: sets only the
+ *  `cortex` entry (type:'stdio'), preserves every other server. `spec` = the package@dist-tag string. */
+export function mergeClaudeMcp(existing, spec, token) {
+  const cfg = existing && typeof existing === 'object' ? { ...existing } : {}
+  cfg.mcpServers = cfg.mcpServers && typeof cfg.mcpServers === 'object' ? { ...cfg.mcpServers } : {}
+  cfg.mcpServers.cortex = { type: 'stdio', command: 'npx', args: ['-y', spec], env: { CORTEX_TOKEN: token } }
+  return cfg
+}
+
+/** Merge Cortex's Claude Code hooks into a ~/.claude/settings.json object. Pure + idempotent: drops
+ *  any prior cortex entry (old token/path/version) from each hook array before appending the current
+ *  one — capture (Stop), status + skills-repair + snapshot-context (SessionStart), precompact
+ *  (PreCompact). Commands carry NO inline token (each subcommand self-resolves it). Mirrors setup.mjs
+ *  step 2 exactly; foreign hooks are never touched. */
+export function mergeClaudeSettings(existing, spec) {
+  const s = existing && typeof existing === 'object' ? existing : {}
+  s.hooks = s.hooks ?? {}
+
+  // Stop — capture.
+  s.hooks.Stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
+  const captureCmd = `npx -y ${spec} capture`
+  for (const grp of s.hooks.Stop) {
+    if (Array.isArray(grp.hooks)) grp.hooks = grp.hooks.filter((h) => !/cortex-mcp.*capture|capture-session-cloud/.test(h.command ?? ''))
+  }
+  let grp = s.hooks.Stop.find((g) => (g.matcher ?? '') === '')
+  if (!grp) { grp = { matcher: '', hooks: [] }; s.hooks.Stop.push(grp) }
+  grp.hooks = grp.hooks ?? []
+  grp.hooks.push({ type: 'command', command: captureCmd })
+
+  // SessionStart — status, then skills self-heal, then snapshot-context (order matters: matches setup).
+  s.hooks.SessionStart = Array.isArray(s.hooks.SessionStart) ? s.hooks.SessionStart : []
+  const statusCmd = `npx -y ${spec} status`
+  for (const sg of s.hooks.SessionStart) {
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? status/.test(h.command ?? ''))
+  }
+  let sgrp = s.hooks.SessionStart.find((g) => (g.matcher ?? '') === '')
+  if (!sgrp) { sgrp = { matcher: '', hooks: [] }; s.hooks.SessionStart.push(sgrp) }
+  sgrp.hooks = sgrp.hooks ?? []
+  sgrp.hooks.push({ type: 'command', command: statusCmd })
+
+  const skillsCmd = `npx -y ${spec} skills --repair --quiet`
+  for (const sg of s.hooks.SessionStart) {
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? skills/.test(h.command ?? ''))
+  }
+  sgrp.hooks.push({ type: 'command', command: skillsCmd })
+
+  const snapshotCmd = `npx -y ${spec} snapshot-context`
+  for (const sg of s.hooks.SessionStart) {
+    if (Array.isArray(sg.hooks)) sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? snapshot-context/.test(h.command ?? ''))
+  }
+  sgrp.hooks.push({ type: 'command', command: snapshotCmd })
+
+  // PreCompact — "author now" reminder.
+  s.hooks.PreCompact = Array.isArray(s.hooks.PreCompact) ? s.hooks.PreCompact : []
+  const precompactCmd = `npx -y ${spec} precompact`
+  for (const pg of s.hooks.PreCompact) {
+    if (Array.isArray(pg.hooks)) pg.hooks = pg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? precompact/.test(h.command ?? ''))
+  }
+  let pgrp = s.hooks.PreCompact.find((g) => (g.matcher ?? '') === '')
+  if (!pgrp) { pgrp = { matcher: '', hooks: [] }; s.hooks.PreCompact.push(pgrp) }
+  pgrp.hooks = pgrp.hooks ?? []
+  pgrp.hooks.push({ type: 'command', command: precompactCmd })
+
+  return s
+}
+
+/** @type {import('./index.mjs').EditorAdapter} */
+export default {
+  id: 'claude-code',
+  displayName: 'Claude Code',
+
+  detect({ home = homedir(), exists = existsSync } = {}) {
+    return exists(join(home, '.claude')) || exists(join(home, '.claude.json'))
+  },
+
+  capabilities: {
+    promptTimeInjection: true,
+    sessionStart: true,
+    captureHook: true,
+    skillDir: '~/.claude/skills',
+    docTrigger: 'stop-hook',
+  },
+
+  // Two independent, non-fatal blocks (mirrors codex.mjs): a malformed file OR an IO error is
+  // skipped-with-warning, never a throw that aborts the other block or a sibling editor. readJson
+  // throws on malformed → caught here → that file is left untouched (never overwritten). The WRITTEN
+  // bytes come from the shared pure functions above, so they are identical to setup's output.
+  async wire({ home = homedir(), token, spec, log = () => {} } = {}) {
+    const wrote = [], skipped = [], warnings = []
+    if (!token) { warnings.push('no token — skipped Claude Code'); return { wrote, skipped, warnings } }
+
+    const claudeJson = join(home, '.claude.json')
+    try {
+      const cfg = readJson(claudeJson) // {} if absent/empty; THROWS (→ skip) if malformed
+      const bak = backupFile(claudeJson)
+      ensureDir(claudeJson)
+      writeJson(claudeJson, mergeClaudeMcp(cfg, spec, token))
+      wrote.push(claudeJson)
+      log(`  ✓ MCP server → ${claudeJson}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`${claudeJson} wiring skipped: ${e.message}`)
+    }
+
+    const settingsJson = join(home, '.claude', 'settings.json')
+    try {
+      const s = readJson(settingsJson)
+      const bak = backupFile(settingsJson)
+      ensureDir(settingsJson)
+      writeJson(settingsJson, mergeClaudeSettings(s, spec))
+      wrote.push(settingsJson)
+      log(`  ✓ Capture hook + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`${settingsJson} wiring skipped: ${e.message}`)
+    }
+    return { wrote, skipped, warnings }
+  },
+}

package/lib/editors/codex.mjs

@@ -0,0 +1,111 @@
+// Editor adapter: OpenAI Codex. P0-b task 3 — wire() + the pure merge functions, moved here verbatim
+// from setup.mjs (which now imports + re-exports them). No caller imported them from setup except
+// setup itself, so this move is transparent.
+import { homedir } from 'node:os'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { readJson, backupFile, ensureDir, writeJson } from './_fsutil.mjs'
+
+/** Merge the Cortex MCP server into a Codex config.toml. Pure + idempotent: strips any existing
+ *  [mcp_servers.cortex] / [mcp_servers.cortex.env] tables (so re-runs update in place rather than
+ *  duplicating — a duplicate TOML table would break Codex's parser), preserves every other table,
+ *  and appends a fresh block. Only touches the cortex tables; never rewrites the user's config. */
+export function mergeCodexToml(text, spec, token) {
+  const targets = new Set(['[mcp_servers.cortex]', '[mcp_servers.cortex.env]'])
+  const kept = []
+  let skipping = false
+  for (const line of (text || '').split('\n')) {
+    const t = line.trim()
+    if (t.startsWith('[') && t.endsWith(']')) skipping = targets.has(t)
+    if (!skipping) kept.push(line)
+  }
+  while (kept.length && kept[kept.length - 1].trim() === '') kept.pop() // drop trailing blanks
+  const block = [
+    '',
+    '[mcp_servers.cortex]',
+    'command = "npx"',
+    `args = ["-y", "${spec}"]`,
+    'startup_timeout_sec = 60', // first npx fetch can be slow; don't time out the server on cold start
+    '',
+    '[mcp_servers.cortex.env]',
+    `CORTEX_TOKEN = "${token}"`,
+    '',
+  ]
+  return [...kept, ...block].join('\n')
+}
+
+/** Merge the capture Stop hook into a Codex hooks.json object. Pure + idempotent: drops any prior
+ *  cortex capture entry (old token / old path / old pinned version) before appending the current one,
+ *  so re-running never duplicates and never leaves a stale version pinned behind a live one.
+ *  Codex's hook runtime has NO SessionStart — only capture (Stop) is wired here. */
+export function mergeCodexHooks(existing, captureCmd) {
+  const h = existing && typeof existing === 'object' ? existing : {}
+  h.hooks = h.hooks && typeof h.hooks === 'object' ? h.hooks : {}
+  h.hooks.Stop = Array.isArray(h.hooks.Stop) ? h.hooks.Stop : []
+  for (const grp of h.hooks.Stop) {
+    if (Array.isArray(grp.hooks)) {
+      grp.hooks = grp.hooks.filter((c) => !/cortex-mcp.*capture|capture-session-cloud/.test(c.command ?? ''))
+    }
+  }
+  let grp = h.hooks.Stop.find((g) => (g.matcher ?? '') === '')
+  if (!grp) { grp = { matcher: '', hooks: [] }; h.hooks.Stop.push(grp) }
+  grp.hooks = grp.hooks ?? []
+  grp.hooks.push({ type: 'command', command: captureCmd })
+  return h
+}
+
+/** @type {import('./index.mjs').EditorAdapter} */
+export default {
+  id: 'codex',
+  displayName: 'OpenAI Codex',
+
+  detect({ home = homedir(), exists = existsSync } = {}) {
+    return exists(join(home, '.codex'))
+  },
+
+  // Codex's hook runtime recognizes PreToolUse/PostToolUse/PreCompact/UserPromptSubmit/Stop — notably
+  // NO SessionStart. So status/skills-repair/snapshot-context stay Claude-only; the manifest must
+  // encode sessionStart:false so P1/P2 don't assume it.
+  capabilities: {
+    promptTimeInjection: true,
+    sessionStart: false,
+    captureHook: true,
+    skillDir: null,
+    docTrigger: 'stop-hook',
+  },
+
+  // Two independent, non-fatal blocks (config.toml + hooks.json) — mirrors setup.mjs steps 1b/1c.
+  // Written bytes come from the shared pure functions above → identical to setup's output.
+  async wire({ home = homedir(), token, spec, log = () => {} } = {}) {
+    const wrote = [], skipped = [], warnings = []
+    if (!token) { warnings.push('no token — skipped Codex'); return { wrote, skipped, warnings } }
+    const codexDir = join(home, '.codex')
+
+    try {
+      const codexToml = join(codexDir, 'config.toml')
+      const existing = existsSync(codexToml) ? readFileSync(codexToml, 'utf8') : ''
+      const bak = backupFile(codexToml)
+      ensureDir(codexToml)
+      writeFileSync(codexToml, mergeCodexToml(existing, spec, token)) // raw TOML text, not JSON
+      wrote.push(codexToml)
+      log(`  ✓ MCP server → ${codexToml}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`Codex MCP wiring skipped: ${e.message}`)
+    }
+
+    try {
+      const codexHooks = join(codexDir, 'hooks.json')
+      let existingHooks
+      try { existingHooks = readJson(codexHooks) } catch { existingHooks = {} } // malformed → start fresh, don't block
+      const bak = backupFile(codexHooks)
+      const captureCmd = `npx -y ${spec} capture`
+      ensureDir(codexHooks)
+      writeJson(codexHooks, mergeCodexHooks(existingHooks, captureCmd))
+      wrote.push(codexHooks)
+      log(`  ✓ Capture hook → ${codexHooks}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`Codex capture hook skipped: ${e.message}`)
+    }
+    return { wrote, skipped, warnings }
+  },
+}

package/lib/editors/cursor.mjs

@@ -0,0 +1,77 @@
+// Editor adapter: Cursor. P0-b task 4 (+ review fixes).
+// ~/.cursor/mcp.json uses the same mcpServers.cortex shape as Claude (minus the `type` field the real
+// Cursor config omits), so wiring Cursor is a pure JSON merge (mergeCursorMcp).
+import { homedir } from 'node:os'
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { backupFile } from './_fsutil.mjs'
+
+/** Merge the Cortex MCP server into a Cursor mcp.json object. Pure + idempotent: sets only the
+ *  `cortex` entry, preserves every other server. `spec` is the package@dist-tag STRING — the same
+ *  convention claude/codex/setup.mjs use, so one install driver can pass a single spec to every adapter. */
+export function mergeCursorMcp(existing, spec, token) {
+  const cfg = existing && typeof existing === 'object' ? { ...existing } : {}
+  cfg.mcpServers = cfg.mcpServers && typeof cfg.mcpServers === 'object' ? { ...cfg.mcpServers } : {}
+  cfg.mcpServers.cortex = { command: 'npx', args: ['-y', spec], env: { CORTEX_TOKEN: token } }
+  return cfg
+}
+
+/** @type {import('./index.mjs').EditorAdapter} */
+export default {
+  id: 'cursor',
+  displayName: 'Cursor',
+
+  detect({ home = homedir(), exists = existsSync } = {}) {
+    return exists(join(home, '.cursor'))
+  },
+
+  // Today Cursor is capture-only: the hook buffers turns and POSTs to /api/ingest, but does not
+  // inject sibling-session context at prompt time. promptTimeInjection stays false until the
+  // Pillar-1 Cursor inject hook is built (a named gap in cross-app-session-visibility-spec.md).
+  capabilities: {
+    promptTimeInjection: false,
+    sessionStart: false,
+    captureHook: true,           // ~/.cursor/hooks/cortex-cursor.mjs
+    skillDir: null,              // Cursor rules/commands dir — revisit in Pillar 2
+    docTrigger: 'hook',
+  },
+
+  // Non-fatal by contract: a Cursor failure (parse OR IO) must never abort the other editors' wiring.
+  async wire({ home = homedir(), token, spec, log = () => {} } = {}) {
+    const wrote = [], skipped = [], warnings = []
+    if (!token) { warnings.push('no token — skipped Cursor'); return { wrote, skipped, warnings } }
+
+    const cursorDir = join(home, '.cursor')
+    const mcpPath = join(cursorDir, 'mcp.json')
+    try {
+      let existing = {}
+      if (existsSync(mcpPath)) {
+        try {
+          existing = JSON.parse(readFileSync(mcpPath, 'utf8'))
+        } catch {
+          // Data-loss guard: a malformed mcp.json may still hold the user's other MCP servers we can't
+          // safely parse. Do NOT overwrite it with a cortex-only config — skip with a warning.
+          warnings.push(`${mcpPath} is not valid JSON — left untouched (fix it, then re-run) to avoid dropping your other MCP servers`)
+          return { wrote, skipped, warnings }
+        }
+      }
+      const bak = backupFile(mcpPath)
+      mkdirSync(cursorDir, { recursive: true })
+      writeFileSync(mcpPath, JSON.stringify(mergeCursorMcp(existing, spec, token), null, 2))
+      wrote.push(mcpPath)
+      log(`  ✓ MCP server → ${mcpPath}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      warnings.push(`Cursor MCP wiring skipped: ${e.message}`) // IO error → non-fatal, siblings unaffected
+    }
+
+    // Capture hook: detect, don't fabricate. The cortex-cursor.mjs hook isn't bundled in this package
+    // yet (it was hand-installed), so warn rather than write a guessed file. Bundling it is follow-up.
+    const hookPath = join(cursorDir, 'hooks', 'cortex-cursor.mjs')
+    if (!existsSync(hookPath)) {
+      warnings.push('Cursor capture hook (~/.cursor/hooks/cortex-cursor.mjs) not found — Cursor sessions will not be captured until it is installed')
+    } else {
+      skipped.push(`${hookPath} (already present)`)
+    }
+    return { wrote, skipped, warnings }
+  },
+}

package/lib/editors/index.mjs

@@ -0,0 +1,42 @@
+// Editor adapter registry (P0-b task 1). One place that knows every editor Cortex can wire.
+// Adding an editor = add a module here; the install driver + capability manifest fall out of it.
+//
+// EditorAdapter shape (see the four modules):
+//   id            stable string id (used in the manifest + `--editor <id>`)
+//   displayName   human label
+//   detect(env)   → boolean; env = { home?, exists? } is injectable for tests
+//   capabilities  { promptTimeInjection, sessionStart, captureHook, skillDir, docTrigger }
+//   wire(ctx)     → performs the install for this editor (stubbed in task 1)
+//
+/** @typedef {Object} EditorAdapter */
+
+import claude from './claude.mjs'
+import codex from './codex.mjs'
+import cursor from './cursor.mjs'
+import antigravity from './antigravity.mjs'
+
+export const ADAPTERS = [claude, codex, cursor, antigravity]
+
+/**
+ * Resolve which editors an install targets.
+ *   'auto'          → every adapter whose detect() is true on this machine (the default)
+ *   'all'           → every adapter, regardless of detection
+ *   'id'|'a,b'      → the named adapter(s); throws on an unknown id (fail loud, don't silently skip)
+ *
+ * @param {string} [flag='auto']
+ * @param {{ adapters?: EditorAdapter[], env?: { home?: string, exists?: (p: string) => boolean } }} [opts]
+ * @returns {EditorAdapter[]}
+ */
+export function resolveEditors(flag = 'auto', { adapters = ADAPTERS, env } = {}) {
+  if (flag === 'all') return [...adapters]
+  if (flag === 'auto') return adapters.filter((a) => a.detect(env))
+
+  const ids = String(flag).split(',').map((s) => s.trim()).filter(Boolean)
+  const known = new Set(adapters.map((a) => a.id))
+  const unknown = ids.filter((id) => !known.has(id))
+  if (unknown.length) {
+    throw new Error(`Unknown editor(s): ${unknown.join(', ')}. Known: ${adapters.map((a) => a.id).join(', ')}`)
+  }
+  // Preserve registry order, dedupe.
+  return adapters.filter((a) => ids.includes(a.id))
+}

package/lib/grep_cli.mjs

@@ -5,16 +5,20 @@ import { fetchCortex, classify, resolveBase } from './diagnose.mjs'
 // Output is ASCII-only (outbound-message convention).
 
 // Pure: parse argv after `grep` → { query, mode, max }.
-//   cortex grep <terms...> [--mode fts | --fts] [--max N]
+//   cortex grep <terms...> [--substring | --literal] [--max N]
+// Default mode is 'fts' (ranked keyword — multi-word queries work); pass --substring/--literal for
+// an exact literal match (identifiers, [[links]], code). (#220)
 export function parseGrepArgs(argv = []) {
-  const out = { query: '', mode: 'substring', max: undefined }
+  const out = { query: '', mode: 'fts', max: undefined }
   const terms = []
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
     if (a === '--mode') {
-      out.mode = argv[++i] === 'fts' ? 'fts' : 'substring'
+      out.mode = argv[++i] === 'substring' ? 'substring' : 'fts'
     } else if (a === '--fts') {
       out.mode = 'fts'
+    } else if (a === '--substring' || a === '--literal') {
+      out.mode = 'substring'
     } else if (a === '--max') {
       const n = Number(argv[++i])
       if (Number.isFinite(n)) out.max = Math.trunc(n)
@@ -50,7 +54,7 @@ export async function runGrep(rest = []) {
   }
   const { query, mode, max } = parseGrepArgs(rest)
   if (!query) {
-    process.stderr.write('usage: cortex grep <query> [--mode fts] [--max N]\n')
+    process.stderr.write('usage: cortex grep <query> [--substring|--literal] [--max N]\n')
     return 1
   }
   const qs = new URLSearchParams({ q: query, mode })

package/lib/install.mjs

@@ -0,0 +1,161 @@
+// `cortex install` — the cross-editor hub installer (P0-b). One command that wires the Cortex MCP
+// server + client shim into EVERY detected editor via the adapter registry, then writes a capability
+// manifest so later pillars (session sync, skill sync, doc sync) know which channels each editor
+// supports. `setup <token>` stays as the single-editor path the console prints; `install` is the
+// multi-editor superset that drives the SAME adapter `wire()` functions.
+import { homedir } from 'node:os'
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { ADAPTERS, resolveEditors } from './editors/index.mjs'
+import { checkToken, resolveBase, readWiredToken } from './diagnose.mjs'
+
+const PKG = '@theronap/cortex-mcp'
+export const MANIFEST_PATH = join(homedir(), '.cortex', 'editors.json')
+
+/** Parse install argv: an optional positional <token> + `--editor auto|all|<id,...>` (also `--all`,
+ *  `--editor=<v>`, `-e <v>`). Unknown flags are ignored (fail-soft — never mistaken for the token). */
+export function parseInstallArgs(argv = []) {
+  let editor = 'auto'
+  let token
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--editor' || a === '-e') { editor = argv[++i] ?? editor; continue }
+    if (a.startsWith('--editor=')) { editor = a.slice('--editor='.length); continue }
+    if (a === '--all') { editor = 'all'; continue }
+    if (a.startsWith('-')) continue // ignore unknown flags, don't treat as token
+    if (token === undefined) token = a
+  }
+  return { token, editor: editor || 'auto' }
+}
+
+/** Pure: build the capability manifest from resolved per-editor entries. Injectable `now`/`cortexMcp`
+ *  keep it deterministic for tests. Each entry = { adapter, detected, wired, wrote?, warnings? }. */
+export function buildManifest(entries, { now = new Date().toISOString(), cortexMcp = null } = {}) {
+  return {
+    schema: 1,
+    generatedAt: now,
+    cortexMcp,
+    editors: entries.map((e) => ({
+      id: e.adapter.id,
+      displayName: e.adapter.displayName,
+      detected: !!e.detected,
+      wired: !!e.wired,
+      capabilities: e.adapter.capabilities,
+      wrote: e.wrote ?? [],
+      warnings: e.warnings ?? [],
+    })),
+  }
+}
+
+/** Read the existing manifest ({} if absent/malformed — never throws). */
+export function readManifest({ path = MANIFEST_PATH } = {}) {
+  try {
+    if (!existsSync(path)) return {}
+    const raw = readFileSync(path, 'utf8').trim()
+    return raw ? JSON.parse(raw) : {}
+  } catch {
+    return {} // malformed manifest is not fatal — a fresh install rewrites it
+  }
+}
+
+export function writeManifest(manifest, { path = MANIFEST_PATH } = {}) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(path, JSON.stringify(manifest, null, 2))
+  return path
+}
+
+export async function runInstall(argv, version) {
+  const { token: argToken, editor } = parseInstallArgs(argv)
+  const token = argToken || readWiredToken()
+  const spec = `${PKG}@stable`
+  const home = homedir()
+  const log = (m) => process.stdout.write(m + '\n')
+
+  if (!token) {
+    process.stderr.write(
+      'Usage: npx @theronap/cortex-mcp install [<CORTEX_TOKEN>] [--editor auto|all|<id,...>]\n\n' +
+      'No token was given and none is already wired.\n' +
+      'Get your token from the Cortex console → Connect your AI.\n',
+    )
+    process.exit(1)
+  }
+
+  let targets
+  try {
+    targets = resolveEditors(editor)
+  } catch (e) {
+    process.stderr.write(`\n✗ ${e.message}\n`)
+    process.exit(1)
+  }
+
+  log('')
+  log('Cortex install — wiring your AI editors…')
+  if (editor === 'auto' && targets.length === 0) {
+    log('  (no supported editors detected — pass --editor all to force, or install an editor first)')
+  }
+
+  // Carry forward prior manifest state for editors NOT targeted this run, so a single-editor
+  // `install --editor cursor` doesn't wipe the "wired" record of editors a previous run set up.
+  const priorById = new Map((readManifest().editors ?? []).map((e) => [e.id, e]))
+  const targetIds = new Set(targets.map((a) => a.id))
+
+  const entries = []
+  for (const adapter of ADAPTERS) {
+    const detected = safeDetect(adapter)
+    if (!targetIds.has(adapter.id)) {
+      const p = priorById.get(adapter.id)
+      entries.push({ adapter, detected, wired: p?.wired ?? false, wrote: p?.wrote ?? [], warnings: [] })
+      continue
+    }
+    log(`\n${adapter.displayName}:`)
+    let res = { wrote: [], skipped: [], warnings: [] }
+    try {
+      res = (await adapter.wire({ home, token, spec, log })) ?? res
+    } catch (e) {
+      // A single editor's failure must never abort the others (fail-soft, like setup's Codex block).
+      res.warnings = [...(res.warnings ?? []), `wire failed: ${e.message}`]
+      log(`  ⚠ ${adapter.displayName} wiring failed: ${e.message}`)
+    }
+    for (const w of res.warnings ?? []) log(`  ⚠ ${w}`)
+    entries.push({
+      adapter,
+      detected,
+      wired: (res.wrote ?? []).length > 0,
+      wrote: res.wrote ?? [],
+      warnings: res.warnings ?? [],
+    })
+  }
+
+  const mpath = writeManifest(buildManifest(entries, { cortexMcp: version ?? null }))
+  log(`\n  ✓ Capability manifest → ${mpath}`)
+
+  // Verify the token against the live API — writing config proves "files written", not "it works".
+  const base = resolveBase(process.env.CORTEX_URL)
+  log('')
+  log('Verifying your token against Cortex…')
+  try {
+    const health = await checkToken(token, base)
+    if (health.ok) {
+      const n = health.projectCount
+      log(`  ✓ Verified — your token works${typeof n === 'number' ? ` (you can see ${n} project${n === 1 ? '' : 's'})` : ''}.`)
+    } else {
+      log('  ⚠ Config written, but the live check did NOT pass:')
+      log(`     ${health.diagnosis?.message ?? 'unknown error'}`)
+      log('     The files are in place; fix the above, then re-check with `doctor`.')
+    }
+  } catch (e) {
+    log(`  ⚠ Could not reach Cortex to verify (${e.message}). Config is written; re-check with 'doctor'.`)
+  }
+
+  const wired = entries.filter((e) => targetIds.has(e.adapter.id) && e.wired).map((e) => e.adapter.displayName)
+  log('')
+  log(`⟳ Wired ${wired.length} editor(s): ${wired.join(', ') || '(none)'}`)
+  log('   Fully quit and reopen each editor to load the Cortex server.')
+  log(`   Console: ${base}`)
+  log('')
+}
+
+function safeDetect(adapter) {
+  try { return !!adapter.detect() } catch { return false }
+}

package/lib/server.mjs

@@ -266,14 +266,14 @@ export async function runServer(version) {
     {
       title: 'Grep the brain wiki',
       description:
-        'Literal substring search across your visible brain wiki pages (matches symbols, identifiers, [[links]]). Returns matching sections with a context snippet and their outbound [[links]].',
+        'Ranked keyword search across your visible brain wiki pages. Multi-word natural-language queries work (results are ranked by relevance). Pass mode:"substring" for an exact literal match of symbols, identifiers, or [[links]]. Returns matching sections with a context snippet and their outbound [[links]].',
       inputSchema: {
-        query: z.string().describe('literal substring to find'),
-        mode: z.enum(['substring', 'fts']).optional().describe("'substring' (default, grep-like) or 'fts' (ranked keyword)"),
+        query: z.string().describe('search terms (natural language is fine)'),
+        mode: z.enum(['substring', 'fts']).optional().describe("'fts' (default, ranked keyword) or 'substring' (exact literal — for identifiers / [[links]] / code)"),
       },
     },
     async ({ query, mode }) => {
-      const qs = new URLSearchParams({ q: query, mode: mode === 'fts' ? 'fts' : 'substring' })
+      const qs = new URLSearchParams({ q: query, mode: mode === 'substring' ? 'substring' : 'fts' })
       const res = await fetchCortex(`${BASE}/api/grep?${qs.toString()}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
       if (!res.ok) {
         const body = await res.text()
@@ -643,6 +643,33 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'create_brain',
+    {
+      title: 'Create a new brain under your existing account',
+      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; use set_active_brain afterward to point writes at it (creating it does not switch your active write brain automatically).',
+      inputSchema: { name: z.string().describe('display name for the new brain, e.g. "Cortex Codebase"') },
+    },
+    async ({ name }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brains`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ name }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not create brain: ${e.message}` }] }
+      }
+      if (!res.ok) {
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        return { content: [{ type: 'text', text: `Could not create brain: ${d.message}` }] }
+      }
+      const r = await res.json()
+      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Run set_active_brain with this org_id to start writing to it — reads already span it automatically.` }] }
+    },
+  )
+
   server.registerTool(
     'list_records',
     {

package/lib/setup.mjs

@@ -3,6 +3,10 @@ import { homedir } from 'os'
 import { join, dirname } from 'path'
 import { checkToken, resolveBase, readWiredToken } from './diagnose.mjs'
 import { installSkills } from './skills.mjs'
+// Pure config-merge functions live in the editor adapters; setup imports (and re-exports) THE SAME
+// functions the `cortex install` path uses, so both write byte-identical config.
+import { mergeClaudeMcp, mergeClaudeSettings } from './editors/claude.mjs'
+import { mergeCodexToml, mergeCodexHooks } from './editors/codex.mjs'
 
 // One-command employee onboarding. Wires both:
 //   1. ~/.claude.json        → the cortex MCP server (context-serving)
@@ -14,33 +18,7 @@ import { installSkills } from './skills.mjs'
 
 const PKG = '@theronap/cortex-mcp'
 
-// Merge the Cortex MCP server into a Codex config.toml. Pure + idempotent: strips any existing
-// [mcp_servers.cortex] / [mcp_servers.cortex.env] tables (so re-runs update in place rather than
-// duplicating — a duplicate TOML table would break Codex's parser), preserves every other table,
-// and appends a fresh block. Only touches the cortex tables; never rewrites the user's config.
-export function mergeCodexToml(text, spec, token) {
-  const targets = new Set(['[mcp_servers.cortex]', '[mcp_servers.cortex.env]'])
-  const kept = []
-  let skipping = false
-  for (const line of (text || '').split('\n')) {
-    const t = line.trim()
-    if (t.startsWith('[') && t.endsWith(']')) skipping = targets.has(t)
-    if (!skipping) kept.push(line)
-  }
-  while (kept.length && kept[kept.length - 1].trim() === '') kept.pop() // drop trailing blanks
-  const block = [
-    '',
-    '[mcp_servers.cortex]',
-    'command = "npx"',
-    `args = ["-y", "${spec}"]`,
-    'startup_timeout_sec = 60', // first npx fetch can be slow; don't time out the server on cold start
-    '',
-    '[mcp_servers.cortex.env]',
-    `CORTEX_TOKEN = "${token}"`,
-    '',
-  ]
-  return [...kept, ...block].join('\n')
-}
+// mergeCodexToml / mergeCodexHooks moved to ./editors/codex.mjs (imported above, re-exported below).
 
 function readJson(path) {
   if (!existsSync(path)) return {}
@@ -61,28 +39,6 @@ function ensureDir(path) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
 }
 
-// Merge the capture Stop hook into a Codex hooks.json object. Pure + idempotent: drops any prior
-// cortex capture entry (old token / old path / old pinned version) before appending the current one,
-// so re-running never duplicates and never leaves a stale version pinned behind a live one.
-// Mirrors the Claude Stop-hook merge in step 2 below, minus the SessionStart/PreCompact hooks Codex
-// doesn't support (confirmed: Codex's hook runtime only recognizes PreToolUse/PostToolUse/PreCompact/
-// UserPromptSubmit/Stop — no SessionStart, so status/skills-repair/snapshot-context stay Claude-only).
-export function mergeCodexHooks(existing, captureCmd) {
-  const h = existing && typeof existing === 'object' ? existing : {}
-  h.hooks = h.hooks && typeof h.hooks === 'object' ? h.hooks : {}
-  h.hooks.Stop = Array.isArray(h.hooks.Stop) ? h.hooks.Stop : []
-  for (const grp of h.hooks.Stop) {
-    if (Array.isArray(grp.hooks)) {
-      grp.hooks = grp.hooks.filter((c) => !/cortex-mcp.*capture|capture-session-cloud/.test(c.command ?? ''))
-    }
-  }
-  let grp = h.hooks.Stop.find((g) => (g.matcher ?? '') === '')
-  if (!grp) { grp = { matcher: '', hooks: [] }; h.hooks.Stop.push(grp) }
-  grp.hooks = grp.hooks ?? []
-  grp.hooks.push({ type: 'command', command: captureCmd })
-  return h
-}
-
 export async function runSetup(argv, version) {
   const token = argv[0]
   if (!token || token.startsWith('-')) {
@@ -115,13 +71,7 @@ export async function runSetup(argv, version) {
       process.exit(1)
     }
     const bak = backup(claudeJson)
-    cfg.mcpServers = cfg.mcpServers ?? {}
-    cfg.mcpServers.cortex = {
-      type: 'stdio',
-      command: 'npx',
-      args: ['-y', spec],
-      env: { CORTEX_TOKEN: token },
-    }
+    cfg = mergeClaudeMcp(cfg, spec, token)
     ensureDir(claudeJson)
     writeFileSync(claudeJson, JSON.stringify(cfg, null, 2))
     log(`  ✓ MCP server → ${claudeJson}${bak ? ' (backup saved)' : ''}`)
@@ -176,72 +126,9 @@ export async function runSetup(argv, version) {
       process.exit(1)
     }
     const bak = backup(settingsJson)
-    s.hooks = s.hooks ?? {}
-    s.hooks.Stop = Array.isArray(s.hooks.Stop) ? s.hooks.Stop : []
-
-    // NO inline token — same hygiene as the Codex hook above; `capture` self-resolves from
-    // ~/.claude.json (which this setup run writes). The filter below drops the old inlined form.
-    const captureCmd = `npx -y ${spec} capture`
-    // Remove any prior cortex capture hook (idempotent: drop old token / old path forms).
-    for (const grp of s.hooks.Stop) {
-      if (Array.isArray(grp.hooks)) {
-        grp.hooks = grp.hooks.filter((h) => !/cortex-mcp.*capture|capture-session-cloud/.test(h.command ?? ''))
-      }
-    }
-    // Find or create a matcher:"" group and append.
-    let grp = s.hooks.Stop.find((g) => (g.matcher ?? '') === '')
-    if (!grp) { grp = { matcher: '', hooks: [] }; s.hooks.Stop.push(grp) }
-    grp.hooks = grp.hooks ?? []
-    grp.hooks.push({ type: 'command', command: captureCmd })
-
-    // Connected-status SessionStart hook: one line inside Claude Code itself saying whether
-    // this machine's sessions are flowing to the org (dry-run finding: silence is unreadable).
-    // `status` reads the token from ~/.claude.json, so the command carries no secret.
-    s.hooks.SessionStart = Array.isArray(s.hooks.SessionStart) ? s.hooks.SessionStart : []
-    const statusCmd = `npx -y ${spec} status`
-    for (const sg of s.hooks.SessionStart) {
-      if (Array.isArray(sg.hooks)) {
-        sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? status/.test(h.command ?? ''))
-      }
-    }
-    let sgrp = s.hooks.SessionStart.find((g) => (g.matcher ?? '') === '')
-    if (!sgrp) { sgrp = { matcher: '', hooks: [] }; s.hooks.SessionStart.push(sgrp) }
-    sgrp.hooks = sgrp.hooks ?? []
-    sgrp.hooks.push({ type: 'command', command: statusCmd })
-
-    // Skills self-heal: every session start, restore any drifted managed Cortex skill (quiet — only
-    // speaks up if it actually changed something). This is what makes the core skills "inalterable".
-    const skillsCmd = `npx -y ${spec} skills --repair --quiet`
-    for (const sg of s.hooks.SessionStart) {
-      if (Array.isArray(sg.hooks)) {
-        sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? skills/.test(h.command ?? ''))
-      }
-    }
-    sgrp.hooks.push({ type: 'command', command: skillsCmd })
-
-    const snapshotCmd = `npx -y ${spec} snapshot-context`
-    for (const sg of s.hooks.SessionStart) {
-      if (Array.isArray(sg.hooks)) {
-        sg.hooks = sg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? snapshot-context/.test(h.command ?? ''))
-      }
-    }
-    sgrp.hooks.push({ type: 'command', command: snapshotCmd })
-
-    // PreCompact "author now" reminder (③ live wiki authoring, best-effort). Merges into the PreCompact
-    // array WITHOUT clobbering other hooks (filters only prior cortex entries, then appends to the ''
-    // matcher group). A hook can't force a turn — this just nudges the session to sweep understanding
-    // into the wiki before compaction; the /log skill is the hard backstop.
-    s.hooks.PreCompact = Array.isArray(s.hooks.PreCompact) ? s.hooks.PreCompact : []
-    const precompactCmd = `npx -y ${spec} precompact`
-    for (const pg of s.hooks.PreCompact) {
-      if (Array.isArray(pg.hooks)) {
-        pg.hooks = pg.hooks.filter((h) => !/cortex-mcp(@[^ ]*)? precompact/.test(h.command ?? ''))
-      }
-    }
-    let pgrp = s.hooks.PreCompact.find((g) => (g.matcher ?? '') === '')
-    if (!pgrp) { pgrp = { matcher: '', hooks: [] }; s.hooks.PreCompact.push(pgrp) }
-    pgrp.hooks = pgrp.hooks ?? []
-    pgrp.hooks.push({ type: 'command', command: precompactCmd })
+    // Capture (Stop) + status/skills/snapshot (SessionStart) + precompact (PreCompact), idempotent
+    // merge — the same pure function the `cortex install` Claude adapter uses.
+    s = mergeClaudeSettings(s, spec)
 
     ensureDir(settingsJson)
     writeFileSync(settingsJson, JSON.stringify(s, null, 2))
@@ -291,6 +178,10 @@ export async function runSetup(argv, version) {
 // resolver — hook commands no longer inline the token. Re-exported for compatibility.
 export { readWiredToken }
 
+// Re-export the pure merge functions from their adapter homes so existing importers of setup.mjs keep
+// working and tests can assert setup uses the SAME function the install path does (byte-identity).
+export { mergeClaudeMcp, mergeClaudeSettings, mergeCodexToml, mergeCodexHooks }
+
 // `repair`: re-run the FULL setup at THIS version using the already-wired token. The one-command fix
 // for a machine set up with an older version (e.g. when skills were installed to the old nested path,
 // or the hooks are pinned to a stale version). No token argument needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.43",
+  "version": "0.9.45",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin",
     "lib",
-    "skills"
+    "skills",
+    "!lib/**/*.test.mjs"
   ],
   "engines": {
     "node": ">=18"

package/lib/docs_scan.test.mjs

@@ -1,73 +0,0 @@
-import { describe, it, expect, beforeEach } from 'bun:test'
-import { mkdtempSync, writeFileSync, mkdirSync } from 'fs'
-import { tmpdir } from 'os'
-import { join } from 'path'
-import { loadState, saveState, scanRoots, markFiles, collectMarkdown, hashContent } from './docs_scan.mjs'
-
-const tmp = () => mkdtempSync(join(tmpdir(), 'docs-scan-'))
-
-describe('state round-trip', () => {
-  it('missing/corrupt state loads as empty and saves back', () => {
-    const dir = tmp()
-    const path = join(dir, 'nested', 'docs-sync.json')
-    expect(loadState(path)).toEqual({ version: 1, roots: [], files: {} })
-    const s = { version: 1, roots: ['/a'], files: { '/a/x.md': { hash: 'h', markedAt: 't' } } }
-    saveState(s, path)
-    expect(loadState(path)).toEqual(s)
-    writeFileSync(path, '{not json')
-    expect(loadState(path)).toEqual({ version: 1, roots: [], files: {} })
-  })
-})
-
-describe('collectMarkdown skip rules', () => {
-  let root
-  beforeEach(() => {
-    root = tmp()
-    writeFileSync(join(root, 'spec.md'), '# spec')
-    writeFileSync(join(root, 'notes.txt'), 'not md')
-    writeFileSync(join(root, 'old.md.bak'), 'backup')
-    mkdirSync(join(root, 'node_modules', 'pkg'), { recursive: true })
-    writeFileSync(join(root, 'node_modules', 'pkg', 'README.md'), 'dep readme')
-    mkdirSync(join(root, '.git'))
-    writeFileSync(join(root, '.git', 'x.md'), 'git internals')
-    mkdirSync(join(root, 'sub'))
-    writeFileSync(join(root, 'sub', 'plan.md'), '# plan')
-    writeFileSync(join(root, 'big.md'), 'x'.repeat(256 * 1024 + 1))
-  })
-  it('finds nested .md, skips node_modules/.git/.bak/non-md/oversize', () => {
-    const found = collectMarkdown(root)
-    expect(found).toEqual([join(root, 'spec.md'), join(root, 'sub', 'plan.md')])
-  })
-})
-
-describe('scan + mark lifecycle', () => {
-  it('new → pending; mark → clean; edit → changed; re-mark → clean', () => {
-    const root = tmp()
-    const doc = join(root, 'design.md')
-    writeFileSync(doc, 'v1')
-    const state = { version: 1, roots: [root], files: {} }
-
-    let r = scanRoots(state)
-    expect(r.pending).toEqual([{ path: doc, status: 'new' }])
-
-    const m = markFiles(state, [doc], '2026-07-02T00:00:00Z')
-    expect(m.marked).toEqual([doc])
-    expect(state.files[doc].hash).toBe(hashContent('v1'))
-    expect(scanRoots(state).pending).toEqual([])
-
-    writeFileSync(doc, 'v2')
-    r = scanRoots(state)
-    expect(r.pending).toEqual([{ path: doc, status: 'changed' }])
-
-    markFiles(state, [doc])
-    expect(scanRoots(state).pending).toEqual([])
-  })
-  it('mark of an unreadable file reports missing and records nothing', () => {
-    const state = { version: 1, roots: [], files: {} }
-    const gone = join(tmp(), 'nope.md')
-    const m = markFiles(state, [gone])
-    expect(m.marked).toEqual([])
-    expect(m.missing).toEqual([gone])
-    expect(state.files[gone]).toBeUndefined()
-  })
-})

package/lib/grep_cli.test.mjs

@@ -1,42 +0,0 @@
-import { describe, it, expect } from 'bun:test'
-import { parseGrepArgs, formatGrepHits } from './grep_cli.mjs'
-
-describe('parseGrepArgs', () => {
-  it('joins free terms into the query, defaults substring', () => {
-    expect(parseGrepArgs(['hello', 'world'])).toEqual({ query: 'hello world', mode: 'substring', max: undefined })
-  })
-  it('honors --mode fts and --fts', () => {
-    expect(parseGrepArgs(['q', '--mode', 'fts']).mode).toBe('fts')
-    expect(parseGrepArgs(['--fts', 'q']).mode).toBe('fts')
-    expect(parseGrepArgs(['q', '--mode', 'bogus']).mode).toBe('substring')
-  })
-  it('parses --max as an integer, ignores non-numeric', () => {
-    expect(parseGrepArgs(['q', '--max', '25']).max).toBe(25)
-    expect(parseGrepArgs(['q', '--max', 'abc']).max).toBeUndefined()
-  })
-  it('keeps the query when flags are interleaved', () => {
-    expect(parseGrepArgs(['foo', '--max', '5', 'bar']).query).toBe('foo bar')
-  })
-})
-
-describe('formatGrepHits', () => {
-  it('reports no matches', () => {
-    expect(formatGrepHits({ hits: [] }, 'xyz')).toBe('No matches for "xyz".')
-    expect(formatGrepHits({}, 'xyz')).toBe('No matches for "xyz".')
-  })
-  it('renders ASCII hit lines with heading, tier, snippet, links', () => {
-    const out = formatGrepHits(
-      { hits: [{ title: 'Acme', heading: 'Current state', tier: 'accessible', snippet: 'big   deal', links: ['Bob', 'Q3'] }] },
-      'deal',
-    )
-    expect(out).toContain('1 match for "deal":')
-    expect(out).toContain('- Acme > Current state [accessible]')
-    expect(out).toContain('    big deal')
-    expect(out).toContain('    -> [[Bob]] [[Q3]]')
-  })
-  it('is ASCII-only', () => {
-    const out = formatGrepHits({ hits: [{ title: 'X', heading: 'H', tier: 'scoped', snippet: 's', links: ['L'] }] }, 'q')
-    // eslint-disable-next-line no-control-regex
-    expect(/^[\x00-\x7F]*$/.test(out)).toBe(true)
-  })
-})

package/lib/imessage_send.test.mjs

@@ -1,35 +0,0 @@
-import { test, expect } from 'bun:test'
-import { decideSend, loadSendAllowlist, phoneKey } from './imessage_send.mjs'
-
-const allow = loadSendAllowlist('+18015551234, mom@example.com')
-
-test('draft-by-default: no send flag → draft, never sends (D3)', () => {
-  const d = decideSend({ recipient: '+18015551234', message: 'hi', send: false, allowlist: allow, confirmSecret: null })
-  expect(d.action).toBe('draft')
-})
-
-test('allowlisted recipient + send:true → send (D10)', () => {
-  expect(decideSend({ recipient: '+1 (801) 555-1234', message: 'hi', send: true, allowlist: allow, confirmSecret: null }).action).toBe('send')
-  expect(decideSend({ recipient: 'MOM@example.com', message: 'hi', send: true, allowlist: allow, confirmSecret: null }).action).toBe('send')
-})
-
-test('off-list recipient + send:true, no secret → BLOCKED (D10 prompt-injection guard)', () => {
-  const d = decideSend({ recipient: '+19998887777', message: 'hi', send: true, allowlist: allow, confirmSecret: null })
-  expect(d.action).toBe('blocked')
-})
-
-test('off-list recipient sends only with the correct out-of-band confirm secret', () => {
-  expect(decideSend({ recipient: '+19998887777', message: 'hi', send: true, confirm: 'wrong', allowlist: allow, confirmSecret: 'sesame' }).action).toBe('blocked')
-  expect(decideSend({ recipient: '+19998887777', message: 'hi', send: true, confirm: 'sesame', allowlist: allow, confirmSecret: 'sesame' }).action).toBe('send')
-})
-
-test('empty recipient/message is blocked', () => {
-  expect(decideSend({ recipient: '', message: 'hi', send: true, allowlist: allow, confirmSecret: null }).action).toBe('blocked')
-  expect(decideSend({ recipient: '+18015551234', message: '  ', send: true, allowlist: allow, confirmSecret: null }).action).toBe('blocked')
-})
-
-test('phoneKey + allowlist normalization', () => {
-  expect(phoneKey('+1 (801) 555-1234')).toBe('8015551234')
-  expect(allow.has('8015551234')).toBe(true)
-  expect(allow.has('mom@example.com')).toBe(true)
-})

package/lib/redact.test.mjs

@@ -1,88 +0,0 @@
-import { test, expect } from 'bun:test'
-import { redactSecrets } from './redact.mjs'
-
-// The 2026-06-22 finding: a Claude Code login token (sk-ant-oat01-…) was sitting inlined
-// in a Stop-hook command and could ride a transcript tail to the org. Capture must never
-// transmit a credential. These assert known secret shapes are stripped — and that ordinary
-// prose / record UUIDs are left intact (no false positives that would mangle real content).
-
-test('redacts an Anthropic OAuth (Claude Code login) token', () => {
-  const s = 'CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-oyo53qZ8m_WSrYZU8rrpWrxmgtbO1T8hSOhhpicMqeZ4Ixtwzbj0qwb in the hook'
-  const out = redactSecrets(s)
-  expect(out).not.toContain('sk-ant-oat01-oyo53qZ8m')
-  expect(out).toContain('[REDACTED:anthropic-oauth]')
-})
-
-test('redacts a range of credential shapes', () => {
-  const cases = [
-    ['sk-ant-api03-' + 'a'.repeat(40), 'anthropic-key'],
-    ['sk-proj-' + 'b'.repeat(40), 'openai'],
-    ['sk-' + 'c'.repeat(40), 'openai'],
-    ['ghp_' + 'd'.repeat(36), 'github'],
-    ['github_pat_' + 'e'.repeat(30), 'github-pat'],
-    ['AKIA' + 'ABCDEFGHIJKLMNOP', 'aws-akid'],
-    ['AIza' + 'f'.repeat(35), 'google'],
-    ['xoxb-' + '1234567890-abcdef', 'slack'],
-    ['eyJ' + 'a'.repeat(20) + '.' + 'b'.repeat(20) + '.' + 'c'.repeat(20), 'jwt'],
-  ]
-  for (const [secret, tag] of cases) {
-    const out = redactSecrets(`token: ${secret} end`)
-    expect(out).toContain(`[REDACTED:${tag}]`)
-    expect(out).not.toContain(secret)
-  }
-})
-
-test('redacts a Bearer token but keeps the scheme', () => {
-  const out = redactSecrets('Authorization: Bearer abcdef0123456789ABCDEFxyz')
-  expect(out).toBe('Authorization: Bearer [REDACTED]')
-})
-
-test('redacts a PEM private key block', () => {
-  const out = redactSecrets('-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----')
-  expect(out).toContain('[REDACTED:private-key]')
-  expect(out).not.toContain('MIIE')
-})
-
-test('leaves ordinary prose and record UUIDs untouched', () => {
-  const prose = 'Fixed the ingest latency; record 5203eacd-321b-43f7-bae2-4d6e7cae96ab landed in ~0.3s.'
-  expect(redactSecrets(prose)).toBe(prose)
-})
-
-// The 2026-07-02 finding: a grep of ~/.codex/hooks.json printed the live CORTEX_TOKEN (a bare
-// UUID — no pattern above catches those) into a transcript. The inline form is gone from hooks
-// (capture self-resolves now), but transcripts can still carry config lines from ANY tool read.
-test('redacts CORTEX_TOKEN in env-assignment and TOML/JSON forms', () => {
-  const uuid = 'ee0455d0-49bd-4141-984d-ece9311f9407'
-  const cases = [
-    `CORTEX_TOKEN=${uuid} npx -y @theronap/cortex-mcp@latest capture`,   // legacy hook command
-    `"CORTEX_TOKEN": "${uuid}"`,                                          // ~/.claude.json
-    `CORTEX_TOKEN = "${uuid}"`,                                           // config.toml
-  ]
-  for (const s of cases) {
-    const out = redactSecrets(s)
-    expect(out).toContain('[REDACTED:cortex-token]')
-    expect(out).not.toContain(uuid)
-  }
-})
-
-test('redacts generic secret-shaped env assignments', () => {
-  const out = redactSecrets('export SUPABASE_SERVICE_SECRET=abcDEF0123456789xyz && run')
-  expect(out).toBe('export SUPABASE_SERVICE_SECRET=[REDACTED:env] && run')
-  const out2 = redactSecrets('MY_API_KEY: "0123456789abcdef0123"')
-  expect(out2).toContain('[REDACTED:env]')
-})
-
-test('generic env pattern leaves short placeholders and prose intact', () => {
-  const cases = [
-    'set YOUR_TOKEN=xxx in the env',                    // short placeholder value
-    'the CORTEX_TOKEN is stored in ~/.claude.json',     // prose, no assignment value
-    'record 5203eacd-321b-43f7-bae2-4d6e7cae96ab',      // bare UUID, no key name
-  ]
-  for (const s of cases) expect(redactSecrets(s)).toBe(s)
-})
-
-test('handles empty / non-string input safely', () => {
-  expect(redactSecrets('')).toBe('')
-  expect(redactSecrets(null)).toBe(null)
-  expect(redactSecrets(undefined)).toBe(undefined)
-})

package/lib/skills.test.mjs

@@ -1,39 +0,0 @@
-import { describe, it, expect } from 'bun:test'
-import { planOrgInstall } from './skills.mjs'
-
-describe('planOrgInstall — the collision + validity gate', () => {
-  it('installs valid served skills', () => {
-    const { install, skipped } = planOrgInstall(
-      [{ name: 'deploy-runbook', body_md: '---\nname: deploy-runbook\n---\nbody' }],
-      ['cortex-log', 'cortex-context'],
-    )
-    expect(install).toEqual([{ name: 'deploy-runbook', source: '---\nname: deploy-runbook\n---\nbody' }])
-    expect(skipped).toEqual([])
-  })
-  it('bundled core skills win name collisions (org can never shadow cortex-log)', () => {
-    const { install, skipped } = planOrgInstall(
-      [{ name: 'cortex-log', body_md: 'evil override' }],
-      ['cortex-log'],
-    )
-    expect(install).toEqual([])
-    expect(skipped[0]).toMatchObject({ name: 'cortex-log' })
-  })
-  it('drops invalid names (path tricks, uppercase, empty) and empty bodies', () => {
-    const { install, skipped } = planOrgInstall(
-      [
-        { name: '../escape', body_md: 'x' },
-        { name: 'UPPER', body_md: 'x' },
-        { name: 'ok-name', body_md: '   ' },
-        { name: '', body_md: 'x' },
-        { name: 'fine', body_md: 'x' },
-      ],
-      [],
-    )
-    expect(install).toEqual([{ name: 'fine', source: 'x' }])
-    expect(skipped.length).toBe(4)
-  })
-  it('tolerates a malformed served list', () => {
-    expect(planOrgInstall(null, []).install).toEqual([])
-    expect(planOrgInstall([null, {}, { name: 'a' }], []).install).toEqual([])
-  })
-})