agent-feedback: empty docs pages, search anchors, and a missing testing guide

agent-feedback/items/2026-07-28-stub-docs-missing-intro-prose.md

@@ -5,8 +5,8 @@ effort: med
 site: docs/explanation/optimizing-performance.md › # Optimizing Performance
 ---
 
-# Fill in the three docs that have no usable opening prose
+# Fill in the four docs that have no usable body
 
-`optimizing-performance.md` and `docs/guide/publishing-components.md` are heading-only stubs with no body text at all, and `docs/guide/library-integration.md` opens its first section with the bare fragment "Use `<lifecycle>` tag" instead of a sentence. Beyond the reader-facing gap, the build derives each page's `<meta name=description>` from its opening paragraph, so the two stubs fall back to the generic site description and library-integration advertises itself to search engines as "Use <lifecycle> tag". Writing an intro paragraph for each fixes both at once.
+`optimizing-performance.md` and `docs/guide/publishing-components.md` are heading-only stubs with no body text at all, `docs/guide/library-integration.md` opens its first section with the bare fragment "Use `<lifecycle>` tag" instead of a sentence, and `docs/guide/duplicate-form-submissions.md` is 118 bytes whose whole body promises content it never delivers ("This guide will discuss disabling buttons & forms after the first submission."), with no headings under it at all. All four are listed in `public/llms.txt` as real pages, so a reader following the Guides index for form handling lands on a promise. Beyond the reader-facing gap, the build derives each page's `<meta name=description>` from its opening paragraph, so the two stubs fall back to the generic site description and library-integration advertises itself to search engines as "Use <lifecycle> tag". Writing an intro paragraph for each fixes both at once; the form guide additionally needs the body its own sentence promises.
 
-Check: `pnpm run build`, then `grep -h '"description"' src/routes/docs/_compiled-docs/{explanation/optimizing-performance,guide/publishing-components,guide/library-integration}+meta.json`.
+Check: `pnpm run build`, then `grep -h '"description"' src/routes/docs/_compiled-docs/{explanation/optimizing-performance,guide/publishing-components,guide/library-integration}+meta.json`; and `wc -c docs/guide/duplicate-form-submissions.md` is 118 against a `duplicate-form-submissions+meta.json` whose `headings` array is empty.

agent-feedback/items/2026-08-20-search-index-h4-sections.md

@@ -0,0 +1,12 @@
+---
+type: dx
+impact: low
+effort: low
+site: src/util/search-index-builder.ts › splitAtHeadings
+---
+
+# Start a search block at `####` headings, not only `##` and `###`
+
+`splitAtHeadings` opens a new `SearchBlock` only on a depth 2 or 3 heading and folds every deeper heading into the enclosing block's body, so an answer that lives under an h4 is matchable as text but gets no result of its own and no anchor. `docs/reference/native-tag.md` keeps `#### Form Reset`, `#### Delegation`, `#### Handler Arguments` and six per-element change-handler sections inside `### Change Handlers`, which produces the largest block in the whole index (4978 characters) titled "Change Handlers" and pointing at `#change-handlers`, so a search for "form reset" lands the reader hundreds of lines above the answer even though the page renders an `id="form-reset"` section and the on-page table of contents lists it. Splitting at depth 4 as well is a one-line change to the depth test; the existing `content.length < 30` filter already drops blocks too small to be worth a result.
+
+Check: `pnpm run build`, then `node -e "const b=require('./public/search-index.json'); console.log(b.filter(x=>x.href.endsWith('#form-reset')).length)"` prints `0`; it should print `1`.

agent-feedback/items/2026-08-20-testing-docs-page.md

@@ -0,0 +1,12 @@
+---
+type: dx
+impact: high
+effort: med
+site: docs/introduction/integrations.md › ## Testing
+---
+
+# Add a Testing guide covering the two-project Vitest setup the starter ships
+
+Everything the site says about testing is the two sentences under `## Testing` in `docs/introduction/integrations.md`, which name `@marko/testing-library` and hand the reader to its GitHub README, and `public/llms.txt` indexes no testing page at all, so an agent scanning the topic list concludes the subject is undocumented. The official `app` starter meanwhile ships a `vitest.config.ts` with two projects, `server` (`environment: "node"`, `src/**/{,*.}server.test.ts`) and `browser` (chromium, `src/**/{,*.}browser.test.ts`), plus `@marko/testing-library` tests beside its `char-count` tag, and nothing on the site explains that split or the filename convention it keys on. A guide should state which project a test belongs in and what each can do, cover `render`, `cleanup` and `fireEvent`, and note that a controlled form element follows `fireEvent.input` rather than `fireEvent.change`, since `packages/runtime-tags/src/dom/controllable.ts` in the marko repo delegates only `"input"`. Leave route handler testing out until the `run` repo's filed defect lands, since importing a `+handler.ts` from a test still throws `ReferenceError: Run is not defined`.
+
+Check: `grep -in test public/llms.txt` returns nothing and `grep -rln testing-library docs/` names only `docs/introduction/integrations.md`; a testing page should exist under `docs/` and appear in the `llms.txt` Guides list.