Skip to content
Back to search

doc-lag

Catch stale documentation after code changes. A local-first CLI for PR-aware documentation drift detection, with evidence-backed findings.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/TarcisioPhilips/doc-lag with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/TarcisioPhilips/doc-lag'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tarcisiophilips--doc-lag/badge.svg)](/listings/tarcisiophilips--doc-lag)

HTML

<a href="/listings/tarcisiophilips--doc-lag"><img src="/api/listings/tarcisiophilips--doc-lag/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires **Node.js 20+** and Git.

CLI

# one-shot (no install)
npx doc-lag scan --base main

# or install globally
npm install -g doc-lag
doc-lag scan --base main --head HEAD

`--head` defaults to `HEAD`. Add `--format json` or `--format sarif` for machines; `--fail-on none` for advisory runs.

GitHub Action

# .github/workflows/doc-lag.yml
name: doc-lag

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  doc-lag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: doc-lag
        uses: TarcisioPhilips/doc-lag@v0
        with:
          fail-on: confirmed

MCP (coding agents)

Prefer the subcommand (there is no separate `doc-lag-mcp` package on npm):

npx -y doc-lag mcp
# same bin, via the doc-lag package:
npx -y -p doc-lag doc-lag-mcp
# or after: npm install -g doc-lag
doc-lag-mcp

**Cursor** — `.cursor/mcp.json`:

{
  "mcpServers": {
    "doc-lag": {
      "command": "npx",
      "args": ["-y", "doc-lag", "mcp"]
    }
  }
}

**Claude Code:**

claude mcp add doc-lag -- npx -y doc-lag mcp

Or commit a project `.mcp.json` with the same `mcpServers` shape.

**VS Code / Copilot** — `.vscode/mcp.json`:

{
  "servers": {
    "doc-lag": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doc-lag", "mcp"]
    }
  }
}

**Codex** — `.codex/config.toml` (project) or `~/.codex/config.toml`:

[mcp_servers.doc-lag]
command = "npx"
args = ["-y", "doc-lag", "mcp"]

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 377 lines
  1. # doc-lag
  2. [![npm](https://img.shields.io/npm/v/doc-lag.svg)](https://www.npmjs.com/package/doc-lag)
  3. [![CI](https://github.com/TarcisioPhilips/doc-lag/actions/workflows/ci.yml/badge.svg)](https://github.com/TarcisioPhilips/doc-lag/actions/workflows/ci.yml)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  5. **Your code changed. Did your docs keep up?**
  6. doc-lag scans a Git range and reports documentation that this change made stale —
  7. with evidence, not guesses. Use it from the CLI, a GitHub Action, or an MCP server
  8. for coding agents.
  9. ```text
  10. scripts.missing:README.md:42:deploy:preview CONFIRMED README.md:42
  11. `npm run deploy:preview` is documented but no longer exists in package.json scripts.
  12. Evidence: package.json#scripts
  13. base: "deploy:preview" was present
  14. head: "deploy:preview" is absent
  15. Suggested action: Update the documented command or restore the script.
  16. ```
  17. It catches removed/renamed `package.json` scripts still documented as `npm`/`pnpm`/`yarn`/`bun`
  18. commands, local Markdown links and paths broken by the diff, and env keys removed from
  19. committed example files (`.env.example` and similar) that docs still mention.
  20. ![Terminal demo: after renaming API_TIMEOUT to REQUEST_TIMEOUT in .env.example, npx doc-lag scan reports a confirmed env.stale finding at docs/setup.md:3 with evidence and a rename suggestion](docs/demo/doc-lag-demo.gif)
  21. ---
  22. ## Quickstart (~1 minute)
  23. Requires **Node.js 20+** and Git.
  24. ### CLI
  25. ```bash
  26. # one-shot (no install)
  27. npx doc-lag scan --base main
  28. # or install globally
  29. npm install -g doc-lag
  30. doc-lag scan --base main --head HEAD
  31. ```
  32. `--head` defaults to `HEAD`. Add `--format json` or `--format sarif` for machines; `--fail-on none` for advisory runs.
  33. ### GitHub Action
  34. ```yaml
  35. # .github/workflows/doc-lag.yml
  36. name: doc-lag
  37. on:
  38. pull_request:
  39. permissions:
  40. contents: read
  41. pull-requests: write
  42. jobs:
  43. doc-lag:
  44. runs-on: ubuntu-latest
  45. steps:
  46. - uses: actions/checkout@v4
  47. with:
  48. fetch-depth: 0
  49. - name: doc-lag
  50. uses: TarcisioPhilips/doc-lag@v0
  51. with:
  52. fail-on: confirmed
  53. ```
  54. ### MCP (coding agents)
  55. Prefer the subcommand (there is no separate `doc-lag-mcp` package on npm):
  56. ```bash
  57. npx -y doc-lag mcp
  58. # same bin, via the doc-lag package:
  59. npx -y -p doc-lag doc-lag-mcp
  60. # or after: npm install -g doc-lag
  61. doc-lag-mcp
  62. ```
  63. **Cursor** — `.cursor/mcp.json`:
  64. ```json
  65. {
  66. "mcpServers": {
  67. "doc-lag": {
  68. "command": "npx",
  69. "args": ["-y", "doc-lag", "mcp"]
  70. }
  71. }
  72. }
  73. ```
  74. **Claude Code:**
  75. ```bash
  76. claude mcp add doc-lag -- npx -y doc-lag mcp
  77. ```
  78. Or commit a project `.mcp.json` with the same `mcpServers` shape.
  79. **VS Code / Copilot** — `.vscode/mcp.json`:
  80. ```json
  81. {
  82. "servers": {
  83. "doc-lag": {
  84. "type": "stdio",
  85. "command": "npx",
  86. "args": ["-y", "doc-lag", "mcp"]
  87. }
  88. }
  89. }
  90. ```
  91. **Codex** — `.codex/config.toml` (project) or `~/.codex/config.toml`:
  92. ```toml
  93. [mcp_servers.doc-lag]
  94. command = "npx"
  95. args = ["-y", "doc-lag", "mcp"]
  96. ```
  97. ---
  98. ## Set it up with your coding agent
  99. Paste this prompt into Claude Code, Cursor, Codex, or VS Code Copilot:
  100. ````text
  101. Set up doc-lag in this repository following
  102. https://github.com/TarcisioPhilips/doc-lag/blob/main/docs/AGENT_SETUP.md
  103. Constraints:
  104. - Read-only setup: do not rewrite application docs unless I ask.
  105. - Do not commit secrets or API keys.
  106. - Add `.github/workflows/doc-lag.yml` with contents: read, pull-requests: write,
  107. actions/checkout@v4 with fetch-depth: 0, and uses: TarcisioPhilips/doc-lag@v0.
  108. - Optionally register the MCP server for the tool I am using (Cursor `.cursor/mcp.json`,
  109. Claude Code `claude mcp add` / `.mcp.json`, VS Code `.vscode/mcp.json`,
  110. Codex `.codex/config.toml`) using `npx -y doc-lag mcp`.
  111. - Do not enable Jev ranking (`--rank jev` / `rank: jev`) unless I explicitly ask.
  112. - Run `npx doc-lag scan --base <default-branch>` (or merge-base) once and report findings.
  113. ````
  114. One-liner for your agent:
  115. ```text
  116. Set up doc-lag in this repo following https://github.com/TarcisioPhilips/doc-lag/blob/main/docs/AGENT_SETUP.md
  117. ```
  118. Machine-readable copies: [`docs/AGENT_SETUP.md`](docs/AGENT_SETUP.md), [`AGENTS.md`](AGENTS.md), [`llms.txt`](llms.txt).
  119. ---
  120. ## How it works
  121. The scan is **PR-aware**: it reports documentation references invalidated by
  122. *this* `base..head` diff. A leftover command that was already stale before the
  123. change is not reported. That keeps the signal focused on the review at hand.
  124. ### Rules
  125. | Rule | Confirmed | Needs-review |
  126. | --- | --- | --- |
  127. | `scripts.missing` | Documented `npm`/`pnpm`/`yarn`/`bun` script invocations removed or renamed in `package.json` | — |
  128. | `links.broken` | Markdown / image links to files deleted or renamed in the diff | Inline `` `path/like` `` heuristics |
  129. | `env.stale` | Code-block / inline-code env keys removed from `.env.example` (and similar) | Bare keys in Markdown table cells |
  130. Markdown in scope: `README.md`, `docs/**/*.md`, `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`.
  131. **confirmed** findings fail CI by default (`--fail-on confirmed`). **needs-review** findings are advisory and do not fail that threshold.
  132. Default scan is offline: no signup, no API keys. The GitHub Action may call the
  133. GitHub API only to create/update the sticky PR comment. The tool never executes
  134. commands found in documentation.
  135. ### Options
  136. | Option | Default | Description |
  137. | --- | --- | --- |
  138. | `--base <ref>` | required | Base Git ref |
  139. | `--head <ref>` | `HEAD` | Head Git ref |
  140. | `--format <text\|json\|sarif>` | `text` | Output format |
  141. | `--fail-on <confirmed\|none>` | `confirmed` | CI threshold |
  142. | `--rank <none\|jev>` | `none` | Optional semantic ranking (**since 0.3.0**) |
  143. | `--cwd <path>` | current directory | Repository to scan |
  144. `DOC_LAG_RANK=jev` is equivalent to `--rank jev` when the flag is omitted (**since 0.3.0**).
  145. ### Exit codes
  146. | Code | Meaning |
  147. | --- | --- |
  148. | 0 | No blocking findings (or `--fail-on none`) |
  149. | 1 | At least one finding at the configured threshold |
  150. | 2 | Usage, configuration, or execution error (including an invalid Git ref) |
  151. Findings go to stdout; errors to stderr.
  152. ### Rule limitations
  153. **`links.broken`** does not report pre-existing broken links, external URLs
  154. (`http://`, `https://`, `mailto:`, …), or missing in-file anchors (file existence
  155. only). Renames detected by Git include the new path as a suggested fix.
  156. **`env.stale`** only reads committed example files (`.env.example`, `.env.sample`,
  157. `.env.template`, and similar) via Git at the given refs — never real `.env`
  158. files. Freeform prose without an extractable key is ignored. A 1:1 remove/add
  159. in the same example file yields a rename hint.
  160. ### What this will *not* do
  161. - Automatically rewrite docs
  162. - Decide whether freeform prose is semantically correct
  163. - Upload repo contents to AI services **unless you opt into `--rank jev`**
  164. - Require MCP, Jev, or another external model (default remains local)
  165. - Execute, install, or evaluate commands mentioned in the scanned repository
  166. ---
  167. ## Optional: Jev ranking *(since 0.3.0)*
  168. By default doc-lag stays offline. When a PR produces many **needs-review**
  169. findings, optional **[Jev](https://docs.typesafe.ai)** ranking (TypeSafe AI’s
  170. non-generative System One model) puts the ones that matter first and sinks likely
  171. false alarms. Ranking **never** changes a finding’s `status` and never upgrades
  172. anything to `confirmed` — order and evidence only.
  173. **When to enable:** large PRs with a noisy needs-review list (especially
  174. `env.stale` table cells or heuristic path mentions). Skip it for small PRs or when
  175. you want a fully offline CI job.
  176. **Example:** three `env.stale` needs-review hits after removing billing/SMTP keys.
  177. Without ranking, a glossary table that merely mentions `LEGACY_TOKEN` sits mixed
  178. in with real config docs. With `--rank jev`, billing/SMTP docs surface first
  179. (~0.96 / ~0.91 confidence) and the glossary mention drops last (~0.22).
  180. **Benchmark** (43 public PRs from 13 open-source projects; evaluation only — not
  181. an endorsement of those projects, TypeSafe, or Jev):
  182. | Ranker | nDCG@3 | P@2 |
  183. | --- | ---: | ---: |
  184. | Jev (`score`) | 0.86 | 0.96 |
  185. | Path overlap | 0.73 | 0.88 |
  186. | BM25 | 0.62 | 0.72 |
  187. Rough cost on that set: ~US$0.007 total and ~0.4s per case.
  188. **Privacy:** when ranking is enabled, PR diff summaries and documentation excerpts
  189. are sent to `https://api.typesafe.ai`. The key is read only from
  190. `TYPESAFE_API_KEY` and is never logged. Missing key → clear error (exit 2).
  191. Timeouts, 4xx/5xx, and rate limits fall back to deterministic order with a warning.
  192. ### Setup (CLI / Action / MCP)
  193. ```bash
  194. export TYPESAFE_API_KEY="your-key" # https://console.typesafe.ai
  195. npx doc-lag scan --base main --head HEAD --rank jev
  196. ```
  197. ```yaml
  198. - uses: TarcisioPhilips/doc-lag@v0
  199. with:
  200. fail-on: confirmed
  201. rank: jev
  202. env:
  203. TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
  204. ```
  205. ```json
  206. {
  207. "name": "scan_diff",
  208. "arguments": {
  209. "base": "main",
  210. "head": "HEAD",
  211. "rank": "jev"
  212. }
  213. }
  214. ```
  215. ---
  216. ## GitHub Action details
  217. On `pull_request`, the Action scans `base.sha..head.sha`, writes a job summary,
  218. and posts or updates a single sticky PR comment. Fork PRs without comment
  219. permission still get the job summary; the step does not fail for that reason.
  220. **Inputs:** `fail-on`, `comment`, `working-directory`, `sarif`, `rank` (**since 0.3.0**),
  221. optional `base` / `head` overrides.
  222. **Outputs:** `findings-count`, `confirmed-count`, `needs-review-count`,
  223. `report-path`, `sarif-path`.
  224. With `comment: true` (default), zero findings still upsert the sticky comment
  225. (“No documentation drift findings…”) so it is obvious the scan ran. Re-runs
  226. match `<!-- doc-lag-sticky -->` instead of posting duplicates.
  227. The Action is a **composite action that installs and builds from source** in
  228. `${{ github.action_path }}` (locked by `package-lock.json`). Pin a tag or SHA for
  229. reproducibility.
  230. Optional SARIF upload:
  231. ```yaml
  232. - name: doc-lag
  233. id: doc-lag
  234. uses: TarcisioPhilips/doc-lag@v0
  235. with:
  236. sarif: true
  237. - if: steps.doc-lag.outputs.sarif-path != ''
  238. uses: github/codeql-action/upload-sarif@v3
  239. with:
  240. sarif_file: ${{ steps.doc-lag.outputs.sarif-path }}
  241. category: doc-lag
  242. ```
  243. (`security-events: write` required for the upload step.)
  244. ### MCP tools
  245. All tools are annotated read-only; paths are constrained to the workspace.
  246. | Tool | Purpose |
  247. | --- | --- |
  248. | `scan_diff` | Scan `base..head` (defaults: merge-base with main → `HEAD`). Set `include_working_tree: true` for uncommitted edits. Optional `rank: "jev"` (**since 0.3.0**). |
  249. | `explain_finding` | Re-scan and return one finding by stable id with full evidence. |
  250. | `list_rules` | List `scripts.missing`, `links.broken`, `env.stale`. |
  251. ---
  252. ## Why this is different
  253. doc-lag focuses on **PR-specific change-to-document traceability** (this diff →
  254. these evidence-backed doc hits), not broad repository linting or age-based
  255. “docs older than code” heuristics. Competitive notes:
  256. [`docs/validation.md`](docs/validation.md), [`PROJECT_SPEC.md`](PROJECT_SPEC.md),
  257. [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
  258. ## Roadmap
  259. 1. Local read-only deterministic CLI (scripts, links, and env rules) — shipped.
  260. 2. GitHub Action + optional SARIF — shipped.
  261. 3. Agent-facing MCP (`doc-lag mcp`; bin `doc-lag-mcp` inside the `doc-lag` package) — shipped on npm.
  262. 4. Optional semantic ranking with Jev (`--rank jev`) — shipped in **0.3.0**.
  263. 5. GitHub Pages only after initial developer adoption.
  264. ## Contributing / development
  265. From a clone (Node 20+):
  266. ```bash
  267. npm install
  268. npm test
  269. npm run build
  270. # scan with the built CLI
  271. node dist/cli.js scan --base main --head HEAD
  272. # or without a build step
  273. npx tsx src/cli.ts scan --base main --head HEAD
  274. npm run scan -- --base main --head HEAD
  275. npm run mcp
  276. ```
  277. Test fixtures are created in a temporary Git repository at runtime (`npm test`).
  278. Issues and PRs welcome.
  279. ## License
  280. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.