brainllm 10.2.0 → 10.4.0

package/dist/index.js

@@ -20040,7 +20040,8 @@ var Kinds = [
   "domain",
   "information",
   "sources",
-  "log"
+  "log",
+  "claim"
 ];
 var KIND_AREA = {
   biography: "master",
@@ -20056,7 +20057,8 @@ var KIND_AREA = {
   domain: "knowledge",
   information: "knowledge",
   sources: "knowledge",
-  log: "insights"
+  log: "insights",
+  claim: "insights"
 };
 var SingletonKinds = [
   "biography",
@@ -20735,8 +20737,8 @@ function decodeEntities(s) {
   }
   return prev;
 }
-function escapeHtml(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+function escapeHtml(s, preserveEntities = true) {
+  return s.replace(preserveEntities ? /&(?![a-zA-Z][a-zA-Z0-9]*;|#\d+;|#x[0-9a-fA-F]+;)/g : /&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 var SUFFIX_STATUS = [
   [/\s*[\u2014\u2013\-:(]\s*(?:partially|partly)\s+(?:resolved|answered|done)\s*\)?\s*$/i, "active"],
@@ -20803,6 +20805,9 @@ function decodeEncodedHtml(body) {
     s = decodeEntitiesOnce(s);
   return s.replace(/&(?![a-zA-Z]+;|#\d+;|#x[0-9a-fA-F]+;)/g, "&amp;");
 }
+function repairDoubleEscaping(html) {
+  return html.replace(/&amp;((?:[a-zA-Z][a-zA-Z0-9]*|#\d+|#x[0-9a-fA-F]+);)/g, (_, entity) => `&${entity}`);
+}
 function inlineMd(escaped) {
   return escaped.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>").replace(/(^|[\s(])\*([^*\s][^*]*)\*/g, "$1<em>$2</em>").replace(/`([^`]+)`/g, "<code>$1</code>").replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g, '<a href="$2">$1</a>');
 }
@@ -20854,7 +20859,7 @@ function toHtml(body) {
     if (code !== null) {
       if (/^```/.test(line)) {
         out.push(`<pre><code>${escapeHtml(code.join(`
-`))}</code></pre>`);
+`), false)}</code></pre>`);
         code = null;
       } else {
         code.push(line);
@@ -20908,7 +20913,7 @@ function toHtml(body) {
   }
   if (code !== null)
     out.push(`<pre><code>${escapeHtml(code.join(`
-`))}</code></pre>`);
+`), false)}</code></pre>`);
   flushTable();
   flushPara();
   flushList();
@@ -20924,9 +20929,94 @@ function toText(html, maxLength = 300) {
   const lastSpace = cut.lastIndexOf(" ");
   return (lastSpace > maxLength * 0.6 ? cut.slice(0, lastSpace) : cut) + "\u2026";
 }
+function addendumIndex(html) {
+  const markerRe = /<h2(?:\s[^>]*)?>\s*((?:Addendum|Withdrawn|Recovered|Reopened)[^<]*)<\/h2>/gi;
+  const out = [];
+  const hits = [...html.matchAll(markerRe)];
+  for (const [i, m] of hits.entries()) {
+    const from = m.index + m[0].length;
+    const to = i + 1 < hits.length ? hits[i + 1].index : html.length;
+    const body = html.slice(from, to);
+    const idMatch = body.match(/<h3(?:\s[^>]*)?>([\s\S]*?)<\/h3>/i);
+    const identity = idMatch ? decodeEntities(idMatch[1].replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim() : undefined;
+    out.push({
+      marker: decodeEntities(m[1]).replace(/\s+/g, " ").trim(),
+      ...identity ? { identity } : {},
+      lead: toText(idMatch ? body.slice(idMatch.index + idMatch[0].length) : body, 120)
+    });
+  }
+  return out;
+}
+function nearestContext(source, needle, radius = 40) {
+  if (!source || needle.length < 4)
+    return null;
+  const longestFrom = (take) => {
+    let lo = 4, hi = needle.length, best2 = null;
+    while (lo <= hi) {
+      const mid = lo + hi >> 1;
+      const frag = take(mid);
+      const at = source.indexOf(frag);
+      if (at !== -1) {
+        best2 = { frag, at };
+        lo = mid + 1;
+      } else {
+        hi = mid - 1;
+      }
+    }
+    return best2;
+  };
+  const prefix = longestFrom((n) => needle.slice(0, n));
+  const suffix = longestFrom((n) => needle.slice(needle.length - n));
+  const best = !prefix ? suffix : !suffix ? prefix : suffix.frag.length > prefix.frag.length ? suffix : prefix;
+  if (!best)
+    return null;
+  const from = Math.max(0, best.at - radius);
+  const to = Math.min(source.length, best.at + best.frag.length + radius);
+  return {
+    fragment: best.frag,
+    context: `${from > 0 ? "\u2026" : ""}${source.slice(from, to)}${to < source.length ? "\u2026" : ""}`,
+    index: best.at
+  };
+}
+var BLOCK_BOUNDARY = /^<\/?(?:p|div|h[1-6]|li|ul|ol|tr|td|th|table|thead|tbody|blockquote|pre|hr|br|section|figure|figcaption)\b/i;
+function stripTagsWithMap(html) {
+  const chars = [];
+  const map2 = [];
+  const emit = (s, at) => {
+    for (const ch of s) {
+      chars.push(ch);
+      map2.push(at);
+    }
+  };
+  const token = /<[^>]*>|&(?:[a-zA-Z][a-zA-Z0-9]*|#\d+|#x[0-9a-fA-F]+);/g;
+  let cursor = 0;
+  let m;
+  while ((m = token.exec(html)) !== null) {
+    for (let i = cursor;i < m.index; i++) {
+      chars.push(html[i]);
+      map2.push(i);
+    }
+    if (m[0].startsWith("<")) {
+      if (BLOCK_BOUNDARY.test(m[0]))
+        emit(" ", m.index);
+    } else {
+      const decoded = decodeEntitiesOnce(m[0]);
+      emit(decoded === m[0] ? m[0] : decoded, m.index);
+    }
+    cursor = m.index + m[0].length;
+  }
+  for (let i = cursor;i < html.length; i++) {
+    chars.push(html[i]);
+    map2.push(i);
+  }
+  return { text: chars.join(""), map: map2 };
+}
 function escapeQueryValue(s) {
   return s.replace(/["\\]/g, " ").replace(/\s+/g, " ").trim();
 }
+function escapeQueryRegex(s) {
+  return s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
 function queryTokens(query, max = 4) {
   const STOP = new Set(["the", "and", "for", "with", "that", "this", "what", "when", "where", "how", "why", "are", "was", "were", "from", "into", "about", "over", "under", "does", "did", "has", "have", "had", "its", "his", "her", "their", "our", "your", "you", "not"]);
   return [...new Set(decodeEntities(query).toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((t) => t.length > 2 && !STOP.has(t)))].slice(0, max);
@@ -21158,13 +21248,14 @@ function headingOutline(html) {
   let m;
   while ((m = re.exec(html)) !== null) {
     const level = Number(m[1]);
-    const text = decodeEntities(m[2].replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
+    const raw = m[2];
+    const text = decodeEntities(raw.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
     if (!text)
       continue;
     const key = `${level}::${text.toLowerCase()}`;
     const occurrence = (seen.get(key) ?? 0) + 1;
     seen.set(key, occurrence);
-    out.push({ level, text, occurrence });
+    out.push({ level, text, occurrence, ...raw.trim() !== text ? { raw: raw.trim() } : {} });
   }
   return out;
 }
@@ -21172,41 +21263,92 @@ function sectionLevelFor(html) {
   const levels = headingOutline(html).map((h) => h.level);
   return levels.length ? Math.min(...levels) : 2;
 }
-function setSection(html, heading, content, mode, occurrence = 1) {
-  html = closeDangling(html);
-  const targetKey = decodeEntities(heading.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim().toLowerCase();
-  for (const level2 of [2, 3, 4]) {
-    const tag = `h${level2}`;
+function locateSection(html, heading, occurrence = 1) {
+  const key = (s) => decodeEntities(s.replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim().toLowerCase();
+  const targetKey = key(heading);
+  for (const level of [2, 3, 4]) {
+    const tag = `h${level}`;
     const globalRe = new RegExp(`<${tag}(?:\\s[^>]*)?>([\\s\\S]*?)</${tag}>`, "gi");
-    const hits = [...html.matchAll(globalRe)].filter((m) => decodeEntities(m[1].replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim().toLowerCase() === targetKey);
+    const hits = [...html.matchAll(globalRe)].filter((m) => key(m[1]) === targetKey);
     if (!hits.length)
       continue;
     const headingCount = hits.length;
     const match = hits[Math.min(Math.max(occurrence, 1), headingCount) - 1];
     const headingStart = match.index;
-    const after = headingStart + match[0].length;
+    const contentStart = headingStart + match[0].length;
+    const nextMatch = html.slice(contentStart).search(new RegExp(`<h[2-${level}]`));
+    return {
+      level,
+      headingStart,
+      contentStart,
+      end: nextMatch === -1 ? html.length : contentStart + nextMatch,
+      headingCount,
+      headingRaw: match[1]
+    };
+  }
+  return null;
+}
+function getSection(html, heading, occurrence = 1) {
+  const closed = closeDangling(html);
+  const found = locateSection(closed, heading, occurrence);
+  if (!found) {
+    return { matched: false, content: "", available: headingOutline(closed).map((h) => h.text) };
+  }
+  const content = closed.slice(found.contentStart, found.end).trim();
+  return {
+    matched: true,
+    content,
+    headingRaw: found.headingRaw,
+    level: found.level,
+    headingCount: found.headingCount,
+    ...headingOutline(content).length ? { subsections: headingOutline(content).map((h) => h.text) } : {}
+  };
+}
+function setSection(html, heading, content, mode, occurrence = 1) {
+  html = closeDangling(html);
+  const found = locateSection(html, heading, occurrence);
+  if (found) {
+    const { headingStart, contentStart, end, headingCount } = found;
+    if (mode === "remove") {
+      const removed = html.slice(contentStart, end).trim();
+      return {
+        html: `${html.slice(0, headingStart)}${html.slice(end)}`.replace(/\n{3,}/g, `
+
+`),
+        matched: true,
+        headingCount,
+        ...headingOutline(removed).length ? { replacedSubsections: headingOutline(removed).map((h) => h.text) } : {}
+      };
+    }
     if (mode === "before") {
       return { html: `${html.slice(0, headingStart)}${content}
 ${html.slice(headingStart)}`, matched: true, headingCount };
     }
     if (mode === "after") {
-      return { html: `${html.slice(0, after)}
-${content}${html.slice(after)}`, matched: true, headingCount };
+      return { html: `${html.slice(0, contentStart)}
+${content}${html.slice(contentStart)}`, matched: true, headingCount };
     }
-    const nextMatch = html.slice(after).search(new RegExp(`<h[2-${level2}]`));
-    const end = nextMatch === -1 ? html.length : after + nextMatch;
-    const existing = html.slice(after, end).trim();
+    const existing = html.slice(contentStart, end).trim();
     const inner = mode === "append" && existing ? `${existing}
 ${content}` : content;
     return {
-      html: `${html.slice(0, after)}
+      html: `${html.slice(0, contentStart)}
 ${inner}
 ${html.slice(end)}`,
       matched: true,
-      headingCount
+      headingCount,
+      ...mode === "replace" && headingOutline(existing).length ? { replacedSubsections: headingOutline(existing).map((h) => h.text) } : {}
     };
   }
   const level = sectionLevelFor(html);
+  if (mode === "remove") {
+    return {
+      html,
+      matched: false,
+      headingCount: 0,
+      available: headingOutline(html).map((h) => h.text)
+    };
+  }
   return {
     html: `${html}
 <h${level}>${heading}</h${level}>
@@ -21217,6 +21359,81 @@ ${content}`,
     available: headingOutline(html).map((h) => h.text)
   };
 }
+function splitByH3(html) {
+  const re = /<h3(?:\s[^>]*)?>([\s\S]*?)<\/h3>/gi;
+  const hits = [...html.matchAll(re)];
+  if (!hits.length)
+    return html.trim() ? [{ body: html.trim(), raw: html.trim() }] : [];
+  const out = [];
+  const lead = html.slice(0, hits[0].index).trim();
+  if (lead)
+    out.push({ body: lead, raw: lead });
+  for (const [i, m] of hits.entries()) {
+    const from = m.index + m[0].length;
+    const to = i + 1 < hits.length ? hits[i + 1].index : html.length;
+    out.push({
+      headingText: decodeEntities(m[1].replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim(),
+      body: html.slice(from, to).trim(),
+      raw: html.slice(m.index, to).trim()
+    });
+  }
+  return out;
+}
+function mergeUnderSection(current, incoming, parentHeading) {
+  const groups = splitByH3(incoming);
+  if (!groups.length)
+    return { html: current, mergedInto: [], appended: [] };
+  const parent = getSection(current, parentHeading);
+  if (!parent.matched) {
+    return { html: setSection(current, parentHeading, incoming, "append").html, mergedInto: [], appended: groups.flatMap((g) => g.headingText ? [g.headingText] : []) };
+  }
+  let section = parent.content;
+  const mergedInto = [];
+  const appended = [];
+  const leftovers = [];
+  for (const g of groups) {
+    if (!g.headingText) {
+      leftovers.push(g.raw);
+      continue;
+    }
+    const key = g.headingText.toLowerCase();
+    const exists = headingOutline(section).some((h) => h.level === 3 && h.text.toLowerCase() === key);
+    if (exists && g.body) {
+      section = setSection(section, g.headingText, g.body, "append").html;
+      mergedInto.push(g.headingText);
+    } else {
+      leftovers.push(g.raw);
+      appended.push(g.headingText);
+    }
+  }
+  if (leftovers.length)
+    section = `${section}
+${leftovers.join(`
+`)}`;
+  return { html: setSection(current, parentHeading, section, "replace").html, mergedInto, appended };
+}
+function sectionProfile(html) {
+  const re = /<h([2-4])(?:\s[^>]*)?>([\s\S]*?)<\/h\1>/gi;
+  const hits = [...html.matchAll(re)];
+  const seen = new Map;
+  const sizes = [];
+  for (const [i, m] of hits.entries()) {
+    const level = Number(m[1]);
+    const text = decodeEntities(m[2].replace(/<[^>]+>/g, "")).replace(/\s+/g, " ").trim();
+    if (!text)
+      continue;
+    const key = `${level}::${text.toLowerCase()}`;
+    seen.set(key, (seen.get(key) ?? 0) + 1);
+    const from = m.index + m[0].length;
+    const to = i + 1 < hits.length ? hits[i + 1].index : html.length;
+    sizes.push({ text, level, chars: to - from });
+  }
+  return {
+    count: sizes.length,
+    largest: sizes.sort((a, b) => b.chars - a.chars).slice(0, 3),
+    ambiguous: [...seen.entries()].filter(([, n]) => n > 1).map(([k]) => k.split("::")[1])
+  };
+}
 function unbalancedTags(html) {
   const stack = [];
   const re = /<\/?([a-zA-Z][a-zA-Z0-9-]*)(?:\s[^>]*)?\/?>/g;
@@ -21351,7 +21568,7 @@ function isOpenResolutionOnly(html) {
 }
 function metaLine(parts) {
   const cleaned = parts.filter((p) => !!p && p.trim().length > 0);
-  return `<p><em>${cleaned.map(escapeHtml).join(" \xB7 ")}</em></p>
+  return `<p><em>${cleaned.map((p) => escapeHtml(p)).join(" \xB7 ")}</em></p>
 <hr>`;
 }
 var STRUCTURED_SINGLETONS = new Set([
@@ -21369,7 +21586,8 @@ var REQUIRED_SECTIONS = {
   goals: ["Near-term", "Long-term"],
   preferences: ["Communication", "Working style", "Tools and stack"],
   responsibilities: ["Core", "Current priorities"],
-  protocols: ["Operating", "Self-correction"]
+  protocols: ["Operating", "Self-correction"],
+  claim: ["Check", "Verifications"]
 };
 function missingSections(kind, html) {
   const required2 = REQUIRED_SECTIONS[kind];
@@ -21563,6 +21781,19 @@ var STRUCTURE_RULES = {
   log: {
     structure: ["Server header (log \xB7 date)", "**Created** / **Updated** / **Deleted** (h2) lists"],
     rules: ["Auto-generated by close(); regenerated in place, never stacked"]
+  },
+  claim: {
+    structure: [
+      "**Check** (h2) \u2014 how to verify the assertion, as inert text: a command, a query, a file path, a URL",
+      "**Verifications** (h2) \u2014 one dated HOLDS/BROKEN line per check, with the evidence observed"
+    ],
+    rules: [
+      'Registered and verified only through claim() \u2014 remember(kind="claim") is rejected',
+      "The title IS the assertion, and is the dedup key \u2014 re-registering the same assertion updates its check and keeps its history",
+      "BrainLLM never executes the Check. It has no shell, and note content is data rather than instructions; the agent runs it and reports back",
+      "Verifications are append-only \u2014 the history is the point, so this is one of the few places a dated stack is correct",
+      "A verification without evidence is refused: a verdict alone is an assertion about an assertion"
+    ]
   }
 };
 function structureRuleFor(kind) {
@@ -21605,6 +21836,8 @@ function kindHome(cfg, kind) {
       return "";
     case "log":
       return cfg.insights.logs;
+    case "claim":
+      return "";
   }
 }
 function dedupScope(cfg, kind) {
@@ -21717,6 +21950,8 @@ function locationLabel(kind, domainTitle) {
       return `Knowledge \u2192 Domains \u2192 ${domainTitle ?? "General"} \u2192 Sources`;
     case "log":
       return "Insights \u2192 Logs";
+    case "claim":
+      return "Insights \u2192 Claims";
   }
 }
 
@@ -21773,8 +22008,11 @@ function reviewKey(n) {
   return n.blobId ?? n.dateModified;
 }
 var STRUCTURE_LINT_LIMIT = 40;
+var SECTION_EDIT_RISK_COUNT = 25;
+var SECTION_EDIT_RISK_CHARS = 8000;
+var ALWAYS_FULL_SLOTS = new Set(["preferences", "protocols"]);
 async function sweep(trilium, cfg, opts = {}) {
-  const { deep = false, dryRun = false, ack } = opts;
+  const { deep = false, dryRun = false, ack, repair } = opts;
   const policy = cfg.policy;
   const report = {
     scanned: 0,
@@ -21999,8 +22237,20 @@ async function sweep(trilium, cfg, opts = {}) {
     if (structure.unbalancedTags.length) {
       report.flagged.push(`unbalanced tags: ${n.title} [${n.noteId}] \u2014 <${structure.unbalancedTags.join(">, <")}> left open; the next write will auto-close them, or fix now with revise(mode=replace)`);
     }
+    const profile = sectionProfile(content);
+    const biggest = profile.largest[0];
+    const crowded = profile.count >= SECTION_EDIT_RISK_COUNT;
+    const lopsided = !!biggest && biggest.chars >= SECTION_EDIT_RISK_CHARS;
+    if (crowded || lopsided) {
+      const reasons = [
+        crowded ? `${profile.count} sections` : null,
+        lopsided ? `largest is '${biggest.text}' at ${Math.round(biggest.chars / 1000)}k characters` : null,
+        profile.ambiguous.length ? `${profile.ambiguous.length} heading text(s) repeated ('${profile.ambiguous.slice(0, 3).join("', '")}') \u2014 those need occurrence= to target` : null
+      ].filter(Boolean);
+      report.flagged.push(`section-edit-risk: ${n.title} [${n.noteId}] \u2014 ${reasons.join("; ")}. ` + `Read outline(${n.noteId}) before any section= edit here, prefer find= for anything smaller than a section, and consider splitting the note.`);
+    }
   }
-  await hygienePasses(trilium, cfg, report, { eligible, connectable, dryRun });
+  await hygienePasses(trilium, cfg, report, { eligible, connectable, dryRun, repair: new Set(repair ?? []) });
   const dupeContainers = [
     { id: cfg.memory.sessions, kind: "session", label: "Sessions" },
     { id: cfg.llm.diary, kind: "diary", label: "Diary" },
@@ -22057,6 +22307,14 @@ async function sweep(trilium, cfg, opts = {}) {
             byDomain.set(domSlug, []);
           byDomain.get(domSlug).push(n);
         }
+        const headingCache = new Map;
+        const headingsOf = async (n) => {
+          if (!headingCache.has(n.noteId)) {
+            const content = await trilium.getNoteContent(n.noteId).catch(() => "");
+            headingCache.set(n.noteId, headingOutline(content).filter((h) => h.level <= 3).map((h) => h.text));
+          }
+          return headingCache.get(n.noteId);
+        };
         for (const [domSlug, notes] of byDomain) {
           const reported = new Set;
           for (let i = 0;i < notes.length; i++) {
@@ -22071,7 +22329,10 @@ async function sweep(trilium, cfg, opts = {}) {
               if (reported.has(pairKey))
                 continue;
               reported.add(pairKey);
-              report.flagged.push(`near-duplicate subject: '${a.title}' [${a.noteId}] and '${bn.title}' [${bn.noteId}] in Domain/${domSlug} ` + `share '${shared.join("', '")}'. Two notes on one subject is the duplicate that actually happens \u2014 ` + `read both, merge into the older one, and forget() the other. If they are genuinely distinct, maintain(ack=[\u2026]) to silence this.`);
+              const [ha, hb] = await Promise.all([headingsOf(a), headingsOf(bn)]);
+              const overlap = ha.filter((h) => hb.some((x) => x.toLowerCase() === h.toLowerCase()));
+              const show = (h) => h.length ? h.slice(0, 8).join(" \xB7 ") + (h.length > 8 ? " \xB7 \u2026" : "") : "(no headings)";
+              report.flagged.push(`near-duplicate subject: '${a.title}' [${a.noteId}] and '${bn.title}' [${bn.noteId}] in Domain/${domSlug} ` + `share '${shared.join("', '")}'. Sections \u2014 '${a.title}': ${show(ha)} | '${bn.title}': ${show(hb)}. ` + (overlap.length ? `${overlap.length} heading(s) in common (${overlap.slice(0, 5).join(", ")}), which is what a genuine split subject looks like \u2014 read both, merge into the older one, and forget() the other.` : `No headings in common, so these are most likely distinct notes that happen to share a title word \u2014 maintain(ack=["${a.noteId}"]) to silence this once you have confirmed it.`));
             }
           }
         }
@@ -22080,6 +22341,16 @@ async function sweep(trilium, cfg, opts = {}) {
   }
   if (suppressed)
     report.suppressed = suppressed;
+  if (deep) {
+    if (domainSlug) {
+      report.coverage = [
+        ...report.coverage ?? [],
+        `scoped to domain '${domainSlug}' \u2014 findings outside it were not evaluated, including the cross-domain ones (duplicate titles across domains, orphans elsewhere) that only an unscoped run can see. Re-run without domain= periodically.`
+      ];
+    } else if (report.flagged.length) {
+      report.laneHint = "Flags here span the whole brain and may cover work this session never touched. LEAVE those \u2014 do not ack= them: an acknowledgement asserts the note's current content was reviewed, so acking unread is the one thing that makes the mechanism useless. Ack only what you actually read, act on what is yours, and pass domain= if you want a single lane.";
+    }
+  }
   return report;
 }
 var STUB_CONTENT_CHARS = 120;
@@ -22091,12 +22362,43 @@ function titleWordCount(title) {
 }
 async function hygienePasses(trilium, cfg, report, ctx) {
   const { eligible } = ctx;
-  const corrupted = await trilium.searchNotes("#noteType note.content *=* '&amp;lt;'", { ancestorNoteId: cfg.root, limit: 50 }).then((r) => r.results).catch(() => []);
+  const corrupted = await trilium.searchNotes(`#noteType note.content %= '${escapeQueryRegex("&amp;(?:[a-zA-Z][a-zA-Z0-9]*|#\\d+|#x[0-9a-fA-F]+);")}'`, { ancestorNoteId: cfg.root, limit: 50 }).then((r) => r.results).catch(() => []);
   report.scanned += corrupted.length;
   for (const n of corrupted) {
     if (!eligible(n))
       continue;
-    report.flagged.push(`entity-corrupted: ${n.title} [${n.noteId}] \u2014 body stores doubly-escaped markup ("&amp;lt;") that renders as literal text. Repair with revise(mode="replace") passing the decoded content; nothing decodes it as a side effect.`);
+    if (ctx.repair.has(n.noteId)) {
+      const before = await trilium.getNoteContent(n.noteId).catch(() => "");
+      const after = repairDoubleEscaping(before);
+      if (after === before) {
+        report.flagged.push(`entity-corrupted: ${n.title} [${n.noteId}] \u2014 repair requested but the body did not change; the match is a note DOCUMENTING the signature rather than carrying it. maintain(ack=["${n.noteId}"]) to silence.`);
+        continue;
+      }
+      if (!ctx.dryRun) {
+        await trilium.createRevision(n.noteId).catch(() => null);
+        await trilium.updateNoteContent(n.noteId, after);
+      }
+      report.fixed.push(`entity-repaired: ${n.title} [${n.noteId}] \u2014 unwound one level of double-escaping${ctx.dryRun ? " (dry run, not written)" : ", snapshot taken first"}.`);
+      continue;
+    }
+    report.flagged.push(`entity-corrupted: ${n.title} [${n.noteId}] \u2014 body stores doubly-escaped markup ("&amp;lt;", "&amp;nbsp;") that renders as literal text. Repair with maintain(repair=["${n.noteId}"]) \u2014 the substitution is always the same, so it is a first-class action rather than something each caller reinvents. Read it first if you need to be sure.`);
+  }
+  const claims = await trilium.searchNotes("#noteType=claim", { ancestorNoteId: cfg.root, fastSearch: true, limit: 200 }).then((r) => r.results).catch(() => []);
+  report.scanned += claims.length;
+  for (const n of claims) {
+    if (!eligible(n))
+      continue;
+    const state = ownedLabel(n, "claimState");
+    const verifiedOn = ownedLabel(n, "verified");
+    const interval = Number(ownedLabel(n, "interval") ?? 30);
+    if (state === "broken") {
+      report.flagged.push(`claim broken: "${n.title}" [${n.noteId}] \u2014 last check FAILED${verifiedOn ? ` on ${verifiedOn}` : ""}. ` + `Correct every note asserting it (consistency() will find the others), then re-verify with claim(claimId="${n.noteId}", holds=true, evidence=\u2026). ` + `A broken claim left in the register is a known-wrong fact with a timestamp on it.`);
+      continue;
+    }
+    const due = !verifiedOn || verifiedOn < isoDaysAgo(interval);
+    if (due) {
+      report.flagged.push(`claim ${verifiedOn ? "lapsed" : "unverified"}: "${n.title}" [${n.noteId}] \u2014 ` + `${verifiedOn ? `last verified ${verifiedOn}, interval ${interval}d` : "never verified since registration"}. ` + `Read its check with claim(claimId="${n.noteId}"), run it, and record the result.`);
+    }
   }
   const titled = await ctx.connectable("#noteType", 300);
   const RECORD_TITLES = new Set(["diary", "session", "log", "threadEntry"]);
@@ -22162,7 +22464,7 @@ async function buildDigest(trilium, cfg, opts = {}) {
     const content = await trilium.getNoteContent(id).catch(() => "");
     if (!content)
       return null;
-    if (depth === "full") {
+    if (depth === "full" || ALWAYS_FULL_SLOTS.has(slot)) {
       const summary = toText(content, Infinity);
       return summary ? { slot, summary } : null;
     }
@@ -22232,9 +22534,39 @@ async function buildDigest(trilium, cfg, opts = {}) {
 }
 
 // src/bootstrap.ts
+var CONTAINER_PURPOSES = {
+  root: "The interconnected second brain \u2014 five areas: Master, LLM, Memory, Knowledge, and Insights.",
+  master: "The master/user. Houses the fundamental, durable information about who they are \u2014 biography, goals, and preferences.",
+  llm: "The assistant. Houses the assistant's fundamental self-model \u2014 its responsibilities, operating protocols, and diary.",
+  llmDiary: "A collection of daily maintained diary notes \u2014 the assistant's unfiltered first-person record of its experience, opinions, and remarks on its own existence during each session in the environment, plus its remarks and opinions on BrainLLM itself.",
+  memory: "The primary memory system the brain operates on \u2014 the running record of daily sessions and multi-session threads.",
+  memorySessions: "A collection of daily, day-lifecycle session notes, each summarising that day's session.",
+  memoryThreads: "A collection of maintained thread notes, each tracking a line of multi-session running work.",
+  knowledge: "The secondary memory system \u2014 learned knowledge that adds to or conflicts with the assistant's training data, about the master/user and across domains.",
+  knowledgeMaster: "A secondary collection of maintained notes about the master/user that don't fit the primary Master area (Biography / Goals / Preferences).",
+  knowledgeDomains: "A collection of domain-scoped books. Each domain holds one maintained Sources note plus the sub-category information notes capturing important learned knowledge \u2014 beyond or conflicting with training data \u2014 about that domain.",
+  insights: "The insights system \u2014 the brain's record of itself: per-day logs of how its own content changed, the rendered relation graph, and the register of claims checked against the world.",
+  insightsLogs: "A collection of per-day, auto-generated notes recording the brain content (notes) created, updated, or deleted that day."
+};
+function containerPurposes(cfg) {
+  return [
+    [cfg.root, CONTAINER_PURPOSES.root],
+    [cfg.master.root, CONTAINER_PURPOSES.master],
+    [cfg.llm.root, CONTAINER_PURPOSES.llm],
+    [cfg.llm.diary, CONTAINER_PURPOSES.llmDiary],
+    [cfg.memory.root, CONTAINER_PURPOSES.memory],
+    [cfg.memory.sessions, CONTAINER_PURPOSES.memorySessions],
+    [cfg.memory.threads, CONTAINER_PURPOSES.memoryThreads],
+    [cfg.knowledge.root, CONTAINER_PURPOSES.knowledge],
+    [cfg.knowledge.master, CONTAINER_PURPOSES.knowledgeMaster],
+    [cfg.knowledge.domains, CONTAINER_PURPOSES.knowledgeDomains],
+    [cfg.insights.root, CONTAINER_PURPOSES.insights],
+    [cfg.insights.logs, CONTAINER_PURPOSES.insightsLogs]
+  ];
+}
 async function createBrainLLMStructure(trilium) {
   const d = new Date().toISOString().slice(0, 10);
-  const root = await trilium.createNote("root", "BrainLLM", purposeContent("The interconnected second brain \u2014 five areas: Master, LLM, Memory, Knowledge, and Insights."), "book");
+  const root = await trilium.createNote("root", "BrainLLM", purposeContent(CONTAINER_PURPOSES.root), "book");
   const rootId = root.note.noteId;
   await Promise.all([
     trilium.addLabel(rootId, "brainLlmRoot", ""),
@@ -22253,30 +22585,30 @@ async function createBrainLLMStructure(trilium) {
     await trilium.addLabel(n.note.noteId, "noteType", kind);
     return n.note.noteId;
   };
-  const masterRoot = await book(rootId, "Master", "The master/user. Houses the fundamental, durable information about who they are \u2014 biography, goals, and preferences.", "bx bx-user");
+  const masterRoot = await book(rootId, "Master", CONTAINER_PURPOSES.master, "bx bx-user");
   const [biography, goals, preferences] = await Promise.all([
     leaf(masterRoot, "Biography", "biography", "A single maintained note of biographical information about the master/user."),
     leaf(masterRoot, "Goals", "goals", "A single maintained note of the master/user's goals."),
     leaf(masterRoot, "Preferences", "preferences", "A single maintained note of the master/user's preferences.")
   ]);
-  const llmRoot = await book(rootId, "LLM", "The assistant. Houses the assistant's fundamental self-model \u2014 its responsibilities, operating protocols, and diary.", "bx bx-bot");
+  const llmRoot = await book(rootId, "LLM", CONTAINER_PURPOSES.llm, "bx bx-bot");
   const [responsibilities, protocols, diary] = await Promise.all([
     leaf(llmRoot, "Responsibilities", "responsibilities", "A single maintained note of the assistant's responsibilities to the master/user, derived from their goals and preferences."),
     leaf(llmRoot, "Protocols", "protocols", "A single maintained note of the assistant's operating and self-correctness protocols \u2014 how it maximises its value to the master/user by efficiently meeting its responsibilities."),
-    book(llmRoot, "Diary", "A collection of daily maintained diary notes \u2014 the assistant's unfiltered first-person record of its experience, opinions, and remarks on its own existence during each session in the environment, plus its remarks and opinions on BrainLLM itself.", "bx bx-book-heart")
+    book(llmRoot, "Diary", CONTAINER_PURPOSES.llmDiary, "bx bx-book-heart")
   ]);
-  const memoryRoot = await book(rootId, "Memory", "The primary memory system the brain operates on \u2014 the running record of daily sessions and multi-session threads.", "bx bx-been-here");
+  const memoryRoot = await book(rootId, "Memory", CONTAINER_PURPOSES.memory, "bx bx-been-here");
   const [sessions, threads] = await Promise.all([
-    book(memoryRoot, "Sessions", "A collection of daily, day-lifecycle session notes, each summarising that day's session.", "bx bx-calendar"),
-    book(memoryRoot, "Threads", "A collection of maintained thread notes, each tracking a line of multi-session running work.", "bx bx-git-branch")
+    book(memoryRoot, "Sessions", CONTAINER_PURPOSES.memorySessions, "bx bx-calendar"),
+    book(memoryRoot, "Threads", CONTAINER_PURPOSES.memoryThreads, "bx bx-git-branch")
   ]);
-  const knowledgeRoot = await book(rootId, "Knowledge", "The secondary memory system \u2014 learned knowledge that adds to or conflicts with the assistant's training data, about the master/user and across domains.", "bx bx-library");
+  const knowledgeRoot = await book(rootId, "Knowledge", CONTAINER_PURPOSES.knowledge, "bx bx-library");
   const [knowledgeMaster, domains] = await Promise.all([
-    book(knowledgeRoot, "Master", "A secondary collection of maintained notes about the master/user that don't fit the primary Master area (Biography / Goals / Preferences).", "bx bx-user-circle"),
-    book(knowledgeRoot, "Domains", "A collection of domain-scoped books. Each domain holds one maintained Sources note plus the sub-category information notes capturing important learned knowledge \u2014 beyond or conflicting with training data \u2014 about that domain.", "bx bx-category")
+    book(knowledgeRoot, "Master", CONTAINER_PURPOSES.knowledgeMaster, "bx bx-user-circle"),
+    book(knowledgeRoot, "Domains", CONTAINER_PURPOSES.knowledgeDomains, "bx bx-category")
   ]);
-  const insightsRoot = await book(rootId, "Insights", "The insights system \u2014 the brain's record of itself, starting with per-day logs of how its own content changed.", "bx bx-bulb");
-  const logs = await book(insightsRoot, "Logs", "A collection of per-day, auto-generated notes recording the brain content (notes) created, updated, or deleted that day.", "bx bx-history");
+  const insightsRoot = await book(rootId, "Insights", CONTAINER_PURPOSES.insights, "bx bx-bulb");
+  const logs = await book(insightsRoot, "Logs", CONTAINER_PURPOSES.insightsLogs, "bx bx-history");
   return {
     version: 9,
     root: rootId,
@@ -22341,37 +22673,8 @@ async function generateDailyLog(trilium, cfg, date4) {
   return { date: date4, noteId: logNoteId, ...counts, action: "created" };
 }
 
-// src/tools-master.ts
-var txt = (obj) => ({
-  content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }]
-});
-var AREAS = ["biography", "goals", "preferences"];
-function registerMasterTools(server, trilium, brainRef) {
-  const b = () => brainRef.config;
-  server.tool("master", "Read a Master singleton in full: biography, goals, or preferences. Returns its id, content, and relation snippet.", { which: exports_external.enum(AREAS) }, async ({ which }) => {
-    const id = b().master[which];
-    if (!id)
-      throw new Error("BrainLLM not bootstrapped \u2014 run bootstrap.");
-    const [note, content] = await Promise.all([trilium.getNote(id), trilium.getNoteContent(id).catch(() => "")]);
-    const relations = relationSnippet(note);
-    return txt({ which, id, content, ...relations ? { relations } : {} });
-  });
-  server.tool("master_recall", "Skim all three Master singletons \u2014 the opening lines of biography, goals, and preferences (with ids and relation snippets).", {}, async () => {
-    const out = {};
-    for (const which of AREAS) {
-      const id = b().master[which];
-      if (!id)
-        continue;
-      const [note, content] = await Promise.all([trilium.getNote(id).catch(() => null), trilium.getNoteContent(id).catch(() => "")]);
-      const relations = note ? relationSnippet(note) : undefined;
-      out[which] = { id, preview: toText(content, 200), ...relations ? { relations } : {} };
-    }
-    return txt(out);
-  });
-}
-
 // src/tools-surface.ts
-var txt2 = (obj) => ({
+var txt = (obj) => ({
   content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }]
 });
 var labelOf = (n, name) => n.attributes.find((a) => a.type === "label" && a.name === name)?.value;
@@ -22402,10 +22705,37 @@ async function skim(trilium, ancestorNoteId, opts = {}) {
     };
   }));
 }
-async function readFull(trilium, id) {
+async function readFull(trilium, id, opts = {}) {
   const [note, content] = await Promise.all([trilium.getNote(id), trilium.getNoteContent(id).catch(() => "")]);
   const relations = relationSnippet(note);
-  return { id, title: note.title, kind: labelOf(note, "noteType"), content, ...relations ? { relations } : {} };
+  const base = { id, title: note.title, kind: labelOf(note, "noteType"), ...relations ? { relations } : {} };
+  if (!opts.section) {
+    return {
+      ...base,
+      content,
+      ...content.length >= LARGE_NOTE_CHARS ? { size: content.length, hint: `${Math.round(content.length / 1000)}k characters. Read one section at a time with section="<heading>" \u2014 outline(${id}) lists them.` } : {}
+    };
+  }
+  const found = getSection(content, opts.section, opts.occurrence ?? 1);
+  if (!found.matched) {
+    return {
+      ...base,
+      content: "",
+      section: opts.section,
+      matched: false,
+      available: found.available,
+      hint: `No "${opts.section}" heading at h2/h3/h4. available= lists the note's real heading texts \u2014 re-target from there rather than falling back to a whole-note read.`
+    };
+  }
+  return {
+    ...base,
+    content: found.content,
+    section: opts.section,
+    matched: true,
+    headingCount: found.headingCount,
+    ...found.subsections?.length ? { subsections: found.subsections } : {},
+    ...found.headingCount && found.headingCount > 1 && !opts.occurrence ? { hint: `${found.headingCount} headings share that text \u2014 this is the FIRST. Pass occurrence= (1-${found.headingCount}) to read another.` } : {}
+  };
 }
 async function previewWithRelations(trilium, id, len = 200) {
   const [note, content] = await Promise.all([trilium.getNote(id).catch(() => null), trilium.getNoteContent(id).catch(() => "")]);
@@ -22413,22 +22743,66 @@ async function previewWithRelations(trilium, id, len = 200) {
   return { preview: toText(content, len), ...relations ? { relations } : {} };
 }
 
+// src/tools-master.ts
+var txt2 = (obj) => ({
+  content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }]
+});
+var AREAS = ["biography", "goals", "preferences"];
+function registerMasterTools(server, trilium, brainRef) {
+  const b = () => brainRef.config;
+  server.tool("master", `Read a Master singleton: biography, goals, or preferences. Returns its id, content, and
+relation snippet.
+
+section="<heading>" reads ONE section instead of the whole note \u2014 the efficient path on
+preferences, whose schedule tables make it the largest of the three, when the session needs one
+day's blocks rather than the whole week. outline(id) lists the headings.`, {
+    which: exports_external.enum(AREAS),
+    section: exports_external.string().optional().describe("Read only this heading's section (h2/h3/h4), instead of the whole note"),
+    occurrence: exports_external.number().int().positive().optional().describe("section=: which same-text heading, 1-based (default: the first)")
+  }, async ({ which, section, occurrence }) => {
+    const id = b().master[which];
+    if (!id)
+      throw new Error("BrainLLM not bootstrapped \u2014 run bootstrap.");
+    const read = await readFull(trilium, id, { section, occurrence });
+    const { id: _id, title: _title, kind: _kind, ...rest } = read;
+    return txt2({ which, id, ...rest });
+  });
+  server.tool("master_recall", "Skim all three Master singletons \u2014 the opening lines of biography, goals, and preferences (with ids and relation snippets).", {}, async () => {
+    const out = {};
+    for (const which of AREAS) {
+      const id = b().master[which];
+      if (!id)
+        continue;
+      const [note, content] = await Promise.all([trilium.getNote(id).catch(() => null), trilium.getNoteContent(id).catch(() => "")]);
+      const relations = note ? relationSnippet(note) : undefined;
+      out[which] = { id, preview: toText(content, 200), ...relations ? { relations } : {} };
+    }
+    return txt2(out);
+  });
+}
+
 // src/tools-llm.ts
 function registerLlmTools(server, trilium, brainRef) {
   const b = () => brainRef.config;
-  server.tool("llm", "Read an LLM note in full: responsibilities or protocols (singletons), or a diary entry by id.", {
+  server.tool("llm", `Read an LLM note: responsibilities or protocols (singletons), or a diary entry by id.
+
+section="<heading>" reads ONE section instead of the whole note \u2014 the efficient path on
+protocols, which is the largest singleton and the one most often needed in part rather than
+whole. outline(id) lists the headings.`, {
     which: exports_external.enum(["responsibilities", "protocols", "diary"]),
-    id: exports_external.string().optional().describe("diary only: the entry id from llm_recall")
-  }, async ({ which, id }) => {
+    id: exports_external.string().optional().describe("diary only: the entry id from llm_recall"),
+    section: exports_external.string().optional().describe("Read only this heading's section (h2/h3/h4), instead of the whole note"),
+    occurrence: exports_external.number().int().positive().optional().describe("section=: which same-text heading, 1-based (default: the first)")
+  }, async ({ which, id, section, occurrence }) => {
     if (which === "diary") {
       if (!id)
         throw new Error("Reading a diary entry needs its id \u2014 use llm_recall to find one.");
-      return txt2(await readFull(trilium, id));
+      return txt(await readFull(trilium, id, { section, occurrence }));
     }
     const noteId = b().llm[which];
     if (!noteId)
       throw new Error("BrainLLM not bootstrapped \u2014 run bootstrap.");
-    return txt2(await readFull(trilium, noteId));
+    return txt(await readFull(trilium, noteId, { section, occurrence }));
   });
   server.tool("llm_recall", "Skim the LLM surface: responsibilities & protocols opening lines (with relation snippets), plus recent diary entries.", { limit: exports_external.number().optional() }, async ({ limit }) => {
     const cfg = b();
@@ -22437,7 +22811,7 @@ function registerLlmTools(server, trilium, brainRef) {
       previewWithRelations(trilium, cfg.llm.protocols),
       skim(trilium, cfg.llm.diary, { kind: "diary", limit: limit ?? 7 })
     ]);
-    return txt2({
+    return txt({
       responsibilities: { id: cfg.llm.responsibilities, ...resp },
       protocols: { id: cfg.llm.protocols, ...prot },
       diary
@@ -22449,21 +22823,28 @@ function registerLlmTools(server, trilium, brainRef) {
 function registerMemoryTools(server, trilium, brainRef) {
   const b = () => brainRef.config;
   server.tool("memory", `Read a Memory note in full by id \u2014 a thread or a session. A thread book returns its
-Context/Resolution plus a children index ({id, date, preview}[], newest first) instead of a
-flat body \u2014 the day-to-day content lives in those [yyyy-mm-dd] children, not the book. Pass
-date="yyyy-mm-dd" to resolve straight to that day's child in the same call, or call memory()
-again with a child's id from the index.`, {
+Context/Resolution plus a children index ({id, date, blocks[]}, newest first) instead of a
+flat body \u2014 the day-to-day content lives in those [yyyy-mm-dd] children, not the book. Each
+child is indexed by its ADDENDUM BLOCKS \u2014 marker, identification line, and lead \u2014 rather than a
+slice from the top of the body, which on a record note is the header and therefore identical on
+every child.
+
+Pass date="yyyy-mm-dd" to resolve straight to that day's child in the same call, or call
+memory() again with a child's id from the index. section="<heading>" reads one section instead
+of the whole body \u2014 use it on long sessions and consolidated thread Contexts.`, {
     id: exports_external.string(),
-    date: exports_external.string().optional().describe("Thread books only: resolve directly to this day's child note (yyyy-mm-dd)")
-  }, async ({ id, date: date4 }) => {
+    date: exports_external.string().optional().describe("Thread books only: resolve directly to this day's child note (yyyy-mm-dd)"),
+    section: exports_external.string().optional().describe("Read only this heading's section (h2/h3/h4), instead of the whole note"),
+    occurrence: exports_external.number().int().positive().optional().describe("section=: which same-text heading, 1-based (default: the first)")
+  }, async ({ id, date: date4, section, occurrence }) => {
     const note = await trilium.getNote(id).catch(() => null);
     if (!note || labelOf(note, "noteType") !== "thread")
-      return txt2(await readFull(trilium, id));
+      return txt(await readFull(trilium, id, { section, occurrence }));
     if (date4) {
       const child = await trilium.searchNotes(`#noteType=threadEntry #created='${date4}'`, { ancestorNoteId: id, fastSearch: true, limit: 1 }).catch(() => ({ results: [] }));
       if (child.results[0])
-        return txt2(await readFull(trilium, child.results[0].noteId));
-      return txt2({ id, title: note.title, kind: "thread", note: `No entry for ${date4}.` });
+        return txt(await readFull(trilium, child.results[0].noteId, { section, occurrence }));
+      return txt({ id, title: note.title, kind: "thread", note: `No entry for ${date4}.` });
     }
     const children = await trilium.searchNotes("#noteType=threadEntry", {
       ancestorNoteId: id,
@@ -22472,13 +22853,17 @@ again with a child's id from the index.`, {
       orderBy: "dateCreated",
       orderDirection: "desc"
     }).catch(() => ({ results: [] }));
-    const entries = await Promise.all(children.results.map(async (c) => ({
-      id: c.noteId,
-      date: labelOf(c, "created") ?? c.dateCreated.slice(0, 10),
-      preview: toText(await trilium.getNoteContent(c.noteId).catch(() => ""), 160)
-    })));
-    const full = await readFull(trilium, id);
-    return txt2({ ...full, children: entries });
+    const entries = await Promise.all(children.results.map(async (c) => {
+      const content = await trilium.getNoteContent(c.noteId).catch(() => "");
+      const blocks = addendumIndex(content);
+      return {
+        id: c.noteId,
+        date: labelOf(c, "created") ?? c.dateCreated.slice(0, 10),
+        ...blocks.length ? { blocks } : { preview: toText(content, 160) }
+      };
+    }));
+    const full = await readFull(trilium, id, { section, occurrence });
+    return txt({ ...full, children: entries });
   });
   server.tool("memory_recall", "Skim Memory: active threads and recent sessions (ids + previews). An optional query filters threads by title.", { query: exports_external.string().optional(), limit: exports_external.number().optional() }, async ({ query, limit }) => {
     const cfg = b();
@@ -22501,14 +22886,24 @@ again with a child's id from the index.`, {
       const content = await trilium.getNoteContent(child.noteId).catch(() => "");
       return { ...t, latestActivity: { date: date4, preview: toText(content, 160) } };
     }));
-    return txt2({ threads, sessions });
+    return txt({ threads, sessions });
   });
 }
 
 // src/tools-knowledge.ts
 function registerKnowledgeTools(server, trilium, brainRef) {
   const b = () => brainRef.config;
-  server.tool("knowledge", "Read a Knowledge note in full by id \u2014 a user-knowledge note, a domain information note, or a Sources note.", { id: exports_external.string() }, async ({ id }) => txt2(await readFull(trilium, id)));
+  server.tool("knowledge", `Read a Knowledge note by id \u2014 a user-knowledge note, a domain information note, or a Sources note.
+
+Pass section="<heading>" to read ONE section instead of the whole body \u2014 the read-side
+counterpart to revise(section=), matching on the same heading contract, so a name that reads
+also writes. Use it on anything large: a note past the read ceiling cannot be returned whole at
+all, and outline(id) lists the headings to choose from. occurrence= disambiguates repeated
+heading texts.`, {
+    id: exports_external.string(),
+    section: exports_external.string().optional().describe("Read only this heading's section (h2/h3/h4), instead of the whole note"),
+    occurrence: exports_external.number().int().positive().optional().describe("section=: which same-text heading, 1-based (default: the first)")
+  }, async ({ id, section, occurrence }) => txt(await readFull(trilium, id, { section, occurrence })));
   server.tool("knowledge_recall", "Skim Knowledge. With a domain: that domain's Sources + information notes. Without: user-knowledge notes plus the list of domains.", { query: exports_external.string().optional(), domain: exports_external.string().optional() }, async ({ query, domain }) => {
     const cfg = b();
     if (domain) {
@@ -22516,11 +22911,11 @@ function registerKnowledgeTools(server, trilium, brainRef) {
       const found = await trilium.searchNotes(`#noteType=domain #domain='${slug}'`, { ancestorNoteId: cfg.knowledge.domains, fastSearch: true, limit: 1 }).catch(() => ({ results: [] }));
       const dom = found.results[0];
       if (!dom)
-        return txt2({ note: `No domain "${domain}" yet.` });
-      return txt2({ domain: dom.title, contents: await skim(trilium, dom.noteId, { query, limit: 50 }) });
+        return txt({ note: `No domain "${domain}" yet.` });
+      return txt({ domain: dom.title, contents: await skim(trilium, dom.noteId, { query, limit: 50 }) });
     }
     const domains = await skim(trilium, cfg.knowledge.domains, { kind: "domain", limit: 50 });
-    return txt2({
+    return txt({
       userKnowledge: await skim(trilium, cfg.knowledge.master, { kind: "user", query, limit: 30 }),
       domains: domains.map((d) => ({ id: d.id, title: d.title }))
     });
@@ -22530,14 +22925,19 @@ function registerKnowledgeTools(server, trilium, brainRef) {
 // src/tools-insights.ts
 function registerInsightsTools(server, trilium, brainRef) {
   const b = () => brainRef.config;
-  server.tool("insights", "Read the BrainLLM's change log for a day (default: today). Format: YYYY-MM-DD.", { date: exports_external.string().optional() }, async ({ date: date4 }) => {
+  server.tool("insights", `Read the BrainLLM's change log for a day (default: today). Format: YYYY-MM-DD.
+section="<heading>" reads one section instead of the whole log.`, {
+    date: exports_external.string().optional(),
+    section: exports_external.string().optional().describe("Read only this heading's section (h2/h3/h4), instead of the whole log"),
+    occurrence: exports_external.number().int().positive().optional().describe("section=: which same-text heading, 1-based (default: the first)")
+  }, async ({ date: date4, section, occurrence }) => {
     const d = date4 ?? localToday();
     const found = await trilium.searchNotes(`#noteType=log #created='${d}'`, { ancestorNoteId: b().insights.logs, fastSearch: true, limit: 1 }).catch(() => ({ results: [] }));
     if (!found.results[0])
-      return txt2({ date: d, note: "No log for this day." });
-    return txt2(await readFull(trilium, found.results[0].noteId));
+      return txt({ date: d, note: "No log for this day." });
+    return txt(await readFull(trilium, found.results[0].noteId, { section, occurrence }));
   });
-  server.tool("insights_recall", "Skim recent change logs (days + previews).", { limit: exports_external.number().optional() }, async ({ limit }) => txt2(await skim(trilium, b().insights.logs, { kind: "log", limit: limit ?? 14 })));
+  server.tool("insights_recall", "Skim recent change logs (days + previews).", { limit: exports_external.number().optional() }, async ({ limit }) => txt(await skim(trilium, b().insights.logs, { kind: "log", limit: limit ?? 14 })));
 }
 
 // src/tools-advanced.ts
@@ -22940,7 +23340,11 @@ ${block}` }));
     await trilium.addLabel(noteId, "created", d);
     return { noteId, action: "created" };
   }
-  server.tool("start", `Boot BrainLLM \u2014 call ONCE at the start of every session, before responding.
+  server.tool("start", `Boot BrainLLM \u2014 call ONCE at the start of every session, before responding. Master
+PREFERENCES and LLM PROTOCOLS always come back in full, even at the default digest depth: they
+carry the schedule, the working style and the operating rules governing the session itself, so a
+session needs them whole before it knows enough to ask for them. Biography, goals and
+responsibilities come back as section headings + preview.
 Runs maintenance, creates today's diary and session notes if not yet open, then returns: today
 and weekday, the Master digest (biography / goals / preferences), the LLM digest
 (responsibilities / protocols / today's diary preview and ID), this session's note ID, active
@@ -23044,7 +23448,7 @@ sessions need one section, not five documents.`, {
       lastSession: digest.lastSession ?? null,
       changesSinceLastSession: changesSinceLastSession.length ? changesSinceLastSession : undefined,
       ...newDay ? { newDay: true, newDayHint: "First session of the day \u2014 call day() for the sweep payload (previous session + log + changes + monthly deliverables in one call)." } : {},
-      ...(depth ?? "digest") === "digest" ? { depthHint: 'Singletons are section headings + preview. Pull the one you need with master(which) / llm(which); re-run start(depth="full") only if the session genuinely needs the whole self-model.' } : {},
+      ...(depth ?? "digest") === "digest" ? { depthHint: 'Preferences and protocols came back IN FULL \u2014 the two needed whole to orient from the first message. Biography, goals and responsibilities are section headings + preview; pull one with master(which) / llm(which), or a single section with their section= parameter. start(depth="full") serves all five inline.' } : {},
       hygiene: { scanned: hygiene.scanned, fixed: hygiene.fixed.length, transitions: hygiene.transitions, flagged: hygiene.flagged, ...hygiene.suppressed ? { suppressed: hygiene.suppressed } : {} }
     });
   });
@@ -23057,6 +23461,14 @@ instead (rarely needed; token-heavy).
 
 Idempotent: fetches are read-only, the sweep is non-destructive, safe to call multiple times.
 
+Returns pending= \u2014 how much each remaining step actually has to do (addendum markers outstanding,
+maintenance flags already raised, diary blocks written today, which singletons were written
+today). The close protocol is ~7 tools landing exactly when context is scarcest, and reciting
+every step unconditionally spends that context on steps with nothing to do. Also returns audit=,
+a cross-singleton check nothing else performs: whether the five singletons agree with each other,
+AND whether the LLM's operating rules still serve what the user's goals and preferences call for
+\u2014 a semantic question, not a textual one, which consistency() and maintain() cannot answer.
+
 After session() returns, work through this protocol \u2014 order doesn't matter mechanically (each
 step is tracked by the tool call itself, not by sequence), but close() enforces that every one
 of diary(), session() [this call], remarks(), addendum(), and maintain() actually ran before it
@@ -23112,6 +23524,24 @@ rather than listing them unconditionally for every caller to work around.`, {
       }
     }
     const hygiene = await sweep(trilium, cfg, { deep: false, dryRun: false }).catch(() => null);
+    const pendingAddendums = await trilium.searchNotes("#noteType note.content *=* 'Addendum'", { ancestorNoteId: cfg.root, fastSearch: false, limit: 40 }).then((r) => r.results.filter((n) => {
+      const kind = labelOf2(n, "noteType");
+      return kind && !["session", "diary", "log", "threadEntry", "thread"].includes(kind);
+    }).length).catch(() => null);
+    const singletonStubs = [
+      ["biography", biography],
+      ["goals", goals],
+      ["preferences", preferences],
+      ["responsibilities", responsibilities],
+      ["protocols", protocols]
+    ];
+    const touchedToday = singletonStubs.filter(([, s]) => s.lastModified === d).map(([name]) => name);
+    const pending = {
+      addendums: pendingAddendums === null ? "unknown" : pendingAddendums,
+      maintenanceFlags: hygiene?.flagged.length ?? 0,
+      diaryBlocksToday: diaryEntry?.blocks ?? 0,
+      singletonsWrittenToday: touchedToday.length ? touchedToday : "none"
+    };
     const scoped = scope === "agent";
     return txt4({
       date: d,
@@ -23121,13 +23551,20 @@ rather than listing them unconditionally for every caller to work around.`, {
       llm: { responsibilities, protocols },
       diary: diaryEntry,
       maintenance: hygiene ? { scanned: hygiene.scanned, fixed: hygiene.fixed.length, transitions: hygiene.transitions, flagged: hygiene.flagged, ...hygiene.suppressed ? { suppressed: hygiene.suppressed } : {} } : "skipped",
+      pending,
+      audit: scoped ? undefined : {
+        consistency: "Read all five singletons and check for ambiguity, internal contradiction, or claims that disagree across them. Fix what you find with revise() BEFORE close(), so the log records a brain that already agrees with itself.",
+        alignment: "Then check correlation, not just agreement: do responsibilities and protocols actually serve what biography, goals and preferences describe? A protocol can be perfectly consistent and still be serving a goal that has moved.",
+        readThem: `master("biography"|"goals"|"preferences") and llm("responsibilities"|"protocols") \u2014 or one section at a time with section=. Written today: ${touchedToday.length ? touchedToday.join(", ") : "none"}.`
+      },
       next: [
         ...scoped ? ["Scoped run \u2014 the user's master singletons and your LLM singletons are OUT of scope and deliberately not listed here."] : [
           "Update master singletons (biography / goals / preferences) via revise() with session observations about the user.",
           "Update LLM singletons (responsibilities / protocols) via revise() with session observations about yourself."
         ],
-        scoped ? "Call addendum() \u2014 fold only what is in your lane; leaving out-of-scope addendums for the next interactive session is correct, and the call itself satisfies the gate." : "Call addendum() \u2014 find and merge any pending addendums.",
-        scoped ? "Call maintain() \u2014 audit brain hygiene; pass domain= to keep the flags in your lane." : "Call maintain() \u2014 audit and fix brain hygiene.",
+        ...scoped ? [] : ["Audit the singletons against each other and against each other's PURPOSE \u2014 see audit= above. This is the step that catches an operating rule still serving a goal that has moved."],
+        scoped ? `Call addendum() \u2014 fold only what is in your lane; leaving out-of-scope addendums for the next interactive session is correct, and the call itself satisfies the gate. (${pending.addendums} note(s) currently carry addendum markers.)` : pending.addendums === 0 ? "Call addendum() \u2014 0 notes currently carry addendum markers, so this should come back clean; the call still satisfies the gate." : `Call addendum() \u2014 ${pending.addendums} note(s) carry addendum markers; fold each into its section.`,
+        scoped ? "Call maintain() \u2014 audit brain hygiene; pass domain= to keep the flags in your lane." : pending.maintenanceFlags === 0 ? "Call maintain() \u2014 the lite sweep just ran clean, so this is a formality unless you want deep=true." : `Call maintain() \u2014 the lite sweep already flagged ${pending.maintenanceFlags} item(s), listed above.`,
         "Call remarks() \u2014 get the diary cues: your experience, opinions, and existence this session, plus BrainLLM remarks.",
         "Call diary() \u2014 write the day's unfiltered record with the cues in hand; the gate counts it only after remarks().",
         "Call close() \u2014 commit the session log (mandatory, last). Refuses until every step ran and session \u2192 remarks \u2192 diary held; pass force=true only when a skipped step genuinely has nothing to log."
@@ -23387,13 +23824,15 @@ 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: exports_external.array(exports_external.string()).optional().describe("Topic tags \u2014 slugged server-side"),
     supersedes: exports_external.string().optional().describe("noteId this replaces \u2014 old note is archived and wired supersedes"),
+    mustCreate: exports_external.boolean().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"),
     connect: exports_external.array(exports_external.object({
       relation: exports_external.enum(RelationTypes),
       toNoteId: exports_external.string()
     })).optional().describe("Relations to wire from this note in the same call \u2014 same semantics as connect() (idempotent, worksWith wired both ways)"),
     icon: exports_external.string().optional().describe('Display icon \u2014 a boxicons class ("bx bx-brain") or a bare name ("brain"); normalized server-side'),
     date: exports_external.string().optional().describe("ISO date override (default: today)")
-  }, async ({ kind, title, body, goal, identity, domain, revision, topics, supersedes, connect: connectRels, icon, date: date4 }) => {
+  }, async ({ kind, title, body, goal, identity, domain, revision, topics, supersedes, mustCreate, connect: connectRels, icon, date: date4 }) => {
+    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: date4 };
     const d = date4 ?? today();
     const { html, warnings: sanitizeWarnings } = renderBody(body ?? "");
@@ -23450,6 +23889,7 @@ For diary entries use the dedicated diary() tool \u2014 remember(kind="diary") i
       const found = sourcesId ? { results: [] } : await trilium.searchNotes("#noteType=sources", { ancestorNoteId: domainId, fastSearch: true, limit: 1 }).catch(() => ({ results: [] }));
       let sid = sourcesId ?? found.results[0]?.noteId;
       let wrote = false;
+      let sourceMerge = {};
       if (!sid) {
         const created2 = await trilium.createNote(domainId, "Sources", contentFor("sources", { date: d, body: html, domain: domainTitle }));
         sid = created2.note.noteId;
@@ -23461,7 +23901,8 @@ For diary entries use the dedicated diary() tool \u2014 remember(kind="diary") i
         const current = await trilium.getNoteContent(sid).catch(() => "");
         if (!current.includes(html)) {
           await trilium.createRevision(sid).catch(() => null);
-          const merged = setSection(current, "Sources", html, "append");
+          const merged = mergeUnderSection(current, html, "Sources");
+          sourceMerge = { ...merged.mergedInto.length ? { mergedIntoGroups: merged.mergedInto } : {}, ...merged.appended.length ? { newGroups: merged.appended } : {} };
           const stamped = bumpLastUpdated(merged.html, d);
           await trilium.updateNoteContent(sid, stamped.html);
           await trilium.updateLabelValue(sid, "updated", d);
@@ -23505,6 +23946,7 @@ For diary entries use the dedicated diary() tool \u2014 remember(kind="diary") i
         location: locationLabel(kind, domainTitle),
         ...createdDomain ? { createdDomain: domainTitle } : {},
         ...revisionChanges.length ? { revision: revisionChanges } : {},
+        ...sourceMerge,
         ...revisionKeys.length ? { revisionRows: revisionKeys } : {},
         ...placeholderLeft ? { structureHint: "The Revision table still holds only its placeholder row. Every source marked \u2705 was verified by someone \u2014 record that with revision=[{source, marker, date}] so the table says so too; marker dates live there, never inline." } : {},
         ...looseProse ? { placementHint: "The body was appended to the Sources section as a loose block, which is rarely what a maintained source list wants. Fold it into the existing entries with revise(noteId, find=\u2026) \u2014 or pass list markup so it joins the list structurally." } : {},
@@ -23523,6 +23965,8 @@ For diary entries use the dedicated diary() tool \u2014 remember(kind="diary") i
       const { domainId, domainTitle, createdDomain } = await resolveDomain(trilium, b(), domain);
       const inDomain = await trilium.searchNotes("#noteType=information", { ancestorNoteId: domainId, fastSearch: true, limit: 100 }).catch(() => ({ results: [] }));
       const existing2 = inDomain.results.find((n) => sameTitle(n.title, subTitle));
+      if (existing2 && mustCreate)
+        return refuseAdoption(existing2.noteId, existing2.title, `in domain "${domainTitle}"`);
       if (existing2) {
         const current = await trilium.getNoteContent(existing2.noteId).catch(() => "");
         if (isDuplicateAppend(current, html))
@@ -23560,6 +24004,8 @@ For diary entries use the dedicated diary() tool \u2014 remember(kind="diary") i
       return err("rejected_kind", "Diary entries use the dedicated diary() tool.", `Call diary(body="...") to write today's diary entry.`);
     if (kind === "session")
       return err("rejected_kind", "Session notes are written by close().", 'Call close(summary="...") to log this session.');
+    if (kind === "claim")
+      return err("rejected_kind", "Claims are registered by claim().", 'Call claim(assertion="...", check="...") \u2014 a claim carries a verification schedule and history that a generic write cannot set up.');
     if (kind === "log")
       return err("rejected_kind", "Log notes are auto-generated by close() and cannot be written manually.");
     if (kind === "domain")
@@ -23570,6 +24016,8 @@ For diary entries use the dedicated diary() tool \u2014 remember(kind="diary") i
     if (!cleanTitle)
       return err("missing_param", `kind="${kind}" requires a title.`, 'Add title="<note title>" to your call.');
     const existing = await findExisting(kind, cleanTitle);
+    if (existing && mustCreate)
+      return refuseAdoption(existing.noteId, existing.title, `in ${KIND_AREA[kind] ?? "the brain"}`);
     if (existing) {
       if (kind === "thread" && !identity && !leadingIdentification(html)) {
         return err("missing_identity", 'Thread addendums open with the canonical identification line (h3): "LLM \xB7 environment \xB7 agent/mode [\xB7 Run N]".', `Pass identity="Claude \u2026 \xB7 <environment> \xB7 <agent/mode>" \u2014 the server renders it as the addendum's h3.`);
@@ -23732,25 +24180,38 @@ a doubly-escaped tag", "which cite a 2026 date"). Backslashes must be escaped.`,
       } catch (e) {
         return err("invalid_pattern", `Not a valid regular expression: ${e.message}`, "Escape backslashes \u2014 a JSON string needs \\\\d for \\d.");
       }
-      const candidates = (await run(`note.content %= '${escapeQueryValue(regex)}'`)).filter(filterNote);
+      const candidates = (await run(`note.content %= '${escapeQueryRegex(regex)}'`)).filter(filterNote);
       const confirmed = [];
       let rejected = 0;
+      let tagSpanning = 0;
       for (const n of candidates) {
         if (confirmed.length >= max)
           break;
         const content = await trilium.getNoteContent(n.noteId).catch(() => "");
-        if (content && re.test(content))
+        if (!content) {
+          rejected++;
+          continue;
+        }
+        const rawHit = re.test(content);
+        const projectedHit = !rawHit && re.test(stripTagsWithMap(content).text);
+        if (rawHit || projectedHit) {
+          if (projectedHit)
+            tagSpanning++;
           confirmed.push(n);
-        else
+        } else
           rejected++;
       }
       const results2 = await Promise.all(confirmed.map(buildResult));
+      const notes = [
+        rejected ? `${rejected} backend candidate(s) did not actually match the pattern and were dropped \u2014 results are verified against the real regex, not just the search index.` : null,
+        tagSpanning ? `${tagSpanning} match(es) were found only after stripping markup \u2014 the phrase is split by an inline tag there.` : null,
+        results2.length === 0 ? "No bodies matched that pattern, searched both as stored HTML and tag-stripped. Note that Trilium's %= pre-filter reads a striptags'd copy, so a pattern anchored ON tags may never reach verification \u2014 consistency() scans exhaustively if you need certainty." : null
+      ].filter(Boolean);
       return txt4({
         mode: "regex",
         pattern: regex,
         results: results2,
-        ...rejected ? { note: `${rejected} backend candidate(s) did not actually match the pattern and were dropped \u2014 results are verified against the real regex, not just the search index.` } : {},
-        ...results2.length === 0 ? { note: "No bodies matched that pattern. Regex runs against stored HTML, so anchor on what is actually stored (tags and entities), not on rendered text." } : {}
+        ...notes.length ? { note: notes.join(" ") } : {}
       });
     }
     if (orderBy) {
@@ -23913,7 +24374,7 @@ find=; to add content next to a heading without touching its body, use mode="bef
     title: exports_external.string().optional().describe("New title (normalized server-side)"),
     section: exports_external.string().optional().describe("Target a section by heading text (h2/h3/h4, in that order); omit for whole-note append/replace"),
     occurrence: exports_external.number().int().positive().optional().describe("section=: which same-text heading to target, 1-based (default: the first). Read them with outline(noteId)."),
-    mode: exports_external.enum(["append", "replace", "before", "after"]).optional().describe('append (default) | replace | before | after \u2014 "before"/"after" insert adjacent to the section= heading without touching its body'),
+    mode: exports_external.enum(["append", "replace", "before", "after", "remove"]).optional().describe('append (default) | replace | before | after | remove \u2014 "before"/"after" insert adjacent to the section= heading without touching its body; "remove" deletes the section= heading and its body, and needs no body='),
     find: exports_external.string().optional().describe("Exact raw string to replace throughout the body with body= \u2014 targeted surgery without a read+full-replace. Takes precedence over section/mode."),
     nth: exports_external.number().int().positive().optional().describe("find=: replace only the Nth occurrence, 1-based (default: all of them)"),
     edits: exports_external.array(exports_external.object({
@@ -24001,23 +24462,37 @@ find=; to add content next to a heading without touching its body, use mode="bef
         const tolerant = [...source.matchAll(rx)].map((m) => ({ start: m.index, length: m[0].length }));
         return tolerant.length ? spans(tolerant, "attribute-tolerant") : null;
       };
-      const missHint = (needle) => {
+      const missHint = (needle, source, alreadyConsumed) => {
+        if (alreadyConsumed)
+          return `Not found \u2014 but an EARLIER edit in this same edits= array already replaced this exact string. The array is applied in order against one body, so the second pass had nothing left to match. This is the expected result, not a failure.`;
         if (looksEntityEscaped(needle))
           return `Not found \u2014 the search string carries escaped markup (&lt;\u2026&gt;) while note bodies store real tags. Pass the tag literally, e.g. "<h3>Typography</h3>".`;
         if (spansBlockBoundary(needle))
           return `Not found \u2014 this string spans an element boundary (a closing tag followed by an opening one). Anchor the find INSIDE a single element instead, or target the heading directly with section= (with mode="before"/"after" to insert around it).`;
-        return `Not found in the note body (exact or attribute-tolerant) \u2014 already replaced on a retry, or the text genuinely differs. Verify with inspect(noteId, content=true), or count occurrences cheaply with inspect(noteId, find="<shorter substring>").`;
+        return `Not found in the note body (exact or attribute-tolerant) \u2014 already replaced on a retry, or the text genuinely differs.`;
+      };
+      const missContext = (needle, source) => {
+        const near = nearestContext(source, needle);
+        return near ? { matchedUpTo: near.fragment, storedNearby: near.context } : {};
       };
       const current = await trilium.getNoteContent(noteId).catch(() => "");
       let working = current;
       const results = [];
       let total = 0;
+      const consumed = new Set;
       for (const e of plan) {
         const applied = applyEdit(working, e.find, e.body, e.nth);
         if (!applied) {
-          results.push({ find: e.find, replaced: 0, hint: missHint(e.find) });
+          const alreadyConsumed = consumed.has(e.find);
+          results.push({
+            find: e.find,
+            replaced: 0,
+            hint: missHint(e.find, current, alreadyConsumed),
+            ...alreadyConsumed ? {} : missContext(e.find, working)
+          });
           continue;
         }
+        consumed.add(e.find);
         working = applied.html;
         total += applied.count;
         results.push({ find: e.find, replaced: applied.count, matchMode: applied.matchMode });
@@ -24029,7 +24504,11 @@ find=; to add content next to a heading without touching its body, use mode="bef
           mode: edits ? "edits" : "find-replace",
           replaced: 0,
           date: d,
-          ...edits ? { results } : { hint: results[0].hint }
+          ...edits ? { results } : {
+            hint: results[0].hint,
+            ...results[0].matchedUpTo ? { matchedUpTo: results[0].matchedUpTo } : {},
+            ...results[0].storedNearby ? { storedNearby: results[0].storedNearby } : {}
+          }
         });
       }
       await trilium.createRevision(noteId).catch(() => null);
@@ -24062,6 +24541,45 @@ find=; to add content next to a heading without touching its body, use mode="bef
     }
     if ((mode2 === "before" || mode2 === "after") && !section)
       return err("missing_param", `mode="${mode2}" inserts relative to a heading and needs one.`, 'Pass section="<heading text>" alongside it, or use mode="append" for a whole-note addendum.');
+    if (mode2 === "remove" && !section)
+      return err("missing_param", 'mode="remove" deletes a section and needs one.', 'Pass section="<heading text>". To delete the whole note use forget(noteId).');
+    if (mode2 === "remove" && section) {
+      const current = await trilium.getNoteContent(noteId).catch(() => "");
+      const result = setSection(current, section, "", "remove", occurrence ?? 1);
+      if (!result.matched) {
+        return txt4({
+          ok: true,
+          noteId,
+          mode: `section:remove:${section}`,
+          matched: false,
+          date: d,
+          available: result.available,
+          hint: `No "${section}" heading at h2/h3/h4 \u2014 nothing was removed and the body is untouched. Check available= for the note's real heading texts.`
+        });
+      }
+      await trilium.createRevision(noteId).catch(() => null);
+      const stamped = bumpLastUpdated(result.html, d);
+      await trilium.updateNoteContent(noteId, stamped.html);
+      const titledOnRemove = await applyTitle();
+      const iconOnRemove = await applyIcon(noteId, icon);
+      await trilium.updateLabelValue(noteId, "updated", d);
+      if (labelOf2(note, "status") === "dormant")
+        await trilium.updateLabelValue(noteId, "status", "active");
+      const relsOnRemove = relationSnippet(note);
+      return txt4({
+        ok: true,
+        noteId,
+        mode: `section:remove:${section}`,
+        matched: true,
+        headingCount: result.headingCount,
+        date: d,
+        ...result.replacedSubsections?.length ? { removedSubsections: result.replacedSubsections, displacedHint: `The removed section contained ${result.replacedSubsections.length} nested heading(s) \u2014 they went with it. A revision was taken first.` } : {},
+        ...titledOnRemove.retitled ? { retitled: titledOnRemove.retitled } : {},
+        ...iconOnRemove ? { icon: iconOnRemove } : {},
+        ...relsOnRemove ? { relations: relsOnRemove } : {},
+        ...structuralFindings(noteKind, stamped.html)
+      });
+    }
     let finalContent = null;
     let sectionMiss = {};
     let threadEntryResult = null;
@@ -24079,7 +24597,11 @@ find=; to add content next to a heading without touching its body, use mode="bef
         const result = setSection(current, section, html, sectionMode, occurrence ?? 1);
         finalContent = bumpLastUpdated(result.html, d).html;
         await trilium.updateNoteContent(noteId, finalContent);
-        sectionResult = { matched: result.matched, headingCount: result.headingCount };
+        sectionResult = {
+          matched: result.matched,
+          headingCount: result.headingCount,
+          ...result.replacedSubsections?.length ? { replacedSubsections: result.replacedSubsections } : {}
+        };
         sectionMiss = {
           ...result.appendedAtLevel ? { appendedAtLevel: result.appendedAtLevel } : {},
           ...result.available?.length ? { available: result.available } : {}
@@ -24121,9 +24643,13 @@ ${block}`), d).html;
     return txt4({
       ok: true,
       noteId,
-      mode: body ? section ? `section:${section}` : mode2 ?? "append" : "metadata-only",
+      mode: body ? section ? `section:${mode2 === "before" || mode2 === "after" ? `insert-${mode2}` : mode2 === "append" ? "append-within" : "replace"}:${section}` : mode2 ?? "append" : titled.retitled ? "rename" : iconSet ? "icon" : "no-op",
       date: d,
       ...sectionResult ? { matched: sectionResult.matched, headingCount: sectionResult.headingCount } : {},
+      ...sectionResult?.replacedSubsections?.length ? {
+        replacedSubsections: sectionResult.replacedSubsections,
+        displacedHint: `The replaced section contained ${sectionResult.replacedSubsections.length} nested heading(s) \u2014 they went with it. Re-add any that should have survived.`
+      } : {},
       ...sectionMiss,
       ...sectionHint ? { hint: sectionHint } : {},
       ...threadEntryResult ? { entryId: threadEntryResult.noteId, entryAction: threadEntryResult.action } : {},
@@ -24361,14 +24887,21 @@ Pass a regex with ONE capture group naming the value that should agree:
 
 Without a capture group it degrades to a presence check \u2014 which notes mention this at all.
 
-Matches STORED HTML, so anchor on what is actually stored (tags and entities), not rendered text.
-Escape backslashes. Scope with domain= or kinds= when the phrase is common.`, {
+Matched against BOTH the stored HTML and a tag-stripped projection of it, so a phrase split by an
+inline <strong> or <code> tag is found, and so is a pattern deliberately anchored on tags.
+Escape backslashes. Scope with domain= or kinds= when the phrase is common.
+
+Scans every in-scope note by default. Trilium's %= backend filter is a LOSSY pre-filter \u2014 it
+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: exports_external.string().describe("Regex over note bodies. One capture group = the value that should agree across notes."),
     domain: exports_external.string().optional().describe("Restrict to one knowledge domain"),
     kinds: exports_external.array(exports_external.enum(Kinds)).optional().describe("Restrict to these kinds"),
     includeArchived: exports_external.boolean().optional().describe("Include archived notes (default false)"),
-    limit: exports_external.number().optional().describe("Max notes to examine (default 60)")
-  }, async ({ pattern, domain, kinds, includeArchived, limit }) => {
+    limit: exports_external.number().optional().describe("Max notes to examine (default 60)"),
+    fast: exports_external.boolean().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 }) => {
     let re;
     try {
       re = new RegExp(pattern, "gi");
@@ -24376,7 +24909,7 @@ Escape backslashes. Scope with domain= or kinds= when the phrase is common.`, {
       return err("invalid_pattern", `Not a valid regular expression: ${e.message}`, "Escape backslashes \u2014 a JSON string needs \\\\d for \\d.");
     }
     const max = limit ?? 60;
-    const clauses = [`note.content %= '${escapeQueryValue(pattern)}'`];
+    const clauses = fast ? [`note.content %= '${escapeQueryRegex(pattern)}'`] : ["#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(() => []);
@@ -24389,41 +24922,53 @@ Escape backslashes. Scope with domain= or kinds= when the phrase is common.`, {
     const byValue = new Map;
     const noCapture = [];
     let hasCaptureGroup = false;
-    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 seen = new Set;
+    const scan = (haystack) => {
+      const values = [];
+      let matched = false;
       re.lastIndex = 0;
       let m;
-      let matched = false;
-      while ((m = re.exec(content)) !== null) {
+      while ((m = re.exec(haystack)) !== null) {
         matched = true;
         const captured = m.slice(1).find((g) => g !== undefined);
-        if (captured !== undefined) {
-          hasCaptureGroup = true;
-          const value = toText(captured, 120).trim() || captured.trim();
-          if (seen.has(value))
-            continue;
-          seen.add(value);
-          if (!byValue.has(value))
-            byValue.set(value, []);
-          byValue.get(value).push(stub);
-        }
+        if (captured !== undefined)
+          values.push(toText(captured, 120).trim() || captured.trim());
         if (m[0] === "")
           re.lastIndex++;
       }
-      if (matched && !seen.size)
+      return { values, matched };
+    };
+    let tagSpanning = 0;
+    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 raw = scan(content);
+      const projected = scan(stripTagsWithMap(content).text);
+      if (projected.matched && !raw.matched)
+        tagSpanning++;
+      const seen = new Set;
+      for (const value of [...raw.values, ...projected.values]) {
+        hasCaptureGroup = true;
+        if (seen.has(value))
+          continue;
+        seen.add(value);
+        if (!byValue.has(value))
+          byValue.set(value, []);
+        byValue.get(value).push(stub);
+      }
+      if ((raw.matched || projected.matched) && !seen.size)
         noCapture.push(stub);
     }
     if (!hasCaptureGroup) {
       return txt4({
         mode: "presence",
         pattern,
+        scan: fast ? "fast (%= pre-filter)" : "exhaustive",
+        notesExamined: scoped.length,
         notes: noCapture,
         total: noCapture.length,
-        note: noCapture.length === 0 ? "No note body matched that pattern. Regex runs against stored HTML \u2014 anchor on tags and entities, not rendered text." : 'The pattern has no capture group, so this is a presence check only. Add one \u2014 consistency("(\\\\d+) users") \u2014 to compare the values these notes actually assert.'
+        note: noCapture.length === 0 ? `No note body matched that pattern across ${scoped.length} note(s), searched both as stored HTML and tag-stripped.${fast ? " fast=true used Trilium's %= pre-filter, which reads a striptags'd copy and can drop notes \u2014 re-run without it before concluding anything." : " That is evidence about the pattern, not the brain."}` : 'The pattern has no capture group, so this is a presence check only. Add one \u2014 consistency("(\\\\d+) users") \u2014 to compare the values these notes actually assert.'
       });
     }
     const groups = [...byValue.entries()].map(([value, notes2]) => ({ value, count: notes2.length, notes: notes2 })).sort((a, b2) => b2.count - a.count);
@@ -24431,8 +24976,10 @@ Escape backslashes. Scope with domain= or kinds= when the phrase is common.`, {
     return txt4({
       mode: "consistency",
       pattern,
+      scan: fast ? "fast (%= pre-filter)" : "exhaustive",
       ...domain ? { domain: slugify(domain) } : {},
       notesExamined: scoped.length,
+      ...tagSpanning ? { tagSpanning, tagSpanningNote: `${tagSpanning} note(s) matched only once markup was stripped \u2014 the phrase is split by an inline tag there. Before v10.3 those were invisible.` } : {},
       distinctValues: groups.length,
       agreement: groups.length === 0 ? "no-data" : agrees ? "unanimous" : "DISAGREEMENT",
       groups,
@@ -24469,8 +25016,10 @@ remember(revision=) matches on exactly) without reading the note.`, {
       headings: headings.map((h) => ({
         level: h.level,
         text: h.text,
-        ...h.occurrence > 1 ? { occurrence: h.occurrence } : {}
+        ...h.occurrence > 1 ? { occurrence: h.occurrence } : {},
+        ...h.raw ? { raw: h.raw } : {}
       })),
+      ...headings.some((h) => h.raw) ? { rawHint: "Headings carrying inline markup also report raw \u2014 their STORED form. section= matches text (use it), find= matches stored HTML (use raw). Building a find= from text alone misses on exactly these headings." } : {},
       sectionLevel: sectionLevelFor(content),
       ...tables.length ? { tables } : {},
       ...report.duplicateHeadings.length ? { duplicateHeadings: report.duplicateHeadings } : {},
@@ -24487,19 +25036,28 @@ surface reads and explore(): reach for it when you need the raw label set, the b
 or the attachment inventory \u2014 confirming a fix landed, debugging drift \u2014 rather than a
 kind-specific summary. Read-only, safe on any note including structural containers.
 
+Pass section="<heading>" alongside content=true to get one section's raw body instead of the
+whole thing \u2014 the same heading contract revise(section=) writes through.
+
 Pass find="<literal>" to count occurrences of a literal string in the body \u2014 total plus a
 per-addendum-block breakdown. The staleness-escalation counter: "how many prior entries
-mention this carried flag" becomes one call instead of a full read + manual counting.`, {
+mention this carried flag" becomes one call instead of a full read + manual counting. On zero
+occurrences it returns the nearest fragment that IS present and the stored text around it, so a
+miss is diagnosed in the same call rather than in three more.`, {
     noteId: exports_external.string().describe("Note to inspect"),
     content: exports_external.boolean().optional().describe("Include the note's raw body content (default: false)"),
+    section: exports_external.string().optional().describe("With content=true, return only this heading's section rather than the whole body"),
     find: exports_external.string().optional().describe("Literal string to count in the body \u2014 returns total occurrences + per-addendum-block counts (flag-staleness tracking)")
-  }, async ({ noteId, content, find }) => {
+  }, async ({ noteId, content, section, find }) => {
     const [note, attachments, rawBody] = await Promise.all([
       trilium.getNote(noteId),
       trilium.getNoteAttachments(noteId).catch(() => []),
       content || find ? trilium.getNoteContent(noteId).catch(() => "") : Promise.resolve(undefined)
     ]);
-    const body = content ? rawBody : undefined;
+    let sectionRead = null;
+    if (content && section && rawBody !== undefined)
+      sectionRead = getSection(rawBody, section);
+    const body = content ? sectionRead ? sectionRead.content : rawBody : undefined;
     let findReport;
     if (find && rawBody !== undefined) {
       const countIn = (s) => s.split(find).length - 1;
@@ -24525,11 +25083,19 @@ mention this carried flag" becomes one call instead of a full read + manual coun
       }
       flush(rawBody.length);
       if (!last) {
-        const total = countIn(rawBody);
-        if (total > 0)
-          blocks.push({ block: "(body)", count: total });
-      }
-      findReport = { find, total: countIn(rawBody), blocks };
+        const total2 = countIn(rawBody);
+        if (total2 > 0)
+          blocks.push({ block: "(body)", count: total2 });
+      }
+      const total = countIn(rawBody);
+      const near = total === 0 ? nearestContext(rawBody, find) : null;
+      findReport = {
+        find,
+        total,
+        blocks,
+        ...near ? { matchedUpTo: near.fragment, storedNearby: near.context } : {},
+        ...total === 0 && !near ? { hint: "Not present, and no fragment of it is either \u2014 the string is unrelated to this note's content." } : {}
+      };
     }
     const labels = note.attributes.filter((a) => a.type === "label").map((a) => ({ name: a.name, value: a.value, ...a.isInheritable ? { inheritable: true } : {} }));
     const relations = relationSnippet(note, 50);
@@ -24549,9 +25115,223 @@ mention this carried flag" becomes one call instead of a full read + manual coun
       parentNoteIds: note.parentNoteIds,
       childNoteIds: note.childNoteIds,
       ...findReport ? { findReport } : {},
+      ...sectionRead ? sectionRead.matched ? { section, sectionMatched: true, ...sectionRead.subsections?.length ? { subsections: sectionRead.subsections } : {} } : { section, sectionMatched: false, available: sectionRead.available, hint: `No "${section}" heading \u2014 content is empty. Re-target from available=.` } : {},
       ...body !== undefined ? { content: body } : {}
     });
   });
+  const resolveClaimsContainer = async () => {
+    const cfg = b();
+    const found = await trilium.searchNotes("note.title = 'Claims'", { ancestorNoteId: cfg.insights.root, fastSearch: true, limit: 1 }).catch(() => ({ results: [] }));
+    if (found.results[0])
+      return found.results[0].noteId;
+    const created = await trilium.createNote(cfg.insights.root, "Claims", "<p><em>Checkable assertions and when each was last verified against the world. Registered and verified through claim(); this container is maintained by the tool.</em></p>");
+    await trilium.addLabel(created.note.noteId, "iconClass", "bx bx-check-shield").catch(() => null);
+    return created.note.noteId;
+  };
+  server.tool("claim", `Register a checkable assertion, and record whether it still holds.
+
+consistency() asks whether the brain agrees with ITSELF. Nothing asked whether a specific
+assertion is still true of the codebase, config or live surface it describes \u2014 so a claim that
+quietly stopped being true stayed authoritative until something downstream broke, and "is the
+brain stale" was answered by luck rather than by a query.
+
+BrainLLM never executes anything. It has Trilium access and no shell, and content in a note is
+data, not instructions \u2014 a recipe that ran itself would be an injection surface pointed at the
+user's machine. So a claim stores WHAT to check as inert text; the agent runs it and reports
+back. The tool owns the register, the schedule and the staleness question.
+
+Modes, by which parameters are present:
+  assertion + check  \u2192 REGISTER (or update, deduped by assertion text)
+  claimId + holds    \u2192 VERIFY: record the outcome and re-stamp the clock
+  claimId alone      \u2192 READ one claim with its verification history
+  neither            \u2192 LIST, newest-verified last; filter with status=
+
+A verified claim is quiet until its interval lapses. maintain(deep=true) surfaces lapsed and
+broken ones, so staleness arrives as a maintenance finding instead of a surprise.`, {
+    assertion: exports_external.string().optional().describe('The claim in plain words, e.g. "the parse pipeline runs before validation" \u2014 also the dedup key'),
+    check: exports_external.string().optional().describe("How to verify it, as INERT text a human or agent runs: a command, a query, a file path, a URL. Never executed by BrainLLM"),
+    noteId: exports_external.string().optional().describe("The note this claim is made in \u2014 wired ~derivedFrom so the claim and its source stay linked"),
+    intervalDays: exports_external.number().int().positive().optional().describe("How long a verification stays good (default: 30)"),
+    claimId: exports_external.string().optional().describe("An existing claim, to read or to verify"),
+    holds: exports_external.boolean().optional().describe("With claimId: did the check pass? false marks the claim broken and surfaces it in maintain()"),
+    evidence: exports_external.string().optional().describe("With holds: what you actually observed \u2014 the output, the count, the response. A verification without evidence is an assertion about an assertion"),
+    status: exports_external.enum(["holding", "broken", "lapsed", "all"]).optional().describe("List filter (default: all)"),
+    retire: exports_external.boolean().optional().describe("With claimId: archive this claim \u2014 the thing it described is gone")
+  }, async ({ assertion, check: check2, noteId, intervalDays, claimId, holds, evidence, status, retire }) => {
+    const cfg = b();
+    if (!cfg.root)
+      return txt4({ status: "uninitialized", action: "Run bootstrap first." });
+    const d = today();
+    const container = await resolveClaimsContainer();
+    const lapsed = (n) => {
+      const verifiedOn = labelOf2(n, "verified");
+      if (!verifiedOn)
+        return true;
+      const days = Number(labelOf2(n, "interval") ?? 30);
+      return verifiedOn < new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);
+    };
+    const stateOf = (n) => labelOf2(n, "claimState") === "broken" ? "broken" : lapsed(n) ? "lapsed" : "holding";
+    const row = (n) => ({
+      claimId: n.noteId,
+      assertion: n.title,
+      state: stateOf(n),
+      lastVerified: labelOf2(n, "verified") ?? "never",
+      intervalDays: Number(labelOf2(n, "interval") ?? 30)
+    });
+    if (claimId) {
+      const note = await trilium.getNote(claimId).catch(() => null);
+      if (!note || labelOf2(note, "noteType") !== "claim")
+        return err("not_found", `${claimId} is not a claim.`, "List them with claim() and no arguments.");
+      if (retire) {
+        await trilium.addLabel(claimId, "archived", "").catch(() => null);
+        return txt4({ ok: true, claimId, action: "retired", assertion: note.title });
+      }
+      if (holds === undefined) {
+        const content2 = await trilium.getNoteContent(claimId).catch(() => "");
+        return txt4({ ...row(note), check: getSection(content2, "Check").content, history: getSection(content2, "Verifications").content, relations: relationSnippet(note) });
+      }
+      if (!evidence)
+        return err("missing_param", "A verification needs evidence.", 'Pass evidence="<what you actually observed>" \u2014 the output, the count, the response. Recording a verdict without it makes the register a record of opinions.');
+      const content = await trilium.getNoteContent(claimId).catch(() => "");
+      const entry = `<p><strong>${d} \u2014 ${holds ? "HOLDS" : "BROKEN"}</strong>: ${escapeHtml(evidence)}</p>`;
+      const updated = setSection(content, "Verifications", entry, "append");
+      await trilium.createRevision(claimId).catch(() => null);
+      await trilium.updateNoteContent(claimId, updated.html);
+      await trilium.updateLabelValue(claimId, "verified", d).catch(() => null);
+      await trilium.updateLabelValue(claimId, "claimState", holds ? "holding" : "broken").catch(() => null);
+      await trilium.updateLabelValue(claimId, "updated", d).catch(() => null);
+      const refreshed = await trilium.getNote(claimId).catch(() => note);
+      return txt4({
+        ok: true,
+        action: holds ? "verified" : "marked-broken",
+        ...row(refreshed),
+        ...holds ? {} : { hint: "This claim is now BROKEN. Correct every note that asserts it \u2014 consistency() will find the others \u2014 then re-verify. A broken claim left in the register is a known-wrong fact with a timestamp on it." }
+      });
+    }
+    if (assertion) {
+      if (!check2)
+        return err("missing_param", "A claim needs a check.", 'Pass check="<command, query, file path or URL that settles it>". A claim nobody can verify is just a sentence; the check is what makes it a claim.');
+      const { title } = normalizeTitle(assertion);
+      const existing = await trilium.searchNotes("#noteType=claim", { ancestorNoteId: container, fastSearch: true, limit: 200 }).then((r) => r.results.find((n) => sameTitle(n.title, title))).catch(() => {
+        return;
+      });
+      const body = `<h2>Check</h2>
+<p>${escapeHtml(check2)}</p>
+` + `<p><em>Inert by design \u2014 BrainLLM never runs this. Run it yourself, then record the outcome with claim(claimId, holds, evidence).</em></p>
+` + `<h2>Verifications</h2>
+`;
+      if (existing) {
+        const current = await trilium.getNoteContent(existing.noteId).catch(() => "");
+        await trilium.createRevision(existing.noteId).catch(() => null);
+        await trilium.updateNoteContent(existing.noteId, setSection(current, "Check", `<p>${escapeHtml(check2)}</p>`, "replace").html);
+        if (intervalDays)
+          await trilium.updateLabelValue(existing.noteId, "interval", String(intervalDays)).catch(() => null);
+        return txt4({ ok: true, action: "updated", ...row(existing), note: "A claim with this assertion already existed \u2014 its check was updated and its verification history kept." });
+      }
+      const created = await trilium.createNote(container, title, body);
+      const id = created.note.noteId;
+      await trilium.addLabel(id, "noteType", "claim");
+      await trilium.addLabel(id, "created", d);
+      await trilium.addLabel(id, "interval", String(intervalDays ?? 30));
+      await trilium.addLabel(id, "claimState", "unverified");
+      await trilium.addLabel(id, "iconClass", "bx bx-check-shield").catch(() => null);
+      if (noteId)
+        await trilium.addRelation(id, "derivedFrom", noteId).catch(() => null);
+      return txt4({
+        ok: true,
+        action: "registered",
+        claimId: id,
+        assertion: title,
+        intervalDays: intervalDays ?? 30,
+        location: "Insights \u2192 Claims",
+        next: `Run the check, then record the result: claim(claimId="${id}", holds=true|false, evidence="<what you observed>"). Until then it is unverified, not holding.`
+      });
+    }
+    const all = await trilium.searchNotes("#noteType=claim", { ancestorNoteId: container, fastSearch: true, limit: 200 }).then((r) => r.results).catch(() => []);
+    const rows = all.map(row).filter((r) => !status || status === "all" || r.state === status);
+    const broken = rows.filter((r) => r.state === "broken").length;
+    const stale = rows.filter((r) => r.state === "lapsed").length;
+    return txt4({
+      total: rows.length,
+      ...broken ? { broken } : {},
+      ...stale ? { needingReverification: stale } : {},
+      claims: rows.sort((a, b2) => a.lastVerified.localeCompare(b2.lastVerified)),
+      ...all.length === 0 ? { note: 'No claims registered. Register one with claim(assertion="\u2026", check="\u2026") \u2014 the assertions worth registering are the ones that would be expensive to discover had gone stale.' } : {}
+    });
+  });
+  server.tool("diff", `What changed in a note \u2014 the revision snapshot against the body as it stands now.
+
+Every content write takes a revision first, and until now nothing could read one back: verifying
+a run of surgical edits on a large note meant re-reading the whole thing, or trusting the
+receipts. Trusting receipts is exactly how a section= replace that silently displaced four
+subsections went unnoticed.
+
+Called with only a noteId, this diffs the MOST RECENT revision against current content \u2014 "what
+did my last write actually do". Pass revisionId to compare against a specific earlier one; the
+revisions list comes back on every call, newest first, so the usual flow is one call to see what
+exists and a second to pick.
+
+Reports changed lines with a little context, plus added/removed counts. Both sides are stored
+HTML, so a formatting-only change is a real difference and shows as one.`, {
+    noteId: exports_external.string().describe("Note to diff"),
+    revisionId: exports_external.string().optional().describe("Compare against this revision (default: the most recent one)"),
+    context: exports_external.number().int().min(0).max(10).optional().describe("Unchanged lines to show around each change (default: 1)")
+  }, async ({ noteId, revisionId, context }) => {
+    const revisions = await trilium.getNoteRevisions(noteId).catch(() => []);
+    if (!revisions.length)
+      return txt4({ noteId, note: "No revisions \u2014 this note has not been written through a content-mutating tool yet, or its revisions have been pruned.", revisions: [] });
+    const target = revisionId ? revisions.find((r) => r.revisionId === revisionId) : revisions[0];
+    if (!target)
+      return err("not_found", `Revision ${revisionId} does not belong to note ${noteId}.`, `Available: ${revisions.slice(0, 10).map((r) => r.revisionId).join(", ")}`);
+    const [before, after] = await Promise.all([
+      trilium.getRevisionContent(target.revisionId).catch(() => ""),
+      trilium.getNoteContent(noteId).catch(() => "")
+    ]);
+    const index = revisions.map((r) => ({
+      revisionId: r.revisionId,
+      dateCreated: r.dateCreated?.slice(0, 16),
+      size: r.contentLength,
+      ...r.revisionId === target.revisionId ? { compared: true } : {}
+    }));
+    if (before === after) {
+      return txt4({
+        noteId,
+        comparedTo: target.revisionId,
+        identical: true,
+        revisions: index,
+        note: "The snapshot and the current body are byte-identical \u2014 the write after this revision changed nothing, or the revision was taken after it."
+      });
+    }
+    const lines = (s) => s.replace(/></g, `>
+<`).split(`
+`);
+    const a = lines(before);
+    const bLines = lines(after);
+    let head = 0;
+    while (head < a.length && head < bLines.length && a[head] === bLines[head])
+      head++;
+    let tail = 0;
+    while (tail < a.length - head && tail < bLines.length - head && a[a.length - 1 - tail] === bLines[bLines.length - 1 - tail])
+      tail++;
+    const pad2 = context ?? 1;
+    const removed = a.slice(head, a.length - tail);
+    const added = bLines.slice(head, bLines.length - tail);
+    const cap = (arr) => arr.length > 40 ? [...arr.slice(0, 40), `\u2026 ${arr.length - 40} more line(s)`] : arr;
+    return txt4({
+      noteId,
+      comparedTo: target.revisionId,
+      revisionDate: target.dateCreated?.slice(0, 16),
+      identical: false,
+      sizeBefore: before.length,
+      sizeAfter: after.length,
+      contextBefore: cap(a.slice(Math.max(0, head - pad2), head)),
+      removed: cap(removed),
+      added: cap(added),
+      contextAfter: cap(a.slice(a.length - tail, a.length - tail + pad2)),
+      summary: `${removed.length} block(s) removed, ${added.length} added, ${after.length - before.length >= 0 ? "+" : ""}${after.length - before.length} characters.`,
+      revisions: index
+    });
+  });
   server.tool("attach", `Attach a raw artifact (file, image, code blob, document) to a note \u2014 or read one back.
 Dual-mode by the content param:
   content provided \u2192 UPSERT by title: creates the attachment, or replaces the existing
@@ -24684,18 +25464,27 @@ domain="<name>" narrows the deep passes to one domain's notes \u2014 the equival
 scoping addendum() already has, so a scoped agent's flags arrive in its own lane instead of it
 re-deriving each run that the cross-venture findings belong to someone else.
 
+repair=[noteId, \u2026] fixes an entity-corrupted body in place instead of reporting it: one level of
+double-escaping is unwound ("&amp;lt;" \u2192 "&lt;", "&amp;nbsp;" \u2192 "&nbsp;"), with a revision taken
+first. The substitution is always the same one, so it is a first-class action rather than
+something each caller reinvents with revise(mode="replace"). Compose with dryRun to see the
+outcome without writing. A note that DOCUMENTS the signature rather than carrying it comes back
+unchanged and is reported as such \u2014 ack= those.
+
 coverage names any pass that hit a cap, so a short list is never mistaken for a clean one.`, {
     deep: exports_external.boolean().optional().describe("Deep pass: stale-review + orphan/sink + structural lint + duplicate titles across Memory/Threads and Knowledge (default: false)"),
     dryRun: exports_external.boolean().optional().describe("Report what would change without changing it"),
     domain: exports_external.string().optional().describe("Narrow the deep passes to one domain's notes (slugged server-side) \u2014 for scoped agents working a single lane"),
-    ack: exports_external.array(exports_external.string()).optional().describe("Note ids to mark reviewed-and-correct \u2014 suppresses their findings until the note's content changes")
-  }, async ({ deep, dryRun, domain, ack }) => {
+    ack: exports_external.array(exports_external.string()).optional().describe("Note ids to mark reviewed-and-correct \u2014 suppresses their findings until the note's content changes"),
+    repair: exports_external.array(exports_external.string()).optional().describe("Note ids to auto-repair entity corruption on \u2014 unwinds one level of double-escaping, revision taken first")
+  }, async ({ deep, dryRun, domain, ack, repair }) => {
     await markStep("maintain");
     const report = await sweep(trilium, b(), {
       deep: deep ?? false,
       dryRun: dryRun ?? false,
       ...domain ? { domain } : {},
-      ...ack?.length ? { ack } : {}
+      ...ack?.length ? { ack } : {},
+      ...repair?.length ? { repair } : {}
     });
     return txt4(report);
   });
@@ -25056,6 +25845,7 @@ Structural containers are excluded; only content notes appear.`, {
         id: n.noteId,
         title: n.title,
         kind: labelOf2(n, "noteType"),
+        parent: n.parentNoteIds?.[0],
         status: labelOf2(n, "status") ?? undefined,
         created: labelOf2(n, "created") ?? n.dateCreated.slice(0, 10),
         modified: n.dateModified.slice(0, 10),
@@ -25103,6 +25893,128 @@ Structural containers are excluded; only content notes appear.`, {
     const total = masterAll.length + llmSingletons.length + llmDiary.length + sessions.length + threads.length + kMaster.length + kDomains.length + insights.length;
     return txt4({ total, areas });
   });
+  server.tool("assembly", `What the brain HOLDS \u2014 every note by title, grouped under the surface it lives in, with each
+surface's own purpose alongside it. The awareness read: "what do I already know here", answered
+in one call before deciding whether to look something up.
+
+Distinct from brain(), which is an inventory: brain() returns id, kind, status, parent, dates and
+relations for every note, and is what you want when auditing or locating one. assembly() answers
+a different question and is shaped for it:
+
+- **Dated collections collapse.** Sessions, diary entries and logs are titled [yyyy-mm-dd], so
+  listing them is a wall of dates carrying no information about content. They come back as a
+  count and a span instead. This is the difference between a listing and an awareness read \u2014 the
+  full titles are one brain() call away when you actually need them.
+- **Domains nest.** Each domain book appears with its own information and sources notes beneath
+  it, which is the real shape of what the brain knows rather than the flat list brain() returns.
+- **Threads group by status**, newest activity first \u2014 the working set is the actionable part.
+- **Purposes are read from the container notes themselves**, the text bootstrap engraved on them,
+  so this can never drift from what the brain actually says about itself.
+
+Pass area= to zoom into one surface and get its full detail.`, {
+    area: exports_external.enum(["master", "llm", "memory", "knowledge", "insights"]).optional().describe("Zoom into one surface instead of all five"),
+    includeArchived: exports_external.boolean().optional().describe("Include archived/resolved notes (default: false)")
+  }, async ({ area, includeArchived }) => {
+    const cfg = b();
+    if (!cfg.root)
+      return txt4({ status: "uninitialized", action: "Run bootstrap first." });
+    const fetchFrom = async (id) => {
+      if (!id)
+        return [];
+      return trilium.searchNotes("#noteType", {
+        ancestorNoteId: id,
+        fastSearch: true,
+        limit: 400,
+        includeArchivedNotes: includeArchived ?? false,
+        orderBy: "dateModified",
+        orderDirection: "desc"
+      }).then((r) => r.results).catch(() => []);
+    };
+    const purposeOf = async (id) => {
+      if (!id)
+        return;
+      const content = await trilium.getNoteContent(id).catch(() => "");
+      const text = toText(content, 400).trim();
+      return text || undefined;
+    };
+    const dateOf = (n) => labelOf2(n, "created") ?? n.dateCreated.slice(0, 10);
+    const span = (notes, label2) => {
+      if (!notes.length)
+        return { count: 0, note: `No ${label2} yet.` };
+      const dates = notes.map(dateOf).sort();
+      return {
+        count: notes.length,
+        earliest: dates[0],
+        latest: dates[dates.length - 1],
+        note: `${notes.length} ${label2}, ${dates[0]} \u2192 ${dates[dates.length - 1]}. Titles are all [yyyy-mm-dd] \u2014 read one with its surface tool, or brain() for the full list.`
+      };
+    };
+    const titles = (notes) => notes.map((n) => n.title);
+    const want = (a) => !area || area === a;
+    const out = {};
+    if (want("master")) {
+      const notes = await fetchFrom(cfg.master.root);
+      out.Master = { purpose: await purposeOf(cfg.master.root), singletons: titles(notes) };
+    }
+    if (want("llm")) {
+      const [all, diary] = await Promise.all([fetchFrom(cfg.llm.root), fetchFrom(cfg.llm.diary)]);
+      const diaryIds = new Set(diary.map((n) => n.noteId));
+      out.LLM = {
+        purpose: await purposeOf(cfg.llm.root),
+        singletons: titles(all.filter((n) => !diaryIds.has(n.noteId))),
+        diary: span(diary, "diary entries")
+      };
+    }
+    if (want("memory")) {
+      const [threads, sessions] = await Promise.all([fetchFrom(cfg.memory.threads), fetchFrom(cfg.memory.sessions)]);
+      const books = threads.filter((n) => labelOf2(n, "noteType") === "thread");
+      const byStatus = (s) => titles(books.filter((n) => (labelOf2(n, "status") ?? "active") === s));
+      out.Memory = {
+        purpose: await purposeOf(cfg.memory.root),
+        threads: {
+          active: byStatus("active"),
+          ...byStatus("dormant").length ? { dormant: byStatus("dormant") } : {},
+          ...byStatus("eternal").length ? { eternal: byStatus("eternal") } : {},
+          ...includeArchived && byStatus("resolved").length ? { resolved: byStatus("resolved") } : {}
+        },
+        sessions: span(sessions.filter((n) => labelOf2(n, "noteType") === "session"), "sessions")
+      };
+    }
+    if (want("knowledge")) {
+      const [master, domainNotes] = await Promise.all([fetchFrom(cfg.knowledge.master), fetchFrom(cfg.knowledge.domains)]);
+      const books = domainNotes.filter((n) => labelOf2(n, "noteType") === "domain");
+      const domains = books.map((book) => {
+        const children = domainNotes.filter((n) => n.noteId !== book.noteId && n.parentNoteIds?.includes(book.noteId));
+        return {
+          domain: book.title,
+          sources: children.some((c) => labelOf2(c, "noteType") === "sources"),
+          notes: titles(children.filter((c) => labelOf2(c, "noteType") === "information"))
+        };
+      });
+      const orphaned = domainNotes.filter((n) => labelOf2(n, "noteType") !== "domain" && !books.some((bk) => n.parentNoteIds?.includes(bk.noteId)));
+      out.Knowledge = {
+        purpose: await purposeOf(cfg.knowledge.root),
+        aboutTheUser: titles(master),
+        domains,
+        ...orphaned.length ? { unparented: titles(orphaned), hint: "These carry a knowledge kind but sit under no domain book \u2014 inspect() them for their real parent." } : {}
+      };
+    }
+    if (want("insights")) {
+      const [logs, all] = await Promise.all([fetchFrom(cfg.insights.logs), fetchFrom(cfg.insights.root)]);
+      const claims = all.filter((n) => labelOf2(n, "noteType") === "claim");
+      out.Insights = {
+        purpose: await purposeOf(cfg.insights.root),
+        logs: span(logs.filter((n) => labelOf2(n, "noteType") === "log"), "daily logs"),
+        claims: claims.length ? { count: claims.length, assertions: titles(claims), note: "Each claim's title IS its assertion. claim(claimId) reads one with its verification history." } : { count: 0, note: "No claims registered \u2014 nothing is currently being checked against the world." }
+      };
+    }
+    return txt4({
+      brain: await purposeOf(cfg.root),
+      ...area ? { scope: area } : {},
+      ...out,
+      ...includeArchived ? {} : { note: "Archived and resolved notes are excluded \u2014 pass includeArchived=true to see them." }
+    });
+  });
   server.tool("bootstrap", `Initialize the BrainLLM structure in Trilium (idempotent \u2014 safe to re-run; refreshes config
 if the structure already exists). Creates the five areas \u2014 Master (Biography/Goals/Preferences),
 LLM (Responsibilities/Protocols/Diary), Memory (Sessions/Threads), Knowledge (Master/Domains),
@@ -25116,9 +26028,24 @@ immediately, no restart needed.`, {}, async () => {
           return { id: child.noteId, title: child.title };
         }));
         const saved = saveConfig(brainRef.config);
+        const refreshed = [];
+        for (const [id, purpose] of containerPurposes(brainRef.config)) {
+          if (!id)
+            continue;
+          const current = await trilium.getNoteContent(id).catch(() => null);
+          if (current === null)
+            continue;
+          const wanted = purposeContent(purpose);
+          if (toText(current, 400).trim() === toText(wanted, 400).trim())
+            continue;
+          await trilium.updateNoteContent(id, wanted).catch(() => null);
+          const note = await trilium.getNote(id).catch(() => null);
+          refreshed.push(note?.title ?? id);
+        }
         return txt4({
           status: "already_initialized",
           message: `BrainLLM structure exists. Config refreshed at: ${saved}`,
+          ...refreshed.length ? { purposesRefreshed: refreshed, note: "These containers described themselves with text that no longer matched the canonical purpose, and have been re-engraved. Container notes are unreachable through revise(), so bootstrap is the only path that can correct them." } : {},
           root: { id: existing.noteId, title: existing.title },
           children
         });
@@ -25715,7 +26642,7 @@ function createServer(origin = null) {
   const s = new McpServer({
     name: "BrainLLM",
     title: "BrainLLM",
-    version: "10.2.0",
+    version: "10.4.0",
     icons: brandingIcons(origin)
   });
   registerTools(s, trilium, brainRef, mode);