stemedb/applications/aphoria/dogfood/dbpool/docs/flywheel-setup.md

Aphoria Flywheel Setup

What Is the Flywheel?

The "Aphoria flywheel" is the self-improving cycle:

1. Scan code → Observations extracted
2. Observations aggregated across projects
3. Patterns with high adoption → Auto-promote to corpus
4. Better corpus → Better scans → More observations → Loop

For dogfooding: You want to see how pattern learning works across multiple scans.

---

Configuration

File: .aphoria/config.toml

Basic Flywheel (Required)

[episteme]
# CRITICAL: Use "persistent" mode (not "ephemeral")
# Ephemeral is fast (~0.25s) but doesn't save observations
mode = "persistent"  # Required for pattern aggregation

[corpus]
# Enable community corpus (patterns learned from scans)
use_community = true  # Default: true

# CRITICAL: Enable pattern aggregation
aggregation_enabled = true  # Required for flywheel

# Include authoritative sources
include_rfc = true     # RFC normative statements
include_owasp = true   # OWASP cheat sheets
include_vendor = true  # Vendor docs (your 27 claims)

# Cache directory for downloaded sources
cache_dir = "/home/jml/.aphoria/cache"

Optional Features

[extractors.inline_markers]
# Enable @aphoria:claim comments
enabled = true
sync_to_pending = true

[community]
# Share patterns with community (opt-in)
enabled = false  # Set true to contribute anonymously
anonymize = true

[llm]
# LLM semantic claim detection
enabled = false  # Optional: Costs tokens
model = "gemini-3-flash-preview"

[learning]
# Pattern learning from LLM-discovered patterns
enabled = false  # Optional: Autonomous pattern discovery

[autonomous]
# Auto-promote high-confidence patterns
enabled = false  # Optional: Requires shadow mode

[shadow]
# Shadow mode testing for auto-promoted extractors
enabled = false  # Optional: Validates safety

---

Verification

After enabling flywheel:

# 1. Run scan in persistent mode
aphoria scan --persist

# 2. Check observations were saved
ls -la ~/.aphoria/corpus-db/

# 3. Run scan with sync (contributes patterns)
aphoria scan --persist --sync

# 4. Query community patterns
curl 'http://localhost:18180/v1/aphoria/corpus?sources[]=community' | jq '.items | length'

Expected behavior:

• First scan: Observations extracted and stored locally
• Subsequent scans: Patterns with high adoption contribute to community corpus
• Over time: More patterns → Better coverage → Improved scanning

---

For Dogfooding

Day 3 Configuration:

Before running your first scan, update .aphoria/config.toml:

[episteme]
mode = "persistent"  # Switch from ephemeral

[corpus]
aggregation_enabled = true  # Enable learning

Then run:

aphoria scan --persist --sync

This will:

• Save observations to local database
• Contribute patterns to community corpus (if enabled)
• Show how patterns aggregate over multiple scans

---

Flywheel Modes Comparison

Mode	Speed	Persistence	Learning	Use Case
Ephemeral	~0.25s	No	No	Quick scans, CI checks
Persistent	~0.5s	Yes	Yes	Development, pattern learning
Persistent + Sync	~0.8s	Yes	Yes	Contributing to community

For dogfooding: Use persistent mode to demonstrate pattern learning.

---

Troubleshooting

Observations not persisting

# Check mode in config
grep "mode" .aphoria/config.toml
# Should show: mode = "persistent"

# Verify corpus DB exists
ls -la ~/.aphoria/corpus-db/
# Should show fjall/ directory

Aggregation not working

# Check aggregation setting
grep "aggregation_enabled" .aphoria/config.toml
# Should show: aggregation_enabled = true

# Verify patterns are being extracted
aphoria scan --format json | jq '.observations | length'
# Should show non-zero count

Community patterns empty

# Query community corpus
curl 'http://localhost:18180/v1/aphoria/corpus?sources[]=community' | jq .

# If empty, run multiple scans to build patterns
aphoria scan --persist --sync
# Repeat 2-3 times to accumulate patterns

---

Next Steps

After configuring the flywheel:

1. Day 3: Run initial scan with persistent mode
2. Day 4: Fix violations and re-scan (patterns accumulate)
3. Day 5: Document pattern learning outcomes in success story

See CHECKLIST.md for Day 3 scanning workflow.