From 6e4eef4a49f77413c37a91a3262e4ffd950fcb17 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 20 Dec 2025 12:56:06 +0000
Subject: [PATCH] docs(skill): add clawdis nodes

---
 skills/clawdis-nodes/SKILL.md | 89 +++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 skills/clawdis-nodes/SKILL.md

diff --git a/skills/clawdis-nodes/SKILL.md b/skills/clawdis-nodes/SKILL.md
new file mode 100644
index 000000000..79e52e49b
--- /dev/null
+++ b/skills/clawdis-nodes/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: clawdis-nodes
+description: Discover, interpret, and target Clawdis nodes (paired devices) via the Gateway/CLI. Use when an agent must find available nodes, choose the best target machine, or reason about presence vs node availability (Tailnet/Tailscale optional).
+---
+
+# Clawdis Nodes
+
+Use the node system to target specific devices (macOS node mode, iOS, Android) for canvas/camera/screen/system actions. Use presence to infer which **user machine** is active, then pick the matching node.
+
+## Quick start
+
+List known nodes and whether they are paired/connected:
+```bash
+clawdis nodes status
+```
+
+Inspect a specific node (commands, caps, permissions):
+```bash
+clawdis nodes describe --node <idOrNameOrIp>
+```
+
+## Node discovery workflow (agent)
+
+1) **List nodes** with `clawdis nodes status`.
+2) **Choose a target**:
+   - Prefer `connected` nodes with the capabilities you need.
+   - Use `perms` (permissions map) to avoid asking for actions that will fail.
+3) **Confirm commands** with `clawdis nodes describe --node …`.
+4) **Invoke actions** via `clawdis nodes …` (camera, canvas, screen, system).
+
+If no nodes are connected:
+- Check pairing: `clawdis nodes pending` / `clawdis nodes list`
+- Ask the user to open/foreground the node app if the action requires it (canvas/camera/screen on iOS/Android).
+
+## Presence vs nodes (don’t confuse them)
+
+**Presence** shows Gateway + connected clients (mac app, WebChat, CLI).  
+**Nodes** are paired devices that expose commands.
+
+Use presence to infer **where the user is active**, then map that to a node:
+
+```bash
+clawdis gateway call system-presence
+```
+
+Heuristics:
+- Pick the presence entry with the smallest `lastInputSeconds` (most active).
+- Match presence `host` / `deviceFamily` to a node `displayName` / `deviceFamily`.
+- If multiple matches, ask for clarification or use `nodes describe` to choose.
+
+Note: CLI connections (`client.mode=cli`) do **not** show up in presence.
+
+## Tailnet / Tailscale (optional context)
+
+Node discovery is Gateway‑owned; Tailnet details only matter for reaching the Gateway:
+- On LAN, the Gateway advertises a Bridge via Bonjour.
+- Cross‑network, prefer Tailnet MagicDNS or Tailnet IP to reach the Gateway.
+- Once connected, always target nodes by id/name/IP via the Gateway (not direct).
+
+## Pairing & approvals
+
+List pairing requests:
+```bash
+clawdis nodes pending
+```
+
+Approve/reject:
+```bash
+clawdis nodes approve <requestId>
+clawdis nodes reject <requestId>
+```
+
+## Typical agent usages
+
+Send a notification to a specific Mac node:
+```bash
+clawdis nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
+```
+
+Capture a node canvas snapshot:
+```bash
+clawdis nodes canvas snapshot --node <idOrNameOrIp> --format png
+```
+
+## Troubleshooting
+
+- `NODE_BACKGROUND_UNAVAILABLE`: the node app must be foregrounded (iOS/Android).
+- Missing permissions in `nodes status`: ask the user to grant permissions in the node app.
+- No connected nodes: ensure the Gateway is reachable; check tailnet/SSH config if remote.