@topy-ai/maggie 0.7.44 → 0.7.46

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

@@ -34,6 +34,23 @@ The draft is written to `.maggie/feedback/`. It contains the Maggie version,
 skill, run ID, phase, error fingerprint, expected/actual result, reproduction
 steps, resolution, validation, and metadata-only screenshot references.
 
+Attach bounded, privacy-safe evidence and relationships when a maintainer will
+need to connect a report to a test, deployment, issue, or related run. Only
+identifiers are stored; file contents, logs, credentials, and local paths are
+never copied:
+
+```bash
+maggie feedback collect --project . --summary "Adapter unavailable" \
+  --evidence-ref test:browser-capability:passed \
+  --evidence-ref report:browser-capability:v1 \
+  --relationship same-run=clone-001
+```
+
+Evidence references are bounded and normalized into the
+`maggie-feedback-evidence-bundle.v1` contract. The accepted kinds are
+`test`, `report`, `screenshot`, `command`, `deployment`, `issue`, `commit`,
+and `artifact`; relationships connect safe IDs such as feedback or run IDs.
+
 If a draft is marked fixed with `--fixed` (or the supplied run report says
 `fixed`), both `--resolution` and `--validation` are required. Feedback text
 also scrubs common POSIX/home/temp and Windows absolute paths by default while
@@ -78,6 +95,12 @@ This writes `.maggie/feedback/batches/<batch-id>-review.json` under the
 duplicate fingerprints/summaries, while retaining only redacted observations;
 review the aggregate and each draft before submitting.
 
+Batch review also emits a bounded `evidenceGraph` and
+`remediationSuggestions`. The graph links feedback IDs to evidence IDs and
+safe related references, while suggestions flag duplicate fingerprints,
+missing batch indexes, shared evidence, or a batch with no validation
+references. These are review aids, not automatic issue or memory writes.
+
 Example:
 
     {

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

@@ -37,18 +37,18 @@ API Pull integration, analytics, booking provider, or Maggie Ops backend.
 ## Commands
 
 ```bash
-python3 tools/clis/maggie_marketplace.py list
-python3 tools/clis/maggie_marketplace.py add \
+maggie tool maggie_marketplace.py list
+maggie tool maggie_marketplace.py add \
   https://www.aura.build/templates/medical-spa-landing-30 clone \
   https://medical-spa-landing-30.aura.build/ \
   --rename medical-spa-landing-001 --replace-id medical-spa-landing-30
-python3 tools/clis/maggie_marketplace.py import \
+maggie tool maggie_marketplace.py import \
   --id medical-spa-landing-30 \
   --template-url https://www.aura.build/templates/medical-spa-landing-30 \
   --preview-url https://medical-spa-landing-30.aura.build/ \
   --category spa --category medical-spa --tags premium --tags clinical
-python3 tools/clis/maggie_marketplace.py validate marketplace/templates/medical-spa-landing-30
-python3 tools/clis/maggie_marketplace.py apply \
+maggie tool maggie_marketplace.py validate marketplace/templates/medical-spa-landing-30
+maggie tool maggie_marketplace.py apply \
   --id medical-spa-landing-30 --project /path/to/astro-project
 ```
 
@@ -84,8 +84,8 @@ The workflow is persisted as `.maggie/marketplace-jobs/<template-id>.json` and
 uses fail-closed checkpoints. Inspect or resume a job with:
 
 ```bash
-python3 tools/clis/maggie_marketplace.py status <template-id>
-python3 tools/clis/maggie_marketplace.py resume <template-id>
+maggie tool maggie_marketplace.py status <template-id>
+maggie tool maggie_marketplace.py resume <template-id>
 ```
 
 If generated assets are missing, the job stops at `WAITING_FOR_ASSETS`; cloned
@@ -114,16 +114,16 @@ or while an output image is reused across content occurrences.
 sample only when the marketplace intentionally introduces a new contract:
 
 ```bash
-python3 tools/clis/maggie_marketplace.py validate \
+maggie tool maggie_marketplace.py validate \
   marketplace/templates/<template-id>
-python3 tools/clis/maggie_marketplace.py validate \
+maggie tool maggie_marketplace.py validate \
   marketplace/templates/<template-id> --sample marketplace/templates/<sample-id>
 ```
 
 For a local export, pass the quoted HTML path as the preview argument:
 
 ```bash
-python3 tools/clis/maggie_marketplace.py add \
+maggie tool maggie_marketplace.py add \
   https://www.aura.build/templates/medical-spa-landing-30 clone \
   "/path/to/Medical Aesthetics & Wellness Landing Page Template.html" \
   --rename medical-spa-landing-001 --category spa --category medical-spa \
@@ -197,7 +197,7 @@ manifest. A spinner, blank iframe, empty React root, loading skeleton, or page
 without meaningful content is a failed clone and must not be packaged.
 
 ```bash
-python3 tools/clis/maggie_clone.py extract \
+maggie tool maggie_clone.py extract \
   "https://medical-spa-landing-30.aura.build/" \
   --run-id marketplace-medical-spa-landing-001
 ```
@@ -301,7 +301,7 @@ redesign is explicitly requested.
 ### 10. Validate and apply
 
 ```bash
-python3 tools/clis/maggie_marketplace.py validate \
+maggie tool maggie_marketplace.py validate \
   marketplace/templates/medical-spa-landing-001
 python3 scripts/validate_skills.py
 git diff --check

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

@@ -38,13 +38,13 @@ Invoke it as:
 Use the deterministic control-plane CLI for lifecycle gates:
 
 ```bash
-python3 tools/clis/maggie_ops.py --project . audit
-python3 tools/clis/maggie_ops.py --project . preflight --write
-python3 tools/clis/maggie_ops.py --project . status
-python3 tools/clis/maggie_ops.py --project . verify
-python3 tools/clis/maggie_ops.py --project . favicon-check \
+maggie tool maggie_ops.py --project . audit
+maggie tool maggie_ops.py --project . preflight --write
+maggie tool maggie_ops.py --project . status
+maggie tool maggie_ops.py --project . verify
+maggie tool maggie_ops.py --project . favicon-check \
   --origin https://example.com
-python3 tools/clis/maggie_ops.py --project . record sitemap-match \
+maggie tool maggie_ops.py --project . record sitemap-match \
   --dry-run --quota-impact quota --idempotency-key match-2026-08-29-001
 ```
 
@@ -88,6 +88,14 @@ maggie ops google-capabilities --project . \
   --report .maggie/google-capability-input.json
 ```
 
+The input must use `maggie-google-capability-report.v2`: each row records the
+redacted active account, the selected target (`property`, `container`,
+`customer`, `project`, or `site`), and the exact scopes. Both account and target
+must be explicitly verified, and `target.id` must equal `resource`. The command
+prints these safe identifiers and scopes before any separate provider adapter
+is allowed to perform a write. A v1 report is rejected because it cannot prove
+that the browser/session is on the intended Google account and property.
+
 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.
@@ -164,6 +172,20 @@ Every mutation must validate the session, role, resource ownership/project
 scope, input schema, legal state transition, and idempotency/correlation key.
 Record actor, timestamp, previous state, next state, reason, and result.
 
+For a GA4/GTM or other Google provider write, validate a hash-only
+write/readback bundle before treating the operation as complete:
+
+```bash
+maggie ops external-write-gate --project . \
+  --evidence .maggie/external-write-readback-input.json \
+  --output .maggie/external-write-readback.json
+```
+
+The bundle requires one stable idempotency key across bounded retries, explicit
+confirmation, successful readback fingerprints, an empty duplicate list, and
+an empty orphaned-workspace list. It never stores provider payloads; an
+incomplete or mismatched readback blocks the release gate.
+
 ### Operate
 
 Use the dashboard or API to perform an explicitly requested operation. Show an

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

@@ -61,7 +61,7 @@ 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
-python3 tools/clis/maggie.py api lifecycle --project .
+maggie tool maggie.py api lifecycle --project .
 ```
 
 The executing form can pull posts/updates, inspect rewrite queue/history and

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

@@ -125,7 +125,10 @@ maggie analytics release-gate --project . --environment staging \
 
 Use `contracts/maggie-seo/gsc-readiness-v1.schema.json` as the evidence
 boundary. Credentials and mutation scopes remain host-owned; a passing local
-contract is not proof of property ownership or live readback.
+contract is not proof of property ownership or live readback. If a GA4/GTM
+write is part of the workflow, also pass hash-only
+`.maggie/external-write-readback.json` evidence to the analytics release gate;
+duplicate or orphaned provider objects fail closed.
 
 ## Freeze and compare a reviewed site
 
@@ -302,7 +305,7 @@ correct.
 For a deterministic technical smoke check, run:
 
 ```bash
-python3 tools/clis/site_audit.py https://example.com --crawl --json
+maggie tool site_audit.py https://example.com --crawl --json
 ```
 
 This validates observable public output only. Strategy, AI visibility
@@ -350,7 +353,7 @@ enter the rewrite queue.
 The deterministic local orchestration entry point is:
 
 ```bash
-python3 tools/clis/maggie.py api lifecycle --project .
+maggie tool maggie.py api lifecycle --project .
 ```
 
 Use `--execute` only after reviewing the dry-run, and add `--allow-quota` for

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -80,66 +80,66 @@ provider research.
 Run from the project root:
 
 ```bash
-python3 tools/clis/maggie_service_booking.py import \
+maggie tool maggie_service_booking.py import \
   "https://www.fresha.com/a/spa-chevy-chase-chevy-chase-4500-north-park-avenue-sbic60h4?pId=512061" \
   --project .
 
-python3 tools/clis/maggie_service_booking.py sync \
+maggie tool maggie_service_booking.py sync \
   "https://www.fresha.com/a/spa-chevy-chase-chevy-chase-4500-north-park-avenue-sbic60h4?pId=512061" \
   --project .
 
-python3 tools/clis/maggie_service_booking.py sync-report --project .
+maggie tool maggie_service_booking.py sync-report --project .
 
-python3 tools/clis/maggie_service_booking.py generate --project . --copy-data docs/service-page-copy.json
-python3 tools/clis/maggie_service_booking.py validate --project .
+maggie tool maggie_service_booking.py generate --project . --copy-data docs/service-page-copy.json
+maggie tool maggie_service_booking.py validate --project .
 
-python3 tools/clis/maggie_service_booking.py validate-copy \
+maggie tool maggie_service_booking.py validate-copy \
   --project . \
   --service-id fresha:15510886 \
   --copy-data docs/service-page-copy.json
 
-python3 tools/clis/maggie_service_booking.py run \
+maggie tool maggie_service_booking.py run \
   "https://www.fresha.com/a/your-location" --project .
 
-python3 tools/clis/maggie_service_booking.py inspect --project .
-python3 tools/clis/maggie_service_booking.py status --project .
+maggie tool maggie_service_booking.py inspect --project .
+maggie tool maggie_service_booking.py status --project .
 
-python3 tools/clis/maggie_service_booking.py convert-page \
+maggie tool maggie_service_booking.py convert-page \
   src/pages/services/scalp-ritual.astro --project .
 
-python3 tools/clis/maggie_service_booking.py match-pages \
+maggie tool maggie_service_booking.py match-pages \
   --project . --pages-dir src/pages
 
 # Apply only reviewed matches; do not accept the first candidate automatically.
-python3 tools/clis/maggie_service_booking.py match-pages \
+maggie tool maggie_service_booking.py match-pages \
   --project . --select 'fresha:15510886=/src/pages/lymphatic-drainage-massage-chevy-chase-md.astro'
 
 # One service may intentionally have multiple reviewed pages; repeat --select.
-python3 tools/clis/maggie_service_booking.py match-pages \
+maggie tool maggie_service_booking.py match-pages \
   --project . \
   --select 'fresha:15510886=/src/pages/lymphatic-drainage-massage-chevy-chase-md.astro' \
   --select 'fresha:15510886=/src/pages/friendship-heights/lymphatic-drainage-massage.astro'
 
-python3 tools/clis/maggie_service_booking.py polish \
+maggie tool maggie_service_booking.py polish \
   --project . \
   --service-id fresha:15510886 \
   --page src/pages/lymphatic-drainage-massage-chevy-chase-md.astro \
   --copy-data docs/service-page-copy.json
 
-python3 tools/clis/maggie_service_booking.py validate-polish \
+maggie tool maggie_service_booking.py validate-polish \
   --project . --service-id fresha:15510886 \
   --page src/pages/lymphatic-drainage-massage-chevy-chase-md.astro \
   --copy-data docs/service-page-copy.json \
   --rendered http://127.0.0.1:4323/lymphatic-drainage-massage-chevy-chase-md/
 
-python3 tools/clis/maggie_service_booking.py category-audit \
+maggie tool maggie_service_booking.py category-audit \
   --project . --rendered-dir /tmp/category-rendered
 
-python3 tools/clis/maggie_service_booking.py category-context --project .
+maggie tool maggie_service_booking.py category-context --project .
 
 # Declare provider behavior, then validate it against the imported catalogue
 # and a sanitized fixture before publishing service pages.
-python3 tools/clis/maggie_service_booking.py capability-audit \
+maggie tool maggie_service_booking.py capability-audit \
   --project . \
   --catalogue .maggie/booking/services.json \
   --capabilities-file .maggie/booking/provider-capabilities.json \
@@ -147,11 +147,11 @@ python3 tools/clis/maggie_service_booking.py capability-audit \
 
 # Answer whether provider-owned treatments are present using the same parser
 # as import/sync; do not search the whole provider page for a name.
-python3 tools/clis/maggie_service_booking.py catalogue-check \
+maggie tool maggie_service_booking.py catalogue-check \
   "https://www.fresha.com/a/your-location" \
   --provider fresha --treatment "Lymphatic drainage massage"
 
-python3 tools/clis/maggie_service_booking.py retirement-audit \
+maggie tool maggie_service_booking.py retirement-audit \
   --project . \
   --catalogue .maggie/booking/services.json \
   --evidence .maggie/booking/retirement-evidence.json
@@ -258,7 +258,7 @@ After the AI artifact is finalised, backfill only deterministic provenance
 metadata with:
 
 ```bash
-python3 tools/clis/maggie_service_booking.py category-hash \
+maggie tool maggie_service_booking.py category-hash \
   --project . --copy-data docs/category-page-copy.json --apply
 ```
 
@@ -282,7 +282,7 @@ is `passed`.
 Run the imported-fact gate before generating service or category copy:
 
 ```bash
-python3 tools/clis/maggie_service_booking.py fact-audit \
+maggie tool maggie_service_booking.py fact-audit \
   --project . --backfill-source
 ```
 
@@ -466,7 +466,7 @@ never let a catch-all route render an unlisted fallback page.
 
 Validate rendered sitemap output with:
 
-    python3 tools/clis/maggie_service_booking.py sitemap-audit \
+    maggie tool maggie_service_booking.py sitemap-audit \
       --project . --index .maggie/rendered-sitemaps/sitemap.xml \
       --sitemap-dir .maggie/rendered-sitemaps
 
@@ -482,7 +482,7 @@ the route.
 
 Then audit the live route graph:
 
-    python3 tools/clis/maggie_service_booking.py route-audit \
+    maggie tool maggie_service_booking.py route-audit \
       --project . --base-url https://example.co.uk
 
 This fetches every sitemap URL, requires HTTP 200, records internal inbound

package/bundled-skills/maggie-social-share/SKILL.md

@@ -22,9 +22,9 @@ and GEO. It is not a second content source of truth.
 Create the reviewable channel contract before generating copy:
 
 ```bash
-python3 tools/clis/maggie_social_share.py plan content.json \
+maggie tool maggie_social_share.py plan content.json \
   --channels linkedin,facebook --output .maggie/social-share-plan.json
-python3 tools/clis/maggie_social_share.py validate .maggie/social-share-plan.json
+maggie tool maggie_social_share.py validate .maggie/social-share-plan.json
 ```
 
 The CLI does not generate copy or publish. It validates identity, canonical

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

@@ -20,11 +20,11 @@ publish marketplace entries.
 Run from the AI CMO Skills repository, or use the equivalent installed tool:
 
 ```bash
-python3 tools/clis/maggie_marketplace.py list
-python3 tools/clis/maggie_marketplace.py list --category spa --tag luxury
-python3 tools/clis/maggie_marketplace.py suggest "premium London medical spa with editorial typography"
-python3 tools/clis/maggie_marketplace.py inspect medical-spa-landing-001
-python3 tools/clis/maggie_marketplace.py apply \
+maggie tool maggie_marketplace.py list
+maggie tool maggie_marketplace.py list --category spa --tag luxury
+maggie tool maggie_marketplace.py suggest "premium London medical spa with editorial typography"
+maggie tool maggie_marketplace.py inspect medical-spa-landing-001
+maggie tool maggie_marketplace.py apply \
   --id medical-spa-landing-001 --project /path/to/astro-project
 ```
 

package/bundled-tools/clis/maggie_analytics.py

@@ -13,6 +13,7 @@ from urllib.parse import urlsplit
 import sys
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from analytics_traffic import audit_events  # noqa: E402
+from external_write import validate as validate_external_write  # noqa: E402
 
 
 GA4_ID = re.compile(r"^G-[A-Z0-9]+$", re.I)
@@ -122,6 +123,12 @@ def release_gate(args: argparse.Namespace) -> int:
             errors.append("gsc-evidence-schema")
     elif args.require_gsc:
         errors.append("gsc-evidence-required")
+    if args.write_readback:
+        write_readback, write_errors = load_json(Path(args.write_readback).resolve(), "external write readback")
+        errors.extend(write_errors)
+        write_result = validate_external_write(write_readback or {})
+        check("external-write-readback", write_result["passed"], "idempotency, readback, duplicate, and cleanup evidence", checks)
+        errors.extend(write_result["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)
@@ -191,6 +198,7 @@ def main() -> int:
     parser.add_argument("--smoke-report", help="production smoke evidence for release-gate")
     parser.add_argument("--gsc-evidence", help="versioned GSC readiness evidence for release-gate")
     parser.add_argument("--require-gsc", action="store_true", help="require GSC readiness evidence in release-gate")
+    parser.add_argument("--write-readback", help="hash-only external write/readback evidence for release-gate")
     parser.add_argument("--events", help="redacted JSON array of analytics events for traffic-audit")
     args = parser.parse_args()
     if args.command == "gsc-readiness":

package/bundled-tools/clis/maggie_browser_audit.py

@@ -10,6 +10,7 @@ from urllib.parse import urlparse
 RUNTIME = Path(__file__).resolve().parents[1] / "runtime"
 sys.path.insert(0, str(RUNTIME))
 from browser_behavior import validate_samples
+from browser_capability import discover_browser_adapter, require_browser_adapter
 from localization_runner import checkpoint
 
 
@@ -108,10 +109,17 @@ def run_interactions(call, steps: list[dict]) -> list[dict]:
 def audit(args):
     if urlparse(args.url).scheme not in {"http", "https", "file"}:
         raise ValueError("URL must use http, https or file")
-    if not args.required:
+    if not args.required and not args.check_browser:
         raise ValueError("at least one --required selector is necessary")
     output = args.output.resolve()
     output.mkdir(parents=True, exist_ok=True)
+    capability = discover_browser_adapter(args.browse)
+    capability_path = args.capability_report.resolve() if args.capability_report else output / "browser-capability.json"
+    checkpoint(capability_path, capability)
+    if args.check_browser:
+        print(json.dumps(capability, indent=2))
+        return 0 if capability["status"] == "ready" else 1
+    require_browser_adapter(args.browse)
     interactions = load_interactions(args.interactions)
     def call(*command):
         result = subprocess.run([str(args.browse), *command], capture_output=True, text=True, timeout=45)
@@ -120,7 +128,8 @@ def audit(args):
         return result.stdout
     report = {"schemaVersion": "maggie-browser-audit.v1", "url": args.url,
               "passed": False, "viewports": [], "evidence": "browser-captured",
-              "interactionManifest": str(args.interactions.resolve()) if args.interactions else None}
+              "interactionManifest": str(args.interactions.resolve()) if args.interactions else None,
+              "browserCapability": str(capability_path)}
     try:
         for index, viewport in enumerate(args.viewport or ["390x844", "768x1024", "1440x900"]):
             width, height = [int(value) for value in viewport.split("x")]
@@ -158,6 +167,8 @@ def main():
     parser.add_argument("url")
     parser.add_argument("--browse", type=Path, required=True)
     parser.add_argument("--output", type=Path, required=True, help="new directory for evidence")
+    parser.add_argument("--capability-report", type=Path, help="write the redacted browser adapter capability report here")
+    parser.add_argument("--check-browser", action="store_true", help="only check adapter capability; do not navigate or write page evidence")
     parser.add_argument("--viewport", action="append")
     parser.add_argument("--required", action="append", default=[])
     parser.add_argument("--sticky", action="append", default=[])