docs: update changelog + cli-reference + roadmap for Phase 1-3

CHANGELOG.md

@@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Highlights
+
+- **Brain Mode — hybrid code search.** `cora brain <query>` combines FTS5 keyword search, usearch vector similarity (HNSW), and graph BFS proximity into a single ranked result set via RRF fusion (k=60). Index-time embeddings use a zero-dependency static token method (256d) — no model download, no GPU.
+- **tree-sitter AST extraction + call edges.** Schema v3 adds an `edges` table storing caller→callee relationships. When `cora index` runs with `--features tree-sitter`, it extracts function calls from AST nodes, enabling `cora trace` and `cora arch`.
+- **`cora trace` and `cora arch` commands.** Trace symbol call chains (depth-limited) and display architecture overview (module breakdown, edge types, top connectors) from the indexed call graph.
+- **Static token embedding engine.** Zero-dependency bag-of-tokens hashing (256d) for code symbol embeddings — suitable for near-duplicate detection and semantic search without external models.
+- **Global index directory.** The symbol database migrated from `.cora/graph.db` (per-project) to `~/.codecora/cora-code/graph.db` (per-user), shared across all projects.
+- **Renamed `cora-cli` → `cora-code`.** Binary is now `cora`, crate is `cora-code`.
+
+### Added
+
+- **Phase 3 — Brain Mode** (#362)
+  - `CodeVectorIndex` — persistent usearch HNSW vector index with fs2 file locking, key↔symbol mapping, and disk serialization
+  - `brain_search()` — hybrid search: FTS5 + usearch KNN (cosine, top-50) + graph BFS (depth-2 from FTS hits) → RRF k=60 fusion
+  - Schema v4: `embedding_tier`, `embedding_dims`, `embedding_model`, `last_embedded_at` columns on `projects` table
+  - Index-time embedding: all symbols embedded via static tokens during `cora index`
+  - CLI: `cora brain <query> [--json] [--limit N]`
+  - MCP tool: `cora.brain_search` — semantic code search for AI coding agents
+- **Phase 2C — `cora trace` and `cora arch`** (#358)
+  - `cora trace <symbol>` — trace call chains from a symbol (depth-limited BFS on call edges)
+  - `cora arch` — architecture overview: module breakdown, edge types, top connectors
+- **Phase 2 — tree-sitter AST extraction + Schema v3** (#356)
+  - tree-sitter AST node extraction for Rust, Python, JavaScript, TypeScript, Go, Java
+  - Schema v3: `edges` table (caller_id, callee_id, edge_type) storing call relationships
+  - Gated behind `--features tree-sitter` (default build does not include tree-sitter)
+- **Phase 1 — Static token embedding engine** (#354)
+  - Bag-of-tokens hashing: 256d vectors from code text, zero external dependencies
+  - Pre-trained nomic-embed-code vocabulary included (768d, reserved for Phase 5)
+  - `tokenize_code()`, `embed_code()`, `cosine_similarity()` public API
+- **Global index migration** (#355)
+  - Symbol database moved from `.cora/graph.db` to `~/.codecora/cora-code/graph.db`
+  - `CODECORA_HOME` env var override for custom data directory
+- **Binary rename** (#338)
+  - Crate renamed `cora-cli` → `cora-code`
+  - Binary name: `cora`
+
 ## [0.7.0] - 2026-07-16
 
 ### Highlights

docs/cli-reference.md

@@ -61,13 +61,15 @@ Complete command reference for the cora CLI.
 | `cora debt --estimate` | Show estimated fix time |
 | `cora debt --since v0.4.5` | Filter by git tag or date |
 | `cora debt --branch main` | Filter by branch |
+| `cora arch` | Architecture overview — modules, edge types, top connectors |
+| `cora trace` `<symbol>` | Trace call chains from a symbol (depth-limited BFS) |
+| `cora brain` `<query>` | Hybrid search: FTS5 + vector + graph → RRF fusion |
+| `cora brain` `--json` | Brain search as JSON |
+| `cora brain` `--limit N` | Max results (default: 20) |
+| `cora index` | Index project symbols into SQLite + usearch |
+| `cora index --rebuild` | Rebuild index from scratch |
 | `cora completion` `<shell>` | Generate shell completions (bash/zsh/fish) |
 | `cora mcp` | Start MCP server for AI coding agents (Claude Code, Cursor, Windsurf) |
-| `cora debt` | Show tech debt report from review history |
-| `cora debt --json` | Debt report in JSON format |
-| `cora debt --trend` | Quality score trend graph |
-| `cora debt --since <date\|tag>` | Filter by date or git tag |
-| `cora debt --branch <name>` | Filter by branch name |
 
 ## Quick Examples
 
@@ -106,3 +108,16 @@ $ curl -fsSL https://raw.githubusercontent.com/codecoradev/cora-code/main/instal
 # Then review with memory:
 $ cora review --staged --memory --learn
 ```
+
+```bash
+# Index your project and search with Brain Mode
+$ cora index
+$ cora brain "error handling"
+$ cora brain "TokenEmbedding" --json --limit 5
+```
+
+```bash
+# Trace call chains and view architecture
+$ cora trace main
+$ cora arch
+```

docs/roadmap.md

@@ -104,5 +104,16 @@ Query layer built on top of the v0.6 index — call graph traversal, test impact
 
 ## Future — What's Next
 
+### Brain Mode Roadmap
+
+- [Phase 1](https://github.com/codecoradev/cora-code/pull/354) — Static token embedding engine (256d) — ✓ Done
+- [Phase 2](https://github.com/codecoradev/cora-code/pull/356) — tree-sitter AST + schema v3 edges table — ✓ Done
+- [Phase 2C](https://github.com/codecoradev/cora-code/pull/358) — `cora trace` + `cora arch` — ✓ Done
+- [Phase 3](https://github.com/codecoradev/cora-code/pull/362) — Brain Mode hybrid search (usearch + RRF) — ✓ Done
+- [Phase 4](https://github.com/codecoradev/cora-code/issues/360) — Uteke integration upgrade → Planned
+- [Phase 5](https://github.com/codecoradev/cora-code/issues/361) — Voyage-4-Nano ONNX (opt-in, 1024d) → Deferred
+
+### Other
+
 - [#117](https://github.com/codecoradev/cora-code/issues/117) Lightweight agent follow-up — 1 capped tool-call — → Planned
 - [#132](https://github.com/codecoradev/cora-code/issues/132) GitHub App backend MVP in Rust (Axum) — → Planned