Quickstart

This guide takes a supported repository from a reviewable policy proposal to its first reproducible Ayni check.

What the first proof looks like

A complete run produces both a human summary and .ayni/last/signals.json. The exact rows depend on the repository, but completion is explicit:

Completion: repository / complete (1 of 1 targets)
rust:workspace test pass
Result: pass

A failed signal can still belong to a complete run. Missing expected work instead produces completion.state = "incomplete" and fails closed.

1. Install Ayni

Follow Installation, then confirm the CLI is available:

ayni --version

Building an image needs Docker with Buildx and Mise. check, verify, and impact run themselves run in the current workspace and need only the selected repository tools.

2. Preview a minimal policy

Ayni can discover supported project roots and propose a minimal, test-only contract without writing anything:

ayni init --dry-run

Review the complete TOML printed to standard output. The proposal enables tests only; it does not guess thresholds or silently enable deeper signals. Create the file explicitly when it is correct:

ayni init --write

--write refuses to overwrite an existing .ayni.toml. Re-run --dry-run whenever you want a fresh proposal to compare by hand.

If automatic project discovery is not appropriate, author .ayni.toml directly. For example:

[checks]
test = true
coverage = false
size = false
complexity = false
deps = false
mutation = false

[languages]
enabled = ["rust"]

[rust]
roots = ["."]

Inspect and validate the effective policy with the single contract command:

ayni contract show

See Configuration for every field and adapter capability tiers before enabling more signals.

3. Share the workflow with coding agents

Create or refresh only Ayni's managed block in AGENTS.md:

ayni agents sync

Review and commit that guidance with the policy. Quality commands never modify agent instructions implicitly.

4. Inspect runtime requirements

The owning language adapters derive an environment plan from the configured roots, enabled signals, and native project metadata:

ayni tools reconcile --check
ayni env show

The plan explains missing or unsupported runtime inputs before anything is locked. Keep native declarations and dependency locks in the repository—for example rust-toolchain.toml and Cargo.lock, or Node's packageManager and native lockfile.

5. Lock and build the managed environment

Provide both AYNI_ENV_CERTIFICATE_SIGNING_KEY and AYNI_ENV_CERTIFICATE_KEY_ID to sign an image with a repository-pinned key. Provide neither for an unsigned image whose metadata still verifies its local lock and protected content. The signing value is a lowercase hexadecimal Ed25519 seed, not a PEM file; see Signing an environment image for generation, key pinning, and CI setup.

ayni env lock
ayni env build
ayni env doctor

Review and commit .ayni.lock. Ayni deliberately does not create or refresh the lock or image when a quality command starts, so changes to the evidence environment remain visible.

Version-control boundary

Commit .ayni.toml, .ayni.lock, and native dependency/tool locks. Ignore .ayni/, which contains local evidence and materialized runtime state.

6. Run the reproducible repository gate

ayni check

check evaluates every enabled, supported signal for every configured root in the current workspace. Do not wrap it in another Ayni command. Launch a built image with your normal container or coding platform tooling, attach the checkout, and run the same ayni check command there.

The full artifact is written to .ayni/last/signals.json. To render the same evidence in another format:

ayni check --output json
ayni check --output markdown

Artifacts record whether execution was managed or host, the contract digest, source fingerprint, environment-lock fingerprint, and relevant managed runtime/tool versions. Results from incompatible provenance are rejected by ayni results compare.

7. Use focused feedback while editing

ayni verify test
ayni verify coverage
ayni impact run --base origin/main

Use the narrowest adapter-supported selectors and copy exact rerun commands from artifact findings. Impact success never replaces the final unscoped ayni check.

8. Confirm the failure and repair loop

Once check passes, deliberately change one test assertion to expect an incorrect result. Run ayni verify test: it should exit nonzero and report the failed test in .ayni/last/signals.json. Restore the assertion and rerun the same verification command. It should now pass. Finish with ayni check to confirm the complete repository contract.

This workflow applies to all five adapters. A failed test is a code failure; missing tools, unreadable reports, or incomplete targets are setup/evidence failures. Read the reported diagnostic before changing code or thresholds. tools reconcile checks native tool metadata, env doctor checks environment readiness, and verify/check execute quality checks. None repairs source or native dependency declarations automatically.

Run in a built image

Images default to /bin/sh. Attach the checkout at the location your platform uses, then run native development commands or ayni check from that checkout.

What to read next

• How Ayni works explains policy, environment, and evidence.
• Adapter capability tiers states where each signal is supported, experimental, or unavailable.
• Managed environments covers locking, image builds, and runtime behavior.
• Signals, Verification, and Impact analysis define the feedback loop.
• CLI reference lists every command and option.