@topy-ai/maggie 0.7.10 → 0.7.11

package/README.md

@@ -218,8 +218,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.10 update --project . --force
-npx @topy-ai/maggie@0.7.10 cleanup --project .
+npx @topy-ai/maggie@0.7.11 update --project . --force
+npx @topy-ai/maggie@0.7.11 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -229,7 +229,7 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.10 workflow adds served-content equivalence checks, query-route
+The 0.7.11 workflow adds served-content equivalence checks, query-route
 baseline exclusions, changed-surface render evidence gates, generated skill
 catalogs, component-binding audits, and icon-family noise filtering. It also
 includes the 0.7.9 nested section-field contracts, renderer-backed examples,
@@ -251,6 +251,11 @@ observations; every route must include status, canonical, indexability, and
 required metadata checks. Agent content writes require an explicit approved
 origin, same-origin redirects, and recursive credential validation. Feedback
 submissions persist and print only an allowlisted acknowledgement. The release
+also adds image-aware content equivalence with explicit legacy-baseline
+limitations, locale checks for stored image alt text, a validated label/value
+`pairs` section, registry fan-out checks, idempotent reconciliation, per-step
+and section-scoped design evidence, catch-all source confidence, shell-safe VPS
+SSH guidance, and compatible feedback CLI examples. The release
 retains the existing service matching,
 localization, seed-manifest, lockfile/analytics, sitemap, deployment and
 rollback workflows.
@@ -492,13 +497,32 @@ maggie design validate-ui --project . \
 This reuses the host project's homepage shell and `DESIGN.md`; it does not
 copy reference branding, source code, private data, or provider facts.
 
-The remaining installable skills are `maggie-blog-bootstrap`, `maggie-dash`,
-`maggie-clone`, `maggie-clone-to-template`, `maggie-marketplace`,
-`maggie-template`, `maggie-design`, `maggie-ops`, `maggie-deployment`,
-`maggie-project-context`, `maggie-social-share`, and `maggie-memory`.
+For existing routes, in-place design jobs are resumable and can be narrowed to
+one section. Catch-all routes remain `unproven` until their content source is
+declared, and each completed step records evidence:
+
+```bash
+maggie design in-place --project . --route /pricing \
+  --content-source src/lib/pages/db.ts
+maggie design step in-place-<id> --project . \
+  --step inspect-route --evidence .maggie/evidence/route.json
+maggie design section --project . --route /pricing --section-id hours
+maggie design section-validate --before before.json --after after.json \
+  --section-id hours
+```
+
+MaggieDash section contracts include a compact `pairs` band for factual
+label/value rows. Validate required values, registry fan-out, locale sidecars,
+and idempotent repairs with `maggie dash sections validate`,
+`fanout-validate`, `locale-validate`, and `reconcile`.
 
-The package also includes `maggie-auth-reference` and `maggie-blog`. Use the
-stable commands below after installation:
+The package includes all 18 installable skills: `maggie-blog-bootstrap`,
+`maggie-dash`, `maggie-clone`, `maggie-clone-to-template`, `maggie-marketplace`,
+`maggie-template`, `maggie-design`, `maggie-ops`, `maggie-deployment`,
+`maggie-project-context`, `maggie-seo-geo`, `maggie-social-share`,
+`maggie-service-booking`, `maggie-memory`, `maggie-content-localization`,
+`maggie-feedback`, `maggie-auth-reference`, and `maggie-blog`. Use the stable
+commands below after installation:
 
 ```bash
 maggie auth reference --project . --confirm

package/bin/maggie.js

@@ -58,7 +58,7 @@ 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|remap-translations> [options]
+  maggie dash sections <validate|prompt|keys|remap-translations|fanout-validate|locale-validate|reconcile> [options]
   maggie dash components-audit --bindings-file FILE --sections-file FILE --pages-file FILE
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
@@ -85,6 +85,10 @@ Usage:
   maggie design validate-ui --project PATH --plan PATH --rendered-dir PATH --confirm
   maggie design icon-inventory --project PATH --source-dir src --runtime assets/icons.css --output docs/icon-inventory.json
   maggie design author --project PATH --route /about --purpose TEXT --audience TEXT --confirm
+  maggie design in-place --project PATH --route /pricing [--content-source PATH]
+  maggie design section --project PATH --route /pricing --section-id ID
+  maggie design section-validate --before FILE --after FILE --section-id ID
+  maggie design step <job-id> --step NAME --evidence FILE
   maggie auth reference --project PATH --confirm
   maggie auth check --project PATH [--production]
   maggie blog init|inspect|ingest|validate|publish|sitemap|settings|rollback|integration-state

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

@@ -181,6 +181,16 @@ maggie dash sections remap-translations \
   --translations-file .maggie/translations-legacy.json \
   --mapping-file .maggie/section-translation-map.json \
   --output .maggie/translations-v2.json --confirm
+
+# Validate locale sidecars for stored image alt text before publishing:
+maggie dash sections locale-validate \
+  --page-id <page-id> --sections-file .maggie/sections.json \
+  --translations-file .maggie/translations-by-locale.json --locale zh-Hant
+
+# Check that a host wired every registry type through all implementation surfaces:
+maggie dash sections fanout-validate \
+  --registry templates/maggiedash/section-registry.json \
+  --fanout-file templates/maggiedash/section-fanout.json
 ```
 
 The catalogue declares purpose, usage, placement, repeatability and layout
@@ -198,6 +208,15 @@ added band must have a real-renderer preview or an explicitly labelled example
 fallback at the supported breakpoints. Do not describe the starter vocabulary
 as a fixed number of bands.
 
+Required fields and repeated `pairs` values cannot be blank. The `pairs`
+starter band is intended for compact label/value facts such as opening hours;
+it is not a prose fallback. The registry fan-out manifest is a host integration
+contract: when a host adds a type, update its type union/schema, blank state,
+validation, readable-content extraction, renderer, and editor entry together,
+then run `fanout-validate`. `locale-validate` checks stored image-alt sidecars;
+the host adapter must write the section and all non-default locale rows in one
+transaction. The JSON report is evidence, not a database write.
+
 Translation keys use stable section IDs, with an array-index fallback only
 until the ordered migration is complete. Migration preserves unique IDs that
 already belong to the source section list; it generates a new ID only for a

package/bundled-skills/maggie-deployment/references/vps.md

@@ -37,6 +37,39 @@ systemd service, environment file, Nginx/TLS configuration, release root,
 database/media migration and backup strategy, health checks, and rollback
 owner before any remote mutation.
 
+### SSH and secret-source contract
+
+Use these canonical project variables when a VPS adapter is configured:
+
+| Variable | Meaning | Precedence |
+| --- | --- | --- |
+| `NOBLOX_DEPLOY_HOST` | VPS hostname or IP | explicit CLI flag, then project `.env`, then provider secret manager |
+| `NOBLOX_DEPLOY_SSH_USER` | SSH login user | explicit CLI flag, then project `.env`, then provider secret manager |
+| `NOBLOX_DEPLOY_SSH_PORT` | SSH port | explicit CLI flag, then project `.env`, then provider secret manager |
+| `NOBLOX_DEPLOY_SSH_KEY` | path or secret reference for the private key | explicit CLI flag, then project `.env`, then provider secret manager |
+| `NOBLOX_DEPLOY_ENV_FILE` | remote runtime env-file reference | provider secret manager only for the secret values |
+
+Legacy provider-specific names may be supported by an adapter, but must be
+mapped to these names in the local plan. The SSH key is preferred. Do not put
+an SSH password in a plan or command line; if password authentication is
+unavoidable, resolve `NOBLOX_DEPLOY_SSH_PASSWORD` at execution time from the
+approved secret manager and never echo it. Explicit CLI values override `.env`;
+`.env` overrides the provider adapter's default names. Values are validated by
+name and presence only, never printed.
+
+When composing SSH options in Bash or zsh, use an array so whitespace is not
+reinterpreted as extra arguments:
+
+```zsh
+ssh_opts=(-o StrictHostKeyChecking=accept-new -o BatchMode=yes)
+ssh "${ssh_opts[@]}" -p "$NOBLOX_DEPLOY_SSH_PORT" \
+  "$NOBLOX_DEPLOY_SSH_USER@$NOBLOX_DEPLOY_HOST" "systemctl is-active example"
+```
+
+Do not use `ssh_opts='-o StrictHostKeyChecking=accept-new -o BatchMode=yes'`
+followed by `ssh $ssh_opts ...`; zsh does not perform the word splitting that
+this pattern assumes.
+
 Create a local, secret-free plan before remote execution:
 
 ```bash

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

@@ -10,13 +10,33 @@ metadata:
 ## In-place route evidence
 
 `maggie design in-place --project . --route /example` resolves local source
-files and falls back to a discovered `[...slug]`/`[[...slug]]` file. That
-fallback is currently a source candidate, not proof that the concrete URL is
-served. Verify the route's HTTP response, content identity and framework route
+files and falls back to a discovered `[...slug]`/`[[...slug]]` file. A catch-all
+is recorded as `resolution: unproven` unless `--content-source` names the
+actual DB/content resolver. A source candidate is not proof that the concrete
+URL is served: verify the HTTP response, content identity, and framework route
 mapping before editing a shared catch-all. Next app-router catch-alls whose
-file is named `page.tsx` are not covered by this filename fallback. Capture
-responsive and interaction evidence separately; a plan in phase `ready` is
-not a successful browser test.
+file is named `page.tsx` are not covered by this filename fallback.
+
+In-place work is resumable. Record each completed step and its evidence:
+
+```bash
+maggie design step in-place-<id> --project . \
+  --step inspect-route --evidence .maggie/evidence/route.json
+maggie design status in-place-<id> --project .
+```
+
+The job becomes `done` only after every required step has evidence; `ready`
+means the contract exists, not that browser QA passed. For a one-band change,
+use section-scoped mode and validate before/after evidence:
+
+```bash
+maggie design section --project . --route /pricing --section-id hours
+maggie design section-validate --before before.json --after after.json \
+  --section-id hours
+```
+
+The validator requires the target section to change and proves that every
+other section remains unchanged.
 
 ## Source-to-runtime icon inventory
 

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

@@ -16,7 +16,7 @@ general lesson or regression test.
 ## Collect locally
 
 ```bash
-maggie feedback collect --project . \
+maggie feedback --project . collect \
   --skill maggie-clone-to-template --run-id clone-001 \
   --type bug --phase visual-qa \
   --summary "Mobile hero overflows the viewport" \
@@ -26,6 +26,7 @@ maggie feedback collect --project . \
   --reproduce "Run the clone workflow" \
   --reproduce "Open the mobile screenshot" \
   --screenshot ./screenshots/mobile.png
+# The equivalent `maggie feedback collect --project . ...` spelling is also supported.
 maggie feedback preview .maggie/feedback/<feedback-id>.json --format markdown
 ```
 

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

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": "maggiedash-section-fanout.v1",
+  "description": "Starter host contract: every registry type must be wired through each implementation surface. Hosts extending the registry must regenerate this file.",
+  "typeUnion": ["cards", "cta", "faq", "hero", "links", "pairs", "prose"],
+  "sectionSchema": ["cards", "cta", "faq", "hero", "links", "pairs", "prose"],
+  "blank": ["cards", "cta", "faq", "hero", "links", "pairs", "prose"],
+  "validation": ["cards", "cta", "faq", "hero", "links", "pairs", "prose"],
+  "textExtraction": ["cards", "cta", "faq", "hero", "links", "pairs", "prose"],
+  "renderer": ["cards", "cta", "faq", "hero", "links", "pairs", "prose"],
+  "editor": ["cards", "cta", "faq", "hero", "links", "pairs", "prose"]
+}

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

@@ -33,6 +33,19 @@
       ],
       "example": {"type": "prose", "heading": "Make the important part easier to understand", "paragraphs": ["Start with the decision your reader is trying to make.", "Then give them the context, evidence and next step in that order."]}
     },
+    {
+      "type": "pairs",
+      "purpose": "Shows named facts as a compact label-and-value band.",
+      "usage": "Use for opening hours, specifications, eligibility, or other factual pairs; never for long prose.",
+      "position": "body",
+      "repeatable": true,
+      "fields": [
+        {"name": "heading", "usage": "What the facts describe.", "limit": 90, "required": true},
+        {"name": "rows", "usage": "Non-empty factual label/value pairs.", "limit": 0, "repeats": {"min": 1, "max": 12, "of": [{"name": "label", "usage": "The fact name.", "limit": 70, "required": true}, {"name": "value", "usage": "The concise fact value; never blank.", "limit": 180, "required": true}]}},
+        {"name": "note", "usage": "Optional clarification below the facts.", "limit": 220}
+      ],
+      "example": {"type": "pairs", "heading": "At a glance", "rows": [{"label": "Typical response", "value": "Within one working day"}, {"label": "Available", "value": "Monday to Friday"}], "note": "Times may change on public holidays."}
+    },
     {
       "type": "cards",
       "purpose": "Presents parallel points side by side.",

package/bundled-tools/clis/maggie_dash.py

@@ -23,7 +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, remap_translations, section_id_migration, validate_registry, copy_notes  # noqa: E402
+from maggie_sections import catalogue, remap_translations, section_id_migration, validate_registry, copy_notes, validate_values, validate_fanout, reconcile_fields, validate_locale_coverage  # noqa: E402
 from route_imports import classify_bindings  # noqa: E402
 
 
@@ -334,6 +334,33 @@ def command_sections(args: argparse.Namespace) -> int:
             result["output"] = str(output)
         emit(result)
         return 0 if result["passed"] else 1
+    if args.sections_command == "fanout-validate":
+        registry = json.loads(Path(args.registry).resolve().read_text(encoding="utf-8"))
+        fanout = json.loads(Path(args.fanout_file).resolve().read_text(encoding="utf-8"))
+        checked = validate_registry(registry)
+        result = {**validate_fanout(registry, fanout), "registry": checked}
+        emit(result)
+        return 0 if result["passed"] and checked["passed"] else 1
+    if args.sections_command == "reconcile":
+        current = json.loads(Path(args.current_file).resolve().read_text(encoding="utf-8"))
+        desired = json.loads(Path(args.desired_file).resolve().read_text(encoding="utf-8"))
+        result = reconcile_fields(current, desired)
+        if result["passed"]:
+            require_confirm(args)
+            output = Path(args.output).resolve()
+            if output.exists() and not args.force:
+                raise ValueError(f"output exists; use --force to replace: {output}")
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(json.dumps(result["result"], indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            result["output"] = str(output)
+        emit(result)
+        return 0 if result["passed"] else 1
+    if args.sections_command == "locale-validate":
+        sections = json.loads(Path(args.sections_file).resolve().read_text(encoding="utf-8"))
+        translations = json.loads(Path(args.translations_file).resolve().read_text(encoding="utf-8"))
+        result = validate_locale_coverage(args.page_id, sections, translations, args.locale)
+        emit(result)
+        return 0 if result["passed"] else 1
     registry = json.loads(Path(args.registry).resolve().read_text(encoding="utf-8"))
     checked = validate_registry(registry)
     if not checked["passed"]:
@@ -344,9 +371,9 @@ def command_sections(args: argparse.Namespace) -> int:
         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)}
+        result = {**checked, "copy": copy_notes(registry, sections), "values": validate_values(registry, sections)}
         emit(result)
-        return 0 if result["copy"]["passed"] else 1
+        return 0 if result["copy"]["passed"] and result["values"]["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
@@ -484,6 +511,15 @@ def parser() -> argparse.ArgumentParser:
     sections_remap = sections_sub.add_parser("remap-translations", help="move an existing translation keyspace into stable section keys")
     sections_remap.add_argument("--translations-file", required=True); sections_remap.add_argument("--mapping-file", required=True); sections_remap.add_argument("--output", required=True); sections_remap.add_argument("--force", action="store_true"); sections_remap.add_argument("--confirm", action="store_true")
     sections_remap.set_defaults(func=command_sections)
+    sections_fanout = sections_sub.add_parser("fanout-validate", help="check registry type fan-out across host implementation surfaces")
+    sections_fanout.add_argument("--registry", required=True); sections_fanout.add_argument("--fanout-file", required=True)
+    sections_fanout.set_defaults(func=command_sections)
+    sections_reconcile = sections_sub.add_parser("reconcile", help="apply an idempotent compare-and-set JSON repair")
+    sections_reconcile.add_argument("--current-file", required=True); sections_reconcile.add_argument("--desired-file", required=True); sections_reconcile.add_argument("--output", required=True); sections_reconcile.add_argument("--force", action="store_true"); sections_reconcile.add_argument("--confirm", action="store_true")
+    sections_reconcile.set_defaults(func=command_sections)
+    sections_locale = sections_sub.add_parser("locale-validate", help="check locale sidecar coverage for stored image alt fields")
+    sections_locale.add_argument("--page-id", required=True); sections_locale.add_argument("--sections-file", required=True); sections_locale.add_argument("--translations-file", required=True); sections_locale.add_argument("--locale", action="append", required=True)
+    sections_locale.set_defaults(func=command_sections)
     sections_keys.set_defaults(func=command_sections)
     components = sub.add_parser("components-audit", help="classify route component bindings against live section/page inventories")
     components.add_argument("--bindings-file", required=True)

package/bundled-tools/clis/maggie_design.py

@@ -328,7 +328,7 @@ PHASES = [
         ],
     },
 ]
-DESIGN_JOB_PHASES = ("created", "preflight", "planned", "validated", "ready", "failed")
+DESIGN_JOB_PHASES = ("created", "preflight", "planned", "validated", "ready", "done", "failed")
 
 
 def existing_evidence(project: Path, target: dict[str, str]) -> list[str]:
@@ -506,7 +506,32 @@ def design_resume(project: Path, job_id: str) -> int:
     return run_design_job(job["urls"], project, job["clone_run"], force=True)[0]
 
 
-def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
+def _step_records(names: list[str]) -> list[dict[str, object]]:
+    return [{"name": name, "status": "pending", "evidence": None} for name in names]
+
+
+def design_step(project: Path, job_id: str, step: str, evidence: str) -> int:
+    """Record one piece of implementation evidence and make progress durable."""
+    path = design_job_path(project.resolve(), job_id)
+    if not path.exists():
+        raise ValueError(f"design job not found: {path}")
+    job = json.loads(path.read_text(encoding="utf-8"))
+    steps = job.get("steps", [])
+    target = next((item for item in steps if item.get("name") == step), None)
+    if target is None:
+        raise ValueError(f"unknown design step for {job_id}: {step}")
+    evidence_path = Path(evidence).expanduser().resolve()
+    if not evidence_path.exists():
+        raise ValueError(f"step evidence does not exist: {evidence_path}")
+    target.update({"status": "done", "evidence": str(evidence_path), "completedAt": datetime.now(timezone.utc).isoformat()})
+    job.setdefault("history", []).append({"event": "step-completed", "step": step, "evidence": str(evidence_path), "at": datetime.now(timezone.utc).isoformat()})
+    job["phase"] = "done" if all(item.get("status") == "done" for item in steps) else "ready"
+    save_design_job(project, job)
+    print(json.dumps({"jobId": job_id, "step": step, "status": target["status"], "phase": job["phase"], "evidence": str(evidence_path)}, indent=2))
+    return 0
+
+
+def in_place_job(project: Path, routes: list[str], force: bool = False, content_source: str = "") -> int:
     """Create a resumable redesign contract for existing first-party routes."""
     project = project.resolve()
     if not routes:
@@ -540,7 +565,13 @@ def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
                     break
         if not match:
             raise ValueError(f"existing route required for in-place redesign: {route}")
-        resolved_routes.append({"route": value, "source": str(match)})
+        catch_all = match.stem in {"[...slug]", "[[...slug]]"}
+        resolved_routes.append({
+            "route": value,
+            "source": str(match),
+            "resolution": "declared" if content_source else ("unproven" if catch_all else "direct-file"),
+            "contentSource": content_source or ("unproven catch-all route; declare the DB/content resolver before implementation" if catch_all else str(match)),
+        })
     digest = hashlib.sha256((str(project) + "\n" + "\n".join(routes)).encode()).hexdigest()[:12]
     job_id = f"in-place-{digest}"
     path = design_job_path(project, job_id)
@@ -558,7 +589,34 @@ def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
         "clone_run_required": False,
         "shared_tokens_required": True,
         "palette_change_allowed": False,
-        "required_steps": ["inspect-route", "apply-design-contract", "visual-review", "route-validation"],
+        "required_steps": ["inspect-route", "declare-content-source", "apply-design-contract", "visual-review", "route-validation"],
+        "steps": _step_records(["inspect-route", "declare-content-source", "apply-design-contract", "visual-review", "route-validation"]),
+        "history": [{"phase": "ready", "at": datetime.now(timezone.utc).isoformat()}],
+    }
+    save_design_job(project, job)
+    print(json.dumps(job, indent=2, ensure_ascii=False))
+    return 0
+
+
+def section_job(project: Path, route: str, section_id: str, force: bool = False) -> int:
+    """Create a focused design job with an unchanged-rest assertion."""
+    project = project.resolve()
+    if not route.startswith("/") or not section_id.strip():
+        raise ValueError("section mode requires a route starting with / and a section id")
+    contract = require_design_contract(project)
+    digest = hashlib.sha256((str(project) + "\n" + route + "\n" + section_id).encode()).hexdigest()[:12]
+    job_id = f"section-{digest}"
+    path = design_job_path(project, job_id)
+    if path.exists() and not force:
+        print(path.read_text(encoding="utf-8"), end="")
+        return 0
+    required = ["inspect-section", "capture-before", "implement-section", "capture-after", "assert-unchanged-rest", "route-validation"]
+    job = {
+        "id": job_id, "workflow": "maggie-design", "mode": "section-scoped", "phase": "ready",
+        "project": str(project), "route": route, "sectionId": section_id,
+        "design_contract": contract, "clone_run_required": False,
+        "scope": {"targetSection": section_id, "unchangedRestAssertion": "all non-target section content and structure hashes remain unchanged"},
+        "required_steps": required, "steps": _step_records(required),
         "history": [{"phase": "ready", "at": datetime.now(timezone.utc).isoformat()}],
     }
     save_design_job(project, job)
@@ -566,6 +624,25 @@ def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
     return 0
 
 
+def validate_section_evidence(before_path: Path, after_path: Path, section_id: str) -> dict[str, object]:
+    """Compare section-scoped evidence and prove the rest stayed unchanged."""
+    before = json.loads(before_path.resolve().read_text(encoding="utf-8"))
+    after = json.loads(after_path.resolve().read_text(encoding="utf-8"))
+    before_sections = {str(item.get("id")): item for item in before.get("sections", []) if isinstance(item, dict) and item.get("id")}
+    after_sections = {str(item.get("id")): item for item in after.get("sections", []) if isinstance(item, dict) and item.get("id")}
+    errors = []
+    if section_id not in before_sections or section_id not in after_sections:
+        errors.append("target section is missing from before or after evidence")
+    unchanged = sorted(section for section in before_sections.keys() & after_sections.keys() if section != section_id and before_sections[section] != after_sections[section])
+    if unchanged:
+        errors.append("non-target sections changed: " + ", ".join(unchanged))
+    missing_rest = sorted((before_sections.keys() ^ after_sections.keys()) - {section_id})
+    if missing_rest:
+        errors.append("non-target section set changed: " + ", ".join(missing_rest))
+    target_changed = section_id in before_sections and section_id in after_sections and before_sections[section_id] != after_sections[section_id]
+    return {"schemaVersion": "maggie-section-evidence.v1", "passed": not errors and target_changed, "targetSection": section_id, "targetChanged": target_changed, "unchangedRest": not unchanged and not missing_rest, "changedNonTargetSections": unchanged, "errors": errors + ([] if target_changed else ["target section did not change"]), "before": str(before_path.resolve()), "after": str(after_path.resolve())}
+
+
 def author_job(project: Path, route: str, purpose: str, audience: str, brief_file: Path | None, confirm: bool) -> int:
     """Create an original page brief without requiring an external source URL."""
     project = project.resolve()
@@ -592,6 +669,20 @@ def author_job(project: Path, route: str, purpose: str, audience: str, brief_fil
 
 
 def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] in {"-h", "--help"}:
+        print("""usage: maggie_design.py <command> [options]
+
+commands:
+  run          run the complete clone-backed design workflow
+  in-place     create a resumable redesign contract for existing routes
+  section      create a section-scoped redesign contract
+  step         record completion evidence for one design step
+  status       show a design job and its per-step progress
+  resume       restart a failed design workflow
+  author       plan an original first-party page
+  reference-ui, init, validate-ui, rebrand, review
+""")
+        return 0
     if len(sys.argv) > 1 and sys.argv[1] == "reference-ui":
         command = argparse.ArgumentParser(description="Record sanitized blog/service UI evidence from a read-only reference project.")
         command.add_argument("--project", type=Path, default=Path.cwd())
@@ -653,13 +744,51 @@ def main() -> int:
         in_place = argparse.ArgumentParser(description="Create an in-place redesign contract for existing first-party routes.")
         in_place.add_argument("--project", type=Path, default=Path.cwd())
         in_place.add_argument("--route", action="append", required=True, help="existing route, for example /pricing")
+        in_place.add_argument("--content-source", default="", help="declared DB/content resolver or source manifest for catch-all routes")
         in_place.add_argument("--force", action="store_true")
         args = in_place.parse_args(sys.argv[2:])
         try:
-            return in_place_job(args.project, args.route, args.force)
+            return in_place_job(args.project, args.route, args.force, args.content_source)
         except (OSError, ValueError, json.JSONDecodeError) as error:
             print(f"BLOCKED: maggie-design in-place: {error}", file=sys.stderr)
             return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "section":
+        section = argparse.ArgumentParser(description="Create a section-scoped redesign contract with an unchanged-rest assertion.")
+        section.add_argument("--project", type=Path, default=Path.cwd())
+        section.add_argument("--route", required=True)
+        section.add_argument("--section-id", required=True)
+        section.add_argument("--force", action="store_true")
+        args = section.parse_args(sys.argv[2:])
+        try:
+            return section_job(args.project, args.route, args.section_id, args.force)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design section: {error}", file=sys.stderr)
+            return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "step":
+        step = argparse.ArgumentParser(description="Record evidence for one design workflow step.")
+        step.add_argument("job_id")
+        step.add_argument("--project", type=Path, default=Path.cwd())
+        step.add_argument("--step", required=True)
+        step.add_argument("--evidence", type=Path, required=True)
+        args = step.parse_args(sys.argv[2:])
+        try:
+            return design_step(args.project, args.job_id, args.step, str(args.evidence))
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design step: {error}", file=sys.stderr)
+            return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "section-validate":
+        section_validate = argparse.ArgumentParser(description="Validate before/after evidence for one section and assert the rest is unchanged.")
+        section_validate.add_argument("--before", type=Path, required=True)
+        section_validate.add_argument("--after", type=Path, required=True)
+        section_validate.add_argument("--section-id", required=True)
+        args = section_validate.parse_args(sys.argv[2:])
+        try:
+            result = validate_section_evidence(args.before, args.after, args.section_id)
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+            return 0 if result["passed"] else 1
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design section-validate: {error}", file=sys.stderr)
+            return 1
     if len(sys.argv) > 1 and sys.argv[1] == "author":
         author = argparse.ArgumentParser(description="Create an original first-party page brief and route plan.")
         author.add_argument("--project", type=Path, default=Path.cwd())

package/bundled-tools/clis/maggie_feedback.py

@@ -204,6 +204,9 @@ def main() -> int:
     parser.add_argument("--project", default=".")
     sub = parser.add_subparsers(dest="command", required=True)
     collect_parser = sub.add_parser("collect")
+    # Accept the project flag after the subcommand as shown in the public
+    # examples. argparse otherwise only accepts the global flag before it.
+    collect_parser.add_argument("--project", default=argparse.SUPPRESS)
     collect_parser.add_argument("--skill", default="")
     collect_parser.add_argument("--run-id", default="")
     collect_parser.add_argument("--run-report")

package/bundled-tools/clis/site_audit.py

@@ -168,7 +168,17 @@ def audit_page(url: str, html: str, status: int, content_type: str, expected_lan
             "headings": page.headings,
             "paragraphs": page.paragraphs,
             "links": [{"href": urljoin(url, link["href"]), "text": link["text"]} for link in page.links],
-            "contentHash": hashlib.sha256(json.dumps({"headings": page.headings, "paragraphs": page.paragraphs, "links": page.links}, sort_keys=True, ensure_ascii=False).encode()).hexdigest(),
+            # Images and their alt text are readable content too. Keeping them
+            # in this contract prevents a prose-only migration from silently
+            # dropping the visual content of a page.
+            "images": [{"src": urljoin(url, image["src"]), "alt": image.get("alt")} for image in page.images],
+            "imageAlts": [image.get("alt") for image in page.images],
+            "contentHash": hashlib.sha256(json.dumps({
+                "headings": page.headings,
+                "paragraphs": page.paragraphs,
+                "links": [{"href": urljoin(url, link["href"]), "text": link["text"]} for link in page.links],
+                "images": [{"src": urljoin(url, image["src"]), "alt": image.get("alt")} for image in page.images],
+            }, sort_keys=True, ensure_ascii=False).encode()).hexdigest(),
         },
         "robots": not robots or not any(token in {"noindex", "none", "nofollow"} for token in robots_tokens),
         "robots_directives": robots,

package/bundled-tools/runtime/maggie_sections.py

@@ -13,6 +13,9 @@ from typing import Any, Iterable
 SCHEMA = "maggiedash-section-registry.v1"
 IDENTITY_SCHEMA = "maggiedash-section-identity.v1"
 TRANSLATION_REMAP_SCHEMA = "maggiedash-translation-remap.v1"
+FANOUT_SCHEMA = "maggiedash-section-fanout.v1"
+RECONCILE_SCHEMA = "maggiedash-reconcile.v1"
+LOCALE_SCHEMA = "maggiedash-locale-coverage.v1"
 
 
 def _validate_field(field: object, at: str, errors: list[str], *, nested: bool = False) -> None:
@@ -154,6 +157,72 @@ def copy_notes(registry: dict[str, Any], sections: object) -> dict[str, Any]:
     return {"passed": not errors, "errors": errors, "notes": notes}
 
 
+def validate_values(registry: dict[str, Any], sections: object) -> dict[str, Any]:
+    """Validate required scalar and repeated values, including pairs rows."""
+    if not isinstance(sections, list):
+        return {"passed": False, "errors": ["sections must be a list"]}
+    specs = {str(item.get("type")): item for item in registry.get("sections", []) if isinstance(item, dict)}
+    errors: list[str] = []
+
+    def check_fields(value: object, fields: list[dict[str, Any]], path: str) -> None:
+        for field in fields:
+            name = str(field.get("name"))
+            child = value.get(name) if isinstance(value, dict) else None
+            at = f"{path}.{name}"
+            if field.get("required") and (child is None or (isinstance(child, str) and not child.strip())):
+                errors.append(f"{at} is required and cannot be blank")
+            repeats = field.get("repeats")
+            if not isinstance(repeats, dict) or not isinstance(child, list):
+                continue
+            if not repeats["min"] <= len(child) <= repeats["max"]:
+                errors.append(f"{at} must contain {repeats['min']}-{repeats['max']} entries")
+            child_fields = [item for item in repeats.get("of", []) if isinstance(item, dict)]
+            for index, item in enumerate(child):
+                if isinstance(item, dict):
+                    check_fields(item, child_fields, f"{at}[{index}]")
+                elif len(child_fields) == 1 and child_fields[0].get("required") and not str(item).strip():
+                    errors.append(f"{at}[{index}] is required and cannot be blank")
+
+    for index, section in enumerate(sections):
+        if not isinstance(section, dict):
+            errors.append(f"sections[{index}] must be an object")
+            continue
+        spec = specs.get(str(section.get("type")))
+        if spec:
+            check_fields(section, [field for field in spec.get("fields", []) if isinstance(field, dict)], f"sections[{index}]")
+    return {"passed": not errors, "errors": errors}
+
+
+def translation_key_paths(page_id: str, sections: object, field_names: tuple[str, ...] = ("imageAlt",)) -> list[str]:
+    """Find stored section fields that need a locale sidecar value."""
+    if not isinstance(sections, list):
+        return []
+    paths: list[str] = []
+
+    def walk(value: object, path: str) -> None:
+        if isinstance(value, dict):
+            for key, child in value.items():
+                child_path = f"{path}.{key}"
+                if key in field_names and isinstance(child, str) and child.strip():
+                    paths.append(child_path)
+                walk(child, child_path)
+        elif isinstance(value, list):
+            for index, child in enumerate(value):
+                walk(child, f"{path}.{index}")
+
+    for index, section in enumerate(sections):
+        walk(section, f"page.{page_id}.sections.{section_key(section, index)}")
+    return paths
+
+
+def validate_locale_coverage(page_id: str, sections: object, translations: object, locales: Iterable[str]) -> dict[str, Any]:
+    """Require non-default locale rows for every declared translatable field."""
+    paths = translation_key_paths(page_id, sections)
+    values = translations if isinstance(translations, dict) else {}
+    missing = [{"locale": locale, "key": key} for locale in locales for key in paths if not isinstance(values.get(locale), dict) or not str(values[locale].get(key) or "").strip()]
+    return {"schemaVersion": LOCALE_SCHEMA, "passed": not missing, "pageId": page_id, "requiredKeys": paths, "missing": missing, "writePolicy": "section row and locale rows must be committed in one transaction"}
+
+
 def new_section_id(existing: Iterable[str] = ()) -> str:
     taken = set(existing)
     while True:
@@ -226,3 +295,39 @@ def remap_translations(translations: object, mappings: object) -> dict[str, Any]
     return {"schemaVersion": TRANSLATION_REMAP_SCHEMA, "passed": not errors, "errors": errors,
             "translations": result, "applied": applied, "unmapped": sorted(unmapped),
             "mappingCount": len(valid)}
+
+
+def validate_fanout(registry: dict[str, Any], fanout: object) -> dict[str, Any]:
+    """Ensure every registry type is wired through each host implementation surface.
+
+    A registry is declarative, but hosts still need a type union/schema,
+    blank-state logic, validation, text extraction, renderer, and editor
+    affordance. This contract makes a missing fan-out edit fail loudly.
+    """
+    if not isinstance(fanout, dict) or fanout.get("schemaVersion") != FANOUT_SCHEMA:
+        return {"schemaVersion": FANOUT_SCHEMA, "passed": False, "errors": [f"fanout schemaVersion must be {FANOUT_SCHEMA}"]}
+    types = {str(item.get("type")) for item in registry.get("sections", []) if isinstance(item, dict)}
+    surfaces = ("typeUnion", "sectionSchema", "blank", "validation", "textExtraction", "renderer", "editor")
+    missing: list[dict[str, str]] = []
+    for surface in surfaces:
+        values = fanout.get(surface)
+        declared = set(values) if isinstance(values, list) else set(values.keys()) if isinstance(values, dict) else set()
+        for section_type in sorted(types - declared):
+            missing.append({"type": section_type, "surface": surface})
+    return {"schemaVersion": FANOUT_SCHEMA, "passed": not missing, "errors": [f"{item['type']} missing {item['surface']} fan-out" for item in missing], "sectionTypes": sorted(types), "missing": missing}
+
+
+def reconcile_fields(current: object, desired: object) -> dict[str, Any]:
+    """Return an idempotent compare-and-set result for repair scripts."""
+    if not isinstance(current, dict) or not isinstance(desired, dict):
+        return {"schemaVersion": RECONCILE_SCHEMA, "passed": False, "errors": ["current and desired must be objects"]}
+    result = copy.deepcopy(current)
+    changed: list[str] = []
+    already_correct: list[str] = []
+    for key, value in desired.items():
+        if current.get(key) == value:
+            already_correct.append(str(key))
+        else:
+            result[key] = copy.deepcopy(value)
+            changed.append(str(key))
+    return {"schemaVersion": RECONCILE_SCHEMA, "passed": True, "changed": changed, "alreadyCorrect": already_correct, "result": result, "convergent": True}

package/bundled-tools/runtime/site_baseline.py

@@ -64,9 +64,15 @@ def compare(baseline: dict, report: dict) -> dict:
             changes.append({"url": url, "fields": fields})
     expected_content = baseline.get("content", {})
     content_changes = []
+    content_not_compared = []
     if expected_content:
         for url in sorted(expected_content.keys() & current_content.keys()):
-            fields = sorted(key for key in expected_content[url].keys() | current_content[url].keys() if expected_content[url].get(key) != current_content[url].get(key))
+            expected_contract = expected_content[url]
+            current_contract = current_content[url]
+            ignored_legacy_fields = {"images", "imageAlts"} if "images" not in expected_contract else set()
+            fields = sorted(key for key in expected_contract.keys() | current_contract.keys() if key not in ignored_legacy_fields and expected_contract.get(key) != current_contract.get(key))
+            if "images" not in expected_contract:
+                content_not_compared.append({"url": url, "fields": ["images", "imageAlts"], "reason": "baseline predates image content contract"})
             if fields:
                 content_changes.append({"url": url, "fields": fields})
         missing_content = sorted(expected_content.keys() - current_content.keys())
@@ -75,6 +81,7 @@ def compare(baseline: dict, report: dict) -> dict:
     return {"passed": not errors and not added and not removed and not changes and not content_changes,
             "errors": errors, "added": added, "removed": removed, "changed": changes,
             "contentChanged": content_changes,
+            "contentNotCompared": content_not_compared,
             "excludedQueryUrls": query_urls}
 
 

package/package.json

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