@topy-ai/maggie 0.7.47 → 0.7.49

package/bundled-tools/clis/maggie_localization.py

@@ -15,6 +15,9 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from content_localization import LANGUAGES, MARKETS, OPERATIONS, parse_locale, protected_field_changes, stale, valid_locale, validate_operation_quality, validate_translation
 from localization_runner import generate, process_adapter
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import maggie_email_localization as email_localization
+
 
 def generate_job(args: argparse.Namespace) -> int:
     if not args.confirm:
@@ -395,6 +398,7 @@ def main() -> int:
     publish_parser.add_argument("job", type=Path); publish_parser.add_argument("--confirm", action="store_true")
     for name in ("stale", "glossary"):
         command = sub.add_parser(name); command.add_argument("--project", type=Path, default=Path("."))
+    email_localization.add_parsers(sub)
     args = parser.parse_args()
     try:
         if args.command == "generate": return generate_job(args)
@@ -406,6 +410,7 @@ def main() -> int:
         if args.command == "review": return review(args.job, args.reviewer, args.decision)
         if args.command == "publish": return publish(args.job, args.confirm)
         if args.command == "stale": return stale_jobs(args.project)
+        if args.command in ("email-matrix", "lifecycle"): return email_localization.run(args)
         return glossary(args.project)
     except (OSError, ValueError, json.JSONDecodeError) as error:
         print(f"ERROR: {error}", file=sys.stderr); return 1

package/bundled-tools/clis/maggie_marketing_run.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""Validate provider-neutral Maggie marketing runs and their named schedule layers.
+
+A marketing run (`maggie-marketing-run-v1`) is one project-scoped record that
+joins content, Social Share, Ads, and measurement work. It references source
+revisions, capability evidence, approvals, mutations, and readbacks by ID; it
+never copies provider secrets or large payloads.
+
+Schedule layers keep four different meanings of "when" apart:
+
+- `infrastructure`: when a worker wakes up (cron, systemd timer, queue);
+  validated by `maggie_schedule.py`.
+- `content_calendar`: when reviewed content or a social post may publish.
+- `campaign_flight`: when paid campaigns may run and spend.
+- `measurement_window`: the data collection and attribution period, including
+  conversion lag.
+
+No function in this module calls a provider, a model, or the network.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import date, datetime
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+SCHEMA_VERSION = "maggie-marketing-run-v1"
+SCHEDULE_LAYERS = {
+    "infrastructure": "Operations: when a worker wakes up (cron/systemd/queue); never a publish time.",
+    "content_calendar": "Editor/marketer: when a reviewed content or social item may publish.",
+    "campaign_flight": "Ads owner: when a paid campaign may run and spend.",
+    "measurement_window": "Analytics: data collection and attribution period, including conversion lag.",
+}
+LAYER_STATUSES = {"planned", "active", "paused", "completed", "cancelled"}
+RUN_MODES = {"draft", "scheduled", "executing", "completed", "cancelled"}
+APPROVAL_STATES = {"pending", "approved", "rejected", "not_required"}
+MUTATION_STATUSES = {"planned", "pending", "succeeded", "failed", "cancelled"}
+MUTATION_KINDS = {"external_publication", "ads_change", "content_delivery", "draft_creation", "configuration"}
+# Workflow stages a regulated-content policy may annotate. Only external
+# publication can be gated by the policy review; everything else continues.
+STAGES = ("delivery", "draft", "seo_geo", "measurement", "external_publication")
+POLICY_GATED_STAGES = {"external_publication"}
+REVIEW_STATES = {"not_required", "pending", "approved", "rejected"}
+SECRET_KEY = re.compile(r"(?:^|_)(?:secret|token|password|api_?key|authorization|cookie)s?$", re.I)
+SECRET_VALUE = re.compile(r"^(?:Bearer\s|sk_(?:live|test)_|ya29\.|AIza)", re.I)
+RUN_ID = re.compile(r"^[a-z0-9][a-z0-9._-]{2,127}$")
+
+
+def _day(value: object) -> date | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).date() if "T" in value else date.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def _zone(value: object) -> bool:
+    if not isinstance(value, str) or not value:
+        return False
+    try:
+        ZoneInfo(value)
+    except (ZoneInfoNotFoundError, ValueError):
+        return False
+    return True
+
+
+def _secrets(value: object, path: str, found: list[str]) -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if SECRET_KEY.search(str(key)) and not str(key).endswith(("_ref", "Ref")):
+                found.append(f"{path}.{key}")
+            _secrets(item, f"{path}.{key}", found)
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _secrets(item, f"{path}[{index}]", found)
+    elif isinstance(value, str) and SECRET_VALUE.search(value):
+        found.append(path)
+
+
+def validate_layers(layers: object, *, label: str = "scheduleLayers") -> tuple[list[str], list[str]]:
+    """Validate named schedule layers shared by maggie-schedule, Social Share, Ads, and analytics."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    if not isinstance(layers, list) or not layers:
+        return [f"{label} must be a non-empty list"], warnings
+    seen: set[tuple[str, str]] = set()
+    for index, layer in enumerate(layers):
+        prefix = f"{label}[{index}]"
+        if not isinstance(layer, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        name = layer.get("layer")
+        if name not in SCHEDULE_LAYERS:
+            errors.append(f"{prefix}.layer must be one of {', '.join(SCHEDULE_LAYERS)}")
+            continue
+        key = (name, str(layer.get("id") or ""))
+        if key in seen:
+            errors.append(f"{prefix} duplicates layer {name} id {key[1] or '(none)'}")
+        seen.add(key)
+        if not _zone(layer.get("timezone")):
+            errors.append(f"{prefix}.timezone must be an IANA time zone")
+        for field in ("owner", "reconciliation"):
+            if not isinstance(layer.get(field), str) or not layer[field].strip():
+                errors.append(f"{prefix}.{field} is required")
+        if layer.get("status") not in LAYER_STATUSES:
+            errors.append(f"{prefix}.status must be one of {', '.join(sorted(LAYER_STATUSES))}")
+        if name == "infrastructure":
+            if not layer.get("scheduleRef"):
+                errors.append(f"{prefix}.scheduleRef must point at the maggie-schedule job (infrastructure has no publish time)")
+            if "start" in layer or "end" in layer:
+                warnings.append(f"{prefix} infrastructure layers describe wake-up intervals; start/end are ignored")
+            continue
+        start, end = _day(layer.get("start")), _day(layer.get("end"))
+        if not start:
+            errors.append(f"{prefix}.start must be an ISO date or date-time")
+        if name != "content_calendar" and not end:
+            errors.append(f"{prefix}.end is required for {name}")
+        if start and end and end < start:
+            errors.append(f"{prefix}.end is before start")
+        if name == "measurement_window" and not isinstance(layer.get("lagDays"), int):
+            warnings.append(f"{prefix}.lagDays is not set; attribution lag will be ignored")
+    return errors, warnings
+
+
+def validate_policy(policy: object, stages: object, mutations: list) -> tuple[list[str], list[str]]:
+    """Regulated-content review gates only external publication (default off, backward compatible)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    if policy is None:
+        policy = {}
+    if not isinstance(policy, dict):
+        return ["policy must be an object"], warnings
+    required = bool(policy.get("regulatedContent") and policy.get("reviewRequired", True))
+    review = policy.get("reviewState", "pending" if required else "not_required")
+    if review not in REVIEW_STATES:
+        errors.append(f"policy.reviewState must be one of {', '.join(sorted(REVIEW_STATES))}")
+    if isinstance(stages, dict):
+        for stage, state in stages.items():
+            if stage not in STAGES:
+                errors.append(f"stages.{stage} is not a known stage ({', '.join(STAGES)})")
+                continue
+            blocked = isinstance(state, dict) and state.get("status") == "blocked" and state.get("reason") == "policy_review"
+            if blocked and stage not in POLICY_GATED_STAGES:
+                errors.append(f"stages.{stage} is blocked by policy review; regulated-content review may only gate "
+                              "external publication — delivery, drafts, SEO/GEO and measurement must continue")
+    elif stages is not None:
+        errors.append("stages must be an object keyed by stage")
+    if required and review != "approved":
+        for mutation in mutations:
+            if isinstance(mutation, dict) and mutation.get("kind") == "external_publication" and mutation.get("status") in {"pending", "succeeded"}:
+                errors.append(f"mutation {mutation.get('mutationId')} publishes regulated content before policy review is approved")
+        if review == "pending":
+            warnings.append("regulated-content review is pending; external publication stays held, other stages continue")
+    return errors, warnings
+
+
+def validate_run(run: object) -> dict:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if not isinstance(run, dict):
+        return {"valid": False, "errors": ["marketing run must be a JSON object"], "warnings": []}
+    if run.get("schemaVersion") != SCHEMA_VERSION:
+        errors.append(f"schemaVersion must be {SCHEMA_VERSION}")
+    if not isinstance(run.get("runId"), str) or not RUN_ID.match(run["runId"]):
+        errors.append("runId must be a lowercase slug (3-128 chars)")
+    for field in ("projectRef", "objective"):
+        if not isinstance(run.get(field), str) or not run[field].strip():
+            errors.append(f"{field} is required")
+    conversion = run.get("conversion")
+    if not isinstance(conversion, dict) or not conversion.get("event") or not conversion.get("source"):
+        errors.append("conversion needs event and source")
+    channels = run.get("channels")
+    if not isinstance(channels, list) or not channels or not all(isinstance(item, str) and item for item in channels):
+        errors.append("channels must be a non-empty list of channel names")
+    if not _zone(run.get("timezone")):
+        errors.append("timezone must be an IANA time zone")
+    if run.get("mode") not in RUN_MODES:
+        errors.append(f"mode must be one of {', '.join(sorted(RUN_MODES))}")
+    if "scheduled_at" in run or "scheduledAt" in run:
+        errors.append("a run must not carry a single scheduled_at; use named scheduleLayers")
+    for index, revision in enumerate(run.get("sourceRevisions") or []):
+        if not isinstance(revision, dict) or not revision.get("sourceId") or not revision.get("revision"):
+            errors.append(f"sourceRevisions[{index}] needs sourceId and revision")
+    for index, ref in enumerate(run.get("capabilityEvidence") or []):
+        if not isinstance(ref, str) or not ref:
+            errors.append(f"capabilityEvidence[{index}] must be an evidence ID or path reference")
+    approval = run.get("approval")
+    if not isinstance(approval, dict) or approval.get("state") not in APPROVAL_STATES:
+        errors.append(f"approval.state must be one of {', '.join(sorted(APPROVAL_STATES))}")
+        approval = {}
+    if approval.get("state") == "approved" and not (approval.get("actor") and approval.get("approvalId")):
+        errors.append("an approved run needs approval.actor and approval.approvalId")
+    layer_errors, layer_warnings = validate_layers(run.get("scheduleLayers"))
+    errors += layer_errors
+    warnings += layer_warnings
+    mutations = run.get("mutations") or []
+    if not isinstance(mutations, list):
+        errors.append("mutations must be a list")
+        mutations = []
+    mutation_ids: set[str] = set()
+    for index, mutation in enumerate(mutations):
+        prefix = f"mutations[{index}]"
+        if not isinstance(mutation, dict) or not mutation.get("mutationId"):
+            errors.append(f"{prefix} needs mutationId")
+            continue
+        mutation_ids.add(mutation["mutationId"])
+        if mutation.get("kind") not in MUTATION_KINDS:
+            errors.append(f"{prefix}.kind must be one of {', '.join(sorted(MUTATION_KINDS))}")
+        if mutation.get("status") not in MUTATION_STATUSES:
+            errors.append(f"{prefix}.status must be one of {', '.join(sorted(MUTATION_STATUSES))}")
+        if mutation.get("kind") in {"external_publication", "ads_change"}:
+            if not mutation.get("idempotencyKey"):
+                errors.append(f"{prefix} external mutation needs an idempotencyKey")
+            if mutation.get("status") in {"pending", "succeeded"} and approval.get("state") != "approved":
+                errors.append(f"{prefix} executed before the run was approved")
+    readback_refs = set()
+    for index, readback in enumerate(run.get("readbacks") or []):
+        if not isinstance(readback, dict) or not readback.get("readbackId"):
+            errors.append(f"readbacks[{index}] needs readbackId")
+            continue
+        ref = readback.get("mutationRef")
+        if ref and ref not in mutation_ids:
+            errors.append(f"readbacks[{index}].mutationRef {ref} does not match a mutation")
+        readback_refs.add(ref)
+    for mutation in mutations:
+        if isinstance(mutation, dict) and mutation.get("status") == "succeeded" and mutation.get("mutationId") not in readback_refs:
+            message = f"mutation {mutation.get('mutationId')} succeeded without a readback reference"
+            (errors if run.get("mode") == "completed" else warnings).append(message)
+    policy_errors, policy_warnings = validate_policy(run.get("policy"), run.get("stages"), mutations)
+    errors += policy_errors
+    warnings += policy_warnings
+    leaked: list[str] = []
+    _secrets(run, "run", leaked)
+    if leaked:
+        errors.append("run must reference secrets, not contain them: " + ", ".join(leaked))
+    return {"valid": not errors, "errors": errors, "warnings": warnings,
+            "runId": run.get("runId"), "layers": sorted({layer.get("layer") for layer in run.get("scheduleLayers") or [] if isinstance(layer, dict)} - {None})}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    check = sub.add_parser("validate", help="validate a maggie-marketing-run-v1 document")
+    check.add_argument("input")
+    layers = sub.add_parser("layers", help="validate a scheduleLayers list, or print the layer model with no input")
+    layers.add_argument("input", nargs="?")
+    args = parser.parse_args()
+    try:
+        if args.command == "layers" and not args.input:
+            print(json.dumps({"layers": SCHEDULE_LAYERS}, indent=2))
+            return 0
+        value = json.loads(Path(args.input).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        parser.error(str(error))
+        return 2
+    if args.command == "validate":
+        result = validate_run(value)
+    else:
+        items = value.get("scheduleLayers") if isinstance(value, dict) else value
+        errors, warnings = validate_layers(items)
+        result = {"valid": not errors, "errors": errors, "warnings": warnings}
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if result["valid"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_marketplace.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
+import os
 import re
 import shutil
 import subprocess
@@ -17,6 +18,9 @@ from html.parser import HTMLParser
 from html import escape, unescape
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import maggie_template_package as package  # noqa: E402
+
 
 ID_PATTERN = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
 REQUIRED_METADATA = ("id", "name", "status", "framework", "industry", "source")
@@ -382,7 +386,7 @@ def catalog_entries(root: Path) -> list[dict]:
 
 def update_catalog(root: Path, metadata: dict) -> None:
     entries = [item for item in catalog_entries(root) if item.get("id") != metadata.get("id")]
-    entries.append({key: metadata[key] for key in ("id", "name", "status", "framework", "industry", "pageTypes", "styleTags", "source", "supports") if key in metadata})
+    entries.append({key: metadata[key] for key in ("id", "name", "displayName", "displayDescription", "status", "framework", "industry", "pageTypes", "styleTags", "source", "supports") if key in metadata})
     entries.sort(key=lambda item: item.get("id", ""))
     save_catalog(root, entries)
 
@@ -1185,6 +1189,8 @@ header:first-of-type a[class*="border-white"], #home a[class*="border-white"] {
     metadata["generatedAssets"] = {"logo": generated[0]["path"], "hero": generated[1]["path"], "careTeam": generated[2]["path"], "provider": "maggie-marketplace-pipeline", "generatedAt": now()}
     metadata["sourceMetadata"]["description"] = description
     write_json(destination / "template.json", metadata)
+    finalise_package_identity(root, destination, getattr(args, "display_name", None), getattr(args, "display_description", None))
+    metadata = read_json(destination / "template.json")
     (destination / "README.md").write_text(f"# {metadata['name']}\n\nA UK-localised Astro homepage template derived from {display_name}. Includes clone evidence, responsive screenshots, locally mapped assets, SEO metadata, Phosphor icons, and a DESIGN.md contract.\n\nThis entry remains a draft until source reuse and asset licensing are reviewed.\n", encoding="utf-8")
     cleanup_template_assets(destination)
     scrub_local_export_references(destination, args.preview_url)
@@ -1192,6 +1198,29 @@ header:first-of-type a[class*="border-white"], #home a[class*="border-white"] {
     update_catalog(root, read_json(destination / "template.json"))
 
 
+def finalise_package_identity(root: Path, destination: Path, display_name: str | None = None, display_description: str | None = None, rewrite_design: bool = True) -> dict:
+    """Measure design tokens, record a neutral display identity, and review screenshots."""
+    metadata = read_json(destination / "template.json")
+    measured = package.measure_design_tokens((destination / "homepage.html").read_text(encoding="utf-8", errors="replace"))
+    if rewrite_design and (destination / "DESIGN.md").exists():
+        package.write_measured_design(destination, measured)
+    metadata["designTokens"] = {"palette": measured["roles"], "textSecondary": measured.get("textSecondary"), "border": measured["border"],
+                                "fonts": {key: measured["fonts"][key] for key in ("display", "body", "missingFontLinks")}, "measuredFrom": "homepage.html", "measuredAt": now()}
+    if not metadata.get("styleTags"):
+        metadata["styleTags"] = package.derived_style_tags(measured)
+    taken = {str(entry.get("displayName", "")).lower() for entry in catalog_entries(root) if entry.get("id") != metadata.get("id")}
+    if display_name or not metadata.get("displayName"):
+        identity = package.generate_display_identity(metadata, measured, taken)
+        metadata["displayName"] = display_name or identity["displayName"]
+        metadata["displayDescription"] = display_description or (metadata.get("displayDescription") if display_name else None) or identity["displayDescription"]
+    elif display_description:
+        metadata["displayDescription"] = display_description
+    metadata["screenshotReview"] = package.screenshot_report(destination)
+    write_json(destination / "template.json", metadata)
+    update_catalog(root, metadata)
+    return metadata
+
+
 def standardize_phosphor_icons(value: str) -> tuple[str, list[dict]]:
     """Inventory source icon semantics, then replace each with a Phosphor class."""
     mapping = {
@@ -1676,7 +1705,12 @@ def audit_image_replacements(path: Path) -> list[str]:
         Path(src.split("?", 1)[0]).name
         for src in re.findall(r"assets/[^\s,\"'?#]+", value, re.I)
     }
-    leaked = sorted(path_name for path_name in source_paths if path_name in homepage_paths)
+    # repair-assets may add a sniffed suffix to an extensionless capture, so a
+    # suffix-less source name also matches its renamed `<name>.<ext>` file.
+    renamed = {Path(name).stem: name for name in homepage_paths if Path(name).suffix}
+    leaked = sorted({path_name if path_name in homepage_paths else renamed[path_name]
+                     for path_name in source_paths
+                     if path_name in homepage_paths or (not Path(path_name).suffix and path_name in renamed)})
     errors = [f"homepage still references captured source image: assets/{name}" for name in leaked]
     generated_assets = [
         item for item in generated_manifest.get("assets", [])
@@ -1834,6 +1868,7 @@ def marketplace_artifact_gate(destination: Path, require_generated_assets: bool
         errors.extend(audit_visual_contrast(destination))
         errors.extend(audit_mobile_navigation(destination))
         errors.extend(audit_image_replacements(destination))
+        errors.extend(package_quality_errors(destination))
         update_template_tasks(destination, "COMPLETED")
         try:
             task_state = read_json(destination / "tasks.json")
@@ -1974,6 +2009,16 @@ def resume_marketplace_job(args: argparse.Namespace) -> int:
     return run_marketplace_job(resumed)
 
 
+def package_quality_errors(path: Path) -> list[str]:
+    """Screenshot, measured-palette, provenance, identity, and image-review gates."""
+    try:
+        catalog = catalog_entries(path.parent.parent)
+    except ValueError:
+        catalog = []
+    report = package.package_audit(path, catalog)
+    return [error for group in report["checks"].values() for error in group]
+
+
 def validate_template(path: Path, sample: Path | None = None) -> int:
     normalise_phosphor_template(path)
     cleanup_template_assets(path)
@@ -1991,6 +2036,7 @@ def validate_template(path: Path, sample: Path | None = None) -> int:
     errors.extend(audit_visual_contrast(path))
     errors.extend(audit_mobile_navigation(path))
     errors.extend(audit_image_replacements(path))
+    errors.extend(package_quality_errors(path))
     if not metadata_path.exists():
         errors.append("missing template.json")
         metadata = {}
@@ -2136,7 +2182,7 @@ def list_templates(args: argparse.Namespace) -> int:
     if args.published:
         entries = [entry for entry in entries if entry.get("status") in PUBLISHED_STATUSES]
     for entry in entries:
-        print(f"{entry.get('id')}\t{entry.get('status', 'unknown')}\t{', '.join(entry.get('industry', []))}\t{', '.join(entry.get('styleTags', []))}")
+        print(f"{entry.get('id')}\t{entry.get('displayName') or '(display name missing)'}\t{entry.get('status', 'unknown')}\t{', '.join(entry.get('industry', []))}\t{', '.join(entry.get('styleTags', []))}")
     return 0
 
 
@@ -2157,7 +2203,7 @@ def suggest_templates(args: argparse.Namespace) -> int:
     ranked = []
     for entry in catalog_entries(marketplace_root(args.marketplace)):
         haystack = set(re.findall(r"[a-z0-9]+", " ".join([
-            str(entry.get("name", "")), " ".join(entry.get("industry", [])),
+            str(entry.get("displayName", "")), str(entry.get("displayDescription", "")), " ".join(entry.get("industry", [])),
             " ".join(entry.get("styleTags", [])), " ".join(entry.get("pageTypes", [])),
         ]).lower()))
         score = len(query & haystack)
@@ -2166,7 +2212,7 @@ def suggest_templates(args: argparse.Namespace) -> int:
         ranked.append((score, entry))
     ranked.sort(key=lambda item: (-item[0], item[1].get("id", "")))
     for score, entry in ranked[:args.limit]:
-        print(f"{score}\t{entry.get('id')}\t{entry.get('status', 'unknown')}\t{', '.join(entry.get('industry', []))}\t{', '.join(entry.get('styleTags', []))}")
+        print(f"{score}\t{entry.get('id')}\t{entry.get('displayName') or '(display name missing)'}\t{entry.get('status', 'unknown')}\t{', '.join(entry.get('industry', []))}\t{', '.join(entry.get('styleTags', []))}")
     return 0
 
 
@@ -2235,6 +2281,107 @@ def enrichment_report(args: argparse.Namespace) -> int:
     print(json.dumps({"status": report["status"], "candidateId": candidate_id, "report": str(output), "retry": report["retry"]}, ensure_ascii=False)); return 0 if not errors else 1
 
 
+def _template_dir(args: argparse.Namespace) -> tuple[Path, Path]:
+    root = marketplace_root(args.marketplace)
+    source = template_path(root, args.id)
+    if not (source / "template.json").is_file():
+        raise ValueError(f"template not found: {args.id}")
+    return root, source
+
+
+def audit_package(args: argparse.Namespace) -> int:
+    """Read-only package-quality audit; --record stores the screenshot review."""
+    root, source = _template_dir(args)
+    report = package.package_audit(source, catalog_entries(root))
+    if args.record:
+        metadata = read_json(source / "template.json")
+        metadata["screenshotReview"] = package.screenshot_report(source)
+        if args.recapture_note:
+            metadata["screenshotReview"]["note"] = args.recapture_note
+        write_json(source / "template.json", metadata)
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+def measure_design(args: argparse.Namespace) -> int:
+    root, source = _template_dir(args)
+    measured = package.measure_design_tokens((source / "homepage.html").read_text(encoding="utf-8", errors="replace"))
+    if args.palette_roles:
+        palettes = package.load_palettes(None, measured, read_json(source / "template.json").get("id"))
+        args.palette_roles.parent.mkdir(parents=True, exist_ok=True)
+        args.palette_roles.write_text(json.dumps(palettes, indent=2) + "\n", encoding="utf-8")
+    if args.write:
+        finalise_package_identity(root, source, rewrite_design=True)
+    print(json.dumps({key: measured[key] for key in ("roles", "textSecondary", "border", "fonts")}, indent=2, ensure_ascii=False))
+    return 0
+
+
+def repair_assets(args: argparse.Namespace) -> int:
+    _, source = _template_dir(args)
+    result = package.repair_asset_provenance(source, write=args.write)
+    print(json.dumps({"write": args.write, **result}, indent=2, ensure_ascii=False))
+    return 0
+
+
+def set_identity(args: argparse.Namespace) -> int:
+    root, source = _template_dir(args)
+    metadata = finalise_package_identity(root, source, args.display_name, args.display_description, rewrite_design=False)
+    errors = package.audit_display_identity(source, catalog_entries(root))
+    print(json.dumps({"displayName": metadata.get("displayName"), "displayDescription": metadata.get("displayDescription"), "errors": errors}, indent=2, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+def template_studio(args: argparse.Namespace) -> int:
+    root, source = _template_dir(args)
+    measured = package.measure_design_tokens((source / "homepage.html").read_text(encoding="utf-8", errors="replace"))
+    palettes = package.load_palettes(args.palettes.resolve() if args.palettes else None, measured, args.id)
+    output = (args.output or root / ".maggie" / "template-studio" / args.id).resolve()
+    result = package.build_studio(source, output, palettes)
+    if args.check_overflow:
+        serve_root = Path(os.path.commonpath([str(output), str(source.resolve())]))
+        report = package.check_studio_overflow(serve_root, output / "index.html", palette_id=args.palette)
+        result["overflow"] = report
+        _write = output / "overflow-report.json"
+        _write.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
+        failing = {width: item for width, item in (report.get("viewports") or {}).items() if item.get("overflowPx")}
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 1 if failing or report.get("error") or not report.get("viewports") else 0
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    print("Serve the common parent over HTTP (python3 -m http.server) to preview; --check-overflow renders it headlessly.")
+    return 0
+
+
+def content_validate(args: argparse.Namespace) -> int:
+    content = read_json(args.input.resolve())
+    errors = package.validate_content(content)
+    print(json.dumps({"status": "passed" if not errors else "failed", "errors": errors}, indent=2))
+    return 0 if not errors else 1
+
+
+def content_css(args: argparse.Namespace) -> int:
+    content = read_json(args.input.resolve())
+    roles = (content.get("palette") or {}).get("roles") or {}
+    if not roles:
+        raise ValueError("content has no palette.roles to export")
+    print(package.palette_css_variables(roles), end="")
+    return 0
+
+
+def image_plan(args: argparse.Namespace) -> int:
+    _, source = _template_dir(args)
+    report = package.plan_image_generation(source, args.unit_cost, args.currency, args.provider)
+    print(json.dumps(report["before"], indent=2))
+    return 0
+
+
+def image_review(args: argparse.Namespace) -> int:
+    _, source = _template_dir(args)
+    report = package.review_generated_images(source, approve=args.approve, reviewer=args.reviewer or "", flags=args.flag, note=args.note or "")
+    summary = {"after": report["after"], "textReview": {key: report["textReview"][key] for key in ("status", "method", "contactSheet")}}
+    print(json.dumps(summary, indent=2))
+    return 0 if report["textReview"]["status"] == "passed" else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--marketplace", type=Path, default=Path("marketplace"))
@@ -2269,6 +2416,8 @@ def main() -> int:
     add.add_argument("--languages", action="append", default=["en"])
     add.add_argument("--translation-policy", choices=("source-only", "review-required", "fully-localized"), default="review-required")
     add.add_argument("--brand", default="Maggie Studio", help="neutral demo brand used by the completion pipeline")
+    add.add_argument("--display-name", help="neutral customer-facing style name (default: generated from measured design)")
+    add.add_argument("--display-description", help="short neutral description shown in template pickers")
     add.add_argument("--site-url", help="final canonical site URL; defaults to an example.co.uk URL")
     add.add_argument("--sample", type=Path)
     add.add_argument("--force", action="store_true")
@@ -2319,6 +2468,51 @@ def main() -> int:
     enrichment.add_argument("--input", type=Path, required=True)
     enrichment.add_argument("--output", type=Path)
     enrichment.set_defaults(func=enrichment_report)
+    audit = sub.add_parser("audit-package", help="read-only screenshot, palette, provenance, identity, and image-review audit")
+    audit.add_argument("id")
+    audit.add_argument("--record", action="store_true", help="store the screenshot review in template.json")
+    audit.add_argument("--recapture-note")
+    audit.set_defaults(func=audit_package)
+    measure = sub.add_parser("measure-design", help="measure palette roles and fonts from homepage CSS")
+    measure.add_argument("id")
+    measure.add_argument("--write", action="store_true", help="rewrite DESIGN.md palette/typography and template.json designTokens")
+    measure.add_argument("--palette-roles", type=Path, help="write the measured signature as maggie-palette-roles-v1 JSON")
+    measure.set_defaults(func=measure_design)
+    repair = sub.add_parser("repair-assets", help="list unlisted assets with honest provenance; add missing file extensions")
+    repair.add_argument("id")
+    repair.add_argument("--write", action="store_true")
+    repair.set_defaults(func=repair_assets)
+    identity = sub.add_parser("identity", help="record a neutral, unique displayName and description")
+    identity.add_argument("id")
+    identity.add_argument("--display-name")
+    identity.add_argument("--display-description")
+    identity.set_defaults(func=set_identity)
+    studio = sub.add_parser("studio", help="build a template x palette x viewport preview studio")
+    studio.add_argument("id")
+    studio.add_argument("--palettes", type=Path, help="maggie-palette-roles-v1 JSON (default: measured signature only)")
+    studio.add_argument("--output", type=Path)
+    studio.add_argument("--check-overflow", action="store_true", help="render headlessly and fail on horizontal overflow")
+    studio.add_argument("--palette", help="palette id to render for --check-overflow (default: signature)")
+    studio.set_defaults(func=template_studio)
+    cvalidate = sub.add_parser("content-validate", help="validate maggie-template-content-v1 JSON")
+    cvalidate.add_argument("--input", type=Path, required=True)
+    cvalidate.set_defaults(func=content_validate)
+    ccss = sub.add_parser("content-css", help="print palette CSS variables for template content")
+    ccss.add_argument("--input", type=Path, required=True)
+    ccss.set_defaults(func=content_css)
+    iplan = sub.add_parser("image-plan", help="record planned image count and estimated cost before generation")
+    iplan.add_argument("id")
+    iplan.add_argument("--unit-cost", type=float)
+    iplan.add_argument("--currency", default="USD")
+    iplan.add_argument("--provider", default="built-in-image-generation")
+    iplan.set_defaults(func=image_plan)
+    ireview = sub.add_parser("image-review", help="contact sheet, OCR/human no-text review, and post-run cost")
+    ireview.add_argument("id")
+    ireview.add_argument("--approve", action="store_true", help="record a human review that found no text, labels, or watermarks")
+    ireview.add_argument("--reviewer")
+    ireview.add_argument("--flag", action="append", default=[], help="asset path with readable text; repeatable")
+    ireview.add_argument("--note")
+    ireview.set_defaults(func=image_review)
     args = parser.parse_args()
     try:
         return int(args.func(args) or 0)