From 5f67c023a2c3c7da4b4d76d6c635663f0af0d4f0 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 13 Dec 2025 16:23:02 +0000
Subject: [PATCH] docs(clawdis-mac): improve help for browser control

---
 .../macos/Sources/ClawdisCLI/BrowserCLI.swift |  7 +-
 .../macos/Sources/ClawdisCLI/ClawdisCLI.swift | 83 +++++++++++++------
 2 files changed, 65 insertions(+), 25 deletions(-)

diff --git a/apps/macos/Sources/ClawdisCLI/BrowserCLI.swift b/apps/macos/Sources/ClawdisCLI/BrowserCLI.swift
index 9aeab48d5..9cd3ba89a 100644
--- a/apps/macos/Sources/ClawdisCLI/BrowserCLI.swift
+++ b/apps/macos/Sources/ClawdisCLI/BrowserCLI.swift
@@ -239,6 +239,8 @@ enum BrowserCLI {
 
     private static func printHelp() {
         let usage = """
+        Browser (clawd) — control clawd’s dedicated Chrome/Chromium via the gateway’s loopback server.
+
         Usage:
           clawdis-mac browser status [--url <http://127.0.0.1:18791>]
           clawdis-mac browser start [--url <...>]
@@ -248,8 +250,11 @@ enum BrowserCLI {
           clawdis-mac browser focus <targetId> [--url <...>]
           clawdis-mac browser close <targetId> [--url <...>]
           clawdis-mac browser screenshot [--target-id <id>] [--full-page] [--url <...>]
+
+        Notes:
+          - Config defaults come from ~/.clawdis/clawdis.json (browser.enabled, browser.controlUrl).
+          - `browser screenshot` prints MEDIA:<path> in text mode.
         """
         print(usage)
     }
 }
-
diff --git a/apps/macos/Sources/ClawdisCLI/ClawdisCLI.swift b/apps/macos/Sources/ClawdisCLI/ClawdisCLI.swift
index 35f071d42..96dc70f5f 100644
--- a/apps/macos/Sources/ClawdisCLI/ClawdisCLI.swift
+++ b/apps/macos/Sources/ClawdisCLI/ClawdisCLI.swift
@@ -408,34 +408,69 @@ struct ClawdisCLI {
 
     private static func printHelp() {
         let usage = """
-        clawdis-mac — talk to the running Clawdis.app XPC service
+        clawdis-mac — talk to the running Clawdis.app (local control socket)
 
         Usage:
           clawdis-mac [--json] <command> ...
-          clawdis-mac notify --title <t> --body <b> [--sound <name>] [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>]
-          clawdis-mac ensure-permissions
-            [--cap <notifications|accessibility|screenRecording|microphone|speechRecognition>]
-            [--interactive]
-          clawdis-mac ui screens
-          clawdis-mac ui screenshot [--screen-index <n>] [--window-id <u32>]
-          clawdis-mac run [--cwd <path>] [--env KEY=VAL] [--timeout <sec>] [--needs-screen-recording] <command ...>
-          clawdis-mac status
-          clawdis-mac rpc-status
-          clawdis-mac agent --message <text> [--thinking <low|default|high>]
-            [--session <key>] [--deliver] [--to <E.164>]
-          clawdis-mac node list
-          clawdis-mac node invoke --node <id> --command <name> [--params-json <json>]
-          clawdis-mac canvas show [--session <key>] [--path </...>]
-            [--x <screenX> --y <screenY>] [--width <w> --height <h>]
-          clawdis-mac canvas hide [--session <key>]
-          clawdis-mac canvas goto --path </...> [--session <key>]
-            [--x <screenX> --y <screenY>] [--width <w> --height <h>]
-          clawdis-mac canvas eval --js <code> [--session <key>]
-          clawdis-mac canvas snapshot [--out <path>] [--session <key>]
-          clawdis-mac browser status|start|stop|tabs|open|focus|close|screenshot
-          clawdis-mac --help
 
-        Default output is text. Use --json for machine-readable output.
+        Commands:
+          Notifications:
+            clawdis-mac notify --title <t> --body <b> [--sound <name>]
+              [--priority <passive|active|timeSensitive>] [--delivery <system|overlay|auto>]
+
+          Permissions:
+            clawdis-mac ensure-permissions
+              [--cap <notifications|accessibility|screenRecording|microphone|speechRecognition>]
+              [--interactive]
+
+          UI:
+            clawdis-mac ui screens
+            clawdis-mac ui screenshot [--screen-index <n>] [--window-id <u32>]
+
+          Shell:
+            clawdis-mac run [--cwd <path>] [--env KEY=VAL] [--timeout <sec>]
+              [--needs-screen-recording] <command ...>
+
+          Status:
+            clawdis-mac status
+            clawdis-mac rpc-status
+
+          Agent:
+            clawdis-mac agent --message <text> [--thinking <low|default|high>]
+              [--session <key>] [--deliver] [--to <E.164>]
+
+          Nodes:
+            clawdis-mac node list
+            clawdis-mac node invoke --node <id> --command <name> [--params-json <json>]
+
+          Canvas:
+            clawdis-mac canvas show [--session <key>] [--path </...>]
+              [--x <screenX> --y <screenY>] [--width <w> --height <h>]
+            clawdis-mac canvas hide [--session <key>]
+            clawdis-mac canvas goto --path </...> [--session <key>]
+              [--x <screenX> --y <screenY>] [--width <w> --height <h>]
+            clawdis-mac canvas eval --js <code> [--session <key>]
+            clawdis-mac canvas snapshot [--out <path>] [--session <key>]
+
+          Browser (clawd):
+            clawdis-mac browser status|start|stop|tabs|open|focus|close|screenshot
+
+        Browser notes:
+          - Uses clawd’s dedicated Chrome/Chromium profile (separate user-data dir).
+          - Talks to the gateway’s loopback browser-control server (config: ~/.clawdis/clawdis.json).
+          - Keys: browser.enabled, browser.controlUrl (default: http://127.0.0.1:18791).
+
+        Examples:
+          clawdis-mac status
+          clawdis-mac agent --message "Hello from clawd" --thinking low
+          clawdis-mac browser start
+          clawdis-mac browser open https://example.com
+          clawdis-mac browser tabs
+          clawdis-mac browser screenshot --full-page
+
+        Output:
+          Default output is text. Use --json for machine-readable output.
+          In text mode, `browser screenshot` prints MEDIA:<path>.
         """
         print(usage)
     }