# Local Development Setup

**When to use:** Setting up StemeDB for local development.

## Prerequisites

- Rust 1.75+ (2024 edition)
- `cargo` and `rustup`

## Quick Start

```bash
# Clone and enter
cd stemedb

# Build everything
cargo build --workspace

# Run tests
cargo test --workspace

# Run lints (must pass)
cargo clippy --workspace -- -D warnings
cargo fmt --check
```

## IDE Setup

### VS Code

Install extensions:
- rust-analyzer
- Even Better TOML
- Error Lens (optional, shows inline errors)

Settings (`.vscode/settings.json`):
```json
{
  "rust-analyzer.check.command": "clippy",
  "rust-analyzer.check.allTargets": true
}
```

### JetBrains (RustRover/CLion)

- Enable Clippy as default checker
- Set rustfmt on save

## Project Structure

```
stemedb/
  CLAUDE.md           # AI router (start here)
  .claude/guides/coding-guidelines.md # Rust standards
  Cargo.toml          # Workspace root
  crates/
    stemedb-core/     # Core types and storage
  .claude/
    agents/           # Specialized AI agents
    commands/         # Slash commands
    skills/           # Reusable procedures
    guides/           # You are here
```

## Git Hooks

The repository includes automatic git hooks to rebuild binaries when source code changes:

- **post-merge**: Runs after `git pull` or `git merge`
- **post-checkout**: Runs after `git checkout` (branch switches only)

These hooks detect changes to:
- Aphoria CLI and core logic
- StemeDB API server
- StemeDB simulator
- Core libraries (affects all binaries)

When changes are detected, the hooks automatically run `cargo build --release --workspace` to rebuild all binaries. This prevents "command not found" errors from stale binaries.

The hooks are installed in `.git/hooks/` and are already executable. If you need to disable them temporarily, you can use `--no-verify` with git commands or rename the hook files.

## Troubleshooting

### Build fails with missing dependencies

```bash
rustup update
cargo clean
cargo build
```

### Clippy warnings

Run with `--fix` for auto-corrections:
```bash
cargo clippy --workspace --fix --allow-dirty
```

### "Command not found" after git pull

If you see this error despite the git hooks, manually rebuild:
```bash
cargo build --release --workspace
```

The binaries are in `target/release/` and should be in your PATH or called via `cargo run --release -p <package>`.

## Related

- [Testing Guide](./testing.md)
- [Rust Guidelines](../backend/rust-guidelines.md)