@topy-ai/maggie 0.7.47 → 0.7.48

package/bundled-skills/maggie-clone-to-template/SKILL.md

@@ -67,6 +67,32 @@ then stores the prompt as
 `CUSTOMIZATION_PROMPT.md` beside the package. It creates a resumable job under
 `marketplace/.maggie/clone-to-template-jobs/`.
 
+### Neutral display identity
+
+A package's customer-facing identity is separate from its source evidence.
+`template.json` `name` and `id` are internal; `sourceMetadata` records the
+source title only as provenance. Pass a designed, neutral style name and a short
+description when planning:
+
+```bash
+maggie tool maggie_clone_to_template.py plan <url> "<approved brief>" --rename <template-id> \
+  --display-name "Olive Atelier" \
+  --display-description "A light editorial beauty homepage with olive accents."
+```
+
+Packaging forwards both to the marketplace importer. Without them, completion
+derives a name from the measured design (accent hue, display typeface,
+industry). The validator rejects a name that repeats a distinctive source-title
+word, looks like a counter (`Beauty Studio 20 001`), or duplicates another
+catalogue entry. Change it later with `maggie_marketplace.py identity <id>
+--display-name …`. Template pickers must show `displayName` and
+`displayDescription`, never the source business name.
+
+Packaging also measures `DESIGN.md` from the rendered CSS, records
+`screenshotReview`, and lists every asset with its provenance. Review captures
+stay at viewport height; tile any full-page capture as described in the
+`maggie-marketplace` package quality gates.
+
 If the full clone run fails or cannot reach `verified`, stop and report the
 clone checkpoint. Do not invoke the marketplace importer as a fallback. If the
 Maggie design review fails, stop before declaring the template ready.

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.4.0
+  version: 1.5.0
 ---
 
 # Maggie Deployment
@@ -239,6 +239,58 @@ maggie tool maggie_deployment.py --retention-plan \
 The CLI never deletes release directories and never permits fewer than two
 retained releases.
 
+### Multi-host secret parity
+
+When several hosts serve the same routes, check that each one holds every
+required secret. The check compares key names and SHA-256 fingerprints and
+never prints, stores, or transmits values:
+
+```bash
+# Local env files (one per host):
+maggie deployment secret-parity \
+  --host api-1=.secrets/api-1.env --host api-2=.secrets/api-2.env \
+  --required SOCIAL_SHARE_ENCRYPTION_KEY
+
+# Or fingerprint manifests produced on each host:
+maggie deployment secret-fingerprint --env-file /etc/example.env \
+  --host api-1 --output api-1.json
+maggie deployment secret-parity --manifest api-1.json --manifest api-2.json \
+  --required SOCIAL_SHARE_ENCRYPTION_KEY
+```
+
+A required key that is missing or differs on any host fails the check. Other
+drifting keys are warnings unless `--strict` is set. A host without Maggie can
+use the no-echo shell snippet in [the VPS reference](references/vps.md); the
+parity command accepts its `KEY <sha256>` output directly. Manifests that
+contain anything other than names and 64-character hex digests are rejected.
+
+### Local and production database isolation
+
+```bash
+maggie deployment env-isolation --project . \
+  --production-env .env.production
+# or: --production-db-host db.example.net
+```
+
+The check fails when the local `.env` points at the production database (same
+host, and port/name when known). The same server with a different database is
+a warning. Deployment preflight runs the check automatically, as a non-blocking
+warning, when `.env.production` exists or `MAGGIE_PRODUCTION_DB_HOST` is set.
+Database URLs are reduced to host/port; credentials are never reported.
+
+### Release ordering for workers and notification templates
+
+Deploy the worker and its templates before any code path can enqueue an event
+that uses a new template. When local development or a staged app shares a
+queue with production, an event that names a template the running worker does
+not know yet must be held and retried, not dead-lettered: an unknown template
+during a rollout is a release-ordering state, not a permanent failure. Check
+that the outbox worker (MaggieDash Booking or the host's own) does not let
+unknown-template deliveries consume the retry budget, and after the release
+confirm the held deliveries were sent.
+If dead-lettered rows already exist, requeue them only after the worker that
+knows the template is live.
+
 Validate the database release separately before a VPS migration:
 
 ```bash

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

@@ -132,6 +132,47 @@ inspect → plan → backup/migrate → npm ci → npm run build
 Deploy staging first. A passing build does not prove Nginx, systemd, DNS, TLS,
 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,
+`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.
+
+### Multi-host secret parity
+
+When more than one host can serve the same routes (failover, load-balanced API
+nodes, workers), every host must hold the same required secrets. A key that
+exists on only one host is invisible until traffic fails over to another and
+returns 5xx. Compare hosts by name and SHA-256 fingerprint, never by value:
+
+```bash
+# On each host (prints names and digests only; values are never echoed):
+for k in SOCIAL_SHARE_ENCRYPTION_KEY DATABASE_URL; do
+  v=$(sed -n "s/^$k=//p" /etc/example.env | head -1)
+  printf '%s %s\n' "$k" "$(printf %s "$v" | sha256sum | cut -c1-64)"
+done > /tmp/api-1.fingerprints
+
+# Locally, after copying each host's fingerprint file:
+maggie deployment secret-parity \
+  --manifest api-1.fingerprints --manifest api-2.fingerprints \
+  --manifest api-3.fingerprints \
+  --required SOCIAL_SHARE_ENCRYPTION_KEY --required DATABASE_URL
+```
+
+Run it after adding a secret and before enabling a host in a pool.
+
+### Environment isolation
+
+A local `.env` must never point at the production database. Shared databases
+let local test records (vouchers, palettes, emails) appear on live pages and be
+picked up by production workers. `maggie deployment env-isolation` fails when
+the local database host, port, and name match production.
+
 ## Verification and rollback
 
 Verify the homepage, changed service routes, `/robots.txt`, `/sitemap.xml`,

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

@@ -285,6 +285,57 @@ all required camera states, and valid PNGs at 390px, 768px, and desktop
 widths. The machine-readable contract is
 [mobile-app-surface-v1.schema.json](../../bundled-contracts/maggie-design/mobile-app-surface-v1.schema.json).
 
+### Onboarding wizards
+
+Use one pattern for multi-step setup (brand, logo, voice, posting hours, and
+similar first-run flows) instead of designing each flow ad hoc:
+
+- A segmented progress bar with one segment per step; the current step is
+  visibly distinct and completed steps are tappable.
+- Each step shows Maggie (or the product guide) with exactly one headline and,
+  at most, one supporting line. Put help in the control, not in paragraphs.
+- Record step state on the server (`pending`, `done`, `skipped`) after every
+  step, and resume from the first unfinished step on any device. Local state
+  alone loses progress on reinstall or a second device.
+- Every optional step offers **Later**. A skipped step reopens on the next
+  sign-in until it is done or explicitly dismissed; never block the app on it.
+- Completed steps keep a redo action (for example "Retrain voice" or
+  "Choose another logo") that reopens that step with the saved value
+  preselected, without restarting the wizard.
+- The primary action stays in the fixed footer; Back never discards saved
+  server state.
+
+### Pickers with previews
+
+For choices that need to be seen (logo styles, templates, palettes, voices):
+
+- The list sheet shows a thumbnail, name, and selection state per row; the
+  row itself selects, and a separate preview control opens a larger view.
+- The large preview opens as a sheet nested in the list sheet, so dismissing
+  it returns to the same scroll position in the list. It offers **Use this**
+  and close; it never replaces the list route.
+- Thumbnails are generated or cached assets, not live renders of every option.
+
+### React Native Web pressables
+
+React Native Web renders `Pressable` and the `Touchable*` family as button-like
+DOM elements. A chip with a nested remove control becomes `<button>` inside
+`<button>`: the DOM is invalid, browsers repair it differently, and taps land
+on the wrong control (for example, removing a tag opens its preview). Render
+the chip body and its remove control as **sibling** pressables inside a plain
+`View`, each with its own accessible label. The same rule applies to `<a>`
+and `<button>` on the web.
+
+Run the static check before browser QA; it scans `.tsx`/`.jsx`, skips build
+and dependency folders, and treats `asChild` wrappers (such as an expo-router
+`Link`) as a pass-through:
+
+    maggie design pressable-check --project . [--pressable Chip --pressable IconButton]
+
+Pass `--pressable` for project components that render a pressable. A rare,
+reviewed exception can carry `maggie-allow-nested-pressable` in a comment on
+the inner element's line.
+
 ## Explicit homepage rebrand mode
 
 The homepage `review` mode only compares screenshots. It does not rebrand a
@@ -543,6 +594,54 @@ collapsed-rail, mobile-drawer, and modal evidence. Sample plans require
 noindex, sitemap exclusion, a visible sample banner, placeholders, and a
 finish checklist.
 
+### Tailwind v4 cascade layers
+
+Tailwind v4 emits utilities inside `@layer utilities`. An unlayered rule beats
+every layered rule regardless of specificity, so an unlayered
+`h1, h2, h3 { font-family: … }` silently defeats template `font-*` utilities,
+and an unlayered icon runtime rule such as `.ph { display: inline-block }`
+defeats `hidden` and `group-open:inline` (a mobile menu then shows both the
+open and close icons). Static class checks pass; only a browser shows it.
+
+- Put app-wide element rules (headings, links, body copy) in `@layer base`.
+- Put icon-font runtime rules and component classes in `@layer components`,
+  or import the icon stylesheet with `@import "./icons.css" layer(components);`.
+- Keep `@theme`, `@utility`, and `@font-face` as they are; they are not
+  competing rules.
+
+Run the static check whenever CSS or the icon package changes:
+
+    maggie design layer-check --project .
+
+It runs only when an `@import "tailwindcss"` entry exists (or with
+`--tailwind-v4`), honours `@layer` blocks and `layer(...)` imports, and fails on
+unlayered element or icon rules that set utility-competing properties.
+Unlayered `html`/`body` rules and class rules that set `display` are reported
+as warnings. Keep `css-cascade-check` for the rendered-browser proof.
+
+### Palette role contract
+
+A template that offers brand colour choices exposes semantic roles instead of
+raw hex values in markup: `canvas`, `panel`, `soft`, `text`, `accent`,
+`accentText`, `onAccent`, `dark`, and `deep`. Bind them to CSS variables (for
+example `--color-canvas`) so a palette swap never edits markup. The generator
+keeps the signature palette and derives named variants by moving hue while
+keeping lightness; neutrals never gain chroma, accent saturation is capped
+(uncapped variants turn garish), `accentText` is forced to 4.5:1 on canvas,
+and `onAccent` is the most legible of white, deep, text, and canvas:
+
+    maggie design palette generate --template <template-id> \
+      --canvas '#F7F3EE' --text '#1F1B16' --accent '#B5651D' \
+      [--roles roles.json] [--count 17] [--max-saturation 0.65] \
+      --output design/palettes.json
+    maggie design palette validate --palette design/palettes.json
+
+Measure the signature roles from the template's rendered CSS, not from a
+reference palette. Generation stops if the signature itself fails the
+contrast rules; fix the signature rather than lowering the threshold. The
+contract is
+[palette-roles-v1.schema.json](../../bundled-contracts/maggie-design/palette-roles-v1.schema.json).
+
 For generated or converted pages, run the markup gate before handing the page
 to a host editor:
 

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
@@ -118,6 +118,43 @@ 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.
+
 ## 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-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

@@ -427,6 +427,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

@@ -30,6 +30,17 @@ 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
+```
+
 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,8 +48,11 @@ 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.
 7. Read back clicks, engagement, assisted conversions, and failures separately
@@ -48,12 +62,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