npm package: @iflow-mcp/amsminn-vericontext
Description: Deterministic, hash-based verification for docs that reference code
Author: amsminn
Latest version: 0.1.5

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./assets/logo-dark.png">
    <source media="(prefers-color-scheme: light)" srcset="./assets/logo-light.png">
    <img alt="vericontext" src="./assets/logo-light.png" width="360">
  </picture>
</p>

<h3 align="center">Docs lie. Hashes don't.</h3>

<p align="center">
  SHA-256 citations for docs that reference code.<br>
  One stale citation breaks the whole document. By design.
</p>

<!-- BADGES:START -->
<!-- generated by add-badges 2026-02-23 -->
<p align="center">
  <a href="https://www.npmjs.com/package/vericontext"><img src="https://img.shields.io/npm/v/vericontext?style=flat-square&logo=npm&logoColor=white" alt="npm version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License: MIT"></a>
  <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square" alt="MCP compatible"></a>
  <a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node >= 20"></a>
</p>
<!-- BADGES:END -->

<p align="center">
  <b>English</b> &middot;
  <a href="README-ko.md">한국어</a>
</p>

---

## 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.
<!-- [ [vctx:src/auth.ts#L1-L50@abcd1234] ] -->

├── src/          <!-- [ [vctx-exists-dir:src/] ] -->
├── tests/        <!-- [ [vctx-exists-dir: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

<details>
<summary>Manual install per agent</summary>

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`

</details>

## 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 <dir> --path <file> --start-line <n> --end-line <n> [--json]
```

### `claim` — generate a structure claim

```bash
npx vericontext claim --root <dir> --kind <kind> --path <path> [--json]
```

`--kind`: `exists` | `exists-file` | `exists-dir` | `missing`

### `verify workspace` — verify all claims in a document

```bash
npx vericontext verify workspace --root <dir> (--in-path <doc> | --text <text>) [--json]
```

| Exit code | Meaning |
|-----------|---------|
| `0` | All valid |
| `1` | One or more failures |

<details>
<summary>Error reasons</summary>

| 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 |

</details>

### `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.

<!-- [[vctx-exists-dir:src/]] -->
<!-- [[vctx:src/cli.ts#L1-L113@4df585c3]] -->
<!-- [[vctx:src/mcp/server.ts#L1-L74@649772e7]] -->
<!-- [[vctx-missing:tmp-output]] -->

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)