hop2 0.9.1 → 0.11.0

package/README.md

@@ -1,12 +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.
 
-Hop also ships with a built-in MCP server, so Claude Code, Codex, Gemini, Cursor, and other MCP clients can create terminals, stream output, and drive agent sessions through Hop.
-
-> **🍎 macOS/Linux** — Requires cloudflared for tunneling
+> **macOS/Linux** — Requires cloudflared for tunneling
 
 ```
            (\(\ 
@@ -14,22 +12,19 @@ Hop also ships with a built-in MCP server, so Claude Code, Codex, Gemini, Cursor
            o_(")(")
 ```
 
-## ✨ Features
+## Why Hop
 
-- 🔐 **Password + 2FA** — Optional password plus TOTP (required for custom domains)
-- 🌍 **Access Anywhere** — Cloudflare tunnel, no port forwarding
-- 🤖 **Built-in MCP Server** — Turn Hop into an agent-facing terminal platform for Claude Code, Codex, Gemini, Cursor, and more
-- 🌐 **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
@@ -41,12 +36,18 @@ This installs:
 - `hop-mcp` — MCP server exposing Hop terminals and sessions
 - `hop-mcp-setup` — MCP client auto-config helper
 
-Then just run:
+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 && \
@@ -54,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
@@ -72,36 +73,22 @@ echo 'export PATH="$HOME/.hop:$PATH"' >> ~/.zshrc
 source ~/.zshrc
 ```
 
-## 🐰 Usage
+## Quick Start
 
+### Browser access
 ```bash
-# Start hopping!
 hop
 ```
 
-**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
-
-**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
+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
 
-## 🤖 Hop MCP
+Then open the URL from another device, sign in, and pick or create a session.
 
-Hop is not just a browser terminal. It also exposes terminals and sessions over MCP so agents can safely operate through the same platform.
-
-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
-
-Quick start:
+### MCP access
 
 ```bash
 hop
@@ -110,251 +97,240 @@ hop-mcp-setup
 
 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).
 
-## 🪟 Sessions
+## Everyday Workflows
+
+### 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
+hop session add workspace-shell --cwd ~/src/my-project --workspace dev
+hop session add myapp --port 3000 --workspace dev
 ```
 
-## 🧾 Session History & Audit Logs
+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:
 
-Hop always writes per-session audit logs.
-Shell history isolation is role-based by default:
-
-- Agent-created terminal sessions: isolated history file per session
-- User-created terminal sessions: keep your shell default history file (opt-in isolation available)
-
-- Isolated history file path: `~/.hop2/workspaces/<workspace>/history/<internal-session>.history`
-- Audit log (NDJSON): `~/.hop2/workspaces/<workspace>/logs/<internal-session>/audit.ndjson`
-- Audit events include `session_start`, `input`, `resize`, `session_end`, plus:
-- `audit_mode` / `pty_state` transitions (auto-switches between `stream` and `tui_keyframe`)
-- `tui_keyframe` snapshots (diff-suppressed; emitted only when content changes)
-- `command_launch` metadata (captures launched command token and detected agent CLI type)
-- Large input/output chunks are truncated with metadata (`bytes`, `omittedBytes`, `dataHead`, `dataTail`)
-
-Tunable defaults:
-
-- `HOP_SESSION_HISTORY_SIZE` (default `5000`)
-- `HOP_AGENT_HISTORY_ISOLATION` (default `1`)
-- `HOP_USER_HISTORY_ISOLATION` (default `0`)
-- `HOP_AGENT_POST_START_HISTORY_INIT` (default `1`)
-- `HOP_POST_START_HISTORY_INIT` (default `0`, forces post-start history init for all sessions)
-- `HOP_SESSION_AUDIT_INLINE_MAX_BYTES` (default `4096`)
-- `HOP_SESSION_TUI_KEYFRAME_INTERVAL_MS` (default `750`)
-- `HOP_SESSION_TUI_KEYFRAME_TAIL_CHARS` (default `20000`)
-- `HOP_SESSION_TUI_KEYFRAME_MAX_LINES` (default `80`)
-
-## 🌐 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)
 ```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_terminal(async=true, ...)` + `hop_wait_poll(...)` (`hop_wait_start` remains only as a legacy alias).
+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 (grant it with `hop session permit <name>`).
 
-**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
 
-## 🖥️ Local Attach
+Expose a local HTTP or WebSocket service through your Hop tunnel:
 
 ```bash
-hop attach <session>
+hop session add myapp --port 3000 --workspace dev
 ```
 
-Attach your local terminal client to an existing hop terminal session.
+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.
+Local terminal sessions are persistent by default: they keep running in the Hay host if the local CLI detaches or the Hop daemon restarts. The local CLI status line shows `persists`; use `Ctrl+Q` inside the local Hop view to kill the session.
 
-## 🔧 Commands
+### Use Hop on Mobile
 
-| Command | Description |
-|---------|-------------|
-| `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 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 |
-| `hop password clear` | Remove password protection |
-| `hop user list` | List users |
-| `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 with `LIVE` vs `SAVED` terminal status |
-| `hop session add <name> [--cwd P]` | Create a terminal session |
-| `hop session add <name> --port N` | Create a port session (proxy) |
-| `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 [--all]` | Remove saved sessions (`--all` also kills live sessions) |
-| `quit` | Type at exit prompt to shutdown tunnel |
+Hop’s mobile UI includes:
 
-Additional installed binaries:
-- `hop-mcp` — Start the Hop MCP server directly
-- `hop-mcp-setup` — Auto-configure supported MCP clients
+- 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
 
-Startup behavior:
-- Hop reconciles already-running external Hay sessions first, then applies the default workspace as additional startup state.
+## Operations
 
-## 🧪 Terminal Backend
+### Logging and History
 
-Hop always uses the `external` terminal runtime (PTYs in a separate local hay host process).
+Hop always writes per-session audit logs.
 
-- The host persists across hop daemon restarts.
-- Host state is tracked in `~/.hop2/.hay-host-state`.
-- On startup and session listing, Hop discovers live hay-host processes and adopts the one(s) that still own runtime rooms if the state file is stale.
-- Local CLI transport is direct to hay-host; daemon restarts do not terminate local terminal sessions.
-- Bare `hop` prompts on cwd match (`Attach existing` vs `Create new`, default `Create new`); non-interactive runs always create new.
-- `HOP_TERMINAL_BACKEND` is accepted for compatibility but ignored.
+Default behavior:
 
-## 📦 Dependencies
+- 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
 
-Installed automatically via Homebrew:
-- `cloudflared` — Cloudflare tunnel
+Paths:
 
-Node.js packages:
-- `http-proxy` — Request proxying
-- `otplib` — TOTP authentication
-- `qrcode-terminal` — QR code display
-- `cookie` — Session cookies
+- 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`
 
-## 🛡️ Security
+Key tunables:
 
-- **Password + TOTP** — Password optional, but required for custom domains
-- **Rate Limiting** — Exponential backoff on failed attempts
-- **Secure Cookies** — `httpOnly`, `secure`, `sameSite=lax`
-- **Session persistence** — Login cookies are signed with a stable session secret by default, so browser sessions can survive `hop stop/start` without reauth.
-- **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
+- `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`
 
-**Passwords:** Recommended for any public URL; required for custom domains.
+### Users, Domains, and Sharing
 
-**Secrets:** Stored in `~/.hop2/` (treat like `~/.ssh/`)
-Set `HOP_PERSIST_SESSION_SECRET=0` to force a fresh login cookie secret every daemon restart.
+Admin flow:
 
-## 🛠 Development (Hay)
+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`.
 
-The hay source is vendored in `./hay`. Hop will serve `hay/apps/web/dist` when present.
+User flow:
 
 ```bash
-npm run build
+npm install -g hop2
+hop client ./credentials.json
 ```
 
-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.
+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`.
 
-## 🤖 Hop MCP (One Subagent Terminal)
+### Security
 
-Use one dedicated terminal when driving a subagent CLI through Hop MCP.
+- 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
 
-1. Create a terminal with `hop_create_terminal` (set `name` and `cwd`).
-2. Start the agent CLI with `hop_write_terminal` (`claude` or `codex`).
-3. Wait for readiness with `hop_wait_terminal(until_prompt=true)`.
-4. Send one instruction at a time via `hopx_send_and_wait` (or `hop_write_terminal` + `hop_wait_terminal`).
-5. Optional helper path: use `hopx_agent_turn(mode="auto")` for a single send+wait turn with mode-aware output (`ui` for TUI screens, `readable_raw` otherwise); it auto-promotes to `ui` if alternate-screen starts mid-turn and uses lean capture defaults (`capture_max_events=60` for readable modes, `0` for `ui` unless overridden, plus `text_only=true` by default for readable waits).
-6. For long waits, prefer `hopx_agent_turn(async=true, ...)` and continue with `hopx_agent_turn(wait_id=..., wait=true, control="wait")`; fall back to `hop_wait_start(...)` / `hop_wait_poll(...)` when you want the lower-level primitives directly.
-7. After each turn, collect output with `hop_wait_terminal` or incremental `hop_read_terminal` cursor reads.
-8. Interrupt with `hop_send_key(key="ctrl_c")` and close using `hop_close_terminal`.
+Secrets are stored in `~/.hop2/`. Set `HOP_PERSIST_SESSION_SECRET=0` if you want login cookies invalidated on every daemon restart.
 
-Safety tips:
-- 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.
+### Runtime and Recovery
 
-## 🐛 Troubleshooting
+Hop uses the external Hay host runtime for PTY hosting and session recovery.
 
-**Authenticator QR code needed again?**
-Run `hop qr auth` to re-show the current TOTP setup QR for Duo/Authy/1Password.
+- 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
 
-**Need to reset TOTP entirely?**
-Delete `.auth_secret` and restart hop to generate a new authenticator secret and QR code.
+## Reference
 
-**Client reset (user mode)?**
-Delete `~/.hop2/clients/<tunnel-id>/` and run `hop client` again.
+### Related Docs
 
-**Tunnel not starting?**
-Make sure `cloudflared` is installed: `brew install cloudflared`
+- [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
 
-**Tunnel returns 502 or died after network changes?**
-Run `hop health --restart`. Hop now waits for the public URL to become healthy again instead of only sending a fire-and-forget restart request.
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `hop` | Start hop daemon/tunnel if needed, then launch a local terminal. Unnamed launches do not reuse a session that already has a local CLI attached. |
+| `hop start` | Start the hop daemon and print QR codes |
+| `hop attach [session]` | Attach to an existing terminal session |
+| `hop attach all` | Attach sequentially to all terminal sessions |
+| `hop local [session]` | Start a daemonless local terminal (`[session]` attaches if it exists) |
+| `hop stop` | Stop the hop daemon (terminal sessions keep running) |
+| `hop stop --all` | Stop the daemon, the hay-host, and all terminal sessions |
+| `hop status` | Show daemon, tunnel, and session status |
+| `hop doctor` | Run environment/health checks |
+| `hop logs [-f]` | Show daemon logs (`-f` to follow) |
+| `hop health [--restart]` | Check tunnel health (`--restart` forces a tunnel restart) |
+| `hop url` | Print current tunnel URL |
+| `hop qr` | Show QR code for current tunnel URL |
+| `hop qr auth` | Show QR code for authenticator app setup |
+| `hop config theme [name]` | Show or set the session naming theme |
+| `hop domain <hostname>` | Set custom domain (named tunnel) |
+| `hop domain-clear` | Remove custom domain, use random URLs |
+| `hop password set` | Set/change password |
+| `hop password clear` | Remove password protection |
+| `hop user list` | List users |
+| `hop user add <name>` | Add user + subdomain |
+| `hop user remove <name>` | Remove user |
+| `hop user export <name>` | Export user credentials |
+| `hop session list` | List live terminal sessions |
+| `hop session list --all` | Include saved definitions from all workspaces alongside live sessions (`-a` is shorthand) |
+| `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 session permit <name>` | Allow agent access to a session |
+| `hop session block <name>` | Block agent access to a session |
+| `hop workspace list` | List workspaces |
+| `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> [--yes]` | Delete a workspace (asks before deleting a non-empty one) |
+| `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 [--all] [--yes]` | Remove workspace-defined sessions (`--all` also kills live sessions after a confirmation; `--yes` skips it) |
+| `hop wipe --agent` | Close all agent-created terminal API sessions |
+
+Local CLI mouse capture is off by default so terminal-native selection and context menus keep working. Use Option+M / Alt+M inside the local Hop view to toggle Hop mouse selection when needed. Use Option+B / Alt+B to toggle the status bar. CLI defaults live under `hay-cli` in `~/.hop.json`.
+
+### Development
+
+The Hay source is vendored in `./hay`. Hop serves `hay/apps/web/dist` when present.
 
-**Stuck processes?**
 ```bash
-pkill cloudflared
+npm run build
+npm test
 ```
 
-## 📝 License
+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.
 
-MIT
-
----
+## Troubleshooting
 
-Made with 🐰 for hopping around
+- 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:
 
+```bash
+pkill cloudflared
 ```
-   ____
-  /    \
- | ^  ^ |     hop hop hop
- |  ..  |
-  \ -- /
-   ||||
-```
+
+## License
+
+MIT

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