docs: describe nodes, node pools and the current control plane

docs/CLAUDE.md

@@ -176,14 +176,16 @@ Applies to everything published on the website.
 
 - The service that routes, schedules, and persists is the **control plane**.
   Never "engine", "server", or "orchestrator".
-- A process running user code with the Rivet SDK is a **worker**. Never "envoy",
-  "runner", "node", "compute", or "data plane".
+- A process running user code with the Rivet SDK is a **node**; nodes sharing a
+  pool name form a **node pool**. Never "envoy", "runner", "worker", "compute" or
+  "data plane". Say "Node.js" for the runtime, "Kubernetes node" for cluster
+  machines, and "control plane instance" for one control plane process.
 - **Never use "agent" as a deployment noun.** Rivet ships agentOS and Actors is
   "where agents live"; the collision is unrecoverable.
 - **"envoy" never appears in docs.** Envoy Proxy is a top-tier CNCF project.
   Internal code keeps its own names.
-- **"Rivet Compute" is retired.** Where prose must name the managed offering it
-  is **Rivet Cloud**, and it links to <https://dashboard.rivet.dev>.
+- **Rivet Cloud** is the managed offering. There is no Rivet dashboard; never link one.
+  Keep its deployment documentation, including managed backend hosting.
 - Spell the product `agentOS`, never `AgentOS`. Capitalize **Rivet Actor** as a
   proper noun, lowercase generic "actor".
 - Always `rivet.dev`, never `rivet.gg`.

docs/actors/content/docs/actions.mdx

@@ -128,8 +128,12 @@ Rivet provides the `ActionContextOf` utility type for exactly this purpose:
 
 See [types](/actors/docs/types) for more details on using `ActionContextOf` and other utility types.
 
+{/* TODO(code): restore when the control plane exposes an API to read an Actor's inspector token. Tracked in ACT-6493.
+
 ## Debugging
 
 - `GET /inspector/rpcs` lists all available actions on an actor.
 - `POST /inspector/action/:name` executes an action with JSON args and returns output.
 - In non-dev mode, inspector endpoints require authorization.
+
+*/}

docs/actors/content/docs/appearance.mdx

@@ -1,10 +1,10 @@
 ---
 title: Icons & Names
-description: "Configure display names and icons for Rivet Actors so each instance is easy to recognize in the dashboard and inspector."
+description: "Configure display names and icons for Rivet Actors so each instance is easy to recognize in the inspector."
 skill: true
 ---
 
-Actors can be customized with a display name and icon that appear in the Rivet inspector & dashboard. This helps identify actors at a glance when managing your application.
+Actors can be customized with a display name and icon that appear in the Rivet inspector. This helps identify actors at a glance when managing your application.
 
 ## Configuration
 
@@ -50,7 +50,7 @@ Users can then use this directly:
 
 <CodeSnippet file="examples/docs/actors-appearance/run-handler-usage.ts" />
 
-This run-handler metadata is currently applied through the registry and serverless metadata paths. The native runtime and inspector config read the actor's `options.name` and `options.icon` directly, so set those explicitly if you need the name or icon to appear everywhere.
+This run-handler metadata is applied through the registry metadata. The native runtime and inspector config read the actor's `options.name` and `options.icon` directly, so set those explicitly if you need the name or icon to appear everywhere.
 
 Actor-level `options.name` and `options.icon` always take precedence, allowing users to override library defaults:
 

docs/actors/content/docs/clients/javascript.mdx

@@ -97,10 +97,10 @@ Defaults to `http://localhost:6420` when unset. RivetKit runs on port 6420 by de
 Endpoints support URL auth syntax:
 
 ```
-https://namespace:token@api.rivet.dev
+https://namespace:token@rivet.example.com
 ```
 
-You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. For serverless deployments, use your app's `/api/rivet` URL. See [Connect](/docs/connect#url-auth-syntax) for details.
+You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. See [Endpoints](/docs/connect#url-auth-syntax) for details.
 
 ## Advanced
 

docs/actors/content/docs/clients/react.mdx

@@ -99,10 +99,10 @@ Defaults to `http://localhost:6420` when unset. RivetKit runs on port 6420 by de
 Endpoints support URL auth syntax:
 
 ```
-https://namespace:token@api.rivet.dev
+https://namespace:token@rivet.example.com
 ```
 
-You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. For serverless deployments, use your app's `/api/rivet` URL. See [Connect](/docs/connect#url-auth-syntax) for details.
+You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. See [Endpoints](/docs/connect#url-auth-syntax) for details.
 
 ## API Reference
 

docs/actors/content/docs/clients/rust.mdx

@@ -348,18 +348,18 @@ use rivetkit::client::ClientConfig;
 
 let config = ClientConfig::new("http://localhost:6420")
 	.namespace("default")
-	.token("pk_...")
+	.token("<scoped-token>")
 	.pool_name("my-pool")
 	.header("x-custom", "value");
 ```
 
 - `namespace` - target namespace (defaults to the control plane's configured namespace).
 - `token` - authentication token for the control plane.
-- `pool_name` - runner pool to target.
+- `pool_name` - node pool to target.
 - `header` / `headers` - extra HTTP headers sent with each request.
 - `max_input_size` - cap on encoded action input size.
 
-For serverless deployments, set the endpoint to your app's `/api/rivet` URL. See [Connect](/docs/connect) for details.
+See [Endpoints](/docs/connect) for details.
 
 ## API Reference
 

docs/actors/content/docs/clients/swift.mdx

@@ -34,7 +34,7 @@ targets: [
 import RivetKitClient
 
 let config = try ClientConfig(
-    endpoint: "https://my-namespace:pk_...@api.rivet.dev"
+    endpoint: "https://my-namespace@rivet.example.com"
 )
 let client = RivetKitClient(config: config)
 
@@ -49,9 +49,9 @@ let count: Int = try await handle.action("increment", 1, as: Int.self)
 import RivetKitClient
 
 let config = try ClientConfig(
-    endpoint: "https://api.rivet.dev",
+    endpoint: "https://rivet.example.com",
     namespace: "my-namespace",
-    token: "pk_..."
+    token: "<scoped-token>"
 )
 let client = RivetKitClient(config: config)
 
@@ -411,7 +411,7 @@ Don't build keys with string interpolation like `"org:\(userId)"` when `userId`
 
 - `RIVET_NAMESPACE` - Namespace (can also be in endpoint URL)
 - `RIVET_TOKEN` - Authentication token (can also be in endpoint URL)
-- `RIVET_RUNNER` - Runner name (defaults to `"default"`)
+{/* TODO(code): document `RIVET_POOL` here once the Swift client reads it; today it reads only its older pool variable. */}
 
 The `endpoint` parameter is always required. There is no default endpoint.
 
@@ -420,10 +420,10 @@ The `endpoint` parameter is always required. There is no default endpoint.
 Endpoints support URL auth syntax:
 
 ```
-https://namespace:token@api.rivet.dev
+https://namespace:token@rivet.example.com
 ```
 
-You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. For serverless deployments, set the endpoint to your app's `/api/rivet` URL. See [Connect](/docs/connect#url-auth-syntax) for details.
+You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. See [Endpoints](/docs/connect#url-auth-syntax) for details.
 
 ## API Reference
 

docs/actors/content/docs/clients/swiftui.mdx

@@ -38,7 +38,7 @@ struct HelloWorldApp: App {
     var body: some Scene {
         WindowGroup {
             ContentView()
-                .rivetKit(endpoint: "https://my-namespace:pk_...@api.rivet.dev")
+                .rivetKit(endpoint: "https://my-namespace@rivet.example.com")
         }
     }
 }
@@ -289,7 +289,7 @@ struct MyApp: App {
     var body: some Scene {
         WindowGroup {
             ContentView()
-                .rivetKit(endpoint: "https://my-namespace:pk_...@api.rivet.dev")
+                .rivetKit(endpoint: "https://my-namespace@rivet.example.com")
         }
     }
 }
@@ -298,7 +298,7 @@ struct MyApp: App {
 @main
 struct MyApp: App {
     private let client = RivetKitClient(
-        config: try! ClientConfig(endpoint: "https://api.rivet.dev", token: "pk_...")
+        config: try! ClientConfig(endpoint: "https://rivet.example.com", token: "<scoped-token>")
     )
 
     var body: some Scene {
@@ -318,7 +318,7 @@ When using `.rivetKit(endpoint:)`, the client is created once and cached per end
 
 - `RIVET_NAMESPACE` - Namespace (can also be in endpoint URL)
 - `RIVET_TOKEN` - Authentication token (can also be in endpoint URL)
-- `RIVET_RUNNER` - Runner name (defaults to `"default"`)
+{/* TODO(code): document `RIVET_POOL` here once the Swift client reads it; today it reads only its older pool variable. */}
 
 The endpoint is always required. There is no default endpoint.
 
@@ -327,10 +327,10 @@ The endpoint is always required. There is no default endpoint.
 Endpoints support URL auth syntax:
 
 ```
-https://namespace:token@api.rivet.dev
+https://namespace:token@rivet.example.com
 ```
 
-You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. For serverless deployments, set the endpoint to your app's `/api/rivet` URL. See [Connect](/docs/connect#url-auth-syntax) for details.
+You can also pass the endpoint without auth and provide `RIVET_NAMESPACE` and `RIVET_TOKEN` separately. See [Endpoints](/docs/connect#url-auth-syntax) for details.
 
 ## API Reference
 

docs/actors/content/docs/crash-course.mdx

@@ -9,7 +9,7 @@ skill: false
 ## Features
 
 - **Long-Lived, Stateful Compute**: Each unit of compute is like a tiny server that remembers things between requests – no need to re-fetch data from a database or worry about timeouts. Like AWS Lambda, but with memory and no timeouts.
-- **Blazing-Fast Reads & Writes**: State is stored on the same machine as your compute, so reads and writes are ultra-fast. No database round trips, no latency spikes. State is persisted to Rivet for long term storage, so it survives server restarts.
+- **Blazing-Fast Reads & Writes**: State lives in memory next to your code, so reads are instant and writes return without waiting on a separate database. Every actor's data is persisted to a durable, replicated volume, so it survives restarts and moves between nodes.
 - **Realtime**: Update state and broadcast changes in realtime with WebSockets. No external pub/sub systems, no polling – just built-in low-latency events.
 - **Infinitely Scalable**: Automatically scale from zero to millions of concurrent actors. Pay only for what you use with instant scaling and no cold starts.
 - **Fault Tolerant**: Built-in error handling and recovery. Actors automatically restart on failure while preserving state integrity and continuing operations.
@@ -245,7 +245,7 @@ Create one actor per user, document, or room. Use compound keys to scope entitie
 
 ### Coordinator & Data Actors
 
-**Data actors** handle core logic (chat rooms, game sessions, user data). **Coordinator actors** track and manage collections of data actors—think of them as an index.
+**Data actors** handle core logic (chat rooms, game sessions, user data). **Coordinator actors** track and manage collections of data actors. think of them as an index.
 
 <CodeGroup>
 <CodeSnippet file="examples/docs/actors-crash-course/coordinator/index.ts" title="index.ts" />
@@ -277,11 +277,11 @@ Use this pattern for long-lived, durable workflows that initialize resources, pr
 - Use `c.conn.state` to securely identify users in actions rather than trusting action parameters.
 - For cross-origin access, validate the request origin in `onBeforeConnect`.
 
-[Authentication Documentation](/docs/authentication) · [Permissions Documentation](/actors/docs/permissions) · [CORS Documentation](/actors/docs/cors)
+[Authentication Documentation](/actors/docs/permissions) · [CORS Documentation](/actors/docs/cors)
 
 ### Versions & Upgrades
 
-When deploying new code, set a version number so Rivet can route new actors to the latest runner and optionally drain old ones. Use a build timestamp, git commit count, or CI build number as the version. It is very important to [configure versioning](/docs/versions) before deploying to production. Without versioning, actors can regress by running on older runner versions, and existing actors will never be forced to migrate to new runners. They will continue running indefinitely on the old runners until they exit.
+Deploy new code by rolling your nodes. When a node stops, its actors sleep and wake on a running node with their state intact, so keep each deploy compatible with the state the previous one wrote. See [Versions & Upgrades](/docs/versions).
 
 [Documentation](/docs/versions)
 

docs/actors/content/docs/debugging.mdx

@@ -1,11 +1,11 @@
 ---
 title: "Debugging Actors"
-description: "Inspect a running Rivet Actor through its gateway endpoints and the actor inspector API, including state, connections, and workflow history."
+description: "Inspect a running Rivet Actor through its gateway endpoints."
 skill: true
 ---
 
 Every endpoint here is reached through the gateway using an actor ID. To find
-actor IDs, list runners, or read provider config, see [Debugging](/docs/debugging)
+actor IDs or check on your nodes, see [Debugging](/docs/debugging)
 in the platform docs. That page also defines the `$RIVET_API`, `$RIVET_NAMESPACE`,
 and `$RIVET_TOKEN` shell variables used throughout the examples below.
 
@@ -16,31 +16,32 @@ All actor-level endpoints are accessed through the gateway. The gateway routes r
 {RIVET_API}/gateway/{actor_id}/{path}
 ```
 
-The gateway only accepts actor IDs, not names. Use `GET /actors?name=...` from the management API to look up actor IDs first.
+The gateway can also find an actor by name and key from query parameters. See [Actor Routing](/docs/api/actor-routing).
 
 ## Authentication
 
-Standard actor endpoints (health, actions, requests) and inspector endpoints have separate authentication requirements.
+Standard actor endpoints (health, actions, requests) use the same authentication as the rest of the gateway.
 
 ### Standard Endpoints
 
 | Environment | Authentication |
 |---|---|
 | **Local development** | No authentication required. |
-| **Self-hosted engine** | The Rivet control plane handles authentication at the gateway level. |
+| **Self-hosted** | The Rivet control plane handles authentication at the gateway level. |
 | **Rivet Cloud** | Authentication is handled by the Rivet Cloud platform at the gateway level. |
 
+{/* TODO(code): restore when the control plane exposes an API to read an Actor's inspector token. Tracked in ACT-6493.
+
 ### Inspector Endpoints
 
-Each actor generates a unique inspector token on first start and persists it in internal SQLite storage. It is also mirrored to legacy KV key `0x03` (base64 `Aw==`) for dashboard compatibility. Pass it as a bearer token in the `Authorization` header.
+Each actor generates a unique inspector token on first start and stores it with its data. Pass it as a bearer token in the `Authorization` header.
 
 Inspector endpoints always require the actor's inspector token, including in local development. There is no local-development bypass.
 
 | Environment | Authentication |
 |---|---|
-| **Local development** | Bearer the actor's inspector token in the `Authorization` header. Fetch it through the management KV endpoint (see below). |
-| **Self-hosted engine** | Bearer the actor's inspector token in the `Authorization` header. The Rivet dashboard fetches it automatically; for direct API access, fetch it through the management KV endpoint (see below). |
-| **Rivet Cloud** | Bearer the actor's inspector token in the `Authorization` header. The Rivet dashboard fetches it automatically; for direct API access, fetch it through the management KV endpoint (see below). |
+| **Local development** | Bearer the actor's inspector token in the `Authorization` header. |
+| **Self-hosted** | Bearer the actor's inspector token in the `Authorization` header. |
 
 ```bash
 curl "$RIVET_API/gateway/{actor_id}/inspector/summary" \
@@ -49,24 +50,7 @@ curl "$RIVET_API/gateway/{actor_id}/inspector/summary" \
 
 ### Retrieving the Inspector Token
 
-Each actor generates a unique inspector token on first start and persists it in internal SQLite storage. The token is also mirrored to the legacy KV key below so the Rivet dashboard can continue to retrieve it through the management KV endpoint. This applies in every environment, including local development.
-
-The inspector token is stored at internal KV key `0x03` (base64: `Aw==`). The response value is also base64-encoded.
-
-```bash
-# Fetch the inspector token for a specific actor
-ACTOR_ID="your-actor-id"
-
-RESPONSE=$(curl -s "$RIVET_API/actors/$ACTOR_ID/kv/keys/Aw==" \
-  -H "Authorization: Bearer $RIVET_TOKEN")
-
-# Extract and decode the base64 value
-INSPECTOR_TOKEN=$(echo "$RESPONSE" | jq -r '.value' | base64 -d)
-
-# Use it to call inspector endpoints
-curl "$RIVET_API/gateway/$ACTOR_ID/inspector/summary" \
-  -H "Authorization: Bearer $INSPECTOR_TOKEN"
-```
+*/}
 
 ## Standard Actor Endpoints
 
@@ -112,6 +96,8 @@ The `response` field is only present when the queue handler returns a value:
 
 If `wait: true` and the timeout is reached, `status` is `"timedOut"`.
 
+{/* TODO(code): restore when the control plane exposes an API to read an Actor's inspector token. Tracked in ACT-6493.
+
 ## Inspector Endpoints
 
 The inspector HTTP API exposes JSON endpoints for querying and modifying actor internals at runtime. These are designed for agent-based debugging and tooling.
@@ -394,3 +380,4 @@ When workflow history is present in `/inspector/summary`, `workflowHistory` is r
 
 Inspector endpoints are safe to poll. For live monitoring, poll at 1-5 second intervals. The `/inspector/summary` endpoint is useful for periodic snapshots since it returns all data in a single request.
 
+*/}

docs/actors/content/docs/destroy.mdx

@@ -10,7 +10,7 @@ skill: true
 - Cleaning up temporary resources
 - GDPR/compliance data removal
 
-Actors sleep when idle, so destruction is only needed to permanently remove data — not to save compute.
+Actors sleep when idle, so destruction is only needed to permanently remove data; not to save compute.
 
 ## Destroying An Actor
 
@@ -22,10 +22,7 @@ To destroy an actor, use `c.destroy()` like this:
 
 ### Destroy via HTTP
 
-Send a DELETE request to destroy an actor. This requires a token for authentication:
-
-- **Rivet Cloud**: Use the service key (`sk_*`) from your `RIVET_ENDPOINT` URL. Find this in the dashboard under **Settings > Advanced > Backend Configuration** (e.g. the `sk_...` portion of `https://default:sk_abc123@api.rivet.dev`).
-- **Self-hosted**: Use an admin token.
+Send a DELETE request to your control plane to destroy an actor. Authenticate with your Rivet token.
 
 <CodeGroup>
 
@@ -34,7 +31,7 @@ const actorId = "your-actor-id";
 const namespace = "default";
 const token = "your-token";
 
-await fetch(`https://api.rivet.dev/actors/${actorId}?namespace=${namespace}`, {
+await fetch(`https://rivet.example.com/actors/${actorId}?namespace=${namespace}`, {
   method: "DELETE",
   headers: {
     Authorization: `Bearer ${token}`,
@@ -43,22 +40,18 @@ await fetch(`https://api.rivet.dev/actors/${actorId}?namespace=${namespace}`, {
 ```
 
 ```bash
-curl -X DELETE "https://api.rivet.dev/actors/{actorId}?namespace={namespace}" \
+curl -X DELETE "https://rivet.example.com/actors/{actorId}?namespace={namespace}" \
   -H "Authorization: Bearer {token}"
 ```
 </CodeGroup>
 
-To find the actor ID, you can list actors first:
+To find the actor ID, list the actors with that name first:
 
 ```bash
-curl "https://api.rivet.dev/actors?namespace={namespace}" \
+curl "https://rivet.example.com/actors?namespace={namespace}&name={actor-name}" \
   -H "Authorization: Bearer {token}"
 ```
 
-### Destroy via Dashboard
-
-To destroy an actor via the dashboard, navigate to the actor and press the red "X" in the top right.
-
 ## Lifecycle Hook
 
 Once destroyed, the `onDestroy` hook will be called. This can be used to clean up resources related to the actor. For example: