# Solo Developer Guide

Get immediate value from Aphoria on your personal or side projects.

## Why Aphoria for Solo Projects?

You don't need enterprise workflows. You need to know when your code contradicts RFCs or security best practices—before it becomes a CVE.

**What you get:**
- Catch `verify=False`, weak TLS, disabled auth—patterns you'd miss in code review
- No team coordination, no policy packs, no approval workflows
- Pre-commit hooks that stop insecure code before it ships

---

## Quick Start (2 Minutes)

### Step 1: Install (30 seconds)

```bash
cd /path/to/stemedb/applications/aphoria
cargo install --path .
```

Verify:
```bash
aphoria --version
```

**Expected output:**
```
aphoria 0.1.0
```

---

### Step 2: Initialize Your Project (30 seconds)

```bash
cd /path/to/your-project
aphoria init
```

This creates `.aphoria/` and loads the authoritative corpus (RFCs, OWASP) into your local database.

---

### Step 3: Run Your First Scan (30 seconds)

```bash
aphoria scan
```

**Expected output (if violations found):**
```
┌──────────────────────┬──────┬─────────┬──────────────────────────────────────────┐
│ File                 │ Line │ Verdict │ Explanation                              │
├──────────────────────┼──────┼─────────┼──────────────────────────────────────────┤
│ api/client.py        │ 42   │ BLOCK   │ TLS cert verification disabled           │
│                      │      │         │ (RFC 5246: MUST verify, confidence: 0.92)│
├──────────────────────┼──────┼─────────┼──────────────────────────────────────────┤
│ config/settings.py   │ 18   │ FLAG    │ DEBUG=True in production config          │
│                      │      │         │ (OWASP: SHOULD disable, confidence: 0.68)│
└──────────────────────┴──────┴─────────┴──────────────────────────────────────────┘

Summary: 1 BLOCK, 1 FLAG, 0 PASS
Scan completed in 0.24s
```

**Expected output (if clean):**
```
✓ No violations found
```

---

### Step 4: Understand the Results

#### Verdicts

| Verdict | Meaning | Confidence Threshold |
|---------|---------|---------------------|
| **BLOCK** | Critical violation - production risk | ≥ 0.7 |
| **FLAG** | Warning - best practice violation | ≥ 0.5 |
| **PASS** | No conflict with authoritative sources | < 0.5 |

---

## Pre-Commit Hook

Add to your `.pre-commit-config.yaml`:

```yaml
repos:
  - repo: local
    hooks:
      - id: aphoria
        name: Aphoria truth check
        entry: aphoria scan --staged --exit-code
        language: system
        pass_filenames: false
```

Now insecure code is blocked before it reaches your repo.

---

## What Aphoria Catches

| Category | Examples |
|----------|----------|
| **TLS/SSL** | Disabled cert verification, weak protocols, insecure ciphers |
| **Authentication** | Missing token validation, disabled auth checks |
| **Configuration** | Debug mode in production, exposed secrets, unsafe defaults |
| **Framework-Specific** | Django DEBUG=True, Flask CSRF disabled, Express without helmet |

---

## Common Workflows

### Daily Development

```bash
# Quick check (fast, no persistence)
aphoria scan
```

### Before Commits

```bash
# Check only staged files
aphoria scan --staged --exit-code
```

### Before Releases

```bash
# Full scan with report
aphoria scan --format markdown > SECURITY_AUDIT.md
```

---

## Handling Conflicts

### Option 1: Fix the Code

The best response. If Aphoria says `verify=False` is insecure, enable verification.

```python
# Before
response = requests.get(url, verify=False)

# After
response = requests.get(url, verify=True)
```

### Option 2: Acknowledge with Reason

Sometimes insecure patterns are intentional (dev environments, testing). Acknowledge them:

```bash
aphoria ack "code://python/requests/tls/cert_verification" \
  --reason "Local dev with self-signed certs, not used in production"
```

The acknowledgment is tracked. Re-scan and it becomes ACK (pass) instead of BLOCK.

### Option 3: Bless a Local Standard

For project-specific decisions that differ from RFCs:

```bash
aphoria bless "code://local/tls/min_version" \
  --predicate version --value "1.3" \
  --reason "This project requires TLS 1.3 minimum"
```

---

## Output Formats

```bash
# Human-readable (default)
aphoria scan --format table

# JSON for scripting
aphoria scan --format json

# Markdown for documentation
aphoria scan --format markdown > SECURITY.md

# SARIF for tool integration
aphoria scan --format sarif > results.sarif
```

---

## Tips for Solo Projects

### Keep It Simple

Don't bother with:
- Trust Packs (enterprise feature)
- Governance workflows (multi-team feature)
- Policy federation (organizational feature)

Just scan, fix, and occasionally acknowledge.

### Use Ephemeral Mode

Default scans are ephemeral—fast with no persistence. That's what you want for quick checks.

Only use `--persist` if you need:
- Baseline comparison (`aphoria diff`)
- Historical tracking

```bash
# Normal (fast)
aphoria scan

# With history (slower)
aphoria scan --persist
```

### Check Before Deploys

Add to your deploy script:

```bash
#!/bin/bash
set -e

# Block deploy on security issues
aphoria scan --exit-code

# Continue with deploy
./deploy.sh
```

---

## Upgrading Your Corpus

The authoritative corpus (RFCs, OWASP) updates periodically:

```bash
# Rebuild corpus with latest sources
aphoria corpus build

# List available sources
aphoria corpus list
```

---

## Troubleshooting

### "Corpus database not found"

```bash
# Initialize project first
aphoria init

# Or specify corpus DB location
export STEMEDB_CORPUS_DB_DIR=/path/to/corpus-db
```

### "No violations found" (but you expected some)

```bash
# Enable debug logging to see what extractors are doing
RUST_LOG=aphoria=debug aphoria scan

# Check which extractors ran
aphoria scan --show-observations
```

### "Scan is slow"

Ephemeral mode (default) should be fast (< 0.3s). If slow:

```bash
# Check file count
find . -name "*.rs" -o -name "*.py" | wc -l

# Exclude large directories
# Edit .aphoria/config.toml:
[scan]
exclude = ["target/", "node_modules/", "venv/"]
```

---

## FAQ

**Q: How is this different from a linter?**

Linters check syntax and style. Aphoria checks whether your *decisions* contradict *authoritative standards*. ESLint won't tell you that `verify=False` contradicts RFC 5246.

**Q: How is this different from SAST?**

SAST finds vulnerability patterns (SQL injection, XSS). Aphoria finds contradictions with specific standards. SAST finds `eval(user_input)`; Aphoria finds "you said TLS 1.1, NIST says TLS 1.2 minimum."

**Q: Does it require an LLM?**

No. Core scanning uses pattern matching. LLM extraction is optional and only for complex patterns. Most projects work without it.

**Q: What languages are supported?**

Aphoria extracts from:
- Configuration files (YAML, TOML, JSON)
- Python, JavaScript/TypeScript
- Rust, Go (partial)

See `aphoria extractors list` for current coverage.

---

## Next Steps

### Option A: Add Pre-Commit Hook (Recommended)

Block insecure code before it reaches your repo - see [Pre-Commit Hook](#pre-commit-hook) section above.

### Option B: Learn by Example

Follow the complete [Database Connection Pool Example](../../dogfood/dbpool/) to see:
- How to extract claims from technical documentation (HikariCP, PostgreSQL)
- How Aphoria catches violations (7-8 real examples)
- How to fix violations incrementally
- How to validate your environment is working

**Time:** 20 minutes to read, optional 5-day hands-on exercise

### Option C: Dive Deeper

- [The First Scan](./the-first-scan.md) - Detailed walkthrough
- [Pre-Flight Checks](./pre-flight-checks.md) - CI integration
- [CLI Reference](../reference/cli-reference.md) - All commands and options
- [Comparison Modes](../reference/comparison-modes.md) - How conflicts are evaluated