API reference drift is the most quantifiable docs failure: the code says the parameter is limit, the docs say max_results, and a customer's integration fails on a Friday. Hand-maintained references drift one endpoint at a time; fully generated references are accurate but unreadable — parameter tables with no prose, no examples, no 'why'.
The missing middle is a reference that's generated from source for accuracy but written for humans — and re-checked every time the source changes.
A Fleet workflow reads the handler source and existing reference as its corpus, drafts human-readable reference updates, and runs a drift review that compares prose to code before a maintainer approves.
genflows:
- name: api-reference
steps:
- {name: update, prompt: "Update the API reference for the endpoints in the corpus: signatures and params from source, prose and examples preserved or improved.", corpus: ["server/routes/**/*.ts", "docs/api/**/*.md"], kind: report, out: reference.md}
- {name: drift, prompt: "Compare every documented signature, param, and status code against the source. Flag mismatches and breaking changes that need a callout.", depends_on: [update], kind: review, out: drift.md}
- {name: maintainer-ok, depends_on: [update, drift], kind: approval, out: decision.md}
Step fingerprinting makes the recurring run cheap: unchanged endpoints skip; the run only re-drafts what the source diff touched. The drift review's breaking-change flags become the maintainer's checklist at the gate.
Source + docs corpus → human-readable update → code-vs-prose drift review → maintainer approval. Generated accuracy with editorial quality, on every change instead of every quarter.
Teams with a public or partner API whose reference docs are loved by customers exactly as much as they are neglected by sprint planning.
Generated references are accurate but inhumane — no examples, no guidance, no migration notes. This keeps prose docs (which customers prefer) and uses the review step to give them generated-level accuracy against the source.
On a schedule, manually, or label-triggered from a shipped API change ticket. Most teams attach it to their API-change workflow so the docs run starts when the code merges.
One binary. Five minutes. See every agent, coordinate every handoff, and keep a full audit trail of what your fleet did.