## TL;DR
Scan the code for deprecation markers and propagate them into the docs with visible notices. Backfill the changelog entry the deprecation deserved. Add a check that fails generation when a deprecated endpoint lacks a notice.

## The exact error
```text
docs agent documented deprecated endpoints as current
```

## Steps
1. **Find the deprecation signals**
   Search the codebase for deprecation decorators, annotations, and comments on the documented endpoints.
   Success check: You have the list of deprecated endpoints and their markers.
2. **Add visible notices**
   Regenerate or patch the docs so each deprecated endpoint carries a deprecation notice with the replacement and removal version.
   Success check: Every deprecated endpoint shows its status and successor.
3. **Backfill the changelog**
   Add the missing deprecation entries to the changelog under the version where the deprecation landed.
   Success check: The changelog records each deprecation.
4. **Gate future runs**
   Make the agent fail or warn when it documents a deprecated endpoint without a notice.
   Success check: Deprecations cannot go undocumented again.

## When to use
- Use when generated docs hide endpoint deprecations.
- Use when an agent generates API docs from code with deprecation markers.

## When not to use
- Not for endpoints that are removed (those need removal notices, not deprecation).
- Not for handwritten docs missing notices (different workflow).

## Why it happens
Agents document what the code does today and miss the temporal metadata: deprecated means 'works now, going away'. Without explicit handling, deprecation decorators become invisible and users build on endpoints slated for removal.

## Edge cases
Deprecation signals vary by stack (decorators, annotations, naming conventions), so the agent needs a per-repo deprecation map. The changelog backfill matters because deprecation is a versioned event readers look up by release.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_O4hNPC9r1QbnJ1x-jd0egQ