Docs lie. Hashes don't.

SHA-256 citations for docs that reference code.
One stale citation breaks the whole document. By design.

English · 한국어

--- ## The Problem AI agents scatter `README.md` and `AGENTS.md` across directories. It works great until the code changes and the docs don't. Files move, functions get rewritten, but the docs still say *"handler logic lives in `src/handler.ts` at L30-L45."* Over time, **docs become liars.** Agents that trust stale docs make worse decisions. VeriContext embeds a **SHA-256 content hash** into every code citation at write time. Verify later: hash matches or it doesn't. No fuzzy matching. No "close enough." ``` Write time: "handler logic" [ [vctx:src/handler.ts#L30-L45@a1b2c3d4] ] After change: vericontext verify → ❌ hash_mismatch (a1b2c3d4 ≠ f5e6d7c8) ``` **One broken citation → entire doc fails.** Fail-closed by design. ## What It Looks Like Citations live in HTML comments — **invisible** in GitHub, VSCode, or any Markdown renderer. **Raw Markdown:** ```markdown The auth module handles login. ├── src/ ├── tests/ ``` **Rendered:** > The auth module handles login. > > ├── src/ > ├── tests/ `vericontext verify` finds and checks every citation. If `src/auth.ts` changes, the hash breaks, the doc fails. ## Setup ```bash npx skills add amsminn/vericontext --skill vericontext-enforcer ``` Auto-detects your agent (Claude Code, Codex, Antigravity, Cursor, Windsurf, OpenCode, ...) and installs to the right path. Supports [40+ agents](https://github.com/vercel-labs/skills). ```bash # uninstall npx skills remove vericontext-enforcer ``` Once installed, the agent automatically: - Inserts `[[vctx:...]]` citations when referencing code in docs - Runs `vctx_verify_workspace` before commits - Flags stale citations for update

Manual install per agent

The skill lives at `skills/vericontext-enforcer/SKILL.md`. Copy it to the right place: | Agent | Skill path | MCP needed? | |-------|-----------|-------------| | **Claude Code** | `.claude/skills/vericontext-enforcer/` | No | | **Antigravity** | `~/.gemini/antigravity/skills/vericontext-enforcer/` | No | | **Codex** | `.codex/skills/vericontext-enforcer/` | Yes | | **Cursor** | `.cursor/rules/vericontext.mdc` | Yes | | **Windsurf** | `.windsurf/rules/vericontext.md` | Yes | | **OpenCode** | Project rules | Yes | For agents that need MCP, add to your config: ```json { "mcpServers": { "vericontext": { "command": "npx", "args": ["-y", "vericontext", "mcp"] } } } ``` MCP tools: `vctx_cite`, `vctx_claim`, `vctx_verify_workspace`

## How It Works Three operations, one principle: **hash it or it doesn't count.** ``` cite claim verify ┌────────┐ ┌────────────┐ ┌───────────────────────┐ │ file │──→ │ [[vctx:.. │ │ for each token: │ │ +lines │ │ @hash8]] │ │ recompute hash │ └────────┘ └────────────┘ │ match? → ok : fail │ │ any fail → doc fails │ └───────────────────────┘ ``` 1. **Cite** — snapshot a file range with its SHA-256 hash (first 8 hex chars) 2. **Claim** — declare structure facts: `exists-dir`, `missing` 3. **Verify** — check every citation and claim. One failure → whole doc fails ### Token Syntax | Type | Token | Example | |------|-------|---------| | Code citation | `[ [vctx:path#Lstart-Lend@hash8] ]` | `[ [vctx:src/cli.ts#L1-L10@a1b2c3d4] ]` | | Directory exists | `[ [vctx-exists-dir:path/] ]` | `[ [vctx-exists-dir:src/] ]` | | Path missing | `[ [vctx-missing:path] ]` | `[ [vctx-missing:tmp-output/] ]` | > **Files always get hashed.** Any mention of a file — its role, code, or existence — uses `vctx_cite` to hash the full file. Only directories use `exists-dir` claims. ## CLI Reference ```bash npm install -g vericontext # or use npx ``` ### `cite` — generate a code citation ```bash npx vericontext cite --root --path --start-line --end-line [--json] ``` ### `claim` — generate a structure claim ```bash npx vericontext claim --root --kind --path [--json] ``` `--kind`: `exists` | `exists-file` | `exists-dir` | `missing` ### `verify workspace` — verify all claims in a document ```bash npx vericontext verify workspace --root (--in-path | --text ) [--json] ``` | Exit code | Meaning | |-----------|---------| | `0` | All valid | | `1` | One or more failures |

Error reasons

| Reason | Meaning | |--------|---------| | `hash_mismatch` | Content changed since citation | | `file_missing` | File does not exist | | `path_escape` | Path escapes root jail | | `range_invalid` | Line range out of bounds | | `binary_file` | Binary file detected | | `symlink_skipped` | Symlink skipped for determinism | | `invalid_input` | Malformed input |

### `mcp` — run as MCP server ```bash npx vericontext mcp ``` Exposes `vctx_cite`, `vctx_claim`, `vctx_verify_workspace` over stdio. ## GitHub Actions ```yaml - name: Verify docs run: npx -y vericontext verify workspace --root . --in-path README.md --json ``` ### Pre-commit Hook ```bash # .husky/pre-commit npx vericontext verify workspace --root . --in-path README.md --json ``` ## Self-Verifying Docs This README contains hidden VeriContext claims. Verify it: ```bash npx vericontext verify workspace --root . --in-path README.md --json ``` To see how claims look in raw source, view this file with `cat README.md` or click "Raw" on GitHub. ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md). ## License [MIT](LICENSE)

vericontext-enforcer

Installation

SKILL.md