@rubytech/create-sitedesk-code 0.1.340

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

@@ -0,0 +1,680 @@
+---
+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 renders the document to PDF once at deploy, then stamps a per-signer copy carrying an embedded Electronic Acceptance Certificate and emails both parties. One acceptance per document, then the signing page closes. 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, stamps a per-signer copy of the deploy-time base PDF with an embedded acceptance certificate, 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."*
+
+**Legal basis (state it, do not just assert it).** This produces a **simple electronic signature**: the signer's *intention to authenticate* the document, captured as a deliberate, consented act (the ticked intent-and-consent box of § 2 plus the recorded identity and timestamp). In the UK such a signature is admissible under the **Electronic Communications Act 2000 s.7** and is the simple-signature tier recognised under **UK eIDAS**; its legal weight rests on the *evidentiary record* — who signed, that they intended to sign electronically, when, and what they signed. That record is exactly what the embedded Electronic Acceptance Certificate (§ 6) and the signer's own copy carry, which is why "legally-recordable" is substantiated here rather than claimed. The basis above is stated for the **UK**; each account should confirm its own governing law, and a higher-assurance tier (advanced/qualified signatures, identity verification, server-side attribution) is a separate capability, not this skill.
+
+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. Note its rule that the D1 **query** endpoint rejects a D1-Read token — every `wrangler d1 execute` here uses a **D1-Edit** token, reads included.
+- **`business-assistant/references/invoicing.md`** — PDF generation via `browser-navigate` + `browser-pdf-save` (its step 4). The **deploy-time base render** (§ 5) uses that exact pattern. Dispatch (§ 6) does **not** — it stamps the persisted base with a PDF library, no browser and no network.
+
+Auth for every `wrangler`/API call is the **reused per-scope narrow token** of `cloudflare/references/api.md` (one deterministic token per scope — minted once if absent, persisted to the secrets file, then loaded and reused), routed by the master's type (`cfat_…` account-scoped vs `cfut_…` user-scoped) by prefix per that reference. Deploy mechanics are `cloudflare/references/hosting-sites.md`.
+
+---
+
+## 0. Pre-flight — block on each prerequisite
+
+Do **not** deploy until all three 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."
+
+3. **The account directory must be set (attachment capability).** `email-send` attaches the signed PDF by absolute path under the account directory, and § 5 persists the base PDF there. If `ACCOUNT_DIR` is unset, the attachment silently degrades to a **text-only** send — neither party receives the PDF — and there is nowhere to persist the base render. Assert it before any deploy or sweep:
+
+   ```bash
+   ( test -n "${ACCOUNT_DIR}" && test -d "${ACCOUNT_DIR}" && test -w "${ACCOUNT_DIR}" ) \
+     && echo "ok" || echo "missing"
+   ```
+
+   On `missing`, stop:
+   > "The account directory isn't set, so I can't attach the signed PDF or persist the base render. `ACCOUNT_DIR` is normally set at spawn; if it's missing, this session was started without an account context — restart the account's session so the spawn seam sets it, then ask me again."
+
+   (`ACCOUNT_DIR` is a spawn-seam guarantee; this pre-flight only asserts it, it does not set it.)
+
+---
+
+## 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, seeds the token, and keys the persisted base PDF. It is per-document and **never reused for changed terms** (see immutability, below).
+
+**Render-once base PDF, keyed by `DOC_REF`.** The body being signed is identical for every signer, so it is rendered to PDF **once at deploy** (§ 5) and persisted under the account directory, keyed by `DOC_REF`:
+
+```
+${ACCOUNT_DIR}/e-sign/<DOC_REF>/base.pdf      # the rendered document
+${ACCOUNT_DIR}/e-sign/<DOC_REF>/base.sha256   # its content hash (drift check, § 8.3)
+```
+
+Per-signer stamped copies (§ 6) are written alongside, in the same `<DOC_REF>` directory. A new `DOC_REF` ⇒ a new render; an existing `DOC_REF` reuses its persisted base and is **never re-rendered**.
+
+**Immutability — signed content must not change.** Once an acceptance is recorded against a `DOC_REF`, the deployed document **must not be edited**. The dispatched PDF is the persisted base captured at deploy, so any later edit to the live page diverges from 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.)
+
+---
+
+## 1a. Access-gating (optional — only named recipients may load the page)
+
+The § 1 default — an unguessable hex slug plus `noindex` — keeps a low-sensitivity document private by obscurity. For a **confidential** proposal to a **named** recipient, add a **Cloudflare Access** gate in front of the page so only allowlisted emails can load it at all. Gating is **additive**: the slug and `noindex` stay; the gate sits in front of them. It is never the default and never replaces them.
+
+**One-Time PIN is the only correct identity provider here — and why.** The signer is an external party who belongs to **no** Cloudflare organization, so SSO, Google, GitHub, SAML and every other org-membership IdP cannot authenticate them. Cloudflare's built-in **One-Time PIN** emails a login code to **any allowlisted address** with no org membership required — exactly the external-signer case. Prescribe `onetimepin`; do not reach for another IdP type for an external signer (a higher-assurance provider is a separate capability, not this skill).
+
+**Load-bearing pre-flight — a gate requires an enabled login method.** Creating an Access application and policy does **not** enable a login method. If the org has **zero** identity providers when the gate goes live, the login page offers **nothing** and locks out *everyone, including the operator*. Before activating any Access app, list the org's IdPs and confirm the list is non-empty:
+
+```bash
+# Empty result here + an active Access app = total lockout. Create the IdP FIRST.
+CLOUDFLARE_API_TOKEN="${MINTED_ACCESS}" curl -sS \
+  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/access/identity_providers" \
+  | jq '.result | length'
+```
+
+**Token scope.** Gating needs the **reused per-scope Access token** (`<brand>-access` — minted once if absent, persisted, then loaded and reused per `api.md` § Provisioning and reusing a stable per-scope token; routed by prefix, with the mint→verify backoff of § 8.8 applying only on the mint-once path) carrying **Access application + policy write** *and* **`Access: Identity Providers Write`**. Resolve those permission-group ids the same way `d1-data-capture.md` § 0 resolves the Pages/D1 ids — one `GET …/tokens/permission_groups` — but **"Access: Apps and Policies Write" can return duplicate ids** from that call, and minting with the wrong variant poisons the token: it then returns `10000` on **every** call, **reads included**. So **verify the token with a read before relying on it** — a `GET …/access/apps` that returns `10000` is the wrong-id signature (distinct from § 8.8's transient post-mint `10000`, which clears within ~30s); re-resolve and mint with the other variant. Token *creation* stays an account-level concern; this skill names the scopes and consumes whatever token type the account supplies. `${MINTED_ACCESS}` below is that token.
+
+**Access-app updates are `PUT`, not `PATCH`.** When you update an existing Access app — most often to widen its destinations — send `PUT …/access/apps/{app_id}` with the **full app body** (re-supply `name`, `destinations`, `type`, `session_duration`, …). `PATCH` returns `10405 "Method not allowed for this authentication scheme"` under API-token auth; there is no working partial-update verb (`api.md` § Access).
+
+**Create IdP → app → policy, in that order:**
+
+1. **Create the One-Time PIN IdP**, then re-list to confirm the list is now non-empty (the pre-flight above, run again):
+
+   ```bash
+   CLOUDFLARE_API_TOKEN="${MINTED_ACCESS}" curl -sS -X POST -H "Content-Type: application/json" \
+     "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/access/identity_providers" \
+     --data '{"name":"One-time PIN","type":"onetimepin"}' | jq '{ok:.success, type:.result.type}'
+   ```
+
+2. **Create the Access application** scoped to the deployed host's **document path(s) `and` `/api/*`** — the signing document's path(s) plus the capture endpoints `POST /api/accept` and `GET /api/status` (§ 4). Leave `/` and the static assets **public**. Gating only the document path is a **bypass**: with `/api/*` open, anyone can `POST /api/accept` and forge an acceptance, and `GET /api/status` is readable ungated. Leaving `/` public is deliberate and load-bearing — it is exactly what lets the neutral root portal (below) load **without a PIN**; the document path(s) and `/api/*` are the only gated destinations.
+
+   **Same-origin invariant — `/api/*` must be Functions of *this* Pages project.** An Access application gates a **host + path**, never a bare path across hosts. So gating `<host>/api/*` covers `/api/accept` and `/api/status` **only when they are Pages Functions of the same Pages project — the same origin — as the gated document**. The § 2 form posts to the **relative** `/api/accept` and `/api/status`, which keeps them same-origin by construction; that default is the invariant, not a convenience. **Splitting the endpoints onto a separate origin** — a second Pages project, any other host — escapes the gate entirely while every per-document check still passes: the document 302s to login, but `POST /api/accept` on the other origin is **forgeable** by anyone and `GET /api/status` is **world-readable**, because the document's Access app never covered that host. The `gate-probe` of "Verify on live" (below) is the only check that catches this; the per-page redirect does not. If the deploy ever resolves `/api/*` to an origin other than the document's own, that origin mismatch is itself the failure — before any probe runs.
+3. **Attach a policy** whose `include` allowlist names the **signer's email** (and the business owner's). Only those addresses can authenticate and view the page.
+
+The IdP call shapes are given inline above; the Access **app** and **policy** endpoints live in `api.md`'s endpoint map, and the permission-group ids are resolved by the `api.md` method (`GET …/tokens/permission_groups`).
+
+**Verify on live.** Loading the gated page **302-redirects to a Cloudflare login page that offers One-Time PIN** — not an empty dead-end. An allowlisted email receives a code, enters it, and reaches the document; a non-allowlisted email is refused after entering its code. Reproduction-before: with **zero** IdPs the same login page offers no method at all — that is the lockout (§ 8.9).
+
+**Verify on live — `gate-probe` `/api/*`, not just the page.** The page redirect above is necessary but **not sufficient**: it never touches `/api/*`, which is exactly how a separate-origin API (the same-origin invariant, above) deploys green while wide open. Before a gated deploy is "done", hit **both** capture endpoints **unauthenticated, with no Access session**, against the live API origin, and read the status code — each must be **refused** (302 to the Access login, or 403) before it reaches the Function:
+
+```bash
+# No cookies, no Access session. API MUST be the gated document's OWN origin —
+# the canonical host § 7 writes as <project>.pages.dev, or a custom domain mapped to it.
+# An UNGATED accept endpoint inserts a sentinel row (doc_ref=GATE-PROBE); delete it as
+# part of remediation. A gated endpoint 302s before the Function runs, so nothing is written.
+API="https://<host>"
+printf 'op=gate-probe endpoint=/api/accept method=POST code=%s\n' \
+  "$(curl -sS -o /dev/null -w '%{http_code}' -X POST -H 'Content-Type: application/json' \
+       -d '{"name":"probe","email":"probe@example.com","token":"GATE-PROBE-aaaaa-aaaaaa","doc_ref":"GATE-PROBE"}' "$API/api/accept")"
+printf 'op=gate-probe endpoint=/api/status method=GET code=%s\n' \
+  "$(curl -sS -o /dev/null -w '%{http_code}' "$API/api/status?doc_ref=GATE-PROBE")"
+```
+
+**Pass:** both `gate-probe` lines report `302` or `403` — the Access gate refused each request **before** it reached the Function. **Fail:** **any other status.** `200` is the canonical signature (`POST /api/accept` forgeable, `GET /api/status` world-readable), but `400`, `409`, or `500` equally fail — any Function-originated response proves the request **reached the Function unauthenticated**, i.e. the API is ungated. (A repeat accept probe returns `409` on the sentinel's `doc_ref` UNIQUE — still ungated, still a fail; only `302`/`403` is a pass.) The cause is almost always `/api/*` resolving to a different origin than the gated document. A non-`302`/`403` here — not the page redirect — is the only signal that catches the split-origin escape. This `gate-probe` is the **unauthenticated negative** test; it is distinct from the § 7 outcome contract, which exercises the *authenticated functional* flow (POST → D1 row → status flip) and therefore runs pre-gate or from an allowlisted session. After both probes refuse, confirm an **allowlisted** session still reaches the form and accepts once.
+
+**Dispatch is unaffected (§ 6).** The sweep stamps the **persisted base** (`base.pdf`, § 1), never by fetching the gated page, so a gate never turns a dispatched "PDF" into an Access login screen — § 8.3 makes that structural. Keep it in mind whenever a gated document is swept.
+
+**Logout links carry `returnTo` — point them at the public root (the primary loop-fix).** Cloudflare Access **does** honour a logout redirect: `GET /cdn-cgi/access/logout?returnTo=<https origin root>` 302s straight to that root and **strips** the stale `__cf_access_message` param. The parameter is **camelCase `returnTo` only** — `return_to` and `redirect_url` are ignored. So build every signer-facing logout link as `/cdn-cgi/access/logout?returnTo=https://<host>/`, with `returnTo` pointing at the **public root**, never at the gated document path (which would just re-challenge for a PIN). A logout link built this way lands the signer cleanly on the public root with no stale param — this is what actually breaks the "enter PIN → logged-out screen" loop.
+
+**Root landing page — a neutral portal, the belt-and-suspenders backstop.** The § 1 project ships only the document page(s), so there is **no `/` page** unless you add one. Even with `returnTo` available, Cloudflare Access still occasionally lands a visitor on the **bare root `/`** — a logout link that omitted `returnTo`, or a post-login that did not deep-link back to the requested path — and with no `/` page that is a **404** on a client-facing portal. So a gated site **must** ship a root `index.html` as the backstop for those bare-root landings. It is a **neutral portal**, not a redirect: a single host can carry **many** gated documents (each its own slug/path/`DOC_REF` — § 3's D1 table is shared across a brand's documents, and § 1a gates each document's path **and** `/api/*`), and they all share one `/`. The root names **no** document — logout links point `returnTo` at the bare root, not at any document path — so a single portal serving every document's bare-root landing must name none.
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="robots" content="noindex,nofollow">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Private signing portal</title>
+<style>body{font:16px system-ui,sans-serif;margin:2rem;color:#444;max-width:34rem}</style>
+</head>
+<body>This is a private signing portal. Use the link you were sent to open your document.</body>
+</html>
+```
+
+The portal **names no document**: no redirect to, link to, or mention of any slug/path/`DOC_REF`, and no proposal/quote/contract content. Adding a second document to the host requires **zero** change to the root — that is the test of its genericity. It carries at most the brand-neutral one-liner above, inline styles only (no external resources), and `noindex,nofollow`. The initial-open flow is unaffected and already scales: a signer clicks their unique slug link → Access challenges → returns them to that exact path; the root is never involved. **Only** the post-logout (and occasional post-login) landing hits the root.
+
+**The root must make no auth-state claim and must never branch on `__cf_access_message` (or any Access query param).** Cloudflare **preserves `__cf_access_message=logged_out` on the URL through the entire re-login redirect** — so a user who clicks "sign back in", enters a fresh code, and is genuinely authenticated is landed back on `/` with the **stale** param still attached. A page that showed a "you've been signed out" interstitial when the param is present would show it to a logged-in user. A static page cannot tell "just logged out" from "just logged back in" from the URL alone — the only reliable signal is auth state, which a static page cannot read. The neutral portal sidesteps this entirely: it shows the **same** content in every state, so it is correct whether served to a logged-out or a re-authenticated browser. Log out of any document → `/` (with or without the stale param) → the neutral portal, never a logged-out screen and never another document's content; bare `/` (no session) → the same neutral portal; return is via the signer's original unique link → Access OTP → their document. (A graceful sign-out acknowledgement, or a real menu of the host's documents, would each need a signal a static public root cannot carry — both out of scope.)
+
+---
+
+## 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 intent-and-consent checkbox** — required; the signer cannot submit without ticking it. Its wording captures **intent to sign electronically and consent to transact electronically** — not bare assent to terms — because that intention is what gives a simple electronic signature legal effect (intro; § 8.7).
+- **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`.
+
+**Two faces, one HTML — wet-ink prints, the form does not.** A signable document carries two mutually-exclusive surfaces: the digital `#sign` form (how it is actually signed) and, optionally, a wet-ink signature block (for a printed counterpart). Scope each so it never appears on the other surface — this is what prevents the "two signatures on one page" bug:
+
+```css
+@media screen { .wet-ink { display: none } }   /* wet-ink never shows on screen */
+@media print  { #sign    { display: none } }   /* the form never prints */
+```
+
+The dispatched PDF therefore carries the agreed content and (if present) the wet-ink block, never an empty live form; the on-screen page carries only the digital form.
+
+**Print pagination — verify pages, not dimensions.** A screen-first document paginates badly to PDF (a full-bleed footer split across two pages, a near-blank trailing page). In the document's styles, force the page model rather than trusting the default flow:
+
+- `@page { size: A4; margin: … }` and explicit page-breaks (`break-before`/`break-after: page`) around full-bleed sections;
+- `break-inside: avoid` on logical blocks (a pricing table, a signature block, a certificate) so they never split;
+- `break-after: avoid` on headings so a heading never lands alone at a page foot.
+
+Confirming A4 *dimensions* is not proof of fit — **read every rendered page** of the base PDF (§ 5) before it is persisted.
+
+**The signing flow.** On load, the page asks the status Function whether this `DOC_REF` is already accepted (below); if so it shows a closed state instead of the form. On submit, client JS mints an **acceptance token** and POSTs JSON to the accept Function. On `{"ok":true}` the form is replaced by a confirmation panel showing the token; if the Function reports the document **already accepted** the signer sees a closed-state message; on any other 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 same-signer duplicate, distinct from a *different* signer hitting an already-accepted document (which the `doc_ref` guard catches; § 4).
+
+**The djb2 hash is not an access control.** It is a deterministic function of `name`, `email` and `DOC_REF` — all public-ish fields a forger can supply — so it is **defence-in-depth obfuscation of the token shape, never a gate**. It makes a token mildly unguessable and lets the database discriminate a same-signer re-submit (above); it does **not** authenticate the POST. The only thing that stops a forged `POST /api/accept` is the § 1a Access gate over a **same-origin** `/api/*`. Never treat the token as a substitute for gating the API.
+
+All confirmation, closed-state, 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; I intend this to be my electronic
+      signature and I agree to sign and transact electronically.</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 STATUS_URL   = "/api/status";
+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");}
+
+// Render the "already accepted" closed state in place of the form. textContent only.
+function showClosed(msg) {
+  const f = document.getElementById("esign");
+  const c = document.getElementById("confirm");
+  if (f) f.hidden = true;
+  c.textContent = "";
+  c.hidden = false;
+  const p = document.createElement("p");
+  p.textContent = msg;
+  c.append(p);
+}
+
+// On load, ask the status Function whether this DOC_REF is already accepted.
+// Fail OPEN: if the status call errors, show the form — the accept Function (§ 4)
+// remains the authoritative close, so a degraded status read never lets a second
+// acceptance through.
+(async () => {
+  try {
+    const r = await fetch(`${STATUS_URL}?doc_ref=${encodeURIComponent(DOC_REF)}`);
+    const j = await r.json();
+    if (j && j.accepted) showClosed("This proposal has already been accepted.");
+  } catch (_) { /* fail open — leave the form visible */ }
+})();
+
+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();
+    // Already closed by an earlier acceptance (a different signer, or a stale link).
+    // Checked BEFORE the generic !ok throw so it never falls through to the mailto fallback.
+    if (j.alreadyAccepted) { showClosed("This proposal has already been accepted."); return; }
+    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.
+
+---
+
+## 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 UNIQUE,
+     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
+   );"
+```
+
+Two uniqueness guards, two distinct purposes:
+
+- **`token UNIQUE`** makes the **same signer** re-submitting the **same** document idempotent (same name+email+`DOC_REF` ⇒ same token ⇒ collision ⇒ no new row).
+- **`doc_ref UNIQUE`** caps the document at **one acceptance, ever** — a *different* signer (different token) cannot insert a second row for a `DOC_REF` that already holds one. This is the lifecycle lock: a signed document is closed. The database, not application logic, is the backstop, so two near-simultaneous submits (a double-click, two tabs) cannot race two rows in — exactly one wins the `doc_ref` constraint and the other is rejected.
+
+**Keep `doc_ref` defined before `token`.** A same-signer re-submit collides on **both** unique columns at once — the same identity yields the same `token` *and* the same `doc_ref`. D1/SQLite reports the **last-defined** unique index first, so with `doc_ref` declared before `token` the dual collision surfaces as `UNIQUE constraint failed: acceptances.token`, which is exactly what routes a genuine same-signer re-submit to the idempotent `ok:true` branch (§ 4) rather than the 409. Reordering these two columns silently inverts that — the same signer would then get "already accepted". The order above is correct; do not swap it.
+
+`swept` is the dispatch cursor (§ 6).
+
+**The guard applies to tables created or recreated after this change.** A table that already holds more than one row for some `doc_ref` will not accept the `UNIQUE` constraint until those rows are reconciled; migrating such an existing table is out of scope here (a co-signer / multi-party model is a separate capability). For a fresh deployment the `CREATE TABLE` above is the whole story.
+
+---
+
+## 4. The Pages Functions — `functions/api/accept.ts` and `functions/api/status.ts`
+
+Two file-routed Functions: `POST /api/accept` records an acceptance; `GET /api/status` reports whether a `DOC_REF` is already accepted. No secret lives in either file; the `DB` binding is injected at runtime.
+
+### `functions/api/accept.ts`
+
+Validates the four required fields, inserts, and discriminates the two UNIQUE collisions:
+
+- a **`token`** collision is the **same signer** re-submitting — idempotent, still `ok:true` (existing behaviour, preserved);
+- a **`doc_ref`** collision is a **second acceptance** for an already-signed document — rejected with a distinct **already-accepted** response at HTTP **409**, no new row.
+
+D1 surfaces the offending column in the constraint text (`UNIQUE constraint failed: acceptances.<col>`), which is what lets one catch branch tell the two apart.
+
+```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) {
+    const msg = String(err);
+    // D1 surfaces the column in the stable text "UNIQUE constraint failed: acceptances.<col>".
+    // token  collision → SAME signer, same document, already recorded. Idempotent: still ok.
+    if (msg.includes("UNIQUE constraint failed: acceptances.token"))
+      return json({ ok: true, token, duplicate: true });
+    // doc_ref collision → a SECOND acceptance for an already-signed document. Closed: reject, no new row.
+    if (msg.includes("UNIQUE constraint failed: acceptances.doc_ref"))
+      return json({ ok: false, error: "already accepted", alreadyAccepted: true }, 409);
+    // Anything else is a real failure (e.g. token missing D1 Edit — § 8.1).
+    return json({ ok: false, error: "insert failed" }, 500);
+  }
+  return json({ ok: true, token });
+};
+```
+
+### `functions/api/status.ts`
+
+A read-only `GET /api/status?doc_ref=…` that reports **only** whether the document is accepted — a single boolean, **no signer PII**. The signing page (§ 2) may be reachable without authentication, so the response must never leak `name`, `email`, or `captured_json`.
+
+```ts
+interface Env { DB: D1Database }
+
+const cors = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, 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 onRequestGet: PagesFunction<Env> = async ({ request, env }) => {
+  const docRef = new URL(request.url).searchParams.get("doc_ref")?.trim();
+  if (!docRef) return json({ ok: false, error: "doc_ref required" }, 400);
+
+  // COUNT only — never SELECT name/email/captured_json. The body carries one boolean.
+  const row = await env.DB
+    .prepare("SELECT count(*) AS c FROM acceptances WHERE doc_ref = ?")
+    .bind(docRef)
+    .first<{ c: number }>();
+
+  return json({ accepted: (row?.c ?? 0) > 0 });
+};
+```
+
+**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 — and render the base PDF once
+
+Deploy the document + both Functions 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 Functions to the `acceptances` database.
+
+**Gated sites also ship the neutral root `index.html` (§ 1a).** When the document is Access-gated, the neutral portal goes in the **same Pages output dir** as the document(s), so the production deploy serves it at `/` in the same shot — no separate deploy. Redeploying *only* the root portal needs a **Pages-Write-only** token: the portal touches no database, so no D1 scope is minted for it.
+
+**Render the base PDF once, here, keyed by `DOC_REF`.** Immediately after the deploy, render the live document to PDF a single time and persist it under the account directory (§ 1). This is the *only* place the browser is used — `browser-navigate` to the deployed document URL, then `browser-pdf-save`, the `invoicing.md` step-4 pattern:
+
+```bash
+mkdir -p "${ACCOUNT_DIR}/e-sign/<DOC_REF>"
+# browser-navigate <deployed-url> ; browser-pdf-save -> ${ACCOUNT_DIR}/e-sign/<DOC_REF>/base.pdf
+shasum -a 256 "${ACCOUNT_DIR}/e-sign/<DOC_REF>/base.pdf" | awk '{print $1}' \
+  > "${ACCOUNT_DIR}/e-sign/<DOC_REF>/base.sha256"
+```
+
+Before persisting, **read every rendered page** of `base.pdf` — full-bleed pages bleed correctly, no footer split across pages, no near-blank trailing page (§ 2 pagination; A4 dimensions are not proof of fit). If the deployed page is behind Cloudflare Access, do this base render in a session that can authenticate to Access — it is a one-time, operator-driven step, unlike dispatch (§ 6), which must never fetch the page at all. A new `DOC_REF` triggers a fresh render; an existing one keeps its persisted base.
+
+---
+
+## 6. Sweep + dispatch
+
+Dispatch runs **only** inside a live operator session on the account's own device — when the operator asks for new acceptances, or when an in-session watcher running inside a still-live session performs the sweep. There is no off-device dispatcher; never register a Claude Code `/schedule` routine or any headless/cloud scheduler to run it (§ 8.2 says why). Mint one **D1-Edit** token here — `${MINTED_D1_EDIT}` — per `api.md` § Minting a narrow token, resolving the permission-group id as `d1-data-capture.md` § 0 does. Reads use the Edit token too: the D1 **query** endpoint rejects a D1-Read token (`d1-data-capture.md`), so a separate read-scoped token is not minted.
+
+1. **Read the unswept rows** with `${MINTED_D1_EDIT}`:
+
+   ```bash
+   CLOUDFLARE_API_TOKEN="${MINTED_D1_EDIT}" 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 — stamp, send, then mark that one row swept:**
+
+   - **Stamp a per-signer copy from the persisted base — no browser, no network.** Dispatch must **never fetch the deployed page**: it may sit behind **Cloudflare Access**, so a headless fetch hits the Access login screen, not the document, and the PDF is garbage. The render-once base (§ 5) is what removes that dependency. Load `${ACCOUNT_DIR}/e-sign/<DOC_REF>/base.pdf`, append an **Electronic Acceptance Certificate** page, and write a per-signer copy alongside it — all with a pure PDF library (**`pdf-lib`**, run as a small Node script; pick another pure library if the account standardises on one, but it must add no browser and no network call):
+
+     ```js
+     // stamp.mjs — node, offline. Reads the persisted base, appends a certificate page,
+     // writes ${ACCOUNT_DIR}/e-sign/<DOC_REF>/signed-<token>.pdf. No network, no browser.
+     import { readFileSync, writeFileSync } from "node:fs";
+     import { PDFDocument, StandardFonts } from "pdf-lib";
+
+     const dir  = process.env.DIR;                       // ${ACCOUNT_DIR}/e-sign/<DOC_REF>
+     const cert = JSON.parse(process.env.CERT);          // {name,title,token,doc_ref,accepted_at,method,assertion}
+     const pdf  = await PDFDocument.load(readFileSync(`${dir}/base.pdf`));
+     const font = await pdf.embedFont(StandardFonts.Helvetica);
+     const page = pdf.addPage();
+     const lines = [
+       "Electronic Acceptance Certificate",
+       `Name:      ${cert.name}`,
+       `Title:     ${cert.title ?? "-"}`,
+       `Doc ref:   ${cert.doc_ref}`,
+       `Token:     ${cert.token}`,
+       `Accepted:  ${cert.accepted_at}`,
+       `Method:    ${cert.method}`,                      // e.g. "simple electronic signature (UK ECA 2000 s.7 / UK eIDAS)"
+       "",
+       "Assertion the signer ticked:",
+       cert.assertion,                                   // the verbatim intent/consent text from § 2
+     ];
+     let y = page.getHeight() - 60;
+     for (const ln of lines) { page.drawText(ln, { x: 50, y, size: 11, font }); y -= 20; }
+     writeFileSync(`${dir}/signed-${cert.token}.pdf`, await pdf.save());
+     ```
+
+     The certificate fields come **from the D1 row**, not a re-fetch: `name`, `title` (an operator-defined field if present), `token`, `doc_ref`, `accepted_at`, the signing `method`, and the **verbatim intent/consent assertion** the signer ticked (§ 2). That makes the artifact self-contained evidence of who accepted, when, and on what stated basis.
+
+   - **Send twice via `email-send`**, each carrying `doc_ref`, `name`, `token`, `accepted_at`, and the **stamped** PDF (`signed-<token>.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`** — this copy is the **statutory record provided to the signer**, the evidentiary copy the legal basis (intro) relies on.
+
+     **Owner-copy visibility.** The owner copy only *arrives* if the agent's mailbox actually receives mail addressed to the business address. A recipient-filter that drops mail to the business address (the bug fixed in `rubytech-shared-catchall-mailbox`) makes the owner copy vanish while the signer copy arrives — check that filter first if the owner reports a missing confirmation.
+
+   - **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 (including a silent degrade to text-only when the attachment is missing — § 0 item 3), **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. Every `wrangler d1 execute` uses the **D1-Edit** token (reads included; the query endpoint rejects D1 Read):
+
+**When the document is Access-gated (§ 1a), `/api/*` is gated too** — so the `curl` POSTs to `/api/accept` and the `GET /api/status` below are themselves **Access-challenged (302 to login), not direct 200s**. Run this end-to-end verification either **before** the gate is applied, or from a context that can authenticate to Access — the same authenticated-session requirement § 5's base render already carries. The `wrangler d1 execute` rows reach D1 through the Cloudflare API, not the gated host, so they verify unchanged.
+
+```bash
+# 1. POST a first 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_EDIT}" wrangler d1 execute <db-name> --remote --command \
+  "SELECT token FROM acceptances WHERE swept = 0;"
+
+# 3. SAME signer idempotency: POST the SAME token again → still {"ok":true}; the SELECT shows exactly one row.
+
+# 4. LOCK: POST a DIFFERENT name/email for the SAME doc_ref → 409 {"ok":false,"error":"already accepted","alreadyAccepted":true}
+curl -sS -o /dev/null -w '%{http_code}\n' -X POST -H "Content-Type: application/json" \
+  -d '{"name":"other","email":"other@example.com","token":"QUOTE-LAKESIDE-fghij-yyyyyy","doc_ref":"QUOTE-LAKESIDE"}' \
+  "https://<project>.pages.dev/api/accept"   # expect: 409
+CLOUDFLARE_API_TOKEN="${MINTED_D1_EDIT}" wrangler d1 execute <db-name> --remote --command \
+  "SELECT count(*) c FROM acceptances WHERE doc_ref = 'QUOTE-LAKESIDE';"   # expect: 1 (no second row)
+
+# 5. STATUS: the read-only endpoint flips false → true and carries NO signer PII.
+curl -sS "https://<project>.pages.dev/api/status?doc_ref=QUOTE-LAKESIDE"
+# expect: {"accepted":true}  — and no name/email/captured_json anywhere in the body.
+
+# 6. Run the sweep (§ 6): both the owner address and test@example.com hold the confirmation email,
+#    each with the stamped certificate-bearing 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
+
+The flow has no application logging — the signal surface is the **D1 row state** plus the persisted-artifact filesystem, reconciled by standing checks. Every `wrangler d1 execute` below uses the **D1-Edit** token. The failure modes that emit no event are the ones this section exists to cover.
+
+### 8.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). First thing to check when acceptances stop arriving.
+
+### 8.2 Acceptance recorded but never dispatched (no-event) — the in-session reconciliation check
+
+The sweep never ran, or `email-send` failed after the row existed — no log, because no action was taken. **Capture is durable; dispatch is not.** The acceptance is recorded at the **edge** in D1 (intro / § 1a) the instant the signer submits — nothing is ever lost, whether or not a session is running. **Dispatch** (stamp + email) needs the account's Pi-local tooling — the D1-Edit token, `email-send`, `stamp.mjs`, `ACCOUNT_DIR` — so it happens **only** while an operator session is live. An acceptance captured while no session is running sits **unswept** until the next session runs the sweep; latency is bounded by operator session cadence, not a cron. That is a deliberate limitation of the in-session-only model, not a defect — the durable D1 row guarantees no loss. The standing check is the operator's **session-open / before-close ritual**: run the reconciliation inside a live session, and any aged unswept row is the signal to sweep now.
+
+> Dispatch runs **only** inside a live operator session on the account's own device. Never register a Claude Code `/schedule` routine, a `RemoteTrigger`, a `CronCreate` durable job, or any off-device/headless scheduler to run the sweep. `/schedule` spawns a fresh agent on **claude.ai's cloud**, which has none of this account's D1 token, `email-send`, `stamp.mjs`, or `ACCOUNT_DIR` — it physically cannot stamp or send. It is a Claude Code capability, not a SiteDesk one, and it is not a substitute for the in-session sweep. Monitoring and dispatch happen in-session, while the session is live. That is the only path.
+
+The reconciliation query, run inside a live session at open and before close:
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_D1_EDIT}" 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 operator's session cadence is an undispatched acceptance — the failure signal. Because § 6 flips `swept` only after both sends verify (and a text-only degrade is treated as a failed send, § 0 item 3), a failed or degraded dispatch leaves the row here for the next pass.
+
+### 8.3 Document modified after an acceptance, or base render missing (signed-content drift)
+
+Two faces of the same integrity guarantee:
+
+- **Drift is prevented structurally, not detected after the fact.** Dispatch (§ 6) stamps the **persisted** `base.pdf`, never the live page, so a post-acceptance edit to the deployed HTML cannot reach the dispatched record or the signer's copy — the evidentiary artifact is fixed at deploy. The document is also closed to new signers (the `doc_ref` lock plus the § 2 already-accepted state), so a later edit changes nothing of record. The § 1 immutability rule remains the operator policy: changed terms are a **new** `doc_ref` and a fresh deploy, never an edit to a signed document. (`base.sha256` is the integrity hash of the persisted base **PDF**, used below to confirm the base is intact — it is *not* a hash of the live HTML page, and the live page is never re-hashed for comparison.)
+- **Render-once integrity (the standing check):** for every distinct `doc_ref` with rows, a persisted `base.pdf` must exist under `${ACCOUNT_DIR}/e-sign/<DOC_REF>/` and still match its recorded `base.sha256`. A missing base (dispatch then has nothing to stamp) or a corrupted/swapped base (hash mismatch) is the failure; it fires at the standing check, not at dispatch:
+
+```bash
+# for each doc_ref with rows: the persisted base must exist and still match its recorded hash
+d="${ACCOUNT_DIR}/e-sign/<DOC_REF>"
+{ [ -s "$d/base.pdf" ] && [ -s "$d/base.sha256" ] \
+    && [ "$(shasum -a 256 "$d/base.pdf" | awk '{print $1}')" = "$(cat "$d/base.sha256")" ] ; } \
+  && echo "base ok" || echo "BASE MISSING OR CORRUPT"
+```
+
+### 8.4 Duplicate-acceptance row by token (same-signer idempotency regressed)
+
+Signal: a `token` appears more than once — the `token`-UNIQUE handling regressed.
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_D1_EDIT}" 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.
+
+### 8.5 More than one acceptance per `doc_ref` (the lock failed — primary standing check)
+
+The lock's failure is a **no-event** failure: an extra row appears silently — the `doc_ref` guard was dropped on a redeploy, never applied to a pre-existing table, or a race slipped through. This is the primary lock check; run it on the same cadence as the § 8.2 reconciliation, reusing the same D1-Edit token:
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_D1_EDIT}" wrangler d1 execute <db-name> --remote --command \
+  "SELECT doc_ref, count(*) c FROM acceptances GROUP BY doc_ref HAVING c > 1;"
+```
+
+Empty is healthy; **any** row is a lock failure. It fires without reproducing a second submission and without waiting for future activity.
+
+A *wrongly-locked* `doc_ref` (a legitimately new document refused because it reused a prior `doc_ref`) is **not** a defect — it is the immutability rule (§ 1) surfacing correctly; the remedy is a new `doc_ref`, not a re-open.
+
+### 8.6 Status endpoint leaks PII, or is dark
+
+- **Leak:** the `GET /api/status` response for an accepted `doc_ref` must contain **only** `accepted` — assert the body carries no `name`/`email`/`captured_json` keys (a one-shot check at deploy, repeated in the § 7 contract). A leak is a breach because the page is reachable without authentication.
+- **Dark (degraded, not a breach):** if the status `GET` errors, the page **fails open** to showing the form (§ 2). This does not let a second acceptance through — the accept Function (§ 4) still rejects it with the 409. The signal that the endpoint is dark is the form showing on an already-accepted `doc_ref`; the backstop is § 8.5, which stays empty because no extra row inserts.
+
+### 8.7 Compliance basis degraded (no-event)
+
+A hand-built document ships the old bare "agree to terms" checkbox (no intent/consent), or the certificate omits the assertion — the artifact dispatches and stores but lacks the evidentiary basis the "legally-recordable" claim depends on, with no error at any step. Signal — a **deploy-time** check, not a runtime log: grep the deployed page for the intent/consent checkbox wording (§ 2) before first acceptance, and confirm the first stamped certificate carries the assertion verbatim. Absence is the failure, caught at deploy/first-dispatch, not after a dispute.
+
+### 8.8 Token-type / freshness failures (handled branches, not no-event)
+
+A `cfut_…` master at an account endpoint returns `9109`; a freshly-minted token returns `10000` for a few seconds. Both are explicit, reproducible API responses — `api.md` § Token type routes by prefix and § verify-with-backoff absorbs the `10000` window. Diagnostic path: the verify call's JSON `errors[].code`.
+
+**A `10000` that does *not* clear is a different failure — the wrong permission-group id.** The "Access: Apps and Policies Write" group can return **duplicate ids** from `GET …/tokens/permission_groups` (§ 1a), and minting with the wrong variant poisons the Access token: it returns `10000` on **every** call, **reads included**, and never clears. The transient post-mint `10000` clears within ~30s of backoff; a `10000` that **persists on a `GET …/access/apps` read** is the poisoned-token signature — re-resolve the permission-group id and mint with the other variant. This is why § 1a verifies a freshly-minted Access token with a read before relying on it.
+
+### 8.9 Access gate active with zero enabled IdPs (no-event lockout)
+
+Only relevant when the document is Access-gated (§ 1a). An Access app is active on the page while the org has **no** identity provider, so the login screen offers no method and everyone — operator included — is locked out. It is a **no-event** failure: the gate emits no log and does not reproduce until someone tries to log in, by which point they are already locked out. Detection is a **standing audit reconciling active Access apps against enabled login methods**:
+
+```bash
+# ≥1 whenever any Access app is active = healthy; 0 with an active app = lockout.
+CLOUDFLARE_API_TOKEN="${MINTED_ACCESS}" curl -sS \
+  "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/access/identity_providers" \
+  | jq '.result | length'
+```
+
+Run on the same cadence as the § 8.2 reconciliation, but with an **Access-scoped** token — not the `${MINTED_D1_EDIT}` the other §8 checks share (this is a `curl` to the Access API, not a `wrangler d1` query). Two adjacent failures are **not** this one and need a different fix: a signer **refused after** the login page offered One-Time PIN is an allowlist miss (their email is absent from the policy `include`, § 1a); a signer who never receives the code despite the method being offered is an email-deliverability problem, not a gate defect. Gating is configuration state, so dispatch is unaffected — the sweep still stamps the persisted base (§ 1a, § 6), never the gated page.
+
+**Ground-truth lifeline** for one document's whole acceptance lifecycle:
+
+```bash
+CLOUDFLARE_API_TOKEN="${MINTED_D1_EDIT}" wrangler d1 execute <db-name> --remote --json --command \
+  "SELECT id, doc_ref, name, token, accepted_at, swept FROM acceptances WHERE doc_ref = 'QUOTE-LAKESIDE' ORDER BY id;"
+```
+
+### 8.10 Root 404 on a gated site (no-event)
+
+Only relevant when the document is Access-gated (§ 1a). The gate is active but the project ships **no `/` page**, so every Cloudflare landing on the bare root — after login (no deep-link) and after logout (`/?__cf_access_message=logged_out`) — hits a **404**. It is a **no-event** failure: nothing logs it, and it does not reproduce until a signer logs out or opens the bare domain, by which point they are staring at a raw 404 on a client portal. Signal — a deploy-time check tied to gating: whenever the § 1a gate is applied, the deployed output dir must contain an `index.html`, and that `index.html` must be the **neutral portal** — no redirect to or path of any specific document. The root is a **static file you author in the output dir** (§ 1a) and Pages serves that dir verbatim, so the check runs against your **local output dir** — the exact bytes Pages serves — and never needs to fetch the Access-gated `/`:
+
+```bash
+DIST=<pages-output-dir>   # the dir deployed in § 5
+test -f "$DIST/index.html" \
+  || echo "FAIL 8.10: gated site ships no root page"
+grep -qE 'location\.replace\(|http-equiv="refresh"' "$DIST/index.html" \
+  && echo "FAIL 8.10: root redirects to a specific document (single-document regression)"
+grep -q "__cf_access_message" "$DIST/index.html" \
+  && echo "FAIL 8.11: root branches on a sticky Access param"
+```
+
+### 8.11 Sticky-param interstitial or document-specific root (the rejected designs regressing)
+
+Two distinct regressions of the § 1a neutral portal, both caught by the § 8.10 grep of the local output dir:
+
+- **Document-specific root (single-document regression).** The root redirects to or embeds **one** document's slug/path/content (the earlier design this supersedes), so it is wrong for every other document on the host and breaks silently the moment a second document is added — no event, until a signer for document B logs out and lands on document A. Signature: any `location.replace(`/meta-refresh or document path in the root. The fix is the neutral portal — no document-specific path, no document content.
+- **Sticky-param interstitial.** The root **branches on `__cf_access_message=logged_out`** — showing a "signed out" interstitial when the param is present. Because Cloudflare preserves that param through the **entire re-login redirect**, a re-authenticated signer is landed back on `/` with the **stale** param and shown a logged-out screen *while logged in*. Signature: any reference to `__cf_access_message` in the root. The fix is the neutral portal — it makes no auth-state claim, so it is correct in every state.
+
+The neutral portal must therefore contain **no** document-specific path **and no** auth-state claim; it shows the same content unconditionally.
+
+### 8.12 Per-deployment preview URLs ungated (confidential-document leak, no-event)
+
+Only relevant when the document is Access-gated (§ 1a). A host-scoped Access app covers the **canonical host** but **not** Cloudflare's per-deployment hostnames: every Pages deploy also serves at `https://<hash>.<project>.pages.dev/…`, and that hostname is **not** behind the host-scoped gate. Confirmed on a live gated build: `https://<hash>.<project>.pages.dev/<doc-path>` served **200, ungated**, while the canonical host was gated — so a confidential document leaks via any deployment-hash URL. It is a **no-event** failure: the leaked read logs nothing and does not reproduce until someone holds a preview URL. Remedy — one of:
+
+- **Disable preview deployments** for the project, so only the production host exists; or
+- **Gate `*.pages.dev`** with an Access app, so the per-deployment hostnames are challenged too.
+
+Signal — a deploy-time / standing check tied to gating: for every gated project, assert preview deployments are disabled (or `*.pages.dev` is gated), then confirm by fetching one live `<hash>.<project>.pages.dev/<doc-path>` and asserting it is **challenged (302 to the Access login), not 200**:
+
+```bash
+# A 200 here is the leak. Expect a 302 to the Access login.
+curl -sS -o /dev/null -w '%{http_code}\n' "https://<hash>.<project>.pages.dev/<doc-path>"
+```
+
+A project with preview deployments enabled and an Access app scoped only to the canonical host is the failure signature.