@theronap/cortex-mcp 0.9.33 → 0.9.35

package/bin/cortex-mcp.mjs

@@ -45,7 +45,9 @@ if (cmd === '--help' || cmd === '-h' || cmd === 'help') {
     `  repair          re-run setup at the latest version using your existing token (no token needed)\n` +
     `  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` +
-    `  skills          install/repair the managed Cortex skills (also wired by setup)\n` +
+    `  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` +
     `  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` +
@@ -117,9 +119,17 @@ if (cmd === 'setup') {
   const { closeFetch } = await import('../lib/diagnose.mjs')
   await closeFetch()
 } else if (cmd === 'skills') {
-  // Install / repair the managed Cortex skills repository. No network — exits naturally.
+  // Install / repair the managed Cortex skills — bundled + org-published (`skills push` publishes).
+  // Org sync is network-fail-soft so the SessionStart hook stays safe offline.
   const { runSkills } = await import('../lib/skills.mjs')
   process.exitCode = await runSkills(rest)
+  const { closeFetch } = await import('../lib/diagnose.mjs')
+  await closeFetch()
+} else if (cmd === 'docs-scan') {
+  // Documentation ingestion, detection half: hash-diff registered doc roots for new/changed *.md.
+  // The cortex-author-docs skill authors the pending docs into wiki pages. No network.
+  const { runDocsScan } = await import('../lib/docs_scan.mjs')
+  process.exitCode = await runDocsScan(rest)
 } else if (cmd === 'precompact') {
   // PreCompact hook (③ live wiki authoring, best-effort): print an "author now" reminder so the session
   // sweeps its understanding into the wiki BEFORE compaction drops it. A hook cannot force a model turn

package/lib/docs_scan.mjs

@@ -0,0 +1,171 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs'
+import { createHash } from 'crypto'
+import { homedir } from 'os'
+import { join, resolve, dirname } from 'path'
+
+// Documentation ingestion — detection half (D1 of docs/documentation-ingestion-spec.md).
+//
+// Specs/plans/design docs get written to disk (repo docs/, ~/.gstack/projects/…) and never reach
+// Cortex as pages. This subcommand DETECTS new/changed markdown under registered roots by content
+// hash; the AUTHORING is done by the live session (the cortex-author-docs skill reads each pending
+// doc and calls the `author` MCP tool) — the agent is the pipe, never a raw-markdown dump.
+//
+// State is local (~/.cortex/docs-sync.json): watched roots + sha256 per pushed file. Files are
+// marked ONLY after a successful author (`--mark`), so a failed author simply stays pending.
+// No network; exits naturally (CLI-subcommand convention).
+
+const STATE_PATH = join(homedir(), '.cortex', 'docs-sync.json')
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next'])
+const MAX_BYTES = 256 * 1024
+
+export function loadState(path = STATE_PATH) {
+  try {
+    const s = JSON.parse(readFileSync(path, 'utf8'))
+    return { version: 1, roots: Array.isArray(s.roots) ? s.roots : [], files: s.files && typeof s.files === 'object' ? s.files : {} }
+  } catch {
+    return { version: 1, roots: [], files: {} }
+  }
+}
+
+export function saveState(state, path = STATE_PATH) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  writeFileSync(path, JSON.stringify(state, null, 2))
+}
+
+export const hashContent = (s) => createHash('sha256').update(s).digest('hex')
+
+// Recursively collect candidate .md files under one root, applying the skip rules.
+export function collectMarkdown(root) {
+  const out = []
+  const walk = (dir) => {
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name))
+        continue
+      }
+      if (!e.name.endsWith('.md') || e.name.endsWith('.bak.md')) continue
+      if (e.name.endsWith('.md.bak')) continue
+      const path = join(dir, e.name)
+      try { if (statSync(path).size > MAX_BYTES) continue } catch { continue }
+      out.push(path)
+    }
+  }
+  walk(root)
+  return out.sort()
+}
+
+// Diff the filesystem against state. Returns { pending: [{path, status:'new'|'changed'}], scanned }.
+export function scanRoots(state) {
+  const pending = []
+  let scanned = 0
+  for (const root of state.roots) {
+    for (const path of collectMarkdown(root)) {
+      scanned++
+      let body
+      try { body = readFileSync(path, 'utf8') } catch { continue }
+      const h = hashContent(body)
+      const prev = state.files[path]?.hash
+      if (!prev) pending.push({ path, status: 'new' })
+      else if (prev !== h) pending.push({ path, status: 'changed' })
+    }
+  }
+  return { pending, scanned }
+}
+
+// Record the CURRENT content hash for the given files (call after a successful author).
+export function markFiles(state, paths, now = new Date().toISOString()) {
+  const marked = []
+  const missing = []
+  for (const p of paths) {
+    const abs = resolve(p)
+    let body
+    try { body = readFileSync(abs, 'utf8') } catch { missing.push(abs); continue }
+    state.files[abs] = { hash: hashContent(body), markedAt: now }
+    marked.push(abs)
+  }
+  return { marked, missing }
+}
+
+// Heuristic soak guardrail (spec D5): the Robin parity experiment forbids re-syncing the local
+// brain into Cortex during the window, so warn when a root looks like the brain repo.
+const looksLikeBrain = (dir) => /\/Documents\/brain(\/|$)/.test(dir)
+
+export async function runDocsScan(argv = []) {
+  const state = loadState()
+  const out = (m) => process.stdout.write(m + '\n')
+
+  const flagIdx = (f) => argv.indexOf(f)
+
+  if (flagIdx('--roots') !== -1) {
+    if (!state.roots.length) out('No roots registered. Add one:  cortex-mcp docs-scan --add-root <dir>')
+    else state.roots.forEach((r) => out(r))
+    return 0
+  }
+
+  if (flagIdx('--add-root') !== -1) {
+    const dir = argv[flagIdx('--add-root') + 1]
+    if (!dir) { process.stderr.write('Usage: docs-scan --add-root <dir>\n'); return 1 }
+    const abs = resolve(dir)
+    if (!existsSync(abs)) { process.stderr.write(`Not a directory: ${abs}\n`); return 1 }
+    if (looksLikeBrain(abs)) {
+      out(`⚠ ${abs} looks like the local brain repo — the Robin parity soak forbids re-syncing it into Cortex.`)
+      out('  Registering anyway is on you; the cortex-author-docs skill will also warn.')
+    }
+    if (!state.roots.includes(abs)) state.roots.push(abs)
+    saveState(state)
+    out(`✓ watching ${abs} (${state.roots.length} root${state.roots.length === 1 ? '' : 's'})`)
+    return 0
+  }
+
+  if (flagIdx('--remove-root') !== -1) {
+    const dir = argv[flagIdx('--remove-root') + 1]
+    if (!dir) { process.stderr.write('Usage: docs-scan --remove-root <dir>\n'); return 1 }
+    const abs = resolve(dir)
+    state.roots = state.roots.filter((r) => r !== abs)
+    saveState(state)
+    out(`✓ removed ${abs}`)
+    return 0
+  }
+
+  if (flagIdx('--mark') !== -1) {
+    const files = argv.slice(flagIdx('--mark') + 1).filter((a) => !a.startsWith('-'))
+    if (!files.length) { process.stderr.write('Usage: docs-scan --mark <file>...\n'); return 1 }
+    const { marked, missing } = markFiles(state, files)
+    saveState(state)
+    marked.forEach((p) => out(`✓ marked ${p}`))
+    missing.forEach((p) => process.stderr.write(`✗ unreadable, not marked: ${p}\n`))
+    return missing.length ? 1 : 0
+  }
+
+  if (flagIdx('--mark-all') !== -1) {
+    // Baseline initialization: acknowledge the whole current backlog without authoring it.
+    const { pending } = scanRoots(state)
+    const { marked } = markFiles(state, pending.map((p) => p.path))
+    saveState(state)
+    out(`✓ baseline set — marked ${marked.length} doc(s) as already-known`)
+    return 0
+  }
+
+  // Default: scan and report.
+  const json = flagIdx('--json') !== -1
+  if (!state.roots.length) {
+    if (json) out(JSON.stringify({ roots: [], pending: [] }))
+    else out('No roots registered. Add one:  cortex-mcp docs-scan --add-root <dir>')
+    return 0
+  }
+  const { pending, scanned } = scanRoots(state)
+  if (json) {
+    out(JSON.stringify({ roots: state.roots, scanned, pending }, null, 2))
+    return 0
+  }
+  if (!pending.length) out(`✓ up to date — ${scanned} doc(s) scanned, nothing pending`)
+  else {
+    out(`${pending.length} doc(s) pending Cortex authoring (of ${scanned} scanned):`)
+    for (const p of pending) out(`  ${p.status === 'new' ? '+ ' : '~ '}${p.path}`)
+    out('Author them via the cortex-author-docs skill, then:  docs-scan --mark <file>...')
+  }
+  return 0
+}

package/lib/docs_scan.test.mjs

@@ -0,0 +1,73 @@
+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/server.mjs

@@ -333,7 +333,14 @@ export async function runServer(version) {
       const day = (d) => (d ? String(d).slice(0, 10) : '')
       const blocks = page.tiers.map((t) => {
         const secs = (t.sections ?? []).map((s) => `### ${s.heading}\n${s.body}`).join('\n\n')
-        const head = `[${t.tier}${day(t.updated_at) ? ` · authored ${day(t.updated_at)}` : ''}${t.validity && t.validity !== 'current' ? ` · ${t.validity}` : ''}${t.version ? `\nversion: ${t.version}` : ''}]`
+        // ADR-0018: a null version isn't "nothing to show" — it means this variant predates content-
+        // hash tracking (a 2026-06-29 import scar) and CANNOT be re-authored via base_version until an
+        // admin backfills it. Silently omitting the line here is exactly what sent callers into an
+        // unrecoverable base_version guessing loop; say so explicitly instead.
+        const versionLine = t.version
+          ? `\nversion: ${t.version}`
+          : `\nversion: none (this variant predates content-hash tracking — base_version writes will always fail here; ask an admin about the ADR-0018 backfill)`
+        const head = `[${t.tier}${day(t.updated_at) ? ` · authored ${day(t.updated_at)}` : ''}${t.validity && t.validity !== 'current' ? ` · ${t.validity}` : ''}${versionLine}]`
         return [head, t.summary, secs].filter(Boolean).join('\n')
       })
       let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — re-author just those sections now with \`author\` (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). Pass this page's \`version\` as base_version when you re-author — if the save comes back stale, the page changed under you: re-read, then re-author. Reading a stale page you can fix IS the trigger to fix it.`
@@ -521,22 +528,23 @@ export async function runServer(version) {
     'set_page_privacy',
     {
       title: 'Change who can see a wiki page',
-      description: 'Re-tier a wiki page you own or may edit: "accessible" (anyone in the org), "scoped" (owner + their management chain), or "confidential" (owner only, plus explicit grants). Demoting a PROJECT page also demotes its evidence records (demote-only; each record\'s owner is notified and can revert). Promotions never touch records. If the target tier already has a page, you\'ll be asked to merge via author first, then re-run with absorb=true. Org admins may demote any page, never promote.',
+      description: 'Re-tier a wiki page you own or may edit: "accessible" (anyone in the org), "scoped" (owner + their management chain), or "confidential" (owner only, plus explicit grants). Demoting a PROJECT page also demotes its evidence records (demote-only; each record\'s owner is notified and can revert). Promotions never touch records. If the target tier already has a page, merge your content into it via `author` FIRST, then read_page the target again to get its fresh version, then re-run this with absorb=true and target_version=<that version> — absorb will REJECT (not silently drop content) if target_version doesn\'t match what\'s actually there, so a merge that didn\'t really land can\'t destroy your source page. Org admins may demote any page, never promote.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).describe('the page kind'),
         name: z.string().describe('the exact page name'),
         tier: z.enum(['accessible', 'scoped', 'confidential']).describe('the new visibility tier'),
         source_tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('when the node has multiple tier variants: which one to move'),
-        absorb: z.boolean().optional().describe('after merging your content into an existing target-tier page via author: true removes your now-absorbed source variant'),
+        absorb: z.boolean().optional().describe('after merging your content into an existing target-tier page via author: true removes your now-absorbed source variant. Requires target_version.'),
+        target_version: z.string().optional().describe('REQUIRED with absorb=true — the target page\'s version, read via read_page AFTER your author() merge landed. Proves the merge actually happened before your source page is deleted; a stale or guessed value is rejected, not silently accepted.'),
       },
     },
-    async ({ kind, name, tier, source_tier, absorb }) => {
+    async ({ kind, name, tier, source_tier, absorb, target_version }) => {
       let res
       try {
         res = await fetchCortex(`${BASE}/api/brain/page-privacy`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, tier, ...(source_tier ? { source_tier } : {}), ...(absorb ? { absorb: true } : {}) }),
+          body: JSON.stringify({ kind, name, tier, ...(source_tier ? { source_tier } : {}), ...(absorb ? { absorb: true } : {}), ...(target_version ? { target_version } : {}) }),
         })
       } catch (e) {
         return { content: [{ type: 'text', text: `Could not set page privacy: ${e.message}` }] }
@@ -547,7 +555,7 @@ export async function runServer(version) {
         // surface the server's structured message verbatim so the agent can follow it.
         if (out?.error) {
           const extra = out.collision === 'readable' && out.blocking
-            ? `\nYour ${out.source?.tier} page: ${out.source?.summary ?? out.source?.title}\nExisting ${out.blocking.tier} page: ${out.blocking.summary ?? out.blocking.title}`
+            ? `\nYour ${out.source?.tier} page: ${out.source?.summary ?? out.source?.title}\nExisting ${out.blocking.tier} page (current version: ${out.blocking.version ?? 'none — this page predates content-hash tracking and cannot be re-authored via base_version; ask an admin about a backfill'}): ${out.blocking.summary ?? out.blocking.title}`
             : ''
           return { content: [{ type: 'text', text: `Could not set page privacy: ${out.error}${extra}` }] }
         }

package/lib/setup.mjs

@@ -252,8 +252,14 @@ export async function runSetup(argv, version) {
   }
 
   // ── 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.
   try {
     installSkills({ quiet: false })
+    const { syncOrgSkills } = await import('./skills.mjs')
+    process.env.CORTEX_TOKEN = process.env.CORTEX_TOKEN || token
+    await syncOrgSkills({ 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

@@ -1,12 +1,20 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync } from 'fs'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, rmSync } from 'fs'
 import { homedir } from 'os'
 import { join, dirname } from 'path'
 import { fileURLToPath } from 'url'
 
 // Managed Cortex skills.
 //
-// Cortex ships mandatory, self-healing skills (e.g. cortex-log) and installs them into EVERY agent
-// CLI present on the machine, at the flat layout each one discovers:
+// Two 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
+//      Part B). An owner/manager/admin publishes a SKILL.md once (`skills push`); every seat's
+//      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.
+//
+// Installed into EVERY agent CLI present on the machine, at the flat layout each one discovers:
 //   ~/.claude/skills/<name>/SKILL.md   (Claude Code)
 //   ~/.codex/skills/<name>/SKILL.md    (OpenAI Codex CLI — only if ~/.codex exists)
 //
@@ -14,13 +22,15 @@ import { fileURLToPath } from 'url'
 // skills as <cli>/skills/<name>/SKILL.md. An earlier layout nested them under skills/cortex/core/,
 // which is installed but INVISIBLE to discovery (the skill never appears as a slash command).
 //
-// "Inalterable" in practice: the bundled skills are the source of truth. On every install AND on
-// every Claude session start (the SessionStart --repair hook), any managed skill whose on-disk
-// content drifted is RESTORED — the user's version is backed up to SKILL.md.user-bak first, so
-// nothing is lost, but the canonical skill always wins. Identical content is a no-op.
+// "Inalterable" in practice: on every install AND on every Claude session start (the SessionStart
+// --repair hook), any managed skill whose on-disk content drifted is RESTORED — the user's version
+// is backed up to SKILL.md.user-bak first, so nothing is lost, but the canonical skill always wins.
+// Identical content is a no-op.
 
 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 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.
@@ -59,38 +69,65 @@ function bundledSkills() {
     })
 }
 
-// Install/repair all bundled skills into one CLI's skills root. Returns per-CLI change lists.
-function installInto(skillsRoot, skills) {
+// Write one skill file with the repair semantics: backup user drift, canonical wins, no-op on match.
+function writeSkillFile(dest, source) {
+  if (!existsSync(dest)) {
+    ensureDir(dirname(dest))
+    writeFileSync(dest, source)
+    return 'installed'
+  }
+  const current = readFileSync(dest, 'utf8')
+  if (current === source) return 'unchanged'
+  try { copyFileSync(dest, `${dest}.user-bak`) } catch { /* best-effort backup */ }
+  writeFileSync(dest, source)
+  return 'repaired'
+}
+
+// Install/repair a skill list into one CLI's skills root, plus remove org skills we previously
+// installed that are no longer served. Merges the manifest rather than clobbering it, so bundled
+// and org passes can run independently.
+function installInto(skillsRoot, skills, { removeNames = [] } = {}) {
   ensureDir(skillsRoot)
-  const result = { installed: [], repaired: [], unchanged: [] }
-  const manifest = { managed: [], updated_by: 'cortex-mcp', skills: {} }
+  const result = { installed: [], repaired: [], unchanged: [], removed: [] }
 
   for (const sk of skills) {
     const dest = join(skillsRoot, sk.name, 'SKILL.md')
-    manifest.managed.push(`${sk.name}/SKILL.md`)
-    manifest.skills[sk.name] = hash(sk.source)
-
-    if (!existsSync(dest)) {
-      ensureDir(dirname(dest))
-      writeFileSync(dest, sk.source)
-      result.installed.push(sk.name)
-      continue
-    }
-    const current = readFileSync(dest, 'utf8')
-    if (current === sk.source) { result.unchanged.push(sk.name); continue }
+    const status = writeSkillFile(dest, sk.source)
+    result[status].push(sk.name)
+  }
 
-    // Drift: preserve the user's version, then restore canonical.
-    try { copyFileSync(dest, `${dest}.user-bak`) } catch { /* best-effort backup */ }
-    writeFileSync(dest, sk.source)
-    result.repaired.push(sk.name)
+  for (const name of removeNames) {
+    const destDir = join(skillsRoot, name)
+    const dest = join(destDir, 'SKILL.md')
+    if (!existsSync(dest)) continue
+    try {
+      copyFileSync(dest, `${dest}.removed-bak`)
+      rmSync(dest)
+      rmSync(`${dest}.removed-bak`)
+      rmSync(destDir, { recursive: true }) // dir now holds only leftovers we created
+      result.removed.push(name)
+    } catch { /* best-effort — a stubborn dir just stays */ }
   }
 
-  writeFileSync(join(skillsRoot, '.cortex-skills.json'), JSON.stringify(manifest, null, 2))
+  // Merge manifest: keep entries from the other pass, replace ours.
+  const manifestPath = join(skillsRoot, '.cortex-skills.json')
+  let manifest = { managed: [], updated_by: 'cortex-mcp', skills: {} }
+  try { manifest = { ...manifest, ...JSON.parse(readFileSync(manifestPath, 'utf8')) } } catch { /* fresh */ }
+  for (const name of removeNames) {
+    delete manifest.skills[name]
+    manifest.managed = (manifest.managed ?? []).filter((m) => m !== `${name}/SKILL.md`)
+  }
+  for (const sk of skills) {
+    if (!manifest.managed.includes(`${sk.name}/SKILL.md`)) manifest.managed.push(`${sk.name}/SKILL.md`)
+    manifest.skills[sk.name] = hash(sk.source)
+  }
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2))
   return result
 }
 
 /**
- * Install / repair the managed Cortex skills into every agent CLI present on the machine.
+ * Install / repair the BUNDLED managed skills into every agent CLI present on the machine.
+ * Synchronous + network-free (setup calls this before any await).
  * @param {{ quiet?: boolean }} opts  quiet → only emit on actual change (for the SessionStart hook)
  * @returns {{ installed: string[], repaired: string[], unchanged: string[], targets: string[] }}
  */
@@ -123,9 +160,134 @@ export function installSkills(opts = {}) {
   return summary
 }
 
-// CLI entry: `cortex-mcp skills [--repair] [--quiet]`. (--repair and plain install are the same
-// idempotent operation; --repair is just the name the SessionStart hook uses for intent.)
+// Decide what to install from a served org-skill list: drop invalid names and bundled collisions
+// (bundled wins — core skills are inalterable). Pure, so it's unit-testable without a network.
+export function planOrgInstall(served, bundledNames) {
+  const bundled = new Set(bundledNames)
+  const install = []
+  const skipped = []
+  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 }
+    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.
+ * Also removes org skills we previously installed that are no longer served (tracked via cache).
+ */
+export async function syncOrgSkills(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('  · org skills: no token wired — skipped'); return summary }
+
+  // Previous org-installed names, so we can remove what the org deleted/disabled.
+  let cache = null
+  try { cache = JSON.parse(readFileSync(ORG_CACHE, 'utf8')) } catch { /* none */ }
+
+  let served = null
+  try {
+    const res = await fetchCortex(`${resolveBase(process.env.CORTEX_URL)}/api/skills`, {
+      headers: { Authorization: `Bearer ${token}` },
+    })
+    if (res.ok) {
+      served = (await res.json())?.skills ?? []
+      summary.source = 'server'
+    }
+  } catch { /* fall through to cache */ }
+  if (!served && Array.isArray(cache?.skills)) { served = cache.skills; summary.source = 'cache' }
+  if (!served) { log('  · org skills: unreachable and no cache — skipped'); return summary }
+
+  const { install, skipped } = planOrgInstall(served, bundledSkills().map((s) => s.name))
+  summary.skipped = skipped
+  const prevNames = Array.isArray(cache?.installed) ? cache.installed : []
+  const currentNames = install.map((s) => s.name)
+  const removeNames = prevNames.filter((n) => !currentNames.includes(n))
+
+  for (const cli of CLIS.filter((c) => existsSync(c.dir))) {
+    const r = installInto(join(cli.dir, 'skills'), install, { removeNames })
+    summary.installed.push(...r.installed)
+    summary.repaired.push(...r.repaired)
+    summary.removed.push(...r.removed)
+  }
+
+  // Persist last-good only when the server actually answered (a cache-fed run keeps the old one).
+  if (summary.source === 'server') {
+    ensureDir(dirname(ORG_CACHE))
+    writeFileSync(ORG_CACHE, JSON.stringify({ 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(`Cortex: org skills — ${bits.join('; ')}${summary.source === 'cache' ? ' (offline cache)' : ''}.\n`)
+  } else if (!quiet) {
+    log(`  ✓ org skills up to date (${currentNames.length} published${skipped.length ? `, ${skipped.length} skipped` : ''})`)
+  }
+  return summary
+}
+
+// `skills push <file>` / `skills push --disable <name>` / `skills push --enable <name>` —
+// publish or toggle an org skill (owner/manager/admin; the server enforces the role).
+async function runSkillsPush(argv) {
+  const { resolveBase, readWiredToken, fetchCortex } = await import('./diagnose.mjs')
+  const token = process.env.CORTEX_TOKEN || readWiredToken()
+  if (!token) { process.stderr.write('No Cortex token wired — run setup first.\n'); return 1 }
+  const base = resolveBase(process.env.CORTEX_URL)
+
+  let payload
+  const toggleIdx = argv.findIndex((a) => a === '--disable' || a === '--enable')
+  if (toggleIdx !== -1) {
+    const name = argv[toggleIdx + 1]
+    if (!name) { process.stderr.write(`Usage: skills push ${argv[toggleIdx]} <name>\n`); return 1 }
+    payload = { name, enabled: argv[toggleIdx] === '--enable' }
+  } else {
+    const file = argv.find((a) => !a.startsWith('-'))
+    if (!file || !existsSync(file)) { process.stderr.write('Usage: skills push <SKILL.md>  (file not found)\n'); return 1 }
+    const body_md = readFileSync(file, 'utf8')
+    const name = frontmatterName(body_md, '').toLowerCase()
+    if (!NAME_RE.test(name)) {
+      process.stderr.write(`SKILL.md needs frontmatter \`name:\` in lowercase kebab (got "${name || 'nothing'}").\n`)
+      return 1
+    }
+    payload = { name, body_md, enabled: true }
+  }
+
+  try {
+    const res = await fetchCortex(`${base}/api/skills`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+    const body = await res.json().catch(() => ({}))
+    if (!res.ok) { process.stderr.write(`✗ ${body.error ?? `HTTP ${res.status}`}\n`); return 1 }
+    process.stdout.write(
+      payload.body_md
+        ? `✓ published "${payload.name}" to your org — every seat installs it on next session start.\n`
+        : `✓ "${payload.name}" ${payload.enabled ? 'enabled' : 'disabled'}.\n`,
+    )
+    return 0
+  } catch (e) {
+    process.stderr.write(`✗ network error: ${e.message}\n`)
+    return 1
+  }
+}
+
+// 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))
+
   const quiet = argv.includes('--quiet')
   if (!quiet) process.stdout.write('\nCortex skills — installing managed skills…\n')
   const r = installSkills({ quiet })
@@ -135,5 +297,6 @@ 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 })
   return 0
 }

package/lib/skills.test.mjs

@@ -0,0 +1,39 @@
+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([])
+  })
+})

package/package.json

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

package/skills/author-docs/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: cortex-author-docs
+description: Push new/changed documentation (specs, plans, design docs) from disk into Cortex as authored wiki pages. Run after writing a spec/plan/design doc, when the user asks to sync docs to Cortex, or as part of session close-out.
+---
+
+> **Cortex-managed skill.** This file is installed and kept up to date by Cortex. Local edits are
+> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.
+
+## Why this exists
+
+Specs, plans, and design docs get written to disk (a repo's `docs/`, skill-generated design docs)
+and never reach Cortex — so the org brain misses its richest artifacts. A spec IS a page: this
+skill turns pending docs into authored wiki pages. You (the live session) are the pipe — you read
+the doc and author a synthesis. Never dump raw markdown into a page.
+
+## When to use
+
+- Right after you write or substantially update a spec/plan/design/runbook doc on disk.
+- When the user asks to push/sync docs to Cortex.
+- During session close-out (`/cortex-log` runs this as a sweep step).
+
+## Steps
+
+1. **Detect:** run `npx -y @theronap/cortex-mcp docs-scan --json`. If `pending` is empty, stop —
+   report nothing. (If no roots are registered and you just wrote docs somewhere, suggest
+   `docs-scan --add-root <dir>` to the user once; don't nag.)
+2. **Author each pending doc** (skip any you judge non-substantive — scratch notes, generated
+   output; leave them unmarked and say so):
+   - Read the file. Decide the target node: a substantial standalone doc becomes its own
+     project-kind node named by the doc's H1 title; a small note folds into its parent project's
+     page as a section. Check the namespace first (`authoring_context`) — enrich an existing node
+     rather than minting a synonym.
+   - Call `author` with a distilled summary + sections — a synthesis of what the doc establishes
+     (decisions, design, status), not a paste. Emit inline `[[links]]`: ALWAYS link up to the
+     parent project node, plus related nodes; include the `[[repo:owner/name]]` stamp when the doc
+     lives in a git repo (that joins the page to its commit timeline).
+   - **Directionality is a hard rule:** the doc page links UP to the hub; NEVER author the hub
+     page just to add a link back to a doc. Fan-in is queryable (`grep "[[hub]]"` = backlinks;
+     `read_page history:true` = the node's event ledger) — hub pages stay curated prose, and a doc
+     belongs on the hub only when a human-judged synthesis mentions it.
+3. **Mark:** after each successful `author`, run
+   `npx -y @theronap/cortex-mcp docs-scan --mark <path>`. Never mark a doc whose author failed —
+   it should stay pending for the next sweep.
+4. **Report:** one short block — each doc → the page it became (or why skipped).
+
+## Safety rules
+
+- Do NOT register or sweep the local brain repo (`~/Documents/brain`) while the Robin parity soak
+  is running — the experiment forbids re-syncing Robin into Cortex mid-window.
+- Respect tiers: if a doc is clearly personal/sensitive, author it `confidential` or ask; default
+  for work docs is the author path's normal default.
+- This skill writes wiki pages via the `author` tool only. It never sends external messages and
+  never deletes anything.

package/skills/log/SKILL.md

@@ -48,6 +48,10 @@ No arguments. Read the conversation context.
    nodes). This is a synthesis, not a transcript dump. Skip nodes you didn't actually advance. If you
    already authored a node mid-session and nothing changed since, `author` will report "no change" —
    that's fine.
+6. **Sweep pending documentation** — run `npx -y @theronap/cortex-mcp docs-scan --json`; if any
+   docs are pending, follow the `cortex-author-docs` skill (author each into its page, then
+   `docs-scan --mark`). Specs/plans written to disk this session must not die on disk — a spec IS
+   a page. If no roots are registered or nothing is pending, skip silently.
 
 ## Output