@topy-ai/maggie 0.7.52 → 0.7.53

package/bundled-skills/maggie-qa-workflow/SKILL.md

@@ -124,6 +124,66 @@ It warns, with environment variable names and host classes only, when:
 
 Use `--rotating-refresh-tokens yes|no` when the code scan cannot tell.
 
+After an edit, prove the browser is running it before judging the change:
+`--base-url http://localhost:8081 --expect-symbol ComposerAutoGrow` fetches the
+page's same-origin scripts and fails when the served bundle lacks the name (a
+stale watcher, the wrong folder, or another session's server). For a local
+`--base-url` the report also names the process listening on the port and its
+start time; a server that was killed (exit 137) and replaced by another
+session fails with "port … is held by pid …".
+
+## Driving the browser during QA
+
+These rules come from sessions that rediscovered each of them:
+
+- **Find controls by role and accessible name, not by text.** Icon fonts put
+  private-use glyphs into `innerText` (a React Native Web tab reads
+  `"\nImage"` or `"Home"`), so exact-text matching fails. Match
+  `[role=tab]`, `[role=button]` with `aria-label`, or strip characters in
+  U+E000–U+F8FF before comparing.
+- **Click through the DOM when the automated window is in the background.**
+  Synthetic mouse clicks wait for the window to be visible and time out;
+  `element.click()` (or dispatching the event) works in a background window.
+  Keep real input for checks that are about input itself (hover, drag).
+- **Reuse the app tab.** Opening a new tab per check clutters the user's
+  browser and, with rotating refresh tokens, adds another app instance.
+  Navigate the existing tab, and close any tab you opened.
+- **Phone width when the window cannot be resized.** Some browser extensions
+  ignore window resizing. A same-origin `<iframe>` 390 px wide reuses the
+  signed-in session and is fine for layout checks **one at a time**: create
+  it, measure, remove it, then the next. The "no parallel iframes" rule is
+  about several app instances refreshing a rotating token at once, not about
+  a single frame. `maggie design app-collect` and `maggie qa fit-check` set
+  the size through the DevTools protocol and need no iframe.
+- **Long measurements run in the page, not in one call.** A loop over 30
+  routes inside one script call times out the browser tool. Start the loop in
+  the page (`window.__qa = {done: false, results: []}`; an async function that
+  pushes results), return immediately, then poll `window.__qa` with short
+  calls. Give each call a time budget of a few seconds.
+
+## Check that dashboards fit the screen
+
+When a dashboard must not scroll the page, check every route, tab and drawer
+at a short laptop and a phone viewport:
+
+```bash
+maggie qa fit-check --base-url http://localhost:4321 \
+  --route /merchant/bookings --route /merchant/settings \
+  --profile-dir .maggie/qa-profile --drawer-selector "[data-drawer-trigger]" \
+  --sidebar-selector "nav.sidebar" --output .maggie/qa-runs/fit.json
+```
+
+Default viewports are 1536x687 (a laptop with browser chrome) and 390x844.
+For each route it measures page overflow on both axes, then clicks every
+visible `[role=tab]` (`--tab-selector`) and measures again, then opens each
+drawer trigger on a fresh page and checks the dialog stays inside the
+viewport. Hidden panels are measured only after their tab is active — a
+panel measured while hidden reports zero, which also breaks screen-sized
+pagers that do not re-measure on tab change. Labels ignore icon glyphs.
+Writes are blocked unless `--allow-write <refresh path>` or `--allow-writes`;
+use `--cdp-url` to attach to a signed-in Chrome. Exit 1 lists each failing
+route, viewport and state, with the first element that is too wide.
+
 ## Check CORS for every method the client uses
 
 Before a release that adds or changes API calls from a browser or webview,

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -205,6 +205,39 @@ does not claim keyboard accessibility, network asset correctness or semantic
 content quality unless those checks run separately. Use the installed browser
 path explicitly when Bun is not in PATH.
 
+## Route checks: name the origin
+
+Release checks that crawl routes (dynamic SEO, localization routes, sitemap
+size) must take an explicit base URL — `--base-url` or a required
+`SITE_ORIGIN` that fails when unset — and print the origin they checked. A
+default such as `http://127.0.0.1:4321` silently hits another local project
+on that port and produces false "foreign URL" and sitemap-size failures.
+Prove which site answers first:
+
+```bash
+maggie seo origin-check --base-url http://127.0.0.1:4321 --project .
+```
+
+It compares the page's canonical / `og:url` and the robots sitemap host with
+`site` in `astro.config.*` (or `--expect-host`), fails when another site
+answers, and prints `checked origin: …`.
+
+## Personalised HTML fragments
+
+Per-person partials (recently viewed, recommendations, "your bookings",
+signed-in header fragments) are not public pages. Each must answer
+`Cache-Control: private, no-store` and `X-Robots-Tag: noindex`, with no
+`public`, `s-maxage` or CDN cache header. Global middleware that sets public
+HTML caching for every `text/html` response must leave a route's private
+header alone (check for an existing `Cache-Control` before setting one);
+otherwise a CDN caches one person's fragment and serves it to everyone. The
+public-session cache contract covers full pages; fragments follow this rule:
+
+```bash
+maggie seo fragment-check --url http://127.0.0.1:4321/fragments/recently-viewed \
+  --url http://127.0.0.1:4321/fragments/recommendations --cookie-env QA_SESSION_COOKIE
+```
+
 ## Automatic memory hook
 
 Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and completion.

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -486,6 +486,29 @@ FAQ helper from the first category implementation; it is a known gap and must
 remain marked incomplete until each FAQ record is independently AI-authored and
 reviewed.
 
+## Moving a business: clients, appointments, gift cards
+
+Importing the provider catalogue is not enough to switch a real business.
+Dry-run the exports first (nothing is written):
+
+```bash
+maggie service migrate-check --project . --timezone Europe/London --market uk \
+  --clients clients.csv --appointments appointments.csv --gift-cards gift-cards.csv \
+  --service "Lash lift" --service "Massage" --staff Jo --staff Sam
+```
+
+It recognises Fresha's (and other systems') column names by synonyms and
+lists unmapped columns; de-duplicates clients by e-mail, then by phone in
+E.164; keeps marketing consent only when the export says opted in; keeps
+only future, not-cancelled appointments, converted with the venue's zone,
+and reports clashes and unmatched services or staff instead of forcing them;
+and keeps gift-card codes with their balance in an `IMPORT:` namespace. The
+report holds counts, column names and row numbers only — no client values —
+plus the undo key and plan. Every real import writes an import record first
+so it can be undone (bookings and unused clients/staff deleted, untouched
+imported codes voided), and an optional "we've moved" e-mail goes once, only
+to imported clients with marketing consent, while online booking is live.
+
 ## Payments: Stripe live setup and gift vouchers
 
 Service pages often lead to first-party payments. When the host takes money
@@ -494,9 +517,11 @@ read-only live setup runbook in `docs/maggiedash-booking/STRIPE-INTEGRATION.md`:
 
 - verify live state with list/retrieve (`GET`) calls only; never use a create
   call as a probe — a probe expected to fail can create a real live object;
-- the owner installs webhook and Connect event-destination signing secrets
-  with a no-echo command (`read -rs … | <secret store>`); the agent never sees
-  them;
+- the owner installs webhook signing secrets — and, on a platform that hosts
+  many businesses (Stripe Connect direct charges, see "Platform hosts" in
+  `STRIPE-INTEGRATION.md`), the Connect event-destination secret — with a
+  no-echo command (`read -rs … | <secret store>`); the agent never sees them.
+  A single business needs no Connect;
 - thin-event destination signing secrets cannot be retrieved via the API;
   roll them in the Dashboard if they were not captured;
 - the Stripe Dashboard may be unusable under browser automation, so hand

package/bundled-skills/maggie-social-share/SKILL.md

@@ -22,7 +22,7 @@ and GEO. It is not a second content source of truth.
 Create the reviewable channel contract before generating copy:
 
 ```bash
-maggie tool maggie_social_share.py plan content.json \
+maggie tool maggie_social_share.py plan content.json --workspace-domain example.com \
   --channels linkedin,facebook --output .maggie/social-share-plan.json
 maggie tool maggie_social_share.py validate .maggie/social-share-plan.json
 ```
@@ -30,6 +30,20 @@ maggie tool maggie_social_share.py validate .maggie/social-share-plan.json
 The CLI does not generate copy or publish. It validates identity, canonical
 URL, channel limits, UTM links, approval state, and provider post state.
 
+- **Own domain only.** A workspace shares articles published on its own
+  site. `plan` refuses a source whose canonical URL is not on
+  `--workspace-domain` (or a subdomain), and `validate` refuses an approved
+  draft without `workspace_domain`. Apply the same rule in source selection:
+  an account that manages several sites must not pick another site's
+  articles for this workspace's plan.
+- **Image posts by default.** When a post has its own image (`image_url`),
+  each channel gets `publish_mode: "image"` with the link in the text;
+  `link_preview` is the default only without an image. A person may switch a
+  post to link preview (record `publish_mode_source: "user"`), and the
+  preview shows the card LinkedIn will show. `validate` fails an image post
+  whose copy lacks the link and an image silently dropped by link-preview
+  mode.
+
 Before connecting providers or scheduling, check the adapter, connection,
 campaign, and queue contracts (shapes and rules in
 [queue and connections](references/queue-and-connections.md)):
@@ -68,7 +82,10 @@ maggie tool maggie_marketing_run.py validate .maggie/marketing-runs/<runId>.json
    optional `not_before`, and local/remote status. Posting hours are slots;
    do not persist a fixed `scheduled_at` per post (it goes stale and strands
    overdue posts). Campaign ideas stay in the idea stage until written, and a
-   campaign starts only through the Start gate.
+   campaign starts only through the Start gate. A series or campaign created
+   only so it can be planned is deleted (or never committed) when the AI plan
+   fails, so a retry does not leave an empty draft per attempt; `campaigns`
+   fails a campaign with `plan_status: failed` and no ideas.
 6. Publish only after the required approval and entitlement checks. Record the
    publication attempt and provider ID; reconcile unknown outcomes against
    readback and retry only with the original idempotency key.
@@ -101,8 +118,13 @@ idempotency, and delete/republish behavior.
   decrypt check on every host that serves social routes.
 - Provider avatar URLs are signed and expire; cache the bytes or refresh on
   readback.
-- Keep model structured-output enums small and validate large vocabularies
-  server-side; see [provider adapter contract](../../references/provider-adapter-contract.md#structured-model-output).
+- Structured-output schemas fail on **complexity**, not only on large enums:
+  no enum inside repeated array items, small `maxItems`, and validate the
+  vocabulary server-side. Run `maggie tool maggie_social_share.py
+  schema-check plan-schema.json` before a release; see [provider adapter
+  contract](../../references/provider-adapter-contract.md#structured-model-output).
+- Posted posts have a lifecycle (Post now, delete, edit and republish); see
+  [queue and connections](references/queue-and-connections.md#posted-post-lifecycle).
 
 ## Safety and commercial boundary
 

package/bundled-skills/maggie-social-share/references/queue-and-connections.md

@@ -115,6 +115,34 @@ An adapter that publishes must declare, in addition to its scope set:
 
 Adapters without `publishes` keep the scope-only shape.
 
+## Posted-post lifecycle
+
+**Post now.** Claim the item atomically before calling the provider
+(`UPDATE ... SET status = 'publishing' WHERE id = $1 AND status IN
+('queued','approved') RETURNING ...`); a second click or another worker gets
+no row and does nothing. On a provider failure restore the previous status
+(and its slot); on an unknown outcome (timeout) leave it `publishing` for
+`reconcile`.
+
+**Delete a published post.** Delete on the provider first, then mark the
+item `deleted` with the time and who did it. A provider 404 means it is
+already gone: mark it deleted. Never delete the local record while the
+provider post still exists.
+
+**Edit and republish.** Most providers cannot edit a post, so an edit is a
+new post replacing the old one. Order matters — never take the old post down
+when the new one cannot go out:
+
+1. Pre-check everything: the source article is still published on the
+   workspace's own domain, the copy with the link fits the limit, the image
+   (if any) is present and accepted, the connection is healthy.
+2. Publish the new post (same idempotency rules as any publish).
+3. Only after the new post is confirmed, delete the old one; if that delete
+   fails, keep both recorded and retry the delete — do not roll back the new
+   post.
+4. If step 2 fails, nothing changed: the old post stays and the item returns
+   to its previous state with the error.
+
 ## Publish reconciliation — `reconcile`
 
 `reconcile` reads the publish-attempt log and a provider readback and returns

package/bundled-tools/clis/maggie_assistant_tools.py

@@ -18,7 +18,7 @@ code or call a model.
   a readable summary (never a bare UUID) and the right scope (account-level
   writes are not filed under the open site).
 - ``approval-selftest``: exercises the reference signed one-time approval
-  token (``tools/runtime/assistant_approval.py``).
+  token and standing workflow approvals (``tools/runtime/assistant_approval.py``).
 """
 
 from __future__ import annotations
@@ -34,8 +34,9 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 SCHEMA = "maggie-assistant-tool-registry.v1"
 RISKS = ("read", "write-reversible", "write-spends", "write-public", "never")
 RISK_ALIASES = {"R0": "read", "W1": "write-reversible", "W2": "write-spends", "W3": "write-public", "W4": "never"}
-CHANNELS = ("in-app", "mcp", "chatgpt", "claude", "cli")
+CHANNELS = ("in-app", "mcp", "chatgpt", "claude", "cli", "web-widget")
 SCOPES = ("account", "workspace")
+CARDS = ("place", "slot-picker", "booking", "voucher", "change-preview", "numbers", "draft", "list")
 NAME_RE = re.compile(r"^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$|^[a-z][a-z0-9]+$")
 SNAKE_RE = re.compile(r"\b[a-z][a-z0-9]*_[a-z0-9_]+\b")
 THE_USER_RE = re.compile(r"\bthe user('s)?\b", re.I)
@@ -74,6 +75,31 @@ def validate_registry(registry: dict) -> dict:
     for duplicate in sorted({name for name in names if names.count(name) > 1}):
         errors.append(f"duplicate tool name {duplicate}")
     counts = {risk: 0 for risk in RISKS}
+    servers = {}
+    for server in registry.get("mcpServers", []) or []:
+        if not isinstance(server, dict) or not server.get("name"):
+            errors.append("mcpServers entries need a name"); continue
+        name = str(server["name"])
+        servers[name] = server
+        if server.get("auth") not in {"none", "oauth"}:
+            errors.append(f"MCP server {name}: auth must be none (public, read-only) or oauth")
+        elif server["auth"] == "none":
+            limit = server.get("rateLimit") if isinstance(server.get("rateLimit"), dict) else {}
+            if not limit.get("perIpPerMinute") and not limit.get("perIpPerDay"):
+                errors.append(f"MCP server {name}: a public server needs rateLimit (perIpPerMinute and/or perIpPerDay)")
+        else:
+            if not str(server.get("resource", "")).startswith("https://"):
+                errors.append(f"MCP server {name}: resource must be the server's canonical https URL (the token audience)")
+            if server.get("audienceBinding", True) is not True and not str(server.get("audienceException", "")).strip():
+                errors.append(f"MCP server {name}: audience binding is on by default (RFC 8707); turning it off needs audienceException with the reason")
+    threads = registry.get("threads") if isinstance(registry.get("threads"), dict) else None
+    if threads and threads.get("storage") == "server":
+        if not isinstance(threads.get("retentionDays"), int) or threads["retentionDays"] < 1:
+            errors.append("threads.retentionDays is required for server-stored conversations")
+        if threads.get("deleteOnAccountDeletion") is not True:
+            errors.append("threads.deleteOnAccountDeletion must be true for server-stored conversations")
+        if threads.get("supportAccess") not in {"none", "with-consent"}:
+            errors.append("threads.supportAccess must be none or with-consent")
     for tool in tools:
         if not isinstance(tool, dict):
             errors.append("each tool must be an object"); continue
@@ -122,13 +148,47 @@ def validate_registry(registry: dict) -> dict:
             warnings.append(f"{where}: the name reads as destructive; app reviewers expect destructiveHint, so consider write-public")
         if tool.get("audit", {}).get("scope") not in (None, tool.get("scope")):
             errors.append(f"{where}: audit.scope must equal the tool scope (an account-level write is not audited under the open site)")
+        card = tool.get("card")
+        if card is not None and card not in CARDS:
+            errors.append(f"{where}: card must be one of {', '.join(CARDS)}")
+        if card == "change-preview" and risk == "read":
+            warnings.append(f"{where}: a change-preview card belongs to a write (it shows what will change before approval)")
+        for server in tool.get("mcpServers", []) or []:
+            if server not in servers:
+                errors.append(f"{where}: mcpServers lists {server!r}, which is not declared in registry.mcpServers")
+            elif servers[server].get("auth") == "none" and risk != "read":
+                errors.append(f"{where}: a public (unauthenticated) MCP server may only expose read tools")
+            elif servers[server].get("auth") == "none" and tool.get("scope") == "account":
+                errors.append(f"{where}: account-scoped tools need a signed-in caller; keep them off the public MCP server")
     for item in registry.get("cantDo", []) or []:
         if not isinstance(item, dict) or not str(item.get("text", "")).strip():
             errors.append("cantDo entries need text (and ideally 'instead')")
             continue
         for problem in user_copy_problems(str(item.get("text", "")) + " " + str(item.get("instead", "")), name_set):
             errors.append(f"cantDo '{str(item['text'])[:40]}': {problem}")
-    return {"schemaVersion": "maggie-assistant-registry-validation.v1", "passed": not errors, "errors": errors, "warnings": warnings, "counts": {"tools": len(tools), **counts}}
+    widget_tools = [t for t in tools if isinstance(t, dict) and "web-widget" in (t.get("channels") or [])]
+    if widget_tools:
+        # A visitor-facing assistant (an AI receptionist) answers strangers: no approvals are possible,
+        # so it only reads business facts, is off until the business turns it on, is capped and logged.
+        for tool in widget_tools:
+            if risk_of(tool) != "read":
+                errors.append(f"{tool.get('name')}: web-widget tools answer visitors and must be read-only; booking and payment stay in the normal booking sheet")
+            if tool.get("scope") == "account":
+                errors.append(f"{tool.get('name')}: web-widget tools act for one business (scope workspace), never on an account")
+        policy = registry.get("visitorPolicy") if isinstance(registry.get("visitorPolicy"), dict) else {}
+        if policy.get("enabledByDefault") is not False:
+            errors.append("visitorPolicy.enabledByDefault must be false: the business turns the receptionist on")
+        caps = policy.get("dailyCaps") if isinstance(policy.get("dailyCaps"), dict) else {}
+        if not caps.get("perVisitor") or not caps.get("perBusiness"):
+            errors.append("visitorPolicy.dailyCaps needs perVisitor and perBusiness (model spend and abuse)")
+        if policy.get("logAnswers") is not True:
+            errors.append("visitorPolicy.logAnswers must be true: the business can read every answer given in its name")
+        if policy.get("factsOnly") is not True:
+            errors.append("visitorPolicy.factsOnly must be true: answers come from the business's own facts, never general knowledge about prices or health")
+        if policy.get("cardDetails") != "never":
+            errors.append("visitorPolicy.cardDetails must be never: the chat never asks for or accepts card numbers")
+    public_tools = [t.get("name") for t in tools if isinstance(t, dict) and any(servers.get(s, {}).get("auth") == "none" for s in t.get("mcpServers", []) or [])]
+    return {"schemaVersion": "maggie-assistant-registry-validation.v1", "passed": not errors, "errors": errors, "warnings": warnings, "counts": {"tools": len(tools), **counts, "cards": sum(1 for t in tools if isinstance(t, dict) and t.get("card")), "publicMcpTools": len(public_tools)}}
 
 
 def annotations_for(tool: dict) -> dict:
@@ -224,6 +284,8 @@ def audit_check(registry: dict, session: dict) -> dict:
         expected_scope = "account" if tool.get("scope") == "account" else call.get("workspace")
         if expected_scope and action.get("scope") != expected_scope:
             errors.append(f"{call.get('tool')}: audited under {action.get('scope')!r}, expected {expected_scope!r}")
+        if action.get("channel") == "workflow" and not action.get("standingApprovalId"):
+            errors.append(f"{call.get('tool')}: a workflow run must record the standing approval id it ran under")
         if call.get("ok") is False and not action.get("error"):
             errors.append(f"{call.get('tool')}: failed call has no audit error")
     return {"schemaVersion": "maggie-assistant-audit-check.v1", "passed": not errors, "errors": errors, "writes": sum(1 for c in calls if risk_of(tools.get(c.get("tool"), {})) not in {"read", ""})}
@@ -249,6 +311,25 @@ def approval_selftest() -> dict:
     results["scopeBound"] = raises(lambda: approval.verify(secret, token, "key-1", "site-b", calls, now=1001))
     results["tamperRejected"] = raises(lambda: approval.verify(secret, token[:-2] + ("AA" if not token.endswith("AA") else "BB"), "key-1", "site-a", calls, now=1001))
     results["idempotencyKeyStable"] = approval.idempotency_key(issued["id"], calls[0]) == approval.idempotency_key(issued["id"], dict(calls[0]))
+    # Standing approval: a waitlist workflow may send at most 2 offer e-mails a day with one template.
+    standing, grant = approval.issue_standing(secret, "owner-1", "site-a", "waitlist-fill", [{"name": "waitlist_offer_send", "maxPerDay": 2, "fixedArgs": {"template": "waitlist_offer"}}], days=30, now=1000)
+    store = approval.StandingStore()
+    offer = {"name": "waitlist_offer_send", "args": {"template": "waitlist_offer", "clientId": "c1"}}
+    first = store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-10-13", now=1001)
+    results["standingAllowsInsideLimits"] = first["auditChannel"] == "workflow" and first["approvalId"] == grant["id"]
+    store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-10-13", now=1001)
+    def falls_back(fn) -> bool:
+        try:
+            fn(); return False
+        except approval.OutsideStandingApproval:
+            return True
+    results["standingDailyLimit"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-10-13", now=1001))
+    results["standingArgsBound"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", {"name": "waitlist_offer_send", "args": {"template": "promo"}}, "2026-10-14", now=1001))
+    results["standingOtherTool"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", {"name": "booking_cancel", "args": {}}, "2026-10-14", now=1001))
+    results["standingExpires"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-12-01", now=1000 + 31 * 86400))
+    store.revoke(grant["id"])
+    results["standingRevocable"] = falls_back(lambda: store.run(secret, standing, "owner-1", "site-a", "waitlist-fill", offer, "2026-10-15", now=1001))
+    results["standingNotAOneTimeToken"] = raises(lambda: approval.verify(secret, standing, "owner-1", "site-a", [offer], now=1001))
     return {"schemaVersion": "maggie-assistant-approval-selftest.v1", "passed": all(results.values()), "checks": results}
 
 

package/bundled-tools/clis/maggie_booking.py

@@ -260,6 +260,10 @@ def access_contract_checks(contract: dict) -> list[str]:
     return errors
 
 
+EMAIL_TEMPLATE_EVENTS_LEGACY = ["booking.confirmed", "booking.rescheduled", "booking.cancelled", "booking.reminder", "payment.action_required", "payment.refunded", "payment.no_show_fee", "package.purchase.confirmed", "package.purchase.refunded", "booking.waitlist.available"]
+EMAIL_TEMPLATE_EVENTS = EMAIL_TEMPLATE_EVENTS_LEGACY[:-1] + ["payment.late_refund_pending", "business.booking_cancelled", "business.booking_rescheduled", "business.late_payment_refund_required", "booking.waitlist.available"]
+
+
 def email_templates_contract_checks(contract: dict) -> list[str]:
     errors: list[str] = []
     properties = contract.get("properties") if isinstance(contract.get("properties"), dict) else {}
@@ -289,12 +293,13 @@ def email_templates_contract_checks(contract: dict) -> list[str]:
     if auth.get("passkeys") is not False: errors.append("passkeys must be disabled")
     if roles != ["owner", "admin", "manager"]: errors.append("roles must be owner, admin, manager")
     events = contract.get("events")
-    if not isinstance(events, list) or len(events) != 10: errors.append("exactly ten Booking email events are required")
     event_ids = [item.get("id") for item in events if isinstance(item, dict)] if isinstance(events, list) else []
-    expected_events = ["booking.confirmed", "booking.rescheduled", "booking.cancelled", "booking.reminder", "payment.action_required", "payment.refunded", "payment.no_show_fee", "package.purchase.confirmed", "package.purchase.refunded", "booking.waitlist.available"]
-    if event_ids != expected_events: errors.append("email event IDs are incomplete or out of order")
+    # MaggieDash <= 0.2.12 installs ship the ten-event contract; 0.2.13 adds the
+    # late-payment and business notices. Both are valid installed contracts.
+    if event_ids not in (EMAIL_TEMPLATE_EVENTS, EMAIL_TEMPLATE_EVENTS_LEGACY):
+        errors.append(f"email template events must be the {len(EMAIL_TEMPLATE_EVENTS)}-event list (or the {len(EMAIL_TEMPLATE_EVENTS_LEGACY)}-event list of MaggieDash 0.2.12 and earlier), in order")
     if len(event_ids) != len(set(event_ids)): errors.append("email event IDs must be unique")
-    allowed = {"customerName", "serviceName", "when", "locationName", "bookingId", "manageUrl", "bookingUrl", "reason", "actionUrl", "packageName", "amount", "expiresAt", "siteName", "arrivalNote"}
+    allowed = {"customerName", "serviceName", "when", "locationName", "bookingId", "manageUrl", "bookingUrl", "reason", "actionUrl", "packageName", "amount", "expiresAt", "siteName", "arrivalNote", "cancelledBy", "previousWhen"}
     declared_variables = contract.get("variables")
     event_variables = {variable for event in events if isinstance(event, dict) for variable in event.get("variables", []) if isinstance(variable, str)} if isinstance(events, list) else set()
     if declared_variables is not None and (not isinstance(declared_variables, list) or set(declared_variables) != event_variables or len(declared_variables) != len(set(declared_variables))):
@@ -1445,6 +1450,12 @@ def parser() -> argparse.ArgumentParser:
 
 
 if __name__ == "__main__":
+    if sys.argv[1:2] == ["rules-vectors"]:
+        from maggie_booking_rules import main as rules_main
+        raise SystemExit(rules_main(sys.argv[2:]))
+    if sys.argv[1:2] == ["connect-qa"]:
+        from maggie_booking_connect_qa import main as connect_qa_main
+        raise SystemExit(connect_qa_main(sys.argv[2:]))
     try:
         arguments = parser().parse_args()
         raise SystemExit(arguments.func(arguments))

package/bundled-tools/clis/maggie_booking_connect_qa.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Test-mode Stripe Connect QA for a booking platform (``maggie booking connect-qa``).
+
+Without a test-mode connected account every Connect path (deposits on the
+business's account, saved cards, no-show fees, packages, memberships,
+refunds, card readers) can only be tested with simulated signed webhooks.
+This command prepares a real end-to-end test run without changing anything:
+
+- refuses live keys (``sk_live_``/``rk_live_``) and reports which variable
+  names are set (never values);
+- with ``--detect``, lists the platform's **test-mode** connected accounts
+  (read-only ``GET /v1/accounts``) and names one that can take charges, or
+  explains how to create one in test mode;
+- prints the ``stripe listen`` command that forwards both platform and Connect
+  events to the local webhook routes;
+- lists the payment cases to run, with Stripe's test cards and the reader
+  simulator, so a QA run records each outcome.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import sys
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+KEY_NAMES = ("STRIPE_SECRET_KEY", "STRIPE_API_KEY")
+WEBHOOK_SECRET_NAMES = ("STRIPE_CONNECT_WEBHOOK_SECRET", "STRIPE_WEBHOOK_SECRET")
+EVENTS = [
+    "checkout.session.completed", "checkout.session.expired", "payment_intent.succeeded", "payment_intent.payment_failed",
+    "setup_intent.succeeded", "charge.refunded", "charge.dispute.created", "customer.subscription.created",
+    "customer.subscription.updated", "customer.subscription.deleted", "invoice.paid", "invoice.payment_failed",
+    "terminal.reader.action_succeeded", "terminal.reader.action_failed", "account.updated",
+]
+CASES = [
+    {"id": "deposit", "do": "Book a deposit service and pay with 4242 4242 4242 4242", "expect": "booking confirmed only after the Connect webhook; payment row on the connected account; amount, currency and account checked"},
+    {"id": "strong-authentication", "do": "Pay with 4000 0025 0000 3155 and complete 3-D Secure", "expect": "confirmed after authentication; the return page polls instead of confirming"},
+    {"id": "declined", "do": "Pay with 4000 0000 0000 0002", "expect": "booking stays pending_payment, hold expires, slot freed"},
+    {"id": "late-payment", "do": "Let the hold expire, then complete the Checkout session", "expect": "reinstated if the time is free, otherwise refunded in full with a client e-mail (rule late_payment)"},
+    {"id": "saved-card-no-show", "do": "Save a card (SetupIntent), mark the booking no-show, charge the no-show fee off-session", "expect": "fee charged on the connected account with the saved payment method; 4000 0027 6000 3184 asks for authentication and must notify the client"},
+    {"id": "package", "do": "Buy a treatment package", "expect": "package credits issued once per payment; redeeming one reduces the balance"},
+    {"id": "membership", "do": "Start a monthly membership, pause it, resume it", "expect": "subscription on the connected account; credits only in billed months (rule membership_credits)"},
+    {"id": "refund", "do": "Refund in full and partly from the dashboard", "expect": "refund on the connected account; charge.refunded reconciles the booking payment"},
+    {"id": "card-reader", "do": "Register the simulated reader (registration code simulated-wpe), send a sale to it, present a test card", "expect": "payment recorded only when the PaymentIntent succeeds; reader cancel leaves the sale open"},
+    {"id": "dispute", "do": "Pay with 4000 0000 0000 0259", "expect": "dispute shown to the business; no automatic refund"},
+]
+
+
+def _env(env_file: Path | None) -> dict[str, str]:
+    values = dict(os.environ)
+    if env_file and env_file.is_file():
+        for line in env_file.read_text(encoding="utf-8", errors="replace").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and "=" in line:
+                key, value = line.removeprefix("export ").split("=", 1)
+                values.setdefault(key.strip(), value.strip().strip("\"'"))
+    return values
+
+
+def list_accounts(key: str) -> dict:
+    token = base64.b64encode(f"{key}:".encode()).decode()
+    request = Request("https://api.stripe.com/v1/accounts?limit=20", headers={"Authorization": f"Basic {token}"})
+    try:
+        with urlopen(request, timeout=20) as response:  # noqa: S310 - fixed Stripe API host, GET only
+            return json.loads(response.read())
+    except HTTPError as error:
+        return {"error": f"Stripe answered {error.code}"}
+    except (URLError, OSError, ValueError) as error:
+        return {"error": str(error)[:120]}
+
+
+def connect_qa(env_file: Path | None, connect_url: str, platform_url: str | None, detect: bool, lister=list_accounts) -> dict:
+    values = _env(env_file)
+    errors: list[str] = []
+    warnings: list[str] = []
+    key_name = next((name for name in KEY_NAMES if values.get(name)), None)
+    key = values.get(key_name, "") if key_name else ""
+    if not key:
+        errors.append("no Stripe secret key found (STRIPE_SECRET_KEY); use the platform's test-mode key")
+    elif key.startswith(("sk_live_", "rk_live_")):
+        errors.append(f"{key_name} is a live key; Connect QA runs only in test mode — switch to the sk_test_ key")
+        key = ""
+    elif not key.startswith(("sk_test_", "rk_test_")):
+        warnings.append(f"{key_name} does not look like a Stripe test key")
+    secrets = {name: bool(values.get(name)) for name in WEBHOOK_SECRET_NAMES}
+    if not any(secrets.values()):
+        warnings.append("no webhook signing secret is set; copy the whsec_ value printed by `stripe listen` into the Connect webhook secret variable")
+    accounts = None
+    ready = None
+    if detect and key:
+        listing = lister(key)
+        if "error" in listing:
+            errors.append(f"could not list connected accounts: {listing['error']}")
+        else:
+            accounts = [{"id": a.get("id"), "chargesEnabled": bool(a.get("charges_enabled")), "detailsSubmitted": bool(a.get("details_submitted")), "country": a.get("country")} for a in listing.get("data", [])]
+            ready = next((a["id"] for a in accounts if a["chargesEnabled"]), None)
+            if not accounts:
+                warnings.append("no test-mode connected account yet: in the Stripe Dashboard (test mode) open Connect → Accounts → Create, complete onboarding with test data, then re-run with --detect")
+            elif not ready:
+                warnings.append("test connected accounts exist but none can take charges yet; finish onboarding with Stripe's test data")
+    listen = "stripe listen --forward-connect-to " + connect_url + (f" --forward-to {platform_url}" if platform_url else "") + " --events " + ",".join(EVENTS)
+    return {
+        "schemaVersion": "maggiedash-booking-connect-qa.v1",
+        "mode": "test",
+        "keyVariable": key_name,
+        "webhookSecrets": secrets,
+        "connectedAccounts": accounts,
+        "testAccount": ready,
+        "commands": [listen, "stripe trigger checkout.session.completed --stripe-account <acct_test_id>  # smoke the Connect route"],
+        "cases": CASES,
+        "status": "failed" if errors else ("warning" if warnings else "ready"),
+        "errors": errors,
+        "warnings": warnings,
+        "note": "read-only: nothing was created or charged; record each case's outcome with maggie qa record",
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie booking connect-qa", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--project", type=Path, default=Path("."))
+    parser.add_argument("--env-file", type=Path, help="default: <project>/.env")
+    parser.add_argument("--connect-webhook-url", default="http://localhost:4321/api/stripe/connect-events")
+    parser.add_argument("--platform-webhook-url", help="platform (non-Connect) webhook route, if separate")
+    parser.add_argument("--detect", action="store_true", help="read-only: list test-mode connected accounts")
+    args = parser.parse_args(argv)
+    report = connect_qa(args.env_file or args.project / ".env", args.connect_webhook_url, args.platform_webhook_url, args.detect)
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 1 if report["status"] == "failed" else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())