cordance-cli 0.1.2

# cordance-cli

> The `cordance` binary — one command that makes any repo legible to Claude
> Code, Cursor, Codex, axiom, and Cortex without prompt engineering.

[![crates.io](https://img.shields.io/crates/v/cordance-cli.svg)](https://crates.io/crates/cordance-cli)
[![docs.rs](https://docs.rs/cordance-cli/badge.svg)](https://docs.rs/cordance-cli)
[![license](https://img.shields.io/badge/license-MIT_OR_Apache--2.0-blue.svg)](#license)

Part of the [Cordance](https://github.com/0ryant/cordance) workspace.

## Discoverability

Search terms: cordance CLI, AI coding agent onboarding, MCP stdio server,
AGENTS.md generator, CLAUDE.md generator, Cursor rules, Codex bootstrap,
axiom harness target, Cortex candidate receipt.

## Install

```sh
cargo install cordance-cli
```

The binary is named `cordance`. Run `cordance --help` for the full
subcommand surface.

## Golden path

```sh
# 1. Add a cordance.toml at your project root (or rely on defaults).
cd my-project
cordance init

# 2. Compile the context pack. Writes:
#      AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, .codex/AGENTS.md,
#      agents/codex/AGENTS.md, pai-axiom-project-harness-target.json,
#      .cordance/pack.json, .cordance/sources.lock, .cordance/evidence-map.json
cordance pack

# 3. Run deterministic doctrine checks against the pack.
cordance advise

# 4. After making changes, verify nothing drifted out of the managed regions.
cordance check
```

## Subcommands

| Command | Purpose |
| --- | --- |
| `cordance init` | Write a default `cordance.toml`. |
| `cordance scan` | Classify all files; emit a Markdown report at `.cordance/scan-report.md`. |
| `cordance pack` | Compile the context pack and emit every target. |
| `cordance advise` | Run the deterministic doctrine checks (no LLM). |
| `cordance doctrine <topic>` | Look up a topic in `0ryant/engineering-doctrine`. |
| `cordance cortex push` | Emit a `cordance-cortex-receipt-v1-candidate.json`. |
| `cordance check` | Drift detection against `.cordance/sources.lock`. |
| `cordance explain <rule>` | Show source provenance for a generated rule. |
| `cordance watch` | Re-run `pack` on file changes. |
| `cordance serve` | Start the JSON-RPC MCP server (stdio) — see ADR 0014. |
| `cordance doctor` | Pre-flight checks: axiom, doctrine, Ollama reachability. |
| `cordance completions <shell>` | Emit shell completion scripts. |

## Configuration

`cordance.toml` at the project root. Every field has a sensible default:

```toml
[doctrine]
source = "../engineering-doctrine"
fallback_repo = "https://github.com/0ryant/engineering-doctrine"
pin_commit = "auto"

[axiom]
source = "../pai-axiom"
algorithm_latest = "auto"

[llm]
provider = "none"   # "none" | "ollama"

[llm.ollama]
base_url = "http://localhost:11434"
model = "qwen2.5-coder:14b"
temperature = 0.1
num_ctx = 8192

[mcp]
allowed_roots = []
```

## What you get

- An `AGENTS.md` + `CLAUDE.md` with **fenced editable regions** — hand
  edits outside the `<!-- cordance:begin … -->` / `<!-- cordance:end … -->`
  markers survive regeneration.
- `.cursor/rules/*.mdc` derived from your project doctrine.
- `.codex/AGENTS.md` + `agents/codex/AGENTS.md` for Codex CLI.
- A `pai-axiom-project-harness-target.v1` JSON the axiom validators accept
  verbatim (read-only-advisory; no runtime authority claims).
- A `cordance-cortex-receipt-v1-candidate` JSON that Cortex's
  `cortex_memory_accept` flow can ingest.
- A `.cordance/sources.lock` so subsequent drift is auditable.

## Authority model

1. **Engineering doctrine** is the authority for *what good looks like*.
   Cordance never modifies doctrine; it only cites it.
2. **Project state** (ADRs, schemas, tests, source) is the authority for
   *what this project decided*. Cordance reads it; never rewrites it.
3. **Axiom** is the authority for *runtime, policy, and proof boundaries*.
   Cordance emits a harness-target JSON axiom's validators accept verbatim;
   never claims runtime authority.

No invented vocabularies. No LLM-laundered hard rules. No reverse-syncing
runtime roots.

## See also

- [Cordance project README](https://github.com/0ryant/cordance#readme)
- [`BUILD_SPEC.md`](https://github.com/0ryant/cordance/blob/master/docs/BUILD_SPEC.md)
  — the full design specification.
- ADRs under [`docs/adr/`](https://github.com/0ryant/cordance/tree/master/docs/adr).
- Library crates: [`cordance-core`](https://crates.io/crates/cordance-core),
  [`cordance-scan`](https://crates.io/crates/cordance-scan),
  [`cordance-doctrine`](https://crates.io/crates/cordance-doctrine),
  [`cordance-emit`](https://crates.io/crates/cordance-emit),
  [`cordance-advise`](https://crates.io/crates/cordance-advise),
  [`cordance-cortex`](https://crates.io/crates/cordance-cortex),
  [`cordance-llm`](https://crates.io/crates/cordance-llm).

## License

Dual-licensed under MIT OR Apache-2.0.