@topy-ai/maggie 0.7.8 → 0.7.9

package/README.md

@@ -218,8 +218,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.8 update --project . --force
-npx @topy-ai/maggie@0.7.8 cleanup --project .
+npx @topy-ai/maggie@0.7.9 update --project . --force
+npx @topy-ai/maggie@0.7.9 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -229,7 +229,9 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.8 workflow adds the shared Google integrations runbook and
+The 0.7.9 workflow adds nested section-field contracts, renderer-backed
+examples, stable-ID preservation during migration, and disjoint page
+inventory guidance. It retains the shared Google integrations runbook and
 fail-closed provider capability matrix, alongside the installable MaggieDash admin distribution and
 audited CMS operations (`cms revisions`,
 `trash`, `restore`, `schedule`, `publish-due`, `duplicate`, `redirect`, and

package/bundled-contracts/maggiedash/README.md

@@ -25,6 +25,15 @@ frontend framework.
 - [`translation-cache-policy-v1.json`](translation-cache-policy-v1.json):
   restart-after-out-of-band-write evidence.
 
+The section registry is an adapter input rather than a fixed six-band list.
+Each registry entry must describe its purpose and limits, include a
+renderer-compatible `example`, and describe object-shaped repeated fields
+under `repeats.of`. Host-specific bands are valid when the host supplies the
+matching renderer and a preview at its real supported breakpoints. Template
+inventory adapters must count published pages once using disjoint page
+classes; child records such as service price options and saved arrangements
+must not be reported as pages.
+
 MaggieDash owns these contracts. Provider adapters may add namespaced metadata,
 but they may not change the required identity, status, provenance, or approval
 fields. Unknown fields must be preserved or reported as unsupported during

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

@@ -180,9 +180,26 @@ maggie dash sections keys --registry templates/maggiedash/section-registry.json
 ```
 
 The catalogue declares purpose, usage, placement, repeatability and layout
-limits. Over-limit copy is an editor note; unknown types fail validation.
+limits, renderer-owned examples, and the shape of repeated entries. A repeat
+may contain an object (`title`, `body`, `href`, and so on), not just a count;
+the nested limits are displayed to the planner and checked by `sections
+validate`. Over-limit copy is an editor note; unknown types fail validation.
+The starter registry is provider-neutral and extensible: a host may add its
+own renderer-backed bands, but every added band must have a real-renderer
+preview or an explicitly labelled example fallback at the supported
+breakpoints. Do not describe the vocabulary as a fixed number of bands.
+
 Translation keys use stable section IDs, with an array-index fallback only
-until the ordered migration is complete.
+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
+missing, duplicate, or target-conflicting ID. Never rebuild IDs from array
+position or overwrite existing translation keys.
+
+Keep data-owned values out of page copy. For example, a pricing band should
+store a service identifier or slug and let the live service/booking adapter
+render current options and prices. Inventory reports must classify each
+published page once into disjoint groups; price options, arrangements, and
+other child records are counts, not pages.
 
 After any script or direct adapter write to translation data, invalidate the
 running process before verification. Record the restart and run the rendering

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

@@ -1,12 +1,84 @@
 {
   "schemaVersion": "maggiedash-section-registry.v1",
-  "description": "The machine-readable section vocabulary used by page planners and editors.",
+  "description": "The provider-neutral starter vocabulary used by page planners and editors. Hosts may extend it with renderer-backed section types.",
   "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}]}
+    {
+      "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": "image", "usage": "The hero image rendered beside or behind the copy.", "limit": 500},
+        {"name": "imageAlt", "usage": "What the hero image shows for a reader who cannot see it.", "limit": 160},
+        {"name": "ctaLabel", "usage": "The action as a verb.", "limit": 30}
+      ],
+      "example": {"type": "hero", "title": "A clearer way to plan your next step", "intro": "Useful guidance for people who want to move forward with confidence.", "image": "https://images.unsplash.com/photo-1497366754035-f200968a6e72", "imageAlt": "A bright workspace with a table and plants", "ctaLabel": "Get started"}
+    },
+    {
+      "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": "Standalone paragraphs.", "limit": 0, "repeats": {"min": 1, "max": 4, "of": [{"name": "paragraph", "usage": "One paragraph of plain prose.", "limit": 400}]}},
+        {"name": "image", "usage": "An optional supporting image.", "limit": 500},
+        {"name": "imageAlt", "usage": "What the supporting image shows.", "limit": 160}
+      ],
+      "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": "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": 0, "repeats": {"min": 3, "max": 3, "of": [{"name": "title", "usage": "The point in a few words.", "limit": 60, "required": true}, {"name": "body", "usage": "One or two sentences.", "limit": 220}]}}
+      ],
+      "example": {"type": "cards", "heading": "A simple path from question to action", "items": [{"title": "Understand", "body": "See the essential context in one place."}, {"title": "Choose", "body": "Compare the options that fit your situation."}, {"title": "Act", "body": "Take the next step with a clear expectation."}]}
+    },
+    {
+      "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": 0, "repeats": {"min": 2, "max": 6, "of": [{"name": "label", "usage": "The destination page name.", "limit": 60, "required": true}, {"name": "href", "usage": "A real path on this site.", "limit": 200, "required": true}, {"name": "body", "usage": "One sentence on what is there.", "limit": 160}]}}
+      ],
+      "example": {"type": "links", "heading": "Keep exploring", "items": [{"label": "How it works", "href": "/how-it-works/", "body": "See the process from start to finish."}, {"label": "Frequently asked questions", "href": "/faq/", "body": "Find concise answers to common questions."}]}
+    },
+    {
+      "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": 0, "repeats": {"min": 2, "max": 8, "of": [{"name": "question", "usage": "A question a real visitor asks.", "limit": 140, "required": true}, {"name": "answer", "usage": "A direct, useful answer.", "limit": 600, "required": true}]}}
+      ],
+      "example": {"type": "faq", "heading": "Questions, answered", "items": [{"question": "What happens next?", "answer": "You will see the relevant options and can choose the next step."}, {"question": "Can I ask for help?", "answer": "Yes. Use the contact route and include the decision you are making."}]}
+    },
+    {
+      "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}
+      ],
+      "example": {"type": "cta", "heading": "Ready to take the next step?", "body": "Start with the option that best matches your goal.", "label": "Get started"}
+    }
   ]
 }

package/bundled-tools/runtime/maggie_sections.py

@@ -14,6 +14,35 @@ SCHEMA = "maggiedash-section-registry.v1"
 IDENTITY_SCHEMA = "maggiedash-section-identity.v1"
 
 
+def _validate_field(field: object, at: str, errors: list[str], *, nested: bool = False) -> None:
+    if not isinstance(field, dict) or not field.get("name"):
+        errors.append(f"{at} needs a name")
+        return
+    if not isinstance(field.get("limit"), int) or field["limit"] < 0:
+        errors.append(f"{at}.limit must be a non-negative integer")
+    if not str(field.get("usage") or "").strip():
+        errors.append(f"{at}.usage is required")
+    repeats = field.get("repeats")
+    if repeats is None:
+        return
+    if 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"{at}.repeats must declare valid min/max")
+        return
+    item_fields = repeats.get("of")
+    if not isinstance(item_fields, list) or not item_fields:
+        errors.append(f"{at}.repeats.of must be a non-empty field list")
+        return
+    nested_names: set[str] = set()
+    for item_index, item_field in enumerate(item_fields):
+        item_at = f"{at}.repeats.of[{item_index}]"
+        _validate_field(item_field, item_at, errors, nested=True)
+        if isinstance(item_field, dict) and item_field.get("name"):
+            name = str(item_field["name"])
+            if name in nested_names:
+                errors.append(f"duplicate repeated field: {name}")
+            nested_names.add(name)
+
+
 def validate_registry(value: object) -> dict[str, Any]:
     errors: list[str] = []
     if not isinstance(value, dict):
@@ -57,13 +86,10 @@ def validate_registry(value: object) -> dict[str, Any]:
             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")
+            _validate_field(field, field_at, errors)
+        example = section.get("example")
+        if not isinstance(example, dict) or example.get("type") != section_type:
+            errors.append(f"{at}.example must be an object with type {section_type}")
     return {"schemaVersion": SCHEMA, "passed": not errors, "errors": errors, "sectionTypes": sorted(seen)}
 
 
@@ -74,11 +100,39 @@ def catalogue(registry: dict[str, Any]) -> str:
         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 ""
+            suffix = ""
+            if isinstance(repeat, dict):
+                count = repeat["min"] if repeat["min"] == repeat["max"] else f"{repeat['min']}-{repeat['max']}"
+                nested = ", ".join(f"{item['name']} ≤{item['limit']}" for item in repeat.get("of", []) if isinstance(item, dict))
+                suffix = f" [{count} entries" + (f" of {{{nested}}}" if nested else "") + "]"
             lines.append(f"  - {field['name']} ≤{field['limit']} chars{suffix}: {field['usage']}")
     return "\n".join(lines)
 
 
+def _copy_notes(value: object, fields: list[dict[str, Any]], path: str, notes: list[dict[str, Any]]) -> None:
+    """Check a field value, including object-shaped repeated entries."""
+    for field in fields:
+        name = str(field.get("name"))
+        child = value.get(name) if isinstance(value, dict) else None
+        limit = int(field.get("limit", 0))
+        if isinstance(child, str) and limit and len(child) > limit:
+            notes.append({"at": f"{path}.{name}", "message": f"{len(child)} characters; layout limit is about {limit}"})
+        repeats = field.get("repeats")
+        if not isinstance(repeats, dict) or not isinstance(child, list):
+            continue
+        if not repeats["min"] <= len(child) <= repeats["max"]:
+            notes.append({"at": f"{path}.{name}", "message": f"{len(child)} entries; layout expects {repeats['min']}-{repeats['max']}"})
+        item_fields = [item for item in repeats.get("of", []) if isinstance(item, dict)]
+        for item_index, item in enumerate(child):
+            item_path = f"{path}.{name}[{item_index}]"
+            if isinstance(item, dict):
+                _copy_notes(item, item_fields, item_path, notes)
+            elif len(item_fields) == 1 and isinstance(item, str):
+                item_limit = int(item_fields[0].get("limit", 0))
+                if item_limit and len(item) > item_limit:
+                    notes.append({"at": item_path, "message": f"{len(item)} characters; layout limit is about {item_limit}"})
+
+
 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] = []
@@ -95,15 +149,7 @@ def copy_notes(registry: dict[str, Any], sections: object) -> dict[str, Any]:
         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']}"})
+        _copy_notes(section, [field for field in spec.get("fields", []) if isinstance(field, dict)], f"sections[{index}]", notes)
     return {"passed": not errors, "errors": errors, "notes": notes}
 
 
@@ -117,12 +163,16 @@ def new_section_id(existing: Iterable[str] = ()) -> str:
 
 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)
+    reserved = {str(item) for item in existing if str(item)}
+    taken: set[str] = set()
     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)
+        # Existing IDs belong to the source section list and must survive a
+        # migration. Only absent, duplicated, or target-conflicting IDs get a
+        # replacement. The old implementation put current IDs in `taken`
+        # before inspecting them and consequently rewrote every section.
+        if not current or current in taken or current in reserved:
+            section["id"] = new_section_id(taken | reserved)
         taken.add(str(section["id"]))
     return result
 

package/package.json

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