stemedb/.claude/skills/aphoria-install/SKILL.md

name	description
aphoria-install	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.

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

# 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

# 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

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

Phase 4: First Scan (Verification)

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

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

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

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

# Update Rust
rustup update

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

"No authoritative assertions" on scan

# Corpus not initialized
aphoria init

Server "address already in use"

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

# 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

# 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

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

ls ~/.aphoria/notes/ 2>/dev/null

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