@topy-ai/maggie 0.7.18 → 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;
@@ -151,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
@@ -284,8 +305,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.18 update --project . --force
-npx @topy-ai/maggie@0.7.18 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
@@ -295,7 +316,10 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.18 workflow adds staged/untracked changed-surface detection, scenario
+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

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.18 init --agent all
+npx @topy-ai/maggie@0.7.19 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,8 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
+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；

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
@@ -301,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" };
@@ -396,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-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-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")

package/bundled-tools/clis/maggie_docs.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Audit project documentation for stale trackers and unreferenced files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+from pathlib import Path
+
+
+DOCUMENT_EXTENSIONS = {".md", ".mdx", ".json", ".yaml", ".yml"}
+SKIP_PARTS = {".git", "node_modules", "dist", "build", ".next"}
+COMPLETED_RE = re.compile(r"(?i)\b(?:done|complete|completed|shipped|resolved|closed)\b")
+TRACKER_RE = re.compile(r"(?i)(?:plan|task|progress|roadmap|todo)")
+RECORD_RE = re.compile(r"(?i)(?:audit|report|evidence|log|feedback|record)")
+
+
+def _files(root: Path) -> list[Path]:
+    return sorted(
+        path for path in root.rglob("*")
+        if path.is_file() and path.suffix.casefold() in DOCUMENT_EXTENSIONS
+        and not any(part in SKIP_PARTS for part in path.relative_to(root).parts)
+    )
+
+
+def _category(path: Path) -> str:
+    if path.suffix.casefold() in {".json", ".yaml", ".yml"}:
+        return "data"
+    name = path.stem
+    if TRACKER_RE.search(name):
+        return "plan"
+    if RECORD_RE.search(name):
+        return "record"
+    return "reference"
+
+
+def _identity(path: Path, text: str) -> str:
+    heading = next((line.strip().lstrip("#").strip() for line in text.splitlines() if line.lstrip().startswith("#")), "")
+    value = heading or path.stem
+    return re.sub(r"[^a-z0-9]+", "-", value.casefold()).strip("-")
+
+
+def _last_change(project: Path, relative: str) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(project), "log", "-1", "--format=%cI", "--", relative],
+            capture_output=True, text=True, check=False,
+        )
+    except OSError:
+        return None
+    value = result.stdout.strip()
+    return value or None
+
+
+def audit(project: Path, docs_dir: str = "docs") -> dict:
+    root = project.resolve()
+    docs = (root / docs_dir).resolve()
+    if not docs.is_dir():
+        return {"schemaVersion": "maggie-docs-audit.v1", "passed": False, "errors": [f"docs directory does not exist: {docs}"], "files": []}
+    files = _files(docs)
+    corpus: list[tuple[Path, str]] = []
+    for path in _files(root):
+        try:
+            corpus.append((path, path.read_text(encoding="utf-8", errors="replace")))
+        except OSError:
+            continue
+    entries = []
+    for path in files:
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError as error:
+            entries.append({"path": str(path.relative_to(root)), "status": "unreadable", "error": str(error)})
+            continue
+        relative = str(path.relative_to(root))
+        basename = path.name
+        inbound = sum(1 for source, source_text in corpus if source != path and (relative in source_text or basename in source_text))
+        category = _category(path)
+        completed_tracker = category == "plan" and bool(COMPLETED_RE.search(text))
+        findings: list[str] = []
+        if completed_tracker:
+            findings.append("completed-progress-tracker")
+        if inbound == 0 and category in {"reference", "data"}:
+            findings.append("unreferenced")
+        entries.append({
+            "path": relative,
+            "category": category,
+            "inboundReferences": inbound,
+            "lastChanged": _last_change(root, relative),
+            "completedTracker": completed_tracker,
+            "openTracker": category == "plan" and not completed_tracker,
+            "identity": _identity(path, text),
+            "findings": findings,
+        })
+    identities: dict[str, list[dict]] = {}
+    for item in entries:
+        identities.setdefault(item.get("identity", ""), []).append(item)
+    duplicate_groups = [group for key, group in identities.items() if key and len(group) > 1]
+    duplicate_paths = {item["path"] for group in duplicate_groups for item in group}
+    for item in entries:
+        item.pop("identity", None)
+        if item["path"] in duplicate_paths:
+            item["findings"].append("duplicate-candidate")
+        item["staleCandidate"] = bool(item["findings"])
+    findings = [item for item in entries if item.get("findings")]
+    return {
+        "schemaVersion": "maggie-docs-audit.v1",
+        "passed": True,
+        "project": str(root),
+        "docsDirectory": str(docs.relative_to(root)),
+        "fileCount": len(entries),
+        "findingCount": len(findings),
+        "summary": {
+            "reference": sum(item.get("category") == "reference" for item in entries),
+            "record": sum(item.get("category") == "record" for item in entries),
+            "plan": sum(item.get("category") == "plan" for item in entries),
+            "data": sum(item.get("category") == "data" for item in entries),
+            "completedTrackers": sum(item.get("completedTracker", False) for item in entries),
+            "openTrackers": sum(item.get("openTracker", False) for item in entries),
+            "unreferenced": sum("unreferenced" in item.get("findings", []) for item in entries),
+            "duplicateCandidates": len(duplicate_groups),
+            "staleCandidates": sum(item.get("staleCandidate", False) for item in entries),
+        },
+        "files": entries,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("audit", nargs="?", choices=("audit",), default="audit")
+    parser.add_argument("--project", default=".")
+    parser.add_argument("--docs-dir", default="docs")
+    parser.add_argument("--fail-on-findings", action="store_true")
+    parser.add_argument("--output")
+    args = parser.parse_args()
+    result = audit(Path(args.project), args.docs_dir)
+    if args.fail_on_findings and result.get("findingCount"):
+        result["passed"] = False
+        result.setdefault("errors", []).append("documentation findings require review")
+    if args.output:
+        output = Path(args.output).expanduser().resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        result["output"] = str(output)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result.get("passed") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/runtime/maggie_api_contract.py

@@ -4,11 +4,17 @@ from __future__ import annotations
 
 from collections.abc import Mapping
 from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+from pathlib import Path
+import json
 
 
 SCHEMA = "maggie-api-contract.v1"
 METHODS = {"get", "post", "put", "patch", "delete", "head", "options", "trace"}
 BODY_METHODS = {"post", "put", "patch"}
+MAX_SPEC_BYTES = 2_000_000
 
 
 def _has_schema(value: object) -> bool:
@@ -95,3 +101,48 @@ def validate_api_contract(spec: object) -> dict[str, Any]:
             operations.append(record)
     return {"schemaVersion": SCHEMA, "passed": not errors, "operations": operations, "errors": errors,
             "operationCount": len(operations), "errorCount": len(errors)}
+
+
+def _safe_url(source: str) -> tuple[str, str]:
+    parsed = urlparse(source)
+    if parsed.scheme not in {"https", "http"} or not parsed.netloc:
+        raise ValueError("API contract source must be a local file or an absolute HTTPS URL")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("API contract URL must not contain credentials, query parameters, or fragments")
+    host = (parsed.hostname or "").casefold()
+    if parsed.scheme == "http" and host not in {"localhost", "127.0.0.1", "::1"}:
+        raise ValueError("plain HTTP is allowed only for loopback development sources")
+    display = f"{parsed.scheme}://{parsed.netloc}{parsed.path or '/'}"
+    return source, display
+
+
+def load_api_contract_source(source: str | Path, *, timeout: float = 20.0) -> tuple[object, dict[str, Any]]:
+    """Load a local JSON spec or fetch a safe URL without writing the response.
+
+    The caller receives source metadata suitable for an audit report. Response
+    bodies are parsed in memory only, so a live contract check cannot silently
+    create a project artifact containing a private API document.
+    """
+    value = str(source)
+    parsed = urlparse(value)
+    if parsed.scheme in {"https", "http"}:
+        requested, display = _safe_url(value)
+        request = Request(requested, headers={"Accept": "application/json", "User-Agent": "MaggieApiContract/1"})
+        try:
+            with urlopen(request, timeout=timeout) as response:
+                raw = response.read(MAX_SPEC_BYTES + 1)
+        except (HTTPError, URLError, TimeoutError) as error:
+            raise RuntimeError(f"could not fetch API contract URL: {error}") from error
+        if len(raw) > MAX_SPEC_BYTES:
+            raise ValueError(f"API contract response exceeds {MAX_SPEC_BYTES} bytes")
+        try:
+            document = json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as error:
+            raise ValueError("API contract URL did not return a UTF-8 JSON document") from error
+        return document, {"sourceType": "url", "source": display}
+
+    path = Path(value).expanduser().resolve()
+    raw = path.read_bytes()
+    if len(raw) > MAX_SPEC_BYTES:
+        raise ValueError(f"API contract file exceeds {MAX_SPEC_BYTES} bytes")
+    return json.loads(raw.decode("utf-8")), {"sourceType": "file", "source": str(path)}

package/bundled-tools/runtime/maggie_dash_runtime.py

@@ -0,0 +1,58 @@
+"""Validate runtime evidence that a dashboard screen actually mounted and ran."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import urlparse
+
+
+SCHEMA = "maggiedash-dashboard-runtime.v1"
+
+
+def validate_runtime_evidence(evidence: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(evidence, Mapping):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["evidence must be an object"]}
+    if evidence.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    for field in ("screen", "route"):
+        if not isinstance(evidence.get(field), str) or not evidence[field].strip():
+            errors.append(f"{field} is required")
+    if evidence.get("mounted") is not True:
+        errors.append("mounted must be true")
+    checks = evidence.get("checks")
+    if not isinstance(checks, list) or not checks:
+        errors.append("checks must contain at least one executed check")
+        checks = []
+    check_results: list[dict[str, Any]] = []
+    for index, check in enumerate(checks):
+        if not isinstance(check, Mapping) or not isinstance(check.get("name"), str) or not check["name"].strip():
+            errors.append(f"checks[{index}] needs a name")
+            continue
+        if not isinstance(check.get("passed"), bool):
+            errors.append(f"checks[{index}].passed must be boolean")
+        elif check["passed"] is False:
+            errors.append(f"runtime check failed: {check['name']}")
+        check_results.append({"name": check["name"], "passed": check.get("passed")})
+    calls = evidence.get("dataCalls", [])
+    if not isinstance(calls, list):
+        errors.append("dataCalls must be a list")
+        calls = []
+    call_results: list[dict[str, Any]] = []
+    for index, call in enumerate(calls):
+        if not isinstance(call, Mapping):
+            errors.append(f"dataCalls[{index}] must be an object")
+            continue
+        url = str(call.get("url") or "")
+        parsed = urlparse(url)
+        if not url or parsed.username or parsed.password or parsed.scheme not in {"", "http", "https"}:
+            errors.append(f"dataCalls[{index}].url must be a relative or credential-free HTTP URL")
+        if not isinstance(call.get("method", "GET"), str):
+            errors.append(f"dataCalls[{index}].method must be a string")
+        if not isinstance(call.get("ok"), bool):
+            errors.append(f"dataCalls[{index}].ok must be boolean")
+        elif call["ok"] is False:
+            errors.append(f"data call failed: {url or 'unknown'}")
+        call_results.append({"url": url, "method": call.get("method", "GET"), "status": call.get("status"), "ok": call.get("ok")})
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "screen": evidence.get("screen"), "route": evidence.get("route"), "mounted": evidence.get("mounted"), "checks": check_results, "dataCalls": call_results}

package/bundled-tools/runtime/maggie_schema_audit.py

@@ -0,0 +1,72 @@
+"""Validate host-supplied table/reader evidence without connecting to a database."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+
+SCHEMA = "maggie-schema-inventory.v1"
+
+
+def audit_schema_inventory(inventory: object, *, fail_on_unread: bool = False) -> dict[str, Any]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if not isinstance(inventory, Mapping):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["inventory must be an object"], "tables": []}
+    if inventory.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    tables = inventory.get("tables")
+    if not isinstance(tables, list):
+        errors.append("tables must be a list")
+        tables = []
+    seen: set[str] = set()
+    normalized: list[dict[str, Any]] = []
+    unread: list[dict[str, Any]] = []
+    unknown: list[str] = []
+    for index, table in enumerate(tables):
+        prefix = f"tables[{index}]"
+        if not isinstance(table, Mapping):
+            errors.append(f"{prefix} must be an object")
+            continue
+        name = str(table.get("name") or "").strip()
+        if not name:
+            errors.append(f"{prefix}.name is required")
+            continue
+        if name in seen:
+            errors.append(f"duplicate table: {name}")
+        seen.add(name)
+        row_count = table.get("rowCount")
+        if not isinstance(row_count, int) or isinstance(row_count, bool) or row_count < 0:
+            errors.append(f"{prefix}.rowCount must be a non-negative integer")
+            row_count = None
+        readers = table.get("readers")
+        if readers is None:
+            unknown.append(name)
+            warnings.append(f"{name} has no reader evidence")
+            reader_list: list[str] = []
+            reader_status = "unknown"
+        elif not isinstance(readers, list) or any(not isinstance(reader, str) or not reader.strip() for reader in readers):
+            errors.append(f"{prefix}.readers must be a list of non-empty strings")
+            reader_list = []
+            reader_status = "invalid"
+        else:
+            reader_list = sorted({reader.strip() for reader in readers})
+            reader_status = "read" if reader_list else "unread"
+        record = {"name": name, "rowCount": row_count, "readers": reader_list, "readerStatus": reader_status}
+        normalized.append(record)
+        if reader_status == "unread":
+            unread.append(record)
+    if fail_on_unread and unread:
+        errors.append(f"{len(unread)} declared table(s) have no reader evidence")
+    return {
+        "schemaVersion": SCHEMA,
+        "passed": not errors,
+        "errors": errors,
+        "warnings": warnings,
+        "tables": normalized,
+        "unreadTables": unread,
+        "unknownReaderEvidence": unknown,
+        "tableCount": len(normalized),
+        "unreadCount": len(unread),
+    }

package/package.json

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