@topy-ai/maggie 0.7.17 → 0.7.19

package/README.md

@@ -76,6 +76,24 @@ maggie qa summary --project . --run <run-id>
 The QA workflow stores secret-free run state under `.maggie/qa-runs/` and
 keeps project-specific scenarios and evidence outside the npm package.
 
+Dashboard and documentation audits are provider-neutral and keep host data
+behind explicit evidence files:
+
+```bash
+maggie dash api-contract --spec .maggie/openapi.json
+maggie dash api-contract --spec https://example.test/openapi.json
+maggie dash schema-audit --inventory .maggie/schema-inventory.json --fail-on-unread
+maggie dash ui runtime-validate --evidence .maggie/dashboard-runtime.json
+maggie docs audit --project . --docs-dir docs --output docs/documentation-audit.json
+```
+
+The API checker accepts a local JSON file or a public HTTPS URL and validates
+the response in memory. Schema audits use host-provided table, row-count, and
+reader evidence; they never guess from a production database. Runtime
+evidence proves that a dashboard screen mounted and executed its checks, so a
+static component scan cannot pass by itself. MaggieDash hosts may also expose
+the provider-neutral activity-log and managed-navigation contracts.
+
 The current package also includes reusable safeguards from the latest feedback
 review: `maggie dash api-contract` checks declared request and 2xx response
 shapes; `maggie blog check-gate`/`approve` enforces review before publish;
@@ -88,6 +106,23 @@ hours. `maggie seo social-cards` checks per-page OG image dimensions and format;
 Dash inventory separates renderer kind from public page kind while reporting
 source coverage for code-rendered routes.
 
+Service booking providers can be checked with a machine-readable,
+fixture-backed capability matrix:
+
+```bash
+maggie service capability-audit --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
+```
+
+The declaration records variant mode (`native`, `derived-offers`,
+`single-fallback`, or `blocked`), price semantics, and stable-ID confidence.
+The audit also records observed counts and fixture evidence. Localized service
+variants use market/locale-aware canonical routes and reciprocal hreflang.
+Release preflight consumes the latest matching scenario QA run when one is
+configured and blocks incomplete evidence.
+
 For Google integrations, validate a redacted provider matrix before reporting
 access. The command fails closed on unknown scopes, missing Ads prerequisites,
 duplicate provider resources, and unverified edit/publish claims:
@@ -134,7 +169,10 @@ maggie dash transition ...      # explicit content approval transition
 maggie dash variant ...         # service variant create/review/preview/publish
 maggie dash sections ...        # field fan-out, locale, binding, media, copy, identity keys
 maggie dash inventory ...        # disjoint renderer/page-kind inventory + coverage
-maggie dash api-contract ...     # declared API body and 2xx response contract
+maggie dash api-contract ...     # local/live declared API body and 2xx contract
+maggie dash schema-audit ...     # host schema reader-evidence audit
+maggie dash ui runtime-validate ... # mounted dashboard runtime evidence
+maggie docs audit ...            # documentation hygiene audit
 maggie agent-content write ...  # host-authorized, origin-bound content bridge
 maggie verification coverage ... # changed surface/locale evidence gate
 maggie clone ...                 # authorized homepage capture
@@ -145,7 +183,7 @@ maggie memory ...                # confirmed preferences and lessons
 maggie feedback ...              # redact, preview, submit, list
 maggie qa ...                    # scenario browser QA, fix/retest, release gate
 maggie localization ...          # plan, validate, review, publish, stale
-maggie service ...               # import, sync, generate, validate
+maggie service ...               # import, sync, capability audit, validate
 maggie seo performance ...       # sampled PageSpeed/CWV report and baseline
 maggie seo images ...             # inventory, variants, confirmation, validate
 maggie seo sitemap ...            # typed/semantic plan, agent-files, apply, rollback
@@ -267,8 +305,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.17 update --project . --force
-npx @topy-ai/maggie@0.7.17 cleanup --project .
+npx @topy-ai/maggie@0.7.19 update --project . --force
+npx @topy-ai/maggie@0.7.19 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -278,7 +316,13 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.17 workflow adds sanitized database-backed blog gate adapters, deployed
+The 0.7.19 workflow adds documentation hygiene audits, live URL API contract
+validation, host-supplied schema reader audits, dashboard runtime evidence,
+and provider-neutral activity-log and managed-navigation contracts. The 0.7.18
+workflow adds staged/untracked changed-surface detection, scenario
+QA release integration, market/locale-aware service variant routes and
+reciprocal hreflang, provider capability matrices with fixture evidence, and
+feedback fixed-proof/path-privacy gates. The 0.7.17 workflow adds sanitized database-backed blog gate adapters, deployed
 IndexNow key verification, social-card and cross-shell head-tag audits, required
 Open Graph image coverage, and behavioural favicon verification. The 0.7.16
 workflow tightens the review-gate exit code and adds retry-path regression

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.16 init --agent all
+npx @topy-ai/maggie@0.7.19 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,7 +25,11 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-0.7.16 補強 review gate 的 CI exit code 與 IndexNow retry regression；
+0.7.19 加入文件 hygiene audit、live URL API contract、schema reader audit、
+dashboard runtime evidence，以及 activity-log 和 managed-navigation contracts。
+0.7.18 加入 staged/untracked changed-surface release gate、QA run 與 release
+整合、market/locale-aware service variant route、provider capability matrix
+fixture evidence，以及 feedback fixed-proof/path privacy gate。0.7.16 補強 review gate 的 CI exit code 與 IndexNow retry regression；
 0.7.15 也加入 API schema contract、blog review gate、sitemap freshness
 warning、change-driven IndexNow 與 page-kind/source-coverage inventory。
 
@@ -59,6 +63,12 @@ maggie migration identity --identity-file .maggie/db-identity.json \
 maggie qa start --project . --scenario-file .maggie/scenario-manifest.json \
   --environment local --base-url http://localhost:4321
 maggie qa summary --project . --run <run-id>
+
+# Provider variant capability matrix
+maggie service capability-audit --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
 ```
 
 完整中文說明、19 個 skills 清單和 roadmap：

package/bin/maggie.js

@@ -61,6 +61,9 @@ Usage:
   maggie dash sections <validate|prompt|keys|remap-translations|fanout-validate|locale-validate|variant-copy-validate|media-validate|bindings-validate|idempotency-validate|reconcile> [options]
   maggie dash inventory --pages-file FILE [--require-page-kinds] [--require-source-coverage]
   maggie dash api-contract --spec FILE
+  maggie dash api-contract --spec https://example.test/openapi.json
+  maggie dash schema-audit --inventory FILE [--fail-on-unread]
+  maggie dash ui runtime-validate --evidence FILE
   maggie dash components-audit --bindings-file FILE --sections-file FILE --pages-file FILE
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
@@ -98,6 +101,7 @@ Usage:
   maggie service import <provider-url> --project PATH
   maggie service sync <provider-url> --project PATH
   maggie service generate --project PATH
+  maggie service capability-audit --project PATH --catalogue FILE --capabilities-file FILE --fixture FILE
   maggie service validate --project PATH
   maggie service inspect --project PATH
   maggie service status --project PATH
@@ -300,6 +304,11 @@ function service(args) {
   process.exitCode = result.status ?? 1;
 }
 
+function docs(args) {
+  if (args[0] && args[0] !== "audit") throw new Error("docs command must be audit");
+  workflowCli("maggie_docs.py", args);
+}
+
 function seo(args) {
   const command = args[0];
   const scripts = { performance: "maggie_performance.py", images: "maggie_images.py", sitemap: "maggie_sitemap.py", indexnow: "maggie_indexnow.py", "social-cards": "maggie_social_cards.py", "head-tags": "maggie_head_tags.py" };
@@ -395,6 +404,7 @@ try {
   else if (command === "auth") workflowCli("maggie_auth.py", args);
   else if (command === "blog") workflowCli("maggie_blog.py", args);
   else if (command === "service") service(args);
+  else if (command === "docs") docs(args);
   else if (command === "seo") seo(args);
   else if (command === "ops") workflowCli("maggie_ops.py", args);
   else if (command === "deployment" && args[0] === "canary") workflowCli("maggie_deployment_canary.py", args.slice(1));

package/bundled-contracts/maggiedash/README.md

@@ -42,6 +42,25 @@ but they may not change the required identity, status, provenance, or approval
 fields. Unknown fields must be preserved or reported as unsupported during
 import.
 
+## Operational UI contracts
+
+- [`activity-log-v1.json`](activity-log-v1.json) defines append-only activity
+  events, actor/action taxonomy, and the metadata boundary;
+- [`navigation-v1.json`](navigation-v1.json) defines locale-aware managed menu
+  items with stable ordering, nesting, and safe destinations;
+- [`dashboard-runtime-v1.json`](dashboard-runtime-v1.json) defines evidence
+  that an admin screen mounted, ran its checks, and completed its data calls.
+
+These are adapter-facing interfaces, not database schemas. A host may use
+PostgreSQL, SQLite, or another first-party store. Activity recording happens
+after a successful caller write, uses the same transaction/client where
+available, redacts credential-like metadata, and must never make the business
+operation fail. Retention/pruning is explicit. Navigation reads fall back to
+site markup when no published menu exists or the adapter is unavailable.
+Dashboard browser checks must emit runtime evidence; a static component scan
+or JSON declaration is not proof that a screen mounted or that its data calls
+ran.
+
 ## Status model
 
 Content transitions are explicit:

package/bundled-contracts/maggiedash/activity-log-v1.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/activity-log-v1.json",
+  "title": "MaggieDash first-party activity log contract v1",
+  "type": "object",
+  "required": ["schemaVersion", "events"],
+  "properties": {
+    "schemaVersion": {"const": "maggiedash-activity-log.v1"},
+    "events": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "occurredAt", "actor", "action"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "occurredAt": {"type": "string", "format": "date-time"},
+          "actor": {"type": "string", "minLength": 1},
+          "action": {"type": "string", "pattern": "^[a-z_]+\\.[a-z_]+$"},
+          "summary": {"type": "string"},
+          "metadata": {"type": "object", "additionalProperties": true}
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/dashboard-runtime-v1.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/dashboard-runtime-v1.json",
+  "title": "MaggieDash dashboard runtime evidence contract v1",
+  "type": "object",
+  "required": ["schemaVersion", "screen", "route", "mounted", "checks"],
+  "properties": {
+    "schemaVersion": {"const": "maggiedash-dashboard-runtime.v1"},
+    "screen": {"type": "string", "minLength": 1},
+    "route": {"type": "string", "minLength": 1},
+    "mounted": {"const": true},
+    "checks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["name", "passed"],
+        "properties": {"name": {"type": "string", "minLength": 1}, "passed": {"type": "boolean"}},
+        "additionalProperties": false
+      }
+    },
+    "dataCalls": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["url", "ok"],
+        "properties": {"url": {"type": "string"}, "method": {"type": "string"}, "status": {"type": "integer"}, "ok": {"type": "boolean"}},
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/navigation-v1.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/navigation-v1.json",
+  "title": "MaggieDash managed navigation contract v1",
+  "type": "object",
+  "required": ["schemaVersion", "location", "locale", "items"],
+  "properties": {
+    "schemaVersion": {"const": "maggiedash-navigation.v1"},
+    "location": {"type": "string", "minLength": 1},
+    "locale": {"type": "string", "minLength": 2},
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "destination", "order"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "label": {"type": "string", "minLength": 1},
+          "destination": {"type": "string", "minLength": 1},
+          "order": {"type": "integer", "minimum": 0},
+          "parentId": {"type": ["string", "null"]},
+          "newTab": {"type": "boolean"}
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/bundled-references/universal-booking-adapter.md

@@ -25,8 +25,10 @@ when a title changes.
     "title": "Signature Scalp Ritual",
     "description": "Provider-supplied factual description.",
     "category": {"level1": "Head Spa", "level2": "Scalp Treatments"},
-    "variants": [{
+  "variants": [{
       "id": "service-123:60",
+      "idSource": "provider",
+      "variantSource": "native",
       "title": "60 minutes",
       "durationMinutes": 60,
       "price": {"amountMinor": 9500, "currency": "GBP", "display": "£95.00"}
@@ -147,3 +149,36 @@ Provider adapters may add `raw` evidence in a private local snapshot, but
 public page generation consumes only the canonical fields above. A sync must
 preserve removed records as `archived` with `removedAt` and must output a
 change report.
+
+## Provider variant capability matrix
+
+Before service pages are published, each provider declares its variant
+behavior in a project-owned JSON file. The declaration is validated against a
+sanitized fixture and emits `maggie-provider-variant-capabilities.v1`:
+
+```json
+{
+  "schemaVersion": "maggie-provider-capabilities.v1",
+  "providers": [{
+    "provider": "fresha",
+    "variantMode": "native",
+    "priceSemantics": "minor-unit-and-display",
+    "stableIdConfidence": "high"
+  }]
+}
+```
+
+`variantMode` is one of `native`, `derived-offers`, `single-fallback`, or
+`blocked`. `priceSemantics` records whether structured minor units and display
+prices are available. `stableIdConfidence` must be justified by provider or
+derived ID evidence. The audit records service/variant counts, observed source
+types, fixture name and hash, and validation errors without copying fixture
+rows or provider credentials. Run it with:
+
+```bash
+maggie service capability-audit \
+  --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
+```

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

@@ -200,8 +200,21 @@ maggie dash sections bindings-validate --sections-file .maggie/sections.json \
   --references-file .maggie/reference-inventory.json
 maggie dash sections idempotency-validate --contract-file .maggie/reconcile-contract.json
 
-# Validate API body/response shapes before a client writes against an endpoint:
+# Validate API body/response shapes before a client writes against an endpoint.
+# The source can be a local JSON file or a public HTTPS URL:
 maggie dash api-contract --spec .maggie/openapi.json
+maggie dash api-contract --spec https://example.test/openapi.json
+
+# Find declared tables with no reader evidence; this never connects to a DB:
+maggie dash schema-audit --inventory .maggie/schema-inventory.json \
+  --fail-on-unread
+
+# Prove a browser check mounted the screen and executed its data calls:
+maggie dash ui runtime-validate --evidence .maggie/dashboard-runtime.json
+
+# Classify docs, show inbound references and completed progress trackers:
+maggie docs audit --project . --docs-dir docs \
+  --output docs/documentation-audit.json
 
 # Classify every published page exactly once. `pageKind` describes the public
 # page family; `kind`/`rendererKind` describes how it is rendered. Keep these
@@ -219,6 +232,14 @@ ordinary, and blog routes, plus `sourceCoverage`. A host adapter must include
 code-rendered routes in the input or declare coverage incomplete; a zero
 database-row count is not evidence that no public routes exist.
 
+The host can expose the optional `activity-log-v1` and `navigation-v1`
+contracts through `/api/maggie/*` adapters. Activity events should be
+append-only and non-blocking to the original write. Managed navigation should
+be locale-aware, ordered, and safe to fall back to existing markup. Do not
+claim a dashboard feature is tested from a static source scan alone: record a
+`dashboard-runtime-v1` report with `mounted: true`, named checks, and the
+actual data calls.
+
 When a host renders multiple shells, export a normalized head manifest and run
 `maggie seo head-tags audit`. This is the reusable boundary for detecting icon
 MIME drift, OG-image fallback drift, and verification-tag coverage; MaggieDash

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

@@ -32,7 +32,8 @@ response bodies in it.
 
 When a release changes a visitor-facing HTML, CSS, component, or asset surface,
 the release preflight automatically requires both a passing icon inventory and
-rendered canary evidence. The canary must include screenshots, zero console or
+rendered canary evidence. It considers unstaged, staged, and untracked
+visitor-facing files. The canary must include screenshots, zero console or
 network errors, and zero placeholder matches. Query-driven routes belong in
 behavior/API checks, not static byte baselines.
 
@@ -161,6 +162,13 @@ python3 tools/clis/maggie_release.py /path/to/project \
   --base-url https://staging.example.com
 ```
 
+If `.maggie/scenario-manifest.json` or `.maggie/qa-runs/` exists, the same
+preflight consumes the latest matching `maggie qa` run for the requested
+environment (and `--base-url`, when supplied). It blocks when a scenario is
+not passed, has no browser-adapter evidence, or the matching run is missing.
+Projects without scenario QA report `not-configured`; Maggie does not run the
+browser itself.
+
 This aggregates deployment, migration, provider-health, schedule, analytics,
 service-fact, editorial approval, durable SEO/route/category evidence,
 MaggieDash schema compatibility, and live runtime security-header checks. It writes

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

@@ -34,6 +34,11 @@ The draft is written to `.maggie/feedback/`. It contains the Maggie version,
 skill, run ID, phase, error fingerprint, expected/actual result, reproduction
 steps, resolution, validation, and metadata-only screenshot references.
 
+If a draft is marked fixed with `--fixed` (or the supplied run report says
+`fixed`), both `--resolution` and `--validation` are required. Feedback text
+also scrubs common POSIX/home/temp and Windows absolute paths by default while
+preserving public URLs and route paths.
+
 ## Submit explicitly
 
 The CLI never submits automatically. After reviewing the draft:

package/bundled-skills/maggie-qa-workflow/SKILL.md

@@ -69,6 +69,11 @@ maggie qa record --project . --run local-qa-001 \
 the test failed, a fix. After a fix, retest the original scenario and at least
 one adjacent scenario affected by the same surface.
 
+A passing `test` or `retest` requires at least one `--evidence` reference from
+the host browser adapter. The adapter owns console, network, authentication,
+URL, viewport, and screenshot capture; this skill stores only a relative path,
+URL reference, and hash when a local file exists.
+
 ## Gate and release evidence
 
 The run gate is `fail` when any scenario fails, `blocked` when there is no
@@ -88,6 +93,12 @@ Before calling a release Pass, also run the relevant build, accessibility,
 SEO, media, API, and deployment-canary checks. A green build, HTTP 200, source
 class, or one guest smoke is not browser QA evidence.
 
+`maggie release` consumes the latest matching run from `.maggie/qa-runs/` when
+the project has a scenario manifest or QA run directory. A matching run must
+have a passed summary, passing scenarios, a passing final test/retest event,
+and browser evidence for every scenario. No manifest or run reports an
+explicit `not-configured` state.
+
 ## Privacy and feedback
 
 Do not put passwords, tokens, cookies, full private URLs, personal data,

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

@@ -21,7 +21,8 @@ supporting relations for all suggested candidates. Inspect each service's
 `pages` after selection and validate the rendered links. The current selection
 path writes `canonical` for selected pages; multiple selections can violate
 the one-canonical invariant. Resolve roles and run validation before publishing.
-Variant role assignment and layout/URL conventions remain tracked in issue #27.
+Variant role assignment and layout/URL conventions are enforced by the shared
+market/locale route and reciprocal hreflang contract.
 
 ## Automatic memory hook
 
@@ -107,6 +108,14 @@ python3 tools/clis/maggie_service_booking.py category-audit \
   --project . --rendered-dir /tmp/category-rendered
 
 python3 tools/clis/maggie_service_booking.py category-context --project .
+
+# Declare provider behavior, then validate it against the imported catalogue
+# and a sanitized fixture before publishing service pages.
+python3 tools/clis/maggie_service_booking.py capability-audit \
+  --project . \
+  --catalogue .maggie/booking/services.json \
+  --capabilities-file .maggie/booking/provider-capabilities.json \
+  --fixture .maggie/booking/fixtures/provider.json
 ```
 
 `import` creates the first catalogue. `sync` compares the newly imported
@@ -265,6 +274,15 @@ amounts silently. Include `Service` and `Offer` JSON-LD only from validated
 catalogue fields. Do not emit `Review`, `AggregateRating`, or medical claims
 unless verified source data is present.
 
+Localized and market-specific variants use
+`/services/<market>/<locale>/<variant-slug>/` as their canonical route. A
+translation never reuses the source route. Published variants expose
+reciprocal hreflang links only to published counterparts. Before generation,
+each provider must declare `variantMode` (`native`, `derived-offers`,
+`single-fallback`, or `blocked`), `priceSemantics`, and `stableIdConfidence`
+in a machine-readable capability file. The capability audit requires a
+sanitized fixture and fails closed on missing or contradictory evidence.
+
 ## AI category/page copy contract
 
 Read [`references/ai-service-copy-contract.md`](../../references/ai-service-copy-contract.md)

package/bundled-tools/clis/maggie_dash.py

@@ -25,7 +25,9 @@ from service_variants import ServiceVariantStore  # noqa: E402
 from maggie_dash_ui import load_and_validate  # noqa: E402
 from maggie_sections import catalogue, remap_translations, section_id_migration, validate_registry, copy_notes, validate_values, validate_fanout, reconcile_fields, validate_locale_coverage  # noqa: E402
 from maggie_quality import validate_variant_copy, validate_media_uniqueness, classify_inventory, validate_bindings, validate_reconcile_contract  # noqa: E402
-from maggie_api_contract import validate_api_contract  # noqa: E402
+from maggie_api_contract import load_api_contract_source, validate_api_contract  # noqa: E402
+from maggie_dash_runtime import validate_runtime_evidence  # noqa: E402
+from maggie_schema_audit import audit_schema_inventory  # noqa: E402
 from route_imports import classify_bindings  # noqa: E402
 
 
@@ -316,6 +318,11 @@ def command_cms(args: argparse.Namespace) -> int:
 
 
 def command_ui(args: argparse.Namespace) -> int:
+    if args.ui_command == "runtime-validate":
+        value = json.loads(Path(args.evidence).resolve().read_text(encoding="utf-8"))
+        result = validate_runtime_evidence(value)
+        emit(result)
+        return 0 if result["passed"] else 1
     result = load_and_validate(Path(args.contract).resolve(), [Path(value).resolve() for value in args.source])
     emit(result)
     return 0 if result["passed"] else 1
@@ -429,8 +436,15 @@ def command_inventory(args: argparse.Namespace) -> int:
 
 
 def command_api_contract(args: argparse.Namespace) -> int:
-    value = json.loads(Path(args.spec).resolve().read_text(encoding="utf-8"))
-    result = validate_api_contract(value)
+    value, source = load_api_contract_source(args.spec)
+    result = {**validate_api_contract(value), "source": source}
+    emit(result)
+    return 0 if result["passed"] else 1
+
+
+def command_schema_audit(args: argparse.Namespace) -> int:
+    value = json.loads(Path(args.inventory).resolve().read_text(encoding="utf-8"))
+    result = audit_schema_inventory(value, fail_on_unread=args.fail_on_unread)
     emit(result)
     return 0 if result["passed"] else 1
 
@@ -537,6 +551,9 @@ def parser() -> argparse.ArgumentParser:
     ui_validate.add_argument("--contract", required=True)
     ui_validate.add_argument("--source", action="append", default=[])
     ui_validate.set_defaults(func=command_ui)
+    ui_runtime = ui_sub.add_parser("runtime-validate", help="validate evidence that a dashboard screen mounted and ran")
+    ui_runtime.add_argument("--evidence", required=True)
+    ui_runtime.set_defaults(func=command_ui)
     sections = sub.add_parser("sections", help="validate section registry and stable section identities")
     sections_sub = sections.add_subparsers(dest="sections_command", required=True)
     sections_validate = sections_sub.add_parser("validate")
@@ -583,9 +600,13 @@ def parser() -> argparse.ArgumentParser:
     inventory.add_argument("--require-page-kinds", action="store_true", help="fail when a published page has no pageKind")
     inventory.add_argument("--require-source-coverage", action="store_true", help="fail unless sourceCoverage.complete is true")
     inventory.set_defaults(func=command_inventory)
-    api_contract = sub.add_parser("api-contract", help="validate declared request and success-response schemas")
-    api_contract.add_argument("--spec", required=True, help="OpenAPI-like JSON document")
+    api_contract = sub.add_parser("api-contract", help="validate a local or live declared request and success-response contract")
+    api_contract.add_argument("--spec", required=True, help="local JSON file or HTTPS URL (loopback HTTP is allowed for development)")
     api_contract.set_defaults(func=command_api_contract)
+    schema_audit = sub.add_parser("schema-audit", help="find declared tables with missing reader evidence")
+    schema_audit.add_argument("--inventory", required=True, help="host-produced schema inventory JSON")
+    schema_audit.add_argument("--fail-on-unread", action="store_true")
+    schema_audit.set_defaults(func=command_schema_audit)
     variant = sub.add_parser("variant", help="manage service variant lifecycle")
     variant_sub = variant.add_subparsers(dest="variant_command", required=True)
     create = variant_sub.add_parser("create"); create.add_argument("--project", default="."); create.add_argument("--service-id", required=True); create.add_argument("--variant-id", required=True); create.add_argument("--variant-type", required=True); create.add_argument("--locale", required=True); create.add_argument("--market", required=True); create.add_argument("--slug", required=True); create.add_argument("--title", required=True); create.add_argument("--facts", required=True); create.add_argument("--source-revision", required=True); create.add_argument("--canonical-variant-id"); create.add_argument("--cluster-link", action="append", default=[]); create.add_argument("--layout-family", default="service-default"); create.add_argument("--confirm", action="store_true")