@topy-ai/maggie 0.7.15 → 0.7.17

package/README.md

@@ -80,9 +80,13 @@ 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;
 sitemap validation flags suspiciously uniform `lastmod` dates; `maggie seo
-indexnow` plans only changed same-origin URLs and holds back URLs accepted in
-the last 24 hours; and dash inventory separates renderer kind from public page
-kind while reporting source coverage for code-rendered routes.
+indexnow` plans only changed same-origin URLs, verifies the deployed key route
+with an optional negative control, and holds back URLs accepted in the last 24
+hours. `maggie seo social-cards` checks per-page OG image dimensions and format;
+`maggie seo head-tags` reports metadata drift across rendered shells;
+`maggie ops favicon-check` verifies the served `/favicon.ico` and declared icon.
+Dash inventory separates renderer kind from public page kind while reporting
+source coverage for code-rendered routes.
 
 For Google integrations, validate a redacted provider matrix before reporting
 access. The command fails closed on unknown scopes, missing Ads prerequisites,
@@ -145,7 +149,10 @@ maggie service ...               # import, sync, generate, 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
-maggie seo indexnow ...           # changed URLs, key check, retry-safe 24h guard
+maggie seo indexnow ...           # changed URLs, deployed key check, 24h guard
+maggie seo social-cards ...       # per-page og:image format/dimension audit
+maggie seo head-tags ...          # rendered-shell head metadata drift audit
+maggie ops favicon-check ...      # served favicon behaviour check
 maggie deployment | migration | release | analytics | schedule
 maggie migration identity --identity-file FILE [--expected-file FILE]
 maggie deployment canary --asset URL=SHA256 --render-report report.json
@@ -199,6 +206,19 @@ Read the [performance PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/mai
 and [image/sitemap PRD](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/docs/image-sitemap-structure-prd.md)
 for adapter, privacy, apply, rollback, and release gates.
 
+For a database-backed blog, `maggie blog check-gate` accepts a sanitized host
+settings adapter so review policy can be checked without copying database
+credentials into a local store:
+
+```bash
+maggie blog check-gate --project . \
+  --adapter-command '["node", "scripts/read-blog-settings.mjs"]'
+```
+
+The adapter is an argv array, receives a versioned request on stdin, and must
+print only the three review-policy fields. Provider stderr is suppressed and a
+missing local store without an adapter fails closed.
+
 ### Design and deployment release gates
 
 Check source-to-runtime icon coverage before shipping a design:
@@ -247,8 +267,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.15 update --project . --force
-npx @topy-ai/maggie@0.7.15 cleanup --project .
+npx @topy-ai/maggie@0.7.17 update --project . --force
+npx @topy-ai/maggie@0.7.17 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -258,7 +278,11 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.15 workflow adds API contracts, blog review gates, sitemap freshness,
+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
+coverage. The 0.7.15 workflow added API contracts, blog review gates, sitemap freshness,
 change-driven IndexNow, and page-kind/source-coverage inventory. It also keeps
 the general `maggie-qa-workflow` skill and `maggie qa`
 CLI for scenario manifests, secret-free browser evidence metadata, test/fix/

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.7.15 init --agent all
+npx @topy-ai/maggie@0.7.16 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,7 @@ 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.15 也加入 API schema contract、blog review gate、sitemap freshness
 warning、change-driven IndexNow 與 page-kind/source-coverage inventory。
 

package/bin/maggie.js

@@ -113,7 +113,7 @@ Usage:
   maggie api lifecycle --project PATH [--execute --allow-quota]
   maggie memory <init|list|search|context|add|record-error|transition|export> --project PATH
   maggie localization <extract|plan|generate|preview|validate|review|publish|stale|glossary> [options]
-  maggie seo performance|images|sitemap|indexnow [options] (sitemap supports strict validate and agent-files)
+  maggie seo performance|images|sitemap|indexnow|social-cards|head-tags [options] (sitemap supports strict validate and agent-files)
   maggie feedback <collect|preview|submit|list> [options]
   maggie qa <start|record|summary|export> [options]
   maggie site-audit URL [--crawl] [--access-log FILE] [--require-sitemap-request] [--languages en-GB,es-MX,ja-JP] [--check-hreflang]
@@ -121,7 +121,7 @@ Usage:
   maggie site-audit URL --crawl --baseline FILE
   maggie browser-audit URL --browse PATH --output DIR --required SELECTOR [--sticky SELECTOR]
   maggie verification coverage --contract FILE --evidence FILE
-  maggie ops audit|preflight|verify|lockfiles|seed-manifest|google-capabilities --project PATH
+  maggie ops audit|preflight|verify|lockfiles|seed-manifest|google-capabilities|favicon-check --project PATH
   maggie ops google-capabilities --project PATH --report FILE [--output FILE]
   maggie ops preflight --project PATH --write
 
@@ -302,8 +302,8 @@ function service(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" };
-  if (!scripts[command]) throw new Error("seo command must be performance, images, sitemap, or indexnow");
+  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" };
+  if (!scripts[command]) throw new Error("seo command must be performance, images, sitemap, indexnow, social-cards, or head-tags");
   workflowCli(scripts[command], args.slice(1));
 }
 

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

@@ -38,6 +38,9 @@ maggie blog init --project . --base-path /our-blogs --confirm
 	maggie blog ingest --project . --source local --input content/posts.json --confirm
 	maggie blog validate --project .
 	maggie blog check-gate --project .
+	# Database-backed hosts can supply a sanitized policy through an adapter.
+	maggie blog check-gate --project . \
+	  --adapter-command '["node", "scripts/read-blog-settings.mjs"]'
 	maggie blog approve --project . --slug example-post --actor reviewer --reason "reviewed" --confirm
 	maggie blog publish --project . --slug example-post --actor owner --reason "approved" --confirm
 maggie blog sitemap --project .
@@ -51,7 +54,14 @@ explicit `approve` transition before `publish`. Stable `contentId` is the
 ingest identity and a published slug must not change during a rewrite.
 Search/sort views are not indexable; drafts never appear in public routes, RSS,
 or sitemap output. Provider keys remain server-side. Public publication and
-migrations always require explicit confirmation.
+	migrations always require explicit confirmation.
+
+The adapter runs as an argv array without a shell, receives a versioned request
+on stdin, and must print only an object containing
+`defaultPostStatus`/`default_post_status`, `requireReview`/`require_review`,
+and `autoPublishEnabled`/`auto_publish`. Provider stderr is suppressed. Use
+`--settings-file` for a reviewed sanitized snapshot. A missing local store with
+neither input fails closed.
 
 To initialize native front-end pages from the approved local UI guideline,
 run `maggie-design`:

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

@@ -219,6 +219,11 @@ 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.
 
+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
+does not infer these values from a route filename or from one sample page.
+
 The catalogue declares purpose, usage, placement, repeatability and layout
 limits, renderer-owned examples, and the shape of repeated entries. A repeat
 may contain an object (`title`, `body`, `href`, and so on), not just a count;

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

@@ -42,6 +42,8 @@ python3 tools/clis/maggie_ops.py --project . audit
 python3 tools/clis/maggie_ops.py --project . preflight --write
 python3 tools/clis/maggie_ops.py --project . status
 python3 tools/clis/maggie_ops.py --project . verify
+python3 tools/clis/maggie_ops.py --project . favicon-check \
+  --origin https://example.com
 python3 tools/clis/maggie_ops.py --project . record sitemap-match \
   --dry-run --quota-impact quota --idempotency-key match-2026-08-29-001
 ```
@@ -52,6 +54,12 @@ python3 tools/clis/maggie_ops.py --project . record sitemap-match \
 approved operation but does not call a remote provider; provider mutations
 remain behind the server-side API adapter and its execute gate.
 
+`favicon-check` is a deployed behavioural check. It fetches `/favicon.ico`
+and the declared `<link rel="icon">` (or an explicit `--declared-url`), then
+requires HTTP 200, a readable square image, and an engine-supported ICO, PNG,
+or GIF response. A logo-shaped source filename is only an unverified source
+candidate; it is never evidence that the public favicon route works.
+
 If the user does not name a mode, inspect the project and propose the smallest
 mode that satisfies the request. Do not rebuild the public blog or change its
 framework just to add Ops.

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

@@ -181,13 +181,23 @@ maggie seo sitemap rollback --backup-manifest .maggie-sitemap-backups/<plan>/bac
   --public-dir public --confirm
 
 # Change-driven IndexNow: only pass URLs whose rendered content changed.
-maggie seo indexnow key-check --public-dir public --key-file <key>.txt --key <key>
+maggie seo indexnow key-check --public-dir public --key-file <key>.txt --key <key> \
+  --key-url https://example.com/<key>.txt \
+  --wrong-key-url https://example.com/not-a-key.txt
 maggie seo indexnow plan --origin https://example.com \
   --changed-urls-file .maggie/changed-urls.json \
   --state-file .maggie/indexnow-state.json --key <key> \
   --output .maggie/indexnow-plan.json
 maggie seo indexnow submit --plan .maggie/indexnow-plan.json \
   --state-file .maggie/indexnow-state.json --confirm
+
+# Resolve each page's og:image and inspect its image contract.
+maggie seo social-cards audit --urls-file .maggie/public-urls.json \
+  --output .maggie/social-cards.json
+
+# Compare normalized head metadata emitted by every rendered shell.
+maggie seo head-tags audit --pages-file .maggie/rendered-head.json \
+  --output .maggie/head-tags.json
 ```
 
 Only confirmed image variants may enter `srcset`; `apply` requires an explicit
@@ -203,6 +213,24 @@ records accepted state only after HTTP 200/202. A 403/429/5xx or network error
 is retryable and must never make the editor save fail; do not retry unchanged
 URLs in a loop.
 
+The complete IndexNow key gate checks both the local public file and the
+deployed URL body. Add a wrong-key URL as a negative control when the host
+route is expected to return 404; response bodies are never printed.
+
+Social-card auditing uses a `300x157` minimum for a large summary card and
+accepts JPEG, PNG, GIF, and ICO responses. It reports missing, unreachable,
+undersized, unreadable, or unsupported images and warns when one source is
+used for at least 75% of a sample of three or more pages. Page-specific
+first-band images remain an editorial choice and should be declared by the
+host manifest.
+
+Head-tag auditing consumes a host-produced JSON manifest with `url`, `shell`,
+and normalized `tags`. It compares structural declarations for icons,
+`og:image`, image MIME type, verification presence, robots, and Twitter cards;
+route-specific title and canonical values are intentionally excluded from
+shell drift. It reports disagreements instead of guessing which shell is
+correct.
+
 For a deterministic technical smoke check, run:
 
 ```bash

package/bundled-tools/clis/maggie.py

@@ -206,7 +206,7 @@ def detect(root: Path) -> dict:
     asset_contract = {
         "redirects": found("present", "redirects file") if any(name in names for name in {"_redirects", "redirects.json", "redirects.csv"}) else missing("no redirects manifest detected"),
         "security_headers": found("present", name) if (name := next((name for name in {"_headers", "headers.json", "vercel.json", "netlify.toml"} if name in names), None)) else missing("no deployment/header policy detected"),
-        "favicon_or_brand": found("present", path) if (path := next((path for path in implementation_paths if any(token in path.lower() for token in {"favicon", "logo", "brand"}) and Path(path).suffix in {".svg", ".png", ".ico", ".webp"}), None)) else missing("no favicon or brand asset detected"),
+        "favicon_or_brand": {"status": "Unverified", "value": "source asset candidate found; verify the served icon with `maggie ops favicon-check`", "evidence": [path]} if (path := next((path for path in implementation_paths if any(token in path.lower() for token in {"favicon", "logo", "brand"}) and Path(path).suffix in {".svg", ".png", ".ico", ".webp"}), None)) else missing("no favicon or brand asset detected"),
         "social_image": found("present", path) if (path := next((path for path in implementation_paths if any(token in path.lower() for token in {"og", "social", "twitter"}) and Path(path).suffix in {".jpg", ".jpeg", ".png", ".webp"}), None)) else missing("no social image asset detected"),
     }
     content_model = {

package/bundled-tools/clis/maggie_blog.py

@@ -9,7 +9,7 @@ import sys
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
-from maggie_blog import BlogStore  # noqa: E402
+from maggie_blog import BlogStore, review_settings_from_adapter  # noqa: E402
 from localization_runner import process_adapter
 from integration_state import integration_state  # noqa: E402
 
@@ -27,7 +27,7 @@ def main() -> int:
     inspect = sub.add_parser("inspect"); inspect.add_argument("--project", type=Path, default=Path.cwd())
     ingest = sub.add_parser("ingest"); ingest.add_argument("--project", type=Path, default=Path.cwd()); ingest.add_argument("--input", type=Path, required=True); ingest.add_argument("--source", default="local"); ingest.add_argument("--confirm", action="store_true")
     validate = sub.add_parser("validate"); validate.add_argument("--project", type=Path, default=Path.cwd())
-    gate = sub.add_parser("check-gate", help="report whether generated content requires review before publication"); gate.add_argument("--project", type=Path, default=Path.cwd())
+    gate = sub.add_parser("check-gate", help="report whether generated content requires review before publication"); gate.add_argument("--project", type=Path, default=Path.cwd()); gate.add_argument("--settings-file", type=Path, help="sanitized host settings JSON"); gate.add_argument("--adapter-command", help="trusted provider JSON argv array that prints sanitized settings JSON"); gate.add_argument("--timeout", type=int, default=120)
     approve = sub.add_parser("approve"); approve.add_argument("--project", type=Path, default=Path.cwd()); approve.add_argument("--slug", required=True); approve.add_argument("--actor", required=True); approve.add_argument("--reason", required=True); approve.add_argument("--confirm", action="store_true")
     publish = sub.add_parser("publish"); publish.add_argument("--project", type=Path, default=Path.cwd()); publish.add_argument("--slug", required=True); publish.add_argument("--actor", required=True); publish.add_argument("--reason", required=True); publish.add_argument("--confirm", action="store_true")
     sitemap = sub.add_parser("sitemap"); sitemap.add_argument("--project", type=Path, default=Path.cwd())
@@ -39,6 +39,16 @@ def main() -> int:
         result = integration_state(configured=args.configured, consent_required=args.consent_required, consent=args.consent, authorized=args.authorized, error=args.error)
         print(json.dumps(result, indent=2, ensure_ascii=False))
         return 0 if result["status"] != "error" else 1
+    if args.command == "check-gate" and (args.settings_file or args.adapter_command):
+        try:
+            adapter_command = json.loads(args.adapter_command) if args.adapter_command else None
+            settings, source = review_settings_from_adapter(args.project.resolve(), args.settings_file.resolve() if args.settings_file else None, adapter_command, args.timeout)
+            result = BlogStore.review_gate(settings)
+            result["source"] = source
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"maggie-blog: {error}", file=sys.stderr); return 1
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result.get("passed") else 1
     store = BlogStore(args.project.resolve())
     if args.command in {"init", "ingest", "publish", "approve", "rollback", "translate-pending"} and not args.confirm:
         print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
@@ -64,6 +74,8 @@ def main() -> int:
     print(json.dumps(result, indent=2, ensure_ascii=False))
     if args.command in {"ingest", "translate-pending"} and result.get("status") == "partial":
         return 1
+    if args.command == "check-gate":
+        return 0 if result.get("passed") else 1
     return 0 if args.command != "validate" or result.get("valid") else 1
 
 

package/bundled-tools/clis/maggie_head_tags.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Compare normalized rendered head tags across site shells."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_head_tags import audit_head_tags, read_pages  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie seo head-tags")
+    sub = parser.add_subparsers(dest="command", required=True)
+    audit = sub.add_parser("audit", help="report head-tag disagreements across rendered shells")
+    audit.add_argument("--pages-file", type=Path, required=True, help="JSON page manifest with url, shell, and tags")
+    audit.add_argument("--output")
+    args = parser.parse_args()
+    try:
+        result = audit_head_tags(read_pages(args.pages_file))
+        if args.output:
+            output = Path(args.output).resolve(); output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result["passed"] else 1
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"maggie-head-tags: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_indexnow.py

@@ -9,7 +9,7 @@ from pathlib import Path
 import sys
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
-from maggie_indexnow import check_key_file, plan_indexnow, submit_plan  # noqa: E402
+from maggie_indexnow import check_key_file, check_key_http, plan_indexnow, submit_plan  # noqa: E402
 
 
 def read_json(path: Path, default: object) -> object:
@@ -26,8 +26,8 @@ def write_json(path: Path, value: object) -> None:
 def main() -> int:
     parser = argparse.ArgumentParser(prog="maggie seo indexnow")
     sub = parser.add_subparsers(dest="command", required=True)
-    key_check = sub.add_parser("key-check", help="verify the public ownership key file")
-    key_check.add_argument("--public-dir", required=True); key_check.add_argument("--key-file", required=True); key_check.add_argument("--key", required=True)
+    key_check = sub.add_parser("key-check", help="verify local and deployed public ownership key evidence")
+    key_check.add_argument("--public-dir", required=True); key_check.add_argument("--key-file", required=True); key_check.add_argument("--key", required=True); key_check.add_argument("--key-url", help="deployed key URL to fetch"); key_check.add_argument("--wrong-key-url", help="negative-control URL expected to return HTTP 404"); key_check.add_argument("--timeout", type=int, default=15)
     plan = sub.add_parser("plan", help="hold back recently accepted URLs and create a submission plan")
     plan.add_argument("--origin", required=True); plan.add_argument("--changed-urls-file", required=True); plan.add_argument("--state-file", required=True); plan.add_argument("--key", required=True); plan.add_argument("--key-location"); plan.add_argument("--guard-hours", type=int, default=24); plan.add_argument("--now"); plan.add_argument("--output", required=True)
     submit = sub.add_parser("submit", help="submit an approved plan; provider failure never updates accepted state")
@@ -36,6 +36,9 @@ def main() -> int:
     try:
         if args.command == "key-check":
             result = check_key_file(Path(args.public_dir).resolve(), args.key_file, args.key)
+            if args.key_url:
+                result["http"] = check_key_http(args.key_url, args.key, args.wrong_key_url, args.timeout)
+                if result["http"]["status"] != "pass": result["status"] = "fail"
             print(json.dumps(result, indent=2)); return 0 if result["status"] == "pass" else 1
         if args.command == "plan":
             changed = read_json(Path(args.changed_urls_file), [])

package/bundled-tools/clis/maggie_ops.py

@@ -15,6 +15,7 @@ from seed_evidence import validate_manifest
 from agent_runtime import preflight as agent_preflight
 from restart_gate import validate as validate_restart_gate
 from google_capabilities import validate_report as validate_google_capability_report
+from maggie_favicon import check_favicon
 
 
 REQUIRED_ROUTES = (
@@ -181,6 +182,12 @@ def command_google_capabilities(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_favicon_check(args: argparse.Namespace) -> int:
+    result = check_favicon(args.origin, args.declared_url, args.timeout)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--project", default=".")
@@ -203,6 +210,11 @@ def main() -> int:
     google.add_argument("--report", required=True)
     google.add_argument("--output")
     google.set_defaults(func=command_google_capabilities)
+    favicon = sub.add_parser("favicon-check", help="fetch /favicon.ico and the declared icon to verify behaviour")
+    favicon.add_argument("--origin", required=True)
+    favicon.add_argument("--declared-url")
+    favicon.add_argument("--timeout", type=int, default=15)
+    favicon.set_defaults(func=command_favicon_check)
     record = sub.add_parser("record", help="record an explicitly authorised operation")
     record.add_argument("operation", choices=("sync", "sitemap-match", "rewrite-queue", "rewrite-approve", "publish", "migration"))
     record.add_argument("--dry-run", action="store_true")

package/bundled-tools/clis/maggie_social_cards.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""Audit per-page Open Graph social-card assets."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_social_cards import audit_cards, pages_from_urls, read_pages  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie seo social-cards")
+    sub = parser.add_subparsers(dest="command", required=True)
+    audit = sub.add_parser("audit", help="resolve each page og:image and inspect its image contract")
+    sources = audit.add_mutually_exclusive_group(required=True)
+    sources.add_argument("--urls-file", type=Path, help="JSON array or {\"urls\": []} of HTML URLs")
+    sources.add_argument("--pages-file", type=Path, help="JSON page manifest with url and ogImage fields")
+    audit.add_argument("--timeout", type=int, default=15)
+    audit.add_argument("--output")
+    args = parser.parse_args()
+    try:
+        pages = read_pages(args.pages_file) if args.pages_file else None
+        if args.urls_file:
+            value = json.loads(args.urls_file.read_text(encoding="utf-8"))
+            urls = value.get("urls") if isinstance(value, dict) else value
+            if not isinstance(urls, list) or any(not isinstance(url, str) or not url.strip() for url in urls):
+                raise ValueError("urls file must be a JSON array or {\"urls\": []} of nonempty strings")
+            pages = pages_from_urls(urls, args.timeout)
+        result = audit_cards(pages or [], timeout=args.timeout)
+        if args.output:
+            output = Path(args.output).resolve(); output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0 if result["passed"] else 1
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"maggie-social-cards: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/site_audit.py

@@ -144,7 +144,7 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
         "canonical": bool(canonical) and urlparse(canonical).fragment == "",
         "description": bool(page.meta.get("description")),
         "locale": valid_locale(page.lang) and (not expected_languages or parse_locale(page.lang)[0] in expected_languages or page.lang in expected_languages),
-        "open_graph": all(page.meta.get(key) for key in ("og:title", "og:description", "og:url")),
+        "open_graph": all(page.meta.get(key) for key in ("og:title", "og:description", "og:url", "og:image")),
         "twitter_card": page.meta.get("twitter:card") in {"summary", "summary_large_image"},
         "jsonld": page.jsonld > 0 and all(item is not None for item in page.jsonld_values),
         "entity_jsonld": any(isinstance(item, dict) and item.get("@type") and (item.get("url") or item.get("@id")) for item in page.jsonld_values),
@@ -312,7 +312,7 @@ def main() -> int:
         checks["canonical"] = {"ok": bool(canonical) and urlparse(canonical).fragment == "", "value": canonical}
         checks["description"] = {"ok": bool(page.meta.get("description")), "value": page.meta.get("description", "")}
         checks["locale"] = {"ok": valid_locale(page.lang) and (not expected_languages or parse_locale(page.lang)[0] in expected_languages or page.lang in expected_languages), "value": page.lang, "language": parse_locale(page.lang)[0], "markets": sorted(markets)}
-        checks["open_graph"] = {"ok": all(page.meta.get(key) for key in ("og:title", "og:description", "og:url")), "fields": {key: bool(page.meta.get(key)) for key in ("og:title", "og:description", "og:url")}}
+        checks["open_graph"] = {"ok": all(page.meta.get(key) for key in ("og:title", "og:description", "og:url", "og:image")), "fields": {key: bool(page.meta.get(key)) for key in ("og:title", "og:description", "og:url", "og:image")}}
         checks["twitter_card"] = {"ok": page.meta.get("twitter:card") in {"summary", "summary_large_image"}, "value": page.meta.get("twitter:card", "")}
         checks["jsonld"] = {"ok": page.jsonld > 0 and all(item is not None for item in page.jsonld_values), "count": page.jsonld}
         checks["entity_jsonld"] = {"ok": any(isinstance(item, dict) and item.get("@type") and (item.get("url") or item.get("@id")) for item in page.jsonld_values), "count": page.jsonld}

package/bundled-tools/runtime/maggie_blog.py

@@ -6,6 +6,7 @@ import hashlib
 import json
 import re
 import shutil
+import subprocess
 from datetime import datetime, timezone
 from pathlib import Path
 from localization_runner import checkpoint, generate
@@ -44,6 +45,90 @@ def checksum(value: object) -> str:
     return "sha256:" + hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
 
 
+def normalise_review_settings(value: object) -> dict:
+    """Map a host settings record to the small review-gate contract.
+
+    Hosts may store settings in PostgreSQL or another provider. The adapter
+    boundary deliberately accepts only these policy fields; credentials and
+    unrelated provider data never enter the report.
+    """
+    if not isinstance(value, dict):
+        raise ValueError("blog settings adapter must return a JSON object")
+    source = value.get("settings") if isinstance(value.get("settings"), dict) else value
+
+    def first(*keys: str, default: object = None) -> object:
+        for key in keys:
+            if key in source:
+                return source[key]
+        return default
+
+    def as_bool(value: object, default: bool) -> bool:
+        if value is None:
+            return default
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            lowered = value.strip().lower()
+            if lowered in {"true", "1", "yes", "on"}:
+                return True
+            if lowered in {"false", "0", "no", "off", ""}:
+                return False
+        return bool(value)
+
+    default_status = str(first("defaultPostStatus", "default_post_status", default="draft") or "draft")
+    return {
+        "schemaVersion": "maggie-blog-settings.v1",
+        "defaultPostStatus": default_status,
+        "requireReview": as_bool(first("requireReview", "require_review", default=True), True),
+        "autoPublishEnabled": as_bool(first("autoPublishEnabled", "auto_publish", "autoPublish", default=False), False),
+    }
+
+
+def review_settings_from_adapter(project: Path, settings_file: Path | None = None,
+                                 adapter_command: list[str] | None = None,
+                                 timeout: int = 120) -> tuple[dict, str]:
+    """Read sanitized settings from a file or trusted argv adapter.
+
+    ``adapter_command`` is executed without a shell and receives a small
+    request on stdin. Its stdout must be the normalized settings object. Error
+    output is intentionally suppressed so provider details cannot leak into a
+    Maggie report.
+    """
+    if settings_file and adapter_command:
+        raise ValueError("use either --settings-file or --adapter-command")
+    if timeout < 1:
+        raise ValueError("adapter timeout must be positive")
+    if settings_file:
+        try:
+            value = json.loads(settings_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            raise ValueError("settings file must contain a JSON object") from None
+        return normalise_review_settings(value), "settings-file"
+    if adapter_command is not None:
+        if not adapter_command or any(not isinstance(part, str) or not part for part in adapter_command):
+            raise ValueError("adapter-command must be a nonempty JSON argv array")
+        try:
+            result = subprocess.run(
+                adapter_command,
+                input=json.dumps({"schemaVersion": "maggie-blog-settings-request.v1"}),
+                text=True,
+                capture_output=True,
+                timeout=timeout,
+                check=False,
+                cwd=project.resolve(),
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            raise OSError("blog settings adapter could not execute or timed out") from None
+        if result.returncode:
+            raise OSError("blog settings adapter failed; provider output suppressed")
+        try:
+            value = json.loads(result.stdout)
+        except json.JSONDecodeError:
+            raise ValueError("blog settings adapter must return a JSON object") from None
+        return normalise_review_settings(value), "adapter-command"
+    raise ValueError("blog is not initialized; use --settings-file or --adapter-command for a provider-backed blog")
+
+
 class BlogStore:
     def __init__(self, project: Path) -> None:
         self.root = project / ".maggie" / "blog"

package/bundled-tools/runtime/maggie_favicon.py

@@ -0,0 +1,86 @@
+"""Behavioural favicon verification for a deployed origin."""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urljoin, urlparse
+from urllib.request import Request, urlopen
+
+from maggie_social_cards import SUPPORTED_FORMATS, _dimensions
+
+
+SCHEMA = "maggie-favicon.v1"
+
+
+class IconLinkParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.href = ""
+        self.type = ""
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag != "link":
+            return
+        data = dict(attrs)
+        rel = set(str(data.get("rel") or "").lower().split())
+        if rel & {"icon", "shortcut"} and data.get("href") and not self.href:
+            self.href = str(data["href"])
+            self.type = str(data.get("type") or "")
+
+
+def _fetch(url: str, timeout: int) -> tuple[int | None, str, bytes, str | None]:
+    try:
+        request = Request(url, headers={"User-Agent": "Maggie-Favicon-Check/1"})
+        with urlopen(request, timeout=timeout) as response:
+            raw = response.read(8_000_001)
+            if len(raw) > 8_000_000:
+                return int(response.status), response.headers.get_content_type(), b"", "response exceeds size limit"
+            return int(response.status), response.headers.get_content_type(), raw, None
+    except HTTPError as error:
+        return int(error.code), "", b"", "HTTP error"
+    except (URLError, TimeoutError, OSError):
+        return None, "", b"", "request failed"
+
+
+def _resource(url: str, timeout: int) -> dict[str, Any]:
+    status, header_type, raw, fetch_error = _fetch(url, timeout)
+    image_type, width, height = _dimensions(raw, header_type)
+    errors: list[str] = []
+    if fetch_error or status != 200:
+        errors.append(fetch_error or "icon request did not return HTTP 200")
+    if image_type not in SUPPORTED_FORMATS:
+        errors.append("unsupported favicon format")
+    if width is None or height is None:
+        errors.append("favicon dimensions could not be read")
+    elif width != height:
+        errors.append("favicon must be square")
+    return {"url": url, "statusCode": status, "format": image_type, "width": width, "height": height, "errors": errors, "passed": not errors}
+
+
+def check_favicon(origin: str, declared_url: str | None = None, timeout: int = 15) -> dict[str, Any]:
+    parsed = urlparse(origin.rstrip("/"))
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.fragment:
+        raise ValueError("origin must be an absolute HTTP(S) URL without a fragment")
+    if timeout < 1:
+        raise ValueError("timeout must be positive")
+    base = origin.rstrip("/") + "/"
+    favicon_url = urljoin(base, "favicon.ico")
+    detected: str | None = None
+    if not declared_url:
+        status, content_type, raw, _ = _fetch(base, timeout)
+        if status == 200 and content_type == "text/html":
+            parser = IconLinkParser(); parser.feed(raw.decode("utf-8", "replace"))
+            if parser.href:
+                detected = urljoin(base, parser.href)
+    declared = declared_url or detected
+    if declared:
+        declared = urljoin(base, declared)
+        declared_parsed = urlparse(declared)
+        if declared_parsed.scheme not in {"http", "https"} or declared_parsed.fragment:
+            raise ValueError("declared-url must resolve to an absolute HTTP(S) URL without a fragment")
+    ico = _resource(favicon_url, timeout)
+    declared_check = _resource(declared, timeout) if declared and declared != favicon_url else None
+    passed = ico["passed"] and (declared_check is None or declared_check["passed"])
+    return {"schemaVersion": SCHEMA, "origin": origin.rstrip("/"), "favicon": ico, "declaredUrl": declared, "declared": declared_check, "passed": passed, "mutation": False}

package/bundled-tools/runtime/maggie_head_tags.py

@@ -0,0 +1,101 @@
+"""Audit normalized head metadata across rendered shells."""
+
+from __future__ import annotations
+
+import json
+from collections import defaultdict
+from pathlib import Path
+from urllib.parse import urlparse
+from typing import Any
+
+
+SCHEMA = "maggie-head-tags.v1"
+STABLE_TAGS = ("icon", "og:image", "og:image:type", "verification", "robots", "twitter:card")
+
+
+def _extension(value: object) -> str | None:
+    path = urlparse(str(value or "")).path.lower()
+    if "." not in path.rsplit("/", 1)[-1]:
+        return None
+    return "." + path.rsplit("/", 1)[-1].rsplit(".", 1)[-1]
+
+
+def _signature(name: str, value: object, tags: dict[str, Any]) -> dict[str, Any]:
+    """Return only safe, structural metadata; never echo verification values."""
+    if name == "verification":
+        present = bool(value) if not isinstance(value, dict) else bool(value.get("present", value.get("content")))
+        return {"present": present}
+    if name == "icon":
+        data = value if isinstance(value, dict) else {"href": value}
+        return {"present": bool(value), "rel": str(data.get("rel") or "icon"), "type": str(data.get("type") or ""), "extension": _extension(data.get("href"))}
+    if name == "og:image":
+        data = value if isinstance(value, dict) else {"href": value}
+        image_type = data.get("type") or tags.get("og:image:type") or ""
+        return {"present": bool(value), "type": str(image_type), "extension": _extension(data.get("href") or data.get("content") or value), "fallback": bool(data.get("fallback", tags.get("og:image:fallback", False)))}
+    if name == "og:image:type":
+        return {"present": bool(value), "type": str(value or "")}
+    if isinstance(value, dict):
+        return {"present": bool(value), "type": str(value.get("type") or "")}
+    return {"present": bool(value), "value": str(value or "")}
+
+
+def audit_head_tags(pages: list[dict[str, Any]]) -> dict[str, Any]:
+    errors: list[dict[str, str]] = []
+    observations: list[dict[str, Any]] = []
+    for page in pages:
+        if not isinstance(page, dict) or not str(page.get("url") or "").strip():
+            errors.append({"reason": "each page requires a URL"})
+            continue
+        shell = str(page.get("shell") or "").strip()
+        if not shell:
+            errors.append({"url": str(page["url"]), "reason": "each page requires a shell"})
+            continue
+        tags = page.get("tags", {})
+        if not isinstance(tags, dict):
+            errors.append({"url": str(page["url"]), "reason": "tags must be an object"})
+            continue
+        observations.append({"url": str(page["url"]), "shell": shell, "tags": {name: _signature(name, tags.get(name), tags) for name in STABLE_TAGS}})
+
+    by_shell: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for observation in observations:
+        by_shell[observation["shell"]].append(observation)
+    disagreements: list[dict[str, Any]] = []
+
+    def compare(scope: str, label: str, entries: list[tuple[str, dict[str, Any]]]) -> None:
+        for tag in STABLE_TAGS:
+            variants: dict[str, dict[str, Any]] = {}
+            urls: dict[str, list[str]] = defaultdict(list)
+            for identifier, observation in entries:
+                signature = observation["tags"][tag]
+                key = json.dumps(signature, sort_keys=True, separators=(",", ":"))
+                variants[key] = signature
+                urls[key].append(observation["url"])
+            if len(variants) > 1:
+                disagreements.append({"scope": scope, "shell": label if scope == "shell" else None, "tag": tag, "variants": [{"signature": signature, "urls": sorted(urls[key])} for key, signature in sorted(variants.items())]})
+
+    for shell, shell_pages in sorted(by_shell.items()):
+        compare("shell", shell, [(shell, page) for page in shell_pages])
+    for tag in STABLE_TAGS:
+        entries = [(shell, page) for shell, shell_pages in sorted(by_shell.items()) for page in shell_pages]
+        shell_signatures: dict[str, dict[str, Any]] = {}
+        shell_urls: dict[str, list[str]] = defaultdict(list)
+        for shell, page in entries:
+            key = json.dumps(page["tags"][tag], sort_keys=True, separators=(",", ":"))
+            shell_signatures[shell] = page["tags"][tag]
+            shell_urls[key].append(page["url"])
+        unique = {json.dumps(value, sort_keys=True, separators=(",", ":")) for value in shell_signatures.values()}
+        if len(unique) > 1:
+            disagreements.append({"scope": "across-shells", "shell": None, "tag": tag, "variants": [{"signature": shell_signatures[shell], "shell": shell, "urls": sorted(shell_urls[json.dumps(shell_signatures[shell], sort_keys=True, separators=(",", ":"))])} for shell in sorted(shell_signatures)]})
+
+    coverage = []
+    for shell, shell_pages in sorted(by_shell.items()):
+        coverage.append({"shell": shell, "pageCount": len(shell_pages), "tags": {tag: sum(1 for page in shell_pages if page["tags"][tag]["present"]) for tag in STABLE_TAGS}})
+    return {"schemaVersion": SCHEMA, "shells": coverage, "observations": observations, "disagreements": disagreements, "errors": errors, "passed": not errors and not disagreements, "mutation": False}
+
+
+def read_pages(path: Path) -> list[dict[str, Any]]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    pages = value.get("pages") if isinstance(value, dict) else value
+    if not isinstance(pages, list):
+        raise ValueError("pages file must be a JSON array or {\"pages\": []}")
+    return pages

package/bundled-tools/runtime/maggie_indexnow.py

@@ -99,6 +99,56 @@ def check_key_file(public_dir: Path, key_file: str, key: str) -> dict[str, Any]:
             "matches": served == key.strip(), "status": "pass" if served == key.strip() else "fail"}
 
 
+def _public_url(value: str, label: str) -> str:
+    parsed = urlparse(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.fragment:
+        raise ValueError(f"{label} must be an absolute HTTP(S) URL without a fragment")
+    return value
+
+
+def _fetch_key(url: str, expected: str, timeout: int) -> dict[str, Any]:
+    status_code: int | None = None
+    matches = False
+    try:
+        request = Request(url, headers={"User-Agent": "Maggie-IndexNow-Key-Check/1"})
+        with urlopen(request, timeout=timeout) as response:
+            status_code = int(response.status)
+            body = response.read(4097)
+            matches = len(body) <= 4096 and body.decode("utf-8", "replace").strip() == expected
+    except HTTPError as error:
+        status_code = int(error.code)
+    except (URLError, TimeoutError, OSError):
+        pass
+    return {"statusCode": status_code, "matches": matches}
+
+
+def check_key_http(key_url: str, key: str, wrong_key_url: str | None = None,
+                   timeout: int = 15) -> dict[str, Any]:
+    """Verify the deployed key route without exposing its response body."""
+    expected = key.strip()
+    if not expected:
+        raise ValueError("key is required")
+    if timeout < 1:
+        raise ValueError("timeout must be positive")
+    correct_url = _public_url(key_url, "key-url")
+    correct = _fetch_key(correct_url, expected, timeout)
+    result: dict[str, Any] = {
+        "keyUrl": correct_url,
+        "correct": correct,
+        "wrong": None,
+        "status": "pass" if correct["statusCode"] == 200 and correct["matches"] else "fail",
+    }
+    if wrong_key_url:
+        wrong_url = _public_url(wrong_key_url, "wrong-key-url")
+        if wrong_url == correct_url:
+            raise ValueError("wrong-key-url must differ from key-url")
+        wrong = _fetch_key(wrong_url, expected, timeout)
+        result["wrong"] = {"url": wrong_url, **wrong, "is404": wrong["statusCode"] == 404}
+        if not result["wrong"]["is404"]:
+            result["status"] = "fail"
+    return result
+
+
 def submit_plan(plan: dict[str, Any], state: dict[str, Any], endpoint: str) -> dict[str, Any]:
     urls = plan.get("eligible") if isinstance(plan.get("eligible"), list) else []
     if not urls:
@@ -122,7 +172,8 @@ def submit_plan(plan: dict[str, Any], state: dict[str, Any], endpoint: str) -> d
     if accepted:
         stamp = _iso(_now())
         entries.extend({"url": url, "statusCode": status_code, "acceptedAt": stamp, "batchId": hashlib.sha256((stamp + url).encode()).hexdigest()[:12]} for url in urls)
-    state.update({"schemaVersion": SCHEMA, "submissions": entries})
+    if accepted:
+        state.update({"schemaVersion": SCHEMA, "submissions": entries})
     return {"schemaVersion": SCHEMA, "status": "accepted" if accepted else "retryable-failure" if retryable else "failed",
             "submitted": len(urls), "accepted": len(urls) if accepted else 0, "statusCode": status_code,
             "retryable": retryable, "failure": failure, "mutation": True}

package/bundled-tools/runtime/maggie_quality.py

@@ -130,7 +130,12 @@ def classify_inventory(value: object, *, require_page_kinds: bool = False, requi
         if path in seen:
             errors.append(f"duplicate inventory path: {path}")
         seen.add(path)
-        explicit = str(page.get("rendererKind") or page.get("rendering") or page.get("kind") or page.get("classification") or "").casefold()
+        explicit_kind = str(page.get("kind") or "").casefold()
+        # `kind` was historically the renderer field, but the page-kind
+        # vocabulary is also accepted for compact host inventories. In that
+        # case infer the renderer from sections/source and keep the axes apart.
+        renderer_value = page.get("rendererKind") or page.get("rendering") or (None if explicit_kind in PAGE_KINDS else page.get("kind"))
+        explicit = str(renderer_value or page.get("classification") or "").casefold()
         if explicit in {"code", "code-rendered", "component", "source"}:
             kind = "code-rendered"
         elif explicit in {"band", "section", "sections"}:

package/bundled-tools/runtime/maggie_social_cards.py

@@ -0,0 +1,165 @@
+"""Provider-neutral Open Graph social-card inspection."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from html.parser import HTMLParser
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urljoin, urlparse
+from urllib.request import Request, urlopen
+
+
+SCHEMA = "maggie-social-cards.v1"
+MIN_WIDTH = 300
+MIN_HEIGHT = 157
+SUPPORTED_FORMATS = {"image/jpeg", "image/png", "image/gif", "image/x-icon"}
+
+
+class OpenGraphParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.values: dict[str, str] = {}
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag != "meta":
+            return
+        data = dict(attrs)
+        key = (data.get("property") or data.get("name") or "").lower()
+        if key in {"og:image", "og:image:type"} and key not in self.values:
+            self.values[key] = str(data.get("content") or "").strip()
+
+
+def _dimensions(raw: bytes, content_type: str) -> tuple[str | None, int | None, int | None]:
+    """Read dimensions from common headers without an image dependency."""
+    if raw.startswith(b"\x89PNG\r\n\x1a\n") and len(raw) >= 24:
+        return "image/png", int.from_bytes(raw[16:20], "big"), int.from_bytes(raw[20:24], "big")
+    if raw[:3] == b"GIF" and len(raw) >= 10:
+        return "image/gif", int.from_bytes(raw[6:8], "little"), int.from_bytes(raw[8:10], "little")
+    if raw[:4] == b"\x00\x00\x01\x00" and len(raw) >= 22:
+        width = raw[6] or 256
+        height = raw[7] or 256
+        return "image/x-icon", width, height
+    if raw[:2] == b"\xff\xd8":
+        index = 2
+        while index + 9 < len(raw):
+            if raw[index] != 0xFF:
+                index += 1
+                continue
+            marker = raw[index + 1]
+            index += 2
+            if marker in {0xD8, 0xD9}:
+                continue
+            if index + 2 > len(raw):
+                break
+            segment_length = int.from_bytes(raw[index:index + 2], "big")
+            if segment_length < 2 or index + segment_length > len(raw):
+                break
+            if marker in set(range(0xC0, 0xC4)) | set(range(0xC5, 0xC8)) | set(range(0xC9, 0xCC)) | set(range(0xCD, 0xD0)):
+                if segment_length >= 7:
+                    return "image/jpeg", int.from_bytes(raw[index + 5:index + 7], "big"), int.from_bytes(raw[index + 3:index + 5], "big")
+            index += segment_length
+        return "image/jpeg", None, None
+    if raw[:4] == b"RIFF" and raw[8:12] == b"WEBP" and len(raw) >= 30:
+        if raw[12:16] == b"VP8X":
+            width = 1 + int.from_bytes(raw[24:27], "little")
+            height = 1 + int.from_bytes(raw[27:30], "little")
+            return "image/webp", width, height
+        return "image/webp", None, None
+    return (content_type.split(";", 1)[0].lower() or None), None, None
+
+
+def _fetch(url: str, timeout: int, limit: int = 8_000_000) -> tuple[int | None, str, bytes, str | None]:
+    try:
+        request = Request(url, headers={"User-Agent": "Maggie-Social-Card-Audit/1"})
+        with urlopen(request, timeout=timeout) as response:
+            raw = response.read(limit + 1)
+            return int(response.status), response.headers.get_content_type(), raw[:limit], None if len(raw) <= limit else "response exceeds size limit"
+    except HTTPError as error:
+        return int(error.code), "", b"", "HTTP error"
+    except (URLError, TimeoutError, OSError):
+        return None, "", b"", "request failed"
+
+
+def _absolute(value: str, base: str) -> str:
+    candidate = urljoin(base.rstrip("/") + "/", value)
+    parsed = urlparse(candidate)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.fragment:
+        raise ValueError("og:image must resolve to an absolute HTTP(S) URL without a fragment")
+    return candidate
+
+
+def audit_cards(pages: list[dict[str, Any]], *, timeout: int = 15,
+                min_width: int = MIN_WIDTH, min_height: int = MIN_HEIGHT) -> dict[str, Any]:
+    if timeout < 1 or min_width < 1 or min_height < 1:
+        raise ValueError("timeout and image dimensions must be positive")
+    reports: list[dict[str, Any]] = []
+    errors: list[dict[str, str]] = []
+    sources: list[str] = []
+    for page in pages:
+        if not isinstance(page, dict) or not str(page.get("url") or "").strip():
+            errors.append({"reason": "page must contain a URL"})
+            continue
+        page_url = str(page["url"]).strip()
+        image = str(page.get("ogImage") or page.get("og:image") or "").strip()
+        record: dict[str, Any] = {"url": page_url, "ogImage": image or None, "fallback": bool(page.get("fallback", False)), "errors": []}
+        if not image:
+            record["errors"].append("missing og:image")
+            reports.append(record)
+            errors.append({"url": page_url, "reason": "missing og:image"})
+            continue
+        try:
+            image_url = _absolute(image, page_url)
+        except ValueError as exc:
+            record["errors"].append(str(exc))
+            reports.append(record)
+            errors.append({"url": page_url, "reason": str(exc)})
+            continue
+        status, header_type, raw, fetch_error = _fetch(image_url, timeout)
+        image_type, width, height = _dimensions(raw, header_type)
+        record.update({"imageUrl": image_url, "statusCode": status, "format": image_type, "width": width, "height": height})
+        if fetch_error or status != 200:
+            record["errors"].append(fetch_error or "image request did not return HTTP 200")
+        elif image_type not in SUPPORTED_FORMATS:
+            record["errors"].append("unsupported format for large social card")
+        elif width is None or height is None:
+            record["errors"].append("image dimensions could not be read")
+        else:
+            if width < min_width or height < min_height:
+                record["errors"].append(f"image is smaller than {min_width}x{min_height}")
+        reports.append(record)
+        sources.append(image_url)
+        for reason in record["errors"]:
+            errors.append({"url": page_url, "reason": reason})
+
+    warnings: list[dict[str, Any]] = []
+    if len(sources) >= 3:
+        source, count = Counter(sources).most_common(1)[0]
+        if count / len(sources) >= 0.75:
+            warnings.append({"reason": "generic fallback concentration", "imageUrl": source, "count": count, "sampleSize": len(sources), "ratio": round(count / len(sources), 3)})
+    return {"schemaVersion": SCHEMA, "threshold": {"minWidth": min_width, "minHeight": min_height, "supportedFormats": sorted(SUPPORTED_FORMATS)}, "pages": reports, "warnings": warnings, "errors": errors, "passed": not errors, "mutation": False}
+
+
+def pages_from_urls(urls: list[str], timeout: int) -> list[dict[str, Any]]:
+    pages: list[dict[str, Any]] = []
+    for page_url in urls:
+        status, content_type, raw, fetch_error = _fetch(page_url, timeout, 2_000_000)
+        if fetch_error or status != 200 or content_type != "text/html":
+            pages.append({"url": page_url, "ogImage": "", "fetchError": fetch_error or "page request did not return HTML"})
+            continue
+        parser = OpenGraphParser()
+        parser.feed(raw.decode("utf-8", "replace"))
+        pages.append({"url": page_url, "ogImage": parser.values.get("og:image", "")})
+    return pages
+
+
+def read_pages(path: Path) -> list[dict[str, Any]]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    pages = value.get("pages") if isinstance(value, dict) else value
+    if not isinstance(pages, list):
+        raise ValueError("pages file must be a JSON array or {\"pages\": []}")
+    if any(not isinstance(page, dict) for page in pages):
+        raise ValueError("pages file entries must be objects")
+    return pages

package/package.json

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