boshu2__agentops/cli/docs/COMMANDS.md

# ao CLI Reference

> Auto-generated by `scripts/generate-cli-reference.sh`.
> Do not edit manually. Re-run the script to update.

## Global Flags

          --config string   Config file (default: ~/.agentops/config.yaml)
          --dry-run         Show what would happen without executing
      -h, --help            help for ao
          --json            Output as JSON (shorthand for -o json)
      -o, --output string   Output format (json, table, yaml) (default "table")
      -v, --verbose         Enable verbose output
          --version         version for ao

---

## Commands

### `ao demo`

Run a demonstration of AgentOps as the engineering operating system

```
ao demo [flags]
```

**Flags:**

```
      --concepts   Explain product model
  -h, --help       help for demo
      --quick      2-minute council-first overview
```

---

### `ao init`

Set up a repository for AgentOps: directories and gitignore.

```
ao init [flags]
```

**Flags:**

```
  -h, --help      help for init
      --stealth   Use .git/info/exclude instead of .gitignore
```

---

### `ao quick-start`

Initialize AgentOps in your current project.

```
ao quick-start [flags]
```

**Aliases:**

```
  quick-start, quickstart
```

**Flags:**

```
  -h, --help       help for quick-start
      --minimal    Minimal setup (just directories)
      --no-beads   Skip beads initialization
```

---

### `ao seed`

Plant the AgentOps seed in any repository.

```
ao seed [path] [flags]
```

**Flags:**

```
      --force             Overwrite existing seed files
  -h, --help              help for seed
      --template string   Goal template: go-cli, python-lib, web-app, rust-cli, generic (default: auto-detect)
```

---

### `ao anti-patterns`

List learnings that have been marked as anti-patterns.

```
ao anti-patterns [flags]
```

---

### `ao badge`

Display a visual badge showing knowledge flywheel health status.

```
ao badge [flags]
```

---

### `ao capabilities`

Print the machine-readable contract for the whole ao CLI as JSON.

```
ao capabilities [flags]
```

---

### `ao ci`

Operations on CI run history via the typed BC2 CIStatusPort. The 'latest' subcommand wraps 'gh run list --commit <sha>' through productionCIStatus; 'recent' wraps the unbound-by-sha variant.

```
ao ci [command]
```

**Subcommands:**

#### `ao ci latest`

Get the most recent CI run for a given commit SHA via the typed

```
ao ci latest <sha> [flags]
```

#### `ao ci recent`

List recent CI runs (any SHA) via productionCIStatus. Default

```
ao ci recent [flags]
```

**Flags:**

```
  -h, --help        help for recent
      --limit int   max runs to emit (0 = all up to port cap of 50) (default 10)
```

---

### `ao citation`

Verify citation freshness via the typed BC1 CitationPort. Useful for cross-repo citation auditing and dream-loop staleness checks.

```
ao citation [command]
```

**Subcommands:**

#### `ao citation verify`

Verify a single citation (file, function, or symbol) against HEAD

```
ao citation verify --kind <file|function|symbol> --raw <text> [flags]
```

**Flags:**

```
  -h, --help          help for verify
      --kind string   citation kind (required: file|function|symbol)
      --raw string    citation text to verify (required)
```

---

### `ao claim`

Bind claims to evidence files at a promotion level (PG1-PG4) and list existing bindings, via the typed BC2 ClaimEvidenceBinderPort.

```
ao claim [command]
```

**Subcommands:**

#### `ao claim bind`

Append (or upgrade) a claim→evidence binding via the typed BC2

```
ao claim bind --claim <AOP-CLAIM-X> --path <evidence-path> [--level PG1|PG2|PG3|PG4] [--anchor ...] [flags]
```

**Flags:**

```
      --anchor stringArray   optional in-file anchors (repeatable)
      --claim string         claim ID (required, e.g. AOP-CLAIM-X)
  -h, --help                 help for bind
      --level string         promotion level: PG1|PG2|PG3|PG4 (default "PG1")
      --path string          evidence file path (required, relative to repo root)
```

#### `ao claim list`

Emit all known claim→evidence bindings via the typed BC2 ClaimEvidenceBinderPort. Output is line-delimited JSON.

```
ao claim list [flags]
```

---

### `ao constraint`

Manage constraints compiled from promoted findings.

```
ao constraint [command]
```

**Subcommands:**

#### `ao constraint activate`

Change constraint status from draft to active

```
ao constraint activate <id> [flags]
```

#### `ao constraint list`

List all constraints with status

```
ao constraint list [flags]
```

#### `ao constraint retire`

Change constraint status from active to retired

```
ao constraint retire <id> [flags]
```

#### `ao constraint review`

List constraints compiled >90 days ago without recent citation

```
ao constraint review [flags]
```

---

### `ao contradict`

Scan learnings and patterns for potential contradictions using keyword overlap heuristics.

```
ao contradict [flags]
```

---

### `ao curate`

Curate manages the knowledge curation pipeline: catalog artifacts,

```
ao curate [command]
```

**Subcommands:**

#### `ao curate catalog`

Catalog a knowledge artifact

```
ao curate catalog <path> [flags]
```

#### `ao curate status`

Show curation pipeline status

```
ao curate status [flags]
```

#### `ao curate verify`

Verify gate health against baselines

```
ao curate verify [flags]
```

**Flags:**

```
  -h, --help           help for verify
      --since string   Filter to changes within duration (e.g. 24h, 7d)
```

---

### `ao dedup`

Scan learnings and patterns for near-duplicates using normalized content hashing.

```
ao dedup [flags]
```

**Flags:**

```
  -h, --help    help for dedup
      --merge   Auto-resolve duplicates: keep highest utility, archive the rest
      --yes     Skip the interactive confirmation prompt for large merges (for hooks/CI)
```

---

### `ao doctor`

Run health checks on your AgentOps installation.

```
ao doctor [command]
```

**Flags:**

```
      --dry-run           With --fix: print the plan, change nothing
      --explain string    Expand a single finding by id
      --fix               Apply fixers for findings (routes through mutate())
  -h, --help              help for doctor
      --json              Output results as JSON
      --online            Enable network probes (default: offline-only)
      --only strings      Scope to a subset of detectors or subsystems
      --quick             Run only fast-path detectors (< 200ms)
      --robot             Alias for --json with structured wrapper
      --robot-triage      Emit the mega-command triage JSON
      --severity string   Minimum severity to emit (P0|P1|P2|P3) (default "P3")
      --since string      Diff findings against an earlier run
      --skip strings      Inverse of --only
```

**Subcommands:**

#### `ao doctor capabilities`

Print the machine-readable doctor contract (JSON)

```
ao doctor capabilities [flags]
```

#### `ao doctor diff`

Show what --fix would change (read-only)

```
ao doctor diff [flags]
```

#### `ao doctor explain`

Expand a single finding with full evidence

```
ao doctor explain <finding-id> [flags]
```

#### `ao doctor fix`

Run detectors, then apply fixers (backs up before every mutation)

```
ao doctor fix [flags]
```

#### `ao doctor gc`

Prune old runs (requires --yes and --before <date>)

```
ao doctor gc [flags]
```

**Flags:**

```
      --before string   Prune runs started before this date (YYYY-MM-DD)
  -h, --help            help for gc
      --yes             Confirm pruning (required)
```

#### `ao doctor health`

Cheap one-line liveness summary

```
ao doctor health [flags]
```

#### `ao doctor ls`

List runs in .doctor/runs/

```
ao doctor ls [flags]
```

#### `ao doctor robot-docs`

Print the paste-ready agent handbook (Markdown)

```
ao doctor robot-docs [flags]
```

#### `ao doctor undo`

Restore from .doctor/runs/<run-id>/backups/ (run-id may be 'latest')

```
ao doctor undo <run-id> [flags]
```

**Flags:**

```
      --dry-run   Print the restore plan; do not execute
  -h, --help      help for undo
      --strict    Refuse if any backup is missing or hash-mismatched (default true)
```

---

### `ao flywheel`

Knowledge flywheel operations and status.

```
ao flywheel [command]
```

**Subcommands:**

#### `ao flywheel close-loop`

Close the knowledge flywheel loop by chaining:

```
ao flywheel close-loop [flags]
```

**Flags:**

```
  -h, --help                 help for close-loop
      --pending-dir string   Pending directory to ingest from (default ".agents/knowledge/pending")
      --quiet                Suppress non-essential output (hook-friendly)
      --threshold string     Minimum age for auto-promotion (default: 24h) (default "24h")
```

#### `ao flywheel compare`

Compare retrieval quality between primary and shadow namespaces.

```
ao flywheel compare [flags]
```

**Flags:**

```
  -h, --help            help for compare
      --shadow string   Shadow namespace to compare against primary (default "shadow")
```

#### `ao flywheel gate`

Check the post-structural readiness gate before retrieval-expansion work.

```
ao flywheel gate [flags]
```

**Flags:**

```
      --corpus string   Benchmark corpus directory (defaults to repo testdata)
  -h, --help            help for gate
```

#### `ao flywheel nudge`

Returns structured JSON combining:

```
ao flywheel nudge [flags]
```

#### `ao flywheel status`

Display comprehensive flywheel health status.

```
ao flywheel status [flags]
```

**Flags:**

```
      --days int           Period in days for metrics calculation (default 7)
  -h, --help               help for status
      --namespace string   Citation namespace to evaluate (primary by default) (default "primary")
```

---

### `ao gate`

Manage human review gates for bronze-tier candidates.

```
ao gate [command]
```

**Subcommands:**

#### `ao gate approve`

Approve a bronze-tier candidate for promotion.

```
ao gate approve <candidate-id> [flags]
```

**Flags:**

```
  -h, --help          help for approve
      --note string   Optional approval note
```

#### `ao gate bulk-approve`

Approve all silver-tier candidates older than a threshold.

```
ao gate bulk-approve [flags]
```

**Flags:**

```
  -h, --help                help for bulk-approve
      --older-than string   Age threshold for bulk approval (default "24h")
      --tier string         Tier to bulk approve (default: silver) (default "silver")
```

#### `ao gate pending`

List bronze-tier candidates awaiting human review.

```
ao gate pending [flags]
```

#### `ao gate reject`

Reject a candidate with a required reason.

```
ao gate reject <candidate-id> [flags]
```

**Flags:**

```
  -h, --help            help for reject
      --reason string   Required rejection reason
```

#### `ao gate run`

Invoke a check-*.sh gate via the typed BC2 GateRunnerPort

```
ao gate run <name> [flags]
```

---

### `ao harness`

Inspect the sync state between the canonical skills/ tree and the skills-codex/ mirror via the typed BC5 HarnessPort. Useful as a typed alternative to scripts/audit-codex-parity.sh for drift detection.

```
ao harness [command]
```

**Subcommands:**

#### `ao harness status`

Emit HarnessSkillSync entries via the typed BC5 HarnessPort

```
ao harness status [--skill <name>] [--out-of-sync-only] [flags]
```

**Flags:**

```
  -h, --help               help for status
      --out-of-sync-only   emit only entries with OutOfSync=true
      --skill string       filter to one skill name (empty = all)
```

---

### `ao loop`

Operations on the /evolve cycle history and related Loop bounded-context state. The 'history' subcommand reads .agents/evolve/cycle-history.jsonl via the typed BC3 LoopReaderPort.

```
ao loop [command]
```

**Subcommands:**

#### `ao loop append`

Append a new entry to .agents/evolve/cycle-history.jsonl via the

```
ao loop append --mode <m> --result <r> [flags]
```

**Flags:**

```
      --commit string       git commit SHA (optional)
      --cycle int           cycle number (0 = auto-assign max+1)
  -h, --help                help for append
      --milestone string    milestone note (optional)
      --mode string         cycle mode (required)
      --result string       cycle result: improved|harvested|unchanged|idle (required)
      --trace-json string   XP/BDD/TDD evidence trace as a JSON object — a file path or inline JSON (optional)
```

#### `ao loop converged`

Evaluate the evolve loop's convergence STOP predicate via the typed

```
ao loop converged [flags]
```

**Flags:**

```
      --fitness-baseline             a fitness baseline artifact has been captured
      --green-streak int             current leading green CI streak (caller-supplied evidence)
  -h, --help                         help for converged
      --unconsumed-high-medium int   current unconsumed HIGH+MEDIUM finding count
```

#### `ao loop history`

Read .agents/evolve/cycle-history.jsonl via the typed BC3 LoopReaderPort.

```
ao loop history [flags]
```

**Flags:**

```
      --end int     end cycle number (inclusive; 0 = unbounded)
  -h, --help        help for history
      --latest      emit only the latest entry
      --limit int   max entries to emit (0 = all)
      --start int   start cycle number (inclusive; 0 = unbounded)
```

#### `ao loop hypothesis`

Operations on the /evolve hypothesis ledger (.agents/evolve/hypotheses.jsonl) via the typed BC3 HypothesisLedgerPort.

```
ao loop hypothesis [command]
```

##### `ao loop hypothesis append`

Append a falsifiable hypothesis to .agents/evolve/hypotheses.jsonl

```
ao loop hypothesis append --id <id> --hypothesis <h> --measure <m> [flags]
```

**Flags:**

```
      --check-at-cycle int   future cycle that evaluates the measure
      --cycle-landed int     cycle the patch landed
  -h, --help                 help for append
      --hypothesis string    expected effect of the patch
      --id string            unique hypothesis ID, e.g. H210.1 (required)
      --measure string       how the effect is verified
      --patch string         one-line description of what landed
      --verdict string       verdict: PENDING|VERIFIED|FALSIFIED (default "PENDING")
```

##### `ao loop hypothesis list`

Read .agents/evolve/hypotheses.jsonl via the typed BC3

```
ao loop hypothesis list [flags]
```

#### `ao loop verify`

Audit .agents/evolve/cycle-history.jsonl integrity via the typed

```
ao loop verify [flags]
```

**Flags:**

```
  -h, --help           help for verify
      --max-idle int   max acceptable trailing idle/unchanged streak before flagging dormancy (default 5)
```

---

### `ao maturity`

Check and manage CASS (Contextual Agent Session Search) maturity levels.

```
ao maturity [learning-id] [flags]
```

**Flags:**

```
      --apply                Apply maturity transitions
      --archive              Move expired/evicted/curated files to archive (requires --expire, --evict, or --curate)
      --curate               Normalize metadata and identify low-signal or uncited stale learnings
      --evict                Identify eviction candidates (composite criteria)
      --expire               Scan for expired learnings
      --global               Operate on ~/.agents/learnings instead of the local workspace learnings
  -h, --help                 help for maturity
      --migrate-md           Add default frontmatter to .md learnings missing utility field
      --recalibrate          Reset utility to 0.5 for all learnings
      --scan                 Scan all learnings for pending transitions
      --target-size string   Size-budget eviction: when set with --evict, archive lowest-utility eligible files until the learnings hub falls below the target (e.g. 250M, 1G, 1024K)
      --uncited-days int     Archive provisional/candidate learnings with zero citations older than this many days when used with --curate (default 60)
```

---

### `ao metrics`

Track and report on knowledge flywheel metrics.

```
ao metrics [command]
```

**Subcommands:**

#### `ao metrics baseline`

Capture a baseline snapshot of the knowledge flywheel.

```
ao metrics baseline [flags]
```

**Flags:**

```
      --days int   Period in days for metrics calculation (default 7)
  -h, --help       help for baseline
```

#### `ao metrics cite`

Record that an artifact was cited in this session.

```
ao metrics cite <artifact-path> [flags]
```

**Flags:**

```
  -h, --help             help for cite
      --query string     Search query that surfaced this artifact
      --session string   Session ID (auto-detected if not provided)
      --type string      Citation type: recall, reference, applied (default "reference")
      --vendor string    Model vendor attribution: claude, codex
```

#### `ao metrics cite-report`

Produce an aggregated report from citation data.

```
ao metrics cite-report [flags]
```

**Flags:**

```
      --days int   Period in days (default 30)
  -h, --help       help for cite-report
      --json       Output as JSON
```

#### `ao metrics health`

Display flywheel health metrics including escape velocity status.

```
ao metrics health [flags]
```

**Flags:**

```
  -h, --help               help for health
      --namespace string   Citation namespace to evaluate (primary by default) (default "primary")
```

#### `ao metrics report`

Display a formatted report of knowledge flywheel metrics.

```
ao metrics report [flags]
```

**Flags:**

```
      --days int   Period in days for metrics calculation (default 7)
  -h, --help       help for report
```

---

### `ao operator`

Read and write operator intents via the typed BC4 OperatorPort. Intents are durable records of operator decisions (halt, rescope, handoff) appended to .agents/operator/intents.jsonl.

```
ao operator [command]
```

**Subcommands:**

#### `ao operator list`

Emit recorded OperatorIntents from .agents/operator/intents.jsonl

```
ao operator list [flags]
```

#### `ao operator record`

Append an OperatorIntent to .agents/operator/intents.jsonl via the

```
ao operator record --kind <kind> [--subject S] [--note N] [flags]
```

**Flags:**

```
  -h, --help             help for record
      --kind string      intent kind (required: halt|rescope|handoff|other)
      --note string      free-text note
      --subject string   intent subject (e.g., bd ID, file path)
```

---

### `ao pool`

Manage knowledge candidates in quality pools.

```
ao pool [command]
```

**Subcommands:**

#### `ao pool auto-promote`

Automatically approve (and optionally promote) high-quality candidates

```
ao pool auto-promote [flags]
```

**Flags:**

```
  -h, --help               help for auto-promote
      --include-gold       Include gold-tier candidates when using --promote (default true)
      --promote            Also stage+promote eligible candidates into .agents/ (not just approval)
      --threshold string   Minimum age for auto-promotion (default: 24h) (default "24h")
```

#### `ao pool batch-promote`

Promote pending pool candidates that meet promotion criteria.

```
ao pool batch-promote [flags]
```

**Flags:**

```
  --dry-run   Show what would be promoted without executing
  --force     Promote all pending candidates regardless of criteria
  --min-age   Minimum age threshold (default: 24h)
      --force            Promote all pending regardless of criteria
  -h, --help             help for batch-promote
      --min-age string   Minimum age for promotion eligibility (default "24h")
```

#### `ao pool ingest`

Ingest pending learnings into the quality pool.

```
ao pool ingest [<files-or-globs...>] [flags]
```

**Flags:**

```
      --dir string   Directory to ingest from when no args are provided (default ".agents/knowledge/pending")
  -h, --help         help for ingest
```

#### `ao pool list`

List knowledge candidates filtered by tier and/or status.

```
ao pool list [flags]
```

**Flags:**

```
  -h, --help            help for list
      --limit int       Maximum results to return (default 50, 0 for unlimited) (default 50)
      --offset int      Skip first N results (for pagination)
      --status string   Filter by status (pending, staged, promoted, rejected)
      --tier string     Filter by tier (gold, silver, bronze)
  -w, --wide            Show full IDs without truncation
```

#### `ao pool migrate-legacy`

Move legacy knowledge captures from .agents/knowledge/*.md into

```
ao pool migrate-legacy [flags]
```

**Flags:**

```
  -h, --help                 help for migrate-legacy
      --pending-dir string   Pending directory for migrated captures (default ".agents/knowledge/pending")
      --source-dir string    Source directory containing legacy markdown captures (default ".agents/knowledge")
```

#### `ao pool promote`

Move a staged candidate to the knowledge base (.agents/learnings/ or .agents/patterns/).

```
ao pool promote <candidate-id> [flags]
```

#### `ao pool reindex`

Walk .agents/learnings/*.md and .agents/patterns/*.md, compute the

```
ao pool reindex [flags]
```

**Flags:**

```
      --dry-run   Print counts only; do not write to the index
  -h, --help      help for reindex
      --json      Emit structured JSON output
```

#### `ao pool reject`

Mark a candidate as rejected and move to rejected directory.

```
ao pool reject <candidate-id> [flags]
```

**Flags:**

```
  -h, --help            help for reject
      --reason string   Reason for rejection (required)
```

#### `ao pool show`

Show detailed information about a pool candidate.

```
ao pool show <candidate-id> [flags]
```

#### `ao pool stage`

Move a candidate from pending to staged status.

```
ao pool stage <candidate-id> [flags]
```

**Flags:**

```
  -h, --help              help for stage
      --min-tier string   Minimum tier threshold (default: bronze)
```

---

### `ao reconcile`

Build a read-only reconciliation report for the current AgentOps repo.

```
ao reconcile [flags]
```

**Flags:**

```
  -h, --help           help for reconcile
      --limit int      maximum bead and run records to sample (default 80)
      --repo string    GitHub repo override for gh calls (owner/name)
      --since string   recent .agents evidence window (default "48h")
```

---

### `ao robot-docs`

Print a paste-ready, agent-targeted handbook for the whole ao CLI.

```
ao robot-docs [flags]
```

---

### `ao status`

Display the current state of AgentOps knowledge base.

```
ao status [flags]
```

---

### `ao version`

Display the version, build information, and runtime details.

```
ao version [flags]
```

---

### `ao vibe-check`

Run a comprehensive vibe-check analysis on your repository.

```
ao vibe-check [flags]
```

**Aliases:**

```
  vibe-check, vibecheck
```

**Flags:**

```
      --full           Show all metrics and findings (verbose)
  -h, --help           help for vibe-check
      --markdown       Output as markdown report
      --repo string    Path to git repository (default ".")
      --since string   Time window for analysis (e.g., 7d, 30d, 90d) (default "7d")
```

---

### `ao autodev`

Define, inspect, and validate the repo-local PROGRAM.md contract.

```
ao autodev [command]
```

**Flags:**

```
      --file string   Path to PROGRAM.md or AUTODEV.md (auto-detects PROGRAM.md then AUTODEV.md)
  -h, --help          help for autodev
```

**Subcommands:**

#### `ao autodev init`

Create a PROGRAM.md template

```
ao autodev init [objective] [flags]
```

**Flags:**

```
      --force   Overwrite an existing program file
  -h, --help    help for init
```

#### `ao autodev show`

Show the parsed PROGRAM.md contract

```
ao autodev show [flags]
```

#### `ao autodev validate`

Validate PROGRAM.md structure

```
ao autodev validate [flags]
```

---

### `ao codex`

Codex lifecycle commands for the AgentOps knowledge flywheel.

```
ao codex [command]
```

**Subcommands:**

#### `ao codex ensure-start`

Ensure Codex startup context exists once per thread

```
ao codex ensure-start [flags]
```

**Flags:**

```
  -h, --help             help for ensure-start
      --limit int        Maximum artifacts to surface per category (default 3)
      --no-maintenance   Skip safe close-loop maintenance on start
      --query string     Optional startup query (defaults to the current Codex thread name)
```

#### `ao codex ensure-stop`

Ensure Codex closeout runs once per thread

```
ao codex ensure-stop [flags]
```

**Flags:**

```
      --auto-extract          Write lightweight learnings and handoff artifacts during closeout (default true)
      --close-loop            Run mutating flywheel close-loop maintenance after forging
  -h, --help                  help for ensure-stop
      --no-close-loop         Skip flywheel close-loop maintenance after forging
      --no-history-fallback   Disable history.jsonl fallback when no archived Codex transcript exists
      --session string        Codex session ID to close (defaults to the active thread)
      --transcript string     Explicit transcript path to forge instead of runtime discovery
```

#### `ao codex start`

Start a Codex session with explicit flywheel maintenance (fallback for pre-v0.115.0)

```
ao codex start [flags]
```

**Flags:**

```
  -h, --help             help for start
      --limit int        Maximum artifacts to surface per category (default 3)
      --no-maintenance   Skip safe close-loop maintenance on start
      --query string     Optional startup query (defaults to the current Codex thread name)
```

#### `ao codex status`

Show Codex lifecycle health (native hooks detected when available)

```
ao codex status [flags]
```

**Flags:**

```
      --days int   Citation window in days for Codex lifecycle health (default 7)
  -h, --help       help for status
```

#### `ao codex stop`

Close a Codex session explicitly (fallback for pre-v0.115.0)

```
ao codex stop [flags]
```

**Flags:**

```
      --auto-extract          Write lightweight learnings and handoff artifacts during closeout (default true)
      --close-loop            Run mutating flywheel close-loop maintenance after forging
  -h, --help                  help for stop
      --no-close-loop         Skip flywheel close-loop maintenance after forging
      --no-history-fallback   Disable history.jsonl fallback when no archived Codex transcript exists
      --session string        Codex session ID to close (defaults to the active thread)
      --transcript string     Explicit transcript path to forge instead of runtime discovery
```

---

### `ao cron`

Helpers for the /evolve --mode=loop cron-fire continuity primitive.

```
ao cron [command]
```

**Subcommands:**

#### `ao cron self-adjust`

Render the next /evolve loop-mode cron prompt and emit JSON for the harness.

```
ao cron self-adjust [flags]
```

**Flags:**

```
  -h, --help                 help for self-adjust
      --next string          Optional recommended next bead
      --on string            Trigger marker: 'cycle-close' for default loop usage (default "cycle-close")
      --shipped string       Comma-separated commit:bead entries shipped this cycle
      --sub-beads string     Comma-separated bead ids filed this cycle
      --template string      Path to the cron-loop-mode template (default ".agents/evolve/cron-template.md")
      --tests-delta string   Human-readable tests delta summary
```

---

### `ao eval`

Run deterministic AgentOps evaluation suites and compare run records.

```
ao eval [command]
```

**Subcommands:**

#### `ao eval baseline`

Promote an eval run record as a baseline

```
ao eval baseline <run.json> [flags]
```

**Flags:**

```
  -h, --help                 help for baseline
      --out string           write promoted baseline run record to path
      --promoted-by string   identity promoting the baseline
      --rationale string     rationale for promoting the baseline
```

#### `ao eval baseline-audit`

Audit eval suite baseline policy against promoted baselines

```
ao eval baseline-audit [suite.json ...] [flags]
```

**Flags:**

```
      --baseline-dir string   promoted baseline directory (default ".agents/evals/baselines")
  -h, --help                  help for baseline-audit
      --root string           suite root to scan when no suite paths are provided (default "evals/agentops-core")
```

#### `ao eval cleanup`

Per SCHEMA.md §4 cleanup state-transition rule (rc2):

```
ao eval cleanup [flags]
```

**Flags:**

```
      --delete        Remove Run directories whose status is failed or aborted (never retracted)
      --dry-run       Preview without mutations
  -h, --help          help for cleanup
      --tmp-age int   Minimum tmp-file age in seconds before sweep (0 = sweep all) (default 60)
      --tmp-files     Sweep orphan *.tmp files older than --tmp-age
```

#### `ao eval compare`

Compare an eval run against a baseline

```
ao eval compare <candidate-run.json> <baseline-run.json> [flags]
```

**Flags:**

```
  -h, --help                             help for compare
      --max-aggregate-regression float   allowed aggregate regression before verdict becomes regression
      --max-dimension-regression float   allowed per-dimension regression before verdict becomes regression
      --out string                       write compared eval run record to path
```

#### `ao eval coverage`

Summarize eval suite coverage

```
ao eval coverage [suite.json ...] [flags]
```

**Flags:**

```
  -h, --help                                help for coverage
      --require-dimension stringArray       required score dimension for missing-dimension reporting (default [correctness,process_adherence,artifact_quality,runtime_compatibility,efficiency,safety,learning_closure])
      --require-domain stringArray          required product domain for missing-domain reporting (default [cli,hook,skill,rpi,runtime,retrieval,scenario,mixed,security])
      --require-evidence-kind stringArray   required evidence kind for missing-evidence-kind reporting
      --require-runtime stringArray         required deterministic runtime for missing-runtime reporting (default [static,shell,mock])
      --root string                         suite root to scan when no suite paths are provided (default "evals/agentops-core")
```

#### `ao eval outcomes`

Outcomes is a derived projection of the locked eval substrate (SCHEMA.md), never an alternate authority. Subcommands compile holdout-safe rubric payloads and ingest returned scores into the one verdict format.

```
ao eval outcomes [command]
```

##### `ao eval outcomes compile`

Compile a holdout-safe Outcomes rubric payload from a locked Task + criteria

```
ao eval outcomes compile <input.json> [flags]
```

##### `ao eval outcomes ingest`

Ingest an Outcomes score payload into the one council verdict record

```
ao eval outcomes ingest <score.json> [flags]
```

**Flags:**

```
      --burn-ledger string         path to a JSON HoldoutBurnLedger; when set, a holdout-split score registers a burn and is REFUSED if the (suite,gt) quota is exhausted (gate #3 runtime enforcement), persisted across invocations
      --expect-judge-hash string   refuse the ingest if the score's judge_content_hash does not match this value (gate #2 rubric-drift parity)
  -h, --help                       help for ingest
```

#### `ao eval run`

Run a deterministic eval suite

```
ao eval run <suite.json> [flags]
```

**Flags:**

```
      --baseline string                 compare the run against a baseline run record
      --baseline-mode string            skill-on | skill-off | both — runs the suite once with skills loaded, once with hooks suppressed, or both for a delta scorecard (default "skill-on")
      --context-mode string             none | ab — run context-off/context-on legs over isolated AO_AGENTS_DIR roots (default "none")
      --context-off-agents-dir string   AO_AGENTS_DIR root for the context-off leg (defaults to suite fixtures)
      --context-on-agents-dir string    AO_AGENTS_DIR root for the context-on leg (defaults to suite fixtures)
      --delta-out string                write delta scorecard JSON to path (with --baseline-mode=both or --context-mode=ab)
  -h, --help                            help for run
      --out string                      write eval run record to path
      --run-id string                   stable run id to use in the run record
      --runtime string                  runtime override (static, mock, shell, claude, codex)
```

#### `ao eval scorecard`

Build an eval scorecard from run records

```
ao eval scorecard <candidate-run.json> [baseline-run.json] [flags]
```

**Flags:**

```
  -h, --help                            help for scorecard
      --kind string                     scorecard kind (rpi, skill-change) (default "rpi")
      --max-category-regression float   allowed per-category regression before verdict becomes regression
      --out string                      write scorecard JSON to path
```

#### `ao eval suite`

Suite-level operations against the §6.5 statistical contract.

```
ao eval suite [command]
```

##### `ao eval suite n-required`

Compute power-derived n_required (gate #6 input on Day 3+)

```
ao eval suite n-required [flags]
```

**Flags:**

```
      --alpha float           Type-I error rate (default 0.05)
      --baseline-rate float   Baseline rate (binomial worst-case fallback) (default 0.5)
  -h, --help                  help for n-required
      --mde float             Minimum detectable effect (default 0.05)
      --paired                Paired comparison (default true)
      --power float           Statistical power (1-beta) (default 0.8)
```

##### `ao eval suite verdict`

Compute the §6.5 paired cluster-bootstrap verdict

```
ao eval suite verdict <suite-id> --arms a,b --inputs <bootstrap-inputs.json> [flags]
```

**Flags:**

```
      --B int            Bootstrap resamples (default 10000)
      --arms string      Comma-separated arm ids (default: from suite varied_axis)
  -h, --help             help for verdict
      --inputs string    Path to canonical bootstrap-inputs JSON (REQUIRED)
      --mde float        Minimum detectable effect (used for inconclusive_high_variance)
      --n-required int   Override n_required (default: derived from suite power block)
```

#### `ao eval task`

Operate on the §3 Task primitive of the eval substrate.

```
ao eval task [command]
```

##### `ao eval task add`

Register a Task by copying its yaml + samples into the substrate

```
ao eval task add <task.yaml> [flags]
```

##### `ao eval task list`

List registered Task ids

```
ao eval task list [flags]
```

##### `ao eval task run`

Opens a new Run under $AGENTOPS_EVALS_ROOT/runs/<run-id>/manifest.json

```
ao eval task run <task-id> [flags]
```

**Flags:**

```
      --allow-weak-labels        Allow runs against confidence=weak ground-truth rows (gate #7)
      --cross-spec               Allow ModelSpec drift (gate #4)
      --dry-run                  Run gates and exit without writing a Run manifest
      --ground-truth string      Ground-truth row id (head of supersession chain)
      --harness string           Harness id (recorded into manifest)
      --harness-dir string       Path to harness source dir for snapshot + gate #8
  -h, --help                     help for run
      --inspect-command string   Inspect command recorded into the Run manifest (not executed yet)
      --inspect-version string   Inspect AI version stamped into manifest (default "0.3.216")
      --model-spec string        ModelSpec id (already captured via ao eval models capture)
      --n-samples int            Override Suite.n_samples
      --quick                    Mark Run as quick_session=true (excluded from --vs auto-baseline pool)
      --rig-id string            Rig identifier stamped into the Run manifest
      --sample-split string      Sample split (dev|holdout); default from suite
      --seeds string             Comma-separated seeds (>=3, per §4)
      --suite string             Suite id or path to suite.yaml (required)
```

##### `ao eval task show`

Print a registered Task summary

```
ao eval task show <task-id> [flags]
```

---

### `ao evolve`

Run the v2 autonomous improvement loop.

```
ao evolve [command]
```

**Flags:**

```
      --auto-clean                        Run stale RPI cleanup before each phased cycle
      --auto-clean-stale-after duration   Only auto-clean runs older than this age (default 24h0m0s)
      --bd-sync-policy string             Legacy bd landing checkpoint policy: auto|always|never (auto/always run 'bd export -o /dev/null' on current bd releases) (default "auto")
      --cleanup-prune-branches            Run legacy branch cleanup during supervisor cleanup
      --cleanup-prune-worktrees           Run git worktree prune during supervisor cleanup (default true)
      --command-timeout duration          Timeout for supervisor external commands (git/bd/gate scripts) (default 20m0s)
      --compile                           Enable Compile producer cadence before queue selection
      --compile-defrag                    Run defrag sweep after Compile mine producer tick
      --compile-interval duration         Minimum interval between Compile producer ticks (0 = every cycle) (default 30m0s)
      --compile-since string              Lookback window for Compile mine producer (default "26h")
      --cycle-delay duration              Delay between completed cycles
      --cycle-retries int                 Automatic retry count per cycle after a failed attempt
      --detached-branch-prefix string     Branch prefix used by detached HEAD self-heal (default "codex/auto-rpi")
      --detached-heal                     Auto-create/switch to a named branch when HEAD is detached
      --ensure-cleanup                    Run stale-run cleanup after each cycle (cleanup guarantee)
      --failure-policy string             Cycle failure policy: stop|continue (default "stop")
      --gate-fast-script string           Fast validation gate script path (default "scripts/validate-go-fast.sh")
      --gate-policy string                Quality/security gate policy: off|best-effort|required (default "off")
      --gate-security-script string       Security gate script path (default "scripts/security-gate.sh")
  -h, --help                              help for evolve
      --kill-switch-path string           Supervisor kill-switch file path checked at cycle boundaries (absolute or repo-relative) (default ".agents/rpi/KILL")
      --landing-branch string             Landing target branch (empty resolves origin/HEAD, then current branch, then main)
      --landing-commit-message string     Commit message template for landing policies that commit (default "chore(rpi): autonomous cycle {{cycle}}")
      --landing-lock-path string          Landing lock file path for synchronized integration (absolute or repo-relative) (default ".agents/rpi/landing.lock")
      --landing-policy string             Landing policy after successful cycle: off|commit|sync-push (default "off")
      --lease                             Acquire a single-flight supervisor lease lock before running
      --lease-path string                 Lease lock file path (absolute or repo-relative) (default ".agents/rpi/supervisor.lock")
      --lease-ttl duration                Lease heartbeat TTL for supervisor lock metadata (default 2m0s)
      --max-cycles int                    Maximum cycles (0 = unlimited, stop when queue empty)
      --mode string                       Execution contract: 'burst' (default, agent self-regulates) or 'loop' (operator-driven; STOP markers mechanically refused) (default "burst")
      --ralph                             Enable Ralph-mode preset for unattended external loop supervision (implies supervisor defaults with safe nonstop settings)
      --repo-filter string                Only process queue items targeting this repo (empty = all)
      --retry-backoff duration            Backoff between cycle retry attempts (default 30s)
      --supervisor                        Enable autonomous supervisor mode (lease lock, self-heal, retries, gates, cleanup) (default true)
```

**Subcommands:**

#### `ao evolve blocked`

Record or inspect typed blocked-events emitted by the /evolve loop.

```
ao evolve blocked [flags]
```

**Flags:**

```
      --bead string              Bead id the agent was working on (write mode, optional)
      --clear string             Clear mode: delete entries for the given cycle id (operator-only)
      --cycle string             Override cycle-id (write mode; defaults to date-derived counter)
  -h, --help                     help for blocked
      --json                     Read mode: emit JSON instead of human-readable text
      --ladder-step-failed int   Ladder step that failed (write mode, optional)
      --list                     Read mode: list blocked events
      --needed-context string    Missing context description (write mode, optional)
      --reason string            Reason text (write mode)
      --tail int                 Read mode: show last N entries (default 10)
```

#### `ao evolve config`

Display the resolved per-repo /evolve preferences.

```
ao evolve config [flags]
```

**Flags:**

```
  -h, --help   help for config
      --json   Emit JSON instead of YAML
      --show   Print the resolved preferences (defaults + preferences.yaml)
```

#### `ao evolve next-work`

Run the 5-step next-work ladder and recommend a bead to claim.

```
ao evolve next-work [flags]
```

**Flags:**

```
      --bd-binary string         Override path to the 'bd' binary (default: resolves via PATH)
  -h, --help                     help for next-work
      --include-operator-shape   Do not filter operator-shape beads at step 1
      --json                     Emit JSON instead of human-readable text
      --mode string              Execution contract: 'burst' (default) or 'loop' (default "burst")
```

#### `ao evolve write-stop-marker`

Write a DORMANT, STOP, or KILL marker under .agents/evolve/.

```
ao evolve write-stop-marker [flags]
```

**Flags:**

```
  -h, --help            help for write-stop-marker
      --marker string   Marker name: dormant, stop, or kill
      --mode string     Execution contract: 'burst' or 'loop' (loop refuses unconditionally) (default "burst")
      --reason string   Reason text written to the marker file
```

---

### `ao feedback-loop`

Automatically close the MemRL feedback loop by updating utilities of cited learnings.

```
ao feedback-loop [flags]
```

**Flags:**

```
      --alpha float            EMA learning rate (default 0.1)
      --citation-type string   Filter citations by type (retrieved, applied, all) (default "retrieved")
      --drain                  Walk citations.jsonl and feed entries with zero feedback_at sentinel (idempotent)
      --drain-reward float     Neutral reward applied to drained citations (0.0-1.0) (default 0.5)
  -h, --help                   help for feedback-loop
      --reward float           Override reward value (0.0-1.0); -1 = compute from transcript (default -1)
      --session string         Session ID to process
      --transcript string      Path to transcript for reward computation
```

---

### `ao goals`

Track, measure, and validate project fitness goals.

```
ao goals [command]
```

**Flags:**

```
      --file string   Path to goals file (auto-detects GOALS.md then GOALS.yaml)
  -h, --help          help for goals
      --timeout int   Check timeout in seconds (default 240)
```

**Subcommands:**

#### `ao goals measure`

Run goal checks and produce a snapshot

```
ao goals measure [flags]
```

**Aliases:**

```
  measure, m
```

**Flags:**

```
      --directives           Output directives as JSON (skip gate checks)
      --exclude-tag string   Skip goals whose Tags include this value (e.g. long-cycle)
      --goal string          Measure a single goal by ID
  -h, --help                 help for measure
      --scenarios-only       Evaluate only executable-spec scenario satisfaction; skip shell gate-command execution
      --total-timeout int    Overall measurement timeout in seconds (0 disables)
```

#### `ao goals validate`

Validate GOALS.yaml structure and wiring

```
ao goals validate [flags]
```

**Aliases:**

```
  validate, v
```

#### `ao goals drift`

Compare snapshots for regressions

```
ao goals drift [flags]
```

**Aliases:**

```
  drift, d
```

#### `ao goals export`

Export latest snapshot as JSON (for CI)

```
ao goals export [flags]
```

**Aliases:**

```
  export, e
```

#### `ao goals history`

Show goal measurement history

```
ao goals history [flags]
```

**Aliases:**

```
  history, h
```

**Flags:**

```
      --goal string    Filter history to a specific goal
  -h, --help           help for history
      --since string   Show entries since date (YYYY-MM-DD)
```

#### `ao goals render`

Render the executable-spec layer as BDD/Gherkin text.

```
ao goals render [flags]
```

**Flags:**

```
  -h, --help         help for render
      --out string   Write Gherkin to this file instead of stdout
```

#### `ao goals scenarios`

List or create the executable-spec scenarios linked to GOALS.md directives.

```
ao goals scenarios [flags]
```

**Flags:**

```
      --create string         Create a scenario from this goal description and link it to --directive
      --directive int         Directive display number (filter when listing, target when creating)
      --directive-id string   Filter listing to one directive by stable Directive ID
  -h, --help                  help for scenarios
      --lint                  Lint the directive↔scenario link graph instead of listing
      --source string         Source for a created scenario (human, agent, prod-telemetry) (default "human")
      --status string         Status for a created scenario (active, draft, retired) (default "draft")
      --strict                With --lint, exit non-zero on warnings as well as errors
      --threshold float       Satisfaction threshold for a created scenario (default 0.8)
```

#### `ao goals trace`

Walk the executable-spec trace chain defined in docs/adr/ADR-0005.

```
ao goals trace [flags]
```

**Flags:**

```
      --from string   Render the trace lineage rooted at this directive, scenario, or bead ID
  -h, --help          help for trace
      --orphans       Audit the whole chain for broken references (errors) and missing yields (warnings)
      --strict        Escalate warning-class defects to a non-zero exit (ADR-0005 §4.2)
```

#### `ao goals add`

Add a new goal

```
ao goals add <id> <check-command> [flags]
```

**Aliases:**

```
  add, a
```

**Flags:**

```
      --description string   Goal description
  -h, --help                 help for add
      --type string          Goal type (health, architecture, quality, meta)
      --weight int           Goal weight (1-10) (default 5)
```

#### `ao goals init`

Bootstrap a new GOALS.md file

```
ao goals init [flags]
```

**Flags:**

```
  -h, --help              help for init
      --non-interactive   Use defaults without prompting
      --template string   Goal template (go-cli, python-lib, web-app, rust-cli, generic)
```

#### `ao goals meta`

Run and report meta-goals only

```
ao goals meta [flags]
```

#### `ao goals migrate`

Migrate goals between formats.

```
ao goals migrate [flags]
```

**Aliases:**

```
  migrate, mg
```

**Flags:**

```
  -h, --help    help for migrate
      --to-md   Convert GOALS.yaml to GOALS.md format
```

#### `ao goals prune`

Remove goals referencing nonexistent files

```
ao goals prune [flags]
```

**Aliases:**

```
  prune, p
```

#### `ao goals steer`

Manage directives

```
ao goals steer [command]
```

##### `ao goals steer add`

Add a new directive

```
ao goals steer add <title> [flags]
```

**Flags:**

```
      --description string   Directive description (required)
  -h, --help                 help for add
      --steer string         Steer direction (increase, decrease, hold, explore) (default "increase")
```

##### `ao goals steer apply`

Apply the top re-steer recommendation to GOALS.md via the non-lossy directive-block patcher. Requires policy auto_apply:true AND explicit human confirmation (interactive prompt, or --auto --yes for scripts). A run without confirmation never changes GOALS.md.

```
ao goals steer apply [flags]
```

**Flags:**

```
      --auto            Equivalent to --yes: explicit non-interactive consent to apply
  -h, --help            help for apply
      --policy string   Re-steer policy path (default: docs/re-steer-policy.json)
      --yes             Pre-confirm the apply for non-interactive/scripted use (explicit consent)
```

##### `ao goals steer prioritize`

Move a directive to a new position

```
ao goals steer prioritize <number> <new-position> [flags]
```

##### `ao goals steer recommend`

Run the re-steer policy engine over the verdict ledger and print recommended directive mutations and skip reasons. GOALS.md is never modified. Use `ao goals steer apply` to apply a recommendation.

```
ao goals steer recommend [flags]
```

**Flags:**

```
  -h, --help            help for recommend
      --policy string   Re-steer policy path (default: docs/re-steer-policy.json)
```

##### `ao goals steer remove`

Remove a directive by number

```
ao goals steer remove <number> [flags]
```

---

### `ao handoff`

Write a structured JSON handoff artifact that captures session context

```
ao handoff [summary] [flags]
```

**Flags:**

```
      --collect         Auto-collect git/bead state into the artifact
      --dry-run         Print artifact to stdout without writing file
      --epic string     Epic ID for RPI context
      --goal string     What the session was working on
  -h, --help            help for handoff
      --no-kill         Write artifact without restarting the session via tmux
      --rpi-phase int   RPI phase number (populates RPI context, sets type=rpi)
      --run-id string   Run ID for RPI context
```

---

### `ao orchestrate`

Tooling for the orchestration safe-degradation ladder

```
ao orchestrate [command]
```

**Subcommands:**

#### `ao orchestrate select`

Resolve the orchestration backend via the safe-degradation ladder

```
ao orchestrate select [flags]
```

**Flags:**

```
  -h, --help         help for select
      --json         Emit the selection trace as JSON
      --opt-out      Bypass swarm engines and run on the beads floor
      --pin string   Force a backend: ntm|claude|codex|beads (overrides --opt-out and availability)
```

---

### `ao ratchet`

Track progress through the phased RPI workflow.

```
ao ratchet [command]
```

**Subcommands:**

#### `ao ratchet check`

Check if prerequisites are satisfied for a workflow step.

```
ao ratchet check <step> [flags]
```

**Aliases:**

```
  check, c
```

#### `ao ratchet next`

Show the next pending step in the RPI workflow.

```
ao ratchet next [flags]
```

**Aliases:**

```
  next, n
```

**Flags:**

```
      --epic string   Filter by epic ID
  -h, --help          help for next
```

#### `ao ratchet spec`

Find and output the current spec artifact path.

```
ao ratchet spec [flags]
```

#### `ao ratchet status`

Display the current state of the ratchet chain.

```
ao ratchet status [flags]
```

**Aliases:**

```
  status, s
```

**Flags:**

```
      --chain string   Filter by chain ID
      --epic string    Filter by epic ID
  -h, --help           help for status
```

#### `ao ratchet validate`

Validate that an artifact meets quality requirements.

```
ao ratchet validate <step> [flags]
```

**Flags:**

```
      --changes strings      Files to validate
  -h, --help                 help for validate
      --lenient              Allow legacy artifacts without schema_version (expires in 90 days)
      --lenient-expiry int   Days until lenient bypass expires (default 90)
```

#### `ao ratchet promote`

Record promotion of an artifact to a higher tier.

```
ao ratchet promote <artifact> [flags]
```

**Aliases:**

```
  promote, p
```

**Flags:**

```
  -h, --help     help for promote
      --to int   Target tier (0-4, required) (default -1)
```

#### `ao ratchet record`

Record that a workflow step has been completed.

```
ao ratchet record <step> [flags]
```

**Flags:**

```
      --cycle int            RPI cycle number (1 for first, 2+ for iterations)
  -h, --help                 help for record
      --input string         Input artifact path
      --lock                 Lock the step (engage ratchet) (default true)
      --output string        Output artifact path (required)
      --parent-epic string   Parent epic ID from prior RPI cycle
      --tier int             Quality tier (0-4) (default -1)
```

#### `ao ratchet skip`

Record that a step was intentionally skipped.

```
ao ratchet skip <step> [flags]
```

**Flags:**

```
  -h, --help            help for skip
      --reason string   Reason for skipping (required)
```

#### `ao ratchet find`

Search for artifacts across all locations.

```
ao ratchet find <pattern> [flags]
```

#### `ao ratchet trace`

Trace an artifact back through the ratchet chain.

```
ao ratchet trace <artifact> [flags]
```

#### `ao ratchet migrate`

Migrate chain from legacy YAML format to JSONL.

```
ao ratchet migrate [flags]
```

#### `ao ratchet migrate-artifacts`

Add schema_version: 1 to existing .agents/ artifacts.

```
ao ratchet migrate-artifacts [path] [flags]
```

---

### `ao rpi`

Commands for automating the RPI lifecycle.

```
ao rpi [command]
```

**Subcommands:**

#### `ao rpi cancel`

Cancel active RPI orchestration runs via a CLI kill switch.

```
ao rpi cancel [flags]
```

**Flags:**

```
      --all             Cancel all active runs discovered under current/sibling roots
      --dry-run         Show what would be cancelled without sending signals
  -h, --help            help for cancel
      --run-id string   Cancel one active run by run ID
      --signal string   Signal to send: TERM|KILL|INT (default "TERM")
```

#### `ao rpi cleanup`

Detect and clean up stale RPI phased runs.

```
ao rpi cleanup [flags]
```

**Flags:**

```
      --all                    Clean up all stale runs
      --dry-run                Show what would be done without making changes
  -h, --help                   help for cleanup
      --prune-branches         Delete legacy RPI branches (rpi/*, codex/auto-rpi-*)
      --prune-worktrees        Run 'git worktree prune' after cleanup
      --run-id string          Clean up a specific run by ID
      --stale-after duration   Only clean runs older than this age (0 disables age filtering)
```

#### `ao rpi loop`

Execute RPI cycles in a loop, consuming from next-work.jsonl.

```
ao rpi loop [goal] [flags]
```

**Flags:**

```
      --auto-clean                        Run stale RPI cleanup before each phased cycle
      --auto-clean-stale-after duration   Only auto-clean runs older than this age (default 24h0m0s)
      --bd-sync-policy string             Legacy bd landing checkpoint policy: auto|always|never (auto/always run 'bd export -o /dev/null' on current bd releases) (default "auto")
      --cleanup-prune-branches            Run legacy branch cleanup during supervisor cleanup
      --cleanup-prune-worktrees           Run git worktree prune during supervisor cleanup (default true)
      --command-timeout duration          Timeout for supervisor external commands (git/bd/gate scripts) (default 20m0s)
      --compile                           Enable Compile producer cadence before queue selection
      --compile-defrag                    Run defrag sweep after Compile mine producer tick
      --compile-interval duration         Minimum interval between Compile producer ticks (0 = every cycle) (default 30m0s)
      --compile-since string              Lookback window for Compile mine producer (default "26h")
      --cycle-delay duration              Delay between completed cycles
      --cycle-retries int                 Automatic retry count per cycle after a failed attempt
      --detached-branch-prefix string     Branch prefix used by detached HEAD self-heal (default "codex/auto-rpi")
      --detached-heal                     Auto-create/switch to a named branch when HEAD is detached
      --ensure-cleanup                    Run stale-run cleanup after each cycle (cleanup guarantee)
      --failure-policy string             Cycle failure policy: stop|continue (default "stop")
      --gate-fast-script string           Fast validation gate script path (default "scripts/validate-go-fast.sh")
      --gate-policy string                Quality/security gate policy: off|best-effort|required (default "off")
      --gate-security-script string       Security gate script path (default "scripts/security-gate.sh")
  -h, --help                              help for loop
      --kill-switch-path string           Supervisor kill-switch file path checked at cycle boundaries (absolute or repo-relative) (default ".agents/rpi/KILL")
      --landing-branch string             Landing target branch (empty resolves origin/HEAD, then current branch, then main)
      --landing-commit-message string     Commit message template for landing policies that commit (default "chore(rpi): autonomous cycle {{cycle}}")
      --landing-lock-path string          Landing lock file path for synchronized integration (absolute or repo-relative) (default ".agents/rpi/landing.lock")
      --landing-policy string             Landing policy after successful cycle: off|commit|sync-push (default "off")
      --lease                             Acquire a single-flight supervisor lease lock before running
      --lease-path string                 Lease lock file path (absolute or repo-relative) (default ".agents/rpi/supervisor.lock")
      --lease-ttl duration                Lease heartbeat TTL for supervisor lock metadata (default 2m0s)
      --max-cycles int                    Maximum cycles (0 = unlimited, stop when queue empty)
      --ralph                             Enable Ralph-mode preset for unattended external loop supervision (implies supervisor defaults with safe nonstop settings)
      --repo-filter string                Only process queue items targeting this repo (empty = all)
      --retry-backoff duration            Backoff between cycle retry attempts (default 30s)
      --supervisor                        Enable autonomous supervisor mode (lease lock, self-heal, retries, gates, cleanup)
```

#### `ao rpi mark-probed`

Set probed_stale_at and probed_by on a next-work item whose tractability

```
ao rpi mark-probed [flags]
```

**Flags:**

```
      --at string      Override the probed-at timestamp (RFC3339); defaults to now
      --by string      Probe author tag, e.g. nightly/2026-04-26-v3 (required)
  -h, --help           help for mark-probed
      --id string      Item identifier (id, bead_id, or title) to stamp (required)
      --queue string   Path to next-work.jsonl (default ".agents/rpi/next-work.jsonl")
```

#### `ao rpi nudge`

Send a message to an active tmux-backed RPI phase session.

```
ao rpi nudge [message] [flags]
```

**Flags:**

```
      --all-workers      Send nudge to every worker session for the phase
  -h, --help             help for nudge
      --message string   Nudge message to send
      --phase int        Phase number to target (1-3; defaults to run's current phase)
      --run-id string    Run ID to target (defaults to latest phased state)
      --worker int       Send nudge to one worker (for example: 1)
```

#### `ao rpi parallel`

Run multiple RPI epics concurrently, each in an isolated git worktree.

```
ao rpi parallel [goals...] [flags]
```

**Flags:**

```
      --auto-merge               Opt in to legacy merge/cleanup after successful epics
      --gate-script string       Validation script to run after all merges (e.g., scripts/ci-local-release.sh)
  -h, --help                     help for parallel
      --manifest string          Path to epic manifest file (JSON)
      --merge-order string       Comma-separated epic names for merge order (default: manifest order or arg order)
      --no-merge                 Compatibility alias for the default preserve-for-review behavior
      --phase-timeout duration   Timeout per epic (kills subprocess if exceeded) (default 1h30m0s)
      --runtime-cmd string       Runtime command for phased sessions (default: claude)
      --tmux                     Spawn epics in tmux windows for interactive visibility
```

#### `ao rpi phased`

Orchestrate the full RPI lifecycle using 3 consolidated phases.

```
ao rpi phased <goal> [flags]
```

**Flags:**

```
      --auto-clean-stale                  Run stale-run cleanup before starting phased execution
      --auto-clean-stale-after duration   Only clean stale runs older than this age when auto-clean is enabled (default 24h0m0s)
      --budget string                     Override phase budgets in seconds (<phase>:<seconds>, comma-separated), e.g. discovery:300,validation:120
      --discovery-artifact string         Path to a pre-validated discovery artifact (markdown) used to skip Phase 1 when combined with --from=implementation
      --domain string                     Scope the run to a domain slice (loads docs/domains/<name>/manifest.yaml; phase prompts carry its boundaries)
      --fast-path                         Force fast path (--quick for gates)
      --force                             With --scaffold-domain: overwrite an existing manifest
      --from string                       Start from phase (discovery, implementation, validation; aliases: research, plan, pre-mortem, crank, vibe, post-mortem) (default "discovery")
  -h, --help                              help for phased
      --interactive                       Enable human gates at research and plan phases
      --live-status                       Stream phase progress to a live-status.md file
      --max-retries int                   Maximum retry attempts per gate (default: 3) (default 3)
      --mixed                             Enable cross-vendor mixed-model execution (planner and reviewer from different vendors)
      --no-budget                         Disable all phase budgets and run without time-box transitions
      --no-dashboard                      Disable auto-opening the web dashboard
      --no-test-first                     Opt out of strict-quality spec-first execution (do not pass --test-first to /crank)
      --no-worktree                       Disable worktree isolation (run in current directory)
      --phase-timeout duration            Maximum wall-clock runtime per phase (0 disables timeout) (default 1h30m0s)
      --runtime string                    Phase runtime mode: auto|direct|stream|tmux (default "auto")
      --runtime-cmd string                Runtime command used for phase prompts (Claude uses '-p'; Codex uses 'exec') (default "claude")
      --scaffold-domain string            Write a domain-slice manifest template at docs/domains/<name>/manifest.yaml and exit (does NOT run RPI)
      --stall-timeout duration            Maximum time without progress before declaring stall (0 disables) (default 10m0s)
      --stream-startup-timeout duration   Maximum time to wait for first stream event before falling back to direct execution (0 disables) (default 45s)
      --swarm-first                       Default each phase to swarm/agent-team execution; fall back to direct execution if swarm runtime is unavailable (default true)
      --test-first                        Default to strict-quality spec-first execution by passing --test-first to /crank (default true)
      --tmux-workers int                  When --runtime tmux, number of worker sessions spawned per phase (default 1)
```

#### `ao rpi serve`

Start a production RPI orchestration run or stream its live dashboard.

```
ao rpi serve [goal | run-id] [flags]
```

**Flags:**

```
  -h, --help                 help for serve
      --no-open              Do not open browser automatically
      --orchestrate          Treat first argument as a goal and run full RPI orchestration
      --port int             Port to listen on (default 7799)
      --run-id string        Run ID to watch explicitly (must match rpi-<8-12 hex> or <12 hex>)
      --runtime string       Phase runtime mode for orchestration: auto|direct|stream|tmux
      --runtime-cmd string   Runtime command for orchestration phase prompts (Claude uses '-p'; Codex uses 'exec')
```

#### `ao rpi status`

Display active and recent RPI phased runs.

```
ao rpi status [flags]
```

**Flags:**

```
  -h, --help    help for status
      --watch   Poll every 5s and redraw (Ctrl-C to exit)
```

#### `ao rpi stream`

Read normalized per-run C2 events from events.jsonl.

```
ao rpi stream [flags]
```

**Flags:**

```
      --follow          Follow for newly appended events
      --format string   Output format: human|json|sse (default "human")
  -h, --help            help for stream
      --run-id string   Run ID to stream (defaults to latest phased state)
```

#### `ao rpi verify`

Verify integrity of the RPI ledger.

```
ao rpi verify [flags]
```

**Flags:**

```
  -h, --help     help for verify
      --latest   Verify the latest RPI ledger state (compatibility alias; current workspace ledger is latest)
```

---

### `ao session`

Session lifecycle operations.

```
ao session [command]
```

**Subcommands:**

#### `ao session bootstrap`

Universal init prompt for any agent spawned into an AgentOps repo.

```
ao session bootstrap [flags]
```

**Flags:**

```
  --json       Emit the full status object as JSON (default: 1-line summary).
  --no-mail    Skip the mcp-agent-mail probe even if the MCP server is reachable.
  --robot      Same as --json but tighter exit-code contract for hooks.
  -h, --help      help for bootstrap
      --json      Emit machine-readable status as JSON
      --no-mail   Skip the mcp-agent-mail probe
      --robot     Robot mode: JSON output with tight exit-code contract for SessionStart hooks
```

#### `ao session close`

Close a session by forging its transcript, extracting learnings,

```
ao session close [flags]
```

**Flags:**

```
      --auto-extract     Extract lightweight learnings (quality-filtered) and write handoff artifact
  -h, --help             help for close
      --session string   Session ID to close (default: most recent transcript)
```

---

### `ao validate`

Run a deterministic validation gate over RPI artifacts and emit a single

```
ao validate [flags]
```

**Flags:**

```
      --bead string          Validate artifacts bound to a bead id
      --changes strings      Explicit files to validate
      --gate                 Exit-code mode: 0=PASS/WARN, 1=FAIL, 2=error
  -h, --help                 help for validate
      --json                 Structured verdict (honored in both modes)
      --lenient              Allow legacy artifacts without schema_version
      --lenient-expiry int   Days until lenient bypass expires (default 90)
      --strict               Promote WARN to FAIL (exit 1)
      --warn-as-fail         Alias for --strict
```

---

### `ao completion`

Generate shell completion scripts for ao.

```
ao completion [bash|zsh|fish|powershell]
```

---

### `ao config`

View and manage AgentOps configuration.

```
ao config [command]
```

**Flags:**

```
  -h, --help   help for config
      --show   Show resolved configuration with sources
```

**Subcommands:**

#### `ao config models`

Display the current model cost tier settings with sources.

```
ao config models [flags]
```

**Flags:**

```
  -h, --help               help for models
      --set-skill string   Set a skill-specific tier override (e.g. council=quality)
      --set-tier string    Set the default model cost tier (quality, balanced, budget)
```

---

### `ao memory`

Manage repo-root MEMORY.md for cross-runtime access

```
ao memory [command]
```

**Subcommands:**

#### `ao memory sync`

Write recent session history to a repo-root MEMORY.md with managed block markers.

```
ao memory sync [flags]
```

**Flags:**

```
  -h, --help                 help for sync
      --max-entries int      Maximum session entries to keep (default 10)
      --output-file string   Output path (default: MEMORY.md in repo root)
      --quiet                Suppress output
```

---

### `ao notebook`

Manage the session notebook (MEMORY.md)

```
ao notebook [command]
```

**Subcommands:**

#### `ao notebook update`

Reads the most recent session data and updates MEMORY.md with a "Last Session"

```
ao notebook update [flags]
```

**Flags:**

```
  -h, --help                 help for update
      --max-lines int        Maximum lines in MEMORY.md (default 190)
      --memory-file string   Path to MEMORY.md (auto-detected if omitted)
      --quiet                Suppress output (for hooks)
      --session string       Specific session ID to update from
      --source string        Source: auto|sessions|pending (default "auto")
```

---

### `ao beads`

Commands that help maintain the bd issue tracker alongside the main

```
ao beads [command]
```

**Subcommands:**

#### `ao beads audit`

Audits open and in-progress beads for backlog hygiene issues.

```
ao beads audit [flags]
```

**Flags:**

```
      --auto-close   Close likely-fixed beads when commit or file-change evidence is found
  -h, --help         help for audit
      --json         Emit audit report as JSON
      --strict       Exit 1 when any likely-fixed, likely-stale, or consolidatable bead is found
```

#### `ao beads cluster`

Analyzes open beads for domain overlap and suggests consolidation groups.

```
ao beads cluster [flags]
```

**Flags:**

```
      --apply   Reparent non-representative beads under the cluster representative
  -h, --help    help for cluster
      --json    Emit cluster report as JSON
```

#### `ao beads harvest`

Reads a closed bead via 'bd show <id>' and writes its closure reason

```
ao beads harvest <bead-id> [flags]
```

**Flags:**

```
      --dry-run          Print the learning content to stdout without writing a file
  -h, --help             help for harvest
      --out-dir string   Directory to write the learning file into (default ".agents/learnings")
```

#### `ao beads lint`

Runs 'ao beads verify' on every bead matching a status filter and

```
ao beads lint [flags]
```

**Flags:**

```
  -h, --help            help for lint
      --json            Emit lint report as JSON
      --status string   bd status filter (open, closed, all) (default "open")
```

#### `ao beads resume`

Transfers a stale claim via 'bd update <bead-id> --claim', then appends a

```
ao beads resume <bead-id> [flags]
```

**Flags:**

```
      --agent string    New claimant id (defaults to BEADS_ACTOR env var, else ao-beads-resume).
  -h, --help            help for resume
      --json            Emit the claim_transferred event to stdout (always written to ledger).
      --ledger string   Path to the provenance ledger (relative to repo root). (default "docs/provenance/ledger.jsonl")
```

#### `ao beads scenarios`

Turn a bead's free-text acceptance criteria into structured Gherkin

```
ao beads scenarios [command]
```

##### `ao beads scenarios extract`

Read a bead's acceptance criteria via 'bd show <id> --json', convert the

```
ao beads scenarios extract <bead-id> [flags]
```

**Flags:**

```
      --force   Extract even when the bead already has a '## Scenarios' block
  -h, --help    help for extract
      --json    Emit extracted scenarios as JSON (data on stdout) instead of a Gherkin block
      --write   After printing the block and an operator y/N confirmation, append it to the bead via 'bd update'
```

##### `ao beads scenarios validate`

Read a bead via 'bd show <id> --json' and validate its authored

```
ao beads scenarios validate <bead-id> [flags]
```

**Flags:**

```
  -h, --help   help for validate
      --json   Emit a structured validation verdict as JSON on stdout
```

#### `ao beads stale-claims`

Lists in_progress beads whose claim activity is older than --threshold.

```
ao beads stale-claims [flags]
```

**Flags:**

```
  -h, --help              help for stale-claims
      --json              Emit JSON array conforming to stale-claim-event.v1 (event_type: stale_detected).
      --threshold float   Staleness threshold in hours (claim updated more than N hours ago). (default 4)
```

#### `ao beads verify`

Reads a bead description via 'bd show <id>' and checks every file

```
ao beads verify <bead-id> [flags]
```

**Flags:**

```
  -h, --help      help for verify
      --json      Emit verification report as JSON instead of human-readable text
      --verbose   Include FRESH citations in the output (default: stale only)
```

---

### `ao compile`

Compile makes the existing AgentOps knowledge compiler available through the ao CLI.

```
ao compile [flags]
```

**Flags:**

```
      --batch-size int      Max changed files per LLM prompt (prevents single-giant-prompt on large corpora) (default 25)
      --compile-only        Skip mine and defrag; run compile plus lint
      --defrag-only         Only run mechanical defrag cleanup
      --force               Recompile all source artifacts regardless of hashes
      --force-repair        Actually delete orphans during --repair. Without --force-repair, --repair runs dry.
      --full                Run the full mine, compile, lint, and defrag cycle
  -h, --help                help for compile
      --incremental         Compile only changed source artifacts (default true)
      --lint-only           Only lint the existing compiled wiki
      --max-batches int     Cap number of compile batches per invocation (0 = unlimited)
      --mine-only           Only mine new knowledge signal
      --output-dir string   Compiled wiki output directory (default ".agents/compiled")
      --quiet               Suppress human progress output
      --repair              Remove orphaned fallback stubs from .agents/compiled/ (files with no inbound wikilink traffic)
      --reset               Delete .agents/compiled/ and .hashes.json before compiling (force full rebuild)
      --runtime string      LLM runtime override for headless compilation (ollama, claude, openai)
      --since string        Mine lookback window for full and mine-only modes (default "26h")
      --sources string      Source .agents root to compile (default ".agents")
```

---

### `ao corpus`

Commands that inspect the local .agents/ corpus quality.

```
ao corpus [command]
```

**Subcommands:**

#### `ao corpus capture`

Write an artifact to a corpus root via the typed BC1

```
ao corpus capture --path <relpath> [--body <text>] [--body-file <file>] [--body-stdin] [--root <dir>] [--meta k=v ...] [flags]
```

**Flags:**

```
      --body string        body text (mutually exclusive with --body-file and --body-stdin)
      --body-file string   read body from file
      --body-stdin         read body from stdin
  -h, --help               help for capture
      --meta stringArray   metadata key=value (repeatable)
      --path string        relative path within root (required)
      --root string        corpus root (default: .agents/learnings/)
```

#### `ao corpus fitness`

Compute the corpus-quality fitness vector for the current .agents/

```
ao corpus fitness [flags]
```

**Flags:**

```
  -h, --help   help for fitness
      --json   Emit the fitness vector as JSON
```

#### `ao corpus inject`

Read knowledge from a corpus root via the typed BC1

```
ao corpus inject [--query <text>] [--root <path>] [--limit N] [flags]
```

**Flags:**

```
  -h, --help           help for inject
      --limit int      max items to emit (0 = all) (default 10)
      --query string   ranking query (empty = all items, score 0)
      --root string    corpus root (default: .agents/learnings/)
```

#### `ao corpus restore`

Untars a snapshot produced by ao corpus snapshot. By default refuses to overwrite an

```
ao corpus restore [flags]
```

**Flags:**

```
      --from string   Explicit snapshot tarball path
  -h, --help          help for restore
      --into string   Destination directory (default: .agents) (default ".agents")
      --json          Emit the result as JSON to stdout
      --latest        Pick the newest tarball in the snapshot dir
      --overwrite     Replace an existing destination directory (with .bak rescue)
```

#### `ao corpus snapshot`

Writes the entire .agents/ tree as a tar.gz to a durable directory outside the repo,

```
ao corpus snapshot [flags]
```

**Flags:**

```
  -h, --help                help for snapshot
      --json                Emit the manifest as JSON to stdout
      --output-dir string   Override snapshot dir (default: $AGENTOPS_CORPUS_SNAPSHOT_DIR or ~/.agentops/corpus-snapshots)
```

---

### `ao defrag`

Defrag performs mechanical cleanup of the knowledge base:

```
ao defrag [flags]
```

**Flags:**

```
      --dedup               Flag learnings with >80% content similarity
  -h, --help                help for defrag
      --output-dir string   Directory for defrag report JSON (default ".agents/defrag")
      --prune               Find orphaned learnings not referenced in patterns or research
      --quiet               Suppress progress output
      --stale-days int      Days after which an unreferenced learning is considered stale (default 30)
```

---

### `ao findings`

Manage promoted finding artifacts under .agents/findings/.

```
ao findings [command]
```

**Subcommands:**

#### `ao findings export`

Export finding artifacts to another repo or findings directory

```
ao findings export <id...> [flags]
```

**Flags:**

```
      --all         Export every local finding
      --force       Overwrite destination files if they already exist
  -h, --help        help for export
      --to string   Destination repo root or .agents/findings directory
```

#### `ao findings list`

List active findings

```
ao findings list [query] [flags]
```

**Flags:**

```
      --all         Include retired and superseded findings
  -h, --help        help for list
      --limit int   Maximum findings to return (default 20)
```

#### `ao findings pull`

Pull finding artifacts from another repo or findings directory

```
ao findings pull <id...> [flags]
```

**Flags:**

```
      --all           Pull every source finding
      --force         Overwrite local files if they already exist
      --from string   Source repo root or .agents/findings directory
  -h, --help          help for pull
```

#### `ao findings retire`

Retire a finding artifact

```
ao findings retire <id> [flags]
```

**Flags:**

```
      --by string   Retired-by marker (defaults to current user or ao findings retire)
  -h, --help        help for retire
```

#### `ao findings stats`

Summarize local finding artifact inventory

```
ao findings stats [flags]
```

---

### `ao forge`

The forge command extracts knowledge candidates from various sources.

```
ao forge [command]
```

**Subcommands:**

#### `ao forge batch`

Find and process pending transcripts in bulk.

```
ao forge batch [flags]
```

**Flags:**

```
      --dir string   Specific directory to scan (default: all Claude project dirs)
      --extract      Trigger extraction after forging
  -h, --help         help for batch
      --max int      Maximum transcripts to process (0 = all)
```

#### `ao forge markdown`

Parse markdown (.md) files and extract knowledge candidates.

```
ao forge markdown <path-or-glob> [flags]
```

**Flags:**

```
  -h, --help    help for markdown
      --queue   Queue for learning extraction at next session start
      --quiet   Suppress all output (for hooks)
```

#### `ao forge review`

Review draft session pages in .agents/ao/sessions/ and promote

```
ao forge review [flags]
```

**Flags:**

```
      --dry-run                    Show what would be promoted without writing
      --eval string                Evaluate review decisions against a labeled JSON manifest without writing
  -h, --help                       help for review
      --reviewer-endpoint string   Ollama HTTP endpoint for --reviewer-model (fallback: $AGENTOPS_LLM_ENDPOINT or http://localhost:11434)
      --reviewer-model string      LLM model tag for Tier 2 reviewer decisions (e.g. gemma2:9b)
      --sessions-dir string        Directory containing session pages (default: .agents/ao/sessions)
```

#### `ao forge transcript`

Parse Claude Code JSONL transcript files and extract knowledge candidates.

```
ao forge transcript <path-or-glob> [flags]
```

**Flags:**

```
  -h, --help                  help for transcript
      --last-session          Process only the most recent transcript
      --legacy-local-llm      Allow legacy local Ollama/Gemma fallback for --tier=1 when no AgentWorker queue is configured
      --llm-endpoint string   Legacy Ollama HTTP endpoint for --tier=1 (fallback: $AGENTOPS_LLM_ENDPOINT or http://localhost:11434)
      --max-chars int         Per-chunk character budget for --tier=1 legacy local LLM mode (default: conservative built-in budget)
      --model string          Legacy local LLM model tag for --tier=1 (e.g. gemma2:9b)
      --queue                 Queue session for learning extraction at next session start
      --quiet                 Suppress all output (for hooks)
      --tier int              Tier 1 transcript processing: enqueue to configured Dream worker; local Ollama fallback requires --legacy-local-llm
```

---

### `ao harvest`

Walks all .agents/ directories across the workspace, extracts learnings,

```
ao harvest [flags]
```

**Flags:**

```
  -h, --help                   help for harvest
      --include string         Artifact types to include (comma-separated) (default "learnings,patterns,research")
      --max-file-size int      Skip files larger than this (bytes) (default 1048576)
      --max-promotions int     Advisory volume gate: emit a stderr WARN when promotions exceed this count (0 disables; AO_MAX_PROMOTIONS env var as fallback). Never blocks. (default 500)
      --min-confidence float   Minimum confidence for promotion (default 0.5)
      --output-dir string      Directory for harvest catalog output (default ".agents/harvest")
      --promote-to string      Promotion destination for high-value artifacts (default ~/.agents/learnings)
      --quiet                  Suppress progress output
      --roots string           Base directories to scan (comma-separated) (default ~/gt)
```

---

### `ao inject`

Inject searches and outputs relevant knowledge for explicit or JIT context.

```
ao inject [context] [flags]
```

**Flags:**

```
      --apply-decay               Apply confidence decay before ranking
      --bead string               Bead ID for work-scoped knowledge injection
      --context string            Context query for filtering (alternative to positional arg)
      --for string                Skill name — assembles context per skill's context declaration
      --format string             Output format: markdown, json (default "markdown")
  -h, --help                      help for inject
      --index-only                Output compact knowledge index table instead of full content
      --max-tokens int            Maximum tokens to output (default 1500)
      --no-cite                   Disable citation recording
      --predecessor string        Path to predecessor handoff file for context injection
      --profile                   Include .agents/profile.md identity artifact in output
      --quarantine-flagged        Quarantine flagged learnings from quality report
      --session string            Session ID for citation tracking (auto-generated if empty)
      --session-type string       Session type for scoring boost (career, research, debug, implement, brainstorm)
      --utility-weight utility:   Multiplier on utility's contribution to ranking (0=disable, 1=default, >1=emphasize). Reads utility: frontmatter; closes the eval-verdict-compiler loop. (default 1)
```

---

### `ao knowledge`

Knowledge turns a mature .agents corpus into operator-ready surfaces.

```
ao knowledge [command]
```

**Subcommands:**

#### `ao knowledge activate`

Run the full knowledge activation outer loop

```
ao knowledge activate [flags]
```

**Flags:**

```
      --goal string   Optional goal for briefing compilation during activation
  -h, --help          help for activate
```

#### `ao knowledge beliefs`

Refresh the belief book from promoted evidence

```
ao knowledge beliefs [flags]
```

#### `ao knowledge brief`

Compile a goal-time briefing

```
ao knowledge brief [flags]
```

**Flags:**

```
      --goal string   Goal to compile into a briefing
  -h, --help          help for brief
```

#### `ao knowledge gaps`

Report thin topics, promotion gaps, and next mining work

```
ao knowledge gaps [flags]
```

#### `ao knowledge playbooks`

Refresh playbook candidates from healthy topics

```
ao knowledge playbooks [flags]
```

**Flags:**

```
  -h, --help           help for playbooks
      --include-thin   Include thin topics when building playbook candidates
```

---

### `ao lookup`

Lookup retrieves full content of specific knowledge artifacts.

```
ao lookup [id] [flags]
```

**Flags:**

```
      --bead string      Filter by source bead ID
      --cite string      Citation type to record for returned artifacts: retrieved, reference, applied (default "retrieved")
  -h, --help             help for lookup
      --json             JSON output
      --limit int        Maximum results to return (default 3)
      --no-cite          Skip citation recording
      --query string     Search query for relevance matching
      --session string   Session ID for citation tracking
```

---

### `ao mind`

Scan, normalize, link, and index .agents/ markdown into an Obsidian knowledge graph.

```
ao mind [command]
```

**Subcommands:**

#### `ao mind all`

Run full pipeline (normalize → link → index)

```
ao mind all [flags]
```

#### `ao mind graph`

Show graph statistics

```
ao mind graph [flags]
```

#### `ao mind index`

Rebuild the graph index

```
ao mind index [flags]
```

#### `ao mind link`

Insert wikilinks between related artifacts

```
ao mind link [flags]
```

#### `ao mind normalize`

Add/fix YAML frontmatter on .agents/ markdown

```
ao mind normalize [flags]
```

#### `ao mind scan`

Show what needs normalization

```
ao mind scan [flags]
```

---

### `ao mine`

Mine scans all reachable data sources for patterns and insights

```
ao mine [flags]
```

**Flags:**

```
      --emit-work-items     Append actionable mine findings to .agents/rpi/next-work.jsonl for evolve to pick up
  -h, --help                help for mine
      --output-dir string   Directory for mine output JSON (default ".agents/mine")
      --quiet               Suppress progress output
      --since string        How far back to look (e.g. 26h, 7d) (default "26h")
      --sources string      Comma-separated sources to mine (git, agents, code, events) (default "git,agents,code")
```

---

### `ao patterns`

Maintenance commands for the .agents/patterns/ directory.

```
ao patterns [command]
```

**Subcommands:**

#### `ao patterns repair-filenames`

Walk .agents/patterns/*.md, detect filenames whose hyphenated segments

```
ao patterns repair-filenames [flags]
```

**Flags:**

```
      --apply        Perform renames (default: dry-run, no disk writes)
      --dir string   Patterns directory to repair (default: <cwd>/.agents/patterns)
  -h, --help         help for repair-filenames
      --quiet        Suppress per-rename output
```

---

### `ao retrieval-bench`

Measure Precision@K and MRR against a curated corpus of learning artifacts.

```
ao retrieval-bench [flags]
```

**Flags:**

```
      --corpus string                    Path to benchmark corpus directory
      --global                           Include ~/.agents/learnings/ (cross-rig aggregated store, requires --live)
  -h, --help                             help for retrieval-bench
      --json                             JSON output
      --k int                            K for Precision@K (default 3)
      --live                             Benchmark against real .agents/learnings/ instead of synthetic corpus
      --search-backend string            Search backend for --search-eval (local-lexical, ao-auto, agentic-rg, wiki-link-expand, rerank-llamacpp) (default "local-lexical")
      --search-compare-backends string   Comma-separated search backends to compare for --search-eval
      --search-eval string               Path to an ao-search eval manifest with queries and ground_truth paths
      --search-root string               Repo root to search for --search-eval (defaults to current directory)
```

---

### `ao search`

Search workspace session history and repo-local AgentOps knowledge.

```
ao search <query> [flags]
```

**Flags:**

```
      --cass             Require upstream cass session-history search
      --cite string      Optional citation type to record for matching repo-local artifacts: retrieved, reference, applied
  -h, --help             help for search
      --limit int        Maximum results to return (default 10)
      --local            Force repo-local AgentOps search only
      --session string   Session ID for citation tracking (defaults to the active runtime session)
      --type string      Filter by type: session(s), learning(s), pattern(s), finding(s), research, compiled, vault-source(s), decision(s), knowledge
      --use-sc           Try Smart Connections semantic search first (requires Obsidian)
```

---

### `ao sessions`

Manage derived session pages under .agents/ao/sessions without touching source transcripts.

```
ao sessions [command]
```

**Subcommands:**

#### `ao sessions index`

Maintain derived session pages under .agents/ao/sessions.

```
ao sessions index [flags]
```

**Flags:**

```
  -h, --help                  help for index
      --prune-orphans         Delete derived session pages whose source_jsonl no longer exists
      --sessions-dir string   Directory containing derived session pages (default: .agents/ao/sessions)
```

#### `ao sessions spawn`

Read a session template, expand variables, run init steps, and create

```
ao sessions spawn <template-path> [flags]
```

**Flags:**

```
      --date string   Override date for template expansion (default: today, YYYY-MM-DD)
      --dry-run       Print expanded template and init steps without executing
  -h, --help          help for spawn
      --no-tmux       Run init steps but skip tmux session creation
```

---

### `ao trace`

Trace the provenance of an artifact back to its source transcript.

```
ao trace <artifact-path> [flags]
```

**Flags:**

```
      --graph   Show ASCII provenance graph
  -h, --help    help for trace
```

---

### `ao wiki`

ao wiki is the experimental unified surface for the wiki bounded context.

```
ao wiki [command]
```

**Subcommands:**

#### `ao wiki doctor`

Report on the wiki corpus directory and the persistent index.

```
ao wiki doctor [flags]
```

**Flags:**

```
      --base string   Corpus base directory (default: current directory)
  -h, --help          help for doctor
```

#### `ao wiki index`

Scan the .agents/ corpus and update the persistent JSONL document index.

```
ao wiki index [flags]
```

**Flags:**

```
      --base string   Corpus base directory (default: current directory)
  -h, --help          help for index
```

#### `ao wiki inject`

Assemble just-in-time .agents/ context.

```
ao wiki inject [flags]
```

#### `ao wiki lint`

Walk the wiki tree and write a dated lint report.

```
ao wiki lint [flags]
```

**Flags:**

```
  -h, --help           help for lint
      --vault string   Vault root (default: current directory)
```

#### `ao wiki promote`

Promote mature wiki pages into authored content.

```
ao wiki promote [flags]
```

**Flags:**

```
  -h, --help           help for promote
      --vault string   Vault root (default: current directory)
```

#### `ao wiki query`

Answer a pending wiki question into wiki/synthesis/.

```
ao wiki query [flags]
```

**Flags:**

```
  -h, --help           help for query
      --vault string   Vault root (default: current directory)
```

#### `ao wiki search`

Rank documents in the wiki index against a free-text query.

```
ao wiki search <query> [flags]
```

**Flags:**

```
      --base string   Corpus base directory (default: current directory)
  -h, --help          help for search
      --limit int     Maximum results to print (default 20)
      --reindex       Rebuild the index before searching
```

---

### `ao agent`

Emit a runtime-specific Agent definition (Managed Agents payload or

```
ao agent [command]
```

**Subcommands:**

#### `ao agent bundle`

Stitch the selected AgentOps skills + the ao tool surface into an

```
ao agent bundle [flags]
```

**Flags:**

```
  -h, --help             help for bundle
      --json             Emit machine-readable JSON (always JSON for now; reserved for parity)
      --out string       Write the bundle to this path instead of stdout
      --runtime string   Target runtime: managed | codex-ntm (required)
      --sandbox string   Sandbox placement: self-hosted | cloud
      --skills string    Comma-separated skill names (default: session-bootstrap,standards,validation,provenance)
```

---

### `ao agents`

Tooling for the .agents/ knowledge surface that backs the

```
ao agents [command]
```

**Subcommands:**

#### `ao agents doctor`

Combine ao agents inspect and ao agents lint into a single

```
ao agents doctor [flags]
```

**Flags:**

```
      --agents-dir string   Path to the .agents/ directory under inspection (default ".agents")
      --contract string     Path to the .agents/ write-surfaces contract doc (default "docs/contracts/agents-write-surfaces.md")
  -h, --help                help for doctor
      --json                Emit machine-readable JSON
      --script string       Path to the lint script (default "scripts/check-agents-write-surfaces.sh")
      --skills-dir string   Path to the skills/ directory used for skill-owned-subdir cross-check (default "skills")
      --strict              Exit non-zero on any orphan or undocumented surface
```

#### `ao agents inspect`

Read the .agents/ write-surface contract and emit a structured

```
ao agents inspect [flags]
```

**Flags:**

```
      --contract string   Path to the .agents/ write-surfaces contract doc (default "docs/contracts/agents-write-surfaces.md")
  -h, --help              help for inspect
      --json              Emit machine-readable JSON
```

#### `ao agents lint`

Wrap scripts/check-agents-write-surfaces.sh and surface its

```
ao agents lint [flags]
```

**Flags:**

```
  -h, --help            help for lint
      --json            Forward --json to the lint script
      --script string   Path to the lint script (default "scripts/check-agents-write-surfaces.sh")
```

---

### `ao extract`

Check for pending session extractions and output a prompt for Claude to process.

```
ao extract [flags]
```

**Flags:**

```
      --all               Process all pending entries
      --bead string       Bead ID to tag extracted learnings with
      --clear             Clear pending queue without processing
  -h, --help              help for extract
      --max-content int   Maximum characters of session content to include (default 3000)
```

---

### `ao help`

Help provides help for any command in the application.

```
ao help [command] [flags]
```

---

### `ao mcp`

Model Context Protocol surface for out-of-session Claude loops (Managed

```
ao mcp [command]
```

**Subcommands:**

#### `ao mcp serve`

Emit the curated MCP tool surface (--print-tools) consumable by

```
ao mcp serve [flags]
```

**Flags:**

```
  -h, --help          help for serve
      --json          Machine-readable JSON (always JSON for --print-tools; reserved for parity)
      --print-tools   Emit the curated tool surface as JSON and exit
```

---

### `ao next-work`

Commands that act on the carry-forward next-work queue that /post-mortem

```
ao next-work [command]
```

**Subcommands:**

#### `ao next-work materialize`

Read .agents/rpi/next-work.jsonl and create one durable bead per

```
ao next-work materialize [flags]
```

**Flags:**

```
      --dry-run                  Show what would be created without creating beads or mutating the queue
      --file string              Path to next-work.jsonl (default: <cwd>/.agents/rpi/next-work.jsonl)
  -h, --help                     help for materialize
      --json                     Emit a machine-readable JSON summary
      --materialized-by string   Actor recorded in provenance metadata (default "next-work-materialize")
      --source-epic string       Only materialize items whose batch source_epic equals this value
```

---

### `ao provenance`

Append-only write model for the SDLC provenance/intent graph

```
ao provenance [command]
```

**Subcommands:**

#### `ao provenance add`

Append one schema-valid, hash-chained provenance edge linking a source

```
ao provenance add <from-id> <to-id> [flags]
```

**Flags:**

```
      --evidence string     Optional evidence pointer (path, commit, CI run URL, event id)
      --from-type string    Source node type (decision|artifact|bead|...) (default "decision")
  -h, --help                help for add
      --json                Emit the sealed edge as JSON
      --relation string     Typed relation (required), e.g. decision_produces_artifact
      --to-type string      Target node type (decision|artifact|bead|...) (default "artifact")
      --trust-tier string   Trust tier (authored|inferred|mined) (default "authored")
      --ts string           Override the UTC RFC3339 timestamp (defaults to now)
```

#### `ao provenance export`

Read docs/provenance/ledger.jsonl, canonically sort its edges by

```
ao provenance export [flags]
```

**Flags:**

```
  -h, --help     help for export
      --json     Emit a single indented JSON array instead of JSONL
      --verify   Verify the re-chained export and print only a one-line summary
```

#### `ao provenance list`

Read the provenance edges recorded in docs/provenance/ledger.jsonl, in

```
ao provenance list [flags]
```

**Flags:**

```
      --from-id string    Filter to edges whose from_id matches
  -h, --help              help for list
      --json              Emit machine-readable JSON
      --relation string   Filter to edges with this relation
```

---

### `ao registry`

Query the unified registry

```
ao registry [command]
```

**Subcommands:**

#### `ao registry list`

List registry entries

```
ao registry list [flags]
```

**Flags:**

```
  -h, --help          help for list
      --type string   Filter by surface type (skills, hooks, stores, jobs, evals, cli, cadence)
```

---

### `ao scenario`

Create, list, and validate holdout scenarios stored in .agents/holdout/.

```
ao scenario [command]
```

**Subcommands:**

#### `ao scenario add`

Author a schema-compliant holdout scenario in .agents/holdout/.

```
ao scenario add <goal> [flags]
```

**Flags:**

```
      --expected-outcome string   Expected observable outcome (default: inferred from goal)
  -h, --help                      help for add
      --narrative string          Narrative description (default: inferred from goal)
      --source string             Scenario source (human, agent, prod-telemetry) (default "human")
      --status string             Scenario status (active, draft, retired) (default "draft")
      --threshold float           Satisfaction threshold in [0,1] (default 0.8)
```

#### `ao scenario init`

Initialize .agents/holdout/ directory for scenario storage

```
ao scenario init [flags]
```

#### `ao scenario list`

List holdout scenarios

```
ao scenario list [flags]
```

**Flags:**

```
  -h, --help            help for list
      --status string   Filter by status (active, draft, retired)
```

#### `ao scenario validate`

Validate holdout scenarios against schema

```
ao scenario validate [flags]
```

---

### `ao scope`

Declare which directories are in scope for the current work session.

```
ao scope [command]
```

**Flags:**

```
  -h, --help          help for scope
      --json          Emit JSON output
      --lock string   Override scope-lock path (defaults to $AO_SCOPE_LOCK or .agents/scope.lock)
```

**Subcommands:**

#### `ao scope freeze`

Freeze one or more directories (additive)

```
ao scope freeze <dir> [<dir>...] [flags]
```

#### `ao scope status`

Show current scope-lock state

```
ao scope status [flags]
```

#### `ao scope unfreeze`

Unfreeze one (or all if no arg) directories

```
ao scope unfreeze [<dir>...] [flags]
```

---

### `ao skills`

Tooling for the skills/ source-of-truth and its skills-codex/

```
ao skills [command]
```

**Subcommands:**

#### `ao skills check`

Walk skills/ and skills-codex/, validating each skill's YAML

```
ao skills check [flags]
```

**Flags:**

```
  -h, --help           help for check
      --json           Emit machine-readable JSON
      --skill string   Restrict the audit to a single skill name
      --strict         Exit non-zero on any finding (CI mode)
```

#### `ao skills consumers`

Print the skills whose consumes[] list includes <skill> — i.e. who

```
ao skills consumers <skill> [flags]
```

**Flags:**

```
  -h, --help   help for consumers
      --json   Emit machine-readable JSON
```

#### `ao skills find`

Score every skills/<name>/SKILL.md against a free-text intent and

```
ao skills find <intent> [flags]
```

**Flags:**

```
  -h, --help        help for find
      --json        Emit machine-readable JSON on stdout
      --limit int   Maximum number of results to return (default 5)
```

#### `ao skills graph`

Render the skill dependency graph (A --> B means A consumes B) from

```
ao skills graph [flags]
```

**Flags:**

```
      --format string   Graph output format (mermaid) (default "mermaid")
  -h, --help            help for graph
```

#### `ao skills list`

Filter the generated skill catalog by hexagonal role, produced or

```
ao skills list [flags]
```

**Flags:**

```
      --consumes string         Filter to skills that consume this port/sibling
  -h, --help                    help for list
      --json                    Emit machine-readable JSON
      --practice string         Filter to skills that apply this practice
      --produces string         Filter to skills that produce this port/artifact
      --role string             Filter by hexagonal_role (domain, driving-adapter, ...)
      --user-invocable string   Filter by user-invocability (true|false)
```

#### `ao skills producers`

Print the skills whose produces[] list includes <output> — i.e. who

```
ao skills producers <output> [flags]
```

**Flags:**

```
  -h, --help   help for producers
      --json   Emit machine-readable JSON
```

---