@topy-ai/maggie 0.7.4 → 0.7.5

package/README.md

@@ -92,6 +92,9 @@ maggie bootstrap interview | phase ...
 maggie dash install | init | status | migrate | cms ...
 maggie dash transition ...      # explicit content approval transition
 maggie dash variant ...         # service variant create/review/preview/publish
+maggie dash sections ...        # validate/catalogue/identity keys
+maggie agent-content write ...  # host-authorized content bridge
+maggie verification coverage ... # changed surface/locale evidence gate
 maggie clone ...                 # authorized homepage capture
 maggie design ...                # authorized interior-page design
 maggie clone-to-template ...     # URL → validated marketplace template
@@ -191,8 +194,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.4 update --project . --force
-npx @topy-ai/maggie@0.7.4 cleanup --project .
+npx @topy-ai/maggie@0.7.5 update --project . --force
+npx @topy-ai/maggie@0.7.5 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -202,15 +205,20 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.4 workflow adds the installable MaggieDash admin distribution and
+The 0.7.5 workflow adds the installable MaggieDash admin distribution and
 audited CMS operations (`cms revisions`,
 `trash`, `restore`, `schedule`, `publish-due`, `duplicate`, `redirect`, and
 signed `preview`). It also adds a read-only MaggieDash `--diff`/`--dry-run`
 migration inventory, body-only dashboard prop validation, dialog accessibility
 contract checks, 404-only redirect policy, trash/scheduler/preview invariants,
-and a shared first-party traffic filter for every measurement channel. The
-release retains the existing service matching, localization, seed-manifest,
-lockfile/analytics, sitemap, deployment and rollback workflows.
+and a shared first-party traffic filter for every measurement channel. It also
+adds stable section identities and reusable section presets, a machine-readable
+MaggieDash section registry, a short-lived agent content bridge, restart gates
+for out-of-band translation writes, deployment release-runner generation,
+disk-versus-manifest skill inventory checks, and changed-surface/locale
+verification. The release retains the existing service matching,
+localization, seed-manifest, lockfile/analytics, sitemap, deployment and
+rollback workflows.
 
 ## MaggieDash lifecycle
 

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.6.9 init --agent all
+npx @topy-ai/maggie@0.7.5 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,10 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
+MaggieDash 也提供穩定 section identity、可重用 section arrangement、機器可讀
+section registry、短期 agent content bridge，以及 translation out-of-band write
+後的 restart gate。`maggie doctor` 會比較 install manifest 與磁碟上的實際 skills。
+
 新版 release gates：
 
 ```bash

package/bin/maggie.js

@@ -66,9 +66,11 @@ Usage:
   maggie doctor [--project PATH]
   maggie bootstrap interview [project]
   maggie dash init|install|status|migrate|transition|variant|cms --project PATH [options]
+  maggie dash sections <validate|prompt|keys> [options]
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
   maggie content FILE --source PROVIDER --project PATH --confirm
+  maggie agent-content write --url URL --token-env ENV --payload FILE
   maggie bootstrap phase <start|pass|fail|status> <phase> [project]
   maggie remove [SKILL ...] [--project PATH] [--agent codex|claude|all]
   maggie cleanup --project PATH [--confirm]
@@ -117,6 +119,7 @@ Usage:
   maggie site-audit URL --crawl --save-baseline FILE --reviewer NAME
   maggie site-audit URL --crawl --baseline FILE
   maggie browser-audit URL --browse PATH --output DIR --required SELECTOR [--sticky SELECTOR]
+  maggie verification coverage --contract FILE --evidence FILE
   maggie ops audit|preflight|verify|lockfiles|seed-manifest --project PATH
   maggie ops preflight --project PATH --write
 
@@ -320,11 +323,22 @@ function doctor(args) {
     ["claude-skills", existsSync(join(root, ".claude", "skills"))],
   ];
   for (const [name, passed] of checks) console.log(`${passed ? "PASS" : "INFO"} ${name}`);
+  const manifestPath = join(root, STATE_DIR, "install.json");
+  let manifest = null;
+  try { if (existsSync(manifestPath)) manifest = JSON.parse(readFileSync(manifestPath, "utf8")); } catch { manifest = null; }
+  const expected = Array.isArray(manifest?.skills) ? [...new Set(manifest.skills)] : null;
   const installed = [];
+  const installedNames = new Set();
   for (const agentRoot of [join(root, ".agents"), join(root, ".claude")]) {
-    for (const skill of SKILL_NAMES) if (existsSync(join(agentRoot, "skills", skill, "SKILL.md"))) installed.push(`${agentRoot}/${skill}`);
+    for (const skill of SKILL_NAMES) if (existsSync(join(agentRoot, "skills", skill, "SKILL.md"))) {
+      installed.push(`${agentRoot}/${skill}`);
+      installedNames.add(skill);
+    }
   }
-  console.log(`INFO installed-skills=${installed.length}`);
+  const missing = expected ? expected.filter((skill) => !installedNames.has(skill)) : [];
+  const inventoryState = expected && missing.length ? "INCOMPLETE" : "PASS";
+  console.log(`${inventoryState} skill-inventory manifest=${expected?.length ?? "unknown"} on-disk=${installedNames.size}${missing.length ? ` missing=${missing.join(",")}` : ""}`);
+  console.log(`INFO installed-skills=${installedNames.size}`);
   console.log("INFO doctor is diagnostic; bootstrap completion remains a project decision gate.");
 }
 
@@ -394,7 +408,9 @@ try {
   else if (command === "feedback") workflowCli("maggie_feedback.py", args);
   else if (command === "site-audit") workflowCli("site_audit.py", args);
   else if (command === "browser-audit") workflowCli("maggie_browser_audit.py", args);
+  else if (command === "verification") workflowCli("maggie_verification.py", args);
   else if (command === "dash") workflowCli("maggie_dash.py", args);
+  else if (command === "agent-content") workflowCli("maggie_agent_content.py", args);
   else if (command === "content") workflowCli("maggie_content.py", args);
   else if (command === "init" || command === "install") install(args);
   else if (command === "update") update(args);

package/bundled-contracts/maggie-deployment/release-runner-v1.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/release-runner-v1.schema.json",
+  "title": "Maggie deployment release runner v1",
+  "type": "object",
+  "required": ["schemaVersion", "orderedSteps", "retention"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-release-runner.v1"},
+    "orderedSteps": {"const": ["install", "typecheck", "migrate", "build", "carry-agent-state", "switch", "restart", "verify", "prune"]},
+    "retention": {"const": "exactly-current-plus-one-rollback"},
+    "mutation": {"enum": ["reviewable-script", "executed-after-confirmation"]}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/README.md

@@ -18,6 +18,12 @@ frontend framework.
   self/chain safety for canonical route redirects;
 - [`telemetry-policy-v1.json`](telemetry-policy-v1.json): first-party/toolchain
   traffic exclusion for every measurement channel.
+- [`agent-content-v1.json`](agent-content-v1.json): short-lived host bridge for
+  validated agent content writes without database credentials;
+- [`section-identity-v1.json`](section-identity-v1.json): stable section IDs
+  for translation keys and ordered migration;
+- [`translation-cache-policy-v1.json`](translation-cache-policy-v1.json):
+  restart-after-out-of-band-write evidence.
 
 MaggieDash owns these contracts. Provider adapters may add namespaced metadata,
 but they may not change the required identity, status, provenance, or approval

package/bundled-contracts/maggiedash/agent-content-v1.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/agent-content-v1.schema.json",
+  "title": "MaggieDash agent content bridge v1",
+  "type": "object",
+  "required": ["method", "authorization", "tokenLifetime", "databaseCredentials"],
+  "properties": {
+    "method": {"const": "POST"},
+    "authorization": {"const": "Bearer short-lived session token"},
+    "tokenLifetime": {"const": "terminal session"},
+    "databaseCredentials": {"const": "never exposed to agent"},
+    "writes": {"type": "array", "items": {"enum": ["validated content operation", "revision", "audit event"]}}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/section-identity-v1.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/section-identity-v1.schema.json",
+  "title": "MaggieDash stable section identity v1",
+  "type": "object",
+  "required": ["schemaVersion", "keyPattern", "fallback", "migrationOrder"],
+  "properties": {
+    "schemaVersion": {"const": "maggiedash-section-identity.v1"},
+    "keyPattern": {"const": "page.<id>.sections.<section-id>.<field>"},
+    "fallback": {"const": "array-index-until-migrated"},
+    "migrationOrder": {"const": "longest-old-prefix-first"}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/translation-cache-policy-v1.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/translation-cache-policy-v1.schema.json",
+  "title": "MaggieDash translation cache policy v1",
+  "type": "object",
+  "required": ["schemaVersion", "outOfBandWrite", "restartRequired", "restartCommand", "verificationAfterRestart"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-restart-gate.v1"},
+    "outOfBandWrite": {"const": true},
+    "restartRequired": {"const": true},
+    "restartCommand": {"type": "string", "minLength": 1},
+    "verificationAfterRestart": {"const": true}
+  },
+  "additionalProperties": false
+}

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

@@ -46,6 +46,21 @@ owns the framework route, email/password session middleware, database, media
 storage, provider credentials, and `/api/maggie/*` adapter endpoints. Read the
 MaggieDash host adapter contract before adding a new framework adapter.
 
+For a built/deployed host, an agent must use the host's validated content
+bridge rather than editing release files or receiving database credentials:
+
+```bash
+maggie agent-content write \
+  --url https://example.test/api/maggie/agent-content.json \
+  --token-env MAGGIE_CONTENT_TOKEN --payload .maggie/content-operation.json
+```
+
+The host mints a short-lived session token. The bridge uses `POST` with
+`Authorization: Bearer`, delegates to the ordinary save/revision/audit path,
+and returns 401/422 for invalid authority or content. Never put database
+credentials or the short-lived token in the payload or generated reports. See
+the [agent content contract](../../contracts/maggiedash/agent-content-v1.json).
+
 ## Workflow
 
 1. Inspect the project with `maggie dash status --project PATH`.
@@ -125,6 +140,11 @@ maggie dash cms publish-due --project . --project-id local-project \
   --reason "scheduled publish tick" --confirm
 maggie dash cms duplicate --project . --project-id local-project --document-id <id> \
   --new-id <new-id> --new-slug <new-slug> --reason "create draft" --confirm
+maggie dash cms preset-save --project . --project-id local-project \
+  --preset-id treatment-page --name "Treatment page" \
+  --sections-file .maggie/sections.json --confirm
+maggie dash cms preset-insert --project . --project-id local-project \
+  --preset-id treatment-page --existing-id hero-1 --reason "add arrangement" --confirm
 maggie dash cms redirect --project . --project-id local-project --from-path /old --to-path /new \
   --reason "canonical slug change" --confirm
 maggie dash cms preview --project . --project-id local-project --document-id <id> \
@@ -142,3 +162,31 @@ are short-lived HMAC-signed tokens; preview responses must use a real preview
 URL with `noindex`, `X-Robots-Tag: noindex`, and `Cache-Control: no-store`.
 Never place the secret in source control or generated reports. See the
 provider-neutral [MaggieDash contract set](../../contracts/maggiedash/README.md).
+
+Reusable arrangements are stored without page-specific section IDs and expand
+into ordinary editable sections with fresh IDs on every insert. Use the
+machine-readable section catalogue before asking a model to plan copy:
+
+```bash
+maggie dash sections validate --registry templates/maggiedash/section-registry.json \
+  --sections-file .maggie/sections.json
+maggie dash sections prompt --registry templates/maggiedash/section-registry.json
+maggie dash sections keys --registry templates/maggiedash/section-registry.json \
+  --page-id <page-id> --sections-file .maggie/sections.json
+```
+
+The catalogue declares purpose, usage, placement, repeatability and layout
+limits. Over-limit copy is an editor note; unknown types fail validation.
+Translation keys use stable section IDs, with an array-index fallback only
+until the ordered migration is complete.
+
+After any script or direct adapter write to translation data, invalidate the
+running process before verification. Record the restart and run the rendering
+check afterward:
+
+```bash
+maggie ops restart-gate --manifest .maggie/translation-restart.json
+```
+
+This prevents an in-process cache window from turning correct database state
+into temporarily stale pages and false verification failures.

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

@@ -63,11 +63,15 @@ Generate a reviewable VPS plan and configuration artifacts locally:
 python3 tools/clis/maggie_deployment.py /path/to/project \
   --vps-plan --domain example.co.uk --service example \
   --release-root /var/www/example \
-  --plan-dir .maggie/deployment/vps-staging
+  --plan-dir .maggie/deployment/vps-staging \
+  --runner-output .maggie/deployment/vps-staging/release-runner.sh
 ```
 
 The output contains only the immutable release/current layout, systemd unit,
-Nginx reverse-proxy config, health commands and rollback command. It never
+Nginx reverse-proxy config, health commands, rollback command, and an ordered
+reviewable release runner. The runner keeps migrations before the symlink flip,
+carries `.agents`/`.claude` state, restarts before verification, and prunes to
+the current release plus one rollback candidate. It never
 contains credentials and never SSHs, changes DNS, restarts systemd or deploys.
 
 VPS plans include a bounded retention policy: keep two immutable releases,
@@ -136,6 +140,20 @@ MaggieDash schema compatibility, and live runtime security-header checks. It wri
 `.maggie/release-preflight.json`; a failed gate blocks release. It never
 deploys, migrates, publishes, or sends provider requests.
 
+Generate a repeatable VPS runner as part of the plan. A deploy step that exists
+only in an operator's shell history is not a release contract:
+
+```bash
+python3 tools/clis/maggie_deployment.py /path/to/project \
+  --vps-plan --domain example.co.uk --service example \
+  --release-root /var/www/example \
+  --runner-output .maggie/deployment/release-runner.sh
+```
+
+Review the generated runner before execution. Its order is install → typecheck
+→ migrate → build → carry agent state → switch → restart → verify → prune;
+retention keeps the current release and one rollback candidate.
+
 Production additionally requires `docs/deployment-rollback-smoke.json` with
 `passed: true`, `environment: production`, a non-empty `previousRelease`, and
 `testedAt`. A rollback command in a plan is not proof that the rollback was

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

@@ -226,3 +226,20 @@ shared contract is in
 [references/maggiedash-telemetry-contract.md](../../references/maggiedash-telemetry-contract.md);
 it excludes only explicit tool/test markers and never infers identity from IP
 or private fields.
+
+## Agent runtime preflight
+
+Before starting an agent from a dashboard, run the runtime preflight and show
+its warnings to the operator. Terminal output must be stripped of ANSI escape
+sequences before URL/code parsing. Headless hosts should use device auth and
+state the account prerequisite before starting. Release installs and agent
+conversation state must be carried outside the immutable release directory.
+When continuing a conversation, pass the agent's resume subcommand before
+other arguments; otherwise the CLI may interpret it as a new prompt.
+
+```bash
+maggie ops agent-preflight --output .maggie/agent-runtime-preflight.json
+```
+
+The preflight is advisory about the host environment but its warnings are
+load-bearing operational evidence, not a claim that an agent login succeeded.

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

@@ -19,6 +19,22 @@ Static audit success
 does not establish Google indexing, scroll behavior, responsive visibility,
 or translation quality. Record those as unverified without separate evidence.
 
+Choose verification from the changed surface. An admin-only change still needs
+the admin routes; an API change needs the API responses; a localized change
+needs every affected locale. Declare the matrix and validate explicit evidence
+before release:
+
+```bash
+maggie verification coverage \
+  --contract contracts/maggie-verification/surface-coverage-v1.json \
+  --evidence .maggie/surface-coverage.json
+```
+
+The evidence must contain one observation for every declared surface/locale
+pair with a status and `passed: true`. Public-page checks alone cannot close an
+admin or API change, and one source-language rendering cannot close a
+localized change.
+
 Crawl reports include `summary.byLocaleTemplate` with total, passed, failed
 and failed URLs per declared locale and template. Regions/scripts remain
 distinct (for example en-GB versus en-US). A template is identified only when

package/bundled-templates/maggiedash/section-registry.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": "maggiedash-section-registry.v1",
+  "description": "The machine-readable section vocabulary used by page planners and editors.",
+  "sections": [
+    {"type": "hero", "purpose": "Says what the page is about and offers the one important action.", "usage": "First on the page; once.", "position": "opening", "repeatable": false, "fields": [{"name": "title", "usage": "Plain words a visitor would search for.", "limit": 70, "required": true}, {"name": "intro", "usage": "Who it is for and what it does.", "limit": 220}, {"name": "ctaLabel", "usage": "The action as a verb.", "limit": 30}]},
+    {"type": "prose", "purpose": "Explains a topic at length, optionally beside an image.", "usage": "Use in the body for explanation.", "position": "body", "repeatable": true, "fields": [{"name": "heading", "usage": "The argument in a sentence.", "limit": 90}, {"name": "paragraphs", "usage": "Two or three standalone paragraphs.", "limit": 400, "repeats": {"min": 1, "max": 4}}]},
+    {"type": "cards", "purpose": "Presents parallel points side by side.", "usage": "Use for steps or genuinely parallel points.", "position": "body", "repeatable": true, "fields": [{"name": "heading", "usage": "What the cards share.", "limit": 90}, {"name": "items", "usage": "The parallel points.", "limit": 220, "repeats": {"min": 3, "max": 3}}]},
+    {"type": "links", "purpose": "Sends the reader to related pages.", "usage": "Near the end after the page has done its job.", "position": "closing", "repeatable": true, "fields": [{"name": "heading", "usage": "What the links have in common.", "limit": 90}, {"name": "items", "usage": "Real related pages on this site.", "limit": 160, "repeats": {"min": 2, "max": 6}}]},
+    {"type": "faq", "purpose": "Answers questions a visitor would otherwise ask.", "usage": "Once near the end; use real visitor questions.", "position": "closing", "repeatable": false, "fields": [{"name": "heading", "usage": "The question topic.", "limit": 90}, {"name": "items", "usage": "Direct questions and answers.", "limit": 600, "repeats": {"min": 2, "max": 8}}]},
+    {"type": "cta", "purpose": "Makes the closing ask.", "usage": "Last on the page; once.", "position": "closing", "repeatable": false, "fields": [{"name": "heading", "usage": "The invitation in a sentence.", "limit": 90, "required": true}, {"name": "body", "usage": "What happens next.", "limit": 220}, {"name": "label", "usage": "The action as a verb.", "limit": 30, "required": true}]}
+  ]
+}

package/bundled-tools/clis/maggie_agent_content.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Use a short-lived MaggieDash host token for validated content writes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+SENSITIVE_KEYS = {"databaseUrl", "databaseURL", "password", "secret", "token", "apiKey"}
+
+
+def validate_payload(value: object) -> dict:
+    if not isinstance(value, dict):
+        raise ValueError("payload must be a JSON object")
+    forbidden = sorted(SENSITIVE_KEYS.intersection(value))
+    if forbidden:
+        raise ValueError("payload must not contain credentials; use the short-lived token environment variable")
+    if not value.get("op"):
+        raise ValueError("payload.op is required")
+    return value
+
+
+def write(url: str, token_env: str, payload: dict, timeout: int = 30) -> dict:
+    token = os.environ.get(token_env, "")
+    if not token:
+        raise ValueError(f"{token_env} is not set")
+    request = Request(url, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"), method="POST", headers={
+        "Accept": "application/json", "Content-Type": "application/json", "Authorization": f"Bearer {token}",
+    })
+    try:
+        with urlopen(request, timeout=timeout) as response:
+            raw = response.read().decode("utf-8", errors="replace")
+            status = response.status
+    except HTTPError as error:
+        raw = error.read().decode("utf-8", errors="replace")
+        status = error.code
+    except URLError as error:
+        raise RuntimeError("content host could not be reached") from error
+    try:
+        body = json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        body = {"error": "host returned non-JSON"}
+    if isinstance(body, dict):
+        for key in SENSITIVE_KEYS:
+            body.pop(key, None)
+    return {"status": status, "passed": 200 <= status < 300, "response": body}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    command = sub.add_parser("write", help="POST a validated content operation")
+    command.add_argument("--url", required=True)
+    command.add_argument("--token-env", default="MAGGIE_CONTENT_TOKEN")
+    command.add_argument("--payload", type=Path, required=True)
+    command.add_argument("--timeout", type=int, default=30)
+    args = parser.parse_args()
+    try:
+        payload = validate_payload(json.loads(args.payload.read_text(encoding="utf-8")))
+        result = write(args.url, args.token_env, payload, args.timeout)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0 if result["passed"] else 1
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"agent-content: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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_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"]}

package/bundled-tools/runtime/surface_coverage.py

@@ -0,0 +1,48 @@
+"""Coverage checks that follow the surface and locale changed by a release."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+SCHEMA = "maggie-surface-coverage.v1"
+
+
+def validate_contract(contract: object) -> dict[str, Any]:
+    errors: list[str] = []
+    if not isinstance(contract, dict):
+        return {"schemaVersion": SCHEMA, "passed": False, "errors": ["coverage contract must be an object"]}
+    if contract.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    surfaces = contract.get("surfaces")
+    if not isinstance(surfaces, list) or not surfaces:
+        errors.append("surfaces must be a non-empty list")
+        surfaces = []
+    seen: set[tuple[str, str]] = set()
+    for index, item in enumerate(surfaces):
+        if not isinstance(item, dict) or not item.get("name") or not isinstance(item.get("routes"), list) or not item["routes"] or not isinstance(item.get("locales"), list) or not item["locales"]:
+            errors.append(f"surfaces[{index}] needs name, routes, and locales")
+            continue
+        for locale in item["locales"]:
+            key = (str(item["name"]), str(locale))
+            if key in seen:
+                errors.append(f"duplicate surface/locale: {key[0]}/{key[1]}")
+            seen.add(key)
+    return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale in seen)}
+
+
+def compare(contract: dict[str, Any], observations: object) -> dict[str, Any]:
+    checked = validate_contract(contract)
+    if not checked["passed"]:
+        return {**checked, "observedPairs": [], "missing": [], "failed": []}
+    expected = {(str(item["name"]), str(locale)) for item in contract["surfaces"] for locale in item["locales"]}
+    observed: dict[tuple[str, str], dict[str, Any]] = {}
+    for item in observations if isinstance(observations, list) else []:
+        if not isinstance(item, dict):
+            continue
+        key = (str(item.get("surface") or ""), str(item.get("locale") or ""))
+        if key in expected:
+            observed[key] = item
+    missing = sorted(f"{surface}/{locale}" for surface, locale in expected - observed.keys())
+    failed = sorted(f"{surface}/{locale}" for (surface, locale), item in observed.items() if item.get("passed") is not True or int(item.get("status", 200)) >= 400)
+    return {"schemaVersion": SCHEMA, "passed": not missing and not failed, "expectedPairs": sorted(f"{surface}/{locale}" for surface, locale in expected), "observedPairs": sorted(f"{surface}/{locale}" for surface, locale in observed), "missing": missing, "failed": failed}

package/package.json

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