liteagents 3.6.0 → 3.8.0

package/packages/ampcode/skills/release/SKILL.md

@@ -126,19 +126,49 @@ confirmed in Phase 0.5.
   summarize, escalate. Do not weigh it yourself.
 - **All clean** → continue.
 
-## Phase 2 — Docs sweep
-Update what this feature actually changed, wherever those docs live in this
-project — match each file's existing format, touch nothing unrelated. Use
-`docs/index.md` when the project has one to find what exists.
-
-- **CHANGELOG.md** — new entry.
-- **README.md** — only if user-facing usage changed.
+## Phase 2 — Docs sweep (required — no skipping, no sampling)
+Update what this branch changed, wherever those docs live in this project —
+match each file's existing format, touch nothing unrelated. Use
+`docs/index.md` when the project has one to find what exists. **All three
+passes run on every release**; the size of the branch or the change never
+cuts one.
+
+1. **List every change.** Read `git log --format='%h %s%n%b'
+   origin/main..HEAD` — the bodies, not just the subjects — and the diff.
+   Write one line per user-visible change: feature, command, flag, behaviour,
+   fix, dependency bump. A subject is a summary; the body is the list, and a
+   sweep built from subjects drops whatever only a body mentions.
+2. **CHANGELOG.md** — a new entry holding every line from pass 1, each under
+   the heading the file already uses for its kind (Added / Changed / Fixed /
+   Security). A new capability is **Added** even when it shipped in a `fix:`
+   commit. Then check it back: every pass-1 line maps to an entry, and the
+   semver level in Phase 3 agrees with the headings (an Added entry means at
+   least minor).
+3. **Grep for stale text.** For every string the diff removed or replaced
+   that a reader might have copied — a command line, flag, file name, recipe,
+   env var, printed message — search the docs for the old form:
+   `grep -rnF "<old string>" --include='*.md' .` (past CHANGELOG entries are
+   history; leave them). Every other hit is stale **because of this branch** —
+   update it. "It was already stale before this branch" is a claim: prove it
+   with `git show $(git merge-base origin/main HEAD):<source path>`. If the
+   base code already disagreed with the doc, report it as out of scope;
+   otherwise it is yours to fix.
+
+Then judge each of these against the pass-1 list:
+- **README.md** — if user-facing usage changed.
 - **PRD** — the feature's entry / status.
 - **Guide / context docs** — the project's standing context.
 - **Findings / learnings** — where the project keeps them.
 - **Any other frequently-updated doc** this change makes stale.
 
-If a doc needs no change, **say so** rather than editing it for its own sake.
+Report **one row per doc**: file · changed / no change · the evidence (the
+grep or diff you ran). A "no change" with no evidence is a skip, and a skip
+fails this phase — it is not a pass. If a doc truly needs no change, say so
+with the evidence rather than editing it for its own sake.
+
+**The sweep is the worker's job, start to finish.** The orchestrator checks
+the report; it does not redo or patch the sweep. A gap it finds goes back to
+the worker, and it counts as a failed sweep, not a small follow-up.
 
 ## Phase 3 — Cut (local only)
 1. **Version bump** — pick the semver level from the change (patch / minor /

package/packages/ampcode/skills/remember/AGENT_RULES.md

@@ -60,7 +60,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** put secrets in the tree — see [Security & Robustness Invariants §1](#security--robustness-invariants)
 - **Never** commit to `main`. Commit to a new branch (name doesn't matter), then propose `/branch-review` followed by `/release`; merging and releasing are my call, made by name — "approve", "good", or "go" on a draft is not that call
 
 ---
@@ -113,6 +113,7 @@ Before adding any external dependency, all of these must be true:
 - **Containerize only when necessary.** Start with a virtualenv or bare metal. Docker adds value for deployment parity and isolation — not for running a script
 - **Responsive web UI is mandatory in dev projects.** Any web UI must be usable on mobile by default — fluid layouts, viewport meta tag, breakpoints for narrow screens, no horizontal scroll. Test in DevTools device emulation before declaring a UI task done. POCs are exempt (validate the idea first), but the moment a POC graduates to a real project this becomes a hard requirement
 - **Surgical changes only.** Touch what the task requires; nothing else. Don't "improve" adjacent code, comments, or formatting. Match existing style even if you'd do it differently. Only clean up orphans your own change created. Dead code, nits, bugs you pass on the way: if it's inside or affects the code you're already changing, and the fix changes no behavior, fix it and say so. Otherwise report it — say what it costs to leave it. "It would be nicer" is not a cost. Every changed line traces to the request or to a fix you named
+- **Meter the whole unit of work.** Usage and cost sum every call a unit of work makes; the last call's number is never the total, and one unpriced call makes the total unknown, not zero
 
 ### Red Flags — Stop and Flag These
 - Over-engineering simple problems
@@ -144,7 +145,7 @@ particular toolchain spells it.
 
 - **After the design stabilizes, not during exploration.** Do not test a prototype — you will write tests for code you delete tomorrow. First make it work (POC), then make it right (tests), then make it fast
 - **Tests first when you already know the contract.** Pure functions, algorithms, parsers, validators, data transformations — write the test, watch it fail, then implement. When you are still discovering the interface, that same discipline produces churn and false confidence
-- **Write tests for bugs.** Every fix ships a regression test that fails before the fix and passes after — the highest-value test there is
+- **Write tests for bugs.** Every fix ships a regression test — the highest-value test there is
 - **Write tests before refactoring.** Characterization tests lock in current behavior first, then change the code
 - **Write tests when the code has users.** Called by other modules or exposed externally means it needs tests; a helper serving one caller does not need its own file
 - **Do not test glue code.** Something that only wires A to B to C is covered at the integration level
@@ -152,7 +153,7 @@ particular toolchain spells it.
 ### What makes a good test
 
 - **Tests real behavior.** Call the public interface, assert on observable output. Never reach into internals
-- **Fails for the right reason.** It breaks when the feature breaks, not when the implementation moves
+- **Fails for the right reason — prove it.** It breaks when the feature breaks, not when the implementation moves. Revert the fix (or switch the check off), run the test, watch it go red, then restore it: a test you have never seen fail is unverified, however right it reads
 - **Reads like a spec.** Someone new to the code should learn what the feature does by reading it
 - **Self-contained.** Sets up its own state, runs, cleans up. No ordering dependencies, and no reliance on project directories, user config, or ambient environment
 - **Deterministic.** Flaky tests erode trust. A dependency on timing, network, or global state is a defect in the test
@@ -186,15 +187,22 @@ Throwaway POCs are exempt while you validate logic (per **POC first** above) —
 1. **No secrets in the repo.** Keys, tokens, and credentials load from the environment / a secret store at runtime — never hardcoded, never logged. `.env` is gitignored; only a value-less `.env.example` is committed. Scan history before trusting a repo. One leaked key is a breached database or a runaway bill.
 2. **Scope every data access to its owner.** Each record read or written is constrained to the requesting principal — via DB-level rules (RLS / row policies) and/or an application-layer ownership check. Never trust a client-supplied id without a gate. If the storage layer offers row-level policies, enabling them is not optional, and "on but too broad" still fails.
 3. **Bound every reachable endpoint.** Rate-limit public routes AND authenticated mutation/write routes AND abuse-prone inbound paths (mail, webhooks). An unbounded route is a free DoS and bill amplifier — a script in a loop should not be able to take the service down.
-4. **Handle the unhappy path.** Every IO / network / DB / third-party call has an explicit failure path. Nothing fails silently. Internal detail (stack traces, queries, secrets) never reaches the client. Async/background work carries its own catch.
+4. **Handle the unhappy path.** Every IO / network / DB / third-party call has an explicit failure path. Nothing fails silently. Internal detail (stack traces, queries, secrets) never reaches the client. Async/background work carries its own catch. A warning nobody has to act on is not a check — either it halts / reds the run, or it is counted and surfaced where a human reads it. Record what you asked a dependency for and what you got back. Read and record the stop/finish reason of every external or model call — a cut-off answer (length/max_tokens) is never the same as no answer.
 5. **Authorization is not authentication.** "Logged in" never implies "allowed". Every state-changing or privileged action checks ownership AND role/permission. If swapping an id in a request would expose or mutate someone else's data, it's a bug — return 403.
 6. **Data access scales.** No queries inside loops, no per-render repeated round-trips, indexes on every filtered/joined column. Code that's fine at 10 users and collapses at 1,000 is a latent outage.
 
-Also hold the line on: input validation at every trust boundary (untrusted uploads, inbound mail, webhooks, and spoofable headers like `X-Forwarded-For` — trust them only behind a vetted proxy); parameterized queries (never string-built SQL); vetted libraries for crypto / auth / sanitization (never roll your own); and least-privilege binding (loopback, not `0.0.0.0`, unless the port is deliberately public).
+Also hold the line on:
+
+- **Validate input at every trust boundary.** Untrusted uploads, inbound mail, webhooks, and spoofable headers like `X-Forwarded-For` — trust the latter only behind a vetted proxy.
+- **Model output is untrusted input too.** Validate it against a schema and key every decision on a typed field — never regex-parse the model's prose for a number, id, or verdict.
+- **Guard lookups keyed by an external string.** Look the key up only among the map's own entries, never inherited ones — an inherited member can otherwise answer for a key the map never had, so "not found → throw" is bypassed.
+- **Parameterize every query.** Never string-build SQL.
+- **Use vetted libraries for security-critical code** — see [External Dependency Checklist](#external-dependency-checklist).
+- **Bind least-privilege.** Loopback, not `0.0.0.0`, unless the port is deliberately public.
 
 **Verify at two moments, not one.**
 - **While building** — this list shapes the code as it's written.
-- **Before deploy/merge** — run **`/branch-review`**, whose second stage runs **`/security`** in full; `/release` then runs **`/ship`** as the mechanical pre-deploy gate. A Critical/High finding blocks the ship; lower-severity findings get logged and triaged, not silently shipped. Proactively remind the user to run them whenever a change touches auth, data access, endpoints, secrets, or untrusted input.
+- **Before deploy/merge** — see [Operating Flow §2](#operating-flow). A Critical/High finding blocks the ship; lower-severity findings get logged and triaged, not silently shipped. Proactively remind the user to run `/branch-review` whenever a change touches auth, data access, endpoints, secrets, or untrusted input.
 
 ---
 

package/packages/ampcode/skills/security/SKILL.md

@@ -23,9 +23,12 @@ These show up in nearly every quickly-built app regardless of stack:
 
 1. **Secrets in the repo.** Tokens / API keys / `.env` files committed to
    tracked files or anywhere in git history. Verify `.env` is gitignored and
-   only a value-less `.env.example` is tracked; scan history (`git log -p`,
-   `git grep`) for leaked keys. Secrets must load from env / a secret store at
-   runtime — never hardcoded, never logged.
+   only a value-less `.env.example` is tracked. Scan ALL history, every
+   branch — a range or target never narrows this — with:
+   `git log --all -p | grep -nE '(sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{30,}|xox[abprs]-[A-Za-z0-9-]{10,}|AIza[0-9A-Za-z_-]{35}|-----BEGIN [A-Z ]*PRIVATE KEY)'`
+   plus any key shape specific to this project's providers. Report each hit
+   as real or a known test fixture. Secrets must load from env / a secret
+   store at runtime — never hardcoded, never logged.
 2. **Data-access authorization (tenant isolation).** Every record read or
    written must be scoped to the requesting principal — via DB-level rules
    (RLS / row policies) and/or application-layer ownership checks. Flag any

package/packages/claude/plugins/live-canvas-marketplace/plugins/live-canvas-channel/package-lock.json

@@ -585,9 +585,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.13.0",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.0.tgz",
-      "integrity": "sha512-jhunvfHWxd7J5EFfSgH4xsYJzSe/lfqbUCxiyyeaQasUsXeEHXtzVid+7EOGByc5JnFa23SSFL3Y2RV/z1T+eQ==",
+      "version": "4.13.7",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.7.tgz",
+      "integrity": "sha512-c8/gF9ac8Y78/agExVocyLevgR+JlpNB444Py0FSX8pJoPdYUfUzRcXtYEYGwt6l19qIlVZPN5Mfsw9jFShmQQ==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"

package/packages/claude/skills/branch-review/SKILL.md

@@ -140,6 +140,13 @@ governs **stage 1 only**:
 - **high / max** — broader coverage; uncertain findings are allowed, but each
   must be labelled uncertain.
 
+**No shortcuts.** The level decides how many findings you report, never which
+checks you run. Every check this file calls required runs at every level —
+never cut or sample one "given the effort level", the branch size, or time. If
+a check truly cannot run, write `NOT RUN: <reason>` for it on the `checks:`
+line of the report and the review record. That is a visible gap, not a
+blocker and not a pass.
+
 **Stage 2 (security) always runs full, at every level.** A shallow security
 pass is worse than none — it reads as coverage while missing the class of bug
 that costs the most.
@@ -189,7 +196,10 @@ carries the reproduction.
   location outside the repo; the tree must still be clean at exit. A test that
   passes against both the buggy and the fixed source is a tautology and proves
   nothing. Flag every one you find, and say so explicitly when the tests are
-  the branch's only evidence for its claims.
+  the branch's only evidence for its claims. **Required, every test file the
+  diff adds or changes — one red run per file is enough; checking a sample of
+  the files is a skip.** Count them as `fail-first N/M files` on the
+  `checks:` line.
 - **Maintainability.** Complexity, naming, duplication — only when material.
 
 ## Stage 2 — Security (always full)
@@ -204,7 +214,10 @@ If `security.md` cannot be found, run what you can from the list above and
 
 This stage is repo- and history-scoped, not diff-scoped: a key committed forty
 commits ago, an unbounded route the diff never touched, or a missing row
-policy on a table the new code now reads are all in scope.
+policy on a table the new code now reads are all in scope. **The review range
+never narrows this stage** — even when you were handed `main..HEAD`, the
+secrets scan covers every commit on every branch (`security.md` item 1 has
+the command).
 
 ## Stage 3 — Verify (adversarial)
 Findings are claims, not facts. **Try to break each one, not to confirm it** —
@@ -292,7 +305,10 @@ uncertain).
 
 Then a coverage line: stage 1 at level `<level>`, stage 2 full, stage 3 —
 each `ran ✓/✗` with its evidence. A stage you did not actually run is a **✗**, never an
-assumed pass.
+assumed pass. Then a `checks:` line for the two checks most often cut short:
+`fail-first N/M files` and `secrets-history all-branches` (or `NOT RUN:
+<reason>` for either). An N below M, or a NOT RUN, is reported as-is — it
+does not block.
 
 **Write the review record** to `.claude/remember/last-review.md`, overwriting
 it. `/release` reads this file; a SHA that lives only in a chat message is
@@ -311,6 +327,7 @@ level: <low | medium | high | max>
 verdict: <ready | blocked>
 date: <YYYY-MM-DD>
 coverage: stage1 <ran|NOT RUN>, stage2 <ran|NOT RUN>, stage3 <ran|NOT RUN>
+checks: fail-first <N/M files|NOT RUN: reason>, secrets-history <all-branches|NOT RUN: reason>
 blockers:
 - <file:line> · <one-sentence claim, no scenario, no suggested fix>
 ```

package/packages/claude/skills/docs-builder/SKILL.md

@@ -51,8 +51,13 @@ Every command below is `node $DB …`; everything the script writes (`docs/.docs
 JSON state, `docs/index.md`, the ledger, the log, the config pointer) lands under the target
 repo. `REPO=` is optional and only needed when not running from the repo root.
 
-**With an argument** (`reorg`, `cleanup <file>`, or `search <query words...>`) — run that mode
-directly, no question asked.
+**With an argument** (`reorg [dir]`, `cleanup <file>`, or `search <query words...>`) — run that
+mode directly, no question asked. `reorg <dir>` re-checks every doc already inside `<dir>` —
+useful to scope a check to one directory outside the default scan. A **bare** `reorg`/`discover`
+(no argument) already re-checks `docs/product/`, `docs/wiki/` and `docs/logs/` on every run —
+only `docs/archive/` stays frozen and out of scope. Scan scope with no argument is otherwise
+narrow by design: root-level `.md` files (top level only, not recursive) plus everything under
+`docs/` (recursive) — nothing else in the repo is ever listed or moved.
 
 **Bare `/docs-builder`, no argument — ALWAYS ask, never auto-detect.** Run `due` first and
 put its one-line verdict in the question text so the choice is informed. Then use
@@ -60,9 +65,9 @@ put its one-line verdict in the question text so the choice is informed. Then us
 
 > **Question: What should docs-builder do?**
 >
-> - **First run** — sort every `.md` in `docs/` into product / archive, then split anything
->   too big into pages and index them. Use when docs are a pile of loose files, or
->   docs-builder has never run here.
+> - **First run** — sort root-level `.md` files and everything under `docs/` into
+>   product/wiki/logs/archive, then split anything too big into pages and index them. Use
+>   when docs are a pile of loose files, or docs-builder has never run here.
 > - **Docs drift** — docs moved on since the last run: report what changed, rebuild the
 >   index, re-run lint. Nothing is restructured and nothing is split.
 
@@ -89,8 +94,9 @@ read-only — no model cost, no interview, nothing moves.
    bucket). `bucket` itself starts **empty** on every row.
 2. **The classification interview.** Feed the model the WHOLE plan table (file, h1, snip,
    lines, suggested+reason) in one call and have it fill `bucket` for every row —
-   `product`/`logs`/`archive` — with a one-line reason: honour that a SHOUTED self-declared
-   status is near-conclusive for `archive` and that `suggested` is a prior, not an authority.
+   `product`/`wiki`/`logs`/`archive` — with a one-line reason: honour that a SHOUTED
+   self-declared status is near-conclusive for `archive` and that `suggested` is a prior, not
+   an authority.
    The model writes its answers straight into `reorg-plan.json`. Then show the user the full
    resulting table via `AskUserQuestion` (approve all / correct specific rows / abort) — a
    correction changes the plan file before anything moves.
@@ -102,12 +108,10 @@ read-only — no model cost, no interview, nothing moves.
    to split** (any, all, none). Only then run `cleanup <file>` (Mode 1) on each chosen file —
    `cleanup` itself prints the estimated split cost for that one file, then a mechanical
    shape report, then stops for its own interview (Mode 1, step 1b) before anything else runs.
-   Before that first commit, add `docs/.docs-builder/` to `.gitignore` if it is not already
-   ignored: it is machine state, regenerated every run, and the ledger stamp is per-clone by
-   design — it must never ride into history on a later `git add -A`.
-   Once the moves are committed, run `node $DB ledger` — nothing in steps 1-3 stamps the
-   ledger, and without the stamp `due` stays NOT due, the picker's verdict stays uninformed,
-   and `/remember`'s docs nudge never fires.
+   Add `docs/.docs-builder/` to `.gitignore` if it is not already ignored: it is machine state,
+   regenerated every run, and the ledger stamp is per-clone by design — it must never ride into
+   history on a later `git add -A`. Then follow "Finishing a run" (below `apply-reorg`, Mode 0
+   step 3) to commit and stamp the ledger.
 
 The two stops are deliberate and different. Step 2 guards *correctness* — the interview and
 the user's approval, before a single file moves. Step 3's follow-up guards *cost* — splitting
@@ -118,7 +122,7 @@ when they pick "First run". Never split N files in one shot on an unseen list.
 first, if a ledger stamp exists, then it runs `discover`. If any row's `bucket` is still
 empty (true on a genuine first run, or when new files appeared since the last classification),
 `reorg` **stops right there** and prints what to do next — it never silently proceeds past an
-unclassified plan. Commit what it changed, then run `node $DB ledger` to move the stamp. Once
+unclassified plan. Otherwise follow "Finishing a run" once it's done. Once
 the plan is fully classified (an already-sorted corpus's re-run
 carries its prior classifications forward automatically — see "Discover is idempotent"
 below), `reorg` continues straight through `apply-reorg` → `lint`, no further stop, so
@@ -131,7 +135,7 @@ already sorted: nothing new to classify, so the interview gate never fires.
 
 | Mode | Menu option | Does | Destructive |
 |---|---|---|---|
-| `/docs-builder reorg` (discover, classification interview, confirm, then apply-reorg) | *First run*, steps 1-3 | classify a WHOLE corpus into product/logs/archive | no (moves are `git mv`, plan classified and reviewed first) |
+| `/docs-builder reorg` (discover, classification interview, confirm, then apply-reorg) | *First run*, steps 1-3 | classify a WHOLE corpus into product/wiki/logs/archive | no (moves are `git mv`, plan classified and reviewed first) |
 | `/docs-builder cleanup <file>` | *First run*, step 3's split question | measure ONE named oversized doc (cost, scan, heading shape) → **stops for the interview** | no (measure-only; original preserved) |
 | `/docs-builder reorg` (bare `docs-builder.cjs reorg`) | *Docs drift* | due's drift summary (if a ledger stamp exists) + discover → (stops here if anything is still unclassified) → apply-reorg → lint, whole corpus | no |
 | `/docs-builder search <query words...>` | *(none — explicit-argument mode only, never offered in the bare picker)* | BM25-rank sections of `docs/.docs-builder/outline.json` against the query, read-only | no |
@@ -155,16 +159,31 @@ docs/
   README.md          entry point, referenced from CLAUDE.md
   index.md           GENERATED by index-flat/apply-reorg/cleanup-apply. never hand-edited.
                      READER-FACING. The WHOLE-CORPUS map — the only file with a completeness
-                     guarantee. ## Product, ## Logs, ## Archive.
+                     guarantee. ## Product, ## Logs (grouped by subdir), ## Archive.
   log.md             append-only:  ## [DATE] operation | description — written by
                      `archive`, `apply-reorg`, `validate`, and `reorg`; NOT written by
                      read-only commands (`due`, `search`, `discover`).
-  product/           specs, designs, plans — the default. `apply-reorg` MOVES files here
-                     (`git mv`); content is never rewritten.
-  logs/              pre-registrations, results, learnings, reports — historical, still
-                     relevant. Same MOVE discipline as product/archive.
-  wiki/              synthesised pages, written by Mode 1 (`cleanup`)'s page writers.
-  archive/           what got cleaned up: self-declared dead. Originals are BYTE-FROZEN:
+  product/           docs ABOUT THE PRODUCT ITSELF — specs, PRDs, designs, guides for this
+                     product. FLAT, no subdirs. `apply-reorg` MOVES files here (`git mv`);
+                     content is never rewritten. Re-checked on EVERY reorg (files sitting here
+                     are re-classified along with everything else — agents litter buckets
+                     over time).
+  wiki/              GENERIC knowledge for the whole repo, not product-specific — conventions,
+                     how-tos, standards, reference. FLAT, no subdirs. Also where Mode 1
+                     (`cleanup`)'s split page writers put synthesised pages. Re-checked every
+                     reorg, same as product/.
+  logs/              ONE-TIME, specific, timely knowledge tied to one section/scenario/case —
+                     POCs, experiments, investigations, incident/session write-ups, reports. The
+                     ONLY bucket that may nest, ONE level: `docs/logs/<group>/*.md` — the group
+                     is the FIRST path segment under `docs/` (a special subfolder is one
+                     self-explanatory group, e.g. every POC under `docs/fwd/` stays together as
+                     `fwd`, however deep a file actually sits inside it), UNLESS that segment is
+                     itself a bucket name (`product`/`wiki`/`archive` → flat; `logs` → the group
+                     is the SECOND segment instead). A file with no first segment — loose at the
+                     repo root, or directly under `docs/` — stays flat. Re-checked every reorg,
+                     same as product/wiki/.
+  archive/           what got cleaned up: self-declared dead. FROZEN — never re-checked, never
+                     walked by a bare `discover`/`reorg` at all. Originals are BYTE-FROZEN:
                      nothing under here is ever a rewrite target, so a doc lands byte-identical
                      to what it carried in (a clean R100 rename) and stays that way. Links
                      elsewhere POINTING AT it are still repaired. History via `git mv`.
@@ -202,14 +221,19 @@ moved the problem (it then clobbered `outline.json` across concurrent splits ins
 **the themed index was removed outright, 2026-08-24**. One index, rebuilt on every reorg and
 after every split, is the whole design.
 
-**Never moved — enforced in code, not just documented** (`PROTECTED_NAMES` / `walkMd`):
+**Never moved — enforced in code, not just documented** (`PROTECTED_NAMES` / `isProtectedName` /
+`walkMd`):
 
-- **Files, at any depth:** `README.md`, `index.md`, `log.md`, `CHANGELOG.md`, `LICENSE.md`,
-  `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CLAUDE.md`, `AGENTS.md`, `AGENT.md`.
-  Bare `LICENSE`/`NOTICE` have no `.md` extension, so the walker never sees them.
+- **Files, at any depth, matched CASE-INSENSITIVELY:** `README.md`, `index.md`, `log.md`,
+  `CHANGELOG.md`, `LICENSE.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`,
+  `CLAUDE.md`, `AGENTS.md`, `AGENT.md` — so `readme.md`, `Claude.md`, `changelog.md`,
+  `agents.md`, etc. are protected too, not just their exact-case forms. Bare `LICENSE`/`NOTICE`
+  have no `.md` extension, so the walker never sees them.
 - **Directories:** every dot-dir (`.git/`, `.github/`, `.claude/`, `.factory/`, `.opencode/`,
-  `.amp/`, `.docs-builder/`) plus `node_modules/`, and the dirs reorg itself owns
-  (`product/`, `logs/`, `archive/`, `wiki/`) so a second run is idempotent.
+  `.amp/`, `.docs-builder/`) plus `node_modules/`. `archive/` is skipped unconditionally by a
+  bare `discover`/`reorg` (frozen, never re-checked); `product/`, `wiki/` and `logs/` are
+  entered and re-checked on that same bare run — only an explicit `discover <dir>` naming one
+  of the reserved names directly bypasses this at all four.
 
 ---
 
@@ -229,11 +253,31 @@ purpose, not silently dropped.
 ### 1. Discover (script) — enriches and PROPOSES, never classifies, never moves
 
 ```bash
-node $DB discover        # defaults to docs/
+node $DB discover        # root-level .md files (top level only) + everything under docs/
+node $DB discover <dir>  # scopes to exactly <dir> instead — e.g. a directory outside docs/
 ```
 
-Recursively finds every `*.md` under the root (skipping `wiki/`, `logs/`, `archive/`,
-`product/`, `.docs-builder/`, and the protected files), and for each one writes a row with:
+**Scan scope with no argument is deliberately narrow:** (a) `.md` files sitting directly at
+the repo root (top level, not recursive) and (b) everything under `docs/` (recursive, entering
+`product/`, `wiki/` and `logs/` — only `docs/archive/` stays frozen and skipped). Every other
+`.md` file anywhere else in the repo is out of scope entirely — never listed, never moved,
+whether or not `docs/` exists. `PROTECTED_NAMES` still applies at the repo root (case-
+insensitively — see Layout above), so `README.md`, `CLAUDE.md`, `CHANGELOG.md`, `AGENTS.md`,
+`AGENT.md`, `LICENSE.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `index.md`
+and `log.md` are never planned or moved. `ROOT=` is NOT read by this script — setting it
+prints a `WARN`; pass the folder as the argument.
+
+**Because `product/`, `wiki/` and `logs/` are re-checked every bare run,** a file already
+sitting in one of them is a REAL row too, not folded away — its `suggested` bucket defaults to
+wherever it already sits (a stronger signal, like a filename token or a SHOUTED status word,
+can still override that). It still needs `bucket` filled by the interview like any other row
+(even if the answer is "yes, stays put") — that settles after one classify+apply pass and
+carries forward from then on, same as everything else. An explicit `discover <dir>` still
+scopes to exactly that one directory, unaffected — useful for anything outside the default
+root+docs/ coverage.
+
+Recursively finds every in-scope `*.md` (skipping `.docs-builder/` and the protected files, at
+any depth in scope), and for each one writes a row with:
 
 - `h1` and a short `snip` (first ~200 chars of body, fence-masked) — reused straight from the
   same `headings()`/`snippet()`/`fenceMask()` parsers `scan` uses, no second extraction path.
@@ -242,14 +286,22 @@ Recursively finds every `*.md` under the root (skipping `wiki/`, `logs/`, `archi
   *sorted* — it is no longer a bucket.
 - `suggested` + `reason` — a mechanical PRIOR, never a verdict:
 
+Checked in this order — the first rule that matches wins:
+
 | suggested | rule |
 |---|---|
 | `archive` | path already under `archive/old/reports/phases`, **or** the doc's own opening declares a SHOUTED status word (`CLOSED`, `DEPRECATED`, `SUPERSEDED`, `WITHDRAWN`, `RETRACTED`, `REFUTED`, `ARCHIVAL`, `ARCHIVED`), **or** the filename matches an archive-shaped prefix (`REPORT`, `STATUS`, `SUMMARY`, `FIX_`, `PHASE_`, `SPRINT_`, `DRAFT`, `WIP`, `OLD`, `TEMP` followed by `-` or `_`) |
 | `logs` | filename carries an experiment-record token — `PREREG`, `LEARNINGS`, `REPORT`, `RESULTS`, `POSTMORTEM`, `RETRO` (case-sensitive, word-boundary, checked ONLY after the archive rules above, so a `REPORT-old.md` still reads as archive, not logs) |
-| `product` | has an H1, no archive/logs signal — the default when nothing else applies |
+| *(residency)* | already resident under `docs/product/`, `docs/wiki/` or `docs/logs/` — its own current bucket is its prior (a stronger signal above can still override, e.g. a product-resident doc now shouting `DEPRECATED`) |
+| `archive`/`logs`/`wiki` | a WEAKER, case-insensitive secondary prior read from the doc's own **H1 + first 3 H2s** — e.g. "Postmortem"/"Retrospective"/"Investigation" → `logs`; "deprecated"/"retired"/"superseded" → `archive`; "Conventions"/"How-to"/"Style Guide"/"Glossary" → `wiki`. Deliberately narrow: bare "guide"/"reference" were tried and DROPPED after false-positiving on an ordinary doc plainly titled "Guide". |
+| `product` | has an H1, no archive/logs/wiki signal — the default when nothing else applies |
 | `product` | no H1, but an **include stub** — its whole non-blank content (≤3 lines) is nothing but include directives (mkdocs `--8<--`, `{% include %}`, `{{ .. }}`, `<!-- include -->`) and/or markdown links | a live pointer, not an unknown doc — real-world miss: uv's `docs/reference/contributing.md` |
 | `product` | no H1 at all, and not an include stub — no strong signal either way; the interview decides, same as any other row |
 
+`suggested` never proposes `wiki` from a residency check alone reaching further than its own
+match — the heuristic is only ever a prior; the interview decides the real `bucket`, including
+routing a doc INTO `wiki` from anywhere.
+
 - `bucket` — **empty on any row discover has not classified before** (see carry-forward
   below; a re-run keeps a bucket the interview already set). This is the field the
   classification interview (step 2) fills, and the ONLY field `apply-reorg` reads to decide
@@ -308,7 +360,7 @@ was the silent move, not the judgement.
 
 1. Read `docs/.docs-builder/reorg-plan.json`. Feed the model the WHOLE table — `file`, `h1`,
    `snip`, `lines`, `suggested`+`reason` — **in one call**, and have it fill `bucket` for
-   every row (`product`/`logs`/`archive`) with a one-line reason. `suggested` is a PRIOR the
+   every row (`product`/`wiki`/`logs`/`archive`) with a one-line reason. `suggested` is a PRIOR the
    model is shown, never an authority over it — but a SHOUTED self-declared status
    (`**Status: CLOSED**`) is near-conclusive for `archive` regardless of what the mechanical
    prior says.
@@ -348,9 +400,15 @@ message, not a crash — so nothing can move on an unreviewed plan. A plan from
 version (`bucket: 'oversized'` or `'review'`, both gone from the schema) is refused too, with
 a pointer to re-run `discover`.
 
-- `product` → verified `git mv` to `docs/product/<basename>`
-- `logs` → verified `git mv` to `docs/logs/<basename>`
-- `archive` → verified `git mv` to `docs/archive/<basename>`
+- `product` → verified `git mv` to `docs/product/<basename>` (always flat)
+- `wiki` → verified `git mv` to `docs/wiki/<basename>` (always flat)
+- `logs` → verified `git mv` to `docs/logs/<basename>` (loose) **or**
+  `docs/logs/<group>/<basename>` — the ONE bucket that may nest, ONE level, where the group is
+  the file's FIRST path segment under `docs/` (unless that segment is itself a bucket name —
+  see the Layout section above). A deeper path inside the same special subfolder joins the
+  SAME group (no ratchet on a re-check either).
+- `archive` → verified `git mv` to `docs/archive/<basename>` (always flat, and frozen — never
+  re-checked again once there)
 - **Oversized files move too — size decides splittable, not sorted.** No bucket is exempt.
   After the move, every oversized row is printed as a follow-up list at its NEW path, one
   `cleanup <path>  (N lines)` line per file — run `cleanup` (Mode 1, below) on each, by hand,
@@ -369,20 +427,10 @@ a pointer to re-run `discover`.
   static — it never varies with row count, so a re-run rewrites identical bytes. Idempotent:
   an existing block is replaced in place, never duplicated; other content is left alone.
   The target is `CONFIG=` (default `CLAUDE.md`); this package uses `CONFIG=CLAUDE.md`.
-- **The moves land STAGED in your git index — commit them promptly.** `git mv` stages each
-  rename immediately (that is what preserves history), so when `apply-reorg` returns the repo
-  is holding N staged renames. Any other session's `git add -A` or `git commit -a` will absorb
-  them into an unrelated commit — OBSERVED TWICE, in two different repos. `apply-reorg` prints
-  a closing advisory naming the counts and a copy-pasteable recipe. **Run that recipe
-  VERBATIM. Do NOT hand-edit it, and do NOT stage by hand instead.** If it looks incomplete
-  or names a path that errors, that is a BUG in the recipe — stop and report it to the user;
-  do not silently repair it and move on. OBSERVED, real (privcloud first field run): the
-  recipe omitted `docs/log.md`, the operator quietly added it by hand, and the bug only
-  surfaced because they were later asked for near-misses — a silent repair is a lost bug
-  report. Do NOT scope the commit to `docs` alone either: the renames are staged, but the
-  inbound-link rewrites are UNSTAGED and reach outside `docs/` (`src/`, `scripts/`, `tests/`,
-  `README.md`). Both belong in ONE commit, or you ship moved files whose links were never
-  repaired. The tool never auto-commits, by design.
+- **The moves land STAGED in your git index — nothing is committed for you.** `git mv` stages
+  each rename immediately (that is what preserves history), so when `apply-reorg` returns the
+  repo is holding N staged renames plus unstaged link rewrites. `apply-reorg` prints a closing
+  commit advisory; see "Finishing a run" below for the actual commit flow.
 - A basename collision (two files, same name, different original folders) is
   disambiguated (`-2`, `-3`, …); a collision with a **file that already exists at the
   destination** is skipped, logged, and does not stop the rest of the run.
@@ -393,7 +441,9 @@ a pointer to re-run `discover`.
   touches — is never removed. Only directories THIS run emptied are candidates; a dir that
   happened to already be empty before this run started is not this tool's to remove.
 - **After every move, `apply-reorg` re-scans the whole corpus** — `docs/product/`,
-  `docs/logs/`, and `docs/archive/` all — straight into `outline.json`, the database `search`
+  `docs/logs/`, and `docs/archive/` all (`docs/wiki/` is excluded, same as any other
+  `PAGES` dir — it holds synthesised pages, not source docs to reorg) — straight into
+  `outline.json`, the database `search`
   reads. Not a hint, not opt-in: it runs every time, even when nothing moved this run (e.g.
   re-running on a corpus already sorted from a previous pass). Measured bug this closes: on a
   real 37-doc corpus, `outline.json` used to hold records for only the 12 files a split had
@@ -402,6 +452,47 @@ a pointer to re-run `discover`.
   content, so a pre-move scan would just be redone), and reuses the same `scan` used
   everywhere else in this pipeline — no second scanner, no second outline format.
 
+### Finishing a run — the commit flow, run by hand every time
+
+`apply-reorg`/`archive`/`cleanup-apply` never auto-commit, by design. Each run's staged renames
+and unstaged link rewrites (in `.md` files only, but anywhere — e.g. the root `README.md`)
+belong in ONE commit, including the
+`CLAUDE.md` docs-pointer block `apply-reorg` writes — it is in `commit-files.txt` along with
+everything else. Run these steps literally, in order:
+
+1. `git branch --show-current`. If it prints `main` or `master`, do **NOT** commit — tell the
+   user the files are ready and to switch to a branch first.
+2. `cat docs/.docs-builder/commit-files.txt` to see exactly what this run touched, and
+   `cat docs/.docs-builder/commit-dirty.txt` to see which of those files already carried the
+   operator's own uncommitted edits BEFORE this run — pathspec can't split hunks, so committing
+   the file commits that edit too. Then ask with `AskUserQuestion`, header `Commit`: if
+   `commit-dirty.txt` lists anything, **"Commit these N files now? Note: these files also
+   carry your own uncommitted edits, which will be committed too: …"** (name them); otherwise
+   **"Commit these N files now?"** — **Commit** (run the printed recipe) / **Leave uncommitted**
+   (say what is pending; nothing this run did gets undone).
+3. On **Commit**, run the printed recipe line EXACTLY as printed:
+   ```
+   git add --pathspec-from-file=docs/.docs-builder/commit-add.txt && git commit -m "docs: reorg" --pathspec-from-file=docs/.docs-builder/commit-files.txt
+   ```
+   (when `REPO` isn't the shell's cwd, both commands are printed as `git -C '<REPO>' …` instead
+   — run that form, unmodified). Do not hand-edit it, do not stage by hand instead, and do not
+   scope it to `docs/` alone — a `.md` outside `docs/` (e.g. `README.md`) can carry a repaired
+   link. If it errors or names a path that doesn't exist, that is a BUG: stop and report it to
+   the user; do not silently hand-repair and move on.
+   OBSERVED, real (privcloud first field run, pre-dating the pathspec-file recipe): a
+   hand-rolled recipe once omitted `docs/log.md` and the operator quietly added it by hand —
+   the bug only surfaced later, when asked for near-misses. A silent repair is a lost bug
+   report.
+4. After a successful commit, run `node $DB ledger` to stamp the consolidation — nothing in
+   `discover`/`apply-reorg`/`archive`/`cleanup-apply` stamps it for you, and without the stamp
+   `due` stays NOT due, the picker's verdict stays uninformed, and `/remember`'s docs nudge
+   never fires.
+
+Add `docs/.docs-builder/` to `.gitignore` before the first commit if it is not already
+ignored — it is machine state, regenerated every run, and the ledger stamp is per-clone by
+design. Never use `git add -A` / `git add -u` / `git commit -a` for this: either would ALSO
+absorb any unrelated in-flight work in the tree — OBSERVED TWICE, in two different repos.
+
 **After each move it repairs the paths that move just broke** — the whole point of doing this
 in a script. Both movers (`apply-reorg` and `archive`) go through ONE function, `moveDoc`, so
 the follow-up list cannot be added to one and missed by the other; that exact miss shipped
@@ -413,8 +504,12 @@ reported as a file that needs re-moving. Two follow-ups:
    (`records[].file`, and the `<file> :: ` prefix inside every key). This is the same
    function `archive` calls; `apply-reorg` used to bypass it, which silently invalidated
    every key of every file it moved. Both now reach it through `moveDoc`.
-2. **Inbound links** — every git-tracked `.md`/`.js`/`.cjs`/`.mjs`/`.json`/`.yml` file that
-   points at the old path (repo-rooted, e.g. `docs/GUIDE.md`) is rewritten to the new one.
+2. **Inbound links** — every git-tracked `.md` file, anywhere in the repo, that points at the
+   old path (repo-rooted, e.g. `docs/GUIDE.md`) is rewritten to the new one. Only `.md` files
+   are ever opened, read, or edited — this is a DOCS tool, not a repo-wide text rewriter.
+   FIELD BUG, real (bareloop, 2026-09-10): the previous version also scanned
+   `.js`/`.cjs`/`.mjs`/`.json`/`.yml`, and rewrote 6 signed JSON job specs (breaking their
+   hashes), a byte-signed `.mjs` close script, and a code comment that tripped a commit gate.
    In `.md` files specifically, a RELATIVE link is also caught: inside actual markdown link
    syntax only (`[text](../concepts/x.md)` or a reference-style `[label]: ./tools.md`), never
    bare prose, the target is resolved against the SCANNING file's own directory, and — if it
@@ -449,13 +544,14 @@ predicate, `isRewriteExempt`, at one call site. `docs/.docs-builder/` is exclude
 
 **A known, deliberate trade-off: this is a literal exact-path match over raw file bytes, not
 fence-aware or context-aware.** It rewrites every exact, word-bounded occurrence of the old path
-in every git-tracked `.md`/`.js`/`.cjs`/`.mjs`/`.json`/`.yml` file (except the two exemptions
-above) — inside a code fence, inside a sentence describing history ("this used to live at
-docs/OLD.md"), anywhere. A prose mention of where a file *used to be* WILL be rewritten to say
-where it is now, changing what the sentence says. This is intentional, not an oversight: a dead
-link is worse than a reworded sentence, the match is exact rather than inferred (unlike the
-dangling-reference *lint*, which infers and was cut outright at 1/27 precision), and every
-rewrite is printed per file so it is visible, never silent.
+in every git-tracked `.md` file (except the two exemptions above) — inside a code fence, inside
+a sentence describing history ("this used to live at docs/OLD.md"), anywhere. A prose mention of
+where a file *used to be* WILL be rewritten to say where it is now, changing what the sentence
+says. This is intentional, not an oversight: a dead link is worse than a reworded sentence, the
+match is exact rather than inferred (unlike the dangling-reference *lint*, which infers and was
+cut outright at 1/27 precision), and every rewrite is printed per file so it is visible, never
+silent. Only `.md` files are ever in scope, so this trade-off never touches non-doc files —
+see "Inbound links" above.
 
 ---
 
@@ -746,14 +842,16 @@ node $DB index-flat
 Writes **one** `docs/index.md` covering the whole corpus, in three sections: `## Product`
 (one row per file under `docs/product/`, plus any pages under `PAGES` — default `docs/wiki/`
 — if they exist, plus any doc still sitting in place elsewhere), `## Logs` (one row per file
-under `docs/logs/`), and `## Archive` (one row per file under `docs/archive/`). Each row is
-an H1 title, a line count, and a link, 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.
+under `docs/logs/`, **grouped by its one-level subdir** — a loose `docs/logs/x.md` row is
+listed ungrouped first, then each subdir gets its own `### <subdir>/` header with its files
+under it, subdirs sorted alphabetically), and `## Archive` (one row per file under
+`docs/archive/`). Each row (product or logs, grouped or not) is 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`
@@ -774,7 +872,8 @@ v3 folds the old `reconcile` and `due` commands into one: "first run" (nothing s
 state, and two separate commands only made users guess which one to run.
 
 ```bash
-node $DB reorg
+node $DB reorg        # root-level .md files (top level only) + everything under docs/
+node $DB reorg <dir>  # re-checks every doc already inside <dir> — passes <dir> to discover
 ```
 
 If a ledger stamp exists (see "Knowing when reorg is due" below), its `due`-style drift