@topy-ai/maggie 0.7.46 → 0.7.48

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
 

package/bundled-skills/maggie-social-share/references/queue-and-connections.md

@@ -0,0 +1,101 @@
+# Social Share queue, campaigns, and connections
+
+All commands read one redacted JSON document, make no provider or model calls,
+and print a JSON report. Validation commands exit `1` when the contract fails.
+
+## Adapter scope contract — `adapters`
+
+```json
+{
+  "adapters": [{
+    "provider": "linkedin",
+    "canonical_scopes": ["openid", "profile", "email", "w_member_social"],
+    "client_id_ref": "linkedin-app-main",
+    "connect_paths": [
+      {"id": "dashboard", "scopes": ["openid", "profile", "email", "w_member_social"]},
+      {"id": "mobile", "scopes": ["openid", "profile", "email", "w_member_social"]}
+    ],
+    "redirect_uris": ["https://app.example.com/oauth/linkedin/callback"],
+    "client_shared_with": []
+  }]
+}
+```
+
+- Fails when any connect path requests a scope set different from
+  `canonical_scopes` (order is ignored). LinkedIn revokes a member's earlier
+  tokens when a sign-in requests a different scope set.
+- Fails when secret fields (`client_secret`, tokens) appear in the manifest.
+  `client_id_ref` is a label, not the credential.
+- Warns when the OAuth client is shared with other products, or redirect URIs
+  span several hosts without a `client_shared_with` record.
+
+## Connection health — `connections`
+
+```json
+{"connections": [{
+  "id": "conn-1", "provider": "linkedin", "status": "active",
+  "token_decryptable": true,
+  "provider_check": {"status": "valid", "checked_at": "2026-10-10T08:00:00Z"},
+  "avatar_url": "https://media.licdn.com/dms/image/...?...&e=1790000000",
+  "avatar_cached": false, "avatar_refresh_on_read": false,
+  "scheduled_items": 4
+}]}
+```
+
+- `status` is derived: `needs_reconnect` when the token cannot be decrypted on
+  the serving host or the provider reports it `revoked`/`invalid`/`expired`.
+  A stored `active` that should be `needs_reconnect` fails, and the report
+  counts scheduled items that would otherwise fail at publish time.
+- Run the decrypt check on every host that serves social routes; a missing
+  encryption key on a failover host looks exactly like an undecryptable token.
+- A signed, expiring avatar URL (LinkedIn `e=`, Meta `oe=`, S3/GCS signed
+  URLs) fails unless `avatar_cached` (bytes in owned storage) or
+  `avatar_refresh_on_read` is true. Use `--now` for deterministic checks.
+
+## Campaign idea stage — `campaigns`
+
+```text
+idea (planned, no copy) --write (1 credit)--> written (draft_id) --all written + start_day + posts_per_day--> Start
+```
+
+- Ideas are visible and manageable on every client (dashboard and mobile), not
+  only where they were planned. Written drafts keep their `campaign_id`.
+- A campaign can start only when every idea is `written` with a `draft_id`,
+  orders are unique integers, `start_day` is a date, and `posts_per_day >= 1`.
+  The report lists blockers; a `started` campaign with blockers fails.
+
+## Slot-based posting queue — `queue`
+
+Posts do not carry a fixed publish time. The person's posting hours are slots:
+
+```json
+{
+  "timezone": "Europe/London",
+  "posting_hours": {"mon": ["09:00", "17:00"], "wed": ["12:30"]},
+  "queue": [{"id": "post-7", "queued_at": "2026-10-09T10:00:00Z", "not_before": null}],
+  "campaigns": [{"id": "autumn", "status": "started", "start_day": "2026-10-12", "posts_per_day": 1,
+                 "ideas": [{"id": "i1", "order": 1, "status": "written", "draft_id": "post-31"}],
+                 "posted_idea_ids": []}]
+}
+```
+
+```bash
+maggie tool maggie_social_share.py queue queue.json --from 2026-10-12T00:00:00Z --slots 14
+```
+
+Rules the planner applies, in order:
+
+1. Each slot (local wall time in `timezone`) posts at most one item.
+2. The standalone queue is newest-first: a new post goes to the front.
+3. A stored time is `not_before` only. An overdue item is simply eligible; it
+   is never stranded behind a past `scheduled_at`.
+4. A started campaign publishes written ideas in idea order from `start_day`,
+   at most `posts_per_day` per local day.
+5. The standalone queue and each started campaign take turns (round-robin);
+   a source with nothing eligible is skipped for that slot.
+6. Wall times keep their local meaning across DST. A time that does not exist
+   (spring-forward gap) is skipped and reported; an ambiguous time uses its
+   first occurrence.
+
+The plan is advisory output for the host scheduler, which re-plans after every
+publish, approval, or queue edit instead of persisting stale per-post times.

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

@@ -28,9 +28,10 @@ maggie tool maggie_marketplace.py apply \
   --id medical-spa-landing-001 --project /path/to/astro-project
 ```
 
-`list` shows ID, lifecycle status, industries, and style tags. `suggest`
-matches the user's brief against those fields and ranks published entries
-first. `inspect` returns metadata and available artifacts. `apply` validates
+`list` shows ID, the neutral `displayName`, lifecycle status, industries, and
+style tags. Show customers the `displayName` and `displayDescription`, never the
+source title in `sourceMetadata`. `suggest` matches the user's brief against
+those fields and ranks published entries first. `inspect` returns metadata and available artifacts. `apply` validates
 the template, writes a namespaced reference to `.maggie/marketplace/<id>/`,
 copies the homepage, assets, screenshots, and `DESIGN.md`, and records
 `.maggie/template-selection.json`. It does not silently overwrite application
@@ -39,6 +40,59 @@ routes.
 Draft entries are for review only. Use `--allow-draft` only when the user
 explicitly wants to preview an unpublished template.
 
+## Preview studio
+
+Compare a template across viewports and palettes before applying it:
+
+```bash
+maggie tool maggie_marketplace.py measure-design <id> --palette-roles /tmp/<id>-palettes.json
+maggie tool maggie_design.py palette generate --roles /tmp/<id>-palettes.json \
+  --template <id> --output /tmp/<id>-palettes.json   # optional: contrast-safe variants
+maggie tool maggie_marketplace.py studio <id> --palettes /tmp/<id>-palettes.json
+maggie tool maggie_marketplace.py studio <id> --palettes /tmp/<id>-palettes.json --check-overflow [--palette <variant-id>]
+```
+
+`studio` writes `.maggie/template-studio/<id>/index.html` under the
+marketplace root: the homepage in scaled frames at 390, 768, 1024, and
+1440 px, a palette dropdown fed by a `maggie-palette-roles-v1` file (the
+measured signature when none is given), and labels on sample copy. Each label
+links to `content-fields.html`, which names the `maggie-template-content-v1`
+field and where the owner replaces it. Elements marked
+`data-maggie-sample="hero.headline"` are labelled exactly; otherwise headings,
+contact links, and section headings are matched heuristically. A palette is
+applied by swapping the signature role colours for the variant's and by
+setting `--maggie-<role>` CSS variables. Open `#<palette-id>` to link a variant.
+
+Serve the marketplace root over HTTP (`python3 -m http.server`) to view it.
+`--check-overflow` serves it locally, renders it with headless Chrome, writes
+`overflow-report.json`, and exits non-zero when any viewport has horizontal
+overflow, naming up to five offending elements. Templates that load Tailwind or
+fonts from a CDN need network access for a faithful render.
+
+## Data-driven component export
+
+A template reused across many businesses must render data, not hand-edited
+copy. The neutral content contract is
+[`contracts/maggie-marketplace/template-content-v1.schema.json`](../../bundled-contracts/maggie-marketplace/template-content-v1.schema.json)
+(`brand`, `contact`, `hero`, `categories` with `services`, `about`, `gallery`,
+`reviews`, `hours`, `faqs`, plus `samples` and an optional palette). An example
+is in [`references/template-content-v1.example.json`](references/template-content-v1.example.json).
+
+```bash
+maggie tool maggie_marketplace.py content-validate --input content.json
+maggie tool maggie_marketplace.py content-css --input content.json   # :root { --maggie-<role>: … }
+```
+
+`content-validate` enforces the business rules the schema cannot: service
+prices and durations, `HH:MM` opening hours, reviews that carry a `source` or
+are explicitly `sample: true` (never invent reviews), and `samples` paths that
+resolve. Export path: build one Astro component per template that takes the
+content object as props, maps each `[data-maggie-sample]` region to its
+content field, and reads colours from the `--maggie-<role>` variables emitted
+by `content-css`. Converting the existing marketplace templates into such
+components is not automated yet; do it per template and keep the static
+`homepage.html` as the visual reference.
+
 ## Selection workflow
 
 Use the deterministic marketplace CLI for listing, recommendation, inspection,

package/bundled-skills/maggie-template/references/template-content-v1.example.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": "maggie-template-content-v1",
+  "brand": { "name": "Maggie Studio", "tagline": "Considered care in London", "logo": { "src": "assets/maggie-mark.png", "alt": "Maggie Studio" } },
+  "contact": { "phone": "020 0000 0000", "email": "hello@example.co.uk", "address": "1 Example Street, London", "bookingUrl": "/book" },
+  "hero": {
+    "headline": "Calm, personalised treatments",
+    "subheadline": "Book facials, massage and body treatments online.",
+    "image": { "src": "assets/maggie-hero.png", "alt": "Treatment room" },
+    "cta": { "label": "Book now", "href": "/book" }
+  },
+  "categories": [
+    {
+      "name": "Facials",
+      "services": [
+        { "name": "Signature facial", "price": 85, "currency": "GBP", "durationMinutes": 60, "bookingRef": null },
+        { "name": "Express facial", "price": 50, "currency": "GBP", "durationMinutes": 30, "bookingRef": null }
+      ]
+    }
+  ],
+  "about": { "heading": "About us", "body": "A small team offering unhurried appointments.", "image": null },
+  "gallery": [{ "src": "assets/maggie-care-team.png", "alt": "Care team" }],
+  "reviews": [{ "quote": "Thoughtful and relaxing.", "author": "A. Client", "rating": 5, "sample": true }],
+  "hours": [
+    { "day": "mon", "opens": "09:00", "closes": "18:00" },
+    { "day": "sun", "closed": true }
+  ],
+  "faqs": [{ "question": "Do you take walk-ins?", "answer": "Please book online so we can prepare your room." }],
+  "samples": ["brand.name", "contact.phone", "contact.email", "contact.address", "hero.headline", "reviews.0"],
+  "palette": {
+    "id": "signature",
+    "name": "Signature",
+    "roles": { "canvas": "#FDFBF7", "panel": "#FFFFFF", "soft": "#F2EFE9", "text": "#2A241E", "accent": "#2D5A27", "accentText": "#2D5A27", "onAccent": "#FFFFFF", "dark": "#2D5A27", "deep": "#000000" }
+  }
+}