@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-skills/maggie-social-share/references/marketing-run.md

@@ -0,0 +1,57 @@
+# Marketing runs, schedule layers, and regulated-content review
+
+A marketing run joins content, Social Share, Ads, and measurement under one
+project-scoped `runId`. It is a reference record: it points at source
+revisions, capability evidence, approvals, mutations, and readbacks by ID and
+never stores provider secrets or large payloads.
+
+Schema: `contracts/maggie-ops/marketing-run-v1.schema.json`
+(`schemaVersion: maggie-marketing-run-v1`). Validate with:
+
+```bash
+maggie tool maggie_marketing_run.py validate .maggie/marketing-runs/<runId>.json
+maggie tool maggie_marketing_run.py layers          # print the layer model
+```
+
+## Run fields
+
+| Field | Purpose |
+|---|---|
+| `runId`, `projectRef` | One project-scoped correlation ID across every channel. |
+| `objective`, `conversion` | What the run is for and which event (and source) proves it. |
+| `channels`, `timezone`, `mode` | Channels involved, the run's IANA zone, and `draft`/`scheduled`/`executing`/`completed`/`cancelled`. |
+| `sourceRevisions` | `{sourceId, revision}` of every content source used. |
+| `capabilityEvidence` | IDs/paths of capability reports (for example a Google capability report). |
+| `approval` | `state`, `actor`, `approvalId`; external mutations require `approved`. |
+| `scheduleLayers` | Named layers (below); a run never carries a single `scheduled_at`. |
+| `mutations` | `{mutationId, kind, channel, status, idempotencyKey, approvalRef}`; external publication and Ads changes need an idempotency key. |
+| `readbacks` | `{readbackId, mutationRef}`; a succeeded mutation needs one before the run is `completed`. |
+| `policy`, `stages` | Regulated-content review (below). |
+
+## Schedule layers
+
+| Layer | Meaning | Owner | Notes |
+|---|---|---|---|
+| `infrastructure` | When a worker wakes up (cron, systemd timer, queue). | Operations | Points at a `maggie_schedule.py` job via `scheduleRef`; never a publish time. |
+| `content_calendar` | When reviewed content or social posts may publish. | Editor/marketer | Social Share's slot queue; `start` required. |
+| `campaign_flight` | When paid campaigns may run and spend. | Ads owner | `start` and `end` required. |
+| `measurement_window` | Collection and attribution period. | Analytics | `start`, `end`, and `lagDays` for conversion lag. |
+
+Every layer declares `timezone`, `owner`, `status`, and a `reconciliation`
+rule describing how its real state is read back. `maggie_schedule.py` jobs are
+always the `infrastructure` layer and reject publish-time fields.
+
+## Regulated-content review
+
+`policy.regulatedContent` is off by default, so existing runs are unchanged.
+When it is on, only the **external publication** action waits for
+`policy.reviewState: approved`. Content delivery and pull (including legacy
+plugins), draft creation, SEO/GEO work, and measurement continue; policy
+labels are additive metadata, never a gate in the delivery path.
+
+The validator fails when:
+
+- a stage other than `external_publication` is `blocked` with reason
+  `policy_review`;
+- an `external_publication` mutation is pending or succeeded before the review
+  is approved.

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

@@ -0,0 +1,152 @@
+# 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.
+
+## Publish contract — `adapters` with `"publishes": true`
+
+An adapter that publishes must declare, in addition to its scope set:
+
+| Field | Meaning |
+|---|---|
+| `limits.text_max` | Provider text limit used by `validate`. |
+| `media.types`, `media.max_bytes` | Accepted media and size budget. |
+| `pending.states`, `pending.max_pending_seconds` | Provider "processing" states and how long a post may stay there before it is treated as failed. |
+| `retry_classes.retryable` / `.terminal` / `.unknown_outcome` | Provider error classes. A timeout is always `unknown_outcome`: the post may already exist. |
+| `idempotency.key_source`, `idempotency.provider_supported` | How the stable key is derived (for example `queue_item_id+revision`) and whether the provider honours it. |
+| `readback.lookup` | `by_idempotency_key` (only when the provider supports keys), `by_marker` (key embedded in the post), or `by_recent_posts`. |
+
+Adapters without `publishes` keep the scope-only shape.
+
+## Publish reconciliation — `reconcile`
+
+`reconcile` reads the publish-attempt log and a provider readback and returns
+one safe action per queue item. It never publishes.
+
+```json
+{
+  "attempts": [{"queue_item_id": "q1", "idempotency_key": "q1:r3", "status": "timeout"}],
+  "readback": {"complete": true, "posts": [{"id": "urn:li:share:1", "marker": "#mg-q1:r3"}]}
+}
+```
+
+```bash
+maggie tool maggie_social_share.py reconcile attempts.json
+```
+
+| Situation | Action |
+|---|---|
+| A readback post carries the item's key or marker | `adopt` it as the published post (timeout-after-success). |
+| An attempt reported a post ID that readback does not show | `verify_readback` before anything else. |
+| Last outcome `timeout`/`pending`/`unknown`, readback incomplete | `await_readback`; no retry. |
+| Same, readback complete and no match | `retry_same_key`. |
+| `failed_retryable` | `retry_same_key`. |
+| `failed_terminal` | `fail`. |
+| Two provider posts for one item, or retries that changed the key | invalid; `resolve_duplicate` (keep the first, delete extras). |
+
+Immediate and scheduled publishing share this one path, so a retry can never
+create a second post.
+
+## Marketing runs and schedule layers
+
+Social work that belongs to a wider campaign is recorded in a
+[marketing run](marketing-run.md) (`maggie-marketing-run-v1`). The slot queue
+above is the `content_calendar` layer; it is never the infrastructure timer
+that wakes the publish worker.

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" }
+  }
+}