@dfosco/storyboard-core 4.2.6 → 4.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.2.6",
+  "version": "4.2.8",
   "type": "module",
   "license": "MIT",
   "bin": {

package/scaffold/AGENTS.md

@@ -66,7 +66,7 @@ The default location is in `.agents/plans`, but the user may ask for a specific
 
 - **create** (`.agents/skills/create/SKILL.md`) — Walks through creating Storyboard assets: prototype, external prototype, flow, page, canvas, object, or record.
 
-- **worktree** (`.agents/skills/worktree/SKILL.md`) — Creates a git worktree in `.worktrees/<branch-name>` and switches into it.
+- **worktree** (`.agents/skills/worktree/SKILL.md`) — Creates a git worktree in `worktrees/<branch-name>` and switches into it.
 
 - **tools** (`.agents/skills/tools/SKILL.md`) — Reference for creating toolbar tools: config schema, handlers, surfaces, and render types.
 

package/scaffold/skills/ship/SKILL.md

@@ -34,7 +34,7 @@ Invoke the **worktree** skill to create a git worktree for the feature branch.
 - If the user provided an explicit branch name, use that instead.
 - Use `ask_user` to confirm the branch name before creating the worktree.
 
-After the worktree is created, all subsequent work happens inside `.worktrees/<branch-name>` **at the repository root** (use `git rev-parse --show-toplevel` to find the root). Never create worktrees nested inside other worktrees.
+After the worktree is created, all subsequent work happens inside `worktrees/<branch-name>` **at the repository root** (use `git rev-parse --show-toplevel` to find the root). Never create worktrees nested inside other worktrees.
 
 ### Step 2: Plan the feature
 

package/scaffold/skills/worktree/SKILL.md

@@ -4,7 +4,7 @@
 
 ## What This Does
 
-Creates a git worktree for a given branch name inside `.worktrees/` and switches into it.
+Creates a git worktree for a given branch name inside `worktrees/` and switches into it.
 
 ---
 
@@ -12,37 +12,23 @@ Creates a git worktree for a given branch name inside `.worktrees/` and switches
 
 When the user asks for a worktree named `<branch-name>`:
 
-### Step 0: Slugify the branch name
-
-Sanitize the branch name to avoid filesystem and subdomain issues:
-
-1. Convert to lowercase.
-2. Replace dots (`.`), spaces, underscores, and other non-alphanumeric characters (except `-` and `/`) with hyphens.
-3. Collapse consecutive hyphens into one.
-4. Trim leading/trailing hyphens from each segment.
-
-**Examples:**
-- `feature.v2` → `feature-v2`
-- `v3.11.0` → `v3-11-0`
-- `my_cool.feature` → `my-cool-feature`
-- `UPPER.Case` → `upper-case`
-
-Use the slugified name for both the **branch name** and **worktree directory** throughout the rest of the workflow.
-
 ### Step 1: Create the worktree
 
 If the branch already exists locally or on the remote:
 
 ```bash
-git worktree add .worktrees/<branch-name> <branch-name>
+git worktree add worktrees/<branch-name> <branch-name>
 ```
 
-If the branch does NOT exist yet, create it from the current HEAD:
+If the branch does NOT exist yet, create it **from the current branch** (NOT from main):
 
 ```bash
-git worktree add .worktrees/<branch-name> -b <branch-name>
+CURRENT_BRANCH=$(git branch --show-current)
+git worktree add worktrees/<branch-name> -b <branch-name> "$CURRENT_BRANCH"
 ```
 
+> **⚠️ CRITICAL:** Always pass the current branch as the start-point. Without it, git defaults to HEAD of the main worktree, which may be a completely different branch.
+
 ### Step 2: Register a dev-server port
 
 Assign a unique port for this worktree so multiple dev servers can run simultaneously.
@@ -59,12 +45,12 @@ Or if the project has `scripts/worktree-port.js`:
 node scripts/worktree-port.js <branch-name>
 ```
 
-This writes to `.worktrees/ports.json` (gitignored). The dev server (`npx storyboard-dev`) reads from this file automatically.
+This writes to `worktrees/ports.json` (gitignored). The dev server (`npx storyboard-dev`) reads from this file automatically.
 
 ### Step 3: Change into the worktree directory
 
 ```bash
-cd .worktrees/<branch-name>
+cd worktrees/<branch-name>
 ```
 
 All subsequent commands in the session should run from this directory.
@@ -99,9 +85,9 @@ The dev server automatically uses the port assigned in Step 2.
 
 ## Notes
 
-- Worktrees live in `.worktrees/` at the repo root — this directory is already gitignored.
+- Worktrees live in `worktrees/` at the repo root — this directory is already gitignored.
 - The branch name comes from the user's request (e.g., "create worktree comments-redo" → branch is `comments-redo`).
 - **Always slugify** the branch name (Step 0) before creating the worktree. Dots cause issues with subdomain routing and are replaced with hyphens.
 - If the worktree already exists, inform the user and `cd` into it instead of recreating it.
 - Port assignments are stable — once a worktree gets a port, it keeps it across restarts.
-- To see all assigned ports, check `.worktrees/ports.json`.
+- To see all assigned ports, check `worktrees/ports.json`.

package/src/canvas/terminal-config.js

@@ -42,9 +42,9 @@ function readDevDomain() {
 /** Detect worktree name */
 function getWorktreeName() {
   try {
-    // Check if we're in a .worktrees/ directory
+    // Check if we're in a worktrees/ directory
     const cwd = rootDir
-    const match = cwd.match(/\.worktrees\/([^/]+)/)
+    const match = cwd.match(/worktrees\/([^/]+)/)
     return match ? match[1] : 'main'
   } catch { return 'main' }
 }

package/src/cli/branch.js

@@ -2,18 +2,24 @@
  * storyboard branch — Interactive guide to switch to a branch worktree.
  *
  * Deterministic flow (no AI):
- *   1. Ask which branch to work on
- *   2. Stash uncommitted work (named stash for safety)
- *   3. Create worktree if needed (git worktree add + npm install)
- *   4. Pull --rebase from origin
- *   5. Apply stash into the new worktree
- *   6. Confirm to user
+ *   1. Ask which branch to work on (or accept --worktree flag)
+ *   2. If existing worktree:
+ *      a. Stash uncommitted work in source (named stash)
+ *      b. Ensure target is on the correct branch
+ *      c. Apply source stash in target
+ *   3. If new worktree:
+ *      a. Stash uncommitted work in source
+ *      b. Create worktree (git worktree add + npm install)
+ *      c. Pull --rebase from origin
+ *      d. Apply source stash in target
+ *   4. Confirm to user
  *
  * Also available as post-setup prompt in setup.js.
  *
  * Usage:
- *   npx storyboard branch
- *   npx storyboard branch <name>   # skip the prompt
+ *   npx storyboard branch                    # interactive
+ *   npx storyboard branch <name>             # positional, skip prompt
+ *   npx storyboard branch --worktree=<name>  # non-interactive flag
  */
 
 import * as p from '@clack/prompts'
@@ -22,8 +28,14 @@ import { existsSync } from 'fs'
 import { resolve } from 'path'
 import { repoRoot, worktreeDir, listWorktrees, getPort, detectWorktreeName } from '../worktree/port.js'
 import { hasUncommittedChanges, localBranchExists } from './dev-helpers.js'
+import { parseFlags } from './flags.js'
 import { dim, green, bold, cyan } from './intro.js'
 
+const flagSchema = {
+  worktree: { type: 'string', description: 'Target worktree/branch name (non-interactive)' },
+  cd: { type: 'boolean', default: false, description: 'Output shell-evaluable cd command (for eval)' },
+}
+
 /** Check if a remote branch exists on origin. */
 function remoteBranchExists(name, cwd) {
   try {
@@ -34,7 +46,7 @@ function remoteBranchExists(name, cwd) {
   }
 }
 
-/** Get the current branch name. */
+/** Get the current branch name in a given directory. */
 function currentBranch(cwd) {
   try {
     return execFileSync('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' }).trim()
@@ -55,96 +67,151 @@ function isValidBranchName(name) {
   return undefined
 }
 
-export async function runBranchGuide(branchArg) {
-  const root = repoRoot()
-  const existing = listWorktrees()
-  const fromBranch = currentBranch(root)
-  const fromWorktree = detectWorktreeName()
+/** Build a timestamped stash message. */
+function stashMessage(from, to) {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-')
+  return `from-${from}-to-${to}-${ts}`
+}
 
-  // 1. Get branch name
-  let targetBranch = branchArg?.trim()
+/**
+ * Stash uncommitted changes (including untracked files) and return the stash ref SHA.
+ * Returns null if nothing was stashed.
+ */
+function stashChanges(cwd, message) {
+  if (!hasUncommittedChanges(cwd)) return null
 
-  if (!targetBranch) {
-    if (existing.length > 0) {
-      // Render as columns that fit the terminal width
-      const maxLen = Math.max(...existing.map(w => w.length))
-      const colWidth = maxLen + 2
-      const termWidth = process.stdout.columns || 80
-      const cols = Math.max(1, Math.floor(termWidth / colWidth))
-      const rows = Math.ceil(existing.length / cols)
-      const lines = []
-      for (let r = 0; r < rows; r++) {
-        const parts = []
-        for (let c = 0; c < cols; c++) {
-          const idx = c * rows + r
-          if (idx < existing.length) {
-            parts.push(cyan(existing[idx].padEnd(colWidth)))
-          }
-        }
-        lines.push(`  ${parts.join('')}`)
+  p.log.step('Stashing uncommitted work…')
+  try {
+    execFileSync('git', ['stash', 'push', '-u', '-m', message], { cwd, stdio: 'pipe' })
+    // Capture the exact stash SHA so we can apply it by ref later
+    const sha = execFileSync('git', ['stash', 'list', '--format=%H', '-1'], { cwd, encoding: 'utf8' }).trim()
+    p.log.success(`Work stashed: ${dim(message)}`)
+    return sha
+  } catch {
+    p.log.warning('Could not stash changes — proceeding anyway')
+    return null
+  }
+}
+
+/**
+ * Apply a specific stash by SHA in the given directory.
+ * Uses apply (not pop) so the backup remains in the stash list.
+ */
+function applyStash(cwd, stashSha) {
+  try {
+    execFileSync('git', ['stash', 'apply', stashSha], { cwd, stdio: 'pipe' })
+    p.log.success('Previous work applied to this branch')
+    return true
+  } catch {
+    p.log.warning('Stash apply had conflicts — resolve them manually')
+    p.log.info(`  Your work is safe in ${dim('git stash list')}`)
+    return false
+  }
+}
+
+/**
+ * Core logic for switching to an EXISTING worktree.
+ *
+ * 1. Stash source changes (if any)
+ * 2. Ensure target worktree is on the expected branch
+ * 3. Apply source stash in target
+ */
+function switchToExistingWorktree(targetBranch, { sourceDir, fromBranch }) {
+  const targetDir = worktreeDir(targetBranch)
+
+  // 1. Stash source changes
+  const sourceStashSha = stashChanges(sourceDir, stashMessage(fromBranch, targetBranch))
+
+  // 2. Ensure target is on the correct branch
+  const targetCurrentBranch = currentBranch(targetDir)
+
+  if (targetCurrentBranch !== targetBranch) {
+    // Target worktree is on a different branch — check if it's clean
+    if (hasUncommittedChanges(targetDir)) {
+      p.log.error(
+        `Worktree ${bold(targetBranch)} is on branch ${bold(targetCurrentBranch)} with uncommitted changes.`
+      )
+      p.log.info(`  Clean up the worktree first:`)
+      p.log.info(`    ${green('cd')} ${dim(`worktrees/${targetBranch}`)}`)
+      p.log.info(`    ${dim('git stash')} ${dim('or')} ${dim('git commit')}`)
+      p.log.info(`    ${dim(`git checkout ${targetBranch}`)}`)
+      if (sourceStashSha) {
+        p.log.info(`\n  Your source stash is safe — apply it later with:`)
+        p.log.info(`    ${dim(`git stash apply ${sourceStashSha.slice(0, 8)}`)}`)
       }
-      p.log.info(`${dim('Existing worktrees:')}\n${lines.join('\n')}`)
+      p.outro('')
+      process.exit(1)
     }
 
-    const result = await p.text({
-      message: 'Which branch do you want to work on? Select one from above or type a new one',
-      placeholder: 'e.g. 4.3.0--my-feature',
-      validate: isValidBranchName,
-    })
+    // Clean worktree on wrong branch — switch it
+    p.log.step(`Switching worktree from ${bold(targetCurrentBranch)} to ${bold(targetBranch)}…`)
+    try {
+      execFileSync('git', ['checkout', targetBranch], { cwd: targetDir, stdio: 'pipe' })
+      p.log.success(`Now on branch ${bold(targetBranch)}`)
+    } catch (err) {
+      p.log.error(`Could not switch branch: ${err.message || 'git checkout failed'}`)
+      if (sourceStashSha) {
+        p.log.info(`  Your source stash is safe: ${dim(`git stash apply ${sourceStashSha.slice(0, 8)}`)}`)
+      }
+      p.outro('')
+      process.exit(1)
+    }
+  } else {
+    p.log.success(`Worktree ${bold(targetBranch)} is on the correct branch`)
+  }
 
-    if (p.isCancel(result)) {
-      p.cancel('Cancelled')
-      process.exit(0)
+  // 3. Apply source stash in target
+  if (sourceStashSha) {
+    if (hasUncommittedChanges(targetDir)) {
+      p.log.warning(`Target worktree has uncommitted changes — skipping stash apply`)
+      p.log.info(`  Apply your stash manually: ${dim(`git stash apply ${sourceStashSha.slice(0, 8)}`)}`)
+    } else {
+      applyStash(targetDir, sourceStashSha)
     }
-    targetBranch = result.trim()
   }
 
-  // 2. Check if worktree already exists
-  const wtDir = worktreeDir(targetBranch)
-  if (existsSync(resolve(wtDir, '.git'))) {
-    p.log.success(`Worktree ${bold(targetBranch)} already exists`)
-    p.note(
-      [
-        `  ${green('cd')} ${dim(`.worktrees/${targetBranch}`)}`,
-        `  ${green('npx storyboard dev')}  ${dim('to start developing')}`,
-      ].join('\n'),
-      'Ready to go'
-    )
-    p.outro('')
-    return
-  }
-
-  // 3. Stash uncommitted work
-  let didStash = false
-  const sourceDir = fromWorktree === 'main' ? root : worktreeDir(fromWorktree)
+  // 4. Summary
+  const lines = [
+    `  Worktree ready: ${green(`worktrees/${targetBranch}`)}`,
+  ]
+  if (sourceStashSha) {
+    lines.push(`  Your uncommitted work has been safely moved`)
+  }
+  lines.push('')
+  lines.push(`  ${green('cd')} ${dim(`worktrees/${targetBranch}`)}`)
+  lines.push(`  ${green('npx storyboard dev')}  ${dim('to start developing')}`)
+  lines.push('')
+  lines.push(`  ${dim('Tip: auto-cd with')} ${green('eval "$(npx sb branch --cd)"')}`)
 
-  if (hasUncommittedChanges(sourceDir)) {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
-    const stashName = `${fromBranch}→${targetBranch}@${timestamp}`
+  p.note(lines.join('\n'), `Branch ${bold(targetBranch)} is ready`)
+  p.outro('')
+  return targetDir
+}
 
-    p.log.step('Stashing uncommitted work…')
-    try {
-      execFileSync('git', ['stash', 'push', '-m', stashName], { cwd: sourceDir, stdio: 'pipe' })
-      didStash = true
-      p.log.success(`Work stashed: ${dim(stashName)}`)
-    } catch {
-      p.log.warning('Could not stash changes — proceeding anyway')
-    }
-  }
+/**
+ * Core logic for creating a NEW worktree.
+ *
+ * 1. Stash source changes
+ * 2. Resolve branch (local/remote/new)
+ * 3. Create worktree + npm install
+ * 4. Pull --rebase
+ * 5. Apply source stash
+ */
+function createNewWorktree(targetBranch, { sourceDir, fromBranch, root }) {
+  // 1. Stash source changes
+  const sourceStashSha = stashChanges(sourceDir, stashMessage(fromBranch, targetBranch))
 
-  // 4. Resolve branch and create worktree
+  // 2. Resolve branch
   const hasLocal = localBranchExists(targetBranch, root)
   const hasRemote = !hasLocal && remoteBranchExists(targetBranch, root)
   const isNew = !hasLocal && !hasRemote
 
   if (isNew) {
-    p.log.step(`Creating new branch ${bold(targetBranch)} from HEAD`)
+    p.log.step(`Creating new branch ${bold(targetBranch)} from ${bold(fromBranch)}`)
   } else if (hasRemote) {
-    // Fetch the remote branch so git worktree add can use it
     p.log.step(`Fetching ${bold(targetBranch)} from origin…`)
     try {
       execFileSync('git', ['fetch', 'origin', targetBranch], { cwd: root, stdio: 'pipe' })
-      // Create a local tracking branch
       try {
         execFileSync('git', ['branch', targetBranch, `origin/${targetBranch}`], { cwd: root, stdio: 'pipe' })
       } catch { /* may already exist after fetch */ }
@@ -155,18 +222,19 @@ export async function runBranchGuide(branchArg) {
     p.log.step(`Using existing branch ${bold(targetBranch)}`)
   }
 
-  // Create the worktree
-  const targetDir = resolve(root, '.worktrees', targetBranch)
+  // 3. Create the worktree
+  const targetDir = resolve(root, 'worktrees', targetBranch)
   const spin = p.spinner()
 
   try {
+    // For new branches, use current branch as start-point (not main's HEAD)
     const gitArgs = isNew
-      ? ['worktree', 'add', targetDir, '-b', targetBranch]
+      ? ['worktree', 'add', targetDir, '-b', targetBranch, fromBranch]
       : ['worktree', 'add', targetDir, targetBranch]
 
-    spin.start(`Creating worktree .worktrees/${targetBranch}`)
+    spin.start(`Creating worktree worktrees/${targetBranch}`)
     execFileSync('git', gitArgs, { cwd: root, stdio: 'pipe' })
-    spin.stop(`Worktree created: .worktrees/${targetBranch}`)
+    spin.stop(`Worktree created: worktrees/${targetBranch}`)
   } catch (err) {
     spin.stop('Failed to create worktree')
     p.log.error(err.message || 'git worktree add failed')
@@ -186,7 +254,7 @@ export async function runBranchGuide(branchArg) {
   // Assign a dev server port
   getPort(targetBranch)
 
-  // 5. Pull --rebase from origin
+  // 4. Pull --rebase from origin
   if (!isNew) {
     try {
       spin.start('Pulling latest changes…')
@@ -197,36 +265,122 @@ export async function runBranchGuide(branchArg) {
     }
   }
 
-  // 6. Apply stash (if we stashed earlier)
-  if (didStash) {
-    try {
-      // Apply (not pop) — keeps the backup in stash list
-      execFileSync('git', ['stash', 'apply'], { cwd: targetDir, stdio: 'pipe' })
-      p.log.success('Previous work applied to this branch')
-    } catch {
-      p.log.warning('Stash apply had conflicts — resolve them manually')
-      p.log.info(`  Your work is safe in ${dim('git stash list')}`)
-    }
+  // 5. Apply source stash
+  if (sourceStashSha) {
+    applyStash(targetDir, sourceStashSha)
   }
 
-  // 7. Summary
+  // 6. Summary
   const lines = [
-    `  Your branch is set up as a worktree in ${green(`.worktrees/${targetBranch}`)}`,
+    `  Your branch is set up as a worktree in ${green(`worktrees/${targetBranch}`)}`,
   ]
-  if (didStash) {
+  if (sourceStashSha) {
     lines.push(`  Your uncommitted work has been safely moved`)
   }
   lines.push('')
-  lines.push(`  ${green('cd')} ${dim(`.worktrees/${targetBranch}`)}`)
+  lines.push(`  ${green('cd')} ${dim(`worktrees/${targetBranch}`)}`)
   lines.push(`  ${green('npx storyboard dev')}  ${dim('to start developing')}`)
   lines.push('')
-  lines.push(`  ${dim('Tip: ask your AI agent about worktrees — they\'re great!')}`)
+  lines.push(`  ${dim('Tip: auto-cd with')} ${green('eval "$(npx sb branch --cd)"')}`)
 
   p.note(lines.join('\n'), `Branch ${bold(targetBranch)} is ready`)
   p.outro('')
+  return targetDir
+}
+
+// ─── Main ───
+
+export async function runBranchGuide(branchArg) {
+  const root = repoRoot()
+  const existing = listWorktrees()
+  const fromWorktree = detectWorktreeName()
+  const sourceDir = fromWorktree === 'main' ? root : worktreeDir(fromWorktree)
+  const fromBranch = currentBranch(sourceDir)
+
+  // 1. Get branch name — select from existing or type a new one
+  let targetBranch = branchArg?.trim()
+
+  if (!targetBranch) {
+    if (existing.length > 0) {
+      // Build select options from existing worktrees + "new branch" option
+      const NEW_BRANCH = Symbol('new')
+      const options = [
+        ...existing.map(name => ({ value: name, label: name })),
+        { value: NEW_BRANCH, label: dim('Create a new branch…') },
+      ]
+
+      const selected = await p.select({
+        message: 'Which branch do you want to work on?',
+        options,
+      })
+
+      if (p.isCancel(selected)) {
+        p.cancel('Cancelled')
+        process.exit(0)
+      }
+
+      if (selected === NEW_BRANCH) {
+        const newName = await p.text({
+          message: 'New branch name:',
+          placeholder: 'e.g. 4.3.0--my-feature',
+          validate: isValidBranchName,
+        })
+        if (p.isCancel(newName)) {
+          p.cancel('Cancelled')
+          process.exit(0)
+        }
+        targetBranch = newName.trim()
+      } else {
+        targetBranch = selected
+      }
+    } else {
+      // No existing worktrees — just ask for a name
+      const result = await p.text({
+        message: 'Branch name for new worktree:',
+        placeholder: 'e.g. 4.3.0--my-feature',
+        validate: isValidBranchName,
+      })
+
+      if (p.isCancel(result)) {
+        p.cancel('Cancelled')
+        process.exit(0)
+      }
+      targetBranch = result.trim()
+    }
+  }
+
+  // 2. Show equivalent non-interactive command (when user used TUI to select)
+  if (!branchArg) {
+    p.log.info(`${dim('Non-interactive:')} ${green(`npx sb branch --worktree=${targetBranch}`)}`)
+  }
+
+  // 3. Route to existing or new worktree flow
+  const wtDir = worktreeDir(targetBranch)
+  if (existsSync(resolve(wtDir, '.git'))) {
+    return switchToExistingWorktree(targetBranch, { sourceDir, fromBranch })
+  } else {
+    return createNewWorktree(targetBranch, { sourceDir, fromBranch, root })
+  }
+}
+
+// ─── Direct invocation ───
+
+const { flags, positional } = parseFlags(process.argv.slice(3), flagSchema)
+const branchArg = flags.worktree || positional[0] || undefined
+
+// When --cd is set, redirect all TUI output (Clack) to stderr so that
+// stdout contains only the shell-evaluable `cd <path>` command.
+// Usage: eval "$(npx sb branch --worktree=<name> --cd)"
+const realStdoutWrite = process.stdout.write.bind(process.stdout)
+if (flags.cd) {
+  process.stdout.write = (chunk, encoding, callback) =>
+    process.stderr.write(chunk, encoding, callback)
 }
 
-// Direct invocation
-const branchArg = process.argv[3] || undefined
 p.intro('storyboard branch')
-runBranchGuide(branchArg)
+runBranchGuide(branchArg).then((targetDir) => {
+  if (flags.cd && targetDir) {
+    process.stdout.write = realStdoutWrite
+    realStdoutWrite(`cd ${JSON.stringify(targetDir)}\n`)
+  }
+})

package/src/cli/code.js

@@ -4,7 +4,7 @@
  * Usage:
  *   storyboard code              # open current worktree or repo root
  *   storyboard code main         # open repo root
- *   storyboard code <branch>     # open .worktrees/<branch>/
+ *   storyboard code <branch>     # open worktrees/<branch>/
  */
 
 import * as p from '@clack/prompts'
@@ -33,7 +33,7 @@ if (!branch) {
   const name = detectWorktreeName()
   const dir = name === 'main' ? root : worktreeDir(name)
   if (openInCode(dir)) {
-    p.outro(`Opened ${name === 'main' ? 'repo root' : `.worktrees/${name}/`}`)
+    p.outro(`Opened ${name === 'main' ? 'repo root' : `worktrees/${name}/`}`)
   } else {
     p.log.error('Could not open VS Code. Is the `code` CLI installed?')
     p.log.info('Run `npx storyboard setup` to install it, or open VS Code and run:')
@@ -59,7 +59,7 @@ if (!branch) {
     process.exit(1)
   }
   if (openInCode(dir)) {
-    p.outro(`Opened .worktrees/${branch}/`)
+    p.outro(`Opened worktrees/${branch}/`)
   } else {
     p.log.error('Could not open VS Code.')
     process.exit(1)

package/src/cli/dev.js

@@ -60,13 +60,13 @@ function remoteBranchExists(name, cwd) {
  * @returns {string} path to the new worktree directory
  */
 function createWorktree(name, root, { newBranch = false } = {}) {
-  const targetDir = resolve(root, '.worktrees', name)
+  const targetDir = resolve(root, 'worktrees', name)
 
   const gitArgs = newBranch
     ? ['worktree', 'add', targetDir, '-b', name]
     : ['worktree', 'add', targetDir, name]
 
-  p.log.step(`Creating worktree: .worktrees/${name}`)
+  p.log.step(`Creating worktree: worktrees/${name}`)
   execFileSync('git', gitArgs, { cwd: root, stdio: 'inherit' })
 
   p.log.step('Installing dependencies…')
@@ -112,7 +112,7 @@ async function resolveDevTarget(branchArg, { allowCreate = true } = {}) {
     // No worktree exists — prompt the user to convert
     p.log.warning(`Root is on branch "${branch}" instead of main.`)
     const shouldConvert = await p.confirm({
-      message: `Convert "${branch}" to a worktree? (moves branch to .worktrees/${branch}/)`,
+      message: `Convert "${branch}" to a worktree? (moves branch to worktrees/${branch}/)`,
       initialValue: true,
     })
 
@@ -403,9 +403,9 @@ async function main() {
   const { worktreeName, targetCwd, created } = await resolveDevTarget(branchArg, { allowCreate })
 
   if (created) {
-    p.log.success(`Worktree ready: .worktrees/${worktreeName}`)
+    p.log.success(`Worktree ready: worktrees/${worktreeName}`)
   } else if (branchArg) {
-    p.log.info(`Using ${worktreeName === 'main' ? 'main repo' : `.worktrees/${worktreeName}`}`)
+    p.log.info(`Using ${worktreeName === 'main' ? 'main repo' : `worktrees/${worktreeName}`}`)
   }
 
   const domain = readDevDomain(targetCwd)

package/src/cli/index.js

@@ -93,8 +93,11 @@ function helpScreen(version) {
     '',
     `  ${bold(cyan('Setup'))}`,
     cmd('setup', 'Install deps, Caddy proxy, start proxy'),
+    cmd('setup --skip-branch', 'Non-interactive setup (skip branch prompt)'),
+    cmd('setup --branch=<name>', 'Setup + switch to a branch'),
     cmd('branch', 'Switch to a branch (interactive worktree guide)'),
     cmd('branch <name>', 'Switch to a specific branch directly'),
+    cmd('branch --worktree=<name>', 'Non-interactive branch switch'),
     cmd('proxy start', 'Start or reload Caddy proxy'),
     cmd('proxy close', 'Stop Caddy proxy'),
     '',

package/src/cli/setup.js

@@ -2,6 +2,11 @@
  * storyboard setup — One-time setup for the Storyboard dev environment.
  *
  * Idempotent: safe to run multiple times, only does what's needed.
+ *
+ * Usage:
+ *   npx storyboard setup                          # interactive
+ *   npx storyboard setup --skip-branch             # non-interactive, skip branch prompt
+ *   npx storyboard setup --branch=<name>           # non-interactive, switch to branch after setup
  */
 
 import * as p from '@clack/prompts'
@@ -9,7 +14,15 @@ import { existsSync, writeFileSync, readFileSync, mkdirSync, readdirSync, symlin
 import path from 'path'
 import { execSync } from 'child_process'
 import { generateCaddyfile, isCaddyInstalled, isCaddyRunning, startCaddy, reloadCaddy } from './proxy.js'
-import { gettingStartedLines, dim, magenta, bold, yellow } from './intro.js'
+import { gettingStartedLines, dim, magenta, bold, yellow, green } from './intro.js'
+import { parseFlags } from './flags.js'
+
+const flagSchema = {
+  'skip-branch': { type: 'boolean', default: false, description: 'Skip the branch prompt at the end' },
+  branch: { type: 'string', description: 'Switch to a branch after setup (non-interactive)' },
+}
+
+const { flags } = parseFlags(process.argv.slice(3), flagSchema)
 
 /**
  * Run a potentially slow task with a spinner that only appears after 500ms.
@@ -330,11 +343,16 @@ if (isCaddyInstalled()) {
     p.log.info(dim('Skipping npm install — dev server is running (would cause restart)'))
     p.log.info(dim('Run `npm install` manually after stopping the dev server if needed'))
   } else {
-    await withSpin(
-      'Installing dependencies...',
-      'Dependencies installed',
-      () => { run('npm install', { stdio: 'ignore' }) }
-    )
+    try {
+      await withSpin(
+        'Installing dependencies...',
+        'Dependencies installed',
+        () => { run('npm install', { stdio: 'ignore' }) }
+      )
+    } catch {
+      p.log.warning('npm install failed — run it manually to see details')
+      p.log.info(`  ${dim('npm install')}`)
+    }
   }
 }
 
@@ -349,26 +367,38 @@ p.note(
 
 // Offer branch guide
 {
-  let currentBranchName = 'main'
-  try {
-    currentBranchName = execSync('git branch --show-current', { encoding: 'utf8' }).trim() || 'main'
-  } catch { /* empty */ }
-
-  const wantBranch = await p.select({
-    message: 'Want to work from a different branch?',
-    options: [
-      { value: true, label: 'Yes (help me create it)' },
-      { value: false, label: `No (stay on current branch ${bold(currentBranchName)})` },
-    ],
-    initialValue: false,
-  })
-
-  if (!p.isCancel(wantBranch) && wantBranch) {
+  // Non-interactive: --branch=<name> or --skip-branch
+  if (flags.branch) {
     const { runBranchGuide } = await import('./branch.js')
-    await runBranchGuide()
-  } else {
+    await runBranchGuide(flags.branch)
+  } else if (flags['skip-branch']) {
     console.log()
     console.log(mascot())
     p.outro('')
+  } else {
+    // Interactive: ask the user
+    let currentBranchName = 'main'
+    try {
+      currentBranchName = execSync('git branch --show-current', { encoding: 'utf8' }).trim() || 'main'
+    } catch { /* empty */ }
+
+    const wantBranch = await p.select({
+      message: 'Want to work from a different branch?',
+      options: [
+        { value: true, label: 'Yes (help me create it)' },
+        { value: false, label: `No (stay on current branch ${bold(currentBranchName)})` },
+      ],
+      initialValue: false,
+    })
+
+    if (!p.isCancel(wantBranch) && wantBranch) {
+      const { runBranchGuide } = await import('./branch.js')
+      await runBranchGuide()
+    } else {
+      console.log()
+      console.log(mascot())
+      p.log.info(`${dim('Non-interactive:')} ${green('npx sb setup --skip-branch')}`)
+      p.outro('')
+    }
   }
 }

package/src/server/index.js

@@ -89,7 +89,7 @@ async function parseBody(req) {
 function resolveWorktreeCwd(branch) {
   const root = repoRoot()
   if (branch === 'main') return root
-  const wtDir = join(root, '.worktrees', branch)
+  const wtDir = join(root, 'worktrees', branch)
   if (existsSync(wtDir)) return wtDir
   return null
 }

package/src/worktree/port.js

@@ -1,7 +1,7 @@
 /**
  * Worktree Port Registry
  *
- * Manages a JSON registry (.worktrees/ports.json) that maps worktree names
+ * Manages a JSON registry (worktrees/ports.json) that maps worktree names
  * to unique dev-server ports. Main always gets 1234; worktrees get 1235+.
  *
  * This module is published as part of @dfosco/storyboard-core so client
@@ -19,10 +19,10 @@ import { findByWorktree } from './serverRegistry.js'
 const BASE_PORT = 1234
 
 /**
- * Resolve the path to .worktrees/ports.json.
+ * Resolve the path to worktrees/ports.json.
  *
  * Derives the repo root from directory structure so it works whether
- * running from the repo root or from inside .worktrees/<name>/ — even
+ * running from the repo root or from inside worktrees/<name>/ — even
  * when ports.json does not exist yet.
  *
  * @param {string} [cwd] — override working directory
@@ -31,34 +31,34 @@ const BASE_PORT = 1234
 export function portsFilePath(cwd = process.cwd()) {
   const realCwd = realpathSync(cwd)
 
-  // Check if we're inside .worktrees/<name>/
-  const worktreeMatch = realCwd.match(/^(.+)[/\\]\.worktrees[/\\][^/\\]+/)
+  // Check if we're inside worktrees/<name>/
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]worktrees[/\\][^/\\]+/)
   if (worktreeMatch) {
-    return join(worktreeMatch[1], '.worktrees', 'ports.json')
+    return join(worktreeMatch[1], 'worktrees', 'ports.json')
   }
 
   // We're at the repo root (or somewhere else) — default location
-  return join(realCwd, '.worktrees', 'ports.json')
+  return join(realCwd, 'worktrees', 'ports.json')
 }
 
 /**
  * Detect the worktree name from the current git context.
  *
- * Returns 'main' when not inside a .worktrees/<name>/ directory.
+ * Returns 'main' when not inside a worktrees/<name>/ directory.
  */
 export function detectWorktreeName() {
   try {
     const topLevel = execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim()
     const realTop = realpathSync(topLevel)
 
-    // Check if we're inside a .worktrees/<name> directory
-    if (realTop.includes('.worktrees/') || realTop.includes('.worktrees\\')) {
+    // Check if we're inside a worktrees/<name> directory
+    if (realTop.includes('worktrees/') || realTop.includes('worktrees\\')) {
       return basename(realTop)
     }
 
     // Also check the cwd pattern
     const realCwd = realpathSync(process.cwd())
-    const worktreeMatch = realCwd.match(/\.worktrees[/\\]([^/\\]+)/)
+    const worktreeMatch = realCwd.match(/worktrees[/\\]([^/\\]+)/)
     if (worktreeMatch) return worktreeMatch[1]
 
     // Not a worktree — check the current branch name
@@ -90,7 +90,7 @@ function isPortInUse(port) {
 /**
  * Get or assign a port for the given worktree name.
  *
- * Creates .worktrees/ports.json if it doesn't exist. Assigns ports
+ * Creates worktrees/ports.json if it doesn't exist. Assigns ports
  * starting at BASE_PORT+1 (1235) for non-main worktrees.
  * If the previously assigned port was stolen by another process,
  * reassigns to the next available port.
@@ -179,7 +179,7 @@ export function resolveRunningPort(worktreeName) {
 }
 
 /**
- * Resolve the port for a worktree from .worktrees/ports.json
+ * Resolve the port for a worktree from worktrees/ports.json
  * without assigning a new one if missing.
  *
  * @param {string} worktreeName
@@ -216,9 +216,9 @@ export function slugify(name) {
 }
 
 /**
- * Resolve the repo root — the directory that contains `.worktrees/`.
+ * Resolve the repo root — the directory that contains `worktrees/`.
  *
- * Works whether cwd is the repo root itself or inside `.worktrees/<name>/`.
+ * Works whether cwd is the repo root itself or inside `worktrees/<name>/`.
  *
  * @param {string} [cwd]
  * @returns {string} absolute path to repo root
@@ -226,7 +226,7 @@ export function slugify(name) {
 export function repoRoot(cwd = process.cwd()) {
   const realCwd = realpathSync(cwd)
 
-  const worktreeMatch = realCwd.match(/^(.+)[/\\]\.worktrees[/\\][^/\\]+/)
+  const worktreeMatch = realCwd.match(/^(.+)[/\\]worktrees[/\\][^/\\]+/)
   if (worktreeMatch) return worktreeMatch[1]
 
   return realCwd
@@ -235,7 +235,7 @@ export function repoRoot(cwd = process.cwd()) {
 /**
  * Resolve the full path to a worktree directory.
  *
- * Returns repo root for 'main', `.worktrees/<name>` otherwise.
+ * Returns repo root for 'main', `worktrees/<name>` otherwise.
  *
  * @param {string} name — worktree name
  * @param {string} [cwd]
@@ -244,11 +244,11 @@ export function repoRoot(cwd = process.cwd()) {
 export function worktreeDir(name, cwd) {
   const root = repoRoot(cwd)
   if (name === 'main') return root
-  return join(root, '.worktrees', name)
+  return join(root, 'worktrees', name)
 }
 
 /**
- * List existing worktree directory names from `.worktrees/`.
+ * List existing worktree directory names from `worktrees/`.
  *
  * Only returns directories that look like real worktrees (contain a `.git` file).
  * Does not include 'main'.
@@ -258,7 +258,7 @@ export function worktreeDir(name, cwd) {
  */
 export function listWorktrees(cwd) {
   const root = repoRoot(cwd)
-  const worktreesDir = join(root, '.worktrees')
+  const worktreesDir = join(root, 'worktrees')
 
   if (!existsSync(worktreesDir)) return []
 

package/src/worktree/port.test.js

@@ -43,27 +43,27 @@ describe('portsFilePath', () => {
     rmSync(tempRoot, { recursive: true, force: true })
   })
 
-  it('returns root .worktrees/ports.json from repo root', () => {
+  it('returns root worktrees/ports.json from repo root', () => {
     const result = portsFilePath(tempRoot)
-    expect(result).toBe(join(tempRoot, '.worktrees', 'ports.json'))
+    expect(result).toBe(join(tempRoot, 'worktrees', 'ports.json'))
   })
 
   it('returns shared ports.json from inside a worktree dir', () => {
-    // Simulate .worktrees/my-branch/
-    const worktreeDir = join(tempRoot, '.worktrees', 'my-branch')
+    // Simulate worktrees/my-branch/
+    const worktreeDir = join(tempRoot, 'worktrees', 'my-branch')
     mkdirSync(worktreeDir, { recursive: true })
     const result = portsFilePath(worktreeDir)
-    expect(result).toBe(join(tempRoot, '.worktrees', 'ports.json'))
+    expect(result).toBe(join(tempRoot, 'worktrees', 'ports.json'))
   })
 
   it('returns shared ports.json from worktree even when ports.json does not exist', () => {
     // This is the key bug fix — first run from a worktree with no ports.json
-    const worktreeDir = join(tempRoot, '.worktrees', 'first-run')
+    const worktreeDir = join(tempRoot, 'worktrees', 'first-run')
     mkdirSync(worktreeDir, { recursive: true })
     const result = portsFilePath(worktreeDir)
-    // Must point to root, NOT to .worktrees/first-run/.worktrees/ports.json
-    expect(result).toBe(join(tempRoot, '.worktrees', 'ports.json'))
-    expect(result).not.toContain('first-run/.worktrees')
+    // Must point to root, NOT to worktrees/first-run/worktrees/ports.json
+    expect(result).toBe(join(tempRoot, 'worktrees', 'ports.json'))
+    expect(result).not.toContain('first-run/worktrees')
   })
 })
 
@@ -73,7 +73,7 @@ describe('getPort / resolvePort', () => {
 
   beforeEach(() => {
     tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-port-test-')))
-    mkdirSync(join(tempRoot, '.worktrees'), { recursive: true })
+    mkdirSync(join(tempRoot, 'worktrees'), { recursive: true })
     originalCwd = process.cwd()
     process.chdir(tempRoot)
   })
@@ -106,7 +106,7 @@ describe('getPort / resolvePort', () => {
 
   it('persists to ports.json', () => {
     getPort('persisted')
-    const portsFile = join(tempRoot, '.worktrees', 'ports.json')
+    const portsFile = join(tempRoot, 'worktrees', 'ports.json')
     expect(existsSync(portsFile)).toBe(true)
     const data = JSON.parse(readFileSync(portsFile, 'utf8'))
     expect(data.persisted).toBe(1235)
@@ -123,7 +123,7 @@ describe('getPort / resolvePort', () => {
   })
 
   it('handles corrupted ports.json gracefully', () => {
-    const portsFile = join(tempRoot, '.worktrees', 'ports.json')
+    const portsFile = join(tempRoot, 'worktrees', 'ports.json')
     writeFileSync(portsFile, 'not valid json')
     // Should not throw — starts fresh
     const port = getPort('recovery')
@@ -136,7 +136,7 @@ describe('repoRoot', () => {
 
   beforeEach(() => {
     tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-root-test-')))
-    mkdirSync(join(tempRoot, '.worktrees', 'my-branch'), { recursive: true })
+    mkdirSync(join(tempRoot, 'worktrees', 'my-branch'), { recursive: true })
   })
 
   afterEach(() => {
@@ -147,8 +147,8 @@ describe('repoRoot', () => {
     expect(repoRoot(tempRoot)).toBe(tempRoot)
   })
 
-  it('returns parent of .worktrees when inside a worktree', () => {
-    const wt = join(tempRoot, '.worktrees', 'my-branch')
+  it('returns parent of worktrees when inside a worktree', () => {
+    const wt = join(tempRoot, 'worktrees', 'my-branch')
     expect(repoRoot(wt)).toBe(tempRoot)
   })
 })
@@ -158,7 +158,7 @@ describe('worktreeDir', () => {
 
   beforeEach(() => {
     tempRoot = realpathSync(mkdtempSync(join(tmpdir(), 'sb-wtdir-test-')))
-    mkdirSync(join(tempRoot, '.worktrees'), { recursive: true })
+    mkdirSync(join(tempRoot, 'worktrees'), { recursive: true })
   })
 
   afterEach(() => {
@@ -169,8 +169,8 @@ describe('worktreeDir', () => {
     expect(worktreeDir('main', tempRoot)).toBe(tempRoot)
   })
 
-  it('returns .worktrees/<name> for branches', () => {
-    expect(worktreeDir('my-feature', tempRoot)).toBe(join(tempRoot, '.worktrees', 'my-feature'))
+  it('returns worktrees/<name> for branches', () => {
+    expect(worktreeDir('my-feature', tempRoot)).toBe(join(tempRoot, 'worktrees', 'my-feature'))
   })
 })
 
@@ -185,12 +185,12 @@ describe('listWorktrees', () => {
     rmSync(tempRoot, { recursive: true, force: true })
   })
 
-  it('returns empty array when .worktrees does not exist', () => {
+  it('returns empty array when worktrees does not exist', () => {
     expect(listWorktrees(tempRoot)).toEqual([])
   })
 
   it('returns only directories with a .git file', () => {
-    const wtDir = join(tempRoot, '.worktrees')
+    const wtDir = join(tempRoot, 'worktrees')
     mkdirSync(wtDir)
 
     // Valid worktree — has .git file
@@ -208,7 +208,7 @@ describe('listWorktrees', () => {
   })
 
   it('returns multiple worktrees', () => {
-    const wtDir = join(tempRoot, '.worktrees')
+    const wtDir = join(tempRoot, 'worktrees')
     mkdirSync(wtDir)
 
     for (const name of ['alpha', 'beta', 'gamma']) {