@dfosco/storyboard 0.6.3 → 0.6.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "type": "module",
   "license": "MIT",
   "description": "Storyboard prototyping framework — core engine, React integration, and canvas",

package/scaffold/AGENTS.md

@@ -100,7 +100,7 @@ The default location is in `.agents/plans`, but the user may ask for a specific
 
 ```bash
 npm run setup        # First-time: install deps, Caddy proxy, start proxy
-storyboard dev       # Start dev server (or: npm run dev)
+npm run dev          # Start dev server (wraps `storyboard dev`)
 npm run dev:vite     # Start vite directly (bypasses CLI)
 npm run build        # Production build
 npm run lint         # Run ESLint
@@ -108,14 +108,14 @@ npm run lint         # Run ESLint
 
 ### Storyboard CLI
 
-The `storyboard` CLI (`sb` alias) wraps dev tooling:
+The `storyboard` CLI (`sb` alias) wraps dev tooling. The standard `npm run dev` script in this repo just calls `storyboard dev` — use `npm run dev` unless you need a CLI-only feature (e.g. starting a dev server for a different worktree).
 
 | Command | Description |
 |---------|-------------|
-| `storyboard dev` | Start Vite with correct base path + update Caddy proxy |
+| `npm run dev` _(preferred)_ | Start the Vite dev server for the current worktree |
+| `storyboard dev [branch]` | Start a dev server — pass a branch to target a different worktree |
 | `storyboard code [branch]` | Open current worktree (or specific branch) in VS Code |
 | `storyboard setup` | Install deps, Caddy, `gh` check, start proxy |
-| `storyboard proxy` | Generate Caddyfile + start/reload Caddy |
 | `storyboard update:version [version]` | Update `@dfosco/storyboard-*` packages to latest (or specific version) |
 | `storyboard canvas read [name]` | Read canvas widgets with content, URLs, file paths, and bounds |
 | `storyboard canvas bounds [name]` | Get widget size and positional bounds (spatial queries) |
@@ -159,7 +159,7 @@ For the full canvas CLI reference (positioning, batch ops, collision detection),
 
 ### Dev URLs
 
-With Caddy proxy running (`storyboard setup`):
+With Caddy proxy running (set up via `npm run setup`):
 - Main: `http://storyboard.localhost/storyboard/`
 - Worktree `fix-bug`: `http://storyboard.localhost/fix-bug/storyboard/`
 
@@ -169,7 +169,7 @@ Without proxy (fallback with port numbers):
 
 ### Dev URL session state
 
-Whenever Copilot starts a dev server (e.g. `storyboard dev`), save the URL as `devURL` in the SQL session database. Read the proxy URL from the dev server's startup output (`[storyboard] proxy URL: <url>`):
+Whenever Copilot starts a dev server (e.g. `npm run dev`), save the URL as `devURL` in the SQL session database. Read the proxy URL from the dev server's startup output (`[storyboard] proxy URL: <url>`):
 
 ```sql
 INSERT OR REPLACE INTO session_state (key, value) VALUES ('devURL', 'http://storyboard.localhost/storyboard/');
@@ -180,7 +180,7 @@ If the proxy is not running, fall back to the direct URL from the output (`[stor
 This `devURL` is used as the default target by the **agent-browser** skill when the user says "inspect the browser", "check the page", etc. — no URL argument needed.
 
 **How `devURL` gets set:**
-- **Automatically** — when Copilot runs `storyboard dev` or `npm run dev`, persist the proxy URL (or direct URL if no proxy) to `devURL`.
+- **Automatically** — when Copilot runs `npm run dev` (or directly `storyboard dev`), persist the proxy URL (or direct URL if no proxy) to `devURL`.
 - **From user input** — if the user says "the dev server is at http://localhost:3000", save that as `devURL`.
 - **Implicitly from inspection** — if no `devURL` is set and the user says "inspect http://storyboard.localhost/storyboard/", that URL becomes the `devURL` for the rest of the session.
 

package/scaffold/skills/canvas/SKILL.md

@@ -23,7 +23,7 @@ Reads, manipulates, and arranges widgets on a Storyboard canvas. Supports absolu
 
 ## Prerequisites
 
-- The dev server **must** be running (`storyboard dev` or `npm run dev`)
+- The dev server **must** be running (`npm run dev`, or `storyboard dev` from the CLI directly)
 - The target canvas must already exist
 
 ## Critical: Never Parse JSONL Directly

package/scaffold/skills/migrate-0.5.0/SKILL.md

@@ -264,7 +264,7 @@ npx storyboard setup
 npm run build
 
 # Start dev server to verify everything works
-npx storyboard dev
+npm run dev
 ```
 
 ---

package/scaffold/skills/ship/SKILL.md

@@ -200,7 +200,7 @@ If clips was skipped in Step 3, skip this step too.
 Run the dev server in the worktree so the user can immediately preview changes:
 
 ```bash
-npx storyboard dev
+npm run dev
 ```
 
 This is the **only** place the dev server starts during a ship workflow — the worktree skill skips its own dev server step when called from ship.
@@ -234,4 +234,4 @@ User says: "ship a feature to add canvas grid snapping"
 8. Updates architecture docs, README, DOCS as needed, commits
 9. Pushes `1.2.0--canvas-grid-snapping` to origin
 10. Marks clips tasks as closed
-11. Starts dev server (`npx storyboard dev`) in the worktree
+11. Starts dev server (`npm run dev`) in the worktree

package/scaffold/skills/worktree/SKILL.md

@@ -19,7 +19,7 @@ When the user asks for a worktree named `<branch-name>`:
 
 ### Preferred: Use `npx storyboard dev <branch>`
 
-The `storyboard` CLI handles the full worktree lifecycle in a single command:
+The `storyboard` CLI handles the full worktree lifecycle in a single command. (Plain `npm run dev` only starts a server for the current worktree — to target a different worktree from anywhere, use the CLI directly.)
 
 ```bash
 npx storyboard dev <branch-name>

package/src/core/autosync/server.test.js

@@ -21,7 +21,7 @@ describe('autosync scope helpers', () => {
     expect(matchesAutosyncScope('canvas', 'src/canvas/notes.txt')).toBe(true)
     expect(matchesAutosyncScope('canvas', 'assets/canvas/images/photo.png')).toBe(true)
     expect(matchesAutosyncScope('canvas', 'assets/canvas/snapshots/snapshot-widget--latest.webp')).toBe(true)
-    expect(matchesAutosyncScope('canvas', 'assets/.storyboard-public/terminal-snapshots/agent-abc.snapshot.json')).toBe(true)
+    expect(matchesAutosyncScope('canvas', 'assets/.storyboard-public/terminal-snapshots/agents.snapshot.json')).toBe(true)
     expect(matchesAutosyncScope('canvas', 'src/prototypes/demo/default.flow.json')).toBe(false)
   })
 

package/src/core/canvas/hot-pool.js

@@ -551,8 +551,8 @@ export class HotPool {
             const paneContent = execSync(
               // H1: include scrollback so the readiness echo can still be
               // matched after the agent's TUI repaints over it.
-              `tmux capture-pane -t "${tmuxName}" -p -S -200`,
-              { encoding: 'utf8', timeout: 1000 }
+              `tmux capture-pane -t "${tmuxName}" -p -S -200 2>/dev/null`,
+              { encoding: 'utf8', timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] }
             )
             // Strip ANSI escape sequences — agent CLIs use heavy formatting
             // eslint-disable-next-line no-control-regex
@@ -580,14 +580,13 @@ export class HotPool {
       return this.#tmuxSessionExists(tmuxName)
     }
 
-    // Send postStartup command (e.g. "/allow-all on")
+    // postStartup is NOT sent here intentionally. It's deferred to widget
+    // handoff (see terminal-server.js warm path) so it runs *after* the
+    // identity/role injection — mode-toggling slash commands like
+    // `/autopilot` must come last so canvas context lands in conversation
+    // history before the agent enters autopilot mode.
     if (postStartup) {
-      try {
-        await new Promise(r => setTimeout(r, 500))
-        execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(postStartup)}`, { stdio: 'ignore' })
-        execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
-        this.#log(`⊕ AGENT ${sessionId} postStartup sent: ${postStartup}`)
-      } catch { /* empty */ }
+      this.#log(`⊕ AGENT ${sessionId} postStartup "${postStartup}" deferred to widget handoff`)
     }
 
     this.#log(`⊕ AGENT ${sessionId} ready (${signalFilePath ? 'file' : 'signal'}: "${readinessSignal || 'file'}")`)
@@ -615,8 +614,8 @@ export class HotPool {
     if (this.#agentConfig?.startupCommand) {
       try {
         const cmd = execSync(
-          `tmux display-message -t "${session.tmuxName}" -p "#{pane_current_command}"`,
-          { encoding: 'utf8', timeout: 1000 }
+          `tmux display-message -t "${session.tmuxName}" -p "#{pane_current_command}" 2>/dev/null`,
+          { encoding: 'utf8', timeout: 1000, stdio: ['ignore', 'pipe', 'ignore'] }
         ).trim()
         // Agent exited if the pane is back to a shell
         const shells = ['zsh', 'bash', 'sh', 'fish']

package/src/core/canvas/terminal-server.js

@@ -23,7 +23,7 @@
  */
 
 import { execSync } from 'node:child_process'
-import { readFileSync, mkdirSync, writeFileSync, renameSync, existsSync, unlinkSync, rmSync } from 'node:fs'
+import { readFileSync, mkdirSync, writeFileSync, renameSync, existsSync, unlinkSync, rmSync, readdirSync } from 'node:fs'
 import { resolve, join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { tmpdir } from 'node:os'
@@ -409,6 +409,110 @@ function publicSnapshotDir() {
   return join(process.cwd(), 'assets', '.storyboard-public', 'terminal-snapshots')
 }
 
+/** Public snapshot index filenames (single consolidated files for all agents). */
+const SNAPSHOT_INDEX_JSON = 'agents.snapshot.json'
+const SNAPSHOT_INDEX_TXT = 'agents-txt.snapshot.json'
+
+/** Max entries kept in the snapshot indexes before GC drops the oldest by timestamp. */
+const SNAPSHOT_INDEX_MAX_ENTRIES = 50
+
+/** In-memory cache of the snapshot indexes to avoid re-reading on every capture. */
+let snapshotIndexCache = null
+let snapshotTxtIndexCache = null
+let snapshotLegacyFilesCleaned = false
+
+function emptyIndex() {
+  return { version: 1, updatedAt: null, agents: {} }
+}
+
+function readIndexFile(filePath) {
+  try {
+    if (!existsSync(filePath)) return emptyIndex()
+    const parsed = JSON.parse(readFileSync(filePath, 'utf8'))
+    if (parsed && typeof parsed === 'object' && parsed.agents && typeof parsed.agents === 'object') {
+      return { version: parsed.version || 1, updatedAt: parsed.updatedAt || null, agents: parsed.agents }
+    }
+  } catch { /* fall through */ }
+  return emptyIndex()
+}
+
+function loadSnapshotIndexes() {
+  if (!snapshotIndexCache) {
+    snapshotIndexCache = readIndexFile(join(publicSnapshotDir(), SNAPSHOT_INDEX_JSON))
+  }
+  if (!snapshotTxtIndexCache) {
+    snapshotTxtIndexCache = readIndexFile(join(publicSnapshotDir(), SNAPSHOT_INDEX_TXT))
+  }
+  return { jsonIndex: snapshotIndexCache, txtIndex: snapshotTxtIndexCache }
+}
+
+/**
+ * Garbage-collect index entries to keep size manageable.
+ * Drops oldest entries by timestamp until under the cap. Operates on both
+ * indexes together so they stay in sync.
+ */
+function gcSnapshotIndexes(jsonIndex, txtIndex) {
+  const keys = Object.keys(jsonIndex.agents)
+  if (keys.length <= SNAPSHOT_INDEX_MAX_ENTRIES) return
+  const sorted = keys
+    .map((k) => ({ k, t: jsonIndex.agents[k]?.timestamp || '' }))
+    .sort((a, b) => (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+  const dropCount = keys.length - SNAPSHOT_INDEX_MAX_ENTRIES
+  for (let i = 0; i < dropCount; i++) {
+    const id = sorted[i].k
+    delete jsonIndex.agents[id]
+    delete txtIndex.agents[id]
+  }
+}
+
+function atomicWriteJson(filePath, data) {
+  const tmpPath = filePath + '.tmp'
+  try {
+    writeFileSync(tmpPath, JSON.stringify(data, null, 2), 'utf8')
+    renameSync(tmpPath, filePath)
+  } catch (err) {
+    try { if (existsSync(tmpPath)) unlinkSync(tmpPath) } catch {} // eslint-disable-line no-empty
+    throw err
+  }
+}
+
+function writeSnapshotIndexes(jsonIndex, txtIndex) {
+  const sDir = publicSnapshotDir()
+  try { mkdirSync(sDir, { recursive: true }) } catch {} // eslint-disable-line no-empty
+  const now = new Date().toISOString()
+  jsonIndex.updatedAt = now
+  txtIndex.updatedAt = now
+  try {
+    atomicWriteJson(join(sDir, SNAPSHOT_INDEX_JSON), jsonIndex)
+  } catch (err) {
+    devLog().logEvent('error', 'Failed to write agents.snapshot.json', { error: err.message })
+  }
+  try {
+    atomicWriteJson(join(sDir, SNAPSHOT_INDEX_TXT), txtIndex)
+  } catch (err) {
+    devLog().logEvent('error', 'Failed to write agents-txt.snapshot.json', { error: err.message })
+  }
+}
+
+/**
+ * One-time cleanup: remove legacy per-widget snapshot files left in the
+ * public dir from before the consolidated-index format. Runs on first call.
+ */
+function cleanupLegacySnapshotFiles() {
+  if (snapshotLegacyFilesCleaned) return
+  snapshotLegacyFilesCleaned = true
+  const sDir = publicSnapshotDir()
+  if (!existsSync(sDir)) return
+  try {
+    for (const file of readdirSync(sDir)) {
+      if (file === SNAPSHOT_INDEX_JSON || file === SNAPSHOT_INDEX_TXT) continue
+      if (file.endsWith('.snapshot.json') || file.endsWith('.snapshot.txt')) {
+        try { unlinkSync(join(sDir, file)) } catch {} // eslint-disable-line no-empty
+      }
+    }
+  } catch { /* empty */ }
+}
+
 /**
  * Read the `private` prop for a widget from the terminal config.
  * Returns true if the widget has props.private === true.
@@ -496,39 +600,28 @@ function captureSnapshot({ tmuxName, widgetId, canvasId, prettyName, cols, rows,
     try { if (existsSync(txtTmpPath)) unlinkSync(txtTmpPath) } catch {} // eslint-disable-line no-empty
   }
 
-  // ── Public snapshot (assets/.storyboard-public/terminal-snapshots/) ──
+  // ── Public snapshot index (assets/.storyboard-public/terminal-snapshots/) ──
+  // We maintain two consolidated index files keyed by widgetId:
+  //   - agents.snapshot.json     → structured data
+  //   - agents-txt.snapshot.json → human-readable text payloads
+  cleanupLegacySnapshotFiles()
   const isPrivate = isWidgetPrivate(widgetId, canvasId)
-  const sDir = publicSnapshotDir()
-  const snapshotPath = join(sDir, `${widgetId}.snapshot.json`)
-  const snapshotTxtPath = join(sDir, `${widgetId}.snapshot.txt`)
-  const tildeSnapshotPath = join(sDir, `~${widgetId}.snapshot.json`)
-  const tildeSnapshotTxtPath = join(sDir, `~${widgetId}.snapshot.txt`)
+  const { jsonIndex, txtIndex } = loadSnapshotIndexes()
 
   if (isPrivate) {
-    // Rename existing public snapshots to tilde-prefixed (gitignored) versions
-    if (existsSync(snapshotPath)) {
-      try { renameSync(snapshotPath, tildeSnapshotPath) } catch {} // eslint-disable-line no-empty
-    }
-    if (existsSync(snapshotTxtPath)) {
-      try { renameSync(snapshotTxtPath, tildeSnapshotTxtPath) } catch {} // eslint-disable-line no-empty
-    }
+    let changed = false
+    if (jsonIndex.agents[widgetId]) { delete jsonIndex.agents[widgetId]; changed = true }
+    if (txtIndex.agents[widgetId]) { delete txtIndex.agents[widgetId]; changed = true }
+    if (changed) writeSnapshotIndexes(jsonIndex, txtIndex)
     return
   }
 
-  // If un-privated, restore from tilde if the public files don't exist yet
-  if (existsSync(tildeSnapshotPath) && !existsSync(snapshotPath)) {
-    try { renameSync(tildeSnapshotPath, snapshotPath) } catch {} // eslint-disable-line no-empty
-  }
-  if (existsSync(tildeSnapshotTxtPath) && !existsSync(snapshotTxtPath)) {
-    try { renameSync(tildeSnapshotTxtPath, snapshotTxtPath) } catch {} // eslint-disable-line no-empty
-  }
-
   const snapshotScrollback = getRollingBufferContent(tmuxName, SNAPSHOT_MAX_AGE_MS)
   const strippedPane = stripAnsi(paneContent)
   const strippedScrollback = stripAnsi(snapshotScrollback)
 
-  // ── JSON snapshot ──
-  const snapshotData = {
+  // ── JSON entry ──
+  jsonIndex.agents[widgetId] = {
     widgetId,
     canvasId,
     prettyName: prettyName || null,
@@ -539,24 +632,7 @@ function captureSnapshot({ tmuxName, widgetId, canvasId, prettyName, cols, rows,
     scrollback: strippedScrollback,
   }
 
-  try {
-    mkdirSync(sDir, { recursive: true })
-  } catch (err) {
-    devLog().logEvent('error', 'Failed to create public snapshot dir', { dir: sDir, error: err.message })
-    return
-  }
-
-  const snapshotTmpPath = snapshotPath + '.tmp'
-  try {
-    writeFileSync(snapshotTmpPath, JSON.stringify(snapshotData, null, 2), 'utf8')
-    renameSync(snapshotTmpPath, snapshotPath)
-  } catch (err) {
-    devLog().logEvent('error', 'Failed to write public snapshot JSON', { widgetId, error: err.message, path: snapshotPath })
-    try { if (existsSync(snapshotTmpPath)) unlinkSync(snapshotTmpPath) } catch {} // eslint-disable-line no-empty
-  }
-
-  // ── Human-readable text snapshot ──
-  const snapshotTxtTmpPath = snapshotTxtPath + '.tmp'
+  // ── Text entry ──
   try {
     const screenText = strippedPane.replace(/\r\n/g, '\n').replace(/\n+$/, '')
     const scrollText = strippedScrollback.replace(/\r\n/g, '\n').replace(/\n+$/, '')
@@ -583,12 +659,13 @@ function captureSnapshot({ tmuxName, widgetId, canvasId, prettyName, cols, rows,
       snpTxt += scrollText + '\n'
     }
 
-    writeFileSync(snapshotTxtTmpPath, snpTxt, 'utf8')
-    renameSync(snapshotTxtTmpPath, snapshotTxtPath)
+    txtIndex.agents[widgetId] = snpTxt
   } catch (err) {
-    devLog().logEvent('error', 'Failed to write public snapshot txt', { widgetId, error: err.message })
-    try { if (existsSync(snapshotTxtTmpPath)) unlinkSync(snapshotTxtTmpPath) } catch {} // eslint-disable-line no-empty
+    devLog().logEvent('error', 'Failed to build snapshot text entry', { widgetId, error: err.message })
   }
+
+  gcSnapshotIndexes(jsonIndex, txtIndex)
+  writeSnapshotIndexes(jsonIndex, txtIndex)
 }
 
 /** Start periodic snapshot capture for a session */
@@ -1209,11 +1286,15 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
           const finalize = () => {
             if (completed) return
             completed = true
+            // Identity/role MUST be injected before postStartup. Commands like
+            // `/autopilot` flip the agent into a mode where the next message is
+            // consumed as a task — so we want canvas context in conversation
+            // history *first*, then the mode-toggling slash command.
+            injectIdentityMessage(tmuxName, { widgetId, displayName: prettyName, canvasId, branch, serverUrl })
+            injectRoleMessageForWidget(tmuxName, widgetId)
             if (postStartup) {
               tmuxSubmit(tmuxName, postStartup)
             }
-            injectIdentityMessage(tmuxName, { widgetId, displayName: prettyName, canvasId, branch, serverUrl })
-            injectRoleMessageForWidget(tmuxName, widgetId)
             // Bind to messaging bus for live delivery + backfill missed messages
             setTimeout(() => {
               migratePendingMessages(widgetId, branch, canvasId).then(() => {
@@ -1408,11 +1489,15 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
                   clearInterval(pollInterval)
                   try { rmSync(readyFilePath, { force: true }) } catch { /* empty */ }
                   setTimeout(() => {
+                    // Identity/role/messaging-bind MUST happen BEFORE postStartup.
+                    // Slash commands like `/autopilot` flip the agent into a mode
+                    // where the next message is consumed as a task — so we want
+                    // canvas context (widgetId, configFile, role) in conversation
+                    // history first, then the mode-toggling slash command last.
+                    softBind()
                     if (postStartup) {
-                      tmuxSubmit(tmuxName, postStartup)
+                      setTimeout(() => tmuxSubmit(tmuxName, postStartup), 1500)
                     }
-                    // Ensure identity/bind happened (no-op if already soft-bound)
-                    softBind()
                   }, 500)
                   if (reason === 'soft-bind-timeout') {
                     devLog(`[terminal-server] readiness slow for ${widgetId} (${tmuxName}); soft-binding now, will run postStartup when .ready arrives`)
@@ -1765,15 +1850,17 @@ export function readTerminalBuffer(widgetId, { maxLength } = {}) {
 }
 
 /**
- * Read a terminal public snapshot by widget ID.
- * Checks new path first, falls back to legacy path.
+ * Read a terminal public snapshot by widget ID from the consolidated index.
+ * Falls back to legacy nested path if not present.
  */
 export function readTerminalSnapshot(widgetId, canvasId) {
-  // New path: assets/.storyboard-public/terminal-snapshots/<widgetId>.snapshot.json
-  const newPath = join(publicSnapshotDir(), `${widgetId}.snapshot.json`)
+  // New: consolidated index at agents.snapshot.json
+  const indexPath = join(publicSnapshotDir(), SNAPSHOT_INDEX_JSON)
   try {
-    if (existsSync(newPath)) {
-      return JSON.parse(readFileSync(newPath, 'utf8'))
+    if (existsSync(indexPath)) {
+      const parsed = JSON.parse(readFileSync(indexPath, 'utf8'))
+      const entry = parsed?.agents?.[widgetId]
+      if (entry) return entry
     }
   } catch { /* empty */ }
 

package/src/core/cli/dev.js

@@ -188,8 +188,13 @@ async function main() {
   // Port resolution priority:
   //   1. --port CLI flag (always wins, never strict)
   //   2. config.port from storyboard.config.json (strict — fail if taken)
+  //      — but ONLY for the main worktree. Worktrees ignore the pinned
+  //      port so they can run concurrently with main on auto-assigned
+  //      ports (otherwise every worktree fails with "port already in use"
+  //      whenever main is up).
   //   3. auto-assigned per-worktree port (non-strict — Vite picks next free)
-  const configuredPort = readConfiguredPort(targetCwd)
+  const rawConfiguredPort = readConfiguredPort(targetCwd)
+  const configuredPort = worktreeName === 'main' ? rawConfiguredPort : null
   const strictPort = flags.port == null && configuredPort != null
   const port = flags.port || configuredPort || getPort(worktreeName)
   const basePath = resolveBasePath(targetCwd)
@@ -322,6 +327,12 @@ async function main() {
 
     const makeFilter = (sink) => {
       let buf = ''
+      // stderr must always pass through, even before "ready in" — otherwise
+      // pre-ready failures (e.g. "Port already in use" when --strictPort is
+      // set) get swallowed and the CLI appears to exit silently. We still
+      // route through the queue once the mascot starts animating so the
+      // redraw isn't shifted mid-frame.
+      const isErr = sink === process.stderr
       return (chunk) => {
         buf += chunk.toString()
         const lines = buf.split('\n')
@@ -338,12 +349,15 @@ async function main() {
             continue
           }
           // Pre-ready: only let the "ready in" line through, then start
-          // the mascot animation.
+          // the mascot animation. Stderr is always passed through so
+          // startup errors aren't silently dropped.
           if (/ready in \d/.test(line)) {
             sink.write(line + '\n')
             renderOnce()
+          } else if (isErr) {
+            sink.write(line + '\n')
           }
-          // else: swallow pre-ready chatter
+          // else: swallow pre-ready stdout chatter
         }
       }
     }

package/src/core/cli/setup.js

@@ -398,32 +398,33 @@ if (isInstalled('code')) {
   p.log.success('Canvas asset directories ready')
 }
 
-// 7a. Scaffold .gitignore entries for private canvas images
+// 7a. Scaffold .gitignore entries for storyboard runtime + private files
 {
   const gitignorePath = '.gitignore'
   const privatePatterns = [
+    // Storyboard runtime state — entirely per-machine, never committed.
+    // Files that NEED to be public must be written to .storyboard-public/
+    // (or assets/.storyboard-public/) instead.
+    '.storyboard/',
+    // Private canvas images / snapshots (tilde prefix = not committed)
     'src/canvas/images/~*',
     'assets/canvas/images/~*',
     'assets/canvas/snapshots/~*',
     'assets/.storyboard-public/terminal-snapshots/~*',
-    // Local-only canvases & prototypes (loaded by `npx storyboard dev`,
-    // excluded from `npm run build`)
-    'src/canvas/**/~*.canvas.jsonl',
-    'src/canvas/~*/',
-    'src/prototypes/~*/',
-    'src/prototypes/**/~*.{flow,object,record,prototype,folder}.json',
-    // Per-user local state (setup version marker, agent prefs, future onboarding state)
-    '.storyboard/.user.json',
+    // Drafts canvases & prototypes — anything inside a `drafts/` dir is
+    // loaded by `npx storyboard dev` but excluded from `npm run build`.
+    'src/canvas/**/drafts/',
+    'src/prototypes/**/drafts/',
   ]
   if (existsSync(gitignorePath)) {
     try {
       let content = readFileSync(gitignorePath, 'utf-8')
       const missing = privatePatterns.filter(p => !content.includes(p))
       if (missing.length > 0) {
-        const block = '\n# Private canvas images (tilde prefix = not committed)\n' + missing.join('\n') + '\n'
+        const block = '\n# Storyboard: runtime state (gitignored) + private tilde-prefixed files\n' + missing.join('\n') + '\n'
         content = content.trimEnd() + '\n' + block
         writeFileSync(gitignorePath, content, 'utf-8')
-        p.log.success('Added private image patterns to .gitignore')
+        p.log.success('Added storyboard patterns to .gitignore')
       }
     } catch { /* ignore */ }
   }

package/src/core/cli/terminal-welcome.js

@@ -273,14 +273,20 @@ async function launchAgent(agent, { isInitialStartup = false } = {}) {
               clearInterval(pollInterval)
               pollInterval = null
               setTimeout(() => {
-                if (agent.postStartup) {
-                  try {
-                    execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(agent.postStartup)}`, { stdio: 'ignore' })
-                    execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
-                  } catch { /* empty */ }
-                }
+                // Identity MUST be injected BEFORE postStartup. Slash commands
+                // like `/autopilot` flip the agent into a mode where the next
+                // message is consumed as a task — so canvas context needs to be
+                // in conversation history before the mode-toggling command.
                 injectIdentityMessage(tmuxName)
                 setTimeout(() => deliverPendingMessages(tmuxName), 2000)
+                if (agent.postStartup) {
+                  setTimeout(() => {
+                    try {
+                      execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(agent.postStartup)}`, { stdio: 'ignore' })
+                      execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+                    } catch { /* empty */ }
+                  }, 3500)
+                }
               }, 500)
             }
           } catch { /* empty */ }