# Staleproof documentation

Staleproof keeps a software organisation's documentation true to its code. This page explains what it does, the problem it solves, how a check works, and where to find everything else in these docs. Start here if you are new; jump to [Install](install.md) or the [Quickstart](getting-started.md) if you want to run it.

## What it is

`staleproof` is an open-source (MIT) command-line tool, GitHub App, GitHub Action, editor extension, Claude Code plugin, pre-commit hook, MCP server, HTTP API and Node.js library, also hosted at [staleproof.dev](https://staleproof.dev). It indexes your repositories into a [FalkorDB](https://www.falkordb.com) graph: Python, TypeScript, JavaScript and Go symbols and the calls between them across repositories, every Markdown, MDX and reStructuredText doc section and code example, and the code each one mentions or calls, with every example call checked against the signature it reaches. For a GitHub pull request it walks that graph to find every doc section the change can make false, predicts which examples the change breaks before anything runs, runs the affected Python, JavaScript and TypeScript examples before and after the change in a sandbox, and (in agent mode) proposes the docs fix with the path in the graph behind each paragraph. Everything it concludes is written back to the graph, so the next check starts from what the last one learned. With no pull request, it checks a working tree before it is pushed, lists the docs that depend on a function before you change it, and audits the docs as they are, with a 0-100 health score.

Without any graph, [`staleproof lint`](lint.md) checks the paths, links, anchors, commands, CLI flags, environment variables and symbols that the docs, READMEs and the files AI coding agents read (`AGENTS.md`, `CLAUDE.md`, Cursor and Copilot rules) name, against the repository itself, and [`staleproof fix`](fix.md) applies the fixes it can verify. The same findings appear in pull requests (annotations, suggestions), in your editor as you type, in Claude Code after each edit, and on `git commit`.

## The problem

Docs drift for two reasons that code review does not catch:

- **The paragraph is in another repository.** A client library, the SDK built on it and the docs site usually live in separate repositories. A change to a function in the client can falsify a page in the docs site that never names that function: the page calls an SDK method, which calls a client method, which calls the function that changed. Nobody reviewing the client pull request sees that page.
- **Nobody re-runs the examples.** Code examples in docs are written once. When the library under them changes, or when they were never quite right, they stay broken until a reader reports it.

Searching for the changed names does not solve either problem, because the docs that break are usually the ones that reach the changed code indirectly.

## A worked example

[falkordb-py#262](https://github.com/FalkorDB/falkordb-py/pull/262) changed one function, `Is_Cluster`. The graph path is:

```text
Is_Cluster ← FalkorDB.__init__ ← README "Asynchronous Example"
```

The README example never names `Is_Cluster`; it calls the constructor, which calls it. Staleproof ran that example (`FalkorDB/falkordb-py:README.md:4`) against falkordb-py installed from source at both commits. It **fails before the pull request** with `TypeError: Redis.__init__() got an unexpected keyword argument 'himport_registry'` and **passes after it**: the pull request fixed a broken README example. A whole-word grep for `Is_Cluster` finds no doc section at all.

The same holds at larger scale. Across the four pull requests checked on FalkorDB's repositories, the graph reaches 120 doc sections; a whole-word grep for the changed names finds 30 of them and matches 227 other sections that no path from the change reaches. For the three falkordb-py pull requests, grep finds none of the 47 sections the graph reaches. On [falkordb-py#276](https://github.com/FalkorDB/falkordb-py/pull/276), 4 changed symbols reach 43 doc sections, 41 of them in other repositories. Every number here comes from [Facts from the graph](FACTS.md), which is generated from the graph.

## How a check works

1. **Index.** `staleproof index` (or the first check of a repository) clones your GitHub repositories, or downloads them where there is no git, and writes one graph per organisation: Python, TypeScript, JavaScript and Go symbols and calls (resolved across repositories through imports, types and re-exports), doc sections and code examples, the symbols each one mentions or uses, and the example lines that no longer fit the code they call.
2. **Ingest the pull request.** The diff between the pull request's two commits becomes symbol-level changes (removed, renamed, signature, modified, added, export-removed), attached to the pull request in the graph.
3. **Trace.** Staleproof walks from each changed symbol back through up to 3 callers, in any repository, to the docs that mention or call them. That is the impact. The changed symbols with no such path are the clearance. For each impacted example it compares the call as written with the code after the pull request: a removed name or a call the new signature rejects is a predicted break.
4. **Prove.** For impacted Python, JavaScript and TypeScript examples, Staleproof installs the repositories from source at the commit before the pull request and at the pull request, runs the example in a sandbox against a scratch FalkorDB, and records both runs.
5. **Judge and remember.** In agent mode a model reads each impacted section, checks maintainers' decisions and earlier verdicts, and records a verdict or proposes an edit for every one. The docs patch is built from those edits. Every check, run and verdict stays in the graph.

The terms used above, in plain language:

- **Impact**: the doc sections and code examples a pull request can make false. A section is impacted when the graph has a path from a changed symbol, through up to 3 callers, to the section (because it mentions one of those symbols, or one of its examples calls one).
- **Evidence path**: that path, written out node by node, changed symbol first and doc last, as in the #262 example above. It is the reason a section is listed, and Staleproof refuses to edit a section without one.
- **Predicted break**: an example whose call fits the code before the pull request and not after it (a removed or renamed name, a new required argument, a keyword that no longer exists), found statically, before anything runs.
- **Mismatch**: an example line that does not fit the code it calls right now, found when the docs are indexed. The [docs audit](audit.md) lists them all, with a health score.
- **Clearance**: the changed symbols that no doc reaches within 3 call hops. The graph proves the absence; each one comes with a `git grep` command so you can check the claim yourself.
- **Verdict**: the conclusion about one section for one pull request: `stale` (with replacement text), `ok`, `governed` (a maintainer decision says it stays as it is) or `skipped`. Maintainers can accept or reject each verdict.
- **Verdict memory**: verdicts, example runs, maintainer decisions and checks stay in the graph. Later checks read them: an identical example run is answered from the graph, a decision is cited instead of re-flagging the section, and earlier verdicts (with whether maintainers accepted them) inform the next judgement.
- **Agent mode and graph mode**: in agent mode a model chooses which tools to call and in what order, judges every impacted section and proposes edits. It needs model API credentials (Claude, or an Anthropic-compatible provider). Graph mode runs the same tools in a fixed order with no model and samples rather than judges: impact, clearance, a ranking of the first impact page and at most 3 example runs. It writes no verdicts and no edits, and needs no key.

## Ways to use it

| Interface | What it is for | Docs |
|---|---|---|
| GitHub App | [Install it](https://github.com/apps/staleproof) on a repository, public or private, no workflow file: a check run on every pull request with the docs it makes wrong, a comment when there is something to say, suggestions for the verified fixes and an **Apply fixes** button | [GitHub App](github-app.md) |
| Website | Paste a pull request URL of any public repository on [staleproof.dev](https://staleproof.dev): indexed on the fly, checked in graph mode, nothing installed; or [audit a repository](https://staleproof.dev/#/audit) and get its README badge | [Install](install.md), [Docs audit](audit.md) |
| CLI | `npx -y staleproof <command>`: index, check a pull request or your working tree, audit, list the docs for a symbol, run an example, record a decision, build the patch; the first command starts FalkorDB and indexes the repository itself | [CLI](cli.md) |
| GitHub Action | `uses: rajkaria/staleproof@v1`, no inputs or secrets: a comment on every pull request with the docs it can make false, the evidence path for each, the examples predicted to break and the examples run before and after, and the verified fixes as suggestions; on a schedule, a docs audit kept in one issue or a weekly fix pull request; on a release, the release gate. On the [GitHub Marketplace](https://github.com/marketplace/actions/staleproof-docs-check) | [GitHub Action](github-action.md), [Fix stale docs](fix.md), [Release gate](release.md) |
| Editors | The VS Code and Cursor extension `staleproof.staleproof` (Visual Studio Marketplace, Open VSX) and `staleproof lsp` for Neovim, Zed, Helix and JetBrains: lint findings as you type, verified quick fixes | [Editors (LSP)](editors.md) |
| Claude Code plugin | `/plugin marketplace add rajkaria/staleproof`, then `/plugin install staleproof@staleproof`: Claude hears which docs each edit made wrong, and fixes them before it stops | [Claude Code plugin](claude-code.md) |
| pre-commit | A hook that stops a commit whose staged changes make a docs reference wrong (pre-commit, lefthook, husky) | [Pre-commit hooks](pre-commit.md) |
| Docs site | A "checked against `abc1234`" stamp on each page: Docusaurus and MkDocs plugins, any HTML | [Checked stamp](verified-stamp.md) |
| MCP server | The tools for Claude Code, Claude Desktop, claude.ai, Cursor, VS Code or any MCP client: hosted at `https://staleproof.dev/api/mcp`, or local over stdio | [MCP server](mcp.md) |
| HTTP API | `staleproof serve`: checks and audits streamed over server-sent events, the README badge, traces, patches, decisions, and the web UI | [HTTP API](http-api.md) |
| Node.js library | Index, check, patch and serve from your own TypeScript code | [Node.js library](library.md) |
| Self-host | Vercel with FalkorDB Cloud, Docker Compose on a VM, or a single machine without Docker | [Deploy](DEPLOY.md) |

## Status

- **Built and run** against FalkorDB's real repositories on the author's machine: the indexer, cross-repository impact, clearance, PageRank ranking, sandboxed example runs, decisions and verdict memory, the CLI, the MCP server, the web UI and graph-mode checks.
- **Agent mode** was written for Claude (default model `claude-sonnet-5-5`) and runs on any Anthropic-compatible API through `ANTHROPIC_BASE_URL`. It has been run with a real model through DeepSeek's Anthropic-compatible endpoint (`deepseek-v4-pro`, also what the live demo uses). The Claude path is tested against a local fake API only.
- **No edit proposed on FalkorDB's repositories yet.** The pull requests checked there are fixes, and every verdict recorded on #262, #267 and #276 is `ok`. Proposing edits and building the patch from them are exercised by the test suite on a fixture organisation.
- **Run end to end** on a private test repository: the GitHub Action's pull request check from the one-click workflow, its suggestions (posted once, a committed one clearing its finding), its weekly fix pull request (opened, updated, closed), and the GitHub App's check runs, comments and suggestions, also next to the Action.
- **Written, not yet exercised**: the Docker image has not been built.
- **Live**: [staleproof.dev](https://staleproof.dev), in hosted mode: any public repository is indexed on first use into a workspace graph of its own, and MCP answers at `/api/mcp`. Examples are not executed there (no sandbox on Vercel); for FalkorDB's repositories, the before/after results come from runs recorded on the graph. Also live: the npm package [`staleproof`](https://www.npmjs.com/package/staleproof), the [GitHub App](https://github.com/apps/staleproof), the Action on the [GitHub Marketplace](https://github.com/marketplace/actions/staleproof-docs-check), the editor extension on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=staleproof.staleproof) and [Open VSX](https://open-vsx.org/extension/staleproof/staleproof), and the Claude Code plugin.

## Limits

- Code is read as Python, TypeScript and JavaScript in published npm packages, or Go; docs as Markdown, MDX or reStructuredText. Python, JavaScript and TypeScript examples are run; Go examples are not. Keyword checks are Python only; JavaScript, TypeScript and Go calls get positional argument counts. Other languages are indexed as text.
- Static checks and predicted breaks judge only calls resolved through imports and types; where the source cannot settle a call, they stay silent.
- GitHub repositories only. Private ones need `GITHUB_TOKEN` (the CLI, a server you run, the GitHub Action) or the GitHub App, which reads the repositories it is installed on into a graph per installation; the hosted site and hosted MCP server index public repositories only.
- Call resolution is static. What types do not reveal falls back to by-name edges (labelled as such) or to no edge.
- The example sandbox is a guard, not a security boundary, and example runs use today's third-party dependencies.

## Documentation map

**Start here**

- [Introduction](README.md): this page.
- [Quickstart](getting-started.md): three ways to start (website, GitHub Action, one command), then a local FalkorDB, FalkorDB's three repositories indexed, a pull request checked, an example run, the patch, the web UI and MCP.
- [Install](install.md): the website, the GitHub Action, the hosted and local MCP servers and the CLI, with what each needs and does.
- [Use cases](use-cases.md): SDK teams with a separate docs site, DevRel after a release, maintainers reviewing pull requests, a weekly docs audit, developers before they push, AI coding agents (with and without a pull request), platform teams with many repositories, and recording maintainer decisions.
- [Docs audit](audit.md): how true the docs are with no pull request: the checks, the score, the CLI, the web page and badge, the API, MCP and the scheduled Action.

**Integrate**

- [CLI](cli.md): every command and option, with examples, output and exit codes.
- [GitHub Action](github-action.md): one-click install, what a run does, inputs and outputs, permissions, the comment format, the docs fix pull request, the scheduled audit and keeping a graph between runs.
- [MCP server](mcp.md): the hosted endpoint, client configuration, the fourteen tools, result format, worked sessions (with and before a pull request) and security notes.
- [HTTP API](http-api.md): every endpoint of `staleproof serve`, including indexing on demand, audits, the badge and MCP over HTTP.
- [Node.js library](library.md): using Staleproof from TypeScript.

**How it works**

- [Core concepts](concepts.md): impact, evidence paths, severity, clearance, static checks, predicted breaks and the audit, verdicts, decisions, runs, checks, the two modes, ids.
- [Indexing](indexing.md): which files are read (Python, TypeScript, JavaScript; Markdown, MDX, reStructuredText), how calls are resolved across repositories, how docs link to and are checked against code, example directives, re-index semantics.
- [Example runner](example-runner.md): virtualenvs per commit, the sandbox, the scratch FalkorDB, skip rules, run outcomes.
- [Decisions and memory](memory.md): maintainer decisions, supersession, verdict review, what every check writes back.
- [The agent](agent.md): the loop, its system prompt and stop condition, model providers, budgets, graph mode.

**Reference**

- [Tools reference](tools.md): the fourteen tools, their parameters and the Cypher each runs.
- [Configuration](configuration.md): every environment variable and global option, and the per-repository `.staleproof.toml`.
- [Graph model and Cypher](GRAPH-MODEL.md): every Cypher statement Staleproof sends to FalkorDB, generated from the code.
- [Facts from the graph](FACTS.md): every number quoted about FalkorDB's repositories, generated from the graph.
- [Architecture](ARCHITECTURE.md): source layout and a check end to end.

**Operate**

- [Deploy](DEPLOY.md): Vercel with FalkorDB Cloud, Docker Compose, or no Docker; hosted mode and its limits.
- [Troubleshooting and FAQ](troubleshooting.md): common errors, limits and answers.

## For LLMs and tools

The site at [staleproof.dev](https://staleproof.dev) serves these docs as plain Markdown: an index at [/llms.txt](https://staleproof.dev/llms.txt), every page in one file at [/llms-full.txt](https://staleproof.dev/llms-full.txt), and each page at `/docs/<slug>.md` (this page is [/docs/introduction.md](https://staleproof.dev/docs/introduction.md)). The repository carries the same index as [llms.txt](../llms.txt), linking to the Markdown files on GitHub.

## Related

- [Quickstart](getting-started.md)
- [Use cases](use-cases.md)
- [Core concepts](concepts.md)
- [Facts from the graph](FACTS.md)