@theronap/agnoclast-mcp 0.9.96

package/lib/diagnose.mjs

@@ -0,0 +1,360 @@
+// Shared health / diagnosis helpers for the cortex MCP client.
+//
+// The whole reason this file exists: a transient infrastructure block (Vercel firewall / bot
+// protection / deployment protection) once surfaced as a bare "Agnoclast API 403: unknown", which
+// read like an auth failure and sent everyone chasing token regeneration for hours. The fix is
+// to tell the truth about WHAT failed.
+//
+// KEY SIGNAL: the Agnoclast app ALWAYS returns JSON ({ error: ... }). So a NON-JSON body on a
+// 4xx/5xx means infrastructure handled the request, not Agnoclast auth — re-running setup or
+// regenerating the token will not help; it is usually transient and worth a retry.
+
+import { readFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+
+export const isUuid = (s) =>
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(s ?? '')
+
+// Find the token already wired on this machine (Claude's ~/.claude.json first, then Codex's
+// config.toml). Lives HERE — the shared leaf module — so both setup/repair and the capture hook
+// use one resolver: hook commands carry NO inline token (token-hygiene, 2026-07-02 — an inlined
+// `CORTEX_TOKEN=…` in hooks.json shows the secret to anything that reads or greps the file, and
+// from there to captured transcripts); `capture` resolves the token itself from the same config
+// the MCP server already holds.
+// ── Token resolution ─────────────────────────────────────────────────────────
+// TWO resolvers, deliberately. An audit of all twelve call sites (ADR-0033 T1) found they are NOT
+// semantically interchangeable: five REQUIRE an explicit token and five may fall back to the wired
+// config. Collapsing both into one function would have silently granted config-based auth to the
+// five that deliberately demand it — the failure the independent review flagged.
+//
+//   resolveEnvToken()    env only          → server, graphify-sync, grep, ingest-folder, resolve
+//   resolveTokenSource() env, then wired   → capture, hydrate, skills×2, context_log, doctor
+//
+// Precedence is PRESENCE-based, not validity-based: the first variable that is set wins, so a stale
+// AGNOCLAST_TOKEN shadows a working CORTEX_TOKEN. Validity-based precedence would need a network
+// round-trip on every resolution, which this path cannot afford. Instead the winner is REPORTED in
+// `source`, so `doctor` shows which variable was used and a shadow is visible rather than silent.
+
+/** In precedence order. Additive only — never drop a name a machine may still be wired with. */
+export const TOKEN_ENV_VARS = ['AGNOCLAST_TOKEN', 'CORTEX_TOKEN']
+const CONFIG_KEYS = ['agnoclast', 'cortex']
+
+/** Environment only. For call sites where an explicit token is the point. */
+export function resolveEnvToken(env = process.env) {
+  for (const name of TOKEN_ENV_VARS) {
+    if (env?.[name]) return { token: env[name], source: `${name} env`, key: null }
+  }
+  return { token: null, source: null, key: null }
+}
+
+// Positive results only, keyed by home. A miss re-reads, so a token wired mid-process (setup, then
+// a hook in the same run) is still picked up; a hit is stable because a token cannot change while a
+// process lives.
+//
+// `home` is an explicit parameter rather than always homedir() because BUN'S os.homedir() IGNORES
+// the HOME variable (verified 2026-08-19: node honours it, bun returns the real home regardless),
+// so a bun test cannot redirect it. editors/*.mjs already take `home` for the same reason.
+const _wiredCache = new Map()
+
+/** Reset the wired-token memo. Tests only. */
+export function resetWiredTokenCache() { _wiredCache.clear() }
+
+/** The wired config: ~/.claude.json first, then Codex config.toml. Memoized because this parses a
+ *  ~117KB JSON file and the twelve call sites above are reached from per-prompt hooks. */
+export function readWiredTokenSource(home = homedir()) {
+  if (_wiredCache.has(home)) return _wiredCache.get(home)
+  const claudeJson = join(home, '.claude.json')
+  try {
+    const cfg = JSON.parse(readFileSync(claudeJson, 'utf8'))
+    for (const key of CONFIG_KEYS) {
+      const env = cfg?.mcpServers?.[key]?.env
+      for (const name of TOKEN_ENV_VARS) {
+        if (env?.[name]) { const r = { token: env[name], source: `${claudeJson} (mcpServers.${key})`, key }; _wiredCache.set(home, r); return r }
+      }
+    }
+  } catch { /* malformed or absent — fall through */ }
+  const codexToml = join(home, '.codex', 'config.toml')
+  try {
+    const toml = readFileSync(codexToml, 'utf8')
+    for (const key of CONFIG_KEYS) {
+      for (const name of TOKEN_ENV_VARS) {
+        const m = toml.match(new RegExp(`\\[mcp_servers\\.${key}\\.env\\][\\s\\S]*?${name}\\s*=\\s*"([^"]+)"`))
+        if (m) { const r = { token: m[1], source: `${codexToml} ([mcp_servers.${key}])`, key }; _wiredCache.set(home, r); return r }
+      }
+    }
+  } catch { /* fall through */ }
+  return { token: null, source: null, key: null }
+}
+
+/** Environment, then wired config. The canonical resolver for background/hook work. */
+export function resolveTokenSource(env = process.env, home = homedir()) {
+  const fromEnv = resolveEnvToken(env)
+  return fromEnv.token ? fromEnv : readWiredTokenSource(home)
+}
+
+/** Bare-token form of the WIRED lookup only — deliberately NOT env-aware, because install.mjs:70
+ *  calls it as `argToken || readWiredToken()` where the whole point is "what is already wired". */
+export function readWiredToken(home = homedir()) {
+  return readWiredTokenSource(home).token
+}
+
+// Pure: pull the cortex-mcp dist-tag / version out of a wired command line. Exported for tests.
+// Returns 'latest' | 'stable' | a version string (e.g. '0.9.4') | null (no cortex-mcp spec present).
+export function parseDistTag(line) {
+  const m = String(line || '').match(/@theronap\/cortex-mcp@(latest|stable|[0-9][^\s"']*)/)
+  return m ? m[1] : null
+}
+
+// Read the dist-tag / version this machine is currently wired to (from the ~/.claude.json cortex MCP
+// command), so a re-run of setup/repair can PRESERVE an intentional channel instead of forcing @stable
+// every time — that silently knocks a dogfooder on @latest back to the pilot channel (bit Theron
+// 2026-07-24). Returns 'latest' | 'stable' | a version string | null (nothing wired yet).
+export function wiredDistTag() {
+  try {
+    const cfg = JSON.parse(readFileSync(join(homedir(), '.claude.json'), 'utf8'))
+    const c = cfg?.mcpServers?.cortex
+    return parseDistTag([c?.command, ...(c?.args ?? [])].filter(Boolean).join(' '))
+  } catch { /* fall through */ }
+  return null
+}
+
+// The production alias — exempt from Vercel Deployment Protection.
+export const CANONICAL_BASE = 'https://cortex-console.vercel.app'
+
+// Resolve the API base from CORTEX_URL. A Vercel *deployment* URL
+// (cortex-console-<hash>-<team>.vercel.app, or any non-canonical *.vercel.app) is guarded by
+// Deployment Protection and returns an HTML auth page to programmatic clients — which looks
+// exactly like an "infra block" (403/401, non-JSON). The production alias is exempt. So if
+// CORTEX_URL points at a deployment URL, we fall back to the alias (and warn on stderr). A real
+// custom domain (not *.vercel.app) is respected as-is. This makes the client robust to a stale
+// CORTEX_URL pointing at a protected preview/deployment — the root cause of the Windows 403.
+export function resolveBase(rawUrl) {
+  const raw = (rawUrl ?? '').trim()
+  if (!raw) return CANONICAL_BASE
+  let host
+  try { host = new URL(raw).host } catch { return CANONICAL_BASE }
+  if (host.endsWith('.vercel.app') && host !== 'cortex-console.vercel.app') {
+    process.stderr.write(
+      `cortex: CORTEX_URL (${raw}) is a protected Vercel deployment URL; using ${CANONICAL_BASE} instead.\n`,
+    )
+    return CANONICAL_BASE
+  }
+  return raw.replace(/\/$/, '')
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
+
+// A non-OK response → an actionable diagnosis: { kind, retriable, message }.
+//   kind: 'auth'  → token bad/revoked/wrong-deployment (NOT retriable)
+//         'infra' → blocked by infrastructure, non-JSON body (retriable, usually transient)
+//         'app'   → a real Agnoclast API error with a JSON message (retriable only if 5xx)
+export function classify(status, contentType, bodyText, requestId) {
+  const isJson = (contentType ?? '').includes('application/json')
+  let appError = null
+  let appHint = null
+  let appMessage = null
+  let appBrains = null
+  if (isJson) {
+    try {
+      const parsed = JSON.parse(bodyText)
+      appError = parsed?.error ?? null
+      // Same lesson as `hint`, one layer up. brain_choice_response.ts writes a full explanation to
+      // `message` and every brain's NAME / PAGE COUNT / SAMPLE TITLES to `brains` — its comment says
+      // "THE BODY IS THE ANSWER TO ITS OWN QUESTION", precisely so a model can pick a brain from what
+      // each one HOLDS. Only `error` survived here, so the agent got the bare code `brain_required`
+      // and could not answer it. Measured on the CLI twin of this bug: `✗ brain_required`, full stop.
+      appMessage = typeof parsed?.message === 'string' && parsed.message.trim() ? parsed.message.trim() : null
+      appBrains = Array.isArray(parsed?.brains) ? parsed.brains : null
+      // `hint` carries the RECOVERY instruction for the errors an agent is meant to act on, not
+      // just report: 409 would_drop ("re-author including the dropped sections…") and 413 too_large
+      // ("split the section…"). It used to be dropped here — only `error` survived — so the agent
+      // saw a bare code like "would_drop_sections" and had no idea what to do with it. The routes
+      // were writing careful self-heal guidance that never reached anyone.
+      appHint = typeof parsed?.hint === 'string' && parsed.hint.trim() ? parsed.hint.trim() : null
+    } catch { /* not json after all */ }
+  }
+  const rid = requestId ? ` [request id: ${requestId}]` : ''
+
+  if (status === 401 || (isJson && appError === 'invalid token')) {
+    return {
+      kind: 'auth', retriable: false,
+      message: `Token rejected (HTTP ${status}: ${appError ?? 'unauthorized'}). The token is invalid, ` +
+        `revoked, or for a different deployment — not an infrastructure problem. Get a fresh token from ` +
+        `the Agnoclast console → Connect your AI, then re-run setup.${rid}`,
+    }
+  }
+  if (!isJson) {
+    return {
+      kind: 'infra', retriable: true,
+      message: `Blocked by infrastructure (HTTP ${status}, non-JSON response) — NOT by Agnoclast auth. This is ` +
+        `usually a transient firewall / bot-protection hiccup; retrying often clears it. If it persists, check ` +
+        `Vercel firewall / deployment protection on the API route. Re-running setup will not help.${rid}`,
+    }
+  }
+  // A brain-choice refusal is ANSWERABLE, so it must arrive as the question it is rather than as a
+  // code. Deliberately narrow: only these two errors reshape the message, so every other classify()
+  // output keeps its existing wording (and its tests).
+  if (isJson && (appError === 'brain_required' || appError === 'unknown_brain') && (appMessage || appBrains)) {
+    const list = (appBrains ?? []).map((b) => {
+      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('; ')}` : ''
+      // Name AND id: brain names are NOT unique (one account holds two called "Personal"), so a name
+      // alone can come back as unknown_brain. The id always resolves.
+      return `  - ${b?.name ?? '(unnamed)'}${pages}${titles}${b?.orgId ? ` [${b.orgId}]` : ''}`
+    })
+    return {
+      kind: 'app', retriable: false,
+      message: `Agnoclast API ${status}: ${appMessage ?? appError}${list.length ? `\n${list.join('\n')}` : ''}` +
+        `\nRe-run this tool with \`brain\` set to one of the names or ids above.${rid}`,
+    }
+  }
+
+  return {
+    kind: 'app', retriable: status >= 500,
+    message: `Agnoclast API ${status}: ${appError ?? 'unknown error'}.${appHint ? ` ${appHint}` : ''}${rid}`,
+  }
+}
+
+// fetch with retry on TRANSIENT responses only (429, 5xx, and infra-style non-JSON 403).
+// App-level 401/403-with-JSON are returned immediately (retrying won't change the verdict).
+// Throws a clear network error if the host is unreachable after retries.
+//
+// PER-ATTEMPT TIMEOUT (added 2026-07-08): every attempt is bounded by an AbortSignal so a
+// HANGING server (not a fast 5xx — an ingest endpoint that just never responds, observed this day)
+// can't stall a hook indefinitely. Without it, `fetch` waits forever and the retry loop made it
+// WORSE — 3 unbounded attempts stacked. Now worst case = (retries+1) * timeoutMs + backoff, and a
+// timed-out attempt is treated as transient (retried, then surfaced as the reach error the callers
+// already swallow). Tunable via CORTEX_HTTP_TIMEOUT_MS; per-call override via opts.timeoutMs.
+// ADR-0020 Stage 2 — this process's session identity, stamped on every request so the server can
+// resolve THIS session's write pointer instead of the person-wide one. Set once by the MCP server at
+// startup (setSessionKey); left null in the one-shot hook processes (capture, context_log), which
+// have no session of their own and correctly fall back to the account pointer.
+//
+// Injected HERE rather than at each call site because fetchCortex is the single chokepoint every
+// caller already funnels through — ~30 call sites pass their own `headers` object, and a header this
+// load-bearing must not depend on remembering it at each one.
+let SESSION_KEY = null
+export function setSessionKey(key) { SESSION_KEY = key || null }
+
+export async function fetchCortex(url, opts = {}, { retries = 2, baseDelayMs = 400 } = {}) {
+  const { timeoutMs: optTimeout, signal: callerSignal, ...rest } = opts
+  const fetchOpts = SESSION_KEY
+    ? { ...rest, headers: { ...(rest.headers ?? {}), 'x-cortex-session-key': SESSION_KEY } }
+    : rest
+  const timeoutMs = optTimeout ?? (Number(process.env.CORTEX_HTTP_TIMEOUT_MS) || 15_000)
+  let lastErr
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      // Fresh timeout signal per attempt; compose with any caller-supplied signal.
+      const timeoutSignal = AbortSignal.timeout(timeoutMs)
+      const signal = callerSignal ? AbortSignal.any([callerSignal, timeoutSignal]) : timeoutSignal
+      const res = await fetch(url, { ...fetchOpts, signal })
+      const ct = res.headers.get('content-type') ?? ''
+      const transient =
+        res.status === 429 ||
+        res.status >= 500 ||
+        (res.status === 403 && !ct.includes('application/json')) // infra block, not app authz
+      if (transient && attempt < retries) {
+        await sleep(baseDelayMs * 2 ** attempt)
+        continue
+      }
+      return res
+    } catch (e) {
+      lastErr = e
+      if (attempt < retries) { await sleep(baseDelayMs * 2 ** attempt); continue }
+    }
+  }
+  throw new Error(
+    `Could not reach Agnoclast at ${url} — ${lastErr?.message ?? 'network error'}. ` +
+    `Check your connection (and CORTEX_URL if you set it).`,
+  )
+}
+
+// Live health probe: hit /api/mcp-context with the token and classify the result.
+// Returns { ok, status, projectCount?, requestId?, diagnosis? }.
+export async function checkToken(token, base) {
+  if (!token) {
+    return { ok: false, status: 0, diagnosis: { kind: 'config', retriable: false,
+      message: 'No CORTEX_TOKEN found. Run: npx -y @theronap/cortex-mcp setup <your-token>' } }
+  }
+  if (!isUuid(token)) {
+    return { ok: false, status: 0, diagnosis: { kind: 'config', retriable: false,
+      message: `Token "${String(token).slice(0, 8)}…" is not a valid Agnoclast token (expected a UUID). ` +
+        `Re-run setup with the token from the console.` } }
+  }
+  const url = `${(base ?? 'https://cortex-console.vercel.app').replace(/\/$/, '')}/api/mcp-context`
+  let res
+  try {
+    res = await fetchCortex(url, { headers: { Authorization: `Bearer ${token}` } })
+  } catch (e) {
+    return { ok: false, status: 0, diagnosis: { kind: 'network', retriable: true, message: e.message } }
+  }
+  const requestId = res.headers.get('x-vercel-id') ?? null
+  const contentType = res.headers.get('content-type')
+  const body = await res.text()
+  if (!res.ok) {
+    return { ok: false, status: res.status, requestId, diagnosis: classify(res.status, contentType, body, requestId) }
+  }
+  let projectCount
+  let captureNotice = null
+  try {
+    const parsed = JSON.parse(body)
+    const ctx = parsed.context ?? ''
+    const m = ctx.match(/## Projects \((\d+)\)/)
+    if (m) projectCount = Number(m[1])
+    // The server's "your work is not landing" advisory. Optional by design: an older server does not
+    // send it and this must stay a health check, so a missing field is simply no notice.
+    if (parsed.captureNotice && typeof parsed.captureNotice.message === 'string') {
+      captureNotice = parsed.captureNotice
+    }
+  } catch { /* context shape changed — non-fatal for a health check */ }
+  return { ok: true, status: 200, projectCount, requestId, captureNotice }
+}
+
+// Probe the org-skills surface. SEPARATE FROM checkToken ON PURPOSE.
+//
+// WHY THIS EXISTS. `doctor` checked exactly one endpoint — /api/mcp-context — and reported PASS on
+// the strength of it. Meanwhile /api/skills answered 409 to every multi-brain caller for three days
+// (measured 2026-08-08: 14 requests, 14 × 409, zero successes; the local cache sat frozen from Aug 5
+// to Aug 8). Org-published skills silently never installed, the client swallowed the status, and
+// doctor — the tool setup.txt tells people to run FIRST when something is wrong — said everything
+// was fine, every single time. A check that probes one surface is a health check for that surface,
+// not for the system, and must not be reported as the latter.
+//
+// Returns checkToken's shape so the caller renders both the same way. `skillCount` is
+// informational: an org with zero published skills is perfectly healthy, so it is NOT a failure.
+export async function checkSkills(token, base) {
+  if (!token || !isUuid(token)) {
+    return { ok: false, status: 0, diagnosis: { kind: 'config', retriable: false,
+      message: 'no usable token — the context check above already covers this' } }
+  }
+  const url = `${(base ?? CANONICAL_BASE).replace(/\/$/, '')}/api/skills`
+  let res
+  try {
+    res = await fetchCortex(url, { headers: { Authorization: `Bearer ${token}` } })
+  } catch (e) {
+    return { ok: false, status: 0, diagnosis: { kind: 'network', retriable: true, message: e.message } }
+  }
+  const requestId = res.headers.get('x-vercel-id') ?? null
+  const contentType = res.headers.get('content-type')
+  const body = await res.text()
+  if (!res.ok) {
+    return { ok: false, status: res.status, requestId, diagnosis: classify(res.status, contentType, body, requestId) }
+  }
+  let skillCount
+  try { skillCount = (JSON.parse(body)?.skills ?? []).length } catch { /* shape drift — non-fatal */ }
+  return { ok: true, status: 200, skillCount, requestId }
+}
+
+// Release the keep-alive sockets the global fetch (undici) holds, so a short-lived CLI command
+// can tear down cleanly. Without this, calling process.exit() right after a fetch can race a
+// lingering socket handle and trip a libuv assertion on Windows
+// (`!(handle->flags & UV_HANDLE_CLOSING)`, src\win\async.c). Best-effort + never throws.
+export async function closeFetch() {
+  try {
+    const dispatcher = globalThis[Symbol.for('undici.globalDispatcher.1')]
+    if (dispatcher && typeof dispatcher.close === 'function') await dispatcher.close()
+  } catch { /* cleanup must never break the caller */ }
+}

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
+// Agnoclast 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 Agnoclast 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 Agnoclast.`)
+      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 Agnoclast 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/doctor.mjs

@@ -0,0 +1,117 @@
+import { readFileSync, existsSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { checkToken, checkSkills, resolveBase, resolveTokenSource } from './diagnose.mjs'
+import { renderRenameNotice } from './rename_notice.mjs'
+
+// `npx @theronap/cortex-mcp doctor` — a live, one-command health check.
+//
+// This is the "is it ACTUALLY working?" tool that was missing: it reads your token, calls the
+// real Agnoclast API, and prints a clear PASS/FAIL with the actual cause. No Claude Code restart
+// needed — so onboarding can confirm the connection independently of "did the server load."
+
+// Token resolution: env first, then the Claude config the setup command wrote (so `doctor`
+// works the moment after `setup`, before any restart). Returns { token, source }.
+// Exported so `use-brain` resolves the token EXACTLY as doctor/status do. There is already a second,
+// subtly different copy of this in context_log.mjs (returns a bare token, not {token, source}); a
+// third copy is how a machine ends up "connected" to one command and "no token found" to another.
+export const resolveToken = resolveTokenSource
+
+// `status` — the one-line SessionStart variant of doctor: a visible "is Agnoclast capturing?"
+// signal inside Claude Code itself (three-machine dry-run finding 2026-06-09: with no
+// indicator, a user can't tell whether their sessions are flowing to the org).
+// Always returns 0 — a status line must never break a session start.
+export async function runStatus() {
+  const base = resolveBase(process.env.CORTEX_URL)
+  const out = (m) => process.stdout.write(m + '\n')
+  const { token } = resolveToken()
+  if (!token) {
+    out('Agnoclast: NOT connected — no token found. Run: npx -y @theronap/cortex-mcp setup <token>')
+    return 0
+  }
+  try {
+    const r = await checkToken(token, base)
+    if (r.ok) {
+      // ⚠ THE NOTICE REPLACES THE HAPPY LINE RATHER THAN FOLLOWING IT.
+      // "connected — sessions on this machine are captured to your org" was printed truthfully to
+      // three people whose sessions were, at that moment, landing in NO brain: connected is a fact
+      // about the TOKEN, and every reader takes it as a fact about their WORK. Printing both would
+      // leave the reassurance that caused four days of silent loss sitting directly above the
+      // warning that contradicts it.
+      if (r.captureNotice?.message) {
+        out(`Agnoclast: ⚠ ${r.captureNotice.message}`)
+        return 0
+      }
+      const n = typeof r.projectCount === 'number' ? ` · ${r.projectCount} project${r.projectCount === 1 ? '' : 's'} visible` : ''
+      out(`Agnoclast: connected — sessions on this machine are captured to your org${n}.`)
+      // TEMPORARY (ADR-0033 T7) — delete with lib/rename_notice.mjs a release after C2.
+      // This one FOLLOWS the happy line rather than replacing it, unlike captureNotice above. The
+      // rule there exists because captureNotice CONTRADICTS the reassurance ("connected" was true
+      // while the work was landing nowhere). This does not contradict anything: the connection is
+      // genuinely fine and a rename is separately scheduled. Replacing the status line with it would
+      // hide a fact the reader needs in order to report a real problem.
+      const notice = renderRenameNotice(resolveToken().key)
+      if (notice) out(notice)
+    } else {
+      out(`Agnoclast: NOT connected — ${r.diagnosis?.message ?? 'check failed'}. Run: npx -y @theronap/cortex-mcp doctor`)
+    }
+  } catch (e) {
+    out(`Agnoclast: status check failed (${e?.message ?? String(e)}) — run doctor.`)
+  }
+  return 0
+}
+
+export async function runDoctor() {
+  const base = resolveBase(process.env.CORTEX_URL)
+  const out = (m) => process.stdout.write(m + '\n')
+
+  out('')
+  out('Agnoclast doctor — checking your connection…')
+  const { token, source } = resolveToken()
+  out(`  token source: ${source ?? 'NONE FOUND'}`)
+  out(`  endpoint:     ${base}`)
+  out('')
+
+  const r = await checkToken(token, base)
+
+  if (r.ok) {
+    out('  ✓ context   — your token authenticates and Agnoclast returned your context.')
+    if (typeof r.projectCount === 'number') out(`    You can currently see ${r.projectCount} project(s).`)
+    if (r.requestId) out(`    (request id: ${r.requestId})`)
+
+    // A SECOND surface, because one endpoint answering is not "the system is healthy". /api/skills
+    // 409'd every multi-brain caller for three days while this command printed PASS on the strength
+    // of /api/mcp-context alone. See checkSkills' header for the full record.
+    const s = await checkSkills(token, base)
+    if (s.ok) {
+      const n = typeof s.skillCount === 'number'
+        ? ` (${s.skillCount} org skill${s.skillCount === 1 ? '' : 's'} published)` : ''
+      out(`  ✓ skills    — the org-skill surface answers${n}.`)
+    } else {
+      // NOT a total failure — context works, so capture and retrieval are fine. But it must never
+      // again render as PASS, because org skills silently stop updating when this breaks.
+      out(`  ✗ skills    — ${s.diagnosis?.kind ?? 'error'}${s.status ? ` (HTTP ${s.status})` : ''}`)
+      out(`    ${s.diagnosis?.message ?? 'unknown error'}`)
+      out('')
+      out('  ⚠ PARTIAL — your connection is fine and capture/retrieval work, but org-published')
+      out('    skills cannot be fetched, so they will silently stop updating (the client falls')
+      out('    back to its last-good cache). Report this rather than ignoring it.')
+      out('')
+      return 1
+    }
+
+    out('')
+    out('  ✓ PASS — every surface checked is answering.')
+    out('')
+    out('  If your AI still does not see Agnoclast, the server just is not loaded yet —')
+    out('  fully quit and reopen Claude Code (the MCP server starts on launch).')
+    out('')
+    return 0
+  }
+
+  out(`  ✗ FAIL — ${r.diagnosis?.kind ?? 'error'}${r.status ? ` (HTTP ${r.status})` : ''}`)
+  out(`    ${r.diagnosis?.message ?? 'unknown error'}`)
+  if (r.diagnosis?.retriable) out('    This looks transient — running `doctor` again shortly may succeed.')
+  out('')
+  return 1
+}