@theronap/cortex-mcp 0.9.44 → 0.9.46

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` +
@@ -49,6 +50,7 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  skills          install/repair the managed Cortex skills — bundled + org-published (also wired by setup)\n` +
     `  skills push <file>     publish a SKILL.md to your org (owner/manager/admin)\n` +
     `  docs-scan       detect new/changed local docs pending Cortex authoring (used by /cortex-author-docs)\n` +
+    `  graphify-sync [path]  rebuild the local code graph (graphify) + log an evidence-tier timeline event\n` +
     `  snapshot-context save the exact startup context Cortex served to a local snapshot\n` +
     `  capture         Stop-hook capturer (invoked by Claude Code)\n` +
     `  ingest-folder <path>   ingest a local markdown folder as your authored records\n` +
@@ -70,6 +72,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
@@ -120,6 +129,13 @@ if (cmd === 'setup') {
   process.exitCode = await runGrep(rest)
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
+} else if (cmd === 'graphify-sync') {
+  // Local producer: `graphify update` + log an evidence-tier timeline event. Run from a cron/
+  // launchd job per repo, not a git hook (shared-checkout hazard — see reference memory).
+  const { runGraphifySync } = await import('../lib/graphify_sync.mjs')
+  process.exitCode = await runGraphifySync(rest)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
 } else if (cmd === 'snapshot-context') {
   const { runSnapshotContext } = await import('../lib/context_log.mjs')
   process.exitCode = await runSnapshotContext()

package/lib/code_graph_cli.mjs

@@ -0,0 +1,59 @@
+import { spawnSync } from 'child_process'
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+// Thin local wrapper around the `graphify` CLI's read-only query subcommands. Deliberately NOT a
+// fetchCortex client like grep/read_page: this is LOCAL-MACHINE data (a tree-sitter AST graph of
+// whatever repo the session's cwd happens to be in), not org-shared Cortex content, and it never
+// becomes the wiki graph — see cortex-wiki-primary-spec (structural/extracted data is evidence,
+// never auto-promoted into authored pages). No LLM, no network call; graphify already built the
+// graph on disk, this just queries it.
+
+function graphPath(cwd) {
+  return join(cwd, 'graphify-out', 'graph.json')
+}
+
+function hasGraphifyBinary() {
+  const r = spawnSync('graphify', ['--version'], { encoding: 'utf8', timeout: 10_000 })
+  return !r.error && r.status === 0
+}
+
+// Pure-ish: build the argv for a given action, or return an error string if params are missing.
+export function buildArgs({ action, question, from, to, node }) {
+  if (action === 'path') {
+    if (!from || !to) return { error: 'action:"path" requires both "from" and "to".' }
+    return { args: ['path', from, to] }
+  }
+  if (action === 'explain') {
+    if (!node) return { error: 'action:"explain" requires "node".' }
+    return { args: ['explain', node] }
+  }
+  if (!question) return { error: 'action:"query" requires "question".' }
+  return { args: ['query', question] }
+}
+
+// Effectful: run one of graphify's query/path/explain subcommands against the graph already built
+// for `cwd`. Returns { ok, text } — never throws, always something readable to hand back to the model.
+export function runCodeGraphQuery({ action, question, from, to, node }, cwd = process.cwd()) {
+  if (!existsSync(graphPath(cwd))) {
+    return {
+      ok: false,
+      text: `No code graph found at ${graphPath(cwd)}. Run the graphify skill (\`/graphify .\`) in this repo first to build one.`,
+    }
+  }
+  if (!hasGraphifyBinary()) {
+    return {
+      ok: false,
+      text: 'graphify CLI not found on PATH. Install it with `uv tool install graphifyy` (or `pipx install graphifyy`), then run the graphify skill to build a graph.',
+    }
+  }
+  const built = buildArgs({ action, question, from, to, node })
+  if (built.error) return { ok: false, text: built.error }
+
+  const r = spawnSync('graphify', built.args, { cwd, encoding: 'utf8', timeout: 60_000, maxBuffer: 4 * 1024 * 1024 })
+  if (r.error) return { ok: false, text: `graphify failed to run: ${r.error.message}` }
+  const out = (r.stdout || '').trim()
+  const err = (r.stderr || '').trim()
+  if (r.status !== 0) return { ok: false, text: err || out || `graphify exited with status ${r.status}` }
+  return { ok: true, text: out || '(no results)' }
+}

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))
+}