@rubytech/create-realagent 1.0.623 → 1.0.624

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -1,31 +1,19 @@
 ---
 name: cloudflare
-description: Cloudflare Tunnel setup and management — a deterministic orchestrator drives the full setup flow; raw tunnel-* tools are internal sub-steps
-tools:
-  - cloudflare-setup-run
-  - cloudflare-setup-status
-  - tunnel-login
-  - tunnel-status
-  - tunnel-install
-  - tunnel-create
-  - tunnel-enable
-  - tunnel-disable
-  - tunnel-add-hostname
-  - dns-lookup
+description: Cloudflare Tunnel operations — setup, reset, dashboard guidance. Zero agent-facing MCP tools; every operation is a shell script or a dashboard click-path the operator performs themselves.
+tools: []
 ---
 
-# Cloudflare Tunnel Setup
+# Cloudflare Tunnel
 
-Each installation has its own Cloudflare account. The operator signs in with OAuth (`tunnel-login`) — `cloudflared` writes `cert.pem` and the plugin records which Cloudflare account this laptop is signed into (`account-binding.json`). That binding is a drift detector only: if the operator later signs in under a different account, subsequent tool calls refuse and point the operator back to the browser.
-
-The Cloudflare dashboard is the single source of truth for which domains, addresses, and tunnels exist on the account. The plugin never reads or mutates account state via any API path — only `cloudflared` CLI shell-outs (which use the signed-in cert locally) and DNS + HTTPS probes against public surfaces. When something is wrong, the agent tells the operator where to click in the dashboard; the operator clicks; then the agent runs the next `cloudflared` command.
+Each installation has its own Cloudflare account. The operator signs in with OAuth via `cloudflared tunnel login` (driven by `setup-tunnel.sh`); `cloudflared` writes `cert.pem` to the brand-scoped config directory. The Cloudflare dashboard is the single source of truth for which domains, addresses, and tunnels exist; the plugin never reads or mutates account state via any API path — only `cloudflared` CLI shell-outs the scripts execute, and DNS + HTTPS probes against public surfaces.
 
 ## When to activate
 
 - Operator mentions Cloudflare, custom domain, public access, or internet access
 - Operator wants to expose the assistant publicly with a custom URL
 - Operator asks about setting up remote access with a custom domain
-- Operator says "set up Cloudflare" or similar
+- Operator says "set up Cloudflare", "reset the tunnel", "my tunnel is broken", or similar
 
 ## What it unlocks
 
@@ -34,40 +22,39 @@ The Cloudflare dashboard is the single source of truth for which domains, addres
 - Custom-branded public chat URLs
 - Webhook endpoints on a stable domain
 
-## Tools
-
-### Operator-facing entry point
+## Operator-facing surface
 
-| Tool | Purpose |
-|------|---------|
-| `cloudflare-setup-run` | Run the full setup flow to completion. One call advances one deterministic step (the state machine is in `setup-orchestrator.ts`). The admin agent's only job is to relay the tool's structured output and pass the operator's literal next input through. |
-| `cloudflare-setup-status` | Read-only diagnostic — returns the current orchestrator phase without advancing. |
+The plugin registers no agent-facing MCP tools (Task 554). Every Cloudflare operation is driven through one of four sanctioned surfaces — `setup-tunnel.sh`, `reset-tunnel.sh`, `references/manual-setup.md`, or `references/dashboard-guide.md`. See the skill below for the discipline rule that binds the agent to these four.
 
-### Internal sub-tools (orchestrator invokes; direct use supported for diagnostics)
+### Scripts
 
-| Tool | Purpose |
-|------|---------|
-| `tunnel-login` | Authenticate via `cloudflared tunnel login`. Sub-step of the orchestrator. |
-| `tunnel-create` | Create tunnel + route DNS for admin (+ optional public) hostname. Sub-step. |
-| `tunnel-enable` | Start the `cloudflared` daemon and verify edge reachability. Sub-step. |
-| `tunnel-status` | End-to-end probe (DNS + HTTPS); `healthy` / `unhealthyReason` enum output drives the orchestrator's next phase choice. |
-| `tunnel-add-hostname` | Add an additional address to the running tunnel. Not driven by the orchestrator. |
-| `tunnel-install` | Install the `cloudflared` binary when missing. |
-| `tunnel-disable` | Stop the `cloudflared` daemon; config preserved. |
-| `dns-lookup` | General-purpose DNS resolver (replaces `dig`/`nslookup`). |
+| Script | Purpose |
+|---|---|
+| [`scripts/setup-tunnel.sh`](scripts/setup-tunnel.sh) | Autonomous end-to-end setup: OAuth login, tunnel create, DNS route, config + state, service restart, post-restart verification. Invocation: `~/setup-tunnel.sh <brand> <port> <admin-hostname> [<public-hostname>] [<apex-hostname>]`. Apex hostnames print an `ACTION REQUIRED` block for the dashboard record the CLI cannot create. |
+| [`scripts/reset-tunnel.sh`](scripts/reset-tunnel.sh) | Deletes every tunnel on the brand's CF account and wipes `${CFG_DIR}`. Does not touch the platform service, stray CNAMEs, or token-mode connectors — those require dashboard cleanup or `pkill`. Invocation: `~/reset-tunnel.sh <brand>`. |
 
-While `cloudflare-setup-run` is mid-flow (phase ≠ idle/healthy/unhealthy), the admin agent's tool menu is filtered: the raw `tunnel-*` tools, Playwright / Chrome DevTools browser tools, and `Bash` / `Write` / `Edit` are removed. This is enforced in `platform/ui/app/lib/tool-surface-filter.ts` — see `.docs/agents.md` §"Tool-surface gates".
-
-## Skills
+### Skills
 
 | Skill | Purpose |
-|-------|---------|
-| [setup-tunnel/SKILL.md](skills/setup-tunnel/SKILL.md) | One-paragraph instruction — "call `cloudflare-setup-run`, relay verbatim, pass operator input through" |
+|---|---|
+| [setup-tunnel/SKILL.md](skills/setup-tunnel/SKILL.md) | Names the four sanctioned surfaces (autonomous / manual / reset / dashboard), the inputs to collect before invoking `setup-tunnel.sh`, and the tool-discipline rule that binds the agent. |
 
-## References
+### References
 
 | Reference | Topics |
-|-----------|--------|
-| [setup-guide.md](references/setup-guide.md) | Prerequisites, domain setup in the dashboard, troubleshooting, tool reference |
+|---|---|
+| [manual-setup.md](references/manual-setup.md) | Step-by-step human runbook — Steps 0–7 with isolated command blocks. Used when diagnosing a failing scripted step or working on a device where the scripts are not yet deployed. |
+| [dashboard-guide.md](references/dashboard-guide.md) | Click-paths for the operations only the Cloudflare dashboard can perform — sign in, switch accounts, add a site, edit an apex CNAME, verify nameservers, delete a tunnel, manage CNAME records. |
+| [reset-guide.md](references/reset-guide.md) | Decision tree for reset vs. patch, the exact `pkill` incantation for token-mode connectors, and the dashboard cleanup paths for stray records and rogue entries. |
+
+The agent loads these references on demand via `plugin-read` as the conversation requires. They are not auto-injected into the system prompt.
+
+## Identity model
+
+- **Product identity** (Maxy vs Real Agent) — known from `brand.json` (`productName`, `configDir`).
+- **Cloudflare account identity** — `cert.pem` from OAuth. One account per brand per device.
+- **Account binding drift** — `~/{configDir}/cloudflared/account-binding.json` is a historical drift marker. Reset via `reset-tunnel.sh` when switching accounts.
+
+## Discipline
 
-Load the relevant skill or reference based on the task.
+Loaded into IDENTITY.md § Cloudflare operations at install time. The short form: the agent's permitted surfaces are the two scripts, the three reference files, and plain `curl` reachability checks — everything else (Playwright, WebSearch-for-CF-recipes, Cloudflare API / SDK, ad-hoc `cloudflared` flag invention, direct edits to cert.pem / tunnel.state / config.yml / alias-domains.json) is out of bounds. Sanctioned-surface failures are reported with evidence and cited against `reset-guide.md`, not improvised around.