docs(skills): explain cross-host agent workflows

skills/paseo/SKILL.md

@@ -1,10 +1,31 @@
 ---
 name: paseo
-description: Paseo reference for managing projects, workspaces, workspace scripts, agents, schedules, and heartbeats.
+description: Paseo reference for managing hosts, projects, workspaces, workspace scripts, agents, schedules, and heartbeats.
 ---
 
 Paseo is a remote daemon that manages coding agents, terminals. Control it through MCP tools or the CLI.
 
+## Connected hosts
+
+Call `list_hosts` to discover the calling daemon (`self`) and its registered destinations (`hosts`). Use a destination's `serverId` for tool calls; labels are display names.
+
+`create_workspace`, `list_workspaces`, `create_agent`, `send_agent_prompt`, `get_agent_status`, `get_agent_activity`, and `list_agents` accept `serverId`. Omit it for the calling daemon. Other MCP tools operate on the calling daemon.
+
+Keep an agent's `{ serverId, agentId }` together. For example, call `send_agent_prompt` with:
+
+```json
+{ "serverId": "srv_build", "agentId": "agent_123", "prompt": "Continue", "notifyOnFinish": true }
+```
+
+Remote paths and workspace IDs belong to the destination. Remote `list_agents` has no caller-directory default; pass `cwd` to filter it.
+
+Manage registrations through the CLI; use the returned `registrationId` for updates and removal:
+
+```bash
+paseo --host localhost:6768 host add localhost:6779 --label build
+paseo --host localhost:6768 host ls --json
+```
+
 ## Projects
 
 Manage the daemon's project registry through the CLI:
@@ -57,7 +78,7 @@ paseo script stop <name> [--cwd <path> | --workspace <workspace-id>]
 
 Initial runtime settings live under `settings`: `modeId`, `thinkingOptionId`, and provider-specific `features`. Agent profiles are the preferred source for these values. For Codex fast mode, pass `settings: { features: { "fast_mode": true } }` when creating the agent.
 
-Agent-scoped creation always creates your subagent. Omit `workspaceId` to use your current workspace; pass a workspace returned by `create_workspace` for isolated delegation. Placement never changes parentage.
+Agent-scoped creation always creates your subagent. On your own host, omit `workspaceId` to use your current workspace. On another host, first list or create a workspace with that `serverId`, then pass its `workspaceId` and the same `serverId` to `create_agent`. Placement never changes parentage.
 
 Detach is an explicit user action in the subagents track, not an agent tool. A cross-workspace child remains your subagent even though it also appears as a normal tab in its workspace.
 
@@ -110,7 +131,11 @@ Agents take time — 10–30+ minutes is routine. Favor asynchronous workflows.
 
 `create_agent` returns after startup. Agent-scoped `send_agent_prompt` returns after queue admission; provider dispatch follows after two quiet seconds. Top-level sends return after dispatch acknowledgement. Top-level callers have no parent callback; observe completion through status/activity tools or SDK/RPC subscriptions and wait APIs.
 
-For agent-scoped `create_agent` and `send_agent_prompt`, `notifyOnFinish` defaults to `true`. The caller receives the target’s completion, error, or permission report automatically, including its last response. Finish your turn with the result for automatic reporting. For a workflow that reports explicitly with `send_agent_prompt`, set `notifyOnFinish: false` when assigning the task. Paseo supplies caller identity for agent-scoped tools and CLI agent context; use that supplied identity.
+For agent-scoped `create_agent` and `send_agent_prompt`, `notifyOnFinish` defaults to `true`. The caller receives the target’s completion, error, or permission report automatically, including its last response. Finish your turn with the result for automatic reporting. Paseo supplies caller identity for agent-scoped tools and CLI agent context; use that supplied identity.
+
+Completion notifications return across hosts without a reverse registration. Explicit cross-host `send_agent_prompt` messages need the recipient's host registered on the sender's daemon. Registering A → B does not let B address A over that connection; reverse connection reuse is not implemented. Before assigning explicit reporting with `notifyOnFinish: false`, have the sender check `list_hosts` for the recipient's server.
+
+Remote finish notifications report idle, not an exact turn. A caller-daemon restart or route loss ends the pending wait; query the child’s status or activity before deciding whether to send another prompt.
 
 With finish notifications enabled, don't poll `list_agents` or `get_agent_status` to "check on" a running agent. The notification will tell you.