@topy-ai/maggie 0.7.52 → 0.7.54

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

@@ -1,288 +0,0 @@
-# MaggieDash Booking workspace
-
-This folder is the product and engineering documentation for the Booking
-workspace at `/_maggie/booking`. The canonical current snapshot and gap list is
-[`CURRENT-STATE.md`](./CURRENT-STATE.md); this README explains the surface and
-links the deeper contracts.
-
-The target is a first-party booking management system for store managers. It
-must own the booking domain while keeping payment providers replaceable. Stripe
-is the first adapter, not the database, booking engine, or public API contract.
-
-## What is true today
-
-This repository currently provides:
-
-- the `maggie-service-booking` skill for provider-backed service catalogues,
-  variants, provider URLs, sync, factual validation, and service-page output;
-- a provider-neutral booking adapter reference with Fresha as the first
-  catalogue provider and Google Calendar as a limited fallback;
-- MaggieDash installation into `./_maggie/admin`;
-- MaggieDash distribution of a separate `./_maggie/booking` React workspace,
-  Booking UI v1 and the provider-neutral Booking host adapter v1;
-- a provider-neutral PostgreSQL Booking starter schema with idempotency, audit,
-  outbox, payment, hold, allocation, and database overlap constraints;
-- `maggie booking install` (including explicit `--install-dependencies`, `--bootstrap`, the combined `--ready` path, and reviewed `--schedule systemd|cron` generation), `worker-schedule`, `inspect`, the read-only first-run `setup` checklist,
-  `contract`, `runtime-validate`, `ops-validate`, task-board, and fail-closed
-  `release-gate` checks in ai-cmo-skills;
-- a non-destructive Astro host bootstrap that installs email/password auth,
-  first-owner registration, manager/public routes, PostgreSQL/Stripe wiring,
-  the schema command, Resend worker, and middleware rewrite starter;
-- Booking access management for email/password staff, manager, and finance
-  accounts is covered by the installable `booking-access-v1` contract, including
-  granular permissions, Resend invitations, password reset, revocation,
-  disabled-account protection, staff-profile linking, and server-enforced
-  granular permissions;
-- tenant-scoped Booking email template management for ten Resend events,
-  allowlisted variables, sandboxed preview, audited draft/publish/rollback, and
-  worker fallback resolution without exposing provider secrets or recipients;
-- server-side staff assignment scope for bookings, calendar, availability,
-  customer summaries, schedule, resources, and lifecycle mutations;
-- a source/install-side runtime plan regression gate for concrete route
-  parameters, query parameters, and mutation bodies;
-- a protected operational-evidence workflow that rejects fixture artifacts at
-  the host release boundary;
-- a separate public-noindex customer-flow contract and route handler for
-  catalogue, availability, holds, checkout start, payment-return recovery,
-  cancellation, token-bound customer rescheduling, customer-manage history,
-  waitlist joining, safe DTO
-  redaction, and notification intents;
-- a tenant-scoped waitlist queue with manager filtering, priority/status
-  actions, audit records, a linked booking conversion transaction, and a Resend
-  availability-notification intent;
-- a worker-side waitlist matcher that orders eligible entries by priority/FIFO,
-  persists the offered slot, and queues one idempotent Resend availability
-  notification without auto-reserving the appointment;
-- separate short-lived payment tokens and 30-day sealed customer-manage
-  tokens, with Resend worker links for customer self-service follow-up;
-- a public customer-manage history view that lists only redacted appointment
-  summaries for the tenant/customer bound to the 30-day token;
-- a manager customer directory with searchable tenant-scoped customer details,
-  consent summary, and appointment history;
-- editable schedule-rule management for working hours, staff shifts, time off,
-  and location closures without destructive snapshot writes;
-- editable service and treatment catalogue management with stable service and
-  variant IDs, payment policy controls, search, and active/inactive status;
-- editable location management with tenant-scoped timezone, locale, address,
-  active state, and online-booking controls;
-- editable staff and resource management with assignment, bookable, capacity,
-  and active-state controls;
-- editable Booking defaults for venue timezone/currency, accepting new
-  bookings, and automatic/manual payment capture policy;
-- editable tenant-scoped treatment package catalogue with included treatment
-  quantities, package pricing, currency, expiry, and active state;
-- manager-granted customer package entitlements with tenant/customer-scoped
-  balances, expiry checks, and atomic redemption when creating manager
-  bookings; public package checkout, provider reconciliation/webhook fulfillment,
-  manager purchase listing, and guarded package refund routes are included;
-- Overview bookability readiness that identifies missing active locations,
-  catalogue variants, assigned bookable staff, working hours, payment
-  capability, and the resulting overall `bookable` state;
-- manager booking creation driven by live catalogue, location, staff, and
-  resource selectors with required allocation;
-- install-time configuration forms that read tenant locations and live service
-  assignments instead of relying on fixture IDs;
-- an installable public customer booking page source and Astro route starter
-  for the same hold/checkout/pending-return journey;
-- public multi-treatment selection with combined-duration availability, summed
-  checkout pricing, safe segment DTOs, segment-safe customer rescheduling, and
-  tenant location selection with location-scoped availability;
-- a deterministic public customer reference-host journey validator covering
-  hold replay, checkout pending state, payment return, token-bound cancel, and
-  manager-session isolation;
-- provider-neutral runtime rules and worker runner for availability, hold
-  expiry, payment webhook/reconciliation, priority/FIFO waitlist matching, and
-  notification outbox delivery;
-- a dated Stripe API/resource/event audit and installable capability contract;
-  the host still supplies the concrete official SDK adapter;
-- a manager Reports screen and tenant-scoped `/reports.json` read model for
-  period totals plus day, service, staff, and location breakdowns;
-- venue-time manager booking displays and wall-clock inputs, with DST-gap
-  rejection and explicit choices for repeated fall-back times;
-- an idempotent 24-hour reminder worker job that queues confirmed-booking
-  reminders into the existing Resend notification outbox;
-- service-level payment policies (`full`, `deposit`, `pay_later`, and
-  `no_payment`), purpose-labelled payment attempts, captured/refunded payment
-  projection, and manager controls for deposits and outstanding balances;
-- systemd/cron scheduling templates and a protected Playwright browser-evidence
-  capture/validation workflow;
-- provider-neutral MaggieDash host, auth, activity, navigation, content, media,
-  migration, and runtime-evidence contracts;
-- a PostgreSQL starter schema for MaggieDash content and audit records.
-- a tenant-scoped Notifications screen for delivery-state inspection and
-  reasoned dead-letter replay, with recipient redaction and audit evidence.
-- policy-safe cancellation settlement that allocates full/deposit refunds,
-  invokes the injected payment provider after the lifecycle write, returns
-  `manual_required` on provider failure, and queues accepted/pending refund
-  notices through the existing Resend outbox;
-
-The manager workspace, distribution contracts, starter schema, provider-neutral
-runtime rules, worker runner, scheduling templates, browser-evidence gate, and
-customer-flow boundary are implemented locally. A secret-free reference host
-and an Astro host scaffold are also available for contract/browser work. A host
-must still apply the schema, prove PostgreSQL transactions, verify a real
-payment account and webhook, enable notification delivery and tenant locking,
-and capture authenticated browser/runtime/ops evidence against a dedicated
-HTTPS test tenant before real bookings can be enabled. Test evidence workflows
-must not target production; any production observation needs its own approved,
-read-only plan.
-Resend is the server-side notification and account-email transport. Staff
-invitation, first-login setup, password reset, one-time token expiry, and
-session revocation are implemented in the Astro host scaffold; real delivery
-and browser evidence remain host deployment gates.
-Stripe setup is likewise server-side: configure the host secret store, then
-verify the account from Booking Overview. For a single-business host, an
-owner/manager can alternatively enter both Stripe values in the secure
-dashboard form; the host verifies them first and stores only encrypted
-ciphertext derived from `BOOKING_TOKEN_SECRET`. Secret presence alone is only
-`pending`; `connected` requires a successful API check, explicit Stripe
-charges/payouts enablement, and a webhook secret. Raw Stripe credentials are
-never returned by the API or stored as plaintext Booking data. Deployment
-secrets take precedence over dashboard-managed credentials.
-
-## Verification snapshot — 2026-09-28
-
-This dated snapshot records the earlier 0.7.48 candidate review and 15-route
-local browser smoke. It is historical; for the current task count, browser
-contract, and release blockers, use [`CURRENT-STATE.md`](./CURRENT-STATE.md).
-
-| Item | Current evidence |
-|---|---|
-| MaggieDash and ai-cmo source | MaggieDash package `0.2.11`; ai-cmo `0.7.48` (published) |
-| Email-template boundary | Ten events, including `payment.no_show_fee`; confirmed bookings allow a host-supplied, escaped `arrivalNote` |
-| ORA source CLI check | Local ai-cmo source `email-templates-contract` and `inspect --project` pass; the installed global package still carries the old nine-event contract and requires a package release/install readback |
-| Regression evidence | MaggieDash `npm test`, 25 targeted ai-cmo Booking Python tests, and ORA email-template/customer validators pass; ORA Astro build passes |
-
-## Historical verification snapshot — 2026-09-21
-
-| Item | Current evidence |
-|---|---|
-| MaggieDash source | Package `0.2.8`, `HEAD`/`origin/main` [`9d99de7`](https://github.com/TOPY-AI-LTD/MaggieDash/commit/9d99de7); the working tree contains newer uncommitted Booking changes |
-| Delivery board | 101 implementation tasks passed and 3 real-host evidence tasks pending (BK-030, BK-031, BK-032). The current browser contract requires all 17 manager routes across three viewports (51 screens), including Packages and Email templates; prior 45-screen captures are historical subset evidence. |
-| Local code gates | MaggieDash `npm test`, contract/UI/security/customer/runtime validators, and Python task-board/link checks passed |
-| Installer projection | The default public GitHub source installed 139 source artifacts plus 23 Astro host files in a fresh disposable project; dependency completion added the missing SSR adapter, and the installed host bootstrap validator, `maggie booking inspect`, and `astro build` all passed. Existing host deployment configs are preserved |
-| Published npm parity | Local CLI source is `0.7.39`; npm still serves `@topy-ai/maggie@0.7.38`, which has the older Booking contract and needs a release/published-tarball verification |
-| Access boundary | Standard Booking schema owns `maggiedash_booking_user_roles`; host access API, explicit permissions, linked `staff_id`, and repository data-scope checks passed |
-| Reference host | 47 manager endpoint checks plus public customer-flow checks passed, including explicit no-show fee route coverage, location setup, package catalogue management, customer package grant/balance/redemption, public package redemption from hold to zero-price booking, package checkout/payment-return, Stripe connection verification, notification replay, and multi-treatment hold/checkout/reschedule |
-| Local browser smoke | At this historical snapshot the browser contract covered 15 manager routes (`45` route/viewport screens). The current v2 contract now covers 17 routes and requires route-specific path/heading evidence; the earlier artifact is not reused as complete evidence. |
-| Production proof | Not yet complete; reference-host and fixture artifacts are explicitly not production evidence |
-
-## Current product limits
-
-The local Booking release supports both manager-led and public customer package
-redemption. After a confirmed package purchase, the customer can continue to
-the public booking page; the server binds the entitlement to the customer's
-email, locks the balance during checkout, and creates a zero-price confirmed
-booking when all selected treatments are covered. A successful cancellation
-restores each active redemption once and records the reversal; completed and
-no-show visits remain consumed by policy. Memberships, gift cards, and
-recurring appointments are not yet part of the v1 contract. No-show fees are
-supported only through the separate consented, explicitly confirmed
-off-session charge route; there is no automatic charge on status transition.
-
-## Evidence inspected
-
-| Evidence | What it establishes |
-|---|---|
-| `/home/balalior/Dev/MaggieDash/maggiedash.json` | Distribution targets `_maggie/admin` plus the separate `_maggie/booking` workspace |
-| `/home/balalior/Dev/MaggieDash/backend/booking-adapter-contract.d.ts` | Booking host owns the email/password session, API prefix, manager service surface, and injected provider boundary |
-| `/home/balalior/Dev/MaggieDash/contracts/booking-host-adapter-v1.json` | Current 47-endpoint Booking host contract and response policy, including treatment packages, customer package balances/redemption, package purchase/refund, Stripe verification, consented no-show fee charging, and notification inspection/replay |
-| `/home/balalior/Dev/MaggieDash/contracts/booking-customer-surface-v1.json` | Current eleven-endpoint public customer boundary and noindex/idempotency policy, including package checkout/payment return |
-| `/home/balalior/Dev/MaggieDash/package.json` | Current `0.2.8` package scripts and executable Booking validators |
-| `skills/maggie-service-booking/SKILL.md` | Current provider-backed catalogue and booking-link scope |
-| `references/provider-adapter-contract.md` | Existing provider-neutral booking/payment direction |
-| `tools/clis/maggie_dash.py` | Installer maps both admin and Booking workspaces, plus root contracts/schema |
-| `tools/clis/maggie_booking.py` | Booking installer plus inspect, contract, runtime, and release gates |
-| `/home/balalior/Dev/MaggieDash/adapters/astro/host/` | Generic non-destructive Astro host scaffold for auth, routes, PostgreSQL, Stripe, schema, Resend worker, and middleware |
-| `/home/balalior/Dev/MaggieDash/contracts/booking-email-templates-v1.json` | Ten-event tenant-scoped template contract and server-only Resend/recipient policy |
-| `/home/balalior/Dev/MaggieDash/backend/booking/email-templates.mjs` | Provider-neutral fallback, placeholder allowlist, HTML escaping, and renderer |
-
-## Documents
-
-| Document | Diataxis role | Use it for |
-|---|---|---|
-| [PRD](./PRD.md) | Reference | Product scope, requirements, personas, and acceptance criteria |
-| [Architecture](./ARCHITECTURE.md) | Explanation | System boundary, modules, state ownership, and runtime topology |
-| [User journeys](./USER-JOURNEYS.md) | Tutorial / explanation | Manager, customer, staff, finance, and failure journeys |
-| [Data flow](./DATA-FLOW.md) | Explanation / reference | DFD, events, consistency, and source-of-truth rules |
-| [Data model](./DATA-MODEL.md) | Reference | Entities, constraints, indexes, and migration order |
-| [Payment gateway](./PAYMENT-GATEWAY.md) | Reference / explanation | Provider port, Stripe adapter, webhooks, refunds, and future providers |
-| [Stripe integration audit](./STRIPE-INTEGRATION.md) | Reference / runbook | Verified API matrix, webhook set, Tax/Billing/Terminal/Connect choices, and gift-card/referral boundary |
-| [Host adapter](./HOST-ADAPTER.md) | Reference | Routes, payloads, auth, errors, and conformance evidence |
-| [Skills and CLI](./SKILLS-AND-CLI.md) | How-to / reference | How ai-cmo-skills supports implementation, checks, and release gates |
-| [Security and compliance](./SECURITY-COMPLIANCE.md) | Explanation / reference | Secrets, tenancy, audit, PCI scope, privacy, and operational controls |
-| [QA plan](./QA-TEST-PLAN.md) | How-to / reference | Contract, state, concurrency, payment, browser, and release tests |
-| [Runtime operations](./RUNTIME-OPERATIONS.md) | How-to / runbook | Worker jobs, webhook flow, notification outbox, cron/systemd, browser evidence, alerts and rollback |
-| [Current state](./CURRENT-STATE.md) | Reference / runbook | Verified surface, release blockers, host sequence, and gaps |
-| [Decision log](./DECISIONS.md) | Explanation | Durable architecture decisions and unresolved choices |
-| [Execution board](./EXECUTION-BOARD.json) | Reference | Leaf tasks with dependencies, implementation files, tests, docs, and acceptance evidence |
-| [Task runbook](./TASK-RUNBOOK.md) | How-to | Task → plan → implement → test → docs → progress operating loop |
-| [ORA integration audit](./ORAWELLNESS-INTEGRATION-AUDIT.md) | Reference | Host-specific Booking, Stripe, Resend, migration, and production-readiness status |
-
-## Diagrams
-
-The source files live in [`diagrams/`](./diagrams/). Rendered images are linked
-from the data-flow and architecture documents so the documentation does not
-depend on GitHub Mermaid rendering.
-
-- [System context](./diagrams/system-context.svg)
-- [Manager journey](./diagrams/manager-journey.svg)
-- [Booking data-flow diagram](./diagrams/booking-dfd.svg)
-- [Payment sequence](./diagrams/payment-sequence.svg)
-- [Booking state machine](./diagrams/booking-state-machine.svg)
-
-Each diagram also has an editable `.mmd` source. Flowcharts include an
-`.excalidraw` scene; the sequence and state diagrams intentionally include only
-SVG and PNG because the renderer's editable-scene converter supports flowcharts
-only.
-
-## Recommended host rollout
-
-1. Read [`CURRENT-STATE.md`](./CURRENT-STATE.md) and run the read-only install,
-   schema, contract, and build checks.
-2. Back up the host database and rehearse restore into an empty disposable
-   database.
-3. Apply Booking/access migrations only after owner approval, then register the
-   first owner and seed a staging location/catalogue/staff schedule.
-4. Configure and verify Stripe test credentials plus the signed webhook secret.
-5. Enable one worker scheduler with lock, alert, retry, and dead-letter proof;
-   verify Resend invitation, reset, reminder, waitlist, refund, package, and
-   no-show delivery.
-6. Capture the 47-endpoint runtime, 51-screen browser, and ops evidence bundle;
-   run the final release gate before a one-location canary.
-
-The detailed execution board is maintained by
-[`EXECUTION-BOARD.json`](./EXECUTION-BOARD.json). Use
-`maggie booking tasks validate` before starting a task and record the evidence
-in [`PROGRESS.md`](./PROGRESS.md). A final delivery decision must require
-runtime, browser, ops, and board evidence:
-
-```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
-```
-
-## Non-negotiable truths
-
-- PostgreSQL is business truth.
-- The availability engine and database constraints are booking truth.
-- The payment gateway is payment truth, but never booking truth.
-- A payment redirect is not proof of payment; a verified webhook or provider
-  read is required.
-- A hold is a first-class record with an expiry and an idempotency key.
-- All monetary values use integer minor units plus an ISO currency.
-- All stored instants are UTC; venue-local input carries an IANA timezone.
-- Manager actions are authenticated, authorized, idempotent, and auditable.
-- Provider credentials stay server-side and never enter dashboard props or
-  browser bundles.
-
-## Evidence boundary
-
-The existing MaggieDash source and ai-cmo-skills contracts were inspected on
-2026-09-21. Statements marked **current** describe repository evidence.
-Statements marked **proposed** describe the implementation target and must not
-be presented to a user as an already-supported feature until the relevant
-contract, adapter, tests, and runtime evidence land.