stemedb/applications/aphoria-dashboard/DOCUMENTATION_INDEX.md

Aphoria Documentation Index

Quick Links

Getting Started

• Main README: applications/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

Getting Started Guides

1. The First Scan - First-time user walkthrough
2. Solo Developer Guide - For individual developers
3. Enterprise Quick Start - 5-minute enterprise setup
4. Enterprise Pilot Guide - Full pilot planning

Core Workflows

• Federating Truth - Trust Pack creation and distribution
• Multi-Team Policy Governance - Cross-team policies
• Policy Audit Trails - Compliance and auditing
• Authoritative State Per Project - Project-specific policies
• Pre-Flight Checks - Pre-commit and CI

Advanced Topics

• Golden Path Loop - Continuous policy improvement
• AAA Game Development - Unreal Engine patterns

Reference Documentation

• CLI Reference - Complete command documentation
• Comparison Modes - Claim comparison modes explained

Architecture Documentation

• Architecture Index - System design and internals

UAT Reports

• UAT Index - Validation test results
• Policy Source Tracking UAT - Trust Pack validation

Vision & Strategy

• Vision & Gaps - Product vision and roadmap gaps

---

Dashboard-Specific Documentation

Setup & Configuration

• Project Path Implementation - localStorage persistence setup
• Quick Reference - Developer quick reference
• Bug Fixes - Hydration and type error fixes
• Corpus Improvements - 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:

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

To contribute:

aphoria scan --persist --sync

---

Common Workflows

1. First-Time Setup

# Install
cargo install --path applications/aphoria

# Initialize corpus
aphoria init

# Run first scan
aphoria scan .

2. Daily Development

# Quick ephemeral scan
aphoria scan .

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

3. CI/CD Integration

# CI mode (fails build on BLOCK)
aphoria scan --exit-code --format json

4. Claims Authoring

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

# Verify claims against code
aphoria verify run

# Coverage analysis
aphoria verify coverage

# Generate documentation
aphoria docs generate

6. Community Contribution

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

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

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

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

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

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

Documentation

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

Corpus Management

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

Pattern Learning

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 for SSR safety patterns

---

Additional Resources

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

---

Last Updated: 2026-02-08