@theronap/agnoclast-mcp 0.9.96

package/lib/session_key.mjs

@@ -0,0 +1,37 @@
+// PGL-21: derive the AI session's stable identity key. Pure — see session_key.test.mjs.
+//
+// Claude Code sets CLAUDE_CODE_SESSION_ID for the lifetime of one logical conversation, surviving
+// any number of MCP subprocess restarts (reconnects, tool-loading events) within it. Prefer it so a
+// session-scoped set_active_brain (ADR-0020 Stage 2) keeps pointing at the right brain across a
+// restart instead of silently falling back to the account pointer on a brand-new randomUUID() —
+// reproduced live 2026-07-27: an explicit set_active_brain(scope:'session') stopped taking effect
+// one restart later, with no visible cause, because the new process minted an unrelated session key
+// with no session_write_pointers row of its own. Any other MCP host that doesn't set the var gets
+// today's unchanged per-process-random behavior.
+export function resolveSessionKey(env, randomUUID) {
+  return env.CLAUDE_CODE_SESSION_ID || randomUUID()
+}
+
+// Which session id a `log_session` call should RECORD. Pure — see session_key.test.mjs.
+//
+// Distinct from resolveSessionKey above, and deliberately NOT built on it. That one answers "which
+// session is this process" and may invent a random id, which is correct for a write pointer: any
+// stable value works because it is only ever compared to itself.
+//
+// This answers "which session produced this record", and there an invented value is actively harmful.
+// The id becomes the record's dedupe key (`claude-code:<id>`) and its payload.session_id, which is the
+// ONLY join to the pages the session wrote (page_revisions.session_key). A random per-process uuid
+// would look exactly like a real session id while pairing with no capture record and matching no
+// revision — a confident join that is silently wrong. The timestamp fallback it would replace is at
+// least honestly unattributable.
+//
+// So: caller's value, else the real conversation id, else NOTHING. Never a random.
+//
+// Measured against prod 2026-08-19: 103 of 136 skill records had no session id because the parameter
+// is optional and callers omit it — 76% of every close-out permanently unjoinable to its own work.
+export function resolveLogSessionId(explicit, env) {
+  if (typeof explicit === 'string' && explicit.trim()) return explicit.trim()
+  const fromEnv = env?.CLAUDE_CODE_SESSION_ID
+  if (typeof fromEnv === 'string' && fromEnv.trim()) return fromEnv.trim()
+  return undefined
+}

package/lib/setup.mjs

@@ -0,0 +1,215 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from 'fs'
+import { homedir } from 'os'
+import { join, dirname } from 'path'
+import { checkToken, resolveBase, readWiredToken, wiredDistTag } 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)
+//   2. ~/.claude/settings.json → the capture Stop hook (activity ingest)
+//
+// Safe by construction: backs up each file before touching it, validates JSON,
+// merges into existing structures (never clobbers other MCP servers / hooks),
+// and is idempotent (re-running just updates the cortex entries in place).
+
+const PKG = '@theronap/cortex-mcp'
+
+// mergeCodexToml / mergeCodexHooks moved to ./editors/codex.mjs (imported above, re-exported below).
+
+// PURE, exported for tests. The dist-tag decision is setup's own logic and it has a scar: a bare
+// spec lets npx reuse a stale cached build, a frozen @x.y.z strands the machine forever (the
+// 0.9.5→0.9.6 freeze that stranded a pilot install), and blindly writing @stable silently knocks a
+// dogfooder off @latest. So: preserve an intentional @latest, otherwise @stable, never a version.
+export function pickSpec(distTag, pkg = PKG) {
+  return distTag === 'latest' ? `${pkg}@latest` : `${pkg}@stable`
+}
+
+// PURE, exported for tests. Returns { token } or { error } — the caller owns process.exit, so the
+// validation itself is reachable from a test runner.
+export function parseSetupArgs(argv, pkg = PKG) {
+  const token = (argv ?? [])[0]
+  if (!token || token.startsWith('-')) {
+    return { error: `Usage: npx ${pkg} setup <CORTEX_TOKEN>\n\nGet your token from the Agnoclast console → Connect your AI.\n` }
+  }
+  return { token }
+}
+
+export function readJson(path) {
+  if (!existsSync(path)) return {}
+  const raw = readFileSync(path, 'utf8').trim()
+  if (!raw) return {}
+  return JSON.parse(raw) // throws on malformed — caller handles
+}
+
+export function backup(path) {
+  if (!existsSync(path)) return null
+  const bak = `${path}.cortex-bak`
+  copyFileSync(path, bak)
+  return bak
+}
+
+function ensureDir(path) {
+  const dir = dirname(path)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+}
+
+export async function runSetup(argv, version) {
+  const parsed = parseSetupArgs(argv)
+  if (parsed.error) { process.stderr.write(parsed.error); process.exit(1) }
+  const token = parsed.token
+  // Wire a moving dist-tag — NOT a frozen version. A bare spec lets npx reuse a stale cached build; a
+  // frozen `@x.y.z` freezes the machine on that version forever (the 0.9.5→0.9.6 freeze that stranded a
+  // pilot install). A tag is re-resolved by npx against the registry, so machines pick up promoted
+  // releases on next launch without re-running setup. Promote a validated build with:
+  //   npm dist-tag add @theronap/cortex-mcp@<version> stable
+  // PRESERVE an intentional @latest (dogfood) pin across re-runs (repair/setup) — otherwise this
+  // silently knocks a dogfooder back to @stable. Fresh installs and existing @stable get @stable.
+  const spec = pickSpec(wiredDistTag())
+  const base = resolveBase(process.env.CORTEX_URL)
+  const home = homedir()
+  const claudeJson = join(home, '.claude.json')
+  const settingsJson = join(home, '.claude', 'settings.json')
+
+  const log = (m) => process.stdout.write(m + '\n')
+  log('')
+  log('Agnoclast setup — wiring your AI assistant…')
+
+  // ── 1. MCP server in ~/.claude.json ──────────────────────────────────────
+  try {
+    let cfg
+    try { cfg = readJson(claudeJson) } catch (e) {
+      process.stderr.write(`\n✗ ${claudeJson} is not valid JSON — fix or remove it, then re-run.\n`)
+      process.exit(1)
+    }
+    const bak = backup(claudeJson)
+    cfg = mergeClaudeMcp(cfg, spec, token)
+    ensureDir(claudeJson)
+    writeFileSync(claudeJson, JSON.stringify(cfg, null, 2))
+    log(`  ✓ MCP server → ${claudeJson}${bak ? ' (backup saved)' : ''}`)
+  } catch (e) {
+    process.stderr.write(`  ✗ failed to update ${claudeJson}: ${e.message}\n`)
+    process.exit(1)
+  }
+
+  // ── 1b. MCP server in Codex (~/.codex/config.toml), only if Codex is installed ──
+  // Codex gets the same Agnoclast context tools as Claude Code. Non-fatal: a Codex hiccup must
+  // never block the primary Claude wiring.
+  const codexDir = join(home, '.codex')
+  if (existsSync(codexDir)) {
+    try {
+      const codexToml = join(codexDir, 'config.toml')
+      const existing = existsSync(codexToml) ? readFileSync(codexToml, 'utf8') : ''
+      const bak = backup(codexToml)
+      writeFileSync(codexToml, mergeCodexToml(existing, spec, token))
+      log(`  ✓ MCP server → ${codexToml}${bak ? ' (backup saved)' : ''}`)
+    } catch (e) {
+      log(`  ⚠ Codex MCP wiring skipped: ${e.message} (Claude wiring unaffected)`)
+    }
+
+    // ── 1c. Capture Stop hook in Codex (~/.codex/hooks.json) ──
+    // Without this, Codex sessions get context tools + skills but never capture — a silent gap
+    // (found 2026-07-02: a hand-set hook on Theron's machine was pinned to a stale 0.4.5, years
+    // behind `stable`, because nothing in setup/repair ever refreshed it). Same idempotent
+    // merge pattern as the Claude Stop hook below; non-fatal on failure.
+    try {
+      const codexHooks = join(codexDir, 'hooks.json')
+      let existingHooks
+      try { existingHooks = readJson(codexHooks) } catch { existingHooks = {} } // malformed → start fresh, don't block
+      const bak = backup(codexHooks)
+      // NO inline token (token-hygiene, 2026-07-02): `capture` resolves CORTEX_TOKEN itself via
+      // readWiredToken() from the config.toml this same setup run writes. An inlined secret in
+      // hooks.json shows up in every read/grep of the file — and from there in captured transcripts.
+      const captureCmd = `npx -y ${spec} capture`
+      ensureDir(codexHooks)
+      writeFileSync(codexHooks, JSON.stringify(mergeCodexHooks(existingHooks, captureCmd), null, 2))
+      log(`  ✓ Capture hook → ${codexHooks}${bak ? ' (backup saved)' : ''}`)
+      log('     Codex will ask you to re-approve this hook once (it hashes hooks.json for tamper-detection).')
+    } catch (e) {
+      log(`  ⚠ Codex capture hook skipped: ${e.message} (Claude wiring unaffected)`)
+    }
+  }
+
+  // ── 2. Capture Stop hook in ~/.claude/settings.json ──────────────────────
+  try {
+    let s
+    try { s = readJson(settingsJson) } catch (e) {
+      process.stderr.write(`\n✗ ${settingsJson} is not valid JSON — fix or remove it, then re-run.\n`)
+      process.exit(1)
+    }
+    const bak = backup(settingsJson)
+    // Capture (Stop) + status/skills/snapshot (SessionStart) + hydrate (UserPromptSubmit), idempotent
+    // merge — the same pure function the `cortex install` Claude adapter uses. Also unwires the retired
+    // PreCompact reminder from seats that still carry it.
+    s = mergeClaudeSettings(s, spec)
+
+    ensureDir(settingsJson)
+    writeFileSync(settingsJson, JSON.stringify(s, null, 2))
+    log(`  ✓ Capture + hydrate hooks + status line → ${settingsJson}${bak ? ' (backup saved)' : ''}`)
+  } catch (e) {
+    process.stderr.write(`  ✗ failed to update ${settingsJson}: ${e.message}\n`)
+    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.
+  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)`)
+  }
+
+  // ── 4. Self-verify — writing config proves "files written", NOT "connection works".
+  // Actually call the API so a bad/expired token is caught HERE, not 40 minutes into debugging.
+  log('')
+  log('Verifying your token against Agnoclast…')
+  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`.')
+  }
+
+  log('')
+  log('⟳ IMPORTANT: fully quit and reopen Claude Code to load the Agnoclast server.')
+  log('   Then your AI sees your Agnoclast context and your sessions flow into the org.')
+  log('   Re-check anytime:  npx -y @theronap/cortex-mcp doctor')
+  log(`   Console: ${base}`)
+  log('')
+}
+
+// readWiredToken moved to diagnose.mjs (the shared leaf module) so `capture` can use the same
+// 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.
+export async function runRepair(version) {
+  const token = readWiredToken()
+  if (!token) {
+    process.stderr.write(
+      'No existing Agnoclast token found in ~/.claude.json or ~/.codex/config.toml.\n' +
+      'Run setup once with your token:  npx -y @theronap/cortex-mcp setup <YOUR_TOKEN>\n',
+    )
+    process.exit(1)
+  }
+  process.stdout.write('Agnoclast repair — re-running setup with your existing token at this version…\n')
+  await runSetup([token], version)
+}

package/lib/skills.mjs

@@ -0,0 +1,374 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, copyFileSync, rmSync } from 'fs'
+import { homedir } from 'os'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+// Managed Agnoclast skills.
+//
+// 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)
+//
+// IMPORTANT: skills MUST be one level under <cli>/skills/ — both Claude Code and Codex discover
+// 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: 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.
+const CLIS = [
+  { id: 'Claude Code', dir: join(homedir(), '.claude') },
+  { id: 'Codex', dir: join(homedir(), '.codex') },
+]
+
+// djb2 — tiny, dependency-free content fingerprint for the manifest (drift detection, not security).
+function hash(s) {
+  let h = 5381
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) >>> 0
+  return h.toString(16)
+}
+
+function ensureDir(path) {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true })
+}
+
+// The invocation name (slash command) comes from the SKILL.md `name:` frontmatter, not the folder.
+// Use it as the install directory so the layout matches what the user types (/cortex-log).
+function frontmatterName(source, fallback) {
+  const m = source.match(/^---[\s\S]*?\bname:\s*([^\n#]+)/)
+  return m ? m[1].trim() : fallback
+}
+
+// Discover bundled skills: each subdir of skills/ that contains a SKILL.md.
+function bundledSkills() {
+  if (!existsSync(BUNDLED)) return []
+  return readdirSync(BUNDLED, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && existsSync(join(BUNDLED, d.name, 'SKILL.md')))
+    .map((d) => {
+      const src = join(BUNDLED, d.name, 'SKILL.md')
+      const source = readFileSync(src, 'utf8')
+      return { name: frontmatterName(source, d.name), src, source }
+    })
+}
+
+// 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: [], removed: [] }
+
+  for (const sk of skills) {
+    const dest = join(skillsRoot, sk.name, 'SKILL.md')
+    const status = writeSkillFile(dest, sk.source)
+    result[status].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 */ }
+  }
+
+  // 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 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[] }}
+ */
+export function installSkills(opts = {}) {
+  const quiet = !!opts.quiet
+  const log = (m) => { if (!quiet) process.stdout.write(m + '\n') }
+
+  const skills = bundledSkills()
+  const summary = { installed: [], repaired: [], unchanged: [], targets: [] }
+  if (!skills.length) return summary // nothing bundled (shouldn't happen) — never error
+
+  const targets = CLIS.filter((c) => existsSync(c.dir))
+  if (!targets.length) return summary // no agent CLI on this machine
+
+  for (const cli of targets) {
+    const skillsRoot = join(cli.dir, 'skills')
+    const r = installInto(skillsRoot, skills)
+    summary.targets.push(cli.id)
+    summary.installed.push(...r.installed)
+    summary.repaired.push(...r.repaired)
+    summary.unchanged.push(...r.unchanged)
+    const changed = [...r.installed, ...r.repaired]
+    if (changed.length) log(`  ✓ ${cli.id}: ${changed.join(', ')} → ${skillsRoot}`)
+  }
+
+  if (quiet && (summary.installed.length || summary.repaired.length)) {
+    // SessionStart surfaces one line in Claude Code so a silent self-heal isn't invisible.
+    process.stdout.write(`Agnoclast: synced managed skill(s) into ${summary.targets.join(' + ')}.\n`)
+  }
+  return summary
+}
+
+// Decide what to install from a served org-skill list: drop invalid names, bundled collisions
+// (bundled wins — core skills are inalterable) and cross-brain collisions. Pure, so it's
+// unit-testable without a network.
+export function planOrgInstall(served, bundledNames) {
+  const bundled = new Set(bundledNames)
+  const install = []
+  const skipped = []
+
+  // /api/skills now fans out across EVERY brain the caller belongs to (ADR-0022 acrossMyBrains), so
+  // for the first time two brains can serve the SAME skill name. Installing both would write one
+  // file twice and silently leave whichever landed last — an executable body from a brain the user
+  // never chose. There is no principled winner, so a cross-brain collision installs NEITHER and says
+  // so, matching how a bundled collision already resolves: when in doubt, do not install.
+  const byName = new Map()
+  for (const s of served ?? []) {
+    const n = (s?.name ?? '').trim()
+    if (!byName.has(n)) byName.set(n, [])
+    byName.get(n).push(s)
+  }
+
+  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 }
+    const dupes = byName.get(name) ?? []
+    if (dupes.length > 1) {
+      // Name the brains so the owner knows which to rename. `brain` is the tag acrossMyBrains adds.
+      const brains = [...new Set(dupes.map((d) => d?.brain).filter(Boolean))]
+      skipped.push({ name, why: `published by ${dupes.length} brains (${brains.join(', ') || 'unknown'}) — rename one; installing neither` })
+      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, resolveTokenSource, fetchCortex } = await import('./diagnose.mjs')
+  const token = resolveTokenSource().token
+  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'
+    } else {
+      // ⚠ DO NOT MAKE THIS SILENT AGAIN. `if (res.ok)` alone is how a 100% failure hid for weeks:
+      // /api/skills answered 409 to every multi-brain caller, this fell through to the cache below,
+      // and the only log line ('unreachable and no cache') does NOT print when a cache exists. So
+      // org skills silently stopped updating and nothing anywhere said so. Fail-soft is right —
+      // SessionStart must not break — but fail-soft is not fail-quiet.
+      log(`  · org 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('  · 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(`Agnoclast: 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
+}
+
+// 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
+// existed as `body.error ?? HTTP ${status}`, which printed the bare code `brain_required` and threw
+// all of that away — the user saw a two-word error with no notion of what a brain is, which ones they
+// have, or what to type next. Pure + exported so the shape is unit-testable without a network.
+export function renderPushError(body, status) {
+  const lines = [body?.message ?? body?.error ?? `HTTP ${status}`]
+  const brains = Array.isArray(body?.brains) ? body.brains : []
+  if (brains.length) {
+    lines.push('', '  Your brains:')
+    for (const b of brains) {
+      const pages = typeof b?.pageCount === 'number' ? ` — ${b.pageCount} page${b.pageCount === 1 ? '' : 's'}` : ''
+      const titles = Array.isArray(b?.sampleTitles) && b.sampleTitles.length
+        ? `: ${b.sampleTitles.slice(0, 2).join('; ')}` : ''
+      lines.push(`    ${b?.name ?? b?.orgId ?? '(unnamed)'}${pages}${titles}`)
+    }
+    lines.push('', '  Re-run with --brain "<name>".')
+  }
+  return lines.join('\n')
+}
+
+// `skills push <file> [--brain <name>]` / `skills push --disable <name> [--brain <name>]` /
+// `skills push --enable <name> [--brain <name>]` — publish or toggle an org skill
+// (owner/manager/admin; the server enforces the role).
+//
+// ⚠ --brain IS NOT OPTIONAL FOR A MULTI-BRAIN CALLER, and until 2026-08-08 there was no way to pass
+// it. Publishing MODIFIES one brain, so the server correctly uses ADR-0022's `requireBrain` half and
+// refuses to guess — but this command sent no `brain`, so every push and every --disable from a
+// multi-brain account died on `brain_required` with no way forward. Confirmed against production:
+// `skills push --disable cortex-author-docs` → `✗ brain_required`, full stop.
+//
+// This is the WRITE twin of the GET bug fixed in #467. The read was miscategorised and now fans out;
+// the write was categorised correctly and simply had no input for the answer it demanded.
+export async function runSkillsPush(argv) {
+  const { resolveBase, resolveTokenSource, fetchCortex } = await import('./diagnose.mjs')
+  const token = resolveTokenSource().token
+  if (!token) { process.stderr.write('No Agnoclast token wired — run setup first.\n'); return 1 }
+  const base = resolveBase(process.env.CORTEX_URL)
+
+  const brainIdx = argv.findIndex((a) => a === '--brain')
+  const brain = brainIdx === -1 ? null : argv[brainIdx + 1]
+  if (brainIdx !== -1 && (!brain || brain.startsWith('-'))) {
+    process.stderr.write('Usage: skills push … --brain <name>  (missing brain name)\n')
+    return 1
+  }
+  // Strip --brain AND its value before any positional parsing below. The value does not start with
+  // '-', so the `argv.find(a => !a.startsWith('-'))` file lookup would otherwise take it as the
+  // SKILL.md path and push the wrong thing.
+  const rest = brainIdx === -1 ? argv : argv.filter((_, i) => i !== brainIdx && i !== brainIdx + 1)
+
+  let payload
+  const toggleIdx = rest.findIndex((a) => a === '--disable' || a === '--enable')
+  if (toggleIdx !== -1) {
+    const name = rest[toggleIdx + 1]
+    if (!name) { process.stderr.write(`Usage: skills push ${rest[toggleIdx]} <name>\n`); return 1 }
+    payload = { name, enabled: rest[toggleIdx] === '--enable' }
+  } else {
+    const file = rest.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 qs = brain ? `?brain=${encodeURIComponent(brain)}` : ''
+    const res = await fetchCortex(`${base}/api/skills${qs}`, {
+      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(`✗ ${renderPushError(body, 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('\nAgnoclast skills — installing managed skills…\n')
+  const r = installSkills({ quiet })
+  if (!quiet) {
+    if (!r.targets.length) process.stdout.write('  ! No agent CLI found (~/.claude or ~/.codex). Nothing to install.\n')
+    else if (!r.installed.length && !r.repaired.length) {
+      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
+}