docs+plugins: rvAgent + RVF agentic-flow integration exploration

Land the rvAgent (vendor/ruvector/crates/rvAgent/) integration research
dossier and update both the Claude Code and Codex plugins so future
operators have a discoverable entry point for prototyping agentic flows
on top of RuView's existing sensing pipeline + RVF cognitive containers.

Added:
- docs/research/rvagent-rvf-integration/README.md
  Full integration thesis: rvAgent's 8 crates + 14 middlewares share
  RVF as their state-persistence format with RuView's existing
  v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs. Three
  shippable touchpoints (each independent):
    1. Two new RVF segment types (SEG_AGENT_STATE = 0x08,
       SEG_DECISION = 0x09) so rvAgent sessions and RuView sensing
       sessions interleave in one witness-bundle-attestable blob
    2. BfldEvent → ToolOutput shim — agent reads BFLD events as
       tool context with no new IPC
    3. cog-* subagent registration under a queen-agent router
  Open questions: workspace inclusion path, sync/async adapter
  placement, privacy-class composition with rvagent-middleware
  sanitizer, Soul Signature ↔ SoulMatchOracle bridge, MCP surface.
  Proposed next: ADR-124 before scaffolding wifi-densepose-agent.

- plugins/ruview/skills/ruview-rvagent/SKILL.md
  New Claude Code skill exposing the integration surface, links to
  the research doc, and lists the three shippable touchpoints. Skill
  description tuned so Claude auto-discovers it for queries like
  "wire rvAgent into RuView" or "operator agent reacting to BFLD."

- plugins/ruview/codex/prompts/ruview-rvagent.md
  Codex counterpart prompt with trigger phrasing, reading order,
  same three touchpoints + open questions, and the ADR-124 next step.

Modified:
- plugins/ruview/.claude-plugin/plugin.json
  Version 0.1.0 → 0.2.0; description extended to mention "BFLD
  privacy layer" and "rvAgent + RVF agentic flows".

- plugins/ruview/codex/AGENTS.md
  Prompt table grows one row: `ruview-rvagent` for the new prompt.

No code changes; no test impact.

Co-Authored-By: claude-flow <ruv@ruv.net>

docs/research/rvagent-rvf-integration/README.md

@@ -0,0 +1,113 @@
+# rvAgent + RVF integration for agentic flows in RuView
+
+**Status**: Research (Exploration) — Pre-Proposal
+**Date**: 2026-05-24
+**Author**: ruv
+
+---
+
+## TL;DR
+
+`vendor/ruvector/crates/rvAgent/` ships a production-grade Rust AI-agent framework with eight composable crates (`rvagent-core`, `-middleware`, `-tools`, `-subagents`, `-backends`, `-a2a`, `-acp`, `-mcp`, `-cli`). The framework already speaks **RVF cognitive containers** as its native state-persistence and inter-agent transport. RuView already uses RVF in `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs`.
+
+**Integration thesis**: the two systems share a serialization substrate. Wiring `rvAgent` swarms into RuView turns the existing sensing pipeline into the substrate that an agentic flow can read from, reason about, and respond to — without writing a new agent runtime.
+
+Concrete value:
+
+1. **Operator-facing agents** that interpret BFLD / pose / vitals events live ("the kitchen has had no presence for 6 h but the kettle stayed on — page the carer").
+2. **In-process subagent coordination** for the multi-cog Cognitum Seed appliance — `cog-pose-estimation`, `cog-person-count`, `cog-ha-matter`, and the new BFLD pipeline can negotiate via rvAgent's CRDT state merging instead of ad-hoc IPC.
+3. **Witness chains** (ADR-028 / ADR-110) get an upstream consumer — rvAgent's audit-trail middleware persists per-decision attestations into the same RVF container an operator already verifies.
+4. **Local SONA learning** — rvAgent's 3-loop adaptive learning slots in alongside the per-home RuVector thresholds already proposed in ADR-116, with the same in-RAM-only privacy posture BFLD enforces (ADR-118 I2).
+
+---
+
+## 1. What rvAgent ships
+
+| Crate | Role | Key types |
+|-------|------|-----------|
+| `rvagent-core` | State machine + COW state cloning + budget tracking | `AgentState`, `Message`, `AgiContainer`, `Arena`, `Budget`, `Graph` |
+| `rvagent-middleware` | 14 built-in middlewares (security, witness, sanitizer, sona, hnsw) | `PipelineConfig`, `build_default_pipeline()` |
+| `rvagent-tools` | Tool definitions + dispatch | `Tool`, `ToolInput`, `ToolOutput` |
+| `rvagent-subagents` | Spawn isolated subagents with O(1) state clone | `Subagent`, CRDT merge |
+| `rvagent-backends` | LLM provider abstraction (Anthropic, OpenAI, local) | `Backend` trait |
+| `rvagent-mcp` | MCP server integration | MCP-style tool registry |
+| `rvagent-a2a` / `-acp` | Agent-to-agent transport, agent communication protocol | wire format |
+| `rvagent-cli` | Operator CLI | argv parsing |
+
+Selling points relevant to RuView:
+
+- **O(1) state cloning via `Arc`** → can spawn one subagent per sensing zone without copying gigabytes of context.
+- **Parallel tool execution** → multiple sensor queries (BFLD presence, vitals BPM, pose) issued in parallel from one rvAgent decision step.
+- **Path confinement + env-var sanitization** → operator-facing agents that touch the host filesystem (e.g., reading `data/recordings/`) stay sandboxed.
+- **Witness chains** in `rvagent-middleware::witness` → already RVF-formatted; round-trips cleanly with ADR-028.
+
+## 2. What RVF already does in RuView
+
+`v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` defines the on-disk container format used for:
+
+- ADR-110 witness attestations (`SEG_MANIFEST`, `SEG_META`).
+- Soul Signature graphs (`docs/research/soul/specification.md` §3).
+- BFLD class-1 (derived) frames once the operator opts into research mode (ADR-118 §1.4).
+
+Each RVF blob is content-addressed (BLAKE3 of the canonical byte representation) and carries a typed segment manifest. The format is intentionally extension-friendly — segment types are `u8` enums, new types can land without breaking older readers.
+
+## 3. The integration surface
+
+Three concrete touchpoints, each shippable independently.
+
+### 3.1 RVF as the rvAgent ↔ RuView wire
+
+rvAgent's `AgiContainer` (`rvagent-core/src/agi_container.rs`, 627 LOC) already produces RVF-compatible blobs as its persistent state format. RuView only needs to define **two segment types** in `rvf_container.rs`:
+
+- `SEG_AGENT_STATE = 0x08` — serialized `rvagent_core::AgentState` (the cloned-on-write tree from `cow_state.rs`).
+- `SEG_DECISION = 0x09` — a single agent decision step: tool calls issued, outputs received, witness signature.
+
+With these two segments, an rvAgent session and a RuView sensing session can interleave entries in the same RVF blob. The witness-bundle script (ADR-028) iterates segments by type, so it would attest both halves with one signing pass.
+
+### 3.2 BFLD events as rvAgent tool inputs
+
+`wifi-densepose-bfld::BfldEvent` (iter 13) is already JSON-serializable via `to_json()`. Wrapping it as an `rvagent_tools::ToolOutput` is a 20-line shim: the agent issues a `read_bfld_state()` tool, the runtime returns the latest event JSON, the agent reasons over it. The full event surface (presence/motion/count/identity_risk/zone_id) becomes available as agent context without any new IPC.
+
+`BfldEvent → ToolOutput` mapping:
+```rust
+impl From<BfldEvent> for ToolOutput {
+    fn from(e: BfldEvent) -> Self {
+        ToolOutput::json(e.to_json().expect("BfldEvent JSON"))
+    }
+}
+```
+
+### 3.3 cog-* as rvAgent subagents
+
+`cog-pose-estimation`, `cog-person-count`, `cog-ha-matter`, and (proposed) `cog-bfld` already share a packaging convention (ADR-100). Each cog can register as a subagent with rvAgent's hub: the cog implements the `Subagent` trait, exports its tool surface, and inherits the parent agent's CRDT state. The queen agent (`rvagent-queen.md` persona) routes operator queries across the cog mesh.
+
+Concrete example:
+- Operator query: "is grandma awake yet?"
+- Queen agent fans out to: `cog-bfld` (presence in bedroom), `cog-quantum-vitals` (HR baseline shift), `cog-pose-estimation` (sitting/standing transition).
+- Each cog returns within budget; queen synthesizes the answer; witness chain logs the decision for compliance audit.
+
+## 4. Open questions
+
+1. **Workspace inclusion**: is `vendor/ruvector/crates/rvAgent/` already on the v2 workspace path, or does it need to be added as a path dep under `wifi-densepose-bfld` / a new `wifi-densepose-agent` crate?
+2. **Async runtime**: rvAgent backends are tokio-based. The BFLD `Publish` trait is intentionally sync (iter 22). A small adapter (sync `Publish` ↔ async `Backend`) probably belongs in a `wifi-densepose-agent` crate, not in BFLD itself.
+3. **Privacy class composition**: what's the rvAgent equivalent of BFLD's `PrivacyClass`? `rvagent-middleware::sanitizer` strips at the tool-output boundary; should it consume `PrivacyClass` from the originating BFLD event so the agent never even sees a class-3 identity field?
+4. **Soul Signature interaction**: rvAgent's `SoulMatchOracle` integration (ADR-121 §2.6) could be the bridge from the Soul Signature graph (`docs/research/soul/`) to the agent decision layer. Worth a dedicated sub-section.
+5. **MCP**: `rvagent-mcp` exposes tools to external MCP clients. Should the BFLD `BfldPipelineHandle::send` surface land as an MCP tool here, or stay private to in-process rvAgent flows?
+
+## 5. Proposed next steps (decision deferred)
+
+- **D1**: Open ADR-124 — "rvAgent + RVF integration for RuView agentic flows" — capturing the segment-type assignments, the cog-subagent contract, and the privacy-class composition rule.
+- **D2**: Scaffold `v2/crates/wifi-densepose-agent` with the sync ↔ async adapter and one example tool (`read_bfld_state`).
+- **D3**: Add `SEG_AGENT_STATE` and `SEG_DECISION` to `rvf_container.rs` as `#[cfg(feature = "agent")]` segments so the v0 ship doesn't pull rvAgent's transitive deps by default.
+- **D4**: Land a one-page demo in `examples/agent-bedroom-check/` showing the queen-agent flow end-to-end against the `BfldPipelineHandle`.
+
+## 6. References
+
+- rvAgent: `vendor/ruvector/crates/rvAgent/README.md`, `rvagent-core/src/agi_container.rs`, `rvagent-middleware/docs/UNICODE_SECURITY.md`
+- Agent personas: `vendor/ruvector/crates/rvAgent/.ruv/agents/{rvagent-coder,rvagent-queen,rvagent-tester,rvagent-security}.md`
+- RVF container: `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs`
+- ADR-028 (witness): `docs/adr/ADR-028-esp32-capability-audit.md`
+- ADR-100 (cog packaging), ADR-110 (witness chain), ADR-116 (cog-ha-matter)
+- ADR-118 (BFLD): `docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md`
+- Soul Signature: `docs/research/soul/specification.md`
+- BFLD impl branch: `feat/adr-118-bfld-impl`, currently at iter 25 (`e8b4fdbc8`)

plugins/ruview/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruview",
-  "description": "End-to-end RuView (WiFi-DensePose) toolkit for Claude Code: onboarding, ESP32 hardware setup, configuration, sensing applications, model training, advanced multistatic sensing, and witness verification — from practical to advanced.",
-  "version": "0.1.0",
+  "description": "End-to-end RuView (WiFi-DensePose) toolkit for Claude Code: onboarding, ESP32 hardware setup, configuration, sensing applications, model training, advanced multistatic sensing, witness verification, BFLD privacy layer, and rvAgent + RVF agentic flows — from practical to advanced.",
+  "version": "0.2.0",
   "author": {
     "name": "ruvnet",
     "url": "https://github.com/ruvnet/RuView"

plugins/ruview/codex/AGENTS.md

@@ -47,6 +47,7 @@ After significant changes: run the Rust tests + Python proof, then `bash scripts
 | `ruview-app` | Run a sensing application (presence / vitals / pose / sleep / MAT / point cloud) |
 | `ruview-train` | Train / evaluate / publish a model (incl. GPU on GCloud) |
 | `ruview-verify` | Run the trust pipeline + pre-merge checklist |
+| `ruview-rvagent` | Explore rvAgent + RVF agentic flows wiring into RuView |
 
 Install: copy `codex/prompts/*.md` into `~/.codex/prompts/`, or run Codex with this directory on its prompt path.
 

plugins/ruview/codex/prompts/ruview-rvagent.md

@@ -0,0 +1,36 @@
+# ruview-rvagent — explore rvAgent + RVF agentic flows for RuView
+
+You are helping the operator explore or prototype the integration of `vendor/ruvector/crates/rvAgent/` (a production Rust AI-agent framework) with RuView's existing sensing pipeline (`v2/crates/wifi-densepose-*`) and the RVF cognitive container format (`v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs`).
+
+## Trigger phrasing
+
+- "wire rvAgent into RuView"
+- "I want a queen agent that fans out to cog-pose-estimation and cog-bfld"
+- "persist agent decisions in the same witness bundle as sensing events"
+- "how do I keep agent outputs class-3 compliant?"
+
+## What to read first
+
+1. `docs/research/rvagent-rvf-integration/README.md` — full integration thesis, open questions, next steps.
+2. `vendor/ruvector/crates/rvAgent/README.md` — what rvAgent ships (8 crates, 14 middlewares).
+3. `vendor/ruvector/crates/rvAgent/.ruv/agents/rvagent-queen.md` — queen-agent persona that coordinates cog subagents.
+4. `v2/crates/wifi-densepose-bfld/src/{event.rs,pipeline_handle.rs}` — the BFLD event surface and the operator-facing handle that an agent would call.
+5. `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` — segment types; `SEG_AGENT_STATE = 0x08` and `SEG_DECISION = 0x09` are the proposed additions.
+
+## Three shippable touchpoints (each independent)
+
+1. **RVF wire** — add `SEG_AGENT_STATE` + `SEG_DECISION` segments so rvAgent and RuView sessions can interleave in one blob (witness-bundle covers both halves).
+2. **Tool shim** — `BfldEvent::to_json()` already exists; wrap as `rvagent_tools::ToolOutput`.
+3. **Cog subagents** — register `cog-pose-estimation`, `cog-person-count`, `cog-ha-matter`, (proposed) `cog-bfld` under the queen via the `Subagent` trait.
+
+## Open questions to surface
+
+- Is `vendor/ruvector/crates/rvAgent/` on the v2 workspace path?
+- Sync ↔ async adapter location (BFLD `Publish` is sync; rvAgent backends are tokio).
+- Privacy-class composition — does `rvagent-middleware::sanitizer` consume `BfldEvent::privacy_class`?
+- Soul Signature ↔ `SoulMatchOracle` bridge (ADR-121 §2.6).
+- Should `BfldPipelineHandle::send` land as a public MCP tool via `rvagent-mcp`?
+
+## Suggested next action
+
+Draft ADR-124 — "rvAgent + RVF integration for RuView agentic flows" — capturing segment assignments, cog-subagent contract, and privacy-class composition. Land **before** scaffolding `v2/crates/wifi-densepose-agent`.

plugins/ruview/skills/ruview-rvagent/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: ruview-rvagent
+description: Explore and prototype rvAgent + RVF integration for RuView agentic flows. Use when working on cross-cog coordination, operator-facing agents reading BFLD / pose / vitals events live, or persisting agent state alongside sensing data in the same RVF container.
+---
+
+# RuView rvAgent + RVF integration
+
+Surface area for wiring `vendor/ruvector/crates/rvAgent/` into RuView so the existing sensing pipeline becomes the substrate an agentic flow can read, reason about, and respond to.
+
+## When to use this skill
+
+- "I want an agent that reacts to BFLD presence in the kitchen and pages the carer."
+- "I need cog-pose-estimation and cog-bfld to negotiate before publishing a synthesized event."
+- "Can the witness chain attest both the sensing event AND the agent decision in one RVF blob?"
+- "How do we keep rvAgent's tool outputs class-3 compliant when the source BFLD event is Restricted?"
+
+## Key surfaces
+
+| Surface | File | Notes |
+|---------|------|-------|
+| rvAgent core | `vendor/ruvector/crates/rvAgent/rvagent-core/src/agi_container.rs` (627 LOC) | RVF-compatible state container |
+| rvAgent middleware | `vendor/ruvector/crates/rvAgent/rvagent-middleware/` | Witness, sanitizer, SONA, HNSW |
+| Agent personas | `vendor/ruvector/crates/rvAgent/.ruv/agents/rvagent-{queen,coder,tester,security}.md` | Reference patterns |
+| RVF container | `v2/crates/wifi-densepose-sensing-server/src/rvf_container.rs` | Add `SEG_AGENT_STATE`, `SEG_DECISION` |
+| BFLD event | `v2/crates/wifi-densepose-bfld/src/event.rs` | `BfldEvent::to_json()` → `ToolOutput` |
+| BFLD pipeline handle | `v2/crates/wifi-densepose-bfld/src/pipeline_handle.rs` | `BfldPipelineHandle::send` |
+
+## Research dossier
+
+Full integration analysis lives at `docs/research/rvagent-rvf-integration/README.md`.
+
+Three shippable touchpoints, each independent:
+
+1. **RVF wire**: two new segment types (`SEG_AGENT_STATE = 0x08`, `SEG_DECISION = 0x09`) let rvAgent sessions interleave with RuView sensing sessions in the same blob.
+2. **Tool surface**: `BfldEvent → ToolOutput` shim turns BFLD events into agent context with no new IPC.
+3. **Cog subagents**: `cog-pose-estimation` / `cog-person-count` / `cog-ha-matter` / `cog-bfld` register as rvAgent subagents under a queen-agent router.
+
+## Open questions
+
+- Workspace inclusion of `vendor/ruvector/crates/rvAgent/` (path dep vs published crate)
+- Sync ↔ async adapter (BFLD `Publish` is sync, rvAgent backends are tokio)
+- Privacy-class composition (does rvAgent's sanitizer consume `PrivacyClass`?)
+- Soul Signature ↔ `SoulMatchOracle` bridge
+- Whether `BfldPipelineHandle::send` lands as a public MCP tool via `rvagent-mcp`
+
+## Next decision
+
+ADR-124 (proposed) — "rvAgent + RVF integration for RuView agentic flows" — would capture segment assignments, cog-subagent contract, and the privacy-class composition rule. Land before scaffolding `v2/crates/wifi-densepose-agent`.