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

```toml
[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

```toml
[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:

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

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

[corpus]
aggregation_enabled = true  # Enable learning
```

Then run:

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

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

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

```bash
# 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.