jml 9bfa626203 docs: reorganize documentation structure for clarity

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>

2026-02-11 07:33:40 +00:00

2.4 KiB

Raw Blame History

Local Development Setup

When to use: Setting up StemeDB for local development.

Prerequisites

Rust 1.75+ (2024 edition)
cargo and rustup

Quick Start

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

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

rustup update
cargo clean
cargo build

Clippy warnings

Run with --fix for auto-corrections:

cargo clippy --workspace --fix --allow-dirty

"Command not found" after git pull

If you see this error despite the git hooks, manually rebuild:

cargo build --release --workspace

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

2.4 KiB Raw Blame History