@topy-ai/maggie 0.7.38 → 0.7.41

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

@@ -11,22 +11,30 @@ for importing a provider's service catalogue. The existing
 right choice for provider-backed services, prices, durations, booking links,
 and factual provider validation.
 
+## Project memory
+
+Before changing a host project, follow the shared
+[`memory-hook.md`](../../references/memory-hook.md) instructions for reading
+relevant project preferences and known pitfalls. After a verified fix or a
+durable host decision, record only the generalizable learning; never promote a
+temporary project detail, secret, or unverified guess into active memory.
+
 ## Contract and safety boundary
 
-Read [`../../docs/maggiedash-booking/README.md`](../../docs/maggiedash-booking/README.md),
-[`TASKS.md`](../../docs/maggiedash-booking/TASKS.md), and the task's linked
+Read [`../../bundled-references/maggiedash-booking/README.md`](../../bundled-references/maggiedash-booking/README.md),
+[`TASKS.md`](../../bundled-references/maggiedash-booking/TASKS.md), and the task's linked
 reference before changing code. MaggieDash owns the manager UI and versioned
 contracts. The host owns routes, traditional email/password sessions,
 PostgreSQL connection/transaction lifetime, tenant authorization, provider
 credentials, payment webhooks, notifications, and deployment. MaggieDash also
-ships a tenant-scoped PostgreSQL manager repository for catalogue, availability,
+ships a tenant-scoped PostgreSQL manager repository for catalogue, treatment packages, availability,
 booking, customer, configuration, schedule, health, audit, hold, and lifecycle
 persistence; it does not replace host connection ownership or payment/public-
 checkout adapters.
 
 For implementation work, use the leaf board and runbook:
-[`EXECUTION-BOARD.json`](../../docs/maggiedash-booking/EXECUTION-BOARD.json)
-and [`TASK-RUNBOOK.md`](../../docs/maggiedash-booking/TASK-RUNBOOK.md). Do not
+[`EXECUTION-BOARD.json`](../../bundled-references/maggiedash-booking/EXECUTION-BOARD.json)
+and [`TASK-RUNBOOK.md`](../../bundled-references/maggiedash-booking/TASK-RUNBOOK.md). Do not
 mark a task passed until its implementation gate, docs update, and evidence
 record are complete.
 
@@ -69,7 +77,7 @@ It applies the host-only evidence rule; fixture, test, and local environments
 cannot satisfy a required operational release artifact.
 
 For local CLI regression, the sanitized no-customer fixture is
-[`fixtures/maggiedash/booking-runtime.v1.json`](../../fixtures/maggiedash/booking-runtime.v1.json).
+[`fixtures/maggiedash/booking-runtime.v1.json`](../../bundled-contracts/maggiedash/booking-runtime.v1.json).
 
 Install the first-party workspace and the host integration through the stable
 Booking installer:
@@ -93,9 +101,23 @@ Astro host it also adds the compatible `@astrojs/node` SSR adapter and the
 portable server config; an existing `astro.config.*` and deployment adapter
 remain host-owned.
 
+For a new host with an approved database migration, `--ready` combines the two
+explicit setup mutations into one command:
+
+```bash
+maggie booking install --project . --confirm --ready
+```
+
+It installs only missing host packages, generates `BOOKING_TOKEN_SECRET` when
+needed, and applies the installed idempotent Booking schema. It still does not
+create the owner, configure Stripe, send email, enable a scheduler, or deploy.
+Use `--schedule systemd` or `--schedule cron` with `--ready` only to generate a
+reviewable scheduler artifact; enabling it remains an operator action after
+backup, migration, and release evidence checks.
+
 The default installer source is the public MaggieDash `0.2.8` distribution. It
-contains the released Astro `hostBootstrap` manifest and 40-route Booking
-source. A fresh public-source install, `maggie booking inspect`, and
+contains the released Astro `hostBootstrap` manifest and 47-route Booking
+source, including the tenant-scoped treatment package catalogue. A fresh public-source install, `maggie booking inspect`, and
 `astro build` are the release evidence; a local-source result alone is not.
 
 For a new host with a reviewed `DATABASE_URL`, the explicit one-command
@@ -114,6 +136,21 @@ characters fails closed. External secret stores must provision the same key
 separately. Bootstrap still does not create the owner, configure Stripe, send
 email, or deploy.
 
+Generate the reviewed worker scheduler artifact as part of the same install,
+or after an existing install:
+
+```bash
+maggie booking install --project . --confirm --bootstrap --schedule systemd
+# or, for a host without systemd:
+maggie booking worker-schedule --project . --scheduler cron --confirm
+```
+
+This writes `deploy/maggie-booking-worker.service` plus `.timer`, or a
+reviewable `deploy/maggie-booking-worker.cron`. It does not edit the crontab,
+enable systemd, start a process, or expose secrets. Review the generated
+artifact, set an unprivileged service user, then enable it only after the
+schema, backup/restore, and release evidence gates pass.
+
 Before changing host configuration, run the safe first-run checklist:
 
 ```bash
@@ -149,16 +186,34 @@ Validate the tenant-scoped Resend template boundary independently:
 maggie booking email-templates-contract
 ```
 
-This freezes the seven supported Booking events, approved `{{variable}}`
+This freezes the ten supported Booking events, approved `{{variable}}`
 placeholders, owner/admin/manager access, audit and idempotency requirements,
 and the server-only provider/recipient privacy boundary. It does not connect to
 Resend, send a message, or expose customer data.
 
+The selected transactional delivery boundary is Resend for email and Twilio
+for SMS. Validate the host policy before wiring provider adapters:
+
+```bash
+maggie booking-delivery \
+  --policy .maggie/booking-delivery-policy.json
+```
+
+The policy requires provider acknowledgement before a booking can display a
+confirmed state, uses a bounded exponential-jitter retry with an idempotency
+key per booking event and channel, and moves exhausted work to a dead-letter
+queue. Replay is an explicit manager action and must be audited. `RESEND_API_KEY`
+and `TWILIO_AUTH_TOKEN` remain server-only host secrets; this gate never sends
+email or SMS.
+
 After the first owner signs in, the Booking Overview includes the same
 secret-safe readiness path: Stripe connection status, test/live mode, and a
-copyable `/api/maggie/booking/webhooks/stripe` URL. It gives the operator the
-next secret-store action without accepting or storing Stripe credentials in the
-browser or Booking database.
+copyable `/api/maggie/booking/webhooks/stripe` URL. The preferred path is still
+the deployment secret store. For a single-business host, an owner or manager
+may submit both Stripe values over HTTPS from this screen; the server verifies
+them first, stores only authenticated AES-256-GCM ciphertext derived from
+`BOOKING_TOKEN_SECRET`, and never returns the raw values. Deployment
+`STRIPE_SECRET_KEY` takes precedence over dashboard-managed credentials.
 
 For an Astro host, framework detection installs missing email/password login,
 first-owner registration, manager/public Booking routes, PostgreSQL/Stripe
@@ -171,9 +226,11 @@ the UI. Use `--host astro` to make detection explicit;
 use `--host none` when only the source distribution is wanted. The
 distribution keeps the content admin at `./_maggie/admin` and Booking source at
 `./_maggie/booking`. Existing files, including an existing `src/middleware.ts`,
-are preserved unless `--force` is explicitly supplied. A conventional Astro
-middleware receives the rewrite block automatically; unsupported middleware is
-preserved and reported by `maggie booking inspect` until integrated manually.
+are preserved unless `--force` is explicitly supplied. Conventional Astro
+middleware using either `defineMiddleware((context, next) => {})` or a
+destructured context such as `defineMiddleware(({ url, request }, next) => {})`
+receives the rewrite block automatically; unsupported middleware is preserved
+and reported by `maggie booking inspect` until integrated manually.
 Installation does not apply SQL, create an owner, or enable a payment provider.
 The standard Booking migration must create
 `maggiedash_booking_user_roles`; do not move that table into a project-only
@@ -233,18 +290,48 @@ allocation by the same time delta, checks each staff/resource interval, and
 preserves the original total duration. Single-treatment requests and legacy
 rows remain compatible. Public DTOs expose only safe segment fields.
 
+When a tenant has multiple online-bookable locations, the public catalogue must
+return a safe `locations` list and the customer page must let the customer pick
+one. Include the selected `locationId` in availability, waitlist, hold,
+checkout, and reschedule requests. Availability must validate that the
+location belongs to the tenant, is active and online-bookable, use its
+timezone, and filter conflicts by that location. Keep the legacy first
+`locationId` field during migration so older hosts remain compatible; never
+fall back to `location-1` or another fixture ID.
+
+After a confirmed package purchase, the public page may carry the opaque
+`packageEntitlementId` into the hold and checkout requests. The server resolves
+the customer from the submitted email, validates tenant ownership, active
+status, expiry, currency, and every selected treatment balance, then locks the
+entitlement and item rows while creating the booking and redemption ledger.
+Public package redemption is all-or-nothing for a multi-treatment selection;
+it confirms a fully covered booking at zero price and does not trust the
+browser to decide the balance.
+
 Every `staff` account must also be linked to a Booking staff profile. The host
 passes that `staff_id` into the server context, and the PostgreSQL repository
 filters bookings, calendar, availability, customer summaries, staff/resources,
 schedule, and lifecycle mutations by that assignment. An unlinked staff
 session fails closed. This is a data-security rule, not a UI convention.
+The administrator access registry must stay identical to the route-handler
+capabilities: calendar, bookings, customers, waitlist, catalogue, packages,
+staff, resources, schedule, locations, payments, refunds, notifications,
+settings, reports, and audit. If `permissions_json` is absent on a legacy role,
+apply the safe role defaults server-side; never treat a missing object as full
+read access. Explicitly granted staff capabilities must be honored by the
+route handler, while staff mutations remain limited to approved lifecycle
+transitions. Keep the access contract, Astro host, reference host, ORA mirror,
+and CLI validator synchronized whenever a route capability changes.
 The bootstrap now uses the host's server-side Resend configuration to send
 single-use invitation and password-reset links; raw tokens are never stored.
 The Resend worker separately delivers booking notifications. The default
 worker cycle includes `match-waitlist` and `enqueue-reminders`. The waitlist
 matcher orders eligible entries by priority/FIFO, requires explicit service and
 location scope, persists the offered slot, and queues one
-`booking.waitlist.available` notification. It never auto-creates or reserves a
+`booking.waitlist.available` notification. Package purchase fulfillment and
+provider-confirmed package refunds also queue the allowlisted
+`package.purchase.confirmed`/`package.purchase.refunded` Resend events linked to
+the package purchase, without appointment manage links. It never auto-creates or reserves a
 booking. The reminder job queues one `booking.reminder`
 email for each confirmed booking in the next 24 hours; the existing Resend
 dispatcher resolves the customer address at delivery time. Reminder queueing
@@ -280,7 +367,9 @@ installed host is:
 node scripts/maggie-booking-schema.mjs --dry-run
 node scripts/maggie-booking-schema.mjs --apply --confirm
 # open /_maggie/register and create the first owner
-# add Stripe and Resend secrets through the deployment secret store
+# preferred: add Stripe and Resend secrets through the deployment secret store
+# alternative: owner/manager can enter the Stripe key pair in Booking Overview;
+# the host verifies it and stores only encrypted ciphertext
 node scripts/maggie-booking-worker.mjs --write --confirm
 ```
 
@@ -379,7 +468,7 @@ Follow the task board rather than building a disconnected calendar first:
    signed duplicate/out-of-order webhooks before enabling capture.
 7. Run the UI source gate, contract gate, host runtime conformance, browser
    journeys, and release gate. Record each command in
-   [`PROGRESS.md`](../../docs/maggiedash-booking/PROGRESS.md).
+   [`PROGRESS.md`](../../bundled-references/maggiedash-booking/PROGRESS.md).
 
 8. Verify the scheduled worker queues and delivers a reminder once for a
    confirmed booking inside the 24-hour window. Check the notification
@@ -442,6 +531,11 @@ short-lived while customer-manage tokens are 30-day links. A redirect is never
 payment proof.
 Run `npm run booking:customer-flow:test` in MaggieDash before wiring the
 adapter, and retain real host/runtime/browser evidence as a separate gate.
+If the host already has a legacy `/book` request form, keep it as a fallback
+until the Booking schema is ready; expose the new customer route only after a
+schema-aware readiness check, and preserve any existing treatment hint when
+linking into the new flow. Do not replace a working host booking form with a
+route that can only show an unconfigured Booking error.
 The manager Booking UI also exposes the tenant-scoped waitlist queue. Managers
 can filter entries, notify/cancel/reprioritize them, or select a concrete slot
 and staff/resource allocation to create a real booking transaction linked by

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

@@ -41,6 +41,19 @@ Each run persists `manifest.json`, `state.json`, and phase outputs under
 `failed` and must be resumed after the defect is fixed; an incomplete run must
 not be presented as a successful clone.
 
+Replay approved interaction states with the same manifest used by
+`maggie browser-audit`:
+
+```bash
+maggie clone interactions --project <project-root> --run-id <stable-run-id> \
+  --browse <browse-cli> --interactions .maggie/browser-interactions.json
+```
+
+The adapter replays at desktop, tablet, and mobile viewports and writes a
+redacted `maggie-clone-interaction-state.v1` evidence file. It never stores
+typed values, credentials, or raw provider payloads. A clone is not
+interaction-complete until every approved step passes at all three viewports.
+
 An exported local HTML file is also a valid source, for example:
 
 ```text

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

@@ -414,3 +414,9 @@ both units being enabled in systemd. Data-dependent releases additionally
 require `rollback.backupId` and `rollback.restoreCommand` in
 `.maggie/deployment/data-release.json`, because switching code alone does not
 restore incompatible data.
+
+`maggie update --help` is read-only. Help flags must be handled before project
+discovery, install-manifest writes, or file synchronization. For fixture-backed
+browser QA, the host owns the isolated dev server and data source; document a
+second port/process and fixture mode in the host runbook instead of making the
+shared updater or deployment CLI start an unmanaged daemon.

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

@@ -95,9 +95,20 @@ fallback. Mobile evidence must not assume that `preload="none"` will emit
 `canplaythrough` without user interaction. Record poster visibility, playback
 state, console errors, network errors, and a screenshot per viewport.
 
-This contract is provider-neutral. It does not claim that Maggie can generate
-video assets; generated-video planning, continuation, safety review, retries,
-and cost approval remain separate product/provider work.
+The playback contract is provider-neutral, while the selected generation
+policy is Google Gemini: `gemini-omni-1.1-flash` for the default hero-video
+route and `veo-3.1-generate-preview` for specialized continuation/frame
+control. Validate the policy and job evidence separately:
+
+```bash
+maggie media video-policy \
+  --policy contracts/maggie-media/video-generation-policy-v1.json
+maggie media video-job --job .maggie/video-job.json
+```
+
+Generation remains host-owned. The host must supply cost budget, rights and
+moderation evidence, idempotency, object storage, and a redacted provenance
+record before a generated asset is used in a release.
 
 ## Automatic memory hook
 
@@ -182,6 +193,20 @@ unconfirmed writes. Generated copy and media must be marked authored rather
 than source-observed. Implementation must still capture responsive screenshots
 and run accessibility/build validation before publication.
 
+Author jobs are resumable design jobs even though their plan is stored beside
+the author brief at `.maggie/design/author-<id>.json`. Use the same progress
+commands as an in-place job; `status` and `step` resolve both supported job
+locations:
+
+```bash
+maggie design status author-<id> --project .
+maggie design step author-<id> --project . \
+  --step inspect-shell --evidence .maggie/evidence/inspect-shell.json
+```
+
+An author plan is not complete until every `requiredSteps` entry has matching
+evidence and the explicit approval step is recorded.
+
 ## Content UI initialization
 
 Use content UI initialization when `maggie-blog` or
@@ -496,3 +521,39 @@ Follow the shared [Maggie Decision Loop](../../references/decision-loop.md) for
 6. Require explicit final confirmation before any mutation or external write.
 
 If a decision is not relevant, record it as `skipped` with a reason. Do not silently assume a missing choice, and do not treat an existing output as permission to skip required work.
+
+## Contract checks for dashboards, samples, and progressive enhancement
+
+Run these stable evidence checks after implementation:
+
+```bash
+maggie design progressive-check --evidence .maggie/progressive.json
+maggie design css-check --html dist/index.html --css dist/assets/app.css
+maggie design css-cascade-check --evidence .maggie/css-cascade.json
+maggie design dash-init --project . --route /_maggie/admin --confirm
+maggie design dash-validate --plan .maggie/design/dashboard/*/plan.json --evidence .maggie/dashboard-evidence.json
+maggie design sample-init --project . --route /layout-sample --purpose "layout exploration" --confirm
+maggie design sample-validate --plan .maggie/design/sample/*/plan.json --evidence .maggie/sample-evidence.json
+```
+
+The checks cover smallest-region swaps, stable DOM identities, third-party
+requests, stale responsive Tailwind utilities, and unlayered CSS winning over
+utilities. Dashboard plans require operator journeys and desktop/tablet/mobile,
+collapsed-rail, mobile-drawer, and modal evidence. Sample plans require
+noindex, sitemap exclusion, a visible sample banner, placeholders, and a
+finish checklist.
+
+For generated or converted pages, run the markup gate before handing the page
+to a host editor:
+
+```bash
+maggie design markup-check --html src/pages/about.astro --require-content-keys
+maggie design style-check --manifest .maggie/style-editing.json
+```
+
+Editable copy uses stable `data-maggie-content-key` values. Never key prices,
+durations, opening times, contact details, entity identifiers, or mixed markup
+without an explicit host contract. Decode HTML entities exactly once; unknown
+or double-escaped entities stop the check. Optional empty attributes such as
+`style=""` must be omitted. Codemods using compiler positions must anchor at
+the opening `<tag` before slicing source text.

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

@@ -60,6 +60,18 @@ requires HTTP 200, a readable square image, and an engine-supported ICO, PNG,
 or GIF response. A logo-shaped source filename is only an unverified source
 candidate; it is never evidence that the public favicon route works.
 
+For npm 11 installation or package release work, run the safe preflight before
+an install mutation:
+
+```bash
+maggie npm11 --project . --output .maggie/npm11-preflight.json
+```
+
+The gate records the observed Node/npm versions, lockfile policy, lifecycle
+script policy, and an ignore-scripts-first smoke boundary. A project with
+`install`, `preinstall`, or `postinstall` scripts requires an explicit
+maintainer decision; Maggie never runs an untrusted install script implicitly.
+
 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.

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

@@ -104,6 +104,29 @@ The strict flag is for a review window where a crawler request is expected; it
 fails only when the supplied log contains no sitemap request. Never upload raw
 logs or include IPs, credentials, or query data in feedback or reports.
 
+### GSC readiness release gate
+
+GSC readiness is part of the existing analytics release gate, not an implied
+result of having a sitemap. Produce redacted evidence for the property,
+verification, canonical origin, robots, sitemap, read-only authorization,
+query/readback, and production smoke:
+
+```bash
+maggie analytics gsc-readiness \
+  --gsc-evidence .maggie/gsc-readiness.json
+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 \
+  --gsc-evidence .maggie/gsc-readiness.json --require-gsc
+```
+
+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.
+
 ## Freeze and compare a reviewed site
 
 ```bash
@@ -381,3 +404,25 @@ backed by a content-change/source-revision event; operational sync, pull,
 deploy, or `updated_at` timestamps are rejected. The agent-file command emits
 locale-aware `llms.txt`, `sitemap.md`, and `insights.md` from the same route
 inventory; non-indexable routes are omitted.
+
+For every release, audit third-party privacy origins:
+
+```bash
+maggie seo privacy-check --evidence .maggie/privacy-origin-evidence.json
+```
+
+The site audit also records `primary_navigation_indexability` and flags a
+same-origin page linked from primary navigation when it is `noindex`,
+`nofollow`, or `none`. The privacy check fails in both directions: an embedded
+origin missing from the policy, or a policy origin never observed in rendered
+pages, requires review.
+
+Noindex pages are still audited structurally. The crawl reports
+`indexabilityIfIndexed` with title, description, canonical, heading, and
+JSON-LD checks that would fail if the route became indexable. This is
+diagnostic evidence only; it does not change robots directives or sitemap
+membership. Baseline drift recapture requires a reviewer reason and records an
+expiring acknowledgement (`--reason-ttl-days`, default 30 days).
+
+Internal-link extraction is DOM-only. Text inside `script`, `style`,
+`noscript`, and comments is never treated as an anchor or link target.

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

@@ -502,3 +502,17 @@ later sync are marked `archived`, retained for reconciliation, and excluded
 from active category context and public fact gates. After every sync, run
 `fact-audit`, `category-context`, the category hash/render/audit sequence, and
 the aggregate `maggie_release.py` gate.
+
+### Treatment groups
+
+Keep one treatment catalogue entry and put length/price choices in its
+`variants` array. Imports emit `treatmentGroup` with variant count, duration
+range, and a from-price summary. Run the gate before rendering service cards:
+
+```bash
+maggie service treatment-group-audit --project .
+```
+
+This prevents a 30/60/90/120-minute treatment from becoming four unrelated
+products and gives catalogue, detail, booking, and pricing surfaces one stable
+identity.

package/bundled-tools/clis/maggie_analytics.py

@@ -48,6 +48,33 @@ def load_json(path: Path, label: str) -> tuple[dict | None, list[str]]:
     return value, []
 
 
+def gsc_checks(evidence: dict) -> dict[str, bool]:
+    required = {
+        "property": isinstance(evidence.get("property"), dict) and bool(evidence["property"].get("siteUrl")),
+        "verification": isinstance(evidence.get("verification"), dict) and evidence["verification"].get("passed") is True,
+        "canonical": isinstance(evidence.get("canonical"), dict) and evidence["canonical"].get("passed") is True,
+        "robots": isinstance(evidence.get("robots"), dict) and evidence["robots"].get("passed") is True,
+        "sitemap": isinstance(evidence.get("sitemap"), dict) and evidence["sitemap"].get("passed") is True,
+        "authorization": isinstance(evidence.get("authorization"), dict) and evidence["authorization"].get("readOnly") is True and evidence["authorization"].get("authorized") is True,
+        "query-readback": isinstance(evidence.get("queryReadback"), dict) and evidence["queryReadback"].get("passed") is True,
+        "production-smoke": isinstance(evidence.get("productionSmoke"), dict) and evidence["productionSmoke"].get("passed") is True,
+    }
+    return required
+
+
+def gsc_readiness(args: argparse.Namespace) -> int:
+    evidence, errors = load_json(Path(args.evidence).resolve(), "gsc evidence")
+    checks = gsc_checks(evidence or {})
+    failed = [name for name, passed in checks.items() if not passed]
+    errors.extend(failed)
+    if evidence and evidence.get("schemaVersion") != "maggie-gsc-readiness.v1":
+        errors.append("schemaVersion must be maggie-gsc-readiness.v1")
+    result = {"schemaVersion": "maggie-gsc-readiness-report.v1", "passed": not errors, "checks": checks, "failedChecks": failed, "errors": errors, "readOnly": True}
+    return_code = 0 if result["passed"] else 1
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return return_code
+
+
 def release_gate(args: argparse.Namespace) -> int:
     project = Path(args.project).resolve()
     checks: dict[str, dict] = {}
@@ -87,6 +114,14 @@ def release_gate(args: argparse.Namespace) -> int:
     errors.extend(provider_errors)
     smoke, smoke_errors = load_json(Path(args.smoke_report).resolve(), "smoke-report")
     errors.extend(smoke_errors)
+    if args.gsc_evidence:
+        gsc, gsc_errors = load_json(Path(args.gsc_evidence).resolve(), "gsc-evidence")
+        errors.extend(gsc_errors)
+        checks.update({f"gsc-{name}": {"passed": passed, "evidence": "maggie-gsc-readiness.v1"} for name, passed in gsc_checks(gsc or {}).items()})
+        if gsc and gsc.get("schemaVersion") != "maggie-gsc-readiness.v1":
+            errors.append("gsc-evidence-schema")
+    elif args.require_gsc:
+        errors.append("gsc-evidence-required")
     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)
@@ -144,7 +179,7 @@ def release_gate(args: argparse.Namespace) -> int:
 
 def main() -> int:
     parser = argparse.ArgumentParser()
-    parser.add_argument("command", nargs="?", choices=("release-gate", "traffic-audit"))
+    parser.add_argument("command", nargs="?", choices=("release-gate", "traffic-audit", "gsc-readiness"))
     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")
@@ -154,8 +189,15 @@ def main() -> int:
     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")
+    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("--events", help="redacted JSON array of analytics events for traffic-audit")
     args = parser.parse_args()
+    if args.command == "gsc-readiness":
+        if not args.gsc_evidence:
+            parser.error("gsc-readiness requires --gsc-evidence")
+        args.evidence = args.gsc_evidence
+        return gsc_readiness(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):