@topy-ai/maggie 0.7.7 → 0.7.8

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.8 update --project . --force
+npx @topy-ai/maggie@0.7.8 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -217,7 +229,8 @@ 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.8 workflow adds 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 +468,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-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-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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "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)