# RunLedger Overview

Purpose: deterministic CI harness for tool-using agents. Record tool calls once, replay in CI, and gate regressions with contracts and budgets.

Core components
- Suite (suite.yaml): agent_command, tool_registry, assertions, budgets, baseline_path.
- Cases (cases/*.yaml): per-task input, cassette path, per-case assertions/budgets.
- Cassettes (cassettes/*.jsonl): recorded tool calls/results for deterministic replay.
- Baselines (baselines/*.json): known-good summaries used for regression gates.
- Artifacts (runledger_out/*): run.jsonl, summary.json, junit.xml, report.html.

How it works (high level)
1. Runner launches the agent as a subprocess.
2. Agent and runner exchange JSONL over stdio (tool_call, tool_result, final_output).
3. Runner records or replays tool results.
4. Assertions and budgets are enforced; regressions fail CI.

Quickstart (commented)
```bash
# Install the CLI
pipx install runledger
# Scaffold a demo suite
runledger init
# Record live tool calls to cassettes
runledger run ./evals/demo --mode record
# Promote the run to a baseline
runledger baseline promote --from runledger_out/demo/<run_id> --to baselines/demo.json
# Replay deterministically in CI
runledger run ./evals/demo --mode replay --baseline baselines/demo.json
```

Key links
- Docs: https://runledger.io/docs.html
- Reference: https://runledger.io/reference.html
- Golden Path: https://runledger.io/answers/golden-path
- GitHub: https://github.com/runledger/Runledger