@topy-ai/maggie 0.7.4 → 0.7.6

package/bundled-tools/clis/maggie_dash.py

@@ -23,6 +23,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from maggie_dash_store import MaggieDashStore  # noqa: E402
 from service_variants import ServiceVariantStore  # noqa: E402
 from maggie_dash_ui import load_and_validate  # noqa: E402
+from maggie_sections import catalogue, section_id_migration, validate_registry, copy_notes  # noqa: E402
 
 
 def project_root(args: argparse.Namespace) -> Path:
@@ -296,6 +297,13 @@ def command_cms(args: argparse.Namespace) -> int:
             result = store.add_redirect(args.project_id, args.from_path, args.to_path, args.actor, args.reason, args.status_code)
         elif args.cms_command == "preview":
             result = store.issue_preview(args.project_id, args.document_id, args.secret, args.ttl)
+        elif args.cms_command == "preset-save":
+            sections = json.loads(Path(args.sections_file).resolve().read_text(encoding="utf-8"))
+            result = store.save_section_preset(args.project_id, args.preset_id, args.name, sections, args.actor, args.description)
+        elif args.cms_command == "preset-list":
+            result = store.list_section_presets(args.project_id)
+        elif args.cms_command == "preset-insert":
+            result = store.insert_section_preset(args.project_id, args.preset_id, args.existing_id, args.actor, args.reason)
         else:
             raise ValueError(f"unknown CMS command: {args.cms_command}")
         emit(result)
@@ -310,6 +318,25 @@ def command_ui(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_sections(args: argparse.Namespace) -> int:
+    registry = json.loads(Path(args.registry).resolve().read_text(encoding="utf-8"))
+    checked = validate_registry(registry)
+    if not checked["passed"]:
+        emit(checked)
+        return 1
+    if args.sections_command == "prompt":
+        print(catalogue(registry))
+        return 0
+    if args.sections_command == "validate":
+        sections = json.loads(Path(args.sections_file).resolve().read_text(encoding="utf-8"))
+        result = {**checked, "copy": copy_notes(registry, sections)}
+        emit(result)
+        return 0 if result["copy"]["passed"] else 1
+    sections = json.loads(Path(args.sections_file).resolve().read_text(encoding="utf-8"))
+    emit(section_id_migration(args.page_id, sections))
+    return 0
+
+
 def variant_store(args: argparse.Namespace) -> ServiceVariantStore:
     return ServiceVariantStore(project_root(args) / ".maggie" / "service-variants.json")
 
@@ -399,6 +426,12 @@ def parser() -> argparse.ArgumentParser:
     redirect.add_argument("--project", default="."); redirect.add_argument("--project-id", default="local-project"); redirect.add_argument("--from-path", required=True); redirect.add_argument("--to-path", required=True); redirect.add_argument("--status-code", type=int, default=301); redirect.add_argument("--actor", default="cli"); redirect.add_argument("--reason", required=True); redirect.add_argument("--confirm", action="store_true")
     preview = cms_sub.add_parser("preview")
     preview.add_argument("--project", default="."); preview.add_argument("--project-id", default="local-project"); preview.add_argument("--document-id", required=True); preview.add_argument("--secret", required=True); preview.add_argument("--ttl", type=int, default=900); preview.add_argument("--confirm", action="store_true")
+    preset_save = cms_sub.add_parser("preset-save", help="save a reusable ordered section arrangement")
+    preset_save.add_argument("--project", default="."); preset_save.add_argument("--project-id", default="local-project"); preset_save.add_argument("--preset-id", required=True); preset_save.add_argument("--name", required=True); preset_save.add_argument("--sections-file", required=True); preset_save.add_argument("--description", default=""); preset_save.add_argument("--actor", default="cli"); preset_save.add_argument("--confirm", action="store_true")
+    preset_list = cms_sub.add_parser("preset-list", help="list reusable section arrangements")
+    preset_list.add_argument("--project", default="."); preset_list.add_argument("--project-id", default="local-project"); preset_list.add_argument("--confirm", action="store_true")
+    preset_insert = cms_sub.add_parser("preset-insert", help="expand an arrangement with fresh section IDs")
+    preset_insert.add_argument("--project", default="."); preset_insert.add_argument("--project-id", default="local-project"); preset_insert.add_argument("--preset-id", required=True); preset_insert.add_argument("--existing-id", action="append", default=[]); preset_insert.add_argument("--actor", default="cli"); preset_insert.add_argument("--reason", required=True); preset_insert.add_argument("--confirm", action="store_true")
     cms.set_defaults(func=command_cms)
     ui = sub.add_parser("ui", help="validate MaggieDash dashboard chrome")
     ui_sub = ui.add_subparsers(dest="ui_command", required=True)
@@ -406,6 +439,17 @@ def parser() -> argparse.ArgumentParser:
     ui_validate.add_argument("--contract", required=True)
     ui_validate.add_argument("--source", action="append", default=[])
     ui_validate.set_defaults(func=command_ui)
+    sections = sub.add_parser("sections", help="validate section registry and stable section identities")
+    sections_sub = sections.add_subparsers(dest="sections_command", required=True)
+    sections_validate = sections_sub.add_parser("validate")
+    sections_validate.add_argument("--registry", required=True); sections_validate.add_argument("--sections-file", required=True)
+    sections_validate.set_defaults(func=command_sections)
+    sections_prompt = sections_sub.add_parser("prompt")
+    sections_prompt.add_argument("--registry", required=True)
+    sections_prompt.set_defaults(func=command_sections)
+    sections_keys = sections_sub.add_parser("keys")
+    sections_keys.add_argument("--registry", required=True); sections_keys.add_argument("--sections-file", required=True); sections_keys.add_argument("--page-id", required=True)
+    sections_keys.set_defaults(func=command_sections)
     variant = sub.add_parser("variant", help="manage service variant lifecycle")
     variant_sub = variant.add_subparsers(dest="variant_command", required=True)
     create = variant_sub.add_parser("create"); create.add_argument("--project", default="."); create.add_argument("--service-id", required=True); create.add_argument("--variant-id", required=True); create.add_argument("--variant-type", required=True); create.add_argument("--locale", required=True); create.add_argument("--market", required=True); create.add_argument("--slug", required=True); create.add_argument("--title", required=True); create.add_argument("--facts", required=True); create.add_argument("--source-revision", required=True); create.add_argument("--canonical-variant-id"); create.add_argument("--cluster-link", action="append", default=[]); create.add_argument("--layout-family", default="service-default"); create.add_argument("--confirm", action="store_true")

package/bundled-tools/clis/maggie_deployment.py

@@ -219,6 +219,54 @@ WantedBy=multi-user.target
     (output_dir / f"{domain}.conf").write_text(nginx, encoding="utf-8")
 
 
+def release_runner(plan: dict) -> str:
+    """Render the ordered, reviewable VPS runner for one release."""
+    root = plan["release_root"]
+    service = plan["service"]
+    domain = plan["domain"]
+    current = plan["current_release"]
+    return f'''#!/usr/bin/env bash
+set -euo pipefail
+
+# Migration precedes the symlink flip; later releases carry agent state.
+: "${{RELEASE_ID:?set RELEASE_ID to an immutable release name}}"
+RELEASE_ROOT="{root}"
+CURRENT="{current}"
+RELEASE="$RELEASE_ROOT/releases/$RELEASE_ID"
+PREVIOUS="$(readlink -f "$CURRENT" 2>/dev/null || true)"
+mkdir -p "$RELEASE"
+cd "$RELEASE"
+
+npm ci
+npm run typecheck
+npm run migrate
+npm run build
+
+if [ -d "$CURRENT/.agents" ]; then cp -a "$CURRENT/.agents" "$RELEASE/.agents"; fi
+if [ -d "$CURRENT/.claude" ]; then cp -a "$CURRENT/.claude" "$RELEASE/.claude"; fi
+
+ln -sfn "$RELEASE" "$CURRENT"
+systemctl restart "{service}"
+systemctl is-active --quiet "{service}"
+curl -fsS "https://{domain}/robots.txt" >/dev/null
+curl -fsS "https://{domain}/sitemap.xml" >/dev/null
+
+# Keep current plus one rollback candidate, and prune only after health checks.
+mapfile -t RELEASES < <(find "$RELEASE_ROOT/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | cut -d' ' -f2-)
+for candidate in "${{RELEASES[@]:2}}"; do
+  [ "$candidate" = "$PREVIOUS" ] && continue
+  [ "$candidate" = "$RELEASE" ] && continue
+  rm -rf -- "$candidate"
+done
+'''
+
+
+def write_release_runner(path: Path, plan: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(release_runner(plan), encoding="utf-8")
+    path.chmod(0o750)
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("project", nargs="?", default=".")
@@ -231,6 +279,7 @@ def main() -> int:
     parser.add_argument("--release-root", default="/var/www/maggie-site", help="immutable release root")
     parser.add_argument("--node-port", type=int, default=4321)
     parser.add_argument("--plan-dir", help="directory for generated VPS artifacts")
+    parser.add_argument("--runner-output", help="write a reviewable ordered VPS release runner")
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
     parser.add_argument("--current-link", help="current symlink for --retention-plan")
     parser.add_argument("--keep-releases", type=int, default=2)
@@ -249,6 +298,8 @@ def main() -> int:
             plan = vps_plan(args.domain, args.service, args.release_root, args.node_port)
             if args.plan_dir:
                 write_vps_plan(Path(args.plan_dir).resolve(), plan)
+            if args.runner_output:
+                write_release_runner(Path(args.runner_output).resolve(), plan)
             print(json.dumps(plan, indent=2, ensure_ascii=False))
             return 0
         if args.retention_plan:

package/bundled-tools/clis/maggie_feedback.py

@@ -20,6 +20,9 @@ from urllib.request import Request, urlopen
 
 DEFAULT_ENDPOINT = "https://feedback.noblox.app/api/feedback"
 SECRET_RE = re.compile(r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|npm_config[^=]*|authorization)\s*[=:]\s*)[^\s,;]+")
+VERSION_RE = re.compile(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?")
+ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
+REPO_ROOT = Path(__file__).resolve().parents[2]
 
 
 def now() -> str:
@@ -35,17 +38,29 @@ def project_fingerprint(project: Path) -> str:
 
 
 def installed_version(project: Path) -> str:
-    """Resolve the version from the runtime wrapper or project install state."""
+    """Resolve the exact runtime version and fail closed on source drift."""
     if os.environ.get("MAGGIE_VERSION"):
-        return safe_text(os.environ["MAGGIE_VERSION"])
-    for path in (project / ".maggie" / "install.json", project / "VERSION"):
+        value = safe_text(os.environ["MAGGIE_VERSION"])
+        return value if VERSION_RE.fullmatch(value) else "unknown"
+    install_path = project / ".maggie" / "install.json"
+    try:
+        value = json.loads(install_path.read_text(encoding="utf-8")).get("version", "")
+        if VERSION_RE.fullmatch(str(value)):
+            return str(value)
+    except (OSError, ValueError, json.JSONDecodeError, AttributeError):
+        pass
+
+    source_versions = []
+    for path in (REPO_ROOT / "VERSION", REPO_ROOT / "packages" / "maggie-cli" / "package.json"):
         try:
             value = json.loads(path.read_text(encoding="utf-8")) if path.suffix == ".json" else path.read_text(encoding="utf-8").strip()
             if isinstance(value, dict): value = value.get("version", "")
-            if re.fullmatch(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?", str(value)):
-                return str(value)
+            if VERSION_RE.fullmatch(str(value)):
+                source_versions.append(str(value))
         except (OSError, ValueError, json.JSONDecodeError):
             continue
+    if source_versions and len(set(source_versions)) == 1:
+        return source_versions[0]
     return "unknown"
 
 
@@ -124,6 +139,18 @@ def to_markdown(data: dict) -> str:
     return "\n".join(lines)
 
 
+def acknowledgement(value: object) -> dict:
+    """Keep only safe, scalar acknowledgement fields from a provider response."""
+    if not isinstance(value, dict):
+        return {}
+    result = {}
+    for key in ACKNOWLEDGEMENT_KEYS:
+        item = value.get(key)
+        if isinstance(item, (str, int, float, bool)):
+            result[key] = safe_text(item)
+    return result
+
+
 def read_feedback(path: Path) -> dict:
     return load_json(path)
 
@@ -152,9 +179,10 @@ def submit(args: argparse.Namespace) -> int:
             result = json.loads(raw) if raw else {}
     except (HTTPError, URLError, TimeoutError) as error:
         raise RuntimeError(f"feedback submission failed: {error}") from error
-    data["submission"] = {"status": "submitted", "endpoint": endpoint, "submittedAt": now(), "response": result if isinstance(result, dict) else {"value": result}}
+    ack = acknowledgement(result)
+    data["submission"] = {"status": "submitted", "endpoint": endpoint, "submittedAt": now(), "acknowledgement": ack}
     path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "response": result}, indent=2, ensure_ascii=False))
+    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "acknowledgement": ack}, indent=2, ensure_ascii=False))
     return 0
 
 

package/bundled-tools/clis/maggie_ops.py

@@ -12,6 +12,8 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from dependency_lock import audit as audit_lockfiles
 from seed_evidence import validate_manifest
+from agent_runtime import preflight as agent_preflight
+from restart_gate import validate as validate_restart_gate
 
 
 REQUIRED_ROUTES = (
@@ -149,6 +151,20 @@ def command_seed_manifest(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_agent_preflight(args: argparse.Namespace) -> int:
+    result = agent_preflight(release_dir=args.release_dir)
+    if args.output:
+        write_json(Path(args.output).resolve(), result)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0
+
+
+def command_restart_gate(args: argparse.Namespace) -> int:
+    result = validate_restart_gate(read_json(Path(args.manifest).resolve()))
+    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=".")
@@ -160,6 +176,13 @@ def main() -> int:
     seed = sub.add_parser("seed-manifest", help="validate explicit sanitized development fixtures")
     seed.add_argument("--manifest", required=True)
     seed.set_defaults(func=command_seed_manifest)
+    agent = sub.add_parser("agent-preflight", help="report agent runtime and deployment gotchas")
+    agent.add_argument("--output")
+    agent.add_argument("--release-dir")
+    agent.set_defaults(func=command_agent_preflight)
+    restart = sub.add_parser("restart-gate", help="validate restart-after-out-of-band-write evidence")
+    restart.add_argument("--manifest", required=True)
+    restart.set_defaults(func=command_restart_gate)
     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_verification.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Validate changed route surfaces and locales from explicit evidence."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from surface_coverage import compare  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    coverage = sub.add_parser("coverage")
+    coverage.add_argument("--contract", type=Path, required=True)
+    coverage.add_argument("--evidence", type=Path, required=True)
+    args = parser.parse_args()
+    if args.command == "coverage":
+        contract = json.loads(args.contract.resolve().read_text(encoding="utf-8"))
+        evidence = json.loads(args.evidence.resolve().read_text(encoding="utf-8"))
+        observations = evidence.get("observations") if isinstance(evidence, dict) else evidence
+        result = compare(contract, observations)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0 if result["passed"] else 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/runtime/agent_runtime.py

@@ -0,0 +1,38 @@
+"""Operational checks for running agent CLIs from a deployed workspace."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+
+ANSI = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+
+def strip_ansi(value: str) -> str:
+    return ANSI.sub("", value)
+
+
+def preflight(environment: dict[str, str] | None = None, release_dir: str | None = None) -> dict:
+    env = environment or dict(os.environ)
+    warnings = [
+        "strip ANSI terminal escapes before parsing URLs, codes, or stored transcripts",
+        "use device authentication on a headless host and confirm the account prerequisite before launch",
+        "carry agent installs and conversation state outside immutable release directories",
+        "put the resume subcommand before agent flags so the CLI cannot treat it as a new prompt",
+    ]
+    risks = []
+    if env.get("NO_COLOR") != "1" or env.get("TERM") not in {"dumb", ""}:
+        risks.append("terminal color may be enabled; parser must still strip ANSI")
+    if release_dir and Path(release_dir).name in {"current", "releases"}:
+        risks.append("agent state must not be stored only inside an immutable release")
+    return {
+        "schemaVersion": "maggie-agent-runtime.v1",
+        "passed": True,
+        "warnings": warnings,
+        "risks": risks,
+        "auth": "device",
+        "resume": {"codex": ["resume", "--last"], "claude": ["--continue"]},
+        "statePolicy": "outside-release-directory",
+    }

package/bundled-tools/runtime/maggie_dash_store.py

@@ -13,6 +13,8 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any
 
+from maggie_sections import ensure_section_ids
+
 
 STATUSES = ("draft", "review", "approved", "scheduled", "published", "archived", "trashed")
 TRANSITIONS = {
@@ -83,6 +85,12 @@ class MaggieDashStore:
               actor_id TEXT NOT NULL, reason TEXT NOT NULL, correlation_id TEXT NOT NULL,
               created_at TEXT NOT NULL
             );
+            CREATE TABLE IF NOT EXISTS maggiedash_section_presets (
+              id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES maggiedash_projects(id),
+              name TEXT NOT NULL, description TEXT, body_json TEXT NOT NULL,
+              created_by TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+              UNIQUE(project_id, name)
+            );
             """
         )
         self._ensure_column("maggiedash_documents", "trashed_at", "TEXT")
@@ -268,6 +276,49 @@ class MaggieDashStore:
         self.connection.commit()
         return result
 
+    def save_section_preset(self, project_id: str, preset_id: str, name: str, sections: list[dict[str, Any]], actor_id: str, description: str = "") -> dict[str, Any]:
+        """Save an ordered arrangement without leaking page-specific IDs."""
+        name = name.strip()
+        if not name:
+            raise ValueError("preset name is required")
+        if not isinstance(sections, list) or not sections or not all(isinstance(section, dict) and section.get("type") for section in sections):
+            raise ValueError("preset sections must be a non-empty typed list")
+        body = []
+        for section in sections:
+            copy = json.loads(json.dumps(section, ensure_ascii=False))
+            copy.pop("id", None)
+            body.append(copy)
+        timestamp = now()
+        self.connection.execute(
+            "INSERT INTO maggiedash_section_presets (id,project_id,name,description,body_json,created_by,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?) "
+            "ON CONFLICT(id) DO UPDATE SET name=excluded.name, description=excluded.description, body_json=excluded.body_json, updated_at=excluded.updated_at",
+            (preset_id, project_id, name, description.strip(), json.dumps(body, ensure_ascii=False), actor_id, timestamp, timestamp),
+        )
+        self._audit(project_id, "section-preset.saved", "section_preset", preset_id, actor_id, "ordered arrangement saved")
+        self.connection.commit()
+        return self.get_section_preset(project_id, preset_id) or {}
+
+    def get_section_preset(self, project_id: str, preset_id: str) -> dict[str, Any] | None:
+        row = self.connection.execute("SELECT * FROM maggiedash_section_presets WHERE project_id=? AND id=?", (project_id, preset_id)).fetchone()
+        if not row:
+            return None
+        result = dict(row)
+        result["body"] = json.loads(result.pop("body_json"))
+        return result
+
+    def list_section_presets(self, project_id: str) -> list[dict[str, Any]]:
+        rows = self.connection.execute("SELECT id FROM maggiedash_section_presets WHERE project_id=? ORDER BY updated_at DESC", (project_id,)).fetchall()
+        return [self.get_section_preset(project_id, row["id"]) for row in rows]
+
+    def insert_section_preset(self, project_id: str, preset_id: str, existing_ids: list[str], actor_id: str, reason: str) -> list[dict[str, Any]]:
+        preset = self.get_section_preset(project_id, preset_id)
+        if not preset:
+            raise ValueError("section preset not found")
+        result = ensure_section_ids(preset["body"], existing_ids)
+        self._audit(project_id, "section-preset.inserted", "section_preset", preset_id, actor_id, reason)
+        self.connection.commit()
+        return result
+
     def add_redirect(self, project_id: str, from_path: str, to_path: str, actor_id: str, reason: str, status_code: int = 301) -> dict[str, Any]:
         if not from_path.startswith("/") or not to_path.startswith("/") or self._normalise_path(from_path) == self._normalise_path(to_path):
             raise ValueError("redirect paths must be distinct absolute paths")

package/bundled-tools/runtime/maggie_sections.py

@@ -0,0 +1,143 @@
+"""Provider-neutral section registry, copy limits, and stable section keys."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import re
+import uuid
+from typing import Any, Iterable
+
+
+SCHEMA = "maggiedash-section-registry.v1"
+IDENTITY_SCHEMA = "maggiedash-section-identity.v1"
+
+
+def validate_registry(value: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["registry must be an object"]}
+    if value.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    sections = value.get("sections")
+    if not isinstance(sections, list) or not sections:
+        errors.append("sections must be a non-empty list")
+        sections = []
+    seen: set[str] = set()
+    for index, section in enumerate(sections):
+        at = f"sections[{index}]"
+        if not isinstance(section, dict):
+            errors.append(f"{at} must be an object")
+            continue
+        section_type = str(section.get("type") or "")
+        if not re.fullmatch(r"[a-z][a-z0-9-]*", section_type):
+            errors.append(f"{at}.type must be a kebab-case identifier")
+        if section_type in seen:
+            errors.append(f"duplicate section type: {section_type}")
+        seen.add(section_type)
+        for field in ("purpose", "usage", "position", "repeatable"):
+            if field not in section:
+                errors.append(f"{at}.{field} is required")
+        if section.get("position") not in {"opening", "body", "closing"}:
+            errors.append(f"{at}.position must be opening, body, or closing")
+        if not isinstance(section.get("repeatable"), bool):
+            errors.append(f"{at}.repeatable must be boolean")
+        fields = section.get("fields")
+        if not isinstance(fields, list) or not fields:
+            errors.append(f"{at}.fields must be a non-empty list")
+            continue
+        field_names: set[str] = set()
+        for field_index, field in enumerate(fields):
+            field_at = f"{at}.fields[{field_index}]"
+            if not isinstance(field, dict) or not field.get("name"):
+                errors.append(f"{field_at} needs a name")
+                continue
+            name = str(field["name"])
+            if name in field_names:
+                errors.append(f"duplicate field: {section_type}.{name}")
+            field_names.add(name)
+            if not isinstance(field.get("limit"), int) or field["limit"] < 0:
+                errors.append(f"{field_at}.limit must be a non-negative integer")
+            if not str(field.get("usage") or "").strip():
+                errors.append(f"{field_at}.usage is required")
+            repeats = field.get("repeats")
+            if repeats is not None and (not isinstance(repeats, dict) or not isinstance(repeats.get("min"), int) or not isinstance(repeats.get("max"), int) or repeats["min"] < 0 or repeats["min"] > repeats["max"]):
+                errors.append(f"{field_at}.repeats must declare valid min/max")
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "sectionTypes": sorted(seen)}
+
+
+def catalogue(registry: dict[str, Any]) -> str:
+    """Render a compact prompt catalogue without duplicating field guidance."""
+    lines: list[str] = []
+    for section in registry.get("sections", []):
+        lines.append(f"{section['type']} — {section['purpose']} | when: {section['usage']} | place: {section['position']} | {'repeatable' if section['repeatable'] else 'once'}")
+        for field in section.get("fields", []):
+            repeat = field.get("repeats")
+            suffix = f" [{repeat['min']}-{repeat['max']} entries]" if isinstance(repeat, dict) else ""
+            lines.append(f"  - {field['name']} ≤{field['limit']} chars{suffix}: {field['usage']}")
+    return "\n".join(lines)
+
+
+def copy_notes(registry: dict[str, Any], sections: object) -> dict[str, Any]:
+    """Return advisory copy/shape notes; over-limit copy is not rejected."""
+    errors: list[str] = []
+    notes: list[dict[str, Any]] = []
+    if not isinstance(sections, list):
+        return {"passed": False, "errors": ["sections must be a list"], "notes": []}
+    specs = {str(item.get("type")): item for item in registry.get("sections", []) if isinstance(item, dict)}
+    for index, section in enumerate(sections):
+        if not isinstance(section, dict):
+            errors.append(f"sections[{index}] must be an object")
+            continue
+        section_type = str(section.get("type") or "")
+        spec = specs.get(section_type)
+        if not spec:
+            errors.append(f"unknown section type: {section_type}")
+            continue
+        for field in spec.get("fields", []):
+            name = str(field.get("name"))
+            value = section.get(name)
+            limit = int(field.get("limit", 0))
+            if isinstance(value, str) and limit and len(value) > limit:
+                notes.append({"at": f"sections[{index}].{name}", "message": f"{len(value)} characters; layout limit is about {limit}"})
+            repeats = field.get("repeats")
+            if isinstance(repeats, dict) and isinstance(value, list) and not repeats["min"] <= len(value) <= repeats["max"]:
+                notes.append({"at": f"sections[{index}].{name}", "message": f"{len(value)} entries; layout expects {repeats['min']}-{repeats['max']}"})
+    return {"passed": not errors, "errors": errors, "notes": notes}
+
+
+def new_section_id(existing: Iterable[str] = ()) -> str:
+    taken = set(existing)
+    while True:
+        candidate = uuid.uuid4().hex[:8]
+        if candidate not in taken:
+            return candidate
+
+
+def ensure_section_ids(sections: list[dict[str, Any]], existing: Iterable[str] = ()) -> list[dict[str, Any]]:
+    result = copy.deepcopy(sections)
+    existing_ids = set(existing)
+    taken = set(existing_ids)
+    for section in result:
+        current = str(section.get("id") or "")
+        if not current or current in existing_ids or current in taken:
+            section["id"] = new_section_id(taken)
+        taken.add(str(section["id"]))
+    return result
+
+
+def section_key(section: object, index: int) -> str:
+    if isinstance(section, dict) and isinstance(section.get("id"), str) and section["id"]:
+        return section["id"]
+    return str(index)
+
+
+def translation_key(page_id: str, section: object, index: int, field: str) -> str:
+    return f"page.{page_id}.sections.{section_key(section, index)}.{field}"
+
+
+def section_id_migration(page_id: str, sections: list[dict[str, Any]]) -> dict[str, Any]:
+    identified = ensure_section_ids(sections)
+    mappings = [{"from": f"page.{page_id}.sections.{index}.", "to": f"page.{page_id}.sections.{section['id']}."} for index, section in enumerate(identified)]
+    return {"schemaVersion": IDENTITY_SCHEMA, "pageId": page_id, "sections": identified, "renameOrder": sorted(mappings, key=lambda item: len(item["from"]), reverse=True), "sourceChecksum": hashlib.sha256(json.dumps(sections, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode()).hexdigest()}

package/bundled-tools/runtime/restart_gate.py

@@ -0,0 +1,22 @@
+"""Evidence gate for writes performed outside the running application."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def validate(value: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return {"schemaVersion": "maggie-restart-gate.v1", "passed": False, "errors": ["restart gate must be an object"]}
+    if value.get("schemaVersion") != "maggie-restart-gate.v1":
+        errors.append("unsupported restart gate schema")
+    if value.get("outOfBandWrite") is not True:
+        errors.append("outOfBandWrite must be true for this gate")
+    if value.get("restartRequired") is not True:
+        errors.append("restartRequired must be true after an out-of-band write")
+    if not str(value.get("restartCommand") or "").strip():
+        errors.append("restartCommand is required")
+    if value.get("verificationAfterRestart") is not True:
+        errors.append("verificationAfterRestart must be true")
+    return {"schemaVersion": "maggie-restart-gate.v1", "passed": not errors, "errors": errors, "order": ["write", "restart", "verify"]}