@topy-ai/maggie 0.7.36 → 0.7.37

package/bundled-contracts/maggiedash/stripe-booking-capabilities-v1.json

@@ -0,0 +1,68 @@
+{
+  "$id": "https://maggiedash.topy.ai/contracts/stripe-booking-capabilities-v1.json",
+  "schemaVersion": "maggiedash-stripe-booking-capabilities.v1",
+  "provider": "stripe",
+  "scope": "booking-and-business-operations",
+  "x-source": "MaggieDash/contracts/stripe-booking-capabilities-v1.json",
+  "x-last-verified-at": "2026-09-20",
+  "x-api-version-policy": {
+    "accountScoped": true,
+    "pinServerVersion": true,
+    "upgradeInSandbox": true,
+    "avoidChargesForNewFlows": true
+  },
+  "x-api-matrix": [
+    { "id": "customers", "status": "core", "resource": "Customer", "operations": ["POST /v1/customers", "GET /v1/customers/:id", "POST /v1/customers/:id"], "bookingUse": "customer mapping and receipts", "officialDocs": ["https://docs.stripe.com/api/customers"] },
+    { "id": "checkout_sessions", "status": "core", "resource": "Checkout Session", "operations": ["POST /v1/checkout/sessions", "GET /v1/checkout/sessions/:id", "POST /v1/checkout/sessions/:id/expire"], "bookingUse": "hosted or embedded one-off booking payments", "officialDocs": ["https://docs.stripe.com/api/checkout/sessions"] },
+    { "id": "payment_intents", "status": "core", "resource": "PaymentIntent", "operations": ["POST /v1/payment_intents", "GET /v1/payment_intents/:id", "POST /v1/payment_intents/:id/confirm", "POST /v1/payment_intents/:id/cancel", "POST /v1/payment_intents/:id/capture"], "bookingUse": "custom payment UI, SCA, capture, reconciliation", "officialDocs": ["https://docs.stripe.com/api/payment_intents"] },
+    { "id": "setup_intents", "status": "optional", "resource": "SetupIntent", "operations": ["POST /v1/setup_intents", "GET /v1/setup_intents/:id", "POST /v1/setup_intents/:id/confirm"], "bookingUse": "consented saved payment methods", "officialDocs": ["https://docs.stripe.com/api/setup_intents"] },
+    { "id": "refunds", "status": "core", "resource": "Refund", "operations": ["POST /v1/refunds", "GET /v1/refunds/:id", "POST /v1/refunds/:id/cancel"], "bookingUse": "full and partial refunds", "officialDocs": ["https://docs.stripe.com/api/refunds"] },
+    { "id": "events", "status": "core", "resource": "Event", "operations": ["GET /v1/events/:id", "GET /v1/events"], "bookingUse": "event identity and reconciliation", "officialDocs": ["https://docs.stripe.com/api/events", "https://docs.stripe.com/api/events/types"] },
+    { "id": "promotion_codes", "status": "optional", "resource": "Promotion Code", "operations": ["POST /v1/promotion_codes", "GET /v1/promotion_codes/:id", "GET /v1/promotion_codes"], "bookingUse": "campaign and referral discount codes", "officialDocs": ["https://docs.stripe.com/api/promotion_codes"] },
+    { "id": "coupons", "status": "optional", "resource": "Coupon", "operations": ["POST /v1/coupons", "GET /v1/coupons/:id", "DELETE /v1/coupons/:id"], "bookingUse": "reusable discounts", "officialDocs": ["https://docs.stripe.com/api/coupons"] },
+    { "id": "customer_balance_transactions", "status": "optional", "resource": "Customer Balance Transaction", "operations": ["POST /v1/customers/:id/balance_transactions", "GET /v1/customers/:id/balance_transactions"], "bookingUse": "invoice credit, not gift-card redemption", "officialDocs": ["https://docs.stripe.com/api/customer_balance_transactions"] },
+    { "id": "subscriptions", "status": "future", "resource": "Subscription", "operations": ["POST /v1/subscriptions", "GET /v1/subscriptions/:id", "POST /v1/subscriptions/:id"], "bookingUse": "future memberships", "officialDocs": ["https://docs.stripe.com/api/subscriptions"] },
+    { "id": "invoices", "status": "future", "resource": "Invoice", "operations": ["POST /v1/invoices", "GET /v1/invoices/:id", "POST /v1/invoices/:id/finalize"], "bookingUse": "future business invoicing", "officialDocs": ["https://docs.stripe.com/api/invoices"] },
+    { "id": "customer_portal_sessions", "status": "future", "resource": "Billing Portal Session", "operations": ["POST /v1/billing_portal/sessions"], "bookingUse": "future customer self-service billing", "officialDocs": ["https://docs.stripe.com/api/customer_portal/sessions"] },
+    { "id": "tax", "status": "optional", "resource": "Tax Calculation/Transaction", "operations": ["POST /v1/tax/calculations", "POST /v1/tax/transactions/create_from_calculation", "POST /v1/tax/transactions/create_reversal"], "bookingUse": "optional VAT/tax calculation", "officialDocs": ["https://docs.stripe.com/tax/payment_intent", "https://docs.stripe.com/api/tax/transactions"] },
+    { "id": "terminal", "status": "future", "resource": "Terminal PaymentIntent", "operations": ["POST /v1/terminal/readers", "POST /v1/terminal/readers/:id/process_payment_intent"], "bookingUse": "future in-person payments", "officialDocs": ["https://docs.stripe.com/terminal/payments"] },
+    { "id": "connect", "status": "future", "resource": "Connected Account", "operations": ["POST /v1/accounts", "POST /v1/account_links", "POST /v1/transfers"], "bookingUse": "future multi-merchant platforms only", "officialDocs": ["https://docs.stripe.com/connect"] }
+  ],
+  "x-webhook-events": [
+    { "eventType": "checkout.session.completed", "requiredFor": "hosted checkout completion", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "checkout.session.async_payment_succeeded", "requiredFor": "delayed payment completion", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "checkout.session.async_payment_failed", "requiredFor": "delayed payment failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "payment_intent.processing", "requiredFor": "payment pending", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "payment_intent.payment_failed", "requiredFor": "payment failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "payment_intent.succeeded", "requiredFor": "payment confirmation", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "payment_intent.requires_action", "requiredFor": "customer action", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "payment_intent.canceled", "requiredFor": "payment cancellation", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "refund.created", "requiredFor": "refund projection", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "refund.updated", "requiredFor": "refund status changes", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "refund.failed", "requiredFor": "refund failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "setup_intent.succeeded", "requiredFor": "saved method setup", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "setup_intent.setup_failed", "requiredFor": "saved method failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "invoice.paid", "requiredFor": "future recurring billing", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "invoice.payment_failed", "requiredFor": "future recurring billing failure", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "customer.subscription.updated", "requiredFor": "future membership state", "officialDocs": ["https://docs.stripe.com/api/events/types"] },
+    { "eventType": "customer.subscription.deleted", "requiredFor": "future membership cancellation", "officialDocs": ["https://docs.stripe.com/api/events/types"] }
+  ],
+  "x-native-capabilities": {
+    "giftCards": "not-native",
+    "referrals": "not-native",
+    "discountCodes": "native",
+    "customerBalanceCredits": "native",
+    "subscriptions": "native",
+    "tax": "native",
+    "terminal": "native",
+    "connect": "native"
+  },
+  "x-ecosystem-integrations": [
+    { "id": "gift-up", "category": "gift-cards", "kind": "stripe-app", "status": "evaluate", "officialDocs": ["https://marketplace.stripe.com/apps/gift-up"], "maggieDecision": "separate partner gift-card system; retain local reference and reconciliation" },
+    { "id": "partnerstack", "category": "affiliate-and-referrals", "kind": "stripe-app", "status": "evaluate", "officialDocs": ["https://marketplace.stripe.com/apps/partnerstack"], "maggieDecision": "affiliate payout candidate; local referral attribution remains authoritative" },
+    { "id": "stripe-apps", "category": "business-operations", "kind": "stripe-product", "status": "recommended", "officialDocs": ["https://stripe.com/apps"], "maggieDecision": "prefer reviewed apps for accounting, CRM, support, analytics, and automation" },
+    { "id": "stripe-tax", "category": "tax", "kind": "stripe-product", "status": "evaluate", "officialDocs": ["https://docs.stripe.com/tax"], "maggieDecision": "enable only after jurisdiction and tax ownership review" },
+    { "id": "stripe-terminal", "category": "in-person-payments", "kind": "stripe-product", "status": "future", "officialDocs": ["https://docs.stripe.com/terminal"], "maggieDecision": "future reader operations" },
+    { "id": "stripe-connect", "category": "multi-merchant", "kind": "stripe-product", "status": "future", "officialDocs": ["https://docs.stripe.com/connect"], "maggieDecision": "future platform-only capability" }
+  ]
+}

package/bundled-skills/README.md

@@ -6,6 +6,7 @@ Skills are the agent-facing workflows. They compose with the tools in
 | Skill | Primary job | Dependencies |
 |---|---|---|
 | `maggie-blog-bootstrap` | Build a complete blog in an existing project | site audit, analytics, API Pull |
+| `maggie-booking` | Install and validate the MaggieDash manager workspace, public customer-flow boundary, lifecycle, payment, notification, and runtime gates | MaggieDash Booking contracts, host database/provider adapter |
 | `maggie-dash` | Initialize and operate the provider-neutral MaggieDash foundation, content store, and approval lifecycle | MaggieDash contracts, project adapter |
 | `maggie-clone` | Reverse-engineer authorized URLs into namespaced blog-project pages | browser MCP, clone planner CLI, bootstrap state |
 | `maggie-clone-to-template` | Turn an authorized URL and prompt into a validated marketplace package | marketplace CLI, screenshot QA, design contract |

package/bundled-skills/catalog.json

@@ -14,6 +14,10 @@
       "name": "maggie-blog-bootstrap",
       "description": "Establish a MaggieDash-backed Astro blog or complete a small SEO/GEO-ready blog in an existing project."
     },
+    {
+      "name": "maggie-booking",
+      "description": "Plan, install, validate, and release the MaggieDash provider-neutral Booking workspace at _maggie/booking. Use for manager booking operations, availability/hold contracts, payment reconciliation, or integrating a host adapter."
+    },
     {
       "name": "maggie-clone",
       "description": "Reverse-engineer an authorized website homepage and create the Maggie homepage foundation inside an existing blog project. Use with /maggie-clone plus a homepage URL when the user wants to replicate the homepage structure, header, footer, assets, responsive behavior, and interactions."

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

@@ -0,0 +1,462 @@
+---
+name: maggie-booking
+description: Plan, install, validate, and release the MaggieDash provider-neutral Booking workspace at _maggie/booking. Use for manager booking operations, availability/hold contracts, payment reconciliation, or integrating a host adapter.
+---
+
+# Maggie Booking
+
+Use this skill for the MaggieDash transactional Booking workspace, not only
+for importing a provider's service catalogue. The existing
+[`maggie-service-booking`](../maggie-service-booking/SKILL.md) skill remains the
+right choice for provider-backed services, prices, durations, booking links,
+and factual provider validation.
+
+## Contract and safety boundary
+
+Read [`../../docs/maggiedash-booking/README.md`](../../docs/maggiedash-booking/README.md),
+[`TASKS.md`](../../docs/maggiedash-booking/TASKS.md), and the task's linked
+reference before changing code. MaggieDash owns the manager UI and versioned
+contracts. The host owns routes, traditional email/password sessions,
+PostgreSQL connection/transaction lifetime, tenant authorization, provider
+credentials, payment webhooks, notifications, and deployment. MaggieDash also
+ships a tenant-scoped PostgreSQL manager repository for catalogue, availability,
+booking, customer, configuration, schedule, health, audit, hold, and lifecycle
+persistence; it does not replace host connection ownership or payment/public-
+checkout adapters.
+
+For implementation work, use the leaf board and runbook:
+[`EXECUTION-BOARD.json`](../../docs/maggiedash-booking/EXECUTION-BOARD.json)
+and [`TASK-RUNBOOK.md`](../../docs/maggiedash-booking/TASK-RUNBOOK.md). Do not
+mark a task passed until its implementation gate, docs update, and evidence
+record are complete.
+
+Never put provider secrets, database credentials, payment card data, or a
+customer export in UI props, browser bundles, fixtures, screenshots, or
+feedback. A payment return URL is not proof of payment; only a verified
+provider webhook or server-side provider read may advance payment state.
+
+## Stable commands
+
+Run read-only checks before any host migration or external mutation:
+
+```bash
+maggie booking inspect --project .
+maggie booking contract
+maggie booking runtime-validate --project . \
+  --evidence .maggie/booking-runtime.json
+maggie booking release-gate --project . --require-runtime \
+  --evidence .maggie/booking-runtime.json
+maggie booking stripe-audit --project .
+maggie booking access-contract
+maggie booking email-templates-contract
+maggie booking tasks validate
+maggie booking tasks list
+```
+
+The final gate must include every evidence class:
+
+```bash
+maggie booking release-gate --project . --require-runtime \
+  --evidence .maggie/booking/runtime-evidence.json \
+  --require-browser --browser-evidence .maggie/booking/browser/evidence.json \
+  --require-ops --ops-evidence .maggie/booking/ops-evidence.json \
+  --require-board
+```
+
+`--require-ops` validates sanitized backup/restore, alert-routing, and
+recovery-rehearsal evidence together with the runtime/browser/board gates.
+It applies the host-only evidence rule; fixture, test, and local environments
+cannot satisfy a required operational release artifact.
+
+For local CLI regression, the sanitized no-customer fixture is
+[`fixtures/maggiedash/booking-runtime.v1.json`](../../fixtures/maggiedash/booking-runtime.v1.json).
+
+Install the first-party workspace and the host integration through the stable
+Booking installer:
+
+```bash
+maggie booking install --project . --confirm
+```
+
+For a host project that does not already contain the Booking runtime packages,
+let the installer add only the missing dependencies through the package manager
+already declared by the project (`npm`, `pnpm`, `yarn`, or `bun`):
+
+```bash
+maggie booking install --project . --confirm --install-dependencies
+```
+
+This is an explicit dependency mutation. It preserves existing package
+versions, updates the matching lockfile, and never installs a second copy of a
+package already present in `dependencies` or `devDependencies`.
+
+The default installer source is the public MaggieDash distribution. It must
+contain the released Astro `hostBootstrap` manifest and 39-route Booking
+source. While validating an unreleased local checkout, pass
+`--source /home/balalior/Dev/MaggieDash`; do not present a local-source result
+as proof that the public npm install path is released.
+
+For a new host with a reviewed `DATABASE_URL`, the explicit one-command
+bootstrap also applies the idempotent Booking schema:
+
+```bash
+maggie booking install --project . --confirm --bootstrap
+```
+
+`--bootstrap` is intentionally opt-in: take the host backup/migration decision
+first. It runs the installed `scripts/maggie-booking-schema.mjs` with
+`--apply --confirm`. When the host uses a local `.env`, it also generates
+`BOOKING_TOKEN_SECRET` when the key is absent. The value is never printed and
+an existing value is never replaced; a configured value shorter than 32
+characters fails closed. External secret stores must provision the same key
+separately. Bootstrap still does not create the owner, configure Stripe, send
+email, or deploy.
+
+Before changing host configuration, run the safe first-run checklist:
+
+```bash
+maggie booking setup --project .
+```
+
+The checklist reports whether the installed workspace, Astro middleware, and
+required environment keys are present. It also lists the explicit schema,
+first-owner, Stripe webhook, and Resend-worker steps. It never prints secret
+values, connects to PostgreSQL, applies migrations, creates an account, sends
+email, configures Stripe, or deploys. A `configured-pending-verification`
+result means static configuration is present but host runtime evidence is still
+required. The checklist also rejects a `BOOKING_TOKEN_SECRET` shorter than 32
+characters and marks a one-sided Stripe key pair as degraded, so a
+present-but-unusable secret cannot be mistaken for a ready installation.
+
+Validate the installable staff-login boundary independently before touching a
+database or provider:
+
+```bash
+maggie booking access-contract
+```
+
+This checks the versioned access contract for administrator-only account
+creation, email/password invitations through Resend, `manager`/`staff`/
+`finance` roles, granular permissions, password reset, revocation, audit
+actions, tenant scoping, and disabled-account protection. It does not create
+accounts or send email.
+
+Validate the tenant-scoped Resend template boundary independently:
+
+```bash
+maggie booking email-templates-contract
+```
+
+This freezes the seven supported Booking events, approved `{{variable}}`
+placeholders, owner/admin/manager access, audit and idempotency requirements,
+and the server-only provider/recipient privacy boundary. It does not connect to
+Resend, send a message, or expose customer data.
+
+After the first owner signs in, the Booking Overview includes the same
+secret-safe readiness path: Stripe connection status, test/live mode, and a
+copyable `/api/maggie/booking/webhooks/stripe` URL. It gives the operator the
+next secret-store action without accepting or storing Stripe credentials in the
+browser or Booking database.
+
+For an Astro host, framework detection installs missing email/password login,
+first-owner registration, manager/public Booking routes, PostgreSQL/Stripe
+adapter wiring, the `/_maggie` rewrite, a schema command, Resend worker, and
+`.env.maggie-booking.example`. It also installs the Booking access API: an
+owner or administrator can create email/password staff, manager, and finance
+accounts, link them to staff profiles, and set explicit route capabilities.
+The permissions are enforced in the server route handler, not only hidden in
+the UI. Use `--host astro` to make detection explicit;
+use `--host none` when only the source distribution is wanted. The
+distribution keeps the content admin at `./_maggie/admin` and Booking source at
+`./_maggie/booking`. Existing files, including an existing `src/middleware.ts`,
+are preserved unless `--force` is explicitly supplied. A conventional Astro
+middleware receives the rewrite block automatically; unsupported middleware is
+preserved and reported by `maggie booking inspect` until integrated manually.
+Installation does not apply SQL, create an owner, or enable a payment provider.
+The standard Booking migration must create
+`maggiedash_booking_user_roles`; do not move that table into a project-only
+extension, or a fresh install can authenticate the owner but cannot resolve a
+Booking session.
+
+The Schedule screen manages working hours, staff shifts, time off, and location
+closures through the audited schedule contract. Managers can search and edit
+existing rules by stable ID; each write preserves the full schedule snapshot
+and removes only the selected row before applying its replacement, so unrelated
+availability rows cannot be deleted by an ordinary edit.
+
+The Catalogue screen supports searchable service/treatment management. Select
+an existing service to edit its stable variant ID, label, duration, price,
+currency, payment policy, or active/inactive state. These writes still go
+through the same idempotent, audited `catalog.json` endpoint; the UI does not
+create replacement records for ordinary edits.
+
+Staff and Resources have the same edit-safe workflow. Managers can select an
+existing profile or resource, update assignments, bookable/active state,
+capacity, and identity fields, then save through the existing audited
+`staff.json` or `resources.json` endpoint without changing the record ID.
+
+Manager-created bookings use live tenant configuration: the form selects an
+active service variant, location, staff member, or resource, and refuses to
+submit without a staff/resource allocation. Do not reintroduce free-text ID
+fields as the primary path; PostgreSQL booking creation requires the allocation
+to be explicit.
+
+The installer must supply those selectors from tenant data, not fixture IDs.
+The manager catalogue response includes active locations, the schedule response
+includes staff-visible locations, new forms default from the first bootstrapped
+location/service, and resource writes persist their service assignments. Keep
+the UI regression gate that rejects `location-1` and `service-1` fallbacks.
+
+For a blank project, configure the first location before services, staff,
+resources, or schedules. The Booking Locations screen uses the audited
+`GET/POST /api/maggie/booking/locations.json` boundary to create or edit a
+tenant location, including IANA timezone, locale, address, active state, and
+online-booking availability. Do not require a seeded venue ID or make the host
+invent one in the browser; the location write must remain tenant-scoped,
+permission-checked, idempotent, and validated server-side.
+
+A booking can contain up to 12 treatment segments. Each segment carries its
+own service variant, start/end interval, price, currency, and staff/resource
+allocation; all segments must use one location and currency, pass server-side
+availability checks, and persist with their allocations in the same transaction.
+The manager form exposes this with `Add treatment` and `Remove treatment`. A
+direct host request uses `segments: [{ serviceVariantId, startAt, endAt,
+staffId|resourceId, priceMinor, currency }]` and remains idempotent.
+
+The public customer page supports the same bounded multi-treatment shape. It
+requests availability for the combined duration, shows the estimated total,
+creates one hold with ordered segments, and converts it into one booking. A
+token-bound customer or manager reschedule shifts every segment and its
+allocation by the same time delta, checks each staff/resource interval, and
+preserves the original total duration. Single-treatment requests and legacy
+rows remain compatible. Public DTOs expose only safe segment fields.
+
+Every `staff` account must also be linked to a Booking staff profile. The host
+passes that `staff_id` into the server context, and the PostgreSQL repository
+filters bookings, calendar, availability, customer summaries, staff/resources,
+schedule, and lifecycle mutations by that assignment. An unlinked staff
+session fails closed. This is a data-security rule, not a UI convention.
+The bootstrap now uses the host's server-side Resend configuration to send
+single-use invitation and password-reset links; raw tokens are never stored.
+The Resend worker separately delivers booking notifications. The default
+worker cycle includes `match-waitlist` and `enqueue-reminders`. The waitlist
+matcher orders eligible entries by priority/FIFO, requires explicit service and
+location scope, persists the offered slot, and queues one
+`booking.waitlist.available` notification. It never auto-creates or reserves a
+booking. The reminder job queues one `booking.reminder`
+email for each confirmed booking in the next 24 hours; the existing Resend
+dispatcher resolves the customer address at delivery time. Reminder queueing
+is idempotent, skips bookings without a customer email, and does not itself
+prove delivery until the host worker reports Resend acceptance. Booking
+checkout creates a short-lived payment-return token and a separate 30-day
+sealed customer-manage token. The worker reuses or creates the manage token
+for confirmation, reschedule, cancellation, and reminder emails, and places
+only the safe URL in the email HTML; raw tokens are never written to the
+outbox.
+
+The Booking workspace also provides an Email templates screen. Owner,
+administrator, and Booking manager sessions can edit a tenant draft, preview it
+with sandboxed sample data, publish a new audited version, or roll back to a
+prior version. Templates are restricted to the event-specific allowlist and
+values are escaped before the Resend worker renders them. A published template
+is resolved by `project_id` and event; if none exists, the safe provider-neutral
+fallback is used. Resend credentials and recipient addresses remain
+host/worker-only.
+
+Payment policy is configured on the service variant and carried onto the
+booking snapshot. The supported modes are `full`, `deposit`, `pay_later`, and
+`no_payment`. Payment attempts must declare `deposit`, `balance`, `full`, or
+`adjustment` purpose. The worker and payment adapter aggregate captured
+attempts plus refunds into paid and balance-due amounts; never infer payment
+truth from a browser redirect or only the latest attempt. A duplicate command
+must replay before current-balance validation.
+
+After the setup checklist is clear, the intended first-run path for an already
+installed host is:
+
+```bash
+node scripts/maggie-booking-schema.mjs --dry-run
+node scripts/maggie-booking-schema.mjs --apply --confirm
+# open /_maggie/register and create the first owner
+# add Stripe and Resend secrets through the deployment secret store
+node scripts/maggie-booking-worker.mjs --write --confirm
+```
+
+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.
+
+The worker should run from a scheduler with a single-flight lock. Do not run
+the schema command or worker against production until the host's backup,
+migration, Stripe, Resend, and release-evidence gates have passed.
+
+It also installs the reviewable runtime starter under `maggiedash/backend/booking`,
+the runtime/browser contracts, `maggiedash/ops/`, safe fixtures, and protected
+GitHub workflow templates. Run the local worker in dry-run mode:
+
+```bash
+npm run booking:worker -- --job all
+```
+
+To preview only the reminder decision without sending email:
+
+```bash
+npm run booking:worker -- --job enqueue-reminders
+```
+
+To preview only the automatic waitlist matching decision:
+
+```bash
+npm run booking:worker -- --job match-waitlist
+```
+
+The source-level domain and host-boundary checks are also available:
+
+```bash
+npm run booking:domain:test
+npm run booking:service:test
+npm run booking:schema:validate
+npm run booking:postgres-core-repository:test
+npm run booking:postgres-manager-methods:test
+npm run booking:postgres-payment-adapter:test
+npm run booking:postgres-backup-restore:integration -- \
+  --source-database-url "$DATABASE_URL" \
+  --restore-database-url "$RESTORE_DATABASE_URL" \
+  --pg-bin-dir "$PG_BIN_DIR" --confirm
+```
+
+The backup/restore command requires two explicitly named disposable or
+approved databases and an empty restore database with no public application
+tables. It verifies the PostgreSQL client tools before `pg_dump`: `pg_dump`
+and `pg_restore` must be the same major version and match or exceed both
+server major versions. Use `--pg-bin-dir` when the matching client is not the
+default `PATH`; otherwise a version-mismatch error provides the corrective
+command. It compares protected Booking table counts afterward, never drops
+either database, and rejects a non-empty target before restore.
+
+The real PostgreSQL cycle is intentionally not read-only. Run it only against
+an explicitly disposable or approved staging database:
+
+```bash
+npm run booking:postgres-core-repository:integration -- \
+  --database-url "$DATABASE_URL" --confirm
+```
+
+For local contract/browser development, MaggieDash also provides a fixture-only
+reference host. It is never a production adapter:
+
+```bash
+npm run booking:reference-host:test
+npm run booking:reference-host -- --port 4175
+```
+
+For production, pass a host module with `loadState`, `saveState`, and
+`dispatchNotification` to `run-booking-jobs.mjs --adapter`; do not point a
+production service at the JSON fixture.
+
+## Implementation order
+
+Follow the task board rather than building a disconnected calendar first:
+
+1. Confirm the host adapter, tenant, role, timezone, error, idempotency, and
+   capability decisions.
+2. Run migration preflight; review backup/restore and `btree_gist` privileges.
+3. Install the Booking workspace and expose the host route with the same
+   email/password session as the admin workspace.
+4. Compose `createPostgresBookingCoreRepository` for tenant-scoped manager
+   reads, configuration writes, and booking/hold/lifecycle writes; run its
+   manager-method gate and explicit disposable/staging PostgreSQL integration
+   command. Verify staff assignment scope with a linked staff session before
+   exposing the dashboard to staff users.
+5. Compose `createPostgresBookingPaymentRepository` with an injected gateway
+   for payment start/reconcile/refund persistence. Keep provider calls outside
+   its short database transaction; inject verified webhook, public checkout,
+   notification, and runtime-evidence adapters separately. The MaggieDash
+   repositories must not call provider SDKs or read secrets.
+6. Add the provider-neutral payment port and a test-mode adapter. Reconcile
+   signed duplicate/out-of-order webhooks before enabling capture.
+7. Run the UI source gate, contract gate, host runtime conformance, browser
+   journeys, and release gate. Record each command in
+   [`PROGRESS.md`](../../docs/maggiedash-booking/PROGRESS.md).
+
+8. Verify the scheduled worker queues and delivers a reminder once for a
+   confirmed booking inside the 24-hour window. Check the notification
+   idempotency key, Resend provider response, retry/dead-letter state, and
+   absence of duplicate sends before enabling customer reminders.
+
+For a production-like staff rollout, verify the account lifecycle end to end:
+Resend invitation email, first-login password setup, password reset, session
+revocation after reset/deactivation, and an authenticated browser test for each
+permission profile. The host still owns delivery retries and production
+evidence.
+
+## Runtime evidence
+
+`runtime-validate` accepts sanitized observations only. Each endpoint must
+report its contract ID, method, route, 2xx status, and whether required fields
+were present. The validator also requires exact endpoint cardinality, an ISO
+timestamp, a dedicated tenant, and no sensitive evidence keys. Do not include
+request bodies, tokens, customer PII, provider payloads, local paths, or
+database details in evidence.
+
+The MaggieDash source package also provides `npm run booking:runtime:plan:test`
+to validate a host runtime plan before credentials are used. It covers all
+contract endpoint IDs, concrete path parameters, required query parameters,
+explicit mutation bodies, and unknown-route rejection.
+
+The UI must visibly handle loading, empty, error, permission-denied,
+provider-outage, and capability-disabled states. A static JSON contract is not
+runtime proof; capture browser evidence after the host route and session are
+actually wired.
+
+## Customer surface
+
+When the product needs customer self-booking, use the separate
+`MaggieDash/contracts/booking-customer-surface-v1.json` contract and
+`backend/booking/customer-route-handler.mjs`. It covers public-noindex
+catalogue/availability, short-lived holds, checkout start, payment-return
+recovery, token-bound customer-manage history, customer cancellation, and
+basic waitlist joining when no suitable slot is available. Use
+`backend/booking/customer-flow.mjs` for redacted public
+DTOs, input validation, bounded payment-return states, and allowlisted
+notification intents.
+
+The installed `booking/src/customer.tsx` and
+`maggiedash/adapters/astro/customer-booking-page.astro` provide the optional
+public `/_maggie/booking/book` UI for catalog, availability, hold, checkout,
+pending payment-return recovery, token-bound rescheduling, token-bound
+cancellation, customer-manage history, and waitlist joining when availability
+is empty. Validate it with
+`npm run booking:customer-ui:test`; the host still owns the public route,
+tenant binding, abuse controls, and payment/email adapters.
+
+The public handler does not use the manager session. The host must inject a
+tenant-bound context and enforce origin/CSRF, rate-limit, bot, token-codec,
+provider, and notification controls. Compose the installable
+`postgres-customer-adapter.mjs` with the manager/payment repositories when
+PostgreSQL persistence is needed; it stores token hashes, token purpose, and
+sealed ciphertext, never raw bearer tokens. Payment-return tokens are
+short-lived while customer-manage tokens are 30-day links. A redirect is never
+payment proof.
+Run `npm run booking:customer-flow:test` in MaggieDash before wiring the
+adapter, and retain real host/runtime/browser evidence as a separate gate.
+The manager Booking UI also exposes the tenant-scoped waitlist queue. Managers
+can filter entries, notify/cancel/reprioritize them, or select a concrete slot
+and staff/resource allocation to create a real booking transaction linked by
+`convertedBookingId`. The worker also performs bounded priority/FIFO matching
+for explicitly scoped slots and queues a Resend availability notification; the
+customer must still claim the live slot, so it never auto-reserves a booking.
+
+For a deterministic end-to-end public journey before host wiring, also run
+`npm run booking:customer-reference-host:test`. This validates the fixture
+reference host only; it is not production tenant, payment, or notification
+evidence.
+The host's idempotency store must compare a normalized request hash: identical
+retries replay the original result, while reusing a key with a different
+payload fails with a conflict and never replays the wrong booking.
+
+## Completion
+
+A Booking task is complete only when implementation, its gate, docs, and the
+dated progress entry all pass. The release gate is intentionally read-only: it
+does not run migrations, create bookings, capture/refund payments, or deploy.

package/bundled-tools/clis/maggie.py

@@ -963,6 +963,13 @@ def command_feedback(args: argparse.Namespace) -> int:
     return completed.returncode
 
 
+def command_booking(args: argparse.Namespace) -> int:
+    """Dispatch Booking contract checks through the canonical Booking CLI."""
+    cli = Path(__file__).with_name("maggie_booking.py")
+    completed = subprocess.run([sys.executable, str(cli), *args.booking_args], cwd=Path.cwd(), check=False)
+    return completed.returncode
+
+
 def parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="maggie", description=__doc__)
     sub = p.add_subparsers(dest="command", required=True)
@@ -1017,6 +1024,9 @@ def parser() -> argparse.ArgumentParser:
     feedback = sub.add_parser("feedback", help="collect, review, and submit privacy-safe feedback")
     feedback.add_argument("feedback_args", nargs=argparse.REMAINDER, help="arguments for maggie_feedback.py")
     feedback.set_defaults(func=command_feedback)
+    booking = sub.add_parser("booking", help="inspect and validate the MaggieDash Booking workspace")
+    booking.add_argument("booking_args", nargs=argparse.REMAINDER, help="arguments for maggie_booking.py")
+    booking.set_defaults(func=command_booking)
     doctor = sub.add_parser("doctor", help="check blog routes and SEO output invariants")
     doctor.add_argument("project", nargs="?", default=".")
     doctor.add_argument("--require-bootstrap", action="store_true")