@topy-ai/maggie 0.6.6 → 0.6.7

package/README.md

@@ -154,11 +154,33 @@ The canary report requires a screenshot and zero console errors, missing
 assets, and visual placeholders for every route. It records safe cache headers
 only and never stores response bodies, cookies, or credentials.
 
+### Localization and analytics release gates
+
+Extract real page strings before creating a localization job, then require a
+clean rendered report before approval:
+
+```bash
+maggie localization extract --project . --source-dir src \
+  --output .maggie/localization/source.json
+maggie localization plan --project . --content content.json \
+  --source .maggie/localization/source.json --source-lang en \
+  --target-lang zh-Hant --locale zh-Hant-TW --market global --operation translate
+maggie localization validate .maggie/localization/<job>.json \
+  --source .maggie/localization/source.json \
+  --render-report .maggie/localization/rendered.json
+```
+
+For analytics, the opt-in end-to-end gate combines the event contract,
+consent/network evidence, provider readback, browser rendering, referral
+redaction, and production smoke report. It fails closed on missing or unsafe
+evidence; see the repository analytics integration guide for the versioned
+artifact schemas.
+
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.6.6 update --project . --force
-npx @topy-ai/maggie@0.6.6 cleanup --project .
+npx @topy-ai/maggie@0.6.7 update --project . --force
+npx @topy-ai/maggie@0.6.7 cleanup --project .
 ```
 
 ## MaggieDash lifecycle

package/README.zh-TW.md

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

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

@@ -2,7 +2,7 @@
 name: maggie-content-localization
 description: Manage translation, polish, rewrite, market localization, review, stale detection, and publishing for pages, guides, posts, services, products, and categories.
 metadata:
-  version: 1.1.0
+  version: 1.2.0
 ---
 
 # Maggie Content Localization
@@ -40,8 +40,16 @@ advisory and never bypasses validation or owner/Admin approval.
 python3 tools/clis/maggie_localization.py plan \
   --project . --content content.json --source-lang en --target-lang zh-Hans \
   --market uk --operation translate --locale zh-Hans-GB
+python3 tools/clis/maggie_localization.py extract --project . --source-dir src \
+  --routes-file docs/routes.tsv --output .maggie/localization/source.json
+python3 tools/clis/maggie_localization.py plan --project . --content content.json \
+  --source .maggie/localization/source.json --source-lang en --target-lang zh-Hans \
+  --market uk --operation translate --locale zh-Hans-GB
 python3 tools/clis/maggie_localization.py preview .maggie/localization/<job>.json
 python3 tools/clis/maggie_localization.py validate .maggie/localization/<job>.json
+python3 tools/clis/maggie_localization.py validate .maggie/localization/<job>.json \
+  --source .maggie/localization/source.json \
+  --render-report .maggie/localization/rendered.json
 python3 tools/clis/maggie_localization.py review .maggie/localization/<job>.json \
   --reviewer owner@example.com --decision approve
 python3 tools/clis/maggie_localization.py publish .maggie/localization/<job>.json --confirm
@@ -60,8 +68,11 @@ health claims, slug, canonical ownership, or content identity during a copy
 operation without structured approval. Incomplete or fallback output must be
 `isIndexable: false`. High-risk content requires Admin approval before publish.
 
-The current validator checks the localization record. It does not yet extract
-strings from a host project or prove browser-rendered language output. That
-larger capability is specified in
+The extractor is read-only and uses a conservative markup adapter for Astro,
+HTML, JSX/TSX, Vue, and Svelte. It records stable string IDs, source hashes,
+line numbers, routes, and attribute/text-node kinds while skipping scripts,
+styles, SVG, and dynamic expressions. Supplying source and render reports to
+`validate` makes the checks fail closed; the prepared `content.json` flow
+remains backward-compatible without those artifacts. See
 [`docs/localization-extraction-render-prd.md`](../../docs/localization-extraction-render-prd.md)
-and remains a separate release-gated feature.
+for the artifact contract and limitations.

package/bundled-tools/clis/maggie_analytics.py

@@ -7,6 +7,7 @@ import argparse
 import json
 import os
 import re
+import subprocess
 from pathlib import Path
 from urllib.parse import urlsplit
 
@@ -14,6 +15,7 @@ from urllib.parse import urlsplit
 GA4_ID = re.compile(r"^G-[A-Z0-9]+$", re.I)
 ALLOWED_EVENTS = {"page_view", "blog_post_view", "booking_click"}
 FORBIDDEN_EVENTS = re.compile(r"(?:purchase|revenue|confirmed[_-]?booking|completed[_-]?treatment|transaction_id)", re.I)
+SENSITIVE_FIELDS = re.compile(r"(?:email|phone|name|address|ip|user[_-]?id|client[_-]?id|query|referrer)", re.I)
 
 
 def parse_env(path: Path) -> dict[str, str]:
@@ -33,13 +35,94 @@ def check(name: str, passed: bool, evidence: str, checks: dict) -> None:
     checks[name] = {"passed": bool(passed), "evidence": evidence}
 
 
+def load_json(path: Path, label: str) -> tuple[dict | None, list[str]]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return None, [f"{label}: {exc}"]
+    if not isinstance(value, dict):
+        return None, [f"{label}: JSON root must be an object"]
+    return value, []
+
+
+def release_gate(args: argparse.Namespace) -> int:
+    project = Path(args.project).resolve()
+    checks: dict[str, dict] = {}
+    errors: list[str] = []
+    contract, contract_errors = load_json(Path(args.contract).resolve(), "contract")
+    errors.extend(contract_errors)
+    if contract:
+        check("contract-schema", contract.get("schemaVersion") == "maggie-analytics-contract.v1", "versioned analytics contract", checks)
+        events = contract.get("events")
+        valid_events = isinstance(events, list) and bool(events) and all(isinstance(event, str) and re.fullmatch(r"[a-z][a-z0-9_]{1,63}", event) and not FORBIDDEN_EVENTS.search(event) for event in events)
+        check("event-contract", valid_events, "event names are lowercase, bounded, and do not claim revenue", checks)
+        destinations = contract.get("destinations")
+        check("destination-contract", isinstance(destinations, list) and bool(destinations) and all(isinstance(item, str) and item in {"ga4", "gtm", "gsc"} for item in destinations), "destinations are from the supported provider set", checks)
+        fields = contract.get("allowedParameters", [])
+        check("parameter-privacy", isinstance(fields, list) and all(isinstance(field, str) and not SENSITIVE_FIELDS.search(field) for field in fields), "allowed event parameters exclude identity and raw acquisition signals", checks)
+        if isinstance(contract.get("referralSources"), list):
+            check("referral-contract", set(contract["referralSources"]).issubset({"search", "partner", "social", "email", "direct", "unknown"}), "referral categories use the redacted taxonomy", checks)
+        else:
+            check("referral-contract", False, "contract must declare referralSources", checks)
+    browser, browser_errors = load_json(Path(args.render_report).resolve(), "render-report")
+    errors.extend(browser_errors)
+    network, network_errors = load_json(Path(args.network_report).resolve(), "network-report")
+    errors.extend(network_errors)
+    provider, provider_errors = load_json(Path(args.provider_report).resolve(), "provider-report")
+    errors.extend(provider_errors)
+    smoke, smoke_errors = load_json(Path(args.smoke_report).resolve(), "smoke-report")
+    errors.extend(smoke_errors)
+    if browser:
+        check("browser-schema", browser.get("schemaVersion") == "maggie-analytics-browser.v1", "versioned browser evidence", checks)
+        check("browser-render", browser.get("passed") is True and isinstance(browser.get("routes"), list) and bool(browser["routes"]), "routes rendered without a browser failure", checks)
+        check("browser-console", isinstance(browser.get("consoleErrors"), list) and not browser["consoleErrors"], "no browser console errors", checks)
+    if network:
+        pre = network.get("preConsentRequests")
+        check("pre-consent-network", isinstance(pre, list) and not pre, "no analytics requests before consent", checks)
+        check("network-redaction", network.get("redacted") is True, "network evidence is explicitly redacted", checks)
+        check("consented-network", isinstance(network.get("consentedRequests"), list), "consented network evidence is present", checks)
+    if provider:
+        check("provider-read-only", provider.get("schemaVersion") == "maggie-analytics-provider.v1" and provider.get("readOnly") is True and provider.get("authorized") is True and provider.get("passed") is True, "provider inspection is authorized, read-only, and passed", checks)
+    if smoke:
+        check("production-smoke", smoke.get("schemaVersion") == "maggie-analytics-smoke.v1" and smoke.get("passed") is True and bool(smoke.get("route")) and bool(smoke.get("release")) and bool(smoke.get("cache")), "public route, release, and cache smoke evidence", checks)
+    if contract and isinstance(contract.get("events"), list) and browser and isinstance(browser.get("consentedEvents"), list):
+        check("event-runtime-coverage", set(contract["events"]).issubset(set(browser["consentedEvents"])), "every contract event is present in consented browser evidence", checks)
+    failed = [name for name, item in checks.items() if not item["passed"]]
+    errors.extend(failed)
+    report = {
+        "schemaVersion": "maggie-analytics-release-gate.v1",
+        "environment": args.environment,
+        "project": str(project),
+        "checks": checks,
+        "passed": not errors,
+        "publish": False,
+        "mutation": "not executed",
+    }
+    output = project / ".maggie" / "analytics-release-gate.json"
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "passed" if report["passed"] else "failed", "environment": args.environment, "report": str(output), "failedChecks": failed, "publish": False}, indent=2))
+    return 0 if report["passed"] else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
+    parser.add_argument("command", nargs="?", choices=("release-gate",))
     parser.add_argument("--project", default=".")
     parser.add_argument("--environment", choices=("development", "staging", "production"), default="staging")
     parser.add_argument("--env-file", help="optional env file; values are never printed")
     parser.add_argument("--html", help="optional rendered HTML snapshot to inspect")
+    parser.add_argument("--contract", help="versioned analytics contract for release-gate")
+    parser.add_argument("--render-report", help="redacted browser/render evidence for release-gate")
+    parser.add_argument("--network-report", help="redacted network evidence for release-gate")
+    parser.add_argument("--provider-report", help="read-only provider evidence for release-gate")
+    parser.add_argument("--smoke-report", help="production smoke evidence for release-gate")
     args = parser.parse_args()
+    if args.command == "release-gate":
+        required = ("contract", "render_report", "network_report", "provider_report", "smoke_report")
+        if any(not getattr(args, name) for name in required):
+            parser.error("release-gate requires --contract, --render-report, --network-report, --provider-report, and --smoke-report")
+        return release_gate(args)
     project = Path(args.project).resolve()
     env = parse_env(Path(args.env_file).resolve()) if args.env_file else parse_env(project / ".env.example")
     env.update({key: value for key, value in os.environ.items() if key in {"PUBLIC_GA4_MEASUREMENT_ID", "PUBLIC_ANALYTICS_ENABLED", "PUBLIC_ANALYTICS_CONSENT_REQUIRED", "GSC_SITE_URL", "GSC_VERIFICATION_TOKEN"}})

package/bundled-tools/clis/maggie_localization.py

@@ -26,6 +26,133 @@ def load(path: Path) -> dict:
     return value
 
 
+MARKUP_EXTENSIONS = {".astro", ".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte"}
+SKIP_TAGS = re.compile(r"<(?:script|style|noscript|svg)\b[^>]*>.*?</(?:script|style|noscript|svg)\s*>", re.I | re.S)
+TAG_PATTERN = re.compile(r"<[^>]*>")
+ATTR_PATTERN = re.compile(r"\b(?:alt|title|aria-label|placeholder)\s*=\s*([\"'])(.*?)\1", re.I | re.S)
+
+
+def source_revision(files: list[Path], root: Path) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(files):
+        digest.update(str(path.relative_to(root)).encode("utf-8"))
+        digest.update(path.read_bytes())
+    return digest.hexdigest()[:16]
+
+
+def extract_file(path: Path, root: Path, route: str) -> list[dict]:
+    raw = path.read_text(encoding="utf-8", errors="replace")
+    cleaned = SKIP_TAGS.sub("", raw)
+    strings: list[dict] = []
+    occupied: list[tuple[int, int]] = []
+
+    def add(value: str, start: int, kind: str) -> None:
+        value = re.sub(r"\s+", " ", value).strip()
+        if len(value) < 2 or "{" in value or "}" in value or re.fullmatch(r"[\W_]+", value or ""):
+            return
+        line = raw.count("\n", 0, start) + 1
+        relative = str(path.relative_to(root))
+        identity = f"{relative}:{line}:{kind}:{value}"
+        strings.append({
+            "id": "src-" + hashlib.sha256(identity.encode("utf-8")).hexdigest()[:16],
+            "file": relative,
+            "line": line,
+            "route": route,
+            "kind": kind,
+            "text": value,
+            "sourceHash": hashlib.sha256(value.encode("utf-8")).hexdigest()[:16],
+            "translatable": True,
+        })
+
+    for match in TAG_PATTERN.finditer(cleaned):
+        tag = match.group(0)
+        for attr in ATTR_PATTERN.finditer(tag):
+            offset = match.start() + attr.start(2)
+            add(attr.group(2), offset, "attribute")
+        occupied.append((match.start(), match.end()))
+    last = 0
+    for start, end in occupied:
+        if start > last:
+            add(cleaned[last:start], last, "text")
+        last = end
+    if last < len(cleaned):
+        add(cleaned[last:], last, "text")
+    return strings
+
+
+def extract_source(args: argparse.Namespace) -> int:
+    project = args.project.resolve()
+    source_dir = (project / args.source_dir).resolve()
+    if not source_dir.is_dir() or project not in source_dir.parents and source_dir != project:
+        raise ValueError("source-dir must be an existing directory inside project")
+    routes: dict[str, str] = {}
+    if args.routes_file:
+        route_path = (project / args.routes_file).resolve()
+        if route_path.exists():
+            for line in route_path.read_text(encoding="utf-8", errors="replace").splitlines():
+                parts = line.split("\t", 1)
+                if len(parts) == 2 and parts[0].strip() and parts[1].strip():
+                    routes[parts[0].strip()] = parts[1].strip()
+    files = [path for path in source_dir.rglob("*") if path.is_file() and path.suffix.lower() in MARKUP_EXTENSIONS]
+    strings: list[dict] = []
+    for path in sorted(files):
+        relative = str(path.relative_to(project))
+        strings.extend(extract_file(path, project, routes.get(relative, "unknown")))
+    revision = source_revision(files, project)
+    output = (project / args.output).resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    artifact = {
+        "schemaVersion": "maggie-localization-source.v1",
+        "sourceRevision": revision,
+        "sourceRoot": str(source_dir.relative_to(project)),
+        "files": [str(path.relative_to(project)) for path in files],
+        "strings": strings,
+        "extraction": {"adapter": "conservative-markup", "readOnly": True, "supportedExtensions": sorted(MARKUP_EXTENSIONS)},
+    }
+    output.write_text(json.dumps(artifact, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": "passed", "output": str(output), "files": len(files), "strings": len(strings), "sourceRevision": revision}, indent=2))
+    return 0
+
+
+def validate_source(path: Path, expected_revision: str | None) -> list[str]:
+    source = load(path)
+    errors: list[str] = []
+    if source.get("schemaVersion") != "maggie-localization-source.v1":
+        errors.append("source artifact schemaVersion is unsupported")
+    strings = source.get("strings")
+    if not isinstance(strings, list) or not strings:
+        errors.append("source artifact has no extracted strings")
+    seen: set[str] = set()
+    for item in strings if isinstance(strings, list) else []:
+        if not isinstance(item, dict) or not item.get("id") or item.get("id") in seen:
+            errors.append("source strings must have unique IDs")
+            continue
+        seen.add(item["id"])
+        if any(marker in str(item.get("text", "")) for marker in ("{", "}")):
+            errors.append(f"source string contains an expression: {item.get('id')}")
+        if not item.get("file") or not item.get("line") or not item.get("sourceHash"):
+            errors.append(f"source string metadata is incomplete: {item.get('id')}")
+    if expected_revision and source.get("sourceRevision") != expected_revision:
+        errors.append("source revision does not match localization job")
+    return errors
+
+
+def validate_render_report(path: Path) -> list[str]:
+    report = load(path)
+    errors: list[str] = []
+    if report.get("schemaVersion") != "maggie-localization-render.v1":
+        errors.append("render report schemaVersion is unsupported")
+    if report.get("passed") is not True:
+        errors.append("render report is not passed")
+    for field in ("routes", "consoleErrors", "failedAssets", "untranslatedRequired"):
+        if field not in report:
+            errors.append(f"render report is missing {field}")
+    for field in ("consoleErrors", "failedAssets", "untranslatedRequired"):
+        if isinstance(report.get(field), list) and report[field]:
+            errors.append(f"render report has {field}")
+    return errors
+
+
 def safe_job_content_token(content_id: str) -> str:
     """Make a content identity safe for a single filename component."""
     token = re.sub(r"[^A-Za-z0-9._-]+", "-", str(content_id)).strip(".-_") or "content"
@@ -36,6 +163,7 @@ def safe_job_content_token(content_id: str) -> str:
 
 def plan_job(args: argparse.Namespace) -> int:
     content = load(args.content)
+    source_artifact = load(args.source) if getattr(args, "source", None) else None
     if args.source_lang not in LANGUAGES or args.target_lang not in LANGUAGES:
         raise ValueError("source-lang and target-lang must be in the supported language registry")
     if args.market not in MARKETS:
@@ -59,11 +187,18 @@ def plan_job(args: argparse.Namespace) -> int:
         "targetLocale": args.locale,
         "operation": args.operation,
         "translationGroupId": identity.get("translationGroupId", f"tg-{content_id}"),
-        "sourceRevision": args.source_revision or content.get("sourceRevision", "unknown"),
+        "sourceRevision": args.source_revision or (source_artifact or {}).get("sourceRevision") or content.get("sourceRevision", "unknown"),
         "status": "draft",
         "translation": {"translationStatus": "draft", "isIndexable": False},
         "createdAt": now(),
     }
+    if source_artifact:
+        if source_artifact.get("schemaVersion") != "maggie-localization-source.v1":
+            raise ValueError("source artifact schemaVersion is unsupported")
+        source_strings = source_artifact.get("strings", [])
+        if not isinstance(source_strings, list) or not source_strings:
+            raise ValueError("source artifact has no extracted strings")
+        job["translation"]["sourceStringIds"] = [item.get("id") for item in source_strings if isinstance(item, dict) and item.get("id")]
     output = Path(args.project) / ".maggie" / "localization" / f"{job['jobId']}.json"
     output.parent.mkdir(parents=True, exist_ok=True)
     output.write_text(json.dumps(job, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
@@ -71,7 +206,7 @@ def plan_job(args: argparse.Namespace) -> int:
     return 0
 
 
-def validate_job(path: Path) -> dict:
+def validate_job(path: Path, source_path: Path | None = None, render_path: Path | None = None) -> dict:
     job = load(path)
     errors = []
     if job.get("operation") not in OPERATIONS:
@@ -93,6 +228,15 @@ def validate_job(path: Path) -> dict:
         })
     }, expected_lang=job.get("targetLanguage")))
     errors.extend(f"protected field changed without approval: {field}" for field in protected_field_changes(job.get("content", {}), translation))
+    if source_path:
+        errors.extend(validate_source(source_path, job.get("sourceRevision")))
+        source = load(source_path)
+        source_ids = {item.get("id") for item in source.get("strings", []) if isinstance(item, dict)}
+        linked_ids = translation.get("sourceStringIds")
+        if not isinstance(linked_ids, list) or set(linked_ids) != source_ids:
+            errors.append("translation sourceStringIds must link every extracted source string")
+    if render_path:
+        errors.extend(validate_render_report(render_path))
     return {"passed": not errors, "errors": errors, "jobId": job.get("jobId"), "status": job.get("status")}
 
 
@@ -172,8 +316,17 @@ def main() -> int:
     plan_parser.add_argument("--market", required=True)
     plan_parser.add_argument("--operation", required=True)
     plan_parser.add_argument("--source-revision")
-    for name in ("preview", "validate"):
-        sub.add_parser(name).add_argument("job", type=Path)
+    plan_parser.add_argument("--source", type=Path, help="optional extracted source artifact")
+    sub.add_parser("preview").add_argument("job", type=Path)
+    validate_parser = sub.add_parser("validate")
+    validate_parser.add_argument("job", type=Path)
+    validate_parser.add_argument("--source", type=Path)
+    validate_parser.add_argument("--render-report", type=Path)
+    extract_parser = sub.add_parser("extract")
+    extract_parser.add_argument("--project", type=Path, default=Path("."))
+    extract_parser.add_argument("--source-dir", default="src")
+    extract_parser.add_argument("--routes-file")
+    extract_parser.add_argument("--output", default=".maggie/localization/source.json")
     review_parser = sub.add_parser("review")
     review_parser.add_argument("job", type=Path); review_parser.add_argument("--reviewer", required=True); review_parser.add_argument("--decision", required=True)
     publish_parser = sub.add_parser("publish")
@@ -185,7 +338,8 @@ def main() -> int:
         if args.command == "plan": return plan_job(args)
         if args.command == "preview": return preview(args.job)
         if args.command == "validate":
-            result = validate_job(args.job); print(json.dumps(result, indent=2)); return 0 if result["passed"] else 1
+            result = validate_job(args.job, args.source, args.render_report); print(json.dumps(result, indent=2)); return 0 if result["passed"] else 1
+        if args.command == "extract": return extract_source(args)
         if args.command == "review": return review(args.job, args.reviewer, args.decision)
         if args.command == "publish": return publish(args.job, args.confirm)
         if args.command == "stale": return stale_jobs(args.project)

package/bundled-tools/clis/maggie_release.py

@@ -212,6 +212,12 @@ def main() -> int:
     parser.add_argument("--output", help="release evidence JSON path")
     parser.add_argument("--skip-compatibility", action="store_true", help="skip the optional schema rehearsal; not recommended for release")
     parser.add_argument("--base-url", help="optional live/staging URL for homepage, admin redirect and 404 smoke")
+    parser.add_argument("--analytics-release-gate", action="store_true", help="require the end-to-end analytics evidence gate")
+    parser.add_argument("--analytics-contract")
+    parser.add_argument("--analytics-render-report")
+    parser.add_argument("--analytics-network-report")
+    parser.add_argument("--analytics-provider-report")
+    parser.add_argument("--analytics-smoke-report")
     args = parser.parse_args()
     project = Path(args.project).resolve()
     if not project.is_dir():
@@ -221,6 +227,21 @@ def main() -> int:
     gates.append(build_gate(project))
     for name, command in build_gates(project, args.environment, args.target, not args.skip_compatibility):
         gates.append(run_gate(name, command, project))
+    if args.analytics_release_gate:
+        evidence = {
+            "--contract": args.analytics_contract,
+            "--render-report": args.analytics_render_report,
+            "--network-report": args.analytics_network_report,
+            "--provider-report": args.analytics_provider_report,
+            "--smoke-report": args.analytics_smoke_report,
+        }
+        missing = [name for name, value in evidence.items() if not value]
+        if missing:
+            parser.error("--analytics-release-gate requires " + ", ".join(missing))
+        analytics_command = [sys.executable, str(ROOT / "maggie_analytics.py"), "release-gate", "--project", str(project), "--environment", args.environment]
+        for name, value in evidence.items():
+            analytics_command.extend([name, value])
+        gates.append(run_gate("analytics-release-gate", analytics_command, project))
     gates.append(editorial_gate(project))
     gates.append(evidence_gate(project, args.environment))
     if args.base_url:

package/bundled-tools/integrations/analytics.md

@@ -46,3 +46,29 @@ Use `--environment production` during release preflight. It fails closed until
 GA4 is explicitly enabled with a valid measurement ID and `GSC_SITE_URL` is
 configured. The CLI never prints secret values and does not claim confirmed
 bookings or revenue from outbound booking clicks.
+
+## End-to-end release gate
+
+For a release that has browser and provider evidence, use the opt-in gate:
+
+```bash
+maggie analytics release-gate --project . --environment staging \
+  --contract .maggie/analytics-contract.json \
+  --render-report .maggie/analytics-browser.json \
+  --network-report .maggie/analytics-network.json \
+  --provider-report .maggie/analytics-provider.json \
+  --smoke-report .maggie/analytics-smoke.json
+```
+
+The contract must use `maggie-analytics-contract.v1` and declare event names,
+supported destinations, privacy-safe parameters, and the redacted referral
+taxonomy. Evidence uses versioned schemas: browser
+`maggie-analytics-browser.v1`, network `maggie-analytics-network.v1`, provider
+`maggie-analytics-provider.v1`, and smoke `maggie-analytics-smoke.v1`.
+Pre-consent requests must be empty; provider evidence must be read-only and
+authorized; rendered routes, cache/release smoke, and all contract events must
+pass. Reports contain metadata only and never raw URLs, query strings, request
+bodies, credentials, or identity fields.
+
+To include it in the aggregate release preflight, pass the same five files to
+`maggie release` with `--analytics-release-gate`.

package/package.json

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