@dfosco/storyboard 1.0.0-beta.0 → 1.0.0-beta.1

package/package.json

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

package/scaffold/AGENTS.md

@@ -2,13 +2,13 @@
 
 ## Selected Widgets Context
 
-**Before processing ANY user prompt**, read `.storyboard/.selectedwidgets.json` at the repository root. This file is updated in real-time by the Storyboard dev server and reflects which canvas the user is currently viewing and which widgets they have selected in the browser.
+**Before processing ANY user prompt**, read `.storyboard/.selectedwidgets.json` at the repository root (the content root — where you run `storyboard` commands; in the `.backstage` layout this is the repo root you see, **not** the hidden `.backstage/` directory). This file is updated in real-time by the Storyboard dev server and reflects which canvas the user is currently viewing and which widgets they have selected in the browser.
 
 **File format:**
 ```json
 {
   "canvasId": "design-system",
-  "canvasFile": "src/canvas/design-system.canvas.jsonl",
+  "canvasFile": "canvas/design-system.canvas.jsonl",
   "selectedWidgetIds": ["img-abc123", "sticky-def456"],
   "widgets": [
     { "id": "img-abc123", "type": "image", "props": { "src": "screenshot.png" } },
@@ -196,6 +196,17 @@ This is a **Storyboard prototyping app** using Vite and file-based routing via `
 > content above the Vite root resolves its dependencies — `storyboard dev`
 > recreates it automatically. Either way, you only edit content +
 > `storyboard.config.json`.
+>
+> **Path convention — read this before following any `src/...` path below.**
+> Every content path in this document is written in the **legacy** form with a
+> `src/` prefix (`src/prototypes/`, `src/canvas/`, `src/components/`). In the
+> **`.backstage`** layout the content folders live at the repo root with **no
+> `src/` prefix** — `src/prototypes/X` becomes `prototypes/X`, `src/components/Y`
+> becomes `components/Y`, and so on. Detect your layout once: if the repo root
+> has a `.backstage/` directory, you are in the backstage layout — drop the
+> `src/` prefix from every path below. Agent files (`.agents/`, `AGENTS.md`) and
+> runtime state (`.storyboard/`) are bridged to the repo root in both layouts,
+> so reference them by their plain names regardless of layout.
 
 Detailed architectural documentation lives in `.agents/architecture/`. Consult the relevant architecture docs when:
 
@@ -231,7 +242,7 @@ The fix was a one-line compaction (4MB → 9KB). Everything the user reported
 - Use **semantic HTML tags** whenever they are appropriate in between Primer React components
 - Use the **canvas widget type registry** at `.agents/data/widget-types.json` as the authoritative list of valid canvas widget `type` strings, their props, default sizes, and when-to-use guidance. Never invent widget types. In particular: when showing multiple variants of a single story file, use ONE `component-set` widget — not N `story` widgets. Regenerate after changing the widget registry: `node scripts/gen-widget-types.mjs`.
 - Use **CSS Modules** (`*.module.css`) for component-specific styles
-- **Components must live in their own directory:** `src/components/Name/Name.jsx`, `Name.module.css`, `name.story.jsx`. Never place component files flat in `src/components/`.
+- **Components must live in their own directory:** `src/components/Name/Name.jsx`, `Name.module.css`, `name.story.jsx` (in the `.backstage` layout: `components/Name/Name.jsx` — drop the `src/` prefix). Never place component files flat in the components folder.
 - **Always use the `create` skill** when creating new components or stories — don't manually create files.
 - **Every piece of data consumed in a page must gracefully handle `null` or `undefined` without crashing.** Since flow data, records, and overrides can all be partial, incomplete, or missing, components must never assume a field exists. Use optional chaining, fallback values, or conditional rendering for every data access.
 - **Branch URL support is required for any feature involving URL fragments or URL matching.** Branch deploys use `VITE_BASE_PATH=/branch--{branch-name}/` which changes `import.meta.env.BASE_URL`. Any URL matching, same-origin detection, or src resolution must account for branch-prefixed paths (e.g. `/branch--my-feature/MyPrototype`). When implementing URL-related features, ask the user about branch URL support — if they're unavailable, build for it by default.

package/scaffold/terminal-agent.agent.md

@@ -23,6 +23,17 @@ tools:
 > - ✅ `POST /_storyboard/canvas/batch` with body `{"name":"my-canvas", ...}`
 > - ❌ `POST /_storyboard/canvas/my-canvas/widgets` — **DOES NOT EXIST**
 
+> **📂 Your working directory.** You run from the **content root** — the
+> directory holding the user's content folders (`prototypes/`, `canvas/`,
+> `components/`, `assets/`). Edit content there by its plain path
+> (`components/Foo/Foo.jsx`, `prototypes/Bar/index.jsx`) — **no `src/` prefix**.
+> Runtime + agent files are bridged into this same root, so the relative paths
+> in this doc just work: `.storyboard/terminals/…` (your config + env),
+> `.agents/skills/…` (skills), and `AGENTS.md` (repo instructions). In the
+> `.backstage` layout the build machinery (`node_modules`, `vite.config.js`,
+> `package.json`) lives in a hidden `.backstage/` directory you don't touch —
+> stay in the content root and never `cd` into `.backstage/`.
+
 ## ⚠️ Prime Directive: Results MUST be visible on the canvas
 
 **You CANNOT signal completion unless the user can see your result on the canvas.** This is non-negotiable. If you did work but the canvas looks the same as before, you failed.

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

@@ -48,6 +48,7 @@ import { writeFileSync, existsSync, unlinkSync, mkdirSync } from 'node:fs'
 import { join } from 'node:path'
 import { devLog } from '../logger/devLogger.js'
 import { readCapturedSessionId, captureFilePath, clearCaptureFile } from './agent-session.js'
+import { findSystemRoot } from '../paths/resolvePaths.js'
 
 /**
  * @typedef {Object} WarmSession
@@ -99,7 +100,13 @@ export class HotPool {
    * @param {Function} [opts.wsSend] — Vite server.ws.send for browser devlog events
    */
   constructor({ root, poolId = 'terminal', config = {}, agentConfig = null, wsSend = null }) {
-    this.#root = root
+    // Pre-warmed agents must spawn in the CONTENT root (where the user's
+    // prototypes/canvas/components live), not the Vite/system root. In the
+    // backstage layout the server passes the system root (`.backstage`); resolve
+    // it to the content root so the warm tmux session's fixed cwd, capture
+    // files (`.storyboard/…`, bridged), and STORYBOARD_PROJECT_ROOT all match
+    // the post-acquisition terminal-server spawn. Legacy layout is unchanged.
+    this.#root = findSystemRoot(root).contentRoot
     this.#poolId = poolId
     this.#poolSize = Math.max(0, config.pool_size ?? DEFAULT_POOL_SIZE)
     this.#maxPoolSize = Math.max(this.#poolSize, config.max_pool_size ?? DEFAULT_MAX_POOL_SIZE)

package/src/core/canvas/server.js

@@ -3522,9 +3522,11 @@ export function Default() {
         // Build server URL for agent env vars
         const serverUrl = `http://localhost:${req.socket?.localPort || 1234}`
 
-        // Create headless tmux session
+        // Create headless tmux session. Spawn in the CONTENT root (where the
+        // user's prototypes/canvas/components live), not the Vite/system root —
+        // matches the warm hot-pool + interactive terminal-server spawn cwd.
         try {
-          execSync(`tmux new-session -d -s "${tmuxName}" -c "${root}"`, { stdio: 'ignore' })
+          execSync(`tmux new-session -d -s "${tmuxName}" -c "${findSystemRoot(root).contentRoot}"`, { stdio: 'ignore' })
           execSync(`tmux set-option -t "${tmuxName}" status off`, { stdio: 'ignore' })
           execSync(`tmux set-option -t "${tmuxName}" mouse on`, { stdio: 'ignore' })
           execSync(`tmux set-option -t "${tmuxName}" set-clipboard off`, { stdio: 'ignore' })
@@ -3874,9 +3876,9 @@ export function Default() {
         }
 
         if (!usedWarm) {
-          // Fresh tmux session (cold path)
+          // Fresh tmux session (cold path) — spawn in the content root.
           try {
-            execSync(`tmux -f /dev/null new-session -d -s "${tmuxName}" -c "${root}"`, { stdio: 'ignore' })
+            execSync(`tmux -f /dev/null new-session -d -s "${tmuxName}" -c "${findSystemRoot(root).contentRoot}"`, { stdio: 'ignore' })
             execSync(`tmux set-option -t "${tmuxName}" status off`, { stdio: 'ignore' })
             execSync(`tmux set-option -t "${tmuxName}" set-clipboard off 2>/dev/null`, { stdio: 'ignore' })
           } catch { /* session may already exist */ }

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

@@ -55,6 +55,7 @@ import {
 } from './terminal-config.js'
 import { findByWorktree } from '../worktree/serverRegistry.js'
 import { detectWorktreeName } from '../worktree/port.js'
+import { findSystemRoot } from '../paths/resolvePaths.js'
 import { bindWidget, unbindWidget } from '../messaging/delivery.js'
 import { joinPresence, leavePresence } from '../messaging/presence.js'
 import {
@@ -982,7 +983,16 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
     ptyProcesses.delete(tmuxName)
   }
 
-  const cwd = process.cwd()
+  // Spawn the agent in the CONTENT root. In the backstage layout the dev
+  // server's process.cwd() is `.backstage/` (the Vite + npm root), but an
+  // agent must run where the user's content lives (prototypes/canvas/components
+  // at the content root). `.storyboard`, `node_modules`, `.agents` and
+  // `AGENTS.md` are bridged into the content root (see ensureContentSystemLinks
+  // / ensureContentNodeModulesLink), so every `.storyboard/...` path below
+  // resolves to the same physical file from either root. Legacy layout is
+  // unchanged (content root === process.cwd()).
+  const { mode: layoutMode, contentRoot } = findSystemRoot()
+  const cwd = layoutMode === 'backstage' ? contentRoot : process.cwd()
   const shell = process.env.SHELL || '/bin/zsh'
   const termCfg = readTerminalConfig()
   const prompt = termCfg.prompt || '$ '

package/src/core/cli/dev.js

@@ -20,7 +20,7 @@ import { readFileSync, existsSync } from 'node:fs'
 import { detectWorktreeName, getPort, releasePort } from '../worktree/port.js'
 import { startFileWatcher } from '../file-watcher/watcher.js'
 import { compactAll } from '../canvas/compact.js'
-import { findSystemRoot, mirrorSystemConfig, ensureContentNodeModulesLink, ensureLinkedDepsOverlay } from '../paths/resolvePaths.js'
+import { findSystemRoot, mirrorSystemConfig, ensureContentNodeModulesLink, ensureLinkedDepsOverlay, ensureContentSystemLinks } from '../paths/resolvePaths.js'
 import { parseFlags } from './flags.js'
 import { setupNeeded, writeUserState, getInstalledStoryboardVersion } from './userState.js'
 import { dim, magenta, bold } from './intro.js'
@@ -188,6 +188,11 @@ async function main() {
     // its hoisted deps aren't reachable from the Vite root. Overlay them so
     // Vite's optimizeDeps.include entries resolve. No-op for published installs.
     ensureLinkedDepsOverlay(layout)
+    // Bridge agent-facing system files (.agents, AGENTS.md, .storyboard) into
+    // the content root so a canvas/terminal agent — which runs FROM the content
+    // root, where prototypes/canvas/components live — can resolve its skills,
+    // instructions, and runtime bridge state by their conventional names.
+    ensureContentSystemLinks(layout)
   }
 
   // Port resolution priority (Vite always rolls forward to the next free

package/src/core/cli/updateVersion.js

@@ -12,7 +12,17 @@
 import * as p from '@clack/prompts'
 import { execSync } from 'child_process'
 import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'fs'
-import { dirname, resolve } from 'path'
+import { dirname, relative, resolve } from 'path'
+import { findSystemRoot } from '../paths/resolvePaths.js'
+
+// In the backstage layout, package.json / node_modules / scripts / vite.config
+// live under `<contentRoot>/.backstage` (the systemRoot) while `.git` and
+// `.github` live at the contentRoot. Resolve both so `storyboard update` works
+// when run from the content root. In the legacy layout both are the same dir.
+const { systemRoot, contentRoot } = findSystemRoot()
+// Path prefix from the git repo root (contentRoot) to systemRoot — '' in legacy,
+// '.backstage' in backstage. Used to stage systemRoot files from contentRoot.
+const sysPrefix = relative(contentRoot, systemRoot)
 
 const command = process.argv[2]
 const channels = { 'update:beta': 'beta', 'update:alpha': 'alpha' }
@@ -27,7 +37,7 @@ if (channels[command]) {
   targetVersion = command.slice('update:'.length)
 }
 
-const pkgPath = resolve(process.cwd(), 'package.json')
+const pkgPath = resolve(systemRoot, 'package.json')
 let pkg
 try {
   pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
@@ -74,7 +84,7 @@ for (const name of storyboardPkgs) {
 }
 
 try {
-  execSync(`npm install ${packages}`, { stdio: 'inherit', cwd: process.cwd() })
+  execSync(`npm install ${packages}`, { stdio: 'inherit', cwd: systemRoot })
   p.log.success('All storyboard packages updated')
 } catch {
   p.log.error('Failed to update packages — see npm output above')
@@ -84,22 +94,23 @@ try {
 // Sync scaffold files (skills, scripts) from the updated package
 p.log.info('Syncing scaffold files…')
 try {
-  execSync('npx storyboard-scaffold', { stdio: 'inherit', cwd: process.cwd() })
+  execSync('npx storyboard-scaffold', { stdio: 'inherit', cwd: systemRoot })
 } catch {
   p.log.warn('Scaffold sync failed — run `npx storyboard-scaffold` manually')
 }
 
 function checkArtifactDiscoveryWorkflow() {
-  const cwd = process.cwd()
+  // Workflows + their scripts live at the git repo root (contentRoot); the
+  // scaffold source ships inside the installed package under systemRoot.
   const workflows = [
-    { name: 'deploy.yml', path: resolve(cwd, '.github', 'workflows', 'deploy.yml') },
-    { name: 'preview.yml', path: resolve(cwd, '.github', 'workflows', 'preview.yml') },
+    { name: 'deploy.yml', path: resolve(contentRoot, '.github', 'workflows', 'deploy.yml') },
+    { name: 'preview.yml', path: resolve(contentRoot, '.github', 'workflows', 'preview.yml') },
   ].filter(workflow => existsSync(workflow.path))
 
   if (workflows.length === 0) return
 
-  const scriptTarget = resolve(cwd, '.github', 'workflows', 'scripts', 'aggregate-artifacts.mjs')
-  const scriptSource = resolve(cwd, 'node_modules', '@dfosco', 'storyboard', 'scaffold', 'scripts', 'aggregate-artifacts.mjs')
+  const scriptTarget = resolve(contentRoot, '.github', 'workflows', 'scripts', 'aggregate-artifacts.mjs')
+  const scriptSource = resolve(systemRoot, 'node_modules', '@dfosco', 'storyboard', 'scaffold', 'scripts', 'aggregate-artifacts.mjs')
 
   if (!existsSync(scriptTarget)) {
     if (existsSync(scriptSource)) {
@@ -133,11 +144,11 @@ try {
   // Read the installed version from the storyboard package (try unified first, then legacy core)
   let installedVersion
   try {
-    const unified = JSON.parse(readFileSync(resolve(process.cwd(), 'node_modules', '@dfosco', 'storyboard', 'package.json'), 'utf8'))
+    const unified = JSON.parse(readFileSync(resolve(systemRoot, 'node_modules', '@dfosco', 'storyboard', 'package.json'), 'utf8'))
     installedVersion = unified.version
   } catch {
     try {
-      const core = JSON.parse(readFileSync(resolve(process.cwd(), 'node_modules', '@dfosco', 'storyboard-core', 'package.json'), 'utf8'))
+      const core = JSON.parse(readFileSync(resolve(systemRoot, 'node_modules', '@dfosco', 'storyboard-core', 'package.json'), 'utf8'))
       installedVersion = core.version
     } catch { /* empty */ }
   }
@@ -150,13 +161,15 @@ try {
   // hands-off — customers never hand-patch these. User-facing *.config.json
   // (storyboard.config.json, terminal.config.json, …) are intentionally NOT
   // staged — those are customer-owned.
-  const filesToStage = [
+  //
+  // In the backstage layout these live under systemRoot (`.backstage`) while
+  // `.git`/`.github` live at contentRoot. Git runs from contentRoot, so prefix
+  // systemRoot-owned paths with sysPrefix; `.github/*` paths stay at the root.
+  const systemFiles = [
     'package.json',
     'package-lock.json',
     'yarn.lock',
     'pnpm-lock.yaml',
-    '.github/skills',
-    '.github/workflows/scripts/aggregate-artifacts.mjs',
     'scripts',
     // Tier-1 package-owned infrastructure (force-synced):
     'vite.config.js',
@@ -165,22 +178,31 @@ try {
     'tsconfig.json',
     'src/library',
   ]
+  const contentFiles = [
+    '.github/skills',
+    '.github/workflows/scripts/aggregate-artifacts.mjs',
+  ]
+  const filesToStage = [
+    ...systemFiles.map(f => (sysPrefix ? `${sysPrefix}/${f}` : f)),
+    ...contentFiles,
+  ]
   for (const f of filesToStage) {
-    try { execSync(`git add ${f}`, { cwd: process.cwd(), stdio: 'pipe' }) } catch { /* empty */ }
+    try { execSync(`git add ${f}`, { cwd: contentRoot, stdio: 'pipe' }) } catch { /* empty */ }
   }
 
   // Svelte was removed from the storyboard base — drop the stale empty stub
   // from existing customer repos so the update sheds it automatically.
   try {
-    execSync('git rm --quiet --ignore-unmatch svelte.config.js', { cwd: process.cwd(), stdio: 'pipe' })
+    const svelteStub = sysPrefix ? `${sysPrefix}/svelte.config.js` : 'svelte.config.js'
+    execSync(`git rm --quiet --ignore-unmatch ${svelteStub}`, { cwd: contentRoot, stdio: 'pipe' })
   } catch { /* empty */ }
 
   // Only commit if there are staged changes
   try {
-    execSync('git diff --cached --quiet', { cwd: process.cwd(), stdio: 'pipe' })
+    execSync('git diff --cached --quiet', { cwd: contentRoot, stdio: 'pipe' })
     p.log.message('No changes to commit — already up to date')
   } catch {
-    execSync(`git commit -m "${commitMsg}"`, { cwd: process.cwd(), stdio: 'pipe' })
+    execSync(`git commit -m "${commitMsg}"`, { cwd: contentRoot, stdio: 'pipe' })
     p.log.success(`Committed: ${commitMsg}`)
   }
 } catch (err) {

package/src/core/paths/resolvePaths.js

@@ -38,7 +38,7 @@
  * @module core/paths/resolvePaths
  */
 
-import { existsSync, lstatSync, readlinkSync, symlinkSync, unlinkSync, readdirSync, realpathSync, mkdirSync } from 'node:fs'
+import { existsSync, lstatSync, readlinkSync, symlinkSync, unlinkSync, readdirSync, realpathSync, mkdirSync, readFileSync, appendFileSync } from 'node:fs'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 import { copyFileSync } from 'node:fs'
 import process from 'node:process'
@@ -426,6 +426,96 @@ export function ensureLinkedDepsOverlay(loc, pkgName = '@dfosco/storyboard') {
 }
 
 
+/**
+ * Append a path to `<root>/.git/info/exclude` exactly once (best-effort).
+ *
+ * Used to keep generated bridge symlinks out of `git status` without touching
+ * the committed `.gitignore` — which must stay layout-agnostic (ignoring
+ * `/.agents` there would wrongly hide a legacy repo's committed files). The
+ * local `info/exclude` is per-clone and never committed, so it is the right
+ * place for backstage-only generated artifacts. Skips git worktrees (where
+ * `.git` is a file, not a directory) — harmless if those show the symlink.
+ *
+ * @param {string} root content root containing `.git`
+ * @param {string} name entry to exclude (added as `/name`)
+ */
+function registerGitExclude(root, name) {
+  try {
+    const gitDir = join(root, '.git')
+    if (!existsSync(gitDir) || !lstatSync(gitDir).isDirectory()) return
+    const infoDir = join(gitDir, 'info')
+    mkdirSync(infoDir, { recursive: true })
+    const excludeFile = join(infoDir, 'exclude')
+    let body = ''
+    try { body = readFileSync(excludeFile, 'utf8') } catch { /* new file */ }
+    const entry = `/${name}`
+    if (body.split(/\r?\n/).includes(entry)) return
+    const prefix = body && !body.endsWith('\n') ? '\n' : ''
+    appendFileSync(excludeFile, `${prefix}${entry}\n`)
+  } catch {
+    /* best-effort — never block dev start on git bookkeeping */
+  }
+}
+
+/**
+ * Bridge hidden system files into the content root so an agent (or any tool)
+ * running from the content root can resolve them by their conventional name.
+ *
+ * In the backstage layout a canvas/terminal agent's working directory is the
+ * content root (where `prototypes/`, `canvas/`, `components/` live), but the
+ * agent instruction + runtime files live under `.backstage`:
+ *
+ *   - `.agents/`     — skills, plans and data the agent reads by relative path
+ *   - `AGENTS.md`    — top-level agent instructions read on every prompt
+ *   - `.storyboard/` — runtime bridge state (`.selectedwidgets.json`,
+ *                      `terminals/*.json`, buffers) the agent and server share
+ *
+ * Each is symlinked from systemRoot into contentRoot with a relative target
+ * (created only when missing, never clobbering a real file the user placed
+ * there) and registered in `.git/info/exclude` so the bridged copy never shows
+ * up as an untracked file. The canonical copies stay committed under
+ * `.backstage`. No-op in the legacy layout (system === content root).
+ *
+ * @param {{ mode: 'backstage'|'legacy', systemRoot: string, contentRoot: string }} loc
+ * @returns {string[]} names that are now bridged into the content root
+ */
+export function ensureContentSystemLinks(loc) {
+  const { mode, systemRoot, contentRoot } = loc
+  if (mode !== 'backstage') return []
+  const names = ['.agents', 'AGENTS.md', '.storyboard']
+  const bridged = []
+  for (const name of names) {
+    const target = join(systemRoot, name)
+    // `.storyboard` is created lazily by the dev server at startup; ensure it
+    // exists first so the symlink resolves immediately rather than dangling.
+    if (name === '.storyboard' && !existsSync(target)) {
+      try { mkdirSync(target, { recursive: true }) } catch { /* empty */ }
+    }
+    if (!existsSync(target)) continue
+    const link = join(contentRoot, name)
+    try {
+      if (isSymlink(link)) {
+        if (resolve(dirname(link), readlinkSync(link)) === resolve(target)) {
+          bridged.push(name)
+          registerGitExclude(contentRoot, name)
+          continue
+        }
+        unlinkSync(link)
+      } else if (existsSync(link)) {
+        // A real file/dir already lives at the content root — never clobber it.
+        continue
+      }
+      symlinkSync(relative(contentRoot, target), link)
+      bridged.push(name)
+      registerGitExclude(contentRoot, name)
+    } catch {
+      /* best-effort bridge — a missing link only degrades agent ergonomics */
+    }
+  }
+  return bridged
+}
+
+
 function isSymlink(p) {
   try {
     return lstatSync(p).isSymbolicLink()

package/src/core/paths/resolvePaths.test.js

@@ -12,6 +12,7 @@ import {
   mirrorSystemConfig,
   ensureContentNodeModulesLink,
   ensureLinkedDepsOverlay,
+  ensureContentSystemLinks,
   ROLES,
   SYSTEM_DIR,
 } from './resolvePaths.js'
@@ -309,4 +310,67 @@ describe('core/paths/resolvePaths', () => {
       expect(ensureLinkedDepsOverlay(findSystemRoot(tmp))).toBe(0)
     })
   })
+
+  describe('ensureContentSystemLinks', () => {
+    // Build a backstage layout with committed system files under .backstage.
+    function setupBackstage({ git = false } = {}) {
+      const sys = join(tmp, SYSTEM_DIR)
+      mkdirSync(join(sys, '.agents', 'skills'), { recursive: true })
+      writeFileSync(join(sys, '.agents', 'skills', 'x.md'), '# skill\n')
+      writeFileSync(join(sys, 'AGENTS.md'), '# agents\n')
+      if (git) mkdirSync(join(tmp, '.git'), { recursive: true })
+      return { sys }
+    }
+
+    it('is a no-op in the legacy layout', () => {
+      expect(ensureContentSystemLinks(findSystemRoot(tmp))).toEqual([])
+    })
+
+    it('bridges .agents, AGENTS.md and .storyboard into the content root', () => {
+      setupBackstage()
+      const bridged = ensureContentSystemLinks(findSystemRoot(tmp))
+      expect(bridged).toEqual(expect.arrayContaining(['.agents', 'AGENTS.md', '.storyboard']))
+      for (const name of ['.agents', 'AGENTS.md', '.storyboard']) {
+        const link = join(tmp, name)
+        expect(lstatSync(link).isSymbolicLink()).toBe(true)
+        expect(realpathSync(link)).toBe(realpathSync(join(tmp, SYSTEM_DIR, name)))
+      }
+      // The bridge resolves real system content through the symlink.
+      expect(readFileSync(join(tmp, '.agents', 'skills', 'x.md'), 'utf8')).toContain('# skill')
+    })
+
+    it('creates a relative symlink target so the repo stays portable', () => {
+      setupBackstage()
+      ensureContentSystemLinks(findSystemRoot(tmp))
+      expect(readlinkSync(join(tmp, 'AGENTS.md'))).toBe(join(SYSTEM_DIR, 'AGENTS.md'))
+    })
+
+    it('lazily creates the .storyboard directory when missing', () => {
+      setupBackstage()
+      expect(existsSync(join(tmp, SYSTEM_DIR, '.storyboard'))).toBe(false)
+      ensureContentSystemLinks(findSystemRoot(tmp))
+      expect(existsSync(join(tmp, SYSTEM_DIR, '.storyboard'))).toBe(true)
+      expect(lstatSync(join(tmp, '.storyboard')).isSymbolicLink()).toBe(true)
+    })
+
+    it('never clobbers a real file already at the content root', () => {
+      setupBackstage()
+      writeFileSync(join(tmp, 'AGENTS.md'), '# user-owned\n')
+      ensureContentSystemLinks(findSystemRoot(tmp))
+      expect(lstatSync(join(tmp, 'AGENTS.md')).isSymbolicLink()).toBe(false)
+      expect(readFileSync(join(tmp, 'AGENTS.md'), 'utf8')).toBe('# user-owned\n')
+    })
+
+    it('is idempotent and registers bridges in .git/info/exclude', () => {
+      setupBackstage({ git: true })
+      ensureContentSystemLinks(findSystemRoot(tmp))
+      ensureContentSystemLinks(findSystemRoot(tmp))
+      const exclude = readFileSync(join(tmp, '.git', 'info', 'exclude'), 'utf8')
+      const lines = exclude.split(/\r?\n/)
+      // Each entry appears exactly once despite two runs.
+      expect(lines.filter((l) => l === '/.agents')).toHaveLength(1)
+      expect(lines.filter((l) => l === '/AGENTS.md')).toHaveLength(1)
+      expect(lines.filter((l) => l === '/.storyboard')).toHaveLength(1)
+    })
+  })
 })