Release: dev -> main

.agents/skills/add-mcp

@@ -0,0 +1 @@
+../../skills/add-mcp

.agents/skills/add-remote-mcp

@@ -0,0 +1 @@
+../../skills/add-remote-mcp

.agents/skills/autoresearch-workflows

@@ -0,0 +1 @@
+../../skills/autoresearch-workflows

.agents/skills/behavioral-core

@@ -0,0 +1 @@
+../../skills/behavioral-core

.agents/skills/bootstrap-plaited-agent

@@ -0,0 +1 @@
+../../skills/bootstrap-plaited-agent

.agents/skills/cmux-browser/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: cmux-browser
+description: End-user browser automation with cmux. Use when you need to open sites, interact with pages, wait for state changes, and extract data from cmux browser surfaces.
+---
+
+# Browser Automation with cmux
+
+Use this skill for browser tasks inside cmux webviews.
+
+## Core Workflow
+
+1. Open or target a browser surface.
+2. Verify navigation with `get url` before waiting or snapshotting.
+3. Snapshot (`--interactive`) to get fresh element refs.
+4. Act with refs (`click`, `fill`, `type`, `select`, `press`).
+5. Wait for state changes.
+6. Re-snapshot after DOM/navigation changes.
+
+```bash
+cmux --json browser open https://example.com
+# use returned surface ref, for example: surface:7
+
+cmux browser surface:7 get url
+cmux browser surface:7 wait --load-state complete --timeout-ms 15000
+cmux browser surface:7 snapshot --interactive
+cmux browser surface:7 fill e1 "hello"
+cmux --json browser surface:7 click e2 --snapshot-after
+cmux browser surface:7 snapshot --interactive
+```
+
+## Surface Targeting
+
+```bash
+# identify current context
+cmux identify --json
+
+# open routed to a specific topology target
+cmux browser open https://example.com --workspace workspace:2 --window window:1 --json
+```
+
+Notes:
+- CLI output defaults to short refs (`surface:N`, `pane:N`, `workspace:N`, `window:N`).
+- UUIDs are still accepted on input; only request UUID output when needed (`--id-format uuids|both`).
+- Keep using one `surface:N` per task unless you intentionally switch.
+
+## Wait Support
+
+cmux supports wait patterns similar to agent-browser:
+
+```bash
+cmux browser <surface> wait --selector "#ready" --timeout-ms 10000
+cmux browser <surface> wait --text "Success" --timeout-ms 10000
+cmux browser <surface> wait --url-contains "/dashboard" --timeout-ms 10000
+cmux browser <surface> wait --load-state complete --timeout-ms 15000
+cmux browser <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000
+```
+
+## Common Flows
+
+### Form Submit
+
+```bash
+cmux --json browser open https://example.com/signup
+cmux browser surface:7 get url
+cmux browser surface:7 wait --load-state complete --timeout-ms 15000
+cmux browser surface:7 snapshot --interactive
+cmux browser surface:7 fill e1 "Jane Doe"
+cmux browser surface:7 fill e2 "jane@example.com"
+cmux --json browser surface:7 click e3 --snapshot-after
+cmux browser surface:7 wait --url-contains "/welcome" --timeout-ms 15000
+cmux browser surface:7 snapshot --interactive
+```
+
+### Clear an Input
+
+```bash
+cmux browser surface:7 fill e11 "" --snapshot-after --json
+cmux browser surface:7 get value e11 --json
+```
+
+### Stable Agent Loop (Recommended)
+
+```bash
+# navigate -> verify -> wait -> snapshot -> action -> snapshot
+cmux browser surface:7 get url
+cmux browser surface:7 wait --load-state complete --timeout-ms 15000
+cmux browser surface:7 snapshot --interactive
+cmux --json browser surface:7 click e5 --snapshot-after
+cmux browser surface:7 snapshot --interactive
+```
+
+If `get url` is empty or `about:blank`, navigate first instead of waiting on load state.
+
+## Deep-Dive References
+
+| Reference | When to Use |
+|-----------|-------------|
+| [references/commands.md](references/commands.md) | Full browser command mapping and quick syntax |
+| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle and stale-ref troubleshooting |
+| [references/authentication.md](references/authentication.md) | Login/OAuth/2FA patterns and state save/load |
+| [references/authentication.md#saving-authentication-state](references/authentication.md#saving-authentication-state) | Save authenticated state right after login |
+| [references/session-management.md](references/session-management.md) | Multi-surface isolation and state persistence patterns |
+| [references/video-recording.md](references/video-recording.md) | Current recording status and practical alternatives |
+| [references/proxy-support.md](references/proxy-support.md) | Proxy behavior in WKWebView and workarounds |
+
+## Ready-to-Use Templates
+
+| Template | Description |
+|----------|-------------|
+| [templates/form-automation.sh](templates/form-automation.sh) | Snapshot/ref form fill loop |
+| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, save/load state |
+| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Navigate + capture snapshots/screenshots |
+
+## Limits (WKWebView)
+
+These commands currently return `not_supported` because they rely on Chrome/CDP-only APIs not exposed by WKWebView:
+- viewport emulation
+- offline emulation
+- trace/screencast recording
+- network route interception/mocking
+- low-level raw input injection
+
+Use supported high-level commands (`click`, `fill`, `press`, `scroll`, `wait`, `snapshot`) instead.
+
+## Troubleshooting
+
+### `js_error` on `snapshot --interactive` or `eval`
+
+Some complex pages can reject or break the JavaScript used for rich snapshots and ad-hoc evaluation.
+
+Recovery steps:
+
+```bash
+cmux browser surface:7 get url
+cmux browser surface:7 get text body
+cmux browser surface:7 get html body
+```
+
+- Use `get url` first so you know whether the page actually navigated.
+- Fall back to `get text body` or `get html body` when `snapshot --interactive` or `eval` returns `js_error`.
+- If the page is still failing, navigate to a simpler intermediate page, then retry the task from there.

.agents/skills/cmux-browser/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "cmux Browser"
+  short_description: "Automate cmux webview surfaces with snapshot/ref workflows."
+  default_prompt: "Use this skill for browser automation via cmux CLI: identify target surface, snapshot interactive refs, perform actions, wait for state changes, and re-snapshot to avoid stale refs."

.agents/skills/cmux-browser/references/authentication.md

@@ -0,0 +1,122 @@
+# Authentication Patterns
+
+Login flows, session persistence, OAuth, and 2FA patterns for cmux browser surfaces.
+
+**Related**: [session-management.md](session-management.md), [SKILL.md](../SKILL.md)
+
+## Contents
+
+- [Basic Login Flow](#basic-login-flow)
+- [Saving Authentication State](#saving-authentication-state)
+- [Restoring Authentication](#restoring-authentication)
+- [OAuth / SSO Flows](#oauth--sso-flows)
+- [Two-Factor Authentication](#two-factor-authentication)
+- [Cookie-Based Auth](#cookie-based-auth)
+- [Token Refresh Handling](#token-refresh-handling)
+- [Security Best Practices](#security-best-practices)
+
+## Basic Login Flow
+
+```bash
+cmux browser open https://app.example.com/login --json
+cmux browser surface:7 wait --load-state complete --timeout-ms 15000
+
+cmux browser surface:7 snapshot --interactive
+# [ref=e1] email, [ref=e2] password, [ref=e3] submit
+
+cmux browser surface:7 fill e1 "user@example.com"
+cmux browser surface:7 fill e2 "$APP_PASSWORD"
+cmux browser surface:7 click e3 --snapshot-after --json
+cmux browser surface:7 wait --url-contains "/dashboard" --timeout-ms 20000
+```
+
+## Saving Authentication State
+
+After logging in, save state for reuse:
+
+```bash
+cmux browser surface:7 state save ./auth-state.json
+```
+
+State includes cookies, localStorage, sessionStorage, and open tab metadata for that surface.
+
+## Restoring Authentication
+
+```bash
+cmux browser open https://app.example.com --json
+cmux browser surface:8 state load ./auth-state.json
+cmux browser surface:8 goto https://app.example.com/dashboard
+cmux browser surface:8 snapshot --interactive
+```
+
+## OAuth / SSO Flows
+
+```bash
+cmux browser open https://app.example.com/auth/google --json
+cmux browser surface:7 wait --url-contains "accounts.google.com" --timeout-ms 30000
+cmux browser surface:7 snapshot --interactive
+
+cmux browser surface:7 fill e1 "user@gmail.com"
+cmux browser surface:7 click e2 --snapshot-after --json
+
+cmux browser surface:7 wait --url-contains "app.example.com" --timeout-ms 45000
+cmux browser surface:7 state save ./oauth-state.json
+```
+
+## Two-Factor Authentication
+
+```bash
+cmux browser open https://app.example.com/login --json
+cmux browser surface:7 snapshot --interactive
+cmux browser surface:7 fill e1 "user@example.com"
+cmux browser surface:7 fill e2 "$APP_PASSWORD"
+cmux browser surface:7 click e3
+
+# complete 2FA manually in the webview, then:
+cmux browser surface:7 wait --url-contains "/dashboard" --timeout-ms 120000
+cmux browser surface:7 state save ./2fa-state.json
+```
+
+## Cookie-Based Auth
+
+```bash
+cmux browser surface:7 cookies set session_token "abc123xyz"
+cmux browser surface:7 goto https://app.example.com/dashboard
+```
+
+## Token Refresh Handling
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+STATE_FILE="./auth-state.json"
+SURFACE="surface:7"
+
+if [ -f "$STATE_FILE" ]; then
+  cmux browser "$SURFACE" state load "$STATE_FILE"
+fi
+
+cmux browser "$SURFACE" goto https://app.example.com/dashboard
+URL=$(cmux browser "$SURFACE" get url)
+
+if printf '%s' "$URL" | grep -q '/login'; then
+  cmux browser "$SURFACE" snapshot --interactive
+  cmux browser "$SURFACE" fill e1 "$APP_USERNAME"
+  cmux browser "$SURFACE" fill e2 "$APP_PASSWORD"
+  cmux browser "$SURFACE" click e3
+  cmux browser "$SURFACE" wait --url-contains "/dashboard" --timeout-ms 20000
+  cmux browser "$SURFACE" state save "$STATE_FILE"
+fi
+```
+
+## Security Best Practices
+
+1. Never commit state files (they include auth tokens).
+2. Use environment variables for credentials.
+3. Clear state/cookies after sensitive tasks:
+
+```bash
+cmux browser surface:7 cookies clear
+rm -f ./auth-state.json
+```

.agents/skills/cmux-browser/references/commands.md

@@ -0,0 +1,108 @@
+# Command Reference (cmux Browser)
+
+This maps common `agent-browser` usage to `cmux browser` usage.
+
+## Direct Equivalents
+
+- `agent-browser open <url>` -> `cmux browser open <url>`
+- `agent-browser goto|navigate <url>` -> `cmux browser <surface> goto|navigate <url>`
+- `agent-browser snapshot -i` -> `cmux browser <surface> snapshot --interactive`
+- `agent-browser click <ref>` -> `cmux browser <surface> click <ref>`
+- `agent-browser fill <ref> <text>` -> `cmux browser <surface> fill <ref> <text>`
+- `agent-browser type <ref> <text>` -> `cmux browser <surface> type <ref> <text>`
+- `agent-browser select <ref> <value>` -> `cmux browser <surface> select <ref> <value>`
+- `agent-browser get text <ref>` -> `cmux browser <surface> get text <ref-or-selector>`
+- `agent-browser get url` -> `cmux browser <surface> get url`
+- `agent-browser get title` -> `cmux browser <surface> get title`
+
+## Core Command Groups
+
+### Navigation
+
+```bash
+cmux browser open <url>                        # opens in caller's workspace (uses CMUX_WORKSPACE_ID)
+cmux browser open <url> --workspace <id|ref>   # opens in a specific workspace
+cmux browser <surface> goto <url>
+cmux browser <surface> back|forward|reload
+cmux browser <surface> get url|title
+```
+
+> **Workspace context:** `browser open` targets the workspace of the terminal where the command is run (via `CMUX_WORKSPACE_ID`), even if a different workspace is currently focused. Use `--workspace` to override.
+
+### Snapshot and Inspection
+
+```bash
+cmux browser <surface> snapshot --interactive
+cmux browser <surface> snapshot --interactive --compact --max-depth 3
+cmux browser <surface> get text body
+cmux browser <surface> get html body
+cmux browser <surface> get value "#email"
+cmux browser <surface> get attr "#email" --attr placeholder
+cmux browser <surface> get count ".row"
+cmux browser <surface> get box "#submit"
+cmux browser <surface> get styles "#submit" --property color
+cmux browser <surface> eval '<js>'
+```
+
+### Interaction
+
+```bash
+cmux browser <surface> click|dblclick|hover|focus <selector-or-ref>
+cmux browser <surface> fill <selector-or-ref> [text]   # empty text clears
+cmux browser <surface> type <selector-or-ref> <text>
+cmux browser <surface> press|keydown|keyup <key>
+cmux browser <surface> select <selector-or-ref> <value>
+cmux browser <surface> check|uncheck <selector-or-ref>
+cmux browser <surface> scroll [--selector <css>] [--dx <n>] [--dy <n>]
+```
+
+### Wait
+
+```bash
+cmux browser <surface> wait --selector "#ready" --timeout-ms 10000
+cmux browser <surface> wait --text "Done" --timeout-ms 10000
+cmux browser <surface> wait --url-contains "/dashboard" --timeout-ms 10000
+cmux browser <surface> wait --load-state complete --timeout-ms 15000
+cmux browser <surface> wait --function "document.readyState === 'complete'" --timeout-ms 10000
+```
+
+### Session/State
+
+```bash
+cmux browser <surface> cookies get|set|clear ...
+cmux browser <surface> storage local|session get|set|clear ...
+cmux browser <surface> tab list|new|switch|close ...
+cmux browser <surface> state save|load <path>
+```
+
+### Diagnostics
+
+```bash
+cmux browser <surface> console list|clear
+cmux browser <surface> errors list|clear
+cmux browser <surface> highlight <selector>
+cmux browser <surface> screenshot
+cmux browser <surface> download wait --timeout-ms 10000
+```
+
+## Agent Reliability Tips
+
+- Use `--snapshot-after` on mutating actions to return a fresh post-action snapshot.
+- Re-snapshot after navigation, modal open/close, or major DOM changes.
+- Prefer short handles in outputs by default (`surface:N`, `pane:N`, `workspace:N`, `window:N`).
+- Use `--id-format both` only when a UUID must be logged/exported.
+
+## Known WKWebView Gaps (`not_supported`)
+
+- `browser.viewport.set`
+- `browser.geolocation.set`
+- `browser.offline.set`
+- `browser.trace.start|stop`
+- `browser.network.route|unroute|requests`
+- `browser.screencast.start|stop`
+- `browser.input_mouse|input_keyboard|input_touch`
+
+See also:
+- [snapshot-refs.md](snapshot-refs.md)
+- [authentication.md](authentication.md)
+- [session-management.md](session-management.md)