@rubytech/create-maxy 1.0.623 → 1.0.624

package/payload/platform/plugins/cloudflare/references/manual-setup.md

@@ -0,0 +1,445 @@
+# Manual Cloudflare tunnel setup — human runbook
+
+Step-by-step recovery path for when the Maxy automation fails or is unavailable. Every command below is isolated in its own code block — nothing to parse from prose. Every path is brand-scoped so multiple brands can coexist on the same Linux user.
+
+Prerequisites: `cloudflared` installed; VNC running on `DISPLAY=:99`; SSH access to the device.
+
+---
+
+## Why two hostnames (admin and public)
+
+Each Maxy installation exposes two distinct surfaces from the same device and the same local port. The platform UI distinguishes them by the inbound `Host:` header.
+
+- **admin hostname** — the operator's private chat + admin panel. PIN-protected. Only the owner uses it.
+- **public hostname** — the public-facing agent (customer chat, marketing agent, WhatsApp webhook target). Reachable by anyone on the internet.
+
+Two tunnel hostnames, one connector, one local service. The tunnel's `ingress:` block routes each hostname to `http://localhost:${PORT}`; the platform UI handles the rest.
+
+---
+
+## Two modes — which are you in?
+
+### Mode A — you own the domain (this runbook)
+
+You have a Cloudflare account and a domain already on that account. You run every step below on your own device using your own cert.pem. Your hostnames are:
+
+- `admin.<yourdomain>`
+- `public.<yourdomain>`
+
+### Mode B — you don't own a domain (Maxy-provided subdomain)
+
+First-time users without a Cloudflare account or domain use a subdomain of the Maxy-operated domain (`maxy.bot`). Maxy owns the CF account and issues each user a token for a pre-created tunnel. Hostnames are:
+
+- `<username>.maxy.bot` — admin surface (e.g. `neo.maxy.bot`, `joel.maxy.bot`)
+- public surface is optional and, when enabled, uses a second Maxy-issued subdomain.
+
+Mode B skips Steps 1–5 of this runbook entirely — the user receives a token from Maxy and only runs Step 6 (the connector) with `--token <X>`. Mode B is documented separately in `managed-tunnel-setup.md`.
+
+**The rest of this runbook covers Mode A only.**
+
+---
+
+## Automation — setup-tunnel.sh and reset-tunnel.sh
+
+The manual walkthrough below exists so an operator can execute every step by hand when the system is broken or the automation is absent. For a normal setup — and for validating that the runbook's steps produce a working tunnel end-to-end — use the two scripts at `platform/plugins/cloudflare/scripts/`:
+
+```
+setup-tunnel.sh <brand> <port> <hostname> [<hostname> ...]
+```
+
+Example:
+
+```
+~/setup-tunnel.sh maxy 19200 admin.maxy.bot public.maxy.bot maxy.chat
+```
+
+Mirrors this runbook verbatim (Steps 0–5b), calls `systemctl --user restart "${BRAND}.service"` at the end to spawn the connector via `resume-tunnel.sh`, then polls each subdomain hostname (up to 60s per host) for a non-530 response. Apex hostnames cannot be routed via CLI (see §Step 4); the script prints an explicit ACTION REQUIRED block naming the dashboard record to edit or add.
+
+```
+reset-tunnel.sh <brand>
+```
+
+Example:
+
+```
+~/reset-tunnel.sh maxy
+```
+
+Deletes every tunnel on the brand's Cloudflare account (via the brand's cert) and wipes `${CFG_DIR}`. Does **not** touch the platform service or any stray misrouted CNAMEs in DNS — those require a manual dashboard delete.
+
+After manual transfer to a device, run `chmod +x ~/setup-tunnel.sh ~/reset-tunnel.sh` before the first invocation.
+
+**Walk through manually (instead of scripting) when:**
+- Diagnosing a step that's failing under the script.
+- Recovering a partial state where the scripts assume a clean start.
+- Validating runbook changes before re-baking them into the scripts.
+- Working on a device where the scripts aren't deployed yet.
+
+---
+
+## Step 0 — Set brand context
+
+Run this once per shell session. Every subsequent step reads these variables. The `BRAND` value determines the on-disk directory (`${HOME}/.${BRAND}/cloudflared/`) so multiple brands on the same Linux user do not collide.
+
+For Maxy:
+
+```
+export BRAND=maxy
+export PORT=19200
+export CFG_DIR="${HOME}/.${BRAND}/cloudflared"
+mkdir -p "${CFG_DIR}"
+```
+
+For Real Agent:
+
+```
+export BRAND=realagent
+export PORT=19500
+export CFG_DIR="${HOME}/.${BRAND}/cloudflared"
+mkdir -p "${CFG_DIR}"
+```
+
+---
+
+## Step 1 — OAuth login
+
+```
+DISPLAY=:99 cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel login
+```
+
+**Why:** Produces the account-level credential that authorises creating tunnels and routing DNS. One-time per device per brand per account.
+
+**Success:** VNC browser opens on the "Authorize Cloudflare Tunnel" page. Click any zone. Terminal prints `You have successfully logged in.`
+
+**`cloudflared` quirk — cert.pem lands at the default path regardless of `--origincert`.** The login subcommand always writes to `~/.cloudflared/cert.pem`. Move it into the brand-scoped directory immediately so every subsequent step works off `${CFG_DIR}/cert.pem`:
+
+```
+mv ~/.cloudflared/cert.pem "${CFG_DIR}/cert.pem"
+```
+
+**If the login fails with `You have an existing certificate`:** cert.pem already exists at the default path from a prior login. Either skip to Step 2 (if the existing cert is correct), or remove it and re-run:
+
+```
+rm ~/.cloudflared/cert.pem
+```
+
+**If the browser does not open:** confirm the VNC display exists:
+
+```
+ls /tmp/.X11-unix/
+```
+
+You should see `X99`. If not, start VNC before retrying Step 1.
+
+---
+
+## Step 2 — List existing tunnels
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel list
+```
+
+**Why:** Shows every tunnel on the brand's account by name and UUID. Use before creating (to avoid name collision) and before deleting (to find the UUID).
+
+**Success:** A table of NAME, ID (UUID), CREATED, CONNECTIONS. An empty list is fine.
+
+**If it fails with `cert.pem not found`:** run Step 1.
+
+---
+
+## Step 3 — Create the tunnel
+
+Choose a tunnel name following the convention `{product}-{device}` (e.g. `maxy-neo`, `maxy-pi`, `realagent-laptop`). Then:
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel create "${BRAND}-$(hostname -s)"
+```
+
+**Why:** Creates a new tunnel on the brand's CF account. Writes the connector credentials file (distinct from cert.pem: this is per-tunnel runtime auth; cert.pem is account auth). The credentials filename is the tunnel UUID.
+
+**Success:** Output contains:
+```
+Created tunnel <name> with id <UUID>
+```
+Note the UUID — every subsequent step needs it.
+
+**If it fails with `already exists`:** a tunnel with that name exists. Either run Step 2 to find its UUID and skip to Step 4, or delete it:
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel delete "${BRAND}-$(hostname -s)"
+```
+
+Then re-run Step 3.
+
+**Capture the UUID as an env var so every subsequent step references it:**
+
+```
+export TUNNEL_ID=<UUID>
+```
+
+Replace `<UUID>` with the value from Step 3's output.
+
+**Note — credentials JSON already lives in `${CFG_DIR}`.** Unlike cert.pem, `cloudflared tunnel create` writes its `<UUID>.json` credentials next to wherever `--origincert` points. Because Step 1's `mv` put cert.pem in `${CFG_DIR}`, the credentials landed there too. No move needed.
+
+---
+
+## Step 4 — Route DNS for each hostname
+
+One command per hostname.
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel route dns --overwrite-dns "${TUNNEL_ID}" admin.maxy.bot
+```
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel route dns --overwrite-dns "${TUNNEL_ID}" public.maxy.bot
+```
+
+**Why:** Creates a CNAME in Cloudflare DNS pointing each hostname at `<UUID>.cfargotunnel.com`. `--overwrite-dns` makes it idempotent.
+
+**Success:** Output contains `Added CNAME <hostname> which will route to this tunnel.`
+
+**If it fails with `zone not found`:** the hostname's parent domain isn't on this brand's Cloudflare account. Either add it in the dashboard (Websites → Add a site) and re-run, or sign into the account that already owns the domain.
+
+### Apex hostnames (e.g. `maxy.chat` as a bare root domain)
+
+`cloudflared tunnel route dns` **cannot** create a CNAME at a zone apex — standard DNS forbids CNAME at apex (conflicts with SOA/NS), and Cloudflare's workaround (CNAME flattening) is only exposed via the CF API/dashboard, not the CLI. Running `tunnel route dns --overwrite-dns <UUID> maxy.chat` silently misroutes to the first non-matching zone it finds (observed: it created `maxy.chat.maxy.bot` under the wrong zone).
+
+**Workflow for apex hostnames:**
+
+1. **Manual — create the CNAME once in the dashboard.** CF dashboard → `<apex-zone>` → DNS → Add record. Type=CNAME, Name=`@` (zone apex), Content=`<UUID>.cfargotunnel.com`, Proxy=on. Cloudflare applies CNAME flattening automatically for apex CNAMEs under a CF-managed zone.
+2. **Scripted — add the ingress rule in Step 5's config.yml** (same as any subdomain hostname). Without this, traffic arrives at the connector and falls through to `http_status:404`.
+3. **Scripted — add the hostname to `alias-domains.json`** if the apex should render the public surface (see §Troubleshooting at the end of this runbook for the classification rule).
+
+Steps 2 and 3 are part of the normal scripted flow. Only Step (1) is the irreducible manual action for apex hostnames.
+
+---
+
+## Step 5 — Write config.yml
+
+The heredoc below expands `${BRAND}`, `${PORT}`, `${CFG_DIR}`, and `${TUNNEL_ID}` at write time. **If any of those variables is empty in the current shell, the file gets written with blank values and cloudflared refuses to start with the cryptic error `"cloudflared tunnel run" requires the ID or name of the tunnel`.** The most common cause is running Step 5 in a fresh shell where Step 0 wasn't re-exported.
+
+**Fail-fast guard — run this first.** It exits non-zero if any required variable is unset or empty, so you cannot accidentally write a broken file:
+
+```
+: "${BRAND:?set Step 0}"; : "${PORT:?set Step 0}"; : "${CFG_DIR:?set Step 0}"; : "${TUNNEL_ID:?set via Step 3}"
+```
+
+Only if that line prints nothing (all vars set) do you proceed to write the config:
+
+```
+cat > "${CFG_DIR}/config.yml" <<EOF
+tunnel: ${TUNNEL_ID}
+credentials-file: ${CFG_DIR}/${TUNNEL_ID}.json
+ingress:
+  - hostname: admin.maxy.bot
+    service: http://localhost:${PORT}
+  - hostname: public.maxy.bot
+    service: http://localhost:${PORT}
+  - service: http_status:404
+EOF
+```
+
+**Why:** Tells cloudflared at startup which tunnel to run, where its credentials are, and how to route each hostname to the brand's local service port. The trailing `http_status:404` line is the mandatory catch-all.
+
+**Success:** Confirm with:
+
+```
+cat "${CFG_DIR}/config.yml"
+```
+
+**If it fails on YAML:** validate with:
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" --config "${CFG_DIR}/config.yml" tunnel ingress validate
+```
+
+---
+
+## Step 5b — Write tunnel.state
+
+`resume-tunnel.sh` (the `ExecStartPre=` in the brand's service) reads `${CFG_DIR}/tunnel.state` to discover which tunnel to run. **Without this file the script exits 0 silently and no connector is spawned** — see lines 34-37 of `platform/scripts/resume-tunnel.sh`. The old MCP tool `tunnel-create` used to write this file via `saveTunnelIdentity()` in `cloudflared.ts`; with the raw CLI flow in this runbook nothing does, so we write it explicitly here.
+
+Re-run the Step 5a fail-fast guard if your shell is new or if Step 5a was a while ago:
+
+```
+: "${BRAND:?set Step 0}"; : "${CFG_DIR:?set Step 0}"; : "${TUNNEL_ID:?set via Step 3}"
+```
+
+Then write the state file:
+
+```
+cat > "${CFG_DIR}/tunnel.state" <<EOF
+{
+  "tunnelId": "${TUNNEL_ID}",
+  "tunnelName": "${BRAND}-$(hostname -s)",
+  "domain": "maxy.bot",
+  "configPath": "${CFG_DIR}/config.yml",
+  "credentialsPath": "${CFG_DIR}/${TUNNEL_ID}.json"
+}
+EOF
+```
+
+**Why each field:** `resume-tunnel.sh` reads `tunnelId`, `domain`, `configPath` (all used; domain is for logging, tunnelId for the log line, configPath is passed as `--config` to cloudflared). `credentialsPath` and `tunnelName` are not read by `resume-tunnel.sh` itself but are consumed by other tools (e.g. `tunnel-status` in the cloudflared plugin), so write them anyway.
+
+**Success:**
+
+```
+cat "${CFG_DIR}/tunnel.state" | jq .tunnelId
+```
+
+Prints the UUID from Step 3. If it prints empty or null, the heredoc's env expansion failed — re-run the fail-fast guard.
+
+**If you skip this step:** `systemctl --user status maxy.service` will show `ExecStartPre=resume-tunnel.sh (code=exited, status=0/SUCCESS)` (no error) but `ps -ef | grep '[c]loudflared'` will show no Maxy connector. Silent failure — the exact gap this step closes.
+
+---
+
+## Step 6 — Restart the brand's user-space service so it respawns the connector with the new config
+
+You do **not** run `cloudflared` manually. The brand's existing user-space systemd unit (`~/.config/systemd/user/${BRAND}.service`) declares `ExecStartPre=/home/<user>/${BRAND}/platform/scripts/resume-tunnel.sh`, and that pre-start script reads `${CFG_DIR}/tunnel.state` and `${CFG_DIR}/config.yml` (the files Steps 5 and 5b just wrote) and spawns the connector in the user's cgroup. Restarting the brand service is what picks up the new config.
+
+> **Note:** When walking through by hand you run this step yourself. The automation script `platform/plugins/cloudflare/scripts/setup-tunnel.sh` runs it for you — the script is autonomous and completes the deployment, including the service restart and post-restart verification (ps-grep for the connector + curl each subdomain). If you used the script, this step is already done.
+
+
+```
+systemctl --user restart "${BRAND}.service"
+```
+
+**Why:** `resume-tunnel.sh` is the deterministic, brand-scoped spawner. Running `cloudflared` manually duplicates the connector (two processes for one tunnel) and races the brand service on every service restart. The service path is the only correct production path.
+
+**Success:**
+
+```
+systemctl --user status "${BRAND}.service" --no-pager
+```
+
+Shows `active (running)` with `ExecStartPre=...resume-tunnel.sh (code=exited, status=0/SUCCESS)`. Then confirm the connector is actually alive:
+
+```
+ps -ef | grep '[c]loudflared'
+```
+
+Expect one line per running brand, each with `--config ${CFG_DIR}/config.yml` under your Linux user (not root). Then verify end-to-end from any machine:
+
+```
+curl -I https://admin.maxy.bot
+```
+
+A non-530 response means the tunnel is live.
+
+**If the connector is missing from `ps`**, the spawn failed silently. Check `${CFG_DIR}/logs/cloudflared.log` for the reason (most often: `config.yml` was written with empty `tunnel:` because Step 5's fail-fast guard was skipped).
+
+**If the hostname returns `530`:** DNS has not propagated yet. Wait 30–60 seconds and retry.
+
+**If the hostname returns `connection refused`:** your local service is not listening on `${PORT}`. Start it.
+
+**If cloudflared exits with `tunnel not found`:** the `${TUNNEL_ID}` in config.yml does not match an existing tunnel on the brand's account. Re-run Step 2 to confirm.
+
+---
+
+## Step 7 — Production durability (user-space systemd via the platform service)
+
+**Do NOT use `sudo cloudflared service install`.** It writes `/etc/systemd/system/cloudflared.service`, copies your config to `/etc/cloudflared/config.yml` (a system-wide path), and runs the connector as root — breaking brand isolation on any device that hosts more than one brand under the same Linux user. We tried this path on 2026-04-19; it created a duplicate connector parallel to the existing user-space one and required an explicit uninstall to undo.
+
+The correct production pattern is already in place on every Maxy device: the brand's platform UI itself is a **user-space systemd service** at `~/.config/systemd/user/<brand>.service`, and that service spawns the cloudflared connector as an `ExecStartPre=` via `platform/scripts/resume-tunnel.sh`. When the user-space service restarts, the connector restarts with it. The connector runs as the Linux user (not root), its config is read from `${CFG_DIR}/config.yml` (brand-scoped, never `/etc`), and multiple brands coexist because each has its own unit file (`maxy.service`, `realagent.service`, etc.).
+
+**Durability prerequisites (one-time per device):**
+
+```
+loginctl enable-linger "$(whoami)"
+```
+
+Lets user-space services survive logout/reboot. Without linger, user units only start at interactive login.
+
+**Confirm the brand's unit is enabled:**
+
+```
+systemctl --user is-enabled "${BRAND}.service"
+```
+
+Expected: `enabled`. If `disabled`, enable it:
+
+```
+systemctl --user enable "${BRAND}.service"
+```
+
+**After any change to `${CFG_DIR}/config.yml`, restart the brand's service** — the `ExecStartPre=resume-tunnel.sh` respawns the connector with the new config:
+
+```
+systemctl --user restart "${BRAND}.service"
+```
+
+**Success:**
+
+```
+systemctl --user status "${BRAND}.service"
+```
+
+Shows `active (running)` with the brand's platform UI + cloudflared alive. A separate `ps -ef | grep '[c]loudflared'` confirms one connector per running brand, all under user `$(whoami)`, none under root.
+
+**If you already ran `sudo cloudflared service install` before reading this** — undo it:
+
+```
+sudo cloudflared service uninstall
+```
+
+Removes the root-level systemd unit, `/etc/cloudflared/config.yml`, and the duplicate connector. The user-space service remains unaffected.
+
+---
+
+## Full reset
+
+If everything is in a bad state and you want to start over. Assumes Step 0 has been run so `${BRAND}` and `${CFG_DIR}` are set.
+
+Find the tunnel name:
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel list
+```
+
+Delete the tunnel (replace `<name>`):
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel delete <name>
+```
+
+Remove the entire brand-scoped cloudflared directory:
+
+```
+rm -rf "${CFG_DIR}"
+```
+
+Order matters: delete the tunnel *before* removing cert.pem (delete needs the cert). Then start again from Step 0.
+
+If the service was installed (Step 7), also uninstall it:
+
+```
+sudo cloudflared service uninstall
+```
+
+---
+
+## Troubleshooting — admin hostname serves the public agent
+
+If `admin.<yourdomain>` is rendering the public-agent UI, the tunnel is fine but the platform UI is treating the admin hostname as public. The platform UI classifies a host as public when either:
+
+- the hostname starts with `public.`, or
+- the hostname appears in `${CFG_DIR}/alias-domains.json`.
+
+Pre-Task-548 sessions populated this file via the now-deleted `tunnel-add-hostname` MCP tool, which wrote every routed hostname — including `admin.*` — into the alias set. The pollution persists across installs.
+
+**Diagnose:**
+
+```
+cat "${CFG_DIR}/alias-domains.json"
+```
+
+If `admin.<yourdomain>` appears in the array, remove it:
+
+```
+jq --arg H "admin.<yourdomain>" 'map(select(. != $H))' "${CFG_DIR}/alias-domains.json" > /tmp/alias.json && mv /tmp/alias.json "${CFG_DIR}/alias-domains.json"
+```
+
+Replace `<yourdomain>` with your actual domain. The platform UI watches the file — no restart required; the next request to the admin hostname routes to the admin surface.
+
+Leave legitimate public aliases (e.g. `maxy.chat`, or `<yourdomain>` root acting as public) in the file.

package/payload/platform/plugins/cloudflare/references/reset-guide.md

@@ -0,0 +1,118 @@
+# Cloudflare reset — when and how
+
+Reset is a heavier action than recovery. `reset-tunnel.sh` deletes every tunnel on the brand's Cloudflare account and wipes the on-disk cloudflared config directory. Use it when the state is genuinely corrupt or when the operator wants a known-good baseline; use patching (targeted cleanup) when the state is mostly correct but one record or process is wrong.
+
+---
+
+## Decision tree — reset or patch?
+
+Ask three questions in order. The first `yes` determines the action.
+
+1. **Is cert.pem bound to an account the operator no longer wants to be signed into?** (e.g. the operator signed in to the wrong account, or the previous account was scrubbed / rotated / delisted.)
+   → Full reset. The cert authorises everything `cloudflared` does; a wrong-account cert poisons every subsequent step.
+
+2. **Is `config.yml` referencing a tunnel UUID that no longer exists on the account, or a hostname that the account no longer owns?**
+   → Full reset. The tunnel the config names is unreachable; recovering per-step is slower than starting clean.
+
+3. **Is the only problem a stray CNAME in the dashboard, a rogue token-mode connector process, or an out-of-date `alias-domains.json` entry?**
+   → Patch (see § Patching below). Reset would destroy correct local state alongside the bad record.
+
+When no question reaches `yes`, the state is probably recoverable per-step via `references/manual-setup.md`. Invoke `setup-tunnel.sh` again before reaching for reset.
+
+---
+
+## Full reset — `reset-tunnel.sh`
+
+### What it does
+
+- Reads cert.pem from `${HOME}/.${BRAND}/cloudflared/cert.pem`.
+- Lists every tunnel on the account the cert authorises.
+- Deletes every one of those tunnels via `cloudflared tunnel delete`.
+- Removes `${HOME}/.${BRAND}/cloudflared/` entirely.
+
+### What it does not do
+
+- It does not touch the platform service (`${BRAND}.service`). Restart the service separately with `systemctl --user restart "${BRAND}.service"` once a fresh tunnel is set up.
+- It does not touch DNS records. Records pointing at `<UUID>.cfargotunnel.com` from a deleted tunnel become stray; delete them in the dashboard (see § Patching below).
+- It does not stop token-mode connector processes. If the device is running `cloudflared ... tunnel run --token <X>` for a tunnel the brand's cert does not own, that connector keeps running.
+- It does not switch accounts. If the bound account was wrong, a fresh `cloudflared tunnel login` from inside `setup-tunnel.sh` on the next run will pick a new one — but the operator must sign in with the correct account in the browser.
+
+### Invocation
+
+```
+~/reset-tunnel.sh <brand>
+```
+
+Example:
+
+```
+~/reset-tunnel.sh maxy
+```
+
+The script exits with the number of tunnels deleted. Relay the output verbatim. If the script exits non-zero (e.g. cert missing, cloudflared not installed), quote the error and stop — do not synthesise a recovery path.
+
+### After reset
+
+Invoke `setup-tunnel.sh` with the operator's chosen hostnames (see `SKILL.md` for the input-collection questions). The script re-runs `cloudflared tunnel login`; the operator authorises a fresh cert from the correct account in the VNC browser.
+
+---
+
+## Patching — targeted cleanup without reset
+
+### Stop a token-mode connector the reset script cannot see
+
+Token-mode tunnels are created by a central operator (e.g. Maxy-provided subdomains under `maxy.bot`). The connector runs with `--token <X>` and does not consult `cert.pem`, so `reset-tunnel.sh` (which authorises via cert.pem) cannot stop or delete it. Kill the process directly:
+
+```
+pkill -f 'cloudflared.*tunnel run --token'
+```
+
+The pattern matches exactly connectors started with `tunnel run --token`, leaving cert-mode connectors (started without `--token`) alone. Confirm the kill:
+
+```
+ps -ef | grep '[c]loudflared'
+```
+
+No lines with `--token` should remain. If multiple token-mode connectors are running, all are killed — scope with a more specific pattern if that is not desired (`pkill -f 'cloudflared.*tunnel run --token eyJ...'` matches the token prefix).
+
+### Delete a stray CNAME that survived a tunnel delete
+
+When `reset-tunnel.sh` deletes a tunnel, the DNS CNAMEs that pointed at `<UUID>.cfargotunnel.com` remain in the zone — Cloudflare deliberately does not cascade-delete DNS when you delete a tunnel. Clean up in the dashboard:
+
+1. See `references/dashboard-guide.md` § "Delete a stray CNAME" for the click-path.
+2. Verify the CNAME's target is the tunnel you just deleted (not a live one).
+3. Delete.
+
+When the operator is unsure which records are stray, have them list the zone's CNAMEs (see `references/dashboard-guide.md` § "List CNAME records in a zone") and compare against the currently-running `cloudflared tunnel list` on the device.
+
+### Remove a rogue entry from `alias-domains.json`
+
+`alias-domains.json` controls which hostnames the platform UI classifies as public (serving the public agent) rather than admin. A prior setup flow may have written an `admin.*` hostname into this file by mistake. Remove it manually:
+
+```
+cat "${CFG_DIR}/alias-domains.json"
+```
+
+If `admin.<yourdomain>` is listed, strip it:
+
+```
+jq --arg H "admin.<yourdomain>" 'map(select(. != $H))' "${CFG_DIR}/alias-domains.json" > /tmp/alias.json && mv /tmp/alias.json "${CFG_DIR}/alias-domains.json"
+```
+
+Replace `<yourdomain>` with the actual domain. The platform UI watches the file and reloads without a restart.
+
+### Fix a single wrong DNS record without tearing everything down
+
+If a hostname's CNAME is pointing at the wrong tunnel (e.g. after an account switch left old records), `cloudflared` can overwrite it once the correct cert is in place:
+
+```
+cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel route dns --overwrite-dns "${TUNNEL_ID}" <hostname>
+```
+
+This runs the same logic `setup-tunnel.sh` runs internally for each subdomain. Apex hostnames do not work here — the dashboard is the only path (see `references/dashboard-guide.md` § "Edit an apex CNAME").
+
+---
+
+## Failure discipline
+
+When `reset-tunnel.sh` or a patch command exits non-zero, report the failure with the exact output. Cite the relevant section above for the next action. Do not chain alternative recovery attempts — the agent's job ends at the boundary of a sanctioned surface, and improvisation outside that boundary is the discipline violation IDENTITY.md § Cloudflare operations exists to prevent.

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

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Reset a brand's Cloudflare tunnel state.
+# Inverse of setup-tunnel.sh; same scope boundary (tunnel state only).
+#
+# Deletes every tunnel on the brand's Cloudflare account (using the brand's
+# cert.pem) and wipes the brand-scoped cloudflared state directory. Leaves
+# the platform service alone — the operator decides whether to stop/restart
+# ${BRAND}.service.
+#
+# Usage:
+#   reset-tunnel.sh <brand>
+#
+# Example:
+#   reset-tunnel.sh maxy
+#
+# Does NOT delete stray misrouted CNAMEs in DNS (e.g. admin.maxy.bot.maxy.chat
+# from an earlier wrong-zone OAuth). Those are zone-specific DNS records the
+# CLI cannot enumerate from here; remove them manually in the CF dashboard.
+
+set -euo pipefail
+
+if [ "$#" -lt 1 ]; then
+  echo "Usage: $0 <brand>" >&2
+  exit 2
+fi
+
+BRAND="$1"
+CFG_DIR="${HOME}/.${BRAND}/cloudflared"
+CERT="${CFG_DIR}/cert.pem"
+
+if [ ! -f "${CERT}" ]; then
+  echo "No cert.pem at ${CERT} — nothing to delete via CLI."
+  echo "Removing ${CFG_DIR} if present."
+  rm -rf "${CFG_DIR}"
+  exit 0
+fi
+
+# Delete every tunnel on the account (the cert is per-account for tunnel CRUD).
+NAMES="$(cloudflared --origincert "${CERT}" tunnel list --output json 2>/dev/null \
+  | jq -r '.[]?.name' | sort -u)"
+if [ -z "${NAMES}" ]; then
+  echo "No tunnels to delete on this brand's account."
+else
+  while IFS= read -r NAME; do
+    [ -z "${NAME}" ] && continue
+    echo "Deleting tunnel: ${NAME}"
+    cloudflared --origincert "${CERT}" tunnel delete "${NAME}"
+  done <<< "${NAMES}"
+fi
+
+# Wipe the brand-scoped cloudflared state directory.
+rm -rf "${CFG_DIR}"
+echo "Removed ${CFG_DIR}"
+
+echo ""
+echo "Reset complete for brand=${BRAND}."
+echo ""
+echo "If earlier runs produced stray misrouted CNAMEs (e.g. admin.maxy.bot.maxy.chat"
+echo "when the cert was scoped to the wrong zone), delete those records manually in"
+echo "the Cloudflare dashboard — the CLI cannot enumerate them from here."
+echo ""
+echo "The platform service (${BRAND}.service) was not touched. To release any"
+echo "running cloudflared connector started by ${BRAND}.service's ExecStartPre,"
+echo "either restart the service (which will no-op on resume since tunnel.state"
+echo "is gone) or leave it running until you re-run setup-tunnel.sh."