From 8b857e41cd4be3395e7601cee36a0c850d4b6472 Mon Sep 17 00:00:00 2001 From: ruv Date: Thu, 1 Oct 2026 17:26:40 -0400 Subject: [PATCH] docs: README and user guide for @ruvnet/ruview 0.9.0 (devices, radar, MCP/ChatGPT, Claude Code mod) - README MetaHarness section pinned to 0.9.0 with the hardware, MCP-over-HTTP, mod, Homecore and kernel commands; plugin section lists the ruview-live mod. - User guide: new "RuView npm toolkit" section (hardware CLI, alert meanings, ESPHome kits, MCP/ChatGPT connection, the /ruview mod, Homecore + kernel), TOC entry, 0.5.0 pins updated. Co-Authored-By: claude-flow --- README.md | 63 +++++++++++++----- docs/user-guide.md | 156 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 201 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 5233dcd77..b2766b97b 100644 --- a/README.md +++ b/README.md @@ -40,29 +40,56 @@ Every WiFi router already fills your space with radio waves. When people move, b
RuView MetaHarness — guided operation for humans and AI agents -The RuView-specific metaharness we created is published as [`@ruvnet/ruview`](harness/ruview/README.md). It provides source-cited guidance, guarded Claude Code/Codex agents, deterministic verification, an honesty check for accuracy claims, and an explicitly granted OAuth-only Cognitum Spaces read. +The RuView-specific metaharness we created is published as [`@ruvnet/ruview`](harness/ruview/README.md). It provides: +- source-cited guidance; +- device access for CSI nodes, radar and LiDAR; +- firmware flashing with boot evidence; +- one MCP server, usable over stdio or HTTP for ChatGPT, with a live console widget; +- a Claude Code mod; +- guarded Claude Code/Codex agents; +- deterministic verification; +- an honesty check for accuracy claims. + +Companion packages: [`homecore`](harness/homecore/README.md) (Homecore developer metaharness) and [`@ruvnet/ruview-kernel`](harness/ruview-kernel/README.md) (the vitals pipeline as WASM). ```bash # Check the local setup and get source-cited guidance -npx @ruvnet/ruview@0.4.0 doctor -npx @ruvnet/ruview@0.4.0 guidance --topic sensing --query "model loading" +npx @ruvnet/ruview@0.9.0 doctor +npx @ruvnet/ruview@0.9.0 guidance --topic sensing --query "model loading" + +# Hardware: what is plugged in, live CSI from your nodes, a 60 GHz radar kit +npx @ruvnet/ruview@0.9.0 devices +npx @ruvnet/ruview@0.9.0 esp32 --watch # ESP32 + Realtek RAC1 nodes, live view +npx @ruvnet/ruview@0.9.0 esp32 --seconds 45 --analyze # live CSI through the vitals kernel +npx @ruvnet/ruview@0.9.0 mmwave --source esphome --host + +# Agents: MCP over stdio, or over HTTP for ChatGPT (token-protected, read tools only) +npx @ruvnet/ruview@0.9.0 mcp start +RUVIEW_MCP_GRANTS=device-access npx @ruvnet/ruview@0.9.0 mcp start --http + +# Claude Code: a live sensing pane (/ruview), shipped in the package +npx @ruvnet/ruview@0.9.0 mod # Run a read-only RuView agent through Codex -npx @ruvnet/ruview@0.4.0 agent run --host codex --repo . \ +npx @ruvnet/ruview@0.9.0 agent run --host codex --repo . \ --prompt "Find the nearest tests and cite the source files" -# Search or verify the reviewed contributor brain -npx @ruvnet/ruview@0.4.0 brain search --query "calibration" -npx @ruvnet/ruview@0.4.0 brain verify --repo . - -# Check claims, replay the deterministic proof, or expose the MCP server -npx @ruvnet/ruview@0.4.0 claim-check --file REPORT.md -npx @ruvnet/ruview@0.4.0 verify -npx @ruvnet/ruview@0.4.0 spaces -npx @ruvnet/ruview@0.4.0 mcp start +# Check claims, replay the deterministic proof, search the reviewed brain +npx @ruvnet/ruview@0.9.0 claim-check --file REPORT.md +npx @ruvnet/ruview@0.9.0 verify +npx @ruvnet/ruview@0.9.0 brain search --query "calibration" ``` -Agent runs are read-only by default. Workspace writes require both `--allow-write` and `--confirm`; retrieved brain content is evidence, not authority. +**Safety:** +- Agent runs are read-only by default. Workspace writes require both `--allow-write` and `--confirm`. +- Hardware reads need the `device-access` grant. +- Flashing and calibration never run over the HTTP transport. +- Device-reported vitals are labelled as unvalidated. +- Retrieved brain content is evidence, not authority. + +A single `npx ruview` package bundling all of this is ready (ADR-376). It is waiting on npm to release the unscoped name. + +Full walkthrough: [user guide → RuView npm toolkit](docs/user-guide.md#ruview-npm-toolkit-ruvnetruview).
@@ -694,7 +721,13 @@ claude --plugin-dir ./plugins/ruview Verify the plugin structure: `bash plugins/ruview/scripts/smoke.sh`. Full details: [`plugins/ruview/README.md`](plugins/ruview/README.md). -For the portable RuView MetaHarness, use `npx @ruvnet/ruview@0.4.0`; the quick commands and fuller explanation are in the collapsed MetaHarness section near the top of this README and in [`harness/ruview/`](harness/ruview/README.md). +**Live sensing pane (Claude Code mod):** the same marketplace also lists `ruview-live`, a Claude Code mod. +- Install it with `/plugin install ruview-live@ruview`, or run `npx @ruvnet/ruview@0.9.0 mod` for its path inside the npm package. +- `/ruview` opens a pane beside the transcript with your CSI nodes and radar, refreshed on a timer, plus a one-line status. +- It is read-only. +- Mods are early access; if `/ruview` is missing, start Claude Code with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`. See [ADR-377](docs/adr/ADR-377-ruview-live-claude-code-mod.md). + +For the portable RuView MetaHarness, use `npx @ruvnet/ruview@0.9.0`. The quick commands and a fuller explanation are in the collapsed MetaHarness section near the top of this README, in [`harness/ruview/`](harness/ruview/README.md), and in the [user guide](docs/user-guide.md#ruview-npm-toolkit-ruvnetruview). diff --git a/docs/user-guide.md b/docs/user-guide.md index da59d4a9e..9ef05425f 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -26,7 +26,12 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation - [Cognitum Seed Integration (ADR-069)](#cognitum-seed-integration-adr-069) 5. [REST API Reference](#rest-api-reference) 6. [WebSocket Streaming](#websocket-streaming) -7. [Web UI](#web-ui) +7. [RuView npm toolkit (`@ruvnet/ruview`)](#ruview-npm-toolkit-ruvnetruview) + - [Hardware from the command line](#hardware-from-the-command-line) + - [MCP for agents, ChatGPT and MCP Apps](#mcp-for-agents-chatgpt-and-mcp-apps) + - [Claude Code mod: live sensing pane](#claude-code-mod-live-sensing-pane) + - [Homecore and the vitals kernel](#homecore-and-the-vitals-kernel) +8. [Web UI](#web-ui) 8. [Vital Sign Detection](#vital-sign-detection) 9. [CLI Reference](#cli-reference) 10. [Observatory Visualization](#observatory-visualization) @@ -451,8 +456,8 @@ authority. Versioned collections are `sites`, `buildings`, `floors`, The dependency-free contributor harness exposes the same read path: ```bash -npx @ruvnet/ruview@0.5.0 spaces --resource alerts --limit 25 -npx @ruvnet/ruview@0.5.0 mcp start +npx @ruvnet/ruview@0.9.0 spaces --resource alerts --limit 25 +npx @ruvnet/ruview@0.9.0 mcp start ``` Its MCP tool is `ruview_spaces_list`. MCP reads are OAuth-only, use the fixed @@ -958,6 +963,151 @@ Source: [`tools/ruview-mcp/`](../tools/ruview-mcp/README.md). Tracking issue: [# --- +## RuView npm toolkit (`@ruvnet/ruview`) + +`@ruvnet/ruview` is RuView's operator toolkit on npm. It has no runtime +dependencies and runs on Node 20+. It is tested on Windows and Linux. One tool +registry serves: +- a CLI; +- an MCP server (stdio, or HTTP for ChatGPT); +- a typed SDK; +- a Claude Code mod. + +Every result is honest about what it is: +- **MEASURED** when it comes from live packets on your machine; +- **SYNTHETIC** for simulators and self-tests; +- **device-reported** for values a radar's own firmware computes, which are + not validated against a reference. + +```bash +npx @ruvnet/ruview@0.9.0 --help +npx @ruvnet/ruview@0.9.0 doctor # what works on this machine, with fixes +``` + +In a terminal, commands print a formatted view. Pipes and `--json` print JSON, +for scripts. + +### Hardware from the command line + +Run these on the machine the hardware is plugged into. + +```bash +# What is plugged in (USB VID:PID → ESP32, Realtek RTL8721Dx, radar, LiDAR) +npx @ruvnet/ruview@0.9.0 devices + +# CSI nodes streaming to this machine (UDP 5005): ESP32 ADR-018 frames and +# Realtek RAC1 frames, per node rate, loss, RSSI and CSI shape +npx @ruvnet/ruview@0.9.0 esp32 --seconds 10 +npx @ruvnet/ruview@0.9.0 esp32 --watch # live view, redrawn every few seconds +npx @ruvnet/ruview@0.9.0 esp32 --seconds 45 --analyze # live CSI through the vitals kernel + +# A board's serial console, without resetting it +npx @ruvnet/ruview@0.9.0 monitor --port COM9 +npx @ruvnet/ruview@0.9.0 monitor --port COM10 --baud 1500000 # Realtek Ameba + +# 60 GHz / 24 GHz radar: raw UART, or an ESPHome kit on your network +npx @ruvnet/ruview@0.9.0 mmwave --port COM5 --model auto +npx @ruvnet/ruview@0.9.0 mmwave --source esphome --host 192.168.1.50 + +# Flash ESP32 firmware: plan first, then write with --confirm (records boot evidence) +npx @ruvnet/ruview@0.9.0 flash-plan --port COM16 --bundle firmware/esp32-csi-node/release_bins/c6-adr110 --variant c6 +npx @ruvnet/ruview@0.9.0 flash --port COM16 --bundle firmware/esp32-csi-node/release_bins/c6-adr110 --variant c6 --confirm +``` + +**What the alerts mean:** + +| Alert | Meaning | +|---|---| +| `heartbeat-only sender` | A board is alive but sends no CSI. On a Realtek board, run `monitor --baud 1500000`. If it shows `lack of csi buf`, the board ran out of CSI report buffers (`csi_buffer_starvation`). Reset it. | +| `port_in_use` | The sensing server already holds UDP 5005. Stop it, or capture on another port your nodes target. | +| `no_decodable_packets` | Packets arrived, but none were in a known RuView format. Check the sender. | +| `seqReordered` / `seqStrays` | Out-of-order or stray sequence numbers. These are not counted as loss. | + +**ESPHome radar kits** (for example the Seeed MR60BHA2): the kit's firmware +owns the radar, so read it over the network with `--source esphome`. +- If the kit cannot join your WiFi, it starts a fallback hotspot. Join it and + set your network in its captive portal, at `http://192.168.4.1`. +- Only private-network addresses are accepted. +- Encrypted or password-protected ESPHome APIs are reported as unsupported. + +### MCP for agents, ChatGPT and MCP Apps + +```bash +# Claude Code, Codex or any MCP client (stdio) +claude mcp add ruview -- npx -y @ruvnet/ruview@0.9.0 mcp start + +# HTTP, for ChatGPT and remote clients +export RUVIEW_MCP_TOKEN="$(node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))")" +RUVIEW_MCP_GRANTS=device-access npx @ruvnet/ruview@0.9.0 mcp start --http --port 8790 +``` + +**Connecting ChatGPT.** Clients that can send headers use +`Authorization: Bearer `. ChatGPT connectors cannot, so: +1. Expose the port over HTTPS, with a tunnel or reverse proxy. +2. Add `https:///mcp/` as the connector URL. + +**Least authority:** +- Hardware tools need the `device-access` grant. +- The HTTP transport binds to localhost by default. +- It refuses unknown browser origins. +- It never allows flashing or calibration, whatever grants are set. + +Node captures, radar reads, device scans and doctor results render in the +**RuView console**: a widget that ChatGPT and other MCP Apps hosts show inline, +with a Refresh button that re-runs the tool. + +### Claude Code mod: live sensing pane + +The package ships `ruview-live`, a Claude Code mod. `/ruview` opens a pane +beside the conversation, refreshed on a timer, showing: +- your CSI nodes; +- an optional ESPHome radar; +- alerts. + +It also keeps a status line such as `RuView · 2 nodes · radar present`. + +```bash +npx @ruvnet/ruview@0.9.0 mod # prints the mod's path in your install and how to load it +claude --plugin-dir "" # try it for one session +# or from the RuView marketplace, inside Claude Code: +# /plugin marketplace add ruvnet/RuView +# /plugin install ruview-live@ruview +``` + +| In Claude Code | Does | +|---|---| +| `/ruview` | Open or close the pane | +| `/ruview refresh` | Run one capture now; the result goes in the status line | +| `/ruview off` | Close the pane | + +**Settings** (`claude plugin configure ruview-live`): `udpPort`, `radarHost`, +`refreshSeconds` and `captureSeconds`. + +The mod only runs the package's read-only CLI commands. Mods are early access: +if `/ruview` is missing, start Claude Code with +`CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1`. + +### Homecore and the vitals kernel + +```bash +npx homecore@0.1.0 guidance --topic plugins --query Wasmtime # Homecore developer metaharness +npx @ruvnet/ruview-kernel@0.1.0 selftest # vitals pipeline as WASM (SYNTHETIC self-test) +``` + +`esp32 --analyze` uses the kernel when it is installed. Its heart and breathing +estimates carry "no reference measurement": they show the signal path works, +not that the readings are accurate. + +Design records: +- [ADR-373](adr/ADR-373-host-device-access-layer.md): device access; +- [ADR-375](adr/ADR-375-ruview-mcp-apps-console-http-transport-and-terminal-ui.md): + MCP Apps console, HTTP transport and terminal UI; +- [ADR-376](adr/ADR-376-ruview-umbrella-npm-package.md): the one-install + `ruview` package, pending the npm name; +- [ADR-377](adr/ADR-377-ruview-live-claude-code-mod.md): the Claude Code mod. + +--- + ## Web UI The built-in Three.js UI is served at `http://localhost:3000/ui/` (Docker) or the configured HTTP port.