@rubytech/create-maxy-code 0.1.243 → 0.1.246

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

@@ -105,12 +105,12 @@ Use this when you need to audit which hostnames are pointing at which `<UUID>.cf
 
 ## Author an Access policy for SSH or SMB
 
-When the agent adds an SSH or SMB ingress hostname (per `references/manual-setup.md`), it surfaces an
-`ACTION REQUIRED` block naming this click-path. The agent does NOT
-create the Access policy — Cloudflare API/SDK is banned
-(`feedback_cf_api_total_eradication`) and `cloudflared` CLI has no
-Access-application create subcommand — so the operator must author it
-in the dashboard before off-LAN clients can reach the Pi.
+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**.

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.

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

@@ -293,9 +293,11 @@ does this on every Pi). The script skips the SMB ingress with
 `[tunnel-install] smb-ingress-skipped reason=samba-not-provisioned`
 rather than failing.
 
-**Access policy is dashboard-only.** Cloudflare API/SDK is forbidden;
-`cloudflared` CLI has no Access-application create subcommand. After
-the ingress is in place, author the policy in the dashboard:
+**Access policy — API or dashboard.** `cloudflared` CLI has no
+Access-application create subcommand, so author the policy either via
+the Cloudflare API with a minted Access-scoped token (see
+`references/api.md` § Access) or by hand in the dashboard. After the
+ingress is in place, the dashboard path is:
 
 ```
 Cloudflare → Zero Trust → Access → Applications → Add → Self-hosted

package/payload/platform/plugins/cloudflare/skills/cloudflare/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: cloudflare
+description: Cloudflare operations for the install — tunnel setup/diagnosis/reset, DNS edits, Pages hosting, and D1 data capture. The agent drives `cloudflared` and `wrangler` directly via Bash and reads the matching reference before each operation class; success is always a live behavioural signal (external HTTP 200, a deployed URL, a D1 round-trip), never an exit code.
+---
+
+# Cloudflare operations
+
+This is the entry point for every Cloudflare task on the install. Pick the operation class, read the matching reference, run the command via Bash, relay the literal output, and prove the outcome with a live signal. There are no Cloudflare MCP tools; the plugin registers none. The agent never browser-automates the dashboard — the operator clicks where a click is genuinely required.
+
+| You want to… | Read | Outcome contract |
+|---|---|---|
+| Stand up / diagnose / reset a tunnel so a hostname is reachable | `references/manual-setup.md` | external `curl -I https://<hostname>` → `200` |
+| Switch accounts, edit an apex CNAME by hand, or other dashboard-only clicks | `references/dashboard-guide.md` | the click-path completed in the operator's browser |
+| Tear down corrupt tunnel state and start clean | `references/reset-guide.md` | a fresh `manual-setup.md` run reaches `200` |
+| Call the Cloudflare API (DNS, zones, tunnels, Access, token mint) | `references/api.md` | the API call returns success and the change is observable |
+| Deploy a static / Next.js site to Cloudflare Pages | `references/hosting-sites.md` | the deployed URL serves the new build |
+| Capture form/waitlist submissions into a database | `references/d1-data-capture.md` | a test POST appears in `SELECT … WHERE swept = 0` |
+
+## Two auth paths, by operation class
+
+- **Tunnel auth is OAuth.** `cloudflared tunnel login` writes `cert.pem`; the operator clicks the linkified OAuth URL in their own browser. This is the only path for tunnel create/route/run. See `references/manual-setup.md`.
+- **API auth is the master token.** The operator provisions one fully-scoped master token once (an **advanced**, operator-guided dashboard step — the agent does not automate it) and stores it at the account-scoped secrets file. The agent reads the master only to **mint a narrowly-scoped, short-lived token** for each operation — a single-zone DNS edit, a one-project Pages deploy, a D1 query — and exports that ephemeral token for the one call. See `references/api.md` for the storage convention, the mint flow, and the binding redaction discipline.
+
+Neither the master token nor any minted token is ever written into a project tree, committed, or echoed into chat.
+
+## Outcome contracts — what "done" means
+
+Every Cloudflare operation proves itself with a live behavioural signal surfaced verbatim in chat:
+
+- **Tunnel:** `curl -I https://<hostname>` from outside the local network returns `HTTP/2 200` (or `HTTP/1.1 200 OK`). No state file, no `result=ok` line, no "service is active" claim substitutes. If the curl returns anything else, diagnose with `cloudflared tunnel info <tunnelId>` and `systemctl --user status ${BRAND}-cloudflared.service` and recover per `references/manual-setup.md`.
+- **Hosting:** the deployed Pages URL returns the new build (`curl -s https://<project>.pages.dev/ | head` shows the new markup).
+- **D1 capture:** a test POST to the live form appears in `wrangler d1 execute <db> --remote --command "SELECT … WHERE swept = 0"`.
+
+## Inputs (tunnel)
+
+Four inputs come from the operator in chat: the admin FQDN, optional public FQDN, optional apex FQDN, and the admin password. `BRAND` is derived from disk — never hardcoded — with `BRAND=$(jq -r .hostname ~/.<configDir>/brand.json)`. The same install can host different brands on different ports; `brand.json.hostname` is the only authoritative source.
+
+## Execution
+
+The agent reads the relevant reference and executes its steps with Bash. Every `cloudflared` / `wrangler` / `curl` invocation's stdout and stderr are relayed into chat verbatim — minus any secret, which is always redacted. The OAuth URL printed by `cloudflared tunnel login` is linkified by the native PTY; the operator clicks it in their own browser. The agent does not spawn a browser, automate the Cloudflare consent page, or drive the dashboard via Playwright or Chrome DevTools.
+
+Tunnel mutations the agent performs from `references/manual-setup.md` (each one only after reading the relevant step):
+
+- `cloudflared tunnel login` — emits the OAuth URL; cert lands at `~/.cloudflared/cert.pem` after the operator authorises.
+- `cloudflared tunnel --origincert <cert> create <name>` — produces `<tunnelId>.json` credentials.
+- Write `~/.${BRAND}/cloudflared/config.yml` (ingress block per the runbook).
+- `cloudflared tunnel --origincert <cert> route dns <tunnelId> <hostname>` — one call per non-apex hostname.
+- For non-admin hostnames not starting with `public.`, append to `~/.${BRAND}/alias-domains.json` so `isPublicHost()` treats them as public.
+- Install + start the `${BRAND}-cloudflared.service` user unit (`systemctl --user daemon-reload && systemctl --user enable --now ${BRAND}-cloudflared.service`).
+
+After the service is up, the agent runs `curl -I https://<admin-hostname>` and pastes the response. The setup-done claim only fires when a `200` line appears in that response.
+
+## Apex hostnames
+
+The `cloudflared` CLI cannot route apex records (e.g. `maxy.chat`) — standard DNS forbids a CNAME at the zone apex. There are now two ways to create the apex record: the operator edits the apex CNAME in the dashboard (`references/dashboard-guide.md` § "Edit an apex CNAME"), or the agent creates it via the Cloudflare API with a minted DNS-scoped token (`references/api.md` § DNS records). Either reaches the same flattened-CNAME result; pick the dashboard path when the operator prefers to click, the API path when an end-to-end agent run is wanted.
+
+## Reset
+
+When local Cloudflare state is corrupt or the operator wants to start from a known-good cert, follow `references/reset-guide.md`. The agent issues the relevant `cloudflared tunnel delete` and `rm -rf ~/.${BRAND}/cloudflared/` commands in Bash, then re-runs the setup steps above.
+
+## Tool discipline — binding
+
+When the operator's request touches Cloudflare, the agent's permitted actions are:
+
+- Invoke `cloudflared` via Bash, following `references/manual-setup.md`.
+- Invoke `wrangler` and the Cloudflare API via Bash, following `references/api.md`, `references/hosting-sites.md`, and `references/d1-data-capture.md`, using a freshly-minted narrow token per operation.
+- Write `config.yml` and `alias-domains.json` per the runbook.
+- Install and start the brand's cloudflared user service.
+- Quote `references/manual-setup.md`, `references/reset-guide.md`, or `references/dashboard-guide.md` verbatim when a dashboard click-path is the right tool.
+- Verify reachability via `curl -I https://<hostname>` and surface the response.
+
+The agent does not drive the dashboard via Playwright or Chrome DevTools, and does not browser-automate master-token creation. It does not synthesise `cloudflared` flag combinations from web search or training — every command comes from the runbook. It never writes a token to disk in a project tree, commits one, or prints one into chat. When a step fails, the agent reports the exact output, names the recovery step from `references/reset-guide.md`, and stops. Improvisation — "let me try a different flag" or "let me drive the dashboard myself" — is the behaviour this rule exists to prevent.

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

@@ -1,6 +1,6 @@
 # Cloudflare Tunnel — the dashboard is the source of truth
 
-Each installation has its own Cloudflare account. Sign-in is OAuth: the agent invokes `cloudflared tunnel login` via Bash; the Cloudflare Authorize URL streams into the admin chat PTY and the native terminal renders it as a clickable link. Click it, authorise in your own browser, and `cloudflared` writes `cert.pem` to the brand's config directory. The agent never reads or mutates Cloudflare account state directly — whatever you see in your logged-in dashboard is the single source of truth. When something needs doing on the account side (adding a domain, deleting a stray entry, switching accounts), the agent relays the click-paths; you run them in your browser.
+Each installation has its own Cloudflare account. The **tunnel** sign-in is OAuth: the agent invokes `cloudflared tunnel login` via Bash; the Cloudflare Authorize URL streams into the admin chat PTY and the native terminal renders it as a clickable link. Click it, authorise in your own browser, and `cloudflared` writes `cert.pem` to the brand's config directory. For **everything else** (DNS, Pages, D1, Access) the agent uses the Cloudflare API, authenticated by a short-lived narrow token it mints from a master token you provision once in the dashboard (an advanced step the agent never automates). Some account-side jobs — adding a domain, switching accounts — are still easiest in your browser, and the agent relays those click-paths; the rest it can do directly via the API.
 
 ## Identity model
 
@@ -8,10 +8,10 @@ Each installation has its own Cloudflare account. Sign-in is OAuth: the agent in
 |------|--------|
 | **Product identity** (Maxy vs Real Agent) | `brand.json` (`productName`, `configDir`) — known at install. |
 | **Cloudflare account identity** | `cert.pem` from OAuth. One account per brand per device. |
-| **Domain scope** (which zones the operator can route) | Live Cloudflare dashboard — the operator picks the zone in the dashboard during OAuth or names it in chat. The agent does not enumerate zones programmatically. |
+| **Domain scope** (which zones the operator can route) | The operator picks the zone in the dashboard during OAuth or names it in chat; the agent can also enumerate zones via the API with a minted read-scoped token. |
 | **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `alias-domains.json`. |
 
-There is no token-based auth for the operator-owned path (Mode A). To switch Cloudflare accounts, the agent runs the reset flow from `plugins/cloudflare/references/reset-guide.md` (deletes the cert and every tunnel on the current account), then the manual-setup flow again — `cloudflared tunnel login` picks a fresh account when you sign in.
+Tunnel auth on the operator-owned path (Mode A) is the OAuth cert (`cert.pem`); API operations use a narrow token the agent mints from your master token. To switch Cloudflare accounts, the agent runs the reset flow from `plugins/cloudflare/references/reset-guide.md` (deletes the cert and every tunnel on the current account), then the manual-setup flow again — `cloudflared tunnel login` picks a fresh account when you sign in.
 
 ## Setup flow
 
@@ -97,6 +97,6 @@ The most common cause is wrong nameservers on the domain. The domain must use Cl
 
 **Does:** invokes `cloudflared` directly via Bash, following `plugins/cloudflare/references/manual-setup.md` step by step; quotes click-paths from the reference files verbatim; verifies external reachability with `curl -I` and surfaces the response.
 
-**Does not:** drive the Cloudflare dashboard via Playwright, synthesise alternative `cloudflared` flag sequences not in the runbook, call any Cloudflare API or SDK, write or edit `cert.pem` / `config.yml` directly outside the runbook's instructions.
+**Does not:** drive the Cloudflare dashboard via Playwright, browser-automate master-token creation, synthesise alternative `cloudflared` flag sequences not in the runbook, write or echo any API token, write or edit `cert.pem` / `config.yml` directly outside the runbook's instructions.
 
 When a command fails, the agent reports the failure and cites the relevant recovery step. It does not improvise.

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

@@ -70,7 +70,7 @@ Grep for both in `~/.<brand>/logs/install-*.log`. Absence after a clean install
 
 The first user-domain write the agent attempts (e.g. recording who the operator is) hits the graph-write gate's `Write blocked (no-admin-user)` or `Write blocked (no-local-business)` error. The agent then asks the persona question, persists the answer through the `business-profile` skill or `profile-update.personFields`, and proceeds. The error itself is the signal — grep `Write blocked` in `~/.<brand>/logs/server.log` to confirm.
 
-Cloudflare, WhatsApp, Telegram, and any other dormant capability surfaces on owner request via the `<dormant-plugins>` sentinel the manager injects per-spawn. Execution is the existing plugin skill (`cloudflare:setup-tunnel`, etc.) — no banner, no per-step flag.
+Cloudflare, WhatsApp, Telegram, and any other dormant capability surfaces on owner request via the `<dormant-plugins>` sentinel the manager injects per-spawn. Execution is the existing plugin skill (`cloudflare:cloudflare`, etc.) — no banner, no per-step flag.
 
 ### Per-spawn system-prompt sentinels
 

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

@@ -223,7 +223,7 @@ When `search` is true and `query` is non-null, the rewritten query replaces the
 
 ### Knowledge retrieval gate
 
-On the public PTY surface the agent itself decides when to call `memory-search` — there is no server-side classifier interposed between the user message and the agent's first tool call. KNOWLEDGE.md (when present) is assembled into the agent's system prompt at spawn time. Whether `memory-search` is reachable at message time is controlled by the agent's `liveMemory` config flag: when `true`, the per-spawn allowlist includes `memory-search` and reads run with `ALLOWED_SCOPES=public`; when `false`, the agent has no graph access mid-turn. When `liveMemory` is false and the visitor sent no attachment, the public allowlist resolves empty; because public webchat runs in `dontAsk` (Task 506), the spawner anchors the allowlist with a single non-native deny-basis token (`mcp__none__deny-basis`) so `--allowed-tools` is always present and native-excluding (Task 609) — without it, `dontAsk` would have nothing to deny against and the brand `allow:["*"]` would re-open native tools.
+The public agent is toolless by construction (Task 615): it has no `memory-search`, no graph access mid-turn, and no tools of any kind. KNOWLEDGE.md (when present) plus SOUL are assembled into the agent's system prompt at spawn time and are the entire knowledge surface. Every `role=public` spawn (webchat, whatsapp, telegram) resolves an empty allowlist and runs in `dontAsk` (Task 506) with a per-spawn `permissions.deny` covering every native, harness, and memory-MCP tool (Task 612). The spawner anchors the empty allowlist with a single non-native deny-basis token (`mcp__none__deny-basis`) so `--allowed-tools` is always present and native-excluding (Task 609) — without it, `dontAsk` would have nothing to deny against and the brand `allow:["*"]` would re-open native tools.
 
 ### Observability
 
@@ -340,10 +340,7 @@ The final step in the retrieval pipeline is injecting retrieved content into the
 
 Public agents run on the same native Claude Code PTY surface as the admin, dispatched through the channel PTY-bridge with `role: 'public'`. The agent's directory files (IDENTITY.md, SOUL.md, KNOWLEDGE.md, KNOWLEDGE-SUMMARY.md when present) are assembled into the system prompt at spawn time. There is no per-turn server-side knowledge injection.
 
-Two paths, selected by the agent's `liveMemory` config flag:
-
-- **`liveMemory: false`** — `memory-search` is excluded from the per-spawn `--allowed-tools` allowlist. The agent has no graph access mid-conversation; KNOWLEDGE.md is the ceiling of factual knowledge.
-- **`liveMemory: true`** — `memory-search` is in the allowlist. The agent decides at message time whether to call it; reads run against the graph with `ALLOWED_SCOPES=public` so only public-scoped nodes return. KNOWLEDGE.md and the live `memory-search` surface are complementary — the baked file covers evergreen facts; the live tool covers the long-tail public-scoped lookups.
+The public agent is toolless by construction (Task 615): `memory-search` and every other tool are excluded from the per-spawn `--allowed-tools` allowlist on every public channel, and a per-spawn `permissions.deny` blocks them outright (Task 612). The agent has no graph access mid-conversation; KNOWLEDGE.md is the ceiling of factual knowledge.
 
 ### KNOWLEDGE.md staleness guard
 
@@ -447,7 +444,7 @@ The SDK's per-tool override is `_meta["anthropic/alwaysLoad"]: true` on each MCP
 
 Each `claude` PTY spawn registers every callable MCP server and every dispatchable subagent before the operator's first turn. **Platform MCP servers come from one channel — installed plugins — for admin and specialist spawns (Task 502).** Claude Code's plugin system serves every plugin MCP tool under the long prefix `mcp__plugin_<plugin>_<server>__<tool>` (for platform plugins `plugin == server == directory`), which is the canonical name the admin `--allowed-tools` argv and every specialist `tools:` frontmatter bind to. Admin spawns no longer write a per-spawn `.mcp.json` or pass `--mcp-config`; the per-account env (`ACCOUNT_ID`, `USER_ID`, `NEO4J_URI`, `NEO4J_PASSWORD`, `PLATFORM_ROOT`, `CLAUDE_CONFIG_DIR`) rides the PTY env block.
 
-**Public agents are the one exception.** A public-facing web agent should boot only the handful of servers it may use, not every installed plugin, so public spawns retain the per-spawn `mcp-config.json` (`--mcp-config <path>`) that restricts the server set to plugins exposing at least one `publicAllowlist: true` tool (minus memory when `liveMemory: false`). Per-spawn descriptors keep the SHORT prefix `mcp__<plugin>__<tool>`, which is why the public allowlist (`toolSurface.public`) stays short while admin/all are long. The descriptor's `command` routes through `lib/mcp-spawn-tee/dist/index.js` so each child server's stderr lands in `${LOG_DIR}/mcp-<name>-stderr-<date>.log` even on synchronous module-load throws (Task 743 wrapper). `--strict-mcp-config` only ever guarded auto-discovery of a project `.mcp.json`; it is retained on the public per-spawn path and dropped from admin spawns that no longer pass `--mcp-config`.
+**Public agents are the one exception.** A public-facing web agent is toolless by construction (Task 615), so public spawns retain the per-spawn `mcp-config.json` (`--mcp-config <path>`) but register **zero** servers in it — the file carries an empty `mcpServers`. Combined with the empty `--allowed-tools`, the `dontAsk` mode, and the per-spawn `permissions.deny` (Task 612), no tool reaches an anonymous visitor on any channel. `--strict-mcp-config` (which only ever guarded auto-discovery of a project `.mcp.json`) is retained on the public per-spawn path so no project file is discovered either; it is dropped from admin spawns that no longer pass `--mcp-config`.
 
 For subagents, the same spawn pushes `--add-dir` for every bundled plugin agents directory (`platform/plugins/*/agents/`, `premium-plugins/*/agents/`) — both roles — plus the per-account specialists directory `<accountDir>/specialists/agents/` (admin only). Claude Code's `subagent_type` dispatch reads the agent file off disk via the added directories; without `--add-dir` the dispatcher returns "no matching agent."
 

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

@@ -3,7 +3,7 @@ name: memory
 description: "Graph memory plugin. Provides memory-search (with optional `fields` projection for known-shape lookups), memory-write, memory-update, memory-edge (create/delete typed directed edges between pre-existing nodes), memory-update-by-name (repair surface that resolves an elementId from a (label, name, accountId) tuple when search cannot return one), memory-lookup-by-name (deterministic read surface that returns nodes by case-insensitive exact `name` match, optionally constrained by labels, bypassing the memory-search ranking stack so a present entity is never missed because a diluted query ranked it below the cut), and the :Report surface (memory-report-write / memory-report-read-latest / memory-report-list) for reading from, writing to, and updating the Neo4j knowledge graph. Includes conversational memory — organic preference learning, evidence-backed recall, and transparent 'what do you know about me?' responses. Document ingestion goes through memory-ingest; the dispatched specialist produces typed-section JSON in-turn from the loaded ontology. Operator-solicited reclassify of an already-stored thread-shaped KD (today: email-thread KDs) is exposed as `kd-classify <attachmentId>` — runs a body-growth gate (proceed iff body grew ≥25% since the last classify, or first-ever classify), stages the body to a temp file under `$ACCOUNT_DIR/tmp/`, and returns a dispatch envelope for the `librarian`; on success `memory-ingest` replaces the prior :Section children and stamps `lastClassifiedAt` + `lastClassifiedBodyLength` on the parent KD. Two modes: `document` (default) for unstructured PDF/web content → :KnowledgeDocument (keyed on `attachmentId`) + :Section, and `chat` for conversation transcripts → :ConversationArchive (keyed on `conversationIdentity`) + :Section chunks; two parent labels, two writer paths chosen by which identity property is set. Conversation-archive Phase 2 splits across two read-only tools (Task 433): `conversation-archive-list-chunks` pages chunk bodies for the dispatched specialist to read in-turn; `conversation-archive-derive-insights` converts the specialist's per-chunk claims into operator-facing proposals with per-kind cypher. `conversation-archive-enrich-rejection` records (or undoes) durable per-row rejections so already-triaged claims do not re-surface on re-runs. Ships five skills: `conversational-memory`, `document-ingest`, `conversation-archive` (source-agnostic transcript ingest for WhatsApp, Telegram, Signal, LinkedIn DMs, Zoom, meeting minutes, iMessage, Slack), `conversation-archive-mcp` (operator-initiated MCP-driven ingest for Granola, Otter, Circleback meetings — sibling of `conversation-archive` sharing the same writer surface and identity formula), and `conversation-archive-enrich` (per-row operator-gated insight derivation over a named archive's chunks). Ships three thinking-tool skills: `challenge` (adversarial retrieval — strongest counter-evidence from the graph for a given claim), `connect` (bridge-finding between two topics via shared graph neighbors), and `emerge` (clusters uncategorised KnowledgeDocument and Section nodes into operator-approved Concept proposals)."
 tools:
   - name: memory-search
-    publicAllowlist: true
+    publicAllowlist: false
     adminAllowlist: true
   - name: memory-write
     publicAllowlist: false
@@ -161,7 +161,7 @@ mcp-manifest: auto
 
 # Memory
 
-Provides read and write access to the Neo4j knowledge graph — search, structured writes, document ingestion, attachment management, conversation history, and user profiles. Tool routing is each agent's IDENTITY.md responsibility; this plugin describes what tools are available, not when to use them. The admin agent and specialist subagents call these tools directly via MCP. Public agents with `liveMemory: true` in their config receive `memory-search` via the per-spawn `--allowed-tools` allowlist; the memory MCP server scopes every read to `ALLOWED_SCOPES=public` so only nodes with `scope: "public"` are reachable. Public agents with `liveMemory: false` get no MCP tools from this plugin — their knowledge comes only from the baked KNOWLEDGE.md.
+Provides read and write access to the Neo4j knowledge graph — search, structured writes, document ingestion, attachment management, conversation history, and user profiles. Tool routing is each agent's IDENTITY.md responsibility; this plugin describes what tools are available, not when to use them. The admin agent and specialist subagents call these tools directly via MCP. Public agents are toolless by construction (Task 615): they receive no MCP tools from this plugin and have no graph access mid-conversation — their knowledge comes only from the baked KNOWLEDGE.md and SOUL assembled into the system prompt at spawn.
 
 Tools are available via the `memory` MCP server.