plexus-python 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

plexus/__init__.py

@@ -5,10 +5,31 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 
     px = Plexus(api_key="plx_xxx", source_id="device-001")
     px.send("temperature", 72.5)
+
+At bench rates, batch — `send()` is one WebSocket frame per call and the
+gateway limits frames, not points:
+
+    with px.run("hotfire-03"), px.batch(interval_ms=50) as b:
+        b.send("att.rate_x", gyro.x)
 """
 
-from plexus.client import AuthenticationError, Plexus, PlexusError, read_mjpeg_frames
+from plexus.batching import BatchSender
+from plexus.client import (
+    AuthenticationError,
+    Plexus,
+    PlexusError,
+    RateLimitedError,
+    read_mjpeg_frames,
+)
 from plexus.config import RetryConfig
 
-__version__ = "0.8.0"
-__all__ = ["AuthenticationError", "Plexus", "PlexusError", "RetryConfig", "read_mjpeg_frames"]
+__version__ = "0.11.0"
+__all__ = [
+    "AuthenticationError",
+    "BatchSender",
+    "Plexus",
+    "PlexusError",
+    "RateLimitedError",
+    "RetryConfig",
+    "read_mjpeg_frames",
+]

plexus/_skills/README.md

@@ -0,0 +1,72 @@
+# Plexus agent skills
+
+Three skills that teach a coding agent — Claude Code, or anything that reads
+the same format — how to build against Plexus without guessing at the API.
+
+| Skill              | For                                                                       |
+| ------------------ | ------------------------------------------------------------------------- |
+| `plexus`           | The API itself: hosts, auth, every endpoint, the live stream, the pitfalls |
+| `plexus-firmware`  | Device-side ingest — ESP32, Pi, Jetson, autopilots, OBCs                   |
+| `plexus-dashboard` | Scaffolding a web dashboard on the read API                               |
+
+They are plain Markdown with YAML frontmatter. No install, no server, no
+credentials — an agent reads them and writes correct code.
+
+## Install
+
+```bash
+pip install plexus-python
+plexus skills install
+```
+
+That writes all three into `~/.claude/skills`. Use `--project` to install into
+`./.claude/skills` instead, so they travel with the repo, `--dir` to pick a
+target, or `--list` to see what ships without writing anything.
+
+Re-running refreshes them. These are reference docs, not config: a stale copy
+is the failure this command exists to fix, so an existing skill is replaced —
+reported as `updated`, never silently.
+
+Then just ask for what you want — "send my ESP32's battery voltage to Plexus",
+"build me a fleet dashboard" — and the agent picks the right one from its
+`description`.
+
+## Why these exist
+
+An agent that has not read these invents a plausible Plexus API and gets it
+wrong in ways that fail quietly. The three that cost the most real time:
+
+- The ingest array is **`points`**, not `metrics`, and every point needs a
+  `class`. Getting this wrong is a 400 on every write.
+- `timestamp` must be a **number**. An ISO-8601 string is rejected outright.
+- The query response is **columnar** — `series[m].avg[i]`, not
+  `series[m][i].v`. Guessing wrong yields `undefined` with no error: an empty
+  chart and no clue why.
+
+Each skill front-loads its pitfalls for that reason.
+
+## Keeping them true
+
+Prose does not compile, so a stale line here survives until it breaks
+someone's code. Two checks stop that:
+
+```bash
+python scripts/verify_skills.py     # every route, against the live API
+pytest tests/test_skills.py         # body shapes and response types, offline
+```
+
+`verify_skills.py` needs no API key. It asserts that every route the skills
+quote exists in the live OpenAPI spec, that every WebSocket route completes a
+real handshake, and — the useful part — that every route documented as **dead**
+is still dead. The skills name non-existent routes on purpose, because agents
+invent them otherwise; if one ever ships for real, the warning has become a lie
+and the check fails.
+
+`tests/test_skills.py` runs offline and guards the request/response shapes that
+have actually shipped broken code. It deliberately touches no network:
+`tests/conftest.py` points the suite at an unroutable address so nothing in it
+can reach production, and that holds here too.
+
+Both were written after an audit on 2026-08-28 found that all three skills had
+drifted — the firmware one badly enough that every template in it would have
+returned a 400.

plexus/_skills/plexus/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: plexus
+description: Integrate with the Plexus telemetry API — send data, query metrics, subscribe to live streams, send commands to devices. Use when the user mentions Plexus, plexus.company, gateway.plexus.company, plexus-data-api.fly.dev, or plx_ API keys. ALSO USE when the request involves IoT/hardware telemetry, fleet observability, sending sensor data to a backend, querying device time-series, building a fleet dashboard, monitoring drones/satellites/robots/edge devices, or any phrase like "send my sensor readings somewhere", "store telemetry", "track a fleet", "ingest metrics", or "device observability" — even if "Plexus" is never said.
+tools: Read, Write, Edit, Bash, WebFetch
+---
+
+# Plexus
+
+Plexus is a telemetry/observability platform for hardware fleets (drones, satellites, robots, edge devices). This skill teaches Claude how to integrate with its public API.
+
+## When to use this skill
+
+Trigger on any of:
+
+- The user mentions "Plexus", "plexus.company", `plx_` keys, `gateway.plexus.company`, or `plexus-data-api.fly.dev`
+- The user wants to ingest telemetry, query device metrics, stream live points, or send commands to a device
+- The user is building a dashboard, alert pipeline, or analysis on top of fleet telemetry
+- The user pastes a Plexus curl example and asks for help
+
+If the user wants to build a **frontend dashboard** specifically, also invoke `plexus-dashboard`.
+If they're writing **firmware / edge code**, also invoke `plexus-firmware`.
+
+## Hosts and auth
+
+Two base URLs. Authenticate with an `x-api-key` header on HTTP.
+
+| Purpose                                            | Host                             |
+| -------------------------------------------------- | -------------------------------- |
+| Ingest                                              | `https://gateway.plexus.company` |
+| Read API (sources, metrics, logs, fleet, commands, live stream) | `https://plexus-data-api.fly.dev` |
+
+```
+x-api-key: plx_...
+```
+
+The OpenAPI spec for the read API lives at `https://plexus-data-api.fly.dev/openapi.json` — fetch it when you need exact schemas. **It does not list the WebSocket endpoints** (FastAPI omits them), so use the Live section below for those.
+
+Read keys from env, never hardcode:
+
+- `PLEXUS_API_KEY` — server / CLI
+- `NEXT_PUBLIC_PLEXUS_API_KEY` — client-side Next.js (only if the user explicitly accepts the trade-off)
+
+## Endpoint cheat sheet
+
+### Send (gateway)
+
+`POST /ingest` — body `{ source_id, points: [...] }`, response `{ success, count, source_id }`.
+
+```json
+{
+  "source_id": "drone-001",
+  "points": [
+    { "class": "metric", "metric": "battery.voltage", "value": 11.8, "timestamp": 1787848320000 }
+  ]
+}
+```
+
+Per point:
+
+- **`class` is required** and must be `"metric"` or `"event"`. Omitting it is a 400.
+- **The array is `points`, not `metrics`.** Sending `metrics: [...]` returns `400 {"error":"'points' array is required"}`. This is the single most common mistake.
+- `metric` (string) and `value` are required.
+- `timestamp` must be a **number** — an ISO-8601 string is rejected with `points[i].timestamp must be a number`. Epoch **milliseconds** is the intended unit; a positive value under `1e12` is interpreted as **seconds** and scaled up automatically.
+- Omitting `timestamp` is safe: the point is stamped with gateway receive time. (This used to land at 1970 and be invisible — fixed, the loader now falls back to `ingested_at`.)
+- `source_id` may be set at the envelope level, per point, or both — per point wins.
+- The gateway creates the source on first write; no registration step.
+
+`POST /api/v1/write` also exists as a Prometheus/Alloy/OTel/Telegraf remote-write receiver. Do not reach for it unless the user already runs one of those.
+
+### Read (data API)
+
+Paths are `/v1/sources/...`. `/v1/devices/...` is a deprecated alias — bare `/v1/devices` 307s to `/v1/devices/`, which 308s to `/v1/sources/`. Both preserve method and body, but just use `sources` (and `curl -L` if you inherit an old path).
+
+- `GET /v1/sources` → `{ devices: [{ source_id, online, last_seen_ms }] }`
+  - Takes `?status=online|offline`.
+  - Note the mismatch: the **path** is `sources`, the **response key** is still `devices`. Renaming stopped halfway. Read `body.devices`.
+- `GET /v1/sources/{id}` → `{ source_id, online, last_seen_ms }`
+- `GET /v1/sources/{id}/metrics` → `string[]` (metric names)
+- `GET /v1/sources/{id}/metrics/latest` → `{ metrics: { [name]: number } }`
+- `GET /v1/sources/{id}/metrics/query?metrics=a,b&last=1h` → columnar, see below. Also takes `start`, `end`, `interval`.
+- `GET /v1/sources/{id}/logs?last=1h&limit=1000` → log rows (also `tail`, `name`, `start`, `end`)
+- `GET /v1/fleet/health` → `{ sources_total, sources_online }`
+- `GET /v1/fleet/metrics?metric=X&last=1h` → `{ metric, interval, sources_online, sources_w_metric, sources: [...], truncated }`
+
+There is **no per-source health endpoint** — `/v1/sources/{id}/health` 404s. Liveness is already on the list: each entry carries `online` and `last_seen_ms`. Use `/v1/fleet/health` for the roll-up.
+
+#### The query response is columnar
+
+Not an array of points. Each metric maps to parallel arrays:
+
+```json
+{
+  "interval": "1m",
+  "auto_downsampled": true,
+  "truncated": false,
+  "series": {
+    "my.metric": {
+      "timestamp_ms": [1787848320000, 1787848380000],
+      "min": [46.5, -0.05],
+      "max": [49.9, 49.9],
+      "avg": [48.2, 26.6],
+      "count": [4, 60]
+    }
+  }
+}
+```
+
+So it is `series[m].timestamp_ms[i]` and `series[m].avg[i]`, not `series[m][i].t`. Zip the arrays by index to plot:
+
+```js
+const s = res.series[metric];
+const points = s.timestamp_ms.map((t, i) => ({ t, v: s.avg[i] }));
+```
+
+`/v1/fleet/metrics` uses the same columnar shape, one entry per source under `sources[]`.
+
+### Live (data API, not the gateway)
+
+```
+WS wss://plexus-data-api.fly.dev/v1/sources/{source_id}/metrics/stream?metrics=a,b
+```
+
+Also `/logs/stream` and `/video/stream` under the same source prefix.
+
+**Auth is the first message, not a header.** Immediately after connect, send:
+
+```json
+{ "type": "auth", "api_key": "plx_..." }
+```
+
+Then just listen — there is no separate `subscribe` message, and the `?metrics=` query param does the filtering server-side. Because auth is a WS message rather than a header, a **browser can connect directly** — no backend relay needed for auth reasons alone (though you still shouldn't ship a key in public client code).
+
+Frames you receive:
+
+- `{"type":"telemetry","points":[ {class, metric, value, timestamp, ...}, ... ]}` — **batched**, an array per frame, same point shape as ingest. Iterate `points`.
+- `{"type":"gateway_reconnecting","attempt":N,"delay_s":N}` — informational; the server is reconnecting upstream and will resume.
+
+Close codes: `4401` unauthorized (bad or missing key, or no auth message within 10s), `4402` payment required (org access disabled).
+
+You do **not** need to answer application-level pings on this endpoint; keepalive is handled at the protocol layer.
+
+The gateway's own sockets (`/ws/device`, `/ws/browser`) are for the Python SDK and the Plexus app respectively. Don't write third-party clients against them. There is no `/v1/stream` on the gateway.
+
+### Control (data API)
+
+`POST /v1/sources/{id}/commands` — body `{ command, params? }`, response `{ queued: bool }`. Confirm with the user before sending — these hit physical hardware.
+
+## Standard scaffolding
+
+When asked to "set up Plexus" in a project, do this:
+
+1. **Detect the language** from the project's manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`). For Python, prefer the SDK: `pip install plexus-python`.
+2. **Create one client module** under `src/lib/plexus.{ts,py,go}` (or the project's idiomatic location). One function per endpoint the user actually needs — don't scaffold the whole surface if they only want ingest.
+3. **Throw a typed error class** (`PlexusError` with `status` + `message`) on non-2xx responses. Map 401 to "check your PLEXUS_API_KEY".
+4. **Read the API key from env**, never hardcode. If the user is shipping a public client app, warn them about exposing keys and recommend a backend proxy.
+5. **Add a single usage example** in the project — one obvious place, not five — so they can verify it works.
+6. **Update README** with a short section: "Set `PLEXUS_API_KEY`, then run X."
+
+## Idioms
+
+- **Polling cadences for dashboards**: latest values 5s, charts 10s, fleet health 10s, source list 30s. Use SWR or TanStack Query with `refreshInterval`.
+- **Time ranges**: prefer `last=1h` (relative) over `start`/`end` (absolute) — easier to reason about and less timezone footgun. `start`/`end` are ISO date-times, not epoch ms.
+- **Batching ingest**: buffer up to 64 points or 5 seconds, whichever first. On 429 / 5xx, exponential backoff with max 3 attempts.
+- **Source IDs are slugs**: `drone-001`, `sat-alpha-3`. Must match `^[a-z0-9][a-z0-9_-]{1,62}$`. Stable, lowercase, hyphenated. Don't use UUIDs in user-facing surfaces.
+- **Source IDs are not deduplicated.** The gateway writes whatever `source_id` you declare. Two devices declaring the same name merge into one source.
+- **Metric names are opaque and may be long.** Anything that round-trips a name must use the identical string on both sides or the series and its metadata will not join.
+
+## Common pitfalls
+
+- **`points`, not `metrics`, on ingest**, and every point needs `class`. The two most common 400s.
+- **Numeric timestamps only.** ISO strings 400. Milliseconds unless the value is under `1e12`, in which case it's read as seconds.
+- **The query response is columnar.** `series[m].avg[i]`, not `series[m][i].v`. Reaching for `.t`/`.v` yields `undefined` and an empty chart with no error.
+- **The live stream is on the data API, and auths by first message.** There is no `/v1/stream` on the gateway.
+- **Telemetry frames are batched** — `points` is an array. Handling one frame as one point silently drops data.
+- `start`/`end` are **ISO date-times on every endpoint** that takes them — `query`, `logs` and `fleet/metrics` alike. `last=1h` is easier and works on all three.
+- `auto_downsampled: true` in a query response means the bucket size was picked for you — surface it in the UI so users understand what they're looking at.
+- Commands queue on the device; they don't execute synchronously. Don't promise the user "it rebooted" — promise "reboot queued".
+
+## When unsure
+
+Fetch `https://plexus-data-api.fly.dev/openapi.json` for the authoritative HTTP schema (it will not show WebSocket routes), and check a real response before writing parsing code. `scripts/verify_skills.py` in this repo checks these docs against the live spec — run it if something here looks stale.
+
+This cheat sheet has drifted before. Corrected 2026-08-27 against Data API 0.1.0 (ingest array name, `sources`/`devices` paths, removed per-source health, columnar query) and again 2026-08-28 against gateway + API source (the live-stream host/path/auth/frame shape, the required `class` field, numeric-only timestamps, the redirect chain, and the now-fixed 1970 timestamp behavior).

plexus/_skills/plexus-dashboard/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: plexus-dashboard
+description: Scaffold a working web dashboard against the Plexus telemetry API — device picker, latest-value tiles, time-series charts, log viewer. Use when the user wants to build a frontend, dashboard, ops UI, mission control, or fleet view on top of Plexus data. Triggering phrases include "show me my drones/satellites/robots", "build a dashboard for my fleet", "vibe code a Plexus frontend", "fleet monitoring UI", "telemetry dashboard", "device status page", "live charts of sensor data", or "ops view for my hardware" — even if "Plexus" is never said, as long as the data source is the Plexus API.
+tools: Read, Write, Edit, Bash, WebFetch
+---
+
+# Plexus Dashboard
+
+Scaffolds a complete web dashboard against the Plexus read API. This skill is opinionated about the stack so the user gets a working dashboard fast — they can swap pieces out later.
+
+## When to use this skill
+
+- The user is building a frontend / dashboard / ops UI on top of Plexus telemetry
+- They mention "vibe code" + Plexus, or want to "build a dashboard for my fleet"
+- They have a Plexus API key and want to _see_ their data, not just ingest it
+
+If they need help with **ingesting** data (firmware / edge), use `plexus-firmware` instead.
+For lower-level **API integration** without a UI, use the generic `plexus` skill.
+
+## Preferred stack
+
+Pick this unless the user explicitly wants something else:
+
+- **Framework**: Next.js (App Router) — it's the default and Vercel-friendly
+- **Styling**: Tailwind utilities only, no design system
+- **Data fetching**: SWR (lighter than TanStack Query for this use case)
+- **Charts**: Recharts (good defaults, easy to customize, no canvas)
+- **Types**: TypeScript, strict
+
+If the project is already React Router / Remix / Vite, adapt — don't force Next.js on top.
+
+## Shape of the thing
+
+```
+Dashboard
+├─ Source list (left rail) — /v1/sources, `online` + `last_seen_ms` are on each row
+└─ Detail pane
+   ├─ Tile row: every metric from /metrics/latest as a big-number card
+   ├─ Chart grid: one line chart per metric over the last 1h via /metrics/query
+   └─ (Optional) Log pane: /logs in a virtualized list
+```
+
+## Polling cadences
+
+| Endpoint                          | Refresh interval |
+| --------------------------------- | ---------------- |
+| `/v1/sources`                     | 30s              |
+| `/v1/sources/{id}/metrics/latest` | 5s               |
+| `/v1/sources/{id}/metrics/query`  | 10s              |
+| `/v1/fleet/health`                | 10s              |
+
+Always use `refreshInterval` on SWR. Never use `setInterval` directly — SWR handles tab visibility, focus revalidation, and dedup.
+
+**There is no per-source health endpoint.** `/v1/sources/{id}/health` 404s. Online status already rides along on `/v1/sources` — every row carries `online` and `last_seen_ms`, so a status dot needs no extra request. Don't poll for it.
+
+Use `/v1/sources` (canonical). `/v1/devices` still works via a 307→308 redirect chain but is deprecated.
+
+## Scaffolding workflow
+
+When the user says "build me a Plexus dashboard":
+
+### Step 1: Confirm scope
+
+Ask exactly two questions, no more:
+
+1. "Which sources? All of them, or one specific source_id?"
+2. "Existing project to extend, or a fresh one?"
+
+### Step 2: Set up the client
+
+Create `src/lib/plexus.ts`:
+
+```ts
+const BASE = "https://plexus-data-api.fly.dev";
+const KEY = process.env.NEXT_PUBLIC_PLEXUS_API_KEY!;
+
+export class PlexusError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+async function get<T>(path: string): Promise<T> {
+  const r = await fetch(`${BASE}${path}`, { headers: { "x-api-key": KEY } });
+  if (!r.ok) throw new PlexusError(r.status, await r.text());
+  return r.json();
+}
+
+/** Note: the path is `sources`, the response key is still `devices`. */
+export type Source = { source_id: string; online: boolean; last_seen_ms: number | null };
+export type Latest = { metrics: Record<string, number> };
+
+/** The query response is COLUMNAR — parallel arrays, not an array of points. */
+export type Series = {
+  timestamp_ms: number[];
+  min: number[];
+  max: number[];
+  avg: number[];
+  count: number[];
+};
+export type Query = {
+  interval: string;
+  auto_downsampled: boolean;
+  truncated: boolean;
+  series: Record<string, Series>;
+};
+
+export const listSources = () => get<{ devices: Source[] }>("/v1/sources");
+export const getLatest = (id: string) =>
+  get<Latest>(`/v1/sources/${id}/metrics/latest`);
+export const queryMetrics = (id: string, metrics: string[], last = "1h") =>
+  get<Query>(
+    `/v1/sources/${id}/metrics/query?metrics=${metrics.join(",")}&last=${last}`,
+  );
+export const fleetHealth = () =>
+  get<{ sources_total: number; sources_online: number }>("/v1/fleet/health");
+
+/** Zip the columnar response into what Recharts wants. */
+export function toPoints(s: Series) {
+  return s.timestamp_ms.map((t, i) => ({ t, v: s.avg[i] }));
+}
+```
+
+### Step 3: Build the components
+
+- `<SourceList>` — `useSWR("sources", listSources, { refreshInterval: 30_000 })`, renders `data.devices`
+- `<StatusDot source>` — pure render off the `online` field already on the row. **No fetch.**
+- `<LatestTiles sourceId>` — polls `/metrics/latest` every 5s, renders each entry as a card
+- `<MetricChart sourceId metric range>` — `useSWR([id, metric, range], () => queryMetrics(id, [metric], range))`, then `toPoints(data.series[metric])` into a Recharts `<LineChart>`
+- Surface `auto_downsampled` in the chart header ("1m buckets") so nobody misreads a smoothed line as raw data
+
+### Step 4: Empty + error states
+
+- If `/v1/sources` returns `{ devices: [] }`: show "No sources yet" with a copy-able curl pointing at `https://gateway.plexus.company/ingest`.
+- On `PlexusError` with status 401: show "Check your PLEXUS_API_KEY".
+- On other errors: log + small toast, don't blow up the UI.
+
+### Step 5: Don't ship without
+
+- Setting `NEXT_PUBLIC_PLEXUS_API_KEY` in `.env.local` (warn the user about exposure if their app is public)
+- A README section with the env var + a one-line description
+- One `npm run dev` smoke test before declaring done
+
+## Upgrade path: drop polling, use the live stream
+
+Once polling works end-to-end, swap `getLatest` polling for the WebSocket stream. Latest-value tiles update the moment a point is ingested instead of on the next 5s tick — feels dramatically better.
+
+The stream is on the **data API**, not the gateway, and it **authenticates with its first message rather than a header** — which means a browser can connect directly, no relay needed:
+
+```ts
+export function subscribeMetrics(
+  sourceId: string,
+  metrics: string[],
+  onPoints: (pts: Array<{ metric: string; value: number; timestamp: number }>) => void,
+) {
+  const qs = metrics.length ? `?metrics=${metrics.join(",")}` : "";
+  const ws = new WebSocket(
+    `wss://plexus-data-api.fly.dev/v1/sources/${sourceId}/metrics/stream${qs}`,
+  );
+
+  // Auth is the FIRST MESSAGE, not a header. Send it within 10s or the
+  // server closes with 4401.
+  ws.onopen = () => ws.send(JSON.stringify({ type: "auth", api_key: KEY }));
+
+  ws.onmessage = (e) => {
+    const m = JSON.parse(e.data);
+    // Frames are BATCHED: `points` is an array. Treating one frame as one
+    // point silently drops data.
+    if (m.type === "telemetry") onPoints(m.points);
+    // m.type === "gateway_reconnecting" is informational; it resumes itself.
+  };
+
+  ws.onclose = (e) => {
+    // 4401 = bad/missing key, 4402 = org access disabled. Neither is worth
+    // retrying; anything else, reconnect with exponential backoff.
+  };
+
+  return () => ws.close();
+}
+```
+
+No `pong` handling is needed on this endpoint — keepalive is at the protocol layer.
+
+**Key exposure still applies.** Auth-by-message solves the browser's header limitation, not the "don't ship a secret to the public internet" problem. If the app is publicly reachable, put a relay in front and keep the key server-side.
+
+Wire it alongside SWR: keep `useSWR` for initial load (UI hydrates with a value immediately) and let stream frames update the same cache via `mutate(key, fn, false)`. Charts can keep polling — querying a 1h window over WS is awkward and the 10s cadence is fine.
+
+## What NOT to do
+
+- Don't add auth/login flows. Tier_1 users have a single API key; this is meant to be embedded in their own auth-protected app.
+- Don't add a backend layer "for safety" unless the user asks or the app is public. Direct browser → data API is the intended pattern for prototypes.
+- Don't poll a per-source health endpoint. It doesn't exist.
+- Don't type the query response as an array. It is columnar, and `.map(p => p.v)` over it yields `undefined` with no error — an empty chart and no clue why.
+- Don't mock data. If the user has no sources yet, show the empty state with the ingest curl, not fake telemetry.
+- Don't over-style. Tailwind utilities, gray scale, one accent color. The whole point is they can iterate on the design themselves.
+
+## When unsure about endpoint shapes
+
+`https://plexus-data-api.fly.dev/openapi.json` is the source of truth for HTTP. It does **not** list WebSocket routes — the generic `plexus` skill documents those.
+
+Corrected 2026-08-28: `/v1/devices` → `/v1/sources`, removed the non-existent per-source health endpoint, fixed the columnar query type, and replaced the live-stream section (the old `wss://gateway.plexus.company/v1/stream` 404s, and the "browsers can't authenticate" caveat no longer holds).