@theronap/cortex-mcp 0.9.84 → 0.9.86

package/bin/cortex-mcp.mjs

@@ -50,8 +50,9 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  doctor          live health check — confirm your token works (no restart needed)\n` +
     `  status          one-line connected/not-connected check (used by the SessionStart hook)\n` +
     `  use-brain [<brain>]    where your session captures are saved — no arg shows the current setting\n` +
-    `  skills          install/repair the managed Agnoclast skills — bundled + org-published (also wired by setup)\n` +
-    `  skills push <file>     publish a SKILL.md to your org (owner/manager/admin)\n` +
+    `  skills [sync]          install/repair bundled, org, and private cross-editor skills\n` +
+    `  skills import --from claude  import all local Claude Code skills into your private library\n` +
+    `  skills push <file> [--brain <name>]  publish a SKILL.md to your org (owner/manager/admin)\n` +
     `  docs-scan       detect new/changed local docs pending Agnoclast authoring (used by /cortex-author-docs)\n` +
     `  graphify-sync [path] [--brain <name-or-id>]  rebuild the local code graph + log a timeline event\n` +
     `  snapshot-context save the exact startup context Agnoclast served to a local snapshot\n` +

package/lib/editors/codex.mjs

@@ -70,7 +70,7 @@ export default {
     promptTimeInjection: true,
     sessionStart: false,
     captureHook: true,
-    skillDir: null,
+    skillDir: '~/.codex/skills',
     docTrigger: 'stop-hook',
   },
 

package/lib/editors/cursor.mjs

@@ -32,7 +32,7 @@ export default {
     promptTimeInjection: false,
     sessionStart: false,
     captureHook: true,           // ~/.cursor/hooks/cortex-cursor.mjs
-    skillDir: null,              // Cursor rules/commands dir — revisit in Pillar 2
+    skillDir: '~/.cursor/skills', // Flat SKILL.md directory verified on the supported Cursor build.
     docTrigger: 'hook',
   },
 

package/lib/setup.mjs

@@ -141,15 +141,16 @@ export async function runSetup(argv, version) {
     process.exit(1)
   }
 
-  // ── 3. Managed skills — installed flat into every agent CLI present (Claude + Codex) ──
-  // Bundled first (sync, network-free), then the org-published set (fail-soft pull), so a fresh
-  // seat has its org's skills at first session, not second. CORTEX_TOKEN is in env for the pull
-  // only if the caller exported it; syncOrgSkills falls back to the token this setup just wired.
+  // ── 3. Managed skills — installed flat into every compatible editor ──────────────────────────
+  // Bundled first (sync, network-free), then org + private served sets (fail-soft pulls), so a
+  // fresh seat has its skills at first session, not second. CORTEX_TOKEN is in env for the pull
+  // only if the caller exported it; each sync falls back to the token this setup just wired.
   try {
     installSkills({ quiet: false })
-    const { syncOrgSkills } = await import('./skills.mjs')
+    const { syncOrgSkills, syncPersonalSkills } = await import('./skills.mjs')
     process.env.CORTEX_TOKEN = process.env.CORTEX_TOKEN || token
     await syncOrgSkills({ quiet: false })
+    await syncPersonalSkills({ quiet: false })
   } catch (e) {
     // Non-fatal: a skills hiccup must never block the core connection. Repair runs each session.
     log(`  ⚠ skills install skipped: ${e.message} (will retry on next session)`)

package/lib/skills.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'url'
 
 // Managed Agnoclast skills.
 //
-// Two sources, one install pipeline:
+// Three sources, one install pipeline:
 //   1. BUNDLED — shipped inside this package (cortex-log, cortex-context, cortex-author-docs).
 //      Inalterable: canonical content always wins; user edits are backed up + restored.
 //   2. ORG-PUBLISHED — rows in the org's `org_skills` table (documentation-ingestion-spec.md
@@ -13,6 +13,9 @@ import { fileURLToPath } from 'url'
 //      SessionStart `skills --repair` hook pulls + installs it here. Bundled names WIN collisions,
 //      so an org can never shadow a core skill. The pull is fail-soft (offline → last-good cache
 //      at ~/.cortex/org-skills-cache.json → skip), because SessionStart must never break.
+//   3. PERSONAL — rows in `personal_skills`, keyed by auth_id. These are private to one person and
+//      are projected into every compatible editor on their machines. Personal wins an org collision
+//      on that person's machine; bundled core still wins every collision.
 //
 // Installed into EVERY agent CLI present on the machine, at the flat layout each one discovers:
 //   ~/.claude/skills/<name>/SKILL.md   (Claude Code)
@@ -30,13 +33,16 @@ import { fileURLToPath } from 'url'
 const HERE = dirname(fileURLToPath(import.meta.url))
 const BUNDLED = join(HERE, '..', 'skills') // packages/cortex-mcp/skills/<name>/SKILL.md
 const ORG_CACHE = join(homedir(), '.cortex', 'org-skills-cache.json')
+const PERSONAL_CACHE = join(homedir(), '.cortex', 'personal-skills-cache.json')
 const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/ // mirrors the org_skills check; also blocks path tricks
 
-// Agent CLIs we install skills into. Claude is primary; Codex is included whenever it's present.
-// Both use the same flat <cli>/skills/<name>/SKILL.md discovery layout.
+// Editor skill roots with the compatible flat SKILL.md discovery layout. Cursor's path was verified
+// on-machine before declaring it supported; Antigravity has no documented skill surface yet, so we
+// deliberately do not fabricate one.
 const CLIS = [
   { id: 'Claude Code', dir: join(homedir(), '.claude') },
   { id: 'Codex', dir: join(homedir(), '.codex') },
+  { id: 'Cursor', dir: join(homedir(), '.cursor') },
 ]
 
 // djb2 — tiny, dependency-free content fingerprint for the manifest (drift detection, not security).
@@ -196,6 +202,25 @@ export function planOrgInstall(served, bundledNames) {
   return { install, skipped }
 }
 
+// Personal skills share the same validation and bundled-collision rule as org skills, but never use
+// the cross-brain collision rule: their auth_id uniqueness means only one personal body can exist per
+// name. Keeping this pure makes the precedence contract testable without touching a real home dir.
+export function planPersonalInstall(served, bundledNames) {
+  const bundled = new Set(bundledNames)
+  const install = []
+  const skipped = []
+  const seen = new Set()
+  for (const s of served ?? []) {
+    const name = (s?.name ?? '').trim()
+    if (!NAME_RE.test(name) || typeof s?.body_md !== 'string' || !s.body_md.trim()) { skipped.push({ name: name || '(unnamed)', why: 'invalid' }); continue }
+    if (bundled.has(name)) { skipped.push({ name, why: 'collides with a bundled core skill' }); continue }
+    if (seen.has(name)) { skipped.push({ name, why: 'duplicate personal skill' }); continue }
+    seen.add(name)
+    install.push({ name, source: s.body_md })
+  }
+  return { install, skipped }
+}
+
 /**
  * Pull the org's published skills and install them beside the bundled ones. FAIL-SOFT by design:
  * no token → skip; fetch failure → last-good cache; nothing → skip. SessionStart must never break.
@@ -236,7 +261,10 @@ export async function syncOrgSkills(opts = {}) {
 
   const { install, skipped } = planOrgInstall(served, bundledSkills().map((s) => s.name))
   summary.skipped = skipped
-  const prevNames = Array.isArray(cache?.installed) ? cache.installed : []
+  // Only a cache written by this personal-sync implementation owns local files it may retire. An
+  // older/cache-shaped-alike file is not proof of ownership; treating it as one deleted source
+  // skills that had not yet been accepted by the server. First sync after an upgrade is additive.
+  const prevNames = cache?.version === 1 && Array.isArray(cache?.installed) ? cache.installed : []
   const currentNames = install.map((s) => s.name)
   const removeNames = prevNames.filter((n) => !currentNames.includes(n))
 
@@ -265,6 +293,76 @@ export async function syncOrgSkills(opts = {}) {
   return summary
 }
 
+/**
+ * Pull the caller's personal skill library and project it into every compatible local editor.
+ * It is deliberately fail-soft for the same reason as org sync: a network outage must not break a
+ * session start. A personal skill wins an unpinned org skill by being installed after org sync.
+ */
+export async function syncPersonalSkills(opts = {}) {
+  const quiet = !!opts.quiet
+  const log = (m) => { if (!quiet) process.stdout.write(m + '\n') }
+  const summary = { installed: [], repaired: [], removed: [], skipped: [], source: 'none' }
+  const { resolveBase, readWiredToken, fetchCortex } = await import('./diagnose.mjs')
+  const token = process.env.CORTEX_TOKEN || readWiredToken()
+  if (!token) { log('  · personal skills: no token wired — skipped'); return summary }
+
+  let cache = null
+  try { cache = JSON.parse(readFileSync(PERSONAL_CACHE, 'utf8')) } catch { /* none */ }
+  let served = null
+  try {
+    const res = await fetchCortex(`${resolveBase(process.env.CORTEX_URL)}/api/personal-skills`, {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+    if (res.ok) {
+      served = (await res.json())?.skills ?? []
+      summary.source = 'server'
+    } else {
+      log(`  · personal skills: server said ${res.status} — using last-good cache. Run \`doctor\` if this persists.`)
+    }
+  } catch { /* fall through to cache */ }
+  if (!served && Array.isArray(cache?.skills)) { served = cache.skills; summary.source = 'cache' }
+  if (!served) { log('  · personal skills: unreachable and no cache — skipped'); return summary }
+
+  const bundledNames = bundledSkills().map((s) => s.name)
+  const { install, skipped } = planPersonalInstall(served, bundledNames)
+  summary.skipped = skipped
+  const prevNames = Array.isArray(cache?.installed) ? cache.installed : []
+  const currentNames = install.map((s) => s.name)
+  const retiredNames = prevNames.filter((n) => !currentNames.includes(n))
+
+  // If a personal override was disabled, put back a cached org skill of that name rather than
+  // deleting it. The normal sync sequence has already refreshed ORG_CACHE before this function.
+  let orgCache = null
+  try { orgCache = JSON.parse(readFileSync(ORG_CACHE, 'utf8')) } catch { /* no org fallback */ }
+  const { install: orgInstall } = planOrgInstall(orgCache?.skills, bundledNames)
+  const orgByName = new Map(orgInstall.map((s) => [s.name, s]))
+  const fallback = retiredNames.map((name) => orgByName.get(name)).filter(Boolean)
+  const removeNames = retiredNames.filter((name) => !orgByName.has(name))
+
+  for (const cli of CLIS.filter((c) => existsSync(c.dir))) {
+    // Fallbacks first, personal second: personal > org, but bundled was installed before either.
+    const r = installInto(join(cli.dir, 'skills'), [...fallback, ...install], { removeNames })
+    summary.installed.push(...r.installed)
+    summary.repaired.push(...r.repaired)
+    summary.removed.push(...r.removed)
+  }
+  if (summary.source === 'server') {
+    ensureDir(dirname(PERSONAL_CACHE))
+    writeFileSync(PERSONAL_CACHE, JSON.stringify({ version: 1, fetchedAt: new Date().toISOString(), skills: served, installed: currentNames }, null, 2))
+  }
+
+  const changed = [...new Set([...summary.installed, ...summary.repaired])]
+  if (changed.length || summary.removed.length) {
+    const bits = []
+    if (changed.length) bits.push(`synced ${changed.join(', ')}`)
+    if (summary.removed.length) bits.push(`removed ${summary.removed.join(', ')}`)
+    process.stdout.write(`Agnoclast: personal skills — ${bits.join('; ')}${summary.source === 'cache' ? ' (offline cache)' : ''}.\n`)
+  } else if (!quiet) {
+    log(`  ✓ personal skills up to date (${currentNames.length} private${skipped.length ? `, ${skipped.length} skipped` : ''})`)
+  }
+  return summary
+}
+
 // Render a failed push. THE SERVER ALREADY ANSWERED THE QUESTION — brain_choice_response.ts builds a
 // body carrying a full `message` plus every brain's NAME, PAGE COUNT and SAMPLE TITLES, explicitly so
 // the caller can choose "by what each one HOLDS, not by which name sounds related". This function
@@ -355,10 +453,83 @@ export async function runSkillsPush(argv) {
   }
 }
 
+export function discoverSkillFiles(root) {
+  if (!root || !existsSync(root)) return []
+  const out = []
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+      const child = join(dir, entry.name)
+      const skill = join(child, 'SKILL.md')
+      if (existsSync(skill)) out.push(skill)
+      walk(child)
+    }
+  }
+  walk(root)
+  // Prefer a direct skill over an equally named nested vendor copy. This gives a user override
+  // priority while still discovering bundled sub-skills such as gstack's long-form workflows.
+  return out.sort((a, b) => {
+    const depth = (path) => path.slice(root.length).split('/').filter(Boolean).length
+    return depth(a) - depth(b) || a.localeCompare(b)
+  })
+}
+
+// `skills import --from claude` is the deliberate migration command. It uploads only the user's
+// skill bodies to their private library, then projects the served result; it never publishes to an
+// organization and it never treats a local copy as proof that server sync worked.
+export async function runSkillsImport(argv) {
+  if (argv.length !== 2 || argv[0] !== '--from' || argv[1] !== 'claude') {
+    process.stderr.write('Usage: skills import --from claude\n')
+    return 1
+  }
+  const { resolveBase, readWiredToken, fetchCortex } = await import('./diagnose.mjs')
+  const token = process.env.CORTEX_TOKEN || readWiredToken()
+  if (!token) { process.stderr.write('No Agnoclast token wired — run setup first.\n'); return 1 }
+  const files = discoverSkillFiles(join(homedir(), '.claude', 'skills'))
+  if (!files.length) { process.stderr.write('No Claude Code SKILL.md files found.\n'); return 1 }
+
+  const base = resolveBase(process.env.CORTEX_URL)
+  let imported = 0
+  const skipped = []
+  const seen = new Set()
+  for (const file of files) {
+    const body_md = readFileSync(file, 'utf8')
+    const name = frontmatterName(body_md, '').toLowerCase()
+    if (!NAME_RE.test(name)) { skipped.push(`${file}: invalid frontmatter name`); continue }
+    if (seen.has(name)) { skipped.push(`${file}: duplicate name ${name}`); continue }
+    seen.add(name)
+    try {
+      const res = await fetchCortex(`${base}/api/personal-skills`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name, body_md, enabled: true }),
+      })
+      if (!res.ok) {
+        const response = await res.json().catch(() => ({}))
+        skipped.push(`${file}: ${response.error ?? `HTTP ${res.status}`}`)
+        continue
+      }
+      imported++
+    } catch (e) {
+      skipped.push(`${file}: network error: ${e.message}`)
+    }
+  }
+  process.stdout.write(`Agnoclast: imported ${imported}/${files.length} Claude Code skills into your private library.\n`)
+  for (const reason of skipped) process.stdout.write(`  · skipped ${reason}\n`)
+  if (imported) await syncPersonalSkills({ quiet: false })
+  return skipped.length ? 1 : 0
+}
+
 // CLI entry: `cortex-mcp skills [--repair] [--quiet] | skills push …`. (--repair and plain install
 // are the same idempotent operation; --repair is just the name the SessionStart hook uses for intent.)
 export async function runSkills(argv = []) {
   if (argv[0] === 'push') return runSkillsPush(argv.slice(1))
+  if (argv[0] === 'import') return runSkillsImport(argv.slice(1))
+  const syncing = argv[0] === 'sync'
+  if (argv[0] && !syncing && argv[0] !== '--repair' && argv[0] !== '--quiet') {
+    process.stderr.write('Usage: skills [sync|--repair] | skills import --from claude | skills push <SKILL.md> [--brain <name>]\n')
+    return 1
+  }
 
   const quiet = argv.includes('--quiet')
   if (!quiet) process.stdout.write('\nAgnoclast skills — installing managed skills…\n')
@@ -369,6 +540,9 @@ export async function runSkills(argv = []) {
       process.stdout.write(`  ✓ Up to date in ${r.targets.join(' + ')} (${[...new Set(r.unchanged)].join(', ') || 'none'}).\n`)
     }
   }
-  if (r.targets.length) await syncOrgSkills({ quiet })
+  if (r.targets.length) {
+    await syncOrgSkills({ quiet })
+    await syncPersonalSkills({ quiet })
+  }
   return 0
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theronap/cortex-mcp",
-  "version": "0.9.84",
+  "version": "0.9.86",
   "description": "Connect your AI assistant to Cortex — your org's projects, activity, gaps, and directives, scoped to you.",
   "type": "module",
   "bin": {