docs(agent-feedback): add agent-feedback setup and take over the streaming render gap

Author: DylanPiercey

AGENTS.md

@@ -0,0 +1,7 @@
+# @marko/testing-library
+
+Simple and complete Marko testing utilities that encourage good testing practices.
+
+## 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.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

agent-feedback/README.md

@@ -0,0 +1,39 @@
+# 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.
+
+## When to add an entry
+
+While working on any task, record anything a future contributor should act on:
+
+- 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`
+
+## Rules
+
+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.
+
+## Resolving a "won't fix" item
+
+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.
+
+## Entry format
+
+```md
+## <one-line imperative summary>
+
+`<primary/file/path.ts>` › `<nearestStableSymbol>` | 2026-07-02 | impact:<low|med|high> | effort:<low|med|high>
+
+<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.>
+```

agent-feedback/bugs.md

@@ -0,0 +1,9 @@
+# Suspected Bugs
+
+Out-of-scope defects noticed while working on something else. Format and rules: [README.md](README.md).
+
+## Consume the first render chunk in `render()` instead of awaiting the completed stream
+
+`src/index.ts` › `render` | 2026-07-30 | impact:med | effort:med
+
+The Marko 6 branch does `String(await (template as any).render(input))`, and that await settles only once marko's `ServerRendered` boundary reaches `FlushStatus.complete`, so `*.server.test.ts` can never observe an `<await>`/`<try>` placeholder or any intermediate streaming state — the HTML handed to `JSDOM.fragment` is always the fully drained output, and a fixture whose `load()` promise never settles hangs `render()` until vitest's timeout with no diagnostic. `toString()` is not an escape hatch: marko throws "Cannot consume asynchronous render with 'toString'" while the render is still pending. Nothing is needed from marko — the object returned by `template.render(input)` already exposes `[Symbol.asyncIterator]()`, `pipe()` and `toReadable()`, and a `for await` over a `<try><await>` fixture yields the `Loading…` placeholder in chunk one — so the fix is local: read the first chunk and stop, either as the default or behind a new flag on `RenderOptions` in `src/shared.ts`, leaving the Marko 3/4/5 callback branch untouched. Note CI does not cover this path today: `devDependencies` pins `marko@^5.39.13` while `peerDependencies` allows `3 - 6`, so reproducing needs a Marko 6 install. Re-verify by adding a `<try><await>` fixture under `src/__tests__/fixtures/` plus a case in `src/__tests__/render.server.test.ts` asserting the placeholder text, then running `pnpm test` — today that case sees only resolved content, or times out when the promise never settles.

agent-feedback/cleanup.md

@@ -0,0 +1,3 @@
+# Cleanup
+
+Duplication, dead code, inconsistencies, refactor opportunities. Format and rules: [README.md](README.md).

agent-feedback/dx.md

@@ -0,0 +1,3 @@
+# Developer Experience
+
+Friction in builds, tests, tooling, or repo workflows. Format and rules: [README.md](README.md).

agent-feedback/perf.md

@@ -0,0 +1,3 @@
+# Performance
+
+Runtime speed and bundle size opportunities. Format and rules: [README.md](README.md).

agent-feedback/unclear.md

@@ -0,0 +1,3 @@
+# Unclear Code & Docs
+
+Things that were hard to understand, and what would have clarified them. Format and rules: [README.md](README.md).