From 00370139a542b8d6d89a11ddb405976da263fd5d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Mon, 5 Jan 2026 02:03:10 +0100
Subject: [PATCH] docs: clarify derived port mapping

---
 docs/configuration.md | 2 ++
 docs/gateway.md       | 7 +++++++
 src/cli/program.ts    | 2 +-
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index ca0622389..1b2355a47 100644
--- a/docs/configuration.md
+++ b/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 \
diff --git a/docs/gateway.md b/docs/gateway.md
index f011c0c12..5b6fb9cd9 100644
--- a/docs/gateway.md
+++ b/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`
diff --git a/src/cli/program.ts b/src/cli/program.ts
index c645483a1..9732d7153 100644
--- a/src/cli/program.ts
+++ b/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>",