@rubytech/create-maxy-code 0.1.244 → 0.1.247

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/admin-identity-gate.md

@@ -0,0 +1,81 @@
+# Native-CC admin PIN identity gate
+
+Every native-CC admin session — the operator chatting through claude.ai/code (web,
+desktop, mobile) over the per-account `claude rc` daemon — must bind a
+PIN-authenticated `userId` before any tool runs. This closes the gap where the
+daemon stamped one boot-time `USER_ID` (from `users.json`) onto every session,
+which is correct for at most one human on a multi-admin install. (Task 619.)
+
+The legacy cookie/PIN browser login (`POST /api/admin/session`) is a separate
+surface documented in [`admin-session.md`](admin-session.md); this gate covers the
+native path, which that login never touched.
+
+## How it works
+
+Three pieces, plus a standing audit. No cross-process `session_id` plumbing: the
+hook keys state by the `session_id` it reads from stdin; validation and profile
+resolution live behind one loopback endpoint.
+
+1. **Shared validator** — `ui/app/lib/admin-identity/pin-validator.ts`. The single
+   PIN primitive (`validatePin` → `match` / `miss` / `unavailable` / `corrupt`),
+   shared by the legacy browser login and the gate so the two cannot drift.
+
+2. **Loopback validate endpoint** — `POST /api/admin/identity/validate`
+   (`ui/server/routes/admin/identity.ts`). Loopback-only (rejects any request
+   carrying `x-forwarded-for`, which only edge-proxied browser requests have).
+   Body `{ pin, sessionId? }`. On a match it resolves the operator's `userName`
+   and `aboutOwner` via the same helpers the browser path uses
+   (`resolveUserIdentity`, `resolveOwnerProfileBlock`) — `loadUserProfile` is never
+   duplicated. On a miss with a `sessionId` it fires a best-effort manager
+   `POST /<sessionId>/stop` (only the UI process reliably holds the manager port).
+
+3. **PreToolUse gate hook** — `plugins/admin/hooks/pin-identity-gate.sh`, wired in
+   `setup-account.sh` as the first universal PreToolUse entry. Runs only for native
+   operator sessions (`MAXY_SESSION_ROLE=admin` and empty `MAXY_SPECIALIST` — the
+   latter excludes pty-spawned specialist/recorder sessions). Per tool call: if an
+   auth-state file exists for the `session_id`, allow; if the tool is
+   `admin-identity-authenticate`, post the PIN to the validate endpoint and on a
+   match write the state file and allow (on a miss/unavailable, deny + terminate);
+   any other tool while unauthenticated is denied with an instruction to
+   authenticate first. Enforcement is in the hook, not the agent's choice — a model
+   that skips the prompt reaches no other tool.
+
+The agent-callable surface is the eager-loaded `admin-identity-authenticate` MCP
+tool (admin plugin); the gate validates and binds before allowing it, and the tool
+returns the authenticated operator's profile to the agent.
+
+Auth state: `<accountDir>/state/admin-identity/<session_id>.json` (`{userId, ts}`).
+One file per authenticated conversation; bound for the session lifetime, not
+re-prompted per message. Task-tool specialist subagents share the operator's
+`session_id`, so they pass once the operator is authenticated.
+
+## Cases
+
+- **Zero admins / absent / empty `users.json`** → `pin-unavailable`, the gate
+  refuses; never a bound empty `userId`. A real install always has `users.json`
+  (the installer/seed writes it), so this is a misconfiguration guard.
+- **One admin** → still prompts; the single matching PIN binds that `userId`.
+- **Many admins** → each PIN binds its own `userId`. The account is fixed (the
+  install's own scope); there is no multi-account picker on this path.
+- **Mismatch** → the session is terminated on the first miss (no retry budget).
+
+## Observability
+
+One structured `[admin-identity]` line per step, correlated by `sessionId`:
+
+```
+op=loopback-spawn-received → op=pin-prompted → (op=pin-bound source=pin |
+op=pin-miss → op=session-terminated) ; the MCP tool emits op=about-owner-loaded.
+```
+
+**Standing audit** (`services/claude-session-manager/src/admin-identity-audit.ts`,
+every 60s) reconciles, independently of the hook, live native-operator sessions
+(watcher rows with `role === null` — daemon-spawned, no sidecar) that reached real
+tool use against the auth-state files. Any such session with no state file emits
+`[admin-identity] op=audit-orphan sessionId=…
+reason=loopback-session-without-authenticated-userId`. This is the no-event
+detector: a silent gate bypass leaves no per-session log line, but the audit still
+surfaces it.
+
+Diagnostic path: `journalctl --user -u <brand>-admin | grep -E '\[admin-identity\]'`,
+then filter by `sessionId` for one session's full lifeline.

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/memory/skills/conversation-archive-enrich/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: conversation-archive-enrich
+description: "Walk an existing ConversationArchive's chunks and derive high-confidence claims and insights into the graph, one operator-gated proposal per row. Use when asked to enrich, derive insights from, or mine an existing conversation archive."
 ---
 
 # Conversation Archive — chunk-anchored insight derivation