docs: add beginner-friendly quick start flow diagram (#951)

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`--export-rvf` no longer silently produces a placeholder model — PR #920.** The `--export-rvf` handler ran *before* `--train`/`--pretrain` and unconditionally wrote placeholder sine-wave weights, so the documented `--train … --export-rvf <path>` workflow short-circuited to a fake model and never trained (while printing "exported successfully"). It now emits the placeholder **container-format demo** only standalone (with a clear warning), and falls through to real training when `--train`/`--pretrain` is set; docs point to `--save-rvf` for the real model. 3 guard tests.
 
 ### Added
+- **Beginner-Friendly Quick Start Setup Flow Diagram — #951.** Added a visual Mermaid flowchart to `README.md` and `docs/readme-details.md` that guides new users and contributors through the setup options: Docker simulation, Python library integration, or live WiFi sensing using ESP32-S3/C6 hardware, optionally integrated with the Cognitum Seed system.
 - **ADR-151 per-room calibration & specialist training — full `baseline → enroll → extract → train` pipeline (new `wifi-densepose-calibration` crate).** "Teach the room before you teach the model": a local-first pipeline that turns a few minutes of clean human anchors — layered on the ADR-135 empty-room baseline — into a versioned bank of small, room-calibrated specialists for **presence, posture, breathing, heartbeat, restlessness, and anomaly**. Stages: guided enrollment with an adaptive quality gate (event-sourced `EnrollmentSession`, re-prompts bad anchors); feature extraction (autocorrelation periodicity in breathing/HR bands + variance/motion); six small specialists (learned threshold / nearest-prototype / band-limited periodicity / novelty); a `SpecialistBank` with baseline-drift **STALE** invalidation; and a `MixtureOfSpecialists` runtime with presence short-circuit + anomaly veto + confidence gating. Specialists are statistical heads today (runnable + hardware-validated); the frozen ADR-150 HF RF Foundation Encoder backbone is the documented upgrade path.
   - **CLI:** `enroll` / `train-room` / `room-status` / `room-watch`, plus the Stage-1 `calibrate-serve` HTTP API (CORS-enabled: `POST /start`, `GET /status`, `POST /stop`, `GET /result`, `GET /baselines`, `GET /health`) and a firewall-free `scripts/csi-udp-relay.py` for local Windows ESP32 testing without admin.
   - **Multistatic fusion (ADR-029):** `MultiNodeMixture` fuses several co-located nodes (each with its own room-calibrated bank) into one room state — presence OR'd across nodes, posture/breathing/heartbeat from the highest-confidence node, a single implausible node vetoes the room's vitals. Driven via `room-watch --node-bank N:path` (repeatable), which groups live frames by `node_id` and fuses. Same-room only; cross-room is federation (ADR-105).

README.md

@@ -74,6 +74,55 @@ RuView turns ordinary WiFi into a contactless sensor. A $9 ESP32 board reads the
 >
 > 🤗 **Pretrained weights**: download from [`ruvnet/wifi-densepose-pretrained`](https://huggingface.co/ruvnet/wifi-densepose-pretrained) — see [Loading the pretrained model](#loading-the-pretrained-model) below for one-command setup.
 
+## 🗺️ Quick Start Setup Flow
+
+Choose your path to get started with RuView:
+
+```mermaid
+graph TD
+    classDef default fill:#1e1e2e,stroke:#cdd6f4,stroke-width:1px,color:#cdd6f4;
+    classDef highlight fill:#f9e2af,stroke:#f9e2af,stroke-width:2px,color:#11111b;
+    classDef action fill:#a6e3a1,stroke:#a6e3a1,stroke-width:1px,color:#11111b;
+
+    Start([Start: Choose Your Goal]):::highlight
+    Start --> Goal{What is your goal?}
+
+    %% Goal paths
+    Goal -->|"Evaluation / Testing"| Docker["Option 1: Docker Simulation"]
+    Goal -->|"Python Library Integration"| Python["Option 4: Python PyPI Package"]
+    Goal -->|"Live WiFi Sensing"| SelectHW["Option 2/3: Live WiFi Sensing"]
+
+    %% Docker path
+    Docker --> DockRun["Run: docker run -p 3000:3000 ruvnet/wifi-densepose:latest"]:::action
+    DockRun --> ViewSim["View simulated data at http://localhost:3000"]:::action
+
+    %% Python path
+    Python --> PyInstall["Run: pip install ruview"]:::action
+    PyInstall --> PyCode["Integrate Breathing/HeartRate extractors in your code"]:::action
+    PyCode --> ViewOutput["Analyze/visualize CSI features"]:::action
+
+    %% Live Sensing / HW path
+    SelectHW --> HWChoice{Choose ESP32 Chip}
+    HWChoice -->|ESP32-S3| S3Node["Option 2a: ESP32-S3 Node"]
+    HWChoice -->|ESP32-C6| C6Node["Option 2b: ESP32-C6 WiFi 6 Node"]
+
+    S3Node --> Flash["Flash Firmware (esptool / idf.py)"]:::action
+    C6Node --> Flash
+
+    Flash --> Prov["Provision WiFi (provision.py)"]:::action
+    Prov --> SeedChoice{Do you have a Cognitum Seed?}
+
+    %% Seed choice
+    SeedChoice -->|Yes| Seed["Option 3: Full Cognitum System"]
+    SeedChoice -->|No| Mesh["ESP32 Mesh Mode"]
+
+    Seed --> SeedProc["Run: node scripts/rf-scan.js / processors"]:::action
+    SeedProc --> ViewUI["View live pose & vitals in RuView UI"]:::action
+
+    Mesh --> MeshDirect["Connect ESP32 directly to sensing-server / browser"]:::action
+    MeshDirect --> ViewUI
+```
+
 ```bash
 # Option 1: Docker (simulated data, no hardware needed)
 docker pull ruvnet/wifi-densepose:latest

docs/readme-details.md

@@ -472,6 +472,53 @@ All crates integrate with [RuVector v2.0.4](https://github.com/ruvnet/ruvector)
 
 ## 🚀 Quick Start
 
+Choose your setup path based on your goal:
+
+```mermaid
+graph TD
+    classDef default fill:#1e1e2e,stroke:#cdd6f4,stroke-width:1px,color:#cdd6f4;
+    classDef highlight fill:#f9e2af,stroke:#f9e2af,stroke-width:2px,color:#11111b;
+    classDef action fill:#a6e3a1,stroke:#a6e3a1,stroke-width:1px,color:#11111b;
+
+    Start([Start: Choose Your Goal]):::highlight
+    Start --> Goal{What is your goal?}
+
+    %% Goal paths
+    Goal -->|"Evaluation / Testing"| Docker["Option 1: Docker Simulation"]
+    Goal -->|"Python Library Integration"| Python["Option 4: Python PyPI Package"]
+    Goal -->|"Live WiFi Sensing"| SelectHW["Option 2/3: Live WiFi Sensing"]
+
+    %% Docker path
+    Docker --> DockRun["Run: docker run -p 3000:3000 ruvnet/wifi-densepose:latest"]:::action
+    DockRun --> ViewSim["View simulated data at http://localhost:3000"]:::action
+
+    %% Python path
+    Python --> PyInstall["Run: pip install ruview"]:::action
+    PyInstall --> PyCode["Integrate Breathing/HeartRate extractors in your code"]:::action
+    PyCode --> ViewOutput["Analyze/visualize CSI features"]:::action
+
+    %% Live Sensing / HW path
+    SelectHW --> HWChoice{Choose ESP32 Chip}
+    HWChoice -->|ESP32-S3| S3Node["Option 2a: ESP32-S3 Node"]
+    HWChoice -->|ESP32-C6| C6Node["Option 2b: ESP32-C6 WiFi 6 Node"]
+
+    S3Node --> Flash["Flash Firmware (esptool / idf.py)"]:::action
+    C6Node --> Flash
+
+    Flash --> Prov["Provision WiFi (provision.py)"]:::action
+    Prov --> SeedChoice{Do you have a Cognitum Seed?}
+
+    %% Seed choice
+    SeedChoice -->|Yes| Seed["Option 3: Full Cognitum System"]
+    SeedChoice -->|No| Mesh["ESP32 Mesh Mode"]
+
+    Seed --> SeedProc["Run: node scripts/rf-scan.js / processors"]:::action
+    SeedProc --> ViewUI["View live pose & vitals in RuView UI"]:::action
+
+    Mesh --> MeshDirect["Connect ESP32 directly to sensing-server / browser"]:::action
+    MeshDirect --> ViewUI
+```
+
 <details open>
 <summary><strong>First API call in 3 commands</strong></summary>