@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-skills/maggie-content-localization/references/email-and-lifecycle.md

@@ -0,0 +1,83 @@
+# Localized email and consent-aware lifecycle email
+
+Email is a localized content surface. Treat every template × locale × market
+as a reviewable variant, and keep transactional/security messages separate
+from marketing consent. Both commands below are read-only: they never call a
+provider and never send.
+
+## Localized templates (`email-matrix`)
+
+Describe templates in a `maggie-email-localization.v1` manifest (schema:
+`contracts/maggie-content/email-localization-v1.schema.json`, shipped as
+`bundled-contracts/maggie-content/` in the npm package).
+
+Locale precedence is fixed: **user preference > market > account > fallback**.
+A send path must pass the resolved recipient locale. Two patterns fail:
+
+- a hard-coded locale (e.g. a fulfilment path that always renders `en`);
+- `Accept-Language` as the only source for fulfilment or transactional email.
+  For other paths it is only a hint and produces a warning.
+
+Declare each send path under `callSites` with its `localeSource` so the check
+covers code paths, not only templates.
+
+The check fails when:
+
+- a required locale or its subject/HTML/plain text is missing;
+- a translated field is identical to the source text (untranslated);
+- variables differ from the source field, are undeclared, or differ between
+  the HTML and plain-text bodies;
+- a CTA route is not a site path or `https` URL, uses a market whose prefix it
+  does not carry, targets a market that does not serve that locale, or changes
+  the template route's parameters.
+
+It warns about glossary terms not rendered as their approved translation,
+CTA routes missing from a body, unused variables, and unapproved variants.
+A variant is publishable only when its `approval` has `status: approved` and a
+`reviewer`; `--require-approved` turns that into a failure for release gates.
+
+```bash
+maggie localization email-matrix emails/manifest.json \
+  --preview-dir .maggie/localization/email-preview
+maggie localization email-matrix emails/manifest.json --require-approved
+```
+
+`--preview-dir` writes one `.html` and one `.txt` file per template × locale,
+filled from the template's synthetic `fixtures` (HTML-escaped) and labelled as
+a preview. Never put customer data in fixtures.
+
+## Lifecycle and marketing email (`lifecycle`)
+
+A `maggie-lifecycle-email.v1` plan (schema:
+`contracts/maggie-content/lifecycle-email-v1.schema.json`) runs through fixed
+stages: plan → segment → consent-check → preview → approve → schedule → send →
+report. `defaults.send` must be `disabled`: nothing is sent until approved.
+
+Start from the library, which drafts every kind with nothing sendable:
+
+```bash
+maggie localization lifecycle --library > emails/lifecycle.json
+maggie localization lifecycle emails/lifecycle.json
+```
+
+Library kinds: opt-in confirmation, welcome, digest, recommendation, gift /
+voucher / waitlist follow-up, merchant lead digest, campaign announcement,
+re-engagement.
+
+Rules the validator enforces:
+
+- Marketing templates need `consent.basis` (opt-in, double-opt-in,
+  soft-opt-in, or legitimate-interest-b2b) and a preference-centre
+  `consent.category`, an unsubscribe path, a preference-centre path, and
+  attribution fields (source/UTM) so outcomes can be measured.
+- Every template has a frequency cap (`maxPerWindow` + ISO 8601 `window`).
+- The opt-in confirmation is sent before consent exists, so it must be
+  transactional and carry no promotional content.
+- `sendable: true` requires an approval with `status: approved`, `reviewer`
+  and `approvedAt` — on the template and on the campaign.
+- Campaigns using marketing templates require consent, must honour
+  suppression, must deduplicate contacts, and need a schedule before they are
+  sendable. Declare aggregate report metrics; never report per-recipient data.
+
+The host owns consent records, segments, suppression lists, delivery and
+reporting. Maggie validates the plan; it does not send or store addresses.

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

@@ -2,7 +2,7 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.5.0
+  version: 1.6.0
 ---
 
 # Maggie Deployment
@@ -88,6 +88,74 @@ not fabricate browser, rendered, or deployment evidence and does not deploy
 from this command. See
 [`readiness-v1.schema.json`](../../bundled-contracts/maggie-deployment/readiness-v1.schema.json).
 
+### Collect host evidence
+
+Instead of hand-written SSH, systemd, and retention scripts per host, declare
+the standard adapters once in `.maggie/deployment/collector.json`
+(`maggie-evidence-collector.v1`) and let one command run them and emit the
+same `maggie-deployment-readiness.v1` report:
+
+```json
+{
+  "schemaVersion": "maggie-evidence-collector.v1",
+  "release": "2026-10-10-a",
+  "adapters": {
+    "canary": {"assets": ["https://example.test/_astro/app.js=<sha256>"], "renderReport": ".maggie/rendered-canary.json"},
+    "health": {"urls": ["https://example.test/robots.txt", "https://example.test/sitemap.xml"]},
+    "rollback": {"evidence": "docs/deployment-rollback-smoke.json", "plan": ".maggie/deployment/vps/deployment-plan.json"},
+    "releaseIdentity": {"command": ["ssh", "-o", "BatchMode=yes", "maggie-deploy@host", "readlink -f /var/www/example/current"]},
+    "authCanary": {"plan": ".maggie/deployment/auth-canary-plan.json"}
+  }
+}
+```
+
+```bash
+maggie deployment collect --project . --config .maggie/deployment/collector.json
+```
+
+Adapters write their evidence under `.maggie/deployment/collected/` and the
+readiness report adds the optional `hostHealth`, `releaseIdentity`,
+`rollbackEvidence`, and `authenticatedCanary` slots next to the five required
+slots. `releaseIdentity` proves the host's `current` release (from an argv
+command such as `readlink -f`, or a `{"url", "field"}` version endpoint)
+equals the expected `release`. Commands are argv lists, never shell strings,
+and are rejected if they contain a literal credential. The report records the
+config SHA-256, the release, and per-adapter run metadata so it can be
+reproduced; it never deploys.
+
+### Authenticated API canaries
+
+Public canaries cannot see failures on signed-in account or business APIs
+(database permission errors, schema mismatches, 403s). Declare role-scoped
+probes in a `maggie-auth-canary-plan.v1` plan:
+
+```json
+{
+  "schemaVersion": "maggie-auth-canary-plan.v1",
+  "baseUrl": "https://example.test",
+  "roles": {"owner": {"tokenEnv": "CANARY_OWNER_TOKEN"}, "staff": {"cookieEnv": "CANARY_STAFF_COOKIE"}},
+  "probes": [
+    {"id": "account", "role": "owner", "path": "/api/account", "expectJsonKeys": ["id", "role"]},
+    {"id": "business", "role": "staff", "path": "/api/business", "expectStatus": [200]},
+    {"id": "fixture-create", "role": "owner", "method": "POST", "path": "/api/canary-fixtures", "fixture": "disposable", "expectStatus": [201]}
+  ]
+}
+```
+
+```bash
+CANARY_OWNER_TOKEN=... maggie deployment auth-canary \
+  --plan .maggie/deployment/auth-canary-plan.json --output .maggie/deployment/auth-canary.json
+```
+
+Credentials come only from the named environment variables of dedicated
+canary accounts; a plan containing a literal token or cookie is rejected.
+Mutating probes must target a `disposable` fixture and run only with
+`--allow-mutations`. Evidence (`maggie-deployment-auth-canary.v1`) records
+probe id, role, method, path, status, and contract-key counts, classifying
+failures as `authorization`, `server`, `route`, `contract`, or `network`;
+it never stores headers, cookies, tokens, response bodies, or personal data.
+A missing credential makes the probe `inconclusive`, not passed.
+
 Classify host/runtime failures before a release can move:
 
 ```bash
@@ -207,7 +275,7 @@ The output contains only the immutable release/current layout, systemd unit,
 Nginx reverse-proxy config, health commands, rollback command, and an ordered
 reviewable release runner. The runner keeps migrations before the symlink flip,
 carries `.agents`/`.claude` state, restarts before verification, and prunes to
-the current release plus one rollback candidate. It never
+the plan's retention policy (default: current plus one rollback candidate). It never
 contains credentials and never SSHs, changes DNS, restarts systemd or deploys.
 
 VPS plans use a dedicated deployer account by default:
@@ -225,9 +293,23 @@ when they are unmarked or stale; use `--check-runner PATH` for a runner stored
 elsewhere. Regenerate from the reviewed VPS plan, inspect the diff, and replace
 the checked-in runner only after review.
 
-VPS plans include a bounded retention policy: keep two immutable releases,
-preserve the `current` target and rollback target, and review prune candidates
-before any operator executes cleanup. Generate a read-only candidate report:
+VPS plans carry one explicit retention policy, `--keep-releases N` (1-5,
+default 2). The same value drives the plan's prune command, the generated
+runner's prune step, `--retention-plan`, preflight, and rollback evidence, so
+Maggie never advertises a rollback target the host deletes:
+
+- `N >= 2` keeps the `current` target plus the release it replaced; the plan's
+  `commands.rollback` switches back to it.
+- `N = 1` keeps only the active release. The plan reports
+  `retention.rollbackAvailable: false` and `commands.rollback: null`, the
+  runner prints `rollback target: unavailable`, and production rollback
+  evidence must declare `codeRollback: "unavailable"` with a `recoveryPlan`
+  (redeploy the previous commit as a new release and restore its data
+  checkpoint). Preflight's `rollback_target_retained` check fails when a plan
+  keeps one release but still advertises a previous-release rollback.
+
+Review prune candidates before any operator executes cleanup. Generate a
+read-only candidate report:
 
 ```bash
 maggie tool maggie_deployment.py --retention-plan \
@@ -236,8 +318,8 @@ maggie tool maggie_deployment.py --retention-plan \
   --keep-releases 2 --output .maggie/deployment/retention-plan.json
 ```
 
-The CLI never deletes release directories and never permits fewer than two
-retained releases.
+The CLI never deletes release directories; only the reviewed runner prunes,
+and only after health checks pass.
 
 ### Multi-host secret parity
 

package/bundled-skills/maggie-deployment/references/vps.md

@@ -121,6 +121,29 @@ before staging migration and require a successful restore test before a
 production release. Keep the backup artifact and migration version in the
 handover record; never put a database URL or password in the manifest.
 
+### Running migrations as the database owner
+
+`sudo -u postgres psql -f /home/ubuntu/site/releases/<release>/db/073.sql`
+fails with `Permission denied` when the release lives under a deploy user's
+home: the `postgres` account cannot traverse that path. Do not widen
+filesystem permissions. Stream the file from a root-readable read into the
+owner-level `psql` instead (the generated plan's `commands.migrate_as_db_owner`):
+
+```bash
+sudo cat /home/ubuntu/site/releases/<release>/db/073.sql \
+  | sudo -u postgres psql -v ON_ERROR_STOP=1 --single-transaction -d <database> -f -
+```
+
+If a file path is required, copy it to a private temporary file readable only
+by the owner and remove it afterwards:
+
+```bash
+tmp=$(sudo -u postgres mktemp) && sudo cp <migration.sql> "$tmp" \
+  && sudo chown postgres: "$tmp" && sudo chmod 600 "$tmp" \
+  && sudo -u postgres psql -v ON_ERROR_STOP=1 -d <database> -f "$tmp"; \
+  sudo rm -f "$tmp"
+```
+
 ## Release workflow
 
 ```text
@@ -134,11 +157,20 @@ robots, sitemap, or private-route correctness.
 
 ### Release retention
 
-Keep exactly the `current` release plus one previous release as the rollback
-target. Prune after every deploy, and only after the new release passed its
-health checks: an unhealthy release must still have its predecessor on disk.
-The generated release runner does this as its final step; it never removes the
-release `current` points at or the release it replaced. Without pruning,
+The retention policy is one explicit number, `--keep-releases N` (default 2),
+shared by the plan, the runner, `--retention-plan`, preflight, and rollback
+evidence. The default keeps the `current` release plus one previous release as
+the rollback target. `N = 1` is allowed for hosts that intentionally keep only
+the active release, but then no on-disk rollback exists: the plan reports
+`rollbackAvailable: false`, the runner says so after pruning, and rollback
+evidence must name a recovery plan (redeploy the previous commit, restore the
+data checkpoint) instead of a previous release.
+
+Prune after every deploy, and only after the new release passed its health
+checks: an unhealthy release must still have its predecessor on disk. The
+generated release runner does this as its final step; it never removes the
+release `current` points at, and with `N >= 2` it also keeps the release it
+replaced. Without pruning,
 `releases/` grows by one full `node_modules` tree per deploy until the disk
 fills. Use `--retention-plan` for a read-only list of prune candidates on hosts
 whose runner predates this step, and review it before deleting anything.
@@ -180,7 +212,7 @@ canonical URLs, booking links, and protected Ops/API routes. Check both apex
 and `www` when configured. Record HTTP status, commit, and release.
 
 Rollback switches `current` to the previous immutable release and restarts the
-service. If migrations are not backward-compatible, stop before deployment and
+service, when the retention policy keeps one. If migrations are not backward-compatible, stop before deployment and
 provide a tested restore or database rollback plan. The first production
 release may declare rollback as not applicable only with `releaseKind: "first"`,
 a non-empty `notApplicableReason`, and `RELEASE_KIND=first`; upgrades still

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

@@ -84,6 +84,61 @@ a successful `assetStatus` (2xx), and a non-empty accessible name. This
 gate is independent from typecheck/build and is read-only apart from its
 explicit output.
 
+### Rendered glyph proof
+
+Collect that browser evidence with the shared collector instead of a
+hand-written report. It renders each route at mobile, tablet, and desktop in
+headless Chrome — through a local GET-only proxy for a running host
+(`--base-url`) or directly from a static build (`--dist`) — and records, per
+representative icon, whether its icon font reached `document.fonts` status
+`loaded`, whether the glyph paints ink that differs from the browser fallback
+font (a missing glyph falls back or paints blank), whether runtime CSS hides
+it (`display`, `visibility`, `opacity`, zero size, or a hidden pseudo-element),
+its font family, accessible name, and the served font asset status:
+
+```bash
+maggie design icon-glyph-check --base-url http://localhost:4321 \
+  --route / --route /contact --family ph=Phosphor \
+  --output .maggie/icon-browser-evidence.json
+```
+
+`--family PREFIX=FAMILY` asserts the expected visual family for a class
+prefix. Evidence from this collector makes `icon-release-gate` also require
+`fontLoaded`, `glyphPainted`, matching family, and an icon at every declared
+viewport; hand-written evidence still passes the original checks but the gate
+reports `glyphIdentityProven: false` with a warning. The collector forwards GET
+requests only and never stores page text beyond icon names and labels.
+
+## Design job verification
+
+`design step` records evidence one step at a time. `design verify` runs every
+step that can be proven automatically against a host adapter and records it
+with durable evidence under `.maggie/design-evidence/<job>/`:
+
+```bash
+# section-scoped job: snapshot before editing, then verify after
+maggie design verify section-<id> --project . --base-url http://localhost:4321 --stage before
+maggie design verify section-<id> --project . --base-url http://localhost:4321
+
+# in-place or author job against a static build, including the host build
+maggie design verify in-place-<id> --project . --dist dist --build-command "npm run build"
+```
+
+Automated steps: `inspect-route`/`inspect-shell`/`inspect-section` (2xx HTML,
+shell landmarks, target section present), `declare-content-source` (no
+unproven catch-all resolution), `capture-before`/`capture-after` (per-section
+structure hashes from `<section id>` or `data-section-id`),
+`assert-unchanged-rest`, `capture-responsive-screenshots` (390/768/1440 PNGs
+with hashes), `accessibility-check` (lang, one h1, alt text, named controls,
+labelled fields, `<main>`), `route-validation` (2xx, title, h1, no template
+placeholders, no accidental `noindex`), and `build-check` only with an explicit
+`--build-command`. A failed check leaves its step pending with `lastCheck`
+evidence. `apply-design-contract`, `implement-*`, `visual-review`, and
+`approval` are never completed by `verify`; record them with `design step` and
+real implementer or reviewer evidence, so a job cannot reach `done` without
+evidence. Client-rendered sections need host-adapter evidence through
+`design step` when the server HTML does not contain them.
+
 ## Hero video playback contract
 
 Hero video is an enhancement, not the only way to see the first-band message.

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

@@ -70,6 +70,15 @@ with one shared correlation ID instead of losing their relationship:
 
     maggie feedback batch --project . --batch-file ./feedback-batch.json
 
+For long cross-feature reviews, prefer the batch file over repeated `collect`
+calls: JSON strings carry multiline text, backticks, and command names without
+shell escaping. `--batch-file -` reads the same JSON from stdin, so a quoted
+heredoc (`<<'EOF'`) never interpolates command substitutions:
+
+    maggie feedback batch --project . --batch-file - <<'EOF'
+    {"batchId": "review-2026-10", "skill": "maggie-deployment", "items": [...]}
+    EOF
+
 The batch file contains 1–50 items and may provide shared `skill`, `runId`,
 `phase`, `priority`, and `affectedCli` values. An item can override those
 fields and supplies the normal `type`, `summary`, `expected`, `actual`,
@@ -155,6 +164,26 @@ skill or CLI, and replace every `REVIEW:` field (expected, actual, validation).
 placeholders. Then continue with `batch`, `batch-review`, and explicit
 `submit` as usual.
 
+## Check release and rollout claims before reporting "fixed"
+
+A fixed report is only as good as the release state it points to. Two
+read-only checks catch the drift that previous reports had to find by hand:
+
+    python3 scripts/validate_docs_freshness.py --release-metadata
+    maggie docs rollout-status --project .
+
+The first (Maggie source repository) fails when `VERSION`, the CLI package
+version, the newest `CHANGELOG.md` heading, and the README current-version text
+disagree, so a published version cannot ship without its release notes. The
+second scans `docs/` for rollout item IDs (default pattern `ABC-12`, override
+with `--id-pattern`) and fails when one document says an item is complete while
+another says it is pending or in progress. When `docs/rollout-status.json`
+(`maggie-rollout-status.v1`: `items[]` with `id`, `status` of `planned`,
+`in_progress`, `blocked`, or `complete`, and `evidence` for complete items)
+exists, it is canonical and every document must agree with it. Mark superseded
+documents with `<!-- documentation-status: historical-snapshot -->` instead of
+leaving contradictory claims current.
+
 ## Submit explicitly
 
 The CLI never submits automatically. After reviewing the draft:

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

@@ -96,10 +96,47 @@ prints these safe identifiers and scopes before any separate provider adapter
 is allowed to perform a write. A v1 report is rejected because it cannot prove
 that the browser/session is on the intended Google account and property.
 
+When a check fails, add an optional `failure` (`code`, `reason`, `httpStatus`;
+never a token or payload) to the row. The validator maps it to one failed
+prerequisite and one safe next action under `remediation`. For a single error,
+`maggie ops google-diagnose --code SERVICE_DISABLED --http-status 403` prints the
+same mapping.
+
+For Google Ads, run the read-only adapter before any keyword research:
+
+```bash
+maggie ops google-ads-preflight --customer-id 123-456-7890 \
+  [--login-customer-id 999-888-7777] [--probe-keyword-planner]
+maggie ops google-ads-keyword-ideas --customer-id 123-456-7890 \
+  --keyword "day spa" --language 1000 --geo-target 2826 --currency GBP
+```
+
+Credentials come from `GOOGLE_ADS_ACCESS_TOKEN` and
+`GOOGLE_ADS_DEVELOPER_TOKEN` (names overridable); values are never printed.
+The adapter only allows `listAccessibleCustomers`, `googleAds:search`, and
+`generateKeywordIdeas`, so it cannot mutate Ads state.
+
 The result separates `read`, `report`, `edit`, and `publish` for each
 provider/resource. Write and publish remain `not_tested` until the operator
 explicitly confirms the exact mutation and a successful read-back is captured.
 
+## Website notifications
+
+For website email, in-app, and SMS operations, follow
+[Website notification operations](references/notifications-operations.md):
+a catalogue with consent, retention, and delivery rules, template drift
+against a paginated provider export, a Resend preflight by variable name
+only, aggregate queue health with operator alerts, and a dry-run retention
+plan. All `maggie ops notifications` commands are offline and read-only, and
+none of them sends a message.
+
+```bash
+maggie ops notifications catalogue validate --project . --catalogue docs/notifications/catalogue.json
+maggie ops notifications templates drift --project . --catalogue docs/notifications/catalogue.json --local src/emails --provider-export exports/page-1.json
+maggie ops notifications preflight --project . --env-file .env.production --catalogue docs/notifications/catalogue.json
+maggie ops notifications health --project . --snapshot .maggie/notifications-health.json
+```
+
 ## Required preflight
 
 1. Inspect `.maggie/analysis.json` and `.maggie/bootstrap-state.json`.

package/bundled-skills/maggie-ops/references/notifications-operations.md

@@ -0,0 +1,154 @@
+# Website notification operations
+
+A provider-neutral operating contract for website email, in-app, and SMS
+notifications: what each message is, which consent it needs, how templates
+stay in sync with the provider, how delivery is kept durable, how the queue is
+watched, and how notification data expires. Every command below is offline and
+read-only. None of them call a provider API, send a message, or print secret
+values or recipient addresses.
+
+## 1. Catalogue every message
+
+Keep one machine-readable catalogue in the project (for example
+`docs/notifications/catalogue.json`) using
+`contracts/maggie-ops/notification-catalogue-v1.schema.json`. The packaged
+example `contracts/maggie-ops/notification-catalogue-example-v1.json` covers the
+seven sections a website normally needs:
+
+| Section | Typical entries |
+|---|---|
+| `identity-security` | email verification, password reset (often provider-owned), sign-in alert, credential/2FA/passkey change, account deletion |
+| `account` | welcome, onboarding reminder, preference update, saved-item digest |
+| `business` | listing/claim status, verification, team invite/approval, import or sync result, publish/domain readiness |
+| `billing` | checkout/subscription active, payment failed, receipt (often provider-owned), plan change, cancellation, trial ending |
+| `support` | contact/waitlist receipt, team copy of a contact, case reply/closure, feedback request |
+| `marketing` | opt-in confirmation, newsletter welcome, content digest, recommendation, gift/voucher interest follow-up, merchant lead digest, re-engagement |
+| `deliverability-ops` | bounce/complaint, suppression, worker failure, dead-letter growth, template drift, sender-domain health, queue health |
+
+Each entry records trigger, audience, category (`transactional`, `support`,
+`marketing`), consent boundary, locales and markets, variables, CTA route,
+idempotency-key template, retention days, provider, channels, delivery mode
+(`outbox`, `direct`, `provider`), queue, and status (`implemented`,
+`provider-owned`, `reserved`, `missing`). The status column turns the
+catalogue into a planning asset: `missing` lists what the site still lacks.
+
+```bash
+maggie ops notifications catalogue validate --project . --catalogue docs/notifications/catalogue.json
+```
+
+The validator enforces the cross-field rules a schema cannot:
+
+- Marketing messages require `consent: opt-in-required`, `unsubscribe: true`
+  (preference-centre and unsubscribe links), and the `marketing` queue.
+- `deliverability-ops` alerts use the `operations` queue. An alert about a
+  failing provider or queue must not travel through that same queue.
+- External-recipient lead email (`lead: true`: contact, waitlist, gift or
+  voucher interest) must use durable `outbox` delivery. A direct send that
+  only logs a failure can silently lose a business lead.
+- CTA routes are site paths or `https://` URLs with a fixed host.
+
+## 2. Durable delivery for lead email
+
+Contact, waitlist, and interest messages are acquisition signals. Route them
+through the same outbox as transactional mail: an idempotency key per
+submission, lease-based claiming, bounded retries, a dead-letter state with
+recorded-reason replay, and provider webhook reconciliation. The visitor's
+request succeeds once the outbox row is committed; delivery failure is an
+operations alert, not a visitor-facing error.
+
+## 3. Template lifecycle and drift
+
+Template work moves through these stages, each producing reviewable evidence:
+
+1. **Discover/scaffold**: derive the template matrix (alias × locale) from the
+   catalogue's `implemented` email entries.
+2. **Preview**: render HTML and plain text from fixtures only, never live
+   customer data.
+3. **Lint**: every placeholder is a declared variable; CTA routes resolve.
+4. **Localize**: every catalogue locale exists in HTML and plain text, with
+   the same variables (see `maggie-content-localization`).
+5. **Approve**: record who approved which template version.
+6. **Sync dry run**: compute the provider diff without writing.
+7. **Publish**: apply the reviewed diff with an explicit confirmation.
+8. **Rollback**: keep the previous provider version ID to restore.
+9. **Verify**: re-run drift; any real send uses a provider test mode or an
+   allow-listed internal recipient, behind an explicit confirmation.
+
+Before every deploy, compare the catalogue, local templates, and a provider
+export. Export **every** page of the provider's template list to JSON first
+(list endpoints paginate; a single call with a page limit can miss templates):
+
+```bash
+maggie ops notifications templates drift --project . \
+  --catalogue docs/notifications/catalogue.json \
+  --local src/emails/templates \
+  --provider-export exports/templates-page-1.json \
+  --provider-export exports/templates-page-2.json
+```
+
+`--local` accepts a directory of `<alias>.<locale>.<ext>` files (placeholders
+`{{ name }}` are extracted) or a `maggie-notification-templates.v1` manifest.
+The report lists missing local/provider templates, extra provider or local
+aliases, locale gaps, undeclared or unused variables, and local/provider
+version drift. It exits non-zero on drift, and when the last export page still
+reports `has_more: true`. A runtime fallback to locally rendered email protects
+delivery but hides drift, so treat drift as a deploy blocker.
+
+## 4. Provider preflight (Resend)
+
+```bash
+maggie ops notifications preflight --project . --env-file .env.production \
+  --catalogue docs/notifications/catalogue.json
+```
+
+Checks, by variable name only: API key, sender (`RESEND_EMAIL`, `RESEND_FROM`,
+or `RESEND_SENDER`), worker secret, support recipients, webhook secret, and
+the template map. Template IDs are not printed. Only the map's alias keys are
+compared with implemented Resend catalogue entries. Add project-specific names
+with `--require NAME`. Presence is not proof of delivery: after deploy, the
+release still needs sender-domain verification, webhook reachability, timer
+health, and an authenticated synthetic delivery recorded as redacted evidence.
+
+## 5. Queue health and alerts
+
+Have the host worker or a read-only SQL job write an aggregate snapshot
+(`maggie-notification-queue-snapshot.v1`) with counts (`pending`,
+`processing`, `deadLetter`, `awaitingWebhook`), `oldestPendingAt`,
+`expiredLeases`, `lastWebhookAt`, `lastSuccessfulRunAt`, optional `rates`
+(`bounce`, `complaint`), and `senderDomainVerified`. Snapshots must not contain
+addresses; the check rejects them if they do.
+
+```bash
+maggie ops notifications health --project . --snapshot .maggie/notifications-health.json \
+  --max-oldest-pending-minutes 30 --max-dead-letter 0
+maggie ops notifications alerts
+```
+
+`health` exits non-zero when any threshold is exceeded, so it can run from a
+systemd timer or CI after the worker. A timer can be active while the worker
+never succeeds, so `lastSuccessfulRunAt` is required. `alerts` prints the
+operator alert templates (severity, owner, recovery action, escalation). Send
+alerts through an operations channel that is independent of the notification
+queue and provider being monitored.
+
+## 6. Privacy, retention, and suppression
+
+The catalogue's `retention` block sets days for `webhook-payload`,
+`delivery-record`, `rendered-snapshot`, and `template-variables`. Store
+minimized webhook fields (event type, provider message ID, status, time), not
+the full raw payload. Keep suppression entries as a hashed address with
+reason and time. Recovery from suppression (for example, a fixed mailbox)
+needs an explicit operator action with a recorded reason.
+
+Plan purges from aggregate counts only:
+
+```bash
+maggie ops notifications retention plan --project . \
+  --catalogue docs/notifications/catalogue.json \
+  --inventory .maggie/notifications-inventory.json
+```
+
+The plan is always a dry run. Rows tied to an open support case or legal hold
+are reported as held. Apply purges through the host's reviewed job or
+migration, and handle account deletion by purging that user's delivery
+records and snapshots and keeping only the hashed suppression entry.

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

@@ -231,6 +231,65 @@ The contract is documented in
 It is provider-neutral and does not accept credentials, provider response
 bodies, or arbitrary filesystem paths in the poll reference.
 
+### Long-running import stages, readiness, and fact provenance
+
+Inside the `import` workflow, a provider import runs four stages: `source`,
+then `enrichment` and `research` in parallel, then `verification`. Validate a
+redacted snapshot with:
+
+```bash
+maggie service import-stages-validate --project . \
+  --manifest .maggie/booking/import-stages.json --output docs/import-stages.json
+```
+
+The `maggie-service-import-stages.v1` contract
+(`contracts/maggie-service-booking/import-stages-v1.schema.json`) requires a
+stage key per stage prefixed with the import ID and reused on retry, bounded
+attempts, `{done, total}` progress (a succeeded stage is complete), and a
+`heartbeatAt` for running stages. A running stage without a heartbeat for more
+than `staleAfterSeconds` makes the import `stale` with an explicit
+`nextAction`. Parallel stages may complete in any order, but a stage may not
+start before its dependencies finish, and a downstream result built from a
+superseded `source.resultRevision` must be marked `resultDiscarded` instead of
+applied. Cancellation must reach every stage; results completed after
+`cancellation.requestedAt` are discarded. The declared import state must match
+the state derived from its stages (`partial` when retries are exhausted after
+some stages succeeded).
+
+Before queuing a long-running provider job, run the worker readiness preflight
+on the worker host. It fails — and the job must not be queued — when a Python
+module is not importable, a browser or matching WebDriver is missing, a crawler
+setting is absent (checked by environment variable name; values are never
+printed), the runtime is not UTF-8, or a country label cannot be normalized to
+ISO 3166 (locale display names and mis-decoded text such as `Königreich` are
+repaired first). A rate-limit probe is a single HEAD request and runs only when
+requested:
+
+```bash
+maggie service import-readiness --project . --python-module selenium \
+  --browser --webdriver --env MAPS_CRAWLER_KEY --country "United Kingdom" \
+  --output docs/import-readiness.json
+```
+
+Imported business facts keep field-level provenance in
+`maggie-service-fact-provenance.v1`
+(`contracts/maggie-service-booking/fact-provenance-v1.schema.json`). A
+user-entered value is authoritative and always wins; provider values carry a
+source, confidence, and reference. Providers that agree corroborate a value;
+providers that disagree above `minConfidence` produce a `needs-review` conflict
+with the policy's proposed choice (`fieldPrecedence` can, for example, prefer
+the website for `websiteUrl`). A provider error is recorded under
+`unavailableSources` and never blocks other providers or fields:
+
+```bash
+maggie service fact-provenance --project . \
+  --facts .maggie/booking/fact-provenance.json --output docs/fact-merge.json
+```
+
+The command exits 1 while conflicts need review; the host review UI reads the
+`maggie-service-fact-merge.v1` artifact and records the reviewer's choice as a
+user-entered value.
+
 `convert-page` imports a normal page as a draft service without inventing
 booking facts. `match-pages` reads filesystem pages plus `docs/pages.json` and
 `docs/page-content.json`, writes candidate evidence to both `.maggie/booking`