@theronap/cortex-mcp 0.9.57 → 0.9.59

package/lib/server.mjs

@@ -518,7 +518,14 @@ export async function runServer(version) {
           const head = `[${t.tier}${day(t.updated_at) ? ` · authored ${day(t.updated_at)}` : ''}${t.validity && t.validity !== 'current' ? ` · ${t.validity}` : ''}${versionLine}]`
           return [head, t.summary, secs].filter(Boolean).join('\n')
         })
-        let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — re-author just those sections now with \`author\` (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). Pass this page's \`version\` as base_version when you re-author — if the save comes back stale, the page changed under you: re-read, then re-author. Reading a stale page you can fix IS the trigger to fix it. Re-authoring is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it.\n— Citing code? Use a SYMBOL and file (\`formConnections\` in \`web/app/api/ingest/route.ts\`), never a line number — line numbers drift with every commit above them. And cite only what you opened THIS session; re-emitting a reference you read on another page is how a stale claim gains a second source and starts looking corroborated.`
+        // REPAIR TOOL (2026-07-31). This footer used to say "re-author just those sections with
+        // `author`" — which `author` cannot do: computeDroppedSections rejects a partial-section
+        // write unconditionally, and the 409 then hands back every section's body, so the advice
+        // routed the reader straight into retyping the whole page. Measured 2026-07-30: one such
+        // retype silently deleted a sentence, a [[link]] (a graph edge), a command list and the
+        // word "today" from sections it was never meant to touch. This footer renders on EVERY
+        // page read in the system, so it was the single widest surface pointing the wrong way.
+        let footer = `— Follow any [[links]] above with read_page to go deeper.\n— If you hold fresher FIRST-HAND truth than this page — something you established THIS session (ran the command, made the change, hold the artifact) that a section here gets concretely wrong — fix just that passage with \`edit_page\`: quote the wrong text as old_string and pass this page's \`version\` as base_version (any node you are permitted to edit; concise; a material contradiction, not merely extra detail). If the save comes back stale the page changed under you — the conflict hands back what changed, so re-anchor from that instead of re-reading. Reading a stale page you can fix IS the trigger to fix it. Editing is pre-authorized — do NOT ask the user before updating (edits are versioned + reversible via page_history/rollback_page); update, then briefly report it. Use \`author\` only to CREATE a page or rewrite one wholesale: it re-emits every section, so untouched sections get retyped on the way through and drift.\n— Citing code? Use a SYMBOL and file (\`formConnections\` in \`web/app/api/ingest/route.ts\`), never a line number — line numbers drift with every commit above them. And cite only what you opened THIS session; re-emitting a reference you read on another page is how a stale claim gains a second source and starts looking corroborated.`
         // slice 4: when the page carries identifier stamps, the history projection is one flag away.
         const allBody = m.tiers.flatMap((t) => (t.sections ?? []).map((s) => s.body)).join('\n')
         const stamps = [...new Set((allBody.match(/\[\[repo:[a-z0-9][a-z0-9-]*\/[a-z0-9_.-]+\]\]/gi) ?? []).map((s) => s.toLowerCase()))]
@@ -670,6 +677,121 @@ export async function runServer(version) {
     },
   )
 
+  server.registerTool(
+    'rename_section',
+    {
+      title: 'Rename one section heading on a wiki page',
+      description: 'Rename ONE section\'s heading on a wiki page, in place. Use this instead of re-authoring the page: `author` cannot express a rename, because a section\'s IDENTITY is its heading string — sending a new title reads as "dropped the old section, added a new one" and is rejected 409 would_drop_sections. This route changes the heading and NOTHING else: the section keeps its body, its position, and crucially its as-of date, so renaming does not reset the currency stamp on a claim nobody re-verified. It is also the ONLY way to fix a heading longer than the 80-char limit, which cannot be re-authored at all. Requires base_version (the `version` read_page prints) — that is also how it finds the right brain, so it can never rename on the wrong one. Refuses, rather than guessing, when the page exists at several tiers, when the heading repeats, or when the new heading is already taken.',
+      inputSchema: {
+        name: z.string().describe('the exact page name, as read_page shows it'),
+        from: z.string().describe('the CURRENT heading, exactly as stored (match is case- and whitespace-insensitive)'),
+        to: z.string().describe('the new heading. Max 80 chars. Must not already be used by another section on this page.'),
+        base_version: z.string().describe('the `version` read_page prints for this page (64-hex). REQUIRED — it is the concurrency check AND how the right brain is resolved. A per-SECTION hash is not valid here.'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('only when the page exists at MORE THAN ONE tier — which one to rename in. A rename never moves content between tiers.'),
+        ordinal: z.number().optional().describe('only when the same heading appears more than once on the page — which occurrence to rename (the error lists the ordinals).'),
+        reason: z.string().optional().describe('why you are renaming it — recorded in page_history like any other edit'),
+      },
+    },
+    async ({ name, from, to, base_version, tier, ordinal, reason }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/rename-section`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            name, from, to, base_version,
+            ...(tier ? { tier } : {}), ...(ordinal !== undefined ? { ordinal } : {}),
+            ...(reason ? { reason } : {}),
+          }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not rename the section: ${e.message}` }] }
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        // Surface the server's hint AND the disambiguators it named, so a 409 is directly actionable
+        // rather than something to retry blindly.
+        const extra = [
+          out?.detail ? `existing: ${out.detail}` : '',
+          Array.isArray(out?.tiers) ? `tiers: ${out.tiers.join(', ')}` : '',
+          Array.isArray(out?.ordinals) ? `ordinals: ${out.ordinals.join(', ')}` : '',
+          out?.currentVersion ? `current version: ${out.currentVersion}` : '',
+        ].filter(Boolean).join(' · ')
+        const hint = out?.hint ? `\n${out.hint}` : ''
+        return { content: [{ type: 'text', text: `Could not rename "${from}" on "${name}": ${out?.error ?? res.status}${extra ? `\n${extra}` : ''}${hint}` }] }
+      }
+      return { content: [{ type: 'text', text: `Renamed on "${name}" (${out.brain} · ${out.tier} tier): "${out.from}" -> "${out.to}". The section kept its body, position and as-of date. New version: ${out.version}` }] }
+    },
+  )
+
+  server.registerTool(
+    'edit_page',
+    {
+      title: 'Change one passage on a wiki page (use this, not author, to fix something)',
+      description:
+        'THE DEFAULT WAY TO CORRECT A PAGE. Replaces ONE passage inside ONE section, by quoting the exact text to replace — like editing a file, not rewriting it. Use this whenever you are fixing, updating or correcting something on an existing page; use `author` only when you are genuinely rewriting a page wholesale or creating one. WHY IT MATTERS: `author` takes the WHOLE page, so every section you did not mean to touch gets retyped by you on the way through, and drifts. Measured 2026-07-30: an edit meant for one section silently deleted a sentence from another, along with a [[link]] — a lost graph edge. Text you never send cannot be damaged. Anchors match the STORED body, so quote from what read_page shows as the section body; if a match fails on whitespace the error tells you so. An anchor matching twice is REFUSED, never guessed — quote more surrounding text. On a stale-version conflict you get the target section back so you can re-anchor without re-reading the page.',
+      inputSchema: {
+        name: z.string().describe('the exact page name, as read_page shows it'),
+        heading: z.string().describe('the heading of the section containing the text you are changing'),
+        old_string: z.string().describe('the exact text to replace. Must appear EXACTLY ONCE within that section — if it repeats, quote more surrounding text to make it unique.'),
+        new_string: z.string().describe('what to replace it with. May be empty, which deletes the anchored text.'),
+        base_version: z.string().describe('the `version` read_page prints for this page (64-hex). REQUIRED — it is the concurrency check AND how the right brain is resolved.'),
+        reason: z.string().describe('WHY you are making this change, in one short phrase — recorded in page_history exactly like an author edit.'),
+        tier: z.enum(['accessible', 'scoped', 'confidential']).optional().describe('only when the page exists at MORE THAN ONE tier — which one to edit. An edit never moves content between tiers.'),
+        ordinal: z.number().optional().describe('only when the same heading appears more than once on the page — which occurrence (the error lists the ordinals).'),
+      },
+    },
+    async ({ name, heading, old_string, new_string, base_version, reason, tier, ordinal }) => {
+      let res
+      try {
+        res = await fetchCortex(`${BASE}/api/brain/edit-page`, {
+          method: 'POST',
+          headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            name, heading, old_string, new_string, base_version, reason,
+            ...(tier ? { tier } : {}), ...(ordinal !== undefined ? { ordinal } : {}),
+          }),
+        })
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Could not edit "${name}": ${e.message}` }] }
+      }
+      const out = await res.json().catch(() => null)
+      if (!res.ok) {
+        // Every failure here is meant to be directly actionable — the caller should be able to fix and
+        // retry from this text alone, without re-reading the page.
+        const bits = [
+          Array.isArray(out?.available) ? `sections on this page: ${out.available.join(' | ')}` : '',
+          Array.isArray(out?.tiers) ? `tiers: ${out.tiers.join(', ')}` : '',
+          Array.isArray(out?.ordinals) ? `ordinals: ${out.ordinals.join(', ')}` : '',
+          out?.count ? `matches: ${out.count}` : '',
+          out?.whitespaceNear === true ? 'YOUR TEXT IS PRESENT but the whitespace differs — re-copy it from the stored body' : '',
+          out?.currentVersion ? `current version: ${out.currentVersion}` : '',
+        ].filter(Boolean).join('\n')
+        const cur = out?.currentSectionBody
+          ? `\n\n--- the section as it stands now (re-anchor against this) ---\n${out.currentSectionBody}`
+          : ''
+        // B5: what ANOTHER session changed elsewhere on this page while you were working. Rendered
+        // INLINE, not as a pointer to page_diff — a pointer is something a busy agent skips, and the
+        // whole point is that you cannot be ignorant of it.
+        const cc = Array.isArray(out?.concurrentChanges) && out.concurrentChanges.length
+          ? '\n\n--- changed elsewhere on this page since you read it (READ THIS before retrying) ---\n' +
+            out.concurrentChanges.map((c) =>
+              `§ ${c.heading}\n${(c.lines ?? []).map((l) => `${l.kind === 'add' ? '+' : '-'} ${l.line}`).join('\n')}`,
+            ).join('\n\n')
+          : ''
+        const ccMeta = [
+          Array.isArray(out?.concurrentAdded) && out.concurrentAdded.length ? `sections ADDED elsewhere: ${out.concurrentAdded.join(', ')}` : '',
+          Array.isArray(out?.concurrentRemoved) && out.concurrentRemoved.length ? `sections REMOVED elsewhere: ${out.concurrentRemoved.join(', ')}` : '',
+          Array.isArray(out?.concurrentTruncated) && out.concurrentTruncated.length ? `(truncated, see page_diff for all of: ${out.concurrentTruncated.join(', ')})` : '',
+        ].filter(Boolean).join('\n')
+        return { content: [{ type: 'text', text: `Could not edit "${name}": ${out?.error ?? res.status}${out?.hint ? `\n${out.hint}` : ''}${bits ? `\n${bits}` : ''}${ccMeta ? `\n${ccMeta}` : ''}${cc}${cur}` }] }
+      }
+      const red = Array.isArray(out.redLinks) && out.redLinks.length
+        ? `\nRed-links now on this page: ${out.redLinks.map((r) => `[[${r}]]`).join(', ')}` : ''
+      return { content: [{ type: 'text', text: `Edited "${name}" (${out.brain} · ${out.tier} tier) § ${out.heading}. Only that passage changed; every other section is byte-identical. New version: ${out.version}${red}` }] }
+    },
+  )
+
   server.registerTool(
     'writing_style',
     {
@@ -1462,9 +1584,20 @@ export async function runServer(version) {
       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(', ')}` : ''
+      // TIER RETARGET — say it out loud. The server has always computed these (AuthorResult.tierCorrections)
+      // and its own comment says corrections are "surfaced (not hidden)", but nothing ever printed them, so
+      // the intent died at the client. That silence is not cosmetic: on 2026-07-29 a correction to
+      // cortex-cross-editor-hub landed on the SCOPED tier while the accessible tier kept serving a claim
+      // known to be false, and the response said only "Authored (1 tier)". Whoever reads this line is the
+      // last chance to notice a page was fixed somewhere nobody reads.
+      const corrections = Array.isArray(out?.tierCorrections) && out.tierCorrections.length
+        ? `\n⚠ TIER: this wrote to ${out.tierCorrections.map((c) => `${c.actualTier} (you asked for ${c.requestedTier})`).join('; ')}.` +
+          ` If that is not the tier you meant, read_page and check which copy you just changed —` +
+          ` a page can exist at several tiers and they drift apart independently.`
+        : ''
       const verb = out?.created ? 'Created + authored' : 'Authored'
-      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(', ')})` : ''}.`
+      const note = out?.built ? `${verb} "${name}" (${out.built} tier${out.built === 1 ? '' : 's'}). Links: ${blue} resolved, ${retired} retired, ${red} red.${corrections}${retiredList}${redList}${stamps}`
+        : `No change to "${name}"${out?.skipped?.length ? ` (${out.skipped.join(', ')})` : ''}.${corrections}`
       return { content: [{ type: 'text', text: note }] }
     },
   )

package/package.json

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

package/skills/author-docs/SKILL.md

@@ -24,8 +24,25 @@ the doc and author a synthesis. Never dump raw markdown into a page.
 1. **Detect:** run `npx -y @theronap/cortex-mcp docs-scan --json`. If `pending` is empty, stop —
    report nothing. (If no roots are registered and you just wrote docs somewhere, suggest
    `docs-scan --add-root <dir>` to the user once; don't nag.)
-2. **Author each pending doc** (skip any you judge non-substantive — scratch notes, generated
-   output; leave them unmarked and say so):
+2. **Triage each pending doc into exactly ONE of three dispositions.** Every pending doc gets one —
+   there is no fourth "deal with it later" state:
+   - **AUTHOR** it (below), then mark it.
+   - **ABSORBED** — the doc is substantive, but an existing page *already covers it as well or
+     better*. Common for build-notes and handoffs: the page kept getting updated while the doc
+     stayed frozen at its writing date. Authoring it again would duplicate, or worse, overwrite a
+     current page with a stale snapshot. **Mark it anyway** (`--mark`), and say which page absorbed
+     it. Do NOT leave it unmarked: it is genuinely handled, and leaving it pending makes every
+     future sweep re-read and re-litigate it. If the doc has one or two durable details the page
+     lacks, add just those to the page, then mark.
+   - **NON-SUBSTANTIVE** — scratch notes, generated output, throwaway logs. Leave unmarked and say
+     so, so a human can decide whether it should be registered at all.
+
+   ⚠ **A doc records the state at its writing date, never the state now.** Before writing any status
+   claim into a page, verify it against the code — a build-notes doc saying "NOT built yet" is
+   evidence about the past, not the present. Copying its status forward is the single most common way
+   this skill injects a false claim into the wiki.
+
+   To author:
    - Read the file. Decide the target node: a substantial standalone doc becomes its own
      project-kind node named by the doc's H1 title; a small note folds into its parent project's
      page as a section. Check the namespace first (`authoring_context`) — enrich an existing node
@@ -38,10 +55,14 @@ the doc and author a synthesis. Never dump raw markdown into a page.
      page just to add a link back to a doc. Fan-in is queryable (`grep "[[hub]]"` = backlinks;
      `read_page history:true` = the node's event ledger) — hub pages stay curated prose, and a doc
      belongs on the hub only when a human-judged synthesis mentions it.
-3. **Mark:** after each successful `author`, run
-   `npx -y @theronap/cortex-mcp docs-scan --mark <path>`. Never mark a doc whose author failed —
-   it should stay pending for the next sweep.
-4. **Report:** one short block — each doc → the page it became (or why skipped).
+3. **Mark:** run `npx -y @theronap/cortex-mcp docs-scan --mark <path>` for every doc you AUTHORED or
+   judged ABSORBED. Never mark a doc whose `author` failed — it must stay pending for the next sweep.
+4. **Verify before reporting.** For each doc you claim you authored, confirm the write actually landed
+   (`read_page` or `page_history`) — an `author` that returns "no change" when you intended an update
+   did NOT land. Never report a page you did not confirm.
+5. **Report:** one short block — each doc → the page it became, the page that absorbed it, or why it
+   was left unmarked. The count of pending docs should be zero afterwards except for the
+   non-substantive ones you deliberately left.
 
 ## Safety rules