diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 54bc27f..5546f8f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,137 +1,214 @@
 # Contributing to Vestige
 
-Thank you for your interest in contributing to Vestige! This document provides guidelines and information to help you get started.
+Thank you for your interest in contributing to Vestige! This guide covers everything you need to get started.
 
 ## Project Overview
 
-Vestige is a Tauri-based desktop application combining a Rust backend with a modern web frontend. We welcome contributions of all kinds—bug fixes, features, documentation, and more.
+Vestige is a cognitive memory MCP server written in Rust. It gives AI agents persistent long-term memory using neuroscience-backed algorithms (FSRS-6, prediction error gating, synaptic tagging, spreading activation, memory dreaming).
+
+**Architecture:**
+
+```
+vestige/
+├── crates/
+│   ├── vestige-core/       # Cognitive engine, FSRS-6, search, embeddings, storage
+│   └── vestige-mcp/        # MCP server, Axum dashboard, WebSocket, tool handlers
+├── apps/
+│   └── dashboard/          # SvelteKit + Three.js 3D dashboard
+├── packages/
+│   ├── vestige-init/       # npx @vestige/init installer
+│   └── vestige-mcp-npm/    # npm binary wrapper
+└── tests/
+    └── vestige-e2e-tests/  # End-to-end MCP protocol tests
+```
 
 ## Development Setup
 
 ### Prerequisites
 
-- **Rust** (stable, latest recommended): [rustup.rs](https://rustup.rs)
-- **Node.js** (v18 or later): [nodejs.org](https://nodejs.org)
-- **pnpm**: Install via `npm install -g pnpm`
-- **Platform-specific dependencies**: See [Tauri prerequisites](https://tauri.app/v1/guides/getting-started/prerequisites)
+- **Rust** (1.85+ stable): [rustup.rs](https://rustup.rs)
+- **Node.js** (v22+): [nodejs.org](https://nodejs.org)
+- **pnpm** (v9+): `npm install -g pnpm`
 
 ### Getting Started
 
-1. Clone the repository:
-   ```bash
-   git clone https://github.com/samvallad33/vestige.git
-   cd vestige
-   ```
+```bash
+git clone https://github.com/samvallad33/vestige.git
+cd vestige
 
-2. Install frontend dependencies:
-   ```bash
-   pnpm install
-   ```
+# Build the dashboard (required for include_dir! embedding)
+cd apps/dashboard && pnpm install && pnpm build && cd ../..
 
-3. Run in development mode:
-   ```bash
-   pnpm tauri dev
-   ```
+# Build the Rust workspace
+cargo build
+
+# Run tests
+VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test --workspace
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `VESTIGE_TEST_MOCK_EMBEDDINGS=1` | Use mock embeddings in tests (skips ONNX model download) |
+| `VESTIGE_DB_PATH` | Override default database path (`~/.vestige/vestige.db`) |
 
 ## Running Tests
 
 ```bash
-# Run Rust tests
-cargo test
+# All tests (734 total)
+VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test --workspace
 
-# Run with verbose output
-cargo test -- --nocapture
+# Core library tests only (352 tests)
+VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test -p vestige-core --lib
+
+# MCP server tests only (378 tests)
+VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test -p vestige-mcp --lib
+
+# E2E MCP protocol tests (requires release build)
+cargo build --release -p vestige-mcp
+cargo test -p vestige-e2e-tests --test mcp_protocol -- --test-threads=1
+
+# Dashboard build test
+cd apps/dashboard && pnpm build
 ```
 
 ## Building
 
 ```bash
-# Build Rust backend (debug)
-cargo build
+# Debug build
+cargo build -p vestige-mcp
 
-# Build Rust backend (release)
-cargo build --release
+# Release build (22MB binary with embedded dashboard)
+cargo build --release -p vestige-mcp
 
-# Build frontend
-pnpm build
-
-# Build complete Tauri application
-pnpm tauri build
+# The release binary is at target/release/vestige-mcp
 ```
 
+### Release Profile
+
+The release profile uses `lto = true`, `codegen-units = 1`, `opt-level = "z"`, and `strip = true` for minimum binary size.
+
 ## Code Style
 
 ### Rust
 
-We follow standard Rust conventions enforced by `rustfmt` and `clippy`.
-
 ```bash
-# Format code
-cargo fmt
+# Format
+cargo fmt --all
 
-# Run linter
-cargo clippy -- -D warnings
+# Lint (zero warnings policy)
+cargo clippy --workspace -- -D warnings
 ```
 
-Please ensure your code passes both checks before submitting a PR.
+- Rust 2024 edition
+- Standard `rustfmt` defaults
+- All public items should have doc comments
+- Tests go in `#[cfg(test)] mod tests` at the bottom of each file
 
-### TypeScript/JavaScript
+### TypeScript/Svelte (Dashboard)
 
 ```bash
-# Lint and format
-pnpm lint
-pnpm format
+cd apps/dashboard
+pnpm check    # Svelte type checking
+pnpm lint     # ESLint
 ```
 
+## Project Structure
+
+### vestige-core
+
+The cognitive engine. Key modules:
+
+| Module | Purpose |
+|--------|---------|
+| `fsrs/` | FSRS-6 spaced repetition (21 parameters, power-law decay) |
+| `neuroscience/` | Synaptic tagging, spreading activation, hippocampal index, importance signals |
+| `advanced/` | Prediction error gating, dreaming, compression, cross-project learning |
+| `search/` | Hybrid search (BM25 + semantic), HyDE, reranker, temporal search |
+| `embeddings/` | fastembed (Nomic Embed v1.5), ONNX inference |
+| `storage/` | SQLite + FTS5 + USearch HNSW |
+
+### vestige-mcp
+
+The MCP server and dashboard. Key modules:
+
+| Module | Purpose |
+|--------|---------|
+| `server.rs` | MCP JSON-RPC server (rmcp 0.14) |
+| `cognitive.rs` | CognitiveEngine — 29 stateful modules |
+| `tools/` | One file per MCP tool (21 tools) |
+| `dashboard/` | Axum HTTP + WebSocket + event bus |
+
+### apps/dashboard
+
+SvelteKit 2 + Three.js + Tailwind CSS. Pages:
+
+- `/dashboard` — 3D memory graph with force-directed layout
+- `/dashboard/memories` — Searchable memory browser
+- `/dashboard/timeline` — Chronological memory timeline
+- `/dashboard/feed` — Real-time WebSocket event stream
+- `/dashboard/explore` — Connection explorer (associations, chains, bridges)
+- `/dashboard/intentions` — Intention manager
+- `/dashboard/stats` — System health, retention distribution, module status
+
 ## Pull Request Process
 
-1. **Fork** the repository and create a feature branch from `main`.
-2. **Write tests** for new functionality.
-3. **Ensure all checks pass**: `cargo fmt`, `cargo clippy`, `cargo test`.
-4. **Keep commits focused**: One logical change per commit with clear messages.
-5. **Update documentation** if your changes affect public APIs or behavior.
-6. **Open a PR** with a clear description of what and why.
+1. **Fork** the repository and create a feature branch from `main`
+2. **Write tests** for new functionality
+3. **Ensure all checks pass**: `cargo fmt`, `cargo clippy`, `cargo test`
+4. **Build the dashboard** if you modified `apps/dashboard/`
+5. **Keep commits focused**: One logical change per commit
+6. **Open a PR** with a clear description
 
 ### PR Checklist
 
-- [ ] Code compiles without warnings
-- [ ] Tests pass locally
-- [ ] Code is formatted (`cargo fmt`)
-- [ ] Clippy passes (`cargo clippy -- -D warnings`)
-- [ ] Documentation updated (if applicable)
+- [ ] `cargo fmt --all` — code is formatted
+- [ ] `cargo clippy --workspace -- -D warnings` — zero warnings
+- [ ] `VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test --workspace` — all tests pass
+- [ ] Dashboard builds (if modified): `cd apps/dashboard && pnpm build`
+- [ ] No secrets, API keys, or credentials in code
+
+### Good First Issues
+
+Look for issues labeled `good first issue`. These are scoped, well-defined tasks ideal for new contributors:
+
+- Adding tests for existing modules
+- Documentation improvements
+- Dashboard UI enhancements
+- New MCP tool implementations
+
+## Adding a New MCP Tool
+
+1. Create `crates/vestige-mcp/src/tools/your_tool.rs`
+2. Implement `pub fn schema() -> Tool` and `pub fn execute(...) -> Result<CallToolResult>`
+3. Register in `crates/vestige-mcp/src/tools/mod.rs`
+4. Add tests in the same file
+5. Update tool count in README and CLAUDE.md
+
+## Adding a New Cognitive Module
+
+1. Add the module to `crates/vestige-core/src/neuroscience/` or `advanced/`
+2. Add the field to `CognitiveEngine` in `crates/vestige-mcp/src/cognitive.rs`
+3. Initialize it in `CognitiveEngine::new()` and `new_with_events()`
+4. Write comprehensive tests (aim for 10+ per module)
+5. Document the neuroscience citation in the module's doc comment
 
 ## Issue Reporting
 
-When reporting bugs, please include:
+Use the issue templates:
 
-- **Summary**: Clear, concise description of the issue
-- **Environment**: OS, Rust version (`rustc --version`), Node.js version
-- **Steps to reproduce**: Minimal steps to trigger the bug
-- **Expected vs actual behavior**
-- **Logs/screenshots**: If applicable
-
-For feature requests, describe the use case and proposed solution.
+- **Bug Report**: Include OS, install method, IDE, vestige version, and steps to reproduce
+- **Feature Request**: Describe the problem, proposed solution, and alternatives considered
 
 ## Code of Conduct
 
-We are committed to providing a welcoming and inclusive environment. All contributors are expected to:
-
-- Be respectful and considerate in all interactions
-- Welcome newcomers and help them get started
-- Accept constructive criticism gracefully
-- Focus on what is best for the community
-
-Harassment, discrimination, and hostile behavior will not be tolerated.
+We are committed to providing a welcoming and inclusive environment. All contributors are expected to be respectful, constructive, and collaborative. Harassment and discrimination will not be tolerated.
 
 ## License
 
-By contributing, you agree that your contributions will be licensed under the same terms as the project:
-
-- **MIT License** ([LICENSE-MIT](LICENSE-MIT))
-- **Apache License 2.0** ([LICENSE-APACHE](LICENSE-APACHE))
-
-You may choose either license at your option.
+By contributing, you agree that your contributions will be licensed under **AGPL-3.0-only** ([LICENSE](LICENSE)), the same license as the project.
 
 ---
 
-Questions? Open a discussion or reach out to the maintainers. We're happy to help!
+Questions? Open a [discussion](https://github.com/samvallad33/vestige/discussions) or reach out to the maintainers.