liteagents 2.18.0 → 2.20.0

package/CHANGELOG.md

@@ -15,6 +15,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Enhanced testing capabilities
 - Performance optimizations
 
+## [2.20.0] - 2026-08-29
+
+### Changed
+- **`AGENT_RULES.md` template (all 4 kits): the spec layer now requires the interview to
+  happen but leaves its shape free.** PRD is defined as a portal with 5 minimum fields
+  (problem & goal, go/no-go, out of scope, modules, open questions) that every POC refines.
+- **Four one-sentence execution-order rules (Sequence / Selection / Iteration / Verify) added
+  to Operating Flow.**
+- **"Build incrementally" replaced by "One module at a time"** (works alone, then connects,
+  both proven) and a separate "No fitting to pass" rule, with a matching Red Flag.
+- **New safeguard: never commit to `main`** — branch, then propose `/code-review` followed by
+  `/release`; merge/release only on a named go.
+- **Removed restated content**: the "AI Agent Instructions" section, the "Safety First"
+  bullet, the "POC scope" bullet, and duplicated spec/POC prose in the Communication Protocol
+  and the CLAUDE.md stub.
+
+## [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.20.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/AGENT_RULES.md

@@ -10,7 +10,6 @@
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
 9. [AGENT.md Stub](#agentmd-stub)
-10. [AI Agent Instructions](#ai-agent-instructions)
 
 ---
 
@@ -18,10 +17,25 @@
 
 Every task runs through three layers. Do not skip ahead to code.
 
-1. **Spec — agree on intent before touching anything.** Interview me up front to surface the *real* goal and the context you can't see — prompt the **decision I'm trying to make**, not the literal task I typed. Break the scope into small buckets with checkpoints. **State the load-bearing structural and logic decisions and get my explicit sign-off *before* you execute.** A wrong assumption caught at spec stage costs a sentence; caught after building it costs the build.
-2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`; a second-model pass (`/code-review`) on non-trivial output is worth the round-trip. External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
+1. **Spec — the interview must happen; its shape is yours.** Before touching anything, surface the *decision I'm actually making*, not the literal task I typed. Ask what you need to know — no more; how you ask is your call. Restate what you heard and get my explicit sign-off on the load-bearing decisions *before* you execute. A wrong assumption caught here costs a sentence; caught after building costs the build.
+
+   Write the outcome down as a **PRD**. A PRD is a portal, not a deliverable — where the conversation starts and the doc every POC refines. Minimum content, whatever the form:
+   - **Problem & goal** — what we're solving and why now
+   - **Go / no-go** — the 1–2 capabilities the product stands or falls on; usually module 0's riskiest assumption (e.g. "can a phone camera read the ID?"). Fails → stop
+   - **Out of scope** — what we're explicitly not doing
+   - **Modules** — the pieces to build, in order (see [*One module at a time*](#validate-before-you-build))
+   - **Open questions** — unknowns that don't block; never silently assumed
+
+   Every POC result updates the PRD; one that flips the go/no-go or a module's assumption is a spec change, not a footnote.
+2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`. When the work is done, propose `/code-review` and then `/release` — you never merge or release on your own (see [Required Safeguards](#required-safeguards-always--ask--never)). External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
 3. **Environment — the standing context.** This file primes every session. Critical-path protections (secrets, auth, schema, CI) are stated as **Always / Ask / Never** below and bind you as written. Where your tool offers a permission allow/ask/deny list, mirror them there so they are enforced and not merely requested.
 
+**Execution order — work the way a program runs, in this order, nothing skipped:**
+1. **Sequence** — do the PRD's modules in the order listed; never start module N+1 while module N is unproven.
+2. **Selection** — every POC is a branch: pass → next module, fail → back to the PRD as a spec change.
+3. **Iteration** — repeat POC → update PRD → next POC until the go/no-go is answered; the loop invariant is *everything built so far still works on its own*.
+4. **Verify** — assert before you move: a step is done when you ran the proof and saw it pass, not when you wrote that it did.
+
 > The model is brilliant at execution and blind to intent. You can outsource the typing; you cannot outsource the understanding. Surface assumptions — don't bury them.
 
 ---
@@ -29,16 +43,14 @@ Every task runs through three layers. Do not skip ahead to code.
 ## Communication Protocol
 
 ### Core Rules
-- **Spec before build**: Don't wait for ambiguity to block you — interview me up front to extract the real goal and the context you can't see. Prompt the *decision*, not the literal task. Restate what you heard before building
-- **Checkpoint before executing**: State the load-bearing structural and logic decisions and get my explicit sign-off *before* you write code. Never run ahead on an unverified assumption — flag it and stop
+- **Spec first, then checkpoint**: see [Operating Flow §1](#operating-flow). Never run ahead on an unverified assumption — flag it and stop
 - **Fact-Based**: Base all recommendations on verified, current information. Prefer external signal (a real run, a real source) over a confident guess
 - **Simplicity Advocate**: Call out overcomplications and suggest simpler alternatives
-- **Safety First**: Never modify critical systems without explicit understanding and approval
 
 ### User Profile
 - **Technical Level**: Non-coder but technically savvy
 - **Learning Style**: Understands concepts, needs executable instructions
-- **Expects**: Step-by-step guidance with clear explanations
+- **Expects**: Step-by-step guidance, ready-to-run commands, and the *why* behind each recommendation
 - **Comfortable with**: Command-line operations and scripts
 - **Builds a lot of web apps** — assume any UI work will be consumed on phones as well as desktop
 
@@ -49,6 +61,7 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 - **Always** identify affected files before making changes, and explain what will change and why
 - **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.amp/settings.json`
 - **Never** write secrets into the tree (`.env`/`*.env`, keys, credentials). They load from the environment at runtime; only a value-less `.env.example` is committed
+- **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/code-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
 ---
 
@@ -57,12 +70,12 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 ### Validate Before You Build
 
 - **POC everything first.** Before committing to a design, build a quick proof-of-concept (~15 min) that validates the core logic. Keep it stupidly simple — manual steps are fine, hardcoded values are fine, no tests needed yet
-- **POC scope:** Cover the happy path, 2-3 common edge cases, **and the riskiest assumption (see below) — not just the parts that are easy to check**. If those hold, the idea is sound
 - **Graduation criteria:** POC validates logic and covers most common scenarios → stop, design properly, then build with structure, tests, and error handling. Never ship the POC — rewrite it
-- **Aim the POC at the load-bearing claim — not the easy part.** Name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
+- **Aim the POC at the load-bearing claim — not the easy part.** Cover the happy path and 2-3 common edges, but name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
 - **Prove, don't assert — a POC's output is evidence you ran, not prose you wrote.** Every claim the design rests on must be something the spike actually exercised and you actually observed. **Measure anything you call "cheap," "fast," "constant," or "negligible"** — never state a cost you didn't time; a guessed number is a bug with a confident voice. State conclusions only at the confidence the evidence supports: if you didn't test it, say so plainly instead of rounding up to "it works." Better a small honest finding than a big-mouthed claim that measurement later falsifies
 - **The test must be able to FAIL — pre-flight check, not an afterthought.** Before trusting a POC's numbers, confirm three things: **(1) Can the test produce the negative?** A fixture you authored to contain the phenomenon you're testing can only confirm it — prefer real, uncrafted data over synthetic inputs; if synthetic is unavoidable, construct it so it *could* show no effect. **(2) Is the harness free of confounds?** A surprising or degenerate result is often an artifact of the setup, not a real finding — when output looks wrong, debug the test before believing it. **(3) Did the test actually exercise the variable?** If two conditions that should differ produce identical output, the variable isn't wired in — that's a finding, not noise. Run this checklist every time, especially when a result confirms what you hoped
-- **Build incrementally.** After POC graduates, break the work into small, independent modules. Focus on one at a time. Each piece must work on its own before integrating with the next
+- **One module at a time.** Build the PRD's modules in order, never several at once. Each module gets its own POC aimed at *its* riskiest assumption (module 0's is the go/no-go). A module is done when **(1)** it works on its own and **(2)** it connects to what's already built and the whole still works — both proven, not assumed. Only then start the next
+- **No fitting to pass.** Never narrow the input, move the threshold, or shrink the scope until a POC goes green. Report the failure and take it back to the PRD
 
 ### Dependency Hierarchy
 
@@ -106,6 +119,7 @@ Before adding any external dependency, all of these must be true:
 - Skipping POC validation for unproven ideas
 - POC-ing only the easy part while hand-waving the risky mechanism, or claiming a cost ("cheap"/"fast"/"constant") you never measured
 - Authoring a fixture/corpus that *guarantees* the result (a test that can't return the negative), or trusting a degenerate-looking number without auditing the harness for confounds — use real uncrafted data; the test must be able to fail
+- Fitting a POC to pass (narrowed input, moved threshold, shrunk scope) instead of reporting the failure; starting module N+1 while module N is unproven
 
 ---
 
@@ -269,9 +283,9 @@ Copy this to any project's AGENT.md. These are mandatory rules, not suggestions.
 ```markdown
 ## Dev Rules
 
-**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC. **Aim the spike at the riskiest assumption, not the easy part; prove, don't assert — measure anything you call "cheap"/"fast"/"constant," and claim only what the evidence supports (no big-mouthed conclusions measurement can falsify). The test must be able to FAIL: prefer real uncrafted data over a fixture you authored to contain the result, audit a degenerate number for harness confounds before believing it, and treat two should-differ conditions that match as a finding.**
+**Spec first.** Interview to find the decision, not the task; write a PRD with problem/goal, go/no-go, out-of-scope, modules, open questions. POCs refine it.
 
-**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
+**POC first, one module at a time.** Each module's POC targets its riskiest assumption (module 0 = go/no-go); the test must be able to fail; prove, don't assert — measure anything you call cheap/fast/constant. No fitting to pass. A module works on its own, then connects to what's built, before the next starts. Never ship the POC.
 
 **Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
 
@@ -283,17 +297,3 @@ Copy this to any project's AGENT.md. These are mandatory rules, not suggestions.
 
 For full development and testing standards, see `.amp/remember/AGENT_RULES.md`.
 ```
-
----
-
-## AI Agent Instructions
-
-When working with this user:
-1. **Interview before building** — extract the real goal and surface load-bearing decisions for sign-off before you execute (see [Operating Flow](#operating-flow))
-2. **Provide step-by-step** instructions with clear explanations
-3. **Include ready-to-run** scripts and commands
-4. **Explain the "why"** behind technical recommendations
-5. **Flag potential issues** before they become problems — name the assumption, don't bury it
-6. **Suggest simpler alternatives** when appropriate
-7. **Ask first** before touching auth, DB schema/migrations, CI, or settings; **never** commit secrets
-8. **Always identify** which files will be affected by changes

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/AGENT_RULES.md

@@ -10,7 +10,6 @@
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
 9. [CLAUDE.md Stub](#claudemd-stub)
-10. [AI Agent Instructions](#ai-agent-instructions)
 
 ---
 
@@ -18,10 +17,25 @@
 
 Every task runs through three layers. Do not skip ahead to code.
 
-1. **Spec — agree on intent before touching anything.** Interview me up front to surface the *real* goal and the context you can't see — prompt the **decision I'm trying to make**, not the literal task I typed. Break the scope into small buckets with checkpoints. **State the load-bearing structural and logic decisions and get my explicit sign-off *before* you execute.** A wrong assumption caught at spec stage costs a sentence; caught after building it costs the build.
-2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`; a second-model pass (`/code-review`) on non-trivial output is worth the round-trip. External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
+1. **Spec — the interview must happen; its shape is yours.** Before touching anything, surface the *decision I'm actually making*, not the literal task I typed. Ask what you need to know — no more; how you ask is your call. Restate what you heard and get my explicit sign-off on the load-bearing decisions *before* you execute. A wrong assumption caught here costs a sentence; caught after building costs the build.
+
+   Write the outcome down as a **PRD**. A PRD is a portal, not a deliverable — where the conversation starts and the doc every POC refines. Minimum content, whatever the form:
+   - **Problem & goal** — what we're solving and why now
+   - **Go / no-go** — the 1–2 capabilities the product stands or falls on; usually module 0's riskiest assumption (e.g. "can a phone camera read the ID?"). Fails → stop
+   - **Out of scope** — what we're explicitly not doing
+   - **Modules** — the pieces to build, in order (see [*One module at a time*](#validate-before-you-build))
+   - **Open questions** — unknowns that don't block; never silently assumed
+
+   Every POC result updates the PRD; one that flips the go/no-go or a module's assumption is a spec change, not a footnote.
+2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`. When the work is done, propose `/code-review` and then `/release` — you never merge or release on your own (see [Required Safeguards](#required-safeguards-always--ask--never)). External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
 3. **Environment — the standing context.** This file primes every session. Critical-path protections (secrets, auth, schema, CI) are stated as **Always / Ask / Never** below and bind you as written. Where your tool offers a permission allow/ask/deny list, mirror them there so they are enforced and not merely requested.
 
+**Execution order — work the way a program runs, in this order, nothing skipped:**
+1. **Sequence** — do the PRD's modules in the order listed; never start module N+1 while module N is unproven.
+2. **Selection** — every POC is a branch: pass → next module, fail → back to the PRD as a spec change.
+3. **Iteration** — repeat POC → update PRD → next POC until the go/no-go is answered; the loop invariant is *everything built so far still works on its own*.
+4. **Verify** — assert before you move: a step is done when you ran the proof and saw it pass, not when you wrote that it did.
+
 > The model is brilliant at execution and blind to intent. You can outsource the typing; you cannot outsource the understanding. Surface assumptions — don't bury them.
 
 ---
@@ -29,16 +43,14 @@ Every task runs through three layers. Do not skip ahead to code.
 ## Communication Protocol
 
 ### Core Rules
-- **Spec before build**: Don't wait for ambiguity to block you — interview me up front to extract the real goal and the context you can't see. Prompt the *decision*, not the literal task. Restate what you heard before building
-- **Checkpoint before executing**: State the load-bearing structural and logic decisions and get my explicit sign-off *before* you write code. Never run ahead on an unverified assumption — flag it and stop
+- **Spec first, then checkpoint**: see [Operating Flow §1](#operating-flow). Never run ahead on an unverified assumption — flag it and stop
 - **Fact-Based**: Base all recommendations on verified, current information. Prefer external signal (a real run, a real source) over a confident guess
 - **Simplicity Advocate**: Call out overcomplications and suggest simpler alternatives
-- **Safety First**: Never modify critical systems without explicit understanding and approval
 
 ### User Profile
 - **Technical Level**: Non-coder but technically savvy
 - **Learning Style**: Understands concepts, needs executable instructions
-- **Expects**: Step-by-step guidance with clear explanations
+- **Expects**: Step-by-step guidance, ready-to-run commands, and the *why* behind each recommendation
 - **Comfortable with**: Command-line operations and scripts
 - **Builds a lot of web apps** — assume any UI work will be consumed on phones as well as desktop
 
@@ -49,6 +61,7 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 - **Always** identify affected files before making changes, and explain what will change and why
 - **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.claude/settings.json`
 - **Never** write secrets into the tree (`.env`/`*.env`, keys, credentials). They load from the environment at runtime; only a value-less `.env.example` is committed
+- **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/code-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
 ---
 
@@ -57,12 +70,12 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 ### Validate Before You Build
 
 - **POC everything first.** Before committing to a design, build a quick proof-of-concept (~15 min) that validates the core logic. Keep it stupidly simple — manual steps are fine, hardcoded values are fine, no tests needed yet
-- **POC scope:** Cover the happy path, 2-3 common edge cases, **and the riskiest assumption (see below) — not just the parts that are easy to check**. If those hold, the idea is sound
 - **Graduation criteria:** POC validates logic and covers most common scenarios → stop, design properly, then build with structure, tests, and error handling. Never ship the POC — rewrite it
-- **Aim the POC at the load-bearing claim — not the easy part.** Name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
+- **Aim the POC at the load-bearing claim — not the easy part.** Cover the happy path and 2-3 common edges, but name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
 - **Prove, don't assert — a POC's output is evidence you ran, not prose you wrote.** Every claim the design rests on must be something the spike actually exercised and you actually observed. **Measure anything you call "cheap," "fast," "constant," or "negligible"** — never state a cost you didn't time; a guessed number is a bug with a confident voice. State conclusions only at the confidence the evidence supports: if you didn't test it, say so plainly instead of rounding up to "it works." Better a small honest finding than a big-mouthed claim that measurement later falsifies
 - **The test must be able to FAIL — pre-flight check, not an afterthought.** Before trusting a POC's numbers, confirm three things: **(1) Can the test produce the negative?** A fixture you authored to contain the phenomenon you're testing can only confirm it — prefer real, uncrafted data over synthetic inputs; if synthetic is unavoidable, construct it so it *could* show no effect. **(2) Is the harness free of confounds?** A surprising or degenerate result is often an artifact of the setup, not a real finding — when output looks wrong, debug the test before believing it. **(3) Did the test actually exercise the variable?** If two conditions that should differ produce identical output, the variable isn't wired in — that's a finding, not noise. Run this checklist every time, especially when a result confirms what you hoped
-- **Build incrementally.** After POC graduates, break the work into small, independent modules. Focus on one at a time. Each piece must work on its own before integrating with the next
+- **One module at a time.** Build the PRD's modules in order, never several at once. Each module gets its own POC aimed at *its* riskiest assumption (module 0's is the go/no-go). A module is done when **(1)** it works on its own and **(2)** it connects to what's already built and the whole still works — both proven, not assumed. Only then start the next
+- **No fitting to pass.** Never narrow the input, move the threshold, or shrink the scope until a POC goes green. Report the failure and take it back to the PRD
 
 ### Dependency Hierarchy
 
@@ -106,6 +119,7 @@ Before adding any external dependency, all of these must be true:
 - Skipping POC validation for unproven ideas
 - POC-ing only the easy part while hand-waving the risky mechanism, or claiming a cost ("cheap"/"fast"/"constant") you never measured
 - Authoring a fixture/corpus that *guarantees* the result (a test that can't return the negative), or trusting a degenerate-looking number without auditing the harness for confounds — use real uncrafted data; the test must be able to fail
+- Fitting a POC to pass (narrowed input, moved threshold, shrunk scope) instead of reporting the failure; starting module N+1 while module N is unproven
 
 ---
 
@@ -269,9 +283,9 @@ Copy this to any project's CLAUDE.md. These are mandatory rules, not suggestions
 ```markdown
 ## Dev Rules
 
-**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC. **Aim the spike at the riskiest assumption, not the easy part; prove, don't assert — measure anything you call "cheap"/"fast"/"constant," and claim only what the evidence supports (no big-mouthed conclusions measurement can falsify). The test must be able to FAIL: prefer real uncrafted data over a fixture you authored to contain the result, audit a degenerate number for harness confounds before believing it, and treat two should-differ conditions that match as a finding.**
+**Spec first.** Interview to find the decision, not the task; write a PRD with problem/goal, go/no-go, out-of-scope, modules, open questions. POCs refine it.
 
-**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
+**POC first, one module at a time.** Each module's POC targets its riskiest assumption (module 0 = go/no-go); the test must be able to fail; prove, don't assert — measure anything you call cheap/fast/constant. No fitting to pass. A module works on its own, then connects to what's built, before the next starts. Never ship the POC.
 
 **Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
 
@@ -283,17 +297,3 @@ Copy this to any project's CLAUDE.md. These are mandatory rules, not suggestions
 
 For full development and testing standards, see `.claude/remember/AGENT_RULES.md`.
 ```
-
----
-
-## AI Agent Instructions
-
-When working with this user:
-1. **Interview before building** — extract the real goal and surface load-bearing decisions for sign-off before you execute (see [Operating Flow](#operating-flow))
-2. **Provide step-by-step** instructions with clear explanations
-3. **Include ready-to-run** scripts and commands
-4. **Explain the "why"** behind technical recommendations
-5. **Flag potential issues** before they become problems — name the assumption, don't bury it
-6. **Suggest simpler alternatives** when appropriate
-7. **Ask first** before touching auth, DB schema/migrations, CI, or settings; **never** commit secrets
-8. **Always identify** which files will be affected by changes

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/AGENT_RULES.md

@@ -10,7 +10,6 @@
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
 9. [AGENTS.md Stub](#agentsmd-stub)
-10. [AI Agent Instructions](#ai-agent-instructions)
 
 ---
 
@@ -18,10 +17,25 @@
 
 Every task runs through three layers. Do not skip ahead to code.
 
-1. **Spec — agree on intent before touching anything.** Interview me up front to surface the *real* goal and the context you can't see — prompt the **decision I'm trying to make**, not the literal task I typed. Break the scope into small buckets with checkpoints. **State the load-bearing structural and logic decisions and get my explicit sign-off *before* you execute.** A wrong assumption caught at spec stage costs a sentence; caught after building it costs the build.
-2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`; a second-model pass (`/code-review`) on non-trivial output is worth the round-trip. External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
+1. **Spec — the interview must happen; its shape is yours.** Before touching anything, surface the *decision I'm actually making*, not the literal task I typed. Ask what you need to know — no more; how you ask is your call. Restate what you heard and get my explicit sign-off on the load-bearing decisions *before* you execute. A wrong assumption caught here costs a sentence; caught after building costs the build.
+
+   Write the outcome down as a **PRD**. A PRD is a portal, not a deliverable — where the conversation starts and the doc every POC refines. Minimum content, whatever the form:
+   - **Problem & goal** — what we're solving and why now
+   - **Go / no-go** — the 1–2 capabilities the product stands or falls on; usually module 0's riskiest assumption (e.g. "can a phone camera read the ID?"). Fails → stop
+   - **Out of scope** — what we're explicitly not doing
+   - **Modules** — the pieces to build, in order (see [*One module at a time*](#validate-before-you-build))
+   - **Open questions** — unknowns that don't block; never silently assumed
+
+   Every POC result updates the PRD; one that flips the go/no-go or a module's assumption is a spec change, not a footnote.
+2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`. When the work is done, propose `/code-review` and then `/release` — you never merge or release on your own (see [Required Safeguards](#required-safeguards-always--ask--never)). External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
 3. **Environment — the standing context.** This file primes every session. Critical-path protections (secrets, auth, schema, CI) are stated as **Always / Ask / Never** below and bind you as written. Where your tool offers a permission allow/ask/deny list, mirror them there so they are enforced and not merely requested.
 
+**Execution order — work the way a program runs, in this order, nothing skipped:**
+1. **Sequence** — do the PRD's modules in the order listed; never start module N+1 while module N is unproven.
+2. **Selection** — every POC is a branch: pass → next module, fail → back to the PRD as a spec change.
+3. **Iteration** — repeat POC → update PRD → next POC until the go/no-go is answered; the loop invariant is *everything built so far still works on its own*.
+4. **Verify** — assert before you move: a step is done when you ran the proof and saw it pass, not when you wrote that it did.
+
 > The model is brilliant at execution and blind to intent. You can outsource the typing; you cannot outsource the understanding. Surface assumptions — don't bury them.
 
 ---
@@ -29,16 +43,14 @@ Every task runs through three layers. Do not skip ahead to code.
 ## Communication Protocol
 
 ### Core Rules
-- **Spec before build**: Don't wait for ambiguity to block you — interview me up front to extract the real goal and the context you can't see. Prompt the *decision*, not the literal task. Restate what you heard before building
-- **Checkpoint before executing**: State the load-bearing structural and logic decisions and get my explicit sign-off *before* you write code. Never run ahead on an unverified assumption — flag it and stop
+- **Spec first, then checkpoint**: see [Operating Flow §1](#operating-flow). Never run ahead on an unverified assumption — flag it and stop
 - **Fact-Based**: Base all recommendations on verified, current information. Prefer external signal (a real run, a real source) over a confident guess
 - **Simplicity Advocate**: Call out overcomplications and suggest simpler alternatives
-- **Safety First**: Never modify critical systems without explicit understanding and approval
 
 ### User Profile
 - **Technical Level**: Non-coder but technically savvy
 - **Learning Style**: Understands concepts, needs executable instructions
-- **Expects**: Step-by-step guidance with clear explanations
+- **Expects**: Step-by-step guidance, ready-to-run commands, and the *why* behind each recommendation
 - **Comfortable with**: Command-line operations and scripts
 - **Builds a lot of web apps** — assume any UI work will be consumed on phones as well as desktop
 
@@ -49,6 +61,7 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 - **Always** identify affected files before making changes, and explain what will change and why
 - **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.factory/settings.json`
 - **Never** write secrets into the tree (`.env`/`*.env`, keys, credentials). They load from the environment at runtime; only a value-less `.env.example` is committed
+- **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/code-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
 ---
 
@@ -57,12 +70,12 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 ### Validate Before You Build
 
 - **POC everything first.** Before committing to a design, build a quick proof-of-concept (~15 min) that validates the core logic. Keep it stupidly simple — manual steps are fine, hardcoded values are fine, no tests needed yet
-- **POC scope:** Cover the happy path, 2-3 common edge cases, **and the riskiest assumption (see below) — not just the parts that are easy to check**. If those hold, the idea is sound
 - **Graduation criteria:** POC validates logic and covers most common scenarios → stop, design properly, then build with structure, tests, and error handling. Never ship the POC — rewrite it
-- **Aim the POC at the load-bearing claim — not the easy part.** Name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
+- **Aim the POC at the load-bearing claim — not the easy part.** Cover the happy path and 2-3 common edges, but name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
 - **Prove, don't assert — a POC's output is evidence you ran, not prose you wrote.** Every claim the design rests on must be something the spike actually exercised and you actually observed. **Measure anything you call "cheap," "fast," "constant," or "negligible"** — never state a cost you didn't time; a guessed number is a bug with a confident voice. State conclusions only at the confidence the evidence supports: if you didn't test it, say so plainly instead of rounding up to "it works." Better a small honest finding than a big-mouthed claim that measurement later falsifies
 - **The test must be able to FAIL — pre-flight check, not an afterthought.** Before trusting a POC's numbers, confirm three things: **(1) Can the test produce the negative?** A fixture you authored to contain the phenomenon you're testing can only confirm it — prefer real, uncrafted data over synthetic inputs; if synthetic is unavoidable, construct it so it *could* show no effect. **(2) Is the harness free of confounds?** A surprising or degenerate result is often an artifact of the setup, not a real finding — when output looks wrong, debug the test before believing it. **(3) Did the test actually exercise the variable?** If two conditions that should differ produce identical output, the variable isn't wired in — that's a finding, not noise. Run this checklist every time, especially when a result confirms what you hoped
-- **Build incrementally.** After POC graduates, break the work into small, independent modules. Focus on one at a time. Each piece must work on its own before integrating with the next
+- **One module at a time.** Build the PRD's modules in order, never several at once. Each module gets its own POC aimed at *its* riskiest assumption (module 0's is the go/no-go). A module is done when **(1)** it works on its own and **(2)** it connects to what's already built and the whole still works — both proven, not assumed. Only then start the next
+- **No fitting to pass.** Never narrow the input, move the threshold, or shrink the scope until a POC goes green. Report the failure and take it back to the PRD
 
 ### Dependency Hierarchy
 
@@ -106,6 +119,7 @@ Before adding any external dependency, all of these must be true:
 - Skipping POC validation for unproven ideas
 - POC-ing only the easy part while hand-waving the risky mechanism, or claiming a cost ("cheap"/"fast"/"constant") you never measured
 - Authoring a fixture/corpus that *guarantees* the result (a test that can't return the negative), or trusting a degenerate-looking number without auditing the harness for confounds — use real uncrafted data; the test must be able to fail
+- Fitting a POC to pass (narrowed input, moved threshold, shrunk scope) instead of reporting the failure; starting module N+1 while module N is unproven
 
 ---
 
@@ -269,9 +283,9 @@ Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions
 ```markdown
 ## Dev Rules
 
-**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC. **Aim the spike at the riskiest assumption, not the easy part; prove, don't assert — measure anything you call "cheap"/"fast"/"constant," and claim only what the evidence supports (no big-mouthed conclusions measurement can falsify). The test must be able to FAIL: prefer real uncrafted data over a fixture you authored to contain the result, audit a degenerate number for harness confounds before believing it, and treat two should-differ conditions that match as a finding.**
+**Spec first.** Interview to find the decision, not the task; write a PRD with problem/goal, go/no-go, out-of-scope, modules, open questions. POCs refine it.
 
-**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
+**POC first, one module at a time.** Each module's POC targets its riskiest assumption (module 0 = go/no-go); the test must be able to fail; prove, don't assert — measure anything you call cheap/fast/constant. No fitting to pass. A module works on its own, then connects to what's built, before the next starts. Never ship the POC.
 
 **Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
 
@@ -283,17 +297,3 @@ Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions
 
 For full development and testing standards, see `.factory/remember/AGENT_RULES.md`.
 ```
-
----
-
-## AI Agent Instructions
-
-When working with this user:
-1. **Interview before building** — extract the real goal and surface load-bearing decisions for sign-off before you execute (see [Operating Flow](#operating-flow))
-2. **Provide step-by-step** instructions with clear explanations
-3. **Include ready-to-run** scripts and commands
-4. **Explain the "why"** behind technical recommendations
-5. **Flag potential issues** before they become problems — name the assumption, don't bury it
-6. **Suggest simpler alternatives** when appropriate
-7. **Ask first** before touching auth, DB schema/migrations, CI, or settings; **never** commit secrets
-8. **Always identify** which files will be affected by changes

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/AGENT_RULES.md

@@ -10,7 +10,6 @@
 7. [Development Workflow](#development-workflow)
 8. [Twelve-Factor Checklist](#twelve-factor-checklist)
 9. [AGENTS.md Stub](#agentsmd-stub)
-10. [AI Agent Instructions](#ai-agent-instructions)
 
 ---
 
@@ -18,10 +17,25 @@
 
 Every task runs through three layers. Do not skip ahead to code.
 
-1. **Spec — agree on intent before touching anything.** Interview me up front to surface the *real* goal and the context you can't see — prompt the **decision I'm trying to make**, not the literal task I typed. Break the scope into small buckets with checkpoints. **State the load-bearing structural and logic decisions and get my explicit sign-off *before* you execute.** A wrong assumption caught at spec stage costs a sentence; caught after building it costs the build.
-2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`; a second-model pass (`/code-review`) on non-trivial output is worth the round-trip. External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
+1. **Spec — the interview must happen; its shape is yours.** Before touching anything, surface the *decision I'm actually making*, not the literal task I typed. Ask what you need to know — no more; how you ask is your call. Restate what you heard and get my explicit sign-off on the load-bearing decisions *before* you execute. A wrong assumption caught here costs a sentence; caught after building costs the build.
+
+   Write the outcome down as a **PRD**. A PRD is a portal, not a deliverable — where the conversation starts and the doc every POC refines. Minimum content, whatever the form:
+   - **Problem & goal** — what we're solving and why now
+   - **Go / no-go** — the 1–2 capabilities the product stands or falls on; usually module 0's riskiest assumption (e.g. "can a phone camera read the ID?"). Fails → stop
+   - **Out of scope** — what we're explicitly not doing
+   - **Modules** — the pieces to build, in order (see [*One module at a time*](#validate-before-you-build))
+   - **Open questions** — unknowns that don't block; never silently assumed
+
+   Every POC result updates the PRD; one that flips the go/no-go or a module's assumption is a spec change, not a footnote.
+2. **Verify — define "good" up front, then prove it.** Write down what success looks like *before* changing code. Prove with measurement and tests, not assertion (see [*Prove, don't assert*](#validate-before-you-build)). Gate security-sensitive work with `/security` and pre-deploy with `/ship`. When the work is done, propose `/code-review` and then `/release` — you never merge or release on your own (see [Required Safeguards](#required-safeguards-always--ask--never)). External signal — a real test run, a real deploy, a gold-standard reference — beats a confident paragraph every time.
 3. **Environment — the standing context.** This file primes every session. Critical-path protections (secrets, auth, schema, CI) are stated as **Always / Ask / Never** below and bind you as written. Where your tool offers a permission allow/ask/deny list, mirror them there so they are enforced and not merely requested.
 
+**Execution order — work the way a program runs, in this order, nothing skipped:**
+1. **Sequence** — do the PRD's modules in the order listed; never start module N+1 while module N is unproven.
+2. **Selection** — every POC is a branch: pass → next module, fail → back to the PRD as a spec change.
+3. **Iteration** — repeat POC → update PRD → next POC until the go/no-go is answered; the loop invariant is *everything built so far still works on its own*.
+4. **Verify** — assert before you move: a step is done when you ran the proof and saw it pass, not when you wrote that it did.
+
 > The model is brilliant at execution and blind to intent. You can outsource the typing; you cannot outsource the understanding. Surface assumptions — don't bury them.
 
 ---
@@ -29,16 +43,14 @@ Every task runs through three layers. Do not skip ahead to code.
 ## Communication Protocol
 
 ### Core Rules
-- **Spec before build**: Don't wait for ambiguity to block you — interview me up front to extract the real goal and the context you can't see. Prompt the *decision*, not the literal task. Restate what you heard before building
-- **Checkpoint before executing**: State the load-bearing structural and logic decisions and get my explicit sign-off *before* you write code. Never run ahead on an unverified assumption — flag it and stop
+- **Spec first, then checkpoint**: see [Operating Flow §1](#operating-flow). Never run ahead on an unverified assumption — flag it and stop
 - **Fact-Based**: Base all recommendations on verified, current information. Prefer external signal (a real run, a real source) over a confident guess
 - **Simplicity Advocate**: Call out overcomplications and suggest simpler alternatives
-- **Safety First**: Never modify critical systems without explicit understanding and approval
 
 ### User Profile
 - **Technical Level**: Non-coder but technically savvy
 - **Learning Style**: Understands concepts, needs executable instructions
-- **Expects**: Step-by-step guidance with clear explanations
+- **Expects**: Step-by-step guidance, ready-to-run commands, and the *why* behind each recommendation
 - **Comfortable with**: Command-line operations and scripts
 - **Builds a lot of web apps** — assume any UI work will be consumed on phones as well as desktop
 
@@ -49,6 +61,7 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 - **Always** identify affected files before making changes, and explain what will change and why
 - **Ask first** — stop and get explicit sign-off — before modifying authentication systems, database schema or migrations, CI workflows, or `.opencode/settings.json`
 - **Never** write secrets into the tree (`.env`/`*.env`, keys, credentials). They load from the environment at runtime; only a value-less `.env.example` is committed
+- **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/code-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
 ---
 
@@ -57,12 +70,12 @@ Not courtesies. These bind you as written, whether or not your tool enforces the
 ### Validate Before You Build
 
 - **POC everything first.** Before committing to a design, build a quick proof-of-concept (~15 min) that validates the core logic. Keep it stupidly simple — manual steps are fine, hardcoded values are fine, no tests needed yet
-- **POC scope:** Cover the happy path, 2-3 common edge cases, **and the riskiest assumption (see below) — not just the parts that are easy to check**. If those hold, the idea is sound
 - **Graduation criteria:** POC validates logic and covers most common scenarios → stop, design properly, then build with structure, tests, and error handling. Never ship the POC — rewrite it
-- **Aim the POC at the load-bearing claim — not the easy part.** Name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
+- **Aim the POC at the load-bearing claim — not the easy part.** Cover the happy path and 2-3 common edges, but name the riskiest assumption first (does the cheap path actually run cheap? does the library really do X? does the perf hold?), then point the spike straight at *that*. A POC that confirms the happy-path shape while hand-waving the risky mechanism is theater. If you catch yourself writing "production would do X" instead of *doing* X in the spike, the POC has not validated X — go do X
 - **Prove, don't assert — a POC's output is evidence you ran, not prose you wrote.** Every claim the design rests on must be something the spike actually exercised and you actually observed. **Measure anything you call "cheap," "fast," "constant," or "negligible"** — never state a cost you didn't time; a guessed number is a bug with a confident voice. State conclusions only at the confidence the evidence supports: if you didn't test it, say so plainly instead of rounding up to "it works." Better a small honest finding than a big-mouthed claim that measurement later falsifies
 - **The test must be able to FAIL — pre-flight check, not an afterthought.** Before trusting a POC's numbers, confirm three things: **(1) Can the test produce the negative?** A fixture you authored to contain the phenomenon you're testing can only confirm it — prefer real, uncrafted data over synthetic inputs; if synthetic is unavoidable, construct it so it *could* show no effect. **(2) Is the harness free of confounds?** A surprising or degenerate result is often an artifact of the setup, not a real finding — when output looks wrong, debug the test before believing it. **(3) Did the test actually exercise the variable?** If two conditions that should differ produce identical output, the variable isn't wired in — that's a finding, not noise. Run this checklist every time, especially when a result confirms what you hoped
-- **Build incrementally.** After POC graduates, break the work into small, independent modules. Focus on one at a time. Each piece must work on its own before integrating with the next
+- **One module at a time.** Build the PRD's modules in order, never several at once. Each module gets its own POC aimed at *its* riskiest assumption (module 0's is the go/no-go). A module is done when **(1)** it works on its own and **(2)** it connects to what's already built and the whole still works — both proven, not assumed. Only then start the next
+- **No fitting to pass.** Never narrow the input, move the threshold, or shrink the scope until a POC goes green. Report the failure and take it back to the PRD
 
 ### Dependency Hierarchy
 
@@ -106,6 +119,7 @@ Before adding any external dependency, all of these must be true:
 - Skipping POC validation for unproven ideas
 - POC-ing only the easy part while hand-waving the risky mechanism, or claiming a cost ("cheap"/"fast"/"constant") you never measured
 - Authoring a fixture/corpus that *guarantees* the result (a test that can't return the negative), or trusting a degenerate-looking number without auditing the harness for confounds — use real uncrafted data; the test must be able to fail
+- Fitting a POC to pass (narrowed input, moved threshold, shrunk scope) instead of reporting the failure; starting module N+1 while module N is unproven
 
 ---
 
@@ -269,9 +283,9 @@ Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions
 ```markdown
 ## Dev Rules
 
-**POC first.** Always validate logic with a ~15min proof-of-concept before building. Cover happy path + common edges. POC works → design properly → build with tests. Never ship the POC. **Aim the spike at the riskiest assumption, not the easy part; prove, don't assert — measure anything you call "cheap"/"fast"/"constant," and claim only what the evidence supports (no big-mouthed conclusions measurement can falsify). The test must be able to FAIL: prefer real uncrafted data over a fixture you authored to contain the result, audit a degenerate number for harness confounds before believing it, and treat two should-differ conditions that match as a finding.**
+**Spec first.** Interview to find the decision, not the task; write a PRD with problem/goal, go/no-go, out-of-scope, modules, open questions. POCs refine it.
 
-**Build incrementally.** Break work into small independent modules. One piece at a time, each must work on its own before integrating.
+**POC first, one module at a time.** Each module's POC targets its riskiest assumption (module 0 = go/no-go); the test must be able to fail; prove, don't assert — measure anything you call cheap/fast/constant. No fitting to pass. A module works on its own, then connects to what's built, before the next starts. Never ship the POC.
 
 **Dependency hierarchy — follow strictly:** vanilla language → standard library → external (only when stdlib can't do it in <100 lines). External deps must be maintained, lightweight, and widely adopted. Exception: always use vetted libraries for security-critical code (crypto, auth, sanitization).
 
@@ -283,17 +297,3 @@ Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions
 
 For full development and testing standards, see `.opencode/remember/AGENT_RULES.md`.
 ```
-
----
-
-## AI Agent Instructions
-
-When working with this user:
-1. **Interview before building** — extract the real goal and surface load-bearing decisions for sign-off before you execute (see [Operating Flow](#operating-flow))
-2. **Provide step-by-step** instructions with clear explanations
-3. **Include ready-to-run** scripts and commands
-4. **Explain the "why"** behind technical recommendations
-5. **Flag potential issues** before they become problems — name the assumption, don't bury it
-6. **Suggest simpler alternatives** when appropriate
-7. **Ask first** before touching auth, DB schema/migrations, CI, or settings; **never** commit secrets
-8. **Always identify** which files will be affected by changes

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`