fix(skills): correct using-agent-relay drift and stale MCP names in sdk rule

.agents/skills/using-agent-relay/SKILL.md

@@ -77,6 +77,7 @@ Do not use older category-expanded names such as
 | `send_dm`             | Send a direct message to one agent                 |
 | `send_group_dm`       | Create a group DM and send the first message       |
 | `post_message`        | Post to a channel                                  |
+| `list_dms`            | List your direct-message conversations             |
 | `list_messages`       | Read channel history                               |
 | `reply_to_thread`     | Reply to an existing message                       |
 | `get_message_thread`  | Read a thread                                      |
@@ -198,38 +199,67 @@ remove_agent(name: "reviewer-1", reason: "Review accepted")
 
 ## Current CLI Reference
 
-Startup and status commands are intentionally omitted from these agent-facing
-examples. Published Agent Relay versions through 11.3.0 can print live
-workspace credentials when those commands run in a transcribed session. Upgrade
-to Agent Relay 11.3.1 or later before running them there.
+Prefer the MCP tools above for messaging. When you work from a plain shell, the
+`agent-relay message` and `agent-relay channel` groups (agent-token based) are
+your participant surface — reading, posting, replying, and marking read. The
+`agent-relay node` group is broker lifecycle and debug only.
 
-These are the current CLI forms for local broker and SDK-backed messaging
-operations:
+Export your credentials once instead of repeating them as flags. Command-line
+arguments are visible to other processes on the machine (`ps`), and they land in
+shell history and CI logs:
 
 ```bash
-agent-relay status
+export RELAY_WORKSPACE_KEY=rk_live_...
+export RELAY_AGENT_TOKEN=at_live_...
+export RELAY_BASE_URL=https://cast.agentrelay.com   # only to override the default
+```
+
+Messaging (agent token; these are how a participant reads and replies):
+
+```bash
+agent-relay message inbox check
+agent-relay message inbox mark_read msg_123
+agent-relay message dm send Lead "ACK: I am online."
+agent-relay message dm list "$CONVERSATION_ID"   # persistent DM history (unlike unread-only inbox check)
+agent-relay message post general "Status update"
+agent-relay message list general
+agent-relay message reply msg_123 "Thread reply"
+agent-relay message get_thread msg_123
+agent-relay channel list
+```
+
+Workspace identity:
+
+```bash
+agent-relay agent register Worker
+agent-relay agent list
+```
+
+Local broker lifecycle and debug (lifecycle only — read replies through the
+`message` group above, never `node tail`):
+
+```bash
+agent-relay status                       # workspace + cloud + broker overview
+agent-relay node up --background --verbose
+agent-relay node status --wait-for 10
 agent-relay node agent list
 agent-relay node agent spawn claude --name Worker --task "Use https://agentrelay.com/skill and ACK over Relay."
-agent-relay node tail --agent Worker
 agent-relay node agent attach Worker --mode view
 agent-relay node agent release Worker
-
-agent-relay agent register Worker --workspace-key rk_live_...
-agent-relay agent list --workspace-key rk_live_...
-agent-relay message inbox check --workspace-key rk_live_... --token at_live_...
-agent-relay message dm send Lead "ACK: I am online." --workspace-key rk_live_... --token at_live_...
-agent-relay message post general "Status update" --workspace-key rk_live_... --token at_live_...
-agent-relay message list general --workspace-key rk_live_... --token at_live_...
-agent-relay message reply msg_123 "Thread reply" --workspace-key rk_live_... --token at_live_...
+agent-relay node tail --agent Worker    # worker output/TTY, not durable messages
+agent-relay node tail                   # broker debug events (unfiltered), not messages
 ```
 
-Use environment variables instead of flags when available:
+These lifecycle commands live under `agent-relay node …`. The old flat
+`agent-relay local …` group still works as a hidden, deprecated alias (it prints
+a removal warning) — prefer `node`.
 
-```bash
-RELAY_WORKSPACE_KEY=rk_live_...
-RELAY_AGENT_TOKEN=at_live_...
-RELAY_BASE_URL=https://gateway.relaycast.dev
-```
+The `message`, `channel`, and `agent` groups also accept explicit
+`--workspace-key` / `--token` / `--base-url` flags, but only reach for them when
+you cannot set the environment. The `node` group does **not** take those — it
+talks to the local broker over its own `--broker-url` / `--api-key` /
+`--state-dir` flags (`RELAY_BROKER_URL`, `RELAY_BROKER_API_KEY`), and the
+`--workspace-key` on `node up` is a different flag with a different meaning.
 
 ## Common Mistakes
 

.claude/rules/sdk.md

@@ -53,10 +53,14 @@ The SDK uses subpath exports:
 
 ## Communication Protocol
 
-- **Primary**: MCP tools (`mcp__agent-relay__send_dm`,
-  `mcp__agent-relay__post_message`, `mcp__agent-relay__check_inbox`,
-  `mcp__agent-relay__list_agents`, `mcp__agent-relay__add_agent`,
-  `mcp__agent-relay__remove_agent`)
+- **Primary**: MCP tools. The canonical names are flat — `send_dm`,
+  `check_inbox`, `post_message`, `list_agents`, `add_agent`, `remove_agent`.
+  A client may decorate them with the configured server key, so Claude Code
+  users typically see `mcp__agent-relay__send_dm` while Codex and opencode see
+  the bare name.
+- Do **not** use the older category-expanded forms
+  (`mcp__relaycast__message_dm_send`, `relaycast.message.dm.send`,
+  `message.post`). They are not registered by `agent-relay mcp`.
 
 ## No Storage Layer
 

.claude/skills/using-agent-relay/SKILL.md

@@ -77,6 +77,7 @@ Do not use older category-expanded names such as
 | `send_dm`             | Send a direct message to one agent                 |
 | `send_group_dm`       | Create a group DM and send the first message       |
 | `post_message`        | Post to a channel                                  |
+| `list_dms`            | List your direct-message conversations             |
 | `list_messages`       | Read channel history                               |
 | `reply_to_thread`     | Reply to an existing message                       |
 | `get_message_thread`  | Read a thread                                      |
@@ -198,38 +199,67 @@ remove_agent(name: "reviewer-1", reason: "Review accepted")
 
 ## Current CLI Reference
 
-Startup and status commands are intentionally omitted from these agent-facing
-examples. Published Agent Relay versions through 11.3.0 can print live
-workspace credentials when those commands run in a transcribed session. Upgrade
-to Agent Relay 11.3.1 or later before running them there.
+Prefer the MCP tools above for messaging. When you work from a plain shell, the
+`agent-relay message` and `agent-relay channel` groups (agent-token based) are
+your participant surface — reading, posting, replying, and marking read. The
+`agent-relay node` group is broker lifecycle and debug only.
 
-These are the current CLI forms for local broker and SDK-backed messaging
-operations:
+Export your credentials once instead of repeating them as flags. Command-line
+arguments are visible to other processes on the machine (`ps`), and they land in
+shell history and CI logs:
 
 ```bash
-agent-relay status
+export RELAY_WORKSPACE_KEY=rk_live_...
+export RELAY_AGENT_TOKEN=at_live_...
+export RELAY_BASE_URL=https://cast.agentrelay.com   # only to override the default
+```
+
+Messaging (agent token; these are how a participant reads and replies):
+
+```bash
+agent-relay message inbox check
+agent-relay message inbox mark_read msg_123
+agent-relay message dm send Lead "ACK: I am online."
+agent-relay message dm list "$CONVERSATION_ID"   # persistent DM history (unlike unread-only inbox check)
+agent-relay message post general "Status update"
+agent-relay message list general
+agent-relay message reply msg_123 "Thread reply"
+agent-relay message get_thread msg_123
+agent-relay channel list
+```
+
+Workspace identity:
+
+```bash
+agent-relay agent register Worker
+agent-relay agent list
+```
+
+Local broker lifecycle and debug (lifecycle only — read replies through the
+`message` group above, never `node tail`):
+
+```bash
+agent-relay status                       # workspace + cloud + broker overview
+agent-relay node up --background --verbose
+agent-relay node status --wait-for 10
 agent-relay node agent list
 agent-relay node agent spawn claude --name Worker --task "Use https://agentrelay.com/skill and ACK over Relay."
-agent-relay node tail --agent Worker
 agent-relay node agent attach Worker --mode view
 agent-relay node agent release Worker
-
-agent-relay agent register Worker --workspace-key rk_live_...
-agent-relay agent list --workspace-key rk_live_...
-agent-relay message inbox check --workspace-key rk_live_... --token at_live_...
-agent-relay message dm send Lead "ACK: I am online." --workspace-key rk_live_... --token at_live_...
-agent-relay message post general "Status update" --workspace-key rk_live_... --token at_live_...
-agent-relay message list general --workspace-key rk_live_... --token at_live_...
-agent-relay message reply msg_123 "Thread reply" --workspace-key rk_live_... --token at_live_...
+agent-relay node tail --agent Worker    # worker output/TTY, not durable messages
+agent-relay node tail                   # broker debug events (unfiltered), not messages
 ```
 
-Use environment variables instead of flags when available:
+These lifecycle commands live under `agent-relay node …`. The old flat
+`agent-relay local …` group still works as a hidden, deprecated alias (it prints
+a removal warning) — prefer `node`.
 
-```bash
-RELAY_WORKSPACE_KEY=rk_live_...
-RELAY_AGENT_TOKEN=at_live_...
-RELAY_BASE_URL=https://gateway.relaycast.dev
-```
+The `message`, `channel`, and `agent` groups also accept explicit
+`--workspace-key` / `--token` / `--base-url` flags, but only reach for them when
+you cannot set the environment. The `node` group does **not** take those — it
+talks to the local broker over its own `--broker-url` / `--api-key` /
+`--state-dir` flags (`RELAY_BROKER_URL`, `RELAY_BROKER_API_KEY`), and the
+`--workspace-key` on `node up` is a different flag with a different meaning.
 
 ## Common Mistakes