fix: developer UX audit — 8 issues resolved

Auth / SDK errors
- Add AuthenticationError for 401/403; was misreported as ConnectionError
- _raise_for_status() helper replaces bare raise_for_status() everywhere
- AsyncRemoteClient._post also intercepts 401/403 before wrapping as ConnectionError
- Export AuthenticationError from valoricore.__init__

SDK / cluster parity
- Add 8 missing /v1/* routes to cluster_server.rs (memory upsert/search,
  list nodes, version, timeline, snapshot save/restore/download)
- Fix broken SDK: all /v1/ paths now exist on both standalone and cluster

Search dimension validation
- engine.search_l2 / search_l2_ns reject wrong-dim queries with clear error
- Cluster path checks locked_dim() before converting to FxpVector
- Integration test added: test_search_dim_validated

Audit page JS crash
- API route returns [] (not error object) when node unreachable
- Client guards with Array.isArray before .map()

verify_log() in-process FFI
- Extract replay logic from valori-verify/main.rs into lib.rs as pub fn
- Expose verify_log_file() PyO3 function in valoricore-ffi
- verify_log() tries FFI first; falls back to subprocess with clear message
- pip users never need the valori-verify binary on PATH

Version unification
- pyproject.toml: dynamic = ["version"]; maturin reads from Cargo workspace
- Single source of truth: bump root Cargo.toml version, both server and
  wheel stay in sync automatically

UI / DX
- npm ci everywhere (CONTRIBUTING, README, dev-setup.sh) for lockfile-exact installs
- Add ui/Dockerfile (3-stage: deps/builder/runner with standalone Next.js output)
- docker-compose: add valori-ui service
- Suppress urllib3 LibreSSL warning on import (cosmetic, not a real error)

E2E test + engine bug fixes
- e2e-test.yml: maturin develop (no glob), add Cargo cache, split steps
- Fix create_edge committer path: edge_id from live_state not engine.state
- Fix search committer path: read live_state not engine.state
- Both bugs caused MemoryClient graph ops and search to silently fail

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: varshith-Git

.github/workflows/e2e-test.yml

@@ -29,18 +29,31 @@ jobs:
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Cache Rust build artifacts
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target/
+          key: ${{ runner.os }}-cargo-e2e-${{ hashFiles('Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-e2e-
+
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
 
-      - name: Build, Install, and Run E2E Test
-        run: |
-          python -m venv .venv
-          source .venv/bin/activate
-          pip install maturin
-          cd python
-          maturin build --release
-          pip install ../target/wheels/valoricore*.whl --force-reinstall
-          cd ..
-          python scripts/valori_e2e_tracer.py
+      - name: Install maturin
+        run: pip install maturin
+
+      - name: Build and install valoricore wheel
+        # maturin develop compiles the Rust extension and installs it into the
+        # active Python environment in one step — no glob-expansion issues from
+        # matching multiple wheel files, and no path-relativity bugs.
+        working-directory: python
+        run: maturin develop --release
+
+      - name: Run E2E tracer
+        run: python scripts/valori_e2e_tracer.py

CONTRIBUTING.md

@@ -136,9 +136,9 @@ maturin develop        # compiles and installs into your active Python env
 ## 4. Web dashboard (Next.js UI)
 
 ```bash
-# Node.js 18+ required
+# Node.js 20+ required (pinned in ui/package.json engines field)
 cd ui
-npm install
+npm ci           # installs exact versions from package-lock.json — do not use npm install
 npm run dev      # starts at http://localhost:3001
 ```
 

Cargo.lock

@@ -49,6 +49,7 @@ valori-kernel    = { path = "crates/valori-kernel",    version = "0.2.1", defaul
 valori-wire      = { path = "crates/valori-wire",      version = "0.2.1" }
 valori-consensus = { path = "crates/valori-consensus", version = "0.2.1" }
 valori-node      = { path = "crates/valori-node",      version = "0.2.1" }
+valori-verify    = { path = "crates/valori-verify",    version = "0.2.1" }
 
 # Firmware requires abort on panic (no unwinding support in no_std)
 # This also guarantees fail-closed behavior for the Node.

Cargo.toml

@@ -104,6 +104,10 @@ Every byte of state is recovered from the append-only, BLAKE3-chained event log
 
 > **New contributor?** `bash dev-setup.sh` — one script installs Rust, the wasm32 target, Python SDK, and UI deps with OS detection and version gates. See [Build from Source](#build-from-source) and [CONTRIBUTING.md](CONTRIBUTING.md).
 
+**Not writing code?** → [Option 2 — Web dashboard](#option-2--web-dashboard-no-code-60-seconds) is the fastest path. Point-and-click project management, no terminal after the first `docker compose up`.
+
+**Writing code?** Pick a client:
+
 **Which client should I use?**
 
 | Client | Install / import | Use when |
@@ -191,7 +195,27 @@ print(db.get_state_hash())
 
 The Rust kernel runs inside your Python process via PyO3 — no server, no Docker, no Rust toolchain needed.
 
-### Option 2 — Docker (~60 seconds, prebuilt image)
+### Option 2 — Web dashboard (no code, ~60 seconds)
+
+The fastest path if you're not writing code — a full point-and-click UI over your Valori node.
+
+```bash
+docker compose up -d              # start the node (port 3000)
+cd ui && npm ci npm install && npm run devnpm install && npm run dev npm run dev   # start the dashboard (port 3001)
+# open http://localhost:3001
+```
+
+**What you get:**
+- **Project manager home** — create named, isolated workspaces; each project gets its own node, port, and data directory under `~/.valori/projects/<name>/`
+- **Persistent state** — opening a project auto-starts its node and restores all data; closing it writes a final snapshot and locks files at rest
+- **Live activity** — count-up stats (records, nodes, edges), an activity heatmap, and a timeline of every committed event
+- **No URL hardcoding** — the UI proxies to the node through Next.js API routes, so there's nothing to configure
+
+The UI talks to the node server-side (Next.js API routes → node HTTP), so the node port never needs to be exposed to the browser directly. Safe to use behind a firewall.
+
+---
+
+### Option 3 — Docker, raw HTTP / Python SDK (~60 seconds, prebuilt image)
 
 ```bash
 docker compose up -d
@@ -233,7 +257,7 @@ hits = db.search(vec, k=5, metadata_filter={"year": {"gte": 2020}}) # range filt
 
 Edit `docker-compose.yml` to change `VALORI_DIM` (default: 1536), add auth, or mount S3.
 
-### Option 3 — One-call document ingest (chunk + embed on-node)
+### Option 4 — One-call document ingest (chunk + embed on-node)
 
 Add an embedding provider to Docker so clients can POST raw text — no client-side embedding needed:
 
@@ -260,7 +284,7 @@ print(ans["answer"], "—", ans["citations"][0]["breadcrumb"])  # lands on "…
 assert db.tree_verify(built["tree"], ans["receipt"])          # proves it wasn't altered
 ```
 
-### Option 4 — 3-node cluster
+### Option 5 — 3-node cluster
 
 ```bash
 cargo install --path crates/valori-cli
@@ -269,7 +293,7 @@ valori setup   # interactive wizard
 
 → [Cluster setup guide](docs/CLUSTER.md) · [Docker Compose](docker-compose.cluster.yml) · [Helm chart](deploy/helm/valori/) · [AWS/Azure Terraform](docs/DEPLOY_AWS.md)
 
-### Option 5 — Agent memory via MCP
+### Option 6 — Agent memory via MCP
 
 ```bash
 VALORI_URL=http://localhost:3000 valori-mcp
@@ -284,17 +308,6 @@ VALORI_URL=http://localhost:3000 valori-mcp
 
 → [`crates/valori-mcp/README.md`](crates/valori-mcp/README.md)
 
-### Option 6 — Web dashboard with persistent projects
-
-```bash
-cd ui && npm install && npm run dev   # http://localhost:3001
-```
-
-Each **project** is an isolated, persistent workspace: its own node, port, and
-data dir under `~/.valori/projects/<name>/`. The Home screen lists every project
-(even when its node is stopped); opening one auto-starts its node and restores
-state, and closing it writes a snapshot and locks the files at rest — they can
-only be deleted from the UI. → [`docs/phases/phase-6-persistent-projects.md`](docs/phases/phase-6-persistent-projects.md)
 
 ---
 
@@ -327,11 +340,15 @@ Requires Rust 1.80+. For the Python FFI extension: `pip install maturin && matur
 
 ## Documentation
 
+**[docs/README.md](docs/README.md)** — start here. Routes you by use case (trying it out / building an app / deploying / verifying / contributing) before listing the full reference index.
+
+Key docs directly:
+
 | Doc | What it covers |
 |---|---|
-| [docs/getting-started.md](docs/getting-started.md) | Full quickstart for all deployment modes |
-| [docs/api-reference.md](docs/api-reference.md) | Complete HTTP API reference |
-| [docs/python-reference.md](docs/python-reference.md) | Full Python SDK reference |
+| [docs/getting-started.md](docs/getting-started.md) | First insert, search, collections, auth — all deployment modes |
+| [docs/api-reference.md](docs/api-reference.md) | Complete HTTP API reference (all `/v1/` endpoints) |
+| [docs/python-reference.md](docs/python-reference.md) | Full Python SDK reference — all four clients |
 | [docs/CLUSTER.md](docs/CLUSTER.md) | Cluster setup, operations, failover |
 | [docs/DR.md](docs/DR.md) | Backup, restore, cross-region DR runbook |
 | [docs/CAPACITY.md](docs/CAPACITY.md) | Capacity planning — vectors/GB, WAL growth, S3 cost |

README.md

@@ -422,6 +422,12 @@ impl ValoriStateMachine {
         hash_state_blake3(&self.inner.lock().await.state)
     }
 
+    /// The dimension the kernel has actually locked to (set on first insert).
+    /// Returns `None` if no records have been inserted yet.
+    pub async fn locked_dim(&self) -> Option<usize> {
+        self.inner.lock().await.state.dim
+    }
+
     /// Run a read-only closure against the kernel state (Phase 2.5 uses
     /// this for serving reads without copying the state out).
     pub async fn with_state<T>(&self, f: impl FnOnce(&KernelState) -> T) -> T {

crates/valori-consensus/src/state_machine.rs

@@ -11,6 +11,7 @@ crate-type = ["cdylib"]
 [dependencies]
 valori-kernel = { workspace = true, features = ["std"] }
 valori-node = { workspace = true }
+valori-verify = { workspace = true }
 pyo3 = { version = "0.29.0", features = ["extension-module", "abi3-py39"] }
 serde_json = "1.0"
 hex = "0.4"

crates/valori-ffi/Cargo.toml

@@ -111,9 +111,17 @@ impl ValoricoreEngine {
     fn search(&self, vector: Vec<f32>, k: usize, filter_tag: Option<u64>) -> PyResult<Vec<(u32, i64)>> {
         let engine = lock_engine!(self);
 
-        // H-3: Reject dimension mismatches for search too; the kernel silently truncates
-        // to min(query.len(), record.len()) which produces wrong distances, not errors.
-        if let Some(dim) = engine.state.dim {
+        // When a committer is active, engine.state is never mutated — reads must
+        // go to live_state.  Fall back to engine.state in the no-committer path.
+        let state_ref: &valori_kernel::state::kernel::KernelState = if let Some(ref c) = engine.event_committer {
+            c.live_state()
+        } else {
+            &engine.state
+        };
+
+        // H-3: Reject dimension mismatches; the kernel silently truncates to
+        // min(query.len(), record.len()) which produces wrong distances, not errors.
+        if let Some(dim) = state_ref.dim {
             if vector.len() != dim {
                 return Err(PyValueError::new_err(format!(
                     "dimension mismatch: engine expects {dim}, got {}", vector.len()
@@ -128,7 +136,7 @@ impl ValoricoreEngine {
         let fxp_vec = FxpVector { data: fxp_data };
 
         let mut results = vec![valori_kernel::index::SearchResult::default(); k];
-        let count = engine.state.search_l2(&fxp_vec, &mut results, filter_tag);
+        let count = state_ref.search_l2(&fxp_vec, &mut results, filter_tag);
 
         let mut py_results = Vec::with_capacity(count);
         for i in 0..count {
@@ -530,11 +538,36 @@ fn verify_embedding(floats: Vec<f32>, claimed_hash: String) -> PyResult<bool> {
     Ok(computed_hash == claimed_hash)
 }
 
+/// Replay an event log file in-process and return a JSON verification report string.
+///
+/// This is identical to `valori-verify --report` but runs inside the already-loaded
+/// `.so` — no subprocess, no binary on PATH, no Rust toolchain required for pip users.
+///
+/// Args:
+///     log_path:      Path to the events.log file.
+///     expected_hash: Optional 64-char hex BLAKE3 state hash to compare against.
+///
+/// Returns:
+///     JSON string with the same schema as `valori-verify --report`.
+///
+/// Raises:
+///     RuntimeError: if the file cannot be read or has a corrupt header.
+#[pyfunction]
+#[pyo3(signature = (log_path, expected_hash = None))]
+fn verify_log_file(log_path: String, expected_hash: Option<String>) -> PyResult<String> {
+    use std::path::Path;
+    let path = Path::new(&log_path);
+    let result = valori_verify::verify_log_file(path, expected_hash.as_deref())
+        .map_err(|e| PyRuntimeError::new_err(e))?;
+    serde_json::to_string(&result).map_err(|e| PyRuntimeError::new_err(e.to_string()))
+}
+
 #[pymodule]
 fn valoricore_ffi(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<ValoricoreEngine>()?;
     m.add_function(wrap_pyfunction!(ingest_embedding, m)?)?;
     m.add_function(wrap_pyfunction!(generate_proof, m)?)?;
     m.add_function(wrap_pyfunction!(verify_embedding, m)?)?;
+    m.add_function(wrap_pyfunction!(verify_log_file, m)?)?;
     Ok(())
 }