CLAUDE.md

1# Claude Code Documentation Index
2 
3This repository indexes Claude documentation from two Anthropic sources but **commits no
4documentation prose** — only metadata. End users fetch the actual `.md` pages from
5Anthropic's servers at runtime into a local cache.
6 
7- **Platform docs**: https://platform.claude.com (API, guides, Agent SDK, etc.)
8- **Claude Code docs**: https://code.claude.com/docs (CLI-specific documentation)
9 
10The metadata (`paths_manifest.json` + `search_index.json`) is regenerated via GitHub
11Actions every 3 hours with safeguards against catastrophic manifest changes.
12 
13> **Read `ARCHITECTURE.md` first** for the full v2 design: manifest schema, index schema,
14> fetch pipeline, safeguard thresholds, filename conventions, cache layout, and the
15> no-committed-content invariant.
16 
17## Delivery: the `/docs` skill and its sibling skills
18 
19Documentation ships as a Claude Code plugin rooted at `plugin/` (the `source` in
20`.claude-plugin/marketplace.json`). `plugin/skills/docs/SKILL.md` is a lean router
21(manual-only via `disable-model-invocation`, so it fires only on an explicit `/docs`;
22auto-discovery is the `claude-docs` skill's job) that delegates to:
23 
24- **`claude-docs`** — all lookups, questions, and searches. Search strategy, synthesis
25  rules, and URL generation live in its `SKILL.md`; the category-to-label mapping lives in
26  its `manifest-reference.md` (single source of truth). Search intelligence belongs there,
27  not in this file.
28- **`claude-docs-validate`** — freshness checks (`-t`) and health validation
29- **`claude-docs-course`** — interactive course generation (`--course <topic>`)
30- **`claude-docs-changelog`** — HTML changelog reports (`--report`)
31- **`plugin/scripts/manifest-diff.sh`** — "what's new" queries (added/changed/removed
32  pages between manifest revisions; there is no mirror-era `git log -- docs/`)
33 
34A SessionStart hook keeps the metadata current via `git reset --hard origin/main`.
35 
36## Repo-only vs shipped
37 
38Only `plugin/` ships. `scripts/` (Python, executed in GitHub Actions) is **not**
39user-facing and is **not** installed with the plugin. `.doc_fetch/` is ephemeral CI fetch
40scratch and `docs/` is legacy scratch — both are gitignored and must never be committed.
41Keeping fetched prose out of the repo is the entire point of the v2 design.
42 
43## Documentation deletion safeguards
44 
45These exist because of a real incident: broken sitemap URLs once deleted 80%+ of the
46documentation in a single sync. Thresholds live in `scripts/fetcher/config.py`, the checks
47in `scripts/fetcher/safeguards.py`, and `ARCHITECTURE.md` documents both. The design
48intent behind them:
49 
50- Discovery aborts before anything is written if too few pages are found — a failing
51  discovery source must never read as "these pages are gone".
52- A manifest transition that removes too large a share of entries, or that leaves too few
53  behind, aborts rather than committing the loss. The guard is first-run-safe: no v2
54  predecessor means a clean start, not a violation.
55- **Carry-forward**: a page that fails to fetch stays in the manifest marked
56  `fetch_status: stale`. A transient error never drops a page.
57- `update-docs.yml` repeats the minimum-file-count floor as a jq check before committing,
58  so the workflow fails closed even if the Python guard is bypassed.
59 
60Discovery is the **union** of two `llms.txt` files and two sitemaps, keyed by canonical
61URL — llms.txt supplies titles and coverage, sitemaps supply `lastmod`. The four URLs are
62listed with rationale in `scripts/fetcher/config.py`.
63 
64## Working on this repository
65 
66```bash
67# CI script dependencies (uses uv)
68uv sync --group dev
69 
70# Regenerate metadata locally — fetches into gitignored .doc_fetch/, then builds the index
71DOCS_FETCH_LIMIT=8 python3 scripts/fetch_claude_docs.py   # fast preview (.preview manifest in scratch)
72python3 scripts/fetch_claude_docs.py                      # full run, ~10 min, writes paths_manifest.json
73python3 scripts/build_search_index.py                     # build search_index.json from scratch
74 
75# Client search scripts resolve the manifest/index from the repo root — run them in place
76./plugin/skills/claude-docs/scripts/content-search.sh hooks matcher
77./plugin/skills/claude-docs/scripts/fuzzy-search.sh agent sdk python
78./plugin/skills/claude-docs-validate/scripts/validate-paths.sh --quick
79
80uv run pytest tests/ -q
81```
82