@topy-ai/maggie 0.7.7 → 0.7.9

package/README.md

@@ -60,6 +60,18 @@ Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
 package ships 18 installable skills and a local-first MaggieDash foundation.
 
+For Google integrations, validate a redacted provider matrix before reporting
+access. The command fails closed on unknown scopes, missing Ads prerequisites,
+duplicate provider resources, and unverified edit/publish claims:
+
+```bash
+maggie ops google-capabilities --project . \
+  --report .maggie/google-capability-input.json
+```
+
+Read the shipped [Google integrations runbook](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/references/google-integrations-runbook.md)
+for the exact scope allowlist and provider-specific preflight rules.
+
 For a genuinely empty project, create the host framework first, then bootstrap
 Maggie in this order:
 
@@ -206,8 +218,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.7 update --project . --force
-npx @topy-ai/maggie@0.7.7 cleanup --project .
+npx @topy-ai/maggie@0.7.9 update --project . --force
+npx @topy-ai/maggie@0.7.9 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -217,7 +229,10 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.7 workflow adds the installable MaggieDash admin distribution and
+The 0.7.9 workflow adds nested section-field contracts, renderer-backed
+examples, stable-ID preservation during migration, and disjoint page
+inventory guidance. It retains the shared Google integrations runbook and
+fail-closed provider capability matrix, alongside the installable MaggieDash admin distribution and
 audited CMS operations (`cms revisions`,
 `trash`, `restore`, `schedule`, `publish-due`, `duplicate`, `redirect`, and
 signed `preview`). It also adds a read-only MaggieDash `--diff`/`--dry-run`
@@ -455,6 +470,7 @@ python3 tools/clis/maggie_design.py rebrand \
 | `maggie-feedback` | Collect redacted feedback drafts and explicitly submit them to the NoBlox feedback endpoint |
 | `maggie-auth-reference` | Generate and validate traditional email/password auth with secure server-side sessions |
 | `maggie-blog` | Run a provider-neutral blog lifecycle with stable identity, topics, feeds, settings, and rollback |
+| `maggie-google-capabilities` | Validate redacted Google provider evidence and separate read/report/edit/publish capability states |
 
 `maggie-design` can initialize native blog and service UI plans from a local,
 read-only structural reference:

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.7 init --agent all
+npx @topy-ai/maggie@0.7.8 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 

package/bin/maggie.js

@@ -120,7 +120,8 @@ Usage:
   maggie site-audit URL --crawl --baseline FILE
   maggie browser-audit URL --browse PATH --output DIR --required SELECTOR [--sticky SELECTOR]
   maggie verification coverage --contract FILE --evidence FILE
-  maggie ops audit|preflight|verify|lockfiles|seed-manifest --project PATH
+  maggie ops audit|preflight|verify|lockfiles|seed-manifest|google-capabilities --project PATH
+  maggie ops google-capabilities --project PATH --report FILE [--output FILE]
   maggie ops preflight --project PATH --write
 
 Examples:

package/bundled-contracts/google-integrations/capability-report-v1.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggie.noblox.app/contracts/google-integrations/capability-report-v1.json",
+  "title": "Maggie Google integrations capability report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "generatedAt", "providerResults", "passed", "mutationsAllowed"],
+  "properties": {
+    "schemaVersion": { "const": "maggie-google-capability-report.v1" },
+    "generatedAt": { "type": "string", "minLength": 1 },
+    "providerResults": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/providerResult" }
+    },
+    "passed": { "type": "boolean" },
+    "mutationsAllowed": { "const": false }
+  },
+  "$defs": {
+    "providerResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "provider", "resource", "authMode", "scopes", "productRole",
+        "evidence", "capabilities", "nextAction"
+      ],
+      "properties": {
+        "provider": { "enum": ["gsc", "ga4", "gtm", "google-ads", "firebase"] },
+        "resource": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "authMode": { "enum": ["desktop-oauth", "service-account-impersonation", "none"] },
+        "scopes": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "productRole": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "evidence": { "$ref": "#/$defs/evidence" },
+        "capabilities": { "$ref": "#/$defs/capabilities" },
+        "nextAction": { "type": "string", "minLength": 1, "maxLength": 500 }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["verified", "endpoint", "statusCode", "readOnly"],
+      "properties": {
+        "verified": { "type": "boolean" },
+        "endpoint": { "type": "string", "minLength": 1, "maxLength": 500 },
+        "statusCode": { "type": "integer", "minimum": 100, "maximum": 599 },
+        "readOnly": { "type": "boolean" },
+        "writeTest": { "$ref": "#/$defs/writeTest" },
+        "adsPrerequisites": { "$ref": "#/$defs/adsPrerequisites" }
+      }
+    },
+    "writeTest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["explicitConfirmation", "statusCode", "readBack"],
+      "properties": {
+        "explicitConfirmation": { "const": true },
+        "statusCode": { "type": "integer", "minimum": 200, "maximum": 299 },
+        "readBack": { "const": true }
+      }
+    },
+    "adsPrerequisites": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["developerTokenPresent", "customerIdPresent"],
+      "properties": {
+        "developerTokenPresent": { "type": "boolean" },
+        "customerIdPresent": { "type": "boolean" },
+        "loginCustomerIdPresent": { "type": "boolean" }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["read", "report", "edit", "publish"],
+      "properties": {
+        "read": { "enum": ["verified", "not_tested", "not_available", "blocked"] },
+        "report": { "enum": ["verified", "not_tested", "not_available", "blocked"] },
+        "edit": { "enum": ["verified", "not_tested", "not_available", "blocked"] },
+        "publish": { "enum": ["verified", "not_tested", "not_available", "blocked"] }
+      }
+    }
+  }
+}

package/bundled-contracts/maggiedash/README.md

@@ -25,6 +25,15 @@ frontend framework.
 - [`translation-cache-policy-v1.json`](translation-cache-policy-v1.json):
   restart-after-out-of-band-write evidence.
 
+The section registry is an adapter input rather than a fixed six-band list.
+Each registry entry must describe its purpose and limits, include a
+renderer-compatible `example`, and describe object-shaped repeated fields
+under `repeats.of`. Host-specific bands are valid when the host supplies the
+matching renderer and a preview at its real supported breakpoints. Template
+inventory adapters must count published pages once using disjoint page
+classes; child records such as service price options and saved arrangements
+must not be reported as pages.
+
 MaggieDash owns these contracts. Provider adapters may add namespaced metadata,
 but they may not change the required identity, status, provenance, or approval
 fields. Unknown fields must be preserved or reported as unsupported during

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

@@ -0,0 +1,133 @@
+# Google integrations runbook
+
+This is the shared authorization and capability contract for Google Search
+Console (GSC), Google Analytics 4 (GA4), Google Tag Manager (GTM), Google Ads,
+and Firebase. Analytics, Ops, SEO/GEO, deployment, and project-context skills
+must link here instead of inventing provider-specific OAuth guidance.
+
+The runbook is deliberately read-first and fail-closed. A successful account
+listing is not proof of reporting access, editing access, or publishing access.
+Never print, persist, or put an access token, refresh token, private key, or
+credential file in a prompt, `.env`, screenshot, feedback payload, or report.
+
+## Choose the authentication mode
+
+| Mode | Use when | Boundary |
+|---|---|---|
+| Desktop OAuth | A person is interactively connecting a property or account | Request only the exact scopes needed for the selected read/report task; keep the resulting credential in the local credential store. |
+| Service-account impersonation | A scheduled or server-side workflow needs repeatable access | The caller must have `roles/iam.serviceAccountTokenCreator` on the target service account; the target service account receives product-level access separately. |
+| None | The user has not authorized a provider | Report `blocked` or `not_tested`; do not guess from project IDs or account listings. |
+
+For ADC-based local checks, use a short-lived token only in the command
+pipeline. When a non-Cloud API scope is needed, validate the scope first and
+use the supported ADC command shape:
+
+```bash
+gcloud auth application-default print-access-token \
+  --impersonate-service-account=SERVICE_ACCOUNT \
+  --scopes=EXACT_SCOPE
+```
+
+Do not use `gcloud auth print-access-token` as a substitute for an ADC flow
+when the requested API scope matters. Do not add `--no-launch-browser` to an
+ADC command unless the installed gcloud version explicitly supports that flag;
+use `--no-browser` for the current ADC login flow when a headless device is
+required.
+
+## Exact scope allowlist
+
+Only the following scopes may appear in a Maggie capability report. A scope
+that is not listed is rejected, including whitespace-split or guessed Tag
+Manager scopes.
+
+| Provider | Read/report | Edit | Publish or special access |
+|---|---|---|---|
+| GSC | `https://www.googleapis.com/auth/webmasters.readonly` | Not applicable to this read/report contract | Full read/write `https://www.googleapis.com/auth/webmasters` is allowed only for an explicitly confirmed mutation workflow. |
+| GA4 | `https://www.googleapis.com/auth/analytics.readonly` | `https://www.googleapis.com/auth/analytics.edit` | Publishing is not an Analytics Admin capability. |
+| GTM | `https://www.googleapis.com/auth/tagmanager.readonly` | `https://www.googleapis.com/auth/tagmanager.edit.containers` | `https://www.googleapis.com/auth/tagmanager.publish`; version management is `https://www.googleapis.com/auth/tagmanager.edit.containerversions`. |
+| Google Ads | `https://www.googleapis.com/auth/adwords` | Same OAuth scope, plus product prerequisites | Same OAuth scope, plus product prerequisites and explicit mutation/read-back evidence. |
+| Firebase | `https://www.googleapis.com/auth/cloud-platform` | Same scope, plus Firebase/Cloud IAM permissions | Publishing is not a Firebase Management capability in this contract. |
+
+The validator accepts the complete provider allowlist, but a capability is
+verified only when its corresponding required scope is present. Scope presence
+alone never proves product access.
+
+## Provider setup and read-only preflight
+
+1. Select one provider and one resource. Enable only that provider API in the
+   Google Cloud project.
+2. Select Desktop OAuth for a human connection or service-account
+   impersonation for automation. Record the mode, exact scopes, resource, and
+   product role; never record credential values.
+3. Verify product-level access, not just Cloud IAM:
+   - **GSC:** the user/service principal can discover the property and run a
+     Search Analytics query.
+   - **GA4:** the principal can discover the account/property and run a Data
+     API report; Admin API discovery and Data API reporting are separate
+     checks.
+   - **GTM:** the principal can list the target account/container. Treat edit
+     and publish as separate, untested capabilities until deliberately tested.
+   - **Google Ads:** verify the customer account and include the developer
+     token and customer ID prerequisites. A manager-account flow also needs a
+     `login-customer-id`; remove hyphens from customer IDs in API headers.
+   - **Firebase:** verify the Cloud project and Firebase resource with the
+     required IAM permissions. Firebase access is not implied by GA4 access.
+4. Use an HTTPS provider endpoint and capture only status code, endpoint, and
+   redacted result metadata. A read/report check must be read-only and return
+   a successful 2xx status.
+5. Generate a capability report and validate it before an agent claims access:
+
+```bash
+maggie ops google-capabilities \
+  --project . \
+  --report .maggie/google-capability-input.json \
+  --output .maggie/google-capability-report.json
+```
+
+The report contract is
+[`capability-report-v1.json`](../bundled-contracts/google-integrations/capability-report-v1.json).
+The CLI writes a normalized result and never copies arbitrary input fields.
+
+## Capability matrix
+
+Every provider/resource row must expose this shape:
+
+| Field | Meaning |
+|---|---|
+| `provider` / `resource` | The Google product and scoped resource being checked |
+| `authMode` | `desktop-oauth`, `service-account-impersonation`, or `none` |
+| `scopes` | Exact allowlisted OAuth scopes, never token values |
+| `productRole` | Role granted in the product, distinct from Cloud IAM |
+| `evidence` | Redacted HTTPS endpoint, HTTP status, verification state, and read-only state |
+| `capabilities.read` | Property/account/resource discovery status |
+| `capabilities.report` | Reporting/data-read status |
+| `capabilities.edit` | Edit status; `verified` requires explicit mutation and read-back evidence |
+| `capabilities.publish` | Publish status; `verified` requires explicit mutation and read-back evidence |
+| `nextAction` | One concrete missing prerequisite or safe follow-up |
+
+Use exactly one of `verified`, `not_tested`, `not_available`, or `blocked` for
+each capability. A report should normally say `not_tested` for GTM edit/publish
+and Ads mutations when only read-only checks were authorized. Never infer a
+write capability from a successful list request.
+
+## Mutation boundary
+
+The shared validator does not execute provider mutations. A provider adapter
+may test an edit or publish operation only after the user explicitly confirms
+the exact resource and operation. It must capture a successful status and
+read-back evidence, then set the capability to `verified`. Otherwise use
+`not_tested` or `blocked`.
+
+Google Ads always remains a separate capability check because OAuth scope,
+product account access, developer token, customer ID, and optional manager
+headers are distinct prerequisites. Firebase similarly requires product/IAM
+permissions; a Cloud project or service account alone is insufficient.
+
+## Authoritative references
+
+- [Search Console API authorization](https://developers.google.com/webmaster-tools/v1/how-tos/authorizing)
+- [Google Analytics Admin API scopes](https://developers.google.com/analytics/devguides/config/admin/v1/rpc/google.analytics.admin.v1beta)
+- [Tag Manager API authorization](https://developers.google.com/tag-platform/tag-manager/api/v2/authorization)
+- [Google Ads authorization and headers](https://developers.google.com/google-ads/api/rest/auth)
+- [Firebase IAM permissions](https://firebase.google.com/docs/projects/iam/permissions)
+- [ADC access-token command](https://cloud.google.com/sdk/gcloud/reference/auth/application-default/print-access-token)

package/bundled-skills/README.md

@@ -13,6 +13,7 @@ Skills are the agent-facing workflows. They compose with the tools in
 | `maggie-template` | Discover, recommend, inspect, and apply a selected Astro homepage template | marketplace catalog, bootstrap state, template `DESIGN.md` |
 | `maggie-design` | Fully clone authorized interior pages, then reconcile them to the homepage header/footer shell | browser MCP, clone planner CLI, completed Maggie homepage |
 | `maggie-ops` | Build, connect, operate, upgrade, and verify the private blog operations dashboard | Ops dashboard contract, authenticated API bridge, host tests |
+| `maggie-google-capabilities` | Validate a redacted Google provider capability matrix without inferring write access | Google integrations runbook, provider evidence |
 | `maggie-deployment` | Deploy and verify a dynamic Maggie blog, Cloudflare-first | Cloudflare Workers, D1, R2, KV, Wrangler |
 | `maggie-project-context` | Sync Project, voice, site and CTA context | project-context CLI/API |
 | `maggie-seo-geo` | Plan, audit, create/rewrite and measure SEO/GEO | visibility, SEO audit, GSC/GA4, content quality |

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

@@ -180,9 +180,26 @@ maggie dash sections keys --registry templates/maggiedash/section-registry.json
 ```
 
 The catalogue declares purpose, usage, placement, repeatability and layout
-limits. Over-limit copy is an editor note; unknown types fail validation.
+limits, renderer-owned examples, and the shape of repeated entries. A repeat
+may contain an object (`title`, `body`, `href`, and so on), not just a count;
+the nested limits are displayed to the planner and checked by `sections
+validate`. Over-limit copy is an editor note; unknown types fail validation.
+The starter registry is provider-neutral and extensible: a host may add its
+own renderer-backed bands, but every added band must have a real-renderer
+preview or an explicitly labelled example fallback at the supported
+breakpoints. Do not describe the vocabulary as a fixed number of bands.
+
 Translation keys use stable section IDs, with an array-index fallback only
-until the ordered migration is complete.
+until the ordered migration is complete. Migration preserves unique IDs that
+already belong to the source section list; it generates a new ID only for a
+missing, duplicate, or target-conflicting ID. Never rebuild IDs from array
+position or overwrite existing translation keys.
+
+Keep data-owned values out of page copy. For example, a pricing band should
+store a service identifier or slug and let the live service/booking adapter
+render current options and prices. Inventory reports must classify each
+published page once into disjoint groups; price options, arrangements, and
+other child records are counts, not pages.
 
 After any script or direct adapter write to translation data, invalidate the
 running process before verification. Record the restart and run the rendering

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

@@ -57,6 +57,12 @@ This command never deploys. Production execution still requires the shared
 decision loop, explicit confirmation, migration/rollback details, and the
 provider-specific deploy command.
 
+When deployment verification depends on Google properties or accounts, use
+the shared [Google integrations runbook](../../references/google-integrations-runbook.md).
+Keep provider auth and capability evidence separate from deployment health;
+never infer Ads, GTM, GSC, GA4, or Firebase write access from a successful
+read-only check.
+
 Generate a reviewable VPS plan and configuration artifacts locally:
 
 ```bash

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

@@ -2,7 +2,7 @@
 name: maggie-ops
 description: Build, connect, operate, upgrade, and verify a private Maggie Ops dashboard for blog content, API Pull, sitemap matching, rewrite approvals, reports, and integrations. Use when the user asks for Ops/admin functionality or lifecycle operations rather than public blog pages.
 metadata:
-  version: 1.0.0
+  version: 1.1.0
 ---
 
 # Maggie Ops
@@ -56,6 +56,22 @@ If the user does not name a mode, inspect the project and propose the smallest
 mode that satisfies the request. Do not rebuild the public blog or change its
 framework just to add Ops.
 
+## Google integrations
+
+Use the shared [Google integrations runbook](../../references/google-integrations-runbook.md)
+for GSC, GA4, GTM, Google Ads, and Firebase authorization. Do not invent
+scopes or treat an account listing as proof of reporting, edit, or publish
+access. After a redacted provider preflight, validate the capability matrix:
+
+```bash
+maggie ops google-capabilities --project . \
+  --report .maggie/google-capability-input.json
+```
+
+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.
+
 ## Required preflight
 
 1. Inspect `.maggie/analysis.json` and `.maggie/bootstrap-state.json`.

package/bundled-skills/maggie-project-context/SKILL.md

@@ -53,6 +53,11 @@ Do not export team, uploads, testimonials, market research, internal workflow
 state, API keys, or OAuth tokens into public source-of-truth files. Missing or
 stale context blocks automatic publishing and falls back to a preview.
 
+For Google provider connections used by context or reporting workflows, follow
+the shared [Google integrations runbook](../../references/google-integrations-runbook.md)
+and keep the normalized capability report separate from generated public
+context. Product roles, OAuth scopes, and Cloud IAM are distinct evidence.
+
 For the combined API Pull lifecycle, use the repository CLI in dry-run first:
 
 ```bash

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -112,6 +112,12 @@ Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and c
 
 For state-changing audits, rewrites, or publishing, follow the shared [Maggie decision loop](../../references/decision-loop.md) and confirm policy and scope before external writes.
 
+For GSC/GA4 verification or any Google provider preflight, use the shared
+[Google integrations runbook](../../references/google-integrations-runbook.md).
+Report the verified property, endpoint, date window, and capability state;
+account discovery alone is not evidence of Search Analytics or GA4 reporting
+access, and read access never implies edit or publish access.
+
 Treat SEO and GEO as one measurable content system: people-first content,
 technical accessibility, extractable structure, evidence, authority, brand
 voice, CTA alignment, and observed search/AI outcomes.

package/bundled-templates/maggiedash/section-registry.json

@@ -1,12 +1,84 @@
 {
   "schemaVersion": "maggiedash-section-registry.v1",
-  "description": "The machine-readable section vocabulary used by page planners and editors.",
+  "description": "The provider-neutral starter vocabulary used by page planners and editors. Hosts may extend it with renderer-backed section types.",
   "sections": [
-    {"type": "hero", "purpose": "Says what the page is about and offers the one important action.", "usage": "First on the page; once.", "position": "opening", "repeatable": false, "fields": [{"name": "title", "usage": "Plain words a visitor would search for.", "limit": 70, "required": true}, {"name": "intro", "usage": "Who it is for and what it does.", "limit": 220}, {"name": "ctaLabel", "usage": "The action as a verb.", "limit": 30}]},
-    {"type": "prose", "purpose": "Explains a topic at length, optionally beside an image.", "usage": "Use in the body for explanation.", "position": "body", "repeatable": true, "fields": [{"name": "heading", "usage": "The argument in a sentence.", "limit": 90}, {"name": "paragraphs", "usage": "Two or three standalone paragraphs.", "limit": 400, "repeats": {"min": 1, "max": 4}}]},
-    {"type": "cards", "purpose": "Presents parallel points side by side.", "usage": "Use for steps or genuinely parallel points.", "position": "body", "repeatable": true, "fields": [{"name": "heading", "usage": "What the cards share.", "limit": 90}, {"name": "items", "usage": "The parallel points.", "limit": 220, "repeats": {"min": 3, "max": 3}}]},
-    {"type": "links", "purpose": "Sends the reader to related pages.", "usage": "Near the end after the page has done its job.", "position": "closing", "repeatable": true, "fields": [{"name": "heading", "usage": "What the links have in common.", "limit": 90}, {"name": "items", "usage": "Real related pages on this site.", "limit": 160, "repeats": {"min": 2, "max": 6}}]},
-    {"type": "faq", "purpose": "Answers questions a visitor would otherwise ask.", "usage": "Once near the end; use real visitor questions.", "position": "closing", "repeatable": false, "fields": [{"name": "heading", "usage": "The question topic.", "limit": 90}, {"name": "items", "usage": "Direct questions and answers.", "limit": 600, "repeats": {"min": 2, "max": 8}}]},
-    {"type": "cta", "purpose": "Makes the closing ask.", "usage": "Last on the page; once.", "position": "closing", "repeatable": false, "fields": [{"name": "heading", "usage": "The invitation in a sentence.", "limit": 90, "required": true}, {"name": "body", "usage": "What happens next.", "limit": 220}, {"name": "label", "usage": "The action as a verb.", "limit": 30, "required": true}]}
+    {
+      "type": "hero",
+      "purpose": "Says what the page is about and offers the one important action.",
+      "usage": "First on the page; once.",
+      "position": "opening",
+      "repeatable": false,
+      "fields": [
+        {"name": "title", "usage": "Plain words a visitor would search for.", "limit": 70, "required": true},
+        {"name": "intro", "usage": "Who it is for and what it does.", "limit": 220},
+        {"name": "image", "usage": "The hero image rendered beside or behind the copy.", "limit": 500},
+        {"name": "imageAlt", "usage": "What the hero image shows for a reader who cannot see it.", "limit": 160},
+        {"name": "ctaLabel", "usage": "The action as a verb.", "limit": 30}
+      ],
+      "example": {"type": "hero", "title": "A clearer way to plan your next step", "intro": "Useful guidance for people who want to move forward with confidence.", "image": "https://images.unsplash.com/photo-1497366754035-f200968a6e72", "imageAlt": "A bright workspace with a table and plants", "ctaLabel": "Get started"}
+    },
+    {
+      "type": "prose",
+      "purpose": "Explains a topic at length, optionally beside an image.",
+      "usage": "Use in the body for explanation.",
+      "position": "body",
+      "repeatable": true,
+      "fields": [
+        {"name": "heading", "usage": "The argument in a sentence.", "limit": 90},
+        {"name": "paragraphs", "usage": "Standalone paragraphs.", "limit": 0, "repeats": {"min": 1, "max": 4, "of": [{"name": "paragraph", "usage": "One paragraph of plain prose.", "limit": 400}]}},
+        {"name": "image", "usage": "An optional supporting image.", "limit": 500},
+        {"name": "imageAlt", "usage": "What the supporting image shows.", "limit": 160}
+      ],
+      "example": {"type": "prose", "heading": "Make the important part easier to understand", "paragraphs": ["Start with the decision your reader is trying to make.", "Then give them the context, evidence and next step in that order."]}
+    },
+    {
+      "type": "cards",
+      "purpose": "Presents parallel points side by side.",
+      "usage": "Use for steps or genuinely parallel points.",
+      "position": "body",
+      "repeatable": true,
+      "fields": [
+        {"name": "heading", "usage": "What the cards share.", "limit": 90},
+        {"name": "items", "usage": "The parallel points.", "limit": 0, "repeats": {"min": 3, "max": 3, "of": [{"name": "title", "usage": "The point in a few words.", "limit": 60, "required": true}, {"name": "body", "usage": "One or two sentences.", "limit": 220}]}}
+      ],
+      "example": {"type": "cards", "heading": "A simple path from question to action", "items": [{"title": "Understand", "body": "See the essential context in one place."}, {"title": "Choose", "body": "Compare the options that fit your situation."}, {"title": "Act", "body": "Take the next step with a clear expectation."}]}
+    },
+    {
+      "type": "links",
+      "purpose": "Sends the reader to related pages.",
+      "usage": "Near the end after the page has done its job.",
+      "position": "closing",
+      "repeatable": true,
+      "fields": [
+        {"name": "heading", "usage": "What the links have in common.", "limit": 90},
+        {"name": "items", "usage": "Real related pages on this site.", "limit": 0, "repeats": {"min": 2, "max": 6, "of": [{"name": "label", "usage": "The destination page name.", "limit": 60, "required": true}, {"name": "href", "usage": "A real path on this site.", "limit": 200, "required": true}, {"name": "body", "usage": "One sentence on what is there.", "limit": 160}]}}
+      ],
+      "example": {"type": "links", "heading": "Keep exploring", "items": [{"label": "How it works", "href": "/how-it-works/", "body": "See the process from start to finish."}, {"label": "Frequently asked questions", "href": "/faq/", "body": "Find concise answers to common questions."}]}
+    },
+    {
+      "type": "faq",
+      "purpose": "Answers questions a visitor would otherwise ask.",
+      "usage": "Once near the end; use real visitor questions.",
+      "position": "closing",
+      "repeatable": false,
+      "fields": [
+        {"name": "heading", "usage": "The question topic.", "limit": 90},
+        {"name": "items", "usage": "Direct questions and answers.", "limit": 0, "repeats": {"min": 2, "max": 8, "of": [{"name": "question", "usage": "A question a real visitor asks.", "limit": 140, "required": true}, {"name": "answer", "usage": "A direct, useful answer.", "limit": 600, "required": true}]}}
+      ],
+      "example": {"type": "faq", "heading": "Questions, answered", "items": [{"question": "What happens next?", "answer": "You will see the relevant options and can choose the next step."}, {"question": "Can I ask for help?", "answer": "Yes. Use the contact route and include the decision you are making."}]}
+    },
+    {
+      "type": "cta",
+      "purpose": "Makes the closing ask.",
+      "usage": "Last on the page; once.",
+      "position": "closing",
+      "repeatable": false,
+      "fields": [
+        {"name": "heading", "usage": "The invitation in a sentence.", "limit": 90, "required": true},
+        {"name": "body", "usage": "What happens next.", "limit": 220},
+        {"name": "label", "usage": "The action as a verb.", "limit": 30, "required": true}
+      ],
+      "example": {"type": "cta", "heading": "Ready to take the next step?", "body": "Start with the option that best matches your goal.", "label": "Get started"}
+    }
   ]
 }

package/bundled-tools/clis/maggie_ops.py

@@ -14,6 +14,7 @@ from dependency_lock import audit as audit_lockfiles
 from seed_evidence import validate_manifest
 from agent_runtime import preflight as agent_preflight
 from restart_gate import validate as validate_restart_gate
+from google_capabilities import validate_report as validate_google_capability_report
 
 
 REQUIRED_ROUTES = (
@@ -165,6 +166,21 @@ def command_restart_gate(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_google_capabilities(args: argparse.Namespace) -> int:
+    report = read_json(Path(args.report).resolve())
+    result = validate_google_capability_report(report)
+    output = Path(args.output).resolve() if args.output else root(args) / ".maggie" / "google-capability-report.json"
+    write_json(output, result)
+    print(json.dumps({
+        "status": "passed" if result["passed"] else "failed",
+        "report": str(output),
+        "providerCount": len(result["providerResults"]),
+        "failedChecks": result["errors"],
+        "mutationsAllowed": False,
+    }, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--project", default=".")
@@ -183,6 +199,10 @@ def main() -> int:
     restart = sub.add_parser("restart-gate", help="validate restart-after-out-of-band-write evidence")
     restart.add_argument("--manifest", required=True)
     restart.set_defaults(func=command_restart_gate)
+    google = sub.add_parser("google-capabilities", help="validate a redacted Google provider capability matrix")
+    google.add_argument("--report", required=True)
+    google.add_argument("--output")
+    google.set_defaults(func=command_google_capabilities)
     record = sub.add_parser("record", help="record an explicitly authorised operation")
     record.add_argument("operation", choices=("sync", "sitemap-match", "rewrite-queue", "rewrite-approve", "publish", "migration"))
     record.add_argument("--dry-run", action="store_true")

package/bundled-tools/integrations/analytics.md

@@ -1,5 +1,10 @@
 # GA4 and Google Search Console
 
+Use the shared [Google integrations runbook](../../references/google-integrations-runbook.md)
+for authorization, exact scopes, product-level roles, and capability
+verification. This guide covers analytics instrumentation; it does not replace
+the provider authentication matrix.
+
 ## GA4
 
 Use the host framework's supported Google tag integration. The minimum

package/bundled-tools/runtime/google_capabilities.py

@@ -0,0 +1,249 @@
+"""Fail-closed validation for redacted Google provider capability reports."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import urlsplit
+
+
+SCHEMA_VERSION = "maggie-google-capability-report.v1"
+CAPABILITY_NAMES = ("read", "report", "edit", "publish")
+CAPABILITY_STATES = {"verified", "not_tested", "not_available", "blocked"}
+PROVIDERS = {"gsc", "ga4", "gtm", "google-ads", "firebase"}
+AUTH_MODES = {"desktop-oauth", "service-account-impersonation", "none"}
+
+SUPPORTED_SCOPES = {
+    "gsc": {
+        "https://www.googleapis.com/auth/webmasters.readonly",
+        "https://www.googleapis.com/auth/webmasters",
+    },
+    "ga4": {
+        "https://www.googleapis.com/auth/analytics.readonly",
+        "https://www.googleapis.com/auth/analytics.edit",
+    },
+    "gtm": {
+        "https://www.googleapis.com/auth/tagmanager.readonly",
+        "https://www.googleapis.com/auth/tagmanager.edit.containers",
+        "https://www.googleapis.com/auth/tagmanager.delete.containers",
+        "https://www.googleapis.com/auth/tagmanager.edit.containerversions",
+        "https://www.googleapis.com/auth/tagmanager.publish",
+        "https://www.googleapis.com/auth/tagmanager.manage.users",
+        "https://www.googleapis.com/auth/tagmanager.manage.accounts",
+    },
+    "google-ads": {"https://www.googleapis.com/auth/adwords"},
+    "firebase": {"https://www.googleapis.com/auth/cloud-platform"},
+}
+
+READ_SCOPES = {
+    "gsc": "https://www.googleapis.com/auth/webmasters.readonly",
+    "ga4": "https://www.googleapis.com/auth/analytics.readonly",
+    "gtm": "https://www.googleapis.com/auth/tagmanager.readonly",
+    "google-ads": "https://www.googleapis.com/auth/adwords",
+    "firebase": "https://www.googleapis.com/auth/cloud-platform",
+}
+
+EDIT_SCOPES = {
+    "gsc": None,
+    "ga4": "https://www.googleapis.com/auth/analytics.edit",
+    "gtm": "https://www.googleapis.com/auth/tagmanager.edit.containers",
+    "google-ads": "https://www.googleapis.com/auth/adwords",
+    "firebase": "https://www.googleapis.com/auth/cloud-platform",
+}
+
+PUBLISH_SCOPES = {
+    "gsc": None,
+    "ga4": None,
+    "gtm": "https://www.googleapis.com/auth/tagmanager.publish",
+    "google-ads": "https://www.googleapis.com/auth/adwords",
+    "firebase": None,
+}
+
+ALLOWED_ENDPOINT_HOSTS = {
+    "searchconsole.googleapis.com",
+    "analyticsadmin.googleapis.com",
+    "analyticsdata.googleapis.com",
+    "tagmanager.googleapis.com",
+    "googleads.googleapis.com",
+    "firebase.googleapis.com",
+}
+
+NOT_APPLICABLE = {
+    "gsc": {"edit", "publish"},
+    "ga4": {"publish"},
+    "firebase": {"publish"},
+}
+
+
+def _string(value: Any, field: str, errors: list[str], *, max_length: int = 500) -> bool:
+    if not isinstance(value, str) or not value.strip() or len(value) > max_length:
+        errors.append(f"{field} must be a non-empty bounded string")
+        return False
+    return True
+
+
+def _endpoint(value: Any, field: str, errors: list[str]) -> bool:
+    if not _string(value, field, errors):
+        return False
+    parts = urlsplit(value)
+    if parts.scheme != "https" or not parts.hostname or parts.username or parts.password or parts.query or parts.fragment:
+        errors.append(f"{field} must be an HTTPS URL without credentials, query, or fragment")
+        return False
+    if parts.hostname.lower() not in ALLOWED_ENDPOINT_HOSTS:
+        errors.append(f"{field} host is not an approved Google API host")
+        return False
+    return True
+
+
+def _write_test(value: Any, field: str, errors: list[str]) -> bool:
+    if not isinstance(value, dict):
+        errors.append(f"{field} is required for a verified write capability")
+        return False
+    allowed = {"explicitConfirmation", "statusCode", "readBack"}
+    unknown = sorted(set(value) - allowed)
+    if unknown:
+        errors.append(f"{field} contains unsupported fields")
+    valid = value.get("explicitConfirmation") is True and value.get("readBack") is True
+    if not valid:
+        errors.append(f"{field} requires explicitConfirmation and readBack")
+    if not isinstance(value.get("statusCode"), int) or not 200 <= value["statusCode"] <= 299:
+        errors.append(f"{field}.statusCode must be a successful HTTP status")
+        valid = False
+    return valid and not unknown
+
+
+def _required_scope(provider: str, capability: str) -> str | None:
+    if capability == "read" or capability == "report":
+        return READ_SCOPES[provider]
+    if capability == "edit":
+        return EDIT_SCOPES[provider]
+    return PUBLISH_SCOPES[provider]
+
+
+def validate_report(report: Any) -> dict[str, Any]:
+    """Return safe validation output; never returns arbitrary input fields."""
+    errors: list[str] = []
+    if not isinstance(report, dict):
+        return {"schemaVersion": "maggie-google-capability-report-result.v1", "passed": False, "errors": ["report must be an object"], "providerResults": []}
+    if report.get("schemaVersion") != SCHEMA_VERSION:
+        errors.append("schemaVersion must be maggie-google-capability-report.v1")
+    if not _string(report.get("generatedAt"), "generatedAt", errors):
+        pass
+    if report.get("mutationsAllowed") is not False:
+        errors.append("mutationsAllowed must be false")
+    rows = report.get("providerResults")
+    if not isinstance(rows, list) or not rows:
+        errors.append("providerResults must be a non-empty array")
+        rows = []
+
+    normalized: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    for index, row in enumerate(rows):
+        prefix = f"providerResults[{index}]"
+        if not isinstance(row, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        required = {"provider", "resource", "authMode", "scopes", "productRole", "evidence", "capabilities", "nextAction"}
+        unknown = sorted(set(row) - required)
+        if unknown:
+            errors.append(f"{prefix} contains unsupported fields")
+        provider = row.get("provider")
+        resource = row.get("resource")
+        if provider not in PROVIDERS:
+            errors.append(f"{prefix}.provider is unsupported")
+            continue
+        if not _string(resource, f"{prefix}.resource", errors, max_length=200):
+            continue
+        key = (provider, resource)
+        if key in seen:
+            errors.append(f"{prefix} duplicates provider/resource")
+        seen.add(key)
+        if row.get("authMode") not in AUTH_MODES:
+            errors.append(f"{prefix}.authMode is unsupported")
+        scopes = row.get("scopes")
+        valid_scope_values = isinstance(scopes, list) and all(isinstance(scope, str) and bool(scope) and not re.search(r"\s", scope) for scope in scopes)
+        if not valid_scope_values or len(scopes) != len(set(scopes)):
+            errors.append(f"{prefix}.scopes must be a unique array of exact scope strings")
+            scopes = []
+        unknown_scopes = sorted(set(scopes) - SUPPORTED_SCOPES[provider])
+        if unknown_scopes:
+            errors.append(f"{prefix}.scopes contains an unsupported scope")
+        if not _string(row.get("productRole"), f"{prefix}.productRole", errors, max_length=200):
+            pass
+        if not _string(row.get("nextAction"), f"{prefix}.nextAction", errors):
+            pass
+        evidence = row.get("evidence")
+        if not isinstance(evidence, dict):
+            errors.append(f"{prefix}.evidence must be an object")
+            evidence = {}
+        else:
+            evidence_allowed = {"verified", "endpoint", "statusCode", "readOnly", "writeTest", "adsPrerequisites"}
+            if set(evidence) - evidence_allowed:
+                errors.append(f"{prefix}.evidence contains unsupported fields")
+        verified_evidence = evidence.get("verified") is True
+        if not _endpoint(evidence.get("endpoint"), f"{prefix}.evidence.endpoint", errors):
+            pass
+        status_code = evidence.get("statusCode")
+        if not isinstance(status_code, int) or not 100 <= status_code <= 599:
+            errors.append(f"{prefix}.evidence.statusCode must be an HTTP status")
+            status_code = 0
+        if not isinstance(evidence.get("readOnly"), bool):
+            errors.append(f"{prefix}.evidence.readOnly must be boolean")
+        capabilities = row.get("capabilities")
+        if not isinstance(capabilities, dict):
+            errors.append(f"{prefix}.capabilities must be an object")
+            capabilities = {}
+        else:
+            if set(capabilities) != set(CAPABILITY_NAMES):
+                errors.append(f"{prefix}.capabilities must contain read, report, edit, and publish only")
+        safe_capabilities: dict[str, str] = {}
+        for capability in CAPABILITY_NAMES:
+            state = capabilities.get(capability)
+            if state not in CAPABILITY_STATES:
+                errors.append(f"{prefix}.capabilities.{capability} is unsupported")
+                state = "blocked"
+            safe_capabilities[capability] = state
+            if capability in NOT_APPLICABLE.get(provider, set()) and state != "not_available":
+                errors.append(f"{prefix}.capabilities.{capability} must be not_available for {provider}")
+            if state == "verified":
+                needed = _required_scope(provider, capability)
+                if needed is None:
+                    errors.append(f"{prefix}.capabilities.{capability} cannot be verified for {provider}")
+                elif needed not in scopes:
+                    errors.append(f"{prefix}.capabilities.{capability} requires its exact provider scope")
+                if not verified_evidence or not 200 <= status_code <= 299:
+                    errors.append(f"{prefix}.capabilities.{capability} requires verified 2xx evidence")
+                if capability in {"read", "report"} and evidence.get("readOnly") is not True:
+                    errors.append(f"{prefix}.capabilities.{capability} requires readOnly evidence")
+                if capability in {"edit", "publish"} and not _write_test(evidence.get("writeTest"), f"{prefix}.evidence.writeTest", errors):
+                    pass
+        prerequisites = evidence.get("adsPrerequisites")
+        if provider == "google-ads" and any(state == "verified" for state in safe_capabilities.values()):
+            if not isinstance(prerequisites, dict) or prerequisites.get("developerTokenPresent") is not True or prerequisites.get("customerIdPresent") is not True:
+                errors.append(f"{prefix}.evidence.adsPrerequisites requires developer token and customer ID presence")
+        elif prerequisites is not None:
+            errors.append(f"{prefix}.evidence.adsPrerequisites is only valid for google-ads")
+        normalized.append({
+            "provider": provider,
+            "resource": resource,
+            "authMode": row.get("authMode"),
+            "scopes": sorted(scopes),
+            "productRole": row.get("productRole"),
+            "evidence": {
+                "verified": verified_evidence,
+                "endpoint": evidence.get("endpoint"),
+                "statusCode": status_code,
+                "readOnly": evidence.get("readOnly"),
+                "writeTested": isinstance(evidence.get("writeTest"), dict),
+            },
+            "capabilities": safe_capabilities,
+            "nextAction": row.get("nextAction"),
+        })
+
+    return {
+        "schemaVersion": "maggie-google-capability-report-result.v1",
+        "passed": not errors,
+        "errors": sorted(set(errors)),
+        "providerResults": normalized,
+        "mutationsAllowed": False,
+    }

package/bundled-tools/runtime/maggie_sections.py

@@ -14,6 +14,35 @@ SCHEMA = "maggiedash-section-registry.v1"
 IDENTITY_SCHEMA = "maggiedash-section-identity.v1"
 
 
+def _validate_field(field: object, at: str, errors: list[str], *, nested: bool = False) -> None:
+    if not isinstance(field, dict) or not field.get("name"):
+        errors.append(f"{at} needs a name")
+        return
+    if not isinstance(field.get("limit"), int) or field["limit"] < 0:
+        errors.append(f"{at}.limit must be a non-negative integer")
+    if not str(field.get("usage") or "").strip():
+        errors.append(f"{at}.usage is required")
+    repeats = field.get("repeats")
+    if repeats is None:
+        return
+    if not isinstance(repeats, dict) or not isinstance(repeats.get("min"), int) or not isinstance(repeats.get("max"), int) or repeats["min"] < 0 or repeats["min"] > repeats["max"]:
+        errors.append(f"{at}.repeats must declare valid min/max")
+        return
+    item_fields = repeats.get("of")
+    if not isinstance(item_fields, list) or not item_fields:
+        errors.append(f"{at}.repeats.of must be a non-empty field list")
+        return
+    nested_names: set[str] = set()
+    for item_index, item_field in enumerate(item_fields):
+        item_at = f"{at}.repeats.of[{item_index}]"
+        _validate_field(item_field, item_at, errors, nested=True)
+        if isinstance(item_field, dict) and item_field.get("name"):
+            name = str(item_field["name"])
+            if name in nested_names:
+                errors.append(f"duplicate repeated field: {name}")
+            nested_names.add(name)
+
+
 def validate_registry(value: object) -> dict[str, Any]:
     errors: list[str] = []
     if not isinstance(value, dict):
@@ -57,13 +86,10 @@ def validate_registry(value: object) -> dict[str, Any]:
             if name in field_names:
                 errors.append(f"duplicate field: {section_type}.{name}")
             field_names.add(name)
-            if not isinstance(field.get("limit"), int) or field["limit"] < 0:
-                errors.append(f"{field_at}.limit must be a non-negative integer")
-            if not str(field.get("usage") or "").strip():
-                errors.append(f"{field_at}.usage is required")
-            repeats = field.get("repeats")
-            if repeats is not None and (not isinstance(repeats, dict) or not isinstance(repeats.get("min"), int) or not isinstance(repeats.get("max"), int) or repeats["min"] < 0 or repeats["min"] > repeats["max"]):
-                errors.append(f"{field_at}.repeats must declare valid min/max")
+            _validate_field(field, field_at, errors)
+        example = section.get("example")
+        if not isinstance(example, dict) or example.get("type") != section_type:
+            errors.append(f"{at}.example must be an object with type {section_type}")
     return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "sectionTypes": sorted(seen)}
 
 
@@ -74,11 +100,39 @@ def catalogue(registry: dict[str, Any]) -> str:
         lines.append(f"{section['type']} — {section['purpose']} | when: {section['usage']} | place: {section['position']} | {'repeatable' if section['repeatable'] else 'once'}")
         for field in section.get("fields", []):
             repeat = field.get("repeats")
-            suffix = f" [{repeat['min']}-{repeat['max']} entries]" if isinstance(repeat, dict) else ""
+            suffix = ""
+            if isinstance(repeat, dict):
+                count = repeat["min"] if repeat["min"] == repeat["max"] else f"{repeat['min']}-{repeat['max']}"
+                nested = ", ".join(f"{item['name']} ≤{item['limit']}" for item in repeat.get("of", []) if isinstance(item, dict))
+                suffix = f" [{count} entries" + (f" of {{{nested}}}" if nested else "") + "]"
             lines.append(f"  - {field['name']} ≤{field['limit']} chars{suffix}: {field['usage']}")
     return "\n".join(lines)
 
 
+def _copy_notes(value: object, fields: list[dict[str, Any]], path: str, notes: list[dict[str, Any]]) -> None:
+    """Check a field value, including object-shaped repeated entries."""
+    for field in fields:
+        name = str(field.get("name"))
+        child = value.get(name) if isinstance(value, dict) else None
+        limit = int(field.get("limit", 0))
+        if isinstance(child, str) and limit and len(child) > limit:
+            notes.append({"at": f"{path}.{name}", "message": f"{len(child)} characters; layout limit is about {limit}"})
+        repeats = field.get("repeats")
+        if not isinstance(repeats, dict) or not isinstance(child, list):
+            continue
+        if not repeats["min"] <= len(child) <= repeats["max"]:
+            notes.append({"at": f"{path}.{name}", "message": f"{len(child)} entries; layout expects {repeats['min']}-{repeats['max']}"})
+        item_fields = [item for item in repeats.get("of", []) if isinstance(item, dict)]
+        for item_index, item in enumerate(child):
+            item_path = f"{path}.{name}[{item_index}]"
+            if isinstance(item, dict):
+                _copy_notes(item, item_fields, item_path, notes)
+            elif len(item_fields) == 1 and isinstance(item, str):
+                item_limit = int(item_fields[0].get("limit", 0))
+                if item_limit and len(item) > item_limit:
+                    notes.append({"at": item_path, "message": f"{len(item)} characters; layout limit is about {item_limit}"})
+
+
 def copy_notes(registry: dict[str, Any], sections: object) -> dict[str, Any]:
     """Return advisory copy/shape notes; over-limit copy is not rejected."""
     errors: list[str] = []
@@ -95,15 +149,7 @@ def copy_notes(registry: dict[str, Any], sections: object) -> dict[str, Any]:
         if not spec:
             errors.append(f"unknown section type: {section_type}")
             continue
-        for field in spec.get("fields", []):
-            name = str(field.get("name"))
-            value = section.get(name)
-            limit = int(field.get("limit", 0))
-            if isinstance(value, str) and limit and len(value) > limit:
-                notes.append({"at": f"sections[{index}].{name}", "message": f"{len(value)} characters; layout limit is about {limit}"})
-            repeats = field.get("repeats")
-            if isinstance(repeats, dict) and isinstance(value, list) and not repeats["min"] <= len(value) <= repeats["max"]:
-                notes.append({"at": f"sections[{index}].{name}", "message": f"{len(value)} entries; layout expects {repeats['min']}-{repeats['max']}"})
+        _copy_notes(section, [field for field in spec.get("fields", []) if isinstance(field, dict)], f"sections[{index}]", notes)
     return {"passed": not errors, "errors": errors, "notes": notes}
 
 
@@ -117,12 +163,16 @@ def new_section_id(existing: Iterable[str] = ()) -> str:
 
 def ensure_section_ids(sections: list[dict[str, Any]], existing: Iterable[str] = ()) -> list[dict[str, Any]]:
     result = copy.deepcopy(sections)
-    existing_ids = set(existing)
-    taken = set(existing_ids)
+    reserved = {str(item) for item in existing if str(item)}
+    taken: set[str] = set()
     for section in result:
         current = str(section.get("id") or "")
-        if not current or current in existing_ids or current in taken:
-            section["id"] = new_section_id(taken)
+        # Existing IDs belong to the source section list and must survive a
+        # migration. Only absent, duplicated, or target-conflicting IDs get a
+        # replacement. The old implementation put current IDs in `taken`
+        # before inspecting them and consequently rewrote every section.
+        if not current or current in taken or current in reserved:
+            section["id"] = new_section_id(taken | reserved)
         taken.add(str(section["id"]))
     return result
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/google-integrations-runbook.md

@@ -0,0 +1,133 @@
+# Google integrations runbook
+
+This is the shared authorization and capability contract for Google Search
+Console (GSC), Google Analytics 4 (GA4), Google Tag Manager (GTM), Google Ads,
+and Firebase. Analytics, Ops, SEO/GEO, deployment, and project-context skills
+must link here instead of inventing provider-specific OAuth guidance.
+
+The runbook is deliberately read-first and fail-closed. A successful account
+listing is not proof of reporting access, editing access, or publishing access.
+Never print, persist, or put an access token, refresh token, private key, or
+credential file in a prompt, `.env`, screenshot, feedback payload, or report.
+
+## Choose the authentication mode
+
+| Mode | Use when | Boundary |
+|---|---|---|
+| Desktop OAuth | A person is interactively connecting a property or account | Request only the exact scopes needed for the selected read/report task; keep the resulting credential in the local credential store. |
+| Service-account impersonation | A scheduled or server-side workflow needs repeatable access | The caller must have `roles/iam.serviceAccountTokenCreator` on the target service account; the target service account receives product-level access separately. |
+| None | The user has not authorized a provider | Report `blocked` or `not_tested`; do not guess from project IDs or account listings. |
+
+For ADC-based local checks, use a short-lived token only in the command
+pipeline. When a non-Cloud API scope is needed, validate the scope first and
+use the supported ADC command shape:
+
+```bash
+gcloud auth application-default print-access-token \
+  --impersonate-service-account=SERVICE_ACCOUNT \
+  --scopes=EXACT_SCOPE
+```
+
+Do not use `gcloud auth print-access-token` as a substitute for an ADC flow
+when the requested API scope matters. Do not add `--no-launch-browser` to an
+ADC command unless the installed gcloud version explicitly supports that flag;
+use `--no-browser` for the current ADC login flow when a headless device is
+required.
+
+## Exact scope allowlist
+
+Only the following scopes may appear in a Maggie capability report. A scope
+that is not listed is rejected, including whitespace-split or guessed Tag
+Manager scopes.
+
+| Provider | Read/report | Edit | Publish or special access |
+|---|---|---|---|
+| GSC | `https://www.googleapis.com/auth/webmasters.readonly` | Not applicable to this read/report contract | Full read/write `https://www.googleapis.com/auth/webmasters` is allowed only for an explicitly confirmed mutation workflow. |
+| GA4 | `https://www.googleapis.com/auth/analytics.readonly` | `https://www.googleapis.com/auth/analytics.edit` | Publishing is not an Analytics Admin capability. |
+| GTM | `https://www.googleapis.com/auth/tagmanager.readonly` | `https://www.googleapis.com/auth/tagmanager.edit.containers` | `https://www.googleapis.com/auth/tagmanager.publish`; version management is `https://www.googleapis.com/auth/tagmanager.edit.containerversions`. |
+| Google Ads | `https://www.googleapis.com/auth/adwords` | Same OAuth scope, plus product prerequisites | Same OAuth scope, plus product prerequisites and explicit mutation/read-back evidence. |
+| Firebase | `https://www.googleapis.com/auth/cloud-platform` | Same scope, plus Firebase/Cloud IAM permissions | Publishing is not a Firebase Management capability in this contract. |
+
+The validator accepts the complete provider allowlist, but a capability is
+verified only when its corresponding required scope is present. Scope presence
+alone never proves product access.
+
+## Provider setup and read-only preflight
+
+1. Select one provider and one resource. Enable only that provider API in the
+   Google Cloud project.
+2. Select Desktop OAuth for a human connection or service-account
+   impersonation for automation. Record the mode, exact scopes, resource, and
+   product role; never record credential values.
+3. Verify product-level access, not just Cloud IAM:
+   - **GSC:** the user/service principal can discover the property and run a
+     Search Analytics query.
+   - **GA4:** the principal can discover the account/property and run a Data
+     API report; Admin API discovery and Data API reporting are separate
+     checks.
+   - **GTM:** the principal can list the target account/container. Treat edit
+     and publish as separate, untested capabilities until deliberately tested.
+   - **Google Ads:** verify the customer account and include the developer
+     token and customer ID prerequisites. A manager-account flow also needs a
+     `login-customer-id`; remove hyphens from customer IDs in API headers.
+   - **Firebase:** verify the Cloud project and Firebase resource with the
+     required IAM permissions. Firebase access is not implied by GA4 access.
+4. Use an HTTPS provider endpoint and capture only status code, endpoint, and
+   redacted result metadata. A read/report check must be read-only and return
+   a successful 2xx status.
+5. Generate a capability report and validate it before an agent claims access:
+
+```bash
+maggie ops google-capabilities \
+  --project . \
+  --report .maggie/google-capability-input.json \
+  --output .maggie/google-capability-report.json
+```
+
+The report contract is
+[`capability-report-v1.json`](../bundled-contracts/google-integrations/capability-report-v1.json).
+The CLI writes a normalized result and never copies arbitrary input fields.
+
+## Capability matrix
+
+Every provider/resource row must expose this shape:
+
+| Field | Meaning |
+|---|---|
+| `provider` / `resource` | The Google product and scoped resource being checked |
+| `authMode` | `desktop-oauth`, `service-account-impersonation`, or `none` |
+| `scopes` | Exact allowlisted OAuth scopes, never token values |
+| `productRole` | Role granted in the product, distinct from Cloud IAM |
+| `evidence` | Redacted HTTPS endpoint, HTTP status, verification state, and read-only state |
+| `capabilities.read` | Property/account/resource discovery status |
+| `capabilities.report` | Reporting/data-read status |
+| `capabilities.edit` | Edit status; `verified` requires explicit mutation and read-back evidence |
+| `capabilities.publish` | Publish status; `verified` requires explicit mutation and read-back evidence |
+| `nextAction` | One concrete missing prerequisite or safe follow-up |
+
+Use exactly one of `verified`, `not_tested`, `not_available`, or `blocked` for
+each capability. A report should normally say `not_tested` for GTM edit/publish
+and Ads mutations when only read-only checks were authorized. Never infer a
+write capability from a successful list request.
+
+## Mutation boundary
+
+The shared validator does not execute provider mutations. A provider adapter
+may test an edit or publish operation only after the user explicitly confirms
+the exact resource and operation. It must capture a successful status and
+read-back evidence, then set the capability to `verified`. Otherwise use
+`not_tested` or `blocked`.
+
+Google Ads always remains a separate capability check because OAuth scope,
+product account access, developer token, customer ID, and optional manager
+headers are distinct prerequisites. Firebase similarly requires product/IAM
+permissions; a Cloud project or service account alone is insufficient.
+
+## Authoritative references
+
+- [Search Console API authorization](https://developers.google.com/webmaster-tools/v1/how-tos/authorizing)
+- [Google Analytics Admin API scopes](https://developers.google.com/analytics/devguides/config/admin/v1/rpc/google.analytics.admin.v1beta)
+- [Tag Manager API authorization](https://developers.google.com/tag-platform/tag-manager/api/v2/authorization)
+- [Google Ads authorization and headers](https://developers.google.com/google-ads/api/rest/auth)
+- [Firebase IAM permissions](https://firebase.google.com/docs/projects/iam/permissions)
+- [ADC access-token command](https://cloud.google.com/sdk/gcloud/reference/auth/application-default/print-access-token)