@topy-ai/maggie 0.7.38 → 0.7.41

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

@@ -0,0 +1,542 @@
+# ai-cmo-skills support for Booking
+
+This document turns the architecture into stable, repeatable checks for
+Maggie users and implementers. Commands marked implemented are shipped in
+`tools/clis/maggie_booking.py`; commands that need a real host runtime remain
+explicit host-evidence gates and fail closed when that evidence is absent.
+
+Current release baseline: MaggieDash `0.2.8`, commit `9d99de7` on
+`origin/main`; the working tree includes the BK-100 dashboard-managed Stripe
+connection slice and BK-099 cancellation-safe
+package-credit restoration
+extension. The local implementation and validators pass; the remaining
+runtime/browser/ops evidence is tracked as BK-030/BK-031/BK-032 in the
+[execution board](./EXECUTION-BOARD.json).
+
+The installer fetches MaggieDash from its public GitHub source by default. A
+fresh disposable Astro project was installed without `--source`, then passed
+the installed host validator and `maggie booking inspect`; the public install
+contains the 47-route Booking release, worker, schema, Astro host scaffold, and
+blank-host SSR adapter/config fallback.
+
+## 1. Existing support
+
+### `maggie-service-booking`
+
+Current support includes:
+
+- provider catalogue import and sync;
+- service, variant, price, duration, provider URL, and provenance validation;
+- provider capability audit using sanitized fixtures;
+- timezone-aware appointment input validation;
+- worker/resolver evidence checks;
+- booking-aware service-page generation gates;
+- retirement and notification lifecycle contracts.
+
+This is useful for catalog bootstrap and provider facts. It does not create a
+local transactional booking engine, native availability, payment webhooks, or
+manager booking screens.
+
+### `maggie-dash`
+
+Current support includes:
+
+- dashboard installation and diff planning;
+- host adapter conformance evidence;
+- migration preflight;
+- UI/runtime evidence and panel audits;
+- provider-neutral MaggieDash schema and dashboard contracts.
+- manager-created multi-treatment appointments with per-segment service,
+  time, price, staff/resource allocation, same-location/currency validation,
+  transactional persistence, and idempotent replay.
+- public multi-treatment customer holds and checkout with combined-duration
+  availability, safe segment DTOs, summed pricing, and segment-safe
+  token-bound rescheduling.
+- blank-project location setup through the tenant-scoped Locations screen and
+  `locations.json` route, before catalogue/staff/resource/schedule setup.
+- tenant-scoped prepaid treatment package catalogue management through the
+  `packages.json` read/write routes and Packages screen, plus customer package
+  entitlement grants, balance reads, and transactional manager/public-customer
+  redemption through `customer-packages.json` and public hold/checkout. Public package checkout,
+  Stripe reconciliation/webhook fulfillment, manager purchase listing, and
+  guarded package refunds are now separate payment flows.
+
+The current installer keeps `_maggie/admin` as the dashboard target and can
+auto-detect an Astro host. Booking host bootstrap is non-destructive: it adds
+missing auth/routes/adapter/schema/worker files and idempotently merges the
+Booking/login/register/reset rewrite block into a conventional existing
+`src/middleware.ts` without replacing host auth or redirects.
+
+### Related existing skills
+
+| Skill | Booking relationship |
+|---|---|
+| `maggie-project-context` | records project, domain, provider, and deployment decisions |
+| `maggie-auth-reference` | keeps email/password session and server-only provider credentials consistent |
+| `maggie-ops` | supplies operational dashboard, audit, health, and recovery patterns |
+| `maggie-deployment` | carries migration, runtime, and release evidence into deployment |
+| `maggie-qa-workflow` | validates browser behavior and host evidence |
+| `maggie-memory` | records durable implementation learnings only after confirmation |
+| `maggie-service-booking` | supplies catalogue/provider facts and booking-link fallback |
+
+## 2. Implemented skill surface
+
+The general skill is:
+
+```text
+maggie-booking
+```
+
+Implemented responsibilities:
+
+1. inspect the installed workspace, root artifacts, adapter, and schema;
+2. validate the provider-neutral host contract and email/password boundary;
+3. validate the administrator-only Booking access contract for staff roles,
+   granular permissions, Resend invitations, password reset, and revocation;
+4. validate sanitized runtime endpoint observations;
+5. run a read-only release gate over the installed workspace and contract;
+6. record failures through the existing feedback/memory workflow without
+   writing active memory automatically.
+
+The skill must not auto-enable native booking or payment writes. Applying a
+migration, configuring a provider, or changing public booking behavior remains
+an explicit confirmation step.
+
+## 3. Stable CLI
+
+The implementation lives under `tools/clis/maggie_booking.py` and is dispatched
+by `tools/clis/maggie.py`.
+
+### Inspect and plan
+
+```bash
+maggie booking install --project . --confirm
+maggie booking install --project . --host astro --dry-run
+maggie booking install --project . --confirm --install-dependencies
+maggie booking install --project . --confirm --bootstrap
+maggie booking install --project . --confirm --bootstrap --schedule systemd
+maggie booking worker-schedule --project . --scheduler cron --confirm
+maggie booking inspect --project .
+maggie booking setup --project .
+maggie booking access-contract
+maggie booking email-templates-contract
+maggie booking contract
+```
+
+`maggie booking install` delegates to the MaggieDash distribution installer.
+For Astro it installs the manager/public pages, email/password login and
+first-owner registration, server-side PostgreSQL/Stripe adapter, middleware
+rewrite, schema command, Resend worker, and `.env.maggie-booking.example`.
+The default `--host auto` only selects Astro when `package.json` or `src/**/*.astro`
+proves it. Existing files are preserved; `--force` is required to replace
+them. A conventional existing middleware is merged automatically, including
+the common destructured `defineMiddleware(({ url, request }, next) => {})`
+form; an unsupported middleware shape is preserved, recorded in install state, and
+causes `maggie booking inspect` to fail until the rewrite is integrated.
+The command still does not apply SQL, create an account, send an email, or
+configure Stripe.
+
+`--install-dependencies` is an explicit host mutation for a fresh Astro
+project. It detects the existing npm/pnpm/yarn/bun lockfile and adds only the
+missing React, Phosphor, Tailwind, PostgreSQL, Stripe, and SSR adapter packages
+required by the Booking scaffold. A blank Astro host gets `@astrojs/node` and
+an `astro.config.mjs` server config; a host with an existing
+`astro.config.*`/deployment adapter keeps that host-owned choice. It is
+incompatible with `--dry-run`, `--diff`, and without `--confirm`; existing
+dependency versions are preserved.
+
+For a new host where the database migration has already been reviewed and
+approved, `--ready` is the convenience form of
+`--install-dependencies --bootstrap`:
+
+```bash
+maggie booking install --project . --confirm --ready
+```
+
+It installs missing host packages, creates the implementation-only booking
+token when the local environment permits it, and applies the idempotent
+Booking schema. It does not create the first owner, configure Stripe, send a
+Resend email, enable systemd/cron, or deploy. `--ready --schedule systemd`
+or `--ready --schedule cron` only writes reviewable scheduler artifacts.
+
+For a blank project, complete setup in this order after the schema and owner
+exist: create the first location in Booking → Locations, then add services and
+treatments, staff/resources, and schedule rules. The location form validates
+the IANA timezone and keeps the write idempotent; it does not depend on
+`location-1` or another fixture ID.
+
+`--bootstrap` is the explicit exception for a reviewed new host: after the
+files are installed, it runs the host-provided
+`scripts/maggie-booking-schema.mjs --apply --confirm` from the project with the
+existing environment. When the host uses a local `.env`, it generates the
+implementation-only `BOOKING_TOKEN_SECRET` if absent, never replaces an
+existing value, and refuses a configured value shorter than 32 characters.
+External secret stores must be provisioned separately. It still does not
+create an owner, configure Stripe, send email, or deploy. Do not use it before
+backup/migration approval.
+
+`--schedule systemd` generates a reviewed `deploy/maggie-booking-worker.service`
+and `.timer`; `maggie booking worker-schedule --scheduler cron` generates a
+cron artifact instead. These commands do not edit crontab, enable systemd, or
+start a worker. Review the service user and enable the scheduler only after
+schema, backup/restore, and host evidence gates pass.
+
+The installed host schema command also supports a safe permission preflight:
+
+```bash
+node scripts/maggie-booking-schema.mjs --dry-run
+```
+
+It runs the core schema and Booking schema first, then applies an optional
+`maggiedash/schema/host-extensions.sql` supplied by the host, all inside a
+transaction that is rolled back. This catches missing PostgreSQL permissions
+such as `btree_gist` without changing the host database; only
+`--apply --confirm` commits the migration.
+
+All commands in this section are read-only. `inspect` reports whether
+`_maggie/booking`, the installed manager and public customer contracts, the
+starter schema, runtime/customer-flow validators, and the installer state
+exist. `setup` adds a safe first-run checklist for required environment-key
+presence and explicit next steps for schema application, first-owner
+registration, Stripe webhooks, and the Resend worker. It never prints secret
+values and does not connect to PostgreSQL or mutate the host. It validates the
+32-character minimum for `BOOKING_TOKEN_SECRET`, reports a partially
+configured Stripe key pair as degraded, and reports a complete pair as
+`online-payments-pending-verification` until the signed-in manager runs the
+server-side Verify Stripe connection action.
+`setup` reports a complete deployment Stripe key pair as
+`online-payments-pending-verification`; when no deployment Stripe keys are
+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.
+`contract` accepts both the source contract JSON Schema and the compact
+ai-cmo-skills contract representation. It never reads secrets or customer data.
+
+`email-templates-contract` validates the tenant-scoped Resend template
+boundary: ten event keys, including package purchase confirmation/refund and
+no-show fee notification,
+event-specific `{{variable}}` allowlists,
+owner/admin/manager access, audited idempotent mutations, 50,000-character
+HTML limits, and the rule that provider credentials and recipient data remain
+server-only. It is a static contract check; it does not send email.
+
+Maintainers must also validate the artifact that npm users will receive, not
+only the source checkout:
+
+```bash
+node scripts/validate-cli-package.mjs
+node scripts/validate-cli-package.mjs --project /home/balalior/Dev/clients/orawellness.uk
+```
+
+After publishing, verify the package served by npm rather than relying only
+on the local tarball:
+
+```bash
+node scripts/verify-published-cli.mjs --version 0.7.39
+```
+
+`scripts/publish-npm.mjs` runs this registry verification automatically after
+`npm publish`; it fails the release if the published Booking contracts are
+stale or incomplete.
+
+This regenerates the bundled contracts/tools, packages the Booking runbook and
+sanitized runtime fixture, rewrites repository-only links, packs the exact npm
+tarball, and runs the packaged `booking contract`, access, email-template,
+task-board, and optional host-inspect checks. It is read-only with respect to
+hosts and never publishes the package.
+
+The installer inspector accepts both contract representations used by the
+distribution: the compact installed form and the JSON Schema source form with
+`properties` plus endpoint inventory. This keeps a fresh MaggieDash source
+install and an installed project on the same auth, endpoint, idempotency, and
+privacy checks.
+
+The installed Booking manager workspace includes an Email templates screen.
+Managers can edit a draft, inspect a sandboxed preview, publish a new version,
+and roll back a prior version. The worker resolves the latest published row by
+project and event, then falls back to the provider-neutral template when no
+tenant override exists. Template values are escaped before the Resend request;
+the outbox remains responsible for retry, dead-letter, and replay state.
+
+The worker cycle also runs `match-waitlist` between availability refresh and
+reminder enqueue. It requires explicit service/location scope in the worker
+availability snapshot; the Astro scaffold accepts
+`BOOKING_WAITLIST_SERVICE_VARIANT_ID`, `BOOKING_WAITLIST_LOCATION_ID`,
+`BOOKING_WAITLIST_SERVICE_NAME`, and `BOOKING_WAITLIST_LOCATION_NAME`. Matching
+is priority-first with FIFO tie-breaking, persists a one-time offered slot, and
+only queues `booking.waitlist.available`; it never auto-creates or reserves a
+booking.
+
+### Runtime and release gates
+
+```bash
+maggie booking runtime-validate --project . \
+  --contract maggiedash/contracts/booking-host-adapter-v1.json \
+  --evidence .maggie/booking-runtime.json
+
+maggie booking release-gate --project . --require-runtime \
+  --contract maggiedash/contracts/booking-host-adapter-v1.json \
+  --evidence .maggie/booking-runtime.json
+```
+
+`runtime-validate` requires one sanitized 2xx observation for every declared
+endpoint, exact endpoint cardinality, an ISO timestamp, a dedicated tenant,
+and no sensitive evidence keys. `release-gate` verifies the contract,
+installed workspace, starter schema, and optional/required runtime evidence. It
+fails closed when `--require-runtime` is used. It does not run migrations,
+create bookings, capture/refund payments, or deploy.
+
+Before a host session is used, `npm run booking:runtime:plan:test` checks that
+the runtime plan covers every contract endpoint, uses concrete path parameters
+where needed, retains required query parameters, supplies mutation bodies, and
+rejects routes outside the `/api/maggie/booking` contract.
+
+The public customer contract has its own source/install validator:
+
+```bash
+npm run booking:customer-flow:test
+```
+
+It covers public DTO redaction, catalog/availability, hold input, pending
+payment-return recovery, notification intents, no-store/noindex responses,
+mutation idempotency, and fail-closed tenant binding. It does not claim that a
+host has configured rate limits, bot controls, a payment provider, or email
+delivery.
+
+The customer reference-host validator additionally exercises a two-treatment
+hold, combined-duration availability, summed checkout pricing, and a
+token-bound multi-treatment reschedule. PostgreSQL-core validation verifies
+that the manager repository shifts each segment and allocation independently;
+these are lifecycle regressions, not production-host evidence.
+
+The manager UI configuration gate also verifies install-time data binding:
+catalog reads expose tenant locations, schedule reads expose staff-visible
+locations, and staff/resource forms derive service/location defaults from those
+responses. It rejects the old fixture `location-1`/`service-1` fallbacks, which
+would make a fresh host appear installed while posting IDs that do not exist in
+the tenant database.
+
+Exercise the full public journey against the secret-free reference host:
+
+```bash
+npm run booking:customer-reference-host:test
+```
+
+This checks the public catalog, availability, hold replay, checkout pending
+state, payment-return recovery, token-bound cancel, manager-session isolation,
+and notification intents. It does not replace real host evidence.
+
+Validate the host-owned operational proof separately:
+
+```bash
+maggie booking ops-validate --evidence .maggie/booking/ops-evidence.json
+```
+
+The ops evidence contract requires sanitized proof for backup/restore,
+delivery of all seven stable health alert codes, and a recovery rehearsal
+(rollback write guard, worker restart, and outbox replay). The command checks
+the artifact only; it does not run a backup, page an operator, or mutate the
+host. Use `--require-host` for a release artifact; it rejects fixture, test,
+and local environments and requires every timestamp/boolean proof field.
+The installed MaggieDash package also ships the manual
+`.github/workflows/booking-ops-evidence.yml` workflow for validating a
+sanitized host artifact from an environment-scoped secret.
+
+For the final release gate, require that proof explicitly:
+
+```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` fails closed until the sanitized operational artifact passes
+the versioned ops contract. This keeps BK-030 evidence in the same final
+decision as the runtime, browser, and execution-board gates.
+
+When an explicitly supplied runtime, browser, or ops artifact is missing or
+malformed, `release-gate` returns a structured `blocked` JSON result with the
+affected evidence status set to `failed` and an actionable read error. It does
+not crash before printing the release decision, which keeps CI artifacts and
+task progress machine-readable.
+
+The browser portion also requires the 390/768/1440 viewport set, safe
+screenshots, ready routes, empty console/request errors, and an empty
+`layoutErrors` array for horizontal overflow.
+
+The MaggieDash source repository also exposes the implementation gates used by
+the task board:
+
+```bash
+npm run booking:ui:test
+npm run booking:security:test
+npm run booking:route-handler:test
+npm run booking:service-contract:test
+npm run booking:worker-adapter:test
+npm run booking:postgres-repository:test
+npm run booking:health:test
+```
+
+With a disposable or approved staging PostgreSQL URL and a host-installed
+`pg` dependency, run the real repository cycle:
+
+```bash
+npm run booking:postgres-repository:integration -- \
+  --database-url "$DATABASE_URL" --confirm
+```
+
+The integration gate creates and removes one uniquely-prefixed test tenant; it
+must never target an unapproved production database.
+
+The backup/restore rehearsal is a separate explicit two-database command. It
+requires an empty target database with no public application tables, rejects a
+non-empty target without modifying it, does not clean either database, and
+compares protected table row counts after a custom-format dump and restore.
+`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 first client on `PATH`:
+
+```bash
+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 route-handler gate covers the reusable host HTTP boundary. It dispatches
+all 47 contract routes while checking email/password session lookup,
+role/project scope, idempotency headers, JSON parsing, safe errors, and raw
+webhook forwarding. A host still injects its repository/service and provider
+verifier.
+
+The service-contract gate covers the installed host seam: every one of the 47
+manager endpoint IDs must map to one injected service method, the repository
+transaction surface must be declared, and the eleven public customer methods must
+remain separate from the manager session boundary. The installed manager
+method gate also protects the 29 database-backed PostgreSQL methods while
+keeping payment SDK and webhook methods injected. `maggie booking inspect` and
+`release-gate` fail when the installed type contract, service/manager
+validators, or PostgreSQL core repository artifact is missing.
+
+The source package also ships `npm run booking:postgres-payment-adapter:test`
+and `postgres-payment-adapter.mjs`. It persists normalized provider results
+without importing an SDK; the host still injects the gateway and verified
+webhook handler.
+
+The public persistence seam is `postgres-customer-adapter.mjs`; its validator
+protects sealed customer tokens, public DTOs, checkout/payment-return state,
+and token-bound cancellation. A host must still supply the token key and
+public abuse/security controls.
+
+After a protected host run, make browser evidence part of the release gate:
+
+```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
+```
+
+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 board gate additionally fails closed until every task in
+`docs/maggiedash-booking/EXECUTION-BOARD.json` is `passed`; use `--board` to
+inspect a different board.
+
+The installed MaggieDash package provides the host runtime commands separately:
+
+```bash
+npm run booking:worker -- --job all
+node maggiedash/scripts/capture-booking-runtime-evidence.mjs \
+  --base-url https://booking.example.test \
+  --plan .secrets/booking-runtime-plan.json \
+  --storage-state .secrets/booking-storage-state.json \
+  --output .maggie/booking/runtime/evidence.json \
+  --confirm
+node maggiedash/scripts/validate-booking-runtime-evidence.mjs \
+  .maggie/booking/runtime/evidence.json
+node maggiedash/scripts/capture-booking-browser-evidence.mjs \
+  --base-url https://booking.example.test \
+  --storage-state .secrets/booking-storage-state.json \
+  --output .maggie/booking/browser/evidence.json
+node maggiedash/scripts/validate-booking-browser-evidence.mjs \
+  .maggie/booking/browser/evidence.json \
+  .maggie/booking/browser
+```
+
+The worker is fixture-safe and dry-run by default. Its report includes a
+correlation ID, `waitlistMatched`, and sanitized health codes for lock
+contention, stale worker or availability state, payment lag, notification
+retries, and dead letters. A real host must inject the PostgreSQL/provider/
+notification adapter and route the health result to its alerting system using
+the systemd, cron, or platform scheduler template from MaggieDash.
+
+The remaining host evidence is tracked in [`TASKS.md`](./TASKS.md): PostgreSQL
+transaction/lock integration, full host conformance, and protected browser
+release evidence. The local UI, security, payment, notification, and worker
+adapter gates are implemented; they do not replace real-host evidence.
+
+The runtime capture plan is host-owned and must cover all 47 contract endpoint
+IDs. It requires a dedicated test tenant, a traditional email/password session
+cookie, explicit mutation bodies, and `--confirm`. The generated evidence only
+contains canonical endpoint IDs/routes, status codes, and required-field
+booleans; it never stores response bodies, cookies, request bodies, or provider
+payloads. The protected workflow is
+`.github/workflows/booking-runtime-evidence.yml`.
+
+## 4. Workflow phases
+
+The existing Maggie bootstrap phase model can be extended with booking-specific
+phases without changing the general bootstrap contract:
+
+```text
+booking-discovery
+  -> booking-contract
+  -> booking-schema
+  -> booking-availability
+  -> booking-payments
+  -> booking-dashboard
+  -> booking-qa
+  -> booking-release
+```
+
+Each phase has `pending`, `running`, `passed`, or `failed`, a validation command,
+an owner, and a safe evidence path. A later phase cannot pass when an earlier
+required phase is pending or failed.
+
+## 5. Feedback and memory integration
+
+When a booking skill run fails:
+
+1. Generate a local feedback draft with skill, Maggie version, workflow/run ID,
+   phase, fingerprint, expected/actual result, command, and safe evidence paths.
+2. Let the user review and submit it through the existing feedback workflow.
+3. After maintainer triage, add the confirmed general fix to a regression test,
+   fixture, contract, or skill instruction.
+4. Only then write a durable memory entry. Never write a project-specific
+   preference or an unverified diagnosis directly to active memory.
+
+This keeps the Booking skill useful across projects without leaking one host's
+temporary configuration into another host.
+
+## 6. CLI design rules
+
+- Read-only by default.
+- `--confirm` for migrations, provider configuration, publication, or any
+  mutation.
+- `--project` defaults to `.` but all output paths are validated inside the
+  project.
+- JSON reports use explicit schema versions.
+- Reports contain hashes and counts rather than raw provider responses.
+- No CLI accepts a token as an argument.
+- No CLI reads secrets into generated reports.
+- Every failed check names the phase, stable error code, and next action.
+- Every successful check prints the exact fixture/contract/revision it verified.

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

@@ -0,0 +1,129 @@
+# Stripe integration audit
+
+**Verified:** 2026-09-20
+**Scope:** MaggieDash Booking payments and adjacent business operations
+**Status:** contract-ready; a host-specific Stripe adapter is still required
+
+This audit covers every Stripe resource used or proposed by the MaggieDash
+Booking boundary. It does not claim that every resource in Stripe's complete
+API is relevant to booking. The executable source of truth is the
+[`stripe-booking-capabilities-v1.json`](../../bundled-contracts/maggiedash/stripe-booking-capabilities-v1.json)
+contract, mirrored into the MaggieDash distribution.
+
+## Current integration decision
+
+MaggieDash has a provider-neutral payment port, a verified webhook boundary,
+idempotent event reconciliation, and a host-owned Stripe adapter seam. The
+adapter uses an injected official Stripe SDK factory, server-side credentials,
+the account's pinned API version, and a raw-body webhook signature check. The
+MaggieDash package itself still has no Stripe SDK dependency or secret.
+
+Booking customer IDs are tenant-local database identifiers, not Stripe
+customer references. The Astro host resolves each local customer through a
+stable tenant-scoped idempotency key, creates or reuses a Stripe Customer, and
+stores only `provider_customer_ref`. Checkout, PaymentIntent, and SetupIntent
+requests use that provider reference; a local UUID is never sent to Stripe as
+a `cus_*` value and the reference is not included in public DTOs.
+
+Stripe's public API documentation is account-aware: the account's API version
+and enabled capabilities are part of the effective contract. Do not copy a
+version date from a generic search result into application code. Pin the
+server SDK/API version, upgrade it in a sandbox, run conformance fixtures, and
+then approve the account upgrade. See [Stripe API versioning](https://docs.stripe.com/api/versioning)
+and the [API reference](https://docs.stripe.com/api).
+
+## API matrix
+
+| Capability | Status | MaggieDash use | Boundary |
+|---|---|---|---|
+| Customers | Core | Stable customer mapping, receipts, saved methods | Host owns PII and account scope |
+| Checkout Sessions | Core | Hosted or embedded deposits and one-off payments | Use one Session per payment attempt |
+| PaymentIntents | Core | Custom Payment Element, SCA, capture and reconciliation | Prefer this for new custom flows |
+| SetupIntents | Optional | Save a method with consent for later balance/no-show charges | Never charge without a local policy and consent |
+| Refunds | Core | Full/partial refund requests | Local refund row first; reconcile `refund.*` events |
+| Events/webhooks | Core | Idempotent payment state projection | Verify raw body before parsing |
+| Coupons + Promotion Codes | Optional | Campaign and referral discounts | Stripe applies the discount; local rules own eligibility |
+| Customer Balance Transactions | Optional | Stripe invoice credits | Not a gift-card ledger by itself |
+| Billing Subscriptions + Invoices | Future | Memberships or recurring plans | Add only when recurring booking is a product requirement |
+| Customer Portal | Future | Customer-managed subscriptions and billing details | Use short-lived portal sessions |
+| Stripe Tax | Optional | VAT/tax calculation and transaction records | Confirm jurisdiction, evidence, and price ownership |
+| Terminal | Future | In-person deposits/balances | Requires reader operations and device lifecycle |
+| Connect | Future | Multi-merchant/platform money movement | Not for a single business or multi-location tenant |
+
+The implementation maps Stripe's provider states into the existing normalized
+states (`requires_action`, `pending`, `failed`, `succeeded`, `cancelled`, and
+`refunded`). Stripe object names never become booking lifecycle states.
+
+## Webhook set
+
+The first adapter should subscribe only to events the configured capabilities
+need:
+
+- `checkout.session.completed`, `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
+  `payment_intent.canceled`;
+- `refund.created`, `refund.updated`, and `refund.failed`;
+- `setup_intent.succeeded` and `setup_intent.setup_failed` when saved methods
+  are enabled;
+- `invoice.paid`, `invoice.payment_failed`,
+  `customer.subscription.updated`, and `customer.subscription.deleted` only
+  when Billing is enabled.
+
+The [Stripe event type reference](https://docs.stripe.com/api/events/types) is
+the authoritative list and is continuously evolving. Unknown events are
+stored as safe unmatched events or ignored by policy; they must not mutate a
+booking merely because a webhook was received.
+
+## Gift cards, credits, and referrals
+
+Stripe has native discounts, customer balance credits, Billing, Tax, Terminal,
+and Connect. It does not expose a native `gift_card` or referral-program
+resource in the API surface reviewed here. Therefore:
+
+1. Gift cards should be either a MaggieDash domain ledger (with issue, redeem,
+   refund, expiry, and immutable transaction rows) or a separately reviewed
+   partner system. A successful Stripe payment funds issuance, but the local
+   gift-card ledger remains the redemption source of truth.
+2. Stripe Customer Balance is invoice credit, not a complete gift-card product.
+   It should not be used for checkout redemption, expiry, transfers, or
+   reconciliation without an explicit accounting decision.
+3. Referrals should be tracked locally: referrer, referred customer, qualifying
+   booking, reward state, reversal state, and idempotency key. Stripe
+   Promotion Codes/Coupons can apply the reward discount; they do not own the
+   referral attribution or qualification rule.
+4. For affiliate-style payouts, the [PartnerStack Stripe App](https://marketplace.stripe.com/apps/partnerstack)
+   is a candidate. For branded omnichannel gift cards, [Gift Up](https://marketplace.stripe.com/apps/gift-up)
+   is a candidate. These are partner apps, not native MaggieDash features, and
+   require permission, privacy, pricing, jurisdiction, and reconciliation
+   review before installation.
+
+The broader [Stripe Apps ecosystem](https://stripe.com/apps) is useful for
+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.
+
+## Recommended rollout order
+
+1. Stripe Customers + Checkout Sessions or PaymentIntents.
+2. Verified webhook reconciliation and Refunds.
+3. Optional SetupIntents for explicitly consented off-session charges.
+4. Coupons/Promotion Codes for campaigns; add local referral attribution.
+5. Stripe Tax if the host has the required tax configuration.
+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.
+
+Run the local contract gate with:
+
+```bash
+npm run booking:stripe:validate
+npm run booking:stripe-adapter:test
+maggie booking stripe-audit --contract /path/to/MaggieDash/contracts/stripe-booking-capabilities-v1.json
+```
+
+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.