token-goat 2.6.18 → 2.6.19

package/dist/token-goat.mjs

@@ -3050,7 +3050,7 @@ var require_commander = __commonJS({
 import { createRequire } from "node:module";
 function resolveVersion() {
   if (true) {
-    return "2.6.18";
+    return "2.6.19";
   }
   const require2 = createRequire(import.meta.url);
   const pkg = require2("../package.json");
@@ -4916,7 +4916,7 @@ function markerExists(current, marker) {
     }
     const resolved = fs3.realpathSync(markerPath);
     const rel = path4.relative(path4.resolve(current), path4.resolve(resolved));
-    return !rel.startsWith("..");
+    return !rel.startsWith("..") && !path4.isAbsolute(rel);
   } catch {
     return false;
   }
@@ -6220,6 +6220,33 @@ CREATE TABLE IF NOT EXISTS hint_suppression_probes (
   PRIMARY KEY (category, harness)
 );
 
+-- Free-text architecture/rationale notes (the "why" layer -- see notes.ts), attached either to
+-- a whole file (symbol = '') or to one specific indexed symbol within it (symbol = that
+-- symbol's name). '' rather than NULL for the whole-file case because SQLite's UNIQUE treats
+-- NULLs as pairwise-distinct (never conflicting with each other), which would let note-add
+-- accumulate unlimited duplicate whole-file notes for the same file instead of upserting one;
+-- '' is a real, comparable value so UNIQUE(file_path, symbol) enforces "at most one note per
+-- attachment point" for both cases identically. 'fingerprint' is a SHA-256 digest (see
+-- fingerprintContent in fingerprint.ts) captured at write time of exactly what the note
+-- describes -- the resolved symbol's current body text for a symbol-scoped note, or a stable
+-- digest of the file's current top-level symbol manifest (name:kind:line-range per symbol,
+-- sorted) for a file-scoped note -- so 'token-goat note-list --stale-only' can recompute the
+-- same fingerprint against the live index later and flag a mismatch (see notes.ts's
+-- isNoteStale). Staleness detection is purely advisory: nothing here ever auto-rewrites or
+-- deletes a note's content, only flags that the code it describes has moved since it was
+-- written -- a human/agent re-review decides what to do with a stale note.
+CREATE TABLE IF NOT EXISTS notes (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  file_path TEXT NOT NULL,
+  symbol TEXT NOT NULL DEFAULT '',
+  content TEXT NOT NULL,
+  fingerprint TEXT NOT NULL,
+  created_at REAL NOT NULL,
+  updated_at REAL NOT NULL,
+  UNIQUE(file_path, symbol)
+);
+CREATE INDEX IF NOT EXISTS idx_notes_file_folded ON notes(TG_LOWER(file_path));
+
 -- Baseline for skill_version_drift.ts's one-shot nudge: the token-goat CLI version (and its
 -- flat command-name set, JSON-encoded) active the moment the token-goat skill's body was
 -- last (re)loaded into this session -- see hooks_skill.ts's postSkillHandler. A session that
@@ -6285,7 +6312,7 @@ CREATE TRIGGER IF NOT EXISTS cache_recall_au AFTER UPDATE ON cache_recall BEGIN
   VALUES (new.row_id, new.label, new.content);
 END;
 `;
-    SCHEMA_VERSION = 7;
+    SCHEMA_VERSION = 8;
     MIGRATIONS = {
       // v1 -> v2: adds files.embed_sha, tracked separately from files.sha so embedding freshness can be gated independently of parse freshness (see makeIndexer in worker.ts). A pre-existing v1 database's `files` table predates the column, so it needs an explicit ALTER TABLE here; a brand-new database already has the column from SCHEMA_SQL's CREATE TABLE above, so the ALTER TABLE would fail with "duplicate column name" there -- swallow exactly that error and rethrow anything else, so a genuine ALTER TABLE failure is never silently lost.
       1: (conn) => alterTableIdempotent(conn, "ALTER TABLE files ADD COLUMN embed_sha TEXT"),
@@ -6778,6 +6805,17 @@ function slideShapes(parsedSlide) {
 function shapeText(shape) {
   return collectTextRuns(shape, "a:t").join(" ").trim();
 }
+function tableRowBlocks(parsedSlide) {
+  const blocks = [];
+  for (const tbl of collectElements(parsedSlide, "a:tbl")) {
+    for (const row of collectElements(tbl, "a:tr")) {
+      const cellTexts = collectElements(row, "a:tc").map((cell) => collectTextRuns(cell, "a:t").join(" ").trim());
+      const rowText = cellTexts.join(" | ").trim();
+      if (rowText.length > 0) blocks.push(rowText);
+    }
+  }
+  return blocks;
+}
 async function slidePathsInPresentationOrder(entries) {
   const presXml = decodeZipEntry(entries, "ppt/presentation.xml");
   const relsXml = decodeZipEntry(entries, "ppt/_rels/presentation.xml.rels");
@@ -6877,7 +6915,7 @@ async function pptxSlideText(filePath, slideNumber, includeNotes) {
   const path63 = slidePaths[slideNumber - 1];
   const parsed = await parseSlide(entries, path63);
   const shapes = slideShapes(parsed);
-  const blocks = shapes.map(shapeText).filter((t) => t.length > 0);
+  const blocks = [...shapes.map(shapeText).filter((t) => t.length > 0), ...tableRowBlocks(parsed)];
   const lines2 = [`# Slide ${slideNumber}`, ...blocks];
   if (includeNotes) {
     const notes = await notesTextFor(entries, await notesPathFor(entries, path63));
@@ -9621,7 +9659,7 @@ function _renderByDaySection(stats) {
   function share(d) {
     return _tokenOrByteShare(d.tokens, d.bytes, stats.totals.tokens, stats.totals.bytes);
   }
-  for (const d of [...stats.by_day].sort((a, b) => b.date.localeCompare(a.date))) {
+  for (const d of [...stats.by_day].sort((a, b) => b.date < a.date ? -1 : b.date > a.date ? 1 : 0)) {
     const s = share(d);
     lines2.push(
       _tableRow({
@@ -10231,6 +10269,7 @@ var init_stats = __esm({
       docx_text: SOURCE_READ,
       transcript_outline: SOURCE_READ,
       transcript: SOURCE_READ,
+      video_chapters: SOURCE_READ,
       coverage_report_gaps: SOURCE_READ,
       json_query: SOURCE_READ,
       json_outline: SOURCE_READ,
@@ -10248,6 +10287,14 @@ var init_stats = __esm({
       session_slice: SOURCE_READ,
       gdrive_sections: SOURCE_READ,
       pr_slice: SOURCE_READ,
+      note_read: SOURCE_READ,
+      note_list: SOURCE_READ,
+      // note-add is a write (like insert-section/replace, which record no stat at all -- neither
+      // has a "full source it replaces" savings concept). It still gets an event-only entry here
+      // (no bytesSaved/tokensSaved argument, same as skill_load) purely so `token-goat note-add`
+      // usage is visible in `token-goat stats --full` at all -- SOURCE_OTHER, not SOURCE_READ,
+      // since it is not a token-savings substitute for a read.
+      note_write: SOURCE_OTHER,
       web_fetch: SOURCE_WEB,
       injection_detected: SOURCE_WEB,
       skill_load: SOURCE_SKILL,
@@ -10292,6 +10339,7 @@ var init_stats = __esm({
       "docx-text": /* @__PURE__ */ new Set(["docx_text"]),
       "transcript-outline": /* @__PURE__ */ new Set(["transcript_outline"]),
       transcript: /* @__PURE__ */ new Set(["transcript"]),
+      "video-chapters": /* @__PURE__ */ new Set(["video_chapters"]),
       "coverage-report-gaps": /* @__PURE__ */ new Set(["coverage_report_gaps"]),
       "json-query": /* @__PURE__ */ new Set(["json_query"]),
       "json-outline": /* @__PURE__ */ new Set(["json_outline"]),
@@ -10309,6 +10357,9 @@ var init_stats = __esm({
       "session-slice": /* @__PURE__ */ new Set(["session_slice"]),
       "gdrive-sections": /* @__PURE__ */ new Set(["gdrive_sections"]),
       "pr-slice": /* @__PURE__ */ new Set(["pr_slice"]),
+      "note-add": /* @__PURE__ */ new Set(["note_write"]),
+      "note-get": /* @__PURE__ */ new Set(["note_read"]),
+      "note-list": /* @__PURE__ */ new Set(["note_list"]),
       npm: /* @__PURE__ */ new Set([
         "bash_compress:npm_install",
         "bash_compress:npm_ci",
@@ -14137,6 +14188,7 @@ function formatHeadingTree(headings, filePath) {
   const lines2 = [];
   lines2.push(`Large markdown file (${headings.length} headings). Use token-goat section to read a specific section:`);
   lines2.push(`  token-goat section "${filePath}::Heading Name"`);
+  lines2.push(`  Tip: an unambiguous heading prefix also resolves (e.g. "Lesson 16" instead of the full heading text) \u2014 shorter to type and avoids shell-quoting issues with punctuation in long headings.`);
   lines2.push(``);
   lines2.push(`Sections:`);
   let headingsAdded = 0;
@@ -15176,12 +15228,12 @@ function parseSectionOrdinal(heading) {
   const match2 = heading.match(/^(.*?)(?:#(\d+))?$/);
   if (!match2) return [heading, 1];
   const baseHeading = match2[1] || heading;
-  const ordinal = match2[2] ? Math.max(1, parseInt(match2[2], 10)) : 1;
-  return [baseHeading, ordinal];
+  const ordinal2 = match2[2] ? Math.max(1, parseInt(match2[2], 10)) : 1;
+  return [baseHeading, ordinal2];
 }
 function extractNamedSection(body, heading) {
   if (!body || !heading) return null;
-  const [baseHeading, ordinal] = parseSectionOrdinal(heading);
+  const [baseHeading, ordinal2] = parseSectionOrdinal(heading);
   const headingLower = stripLower(baseHeading);
   const lines2 = body.split("\n");
   let matchCount = 0;
@@ -15191,7 +15243,7 @@ function extractNamedSection(body, heading) {
       const headingText = stripLower(stripped.slice(3));
       if (headingText === headingLower) {
         matchCount++;
-        if (matchCount === ordinal) {
+        if (matchCount === ordinal2) {
           startIdx = i + 1;
           break;
         }
@@ -16265,6 +16317,11 @@ function isNodeModulesPath(p) {
   const check2 = foldPath(p);
   return check2.includes("/node_modules/") || check2.includes("\\node_modules\\");
 }
+function relPathWithinRoot(root, target) {
+  const rel = path21.relative(root, target).replace(/\\/g, "/");
+  if (rel.startsWith("..") || path21.isAbsolute(rel)) return null;
+  return rel;
+}
 function _isDocFile(filePath) {
   const lower = filePath.toLowerCase();
   return lower.endsWith(".md") || lower.endsWith(".mdx") || lower.endsWith(".markdown") || lower.endsWith(".rst");
@@ -16429,7 +16486,8 @@ function loadSnapshotDiff(sessionId, normalized, basename19) {
 }
 function scanCrossSessionManifests(projectRoot, projectHash2, filePath, ttlSecs) {
   try {
-    const relPath = path21.relative(projectRoot, filePath).replace(/\\/g, "/");
+    const relPath = relPathWithinRoot(projectRoot, filePath);
+    if (relPath === null) return false;
     const foldedRelPath = foldPath(relPath);
     const manifests = readAllSessionManifests(projectHash2, ttlSecs);
     for (const data of manifests) {
@@ -16473,7 +16531,7 @@ function isProtectedRecentRead(normalized, n) {
   if (n <= 0) return false;
   const ranked = Array.from(getSessionFiles().entries()).sort((a, b) => {
     const byRecency = b[1].lastReadAt - a[1].lastReadAt;
-    return byRecency !== 0 ? byRecency : a[0].localeCompare(b[0]);
+    return byRecency !== 0 ? byRecency : a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
   });
   const rank = ranked.findIndex(([filePath]) => filePath === normalized);
   return rank !== -1 && rank < n;
@@ -16717,8 +16775,7 @@ function preReadHandlerInner(event) {
       if (!project) {
         project = makeProjectAt(cwd);
       }
-      const relPath = path21.relative(project.root, normalized).replace(/\\/g, "/");
-      if (!relPath.startsWith("..")) {
+      if (relPathWithinRoot(project.root, normalized) !== null) {
         const ttlSecs = config2.hints.cross_session_read_dedup_ttl_secs;
         if (scanCrossSessionManifests(project.root, project.hash, normalized, ttlSecs)) {
           recordActualRead(event, normalized);
@@ -16855,7 +16912,7 @@ function estimateTruncatedLineCount(normalized) {
   return Infinity;
 }
 function editAnywayHint(normalized) {
-  return 'To edit it anyway, use `token-goat replace "' + normalized + '" --old-from <oldfile> --new-from <newfile>` for a snippet edit, or `token-goat write-file "' + normalized + "\" --from <newfile>` to rewrite the whole file \u2014 Read/Edit's own precondition can't be satisfied after this deny.";
+  return 'To edit it anyway, use `token-goat replace "' + normalized + '" --old-b64 <base64> --new-b64 <base64>` (preferred \u2014 no temp files needed) or `--old-from <oldfile> --new-from <newfile>` for a snippet edit, or `token-goat write-file "' + normalized + "\" --b64 <base64>` (or `--from <newfile>`) to rewrite the whole file \u2014 Read/Edit's own precondition can't be satisfied after this deny.";
 }
 function truncatedReadDenyMessage(normalized) {
   return 'File was truncated on last read (>33K tokens). Use `token-goat skeleton "' + normalized + '"` for structure or `token-goat read "' + normalized + '::SymbolName"` for one function. ' + editAnywayHint(normalized);
@@ -16890,8 +16947,8 @@ function postReadHandlerInner(event) {
       const sessionState = exportSessionState();
       const mappedFiles = [];
       for (const fileEntry of sessionState.files) {
-        const relPath = path21.relative(project.root, fileEntry.path).replace(/\\/g, "/");
-        if (!relPath.startsWith("..")) {
+        const relPath = relPathWithinRoot(project.root, fileEntry.path);
+        if (relPath !== null) {
           mappedFiles.push({
             rel_path: relPath,
             hit_count: fileEntry.readCount
@@ -18616,9 +18673,6 @@ function extractPhp(content, filePath) {
   let braceDepth = 0;
   let inComment = false;
   let mlState = null;
-  function currentClass() {
-    return contextStack.length > 0 ? contextStack[contextStack.length - 1]?.[0] ?? null : null;
-  }
   for (let i = 0; i < lines2.length; i++) {
     const rawLine = lines2[i] ?? "";
     const lineNum = i + 1;
@@ -18682,7 +18736,9 @@ function extractPhp(content, filePath) {
     if (clsM) {
       const kind = clsM[1] ?? "class";
       const name2 = clsM[2] ?? "";
-      const parent = currentClass();
+      const preLineDepth = braceDepth - openB + closeB;
+      const topFrame2 = contextStack.length > 0 ? contextStack[contextStack.length - 1] : void 0;
+      const parent = topFrame2 !== void 0 && preLineDepth === topFrame2[1] + 1 ? topFrame2[0] : null;
       symbols.push(makeLineSymbol(filePath, name2, kind, lineNum, stripped.slice(0, 200), parent ?? void 0));
       contextStack.push([name2, braceDepth - openB + closeB, false]);
       if (openB > 0 && openB === closeB) {
@@ -19280,6 +19336,9 @@ function extractScala(content, filePath) {
       const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
       symbols.push(makeLineSymbol(filePath, cname, "class", lineNum, stripped.slice(0, 200), parent));
       typeStack.push({ name: cname, startDepth: braceDepth, bodyEntered: false });
+      if (/\bcase\s+class\b/.test(stripped) && !stripStringLiterals(line).includes("{")) {
+        typeStack.pop();
+      }
       matched = true;
     }
     const om = !matched && typeDetectionGateOk && (!isIndented || typeStack.length > 0) ? OBJECT_RE.exec(stripped) : null;
@@ -19288,6 +19347,9 @@ function extractScala(content, filePath) {
       const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
       symbols.push(makeLineSymbol(filePath, oname, "object", lineNum, stripped.slice(0, 200), parent));
       typeStack.push({ name: oname, startDepth: braceDepth, bodyEntered: false });
+      if (/\bcase\s+object\b/.test(stripped) && !stripStringLiterals(line).includes("{")) {
+        typeStack.pop();
+      }
       matched = true;
     }
     const tm = !matched && typeDetectionGateOk && (!isIndented || typeStack.length > 0) ? TRAIT_RE.exec(stripped) : null;
@@ -19375,13 +19437,13 @@ var init_scala = __esm({
     init_common();
     IMPORT_RE3 = /^import\s+([A-Za-z_][A-Za-z0-9_.]*(?:\._)?)/;
     BRACE_IMPORT_RE = /^import\s+([A-Za-z_][A-Za-z0-9_.]*)\.\{([^}]*)\}/;
-    CLASS_RE3 = /^\s*(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)?\s*class\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s|\[|\(|:|$)/;
-    OBJECT_RE = /^\s*(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)?\s*object\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s|:|$)/;
-    TRAIT_RE = /^\s*(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)?\s*trait\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s|\[|:|$)/;
+    CLASS_RE3 = /^\s*(?:(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)\s+)*class\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s|\[|\(|:|$)/;
+    OBJECT_RE = /^\s*(?:(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)\s+)*object\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s|:|$)/;
+    TRAIT_RE = /^\s*(?:(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)\s+)*trait\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s|\[|:|$)/;
     ENUM_RE = /^\s*(?:private|protected)?\s*enum\s+([A-Za-z_][A-Za-z0-9_]*)(?:\s|\[|\(|:|$)/;
-    FUNC_RE2 = /^\s*(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)?\s*def\s+([A-Za-z_][A-Za-z0-9_]*|[+\-*/%=!<>&|^~]+)(?:\s*\[|\s*\(|\s*:)/;
-    VAL_RE = /^\s*(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)?\s*val\s+([A-Za-z_][A-Za-z0-9_]*)/;
-    VAR_RE = /^\s*(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)?\s*var\s+([A-Za-z_][A-Za-z0-9_]*)/;
+    FUNC_RE2 = /^\s*(?:(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)\s+)*def\s+([A-Za-z_][A-Za-z0-9_]*|[+\-*/%=!<>&|^~]+)(?:\s*\[|\s*\(|\s*:)/;
+    VAL_RE = /^\s*(?:(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)\s+)*val\s+([A-Za-z_][A-Za-z0-9_]*)/;
+    VAR_RE = /^\s*(?:(?:implicit|lazy|sealed|abstract|final|private|protected|override|covariant|contravariant|case)\s+)*var\s+([A-Za-z_][A-Za-z0-9_]*)/;
   }
 });
 
@@ -19471,8 +19533,9 @@ function extractLua(content, filePath) {
       funcStack.push({ name: "", endKeywordNeeded: true, isBlock: true });
       continue;
     }
-    if (stripped === "end" || /^end\s/.test(stripped) || /^end$/.test(stripped)) {
-      if (funcStack.length > 0) {
+    if (/^(?:end(?:\s+|$))+$/.test(stripped)) {
+      const popCount = (stripped.match(/\bend\b/g) ?? []).length;
+      for (let k = 0; k < popCount && funcStack.length > 0; k++) {
         funcStack.pop();
       }
     }
@@ -19515,6 +19578,7 @@ function extractElixir(content, filePath) {
       continue;
     }
     const opensDoBlock = /\bdo\s*$/.test(stripped);
+    const opensFnBlock = /\bfn\b/.test(stripped) && !/\bend\b/.test(stripped) && /(?:fn|->)\s*$/.test(stripped);
     const modM = MODULE_RE.exec(stripped);
     if (modM) {
       const modName = modM[1] ?? "";
@@ -19564,7 +19628,7 @@ function extractElixir(content, filePath) {
       }
       continue;
     }
-    if (opensDoBlock) {
+    if (opensDoBlock || opensFnBlock) {
       moduleStack.push({ name: "", endKeywordNeeded: true, isBlock: true });
       continue;
     }
@@ -19640,6 +19704,14 @@ function extractDart(content, filePath) {
         typeStack.push({ name: mname, startDepth: braceDepth, bodyEntered: false });
         matched = true;
       }
+      const etm = !matched ? EXTENSION_TYPE_RE.exec(stripped) : null;
+      if (etm) {
+        const etname = etm[1] ?? "";
+        const parent = typeStack.length > 0 ? typeStack[typeStack.length - 1].name : void 0;
+        symbols.push(makeLineSymbol(filePath, etname, "extension_type", lineNum, stripped.slice(0, 200), parent));
+        typeStack.push({ name: etname, startDepth: braceDepth, bodyEntered: false });
+        matched = true;
+      }
       const extm = !matched ? EXTENSION_RE.exec(stripped) : null;
       if (extm) {
         const extname14 = extm[1] ?? "extension";
@@ -19690,7 +19762,7 @@ function extractDart(content, filePath) {
   }
   return { symbols, imports };
 }
-var CLASS_RE4, ENUM_RE2, MIXIN_RE, EXTENSION_RE, FUNC_RE5;
+var CLASS_RE4, ENUM_RE2, MIXIN_RE, EXTENSION_RE, EXTENSION_TYPE_RE, FUNC_RE5;
 var init_dart = __esm({
   "src/languages/dart.ts"() {
     "use strict";
@@ -19700,6 +19772,7 @@ var init_dart = __esm({
     ENUM_RE2 = /^enum\s+([A-Za-z_][A-Za-z0-9_]*)/;
     MIXIN_RE = /^(?:base\s+)?mixin\s+([A-Za-z_][A-Za-z0-9_]*)/;
     EXTENSION_RE = /^extension\s+(?:([A-Za-z_][A-Za-z0-9_]*)\s+)?on\s+/;
+    EXTENSION_TYPE_RE = /^extension\s+type\s+([A-Za-z_][A-Za-z0-9_]*)/;
     FUNC_RE5 = /(?:^|\s)(?:static\s+)?(?:(?:void|Future|Stream|async|external)\s+|[A-Za-z_][A-Za-z0-9_<>]*(?:\s*\?)?\s+)([A-Za-z_][A-Za-z0-9_]*)\s*(?:<[^>]*>)?\s*\(/;
   }
 });
@@ -19726,33 +19799,39 @@ function extractZig(content, filePath) {
     }
     const isIndented = line[0] === " " || line[0] === "	";
     let matched = false;
-    if (!isIndented || scopeStack.length > 0) {
+    const outerFrame = scopeStack.length > 0 ? scopeStack[scopeStack.length - 1] : null;
+    const outerDepthInType = outerFrame !== null ? braceDepth - outerFrame.startDepth : 0;
+    const typeDetectionGateOk = scopeStack.length === 0 || outerDepthInType === 1;
+    if (typeDetectionGateOk && (!isIndented || scopeStack.length > 0)) {
       const sm = CONTAINER_RE.exec(stripped);
       if (sm) {
         const sname = sm[1] ?? "";
         const skind = sm[2] ?? "struct";
         if (sname) {
-          const parent = scopeStack.length > 0 ? scopeStack[scopeStack.length - 1].name : void 0;
+          const parent = outerFrame !== null ? outerFrame.name : void 0;
           symbols.push(makeLineSymbol(filePath, sname, skind, lineNum, stripped.slice(0, 200), parent));
           scopeStack.push({ name: sname, startDepth: braceDepth, bodyEntered: false });
           matched = true;
         }
       }
     }
-    if (!matched && !isIndented) {
+    const frame = scopeStack.length > 0 ? scopeStack[scopeStack.length - 1] : null;
+    if (!matched && !isIndented && frame === null) {
       const fm = FUNC_RE6.exec(stripped);
       if (fm) {
         const fname = fm[2] ?? "";
         symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200)));
         matched = true;
       }
-    } else if (!matched && scopeStack.length > 0) {
-      const fm = FUNC_RE6.exec(stripped);
-      if (fm) {
-        const fname = fm[2] ?? "";
-        const parent = scopeStack[scopeStack.length - 1].name;
-        symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), parent));
-        matched = true;
+    } else if (!matched && frame !== null) {
+      const depthInType = braceDepth - frame.startDepth;
+      if (depthInType === 1) {
+        const fm = FUNC_RE6.exec(stripped);
+        if (fm) {
+          const fname = fm[2] ?? "";
+          symbols.push(makeLineSymbol(filePath, fname, "function", lineNum, stripped.slice(0, 200), frame.name));
+          matched = true;
+        }
       }
     }
     if (!matched && !isIndented) {
@@ -19773,9 +19852,9 @@ function extractZig(content, filePath) {
       if (ch === "{") {
         braceDepth++;
         if (scopeStack.length > 0) {
-          const frame = scopeStack[scopeStack.length - 1];
-          if (braceDepth > frame.startDepth) {
-            frame.bodyEntered = true;
+          const frame2 = scopeStack[scopeStack.length - 1];
+          if (braceDepth > frame2.startDepth) {
+            frame2.bodyEntered = true;
           }
         }
       } else if (ch === "}") {
@@ -23190,7 +23269,18 @@ var init_parser = __esm({
       // `visit` already descends into `interface_body`/class bodies to find them.
       ["method_signature", "method"],
       ["property_signature", "var"],
-      ["abstract_method_signature", "method"]
+      ["abstract_method_signature", "method"],
+      // `namespace Foo { ... }` (and the legacy `module Foo { ... }` synonym) parses as
+      // `internal_module`; `declare module "some-string" { ... }` (an ambient module declaration,
+      // common in .d.ts files) parses as `module` -- a distinct node type from either. Neither had a
+      // kind-map entry, so the namespace/module declaration itself was silently invisible to
+      // `symbol`/`outline`/`skeleton`/`read`, even though everything nested inside it still indexed
+      // fine (the walk recurses into every node's children regardless of the parent's kind-map
+      // membership) -- the same container-drop shape already fixed for C++ `namespace_definition`
+      // and Rust `mod_item`. Both node types expose their name on the standard `name` field
+      // (an identifier, nested_identifier, or string), so `nodeName` resolves it without special-casing.
+      ["internal_module", "namespace"],
+      ["module", "namespace"]
     ]);
     TSJS_FN_SCOPE_TYPES = /* @__PURE__ */ new Set([
       "function_declaration",
@@ -24226,6 +24316,7 @@ function workerHealthCheckMarkerPath(dir) {
   return path33.join(dir, "worker-healthcheck.marker");
 }
 function ensureWorkerAlive(dir = dataDir()) {
+  if (process.env["TOKEN_GOAT_NO_WORKER_SPAWN"] === "1") return;
   const markerPath = workerHealthCheckMarkerPath(dir);
   try {
     const stat2 = fs27.statSync(markerPath);
@@ -24337,6 +24428,7 @@ async function runWorkerLoop(dir, pollIntervalMs, shouldStop = () => false) {
   let lastSnapshotCleanupMs = 0;
   let lastKnownRootsSweepMs = 0;
   while (!shouldStop()) {
+    if (!fs27.existsSync(dir)) break;
     try {
       drainOnce(dir);
     } catch {
@@ -24657,7 +24749,7 @@ function tableSectionEndIndex(headers, headerPos, totalLines) {
   }
   return totalLines;
 }
-function resolveHeaderPos(headers, base, ordinal) {
+function resolveHeaderPos(headers, base, ordinal2) {
   const target = base.toLowerCase();
   const normalizedTarget = normalizeHeading(base).toLowerCase();
   const strippedTarget = normalizeHeadingStrip(base).toLowerCase();
@@ -24678,12 +24770,12 @@ function resolveHeaderPos(headers, base, ordinal) {
   }
   const matches2 = exactMatches.length > 0 ? exactMatches : normalizedMatches.length > 0 ? normalizedMatches : strippedMatches;
   if (matches2.length > 0) {
-    const pick3 = ordinal === null ? 0 : ordinal - 1;
+    const pick3 = ordinal2 === null ? 0 : ordinal2 - 1;
     const headerPos = matches2[pick3];
     if (headerPos === void 0) return null;
     return { headerPos, redirectedFrom: null };
   }
-  if (ordinal !== null || normalizedTarget.length === 0) return null;
+  if (ordinal2 !== null || normalizedTarget.length === 0) return null;
   let prefixPos = -1;
   const distinct = /* @__PURE__ */ new Set();
   for (let i = 0; i < headers.length; i++) {
@@ -24719,10 +24811,10 @@ function buildSectionResult(headers, kind, lines2, headerPos, redirectedFrom) {
 }
 function resolveSectionFromText(text, headingSpec, language) {
   const { headers, kind } = findHeaders(text, language);
-  const { base, ordinal } = parseHeadingSpec(headingSpec, headers);
+  const { base, ordinal: ordinal2 } = parseHeadingSpec(headingSpec, headers);
   if (base.length === 0) return null;
   const lines2 = text.split("\n");
-  const resolved = resolveHeaderPos(headers, base, ordinal);
+  const resolved = resolveHeaderPos(headers, base, ordinal2);
   if (resolved === null) return null;
   return buildSectionResult(headers, kind, lines2, resolved.headerPos, resolved.redirectedFrom);
 }
@@ -25669,6 +25761,11 @@ var init_graph_commands = __esm({
       "opaque",
       "mixin",
       "extension",
+      // 'extension_type' (Dart 3.3's zero-cost wrapper type, `extension type Meters(int value)`) is
+      // a distinct declaration kind from a plain 'extension' -- languages/dart.ts's
+      // EXTENSION_TYPE_RE emits it via the same makeLineSymbol code path as 'class'/'mixin'/
+      // 'extension' above, so it needs the same TYPE_KINDS entry those already have.
+      "extension_type",
       "actor",
       // Protocol Buffers (languages/proto_idx.ts's KIND_MAP) uses its own kind strings rather
       // than the generic 'enum'/'interface' -- a proto message is a struct-shaped type, a proto
@@ -25710,7 +25807,26 @@ var init_graph_commands = __esm({
       // excluded from `token-goat types` in its entirety, the same class of gap already fixed for
       // Rust union, Swift protocol/actor, Zig opaque, Dart mixin/extension, proto message/enum/
       // service, Apex class/interface/enum, and GraphQL type/interface/input/enum/union.
-      "object"
+      "object",
+      // languages/sfc_idx.ts (Vue/Svelte/Astro single-file components) emits 'sfc_script_class' for
+      // a top-level class declaration in the component's script block, a distinct kind string rather
+      // than the generic 'class' -- so unlike a plain class it never reaches the looksLikeTypeClass
+      // fallback below either, which only ever queries kind === 'class' literally. Every SFC
+      // top-level class was indexed but silently excluded from `token-goat types` in its entirety,
+      // the same class of gap already fixed for Rust union, Swift protocol/actor, Zig opaque, Dart
+      // mixin/extension, proto message/enum/service, Apex class/interface/enum, GraphQL
+      // type/interface/input/enum/union, and Kotlin/Scala object.
+      "sfc_script_class",
+      // languages/graphql_idx.ts's TYPE_RE handler maps EVERY `extend type|interface|input|enum|
+      // union|scalar Foo { ... }` declaration to this one shared kind regardless of which keyword
+      // follows `extend` -- GraphQL's mechanism for adding fields to a type from another file/module,
+      // ubiquitous in federation and schema-stitching -- but unlike the six non-extend KIND_MAP
+      // entries already listed above, this kind was never added here, so every `extend` declaration
+      // was indexed but silently excluded from `token-goat types` in its entirety, the same class of
+      // gap already fixed for the other six GraphQL kinds, Rust union, Swift protocol/actor, Zig
+      // opaque, Dart mixin/extension, proto message/enum/service, Apex class/interface/enum, and
+      // Kotlin/Scala object.
+      "graphql_extend"
     ];
     MAX_CYCLES = 200;
   }
@@ -28153,7 +28269,8 @@ function extractOperations(spec) {
       });
     }
   }
-  operations.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+  const ordinal2 = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+  operations.sort((a, b) => ordinal2(a.path, b.path) || ordinal2(a.method, b.method));
   return operations;
 }
 function formatOpenApiOutline(operations) {
@@ -28241,7 +28358,7 @@ function listZipEntries(data) {
       return false;
     }
   });
-  entries.sort((a, b) => a.path.localeCompare(b.path));
+  entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
   return entries;
 }
 function formatZipList(entries) {
@@ -28724,7 +28841,11 @@ function hasGap(f) {
 }
 function rankAndFilter(files) {
   const withGaps = files.filter(hasGap);
-  withGaps.sort((a, b) => b.uncoveredLineCount - a.uncoveredLineCount || a.filePath.localeCompare(b.filePath));
+  withGaps.sort((a, b) => {
+    const byCount = b.uncoveredLineCount - a.uncoveredLineCount;
+    if (byCount !== 0) return byCount;
+    return a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0;
+  });
   return withGaps;
 }
 function detectCoverageFormat(text) {
@@ -29272,6 +29393,83 @@ var init_screenshot = __esm({
   }
 });
 
+// src/notes.ts
+function toNoteRow(row) {
+  return {
+    id: row.id,
+    filePath: row.file_path,
+    symbol: row.symbol,
+    content: row.content,
+    fingerprint: row.fingerprint,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function pickEarliest(matches2) {
+  return matches2.reduce((best, s) => s.lineStart < best.lineStart ? s : best);
+}
+function resolveSymbolMatch(filePath, symbolName, dbPath = globalDbPath()) {
+  const matches2 = querySymbols({ filePath, name: symbolName }, dbPath);
+  return matches2.length === 0 ? null : pickEarliest(matches2);
+}
+function symbolNamesInFile(filePath, dbPath = globalDbPath()) {
+  const symbols = querySymbols({ filePath, limit: 1e5 }, dbPath);
+  return [...new Set(symbols.map((s) => s.name))].sort();
+}
+function computeFileFingerprint(filePath, dbPath = globalDbPath()) {
+  const symbols = querySymbols({ filePath, limit: 1e6 }, dbPath);
+  const manifest = symbols.map((s) => `${s.name}:${s.kind}:${s.lineStart}-${s.lineEnd}`).sort().join("\n");
+  return fingerprintContent(manifest);
+}
+function computeSymbolFingerprint(filePath, symbolName, dbPath = globalDbPath()) {
+  const match2 = resolveSymbolMatch(filePath, symbolName, dbPath);
+  return match2 === null ? null : fingerprintContent(match2.body);
+}
+function upsertNote(filePath, symbol3, content, fingerprint, dbPath = globalDbPath()) {
+  const db = getDb(dbPath);
+  const now = Date.now() / 1e3;
+  db.prepare(
+    `INSERT INTO notes (file_path, symbol, content, fingerprint, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(file_path, symbol) DO UPDATE SET
+       content = excluded.content,
+       fingerprint = excluded.fingerprint,
+       updated_at = excluded.updated_at`
+  ).run(filePath, symbol3, content, fingerprint, now, now);
+}
+function getNote(filePath, symbol3, dbPath = globalDbPath()) {
+  const db = getDb(dbPath);
+  const row = db.prepare(
+    `SELECT id, file_path, symbol, content, fingerprint, created_at, updated_at FROM notes WHERE ${pathEqClause("file_path")} AND symbol = ?`
+  ).get(foldPath(filePath), symbol3);
+  return row === void 0 ? null : toNoteRow(row);
+}
+function listNotes(dbPath = globalDbPath()) {
+  const db = getDb(dbPath);
+  const rows = db.prepare(
+    "SELECT id, file_path, symbol, content, fingerprint, created_at, updated_at FROM notes ORDER BY file_path, symbol"
+  ).all();
+  return rows.map(toNoteRow);
+}
+function isNoteStale(note, dbPath = globalDbPath()) {
+  const current = note.symbol === WHOLE_FILE_NOTE_SYMBOL ? computeFileFingerprint(note.filePath, dbPath) : computeSymbolFingerprint(note.filePath, note.symbol, dbPath);
+  return current === null || current !== note.fingerprint;
+}
+var WHOLE_FILE_NOTE_SYMBOL;
+var init_notes = __esm({
+  "src/notes.ts"() {
+    "use strict";
+    init_define_import_meta_env();
+    init_constants();
+    init_db();
+    init_fingerprint();
+    init_index_reader();
+    init_sql_path();
+    init_util2();
+    WHOLE_FILE_NOTE_SYMBOL = "";
+  }
+});
+
 // src/ts_refs.ts
 import { createRequire as createRequire6 } from "node:module";
 import * as path45 from "node:path";
@@ -29824,6 +30022,9 @@ function runSection(opts) {
   const heading = opts.spec.slice(colonIdx + 2);
   const result = readSection(filePath, heading);
   if (result === null) {
+    if (!fs36.existsSync(filePath)) {
+      return { text: `File not found: '${filePath}'`, code: 1 };
+    }
     const messages = [`Section '${heading}' not found in '${filePath}'`];
     const available = listSections(filePath);
     if (available.length > 0) messages.push(didYouMean(available));
@@ -29968,7 +30169,7 @@ function runRefsSingle(opts) {
 function groupRefsByFile(refs) {
   const byFile = /* @__PURE__ */ new Map();
   for (const ref2 of refs) byFile.set(ref2.filePath, (byFile.get(ref2.filePath) ?? 0) + 1);
-  return [...byFile.entries()].map(([file2, count]) => ({ file: file2, count })).sort((a, b) => b.count - a.count || a.file.localeCompare(b.file));
+  return [...byFile.entries()].map(([file2, count]) => ({ file: file2, count })).sort((a, b) => b.count - a.count || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
 }
 function renderTopFilesSummary(refs, topN) {
   const grouped = groupRefsByFile(refs);
@@ -31478,6 +31679,11 @@ function extractImports(text, ext2) {
       const m = /^\s*#\s*include\s+[<"]([^>"]+)[>"]/.exec(line);
       if (m) push(m[1]);
     }
+  } else if ([".sh", ".bash"].includes(e)) {
+    for (const line of lines2) {
+      const m = /^\s*(?:source|\.)\s+['"]?([^\s'";]+)['"]?/.exec(line);
+      if (m) push(m[1]);
+    }
   } else if ([".ps1", ".psm1"].includes(e)) {
     for (const line of lines2) {
       const importMod = /^\s*Import-Module\s+(?:-Name\s+)?['"]?([^\s'";]+)/i.exec(line);
@@ -31718,6 +31924,59 @@ ${previewLines(s.body, 3)}`);
   recordReadStat("semantic_search", sumFileSizes(results.map((s) => s.filePath)), text, query);
   return { text, code: 0 };
 }
+function runNoteGet(opts) {
+  const resolvedPath = resolveIndexPath(opts.file, opts.projectRoot ?? process.cwd());
+  healStaleIndex(resolvedPath);
+  const symbol3 = opts.symbol ?? WHOLE_FILE_NOTE_SYMBOL;
+  const note = getNote(resolvedPath, symbol3);
+  if (note === null) {
+    const where = opts.symbol !== void 0 ? ` for symbol '${opts.symbol}'` : " (whole-file note)";
+    return { text: `No note found for '${opts.file}'${where}`, code: 1 };
+  }
+  const stale = isNoteStale(note);
+  if (opts.json === true) {
+    const payload = {
+      filePath: note.filePath,
+      symbol: note.symbol === WHOLE_FILE_NOTE_SYMBOL ? null : note.symbol,
+      content: note.content,
+      stale,
+      createdAt: note.createdAt,
+      updatedAt: note.updatedAt
+    };
+    const text2 = JSON.stringify(payload, null, 2);
+    recordStat("note_read");
+    return { text: text2, code: 0 };
+  }
+  const target = note.symbol === WHOLE_FILE_NOTE_SYMBOL ? opts.file : `${opts.file}::${note.symbol}`;
+  const staleTag = stale ? " [STALE \u2014 code changed since this note was written]" : "";
+  const text = `# note \u2014 ${target}${staleTag}
+${note.content}`;
+  recordStat("note_read");
+  return { text, code: 0 };
+}
+function runNoteList(opts = {}) {
+  const withStale = listNotes().map((note) => ({ note, stale: isNoteStale(note) }));
+  const filtered = opts.staleOnly === true ? withStale.filter((n) => n.stale) : withStale;
+  if (opts.json === true) {
+    const items = filtered.map(({ note, stale }) => ({
+      filePath: note.filePath,
+      symbol: note.symbol === WHOLE_FILE_NOTE_SYMBOL ? null : note.symbol,
+      stale,
+      updatedAt: note.updatedAt
+    }));
+    recordStat("note_list");
+    return { text: JSON.stringify(items, null, 2), code: 0 };
+  }
+  recordStat("note_list");
+  if (filtered.length === 0) {
+    return { text: opts.staleOnly === true ? "No stale notes." : "No notes recorded.", code: 0 };
+  }
+  const lines2 = filtered.map(({ note, stale }) => {
+    const target = note.symbol === WHOLE_FILE_NOTE_SYMBOL ? note.filePath : `${note.filePath}::${note.symbol}`;
+    return `${stale ? "[STALE] " : ""}${target}`;
+  });
+  return { text: lines2.join("\n"), code: 0 };
+}
 var DIDYOUMEAN_LIMIT, GREP_MAX_LINES, FIND_SCAN_LIMIT, REFS_TOP_SCAN_LIMIT, STALE_WARNING, PARENT_IDENTIFIER_RE, SKELETON_SYMBOL_CAP, HUNK_HEADER_RE, DEFAULT_LOG_MAX_COUNT;
 var init_read_commands = __esm({
   "src/read_commands.ts"() {
@@ -31752,6 +32011,7 @@ var init_read_commands = __esm({
     init_pdf_extract();
     init_screenshot();
     init_stats();
+    init_notes();
     init_ts_refs();
     DIDYOUMEAN_LIMIT = 5;
     GREP_MAX_LINES = 200;
@@ -48167,9 +48427,10 @@ async function storeBashOutput(command, output, exitCode, cwd = null) {
   const id = await commandHash(command, cwd);
   const fingerprints = computeBashFingerprints(command, cwd);
   const redactedOutput = redactSecrets(output).text;
+  const redactedCommand = redactSecrets(command).text;
   const entry = {
     id,
-    command,
+    command: redactedCommand,
     output: redactedOutput,
     exitCode,
     storedAt: Date.now(),
@@ -48178,7 +48439,7 @@ async function storeBashOutput(command, output, exitCode, cwd = null) {
   };
   _byId.set(id, entry);
   storeBlob(BASH_OUTPUT_SUBDIR, id, entry);
-  indexRecallEntry("bash", id, command, `${command}
+  indexRecallEntry("bash", id, redactedCommand, `${redactedCommand}
 ${redactedOutput}`, entry.storedAt);
   return id;
 }
@@ -48608,7 +48869,8 @@ function storeWebOutput(url2, content, dedupKey = url2) {
   _byId2.set(cacheId, redactedContent);
   _urlIndex.set(url2, cacheId);
   storeBlob(WEB_OUTPUT_SUBDIR, cacheId, { url: url2, content: redactedContent });
-  indexRecallEntry("web", cacheId, url2, `${url2}
+  const redactedUrl = redactSecrets(url2).text;
+  indexRecallEntry("web", cacheId, redactedUrl, `${redactedUrl}
 ${redactedContent}`, Date.now());
   return cacheId;
 }
@@ -54653,7 +54915,7 @@ function preFetchHandler(event) {
     if (cached2 !== null) {
       const cachedBytes = Buffer.byteLength(cached2, "utf-8");
       if (cachedBytes >= loadConfig().hints.web_dedup_min_bytes) {
-        recordStat("webfetch:recall", cachedBytes, Math.round(cached2.length / 4));
+        recordStat("webfetch:recall", cachedBytes, Math.round(cachedBytes / 4));
         return denyOutput(
           "Already fetched this URL with this prompt; the response is cached. Use `token-goat web-output " + cacheId + "` to recall it (append `--grep PATTERN` to filter or `--section Heading` for a markdown section) instead of re-fetching."
         );
@@ -55172,8 +55434,17 @@ function pathStem(p) {
   const dot = name2.lastIndexOf(".");
   return dot > 0 ? name2.slice(0, dot) : name2;
 }
-function positionalArgs(args) {
-  return args.filter((a) => !a.startsWith("-"));
+function positionalArgs(args, valueFlags) {
+  const out2 = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith("-")) {
+      if (valueFlags?.has(a) === true && i + 1 < args.length) i++;
+      continue;
+    }
+    out2.push(a);
+  }
+  return out2;
 }
 var SHORT_FLAGS_WITH_VALUE = /* @__PURE__ */ new Set(["-n", "-c", "-u", "-e"]);
 function stripPrefixes(argv) {
@@ -55311,6 +55582,7 @@ function byteLength(s) {
 
 // src/tool_filters/base.ts
 init_define_import_meta_env();
+init_secret_redact();
 var CompressedOutput = class {
   constructor(text, originalBytes, compressedBytes, filterName, exitCode = 0, notes = []) {
     this.text = text;
@@ -55480,6 +55752,9 @@ ${stderr.replace(/\s+$/, "")}`;
     const lines2 = body.split("\n");
     if (lines2.length > maxLines) body = truncateMiddleSmart(lines2, maxLines).join("\n");
     body = capBytes(body, maxBytes);
+    const redacted = redactSecrets(body);
+    body = redacted.text;
+    if (redacted.count > 0) notes.push(`redacted ${redacted.count} secret-shaped value(s)`);
     if (notes.length) body = `[${notes.join("; ")}]
 ${body}`;
     return new CompressedOutput(body, originalBytes, byteLength(body), this.name, exitCode, notes);
@@ -58730,7 +59005,9 @@ var _GIT_VALUE_FLAGS = /* @__PURE__ */ new Set([
   "-F",
   "--file",
   "--author",
-  "--date"
+  "--date",
+  "--git-dir",
+  "--work-tree"
 ]);
 function gitPositionalArgs(args) {
   const out2 = [];
@@ -61258,6 +61535,7 @@ var _DOCKER_OLD_SHA_RE = /^ *---> (?:sha256:)?[0-9a-f]{12,}\s*$/;
 var _DOCKER_OLD_STEP_RE = /^Step \d+\/\d+ : /;
 var _DOCKER_OLD_SUCCESS_RE = /^Successfully built [0-9a-f]+/;
 var _DOCKER_OLD_INTERMEDIATE_RE = /^Removing intermediate container [0-9a-f]+/;
+var _DOCKER_OLD_STEP_ERROR_RE = /error|returned a non-zero code/i;
 var DockerFilter = class extends ToolFilter {
   name = "docker";
   binaries = /* @__PURE__ */ new Set(["docker", "buildah", "podman", "nerdctl"]);
@@ -61338,7 +61616,7 @@ var DockerFilter = class extends ToolFilter {
           oldStepErr = false;
           continue;
         }
-        if (ol.toLowerCase().includes("error")) oldStepErr = true;
+        if (_DOCKER_OLD_STEP_ERROR_RE.test(ol)) oldStepErr = true;
         oldNew.push(ol);
       }
       if (oldStepHdr !== null) {
@@ -61575,12 +61853,26 @@ function _compressKubectlDescribe(text) {
   }
   return kept.join("\n");
 }
+var KUBECTL_GLOBAL_VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "-n",
+  "--namespace",
+  "--context",
+  "--kubeconfig",
+  "--cluster",
+  "--user",
+  "-s",
+  "--server",
+  "--token",
+  "--as",
+  "--as-group",
+  "--request-timeout"
+]);
 var KubectlFilter = class extends ToolFilter {
   name = "kubectl";
   binaries = /* @__PURE__ */ new Set(["kubectl", "k", "k9s", "oc"]);
   errorPassthrough = true;
   compressBody(stdout, stderr, _exitCode, argv) {
-    const pos = positionalArgs(argv.slice(1));
+    const pos = positionalArgs(argv.slice(1), KUBECTL_GLOBAL_VALUE_FLAGS);
     const subcommand = pos[0] ?? "";
     let text = stdout;
     if (subcommand === "get" || subcommand === "top") {
@@ -61762,7 +62054,7 @@ var KubectlLogsFilter = class extends ToolFilter {
     const stem = pathStem(argv[0]).toLowerCase();
     const name2 = pathName(argv[0]).toLowerCase();
     if (!["kubectl", "k"].includes(stem) && !["kubectl", "k"].includes(name2)) return false;
-    const pos = positionalArgs(argv.slice(1));
+    const pos = positionalArgs(argv.slice(1), KUBECTL_GLOBAL_VALUE_FLAGS);
     return pos.length > 0 && pos[0] === "logs";
   }
   compressBody(stdout, stderr, _exitCode, _argv) {
@@ -62208,6 +62500,19 @@ var awsFilter = new AwsFilter();
 var _AWS_UPLOAD_RE = /^upload:\s+\S+\s+to\s+s3:\/\//i;
 var _AWS_DOWNLOAD_RE = /^download:\s+s3:\/\//i;
 var _AWS_S3_PROGRESS_RE = /^(?:Completed\s+\d|\d+(?:\.\d+)?\s*(?:KiB|MiB|GiB|B)\/s|Calculating|upload\s+failed:|download\s+failed:)/i;
+var AWS_GLOBAL_VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--profile",
+  "--region",
+  "--endpoint-url",
+  "--output",
+  "--query",
+  "--color",
+  "--ca-bundle",
+  "--cli-read-timeout",
+  "--cli-connect-timeout",
+  "--cli-binary-format",
+  "--cli-pager"
+]);
 var AwsCliFilter = class extends ToolFilter {
   name = "aws-cli";
   binaries = /* @__PURE__ */ new Set(["aws", "aws2"]);
@@ -62215,7 +62520,7 @@ var AwsCliFilter = class extends ToolFilter {
   _JSON_ARRAY_THRESHOLD = 10;
   _JSON_ARRAY_KEEP = 3;
   compressBody(stdout, stderr, _exitCode, argv) {
-    const positionals = positionalArgs(argv.slice(1));
+    const positionals = positionalArgs(argv.slice(1), AWS_GLOBAL_VALUE_FLAGS);
     const isS3Transfer = positionals.length >= 2 && positionals[0] === "s3" && (positionals[1] === "cp" || positionals[1] === "sync" || positionals[1] === "mv");
     const isCfnEvents = positionals.length >= 2 && positionals[0] === "cloudformation" && positionals[1] === "describe-stack-events";
     let text = stdout;
@@ -63606,6 +63911,7 @@ var _GH_RUN_PASS_STEP_RE = /^\s*[✓√]\s/;
 var _GH_RUN_FAIL_STEP_RE = /^\s*[X✗❌]\s|^\s*FAIL(:|ED|URE)\b|^\s*Error:\s/;
 var _GH_API_URL_SUFFIX = "_url";
 var _GH_API_URL_KEEP = /* @__PURE__ */ new Set(["html_url", "avatar_url", "clone_url", "ssh_url"]);
+var GH_GLOBAL_VALUE_FLAGS = /* @__PURE__ */ new Set(["-R", "--repo", "--hostname"]);
 var _GH_API_NOISE_KEYS = /* @__PURE__ */ new Set(["gravatar_id", "site_admin"]);
 var _GH_CONTENT_B64_RE = /^[A-Za-z0-9+/=\n]+$/;
 var _GH_BASE64_MIN_LEN = 200;
@@ -63890,7 +64196,7 @@ var GhFilter = class extends ToolFilter {
   binaries = /* @__PURE__ */ new Set(["gh"]);
   compress(stdout, stderr, _exitCode, argv) {
     const redactedStdout = redactGhBase64Content(stdout);
-    const positionals = positionalArgs(argv.slice(1));
+    const positionals = positionalArgs(argv.slice(1), GH_GLOBAL_VALUE_FLAGS);
     const subcommand = positionals[0] ?? "";
     const action = positionals[1] ?? "";
     const merged = this.combineOutput(redactedStdout, stderr);
@@ -64695,9 +65001,38 @@ var LsFilter = class _LsFilter extends ToolFilter {
 var _EZA_PASSTHROUGH = 30;
 var _HEADER_KEYWORDS = /* @__PURE__ */ new Set(["permission", "size", "date", "user", "name"]);
 var _SUMMARY_KEYWORDS = ["director", "file", "total"];
-var EzaFilter = class extends ToolFilter {
+var EzaFilter = class _EzaFilter extends ToolFilter {
   name = "eza";
   binaries = /* @__PURE__ */ new Set(["eza", "exa", "ls"]);
+  // Flags eza/exa support that plain GNU/BSD `ls` does not -- used to disambiguate the shared
+  // 'ls' binary claim below (a common `alias ls=eza` setup means the literal command text is
+  // "ls ...", but token-goat only ever sees that raw text, never the shell's alias resolution).
+  static _EZA_ONLY_FLAGS = /* @__PURE__ */ new Set([
+    "--tree",
+    "-T",
+    "--icons",
+    "--no-icons",
+    "--git",
+    "--git-repos",
+    "--git-repos-no-status",
+    "--level"
+  ]);
+  // LsFilter (registered before EzaFilter in SHELL_FILE_FILTERS) always wins a plain `ls`
+  // invocation since binary-name matching alone can't tell a real GNU/BSD `ls` from an
+  // `alias ls=eza` shell alias -- the literal command text is "ls ..." either way. Without this
+  // gate, EzaFilter's own 'ls' binary claim was permanently unreachable dead code: LsFilter's
+  // generic ls-format compressor (no awareness of eza's tree/column output) silently ran on
+  // every aliased `ls --tree`/`ls --icons`/etc. invocation instead. Mirrors RgFilter's own
+  // `_hasContextFlags` gate, which resolves the same kind of shared-binary ambiguity between
+  // itself and GrepFilter.
+  matches(argv) {
+    if (!super.matches(argv)) return false;
+    const first2 = argv[0];
+    const stem = pathStem(first2).toLowerCase();
+    const name2 = pathName(first2).toLowerCase();
+    if (stem !== "ls" && name2 !== "ls") return true;
+    return argv.slice(1).some((a) => _EzaFilter._EZA_ONLY_FLAGS.has(a));
+  }
   compressBody(stdout, stderr, _exitCode, argv) {
     const merged = this.combineOutput(stdout, stderr);
     const text = normalise(merged);
@@ -65455,9 +65790,11 @@ var SHELL_FILE_FILTERS = [
   ffmpegFilter,
   // Diff tool (plain POSIX diff; git diff is handled by GitFilter)
   diffFilter,
-  // Directory listings — LsFilter (simple) before EzaFilter (richer tree/column-aware)
-  lsFilter,
+  // Directory listings — EzaFilter before LsFilter: EzaFilter's matches() gate falls through to
+  // LsFilter for a plain `ls` with no eza-only flag, but must run FIRST so it can actually claim
+  // an aliased `ls --tree`/`ls --icons`/etc. invocation (see EzaFilter.matches doc comment).
   ezaFilter,
+  lsFilter,
   fdFilter,
   wcFilter,
   treeFilter,
@@ -65967,7 +66304,7 @@ var flutterFilter = new FlutterFilter();
 var DART_ANALYZING_RE = /^Analyzing\s/;
 var DART_ANALYZE_RESULT_RE = /^(?:No issues found!|\d+ issue[s]? found\.|warning -|error -|info -|hint -)/;
 var DART_TEST_PROGRESS_RE = /^\d{2}:\d{2}\s+[+\d]|^[.]+$/;
-var DART_COMPILE_DONE_RE = /^(?:Generated:\s|Compiling\s)/;
+var DART_COMPILE_DONE_RE = /^Generated:\s/;
 var DART_TEST_SUMMARY_RE = /(?:All tests passed\.?|\d+\s+test[s]?\s+(?:passed|failed))/;
 var PUB_KEEP_RE2 = /^(?:Resolving dependencies|Changed \d+|No dependencies changed|Got dependencies|Downloading packages|Building package executable)/;
 var PUB_PKG_LINE_RE2 = /^[+>!]\s+\S+\s+\S+/;
@@ -69710,8 +70047,9 @@ function storeMcpOutput(sessionId, toolName, toolInput, resultText) {
   const rawSizeBytes = Buffer.byteLength(resultText, "utf-8");
   if (rawSizeBytes > MCP_MAX_CACHE_BYTES) return null;
   const id = mcpOutputId(sessionId, mcpHash(toolName, toolInput));
-  const label = `mcp:${toolName} ${mcpInputPreview(toolInput)}`.trim();
+  const rawLabel = `mcp:${toolName} ${mcpInputPreview(toolInput)}`.trim();
   const redactedOutput = redactSecrets(resultText).text;
+  const label = redactSecrets(rawLabel).text;
   const entry = {
     id,
     command: label,
@@ -69980,6 +70318,7 @@ function compressMcpResultWithPacks(toolName, resultText) {
 }
 
 // src/hooks_mcp.ts
+init_secret_redact();
 function isMcpErrorResponse(raw) {
   const tr = raw["tool_response"];
   if (!tr || typeof tr !== "object") return false;
@@ -70019,7 +70358,7 @@ function postMcpHandler(event) {
         return {
           hookType: "rewriteOutput",
           updatedOutput: `[token-goat: compressed, full via mcp-output ${id}]
-${compressed}`
+${redactSecrets(compressed).text}`
         };
       }
     }
@@ -71753,6 +72092,7 @@ function recordSavings(result) {
 
 // src/cli.ts
 init_read_commands();
+init_notes();
 
 // src/bridges_status.ts
 init_define_import_meta_env();
@@ -72168,6 +72508,7 @@ function formatCues(cues) {
 init_graph_commands();
 init_skill_cache();
 init_hooks_read();
+init_section_reader();
 init_util2();
 init_ansi();
 init_config();
@@ -75515,6 +75856,9 @@ import * as fs43 from "node:fs";
 import * as path53 from "node:path";
 var MAX_ENTRIES = 30;
 var KEY_RE2 = /^[A-Za-z0-9_-]{1,80}$/;
+function ordinal(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
 function memoryPath(projectHash2) {
   return path53.join(dataDir(), "projects", `${projectHash2}_memory.toml`);
 }
@@ -75569,7 +75913,7 @@ function loadRaw(filePath) {
 }
 function save(filePath, entries) {
   const lines2 = [];
-  const sorted = Object.entries(entries).sort(([a], [b]) => a.localeCompare(b));
+  const sorted = Object.entries(entries).sort(([a], [b]) => ordinal(a, b));
   for (const [k, v] of sorted) {
     const escaped = v.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\r/g, "\\r").replace(/\n/g, "\\n");
     lines2.push(`${k} = "${escaped}"`);
@@ -75592,7 +75936,7 @@ function setEntry(projectHash2, key, value) {
     const isNewKey = !(key in entries);
     if (isNewKey && Object.keys(entries).length >= MAX_ENTRIES) {
       const keysToKeep = MAX_ENTRIES - 1;
-      const allKeys = Object.keys(entries).sort((a, b) => a.localeCompare(b));
+      const allKeys = Object.keys(entries).sort((a, b) => ordinal(a, b));
       for (const k of allKeys.slice(keysToKeep)) {
         delete entries[k];
       }
@@ -76237,7 +76581,7 @@ function parseRequirementsTxt(content) {
   const deps = [];
   for (const raw of splitLines2(content)) {
     if (/^\s*#/.test(raw)) continue;
-    const eggMatch = /^\s*(?:git|hg|svn|bzr)\+.*#egg=([A-Za-z0-9_.-]+)/.exec(raw);
+    const eggMatch = /^\s*(?:-e\s+|--editable[\s=]+)?(?:git|hg|svn|bzr)\+.*#egg=([A-Za-z0-9_.-]+)/.exec(raw);
     if (eggMatch !== null) {
       deps.push({ name: eggMatch[1] ?? "", version: "", kind: "unknown" });
       continue;
@@ -76805,8 +77149,11 @@ function resolveTypesLocation(pkgDir, pkgJson, nodeModulesDir, pkgName) {
     try {
       const typesPkgJson = JSON.parse(typesPkgJsonRaw);
       const entry = (typeof typesPkgJson["types"] === "string" ? typesPkgJson["types"] : void 0) ?? (typeof typesPkgJson["main"] === "string" ? typesPkgJson["main"] : void 0) ?? "index.d.ts";
-      const entryPath = path55.join(typesPkgDir, entry.endsWith(".d.ts") ? entry : `${entry}.d.ts`);
-      if (fileExists2(entryPath)) return { path: entryPath, source: "@types" };
+      const entryCandidates = [entry, entry.endsWith(".d.ts") ? entry : `${entry}.d.ts`, entry.replace(/\.[cm]?[jt]s$/, ".d.ts")];
+      for (const c of entryCandidates) {
+        const entryPath = path55.join(typesPkgDir, c);
+        if (fileExists2(entryPath)) return { path: entryPath, source: "@types" };
+      }
     } catch {
     }
     const fallback = path55.join(typesPkgDir, "index.d.ts");
@@ -78457,8 +78804,11 @@ var FILE_PATH_TOOLS = /* @__PURE__ */ new Set(["Read", "Edit", "Write", "Noteboo
 function extractFilePath(name2, input) {
   if (!FILE_PATH_TOOLS.has(name2)) return null;
   if (input === null || typeof input !== "object") return null;
-  const fp = input["file_path"];
-  return typeof fp === "string" ? fp : null;
+  const o = input;
+  const fp = o["file_path"];
+  if (typeof fp === "string") return fp;
+  const notebookPath = o["notebook_path"];
+  return typeof notebookPath === "string" ? notebookPath : null;
 }
 function extractCommand2(name2, input) {
   if (name2 !== "Bash") return null;
@@ -79751,7 +80101,11 @@ function cmdVideoChapters(file2) {
     }
     lines2.push("(extract a subtitle stream to .vtt/.srt with ffmpeg, then use transcript/transcript-outline on it)");
   }
-  out(lines2.join("\n"));
+  const text = lines2.join("\n");
+  out(text);
+  const fullSourceBytes = fileSizeOrZero(file2);
+  const bytesSaved = Math.max(1, fullSourceBytes - Buffer.byteLength(text, "utf8"));
+  recordStat("video_chapters", bytesSaved, Math.round(bytesSaved / 4));
 }
 function formatVideoTimestamp(totalSeconds) {
   const hours = Math.floor(totalSeconds / 3600);
@@ -80388,6 +80742,50 @@ function decodeBase64Buffer(payload, label) {
   }
   return Buffer.from(normalized, "base64");
 }
+function cmdNoteAdd(file2, opts) {
+  if (!file2 || !file2.trim()) {
+    throw new CliError("file path cannot be empty");
+  }
+  const usingFrom = opts.contentFrom !== void 0;
+  const usingB64 = opts.contentB64 !== void 0;
+  if (usingFrom && usingB64) {
+    throw new CliError("cannot mix --content-from with --content-b64");
+  }
+  if (!usingFrom && !usingB64) {
+    throw new CliError("must provide either --content-from or --content-b64");
+  }
+  const contentBytes = usingFrom ? readFileBoundedRaw(opts.contentFrom, "--content-from") : decodeBase64Buffer(opts.contentB64, "--content-b64");
+  if (contentBytes.length === 0) {
+    throw new CliError("note content cannot be empty");
+  }
+  if (Buffer.compare(Buffer.from(contentBytes.toString("utf8"), "utf8"), contentBytes) !== 0) {
+    throw new CliError("note content must be valid UTF-8 text");
+  }
+  const resolvedPath = resolveIndexPath(file2);
+  if (!fs52.existsSync(resolvedPath)) {
+    throw new CliError(`File not found: '${resolvedPath}'`);
+  }
+  healStaleIndex(resolvedPath);
+  let symbol3 = WHOLE_FILE_NOTE_SYMBOL;
+  let fingerprint;
+  if (opts.symbol !== void 0) {
+    const match2 = resolveSymbolMatch(resolvedPath, opts.symbol);
+    if (match2 === null) {
+      const messages = [`No symbol named '${opts.symbol}' is indexed in '${file2}'`];
+      const available = symbolNamesInFile(resolvedPath);
+      if (available.length > 0) messages.push(didYouMean(available));
+      throw new CliError(messages.join("\n"));
+    }
+    symbol3 = opts.symbol;
+    fingerprint = fingerprintContent(match2.body);
+  } else {
+    fingerprint = computeFileFingerprint(resolvedPath);
+  }
+  upsertNote(resolvedPath, symbol3, contentBytes.toString("utf8"), fingerprint);
+  const target = opts.symbol !== void 0 ? `${file2}::${opts.symbol}` : file2;
+  out(`Note saved: ${target} (fingerprint ${fingerprint.slice(0, 12)})`);
+  recordStat("note_write");
+}
 function cmdWriteFile(dest, opts) {
   validateWritablePath(dest, "destination");
   if (opts.from !== void 0 && opts.b64 !== void 0) {
@@ -80493,6 +80891,56 @@ function diagnoseNearMiss(targetText, oldText) {
   }
   return void 0;
 }
+function detectDominantEol(buf) {
+  let crlf = 0;
+  let lfOnly = 0;
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 10) {
+      if (i > 0 && buf[i - 1] === 13) crlf++;
+      else lfOnly++;
+    }
+  }
+  return crlf > lfOnly ? "\r\n" : "\n";
+}
+function normalizeEolToMatch(source, reference) {
+  const eol = detectDominantEol(reference);
+  const CR = 13;
+  const LF = 10;
+  const collapsed = [];
+  for (let i = 0; i < source.length; i++) {
+    if (source[i] === CR && source[i + 1] === LF) continue;
+    collapsed.push(source[i]);
+  }
+  if (eol === "\n") return Buffer.from(collapsed);
+  const expanded = [];
+  for (const b of collapsed) {
+    if (b === LF) expanded.push(CR, LF);
+    else expanded.push(b);
+  }
+  return Buffer.from(expanded);
+}
+var MAX_CLOSEST_MATCH_COMPARISONS = 2e6;
+function findClosestLineWindow(targetText, oldText) {
+  const targetLines = targetText.split("\n");
+  const oldLines = oldText.split("\n");
+  const windowSize = oldLines.length;
+  if (windowSize === 0 || windowSize > targetLines.length) return void 0;
+  if ((targetLines.length - windowSize + 1) * windowSize > MAX_CLOSEST_MATCH_COMPARISONS) return void 0;
+  let bestIdx = -1;
+  let bestScore = 0;
+  for (let i = 0; i <= targetLines.length - windowSize; i++) {
+    let score = 0;
+    for (let j = 0; j < windowSize; j++) {
+      if (targetLines[i + j] === oldLines[j]) score++;
+    }
+    if (score > bestScore) {
+      bestScore = score;
+      bestIdx = i;
+    }
+  }
+  if (bestIdx === -1) return void 0;
+  return { lineStart: bestIdx + 1, region: targetLines.slice(bestIdx, bestIdx + windowSize).join("\n") };
+}
 function cmdReplace(file2, opts) {
   validateWritablePath(file2, "target file");
   const targetBuf = readFileBoundedRaw(file2, "target file", true);
@@ -80520,19 +80968,32 @@ function cmdReplace(file2, opts) {
   }
   const oldBytes = usingFrom ? readFileBoundedRaw(opts.oldFrom, "--old-from") : decodeBase64Buffer(opts.oldB64, "--old-b64");
   const newBytes = usingFrom ? readFileBoundedRaw(opts.newFrom, "--new-from") : decodeBase64Buffer(opts.newB64, "--new-b64");
-  if (oldBytes.length === 0) {
+  const normalizedOldBytes = opts.normalizeNewlines === true ? normalizeEolToMatch(oldBytes, targetBuf) : oldBytes;
+  const normalizedNewBytes = opts.normalizeNewlines === true ? normalizeEolToMatch(newBytes, targetBuf) : newBytes;
+  if (normalizedOldBytes.length === 0) {
     throw new CliError("old string cannot be empty");
   }
   const matches2 = [];
   let cursor = 0;
-  while ((cursor = targetBuf.indexOf(oldBytes, cursor)) !== -1) {
+  while ((cursor = targetBuf.indexOf(normalizedOldBytes, cursor)) !== -1) {
     matches2.push(cursor);
-    cursor += oldBytes.length;
+    cursor += normalizedOldBytes.length;
   }
   const occurrences = matches2.length;
   if (occurrences === 0) {
-    const nearMiss = diagnoseNearMiss(targetBuf.toString("utf8"), oldBytes.toString("utf8"));
-    throw new CliError(nearMiss !== void 0 ? `old string not found in ${file2} \u2014 ${nearMiss}` : `old string not found in ${file2}`);
+    const nearMiss = diagnoseNearMiss(targetBuf.toString("utf8"), normalizedOldBytes.toString("utf8"));
+    if (nearMiss !== void 0) {
+      throw new CliError(`old string not found in ${file2} \u2014 ${nearMiss}`);
+    }
+    const closest = findClosestLineWindow(targetBuf.toString("utf8"), normalizedOldBytes.toString("utf8"));
+    if (closest !== void 0) {
+      const diff = buildLineDiff(closest.region, normalizedOldBytes.toString("utf8"), file2);
+      throw new CliError(
+        `old string not found in ${file2} \u2014 closest match at line ${closest.lineStart} (showing: what's actually there vs. what --old-from/--old-b64 searched for):
+${diff}`
+      );
+    }
+    throw new CliError(`old string not found in ${file2}`);
   }
   if (occurrences > 1 && !opts.all) {
     throw new CliError(`old string appears ${occurrences} times in ${file2} \u2014 pass --all to replace every occurrence, or provide a more specific match`);
@@ -80541,8 +81002,8 @@ function cmdReplace(file2, opts) {
   let prevEnd = 0;
   for (const pos of matches2) {
     parts.push(targetBuf.subarray(prevEnd, pos));
-    parts.push(newBytes);
-    prevEnd = pos + oldBytes.length;
+    parts.push(normalizedNewBytes);
+    prevEnd = pos + normalizedOldBytes.length;
   }
   parts.push(targetBuf.subarray(prevEnd));
   const replacedBuf = Buffer.concat(parts);
@@ -80569,6 +81030,65 @@ function cmdReplace(file2, opts) {
   enqueueDirtyPathSafe(file2);
   out(`replaced ${occurrences} occurrence${occurrences === 1 ? "" : "s"} in ${file2}`);
 }
+function cmdInsertSection(file2, opts) {
+  validateWritablePath(file2, "target file");
+  const usingFrom = opts.contentFrom !== void 0;
+  const usingB64 = opts.contentB64 !== void 0;
+  if (usingFrom && usingB64) {
+    throw new CliError("cannot mix --content-from with --content-b64");
+  }
+  if (!usingFrom && !usingB64) {
+    throw new CliError("must provide either --content-from or --content-b64");
+  }
+  const contentBytes = usingFrom ? readFileBoundedRaw(opts.contentFrom, "--content-from") : decodeBase64Buffer(opts.contentB64, "--content-b64");
+  if (contentBytes.length === 0) {
+    throw new CliError("content to insert cannot be empty");
+  }
+  let preWriteStat;
+  try {
+    preWriteStat = fs52.statSync(file2);
+  } catch {
+  }
+  const result = readSection(file2, opts.after);
+  if (result === null) {
+    const available = listSections(file2);
+    const messages = [`Section '${opts.after}' not found in '${file2}'`];
+    if (available.length > 0) messages.push(didYouMean(available));
+    throw new CliError(messages.join("\n"));
+  }
+  let rawText;
+  try {
+    rawText = fs52.readFileSync(file2, "utf-8");
+  } catch (e) {
+    mapFsError(e, void 0, file2);
+  }
+  if (rawText.charCodeAt(0) === 65279) rawText = rawText.slice(1);
+  const eol = detectDominantEol(Buffer.from(rawText, "utf8"));
+  const lfLines = rawText.replace(/\r\n/g, "\n").split("\n");
+  const insertAt = result.lineEnd;
+  const insertedLines = contentBytes.toString("utf8").replace(/\r\n/g, "\n").split("\n");
+  if (insertedLines.length > 0 && insertedLines[insertedLines.length - 1] === "") insertedLines.pop();
+  const mergedLfText = [...lfLines.slice(0, insertAt), ...insertedLines, ...lfLines.slice(insertAt)].join("\n");
+  const mergedText = eol === "\n" ? mergedLfText : mergedLfText.replace(/\n/g, "\r\n");
+  if (preWriteStat !== void 0) {
+    let preRenameStat;
+    try {
+      preRenameStat = fs52.statSync(file2);
+    } catch {
+    }
+    if (preRenameStat !== void 0 && (preRenameStat.mtimeMs !== preWriteStat.mtimeMs || preRenameStat.size !== preWriteStat.size)) {
+      throw new CliError(`${file2} changed on disk while insert-section was running -- the file was modified concurrently, so the insert was NOT applied. Retry.`);
+    }
+  }
+  try {
+    atomicWriteBuffer(file2, Buffer.from(mergedText, "utf8"));
+  } catch (e) {
+    mapFsError(e, void 0, file2);
+  }
+  enqueueDirtyPathSafe(file2);
+  const redirectNote = result.redirectedFrom !== void 0 ? ` (redirected from: '${result.redirectedFrom}')` : "";
+  out(`inserted after '${result.heading}'${redirectNote} in ${file2}`);
+}
 async function cmdGdriveSections(fileId, opts) {
   const fetchOpts = { fresh: opts.fresh === true };
   const text = await fetchDoc(fileId, fetchOpts);
@@ -80783,7 +81303,9 @@ function buildProgram() {
       })
     )
   );
-  program2.command("section <spec>").description("read one section from a file (spec: file::heading), or list all sections with --list").option("-j, --json", "output as JSON").option("--list", "list all section headings in the file instead of reading one").action(
+  program2.command("section <spec>").description(
+    'read one section from a file (spec: file::heading, or file::<unambiguous heading prefix> \u2014 e.g. "Lesson 16" resolves a longer unique heading), or list all sections with --list'
+  ).option("-j, --json", "output as JSON").option("--list", "list all section headings in the file instead of reading one").action(
     (spec, opts) => opts.list === true ? runExit(() => runListSections({ file: spec, ...opts.json === true ? { json: true } : {} })) : runExitText(() => runSection({ spec, ...opts.json === true ? { json: true } : {} }))
   );
   program2.command("semantic <query>").description("semantic search (falls back to full-text search)").option("-l, --limit <n>", "max results").action(guard(cmdSemantic));
@@ -81144,7 +81666,33 @@ function buildProgram() {
   ).option("--summary", "line ranges and ours/base/theirs labels only, omitting the conflict content").option("--json", "emit the results as JSON instead of text").action(guard(cmdConflicts));
   program2.command("screenshot <url> <destPath>").description("capture a local headless-browser screenshot, shrunk the same way local image reads are").option("--executable-path <path>", "Chrome/Chromium executable to launch (overrides config/auto-detect)").option("--width <n>", "viewport width in pixels (default: 1280)").option("--height <n>", "viewport height in pixels (default: 800)").option("--full-page", "capture the full scrollable page instead of just the viewport").action(guard(cmdScreenshot));
   program2.command("write-file <dest>").description("write exact bytes to a file \u2014 handles backticks, quotes, $vars, CRLF without escaping\n\nModes: --b64 PAYLOAD (base64), --from SOURCE (copy file), or piped stdin").option("--from <source>", "copy bytes from this source file instead of stdin/base64").option("--b64 <payload>", "decode base64 payload and write to dest").action(guard(cmdWriteFile));
-  program2.command("replace <file>").description("replace one string in a file; supply old/new text via --old-from/--new-from or --old-b64/--new-b64, and use --all to replace every occurrence").option("--old-from <source>", "read the old text from this source file").option("--new-from <source>", "read the new text from this source file").option("--old-b64 <payload>", "base64 payload for the old text").option("--new-b64 <payload>", "base64 payload for the new text").option("--all", "replace every occurrence instead of requiring a unique match").action(guard(cmdReplace));
+  program2.command("replace <file>").description("replace one string in a file; supply old/new text via --old-from/--new-from or --old-b64/--new-b64, and use --all to replace every occurrence").option("--old-from <source>", "read the old text from this source file").option("--new-from <source>", "read the new text from this source file").option("--old-b64 <payload>", "base64 payload for the old text").option("--new-b64 <payload>", "base64 payload for the new text").option("--all", "replace every occurrence instead of requiring a unique match").option(
+    "--normalize-newlines",
+    "convert the old/new text's line endings (CRLF/LF) to match the target file's dominant line ending before matching, instead of requiring a byte-exact line-ending match"
+  ).action(guard(cmdReplace));
+  program2.command("insert-section <file>").description(
+    "insert content immediately after a matched section (spec resolved the same way as `section`: exact heading, or an unambiguous prefix), avoiding a stale byte-exact anchor for append-to-a-running-log edits"
+  ).requiredOption("--after <heading>", "heading text (or unambiguous prefix) to insert after").option("--content-from <source>", "read the content to insert from this source file").option("--content-b64 <payload>", "base64 payload for the content to insert").action(guard(cmdInsertSection));
+  program2.command("note-add <file>").description(
+    "attach a free-text architecture note to a file, or to one specific indexed symbol within it (--symbol NAME), fingerprinting what the note describes so `note-list --stale-only` can flag it once the code changes"
+  ).option("--symbol <name>", "attach the note to one indexed symbol in the file instead of the whole file").option("--content-from <source>", "read the note content (Markdown) from this source file").option("--content-b64 <payload>", "base64 payload for the note content").action(guard(cmdNoteAdd));
+  program2.command("note-get <file>").description("read back the note attached to a file, or to one indexed symbol within it (--symbol NAME); flags whether it has gone stale since it was written").option("--symbol <name>", "read the note attached to this indexed symbol instead of the whole-file note").option("-j, --json", "output as JSON").action(
+    (file2, opts) => runExitText(
+      () => runNoteGet({
+        file: file2,
+        ...opts.symbol !== void 0 ? { symbol: opts.symbol } : {},
+        ...opts.json === true ? { json: true } : {}
+      })
+    )
+  );
+  program2.command("note-list").description("list every recorded architecture note; --stale-only shows just the notes whose attached file/symbol changed since they were written").option("--stale-only", "only list notes whose fingerprint no longer matches the current index").option("-j, --json", "output as JSON").action(
+    (opts) => runExitText(
+      () => runNoteList({
+        ...opts.staleOnly === true ? { staleOnly: true } : {},
+        ...opts.json === true ? { json: true } : {}
+      })
+    )
+  );
   program2.command("gdrive-sections <file-id>").description("fetch and list sections from a public Google Doc").option("--heading <name>", "get content of one named section").option("--fresh", "skip the on-disk cache and force a live fetch").action(guard(cmdGdriveSections));
   program2.command("compress").description("run a shell command and emit a compressed view of its output").requiredOption("-c, --cmd <command>", "the shell command to run, as one string").option("-f, --filter <name>", "filter name (auto-detected from the command when omitted)").option("--timeout <seconds>", "wall-clock timeout in seconds (0 = built-in default)").option("--no-compress", "stream output raw without compression (debug the wrapper)").option("--profile <name>", "compression profile: aggressive | balanced | minimal").option("--max-tokens <n>", "post-compress token cap (0 = no cap)").action(cmdCompress);
   program2.command("version").description("print the token-goat version").action(