Docs Guide

docs-guide for Codex

Read these first:

• references/llms-txt-sites.md
• references/fallback-strategies.md

Load on demand (spec-level or fetch-prompt workflow questions):

• references/webfetch-prompts.md
• references/regression-cases.md

Scope

Any library, framework, API, or service with official documentation — including LLM provider APIs (OpenAI, Anthropic, Google Gemini, etc.) via their llms.txt indexes listed in references/llms-txt-sites.md.

Trigger on:

• "How do I…", "What is…", "How does X work", "Best practice for…" about any library or framework
• Explicit doc requests — "공식문서", "official docs", "문서 기반으로", "docs에서 확인해줘"
• Version-sensitive or spec-level questions about external libraries
• Questions about the llms.txt standard itself (what it is, which sites have it, llms.txt vs llms-full.txt)

When a question spans several tools or skills (e.g., "How to use Stripe inside my agent runtime"), this skill owns the external-documentation part only.

Arguments

When invoked as docs-guide [library] [question], parse the leading token(s) as the library and the rest as the topic:

• docs-guide react useEffect → Library: React, Question: useEffect
• docs-guide next.js app router caching → Library: Next.js, Question: app router caching
• docs-guide fastapi dependency injection → Library: FastAPI, Question: dependency injection
• docs-guide (no args) → ask which library/framework and which topic (one §A question covering both), unless Step 0 project context makes the library obvious

Clarification — docs-guide is minimal-interview

This plugin mostly needs just two facts: library and topic.

Per shared/questioning-policy.md §2c — if the user already named the library and topic, proceed immediately without asking anything.

If the library OR topic is genuinely ambiguous (e.g., "Router" with no project context), ask exactly ONE numbered-option question per §A below, then proceed.

§A — Numbered-option format (Codex CLI has no multiple-choice card UI)

Codex CLI has no card UI. When you must ask, output a chat block:

질문: <한 줄 질문>
1. <추천안> — 무엇인지, 왜 이걸 추천하는지
2. <대안> — 무엇인지, 트레이드오프
3. 직접 입력 (문장으로 말씀해 주세요)

• Recommended option always goes first (1번).
• Multi-pick → "여러 개면 1,3처럼 적어주세요."
• Never ask more than once; if still unclear, proceed with the most likely interpretation.

Step 0 — Project Context Detection

Before fetching, quickly scan local dependency files to detect library version:

package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle

Use this for:

• Version detection: "react": "^19.0.0" → fetch React 19 docs
• Disambiguation: project has both react-router-dom and express, user asks "Router" → resolve silently
• Skip unnecessary search: if the library is not installed in the project, say so briefly

Skip this step if the question already names a specific library and version.

Intent Classification (Smart Broad)

FETCH (external lookup needed)

• Library/framework APIs, configuration, features
• Setup/installation, migration guides, breaking changes
• API reference (endpoints, parameters, return types)
• Questions where wrong info causes bugs (auth, payments, DB queries)
• Explicit doc requests

SKIP (answer from knowledge)

• Basic language syntax (Python for loop, JS array methods)
• General CS concepts (REST, closures)
• Architecture discussions not tied to a specific library version

DISAMBIGUATE

• Generic term maps to multiple libraries ("Router", "ORM", "auth", "store")
• Check Step 0 first; if still ambiguous, ask one §A question

When unsure between FETCH and SKIP, answer from knowledge first, then offer: "공식 문서도 확인해볼까요?"

Version Awareness

1. Project context first — check Step 0
2. User mention — "React 19", "Django 5.0"
3. Normalize — react 18, React v18, @18, ^18.2.0 → all mean React 18.x
4. Version-specific URLs — Next.js /docs/14/, Django /en/5.0/, Python /3.12/library/
5. Default — latest stable; note which version was used

Common pitfalls:

Documentation Retrieval Strategy

Step 1 — Check known llms.txt sites

Load references/llms-txt-sites.md. If the library is listed, use that URL directly.

Step 2 — Try llms.txt on the official site

If not in the known list:

1. If you know the official docs domain → try llms.txt directly
2. If unsure → search for {library name} official site to find the domain
3. Try in order:
   • {official-site}/llms.txt
   • {official-site}/docs/llms.txt
   • {official-site}/llms-full.txt

If llms.txt exists:

• Read the index to find relevant page URLs
• Fetch the specific page(s) for the user's question
• URL fix: if a linked URL ends in .md but returns 404, retry without .md

Step 3 — Fallback strategies (no llms.txt)

Load references/fallback-strategies.md and try in order:

3a. Per-technology strategy — 40+ technologies with best known URLs

3b. GitHub raw markdown (most reliable for OSS):

• Search: {library name} documentation site:github.com
• Try: https://raw.githubusercontent.com/{owner}/{repo}/main/docs/{topic}.md
• Branch fallback: main → master → version branches (e.g., 8.17)

3c. sitemap.xml (universal fallback):

• Fetch {official-site}/sitemap.xml
• Filter for /docs/, /guide/, /reference/ patterns
• Fetch the most relevant page

3d. Platform-specific signals (low reliability for Hugo — skip straight to sitemap/GitHub there):

• /search/search_index.json → MkDocs (full page text)
• /objects.inv → Sphinx
• <meta name="generator"> → Docusaurus, VitePress

3e. Search (last resort):

• Search {library name} official documentation {topic}
• Prefer official domains over tutorials/blogs
• Tell the user which method was used

Spec-Level Drill-Down Requirement (v1.3.3)

For these question types, fetching only the index/overview page is INSUFFICIENT. You MUST fetch the per-item detail page.

Spec-level triggers

• "최신 / 현재 / newest / latest" model, version, release
• Exact API identifiers (model IDs, function names, env var names, parameter names)
• Pricing, token limits, rate limits, quota, deprecation dates
• Context window / max tokens / output limit
• Region availability / preview vs GA / tier availability
• Endpoint compatibility (Responses API, Chat Completions, Batch, embeddings)
• Modalities / tool support (vision, audio, structured output, function calling)
• SDK / package version / migration / breaking changes
• Request parameter names / response schema fields
• Default model 변경 / sunset date / release date / "deprecated" / "legacy"
• Feature support matrix ("X 지원하나?", "Y 가능?")

Drill-down protocol

Load references/webfetch-prompts.md before fetching spec-level pages.

1. Fetch the index/overview page (llms.txt or root docs)
2. If the question matches any spec-level trigger above, do NOT stop here
3. From the index, extract actual href URLs for each relevant item
   • Use Template 1 from references/webfetch-prompts.md
   • Do NOT guess URLs from natural names — *-preview, *-beta, *-canary, *-experimental suffixes are unguessable
4. Fetch each detail page (claim-type-bounded cap below)
5. Cite the detail page URL in the answer, not just the index