diff --git a/.claude/skills/aphoria-install/SKILL.md b/.claude/skills/aphoria-install/SKILL.md new file mode 100644 index 0000000..29b5b27 --- /dev/null +++ b/.claude/skills/aphoria-install/SKILL.md @@ -0,0 +1,342 @@ +--- +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`) | diff --git a/CLAUDE.md b/CLAUDE.md index b132b6d..f943c5b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -46,6 +46,7 @@ A probabilistic knowledge graph database that stores Claims, not Facts. Append-o | **Understand repo structure** | [ai-lookup/repo-structure.md](ai-lookup/repo-structure.md) | | **Aphoria LLM eval** | Load skill: `aphoria-llm-optimization` | | **General LLM optimization** | Load skill: `llm-optimization` | +| **Install Aphoria** | Load skill: `aphoria-install` | ## Roadmap Maintenance