# Aphoria Documentation Index

## Quick Links

### Getting Started
- **Main README**: [`applications/aphoria/README.md`](../../aphoria/README.md)
  - Quick start guide
  - Installation instructions
  - Basic scan workflows
  - Output formats
  - Pre-commit integration

### User Guides
- **Guides Index**: [`applications/aphoria/docs/guides/README.md`](../../aphoria/docs/guides/README.md)

#### Getting Started Guides
1. **[The First Scan](../../aphoria/docs/guides/the-first-scan.md)** - First-time user walkthrough
2. **[Solo Developer Guide](../../aphoria/docs/guides/solo-developer-guide.md)** - For individual developers
3. **[Enterprise Quick Start](../../aphoria/docs/guides/enterprise-quick-start.md)** - 5-minute enterprise setup
4. **[Enterprise Pilot Guide](../../aphoria/docs/guides/enterprise-pilot-guide.md)** - Full pilot planning

#### Core Workflows
- **[Federating Truth](../../aphoria/docs/guides/federating-truth.md)** - Trust Pack creation and distribution
- **[Multi-Team Policy Governance](../../aphoria/docs/guides/multi-team-policy-governance.md)** - Cross-team policies
- **[Policy Audit Trails](../../aphoria/docs/guides/policy-audit-trails.md)** - Compliance and auditing
- **[Authoritative State Per Project](../../aphoria/docs/guides/authoritative-state-per-project.md)** - Project-specific policies
- **[Pre-Flight Checks](../../aphoria/docs/guides/pre-flight-checks.md)** - Pre-commit and CI

#### Advanced Topics
- **[Golden Path Loop](../../aphoria/docs/guides/golden-path-loop.md)** - Continuous policy improvement
- **[AAA Game Development](../../aphoria/docs/guides/aaa-game-development.md)** - Unreal Engine patterns

### Reference Documentation
- **[CLI Reference](../../aphoria/docs/cli-reference.md)** - Complete command documentation
- **[Comparison Modes](../../aphoria/docs/comparison-modes.md)** - Claim comparison modes explained

### Architecture Documentation
- **[Architecture Index](../../aphoria/docs/architecture/README.md)** - System design and internals

### UAT Reports
- **[UAT Index](../../aphoria/uat/README.md)** - Validation test results
- **[Policy Source Tracking UAT](../../aphoria/uat/2026-02-04-uat-real-world-policy-source.md)** - Trust Pack validation

### Vision & Strategy
- **[Vision & Gaps](../../aphoria/docs/vision-gaps.md)** - Product vision and roadmap gaps

---

## Dashboard-Specific Documentation

### Setup & Configuration
- **[Project Path Implementation](./PROJECT_PATH_IMPLEMENTATION.md)** - localStorage persistence setup
- **[Quick Reference](./QUICK_REFERENCE.md)** - Developer quick reference
- **[Bug Fixes](./BUGFIXES.md)** - Hydration and type error fixes
- **[Corpus Improvements](./CORPUS_IMPROVEMENTS.md)** - Form refactoring and UX improvements

### API Documentation
- **Client**: `src/lib/api/client.ts` - StemeDB API client
- **Types**: `src/lib/api/types.ts` - TypeScript type definitions

### Component Documentation
- **Claims Card**: `src/components/claims/claim-card.tsx` - Rich claim display
- **Corpus Panel**: `src/components/corpus/corpus-panel.tsx` - Community patterns
- **Scans Panel**: `src/components/scans/scans-panel.tsx` - Scan management

---

## Key Concepts

### What is Aphoria?
A code-level truth linter that validates your code against authoritative technical standards (RFCs, OWASP, vendor documentation). It checks **intent against authority**, not just syntax.

### Observations vs Claims
- **Observations**: Automated pattern matches (e.g., `imports/tokio: true`)
- **Claims**: Human-authored rules with provenance, invariants, and consequences

### Corpus Types
1. **Authoritative Corpus**: Built-in standards (RFCs, OWASP, CWE)
2. **Community Corpus**: Aggregated patterns from opt-in users
3. **Project Claims**: Local `.aphoria/claims.toml` file

### Scan Modes
- **Ephemeral** (default): Fast, in-memory, no persistence (~0.25s)
- **Persistent** (`--persist`): Stores in Episteme, enables diff/baseline
- **Sync** (`--persist --sync`): Also pushes to community corpus

### Community Sharing
Opt-in feature that anonymizes observations and contributes to community patterns:

```toml
[community]
enabled = true          # Must opt-in (default: false)
anonymize = true        # Hash project identifiers
min_confidence = 0.7    # Quality threshold
```

To contribute:
```bash
aphoria scan --persist --sync
```

---

## Common Workflows

### 1. First-Time Setup
```bash
# Install
cargo install --path applications/aphoria

# Initialize corpus
aphoria init

# Run first scan
aphoria scan .
```

### 2. Daily Development
```bash
# Quick ephemeral scan
aphoria scan .

# Pre-commit (staged files only)
aphoria scan --staged --exit-code
```

### 3. CI/CD Integration
```bash
# CI mode (fails build on BLOCK)
aphoria scan --exit-code --format json
```

### 4. Claims Authoring
```bash
# List existing claims
aphoria claims list

# Create new claim
aphoria claims create \
  --id "myapp-tls-001" \
  --concept-path "myapp/api/tls/min_version" \
  --predicate "min_version" \
  --value "TLSv1.3" \
  --comparison equals \
  --provenance "Security policy 2024-Q1" \
  --invariant "API MUST use TLS 1.3 or higher" \
  --consequence "Vulnerable to downgrade attacks" \
  --tier expert \
  --category security
```

### 5. Verification (Audit)
```bash
# Verify claims against code
aphoria verify run

# Coverage analysis
aphoria verify coverage

# Generate documentation
aphoria docs generate
```

### 6. Community Contribution
```bash
# Preview what would be shared
aphoria scan --community-preview

# Actually share (with community.enabled = true)
aphoria scan --persist --sync
```

---

## Dashboard Features

### Scans Panel (`/scans`)
- Run new scans
- View scan history
- Drill into findings
- Filter by verdict (PASS/CONFLICT/MISSING)

### Claims Panel (`/claims`)
- List authored claims
- View claim details (invariant, consequence, provenance)
- Run verification
- View coverage metrics

### Corpus Panel (`/corpus`)
- Browse community patterns
- Filter by subject prefix
- See project counts
- Identify consensus patterns

---

## Configuration Files

### Project Config (`.aphoria/config.toml`)
```toml
[project]
name = "myapp"

[community]
enabled = false  # Opt-in for corpus contribution

[thresholds]
flag = 0.5
block = 0.7

[extractors]
# Enable/disable specific extractors
```

### Claims File (`.aphoria/claims.toml`)
Human-authored claims with full provenance:
```toml
[[claim]]
id = "myapp-rule-001"
concept_path = "myapp/module/property"
predicate = "key"
value = "expected_value"
comparison = "equals"
provenance = "Where this rule came from"
invariant = "What MUST stay true"
consequence = "What breaks if violated"
authority_tier = "expert"
category = "security"
status = "active"
```

---

## CLI Command Reference

### Scanning
```bash
aphoria scan [PATH]                  # Quick ephemeral scan
aphoria scan --persist               # Persistent mode
aphoria scan --persist --sync        # + community push
aphoria scan --staged                # Pre-commit (staged files)
aphoria scan --exit-code             # CI mode
aphoria scan --format json           # JSON output
aphoria scan --format sarif          # GitHub Security tab
aphoria scan --community-preview     # Dry run (no data sent)
```

### Claims Management
```bash
aphoria claims list                  # List all claims
aphoria claims create                # Author new claim
aphoria claims explain <ID>          # Explain a claim
aphoria claims update <ID>           # Update existing claim
aphoria claims supersede <ID>        # Supersede with new claim
aphoria claims deprecate <ID>        # Mark as deprecated
```

### Verification
```bash
aphoria verify run                   # Verify all claims
aphoria verify map                   # Show extractor→claim mapping
aphoria verify coverage              # Coverage analysis
```

### Documentation
```bash
aphoria docs generate                # Generate docs from claims
aphoria explain <CONCEPT>            # Explain concept
```

### Corpus Management
```bash
aphoria corpus build                 # Build authoritative corpus
aphoria corpus list                  # List corpus sources
aphoria corpus export-pack           # Export as Trust Pack
```

### Pattern Learning
```bash
aphoria patterns sync                # Sync learned patterns
aphoria patterns status              # Show sync status
aphoria patterns pull-community      # Pull community extractors
aphoria patterns show                # Show learned patterns
```

---

## Troubleshooting

### Empty Corpus Panel
**Problem**: `/corpus` page shows "0 patterns"

**Solution**: Community corpus requires:
1. Enable `community.enabled = true` in config
2. Run `aphoria scan --persist --sync`
3. Wait for patterns to aggregate

### Claims Not Verifying
**Problem**: Verification shows "MISSING" for valid code patterns

**Solution**: Check:
1. Concept path matches extractor output
2. Comparison mode is correct (equals/present/absent/not_equals)
3. Value matches exactly (including type)
4. Extractor declares the predicate in `verifiable_predicates()`

### Hydration Errors
**Problem**: React hydration mismatch in dashboard

**Solution**: See [`BUGFIXES.md`](./BUGFIXES.md) for SSR safety patterns

---

## Additional Resources

- **Episteme (StemeDB)**: [`../../README.md`](../../README.md) - Knowledge graph database
- **CLAUDE.md**: [`../../CLAUDE.md`](../../CLAUDE.md) - Project context for AI assistants
- **Roadmap**: [`../../roadmap.md`](../../roadmap.md) - Current development status

---

**Last Updated**: 2026-02-08