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

---

## Commands

### `ao demo`

Run an interactive demonstration of AgentOps capabilities.

```
ao demo [flags]
```

**Flags:**

```
      --concepts   Just explain core concepts
  -h, --help       help for demo
      --quick      2-minute quick overview
```

---

### `ao init`

Set up a repository for AgentOps: directories, gitignore, and optional hooks.

```
ao init [flags]
```

**Flags:**

```
      --full            With --hooks, explicitly request full coverage (legacy explicit flag)
  -h, --help            help for init
      --hooks           Also register hooks (full 12-event coverage by default; equivalent to ao hooks install --full)
      --minimal-hooks   With --hooks, install SessionStart + SessionEnd + Stop hooks (lightweight)
      --stealth         Use .git/info/exclude instead of .gitignore
```

---

### `ao quick-start`

Initialize AgentOps in your current project.

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

**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 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
```

---

### `ao doctor`

Run health checks on your AgentOps installation.

```
ao doctor [flags]
```

**Flags:**

```
  -h, --help   help for doctor
      --json   Output results as JSON
```

---

### `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 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
      --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 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 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 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]
```

**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)
  -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)
  -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 evolve`

Run the v2 autonomous improvement loop.

```
ao evolve [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 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)
      --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)
```

---

### `ao factory`

Software-factory operator surface for AgentOps.

```
ao factory [command]
```

**Subcommands:**

#### `ao factory start`

Start the software-factory operator lane for a concrete goal.

```
ao factory start [flags]
```

**Flags:**

```
      --goal string      Goal to brief and use as the startup query
  -h, --help             help for start
      --limit int        Maximum artifacts to surface per category during startup (default 3)
      --no-maintenance   Skip safe close-loop maintenance on start
```

---

### `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")
  -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
      --json          Output as JSON
      --timeout int   Check timeout in seconds (default 120)
```

**Subcommands:**

#### `ao goals measure`

Run goal checks and produce a snapshot

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

**Flags:**

```
      --directives    Output directives as JSON (skip gate checks)
      --goal string   Measure a single goal by ID
  -h, --help          help for measure
```

#### `ao goals validate`

Validate GOALS.yaml structure and wiring

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

#### `ao goals drift`

Compare snapshots for regressions

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

#### `ao goals export`

Export latest snapshot as JSON (for CI)

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

#### `ao goals history`

Show goal measurement history

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

**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 add`

Add a new goal

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

**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]
```

**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]
```

#### `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 prioritize`

Move a directive to a new position

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

##### `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 overnight`

Dream is AgentOps' private overnight operator mode.

```
ao overnight [command]
```

**Subcommands:**

#### `ao overnight curator`

Inspect and operate a local Tier 1 Dream curator such as Ollama/Gemma.

```
ao overnight curator [command]
```

##### `ao overnight curator compact`

Run the local curator pending-log compactor

```
ao overnight curator compact [flags]
```

**Flags:**

```
      --apply     Apply pending-log compaction
      --dry-run   Preview pending-log compaction without writing
  -h, --help      help for compact
```

##### `ao overnight curator diagnose`

Explain local curator setup problems

```
ao overnight curator diagnose [flags]
```

**Flags:**

```
  -h, --help   help for diagnose
      --json   Render curator diagnosis as JSON
```

##### `ao overnight curator enqueue`

Enqueue an allowlisted local curator job

```
ao overnight curator enqueue [flags]
```

**Flags:**

```
      --chunk-end int     End chunk index for ingest-claude-session jobs
      --chunk-start int   Start chunk index for ingest-claude-session jobs
  -h, --help              help for enqueue
      --kind string       Job kind to enqueue: ingest-claude-session, lint-wiki, or dream-seed
      --source string     Source path for ingest-claude-session jobs
```

##### `ao overnight curator event`

Write a bounded needs-review escalation event

```
ao overnight curator event [flags]
```

**Flags:**

```
      --budget int              Maximum downstream event budget (default 1)
      --desired-action string   Requested bounded action for Tier 2 review
  -h, --help                    help for event
      --note string             Optional operator note
      --severity string         Event severity: info, warn, high, or critical
      --source string           Event source, for example gemma or local-soc
      --target string           Escalation target (default "dream-council")
```

##### `ao overnight curator status`

Report local curator queue, worker, and model health

```
ao overnight curator status [flags]
```

**Flags:**

```
  -h, --help   help for status
      --json   Render curator status as JSON
```

#### `ao overnight report`

Read a Dream report from summary.json and render it as JSON, YAML, or

```
ao overnight report [flags]
```

**Flags:**

```
      --from string   Directory containing summary.json, or the summary.json file itself
  -h, --help          help for report
```

#### `ao overnight setup`

Inspect the current machine, detect available Dream runtimes and scheduler

```
ao overnight setup [flags]
```

**Flags:**

```
      --apply              Persist the detected Dream config and generate scheduler assistance artifacts
      --at string          Preferred local Dream run time in HH:MM (used for scheduler assistance)
  -h, --help               help for setup
      --keep-awake         Persist keep-awake on for Dream runs
      --no-keep-awake      Persist keep-awake off for Dream runs
      --runner strings     Dream runner to persist (repeatable: --runner codex --runner claude)
      --scheduler string   Scheduler mode to persist (auto, manual, launchd, cron, systemd, task-scheduler) (default "auto")
```

#### `ao overnight start`

Start a private overnight Dream run against the local repository.

```
ao overnight start [flags]
```

**Flags:**

```
      --checkpoint-max-mb int   Max total MB of checkpoint storage per run (default 512)
      --creative-lane           Enable the bounded wildcard lane when Dream Council is running
      --goal string             Optional goal to include in the morning report and briefing step
  -h, --help                    help for start
      --keep-awake              Force keep-awake assistance on for this run
      --max-iterations int      Cap iteration count (0 = budget-bounded only)
      --no-keep-awake           Disable keep-awake assistance for this run
      --output-dir string       Directory for overnight artifacts (defaults to dream.report_dir)
      --plateau-epsilon float   Plateau threshold: |delta| below this counts as plateau (default 0.01)
      --plateau-window int      Plateau window K (consecutive sub-epsilon deltas required to halt) (default 2)
      --queue string            Operator-pinned nightly priorities (markdown file)
      --run-timeout string      Maximum duration for the overnight run (defaults to dream.run_timeout)
      --runner strings          Dream runner to execute (repeatable: --runner codex --runner claude)
      --warn-only               First-N-runs mode: warn on plateau/regression, don't halt. Default true; flip to false once thresholds are calibrated. (default true)
```

#### `ao overnight warn-only`

Dream's warn-only ratchet protects the first 2-3 production runs

```
ao overnight warn-only [command]
```

##### `ao overnight warn-only reset`

Reset .agents/overnight/warn-only-budget.json to a fresh state.

```
ao overnight warn-only reset [flags]
```

**Flags:**

```
  -h, --help          help for reset
      --initial int   Initial rescue ceiling (defaults to 3)
      --json          Emit the reset result as JSON instead of human-readable text
```

---

### `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]
```

#### `ao ratchet next`

Show the next pending step in the RPI workflow.

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

**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]
```

**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]
```

**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 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:**

```
      --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                 Skip auto-merge (leave worktrees for manual review)
      --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
      --fast-path                         Force fast path (--quick for gates)
      --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")
      --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]
```

---

### `ao session`

Session lifecycle operations.

```
ao session [command]
```

**Subcommands:**

#### `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 completion`

Generate shell completion scripts for ao.

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

---

### `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 hooks`

The hooks command manages runtime hooks that automate the CASS knowledge flywheel.

```
ao hooks [command]
```

**Subcommands:**

#### `ao hooks init`

Generate hooks configuration for the CASS knowledge flywheel (Claude Code format).

```
ao hooks init [flags]
```

**Flags:**

```
      --format string   Output format: json, shell (default "json")
  -h, --help            help for init
```

#### `ao hooks install`

Install ao hooks to ~/.claude/settings.json.

```
ao hooks install [flags]
```

**Flags:**

```
      --dry-run             Show what would be installed without making changes
      --force               Overwrite existing ao hooks
      --full                Install all hook events from hooks.json with scripts copied to ~/.agentops/
  -h, --help                help for install
      --source-dir string   Path to agentops repo checkout (for --full script installation)
```

#### `ao hooks show`

Display the current hooks configuration from ~/.claude/settings.json (Claude Code runtime).

```
ao hooks show [flags]
```

#### `ao hooks test`

Test that all hook dependencies are available and working.

```
ao hooks test [flags]
```

**Flags:**

```
      --dry-run   Show test steps without running hooks
  -h, --help      help for test
```

---

### `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 plans`

Plans manages the plan manifest at .agents/plans/manifest.jsonl.

```
ao plans [command]
```

**Subcommands:**

#### `ao plans diff`

Diff compares the plan manifest against beads reality.

```
ao plans diff [flags]
```

#### `ao plans list`

List shows all plans in the manifest.

```
ao plans list [flags]
```

**Flags:**

```
  -h, --help             help for list
      --project string   Filter by project path
      --status string    Filter by status (active, completed, abandoned, superseded)
```

#### `ao plans register`

Register adds a plan to the manifest.jsonl for discovery.

```
ao plans register <plan-path> [flags]
```

**Flags:**

```
      --beads-id string   Beads issue/epic ID this plan implements
  -h, --help              help for register
      --name string       Human-readable plan name
      --project string    Project path this plan applies to
```

#### `ao plans search`

Search plans by name or project

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

#### `ao plans sync`

Sync pulls plan metadata from beads to prevent drift.

```
ao plans sync [flags]
```

#### `ao plans update`

Update a plan's status or metadata

```
ao plans update <plan-path> [flags]
```

**Flags:**

```
      --beads-id string   Update beads ID
  -h, --help              help for update
      --status string     New status for the plan
```

---

### `ao beads`

Commands that help maintain the bd issue tracker alongside the main

```
ao beads [command]
```

**Subcommands:**

#### `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 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:**

```
      --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
      --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
      --mine-only           Only mine new knowledge signal
      --output-dir string   Compiled wiki output directory (default ".agents/compiled")
      --quiet               Suppress human progress output
      --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 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 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
      --oscillation-sweep   Flag evolve goals alternating improved/fail >=3 consecutive cycles
      --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
      --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
      --llm-endpoint string   Ollama HTTP endpoint for --tier=1 (default: $AGENTOPS_LLM_ENDPOINT or http://localhost:11434)
      --model string          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 local-LLM summarization pipeline (requires --model, --llm-endpoint optional)
```

---

### `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)
      --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 session startup.

```
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)
```

---

### `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 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-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, decision(s), knowledge
      --use-sc           Try Smart Connections semantic search first (requires Obsidian)
```

---

### `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 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 scenario`

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

```
ao scenario [command]
```

**Subcommands:**

#### `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]
```

---