@dfosco/storyboard 0.5.0-alpha.3 → 0.5.0-alpha.4

package/dist/storyboard-ui.js

@@ -11573,7 +11573,7 @@ function At() {
       console.error("[storyboard] Error in tool state subscriber:", t);
     }
 }
-const Fr = { "command-toolbar": { position: "bottom-right", layout: "row" }, "canvas-toolbar": { position: "bottom-left", layout: "row" }, "command-palette": { position: "command-menu", layout: "list" } }, Wr = { dark: "github-dark-dimmed", light: "github" }, Ur = { "hide-chrome": { ariaLabel: "Hide toolbars", icon: "primer/light-bulb", render: "button", surface: "command-toolbar", handler: "core:hide-chrome", modes: ["*"], prod: !0, shortcut: { key: ".", label: "cmd ." }, hideInCommandPalette: [".*"], alwaysVisible: !0 }, flows: { label: "Flows", ariaLabel: "Switch flow", icon: "feather/fast-forward", render: "menu", surface: "command-toolbar", modes: ["*"], prod: !0, menuWidth: "280px", handler: "core:flows", excludeRoutes: ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"], hideInCommandPalette: ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"] }, theme: { label: "Theme", ariaLabel: "Switch theme", icon: "primer/sun", meta: { strokeWeight: 2 }, render: "menu", surface: "command-toolbar", handler: "core:theme", modes: ["*"], prod: !0, menuWidth: "260px", hideInCommandPalette: [".*"], options: [{ label: "System", value: "system" }, { label: "Light", value: "light" }, { label: "Light colorblind", value: "light_colorblind" }, { label: "Dark", value: "dark" }, { label: "Dark colorblind", value: "dark_colorblind" }, { label: "Dark high contrast", value: "dark_high_contrast" }, { label: "Dark Dimmed", value: "dark_dimmed" }] }, comments: { ariaLabel: "Comments", icon: "primer/comment", render: "button", surface: "*", handler: "core:comments", modes: ["*"], prod: !0, excludeRoutes: ["^/$", "^/workspace", "^/viewfinder"], hideInCommandPalette: ["^/$", "^/workspace", "^/viewfinder"] }, inspector: { ariaLabel: "Inspect components", icon: "iconoir/square-dashed", render: "sidepanel", surface: "command-toolbar", sidepanel: "inspector", handler: "core:inspector", modes: ["*"], prod: !0, excludeRoutes: ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"], hideInCommandPalette: ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"], meta: { strokeWeight: 2, scale: 1.1 }, shortcut: { key: "i", label: "cmd + i" } }, create: { disabled: !0, label: "Create", ariaLabel: "Create", icon: "iconoir/plus-circle", meta: { strokeWeight: 2, scale: 1.1 }, render: "menu", surface: "command-toolbar", handler: "core:create", modes: ["*"], menuWidth: "290px", actions: [{ type: "header", label: "Create" }, { id: "workshop/create-prototype", label: "New prototype", type: "default", modes: ["*"], feature: "createPrototype" }, { id: "workshop/create-flow", label: "New flow", type: "default", modes: ["*"], feature: "createFlow", excludeRoutes: ["/canvas/", "/components/"] }, { id: "workshop/create-page", label: "New page", type: "default", modes: ["*"], feature: "createPage", excludeRoutes: ["/canvas/", "/components/"] }, { id: "workshop/create-canvas", label: "New canvas", type: "default", modes: ["*"], feature: "createCanvas" }, { type: "footer", label: "Only available in dev environment" }] }, autosync: { ariaLabel: "Auto sync", icon: "primer/sync", render: "menu", surface: "command-toolbar", handler: "core:autosync", modes: ["*"], menuWidth: "400px" }, "canvas-add-widget": { ariaLabel: "Add widget", icon: "iconoir/grid-plus", render: "menu", surface: "canvas-toolbar", handler: "core:canvas-add-widget", modes: ["*"], meta: { strokeWeight: 2, scale: 1.2 }, menuWidth: "300px", excludeRoutes: ["^/$", "^/workspace", "^/viewfinder"], hideInCommandPalette: [".*"] }, "canvas-agents": { ariaLabel: "Add agent", label: "Add agent", icon: "agents", render: "menu", surface: "canvas-toolbar", handler: "core:canvas-agents", modes: ["*"], menuWidth: "220px", excludeRoutes: ["^/$", "^/workspace", "^/viewfinder"], hideInCommandPalette: [".*"] }, "canvas-zoom": { ariaLabel: "Zoom controls", render: "canvas-zoom", surface: "canvas-toolbar", handler: "core:canvas-toolbar", modes: ["*"], prod: !0, hideInCommandPalette: [".*"] }, "canvas-zoom-to-fit": { ariaLabel: "Zoom to objects", label: "Zoom to objects", icon: "iconoir/square-3d-three-points", meta: { strokeWeight: 2, scale: 1.2 }, render: "canvas-zoom-to-fit", surface: "canvas-toolbar", handler: "core:canvas-toolbar", modes: ["*"], prod: !0, hideInCommandPalette: ["^(?!/canvas)"] }, "canvas-snap": { ariaLabel: "Snap to grid", label: "Snap to grid", labelOn: "Snap to grid (on)", labelOff: "Snap to grid (off)", icon: "primer/apps", meta: { strokeWeight: 1.5, scale: 1.2 }, render: "canvas-snap", surface: "canvas-toolbar", handler: "core:canvas-toolbar", gridSize: 40, modes: ["*"], hideInCommandPalette: ["^(?!/canvas)"] }, "canvas-undo-redo": { ariaLabel: "Undo and redo", render: "canvas-undo-redo", surface: "canvas-toolbar", handler: "core:canvas-toolbar", modes: ["*"], hideInCommandPalette: [".*"] }, workspace: { label: "Go to workspace", icon: "primer/home-fill", render: "link", surface: "command-palette", modes: ["*"], prod: !0, url: "/" }, repository: { label: "Go to repository", icon: "primer/mark-github", render: "link", surface: "command-palette", modes: ["*"], prod: !0, url: "" }, docs: { label: "Storyboard Docs", ariaLabel: "Storyboard Docs", icon: "primer/book", render: "link", surface: "command-palette", modes: ["*"], prod: !0, url: "https://github.com/dfosco/storyboard/blob/main/DOCS.md" }, "submit-feedback": { label: "Submit feedback", icon: "primer/megaphone", render: "link", surface: "command-palette", modes: ["*"], prod: !0, url: "https://github.com/dfosco/storyboard/issues/new?template=feedback.yml" }, devtools: { label: "Devtools", icon: "iconoir/wrench", render: "submenu", surface: "command-palette", modes: ["*"], prod: !0, handler: "core:devtools", hideFromCommandPaletteSearch: !0 }, "palette-theme": { label: "Switch theme", icon: "primer/sun", render: "submenu", surface: "command-palette", modes: ["*"], prod: !0, handler: "core:palette-theme" }, "feature-flags": { label: "Feature Flags", icon: "iconoir/white-flag", render: "submenu", surface: "command-palette", modes: ["*"], prod: !0, hideFromCommandPaletteSearch: !0, handler: "core:feature-flags" }, "hide-toolbars": { label: "Hide toolbars", icon: "primer/light-bulb", render: "button", surface: "command-palette", modes: ["*"], prod: !0, inlineAction: "toggle-chrome", shortcut: { key: ".", label: "cmd + ." } }, "command-palette": { ariaLabel: "Command palette", icon: "iconoir/key-command", meta: { strokeWeight: 2 }, render: "button", surface: "command-toolbar", size: "icon-2xl", handler: "core:command-palette", modes: ["*"], prod: !0, shortcut: { key: "k", label: "cmd + K" }, hideInCommandPalette: [".*"] } }, Gr = {
+const Fr = { "command-toolbar": { position: "bottom-right", layout: "row" }, "canvas-toolbar": { position: "bottom-left", layout: "row" }, "command-palette": { position: "command-menu", layout: "list" } }, Wr = { dark: "github-dark-dimmed", light: "github" }, Ur = { "hide-chrome": { ariaLabel: "Hide toolbars", icon: "primer/light-bulb", render: "button", surface: "command-toolbar", handler: "core:hide-chrome", modes: ["*"], prod: !0, shortcut: { key: ".", label: "cmd ." }, hideInCommandPalette: [".*"], alwaysVisible: !0 }, flows: { label: "Flows", ariaLabel: "Switch flow", icon: "feather/fast-forward", render: "menu", surface: "command-toolbar", modes: ["*"], prod: !0, menuWidth: "280px", handler: "core:flows", excludeRoutes: ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"], hideInCommandPalette: ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"] }, theme: { label: "Theme", ariaLabel: "Switch theme", icon: "primer/sun", meta: { strokeWeight: 2 }, render: "menu", surface: "command-toolbar", handler: "core:theme", modes: ["*"], prod: !0, menuWidth: "260px", hideInCommandPalette: [".*"], options: [{ label: "System", value: "system" }, { label: "Light", value: "light" }, { label: "Light colorblind", value: "light_colorblind" }, { label: "Dark", value: "dark" }, { label: "Dark colorblind", value: "dark_colorblind" }, { label: "Dark high contrast", value: "dark_high_contrast" }, { label: "Dark Dimmed", value: "dark_dimmed" }] }, comments: { ariaLabel: "Comments", icon: "primer/comment", render: "button", surface: "*", handler: "core:comments", modes: ["*"], prod: !0, excludeRoutes: ["^/$", "^/workspace", "^/viewfinder"], hideInCommandPalette: ["^/$", "^/workspace", "^/viewfinder"] }, inspector: { ariaLabel: "Inspect components", icon: "iconoir/square-dashed", render: "sidepanel", surface: "command-toolbar", sidepanel: "inspector", handler: "core:inspector", modes: ["*"], prod: !0, excludeRoutes: ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"], hideInCommandPalette: ["^/$", "^/workspace", "^/viewfinder", "/canvas/", "/components/", "/notebook/"], meta: { strokeWeight: 2, scale: 1.1 }, shortcut: { key: "i", label: "cmd + i" } }, create: { disabled: !0, label: "Create", ariaLabel: "Create", icon: "iconoir/plus-circle", meta: { strokeWeight: 2, scale: 1.1 }, render: "menu", surface: "command-toolbar", handler: "core:create", modes: ["*"], menuWidth: "290px", actions: [{ type: "header", label: "Create" }, { id: "workshop/create-prototype", label: "New prototype", type: "default", modes: ["*"], feature: "createPrototype" }, { id: "workshop/create-flow", label: "New flow", type: "default", modes: ["*"], feature: "createFlow", excludeRoutes: ["/canvas/", "/components/"] }, { id: "workshop/create-page", label: "New page", type: "default", modes: ["*"], feature: "createPage", excludeRoutes: ["/canvas/", "/components/"] }, { id: "workshop/create-canvas", label: "New canvas", type: "default", modes: ["*"], feature: "createCanvas" }, { type: "footer", label: "Only available in dev environment" }] }, autosync: { ariaLabel: "Auto sync", icon: "primer/sync", render: "menu", surface: "command-toolbar", handler: "core:autosync", modes: ["*"], menuWidth: "400px" }, "canvas-add-widget": { ariaLabel: "Add widget", icon: "iconoir/grid-plus", render: "menu", surface: "canvas-toolbar", handler: "core:canvas-add-widget", modes: ["*"], meta: { strokeWeight: 2, scale: 1.2 }, menuWidth: "300px", excludeRoutes: ["^/$", "^/workspace", "^/viewfinder"], hideInCommandPalette: [".*"] }, "canvas-agents": { ariaLabel: "Add agent", label: "Add agent", icon: "agents", render: "menu", surface: "canvas-toolbar", handler: "core:canvas-agents", modes: ["*"], prod: !0, menuWidth: "220px", excludeRoutes: ["^/$", "^/workspace", "^/viewfinder"], hideInCommandPalette: [".*"] }, "canvas-zoom": { ariaLabel: "Zoom controls", render: "canvas-zoom", surface: "canvas-toolbar", handler: "core:canvas-toolbar", modes: ["*"], prod: !0, hideInCommandPalette: [".*"] }, "canvas-zoom-to-fit": { ariaLabel: "Zoom to objects", label: "Zoom to objects", icon: "iconoir/square-3d-three-points", meta: { strokeWeight: 2, scale: 1.2 }, render: "canvas-zoom-to-fit", surface: "canvas-toolbar", handler: "core:canvas-toolbar", modes: ["*"], prod: !0, hideInCommandPalette: ["^(?!/canvas)"] }, "canvas-snap": { ariaLabel: "Snap to grid", label: "Snap to grid", labelOn: "Snap to grid (on)", labelOff: "Snap to grid (off)", icon: "primer/apps", meta: { strokeWeight: 1.5, scale: 1.2 }, render: "canvas-snap", surface: "canvas-toolbar", handler: "core:canvas-toolbar", gridSize: 40, modes: ["*"], hideInCommandPalette: ["^(?!/canvas)"] }, "canvas-undo-redo": { ariaLabel: "Undo and redo", render: "canvas-undo-redo", surface: "canvas-toolbar", handler: "core:canvas-toolbar", modes: ["*"], hideInCommandPalette: [".*"] }, workspace: { label: "Go to workspace", icon: "primer/home-fill", render: "link", surface: "command-palette", modes: ["*"], prod: !0, url: "/" }, repository: { label: "Go to repository", icon: "primer/mark-github", render: "link", surface: "command-palette", modes: ["*"], prod: !0, url: "" }, docs: { label: "Storyboard Docs", ariaLabel: "Storyboard Docs", icon: "primer/book", render: "link", surface: "command-palette", modes: ["*"], prod: !0, url: "https://github.com/dfosco/storyboard/blob/main/DOCS.md" }, "submit-feedback": { label: "Submit feedback", icon: "primer/megaphone", render: "link", surface: "command-palette", modes: ["*"], prod: !0, url: "https://github.com/dfosco/storyboard/issues/new?template=feedback.yml" }, devtools: { label: "Devtools", icon: "iconoir/wrench", render: "submenu", surface: "command-palette", modes: ["*"], prod: !0, handler: "core:devtools", hideFromCommandPaletteSearch: !0 }, "palette-theme": { label: "Switch theme", icon: "primer/sun", render: "submenu", surface: "command-palette", modes: ["*"], prod: !0, handler: "core:palette-theme" }, "feature-flags": { label: "Feature Flags", icon: "iconoir/white-flag", render: "submenu", surface: "command-palette", modes: ["*"], prod: !0, hideFromCommandPaletteSearch: !0, handler: "core:feature-flags" }, "hide-toolbars": { label: "Hide toolbars", icon: "primer/light-bulb", render: "button", surface: "command-palette", modes: ["*"], prod: !0, inlineAction: "toggle-chrome", shortcut: { key: ".", label: "cmd + ." } }, "command-palette": { ariaLabel: "Command palette", icon: "iconoir/key-command", meta: { strokeWeight: 2 }, render: "button", surface: "command-toolbar", size: "icon-2xl", handler: "core:command-palette", modes: ["*"], prod: !0, shortcut: { key: "k", label: "cmd + K" }, hideInCommandPalette: [".*"] } }, Gr = {
   surfaces: Fr,
   highlighting: Wr,
   tools: Ur

package/package.json

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

package/scaffold/manifest.json

@@ -27,10 +27,26 @@
     },
     {
       "source": "scaffold/skills/",
-      "target": ".github/skills/",
+      "target": ".agents/skills/",
       "mode": "updateable",
       "directory": true
     },
+    {
+      "source": "scaffold/roles/",
+      "target": ".agents/roles/",
+      "mode": "updateable",
+      "directory": true
+    },
+    {
+      "source": "scaffold/prompt-agent.agent.md",
+      "target": ".agents/prompt-agent.agent.md",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/terminal-agent.agent.md",
+      "target": ".agents/terminal-agent.agent.md",
+      "mode": "updateable"
+    },
     {
       "source": "scaffold/deploy.yml",
       "target": ".github/workflows/deploy.yml",

package/scaffold/{agents/prompt-agent.agent.md → prompt-agent.agent.md}

@@ -16,6 +16,8 @@ You are a **single-shot task agent** spawned by a prompt widget on a Storyboard
 
 **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.
 
+**Exception — messaging actions:** When your task is sending a message to a peer (via `storyboard terminal send` or the messaging bus), the message itself IS the deliverable. **Do NOT create a widget on the canvas to echo or summarize the message.** Just send the message, save your output, and signal done. Canvas widgets are for task results, not for reflecting conversational messages back onto the board. Only create a canvas widget for a messaging action if the message content explicitly calls for it (e.g., "send this result and post it on the canvas too") or if you're outputting a completed task result that happens to also be sent as a message.
+
 Before signaling done, you must have done **at least one** of:
 
 1. **Created a new widget** on the canvas (sticky note, markdown, story, etc.) connected to your prompt widget — showing the output, summary, or deliverable

package/scaffold/roles/cluster-token.md

@@ -0,0 +1,25 @@
+---
+title: Cluster Token Holder
+type: transient
+default: false
+---
+
+# Cluster Token
+
+You currently **hold the cluster token** — you have speaking rights in the hub.
+
+## What this means
+
+- You can broadcast messages to the hub channel via `POST /_storyboard/messages/hub/send`.
+- You can transfer the token to a peer via `POST /_storyboard/messages/hub/token` when you want them to act autonomously.
+- Other hub members cannot broadcast until they hold the token or receive a message token for a specific request.
+
+## What this does NOT mean
+
+- Holding the cluster token does **not** make you the leader. You **cannot** set the hub goal or signal finality — those are leader-only actions tied to the role, not the token.
+- If you are a member holding the token, use it to complete delegated work, then transfer it back to the leader.
+
+## When you lose the token
+
+- You will be notified via a `hub:token:transferred` event in the channel log.
+- After losing the token, wait for a message token (ordered response request) before acting.

package/scaffold/roles/leader.role.md

@@ -0,0 +1,38 @@
+---
+title: Leader
+type: unique
+default: false
+---
+
+# Leader Role
+
+You are the **leader** of this hub. You coordinate the conversation and own completion.
+
+## Responsibilities
+
+1. **Receive user requests** — when a user message arrives, you define the hub goal and orchestrate work across hub members.
+2. **Set the goal** — use `storyboard hub goal --hub <hubId> --goal "..."` to set the high-level objective. This is a leader-only action (not tied to the hub token).
+3. **Delegate with tokens** — when you hold the hub token, send requests to peers via `storyboard hub send --hub <hubId> --sender <yourId> --body "..."`. You can transfer the token to a peer with `storyboard hub token --hub <hubId> --to <peerId>` for autonomous work.
+4. **Aggregate responses** — poll `storyboard messages read --channel <channel> --since <lastId>` to collect peer responses as message tokens resolve.
+5. **Own completion** — you decide when the task is done. Render the final result on the canvas (add or update widgets), then signal finality via `storyboard hub conversation finality --hub <hubId> --sender <yourId>`. Finality is a leader-only action — it does not require the hub token.
+
+## Hub Protocol
+
+- Read your hub context from the terminal config file at `.storyboard/terminals/{yourWidgetId}.json` — the `hubs` array lists your peers, your channel, and whether you hold the hub token.
+- Start a conversation with `storyboard hub conversation start --hub <hubId> --sender <yourId>` before sending your first hub message.
+- Use `storyboard hub goal --hub <hubId> --goal "..."` to set the high-level objective visible to all peers.
+- Poll `storyboard messages read --channel <channel> --since <lastId>` every 2 seconds to check for new messages.
+- After all peer responses arrive, synthesize and act. If the task is complete, render output on the canvas and call finality.
+- You may reopen a finalized conversation with `storyboard hub conversation reopen --hub <hubId> --sender <yourId>` if new context arrives.
+
+## Canvas Output
+
+- **Iterate, don't duplicate.** When a peer provides feedback on an existing canvas widget (markdown, sticky note, component, etc.), **update that widget** using `storyboard canvas update <id>` — do not create a new one. Only create a new widget when the output is genuinely a separate deliverable (e.g. a second document the user asked for).
+- Use your judgment: if the user asked for "a markdown document," there should be exactly one markdown widget at the end — refined through rounds of feedback, not a trail of drafts.
+
+## Important
+
+- **Never signal finality before the canvas reflects the outcome.** Finality means "the user can see the result."
+- If a peer times out, skip them and proceed with available responses.
+- Keep messages concise — peers see the full conversation log.
+

package/scaffold/roles/member.role.md

@@ -0,0 +1,32 @@
+---
+title: Member
+type: shared
+default: true
+---
+
+# Member Role
+
+You are a **member** of this hub. You contribute work when the leader delegates to you.
+
+## Responsibilities
+
+1. **Wait for your token** — monitor your message token status by polling `storyboard messages read --channel <channel> --since <lastId>`. When a `hub:message:request` arrives and your token is active, respond.
+2. **Respond promptly** — read the full conversation context, do your work, then respond via `storyboard hub respond --hub <hubId> --sender <yourId> --body "..."` with your analysis, implementation, or feedback.
+3. **Report clearly** — include what you did, what you found, or what you recommend. The leader aggregates responses from all peers.
+4. **Defer finality** — never signal conversation finality. The leader owns completion decisions and canvas rendering.
+
+## Hub Protocol
+
+- Read your hub context from `.storyboard/terminals/{yourWidgetId}.json` — the `hubs` array tells you your role, peers, channel, and active token status.
+- Poll `storyboard messages read --channel <channel> --since <lastId>` every 2 seconds.
+- When you see a `hub:message:request` event where your widget is the active token holder, process the request and respond.
+- Your response automatically advances the token to the next peer.
+- If you receive the hub token (via `hub:token:transferred`), you may send messages to the channel, but defer major decisions to the leader.
+
+## Important
+
+- **Do not create output widgets on the canvas unless explicitly asked by the leader.** The leader renders final results.
+- **Iterate, don't duplicate.** If the leader asks you to refine or improve a widget that already exists on the canvas, update it with `storyboard canvas update <id>` — do not create a new widget alongside it.
+- Keep responses focused and concise — the leader reads all peer responses to synthesize.
+- If you need clarification, include your question in your response body — the leader will follow up.
+

package/scaffold/roles/starter.role.md

@@ -0,0 +1,79 @@
+---
+title: Starter
+type: unique
+default: false
+transient: true
+---
+
+# Starter Role
+
+You are the **starter** of a hub. Your job is to spawn real, autonomous agent sessions on the canvas, connect them, and kick off the conversation. Each agent widget you create becomes an **independent AI process** — its own tmux session running its own CLI agent. Once the hub is running, your role transitions to **leader**.
+
+## When This Role Is Assigned
+
+This role is injected when the user asks you to create a hub (e.g., "create a hub for…", "spawn a hub with…", "Hub: [task]"). It provides the context you need to bootstrap the hub without guessing.
+
+## Hub Creation Procedure
+
+### 1. Determine Composition
+
+Based on the user's request, decide:
+- How many agents are needed (minimum 2 total, including yourself)
+- What each agent's specialization/name should be
+- Keep it small (2–5 agents is typical)
+
+### 2. Create Agent Widgets and Connectors
+
+Use `storyboard canvas batch` to create all agents and connect them in one call. Use `$0`, `$1`, etc. to reference widget IDs from earlier operations:
+
+```bash
+storyboard canvas batch --canvas "$STORYBOARD_CANVAS_ID" --ops '[
+  { "op": "create-widget", "type": "agent", "props": { "prettyName": "<agent-name>", "agentId": "copilot" } },
+  { "op": "create-connector", "startWidgetId": "'"$STORYBOARD_WIDGET_ID"'", "startAnchor": "right", "endWidgetId": "$0", "endAnchor": "left" }
+]'
+```
+
+For multiple agents, add more `create-widget` + `create-connector` pairs. Reference `$0` for the first widget, `$1` for the second, etc.
+
+### 3. Wait for Agent Sessions
+
+Agent widgets auto-start when the browser renders them — the TerminalWidget connects via WebSocket and the terminal-server launches the agent using the `startupCommand` from the widget's `agentId`. **You do not need to call `agent/spawn`** — just wait a few seconds for the browser to render the new widgets and for the agents to boot.
+
+### 4. Enable Broadcast
+
+Turn on messaging across the full hub:
+
+```bash
+storyboard canvas broadcast \
+  --canvas "$STORYBOARD_CANVAS_ID" \
+  --widget "$STORYBOARD_WIDGET_ID" \
+  --mode two-way \
+  --pass-through
+```
+
+### 5. Start Conversation
+
+Wait 2–3 seconds for hub materialization, then read your hub ID and start a conversation:
+
+```bash
+# Read hub ID from terminal config
+HUB_ID=$(cat .storyboard/terminals/$(echo $STORYBOARD_WIDGET_ID | tr '-' '_').json 2>/dev/null | jq -r '.hubs[0].hubId // empty')
+
+# If hub ID isn't available yet, check the hub state endpoint
+if [ -z "$HUB_ID" ]; then
+  HUB_ID=$(storyboard hub state --canvas "$STORYBOARD_CANVAS_ID" 2>/dev/null | jq -r '.hubs[0].hubId // empty')
+fi
+
+# Start conversation
+storyboard hub conversation start --hub "$HUB_ID" --sender "$STORYBOARD_WIDGET_ID"
+```
+
+## After Hub Creation
+
+Once all agents are spawned and the conversation has started, your role automatically transitions to **leader**. Read `.agents/roles/leader.role.md` for your ongoing responsibilities.
+
+## Guardrails
+
+- **Explicit only** — only create a hub when the user explicitly asks ("create a hub", "spawn a hub", "Hub: [task]")
+- **Max 5 agents** — keep hubs small and focused unless the user specifies otherwise
+- **You are the leader** — you always become the hub leader; spawned agents are members

package/scaffold/skills/architecture-scanner/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: architecture-scanner
+description: Architecture scanner and documentation generator. Use when scanning the codebase architecture, updating architecture docs, or generating architecture documentation.
+metadata:
+  author: Daniel Fosco
+  version: "2026.3.09"
+---
+
+# Architecture Scanner Skill
+
+> Triggered by: "scan the codebase architecture", "update the architecture", "update arch", "generate architecture docs", "scan arch", "full update", "full architecture update", "full refresh architecture"
+
+## What This Does
+
+Generates documentation files in `.agents/architecture/` that describe every architecturally significant file in the codebase. The system has two layers:
+
+- **`architecture.index.md`** — The architectural overview. Groups files by category (ordered and configured via the `categories` array in `files.json`) and includes prose summaries. Categories with `"priority": "critical"` get 2-3x more detailed overviews. A reader should be able to understand the system's architecture from this file alone.
+- **Per-file docs** (`{filepath}.md`) — Detailed documentation for individual files, including what they do, how they work (with code samples), their dependencies, and dependents. Every file reference is cross-linked to its architecture doc.
+
+## How to Execute
+
+### Step 0: Inventory package topology (required)
+
+Before discovery, identify **every** `package.json` in the repo (root + workspace packages), excluding `node_modules`, and read each manifest:
+
+```bash
+find . -name package.json \
+  -not -path './node_modules/*' \
+  -not -path './packages/*/node_modules/*' \
+  -not -path './worktrees/*' \
+  | sort
+```
+
+Use this inventory to build your architecture mental model (package names, responsibilities, and internal package dependencies). This step is mandatory and prevents stale assumptions like "the repo only has two packages."
+
+### Step 1: Discover files
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --discover
+```
+
+This scans the repo using discovery rules and creates or updates `files.json` in the skill folder. If `files.json` doesn't exist yet, it creates it with default priorities. If it already exists, it **adds new files** and **removes deleted files**, but **preserves user-set `importance` values** — those are never overwritten.
+
+Discovery includes the root `package.json` and every workspace package manifest at `packages/*/package.json`, so package-level architecture is always represented in the docs.
+
+Run this first to ensure the file list is current.
+
+### Step 2: Determine what needs to be done
+
+Run `--stale` to get the incremental manifest. This is the **default for all runs** unless architecture docs don't exist yet.
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --stale
+```
+
+This uses **git history** to detect changes: it finds the most recent commit that touched `.agents/architecture/`, then diffs against `HEAD` to identify changed source files, and also includes uncommitted (staged/unstaged) changes.
+
+`--stale` returns a JSON object with three incremental buckets:
+
+- **`files`** — docs to create/update:
+  - `"missing"` = source exists but doc does not (added/new file docs)
+  - `"stale"` = source changed since last architecture update
+- **`removed`** — docs to delete because source was removed/moved or is no longer tracked
+- **`index`** — whether `architecture.index.md` should be regenerated (`"status": "stale"`) and why
+
+If `files` and `removed` are both empty and `index.status` is `"fresh"`, docs are up to date.
+
+**When `--stale` suggests a full scan:** If more than 50% of documented files need updates, output includes `"suggestion": "full_scan"` and a message. In this case, switch to a full scan:
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --manifest
+```
+
+You can also force a full scan explicitly with:
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --full
+```
+
+This outputs every non-low file regardless of change status. Use this for:
+- **First-time runs** (no architecture docs exist yet)
+- **Template changes** (when the doc format itself changed, so all docs need regeneration)
+- **When `--stale` suggests it** (many files changed across multiple commits)
+- **When the user explicitly requests a full scan**
+- **When the user says natural-language variants like "full update" / "full refresh"**
+
+**Low importance files are excluded from both manifests and should NOT get architecture docs.**
+
+### Step 3: Generate or update documentation for each file
+
+For each entry in `files` (from `--stale`) or each entry in the full manifest (`--manifest`/`--full`), produce a markdown file at:
+
+```
+.agents/architecture/{filepath}.md
+```
+
+For example:
+- `src/storyboard/core/loader.js` → `.agents/architecture/src/storyboard/core/loader.js.md`
+- `vite.config.js` → `.agents/architecture/vite.config.js.md`
+
+#### For NEW files (status `"missing"`, or first full scan):
+
+Create subdirectories as needed with `mkdir -p`. Use the **create** tool to write the doc file. The manifest's `doc` field contains the exact relative path to use.
+
+#### For STALE files (status `"stale"`):
+
+The doc already exists but the source file has changed. Follow this process:
+
+1. **Read the source file** to understand what changed
+2. **Read the existing doc file** to see what's already documented
+3. **Use the edit tool** to update only the sections that are affected by the source changes — preserve the existing structure and any manually-added context that's still accurate
+4. Do NOT recreate the file from scratch — make surgical updates
+
+#### For REMOVED files (status `"removed"` in `removed` array):
+
+Delete the stale architecture doc file referenced by the entry's `doc` field. If any docs are deleted, regenerate the index in Step 4.
+
+**What to check when updating a stale doc:**
+- Has the file's purpose changed? → Update **Goal**
+- Have exports/functions/components changed? → Update **Composition**
+- Have imports changed? → Update **Dependencies**
+- Have downstream consumers changed? → Update **Dependents** (re-grep)
+- Any new edge cases or behavior changes? → Update **Notes**
+
+#### Doc template
+
+Each doc file MUST follow this template:
+
+```markdown
+# `{filepath}`
+
+<!--
+source: {filepath}
+category: {category}
+importance: {importance}
+-->
+
+> [← Architecture Index](../architecture.index.md)
+
+(Adjust the relative path based on nesting depth — e.g., `../../architecture.index.md` for files 2 levels deep like `src/storyboard/core/loader.js.md`)
+
+## Goal
+
+{1-2 paragraph architectural summary: what this file does, why it exists, and how it fits into the broader system. This should be readable by someone unfamiliar with the codebase.}
+
+## Composition
+
+{Detailed description of the file's structure: what it exports, key functions/components, internal organization, type signatures, parameter details. Include code samples from the actual source file to illustrate key exports, signatures, and patterns — don't just describe them in prose.}
+
+## Dependencies
+
+{List of significant imports — what this file depends on, and why}
+
+## Dependents
+
+{What depends on this file — who imports it, derived by grepping}
+
+## Notes
+
+{Any non-obvious behavior, edge cases, circular dependency considerations, or architectural decisions worth noting. Omit this section if there's nothing notable.}
+```
+
+**Rules for writing docs:**
+- Read each file's actual content before writing its doc — do NOT guess
+- The **Goal** section is the most important — it should be a clear, standalone summary (1-2 paragraphs) that anyone can read without expanding the details
+- The remaining sections (Composition, Dependencies, Dependents, Notes) are all top-level headings — do NOT wrap them in a `<details>` element
+- **Include code samples** — when describing exports, function signatures, component props, data shapes, or usage patterns, include actual code snippets from the source file. This makes docs scannable and concrete.
+- **Cross-link file references** — every time a file path is mentioned anywhere in the documentation (Goal, Composition, Dependencies, Dependents, Notes, or the index), it MUST be a markdown hyperlink to that file's architecture doc. Use relative paths from the current doc to the target doc. For example, in a doc at `.agents/architecture/src/storyboard/context.jsx.md`, a reference to the loader would be written as [`src/storyboard/core/loader.js`](./core/loader.js.md). If the referenced file has no architecture doc (e.g., low-importance files), link to the source file on GitHub or leave it as plain text with a backtick code span.
+- The "Dependents" section should be derived by grepping for imports of this file
+- For `medium` importance files, keep it concise — shorter Goal, fewer code samples
+- For `high` importance files, write a thorough Goal (2 paragraphs), comprehensive Composition with multiple code samples, and complete dependency/dependent lists
+
+### Step 4: Generate the index
+
+```bash
+.agents/skills/architecture-scanner/scan.sh --index
+```
+
+This reads the generated doc files and creates `architecture.index.md` with a categorized table of contents.
+
+Run this whenever `--stale` reports `index.status: "stale"` (including when files were changed, added, or removed).
+
+**After the script generates the index**, you MUST enhance it by adding a prose overview for each category section. Read the `categories` array in `files.json` to determine category order, display names, and priority levels. The final index should follow this structure:
+
+```markdown
+# Architecture Index
+
+> Auto-generated documentation of architecturally significant files.
+> Run `scan the codebase architecture` to regenerate.
+
+## {Category Name}
+
+{Overview paragraph(s) — see priority rules below}
+
+- [`path/to/file.js`](./path/to/file.js.md) — {one-line description}
+- [`path/to/other.js`](./path/to/other.js.md) — {one-line description}
+
+## {Next Category}
+...
+```
+
+**Category configuration** is defined in `files.json` under the `categories` array:
+
+```json
+"categories": [
+  { "id": "storyboard", "name": "Storyboard System", "priority": "critical", "order": 1 },
+  { "id": "config", "name": "Configuration", "priority": "normal", "order": 5 }
+]
+```
+
+- **`order`** — Controls the display order of categories in the index (ascending)
+- **`name`** — The display heading used in the index (`## {name}`)
+- **`priority`** — Controls the depth of the overview:
+  - **`critical`** — The overview for this category should be 2-3x longer than normal. Write 3-4 paragraphs covering key concepts, data flow, architectural decisions, and how the parts interact. Include code samples or diagrams in the overview itself when helpful. These are the categories a new contributor must deeply understand.
+  - **`normal`** — Standard 1-2 paragraph overview explaining purpose, key patterns, and relationships between files.
+
+**Rules for the index:**
+- Category sections are ordered by the `order` field in the `categories` array
+- Each category section gets an architectural overview — length determined by `priority`
+- Each link gets a brief one-line description (pulled from the file doc's Goal section)
+- **Cross-link file references** — every file path mentioned in the overview text must link to its architecture doc (same rule as per-file docs)
+- The opening architecture narrative must reflect the **full package inventory** from Step 0 (all `package.json` files), not just the packages currently documented in one category
+- Write for someone unfamiliar with the codebase — the index is the entry point to understanding the architecture
+
+### Step 5: Verify
+
+- Confirm every file in the manifest has a corresponding `.md` doc
+- Confirm every entry in `removed` had its doc file deleted
+- Confirm `architecture.index.md` links to all docs
+- Confirm every doc has a backlink to the index
+
+### Step 6: Commit
+
+```bash
+git add .agents/architecture/ .agents/skills/architecture-scanner/
+git commit -m "Update architecture documentation"
+```