@topy-ai/maggie 0.7.48 → 0.7.49

package/bundled-contracts/maggie-ops/notification-catalogue-v1.schema.json

@@ -0,0 +1,273 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/maggie-ops/notification-catalogue-v1.schema.json",
+  "title": "Maggie website notification catalogue v1",
+  "description": "Provider-neutral catalogue of every website email, in-app and SMS notification. Validated by `maggie ops notifications catalogue validate`, which also enforces cross-field rules (marketing consent/unsubscribe/queue, operations alerts on the operations queue, durable outbox for external lead email).",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "retention",
+    "entries"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "maggie-notification-catalogue.v1"
+    },
+    "project": {
+      "type": "string"
+    },
+    "retention": {
+      "type": "object",
+      "required": [
+        "webhook-payload",
+        "delivery-record",
+        "rendered-snapshot",
+        "template-variables"
+      ],
+      "properties": {
+        "webhook-payload": {
+          "type": "object",
+          "required": [
+            "days"
+          ],
+          "properties": {
+            "days": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "storeRawPayload": {
+              "type": "boolean"
+            },
+            "minimizedFields": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "delivery-record": {
+          "type": "object",
+          "required": [
+            "days"
+          ],
+          "properties": {
+            "days": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "storeRawPayload": {
+              "type": "boolean"
+            },
+            "minimizedFields": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "rendered-snapshot": {
+          "type": "object",
+          "required": [
+            "days"
+          ],
+          "properties": {
+            "days": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "storeRawPayload": {
+              "type": "boolean"
+            },
+            "minimizedFields": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "template-variables": {
+          "type": "object",
+          "required": [
+            "days"
+          ],
+          "properties": {
+            "days": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "storeRawPayload": {
+              "type": "boolean"
+            },
+            "minimizedFields": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "entries": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "alias",
+          "section",
+          "trigger",
+          "audience",
+          "category",
+          "consent",
+          "locales",
+          "variables",
+          "idempotencyKey",
+          "retentionDays",
+          "provider",
+          "channels",
+          "status",
+          "delivery",
+          "queue"
+        ],
+        "properties": {
+          "alias": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9._-]{0,99}$"
+          },
+          "section": {
+            "enum": [
+              "identity-security",
+              "account",
+              "business",
+              "billing",
+              "support",
+              "marketing",
+              "deliverability-ops"
+            ]
+          },
+          "trigger": {
+            "type": "string",
+            "minLength": 1
+          },
+          "audience": {
+            "enum": [
+              "visitor",
+              "user",
+              "merchant",
+              "team",
+              "operator"
+            ]
+          },
+          "category": {
+            "enum": [
+              "transactional",
+              "support",
+              "marketing"
+            ]
+          },
+          "consent": {
+            "enum": [
+              "not-required",
+              "opt-in-required",
+              "operator-only"
+            ]
+          },
+          "locales": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "string"
+            }
+          },
+          "markets": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "variables": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,63}$"
+            }
+          },
+          "cta": {
+            "type": [
+              "object",
+              "null"
+            ],
+            "properties": {
+              "label": {
+                "type": "string"
+              },
+              "route": {
+                "type": "string"
+              }
+            }
+          },
+          "idempotencyKey": {
+            "type": "string",
+            "pattern": "\\{"
+          },
+          "retentionDays": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "provider": {
+            "type": "string"
+          },
+          "channels": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "enum": [
+                "email",
+                "in-app",
+                "sms"
+              ]
+            }
+          },
+          "status": {
+            "enum": [
+              "implemented",
+              "provider-owned",
+              "reserved",
+              "missing"
+            ]
+          },
+          "delivery": {
+            "enum": [
+              "outbox",
+              "direct",
+              "provider"
+            ]
+          },
+          "queue": {
+            "enum": [
+              "user",
+              "operations",
+              "marketing"
+            ]
+          },
+          "lead": {
+            "type": "boolean"
+          },
+          "unsubscribe": {
+            "type": "boolean"
+          },
+          "frequency": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggie-service-booking/fact-provenance-v1.schema.json

@@ -0,0 +1,128 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/service-fact-provenance-v1.json",
+  "title": "Maggie field-level provenance for imported business facts",
+  "description": "Per-field evidence from the user and from providers (Fresha, Google, website, ...). User-entered values are authoritative. Provider disagreement above policy.minConfidence becomes a needs-review conflict; a provider error is recorded and never blocks other sources. Merge with `maggie service fact-provenance`, which writes a maggie-service-fact-merge.v1 artifact for the host review UI.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "entityId",
+    "fields"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "maggie-service-fact-provenance.v1"
+    },
+    "entityId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "policy": {
+      "type": "object",
+      "properties": {
+        "precedence": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "prefixItems": [
+            {
+              "const": "user"
+            }
+          ],
+          "minItems": 1
+        },
+        "fieldPrecedence": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "prefixItems": [
+              {
+                "const": "user"
+              }
+            ],
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "minConfidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "fields": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "$ref": "#/$defs/field"
+      }
+    }
+  },
+  "$defs": {
+    "field": {
+      "type": "object",
+      "properties": {
+        "user": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "required": [
+            "value"
+          ],
+          "properties": {
+            "value": {},
+            "at": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "actor": {
+              "type": "string"
+            }
+          }
+        },
+        "sources": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "source"
+            ],
+            "properties": {
+              "source": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_-]{0,39}$",
+                "not": {
+                  "const": "user"
+                }
+              },
+              "value": {},
+              "confidence": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "observedAt": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "sourceRef": {
+                "type": "string",
+                "description": "public page or record reference; never credentials"
+              },
+              "error": {
+                "type": "string",
+                "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/bundled-contracts/maggie-service-booking/import-stages-v1.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/service-import-stages-v1.json",
+  "title": "Maggie provider-neutral multi-stage service import state",
+  "description": "One import runs source, enrichment, research and verification stages. Stage keys are idempotent and reused on retry; running stages heartbeat and become stale after staleAfterSeconds; downstream stages record the source revision they consumed so superseded (out-of-order) results are discarded; cancellation is propagated to every stage and late results are discarded. Validate with `maggie service import-stages-validate`.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "importId",
+    "idempotencyKey",
+    "state",
+    "staleAfterSeconds",
+    "stages"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "maggie-service-import-stages.v1"
+    },
+    "importId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"
+    },
+    "idempotencyKey": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"
+    },
+    "provider": {
+      "type": "string"
+    },
+    "state": {
+      "enum": [
+        "queued",
+        "running",
+        "succeeded",
+        "partial",
+        "failed",
+        "cancelled",
+        "stale"
+      ]
+    },
+    "staleAfterSeconds": {
+      "type": "integer",
+      "minimum": 30,
+      "maximum": 86400
+    },
+    "evaluatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "nextAction": {
+      "type": "string",
+      "minLength": 1
+    },
+    "cancellation": {
+      "type": "object",
+      "properties": {
+        "requested": {
+          "type": "boolean"
+        },
+        "requestedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "propagated": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "stages": {
+      "type": "array",
+      "minItems": 4,
+      "maxItems": 4,
+      "items": {
+        "$ref": "#/$defs/stage"
+      }
+    }
+  },
+  "$defs": {
+    "stage": {
+      "type": "object",
+      "required": [
+        "name",
+        "stageKey",
+        "state",
+        "attempt",
+        "maxAttempts",
+        "progress"
+      ],
+      "properties": {
+        "name": {
+          "enum": [
+            "source",
+            "enrichment",
+            "research",
+            "verification"
+          ]
+        },
+        "stageKey": {
+          "type": "string",
+          "description": "<importId>:<stage>[:<input hash>]; reused on retry"
+        },
+        "dependsOn": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "source",
+              "enrichment",
+              "research",
+              "verification"
+            ]
+          },
+          "description": "defaults: enrichment/research -> source; verification -> enrichment, research"
+        },
+        "state": {
+          "enum": [
+            "queued",
+            "running",
+            "succeeded",
+            "failed",
+            "skipped",
+            "cancelled"
+          ]
+        },
+        "attempt": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "maxAttempts": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "progress": {
+          "type": "object",
+          "required": [
+            "done",
+            "total"
+          ],
+          "properties": {
+            "done": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "total": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "heartbeatAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "completedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "resultRevision": {
+          "type": [
+            "string",
+            "integer"
+          ],
+          "description": "source stage: revision of its current result"
+        },
+        "inputRevision": {
+          "type": [
+            "string",
+            "integer"
+          ],
+          "description": "downstream stages: source revision consumed"
+        },
+        "resultDiscarded": {
+          "type": "boolean"
+        },
+        "errorCode": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/bundled-references/google-integrations-runbook.md

@@ -119,6 +119,60 @@ selected `resource`. A report that only proves account discovery, or comes from
 the wrong browser account/property, is rejected before a write workflow can use
 it.
 
+## Failure remediation
+
+A failed check must name the one prerequisite that failed, not a generic
+"access denied". Put only the provider error code/reason and HTTP status in the
+row's optional `failure` field; the validator returns `remediation` with a
+stable `code`, the failed `prerequisite`, and one safe `nextAction`. It never
+echoes the input text. `maggie ops google-diagnose` applies the same mapping to
+one error.
+
+| Signal | Failed prerequisite | Safe next action |
+|---|---|---|
+| `invalid_scope` (ADC) | OAuth scope request | Re-run the ADC/impersonation command with the exact allowlisted scope |
+| `ACCESS_TOKEN_SCOPE_INSUFFICIENT` | Granted token scope | Mint a new token that includes the provider scope |
+| `redirect_uri_mismatch` | OAuth client redirect URI | Add the exact callback URL to the client, or use the client that lists it |
+| Consent screen not configured / app not verified | OAuth consent configuration | Configure user type, test users, or verification in the client's project |
+| `SERVICE_DISABLED` / `accessNotConfigured` | Cloud API enablement | Enable the API in the project that owns the client or service account |
+| `RESOURCE_EXHAUSTED` / HTTP 429 | Provider quota | Stop retrying; wait for the window or request quota; record `blocked` |
+| `DEVELOPER_TOKEN_PARAMETER_MISSING` | Ads developer token | Install the token in the host secret store; send the `developer-token` header |
+| `DEVELOPER_TOKEN_NOT_APPROVED` | Ads token access level | Apply for Basic/Standard access, or use a test account |
+| `DEVELOPER_TOKEN_PROHIBITED` | Developer token/project pairing | Use the OAuth client from the paired Cloud project, or request access for the new project |
+| `USER_PERMISSION_DENIED` with a manager | `login-customer-id` | Set it to the manager that links the target, or omit it for direct access |
+| `USER_PERMISSION_DENIED` / `CUSTOMER_NOT_FOUND` | Ads account access | Grant the user access to the customer or its manager |
+| GA4 "insufficient permissions for this property" | GA4 property membership | Add the principal to the property with Viewer or higher |
+| `iam.serviceAccounts.getAccessToken` denied | Service-account impersonation | Grant `roles/iam.serviceAccountTokenCreator` on the target service account |
+| Other `PERMISSION_DENIED` / HTTP 403 | Product role | Grant the product-level role; Cloud IAM alone is insufficient |
+| `invalid_grant` / HTTP 401 | Credential validity | Reconnect; the stored token is expired or revoked |
+
+## Google Ads read-only preflight and Keyword Planner
+
+`maggie ops google-ads-preflight` checks, in order and independently: customer
+and `login-customer-id` format (10 digits; hyphens stripped), developer-token
+presence (environment variable name only), the `adwords` scope via token
+introspection (token sent in a POST body, never a URL),
+`customers:listAccessibleCustomers`, the manager hierarchy through
+`customer_client` when a manager is used, a `customer` read (currency, manager,
+test-account flags), and Keyword Planner readiness. The Keyword Planner check
+reports `ready` without spending a request unless `--probe-keyword-planner` is
+passed, which sends one one-result `generateKeywordIdeas` call. Every failure
+carries the same `remediation` mapping as above.
+
+`maggie ops google-ads-keyword-ideas` sends read-only `generateKeywordIdeas`
+requests (keyword, URL, or keyword+URL seed; language and geo-target constants;
+bounded pagination) and normalizes each idea to `text`, `avgMonthlySearches`,
+`competition`, `competitionIndex`, and `lowTopOfPageBid`/`highTopOfPageBid`
+converted from micros into the customer currency.
+
+The adapter refuses any request outside `listAccessibleCustomers`,
+`googleAds:search`, and `generateKeywordIdeas`, so it cannot mutate campaigns,
+budgets, or keywords. The REST API version defaults to `v21` and can be set with
+`--api-version` or `MAGGIE_GOOGLE_ADS_API_VERSION`; check Google's sunset
+schedule and use a currently supported version. Keyword Planner volumes are
+estimates for planning and require an approved developer token on a real
+account; test accounts return no metrics.
+
 ## Capability matrix
 
 Every provider/resource row must expose this shape:

package/bundled-skills/maggie-content-localization/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-content-localization
 description: Manage translation, polish, rewrite, market localization, review, stale detection, and publishing for pages, guides, posts, services, products, and categories.
 metadata:
-  version: 1.3.0
+  version: 1.4.0
 ---
 
 # Maggie Content Localization
@@ -70,6 +70,20 @@ Norwegian, Finnish, Greek, Hebrew, Czech, Romanian, Hungarian, Thai, Persian,
 and Swahili. Use BCP 47 regions such as `es-MX`, `pt-BR`, `ar-SA`, or `ja-JP`
 when market-specific copy is required.
 
+## Email and lifecycle email
+
+Localized email is a content surface with its own checks. Resolve the
+recipient locale as user preference > market > account > fallback; never
+hard-code a locale or rely on `Accept-Language` alone in fulfilment paths.
+`maggie localization email-matrix` checks missing locales, untranslated
+values, changed or undeclared variables, HTML/plain-text parity, market CTA
+routes, glossary terms, and approval, and can write fixture-filled previews.
+`maggie localization lifecycle` validates a consent-aware marketing plan
+(consent basis, unsubscribe and preference-centre paths, frequency cap,
+attribution, no send until approved) and `--library` drafts the standard
+template set with nothing sendable. Both are read-only and never send. See
+[email and lifecycle email](references/email-and-lifecycle.md).
+
 ## Invocation lifecycle
 
 At the start, run the memory hook for the current skill and load only relevant
@@ -98,6 +112,8 @@ maggie tool maggie_localization.py review .maggie/localization/<job>.json \
 maggie tool maggie_localization.py publish .maggie/localization/<job>.json --confirm
 maggie tool maggie_localization.py stale --project .
 maggie tool maggie_localization.py glossary --project .
+maggie tool maggie_localization.py email-matrix emails/manifest.json --preview-dir .maggie/localization/email-preview
+maggie tool maggie_localization.py lifecycle emails/lifecycle.json
 ```
 
 Operations are distinct: `translate` preserves meaning, `polish` improves