@topy-ai/maggie 0.7.36 → 0.7.37

package/bundled-tools/clis/maggie_booking.py

@@ -0,0 +1,1080 @@
+#!/usr/bin/env python3
+"""Install and validate the MaggieDash Booking workspace and host boundary."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import secrets
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+# Source checkouts keep contracts and the delivery board at repository root;
+# npm packages keep the same artifacts under bundled-contracts. Resolve both
+# layouts so the published CLI uses the exact same Booking gates as the repo.
+PACKAGED_CONTRACTS_ROOT = REPO_ROOT / "bundled-contracts"
+CONTRACTS_ROOT = PACKAGED_CONTRACTS_ROOT if PACKAGED_CONTRACTS_ROOT.is_dir() else REPO_ROOT / "contracts"
+DEFAULT_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-host-adapter-v1.json"
+DEFAULT_ACCESS_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-access-v1.json"
+DEFAULT_EMAIL_TEMPLATES_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-email-templates-v1.json"
+DEFAULT_OPS_EVIDENCE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "booking-ops-evidence-v1.json"
+DEFAULT_STRIPE_CONTRACT = CONTRACTS_ROOT / "maggiedash" / "stripe-booking-capabilities-v1.json"
+EXECUTION_BOARD = (
+    CONTRACTS_ROOT / "maggiedash" / "execution-board.json"
+    if PACKAGED_CONTRACTS_ROOT.is_dir()
+    else REPO_ROOT / "docs" / "maggiedash-booking" / "EXECUTION-BOARD.json"
+)
+
+
+def load_json(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise RuntimeError(f"could not read JSON: {path}: {error}") from error
+    if not isinstance(value, dict):
+        raise RuntimeError(f"JSON object required: {path}")
+    return value
+
+
+def load_gate_json(path: Path, label: str) -> tuple[dict | None, str | None]:
+    try:
+        return load_json(path), None
+    except RuntimeError as error:
+        return None, f"{label}: {error}"
+
+
+def load_execution_board(path: Path = EXECUTION_BOARD) -> dict:
+    board = load_json(path)
+    if board.get("schemaVersion") != "maggiedash-booking-execution-board.v1":
+        raise RuntimeError("unsupported Booking execution board schema")
+    if not isinstance(board.get("tasks"), list):
+        raise RuntimeError("Booking execution board tasks must be a list")
+    return board
+
+
+def execution_board_checks(board: dict) -> list[str]:
+    errors: list[str] = []
+    tasks = board.get("tasks") or []
+    allowed_statuses = {"planned", "in_progress", "needs-evidence", "blocked", "passed"}
+    required_fields = {"id", "epic", "title", "repository", "dependsOn", "status", "plan", "implementation", "tests", "docs", "acceptance"}
+    ids: set[str] = set()
+    for task in tasks:
+        if not isinstance(task, dict):
+            errors.append("task must be an object")
+            continue
+        task_id = task.get("id")
+        if not task_id or task_id in ids: errors.append(f"duplicate or missing task id: {task_id or 'unknown'}")
+        ids.add(str(task_id))
+        missing = sorted(required_fields - set(task))
+        if missing: errors.append(f"{task_id}: missing fields {','.join(missing)}")
+        if task.get("status") not in allowed_statuses: errors.append(f"{task_id}: unsupported status {task.get('status')}")
+        for field in ("dependsOn", "plan", "implementation", "tests", "docs", "acceptance"):
+            if not isinstance(task.get(field), list) or not task.get(field): errors.append(f"{task_id}: {field} must be a non-empty list")
+    for task in tasks:
+        if not isinstance(task, dict): continue
+        for dependency in task.get("dependsOn", []):
+            if dependency not in ids and not (isinstance(dependency, str) and dependency.startswith("BK-0") and int(dependency.split("-")[1]) <= 16):
+                errors.append(f"{task.get('id')}: unknown dependency {dependency}")
+    if board.get("workflow") != ["task", "plan", "implement", "test", "update-docs", "record-progress"]:
+        errors.append("workflow must be task -> plan -> implement -> test -> update-docs -> record-progress")
+    return errors
+
+
+def board_result(board: dict) -> dict:
+    errors = execution_board_checks(board)
+    tasks = [item for item in board.get("tasks", []) if isinstance(item, dict)]
+    unfinished = [item.get("id") for item in tasks if item.get("status") != "passed"]
+    return {
+        "status": "passed" if not errors and not unfinished else "blocked",
+        "tasks": len(tasks),
+        "passed": len(tasks) - len(unfinished),
+        "unfinished": unfinished,
+        "errors": errors,
+    }
+
+
+def task_ready(task: dict, by_id: dict[str, dict]) -> bool:
+    for dependency in task.get("dependsOn", []):
+        dependency_task = by_id.get(dependency)
+        if dependency_task and dependency_task.get("status") != "passed": return False
+    return task.get("status") in {"planned", "in_progress", "needs-evidence"}
+
+
+def command_tasks(args: argparse.Namespace) -> int:
+    board_path = Path(args.board).expanduser().resolve() if args.board else EXECUTION_BOARD
+    board = load_execution_board(board_path)
+    errors = execution_board_checks(board)
+    tasks = [item for item in board.get("tasks", []) if isinstance(item, dict)]
+    by_id = {item.get("id"): item for item in tasks}
+    if args.task_command == "validate":
+        result = {"status": "passed" if not errors else "failed", "board": str(board_path), "tasks": len(tasks), "errors": errors}
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if not errors else 1
+    if args.task_command == "show":
+        task = by_id.get(args.task_id)
+        if not task:
+            print(json.dumps({"status": "not-found", "task": args.task_id}, indent=2, ensure_ascii=False))
+            return 1
+        print(json.dumps({**task, "ready": task_ready(task, by_id)}, indent=2, ensure_ascii=False))
+        return 0
+    if args.task_command == "list":
+        selected = [item for item in tasks if not args.status or item.get("status") == args.status]
+        print(json.dumps({"status": "passed" if not errors else "failed", "board": str(board_path), "items": [{"id": item.get("id"), "title": item.get("title"), "status": item.get("status"), "ready": task_ready(item, by_id), "dependsOn": item.get("dependsOn", [])} for item in selected], "errors": errors}, indent=2, ensure_ascii=False))
+        return 0 if not errors else 1
+    raise RuntimeError(f"unknown task command: {args.task_command}")
+
+
+def stripe_contract_checks(contract: dict, max_age_days: int = 120) -> list[str]:
+    errors: list[str] = []
+    schema_version = contract.get("schemaVersion") or (contract.get("properties") or {}).get("schemaVersion", {}).get("const")
+    provider = contract.get("provider") or (contract.get("properties") or {}).get("provider", {}).get("const")
+    scope = contract.get("scope") or (contract.get("properties") or {}).get("scope", {}).get("const")
+    if schema_version != "maggiedash-stripe-booking-capabilities.v1": errors.append("schemaVersion must be maggiedash-stripe-booking-capabilities.v1")
+    if provider != "stripe": errors.append("provider must be stripe")
+    if scope != "booking-and-business-operations": errors.append("scope must cover booking-and-business-operations")
+    policy = contract.get("x-api-version-policy") or contract.get("apiVersionPolicy") or {}
+    for field in ("accountScoped", "pinServerVersion", "upgradeInSandbox", "avoidChargesForNewFlows"):
+        if policy.get(field) is not True: errors.append(f"Stripe API version policy {field} must be true")
+    apis = contract.get("x-api-matrix") or contract.get("apis") or []
+    api_ids = {item.get("id") for item in apis if isinstance(item, dict)}
+    required_apis = {"customers", "checkout_sessions", "payment_intents", "setup_intents", "refunds", "events", "promotion_codes", "coupons", "customer_balance_transactions", "subscriptions", "invoices", "customer_portal_sessions", "tax", "terminal", "connect"}
+    errors.extend(f"missing API matrix entry: {item}" for item in sorted(required_apis - api_ids))
+    events = contract.get("x-webhook-events") or contract.get("webhookEvents") or []
+    event_ids = {item.get("eventType") for item in events if isinstance(item, dict)}
+    required_events = {"checkout.session.completed", "checkout.session.async_payment_succeeded", "checkout.session.async_payment_failed", "payment_intent.processing", "payment_intent.payment_failed", "payment_intent.succeeded", "payment_intent.requires_action", "payment_intent.canceled", "refund.created", "refund.updated", "refund.failed"}
+    errors.extend(f"missing webhook event: {item}" for item in sorted(required_events - event_ids))
+    native = contract.get("x-native-capabilities") or contract.get("nativeCapabilities") or {}
+    if native.get("giftCards") != "not-native": errors.append("giftCards must remain not-native")
+    if native.get("referrals") != "not-native": errors.append("referrals must remain not-native")
+    if native.get("discountCodes") != "native": errors.append("discountCodes must be native")
+    verified = contract.get("x-last-verified-at") or contract.get("lastVerifiedAt")
+    try:
+        age_days = (datetime.now(timezone.utc).date() - datetime.fromisoformat(str(verified)).date()).days
+        if age_days < 0 or age_days > max_age_days: errors.append(f"Stripe contract verification is {age_days} days old")
+    except (TypeError, ValueError):
+        errors.append("lastVerifiedAt must be an ISO date")
+    return errors
+
+
+def contract_checks(contract: dict) -> list[str]:
+    errors: list[str] = []
+    schema_version = contract.get("schemaVersion")
+    api_prefix = contract.get("apiPrefix")
+    auth = contract.get("auth") or {}
+    endpoint_ids = contract.get("endpointIds")
+    if isinstance(contract.get("properties"), dict):
+        properties = contract["properties"]
+        schema_version = (properties.get("schemaVersion") or {}).get("const")
+        api_prefix = (properties.get("apiPrefix") or {}).get("const")
+        auth_properties = (properties.get("auth") or {}).get("properties") or {}
+        auth = {
+            "managerSession": (auth_properties.get("managerSession") or {}).get("const"),
+            "emailPassword": (auth_properties.get("emailPassword") or {}).get("const"),
+            "passkeys": (auth_properties.get("passkeys") or {}).get("const"),
+        }
+        endpoint_ids = [item.get("id") for item in contract.get("x-endpoints", []) if isinstance(item, dict) and item.get("id")]
+    if schema_version != "maggiedash-booking-host-adapter.v1": errors.append("schemaVersion must be maggiedash-booking-host-adapter.v1")
+    if api_prefix != "/api/maggie/booking": errors.append("apiPrefix must be /api/maggie/booking")
+    if auth.get("managerSession") != "host-session-cookie": errors.append("managerSession must use the host session cookie")
+    if auth.get("emailPassword") is not True: errors.append("emailPassword must be enabled")
+    if auth.get("passkeys") is not False: errors.append("passkeys must be disabled")
+    required = contract.get("requiredCapabilities")
+    if required is None and isinstance(contract.get("properties"), dict): required = ["bookingOverview", "bookingCalendar", "bookingLifecycle"]
+    if not isinstance(required, list) or not required: errors.append("requiredCapabilities must be a non-empty list")
+    if not isinstance(endpoint_ids, list) or len(endpoint_ids) != len(set(endpoint_ids)): errors.append("endpointIds must be unique")
+    if not endpoint_ids or not all(str(value).startswith("booking.") for value in endpoint_ids): errors.append("endpointIds must use the booking namespace")
+    if isinstance(contract.get("properties"), dict):
+        endpoints = [item for item in contract.get("x-endpoints", []) if isinstance(item, dict)]
+        if not endpoints: errors.append("detailed host contract must declare x-endpoints")
+        if len(endpoint_ids or []) != len(set(endpoint_ids or [])): errors.append("detailed host endpoint IDs must be unique")
+        if any(not isinstance(item.get("serviceMethod"), str) or not item.get("serviceMethod") for item in endpoints): errors.append("detailed host endpoints must declare serviceMethod")
+    else:
+        service_methods = contract.get("serviceMethods")
+        if not isinstance(service_methods, dict) or set(service_methods) != set(endpoint_ids or []): errors.append("serviceMethods must map every endpoint exactly once")
+        elif not all(isinstance(value, str) and value for value in service_methods.values()): errors.append("serviceMethods values must be non-empty strings")
+        customer_methods = contract.get("customerServiceMethods")
+        if customer_methods != ["readPublicCatalog", "readPublicAvailability", "createCustomerHold", "startCustomerCheckout", "readCustomerPaymentReturn", "readCustomerManage", "cancelCustomerBooking", "rescheduleCustomerBooking", "joinCustomerWaitlist"]: errors.append("customerServiceMethods must declare the nine public customer methods")
+    return errors
+
+
+def access_contract_checks(contract: dict) -> list[str]:
+    errors: list[str] = []
+    properties = contract.get("properties") if isinstance(contract.get("properties"), dict) else {}
+    if properties:
+        schema_version = (properties.get("schemaVersion") or {}).get("const")
+        api_prefix = (properties.get("apiPrefix") or {}).get("const")
+        auth_properties = (properties.get("auth") or {}).get("properties") or {}
+        auth = {key: (auth_properties.get(key) or {}).get("const") for key in ("administratorSession", "emailPassword", "passkeys", "resendInvitation")}
+        roles = (properties.get("roles") or {}).get("const")
+        permissions = (properties.get("permissions") or {}).get("const") or []
+        endpoint_items = [item for item in contract.get("x-endpoints", []) if isinstance(item, dict)]
+        endpoint_ids = [item.get("id") for item in endpoint_items]
+        routes = {item.get("id"): f"{item.get('method')} {item.get('route')}" for item in endpoint_items if item.get("id")}
+        policy_properties = (properties.get("policy") or {}).get("properties") or {}
+        policy = {key: (policy_properties.get(key) or {}).get("const") for key in ("tenantScoped", "disabledAccountsStayDisabled", "passwordMinimumLength")}
+    else:
+        schema_version = contract.get("schemaVersion")
+        api_prefix = contract.get("apiPrefix")
+        auth = contract.get("auth") or {}
+        roles = contract.get("roles")
+        permissions = contract.get("permissions") or []
+        endpoint_ids = contract.get("endpointIds") or [item.get("id") for item in contract.get("x-endpoints", []) if isinstance(item, dict)]
+        routes = contract.get("canonicalRoutes") or {}
+        policy = contract.get("policy") or {}
+    if schema_version != "maggiedash-booking-access.v1": errors.append("schemaVersion must be maggiedash-booking-access.v1")
+    if api_prefix != "/api/maggie/booking/access.json": errors.append("apiPrefix must be /api/maggie/booking/access.json")
+    if auth.get("administratorSession") != "host-session-cookie": errors.append("administratorSession must use the host session cookie")
+    if auth.get("emailPassword") is not True: errors.append("emailPassword must be enabled")
+    if auth.get("passkeys") is not False: errors.append("passkeys must be disabled")
+    if auth.get("resendInvitation") is not True: errors.append("resendInvitation must be enabled")
+    if roles != ["manager", "staff", "finance"]: errors.append("roles must be manager, staff, finance")
+    for permission in ("calendar.read", "bookings.manage", "payments.manage", "refunds.manage", "audit.read"):
+        if permission not in permissions: errors.append(f"missing permission: {permission}")
+    if endpoint_ids != ["booking.access.read", "booking.access.create", "booking.access.update", "booking.access.revoke"]: errors.append("access endpoint IDs are incomplete or out of order")
+    expected = {"booking.access.read": "GET /access.json", "booking.access.create": "POST /access.json", "booking.access.update": "PATCH /access.json", "booking.access.revoke": "DELETE /access.json"}
+    if routes != expected: errors.append("access canonical routes are incomplete")
+    if policy.get("tenantScoped") is not True or policy.get("disabledAccountsStayDisabled") is not True or policy.get("passwordMinimumLength") != 12: errors.append("access safety policy is incomplete")
+    return errors
+
+
+def email_templates_contract_checks(contract: dict) -> list[str]:
+    errors: list[str] = []
+    properties = contract.get("properties") if isinstance(contract.get("properties"), dict) else {}
+    if properties:
+        schema_version = (properties.get("schemaVersion") or {}).get("const")
+        api_prefix = (properties.get("apiPrefix") or {}).get("const")
+        auth_properties = (properties.get("auth") or {}).get("properties") or {}
+        auth = {key: (auth_properties.get(key) or {}).get("const") for key in ("managerSession", "emailPassword", "passkeys")}
+        policy_properties = (properties.get("policy") or {}).get("properties") or {}
+        policy = {key: (policy_properties.get(key) or {}).get("const") for key in ("tenantScoped", "allowedRoles", "variableSyntax", "maxHtmlLength", "auditRequired", "idempotencyRequiredForMutations", "syntax", "providerCredentialsRemainServerOnly", "recipientDataNeverReturned")}
+        roles = policy.get("allowedRoles")
+        endpoint_items = [item for item in contract.get("endpoints", []) if isinstance(item, dict)]
+        endpoint_ids = [item.get("id") for item in endpoint_items]
+        routes = {item.get("id"): f"{item.get('method')} {item.get('route')}" for item in endpoint_items if item.get("id")}
+    else:
+        schema_version = contract.get("schemaVersion")
+        api_prefix = contract.get("apiPrefix")
+        auth = contract.get("auth") or {}
+        policy = contract.get("policy") or {}
+        roles = contract.get("roles")
+        endpoint_ids = contract.get("endpointIds")
+        routes = contract.get("canonicalRoutes") or {}
+    if schema_version != "maggiedash-booking-email-templates.v1": errors.append("schemaVersion must be maggiedash-booking-email-templates.v1")
+    if api_prefix != "/api/maggie/booking/email-templates.json": errors.append("apiPrefix must be /api/maggie/booking/email-templates.json")
+    if auth.get("managerSession") != "host-session-cookie": errors.append("managerSession must use the host session cookie")
+    if auth.get("emailPassword") is not True: errors.append("emailPassword must be enabled")
+    if auth.get("passkeys") is not False: errors.append("passkeys must be disabled")
+    if roles != ["owner", "admin", "manager"]: errors.append("roles must be owner, admin, manager")
+    events = contract.get("events")
+    if not isinstance(events, list) or len(events) != 7: errors.append("exactly seven Booking email events are required")
+    event_ids = [item.get("id") for item in events if isinstance(item, dict)] if isinstance(events, list) else []
+    expected_events = ["booking.confirmed", "booking.rescheduled", "booking.cancelled", "booking.reminder", "payment.action_required", "payment.refunded", "booking.waitlist.available"]
+    if event_ids != expected_events: errors.append("email event IDs are incomplete or out of order")
+    if len(event_ids) != len(set(event_ids)): errors.append("email event IDs must be unique")
+    allowed = {"customerName", "serviceName", "when", "locationName", "bookingId", "manageUrl", "bookingUrl", "reason", "actionUrl", "siteName"}
+    for event in events if isinstance(events, list) else []:
+        variables = event.get("variables") if isinstance(event, dict) else None
+        if not isinstance(variables, list) or not variables: errors.append(f"{event.get('id', 'unknown')}: variables must be a non-empty list")
+        if any(variable not in allowed for variable in variables or []): errors.append(f"{event.get('id', 'unknown')}: unsupported template variable")
+    if endpoint_ids != ["booking.email-templates.read", "booking.email-templates.draft", "booking.email-templates.publish", "booking.email-templates.rollback"]: errors.append("email template endpoint IDs are incomplete or out of order")
+    expected_routes = {
+        "booking.email-templates.read": "GET /email-templates.json",
+        "booking.email-templates.draft": "PATCH /email-templates.json?action=draft",
+        "booking.email-templates.publish": "PATCH /email-templates.json?action=publish",
+        "booking.email-templates.rollback": "PATCH /email-templates.json?action=rollback",
+    }
+    if routes != expected_routes: errors.append("email template canonical routes are incomplete")
+    if policy.get("tenantScoped") is not True or policy.get("auditRequired") is not True or policy.get("idempotencyRequiredForMutations") is not True: errors.append("email template tenant, audit, and idempotency policies are required")
+    syntax = policy.get("syntax") or policy.get("variableSyntax")
+    if syntax not in ("{{variable}}", "{{name}}") or policy.get("maxHtmlLength") != 50000: errors.append("email template syntax or length policy is incorrect")
+    if policy.get("providerCredentialsRemainServerOnly") is not True or policy.get("recipientDataNeverReturned") is not True: errors.append("email template provider and recipient privacy policy is incomplete")
+    return errors
+
+
+def customer_contract_checks(contract: dict) -> list[str]:
+    errors: list[str] = []
+    properties = contract.get("properties") if isinstance(contract.get("properties"), dict) else {}
+    if properties:
+        schema_version = (properties.get("schemaVersion") or {}).get("const")
+        api_prefix = (properties.get("apiPrefix") or {}).get("const")
+        security = properties.get("security") or {}
+        security_properties = security.get("properties") or {}
+        auth = security_properties.get("auth", {}).get("const")
+        noindex = security_properties.get("noindex", {}).get("const")
+        endpoints = [item for item in contract.get("x-endpoints", []) if isinstance(item, dict)]
+        ids = [item.get("id") for item in endpoints]
+    else:
+        schema_version = contract.get("schemaVersion")
+        api_prefix = contract.get("apiPrefix")
+        auth = contract.get("auth")
+        noindex = contract.get("noindex")
+        ids = [str(item) for item in contract.get("endpointIds", [])]
+        response_policy = contract.get("responsePolicy") if isinstance(contract.get("responsePolicy"), dict) else {}
+        canonical = contract.get("canonicalRoutes") or {}
+        endpoints = []
+        for item in ids:
+            route = str(canonical.get(item, ""))
+            method, _, relative = route.partition(" ")
+            endpoints.append({"id": item, "method": method, "route": relative, "idempotent": method == "GET" or item.endswith((".create", ".start", ".cancel", "-cancel", ".reschedule", "-reschedule", ".join"))})
+    if schema_version != "maggiedash-booking-customer-surface.v1": errors.append("schemaVersion must be maggiedash-booking-customer-surface.v1")
+    if api_prefix != "/api/maggie/booking/public": errors.append("apiPrefix must be /api/maggie/booking/public")
+    page_path = (properties.get("pagePath") or {}).get("const") if properties else contract.get("pagePath")
+    if page_path != "/_maggie/booking/book": errors.append("pagePath must be /_maggie/booking/book")
+    if auth != "public-noindex": errors.append("customer auth must be public-noindex")
+    if noindex is not True: errors.append("customer surface must be noindex")
+    if properties == {} and response_policy.get("mutationPolicy") != "all-public-mutations-require-idempotency-key-and-replay-original-result": errors.append("customer mutationPolicy must require idempotent replay")
+    if properties == {} and set(response_policy.get("holdInputPolicy", [])) != {"valid-email", "booking-update-consent"}: errors.append("customer holdInputPolicy must require valid email and booking-update-consent")
+    if len(endpoints) != 9: errors.append("customer surface must declare nine endpoints")
+    if len(ids) != len(set(ids)): errors.append("customer endpoint IDs must be unique")
+    if not all(str(item).startswith("booking.public.") for item in ids): errors.append("customer endpoint IDs must use the booking.public namespace")
+    for endpoint in endpoints:
+        if endpoint.get("method") not in {"GET", "POST"}: errors.append(f"{endpoint.get('id')}: customer method is unsupported")
+        if not str(endpoint.get("route", "")).startswith("/"): errors.append(f"{endpoint.get('id')}: customer route must be relative")
+        if endpoint.get("idempotent") is not True: errors.append(f"{endpoint.get('id')}: customer route must be idempotent")
+    return errors
+
+
+def command_contract(args: argparse.Namespace) -> int:
+    path = Path(args.contract).expanduser().resolve()
+    contract = load_json(path)
+    errors = contract_checks(contract)
+    endpoint_items = contract.get("endpointIds") or [item.get("id") for item in contract.get("x-endpoints", []) if isinstance(item, dict) and item.get("id")]
+    result = {"status": "passed" if not errors else "failed", "contract": str(path), "schemaVersion": contract.get("schemaVersion"), "endpointCount": len(endpoint_items), "errors": errors}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def command_access_contract(args: argparse.Namespace) -> int:
+    path = Path(args.contract).expanduser().resolve()
+    contract = load_json(path)
+    errors = access_contract_checks(contract)
+    properties = contract.get("properties") if isinstance(contract.get("properties"), dict) else {}
+    endpoint_items = contract.get("endpointIds") or [item.get("id") for item in contract.get("x-endpoints", []) if isinstance(item, dict) and item.get("id")]
+    result = {"status": "passed" if not errors else "failed", "contract": str(path), "schemaVersion": contract.get("schemaVersion") or (properties.get("schemaVersion") or {}).get("const"), "endpointCount": len(endpoint_items), "errors": errors}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def command_email_templates_contract(args: argparse.Namespace) -> int:
+    path = Path(args.contract).expanduser().resolve()
+    contract = load_json(path)
+    errors = email_templates_contract_checks(contract)
+    properties = contract.get("properties") if isinstance(contract.get("properties"), dict) else {}
+    endpoint_items = contract.get("endpointIds") or [item.get("id") for item in contract.get("endpoints", []) if isinstance(item, dict) and item.get("id")]
+    result = {"status": "passed" if not errors else "failed", "contract": str(path), "schemaVersion": contract.get("schemaVersion") or (properties.get("schemaVersion") or {}).get("const"), "eventCount": len(contract.get("events") or []), "endpointCount": len(endpoint_items), "errors": errors}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def project_path(args: argparse.Namespace) -> Path:
+    return Path(args.project).expanduser().resolve()
+
+
+def middleware_has_booking_rewrites(text: str) -> bool:
+    """Accept both TypeScript regex source (`\\/`) and plain path markers."""
+    normalized = text.replace("\\/", "/")
+    return all(marker in normalized for marker in ("/_maggie/booking", "/_maggie/login", "/_maggie/register"))
+
+
+ENV_FILES = (
+    ".env",
+    ".env.local",
+    ".env.production",
+    ".env.production.local",
+    ".env.maggie-booking",
+    ".env.maggie-booking.local",
+)
+
+REQUIRED_HOST_DEPENDENCIES = (
+    "@astrojs/react",
+    "@phosphor-icons/react",
+    "@tailwindcss/vite",
+    "pg",
+    "react",
+    "react-dom",
+    "stripe",
+    "tailwindcss",
+)
+
+# Keep the host install path reproducible without taking ownership of the
+# host's Astro version. Existing dependencies are left untouched; only
+# missing packages are added by `--install-dependencies`.
+HOST_DEPENDENCY_RANGES = {
+    "@astrojs/react": "^6.0.0",
+    "@phosphor-icons/react": "^2.1.10",
+    "@tailwindcss/vite": "^4.0.0",
+    "pg": "^8.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "stripe": "^22.0.0",
+    "tailwindcss": "^4.0.0",
+}
+
+
+def missing_host_dependencies(root: Path) -> list[str]:
+    """Return only host packages absent from both dependency sections."""
+    try:
+        package = json.loads((root / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return list(REQUIRED_HOST_DEPENDENCIES)
+    installed = set(package.get("dependencies") or {}) | set(package.get("devDependencies") or {})
+    return sorted(name for name in REQUIRED_HOST_DEPENDENCIES if name not in installed)
+
+
+def host_package_manager(root: Path) -> tuple[str, list[str]]:
+    """Select the package manager already declared by the host project."""
+    lockfiles = (
+        ("pnpm-lock.yaml", "pnpm"),
+        ("yarn.lock", "yarn"),
+        ("bun.lockb", "bun"),
+        ("bun.lock", "bun"),
+        ("package-lock.json", "npm"),
+    )
+    manager = next((name for filename, name in lockfiles if (root / filename).is_file()), "npm")
+    if shutil.which(manager) is None:
+        raise RuntimeError(f"{manager} is required to install Booking host dependencies but is not available on PATH")
+    packages = [f"{name}@{HOST_DEPENDENCY_RANGES[name]}" for name in missing_host_dependencies(root)]
+    if manager == "npm":
+        return manager, ["npm", "install", "--save", "--no-audit", "--no-fund", *packages]
+    if manager == "pnpm":
+        return manager, ["pnpm", "add", *packages]
+    if manager == "yarn":
+        return manager, ["yarn", "add", *packages]
+    return manager, ["bun", "add", *packages]
+
+
+def install_host_dependencies(root: Path, runner=None) -> dict:
+    """Install only missing Astro Booking packages through the host manager."""
+    missing = missing_host_dependencies(root)
+    if not missing:
+        return {"status": "unchanged", "missing": [], "packageManager": None, "command": []}
+    manager, command = host_package_manager(root)
+    execute = runner or subprocess.run
+    completed = execute(command, cwd=root, check=False)
+    if completed.returncode != 0:
+        raise RuntimeError(f"{manager} failed while installing {len(missing)} missing Booking host dependencies")
+    return {"status": "installed", "missing": missing, "packageManager": manager, "command": [manager, "add" if manager != "npm" else "install", *[f"{name}@{HOST_DEPENDENCY_RANGES[name]}" for name in missing]]}
+
+
+def _meaningful_env_value(value: str) -> bool:
+    """Return whether a dotenv value is configured without exposing it."""
+    normalized = value.strip().strip('"').strip("'").strip()
+    if not normalized:
+        return False
+    if normalized.startswith("<") and normalized.endswith(">"):
+        return False
+    if normalized in {"...", "changeme", "change-me", "your-value", "your_value"}:
+        return False
+    return True
+
+
+def _read_env_keys(root: Path, environment: dict[str, str] | None = None) -> dict[str, list[str]]:
+    """Find configured keys while keeping values out of all reports."""
+    sources: dict[str, list[str]] = {}
+    current = environment if environment is not None else os.environ
+    for key, value in current.items():
+        if _meaningful_env_value(str(value)):
+            sources.setdefault(key, []).append("process")
+    assignment = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*(?:#.*)?$")
+    for relative in ENV_FILES:
+        path = root / relative
+        if not path.is_file():
+            continue
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            match = assignment.match(line)
+            if not match or not _meaningful_env_value(match.group(2)):
+                continue
+            key = match.group(1)
+            sources.setdefault(key, []).append(relative)
+    return sources
+
+
+def _read_env_values(root: Path, environment: dict[str, str] | None = None) -> dict[str, str]:
+    """Read values only for local validation; callers must never serialize them."""
+    values: dict[str, str] = {}
+    current = environment if environment is not None else os.environ
+    for key, value in current.items():
+        if _meaningful_env_value(str(value)):
+            values[key] = str(value).strip().strip('"').strip("'").strip()
+    assignment = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*(?:#.*)?$")
+    for relative in ENV_FILES:
+        path = root / relative
+        if not path.is_file():
+            continue
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            continue
+        for line in lines:
+            match = assignment.match(line)
+            if not match or not _meaningful_env_value(match.group(2)):
+                continue
+            values.setdefault(match.group(1), match.group(2).strip().strip('"').strip("'").strip())
+    return values
+
+
+def setup_check(check_id: str, label: str, keys: list[str], configured: bool, *, required: bool = True, detail: str = "", status_override: str | None = None) -> dict:
+    return {
+        "id": check_id,
+        "label": label,
+        "status": status_override or ("passed" if configured else ("missing" if required else "optional")),
+        "required": required,
+        "keys": keys,
+        **({"detail": detail} if detail else {}),
+    }
+
+
+def booking_setup_result(root: Path, environment: dict[str, str] | None = None) -> dict:
+    """Build a safe first-run checklist; never connects to the database or providers."""
+    sources = _read_env_keys(root, environment)
+    values = _read_env_values(root, environment)
+    has = lambda key: bool(sources.get(key))
+    try:
+        package = json.loads((root / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        package = {}
+    installed_dependencies = set((package.get("dependencies") or {})) | set((package.get("devDependencies") or {}))
+    missing_dependencies = sorted(set(REQUIRED_HOST_DEPENDENCIES) - installed_dependencies)
+    has_sender = has("EMAIL_FROM") or has("RESEND_FROM_EMAIL")
+    token_present = has("BOOKING_TOKEN_SECRET")
+    token_valid = token_present and len(values.get("BOOKING_TOKEN_SECRET", "")) >= 32
+    stripe_secret = has("STRIPE_SECRET_KEY")
+    stripe_webhook = has("STRIPE_WEBHOOK_SECRET")
+    stripe_complete = stripe_secret and stripe_webhook
+    stripe_partial = stripe_secret != stripe_webhook
+    workspace = (root / "_maggie" / "booking" / "booking.tsx").is_file()
+    middleware = root / "src" / "middleware.ts"
+    middleware_text = middleware.read_text(encoding="utf-8") if middleware.is_file() else ""
+    middleware_ready = "maggie-auto-rewrite-v1" in middleware_text or middleware_has_booking_rewrites(middleware_text)
+    checks = [
+        {"id": "workspace", "label": "Booking workspace", "status": "passed" if workspace else "missing", "required": True},
+        {"id": "middleware", "label": "/_maggie route integration", "status": "passed" if middleware_ready else "missing", "required": True},
+        {"id": "dependencies", "label": "Astro Booking host dependencies", "status": "passed" if not missing_dependencies else "missing", "required": True, "missing": missing_dependencies, "detail": "Install the missing packages before building the host."},
+        setup_check("database", "PostgreSQL connection", ["DATABASE_URL"], has("DATABASE_URL"), detail="Used by manager routes, public booking, schema command, and worker."),
+        setup_check("site", "Public site URL", ["PUBLIC_SITE_URL"], has("PUBLIC_SITE_URL"), detail="Used for login links, booking links, and email URLs."),
+        setup_check("booking-token", "Public booking token secret", ["BOOKING_TOKEN_SECRET"], token_valid, detail="Must be at least 32 characters; used to sign public manage-booking links." if token_valid or not token_present else "The configured secret is too short; use at least 32 characters.", status_override="passed" if token_valid else "invalid" if token_present else None),
+        setup_check("resend", "Resend email delivery", ["RESEND_API_KEY", "EMAIL_FROM|RESEND_FROM_EMAIL"], has("RESEND_API_KEY") and has_sender, detail="Required for password setup/reset, booking notifications, and reminders."),
+        setup_check("stripe", "Stripe online payments", ["STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET"], stripe_complete, required=False, detail="Required only for deposit/full online payment flows; webhook URL is /api/maggie/booking/webhooks/stripe." if not stripe_partial else "Both Stripe secret and webhook secret are required for online payments.", status_override="passed" if stripe_complete else "degraded" if stripe_partial else "optional"),
+        {"id": "schema", "label": "Booking database schema", "status": "not-verified", "required": True, "detail": "The CLI does not connect to PostgreSQL. Apply the schema after backup, then verify with the host runtime checks."},
+        {"id": "owner", "label": "First owner account", "status": "not-verified", "required": True, "detail": "Open /_maggie/register once the schema is applied. Registration closes after the first owner."},
+        {"id": "worker", "label": "Resend worker schedule", "status": "not-verified", "required": True, "detail": "Run the installed worker from a single-flight scheduler; setup does not create a cron or systemd job."},
+    ]
+    missing_required = [item["id"] for item in checks if item.get("required") and item.get("status") in {"missing", "invalid"}]
+    verification_pending = [item["id"] for item in checks if item.get("status") == "not-verified"]
+    missing_config = [item["id"] for item in checks if item.get("status") in {"missing", "invalid"}]
+    degraded_config = [item["id"] for item in checks if item.get("status") == "degraded"]
+    next_steps = []
+    if missing_config:
+        next_steps.append("Add the missing keys to the host secret store or .env file; values are never printed by this command.")
+    if "booking-token" in missing_config:
+        next_steps.append("Regenerate BOOKING_TOKEN_SECRET with at least 32 characters before enabling public customer manage links.")
+    if "stripe" in degraded_config:
+        next_steps.append("Configure both STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET before accepting online payments.")
+    if missing_dependencies:
+        next_steps.append("Install missing host packages with the project package manager: maggie booking install --project . --confirm --install-dependencies")
+    if any(item["id"] == "schema" and item["status"] == "not-verified" for item in checks):
+        next_steps.append("After backup, run: maggie booking install --project . --confirm --bootstrap")
+    if any(item["id"] == "owner" and item["status"] == "not-verified" for item in checks):
+        next_steps.append("Open /_maggie/register and create the first owner, then sign in at /_maggie/login")
+    if any(item["id"] == "worker" and item["status"] == "not-verified" for item in checks):
+        next_steps.append("Configure a single-flight scheduler for: node scripts/maggie-booking-worker.mjs --write --confirm")
+    if not has("STRIPE_SECRET_KEY") or not has("STRIPE_WEBHOOK_SECRET"):
+        next_steps.append("If taking online payments, configure Stripe test keys and POST /api/maggie/booking/webhooks/stripe before live mode.")
+    status = "needs-configuration" if missing_required else "configured-pending-verification"
+    return {
+        "status": status,
+        "project": str(root),
+        "checks": checks,
+        "configuredKeys": sorted(key for key in sources if key in {"DATABASE_URL", "PUBLIC_SITE_URL", "BOOKING_TOKEN_SECRET", "RESEND_API_KEY", "EMAIL_FROM", "RESEND_FROM_EMAIL", "STRIPE_SECRET_KEY", "STRIPE_WEBHOOK_SECRET"}),
+        "verificationPending": verification_pending,
+        "paymentConfiguration": "online-payments" if has("STRIPE_SECRET_KEY") and has("STRIPE_WEBHOOK_SECRET") else "no-payment-or-incomplete-stripe",
+        "next": next_steps,
+        "note": "Read-only checklist. It does not print secrets, connect to PostgreSQL, apply migrations, create an owner, configure Stripe, send email, or deploy.",
+    }
+
+
+def command_setup(args: argparse.Namespace) -> int:
+    result = booking_setup_result(project_path(args))
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["status"] == "configured-pending-verification" else 1
+
+
+def ensure_bootstrap_token_secret(root: Path) -> bool:
+    """Create the local public-booking secret without ever returning its value.
+
+    The host worker and public customer routes both read BOOKING_TOKEN_SECRET
+    from the host environment. A reviewed `--bootstrap` install should not
+    leave a fresh host unusable because an implementation-only secret was
+    forgotten. Existing configured values are never replaced; an existing
+    short value fails closed instead.
+    """
+    values = _read_env_values(root)
+    existing = values.get("BOOKING_TOKEN_SECRET")
+    if existing:
+        if len(existing) < 32:
+            raise RuntimeError("BOOKING_TOKEN_SECRET is configured but shorter than 32 characters; refusing to replace it")
+        return False
+
+    env_path = root / ".env"
+    try:
+        text = env_path.read_text(encoding="utf-8") if env_path.is_file() else ""
+    except OSError as error:
+        raise RuntimeError(f"could not read host environment file: {env_path}: {error}") from error
+    secret = secrets.token_urlsafe(48)
+    assignment = f"BOOKING_TOKEN_SECRET={secret}"
+    pattern = re.compile(r"^\s*BOOKING_TOKEN_SECRET\s*=.*$", re.MULTILINE)
+    if pattern.search(text):
+        updated = pattern.sub(assignment, text, count=1)
+    else:
+        separator = "" if not text or text.endswith("\n") else "\n"
+        updated = text + separator + "\n# Generated by Maggie Booking bootstrap; keep this value in the host secret store.\n" + assignment + "\n"
+    try:
+        env_path.write_text(updated, encoding="utf-8")
+        if not env_path.exists():
+            raise RuntimeError(f"host environment file was not created: {env_path}")
+    except OSError as error:
+        raise RuntimeError(f"could not write host environment file: {env_path}: {error}") from error
+    print(f"BOOKING_TOKEN_SECRET generated in {env_path} (value intentionally hidden)")
+    return True
+
+
+def command_install(args: argparse.Namespace) -> int:
+    """Install Booking, optionally adding missing host packages and schema."""
+    if (args.bootstrap or args.install_dependencies) and (args.dry_run or args.diff):
+        print("INSTALL_MUTATION_INCOMPATIBLE: --bootstrap and --install-dependencies cannot be combined with --dry-run or --diff.", file=sys.stderr)
+        return 2
+    if not args.dry_run and not args.diff and not args.confirm:
+        print("CONFIRMATION_REQUIRED: add --confirm before installing Booking.", file=sys.stderr)
+        return 2
+    root = project_path(args)
+    dash = Path(__file__).with_name("maggie_dash.py")
+    command = [sys.executable, str(dash), "install", "--project", str(root), "--host", args.host]
+    if args.source:
+        command.extend(["--source", args.source])
+    if args.ref:
+        command.extend(["--ref", args.ref])
+    if args.force:
+        command.append("--force")
+    if args.dry_run:
+        command.append("--dry-run")
+    if args.diff:
+        command.append("--diff")
+    if args.existing_dir:
+        command.extend(["--existing-dir", args.existing_dir])
+    if args.confirm:
+        command.append("--confirm")
+    completed = subprocess.run(command, cwd=root, check=False)
+    if completed.returncode != 0:
+        return completed.returncode
+    if args.install_dependencies:
+        try:
+            dependency_result = install_host_dependencies(root)
+        except RuntimeError as error:
+            print(f"DEPENDENCY_INSTALL_FAILED: {error}", file=sys.stderr)
+            return 1
+        print(json.dumps({"status": "host-dependencies", **dependency_result}, ensure_ascii=False))
+    if not args.bootstrap:
+        return 0
+    try:
+        ensure_bootstrap_token_secret(root)
+    except RuntimeError as error:
+        print(f"BOOTSTRAP_FAILED: {error}", file=sys.stderr)
+        return 1
+    schema_script = root / "scripts" / "maggie-booking-schema.mjs"
+    if not schema_script.is_file():
+        print(f"BOOTSTRAP_FAILED: installed host schema script is missing: {schema_script}", file=sys.stderr)
+        return 1
+    schema = subprocess.run(["node", str(schema_script), "--apply", "--confirm"], cwd=root, check=False)
+    return schema.returncode
+
+
+def command_inspect(args: argparse.Namespace) -> int:
+    root = project_path(args)
+    installed = root / "_maggie" / "booking"
+    installed_entry = installed / "booking.tsx"
+    state = root / ".maggie" / "dash-install.json"
+    state_data = load_json(state) if state.is_file() else {}
+    middleware = root / "src" / "middleware.ts"
+    middleware_text = middleware.read_text(encoding="utf-8") if middleware.is_file() else ""
+    middleware_integration = (
+        state_data.get("hostFramework") != "astro"
+        or (
+            middleware.is_file()
+            and (
+                "maggie-auto-rewrite-v1" in middleware_text
+                or middleware_has_booking_rewrites(middleware_text)
+            )
+        )
+    )
+    contract = root / "maggiedash" / "contracts" / "booking-host-adapter-v1.json"
+    access_contract = root / "maggiedash" / "contracts" / "booking-access-v1.json"
+    email_templates_contract = root / "maggiedash" / "contracts" / "booking-email-templates-v1.json"
+    customer_contract = root / "maggiedash" / "contracts" / "booking-customer-surface-v1.json"
+    stripe_contract = root / "maggiedash" / "contracts" / "stripe-booking-capabilities-v1.json"
+    service_types = root / "maggiedash" / "backend" / "booking-adapter-contract.d.ts"
+    service_validator = root / "maggiedash" / "scripts" / "validate-booking-service-contract.mjs"
+    manager_methods_validator = root / "maggiedash" / "scripts" / "validate-booking-postgres-manager-methods.mjs"
+    payment_adapter = root / "maggiedash" / "backend" / "booking" / "postgres-payment-adapter.mjs"
+    payment_validator = root / "maggiedash" / "scripts" / "validate-booking-postgres-payment-adapter.mjs"
+    customer_adapter = root / "maggiedash" / "backend" / "booking" / "postgres-customer-adapter.mjs"
+    customer_validator = root / "maggiedash" / "scripts" / "validate-booking-postgres-customer-adapter.mjs"
+    backup_restore_validator = root / "maggiedash" / "scripts" / "validate-booking-postgres-backup-restore.integration.mjs"
+    core_repository = root / "maggiedash" / "backend" / "booking" / "postgres-core-repository.mjs"
+    if not contract.exists(): contract = Path(args.contract).expanduser().resolve()
+    checks = {
+        "project": str(root),
+        "bookingWorkspace": installed.is_dir(),
+        "bookingEntry": installed_entry.is_file(),
+        "installState": state.is_file(),
+        "middlewareIntegration": middleware_integration,
+        "hostContract": contract.is_file(),
+        "accessContract": access_contract.is_file(),
+        "emailTemplatesContract": email_templates_contract.is_file(),
+        "serviceAdapterTypes": service_types.is_file(),
+        "serviceContractValidator": service_validator.is_file(),
+        "postgresManagerMethodsValidator": manager_methods_validator.is_file(),
+        "postgresPaymentAdapter": payment_adapter.is_file(),
+        "postgresPaymentValidator": payment_validator.is_file(),
+        "postgresCustomerAdapter": customer_adapter.is_file(),
+        "postgresCustomerValidator": customer_validator.is_file(),
+        "postgresBackupRestoreValidator": backup_restore_validator.is_file(),
+        "postgresCoreRepository": core_repository.is_file(),
+        "customerSurfaceContract": customer_contract.is_file(),
+        "stripeContract": stripe_contract.is_file(),
+        "schema": (root / "maggiedash" / "schema" / "maggie-booking-install.sql").is_file(),
+        "runtimeContract": (root / "maggiedash" / "contracts" / "booking-runtime-v1.json").is_file(),
+        "browserEvidenceContract": (root / "maggiedash" / "contracts" / "booking-browser-evidence-v1.json").is_file(),
+        "runtimePlanValidator": (root / "maggiedash" / "scripts" / "validate-booking-runtime-plan.mjs").is_file(),
+        "customerFlowValidator": (root / "maggiedash" / "scripts" / "validate-booking-customer-flow.mjs").is_file(),
+        "customerUIValidator": (root / "maggiedash" / "scripts" / "validate-booking-customer-ui.mjs").is_file(),
+        "customerReferenceHostValidator": (root / "maggiedash" / "scripts" / "validate-booking-customer-reference-host.mjs").is_file(),
+        "customerReferenceHost": (root / "maggiedash" / "backend" / "booking" / "customer-reference-host.mjs").is_file(),
+        "customerPageTemplate": (root / "maggiedash" / "adapters" / "astro" / "customer-booking-page.astro").is_file(),
+        "worker": (root / "maggiedash" / "backend" / "booking" / "run-booking-jobs.mjs").is_file(),
+        "opsTemplates": (root / "maggiedash" / "ops").is_dir(),
+        "runtimeWorkflow": (root / ".github" / "workflows" / "booking-runtime.yml").is_file(),
+        "browserWorkflow": (root / ".github" / "workflows" / "booking-browser-evidence.yml").is_file(),
+        "opsEvidenceWorkflow": (root / ".github" / "workflows" / "booking-ops-evidence.yml").is_file(),
+    }
+    errors = [name for name, passed in checks.items() if name != "project" and not passed]
+    errors.extend(f"host:{warning}" for warning in state_data.get("hostWarnings", []) if warning)
+    if contract.is_file(): errors.extend(f"contract:{item}" for item in contract_checks(load_json(contract)))
+    if access_contract.is_file(): errors.extend(f"accessContract:{item}" for item in access_contract_checks(load_json(access_contract)))
+    if email_templates_contract.is_file(): errors.extend(f"emailTemplatesContract:{item}" for item in email_templates_contract_checks(load_json(email_templates_contract)))
+    if customer_contract.is_file(): errors.extend(f"customerContract:{item}" for item in customer_contract_checks(load_json(customer_contract)))
+    if stripe_contract.is_file(): errors.extend(f"stripe:{item}" for item in stripe_contract_checks(load_json(stripe_contract)))
+    result = {"status": "passed" if not errors else "needs-attention", "checks": checks, "errors": errors, "next": ["maggie dash install --project . --confirm", "maggie booking runtime-validate --project . --evidence .maggie/booking-runtime.json"] if errors else ["maggie booking release-gate --project ."]}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def runtime_result(evidence: dict, contract: dict) -> dict:
+    observations = evidence.get("endpoints") if isinstance(evidence.get("endpoints"), list) else evidence.get("observations")
+    if not isinstance(observations, list): observations = []
+    if isinstance(contract.get("properties"), dict):
+        required = {str(item.get("id")) for item in contract.get("x-endpoints", []) if isinstance(item, dict) and item.get("id")}
+        endpoint_map = {str(item.get("id")): item for item in contract.get("x-endpoints", []) if isinstance(item, dict) and item.get("id")}
+        api_prefix = ((contract.get("properties") or {}).get("apiPrefix") or {}).get("const", "/api/maggie/booking")
+    else:
+        required = {str(value) for value in contract.get("endpointIds", [])}
+        endpoint_map = {}
+        api_prefix = contract.get("apiPrefix", "/api/maggie/booking")
+    seen = {str(item.get("id")) for item in observations if isinstance(item, dict)}
+    errors: list[str] = []
+    if evidence.get("schemaVersion") != "maggiedash-booking-runtime.v1": errors.append("runtime schemaVersion is unsupported")
+    if not str(evidence.get("baseUrl", "")).startswith("https://"): errors.append("runtime baseUrl must use HTTPS")
+    generated_at = evidence.get("generatedAt")
+    try:
+        datetime.fromisoformat(str(generated_at).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        errors.append("runtime generatedAt must be an ISO timestamp")
+    if not isinstance(evidence.get("tenant"), str) or not evidence.get("tenant"): errors.append("runtime tenant must identify the dedicated test tenant")
+    if len(observations) != len(required): errors.append(f"expected {len(required)} endpoint observations, got {len(observations)}")
+    if len(seen) != len([item for item in observations if isinstance(item, dict)]): errors.append("endpoint observations must be unique")
+    for item in observations:
+        if not isinstance(item, dict): errors.append("observation must be an object"); continue
+        item_id = str(item.get("id", "unknown"))
+        if item_id not in required: errors.append(f"unknown endpoint observation: {item_id}")
+        for field in ("id", "method", "route", "status", "requiredFieldsPresent"):
+            if field not in item: errors.append(f"{item_id}: missing {field}")
+        expected = endpoint_map.get(item_id)
+        if expected:
+            expected_route = f"{api_prefix}{expected.get('route', '')}"
+            if item.get("method") != expected.get("method"): errors.append(f"{item_id}: method differs from contract")
+            if item.get("route") != expected_route: errors.append(f"{item_id}: route differs from contract")
+        if item.get("status") not in range(200, 300): errors.append(f"{item_id}: status is not 2xx")
+        if item.get("requiredFieldsPresent") is not True: errors.append(f"{item_id}: required fields are incomplete")
+        for key in item:
+            if re.search(r"body|payload|cookie|token|secret|signature|authorization|email|phone", str(key), re.IGNORECASE): errors.append(f"{item_id}: sensitive evidence field is present: {key}")
+    missing = sorted(required - seen)
+    errors.extend(f"missing endpoint observation: {item}" for item in missing)
+    return {"status": "passed" if not errors and bool(observations) else "failed", "checked": len(observations), "required": len(required), "missing": missing, "errors": errors}
+
+
+def browser_result(evidence: dict, artifact_root: Path) -> dict:
+    """Validate sanitized browser evidence without importing a browser runtime."""
+    errors: list[str] = []
+    if evidence.get("schemaVersion") != "maggiedash-booking-browser-evidence.v1": errors.append("browser schemaVersion is unsupported")
+    if not str(evidence.get("baseUrl", "")).startswith("https://"): errors.append("browser baseUrl must use HTTPS")
+    generated_at = evidence.get("generatedAt")
+    try:
+        datetime.fromisoformat(str(generated_at).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        errors.append("browser generatedAt must be an ISO timestamp")
+    viewport_map = {("mobile", 390, 844), ("tablet", 768, 1024), ("desktop", 1440, 1000)}
+    actual_viewports = evidence.get("viewports") if isinstance(evidence.get("viewports"), list) else []
+    observed_viewports = {(item.get("name"), item.get("width"), item.get("height")) for item in actual_viewports if isinstance(item, dict)}
+    for viewport in sorted(viewport_map - observed_viewports):
+        errors.append(f"missing viewport {viewport[0]} {viewport[1]}x{viewport[2]}")
+    routes = ["/_maggie/booking/", "/_maggie/booking/calendar", "/_maggie/booking/bookings", "/_maggie/booking/customers", "/_maggie/booking/waitlist", "/_maggie/booking/locations", "/_maggie/booking/catalog", "/_maggie/booking/staff", "/_maggie/booking/resources", "/_maggie/booking/schedule", "/_maggie/booking/payments", "/_maggie/booking/notifications", "/_maggie/booking/reports", "/_maggie/booking/settings", "/_maggie/booking/audit"]
+    screens = evidence.get("screens") if isinstance(evidence.get("screens"), list) else []
+    for route in routes:
+        for viewport in ("mobile", "tablet", "desktop"):
+            item = next((row for row in screens if isinstance(row, dict) and row.get("route") == route and row.get("viewport") == viewport), None)
+            if not item: errors.append(f"missing browser screen {viewport}:{route}"); continue
+            if not isinstance(item.get("httpStatus"), int) or not 200 <= item["httpStatus"] < 400: errors.append(f"browser screen is not successful {viewport}:{route}")
+            if item.get("ready") is not True: errors.append(f"browser screen is not ready {viewport}:{route}")
+            screenshot = item.get("screenshot")
+            if not isinstance(screenshot, str) or Path(screenshot).is_absolute() or ".." in Path(screenshot).parts: errors.append(f"unsafe browser screenshot path {viewport}:{route}")
+            elif not (artifact_root / screenshot).is_file(): errors.append(f"missing browser screenshot {screenshot}")
+    if evidence.get("consoleErrors") != []: errors.append("browser consoleErrors is not empty")
+    if evidence.get("failedRequests") != []: errors.append("browser failedRequests is not empty")
+    if evidence.get("layoutErrors") != []: errors.append("browser layoutErrors is not empty")
+    return {"status": "passed" if not errors else "failed", "screens": len(screens), "required": len(routes) * 3, "errors": errors}
+
+
+def command_runtime_validate(args: argparse.Namespace) -> int:
+    evidence = load_json(Path(args.evidence).expanduser().resolve())
+    contract = load_json(Path(args.contract).expanduser().resolve())
+    result = runtime_result(evidence, contract)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["status"] == "passed" else 1
+
+
+def ops_evidence_result(evidence: dict, contract: dict, require_host: bool = False) -> dict:
+    errors: list[str] = []
+    if evidence.get("schemaVersion") != contract.get("schemaVersion"): errors.append("ops evidence schemaVersion is unsupported")
+    if not evidence.get("generatedAt") or not isinstance(evidence.get("environment"), str) or not isinstance(evidence.get("tenant"), str): errors.append("generatedAt, environment, and tenant are required")
+    try:
+        datetime.fromisoformat(str(evidence.get("generatedAt")).replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        errors.append("ops generatedAt must be an ISO timestamp")
+    if require_host and evidence.get("environment") in {"fixture", "test", "local"}: errors.append("host evidence cannot use a fixture/local environment")
+    checks = evidence.get("checks") if isinstance(evidence.get("checks"), dict) else {}
+    def check_object(name: str) -> dict:
+        value = checks.get(name)
+        return value if isinstance(value, dict) else {}
+    required_fields = contract.get("requiredCheckFields") or {
+        "backup_restore": ["status", "backupVerifiedAt", "restoreVerifiedAt", "rowCountVerified"],
+        "alert_routing": ["status", "alertCodes", "criticalDeliveryVerified"],
+        "recovery_rehearsal": ["status", "rollbackWriteGuardVerified", "workerRestartVerified", "outboxReplayVerified"],
+    }
+    for check in contract.get("requiredChecks", []):
+        check_data = check_object(check)
+        if check_data.get("status") != "passed": errors.append(f"{check} must be passed")
+        for field in required_fields.get(check, []):
+            if field not in check_data: errors.append(f"{check}.{field} is required")
+    routed = check_object("alert_routing").get("alertCodes")
+    if not isinstance(routed, list) or not set(contract.get("requiredAlertCodes", [])).issubset(set(routed)): errors.append("alert routing does not cover every stable alert code")
+    for field in ("backupVerifiedAt", "restoreVerifiedAt"):
+        try:
+            datetime.fromisoformat(str(check_object("backup_restore").get(field)).replace("Z", "+00:00"))
+        except (TypeError, ValueError):
+            errors.append(f"backup_restore.{field} must be an ISO timestamp")
+    if check_object("backup_restore").get("rowCountVerified") is not True: errors.append("backup_restore.rowCountVerified must be true")
+    if check_object("alert_routing").get("criticalDeliveryVerified") is not True: errors.append("alert_routing.criticalDeliveryVerified must be true")
+    for field in ("rollbackWriteGuardVerified", "workerRestartVerified", "outboxReplayVerified"):
+        if check_object("recovery_rehearsal").get(field) is not True: errors.append(f"recovery_rehearsal.{field} must be true")
+    safe_fields = set(contract.get("safeFields", []))
+    def walk(value: object, path: str = "") -> None:
+        if isinstance(value, dict):
+            for key, child in value.items():
+                if key not in safe_fields: errors.append(f"unsafe ops evidence field: {path + key}")
+                walk(child, f"{path}{key}.")
+        elif isinstance(value, list):
+            for index, child in enumerate(value): walk(child, f"{path}{index}.")
+    walk(evidence)
+    return {"status": "passed" if not errors else "failed", "checks": sorted(checks), "requiredAlertCodes": len(contract.get("requiredAlertCodes", [])), "errors": errors}
+
+
+def command_ops_validate(args: argparse.Namespace) -> int:
+    evidence = load_json(Path(args.evidence).expanduser().resolve())
+    contract = load_json(Path(args.contract).expanduser().resolve())
+    result = ops_evidence_result(evidence, contract, require_host=args.require_host)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["status"] == "passed" else 1
+
+
+def command_release_gate(args: argparse.Namespace) -> int:
+    root = project_path(args)
+    contract = Path(args.contract).expanduser().resolve()
+    contract_result = contract_checks(load_json(contract))
+    access_path = root / "maggiedash" / "contracts" / "booking-access-v1.json"
+    access_result = access_contract_checks(load_json(access_path)) if access_path.is_file() else ["installed Booking access contract is missing"]
+    email_templates_path = root / "maggiedash" / "contracts" / "booking-email-templates-v1.json"
+    email_templates_result = email_templates_contract_checks(load_json(email_templates_path)) if email_templates_path.is_file() else ["installed Booking email templates contract is missing"]
+    stripe_path = root / "maggiedash" / "contracts" / "stripe-booking-capabilities-v1.json"
+    stripe_errors = stripe_contract_checks(load_json(stripe_path)) if stripe_path.is_file() else ["installed Stripe capability contract is missing"]
+    checks = {"contract": not contract_result, "emailTemplatesContract": not email_templates_result, "stripeContract": not stripe_errors, "serviceAdapterTypes": (root / "maggiedash" / "backend" / "booking-adapter-contract.d.ts").is_file(), "serviceContractValidator": (root / "maggiedash" / "scripts" / "validate-booking-service-contract.mjs").is_file(), "postgresManagerMethodsValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-manager-methods.mjs").is_file(), "postgresPaymentAdapter": (root / "maggiedash" / "backend" / "booking" / "postgres-payment-adapter.mjs").is_file(), "postgresPaymentValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-payment-adapter.mjs").is_file(), "postgresCustomerAdapter": (root / "maggiedash" / "backend" / "booking" / "postgres-customer-adapter.mjs").is_file(), "postgresCustomerValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-customer-adapter.mjs").is_file(), "postgresBackupRestoreValidator": (root / "maggiedash" / "scripts" / "validate-booking-postgres-backup-restore.integration.mjs").is_file(), "postgresCoreRepository": (root / "maggiedash" / "backend" / "booking" / "postgres-core-repository.mjs").is_file(), "workspace": (root / "_maggie" / "booking" / "booking.tsx").is_file(), "schema": (root / "maggiedash" / "schema" / "maggie-booking-install.sql").is_file()}
+    errors = list(contract_result)
+    errors.extend(f"access:{item}" for item in access_result)
+    errors.extend(f"emailTemplates:{item}" for item in email_templates_result)
+    errors.extend(f"stripe:{item}" for item in stripe_errors)
+    errors.extend(name for name, passed in checks.items() if not passed)
+    runtime_status = "not-provided"
+    if args.evidence:
+        runtime_evidence, runtime_error = load_gate_json(Path(args.evidence).expanduser().resolve(), "runtime evidence could not be read")
+        if runtime_error:
+            runtime_status = "failed"
+            errors.append(runtime_error)
+        else:
+            runtime_status = runtime_result(runtime_evidence, load_json(contract)).get("status", "failed")
+            if runtime_status != "passed": errors.append("runtime evidence failed")
+    elif args.require_runtime:
+        errors.append("runtime evidence is required")
+    browser_status = "not-provided"
+    if args.browser_evidence:
+        browser_path = Path(args.browser_evidence).expanduser().resolve()
+        browser_evidence, browser_error = load_gate_json(browser_path, "browser evidence could not be read")
+        if browser_error:
+            browser_status = "failed"
+            errors.append(browser_error)
+        else:
+            browser_status = browser_result(browser_evidence, browser_path.parent).get("status", "failed")
+            if browser_status != "passed": errors.append("browser evidence failed")
+    elif args.require_browser:
+        errors.append("browser evidence is required")
+    ops_status = "not-provided"
+    if args.ops_evidence:
+        ops_path = Path(args.ops_evidence).expanduser().resolve()
+        ops_contract_path = Path(args.ops_contract).expanduser().resolve()
+        ops_evidence, ops_error = load_gate_json(ops_path, "ops evidence could not be read")
+        ops_contract, ops_contract_error = load_gate_json(ops_contract_path, "ops evidence contract could not be read")
+        if ops_error or ops_contract_error:
+            ops_status = "failed"
+            if ops_error: errors.append(ops_error)
+            if ops_contract_error: errors.append(ops_contract_error)
+        else:
+            ops_status = ops_evidence_result(ops_evidence, ops_contract, require_host=args.require_ops).get("status", "failed")
+            if ops_status != "passed": errors.append("ops evidence failed")
+    elif args.require_ops:
+        errors.append("ops evidence is required")
+    board_status = "not-provided"
+    board_report = None
+    if args.board or args.require_board:
+        board_path = Path(args.board).expanduser().resolve() if args.board else EXECUTION_BOARD
+        board_report = board_result(load_execution_board(board_path))
+        board_report["board"] = str(board_path)
+        board_status = board_report["status"]
+        if board_status != "passed": errors.append("execution board is not complete")
+    result = {"status": "passed" if not errors else "blocked", "project": str(root), "checks": {**checks, "accessContract": not access_result}, "runtime": runtime_status, "browser": browser_status, "ops": ops_status, "board": board_report, "errors": errors, "note": "This gate does not run migrations, create bookings, capture payments, or deploy."}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def command_stripe_audit(args: argparse.Namespace) -> int:
+    root = project_path(args)
+    candidate = Path(args.contract).expanduser().resolve() if args.contract else root / "maggiedash" / "contracts" / "stripe-booking-capabilities-v1.json"
+    if not candidate.is_file() and DEFAULT_STRIPE_CONTRACT.is_file(): candidate = DEFAULT_STRIPE_CONTRACT
+    contract = load_json(candidate)
+    errors = stripe_contract_checks(contract, max_age_days=args.max_age_days)
+    result = {"status": "passed" if not errors else "failed", "contract": str(candidate), "lastVerifiedAt": contract.get("x-last-verified-at") or contract.get("lastVerifiedAt"), "apiCount": len(contract.get("x-api-matrix") or contract.get("apis") or []), "webhookEventCount": len(contract.get("x-webhook-events") or contract.get("webhookEvents") or []), "nativeCapabilities": contract.get("x-native-capabilities") or contract.get("nativeCapabilities") or {}, "errors": errors}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="maggie booking", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    install = sub.add_parser("install", help="install Booking and the framework host scaffold")
+    install.add_argument("--project", default=".")
+    install.add_argument("--source", help="local MaggieDash checkout or Git URL")
+    install.add_argument("--ref", default="main")
+    install.add_argument("--host", choices=["auto", "astro", "none"], default="auto")
+    install.add_argument("--force", action="store_true")
+    install.add_argument("--dry-run", action="store_true")
+    install.add_argument("--diff", action="store_true")
+    install.add_argument("--existing-dir")
+    install.add_argument("--install-dependencies", action="store_true", help="add missing Astro Booking packages with the host package manager")
+    install.add_argument("--bootstrap", action="store_true", help="apply the installed host Booking schema after installation")
+    install.add_argument("--confirm", action="store_true")
+    install.set_defaults(func=command_install)
+    contract = sub.add_parser("contract", help="validate the provider-neutral Booking contract")
+    contract.add_argument("--contract", default=str(DEFAULT_CONTRACT))
+    contract.set_defaults(func=command_contract)
+    access_contract = sub.add_parser("access-contract", help="validate the Booking administrator access contract")
+    access_contract.add_argument("--contract", default=str(DEFAULT_ACCESS_CONTRACT))
+    access_contract.set_defaults(func=command_access_contract)
+    email_templates_contract = sub.add_parser("email-templates-contract", help="validate the tenant-scoped Booking email template contract")
+    email_templates_contract.add_argument("--contract", default=str(DEFAULT_EMAIL_TEMPLATES_CONTRACT))
+    email_templates_contract.set_defaults(func=command_email_templates_contract)
+    inspect = sub.add_parser("inspect", help="inspect Booking install artifacts and contracts")
+    inspect.add_argument("--project", default=".")
+    inspect.add_argument("--contract", default=str(DEFAULT_CONTRACT))
+    inspect.set_defaults(func=command_inspect)
+    setup = sub.add_parser("setup", help="show the safe first-run Booking setup checklist")
+    setup.add_argument("--project", default=".")
+    setup.set_defaults(func=command_setup)
+    runtime = sub.add_parser("runtime-validate", help="validate sanitized host endpoint evidence")
+    runtime.add_argument("--project", default=".")
+    runtime.add_argument("--contract", default=str(DEFAULT_CONTRACT))
+    runtime.add_argument("--evidence", required=True)
+    runtime.set_defaults(func=command_runtime_validate)
+    ops = sub.add_parser("ops-validate", help="validate sanitized host backup, alert, and recovery evidence")
+    ops.add_argument("--project", default=".")
+    ops.add_argument("--contract", default=str(DEFAULT_OPS_EVIDENCE_CONTRACT))
+    ops.add_argument("--evidence", required=True)
+    ops.add_argument("--require-host", action="store_true", help="reject fixture/local evidence")
+    ops.set_defaults(func=command_ops_validate)
+    gate = sub.add_parser("release-gate", help="run the read-only Booking release gate")
+    gate.add_argument("--project", default=".")
+    gate.add_argument("--contract", default=str(DEFAULT_CONTRACT))
+    gate.add_argument("--evidence")
+    gate.add_argument("--require-runtime", action="store_true")
+    gate.add_argument("--browser-evidence")
+    gate.add_argument("--require-browser", action="store_true")
+    gate.add_argument("--ops-evidence", help="sanitized backup, alert, and recovery evidence JSON")
+    gate.add_argument("--ops-contract", default=str(DEFAULT_OPS_EVIDENCE_CONTRACT))
+    gate.add_argument("--require-ops", action="store_true", help="fail unless host operational evidence is provided and valid")
+    gate.add_argument("--board", help="execution board JSON to inspect")
+    gate.add_argument("--require-board", action="store_true", help="fail unless every execution-board task is passed")
+    gate.set_defaults(func=command_release_gate)
+    stripe = sub.add_parser("stripe-audit", help="validate the current Stripe booking capability matrix")
+    stripe.add_argument("--project", default=".")
+    stripe.add_argument("--contract")
+    stripe.add_argument("--max-age-days", type=int, default=120)
+    stripe.set_defaults(func=command_stripe_audit)
+    tasks = sub.add_parser("tasks", help="inspect the executable Booking delivery board")
+    tasks_sub = tasks.add_subparsers(dest="task_command", required=True)
+    tasks_validate = tasks_sub.add_parser("validate", help="validate task dependencies and required fields")
+    tasks_validate.add_argument("--board")
+    tasks_validate.set_defaults(func=command_tasks)
+    tasks_list = tasks_sub.add_parser("list", help="list Booking delivery tasks")
+    tasks_list.add_argument("--status", choices=["planned", "in_progress", "needs-evidence", "blocked", "passed"])
+    tasks_list.add_argument("--board")
+    tasks_list.set_defaults(func=command_tasks)
+    tasks_show = tasks_sub.add_parser("show", help="show one Booking delivery task")
+    tasks_show.add_argument("task_id")
+    tasks_show.add_argument("--board")
+    tasks_show.set_defaults(func=command_tasks)
+    return parser
+
+
+if __name__ == "__main__":
+    try:
+        arguments = parser().parse_args()
+        raise SystemExit(arguments.func(arguments))
+    except RuntimeError as error:
+        print(f"BOOKING_CHECK_FAILED: {error}", file=sys.stderr)
+        raise SystemExit(1)