docs: refresh pairing devices and dns refs

docs/cli/devices.md

@@ -75,6 +75,8 @@ Rotate a device token for a specific role (optionally updating scopes).
 openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
 ```
 
+Returns the new token payload as JSON.
+
 ### `openclaw devices revoke --device <id> --role <role>`
 
 Revoke a device token for a specific role.
@@ -83,6 +85,8 @@ Revoke a device token for a specific role.
 openclaw devices revoke --device <deviceId> --role node
 ```
 
+Returns the revoke result as JSON.
+
 ## Common options
 
 - `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
@@ -100,6 +104,7 @@ Pass `--token` or `--password` explicitly. Missing explicit credentials is an er
 - These commands require `operator.pairing` (or `operator.admin`) scope.
 - `devices clear` is intentionally gated by `--yes`.
 - If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
+- `devices approve` picks the newest pending request automatically when you omit `requestId` or pass `--latest`.
 
 ## Token drift recovery checklist
 

docs/cli/dns.md

@@ -19,5 +19,30 @@ Related:
 
 ```bash
 openclaw dns setup
+openclaw dns setup --domain openclaw.internal
 openclaw dns setup --apply
 ```
+
+## `dns setup`
+
+Plan or apply CoreDNS setup for unicast DNS-SD discovery.
+
+Options:
+
+- `--domain <domain>`: wide-area discovery domain (for example `openclaw.internal`)
+- `--apply`: install or update CoreDNS config and restart the service (requires sudo; macOS only)
+
+What it shows:
+
+- resolved discovery domain
+- zone file path
+- current tailnet IPs
+- recommended `openclaw.json` discovery config
+- the Tailscale Split DNS nameserver/domain values to set
+
+Notes:
+
+- Without `--apply`, the command is a planning helper only and prints the recommended setup.
+- If `--domain` is omitted, OpenClaw uses `discovery.wideArea.domain` from config.
+- `--apply` currently supports macOS only and expects Homebrew CoreDNS.
+- `--apply` bootstraps the zone file if needed, ensures the CoreDNS import stanza exists, and restarts the `coredns` brew service.

docs/cli/index.md

@@ -686,6 +686,11 @@ Subcommands:
 - `pairing approve <channel> <code> [--account <id>] [--notify]`
 - `pairing approve --channel <channel> [--account <id>] <code> [--notify]`
 
+Notes:
+
+- If exactly one pairing-capable channel is configured, `pairing approve <code>` is also allowed.
+- `list` and `approve` both support `--account <id>` for multi-account channels.
+
 ### `devices`
 
 Manage gateway device pairing entries and per-role device tokens.
@@ -700,6 +705,12 @@ Subcommands:
 - `devices rotate --device <id> --role <role> [--scope <scope...>]`
 - `devices revoke --device <id> --role <role>`
 
+Notes:
+
+- `devices list` and `devices approve` can fall back to local pairing files on local loopback when direct pairing scope is unavailable.
+- `devices approve` auto-selects the newest pending request when no `requestId` is passed or `--latest` is set.
+- `devices rotate` and `devices revoke` return JSON payloads.
+
 ### `hooks`
 
 Manage internal agent hooks.
@@ -745,8 +756,14 @@ Wide-area discovery DNS helper (CoreDNS + Tailscale). See [/gateway/discovery](/
 
 Options:
 
+- `--domain <domain>`
 - `--apply`: install/update CoreDNS config (requires sudo; macOS only).
 
+Notes:
+
+- Without `--apply`, this is a planning helper that prints the recommended OpenClaw + Tailscale DNS config.
+- `--apply` currently supports macOS with Homebrew CoreDNS only.
+
 ## Messaging + agent
 
 ### `message`

docs/cli/pairing.md

@@ -20,10 +20,43 @@ openclaw pairing list telegram
 openclaw pairing list --channel telegram --account work
 openclaw pairing list telegram --json
 
+openclaw pairing approve <code>
 openclaw pairing approve telegram <code>
 openclaw pairing approve --channel telegram --account work <code> --notify
 ```
 
+## `pairing list`
+
+List pending pairing requests for one channel.
+
+Options:
+
+- `[channel]`: positional channel id
+- `--channel <channel>`: explicit channel id
+- `--account <accountId>`: account id for multi-account channels
+- `--json`: machine-readable output
+
+Notes:
+
+- If multiple pairing-capable channels are configured, you must provide a channel either positionally or with `--channel`.
+- Extension channels are allowed as long as the channel id is valid.
+
+## `pairing approve`
+
+Approve a pending pairing code and allow that sender.
+
+Usage:
+
+- `openclaw pairing approve <channel> <code>`
+- `openclaw pairing approve --channel <channel> <code>`
+- `openclaw pairing approve <code>` when exactly one pairing-capable channel is configured
+
+Options:
+
+- `--channel <channel>`: explicit channel id
+- `--account <accountId>`: account id for multi-account channels
+- `--notify`: send a confirmation back to the requester on the same channel
+
 ## Notes
 
 - Channel input: pass it positionally (`pairing list telegram`) or with `--channel <channel>`.