@theronap/cortex-mcp 0.9.95 → 0.9.96

package/lib/migrate_key.mjs

@@ -0,0 +1,139 @@
+import { homedir } from 'node:os'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { readJson, backupFile, ensureDir, writeJson } from './editors/_fsutil.mjs'
+import { allowedToolsFor } from './editors/claude.mjs'
+
+// The C2 key flip, made self-sufficient (ADR-0033 §5, T8).
+//
+// The plan was: C1 adds `mcp__agnoclast__*` to the permission allowlist, then C2 one release later
+// flips `mcpServers.cortex` → `mcpServers.agnoclast`. An earlier draft claimed the release gap made
+// the dangerous ordering "structurally impossible". IT DOES NOT. There is no forced upgrade
+// sequence and — by this ADR's own decision — no version telemetry, so a seat that sits idle
+// through C1 and then upgrades straight to a C2 build receives the flip having never received the
+// allowlist. The gap helps the common case and guarantees nothing.
+//
+// So the ordering guarantee lives HERE, on the machine, not in the release cadence:
+//
+//   1. ensure the new namespace's allow rules are present   (additive — nothing is removed)
+//   2. RE-READ from disk and verify they actually landed
+//   3. only then flip the config key
+//   4. re-read and verify the flip landed
+//   5. record it, so a re-run is a no-op
+//
+// If step 2 fails, the key is NOT flipped and the machine stays fully working on the old name. The
+// failure this prevents is silent: renamed tools that fall outside the allowlist do not error, they
+// prompt — which on an unattended seat (cron, scheduled agents, --print) is a hang or a skip.
+//
+// Note this is the REVERSE of the order editors/claude.mjs wire() uses, which writes .claude.json
+// before settings.json. That is fine for a fresh install, where neither exists yet; it is exactly
+// wrong for a migration, where the config key must move last.
+
+export const OLD_KEY = 'cortex'
+export const NEW_KEY = 'agnoclast'
+
+/** Where the completed migration is recorded. Under ~/.cortex, which ADR-0033 D3 keeps. */
+export const migrationStatePath = (home) => join(home, '.cortex', 'migration.json')
+
+/** PURE. The mcpServers object with our entry moved to the new key, preserving the entry verbatim.
+ *  Returns the same object reference semantics as the input (a copy), plus what it did. */
+export function migratedMcpServers(servers) {
+  const out = { ...(servers ?? {}) }
+  if (out[NEW_KEY] && !out[OLD_KEY]) return { servers: out, moved: false, reason: 'already-new-key' }
+  if (!out[OLD_KEY]) return { servers: out, moved: false, reason: 'no-entry' }
+  // Carry the entry across untouched: command, args (the package spec) and env all survive, so a
+  // dogfooder pinned to @latest stays pinned and the token is not re-derived.
+  out[NEW_KEY] = out[OLD_KEY]
+  delete out[OLD_KEY]
+  return { servers: out, moved: true, reason: null }
+}
+
+/** PURE. Allow rules the new namespace needs that this settings object does not yet carry. */
+export function missingAllows(settings, required = allowedToolsFor(NEW_KEY)) {
+  const have = new Set(Array.isArray(settings?.permissions?.allow) ? settings.permissions.allow : [])
+  return required.filter((r) => !have.has(r))
+}
+
+/** PURE. Settings with the new namespace's rules added. ADDITIVE — the old namespace's rules and
+ *  every user-added rule survive (editors/claude.mjs:48 invariant), and `deny` is never touched. */
+export function withNewAllows(settings, required = allowedToolsFor(NEW_KEY)) {
+  const s = settings && typeof settings === 'object' ? { ...settings } : {}
+  s.permissions = s.permissions && typeof s.permissions === 'object' ? { ...s.permissions } : {}
+  s.permissions.allow = Array.isArray(s.permissions.allow) ? [...s.permissions.allow] : []
+  for (const rule of required) if (!s.permissions.allow.includes(rule)) s.permissions.allow.push(rule)
+  return s
+}
+
+/**
+ * Perform the guarded migration on one machine. Idempotent.
+ * Returns { status, ...detail } where status is one of:
+ *   'already'            — the state file says this machine is done
+ *   'nothing-to-migrate' — no entry of ours under either key
+ *   'aborted'            — the allowlist could not be verified; the key was NOT flipped
+ *   'migrated'           — allows verified, key flipped, state recorded
+ */
+export function runKeyMigration({ home = homedir(), dryRun = false, io = {} } = {}) {
+  const { read = readJson, write = writeJson, backup = backupFile, mkdir = ensureDir, exists = existsSync } = io
+  const claudeJson = join(home, '.claude.json')
+  const settingsJson = join(home, '.claude', 'settings.json')
+  const statePath = migrationStatePath(home)
+  const required = allowedToolsFor(NEW_KEY)
+
+  if (exists(statePath)) {
+    try { if (read(statePath)?.to === NEW_KEY) return { status: 'already', statePath } } catch { /* re-run */ }
+  }
+
+  let cfg
+  try { cfg = read(claudeJson) } catch (e) { return { status: 'aborted', step: 'read-config', reason: e.message } }
+  const plan = migratedMcpServers(cfg?.mcpServers)
+  if (!plan.moved) return { status: 'nothing-to-migrate', reason: plan.reason }
+
+  // ── 1+2. Allowlist FIRST, then verify from disk. ───────────────────────────
+  let settings
+  try { settings = read(settingsJson) } catch (e) { return { status: 'aborted', step: 'read-settings', reason: e.message } }
+  const missing = missingAllows(settings, required)
+  if (dryRun) return { status: 'dry-run', wouldAdd: missing, wouldFlip: `${OLD_KEY} -> ${NEW_KEY}` }
+
+  if (missing.length) {
+    try {
+      backup(settingsJson)
+      mkdir(settingsJson)
+      write(settingsJson, withNewAllows(settings, required))
+    } catch (e) {
+      return { status: 'aborted', step: 'write-settings', reason: e.message, added: 0 }
+    }
+  }
+
+  // Re-read from disk. Writing is not the same as landing: a full disk, a concurrent writer, or a
+  // permission problem can all produce a successful-looking write and an unchanged file.
+  let verify
+  try { verify = read(settingsJson) } catch (e) {
+    return { status: 'aborted', step: 'verify-settings', reason: e.message }
+  }
+  const stillMissing = missingAllows(verify, required)
+  if (stillMissing.length) {
+    return { status: 'aborted', step: 'verify-settings', reason: 'allow rules did not persist', stillMissing }
+  }
+
+  // ── 3+4. Only now flip the key, then verify that too. ──────────────────────
+  try {
+    backup(claudeJson)
+    mkdir(claudeJson)
+    write(claudeJson, { ...cfg, mcpServers: plan.servers })
+  } catch (e) {
+    return { status: 'aborted', step: 'write-config', reason: e.message, allowsAdded: missing.length }
+  }
+  let cfgAfter
+  try { cfgAfter = read(claudeJson) } catch (e) {
+    return { status: 'aborted', step: 'verify-config', reason: e.message }
+  }
+  if (!cfgAfter?.mcpServers?.[NEW_KEY]) {
+    return { status: 'aborted', step: 'verify-config', reason: 'config key did not persist' }
+  }
+
+  // ── 5. Record it. Best-effort: a missing state file only costs an idempotent re-run. ──
+  const record = { from: OLD_KEY, to: NEW_KEY, allowsAdded: missing.length }
+  try { mkdir(statePath); write(statePath, record) } catch { /* non-fatal */ }
+
+  return { status: 'migrated', ...record, statePath }
+}

package/lib/publish_targets.mjs

@@ -0,0 +1,51 @@
+// The names this package is published under, and how to derive each variant's package.json.
+//
+// ADR-0033 §3. Phase B publishes the SAME build under two names: `@theronap/agnoclast-mcp` going
+// forward, and `@theronap/cortex-mcp` in perpetuity, because the old name is hardcoded in hook
+// command strings and in generated launchd/cron scripts on machines we cannot reach. Generated
+// scripts are frozen at write time (D9), so a script written last year still invokes the old name
+// and no upgrade can repair it. Unpublishing would break those silently.
+//
+// "Byte-identical tarballs" is impossible — the name lives inside the tarball's own package.json —
+// so the guarantee is weaker and more precise: both variants are packed from ONE source tree in ONE
+// release step, and differ ONLY in the fields listed in VARIANT_FIELDS.
+//
+// The `bin` key differs too, and must. npm installs bins by key, so two packages both declaring
+// `cortex-mcp` collide on any machine that resolves both. Each variant declares a bin named after
+// itself. `npx -y <either name>` still works: with exactly one bin declared, npx runs it regardless
+// of what the key is called.
+
+/** The fields that may legitimately differ between variants. Anything else differing is a bug. */
+export const VARIANT_FIELDS = ['name', 'bin']
+
+/** Publish targets, primary first. Additive only: a name that has ever been published stays here. */
+export const PUBLISH_TARGETS = [
+  { name: '@theronap/agnoclast-mcp', bin: 'agnoclast-mcp', role: 'primary' },
+  { name: '@theronap/cortex-mcp', bin: 'cortex-mcp', role: 'alias' },
+]
+
+/** The entry point every variant's bin points at. One file, many names. */
+export const BIN_ENTRY = 'bin/cortex-mcp.mjs'
+
+/** PURE. The package.json to publish for one target, derived from the source manifest. */
+export function variantPackageJson(sourcePkg, target) {
+  if (!sourcePkg || typeof sourcePkg !== 'object') throw new TypeError('variantPackageJson: sourcePkg must be an object')
+  if (!target?.name || !target?.bin) throw new TypeError('variantPackageJson: target needs { name, bin }')
+  return { ...sourcePkg, name: target.name, bin: { [target.bin]: BIN_ENTRY } }
+}
+
+/** PURE. Fields that differ between two manifests, so a release can assert only VARIANT_FIELDS do.
+ *  Returns a sorted list of top-level keys whose JSON serialization differs. */
+export function differingFields(a, b) {
+  const keys = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})])
+  const out = []
+  for (const k of keys) {
+    if (JSON.stringify(a?.[k]) !== JSON.stringify(b?.[k])) out.push(k)
+  }
+  return out.sort()
+}
+
+/** PURE. True when two variants differ ONLY in the fields allowed to differ. */
+export function variantsAreEquivalent(a, b) {
+  return differingFields(a, b).every((f) => VARIANT_FIELDS.includes(f))
+}

package/lib/redact.mjs

@@ -24,7 +24,7 @@ const PATTERNS = [
   // Agnoclast's own login token wherever it appears in KEY=value / KEY: value form (hooks.json,
   // config.toml, shell commands — the 2026-07-02 finding: a grep of hooks.json put the live token
   // in a transcript and nothing below caught it). Specific pattern first for the accurate label.
-  [/(CORTEX_TOKEN["']?\s*[=:]\s*["']?)[0-9a-fA-F][0-9a-fA-F-]{30,}/g, '$1[REDACTED:cortex-token]'],
+  [/((?:AGNOCLAST|CORTEX)_TOKEN["']?\s*[=:]\s*["']?)[0-9a-fA-F][0-9a-fA-F-]{30,}/g, '$1[REDACTED:agnoclast-token]'],
   // Generic secret-shaped assignment: an UPPER_SNAKE name ending in TOKEN/SECRET/PASSWORD/
   // API_KEY/APIKEY assigned a ≥16-char value. Conservative: the name-suffix + length floor keep
   // ordinary prose, short placeholders, and bare UUIDs (record ids) intact.

package/lib/rename_notice.mjs

@@ -0,0 +1,31 @@
+import { NEW_KEY, OLD_KEY } from './migrate_key.mjs'
+
+// The C1 warning (ADR-0033 §4, T7).
+//
+// THIS WHOLE MODULE IS TEMPORARY. It ships in C1, one release ahead of the C2 key flip, and is
+// DELETED a release after C2. If you are reading this and C2 shipped more than one release ago,
+// delete the file, its test, and the two lines that call it in doctor.mjs.
+//
+// The decision it implements: warn once that the flip is coming, then it is the user's file and
+// their call. No detection loop, no dismiss state, no expiry to guess. Earlier drafts proposed
+// grepping every user's CLAUDE.md on a cadence and nagging until it changed; that was rejected —
+// the package has never written CLAUDE.md and should not start, and a nag that cannot tell a fixed
+// file from an unfixed one is wrong for some readers the entire time it runs.
+//
+// It is self-limiting without any state: the notice renders only while this machine is still on the
+// OLD config key. Once `migrate-key` flips it, the condition is false and the message stops. That is
+// "warn, then leave them alone" expressed as a condition rather than as a timer.
+
+/** C1 sets this true. Until then the notice is inert, so building it now changes nothing for the
+ *  people currently on @latest. Flipping this constant IS the C1 release. */
+export const RENAME_NOTICE_ACTIVE = false
+
+/** PURE. The one-line warning, or null when it should stay quiet.
+ *  `key` is which config key answered on this machine ('cortex' | 'agnoclast' | null). */
+export function renderRenameNotice(key, { active = RENAME_NOTICE_ACTIVE } = {}) {
+  if (!active) return null
+  if (key !== OLD_KEY) return null // already flipped, or nothing wired — nothing to warn about
+  return `Agnoclast: heads up — the MCP tools are being renamed from mcp__${OLD_KEY}__* to `
+    + `mcp__${NEW_KEY}__*. If your CLAUDE.md names the old tools, update it when convenient. `
+    + `Run \`npx -y @theronap/cortex-mcp migrate-key\` to switch now, or wait and it will happen for you.`
+}

package/lib/resolve.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from 'child_process'
-import { fetchCortex, resolveBase, classify } from './diagnose.mjs'
+import { fetchCortex, resolveBase, resolveEnvToken, classify } from './diagnose.mjs'
 import { edgeSafeEnv } from './edge_extract.mjs'
 
 // `cortex-mcp resolve` — the JUDGE half of entity identity dedup (Grey harvest). The server FLAGS the
@@ -38,7 +38,7 @@ export async function brainsToSweep(base, token, wanted, deps = {}) {
 export async function runResolve(argv = []) {
   // recursion guard (we spawn `claude --print`; if its Stop hook fires capture, that no-ops on this flag)
   if (process.env.CORTEX_SUMMARIZING) { process.stderr.write('cortex: summarizer subprocess, skipping\n'); return }
-  const token = process.env.CORTEX_TOKEN
+  const token = resolveEnvToken().token
   if (!token) { process.stderr.write('cortex: CORTEX_TOKEN not set, skipping\n'); return }
   const base = resolveBase(process.env.CORTEX_URL)
 

package/lib/server.mjs

@@ -5,8 +5,8 @@ import { writeFileSync, mkdirSync } from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 import { createHash, randomUUID } from 'crypto'
-import { fetchCortex, classify, resolveBase, setSessionKey } from './diagnose.mjs'
-import { resolveSessionKey } from './session_key.mjs'
+import { fetchCortex, classify, resolveBase, resolveEnvToken, setSessionKey } from './diagnose.mjs'
+import { resolveSessionKey, resolveLogSessionId } from './session_key.mjs'
 import { runSendImessage } from './imessage_send.mjs'
 import { formatGrepHits } from './grep_cli.mjs'
 import { renderTriage } from './red_link_triage.mjs'
@@ -76,7 +76,7 @@ export const renderSection = (s, day) => `### ${s.heading}${sectionCurrencyStamp
 // context to their AI assistant. CORTEX_TOKEN identifies the user + org.
 
 export async function runServer(version) {
-  const TOKEN = process.env.CORTEX_TOKEN
+  const TOKEN = resolveEnvToken().token
   const BASE = resolveBase(process.env.CORTEX_URL)
 
   if (!TOKEN) {
@@ -108,7 +108,11 @@ export async function runServer(version) {
       await fetchCortex(`${BASE}/api/session-ping`, {
         method: 'POST',
         headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-        body: JSON.stringify({ sessionKey: SESSION_KEY, cwd: process.cwd() }),
+        // mcpVersion (ADR-0033 T9): the fleet currently has NO way to report which client build a
+        // seat runs — session-ping carried liveness only. That is why every version gate in this
+        // ADR was unobservable. Additive and forward-compatible: the route destructures sessionKey
+        // and cwd and ignores the rest, so this is inert until a column exists to store it.
+        body: JSON.stringify({ sessionKey: SESSION_KEY, cwd: process.cwd(), mcpVersion: version }),
       })
     } catch { /* best-effort heartbeat — never disrupt the session */ }
   }
@@ -224,7 +228,7 @@ export async function runServer(version) {
     'log_session',
     {
       title: 'Log this session to Agnoclast',
-      description: 'Persist a CURATED summary of this work session as its durable Agnoclast record (authoritative — supersedes the auto-capture hook). Call at session close after composing the summary. Pass sessionId (the Claude Code session id) so this dedupes with the auto-capture of the same session. If you belong to more than one brain you MUST name one — without a brain a session log has no route and is STAGED rather than recorded. **If the session touched work belonging to different brains, pass `segments` instead of `summary` and split it** — one segment per brain, each summary standing on its own and never alluding to the others. Reports every segment individually; a partial result is reported as PARTIAL, never as success.',
+      description: 'Persist a CURATED summary of this work session as its durable Agnoclast record (authoritative — supersedes the auto-capture hook). Call at session close after composing the summary. `sessionId` now defaults to this session automatically (from CLAUDE_CODE_SESSION_ID) so the log dedupes with the auto-capture of the same session — pass it explicitly only to log on behalf of a DIFFERENT session, e.g. recovering one whose own close-out failed. If you belong to more than one brain you MUST name one — without a brain a session log has no route and is STAGED rather than recorded. **If the session touched work belonging to different brains, pass `segments` instead of `summary` and split it** — one segment per brain, each summary standing on its own and never alluding to the others. Reports every segment individually; a partial result is reported as PARTIAL, never as success.',
       inputSchema: {
         summary: z.string().optional().describe('the curated session summary — the single-brain form. Omit when passing `segments`'),
         segments: z.array(z.object({
@@ -235,12 +239,33 @@ export async function runServer(version) {
         })).optional().describe('SPLIT the log, one entry per brain. Use whenever a session touched work belonging to different brains: a session is a container of time, not a topic, and every single-brain answer is wrong — filing it all in the org brain exposes personal work to colleagues, filing it all in the personal one denies the org its record, and summarizing half silently drops the other half. Max ONE segment per brain (they share this session\'s dedupe key, so two aimed at the same brain would overwrite each other). When a chunk is ambiguous, put it in the MORE PRIVATE brain — a misfile there is private, a misfile the other way is visible to everyone in the org.'),
         project: z.string().optional().describe('project key/name this session worked in'),
         title: z.string().optional().describe('short title for the session'),
-        sessionId: z.string().optional().describe('the Claude Code session id — shared by every segment, and the only thing pairing them. Deliberately NOT a link: segments never reference each other, so a reader cleared for one brain cannot tell the others exist, while you can join on it across brains'),
+        sessionId: z.string().optional().describe('the Claude Code session id — DEFAULTS to the current session, so omit it unless you are logging on behalf of another one. It is shared by every segment and the only thing pairing them, and it is also the join to the pages this session wrote (page_revisions.session_key); without it the record is unattributable forever, since the fallback dedupe key is a timestamp. Deliberately NOT a link: segments never reference each other, so a reader cleared for one brain cannot tell the others exist, while you can join on it across brains'),
         brain: z.string().optional().describe('which brain to record this session in (name or org id, one of your own). REQUIRED IN EFFECT for a multi-brain member: session-class sources route only by an explicit brain or a sole membership, so omitting it stages the log instead of recording it.'),
         privacy: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('tier this record AT WRITE TIME. Use when the summary names confidential work (a candidate evaluation, a security finding) — safer than letting it land org-visible and re-tiering after, which leaves it readable in between.'),
       },
     },
     async ({ summary, segments, project, title, sessionId, brain, privacy }) => {
+      // Default the session id from the environment when the caller omits it.
+      //
+      // `sessionId` is optional and the model routinely does not pass it, so the record lands with a
+      // TIMESTAMP dedupe key (`claude-code:<ISO>`) and a null payload.session_id. Measured against
+      // prod 2026-08-19: of 136 skill records, only 33 carried a session id — the other 103 are
+      // unattributable by any means, because the timestamp key is not a fallback identity. That is
+      // 76% of every /cortex-log close-out unable to be joined to the pages that session wrote
+      // (page_revisions.session_key), which is the join the whole currency audit runs on.
+      //
+      // The process has always known this value. It is the same CLAUDE_CODE_SESSION_ID the capture
+      // hook sends as hook.session_id, which is precisely what makes the two dedupe onto one record
+      // instead of two — the stated purpose of the parameter in this tool's own description.
+      //
+      // ⚠ resolveLogSessionId, NOT resolveSessionKey / SESSION_KEY. The latter falls back to
+      // randomUUID(), and a random per-process uuid here would be WORSE than the timestamp it
+      // replaces: it looks like a real session id, mints `claude-code:<random>` as a dedupe key that
+      // pairs with no capture record and matches no page_revisions.session_key, and so manufactures a
+      // confident-looking join that is silently wrong. A missing id is honest; an invented one is not.
+      // Hosts that do not set the var keep today's timestamp behaviour. Negative-controlled in
+      // session_key.test.mjs.
+      sessionId = resolveLogSessionId(sessionId, process.env)
       // A session is a container of TIME, not a topic (ADR-0029 step 4). Normalize to a list of
       // segments; the single-brain call is just a one-segment list.
       const list = Array.isArray(segments) && segments.length

package/lib/session_key.mjs

@@ -11,3 +11,27 @@
 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

@@ -20,14 +20,32 @@ const PKG = '@theronap/cortex-mcp'
 
 // mergeCodexToml / mergeCodexHooks moved to ./editors/codex.mjs (imported above, re-exported below).
 
-function readJson(path) {
+// 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
 }
 
-function backup(path) {
+export function backup(path) {
   if (!existsSync(path)) return null
   const bak = `${path}.cortex-bak`
   copyFileSync(path, bak)
@@ -40,14 +58,9 @@ function ensureDir(path) {
 }
 
 export async function runSetup(argv, version) {
-  const token = argv[0]
-  if (!token || token.startsWith('-')) {
-    process.stderr.write(
-      'Usage: npx @theronap/cortex-mcp setup <CORTEX_TOKEN>\n\n' +
-      'Get your token from the Agnoclast console → Connect your AI.\n'
-    )
-    process.exit(1)
-  }
+  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
@@ -55,7 +68,7 @@ export async function runSetup(argv, version) {
   //   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 = wiredDistTag() === 'latest' ? `${PKG}@latest` : `${PKG}@stable`
+  const spec = pickSpec(wiredDistTag())
   const base = resolveBase(process.env.CORTEX_URL)
   const home = homedir()
   const claudeJson = join(home, '.claude.json')

package/lib/skills.mjs

@@ -206,8 +206,8 @@ export async function syncOrgSkills(opts = {}) {
   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()
+  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.
@@ -300,8 +300,8 @@ export function renderPushError(body, status) {
 // 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, readWiredToken, fetchCortex } = await import('./diagnose.mjs')
-  const token = process.env.CORTEX_TOKEN || readWiredToken()
+  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)