plexus-python 0.7.1__tar.gz → 0.9.0__tar.gz

{plexus_python-0.7.1 → plexus_python-0.9.0}/AGENTS.md

@@ -4,22 +4,27 @@ Machine-readable interface for AI assistants and automation scripts.
 
 ## Environment Variables
 
-| Variable                | Description                           | Default                          |
-| ----------------------- | ------------------------------------- | -------------------------------- |
-| `PLEXUS_API_KEY`        | API key for authentication (required) | none                             |
-| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL               | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                 | `wss://plexus-gateway.fly.dev`   |
+| Variable                | Description                                     | Default                          |
+| ----------------------- | ----------------------------------------------- | -------------------------------- |
+| `PLEXUS_API_KEY`        | API key for authentication (required)           | none                             |
+| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL                         | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                           | `wss://gateway.plexus.company`   |
+| `PLEXUS_ENDPOINT`       | Product app URL (runs, frame uploads, CLI auth) | `https://app.plexus.company`     |
+| `PLEXUS_QUIET`          | Set `1`/`true`/`yes` to silence `[plexus]` stderr status lines | unset (status lines on) |
 
 ## CLI Commands
 
 ```bash
-plexus start                           # Stream with PLEXUS_API_KEY env var
-plexus start --key plx_xxxxx           # Pass key inline
-plexus start --device-id my-device     # Set device identifier
-plexus reset                           # Clear config
+plexus init                            # Authorize this machine, save an API key locally (alias: login)
+plexus init --name my-key              # Label for the issued key (default: cli-<hostname>)
+plexus init --force                    # Overwrite an existing local key
+plexus logout                          # Forget the local API key
+plexus whoami                          # Show the local credential summary
 ```
 
-An API key is required — set `PLEXUS_API_KEY` or pass `--key`. There is no interactive signup; get a key at app.plexus.company/devices.
+`plexus init` opens a browser to `app.plexus.company/auth/cli`, waits for the callback, and
+persists the issued key to `~/.plexus/config.json`. Alternatively, set `PLEXUS_API_KEY` (or pass
+`api_key=` to `Plexus()`) instead of running `init`; get a key at app.plexus.company/api.
 
 ## Exit Codes
 

{plexus_python-0.7.1 → plexus_python-0.9.0}/API.md

@@ -30,7 +30,7 @@ Then control streaming, recording, and configuration from [app.plexus.company/de
 Send data directly via HTTP:
 
 ```bash
-curl -X POST https://plexus-gateway.fly.dev/ingest \
+curl -X POST https://gateway.plexus.company/ingest \
   -H "x-api-key: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -55,8 +55,8 @@ Plexus uses API keys for all authentication:
 
 **Option A: CLI setup (recommended for devices)**
 
-1. Run `plexus start` on your device
-2. Sign up or sign in directly in the terminal
+1. Run `plexus init` on your device
+2. Authorize the machine in the browser tab it opens
 3. API key is saved to `~/.plexus/config.json`
 
 **Option B: Manual creation**
@@ -77,7 +77,7 @@ x-api-key: plx_xxxxx
 
 ### Send Data
 
-**POST** `/api/ingest`
+**POST** `https://gateway.plexus.company/ingest`
 
 ```json
 {
@@ -87,21 +87,19 @@ x-api-key: plx_xxxxx
       "value": 72.5,
       "timestamp": 1699900000.123,
       "source_id": "sensor-001",
-      "tags": { "location": "lab" },
-      "session_id": "test-001"
+      "tags": { "location": "lab" }
     }
   ]
 }
 ```
 
-| Field        | Type   | Required | Description                                    |
-| ------------ | ------ | -------- | ---------------------------------------------- |
-| `metric`     | string | Yes      | Metric name (e.g., `temperature`, `motor.rpm`) |
-| `value`      | any    | Yes      | See supported value types below                |
+| Field        | Type   | Required | Description                                                                                                                                                                                             |
+| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metric`     | string | Yes      | Metric name (e.g., `temperature`, `motor.rpm`)                                                                                                                                                          |
+| `value`      | any    | Yes      | See supported value types below                                                                                                                                                                         |
 | `timestamp`  | float  | No       | Unix timestamp in seconds (or ms if ≥ 1e12). Omit to use device time. Over WebSocket, the Python SDK applies a server-synced clock correction when omitted — see [Clock correction](#clock-correction). |
-| `source_id`  | string | Yes      | Your source identifier                         |
-| `tags`       | object | No       | Key-value labels                               |
-| `session_id` | string | No       | Group data into sessions                       |
+| `source_id`  | string | Yes      | Your source identifier                                                                                                                                                                                  |
+| `tags`       | object | No       | Key-value labels                                                                                                                                                                                        |
 
 ### Supported Value Types
 
@@ -115,29 +113,7 @@ x-api-key: plx_xxxxx
 
 ### Sessions
 
-Group related data for analysis and playback.
-
-**Create session:**
-
-```json
-POST /api/sessions
-{
-  "session_id": "test-001",
-  "name": "Motor Test Run",
-  "source_id": "sensor-001",
-  "status": "active"
-}
-```
-
-**End session:**
-
-```json
-PATCH /api/sessions/{session_id}
-{
-  "status": "completed",
-  "ended_at": "2024-01-15T10:30:00Z"
-}
-```
+> **Removed / not built.** There is no sessions or runs REST API (`POST /api/sessions`, `POST /api/runs`) — no such route exists in the gateway or platform, and the SDK's former `run()` context has been removed. To group a slice of data, use plain `tags` on each point.
 
 ## WebSocket API
 
@@ -146,13 +122,13 @@ For real-time UI-controlled streaming, devices connect via WebSocket.
 ### Connection Flow
 
 1. Device connects to the gateway
-2. Device authenticates with API key
-3. Device reports available sensors
-4. Dashboard controls streaming via messages
+2. Device authenticates with API key (and advertises any registered commands)
+3. Device streams `telemetry` frames
+4. Dashboard/API invokes registered commands via `typed_command`
 
 ### Device Authentication
 
-Devices authenticate using an API key. The `source_id` in the request is the device's *desired* name; the server may return a different, auto-suffixed name in the `authenticated` frame if the desired name is already claimed by another device (see [Device identity](../README.md#device-identity) in the README).
+Devices authenticate using an API key. The gateway echoes the declared `source_id` back unchanged — there is no auto-suffixing, so pick a unique `source_id` per device.
 
 ```json
 // Device → Server
@@ -160,9 +136,8 @@ Devices authenticate using an API key. The `source_id` in the request is the dev
   "type": "device_auth",
   "api_key": "plx_xxxxx",
   "source_id": "drone-01",
-  "install_id": "c9f2e0b46f4a4f6a8c3e1d5b0a2e7f91",
   "platform": "python-sdk",
-  "agent_version": "0.3.1"
+  "agent_version": "0.8.0"
 }
 
 // Server → Device
@@ -171,53 +146,34 @@ Devices authenticate using an API key. The `source_id` in the request is the dev
   "source_id": "drone-01",
   "server_time_ms": 1746100800000
 }
-
-// Server → Device (collision case)
-{
-  "type": "authenticated",
-  "source_id": "drone-01_2",
-  "server_time_ms": 1746100800000
-}
 ```
 
-The SDK **adopts** whatever `source_id` the server returns and uses it for all subsequent frames, heartbeats, and reconnects. It also persists the assigned name locally so reconnects go straight to the claimed slot.
-
 `server_time_ms` is the gateway's current Unix time in milliseconds. The Python SDK uses it to compute a clock offset (`server_time - device_time`) that is applied to every SDK-generated timestamp for the lifetime of the connection. This corrects for devices that boot without NTP or have an unreliable RTC — a common condition on embedded Linux. See [Clock correction](#clock-correction) for details and limitations.
 
-`install_id` is a stable per-installation UUID, generated on the device's first run and saved to `~/.plexus/config.json`. It lets the server distinguish a rebooting device from a new device trying to claim an existing name. Legacy SDKs that omit `install_id` continue to work as before (the server passes the declared `source_id` through unchanged).
+> **Removed:** `install_id` and server-side `source_id` auto-suffixing were removed in 0.7.1. The device_auth frame no longer carries an `install_id`, and the client does not adopt or persist a server-assigned name.
 
-### Message Types (Dashboard → Device)
+### Frame Types
 
-| Type            | Description                          |
-| --------------- | ------------------------------------ |
-| `start_stream`  | Start streaming sensor data          |
-| `stop_stream`   | Stop streaming                       |
-| `start_session` | Start recording to a session         |
-| `stop_session`  | Stop recording                       |
-| `configure`     | Configure sensor (e.g., sample rate) |
-| `ping`          | Keepalive request                    |
+**Device → Server**
 
-### Message Types (Device → Dashboard)
+| Type             | Description                                     |
+| ---------------- | ----------------------------------------------- |
+| `device_auth`    | Authenticate on connect (see above)             |
+| `telemetry`      | Sensor data points                              |
+| `heartbeat`      | Liveness ping (every 30s)                       |
+| `command_result` | `ack` / `result` / `error` for a typed command  |
 
-| Type              | Description             |
-| ----------------- | ----------------------- |
-| `telemetry`       | Sensor data points      |
-| `session_started` | Confirm session started |
-| `session_stopped` | Confirm session stopped |
-| `pong`            | Keepalive response      |
+**Server → Device**
 
-### Start Streaming
+| Type            | Description                                            |
+| --------------- | ----------------------------------------------------- |
+| `authenticated` | Auth accepted; carries `server_time_ms`               |
+| `typed_command` | Invoke a command the device registered via `on_command` |
 
-```json
-// Dashboard → Device
-{
-  "type": "start_stream",
-  "source_id": "my-device-001",
-  "metrics": ["accel_x", "accel_y", "accel_z"],
-  "interval_ms": 100
-}
+### Telemetry
 
-// Device → Dashboard (continuous)
+```json
+// Device → Server (streamed continuously)
 {
   "type": "telemetry",
   "points": [
@@ -228,54 +184,20 @@ The SDK **adopts** whatever `source_id` the server returns and uses it for all s
 }
 ```
 
-### Start Session (Recording)
+### Commands
 
-```json
-// Dashboard → Device
-{
-  "type": "start_session",
-  "source_id": "my-device-001",
-  "session_id": "session_1699900000_abc123",
-  "session_name": "Motor Test",
-  "metrics": [],
-  "interval_ms": 100
-}
+Dashboard/API actions reach the device as a single `typed_command` envelope; the device replies with `command_result` frames. Register handlers with `px.on_command(...)` before the first `send()`.
 
-// Device → Dashboard
-{
-  "type": "session_started",
-  "session_id": "session_1699900000_abc123",
-  "session_name": "Motor Test"
-}
+```json
+// Server → Device
+{ "type": "typed_command", "id": "cmd-1", "command": "reboot", "params": { "delay_s": 0 } }
 
-// Device streams telemetry with session_id tag
-{
-  "type": "telemetry",
-  "session_id": "session_1699900000_abc123",
-  "points": [
-    {
-      "metric": "accel_x",
-      "value": 0.12,
-      "timestamp": 1699900000123,
-      "tags": { "session_id": "session_1699900000_abc123" }
-    }
-  ]
-}
+// Device → Server (ack, then result or error)
+{ "type": "command_result", "id": "cmd-1", "command": "reboot", "event": "ack" }
+{ "type": "command_result", "id": "cmd-1", "command": "reboot", "event": "result", "result": { "ok": true } }
 ```
 
-### Configure Sensor
-
-```json
-// Dashboard → Device
-{
-  "type": "configure",
-  "source_id": "my-device-001",
-  "sensor": "MPU6050",
-  "config": {
-    "sample_rate": 50
-  }
-}
-```
+> **Removed / not built.** There are no raw `start_stream`, `stop_stream`, `start_session`, `stop_session`, `configure`, `session_started`, or `session_stopped` frames — the earlier agent-style streaming/recording protocol was removed. Dashboard-driven control now flows through the `typed_command` envelope above.
 
 ## Code Examples
 
@@ -286,7 +208,7 @@ import requests
 import time
 
 requests.post(
-    "https://plexus-gateway.fly.dev/ingest",
+    "https://gateway.plexus.company/ingest",
     headers={"x-api-key": "plx_xxxxx"},
     json={
         "points": [{
@@ -302,7 +224,7 @@ requests.post(
 ### JavaScript
 
 ```javascript
-await fetch("https://plexus-gateway.fly.dev/ingest", {
+await fetch("https://gateway.plexus.company/ingest", {
   method: "POST",
   headers: {
     "x-api-key": "plx_xxxxx",
@@ -344,7 +266,7 @@ func main() {
     }
 
     body, _ := json.Marshal(points)
-    req, _ := http.NewRequest("POST", "https://plexus-gateway.fly.dev/ingest", bytes.NewBuffer(body))
+    req, _ := http.NewRequest("POST", "https://gateway.plexus.company/ingest", bytes.NewBuffer(body))
     req.Header.Set("x-api-key", "plx_xxxxx")
     req.Header.Set("Content-Type", "application/json")
 
@@ -363,7 +285,7 @@ func main() {
 // field entirely if you cannot guarantee NTP sync at send time.
 void sendToPlexus(const char* metric, float value) {
     HTTPClient http;
-    http.begin("https://plexus-gateway.fly.dev/ingest");
+    http.begin("https://gateway.plexus.company/ingest");
     http.addHeader("Content-Type", "application/json");
     http.addHeader("x-api-key", "plx_xxxxx");
 
@@ -386,7 +308,7 @@ void sendToPlexus(const char* metric, float value) {
 API_KEY="plx_xxxxx"
 SOURCE_ID="sensor-001"
 
-curl -X POST https://plexus-gateway.fly.dev/ingest \
+curl -X POST https://gateway.plexus.company/ingest \
   -H "x-api-key: $API_KEY" \
   -H "Content-Type: application/json" \
   -d "{
@@ -430,40 +352,9 @@ while True:
         px.send("attitude.pitch", msg.pitch)
 ```
 
-See [docs.plexus.dev/recipes](https://docs.plexus.dev/recipes) for more.
-
 ## Python SDK with Sensor Drivers
 
-For Raspberry Pi and other Linux devices, the Python SDK includes sensor drivers:
-
-```bash
-pip install plexus-python[sensors]
-plexus start
-```
-
-### Supported Sensors
-
-| Sensor  | Type        | Metrics                                                       | I2C Address |
-| ------- | ----------- | ------------------------------------------------------------- | ----------- |
-| MPU6050 | 6-axis IMU  | `accel_x`, `accel_y`, `accel_z`, `gyro_x`, `gyro_y`, `gyro_z` | 0x68, 0x69  |
-| MPU9250 | 9-axis IMU  | `accel_x`, `accel_y`, `accel_z`, `gyro_x`, `gyro_y`, `gyro_z` | 0x68        |
-| BME280  | Environment | `temperature`, `humidity`, `pressure`                         | 0x76, 0x77  |
-
-### Custom Sensors
-
-```python
-from plexus.sensors import BaseSensor, SensorReading
-
-class MySensor(BaseSensor):
-    name = "MySensor"
-    metrics = ["voltage", "current"]
-
-    def read(self):
-        return [
-            SensorReading("voltage", read_adc(0) * 3.3),
-            SensorReading("current", read_adc(1) * 0.1),
-        ]
-```
+> **Removed / not built.** There is no `plexus-python[sensors]` extra and no `plexus.sensors` module (`BaseSensor` / `SensorReading` do not exist). The only optional extras are `[video]` and `[dev]`. This SDK stays out of your decode path — read your sensor with whatever library you already use and pass values to `px.send()` (see [Bring Your Own Protocol](#bring-your-own-protocol) above).
 
 ## Errors
 
@@ -492,24 +383,26 @@ px.send("temperature", 72.5, timestamp=t)        # your timestamp → used as-is
 ```
 
 **When to pass an explicit timestamp:**
+
 - You have a reliable wall-clock source (GPS, trusted hardware RTC, host NTP)
 - You are replaying or backfilling historical data
 - Your sensor provides its own wall-clock timestamp
 
 **When to omit timestamp:**
+
 - The device may have booted without NTP (Raspberry Pi, Jetson, field robots without network on first boot)
 - You have no reliable external time source
 
 **Known limitations:**
+
 - The clock offset refreshes only on WebSocket reconnect. A device with a drifting RTC that stays connected for many days will accumulate uncorrected drift between reconnects proportional to the drift rate.
-- HTTP transport (`transport="http"`) does not receive clock sync — timestamps default to the device clock uncorrected.
-- `send_batch()` takes one shared `timestamp` for the whole batch, not per-point. For per-point timestamps, call `send()` in a loop.
+- The HTTP fallback path (used when the WebSocket is unavailable) does not receive clock sync — timestamps default to the device clock uncorrected.
+- `send_batch()` takes one shared `timestamp` by default; pass `(metric, value, timestamp)` 3-tuples for per-point timestamps.
 
 ## Best Practices
 
 - **Batch points** - Send up to 100 points per request for HTTP
 - **Omit timestamp when unsure** - The Python SDK applies server-synced clock correction when `timestamp` is omitted over WebSocket; only pass an explicit timestamp when you have a reliable wall-clock source
 - **Consistent source_id** - Use the same ID for each physical device/source
-- **Use tags** - Label data for filtering (e.g., `{"location": "lab"}`)
-- **Use sessions** - Group related data for easier analysis
-- **Prefer WebSocket** - For real-time UI-controlled devices, use `plexus start`
+- **Use tags** - Label data for filtering and grouping (e.g., `{"location": "lab"}`)
+- **Prefer WebSocket** - For real-time UI-controlled devices, the SDK connects over WebSocket by default

{plexus_python-0.7.1 → plexus_python-0.9.0}/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.9.0] - 2026-08-27 - Flexible values and the real slug rule
+
+Two fixes for data that looked like it was sent but never arrived, plus the
+removal of a dead API.
+
+### Fixed
+
+- **`send()` now infers a point's class from its value type** instead of always
+  tagging `class="metric"`. Numbers stay metrics; strings, bools, dicts and
+  lists become events. The gateway rejects a non-numeric value on
+  `class="metric"` and drops the *whole frame* — so `px.send("state", "RUNNING")`
+  silently took every other point in that batch down with it. Non-numeric values
+  have been advertised since 0.2.0; this is what makes them work.
+  An explicit `data_class="metric"` with a non-numeric value now raises
+  `PlexusError` locally rather than failing on the wire.
+
+- **`source_id` validation matched an older, stricter rule than the server.**
+  The SDK enforced `^[a-z0-9][a-z0-9_-]{1,62}$` — no dots, minimum two
+  characters — while the gateway accepts `^[a-z0-9][a-z0-9._-]*$` up to 256
+  characters. Names production would have accepted (`rack.01`, `a`) raised
+  `ValueError` in the constructor before a single byte left the host, which
+  reads as an auth problem and is not one. The SDK now mirrors the wire rule.
+  Uuid-shaped ids are still rejected: the app resolves those as internal ids,
+  so such a source would be unreachable.
+
+- Buffer drains are chunked, so a backlog over the gateway's 10k-points-per-batch
+  ceiling no longer wedges every subsequent send. The WebSocket auth wait is paid
+  once, on the first send, instead of stalling each call.
+
+### Removed
+
+- `run()` context manager and its `POST /api/runs` plumbing. The `/api/runs` route never
+  existed on the platform (both notifications failed silently on every call), the ingest
+  loader drops `run_id` from points, and nothing was ever stored — so removal loses no
+  data. To group a slice of data, use `tags` on each point.
+
+### Security
+
+- Bumped pillow to 12.3.0 and idna to 3.19 for published advisories.
+
+## [0.8.0] - 2026-07-02 - Command concurrency control
+
+### Added
+
+- `concurrency` option on `on_command()` / `register_command()`. Defaults to `"accept"`
+  (unchanged behavior — overlapping invocations run concurrently). Set `"reject"` to refuse a
+  new invocation with an error result (`command already in progress: <name>`) while a previous
+  invocation of the same command is still running. Use it for handlers that drive exclusive
+  hardware (e.g. a pump init) so a client retry or double-click can't start two at once.
+  Protection is per command name; the immediate ack is still sent before the handler runs.
+
 ## [0.7.1] - 2026-06-02 - Remove install_id / source_id auto-suffix
 
 ### Changed
@@ -184,7 +237,7 @@
 
 ### Changed
 
-- Gateway WebSocket URL (`wss://plexus-gateway.fly.dev`) is now the SDK
+- Gateway WebSocket URL (`wss://gateway.plexus.company`) is now the SDK
   default — no need to pass `ws_url` explicitly.
 - Removed the `[plexus]   endpoint: …` line from the connection printout.
 
@@ -342,7 +395,7 @@ Breaking. `plexus-python` is now just the thin client — no agent, adapters, se
 
 ### Changed
 
-- Default ingest endpoint points directly at the Plexus gateway (`https://plexus-gateway.fly.dev/ingest`), not the Next.js app proxy
+- Default ingest endpoint points directly at the Plexus gateway (`https://gateway.plexus.company/ingest`), not the Next.js app proxy
 - Client raises `ValueError` clearly when no API key is available, instead of invoking a login flow
 
 ## [0.1.0] - Initial release

{plexus_python-0.7.1 → plexus_python-0.9.0}/PKG-INFO

@@ -1,12 +1,12 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.7.1
+Version: 0.9.0
 Summary: Thin Python SDK for Plexus — send telemetry in one line
-Project-URL: Homepage, https://plexus.dev
-Project-URL: Documentation, https://docs.plexus.dev
+Project-URL: Homepage, https://plexus.company
+Project-URL: Documentation, https://docs.plexus.company
 Project-URL: Repository, https://github.com/plexus-oss/plexus-python
 Project-URL: Issues, https://github.com/plexus-oss/plexus-python/issues
-Author-email: Plexus <hello@plexus.dev>
+Author-email: Plexus <info@plexus.company>
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: fleet,hardware,iot,monitoring,observability,telemetry
@@ -27,7 +27,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: opencv-python-headless>=4.8; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: ruff==0.15.12; extra == 'dev'
 Requires-Dist: websockets>=12; extra == 'dev'
 Provides-Extra: video
 Requires-Dist: numpy>=1.24; extra == 'video'
@@ -68,7 +68,7 @@ curl -sL https://app.plexus.company/setup | bash -s -- \
 
 The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
 
-**If two devices end up requesting the same name**, the gateway auto-suffixes: the first connection gets `drone-01`, the second gets `drone-01_2`, the third `drone-01_3`, and so on. The SDK logs the rename at INFO and persists the assigned name to `~/.plexus/config.json` so the device keeps its identity across reboots. Under the hood, a per-installation UUID (`install_id`, lazily generated on first run) is what lets the gateway tell "same device reconnecting" from "different device claiming the same name."
+**Names are not auto-deduplicated.** The gateway echoes back whatever `source_id` you declare, unchanged — pick a unique name per device (that's what `--name` and `source_id=...` are for). Two devices that declare the same name write into the same source.
 
 In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
 
@@ -111,7 +111,7 @@ px.send_batch([
 ])
 ```
 
-`points` is a list of `(metric, value)` tuples. All points share the same timestamp (now, unless you pass `timestamp=t`). For independent timestamps per point, call `send()` in a loop instead.
+`points` is a list of `(metric, value)` tuples, or `(metric, value, timestamp)` 3-tuples when you need a per-point timestamp. Points without their own timestamp share the batch timestamp (now, unless you pass `timestamp=t`).
 
 ### `event(name, data)` — record a discrete occurrence
 
@@ -125,16 +125,6 @@ px.event("sensor_error", {"sensor": "imu", "code": 42}, tags={"motor": "A"})
 
 The platform displays events as markers overlaid on your telemetry charts, not as time-series lines.
 
-### `run(run_id)` — group data into a named recording
-
-```python
-with px.run("thermal-cycle-001"):
-    while running:
-        px.send("temperature", read_temp())
-```
-
-All `send()` calls inside the context are tagged with `run_id`, making it easy to isolate and replay that slice of data in the dashboard.
-
 ## Video streaming
 
 Two methods depending on whether you control the capture loop or just have a URL.
@@ -228,8 +218,8 @@ px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no cor
 
 **Known limits:**
 - Clock sync refreshes on WebSocket (re)connect. A device with a drifting RTC that stays connected for many days accumulates uncorrected drift between reconnects.
-- HTTP-only transport (`transport="http"`) does not receive clock sync — timestamps default to the uncorrected device clock.
-- `send_batch()` shares one timestamp across the whole batch. For per-point timestamps, call `send()` in a loop.
+- The HTTP fallback path (used when the WebSocket is unavailable) does not receive clock sync — timestamps default to the uncorrected device clock.
+- `send_batch()` shares one timestamp across the batch by default; pass `(metric, value, timestamp)` 3-tuples for per-point timestamps.
 
 ## Transport
 
@@ -241,13 +231,12 @@ By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway
 If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
 
 ```python
-# default — ws with http fallback
+# ws with transparent http fallback — this is the only mode
 px = Plexus()
-
-# force http (legacy)
-px = Plexus(transport="http")
 ```
 
+There is no transport selector: the SDK always prefers the WebSocket and falls back to `POST /ingest` on its own when the socket is unavailable.
+
 ### Handling commands
 
 Register a handler before the first `send()` so the command is advertised in the auth frame:
@@ -270,8 +259,8 @@ The SDK sends an `ack` frame before invoking the handler, then a `result` frame
 | Variable                | Description                  | Default                          |
 | ----------------------- | ---------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key (required)           | none                             |
-| `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://plexus-gateway.fly.dev`   |
+| `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://gateway.plexus.company`   |
 
 ## Architecture