@dfosco/storyboard 0.7.1 → 0.9.0

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,15 @@ 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).
 
+<!-- cli-table --start-->
 | 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) |
@@ -152,6 +153,7 @@ The `storyboard` CLI (`sb` alias) wraps dev tooling:
 | `storyboard messages send` | Publish and wait for correlated response |
 | `storyboard messages read` | Read events from a channel |
 | `storyboard messages batch` | Batch publish + read operations |
+<!-- cli-table --end-->
 
 > **Convention: Every server API endpoint must have a corresponding CLI command with 1:1 flag-to-field mapping.** Agents use CLI commands, not curl. When adding a new API endpoint, always create a matching CLI command.
 
@@ -159,7 +161,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 +171,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 +182,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/README.md

@@ -0,0 +1,18 @@
+# Storyboard
+
+> Note: this is a scaffold-source README. The file copied to client repos
+> only contains the fragment bodies — the bare `<!-- … --start-->` markers
+> below are stripped on whole-file copy. Clients can also adopt individual
+> fragments by adding `<!-- storyboard:scaffold/README.md:<id> --start-->`
+> markers around their own content.
+
+## Storyboard Launcher (Desktop App)
+
+<!-- launcher-download --start-->
+Download the macOS Launcher from the [latest launcher release](https://github.com/dfosco/storyboard/releases?q=storyboard-launcher&expanded=true).
+
+After installing, run:
+```bash
+sudo xattr -rd com.apple.quarantine '/Applications/Storyboard Launcher.app'
+```
+<!-- launcher-download --end-->

package/scaffold/deploy.yml

@@ -101,3 +101,24 @@ jobs:
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git commit -m "Update branch manifest"
           git push origin gh-pages
+
+      - name: Generate artifacts index
+        run: |
+          set -e
+          # Remove stale worktrees from previous steps
+          git worktree list --porcelain | awk '/^worktree \/tmp/{print $2}' | while read wt; do
+            git worktree remove --force "$wt" 2>/dev/null || true
+          done
+          git fetch origin gh-pages:gh-pages 2>/dev/null || true
+          DEPLOY_DIR=$(mktemp -d)
+          git worktree add "$DEPLOY_DIR" gh-pages
+
+          node "$GITHUB_WORKSPACE/.github/workflows/scripts/aggregate-artifacts.mjs" "$DEPLOY_DIR"
+
+          cd "$DEPLOY_DIR"
+          git add artifacts.index.json
+          git diff --cached --quiet && echo "Artifacts index unchanged" && exit 0
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "Update artifacts index"
+          git push origin gh-pages

package/scaffold/gitignore

@@ -52,25 +52,19 @@ packages/core/dist/storyboard-ui.*
 # Agent Browser
 agent-browser.json
 
-# Auto-generated scaffold dir (copies of library config defaults — overwritten on every dev-server boot)
-.storyboard/scaffold/
-
-# Real-time canvas selection bridge for Copilot
-.storyboard/.selectedwidgets.json
-
-# Runtime/transient state (per-machine, per-session)
-.storyboard/agent-sessions/
-.storyboard/hot-pool/
-.storyboard/logs/
-.storyboard/terminal-buffers/
-.storyboard/messages/
-
-# Private canvas images (tilde prefix = not committed)
+# <!-- runtime-state --start-->
+# Storyboard runtime state + private tilde-prefixed files.
+# Kept in sync by storyboard-scaffold — edit `packages/storyboard/scaffold/gitignore` in storyboard-core.
+.storyboard/
 src/canvas/images/~*
 assets/canvas/images/~*
+assets/canvas/images/drafts/
 assets/canvas/snapshots/~*
 assets/.storyboard-public/terminal-snapshots/~*
+src/canvas/**/drafts/
+src/prototypes/**/drafts/
 .sync-target
+# <!-- runtime-state --end-->
 
 # Integration test results (ephemeral local artifacts)
 test-results/

package/scaffold/preview.yml

@@ -115,6 +115,27 @@ jobs:
           git commit -m "Update branch manifest"
           git push origin gh-pages
 
+      - name: Generate artifacts index
+        run: |
+          set -e
+          # Remove stale worktrees from previous steps
+          git worktree list --porcelain | awk '/^worktree \/tmp/{print $2}' | while read wt; do
+            git worktree remove --force "$wt" 2>/dev/null || true
+          done
+          git fetch origin gh-pages:gh-pages 2>/dev/null || true
+          DEPLOY_DIR=$(mktemp -d)
+          git worktree add "$DEPLOY_DIR" gh-pages
+
+          node "$GITHUB_WORKSPACE/.github/workflows/scripts/aggregate-artifacts.mjs" "$DEPLOY_DIR"
+
+          cd "$DEPLOY_DIR"
+          git add artifacts.index.json
+          git diff --cached --quiet && echo "Artifacts index unchanged" && exit 0
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "Update artifacts index"
+          git push origin gh-pages
+
       - name: Print preview URL
         run: |
           echo "## 🔗 Branch Preview" >> "$GITHUB_STEP_SUMMARY"
@@ -179,3 +200,22 @@ jobs:
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git commit -m "Update branch manifest"
           git push origin gh-pages
+
+      # cleanup-preview does not install npm dependencies. Check out the source
+      # tree separately so the checked-in workflow helper can run with plain Node.
+      - name: Checkout source workflow scripts
+        uses: actions/checkout@v6
+        with:
+          path: source
+
+      - name: Generate artifacts index
+        run: |
+          set -e
+          node source/.github/workflows/scripts/aggregate-artifacts.mjs "$GITHUB_WORKSPACE"
+
+          git add artifacts.index.json
+          git diff --cached --quiet && echo "Artifacts index unchanged" && exit 0
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -m "Update artifacts index"
+          git push origin gh-pages

package/scaffold/{manifest.json → scaffold.config.json}

@@ -3,15 +3,15 @@
     {
       "source": "scaffold/AGENTS.md",
       "target": "AGENTS.md",
-      "mode": "updateable"
+      "mode": "scaffold"
     },
     {
       "source": "scaffold/gitignore",
       "target": ".gitignore",
-      "mode": "updateable"
+      "mode": "scaffold"
     },
     {
-      "source": "scaffold/storyboard.config.json",
+      "source": "storyboard.config.json",
       "target": "storyboard.config.json",
       "mode": "scaffold"
     },
@@ -67,6 +67,11 @@
       "target": ".github/workflows/preview.yml",
       "mode": "updateable"
     },
+    {
+      "source": "scaffold/scripts/aggregate-artifacts.mjs",
+      "target": ".github/workflows/scripts/aggregate-artifacts.mjs",
+      "mode": "updateable"
+    },
     {
       "source": "scaffold/githooks/",
       "target": ".githooks/",
@@ -88,6 +93,71 @@
       "source": "scaffold/codex/config.toml",
       "target": ".codex/config.toml",
       "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/mount.jsx",
+      "target": "src/library/mount.jsx",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/prototypes-entry.jsx",
+      "target": "src/library/prototypes-entry.jsx",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/routes.jsx",
+      "target": "src/library/routes.jsx",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/_app.jsx",
+      "target": "src/library/_app.jsx",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/_app.module.css",
+      "target": "src/library/_app.module.css",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/workspace.jsx",
+      "target": "src/library/workspace.jsx",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/viewfinder.jsx",
+      "target": "src/library/viewfinder.jsx",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/create.jsx",
+      "target": "src/library/create.jsx",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/index.jsx",
+      "target": "src/library/index.jsx",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/library/README.md",
+      "target": "src/library/README.md",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/src/_prototype.jsx",
+      "target": "src/_prototype.jsx",
+      "mode": "scaffold"
+    },
+    {
+      "source": "scaffold/src/_story.jsx",
+      "target": "src/_story.jsx",
+      "mode": "scaffold"
     }
+  ],
+  "fragmentSources": [
+    "scaffold/gitignore",
+    "scaffold/AGENTS.md",
+    "scaffold/README.md"
   ]
 }

package/scaffold/scripts/aggregate-artifacts.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+import fs from 'fs'
+import path from 'path'
+import process from 'process'
+
+const INDEX_FILENAME = 'artifacts.index.json'
+const TMP_FILENAME = '.artifacts.index.json.tmp'
+const SCHEMA_VERSION = 1
+
+function compareBranchNames(a, b) {
+  if (a.branch === 'main' && b.branch !== 'main') return -1
+  if (b.branch === 'main' && a.branch !== 'main') return 1
+  return String(a.branch || '').localeCompare(String(b.branch || ''))
+}
+
+function withTrailingSlash(folder) {
+  if (!folder) return ''
+  return folder.endsWith('/') ? folder : `${folder}/`
+}
+
+function generatedAtMs(manifest) {
+  const value = Date.parse(manifest?.generatedAt || '')
+  return Number.isNaN(value) ? 0 : value
+}
+
+function deriveFolder(manifest, dir, ghPagesDir) {
+  if (dir === ghPagesDir) return ''
+  if (typeof manifest.folder === 'string') return manifest.folder
+  return path.basename(dir)
+}
+
+function deriveBranch(manifest, folder) {
+  if (!folder) return 'main'
+  if (typeof manifest.branch === 'string' && manifest.branch) return manifest.branch
+  return manifest.deployBranch || folder.replace(/^branch--/, '')
+}
+
+function deriveDeployBranch(manifest, branch, folder) {
+  if (!folder || branch === 'main') return 'main'
+  if (typeof manifest.deployBranch === 'string' && manifest.deployBranch) return manifest.deployBranch
+  return folder.replace(/^branch--/, '')
+}
+
+function readManifest(dir) {
+  const manifestPath = path.join(dir, 'artifacts.json')
+  const label = path.basename(dir) || dir
+
+  let raw
+  try {
+    raw = fs.readFileSync(manifestPath, 'utf8')
+  } catch (err) {
+    if (err?.code === 'ENOENT') {
+      console.info(`[aggregate-artifacts] Skipping ${label}: artifacts.json not found`)
+      return { manifest: null, readError: false }
+    }
+    console.warn(`[aggregate-artifacts] Skipping ${label}: could not read artifacts.json (${err.message})`)
+    return { manifest: null, readError: true }
+  }
+
+  let manifest
+  try {
+    manifest = JSON.parse(raw)
+  } catch (err) {
+    console.warn(`[aggregate-artifacts] Skipping ${label}: malformed artifacts.json (${err.message})`)
+    return { manifest: null, readError: false }
+  }
+
+  if (manifest?.schemaVersion !== SCHEMA_VERSION) {
+    console.warn(`[aggregate-artifacts] Skipping ${label}: unsupported schemaVersion ${manifest?.schemaVersion}`)
+    return { manifest: null, readError: false }
+  }
+
+  return { manifest, readError: false }
+}
+
+function listManifestDirs(ghPagesDir) {
+  const entries = fs.readdirSync(ghPagesDir, { withFileTypes: true })
+  const branchDirs = entries
+    .filter(entry => entry.isDirectory() && entry.name.startsWith('branch--'))
+    .map(entry => path.join(ghPagesDir, entry.name))
+    .sort((a, b) => path.basename(a).localeCompare(path.basename(b)))
+
+  return [ghPagesDir, ...branchDirs]
+}
+
+function collectManifests(ghPagesDir) {
+  const manifestsByFolder = new Map()
+  let readErrorCount = 0
+
+  for (const dir of listManifestDirs(ghPagesDir)) {
+    const { manifest, readError } = readManifest(dir)
+    if (readError) readErrorCount += 1
+    if (!manifest) continue
+
+    const folder = deriveFolder(manifest, dir, ghPagesDir)
+    const current = { manifest, dir, folder }
+    const previous = manifestsByFolder.get(folder)
+
+    if (!previous) {
+      manifestsByFolder.set(folder, current)
+      continue
+    }
+
+    const previousBranch = deriveBranch(previous.manifest, previous.folder)
+    const currentBranch = deriveBranch(manifest, folder)
+    const keepCurrent = generatedAtMs(manifest) > generatedAtMs(previous.manifest)
+    const keptBranch = keepCurrent ? currentBranch : previousBranch
+
+    console.warn(
+      `[aggregate-artifacts] Branch folder collision for "${folder || '(root)'}" between "${previousBranch}" and "${currentBranch}"; keeping "${keptBranch}"`,
+    )
+
+    if (keepCurrent) manifestsByFolder.set(folder, current)
+  }
+
+  if (readErrorCount > 1) {
+    throw new Error(`Failed to read ${readErrorCount} artifacts manifests; preserving existing ${INDEX_FILENAME}`)
+  }
+
+  const manifests = [...manifestsByFolder.values()]
+  if (manifests.length === 0) {
+    throw new Error(`No readable artifacts.json manifests found; preserving existing ${INDEX_FILENAME}`)
+  }
+
+  return manifests
+}
+
+function addPrototype(index, manifestInfo, item) {
+  const id = item?.artifactId || item?.id
+  if (!id) return
+
+  const { manifest, folder } = manifestInfo
+  const branch = deriveBranch(manifest, folder)
+  const key = String(id)
+
+  if (!index.prototypes[key]) {
+    index.prototypes[key] = { id: key, branches: [] }
+  }
+
+  index.prototypes[key].branches.push({
+    branch,
+    folder: withTrailingSlash(folder),
+    title: item.title ?? item.id ?? key,
+    route: item.route ?? null,
+    isExternal: Boolean(item.isExternal),
+    externalUrl: item.externalUrl ?? null,
+    folderName: item.folder ?? null,
+    sha: manifest.sha ?? null,
+    lastModified: item.lastModified ?? null,
+  })
+}
+
+function addCanvas(index, manifestInfo, item) {
+  const id = item?.artifactId || item?.id
+  if (!id) return
+
+  const { manifest, folder } = manifestInfo
+  const branch = deriveBranch(manifest, folder)
+  const key = String(id)
+
+  if (!index.canvases[key]) {
+    index.canvases[key] = { id: key, branches: [] }
+  }
+
+  index.canvases[key].branches.push({
+    branch,
+    folder: withTrailingSlash(folder),
+    name: item.name ?? item.id ?? key,
+    route: item.route ?? null,
+    folderName: item.folder ?? null,
+    sha: manifest.sha ?? null,
+    lastModified: item.lastModified ?? null,
+  })
+}
+
+function sortArtifactMap(map) {
+  const sorted = {}
+
+  for (const key of Object.keys(map).sort((a, b) => a.localeCompare(b))) {
+    sorted[key] = {
+      ...map[key],
+      branches: [...map[key].branches].sort(compareBranchNames),
+    }
+  }
+
+  return sorted
+}
+
+function buildIndex(manifests) {
+  const index = {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    branches: [],
+    prototypes: {},
+    canvases: {},
+  }
+
+  for (const manifestInfo of manifests) {
+    const { manifest, folder } = manifestInfo
+    const branch = deriveBranch(manifest, folder)
+    const deployBranch = deriveDeployBranch(manifest, branch, folder)
+
+    index.branches.push({ branch, deployBranch, folder })
+
+    for (const item of Array.isArray(manifest.prototypes) ? manifest.prototypes : []) {
+      addPrototype(index, manifestInfo, item)
+    }
+
+    for (const item of Array.isArray(manifest.canvases) ? manifest.canvases : []) {
+      addCanvas(index, manifestInfo, item)
+    }
+  }
+
+  index.branches = [...index.branches].sort(compareBranchNames)
+  index.prototypes = sortArtifactMap(index.prototypes)
+  index.canvases = sortArtifactMap(index.canvases)
+
+  return index
+}
+
+function writeIndex(ghPagesDir, index) {
+  const targetPath = path.join(ghPagesDir, INDEX_FILENAME)
+  const tmpPath = path.join(ghPagesDir, TMP_FILENAME)
+  const contents = `${JSON.stringify(index, null, 2)}\n`
+
+  fs.writeFileSync(tmpPath, contents, 'utf8')
+  fs.renameSync(tmpPath, targetPath)
+
+  return targetPath
+}
+
+function aggregateArtifacts(ghPagesDir) {
+  const resolvedDir = path.resolve(ghPagesDir)
+  const manifests = collectManifests(resolvedDir)
+  const index = buildIndex(manifests)
+  return writeIndex(resolvedDir, index)
+}
+
+function main() {
+  const ghPagesDir = process.argv[2]
+
+  if (!ghPagesDir) {
+    console.error('Usage: node aggregate-artifacts.mjs <gh-pages-dir>')
+    process.exit(1)
+  }
+
+  try {
+    const targetPath = aggregateArtifacts(ghPagesDir)
+    console.info(`[aggregate-artifacts] Wrote ${targetPath}`)
+  } catch (err) {
+    console.error(`[aggregate-artifacts] ${err.message}`)
+    process.exit(1)
+  }
+}
+
+main()

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/scaffold/src/_prototype.jsx

@@ -0,0 +1,17 @@
+/**
+ * _prototype.jsx — wraps every prototype route in this project.
+ *
+ * Storyboard resolves this file via `import.meta.glob('/src/_prototype.{jsx,tsx}')`
+ * and wraps every prototype route's render with the default export — both in
+ * the workspace SPA and in the isolated `prototypes.html` iframe.
+ *
+ * By default, this is a pass-through (no providers, no CSS). Customize freely:
+ * - Add an `import './_prototype.css'` and import your design tokens / Tailwind / fonts
+ * - Wrap in your design system's ThemeProvider (Primer, Reshaped, Chakra, etc.)
+ *
+ * Delete this file entirely if you want prototypes to render with absolutely
+ * nothing inherited from storyboard.
+ */
+export default function PrototypeWrapper({ children }) {
+  return children
+}

package/scaffold/src/_story.jsx

@@ -0,0 +1,13 @@
+/**
+ * _story.jsx — wraps every story render in this project.
+ *
+ * Covers: StoryPage routes, ComponentSetPage grid, InlineStoryRenderer
+ * (canvas widget), componentIsolate / componentSetIsolate (iframe entries).
+ *
+ * Pass-through default — customize like `src/_prototype.jsx` (often the two
+ * share the same providers; one common pattern is to re-export this file
+ * from `_prototype.jsx`).
+ */
+export default function StoryWrapper({ children }) {
+  return children
+}

package/scaffold/src/library/README.md

@@ -0,0 +1,34 @@
+# DO NOT EDIT FILES IN THIS DIRECTORY
+
+`src/library/` contains storyboard's bootstrap boilerplate AND its workspace
+pages (Workspace, Viewfinder, Create, the SPA landing index). These files
+are managed by storyboard and may be overwritten by future
+`storyboard update:version` runs.
+
+The contents:
+
+| File | What it does |
+|---|---|
+| `mount.jsx` | Vite SPA entry — `index.html` loads this |
+| `prototypes-entry.jsx` | Vite iframe entry — `prototypes.html` loads this |
+| `routes.jsx` | Generouted glue: scans `src/library/*.jsx` (workspace pages) and `src/prototypes/**` (your prototypes) |
+| `_app.jsx`, `_app.module.css` | Workspace SPA shell — `StoryboardProvider`, suspense, error boundary, feature-flag banner |
+| `workspace.jsx` | `/workspace` route — calls `<Workspace>` |
+| `viewfinder.jsx` | `/viewfinder` redirect (kept for back-compat) |
+| `create.jsx` | `/create` standalone artifact creator |
+| `index.jsx` | `/` landing — `<SimpleWorkspace>` |
+
+## How to customize storyboard
+
+Almost every customization knob lives elsewhere:
+
+| What you want to change | Edit |
+|---|---|
+| App title, theming, feature flags, surfaces | `storyboard.config.json` |
+| Provider chain for every **prototype** (design system, fonts, Tailwind) | `src/_prototype.jsx` (optional — create it if you want it) |
+| Provider chain for every **story** | `src/_story.jsx` (optional) |
+| Add new routes the user can navigate to inside the SPA | Add files under `src/prototypes/` |
+
+If you have a real reason to edit a file in this directory, just edit it —
+storyboard will warn (but not block) on the next sync. You opt out of sync
+by adding the file path to your `.storyboard-sync.ignore` file (planned).