@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,108 @@
+# Cloudflare dashboard — click-paths
+
+The dashboard is the only surface for operations the CLI cannot perform: signing in, adding a site, editing an apex CNAME, deleting a tunnel after its replicas are stopped, and switching accounts. The agent does not drive the dashboard — it relays the numbered steps below to the operator, who runs them in their own browser.
+
+Anchor on the dashboard's text labels, not pixel positions. Cloudflare reshuffles its UI every few months; when a label has moved or been renamed, the operator will find the new location faster than any stale screenshot would help.
+
+---
+
+## Sign in and confirm which account
+
+1. Open https://dash.cloudflare.com in a browser.
+2. If a sign-in page appears, sign in with the email that owns your Cloudflare account.
+3. Look at the top-left corner of the dashboard, next to the orange Cloudflare cloud icon. The account name shown there is the account the laptop will also be bound to when you run `tunnel login` from the device. Confirm this is the right account before continuing.
+
+---
+
+## Switch between Cloudflare accounts
+
+1. Click the account name in the top-left corner (next to the orange cloud).
+2. A dropdown appears listing every account your sign-in has access to.
+3. Click the account you want to switch into. The dashboard reloads on that account.
+4. Verify the new account name now shows in the top-left before running any CLI command.
+
+---
+
+## Add a domain to a Cloudflare account
+
+1. With the correct account active (top-left), click **Websites** in the left-hand sidebar.
+2. Click the **Add a site** button.
+3. Enter the bare domain (e.g. `example.com`, not `www.example.com`) and click **Continue**.
+4. Cloudflare scans the domain's existing DNS records and presents them for review. Confirm any records you want preserved — website (`A`), email (`MX`), and DNS verification (`TXT`) records are common.
+5. Cloudflare gives you two nameservers (e.g. `adam.ns.cloudflare.com`, `eve.ns.cloudflare.com`). Copy them.
+6. Open your domain registrar's control panel in a separate browser tab and replace the registrar's nameservers with the two from Cloudflare.
+7. Return to Cloudflare and click **Check nameservers**. The zone shows **Pending** until propagation completes (minutes to 24 hours); it moves to **Active** once Cloudflare's edge sees the new nameservers on the domain.
+
+---
+
+## Verify a zone's nameservers are correct
+
+1. Click **Websites** in the sidebar, then click the domain you want to check.
+2. The zone's status appears at the top — **Active** means Cloudflare serves DNS for this zone; **Pending** means the registrar has not yet switched nameservers to Cloudflare's.
+3. For a deeper check, click **DNS** in the sidebar, then **Records**. At the top of the records list, Cloudflare shows the two assigned nameservers for this zone. Those are the exact values the registrar must set at the domain level.
+
+---
+
+## Authorise a new tunnel (pick the right zone)
+
+This page opens automatically when `cloudflared tunnel login` runs on the device.
+
+1. The "Authorize Cloudflare Tunnel" page shows every zone on the currently-active account.
+2. Click the zone you want the tunnel to be able to route DNS for.
+3. Click **Authorize**. The browser closes or shows "You can close this page."
+4. Return to the terminal — `cloudflared` prints `You have successfully logged in.` once the cert lands.
+
+If the account shown in the top-left is not the one that owns the zone you need, click the account-name dropdown first (see "Switch between Cloudflare accounts") and re-authorise from the right account.
+
+---
+
+## Edit an apex CNAME (bare-domain hostname)
+
+Apex hostnames — a record at the zone root, e.g. `maxy.chat` rather than `www.maxy.chat` — cannot be routed by `cloudflared tunnel route dns` because standard DNS forbids CNAMEs at zone apex. Cloudflare's workaround (CNAME flattening) is only exposed via the dashboard. When `setup-tunnel.sh` prints an `ACTION REQUIRED` block for an apex, these are the steps:
+
+1. Click **Websites** in the sidebar, then click the apex zone (e.g. `maxy.chat`).
+2. Click **DNS** in the sidebar, then **Records**.
+3. If a record already exists at `@` (zone apex): click **Edit** on that record, set **Type** to `CNAME`, **Content** to the tunnel target (e.g. `<UUID>.cfargotunnel.com`), leave **Proxy status** as **Proxied** (orange cloud), and click **Save**.
+4. If no record exists at `@`: click **Add record**, set **Type** to `CNAME`, **Name** to `@`, **Content** to the tunnel target, **Proxy status** to **Proxied**, and click **Save**.
+
+Cloudflare applies CNAME flattening automatically for apex CNAMEs under a CF-managed zone — no further flag needed.
+
+---
+
+## Delete a tunnel after stopping its replicas
+
+`cloudflared tunnel delete` refuses when any connector process is still running against the tunnel. For token-mode tunnels (created by a central operator, run on a device with `--token`), the connector is not managed by the local `cloudflared` CLI.
+
+1. On the device, run `pkill -f 'cloudflared.*tunnel run --token'` to terminate the local token-mode connector. See `references/reset-guide.md` for the exact incantation.
+2. Open the dashboard and navigate to **Zero Trust** → **Networks** → **Tunnels**.
+3. Find the tunnel by name. The **Status** column should now say **Inactive** or **Degraded** — the connector count dropped to zero because Step 1 killed it.
+4. Click the tunnel's row, then click the **...** menu on the far right, then **Delete**.
+5. Confirm the deletion in the dialog.
+
+If **Status** still shows **Healthy** with connectors > 0, another device is also running the tunnel — track down and stop those connectors first.
+
+---
+
+## List CNAME records in a zone
+
+1. Click **Websites** in the sidebar, then click the zone.
+2. Click **DNS** in the sidebar, then **Records**.
+3. Filter the records list by **Type** = `CNAME`. Every CNAME in the zone shows — Name, Content (the target), Proxy status, TTL.
+
+Use this when you need to audit which hostnames are pointing at which `<UUID>.cfargotunnel.com` target, or to find stray records left by a prior tunnel setup that should be deleted.
+
+---
+
+## Delete a stray CNAME
+
+1. List the CNAMEs in the zone (see above).
+2. Find the record you want to remove. Confirm its target is the stale tunnel — do not delete a record pointing at a live tunnel.
+3. Click **Edit** on the record, then **Delete**, then confirm in the dialog.
+
+`references/reset-guide.md` names the scenarios where this cleanup is load-bearing (post-reset stray records, account-switch residue).
+
+---
+
+## Where tunnels live in the dashboard (as of 2026-04)
+
+Tunnels are under **Zero Trust** → **Networks** → **Tunnels**. This is not in the top-level sidebar — it is under the Zero Trust sub-dashboard, which itself appears in the main sidebar. Cloudflare has moved this location in the past. If **Networks** → **Tunnels** is not visible under Zero Trust, the label has likely been renamed; look for "Tunnels" under Networks or Access.

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

@@ -0,0 +1,481 @@
+# 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; the brand's VNC running on its own X display + rfbport + websockify + CDP port (per `brand.json`'s `vncDisplay`/`rfbPort`/`websockifyPort`/`cdpPort` fields — Tasks 553 + 924; defaults Maxy=`:99`/`5900`/`6080`/`9222`, Real Agent=`:100`/`5901`/`6081`/`9223`, Maxy-2=`:101`/`5902`/`6082`/`9224`, Maxy-3=`:102`/`5903`/`6083`/`9225`, Maxy-4=`:103`/`5904`/`6084`/`9226`); SSH access to the device. The defaults table is historical — runtime readers (`paths.ts`, admin/MCP, `vnc.sh`, `test-laptop-vnc-boot.sh`) loud-fail with `reason=cdp-port-unresolved` if any of `rfbPort`/`websockifyPort`/`cdpPort` is missing from the live `brand.json`; the values above show what each brand's `brand.json` contains, not what the readers fall back to.
+
+---
+
+## 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/`:
+
+> **Task 954 — `list-cf-domains` is brand-arg + brand.json driven.** `list-cf-domains.sh` requires the brand name as `$1`; the .ts helper reads `cdpPort` from `${MAXY_PLATFORM_ROOT}/config/brand.json` (no silent default). Missing brand arg, missing brand.json, or missing `cdpPort` field each exit 1 with a named `reason=` token, and the route maps them to `field=config` (no Retry button — fix the install instead).
+
+```
+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
+
+The DISPLAY value is per-brand (Task 553). Read it from the brand manifest so the chromium tab opens in the correct VNC:
+
+```
+export VNC_DISPLAY=":$(jq -r '.vncDisplay // 99' "${HOME}/${BRAND}/platform/config/brand.json")"
+DISPLAY="${VNC_DISPLAY}" 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.
+
+### States the consent page can render
+
+The dashboard at `dash.cloudflare.com/argotunnel?...` is `cloudflared`'s native consent surface. The automation wrapper does not inspect or auto-click it; the operator drives every variation manually on the VNC.
+
+1. **Pre-authorize — the Authorize button is visible.** Single-zone account. Click **Authorize**. Cloudflare's callback fires and `~/.cloudflared/cert.pem` lands a second or two later. Continue with the `mv` above.
+
+2. **Multi-zone picker — "Please select the zone you want to add a Tunnel to" with a list of zones.** Multi-zone account. Click the zone row you want first; the page renders the Authorize button. Click **Authorize**. Same callback path as state 1.
+
+3. **Post-success — "Cloudflared has installed a certificate" modal.** The bound account already has a cert authorised for the zones the dashboard knows about. The OAuth callback is idempotent — navigating to a fresh `cloudflared tunnel login` URL still fires the callback, so `~/.cloudflared/cert.pem` will land. Wait a second or two, then run the `mv`.
+
+   If the cert *also* exists at `${CFG_DIR}/cert.pem` from a prior partial run, Step 1 is already complete — skip to Step 2.
+
+4. **Blank or button-less — neither the Authorize button nor the success modal is on the page.** The browser may be mid-load, signed out of Cloudflare, blocking on captcha, or showing some other state. Sign in to Cloudflare in the same browser, navigate back to the URL `cloudflared tunnel login` printed, and complete the click manually. If the URL has expired, kill `cloudflared` (`Ctrl+C`) and re-run Step 1 to get a fresh URL.
+
+---
+
+## 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 — any of these output shapes:** cloudflared emits one of three distinct messages on exit 0, all of which mean the hostname is routed correctly. Do not parse stdout to distinguish them — exit 0 is the signal.
+
+1. New record: `Added CNAME <hostname> which will route to this tunnel`
+2. Overwritten: `Added CNAME <hostname> which will route to this tunnel` (same shape as new; `--overwrite-dns` makes overwrite transparent)
+3. Idempotent no-op: `<timestamp> INF <hostname> is already configured to route to your tunnel tunnelID=<UUID>`
+
+Shape 3 is what a second clean run of setup-tunnel.sh against an already-configured hostname emits. Historically the shell script's stdout parser rejected this shape and exited 1 on the idempotent case; the script now relies on cloudflared's exit code exclusively.
+
+**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 — with a critical twist documented below. If you used the script, this step is already done and the service will restart a few seconds after the script exits.
+
+
+```
+systemctl --user restart "${BRAND}.service"
+```
+
+**Why the script dispatches the restart via `systemd-run` instead of a direct `systemctl restart`:** when the admin agent invokes `setup-tunnel.sh` via the Bash tool, the script runs *inside* `${BRAND}.service`'s cgroup. A direct `systemctl --user restart ${BRAND}.service` from that cgroup tells systemd to SIGTERM the entire cgroup — the node server, the claude subprocess, the Bash child, and the script itself all die simultaneously. cgroup membership is inherited: `setsid`, `nohup`, `disown`, and `&` all stay in the caller's cgroup, and `systemd-run --scope` runs in the caller's scope. Only `systemd-run --user --unit=<name> --on-active=<N>s` creates a genuinely new transient unit with its own cgroup. The script uses that primitive to arm the restart a few seconds after its own exit:
+
+```
+systemd-run --user --unit=maxy-tunnel-restart-<nonce>.service --on-active=3s --collect \
+  /bin/systemctl --user restart "${BRAND}.service"
+```
+
+The script then emits `[script:setup-tunnel] step=service-restart-dispatched` and `step=service-restart-armed exit=0` in the per-conversation stream log so operators see exactly when the restart was scheduled, exits 0, and the transient timer fires from outside the service's cgroup — semantically identical to this manual runbook's `systemctl --user restart`. (The `script:` prefix is the chat-surface namespace — see `_stream-log.sh` header.)
+
+When walking through manually you do **not** need `systemd-run` — your SSH shell already lives in a separate user-scope cgroup (`user@<uid>.service`), so the direct `systemctl restart` does not kill the caller. The script's extra indirection only matters when the caller *is* the service being restarted.
+
+**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.