Phase 0 docs-fetch surfaced two critical facts that reshaped the build:
1. **`/research/v1` deprecates 2026-05-01** — 11 days from now. Verbatim from Exa docs: "migrate to `/search` with `type: deep-reasoning`." Dropping the /research route from scope before Phase 1 started saved building immediate tech debt. 2. **Webset status state machine** — live docs show `pending|running|idle|paused`, not the `running → idle → completed` claim in exa-mastery SKILL.md. The skill drifted. SKILL.md needs an update.
The Websets path also confirmed: `https://api.exa.ai/websets/v0/websets` with `x-api-key` header. The legacy `fetch_webset_data.py` uses `Bearer` auth and the shorter `/websets/{id}` path — both work but the canonical pattern is `x-api-key` + `/v0/websets/`. Standardized on canonical for the new routes.
I came in trusting our own SKILL.md as the authoritative reference for Exa. It's not, and shouldn't be — Exa is a moving target with active deprecations. Our SKILL.md is a snapshot from 2026-04-30. In 11 days /research dies. In some unknown future, Websets v0 will be replaced by v1. The SKILL.md should explicitly cite a "verified-against" date for every claim and link to the live docs page that produced it.
"Docs decay, vendors deprecate." Same class of risk as architecture.json drift — a reference file says X, reality says Y. Mitigation: every Exa-touching build fetches the live docs for the relevant endpoint in Phase 0. That fetch takes ~10 seconds and catches deprecation notices.
Three updates to exa-mastery SKILL.md needed as a follow-up swarm-upgrade:
1. State-machine table needs `pending|running|idle|paused` not the `running → idle → completed` it currently shows. 2. Every endpoint section needs a "verified-against" date and a link to the live docs page. 3. /research section needs a deprecation banner — sunsets 2026-05-01, migrate to /search?type=deep-reasoning.
Will surface these as a swarm-upgrade proposal after this run lands.
Generated from 023__exa-mastery.md — do not edit this HTML directly.