hop2 0.9.0 → 0.10.0

package/README.md

@@ -1,10 +1,10 @@
 # 🐰 hop
 
-**Hop into your terminal from anywhere in the world.**
+**Terminal access for humans and agents.**
 
-Access your Mac's terminal from your phone, tablet, or any browser — secured with password + 2FA, tunneled through Cloudflare.
+Hop gives you secure browser access to local terminals and a built-in MCP server for creating, driving, and auditing agent sessions over the same runtime.
 
-> **🍎 macOS/Linux** — Requires cloudflared for tunneling
+> **macOS/Linux** — Requires cloudflared for tunneling
 
 ```
            (\(\ 
@@ -12,33 +12,42 @@ Access your Mac's terminal from your phone, tablet, or any browser — secured w
            o_(")(")
 ```
 
-## ✨ Features
+## Why Hop
 
-- 🔐 **Password + 2FA** — Optional password plus TOTP (required for custom domains)
-- 🌍 **Access Anywhere** — Cloudflare tunnel, no port forwarding
-- 🌐 **Custom Domains + Multi‑User** — Share subdomains with per‑user credentials
-- 📱 **Mobile Virtual Keyboard** — Custom keyboard with Esc, Ctrl, Alt, arrows, and more
-- ⌨️ **Native Keyboard Support** — Tap the blue button for dictation, spellcheck & autocomplete
-- 🪟 **Multi-Session** — Create and switch between named sessions
-- 🔌 **Port Sessions** — Proxy a local HTTP/WS service via hop
-- 🔄 **Quick Session Switching** — Floating menu to switch sessions without leaving the terminal
-- 🎨 **Modern UI** — Clean, minimal iOS-style design
-- ⚡ **Auto-Attach** — Multiple terminals share the same tunnel
+- **Browser terminal from anywhere** — Tunnel through Cloudflare with no port forwarding
+- **MCP-native terminal control** — Claude Code, Codex, Gemini, Cursor, and other MCP clients can create terminals, stream output, and send input through Hop
+- **One runtime for humans and agents** — The browser UI, local CLI, and MCP server operate on the same sessions
+- **Operationally useful primitives** — Named sessions, port sessions, auto-attach, and explicit workspace snapshots
+- **Auditability built in** — Per-session logs, isolated agent history, and TUI-aware capture defaults
+- **Security when you need it** — Password + 2FA, custom domains, and multi-user support
 
 ## 🚀 Quick Install
 
+Most users only need the npm install. Source install is mainly for development or local hacking.
+
 ### From npm (easiest)
 
 ```bash
 npm install -g hop2
 ```
 
-Then just run:
+This installs:
+- `hop` — main CLI / daemon / browser terminal entrypoint
+- `hop-mcp` — MCP server exposing Hop terminals and sessions
+- `hop-mcp-setup` — MCP client auto-config helper
+
+Then:
 ```bash
 hop
 ```
 
-### One-liner from source
+If you want agent access too:
+
+```bash
+hop-mcp-setup
+```
+
+### From source (one-liner)
 
 ```bash
 git clone https://github.com/jzthree/hop.git ~/.hop && \
@@ -46,7 +55,7 @@ cd ~/.hop && npm install && \
 sudo ln -sf ~/.hop/hop /usr/local/bin/hop
 ```
 
-### Manual Install from source
+### From source (manual)
 
 ```bash
 # Clone the repo
@@ -64,114 +73,202 @@ echo 'export PATH="$HOME/.hop:$PATH"' >> ~/.zshrc
 source ~/.zshrc
 ```
 
-## 🐰 Usage
+## Quick Start
 
+### Browser access
 ```bash
-# Start hopping!
 hop
+```
+
+First run:
+1. Optionally set a password with `hop password set`
+2. Scan the authenticator QR code
+3. Note the URL
+4. Press Enter to start your first local terminal
+
+Then open the URL from another device, sign in, and pick or create a session.
 
-# Use iTerm control mode for local session
-hop --iterm
+### MCP access
+
+```bash
+hop
+hop-mcp-setup
 ```
 
-**First time:**
-1. (Optional) Set a password: `hop password set`
-2. Scan the QR code with your authenticator app (Google Authenticator, Authy, 1Password, etc.)
-3. Note the URL displayed
-4. Press Enter to start your local session
+Then restart your MCP client. `hop-mcp-setup` auto-detects and configures supported clients such as Claude Code, Claude Desktop, Cursor, Gemini CLI, Codex CLI, VS Code / Copilot, and Antigravity.
+
+Typical use cases:
+- Launch a dedicated Claude Code / Codex / Gemini terminal and drive it over multiple turns
+- Create isolated agent sessions with per-session history and audit logs
+- Read terminal output incrementally instead of screen-scraping a browser
+- Build higher-level agent workflows on top of stable terminal/session primitives
+
+For full MCP usage, tools, and subagent workflows, see [README-MCP.md](./README-MCP.md).
 
-**From your phone:**
-1. Open the URL in your browser
-2. Enter your password (if enabled) and 6‑digit code
-3. Pick or create a session
-4. 🐰 You're in! Use the virtual keyboard for terminal keys, or tap the blue button for native input
+## Everyday Workflows
 
-## 🪟 Sessions
+### Create and Reuse Sessions
 
 Create multiple independent terminal sessions from the Session Picker (`/sessions`):
 
-- **Create**: Type a name and click Create
-- **Join**: Click Join on any existing session
-- **Sessions are shared**: Multiple devices can view the same session
+- Create a new named shell session
+- Join any existing session
+- Share a live session between multiple devices
+- Save selected live terminal sessions into a named workspace when you want to reuse them later
+
+Scratch sessions stay live-only unless you explicitly save them into a workspace. To save reusable definitions from the CLI:
 
-You can also create **Port Sessions** that proxy to a local HTTP/WS service on your machine.
-Use the Session Picker or:
 ```bash
-hop session add myapp --port 3000
+hop session add workspace-shell --cwd ~/src/my-project --workspace dev
+hop session add myapp --port 3000 --workspace dev
 ```
 
-## 🌐 Custom Domains & Multi‑User
-
-### Admin (your machine)
-1. Set a password (required for custom domains):
-   ```bash
-   hop password set
-   ```
-2. Configure your domain:
-   ```bash
-   hop domain hop.yourdomain.com
-   ```
-3. Add a user + export credentials:
-   ```bash
-   hop user add alice
-   hop user export alice
-   ```
-4. Send the exported folder to the user.
-
-### User (their machine)
+Use `hop workspace save <name>` to snapshot selected live terminal sessions, or `hop session add ... --workspace <name>` when you want to define a reusable terminal or port entry directly.
+
+Inspect or remove saved workspace definitions with:
+
 ```bash
-npm install -g hop2
-hop client ./credentials.json
+hop workspace show dev
+hop workspace delete dev
 ```
-First run prompts them to set a password + scan a TOTP QR code.  
-They then log in at their URL, e.g. `https://alice.hop.yourdomain.com`.
 
-## 📱 Mobile Keyboard
+### Drive a Subagent Over MCP
+
+Use one dedicated terminal per subagent.
 
-On mobile devices, Hop provides a custom virtual keyboard designed for terminal use:
+1. Create a terminal with `hop_create_terminal` and set `name` / `cwd`.
+2. Start the agent CLI with `hop_write_terminal`.
+3. Wait for readiness with `hop_wait_terminal(until_prompt=true)`.
+4. Prefer `hopx_agent_turn(mode="auto")` or `hopx_send_and_wait(...)` for one turn at a time.
+5. For long waits, use `hopx_agent_turn(async=true, ...)` or the lower-level `hop_wait_start(...)` / `hop_wait_poll(...)`.
+6. Interrupt with `hop_send_key(key="ctrl_c")` and close with `hop_close_terminal`.
 
-**Accessory Row:**
-- `Esc` `Tab` `Ctrl` `Alt` — Essential terminal keys
-- `← ↓ ↑ →` — Arrow keys for navigation
-- 🔵 **Blue keyboard button** — Opens native iOS keyboard for dictation, spellcheck & autocomplete
+Safety tips:
 
-**Floating Menu (top-right button):**
-- **Toggle Keyboard** — Show/hide the virtual keyboard
-- **Session List** — Quick-switch between sessions
-- **All Sessions** — Return to session picker
+- Keep one subagent per terminal.
+- Do not queue a second instruction before reading the first response.
+- For attached user sessions, confirm `agentPermitted` before sending input.
 
-**Tips:**
-- The floating button is draggable — move it anywhere
-- First-time users will see a tooltip pointing to the native keyboard button
-- Use the native keyboard for longer text input with autocomplete
+### Share a Local Web App
 
-## 🖥️ iTerm Integration
+Expose a local HTTP or WebSocket service through your Hop tunnel:
 
 ```bash
-hop --iterm
+hop session add myapp --port 3000
 ```
 
-Uses tmux control mode (`-CC`) for native scrolling, copy/paste, splits, and search. Session remains accessible via web.
+Result:
+
+- local service stays on localhost
+- Hop exposes it at `https://your-tunnel-url/s/myapp/`
+- WebSocket apps work too
 
-## 🔌 Port Sessions
+### Reattach Locally
 
-Expose local HTTP/WebSocket services through your tunnel:
+Attach your local terminal client to an existing terminal session:
 
 ```bash
-hop session add myapp --port 3000
-# Access at: https://your-tunnel-url/s/myapp/
+hop attach <session>
 ```
 
-Works with dev servers, Jupyter, APIs — anything on localhost. Supports WebSocket.
+This is useful when you want a browser, an MCP client, and a local shell to converge on the same named session.
+
+### Use Hop on Mobile
+
+Hop’s mobile UI includes:
+
+- a terminal-oriented accessory row with `Esc`, `Tab`, `Ctrl`, `Alt`, and arrows
+- a native keyboard button for dictation, spellcheck, and autocomplete
+- a floating menu for keyboard toggle and session switching
+- draggable controls designed for one-handed use
+
+## Operations
+
+### Logging and History
+
+Hop always writes per-session audit logs.
+
+Default behavior:
+
+- agent-created sessions get isolated shell history files
+- user-created sessions keep normal shell history unless you opt into isolation
+- TUI apps switch to diff-suppressed keyframe capture automatically
+
+Paths:
+
+- scratch sessions: `~/.hop2/runtime/history/<internal-session>.history`
+- scratch audit logs: `~/.hop2/runtime/logs/<internal-session>/audit.ndjson`
+- workspace-backed sessions: `~/.hop2/workspaces/<workspace>/history/<internal-session>.history`
+- workspace-backed audit logs: `~/.hop2/workspaces/<workspace>/logs/<internal-session>/audit.ndjson`
+
+Key tunables:
 
-## 🔧 Commands
+- `HOP_SESSION_HISTORY_SIZE`
+- `HOP_AGENT_HISTORY_ISOLATION`
+- `HOP_USER_HISTORY_ISOLATION`
+- `HOP_AGENT_POST_START_HISTORY_INIT`
+- `HOP_POST_START_HISTORY_INIT`
+- `HOP_SESSION_AUDIT_INLINE_MAX_BYTES`
+- `HOP_SESSION_TUI_KEYFRAME_INTERVAL_MS`
+- `HOP_SESSION_TUI_KEYFRAME_TAIL_CHARS`
+- `HOP_SESSION_TUI_KEYFRAME_MAX_LINES`
+
+### Users, Domains, and Sharing
+
+Admin flow:
+
+1. Set a password with `hop password set`.
+2. Configure a hostname with `hop domain hop.yourdomain.com`.
+3. Add a user with `hop user add alice`.
+4. Export credentials with `hop user export alice`.
+
+User flow:
+
+```bash
+npm install -g hop2
+hop client ./credentials.json
+```
+
+First run prompts for password setup and TOTP enrollment, then the user logs in at their assigned URL such as `https://alice.hop.yourdomain.com`.
+
+### Security
+
+- Password + TOTP is supported; password is required for custom domains
+- Login cookies are `httpOnly`, `secure`, and `sameSite=lax`
+- Browser sessions persist across `hop stop/start` by default through a stable session secret
+- The local server binds only to `127.0.0.1`
+- Cloudflare Tunnel provides end-to-end TLS
+
+Secrets are stored in `~/.hop2/`. Set `HOP_PERSIST_SESSION_SECRET=0` if you want login cookies invalidated on every daemon restart.
+
+### Runtime and Recovery
+
+Hop uses the external Hay host runtime for PTY hosting and session recovery.
+
+- active PTYs live in a separate local hay-host process
+- the host survives daemon restarts
+- host state is tracked in `~/.hop2/.hay-host-state`
+- startup reconciles already-running Hay sessions before applying workspace state
+- `HOP_TERMINAL_BACKEND` is accepted only for compatibility and ignored
+
+## Reference
+
+### Related Docs
+
+- [README-MCP.md](./README-MCP.md) for MCP tools, helper wrappers, and agent-driving patterns
+- [INTEGRATION.md](./INTEGRATION.md) for the current Hop/Hay architecture
+- [hay/README.md](./hay/README.md) for the vendored Hay workspace
+
+### Commands
 
 | Command | Description |
 |---------|-------------|
-| `hop` | Start hop (or attach to existing tunnel) |
-| `hop --iterm` | Use iTerm tmux control mode for local session |
+| `hop` | Start hop daemon/tunnel if needed, then launch a local terminal |
+| `hop attach all` | Attach sequentially to all terminal sessions |
+| `hop local [session]` | Start a daemonless local terminal (`[session]` attaches if it exists) |
 | `hop url` | Print current tunnel URL |
-| `hop qr` | Show QR code for current URL |
+| `hop qr` | Show QR code for current tunnel URL |
+| `hop qr auth` | Show QR code for authenticator app setup |
 | `hop domain <hostname>` | Set custom domain (named tunnel) |
 | `hop domain-clear` | Remove custom domain, use random URLs |
 | `hop password set` | Set/change password |
@@ -180,81 +277,45 @@ Works with dev servers, Jupyter, APIs — anything on localhost. Supports WebSoc
 | `hop user add <name>` | Add user + subdomain |
 | `hop user remove <name>` | Remove user |
 | `hop user export <name>` | Export user credentials |
-| `hop session list` | List sessions |
-| `hop session add <name>` | Create a terminal session |
-| `hop session add <name> --port N` | Create a port session (proxy) |
+| `hop session list` | List live terminal sessions |
+| `hop session list --all` | Include saved definitions from all workspaces alongside live sessions |
+| `hop session add <name> [--cwd P] --workspace W` | Save a terminal session definition to a named workspace |
+| `hop session add <name> --port N --workspace W` | Save a port session definition to a named workspace |
+| `hop workspace create <name>` | Create an empty workspace |
+| `hop workspace show <name>` | Show saved definitions in a workspace |
+| `hop workspace save <name>` | Save selected live terminal sessions into a workspace |
+| `hop workspace load <name>` | Start sessions defined in a workspace |
+| `hop workspace delete <name>` | Delete a workspace |
+| `hop session rename <old> <new>` | Rename a session |
 | `hop session remove <name>` | Remove a session |
 | `hop client <credentials>` | Run hop with exported credentials |
-| `hop wipe` | Kill all hop tmux sessions |
-| `quit` | Type at exit prompt to shutdown tunnel |
-
-## 📦 Dependencies
-
-Installed automatically via Homebrew:
-- `tmux` — Terminal multiplexer
-- `ttyd` — Web terminal
-- `cloudflared` — Cloudflare tunnel
-
-Node.js packages:
-- `http-proxy` — Request proxying
-- `otplib` — TOTP authentication
-- `qrcode-terminal` — QR code display
-- `cookie` — Session cookies
-
-## 🛡️ Security
-
-- **Password + TOTP** — Password optional, but required for custom domains
-- **Rate Limiting** — Exponential backoff on failed attempts
-- **Secure Cookies** — `httpOnly`, `secure`, `sameSite=lax`
-- **Random URL** — Unguessable tunnel URL for quick tunnels
-- **Fixed URL** — Custom domains keep a stable URL
-- **Local Binding** — Server only listens on 127.0.0.1
-- **End-to-End TLS** — Cloudflare Tunnel encryption
-
-**Passwords:** Recommended for any public URL; required for custom domains.
+| `hop wipe [--all]` | Remove workspace-defined sessions (`--all` also kills live sessions) |
+| `quit` | Type at exit prompt to shut down the tunnel |
 
-**Secrets:** Stored in `~/.hop2/` (treat like `~/.ssh/`)
+### Development
 
-## 🛠 Development (Hay)
-
-The hay source is vendored in `./hay`. Hop will serve `hay/apps/web/dist` when present.
+The Hay source is vendored in `./hay`. Hop serves `hay/apps/web/dist` when present.
 
 ```bash
 npm run build
+npm test
 ```
 
-This builds hay (web + cli) and syncs `hay/apps/web/dist` into `hay-web/` for Hop to serve.
-If `./hay` exists and the dist folder is missing, `hop` will auto-build hay on startup.
-
-## 🐛 Troubleshooting
+This rebuilds Hay and syncs `hay/apps/web/dist` into `hay-web/`. `npm test` runs a basic syntax sanity check on the main `hop` entrypoint. If `./hay` exists and the dist folder is missing, `hop` auto-builds Hay on startup.
 
-**QR code not working?**
-Delete `.auth_secret` and restart hop to generate a new code.
+## Troubleshooting
 
-**Client reset (user mode)?**
-Delete `~/.hop2/clients/<tunnel-id>/` and run `hop client` again.
+- Authenticator QR again: run `hop qr auth`
+- Reset TOTP entirely: delete `.auth_secret` and restart Hop
+- Reset a client install: delete `~/.hop2/clients/<tunnel-id>/` and run `hop client` again
+- Tunnel not starting: install `cloudflared` with `brew install cloudflared`
+- Tunnel returning `502` after a network change: run `hop health --restart`
+- Stuck tunnel processes:
 
-**Tunnel not starting?**
-Make sure `cloudflared` is installed: `brew install cloudflared`
-
-**Stuck processes?**
 ```bash
-pkill ttyd; pkill cloudflared; tmux kill-server
+pkill cloudflared
 ```
 
-## 📝 License
+## License
 
 MIT
-
----
-
-Made with 🐰 for hopping around
-
-```
-   ____
-  /    \
- | ^  ^ |     hop hop hop
- |  ..  |
-  \ -- /
-   ||||
-```

package/demo/30s-product-demo.md

@@ -0,0 +1,98 @@
+# 30s Product Demo Runbook
+
+This is the first concrete demo built on top of the small Hop demo harness.
+
+## Goal
+
+Show that Hop can:
+
+1. host a visible subagent terminal
+2. let the human watch and steer it live
+3. expose the resulting app through the same runtime
+4. reconnect cleanly on mobile
+
+## Recommended Structure
+
+### Clip 1: Session picker
+
+Duration: 2 to 3 seconds
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/record-hop-view.mjs \
+  --out demo-output/clip-01-sessions \
+  --duration 2500
+```
+
+Use this under the caption:
+
+`Terminal access for humans and agents`
+
+### Clip 2: Start a dedicated agent terminal
+
+Create or attach a named session that will hold the agent:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/drive-hop-terminal.mjs \
+  --name demo-agent \
+  --cwd "$PWD"
+```
+
+Then launch `codex` in that session with your preferred flags. For now this is still better driven explicitly rather than hidden behind another wrapper.
+
+### Clip 3: Record live terminal work
+
+Once Codex is working in `demo-agent`, record the session page:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/record-hop-view.mjs \
+  --session demo-agent \
+  --out demo-output/clip-03-agent \
+  --duration 8000
+```
+
+Suggested caption:
+
+`Watch every step in real time`
+
+### Clip 4: Redirect mid-run
+
+Send a second instruction into the same session while it is still running, then record a short follow-up clip.
+
+Suggested caption:
+
+`Interrupt. Redirect. Continue.`
+
+### Clip 5: Record mobile view
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/record-hop-view.mjs \
+  --session demo-agent \
+  --mobile true \
+  --out demo-output/clip-05-mobile \
+  --duration 4000
+```
+
+Suggested caption:
+
+`Check progress from anywhere`
+
+### Clip 6: Optional second agent tease
+
+Repeat the same flow with a second session such as `demo-reviewer` and end on a very short two-agent tease.
+
+Keep this to 2 to 3 seconds. It should feel like a promise, not a second full story.
+
+## Editing Notes
+
+- Prefer 5 to 8 second source clips, then trim aggressively
+- Use hard cuts, not slow transitions
+- Do not show login unless the login flow itself is the product being demoed
+- Keep text overlays short and concrete
+- Avoid dense terminal text overlays; let the UI and motion carry the demo
+
+## Current State
+
+- Browser recording works
+- Mobile recording works
+- Local API terminal creation works
+- The current driver is good enough to bootstrap sessions, but it is not yet a full turn-by-turn subagent director

package/demo/README.md

@@ -0,0 +1,106 @@
+# Hop Demo Harness
+
+Small reusable pieces for recording real Hop browser footage and driving real Hop terminals.
+
+## What This Is
+
+- `record-hop-view.mjs` records the Hop browser UI with Playwright
+- `drive-hop-terminal.mjs` creates or attaches to a terminal over Hop's local API and sends input
+- `director.mjs` runs the first single-agent 30s capture flow end to end
+- `static-preview-server.mjs` serves the sanitized demo workspace for preview clips
+- `stitch-demo-video.mjs` concatenates recorded WebM clips into one rough MP4
+- `hop-demo-lib.mjs` holds the shared state, auth, browser, and API helpers
+
+The harness uses the local Hop daemon port from `~/.hop2/.tunnel-state` and injects the Hop session cookie directly into Playwright. That avoids interactive login during capture while still exercising the real Hop UI.
+
+For production demos, `director.mjs` now uses a sanitized workspace and filters non-demo sessions out of the captured UI so the recording does not show your normal session list, username, hostname, or personal directory path. Starting from an isolated Hop home is supported as an opt-in experiment with `--start-daemon true`.
+
+## Prerequisites
+
+- Hop daemon is running
+- `codex` or another terminal program is already installed if you want to demo an agent
+- Homebrew Node is available at `/opt/homebrew/bin/node`
+- Playwright is available from the vendored Hay workspace
+
+## Basic Examples
+
+Create or attach a terminal and run a command:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/drive-hop-terminal.mjs \
+  --name demo-agent \
+  --cwd "$PWD" \
+  --exec "printf 'hello from hop demo\\n'"
+```
+
+Wait for output after starting a program:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/drive-hop-terminal.mjs \
+  --name demo-agent \
+  --cwd "$PWD" \
+  --exec "codex" \
+  --wait-timeout 15000
+```
+
+Record the session picker:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/record-hop-view.mjs \
+  --out demo-output/sessions \
+  --duration 3000
+```
+
+Record one terminal session:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/record-hop-view.mjs \
+  --session demo-agent \
+  --out demo-output/demo-agent \
+  --duration 8000
+```
+
+Record a mobile-sized view:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/record-hop-view.mjs \
+  --session demo-agent \
+  --mobile true \
+  --out demo-output/demo-agent-mobile \
+  --duration 5000
+```
+
+Run the first end-to-end single-agent capture flow:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/director.mjs \
+  --name demo-agent \
+  --preset landing-page \
+  --launch "codex" \
+  --out demo-output/run-01
+```
+
+Stitch the recorded clips into a rough cut:
+
+```bash
+PATH=/opt/homebrew/bin:$PATH /opt/homebrew/bin/node demo/stitch-demo-video.mjs \
+  --in demo-output/run-01 \
+  --out demo-output/run-01/hop-demo-rough.mp4
+```
+
+## Suggested 30s Demo Flow
+
+1. Record `/sessions`
+2. Start a dedicated `codex` terminal with `drive-hop-terminal.mjs`
+3. Record the live session page while Codex works
+4. Send a second instruction into the same terminal
+5. Record a mobile view of the same session
+6. Stitch the clips with `ffmpeg`
+
+## Notes
+
+- The current scripts are intentionally small. The new `director.mjs` is still a thin orchestrator, not a large demo framework.
+- Desktop recording now defaults to `1920x1080`. Mobile clips are normalized onto the same canvas during stitching.
+- The default showcase flow now records a filtered session picker, the live agent terminal, a follow-up redirect clip, a preview-app clip through a Hop port session, and a mobile clip.
+- `stitch-demo-video.mjs` now overlays short captions by default. Use `--overlay-captions false` to disable that.
+- For a deterministic product video, prefer recording short clips and stitching them together rather than relying on one perfect live take.