@juspay/shooter 1.0.0 → 1.2.0

package/.claude/hooks/notifier.cjs

@@ -33,8 +33,8 @@ const RUNTIME = IS_OPENCODE ? 'opencode' : 'claude-code';
 
 // Environment configuration
 const USE_LOCAL = process.env.SHOOTER_USE_LOCAL === 'true';
-const LOCAL_PORT = process.env.SHOOTER_LOCAL_PORT || '3000';
-const REMOTE_BASE_URL = process.env.SHOOTER_API_URL || '';
+const LOCAL_PORT = process.env.SHOOTER_LOCAL_PORT || '54007';
+const REMOTE_BASE_URL = process.env.SHOOTER_API_URL?.trim() || '';
 const LOCAL_BASE_URL = `http://localhost:${LOCAL_PORT}`;
 const BASE_URL = USE_LOCAL ? LOCAL_BASE_URL : REMOTE_BASE_URL;
 const API_URL = `${BASE_URL}/api/notify`;
@@ -80,28 +80,35 @@ async function hasWebSocketClients() {
     const url = `${BASE_URL}/api/ws-status`;
     const protocol = url.startsWith('https') ? https : http;
     return new Promise((resolve) => {
-      const req = protocol.request(url, {
-        method: 'GET',
-        headers: { Authorization: `Bearer ${AUTH_KEY}` },
-        timeout: 3000,
-      }, (res) => {
-        let data = '';
-        res.on('data', (chunk) => (data += chunk));
-        res.on('end', () => {
-          if (res.statusCode === 200) {
-            try {
-              const parsed = JSON.parse(data);
-              resolve(parsed.connectedClients > 0);
-            } catch (e) {
+      const req = protocol.request(
+        url,
+        {
+          method: 'GET',
+          headers: { Authorization: `Bearer ${AUTH_KEY}` },
+          timeout: 3000,
+        },
+        (res) => {
+          let data = '';
+          res.on('data', (chunk) => (data += chunk));
+          res.on('end', () => {
+            if (res.statusCode === 200) {
+              try {
+                const parsed = JSON.parse(data);
+                resolve(parsed.connectedClients > 0);
+              } catch (e) {
+                resolve(false);
+              }
+            } else {
               resolve(false);
             }
-          } else {
-            resolve(false);
-          }
-        });
-      });
+          });
+        }
+      );
       req.on('error', () => resolve(false));
-      req.on('timeout', () => { req.destroy(); resolve(false); });
+      req.on('timeout', () => {
+        req.destroy();
+        resolve(false);
+      });
       req.end();
     });
   } catch (e) {
@@ -625,26 +632,20 @@ async function handlePermission(event) {
         console.error(`=== REGISTERING REQUEST & POLLING VIA WEBSOCKET CHANNEL ===\n`);
       }
 
-      // POST to /api/notify with waitForResponse so the server creates a pending
-      // request entry. Without this, GET /api/response returns 404 every time.
+      // Register the pending request but skip the actual push notification —
+      // the events channel will broadcast the permission to connected clients.
       result = await sendNotificationAndPoll(
         title,
         body,
         'permission',
         event.source,
         requestId,
-        d
+        d,
+        { skipPush: true }
       );
     } else {
       // No WebSocket clients — send push notification and poll
-      result = await sendNotificationAndPoll(
-        title,
-        body,
-        'permission',
-        event.source,
-        requestId,
-        d
-      );
+      result = await sendNotificationAndPoll(title, body, 'permission', event.source, requestId, d);
     }
 
     if (result && result.decision) {
@@ -1022,7 +1023,15 @@ function createCompletionMessage(state, projectName) {
  *
  * Returns { decision: 'allow' | 'deny' } or null on timeout.
  */
-function sendNotificationAndPoll(title, body, category, source, requestId, eventData) {
+function sendNotificationAndPoll(
+  title,
+  body,
+  category,
+  source,
+  requestId,
+  eventData,
+  { skipPush = false } = {}
+) {
   return new Promise((resolve) => {
     const timestamp = new Date().toISOString();
 
@@ -1030,6 +1039,81 @@ function sendNotificationAndPoll(title, body, category, source, requestId, event
     const envPrefix = USE_LOCAL ? '[LOCAL]' : '';
     const finalTitle = `${runtimePrefix}${envPrefix ? ' ' + envPrefix : ''} ${title}`;
 
+    // When skipPush is true (WebSocket clients connected), skip the actual
+    // POST to /api/notify but still register the pending request and poll.
+    if (skipPush) {
+      debugLog(
+        `Skipping push notification (WebSocket active), going straight to polling (requestId: ${requestId})`
+      );
+      // Register the pending request on the server so polling finds it.
+      // We still need to POST with waitForResponse so the server creates
+      // the pending-request entry, but we mark it as ws-only.
+      const registerPayload = JSON.stringify({
+        title: finalTitle,
+        message: body,
+        waitForResponse: true,
+        skipPush: true,
+        ...(DEVICE_TOKEN && { deviceToken: DEVICE_TOKEN }),
+        data: {
+          category,
+          project: getProjectName(),
+          timestamp,
+          requestId,
+          clientTimestamp: timestamp,
+          source: 'shooter-completion-detector',
+          environment: USE_LOCAL ? 'local' : 'remote',
+          runtime: source,
+          toolName: eventData.tool || '',
+          toolInput: eventData.toolInput || {},
+          sessionId: eventData.sessionId || '',
+        },
+      });
+
+      const registerOptions = {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${AUTH_KEY}`,
+          'Content-Length': Buffer.byteLength(registerPayload),
+          'User-Agent': `Shooter-Notifier/3.0 ${source}`,
+        },
+      };
+
+      const protocol = API_URL.startsWith('https') ? https : http;
+      const req = protocol.request(API_URL, registerOptions, (res) => {
+        let responseData = '';
+        res.on('data', (chunk) => (responseData += chunk));
+        res.on('end', () => {
+          debugLog(`Pending request registered (skipPush): status=${res.statusCode}`);
+          if (res.statusCode !== 200) {
+            debugLog(
+              `Registration failed (skipPush): ${res.statusCode} - falling through to local dialog`
+            );
+            resolve(null);
+            return;
+          }
+          // Start polling only after successful registration — the WebSocket
+          // events channel will deliver the permission to connected clients.
+          startPolling(requestId, resolve);
+        });
+      });
+
+      req.on('error', (error) => {
+        debugLog(
+          `Register request error (skipPush): ${error.message} - falling through to local dialog`
+        );
+        resolve(null);
+      });
+
+      req.setTimeout(10000, () => {
+        req.destroy(new Error('Request timeout'));
+      });
+
+      req.write(registerPayload);
+      req.end();
+      return;
+    }
+
     debugLog(`Sending bidirectional notification: "${finalTitle}" (requestId: ${requestId})`);
 
     const payload = JSON.stringify({

package/.claude/settings.json

@@ -9,7 +9,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs PreToolUse"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs PreToolUse"
           }
         ]
       }
@@ -20,7 +20,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs PostToolUse"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs PostToolUse"
           }
         ]
       }
@@ -31,7 +31,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs PostToolUseFailure"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs PostToolUseFailure"
           }
         ]
       }
@@ -42,7 +42,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs Stop"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs Stop"
           }
         ]
       }
@@ -53,7 +53,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs SessionStart"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs SessionStart"
           }
         ]
       }
@@ -64,7 +64,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs SessionEnd"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs SessionEnd"
           }
         ]
       }
@@ -75,7 +75,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs Notification"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs Notification"
           }
         ]
       }
@@ -86,7 +86,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs PermissionRequest",
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs PermissionRequest",
             "timeout": 180
           }
         ]
@@ -98,7 +98,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs SubagentStart"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs SubagentStart"
           }
         ]
       }
@@ -109,7 +109,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs SubagentStop"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs SubagentStop"
           }
         ]
       }
@@ -120,7 +120,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs UserPromptSubmit"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs UserPromptSubmit"
           }
         ]
       }
@@ -131,7 +131,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs TeammateIdle"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs TeammateIdle"
           }
         ]
       }
@@ -142,7 +142,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs TaskCompleted"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs TaskCompleted"
           }
         ]
       }
@@ -153,7 +153,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=3000 API_KEY=$API_KEY node .claude/hooks/notifier.cjs PreCompact"
+            "command": "SHOOTER_USE_LOCAL=true SHOOTER_LOCAL_PORT=${SHOOTER_LOCAL_PORT:-54007} API_KEY=$API_KEY node .claude/hooks/notifier.cjs PreCompact"
           }
         ]
       }

package/README.md

@@ -33,27 +33,37 @@ Shooter turns your phone into a remote control for AI coding sessions running on
 
 ## Quick Start
 
+**One-command install** (recommended):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/juspay/shooter/release/scripts/install.sh | sh
+```
+
+This clones to `~/.shooter/repo`, auto-generates an API key, installs dependencies, builds, offers to install cloudflared for remote access, enables autostart on login, and starts the server.
+
+**Or clone and set up manually:**
+
 ```bash
 git clone https://github.com/juspay/shooter.git
 cd shooter
 pnpm install
 pnpm setup        # interactive wizard: generates .env, builds, runs health check
-pnpm start        # start the server on http://localhost:3000
+pnpm start        # start the server on http://localhost:54007
 ```
 
-Open [http://localhost:3000](http://localhost:3000) in your browser. Visit `/config` to enter your API key for the web UI.
+Open [http://localhost:54007](http://localhost:54007) in your browser. Visit `/config` to enter your API key for the web UI.
 
 ---
 
 ## All Setup Methods
 
-| Method | Command | Notes |
-|--------|---------|-------|
-| Interactive wizard | `pnpm setup` | Recommended. Walks through env config, builds, and verifies. |
-| CLI (npx) | `npx @juspay/shooter setup` | No clone needed -- runs the setup wizard directly from npm |
-| One-command install | `curl -fsSL https://raw.githubusercontent.com/juspay/shooter/release/scripts/install.sh \| sh` | Clones to `~/.shooter`, installs deps, runs wizard |
-| Docker | `docker compose up -d` | See [Docker](#docker) |
-| Manual | See [Manual Setup](#manual-setup) | For advanced users |
+| Method              | Command                                                                                        | Notes                                                                                                |
+| ------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| One-command install | `curl -fsSL https://raw.githubusercontent.com/juspay/shooter/release/scripts/install.sh \| sh` | Recommended. Clones to `~/.shooter/repo`, auto-generates API key, builds, installs cloudflared, starts server |
+| Interactive wizard  | `pnpm setup`                                                                                   | Walks through env config, builds, and verifies. Pass `--auto` for non-interactive mode.              |
+| CLI (npx)           | `npx @juspay/shooter setup`                                                                    | No clone needed -- runs the setup wizard directly from npm                                           |
+| Docker              | `docker compose up -d`                                                                         | See [Docker](#docker)                                                                                |
+| Manual              | See [Manual Setup](#manual-setup)                                                              | For advanced users                                                                                   |
 
 ### Manual Setup
 
@@ -82,7 +92,7 @@ source ~/.zshrc
 +----------------------------------------------------------+
 |  Dev Machine                                             |
 |                                                          |
-|  SvelteKit Server (adapter-node, port 3000)              |
+|  SvelteKit Server (adapter-node, port 54007)             |
 |    +-- REST API (/api/terminals, /api/notify, ...)       |
 |    +-- WebSocket Server (ws, noServer mode)              |
 |    +-- PTY Manager (node-pty + holder processes)         |
@@ -111,11 +121,11 @@ source ~/.zshrc
 
 **Three WebSocket channels:**
 
-| Channel | Path | Purpose |
-|---------|------|---------|
-| Terminal I/O | `/ws/terminal/:id` | Raw PTY byte stream (xterm.js) |
-| Session stream | `/ws/session/:id` | Structured AI conversation updates |
-| Global events | `/ws/events` | Server broadcasts (new sessions, exits, permissions) |
+| Channel        | Path               | Purpose                                              |
+| -------------- | ------------------ | ---------------------------------------------------- |
+| Terminal I/O   | `/ws/terminal/:id` | Raw PTY byte stream (xterm.js)                       |
+| Session stream | `/ws/session/:id`  | Structured AI conversation updates                   |
+| Global events  | `/ws/events`       | Server broadcasts (new sessions, exits, permissions) |
 
 ---
 
@@ -123,21 +133,21 @@ source ~/.zshrc
 
 Copy `.env.example` to `.env` and fill in your values. The `pnpm setup` wizard handles this interactively.
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `API_KEY` | **Yes** | -- | Bearer token for authenticating all API and hook requests |
-| `PORT` | No | `3000` | HTTP server port |
-| `DEVICE_PLATFORM` | No | `ios` | Push notification target: `ios` or `android` |
-| `APNS_KEY` | No | -- | APNs private key (`.p8` file contents, newlines escaped as `\n`) |
-| `APNS_KEY_ID` | No | -- | 10-character APNs key identifier from Apple Developer portal |
-| `APNS_TEAM_ID` | No | -- | 10-character Apple Team ID |
-| `APNS_BUNDLE_ID` | No | -- | iOS app bundle identifier (must match Xcode project) |
-| `APNS_PRODUCTION` | No | `false` | Set `true` for TestFlight / App Store builds |
-| `DEVICE_TOKEN` | No | -- | Target iOS device token (64-character hex) |
-| `FCM_PROJECT_ID` | No | -- | Firebase project ID |
-| `FCM_CLIENT_EMAIL` | No | -- | Firebase service account email |
-| `FCM_PRIVATE_KEY` | No | -- | Firebase service account private key (PEM format) |
-| `ANDROID_DEVICE_TOKEN` | No | -- | Target Android FCM device token |
+| Variable               | Required | Default | Description                                                      |
+| ---------------------- | -------- | ------- | ---------------------------------------------------------------- |
+| `API_KEY`              | **Yes**  | --      | Bearer token for authenticating all API and hook requests        |
+| `PORT`                 | No       | `54007` | HTTP server port                                                 |
+| `DEVICE_PLATFORM`      | No       | `ios`   | Push notification target: `ios` or `android`                     |
+| `APNS_KEY`             | No       | --      | APNs private key (`.p8` file contents, newlines escaped as `\n`) |
+| `APNS_KEY_ID`          | No       | --      | 10-character APNs key identifier from Apple Developer portal     |
+| `APNS_TEAM_ID`         | No       | --      | 10-character Apple Team ID                                       |
+| `APNS_BUNDLE_ID`       | No       | --      | iOS app bundle identifier (must match Xcode project)             |
+| `APNS_PRODUCTION`      | No       | `false` | Set `true` for TestFlight / App Store builds                     |
+| `DEVICE_TOKEN`         | No       | --      | Target iOS device token (64-character hex)                       |
+| `FCM_PROJECT_ID`       | No       | --      | Firebase project ID                                              |
+| `FCM_CLIENT_EMAIL`     | No       | --      | Firebase service account email                                   |
+| `FCM_PRIVATE_KEY`      | No       | --      | Firebase service account private key (PEM format)                |
+| `ANDROID_DEVICE_TOKEN` | No       | --      | Target Android FCM device token                                  |
 
 ---
 
@@ -225,22 +235,22 @@ Shooter integrates with Claude Code through lifecycle hooks defined in `.claude/
 
 ### Captured Events
 
-| Hook | Description |
-|------|-------------|
-| `PreToolUse` | Before a tool executes (file edit, bash command, etc.) |
-| `PostToolUse` | After a tool completes successfully |
-| `PostToolUseFailure` | After a tool fails |
-| `PermissionRequest` | Claude Code asks for permission -- **blocks until you respond** |
-| `SessionStart` | A new coding session begins |
-| `SessionEnd` | A coding session ends |
-| `Stop` | Claude Code stops execution |
-| `Notification` | General notification from Claude Code |
-| `SubagentStart` | A subagent is spawned |
-| `SubagentStop` | A subagent completes |
-| `UserPromptSubmit` | User submits a prompt |
-| `TeammateIdle` | A teammate agent becomes idle |
-| `TaskCompleted` | A task finishes |
-| `PreCompact` | Before context compaction |
+| Hook                 | Description                                                     |
+| -------------------- | --------------------------------------------------------------- |
+| `PreToolUse`         | Before a tool executes (file edit, bash command, etc.)          |
+| `PostToolUse`        | After a tool completes successfully                             |
+| `PostToolUseFailure` | After a tool fails                                              |
+| `PermissionRequest`  | Claude Code asks for permission -- **blocks until you respond** |
+| `SessionStart`       | A new coding session begins                                     |
+| `SessionEnd`         | A coding session ends                                           |
+| `Stop`               | Claude Code stops execution                                     |
+| `Notification`       | General notification from Claude Code                           |
+| `SubagentStart`      | A subagent is spawned                                           |
+| `SubagentStop`       | A subagent completes                                            |
+| `UserPromptSubmit`   | User submits a prompt                                           |
+| `TeammateIdle`       | A teammate agent becomes idle                                   |
+| `TaskCompleted`      | A task finishes                                                 |
+| `PreCompact`         | Before context compaction                                       |
 
 ### Permission Flow
 
@@ -254,13 +264,13 @@ The `PermissionRequest` hook has a 180-second timeout in `.claude/settings.json`
 
 ### Hook Environment Variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SHOOTER_USE_LOCAL` | -- | Set `true` to connect to local server instead of remote URL |
-| `SHOOTER_LOCAL_PORT` | `3000` | Local server port when using `SHOOTER_USE_LOCAL` |
-| `SHOOTER_API_URL` | -- | Remote server URL (when not using local) |
-| `SHOOTER_PERMISSION_TIMEOUT` | `120` | Seconds to wait for a permission response |
-| `API_KEY` | -- | Bearer token (must match the server's `API_KEY`) |
+| Variable                     | Default | Description                                                 |
+| ---------------------------- | ------- | ----------------------------------------------------------- |
+| `SHOOTER_USE_LOCAL`          | --      | Set `true` to connect to local server instead of remote URL |
+| `SHOOTER_LOCAL_PORT`         | `54007` | Local server port when using `SHOOTER_USE_LOCAL`            |
+| `SHOOTER_API_URL`            | --      | Remote server URL (when not using local)                    |
+| `SHOOTER_PERMISSION_TIMEOUT` | `120`   | Seconds to wait for a permission response                   |
+| `API_KEY`                    | --      | Bearer token (must match the server's `API_KEY`)            |
 
 ---
 
@@ -282,7 +292,7 @@ docker build -t shooter .
 docker run -d \
   --name shooter \
   --env-file .env \
-  -p 3000:3000 \
+  -p 54007:54007 \
   -v shooter-data:/root/.shooter \
   --restart unless-stopped \
   shooter
@@ -290,6 +300,8 @@ docker run -d \
 
 The multi-stage Dockerfile uses `node:20-slim` and includes build tools for `node-pty` and `better-sqlite3` native addons. SQLite data is persisted in the `shooter-data` volume. The `.env` file is injected at runtime and never baked into the image.
 
+A separate `Dockerfile.test` is provided for verifying the fresh-user install experience in an isolated container.
+
 ### docker-compose.yml
 
 ```yaml
@@ -297,7 +309,7 @@ services:
   shooter:
     build: .
     ports:
-      - "3000:3000"
+      - '54007:54007'
     env_file:
       - .env
     volumes:
@@ -314,25 +326,25 @@ volumes:
 
 All endpoints require the `Authorization: Bearer <API_KEY>` header.
 
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/api/health` | Health check with server status |
-| `GET` | `/api/terminals` | List all active and recently exited terminals |
-| `POST` | `/api/terminals` | Create a new terminal session |
-| `GET` | `/api/terminals/:id` | Get details for a specific terminal |
-| `DELETE` | `/api/terminals/:id` | Kill and remove a terminal session |
-| `POST` | `/api/terminals/:id/resize` | Resize a terminal (cols, rows) |
-| `POST` | `/api/ws-ticket` | Generate a short-lived WebSocket auth ticket |
-| `GET` | `/api/ws-status` | Get connected WebSocket client count |
-| `POST` | `/api/notify` | Send a push notification via APNs or FCM |
-| `GET` | `/api/notify` | Check notification status and history |
-| `POST` | `/api/response` | Submit a permission allow/deny decision |
-| `GET` | `/api/response` | Poll for a pending permission decision |
-| `GET` | `/api/sessions` | List sessions across all projects |
-| `POST` | `/api/webhook` | Receive external webhook events |
-| `GET` | `/api/qr-config` | Generate QR code for mobile app pairing |
-| `POST` | `/api/device-token` | Register a device token (iOS or Android) |
-| `GET` | `/api/debug` | Debug information (APNs config, device token status) |
+| Method   | Path                        | Description                                          |
+| -------- | --------------------------- | ---------------------------------------------------- |
+| `GET`    | `/api/health`               | Health check with server status                      |
+| `GET`    | `/api/terminals`            | List all active and recently exited terminals        |
+| `POST`   | `/api/terminals`            | Create a new terminal session                        |
+| `GET`    | `/api/terminals/:id`        | Get details for a specific terminal                  |
+| `DELETE` | `/api/terminals/:id`        | Kill and remove a terminal session                   |
+| `POST`   | `/api/terminals/:id/resize` | Resize a terminal (cols, rows)                       |
+| `POST`   | `/api/ws-ticket`            | Generate a short-lived WebSocket auth ticket         |
+| `GET`    | `/api/ws-status`            | Get connected WebSocket client count                 |
+| `POST`   | `/api/notify`               | Send a push notification via APNs or FCM             |
+| `GET`    | `/api/notify`               | Check notification status and history                |
+| `POST`   | `/api/response`             | Submit a permission allow/deny decision              |
+| `GET`    | `/api/response`             | Poll for a pending permission decision               |
+| `GET`    | `/api/sessions`             | List sessions across all projects                    |
+| `POST`   | `/api/webhook`              | Receive external webhook events                      |
+| `GET`    | `/api/qr-config`            | Generate QR code for mobile app pairing              |
+| `POST`   | `/api/device-token`         | Register a device token (iOS or Android)             |
+| `GET`    | `/api/debug`                | Debug information (APNs config, device token status) |
 
 ### WebSocket Authentication
 
@@ -341,7 +353,7 @@ WebSocket connections use ticket-based auth. First call `POST /api/ws-ticket` wi
 ### Example: Create Terminal
 
 ```bash
-curl -X POST http://localhost:3000/api/terminals \
+curl -X POST http://localhost:54007/api/terminals \
   -H "Authorization: Bearer $API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"command": "claude", "cwd": "/Users/me/project", "cols": 80, "rows": 24}'
@@ -380,6 +392,24 @@ pnpm format:check  # Check formatting without writing
 
 **Note:** `pnpm dev` runs the Vite dev server, which does not include the WebSocket server or PTY manager. For full functionality (terminal sessions, live streaming), use `pnpm build && pnpm start`.
 
+### CLI Commands
+
+The `shooter` command (via `bin/shooter.cjs` or the global `shooter` symlink) supports:
+
+| Command              | Description                                                        |
+| -------------------- | ------------------------------------------------------------------ |
+| `shooter start`      | Start the server (default if no command given)                     |
+| `shooter stop`       | Stop the running server gracefully (SIGTERM, then SIGKILL after 5s)|
+| `shooter status`     | Show PID, URL, autostart state, log path                          |
+| `shooter autostart on`  | Enable autostart on login (LaunchAgent on macOS, systemd on Linux) |
+| `shooter autostart off` | Disable autostart and remove the service definition              |
+| `shooter logs`       | Tail server logs (log file on macOS, journalctl on Linux)          |
+| `shooter setup`      | Run the interactive setup wizard; pass `--auto` for non-interactive|
+| `shooter version`    | Print version number                                               |
+| `shooter help`       | Show all available commands                                        |
+
+Process state is tracked via a PID file at `~/.shooter/shooter.pid`. Logs are written to `~/.shooter/logs/shooter.log` when running via autostart.
+
 ### Type System
 
 Types are auto-generated from YAML specifications in `specs/types/` using [type-crafter](https://github.com/nicktaf/type-crafter). Never edit files in `src/generated/types/` directly -- edit the YAML specs and run `pnpm run gen:types`.
@@ -390,18 +420,19 @@ Types are auto-generated from YAML specifications in `specs/types/` using [type-
 
 ```
 shooter/
-  server.ts                        # HTTP + WebSocket server entry point
+  server.ts                        # HTTP + WebSocket server entry point (build guard check)
   package.json                     # Dependencies and scripts (pnpm only)
   Dockerfile                       # Multi-stage Docker build
+  Dockerfile.test                  # Test image for fresh-user install verification
   docker-compose.yml               # Docker Compose config
   .env.example                     # Environment variable template
   svelte.config.js                 # SvelteKit config (adapter-node)
   vite.config.ts                   # Vite config (node-pty external)
   bin/
-    shooter.cjs                    # CLI entry point (shooter start|setup|help)
+    shooter.cjs                    # CLI entry point (start|stop|status|autostart|logs|setup|help)
   scripts/
-    setup.cjs                      # Interactive setup wizard
-    install.sh                     # One-command curl installer
+    setup.cjs                      # Interactive setup wizard (--auto for non-interactive)
+    install.sh                     # One-command installer (full auto setup + cloudflared)
   .claude/
     hooks/notifier.cjs             # Unified hook notifier (Node.js)
     settings.json                  # Hook configuration (13 event types)
@@ -458,8 +489,9 @@ shooter/
 
 - Verify Node.js 20+ is installed: `node --version`
 - Ensure pnpm is used (npm and yarn are blocked): `pnpm --version`
-- Check that `pnpm build` completed without errors before running `pnpm start`
-- Confirm `.env` exists and `API_KEY` is set
+- Check that `pnpm build` completed without errors before running `pnpm start` -- `server.ts` has a build guard that exits with a clear error if `build/handler.js` is missing
+- Confirm `.env` exists and `API_KEY` is set (the server also checks `~/.shooter/.env` as a fallback)
+- On Linux, ensure build tools are installed: `python3`, `make`, `g++` (needed for native modules)
 
 ### WebSocket connections fail
 
@@ -479,7 +511,7 @@ shooter/
 
 - `API_KEY` must be exported in your shell environment, not just in `.env`: `export API_KEY="..."`
 - Verify the hooks are configured in `.claude/settings.json`
-- Test connectivity: `curl -H "Authorization: Bearer $API_KEY" http://localhost:3000/api/health`
+- Test connectivity: `curl -H "Authorization: Bearer $API_KEY" http://localhost:54007/api/health`
 
 ### Terminal sessions lost after restart
 
@@ -494,8 +526,8 @@ shooter/
 
 ### Port already in use
 
-- Default port is 3000. Set `PORT=<number>` in `.env` to use a different port.
-- Check what is using the port: `lsof -i :3000`
+- Default port is 54007. Set `PORT=<number>` in `.env` to use a different port.
+- Check what is using the port: `lsof -i :54007`
 
 ---