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.
| Step | Kind | What it does |
|---|---|---|
update |
Document | “Update the API reference for the endpoints in the corpus: signatures and params from source, prose and examples preserved or improved.” Reads server/routes/**/*.ts, docs/api/**/*.md. |
drift |
Review | “Compare every documented signature, param, and status code against the source. Flag mismatches and breaking changes that need a callout.” |
maintainer-ok |
Approval gate | Pauses the run for a human sign-off; records the approver, timestamp, and note. |
You build this once on the dashboard canvas; your self-hosted Fleet worker pulls the definition and runs it against your repository.
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.
