diff --git a/agent-feedback/items/2026-07-30-script-tag-run-order.md b/agent-feedback/items/2026-07-30-script-tag-run-order.md
index 5c5f039cb..d6d52d7b0 100644
--- a/agent-feedback/items/2026-07-30-script-tag-run-order.md
+++ b/agent-feedback/items/2026-07-30-script-tag-run-order.md
@@ -10,3 +10,7 @@ site: docs/reference/core-tag.md › ## <script>
 The `<script>` section says the body "is executed first when the template has finished rendering and is mounted in the browser" and re-runs when a referenced tag variable changes, which leaves source order as the only ordering a reader can infer between two `<script>` tags. Marko compiles a `<script>` that reads a tag variable into that variable's own setup, so it first runs when the variable initializes, ahead of an earlier-in-source `<script>` that reads nothing. Given `<let/board=DEFAULT/>`, a first script that only assigns `board` from `localStorage`, and a second that reads `board` and writes it back, the second runs first with `DEFAULT` and overwrites the saved value before the restore reads it: the compiled dom output puts the persist effect inside `_let(...)` while the restore stays a separate `$setup__script`. The page's own `<script=remember/>` example already persists `input.collapsed` to `sessionStorage` without saying when it first fires, so the rule belongs there, stated positively: reading a tag variable ties the effect to that variable's initialization. The paired restore-and-persist idiom belongs under `## <lifecycle>`, whose `onMount`/`onUpdate` handlers already model "set up once, then follow the value".
 
 Check: `grep -n "finished rendering" docs/reference/core-tag.md` is the page's only ordering statement and `grep -rn "localStorage" docs/` returns nothing, so neither the rule nor the idiom is documented; the clobber reproduces in the local playground (`pnpm run dev`).
+
+Which reads count needs the same statement. A read anywhere in the body subscribes, including from a closure that runs long after the effect returned, while an assignment alone does not: a `<script>` registering `document.addEventListener("keydown", (e) => { if (e.key === "?") helpOpen = !helpOpen }, { signal: $signal })` compiles into `helpOpen`'s own `_let` signal, so every toggle aborts `$signal`, tears the listener down and registers a fresh one, whereas the same body writing `helpOpen = true` stays a one-time `$setup__script`. The qualification belongs on `docs/reference/language.md` › ### `$signal` too, which teaches this idiom with an empty listener body, the one variant that does not churn, and says `$signal` aborts when "The expression is invalidated" without saying what invalidates it. Scope the sentence to a read of a reactive tag variable rather than of any identifier, since marko `translator/util/references.ts` › `resolveReferencedBindingsInFunction` skips getter, hoisted and dom reads, so the `myButton()` element reference in the section's own example does not subscribe; and cross-link `## <lifecycle>`, whose `onMount` is the run-once tool for registering a listener that reads state.
+
+Check: in the marko checkout, `pnpm run compile -- -o dom -d` on `<let/helpOpen=false><script>document.addEventListener("keydown", (e) => { if (e.key === "?") helpOpen = !helpOpen; }, { signal: $signal });</script><div>${helpOpen}</div>` emits `_let("helpOpen/1", $scope => { _$signalReset($scope, 0); _text(...); $helpOpen__script($scope); })`, while the same body writing `helpOpen = true` leaves `$setup__script($scope)` in `$setup`. Mounted, three `?` presses take the read version's run counter from 1 to 4 and add three `document.addEventListener` calls; the write-only body and a `<lifecycle onMount>` rewrite stay at 1 with none.
diff --git a/agent-feedback/items/2026-08-20-compiler-api-docs.md b/agent-feedback/items/2026-08-20-compiler-api-docs.md
index 294828951..3f0f19f74 100644
--- a/agent-feedback/items/2026-08-20-compiler-api-docs.md
+++ b/agent-feedback/items/2026-08-20-compiler-api-docs.md
@@ -10,3 +10,7 @@ site: docs/guide/low-level-apis.md › ## Writing a Migrator
 `docs/guide/low-level-apis.md` is 379 bytes: one intro paragraph, then `## Writing a Migrator` and `## Writing a Translator` with nothing under either, and it is the only entry `public/llms.txt` offers for the compiler ("Advanced low-level APIs"). Nothing else on the site names the API those sections need. `grep -rniE 'compileSync|compileFile|@marko/compiler|babel-utils' docs/` matches one newsletter sentence, and the generated `/docs/reference-full.md` bundle contains none of it, so an agent asked to write a codemod, a migrator or a bundler integration reverse-engineers `@marko/compiler`'s `index.d.ts`, which exports `compile`, `compileSync`, `compileFile`, `compileFileSync`, `configure`, `getRuntimeEntryFiles` and a `taglib` namespace. The version relationship is unstated too: `marko@6.3.44` depends on `@marko/compiler@^5.42.2`, so a search for the installed compiler's documentation lands on the Marko 5 site, and no page says that pairing is expected. Fill the two sections against the `migrator` and `translator` hooks the taglib loader reads from `marko.json`, and give the compiler entry points a reference page indexed in `llms.txt`.
 
 Check: `grep -rniE 'compileSync|compileFile|@marko/compiler' docs/ | grep -v newsletter` returns nothing and `wc -c docs/guide/low-level-apis.md` prints 379; expect both sections to have bodies and the compiler entry points and their output modes to be documented somewhere under `docs/`.
+
+The `./register` subpath belongs in the same reference. `@marko/compiler/register` self-installs a `require.extensions[".marko"]` hook on require (`packages/compiler/src/register.cjs` › `register`, typed by `register.d.ts`, pinned by `compiler/test/register.test.js`) that compiles each template with `compileFileSync` and forces `modules: "cjs"`, so `require("./hello.marko").default.render(input)` renders a template from a plain Node process with no bundler, and an ESM entry bridges through `createRequire` because the hook does not serve `import("./hello.marko")`. It is the one bundler-free render path the site could describe: `docs/introduction/installation.md` › ## Manual Setup starts from "your preferred bundler", `docs/introduction/integrations.md` › Bundlers lists Vite, Webpack, Rollup and Lasso, and `docs/reference/template.md`'s Node `http.createServer` examples import `./template.marko` without saying what loads it. Document the hook, its CommonJS output and its `output`, `sourceMaps` and `extensions` options alongside the entry points.
+
+Check: `grep -rn -i 'compiler/register\|require.extensions\|node-require' docs public/llms.txt` exits 1. In a scratch dir with a package.json (the compiler resolves `marko/translator` from the nearest package root above `process.cwd()`, and without one the hook throws `Cannot find module 'marko/translator'`) and node_modules resolving marko 6.3.46 with @marko/compiler 5.42.3, with `hello.marko` = `<h1>Hello ${input.name}</h1>`, `node -e 'require("@marko/compiler/register")({output:"html",sourceMaps:false});require("./hello.marko").default.render({name:"Ada"}).then(h=>console.log(String(h)))'` prints `<h1>Hello Ada</h1>`, while `import "@marko/compiler/register"; await import("./hello.marko")` from an `.mjs` throws `ERR_UNKNOWN_FILE_EXTENSION` and the same file's `createRequire(import.meta.url)("./hello.marko").default.render({ name: "Ada" })` prints the same HTML.
diff --git a/agent-feedback/items/2026-08-28-browser-only-setup.md b/agent-feedback/items/2026-08-28-browser-only-setup.md
new file mode 100644
index 000000000..6fc92cac0
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-browser-only-setup.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/introduction/installation.md › ## Manual Setup
+---
+
+# Document the browser-only setup (`marko({ linked: false })`, `index.html`, `Template.mount`) under Manual Setup
+
+`docs/introduction/installation.md` › ## Manual Setup walks through Vite plus `marko()` plus an express SSR server, and the browser-only alternative survives as a parenthetical on the "Add a server" step ("this can be disabled with the Marko plugin's `linked` option"). `linked` appears in one other place under `docs/`, the `docs/reference/lazy-loading.md` note that `linked: false` cannot code-split; `docs/introduction/integrations.md` covers bundlers with no browser build; and `docs/reference/template.md` › ## `Template.mount(input, node, position?)` documents the API, warning that it is "primarily intended to be used in exclusively client rendered environments", without tying it to a build setup. Following Manual Setup and dropping the server file without also passing `linked: false` fails the build with `[marko-vite:pre] You must run the "ssr" build before the "browser" build.`, an error the docs do not explain. Add a Manual Setup subsection assembling the three files a client-only app needs, a `vite.config.ts` with `marko({ linked: false })`, an `index.html` holding a mount node and a module script, and an entry module calling `Template.mount`; carry the lazy-loading note that `linked: false` cannot code-split and link the `Template.mount` section. The site already runs this mode itself in the playground (`src/util/workspace.ts`).
+
+Check: `grep -rn '\blinked\b' docs` prints only `docs/introduction/installation.md:88` (the parenthetical) and `docs/reference/lazy-loading.md:180`, and `grep -rni 'client-only\|SPA' docs` prints nothing. In a scratch dir with marko 6.3.46, @marko/vite 6.1.11 and vite 8.2.2, with `vite.config.ts` = `export default defineConfig({ plugins: [marko({ linked: false })] })`, `index.html` = `<div id="app"></div><script type="module" src="/src/main.ts"></script>`, `src/app.marko` = `<let/count=input.start ?? 0><button onClick() { count++ }>Clicked ${count}</button>` and `src/main.ts` = `App.mount({ start: 3 }, document.getElementById("app")!)`, `npx vite build` prints `✓ 7 modules transformed` plus `dist/assets/index-*.js 4.76 kB` and `npx vite preview` serves a page whose button goes from `Clicked 3` to `Clicked 4` with no server file. The same project with plain `marko()` fails `npx vite build` with `You must run the "ssr" build before the "browser" build.`
diff --git a/agent-feedback/items/2026-08-28-catch-scope-render-errors.md b/agent-feedback/items/2026-08-28-catch-scope-render-errors.md
new file mode 100644
index 000000000..175217438
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-catch-scope-render-errors.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/reference/core-tag.md › ### `@catch`
+---
+
+# Scope `@catch` to errors thrown while rendering the `<try>` content
+
+`docs/reference/core-tag.md` › ### `@catch` says "When a runtime error occurs in the content of the `<try>` or its `@placeholder` attribute tag, the content is replaced", which a reader takes to include the event handlers and effects written in that content. The runtime scopes it to the render path: marko `dom/catch.feat.ts` wraps `runRender` alone, with a comment recording that an error thrown from a `<script>` or `<lifecycle>` body deliberately escapes the flush, and `dom/event.ts` › `handleDelegated` invokes handlers bare. Clicking a `<button onClick() { throw new Error("event boom") }>` inside a `<try>` leaves `@catch` unrendered, leaves the sibling content in place and surfaces one uncaught page error; a `<script>` that throws behaves the same on its first mount and on an update, while a throw during render, initial or on update, and a rejected `<await>` are both caught. Restate the section as the positive rule, that `@catch` covers errors thrown while rendering the content including a rejected `<await>`, and point handler and effect errors at the ordinary window error path.
+
+Check: mount `<try><widget mode=mode/><@catch|err|><div class="caught">caught: ${err.message}</div></@catch></try>`, where widget is `<const/status=health(input.mode)><div class="status">Status: ${status}</div><button onClick() { throw new Error("event boom") }>Poke</button>` and `health` throws for `mode === "render"`. Clicking Poke gives `{ caughtCount: 0, status: "Status: healthy", pageErrors: ["event boom"] }`; flipping `mode` to `"render"` gives `{ caughtCount: 1, caughtText: "caught: render boom", statusCount: 0 }`; a `<try>`-wrapped child whose `<script>` throws gives `{ caughtCount: 0, errs: ["effect boom"] }` with its sibling content still rendered; `<try><await|v|=Promise.reject(new Error("await boom"))>` renders `@catch` with an empty `pageErrors`.
diff --git a/agent-feedback/items/2026-08-28-controllable-counter-optional-count.md b/agent-feedback/items/2026-08-28-controllable-counter-optional-count.md
new file mode 100644
index 000000000..95981c825
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-controllable-counter-optional-count.md
@@ -0,0 +1,12 @@
+---
+type: bug
+impact: med
+effort: low
+site: docs/explanation/controllable-components.md › ### Controllable `<let>`
+---
+
+# Give the controllable `<counter>` example an optional `count` and a `?? 0` default
+
+The counter.marko block under `docs/explanation/controllable-components.md` › ### Controllable `<let>` declares `count: number` as required and binds `<let/count=input.count valueChange=input.countChange>`, while the parent block on the same page renders a bare `<counter/>` labelled "This one holds its own state". `mtc` rejects that usage with TS2345 (`Property 'count' is missing in type '{}' but required in type 'Input'`), and silencing the error does not rescue it: `input.count` is undefined, so the server renders `Count: ` where the page's own bullet promises the behavior of its first example, and the first click makes it NaN. The shape that keeps the uncontrolled, seeded and controlled usages all valid is `count?: number` with `<let/count=input.count ?? 0 valueChange=input.countChange>`, which type-checks for `<counter/>`, `<counter count=5/>`, `<counter count=parentCount countChange(count) {...}/>` and `<counter count:=parentCount/>`. Note in the section that the explicit handler form is required once a default is involved, since `<let/count:=input.count ?? 0>` is a compile error; `docs/reference/core-tag.md` › ### Controllable Let is self-consistent and needs no change.
+
+Check: copy the two blocks under ### Controllable `<let>` verbatim into a project with `@marko/type-check` 3.2.0 as `src/tags/counter.marko` and `src/parent.marko` and run `npx mtc`: it reports `error TS2345` on `<counter/>` in `src/parent.marko` with `Property 'count' is missing in type '{}' but required in type 'Input'`, unchanged with `strict: false`. In the marko checkout, `pnpm run compile -- -o html -d <parent.marko>` and rendering the result gives `<button>Count: <!>0<!--...--></button><button>Count: <!><!--...--></button>`, the second button carrying no number. With `count?: number` and `?? 0`, `npx mtc` reports nothing for the four usages above, while `<let/count:=input.count ?? 0>` fails `pnpm run compile -- -o dom -d` with "Attributes may only be bound to identifiers or member expressions".
diff --git a/agent-feedback/items/2026-08-28-custom-element-attributes-setattribute.md b/agent-feedback/items/2026-08-28-custom-element-attributes-setattribute.md
new file mode 100644
index 000000000..6f07495fb
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-custom-element-attributes-setattribute.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/reference/typescript.md › ### Registering a new native tag (e.g. for custom elements)
+---
+
+# State that attributes on a registered custom element are written with `setAttribute`, never as properties
+
+Every attribute on a `marko.json`-registered custom element goes through marko `packages/runtime-tags/src/dom/dom.ts` › `_attr`, which is `setAttribute(element, name, normalizeAttrValue(value))` with no `name in element` or `customElements.get` branch, and the translator special-cases controllable properties for input, select, textarea, details and dialog alone, so a same-named property setter on the element class is never called. The example under `docs/reference/typescript.md` › ### Registering a new native tag (e.g. for custom elements) reads the other way: it declares `class RangeSliderElement extends HTMLElement { value = 0 }` beside `<range-slider/sliderEl value=threshold step=5 .../>`, so the class field holds its initial value while `getAttribute("value")` tracks the binding, and the class declares no `observedAttributes`, so as printed nothing in it picks the attribute up. State the positive rule on that section and on `docs/reference/native-tag.md`, and show the element-reference idiom for writing a property, `<x-datepicker/picker value=newDate/>` with `picker().value = newDate` from a `<script>` body. `docs/guide/library-integration.md` › ### Consuming in Marko and ### Using Marko in a Web Component are empty headings and are the natural second home for it.
+
+Check: `sed -n '/export function _attr(/,/^}/p' packages/runtime-tags/src/dom/dom.ts` in the marko checkout shows the `setAttribute` call as the whole body. In a `linked: false` Vite page with `marko.json` = `{"<x-datepicker>":{"html":true}}` and an `x-datepicker` class defining `static get observedAttributes(){return["value"]}` plus a counting `set value(v)` and `attributeChangedCallback`, rendering `<let/newDate="2025-06-15"/><x-datepicker value=newDate/>` and then reassigning `newDate` reports `{ propertySets: 0, attributeSets: 2, setterCalls: [] }` with `outerHTML` `<x-datepicker value="2026-01-01"></x-datepicker>`. Rendering the typescript.md example with its class registered leaves `el.value` at its class-field value while `el.getAttribute("value")` goes `20` then `42`.
diff --git a/agent-feedback/items/2026-08-28-custom-event-handler-typing.md b/agent-feedback/items/2026-08-28-custom-event-handler-typing.md
new file mode 100644
index 000000000..37fc4a1ca
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-custom-event-handler-typing.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: low
+effort: low
+site: docs/reference/typescript.md › ### Registering a new native tag (e.g. for custom elements)
+---
+
+# Show how to declare a custom element's `CustomEvent` handler in the native tag registration
+
+`AttrEventHandler` (marko `packages/runtime-tags/tags-html.d.ts`) brands a handler's event as `Event` intersected with a `currentTarget` string literal carrying the delegation guidance, deliberate since #3817. Any `currentTarget` brand makes that type non-comparable with `CustomEvent<T>`, so a handler inherited from `Marko.HTMLAttributes` cannot reach a custom element's `detail` the ordinary way: `(e as CustomEvent<string>).detail` is TS2352, annotating the parameter is TS2322, and re-declaring `onChange` in an interface that extends `Marko.HTMLAttributes<T>` is TS2430; only a widening double cast compiles. The supported route is to declare the event on the attributes interface, which for a custom name needs nothing extra (`interface XAttrs extends Marko.HTMLAttributes<T> { onDatepickerChange?: (e: CustomEvent<string>, target: T) => void }`) and for a name colliding with a standard DOM event needs `extends Omit<Marko.HTMLAttributes<T>, "onChange">`. Add both spellings, and the collision rule, to the registration section, which today shows `onChange(evt, target) { target.value }` alone.
+
+Check: in a project with `@marko/type-check` 3.2.0 and `marko.json` `{ "<x-datepicker>": { "html": true } }`, `npx mtc -p tsconfig.json -d condensed` over `<div onChange(e) { const d: string = (e as CustomEvent<string>).detail }/>` reports `error TS2352 Conversion of type 'Event & { currentTarget: "Marko delegates events, ..."; }' to type 'CustomEvent<string>' may be a mistake`, and over `<div onChange(e: CustomEvent<string>) { console.log(e.detail) }/>` reports `error TS2322 Type '(e: CustomEvent<string>) => void' is not assignable to type 'AttrEventHandler<Event, HTMLDivElement>'`, while `e as Event as CustomEvent<string>` and `e as unknown as CustomEvent<string>` report nothing. Registering `interface DatepickerAttributes extends Omit<Marko.HTMLAttributes<DatepickerElement>, "onChange"> { value?: string; onChange?: (e: CustomEvent<string>, target: DatepickerElement) => void }` as `Marko.NativeTags["x-datepicker"]` leaves `<x-datepicker value=picked onChange(e, target) { const d: string = e.detail } onClick(e, target) { console.log(e.clientX, target.value) }/>` clean, while `e.clientX` inside `onChange` still reports TS2339.
diff --git a/agent-feedback/items/2026-08-28-custom-tag-html-true-registration.md b/agent-feedback/items/2026-08-28-custom-tag-html-true-registration.md
new file mode 100644
index 000000000..10abee7d2
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-custom-tag-html-true-registration.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/reference/custom-tag.md › ## Installed Custom Tags
+---
+
+# Show the marko.json `"html": true` registration for unknown native tags on custom-tag.md
+
+The compiler knows 111 HTML tags (`marko/packages/compiler/src/taglib/marko-html.json`), and anything outside that list, `<center>`, `<o:p>` or a custom element, fails to compile with an error linking to `docs/reference/custom-tag.md#relative-custom-tags`. The supported registration is `{ "<center>": { "html": true } }` in a `marko.json` beside the template or in any ancestor directory (taglib loader `loadTagFromProps.js` › `html`, consumed by compiler `babel-utils/tags.js` › `isNativeTag`), after which both html and dom output emit the element verbatim. On the site that registration appears only under `docs/reference/typescript.md` › ### Registering a new native tag (e.g. for custom elements), a page a JavaScript author chasing `<center>` never opens, while the page the error links to shows `marko.json` in its package `exports` form alone. State the rule and the example on `custom-tag.md` next to that existing `marko.json` block, and cross-link it from `docs/reference/native-tag.md` and from the typescript.md section.
+
+Check: `printf '<center>x</center>\n' > a/x.marko`, then in the marko checkout `pnpm run compile -- -o html -d a/x.marko` exits 1 with ``Unable to find entry point for [custom tag](https://markojs.com/docs/reference/custom-tag#relative-custom-tags) `<center>`. Did you mean `<meter>`?``; adding `{ "<center>": { "html": true } }` as `marko.json` beside the file makes the same command write `x.marko.js` containing `_html("<center>x</center>")`, and `-o dom` likewise. `grep -rn '"html": true' docs` hits only `docs/reference/typescript.md`, and `grep -n -i 'marko.json\|"html"' docs/reference/custom-tag.md docs/reference/native-tag.md` hits only custom-tag.md's package `exports` example.
diff --git a/agent-feedback/items/2026-08-28-escaping-rules-per-context.md b/agent-feedback/items/2026-08-28-escaping-rules-per-context.md
new file mode 100644
index 000000000..24242b802
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-escaping-rules-per-context.md
@@ -0,0 +1,21 @@
+---
+type: dx
+impact: low
+effort: low
+site: docs/reference/language.md › ### Dynamic Text
+---
+
+# State the per-context escaping rules for `${}`, static text, `<textarea>` bodies and `<html-comment>`
+
+`docs/reference/language.md` › ### Dynamic Text says only that an interpolated value is "automatically escaped to avoid XSS", and ## Attributes says an attribute literal is a JavaScript string rather than an html attribute string. The runtime rules are per-context, each deliberate and carrying an intent comment, and they are stated on no page or cheatsheet: `${}` in text escapes `<`, `&` and CR to `&lt;`, `&amp;` and `&#13;` and leaves `>` alone (marko `packages/runtime-tags/src/html/content.ts` › `_escape`); static text is emitted verbatim, so `&copy;`, `&#169;`, `&unknownent;` and a bare `&` all survive; a static `<textarea>` body is decoded and then re-escaped by the value path (`translator/core/textarea.ts`), the one text context where a static body is rewritten; `<html-comment>` escapes `>` alone (`content.ts` › `_escape_comment`); and a dynamic attribute value escapes the quote character in use, CR, and an `&` that would start a character reference (`html/attrs.ts` › `escapeDoubleQuotedAttrValue`), so an interpolated `a & b < c > d` round-trips into the attribute unchanged. Readers pasting markup that carries character references need the rule per context to predict the output. Add the character sets under ### Dynamic Text and ## Attributes, the decode rule under `docs/reference/native-tag.md` › #### `<textarea>`, and the comment rule under `docs/reference/core-tag.md` › ## `<html-comment>`.
+
+```marko
+<div title="&amp;">ampent</div>
+<p>x &amp; y &copy; &#169; &unknownent; & z</p>
+<textarea>note &lt; & more</textarea>
+<span>${"<b>&amp;"}</span>
+<html-comment>${"a > b < c"}</html-comment>
+<div title=`${"a & b < c > d"}`>attr-interp</div>
+```
+
+Check: render the template above with marko 6.3.46 html output. It prints `<div title="&amp;amp;">ampent</div><p>x &amp; y &copy; &#169; &unknownent; & z</p><textarea>note &lt; &amp; more</textarea><span>&lt;b>&amp;amp;</span><!--a &gt; b < c--><div title="a & b < c > d">attr-interp</div>`. `grep -n -i 'escap\|character reference\|entit' docs/reference/language.md` matches only the XSS note and the Unescaped Text section, and the same grep over `docs/reference/native-tag.md` exits 1.
diff --git a/agent-feedback/items/2026-08-28-installation-manual-setup-marko-latest.md b/agent-feedback/items/2026-08-28-installation-manual-setup-marko-latest.md
new file mode 100644
index 000000000..439547a38
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-installation-manual-setup-marko-latest.md
@@ -0,0 +1,12 @@
+---
+type: bug
+impact: high
+effort: low
+site: docs/introduction/installation.md › ## Manual Setup
+---
+
+# Point installation.md's manual setup at `npm install marko`, not `marko@next`
+
+`docs/introduction/installation.md` › ## Manual Setup tells a newcomer to run `npm install marko@next` on its Install Marko step. Since marko 6.1.9 (#3223, "Release marko@5 as `m5` dist-tag and marko@6 as `latest` dist-tag") the release script publishes `marko` to `latest` and `m5` only, so the `next` dist-tag is frozen at 6.1.8 while `latest` is 6.3.46, and the first manual-setup step installs a runtime two minor lines behind the one the rest of the site documents (no assets and lazy loading, no sync `<await>`, none of the 6.2 or 6.3 changes). The site already states the current rule elsewhere: `docs/newsletter/june-2026.md` › ## Latest on npm says "The `marko` package is tagged `latest` on npm, so `npm install marko` brings in the Tags API runtime". Change the line to `npm install marko`.
+
+Check: `grep -rn '@next' docs` prints one line, `docs/introduction/installation.md:52:   npm install marko@next`; `npm view marko dist-tags --json` prints `{"m3":"3.14.4","m2":"2.11.3","m4":"4.28.10","next":"6.1.8","m5":"5.39.38","latest":"6.3.46"}` and `npm view marko@next version` prints `6.1.8`.
diff --git a/agent-feedback/items/2026-08-28-let-null-tag-variable-typing.md b/agent-feedback/items/2026-08-28-let-null-tag-variable-typing.md
new file mode 100644
index 000000000..28f6bd38b
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-let-null-tag-variable-typing.md
@@ -0,0 +1,12 @@
+---
+type: bug
+impact: med
+effort: low
+site: docs/explanation/serializable-state.md › ## Unserializable Data
+---
+
+# Fix the `<let/x=null>` examples in serializable-state.md and document how to type a `<let>` tag variable
+
+A `<let>` tag variable takes the exact type of its initial value with no widening, so under `strictNullChecks`, which the default `@marko/run` TypeScript scaffold turns on, `<let/x=null>` is typed `null`: every later assignment is TS2322 and a call is TS2349 on `never`, unlike plain TypeScript where `let x = null` evolves. `docs/explanation/serializable-state.md` ships that form twice. The NOTE under ## Unserializable Data (`<let/handler=null>` then `handler?.(); handler = onSecondClick`) fails `mtc` verbatim, and the ## Shared References example (`<let/muted=null>` then `muted = comment.author`) fails as soon as the surrounding `Input` is typed. Two spellings work and neither is shown anywhere on the site: `<let/x=null as string | null>` and `<let<string | null>/x=null>`, while the annotation form `<let/x:(string | null)=null>` does not, which language-server item 2026-07-18-tag-var-union-annotation.md already covers. Fix both examples and add the typing sentence next to `<let>` in `docs/reference/typescript.md` › ## TypeScript Syntax in `.marko` and `docs/reference/core-tag.md` › ## `<let>`.
+
+Check: in a `@marko/run` scaffold with `@marko/type-check` and `strict: true`, paste the serializable-state.md NOTE verbatim into `src/tags/k73-doc.marko`, add `src/tags/k73-forms.marko` holding `<let/a=null>`, `<let/b=null as string | null>`, `<let<string | null>/c=null>`, `<let/d:(string | null)=null>` and `<button onClick() { a = "x"; b = "x"; c = "x"; d = "x" }>x</button>`, then run `npx mtc`. The docs snippet reports `error TS2349 ... Type 'never' has no call signatures` and `error TS2322 Type '() => void' is not assignable to type 'null'`; of the four forms only `a` and `d` report `error TS2322 Type '"x"' is not assignable to type 'null'`. `<let/handler=null as (() => void) | null>` makes the docs snippet exit 0, and with `"strict": false` the snippet passes, which is why the site's own `pnpm run type-check` (`marko-type-check` over `src/`, not markdown snippets) never saw it.
diff --git a/agent-feedback/items/2026-08-28-llms-txt-getting-started-description.md b/agent-feedback/items/2026-08-28-llms-txt-getting-started-description.md
new file mode 100644
index 000000000..f885ff2fb
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-llms-txt-getting-started-description.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: low
+effort: low
+site: public/llms.txt › ## Introduction
+---
+
+# Retire the inherited "Quick start guide" llms.txt description for getting-started.md
+
+`public/llms.txt` › ## Introduction indexes `docs/introduction/getting-started.md` as "Quick start guide for new projects", but that page is the Marko 6 version note, one orientation paragraph, ## Prerequisite Knowledge and ## Next Steps; the create command lives on `docs/introduction/installation.md` and `docs/marko-run/getting-started.md`. The description was inherited rather than written for the page: commit ec6e95618 moved the entry from the Marko Run quick start, which does carry `npm init marko`, kept the old text, and gave the new Marko Run entry its own "Quick start for Marko Run". The page is also the docs landing page, since `src/routes/docs/+handler.ts` redirects `/docs` to it and the home CTA links there, so the stale line is the index's first Introduction entry. Reword it to describe orientation and prerequisites, or put the create command on the page.
+
+Check: `grep -c 'npm init marko' docs/introduction/getting-started.md` prints `0` while `grep -n 'Getting Started' public/llms.txt` prints `32:- [Getting Started](/docs/introduction/getting-started.md): Quick start guide for new projects` beside `79:- [Getting Started](/docs/marko-run/getting-started.md): Quick start for Marko Run`. `git log -S 'introduction/getting-started.md): Quick start guide for new projects' -- public/llms.txt` returns ec6e95618, whose diff moves the link and leaves the description untouched.
diff --git a/agent-feedback/items/2026-08-28-nested-reactivity-case-3.md b/agent-feedback/items/2026-08-28-nested-reactivity-case-3.md
new file mode 100644
index 000000000..cd68d2362
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-nested-reactivity-case-3.md
@@ -0,0 +1,12 @@
+---
+type: cleanup
+impact: med
+effort: med
+site: docs/explanation/nested-reactivity.md › ## Case 3: Complex Hoisted State
+---
+
+# Write the Case 3 section of nested-reactivity.md and drop the `<mut>` TODO comment
+
+`docs/explanation/nested-reactivity.md` ends at `## Case 3: Complex Hoisted State`, whose entire body is an HTML comment reading `TODO: discuss <mut> tag`. The section is load-bearing: the page's TLDR promises "Three approaches" and its intro promises "3 ways", and the heading is a live sidebar link, since markodown's heading renderer records every h2 into `meta.headings` and `src/routes/docs/+layout.marko` feeds those to `TocTree`, so a reader lands in an empty `<section id="case-3-complex-hoisted-state">`. The raw markdown is served as-is (`public/docs` is a symlink to `../docs`) and `public/llms.txt` points agents at that URL, so the comment also promises a `<mut>` tag that Marko does not ship. Write the section against the pattern Case 2 already sets up, an immutable update with a keyed `<for>`, and remove the comment.
+
+Check: `tail -3 docs/explanation/nested-reactivity.md` prints the `## Case 3: Complex Hoisted State` heading, a blank line and the TODO comment as the file's last lines. `grep -rnw mut` over `docs/`, the marko packages and both cheatsheets returns that one line, and in the marko checkout `pnpm run compile -- -o dom -d` on `<let/x={a:1}/>` plus `<mut=x.a>2</mut>` fails with ``Unable to find entry point for [custom tag](https://markojs.com/docs/reference/custom-tag#relative-custom-tags) `<mut>`. Did you mean `<dt>`?``
diff --git a/agent-feedback/items/2026-08-28-serve-cheatsheets.md b/agent-feedback/items/2026-08-28-serve-cheatsheets.md
new file mode 100644
index 000000000..1bcb9a60d
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-serve-cheatsheets.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: public/llms.txt › ## Reference
+---
+
+# Serve the shipped cheatsheets from markojs.com and index them in llms.txt
+
+`marko/packages/runtime-tags/cheatsheet.md` and `run/packages/run/cheatsheet.md` ship inside packages this site already depends on, and the one mention across `public/llms.txt`, `docs/` and `src/` is the July 2026 newsletter sentence announcing that the file exists in the package. The pointers a reader gets instead are node_modules paths: the compiler appends `Fix guide: READ node_modules/marko/cheatsheet.md before writing a fix.` to a compile error under a coding agent, and the generated `.marko-run/routes.d.ts` header names `@marko/run/cheatsheet.md`. The sheets carry rules stated on no docs page: retrying a caught `<try>` by bumping a key on a wrapping `<for>`, `<await>` re-showing its `@placeholder` when handed a new promise in the browser, and `tsc` skipping `.marko` so a type-broken template still exits 0, where `docs/introduction/installation.md` says only to use `mtc` "instead of `tsc`". Serve both files at their own routes through a handler modelled on `src/routes/docs/_llms/reference-full%2emd+handler.ts`, which already reads a file off disk and returns text, and index those routes in `public/llms.txt` › ## Reference; mirror the package files rather than folding their prose into a docs page, since the `<for>` re-key recipe is the kind of workaround the writing guidelines keep out of docs.
+
+Check: `grep -rn -i cheatsheet public/llms.txt docs/ src/` returns only `docs/newsletter/july-2026.md:83`. `curl -sL https://markojs.com/llms.txt | grep -i cheatsheet` is empty and `curl -sL https://markojs.com/docs/reference-full.md | grep -c -i cheatsheet` prints `0`, while `curl -s -o /dev/null -w '%{http_code}' -L` prints `404` for `/docs/cheatsheet.md`, `/cheatsheet`, `/docs/cheatsheet` and `/docs/reference/cheatsheet.md` and `200` for `/llms.txt` and `/docs/reference-full.md` as controls. `grep -rniE 'retry|reset the|recover' docs/ | grep -v newsletter` is empty and `grep -rnw tsc docs/` hits only `docs/introduction/installation.md`.
diff --git a/agent-feedback/items/2026-08-28-starter-templates-and-flags.md b/agent-feedback/items/2026-08-28-starter-templates-and-flags.md
new file mode 100644
index 000000000..2e65a96e8
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-starter-templates-and-flags.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: low
+effort: low
+site: docs/introduction/installation.md › ## Marko Run Setup (Recommended)
+---
+
+# Name the four starter templates and the non-interactive flags beside `npm init marko -- -t basic`
+
+`docs/introduction/installation.md` › ## Marko Run Setup (Recommended) shows `npm init marko -- -t basic` and no other template name or CLI flag, and `docs/marko-run/getting-started.md` › ## Using a Template shows a bare `npm init marko` with the phrase "After choosing a template and project name" and names none. An interactive run does offer `app`, `basic`, `library` and `vite-express`, but `@marko/create` skips every prompt under CI, an AI agent or a piped stdin (`acceptDefaults = yes || isAgent() || isCI()`), so the readers who must pass `-t` are exactly the ones who never see the list, and their fallbacks stop short of it: the `create-marko` alias that `npm init marko` runs publishes no README, and `@marko/create`'s README names `basic` alone and omits `--no-install` and `--no-git`, which only `--help` lists. Put the four names beside the `-t basic` line, say they are examples from marko-js/examples (minus the `-marko-5` ones) so the list is understood to track that repo, and add `-n/--name`, `-y/--yes`, `--no-install` and `--no-git`.
+
+Check: `grep -rn -e 'vite-express' -e '\-\-no-git' -e '\-\-no-install' -e '\-t library' -e '\-t app' docs public` prints nothing, while `grep -rn 'npm init marko' docs` prints `docs/introduction/installation.md:19:npm init marko -- -t basic` and `docs/marko-run/getting-started.md:12`. `npm view create-marko readme | wc -c` prints `0` and `npm pack create-marko@6.3.0 && tar tzf create-marko-6.3.0.tgz` lists only `package/package.json`, `package/bin.mjs` and `package/LICENSE`; `npm view @marko/create readme | sed -n '/## Options/,$p'` shows `basic` as its only example name and no `--no-install` or `--no-git`, both of which `npx -y create-marko@6.3.0 --help` prints. In a marko-js/examples checkout, `ls examples | grep -v -- -marko-5` prints `app basic library vite-express`.
diff --git a/agent-feedback/items/2026-08-28-tag-library-package-exports.md b/agent-feedback/items/2026-08-28-tag-library-package-exports.md
new file mode 100644
index 000000000..4294d9a1f
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-tag-library-package-exports.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/reference/custom-tag.md › ## Installed Custom Tags
+---
+
+# Document that a tag library's package.json `exports` map must expose the directory its marko.json names
+
+A tag discovered through an installed package's `marko.json` is imported by the bare specifier `<packageName>/<path relative to the package root>`, for example `@acme/ui/dist/tags/acme-icon/index.marko`. That is deliberate since compiler #3418 and #3501, so a pnpm virtual-store realpath is never emitted, and the specifier carries the file's on-disk location rather than any alias the library declares. A library that ships a package.json `exports` map therefore has to expose the directory its `marko.json` `exports` key names (`"./dist/*": "./dist/*"`); the library's own `"./tags/*": "./dist/tags/*/index.marko"` alias does not satisfy it. Without that entry the consumer compiles clean and then fails in the bundler on an import nobody wrote, with no template path, tag name or `marko.json` in the message. State the requirement on `docs/reference/custom-tag.md` › ## Installed Custom Tags beside the `marko.json` `"exports"` key, and on `docs/guide/publishing-components.md`, which currently has headings and no body.
+
+Check: in a consumer of a tag library whose `marko.json` is `{"exports": "./dist/tags"}` and whose package.json `exports` map has no entry covering `./dist/*`, and whose templates use the library only through tag discovery, `node -e 'const {compileSync}=require("@marko/compiler");const r=compileSync("<acme-icon name=\"x\"/>",require("path").resolve("src/probe.marko"),{output:"html"});console.log(r.code.split("\n").filter(l=>l.includes("acme")).join("\n"))'` prints `import _acmeIcon from "@acme/ui/dist/tags/acme-icon/index.marko";` with `diagnostics: []`. `npx vite build --app` then fails with `[rolldown:vite-resolve] "./dist/tags/acme-icon/index.marko" is not exported under the conditions ["module", "node", "production", "import"] from package .../node_modules/@acme/ui`, and `npx vite` plus `curl localhost:<port>/` returns 500 with the same message. Adding `"./dist/*": "./dist/*"`, or deleting the `exports` field, makes both pass; `npx mtc` exits 0 either way.
diff --git a/agent-feedback/items/2026-08-28-template-mount-element-target.md b/agent-feedback/items/2026-08-28-template-mount-element-target.md
new file mode 100644
index 000000000..1316a985c
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-template-mount-element-target.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: med
+effort: low
+site: docs/reference/template.md › ## `Template.mount(input, node, position?)`
+---
+
+# State that `Template.mount` renders into an element, not a ShadowRoot or DocumentFragment
+
+`Template.mount` describes `node` as "a reference to the DOM node" and marko `packages/runtime-tags/index.d.ts` types it `reference: Node`, so a `ShadowRoot` or a `DocumentFragment` type-checks, while two deliberate runtime decisions make either target unusable. `dom/renderer.ts` hands the parent's `namespaceURI` to `dom/parse-html.ts` › `parseHTML`, which keys its cached `<template>` parser on it, so a namespace-less parent parses the markup as foreign content: `<button>` and `<input>` come back with `namespaceURI === null` and without their `HTMLElement` prototypes, `click` and `focus` are undefined, and the `<input>` is not a form control. Separately, `dom/event.ts` › `delegate` installs one capture listener on `document`, and a shadow tree's events are re-targeted to the host before they reach it, so `onClick` and `value:=` inside a shadow tree stay quiet. Both decisions carry a won't-fix comment in marko source and neither is stated on the site, so put the positive rule on the `Template.mount` section and under `docs/reference/native-tag.md` › #### Delegation: `mount` renders into an element, and a Marko island inside a web component attaches its own root element and mounts there.
+
+Check: build a `linked: false` Vite page that mounts `<let/count=0/><let/text="a"/><button class="k49-btn" onClick(){count++}>clicked ${count}</button><input class="k49-input" value:=text><div class="k49-text">text=${text}</div>` into a light `<div>`, into `host.attachShadow({mode:"open"})` and into a `DocumentFragment` later appended to the document, then drive each with a real `page.mouse.click` and a composed `input` event. The light target reports `HTMLButtonElement`/`HTMLInputElement` and reaches `clicked 1` and `text=light-typed`; the shadow target reports `Element`/`Element`, serializes as `<input class="k49-input"></input>` and stays at `clicked 0` and `text=a` with an empty `pageErrors`; the appended fragment reaches `clicked 1` while keeping its null-namespace nodes. In the marko checkout `grep -rn -i shadow packages/runtime-tags/src/dom/` prints the two won't-fix comments, in `parse-html.ts` and `event.ts`.
diff --git a/agent-feedback/items/2026-08-28-validation-body-without-validator.md b/agent-feedback/items/2026-08-28-validation-body-without-validator.md
new file mode 100644
index 000000000..0fc3e63d9
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-validation-body-without-validator.md
@@ -0,0 +1,12 @@
+---
+type: bug
+impact: med
+effort: low
+site: docs/marko-run/validation.md › ## Request Bodies
+---
+
+# Correct validation.md on `ctx.body` when a body option carries only limits
+
+`docs/marko-run/validation.md` › ## Request Bodies states "With no validator, it resolves to the raw parsed body." @marko/run builds the `ctx.body` thenable only when the route's merged options carry a validator (`packages/run/src/runtime/internal.ts` › `createContext`, guarding on `route.options.json?.validator || route.options.form?.validator`), so an options object holding only limits leaves `ctx.body` `undefined` at runtime and typed exactly `undefined`, and `readBody` counts such an option as contributing limits alone, so once a sibling option supplies a validator the same request is rejected 415. With no validator anywhere the request quietly succeeds with an undefined body and the declared `maxBytes` is never enforced, which is the more dangerous shape because nothing errors. The rest of the ecosystem already states the rule, in run's README, its cheatsheet's identity-validator recipe and the `Context.body` JSDoc, so replace the sentence with the `json: (value) => value` recipe and say that an option carrying only limits does not accept its media type.
+
+Check: in a `@marko/run` app add `src/routes/k75raw/+handler.ts` = `export const POST = Run.POST({ form: { maxBytes: 16_384 } }, async (ctx) => Response.json({ typeofBody: typeof ctx.body, body: (await ctx.body) ?? null }));`, `src/routes/k75id/+handler.ts` with `form: { validator: (value) => value, maxBytes: 16_384 }` and `src/routes/k75mix/+handler.ts` with `json: (value) => value, form: { maxBytes: 16_384 }`, then `npx marko-run build && PORT=4905 node dist/index.mjs`. `curl -X POST -H 'content-type: application/x-www-form-urlencoded' -d 'a=1&b=2'` returns `{"typeofBody":"undefined","body":null}` with HTTP 200 from `/k75raw`, `{"typeofBody":"object","body":{"a":"1","b":"2"}}` with HTTP 200 from `/k75id`, and HTTP 415 from `/k75mix`. Annotating `const probe: string = await ctx.body` in the first route makes `npx mtc` report `error TS2322 Type 'undefined' is not assignable to type 'string'`.
diff --git a/agent-feedback/items/2026-08-28-whitespace-line-break-placeholder.md b/agent-feedback/items/2026-08-28-whitespace-line-break-placeholder.md
new file mode 100644
index 000000000..a780045aa
--- /dev/null
+++ b/agent-feedback/items/2026-08-28-whitespace-line-break-placeholder.md
@@ -0,0 +1,12 @@
+---
+type: dx
+impact: low
+effort: low
+site: docs/reference/language.md › ## Whitespace
+---
+
+# Say that a line break next to a `${}` placeholder is removed, not only between two tags
+
+`docs/reference/language.md` › ## Whitespace states the rule as "Whitespace that begins with a line break is removed entirely at the start and end of a tag's content and between two tags", and its WARNING repeats it as "A line break between two tags leaves no space between them". In whitespace-collapsing markup the parser drops any whitespace-only run that begins with a line break wherever it sits, so a `${}` placeholder behaves exactly like a tag for that rule: `<b>Total:</b>` followed by a newline and `${input.amount}` renders `<b>Total:</b>5`, and two placeholders on consecutive lines render glued together, while a run that carries content keeps its line break as one space on either side of a placeholder. An author formatting a template across lines therefore loses a separator the page's wording promises to keep. Restate the rule as "a whitespace-only run beginning with a line break is removed", say a `${}` placeholder counts as a tag for it, extend the WARNING's advice to keep a separating space on the placeholder's own line, and leave the existing `<pre>`, `<textarea>`, `<script>` and `<style>` carve-out as is.
+
+Check: with marko 6.3.46, `require("@marko/compiler/register")({ output: "html", sourceMaps: false })` then rendering `<div><b>Total:</b>\n${input.amount}</div>\n<div><b>Total:</b>\nnow</div>\n<p>${input.a}\n${input.b}</p>\n<p>foo\n${input.a}</p>` with `{amount:5,a:"A",b:"B"}` prints `<div><b>Total:</b>5</div><div><b>Total:</b> now</div><p>AB</p><p>foo A</p>`. The Whitespace section predicts a space before each placeholder.
diff --git a/cspell.json b/cspell.json
index 0ee285e8a..6ee995c1a 100644
--- a/cspell.json
+++ b/cspell.json
@@ -7,6 +7,7 @@
     "afterbegin",
     "afterend",
     "Algolia",
+    "ampent",
     "apos",
     "autofocus",
     "beforebegin",
@@ -19,9 +20,11 @@
     "Campolo",
     "caseycarroll",
     "cheatsheet",
+    "cheatsheets",
     "codegen",
     "codespan",
     "contenteditable",
+    "datepicker",
     "dblclick",
     "defunkt",
     "Delisle",
@@ -29,7 +32,9 @@
     "desugared",
     "desugars",
     "emdash",
+    "entit",
     "esbuild",
+    "escap",
     "Fastly",
     "figcaption",
     "flexsearch",
@@ -39,6 +44,7 @@
     "hrefs",
     "htmljs",
     "importmap",
+    "interp",
     "Jetpack",
     "jridgewell",
     "keymap",
@@ -62,6 +68,7 @@
     "packument",
     "Piercey",
     "popovertarget",
+    "realpath",
     "recents",
     "Referer",
     "renderable",