@ytspar/sweetlink 1.14.0 → 1.15.0

package/README.md

@@ -181,7 +181,7 @@ pnpm sweetlink query --selector "h1"
 ### Screenshots
 
 ```bash
-# Full page screenshot
+# Full page screenshot (html2canvas, fast)
 pnpm sweetlink screenshot
 
 # Element screenshot
@@ -190,8 +190,23 @@ pnpm sweetlink screenshot --selector ".company-card"
 # Full page with custom output
 pnpm sweetlink screenshot --full-page --output page.png
 
-# Force CDP method (requires Chrome debugging)
-pnpm sweetlink screenshot --force-cdp
+# Navigate to URL before capturing
+pnpm sweetlink screenshot --url http://localhost:3000/about
+
+# Custom viewport dimensions
+pnpm sweetlink screenshot --force-cdp --width 375 --height 667
+pnpm sweetlink screenshot --force-cdp --viewport mobile
+
+# Pixel-perfect via daemon (see Persistent Daemon section)
+pnpm sweetlink screenshot --hifi
+pnpm sweetlink screenshot --responsive
+
+# Skip server readiness check
+pnpm sweetlink screenshot --no-wait
+
+# Force specific method
+pnpm sweetlink screenshot --force-cdp   # Playwright/CDP
+pnpm sweetlink screenshot --force-ws    # WebSocket/html2canvas
 ```
 
 ### DOM Queries
@@ -306,30 +321,125 @@ pnpm sweetlink click --selector ".tab" --index 2
 
 **Debugging:** Use `DEBUG=1 pnpm sweetlink click ...` to see generated JavaScript.
 
-### Network Requests (CDP Required)
+### Network Requests
 
 ```bash
-# Get all network requests
+# Get all network requests (via WebSocket bridge)
 pnpm sweetlink network
 
 # Filter by URL
 pnpm sweetlink network --filter "/api/"
+
+# Failed requests only (via daemon ring buffer)
+pnpm sweetlink network --failed
+pnpm sweetlink network --failed --last 10
+```
+
+### Schema, Outline, Accessibility
+
+```bash
+# Page schema (JSON-LD, meta tags, Open Graph)
+pnpm sweetlink schema
+
+# Document outline (heading structure)
+pnpm sweetlink outline
+
+# Accessibility audit (axe-core)
+pnpm sweetlink a11y
+
+# Web Vitals (FCP, LCP, CLS, INP)
+pnpm sweetlink vitals
+```
+
+### Server Management
+
+```bash
+# Wait for dev server to be ready (useful in scripts)
+pnpm sweetlink wait --url http://localhost:3000
+pnpm sweetlink wait --url http://localhost:3000 --wait-timeout 60000
+
+# Check server health
+pnpm sweetlink status
+
+# Clean up Sweetlink processes
+pnpm sweetlink cleanup
+pnpm sweetlink cleanup --force
+
+# Target specific app in monorepo (by branch or app name)
+pnpm sweetlink screenshot --app my-app
 ```
 
 ### Persistent Daemon (v2)
 
 Sweetlink v2 adds a persistent Playwright daemon for high-fidelity operations. The daemon auto-starts on first use and auto-stops after 30min idle.
 
+#### Auto-Start with Vite
+
+Add `daemon: true` to your Vite plugin config — the daemon starts/stops with your dev server:
+
+```typescript
+// vite.config.ts
+import { sweetlink } from '@ytspar/sweetlink/vite';
+
+export default defineConfig({
+  plugins: [sweetlink({ daemon: true })]
+  // Or with visible browser: sweetlink({ daemon: true, headed: true })
+});
+```
+
+#### Auto-Start with Dev Script
+
+Add a `dev` script that starts both your app and the daemon:
+
+```json
+{
+  "scripts": {
+    "dev": "vite",
+    "dev:daemon": "concurrently 'vite' 'sweetlink daemon start --url http://localhost:5173'"
+  }
+}
+```
+
+#### Multiple Apps (Monorepo)
+
+Each daemon is scoped by app port. Running two apps on different ports creates separate daemons:
+
+```bash
+# Terminal 1: App A on port 3000
+sweetlink daemon start --url http://localhost:3000
+# State: .sweetlink/daemon-3000.json
+
+# Terminal 2: App B on port 5173
+sweetlink daemon start --url http://localhost:5173
+# State: .sweetlink/daemon-5173.json
+
+# Commands target specific apps via --url
+sweetlink screenshot --hifi --url http://localhost:3000
+sweetlink screenshot --hifi --url http://localhost:5173
+```
+
+#### Manual Lifecycle
+
+```bash
+# Start manually (auto-starts on first --hifi command if not running)
+pnpm sweetlink daemon start --url http://localhost:5173
+pnpm sweetlink daemon start --url http://localhost:5173 --headed  # visible browser
+
+# Check status
+pnpm sweetlink daemon status
+
+# Stop (or wait for 30min idle auto-stop)
+pnpm sweetlink daemon stop
+```
+
+#### CLI Quick Reference
+
 ```bash
 # Pixel-perfect screenshot via persistent daemon (~150ms after startup)
 pnpm sweetlink screenshot --hifi
 
 # Responsive screenshots at 3 breakpoints (375/768/1280)
 pnpm sweetlink screenshot --responsive
-
-# Manage daemon lifecycle
-pnpm sweetlink daemon status
-pnpm sweetlink daemon stop
 ```
 
 ### Accessibility Snapshots & Refs
@@ -375,6 +485,38 @@ pnpm sweetlink record stop
 # Generates .sweetlink/<session-id>/viewer.html
 ```
 
+### Demo Documents
+
+Build a Markdown tutorial/proof document step-by-step (inspired by [Showboat](https://simonwillison.net/2026/Feb/10/showboat-and-rodney/)):
+
+```bash
+# Start a new demo
+pnpm sweetlink demo init "How to use the search feature"
+
+# Add narrative prose
+pnpm sweetlink demo note "First, run the tests to see them pass."
+
+# Run a command and capture output inline
+pnpm sweetlink demo exec "pnpm test -- --grep search"
+
+# Take a screenshot and embed it
+pnpm sweetlink demo screenshot --url http://localhost:5173 --caption "Search results"
+
+# Capture accessibility tree
+pnpm sweetlink demo snapshot --url http://localhost:5173
+
+# Remove last section if it's wrong
+pnpm sweetlink demo pop
+
+# Re-run all commands to verify outputs haven't changed
+pnpm sweetlink demo verify
+
+# Check status
+pnpm sweetlink demo status
+```
+
+Result: a `DEMO.md` with embedded command outputs and screenshots that serves as both documentation and a regression test.
+
 ### PR Evidence
 
 ```bash
@@ -564,19 +706,53 @@ This 15x token savings enables 10+ autonomous iterations within Claude's budget.
 
 ## Comparison with Alternatives
 
-| Feature | Sweetlink | Playwright MCP | Manual Screenshots |
-|---------|-----------|----------------|-------------------|
-| Setup Time | < 1 min | 5-10 min | N/A |
-| Token Cost | ~1,000 | ~5,000 | N/A |
-| Auto Reconnect | ✅ | ❌ | N/A |
-| Console Logs | ✅ | ✅ | ❌ |
-| Network Requests | ✅ (CDP) | ✅ | ❌ |
-| DOM Queries | ✅ | ✅ | ❌ |
-| JS Execution | ✅ | ✅ | ❌ |
-| Click Elements | ✅ | ✅ | ❌ |
-| Element Screenshots | ✅ | ✅ | ❌ |
-| Full Page Screenshots | ✅ | ✅ | ✅ |
-| Autonomous Loops | ✅ (10+) | Limited (2-3) | ❌ |
+### Screenshot & Interaction
+
+| Feature | Sweetlink | Playwright CLI | Chrome DevTools MCP | agent-browser |
+|---------|-----------|----------------|--------------------|--------------|
+| Setup | Vite/Next plugin | npm install | Chrome flag | npm install |
+| Token cost/screenshot | ~1,000 | ~5,000 | ~5,000 | ~3,000 |
+| Fast screenshots (html2canvas) | ✅ | ❌ | ❌ | ❌ |
+| Pixel-perfect screenshots | ✅ (`--hifi`) | ✅ | ✅ | ✅ |
+| Responsive (multi-viewport) | ✅ (`--responsive`) | Manual | ❌ | ❌ |
+| Device emulation (iPhone, Pixel) | ✅ (named presets) | ✅ | ❌ | ✅ |
+| @ref element interaction | ✅ (accessibility tree) | ❌ (CSS selectors) | ❌ | ✅ (Stagehand AI) |
+| DOM queries | ✅ | ✅ | ✅ | ❌ |
+| JS execution | ✅ | ✅ | ✅ | ❌ |
+| Persistent browser sessions | ✅ (daemon) | ❌ (per-run) | ✅ | ✅ |
+
+### Evidence & Reporting
+
+| Feature | Sweetlink | ProofShot | Proof | Playwright |
+|---------|-----------|-----------|-------|------------|
+| Video recording (WebM) | ✅ | ✅ | ✅ | ✅ (trace) |
+| Interactive HTML viewer | ✅ (video + overlays) | ✅ | ✅ | ✅ (trace viewer) |
+| Click ripple overlays | ✅ (canvas) | ✅ | ✅ (FFmpeg) | ❌ |
+| Console ring buffer | ✅ (always-on, 50K) | ✅ | ❌ | ❌ |
+| Network ring buffer | ✅ (always-on, 50K) | ❌ | ❌ | ✅ (HAR) |
+| Multi-language error detection | ✅ (10+ languages) | ✅ | ❌ | ❌ |
+| Snapshot diffing (a11y tree) | ✅ | ❌ | ❌ | ❌ |
+| Annotated screenshots | ✅ (@ref labels) | ✅ | ❌ | ❌ |
+| SUMMARY.md report | ✅ | ✅ | ✅ (3 formats) | ❌ |
+| Demo documents (Showboat-style) | ✅ | ❌ | ❌ | ❌ |
+| PR evidence upload | ✅ (`proof --pr`) | ✅ | ❌ | ❌ |
+| Webhook sharing | ✅ (any URL) | ❌ | ❌ | ❌ |
+| Self-contained viewer (offline) | ✅ (base64 video) | ✅ | ✅ | ✅ |
+
+### Developer Experience
+
+| Feature | Sweetlink | ProofShot | Chrome DevTools MCP |
+|---------|-----------|-----------|---------------------|
+| Devbar toolbar UI | ✅ | ❌ | ❌ |
+| Record button in browser | ✅ | ❌ | ❌ |
+| Viewer auto-opens on stop | ✅ | ❌ | ❌ |
+| Copy Report to clipboard | ✅ (CLI + viewer) | ❌ | ❌ |
+| Serve viewer on network | ✅ (`report --serve`) | ❌ | ❌ |
+| Multi-instance (monorepo) | ✅ (per-port daemon) | ❌ | ❌ |
+| Vite/Next.js auto-start | ✅ (plugin option) | ❌ | ❌ |
+| Accessibility audit (axe-core) | ✅ | ❌ | ❌ |
+| Web Vitals | ✅ | ❌ | ❌ |
+| Ruler/measurement tool | ✅ | ❌ | ❌ |
 
 ## When to Use Alternatives
 
@@ -585,22 +761,21 @@ This 15x token savings enables 10+ autonomous iterations within Claude's budget.
 **Use Sweetlink when:**
 - You're debugging/iterating on a running dev server
 - You need lightweight, token-efficient screenshots (~1000 tokens vs ~5000)
-- You want real-time console log capture
-- Your app is already running and you just need to inspect it
+- You want always-on console/network capture without "start watching"
+- You need session recording with interactive video viewer
+- You want demo documents that serve as both tutorials and regression tests
 - You're doing autonomous UI development loops (10+ iterations)
+- You want a toolbar UI in the browser for visual debugging
 
 **Use [Agent Browser](https://github.com/vercel-labs/agent-browser) when:**
-- You need full browser automation (navigation, form filling, multi-page flows)
-- You're testing production sites or external URLs
-- Sweetlink isn't integrated into the target application
+- You're testing production sites or external URLs where Sweetlink isn't installed
 - You need Stagehand's AI-powered element selection
 - You're building autonomous agents that interact with arbitrary websites
 
-**Use Playwright MCP when:**
-- You need precise, programmatic browser control
-- You're running E2E tests with assertions
-- You need browser contexts, multiple tabs, or complex scenarios
-- You require network interception or request mocking
+**Use Playwright directly when:**
+- You're writing structured E2E test suites with assertions
+- You need network interception, request mocking, or multiple browser contexts
+- You want trace viewer for debugging test failures
 
 ### Agent Browser Quick Start
 

package/claude-skills/screenshot/SKILL.md

@@ -27,7 +27,7 @@ CLI (pnpm sweetlink)
         console, network --failed, record, proof
 ```
 
-The daemon auto-starts on first `--hifi`/`snapshot` command and auto-stops after 30min idle. State file at `.sweetlink/daemon.json`.
+The daemon auto-starts on first `--hifi`/`snapshot` command and auto-stops after 30min idle. State file at `.sweetlink/daemon-{port}.json` (scoped per app port for multi-instance support).
 
 ### Prerequisites
 
@@ -344,9 +344,29 @@ pnpm sweetlink record status
 ```bash
 pnpm sweetlink daemon status
 pnpm sweetlink daemon start --url http://localhost:3000
+pnpm sweetlink daemon start --url http://localhost:3000 --headed  # visible browser
 pnpm sweetlink daemon stop
 ```
 
+### proof — Upload session evidence to GitHub PR
+
+```bash
+pnpm sweetlink proof --pr 123
+pnpm sweetlink proof --pr 123 --repo owner/repo
+```
+
+### Other useful commands
+
+```bash
+pnpm sweetlink wait --url http://localhost:3000   # Wait for server ready
+pnpm sweetlink status                              # Check server health
+pnpm sweetlink vitals                               # Get Web Vitals
+pnpm sweetlink a11y                                 # Accessibility audit
+pnpm sweetlink schema                               # Page schema (meta, OG, JSON-LD)
+pnpm sweetlink outline                              # Document heading structure
+pnpm sweetlink cleanup --force                      # Clean up Sweetlink processes
+```
+
 ## Agent-Browser Commands
 
 ### Basic Usage

package/dist/cli/sweetlink.js

@@ -1843,6 +1843,49 @@ const COMMAND_HELP = {
       pnpm sweetlink snapshot -i
       pnpm sweetlink click @e3
       pnpm sweetlink record stop`,
+    report: `  report [options]
+    Print or share the latest session report.
+
+    Modes:
+      (default)                   Print SUMMARY.md to stdout
+      --clipboard                 Copy SUMMARY.md to clipboard (pbcopy on macOS, xclip on Linux)
+      --serve                     Start a temporary HTTP server serving viewer.html
+      --webhook <url>             POST session data as JSON to a webhook URL
+
+    Options:
+      --session <dir>             Session directory (default: .sweetlink)
+
+    Examples:
+      pnpm sweetlink report
+      pnpm sweetlink report --clipboard
+      pnpm sweetlink report --serve
+      pnpm sweetlink report --webhook https://hooks.slack.com/...`,
+    demo: `  demo <subcommand> [options]
+    Build a Markdown demo document step-by-step.
+    Each command appends a section. The result is a reproducible
+    tutorial/proof document with embedded outputs and screenshots.
+
+    Subcommands:
+      init <title>              Start a new demo document
+      note <text>               Add a prose note section
+      exec <command>            Run command, capture output inline
+      screenshot [--caption]    Take hifi screenshot and embed
+      snapshot                  Capture accessibility tree inline
+      pop                       Remove the last section
+      verify                    Re-run all exec sections and verify outputs
+      status                    Show current demo state
+
+    Options:
+      --url <url>               Dev server URL (for screenshots/snapshots)
+      --output <dir>            Output directory (default: .sweetlink/demo)
+      --caption <text>          Caption for screenshot
+
+    Examples:
+      pnpm sweetlink demo init "How to use the search feature"
+      pnpm sweetlink demo note "First, navigate to the search page."
+      pnpm sweetlink demo exec "pnpm test -- --grep search"
+      pnpm sweetlink demo screenshot --caption "Search results"
+      pnpm sweetlink demo verify`,
 };
 // Aliases that map to canonical command names
 const COMMAND_ALIASES = {
@@ -1947,6 +1990,8 @@ if (hasFlag('--output-schema')) {
         'console',
         'record',
         'proof',
+        'report',
+        'demo',
     ];
     const schemaCommand = knownCommands.includes(commandType)
         ? commandType === 'measure'
@@ -2313,8 +2358,23 @@ async function handleStatusCommand() {
                 else if (subcommand === 'stop') {
                     const resp = await daemonRequest(state, 'record-stop');
                     const data = resp.data;
-                    console.log('[Sweetlink] Recording stopped.');
-                    console.log(JSON.stringify(data.manifest, null, 2));
+                    const m = data.manifest;
+                    console.log(`[Sweetlink] Recording stopped: ${m.sessionId}`);
+                    console.log(`  Duration: ${m.duration.toFixed(1)}s | Actions: ${m.commands.length}${m.video ? ' | Video: ' + m.video : ''}`);
+                    // Auto-open the viewer
+                    if (data.viewerPath && !hasFlag('--no-open')) {
+                        console.log(`  Viewer: ${data.viewerPath}`);
+                        const { execFile } = await import('child_process');
+                        const openCmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+                        execFile(openCmd, [data.viewerPath], (err) => {
+                            if (err)
+                                console.error('  Could not open viewer:', err.message);
+                        });
+                        console.log(`  Opened in browser.`);
+                    }
+                    else if (data.viewerPath) {
+                        console.log(`  Viewer: ${data.viewerPath}`);
+                    }
                     result = data;
                 }
                 else {
@@ -2330,6 +2390,237 @@ async function handleStatusCommand() {
                 }
                 break;
             }
+            case 'report': {
+                const sessionDirArg = getArg('--session') ?? '.sweetlink';
+                // Find latest session directory
+                if (!fs.existsSync(sessionDirArg)) {
+                    console.error(`[Sweetlink] Session directory not found: ${sessionDirArg}`);
+                    process.exit(1);
+                }
+                const reportSessions = fs.readdirSync(sessionDirArg)
+                    .filter((f) => f.startsWith('session-'))
+                    .sort()
+                    .reverse();
+                if (reportSessions.length === 0) {
+                    console.error('[Sweetlink] No session found. Run `record start` and `record stop` first.');
+                    process.exit(1);
+                }
+                const reportSessionDir = path.join(sessionDirArg, reportSessions[0]);
+                if (hasFlag('--clipboard')) {
+                    // Copy SUMMARY.md to clipboard
+                    const summaryPath = path.join(reportSessionDir, 'SUMMARY.md');
+                    if (!fs.existsSync(summaryPath)) {
+                        console.error(`[Sweetlink] SUMMARY.md not found at ${summaryPath}`);
+                        process.exit(1);
+                    }
+                    const summaryContent = fs.readFileSync(summaryPath, 'utf-8');
+                    const { execFileSync } = await import('child_process');
+                    const clipCmd = process.platform === 'darwin' ? 'pbcopy' : 'xclip';
+                    const clipArgs = process.platform === 'darwin' ? [] : ['-selection', 'clipboard'];
+                    try {
+                        execFileSync(clipCmd, clipArgs, { input: summaryContent });
+                        console.log('[Sweetlink] SUMMARY.md copied to clipboard.');
+                    }
+                    catch (err) {
+                        console.error(`[Sweetlink] Failed to copy to clipboard (${clipCmd}):`, err instanceof Error ? err.message : err);
+                        process.exit(1);
+                    }
+                    result = { mode: 'clipboard', session: reportSessions[0] };
+                }
+                else if (hasFlag('--serve')) {
+                    // Serve viewer.html on a random port
+                    const viewerPath = path.join(reportSessionDir, 'viewer.html');
+                    if (!fs.existsSync(viewerPath)) {
+                        console.error(`[Sweetlink] viewer.html not found at ${viewerPath}`);
+                        process.exit(1);
+                    }
+                    const viewerContent = fs.readFileSync(viewerPath, 'utf-8');
+                    const http = await import('http');
+                    const port = 10000 + Math.floor(Math.random() * 50000);
+                    const server = http.createServer((_req, res) => {
+                        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                        res.end(viewerContent);
+                    });
+                    server.listen(port, '0.0.0.0', () => {
+                        const os = require('os');
+                        const nets = os.networkInterfaces();
+                        let lanIp = 'localhost';
+                        for (const name of Object.keys(nets)) {
+                            for (const net of nets[name]) {
+                                if (net.family === 'IPv4' && !net.internal) {
+                                    lanIp = net.address;
+                                    break;
+                                }
+                            }
+                            if (lanIp !== 'localhost')
+                                break;
+                        }
+                        console.log(`[Sweetlink] Serving viewer at:`);
+                        console.log(`  Local:   http://localhost:${port}`);
+                        console.log(`  Network: http://${lanIp}:${port}`);
+                        console.log('  Press Ctrl+C to stop.');
+                    });
+                    // Keep running until Ctrl+C
+                    await new Promise(() => { });
+                }
+                else if (getArg('--webhook')) {
+                    // POST session data to webhook
+                    const webhookUrl = getArg('--webhook');
+                    const manifestPath = path.join(reportSessionDir, 'sweetlink-session.json');
+                    const summaryPath = path.join(reportSessionDir, 'SUMMARY.md');
+                    if (!fs.existsSync(manifestPath)) {
+                        console.error(`[Sweetlink] Manifest not found at ${manifestPath}`);
+                        process.exit(1);
+                    }
+                    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                    const summary = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, 'utf-8') : '';
+                    const payload = { summary, manifest };
+                    // Include viewer HTML for Slack/Discord webhooks
+                    if (/slack|discord/i.test(webhookUrl)) {
+                        const viewerPath = path.join(reportSessionDir, 'viewer.html');
+                        if (fs.existsSync(viewerPath)) {
+                            payload.viewerHtml = fs.readFileSync(viewerPath, 'utf-8');
+                        }
+                    }
+                    const body = JSON.stringify(payload);
+                    const res = await fetch(webhookUrl, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body,
+                    });
+                    if (res.ok) {
+                        console.log(`[Sweetlink] Report posted to ${webhookUrl} (${res.status})`);
+                    }
+                    else {
+                        console.error(`[Sweetlink] Webhook failed: ${res.status} ${res.statusText}`);
+                        process.exit(1);
+                    }
+                    result = { mode: 'webhook', url: webhookUrl, status: res.status };
+                }
+                else {
+                    // Default: print SUMMARY.md to stdout
+                    const summaryPath = path.join(reportSessionDir, 'SUMMARY.md');
+                    if (!fs.existsSync(summaryPath)) {
+                        console.error(`[Sweetlink] SUMMARY.md not found at ${summaryPath}`);
+                        process.exit(1);
+                    }
+                    const summaryContent = fs.readFileSync(summaryPath, 'utf-8');
+                    process.stdout.write(summaryContent);
+                    result = { mode: 'stdout', session: reportSessions[0] };
+                }
+                break;
+            }
+            case 'demo': {
+                const sub = args[1];
+                const projRoot = findProjectRoot();
+                const demoDir = getArg('--output') ?? path.join(projRoot, '.sweetlink', 'demo');
+                const stateFile = path.join(demoDir, 'demo-state.json');
+                // Lazy import demo module
+                const demoMod = await import('../daemon/demo.js');
+                if (sub === 'init') {
+                    const title = args[2];
+                    if (!title) {
+                        console.error('[Sweetlink] Error: demo init requires a title');
+                        process.exit(1);
+                    }
+                    const demoState = await demoMod.initDemo(title, demoDir, { url: getArg('--url') });
+                    await demoMod.writeDemo(demoState);
+                    console.log(`[Sweetlink] Demo initialized: ${demoState.filePath}`);
+                    result = { filePath: demoState.filePath };
+                }
+                else if (sub === 'note') {
+                    const text = args.slice(2).join(' ');
+                    if (!text) {
+                        console.error('[Sweetlink] Error: demo note requires text');
+                        process.exit(1);
+                    }
+                    const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                    const updated = demoMod.addNote(state, text);
+                    await demoMod.writeDemo(updated);
+                    console.log(`[Sweetlink] Note added (${updated.sections.length} sections)`);
+                    result = { sections: updated.sections.length };
+                }
+                else if (sub === 'exec') {
+                    const cmd = args.slice(2).join(' ');
+                    if (!cmd) {
+                        console.error('[Sweetlink] Error: demo exec requires a command');
+                        process.exit(1);
+                    }
+                    const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                    const updated = await demoMod.addExec(state, cmd, []);
+                    await demoMod.writeDemo(updated);
+                    const lastSection = updated.sections[updated.sections.length - 1];
+                    console.log(`[Sweetlink] Exec added: ${cmd} (exit ${lastSection.exitCode ?? 0})`);
+                    result = { sections: updated.sections.length, exitCode: lastSection.exitCode };
+                }
+                else if (sub === 'screenshot') {
+                    const targetUrl = getArg('--url') ?? 'http://localhost:3000';
+                    const caption = getArg('--caption') ?? 'Screenshot';
+                    const daemonState = await ensureDaemon(projRoot, targetUrl);
+                    const resp = await daemonRequest(daemonState, 'screenshot', {});
+                    const data = resp.data;
+                    const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                    const updated = await demoMod.addScreenshot(state, Buffer.from(data.screenshot, 'base64'), caption);
+                    await demoMod.writeDemo(updated);
+                    console.log(`[Sweetlink] Screenshot added: ${caption}`);
+                    result = { sections: updated.sections.length };
+                }
+                else if (sub === 'snapshot') {
+                    const targetUrl = getArg('--url') ?? 'http://localhost:3000';
+                    const daemonState = await ensureDaemon(projRoot, targetUrl);
+                    const resp = await daemonRequest(daemonState, 'snapshot', { interactive: true });
+                    const data = resp.data;
+                    const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                    const updated = demoMod.addSnapshot(state, data.tree);
+                    await demoMod.writeDemo(updated);
+                    console.log(`[Sweetlink] Snapshot added (${updated.sections.length} sections)`);
+                    result = { sections: updated.sections.length };
+                }
+                else if (sub === 'pop') {
+                    const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                    const updated = demoMod.popSection(state);
+                    await demoMod.writeDemo(updated);
+                    console.log(`[Sweetlink] Last section removed (${updated.sections.length} remaining)`);
+                    result = { sections: updated.sections.length };
+                }
+                else if (sub === 'verify') {
+                    const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                    const verifyResult = await demoMod.verifyDemo(state);
+                    if (verifyResult.passed) {
+                        console.log('[Sweetlink] Demo verified: all outputs match');
+                    }
+                    else {
+                        console.log(`[Sweetlink] Demo verification FAILED: ${verifyResult.failures.length} mismatch(es)`);
+                        for (const f of verifyResult.failures) {
+                            console.log(`  Section ${f.index}: ${f.command}`);
+                            console.log(`    Expected: ${f.expected.substring(0, 80)}...`);
+                            console.log(`    Actual:   ${f.actual.substring(0, 80)}...`);
+                        }
+                    }
+                    result = verifyResult;
+                }
+                else {
+                    // status
+                    if (fs.existsSync(stateFile)) {
+                        const state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+                        console.log(`[Sweetlink] Demo: "${state.title}" (${state.sections.length} sections)`);
+                        console.log(`  File: ${state.filePath}`);
+                        for (const s of state.sections) {
+                            const preview = s.type === 'note' ? s.content.substring(0, 60) :
+                                s.type === 'exec' ? `$ ${s.command}` :
+                                    s.type === 'screenshot' ? `[image] ${s.screenshotFile}` :
+                                        '[snapshot]';
+                            console.log(`  ${s.type.padEnd(12)} ${preview}`);
+                        }
+                        result = state;
+                    }
+                    else {
+                        console.log('[Sweetlink] No demo in progress. Run `demo init <title>` to start.');
+                        result = null;
+                    }
+                }
+                break;
+            }
             case 'daemon': {
                 const subcommand = args[1];
                 const projRoot = findProjectRoot();
@@ -2340,7 +2631,8 @@ async function handleStatusCommand() {
                 }
                 else if (subcommand === 'start') {
                     const targetUrl = getArg('--url') ?? 'http://localhost:3000';
-                    const state = await ensureDaemon(projRoot, targetUrl);
+                    const headedFlag = hasFlag('--headed');
+                    const state = await ensureDaemon(projRoot, targetUrl, { headed: headedFlag });
                     console.log(`[Sweetlink] Daemon running on port ${state.port} (PID: ${state.pid})`);
                     result = {
                         running: true,