fix: document safe template default editing

packages/cli/src/registry/registryBlocks.test.ts

@@ -62,6 +62,10 @@ describe("registry blocks", () => {
 
       expect(contractFiles, templateId).toHaveLength(1);
       expect(composition, templateId).toBeDefined();
+      const editingContract = readFileSync(join(itemDir, "TEMPLATE.md"), "utf8");
+      expect(editingContract, templateId).toContain("## Safe editing mechanics");
+      expect(editingContract, templateId).toContain("set_template_variable_defaults");
+      expect(editingContract, templateId).toContain("HTML-entity-encoded JSON");
       const html = readFileSync(join(itemDir, composition?.path ?? ""), "utf8");
       const { document } = parseHTML(html);
       const declarations = JSON.parse(

registry/blocks/ai-chat-reveal/TEMPLATE.md

@@ -15,6 +15,10 @@ Only defaults declared in `data-composition-variables` are editable:
 
 Typed and streamed copy is length-locked to within 20% of the original.
 
+## Safe editing mechanics
+
+Call `set_template_variable_defaults` once with the existing variable ids and their new defaults. Do not directly edit or rewrite `index.html` or its `data-composition-variables` attribute; the imported declaration is HTML-entity-encoded JSON and the setter preserves that encoding. Never edit `__template_baseline__.html` or a duplicate composition file. For an image slot, pass only the token returned by an image tool. Validate after the setter succeeds.
+
 ## Protected
 
 Do not change chat chrome, keyboard, layout, palette, fonts, scene order, duration, timing, easing, typing cadence, or reveal logic. Do not replace any image outside the declared closing-card logo slot, and do not restyle the assistant interface to match the supplied website. This contract declares no color variables.

registry/blocks/chatgpt-exchange/TEMPLATE.md

@@ -14,6 +14,10 @@ Only defaults declared in `data-composition-variables` are editable:
 
 Typed and streamed copy is length-locked to within 20% of the original.
 
+## Safe editing mechanics
+
+Call `set_template_variable_defaults` once with the existing variable ids and their new defaults. Do not directly edit or rewrite `index.html` or its `data-composition-variables` attribute; the imported declaration is HTML-entity-encoded JSON and the setter preserves that encoding. Never edit `__template_baseline__.html` or a duplicate composition file. Validate after the setter succeeds.
+
 ## Protected
 
 Preserve the ChatGPT name, labels, suggestions, predictive keyboard text, header, composer, keyboard, icons, fonts, palette, layout, status UI, table geometry, scene structure, duration, timing, easing, typing cadence, and reveal behavior.

registry/blocks/claude-exchange/TEMPLATE.md

@@ -13,6 +13,10 @@ Only defaults declared in `data-composition-variables` are editable:
 
 Typed and streamed copy is length-locked to within 20% of the original.
 
+## Safe editing mechanics
+
+Call `set_template_variable_defaults` once with the existing variable ids and their new defaults. Do not directly edit or rewrite `index.html` or its `data-composition-variables` attribute; the imported declaration is HTML-entity-encoded JSON and the setter preserves that encoding. Never edit `__template_baseline__.html` or a duplicate composition file. Validate after the setter succeeds.
+
 ## Protected
 
 Preserve the Claude name, model name, usage notice, placeholders, disclaimer, source treatment, header, composer, icons, starburst, fonts, palette, layout, status UI, scene structure, duration, timing, easing, typing cadence, and reveal behavior.

registry/blocks/message-thread-reveal/TEMPLATE.md

@@ -15,6 +15,10 @@ Only defaults declared in `data-composition-variables` are editable:
 
 Keep replacement copy within 20% of the original length.
 
+## Safe editing mechanics
+
+Call `set_template_variable_defaults` once with the existing variable ids and their new defaults. Do not directly edit or rewrite `index.html` or its `data-composition-variables` attribute; the imported declaration is HTML-entity-encoded JSON and the setter preserves that encoding. Never edit `__template_baseline__.html` or a duplicate composition file. For an image slot, pass only the token returned by an image tool. Validate after the setter succeeds.
+
 ## Protected
 
 Preserve messaging chrome, bubble styling, receipts, palette, typography, geometry, scene structure, duration, timing, easing, and reveal behavior. Do not replace any image outside the declared link-card and closing-card logo slots, and do not recolor the messaging interface to match the supplied website.

registry/blocks/notes-reveal/TEMPLATE.md

@@ -14,6 +14,10 @@ Only defaults declared in `data-composition-variables` are editable:
 
 Typed copy is length-locked to within 20% of the original.
 
+## Safe editing mechanics
+
+Call `set_template_variable_defaults` once with the existing variable ids and their new defaults. Do not directly edit or rewrite `index.html` or its `data-composition-variables` attribute; the imported declaration is HTML-entity-encoded JSON and the setter preserves that encoding. Never edit `__template_baseline__.html` or a duplicate composition file. Validate after the setter succeeds.
+
 ## Protected
 
 Preserve notes chrome, paper treatment, fonts, colors, checklist geometry, scene structure, duration, timing, easing, handwriting motion, and reveal cadence.

registry/blocks/notification-cascade/TEMPLATE.md

@@ -14,6 +14,10 @@ Only defaults declared in `data-composition-variables` are editable:
 
 Keep replacement copy within 20% of the original length.
 
+## Safe editing mechanics
+
+Call `set_template_variable_defaults` once with the existing variable ids and their new defaults. Do not directly edit or rewrite `index.html` or its `data-composition-variables` attribute; the imported declaration is HTML-entity-encoded JSON and the setter preserves that encoding. Never edit `__template_baseline__.html` or a duplicate composition file. For an image slot, pass only the token returned by an image tool. Validate after the setter succeeds.
+
 ## Protected
 
 Do not change CSS, layout, backdrop, notification chrome, scene structure, duration, timing, easing, stacking, or reveal behavior. Do not replace any image outside the declared closing-card logo slot. Colors are protected because this template declares no color variables.

registry/blocks/share-sheet-carousel/TEMPLATE.md

@@ -15,6 +15,10 @@ Only defaults declared in `data-composition-variables` are editable:
 
 Keep replacement copy within 20% of the original length.
 
+## Safe editing mechanics
+
+Call `set_template_variable_defaults` once with the existing variable ids and their new defaults. Do not directly edit or rewrite `index.html` or its `data-composition-variables` attribute; the imported declaration is HTML-entity-encoded JSON and the setter preserves that encoding. Never edit `__template_baseline__.html` or a duplicate composition file. For an image slot, pass only the token returned by an image tool. Validate after the setter succeeds.
+
 ## Protected
 
 Preserve the share-sheet palette, typography, buttons, geometry, carousel layout, scene structure, duration, timing, easing, and tap animation. Do not replace any image outside the declared slide and logo slots, and do not recolor the operating-system interface.

registry/blocks/slack-notification-ad/TEMPLATE.md

@@ -13,6 +13,10 @@ Only defaults declared in `data-composition-variables` are editable:
 
 Keep replacement copy within 20% of the original length. The payoff logo must remain legible in the existing icon tile.
 
+## Safe editing mechanics
+
+Call `set_template_variable_defaults` once with the existing variable ids and their new defaults. Do not directly edit or rewrite `index.html` or its `data-composition-variables` attribute; the imported declaration is HTML-entity-encoded JSON and the setter preserves that encoding. Never edit `__template_baseline__.html` or a duplicate composition file. For the payoff logo, pass only the token returned by an image tool. Validate after the setter succeeds.
+
 ## Protected
 
 Preserve the Slack mark on request notifications, iOS status/date/clock labels, wallpaper, notification chrome, fonts, palette, stacking geometry, scene structure, duration, timing, easing, and arrival cadence.