agent traversal

traverse the corpus by ownership, not keyword accumulation: machine index -> raw .md document of the nearest governing rule -> its direct related links only when a boundary crosses domains.

• rendered Fumadocs URL: reading and browsing
• matching .md URL: stable direct-retrieval representation
• both identify the same canonical document and path

keyword navigation reads unrelated examples alongside governing rules. a domain rule (database pagination) shares keywords with a stack page (TanStack Query optimization) but governs different concerns. the agent conflates implementation mechanisms with core reasoning, copies a library-specific pattern into domain decisions, and breaks the corpus's portable/technology-specific boundary. the codebase then says "we use TanStack because the gurus say so" instead of "we cache because cost matters, and we use TanStack to implement it here" — decisions stay tethered to a stale implementation across boundary changes.

ownership-first retrieval keeps the reason separate from the mechanism, so a future engineer can substitute a new technology confidently.

1. fetch /guru/llms.txt for the compact raw-document catalog, or /guru/agent-index.json when title, kind, canonical URL, and raw URL are needed as structured data.
2. start with core when choosing an optimization principle: readability, maintenance surface, bounded units, or compounding work.
3. select the owning domain for the decision boundary.
4. read a stack page only when the rule depends on a named library or platform.
5. use a case study to inspect a full proven flow, not as a competing owner.
6. retrieve direct related links only when they name a needed dependency, authority, or verification path.

bad

Agent searches "cache" in corpus -> reads TanStack Query stack page + performance
domain page in random order -> adopts TanStack's identity-key pattern for a
D1 query cache that has no browser client -> 6 months later, caching rules
change, only TanStack page is updated, D1 pattern is orphaned and no longer
verified

keyword-only retrieval treats library patterns as owning facts instead of implementation choices bounded to that library. when the core principle (e.g., cache invalidation) changes, orphaned copies in other domains are silent and untraced: duplicated rules drift independently, none can be found from the owner, and the corpus contradicts itself while every reader assumes the page they found is the law.

good

Agent consults agent-index.json for "cache" -> selects core principle for
performance/cache-identity -> reads that rule's verification checklist ->
navigates to performance domain for ownership rules -> reads stack page only
to implement the chosen rule in TanStack Query (or D1) -> documents the
verification in the domain owner, not the stack page

each read narrows the decision while preserving the owner that can explain and verify it. when a core principle changes, one place is authoritative and stack-specific copies can be checked against it. the reason stays separable from the mechanism, so replacing a library means re-implementing one stack page against an unchanged governing rule, not re-deriving the decision.

for any corpus page, confirm its raw_url returns the authored MDX and its canonical_url renders the same title through Fumadocs. verify one traversal starts at the appropriate core or domain owner before reaching a stack-specific practice.

core engineering mindset · reader-first business code · agentic compounding · regex-friendly codebase · mdx as interface