## TL;DR
Diff the docs' flag list against the real --help output, remove or correct the stale flags, and switch the agent to generating the CLI reference from the argument parser instead of cached text. Add a drift check comparing docs to --help on every run.

## The exact error
```text
docs list cli flags that no longer exist
```

## Steps
1. **Capture real --help**
   Run the CLI's --help for every command and save the output as the ground truth.
   Success check: You have the actual current flag set.
2. **Diff against the docs**
   Compare the documented flags with the --help output and list every removed, renamed, or added flag.
   Success check: You have the complete drift list.
3. **Regenerate from the parser**
   Change the agent to build the CLI reference from the argument parser definition, not from old docs text.
   Success check: The reference derives from the code, so it cannot drift.
4. **Add a drift check**
   On each run, compare the generated reference with --help output and fail on mismatch.
   Success check: Flag drift fails the pipeline instead of shipping.

## When to use
- Use when CLI docs describe flags that no longer exist.
- Use when an agent documents a CLI tool.

## When not to use
- Not for flags that exist but behave differently (behavior drift, not flag drift).
- Not for handwritten tutorials referencing old flags (update the prose).

## Why it happens
CLI flags change faster than docs: renames and removals land in code while the reference still describes the old surface. Agents that copy forward the previous docs text preserve the drift indefinitely.

## Edge cases
Generating from the parser is the structural fix; the drift check catches the cases where generation is bypassed. Shell completion scripts generated from the same parser stay consistent for free.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ryRweGJqTE-_TPJ3CTB_IA