brainllm 12.2.0 → 12.3.0

package/.env.example

@@ -17,7 +17,7 @@ TRILIUM_ETAPI_TOKEN=
 TRILIUM_PASSWORD=
 
 # ── Tool surface ───────────────────────────────────────────────────────────────
-# core (default): the 39 brain-aware tools. full: adds the 33 raw ETAPI tools.
+# core (default): the 44 brain-aware tools. full: adds the 33 raw ETAPI tools.
 # BRAINLLM_MODE=full
 
 # ── Timezone ───────────────────────────────────────────────────────────────────

package/README.md

@@ -10,7 +10,7 @@ A persistent, graph-structured second brain for Claude and any MCP client — bu
 
 [**brainllm site**](https://miisodev.github.io/BrainLLM/) · [How it works](https://miisodev.github.io/BrainLLM/how-it-works.html) · [Use cases](https://miisodev.github.io/BrainLLM/use-cases.html) · [Docs](https://miisodev.github.io/BrainLLM/docs.html)
 
-[![Version](https://img.shields.io/badge/version-12.2.0-f59e0b?style=flat-square)](https://github.com/miisodev/BrainLLM/releases)
+[![Version](https://img.shields.io/badge/version-12.3.0-f59e0b?style=flat-square)](https://github.com/miisodev/BrainLLM/releases)
 [![CI](https://img.shields.io/github/actions/workflow/status/miisodev/BrainLLM/ci.yml?branch=main&style=flat-square&label=CI&color=f59e0b)](https://github.com/miisodev/BrainLLM/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-a1a1aa?style=flat-square)](./LICENSE)
 [![Runtime: Bun](https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.0-a1a1aa?style=flat-square&logo=bun&logoColor=white)](https://bun.sh)
@@ -50,7 +50,8 @@ Placement, naming, labels, deduplication, relation bookkeeping, lifecycle aging,
 - **A visible graph** — `graph()` renders the whole relation graph (or any note's neighborhood) as a Mermaid flowchart, maintained as a native Trilium note.
 - **One-call day orientation** — `day()` serves the previous session, its change log, everything touched since, and the month's deliverables in a single call.
 - **Resilient plumbing** — every backend call is timeout-bounded with retry on idempotent reads; all writes are idempotent or duplicate-guarded, so crashes and retries never double-write; content surgery survives the editor's own HTML rewriting; renaming a domain cascades to everything inside it; the maintenance sweep heals drift it finds.
-- **Multi-agent by default** — all write-classified tools serialize behind a process-wide FIFO lock, so two agents (an interactive session and an automated run, say) writing through one hosted instance queue in arrival order instead of racing; reads stay fully parallel. Deletion catch-up in the daily log keeps a note deleted after its day's close from vanishing without a trace.
+- **Multi-agent by default** — all write-classified tools serialize behind a process-wide FIFO lock, so two agents (an interactive session and an automated run, say) writing through one hosted instance queue in arrival order instead of racing; reads stay fully parallel. Deletion catch-up in the daily log keeps a note deleted after its day's close from vanishing without a trace — and its window is configurable (`deletionCatchupDays` in the lifecycle policy), defaulting to Trilium's 7-day retention.
+- **Ask in prose, split on a seam** — `consistency(subject="…")` finds every note asserting about a fact however it is phrased, no regex guessing; `consistency(pattern, staleAfterDays=N)` surfaces figures held in exactly one untouched note, the ones that rot silently because nothing disagrees with them; `read(ids=[…])` batches a multi-note orientation into one round trip; and `split(noteId, sections=[…], into="…")` is the write half of the oversized-note problem — it lifts whole sections into a new note and leaves a pointer back. Information notes can carry a `#mandate` marker so a scoped session finds the one note it must obey without reading every note's prose.
 
 ---
 
@@ -193,13 +194,13 @@ Every tool declares whether it reads, writes, or destroys, so your client can gr
 
 The classification lives in one reviewable table ([`src/annotations.ts`](./src/annotations.ts)) rather than scattered across registrations, and its default is deliberately unsafe-side: a tool missing from the table is treated as a **write**, never a read, and says so at startup. Three are worth knowing because they look like reads and aren't — `start()` creates today's diary and session stubs, `session()` runs the maintenance sweep, and `graph()` writes the rendered graph note.
 
-### Core — universal verbs (32)
+### Core — universal verbs (34)
 
 | Group | Tools |
 |---|---|
 | Session lifecycle | `start` · `day` · `session` · `remarks` · `close` · `backup` |
-| Writing | `remember` · `diary` · `revise` · `resolve` · `withdraw` · `recover` |
-| Reading & search | `recall` · `domain` · `brain` · `assembly` · `outline` · `inspect` · `diff` · `template` · `consistency` |
+| Writing | `remember` · `diary` · `revise` · `split` · `resolve` · `withdraw` · `recover` |
+| Reading & search | `read` · `recall` · `domain` · `brain` · `assembly` · `outline` · `inspect` · `diff` · `template` · `consistency` |
 | Graph | `connect` · `explore` · `graph` |
 | Attachments & labels | `attach` · `detach` · `label` |
 | Maintenance & system | `addendum` · `maintain` · `claim` · `forget` · `bootstrap` |

package/dist/index.js

@@ -25099,7 +25099,8 @@ var SymmetricRelations = ["worksWith"];
 var DEFAULT_POLICY = {
   dormantAfterDays: 21,
   archiveDormantAfterDays: 45,
-  staleAfterDays: 7
+  staleAfterDays: 7,
+  deletionCatchupDays: 7
 };
 
 // src/time.ts
@@ -26445,6 +26446,57 @@ function splitByH3(html) {
   }
   return out;
 }
+function sectionSpans(html) {
+  const closed = closeDangling(html);
+  const heads = [];
+  const re = /<h([2-4])(?:\s[^>]*)?>([\s\S]*?)<\/h\1>/gi;
+  let m;
+  while ((m = re.exec(closed)) !== null) {
+    const text = decodeEntities(m[2].replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
+    if (!text)
+      continue;
+    heads.push({ level: Number(m[1]), text, start: m.index, bodyStart: m.index + m[0].length });
+  }
+  const seen = new Map;
+  return heads.map((h, i) => {
+    const next = heads.findIndex((x, j) => j > i && x.level <= h.level);
+    const end = next === -1 ? closed.length : heads[next].start;
+    const occurrence = (seen.get(`${h.level}::${h.text.toLowerCase()}`) ?? 0) + 1;
+    seen.set(`${h.level}::${h.text.toLowerCase()}`, occurrence);
+    return { level: h.level, text: h.text, start: h.start, bodyStart: h.bodyStart, end, occurrence };
+  });
+}
+function extractSections(html, headings) {
+  if (!headings.length)
+    return { html, extracted: "", matched: [], missed: [] };
+  const closed = closeDangling(html);
+  const spans = sectionSpans(closed);
+  const key = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();
+  const taken = [];
+  const missed = [];
+  const used = new Set;
+  for (const wanted of headings) {
+    const idx = spans.findIndex((s, i) => !used.has(i) && key(s.text) === key(wanted));
+    if (idx === -1) {
+      missed.push(wanted);
+      continue;
+    }
+    used.add(idx);
+    taken.push(spans[idx]);
+  }
+  if (!taken.length)
+    return { html, extracted: "", matched: [], missed };
+  const sorted = [...taken].sort((a, b) => a.start - b.start);
+  let remaining = closed;
+  for (const s of [...sorted].sort((a, b) => b.start - a.start)) {
+    remaining = `${remaining.slice(0, s.start)}${remaining.slice(s.end)}`.replace(/\n{3,}/g, `
+
+`);
+  }
+  const extracted = sorted.map((s) => closed.slice(s.start, s.end).trim()).filter(Boolean).join(`
+`);
+  return { html: remaining.trim(), extracted, matched: taken.map((s) => s.text), missed };
+}
 function mergeUnderSection(current, incoming, parentHeading) {
   const groups = splitByH3(incoming);
   if (!groups.length)
@@ -26937,6 +26989,9 @@ function labelPlan(kind, opts, date) {
   if ((kind === "information" || kind === "domain" || kind === "sources") && opts.domain) {
     labels.push({ name: "domain", value: slugify(opts.domain) });
   }
+  if (kind === "information" && opts.mandate) {
+    labels.push({ name: "mandate", value: "" });
+  }
   for (const topic of opts.topics ?? []) {
     const slug = slugify(topic);
     if (slug)
@@ -27099,7 +27154,8 @@ async function sweep(trilium, cfg, opts = {}) {
     policy: {
       dormantAfterDays: policy.dormantAfterDays,
       archiveDormantAfterDays: policy.archiveDormantAfterDays,
-      staleAfterDays: policy.staleAfterDays
+      staleAfterDays: policy.staleAfterDays,
+      deletionCatchupDays: policy.deletionCatchupDays ?? 7
     }
   };
   if (!cfg.root)
@@ -27231,7 +27287,7 @@ async function sweep(trilium, cfg, opts = {}) {
   }
   if (deep && !domainSlug) {
     const feed = await trilium.getNoteHistory(cfg.root).catch(() => []);
-    const deletionsWindow = isoDaysAgo(7);
+    const deletionsWindow = isoDaysAgo(policy.deletionCatchupDays ?? 7);
     const recent = feed.filter((h) => h.current_isDeleted && h.date.slice(0, 10) >= deletionsWindow);
     report.scanned += recent.length;
     for (const [i, h] of recent.entries()) {
@@ -27794,13 +27850,14 @@ async function generateDailyLog(trilium, cfg, date) {
 }
 var DELETION_CATCHUP_DAYS = 7;
 async function catchUpDeletions(trilium, cfg, today) {
-  const empty = { windowDays: DELETION_CATCHUP_DAYS, deletionsFound: 0, regenerated: [] };
+  const windowDays = cfg.policy.deletionCatchupDays ?? DELETION_CATCHUP_DAYS;
+  const empty = { windowDays, deletionsFound: 0, regenerated: [] };
   if (!cfg.root || !cfg.insights.logs)
     return empty;
   const history = await trilium.getNoteHistory(cfg.root).catch(() => []);
   if (!history.length)
     return empty;
-  const cutoff = new Date(Date.parse(`${today}T00:00:00Z`) - (DELETION_CATCHUP_DAYS - 1) * 86400000).toISOString().slice(0, 10);
+  const cutoff = new Date(Date.parse(`${today}T00:00:00Z`) - (windowDays - 1) * 86400000).toISOString().slice(0, 10);
   const byDay = new Map;
   let total = 0;
   for (const h of history) {
@@ -27822,7 +27879,7 @@ async function catchUpDeletions(trilium, cfg, today) {
     if (report)
       regenerated.push(day);
   }
-  return { windowDays: DELETION_CATCHUP_DAYS, deletionsFound: total, regenerated };
+  return { windowDays, deletionsFound: total, regenerated };
 }
 
 // src/tools-surface.ts
@@ -27853,7 +27910,8 @@ async function skim(trilium, ancestorNoteId, opts = {}) {
       status: labelOf(n, "status") ?? undefined,
       updated: n.dateModified.slice(0, 10),
       preview: toText(content, 160),
-      ...relations ? { relations } : {}
+      ...relations ? { relations } : {},
+      ...n.attributes.some((a) => a.type === "label" && a.name === "mandate") ? { mandate: true } : {}
     };
   }));
 }
@@ -28288,7 +28346,7 @@ sessions need one section, not five documents.`, {
         deleted: [],
         flagged: [`sweep failed: ${e}`],
         dryRun: false,
-        policy: { dormantAfterDays: cfg.policy.dormantAfterDays, archiveDormantAfterDays: cfg.policy.archiveDormantAfterDays, staleAfterDays: cfg.policy.staleAfterDays }
+        policy: { dormantAfterDays: cfg.policy.dormantAfterDays, archiveDormantAfterDays: cfg.policy.archiveDormantAfterDays, staleAfterDays: cfg.policy.staleAfterDays, deletionCatchupDays: cfg.policy.deletionCatchupDays ?? 7 }
       })),
       buildDigest(trilium, cfg, { depth: depth ?? "digest" })
     ]);
@@ -28748,6 +28806,7 @@ For diary entries use the dedicated diary() tool \u2014 remember(kind="diary") i
     })).optional().describe("kind=sources only: upsert Revision-table rows by source name \u2014 re-verifying a source replaces its existing row's Marker/Date in place instead of appending a new one"),
     topics: arrayType(stringType()).optional().describe("Topic tags \u2014 slugged server-side"),
     supersedes: stringType().optional().describe("noteId this replaces \u2014 old note is archived and wired supersedes"),
+    mandate: booleanType().optional().describe("kind=information only: mark this note as a standing mandate/brief (instructions a future session must follow) rather than a current-state fact. Adds a #mandate flag, surfaced in domain() and knowledge_recall \u2014 a scoped autonomous session finds 'the thing I must obey' without reading every note's prose to tell it apart."),
     mustCreate: booleanType().optional().describe("Refuse instead of adopting an existing note when the title already exists \u2014 turns a silent overwrite on a generic title (Current State, Sources, Technology Stack) into a catchable error"),
     strict: booleanType().optional().describe("Refuse the write when the body needs structural repair (unclosed tags, <br> runs) instead of accepting the repaired form"),
     connect: arrayType(objectType({
@@ -28756,9 +28815,9 @@ For diary entries use the dedicated diary() tool \u2014 remember(kind="diary") i
     })).optional().describe("Relations to wire from this note in the same call \u2014 same semantics as connect() (idempotent, worksWith wired both ways)"),
     icon: stringType().optional().describe('Display icon \u2014 a boxicons class ("bx bx-brain") or a bare name ("brain"); normalized server-side'),
     date: stringType().optional().describe("ISO date override (default: today)")
-  }, async ({ kind, title, body, goal, identity, domain, revision, topics, supersedes, mustCreate, strict, connect: connectRels, icon, date }) => {
+  }, async ({ kind, title, body, goal, identity, domain, revision, topics, supersedes, mandate, mustCreate, strict, connect: connectRels, icon, date }) => {
     const refuseAdoption = (existingId, existingTitle, where) => err("already_exists", `A ${kind} note titled "${existingTitle}" already exists ${where} [${existingId}] \u2014 mustCreate=true refuses to adopt it.`, `Read it first with ${kind === "thread" ? "memory" : "knowledge"}(${existingId}). To add to it deliberately, re-run without mustCreate, or use revise(${existingId}, \u2026). To keep both, pick a title that distinguishes them.`);
-    const opts = { domain, topics, date };
+    const opts = { domain, topics, date, ...mandate ? { mandate: true } : {} };
     const d = date ?? today();
     const { html, warnings: sanitizeWarnings } = renderBody(body ?? "");
     if (strict) {
@@ -29256,6 +29315,7 @@ Use recall() for keyword or full-text search instead.`, {
         modified: n.dateModified.slice(0, 10),
         idleDays: idle,
         ...stale ? { stale: true } : {},
+        ...hasLabel(n, "mandate") ? { mandate: true } : {},
         ...hasLabel(n, "archived") ? { archived: true } : {},
         ...relations ? { relations } : {}
       });
@@ -29274,6 +29334,30 @@ Use recall() for keyword or full-text search instead.`, {
       ...total === 0 && !knowledgeDomain ? { note: `No content found for "${slug}". Create a Knowledge domain with remember(kind="information", domain="${name}") or tag notes with topics=["${slug}"].` } : {}
     });
   });
+  server.tool("read", `Batched multi-note read: several note bodies in ONE round trip. Give ids=[...] and get back
+{count, notes:[{id, title, kind, content, relations?}]}. The orientation step is structurally a
+fan-out \u2014 nineteen notes, several very large \u2014 and N separate surface calls is N chances to
+time out mid-read, which is the one thing that wastes budget rather than spending it. This tool
+collapses the fan-out into one call.
+
+Pure read: returns bodies verbatim, no placeholders, no dedup, no kind restrictions. Note the
+cap: up to 10 ids per call. For one id prefer the kinded read (knowledge()/memory()/llm()) which
+returns the same shape through the same helper; for a huge note the sectioned read is still the
+efficient path \u2014 read() returns whole bodies.`, {
+    ids: arrayType(stringType()).min(1).max(10).describe("Note ids to read \u2014 one body per id, one round trip (cap 10)")
+  }, async ({ ids }) => {
+    const notes = await Promise.all(ids.map(async (id) => {
+      try {
+        const note = await trilium.getNote(id);
+        const content = await trilium.getNoteContent(id).catch(() => "");
+        const relations = relationSnippet(note);
+        return { id, title: note.title, kind: ownedLabel(note, "noteType") ?? undefined, content, ...relations ? { relations } : {} };
+      } catch {
+        return { id, missing: true };
+      }
+    }));
+    return txt3({ count: notes.length, notes });
+  });
   server.tool("revise", `Update an existing note by id. Append a dated addendum (default), replace the body
 (mode=replace), edit a heading section in place (section=), insert around a heading
 (section= with mode="before"/"after"), or do targeted string surgery (find=, or edits= for
@@ -29646,6 +29730,77 @@ status, and archive it in place (it stays where it is, excluded from default rec
       ...warnings.length ? { sanitized: warnings } : {}
     });
   });
+  server.tool("split", `Split a note on its section seams: move whole sections (heading + body) out of one note into a
+new note, leaving a pointer back. The trim affordance \u2014 the write half of the oversized-note
+problem, which maintain() detects but nothing acts on. A note past the read ceiling with twenty
+sections becomes two readable notes instead of one unusable one, and the source stays navigable
+because a pointer marks where the content went.
+
+Pass sections=[heading1, heading2, ...] (heading TEXT, the same contract section= uses) and
+into="<new title>". Each named section is lifted out whole \u2014 nested sub-sections go with their
+parent. Repeated headings are consumed first-match-per-request: passing the same heading twice
+takes the next occurrence each time. The new note is created under the same parent, typed the
+same as the source, and carries the source's #domain/#topic labels; the source is left with a
+"Split into <title>" pointer and a ~references relation to the new note. Sections that do not
+exist are reported in missed= and left in place.
+
+Returns the new note id, the sections moved, and the source's remaining size. A revision is
+taken of the source before it is written. Refused on containers and singletons \u2014 this is for
+content notes.`, {
+    noteId: stringType().describe("Note to split \u2014 the source whose sections are moving out"),
+    sections: arrayType(stringType()).min(1).max(20).describe("Section headings (text) to move out \u2014 nested sub-sections go with their parent"),
+    into: stringType().describe("Title of the new note that receives the moved sections"),
+    date: stringType().optional().describe("ISO date (default: today)")
+  }, async ({ noteId, sections, into, date }) => {
+    if (isStructural(b(), noteId))
+      return err("protected_note", `Note ${noteId} is a structural note (container or singleton) and cannot be split.`, "split() is for content notes \u2014 pass a content note id, not a container.");
+    const d = date ?? today();
+    const note = await trilium.getNote(noteId);
+    const kind = labelOf2(note, "noteType") ?? "information";
+    const current = await trilium.getNoteContent(noteId).catch(() => "");
+    const result = extractSections(current, sections);
+    if (!result.matched.length)
+      return err("no_sections_matched", `None of the requested sections exist in this note.`, `Available headings: ${headingOutline(current).map((h) => `"${h.text}"`).join(", ") || "(none)"}. Pass the exact heading text from outline(noteId).`);
+    const { title: cleanTitle } = normalizeTitle(into);
+    if (!cleanTitle)
+      return err("missing_param", "into= produced no usable title.", 'Give the new note a real title, e.g. into="Code Priority Queue \u2014 resolved items".');
+    const parentId = note.parentNoteIds[0];
+    if (!parentId)
+      return err("no_parent", "The source note has no parent \u2014 cannot place the split target.", "A content note should have exactly one parent.");
+    const created = await trilium.createNote(parentId, cleanTitle, result.extracted, "text");
+    const nid = created.note.noteId;
+    for (const l of labelPlan(kind, { domain: labelOf2(note, "domain"), topics: note.attributes.filter((a) => a.type === "label" && a.name === "topic").map((a) => a.value ?? "").filter(Boolean) }, d)) {
+      if (l.name === "noteType" || l.name === "created")
+        await trilium.addLabel(nid, l.name, l.value, l.inheritable ?? false);
+    }
+    if (labelOf2(note, "domain"))
+      await trilium.addLabel(nid, "domain", labelOf2(note, "domain")).catch(() => null);
+    for (const t of note.attributes.filter((a) => a.type === "label" && a.name === "topic")) {
+      if (t.value)
+        await trilium.addLabel(nid, "topic", t.value).catch(() => null);
+    }
+    const pointer = `<p><em>Split ${d} \u2014 moved ${result.matched.length} section(s) into <strong>${escapeHtml(cleanTitle)}</strong> [${nid}].</em></p>`;
+    await trilium.createRevision(noteId).catch(() => null);
+    await trilium.updateNoteContent(noteId, `${pointer}
+${result.html}`);
+    await trilium.updateLabelValue(noteId, "updated", d);
+    await trilium.addRelation(noteId, "references", nid).catch(() => null);
+    const remaining = await trilium.getNoteContent(noteId).catch(() => "");
+    const remainingNote = await trilium.getNote(noteId).catch(() => null);
+    return txt3({
+      ok: true,
+      action: "split",
+      noteId,
+      newNoteId: nid,
+      newNoteTitle: cleanTitle,
+      moved: result.matched,
+      ...result.missed.length ? { missed: result.missed } : {},
+      remainingSize: remaining.length,
+      pointer: `Split ${d} \u2014 moved ${result.matched.length} section(s) into ${cleanTitle} [${nid}]`,
+      ...remainingNote ? { relations: relationSnippet(remainingNote) } : {},
+      note: `Moved ${result.matched.length} section(s) into "${cleanTitle}" [${nid}]; the source now points at it. If this was the wrong seam, the source has a revision from before the split.`
+    });
+  });
   server.tool("withdraw", `Withdraw an archived or resolved thread from the archive: removes the #archived flag,
 resets status to active, clears the closed date, and appends a dated "Withdrawn" addendum.
 Use when a resolved or dormant thread resurfaces as live work.`, {
@@ -29842,13 +29997,58 @@ Scans every in-scope note by default. Trilium's %= backend filter is a LOSSY pre
 reads a striptags'd copy of the content, so it drops notes this tool should examine \u2014 and on a
 contradiction sweep a falsely clean result is worse than a slow one. Pass fast=true to use it
 anyway when scope is wide and speed matters more than completeness.`, {
-    pattern: stringType().describe("Regex over note bodies. One capture group = the value that should agree across notes."),
+    pattern: stringType().optional().describe("Regex over note bodies. One capture group = the value that should agree across notes. Omit when using subject= (prose mode)."),
+    subject: stringType().optional().describe("Prose-subject mode: give a fact in prose ('the two scheduled agents'), get back the notes asserting about that subject, however phrased \u2014 no regex guessing. Tokenized into significant content words; mutually exclusive with pattern. Use domain= to scope the search."),
+    staleAfterDays: numberType().optional().describe("With pattern: flag figures asserted in EXACTLY one note whose sole note was last touched more than N days ago \u2014 the single-copy values that rot silently, because consistency() can only tell a single copy agrees with itself. Reported in staleSingles."),
     domain: stringType().optional().describe("Restrict to one knowledge domain"),
     kinds: arrayType(enumType(Kinds)).optional().describe("Restrict to these kinds"),
     includeArchived: booleanType().optional().describe("Include archived notes (default false)"),
     limit: numberType().optional().describe("Max notes to examine (default 60)"),
     fast: booleanType().optional().describe("Pre-filter candidates with Trilium's %= operator \u2014 faster, but its striptags'd corpus silently drops notes (default: false, scan every in-scope note)")
-  }, async ({ pattern, domain, kinds, includeArchived, limit, fast }) => {
+  }, async ({ pattern, subject, staleAfterDays, domain, kinds, includeArchived, limit, fast }) => {
+    if (!pattern && !subject)
+      return err("missing_param", "consistency() needs either a regex pattern or a prose subject.", 'Pass pattern="(\\\\d+) users" to compare a captured value, or subject="<a fact in prose>" to find every note asserting about that subject however phrased.');
+    if (subject && !pattern) {
+      const max = limit ?? 60;
+      const tokens = queryTokens(subject, 8);
+      if (!tokens.length)
+        return err("no_tokens", "The subject produced no significant content words.", 'A subject of all stop-words ("what was it") cannot find anything \u2014 name the thing you re-measured.');
+      const clauses = ["#noteType"];
+      if (domain)
+        clauses.push(`#domain='${slugify(domain)}'`);
+      const notes = await trilium.searchNotes(clauses.join(" AND "), { ancestorNoteId: b().root, limit: max, includeArchivedNotes: includeArchived ?? false }).then((r) => r.results).catch(() => []);
+      const scoped = notes.filter((n) => {
+        const kind = ownedLabel(n, "noteType");
+        if (!kind)
+          return false;
+        return !kinds?.length || kinds.includes(kind);
+      });
+      const threshold = Math.max(1, Math.ceil(tokens.length / 2));
+      const hits = [];
+      for (const n of scoped) {
+        const content = await trilium.getNoteContent(n.noteId).catch(() => "");
+        if (!content)
+          continue;
+        const text = stripTagsWithMap(content).text.toLowerCase();
+        const matchedTokens = tokens.filter((t) => text.includes(t));
+        if (matchedTokens.length < threshold)
+          continue;
+        hits.push({ id: n.noteId, title: n.title, kind: ownedLabel(n, "noteType") ?? "", matchedTokens, snippet: toText(content, 200) });
+      }
+      return txt3({
+        mode: "subject",
+        subject,
+        tokens,
+        threshold: `${threshold} of ${tokens.length} token(s)`,
+        notesExamined: scoped.length,
+        notes: hits,
+        total: hits.length,
+        ...domain ? { domain: slugify(domain) } : {},
+        note: hits.length ? `${hits.length} note(s) assert something about "${subject}". Open each to read the claim \u2014 or narrow with domain= / kinds=.` : `No note in scope matched ${threshold}+ of the subject's tokens. That is evidence about the phrasing, not the brain \u2014 this mode is deliberately phrase-agnostic, so if you expected a hit, the fact may not be recorded here at all.`
+      });
+    }
+    if (!pattern)
+      return err("missing_param", "No regex pattern given for consistency.", 'Pass pattern="(\\\\d+) users" \u2014 or subject="<a fact in prose>" for the prose-subject mode.');
     let re;
     try {
       re = new RegExp(pattern, "gi");
@@ -29885,11 +30085,12 @@ anyway when scope is wide and speed matters more than completeness.`, {
       return { values, matched };
     };
     let tagSpanning = 0;
+    const idleSince = (iso) => Math.max(0, Math.floor((Date.now() - new Date(iso.replace(" ", "T")).getTime()) / 86400000));
     for (const n of scoped) {
       const content = await trilium.getNoteContent(n.noteId).catch(() => "");
       if (!content)
         continue;
-      const stub = { id: n.noteId, title: n.title, kind: ownedLabel(n, "noteType") ?? "" };
+      const stub = { id: n.noteId, title: n.title, kind: ownedLabel(n, "noteType") ?? "", idleDays: idleSince(n.dateModified) };
       const raw = scan(content);
       const projected = scan(stripTagsWithMap(content).text);
       if (projected.matched && !raw.matched)
@@ -29919,6 +30120,7 @@ anyway when scope is wide and speed matters more than completeness.`, {
       });
     }
     const groups = [...byValue.entries()].map(([value, notes]) => ({ value, count: notes.length, notes })).sort((a, b) => b.count - a.count);
+    const staleSingles = staleAfterDays ? groups.filter((g) => g.count === 1 && g.notes[0].idleDays >= staleAfterDays).map((g) => ({ value: g.value, note: { id: g.notes[0].id, title: g.notes[0].title, kind: g.notes[0].kind }, idleDays: g.notes[0].idleDays })) : [];
     const agrees = groups.length <= 1;
     return txt3({
       mode: "consistency",
@@ -29930,6 +30132,8 @@ anyway when scope is wide and speed matters more than completeness.`, {
       distinctValues: groups.length,
       agreement: groups.length === 0 ? "no-data" : agrees ? "unanimous" : "DISAGREEMENT",
       groups,
+      ...staleAfterDays ? { staleAfterDays } : {},
+      ...staleSingles.length ? { staleSingles, staleSinglesNote: `${staleSingles.length} figure(s) appear in exactly one note, untouched ${staleAfterDays}d+ \u2014 a single copy cannot disagree with itself, so re-measure these against the world rather than against other notes.` } : {},
       ...noCapture.length ? { matchedWithoutValue: noCapture } : {},
       note: agrees ? groups.length === 0 ? "No note asserted a value for that pattern. That is evidence about the pattern, not about the brain \u2014 check it against a note you know contains the fact." : `All ${groups[0].count} note(s) agree on "${groups[0].value}".` : `${groups.length} DIFFERENT values are asserted across ${scoped.length} notes. Establish which is true from evidence, correct every note that disagrees, and wire ~corrects from the note that overturns the old claim \u2014 revising in place leaves no trace the wrong value was ever believed.`
     });
@@ -31103,6 +31307,7 @@ var TOOL_ANNOTATIONS = {
   brain: READ,
   recall: READ,
   domain: READ,
+  read: READ,
   outline: READ,
   inspect: READ,
   template: READ,
@@ -31129,6 +31334,7 @@ var TOOL_ANNOTATIONS = {
   remember: WRITE,
   diary: APPEND,
   revise: WRITE,
+  split: WRITE,
   close: APPEND,
   connect: WRITE,
   label: WRITE,
@@ -32296,7 +32502,7 @@ function createServer(origin = null) {
   const s = new McpServer({
     name: "BrainLLM",
     title: "BrainLLM",
-    version: "12.2.0",
+    version: "12.3.0",
     icons: brandingIcons(origin)
   });
   registerTools(s, trilium, brainRef);

package/manifest.json

@@ -2,7 +2,7 @@
   "dxt_version": "0.1",
   "name": "brainllm",
   "display_name": "BrainLLM",
-  "version": "12.2.0",
+  "version": "12.3.0",
   "description": "Turns TriliumNext Notes into a persistent, graph-structured second brain for Claude and other LLM clients.",
   "long_description": "BrainLLM is an MCP server that organises memory into five purpose-built areas (Master, LLM, Memory, Knowledge, Insights). The model supplies content while the server owns placement, format, lifecycle, dates and backups. Includes a full raw ETAPI surface for advanced use. Requires a running TriliumNext instance and the Bun runtime.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainllm",
-  "version": "12.2.0",
+  "version": "12.3.0",
   "mcpName": "io.github.miisodev/brainllm",
   "description": "MCP server that turns TriliumNext Notes into a persistent, graph-structured second brain for Claude and other LLM clients.",
   "author": "Kevin Miiso Novo <miisodev@gmail.com>",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.miisodev/brainllm",
   "description": "Persistent graph-structured memory for LLMs in TriliumNext Notes — readable and editable by humans.",
-  "version": "12.2.0",
+  "version": "12.3.0",
   "websiteUrl": "https://github.com/miisodev/BrainLLM#readme",
   "repository": {
     "url": "https://github.com/miisodev/BrainLLM",
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "brainllm",
-      "version": "12.2.0",
+"version": "12.3.0",
       "transport": {
         "type": "stdio"
       },
@@ -39,7 +39,7 @@
         },
         {
           "name": "BRAINLLM_MODE",
-          "description": "core (default) exposes the 39 brain-aware tools; full additionally exposes the 33 raw ETAPI tools.",
+          "description": "core (default) exposes the 44 brain-aware tools; full additionally exposes the 33 raw ETAPI tools.",
           "isRequired": false,
           "format": "string",
           "default": "core"

package/skills/brainllm/SKILL.md

@@ -30,9 +30,11 @@ DURING          remember(...)           ← the moment something worth keeping a
                 <surface> / _recall      ← read a surface in full, or skim it (section= reads ONE section — the read twin of revise(section=))
                 domain(name)             ← surface all content for a domain/topic/project — the RELIABLE retrieval path; reach here first
                 recall(...)              ← ranked search; pass domain= whenever you know the area
-                consistency(pattern)     ← does the brain agree with itself? run after correcting a fact recorded in >1 note
+                consistency(pattern|subject) ← does the brain agree with itself? pattern= to compare a captured value; subject= to find notes asserting about a fact however phrased; staleAfterDays= to surface single-copy figures that rot silently. Run after correcting a fact recorded in >1 note
+                read(ids=[…])                ← batched multi-note read — several bodies, one round trip
                 claim(...)               ← does the brain still agree with the WORLD? register a checkable assertion; verify on a schedule
                 revise(...)              ← edit a note (section= for whole sections, find=/edits= for surgery, mode=before/after to insert, mode=remove to delete)
+                split(noteId, sections, into) ← the trim affordance: lift whole sections into a new note, leaving a pointer — the write half of the oversized-note problem
                 outline(noteId)          ← the heading tree + structural check — read BEFORE a section= edit you're guessing at
                 diff(noteId)             ← what your last write actually changed, against the revision it snapshotted
                 resolve(...)             ← close a thread with its outcome
@@ -155,6 +157,8 @@ Each surface has two read tools: `<surface>` reads in full, `<surface>_recall` s
 
 `recall(query, kinds?, domain?, includeArchived?, regex?, fuzzy?)` searches the **whole** brain — use it when you don't know the surface, or for cross-surface lookups. A fuzzy pass runs automatically when the exact strategies come back thin; those hits are marked `fuzzy: true` and are leads to verify, not answers. `regex=` matches a real regular expression against stored bodies — the tool for structural questions keyword search cannot express.
 
+**`read(ids=[…])` is the batched read — several bodies, one round trip.** The orientation step is a fan-out (a dozen notes, several huge) and N separate calls is N chances to time out mid-read; `read()` collapses it into one call, up to 10 ids, returning each body verbatim regardless of kind. Reach for it when you need whole bodies across kinds; prefer the kinded `knowledge()`/`memory()`/`llm()` for a single note, and a `section=` read for one huge note — `read()` returns whole bodies.
+
 `assembly(area?)` answers **"what do I already know here"** — every note by title, grouped under the surface it lives in, with each surface's own purpose alongside it. This is the orientation read: reach for it *before* deciding whether you need to look something up, not after a search comes back thin. Dated collections (sessions, diary, logs) collapse to a count and a span, because listing sixty `[yyyy-mm-dd]` titles is the bulk of the brain and none of its meaning; domains nest under their book; threads group by status. `area=` zooms into one surface.
 
 **`assembly()` and `brain()` answer different questions and are not interchangeable.** Assembly is *awareness* — titles and shape, sized to be read. Brain is *inventory* — ids, kinds, statuses, parents, dates, for auditing or locating one note. Reaching for the inventory when the question was awareness is the common mistake, and it costs several times the tokens to answer worse.
@@ -243,6 +247,8 @@ A revision snapshot is always taken first. Containers are refused; the maintaine
 
 **Merge, don't stack — the mechanics.** Master, LLM singletons, and Knowledge notes (including every per-domain Sources note and information note) are clean structured documents, so `revise()`'s *default* append mode is the wrong one for them: reach for `section=` or `mode=replace` to absorb the content into the body, and `find=`/`edits=` for anything smaller than a section. Default append is correct only on sessions, diary entries, logs, and thread day-children. The rule and its rationale are stated in full under Writing.
 
+**When a note is past the read ceiling, the right move is `split()`, not more surgery.** A note too big to return whole and flagged by `maintain()`'s oversized check has usually grown two or three subjects under one title — that is a structural problem surgery can't fix, only a split can. `split(noteId, sections=[…], into="<title>")` lifts whole sections (heading + body, nested sub-sections with their parent) into a new note under the same parent, typed and labelled like the source, and leaves a pointer plus a `~references` edge in the source. Splitting on a semantic seam (a live queue from a do-not-re-raise index, one sub-category from another) turns two months of brittle `find=` surgery into one call. Outline the note first to name the seams; sections that don't match come back in `missed=` and stay put.
+
 ---
 
 ## Completing — `resolve`
@@ -271,7 +277,9 @@ Pick the most specific verb that's true; `relatesTo` is the last resort. `worksW
 
 A brain can be wrong in two directions, and they need different tools. **`consistency()` asks whether the brain agrees with itself. `claim()` asks whether it still agrees with the world.** Nothing else in the surface answers either question: `recall()` ranks by relevance and `maintain()` checks structure, so both failures sit in notes that read as authoritative.
 
-**`consistency(pattern, domain?, kinds?)` — the same fact, recorded differently in several places.** Give a regex with one capture group naming the value that should agree — `consistency("([0-9]+) Titan mailboxes")` — and it returns every note asserting a value, grouped, with `agreement: "unanimous"` or `"DISAGREEMENT"`. **Run it after correcting any fact that could be recorded in more than one place**, because revising one note leaves its siblings silently wrong and every copy still looks authoritative. It matches both the stored HTML and a tag-stripped projection, so a phrase broken by an inline `<strong>` is found; it scans every in-scope note by default, because on a contradiction sweep a falsely clean result is worse than a slow one.
+**`consistency(pattern | subject, domain?, kinds?, staleAfterDays?)` — the same fact, recorded differently in several places.** Give a regex with one capture group naming the value that should agree — `consistency("([0-9]+) Titan mailboxes")` — and it returns every note asserting a value, grouped, with `agreement: "unanimous"` or `"DISAGREEMENT"`. **Run it after correcting any fact that could be recorded in more than one place**, because revising one note leaves its siblings silently wrong and every copy still looks authoritative. It matches both the stored HTML and a tag-stripped projection, so a phrase broken by an inline `<strong>` is found; it scans every in-scope note by default, because on a contradiction sweep a falsely clean result is worse than a slow one.
+
+**Two additions make it the tool to reach for when you re-measure a fact.** `subject="<prose>"` is the no-regex-guessing mode: give it the fact in plain words and it returns every note asserting about that subject, however phrased — tokenized and matched on significant content words, so the word-order a hand-built pattern anchored on no longer hides the answer. `staleAfterDays=N` reports the **single-copy** figures: values asserted in exactly one note whose sole note was untouched N+ days. Those are the ones that rot silently — a single copy can only agree with itself, so `consistency()`'s verdict of "unanimous" is no evidence of currentness; the `staleSingles` list is where re-measurement is owed.
 
 **`claim()` — an assertion that was true when written and may not be now.** Register one with `assertion=` and `check=`; record an outcome with `claimId=`, `holds=` and `evidence=`; read one with `claimId=` alone; list with no arguments at all. `maintain(deep=true)` then surfaces the lapsed, the never-verified and the broken, so "is the brain stale" becomes a query instead of something caught by luck.
 
@@ -323,20 +331,22 @@ Most of these are computed **server-side** from note properties rather than by r
 | `day(date?, recap?)` | The new-day sweep payload in one call: previous session in full + that day's log + notes touched since + the current month's deliverables note in full, plus the sweep protocol as `next[]`. Call when start() flags `newDay`. `recap=true` instead returns every addendum written TODAY across sessions, diary and thread children, chronologically and attributed — for arriving mid-day after autonomous runs. |
 | `session(date?, full?, scope?)` | Mandatory pre-close step. Fetches master and LLM singletons as `{id, lastModified, relations}` stubs (light by default — start() already served them in full; fetch via master()/llm() only what you'll revise), today's diary as `{id, blocks, size}`, and runs the lite maintenance sweep. `full=true` inlines singleton content and the diary body (rarely needed). `scope="agent"` omits the user's-singleton steps for a scoped/autonomous run. Returns `next[]` driving the full end-of-session protocol, ending in `remarks()` → `diary()` → `close()`. Call before `close()`; idempotent. |
 | `remarks()` | Cue-only diary prompt, called before `diary()` — returns two cue banks (experience: what the session was like / your opinions / your existence here; brainllm: capability walls, bugs, usability & efficiency, roadmap) and satisfies its gate step on the call. Writes nothing; answer as first-person prose in today's diary via `diary()`. |
-| `close(summary, title?, identity, learned?, date?, backup?, continuing?, force?)` | Commit the session log ([yyyy-mm-dd] note; identity= REQUIRED — the canonical h3 identification line; title param above Summary) + backup + daily log (regenerated in place, plus a deletion catch-up that regenerates past days' logs when the change feed shows deletions ≤7 days old — a deletion landing after that day's close is no longer invisible) + idempotent session↔log wiring. **Refuses unless `session()`, `addendum()`, `maintain()`, `remarks()`, and `diary()` each ran this session AND `session() → remarks() → diary()` held (last calls)** — returns `{error, detail, hint}` naming what's missing or out of order; `force=true` bypasses the gate (reported back as `bypassed`) but never the identity requirement. `continuing=true` is the SECOND close of a day: skips the ceremonial re-run, and is verified against today's note so it can't stand in for a first close. On success returns `{action, noteId, date, backup, log}` (plus `deletionCatchUp` when one ran) and resets the gate. Once, last. |
+| `close(summary, title?, identity, learned?, date?, backup?, continuing?, force?)` | Commit the session log ([yyyy-mm-dd] note; identity= REQUIRED — the canonical h3 identification line; title param above Summary) + backup + daily log (regenerated in place, plus a deletion catch-up that regenerates past days' logs when the change feed shows deletions inside the configurable window — `deletionCatchupDays`, default 7, Trilium's eraser retention — so a deletion landing after that day's close is no longer invisible) + idempotent session↔log wiring. **Refuses unless `session()`, `addendum()`, `maintain()`, `remarks()`, and `diary()` each ran this session AND `session() → remarks() → diary()` held (last calls)** — returns `{error, detail, hint}` naming what's missing or out of order; `force=true` bypasses the gate (reported back as `bypassed`) but never the identity requirement. `continuing=true` is the SECOND close of a day: skips the ceremonial re-run, and is verified against today's note so it can't stand in for a first close. On success returns `{action, noteId, date, backup, log}` (plus `deletionCatchUp` when one ran) and resets the gate. Once, last. |
 | `assembly(area?, includeArchived?)` | **What the brain HOLDS**, shaped for awareness rather than audit: every note by title grouped under its surface, with each surface's engraved purpose alongside. Dated collections (sessions, diary, logs) collapse to a count and a date span — listing sixty `[yyyy-mm-dd]` titles is the bulk of the brain and none of its meaning. Domains nest under their book; threads group by status. `area=` zooms into one. Read this before deciding whether you need to look something up. |
 | `brain(includeArchived?)` | Full content tree: every typed note across all five areas, grouped, with id/kind/status/parent/dates. The **inventory** — reach for it to audit or locate, and for `assembly()` when the question is what you know. |
 | `bootstrap()` | Initialize the structure if uninitialized, or verify and refresh config if it already exists. Only creates a new tree when the stored root note is confirmed deleted in Trilium (404). Any other error (network, auth, timeout) is surfaced rather than silently creating a duplicate tree. |
-| `remember(kind, …)` | Write a note — routed, formatted, deduped server-side. New threads REQUIRE `goal=` (queried from the user); thread appends REQUIRE `identity=`; thread bodies must not carry a Resolution. `connect=[{relation, toNoteId}]` wires relations in the same call; a new connectable note without them returns an orphan-prevention hint. Sources/information receipts include `domainId`. `icon=` sets the display icon. Rejects diary/session/log/domain — each has a dedicated path. |
+| `remember(kind, …)` | Write a note — routed, formatted, deduped server-side. New threads REQUIRE `goal=` (queried from the user); thread appends REQUIRE `identity=`; thread bodies must not carry a Resolution. `connect=[{relation, toNoteId}]` wires relations in the same call; a new connectable note without them returns an orphan-prevention hint. Sources/information receipts include `domainId`. `icon=` sets the display icon. Rejects diary/session/log/domain — each has a dedicated path. `mandate=true` (kind=information) marks a note as a standing brief — adds a `#mandate` flag surfaced in domain() and knowledge_recall, so a scoped autonomous session can find "the thing I must obey" without reading every note's prose to tell it apart from current-state fact. |
 | `diary(body, identity, icon?, date?)` | Write to today's [yyyy-mm-dd] diary — every write lands as a timestamped `Addendum — HH:mm` block, including the first of the day; identity= ENFORCED (the canonical h3 identification line). The FINAL gate step — close() counts it only when its last call came after session() and remarks(); mid-session writes welcome. |
 | `template(kind)` | The canonical structure for a content kind: skeleton + top-to-bottom structure + the rules writes are held to. Read before the first write of a kind — then read an existing sibling for the conventions the skeleton can't encode (heading depth, table shape, title style). Template for the schema, sibling for the shape. |
 | `graph(noteId?, depth?, includeArchived?)` | The graph view — Mermaid flowchart of the relation graph (whole brain, or a note's neighborhood), returned AND upserted into the maintained Insights/Graph mermaid note. On-demand only — reflects the brain as of the call, not auto-refreshed after later writes; a scoped call replaces the note's content, it doesn't merge. |
 | `recall(query, …)` | BrainLLM-wide ranked search. **Scope it — pass `domain=` whenever you know the area.** Title matches score per-token with an exact-title bonus, but an unscoped query across a large brain still ranks full-text noise alongside the note you want. `orderBy` / `orderDirection` for temporal ordering; `fastSearch` for title/label-only; `regex=` for a body pattern instead of keywords; `fuzzy=` to force the typo-tolerant pass on or off. A thin or odd result is evidence about the **query**, not the brain. |
-| `consistency(pattern, domain?, kinds?)` | **Does the brain agree with itself?** Give a regex with one capture group naming the value that should match across notes — `consistency("(\\d+) Titan mailboxes")` — and it returns every note asserting a value, grouped, with `agreement: "unanimous"` or `"DISAGREEMENT"`. This is the check nothing else performs: `recall()` ranks by relevance and `maintain()` checks structure, so a correction applied to one note leaves its siblings silently wrong. **Run it after correcting any fact that could be recorded in more than one place.** Matched against **both** the stored HTML and a tag-stripped projection, so a phrase split by an inline `<strong>` or `<code>` is found and so is a pattern anchored on tags. Scans every in-scope note by default — Trilium's `%=` pre-filter reads a striptags'd copy and silently drops notes, and on a contradiction sweep a falsely clean result is worse than a slow one; `fast=true` opts back into it. |
+| `read(ids=[…])` | **Batched multi-note read — several bodies, one round trip.** The orientation step is structurally a fan-out (a dozen notes, some huge) and N separate surface calls is N chances to time out mid-read; this collapses it into one. Up to 10 ids; returns `{count, notes:[{id, title, kind, content, relations?}]}`. Pure read, no kind restrictions. For a single note prefer the kinded read (knowledge()/memory()/llm()); for one huge note a sectioned read is still cheaper — read() returns whole bodies. |
+| `consistency(pattern \| subject, domain?, kinds?, staleAfterDays?)` | **Does the brain agree with itself?** Two modes. *Pattern:* give a regex with one capture group naming the value that should match across notes — `consistency("(\\d+) Titan mailboxes")` — and it returns every note asserting a value, grouped, with `agreement: "unanimous"` or `"DISAGREEMENT"`. *Subject:* give a fact in prose — `consistency(subject="the two scheduled agents")` — and get back every note asserting about it, however phrased, no regex guessing; the tool tokenizes the prose and matches a majority of its significant words, so the phrasing that defeated a hand-built pattern is found. `staleAfterDays=N` adds the **single-copy** report: figures asserted in exactly one note whose sole note was untouched N+ days — the ones that rot silently, because a single copy can only agree with itself. This is the check nothing else performs: `recall()` ranks by relevance and `maintain()` checks structure, so a correction applied to one note leaves its siblings silently wrong. **Run it after correcting any fact that could be recorded in more than one place.** Matched against **both** the stored HTML and a tag-stripped projection, so a phrase split by an inline `<strong>` or `<code>` is found and so is a pattern anchored on tags. Scans every in-scope note by default — Trilium's `%=` pre-filter reads a striptags'd copy and silently drops notes, and on a contradiction sweep a falsely clean result is worse than a slow one; `fast=true` opts back into it. |
 | `claim(...)` | **Does the brain still agree with the WORLD?** `consistency()` compares notes to each other; nothing asked whether an assertion is still true of the codebase, config or live surface it describes — so a claim that quietly stopped being true stayed authoritative until something downstream broke. Register one with `assertion=` + `check=`, record an outcome with `claimId=` + `holds=` + `evidence=`, read one with `claimId=` alone, list with no arguments. **BrainLLM never executes the check** — it has no shell, and note content is data rather than instructions; you run it and report back. `maintain(deep=true)` surfaces lapsed, unverified and broken claims. |
 | `diff(noteId, revisionId?)` | What a write actually changed: the revision snapshot against current content, defaulting to the most recent. Every content write already took a revision and nothing could read one back, so verifying surgical edits meant re-reading the whole note or trusting the receipts. Returns the revision index on every call. |
 | `<surface>` / `<surface>_recall` | Read a surface in full (`section=` for one section) / skim it (master, llm, memory, knowledge, insights). |
 | `revise(noteId, …)` | Append / replace / section-edit / insert / find-replace a note. Thread appends REQUIRE `identity=`. Section: h2/h3/h4 tolerant match, `occurrence=` to disambiguate, `mode="before"/"after"` to insert a sibling block around the whole section (section-relative, so "after" lands *past* that section's body, never between the heading and it), `mode="prepend"` to insert at the top of the section body below its heading; returns `matched`/`headingCount`/`available[]` — check them. `find=` + `body=`: exact-string surgery with an attribute- and whitespace-tolerant fallback (`matchMode` in the receipt), `nth=` for one occurrence; `edits=[{find, body}]` for several in one read/write. Misses return a cause-specific hint. `title=` composes with every mode. `strict=true` refuses a section miss AND a body needing structural repair. Retitling a domain book cascades `#domain` to its children. `Last updated` lines bumped server-side. Snapshot taken on content writes (not metadata-only). |
+| `split(noteId, sections=[…], into="<title>")` | **The trim affordance — the write half of the oversized-note problem.** Lifts whole sections (heading + body, nested sub-sections go with their parent) out of one note into a new note created under the same parent, typed and labelled like the source, and leaves a pointer in the source plus a `~references` edge. A note past the read ceiling becomes two readable notes instead of one unusable one. Sections are matched by heading TEXT (the same contract `section=` uses); repeated headings are consumed first-match-per-request; sections that don't exist come back in `missed=` and stay in place. A revision is taken of the source first. Refused on containers and singletons — for content notes. |
 | `outline(noteId)` | The heading tree without the body: every h2–h4 with level, occurrence index, and — for headings carrying inline markup — `raw`, their stored form (`section=` matches `text`, `find=` matches `raw`). On notes 15k+ each heading also carries a first-block `preview` of its section — the orientation read for oversized notes. Plus the note's section level, any table's key column, size, and structural findings (duplicate headings, unbalanced tags). Read it before a `section=` edit you're guessing at, and after a run of surgical edits to confirm the note is still sound. |
 | `resolve(noteId, outcome, …)` | Close a thread: outcome + terminal status + archive-in-place. |
 | `withdraw(noteId, reason?, …)` | Pull an archived/resolved thread back to active (thread kind only — use recover() for other note kinds). |

package/skills/brainllm/references/domains.md

@@ -58,3 +58,9 @@ A domain's Knowledge surface is exactly: **one maintained Sources note, plus a s
 Chronological, run-by-run history belongs in Memory/Threads — a thread is the right place for "here's what Run N found"; a domain information note is the right place for "here's what's actually true about this sub-category," kept current by revision, not accumulation. If you find yourself naming a new information note after today's date or a run number, stop — that finding either updates an existing note (revise it) or doesn't belong in Domains at all.
 
 The title rule is the same here as everywhere: **four words maximum**, no dates, no run numbers. Sub-category titles are where it's most often stretched, and a title that won't fit is telling you something — a sub-category needing eight words to name is usually two sub-categories, so split the content rather than the title. Merge behaviour follows from the same place: Sources and information notes are maintained current-state documents, so new findings fold into the relevant section (`section=`, `find=`) and never arrive as a dated addendum block.
+
+## Standing briefs vs current-state facts — the mandate marker
+
+A domain holds two things that read alike and behave differently: a **standing brief** (instructions a future session must follow — the operating mandate of a venture) and a **current-state fact** (what's true right now). Both are `kind="information"`, and until now telling them apart meant reading each note's prose. A scoped autonomous session that needs "the thing I must obey" should not have to skim every sub-category note to find it.
+
+Mark a brief with `remember(kind="information", domain=…, title=…, body=…, mandate=true)` — it adds a `#mandate` flag, surfaced as `mandate: true` in `domain()` group rows and in `knowledge_recall` stubs. A session looking for its brief reads the domain and the mandate-flagged note is the one carrying instructions rather than facts. `label(noteId, "mandate")` / `label(noteId, "mandate", remove=true)` sets or clears the marker on an existing note. One note per mandate, titled by the brief it is ("Founder Brief", "Operating Mandate") — the four-word rule still applies.

package/skills/brainllm/references/taxonomy.md

@@ -44,6 +44,7 @@ Written by the server — you never set `#noteType`, `#status`, `#created`, `#up
 | `#topic` | slugged, repeatable | Subject tags (`ai-tooling`, `infra`) — capitalization normalized server-side |
 | `#domain` | slugged | Knowledge domain — book auto-created on first use |
 | `#archived` | (flag) | Excludes the note from default `recall()`; content preserved in place |
+| `#mandate` | (flag) | Information notes only — marks a **standing brief** (instructions a future session must follow) as distinct from current-state fact. Set via `remember(…, mandate=true)` or `label(id, "mandate")`; surfaced in `domain()` and `knowledge_recall`. See `references/domains.md` |
 | `#reviewed` | content blob id | Set by `maintain(ack=[…])` — this note's current content was reviewed and its maintenance findings accepted. Suppresses them until the body actually changes, then all of them return |
 | `#brainLlmRoot` | (flag) | Marks the brain root — used by auto-discovery |
 | `#iconClass` | `bx …` | Display icon — set via `icon=` on `remember`/`revise`/`diary`/`close` (class or bare name, normalized) |