CLAUDE.md · diff
git:20260916.5038c66 to git:20260917.e38795b
11 added, 4 removed. Audit A to A.
# Claude Code Documentation Index
This repository indexes Claude documentation from two Anthropic sources but **commits no
documentation prose** — only metadata. End users fetch the actual `.md` pages from
Anthropic's servers at runtime into a local cache.
- **Platform docs**: https://platform.claude.com (API, guides, Agent SDK, etc.)
- **Claude Code docs**: https://code.claude.com/docs (CLI-specific documentation)
The metadata (`paths_manifest.json` + `search_index.json`) is regenerated via GitHub
Actions every 3 hours with safeguards against catastrophic manifest changes.
> **Read `ARCHITECTURE.md` first** for the full v2 design: manifest schema, index schema,
> fetch pipeline, safeguard thresholds, filename conventions, cache layout, and the
> no-committed-content invariant.
## Delivery: the `/docs` skill and its sibling skills
Documentation ships as a Claude Code plugin rooted at `plugin/` (the `source` in
`.claude-plugin/marketplace.json`). `plugin/skills/docs/SKILL.md` is a lean router
(manual-only via `disable-model-invocation`, so it fires only on an explicit `/docs`;
auto-discovery is the `claude-docs` skill's job) that delegates to:
- **`claude-docs`** — all lookups, questions, and searches. Search strategy, synthesis
rules, and URL generation live in its `SKILL.md`; the category-to-label mapping lives in
its `manifest-reference.md` (single source of truth). Search intelligence belongs there,
not in this file.
- **`claude-docs-validate`** — freshness checks (`-t`) and health validation
- **`claude-docs-course`** — interactive course generation (`--course <topic>`)
- **`claude-docs-changelog`** — HTML changelog reports (`--report`)
- **`plugin/scripts/manifest-diff.sh`** — "what's new" queries (added/changed/removed
pages between manifest revisions; there is no mirror-era `git log -- docs/`)
A SessionStart hook keeps the metadata current via `git reset --hard origin/main`.
## Repo-only vs shipped
Only `plugin/` ships. `scripts/` (Python, executed in GitHub Actions) is **not**
user-facing and is **not** installed with the plugin. `.doc_fetch/` is ephemeral CI fetch
scratch and `docs/` is legacy scratch — both are gitignored and must never be committed.
Keeping fetched prose out of the repo is the entire point of the v2 design.
## Documentation deletion safeguards
These exist because of a real incident: broken sitemap URLs once deleted 80%+ of the
documentation in a single sync. Thresholds live in `scripts/fetcher/config.py`, the checks
in `scripts/fetcher/safeguards.py`, and `ARCHITECTURE.md` documents both. The design
intent behind them:
- Discovery aborts before anything is written if too few pages are found — a failing
discovery source must never read as "these pages are gone".
- A manifest transition that removes too large a share of entries, or that leaves too few
behind, aborts rather than committing the loss. The guard is first-run-safe: no v2
predecessor means a clean start, not a violation.
- **Carry-forward**: a page that fails to fetch stays in the manifest marked
`fetch_status: stale`. A transient error never drops a page. Pages already
`stale`/`failed` do not count toward the removal share (their disappearance
from discovery confirms an upstream removal), and a manifest more than 25%
- stale is never committed, which bounds the loss those two rules can combine into
- (25% stale dropped free, plus the ordinary 10% live-removal allowance).
+ stale is never committed. Those bounds are **per transition** (25% stale
+ dropped free plus the ordinary 10% live-removal allowance, each measured
+ against the current manifest); they do not compose across runs. The only
+ absolute backstops are the 250 fetched-OK floor and the 200 discovery floor.
+ - **Operator override**: a page block that leaves discovery without first
+ failing to fetch (redirect and delisting in the same upstream deploy) goes
+ `ok` → absent in one run and trips the 10% guard every run thereafter. The
+ `confirm_removals` input on a manual `update-docs` dispatch allows that
+ removal for one run, logging every removed URL; the other guards still apply.
- `update-docs.yml` repeats all three transition guards (page floor, stale-share ceiling,
live-removal share against the `HEAD` manifest) as jq checks before committing, so the
- workflow fails closed even if the Python guard is bypassed. Integration tests pin each
- jq constant to `config.py`.
+ workflow fails closed even if the Python guard is bypassed; the jq mirror honours the
+ same `confirm_removals` override. Integration tests pin each jq constant to `config.py`.
Discovery is the **union** of two `llms.txt` files and two sitemaps, keyed by canonical
URL — llms.txt supplies titles and coverage, sitemaps supply `lastmod`. The four URLs are
listed with rationale in `scripts/fetcher/config.py`.
## Working on this repository
```bash
# CI script dependencies (uses uv)
uv sync --group dev
# Regenerate metadata locally — fetches into gitignored .doc_fetch/, then builds the index
DOCS_FETCH_LIMIT=8 python3 scripts/fetch_claude_docs.py # fast preview (.preview manifest in scratch)
python3 scripts/fetch_claude_docs.py # full run, ~10 min, writes paths_manifest.json
python3 scripts/build_search_index.py # build search_index.json from scratch
# Client search scripts resolve the manifest/index from the repo root — run them in place
./plugin/skills/claude-docs/scripts/content-search.sh hooks matcher
./plugin/skills/claude-docs/scripts/fuzzy-search.sh agent sdk python
./plugin/skills/claude-docs-validate/scripts/validate-paths.sh --quick
uv run pytest tests/ -q
```