re-sync and add notes about server refactor

.agents/skills/cli-agent-browser/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: cli-agent-browser
+description: 'Browser automation via the agent-browser CLI — a daemon-backed Chrome controller with persistent state across shell calls. Primary choice for browser tasks inside the agent-safehouse sandbox. Use when interacting with web pages — navigating, snapshotting, clicking, filling forms, taking screenshots. Triggers on: browse a page, automate browser, take a screenshot, fill a form, click a button, scrape a page, test a web app.'
+---
+
+# agent-browser
+
+The most reliable browser CLI for agents running inside the **`agent-safehouse`**
+sandbox. A persistent daemon (sockets, pid, state in `~/.agent-browser/`)
+spawns Chrome with the right flags and survives across one-shot Bash calls —
+the daemon model that `chrome-devtools-axi` and `cdp-cli launch` cannot achieve
+under sandboxing.
+
+## Prerequisites
+
+This skill's pinned launch invocation depends on two Safehouse features being
+enabled in `~/.config/zsh/agents.zsh` `safe`: `agent-browser` (allows Chrome
+to dlopen its framework and reach Mach ports) and `process-control` (allows
+daemon liveness checks). If they're missing, `agent-browser open` fails with
+`Auto-launch failed: CDP response channel closed`.
+
+## First Launch: Pin the Args
+
+Chrome inside `agent-safehouse` **must** be launched with `--no-sandbox`
+(Safehouse's outer Seatbelt blocks Chrome's inner sandbox from re-initializing)
+and `--ignore-certificate-errors` (the Cloudflare Zero Trust CA is plumbed to
+Node but not Chrome). Pass both via `--args` on the first call after a fresh
+shell or after `agent-browser close`:
+
+```bash
+agent-browser --args "--no-sandbox,--ignore-certificate-errors" open https://example.com
+```
+
+**Args stick to the running daemon.** Subsequent calls do not need `--args`
+and will warn "daemon already running" if you pass them anyway. To change
+launch args, run `agent-browser close` first, then re-open with new args.
+
+## Core Workflow
+
+After `open`, every command targets the live page:
+
+```bash
+agent-browser snapshot                     # AX tree with @ref handles
+agent-browser click @e2                    # click ref from snapshot
+agent-browser fill @e5 "user@example.com"
+agent-browser type "search query"
+agent-browser press Enter
+agent-browser screenshot /tmp/out.png
+agent-browser open <new-url>               # navigate same daemon
+agent-browser close                        # tear down
+```
+
+Refs (`@e1`, `@e2`, …) come from the most recent `snapshot` and are stable
+within the page; re-snapshot after navigation or DOM mutations.
+
+## Upstream Skills (Authoritative Reference)
+
+The CLI ships its own version-matched documentation. Load the upstream skill
+for the full command reference and patterns:
+
+```bash
+agent-browser skills get core --full       # full command reference + templates
+agent-browser skills list                  # specialized skills (Electron, Slack, …)
+```
+
+Prefer the upstream skill over guessing from `agent-browser --help`. This
+file's job is just to pin the sandbox-correct launch invocation and explain
+the daemon-args lifecycle.
+
+## When Not to Use This Skill
+
+- **Need to drive an existing user Chrome session** (cookies, logged-in
+  state, extensions) — agent-browser uses its own clean profile. Use
+  [cli-cdp](../cli-cdp/SKILL.md) in attach mode against a Chrome the user
+  launched manually.
+- **One-shot screenshot or PDF with no follow-up interaction, in a context
+  without MCP browser tools** — [cli-playwright](../cli-playwright/SKILL.md)'s
+  stateless `screenshot`/`pdf` commands are lighter than spinning up the
+  daemon.
+- **MCP browser tools are available** (e.g. Amp's `mcp__chrome_devtools__*`)
+  — those run outside the sandbox and have richer DevTools coverage.

.agents/skills/cli-cdp/SKILL.md

@@ -11,14 +11,55 @@ debugging.
 
 ## Prerequisites
 
-Chrome must be running with `--remote-debugging-port`:
+Chrome must be running with `--remote-debugging-port`. **First check whether
+you can launch it yourself or must ask the user to launch it externally.**
+
+### Step 1: Detect the sandbox
+
+```bash
+echo "${APP_SANDBOX_CONTAINER_ID:-none}"
+```
+
+- **`none` (unsandboxed)** — you can run `cdp-cli launch` yourself; it spawns
+  Chrome on port 9223 with a clean profile under `$TMPDIR`.
+- **`agent-safehouse` (or any other sandbox)** — `cdp-cli launch` reports
+  `{"success":true}` but the Chrome it spawns crashes silently with SIGABRT
+  because its launch args lack `--no-sandbox` and there is no flag to add
+  one. **You must use attach mode** (Step 2).
+
+### Step 2a: Unsandboxed — self-launch
+
+```bash
+cdp-cli launch
+cdp-cli tabs                    # confirm a page is listed
+```
+
+### Step 2b: Sandboxed — ask the user to launch Chrome externally
+
+Stop and ask the user to run this in a **non-sandboxed Terminal window**
+(Terminal.app or iTerm, not cmux):
+
+```bash
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --remote-debugging-port=9223 \
+  --user-data-dir="$HOME/.chrome-debug-profile" \
+  about:blank
+```
+
+The separate `--user-data-dir` keeps it isolated from the user's main Chrome
+profile so both can run at the same time. Tell the user to leave that
+terminal window open — closing it kills Chrome.
+
+After they confirm Chrome is open, verify connectivity from your shell:
 
 ```bash
-cdp-cli launch                  # macOS: launches Chrome with debugging on :9223
+curl -s http://localhost:9223/json/version | head -3   # should return JSON
+cdp-cli tabs                                           # should list the page
 ```
 
-Or start Chrome manually with `--remote-debugging-port=9222` and pass
-`--cdp-url http://localhost:9222`.
+From here every other `cdp-cli` command works normally — TCP to localhost
+is allowed through the sandbox; only Chrome's own dlopen and process spawn
+are blocked.
 
 ## Page Identification
 

.agents/skills/cli-chrome-axi/SKILL.md

@@ -5,6 +5,17 @@ description: 'Uses the chrome-devtools-axi CLI for browser automation, accessibi
 
 # chrome-devtools-axi
 
+## Sandbox Compatibility — Check First
+
+Run `echo "${APP_SANDBOX_CONTAINER_ID:-none}"` before using this skill.
+
+- **`agent-safehouse`**: **DO NOT use this skill.** The CLI's persistent
+  bridge daemon cannot detach from the Bash subprocess under Seatbelt and
+  times out at startup (`Bridge failed to start within 30s`). Use
+  [cli-agent-browser](../cli-agent-browser/SKILL.md) for daemon-style
+  browser work or [cli-playwright](../cli-playwright/SKILL.md) for one-shots.
+- **`none` (unsandboxed)**: this skill works as documented below.
+
 Use `chrome-devtools-axi` when you want Chrome DevTools automation from the shell with agent-friendly output and stable accessibility refs.
 
 ## Why This CLI

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

@@ -5,6 +5,21 @@ description: 'Deep expertise in cmux — the terminal multiplexer with native br
 
 # cmux — Terminal Multiplexer with Native Browser
 
+## Sandbox Compatibility — Check First
+
+Run `echo "${APP_SANDBOX_CONTAINER_ID:-none}"` and `echo "${CMUX_SURFACE_ID:-none}"`
+before using this skill.
+
+- **`agent-safehouse` and/or `CMUX_SURFACE_ID=none`**: **DO NOT use this skill.**
+  The `cmux` CLI is not reachable from inside the `agent-safehouse` sandbox
+  (its install path is denied), and the `CMUX_WORKSPACE_ID` / `CMUX_SURFACE_ID`
+  env vars assumed below are not injected. For browser tasks, use
+  [cli-agent-browser](../cli-agent-browser/SKILL.md). For terminal/pane
+  interactions you actually need from inside the sandbox, ask the user to
+  run the cmux commands directly.
+- **Unsandboxed cmux pane (both env vars present)**: this skill works as
+  documented below.
+
 cmux manages terminal panes and browser views through a Unix socket CLI.
 You are already running inside cmux — your current pane has env vars
 `CMUX_WORKSPACE_ID` and `CMUX_SURFACE_ID` set automatically.

.agents/skills/cli-playwright/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: cli-playwright
+description: 'One-shot browser captures via the Playwright CLI — screenshots and PDFs of arbitrary URLs with no daemon. Best stateless option for agents that need to capture a page but lack MCP browser tools. Use when you need a single screenshot or PDF of a URL without follow-up interaction. Triggers on: screenshot a page, save page as pdf, capture web page, snapshot a url.'
+---
+
+# Playwright CLI (one-shot)
+
+For agents without MCP browser tools that need a **single page capture** with
+no interaction loop. Each invocation launches Chromium, performs one action,
+and exits — no daemon to manage. Inside `agent-safehouse`, the `playwright-chrome`
+Safehouse feature has already injected `PLAYWRIGHT_MCP_SANDBOX=false` into
+the environment, so Chromium starts cleanly without you setting anything.
+
+For multi-step interaction loops use [cli-agent-browser](../cli-agent-browser/SKILL.md)
+instead — its daemon persists state across calls; Playwright one-shots do not.
+
+## Two Binaries on PATH
+
+This skill is about the **test-runner `playwright`** (from `@playwright/test`),
+which exposes one-shot commands like `screenshot` and `pdf`. The other
+binary, `playwright-cli` (from a separate package), is a daemon wrapper
+around Playwright-MCP — its `--ignore-https-errors` plumbing through config
+files is finicky in this environment, so prefer `agent-browser` for
+daemon-style work.
+
+## Prerequisites
+
+- Safehouse `playwright-chrome` feature must be enabled (auto-injects
+  `PLAYWRIGHT_MCP_SANDBOX=false`). Confirm with `echo $PLAYWRIGHT_MCP_SANDBOX`
+  — should print `false`.
+- Chromium browser must be installed in `~/Library/Caches/ms-playwright/`.
+  If `playwright screenshot` errors with "Executable doesn't exist", run:
+  ```bash
+  playwright install chromium
+  ```
+  This downloads to a cached location Safehouse already permits, no `sudo`.
+
+## Core Commands
+
+```bash
+# Screenshot — always pass --ignore-https-errors for Cloudflare-gated sites
+playwright screenshot --ignore-https-errors https://example.com /tmp/out.png
+
+# Full-page screenshot
+playwright screenshot --ignore-https-errors --full-page <url> <file>
+
+# PDF (uses Chromium printing pipeline)
+playwright pdf --ignore-https-errors <url> /tmp/out.pdf
+
+# Wait for content before capturing
+playwright screenshot --ignore-https-errors \
+  --wait-for-selector ".loaded" \
+  --wait-for-timeout 5000 \
+  <url> <file>
+
+# Emulate device / color scheme
+playwright screenshot --ignore-https-errors \
+  --device "iPhone 11" --color-scheme dark \
+  <url> <file>
+```
+
+## Always Pass `--ignore-https-errors`
+
+The `safe` function forwards the Cloudflare Zero Trust root CA to Node
+(`NODE_EXTRA_CA_CERTS`), but **Chromium does not honor that env var** — it
+uses its own cert store, which doesn't include the Cloudflare gateway CA.
+Without `--ignore-https-errors`, any HTTPS URL routed through the gateway
+fails with `net::ERR_CERT_AUTHORITY_INVALID`.
+
+## Common Pitfalls
+
+- **`playwright open <url>` is interactive** and will hang the Bash tool —
+  use `screenshot` or `pdf` for one-shot capture, or `cli-agent-browser`
+  for interactive flows.
+- **`playwright codegen`** records user actions — useless from an
+  agent shell.
+- **`playwright test`** runs a `playwright.config.ts` test suite — not a
+  general-purpose browser CLI.