## TL;DR
Check out the intended tag before generating and verify with `git describe`. Agents that generate from whatever is checked out document whatever happens to be there.

## Error
```text
(api reference documents v2.0 while the release is v2.1; no error text)
```

## Steps
1. Check what is actually checked out in the agent workspace: `git describe --tags` and `git status`. Expected: the real checked-out ref, which often is not what was assumed.
2. Check out the intended tag explicitly: `git checkout v2.1.0` (or the release branch), and make the checkout a named, logged step in the job. Expected: the workspace is on the right ref.
3. Verify a version-identifying symbol (version constant, changelog head) matches the intended release before generating. Expected: independent confirmation of the right version.
4. Re-run generation. Expected: the reference matches the intended tag.

## When to use
- The reference documents the wrong version
- The agent reuses a workspace across releases
- Releases are cut from tags the agent never checks out

## When not to use
- The workspace is on the right tag but docs still lag (a generation or cache problem)
- The wrong content comes from a submodule (a submodule sync problem)
- You document a branch, not a tag (check out the branch instead)

## Tool compatibility
Git with any generator. The checkout-verify pattern is tool-independent.

### Variant phrasings
### agent builds from main instead of the release tag
Pin the ref in the job definition; do not rely on the workspace default.

### tag exists locally but not in the agent's clone
Fetch tags explicitly: `git fetch --tags` before checkout.

## Why it happens
Agent workspaces persist across runs, and nothing forces a checkout to the release ref. Generation runs against the stale checkout and produces confidently wrong versioned docs.

## Provenance

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