@rubytech/create-maxy-code 0.1.244 → 0.1.246

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:849e817f1959f8b45a530e2d28f3eaa9a3fc7ad66729747d92087517ae7e3fe8
+content-hash: sha256:bff8fac482b70e56a1d4dd32167987663f0282ce43f4659d9c8c5cb592f77cd9
 brand: maxy-code
 product-name: Maxy
 ---
@@ -645,7 +645,7 @@ macOS is the lightweight surface. Compared with the Pi install, the macOS path d
 
 - **No cgroup / resource decoupling.** Pi installs decouple Claude Code's cgroup from systemd's session scope so a closed VNC viewer cannot reap the long-running agent. macOS uses launchd, which is already per-user and does not have the same cleanup pathology, so the work is unnecessary.
 - **No VNC.** The admin UI is the surface. You drive it from a browser on the same machine or any device on the LAN; there is no display server to bootstrap.
-- **No `cloudflared` tunnel by default.** Pi installs ship a tunnel because the device is typically headless and on a residential network. On a Mac the LAN URL is usually enough; if you want a public URL, install `cloudflared` separately and run `cloudflared tunnel login` from the terminal. Cloudflare API tokens are never used — only the CLI's interactive `tunnel login` flow.
+- **No `cloudflared` tunnel by default.** Pi installs ship a tunnel because the device is typically headless and on a residential network. On a Mac the LAN URL is usually enough; if you want a public URL, install `cloudflared` separately and run `cloudflared tunnel login` from the terminal. The tunnel uses the CLI's interactive `tunnel login` flow; other Cloudflare operations (DNS, Pages, D1) use the API with a token the agent mints from an operator-provisioned master.
 
 ## Smoke checklist
 
@@ -677,7 +677,7 @@ The doc is brand-aware. Examples use the default brand `maxy-code`; substitute `
 - Raspberry Pi 5, 16GB RAM (canonical) — Pi 4 8GB works but the first install runs slower.
 - Ubuntu Server 24.04 LTS, 64-bit, freshly imaged with Raspberry Pi Imager. Earlier Ubuntu / Pi OS releases are not part of the supported matrix.
 - The pi has a wired or Wi-Fi route to the internet and an SSH-reachable user with sudo (the username does not matter — Rubytech images ship `admin` by default).
-- A Cloudflare account whose dashboard you can sign into in a web browser. No API tokens are ever issued or stored; the only Cloudflare auth path is `cloudflared tunnel login` running in the Pi's VNC browser after install.
+- A Cloudflare account whose dashboard you can sign into in a web browser. The tunnel signs in via `cloudflared tunnel login` (OAuth, in the Pi's VNC browser after install); DNS/Pages/D1 use the Cloudflare API with a token the agent mints from a master token you provision once.
 - A connected monitor or a working VNC viewer for the one-time `cloudflared tunnel login` step. After that step the Pi runs headless.
 
 For Hetzner Cloud, see [hetzner.md](hetzner.md). The apt path, systemd user-service, and Cloudflare flow are the same; the difference is that a cloud VM has no physical display and no LAN to the operator, so the noVNC browser is reached over SSH port-forwarding for the one-time Cloudflare bootstrap.
@@ -749,9 +749,9 @@ The installer also wires `loginctl enable-linger <user>` so the user-service sur
 
 ## 4. Bootstrap the Cloudflare tunnel
 
-The installer puts `cloudflared` on PATH but does not provision the tunnel — Cloudflare auth happens once, interactively, in a browser the operator drives. There is no API token, no service token, no SDK call: the only auth path is `cloudflared tunnel login`, which writes a browser-issued cert to `$HOME/.maxy-code/.cloudflared/cert.pem` on success.
+The installer puts `cloudflared` on PATH but does not provision the tunnel — Cloudflare tunnel auth happens once, interactively, in a browser the operator drives. The tunnel's only auth path is `cloudflared tunnel login`, which writes a browser-issued cert to `$HOME/.maxy-code/.cloudflared/cert.pem` on success. Other Cloudflare operations (DNS, Pages, D1) use the API with a token the agent mints from an operator-provisioned master — see the `cloudflare` plugin.
 
-Open the Pi's VNC browser at `http://<hostname>.local:<port>/vnc` (or over the LAN at whichever port the install log printed for noVNC). In the chat surface, ask the agent to run the Cloudflare setup — the [`cloudflare`](../../platform/plugins/cloudflare/PLUGIN.md) plugin's `setup-tunnel` skill walks `cloudflared tunnel login`, `cloudflared tunnel create`, `cloudflared tunnel route dns`, and the systemd `<hostname>-cloudflared.service` unit in order, streaming `cloudflared`'s stdout verbatim into chat. The OAuth URL the CLI prints is linkified by the PTY; the operator clicks it inside the VNC browser and authorises the cert against the right Cloudflare account.
+Open the Pi's VNC browser at `http://<hostname>.local:<port>/vnc` (or over the LAN at whichever port the install log printed for noVNC). In the chat surface, ask the agent to run the Cloudflare setup — the [`cloudflare`](../../platform/plugins/cloudflare/PLUGIN.md) plugin's `cloudflare` skill walks `cloudflared tunnel login`, `cloudflared tunnel create`, `cloudflared tunnel route dns`, and the systemd `<hostname>-cloudflared.service` unit in order, streaming `cloudflared`'s stdout verbatim into chat. The OAuth URL the CLI prints is linkified by the PTY; the operator clicks it inside the VNC browser and authorises the cert against the right Cloudflare account.
 
 Setup is done when, and only when, `curl -I https://<hostname>.<your-zone>` issued from outside the local network returns `HTTP/2 200`. No state file, no `tunnel run` exit code, and no "service is active" claim substitutes for the live HTTPS response.
 
@@ -798,7 +798,7 @@ npx -y @rubytech/create-realagent-code@latest --uninstall
 ## What this install does not do
 
 - **No SCP / rsync.** The Pi is reached over npm only. Updates are `npx -y @rubytech/create-maxy-code@latest …` again, never a file push from the operator's laptop.
-- **No Cloudflare API tokens.** The only Cloudflare auth path is `cloudflared tunnel login` running in the Pi's VNC browser. If a doc, plugin, or workflow asks for a CF API token it is wrong — surface the discrepancy before proceeding.
+- **Tunnel auth is OAuth; the API is permitted for the rest.** The tunnel's only auth path is `cloudflared tunnel login` in the Pi's VNC browser. DNS, Pages, and D1 use the Cloudflare API with a short-lived narrow token the agent mints from an operator-provisioned master token (see the `cloudflare` plugin); tokens are never written to a project tree or echoed.
 - **No shared state across brands.** Two brands on one Pi each have their own Neo4j port, systemd unit, VNC display, websockify port, tunnel, and persist directory. They do not share DNS, ports, or filesystem state.
 
 ## Smoke checklist
@@ -807,7 +807,7 @@ Fresh-Pi smoke pass criteria:
 
 1. Install on a clean Ubuntu Server 24.04 image with no prior Maxy footprint completes, prints a LAN URL, and the systemd user-service is `active (running)`.
 2. The LAN URL `http://<hostname>.local:<port>` opens the admin UI and the chat surface is interactive.
-3. Cloudflare setup driven by the `cloudflare` plugin's `setup-tunnel` skill ends with `curl -I https://<hostname>.<your-zone>` returning `HTTP/2 200` from outside the LAN.
+3. Cloudflare setup driven by the `cloudflare` plugin's `cloudflare` skill ends with `curl -I https://<hostname>.<your-zone>` returning `HTTP/2 200` from outside the LAN.
 4. Reboot — both URLs are reachable again after boot without any manual action.
 5. Install a second brand with a different `--hostname`; both brands' admin UIs are reachable on their own ports / public URLs and neither has touched the other's state.
 6. Uninstall removes the systemd unit, the Avahi service file, and the persist directory.
@@ -949,9 +949,9 @@ After the Cloudflare tunnel is provisioned, close the SSH session — every surf
 
 ## 5. Bootstrap the Cloudflare tunnel
 
-The installer puts `cloudflared` on PATH but does not provision the tunnel — Cloudflare auth happens once, interactively, in the noVNC browser the operator drives over the SSH forward from step 4. There is no API token, no service token, no SDK call: the only auth path is `cloudflared tunnel login`, which writes a browser-issued cert to `$HOME/.maxy-code/.cloudflared/cert.pem` on success.
+The installer puts `cloudflared` on PATH but does not provision the tunnel — Cloudflare tunnel auth happens once, interactively, in the noVNC browser the operator drives over the SSH forward from step 4. The tunnel's only auth path is `cloudflared tunnel login`, which writes a browser-issued cert to `$HOME/.maxy-code/.cloudflared/cert.pem` on success. Other Cloudflare operations (DNS, Pages, D1) use the API with a token the agent mints from an operator-provisioned master — see the `cloudflare` plugin.
 
-In the noVNC browser session, open the admin UI at `http://localhost:<port>`. In chat, ask the agent to run the Cloudflare setup — the [`cloudflare`](../../platform/plugins/cloudflare/PLUGIN.md) plugin's `setup-tunnel` skill walks `cloudflared tunnel login`, `cloudflared tunnel create`, `cloudflared tunnel route dns`, and the systemd `<hostname>-cloudflared.service` unit in order, streaming `cloudflared`'s stdout verbatim into chat. The OAuth URL the CLI prints is linkified by the PTY; the operator clicks it inside the noVNC browser and authorises the cert against the right Cloudflare account.
+In the noVNC browser session, open the admin UI at `http://localhost:<port>`. In chat, ask the agent to run the Cloudflare setup — the [`cloudflare`](../../platform/plugins/cloudflare/PLUGIN.md) plugin's `cloudflare` skill walks `cloudflared tunnel login`, `cloudflared tunnel create`, `cloudflared tunnel route dns`, and the systemd `<hostname>-cloudflared.service` unit in order, streaming `cloudflared`'s stdout verbatim into chat. The OAuth URL the CLI prints is linkified by the PTY; the operator clicks it inside the noVNC browser and authorises the cert against the right Cloudflare account.
 
 Setup is done when, and only when, `curl -I https://<hostname>.<your-zone>` issued from the operator's laptop returns `HTTP/2 200`. No state file, no `tunnel run` exit code, and no "service is active" claim substitutes for the live HTTPS response.
 
@@ -993,7 +993,7 @@ npx -y @rubytech/create-realagent-code@latest --uninstall
 ## What this install does not do
 
 - **No SCP / rsync.** Updates are `npx -y @rubytech/create-maxy-code@latest …` again, never a file push from the operator's laptop.
-- **No Cloudflare API tokens.** The only Cloudflare auth path is `cloudflared tunnel login` in the noVNC browser over SSH forward.
+- **Tunnel auth is OAuth; the API is permitted for the rest.** The tunnel's only auth path is `cloudflared tunnel login` in the noVNC browser over SSH forward. DNS, Pages, and D1 use the Cloudflare API with a short-lived narrow token the agent mints from an operator-provisioned master token (see the `cloudflare` plugin).
 - **No shared state across brands.** Two brands on one server each have their own Neo4j port, systemd unit, VNC display, websockify port, tunnel, and persist directory.
 - **No public IPv4 exposure.** The Hetzner firewall opens port 22 only; every operator-facing surface is fronted by the Cloudflare tunnel.
 
@@ -1004,7 +1004,7 @@ Fresh-Hetzner smoke pass criteria:
 1. Provision a CAX31 with Ubuntu 24.04 arm64 and an SSH key; SSH in as `root`, create `admin`, switch.
 2. Install completes on the clean image, prints a loopback URL, and the systemd user-service is `active (running)`.
 3. The noVNC page reached over `ssh -L 8080:localhost:<novnc-port>` displays the admin UI.
-4. Cloudflare setup driven by the `cloudflare` plugin's `setup-tunnel` skill ends with `curl -I https://<hostname>.<your-zone>` returning `HTTP/2 200` from the operator's laptop.
+4. Cloudflare setup driven by the `cloudflare` plugin's `cloudflare` skill ends with `curl -I https://<hostname>.<your-zone>` returning `HTTP/2 200` from the operator's laptop.
 5. Reboot the server; both `<hostname>.service` and `<hostname>-cloudflared.service` come back up; the public URL is reachable again without any manual action.
 6. Install a second brand with a different `--hostname`; both brands' admin UIs are reachable on their own public hostnames and neither has touched the other's state.
 7. Uninstall removes the systemd unit and the persist directory.
@@ -1017,7 +1017,7 @@ Source: https://docs.getmaxy.com/cloudflare.md
 
 # 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
 
@@ -1025,10 +1025,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
 
@@ -1114,7 +1114,7 @@ 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.
 
@@ -3281,7 +3281,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/admin/skills/public-agent-manager/SKILL.md

@@ -1,6 +1,6 @@
 # Public Agent Manager
 
-Create, edit, clone, list, preview, and delete public agents. Each public agent is a self-contained directory under `agents/` with its own identity, personality, knowledge, model, and selected plugins.
+Create, edit, clone, list, preview, and delete public agents. Each public agent is a self-contained directory under `agents/` with its own identity, personality, knowledge, and model.
 
 ## Agent Directory Structure
 
@@ -8,13 +8,15 @@ Each agent lives at `{accountDir}/agents/{slug}/`:
 
 | File | Purpose | Required |
 |------|---------|----------|
-| `config.json` | Model, selected plugins, display name, status, image identity | Yes |
-| `IDENTITY.md` | Boundaries, behavioural rules | Yes |
-| `SOUL.md` | Personality only — tone, voice, warmth, greeting style | Yes |
-| `KNOWLEDGE.md` | Domain facts from the graph — pricing, FAQs, services | No |
+| `config.json` | Model, display name, status, image identity, knowledge keywords | Yes |
+| `IDENTITY.md` | Boundaries, behavioural rules — copied verbatim from the Rubytech template | Yes |
+| `SOUL.md` | Personality and role — tone, voice, warmth, greeting; plus the agent's job: give basic public info and capture the visitor's contact details for human follow-up (the chat equivalent of the landing-page contact form) | Yes |
+| `KNOWLEDGE.md` | The business's public-facing facts at landing-page detail — pricing, FAQs, services | Yes |
 | `KNOWLEDGE-SUMMARY.md` | Auto-generated summary when KNOWLEDGE.md exceeds context budget | No |
 | `assets/` | Per-agent images (logo, avatar, icon) | No |
 
+`SOUL.md` and `KNOWLEDGE.md` are authored entirely client-side by you at agent creation and must be **non-empty before the agent goes active** — a public spawn whose SOUL or KNOWLEDGE is empty or missing is refused at spawn (the visitor sees an unavailable state, never a dud agent), so neither ships as a template nor is seeded by the installer. `IDENTITY.md` is copied verbatim from the Rubytech-controlled template, never drafted.
+
 ## Slug Rules
 
 - Lowercase a-z, 0-9, hyphens only
@@ -29,7 +31,6 @@ Each agent lives at `{accountDir}/agents/{slug}/`:
   "slug": "sales",
   "displayName": "Sales Agent",
   "model": "claude-haiku-4-5",
-  "plugins": ["sales"],
   "status": "active",
   "knowledgeKeywords": [],
   "image": "/agent-assets/sales/agent-image.png",
@@ -58,7 +59,7 @@ An optional image (avatar, icon, or logo) displayed in the public chat header in
 
 **Fallback chain:** agent image → account brand logo → platform default icon. When no image is configured, the existing brand logo behaviour is preserved.
 
-During creation (Step 7) and editing, offer image upload when the user has an image ready. Use the `agent-image` tool with `action: "set"`, providing the file path and the appropriate shape. If the user wants the agent's name shown in the header, set `showAgentName: true` in config.json.
+During creation (Step 6) and editing, offer image upload when the user has an image ready. Use the `agent-image` tool with `action: "set"`, providing the file path and the appropriate shape. If the user wants the agent's name shown in the header, set `showAgentName: true` in config.json.
 
 ### Knowledge Tagging
 
@@ -76,37 +77,15 @@ Present as a `select` field within the agent configuration `form` during creatio
 | Sonnet | `claude-sonnet-4-6` | Balanced. Nuanced conversation, qualification, support. | Standard |
 | Opus | `claude-opus-4-7` | Maximum intelligence. Complex sales, consultative selling. | Premium |
 
-### Plugin Selection
-
-Present available plugins as a `multi-select` component. Selected plugin names are stored in `config.json`. The platform filters embedded plugins per-agent at runtime — only plugins whose `metadata.platform.embed` includes `"public"` are actually embedded.
-
-Only present plugins from the curated list below. Before presenting, verify each plugin's directory exists under `$PLATFORM_ROOT/plugins/` (premium plugins are only available when delivered). Omit any plugin whose directory is absent.
-
-**Core (always available):**
-
-| Plugin | Description |
-|--------|-------------|
-| `sales` | Buying signal detection, closing techniques, objection handling |
-| `docs` | User guide and platform documentation |
-
-**Premium — Real Agent (only when delivered):**
-
-| Plugin | Description |
-|--------|-------------|
-| `buyers` | Buyer enquiry handling and educational guides |
-| `estate-coaching` | Agent coaching and performance development |
-| `estate-sales` | Real estate sales methodology |
-| `estate-teaching` | Training and educational content |
-
 ## SOUL.md Scope Enforcement
 
-SOUL.md is strictly personality. When the user provides content for SOUL.md, route non-personality content to the correct file:
+SOUL.md is personality and role. When the user provides content for SOUL.md, route content that belongs elsewhere to the correct file:
 
 - **Facts, pricing, services, FAQs** → KNOWLEDGE.md
-- **Engagement strategy, qualification flows, component usage** → handled by selected plugins
-- **Boundaries, tool rules, procedural instructions** → IDENTITY.md
+- **Engagement and qualification — how the agent draws out what the visitor needs and captures their contact details for human follow-up** → SOUL.md (this is the agent's role; the public agent is toolless, so there are no plugins to embed)
+- **Boundaries and procedural rules** → IDENTITY.md (Rubytech-controlled and copied verbatim — the agent's hard limits live there, not in SOUL)
 
-SOUL.md answers "what does this agent feel like to talk to?" — tone, warmth, formality, humour, greeting personality. SOUL.md must not restate constraints from IDENTITY.md. When user-provided content could belong to either file, apply this test: "does this restrict what the agent does?" → IDENTITY.md. "Does this describe how the agent sounds?" → SOUL.md. If content does both (e.g. "always respond politely"), route to SOUL — the constraint is a consequence of tone, not an operational boundary. Present SOUL.md via `document-editor` for the user to review and approve. Follow the document-editor encoding constraint in IDENTITY.md when generating content.
+SOUL.md answers "what does this agent feel like to talk to, and what is it here to do?" — tone, warmth, formality, greeting, and the role of giving basic public info and capturing contact details. SOUL.md must not restate constraints from IDENTITY.md. When user-provided content could belong to either file, apply this test: "does this restrict what the agent does?" → IDENTITY.md. "Does this describe how the agent sounds?" → SOUL.md. If content does both (e.g. "always respond politely"), route to SOUL — the constraint is a consequence of tone, not an operational boundary. Present SOUL.md via `document-editor` for the user to review and approve. Follow the document-editor encoding constraint in IDENTITY.md when generating content.
 
 ## KNOWLEDGE.md Population
 
@@ -136,10 +115,9 @@ The system prompt must leave room for conversation. After assembling all files,
 ```
 IDENTITY.md:     800 tokens
 SOUL.md:         400 tokens
-sales plugin:  2,100 tokens
 KNOWLEDGE.md:  8,200 tokens
 ─────────────────────────
-Total:        11,500 / 40,000 (29%)
+Total:         9,400 / 40,000 (24%)
 ```
 
 Warn if total exceeds 50% of the model's context window.
@@ -148,7 +126,7 @@ Warn if total exceeds 50% of the model's context window.
 
 ### Create from Template
 
-When template context is provided (a path to a template directory containing `template.json`, `IDENTITY.md`, and `SOUL.md`), the Create operation pre-populates its steps from the template. The user reviews and approves every file — the template is a starting point, not an automatic deployment.
+When template context is provided (a path to a template directory containing `template.json` and a `SOUL.md` seed), the Create operation pre-populates its steps from the template. The user reviews and approves every file — the template is a starting point, not an automatic deployment.
 
 Read the template's `template.json` and seed files. If `template.json` is unreadable or missing required fields (`suggestedSlug`, `displayName`), report the error and fall back to the standard Create flow.
 
@@ -156,12 +134,11 @@ The following Create steps are modified when a template is provided:
 
 - **Step 1** — use `suggestedSlug` from `template.json` as the initial slug. If an agent already exists at that slug, ask the user to choose a different name.
 - **Step 2** — skip. The agent name and role come from `template.json` `displayName` and `description`.
-- **Step 3** — pre-select the plugins listed in `template.json` `plugins` array. Only plugins that appear in the curated public-eligible list (see Plugin Selection above) can be pre-selected. If any template plugin is not available (not delivered, not enabled, or not marked for public embed), note which ones are missing and let the user adjust the selection.
-- **Step 5** — present the template's `IDENTITY.md` content via `document-editor` instead of drafting from a role description. The user can edit before approving.
-- **Step 6** — present the template's `SOUL.md` content via `document-editor` instead of drafting from conversation. The user can edit before approving.
-- **Step 7** — pre-populate form defaults: `model` from `template.json` (or `claude-haiku-4-5` if absent), `knowledgeKeywords` from `template.json` (or empty).
+- **Step 4** — unchanged: `IDENTITY.md` is always the Rubytech-controlled template copied verbatim, never the agent template's own identity.
+- **Step 5** — present the template's `SOUL.md` content via `document-editor` instead of drafting from conversation. The user can edit before approving.
+- **Step 6** — pre-populate form defaults: `model` from `template.json` (or `claude-haiku-4-5` if absent), `knowledgeKeywords` from `template.json` (or empty).
 
-All other steps (4, 8-12) proceed identically — knowledge discovery, direct tagging, KNOWLEDGE.md generation, config write, budget check, and confirmation are unchanged.
+All other steps (3, 7-12) proceed identically — knowledge discovery, direct tagging, KNOWLEDGE.md generation, config write, budget check, and confirmation are unchanged.
 
 After creation, no template metadata persists in the agent's files. The resulting agent is indistinguishable from one created manually. The user owns it completely.
 
@@ -169,11 +146,10 @@ After creation, no template metadata persists in the agent's files. The resultin
 
 1. **Pre-creation check** — verify the target directory (`agents/{slug}/`) does not exist or is empty before proceeding. If remnant files exist from a prior incomplete deletion, flag the issue to the user: show what files remain and offer to clean them up before starting fresh. Do not silently inherit stale files — a leftover `config.json` from a previous agent would bypass the creation gate.
 2. Ask for the agent's name (becomes the slug) and role description
-3. Present available plugins (multi-select)
-4. **Knowledge discovery** — search the graph with admin permissions (no `agentSlug` — the agent doesn't exist yet) to find available knowledge. Present available content grouped by category for the user to select.
-5. Present `IDENTITY.md` via document-editor with `filePath: "agents/{slug}/IDENTITY.md"` (draft from role description). Write on approval.
-6. Present `SOUL.md` via document-editor with `filePath: "agents/{slug}/SOUL.md"` (draft personality from user conversation). Write on approval.
-7. Present agent configuration via a single `form` component with these fields:
+3. **Knowledge discovery** — search the graph with admin permissions (no `agentSlug` — the agent doesn't exist yet) to find available knowledge. Present available content grouped by category for the user to select.
+4. **Install `IDENTITY.md`** — copy the Rubytech-controlled template verbatim to `agents/{slug}/IDENTITY.md`. It is fixed (the toolless public directive — Task 615) and is never drafted, edited, or presented for review.
+5. Present `SOUL.md` via document-editor with `filePath: "agents/{slug}/SOUL.md"` (draft personality and role from user conversation — tone plus the job of giving basic public info and capturing the visitor's contact details). Write on approval. Must be non-empty; an empty SOUL is refused at spawn.
+6. Present agent configuration via a single `form` component with these fields:
    - `knowledgeKeywords` (`text`): label "Knowledge keywords (max 5, comma-separated)", placeholder with examples relevant to the agent's role
    - `model` (`select`): label "Model", options with descriptions:
      - `claude-haiku-4-5` — "Haiku — Fast, cost-effective. FAQ, routing, high-volume."
@@ -183,30 +159,30 @@ After creation, no template metadata persists in the agent's files. The resultin
    The `model` field should have a `defaultValue` of `"claude-haiku-4-5"`.
    Wait for the user's response before proceeding.
    After the form is submitted, ask the user if they have an image (avatar, icon, or logo) for the agent. If yes, ask the user to provide the file and select the shape (circle for avatars/icons, rounded for logos), then use the `agent-image` tool to upload it.
-8. **Direct slug tagging (optional, gated)** — keyword subscriptions (configured in Step 7) and direct slug tagging are independent routing mechanisms. Keyword subscriptions route content by topic — any matching node is visible, now or in the future. Direct slug tagging routes specific nodes by identity — only explicitly tagged nodes are visible via the slug search path. Neither implies the other.
+7. **Direct slug tagging (optional, gated)** — keyword subscriptions (configured in Step 6) and direct slug tagging are independent routing mechanisms. Keyword subscriptions route content by topic — any matching node is visible, now or in the future. Direct slug tagging routes specific nodes by identity — only explicitly tagged nodes are visible via the slug search path. Neither implies the other.
 
    Ask the user whether any specific knowledge nodes should be tagged with this agent's slug. Explain that direct tagging makes specific nodes always visible to this agent regardless of keyword matches, and is useful for content that doesn't match any keyword but should still be available. If keyword subscriptions already cover the desired content, tagging is unnecessary.
 
-   - If the user approves: present the knowledge discovery results from Step 4 for selection, read each node's current `agents` array first, and confirm the new slug-tag set with the user. The recorder folds the slug onto each node's `agents` array in its next turn.
+   - If the user approves: present the knowledge discovery results from Step 3 for selection, read each node's current `agents` array first, and confirm the new slug-tag set with the user. The recorder folds the slug onto each node's `agents` array in its next turn.
    - If the user declines: skip tagging entirely. Do not propose tagging without explicit approval.
-9. **KNOWLEDGE.md generation** — populate from the now-tagged set plus keyword matches using the `update-knowledge` skill workflow
-10. Write `config.json` with selected model, plugins, status "active", and `knowledgeKeywords`. This is the last gated write — placed after IDENTITY.md, SOUL.md, and KNOWLEDGE.md to prevent cascade failure if one gate stalls.
-11. Check context budget — auto-summarise if over threshold
-12. **Project the agent into the graph** — delegate to the `specialists:database-operator` specialist with the instruction: "Project public agent `{slug}` into the graph by POSTing to `/api/admin/agents/{slug}/project`." The route reads the on-disk files and idempotently MERGEs the `:Agent` node, the four owned `:KnowledgeDocument` projections (IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY when present, namespaced `attachmentId="agent:<slug>:<role>"`), the `HAS_*` edges, and the `USES_KNOWLEDGE` edges to every operator-tagged doc. Loud-fail: if the route returns non-2xx, surface the error to the user verbatim — the agent's files exist on disk but its graph projection is incomplete, which means the operator's /graph view will not show this agent. Re-running the projection is safe; it is the same idempotent MERGE.
-13. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
+8. **KNOWLEDGE.md generation** — populate from the now-tagged set plus keyword matches using the `update-knowledge` skill workflow. KNOWLEDGE.md is required and must be non-empty; an empty or missing KNOWLEDGE is refused at spawn.
+9. Write `config.json` with selected model, status "active", and `knowledgeKeywords`. This is the last gated write — placed after IDENTITY.md, SOUL.md, and KNOWLEDGE.md to prevent cascade failure if one gate stalls.
+10. Check context budget — auto-summarise if over threshold
+11. **Project the agent into the graph** — delegate to the `specialists:database-operator` specialist with the instruction: "Project public agent `{slug}` into the graph by POSTing to `/api/admin/agents/{slug}/project`." The route reads the on-disk files and idempotently MERGEs the `:Agent` node, the four owned `:KnowledgeDocument` projections (IDENTITY/SOUL/KNOWLEDGE/KNOWLEDGE-SUMMARY when present, namespaced `attachmentId="agent:<slug>:<role>"`), the `HAS_*` edges, and the `USES_KNOWLEDGE` edges to every operator-tagged doc. Loud-fail: if the route returns non-2xx, surface the error to the user verbatim — the agent's files exist on disk but its graph projection is incomplete, which means the operator's /graph view will not show this agent. Re-running the projection is safe; it is the same idempotent MERGE.
+12. Confirm creation: "Agent created. Visitors can reach it at `/{slug}`"
 
 ### List
 
 Read `defaultAgent` from `account-manage` to identify the current default. Read all directories under `agents/`. For each, read `config.json` and estimate total token budget. Present as a structured summary, marking the default agent:
 
 **sales** — Sonnet Standard * default
-1 plugin · 11,500 / 200,000 tokens (6%) · active
+11,500 / 200,000 tokens (6%) · active
 
 **support** — Haiku Low cost
-0 plugins · 3,200 / 40,000 tokens (8%) · active
+3,200 / 40,000 tokens (8%) · active
 
 **public** — Haiku Low cost
-1 plugin · 9,800 / 40,000 tokens (25%) · active
+9,800 / 40,000 tokens (25%) · active
 
 ### Clone
 

package/payload/platform/plugins/cloudflare/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare",
-  "description": "Cloudflare Tunnel operations — setup, reset, dashboard guidance. Zero agent-facing MCP tools; every operation is the agent invoking `cloudflared` directly via Bash or quoting a dashboard click-path the operator performs themselves.",
+  "description": "Cloudflare operations — tunnel setup/reset, DNS, Pages hosting, D1 data capture, and dashboard guidance. Zero agent-facing MCP tools; every operation is the agent invoking `cloudflared` or `wrangler` directly via Bash, calling the Cloudflare API with a minted narrow token, or quoting a dashboard click-path the operator performs themselves.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

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

@@ -1,13 +1,13 @@
 ---
 name: cloudflare
-description: Cloudflare Tunnel operations — setup, reset, dashboard guidance. Zero agent-facing MCP tools; every operation is the agent invoking `cloudflared` directly via Bash or quoting a dashboard click-path the operator performs themselves.
+description: Cloudflare operations — tunnel setup/reset, DNS, Pages hosting, D1 data capture, and dashboard guidance. Zero agent-facing MCP tools; every operation is the agent invoking `cloudflared` or `wrangler` directly via Bash, calling the Cloudflare API with a minted narrow token, or quoting a dashboard click-path the operator performs themselves.
 tools: []
 mcp-manifest: skip
 ---
 
 # Cloudflare Tunnel
 
-Each installation has its own Cloudflare account. The operator signs in with OAuth via `cloudflared tunnel login` (issued by the agent through Bash); `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 agent runs, and DNS + HTTPS probes against public surfaces.
+Each installation has its own Cloudflare account. Two auth paths serve two operation classes. **Tunnel** auth is OAuth: the operator signs in via `cloudflared tunnel login` (issued by the agent through Bash); `cloudflared` writes `cert.pem` to the brand-scoped config directory. **API** auth (DNS, zones, Pages, D1, Access, token mint) is the master token: the operator provisions one fully-scoped master token in the dashboard (an advanced, operator-guided step the agent never automates), stored at the account-scoped secrets file; the agent reads it only to mint a narrowly-scoped, short-lived token per operation and exports that ephemeral token for the one call. Account state is brand-isolated and the master token never leaves the secrets file — see `references/api.md`.
 
 ## When to activate
 
@@ -25,20 +25,23 @@ Each installation has its own Cloudflare account. The operator signs in with OAu
 
 ## Operator-facing surface
 
-The plugin registers no agent-facing MCP tools. Every Cloudflare operation is the agent invoking `cloudflared` directly via Bash, following the numbered steps in `references/manual-setup.md`, with the cloudflared stdout/stderr streamed verbatim into the PTY chat. The OAuth URL printed by `cloudflared tunnel login` is linkified by the native PTY; the operator clicks it in their own browser. There is no shell-script wrapper, no orchestrator state machine, no MCP-tool surface.
+The plugin registers no agent-facing MCP tools. Every Cloudflare operation is the agent invoking `cloudflared` or `wrangler` directly via Bash, or calling the Cloudflare API with a minted narrow token, with stdout/stderr streamed verbatim into the PTY chat (secrets redacted). The OAuth URL printed by `cloudflared tunnel login` is linkified by the native PTY; the operator clicks it in their own browser. There is no shell-script wrapper, no orchestrator state machine, no MCP-tool surface.
 
 ### Skills
 
 | Skill | Purpose |
 |---|---|
-| [setup-tunnel/SKILL.md](skills/setup-tunnel/SKILL.md) | Names the outcome contract (external HTTP 200 to the configured hostname), the inputs to collect, the runbook to execute, and the tool-discipline rule that binds the agent. |
+| [cloudflare/SKILL.md](skills/cloudflare/SKILL.md) | The entry point for every Cloudflare operation. Routes each operation class to its reference, names the outcome contracts (tunnel external HTTP 200; hosting deployed URL; D1 round-trip), and states the tool-discipline + secret-redaction rules that bind the agent. |
 
 ### References
 
 | Reference | Topics |
 |---|---|
-| [manual-setup.md](references/manual-setup.md) | Step-by-step runbook — Steps 0–7 with isolated `cloudflared` command blocks. The agent reads the relevant step before issuing each command. |
-| [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. |
+| [manual-setup.md](references/manual-setup.md) | Tunnel runbook — Steps 0–7 with isolated `cloudflared` command blocks. The agent reads the relevant step before issuing each command. |
+| [api.md](references/api.md) | Cloudflare API library — canonical docs URL + curated endpoint map (DNS, zones, tunnels, token create/verify), the advanced master-token creation walkthrough, the account-scoped secrets-file storage convention, and the agent's mint-narrow-token discipline. |
+| [d1-data-capture.md](references/d1-data-capture.md) | Form → Pages Function → D1 store → read/sweep. The Pages-Edit **and** D1-Edit token-scope requirement, `wrangler d1 create`/`execute --remote`, the `swept` column. |
+| [hosting-sites.md](references/hosting-sites.md) | Deploy a static or Next.js site to Cloudflare Pages via `wrangler pages deploy`. |
+| [dashboard-guide.md](references/dashboard-guide.md) | Click-paths for operations the operator prefers to do by hand — sign in, switch accounts, add a site, edit an apex CNAME, verify nameservers, delete a tunnel, manage CNAME records, author an Access policy. |
 | [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.
@@ -55,4 +58,4 @@ The setup-done claim only fires when `curl -I https://<hostname>` issued from ou
 
 ## Discipline
 
-Loaded into IDENTITY.md § Cloudflare operations at install time. The short form: the agent's permitted surfaces are direct `cloudflared` invocations via Bash following the runbook, the three reference files, and `curl -I` reachability checks — everything else (Playwright, WebSearch-for-CF-recipes, Cloudflare API / SDK, ad-hoc `cloudflared` flag invention not in the runbook) is out of bounds. When a step fails, the agent reports the exact `cloudflared` output, cites the recovery step from `references/reset-guide.md`, and stops.
+The agent's permitted surfaces are: direct `cloudflared` and `wrangler` invocations via Bash following the references; Cloudflare API calls authenticated by a freshly-minted narrow token (the master token stays in the secrets file, never on a command line that echoes, never in chat); the reference files; and live verification (`curl -I` for tunnels, the deployed URL for hosting, a `SELECT` for D1). Out of bounds: Playwright or Chrome DevTools driving the dashboard, browser-automating master-token creation, WebSearch-for-CF-recipes, ad-hoc `cloudflared` flag invention not in the runbook, and writing or echoing any token. When a step fails, the agent reports the exact output (secrets redacted), cites the recovery step from `references/reset-guide.md`, and stops.

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.