docs: add a current Observer page built on scoped observer tokens

web/content/docs/7.1.1/observer.mdx

@@ -22,6 +22,15 @@ https://agentrelay.com/observer?key=<workspace_key>
 
 The TypeScript SDK exposes this directly as `relay.observerUrl` once the workspace key is available.
 
+<Note>
+  Do not do this on a current release. A workspace key is an administrative
+  credential — it can send messages, spawn agents, and change workspace
+  settings — and a URL query string is not a safe place for one. Current
+  versions provide `agent-relay observer`, which mints a scoped, expiring,
+  read-only observer token and builds the link from that instead. See the
+  current [Observer docs](https://agentrelay.com/docs/observer).
+</Note>
+
 ## When to use it
 
 Use Observer when you want visibility without control. If you need to chat, spawn agents, or manage the workspace interactively, use [Relay Dashboard](/docs/relay-dashboard).

web/content/docs/agent-relay-mcp.mdx

@@ -8,7 +8,7 @@ description: 'Expose Agent Relay messaging and registered actions to any agent a
 
 `agent-relay mcp` registers three groups of tools:
 
-- workspace and agent tools (`register_agent`, `list_agents`, `add_agent`, `remove_agent`, `create_workspace`, `set_workspace_key`, `spawn`, `submit_result`, `query_nodes`)
+- workspace and agent tools (`register_agent`, `list_agents`, `add_agent`, `remove_agent`, `create_workspace`, `set_workspace_key`, `spawn`, `submit_result`, `query_nodes`, `get_observer_url`)
 - messaging and inbox tools (the table below)
 - action tools (`list_actions`, `invoke_action`, plus one generated tool per registered action)
 
@@ -78,6 +78,25 @@ calling `spawn` or before asking an operator to bind an app-server agent to a no
 routes, not a workspace feature flag: a roster entry can be a direct connection, a broker-controlled
 WebSocket worker, an HTTP push endpoint, or a polling integration.
 
+## Observer Links
+
+`get_observer_url` mints a scoped, read-only observer token and returns a URL built from it, so an
+orchestrating agent can hand a watching human a follow-along link. Requires a workspace key on the
+session.
+
+| Input | Type | Description |
+| --- | --- | --- |
+| `channels` | `string[]` | Optional. Restrict the view to these channels. Omit to show every channel. |
+| `include_dms` | `boolean` | Optional. Include agent DM traffic. Defaults to `false`. |
+| `expires_in_hours` | `integer` | Optional. Token lifetime, 1–2160. Defaults to `24`. |
+
+Returns `url`, `tokenId`, `expiresAt`, `includesDms`, and `channels` when a channel filter was applied.
+Revoke a link early with `agent-relay observer revoke <tokenId>`.
+
+Never build an observer URL from the workspace key. `rk_live_*` is an administrative credential, and the
+realtime endpoint rejects it — only a scoped observer token with `stream:read` is accepted. See
+[Observer](/docs/observer).
+
 ## Generated Action Tools
 
 Each registered action becomes an explicit MCP tool.

web/content/docs/observer.mdx

@@ -0,0 +1,102 @@
+---
+title: 'Observer'
+metaTitle: 'Observer: Watch Agent Relay Traffic in Real Time'
+description: 'Share a read-only, expiring link so a human can follow an Agent Relay workspace live — messages, agent activity, and handoffs — without joining the run or handling a workspace key.'
+---
+
+Observer is a read-only view of a live workspace. Use it to let a human follow
+agent conversations, handoffs, and progress without joining the run as a
+participant.
+
+## What it shows
+
+- Messages as they move through the workspace
+- Agent activity and delivery updates in real time
+- A shareable live view for anyone who should watch but not participate
+
+## Get an observer link
+
+```bash
+agent-relay observer
+```
+
+That prints a URL you can share:
+
+```text
+https://agentrelay.com/observer?key=ot_live_...
+```
+
+The command mints a scoped **observer token** (`ot_live_...`) and builds the
+link from it. By default the token expires in 24 hours and excludes agent DMs.
+
+Narrow or widen it as needed:
+
+```bash
+agent-relay observer --channels build,review   # only these channels
+agent-relay observer --include-dms             # include agent DMs
+agent-relay observer --expires 7d              # longer-lived link
+agent-relay observer --json                    # token metadata + URL as JSON
+```
+
+Manage tokens you have handed out:
+
+```bash
+agent-relay observer list          # id, status, expiry (token material is never shown)
+agent-relay observer revoke <id>   # cut off a link immediately
+```
+
+An orchestrating agent can do the same through the Agent Relay MCP server with
+the `get_observer_url` tool, so a lead can hand you a link without shelling out.
+
+## Never share a workspace key
+
+A workspace key (`rk_live_...`) is an **administrative** credential: it can send
+messages, spawn and remove agents, and change workspace settings. Do not put one
+in an observer URL, a chat message, or a terminal transcript. Query strings end
+up in browser history, referrer headers, and proxy logs.
+
+An observer token is the credential built for this job:
+
+| | Workspace key (`rk_live_`) | Observer token (`ot_live_`) |
+| --- | --- | --- |
+| Read messages and activity | yes | yes |
+| Send messages, spawn agents, administer | yes | **no** |
+| Expires | no | yes |
+| Revocable individually | no | yes |
+| Scopable to channels | no | yes |
+
+The realtime endpoint enforces this: it rejects a workspace key outright and
+accepts only an observer token carrying the `stream:read` scope.
+
+## Self-hosted and staging
+
+Point the command at a different observer deployment with `--observer-url`, or
+set `RELAY_OBSERVER_URL`:
+
+```bash
+agent-relay observer --observer-url https://observer.relaycast.dev
+```
+
+## When to use it
+
+Use Observer when you want visibility without control. To chat, spawn agents, or
+manage the workspace interactively, use the Relay Dashboard instead — its page
+has not been brought forward past the
+[v7.1.1 archive](/docs/7.1.1/relay-dashboard) yet.
+
+## Related docs
+
+<CardGroup cols={2}>
+  <Card title="Authentication" href="/docs/authentication">
+    The credential types Agent Relay issues and what each one can do.
+  </Card>
+  <Card title="Agent Relay MCP" href="/docs/agent-relay-mcp">
+    Includes `get_observer_url` for orchestrating agents.
+  </Card>
+  <Card title="CLI reference" href="/docs/reference-cli">
+    Every `agent-relay` command, including `observer`.
+  </Card>
+  <Card title="Quickstart" href="/docs/quickstart">
+    Start a workspace and get agents talking.
+  </Card>
+</CardGroup>

web/content/docs/reference-cli.mdx

@@ -43,6 +43,32 @@ The SDK-backed groups are `agent`, `channel`, `message`, `integration`, `capabil
 | `agent-relay workspace switch <name>` | Switch the active stored workspace. |
 | `agent-relay workspace active [--json] [--api-url <url>] [--refresh-timeout <ms>]` | Show the active canonical cloud workspace. |
 
+## Observer
+
+Mint a read-only link so a human can follow a workspace live. See
+[Observer](/docs/observer) for the credential model.
+
+| Command | Description |
+| --- | --- |
+| `agent-relay observer [flags]` | Mint a scoped observer token and print the observer URL built from it. |
+| `agent-relay observer list [--json]` | List observer tokens for the workspace. Raw token material is never shown. |
+| `agent-relay observer revoke <id>` | Revoke an observer token immediately. |
+
+| Flag | Description |
+| --- | --- |
+| `--channels <names>` | Restrict the view to a comma-separated list of channels. |
+| `--include-dms` | Include agent DM traffic. Excluded by default. |
+| `--expires <duration>` | Token lifetime such as `30m`, `24h`, `7d`. Defaults to `24h`, maximum `90d`. |
+| `--name <name>` | Token name. Defaults to a generated unique name. |
+| `--observer-url <url>` | Observer dashboard URL (`RELAY_OBSERVER_URL`). Defaults to `https://agentrelay.com/observer`. |
+| `--json` | Print the token metadata and URL as JSON. |
+
+All three accept `--workspace-key` and `--base-url`. `observer` is not one of
+the SDK-backed groups above — it declares those two flags itself and takes no
+`--token`, because minting an observer token requires the workspace key; an
+agent token cannot do it. The minted token is read-only and expiring — never
+build an observer URL from a workspace key.
+
 ## Agents
 
 | Command | Description |

web/lib/docs-nav.ts

@@ -56,6 +56,7 @@ export const docsNav: NavGroup[] = [
     items: [
       { title: 'TypeScript SDK', slug: 'typescript-sdk' },
       { title: 'Agent Relay MCP', slug: 'agent-relay-mcp' },
+      { title: 'Observer', slug: 'observer' },
     ],
   },
   {