Merge pull request #942 from web3dev1337/feature/commander-instructions

feat: seed Commander CLAUDE.md/AGENTS.md for desktop

Author: web3dev1337

CODEBASE_DOCUMENTATION.md

@@ -110,8 +110,12 @@ server/githubCloneWorktreeService.js - GitHub import flow for Quick Work (`owner
 server/portRegistry.js             - Port assignment + live service scanner (`/api/ports/scan`)
 ├─ Windows scan path: uses hidden `netstat`/`tasklist` probes so packaged Tauri builds do not flash console windows when Ports/Dashboard panels refresh
 └─ UI metadata: labels orchestrator-assigned ports, known dev servers, and custom user labels
+server/commanderService.js         - Top-level Commander PTY (Claude/Codex) + launch buffering
+├─ Packaged CWD: uses `ORCHESTRATOR_DATA_DIR/commander` so desktop users can edit `CLAUDE.md` / `AGENTS.md` safely
+└─ First-run seed: copies the packaged `docs/COMMANDER_CLAUDE.md` into the Commander data directory when missing
 scripts/tauri/prepare-backend-resources.js - Tauri backend packager
 ├─ Bundles: server/client/config/templates/scripts + optional Node runtime into `src-tauri/resources/backend`
+├─ Commander instructions: copies `docs/COMMANDER_CLAUDE.md` into `resources/backend/{COMMANDER_CLAUDE.md,CLAUDE.md,AGENTS.md}` for desktop builds
 ├─ Resource-sync reuse: repeated runs skip recopying server/client/templates/config payloads when the source-tree stamp still matches
 ├─ Prod-deps reuse: repeated `--install-prod` runs skip `npm ci` when package-lock + bundled Node stamp still match
 └─ CI cache: Windows release workflow restores `src-tauri/resources/backend/node_modules` so warm installer builds avoid re-installing backend prod deps

docs/COMMANDER_CLAUDE.md

@@ -1,8 +1,19 @@
 # Commander Claude - API Reference
 
-You are Commander Claude. You can control the Agent Workspace by calling these API endpoints via curl.
+You are Commander (Claude or Codex). You can control the Claude Orchestrator by calling these HTTP APIs via `curl`.
 
-**Base URL:** `http://localhost:4000`
+Runtime connection info (desktop builds pick a free port each launch):
+- Host: `ORCHESTRATOR_HOST` (default `127.0.0.1`)
+- Port: `ORCHESTRATOR_PORT` (default `9460` for `npm start`)
+- Auth: if `AUTH_TOKEN` is set, every request must include `-H "X-Auth-Token: $AUTH_TOKEN"` (or `?token=$AUTH_TOKEN`)
+
+**Base URL:** `http://${ORCHESTRATOR_HOST:-127.0.0.1}:${ORCHESTRATOR_PORT:-9460}`
+
+Optional helper (bash):
+```bash
+BASE_URL="http://${ORCHESTRATOR_HOST:-127.0.0.1}:${ORCHESTRATOR_PORT:-9460}"
+# If AUTH_TOKEN is set, add: -H "X-Auth-Token: $AUTH_TOKEN"
+```
 
 ---
 
@@ -13,75 +24,86 @@ The Command Registry provides semantic, self-documenting commands. **This is the
 ### Discover Available Commands
 ```bash
 # See all available commands with descriptions and examples
-curl -s http://localhost:4000/api/commander/capabilities | jq
+curl -sS "$BASE_URL/api/commander/capabilities" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 ```
 
 ### Get Live Context (Recommended)
 ```bash
 # See current UI/session context (selected queue item, sessions, workspace, etc.)
-curl -s http://localhost:4000/api/commander/context | jq
+curl -sS "$BASE_URL/api/commander/context" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 ```
 
 ### Get Runtime Help Prompt (Self-Updating)
 ```bash
 # Plain-text prompt generated from the command registry + current context
-curl -s http://localhost:4000/api/commander/prompt
+curl -sS "$BASE_URL/api/commander/prompt" -H "X-Auth-Token: $AUTH_TOKEN"
 ```
 
 ### Execute Commands
 ```bash
 # General syntax
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "COMMAND_NAME", "params": {...}}'
 
 # Focus on a terminal
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "focus-session", "params": {"sessionId": "work1-claude"}}'
 
 # Switch workspace
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "switch-workspace", "params": {"name": "Epic Survivors"}}'
 
 # Open Commander panel
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "open-commander"}'
 
 # Open New Project wizard
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "open-new-project"}'
 
 # Start Claude in a session
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "start-claude", "params": {"sessionId": "work1-claude"}}'
 
 # Run a shell command
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "run-command", "params": {"sessionId": "work1-server", "command": "npm test"}}'
 
 # Broadcast to multiple sessions
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "broadcast", "params": {"sessionIds": ["work1-claude", "work2-claude"], "input": "git pull\n"}}'
 
 # Highlight a worktree in sidebar
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "highlight-worktree", "params": {"worktreeId": "work1"}}'
 
 # Focus a worktree (show ONLY that worktree's terminals, hide others)
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "focus-worktree", "params": {"worktreeId": "work1"}}'
 
 # Show all worktrees again (unfocus)
-curl -s http://localhost:4000/api/commander/execute \
+curl -sS "$BASE_URL/api/commander/execute" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"command": "show-all-worktrees"}'
 ```
@@ -100,10 +122,11 @@ curl -s http://localhost:4000/api/commander/execute \
 
 ```bash
 # View all active sessions
-curl -s http://localhost:4000/api/commander/sessions | jq
+curl -sS "$BASE_URL/api/commander/sessions" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Send input to a specific session
-curl -s http://localhost:4000/api/commander/send-to-session \
+curl -sS "$BASE_URL/api/commander/send-to-session" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"sessionId": "zoo-game-work1-claude", "input": "git status\n"}'
 ```
@@ -112,18 +135,20 @@ curl -s http://localhost:4000/api/commander/send-to-session \
 
 ```bash
 # List all workspaces
-curl -s http://localhost:4000/api/workspaces | jq
+curl -sS "$BASE_URL/api/workspaces" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Scan for available repos
-curl -s http://localhost:4000/api/workspaces/scan-repos | jq
+curl -sS "$BASE_URL/api/workspaces/scan-repos" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Create a new worktree
-curl -s http://localhost:4000/api/workspaces/create-worktree \
+curl -sS "$BASE_URL/api/workspaces/create-worktree" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"repoPath": "~/GitHub/games/monogame/zoo-game", "branchName": "feature/new-work"}'
 
 # Remove a worktree
-curl -s http://localhost:4000/api/workspaces/remove-worktree \
+curl -sS "$BASE_URL/api/workspaces/remove-worktree" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"worktreePath": "~/GitHub/games/monogame/zoo-game/work5"}'
 ```
@@ -132,10 +157,11 @@ curl -s http://localhost:4000/api/workspaces/remove-worktree \
 
 ```bash
 # Get available project templates
-curl -s http://localhost:4000/api/greenfield/templates | jq
+curl -sS "$BASE_URL/api/greenfield/templates" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Create new project
-curl -s http://localhost:4000/api/greenfield/create \
+curl -sS "$BASE_URL/api/greenfield/create" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"name": "my-project", "path": "~/GitHub", "template": "empty"}'
 ```
@@ -144,43 +170,44 @@ curl -s http://localhost:4000/api/greenfield/create \
 
 ```bash
 # Check git status across worktrees
-curl -s http://localhost:4000/api/git/status | jq
+curl -sS "$BASE_URL/api/git/status" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Check for updates
-curl -s http://localhost:4000/api/git/check-updates | jq
+curl -sS "$BASE_URL/api/git/check-updates" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Pull updates
-curl -s http://localhost:4000/api/git/pull -X POST
+curl -sS "$BASE_URL/api/git/pull" -H "X-Auth-Token: $AUTH_TOKEN" -X POST
 ```
 
 ## Quick Links & Favorites
 
 ```bash
 # Get quick links and favorites
-curl -s http://localhost:4000/api/quick-links | jq
+curl -sS "$BASE_URL/api/quick-links" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Get recent sessions
-curl -s http://localhost:4000/api/quick-links/recent-sessions | jq
+curl -sS "$BASE_URL/api/quick-links/recent-sessions" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 ```
 
 ## Continuity (Session Memory)
 
 ```bash
 # Get continuity ledger for current workspace
-curl -s http://localhost:4000/api/continuity/ledger | jq
+curl -sS "$BASE_URL/api/continuity/ledger" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Get workspace continuity info
-curl -s http://localhost:4000/api/continuity/workspace | jq
+curl -sS "$BASE_URL/api/continuity/workspace" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 ```
 
 ## User Settings
 
 ```bash
 # Get all user settings
-curl -s http://localhost:4000/api/user-settings | jq
+curl -sS "$BASE_URL/api/user-settings" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 
 # Update global settings
-curl -s http://localhost:4000/api/user-settings/global \
+curl -sS "$BASE_URL/api/user-settings/global" \
+  -H "X-Auth-Token: $AUTH_TOKEN" \
   -X PUT -H "Content-Type: application/json" \
   -d '{"theme": "dark", "notifications": true}'
 ```
@@ -189,7 +216,7 @@ curl -s http://localhost:4000/api/user-settings/global \
 
 ```bash
 # Get all port assignments
-curl -s http://localhost:4000/api/ports | jq
+curl -sS "$BASE_URL/api/ports" -H "X-Auth-Token: $AUTH_TOKEN" | jq
 ```
 
 ## Direct File System Access
@@ -211,14 +238,15 @@ git -C ~/GitHub/games/monogame/zoo-game worktree list
 
 ### Broadcast message to all Claude sessions
 ```bash
-for sid in $(curl -s http://localhost:4000/api/commander/sessions | jq -r '.sessions[] | select(.id | contains("claude")) | .id'); do
-  curl -s http://localhost:4000/api/commander/send-to-session \
+for sid in $(curl -sS "$BASE_URL/api/commander/sessions" -H "X-Auth-Token: $AUTH_TOKEN" | jq -r '.sessions[] | select(.id | contains("claude")) | .id'); do
+  curl -sS "$BASE_URL/api/commander/send-to-session" \
+    -H "X-Auth-Token: $AUTH_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"sessionId\": \"$sid\", \"input\": \"# Message from Commander\n\"}"
 done
 ```
 
 ### Check what each session is working on
 ```bash
-curl -s http://localhost:4000/api/commander/sessions | jq '.sessions[] | {id, status, branch}'
+curl -sS "$BASE_URL/api/commander/sessions" -H "X-Auth-Token: $AUTH_TOKEN" | jq '.sessions[] | {id, status, branch}'
 ```

scripts/tauri/prepare-backend-resources.js

@@ -96,6 +96,7 @@ function buildResourceSyncStamp({
   srcLock,
   srcConfig,
   srcUserDefaults,
+  srcCommanderInstructions,
   srcLicensePublicKey,
   srcUpdaterPublicKey,
   bundledNodePath
@@ -109,6 +110,7 @@ function buildResourceSyncStamp({
       packageLock: statSignature(srcLock),
       configJson: statSignature(srcConfig),
       userSettingsDefaultJson: statSignature(srcUserDefaults),
+      commanderInstructions: statSignature(srcCommanderInstructions),
       createProjectScript: statSignature(path.join(srcScripts, 'create-project.js')),
       licensePublicKey: statSignature(srcLicensePublicKey),
       updaterPublicKey: statSignature(srcUpdaterPublicKey),
@@ -231,6 +233,13 @@ function main() {
   const srcLock = path.join(repoRoot, 'package-lock.json');
   const srcConfig = path.join(repoRoot, 'config.json');
   const srcUserDefaults = path.join(repoRoot, 'user-settings.default.json');
+  const srcCommanderInstructions = (() => {
+    const docsPath = path.join(repoRoot, 'docs', 'COMMANDER_CLAUDE.md');
+    if (fs.existsSync(docsPath)) return docsPath;
+    const rootPath = path.join(repoRoot, 'COMMANDER_CLAUDE.md');
+    if (fs.existsSync(rootPath)) return rootPath;
+    return null;
+  })();
   const srcLicensePublicKey =
     process.env.ORCHESTRATOR_LICENSE_PUBLIC_KEY_PATH
     || process.env.TAURI_LICENSE_PUBLIC_KEY_PATH
@@ -275,6 +284,7 @@ function main() {
     srcLock,
     srcConfig,
     srcUserDefaults,
+    srcCommanderInstructions,
     srcLicensePublicKey,
     srcUpdaterPublicKey,
     bundledNodePath
@@ -286,6 +296,13 @@ function main() {
     path.join(outDir, 'scripts', 'create-project.js'),
     path.join(outDir, 'package.json')
   ];
+  if (srcCommanderInstructions) {
+    requiredResourcePaths.push(
+      path.join(outDir, 'COMMANDER_CLAUDE.md'),
+      path.join(outDir, 'CLAUDE.md'),
+      path.join(outDir, 'AGENTS.md')
+    );
+  }
 
   if (canReuseResourceSync({
     stampPath: resourceSyncStampPath,
@@ -334,6 +351,17 @@ function main() {
     } else {
       removeIfExists(path.join(outDir, 'user-settings.default.json'));
     }
+    if (srcCommanderInstructions) {
+      // Commander runs from the packaged backend root directory, so include a reduced
+      // CLAUDE.md/AGENTS.md control-surface reference for both Claude Code and Codex CLI.
+      copyFile(srcCommanderInstructions, path.join(outDir, 'COMMANDER_CLAUDE.md'));
+      copyFile(srcCommanderInstructions, path.join(outDir, 'CLAUDE.md'));
+      copyFile(srcCommanderInstructions, path.join(outDir, 'AGENTS.md'));
+    } else {
+      removeIfExists(path.join(outDir, 'COMMANDER_CLAUDE.md'));
+      removeIfExists(path.join(outDir, 'CLAUDE.md'));
+      removeIfExists(path.join(outDir, 'AGENTS.md'));
+    }
     if (srcLicensePublicKey && fs.existsSync(srcLicensePublicKey)) {
       copyFile(srcLicensePublicKey, path.join(outDir, 'license-public-key.pem'));
     } else {