@rubytech/create-maxy-code 0.1.278 → 0.1.280

package/payload/platform/plugins/aeo/skills/structured-answer/SKILL.md

@@ -5,6 +5,8 @@ description: Use when authoring or auditing a page whose primary purpose is to a
 
 # Structured-answer page template
 
+Invoked from `specialists:content-producer`.
+
 Answer engines (Claude, ChatGPT, Perplexity, Google AI Overviews, Bing Copilot) lift a single short span when they cite a page. That span is almost always the first paragraph after the H1, when it is short and direct. Every other element on the page either supports the lift or gets ignored.
 
 ## The shape

package/payload/platform/plugins/business-assistant/PLUGIN.md

@@ -28,8 +28,12 @@ You are an AI-powered business assistant — like a trusted secretary who knows
 
 Every incoming customer message: identify (new vs existing) → triage (urgent/routine/quick) → gather info → respond or escalate → update memory.
 
+Enquiries also arrive through the business's **published-site contact form**, which lands rows in a Cloudflare **D1** database rather than as messages — a primary inbound channel, not a side channel. When the owner asks about new sign-ups, contacts, or enquiries, read D1 **first** (see `references/site-lead-intake.md`), before memory or sessions.
+
 Track status through the pipeline: enquiry → quoted → booked → completed → invoiced → paid.
 
+When a built document — a quote, contract, proposal, or set of terms — needs a recordable signature without DocuSign, load the `e-sign` skill (`skill-load skillName="e-sign"`).
+
 ## Session & Task Continuity
 
 Every conversation is a session. At the start of each session:
@@ -56,6 +60,7 @@ Load the relevant reference when the task requires it:
 - **Scheduling & briefings** → `references/scheduling.md` — booking protocol, geographic clustering, travel time estimation, morning briefings, holiday mode, GPS integration
 - **Invoices & payment** → `references/invoicing.md` — HTML invoice creation, PDF generation via `browser-navigate` + `browser-pdf-save`, sending, payment chase protocol
 - **Customer records** → `references/crm.md` — contact record management, `contact_lookup`/`contact_update` usage, pipeline tracking, when to create/update records
+- **Site form submissions** → `references/site-lead-intake.md` — the published-site contact form is a primary inbound channel landing in Cloudflare D1; "any new sign-ups/contacts/enquiries?" reads D1 first, then dedupes each unswept row into the graph and routes it to the recorded front-line owner
 - **Document filing** → `references/document-management.md` — dual-scope filing system, naming conventions, folder structure for customer-facing vs internal documents
 - **Task & session management** → `references/task-management.md` — task lifecycle, session naming, cross-session progress tracking
 - **Owner profiling** → `references/profiling.md` — observation triggers, privacy boundaries, when and how to write preferences

package/payload/platform/plugins/business-assistant/references/crm.md

@@ -36,6 +36,12 @@ Create a contact record on the **first meaningful interaction** with a new custo
 - Spam or wrong numbers
 - One-off enquiries that go nowhere (unless the business owner asks you to)
 
+## Inbound Enquiries Also Arrive via the Site Form → D1
+
+Not every new contact comes in by phone or WhatsApp. The business's **published-site contact form** is a primary inbound-enquiry channel, and its submissions land as rows in a Cloudflare **D1** database, not as messages — nothing surfaces them automatically. When the owner asks about new sign-ups, contacts, or enquiries, read D1 first, then turn each new row into a contact record here. See `references/site-lead-intake.md` for the read-first-from-D1, dedupe, create-or-update, sweep-after-write capability.
+
+A new site lead is routed to the install's **recorded front-line owner** — and that ownership is **operator data** (recorded on the graph, or asked of the operator if not yet recorded), never a guessed name and never baked into a reference. Routing a lead to whoever seems plausible is the mistake; route to the recorded owner.
+
 ## When to Update a Record
 
 Update the contact record after every event that changes the customer's status or adds useful information:

package/payload/platform/plugins/business-assistant/references/site-lead-intake.md

@@ -0,0 +1,52 @@
+# Managing site form submissions (the published-site → D1 inbound channel)
+
+The business's published website has a contact / enquiry form, and that form is a **primary inbound-enquiry channel** — equal to phone and WhatsApp, not a side channel. Submissions do not arrive as messages; they land as rows in a **Cloudflare D1** database (the leads DB created in `plugins/cloudflare/references/d1-data-capture.md`). Nothing surfaces them automatically. This reference is the capability: when the owner asks about new enquiries, read D1 first, then turn each new row into a graph contact routed to the right person.
+
+The failure this prevents is concrete: asked "any new sign-ups?", an agent that searches memory or lists public-agent sessions will report "nothing new" while real leads sit unswept in D1. Memory and public-agent sessions are not where site enquiries live. **D1 is.**
+
+---
+
+## "Any new sign-ups / contacts / enquiries?" → read D1 first
+
+When the owner asks whether anything new has come in — sign-ups, contacts, enquiries, leads — the **first action is a D1 read of the leads DB**, before `memory_search`, before `contact_lookup` sweeps, before any public-agent `session-list`. The unswept set is the answer:
+
+```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;"
+```
+
+This composes `plugins/cloudflare/references/d1-data-capture.md` § 6 (read/sweep) and § 0 (minting the Pages-+-D1 token); the credential and token discipline there is binding. Before this `wrangler` call: run the load-credentials pre-flight from `plugins/cloudflare/references/api.md` (source the secrets file, assert `CLOUDFLARE_API_TOKEN` non-empty), mint the narrow Pages-+-D1 token, and confirm `${MINTED_PAGES_D1}` is non-empty — so the incident's `CLOUDFLARE_API_TOKEN not set` failure cannot reach the leads read. The DB name and the site's project are operator/install data, recorded where the site was set up — not guessed.
+
+**Outcome contract for the answer:** the transcript shows a D1 round-trip (`wrangler d1 execute … SELECT … WHERE swept = 0`) as the response to "any new sign-ups?", not a memory search. A `memory_search` or public-agent `session-list` returned as the answer is the defect, not the answer.
+
+---
+
+## Each unswept row → dedupe, create-or-update, then route
+
+For every row in the unswept set, in order:
+
+1. **Dedupe against the graph.** Look the person up by the identifiers the row actually carries. The canonical leads table (`plugins/cloudflare/references/d1-data-capture.md` § 3) holds `name, email, message` — so `contact_lookup` on the row's **email**, and on a **phone** only when the form captured one and the SELECT fetched it. Match the columns the form collects; do not look up a field the row does not carry. A match means update; no match means create.
+2. **Create or update the contact.** No match → `contact_create` with the name and identifiers from the row, `status: enquiry`, `source` naming the site form. Match → `contact_update` to add anything new (email/phone/message context) without clobbering existing fields. Write the enquiry detail into the contact's memory profile as in `references/crm.md`.
+3. **Route to the install's recorded front-line owner** (below).
+4. **Sweep the row only after the graph write is confirmed.** Flip `swept = 1` for the ingested rows once the contact create/update has returned successfully — never before. An unconfirmed write followed by a sweep loses the lead silently.
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 execute <db-name> --remote --command \
+  "UPDATE leads SET swept = 1 WHERE swept = 0;"
+```
+
+A row is the durable record until it is swept; the sweep is the commit, and it follows the graph write, not the other way round.
+
+---
+
+## Front-line-owner routing is operator data, never a baked name
+
+A new site lead is assigned to the install's **recorded front-line owner** — the person enquiries route to for first contact and follow-up. That ownership is **operator data**: it lives on the graph (a recorded property or relationship on the business/account) or, if not yet recorded, it is **asked of the operator**. It is never a name baked into this reference, and never guessed from context. Assigning a lead to whoever seems plausible — a back-office contact, a name seen earlier in the session — is the defect this rule prevents; an owner the operator then has to correct means the routing was guessed, not read.
+
+If the front-line owner is not recorded on the install, ask the operator who new enquiries should go to and record it, then route. (Populating that data is an operator action; this reference states only the routing rule and where the data lives.)
+
+---
+
+## Why D1, not memory
+
+Memory profiles and public-agent sessions describe people the business already talks to. A site enquiry is a **new** signal arriving through the website, captured by the form's Pages Function into D1 with a `swept` cursor precisely so "what's new" is a deterministic query rather than a guess. The whole point of the `swept = 0` set is that it is the authoritative, un-missable list of enquiries not yet brought into the business's records. Querying anything else first is how a real lead gets reported as "nothing new".

package/payload/platform/plugins/business-assistant/skills/e-sign/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: e-sign
+description: "Put a legally-recordable signature on any hosted document — a quote, contract, proposal, or set of terms — without DocuSign. A Cloudflare Pages signing form captures the acceptance to D1; the agent then sweeps the row, renders the signed content to PDF, and emails both parties. Triggers: 'sign this proposal', 'get this contract signed', 'put a signature on this', 'e-signature', 'send for signature', 'accept a proposal online', 'signature on a document'."
+---
+
+# E-signatures — signing any hosted document (form → D1 → PDF + email)
+
+**Invoked by the business-assistant (or admin) directly** when a built document — a quote, contract, proposal, or set of terms — needs a recordable signature.
+
+How to put a legally-recordable signature on **any** document the business hosts — a quote, a contract, a proposal, a set of terms — without DocuSign. The document is deployed to **Cloudflare Pages** with a signing form as its final section; the signer submits; a Pages Function writes the acceptance to **Cloudflare D1**; the agent later sweeps the row, renders the signed content to PDF, and emails both parties a confirmation.
+
+This skill owns **only the signature**: the form, the capture, the PDF, and the dispatch. The document's body — what is actually being signed — is whatever flow built it (a quotation plugin, a hand-written contract, anything). This begins at *"a built document needs a signature."*
+
+It composes two patterns you must read alongside it:
+
+- **`cloudflare/references/d1-data-capture.md`** — the form → Pages Function → D1 → sweep mechanics, and the token-scope breakage (§ 0). Everything about minting the Pages-+-D1 token, `wrangler.toml`, and `wrangler d1 execute --remote` lives there; this skill does not repeat it.
+- **`business-assistant/references/invoicing.md`** — PDF generation via `browser-navigate` + `browser-pdf-save` (its step 4). The signed-content PDF uses that exact pattern.
+
+Auth for every `wrangler`/API call is a minted narrow token per `cloudflare/references/api.md`. Deploy mechanics are `cloudflare/references/hosting-sites.md`.
+
+---
+
+## 0. Pre-flight — block on either prerequisite
+
+Do **not** deploy until both pass. Each failure has one exact remediation; stop and give it.
+
+1. **Email must be configured.** Call `email-status`. If it does not report a configured inbox, stop:
+   > "Email isn't set up yet. Run `email-setup` first, then ask me again."
+
+   Dispatch (§ 6) sends through `email-send`; without a configured inbox the acceptance is captured but never delivered.
+
+2. **The Cloudflare master token must exist.** With `SECRETS_DIR` per `api.md` (`~/<brand>-code/data/accounts/<accountId>/secrets`):
+
+   ```bash
+   ( test -s "${SECRETS_DIR}/cloudflare.env" && grep -q '^CLOUDFLARE_API_TOKEN=' "${SECRETS_DIR}/cloudflare.env" ) \
+     && echo "ok" || echo "missing"
+   ```
+
+   On `missing`, stop:
+   > "There's no Cloudflare master token. Provision it once per `cloudflare/references/api.md` § Provisioning the master token, then ask me again."
+
+---
+
+## 1. The signable document
+
+A self-contained HTML document — all styles inline, no external resources — deployed to **Cloudflare Pages**, not the local platform server. Pages is required because only a Pages Function can receive the acceptance POST; a page served off the platform device has nowhere to write the row.
+
+- **Slug carries a random hex suffix** so the URL is unguessable: `quote-lakeside-7f3a9c.html` (or a project whose name carries the suffix). Mint the suffix once: `openssl rand -hex 3`.
+- **Page carries `<meta name="robots" content="noindex,nofollow">`** in `<head>` — a signable document is private, never indexed.
+- **Assign a `DOC_REF`** — a short stable identifier for this one document, e.g. `QUOTE-LAKESIDE`. It keys the acceptance row and seeds the token. It is per-document and **never reused for changed terms** (see immutability, below).
+
+**Immutability — signed content must not change.** Once an acceptance is recorded against a `DOC_REF`, the deployed document **must not be edited**. The PDF that is dispatched is rendered from the live page, so any later edit silently changes what the records claim was signed. Re-issuing changed terms is a **new** document with a **new** `DOC_REF` and a fresh deploy — never an edit to the signed one. (Failure-mode detail: § 8.3.)
+
+---
+
+## 2. The signing form (final section of the document)
+
+The form is the document's last section. It carries three fixed controls plus whatever the operator's document needs:
+
+- **`name`** — required.
+- **`email`** — required (this is where the signer's confirmation is sent).
+- **An agreement checkbox** — required; the signer cannot submit without ticking it.
+- **Operator-defined fields** — any extra inputs the specific document needs (company, project address, a quoted figure to confirm). These are **discovered from the document**, not fixed here; the client JS below sweeps every named field beyond the fixed three into `captured_json`.
+
+On submit, client JS mints an **acceptance token** and POSTs JSON to the Pages Function. On `{"ok":true}` the form is replaced by a confirmation panel showing the token; on any failure the signer gets a pre-filled `mailto:` fallback so the acceptance is never lost.
+
+**Acceptance token** — `<DOC_REF>-<5-char base36 timestamp>-<6-char djb2 hash>`. The hash is djb2 over `name + email + DOC_REF`: it binds the signer's identity to this document, so a UNIQUE collision on the token means *the same signer re-submitting the same document* — a genuine duplicate, not a clash between two signers.
+
+The confirmation and fallback panels are built with `textContent` and DOM nodes, never `innerHTML` — the signer's own name and email flow back into the page, and `innerHTML` would make that an injection surface.
+
+```html
+<section id="sign">
+  <h2>Accept &amp; sign</h2>
+  <form id="esign">
+    <input name="name" required placeholder="Full name">
+    <input name="email" type="email" required placeholder="Email">
+    <!-- operator-defined fields go here, e.g.:
+    <input name="company" placeholder="Company">
+    <input name="project_address" placeholder="Project address"> -->
+    <label><input type="checkbox" name="agree" required>
+      I have read and agree to the terms above.</label>
+    <button type="submit">Sign</button>
+  </form>
+  <div id="confirm" hidden></div>
+</section>
+
+<script>
+const DOC_REF      = "QUOTE-LAKESIDE";            // unique per document; never reused for changed terms
+const ACCEPT_URL   = "/api/accept";
+const OWNER_MAILTO = "OWNER@EXAMPLE.COM";         // fallback recipient = the business's configured address
+
+// 6-char base36 djb2 — deterministic over signer identity + document.
+function djb2(s){let h=5381;for(let i=0;i<s.length;i++)h=((h<<5)+h+s.charCodeAt(i))>>>0;return h.toString(36).slice(-6).padStart(6,"0");}
+
+document.getElementById("esign").addEventListener("submit", async (e) => {
+  e.preventDefault();
+  const f = e.target;
+  const name  = f.name.value.trim();
+  const email = f.email.value.trim();
+  const ts    = Date.now().toString(36).slice(-5);
+  const token = `${DOC_REF}-${ts}-${djb2(name + email + DOC_REF)}`;
+
+  // Everything beyond the fixed three fields is operator-defined; carry it verbatim.
+  const extra = {};
+  for (const el of f.elements) {
+    if (!el.name || ["name", "email", "agree"].includes(el.name)) continue;
+    extra[el.name] = el.type === "checkbox" ? el.checked : el.value;
+  }
+  const payload = { name, email, token, doc_ref: DOC_REF, ...extra };
+
+  const c = document.getElementById("confirm");
+  c.textContent = "";
+  try {
+    const r = await fetch(ACCEPT_URL, {
+      method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload),
+    });
+    const j = await r.json();
+    if (!j.ok) throw new Error(j.error || "rejected");
+    f.hidden = true; c.hidden = false;
+    const p = document.createElement("p");
+    const ref = document.createElement("strong");
+    ref.textContent = j.token;
+    p.append("Signed. Your acceptance reference is ", ref, ". A copy has been sent for processing.");
+    c.append(p);
+  } catch (err) {
+    // Function unreachable or insert failed — never drop the acceptance; offer the pre-filled mailto.
+    const subj = encodeURIComponent(`Acceptance: ${DOC_REF} (${token})`);
+    const body = encodeURIComponent(`I accept ${DOC_REF}.\nName: ${name}\nEmail: ${email}\nReference: ${token}`);
+    c.hidden = false;
+    const p = document.createElement("p");
+    const a = document.createElement("a");
+    a.href = `mailto:${OWNER_MAILTO}?subject=${subj}&body=${body}`;
+    a.textContent = "Send it by email instead";
+    p.append("We couldn't record your signature automatically. ", a, ".");
+    c.append(p);
+  }
+});
+</script>
+```
+
+`OWNER_MAILTO` is the **business's own configured address** — read it from configured business identity, never invent one. It is the fallback path only; the primary path is the Function.
+
+**PDF tip:** add `@media print { #sign { display: none } }` to the document's styles so the dispatched PDF carries the agreed content, not an empty form.
+
+---
+
+## 3. D1 table — one per brand, shared across that brand's documents
+
+Follow `d1-data-capture.md` for creating the database, the `wrangler.toml` binding, and the both-Pages-Edit-**and**-D1-Edit token. The schema here is generic — it imposes no business fields; operator-defined fields live in `captured_json`:
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_PAGES_D1}" wrangler d1 execute <db-name> --remote --command \
+  "CREATE TABLE IF NOT EXISTS acceptances (
+     id            INTEGER PRIMARY KEY AUTOINCREMENT,
+     doc_ref       TEXT    NOT NULL,
+     name          TEXT    NOT NULL,
+     email         TEXT    NOT NULL,
+     token         TEXT    NOT NULL UNIQUE,
+     captured_json TEXT,
+     accepted_at   TEXT    NOT NULL DEFAULT (datetime('now')),
+     swept         INTEGER NOT NULL DEFAULT 0
+   );"
+```
+
+One `acceptances` table serves every document the brand signs; rows are separated by `doc_ref`. `token UNIQUE` is what makes a re-submit idempotent. `swept` is the dispatch cursor (§ 6).
+
+---
+
+## 4. The Pages Function — `functions/api/accept.ts`
+
+Served at `POST /api/accept` by file path. It validates the four required fields, inserts, and handles the UNIQUE collision gracefully — an already-recorded token still returns `ok:true` so the signer never sees an error for signing twice. No secret lives in this file; the `DB` binding is injected at runtime.
+
+```ts
+interface Env { DB: D1Database }
+
+const cors = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+};
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json", ...cors } });
+
+export const onRequestOptions: PagesFunction = async () => new Response(null, { status: 204, headers: cors });
+
+export const onRequestPost: PagesFunction<Env> = async ({ request, env }) => {
+  let p: any;
+  try { p = await request.json(); } catch { return json({ ok: false, error: "bad json" }, 400); }
+
+  const name   = String(p.name ?? "").trim();
+  const email  = String(p.email ?? "").trim();
+  const token  = String(p.token ?? "").trim();
+  const docRef = String(p.doc_ref ?? "").trim();
+  if (!name || !email || !token || !docRef)
+    return json({ ok: false, error: "name, email, token, doc_ref required" }, 400);
+
+  // Everything beyond the four required fields is operator-defined; stash verbatim.
+  const { name: _n, email: _e, token: _t, doc_ref: _d, ...extra } = p;
+  const capturedJson = Object.keys(extra).length ? JSON.stringify(extra) : null;
+
+  try {
+    await env.DB
+      .prepare("INSERT INTO acceptances (doc_ref, name, email, token, captured_json) VALUES (?, ?, ?, ?, ?)")
+      .bind(docRef, name, email, token, capturedJson)
+      .run();
+  } catch (err) {
+    // UNIQUE(token) collision = same signer, same document, already recorded. Idempotent: still ok.
+    // D1 surfaces the constraint as the stable text "UNIQUE constraint failed"; match the phrase,
+    // not the bare word, so an unrelated error never gets swallowed as a duplicate.
+    if (String(err).includes("UNIQUE constraint failed")) return json({ ok: true, token, duplicate: true });
+    return json({ ok: false, error: "insert failed" }, 500);
+  }
+  return json({ ok: true, token });
+};
+```
+
+**The single most common breakage — token scope.** A Pages-only token deploys the document and renders the form, but **every POST silently 500s at the insert** because the Function can't write D1. The minted token must carry **both Pages Edit and D1 Edit** (`d1-data-capture.md` § 0). When acceptances stop arriving, this is the first thing to check.
+
+---
+
+## 5. Deploy
+
+Deploy the document + Function via `hosting-sites.md`, with the both-Pages-Edit-and-D1-Edit token. The `[[d1_databases]]` binding in `wrangler.toml` is what wires the deployed Function to the `acceptances` database.
+
+---
+
+## 6. Sweep + dispatch
+
+When the operator asks for new acceptances (there is no standing cron — see § 8.2 for the reconciliation a scheduled task would run). Two tokens are minted here, both per `api.md` § Minting a narrow token, resolving permission-group ids exactly as `d1-data-capture.md` § 0 does: `${MINTED_D1_READ}` carries only **D1 Read** (for the SELECTs), `${MINTED_D1_EDIT}` carries **D1 Edit** (for the per-row mark-swept). Minting read-scoped where only a read is needed keeps the edit token off every command that does not write.
+
+1. **Read the unswept rows** with `${MINTED_D1_READ}`:
+
+   ```bash
+   CLOUDFLARE_API_TOKEN="${MINTED_D1_READ}" wrangler d1 execute <db-name> --remote --json --command \
+     "SELECT id, doc_ref, name, email, token, captured_json, accepted_at
+        FROM acceptances WHERE swept = 0 ORDER BY id;"
+   ```
+
+2. **For each unswept row, in order — dispatch, then mark that one row swept:**
+   - **Render the signed content to PDF.** `browser-navigate` to the deployed document URL, then `browser-pdf-save` to an absolute path under the account directory — the `invoicing.md` step-4 pattern. The PDF is of the live page, which (immutability, § 1) is exactly what was signed.
+   - **Send twice via `email-send`**, each carrying `doc_ref`, `name`, `token`, `accepted_at`, and the PDF as an attachment:
+     - once to the **business owner's configured address** (read from configured business identity — never hard-code a recipient in this workflow);
+     - once to the **signer's captured `email`**.
+   - **Mark this row — and only this row — swept, once both sends return a verified result**, keyed by its `id`:
+
+     ```bash
+     CLOUDFLARE_API_TOKEN="${MINTED_D1_EDIT}" wrangler d1 execute <db-name> --remote --command \
+       "UPDATE acceptances SET swept = 1 WHERE id = <row-id>;"
+     ```
+
+   Never flip `swept` on assumption. If either `email-send` for a row fails, **skip its UPDATE** and move to the next row; that row stays `swept = 0` so the next sweep (or the reconciliation in § 8.2) re-surfaces it. A bulk `WHERE swept = 0` here is wrong — it would mark rows whose dispatch failed earlier in the same batch; the per-row `WHERE id = <row-id>` is what makes the `swept` flag track verified dispatch exactly.
+
+---
+
+## 7. Outcome contract
+
+The acceptance flow is proven end-to-end on the **live** Pages deployment — the D1 row, not the POST status, is the contract:
+
+```bash
+# 1. POST a test acceptance to the live Function.
+curl -sS -X POST -H "Content-Type: application/json" \
+  -d '{"name":"verify","email":"test@example.com","token":"QUOTE-LAKESIDE-abcde-zzzzzz","doc_ref":"QUOTE-LAKESIDE"}' \
+  "https://<project>.pages.dev/api/accept"
+# expect: {"ok":true,"token":"QUOTE-LAKESIDE-abcde-zzzzzz"}
+
+# 2. The row exists in the unswept set. (A 200 with no row here is a FAILURE — see § 8.1.)
+CLOUDFLARE_API_TOKEN="${MINTED_D1_READ}" wrangler d1 execute <db-name> --remote --command \
+  "SELECT token FROM acceptances WHERE swept = 0;"
+
+# 3. POST the SAME token again → still {"ok":true}; the SELECT shows exactly one row (UNIQUE handled).
+
+# 4. Run the sweep (§ 6): both the owner address and test@example.com hold the confirmation email,
+#    each with the signed-content PDF attached; re-running the SELECT WHERE swept = 0 no longer returns the row.
+```
+
+Surface every step as verb + target ("inserting a test acceptance", "sweeping unswept rows from `<db-name>`"). **Token values are never printed** to chat or stdout outside the signer-facing confirmation panel.
+
+---
+
+## 8. Failure modes and the signal for each
+
+1. **POST silently 500s at the insert (token missing D1 Edit).** Signal fires *without reproducing end to end*: the test POST returns non-`ok`, and the confirming `SELECT WHERE swept = 0` shows no new row. Fix: re-mint the token confirming **both** Pages Edit and D1 Edit (`d1-data-capture.md` § 0). This is the first thing to check when acceptances stop arriving.
+
+2. **Acceptance recorded but never dispatched (no-event failure).** The sweep never ran, or `email-send` failed after the row existed — this emits no log, because no action was taken. Detection is a **standing reconciliation, not a hung log line**:
+
+   ```bash
+   CLOUDFLARE_API_TOKEN="${MINTED_D1_READ}" wrangler d1 execute <db-name> --remote --command \
+     "SELECT count(*), min(accepted_at) FROM acceptances WHERE swept = 0;"
+   ```
+
+   Any row whose `accepted_at` is older than the sweep cadence is an undispatched acceptance. Run this on a schedule (or each time acceptances are reviewed) and treat a non-empty aged result as the failure signal. Because § 6 flips `swept` only after both sends verify, a failed dispatch leaves the row here for the next pass.
+
+3. **Document modified after an acceptance (signed-content drift).** Signal: the dispatched PDF no longer matches what was signed. Detection without reproduction — record the deployed document's content hash at first acceptance; a later mismatch is the failure. The rule (§ 1) is absolute: changed terms require a **new** `doc_ref` and a fresh deploy, never an edit to a signed document.
+
+4. **Duplicate-acceptance row.** Signal: a `token` appears more than once — the UNIQUE handling regressed.
+
+   ```bash
+   CLOUDFLARE_API_TOKEN="${MINTED_D1_READ}" wrangler d1 execute <db-name> --remote --command \
+     "SELECT token, count(*) c FROM acceptances GROUP BY token HAVING c > 1;"
+   ```
+
+   Healthy signature: re-POSTing a token leaves its count at one.
+
+**Ground-truth lifeline** for one document's whole acceptance lifecycle:
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_D1_READ}" wrangler d1 execute <db-name> --remote --json --command \
+  "SELECT id, doc_ref, token, accepted_at, swept FROM acceptances WHERE doc_ref = 'QUOTE-LAKESIDE' ORDER BY id;"
+```

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

@@ -41,6 +41,7 @@ The plugin registers no agent-facing MCP tools. Every Cloudflare operation is th
 | [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`. |
+| [web-analytics.md](references/web-analytics.md) | Why a registered site reports 0 visitors — the RUM API is blocked (no permission group), registered ≠ collecting, edge auto-injection is impossible for a Pages-only custom domain, and the beacon must be injected into the site HTML, rebuilt, and redeployed. Outcome: beacon present in live HTML. |
 | [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. |
 

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

@@ -57,6 +57,18 @@ Load the master for a mint call:
 set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a
 ```
 
+### Load-credentials pre-flight (assert before any `wrangler` / `curl`)
+
+Sourcing the file is not proof the token loaded — a missing file, a typo in the path, or an empty value all leave `CLOUDFLARE_API_TOKEN` unset, and the **next** `wrangler` / `curl` then fails with `CLOUDFLARE_API_TOKEN not set` *after* you have already issued the command. Make the load a **hard precondition**: source, then assert the token is non-empty, and stop if it is not. This block precedes every `wrangler d1`, `wrangler pages`, and Cloudflare-API `curl` in this reference and the ones that compose it:
+
+```bash
+set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a
+: "${CLOUDFLARE_API_TOKEN:?credentials not loaded — source the secrets file before any wrangler/curl}"
+: "${CLOUDFLARE_ACCOUNT_ID:?account id not loaded — source the secrets file before any wrangler/curl}"
+```
+
+The `:?` form aborts the shell with the given message when the variable is empty or unset, so a credential-unloaded call can never reach the API. The token value is never printed — only the abort message on failure.
+
 ---
 
 ## Provisioning the master token (ADVANCED — operator-guided, never automated)
@@ -75,12 +87,14 @@ This is the one manual, operator-driven step. The agent relays the click-path; i
 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):
+Verify the master works (token value never printed — only the verification result). The master provisioned above is an **account-scoped** token (`cfat_…`, scoped to one account under **Account Resources**), so it verifies at the **account** endpoint, not the user endpoint. Verifying a `cfat_…` token at `/user/tokens/verify` returns `Invalid API Token` even when the token is valid:
 
 ```bash
 set -a; . "${SECRETS_DIR}/cloudflare.env"; set +a
+: "${CLOUDFLARE_API_TOKEN:?credentials not loaded — source the secrets file first}"
+: "${CLOUDFLARE_ACCOUNT_ID:?account id not loaded — source the secrets file first}"
 curl -sS -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \
-  "https://api.cloudflare.com/client/v4/user/tokens/verify" | jq '.result.status'
+  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/tokens/verify" | jq '.result.status'
 # expect: "active"
 ```
 
@@ -128,7 +142,7 @@ Look up `<pages-edit-permission-group-id>` (and the ids for DNS Edit, D1 Edit, e
 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.
+- `GET  /accounts/${ACC}/tokens/verify` — confirm an **account-scoped** (`cfat_…`) token is active. This is the endpoint for the master and every minted narrow token here, all of which are account-scoped. **`/user/tokens/verify` is user-scoped only** and returns `Invalid API Token` for a `cfat_…` token even when it is valid — do not use it to verify an account token.
 - `POST /accounts/${ACC}/tokens` — mint a narrow token (see above).
 - `GET  /accounts/${ACC}/tokens/permission_groups` — resolve permission-group ids for scoping.
 

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

@@ -4,6 +4,8 @@ The dashboard is the only surface for operations the CLI cannot perform: signing
 
 Anchor on the dashboard's text labels, not pixel positions. Cloudflare reshuffles its UI every few months; when a label has moved or been renamed, the operator will find the new location faster than any stale screenshot would help.
 
+**Never fabricate a navigation path.** Only relay a click-path that appears verbatim in this file or another verified runbook. When the operator needs a dashboard step that is **not** in a verified path here — or when a relayed path turns out to be wrong ("No such menu") — do **not** invent menu names or guess where Cloudflare put it. Ask the operator what they see on their screen, or ask them to paste the snippet / value you need, and route from there. A guessed nav path that sends the operator hunting for a menu that does not exist is the failure this rule prevents; an honest "I don't have a verified path for that — what do you see under X?" is correct.
+
 ---
 
 ## Sign in and confirm which account
@@ -168,6 +170,14 @@ No server restart is needed. Verify with `curl -s https://<domain>/ | head` —
 
 ---
 
+## Web Analytics — registration is here, but collection is a beacon in the HTML
+
+Cloudflare Web Analytics is configured in the dashboard, but registering a site there does **not** start collection — the beacon must be present in the served HTML. The full diagnosis and fix (why the RUM API is blocked, why registered ≠ collecting, why auto-injection is impossible for a Pages-only custom domain, and the inject-rebuild-redeploy path) lives in `references/web-analytics.md`. Read it before answering any "0 visitors / no analytics" question.
+
+Because Cloudflare moves this area and the exact menu path varies by account, do not guess the click-path to the Web Analytics page. Ask the operator what they see, or have them paste the site's beacon snippet, then follow `references/web-analytics.md`.
+
+---
+
 ## Where tunnels live in the dashboard (as of 2026-04)
 
 Tunnels are under **Zero Trust** → **Networks** → **Tunnels**. This is not in the top-level sidebar — it is under the Zero Trust sub-dashboard, which itself appears in the main sidebar. Cloudflare has moved this location in the past. If **Networks** → **Tunnels** is not visible under Zero Trust, the label has likely been renamed; look for "Tunnels" under Networks or Access.

package/payload/platform/plugins/cloudflare/references/web-analytics.md

@@ -0,0 +1,64 @@
+# Cloudflare Web Analytics — beacon-injected, not API-configured
+
+Cloudflare Web Analytics is the privacy-first RUM (real-user-monitoring) product that counts visits, page views, and referrers for a site without cookies. On this install it is configured **in the dashboard** and collects data **only when the JS beacon is present in the served HTML**. This reference exists because a 0-visitor reading is almost always a missing beacon, not a registration problem — and because the API path most agents reach for first is structurally blocked here.
+
+Pair this with `hosting-sites.md` (how the site is built and deployed) and `dashboard-guide.md` (the click-paths the operator runs when a dashboard step is genuinely required).
+
+---
+
+## The RUM site API is blocked without a RUM permission group
+
+The `/accounts/{account_id}/rum/site_info` family of endpoints (list/create/edit RUM sites) requires an **Account · Web Analytics** permission group on the token. That permission group is **not among the master token's rows** provisioned in `api.md` § Provisioning (which owns the authoritative list). A minted token therefore cannot carry it, and every RUM API call returns auth error **10000 ("Authentication error")** regardless of which token is tried.
+
+Do not chase 10000 by re-minting. Web Analytics site registration is a **dashboard-only** configuration step on this install: the operator creates/inspects the site under the dashboard, and the agent never drives it via the API. Treat the RUM API as unavailable, not as a token bug to fix.
+
+---
+
+## Registered ≠ collecting — 0 visitors means the beacon is missing
+
+A site can show as **registered/enabled** in Web Analytics and still report **0 visitors**. Registration only allocates a site tag in the dashboard; it does not place anything on the page. Collection begins only when the beacon `<script>` is actually loaded by the browser, which requires the snippet to be present in the **served HTML**.
+
+So when the operator asks "why are there no analytics / 0 visitors" on a site that is registered:
+
+- The diagnosis is **not** "registration failed" and **not** "the dashboard is wrong".
+- The diagnosis is "the beacon JS is not in the HTML". Confirm it directly against the live site:
+
+```bash
+curl -s https://<host>/ | grep cloudflareinsights || echo "BEACON ABSENT"
+```
+
+If `cloudflareinsights` does not appear, the beacon is missing and no amount of dashboard reconfiguration will start collection.
+
+---
+
+## Auto-injection needs a proxied DNS zone — Pages-only custom domains do not have one
+
+Cloudflare can **auto-inject** the beacon at the edge, but only for hostnames served through a **Cloudflare-proxied DNS zone** (orange-cloud), where Cloudflare controls the HTML response on the way out. A **Pages-only custom domain** — e.g. a `*.pages.dev` project mapped to a custom domain that is **not** a CF-managed zone (such as `realagent.network`, which is Pages-only with no zone) — has no proxied zone in the path, so edge auto-injection is **structurally impossible**. There is no flag that turns it on; the prerequisite (a zone) does not exist.
+
+Do not claim auto-injection "would work if the domain were a zone" as a fix — for a Pages-only custom domain the domain is not a zone, so the only path is manual injection into the site's own HTML.
+
+---
+
+## The working path: inject the beacon into the site HTML, rebuild, redeploy
+
+For a Pages-only custom domain the beacon must be placed in the source HTML the site renders, then built and deployed:
+
+1. Get the site's beacon snippet from the dashboard (the `<script defer src="https://static.cloudflareinsights.com/beacon.min.js" data-cf-beacon='{"token":"<site-tag>"}'></script>` block, with the site's own token).
+2. Add it to the rendered HTML — for a Next.js app, the document `<head>` in `app/layout.tsx` (or the framework's equivalent root layout) so every route carries it.
+3. Rebuild the site and `wrangler pages deploy` per `hosting-sites.md`.
+4. Confirm the beacon is live (outcome contract below).
+
+This is exactly the fix applied to `realagent.network` in the session that sourced this reference: the snippet was added to `app/layout.tsx`, rebuilt, redeployed, and confirmed in the served HTML.
+
+---
+
+## Outcome contract
+
+Web Analytics is collecting when the beacon appears in the **live served HTML**, not when the dashboard says "enabled":
+
+```bash
+curl -s https://<host>/ | grep cloudflareinsights
+# a match (the beacon.min.js script line) is the proof
+```
+
+A registered site in the dashboard is **not** the contract; a present beacon in the response is. Visitor counts then appear in the dashboard after real traffic — first data is delayed, so the grep, not an immediate visitor number, is what closes the task.

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

@@ -5,6 +5,8 @@ description: Cloudflare operations for the install — tunnel setup/diagnosis/re
 
 # Cloudflare operations
 
+Invoked from `specialists:personal-assistant`.
+
 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 |
@@ -15,6 +17,7 @@ This is the entry point for every Cloudflare task on the install. Pick the opera
 | 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` |
+| Diagnose / enable Web Analytics on a site (0 visitors, no data) | `references/web-analytics.md` | beacon present in live HTML (`curl -s https://<host>/ \| grep cloudflareinsights`) |
 
 ## Two auth paths, by operation class
 

package/payload/platform/plugins/deep-research/skills/academic-verify/SKILL.md

@@ -5,6 +5,8 @@ description: "Traces an academic or scientific claim through the publication cha
 
 # Academic verify
 
+Invoked from `specialists:research-assistant`.
+
 This skill is for claims that arrive as "studies show", "research suggests", or a named paper title. It traces the claim to the actual paper, the actual journal, and the actual conclusion of the source. It never says "verified" without a primary source URL.
 
 ## When to run

package/payload/platform/plugins/deep-research/skills/book-mirror/SKILL.md

@@ -5,6 +5,8 @@ description: "Reads a book the owner provides (PDF, ePub, web link, or text), wa
 
 # Book mirror
 
+Invoked from `specialists:research-assistant`.
+
 This skill turns a book into a usable document by walking the chapters one at a time and asking, for each: "what does this say, and how does it apply to this specific owner". The output is a personalised pack the owner can read once and act on. It is grounded in the graph; the right-hand column is always specific to what the graph already knows about the owner.
 
 ## When to run

package/payload/platform/plugins/deep-research/skills/data-research/SKILL.md

@@ -5,6 +5,8 @@ description: "Recipe-driven structured-data extraction. Takes a named recipe and
 
 # Data research
 
+Invoked from `specialists:research-assistant`.
+
 This skill turns unstructured-looking sources (emails, reports, forms, web pages) into structured graph entities. The transformation is always recipe-driven: a named YAML recipe declares what fields to extract, what validations to apply, and what graph nodes to write. The skill runs a named recipe; it never invents a schema on the fly.
 
 **Default parent.** Every recipe declares its hierarchy parent via `graph_target.parent` — either `Project` (the run-time recipe argument names which Project elementId to attach to) or `LocalBusiness` (the account root, for cross-project recipes like investor-updates). The skill refuses to run a recipe whose `parent` field is missing or whose named Project does not exist. Per-row writes attach to that parent via the canonical containment edge; the recipe's `relationships:` block describes cross-hierarchy edges (e.g. `ROUND_FOR → Organization`) which are written separately and do not substitute for the parent.

package/payload/platform/plugins/deep-research/skills/deep-research/SKILL.md

@@ -20,6 +20,8 @@ config:
 
 # Deep Research Skill
 
+Invoked from `specialists:research-assistant`.
+
 You are a research agent. Answer questions using live web sources, synthesise findings across multiple sources, and present results with full attribution. You do not guess. You search, read, extract, and cite.
 
 ## Workflow

package/payload/platform/plugins/deep-research/skills/strategic-reading/SKILL.md

@@ -5,6 +5,8 @@ description: "Reads a source (article, book, report, document) through a specifi
 
 # Strategic reading
 
+Invoked from `specialists:research-assistant`.
+
 This skill reads a document with a specific question in mind. The owner names the lens (a project, a problem, a goal). The skill summarises what the source actually says, then translates each section into how it applies to the named lens, and closes with a playbook of three to seven concrete steps. Both halves are grounded: the left half in the source text, the right half in the graph.
 
 ## When to run