docs: clarify derived port mapping

docs/configuration.md

@@ -1024,6 +1024,8 @@ Convenience flags (CLI):
 - `clawdbot --dev …` → uses `~/.clawdbot-dev` + shifts ports from base `19001`
 - `clawdbot --profile <name> …` → uses `~/.clawdbot-<name>` (port via config/env/flags)
 
+See `docs/gateway.md` for the derived port mapping (gateway/bridge/browser/canvas).
+
 Example:
 ```bash
 CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json \

docs/gateway.md

@@ -70,6 +70,13 @@ Defaults (can be overridden via env/flags/config):
 - `canvasHost.port=19005` (derived: `gateway.port+4`)
 - `agent.workspace` default becomes `~/clawd-dev` when you run `setup`/`onboard` under `--dev`.
 
+Derived ports (rules of thumb):
+- Base port = `gateway.port` (or `CLAWDBOT_GATEWAY_PORT` / `--port`)
+- `bridge.port = base + 1` (or `CLAWDBOT_BRIDGE_PORT` / config override)
+- `browser.controlUrl port = base + 2` (or `CLAWDBOT_BROWSER_CONTROL_URL` / config override)
+- `canvasHost.port = base + 4` (or `CLAWDBOT_CANVAS_HOST_PORT` / config override)
+- Browser profile CDP ports auto-allocate from `browser.controlPort + 9 .. + 108` (persisted per profile).
+
 Checklist per instance:
 - unique `gateway.port`
 - unique `CLAWDBOT_CONFIG_PATH`

src/cli/program.ts

@@ -41,7 +41,7 @@ export function buildProgram() {
     .version(PROGRAM_VERSION)
     .option(
       "--dev",
-      "Dev profile: isolate config/state under ~/.clawdbot-dev and default gateway port 19001",
+      "Dev profile: isolate state under ~/.clawdbot-dev, default gateway port 19001, and shift derived ports (bridge/browser/canvas)",
     )
     .option(
       "--profile <name>",