diff --git a/docs/debugging.md b/docs/debugging.md
index 8cd109ec5..e9dd74d99 100644
--- a/docs/debugging.md
+++ b/docs/debugging.md
@@ -54,11 +54,11 @@ debugging. There are **two** `--dev` flags:
 - **`gateway --dev`: tells the Gateway to auto-create a default config +
   workspace** when missing (and skip BOOTSTRAP.md).
 
-Recommended flow:
+Recommended flow (dev profile + dev bootstrap):
 
 ```bash
-pnpm clawdbot --dev gateway --dev
-pnpm clawdbot --dev tui
+pnpm gateway:dev
+CLAWDBOT_PROFILE=dev pnpm clawdbot tui
 ```
 
 What this does:
@@ -80,7 +80,14 @@ What this does:
 Reset flow (fresh start):
 
 ```bash
-pnpm clawdbot --dev gateway --dev --reset
+pnpm gateway:dev:reset
+```
+
+Note: `--dev` is a **global** profile flag and gets eaten by some runners.
+If you need to spell it out, use the env var form:
+
+```bash
+CLAWDBOT_PROFILE=dev pnpm clawdbot gateway --dev --reset
 ```
 
 `--reset` wipes config, credentials, sessions, and the dev workspace (using
diff --git a/package.json b/package.json
index 03dfba4d5..3ef2fae28 100644
--- a/package.json
+++ b/package.json
@@ -65,6 +65,10 @@
     "start": "tsx src/entry.ts",
     "clawdbot": "tsx src/entry.ts",
     "gateway:watch": "tsx watch src/entry.ts gateway --force",
+    "gateway:dev": "CLAWDBOT_PROFILE=dev tsx src/entry.ts gateway --dev",
+    "gateway:dev:reset": "CLAWDBOT_PROFILE=dev tsx src/entry.ts gateway --reset",
+    "tui": "tsx src/entry.ts tui",
+    "tui:dev": "CLAWDBOT_PROFILE=dev tsx src/entry.ts tui",
     "clawdbot:rpc": "tsx src/entry.ts agent --mode rpc --json",
     "ios:gen": "cd apps/ios && xcodegen generate",
     "ios:open": "cd apps/ios && xcodegen generate && open Clawdbot.xcodeproj",