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

## 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. Ephemeral by Default
Default scans are fast and ephemeral. Server/persistence is opt-in.

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

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

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

## 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 (Optional): Configure Hosted Mode

Connect Aphoria to StemeDB server:

```bash
# In project directory
cat > aphoria.toml << 'EOF'
[project]
name = "my-project"

[hosted]
url = "http://localhost:18180"
EOF

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