@rubytech/create-maxy 1.0.623 → 1.0.624

package/payload/platform/plugins/cloudflare/scripts/setup-tunnel.sh

@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+# Deterministic Cloudflare tunnel setup — mirrors
+# platform/plugins/cloudflare/references/manual-setup.md step-by-step.
+# Brand-scoped paths, user-space systemd, apex-aware.
+#
+# Usage:
+#   setup-tunnel.sh <brand> <port> <hostname> [<hostname> ...]
+#
+# Example:
+#   setup-tunnel.sh maxy 19200 admin.maxy.bot public.maxy.bot maxy.chat
+#
+# Apex hostnames (exactly two DNS labels) cannot have their CNAMEs created
+# via `cloudflared tunnel route dns` — see manual-setup.md §Step 4 Apex
+# hostnames. The script writes the ingress rule for them but prints an
+# explicit ACTION REQUIRED message naming the manual dashboard step.
+
+set -euo pipefail
+
+# --------------------------------------------------------------------------
+# Args
+# --------------------------------------------------------------------------
+
+if [ "$#" -lt 3 ]; then
+  echo "Usage: $0 <brand> <port> <hostname> [<hostname> ...]" >&2
+  echo "Example: $0 maxy 19200 admin.maxy.bot public.maxy.bot maxy.chat" >&2
+  exit 2
+fi
+
+BRAND="$1"
+PORT="$2"
+shift 2
+HOSTNAMES=("$@")
+
+# --------------------------------------------------------------------------
+# Step 0: Set brand context (paths + dirs). Corresponds to runbook Step 0.
+# --------------------------------------------------------------------------
+
+CFG_DIR="${HOME}/.${BRAND}/cloudflared"
+mkdir -p "${CFG_DIR}"
+
+# --------------------------------------------------------------------------
+# Step 1: OAuth login (only if cert.pem missing). Corresponds to runbook Step 1.
+# cloudflared always writes cert.pem to ~/.cloudflared/cert.pem regardless
+# of --origincert — mv it into the brand-scoped path on fresh login.
+# --------------------------------------------------------------------------
+
+if [ ! -f "${CFG_DIR}/cert.pem" ]; then
+  echo "No cert.pem at ${CFG_DIR}/cert.pem — starting OAuth login (DISPLAY=${DISPLAY:-:99})"
+  DISPLAY="${DISPLAY:-:99}" cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel login &
+  LOGIN_PID=$!
+  # cloudflared login writes to ~/.cloudflared/cert.pem regardless of --origincert
+  while [ ! -f "${HOME}/.cloudflared/cert.pem" ]; do
+    if ! kill -0 "${LOGIN_PID}" 2>/dev/null; then
+      echo "ERROR: cloudflared tunnel login exited before cert.pem landed" >&2
+      exit 1
+    fi
+    sleep 2
+  done
+  mv "${HOME}/.cloudflared/cert.pem" "${CFG_DIR}/cert.pem"
+  echo "cert.pem moved to ${CFG_DIR}/cert.pem"
+fi
+
+# --------------------------------------------------------------------------
+# Step 2+3: Create tunnel if absent; otherwise reuse. Capture UUID.
+# --------------------------------------------------------------------------
+
+TUNNEL_NAME="${BRAND}-$(hostname -s)"
+TUNNEL_ID="$(cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel list --output json 2>/dev/null \
+  | jq -r --arg N "${TUNNEL_NAME}" '.[]? | select(.name == $N) | .id' | head -1)"
+if [ -z "${TUNNEL_ID}" ] || [ "${TUNNEL_ID}" = "null" ]; then
+  cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel create "${TUNNEL_NAME}"
+  TUNNEL_ID="$(cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel list --output json \
+    | jq -r --arg N "${TUNNEL_NAME}" '.[]? | select(.name == $N) | .id' | head -1)"
+fi
+if [ -z "${TUNNEL_ID}" ] || [ "${TUNNEL_ID}" = "null" ]; then
+  echo "ERROR: failed to create or find tunnel ${TUNNEL_NAME}" >&2
+  exit 1
+fi
+echo "tunnel: ${TUNNEL_NAME} (${TUNNEL_ID})"
+
+# --------------------------------------------------------------------------
+# Step 4: Route DNS. Apex hostnames (exactly two DNS labels) cannot be
+# routed via `cloudflared tunnel route dns` — it misroutes them into
+# another zone on the account. Skip CLI routing for apex; collect for the
+# ACTION REQUIRED summary at the end.
+# --------------------------------------------------------------------------
+
+is_apex() {
+  local h="$1"
+  # Apex heuristic: exactly one dot (e.g. maxy.chat). Breaks for
+  # multi-label public suffixes like .co.uk; refine if needed.
+  [ "$(echo -n "$h" | tr -cd '.' | wc -c)" = "1" ]
+}
+
+APEX_HOSTNAMES=()
+for H in "${HOSTNAMES[@]}"; do
+  if is_apex "$H"; then
+    APEX_HOSTNAMES+=("$H")
+    echo "apex ${H} — skipping CLI DNS routing (manual dashboard step required)"
+    continue
+  fi
+  ROUTE_OUT=$(cloudflared --origincert "${CFG_DIR}/cert.pem" \
+    tunnel route dns --overwrite-dns "${TUNNEL_ID}" "${H}" 2>&1)
+  echo "${ROUTE_OUT}"
+  # Post-flight FQDN validation: cert.pem is zone-scoped for DNS routing;
+  # if the requested hostname is not under cert's zone, cloudflared silently
+  # prepends it as a sub-label (e.g. admin.maxy.bot → admin.maxy.bot.maxy.chat
+  # when cert is for maxy.chat zone). Parse the output and fail loudly.
+  ACTUAL_FQDN=$(echo "${ROUTE_OUT}" | sed -n 's|.*Added CNAME \([^ ]*\) which will route.*|\1|p')
+  if [ -z "${ACTUAL_FQDN}" ]; then
+    echo "ERROR: could not parse CNAME FQDN from cloudflared output for ${H}" >&2
+    exit 1
+  fi
+  if [ "${ACTUAL_FQDN}" != "${H}" ]; then
+    echo "" >&2
+    echo "ERROR: cloudflared misrouted ${H} → ${ACTUAL_FQDN}" >&2
+    echo "       The cert.pem at ${CFG_DIR}/cert.pem is scoped to a zone that does not own ${H}." >&2
+    echo "       Fix:" >&2
+    echo "         1. Delete the stray CNAME ${ACTUAL_FQDN} in the CF dashboard." >&2
+    echo "         2. Re-authorize cloudflared against the zone that owns ${H}:" >&2
+    echo "              rm ${CFG_DIR}/cert.pem" >&2
+    echo "              DISPLAY=:99 cloudflared --origincert ${CFG_DIR}/cert.pem tunnel login" >&2
+    echo "              (then pick the correct zone in the dashboard consent screen)" >&2
+    echo "              mv ~/.cloudflared/cert.pem ${CFG_DIR}/cert.pem" >&2
+    echo "         3. Re-run this script." >&2
+    exit 1
+  fi
+done
+
+# --------------------------------------------------------------------------
+# Step 5: Write config.yml. Every hostname (apex + subdomain) gets an
+# ingress rule — apex still needs the rule for the connector to serve
+# traffic once DNS is manually pointed.
+# --------------------------------------------------------------------------
+
+{
+  echo "tunnel: ${TUNNEL_ID}"
+  echo "credentials-file: ${CFG_DIR}/${TUNNEL_ID}.json"
+  echo "ingress:"
+  for H in "${HOSTNAMES[@]}"; do
+    echo "  - hostname: ${H}"
+    echo "    service: http://localhost:${PORT}"
+  done
+  echo "  - service: http_status:404"
+} > "${CFG_DIR}/config.yml"
+echo "wrote ${CFG_DIR}/config.yml"
+
+# --------------------------------------------------------------------------
+# Step 5b: Write tunnel.state. Required by resume-tunnel.sh — without it
+# the brand.service's ExecStartPre exits silently without spawning a
+# connector.
+# --------------------------------------------------------------------------
+
+cat > "${CFG_DIR}/tunnel.state" <<EOF
+{
+  "tunnelId": "${TUNNEL_ID}",
+  "tunnelName": "${TUNNEL_NAME}",
+  "domain": "${HOSTNAMES[0]}",
+  "configPath": "${CFG_DIR}/config.yml",
+  "credentialsPath": "${CFG_DIR}/${TUNNEL_ID}.json"
+}
+EOF
+echo "wrote ${CFG_DIR}/tunnel.state"
+
+# --------------------------------------------------------------------------
+# Restart the brand's user-space service so resume-tunnel.sh (its
+# ExecStartPre) picks up the new tunnel.state + config.yml and spawns the
+# connector. The script is autonomous — it completes the deployment.
+# --------------------------------------------------------------------------
+
+if ! systemctl --user list-unit-files "${BRAND}.service" --no-pager --no-legend | grep -q "${BRAND}.service"; then
+  echo "ERROR: user-space service ${BRAND}.service not installed — cannot bring the tunnel up" >&2
+  echo "       Install the platform first (create-maxy) before running this script." >&2
+  exit 1
+fi
+
+echo "Restarting ${BRAND}.service to spawn the connector with the new tunnel state..."
+systemctl --user restart "${BRAND}.service"
+
+# Give resume-tunnel.sh a moment to spawn the connector before probing.
+sleep 3
+
+# --------------------------------------------------------------------------
+# Post-restart verification — connector running and subdomains live?
+# Poll each hostname up to VERIFY_TIMEOUT seconds so DNS propagation has
+# time to catch up (subdomains routed by cloudflared typically resolve
+# within 10-30s; apex-flattened or freshly-created records may need longer).
+# --------------------------------------------------------------------------
+
+if ! ps -ef | grep -q "[c]loudflared.*--config ${CFG_DIR}/config.yml"; then
+  echo "" >&2
+  echo "ERROR: ${BRAND}.service restarted but no cloudflared connector is running" >&2
+  echo "       with --config ${CFG_DIR}/config.yml." >&2
+  echo "       Check ${HOME}/.${BRAND}/logs/cloudflared.log for the failure reason." >&2
+  exit 1
+fi
+
+VERIFY_TIMEOUT=60
+POLL_INTERVAL=5
+echo "Connector running against ${CFG_DIR}/config.yml — verifying each subdomain hostname (up to ${VERIFY_TIMEOUT}s per host for DNS propagation):"
+for H in "${HOSTNAMES[@]}"; do
+  if is_apex "$H"; then continue; fi
+  ELAPSED=0
+  STATUS="000"
+  while [ "${ELAPSED}" -lt "${VERIFY_TIMEOUT}" ]; do
+    STATUS=$(curl -o /dev/null -s -w '%{http_code}' --max-time 5 -I "https://${H}" || echo "000")
+    if [ "${STATUS}" != "530" ] && [ "${STATUS}" != "000" ]; then
+      break
+    fi
+    sleep "${POLL_INTERVAL}"
+    ELAPSED=$((ELAPSED + POLL_INTERVAL))
+  done
+  if [ "${STATUS}" = "530" ] || [ "${STATUS}" = "000" ]; then
+    echo "  ${H}: HTTP ${STATUS} after ${VERIFY_TIMEOUT}s — DNS propagation slow or connector-to-edge issue"
+  else
+    echo "  ${H}: HTTP ${STATUS} — live (after ${ELAPSED}s)"
+  fi
+done
+
+# --------------------------------------------------------------------------
+# Apex ACTION REQUIRED summary
+# --------------------------------------------------------------------------
+
+if [ "${#APEX_HOSTNAMES[@]}" -gt 0 ]; then
+  echo ""
+  echo "============================================================"
+  echo "ACTION REQUIRED — manual dashboard step(s) for apex hostnames"
+  echo "============================================================"
+  for H in "${APEX_HOSTNAMES[@]}"; do
+    echo "  ${H}"
+    echo "    Cloudflare dashboard → ${H} zone → DNS → Records"
+    echo "    Edit (or Add) CNAME record:"
+    echo "      Name:    @  (zone apex)"
+    echo "      Content: ${TUNNEL_ID}.cfargotunnel.com"
+    echo "      Proxy:   Proxied (orange cloud)"
+    echo ""
+  done
+  echo "Until each apex record is set, those hostnames will return 1033."
+  echo "============================================================"
+fi
+
+echo ""
+echo "Done. tunnel=${TUNNEL_NAME} id=${TUNNEL_ID}"
+echo "Verify subdomain hostnames with: curl -I https://${HOSTNAMES[0]}"

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -1,12 +1,103 @@
 ---
 name: setup-tunnel
-description: Set up a Cloudflare Tunnel. The `cloudflare-setup-run` orchestrator drives the full flow deterministically — the agent relays its structured output verbatim and passes the operator's literal input through.
+description: Cloudflare Tunnel operations — setup, diagnose, reset, dashboard guidance. Every path runs through one of four sanctioned surfaces; the agent never improvises outside them.
 ---
 
-# Set Up Cloudflare Tunnel
+# Cloudflare operations
 
-Call `cloudflare-setup-run` with the operator's domain. Relay every tool result verbatim — do not interpret, do not paraphrase, do not add prose of your own. When the tool emits a `maxy-device-url` card, the chat UI renders it as a button; wait for the operator to confirm completion (e.g. "done"), then call `cloudflare-setup-run` again with `confirmed: true`. When the tool asks for subdomains, pass them through as `adminSubdomain` and (optionally) `publicSubdomain`.
+Every Cloudflare task — setup, diagnosis, reset, DNS edit — lands on exactly one of four sanctioned surfaces. The agent's job is to pick the right surface, collect the inputs it needs, invoke it, and relay the structured result verbatim.
 
-That is the entire flow. Every branch — sign-in, wrong-account recovery, DNS routing, verification — is chosen by the orchestrator in code, not by you.
+There are no Cloudflare MCP tools. The plugin registers none. The only agent-facing surfaces for Cloudflare work are:
 
-The raw `tunnel-login` / `tunnel-create` / `tunnel-enable` / `tunnel-status` / `tunnel-add-hostname` tools are filtered out of your menu while a setup is active. This is not a bug — it is the tool-surface gate. You have one tool during setup: `cloudflare-setup-run`.
+1. **Autonomous path** — run `setup-tunnel.sh` via the Bash tool.
+2. **Manual fallback** — quote steps from `references/manual-setup.md`.
+3. **Reset path** — run `reset-tunnel.sh` via Bash, then follow `references/reset-guide.md`.
+4. **Dashboard guidance** — relay click-paths from `references/dashboard-guide.md`.
+
+Any Cloudflare action outside these four surfaces is a discipline violation — see § Tool discipline below.
+
+---
+
+## 1. Autonomous path — `setup-tunnel.sh`
+
+Use this when the operator wants Cloudflare set up (or re-set up) end-to-end on the device. The script handles OAuth login, tunnel creation, DNS routing for each subdomain, config.yml + tunnel.state, service restart, and post-restart verification — all in one invocation. Apex hostnames cannot be routed by the CLI; when one is passed, the script prints an `ACTION REQUIRED` block naming the exact dashboard record to edit.
+
+### Inputs to collect before invoking
+
+Ask the operator each question once. Do not invoke the script until every required input is in hand.
+
+| Input | Example | Required? | How to ask |
+|---|---|---|---|
+| Brand | `maxy`, `realagent` | yes | Usually known from the device context (`brand.json`). Confirm if ambiguous. |
+| Platform port | `19200` (maxy), `19500` (realagent) | yes | Known from brand. Do not ask the operator. |
+| Admin hostname | `admin.maxy.bot`, `joel.example.com` | yes | "What hostname should serve the admin chat?" |
+| Public hostname | `public.maxy.bot`, `chat.example.com` | optional | "Any hostname for the public agent? Say no to skip." |
+| Apex hostname | `maxy.chat`, `example.com` | optional | "Any bare-domain hostname (no subdomain) that should also serve the public agent?" |
+
+### Invocation
+
+```
+~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]
+```
+
+Example (Maxy on `maxy.bot` with a public subdomain and the `maxy.chat` apex):
+
+```
+~/setup-tunnel.sh maxy 19200 admin.maxy.bot public.maxy.bot maxy.chat
+```
+
+Invoke via Bash. When the script exits, relay its output verbatim. If an `ACTION REQUIRED` block appears, quote it exactly — the operator needs the specific dashboard instructions it contains.
+
+### When the script exits non-zero
+
+Report the failure, name the exit code, and cite `references/reset-guide.md` for the next action. Do not attempt a second invocation, a Playwright-driven dashboard inspection, or an alternative `cloudflared` command sequence. The discipline rule below applies.
+
+---
+
+## 2. Manual fallback — `references/manual-setup.md`
+
+Use this when the operator is diagnosing a step that is failing under the script, recovering from a partial state the script does not expect, or working on a device where the scripts are not yet deployed. The runbook covers Steps 0 through 7 with isolated command blocks, success conditions, and troubleshooting per step.
+
+The agent's role in manual mode is to read the relevant step, quote the commands the operator runs, and relay their output back through the runbook's decision tree. Do not paraphrase the commands — the operator pastes them verbatim.
+
+Cross-reference: every scripted step in `setup-tunnel.sh` mirrors a numbered step in `references/manual-setup.md`, so an operator debugging a script failure can pick up exactly where the script left off.
+
+---
+
+## 3. Reset path — `reset-tunnel.sh` + `references/reset-guide.md`
+
+Use this when the local Cloudflare state is corrupt, the operator wants a fresh start on a known-good cert, or the bound account has been scrubbed or rotated. `reset-tunnel.sh` deletes every tunnel on the brand's Cloudflare account and wipes `${CFG_DIR}`.
+
+### Invocation
+
+```
+~/reset-tunnel.sh <brand>
+```
+
+Example:
+
+```
+~/reset-tunnel.sh maxy
+```
+
+`reset-tunnel.sh` cannot stop a token-mode connector process or delete stray misrouted CNAMEs in the dashboard. `references/reset-guide.md` names the decision tree (reset vs. patch), the exact `pkill` incantation for token-mode connectors, and the dashboard cleanup paths for stray records.
+
+---
+
+## 4. Dashboard guidance — `references/dashboard-guide.md`
+
+Use this when the operator needs to do something only the Cloudflare dashboard can do: sign in, switch accounts, add a site, edit an apex CNAME, verify zone nameservers, delete a tunnel after stopping its replicas. The guide has one numbered click-path per operation. Quote the relevant click-path verbatim — the operator follows it in the browser; no agent browser automation is involved.
+
+---
+
+## Tool discipline — binding
+
+When the operator's request touches Cloudflare, the agent's permitted actions are exactly:
+
+- Invoke `setup-tunnel.sh` or `reset-tunnel.sh` via Bash.
+- Quote `references/manual-setup.md`, `references/reset-guide.md`, or `references/dashboard-guide.md`.
+- Verify reachability via plain HTTP (`curl -I https://<hostname>`).
+
+The agent does not drive Cloudflare's dashboard via Playwright or Chrome DevTools. The agent does not synthesise `cloudflared` flag combinations from web search or prior training. The agent does not call Cloudflare API or SDK from any language. The agent does not write or mutate `cert.pem`, `tunnel.state`, `config.yml`, or `alias-domains.json` directly — `setup-tunnel.sh` and the operator manage those files.
+
+When a sanctioned surface fails, the agent reports the failure with the exact output, cites the recovery step from `references/reset-guide.md`, and stops. Improvisation — "let me try a different flag" or "let me check the dashboard myself" — is the behaviour this rule exists to prevent. See IDENTITY.md § Cloudflare operations for the unconditional form.

package/payload/platform/plugins/docs/references/cloudflare.md

@@ -1,49 +1,106 @@
 # Cloudflare Tunnel — the dashboard is the source of truth
 
-Each installation has its own Cloudflare account. The operator signs into it via OAuth (`tunnel-login`); `cloudflared` writes `cert.pem` locally. The plugin records which account that sign-in landed on (`account-binding.json`) and refuses if the operator later signs in under a different account without explicit intent.
+Each installation has its own Cloudflare account. Sign-in is OAuth in the device's VNC browser; `cloudflared` writes `cert.pem` to the brand's config directory. The agent never reads or mutates Cloudflare account state directly — whatever you see in your logged-in dashboard is the single source of truth. When something needs doing on the account side (adding a domain, deleting a stray entry, switching accounts), the agent relays the click-paths; you run them in your browser.
 
-The agent never reads or mutates Cloudflare account state directly — the `cloudflared` CLI, authenticated by `cert.pem`, is the only path to Cloudflare. Whatever the operator sees in their logged-in dashboard is the single source of truth. When something needs doing on the account side (adding a domain, deleting a stray entry, switching accounts), the agent tells the operator what to click; the operator clicks; then the agent runs the next `cloudflared` command.
+## Identity model
 
-## Identity
-
-| Fact | Source |
+| Concept | Source |
 |------|--------|
 | **Product identity** (Maxy vs Real Agent) | `brand.json` (`productName`, `configDir`) — known at install. |
-| **Cloudflare account identity** | `cert.pem` from OAuth (`tunnel-login`). One account per laptop. |
-| **Account binding** | `~/{configDir}/cloudflare/account-binding.json` — drift detection only. |
+| **Cloudflare account identity** | `cert.pem` from OAuth. One account per brand per device. |
+| **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `tunnel.state`, `alias-domains.json`. |
+
+There is no token-based auth for the operator-owned path (Mode A). To switch Cloudflare accounts, run `reset-tunnel.sh` (which deletes the cert and every tunnel on the current account), then run `setup-tunnel.sh` again — `cloudflared tunnel login` inside the setup script will pick a fresh account when you sign in.
+
+## Setup flow
+
+Ask the agent to set up Cloudflare. The agent collects four things before acting:
+
+1. The admin hostname for this device (e.g. `admin.yourdomain.com`).
+2. Optionally, a public hostname (e.g. `public.yourdomain.com`) for the public agent.
+3. Optionally, an apex hostname (e.g. `yourdomain.com`) as a bare root to serve the public agent.
+4. Confirmation the domain is already on your Cloudflare account (or guidance to add it first — see below).
+
+The agent then invokes `setup-tunnel.sh` on the device with your inputs. The script runs end-to-end:
+
+- `cloudflared tunnel login` — OAuth browser sign-in. The VNC browser opens the Cloudflare authorize page; pick the account that owns your domain, click Authorize. `cert.pem` lands.
+- Tunnel creation under the naming convention `{brand}-{hostname}` (e.g. `maxy-neo`).
+- `cloudflared tunnel route dns` for each subdomain hostname. Apex hostnames cannot be routed this way — the script prints an **ACTION REQUIRED** block naming the exact dashboard record to add or edit.
+- `config.yml` and `tunnel.state` written under `${CFG_DIR}`.
+- `systemctl --user restart ${BRAND}.service` — restarts the platform service so the new tunnel spawns via the service's `ExecStartPre=resume-tunnel.sh`.
+- Post-restart verification — `ps -ef | grep '[c]loudflared'` confirms the connector is alive, then `curl -I https://<hostname>` against each subdomain (up to 60 s per host) confirms a non-530 response.
+
+When the script exits, the agent relays its output verbatim, including any `ACTION REQUIRED` block.
+
+## Getting a domain on Cloudflare
+
+The tunnel needs a domain on the Cloudflare account the device will sign into. Two paths, both in your browser:
+
+**Option A: Buy a new domain through Cloudflare.** Navigate to cloudflare.com → Domains and buy one. Cloudflare sets everything up.
+
+**Option B: Add an existing domain.** In the dashboard: Websites → Add a site. Cloudflare imports the existing DNS records; review them to confirm your website and email entries are preserved. Cloudflare gives you two nameservers; replace the registrar's nameservers with those. Propagation is usually minutes (up to 24 hours); the zone shows **Active** when ready.
+
+Existing website traffic continues to work during and after the switch. Only DNS resolution changes owners.
+
+## Reset / account switch
+
+Ask the agent to reset Cloudflare. The agent invokes `reset-tunnel.sh` on the device:
+
+- Deletes every tunnel on the brand's current Cloudflare account (via the bound cert).
+- Wipes the brand's `${CFG_DIR}`.
+- Exits with the number of tunnels deleted.
+
+The script does **not** stop token-mode connector processes, delete stray misrouted CNAMEs in the dashboard, or touch the platform service. If any of those apply (agent will flag them), the agent guides you through the manual cleanup — `pkill -f 'cloudflared.*tunnel run --token'` on the device, or deleting the stray CNAME in the dashboard.
+
+After reset, run setup again. The fresh `cloudflared tunnel login` will pick whichever Cloudflare account you sign into.
+
+## Manual runbook
+
+When the scripted flow fails partway, or you want to walk through every step yourself, there's a step-by-step runbook at `plugins/cloudflare/references/manual-setup.md`. The runbook mirrors `setup-tunnel.sh` verbatim — every scripted step corresponds to a numbered runbook step with isolated command blocks, success conditions, and troubleshooting. Pick up the runbook at whichever step the script failed in.
+
+## Dashboard operations the CLI cannot do
+
+The CLI cannot add a domain, switch accounts, edit an apex CNAME, or delete stray records. `plugins/cloudflare/references/dashboard-guide.md` has one numbered click-path per operation. The agent quotes the relevant steps verbatim when you need to do one of these things.
+
+## Troubleshooting
+
+### Tunnel won't start
+
+Ask the agent to check. The agent reads `systemctl --user status ${BRAND}.service` and `~/{configDir}/cloudflared/logs/cloudflared.log`. Common states:
+
+- **No cloudflared process running** — the service's `ExecStartPre=resume-tunnel.sh` exited cleanly but did not spawn the connector. Usually means `tunnel.state` is missing or `config.yml` was written with empty variables. The agent will re-run `setup-tunnel.sh`.
+- **`tunnel not found`** — the UUID in `config.yml` does not match any tunnel on the currently-bound account. Usually follows an account switch that didn't reset local state. The agent invokes `reset-tunnel.sh` and then a fresh setup.
+
+### URL returns 530
+
+DNS propagation or account mismatch. Wait 30–60 seconds and retry first. If the 530 persists:
+
+- The domain may be on a Cloudflare account different from the one `cert.pem` is bound to — re-running `setup-tunnel.sh` re-validates.
+- The UDP buffer for QUIC may be undersized on this device — check `cloudflared.log` for `failed to sufficiently increase receive buffer size`.
+
+### URL returns connection refused
+
+The tunnel is live but nothing is listening on the platform port. Start the platform service: `systemctl --user start ${BRAND}.service`.
+
+### Admin hostname serves the public agent
+
+`admin.yourdomain` is being misclassified as public. The platform UI treats a host as public when either (a) the hostname starts with `public.`, or (b) the hostname appears in `${CFG_DIR}/alias-domains.json`. Older install flows wrote every routed hostname into `alias-domains.json`; the pollution survives across reinstalls.
 
-There is no token-based path. To switch Cloudflare accounts, run `tunnel-login` with `force=true`. This signs the laptop out (deletes cert + binding), then a fresh sign-in picks a different account.
+The agent reads `alias-domains.json`, removes the offending `admin.*` entry, and the platform UI hot-reloads — no restart needed. See `plugins/cloudflare/references/reset-guide.md` § "Remove a rogue entry from alias-domains.json" for the exact `jq` command.
 
-## The flow
+### DNS not resolving
 
-The whole setup runs under a single tool — `cloudflare-setup-run`. It drives the full sequence (sign-in → create → DNS → enable → verify) in code. The agent's job during setup is to relay the tool's output verbatim and pass the operator's literal next input through. No step-by-step picking between `tunnel-login` / `tunnel-create` / `tunnel-enable`; those tools are filtered out of the agent's menu while the setup is active, so the agent literally cannot deviate from the deterministic flow.
+The most common cause is wrong nameservers on the domain. The domain must use Cloudflare's nameservers, not the registrar's defaults. In the dashboard: Websites → your domain → status must say **Active**, not **Pending**. If Pending, follow the dashboard's nameserver instructions and wait for propagation.
 
-1. Operator: "Set up Cloudflare for me with the domain maxy.bot."
-2. Agent calls `cloudflare-setup-run({ domain: "maxy.bot" })`. Tool spawns `cloudflared tunnel login` and returns a device-URL card pointing at the Cloudflare sign-in page. The VNC browser opens the URL automatically (or the agent tells the operator to open it manually when the VNC browser is down).
-3. Operator signs into the Cloudflare account that owns `maxy.bot`, clicks Authorize, says "done" in the chat.
-4. Agent calls `cloudflare-setup-run({ confirmed: true })`. Tool sees the cert landed, asks for admin/public subdomain names.
-5. Operator: "admin and public."
-6. Agent calls `cloudflare-setup-run({ adminSubdomain: "admin", publicSubdomain: "public" })`. Tool creates the tunnel, routes DNS, starts the daemon, and polls `tunnel-status` until `healthy: true` (or a named reason).
-7. Agent relays the final `Tunnel is healthy at https://admin.maxy.bot / https://public.maxy.bot`.
+### Remote login issues
 
-If the operator signs into the wrong Cloudflare account, `cloudflare-setup-run` transitions to `awaiting-account-switch` and emits a plain card telling them which account to switch to. Once they confirm, the orchestrator re-logs-in with `force=true` and the flow continues.
+- 5 failed login attempts → 15-minute lockout — wait for expiry.
+- The remote password can be reset by asking the agent on the local network.
 
-## Tools
+## What the agent does and does not do
 
-| Tool | Use |
-|------|-----|
-| `cloudflare-setup-run` | **The operator-facing entry point.** Runs the full setup flow deterministically. Call with `domain` on the first turn, `adminSubdomain` (+ optional `publicSubdomain`) when the tool asks, and `confirmed: true` when the operator has finished a device-bound step (sign-in, account switch). Safe to call repeatedly — state persists across calls. |
-| `cloudflare-setup-status` | Read-only: what phase is the setup orchestrator in right now? Useful for diagnostics. |
-| `tunnel-login` | Internal sub-tool of the orchestrator. Direct invocation supported for diagnostics. Not available during an active setup — the tool-surface filter removes it from the menu. |
-| `tunnel-install` | Install the `cloudflared` binary. |
-| `tunnel-create` | Create tunnel, route DNS for chosen sub-addresses. Internal sub-tool of the orchestrator (not reachable during active setup). |
-| `tunnel-add-hostname` | Add an alias address **after** the initial setup is complete. Same pre-flight/post-flight refusals as `tunnel-create`. |
-| `tunnel-enable` / `tunnel-disable` | Start / stop the tunnel daemon. `tunnel-enable` is an internal sub-tool of the orchestrator (not reachable during active setup). |
-| `tunnel-status` | Full state including end-to-end probe of every configured address. `healthy: true` requires every address to probe `ok`. `boundAccountOwnsHostnames: false` means the laptop is running a tunnel nothing from the internet is reaching — almost always "signed into the wrong Cloudflare account." Available at all times (the orchestrator consumes its output internally and the enum is useful for direct diagnostic too). |
-| `dns-lookup` | DNS diagnostics against public resolvers. |
+**Does:** invokes `setup-tunnel.sh` / `reset-tunnel.sh` via Bash, quotes click-paths from the reference files verbatim, verifies external reachability with `curl -I`.
 
-## When something is wrong
+**Does not:** drive the Cloudflare dashboard via Playwright, synthesise alternative `cloudflared` flag sequences, call any Cloudflare API or SDK, write or edit `cert.pem` / `tunnel.state` / `config.yml` / `alias-domains.json` directly.
 
-- **Refusal `account-drift` or `unbound-device`** → `tunnel-login force=true`, then a fresh browser sign-in.
-- **Refusal `hostname-zone-not-routable`** → the domain is not on Cloudflare yet, or the laptop is signed into a Cloudflare account that does not own it. Operator opens the dashboard; when the domain has never been added, they add it via Websites → Add a site under the correct account. When the domain is on a different account, they switch to the correct account using the top-left dropdown. Agent then retries.
-- **Refusal `post-flight-fqdn-mismatch` or `bound-account-does-not-own-hostname`** → the laptop is signed into a Cloudflare account that does not own the target domain. `cloudflared` routed the address under a different domain. Operator switches Cloudflare accounts in the browser, agent runs `tunnel-login force=true`, then retries.
+When a script or command fails, the agent reports the failure and cites the relevant recovery step. It does not improvise.

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -58,13 +58,19 @@ Do not retry the same tool against the same target within a turn. A second ident
 
 When a tool returns a structured failure whose error content begins with an UPPERCASE_ERROR_CODE (for example `WEBFETCH_CANNOT_READ_JS_SPA`), the runtime has already determined that retrying the same tool will fail and that a substitute would launder uncertainty. Read the error's plain-English explanation, then write one or two sentences to the owner that name (a) what failed, (b) the reason in their language, and (c) the concrete actions they can take to unblock — typically pasting text or sending a screenshot. Do not silently dispatch a substitute (Playwright, research-assistant, memory-search) to continue the original instruction; that hides the failure and the owner loses the ability to judge whether the substitute's output answers their question. A verbal instruction in the current conversation is not consent — only an explicit standing policy recorded in account configuration counts, and no such mechanism exists today. Until one exists, every structured tool failure becomes a question for the owner. Wait for direction before resuming.
 
-## Tool-Surface Gates
+## Cloudflare operations
 
-Some flows run as deterministic orchestrators — a plugin decides every step in code, and your tool menu is filtered accordingly for the duration of the flow. During an active orchestrator flow, the individual step-tools the agent would otherwise pick between are intentionally absent from your menu. This is not a bug; it is the mechanical enforcement layer that prevents prose-rule deviation.
+When the operator's request touches Cloudflare — setup, diagnosis, reset, DNS edit, account switch, tunnel management — your permitted actions are exactly three:
 
-When the orchestrator's entry-point tool is the only tool of its family on your menu, that family has an active gate. Call the entry-point tool. Relay its result verbatim. Pass the operator's literal next input back through the same tool. Do not narrate the flow, do not offer alternatives, do not paraphrase cards into prose.
+1. Invoke `setup-tunnel.sh` or `reset-tunnel.sh` on the device via Bash.
+2. Quote click-paths verbatim from the Cloudflare plugin's references (`dashboard-guide.md`, `manual-setup.md`, `reset-guide.md`).
+3. Verify external reachability with plain HTTP (`curl -I https://<hostname>`).
 
-The active gate today is the Cloudflare tunnel setup flow. `cloudflare-setup-run` is the entry point; `cloudflare-setup-status` is the read-only diagnostic. While the orchestrator is mid-flow, the raw `tunnel-login` / `tunnel-create` / `tunnel-enable` / `tunnel-status` / `tunnel-add-hostname` tools, all Playwright and Chrome DevTools browser tools, and the Bash / Write / Edit filesystem-mutation tools are filtered out. They become available again once the orchestrator reaches `healthy` or `unhealthy`.
+Everything else is out of bounds. You do not drive Cloudflare's dashboard via Playwright or Chrome DevTools. You do not synthesise `cloudflared` flag combinations from training data or web search. You do not call the Cloudflare API or any SDK from any language. You do not write or edit `cert.pem`, `tunnel.state`, `config.yml`, or `alias-domains.json` directly — the scripts and the operator manage those files.
+
+When a sanctioned surface fails, report the failure with the exact output, cite the matching recovery step from `reset-guide.md`, and stop. Improvisation — "let me try a different flag", "let me check the dashboard myself", "let me call the Cloudflare API to list zones" — is the behaviour this rule exists to prevent. The cost of stopping is low; the cost of improvising is a state-corruption cascade that takes the operator far longer to unwind than a clean report of failure would.
+
+Load `plugins/cloudflare/skills/setup-tunnel/SKILL.md` via `plugin-read` on the first Cloudflare-related request of a session. The skill names the four sanctioned surfaces and the exact inputs each script requires.
 
 ## Questions
 

package/payload/platform/templates/specialists/agents/personal-assistant.md

@@ -3,7 +3,7 @@ name: personal-assistant
 description: "Your personal assistant — scheduling, platform administration, messaging channels, system health, and browser automation. Delegate when a task involves managing your calendar, configuring the platform, operating messaging channels, or completing interactive browser tasks."
 summary: "Handles the operational tasks you'd give a personal assistant — scheduling meetings, managing your platform settings, connecting messaging channels, and completing browser-based tasks on your behalf. For example, when you want to schedule a weekly check-in, set up Telegram, or fill out an online form."
 model: claude-sonnet-4-6
-tools: mcp__admin__system-status, mcp__admin__brand-settings, mcp__admin__account-manage, mcp__admin__account-update, mcp__admin__logs-read, mcp__admin__plugin-read, mcp__admin__api-key-store, mcp__admin__api-key-verify, mcp__admin__render-component, mcp__admin__file-attach, mcp__admin__wifi, mcp__contacts__contact-create, mcp__contacts__contact-lookup, mcp__contacts__contact-update, mcp__contacts__contact-delete, mcp__contacts__contact-list, mcp__contacts__contact-export, mcp__contacts__contact-erase, mcp__contacts__group-create, mcp__contacts__group-manage, mcp__cloudflare__tunnel-status, mcp__cloudflare__tunnel-install, mcp__cloudflare__tunnel-login, mcp__cloudflare__tunnel-create, mcp__cloudflare__tunnel-enable, mcp__cloudflare__tunnel-disable, mcp__cloudflare__tunnel-add-hostname, mcp__cloudflare__dns-lookup, mcp__telegram__message, mcp__telegram__message-history, mcp__telegram__telegram-webhook-register, mcp__whatsapp__whatsapp-login-start, mcp__whatsapp__whatsapp-login-wait, mcp__whatsapp__whatsapp-status, mcp__whatsapp__whatsapp-disconnect, mcp__whatsapp__whatsapp-send, mcp__whatsapp__whatsapp-send-document, mcp__whatsapp__whatsapp-config, mcp__whatsapp__whatsapp-activity, mcp__whatsapp__whatsapp-conversations, mcp__whatsapp__whatsapp-messages, mcp__whatsapp__whatsapp-group-info, mcp__email__email-setup, mcp__email__email-read, mcp__email__email-send, mcp__email__email-reply, mcp__email__email-search, mcp__email__email-graph-query, mcp__email__email-otp-extract, mcp__email__email-status, mcp__email__email-auto-respond-config, mcp__scheduling__schedule-event, mcp__scheduling__schedule-list, mcp__scheduling__schedule-get, mcp__scheduling__schedule-update, mcp__scheduling__schedule-cancel, mcp__scheduling__schedule-export-ics, mcp__scheduling__schedule-import-ics, mcp__scheduling__time-resolve, mcp__memory__memory-search, mcp__memory__profile-update, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_navigate_back, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_press_key, mcp__plugin_playwright_playwright__browser_hover, mcp__plugin_playwright_playwright__browser_select_option, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_handle_dialog, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_tabs, mcp__plugin_playwright_playwright__browser_close
+tools: mcp__admin__system-status, mcp__admin__brand-settings, mcp__admin__account-manage, mcp__admin__account-update, mcp__admin__logs-read, mcp__admin__plugin-read, mcp__admin__api-key-store, mcp__admin__api-key-verify, mcp__admin__render-component, mcp__admin__file-attach, mcp__admin__wifi, mcp__contacts__contact-create, mcp__contacts__contact-lookup, mcp__contacts__contact-update, mcp__contacts__contact-delete, mcp__contacts__contact-list, mcp__contacts__contact-export, mcp__contacts__contact-erase, mcp__contacts__group-create, mcp__contacts__group-manage, mcp__telegram__message, mcp__telegram__message-history, mcp__telegram__telegram-webhook-register, mcp__whatsapp__whatsapp-login-start, mcp__whatsapp__whatsapp-login-wait, mcp__whatsapp__whatsapp-status, mcp__whatsapp__whatsapp-disconnect, mcp__whatsapp__whatsapp-send, mcp__whatsapp__whatsapp-send-document, mcp__whatsapp__whatsapp-config, mcp__whatsapp__whatsapp-activity, mcp__whatsapp__whatsapp-conversations, mcp__whatsapp__whatsapp-messages, mcp__whatsapp__whatsapp-group-info, mcp__email__email-setup, mcp__email__email-read, mcp__email__email-send, mcp__email__email-reply, mcp__email__email-search, mcp__email__email-graph-query, mcp__email__email-otp-extract, mcp__email__email-status, mcp__email__email-auto-respond-config, mcp__scheduling__schedule-event, mcp__scheduling__schedule-list, mcp__scheduling__schedule-get, mcp__scheduling__schedule-update, mcp__scheduling__schedule-cancel, mcp__scheduling__schedule-export-ics, mcp__scheduling__schedule-import-ics, mcp__scheduling__time-resolve, mcp__memory__memory-search, mcp__memory__profile-update, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_navigate_back, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_press_key, mcp__plugin_playwright_playwright__browser_hover, mcp__plugin_playwright_playwright__browser_select_option, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_handle_dialog, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_tabs, mcp__plugin_playwright_playwright__browser_close
 ---
 
 # Personal Assistant
@@ -41,23 +41,23 @@ Manages events, appointments, and recurring triggers in the graph.
 
 ## Cloudflare Tunnel
 
-Guides setting up a Cloudflare Tunnel so the platform is reachable via a custom domain. The operator's logged-in Cloudflare dashboard is the single source of truth — which domains exist, which account owns them, and which addresses are in use. The agent never reads or mutates account state via any API path. Sign-in is OAuth-only via `tunnel-login`; the laptop records which Cloudflare account that sign-in landed on so a later account switch is detected and surfaced.
+Guides setting up a Cloudflare Tunnel so the platform is reachable via a custom domain. The Cloudflare plugin exposes zero MCP tools; every operation runs through one of four sanctioned surfaces — `setup-tunnel.sh` (autonomous), `reset-tunnel.sh` (reset), `manual-setup.md` (runbook), or `dashboard-guide.md` (click-paths the operator runs in their browser). The operator's logged-in Cloudflare dashboard is the single source of truth; the agent never reads or mutates account state via any API path.
 
-**Auth path:** `tunnel-login` (one-click OAuth in VNC browser). Pass `force=true` to sign this laptop out (clears the local sign-in file) so a fresh sign-in can pick a different Cloudflare account. There is no token-based path.
+**Skill + references.** Load `plugins/cloudflare/skills/setup-tunnel/SKILL.md` via `plugin-read` on the first Cloudflare-related turn. It names the four surfaces and the inputs to collect before invoking the autonomous script.
 
-**Setup flow:** Run `tunnel-login`, then `tunnel-create` with the domain and sub-address choices. The tools enforce pre-flight (does the domain's registrable parent have Cloudflare nameservers?) and post-flight (did `cloudflared` route the address under the requested name?) safety checks. A refusal always surfaces a dashboard instruction — never an API retry.
+**Autonomous setup.** Collect the admin hostname (and optionally public + apex hostnames), then invoke `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]` via Bash. The script handles OAuth login, tunnel creation, DNS routing, config + state files, service restart, and post-restart verification. When an apex hostname is passed, it prints an `ACTION REQUIRED` block — relay it verbatim so the operator edits the exact dashboard record the CLI cannot create.
 
-**Diagnostic flow:** `tunnel-status` does an end-to-end probe per configured address (DNS + HTTPS via Cloudflare's edge). `healthy: true` requires every address to probe `ok`. `boundAccountOwnsHostnames: false` means the tunnel is running on this laptop but nothing from the internet is reaching it — almost always because the laptop is signed into a Cloudflare account that does not own the target domain.
+**Reset / account switch.** Invoke `~/reset-tunnel.sh <brand>` via Bash to delete every tunnel on the brand's CF account and wipe `${CFG_DIR}`. Token-mode connectors and stray CNAMEs require manual cleanup — cite `plugins/cloudflare/references/reset-guide.md` for the exact `pkill` incantation and dashboard click-path.
 
-**Recovery flow:** The single recovery path for every wrong-account failure is: operator opens Cloudflare in their browser, confirms the account name in the top-left is the one that owns the target domain (or switches accounts using the dropdown), confirms to the agent, then the agent runs `tunnel-login force=true` to re-authenticate. Any stray records `cloudflared` created under the wrong domain are cleaned up by the operator in the wrong-account dashboard — the agent cannot reach account state.
+**Dashboard guidance.** When the operator needs to add a domain, switch accounts, edit an apex CNAME, or delete stray records, quote the relevant click-path verbatim from `plugins/cloudflare/references/dashboard-guide.md`. The operator runs it in their browser.
 
-**DNS lookups:** `dns-lookup` for hostname resolution. Nameserver-not-yet-propagated is the most common operator issue — `tunnel-status`'s e2e probe names the failure mode directly (`dns-missing`, `cname-points-elsewhere`, `edge-unreachable`, `tunnel-not-matched`).
+**Manual runbook.** When the scripted flow fails partway, drop into `plugins/cloudflare/references/manual-setup.md` at whichever step the script failed in. Every scripted step mirrors a numbered runbook step.
 
-**Alias addresses:** `tunnel-add-hostname` adds an additional address to an existing tunnel. The alias's domain must be on the same Cloudflare account this laptop is signed into — if not, the tool refuses with dashboard guidance.
+**Tool discipline (IDENTITY.md § Cloudflare operations).** Do not drive the Cloudflare dashboard via Playwright or Chrome DevTools. Do not synthesise `cloudflared` flag combinations. Do not call the Cloudflare API or SDK. Do not write or edit `cert.pem`, `tunnel.state`, `config.yml`, or `alias-domains.json` directly. When a sanctioned surface fails, report with evidence and cite `reset-guide.md` — do not improvise.
 
 **User-facing language:** Say "Cloudflare account", "domain", "address", "sign in", "browser". Never say "zone", "CNAME", "account ID", "API", "SDK", or any hexadecimal identifier.
 
-**Verification:** Always verify URLs work by navigating to them in the browser. Never claim a URL works without browser verification.
+**Verification:** Always verify URLs work by running `curl -I https://<hostname>` after the script finishes. A non-530 response means the tunnel is live. Never claim a URL works without verification.
 
 ## Telegram