@topy-ai/maggie 0.7.46 → 0.7.48

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)

package/bundled-tools/clis/maggie_memory.py

@@ -35,12 +35,15 @@ def main() -> int:
     listing.add_argument("--status", choices=sorted(memory.STATUSES), default=None)
     listing.add_argument("--skill", default="")
     listing.add_argument("--query", default="")
+    listing.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     search = add_project(sub.add_parser("search"))
     search.add_argument("query")
     search.add_argument("--skill", default="")
+    search.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     context = add_project(sub.add_parser("context"))
     context.add_argument("--skill", default="")
     context.add_argument("--query", default="")
+    context.add_argument("--include-shared", action="store_true", help="explicitly include user/workspace memory entries")
     add = add_project(sub.add_parser("add"))
     add.add_argument("kind", choices=("preferences", "conventions", "lessons"))
     add.add_argument("--scope", choices=sorted(memory.SCOPES), required=True)
@@ -85,17 +88,21 @@ def main() -> int:
             output(memory.transition(args.project, args.kind, args.item_id, args.status))
         elif args.command in {"context", "search", "list"}:
             query = args.query if args.command == "search" else getattr(args, "query", "")
-            result = memory.relevant(args.project, skill=getattr(args, "skill", ""), query=query, status=getattr(args, "status", None))
+            result = memory.relevant(args.project, skill=getattr(args, "skill", ""), query=query, status=getattr(args, "status", None), include_shared=getattr(args, "include_shared", False))
             if args.command == "list" and args.kind:
                 result = {args.kind: result[args.kind]}
             if args.command == "list" and args.status:
                 result = {kind: [item for item in items if item.get("status") == args.status] for kind, items in result.items()}
-            output(result)
+            if args.command == "context":
+                ready = memory.initialized(args.project)
+                output({"status": "ready" if ready else "uninitialized", "initialized": ready, **result})
+            else:
+                output(result)
         elif args.command == "export":
             payload = {kind: memory.read(args.project, kind) for kind in memory.KINDS if kind != "errors"}
             if args.public_safe:
                 for value in payload.values():
-                    value["items"] = [item for item in value["items"] if item.get("scope") != "user" and item.get("status") == "active"]
+                    value["items"] = [item for item in value["items"] if item.get("scope") == "project" and item.get("status") == "active"]
             destination = Path(args.output)
             destination.parent.mkdir(parents=True, exist_ok=True)
             destination.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")

package/bundled-tools/clis/maggie_palette.py

@@ -0,0 +1,280 @@
+#!/usr/bin/env python3
+"""Generate and validate a semantic palette role contract for a template.
+
+A template exposes colour roles instead of raw hex values in markup. The
+signature palette is the template's own; variants are derived from it by
+moving hue while keeping lightness, capping accent saturation, and forcing
+the contrast rules that make the roles safe to swap without editing markup.
+The command is deterministic and makes no network or model calls.
+"""
+
+from __future__ import annotations
+
+import argparse
+import colorsys
+import json
+import re
+import sys
+from pathlib import Path
+
+SCHEMA_VERSION = "maggie-palette-roles-v1"
+ROLES = ("canvas", "panel", "soft", "text", "accent", "accentText", "onAccent", "dark", "deep")
+HEX = re.compile(r"^#[0-9A-Fa-f]{6}$")
+MIN_TEXT_CONTRAST = 4.5
+DEFAULT_MAX_SATURATION = 0.65
+DEFAULT_VARIANT_COUNT = 17
+MIN_HUE_DISTANCE = 15.0
+
+# Named hue anchors used for variants. Order is the output order.
+HUE_ANCHORS = (
+    ("rose", "Rose", 350), ("coral", "Coral", 10), ("terracotta", "Terracotta", 20),
+    ("amber", "Amber", 36), ("ochre", "Ochre", 45), ("olive", "Olive", 65),
+    ("moss", "Moss", 90), ("sage", "Sage", 130), ("jade", "Jade", 155),
+    ("teal", "Teal", 178), ("lagoon", "Lagoon", 190), ("ocean", "Ocean", 205),
+    ("cobalt", "Cobalt", 220), ("indigo", "Indigo", 240), ("iris", "Iris", 258),
+    ("violet", "Violet", 275), ("plum", "Plum", 300), ("orchid", "Orchid", 322),
+)
+
+
+def parse_hex(value: str) -> tuple[float, float, float]:
+    if not isinstance(value, str) or not HEX.match(value):
+        raise ValueError(f"colour must be #RRGGBB: {value!r}")
+    return tuple(int(value[index:index + 2], 16) / 255 for index in (1, 3, 5))  # type: ignore[return-value]
+
+
+def to_hex(rgb: tuple[float, float, float]) -> str:
+    return "#" + "".join(f"{round(max(0.0, min(1.0, channel)) * 255):02X}" for channel in rgb)
+
+
+def to_hsl(value: str) -> tuple[float, float, float]:
+    hue, lightness, saturation = colorsys.rgb_to_hls(*parse_hex(value))
+    return hue * 360, saturation, lightness
+
+
+def from_hsl(hue: float, saturation: float, lightness: float) -> str:
+    return to_hex(colorsys.hls_to_rgb((hue % 360) / 360, max(0.0, min(1.0, lightness)), max(0.0, min(1.0, saturation))))
+
+
+def luminance(value: str) -> float:
+    def linear(channel: float) -> float:
+        return channel / 12.92 if channel <= 0.03928 else ((channel + 0.055) / 1.055) ** 2.4
+    red, green, blue = (linear(channel) for channel in parse_hex(value))
+    return 0.2126 * red + 0.7152 * green + 0.0722 * blue
+
+
+def contrast(first: str, second: str) -> float:
+    high, low = sorted((luminance(first), luminance(second)), reverse=True)
+    return (high + 0.05) / (low + 0.05)
+
+
+def hue_distance(first: float, second: float) -> float:
+    delta = abs(first - second) % 360
+    return min(delta, 360 - delta)
+
+
+def mix(first: str, second: str, amount: float) -> str:
+    a, b = parse_hex(first), parse_hex(second)
+    return to_hex(tuple(x + (y - x) * amount for x, y in zip(a, b)))  # type: ignore[arg-type]
+
+
+def ensure_contrast(colour: str, background: str, minimum: float = MIN_TEXT_CONTRAST) -> str:
+    """Move only lightness, away from the background, until contrast passes."""
+    if contrast(colour, background) >= minimum:
+        return colour
+    hue, saturation, lightness = to_hsl(colour)
+    step = -0.01 if luminance(background) > 0.18 else 0.01
+    candidate = colour
+    for _ in range(101):
+        lightness = max(0.0, min(1.0, lightness + step))
+        candidate = from_hsl(hue, saturation, lightness)
+        if contrast(candidate, background) >= minimum:
+            return candidate
+    return candidate
+
+
+def pick_on_accent(accent: str, candidates: list[str]) -> str:
+    return max(candidates, key=lambda candidate: (round(contrast(candidate, accent), 4), candidate))
+
+
+def complete_roles(roles: dict[str, str]) -> dict[str, str]:
+    """Fill derived roles for a signature; supplied roles are never changed."""
+    missing = [name for name in ("canvas", "text", "accent") if not roles.get(name)]
+    if missing:
+        raise ValueError("signature needs canvas, text and accent; missing " + ", ".join(missing))
+    for name, value in roles.items():
+        if name not in ROLES:
+            raise ValueError(f"unknown palette role: {name}")
+        parse_hex(value)
+    filled = {name: roles[name].upper() for name in roles}
+    canvas, text, accent = filled["canvas"], filled["text"], filled["accent"]
+    filled.setdefault("panel", mix(canvas, text, 0.04))
+    filled.setdefault("soft", mix(canvas, accent, 0.12))
+    # The dark band is the text colour on light canvases and a deeper canvas on dark ones.
+    if luminance(canvas) > 0.18:
+        filled.setdefault("dark", text)
+    else:
+        canvas_hue, canvas_saturation, canvas_lightness = to_hsl(canvas)
+        filled.setdefault("dark", from_hsl(canvas_hue, canvas_saturation, canvas_lightness * 0.8))
+    deep_hue, deep_saturation, deep_lightness = to_hsl(filled["dark"])
+    filled.setdefault("deep", from_hsl(deep_hue, deep_saturation, deep_lightness * 0.7))
+    filled.setdefault("accentText", ensure_contrast(accent, canvas))
+    filled.setdefault("onAccent", pick_on_accent(accent, ["#FFFFFF", filled["deep"], text, canvas]))
+    return {name: filled[name] for name in ROLES}
+
+
+def derive_variant(signature: dict[str, str], anchor: tuple[str, str, int], max_saturation: float) -> dict[str, object]:
+    identifier, name, target = anchor
+    accent_hue, accent_saturation, accent_lightness = to_hsl(signature["accent"])
+    shift = target - accent_hue
+    roles: dict[str, str] = {}
+    for role in ("canvas", "panel", "soft", "text", "dark", "deep"):
+        hue, saturation, lightness = to_hsl(signature[role])
+        # Neutrals follow the hue move but never gain chroma.
+        roles[role] = from_hsl(hue + shift, min(saturation, max_saturation), lightness)
+    roles["text"] = ensure_contrast(roles["text"], roles["canvas"])
+    roles["text"] = ensure_contrast(roles["text"], roles["panel"])
+    accent = from_hsl(target, min(accent_saturation, max_saturation), accent_lightness)
+    candidates = ["#FFFFFF", roles["deep"], roles["text"], roles["canvas"]]
+    on_accent = pick_on_accent(accent, candidates)
+    if contrast(on_accent, accent) < MIN_TEXT_CONTRAST:
+        accent = ensure_contrast(accent, on_accent)
+        on_accent = pick_on_accent(accent, candidates)
+    roles["accent"] = accent
+    roles["onAccent"] = on_accent
+    roles["accentText"] = ensure_contrast(accent, roles["canvas"])
+    return {"id": identifier, "name": name, "roles": {role: roles[role] for role in ROLES}}
+
+
+def generate(roles: dict[str, str], *, template: str | None = None, name: str = "Signature",
+             count: int = DEFAULT_VARIANT_COUNT, max_saturation: float = DEFAULT_MAX_SATURATION) -> dict[str, object]:
+    if not 0 < max_saturation <= 1:
+        raise ValueError("max saturation must be in (0, 1]")
+    if count < 0:
+        raise ValueError("count must not be negative")
+    signature = complete_roles(roles)
+    accent_hue = to_hsl(signature["accent"])[0]
+    anchors = [anchor for anchor in HUE_ANCHORS if hue_distance(anchor[2], accent_hue) >= MIN_HUE_DISTANCE]
+    variants = [derive_variant(signature, anchor, max_saturation) for anchor in anchors[:count]]
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "template": template,
+        "signature": {"id": "signature", "name": name, "roles": signature},
+        "variants": variants,
+    }
+
+
+def validate(palette: dict[str, object], max_saturation: float = DEFAULT_MAX_SATURATION) -> dict[str, object]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    if palette.get("schemaVersion") != SCHEMA_VERSION:
+        errors.append(f"schemaVersion must be {SCHEMA_VERSION}")
+    template = palette.get("template")
+    if template is not None and not isinstance(template, str):
+        errors.append("template must be a string or null")
+    entries: list[tuple[dict, bool]] = []
+    if isinstance(palette.get("signature"), dict):
+        entries.append((palette["signature"], False))  # type: ignore[arg-type]
+    else:
+        errors.append("signature must be an object")
+    if isinstance(palette.get("variants"), list):
+        entries.extend((variant, True) for variant in palette["variants"])  # type: ignore[union-attr]
+    else:
+        errors.append("variants must be a list")
+    seen: set[str] = set()
+    checked = 0
+    for entry, is_variant in entries:
+        if not isinstance(entry, dict):
+            errors.append("each palette entry must be an object")
+            continue
+        identifier = str(entry.get("id") or "")
+        label = identifier or "<missing id>"
+        if not identifier or not str(entry.get("name") or "").strip():
+            errors.append(f"{label}: id and name are required")
+        if identifier in seen:
+            errors.append(f"{label}: duplicate palette id")
+        seen.add(identifier)
+        roles = entry.get("roles")
+        if not isinstance(roles, dict):
+            errors.append(f"{label}: roles must be an object")
+            continue
+        missing = [role for role in ROLES if role not in roles]
+        invalid = [role for role in ROLES if role in roles and not (isinstance(roles[role], str) and HEX.match(roles[role]))]
+        if missing:
+            errors.append(f"{label}: missing roles " + ", ".join(missing))
+        if invalid:
+            errors.append(f"{label}: roles must be #RRGGBB: " + ", ".join(invalid))
+        if missing or invalid:
+            continue
+        checked += 1
+        for foreground, background in (("text", "canvas"), ("text", "panel"), ("accentText", "canvas"), ("onAccent", "accent")):
+            ratio = contrast(roles[foreground], roles[background])
+            if ratio < MIN_TEXT_CONTRAST:
+                errors.append(f"{label}: {foreground} on {background} is {ratio:.2f}:1; needs {MIN_TEXT_CONTRAST}:1")
+        saturation = to_hsl(roles["accent"])[1]
+        if is_variant and saturation > max_saturation + 0.01:
+            errors.append(f"{label}: accent saturation {saturation:.2f} exceeds cap {max_saturation:.2f}")
+        if contrast(roles["text"], roles["soft"]) < MIN_TEXT_CONTRAST:
+            warnings.append(f"{label}: text on soft is below {MIN_TEXT_CONTRAST}:1; avoid body copy on soft surfaces")
+    return {"schemaVersion": "maggie-palette-validation.v1", "passed": not errors, "checkedPalettes": checked, "errors": errors, "warnings": warnings}
+
+
+def _load_roles(args: argparse.Namespace) -> dict[str, str]:
+    roles: dict[str, str] = {}
+    if args.roles:
+        data = json.loads(args.roles.read_text(encoding="utf-8"))
+        if isinstance(data.get("signature"), dict):
+            data = data["signature"].get("roles") or {}
+        elif isinstance(data.get("roles"), dict):
+            data = data["roles"]
+        roles.update({key: value for key, value in data.items() if isinstance(value, str)})
+    for role in ROLES:
+        value = getattr(args, role, None)
+        if value:
+            roles[role] = value
+    return roles
+
+
+def _emit(payload: dict[str, object], output: Path | None) -> None:
+    encoded = json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(encoded, encoding="utf-8")
+    print(encoded, end="")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie design palette", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+    generate_parser = sub.add_parser("generate", help="derive contrast-safe variants from a signature palette")
+    generate_parser.add_argument("--roles", type=Path, help="JSON roles object, or an existing palette file")
+    for role in ROLES:
+        generate_parser.add_argument(f"--{role}", dest=role, help=f"{role} colour as #RRGGBB")
+    generate_parser.add_argument("--template", help="template id recorded in the contract")
+    generate_parser.add_argument("--name", default="Signature", help="signature palette display name")
+    generate_parser.add_argument("--count", type=int, default=DEFAULT_VARIANT_COUNT)
+    generate_parser.add_argument("--max-saturation", type=float, default=DEFAULT_MAX_SATURATION)
+    generate_parser.add_argument("--output", type=Path)
+    validate_parser = sub.add_parser("validate", help="check roles, hex values, contrast and saturation cap")
+    validate_parser.add_argument("--palette", type=Path, required=True)
+    validate_parser.add_argument("--max-saturation", type=float, default=DEFAULT_MAX_SATURATION)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "generate":
+            palette = generate(_load_roles(args), template=args.template, name=args.name, count=args.count, max_saturation=args.max_saturation)
+            report = validate(palette, args.max_saturation)
+            if not report["passed"]:
+                print(json.dumps(report, indent=2), file=sys.stderr)
+                print("BLOCKED: maggie-design palette generate: the signature palette fails the contrast contract", file=sys.stderr)
+                return 1
+            _emit(palette, args.output)
+            return 0
+        report = validate(json.loads(args.palette.read_text(encoding="utf-8")), args.max_saturation)
+        _emit(report, None)
+        return 0 if report["passed"] else 1
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"BLOCKED: maggie-design palette {args.command}: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())