Tighten LLM-facing docs: generator preamble strip + AGENTS.md Docs Verification refactor + guide.md dedupe#349
Merged
brianmhunt merged 5 commits intomainfrom Apr 21, 2026
Merged
Conversation
Stripped templated boilerplate from
`tko.io/scripts/generate-verified-behaviors.mjs`:
- Dropped the per-file "## When to Read This" heading + derived
sentence. The title + one-line description already said the
same thing.
- Replaced the "## Status" bullet block with a single inline
line: `status: <s> · specs: <path> · curated: <path>`.
More grep-friendly (single-pattern match) and same info.
- Shortened the generated-notice from two lines to one:
"Generated from package discovery + curated JSON.
Unit-test-backed only."
- Removed the "Package-scoped behavior summaries for agents.
Every package gets a file." preamble from the index.
- Deleted now-unreferenced helpers `statusSummary` and
`lowerFirst`.
Regenerated all 26 verified-behaviors/*.md files from the new
template. Byte totals across the set: ~44KB → ~36KB (~18%
cut). Every downstream agent that loads the verified-behaviors
pack on session start sees that saving amortized.
No semantic loss: all three status paths still render
correctly (curated, tests-present-needs-curation, no-tests);
the charter ("unit-test-backed only") survives in compressed
form; links and behavior bullets are unchanged.
Adversarial pass: Explore subagent on scripts + regen output.
Result: clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
AGENTS.md is loaded every agent session. Its "Docs Verification" subsection was 7 lines of playwright-cli workflow detail — the long-form flow (close-all, open, snapshot, click, esbuild-status checks) rarely applies to the typical docs edit, and when it does, the agent can follow a link. Shrunk AGENTS.md to a one-paragraph mandate that names the minimum (`bun run build` in `tko.io/` produces a clean Astro build; Open-in-Playground buttons must render on pages with TSX examples) and links to the full flow. The original headless-playwright steps now live under a new "## Docs verification" section in `tko.io/public/agents/process.md`. Also added to process.md: a note that `tko.io/public/agents/verified-behaviors/*.md` are regenerated from `packages/*/verified-behaviors.json` on every build — saves a future agent from making the same hand-edit-to- generated-file mistake. Net AGENTS.md delta vs main: −6 lines. Net process.md delta vs main: +13 lines (loaded only when the link is followed). Adversarial pass: Explore subagent. Flagged 2 items, both false positives: (a) repo-relative markdown links need the https:// protocol — wrong, relative paths resolve for Claude Code and standard markdown renderers; (b) orphan risk means the 2-line headless flow should re-embed in AGENTS.md — wrong direction per the session goal of slimming AGENTS.md, the link-on-demand pattern is deliberate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The Gotchas section had a weaker form of the
"don't create reactive primitives inside a computed's evaluator"
rule that covered only `computed()` and `subscribe()`. The
teaching version in the Observables subsection (line 41)
and the llms.txt Gotchas bullet both already covered all three
primitives, so the Gotchas bullet was out of date.
Rewrote the Gotcha to match, plus a cross-ref back to the
teaching section. Kept the explanation honest about the
difference between the three primitive types:
- `ko.computed()` + `.subscribe()` inside the evaluator =
instance plus live subscriptions leak on every re-run —
memory + CPU unbounded.
- `ko.observable()` / `ko.observableArray()` inside the
evaluator = instance allocation leaks (no subscription
tail), still waste but not the same CPU spiral.
This removes the prior wording ("memory and CPU explode" for
all three) that contradicted line 41's correct statement that
bare observables are "safe anywhere".
Adversarial pass: Explore subagent. Flagged 1 valid item —
original rewrite conflated observable-in-computed with
subscription-leak, contradicting line 41's safety claim.
Resolved by distinguishing the two cases in the Gotcha body.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 41 minutes and 52 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (28)
📝 WalkthroughWalkthroughSimplifies documentation across the tko.io project by consolidating multi-section metadata blocks in verified-behaviors files into compact single-line format, updating docs verification procedures in AGENTS.md with clearer instructions pointing to a detailed process guide, refining guidance on reactive primitive instantiation within computeds, and updating the generation script to produce the new condensed format. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
tko.io/public/agents/verified-behaviors/binding-template.md (1)
7-7: Consider adding automated validation of referenced paths in verified-behaviors docs.All paths in this file are currently valid, but automated checks would prevent stale references in future regenerated files across
tko.io/public/agents/verified-behaviors/.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tko.io/public/agents/verified-behaviors/binding-template.md` at line 7, Add an automated CI validation that parses each markdown in the verified-behaviors docs and verifies that every referenced path (e.g., `packages/binding.template/spec` and `packages/binding.template/verified-behaviors.json`) actually exists; implement this as a small script (e.g., validateVerifiedBehaviorsPaths.js with exported function verifyPathsInVerifiedBehaviors) that scans tko.io/public/agents/verified-behaviors/*.md for backtick-quoted paths, checks filesystem existence, returns non-zero on any missing path, and wire it into CI (e.g., a new npm script "check:verified-behaviors" called from the pipeline) so future regenerated files fail CI if they contain stale references.tko.io/scripts/generate-verified-behaviors.mjs (1)
159-172: Drop the now-unusedwhenToReadfield.With the "When to Read This" section removed from
renderPackage,whenToReadis no longer read anywhere. Small dead-code cleanup worth doing while you're here.♻️ Proposed diff
const pkg = { packageDir, slug: slugFromPackageDir(packageDir), title, description: description || `Verified behaviors for ${title}.`, indexDescription: description || `Verified behaviors for ${title}.`, - whenToRead: curated?.whenToRead ?? '', behaviors: curated?.behaviors ?? [],Based on learnings: "When touching a file, fix small nearby issues if low-risk and in-scope: … dead code, unused imports, stale comments".
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tko.io/scripts/generate-verified-behaviors.mjs` around lines 159 - 172, The pkg object in generate-verified-behaviors.mjs currently includes a now-unused property whenToRead (set from curated?.whenToRead) which is dead code after renderPackage stopped using it; remove the whenToRead line from the pkg literal (and any related curated?.whenToRead references) so pkg no longer contains that field and ensure no other code in this module relies on pkg.whenToRead (grep for renderPackage, slugFromPackageDir, curated, and pkg to confirm).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@tko.io/public/agents/verified-behaviors/binding-template.md`:
- Line 7: Add an automated CI validation that parses each markdown in the
verified-behaviors docs and verifies that every referenced path (e.g.,
`packages/binding.template/spec` and
`packages/binding.template/verified-behaviors.json`) actually exists; implement
this as a small script (e.g., validateVerifiedBehaviorsPaths.js with exported
function verifyPathsInVerifiedBehaviors) that scans
tko.io/public/agents/verified-behaviors/*.md for backtick-quoted paths, checks
filesystem existence, returns non-zero on any missing path, and wire it into CI
(e.g., a new npm script "check:verified-behaviors" called from the pipeline) so
future regenerated files fail CI if they contain stale references.
In `@tko.io/scripts/generate-verified-behaviors.mjs`:
- Around line 159-172: The pkg object in generate-verified-behaviors.mjs
currently includes a now-unused property whenToRead (set from
curated?.whenToRead) which is dead code after renderPackage stopped using it;
remove the whenToRead line from the pkg literal (and any related
curated?.whenToRead references) so pkg no longer contains that field and ensure
no other code in this module relies on pkg.whenToRead (grep for renderPackage,
slugFromPackageDir, curated, and pkg to confirm).
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f4306a03-5072-4cef-a052-3d9e438bc9d4
📒 Files selected for processing (30)
AGENTS.mdtko.io/public/agents/guide.mdtko.io/public/agents/process.mdtko.io/public/agents/verified-behaviors/bind.mdtko.io/public/agents/verified-behaviors/binding-component.mdtko.io/public/agents/verified-behaviors/binding-core.mdtko.io/public/agents/verified-behaviors/binding-foreach.mdtko.io/public/agents/verified-behaviors/binding-if.mdtko.io/public/agents/verified-behaviors/binding-template.mdtko.io/public/agents/verified-behaviors/builder.mdtko.io/public/agents/verified-behaviors/computed.mdtko.io/public/agents/verified-behaviors/filter-punches.mdtko.io/public/agents/verified-behaviors/index.mdtko.io/public/agents/verified-behaviors/lifecycle.mdtko.io/public/agents/verified-behaviors/observable.mdtko.io/public/agents/verified-behaviors/provider-attr.mdtko.io/public/agents/verified-behaviors/provider-bindingstring.mdtko.io/public/agents/verified-behaviors/provider-component.mdtko.io/public/agents/verified-behaviors/provider-databind.mdtko.io/public/agents/verified-behaviors/provider-multi.mdtko.io/public/agents/verified-behaviors/provider-mustache.mdtko.io/public/agents/verified-behaviors/provider-native.mdtko.io/public/agents/verified-behaviors/provider-virtual.mdtko.io/public/agents/verified-behaviors/provider.mdtko.io/public/agents/verified-behaviors/utils-component.mdtko.io/public/agents/verified-behaviors/utils-functionrewrite.mdtko.io/public/agents/verified-behaviors/utils-jsx.mdtko.io/public/agents/verified-behaviors/utils-parser.mdtko.io/public/agents/verified-behaviors/utils.mdtko.io/scripts/generate-verified-behaviors.mjs
Contributor
There was a problem hiding this comment.
Pull request overview
Reduces token footprint of TKO’s agent-facing documentation by trimming boilerplate from generated verified-behaviors markdown, and refactoring docs verification guidance to be more link-driven and less verbose.
Changes:
- Simplified
verified-behaviors/*.mdgeneration output (shorter preamble/status/next-step text) and removed unused generator helpers. - Moved detailed docs verification steps from
AGENTS.mdintotko.io/public/agents/process.mdand linked to it fromAGENTS.md. - Updated
guide.md“Gotchas” guidance to more precisely distinguish observable allocation waste vs computed/subscription leak behavior.
Reviewed changes
Copilot reviewed 30 out of 30 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tko.io/scripts/generate-verified-behaviors.mjs | Trims generated markdown boilerplate and simplifies index/package rendering. |
| tko.io/public/agents/process.md | Adds “Docs verification” section and guidance about generated verified-behaviors docs. |
| AGENTS.md | Replaces detailed docs verification steps with a short summary + link to process.md. |
| tko.io/public/agents/guide.md | Refines “Gotchas” language about reactive primitives inside computed evaluators. |
| tko.io/public/agents/verified-behaviors/index.md | Regenerated index with shorter preamble and streamlined list formatting. |
| tko.io/public/agents/verified-behaviors/bind.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/binding-component.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/binding-core.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/binding-foreach.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/binding-if.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/binding-template.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/builder.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/computed.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/filter-punches.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/lifecycle.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/observable.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider-attr.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider-bindingstring.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider-component.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider-databind.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider-multi.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider-mustache.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider-native.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/provider-virtual.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/utils.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/utils-component.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/utils-functionrewrite.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/utils-jsx.md | Regenerated with compact notice/status formatting. |
| tko.io/public/agents/verified-behaviors/utils-parser.md | Regenerated with compact notice/status formatting. |
Comment on lines
+83
to
+84
| Also — `tko.io/public/agents/verified-behaviors/*.md` are regenerated from `packages/*/verified-behaviors.json` on every `prebuild` / `predev` / CI build. Edit the JSON source, never the generated markdown. Hand edits are wiped on the next build. | ||
|
|
There was a problem hiding this comment.
This note about tko.io/public/agents/verified-behaviors/*.md being regenerated is duplicated earlier in this same document (the existing note near the top already covers the same point). Duplicating the rule risks the two copies drifting; consider removing this copy and referring readers to the earlier section instead (or consolidate into one canonical paragraph).
Suggested change
| Also — `tko.io/public/agents/verified-behaviors/*.md` are regenerated from `packages/*/verified-behaviors.json` on every `prebuild` / `predev` / CI build. Edit the JSON source, never the generated markdown. Hand edits are wiped on the next build. |
|
|
||
| - **Async computeds are dangerous.** Dependency tracking runs synchronously — it records which observables are read during the evaluator, then stops. An `async` evaluator returns a Promise at the first `await`, so any observable reads after that are outside the tracking window and never registered as dependencies. The computed cannot know when the async function finishes (halting problem). If you must use async computeds, read all observable dependencies *before* the first `await`. | ||
| - **Don't create computeds/subscriptions inside computeds.** A computed re-evaluates every time a dependency changes. If the evaluator creates a new `computed()` or `subscribe()` each run, those pile up and never get disposed — memory and CPU explode. Create subscriptions once outside, or dispose the previous one before creating a new one. | ||
| - **Never create reactive primitives inside a computed's evaluator.** Each re-evaluation allocates a new instance — for `ko.computed()` and `.subscribe()` the old instance stays alive with its subscriptions, so memory and CPU grow unbounded; for `ko.observable()` / `ko.observableArray()` the allocation itself is the only leak (no subscriptions to drag along), but it is still waste. Create reactive primitives once outside the computed, or inside a `LifeCycle`-enabled constructor. See "Observables vs computed dependency management" above for the full discussion. |
There was a problem hiding this comment.
This updated gotcha now distinguishes ko.observable() allocations from the subscription leaks caused by ko.computed()/.subscribe(), but the referenced section above (“Observables vs computed dependency management”) still states that creating ko.observable() inside a computed evaluator makes “memory and CPU grow unbounded”. To avoid contradictory guidance in the same doc (especially since this line points readers to that section), align the wording in one place or the other so both explain the same distinction.
Suggested change
| - **Never create reactive primitives inside a computed's evaluator.** Each re-evaluation allocates a new instance — for `ko.computed()` and `.subscribe()` the old instance stays alive with its subscriptions, so memory and CPU grow unbounded; for `ko.observable()` / `ko.observableArray()` the allocation itself is the only leak (no subscriptions to drag along), but it is still waste. Create reactive primitives once outside the computed, or inside a `LifeCycle`-enabled constructor. See "Observables vs computed dependency management" above for the full discussion. | |
| - **Never create reactive primitives inside a computed's evaluator.** Each re-evaluation allocates a new instance — for `ko.computed()` and `.subscribe()` the old instance stays alive with its subscriptions, so memory and CPU grow unbounded; for `ko.observable()` / `ko.observableArray()` the repeated allocation itself is the waste (they do not retain old subscriptions the same way), but it is still a leak of unnecessary reactive state. Create reactive primitives once outside the computed, or inside a `LifeCycle`-enabled constructor. |
The inline `status: ... · specs: ... · curated: ...` line in every
`verified-behaviors/*.md` gave agents nothing to act on:
- `status: curated` was redundant with the presence of a
`## Behaviors` section (and for the other status values the
file body already said so explicitly).
- `specs: <dir>` was the directory root of per-behavior spec
citations that already appear below — strictly less
information than `Specs: packages/xxx/spec/foo.ts` on each
bullet.
- Only `curated: <path>` carried value, as the
source-of-truth pointer for agents editing the doc.
Replaced the whole line with a single trailing italic footer:
_Curated source: `packages/<pkg>/verified-behaviors.json`_
Prose now sits at the top of the file, metadata at the tail.
Per-behavior spec citations untouched.
Byte total across the 26 verified-behaviors files:
~35,922 → ~34,673 (~3.5% further cut on top of the ~18% from
the previous commit; ~22% total vs main).
Adversarial pass: Explore subagent. Result: clean. No tooling
or CI consumes `status:` in those files; fallback to
`expectedCuratedRelativePath` covers the no-curated-yet case
without misleading (footer names the eventual target path,
not implying existence; preceding instruction makes that
clear).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two valid findings from Copilot's review of this PR: 1. **process.md dup** (Copilot @ line 84). The verified-behaviors-is-regenerated note was added at the tail of the new "## Docs verification" section, but the same rule already lives near the top of the document under "Never ship docs that reference things that don't exist on the target branch" (lines 29–32). Two copies risked drift. Collapsed to a single back-reference from the Docs- verification section pointing at the canonical paragraph. 2. **guide.md contradiction** (Copilot @ line 287). Line 41 in the Observables subsection still said "memory and CPU grow unbounded" for all three primitive types (observable, computed, subscribe) created inside a computed's evaluator — which contradicted both the earlier guide-level statement that bare observables are "safe anywhere" (line 38) and the nuanced Gotcha added in the previous commit. Aligned line 41 to the same distinction: `computed()` + `.subscribe()` leak instance + live subscriptions (memory + CPU); `ko.observable()` / `ko.observableArray()` allocation alone is the waste (no subscription tail to drag), still avoid, but not the same failure mode. Adversarial pass: Copilot (external reviewer on PR #349). Flagged 2, both valid, both addressed here. Spot-verified that the process.md back-reference target section exists and carries the canonical regeneration note. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
brianmhunt
pushed a commit
that referenced
this pull request
Apr 21, 2026
testing.md + process.md instructed agents to query the
playground DOM by `#id` (e.g. `#preview`, `#console-messages`,
`#esbuild-status`, `#compile-time`, `#error-bar`). None of
those IDs exist. The playground uses `data-role` attribute
selectors throughout (`tko.io/src/playground/shell.ts`):
- `[data-role="preview"]` — iframe (line 54)
- `[data-role="console-messages"]` — console output container (line 61)
- `[data-role="status"]` — generic status element
shows "esbuild ready" label
(shell.ts:67 + runner-iife.ts:64)
- `[data-role="compile-time"]` — compile elapsed (line 68)
- `[data-role="error-bar"]` — hidden until a build error
(line 55)
Replaced every `#foo` playground reference in both files with
the correct attribute selector. The `#esbuild-status` →
`[data-role="status"]` mapping is worth calling out
specifically: the element is generic (handles loading → ready
→ error states), not esbuild-specific; the doc notes that the
label text becomes "esbuild ready" so an agent grepping the
snapshot still has the right string to look for.
Not a regression — these selector bugs pre-date this branch.
Found while reviewing testing.md for correctness after the
earlier preamble-strip pass; AGENTS.md had already migrated
its playwright flow to process.md in PR #349, so the fix had
a single home (no stale copy left behind).
Adversarial pass: Explore subagent cross-referenced every
selector against `tko.io/src/playground/shell.ts` +
`runner-iife.ts`. Result: clean, all five mappings match
actual DOM.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three independent token-reduction edits to TKO's agent-facing doc surface. Each commit is adversarial-reviewed with the audit line at the end of its commit message.
1. Generator preamble strip (
tko.io/scripts/generate-verified-behaviors.mjs+ 26 regen'd files)Dropped templated boilerplate from every `verified-behaviors/*.md` file: the per-file `## When to Read This` heading + derived sentence, the `## Status` bullet block (collapsed to a single `status: ... · specs: ... · curated: ...` line), the two-line generated notice (now one line), and the index preamble. Dead helpers `statusSummary` + `lowerFirst` removed.
Result: ~44KB → ~36KB across the 26 files (~18% cut). Every agent that loads the verified-behaviors pack pays less on session start.
2. `AGENTS.md` Docs Verification → link to `process.md`
The 7-line headless-playwright flow rarely applies to typical docs edits; when it does, agents follow a link. AGENTS.md now one-paragraph: names the minimum (`bun run build`, Open-in-Playground verification) and links to the full flow in `process.md`. Full flow now lives under a new `## Docs verification` section in `tko.io/public/agents/process.md`. Also added to process.md: a note that verified-behaviors/*.md are regen'd from JSON on every build — saves a future agent from hand-editing generated files.
Net AGENTS.md delta vs main: −6 lines. process.md delta vs main: +13 lines (loaded only when link is followed).
3. `guide.md` Gotcha dedupe + accuracy fix
The Gotchas bullet for "don't create reactive primitives inside a computed's evaluator" was a weaker form of the rule already present at line 41 and in llms.txt — covered only `computed()` and `subscribe()`. Upgraded to match the strong version (adds `observable()`). Honest about the distinction: `computed()` + `subscribe()` leak subscriptions on every re-run (memory + CPU); `observable()` only wastes the allocation. This removes the prior hyperbole ("memory and CPU explode" for all three) which contradicted line 41's correct statement that bare observables are "safe anywhere".
Verification
Out of scope
A separate question under discussion: whether to restructure `llms.txt` into a pure link-index in the bun.sh/llms.txt style (no inline primer content). Deferring to a follow-up — current `llms.txt` standalone-primer value is non-trivial and the migration needs its own design round.
🤖 Generated with Claude Code
Summary by CodeRabbit