@topy-ai/maggie 0.7.47 → 0.7.49

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

@@ -2,7 +2,7 @@
 name: maggie-feedback
 description: Collect, review, and explicitly submit privacy-safe feedback about a Maggie skill run, workflow result, bug, or feature request.
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Maggie Feedback
@@ -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`,
@@ -118,6 +127,63 @@ Example:
       ]
     }
 
+## Feedback types
+
+- `bug`: the skill or CLI did something wrong.
+- `quality`: the result works but falls short (unclear output, weak defaults).
+- `feature`: a missing capability.
+- `improvement`: a concrete proposal to change an existing skill or CLI
+  (a new flag, a better default, a guidance section).
+- `general`: anything else.
+
+The hosted endpoint accepts `bug`, `feature`, `quality`, and `general`. An
+`improvement` draft keeps its type locally and is submitted as `feature` with
+`subtype: "improvement"`, so maintainers can still filter it.
+
+## Draft a batch from a working session
+
+After a long session, draft batch items from the commits made since a known
+point instead of writing them by hand:
+
+```bash
+maggie feedback session-summary --project . \
+  --repo . --since v1.4.0 \
+  --batch-id social-session-2026-10 --skill maggie-social-share
+```
+
+The helper reads commit subjects only (no diffs, paths, or file contents) and
+redacts secrets and local paths. `fix:` commits become fixed `bug` items with a
+`commit:<sha>` evidence reference; `feat:`, `perf:` and `refactor:` commits
+become `improvement` candidates; other commits are skipped and counted. It also
+adds one placeholder for an open ask. It writes a draft batch file under
+`.maggie/feedback/batches/` and does not create or submit feedback.
+
+Review the file: delete items that concern the project rather than a Maggie
+skill or CLI, and replace every `REVIEW:` field (expected, actual, validation).
+`maggie feedback batch` rejects a file that still contains `REVIEW:`
+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-marketplace/SKILL.md

@@ -52,6 +52,18 @@ maggie tool maggie_marketplace.py apply \
   --id medical-spa-landing-30 --project /path/to/astro-project
 ```
 
+Package-quality commands (read-only unless `--write`/`--record`/`--approve`):
+
+```bash
+maggie tool maggie_marketplace.py audit-package <id>          # all package-quality gates, JSON report
+maggie tool maggie_marketplace.py measure-design <id> --write # palette roles + fonts from homepage CSS
+maggie tool maggie_marketplace.py repair-assets <id> --write  # list unlisted assets honestly; add file extensions
+maggie tool maggie_marketplace.py identity <id> --display-name "Olive Atelier" \
+  --display-description "A light editorial beauty homepage with olive accents."
+maggie tool maggie_marketplace.py image-plan <id> --unit-cost 0.04 --currency USD
+maggie tool maggie_marketplace.py image-review <id> [--approve --reviewer NAME | --flag assets/x.png]
+```
+
 The native installer exposes the same operation as
 `maggie marketplace add <template-url> clone <preview-url> --rename <id>`.
 
@@ -95,6 +107,55 @@ validator before it is reported complete. If the validator has changed or the
 artifact drifted, the job becomes `STALE` and must be resumed or rebuilt; do
 not treat an old readiness flag as proof of current validity.
 
+## Package quality gates
+
+`validate` and the completion checkpoint include five package-quality gates.
+`audit-package` runs only these, without the mutating cleanup that `validate`
+performs, so it is safe on any checkout.
+
+1. **Screenshots decode and fit a pixel budget.** Every file in
+   `screenshots/` must fully decode (PNG chunk CRCs and inflated size, JPEG
+   frame/end markers, WebP header; Pillow is used too when installed). A
+   corrupt capture shows as glitch noise and is reported as
+   `recapture-required`; recapture it with `maggie_clone_to_template.py
+   review` — never hand-edit or keep it. The budget is 40 MP per image and
+   16383 px per edge, well under sharp's default `limitInputPixels`
+   (268,402,689 px) and Pillow's decompression-bomb guard, so consumers never
+   need to disable those limits. Ship full-page captures as tiles no taller
+   than 4096 px (`desktop-full-01.png`, `desktop-full-02.png`, …) or as a
+   compressed WebP preview; keep `desktop.png`/`tablet.png`/`mobile.png` at
+   viewport height. `audit-package --record` stores the per-file result in
+   `template.json` `screenshotReview`.
+2. **`DESIGN.md` palette is measured, not inherited.** The palette and fonts
+   come from the template's own CSS: Tailwind config colours and fonts,
+   arbitrary utilities (`bg-[#…]`), the Tailwind neutral scales, body rules,
+   inline and stylesheet declarations, and Google Fonts links.
+   `measure-design --write` rewrites the `### Reference palette` and
+   typography lines, stores `designTokens` (the nine
+   `maggie-palette-roles-v1` roles plus fonts and missing font links) in
+   `template.json`, and fills empty `styleTags` with measured tags
+   (`light-canvas`, `serif-display`, `warm-neutral`, …). Every declared colour
+   must exist in the page CSS and Background/Text primary must match the
+   measured canvas/text; derived contrast-safe roles are labelled `derived`.
+   Check the result against the screenshots before overriding anything.
+3. **Every asset has provenance.** Every image under `assets/` must be listed
+   in `generated-asset-manifest.json` with a provider and role. Captured
+   source images are listed as `provider: captured-source`, `reuse: false`,
+   `replacementRequired: true`; files without a generation record are
+   `provider: unrecorded`, `reuse: false`, `provenanceReview: required`. Both
+   block publishing. Files without an extension are rejected;
+   `repair-assets --write` sniffs the type, renames the file, and rewrites
+   `homepage.html` and `image-inventory.json`.
+4. **Neutral display identity.** `template.json` carries a customer-facing
+   `displayName` and `displayDescription` that are separate from the ID,
+   `name`, and `sourceMetadata`. The name must not repeat a distinctive word
+   from the source title, must not be a counter such as `Beauty Studio 20
+   001`, and must be unique in the catalogue. Completion derives one from the
+   measured design (accent hue, display typeface, industry) when none is
+   given; prefer a reviewed, designed name. `list`, `suggest`, and the catalogue
+   show `displayName`; source titles never appear in customer-facing pickers.
+5. **Generated images pass a no-text review.** See step 4 below.
+
 Each import also creates `tasks.json`. It is the workflow ledger: it stores
 source/output inventories for logos, icons, images, headings, links, buttons,
 visible copy, and Tailwind, plus evidence and status for source analysis,
@@ -222,6 +283,32 @@ role, provider, date, and prompt in `generated-asset-manifest.json`. Validate
 that every PNG/JPEG decodes. Never apply text replacement tools to binary
 assets.
 
+Report cost before and after every generation run, and review every output
+for text. A "no text, no labels" prompt is not a guarantee: product bottles,
+signage, and packaging routinely come back with readable words.
+
+```bash
+# before generating: planned image count and estimated cost
+maggie tool maggie_marketplace.py image-plan <id> --unit-cost <price-per-image> --currency USD
+# after generating: actual count/cost, contact sheet, and text review
+maggie tool maggie_marketplace.py image-review <id>
+# a person checked image-review/contact-sheet.html and found no text
+maggie tool maggie_marketplace.py image-review <id> --approve --reviewer <name>
+# or record a failure, regenerate that asset, and review again
+maggie tool maggie_marketplace.py image-review <id> --flag assets/maggie-hero.png
+```
+
+`image-plan` counts inventory occurrences marked `needs-generation`, pending
+roles, and captured-source assets awaiting replacement. Take the unit cost from
+the provider's current price list; when omitted, the estimate is recorded as
+unknown rather than guessed. `image-review` writes the post-run count and cost,
+`image-review/contact-sheet.html`, and a per-image `textReview` in
+`image-generation-report.json`. When `tesseract` is installed, OCR flags any
+image with readable words; otherwise the review stays `pending-human-review`
+until `--approve`. Completion and `validate` block until the review is
+`passed` and covers every generated asset. These commands make no model or
+paid API calls themselves.
+
 Before generating anything, create `image-inventory.json` from the final
 section structure. Include one record for every logo and image occurrence:
 `id`, source occurrence/line, semantic role, composition, dimensions/aspect
@@ -315,6 +402,10 @@ image references. It also verifies the generated asset roles used by the
 sample. A mismatch blocks `apply` and publish until the template is repaired
 or an explicitly approved `--sample` contract is selected.
 
+The validator also runs the package quality gates above (screenshot
+integrity and budget, measured palette, asset provenance, neutral display
+identity, generated-image text review).
+
 Also parse all JSON and JSON-LD, require exactly one canonical, verify `en-GB`,
 decode every local image, scan for source brand/person/place/phone/social URL
 remnants, confirm no Iconify/platform runtime remains, and inspect desktop,

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-qa-workflow/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-qa-workflow
 description: Run scenario-based browser QA with explicit evidence, fix/retest lifecycle, and release-gate decisions for web projects.
 metadata:
-  version: 1.2.0
+  version: 1.3.0
 ---
 
 # Maggie QA Workflow
@@ -74,6 +74,46 @@ the host browser adapter. The adapter owns console, network, authentication,
 URL, viewport, and screenshot capture; this skill stores only a relative path,
 URL reference, and hash when a local file exists.
 
+## Protect production data
+
+Declare which API the build under test talks to, and mark scenarios that
+write data with `"mutates": true` in the scenario manifest:
+
+```bash
+maggie qa start --project . --run-id local-qa-002 \
+  --environment local --base-url http://localhost:4321 \
+  --api-base https://api.example.com \
+  --production-api https://api.example.com
+```
+
+When the API base is a production API, mutating scenarios start as `blocked`
+and `record` refuses a pass or fail result for them. Run those scenarios
+against a non-production API, or start a run with `--allow-production-writes`
+only after the user explicitly consents and a restore path exists. Overriding
+`window.fetch` from the page does not stop a bundled API client from sending
+requests; use network-layer interception as described in the
+[browser inspection contract](../../references/browser-inspection.md).
+
+## Check CORS for every method the client uses
+
+Before a release that adds or changes API calls from a browser or webview,
+preflight every HTTP method the client sends through the public edge, not only
+the origin server:
+
+```bash
+maggie qa cors-preflight --project . \
+  --url https://api.example.com/v1/setup \
+  --origin https://app.example.com \
+  --method GET,POST,PUT,PATCH,DELETE \
+  --request-header content-type,authorization \
+  --output .maggie/qa-runs/cors-preflight.json
+```
+
+The command sends only `OPTIONS` requests and fails when a method, origin, or
+request header is not allowed. A method missing from the edge allow-list
+fails in the browser with a generic network error (Safari: "Load failed") and
+leaves no request in server logs, so it is easy to misdiagnose.
+
 ## Assert the requirement at runtime
 
 Do not use a source class, edited markup fragment, or implementation detail as

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`
@@ -427,6 +486,29 @@ FAQ helper from the first category implementation; it is a known gap and must
 remain marked incomplete until each FAQ record is independently AI-authored and
 reviewed.
 
+## Payments: Stripe live setup and gift vouchers
+
+Service pages often lead to first-party payments. When the host takes money
+through MaggieDash Booking (rather than the external provider), follow the
+read-only live setup runbook in `docs/maggiedash-booking/STRIPE-INTEGRATION.md`:
+
+- verify live state with list/retrieve (`GET`) calls only; never use a create
+  call as a probe — a probe expected to fail can create a real live object;
+- the owner installs webhook and Connect event-destination signing secrets
+  with a no-echo command (`read -rs … | <secret store>`); the agent never sees
+  them;
+- thin-event destination signing secrets cannot be retrieved via the API;
+  roll them in the Dashboard if they were not captured;
+- the Stripe Dashboard may be unusable under browser automation, so hand
+  Dashboard-only steps to the owner and confirm them with read-only calls.
+
+Gift vouchers (online and at the till, partial redemption, undo, void, expiry,
+refunds, buyer/recipient emails, merchant ledger) follow the host-owned
+`contracts/maggiedash/booking-voucher-lifecycle-v1.json` contract described in
+`docs/maggiedash-booking/VOUCHERS.md`. Do not invent a separate voucher model;
+replay the host's sanitized ledger with
+`maggie booking voucher-contract --ledger FIXTURE`.
+
 ## Gates
 
 The workflow stops when any gate fails:

package/bundled-skills/maggie-social-share/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-social-share
 description: Turn approved AI CMO articles and content assets into platform-native social drafts, scheduled posts, and measured distribution. Use for Social Share planning, LinkedIn/Facebook copy, CTA mapping, calendars, approvals, publish retries, or social performance readback.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Maggie Social Share
@@ -30,6 +30,33 @@ maggie tool maggie_social_share.py validate .maggie/social-share-plan.json
 The CLI does not generate copy or publish. It validates identity, canonical
 URL, channel limits, UTM links, approval state, and provider post state.
 
+Before connecting providers or scheduling, check the adapter, connection,
+campaign, and queue contracts (shapes and rules in
+[queue and connections](references/queue-and-connections.md)):
+
+```bash
+maggie tool maggie_social_share.py adapters .maggie/social-adapters.json
+maggie tool maggie_social_share.py connections .maggie/social-connections.json
+maggie tool maggie_social_share.py campaigns .maggie/social-campaigns.json
+maggie tool maggie_social_share.py queue .maggie/social-queue.json --slots 14
+maggie tool maggie_social_share.py reconcile .maggie/social-attempts.json
+```
+
+A publishing adapter also declares limits, media rules, pending behaviour,
+retry classes (a timeout is an unknown outcome, never retryable), idempotency,
+and readback. `reconcile` turns the attempt log plus provider readback into
+adopt / await / retry-with-the-same-key / fail decisions, so a
+timeout-after-success never creates a duplicate post.
+
+When social work is part of a wider campaign, record it in a
+[marketing run](references/marketing-run.md) with named schedule layers
+(infrastructure, content calendar, campaign flight, measurement window) and,
+for regulated content, a review that gates only external publication:
+
+```bash
+maggie tool maggie_marketing_run.py validate .maggie/marketing-runs/<runId>.json
+```
+
 1. Select an approved or explicitly shareable source article/content asset.
 2. Read Project Context and the selected social tone/template.
 3. Extract one clear content atom: insight, statistic, process, story, or
@@ -37,10 +64,14 @@ URL, channel limits, UTM links, approval state, and provider post state.
 4. Create platform-native variants with the platform's current limits and a
    clear CTA. Preserve the source canonical URL and apply the configured UTM
    policy.
-5. Store drafts as calendar items with source ID, platform, version, approval,
-   scheduled time, and local/remote status.
+5. Store drafts as queue items with source ID, platform, version, approval,
+   optional `not_before`, and local/remote status. Posting hours are slots;
+   do not persist a fixed `scheduled_at` per post (it goes stale and strands
+   overdue posts). Campaign ideas stay in the idea stage until written, and a
+   campaign starts only through the Start gate.
 6. Publish only after the required approval and entitlement checks. Record the
-   publication attempt and provider ID; retry only with bounded idempotency.
+   publication attempt and provider ID; reconcile unknown outcomes against
+   readback and retry only with the original idempotency key.
 7. Read back clicks, engagement, assisted conversions, and failures separately
    from article SEO/GEO metrics.
 
@@ -48,12 +79,30 @@ URL, channel limits, UTM links, approval state, and provider post state.
 
 ```text
 source_content_id, canonical_url, platform, format, hook, body, cta,
-hashtags_or_mentions, scheduled_at, approval_state, tracking_url
+hashtags_or_mentions, not_before, queue_position, campaign_id, approval_state,
+tracking_url
 ```
 
+`not_before` is optional and only a lower bound; the slot planner assigns the
+actual publish slot.
+
 Start with LinkedIn and Facebook adapters. Add other platforms only when the
-adapter can declare limits, auth scope, media requirements, idempotency, and
-delete/republish behavior.
+adapter can declare limits, one canonical auth scope set, media requirements,
+idempotency, and delete/republish behavior.
+
+## Connections
+
+- Every connect path (dashboard, mobile, CLI) requests the adapter's canonical
+  scope set. LinkedIn revokes a member's earlier tokens when a sign-in asks
+  for a different set; a shared OAuth client used by other products can do
+  the same. `adapters` fails on scope drift and warns on shared clients.
+- A connection whose token the provider revoked, or that a serving host cannot
+  decrypt, shows **Reconnect** before anything is scheduled on it. Run the
+  decrypt check on every host that serves social routes.
+- Provider avatar URLs are signed and expire; cache the bytes or refresh on
+  readback.
+- Keep model structured-output enums small and validate large vocabularies
+  server-side; see [provider adapter contract](../../references/provider-adapter-contract.md#structured-model-output).
 
 ## Safety and commercial boundary