@theronap/cortex-mcp 0.9.53 → 0.9.55

package/lib/editors/claude.mjs

@@ -28,7 +28,7 @@ export function mergeClaudeMcp(existing, spec, token) {
 export const CORTEX_ALLOWED_TOOLS = [
   // read surface
   'grep', 'read_page', 'my_context', 'project_status', 'session_context', 'search_org',
-  'list_records', 'page_history', 'timeline_pull', 'my_brains', 'my_sessions', 'writing_style',
+  'list_records', 'page_history', 'page_diff', 'timeline_pull', 'my_brains', 'my_sessions', 'writing_style',
   'code_graph_query', 'my_retier_notices', 'list_page_grants', 'file_requests', 'page_merge_requests',
   // live authoring core
   'authoring_context', 'author', 'log_session',

package/lib/server.mjs

@@ -499,7 +499,15 @@ export async function runServer(version) {
       const day = (d) => (d ? String(d).slice(0, 10) : '')
       const renderMatch = (m, tagBrain) => {
         const blocks = m.tiers.map((t) => {
-          const secs = (t.sections ?? []).map((s) => `### ${s.heading}\n${s.body}`).join('\n\n')
+          const secs = (t.sections ?? []).map((s) => {
+            // Undefined is an older-server response during a rolling deploy: do
+            // not invent a currency verdict until this server has computed one.
+            const currency = s.hasExplicitDate === false
+              ? '\n⚠ **Undated section — verify before relying on its claims.**\n'
+              : ''
+            const asOf = s.asOf ? ` · as of ${day(s.asOf)}` : ''
+            return `### ${s.heading}${asOf}${currency}${s.body}`
+          }).join('\n\n')
           // ADR-0018: a null version isn't "nothing to show" — it means this variant predates content-
           // hash tracking (a 2026-06-29 import scar) and CANNOT be re-authored via base_version until an
           // admin backfills it. Silently omitting the line here is exactly what sent callers into an
@@ -556,10 +564,78 @@ export async function runServer(version) {
       if (!revs.length) return { content: [{ type: 'text', text: `"${name}" (${k}) has no recorded version history yet.` }] }
       const lines = revs.map((r) => {
         const who = r.actor_name ? ` · ${r.actor_name}` : ''
+        // change_kind first and bracketed so a column of [correct] is scannable — the whole point is
+        // that a page with repeated corrections looks different at a glance from one that only grew.
+        const what = r.change_kind ? ` · [${r.change_kind}]` : ''
         const why = r.reason ? ` — ${r.reason}` : ''
-        return `- rev ${r.rev_no} · ${String(r.created_at).slice(0, 10)} · ${r.op} · ${r.tier}${who}${why}\n    version: ${r.content_hash}`
+        // Session keys run up to 200 chars; a short prefix is enough to group a session's edits and to
+        // hand to a human. Null on every pre-2026-07-27 revision — render nothing rather than "none",
+        // so "not recorded" never reads as "recorded as empty".
+        const sess = r.session_key ? `\n    session: ${String(r.session_key).slice(0, 24)}` : ''
+        return `- rev ${r.rev_no} · ${String(r.created_at).slice(0, 10)} · ${r.op}${what} · ${r.tier}${who}${why}\n    version: ${r.content_hash}${sess}`
       })
-      return { content: [{ type: 'text', text: `# ${name} — page history (newest first)\n${lines.join('\n')}\n\n— \`read_page "${name}"\` with version:<rev_no|version> to view an old body; \`rollback_page\` to restore one.` }] }
+      const anyKind = revs.some((r) => r.change_kind)
+      const hint = anyKind
+        ? `\n— \`page_diff "${name}"\` to see exactly what a revision changed.`
+        : `\n— Revisions written before 2026-07-27 carry no reason/change_kind — that is "not recorded", not "no reason".`
+      return { content: [{ type: 'text', text: `# ${name} — page history (newest first)\n${lines.join('\n')}\n\n— \`read_page "${name}"\` with version:<rev_no|version> to view an old body; \`rollback_page\` to restore one.${hint}` }] }
+    },
+  )
+
+  server.registerTool(
+    'page_diff',
+    {
+      title: 'See exactly what an edit changed',
+      description: 'Show WHAT CHANGED between two versions of an authored wiki page — which sections were added, removed or rewritten, plus the reason and change_kind recorded for the edit. Use it when page_history tells you an edit happened and you need to know what it actually did: before trusting a claim that was recently rewritten, when auditing whether a "correct" edit really fixed something, or before rollback_page so you know what you would be undoing. `from` defaults to the version immediately before `to`, so passing just `to` answers "what did this one edit change?". RLS-scoped: you can diff only pages you may read.',
+      inputSchema: {
+        name: z.string().describe('the canonical node name exactly as written (e.g. "Agnoclast")'),
+        kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('node kind (default project)'),
+        to: z.string().describe('the NEWER version: a rev_no (e.g. "6") or a content_hash, from page_history'),
+        from: z.string().optional().describe('the OLDER version to compare against. Omit to use the revision immediately before `to` — which is what you want for "what did this edit change?"'),
+        lines: z.boolean().optional().describe('also show line-level +/- within each changed section. Off by default: the section-level answer is usually what you want and is far shorter.'),
+      },
+    },
+    async ({ name, kind, to, from, lines }) => {
+      const k = kind ?? 'project'
+      let res
+      try {
+        const qs = new URLSearchParams({
+          kind: k, key: name, to,
+          ...(from ? { from } : {}), ...(lines ? { lines: '1' } : {}),
+        })
+        res = await fetchCortex(`${BASE}/api/brain/page-diff?${qs}`, { headers: { Authorization: `Bearer ${TOKEN}` } })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not diff "${name}": ${e.message}` }] }
+      }
+      if (res.status === 404) return { content: [{ type: 'text', text: `No ${k} named "${name}", or it has no version "${to}". Run \`page_history "${name}"\` to list its versions.` }] }
+      if (!res.ok) {
+        const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
+        return { content: [{ type: 'text', text: `Could not diff "${name}": ${d.message}` }] }
+      }
+      const out = await res.json()
+      const d = out.diff
+      const head = d.from.revNo === 0
+        ? `# ${name} — rev ${d.to.revNo} (first version)`
+        : `# ${name} — rev ${d.from.revNo} → rev ${d.to.revNo}`
+      const meta = []
+      meta.push(`${String(d.to.createdAt).slice(0, 10)} · ${d.to.op}${d.to.changeKind ? ` · [${d.to.changeKind}]` : ''}${d.to.actorName ? ` · ${d.to.actorName}` : ''}`)
+      if (d.to.reason) meta.push(`reason: ${d.to.reason}`)
+      if (d.to.sessionKey) meta.push(`session: ${String(d.to.sessionKey).slice(0, 24)}`)
+      const body = []
+      if (d.summaryChanged) body.push('- summary: CHANGED')
+      for (const h of d.sections.added) body.push(`- + added section: ${h}`)
+      for (const h of d.sections.removed) body.push(`- − removed section: ${h}`)
+      for (const c of d.sections.changed) {
+        body.push(`- ~ changed section: ${c.heading}`)
+        // Cap the rendered hunk. A section body can be 65k chars; dumping a full rewrite into a tool
+        // result buries the signal and burns the reader's context for no gain.
+        for (const l of (c.lines ?? []).slice(0, 40)) body.push(`    ${l.kind === 'add' ? '+' : '−'} ${l.line}`)
+        if ((c.lines?.length ?? 0) > 40) body.push(`    … ${c.lines.length - 40} more changed lines`)
+      }
+      if (!body.length) body.push('- no section or summary changes (metadata-only revision, e.g. a re-tier)')
+      const tail = d.sections.unchangedCount ? `\n\n${d.sections.unchangedCount} section(s) unchanged.` : ''
+      const hint = lines ? '' : '\n— Pass `lines: true` to see the actual changed lines within each section.'
+      return { content: [{ type: 'text', text: `${head}\n${meta.join(' · ')}\n\n${body.join('\n')}${tail}${hint}` }] }
     },
   )
 
@@ -648,7 +724,7 @@ export async function runServer(version) {
     'my_brains',
     {
       title: 'List your brains + which one writes land in',
-      description: 'List the brains (orgs/workspaces) you belong to and show which one is your ACTIVE WRITE brain — where author/log_session/capture currently land. Reads span all your brains; writes go to the active one. Use this to see your options before set_active_brain, or when a session seems to belong to a different brain than the one you are writing to.',
+      description: 'List the brains (orgs/workspaces) you belong to. Reads span ALL of them, and writes to an EXISTING page now resolve to the brain that holds it — you do NOT need to check or switch anything before authoring, and you should not. The active brain is only a default for creating a page that exists nowhere yet. Use this when you genuinely need to see what brains exist or how they are populated.',
       inputSchema: {},
     },
     async () => {
@@ -676,13 +752,13 @@ export async function runServer(version) {
       // Which layer is deciding, and what clearing it would fall back to — otherwise the pointer
       // confusion simply reappears one level down.
       const note = !activeIsExplicit
-        ? '\n(active brain is the default — you have one brain; set_active_brain once you hold more.)'
+        ? '\n(you have one brain; nothing to choose.)'
         : activeSource === 'session'
           ? `\n(this SESSION's override — your other sessions are unaffected${accountOrgId && accountOrgId !== sessionOrgId ? `; clearing it falls back to ${accountOrgId}` : ''}.)`
           : activeSource === 'account'
             ? '\n(account-wide pointer — shared by every session that has not set its own.)'
             : ''
-      return { content: [{ type: 'text', text: `Your brains (▶ = writes land here):\n${lines.join('\n')}${note}` }] }
+      return { content: [{ type: 'text', text: `Your brains (▶ = default for NEW pages only — edits to existing pages route themselves):\n${lines.join('\n')}${note}` }] }
     },
   )
 
@@ -724,8 +800,8 @@ export async function runServer(version) {
   server.registerTool(
     'set_active_brain',
     {
-      title: 'Choose the brain your writes go to',
-      description: "Point your writes (author / log_session / capture) at one of your brains, by its org id (from my_brains). Pass org_id = null to clear it. You can only select a brain you are a member of. SCOPE: 'session' (default) changes ONLY this session — other windows you have open keep writing where they were, which is almost always what you want. 'account' changes the sticky person-wide pointer, which redirects every other session that has not set its own.",
+      title: 'Set the default brain for NEW pages',
+      description: "RARELY NEEDED — do not reach for this reflexively. Editing an EXISTING page routes itself: author/set_page_validity/rollback resolve the brain from the page (via base_version, ref, or name), so switching first is unnecessary and switching WRONG is now impossible to cause. This only sets the default for creating a page that exists in NO brain yet, and for log_session/capture. If you find yourself about to call this so an edit lands correctly, don't — just author; it will find the page. Pass org_id = null to clear. SCOPE: 'session' (default) changes ONLY this session; 'account' changes the person-wide pointer and redirects every other open session that has not set its own.",
       inputSchema: {
         org_id: z.string().nullable().describe('the org id of the brain to write to (from my_brains), or null to clear the pointer'),
         scope: z.enum(['session', 'account']).optional()
@@ -764,7 +840,7 @@ export async function runServer(version) {
     'create_brain',
     {
       title: 'Create a new brain under your existing account',
-      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; use set_active_brain afterward to point writes at it (creating it does not switch your active write brain automatically).',
+      description: 'Create a brand-new brain (org/workspace) — a fully independent knowledge graph — under your EXISTING account. No new login, no new email/password: this adds a second membership to the account you are already using. Reads never cross brains; new pages default to your active brain, so use set_active_brain if you want NEW pages to land in this one; edits to existing pages always route to whichever brain holds them.',
       inputSchema: { name: z.string().describe('display name for the new brain, e.g. "Cortex Codebase"') },
     },
     async ({ name }) => {
@@ -783,7 +859,7 @@ export async function runServer(version) {
         return { content: [{ type: 'text', text: `Could not create brain: ${d.message}` }] }
       }
       const r = await res.json()
-      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Run set_active_brain with this org_id to start writing to it — reads already span it automatically.` }] }
+      return { content: [{ type: 'text', text: `Created brain "${name}" [${r.orgId}]. Reads already span it. Edits to pages in it route themselves; set_active_brain only if you want NEW pages to default here.` }] }
     },
   )
 
@@ -1307,7 +1383,7 @@ export async function runServer(version) {
     {
       title: 'Authoring context (call before author)',
       description:
-        'Fetch the scaffolding to author a Cortex wiki node: the canonical NAMESPACE (existing node names — link to these with the EXACT name inside [[ ]]) and the node-type CONNECTION RULES (what kinds of links to look for). ALWAYS call this BEFORE `author` so the page links to real nodes by their established names instead of minting synonyms. Reference a node in the namespace as [[Name]]; if you reference something real that is NOT in the namespace, still write [[Name]] — that is a red-link marking a node worth creating. If the page IS about a specific code repo or chat channel, also stamp it once — [[repo:owner/name]] or [[channel:name]] (lowercase, no #) — identifier join keys, not page links.',
+        'Fetch the scaffolding to author a Cortex wiki node: the canonical NAMESPACE (current node names — link to these with the EXACT name inside [[ ]]), any deliberately RETIRED page names and their successors, and the node-type CONNECTION RULES. ALWAYS call this BEFORE `author` so the page links to current knowledge rather than minting synonyms or reviving a retired page. Reference a node in the namespace as [[Name]]; if you reference something real that is NOT in the namespace, still write [[Name]] — that is a red-link marking a node worth creating. If the page IS about a specific code repo or chat channel, also stamp it once — [[repo:owner/name]] or [[channel:name]] (lowercase, no #) — identifier join keys, not page links.',
       inputSchema: {
         kind: z.enum(['project', 'person', 'org', 'user']).optional().describe('the node type you are about to author (default project)'),
       },
@@ -1324,12 +1400,17 @@ export async function runServer(version) {
         const d = classify(res.status, res.headers.get('content-type'), await res.text(), res.headers.get('x-vercel-id'))
         return { content: [{ type: 'text', text: `Could not fetch authoring context: ${d.message}` }] }
       }
-      const { connectionRules, namespace } = await res.json()
+      const { connectionRules, namespace, retiredLinks } = await res.json()
       const ns = Array.isArray(namespace) ? namespace : []
       const nsList = ns.map((n) => `[[${n}]]`).join(', ')
+      const retired = Array.isArray(retiredLinks) ? retiredLinks : []
+      const retiredList = retired.length
+        ? `\n\nRETIRED PAGES — do not treat these as current or author over them: ${retired.map((r) => `[[${r.name}]] (${r.validity}${r.supersededBy ? ` → [[${r.supersededBy}]]` : ''})`).join(', ')}`
+        : ''
       const text =
         `Authoring a "${k}" node. Connection rules (kinds of links to look for):\n${connectionRules}\n\n` +
         `NAMESPACE — ${ns.length} existing nodes; link with the EXACT name inside [[ ]]:\n${nsList}\n\n` +
+        retiredList +
         `Now author the page (summary + sections) with inline [[links]] woven into the prose. Link, do not restate. ` +
         `For something real that is not in this namespace, still write [[Name]] (a red-link). Then call \`author\`.`
       return { content: [{ type: 'text', text }] }
@@ -1352,9 +1433,11 @@ export async function runServer(version) {
         })).describe('3-5 sections; the page body'),
         tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('visibility tier. Omit for the safe default: scoped (you + your management chain) on nodes that support it — your user page, projects you own-scope — and accessible elsewhere (person/org pages are the shared wiki). Pass accessible explicitly when the page is meant for the whole org.'),
         base_version: z.string().optional().describe('the `version` hash shown when you read this page (read_page) — REQUIRED when updating an existing page, so a concurrent edit is caught instead of clobbered. Omit only for a brand-new node. If the save returns "stale" or "read first", read_page again and retry with the fresh version.'),
+        reason: z.string().describe('WHY you are making this edit, in one short phrase — recorded permanently in page_history so a later reader can tell a routine addition from a correction. Say what CHANGED and what prompted it ("Ben pilot abandoned per Theron 07-17", "corrected: 0069 already widened the CHECK"), not what you did ("updated page"). This is the field that makes staleness auditable.'),
+        change_kind: z.enum(['add', 'correct', 'supersede', 'expand', 'retire']).optional().describe('what KIND of edit: "add" (new information), "correct" (the page said something FALSE — the currency-critical one), "supersede" (was true, now outdated by events), "expand" (elaborates, no claim changed), "retire" (putting the page or a section to rest). Be honest with "correct" — a page whose history shows repeated corrections is a page whose claims need checking, and that signal is the point.'),
       },
     },
-    async ({ kind, name, summary, sections, tier, base_version }) => {
+    async ({ kind, name, summary, sections, tier, base_version, reason, change_kind }) => {
       // No client-side tier default — the server computes the per-kind safe default (page-privacy
       // T4/D10) so version-pinned installs can't bake a stale policy.
       const pages = [{ ...(tier ? { tier } : {}), summary, base_version, sections: Array.isArray(sections) ? sections : [] }]
@@ -1363,7 +1446,7 @@ export async function runServer(version) {
         res = await fetchCortex(`${BASE}/api/brain/author`, {
           method: 'POST',
           headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
-          body: JSON.stringify({ kind, name, pages }),
+          body: JSON.stringify({ kind, name, pages, reason, change_kind }),
         })
       } catch (e) {
         return { content: [{ type: 'text', text: `Could not author "${name}": ${e.message}` }] }
@@ -1374,11 +1457,13 @@ export async function runServer(version) {
       }
       const out = await res.json()
       const blue = out?.links?.blue ?? 0
+      const retired = out?.links?.retired ?? 0
       const red = out?.links?.red ?? 0
       const redList = Array.isArray(out?.redLinks) && out.redLinks.length ? `\nRed-links (wanted nodes): ${out.redLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
+      const retiredList = Array.isArray(out?.retiredLinks) && out.retiredLinks.length ? `\nRetired links (not current or wanted): ${out.retiredLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
       const stamps = Array.isArray(out?.identifiers) && out.identifiers.length ? `\nIdentifier stamps (join keys): ${out.identifiers.map((i) => `[[${i}]]`).join(', ')}` : ''
       const verb = out?.created ? 'Created + authored' : 'Authored'
-      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${red} red.${redList}${stamps}`
+      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${retired} retired, ${red} red.${retiredList}${redList}${stamps}`
         : `No change to "${name}"${out?.skipped?.length ? ` (${out.skipped.join(', ')})` : ''}.`
       return { content: [{ type: 'text', text: note }] }
     },

package/package.json

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