docs(agent-feedback): migrate to one item per file

AGENTS.md

@@ -5,7 +5,7 @@
 - Describe what Marko does, never what it lacks. No "there is no X", and no workarounds that route around the framework.
 - Do not document compile errors. The compiler reports them with a code frame. This covers content that reframes them, such as a table mapping another framework's attribute names onto Marko's.
 - Do not document errors, warnings, or checks that only a `MARKO_DEBUG` build produces. State the rule, not the message.
-- Never document a known bug as intended behavior. Grep `agent-feedback/bugs.md` in the `marko` repo first; a hit means file the defect and leave the docs alone.
+- Never document a known bug as intended behavior. Grep `agent-feedback/` in the `marko` repo first; a hit means file the defect and leave the docs alone.
 - Drop a topic that loses its main claim to the rule above. What remains is the least verified part of it.
 - Prefer filing a defect to writing a caveat that teaches readers to live with one.
 
@@ -121,4 +121,4 @@
 
 ## Agent feedback
 
-Anything actionable but out of scope for the current task — a suspected bug, cleanup, a perf/size win, tooling friction, or code that was confusing — must be recorded in [`agent-feedback/`](agent-feedback/README.md) before finishing. Don't silently drop it, and don't fix it inside an unrelated diff.
+Anything actionable but out of scope for the current task (suspected bug, cleanup, perf or size win, tooling friction, confusing code) must be filed in [`agent-feedback/`](agent-feedback/README.md) before finishing. Never drop it silently. Never fix it inside an unrelated diff.

agent-feedback/README.md

@@ -1,39 +1,65 @@
 # Agent Feedback
 
-Actionable observations that were **out of scope for the task that surfaced them**. If something is in scope, fix it instead. Do not expand a task's diff to fix issues recorded here.
+Actionable observations that were out of scope for the task that surfaced them. In scope: fix it. Out of scope: file it here. Never expand a task's diff to fix an item recorded here.
 
-## When to add an entry
+One item per file in `items/`, named `YYYY-MM-DD-<slug>.md`.
 
-While working on any task, record anything a future contributor should act on:
+## When to file
 
-- a suspected bug you couldn't pursue → `bugs.md`
-- duplication, dead code, inconsistency, refactor opportunities → `cleanup.md`
-- runtime speed or bundle size opportunities → `perf.md`
-- friction in builds, tests, tooling, or repo workflows → `dx.md`
-- code or docs that were confusing, and what would have clarified them → `unclear.md`
+Anything a future contributor should act on:
 
-## Rules
+- `bug`: a suspected defect left unpursued
+- `cleanup`: duplication, dead code, inconsistency, refactor opportunity
+- `perf`: speed, memory, payload or bundle size, build time
+- `dx`: friction in builds, tests, tooling, or repo workflows
+- `unclear`: code or docs that were confusing, and what would have clarified them
 
-1. **Search the category file first.** If an entry already covers it, don't duplicate; append a corroborating sentence only if you have new information.
-2. **Be self-contained.** Include enough detail (paths, symbols, reasoning) that someone can act without re-discovering your analysis. Never reference "my earlier analysis" or conversation context.
-3. **Cite by stable symbol, not line number.** Line numbers rot with the next edit; anchor the primary citation to the nearest enclosing stable symbol (exported function, class, variable, or a heading for docs). A line number may appear in the body as a secondary hint.
-4. **Append to the end** of the category file.
-5. Entries are **removed when resolved** (delete, don't mark done; git history is the archive).
-6. **Verify before recording.** A guess is not feedback.
+## Rules
 
-## Resolving a "won't fix" item
+1. **Verify first.** A guess is not feedback. Every item ends with a check that reproduces the claim.
+2. **Dedupe first.** `grep -ril '<path or symbol>' agent-feedback/items`. If a file covers it, edit that file only when you add new information.
+3. **Check the code site.** An intent comment there means the behavior is deliberate. Do not file it.
+4. **Self-contained.** Paths, symbols, reasoning. Never reference conversation context or "earlier analysis".
+5. **Cite by stable symbol**, never line number.
+6. **State the defect and the check.** Never describe what works. Never narrate a landed fix.
+7. **Direction is preventive for `unclear` and `dx`.** Name what would have stopped the trip: a comment, a doc line, a lint rule, a compile error, a debug-only warning. The goal is that the next agent does not hit it.
+8. **Resolve by deleting the file in the same PR as the fix.** A partial fix rewrites the file to what remains.
+9. **Won't-fix is a maintainer's call, never an agent's.** Add a comment (two lines max) at the code site stating the behavior and why it is deliberate, then delete the file. The comment is what stops re-filing. Never consult git history to learn whether something was resolved; if it is not in `items/` and not commented at the site, it is unresolved.
 
-When a maintainer has explicitly deemed an item "won't fix" / "not worth it", resolve it by adding a brief inline comment at the code site that captures the decision (so it is not re-filed), then remove the entry. Only on such an explicit call — never on your own initiative.
+## Item format
 
-## Entry format
+`items/YYYY-MM-DD-<slug>.md`:
 
 ```md
-## <one-line imperative summary>
+---
+type: bug | cleanup | perf | dx | unclear
+impact: high | med | low
+effort: high | med | low
+site: <path/to/file.ts> › <nearestStableSymbol>
+---
+
+# <one-line imperative title>
 
-`<primary/file/path.ts>` › `<nearestStableSymbol>` | 2026-07-02 | impact:<low|med|high> | effort:<low|med|high>
+<2-6 sentences: the problem, why it matters, a concrete direction. Cut evidence a fixer can re-derive from the site.>
 
-<2–6 sentences: the problem, why it matters, and a concrete suggested direction,
-ending with the check that re-verifies the claim (a command, input, or
-observation). Cut evidence beyond what a fixer needs to act; further detail is
-re-derived from the citation. Additional file paths inline as needed.>
+Check: <command, input, or observation that reproduces the claim>
 ```
+
+`impact`: what breaks or is lost if ignored. `effort`: expected size of the fix. Both are the filer's estimate; triage re-judges.
+
+## Repo notes
+
+The markojs.com site: docs as markdown under `docs/`, a `@marko/run` app under `src/`, plus the browser playground. The root `AGENTS.md` holds the documentation writing guidelines and they govern any docs change; read it too.
+
+**Reproduce a claim.**
+
+- Docs content: `grep` the page, then verify the behavior it describes against Marko runtime source, a fixture snapshot, or a compiled probe. An existing docs sentence is not evidence.
+- Anchors and slugs: `github-slugger` resolves collisions in document order, so a second heading with the same slug becomes `#name-1`. Check with the slugger directly rather than guessing.
+- Playground and site behavior: `pnpm run dev`, then reproduce in the browser.
+- Build-derived output (page `<meta>`, generated llms bundles): `pnpm run build`, then read `src/routes/docs/_compiled-docs/`.
+
+**Guard tests.** `pnpm test` (`vitest run`). A docs-structure claim (every page indexed, every anchor resolving) is best guarded by a test that walks `docs/**/*.md`, not by a snapshot of one page.
+
+**Pre-ship.** `pnpm run lint` (markdownlint over `docs/**/*.md`, then cspell) and `pnpm run type-check` (`marko-type-check`). `pnpm run build` when the change can affect generated output.
+
+**Gotchas.** `pnpm run lint` runs cspell, which has a Node engine floor above some default installs and aborts on the version check before checking anything; the husky pre-commit hook hits the same wall. Never document a known Marko bug as intended behavior: file the defect instead. Never use an em dash in docs, and grep `' - '` too, since a spaced hyphen doing the same job is the same problem.

agent-feedback/items/2026-07-19-llms-txt-completeness.md

@@ -0,0 +1,12 @@
+---
+type: unclear
+impact: med
+effort: low
+site: public/llms.txt › Reference
+---
+
+# Index every public docs page in `llms.txt` and add a completeness check
+
+`public/llms.txt` is a hand-maintained static index with no generator, and three substantive on-disk pages are linked from none of its topic sections: `docs/reference/lazy-loading.md` (the whole `import ... with { load: "visible#hero" }` client code-splitting and deferred-hydration API), `docs/explanation/class-vs-tags-api.md` (the flagship Marko 5-to-6 migration mental-model guide), and `docs/reference/supported-environments.md`. The only aggregate generator, `src/routes/docs/_llms/reference-full%2emd+handler.ts`, hardcodes a 9-page list that includes lazy-loading but omits supported-environments, so even the bundle llms.txt labels "Complete reference documentation" is itself incomplete, and class-vs-tags-api appears in no aggregate at all. Because llms.txt is an agent's primary topic index, an agent asked to add deferred client hydration scans the Reference links, finds no lazy-loading entry, and concludes the capability does not exist; an agent porting a Marko 5 class app never discovers class-vs-tags-api.md and mis-migrates from memory. Add the three pages to their sections, add supported-environments to the reference-full list, and add a test asserting every `docs/**/*.md` slug appears in llms.txt so new pages cannot silently drop out.
+
+Check: `grep -c lazy-loading public/llms.txt` is 0 while `docs/reference/lazy-loading.md` exists; same for `class-vs-tags-api` and `supported-environments`.

agent-feedback/items/2026-07-19-template-mount-node-required.md

@@ -0,0 +1,12 @@
+---
+type: unclear
+impact: low
+effort: low
+site: docs/reference/template.md › Template.mount(input, node, position?)
+---
+
+# Mark `Template.mount`'s `node` param as required, not `Default: undefined`
+
+The `Template.mount(input, node, position?)` parameter table lists a Default of `{}` for `input` and `"beforeend"` for `position`, both real defaults, but `undefined` for `node`, which reads as "node is optional and defaults to undefined". `node` is required: `packages/runtime-tags/index.d.ts` in the marko repo declares `mount(input, reference: Node, position?)` with `reference` non-optional, and `packages/runtime-tags/src/dom/template.ts` › `mount` defaults only `input = {}` while `reference` has no default and is dereferenced unconditionally, so `template.mount(input)` is a type error and throws at runtime. The doc's own examples always pass a node. Agents treat parameter tables as the machine-readable contract: an agent building a client mount or test harness reads "node: Default undefined", writes `template.mount(input)` expecting a detached mount, and burns a debug cycle, or ships code that crashes on the undefined reference. Replace the `undefined` cell with "required", or split required params from defaulted ones, so the table agrees with the `reference: Node` signature.
+
+Check: read the parameter table under the `Template.mount` heading in `docs/reference/template.md`.