Drift detection
Generated docs drift from the codebase over time — scripts get renamed, files move, packages change. MDPilot detects this drift and patches only the stale parts.
What drift is
Drift is the gap between what your docs say and what your codebase actually does. It happens gradually — you rename a script, move a file, install a new package, refactor a directory — and the docs quietly become wrong.
For human readers, stale docs are annoying. For AI agents, they are actively harmful: an agent that reads a CLAUDE.md referencing a npm run seed script that no longer exists will confidently run a command that fails.
Two detection methods
MDPilot parses the doc and extracts every command and file path it references — patterns like npm run foo, yarn run foo, and backtick-wrapped paths like `src/lib/foo.ts`. Then it checks each one against the current repo state.
Issues it catches
Script referenced in docs no longer exists in package.json
File path referenced in docs no longer exists on disk
When MDPilot generates a file, it saves a snapshot of the project state to .mdpilot/manifest.json. On a subsequent drift check, it compares the current state to that snapshot and surfaces things that changed but may not be reflected in the docs.
Issues it catches
New npm scripts added since the last generate — possibly worth documenting
Scripts that existed at generate time but have since been removed
New top-level directories that didn't exist when docs were generated
New packages installed since the last generate
Docs older than 90 days — a soft staleness signal
Both methods run together — Method A always runs; Method B adds additional signals if a manifest exists. Results are sorted by severity: High → Medium → Low.
The manifest file
When the MCP server generates a file with writeToDisk: true, it writes a snapshot to .mdpilot/manifest.json at the project root. The snapshot records:
Add .mdpilot/ to .gitignoreif you don't want to commit the manifest, or commit it to share drift history across the team.
Using drift detection
Via the MCP server — open any repo in your IDE and run:
Step 1 — detect drift
"Use mdpilot to check my docs for drift."
Step 2 — patch stale sections
"Use mdpilot to update the stale sections."
The check_drift tool returns a list of issues. The update_docs tool patches ONLY the stale sections — it leaves everything else untouched.
By default, check_drift scans README.md, AGENTS.md, CLAUDE.md, and CONTRIBUTING.md. You can specify different files by name.