@rubytech/create-siteoffice-code 0.1.256

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

@@ -0,0 +1,166 @@
+# Cloudflare API — master token, minted narrow tokens, endpoint map
+
+The Cloudflare REST API is a permitted surface on this install. It is how the agent does DNS edits, Pages deploys, D1 queries, Access policies, and apex-CNAME creation without driving the dashboard. This reference is the library: where the canonical docs live, how auth works (one operator-provisioned master token; the agent mints short-lived narrow tokens from it), where the master is stored, and the curated endpoints worth knowing.
+
+Canonical reference (always the source of truth for request shapes, never mirror it wholesale here): **https://developers.cloudflare.com/api/**
+
+---
+
+## Auth model — one master, many minted narrow tokens
+
+There are two distinct tokens in play. Keep them separate.
+
+- **Master token** — fully-scoped, long-lived, provisioned **once** by the operator in the dashboard (see § Provisioning the master token, below). Broad enough to manage Pages, D1, DNS, **and** create API tokens. The agent reads it only to mint narrow tokens. It is never passed to `wrangler`, never put on a command line that gets echoed, never printed.
+- **Minted narrow token** — scoped to exactly one operation class (a single-zone DNS edit, a one-project Pages deploy, a D1 query), short-lived, created by the agent via the API call below. Exported into the environment for the one `wrangler` / API call, then discarded. Never written to disk, never committed, never echoed into chat.
+
+Why mint instead of hand-rolling: the operator provisions the master once; every per-operation token is minted by the agent on demand, so the operator never hand-crafts scoped tokens and no broad token is ever exported to a tool that could log it.
+
+---
+
+## Master token storage — account-scoped secrets file
+
+Store the master at an account-scoped secrets file, **not** in any deployable project tree:
+
+```
+~/<brand>-code/data/accounts/<accountId>/secrets/cloudflare.env      # mode 600, umask 077
+```
+
+(worked example: `~/realagent-code/data/accounts/<accountId>/secrets/cloudflare.env`)
+
+It holds exactly two values:
+
+```
+CLOUDFLARE_API_TOKEN=<master>
+CLOUDFLARE_ACCOUNT_ID=<accountId>
+```
+
+Rationale (binding):
+
+1. **Account-isolated** — under `data/accounts/<accountId>/`, consistent with brand isolation; one account's master never sits where another account's flow can read it.
+2. **Outside every deployable/git project tree** — so the god-token can never be committed or shipped in a Pages upload. This is the failure mode a project-root `.env` invites: a `.env` next to a site's source gets swept into the `wrangler pages deploy` upload or a `git add .`.
+3. **Sourced on demand for the master only** — `set -a; . <file>; set +a` to load `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` into the environment for the mint call; per-operation narrow tokens go into the ephemeral environment of their single command, never into this file.
+
+Create it once (mode 600, parent dirs 700):
+
+```bash
+ACCOUNT_ID="<accountId>"
+SECRETS_DIR="${HOME}/<brand>-code/data/accounts/${ACCOUNT_ID}/secrets"
+( umask 077; mkdir -p "${SECRETS_DIR}" )
+# The operator pastes the master token; the agent never echoes it back.
+( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "<master>" "${ACCOUNT_ID}" > "${SECRETS_DIR}/cloudflare.env" )
+chmod 600 "${SECRETS_DIR}/cloudflare.env"
+```
+
+Load the master for a mint call:
+
+```bash
+set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a
+```
+
+---
+
+## Provisioning the master token (ADVANCED — operator-guided, never automated)
+
+This is the one manual, operator-driven step. The agent relays the click-path; it does **not** browser-automate it (no Playwright, no Chrome DevTools, no consent-page driver).
+
+1. Open **https://dash.cloudflare.com/profile/api-tokens** in your browser.
+2. Click **Create Token** → **Create Custom Token** → **Get started**.
+3. Name it (e.g. `<brand> master`). Under **Permissions**, add these rows (Account-level unless noted):
+   - **Account · Cloudflare Pages · Edit**
+   - **Account · D1 · Edit**
+   - **Account · API Tokens · Write**  ← this is what lets the agent mint narrow tokens
+   - **Zone · DNS · Edit** (Zone Resources → the zones you route)
+   - **Account · Cloudflare Tunnel · Edit** (only if you want the API to manage tunnels alongside `cloudflared`)
+4. **Account Resources** → Include → your account. **Zone Resources** → Include → the zones in scope.
+5. Click **Continue to summary**, then **Create Token**.
+6. Copy the token **once** — Cloudflare shows it a single time. Paste it into the secrets file (above). The agent stores it without echoing it back.
+
+Verify the master works (token value never printed — only the verification result):
+
+```bash
+set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a
+curl -sS -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+  "https://api.cloudflare.com/client/v4/user/tokens/verify" | jq '.result.status'
+# expect: "active"
+```
+
+---
+
+## Minting a narrow token
+
+The agent mints a per-operation token from the master via `POST /accounts/{account_id}/tokens`. Scope it to the single operation, give it a short TTL, export it for the one call, discard it.
+
+```bash
+set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a   # loads the master + account id
+
+# Example: a one-project Pages-deploy token. Adjust the policy for the operation.
+MINTED=$(curl -sS -X POST \
+  -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+  -H "Content-Type: application/json" \
+  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/tokens" \
+  --data @- <<'JSON' | jq -r '.result.value'
+{
+  "name": "ephemeral-pages-deploy",
+  "policies": [{
+    "effect": "allow",
+    "resources": { "com.cloudflare.api.account.<accountId>": "*" },
+    "permission_groups": [{ "id": "<pages-edit-permission-group-id>", "name": "Pages Write" }]
+  }],
+  "expires_on": "<iso8601-a-few-minutes-out>"
+}
+JSON
+)
+
+# Use it for exactly one command, in this command's environment only:
+CLOUDFLARE_API_TOKEN="${MINTED}" wrangler pages deploy ./dist --project-name <project> --branch=main
+
+unset MINTED   # discard; never written to disk, never echoed
+```
+
+Look up `<pages-edit-permission-group-id>` (and the ids for DNS Edit, D1 Edit, etc.) once via `GET /accounts/{account_id}/tokens/permission_groups`; they are stable per account.
+
+**Redaction is binding.** Every example above pipes the token into a variable or an `Authorization` header and never to stdout. The agent surfaces the operation as verb + target — "minting a Pages-deploy token", "creating CNAME `chat.example.com`" — never the secret. A failure surfaces the API error body with any `Authorization` value masked.
+
+---
+
+## Curated endpoint map
+
+Request/response shapes live at the canonical docs URL; this is the index of what to reach for. `${ACC}` = `CLOUDFLARE_ACCOUNT_ID`, `${ZONE}` = the zone id, `${TOKEN}` = a **minted narrow** token.
+
+### Token create / verify
+- `GET  /user/tokens/verify` — confirm a token is active.
+- `POST /accounts/${ACC}/tokens` — mint a narrow token (see above).
+- `GET  /accounts/${ACC}/tokens/permission_groups` — resolve permission-group ids for scoping.
+
+### DNS records (zone-scoped; needs **Zone · DNS · Edit**)
+- `GET  /zones/${ZONE}/dns_records` — list / find a record id.
+- `POST /zones/${ZONE}/dns_records` — create. For an **apex CNAME**, set `"type":"CNAME"`, `"name":"@"` (or the bare zone name), `"content":"<UUID>.cfargotunnel.com"`, `"proxied":true` — Cloudflare flattens it automatically. This is the API equivalent of the dashboard apex edit in `dashboard-guide.md`.
+- `PUT/PATCH /zones/${ZONE}/dns_records/{id}` — update. `DELETE …/{id}` — remove a stray record.
+
+```bash
+curl -sS -X POST -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
+  "https://api.cloudflare.com/client/v4/zones/${ZONE}/dns_records" \
+  --data '{"type":"CNAME","name":"@","content":"<UUID>.cfargotunnel.com","proxied":true}' \
+  | jq '{ok:.success, name:.result.name}'
+```
+
+### Zones
+- `GET /zones?account.id=${ACC}` — list zones on the account; find a zone id by name (`?name=example.com`).
+
+### Tunnels (Account · Cloudflare Tunnel)
+- `GET  /accounts/${ACC}/cfd_tunnel` — list tunnels.
+- `POST /accounts/${ACC}/cfd_tunnel` — create. `DELETE …/{tunnel_id}` — delete.
+- The OAuth/`cloudflared` path in `manual-setup.md` remains the primary tunnel flow; use the API only when an end-to-end programmatic run is wanted.
+
+### Access (Zero Trust) applications + policies
+- `POST /accounts/${ACC}/access/apps` and `POST /accounts/${ACC}/access/apps/{app_id}/policies` — author an Access application + policy programmatically. The dashboard click-path in `dashboard-guide.md` § "Author an Access policy" is the alternative for operators who prefer to click.
+
+---
+
+## When to use which path
+
+- **Tunnel create/route/run** → `cloudflared` (OAuth cert), per `manual-setup.md`. The API can manage tunnels too, but the cert path is the established one.
+- **Apex CNAME** → API (above) or dashboard (`dashboard-guide.md`). Either flattens correctly.
+- **Pages deploy** → `wrangler` with a minted Pages-Edit token, per `hosting-sites.md`.
+- **D1 read/write** → `wrangler d1 execute --remote` with a minted D1-Edit token, per `d1-data-capture.md`.
+- **Inspecting account state** (which zones, which tunnels) → API `GET` with a read-scoped minted token, or the dashboard.

package/payload/platform/plugins/cloudflare/references/d1-data-capture.md

@@ -0,0 +1,157 @@
+# Capturing form submissions into Cloudflare D1
+
+This is the established pattern for turning a static site's contact / waitlist form into durable, queryable leads: the form POSTs to a **Pages Function**, the Function inserts a row into a **Cloudflare D1** database, and the agent reads and sweeps new rows with `wrangler d1 execute --remote`. It is live on `realagent.pages.dev` today — the worked example below is that deployment, generalized with placeholders.
+
+Pair this with `hosting-sites.md` (how the site itself gets deployed) and `api.md` (the master token + mint-narrow discipline that authenticates every `wrangler` call).
+
+---
+
+## The single most common breakage — token scope
+
+A Pages-only token **cannot touch D1**. The deploy succeeds, the form renders, and every submission silently 500s at the D1 insert. The token used for D1-backed Pages work must carry **both**:
+
+- **Account · Cloudflare Pages · Edit**
+- **Account · D1 · Edit**
+
+Mint a narrow token that includes both permission groups (see `api.md` § Minting a narrow token) before any `wrangler d1` or D1-backed deploy command. This was observed live in the session that built `realagent.pages.dev`; it is the first thing to check when captures stop arriving.
+
+---
+
+## 0. Mint the Pages-+-D1 token
+
+Every command below uses `${MINTED_PAGES_D1}` — a narrow token scoped to **both** Pages Edit and D1 Edit, minted from the master per `api.md` § Minting a narrow token. Mint it once at the start of the session and export it; it is never written to disk or echoed:
+
+```bash
+set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a   # loads master + account id
+MINTED_PAGES_D1=$(curl -sS -X POST \
+  -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
+  -H "Content-Type: application/json" \
+  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/tokens" \
+  --data @- <<'JSON' | jq -r '.result.value'
+{
+  "name": "ephemeral-pages-d1",
+  "policies": [{
+    "effect": "allow",
+    "resources": { "com.cloudflare.api.account.<accountId>": "*" },
+    "permission_groups": [
+      { "id": "<pages-edit-permission-group-id>", "name": "Pages Write" },
+      { "id": "<d1-edit-permission-group-id>", "name": "D1 Write" }
+    ]
+  }],
+  "expires_on": "<iso8601-a-few-minutes-out>"
+}
+JSON
+)
+```
+
+Resolve the two permission-group ids once via `GET /accounts/{account_id}/tokens/permission_groups` (see `api.md`). When the work is done, `unset MINTED_PAGES_D1`.
+
+---
+
+## 1. Create the database
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 create <db-name>
+# worked example: wrangler d1 create realagent-leads
+```
+
+`wrangler` prints the database `name` and `database_id`. Copy the `database_id` into `wrangler.toml` (next step). The token value is never printed — only the database identifiers.
+
+## 2. Bind the database in `wrangler.toml`
+
+The binding name (`DB` below) is the variable the Pages Function reads off `env`. Keep `wrangler.toml` in the site's project root — it carries no secret, only the database id.
+
+```toml
+name = "<project>"                 # worked example: realagent
+pages_build_output_dir = "dist"    # or the framework's output dir
+
+[[d1_databases]]
+binding = "DB"
+database_name = "<db-name>"        # realagent-leads
+database_id = "<database_id>"      # from step 1
+```
+
+## 3. Create the table
+
+Apply the schema to the remote database (`--remote` targets the live D1, not a local replica):
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 execute <db-name> --remote --command \
+  "CREATE TABLE IF NOT EXISTS leads (
+     id INTEGER PRIMARY KEY AUTOINCREMENT,
+     name TEXT,
+     email TEXT NOT NULL,
+     message TEXT,
+     created_at TEXT NOT NULL DEFAULT (datetime('now')),
+     swept INTEGER NOT NULL DEFAULT 0
+   );"
+```
+
+The `swept` column is the read-cursor: a row is `swept = 0` until the agent has ingested it, then flipped to `1`. This is what makes "show me new leads" a deterministic query rather than a guess.
+
+## 4. The Pages Function — `functions/api/contact.ts`
+
+A file at `functions/api/contact.ts` is served at `POST /api/contact` automatically (Pages Functions route by file path). It reads the `DB` binding and inserts a row. No secret lives in this file — the D1 binding is injected by the platform at runtime.
+
+```ts
+interface Env { DB: D1Database }
+
+export const onRequestPost: PagesFunction<Env> = async ({ request, env }) => {
+  const form = await request.formData();
+  const email = String(form.get("email") ?? "").trim();
+  if (!email) return new Response("email required", { status: 400 });
+
+  await env.DB
+    .prepare("INSERT INTO leads (name, email, message) VALUES (?, ?, ?)")
+    .bind(String(form.get("name") ?? ""), email, String(form.get("message") ?? ""))
+    .run();
+
+  return new Response(null, { status: 303, headers: { Location: "/thanks" } });
+};
+```
+
+The site's form posts to it:
+
+```html
+<form method="POST" action="/api/contact">
+  <input name="email" type="email" required>
+  <input name="name">
+  <textarea name="message"></textarea>
+  <button>Join the waitlist</button>
+</form>
+```
+
+## 5. Deploy
+
+Deploy via `hosting-sites.md`. The binding in `wrangler.toml` is what wires the deployed Function to D1; the deploy token must carry both Pages Edit and D1 Edit (above).
+
+## 6. Read and sweep new submissions
+
+Read everything not yet ingested:
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 execute <db-name> --remote --json --command \
+  "SELECT id, name, email, message, created_at FROM leads WHERE swept = 0 ORDER BY id;"
+```
+
+After ingesting those rows (e.g. writing them into the graph), mark them swept so the next read returns only newer ones:
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 execute <db-name> --remote --command \
+  "UPDATE leads SET swept = 1 WHERE swept = 0;"
+```
+
+---
+
+## Outcome contract
+
+D1 capture is done when a **test POST to the live form** appears in the unswept set:
+
+```bash
+curl -sS -X POST -d "email=test@example.com&name=verify" "https://<project>.pages.dev/api/contact" -i | head -1
+# then:
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 execute <db-name> --remote --command \
+  "SELECT email FROM leads WHERE swept = 0;"
+```
+
+The test email appearing in that `SELECT` is the proof. A 200/303 on the POST alone is not — the row in D1 is the contract. Surface the operation as verb + target ("inserting a test lead", "reading unswept rows from `realagent-leads`"); the token value never appears.

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

@@ -0,0 +1,173 @@
+# 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 the agent prints an `ACTION REQUIRED` block for an apex (per `references/manual-setup.md` § Step 4), 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).
+
+---
+
+## Author an Access policy for SSH or SMB
+
+When the agent adds an SSH or SMB ingress hostname (per `references/manual-setup.md`),
+the Access policy must exist before off-LAN clients can reach the Pi. There are two
+paths: the agent can author it via the Cloudflare API with a minted Access-scoped
+token (see `references/api.md` § Access), or the operator can author it by hand in the
+dashboard with the click-path below. `cloudflared` CLI has no Access-application create
+subcommand, so the dashboard path is the manual alternative to the API.
+
+1. Click **Zero Trust** in the sidebar.
+2. Click **Access** → **Applications**.
+3. Click **Add an application**, then **Self-hosted**.
+4. Set **Application name** to the hostname (e.g. `ssh.maxy.bot`).
+5. Set **Application domain** to the same hostname. **Subdomain** is the
+   first DNS label (`ssh`), **Domain** is the registered parent zone
+   (`maxy.bot`), **Path** stays blank.
+6. Click **Next** through the identity/CORS pages (defaults are fine
+   for a single-operator setup).
+7. On the **Add policies** page, click **Add a policy**.
+8. **Policy name:** "Operator allow". **Action:** `Allow`.
+9. Under **Configure rules** → **Include**, add a rule:
+   **Selector** = `Emails`, **Value** = the operator's email (the same
+   one named in the `ACTION REQUIRED` block).
+10. Click **Save** to land the policy, then **Add application** to land
+    the application.
+
+Repeat for the SMB hostname if the script printed both. Identity list
+gates both routes; the same emails apply.
+
+**Verify:** From an off-LAN machine run
+`cloudflared access login https://ssh.<brand>.<rootdomain>`. Cloudflare
+prompts for the operator email, sends a one-time PIN, and returns to a
+success page. Then `cloudflared access ssh --hostname ssh.<brand>.<rootdomain>`
+opens an SSH prompt to the Pi.
+
+---
+
+## Create a URL Rewrite Rule
+
+A URL Rewrite Rule silently rewrites the path the origin server receives without changing the URL the visitor sees in their browser. Use this when you want a custom domain root (e.g. `getmaxy.com/`) to serve a path that lives elsewhere on the origin (e.g. `/sites/getmaxy/`) without redirecting the visitor.
+
+This is **not** the same as a Page Rule redirect. Page Rules issue a visible 301/302 to the browser; a Rewrite Rule changes only what the origin receives, transparently.
+
+1. Click **Websites** in the sidebar, then click the zone.
+2. Click **Rules** in the left-hand sidebar, then **Overview**.
+3. Click **Create rule**, then select **URL Rewrite Rule**.
+   Alternatively, click **Create from template** and choose **"Rewrite path of moved section"** for a pre-filled starting point.
+4. Enter a descriptive **Rule name** (e.g. `getmaxy apex → marketing site`).
+5. Under **If incoming requests match**, select **Custom filter expression** and enter the expression. For a match on bare domain and www:
+   ```
+   (http.host eq "example.com") or (http.host eq "www.example.com")
+   ```
+6. Under **Then**, set **Path** → **Rewrite to** → **Dynamic** and enter the expression:
+   ```
+   concat("/sites/mysite", http.request.uri.path)
+   ```
+   Leave **Query string** on **Preserve** (unchanged).
+7. Click **Deploy**.
+
+No server restart is needed. Verify with `curl -s https://<domain>/ | head` — the response should be the site's HTML, not the agent SPA `<div id="root">`.
+
+**When the zone cert misroutes:** if `cloudflared tunnel route dns` is run for a hostname in a zone the cert was not authorised for at `tunnel login`, it silently creates a record in the wrong zone (appends the cert's zone as a suffix). Check the emitted record name in the command output; if it has an unexpected suffix, delete the stray record via `DNS → Records` and create the CNAME manually in the correct zone instead.
+
+---
+
+## 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/hosting-sites.md

@@ -0,0 +1,66 @@
+# Deploying a site to Cloudflare Pages
+
+How to put a static or Next.js site on Cloudflare Pages via `wrangler`, the way `realagent.pages.dev` is deployed. This covers the build → deploy → verify loop and the Next.js specifics. Auth is a minted narrow token per `api.md`; if the site also captures form data, read `d1-data-capture.md` for the dual Pages-Edit **and** D1-Edit scope.
+
+This is distinct from `references/serving-published-sites.md`, which serves a platform-published site at a custom domain through the brand's **cloudflared tunnel**. This reference is about **Cloudflare Pages** — Cloudflare hosts the build, not the install device.
+
+---
+
+## When to use Pages vs the tunnel
+
+- **Cloudflare Pages** (this reference) — a standalone marketing/landing/app site that Cloudflare builds and serves on its edge, optionally with Pages Functions + D1. Use when the site is its own project and you want Cloudflare to host it.
+- **The brand tunnel** (`manual-setup.md` + `serving-published-sites.md`) — expose something running on the install device at a custom domain. Use when the content is served by the platform itself.
+
+---
+
+## 1. Build the site
+
+Produce the static output the framework emits.
+
+- **Static / Vite / Astro:** `npm run build` → output in `dist/` (or the framework default).
+- **Next.js:** Pages needs a static or edge-compatible build. For a fully static site use `output: "export"` in `next.config.js` and `npm run build` → output in `out/`. For a Next.js app with server routes, deploy through the Pages adapter (`@cloudflare/next-on-pages`): `npx @cloudflare/next-on-pages` → output in `.vercel/output/static`.
+
+## 2. Configure `wrangler.toml`
+
+```toml
+name = "<project>"                       # the Pages project name, e.g. realagent
+pages_build_output_dir = "<output-dir>"  # dist | out | .vercel/output/static
+compatibility_date = "2024-01-01"
+compatibility_flags = ["nodejs_compat"]  # required for next-on-pages and most Functions
+```
+
+If the site captures form data, add the `[[d1_databases]]` binding from `d1-data-capture.md` here.
+
+## 3. Mint a deploy token
+
+A Pages deploy needs **Account · Cloudflare Pages · Edit**. If the site has Pages Functions hitting D1, the token also needs **Account · D1 · Edit** (the single most common breakage — see `d1-data-capture.md`). Mint it per `api.md` § Minting a narrow token:
+
+```bash
+set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a
+# MINTED = a narrow token scoped to Pages Edit (+ D1 Edit if the site uses D1)
+```
+
+## 4. Deploy
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED}" wrangler pages deploy <output-dir> \
+  --project-name <project> --branch=main
+```
+
+`--branch=main` deploys to the production alias (`https://<project>.pages.dev`); any other branch name produces a preview URL instead. The first deploy of a new project name creates the project. The token value is never printed — `wrangler` prints the deployment URL, which is what gets surfaced.
+
+## 5. Custom domain (optional)
+
+Attach a custom domain to the Pages project in the dashboard (**Workers & Pages → your project → Custom domains → Set up a domain**), or via the API. Cloudflare provisions the certificate and the CNAME automatically when the zone is on the same account.
+
+---
+
+## Outcome contract
+
+Hosting is done when the deployed URL serves the **new** build:
+
+```bash
+curl -s "https://<project>.pages.dev/" | head
+```
+
+The response showing the new markup is the proof. A successful `wrangler` exit alone is not the contract — the live URL returning the new content is. Surface the operation as verb + target ("deploying Pages project `realagent`"); the token value never appears in chat or stdout.