@topy-ai/maggie 0.7.47 → 0.7.48

package/bundled-references/maggiedash-booking/QA-TEST-PLAN.md

@@ -45,6 +45,19 @@ allocation is rejected inside a rolled-back transaction. It also verifies the
 normalized payment-event columns, availability snapshot table, and a
 PostgreSQL advisory-lock round trip.
 
+Canonical browser evidence capture treats both network-level request failures
+and HTTP responses with status 400 or higher as failed requests. Failure
+records retain viewport, method, status (for HTTP failures), and origin, but
+omit URL paths and query strings so customer identifiers and bearer-like URL
+values are not copied into the evidence artifact. Console and capture errors
+are recorded as route-level codes without raw browser or exception text. The
+GitHub Actions artifact allowlist includes only `evidence.json` and screenshots;
+the protected `storage-state.json` is excluded even when a workflow step fails. Run
+`npm run booking:browser:evidence:test` to check those cases and the 51-screen
+validator contract. Runtime and browser capture commands also avoid printing
+raw plan/exception contents to workflow logs; only allowlisted target error
+codes are emitted, and all other capture errors use a generic code.
+
 The worker repository boundary has a separate source gate:
 
 ```bash
@@ -140,6 +153,9 @@ provider payment attempts for one client action.
 
 For desktop and mobile:
 
+- On the public customer booking page, select a slot, change the native date,
+  verify availability reloads for the new date, and ensure the prior slot is
+  cleared before checkout can be submitted.
 - login redirect and return path;
 - sidebar/workspace navigation;
 - overview empty/loading/error/provider-outage states;
@@ -171,13 +187,28 @@ release-gate.json
 ```
 
 The protected workflow
-`.github/workflows/booking-browser-evidence.yml` captures the 15 Booking
+`.github/workflows/booking-browser-evidence.yml` captures all 17 Booking
 routes at 390x844, 768x1024, and 1440x1000, with a host session supplied by an
-environment-scoped secret. `validate-booking-browser-evidence.mjs` fails on a
-missing route, non-2xx response, login redirect, missing screenshot, console
-error, failed network request, or horizontal overflow reported in
-`layoutErrors`. Browser evidence must come from a dedicated test tenant and
-must never include committed cookies or customer exports.
+environment-scoped secret. The v2 contract maps every route to its expected
+primary heading. Capture records the final pathname and visible `main h1`;
+`validate-booking-browser-evidence.mjs` rejects a route redirect, the wrong
+screen heading, missing routes or screenshots, non-2xx responses, login
+redirects, console errors, failed network requests, and horizontal overflow
+reported in `layoutErrors`. Browser evidence must come from a dedicated test
+tenant and must never include committed cookies or customer exports.
+Existing v1 artifacts do not satisfy the current v2 gate and must be recaptured;
+do not relabel older evidence because it lacks the route-specific observations.
+
+The canonical MaggieDash workflows, the ORA repository's root workflows, and
+both capture commands validate `base_url` against the selected GitHub
+environment's exact-host
+`BOOKING_TEST_HOST_ALLOWLIST` variable. The value is a comma- or
+whitespace-separated list of hostnames; wildcards, non-HTTPS URLs, URLs with
+paths/credentials, and unlisted hosts are rejected. The workflows run this
+preflight before writing session-state or runtime-plan material, then pass the
+allowlist into the capture command for an independent second check. Configure
+only dedicated Booking test hosts in this variable; do not add the production
+host.
 
 The protected workflow
 `.github/workflows/booking-runtime-evidence.yml` captures all 47 host adapter

package/bundled-references/maggiedash-booking/README.md

@@ -97,6 +97,8 @@ This repository currently provides:
   the host still supplies the concrete official SDK adapter;
 - a manager Reports screen and tenant-scoped `/reports.json` read model for
   period totals plus day, service, staff, and location breakdowns;
+- venue-time manager booking displays and wall-clock inputs, with DST-gap
+  rejection and explicit choices for repeated fall-back times;
 - an idempotent 24-hour reminder worker job that queues confirmed-booking
   reminders into the existing Resend notification outbox;
 - service-level payment policies (`full`, `deposit`, `pay_later`, and
@@ -120,8 +122,10 @@ customer-flow boundary are implemented locally. A secret-free reference host
 and an Astro host scaffold are also available for contract/browser work. A host
 must still apply the schema, prove PostgreSQL transactions, verify a real
 payment account and webhook, enable notification delivery and tenant locking,
-and capture authenticated production browser/runtime/ops evidence before real
-bookings can be enabled.
+and capture authenticated browser/runtime/ops evidence against a dedicated
+HTTPS test tenant before real bookings can be enabled. Test evidence workflows
+must not target production; any production observation needs its own approved,
+read-only plan.
 Resend is the server-side notification and account-email transport. Staff
 invitation, first-login setup, password reset, one-time token expiry, and
 session revocation are implemented in the Astro host scaffold; real delivery
@@ -136,18 +140,31 @@ charges/payouts enablement, and a webhook secret. Raw Stripe credentials are
 never returned by the API or stored as plaintext Booking data. Deployment
 secrets take precedence over dashboard-managed credentials.
 
-## Current verification snapshot — 2026-09-21
+## Verification snapshot — 2026-09-28
+
+This dated snapshot records the earlier 0.7.48 candidate review and 15-route
+local browser smoke. It is historical; for the current task count, browser
+contract, and release blockers, use [`CURRENT-STATE.md`](./CURRENT-STATE.md).
+
+| Item | Current evidence |
+|---|---|
+| MaggieDash and ai-cmo source | MaggieDash package `0.2.11`; ai-cmo `0.7.48` (published) |
+| Email-template boundary | Ten events, including `payment.no_show_fee`; confirmed bookings allow a host-supplied, escaped `arrivalNote` |
+| ORA source CLI check | Local ai-cmo source `email-templates-contract` and `inspect --project` pass; the installed global package still carries the old nine-event contract and requires a package release/install readback |
+| Regression evidence | MaggieDash `npm test`, 25 targeted ai-cmo Booking Python tests, and ORA email-template/customer validators pass; ORA Astro build passes |
+
+## Historical verification snapshot — 2026-09-21
 
 | Item | Current evidence |
 |---|---|
 | MaggieDash source | Package `0.2.8`, `HEAD`/`origin/main` [`9d99de7`](https://github.com/TOPY-AI-LTD/MaggieDash/commit/9d99de7); the working tree contains newer uncommitted Booking changes |
-| Delivery board | 84 implementation tasks passed and 3 real-host evidence tasks pending (BK-030, BK-031, BK-032); Reports, reminders, payment-policy projection, cancellation policy snapshots/cutoff/refund settlement, consented Stripe no-show fee charging with explicit manager/finance approval, venue-local calendar day/week ranges, manager/customer history, editable schedule rules, catalogue, treatment package catalogue plus customer entitlement balances/redemption, public package checkout/payment return and public customer package redemption, transactional package-credit restoration on cancellation, Stripe package fulfillment/refunds, package confirmation/refund Resend notifications, locations, staff/resource management, live-config booking creation, manager and public multi-treatment appointments, segment-safe rescheduling, strict first-run setup checks, secure dashboard-managed Stripe connection, tenant-scoped Stripe Customer identity mapping, secret-safe Stripe readiness, installed-workspace validator coverage, explicit schema bootstrap, bootstrap secret provisioning, transactional schema dry-run, compatible Resend sender keys, token-bound rescheduling, customer-manage links/history, transactional waitlist conversion, priority/FIFO waitlist slot matching, synchronized install contracts, npm bundled-contract path resolution, tenant-scoped notification inspection/dead-letter replay, first-owner registration hardening, access defaults, complete server-enforced capability permissions, worker migration preflight, complete browser evidence route coverage, installable administrator-managed Booking access contracts, reference-host Team access CRUD/denial evidence, dependency-complete fresh Astro installation, tenant-scoped Resend email template management, and complete tenant booking defaults are covered by the manager/runtime and public-customer contracts |
+| Delivery board | 101 implementation tasks passed and 3 real-host evidence tasks pending (BK-030, BK-031, BK-032). The current browser contract requires all 17 manager routes across three viewports (51 screens), including Packages and Email templates; prior 45-screen captures are historical subset evidence. |
 | Local code gates | MaggieDash `npm test`, contract/UI/security/customer/runtime validators, and Python task-board/link checks passed |
 | Installer projection | The default public GitHub source installed 139 source artifacts plus 23 Astro host files in a fresh disposable project; dependency completion added the missing SSR adapter, and the installed host bootstrap validator, `maggie booking inspect`, and `astro build` all passed. Existing host deployment configs are preserved |
 | Published npm parity | Local CLI source is `0.7.39`; npm still serves `@topy-ai/maggie@0.7.38`, which has the older Booking contract and needs a release/published-tarball verification |
 | Access boundary | Standard Booking schema owns `maggiedash_booking_user_roles`; host access API, explicit permissions, linked `staff_id`, and repository data-scope checks passed |
 | Reference host | 47 manager endpoint checks plus public customer-flow checks passed, including explicit no-show fee route coverage, location setup, package catalogue management, customer package grant/balance/redemption, public package redemption from hold to zero-price booking, package checkout/payment-return, Stripe connection verification, notification replay, and multi-treatment hold/checkout/reschedule |
-| Local browser smoke | The browser contract now covers all 15 manager routes (`45` route/viewport screens) across 390/768/1440. A fresh authenticated host capture is still required; the earlier 33/33 result covered only the former 11-route surface and is not reused as production evidence |
+| Local browser smoke | At this historical snapshot the browser contract covered 15 manager routes (`45` route/viewport screens). The current v2 contract now covers 17 routes and requires route-specific path/heading evidence; the earlier artifact is not reused as complete evidence. |
 | Production proof | Not yet complete; reference-host and fixture artifacts are explicitly not production evidence |
 
 ## Current product limits
@@ -231,7 +248,7 @@ only.
 5. Enable one worker scheduler with lock, alert, retry, and dead-letter proof;
    verify Resend invitation, reset, reminder, waitlist, refund, package, and
    no-show delivery.
-6. Capture the 47-endpoint runtime, 45-screen browser, and ops evidence bundle;
+6. Capture the 47-endpoint runtime, 51-screen browser, and ops evidence bundle;
    run the final release gate before a one-location canary.
 
 The detailed execution board is maintained by

package/bundled-references/maggiedash-booking/RUNTIME-OPERATIONS.md

@@ -13,7 +13,8 @@ provider adapters, email/SMS, secrets, tenant scope, and deployment.
 | Payment webhook | `payment_attempts`, `webhook_events`, `events`, `audit_events` | `payment-webhook.mjs`, `booking.provider.webhook` | host server route |
 | Payment reconciliation | `payment_attempts`, `refunds`, `webhook_events` | `reconcilePaymentEvents` and `booking.payment.*` endpoints | host worker/provider adapter |
 | Notifications | `outbox`, `notifications`, `events`, `audit_events` | `notifications.mjs`, `claimNotifications`, `scheduleNotification` | host email/SMS adapter |
-| Browser evidence | no business tables; artifact storage only | `booking-browser-evidence-v1.json` and capture/validate scripts | protected CI environment |
+| Browser evidence | no business tables; artifact storage only | `booking-browser-evidence-v2.json` and capture/validate scripts | protected CI environment |
+| Worker freshness | `maggiedash_booking_worker_status` | successful write-cycle timestamp, read by the next cycle's `worker.stale` health check | host worker + scheduler |
 
 ## Worker sequence
 
@@ -31,16 +32,46 @@ lock tenant
 unlock tenant
 ```
 
+Sanitized ops evidence uses UTC timestamps and must preserve the sequence
+`backupVerifiedAt <= restoreVerifiedAt <= generatedAt`. Validators reject a
+restore before its backup, a report generated before restore verification, and
+non-object evidence roots. Direct CLI validation reports a bounded
+`BOOKING_CHECK_FAILED` input error for a non-object JSON file; `release-gate`
+continues and returns a structured `blocked` result with ops status `failed`.
+
 The database exclusion constraints remain the final double-booking guard. A
 distributed lock reduces duplicate work but is not a correctness substitute.
 
+Each worker acquires its tenant lock before loading worker state. If another
+cycle holds the lock, the runner exits with `status: "skipped"`,
+`worker.lock_contention` at warning severity, and `stateChanged: false`. It
+does not read worker state, write rows, dispatch providers, or mark the cycle
+as a failure. Database/lock acquisition errors still produce a failed worker
+report and must be monitored by the scheduler.
+
 Every installed PostgreSQL worker performs a read-only schema preflight before
-acquiring the tenant lock. It checks the core, Booking, and access tables. If a
-migration is missing, it exits with code 1 and emits bounded JSON with
+acquiring the tenant lock. It checks the core, Booking, access, and persisted
+worker-status tables. If a migration is missing, it exits with code 1 and emits bounded JSON with
 `status: "needs-migration"`; it does not load worker state, acquire the lock,
 or write business rows. Operators should run the schema command's `--dry-run`
 before an explicitly approved `--apply --confirm` migration.
 
+The repository reads `last_success_at` for the selected tenant before the cycle
+and upserts it only when a write-mode cycle passes. That timestamp is persisted
+in the same transaction as the worker state and is supplied to the next
+cycle's `worker.stale` evaluation. A successful write returns the committed
+status timestamp and uses it in that cycle's health report, so the report does
+not retain a stale pre-write value. Preview runs do not advance it and continue
+to evaluate the persisted timestamp. If an adapter write fails after state is
+loaded, the structured error output retains that prior timestamp for stale
+health evaluation. An external scheduler monitor is still required to detect
+a worker that never starts, because no in-process health report can be emitted
+while the process is down.
+The additive status table is now present in ORA staging; the six-job preview
+there passed with `write=false`, zero alerts, and no provider dispatch. The
+preview intentionally left `last_success_at` empty. Production still needs the
+schema migration before the updated worker can run.
+
 Notification delivery is intentionally after booking/payment truth is committed.
 `notifications.mjs` stores only a recipient hash and allowlisted template
 variables, leases rows before dispatch, retries with exponential backoff, moves
@@ -66,6 +97,28 @@ payment signal.
 
 ## Host adapter module
 
+The worker supports `--help`, which exits before loading environment values or
+connecting to PostgreSQL. The worker defaults to preview mode. A preview reports eligible outbox rows as
+`previewed` and never invokes `dispatchNotification`; it does not write the
+claim or delivery result. `--write` performs database writes and invokes the
+host provider for each claimed notification. Reconcile staging outbox/provider
+activity before any write-mode run.
+
+The generic Astro PostgreSQL worker and ORA host worker include the
+schema-versioned `health` summary in successful cycle output and caught
+schema/lock/runtime failures. It carries stable alert codes, severity, a
+correlation ID, and counts only; the worker does not send an alert itself.
+Route critical reports from the host's structured log pipeline to its chosen
+alert destination. Configuration and database connection failures that occur
+before worker startup remain process-level errors and must also be monitored by
+the scheduler. Structured startup and runtime errors pass through the shared
+redactor, which removes known secret environment values, connection URIs,
+bearer/API tokens, customer email and phone numbers, and sensitive key/value
+fragments before writing JSON.
+When the provider accepts a notification, its opaque `providerRef` is retained
+on the sent outbox row for provider activity reconciliation; it is not exposed
+through customer-facing DTOs.
+
 The production command accepts a host module:
 
 ```bash
@@ -117,10 +170,12 @@ state write.
 
 The protected workflow in
 `.github/workflows/booking-browser-evidence.yml` requires an HTTPS base URL and
-an environment-scoped, short-lived storage state. It captures 15 manager
-screens at mobile/tablet/desktop widths, records console/request failures, uploads
-artifacts for 14 days, and fails validation when any route is missing, not
-ready, non-2xx, or has a browser/network error.
+an environment-scoped, short-lived storage state. The v2 contract captures all
+17 manager screens at mobile/tablet/desktop widths and binds each route to its
+expected primary heading. Evidence records the final pathname and rendered
+heading; validation rejects wrong-route redirects, a wrong screen rendered at
+the requested URL, missing screens, non-2xx responses, and browser/network
+errors. Artifacts are retained for 14 days.
 
 Never commit storage state, cookies, screenshots with customer data, or raw
 provider payloads. Use a dedicated test tenant and redact artifacts before
@@ -138,7 +193,8 @@ must never be used as production evidence.
 
 Alert on:
 
-- worker lock contention or two missed minute ticks;
+- worker lock contention, a stale last successful write cycle, or two missed
+  minute ticks;
 - availability read model older than five minutes;
 - holds expiring above baseline;
 - payment webhook verification/quarantine spikes or reconciliation lag;

package/bundled-references/maggiedash-booking/SKILLS-AND-CLI.md

@@ -210,6 +210,12 @@ present it reports `dashboard-or-host-secret-pending` and points the signed-in
 owner/manager to the secure Booking Overview connection form. A partial
 deployment pair remains `degraded` because the dashboard form is intentionally
 not allowed to override deployment-managed credentials.
+For compatibility with the existing ORA host, `setup` also recognizes
+`ST_SECRECT_KEY` as a legacy alias for `STRIPE_SECRET_KEY`; a complete alias
+plus `STRIPE_WEBHOOK_SECRET` pair is still only
+`online-payments-pending-verification`. New deployments should use the
+canonical name, and only the authenticated Booking connection check can verify
+that the credentials connect to the intended Stripe account.
 `contract` accepts both the source contract JSON Schema and the compact
 ai-cmo-skills contract representation. It never reads secrets or customer data.
 
@@ -445,8 +451,11 @@ maggie booking release-gate --project . --require-runtime \
   --require-board
 ```
 
-The browser gate checks all 15 screens at mobile/tablet/desktop widths, safe
-screenshot paths, ready state, no console errors, and no failed requests.
+The browser gate checks all 17 screens at mobile/tablet/desktop widths, safe
+screenshot paths, PNG/JPEG content matching the file extension, exact viewport
+width and at least viewport height (host captures use `fullPage`), ready state,
+no console errors, and no failed requests. Screenshot artifacts are capped at
+25 MiB each.
 The board gate additionally fails closed until every task in
 `docs/maggiedash-booking/EXECUTION-BOARD.json` is `passed`; use `--board` to
 inspect a different board.

package/bundled-references/maggiedash-booking/STRIPE-INTEGRATION.md

@@ -59,7 +59,8 @@ states (`requires_action`, `pending`, `failed`, `succeeded`, `cancelled`, and
 The first adapter should subscribe only to events the configured capabilities
 need:
 
-- `checkout.session.completed`, `checkout.session.async_payment_succeeded`,
+- `checkout.session.completed`, `checkout.session.expired`,
+  `checkout.session.async_payment_succeeded`,
   and `checkout.session.async_payment_failed`;
 - `payment_intent.processing`, `payment_intent.payment_failed`,
   `payment_intent.succeeded`, `payment_intent.requires_action`, and
@@ -104,6 +105,47 @@ accounting, CRM, support, analytics, marketing, and workflow automation. It is
 an integration surface, not a reason to add third-party credentials to the
 MaggieDash browser bundle.
 
+## Live setup runbook (read-only verification)
+
+Switching a host to live mode is the step most likely to create real objects
+by accident. A probe that was expected to fail has created a real live object,
+so the live checklist is strictly read-only from the agent side:
+
+1. **Verify with GET only.** Use list/retrieve calls (`GET /v1/account`,
+   `GET /v1/webhook_endpoints`, `GET /v2/core/event_destinations` or the
+   SDK equivalents, `GET /v1/products?limit=…`) to confirm account mode,
+   enabled capabilities, endpoint URLs, and subscribed events. Never use a
+   `POST`/create call as a probe "to see whether it fails"; in live mode it may
+   succeed. If a write is genuinely required, show the exact request to the
+   owner and run it only after explicit approval.
+2. **Install signing secrets through a user-run, no-echo command.** The agent
+   must not see, print, or paste webhook or Connect event-destination signing
+   secrets. Give the owner a command they run themselves, for example:
+
+   ```bash
+   read -rs STRIPE_WEBHOOK_SECRET && printf '%s' "$STRIPE_WEBHOOK_SECRET" \
+     | wrangler secret put STRIPE_WEBHOOK_SECRET   # or the host's secret store
+   unset STRIPE_WEBHOOK_SECRET
+   ```
+
+   Then verify presence only (secret name listed, value never read back).
+3. **Thin-event destination secrets are not retrievable via the API.** A
+   Connect/thin-event destination's signing secret is shown once in the
+   Dashboard when the destination is created or rolled. If it was not
+   captured, roll it in the Dashboard and install the new value with step 2;
+   do not try to fetch it programmatically.
+4. **Hand Dashboard steps to the owner.** The Stripe Dashboard can be unusable
+   under browser automation (bot challenges, 2FA, session prompts). Treat
+   Dashboard-only steps — activating live mode, creating or rolling event
+   destinations, revealing secrets, Connect onboarding — as owner tasks with a
+   written checklist, then confirm the result with the read-only calls above.
+5. **Record evidence, not values.** Capture account mode, endpoint IDs, event
+   lists, and secret *presence* in the release evidence; never key material.
+
+`maggie booking setup` and `maggie booking stripe-audit` do not call Stripe:
+they read local configuration and the versioned capability contract only.
+Any host-side live readiness check must likewise issue `GET` requests only.
+
 ## Recommended rollout order
 
 1. Stripe Customers + Checkout Sessions or PaymentIntents.
@@ -114,7 +156,8 @@ MaggieDash browser bundle.
 6. Billing/Portal for memberships; Terminal for in-person operations; Connect
    only for a true platform model.
 7. Gift-card partner or local ledger after accounting and redemption rules are
-   approved.
+   approved. The local-ledger option is fixed by the
+   [voucher lifecycle contract](./VOUCHERS.md).
 
 Run the local contract gate with:
 
@@ -127,3 +170,24 @@ maggie booking stripe-audit --contract /path/to/MaggieDash/contracts/stripe-book
 No production payment, refund, gift-card issue, or referral reward is enabled
 by this document. The host must add its adapter, integration tests, secret
 configuration, and runtime evidence first.
+
+
+Public customer booking payments explicitly request the hosted Checkout flow.
+The PostgreSQL payment adapter preserves `hosted` in the normalized request,
+its idempotency hash, and provider call; the Stripe adapter then creates one
+Checkout Session for that payment attempt. Package purchases already use the
+same hosted flow.
+
+
+Hosted Checkout Sessions request a 31-minute expiry, above Stripe's 30-minute
+minimum. Reconciliation recognizes `cs_` references and retrieves the Checkout
+Session; open sessions remain pending, paid sessions succeed and adopt the
+PaymentIntent reference when Stripe provides one, and expired sessions map to
+the provider-neutral cancelled state.
+
+
+For Checkout's asynchronous payment methods, supported `checkout.session.*`
+webhooks retain the Session's PaymentIntent reference when Stripe provides one.
+The Session ID is the fallback for events without a PaymentIntent, such as an
+expired unpaid Checkout. This keeps later reconciliation and refund requests
+on the provider object they expect.

package/bundled-references/maggiedash-booking/TASK-RUNBOOK.md

@@ -79,7 +79,7 @@ maggie booking release-gate --project . --require-runtime \
   --require-ops --ops-evidence .maggie/booking/ops-evidence.json
 ```
 
-`--require-browser` applies the same 15-screen × 3-viewport checks as the
+`--require-browser` applies the same 17-screen × 3-viewport checks (51 screens) as the
 browser evidence validator, including safe screenshot paths, ready state,
 empty console errors, and empty failed-request reports.
 

package/bundled-references/maggiedash-booking/TASKS.md

@@ -40,8 +40,8 @@ or evidence gate. The detailed leaf-task board is
 | BK-027 | Finish Booking UI data loading, navigation, forms, and action feedback | MaggieDash | BK-018, BK-022, BK-023 | typed route loading, pagination, dialogs, forms, feedback | UI source gate + esbuild + reference-host Chrome smoke | passed |
 | BK-028 | Finish manager daily operations journeys | MaggieDash | BK-021, BK-023, BK-027 | calendar modes, lifecycle/reschedule, payment operations, audit views | UI source gate + reference-host Chrome interaction smoke | passed |
 | BK-029 | Verify authentication, tenancy, roles, and privacy boundaries | both | BK-019, BK-022, BK-027 | session/role/project checks, staff lifecycle-only mutations, payment/customer denial, and redaction scan | security validator + contract gate | passed |
-| BK-030 | Wire the production worker and operational controls | both | BK-020, BK-021, BK-024, BK-026 | injected PostgreSQL worker repository/adapter, tenant lock, correlation/health report, dead-letter policy, ops evidence contract, production fixture guard, executable backup/restore rehearsal, and reviewed systemd/cron schedule generation | adapter/repository/health/ops evidence tests + `maggie booking worker-schedule` + real disposable worker cycle/schema/lock + `npm run booking:postgres-backup-restore:integration -- --source-database-url <source> --restore-database-url <empty-target> --pg-bin-dir <matching-postgres-bin-dir> --confirm`; host connection/alert routing/backup/recovery evidence pending | needs-evidence |
-| BK-031 | Capture real host conformance and browser evidence | both | BK-019, BK-022, BK-028, BK-029, BK-030 | 47-manager-endpoint runtime plan/evidence and 15-screen Playwright evidence with concrete route/query validation, console/request/layout overflow checks | `npm run booking:runtime:plan:test` + protected runtime/browser workflows | needs-evidence |
+| BK-030 | Wire the production worker and operational controls | both | BK-020, BK-021, BK-024, BK-026 | injected PostgreSQL worker adapter, serialized tenant-scoped reads, no-provider dry-run, credential-free `--help`, tenant lock, correlation/health report with a persisted tenant-scoped last-success timestamp, dead-letter policy, ops evidence contract, production fixture guard, executable backup/restore rehearsal, and reviewed systemd/cron schedule generation | adapter/repository/health/ops evidence tests + safe installed `--help` checks + `maggie booking worker-schedule` + real disposable worker cycle/schema/lock + staging no-dispatch preview + backup/restore integration; lock contention skips before state load and provider dispatch; `worker.stale` reads the persisted prior success and the status table is preflighted; ORA staging migration, six-job preview, and real PostgreSQL integration passed; redaction covers customer email and phone numbers; ORA staging tools now enforce normalized production/staging database separation and provide a read-only cleanup audit; local backup/restore rehearsal passed; ORA production timer observed active and write-capable; provider activity review, alert routing, and host recovery evidence pending | needs-evidence |
+| BK-031 | Capture real host conformance and browser evidence | both | BK-019, BK-022, BK-028, BK-029, BK-030 | ORA local Chrome v2 QA now checks all 17 manager routes at 3 viewports (51/51 normalized route/heading/layout passes, zero captured console errors, no horizontal overflow). A post-BK-141 localhost smoke also confirms Calendar venue-zone rendering and the Bookings direct route/New booking dialog after fixing a missing dirty-state hook and SSR hydration mismatch. Failed network requests were not observable and screenshot bitmap dimensions vary, so local artifacts remain supplemental only. The ORA repo `.env` has no dedicated HTTPS staging base URL; protected workflow secrets were not inspected. Canonical MaggieDash and ORA root workflows now run the exact environment host-allowlist preflight before protected state writes and pass the allowlist to capture for a second check; regression and contract checks cover workflow ordering. Authenticated HTTPS-host evidence for all 47 endpoints and the canonical 51-screen browser artifact remain open | `npm run booking:runtime:plan:test` + MaggieDash `npm test` + ORA `booking:evidence-target:test`, `contract:check`, Astro check/build + protected-workflow order/allowlist regression + canonical/ORA helper byte parity + ORA local Chrome QA (supplemental only) | needs-evidence |
 | BK-032 | Run release gate, canary, documentation, and feedback closure | both | BK-025, BK-030, BK-031, BK-033, BK-034, BK-035, BK-036, BK-037, BK-038 | final release report, browser artifact parity/layout rejection, and docs | `maggie booking release-gate --require-runtime --require-browser --require-ops --require-board` | needs-evidence |
 | BK-033 | Freeze and validate the public customer booking boundary | both | BK-021, BK-024, BK-026 | public-noindex catalog/availability/hold/checkout/payment-return/cancel contract, redacted DTOs, notification intents, and host safety boundary | `npm run booking:customer-flow:test` + `npm test` | passed |
 | BK-034 | Ship the public customer booking page and pending-payment recovery UI | MaggieDash | BK-033 | installable customer page source, Astro route starter, catalog/availability/hold/checkout/pending-return UI, and noindex/public request checks | `npm run booking:customer-ui:test` + manifest/install validation | passed |
@@ -94,7 +94,7 @@ or evidence gate. The detailed leaf-task board is
 | BK-081 | Harden first-owner registration | both | BK-058, BK-071 | Serialize first-owner registration, verify existing passwords, and prevent password overwrite or disabled-account reactivation | MaggieDash bootstrap validator + `npm test` + ORA `contract:check`/build + `git diff --check` | passed |
 | BK-082 | Harden Booking access defaults and disabled-account boundary | both | BK-026, BK-081 | Give invited staff/finance accounts safe role defaults, preserve granular permissions, and reject disabled accounts instead of re-enabling them | MaggieDash bootstrap validator + `npm test` + ORA `contract:check`/build + `git diff --check` | passed |
 | BK-083 | Add worker migration preflight | both | BK-030, BK-070 | Check core, Booking, and access tables before worker lock/repository reads and return bounded `needs-migration` JSON without writes or stack traces | worker `node --check` + Astro bootstrap validator + unmigrated ORA worker run + `git diff --check` | passed |
-| BK-084 | Synchronize browser evidence with the complete manager workspace | both | BK-080, BK-083 | Cover all 15 manager routes at mobile, tablet, and desktop viewports and keep installed UI markers aligned with the evidence contract | MaggieDash `npm test` + ORA contract/build + ai-cmo Booking tests + packaged task validation + `git diff --check` | passed |
+| BK-084 | Synchronize browser evidence with the complete manager workspace | both | BK-080, BK-083 | Covered the then-current 15 manager routes across mobile, tablet, and desktop; BK-120 extends the evidence set to all 17 current routes | MaggieDash `npm test` + ORA contract/build + ai-cmo Booking tests + packaged task validation + `git diff --check` | passed |
 | BK-085 | Make cancellation and refund policy tenant-configurable and booking-scoped | both | BK-064, BK-084 | Configure cutoff/refund/no-show policy, snapshot it on every booking creation path, and enforce customer cancellation cutoff without pretending provider refunds are automatic | MaggieDash `npm test` + ORA contract/build + policy validators + `git diff --check` | passed |
 | BK-086 | Make calendar day and week views honor their requested venue-local range | both | BK-084, BK-085 | Filter Day/Week queries by the correct venue-local range, keep staff scope, and align reference host/UI behavior with the PostgreSQL contract | MaggieDash `npm test` + calendar/repository validators + ORA contract/build + `git diff --check` | passed |
 | BK-087 | Execute cancellation refunds through the provider boundary and Resend outbox | both | BK-080, BK-085, BK-086 | Allocate policy-safe refunds across captured attempts, call the injected provider after cancellation, expose bounded settlement status, queue payment.refunded only for accepted/pending refunds, and keep generic/ORA Resend workers behaviorally aligned | MaggieDash `npm test` + cancellation/customer settlement validators + Astro bootstrap validator + ORA contract/build + `git diff --check` | passed |
@@ -115,9 +115,20 @@ or evidence gate. The detailed leaf-task board is
 | BK-101 | Complete server-enforced Booking capability permissions | both | BK-089, BK-100 | Reconcile every route capability with the administrator registry, enforce safe role defaults for legacy rows, honor explicitly granted staff reads, and synchronize generic/ORA/reference-host/CLI contracts | MaggieDash npm/access/route-handler gates, ORA contract/build, ai-cmo Booking tests, and `git diff --check` | passed |
 | BK-102 | Persist provider customer identity for real Stripe payments | both | BK-025, BK-100 | Resolve local tenant customer UUIDs to idempotent Stripe Customer objects, persist only the provider reference, and use it for Checkout/PaymentIntent/SetupIntent without leaking credentials or cross-tenant data | Stripe adapter conformance with customer resolver, central/ORA schema validators, ORA contract/build, MaggieDash `npm test`, and `git diff --check` | passed |
 | BK-103 | Add consented Stripe no-show fee charging | both | BK-088, BK-102 | Add an explicit manager/finance action that charges only a policy-derived no-show fee when the customer consented, a saved payment method is available, and Stripe off-session capability is verified; persist adjustment payment/audit state and queue the Resend payment notification | Stripe adapter, payment adapter, route/reference-host, email, UI, central `npm test`, ORA contract/build, and `git diff --check` | passed |
+| BK-104 | Gate public booking exposure on host readiness | both | BK-033, BK-034 | Shared fail-closed readiness gate and test override; gate Astro customer page and new customer creation routes while preserving customer continuations; install the source manifest and reuse route policy in ORA | MaggieDash `npm test` + Astro host-bootstrap gate + direct route guard tests + ORA public-gate/build + source CLI install parity | passed |
+| BK-105 | Synchronize ORA Booking CLI gates with current contracts | both | BK-097, BK-100 | Sync ORA-local inspect/setup validator and source contract with the canonical ten-event template contract, `arrivalNote`, and Stripe key alias behavior while preserving pending-verification semantics | ORA-local inspect/setup/email-template contract + canonical Booking CLI unit tests + byte-parity + whitespace checks | passed |
+| BK-106 | Explain Stripe connection checks in the Booking setup checklist | MaggieDash | BK-100, BK-105 | Show API, webhook, charge and payout check results, with a clear action when the account cannot accept payments | Booking UI validator + MaggieDash `npm test` + task-board validation + `git diff --check` | passed |
+| BK-107 | Derive online-payment capability from verified Stripe charge availability | both | BK-100, BK-104, BK-106 | Keep online/off-session payment disabled until the credential is verified and Stripe reports charges enabled; mirror the rule into ORA | Stripe readiness regression + host-bootstrap + MaggieDash `npm test` + ORA contract/build + byte parity | passed |
+| BK-108 | Fail closed when online-payment capability is missing | both | BK-107 | Missing payment capability in stored settings must not make manager Overview or payment-health report payments ready | PostgreSQL core repository regression + MaggieDash `npm test` + ORA contract/build + source parity | passed |
 
 ## Execution rule
 
+| BK-109 | Require explicit online-payment capability in shared payment flows | both | BK-108 | Shared payment starts and reference-host readiness must fail closed unless onlinePayment is an explicit boolean true | focused gateway/reference-host regressions + MaggieDash `npm test` + ORA contract/build + task board | passed |
+
+| BK-110 | Verify current Booking install parity in a disposable Astro host | both | BK-109 | Exercise the current manifest through canonical CLI install; compare every projected file and run installed inspect/bootstrap validators without DB or dependency writes | disposable Astro install + exact parity + inspect + installed validators + source host-bootstrap + board | passed |
+
+| BK-111 | Bind Stripe gateway capabilities to verified account state | both | BK-107, BK-109, BK-110 | Runtime Stripe gateway must use account-verification state, not credential presence or hardcoded true values | readiness matrix + adapter regressions + MaggieDash tests + ORA contract/build + 207-file install parity | passed |
+
 For each leaf task: select it with `maggie booking tasks`, write the plan and
 acceptance checks, implement the smallest complete slice, run its gate, update
 the relevant docs, then append a dated entry to [`PROGRESS.md`](./PROGRESS.md).
@@ -135,3 +146,33 @@ invent a production provider integration, notification transport, or live
 database migration runner. Those remain explicit Phase 2–6 host work in
 [`CURRENT-STATE.md`](./CURRENT-STATE.md) and are represented by contracts and
 readiness states where the host must own the runtime behavior.
+| BK-112 | Require verified online-payment capability for public exposure | both | BK-104, BK-107, BK-111 | Keep the natural public entry closed unless Stripe is connected in live mode with an explicit onlinePayment capability and verified secret fingerprint; preserve parity with generic Astro | ORA exposure/contract/readiness validators + Astro build + generic host-bootstrap parity + task-board validation | passed |
+| BK-113 | Restrict public force-open override to non-production hosts | both | BK-104, BK-112 | Deny force-open by default; generic Astro and ORA may opt in only outside production, while production force-off remains available and force-on falls back to natural readiness | shared and ORA gate regressions + host-bootstrap parity + ORA contract/build + staging-backed production preview + fresh install parity + task-board validation | passed |
+| BK-114 | Show verified Stripe account reference in Booking setup | both | BK-100, BK-102, BK-111 | Return the tenant-scoped persisted Stripe account ID and show it in the manager checklist to support intended-account confirmation, with no secret/provider payload exposure | PostgreSQL/reference-host/UI validators + MaggieDash npm test + ORA validators/build + fresh install checks + task-board validation | passed |
+| BK-115 | Complete customer payment-return handoff and guest details | both | BK-107, BK-114 | Use the long-lived manage token after verified payment, expose safe guest/pricing details to the customer DTO, and preserve only the suitability-cleared marker in ORA holds | MaggieDash/ORA customer-flow and UI validators + staging PostgreSQL integration + build + install parity + board validation | passed |
+| BK-116 | Fail fast before staging checkout writes when Stripe test charges are disabled | ORA host harness | BK-114, BK-115 | Run a read-only Stripe test-account capability preflight before staging writes; reject disabled charges and live keys without exposing credentials | ORA preflight unit tests + checkout suite fail-fast check + task-board validation | passed |
+| BK-117 | Validate browser screenshot image contents and viewport dimensions | both | BK-031 | Require PNG/JPEG bytes to match the extension and named viewport width, allow full-page height, and reject malformed or oversized artifacts across the canonical gate and ORA mirrors | Python browser-evidence unit tests + MaggieDash npm test + canonical/ORA JS valid and invalid fixture parity + mirror parity + task-board validation | passed |
+| BK-118 | Keep packaged Booking status references link-safe | ai-cmo-skills | BK-091 | Replace a workspace-only relative link in canonical Booking status docs and rebuild the standalone CLI reference bundle | bundled-reference markdown-link test + full AI-CMO Python suite + task-board validation | passed |
+| BK-119 | Verify customer date changes refresh availability and clear stale slots | ORA host harness | BK-115 | Change the date after selecting a public customer slot; prove the new-date availability request and response render, the old selection clears, and the browser submits no hold/checkout | ORA local-staging Playwright UI journey + contract/build + task-board validation + `git diff --check` | passed |
+| BK-120 | Cover every current manager screen in browser evidence | both | BK-117 | Align the evidence contract/capture/validator and ORA mirrors with all 17 current screens, including Packages and Email templates, across three viewports (51 screens) | canonical/ORA accept and missing-route regressions + MaggieDash `npm test` + ORA contract/build + mirror parity + packaged-contract test + task-board validation | passed |
+| BK-121 | Reject browser evidence captured from the wrong manager screen | both | BK-120 | Version the evidence contract to v2 and require each screen’s final pathname and primary heading to match its manager route | canonical/ORA path-heading regressions + MaggieDash `npm test` + AI-CMO browser-evidence tests + ORA contract/build + mirror parity + task-board validation | passed |
+| BK-122 | Test browser capture readiness without requiring a live host | both | BK-121 | Extract and package the pure pathname/readiness helper; cover successful and rejected capture states deterministically | helper condition regressions + MaggieDash `npm test`/manifest + AI-CMO Booking tests + ORA contract/build + mirror parity + task-board validation | passed |
+| BK-123 | Keep Booking inventory and release status docs aligned with contracts | ai-cmo-skills | BK-122 | Align public inventory/current-state docs with v2 routes and latest Stripe/staging evidence; test task counts against the board | docs inventory/status regression + AI-CMO Booking tests + task-board validation + ORA doc checks | passed |
+| BK-124 | Honor scheduled location closures in customer availability | both | BK-052, BK-123 | Load location closure intervals into the shared planner and reject overlapping public slots and holds while preserving exact boundaries | pure planner + PostgreSQL customer-adapter closure regressions + ORA contract/build + task-board validation | passed |
+| BK-125 | Apply dated staff shifts to customer availability | both | BK-052, BK-124 | Load date-scoped shifts and constrain assigned staff to shifts plus recurring venue/staff hours, preserving fallback on dates without shifts | pure planner + PostgreSQL customer-adapter shift regressions + ORA contract/build + task-board validation | passed |
+| BK-126 | Enforce configured availability on manager-created bookings | both | BK-042, BK-052, BK-125 | Apply the shared venue/staff/resource planner to direct manager creation and waitlist conversion; keep active manager-only services bookable; reject schedule-ineligible explicit assignments before booking/queue writes | Canonical and ORA repository regressions + fresh local-source install projection + customer/availability validators + ORA contract/build + docs/board validation | passed |
+| BK-127 | Enforce configured availability on booking reschedules | both | BK-052, BK-125, BK-126 | Apply the shared planner to proposed manager/customer reschedules while excluding the current booking's old allocations | Canonical and ORA repository regressions + fresh local-source install projection + customer/availability validators + ORA contract/build + docs/board validation | passed |
+| BK-128 | Synchronize expired Stripe Checkout reconciliation across hosts | both | BK-025, BK-030 | Normalize `checkout.session.expired` as a cancelled attempt, cancel its pending booking and release its reserved allocation; sync contract/CLI/host mirrors | Runtime regression + PostgreSQL 16 disposable worker integration + MaggieDash npm test + ORA validators/contract + AI-CMO contract/task validation | passed |
+| BK-129 | Route package purchase reads through the payment repository seam | both | BK-096, BK-097 | Keep the payment-owned manager read on the composed payment repository, outside the core-only transaction callback | service regression + MaggieDash npm test + board validation + `git diff --check` | passed |
+| BK-130 | Persist provider references returned by payment reconciliation | both | BK-025, BK-030 | Save a refreshed provider payment reference during payment-attempt or package-purchase reconciliation, preserving the prior reference when omitted | PostgreSQL payment-adapter regression + MaggieDash npm test + board validation + `git diff --check` | passed |
+| BK-131 | Carry hosted Checkout intent through public booking payments | both | BK-107, BK-130 | Preserve hosted intent from customer checkout through payment adapter and include it in request identity so Stripe creates a Checkout Session | customer/payment adapter regressions + Stripe adapter validator + MaggieDash npm test + board validation + `git diff --check` | passed |
+| BK-132 | Reconcile Stripe Checkout Sessions through the generic adapter | both | BK-128, BK-130, BK-131 | Create bounded-lifetime Checkout Sessions and retrieve `cs_` references through Stripe Checkout, mapping open/paid/expired states and provider references | Stripe adapter regressions + MaggieDash npm test + board validation + Booking Python tests + `git diff --check` | passed |
+| BK-133 | Preserve PaymentIntent references from asynchronous Checkout webhooks | both | BK-130, BK-132 | Normalize `checkout.session.async_payment_succeeded/failed` with the PaymentIntent reference when available, retaining the Session ID only as fallback | canonical/ORA runtime projection regression + disposable PostgreSQL 16 worker persistence integration + MaggieDash npm test + ORA contract check + board validation + Booking Python tests + `git diff --check` | passed |
+| BK-134 | Fulfill captured package purchases after sales are disabled | both | BK-096, BK-097 | Do not gate paid package webhook fulfillment on current sale availability; preserve active checks when starting new purchases | canonical Astro bootstrap + ORA contract regression + builds + board validation + Booking Python tests + `git diff --check` | passed |
+| BK-135 | Retry incomplete package fulfillment on duplicate webhooks | both | BK-134 | Re-run idempotent package settlement when a verified provider event is redelivered; only mark package events processed after fulfillment, and propagate failure so the provider retries | canonical/ORA duplicate retry runtime regression + host contract checks + MaggieDash `npm test` + ORA runtime/contract + board/Python validation + `git diff --check` | passed |
+| BK-136 | Require a validated manage token for closed-gate reschedule availability | both | BK-033, BK-113 | Remove raw query-token gate exemptions; permit closed-gate availability only after host validation of a bearer manage token for a reschedulable booking; keep the token out of the URL | canonical/ORA gate, customer-adapter and UI regressions + MaggieDash `npm test` + ORA `contract:check`, Astro check/build + task-board validation + `git diff --check` | passed |
+| BK-137 | Require validated tokens to render the closed-gate customer page | both | BK-104, BK-136 | Remove the raw query-token page exception; when the public gate is closed, render customer continuations only after validating one unexpired, unrevoked booking payment/manage token or package purchase token | canonical/ORA customer-adapter and route checks + MaggieDash `npm test` and host bootstrap + ORA `contract:check`, Astro check/build + task-board validation + `git diff --check` | passed |
+| BK-138 | Require manage-purpose tokens for customer cancellation and rescheduling | both | BK-060, BK-137 | Require an unexpired, unrevoked manage token scoped to the requested booking before cancel/reschedule mutations and before returning an idempotent replay | canonical/ORA customer-adapter regressions for payment, expired, revoked, wrong-booking and revoked replay denial + MaggieDash `npm test` + ORA `contract:check`, Astro check/build + task-board validation + `git diff --check` | passed |
+| BK-139 | Align the reference customer host with payment/manage token boundaries | MaggieDash | BK-035, BK-138 | Issue separate short-lived payment and 30-day manage tokens; expose manage access only after a valid payment return; validate manage purpose, expiry, revocation, and booking scope before mutation replay | reference-host journey covers token purpose/lifetimes, payment-token and wrong-booking denial, revoked replay denial + MaggieDash `npm test` + task-board validation + `git diff --check` | passed |
+| BK-140 | Fail closed on expired package return tokens in reference hosts | both | BK-035, BK-137 | Reject missing, expired, or malformed-expiry package return tokens before purchase reads/reconciliation, and synchronize canonical/ORA manifest-projected fixture host and validator | canonical and ORA customer-reference-host revoked/expiry regressions + byte parity + MaggieDash `npm test` + ORA `contract:check` + AI-CMO Booking tests + task-board validation + `git diff --check` | passed |
+| BK-141 | Use venue-local time throughout manager booking workflows | both | BK-021, BK-028 | Render appointment instants and interpret manager create, waitlist conversion, reschedule, and dated shift/time-off/closure datetime-local fields in each selected location timezone; reject DST gaps, expose fold choices, disable nonexistent calendar slots, and order dated schedule intervals by UTC instant | Venue-time conversion and schedule UI regressions + MaggieDash `npm test` + ORA Booking UI/contract/build + Booking Python tests + board validation + source parity + `git diff --check` | passed |

package/bundled-references/maggiedash-booking/VOUCHERS.md

@@ -0,0 +1,47 @@
+# Gift voucher lifecycle
+
+**Status:** contract only — MaggieDash ships no voucher runtime in this release.
+**Contract:** `contracts/maggiedash/booking-voucher-lifecycle-v1.json`
+**Validator:** `maggie booking voucher-contract [--ledger FIXTURE]`
+
+Stripe has no native gift-card resource (see
+[Stripe integration](./STRIPE-INTEGRATION.md#gift-cards-credits-and-referrals)).
+A host that sells vouchers therefore owns a local, append-only ledger, and a
+Stripe payment only *funds* an online voucher. This contract fixes the
+provider-neutral lifecycle so every host implements the same rules instead of
+designing them from scratch.
+
+## Lifecycle
+
+| Concern | Rule |
+|---|---|
+| Sale online | Checkout/PaymentIntent funds the voucher; it stays `pending_payment` until the verified payment webhook, then the `issue` entry records `paymentRef`. |
+| Sale in shop (till) | Staff with `vouchers.sell` record the in-shop payment method (`cash`, `card-terminal`, `external`); the voucher is active immediately. |
+| Code format | Online: `PREFIX-XXXX-XXXX-XXXX` from an unambiguous alphabet, last segment a truncated HMAC under a server-only secret, checked in constant time before any lookup. Till: prefix + digits with a Luhn check digit. Store only `codeHash` and `codeLast4`; the full code appears only in the delivery email. |
+| Partial redemption | Any positive amount up to the remaining balance; the remainder stays redeemable. |
+| Undo | `undo_redeem` reverses one earlier `redeem` by id, same amount, at most once, never after void. |
+| Void | Requires a reason; blocks every later redemption, undo, and refund. |
+| Expiry | No redemption at or after `expiresAt`; an `expire` entry records the unused balance. The expiry policy is declared by the host for its jurisdiction. |
+| Refund | Capped by the remaining balance and by the funded amount minus earlier refunds. Online refunds reference the original provider payment (a Stripe Refund); till refunds record `refundMethod`. A full refund before any redemption moves the voucher to `refunded`. |
+| Emails | `voucher.purchase.confirmed` (buyer), `voucher.delivered` (recipient), `voucher.redeemed`, `voucher.refunded`, `voucher.expiry_reminder`, delivered through the host outbox. |
+| Merchant ledger | Append-only `issue`, `redeem`, `undo_redeem`, `void`, `expire`, `refund` entries with actor, timestamp, and idempotency key; every mutation is audited and tenant-scoped. |
+
+States: `pending_payment`, `active`, `exhausted`, `expired`, `voided`,
+`refunded`. Money is integer minor units, one currency per voucher.
+
+## Proving a host implementation
+
+Export a sanitized `maggiedash-booking-voucher-ledger.v1` fixture (no full
+codes, secrets, or customer PII) and replay it:
+
+```bash
+maggie booking voucher-contract
+maggie booking voucher-contract --ledger path/to/voucher-ledger.json
+```
+
+The replay rejects a negative balance, over-redemption, redemption after void
+or expiry or before payment, a second undo of the same redemption, refunds
+above the balance or funded amount, online refunds without a payment
+reference, and declared `status`/`balance` values that disagree with the
+ledger. `fixtures/maggiedash/booking-voucher-ledger.v1.json` in the source
+repository is a passing example.

package/bundled-references/provider-adapter-contract.md

@@ -150,6 +150,39 @@ image-processing contract: optimisation may use Cloudflare Images
 transformations, Astro build tooling or a provider-specific implementation
 behind the same interface.
 
+## OAuth connections
+
+A provider connection is only as reliable as its weakest connect path:
+
+- Each adapter declares one canonical OAuth scope set. Every client that
+  starts the flow (dashboard, mobile app, CLI) requests exactly that set.
+  LinkedIn invalidates a member's earlier tokens when a later sign-in asks for
+  a different scope set, so a mobile app that omits `email` silently revokes
+  the dashboard's token while the database still says `active`.
+- Prefer one OAuth client per product. When a client ID is shared with other
+  products or callbacks, record it as `client_shared_with`; their sign-ins can
+  revoke this product's tokens unless they use the identical scope set.
+- Treat stored connection status as a cache. A token that the provider has
+  revoked, or that the serving host cannot decrypt, is `needs_reconnect`
+  before anything is scheduled on it — not when a post fails.
+- Provider media URLs (for example `media.licdn.com` with an `e=` expiry) are
+  signed and expire. Cache the bytes in owned storage or refresh on readback.
+
+`maggie tool maggie_social_share.py adapters` and `connections` check these
+rules from a redacted JSON manifest; see the Social Share skill for shapes.
+
+## Structured model output
+
+Keep structured-output schemas small. Gemini rejected a JSON schema whose enum
+had 125 values with `400 INVALID_ARGUMENT`, and the caller silently fell back
+for every request. For a large vocabulary (styles, categories, catalogue IDs):
+
+1. ask for a free string (optionally with a short list of examples in the
+   prompt) instead of a large `enum`;
+2. validate the returned value server-side against the authoritative list;
+3. treat a schema rejection or an unknown value as a visible, counted failure —
+   never a silent fallback to a default.
+
 ## Adding a provider
 
 1. Implement the relevant interface in `src/lib/providers/`.

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

@@ -373,6 +373,14 @@ node scripts/maggie-booking-schema.mjs --apply --confirm
 node scripts/maggie-booking-worker.mjs --write --confirm
 ```
 
+Before switching Stripe to live mode, follow the read-only live setup runbook
+in `docs/maggiedash-booking/STRIPE-INTEGRATION.md`: verify with list/retrieve
+calls only, never use a create call as a probe, have the owner install
+webhook and event-destination signing secrets with a no-echo command, and hand
+Dashboard-only steps to the owner. Gift vouchers follow the host-owned
+`booking-voucher-lifecycle-v1.json` contract; validate a host ledger with
+`maggie booking voucher-contract --ledger FIXTURE`.
+
 The dry-run executes the complete additive migration in a transaction and
 rolls it back, which verifies PostgreSQL permissions without changing data.
 The apply command commits the migration as one transaction.