Docs Search

Docs Search — Navigation Methodology for Official Library Documentation

Methodology distillation of the generic moves an agent makes when reaching for a library's official documentation. Not a per-library skill — one skill plus a thin per-library record in the shared knowledge graph (`/knowledge/libraries/`), because 90% of the work is the same regardless of which library you're searching.

This is the navigation layer that sits next to `library-reference-distillation`. That skill is for authoring a full library-ref rule pack when you have time to extract idioms. This skill is for just looking something up when you don't — a lighter-weight, faster-to-author alternative whose unit of growth is a ~30-line topography record, not a full rule pack.

When to Apply

Use this skill when:

• An agent needs a specific answer from a library's official documentation and "search the docs" is the next move
• The user asks "where do I find X in <library> docs?" or "did <library> change Y recently?"
• The documentation appears to match the situation but production behavior diverges
• The agent is about to Google a library question and would benefit from going to the library's own site search, llms.txt, or changelog first
• A library has been used before and a topography record exists in registry/ — read it before navigating
• A library has been used and no record exists yet — apply the methodology, then capture findings in registry/<library>.md so the next lookup is faster

This skill is not for:

• Authoring a library-reference rule pack — when you want to extract idioms and failure-gap rules into a distilled skill, use `library-reference-distillation` instead. Once a full library-ref skill exists for library X, the registry entry for X becomes redundant and should be cut.
• General web search — if the question is not about a specific library's official docs (e.g., "what's the best practice for X across the ecosystem"), this is the wrong tool.
• Reading internal/proprietary docs — no llms.txt, no public changelog, no public issues. The methodology assumes public, versioned, OSS-style documentation.

How to Use

The four categories are orthogonal moves. Match the symptom to the move:

For category overviews and ordering rationale, see `references/_sections.md`.

Rule Categories

Quick Reference

1. Choose Source

• `src-decision-tree` — Classify the question (API behavior / changelog / idiom / known-bug / migration) before picking a section; "search the docs" is not a plan
• `src-llms-txt-first` — Probe <docs-root>/llms.txt or /llms-full.txt before scraping HTML; AI-canonical format if it exists
• `src-bounded-knowledge-read` — Filename is the index: read only knowledge/libraries/<slug>.md, never scan the dir; bounds per-invocation token cost regardless of knowledge-store size

2. Match Version

• `ver-find-selector` — Find the version selector before reading any reference page; ask the user or read package.json to pin
• `ver-changelog-first` — When the question contains "since I upgraded" or "did X change", read the changelog before the reference

3. Fall Back

• `fall-known-issues` — When docs match the user's code but reality doesn't, check GitHub issues, status page, and Discord/forum for known bugs before re-reading docs
• `fall-samples-over-prose` — For "how should I structure this?" go to the examples/ dir or samples repo first; idiomatic structure lives in code, not prose

4. Capture for Reuse

• `capture-registry-record` — After a successful lookup against a new library, write the docs: section of knowledge/libraries/<library>.md so future lookups skip the discovery phase

Knowledge Store

Per-library topography records live in the repo-root shared knowledge graph at `/knowledge/libraries/`. The same files are written by `code-distill` — each skill owns one section (docs: for this skill, code: for code-distill) and never overwrites the other. See `knowledge/README.md` for the merged schema, wiki-link conventions, and the merge discipline.

The knowledge store is intentionally empty at v0.1.0. First entries are added when a real lookup demands one, not pre-emptively. If you find yourself adding a record for a library you have not actually queried, stop — wait for the real need.

Read discipline: when the user names a library, do exactly read knowledge/libraries/<slug>.md. Never scan knowledge/libraries/ to "see what's available" — the filename is the index, and lazy access is what keeps per-invocation token cost bounded regardless of knowledge-store size.

Related Skills

• `library-reference-distillation` — Authoring playbook for full library-ref rule packs (the heavier sibling); when a full library-ref skill ships for library X, retire the registry entry for X
• `radical-simplification` — The thinking layer above this skill; this skill itself is an instance of the "constrain → name the invariant" move applied to the question "how do I look this up?"
• `init` (and similar) — When the lookup is about your own codebase, that's a different problem; this skill is for external library docs

Authoring Note

These rules are load-bearing, not decorative. Each names a wrong default an agent has when reaching for documentation: treating all questions as "search docs," ignoring llms.txt, reading the latest reference page while the user is on an older version, re-reading docs when reality contradicts them, preferring narrative over code, and redoing lookup work next time. If a rule restates something a capable model already does correctly when prompted, cut it. Coverage is proven by /dev-skill:eval on real doc-lookup prompts, not by rule count. The registry grows organically as real lookups demand entries.

Documentation Navigation Methodology

Version 0.2.0 dot-skills May 2026

---

Abstract

Methodology distillation of the generic moves that turn 'I need to look this up' into a fast, version-correct answer from a library's official documentation — independent of which library. 8 rules across 4 orthogonal categories — Choose Source, Match Version, Fall Back, Capture for Reuse — each naming a wrong default an agent makes when reaching for docs (treating all questions as 'search docs', ignoring llms.txt, reading latest docs while user is on an older version, re-reading docs when reality contradicts them, preferring prose over examples, redoing lookup work next time). Per-library facts live in a topography registry (registry/<lib>.md) so the methodology is shared once and per-library overlay is thin reference data — collapses the 'one skill per library' trap. Registry is intentionally empty at v0.1.0; first entry should be grounded in a real lookup, not pre-empted.

---

Table of Contents

1. Choose Source

• 1.1 Classify the question before searching — changelog, reference, idiom, or known-bug
• 1.2 Probe llms.txt before scraping HTML — AI-canonical format takes priority
• 1.3 Read only the named knowledge entry; never scan knowledge/libraries/

2. Match Version

• 2.1 Find the version selector before reading any reference page
• 2.2 Read the changelog before the reference for "did X change" questions

3. Fall Back

• 3.1 For idiom questions, read examples and samples before prose docs
• 3.2 When docs match the code but reality doesn't, check GitHub issues, status, and forum

4. Capture for Reuse

• 4.1 Write the docs section of knowledge/libraries/<library>.md after a successful lookup

---

References

1. https://diataxis.fr/ 2. https://llmstxt.org/ 3. https://stripe.com/docs/upgrades 4. https://keepachangelog.com/

---

Source Files

This document was compiled from individual reference files. For detailed editing or extension:

Sections

This file defines the four orthogonal categories of moves an agent makes when reaching for a library's official documentation. The prefix in parentheses is the filename prefix that groups rules. Categories are ordered by the sequence they fire when handling a real lookup: choose where to read → match the right version → fall back when official sources fail → capture findings so the next lookup is cheaper.

The four categories are orthogonal — applying one does not satisfy the others. Match the symptom in front of you:

• "I'm about to search the docs" → src (which source for which question?)
• "I'm about to read a reference page" → ver (which version am I reading?)
• "Docs match the user's code but reality doesn't" → fall (issues, samples)
• "I just found the canonical entry points" → capture (write to registry/)

This skill is the methodology layer. Per-library facts (Stripe's dated API model, Tailwind's v3/v4 split, Anthropic's llms.txt presence) are not rules — they are reference data living in registry/, intentionally empty at v0.1.0 and growing only when real lookups demand new entries.

---

1. Choose Source (src)

Description: Where to read, given what the user is actually asking. The default failure mode is treating every lookup as "search the docs" — which produces a Google-style scan that misses changelog-only answers, ignores AI- canonical formats like llms.txt, and lands on the reference page even when the answer is in a guide or a known-issues thread. Covers question classification (changelog vs reference vs idiom vs known-bug) and the llms.txt probe that should precede any HTML scraping.

2. Match Version (ver)

Description: Reading the right version of the reference. The default failure mode is reading latest docs while the user is on an older release — producing technically-correct-but-actually-wrong answers. Covers finding the version selector before reading any reference page, and consulting the changelog before the reference when the question is "did X change since I upgraded?"

3. Fall Back (fall)

Description: What to do when the canonical source fails — either docs match the user's code but reality contradicts them, or the question is about idioms that the prose docs don't capture. The default failure mode is re-reading the same doc page after each failed attempt. Covers known-issues fallback (GitHub issues, status page, Discord) and the examples-over-prose move for idiom questions.

4. Capture for Reuse (capture)

Description: Recording what you discovered about a library's docs topography so the next agent doesn't redo the discovery work. The default failure mode is treating each lookup as one-shot, then re-discovering the same root URL, changelog path, and samples repo next time. Covers writing the docs: section of knowledge/libraries/<library>.md (the repo-root shared knowledge graph) once you've found the canonical entry points. The file is shared with code-distill, which writes the code: section — each skill owns one section and never overwrites the other.

Write the docs section of knowledge/libraries/<library>.md after a successful lookup

By default each doc lookup is one-shot — the agent discovers the docs root, the changelog URL, the samples repo, and whether llms.txt exists, then loses all of that when the session ends. The next agent re-discovers the same facts. The move is to capture topography findings in the shared knowledge graph at `knowledge/libraries/<library>.md` (docs: section only) immediately after a successful lookup. The same file is shared with code-distill — it owns the code: section, this skill owns the docs: section, neither overwrites the other.

When to write (apply at end of a real successful lookup):

  - You searched a library's docs and got the right answer → write
  - You probed for llms.txt (found or not) → record the result
  - You found the canonical changelog / samples / upgrades URLs → record

DO NOT write from training-data knowledge alone. Entries are grounded
observations from real WebFetches, not recall.

The docs section of the knowledge record:

---
library: stripe                       # filename stem, kebab-case
last-verified-date: YYYY-MM-DD        # update on every write

# Shared metadata (any writer may merge into these lists)
uses: []                              # libraries this library depends on
implements: []                        # patterns it implements ([[wiki-links]])
notable-landmarks:
  - /docs/error-codes (canonical error reference)
  - stripe-mock (local test server)

# This skill owns the docs: section
docs:
  root: https://stripe.com/docs
  llms-txt: null                      # probed YYYY-MM-DD, none yet
  api-reference: /docs/api
  changelog: https://stripe.com/changelog
  version-model: dated                # semver | dated | unversioned
  version-selector: api-version URL param
  upgrades: https://stripe.com/docs/upgrades
  samples-repo: https://github.com/stripe-samples
  status-page: https://status.stripe.com
  discord-or-forum: null
  lookup-count: 1                     # incremented every successful session

# code-distill writes the code: section; do not touch it from here
---

The merge discipline (CRITICAL):

• If the file does not exist → create it with library:, shared metadata, and docs: only
• If the file exists with no docs: section → add docs: only; do not modify code: or other sections
• If the file exists with docs: already → update fields under docs:, increment `docs.lookup-count`, refresh last-verified-date; never overwrite the whole file blindly
• For shared list fields (uses, implements, notable-landmarks): merge by union; do not replace

When to refresh:

• On every lookup for this library: re-check changelog URL still resolves; re-probe llms.txt if previously null and ≥ 90 days have passed; bump last-verified-date
• On major library version bump: full re-verification of all URLs (docs sites get reorganized)
• When a lookup fails because a recorded URL 404s: update in the same session that hit the failure

The graduation rule. When docs.lookup-count >= 3 on a single library, the library has earned a full library-reference distillation rule pack (sibling of nuqs, zod, react-hook-form, effect-ts, emilkowal-animations). Author it using the `library-reference-distillation` playbook. Once shipped:

1. Delete the `docs:` section of knowledge/libraries/<library>.md (or delete the whole file if code: is also absent or already graduated) 2. Add the library to this skill's "When NOT to Apply" with a pointer to the new static skill 3. The library moves out of this light layer into the heavy layer (full library-reference distillation output)

What NOT to write here:

• Idiomatic rules (those go in a full library-reference distillation skill — see `library-reference-distillation`)
• API method documentation (the library's docs are the source)
• Opinions or recommendations about the library
• The code: section — that is owned by `code-distill`

The mechanical trigger: at the end of any successful doc-search session for a library whose docs: section is missing from knowledge/libraries/, write it before closing out. If the section exists, increment docs.lookup-count and refresh last-verified-date. Discovery was already done during the lookup; capturing costs seconds.

Reference: knowledge/README.md — full schema and merge discipline

When docs match the code but reality doesn't, check GitHub issues, status, and forum

By default when behavior contradicts the documentation, the agent re-reads the documentation. This is the docs-loop trap: the agent assumes the docs are right and the user is wrong, so re-reading "more carefully" must reveal the missed detail. Most of the time, the documentation is right in principle but the implementation has a known bug — and the canonical record of that lives in GitHub issues, the status page, or the project's Discord, not in the docs.

The fallback ladder (apply in order when docs match but reality doesn't):

  Tier 1 — Status page (rules out a current incident)
     <library>.statuspage.io, status.<library>.com
     "Is the service degraded RIGHT NOW?"

  Tier 2 — GitHub issues, open + closed
     github.com/<owner>/<library>/issues?q=<error-message>
     Search the EXACT error message in quotes first; then keywords
     Check both open AND closed (a "fixed" issue often documents
     workarounds for older versions)

  Tier 3 — Recent releases (last 3 minor versions)
     A regression in a recent release may be live; the bug fix
     may be in the NEXT release, not the current one

  Tier 4 — Discord / community forum / Stack Overflow
     Some libraries triage in Discord first, issues second
     (Tailwind, Effect, shadcn). For these, Discord is canonical.

  Tier 5 — Twitter/X from the author's account
     For very recent libraries, authors sometimes announce
     "known issue, working on it" before filing an issue

The discriminator:
  - Found the exact symptom in an open issue → likely a known bug
  - Found it in a closed issue → check the resolution; may need
    to upgrade past the user's version or apply a workaround
  - Found a recent commit reverting a feature → the user's
    version may have the broken code; advise upgrade or downgrade
  - Nothing matches → escalate to "this is a new bug" path
    (file an issue, prepare a minimal repro)

When NOT to apply:
  - User's code obviously doesn't match the docs (typo, wrong
    function name) → fix the code, do not fall back
  - The question is "how do I do X?" not "X isn't working" →
    wrong category; this rule is for divergence, not discovery

The mechanical trigger: when re-reading docs would be the next action and the user already showed correct-looking code, switch to the issue tracker first. The docs are not the source of truth when the behavior is buggy — only when the contract is documented.

Reference: The react-hook-form skill's `formstate-async-submit-lifecycle` rule citing GH discussion #10103 — exactly this pattern

For idiom questions, read examples and samples before prose docs

By default for "how should I structure this?" the agent reads the prose guides and assembles an answer from English sentences. This produces structurally plausible answers that don't match how the library is actually used. Idioms are encoded in code, not prose — the authors' own examples and samples are the highest-fidelity source for "what does idiomatic usage look like." Read the code first; use prose only for context.

The idiom-source ladder (for "how should I do X?" questions):

  Tier 1 — Examples dir inside the main repo
    github.com/<owner>/<library>/tree/main/examples/
    github.com/<owner>/<library>/tree/main/e2e/
    These are the maintainers' own canonical usage. They were
    written to validate the API and exhibit how the author
    actually intends the library to be used.

  Tier 2 — Dedicated samples / templates repo
    github.com/<owner>/<library>-samples
    github.com/<owner>/<library>-examples
    Often per-framework or per-use-case. Useful when the main
    repo doesn't include examples, or includes only minimal ones.

  Tier 3 — Playground / sandbox the library publishes
    e.g. tailwindplay.com, codesandbox templates linked from docs,
    stackblitz starters
    Reveals interactive idioms that a static repo doesn't.

  Tier 4 — Test files in the main repo
    github.com/<owner>/<library>/tree/main/test
    Tests are the "what the library guarantees" surface — they
    exhibit edge-case idioms (error handling, concurrent use,
    initialization order) that the examples don't bother with.

  Tier 5 — Real OSS projects that use the library
    GitHub code search for `<distinctive-import>` filtered to
    repos with >100 stars. Shows how *consumers* use the library,
    which sometimes diverges from author intent.

  Tier 6 — Prose docs / cookbook
    Only NOW does the prose come in — and only for "why" context
    around the patterns you already saw in code.

The discriminator (per question):
  - Question contains "structure", "organize", "set up", "pattern"
    → idiom question → samples ladder
  - Question contains "what does X return", "what are X's params"
    → reference question → /docs/api page
  - Question contains "best practice" → samples + prose together
    (the prose tells you what the author thinks is best;
     the samples show what they actually do)

Anti-pattern:
  Citing a snippet from prose docs as "the idiomatic way" when
  the samples directory shows a different pattern. The samples
  are how the library is used; the prose is how it's marketed.

The mechanical trigger: when the question is about structure or pattern, the first WebFetch should be a samples URL, not a prose page. If the registry record for this library doesn't list a samples URL, find one and capture it before answering.

Reference: The library-reference-distillation skill's `source-priority-ladder` rule — same observation applied to skill authoring

Read only the named knowledge entry; never scan knowledge/libraries/

By default once the agent learns there is a knowledge graph under /knowledge/libraries/, it does ls knowledge/libraries/ to "see what's available" before reading the named entry — or reads several entries to "compare." Both burn tokens linearly in the size of the knowledge store. The move is to treat the filename as the index: when the user names library X, read exactly knowledge/libraries/<x-slug>.md and proceed. The filesystem is the hash table; lazy access is what keeps per-invocation token cost bounded regardless of how many entries accumulate over time.

The bounded-access discipline:

  When the user names library X:
    1. Compute the slug (kebab-case, matching the library's own name):
         "shadcn/ui"      → shadcn-ui
         "React Hook Form" → react-hook-form
         "Effect" or "Effect-ts" → effect-ts
    2. Try exactly: read knowledge/libraries/<slug>.md
    3a. File exists → proceed with that single entry
    3b. File does not exist → fall back to discovery (per the
        skill's methodology); capture findings at session end
        per capture-registry-record

  Never:
    - ls knowledge/libraries/ to "see what's available" before
      reading the named entry
    - read multiple entries to compare against each other
    - read knowledge/README.md on every invocation (only read
      it when WRITING a new entry, to confirm schema)
    - grep across knowledge/libraries/ for keywords (the filename
      is already the canonical key)

  The only legitimate multi-entry access:
    - Following a wiki-link from one entry: if libraries/shadcn-ui.md
      has uses: [[radix-ui]], you MAY follow to libraries/radix-ui.md
      — but only if the user's question actually requires the
      upstream dependency. Default: don't traverse, just answer
      from the named entry.

Token-cost guardrail:
  Per-invocation knowledge read cost = O(1) when disciplined.
  Per-invocation knowledge read cost = O(N) when undisciplined.
  With N → 100+ entries, the difference is measured in seconds
  and thousands of tokens per query.

The mechanical check: before any operation that touches more than ONE file under knowledge/, ask "is this strictly required for the named query?" If the answer is "I want to see what's there" or "it might be useful," the answer is no — bound the access to the named entry and trust the filename-as-index. If a needed entry doesn't exist, do discovery and capture — do not browse the registry first.

Reference: knowledge/README.md — Reading from knowledge section codifies the same discipline

Classify the question before searching — changelog, reference, idiom, or known-bug

By default the agent treats "I need to look this up" as "open the docs and search." This produces a Google-style scan that lands on the API reference even when the answer is in the changelog, a guide, or a GitHub issue. The move is to classify the question first — five categories, each pointing to a different doc section. The classification takes seconds and saves the wrong-page-read tax.

Question type            First place to look
─────────────────────────────────────────────────────────────────────
Reference                API reference page for the resource/hook/component
  "What does X return?"  e.g. /docs/api/<resource>, /docs/<hook-name>
  "What are X's params?"

Changelog                Changelog or release notes
  "Did X change?"        e.g. /changelog, /releases, github releases tab
  "Why broken since N→M?"

Idiom                    Examples dir / samples repo / cookbook
  "How should I do X?"   e.g. github.com/<author>/<lib>/tree/main/examples
  "What's the right way?"  e.g. <lib>-samples repo, /docs/recipes

Known-bug                GitHub issues, status page, Discord/forum
  "Docs say X but Y"     e.g. github.com/<author>/<lib>/issues
  "This isn't working"     status.<lib>.com, community.<lib>.com

Migration                Upgrade guide / breaking changes doc
  "Move from N to M"     e.g. /docs/upgrades, /docs/migrating-to-vN

If unclassifiable:        ASK THE USER what they actually want before
                          scanning the docs. The classification IS the spec.

Apply before opening any doc page: name the question type out loud (even silently), then open the matching section. If you find yourself on the reference page for a "did X change?" question, stop — you are reading the wrong section. The cheapest way to misuse documentation is to land on a page that could contain the answer but doesn't.

Reference: Diátaxis documentation framework — reference / how-to / explanation / tutorial as the canonical doc-section taxonomy

Probe llms.txt before scraping HTML — AI-canonical format takes priority

By default the agent goes straight to the human-facing HTML docs and either uses WebFetch on rich HTML pages or runs a site search. This wastes tokens on navigation chrome and produces noisy results. A growing number of libraries publish `llms.txt` (and sometimes llms-full.txt) — a flat, structured, AI-targeted index of the same content. Probe for it before any HTML scraping.

The probe (run once per library, then cache result in registry/):

  1. Try <docs-root>/llms.txt
     e.g. https://anthropic.com/llms.txt
          https://effect.website/llms.txt
          https://tailwindcss.com/llms.txt
     200 → use it; it lists section URLs in AI-friendly order

  2. Try <docs-root>/llms-full.txt
     Some libraries publish a "everything in one file" variant
     200 → use it for broad-scan questions; smaller for targeted ones

  3. Try <library-root>/llms.txt (some put it at the site root)

  4. Check the library's GitHub README for an llms.txt mention

  5. Only after 1–4 fail → fall back to HTML doc scraping

Why this matters:
  - llms.txt is the author's INTENT for how AI should consume the docs
  - It typically points to the canonical section URLs, skipping marketing
    pages, version-switcher chrome, and out-of-date duplicates
  - Token-cheaper: no JS, no CSS, no nav, no footer, no analytics scripts
  - When present, it is THE source of truth for navigation

When to revisit:
  - Library version bump → re-probe (llms.txt is a recent convention,
    libraries are still adding it)
  - Lookup feels unusually noisy → check whether llms.txt now exists

Anti-pattern:
  Caching "no llms.txt" in registry without an expiry. The set of
  libraries with llms.txt grows monthly — re-probe on each major
  version of the library or on registry refresh.

The mechanical trigger: before any WebFetch of a docs page, check the registry for llms.txt URL; if absent, probe before scraping. Once probed, record the result in registry/<library>.md so the next lookup skips this step.

Reference: llmstxt.org — the llms.txt convention proposal and registry of adopting sites

Read the changelog before the reference for "did X change" questions

By default when something was working and now isn't, the agent re-reads the reference page for the affected API. This misses the single most common cause: the API changed in a recent release. The reference page documents the current state — it cannot tell you whether the behavior the user is seeing matches the version they have. The move is to read the changelog before the reference whenever the question contains drift signal.

Triggers that demand changelog-first (do NOT skip):

  - "Used to work, now doesn't since I upgraded"
  - "After bumping <library> to <version>, X broke"
  - "Worked in dev but not in prod" (often = version skew)
  - "The docs say X but I'm getting Y"
  - "Was this API renamed/removed?"
  - "Why is my code emitting a deprecation warning?"

The changelog read sequence:

  1. Locate the changelog. Common spots:
     - <docs-root>/changelog
     - <library-repo>/CHANGELOG.md
     - <library-repo>/releases (GitHub releases tab)
     - <docs-root>/blog (some libraries publish breaking changes
        as blog posts; nuqs does this with nuqs-2.5)

  2. Read entries between the user's version and "latest" (or the
     version they were upgrading FROM and TO).

  3. Grep the changelog for the affected API name first; if it
     appears, you have the answer in 30 seconds. If it doesn't,
     scan for "breaking" or "BREAKING CHANGE" entries.

  4. ONLY THEN open the reference page — and read it in light of
     what the changelog said.

The cheap test:
  After reading the changelog, can you state "<thing> changed
  from X to Y in version Z, and the user is on version W"? If
  yes, the answer is reachable. If no, the changelog wasn't
  the source — escalate to known-issues (`fall-known-issues`).

Anti-pattern:
  Skipping the changelog because "I already know this library."
  Library knowledge from training data ages out fast — the
  changelog is the truth.

The mechanical trigger: any question with the words "since," "after upgrading," "used to work," "deprecated," or "removed" — open the changelog before the reference. If you skip this and answer from the current reference page, you will silently mislead.

Reference: Keep a Changelog — the canonical format for human- and AI-readable changelogs

Find the version selector before reading any reference page

By default the agent reads latest documentation and assumes the user is on the latest version of the library. This produces technically-correct-but-actually-wrong answers — references to APIs that don't exist yet in the user's version, examples using syntax from a future release, or deprecation warnings for code the user wrote against a stable older API. The move is to find the version selector before reading any reference page and pin the lookup to the user's actual version.

The version-pinning sequence (apply BEFORE reading any reference page):

  1. Determine the user's version. In priority order:
     a. Ask the user directly: "Which version of <library> are you on?"
     b. Read package.json / Cargo.toml / requirements.txt / go.mod
        in the project root
     c. Read the lockfile (package-lock.json, yarn.lock, etc.) for
        the actual resolved version
     d. Check imports for version-specific patterns (e.g. `from
        "openai/resources/beta"` signals a different version than
        `from "openai/resources/messages"`)

  2. Find the version selector on the docs site. Common patterns:
     - Dropdown in the top-right (React, Vue, Next.js)
     - Subdomain (v2.tailwindcss.com vs tailwindcss.com)
     - URL path (docs.python.org/3.11 vs /3.12)
     - Date in URL (Stripe: /docs/api?api-version=2023-10-16)

  3. Switch the docs to the user's version, THEN read.

  4. If no version selector exists, the library is either
     unversioned (read latest) or single-version (note in registry).

Cases that get this wrong by default:

  - Tailwind v4 vs v3 — utility behaviors differ; reading v4 docs
    when user is on v3 produces hallucinated utility classes
  - React 19 vs 18 — Server Components / use() / form actions
    don't exist before 19
  - Next.js 13 → 14 → 15 → 16 — App Router conventions change
  - Effect 3.x vs 4-beta — ServiceMap → Context.Service rename

The mechanical trigger: before WebFetching any reference page, state the version you are reading and the version the user is on. If they don't match, switch first. The two-minute cost of pinning saves the half-hour cost of debugging an answer that doesn't apply.

Reference: Stripe's dated API versioning model — exemplary case where ignoring version selector silently produces wrong behavior