# Advanced Operations — References, Events, Export, Validation, Admin

## Quick Capture with `idea`

Shortcut to create a backlog IDEA issue without specifying type/priority:

```bash
ao idea "Support webhooks for event notifications"
ao idea "Refactor query parser" --epic "Performance" --body "Details about the idea"
```

Equivalent to `ao add TITLE --type idea --priority backlog`.

## Lessons Learned

Capture and retrieve per-issue lessons for agent retrospectives:

```bash
# Add a lesson learned
ao lesson add FEAT-0042 "Review caught: missing null check on optional field"

# List lessons for an issue
ao lesson ls FEAT-0042

# Filter and limit
ao lesson ls FEAT-0042 --query "review" --limit 5
```

## Event Log Compaction

Analyze and compact the event log to reduce size:

```bash
# Analyze compaction candidates (dry run)
ao compact analyze

# Apply compaction (collapses events into snapshots)
ao --yes compact apply
```

## Reference Documents

Reference docs attach detailed specs or plans to issues.

```bash
# Create reference doc from template and attach
ao --yes ref init FEAT-0042@abc123

# Attach a custom reference doc path
ao --yes ref attach FEAT-0042@abc123 --path docs/spec.md

# Open reference doc in $EDITOR
ao ref open FEAT-0042@abc123

# Check reference doc status
ao ref status FEAT-0042@abc123
```

Reference docs are stored in `.agent/ops/issues/references/`.

## Raw Event Operations

```bash
# Append a raw event from stdin
echo '{"issue_id":"FEAT-0042","op":"set","payload":{"notes":"raw"}}' | ao --yes --in - event append
```

Use sparingly — prefer high-level commands (`add`, `set`, `close`).

## Export

```bash
# Export all active issues as single JSON file
ao export json --out issues.json

# Export as JSONL
ao export jsonl --out issues.jsonl
```

## Import and Merge

```bash
# Import events from external file into events.jsonl
ao --yes import external-events.jsonl

# Merge two events.jsonl files (union + dedup by event_id)
ao merge other-events.jsonl
```

## Validation

```bash
# Run configured validation commands (tests, lint, etc.)
ao validate
```

Validation commands are configured in the project constitution or `pyproject.toml`.

## Completion Gate

```bash
# Check completion gate: issue done + no blockers + validation passes
ao gate FEAT-0042@abc123
```

The gate verifies:
1. Issue status is `done`
2. No open dependency blockers
3. Configured validation commands pass

## Label Suggestion

```bash
# Suggest labels for file paths using glob-to-label config
ao suggest-labels src/ao/web/app.py src/ao/models.py
```

## Onboarding

```bash
# Generate AOI_GUIDE.md for agent onboarding
ao onboard
```

## Installation and Updates

```bash
# Install AO asset folders
ao install

# Update AO assets (never mutates .agent files)
ao update

# Duplicate a skill across engines
ao duplicate ao-baseline --engine claude --engine opencode
```

## Git Hooks

```bash
# Install AO git hooks (post-merge, post-checkout, pre-push)
ao hooks install
ao hooks install --force   # overwrite existing non-AO hooks

# Check hook status
ao hooks status

# Remove AO-installed hooks
ao hooks uninstall

# Install hook config for an AI agent engine
ao hooks agent-install --engine copilot

# Run a hook rule (JSON stdin → decision stdout)
ao hooks run --engine claude --event pre-push

# Test a hook rule with sample payload
ao hooks test --engine claude --event pre-push --payload test.json

# Generate iteration prompt for an agent engine
ao hooks loop-prompt --engine opencode --output prompt.md

# Run iteration loop until no ready issues remain
ao hooks loop-run --engine opencode --max 5
ao hooks loop-run --engine copilot --dry-run
```

## Admin and Recovery

```bash
ao admin --help    # Admin recovery and migration commands
```

## Web UI

```bash
# Start Kanban web UI (localhost:8000)
ao web
```

The web UI provides:
- Drag-and-drop Kanban board by status or priority
- Real-time WebSocket updates
- REST API at `/api/`

## Priming (Machine-Readable Summary)

```bash
# Output machine-readable AO command/schema summary
ao prime
```

Useful for bootstrapping agent context with full CLI capabilities.
