## TL;DR
Verify every endpoint the agent documents against the real route surface (your OpenAPI spec paths or the framework's route list) and run a link checker over the built docs before publishing. The agent linked endpoints it imagined because no step compared its output to the actual API. Route-checking turns invented endpoints into caught errors.

```text
docs agent hallucinated api endpoints, generated broken links
```

## Steps
1. Extract the endpoints from the generated docs: search the built pages or sources for path-like links (strings starting with /v1/, /api/, and similar in your project). Expected: a concrete list of documented endpoints.
2. Pull the real route list: from your OpenAPI spec's paths object, or your framework's route listing command. Expected: the authoritative set of endpoints that actually exist.
3. Diff the two lists: every documented endpoint must exist in the real routes. Expected: a concrete list of invented endpoints (in docs, not in routes).
4. Delete or correct the invented endpoints, fix the links, and rebuild. Expected: a link checker over the built site reports zero broken internal endpoint links.
5. Add the gate: the agent diffs documented endpoints against the route list before publishing, and any invented endpoint fails the run. Expected: a test run with a fake endpoint exits nonzero naming it.

## Use this when
- generated docs link to endpoints that 404
- a link checker flags agent-generated endpoint URLs
- API reference was written by an agent, not a human

## Not for this skill when
- endpoints are real but documented wrongly (content issue)
- links break because the API changed after publishing (drift; regenerate)
- humans wrote the docs (review problem)

## Variant phrasings
- agent invented api endpoints in docs
- generated docs link to nonexistent endpoints
- broken endpoint links from docs agent

## Why it happens
Endpoint paths are highly patterned, so a language model can extend the pattern into endpoints that look right but were never implemented. The docs read convincingly, the links resolve nowhere, and users discover it in production.

## Edge cases
- Path parameters make naive string matching fail: compare route patterns, not literal URLs with sample ids.
- Versioned prefixes are a classic mismatch: check the version segment explicitly.
- Endpoints behind feature flags exist in code but not in prod: decide whether docs should list them at all.
- External links rot independently of hallucination: check those on a schedule too.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_r8chTxbNWKT_KW8kEtf3Xw