@topy-ai/maggie 0.7.37 → 0.7.40

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

@@ -11,22 +11,30 @@ for importing a provider's service catalogue. The existing
 right choice for provider-backed services, prices, durations, booking links,
 and factual provider validation.
 
+## Project memory
+
+Before changing a host project, follow the shared
+[`memory-hook.md`](../../references/memory-hook.md) instructions for reading
+relevant project preferences and known pitfalls. After a verified fix or a
+durable host decision, record only the generalizable learning; never promote a
+temporary project detail, secret, or unverified guess into active memory.
+
 ## 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
+Read [`../../bundled-references/maggiedash-booking/README.md`](../../bundled-references/maggiedash-booking/README.md),
+[`TASKS.md`](../../bundled-references/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,
+ships a tenant-scoped PostgreSQL manager repository for catalogue, treatment packages, 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
+[`EXECUTION-BOARD.json`](../../bundled-references/maggiedash-booking/EXECUTION-BOARD.json)
+and [`TASK-RUNBOOK.md`](../../bundled-references/maggiedash-booking/TASK-RUNBOOK.md). Do not
 mark a task passed until its implementation gate, docs update, and evidence
 record are complete.
 
@@ -69,7 +77,7 @@ 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).
+[`fixtures/maggiedash/booking-runtime.v1.json`](../../bundled-contracts/maggiedash/booking-runtime.v1.json).
 
 Install the first-party workspace and the host integration through the stable
 Booking installer:
@@ -88,13 +96,29 @@ 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`.
+package already present in `dependencies` or `devDependencies`. For a blank
+Astro host it also adds the compatible `@astrojs/node` SSR adapter and the
+portable server config; an existing `astro.config.*` and deployment adapter
+remain host-owned.
+
+For a new host with an approved database migration, `--ready` combines the two
+explicit setup mutations into one command:
+
+```bash
+maggie booking install --project . --confirm --ready
+```
+
+It installs only missing host packages, generates `BOOKING_TOKEN_SECRET` when
+needed, and applies the installed idempotent Booking schema. It still does not
+create the owner, configure Stripe, send email, enable a scheduler, or deploy.
+Use `--schedule systemd` or `--schedule cron` with `--ready` only to generate a
+reviewable scheduler artifact; enabling it remains an operator action after
+backup, migration, and release evidence checks.
 
-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.
+The default installer source is the public MaggieDash `0.2.8` distribution. It
+contains the released Astro `hostBootstrap` manifest and 47-route Booking
+source, including the tenant-scoped treatment package catalogue. A fresh public-source install, `maggie booking inspect`, and
+`astro build` are the release evidence; a local-source result alone is not.
 
 For a new host with a reviewed `DATABASE_URL`, the explicit one-command
 bootstrap also applies the idempotent Booking schema:
@@ -112,6 +136,21 @@ 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.
 
+Generate the reviewed worker scheduler artifact as part of the same install,
+or after an existing install:
+
+```bash
+maggie booking install --project . --confirm --bootstrap --schedule systemd
+# or, for a host without systemd:
+maggie booking worker-schedule --project . --scheduler cron --confirm
+```
+
+This writes `deploy/maggie-booking-worker.service` plus `.timer`, or a
+reviewable `deploy/maggie-booking-worker.cron`. It does not edit the crontab,
+enable systemd, start a process, or expose secrets. Review the generated
+artifact, set an unprivileged service user, then enable it only after the
+schema, backup/restore, and release evidence gates pass.
+
 Before changing host configuration, run the safe first-run checklist:
 
 ```bash
@@ -147,16 +186,19 @@ Validate the tenant-scoped Resend template boundary independently:
 maggie booking email-templates-contract
 ```
 
-This freezes the seven supported Booking events, approved `{{variable}}`
+This freezes the ten 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.
+copyable `/api/maggie/booking/webhooks/stripe` URL. The preferred path is still
+the deployment secret store. For a single-business host, an owner or manager
+may submit both Stripe values over HTTPS from this screen; the server verifies
+them first, stores only authenticated AES-256-GCM ciphertext derived from
+`BOOKING_TOKEN_SECRET`, and never returns the raw values. Deployment
+`STRIPE_SECRET_KEY` takes precedence over dashboard-managed credentials.
 
 For an Astro host, framework detection installs missing email/password login,
 first-owner registration, manager/public Booking routes, PostgreSQL/Stripe
@@ -169,9 +211,11 @@ 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.
+are preserved unless `--force` is explicitly supplied. Conventional Astro
+middleware using either `defineMiddleware((context, next) => {})` or a
+destructured context such as `defineMiddleware(({ url, request }, next) => {})`
+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
@@ -231,18 +275,48 @@ 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.
 
+When a tenant has multiple online-bookable locations, the public catalogue must
+return a safe `locations` list and the customer page must let the customer pick
+one. Include the selected `locationId` in availability, waitlist, hold,
+checkout, and reschedule requests. Availability must validate that the
+location belongs to the tenant, is active and online-bookable, use its
+timezone, and filter conflicts by that location. Keep the legacy first
+`locationId` field during migration so older hosts remain compatible; never
+fall back to `location-1` or another fixture ID.
+
+After a confirmed package purchase, the public page may carry the opaque
+`packageEntitlementId` into the hold and checkout requests. The server resolves
+the customer from the submitted email, validates tenant ownership, active
+status, expiry, currency, and every selected treatment balance, then locks the
+entitlement and item rows while creating the booking and redemption ledger.
+Public package redemption is all-or-nothing for a multi-treatment selection;
+it confirms a fully covered booking at zero price and does not trust the
+browser to decide the balance.
+
 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 administrator access registry must stay identical to the route-handler
+capabilities: calendar, bookings, customers, waitlist, catalogue, packages,
+staff, resources, schedule, locations, payments, refunds, notifications,
+settings, reports, and audit. If `permissions_json` is absent on a legacy role,
+apply the safe role defaults server-side; never treat a missing object as full
+read access. Explicitly granted staff capabilities must be honored by the
+route handler, while staff mutations remain limited to approved lifecycle
+transitions. Keep the access contract, Astro host, reference host, ORA mirror,
+and CLI validator synchronized whenever a route capability changes.
 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.waitlist.available` notification. Package purchase fulfillment and
+provider-confirmed package refunds also queue the allowlisted
+`package.purchase.confirmed`/`package.purchase.refunded` Resend events linked to
+the package purchase, without appointment manage links. 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
@@ -278,7 +352,9 @@ installed host is:
 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
+# preferred: add Stripe and Resend secrets through the deployment secret store
+# alternative: owner/manager can enter the Stripe key pair in Booking Overview;
+# the host verifies it and stores only encrypted ciphertext
 node scripts/maggie-booking-worker.mjs --write --confirm
 ```
 
@@ -377,7 +453,7 @@ Follow the task board rather than building a disconnected calendar first:
    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).
+   [`PROGRESS.md`](../../bundled-references/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
@@ -440,6 +516,11 @@ 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.
+If the host already has a legacy `/book` request form, keep it as a fallback
+until the Booking schema is ready; expose the new customer route only after a
+schema-aware readiness check, and preserve any existing treatment hint when
+linking into the new flow. Do not replace a working host booking form with a
+route that can only show an unconfigured Booking error.
 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

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

@@ -182,6 +182,20 @@ unconfirmed writes. Generated copy and media must be marked authored rather
 than source-observed. Implementation must still capture responsive screenshots
 and run accessibility/build validation before publication.
 
+Author jobs are resumable design jobs even though their plan is stored beside
+the author brief at `.maggie/design/author-<id>.json`. Use the same progress
+commands as an in-place job; `status` and `step` resolve both supported job
+locations:
+
+```bash
+maggie design status author-<id> --project .
+maggie design step author-<id> --project . \
+  --step inspect-shell --evidence .maggie/evidence/inspect-shell.json
+```
+
+An author plan is not complete until every `requiredSteps` entry has matching
+evidence and the explicit approval step is recorded.
+
 ## Content UI initialization
 
 Use content UI initialization when `maggie-blog` or
@@ -496,3 +510,24 @@ Follow the shared [Maggie Decision Loop](../../references/decision-loop.md) for
 6. Require explicit final confirmation before any mutation or external write.
 
 If a decision is not relevant, record it as `skipped` with a reason. Do not silently assume a missing choice, and do not treat an existing output as permission to skip required work.
+
+## Contract checks for dashboards, samples, and progressive enhancement
+
+Run these stable evidence checks after implementation:
+
+```bash
+maggie design progressive-check --evidence .maggie/progressive.json
+maggie design css-check --html dist/index.html --css dist/assets/app.css
+maggie design css-cascade-check --evidence .maggie/css-cascade.json
+maggie design dash-init --project . --route /_maggie/admin --confirm
+maggie design dash-validate --plan .maggie/design/dashboard/*/plan.json --evidence .maggie/dashboard-evidence.json
+maggie design sample-init --project . --route /layout-sample --purpose "layout exploration" --confirm
+maggie design sample-validate --plan .maggie/design/sample/*/plan.json --evidence .maggie/sample-evidence.json
+```
+
+The checks cover smallest-region swaps, stable DOM identities, third-party
+requests, stale responsive Tailwind utilities, and unlayered CSS winning over
+utilities. Dashboard plans require operator journeys and desktop/tablet/mobile,
+collapsed-rail, mobile-drawer, and modal evidence. Sample plans require
+noindex, sitemap exclusion, a visible sample banner, placeholders, and a
+finish checklist.

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -381,3 +381,15 @@ backed by a content-change/source-revision event; operational sync, pull,
 deploy, or `updated_at` timestamps are rejected. The agent-file command emits
 locale-aware `llms.txt`, `sitemap.md`, and `insights.md` from the same route
 inventory; non-indexable routes are omitted.
+
+For every release, audit third-party privacy origins:
+
+```bash
+maggie seo privacy-check --evidence .maggie/privacy-origin-evidence.json
+```
+
+The site audit also records `primary_navigation_indexability` and flags a
+same-origin page linked from primary navigation when it is `noindex`,
+`nofollow`, or `none`. The privacy check fails in both directions: an embedded
+origin missing from the policy, or a policy origin never observed in rendered
+pages, requires review.

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

@@ -502,3 +502,17 @@ later sync are marked `archived`, retained for reconciliation, and excluded
 from active category context and public fact gates. After every sync, run
 `fact-audit`, `category-context`, the category hash/render/audit sequence, and
 the aggregate `maggie_release.py` gate.
+
+### Treatment groups
+
+Keep one treatment catalogue entry and put length/price choices in its
+`variants` array. Imports emit `treatmentGroup` with variant count, duration
+range, and a from-price summary. Run the gate before rendering service cards:
+
+```bash
+maggie service treatment-group-audit --project .
+```
+
+This prevents a 30/60/90/120-minute treatment from becoming four unrelated
+products and gives catalogue, detail, booking, and pricing surfaces one stable
+identity.