# criv

> criv is an open-source Rust CLI that keeps repository documentation connected
> to the code it describes. Docs point at real files, symbols, and decisions;
> criv validates that those references still resolve before a change lands. It
> runs entirely locally, with no server and no network access. MIT licensed.

## Install with mise

Use the latest released binary in the target repository's `mise.toml`:

```toml
[tools."github:TudorAndrei/criv"]
version = "latest"
```

Then run `mise install`. Building from source with
`cargo install --git https://github.com/TudorAndrei/criv criv` also works.

## Add criv to a codebase

```sh
mise install
criv init                    # create the vault and agent skills
criv watch --once            # build the graph
criv check                   # validate it
```

`criv init` writes only what it needs and leaves existing Markdown alone.
It does not create Git hooks or editor files. Use `--no-skills` to skip the
generated agent skills.

The optional local viewer is in each release archive. Install it into one
selected editor:

```sh
criv install-editor --editor code
criv install-editor --editor cursor
```

Use `--dry-run` to check the editor and bundled viewer without an editor change.

## Give an agent its first task

Tell the agent to run `criv init` at the repository root. It can then read
existing documentation and, when they are available, past project conversations
before it decides which lasting choices need ADRs. The agent must use that
evidence with the current code. It must not invent a decision history.

After the agent writes supported ADRs, run:

```sh
criv watch --once
criv check
```

## Commands

- `criv check` — validate Markdown formatting, note schema, ADR placement,
  wiki-links, source targets, Mermaid C4 diagram references, policy pattern
  references, and ADR supersession rules. `--fix` applies formatting fixes.
- `criv watch --once` — write `.criv/state.json` and content-addressed snapshots.
- `criv query ...` — ask the graph about coverage, citations, ADR governance,
  callers, callees, C4 elements, and diffs.
- `criv enforce --stage commit|push|ci` — run the stage-aware gate used by hooks
  and CI.

## Links

- [Repository](https://github.com/TudorAndrei/criv): source, README, issues
- [Query reference](https://github.com/TudorAndrei/criv/blob/main/docs/query-reference.md): every `criv query` subcommand
- [Releases](https://github.com/TudorAndrei/criv/releases): prebuilt binaries
- [Tooling policy](https://github.com/TudorAndrei/criv/blob/main/docs/tooling.md): hook behavior
- [Get started](https://tudorandrei.github.io/criv/getting-started/): setup guide
- [ADR discovery](https://tudorandrei.github.io/criv/adr-discovery/): agent workflow for ADR candidates
- [Full agent guide](https://tudorandrei.github.io/criv/llms-full.txt): complete setup and ADR workflow
- [Documentation](https://tudorandrei.github.io/criv/docs/): generated repository documentation