liteagents 2.17.1 → 2.19.0

package/CHANGELOG.md

@@ -15,6 +15,132 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Enhanced testing capabilities
 - Performance optimizations
 
+## [2.19.0] - 2026-08-26
+
+### Changed
+- **`docs/index.md` rows now list each doc's H2 headings, one per line, with a line range.**
+  The index is meant to let an agent find and slice-read a section without opening the doc —
+  previously each row carried only an H1, a line count, and a link, so an agent still had to
+  open the file to find anything inside it. Each H2 line reuses the exact `headings()` +
+  `fenceMask()` boundaries `scan` already writes to `outline.json` (no second parser), so a
+  heading inside a fenced code block still never appears. Archive rows stay H1-only — an
+  archived doc is frozen history, not a live section to route into.
+- **`/remember` step 7 self-heals `docs/index.md` every run, not just at reorg time.** Any
+  drift `due` reports (new/moved/changed/deleted, not only the >=5-doc DUE threshold) now
+  also re-runs `index-flat` — script-only, no model call — so the index stays current between
+  full `/docs-builder reorg` passes instead of silently drifting until the next one.
+- **`AGENT_RULES.md` demoted from an `@`-include to a plain path pointer.** It was wired into
+  CLAUDE.md as `@.claude/remember/AGENT_RULES.md`, which hot-loads the whole file into every
+  session even though it's documented as "not hot context" — measured at ~6.5k tokens/session
+  of standards prose loaded despite the file's own claim otherwise. `MEMORY.md` stays
+  `@`-referenced (it is hot); `AGENT_RULES.md` is now a plain path line, read only when
+  designing or building something new.
+
+## [2.18.0] - 2026-08-26
+
+### Changed
+- **`/remember`'s antigen step redesigned to classify-then-count.** A 15-repo audit found
+  MEMORY.md's Antigens section hand-drifted from the ledger in 14/15 repos and rule-text
+  disagreement in 22 entries, root-caused to the model writing the same rule text in three
+  places and doing hash/dedup arithmetic in prose. Narrowed the LLM to one classification
+  judgment per cluster (`drop` | existing `ag-NNN` | `new:<theme>`); moved everything else —
+  hash union, dedup, promotion, rendering, and checking — into deterministic code
+  (`friction.cjs count`/`render`/`check`/`migrate-attempts`). Added invariants I6-new
+  (render(ledger) byte-equal to MEMORY.md's Antigens section) and I7 (`rule` ==
+  `attempts[last].rule`), Guard B (`new:` clusters never merge with each other in the same
+  classify batch), and an adopted-date gate so pre-fix evidence can't count toward
+  `recurred_while_hot`. `remember.md` rewritten as literal commands to run, not prose to
+  interpret. Validated live on 3 real repos; 947 tests passing, mirrored to all
+  four packages with 0 non-path diffs.
+
+### Fixed
+- **`friction.cjs check` exited 0 when I6-new was NOT EQUAL** — only I7 could fail it, so an
+  automated caller saw a pass while MEMORY.md was hand-drifted from the ledger. Now exits 1 on
+  either invariant failing. Validated on real backups (zkagent NOT EQUAL → 1, bareloop 8 I7
+  mismatches → 1, liteagents EQUAL → 0).
+- **`observing`→`hot` promotion in `friction.cjs count` wrote no history line and left
+  `attempts[last].adopted` at the candidate date**, so on the next run a conversation from
+  before the rule went hot counted toward `recurred_while_hot` — the adopted-date gate was
+  comparing against the wrong date. Promotion now appends `promoted to hot (N sessions)` and
+  re-stamps `adopted` to the run date. Reproduced and fixed on liteagents' real ag-003
+  (unfixed: rwh=1; fixed: rwh=0, gated).
+- **`/remember` could append near-duplicate episodes when re-processing already-filed
+  stashes.** The Episodes section only ever appended; nothing checked whether a new episode
+  covered the same work as one already in the section. Step 4b's episode rule now dedups
+  before appending — merge into the existing entry (judged by content, not title) instead of
+  adding a second copy. Validated on the exact data that surfaced it: with the old rule, 4/5
+  duplicate pairs survived across 5 isolated runs; with dedup, 0/5, and the 10-most-recent cap
+  still held. All four packages.
+- **A newly-created antigen entry's `rule` text was a literal placeholder string,
+  not real content.** `friction.cjs count` wrote
+  a hardcoded placeholder string into `rule` and
+  `attempts[0].rule` for any brand-new `ag-NNN` entry, and `render` printed it verbatim into
+  MEMORY.md — so the placeholder could land in a user's actual memory file. The 4a classifier
+  now emits the one-line rule text alongside a `new:<theme>` label in the same judgment (no
+  new LLM pass): `{cluster_index: {label: "new:<theme>", rule: "..."}}`. `count` accepts both
+  this shape and the old bare-string shape (bare stays valid for `drop`/`ag-NNN`, and for
+  `new:` clusters with `sessions < 2`, which never create an entry). A `new:` cluster with
+  `sessions >= 2` and no rule is reported as malformed and creates nothing — never falls back
+  to placeholder text. All four packages; 947 tests passing.
+- **friction's severity axis was degenerate — every cluster it ever emitted was severe.**
+  Clusters are seeded only on an observed reaction (`user_correction`, `user_curse`,
+  `interrupt_cascade`), and the severe test accepted all three of those same signals, so the
+  thing required for a cluster to exist also made it severe. Measured 69/69 severe on the real
+  corpus (3170 sessions, 77 projects) and 66/66 on the privcloud fixture. The documented
+  recurrence × severity 2×2 was therefore a 1×2 on recurrence alone: `fact` (recurring + mild)
+  and `drop` (one-off + mild) had never once fired, and every one-off "no, do X instead" was
+  labelled an `episode` — 68 of them in a single `/remember` run. Severe now means intensity:
+  a curse, an interrupt cascade, or a tool error corroborating the reaction; a plain
+  correction is mild. Re-run on the same corpus: 69 → 31 clusters, all 38 dropped were
+  correction-only with no curse/interrupt/error. Regression fixture (i) plus a new assertion
+  on (h) (13 plain corrections → `fact`, not `antigen`) observed failing on pre-fix code;
+  five dedup fixtures gained a curse word so they stay observable. All four packages.
+- **Review of both specs against their scripts found 24 more defects; each was reproduced,
+  approved, and then fixed one at a time by a delegated agent with a failing-first test.**
+  docs-builder script: `apply-reorg` wrote a config pointer to a `docs/index.md` that
+  `index-flat` had just declined to write (now skipped with a message); its results JSON
+  reported `claudeMdUpdated: false` because it printed before the flag was set; `discover` on
+  an already-sorted corpus told the operator to run a classification interview on a 0-row
+  plan; the usage string omitted `cleanup-apply`; and JSON state (`docs/.docs-builder/*`)
+  resolved against the cwd while `index.md`/ledger/config resolved against `REPO`, splitting
+  the state when run from anywhere but the root — `ARTIFACTS` now resolves under `REPO` at
+  the one chokepoint, explicit `OUT=`/path args unchanged. friction: when analyze found no
+  sessions it fell through to extract on the PREVIOUS run's `friction_analysis.json`, exit 0,
+  clobbering `antigen_clusters.json` to empty — the no-input case now returns a distinct code
+  (2; 1 was already the verdict) and stops. docs-builder spec: commands now `cd` to the target
+  root and call the script by absolute path (`$DB`), every `REPO=<repo>` prefix dropped (they
+  also never matched `allowed-tools: Bash(node:*)`); neither picker flow ever stamped the
+  ledger, so `due` said NOT due forever — both end with `ledger` after the commit; Modes table
+  pointed at a nonexistent "step 4"; empty follow-up list had no instruction; two stale
+  `docs/README.md` refs and "fifteen subcommands" (fourteen). remember spec: step 7 called
+  `docs-builder.cjs` cwd-relative (MODULE_NOT_FOUND on every repo but this one) and relayed
+  `due`'s "run ledger" advice that step 7 itself forbids; the `antigen_review.md` fallback has
+  no `session_ids`, so 4c would have counted every re-scan as recurrence (no counting on that
+  path now); the migration clause re-fired every run on an entry that matched nothing; the
+  early-stop condition depended on 4c's own output; step 5 rendered legacy 1-session
+  `observing` entries; three wrong step cross-references; "recursively" was two levels.
+  Also: both test suites leaked every `mkdtemp` dir (~1,000 per docs-builder run) until
+  `/tmp` ran out of inodes mid-session — both now remove them on exit (`KEEP_TMP=1` keeps).
+  Not changed, flagged as a design call: a friction `fact` (3+ sessions, mild) writes straight
+  into hot Facts with no ledger stage while an antigen needs 5 — reachable for the first time
+  since the severity fix.
+- **`/docs-builder` could not find its own script outside this repo.** `docs-builder.md` wrote
+  every command as `node docs-builder/docs-builder.cjs …` without saying that path is
+  relative to the command's own directory (`~/.claude/commands/`), so on an external repo the
+  model searched the target tree, found nothing, and refused to run. Added the same "locate
+  the script first" step `remember.md` already has for `friction.cjs`. All four packages.
+
+- **`/remember` step 4b routed a one-off severe friction cluster to "an Episode" that has no
+  home.** The Episodes section is stash-fed and capped at 10, and 4c already refuses a ledger
+  entry for a 1-session cluster — so the instruction contradicted the rest of the command and,
+  post-severity-fix, would have asked for ~30 cross-project one-offs to flush the stash
+  episodes. 4b now says what 4c already implied: a one-off is written nowhere; friction
+  re-surfaces it every run until it recurs, and at 2 sessions it gets a ledger `observing`
+  entry. Step 8's "facts should not grow by the number of new facts" expectation was reworded
+  too — measured on bareloop at steady state (273 facts, mean 131 chars, 0 near-duplicates)
+  the compressor correctly shortens nothing, and the old wording invited forced merges.
+  All four packages.
+
 ## [2.17.1] - 2026-08-25
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liteagents",
-  "version": "2.17.1",
+  "version": "2.19.0",
   "description": "AI development toolkit with 11 specialized agents and 18 commands including live-canvas UI design with click-to-annotate feedback. Simple one-question installer for Claude, Opencode, Ampcode, and Droid.",
   "main": "index.js",
   "bin": {

package/packages/ampcode/commands/docs-builder/docs-builder.cjs

@@ -728,14 +728,33 @@ function plan(outlineF, labelsF) {
 // tripwire, never a prune, never a collapse, never a delete.
 const ARCHIVE_WARN_ROWS = 100; // stated default, not measured — see docs-builder-v3-spec.md
 
-function indexRow(rel, dest) {
+// `includeH2` is false for archive rows: an archived doc is frozen history, not a live
+// section a reader is being routed into, so its row stays H1 + line count + link only.
+function indexRow(rel, dest, includeH2) {
   const text = read(rel);
-  const h1 = (text.split('\n').find(l => l.startsWith('# ')) || '').slice(2).trim();
-  const lines = text.split('\n').length;
+  const lines = text.split('\n');
+  // Same headings()+fenceMask() path scan() uses -- no second parser -- so an H2 inside a
+  // ``` fence is masked out here exactly as it is there.
+  const mask = fenceMask(lines);
+  const { h1, heads } = headings(lines, mask);
   // Read from INSIDE index.md, so the link must resolve relative to index.md's own
   // directory, not the repo root.
   const relLink = path.relative(path.dirname(dest), repoPath(rel)).split(path.sep).join('/');
-  return `- [${h1 || path.basename(rel)}](${relLink}) — ${lines} lines\n`;
+  let row = `- [${h1 || path.basename(rel)}](${relLink}) — ${lines.length} lines\n`;
+  if (!includeH2) return row;
+  // One line per H2, each with its own line range: from the `## ` heading's own 1-based
+  // line through the line before the next heading of level <= 2 (H1 or H2), or EOF for the
+  // last one -- the SAME boundary scan() uses to write s/e into outline.json, re-derived
+  // here from the same heads array rather than duplicated as a second computation. Lets an
+  // agent jump straight to (and slice-read) a section without opening the doc at all.
+  const boundaries = heads.filter(h => h.lvl <= 2);
+  boundaries.forEach((h, i) => {
+    if (h.lvl !== 2) return;
+    const start = h.line;
+    const end = i + 1 < boundaries.length ? boundaries[i + 1].line - 1 : lines.length;
+    row += `  - ${h.text} (L${start}–${end})\n`;
+  });
+  return row;
 }
 
 function renderSection(title, rows) {
@@ -761,15 +780,16 @@ function indexFlat() {
 
   if (!productFiles.length && !logsFiles.length && !archiveFiles.length && !pageFiles.length) {
     console.log('nothing to index — run `discover` + `apply-reorg` first.');
-    return;
+    return false; // caller (applyReorg) uses this to skip the config pointer — no index.md was written
   }
 
   const outRel = process.env.OUT || 'docs/index.md';
   const dest = repoPath(outRel);
   const productRows = [...productFiles, ...pageFiles].sort()
-    .map(f => ({ file: f, row: indexRow(f, dest) }));
-  const logsRows = logsFiles.sort().map(f => ({ file: f, row: indexRow(f, dest) }));
-  const archiveRows = archiveFiles.sort().map(f => ({ file: f, row: indexRow(f, dest) }));
+    .map(f => ({ file: f, row: indexRow(f, dest, true) }));
+  const logsRows = logsFiles.sort().map(f => ({ file: f, row: indexRow(f, dest, true) }));
+  // Archive rows are deliberately H1-only -- frozen history, not a live section to route into.
+  const archiveRows = archiveFiles.sort().map(f => ({ file: f, row: indexRow(f, dest, false) }));
 
   let s = '# Index\n\n';
   // Unconditional — not gated on row count, unlike ARCHIVE_WARN_ROWS below: a reader should
@@ -1748,7 +1768,11 @@ function discover(root) {
   // writes had persisted. Carry-forward (above) is exactly why a re-run can arrive here with
   // buckets already set, so this has to report what is actually in the plan.
   const filled = rows.filter(r => r.bucket).length;
-  if (!filled) {
+  if (!rows.length) {
+    console.log(`plan written to docs/.docs-builder/reorg-plan.json — 0 rows. Nothing outside `
+      + 'product/, logs/ and archive/ is left to classify — the corpus is already sorted. '
+      + '`apply-reorg` will only rescan and rebuild the index.');
+  } else if (!filled) {
     console.log(`plan written to docs/.docs-builder/reorg-plan.json — every row's \`suggested\` `
       + 'is a PRIOR, not a verdict, and `bucket` is empty. Run the classification interview '
       + '(docs-builder.md): feed the model the plan, get bucket+reason per row, get the user\'s '
@@ -1880,7 +1904,7 @@ const DOCS_INDEX_END = '<!-- DOCS_INDEX:END -->';
 function docsIndexBlock() {
   return `${DOCS_INDEX_START}\n`
     + 'Docs map: `docs/index.md` — every doc in this project, with line counts.\n'
-    + 'Too many rows to read whole? Search instead: `/docs-builder search <query words>`\n'
+    + 'Search this corpus instead of reading it whole: `/docs-builder search <query words>`\n'
     + `${DOCS_INDEX_END}`;
 }
 function injectClaudeMdPointer() {
@@ -1969,7 +1993,6 @@ function applyReorg(planFile) {
   // (re)builds outline.json for a corpus that already sat in docs/product/docs/archive/docs/logs
   // from a previous run, e.g. after a manual git mv or a re-run with nothing left to do.
   scanWholeCorpus();
-  console.log(JSON.stringify(results, null, 1));
   if (splitCandidates.length) {
     // Ranked, logs last (spec §5): a prereg is a legitimate split target but rarely the best
     // NEXT one. Array.prototype.sort is stable in Node, so this only reorders logs to the
@@ -1982,18 +2005,23 @@ function applyReorg(planFile) {
   // v3: apply-reorg writes docs/index.md itself — a reorg-only corpus ends up indexed
   // without a second command. Runs unconditionally — oversized docs are sorted like anything
   // else now, so this was never conditional on them.
-  indexFlat();
-  // Crash-isolated, same spirit as the moveDoc() follow-up failures collected above: a
-  // failure to write the config file is a WARN, never a thrown error — it must not make an
-  // already-moved file look unmoved or fail the run.
+  const indexed = indexFlat() !== false;
   const configName = process.env.CONFIG || 'CLAUDE.md';
-  try {
-    injectClaudeMdPointer();
-    results.claudeMdUpdated = true;
-    console.log(`  updated ${configName} with the docs/index.md pointer`);
-  } catch (e) {
-    console.error(`  WARN could not update ${configName} with the docs/index.md pointer: ${e.message}`);
+  if (!indexed) {
+    console.log(`  skipped the ${configName} pointer — no docs/index.md was written`);
+  } else {
+    // Crash-isolated, same spirit as the moveDoc() follow-up failures collected above: a
+    // failure to write the config file is a WARN, never a thrown error — it must not make an
+    // already-moved file look unmoved or fail the run.
+    try {
+      injectClaudeMdPointer();
+      results.claudeMdUpdated = true;
+      console.log(`  updated ${configName} with the docs/index.md pointer`);
+    } catch (e) {
+      console.error(`  WARN could not update ${configName} with the docs/index.md pointer: ${e.message}`);
+    }
   }
+  console.log(JSON.stringify(results, null, 1));
   logOp('apply-reorg', `moved ${results.moved}, skipped ${results.skipped}, `
     + `${splitCandidates.length} oversized split candidate(s), `
     + `${results.linksRewritten} link(s) rewritten, ${results.syncFailed} sync failure(s), `
@@ -2327,7 +2355,7 @@ function cleanupApply(file, outlineF, labelsF) {
 
 // Machine state has one home. Callers can override with OUT, but the default must never
 // scatter JSON into whatever directory the user happened to be standing in.
-const ARTIFACTS = 'docs/.docs-builder';
+const ARTIFACTS = path.join(REPO, 'docs/.docs-builder');
 function write(obj, fallback) {
   const dest = process.env.OUT || path.join(ARTIFACTS, fallback);
   fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -2352,7 +2380,7 @@ switch (cmd) {
   case 'cleanup-apply': cleanupApply(rest[0], rest[1], rest[2]); break;
   default:
     die('usage: docs-builder.cjs <scan|validate|plan|index-flat|search|archive|ledger|due|lint|'
-      + 'discover|apply-reorg|reorg|cleanup> [args]\n'
+      + 'discover|apply-reorg|reorg|cleanup|cleanup-apply> [args]\n'
       + '  scan        <file.md...>                 -> outline.json\n'
       + '  validate    <outline.json> <labels.json> -> PASS/FAIL (exit 1 on FAIL)\n'
       + '  plan        <outline.json> <labels.json> -> task-<theme>.json per page\n'
@@ -2368,6 +2396,7 @@ switch (cmd) {
       + 'drift summary if a ledger stamp exists (the single front door)\n'
       + '  cleanup     <file.md>                     -> ONE named file: cost estimate, then scan\n'
       + '                                                 (the ONLY entry point to the split pipeline)\n'
+      + '  cleanup-apply <file.md> [outline] [labels] -> plan + pages + archive, after the cleanup interview\n'
       + 'env: REPO (default cwd), OUT (output path), INDEX (default docs/index.md), '
       + 'PAGES (default docs/wiki), TASKS (default docs/.docs-builder/tasks), '
       + 'N (search result count, default 10), OVERSIZED_LINES (default 500)');

package/packages/ampcode/commands/docs-builder.md

@@ -9,7 +9,7 @@ allowed-tools: Read, Write, Edit, Grep, Glob, Task, AskUserQuestion, Bash(node:*
 # docs-builder
 
 Keep project docs **current, complete and findable**, and split a file when it outgrows
-its row in `docs/README.md`.
+its row in `docs/index.md`.
 
 > **The honest label: this does NOT make docs cheaper to read.**
 > Measured four ways; best case is a tie with doing nothing. Cost tracks *findings*, not
@@ -36,6 +36,21 @@ carry over, the absolute prices do not.
 
 ## Invocation
 
+**Locate the script first.** `docs-builder.cjs` is bundled next to this command at
+`docs-builder/docs-builder.cjs` — the same directory as this file, whether installed or run
+from the package. Never search the target repo for it, never reconstruct it from this spec,
+and if it truly exists nowhere say so and stop. Set `DB` to its ABSOLUTE path, then `cd` to
+the target repo's root:
+
+```
+DB=<absolute path to docs-builder.cjs>
+cd <target repo root>
+```
+
+Every command below is `node $DB …`; everything the script writes (`docs/.docs-builder/*`
+JSON state, `docs/index.md`, the ledger, the log, the config pointer) lands under the target
+repo. `REPO=` is optional and only needed when not running from the repo root.
+
 **With an argument** (`reorg`, `cleanup <file>`, or `search <query words...>`) — run that mode
 directly, no question asked.
 
@@ -82,10 +97,17 @@ read-only — no model cost, no interview, nothing moves.
 3. `apply-reorg` moves every row, **oversized included** — size only decides whether a doc is
    *splittable*, not whether it gets sorted. It refuses outright if any row's `bucket` is
    still empty. Afterward it prints the oversized docs it just moved as a follow-up list,
-   `cleanup <NEW path>  (N lines)`, `logs/` entries last. Show that list, then **ask which to
-   split** (any, all, none). Only then run `cleanup <file>` (Mode 1) on each chosen file —
+   `cleanup <NEW path>  (N lines)`, `logs/` entries last. If the list is empty (nothing
+   oversized), say so and skip the split question; otherwise show the list, then **ask which
+   to split** (any, all, none). Only then run `cleanup <file>` (Mode 1) on each chosen file —
    `cleanup` itself prints the estimated split cost for that one file, then a mechanical
    shape report, then stops for its own interview (Mode 1, step 1b) before anything else runs.
+   Before that first commit, add `docs/.docs-builder/` to `.gitignore` if it is not already
+   ignored: it is machine state, regenerated every run, and the ledger stamp is per-clone by
+   design — it must never ride into history on a later `git add -A`.
+   Once the moves are committed, run `node $DB ledger` — nothing in steps 1-3 stamps the
+   ledger, and without the stamp `due` stays NOT due, the picker's verdict stays uninformed,
+   and `/remember`'s docs nudge never fires.
 
 The two stops are deliberate and different. Step 2 guards *correctness* — the interview and
 the user's approval, before a single file moves. Step 3's follow-up guards *cost* — splitting
@@ -96,7 +118,8 @@ when they pick "First run". Never split N files in one shot on an unseen list.
 first, if a ledger stamp exists, then it runs `discover`. If any row's `bucket` is still
 empty (true on a genuine first run, or when new files appeared since the last classification),
 `reorg` **stops right there** and prints what to do next — it never silently proceeds past an
-unclassified plan. Once the plan is fully classified (an already-sorted corpus's re-run
+unclassified plan. Commit what it changed, then run `node $DB ledger` to move the stamp. Once
+the plan is fully classified (an already-sorted corpus's re-run
 carries its prior classifications forward automatically — see "Discover is idempotent"
 below), `reorg` continues straight through `apply-reorg` → `lint`, no further stop, so
 `index.md` and `lint.json` stay current. This is the common, cheap case for a corpus that is
@@ -109,7 +132,7 @@ already sorted: nothing new to classify, so the interview gate never fires.
 | Mode | Menu option | Does | Destructive |
 |---|---|---|---|
 | `/docs-builder reorg` (discover, classification interview, confirm, then apply-reorg) | *First run*, steps 1-3 | classify a WHOLE corpus into product/logs/archive | no (moves are `git mv`, plan classified and reviewed first) |
-| `/docs-builder cleanup <file>` | *First run*, step 4 | measure ONE named oversized doc (cost, scan, heading shape) → **stops for the interview** | no (measure-only; original preserved) |
+| `/docs-builder cleanup <file>` | *First run*, step 3's split question | measure ONE named oversized doc (cost, scan, heading shape) → **stops for the interview** | no (measure-only; original preserved) |
 | `/docs-builder reorg` (bare `docs-builder.cjs reorg`) | *Docs drift* | due's drift summary (if a ledger stamp exists) + discover → (stops here if anything is still unclassified) → apply-reorg → lint, whole corpus | no |
 | `/docs-builder search <query words...>` | *(none — explicit-argument mode only, never offered in the bare picker)* | BM25-rank sections of `docs/.docs-builder/outline.json` against the query, read-only | no |
 
@@ -206,7 +229,7 @@ purpose, not silently dropped.
 ### 1. Discover (script) — enriches and PROPOSES, never classifies, never moves
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs discover        # defaults to docs/
+node $DB discover        # defaults to docs/
 ```
 
 Recursively finds every `*.md` under the root (skipping `wiki/`, `logs/`, `archive/`,
@@ -317,7 +340,7 @@ files with no gate at all.
 ### 3. Apply (script) — an ALREADY-CLASSIFIED plan, verified moves, survives a bad file
 
 ```bash
-CONFIG=AGENT.md node docs-builder/docs-builder.cjs apply-reorg   # defaults to the plan above
+CONFIG=AGENT.md node $DB apply-reorg   # defaults to the plan above
 ```
 
 **Refuses outright if any row's `bucket` is still empty** — the interview-has-not-happened
@@ -455,7 +478,7 @@ real page count isn't known until the model groups sections in step 2), runs ste
 below for you, then measures the document's heading shape and **stops**:
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs cleanup docs/BIG.md
+node $DB cleanup docs/BIG.md
 ```
 
 **Nothing past this command runs until a human has answered the interview (step 1b) below.**
@@ -468,8 +491,8 @@ choosing to continue, and confirming, the themes.
 ### 1. Scan (script) — run automatically by `cleanup`, shown here for what it produces
 
 ```bash
-REPO=<repo> OUT=docs/.docs-builder/outline.json \
-  node docs-builder/docs-builder.cjs scan docs/BIG.md
+OUT=docs/.docs-builder/outline.json \
+  node $DB scan docs/BIG.md
 ```
 
 One record per H2, each carrying the doc's H1 identity, a 2-line snippet, every H3 **with
@@ -560,7 +583,7 @@ it `false`) on every other theme.
 ### 3. Validate (script) — **hard gate, exits 1 on failure**
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs validate \
+node $DB validate \
   docs/.docs-builder/{outline,labels}.json
 ```
 
@@ -586,7 +609,7 @@ index, which is gone — on the one whole-corpus index it would silently skip mo
 ### 4. Plan + apply (script) — `cleanup-apply`, the door back in after the interview
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs cleanup-apply docs/BIG.md \
+node $DB cleanup-apply docs/BIG.md \
   docs/.docs-builder/outline.json docs/.docs-builder/labels.json
 ```
 
@@ -616,7 +639,7 @@ the checkpoint; there is no separate state file to go stale. It is also still ru
 own:
 
 ```bash
-REPO=<repo> OUT=docs/.docs-builder/tasks node docs-builder/docs-builder.cjs plan \
+OUT=docs/.docs-builder/tasks node $DB plan \
   docs/.docs-builder/{outline,labels}.json
 ```
 
@@ -653,7 +676,7 @@ Each agent reads **only its own line ranges**. The value is context isolation.
 ### 6. Archive the original (script) — run for you by `cleanup-apply` once all pages exist
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs archive docs/BIG.md
+node $DB archive docs/BIG.md
 ```
 
 A **verified move**, not a copy: hash → `git mv` (so history follows) → hash again →
@@ -697,7 +720,7 @@ which defaults the outline path and takes only the query. The underlying script
 works directly, and is what the slash command runs:
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs search docs/.docs-builder/outline.json <query words...>
+node $DB search docs/.docs-builder/outline.json <query words...>
 ```
 
 BM25 over each section's real text (no deps, no separate index to build — it reads
@@ -717,14 +740,20 @@ reorg, not only whichever ones a split happened to touch.
 some archived docs).
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs index-flat
+node $DB index-flat
 ```
 
 Writes **one** `docs/index.md` covering the whole corpus, in three sections: `## Product`
 (one row per file under `docs/product/`, plus any pages under `PAGES` — default `docs/wiki/`
 — if they exist, plus any doc still sitting in place elsewhere), `## Logs` (one row per file
 under `docs/logs/`), and `## Archive` (one row per file under `docs/archive/`). Each row is
-an H1 title, a line count, and a link. No theme grouping, no `labels.json`, no model call.
+an H1 title, a line count, and a link, plus one indented line per H2 heading (in document
+order) so an agent can find and slice-read a section without opening the doc — each H2
+line carries its own `(Lstart–end)` line range, reusing the SAME `headings()`+`fenceMask()`
+boundaries `scan` already writes to `outline.json` (no second parser). Omitted when the doc
+has no H2s. `## Archive` rows are H1-only, never H2 lines — an archived doc is frozen
+history, not a live section to route into. No theme grouping, no `labels.json`, no model
+call.
 Default destination `docs/index.md` — **the only writer of that default path** in this whole
 pipeline (nothing else writes an index at all).
 `search` reads `outline.json`, never `index.md`. Prints the row counts and records a `log.md`
@@ -745,7 +774,7 @@ v3 folds the old `reconcile` and `due` commands into one: "first run" (nothing s
 state, and two separate commands only made users guess which one to run.
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs reorg
+node $DB reorg
 ```
 
 If a ledger stamp exists (see "Knowing when reorg is due" below), its `due`-style drift
@@ -773,7 +802,7 @@ still runnable by hand once a `labels.json` exists.
 `lint` is also runnable standalone, on any file list, not only as part of `reorg`:
 
 ```bash
-REPO=<repo> node docs-builder/docs-builder.cjs lint <file.md...>
+node $DB lint <file.md...>
 ```
 
 -> `lint.json`. Every check below is declared-only (see the governing rule further down) —
@@ -812,8 +841,8 @@ git is the diff engine. The ledger stores only the one thing git cannot know —
 last consolidated** — so the two can never drift apart.
 
 ```bash
-node docs-builder/docs-builder.cjs ledger   # stamp the current state (run after a reorg)
-node docs-builder/docs-builder.cjs due      # what changed since, and by how much
+node $DB ledger   # stamp the current state (run after COMMITTING a reorg)
+node $DB due      # what changed since, and by how much
 ```
 
 `due` classifies every doc against the stamped SHA using `git diff --numstat -M`: