@topy-ai/maggie 0.7.37 → 0.7.40

package/bundled-references/maggiedash-booking/HOST-ADAPTER.md

@@ -0,0 +1,314 @@
+# Booking host adapter contract
+
+This is the versioned screen-level contract for `/_maggie/booking`. It extends
+the current MaggieDash host adapter model rather than replacing it. The host
+continues to own routes, email/password sessions, database access, provider
+secrets, and deployment.
+
+## 1. Route and auth rules
+
+```text
+Public/customer booking: host-owned public route, no admin session required
+Manager UI: /_maggie/booking, host email/password session required
+Manager API: /api/maggie/booking/*, same-origin session required
+Provider webhooks: host server endpoint, provider signature required
+```
+
+The booking UI is `noindex,nofollow`. It uses the existing host-session cookie
+and role/membership checks. Passkeys and passwordless login are not part of this
+contract.
+
+When the session role is `staff`, the host must return the linked Booking
+`staffId` in the server-only session context. The repository then limits staff
+reads and lifecycle mutations to allocations and schedule/location records
+owned by that staff profile. A staff role without a linked profile is rejected;
+the browser must never be allowed to choose or override this scope.
+
+MaggieDash also ships a framework-neutral dispatcher at
+`backend/booking/route-handler.mjs`. Hosts can inject `createBookingService`
+plus their session lookup and verified webhook handler to obtain the complete
+47-route mapping with common JSON parsing, idempotency, project scope, role
+checks, correlation headers, and safe error responses. The host remains
+responsible for the actual repository, transaction, provider verification, and
+deployment. Validate the boundary with
+`npm run booking:route-handler:test` before wiring framework routes.
+
+Customer traffic uses a separate public-noindex dispatcher at
+`backend/booking/customer-route-handler.mjs`. It does not use the manager
+session. The host must bind the request to a tenant and apply origin/CSRF,
+rate-limit, bot, and opaque payment-return-token controls. Its DTO and
+notification boundary is in `backend/booking/customer-flow.mjs`.
+
+## 2. Proposed endpoints
+
+All JSON errors use:
+
+```json
+{
+  "error": "safe human-readable message",
+  "code": "stable.machine.code",
+  "correlationId": "corr_...",
+  "retryable": false
+}
+```
+
+| ID | Method | Route | Purpose |
+|---|---|---|---|
+| `booking.overview.read` | GET | `/api/maggie/booking/overview.json` | KPI cards, provider health, readiness, next bookings |
+| `booking.calendar.read` | GET | `/api/maggie/booking/calendar.json` | Day/week allocations and filters |
+| `booking.bookings.read` | GET | `/api/maggie/booking/bookings.json` | Search and paginated booking list |
+| `booking.booking.read` | GET | `/api/maggie/booking/bookings/{id}.json` | Detail, timeline, payments, notifications |
+| `booking.booking.create` | POST | `/api/maggie/booking/bookings.json` | Manager-created booking |
+| `booking.booking.transition` | POST | `/api/maggie/booking/bookings/{id}/transition.json` | Check-in, complete, cancel, no-show |
+| `booking.booking.no-show-fee` | POST | `/api/maggie/booking/bookings/{id}/no-show-fee.json` | Explicitly charge a consented, policy-derived no-show fee |
+| `booking.booking.reschedule` | POST | `/api/maggie/booking/bookings/{id}/reschedule.json` | Preview and apply a reschedule |
+| `booking.availability.read` | GET | `/api/maggie/booking/availability.json` | Calculate valid slots |
+| `booking.holds.create` | POST | `/api/maggie/booking/holds.json` | Create customer/manager hold |
+| `booking.holds.release` | POST | `/api/maggie/booking/holds/{id}/release.json` | Release a hold explicitly |
+| `booking.customers.read` | GET | `/api/maggie/booking/customers.json` | Search customers within scope |
+| `booking.customer.read` | GET | `/api/maggie/booking/customers/{id}.json` | Customer profile and safe history |
+| `booking.catalog.read` | GET | `/api/maggie/booking/catalog.json` | Services, variants, policies, readiness |
+| `booking.catalog.write` | POST | `/api/maggie/booking/catalog.json` | Create/update catalog draft |
+| `booking.packages.read` | GET | `/api/maggie/booking/packages.json` | Tenant-scoped prepaid treatment package catalogue |
+| `booking.package.write` | POST | `/api/maggie/booking/packages.json` | Create/update package price, expiry, and included treatments |
+| `booking.customer-packages.read` | GET | `/api/maggie/booking/customer-packages.json` | Read tenant/customer package balances and remaining visits |
+| `booking.customer-package.grant` | POST | `/api/maggie/booking/customer-packages.json` | Grant a package entitlement to an existing customer |
+| `booking.locations.read` | GET | `/api/maggie/booking/locations.json` | Tenant locations and setup state |
+| `booking.location.write` | POST | `/api/maggie/booking/locations.json` | Create/update location configuration |
+| `booking.staff.read` | GET | `/api/maggie/booking/staff.json` | Staff and eligibility |
+| `booking.staff.write` | POST | `/api/maggie/booking/staff.json` | Create/update staff configuration |
+| `booking.resources.read` | GET | `/api/maggie/booking/resources.json` | Resources and requirements |
+| `booking.resources.write` | POST | `/api/maggie/booking/resources.json` | Create/update resource configuration |
+| `booking.schedule.read` | GET | `/api/maggie/booking/schedule.json` | Hours, shifts, blocks, closures |
+| `booking.schedule.write` | POST | `/api/maggie/booking/schedule.json` | Save a validated schedule change |
+| `booking.payments.read` | GET | `/api/maggie/booking/payments.json` | Payment attempts, transactions, refunds |
+| `booking.payment.start` | POST | `/api/maggie/booking/payments/start.json` | Start a normalized payment attempt |
+| `booking.payment.reconcile` | POST | `/api/maggie/booking/payments/{id}/reconcile.json` | Request provider read/reconciliation |
+| `booking.refund.start` | POST | `/api/maggie/booking/refunds.json` | Start a full or partial refund |
+| `booking.notifications.read` | GET | `/api/maggie/booking/notifications.json` | Inspect redacted Resend delivery state |
+| `booking.notification.replay` | POST | `/api/maggie/booking/notifications/{id}/replay.json` | Replay one dead-letter notification with an audited reason |
+| `booking.payment-health.read` | GET | `/api/maggie/booking/payment-health.json` | Provider config and capability summary |
+| `booking.payment-health.verify` | POST | `/api/maggie/booking/payment-health.json` | Server-side Stripe account verification; owner/manager may submit credentials once, which are encrypted at rest |
+| `booking.settings.read` | GET | `/api/maggie/booking/settings.json` | Policy and integration settings, redacted |
+| `booking.settings.update` | PATCH | `/api/maggie/booking/settings.json` | Save non-secret settings |
+| `booking.audit.read` | GET | `/api/maggie/booking/audit.json` | Booking-scoped audit timeline |
+| `booking.events.read` | GET | `/api/maggie/booking/events.json` | Outbox/reconciliation operational view |
+| `booking.runtime.read` | GET | `/api/maggie/booking/runtime.json` | Sanitized screen/runtime evidence |
+| `booking.provider.webhook` | POST | `/api/maggie/booking/webhooks/{provider}` | Server-only verified provider event ingress |
+
+`booking.payment-health.verify` accepts `{ "provider": "stripe" }` for a
+deployment-managed connection. An owner or manager may instead include
+`secretKey` and `webhookSecret` in the same HTTPS request. The host verifies
+the pair before sealing it with `BOOKING_TOKEN_SECRET`; the values are never
+returned, logged, or included in the redacted payment-health response.
+
+### Booking permission registry
+
+The administrator-managed Team access contract exposes the complete
+server-enforced capability list: `calendar.read`, `bookings.read`,
+`bookings.manage`, `customers.read`, `waitlist.read`, `waitlist.manage`,
+`catalog.read`, `catalog.manage`, `packages.read`, `packages.manage`,
+`staff.read`, `staff.manage`, `resources.read`, `resources.manage`,
+`schedule.read`, `schedule.manage`, `locations.read`, `locations.manage`,
+`payments.read`, `payments.manage`, `refunds.manage`, `notifications.read`,
+`notifications.manage`, `settings.read`, `settings.manage`, `reports.read`,
+and `audit.read`. The UI receives the registry from `/access.json`; the route
+handler applies it server-side, so a hidden UI control cannot grant or bypass
+access. Owners and managers retain the full surface, while staff and finance
+accounts require explicit capability entries.
+
+Webhook routes are not called by the browser and should be separate from the
+session-authenticated dashboard endpoint:
+
+```text
+POST /api/maggie/booking/webhooks/{provider}
+```
+
+### Public customer routes
+
+The eleven public routes are versioned separately in
+`MaggieDash/contracts/booking-customer-surface-v1.json`:
+
+| ID | Method | Route |
+|---|---|---|
+| `booking.public.catalog.read` | GET | `/api/maggie/booking/public/catalog.json` |
+| `booking.public.availability.read` | GET | `/api/maggie/booking/public/availability.json?serviceVariantId={serviceVariantId}&locationId={locationId}&date={date}` |
+| `booking.public.hold.create` | POST | `/api/maggie/booking/public/holds.json` |
+| `booking.public.checkout.start` | POST | `/api/maggie/booking/public/checkout.json` |
+| `booking.public.payment-return.read` | GET | `/api/maggie/booking/public/payment-return.json` |
+| `booking.public.manage.read` | GET | `/api/maggie/booking/public/manage.json?token={token}` |
+| `booking.public.booking-cancel` | POST | `/api/maggie/booking/public/bookings/{id}/cancel.json` |
+| `booking.public.booking-reschedule` | POST | `/api/maggie/booking/public/bookings/{id}/reschedule.json` |
+| `booking.public.waitlist.join` | POST | `/api/maggie/booking/public/waitlist.json` |
+
+The public handler sets `no-store` and `X-Robots-Tag: noindex`, requires an
+idempotency key for writes, and fails closed if the host cannot bind a tenant.
+It returns only the redacted customer DTOs and payment-return states; a
+redirect cannot mark a payment paid. Use the existing outbox adapter for
+confirmation, cancellation, reschedule, and reminder email intents. The host
+stores customer token purpose explicitly: payment-return tokens are short-lived
+and the Resend worker uses a separate 30-day sealed `manage` token for links.
+
+For a deterministic end-to-end public journey, run:
+
+```bash
+npm run booking:customer-reference-host:test
+```
+
+This wraps the reference state with the public customer dispatcher and verifies
+hold replay, checkout-to-pending recovery, token-bound cancellation, manager
+session isolation, and notification intents. It is test evidence, never a
+production customer or payment host.
+
+## 3. Response shapes
+
+Overview:
+
+```json
+{
+  "date": "2026-09-20",
+  "timezone": "Europe/London",
+  "metrics": {
+    "bookings": 0,
+    "revenueMinor": 0,
+    "currency": "GBP",
+    "noShows": 0,
+    "balanceDueMinor": 0
+  },
+  "providerHealth": [],
+  "readiness": { "bookable": false, "checks": [] },
+  "nextBookings": [],
+  "correlationId": "corr_..."
+}
+```
+
+Availability:
+
+```json
+{
+  "query": {
+    "locationId": "loc_1",
+    "serviceVariantId": "variant_1",
+    "date": "2026-09-25",
+    "timezone": "Europe/London"
+  },
+  "slots": [
+    {
+      "startAt": "2026-09-25T09:00:00Z",
+      "endAt": "2026-09-25T10:00:00Z",
+      "localLabel": "10:00",
+      "staffIds": ["staff_1"],
+      "resourceIds": ["room_1"]
+    }
+  ],
+  "warnings": [],
+  "correlationId": "corr_..."
+}
+```
+
+Booking detail must include booking status and payment status separately, plus
+segments, allocations, safe timeline events, payment summary, allowed actions,
+and capability flags.
+
+## 4. Request rules
+
+- Mutations require a same-origin session and a role permission.
+- Mutations require `Idempotency-Key`; missing keys return `400`.
+- Requests carry `X-Correlation-Id` or receive a server-generated one.
+- JSON mutating requests declare `content-type: application/json`.
+- Server validates all IDs against tenant/location scope.
+- Server ignores client-supplied role, amount, currency, status, and provider
+  capability claims.
+- Mutations return the canonical persisted result, not the input echo.
+- Errors are safe, bounded, and do not include SQL, stack traces, provider
+  secrets, or raw webhook payloads.
+
+### Role-specific route boundary
+
+The shared route handler enforces the coarse role boundary and any explicit
+capabilities supplied on the session, while the host supplies the
+session-derived tenant, location, and assignment scope:
+
+- `staff` may read operational booking routes and transition assigned work to
+  `checked_in`, `in_progress`, `completed`, or `no_show`.
+- `staff` must be denied payment routes, payment-health details, customer
+  directory routes, configuration writes, and all other mutations.
+- `finance` may operate payment/refund routes and payment health, but does not
+  gain customer or configuration administration by implication.
+- The host must filter staff results to permitted locations and assignments
+  before the service returns list or detail DTOs. The shipped PostgreSQL
+  repository applies the standard `staff_id` assignment filter; custom host
+  repositories and reporting endpoints must preserve the same invariant.
+
+The source validator covers the coarse policy. A production host must add
+authenticated route and browser evidence proving its narrower tenant/location
+and assignment queries.
+
+The MaggieDash source includes a provider-neutral service seam in
+`backend/booking/request.mjs`, `dto.mjs`, and `service.mjs`. It is deliberately
+repository/transaction injected: the host supplies the PostgreSQL repository,
+session-derived project and role, clock, and provider adapter. The service
+returns canonical DTOs and the versioned safe error object; it does not import a
+database driver or payment SDK.
+
+## 5. Capability and feature flags
+
+```json
+{
+  "booking": {
+    "nativeAvailability": true,
+    "nativeBooking": true,
+    "waitlist": true,
+    "resources": true
+  },
+  "payment": {
+    "provider": "stripe",
+    "onlinePayment": true,
+    "refunds": true,
+    "partialRefunds": true,
+    "terminal": false,
+    "savedPaymentMethod": false
+  }
+}
+```
+
+Capabilities describe configured and verified behavior. They do not mean that
+an SDK is installed. A missing capability must result in a safe disabled state,
+not an invented UI action.
+
+## 6. Conformance evidence
+
+Add `booking.*` endpoints to a future version of the host-adapter contract and
+capture sanitized observations with the existing `maggie dash conformance`
+pattern. The evidence must include method, route, status, content type,
+required fields, and `passed`, but never cookies, authorization headers,
+provider payloads, or customer contact data.
+
+The release gate should also verify:
+
+- all booking screens mounted;
+- no public booking/admin route is indexable accidentally;
+- auth redirects work;
+- database migration version is current;
+- provider health is truthful;
+- payment fixtures and webhook fixtures pass;
+- browser screenshots have no overflow or console errors.
+
+## 7. Local reference host
+
+MaggieDash includes a secret-free, in-memory reference host for contract and
+browser development. It is not a production database adapter and must never be
+used to serve real customer or payment traffic.
+
+From the MaggieDash source repository:
+
+```bash
+npm run booking:reference-host:test
+npm run booking:reference-host -- --port 4175
+```
+
+The validator exercises all 47 endpoint IDs, required response fields,
+email/password-session presence, project scope, role scope, idempotent replay,
+provider webhook authentication, and fixture redaction. The local server is
+useful for wiring a browser route before a host supplies PostgreSQL and real
+provider adapters.

package/bundled-references/maggiedash-booking/ORAWELLNESS-INTEGRATION-AUDIT.md

@@ -0,0 +1,227 @@
+# ORA Wellness Booking integration audit
+
+Date: 2026-09-21
+Project: `/home/balalior/Dev/clients/orawellness.uk`
+Source: MaggieDash Booking `0.2.8` plus ORA host adapter
+
+## Short answer
+
+The host now has the main Fresha-style foundation: manager workspace, services,
+staff, resources, working hours, availability, holds, bookings, customer
+tokens, Stripe payment boundary, Resend notification outbox, audit records,
+email/password login, and separate Booking roles.
+
+It is not production-ready yet. The remaining work is deployment evidence and
+provider operations, not another UI shell.
+
+The ORA `.env` currently contains a Stripe test secret under the existing
+`ST_SECRECT_KEY` compatibility name and a publishable test key under
+`ST_PUB_KEY`. The secret value is intentionally not recorded here. No
+`STRIPE_WEBHOOK_SECRET` is configured yet, so the account is not considered
+verified or connected for Booking.
+
+Current database gate: the existing ORA application schema check passes and the
+Booking migration dry-run passes transactionally, but the live Booking schema
+has not been applied. The 2026-09-21 read-only preflight confirmed that the
+core schema exists while `maggiedash_booking_allocations` and
+`maggiedash_booking_user_roles` are still absent. The worker therefore fails
+closed without touching production data. Do not enable the live dashboard or
+scheduler until the owner approves the migration, verifies the backup/restore
+path, creates the first owner, and captures runtime evidence.
+
+## Verified in the codebase
+
+| Capability | Evidence | State |
+|---|---|---|
+| Manager dashboard | `/_maggie/booking`, `_maggie/booking/booking.tsx` | Installed |
+| Traditional authentication | `src/lib/maggie/auth.ts`, registration and login routes | Installed |
+| Booking roles | `maggiedash_booking_user_roles`, Staff access panel, complete server-enforced capability registry for calendar/bookings/customers/waitlist/catalogue/packages/staff/resources/schedule/locations/payments/refunds/notifications/settings/reports/audit | Installed; explicit staff/finance grants and safe legacy defaults covered by BK-101 |
+| Staff account lifecycle | Booking Staff panel creates accounts, sends Resend invitations, supports one-time password setup and password reset | Installed; real delivery/browser proof pending |
+| Staff data scope | Linked `staff_id` passed into the server context and filtered in the repository | Installed; host migration/staging proof pending |
+| Services/treatments | Searchable catalogue with editable service/variant details, payment policy, price, preparation/cleanup buffers, active/inactive state, manager multi-treatment appointments, public multi-treatment holds/checkout, and live service/location selectors | Installed; legacy allocation backfill and staging data verification pending |
+| Treatment packages | Tenant-scoped manager catalogue, manager-granted entitlements, public package checkout/payment return and fully covered public customer redemption, webhook fulfillment, balance reads, expiry checks, atomic redemption, cancellation-safe package-credit restoration, guarded refunds, and package confirmation/refund Resend outbox events | Installed locally; real Stripe/DB migration, webhook, Resend, and staging delivery proof pending |
+| Locations | Tenant-scoped Locations screen and `locations.json` route for first-location setup, timezone, locale, address, active state, and online-booking controls; public catalogue exposes all active online-booking locations | Installed; staging data verification pending |
+| Staff/resources | Editable staff profiles, service/location assignments, bookable state, resources, capacity, resource service assignments, and overlap constraints | Installed; staging data verification pending |
+| Calendar/availability | Day/week calendar, working hours, shifts, time off, closures, holds | Installed |
+| Booking defaults | Settings screen edits venue timezone/currency, pauses new booking writes, and selects automatic/manual capture policy | Installed; staging policy verification pending |
+| Stripe | Injected SDK gateway, account capability row, signed webhook boundary | Host-wired; staging proof pending |
+| Resend | Notification outbox plus `scripts/maggie-booking-worker.mjs` dispatcher, including a separate 30-day sealed customer-manage link | Host-wired; scheduled delivery proof pending; worker waits for Booking schema |
+| Notification operations | Tenant-scoped Notifications screen, redacted delivery-state list, and owner/manager-only dead-letter replay with reason/idempotency/audit controls | Installed; ORA validators/build passed; real delivery proof pending |
+| Public self-booking | `/_maggie/booking/book`, catalog/location selector, location-scoped combined-duration availability, multi-treatment hold/checkout, return, token-bound segment-safe reschedule/cancel, and 30-day customer-manage history | Installed; staging proof pending |
+| Waitlist | Public no-slot join, tenant-scoped manager queue, manual notify/cancel/priority actions, transactional conversion to a linked booking, priority/FIFO worker matching, and `booking.waitlist.available` Resend intent | Installed; explicit worker scope, real migration, scheduler, and delivery proof pending |
+| Reports | `/reports.json` plus Booking Reports screen with period/service/staff/location breakdowns | Installed; staging data verification pending |
+| Bookability readiness | Overview reports active location, catalogue variant, assigned bookable staff, working hours, overall bookable state, and payment capability | Installed; staging data verification pending |
+| Customer history | Searchable tenant-scoped manager directory plus token-bound public customer-manage history with redacted appointment summaries | Installed; staging data verification pending |
+| Schedule rules | Searchable/editable working hours, staff shifts, time off, and location closures through the audited schedule route | Installed; staging data verification pending |
+| 24-hour reminders | Worker queues one idempotent `booking.reminder` email into the Resend outbox for each eligible confirmed booking | Installed; scheduled Resend delivery evidence pending |
+| Payment policy and balance | Service-level full/deposit/pay-later/no-payment policy, purpose-labelled attempts, paid/balance projection, and refund projection | Installed; migration and Stripe staging evidence pending |
+| Payment truth | Verified webhook/provider read projects payment and booking state | Implemented; Stripe event test pending |
+| Legacy `/book` | Request-by-email flow | Kept as fallback |
+
+## Fixes made during this audit
+
+1. Public catalogue now returns all active online-booking locations plus a
+   backwards-compatible first `locationId`. The browser displays the tenant
+   locations, scopes availability to the selected location, and posts that
+   selected ID instead of using the fake `location-1` fallback.
+2. Public origin and rate-limit failures now return safe 403/429 responses.
+3. Stripe account status and capabilities are upserted into
+   `maggiedash_booking_payment_accounts`; no secret value is stored there.
+4. Webhook records store a SHA-256 payload hash instead of using the provider
+   event ID as a misleading hash.
+5. Customer cancellation queues the Booking notification through the same
+   Resend outbox.
+6. Customer rescheduling now uses the same sealed token, transactional
+   allocation conflict checks, idempotent replay, and `booking.rescheduled`
+   Resend outbox path as manager rescheduling.
+7. Customer checkout now creates a short-lived payment-return token and a
+   separate 30-day `manage` token. The Resend worker reuses or creates the
+   manage token for booking notifications without storing a raw token in the
+   outbox.
+8. Verified payment events now project `pending_payment` to `confirmed` and
+   `paid`, or cancel failed payment bookings and release their allocations,
+   before the worker acknowledges the event. Confirmation/cancellation
+   notifications are then queued once.
+9. Booking Staff can now create an email/password account directly, link its
+   staff profile, assign permissions, and resend a secure invitation without
+   using a separate People screen.
+10. Added the `/_maggie/reset-password` middleware rewrite so invitation and
+password-reset links resolve to the Astro reset page.
+11. Added a manager Overview setup checklist that reads the existing payment
+    health response, shows Stripe status and test/live mode, and provides a
+    copyable webhook URL without exposing provider secrets.
+12. Fixed the installed UI validator to resolve ORA's `_maggie/booking`
+    workspace instead of assuming a source-package `maggiedash/booking/src`
+    directory.
+13. Added provider-neutral automatic waitlist matching. The worker matches one
+    eligible waiting customer per explicit service/location slot, persists the
+    offered interval, and queues an idempotent Resend notification without
+    auto-reserving the appointment.
+14. Added the public `GET /api/maggie/booking/public/manage.json` history
+    surface. The existing 30-day Resend manage token now resolves the current
+    customer's tenant-scoped appointments through a redacted DTO; payment
+    tokens and manager credentials are not accepted by this endpoint.
+15. Added manager multi-treatment appointments. The form can compose up to 12
+    service segments, while the host validates duration, availability, shared
+    location/currency, per-segment staff/resource allocation, and persists the
+    segments and allocations atomically with the booking.
+16. Added public multi-treatment booking and segment-safe rescheduling. Customer
+    holds persist `segments_json`, checkout sums all treatment prices, and both
+    customer and manager rescheduling shift each segment/allocation together
+    while checking conflicts independently and preserving the total duration.
+17. Removed install-time `location-1`/`service-1` assumptions. Catalog and
+    schedule reads now return tenant locations; manager forms derive defaults
+    from those responses, and resource writes persist service assignments.
+18. Added tenant-scoped location management so a blank project can create its
+    first venue before configuring services, staff, resources, and schedules.
+    The same audited location contract is mirrored in ORA's installed Booking
+    workspace.
+19. Fixed a runtime catalogue query that referenced the nonexistent
+    `service_variants.created_at` column. Variant reads now use stable existing
+    columns for ordering. Hardened the ORA initial catalogue seed so a partial
+    retry reuses matching services and upserts variants instead of creating
+    duplicate services.
+20. Closed the treatment catalogue UI parity gap: the manager can now manage
+    every variant under a service, including duration, price, currency, and
+    active state, while preserving the existing idempotent backend write.
+
+## Installer productization update
+
+The MaggieDash distribution now declares an Astro host bootstrap. New Astro
+projects can use:
+
+```bash
+maggie booking install --project . --confirm
+```
+
+The installer adds missing Booking routes, email/password registration/login,
+PostgreSQL/Stripe adapter wiring, public booking route, middleware scaffold,
+schema command, Resend worker, and `.env.maggie-booking.example`. Existing
+host files are preserved. ORA already has host-owned versions of these files,
+so a repeat install should preserve ORA's middleware, auth, and adapter rather
+than overwrite them. Existing Astro middleware in either the full-context or
+common destructured-context form now receives the idempotent rewrite block;
+unknown middleware shapes remain fail-closed and are reported for manual review
+before the Booking URL is exposed.
+
+For hosts that use the installed Resend outbox and reminder worker, the CLI can
+also generate a reviewed scheduler artifact:
+
+```bash
+maggie booking install --project . --confirm --bootstrap --schedule systemd
+```
+
+The command writes the systemd service/timer under `deploy/` but does not
+enable or start it. Production still requires an approved service user,
+migration, backup/restore, alert routing, and authenticated runtime evidence.
+
+## Release blockers
+
+| Priority | Work | Why it matters | Owner |
+|---|---|---|---|
+| P0 | Apply `maggiedash-booking-install.sql` and host role migration on staging | Current ORA database check shows core MaggieDash tables exist, but Booking and Booking-role tables are not installed | ORA deployment |
+| P0 | Release the current MaggieDash source used by the default installer | The public `9d99de7` source is a validated `0.2.8` baseline, but the current 47-route/no-show changes remain uncommitted in the working tree | MaggieDash release owner |
+| P0 | Configure the Stripe webhook secret and verify the existing test account; keep `BOOKING_TOKEN_SECRET` and Resend sender available | The test secret is present through `ST_SECRECT_KEY`, but signed webhook verification and connected readiness remain unavailable | ORA deployment |
+| P0 | Run worker every minute with alerting | Holds, payment projections, and Resend delivery otherwise remain pending; `maggie booking worker-schedule` now generates the reviewed systemd/cron artifact, but host enablement and alert routing remain pending | ORA operations |
+| P0 | Capture authenticated runtime/browser/ops evidence | Local build and reference fixtures cannot prove the real host | ORA + release owner |
+| P1 | Run Stripe test-mode scenarios | Confirm success, failure, delayed/duplicate webhook, and refund behavior against the actual account | ORA + Stripe |
+| P1 | Capture Resend invitation/reset evidence | Booking notifications are wired; staff account invitation and password reset now use the same server-side Resend configuration | ORA + release owner |
+| P1 | Capture reminder delivery evidence | The worker now enqueues reminders; staging must prove scheduler timing, Resend acceptance, retry, and no duplicate send | ORA + release owner |
+| P1 | Verify customer-manage links in real Resend emails | Staging must prove the 30-day link opens the noindex customer page and reschedule/cancel remain token-bound | ORA + release owner |
+| P1 | Verify waitlist notification delivery and conversion workflow | Staging must prove queue scope, one-time notification behavior, Resend acceptance, conflict handling, and the linked booking/confirmation email | ORA + product owner |
+| P1 | Switch marketing CTAs from `/book` to `/_maggie/booking/book` | Avoid sending customers to the new flow before staging proves it | Product owner |
+| P2 | Add richer Fresha features | Package purchase/refund paths are implemented locally. Memberships, gift cards, advanced multi-location staff rules, and customer-side package/membership pricing remain roadmap items. Customer self-service history, bounded automatic waitlist matching, and segment-safe multi-treatment rescheduling still need real host delivery proof | Product roadmap |
+
+## Evidence already run
+
+- ORA `npm run build`: passed with no errors, warnings, or hints;
+  the Stripe setup checklist is included in the built Booking workspace.
+- ORA `npm audit --omit=dev --audit-level=high`: passed with zero
+  vulnerabilities after refreshing the Cloudflare/Wrangler lockfile chain.
+- ORA `maggie booking inspect --project .`: passed all installed workspace,
+  contract, schema, customer, worker, and ops checks.
+- ORA installed UI and customer UI validators: passed after resolving the
+  `_maggie/booking` workspace path.
+- Central and ORA Booking UI validators now also reject fixture location/service
+  IDs in the installed manager source; both copies passed.
+- Central and ORA location configuration, service-contract, route-handler, and
+  reference-host validators now cover the 47-route manager surface; both
+  installed UI copies passed.
+- ORA worker/runtime regression: passed for waitlist priority/FIFO matching,
+  one-time offered-slot persistence, and idempotent replay.
+- ORA customer reference-host regression: passed public multi-treatment
+  availability, hold/checkout, and token-bound multi-treatment rescheduling;
+  the PostgreSQL core regression also passed segment-safe rescheduling.
+- MaggieDash customer-flow, customer-UI, runtime-plan, worker-repository, and
+  syntax checks: passed.
+- ORA `maggie booking release-gate --project .`: static contract/workspace gate
+  passed; runtime, browser, ops, and board evidence were not supplied.
+- ORA `maggie booking setup --project .`: dependencies, database URL, public
+  URL, Booking token secret, Resend sender configuration, and a Stripe test
+  secret alias are present; the missing webhook secret keeps Stripe in pending
+  verification, while schema, first owner, and worker schedule remain explicit
+  verification steps.
+- Full required release gate was run read-only on 2026-09-21 and correctly
+  returned `blocked` for the missing runtime, browser, ops, and unfinished-board
+  evidence. It did not run migrations, create bookings, send email, or deploy.
+- ORA `npm run booking:schema -- --check`: `needs-migration` with core present,
+  Booking absent, and Booking access absent. This command was read-only; no
+  database migration was applied.
+- Disposable local ORA Astro runtime: first-owner registration HTTP 201,
+  password login HTTP 200, authenticated overview/settings/catalog/staff HTTP
+  200, and public catalog HTTP 200 against a temporary PostgreSQL database.
+  This caught the variant ordering and partial-seed defects above; it is not
+  production or staging evidence.
+- Central and ORA PostgreSQL core integrations now persist two treatment
+  variants, assert expanded allocation ranges after rescheduling, and reject a
+  buffer-overlapping adjacent booking. The reference hosts and customer
+  cursors also apply the same rule. The one-time
+  `schema/maggie-booking-buffer-backfill.sql` migration is included but still
+  needs staging/owner approval; no live ORA database was changed.
+
+## Decision
+
+Do not market this as a complete Fresha replacement yet. It is a valid Booking
+foundation and installable host integration. The next safe step is staging
+migration plus real Stripe/Resend/browser evidence, followed by a canary before
+changing the public CTA.