@dfosco/storyboard 0.5.0-alpha.0

package/scaffold/codex/config.toml

@@ -0,0 +1,246 @@
+model = "o4-mini"
+
+developer_instructions = """
+
+# Terminal Agent Context
+
+Before processing ANY user prompt, read the terminal config file for this session.
+
+## Step 1: Read terminal config
+
+Your widget ID is available via `$STORYBOARD_WIDGET_ID`. Use it to read your config directly:
+```bash
+cat .storyboard/terminals/${STORYBOARD_WIDGET_ID}.json
+```
+
+If the env var is empty, source it from the terminal env file first:
+```bash
+# Find the env file for this tmux session
+ENV_FILE=$(ls -t .storyboard/terminals/*.env 2>/dev/null | head -1)
+if [ -n "$ENV_FILE" ]; then source "$ENV_FILE"; fi
+cat .storyboard/terminals/${STORYBOARD_WIDGET_ID}.json
+```
+
+If not found, tell the user that's the case -- do not pick a random one.
+
+The config file contains everything you need — no additional API calls required:
+
+```json
+{
+  "widgetId": "terminal-abc123",
+  "canvasId": "storyboarding/my-canvas",
+  "branch": "4.2.0--terminal-agents",
+  "worktree": "4.2.0--terminal-agents",
+  "devDomain": "storyboard-core",
+  "serverUrl": "http://localhost:1269",
+  "workingDirectory": "/path/to/worktree",
+  "connectedWidgets": [
+    {
+      "id": "sticky-def456",
+      "type": "sticky-note",
+      "props": { "text": "Build a login form", "color": "yellow" }
+    },
+    {
+      "id": "markdown-ghi789",
+      "type": "markdown",
+      "props": { "content": "# Requirements\n- Email + password\n- OAuth support" }
+    }
+  ]
+}
+```
+
+## Step 2: Use connected widget context
+
+The `connectedWidgets` array contains the FULL props of every widget connected to this terminal. These are your **partners** (also known as **buddies**). This is your highest priority context.
+
+When the user says "your partner", "your buddy", or "connected widget" — they mean widgets in your `connectedWidgets` array. If there's only one connected widget, "partner" and "buddy" refer to it directly. If there are multiple, ask which one.
+
+- **sticky-note**: `props.text` — instructions, notes, or requirements
+- **markdown**: `props.content` — documentation, specs, or prose
+- **image**: `props.src` — image filename at `assets/canvas/images/{props.src}`
+- **story**: `props.storyId` + `props.exportName` — component to work with
+- **link-preview**: `props.url` — external reference
+- **prototype**: `props.src` — prototype path
+- **terminal** / **agent**: another terminal or agent you can message (see Step 6)
+
+Interpret the user's prompt in light of these connected widgets.
+
+## Step 3: Prefer CLI commands for canvas operations
+
+**Always prefer `npx storyboard` CLI commands over HTTP API calls.** CLI commands run directly in the worktree and resolve the dev server automatically — no port numbers or URLs needed.
+
+### Reading canvas state
+```bash
+npx storyboard canvas read <canvas-name> --json
+npx storyboard canvas read <canvas-name> --id <widget-id> --json
+```
+
+### Updating a widget
+```bash
+# Update text on a sticky note
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --text "New text"
+
+# Update markdown content
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --content "# New heading"
+
+# Update arbitrary props
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --props '{"key":"value"}'
+
+# Move a widget
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --x 100 --y 200
+
+# Shorthand flags: --text, --content, --src, --url, --color
+```
+
+### Adding a widget
+```bash
+npx storyboard canvas add sticky-note --canvas <canvas-name> --props '{"text":"Hello"}'
+npx storyboard canvas add markdown --canvas <canvas-name> --x 100 --y 200
+```
+
+**Why CLI over API:** The CLI resolves the correct dev server port automatically via the Caddy proxy or ports.json. You never need to know the port number. All commands work from any worktree directory.
+
+## Step 4: Connect every widget you create
+
+**After creating ANY widget on the canvas, always create a connector from the terminal widget to the new widget.** This keeps the canvas graph intact — every object the terminal creates must be visually linked back to it.
+
+The connector API is HTTP-only (CLI doesn't support connectors yet). Use `$STORYBOARD_SERVER_URL`, `$STORYBOARD_CANVAS_ID`, and `$STORYBOARD_WIDGET_ID` from your environment.
+
+### Example: Create a sticky note and connect it
+
+```bash
+# 1. Create the widget — capture its ID from the response
+RESPONSE=$(curl -s -X POST "${STORYBOARD_SERVER_URL}/_storyboard/canvas/${STORYBOARD_CANVAS_ID}/widgets" \
+  -H "Content-Type: application/json" \
+  -d '{"type":"sticky-note","props":{"text":"Hello from terminal"}}')
+
+NEW_ID=$(echo "$RESPONSE" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+# 2. Connect terminal → new widget
+curl -s -X POST "${STORYBOARD_SERVER_URL}/_storyboard/canvas/connector" \
+  -H "Content-Type: application/json" \
+  -d "{\"name\":\"${STORYBOARD_CANVAS_ID}\",\"startWidgetId\":\"${STORYBOARD_WIDGET_ID}\",\"endWidgetId\":\"${NEW_ID}\",\"startAnchor\":\"right\",\"endAnchor\":\"left\"}"
+```
+
+### Example: Create a markdown block and connect it
+
+```bash
+RESPONSE=$(curl -s -X POST "${STORYBOARD_SERVER_URL}/_storyboard/canvas/${STORYBOARD_CANVAS_ID}/widgets" \
+  -H "Content-Type: application/json" \
+  -d '{"type":"markdown","props":{"content":"# Plan\n- Step 1\n- Step 2"}}')
+
+NEW_ID=$(echo "$RESPONSE" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+curl -s -X POST "${STORYBOARD_SERVER_URL}/_storyboard/canvas/connector" \
+  -H "Content-Type: application/json" \
+  -d "{\"name\":\"${STORYBOARD_CANVAS_ID}\",\"startWidgetId\":\"${STORYBOARD_WIDGET_ID}\",\"endWidgetId\":\"${NEW_ID}\",\"startAnchor\":\"right\",\"endAnchor\":\"left\"}"
+```
+
+### Pattern: 1→n — terminal creates multiple widgets
+
+When creating several widgets, connect each one back to the terminal individually:
+
+```bash
+for i in 1 2 3; do
+  RESPONSE=$(curl -s -X POST "${STORYBOARD_SERVER_URL}/_storyboard/canvas/${STORYBOARD_CANVAS_ID}/widgets" \
+    -H "Content-Type: application/json" \
+    -d "{\"type\":\"sticky-note\",\"props\":{\"text\":\"Task $i\"}}")
+
+  NEW_ID=$(echo "$RESPONSE" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+  curl -s -X POST "${STORYBOARD_SERVER_URL}/_storyboard/canvas/connector" \
+    -H "Content-Type: application/json" \
+    -d "{\"name\":\"${STORYBOARD_CANVAS_ID}\",\"startWidgetId\":\"${STORYBOARD_WIDGET_ID}\",\"endWidgetId\":\"${NEW_ID}\",\"startAnchor\":\"right\",\"endAnchor\":\"left\"}"
+done
+```
+
+**Anchor guidance:** Use `"right"` → `"left"` by default (terminal on left, new widgets to the right). Adjust if the spatial layout calls for a different direction.
+
+> For the full connector API (delete, direction, validation rules), see the **Connectors** section in the canvas skill docs.
+
+## Step 5: Signal completion
+
+When your task is complete:
+```bash
+npx storyboard agent signal --status done --message "Brief summary"
+```
+
+On failure:
+```bash
+npx storyboard agent signal --status error --message "What went wrong"
+```
+
+## Step 6: Messaging with connected terminals
+
+If your terminal config has a `messaging` section, you can exchange messages with connected terminal/agent peers. Check your config:
+
+```bash
+cat .storyboard/terminals/${STORYBOARD_WIDGET_ID}.json | jq '.messaging'
+```
+
+### Send a message to a peer
+```bash
+npx storyboard terminal send <peerWidgetId> "Your message here"
+```
+
+Or auto-resolve the connected peer (only works with a single connected terminal):
+```bash
+npx storyboard terminal send --connected "Your message here"
+```
+
+### Save your output for peers to read
+
+**IMPORTANT: You MUST save your output after every response when messaging is enabled.** This is how your peer reads what you said — without it, they see `null`.
+
+```bash
+npx storyboard terminal output --summary "One-line summary" --content "Your full response text here"
+```
+
+Peers read your output from your config file:
+```bash
+cat .storyboard/terminals/${STORYBOARD_WIDGET_ID}.json | jq '.latestOutput.content'
+```
+
+### Check a peer's status
+```bash
+npx storyboard terminal status <peerWidgetId>
+```
+
+### Read a peer's latest output
+```bash
+cat .storyboard/terminals/<peerWidgetId>.json | jq '.latestOutput'
+```
+
+### Messaging modes
+Messaging is controlled by the user via the 💬 menu on terminal widgets:
+- **No messaging** — you cannot send or receive (default)
+- **One-way →** — only one direction is allowed
+- **Two-way ↔** — both terminals can send freely
+
+Check your `messaging.peers` array to see which peers you can message and in which direction (`canSend` / `canReceive`).
+
+**IMPORTANT:**
+- NEVER write directly to `.canvas.jsonl` files — use the canvas CLI or server API
+- **Prefer CLI commands** (`npx storyboard canvas ...`) over direct HTTP calls — they resolve ports automatically
+- Only fall back to HTTP API (`{serverUrl}/_storyboard/canvas/`) if the CLI doesn't support the operation
+- Environment variables `$STORYBOARD_WIDGET_ID`, `$STORYBOARD_CANVAS_ID`, `$STORYBOARD_BRANCH`, `$STORYBOARD_SERVER_URL` are available in the shell
+
+## HTTP API Reference (fallback only)
+
+If the CLI fails, use these endpoints. The `serverUrl` is in your terminal config or `$STORYBOARD_SERVER_URL`.
+
+### Safe: Update a single widget (PATCH)
+```bash
+curl -s -X PATCH "${STORYBOARD_SERVER_URL}/_storyboard/canvas/widget" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"<canvasId>","widgetId":"<widgetId>","props":{"text":"new value"}}'
+```
+
+### Safe: Read canvas state (GET)
+```bash
+curl -s "${STORYBOARD_SERVER_URL}/_storyboard/canvas/<canvasId>"
+```
+
+### ⚠️ NEVER use `PUT /_storyboard/canvas/update` with a `widgets` array
+That endpoint **replaces ALL widgets** in the canvas. Sending one widget = deleting everything else.
+"""

package/scaffold/deploy.yml

@@ -0,0 +1,103 @@
+name: Deploy (main)
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Deploy to gh-pages (root)
+        run: |
+          set -e
+
+          # Configure git
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Clone gh-pages branch (or create it)
+          git fetch origin gh-pages:gh-pages 2>/dev/null || true
+          DEPLOY_DIR=$(mktemp -d)
+          if git show-ref --verify --quiet refs/heads/gh-pages; then
+            git worktree add "$DEPLOY_DIR" gh-pages
+          else
+            git worktree add --orphan "$DEPLOY_DIR" gh-pages
+            rm -rf "$DEPLOY_DIR"/*
+          fi
+
+          # Remove root-level files only (preserve branch--* folders)
+          cd "$DEPLOY_DIR"
+          find . -maxdepth 1 ! -name '.' ! -name '.git' ! -name 'branch--*' -exec rm -rf {} +
+
+          # Copy new build output (includes CNAME if customDomain is set)
+          cp -r "$GITHUB_WORKSPACE/dist/." .
+
+          # Ensure .nojekyll exists at root (GitHub Pages ignores _-prefixed dirs without it)
+          touch .nojekyll
+
+          # Commit and push
+          git add -A
+          git diff --cached --quiet && echo "No changes to deploy" && exit 0
+          git commit -m "Deploy main @ $(echo $GITHUB_SHA | head -c 7)"
+          git push origin gh-pages
+
+      - name: Generate branch manifest
+        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
+
+          cd "$DEPLOY_DIR"
+
+          # Build branches.json from branch--* folders
+          echo '[' > branches.json
+          FIRST=true
+          for dir in branch--*/; do
+            [ -d "$dir" ] || continue
+            FOLDER="${dir%/}"
+            # Extract branch name: strip "branch--" prefix
+            BRANCH="${FOLDER#branch--}"
+            if [ "$FIRST" = true ]; then
+              FIRST=false
+            else
+              echo ',' >> branches.json
+            fi
+            printf '  {"folder":"%s","branch":"%s"}' "$FOLDER" "$BRANCH" >> branches.json
+          done
+          echo '' >> branches.json
+          echo ']' >> branches.json
+
+          git add branches.json
+          git diff --cached --quiet && echo "Manifest 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 branch manifest"
+          git push origin gh-pages

package/scaffold/githooks/pre-push

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+#
+# pre-push pipeline — runs checks and generators before pushing.
+#
+# Pipeline stages run in order. Each stage can:
+#   - Pass silently (exit 0)
+#   - Fail and block the push (exit 1) — all changes are reverted
+#   - Generate files that get auto-committed
+#
+# Add new stages by defining a function and adding it to STAGES.
+#
+# Installed by: storyboard setup / storyboard-scaffold
+#
+
+set -euo pipefail
+
+# ── Configuration ─────────────────────────────────────────────────
+# Ordered list of stages. Add new stages here.
+# Note: snapshot generation moved to CI (snapshots.yml workflow).
+STAGES=(
+)
+
+# ── Helpers ───────────────────────────────────────────────────────
+
+SNAPSHOT_SHA=""
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+DIM='\033[2m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+log()  { echo -e "${DIM}[pre-push]${RESET} $*"; }
+ok()   { echo -e "${DIM}[pre-push]${RESET} ${GREEN}✓${RESET} $*"; }
+fail() { echo -e "${DIM}[pre-push]${RESET} ${RED}✗${RESET} $*"; }
+
+save_snapshot() {
+  SNAPSHOT_SHA=$(git rev-parse HEAD)
+}
+
+revert_snapshot() {
+  if [ -n "$SNAPSHOT_SHA" ] && [ "$(git rev-parse HEAD)" != "$SNAPSHOT_SHA" ]; then
+    log "Reverting auto-committed changes..."
+    git reset --soft "$SNAPSHOT_SHA" 2>/dev/null || true
+  fi
+}
+
+auto_commit() {
+  local label="$1"
+  shift
+  local paths=("$@")
+
+  local changes=""
+  for p in "${paths[@]}"; do
+    changes+=$(git status --porcelain "$p" 2>/dev/null || true)
+  done
+
+  if [ -n "$changes" ]; then
+    git add "${paths[@]}" 2>/dev/null
+    git commit -m "chore: ${label}" --no-verify --allow-empty 2>/dev/null
+    ok "${label} (committed)"
+    return 0
+  fi
+  return 1
+}
+
+# ── Stages ────────────────────────────────────────────────────────
+
+stage_test() {
+  if [ ! -f "vitest.config.js" ] && [ ! -f "vitest.config.ts" ]; then return 0; fi
+  if ! command -v npx &>/dev/null; then return 0; fi
+
+  log "Running tests..."
+  if npx --no-install vitest run --reporter=dot 2>&1; then
+    ok "Tests passed"
+  else
+    fail "Tests failed — push blocked"
+    return 1
+  fi
+}
+
+stage_snapshots() {
+  local canvas_files
+  canvas_files=$(find src/canvas -name "*.canvas.jsonl" 2>/dev/null | head -1)
+  [ -z "$canvas_files" ] && return 0
+
+  if ! npx --no-install storyboard snapshots 2>&1; then
+    log "Snapshot generation skipped"
+    return 0
+  fi
+
+  auto_commit "update canvas snapshots" \
+    "assets/canvas/snapshots/" \
+    "assets/canvas/images/" \
+    "src/canvas/" \
+    || true
+}
+
+# ── Pipeline runner ───────────────────────────────────────────────
+
+main() {
+  save_snapshot
+
+  for stage in "${STAGES[@]}"; do
+    if ! "$stage"; then
+      revert_snapshot
+      fail "${BOLD}Push aborted${RESET} by ${stage}"
+      exit 1
+    fi
+  done
+
+  log "${GREEN}All stages passed${RESET}"
+}
+
+main

package/scaffold/gitignore

@@ -0,0 +1,64 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/packages/**/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+/dist
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.playwright-profile
+
+.github/skills/_archive
+.github/skills/primer-primitives
+.github/skills/primer-components-catalog
+.github/skills/primer-screenshot-builder
+.github/skills/primer-screenshot-patterns
+.github/skills/primer-url-builder
+.github/skills/playwright-cli
+.worktrees
+# Agent symlinks are build targets — source of truth is .agents/agents/
+# storyboard setup creates symlinks for Copilot CLI and Claude Code
+.github/agents/_buddy-rails.md
+.github/agents/_buddy.md
+.github/agents/terminal-agent.md
+.github/agents/prompt-agent.md
+.claude/agents/
+_*.md
+
+# Compiled UI bundle (built before publish, not tracked in git)
+packages/core/dist/storyboard-ui.*
+
+.clips
+
+# Agent Browser
+agent-browser.json
+
+# Selected widgets bridge (real-time canvas selection for Copilot)
+.storyboard
+
+# Private canvas images (tilde prefix = not committed)
+src/canvas/images/~*
+assets/canvas/images/~*
+assets/canvas/snapshots/~*
+assets/.storyboard-public/terminal-snapshots/~*
+.sync-target
+
+# Integration test results (ephemeral local artifacts)
+test-results/

package/scaffold/manifest.json

@@ -0,0 +1,56 @@
+{
+  "files": [
+    {
+      "source": "scaffold/AGENTS.md",
+      "target": "AGENTS.md",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/gitignore",
+      "target": ".gitignore",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/storyboard.config.json",
+      "target": "storyboard.config.json",
+      "mode": "scaffold"
+    },
+    {
+      "source": "scaffold/scripts/link.sh",
+      "target": "scripts/link.sh",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/scripts/unlink.sh",
+      "target": "scripts/unlink.sh",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/skills/",
+      "target": ".github/skills/",
+      "mode": "updateable",
+      "directory": true
+    },
+    {
+      "source": "scaffold/deploy.yml",
+      "target": ".github/workflows/deploy.yml",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/preview.yml",
+      "target": ".github/workflows/preview.yml",
+      "mode": "updateable"
+    },
+    {
+      "source": "scaffold/githooks/",
+      "target": ".githooks/",
+      "mode": "updateable",
+      "directory": true
+    },
+    {
+      "source": "scaffold/codex/config.toml",
+      "target": ".codex/config.toml",
+      "mode": "updateable"
+    }
+  ]
+}