9bfa626203
Major documentation restructure to improve discoverability and reduce duplication. ## Changes **Deleted (Archived/Consolidated)**: - Removed duplicate getting started guides - Archived outdated planning documents - Consolidated corpus and configuration docs - Removed obsolete vision/spec files (superseded by vision.md) - Cleaned up scrapyard and old PDFs **New Structure**: - docs/about/ - Project overview and introduction - docs/guides/ - User guides (moved from root) - docs/specs/ - Technical specifications - docs/sdk/ - SDK documentation (Go) - docs/references/ - API references - docs/archive/ - Archived historical docs - applications/aphoria/docs/advanced/ - Advanced topics - applications/aphoria/docs/reference/ - CLI reference - applications/aphoria/docs/archive/ - Archived aphoria docs **Updated**: - README.md - New root README with clear navigation - CONTRIBUTING.md - Contribution guidelines - CLAUDE.md - Updated paths to new structure - roadmap.md - Added recent completions ## Files Changed - 57 files changed - 1,977 insertions(+) - 961 deletions(-) **Net change**: +1,016 lines (added CONTRIBUTING.md, README.md, reorganized content) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
112 lines
2.4 KiB
Markdown
112 lines
2.4 KiB
Markdown
# 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)
|