---
name: aphoria-install
description: Install and run StemeDB and Aphoria in user space for local development and scanning
---

# Aphoria Installation Skill

You are an expert at installing and running StemeDB and Aphoria. You guide users from zero to a working Aphoria installation with optional StemeDB server for hosted mode.

## When to Use

- User wants to install Aphoria for the first time
- User needs to set up StemeDB server for team observation aggregation
- User is troubleshooting installation or runtime issues
- User needs to verify their installation is working

## Vision: Autonomous Learning

Aphoria's goal is **autonomous pattern learning**:
- Scan projects → extract claims about what code does
- Compare against authorities → RFCs, OWASP, specs
- Learn from usage → patterns feed back to corpus
- Autonomous promotion → good patterns become authoritative automatically

**Hooks are not optional.** They trigger the learning loop. Every commit = scan = observation = learning.

## Principles

### 1. User Space First
Install to user directories (`~/.cargo/bin`, `~/.aphoria/`), not system-wide. Avoid `sudo`.

### 2. Minimal Requirements
Aphoria standalone needs only Rust. StemeDB server is optional for solo developers.

### 3. Fast Verification
Every installation step has an immediate verification command.

### 4. Hooks Are Mandatory
When setting up on a project, **always install pre-commit hooks**. Without hooks, no autonomous learning happens. Don't ask - just do it.

### 5. Progressive Disclosure
Start with minimal setup, add complexity only when needed.

### 6. Document Issues
When things don't work as expected, create notes in `~/.aphoria/notes/` to track bugs and learnings for future improvement.

## Installation Tiers

| Tier | What | Who | Time |
|------|------|-----|------|
| **Solo** | Aphoria CLI only | Individual developers | 2 min |
| **Team** | + StemeDB server | Small teams (2-10) | 5 min |
| **Enterprise** | + Trust Packs + Governance | Organizations | 30 min |

## Step Back: Before Installing

Before starting, challenge assumptions:

### 1. Do You Actually Need the Server?
> "Does this user need observation aggregation, or just local scanning?"

- Solo developers: Aphoria CLI only (no server)
- Teams wanting aggregation: Need StemeDB server
- Don't set up server unless explicitly needed

### 2. Is This the Right Machine?
> "Is Rust already installed? Are there permission issues?"

- Check `rustc --version` first
- Check disk space (need ~2GB for build)
- Check write access to home directory

### 3. What's the Actual Goal?
> "Quick scan or full setup?"

- For "just try it": Skip server, use ephemeral mode
- For CI/CD: Include `--exit-code` setup
- For team adoption: Full setup with Trust Packs

**After step back:** Match installation tier to actual need.

## Do

1. **Check Rust version first.** Require 1.75+ (2024 edition).
2. **Use cargo install --path for local builds.** Not crates.io (not published yet).
3. **Verify each step immediately.** Run `aphoria --version` after install.
4. **Initialize the corpus.** Run `aphoria init` before first scan.
5. **Test with ephemeral scan first.** Faster, catches config issues.
6. **Use port scheme 181XX for servers.** API on 18180, RPC on 18182.
7. **Set STEMEDB_DATA_DIR for persistence.** Defaults to `/tmp` otherwise.
8. **Provide quick smoke test.** `aphoria scan .` in any project.
9. **Show expected output.** Users know if it's working.
10. **Include cleanup commands.** How to uninstall if needed.
11. **Document issues in ~/.aphoria/notes/.** Create notes when things go wrong.
12. **Check for past notes.** Review known issues before starting.

## Do Not

1. **Use sudo for installation.** Keep everything in user space.
2. **Skip rustup update.** Outdated Rust causes cryptic build failures.
3. **Start server when not needed.** Solo devs don't need it.
4. **Hardcode localhost URLs.** Use env vars with localhost fallback.
5. **Skip clippy in build verification.** It catches real issues.
6. **Assume PATH is configured.** `~/.cargo/bin` may not be in PATH.
7. **Install system-wide.** This complicates upgrades and cleanup.
8. **Mix production and dev setups.** Be explicit about which.

## Decision Points

### Solo vs Team Installation

Stop. Questions:
- Will observations be aggregated across projects?
- Are multiple developers using Aphoria?
- Is there a central compliance requirement?

**Solo:** Install Aphoria CLI only
**Team:** Install both Aphoria CLI and StemeDB server

### Server Persistence

Stop. Questions:
- Is this for testing or production?
- Does data need to survive restarts?
- What's the disk space budget?

**Testing:** Use default `/tmp` (ephemeral)
**Production:** Set `STEMEDB_DATA_DIR=/var/lib/stemedb` (persistent)

## Constraints

**NEVER:**
- Use `sudo` for any installation step
- Install globally when user-space works
- Skip the `aphoria init` step
- Run server as root
- Hardcode paths without env var fallback

**ALWAYS:**
- Verify Rust 1.75+ before building
- Run `cargo clippy --workspace -- -D warnings` to validate build
- Use the port scheme (181XX) for servers
- Provide verification commands after each step
- Include rollback/uninstall instructions
- Create note in `~/.aphoria/notes/` when issues occur
- Check for existing notes about known issues before installing

## Installation Protocol

### Phase 1: Prerequisites

```bash
# Check Rust version (need 1.75+)
rustc --version

# If missing or outdated:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
rustup update
```

### Phase 2: Build and Install Aphoria

```bash
# Navigate to Aphoria
cd /path/to/stemedb/applications/aphoria

# Build (includes all tests and clippy)
cargo build --release

# Install to ~/.cargo/bin
cargo install --path .

# Verify
aphoria --version
# Expected: aphoria 0.1.0
```

### Phase 3: Initialize Corpus

```bash
# Load authoritative corpus (RFCs, OWASP)
aphoria init
# Expected: "Initializing Aphoria..."
#           "Ingested N authoritative assertions."
#           "Ready."
```

### Phase 4: First Scan (Verification)

```bash
# Quick ephemeral scan (any project directory)
cd ~/some-project
aphoria scan .

# Expected output (example):
# Scanning some-project ...
#   BLOCK  code://python/requests/tls/cert_verification
#          Your code:  verify=False (api/client.py:42)
#          RFC 5246:   TLS certificate verification MUST be enabled
#          Conflict:   0.92
# N conflicts found.
```

### Phase 5 (Optional): StemeDB Server

Only for teams wanting observation aggregation:

```bash
# From stemedb root
cd /path/to/stemedb

# Build server
cargo build --release -p stemedb-api

# Run (ephemeral, for testing)
cargo run --release -p stemedb-api -- --bind 127.0.0.1:18180

# Or with persistence
STEMEDB_DATA_DIR=~/.stemedb cargo run --release -p stemedb-api -- \
    --bind 127.0.0.1:18180

# Verify
curl http://localhost:18180/health
# Expected: {"status":"ok"}
```

### Phase 6: Set Up Project (MANDATORY)

When installing Aphoria on any project, **always do all three**:

```bash
# 1. Create config
cat > aphoria.toml << 'EOF'
[project]
name = "my-project"
description = "Brief description"

[scan]
domains = ["security", "cryptography"]

[thresholds]
flag = 0.4
block = 0.6

[learning]
persist = true
sync = true
EOF

# 2. Install pre-commit hook (NOT OPTIONAL)
mkdir -p .git/hooks
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
aphoria scan --staged --exit-code
if [ $? -ne 0 ]; then
    echo "Aphoria found conflicts."
    exit 1
fi
EOF
chmod +x .git/hooks/pre-commit

# 3. Create documentation
cat > aphoria.md << 'EOF'
# Aphoria Integration

This project uses Aphoria for autonomous security pattern learning.
Every commit triggers a scan. Observations feed back to the corpus.
See aphoria.toml for configuration.
EOF

# 4. Run baseline
aphoria scan --persist --sync
```

**Do not skip the hook.** It's the trigger for autonomous learning.

### Phase 7 (Optional): Configure Hosted Mode

Connect Aphoria to StemeDB server:

```bash
# Add to aphoria.toml
[hosted]
url = "http://localhost:18180"

# Test connection
aphoria scan --persist --sync
# Expected: "Pushed N observations to hosted server"
```

## Troubleshooting

### "command not found: aphoria"

```bash
# Add cargo bin to PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Or for zsh
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

### Build fails with "edition 2024"

```bash
# Update Rust
rustup update

# Verify version (need 1.75+)
rustc --version
```

### "No authoritative assertions" on scan

```bash
# Corpus not initialized
aphoria init
```

### Server "address already in use"

```bash
# Check what's using port 18180
lsof -i :18180

# Kill existing process or use different port
cargo run -p stemedb-api -- --bind 127.0.0.1:18181
```

### "Hosted sync failed"

```bash
# Check server is running
curl http://localhost:18180/health

# Check URL in aphoria.toml is correct
cat aphoria.toml

# Enable debug logging
RUST_LOG=aphoria=debug aphoria scan --persist --sync
```

## Uninstall

```bash
# Remove binary
rm ~/.cargo/bin/aphoria

# Remove local data
rm -rf ~/.aphoria

# Remove stemedb data (if using persistent mode)
rm -rf ~/.stemedb

# Remove server binary (if installed)
rm ~/.cargo/bin/stemedb-api
```

## Output Format

When guiding installation, provide:

```
## Current Status
- Rust: [version or missing]
- Aphoria: [installed/missing]
- StemeDB: [optional - running/stopped/not needed]

## Next Step
[Single clear action]

## Command
```bash
[exact command to run]
```

## Expected Output
[what they should see]
```

## Quick Reference

| Command | Purpose |
|---------|---------|
| `aphoria --version` | Verify installation |
| `aphoria init` | Load authoritative corpus |
| `aphoria scan .` | Quick ephemeral scan |
| `aphoria scan --staged --exit-code` | Pre-commit mode |
| `aphoria scan --persist` | Enable drift detection |
| `aphoria scan --persist --sync` | Push to hosted server |
| `cargo run -p stemedb-api` | Start StemeDB server |
| `curl localhost:18180/health` | Verify server health |

## Environment Variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `STEMEDB_DATA_DIR` | `/tmp` | Server data directory |
| `STEMEDB_BIND_ADDR` | `127.0.0.1:18180` | Server bind address |
| `APHORIA_API_KEY` | (none) | Auth token for hosted mode |
| `RUST_LOG` | (none) | Debug logging (`aphoria=debug`) |

## Issue Documentation Protocol

When something doesn't work as expected, bugs occur, or workarounds are needed, create a note to track the experience.

### Note Location

```
~/.aphoria/notes/{YYYY-MM-DD}-{issue-name}.md
```

Example: `~/.aphoria/notes/2026-02-07-rust-version-mismatch.md`

### When to Create Notes

Create a note when:
- A step fails unexpectedly
- Verification doesn't pass
- A workaround was needed
- Documentation was incomplete or wrong
- Environment-specific issues occurred
- User had to intervene manually

### Note Format

```markdown
# Installation Note: [Issue Name]

**Date:** YYYY-MM-DD HH:MM
**Phase:** Prerequisites | Build | Init | Verify | Server
**Outcome:** Success with issues | Partial failure | Complete failure

## Environment
- OS: [macOS/Linux/Windows]
- Rust version: [rustc output]
- Working directory: [path]

## Issue Summary
[One paragraph describing what went wrong]

## Steps to Reproduce
1. [Step that triggered the issue]
2. [What was expected]
3. [What actually happened]

## Error Output
```
[Paste error messages or unexpected output]
```

## Workaround Applied
[What was done to work around the issue, if any]

## Root Cause (if known)
[Why this happened]

## Suggested Fix
[How the skill/docs should be updated to prevent this]

## Tags
#bug #prerequisite #build #init #server #workaround
```

### Creating Notes

```bash
# Ensure directory exists
mkdir -p ~/.aphoria/notes

# Create note
cat > ~/.aphoria/notes/$(date +%Y-%m-%d)-issue-name.md << 'EOF'
[Note content]
EOF
```

### Reviewing Past Notes

Before installing, check for known issues:
```bash
ls ~/.aphoria/notes/ 2>/dev/null
```

If notes exist, warn user about known issues they may encounter.
