fix(ux): dev experience audit — dim enforcement, auth, docs, examples

Author: varshith-Git

.env.example

@@ -1,5 +1,100 @@
-# Valori Environment Configuration
-# Copy this to .env and fill in your values
+# Valori node — environment variables
+# Copy this file to .env and uncomment what you need.
+# All variables are optional unless marked (required).
+#
+# Start a node: source .env && cargo run -p valori-node
+# Full reference: CLAUDE.md § Environment variables
 
-# Production Koyeb Deployment URL
-VALORI_URL=https://your-deployment.koyeb.app
+# ── Core (standalone node) ────────────────────────────────────────────────────
+
+# (required) Vector dimension — immutable after the first insert.
+VALORI_DIM=128
+
+# HTTP listen address (default: 0.0.0.0:3000)
+#VALORI_BIND=0.0.0.0:3000
+
+# Index type: "brute" (exact, default) or "hnsw" (approximate, faster at scale)
+#VALORI_INDEX=brute
+
+# Slab capacity — max records the node can hold in memory (default: 1_000_000)
+#VALORI_MAX_RECORDS=1000000
+
+# Graph slab capacities
+#VALORI_MAX_NODES=100000
+#VALORI_MAX_EDGES=500000
+
+# ── Durability ────────────────────────────────────────────────────────────────
+
+# Append-only BLAKE3-chained event log (omit = in-memory only, no crash recovery)
+#VALORI_EVENT_LOG_PATH=./data/events.log
+
+# Snapshot file for fast restart (omit = no snapshot; WAL-only recovery still works)
+#VALORI_SNAPSHOT_PATH=./data/snapshot.bin
+
+# ── Security ──────────────────────────────────────────────────────────────────
+
+# Bearer token — all API requests must include "Authorization: Bearer <token>"
+# Generate one: openssl rand -hex 32
+#VALORI_AUTH_TOKEN=
+
+# ── Recency decay ─────────────────────────────────────────────────────────────
+
+# Default half-life for recency-aware search ranking (seconds).
+# 86400 = 1 day. 0 or unset = no decay.
+#VALORI_DECAY_HALF_LIFE_SECS=86400
+
+# ── Built-in embedding / ingest pipeline ─────────────────────────────────────
+# Enables POST /v1/ingest — send raw text, get chunk+embed+insert in one call.
+
+# Provider: ollama | openai | custom (omit = embedding disabled)
+#VALORI_EMBED_PROVIDER=ollama
+
+# Model name (provider-specific default used if unset)
+#VALORI_EMBED_MODEL=nomic-embed-text
+
+# Base URL for the embedding provider
+#VALORI_EMBED_URL=http://localhost:11434
+
+# API key for OpenAI or custom providers
+#VALORI_EMBED_API_KEY=
+
+# ── Object-store offload (Phase 3.1) ─────────────────────────────────────────
+# Snapshot archival + WAL rotation to S3, MinIO, or R2.
+
+# s3://bucket/prefix | file:///path (omit = disabled)
+#VALORI_OBJECT_STORE_URL=s3://my-bucket/valori
+
+# Snapshots to keep after pruning (default: 7)
+#VALORI_OBJECT_STORE_KEEP=7
+
+# S3 region (also reads AWS_DEFAULT_REGION)
+#VALORI_OBJECT_STORE_REGION=us-east-1
+
+# Custom S3-compatible endpoint (MinIO / Localstack / R2)
+#VALORI_OBJECT_STORE_ENDPOINT=http://localhost:9000
+
+# ── Cluster additions ─────────────────────────────────────────────────────────
+# Uncomment all of these when running in cluster mode.
+
+# Integer node ID (1-based, must be unique in the cluster)
+#VALORI_NODE_ID=1
+
+# Full cluster topology: id=raft_addr/http_addr,...
+#VALORI_CLUSTER_MEMBERS=1=127.0.0.1:3101/127.0.0.1:3001,2=127.0.0.1:3102/127.0.0.1:3002,3=127.0.0.1:3103/127.0.0.1:3003
+
+# Set to 1 on the bootstrap node only, on first boot only. Remove after cluster is formed.
+#VALORI_CLUSTER_INIT=1
+
+# gRPC listen address for Raft (default: 0.0.0.0:3100)
+#VALORI_RAFT_BIND=0.0.0.0:3101
+
+# Persistent redb file for Raft log + vote + state machine
+#VALORI_RAFT_LOG_PATH=./data/raft.redb
+
+# Hash-convergence poll interval in seconds (0 = off, default: 30)
+#VALORI_STATE_HASH_CHECK_SECS=30
+
+# mTLS for inter-node Raft traffic (all three required to enable mTLS)
+#VALORI_TLS_CA=./certs/ca.crt
+#VALORI_TLS_CERT=./certs/node.crt
+#VALORI_TLS_KEY=./certs/node.key

CONTRIBUTING.md

@@ -7,7 +7,7 @@ This guide gets you from a fresh clone to a running node in under 10 minutes.
 Run this once after cloning. It installs Rust, the wasm32 target, Python SDK, and UI dependencies, then builds the workspace:
 
 ```bash
-bash scripts/dev-setup.sh
+bash dev-setup.sh
 ```
 
 Works on macOS and Linux. If you prefer to install things manually, follow the steps below.
@@ -80,9 +80,9 @@ VALORI_EVENT_LOG_PATH=/tmp/valori-events.log \
 VALORI_SNAPSHOT_PATH=/tmp/valori.snap \
 cargo run -p valori-node
 
-# Custom port
+# Custom port (e.g. 8080 — default is 3000)
 VALORI_DIM=128 \
-VALORI_BIND=0.0.0.0:8080 \
+VALORI_BIND=0.0.0.0:3000 \
 cargo run -p valori-node
 
 # With embedding provider (enables POST /v1/ingest — chunk+embed+insert in one call)
@@ -139,7 +139,7 @@ maturin develop        # compiles and installs into your active Python env
 # Node.js 18+ required
 cd ui
 npm install
-npm run dev      # starts at http://localhost:4000
+npm run dev      # starts at http://localhost:3001
 ```
 
 The UI reverse-proxies API calls to the node, so **start the node first** (step 2). No extra config needed for local dev.

Makefile

@@ -21,9 +21,9 @@ check:
 test:
 	cargo test --workspace --exclude valori-embedded --exclude valori-ffi
 
-## Run a single standalone node as an HTTP server on 0.0.0.0:8080
+## Run a single standalone node as an HTTP server on 0.0.0.0:3000
 server:
-	VALORI_BIND=0.0.0.0:8080 cargo run --release -p valori-node
+	VALORI_BIND=0.0.0.0:3000 cargo run --release -p valori-node
 
 ## Bring up a 3-node Raft cluster in Docker
 cluster: