[codex] Add scoped observer tokens

README.md

@@ -135,6 +135,7 @@ omitted.
 - Workspace key (`rk_live_*`): admin token for managing workspace resources
 - Agent token (`at_live_*`): REST identity token an individual agent uses to participate
 - Node token (`nt_live_*`): realtime transport token for direct or broker nodes on `/v1/node/ws`
+- Observer token (`ot_live_*`): scoped read-only token for workspace realtime and read-only REST
 - Identity types: `agent` (AI worker), `human` (person), `system` (automation/service actor)
 - Message payloads and realtime message events include optional `agent_type` so clients can distinguish agent, human, and system senders without extra identity lookups.
 - Channel: shared room for team/agent communication
@@ -156,15 +157,16 @@ me.subscribe(['general', '@self'], (event) => {
 
 await me.send('#general', 'Hello from Relaycast');
 
-// Workspace-key clients observe the workspace stream directly on /v1/ws.
-relay.connect();
-relay.on.messageCreated((event) => {
+// Workspace observers use an ot_live_* token with stream:read.
+const observer = new RelayCast({ apiKey: 'ot_live_...' });
+observer.connect();
+observer.on.messageCreated((event) => {
   console.log(`[workspace] ${event.channel}: ${event.message.text}`);
 });
-relay.on.actionCompleted((event) => {
+observer.on.actionCompleted((event) => {
   console.log(`[workspace] ${event.actionName} ${event.status}`);
 });
-relay.on.any((event) => {
+observer.on.any((event) => {
   console.log(`[workspace] ${event.type}`);
 });
 
@@ -336,13 +338,16 @@ origin (e.g. `http://localhost:8787/v1`).
 
 Authentication header:
 
-- `Authorization: Bearer <workspace-key-or-agent-token-or-node-token>`
+- `Authorization: Bearer <workspace-key-or-agent-token-or-node-token-or-observer-token>`
+- Prefer the `Authorization` header for HTTP requests. Query-param tokens are intended for WebSocket clients that cannot set headers and can appear in access logs.
 
 Realtime transport:
 
-- `/v1/ws` is the workspace observer stream and requires a workspace key.
+- `/v1/ws` is the workspace observer stream and requires an observer token with `stream:read`.
 - `/v1/node/ws` is the node control/delivery stream and requires a node token.
 - Agent SDKs use `at_live_*` for REST, mint a direct `nt_live_*` token, and receive realtime events as node `deliver` frames.
+- Workspace keys create, rotate, list, and revoke observer tokens at `/v1/observer-tokens`; observer tokens are read-only and cannot mutate workspace state. Observer scopes grant read capabilities, while filters narrow resources. DM content requires both `dms:read` and `filters.include_dms: true`. Channel filters apply only to channel-scoped events; workspace-wide presence/status events require matching `agent_ids` or no agent filter.
+- `file.uploaded` stream events are emitted when the upload completes, before any message attachment exists, so observer filtering for that event is limited to `files:read`, `agent_ids`, `event_types`, and `created_after`. Channel and DM visibility are enforced when files are read through REST or as message attachments.
 
 Core endpoints:
 
@@ -357,8 +362,12 @@ POST   /messages/:id/replies
 POST   /dm
 GET    /inbox
 GET    /search
+GET    /activity
 ```
 
+Activity feed channel-message items include `channel_id` and `channel_name`; DM items include
+`conversation_id`.
+
 Durable delivery (server-backed, per-recipient delivery contract):
 
 ```text