liteagents 2.18.0 → 2.19.0

package/CHANGELOG.md

@@ -15,6 +15,27 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liteagents",
-  "version": "2.18.0",
+  "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) {
@@ -767,9 +786,10 @@ function indexFlat() {
   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

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

@@ -747,7 +747,13 @@ Writes **one** `docs/index.md` covering the whole corpus, in three sections: `##
 (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`

package/packages/ampcode/commands/remember.md

@@ -346,12 +346,13 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      inline duplication is needed
    - If `.amp/remember/AGENT_RULES.md` exists (bootstrapped in step 1), compose a second,
      independent section between `<!-- AGENT_RULES:START -->` and `<!-- AGENT_RULES:END -->`
-     markers:
+     markers. Unlike MEMORY.md above, this is a **plain path pointer, never `@`-referenced**
+     — an `@`-reference hot-loads the whole file into every session, and this is a standards
+     guide to consult when designing/building something new, not hot context:
      ```
      <!-- AGENT_RULES:START -->
-     Consult when building something new or adding a feature — a standards guide, not hot
-     context like MEMORY.md above:
-     @.amp/remember/AGENT_RULES.md
+     Standards guide (read when designing/building something new, not hot context):
+     .amp/remember/AGENT_RULES.md
      <!-- AGENT_RULES:END -->
      ```
    - Each marker pair is independent: if AGENT.md already has a given pair, replace the
@@ -411,11 +412,12 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
 6. **Update processed manifest**
    - Append paths of newly processed stashes to `.amp/remember/.processed`
 
-7. **Docs reconcile check — DETECT ONLY** (best-effort, crash-isolated like step 0)
+7. **Docs reconcile check + auto re-index** (best-effort, crash-isolated like step 0)
 
-   `/remember` never reconciles docs, never writes frontmatter, never edits a page. It
-   prints at most one nudge line. Wrapped so any failure here can never block the memory
-   write that already happened in steps 3-6.
+   `/remember` never reconciles doc CONTENT, never writes frontmatter, never edits a page —
+   the only write here is the generated `docs/index.md` itself, via the same deterministic
+   `index-flat` script `/docs-builder` already uses, never a model call. Wrapped so any
+   failure here can never block the memory write that already happened in steps 3-6.
 
    - **Locate `docs-builder.cjs`** — bundled next to this command at
      `docs-builder/docs-builder.cjs` (same convention as `remember/friction.cjs`). Call it by
@@ -444,7 +446,19 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
    - If `due` prints "no ledger yet" (no `docs/.docs-builder/ledger.json` to compare against),
      do NOT relay it — print the same `/docs-builder reorg` line as the no-`docs/.docs-builder/`
      case above, for the same reason: `ledger` would stamp an unsorted pile as correct.
-   - If DUE, end with one line and nothing more:
+   - **Auto re-index — script only, no model, in addition to the DUE advisory below, not a
+     replacement for it.** If `due`'s output was NOT `docs unchanged since <sha>. NOT due.`
+     (i.e. it printed a row table -- any new/moved/moved+changed/changed/deleted doc, whether
+     or not the >=5 threshold below was crossed), the index has drifted and self-heals right
+     here, unconditionally:
+     ```bash
+     node <docs-builder.cjs> index-flat
+     ```
+     Same script `/docs-builder reorg` already calls, run standalone — no model call, no
+     interview, nothing moves. Note in the step-8 report that `docs/index.md` (and
+     `docs/log.md`, if `index-flat` touched it) were regenerated, so they are included
+     alongside whatever step 3-6 already changed when this run is committed.
+   - If DUE (the row count crossed the >=5 threshold), ALSO end with one line:
      ```
      docs: 7 changed since 991f72d3 — run /docs-builder reorg
      ```
@@ -489,12 +503,14 @@ Reads all raw material (`.amp/stash/*.md` + `.amp/remember/friction/antigen_clus
      ledger: ag-002 "literal scoped ask"         ESCALATED → Fact; 2 phrasings failed. Hook or accept?
      ```
    - If AGENT_RULES.md was bootstrapped this run, say so (one line)
+   - If step 7 ran the auto re-index, say so and name the regenerated files
+     (`docs/index.md`, plus `docs/log.md` if touched) so they are staged with this run
    - Confirm MEMORY.md and AGENT.md updated
 
 **File locations (all project-local — two dirs: `/stash` owns `.amp/stash/`, `/remember` owns `.amp/remember/`)**
 - Stash files: `.amp/stash/*.md`
 - Memory file: `.amp/remember/MEMORY.md` (single source of truth, referenced as `@.amp/remember/MEMORY.md`)
-- Rules template: `.amp/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced as `@.amp/remember/AGENT_RULES.md`)
+- Rules template: `.amp/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced by a plain path pointer, not `@`-referenced — see step 5)
 - Antigen ledger: `.amp/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
 - Consolidation report: `.amp/remember/report.md` (latest step-8 report, overwritten each run)
 - Processed manifest: `.amp/remember/.processed`

package/packages/claude/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) {
@@ -767,9 +786,10 @@ function indexFlat() {
   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

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

@@ -747,7 +747,13 @@ Writes **one** `docs/index.md` covering the whole corpus, in three sections: `##
 (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`

package/packages/claude/commands/remember.md

@@ -346,12 +346,13 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antige
      inline duplication is needed
    - If `.claude/remember/AGENT_RULES.md` exists (bootstrapped in step 1), compose a second,
      independent section between `<!-- AGENT_RULES:START -->` and `<!-- AGENT_RULES:END -->`
-     markers:
+     markers. Unlike MEMORY.md above, this is a **plain path pointer, never `@`-referenced**
+     — an `@`-reference hot-loads the whole file into every session, and this is a standards
+     guide to consult when designing/building something new, not hot context:
      ```
      <!-- AGENT_RULES:START -->
-     Consult when building something new or adding a feature — a standards guide, not hot
-     context like MEMORY.md above:
-     @.claude/remember/AGENT_RULES.md
+     Standards guide (read when designing/building something new, not hot context):
+     .claude/remember/AGENT_RULES.md
      <!-- AGENT_RULES:END -->
      ```
    - Each marker pair is independent: if CLAUDE.md already has a given pair, replace the
@@ -411,11 +412,12 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antige
 6. **Update processed manifest**
    - Append paths of newly processed stashes to `.claude/remember/.processed`
 
-7. **Docs reconcile check — DETECT ONLY** (best-effort, crash-isolated like step 0)
+7. **Docs reconcile check + auto re-index** (best-effort, crash-isolated like step 0)
 
-   `/remember` never reconciles docs, never writes frontmatter, never edits a page. It
-   prints at most one nudge line. Wrapped so any failure here can never block the memory
-   write that already happened in steps 3-6.
+   `/remember` never reconciles doc CONTENT, never writes frontmatter, never edits a page —
+   the only write here is the generated `docs/index.md` itself, via the same deterministic
+   `index-flat` script `/docs-builder` already uses, never a model call. Wrapped so any
+   failure here can never block the memory write that already happened in steps 3-6.
 
    - **Locate `docs-builder.cjs`** — bundled next to this command at
      `docs-builder/docs-builder.cjs` (same convention as `remember/friction.cjs`). Call it by
@@ -444,7 +446,19 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antige
    - If `due` prints "no ledger yet" (no `docs/.docs-builder/ledger.json` to compare against),
      do NOT relay it — print the same `/docs-builder reorg` line as the no-`docs/.docs-builder/`
      case above, for the same reason: `ledger` would stamp an unsorted pile as correct.
-   - If DUE, end with one line and nothing more:
+   - **Auto re-index — script only, no model, in addition to the DUE advisory below, not a
+     replacement for it.** If `due`'s output was NOT `docs unchanged since <sha>. NOT due.`
+     (i.e. it printed a row table -- any new/moved/moved+changed/changed/deleted doc, whether
+     or not the >=5 threshold below was crossed), the index has drifted and self-heals right
+     here, unconditionally:
+     ```bash
+     node <docs-builder.cjs> index-flat
+     ```
+     Same script `/docs-builder reorg` already calls, run standalone — no model call, no
+     interview, nothing moves. Note in the step-8 report that `docs/index.md` (and
+     `docs/log.md`, if `index-flat` touched it) were regenerated, so they are included
+     alongside whatever step 3-6 already changed when this run is committed.
+   - If DUE (the row count crossed the >=5 threshold), ALSO end with one line:
      ```
      docs: 7 changed since 991f72d3 — run /docs-builder reorg
      ```
@@ -489,12 +503,14 @@ Reads all raw material (`.claude/stash/*.md` + `.claude/remember/friction/antige
      ledger: ag-002 "literal scoped ask"         ESCALATED → Fact; 2 phrasings failed. Hook or accept?
      ```
    - If AGENT_RULES.md was bootstrapped this run, say so (one line)
+   - If step 7 ran the auto re-index, say so and name the regenerated files
+     (`docs/index.md`, plus `docs/log.md` if touched) so they are staged with this run
    - Confirm MEMORY.md and CLAUDE.md updated
 
 **File locations (all project-local — two dirs: `/stash` owns `.claude/stash/`, `/remember` owns `.claude/remember/`)**
 - Stash files: `.claude/stash/*.md`
 - Memory file: `.claude/remember/MEMORY.md` (single source of truth, referenced as `@.claude/remember/MEMORY.md`)
-- Rules template: `.claude/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced as `@.claude/remember/AGENT_RULES.md`)
+- Rules template: `.claude/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced by a plain path pointer, not `@`-referenced — see step 5)
 - Antigen ledger: `.claude/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
 - Consolidation report: `.claude/remember/report.md` (latest step-8 report, overwritten each run)
 - Processed manifest: `.claude/remember/.processed`

package/packages/droid/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) {
@@ -767,9 +786,10 @@ function indexFlat() {
   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

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

@@ -747,7 +747,13 @@ Writes **one** `docs/index.md` covering the whole corpus, in three sections: `##
 (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`

package/packages/droid/commands/remember.md

@@ -346,12 +346,13 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
      inline duplication is needed
    - If `.factory/remember/AGENT_RULES.md` exists (bootstrapped in step 1), compose a second,
      independent section between `<!-- AGENT_RULES:START -->` and `<!-- AGENT_RULES:END -->`
-     markers:
+     markers. Unlike MEMORY.md above, this is a **plain path pointer, never `@`-referenced**
+     — an `@`-reference hot-loads the whole file into every session, and this is a standards
+     guide to consult when designing/building something new, not hot context:
      ```
      <!-- AGENT_RULES:START -->
-     Consult when building something new or adding a feature — a standards guide, not hot
-     context like MEMORY.md above:
-     @.factory/remember/AGENT_RULES.md
+     Standards guide (read when designing/building something new, not hot context):
+     .factory/remember/AGENT_RULES.md
      <!-- AGENT_RULES:END -->
      ```
    - Each marker pair is independent: if AGENTS.md already has a given pair, replace the
@@ -411,11 +412,12 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
 6. **Update processed manifest**
    - Append paths of newly processed stashes to `.factory/remember/.processed`
 
-7. **Docs reconcile check — DETECT ONLY** (best-effort, crash-isolated like step 0)
+7. **Docs reconcile check + auto re-index** (best-effort, crash-isolated like step 0)
 
-   `/remember` never reconciles docs, never writes frontmatter, never edits a page. It
-   prints at most one nudge line. Wrapped so any failure here can never block the memory
-   write that already happened in steps 3-6.
+   `/remember` never reconciles doc CONTENT, never writes frontmatter, never edits a page —
+   the only write here is the generated `docs/index.md` itself, via the same deterministic
+   `index-flat` script `/docs-builder` already uses, never a model call. Wrapped so any
+   failure here can never block the memory write that already happened in steps 3-6.
 
    - **Locate `docs-builder.cjs`** — bundled next to this command at
      `docs-builder/docs-builder.cjs` (same convention as `remember/friction.cjs`). Call it by
@@ -444,7 +446,19 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
    - If `due` prints "no ledger yet" (no `docs/.docs-builder/ledger.json` to compare against),
      do NOT relay it — print the same `/docs-builder reorg` line as the no-`docs/.docs-builder/`
      case above, for the same reason: `ledger` would stamp an unsorted pile as correct.
-   - If DUE, end with one line and nothing more:
+   - **Auto re-index — script only, no model, in addition to the DUE advisory below, not a
+     replacement for it.** If `due`'s output was NOT `docs unchanged since <sha>. NOT due.`
+     (i.e. it printed a row table -- any new/moved/moved+changed/changed/deleted doc, whether
+     or not the >=5 threshold below was crossed), the index has drifted and self-heals right
+     here, unconditionally:
+     ```bash
+     node <docs-builder.cjs> index-flat
+     ```
+     Same script `/docs-builder reorg` already calls, run standalone — no model call, no
+     interview, nothing moves. Note in the step-8 report that `docs/index.md` (and
+     `docs/log.md`, if `index-flat` touched it) were regenerated, so they are included
+     alongside whatever step 3-6 already changed when this run is committed.
+   - If DUE (the row count crossed the >=5 threshold), ALSO end with one line:
      ```
      docs: 7 changed since 991f72d3 — run /docs-builder reorg
      ```
@@ -489,12 +503,14 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
      ledger: ag-002 "literal scoped ask"         ESCALATED → Fact; 2 phrasings failed. Hook or accept?
      ```
    - If AGENT_RULES.md was bootstrapped this run, say so (one line)
+   - If step 7 ran the auto re-index, say so and name the regenerated files
+     (`docs/index.md`, plus `docs/log.md` if touched) so they are staged with this run
    - Confirm MEMORY.md and AGENTS.md updated
 
 **File locations (all project-local — two dirs: `/stash` owns `.factory/stash/`, `/remember` owns `.factory/remember/`)**
 - Stash files: `.factory/stash/*.md`
 - Memory file: `.factory/remember/MEMORY.md` (single source of truth, referenced as `@.factory/remember/MEMORY.md`)
-- Rules template: `.factory/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced as `@.factory/remember/AGENT_RULES.md`)
+- Rules template: `.factory/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced by a plain path pointer, not `@`-referenced — see step 5)
 - Antigen ledger: `.factory/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
 - Consolidation report: `.factory/remember/report.md` (latest step-8 report, overwritten each run)
 - Processed manifest: `.factory/remember/.processed`

package/packages/opencode/command/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) {
@@ -767,9 +786,10 @@ function indexFlat() {
   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

package/packages/opencode/command/docs-builder.md

@@ -747,7 +747,13 @@ Writes **one** `docs/index.md` covering the whole corpus, in three sections: `##
 (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`

package/packages/opencode/command/remember.md

@@ -346,12 +346,13 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
      inline duplication is needed
    - If `.opencode/remember/AGENT_RULES.md` exists (bootstrapped in step 1), compose a second,
      independent section between `<!-- AGENT_RULES:START -->` and `<!-- AGENT_RULES:END -->`
-     markers:
+     markers. Unlike MEMORY.md above, this is a **plain path pointer, never `@`-referenced**
+     — an `@`-reference hot-loads the whole file into every session, and this is a standards
+     guide to consult when designing/building something new, not hot context:
      ```
      <!-- AGENT_RULES:START -->
-     Consult when building something new or adding a feature — a standards guide, not hot
-     context like MEMORY.md above:
-     @.opencode/remember/AGENT_RULES.md
+     Standards guide (read when designing/building something new, not hot context):
+     .opencode/remember/AGENT_RULES.md
      <!-- AGENT_RULES:END -->
      ```
    - Each marker pair is independent: if AGENTS.md already has a given pair, replace the
@@ -411,11 +412,12 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
 6. **Update processed manifest**
    - Append paths of newly processed stashes to `.opencode/remember/.processed`
 
-7. **Docs reconcile check — DETECT ONLY** (best-effort, crash-isolated like step 0)
+7. **Docs reconcile check + auto re-index** (best-effort, crash-isolated like step 0)
 
-   `/remember` never reconciles docs, never writes frontmatter, never edits a page. It
-   prints at most one nudge line. Wrapped so any failure here can never block the memory
-   write that already happened in steps 3-6.
+   `/remember` never reconciles doc CONTENT, never writes frontmatter, never edits a page —
+   the only write here is the generated `docs/index.md` itself, via the same deterministic
+   `index-flat` script `/docs-builder` already uses, never a model call. Wrapped so any
+   failure here can never block the memory write that already happened in steps 3-6.
 
    - **Locate `docs-builder.cjs`** — bundled next to this command at
      `docs-builder/docs-builder.cjs` (same convention as `remember/friction.cjs`). Call it by
@@ -444,7 +446,19 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
    - If `due` prints "no ledger yet" (no `docs/.docs-builder/ledger.json` to compare against),
      do NOT relay it — print the same `/docs-builder reorg` line as the no-`docs/.docs-builder/`
      case above, for the same reason: `ledger` would stamp an unsorted pile as correct.
-   - If DUE, end with one line and nothing more:
+   - **Auto re-index — script only, no model, in addition to the DUE advisory below, not a
+     replacement for it.** If `due`'s output was NOT `docs unchanged since <sha>. NOT due.`
+     (i.e. it printed a row table -- any new/moved/moved+changed/changed/deleted doc, whether
+     or not the >=5 threshold below was crossed), the index has drifted and self-heals right
+     here, unconditionally:
+     ```bash
+     node <docs-builder.cjs> index-flat
+     ```
+     Same script `/docs-builder reorg` already calls, run standalone — no model call, no
+     interview, nothing moves. Note in the step-8 report that `docs/index.md` (and
+     `docs/log.md`, if `index-flat` touched it) were regenerated, so they are included
+     alongside whatever step 3-6 already changed when this run is committed.
+   - If DUE (the row count crossed the >=5 threshold), ALSO end with one line:
      ```
      docs: 7 changed since 991f72d3 — run /docs-builder reorg
      ```
@@ -489,12 +503,14 @@ Reads all raw material (`.opencode/stash/*.md` + `.opencode/remember/friction/an
      ledger: ag-002 "literal scoped ask"         ESCALATED → Fact; 2 phrasings failed. Hook or accept?
      ```
    - If AGENT_RULES.md was bootstrapped this run, say so (one line)
+   - If step 7 ran the auto re-index, say so and name the regenerated files
+     (`docs/index.md`, plus `docs/log.md` if touched) so they are staged with this run
    - Confirm MEMORY.md and AGENTS.md updated
 
 **File locations (all project-local — two dirs: `/stash` owns `.opencode/stash/`, `/remember` owns `.opencode/remember/`)**
 - Stash files: `.opencode/stash/*.md`
 - Memory file: `.opencode/remember/MEMORY.md` (single source of truth, referenced as `@.opencode/remember/MEMORY.md`)
-- Rules template: `.opencode/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced as `@.opencode/remember/AGENT_RULES.md`)
+- Rules template: `.opencode/remember/AGENT_RULES.md` (bootstrapped once from the bundled package template on first `/remember` run, never overwritten again — user-owned after that; referenced by a plain path pointer, not `@`-referenced — see step 5)
 - Antigen ledger: `.opencode/remember/ledger.json` (per-rule evidence trail: class, status, attempts/rejected-buffer, recurrence-while-hot)
 - Consolidation report: `.opencode/remember/report.md` (latest step-8 report, overwritten each run)
 - Processed manifest: `.opencode/remember/.processed`