Skip to main content

​
Ariel Operations Runbook

​
Baseline Management

​
Create and Freeze a Baseline

# Via MCP (Claude)
ariel_baseline_create BL-ARCH-001 --name "Architecture v1.0" --author "team"
ariel_baseline_add_ci BL-ARCH-001 --type doc --ref docs/architecture/overview.md
ariel_baseline_freeze BL-ARCH-001

# Via REST API
curl -X POST http://localhost:8000/api/ariel/baselines \
  -H "Content-Type: application/json" \
  -d '{"baseline_id": "BL-ARCH-001", "name": "Architecture v1.0", "author": "team"}'

​
Verify Baseline Integrity

ariel_baseline_verify BL-ARCH-001
Returns pass, drift_detected, or missing_detected per CI.

​
Compare Baselines

ariel_baseline_diff BL-ARCH-001 BL-ARCH-002

​
Sync Troubleshooting

​
Sync Not Running

  1. Check SyncEngine initialization in server.py
  2. Verify database connectivity: Database.health_check()
  3. Check ariel_sync_history for failed sync records: 
    SELECT * FROM ariel_sync_history
WHERE status = 'failed'
ORDER BY created_at DESC
LIMIT 10;

​
Sync Conflicts

Default strategy: BASELINE_PRIORITY. Change via ConflictStrategy enum. Options:
  • BASELINE_PRIORITY — Ariel data wins
  • TRACEO_PRIORITY — Traceo data wins
  • LAST_WRITE_WINS — Most recent timestamp wins
  • MANUAL — Returns both sides for manual resolution

​
Cross-Workspace Isolation

All baseline operations are workspace-scoped via RLS. Verify: 
-- Check RLS is enabled
SELECT tablename, rowsecurity FROM pg_tables
WHERE tablename LIKE 'ariel_%';

-- Verify policies
SELECT * FROM pg_policies WHERE tablename LIKE 'ariel_%';

​
Baseline Recovery

​
Restore from YAML

If PostgreSQL data is lost but YAML files exist:
  1. Set TRACEO_STORAGE_BACKEND=file
  2. Point ARIEL_BASELINES_PATH to the baselines directory
  3. Use ariel_baseline_list to verify recovery

​
Restore from PostgreSQL

If YAML files are lost:
  1. Set TRACEO_STORAGE_BACKEND=postgres
  2. Use ariel_baseline_list to verify data
  3. Export to YAML if needed via the API

​
Database Migration

Apply migration: 
psql -f migrations/005_ariel_baselines.sql
Verify tables: 
SELECT table_name FROM information_schema.tables
WHERE table_name LIKE 'ariel_%';

​
Building Documentation

# Build knowledge docs
./scripts/build-docs.sh

# Or via MCP tool
ariel_build --repo-root knowledge/

# Serve locally
cd knowledge && mkdocs serve