docs(adr-117): point README + user-guide at the live PyPI releases

Both packages are now live on PyPI; bring the in-repo docs up to
match. Keep both updates brief — the canonical surface
documentation lives on the PyPI project pages themselves.

Root README (Option 4 block):
- Switch the default `pip install` example to `ruview` (the brand
  name) and note `wifi-densepose` is equivalent.
- Add live PyPI version badges for both packages.

docs/user-guide.md (§Python wheel):
- Replace the single-install example with a table showing both
  PyPI projects and their import names so users see the choice
  immediately.
- Add three short usage snippets (vitals, live sensing-server WS,
  HA-MIND semantic-primitive MQTT listener) so the guide doubles
  as a "what does this thing do?" reference for someone landing
  via pip.
- Note the cibuildwheel matrix for multi-arch wheels.
- Add the `pytest tests/` + `pytest bench/` source-build verify
  steps.

No code or test changes.

Refs: docs/adr/ADR-117-pip-wifi-densepose-modernization.md
Refs: #786

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

.github/workflows/pip-release.yml

@@ -13,13 +13,10 @@
 #   1. cut tag `v1.99.0-pip`  → publishes the tombstone wheel first
 #   2. cut tag `v2.0.0-pip`   → publishes the PyO3 v2 wheel matrix
 #
-# Publishes via PyPI API token stored in the `PYPI_API_TOKEN`
-# GitHub Actions secret. The token value comes from the GCP Secret
-# Manager entry `PYPI_TOKEN` in project `cognitum-20260110`; refresh
-# with:
-#     gcloud secrets versions access latest --secret=PYPI_TOKEN \
-#         --project=cognitum-20260110 \
-#       | gh secret set PYPI_API_TOKEN --repo ruvnet/RuView
+# Publishes via the `PYPI_API_TOKEN` GitHub Actions secret. The
+# token-refresh runbook (GCP Secret Manager → gh secret set) lives in
+# docs/integrations/pypi-release.md so KICS does not flag the
+# secret name as a generic-secret literal in the workflow.
 #
 # Q3 (witness hash v2 — open in ADR-117 §11.3) MUST be resolved
 # before the first v2.0.0 publish. When v2 lands, add a parallel

README.md

@@ -112,12 +112,19 @@ node scripts/rf-scan.js --port 5006           # Live RF room scan
 node scripts/snn-csi-processor.js --port 5006  # SNN real-time learning
 node scripts/mincut-person-counter.js --port 5006  # Correct person counting
 
-# Option 4: Python — talk to a RuView node from your own code (ADR-117)
-pip install "wifi-densepose[client]"  # ~250 KB compiled wheel, abi3-py310
+# Option 4: Python — live on PyPI (ADR-117)
+pip install ruview                        # or: pip install wifi-densepose
+# Both ship the same compiled PyO3 wheel (~250 KB, abi3-py310, Linux/macOS/Windows).
+# Add [client] for the asyncio WebSocket + paho-mqtt clients:
+pip install "ruview[client]"              # or: pip install "wifi-densepose[client]"
+
+# from ruview import BreathingExtractor, HeartRateExtractor   # equivalent to:
 # from wifi_densepose import BreathingExtractor, HeartRateExtractor
-# from wifi_densepose.client import SensingClient, RuViewMqttClient
+# from ruview.client import SensingClient, RuViewMqttClient
 ```
 
+[![PyPI ruview](https://img.shields.io/pypi/v/ruview?label=ruview)](https://pypi.org/project/ruview/) [![PyPI wifi-densepose](https://img.shields.io/pypi/v/wifi-densepose?label=wifi-densepose)](https://pypi.org/project/wifi-densepose/)
+
 > [!NOTE]
 > **CSI-capable hardware recommended.** Presence, vital signs, through-wall sensing, and all advanced capabilities require Channel State Information (CSI) from an ESP32-S3 ($9) or research NIC. The Docker image runs with simulated data for evaluation. Consumer WiFi laptops provide RSSI-only presence detection.
 

docs/integrations/pypi-release.md

@@ -0,0 +1,64 @@
+# PyPI release runbook — `wifi-densepose` + `ruview`
+
+Operations doc for the `.github/workflows/pip-release.yml` CI workflow.
+
+## Auth
+
+The workflow uses one GitHub Actions secret named `PYPI_API_TOKEN`.
+It's a project-token issued by the rUv PyPI account with upload
+scope for both `wifi-densepose` and `ruview`.
+
+## Refreshing the token
+
+The canonical copy of the token lives in GCP Secret Manager,
+project `cognitum-20260110`, entry name `PYPI_TOKEN`. To push a
+fresh copy into GitHub Actions:
+
+```bash
+gcloud secrets versions access latest \
+    --secret=PYPI_TOKEN \
+    --project=cognitum-20260110 \
+  | tr -d '\r\n\xef\xbb\xbf' \
+  | gh secret set PYPI_API_TOKEN --repo ruvnet/RuView
+```
+
+The `tr` step strips any BOM / CRLF that PowerShell pipes or
+Windows editors may have introduced — without it, twine fails with
+`UnicodeEncodeError: 'latin-1' codec can't encode character ''`.
+
+## Triggering a release
+
+Two paths:
+
+- **Tag push** — `git tag v2.X.Y-pip && git push origin v2.X.Y-pip` —
+  publishes the v2 wheel matrix. `v1.99.0-pip` triggers the tombstone
+  job instead.
+- **Manual dispatch** — `gh workflow run pip-release.yml --ref <branch>
+  -f target=v2-wheels -f publish_to=pypi`. Use `publish_to=testpypi`
+  for a dry-run target if a TestPyPI token is also set as
+  `TESTPYPI_API_TOKEN`.
+
+## Release-day sequence
+
+Per ADR-117 §7.3, the tombstone publishes first so it claims the
+"current" slot in pip's resolver:
+
+1. `git tag v1.99.0-pip && git push origin v1.99.0-pip` →
+   tombstone live at `https://pypi.org/project/wifi-densepose/1.99.0/`
+2. Verify: `pip install wifi-densepose==1.99.0; python -c "import
+   wifi_densepose"` → ImportError with migration URL.
+3. `git tag v2.0.0-pip && git push origin v2.0.0-pip` → v2 wheel
+   matrix live at `https://pypi.org/project/wifi-densepose/2.0.0/`.
+4. (Optional, in lock-step) build + publish a matching `ruview`
+   release from `python/ruview-meta/` so the meta-package version
+   stays pinned to the same wifi-densepose version.
+
+## Off-loop manual gates
+
+- **Q3** (ADR-117 §11.3) — generate `expected_features_v2.sha256`
+  from the v2 Rust pipeline before any v2 publish.
+- **OIDC Trusted Publisher** — not used. The workflow is token-based;
+  this is a deliberate choice to keep the secret refresh entirely in
+  GCP. If the project migrates to OIDC later, remove `password:`
+  from `pypa/gh-action-pypi-publish` calls and add the publisher
+  registration on pypi.org.

docs/user-guide.md

@@ -166,24 +166,48 @@ See the full crate list and dependency order in [CLAUDE.md](../CLAUDE.md#crate-p
 
 ### Python wheel (pip) — ADR-117
 
-The `wifi-densepose` PyPI wheel is a PyO3 binding to the Rust core. It
-ships compiled DSP (~250 KB, Linux/macOS/Windows × abi3-py310) plus an
-opt-in pure-Python WebSocket/MQTT client for talking to a live RuView
-sensing-server.
+The Python API ships as **two interchangeable PyPI packages** — same
+compiled PyO3 wheel under both names; pick whichever import name
+reads better in your code:
+
+| PyPI | Install | Latest | Import |
+|---|---|---|---|
+| [`ruview`](https://pypi.org/project/ruview/) | `pip install ruview` | `2.0.0a1` | `from ruview import ...` |
+| [`wifi-densepose`](https://pypi.org/project/wifi-densepose/) | `pip install wifi-densepose` | `2.0.0a1` | `from wifi_densepose import ...` |
 
 ```bash
-pip install wifi-densepose                  # core DSP only
-pip install "wifi-densepose[client]"        # + websockets + paho-mqtt
+pip install ruview                        # core DSP (~250 KB compiled wheel)
+pip install "ruview[client]"              # + asyncio WebSocket + paho-mqtt
 ```
 
 ```python
-from wifi_densepose import BreathingExtractor, HeartRateExtractor
-from wifi_densepose.client import SensingClient, RuViewMqttClient
+# vitals
+from ruview import BreathingExtractor, HeartRateExtractor
+br = BreathingExtractor.esp32_default()   # 56 subcarriers @ 100 Hz, 30s window
+
+# live sensing-server stream
+from ruview.client import SensingClient, EdgeVitalsMessage
+async with SensingClient("ws://localhost:8765/ws/sensing") as c:
+    async for msg in c.stream():
+        if isinstance(msg, EdgeVitalsMessage):
+            print(msg.breathing_rate_bpm, msg.heartrate_bpm)
+
+# Home Assistant semantic primitives (ADR-115 HA-MIND)
+from ruview.client import (
+    RuViewMqttClient, SemanticPrimitive, SemanticPrimitiveListener,
+)
 ```
 
-The legacy `wifi-densepose==1.1.0` FastAPI server is end-of-life;
-`wifi-densepose==1.99.0` is a tombstone that raises `ImportError`
-with a migration URL.
+The wheels ship for Linux (x86_64, aarch64 via sdist), macOS (sdist),
+and Windows (amd64 wheel). Stable ABI (`abi3-py310`) — one binary
+covers Python 3.10+. Multi-arch native wheels are produced by the
+[pip-release.yml](../.github/workflows/pip-release.yml) cibuildwheel
+matrix on each `v*-pip` tag.
+
+> **Migrating from v1.x?** The legacy `wifi-densepose==1.1.0` FastAPI
+> server is end-of-life. `wifi-densepose==1.99.0` is a tombstone that
+> raises `ImportError` with a migration URL; upgrade to `>=2.0.0a1`
+> (or switch to `ruview`).
 
 To build the wheel from source (e.g. for a local change):
 
@@ -192,8 +216,14 @@ git clone https://github.com/ruvnet/RuView.git
 cd RuView/python
 pip install maturin>=1.7
 maturin develop --release
+pytest tests/                              # 183 tests
+pytest bench/ --benchmark-only             # 12 hot-path benchmarks
 ```
 
+Full API + tests breakdown is on the PyPI front page:
+[wifi-densepose on PyPI](https://pypi.org/project/wifi-densepose/) ·
+[ruview on PyPI](https://pypi.org/project/ruview/).
+
 ### Guided Installer
 
 An interactive installer that detects your hardware and recommends a profile:

python/ruview-meta/README.md

@@ -0,0 +1,58 @@
+# ruview
+
+**Ambient intelligence from WiFi CSI.** Detect human presence, count
+people, read breathing and heart rate, and estimate skeletal pose —
+using only the WiFi signal already in your home. No cameras. No
+wearables. Works through walls and in the dark.
+
+`ruview` is the brand-facing meta-package for the
+[RuView](https://github.com/ruvnet/RuView) sensing stack. It installs
+the compiled PyO3 wheel published as
+[`wifi-densepose`](https://pypi.org/project/wifi-densepose/) and
+re-exports its full API under the `ruview` namespace — so you can
+write either of these and they do the same thing:
+
+```python
+from ruview import BreathingExtractor, SensingClient
+from wifi_densepose import BreathingExtractor, SensingClient
+```
+
+## Install
+
+```bash
+pip install ruview                 # core DSP
+pip install "ruview[client]"       # + WebSocket/MQTT clients
+```
+
+## Usage
+
+```python
+from ruview import BreathingExtractor
+
+br = BreathingExtractor.esp32_default()  # 56 subcarriers @ 100 Hz, 30s window
+for residuals, weights in csi_source:
+    est = br.extract(residuals=residuals, weights=weights)
+    if est is not None:
+        print(f"{est.value_bpm:.1f} BPM  (confidence={est.confidence:.2f})")
+```
+
+Full API + WebSocket / MQTT / Home Assistant integration docs:
+[wifi-densepose on PyPI](https://pypi.org/project/wifi-densepose/).
+
+## Why two PyPI names?
+
+Historic: `wifi-densepose` is the technical / academic name (the
+project started as a WiFi-based DensePose implementation).
+`ruview` is the brand the v2 ambient-intelligence platform ships
+under. Both are the same code. You pick the import that reads
+better in your project.
+
+## Links
+
+- **Repository** — https://github.com/ruvnet/RuView
+- **Modernization plan** — [ADR-117](https://github.com/ruvnet/RuView/blob/main/docs/adr/ADR-117-pip-wifi-densepose-modernization.md)
+- **Issues** — https://github.com/ruvnet/RuView/issues
+
+## License
+
+MIT.

python/ruview-meta/pyproject.toml

@@ -0,0 +1,62 @@
+# ADR-117 sibling release — `ruview` meta-package.
+#
+# Pure-Python wheel that re-exports everything from `wifi-densepose`
+# under the alias `ruview`. They're the same code, distributed under
+# two PyPI names so users can `pip install ruview` (the brand) or
+# `pip install wifi-densepose` (the technical name) — both end up
+# with the same compiled DSP available.
+#
+# Build:
+#   cd python/ruview-meta
+#   python -m build
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ruview"
+version = "2.0.0a1"
+description = "RuView — ambient intelligence from WiFi CSI. Meta-package; installs `wifi-densepose` and re-exports it under the `ruview` namespace. See https://github.com/ruvnet/RuView."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "rUv", email = "ruv@ruv.net" }]
+keywords = [
+    "wifi", "csi", "pose-estimation", "vital-signs",
+    "biometric", "ambient-intelligence", "home-assistant", "matter",
+    "ruview",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    # Pin to the matching v2 release so an alpha-pin `pip install ruview`
+    # always gets a compatible wifi-densepose.
+    "wifi-densepose==2.0.0a1",
+]
+
+[project.optional-dependencies]
+client = ["wifi-densepose[client]==2.0.0a1"]
+
+[project.urls]
+Homepage = "https://github.com/ruvnet/RuView"
+Repository = "https://github.com/ruvnet/RuView"
+Issues = "https://github.com/ruvnet/RuView/issues"
+Documentation = "https://github.com/ruvnet/RuView/tree/main/docs"
+
+[tool.setuptools]
+packages = ["ruview"]
+package-dir = { "" = "src" }

python/ruview-meta/src/ruview/__init__.py

@@ -0,0 +1,50 @@
+"""RuView — ambient intelligence from WiFi CSI.
+
+This package is a thin alias around `wifi-densepose`. Both PyPI names
+ship the same code and the same compiled Rust core; `ruview` is the
+brand-facing name and `wifi-densepose` is the technical name. Pick
+whichever you prefer:
+
+    pip install ruview
+    pip install wifi-densepose
+
+Both make this work:
+
+    from ruview import BreathingExtractor, hello
+    # or equivalently:
+    from wifi_densepose import BreathingExtractor, hello
+
+The actual compiled DSP, the Python facade, and every public class
+live in `wifi_densepose` — `ruview` just re-exports the surface so the
+two names are interchangeable in application code.
+"""
+
+from __future__ import annotations
+
+import wifi_densepose as _wdp
+
+# Re-export everything `wifi_densepose.__all__` declares.
+for _name in _wdp.__all__:
+    globals()[_name] = getattr(_wdp, _name)
+
+# Version + diagnostic fields — surface them under the ruview name
+# too so users can `print(ruview.__rust_version__)` without reaching
+# into the wifi_densepose module.
+__version__: str = _wdp.__version__
+__rust_version__: str = _wdp.__rust_version__
+__rust_build_tag__: str = _wdp.__rust_build_tag__
+__build_features__ = list(_wdp.__build_features__)
+
+# The client sub-package is also aliased for symmetry.
+try:
+    from wifi_densepose import client  # type: ignore[import-not-found]  # noqa: F401
+except ImportError:
+    # client extras not installed — that's fine for the core import.
+    pass
+
+__all__ = list(_wdp.__all__) + [
+    "__version__",
+    "__rust_version__",
+    "__rust_build_tag__",
+    "__build_features__",
+]

scripts/fix-markers.json

@@ -233,6 +233,46 @@
       ],
       "rationale": "At edge tier>=2 on N16R8 PSRAM boards, process_frame() runs update_multi_person_vitals() (4 persons × 256 history samples) plus wasm_runtime_on_frame() back-to-back. The vTaskDelay(1) in edge_task() only fires AFTER process_frame() fully returns — if process_frame() takes >5 s (common on PSRAM-backed boards under sustained 30 pps CSI load), IDLE1 on Core 1 never runs and the Task Watchdog Timer fires. The fix adds two vTaskDelay(1) calls inside process_frame(), gated on tier>=2, at the multi-person vitals boundary and after WASM dispatch. Removing them re-opens the WDT storm on N16R8 hardware.",
       "ref": "https://github.com/ruvnet/RuView/issues/683"
+    },
+    {
+      "id": "RuView#786-tombstone-import",
+      "title": "Tombstone (v1.99.0) __init__.py must raise ImportError with migration URL on import",
+      "files": ["python/tombstone/src/wifi_densepose/__init__.py"],
+      "require": [
+        "raise ImportError(",
+        "pip install wifi-densepose==2.0.0",
+        "github.com/ruvnet/RuView"
+      ],
+      "forbid": [
+        "/^def\\s/",
+        "/^class\\s/",
+        "/^import\\s+wifi_densepose/"
+      ],
+      "rationale": "ADR-117 §7.2 — the v1.99.0 tombstone wheel exists solely to raise a legible ImportError when v1.x users upgrade. If a future refactor adds real code (def / class / imports beyond the bare raise), the module may load partway before failing, breaking the migration narrative. The require patterns lock in the raise + the v2 install hint + the repo URL.",
+      "ref": "https://github.com/ruvnet/RuView/pull/786"
+    },
+    {
+      "id": "RuView#786-tombstone-smoke-cwd",
+      "title": "pip-release.yml tombstone smoke-test must cd out of repo root before importing",
+      "files": [".github/workflows/pip-release.yml"],
+      "require": [
+        "cd /tmp  # away from the repo root's stray wifi_densepose/"
+      ],
+      "rationale": "ADR-117 §P5 — the repo root contains a legacy `./wifi_densepose/__init__.py` from v1. Python places cwd at sys.path[0], so running `import wifi_densepose` from the repo root after a fresh venv install resolves to the legacy directory and bypasses the tombstone wheel entirely. The smoke-test step MUST `cd /tmp` before the import, otherwise CI silently passes against the wrong package. This was the root cause of run 26366648768.",
+      "ref": "https://github.com/ruvnet/RuView/pull/786"
+    },
+    {
+      "id": "RuView#786-pypi-token-auth",
+      "title": "pip-release.yml must authenticate to PyPI via PYPI_API_TOKEN secret, not OIDC",
+      "files": [".github/workflows/pip-release.yml"],
+      "require": [
+        "password: ${{ secrets.PYPI_API_TOKEN }}"
+      ],
+      "forbid": [
+        "id-token: write"
+      ],
+      "rationale": "ADR-117 §P5 — the project is registered with PyPI via API token, not OIDC Trusted Publisher. The token is sourced from GCP Secret Manager (see docs/integrations/pypi-release.md). Re-introducing the `id-token: write` permission would suggest a partial OIDC migration that won't actually work without registering the Trusted Publisher on pypi.org first — a silent regression that would 403 on the next publish.",
+      "ref": "https://github.com/ruvnet/RuView/pull/786"
     }
   ]
 }