@easysociable/cli 0.1.1 → 0.1.3

package/skills/easysociable-template/references/PLATFORM_SPECS.md

@@ -120,12 +120,20 @@ No platform chrome assumptions. Still pick a concrete preset (`1:1`, `4:5`, `3:4
 
 ---
 
+## Layout Family (multi-platform create)
+
+Creating a template **defaults** to a Layout Family with one master page + derived presets — see `workflows/MULTI_PLATFORM_FAMILY.md`.
+
+Same-preset platforms share one variant tree (**Instagram + Threads → `4:5`**). Do not invent a second 4:5 page for Threads.
+
+Typical vertical bucket when master is `3:4` (Xiaohongshu): also derive `4:5`, `9:16`, `1:1`. Absolute layout cannot share one AST across those presets — hand-tune each variant after derive.
+
 ## Selection rules for Agents
 
-1. If user names one platform → set `platforms: [that]` and use that platform’s **Recommended** row.  
-2. If user names several → intersection of workable presets; if empty, ask them to pick a primary platform or accept letterboxing.  
+1. If user names one platform only → set master `platforms: [that]` + that platform’s **Recommended** row; skip family derive unless they later ask for more.  
+2. If user names several **or** does not limit platforms → pick a master Recommended canvas, then derive the default vertical targets (`MULTI_PLATFORM_FAMILY.md`).  
 3. Never mix presets across slides of one deck without an explicit user choice (IG/Threads/TikTok crop to first slide).  
-4. Put platform + preset into P0 `selectionMetadata` before Publish.  
+4. Each family variant’s P0 `selectionMetadata` must list only platforms that match that page’s `canvasPreset`.  
 5. Specs above are **practical authoring targets** (2026 guides + Meta help for IG). Re-verify if a platform announces breaking crop changes.
 
 ## Sources (research snapshot)

package/skills/easysociable-template/references/THEME_TOKENS.md

@@ -15,7 +15,7 @@ Theme is the **skin** (color / font / surface). The page template is the **struc
 
 ## Gateway payload (`theme_schema_v1`)
 
-Gateway persists `themeTokens` in `TemplateTheme.tokens`. When `palette` is present, `theme_schema_version` is `theme_schema_v2`. The `colors` object includes six semantic roles: `canvas`, `text`, `accent`, `muted`, `primary`, `border`.
+Authoring persists Studio preview tokens on **`TemplateLayoutFamily.preview_tokens`** (not a TemplateTheme row). Fill/render uses Brand `themeSnapshot` first, then family preview tokens, then a service default (ADR-0033). When `palette` is present, treat tokens as `theme_schema_v2`. The `colors` object includes six semantic roles: `canvas`, `text`, `accent`, `muted`, `primary`, `border`.
 
 ```ts
 {

package/skills/easysociable-template/references/fixtures/image-reference.design-plan.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": "design_plan_v2_1",
+  "sourceKind": "image_reference",
+  "intent": {
+    "jobToBeDone": "Rebuild soft-card landing convert poster from reference",
+    "primaryPlatform": "instagram",
+    "canvas": { "width": 1080, "height": 1350 }
+  },
+  "philosophy": {
+    "movementName": "Soft Ledger",
+    "space": "Stacked rounded cards with generous outer margin",
+    "color": "Warm cream canvas, dark ink, soft peach accents",
+    "rhythm": "Even card gaps; one tip band; bottom CTA",
+    "composition": "Title → dual soft cards with figures → tip → CTA",
+    "typographyAccent": "Bold title; quieter body in cards",
+    "craftBar": "Match reference geometry; image slots for figures; no CSS fake people"
+  },
+  "concepts": [
+    {
+      "id": "soft-ledger-rebuild",
+      "name": "Soft ledger rebuild",
+      "rationale": "Reference already fixes composition",
+      "philosophyExpression": "Same stack and figure wells as referenceSpec",
+      "visualMotif": "soft rounded cards",
+      "layout": "title, two cards, tip, cta",
+      "hierarchy": "title > card copy > tip > cta",
+      "typography": "bold title, medium body",
+      "colorStrategy": "cream + ink from reference",
+      "assetStrategy": "two image slots for person illustrations",
+      "risks": ["figure crops"]
+    }
+  ],
+  "selectedConceptId": "soft-ledger-rebuild",
+  "selectionReason": "Single reconstruction of the supplied reference",
+  "referenceSpec": {
+    "stackOrder": ["title", "soft-card-1", "soft-card-2", "tip", "cta"],
+    "margins": "~48px outer",
+    "gaps": "~24px between cards",
+    "radii": "cards 16px; figure wells 12px",
+    "typeScale": "title ~42/bold; body ~22; tip ~18"
+  },
+  "referenceImageInventory": [
+    {
+      "label": "Left soft-card person illustration",
+      "slotKey": "image_0",
+      "imageRole": "hero",
+      "boxApprox": "left mid ~280×320"
+    },
+    {
+      "label": "Right soft-card person illustration",
+      "slotKey": "image_1",
+      "imageRole": "hero",
+      "boxApprox": "right mid ~280×320"
+    }
+  ],
+  "assetPlan": [
+    {
+      "role": "hero",
+      "source": "user_upload",
+      "required": true,
+      "slotKey": "image_0",
+      "description": "Left soft-card person illustration — empty image-slot frame",
+      "treatment": "Match reference box; placeholder until account imageId fill"
+    },
+    {
+      "role": "hero",
+      "source": "user_upload",
+      "required": true,
+      "slotKey": "image_1",
+      "description": "Right soft-card person illustration — empty image-slot frame",
+      "treatment": "Match reference box; placeholder until account imageId fill"
+    }
+  ]
+}

package/skills/easysociable-template/references/fixtures/image-reference.visual-qa.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": "visual_qa_v2_1",
+  "draftId": "draft_fixture_ref",
+  "iteration": 0,
+  "sourceKind": "image_reference",
+  "screenshotEvidence": "/tmp/studio-render-fixture.png",
+  "referenceCompare": {
+    "performed": true,
+    "geometryMatch": true,
+    "imageSlotsMatchInventory": true,
+    "notes": "Fixture — stack and image_0/image_1 frames match referenceSpec"
+  },
+  "hardFailures": [],
+  "scores": {
+    "hierarchy": 18,
+    "composition": 14,
+    "spacingAlignment": 14,
+    "typography": 14,
+    "colorContrast": 9,
+    "assetRelevance": 9,
+    "contentResilience": 8,
+    "editability": 5
+  },
+  "total": 91,
+  "verdict": "pass",
+  "issues": [],
+  "changesMade": []
+}

package/skills/easysociable-template/scripts/validate-design-v2.mjs

@@ -126,6 +126,67 @@ function validateThemeTokensBlock(tokens, label) {
     errors.push(`${label}.surfaces.shadow is required`)
 }
 
+const REFERENCE_SPEC_FIELDS = ['margins', 'gaps', 'radii', 'typeScale']
+const IMAGE_INVENTORY_ROLES = new Set(['hero', 'screenshot', 'avatar', 'product'])
+const IMAGE_SLOT_SOURCES = new Set(['user_upload', 'brand_kit', 'external_photo', 'generated'])
+const SLOT_KEY_RE = /^image_\d+$/
+
+function validateReferenceImageFields(plan, assetPlan) {
+  const spec = plan.referenceSpec
+  if (!spec || typeof spec !== 'object') {
+    errors.push('referenceSpec is required when sourceKind is image_reference')
+  }
+  else {
+    if (!Array.isArray(spec.stackOrder) || spec.stackOrder.length < 1)
+      errors.push('referenceSpec.stackOrder must be a non-empty array')
+    else {
+      spec.stackOrder.forEach((entry, index) => {
+        if (!nonEmpty(entry))
+          errors.push(`referenceSpec.stackOrder[${index}] must be a non-empty string`)
+      })
+    }
+    REFERENCE_SPEC_FIELDS.forEach((field) => {
+      if (!nonEmpty(spec[field]))
+        errors.push(`referenceSpec.${field} is required`)
+    })
+  }
+
+  const inventory = plan.referenceImageInventory
+  if (!Array.isArray(inventory)) {
+    errors.push('referenceImageInventory must be an array when sourceKind is image_reference (empty if no pictures)')
+    return
+  }
+
+  const seenSlotKeys = new Set()
+  inventory.forEach((item, index) => {
+    if (!nonEmpty(item?.label))
+      errors.push(`referenceImageInventory[${index}].label is required`)
+    if (!SLOT_KEY_RE.test(item?.slotKey ?? ''))
+      errors.push(`referenceImageInventory[${index}].slotKey must match image_N`)
+    else if (seenSlotKeys.has(item.slotKey))
+      errors.push(`referenceImageInventory duplicate slotKey: ${item.slotKey}`)
+    else
+      seenSlotKeys.add(item.slotKey)
+    if (!IMAGE_INVENTORY_ROLES.has(item?.imageRole))
+      errors.push(`referenceImageInventory[${index}].imageRole must be hero|screenshot|avatar|product`)
+    if (!nonEmpty(item?.boxApprox))
+      errors.push(`referenceImageInventory[${index}].boxApprox is required`)
+  })
+
+  if (!Array.isArray(assetPlan))
+    return
+
+  seenSlotKeys.forEach((slotKey) => {
+    const match = assetPlan.find((asset) => asset?.slotKey === slotKey)
+    if (!match) {
+      errors.push(`assetPlan must include an entry with slotKey ${slotKey} for each inventoried picture`)
+      return
+    }
+    if (!IMAGE_SLOT_SOURCES.has(match.source))
+      errors.push(`assetPlan entry for ${slotKey} must use user_upload|brand_kit|external_photo|generated (not css_svg stand-in)`)
+  })
+}
+
 function validateDesignPlan(plan) {
   const allowedSourceKinds = new Set(['text_brief', 'image_reference'])
   const allowedRoles = new Set(['background', 'hero', 'decorative', 'avatar', 'logo', 'icon'])
@@ -206,8 +267,13 @@ function validateDesignPlan(plan) {
         errors.push(`assetPlan[${index}].required must be boolean`)
       if (!nonEmpty(asset?.description))
         errors.push(`assetPlan[${index}].description is required`)
+      if (asset?.slotKey !== undefined && !SLOT_KEY_RE.test(asset.slotKey))
+        errors.push(`assetPlan[${index}].slotKey must match image_N when present`)
     })
   }
+
+  if (plan.sourceKind === 'image_reference')
+    validateReferenceImageFields(plan, plan.assetPlan)
 }
 
 function validateThemeTokens(theme) {
@@ -252,6 +318,33 @@ function validateThemeTokens(theme) {
   }
 }
 
+function validateReferenceCompare(qa) {
+  const compare = qa.referenceCompare
+  if (qa.sourceKind !== 'image_reference') {
+    if (compare !== undefined && (compare === null || typeof compare !== 'object'))
+      errors.push('referenceCompare must be an object when present')
+    return
+  }
+  if (!compare || typeof compare !== 'object') {
+    errors.push('referenceCompare is required when sourceKind is image_reference')
+    return
+  }
+  if (typeof compare.performed !== 'boolean')
+    errors.push('referenceCompare.performed must be boolean')
+  if (typeof compare.geometryMatch !== 'boolean')
+    errors.push('referenceCompare.geometryMatch must be boolean')
+  if (typeof compare.imageSlotsMatchInventory !== 'boolean')
+    errors.push('referenceCompare.imageSlotsMatchInventory must be boolean')
+  if (qa.verdict === 'pass') {
+    if (compare.performed !== true)
+      errors.push('pass verdict for image_reference requires referenceCompare.performed true')
+    if (compare.geometryMatch !== true)
+      errors.push('pass verdict for image_reference requires referenceCompare.geometryMatch true')
+    if (compare.imageSlotsMatchInventory !== true)
+      errors.push('pass verdict for image_reference requires referenceCompare.imageSlotsMatchInventory true')
+  }
+}
+
 function validateVisualQa(qa) {
   const maxima = {
     hierarchy: 20,
@@ -278,6 +371,8 @@ function validateVisualQa(qa) {
     errors.push('changesMade must be an array')
   if (!['pass', 'revise'].includes(qa.verdict))
     errors.push('verdict must be pass or revise')
+  if (qa.sourceKind !== undefined && !['text_brief', 'image_reference'].includes(qa.sourceKind))
+    errors.push('sourceKind must be text_brief or image_reference when present')
 
   let calculatedTotal = 0
   for (const [field, maximum] of Object.entries(maxima)) {
@@ -298,6 +393,8 @@ function validateVisualQa(qa) {
   }
   if (qa.verdict === 'revise' && calculatedTotal >= 80 && qa.hardFailures?.length === 0)
     errors.push('revise verdict conflicts with a passing score and no hardFailures')
+
+  validateReferenceCompare(qa)
 }
 
 if (value?.schemaVersion === 'design_plan_v2_1')

package/skills/easysociable-template/workflows/ASSET_PLAN.md

@@ -24,7 +24,8 @@ Choose the first adequate option:
 - Roles: `background | hero | decorative | avatar | logo | icon`.
 - For `external_photo` / `template_icon_catalog` / `gradient_catalog`: discovery → bounded showcase → **user confirm** → materialize. Unselected → no EasySociable write.
 - **`role: icon` ⇒ `source` MUST be `template_icon_catalog`** (unless catalog failed and user approved degrade). Never invent path SVG for icons “to go faster”.
-- Never put third-party temporary URLs into `authoringSource`.
+- **Reference-image path:** every `referenceImageInventory` entry MUST have a matching `assetPlan` row with the same `slotKey`, source `user_upload|brand_kit|external_photo|generated`, and role suited to the picture — not `css_svg` fake people/illustrations. Geometric chrome only for non-pictorial panels/lines/anonymous washes.
+- Never put third-party temporary image URLs into `authoringSource`.
 - Use generated imagery only when it supports the selected concept. Prefer transparent, text-free, crop-safe elements for independent decorations.
 - Never ask image generation to render the final poster, headline, metric, avatar name, or other replaceable content.
 - Keep generated prompts and returned asset IDs/paths as provenance when available.

package/skills/easysociable-template/workflows/AUTHORING_FROM_BRIEF.md

@@ -4,12 +4,12 @@ Primary intake when the user describes a single-page template in words (no refer
 
 ## Goal
 
-One publishable **single-page** template draft: Design Brief → Design Philosophy → 2–3 Concepts → Asset Plan → Theme lock → slot table + absolute layout → screenshot QA → Authoring Studio.
+One publishable **single-page** template **Family** (master canvas + multi-platform variants by default): Design Brief → Design Philosophy → 2–3 Concepts → Asset Plan → Theme lock → master layout → Authoring Studio → `MULTI_PLATFORM_FAMILY.md`.
 
 ## Steps
 
-1. Confirm this is **one page**, not a slideshow. If they want a multi-slide deck, stop and hand off (`OUT_OF_SCOPE.md`).
-2. Read `references/PLATFORM_SPECS.md` and lock platforms + **Recommended** canvas (preset + pixels).
+1. Confirm this is **one page**, not a slideshow. If they want a multi-slide deck, stop and hand off (`OUT_OF_SCOPE.md`). Multi-platform variants of the same page are expected — that is not a slideshow.
+2. Read `references/PLATFORM_SPECS.md`. Lock **master** platform + recommended canvas, and the default vertical derive targets unless the user limited platforms (`MULTI_PLATFORM_FAMILY.md`).
 3. **Mandatory — V2.1 design plan first** (no reference image):
    - Follow `workflows/DESIGN_BRIEF.md`
    - Follow `workflows/DESIGN_PHILOSOPHY.md`; lock shared `philosophy` (+ companion `design-philosophy.md`)
@@ -30,7 +30,7 @@ One publishable **single-page** template draft: Design Brief → Design Philosop
    - `authoringSource` per `references/AUTHORING_SOURCE.md` (flat tree + text-nesting exception)
    - Theme per `references/THEME_TOKENS.md` — use `themeTokens` from validated `theme-tokens.json` for `theme.create`
 5. Run `scripts/validate-authoring-source.mjs <authoring-source.json>` and fix every error.
-6. Continue with `workflows/AUTHORING_STUDIO.md` (`source.kind = text_brief`); its Visual QA loop is required before handoff.
+6. Continue with `workflows/AUTHORING_STUDIO.md` (`source.kind = text_brief`) → **`MULTI_PLATFORM_FAMILY.md`** (derive + hand-tune + QA each variant) before handoff.
 
 ## Checklist pages
 

package/skills/easysociable-template/workflows/AUTHORING_FROM_IMAGE.md

@@ -4,48 +4,98 @@ Intake when the user provides a poster / card image to turn into a **single-page
 
 ## Goal
 
-Vision/LLM understanding stays **local**. Output is a structured candidate (`authoringSource` + slot table + Theme), not a claim of pixel-perfect clone. User always finishes in Authoring Studio.
+Vision/LLM understanding stays **local**. Rebuild the page as a slotted `authoringSource` that **follows the reference as a layout and visual specification**, not as a loose mood board.
+
+User always finishes in Authoring Studio. Do **not** claim a pixel-perfect clone is guaranteed under absolute layout — but do **not** treat approximation as permission to invent a different composition.
+
+## Non-negotiable (reference path)
+
+When `source.kind = image_reference` (user gave a reference image):
+
+1. **Spec over vibes.** Target function is **minimize visual distance to the reference** under slot/Theme/flat-tree constraints — not “ship any educational card that validates.”
+2. **Measure before inventing.** Extract and record **`referenceSpec`** in `design-plan.json` (required fields: `stackOrder`, `margins`, `gaps`, `radii`, `typeScale` — contract in `references/DESIGN_V2_1.md`). Validator rejects plans without it.
+3. **Inventory every pictorial region.** Before building nodes, list all **bitmap-like content** in the reference into **`referenceImageInventory`** (see § Image inventory). Each must become an **`image` slot** (or Icon Catalog for true icons — see below). **Forbidden:** replacing those regions with CSS fake faces, emoji, or invented SVG “because it’s faster.”
+4. **Editable copy stays nodes.** Rebuild typography and numbers as text/number slots. Never flatten replaceable text into a baked background image.
+5. **Visual QA must compare to the reference.** Studio screenshot alone is not enough — side-by-side against the reference is required before handoff (`VISUAL_QA.md` § Reference compare). `visual-qa.json` must set `sourceKind: image_reference` and a passing `referenceCompare`.
+
+## Image inventory (what must become an image slot)
+
+Treat as **pictorial / bitmap content** → **`image` slot** (`image_0`, `image_1`, …) with `imageRoles` set:
+
+| Include as image slot | Examples |
+|-----------------------|----------|
+| Photos | People, product, lifestyle |
+| Illustrations / drawn characters | Soft person illustrations, mascots |
+| Screenshots / UI captures | App frames, dashboards |
+| Avatars / logos used as content | Profile photos, brand marks used as imagery |
+| Any non-geometric picture inside a frame | Rounded photo wells, poster insets |
+
+**Not** image slots (CSS / Theme / Icon Catalog instead):
+
+| Keep as chrome | How |
+|----------------|-----|
+| Solid/gradient panels, hairlines, anonymous discs used only as wash | CSS decoration |
+| Number badges that are pure typography in a circle | decoration + fixed or `text`/`number` if variable |
+| Recognizable **icons/glyphs** (arrows, checks, UI symbols) | **Icon Catalog** (`SURFACE_REVIEW.md` § Icons) — not hand-drawn; not a photo slot unless the reference literally uses a photo there |
+
+If unsure whether a region is “illustration” vs “icon”: prefer **image slot** when it looks like artwork/photo; use Icon Catalog when it is a standard UI glyph.
+
+### Image slot rules on this path
+
+- Each inventoried picture → one `image` slot; set `requiresImage` / `imageRoles` / `slotSummary.image` accordingly.
+- Authoring nodes for those slots: absolute `img` (or image host) with `data-variable="image_N"` — **empty placeholder frame** matching reference geometry (size, radius, position). Do not fill with CSS person-shapes.
+- At create time, placeholders may be empty; fill later via account `imageId` (`FILL_AND_RENDER.md`). Optional: import a cropped stand-in from the reference only when the user supplies/exports that crop as an upload — never keep third-party temp URLs in Authoring Source.
+- Write inventory into `design-plan.json` → `referenceImageInventory` **and** matching `assetPlan[]` rows with the same `slotKey` (see `DESIGN_V2_1.md`). Do not leave inventory only in chat.
 
 ## Steps
 
 1. Confirm single-page intent (not “rebuild this whole carousel as one Agent pack”).
-2. Read `references/PLATFORM_SPECS.md` when mapping detected aspect → platform defaults.
-3. Inspect the image and extract:
+2. Read `references/PLATFORM_SPECS.md` when mapping detected aspect → platform defaults. Prefer the platform the user named; otherwise infer from aspect and **confirm**.
+3. **Read the reference pixels with a vision-capable tool** (`read_file` on the image path, or equivalent). Do **not** invent geometry or image inventory from a filename, caption, or memory alone. Then extract **into a written checklist** (show the user before heavy authoring when geometry is ambiguous):
    - Canvas aspect / preset + suggested pixel size; likely `platforms`
    - Likely **pageRoles** (1–2), contentFamily / archetypes, density, visualStyle
-   - Layout regions (title, metric, image well, footer, …)
-   - **Variable vs fixed**: only variable regions become slots
-   - Theme candidates (canvas/text/accent/muted, font feel)
-4. Reverse-engineer a short shared philosophy (`workflows/DESIGN_PHILOSOPHY.md`) from the reference — movement name + space/color/rhythm/composition/type/craftBar. Write it into `design-plan.json` `philosophy`.
-5. Treat the reconstruction direction as the selected concept (one concept is enough), with `philosophyExpression` describing how the rebuilt zones express that philosophy. Then follow `workflows/ASSET_PLAN.md` and `workflows/SURFACE_REVIEW.md` when the rebuild needs wash, slot photography, or icons:
-   - Reuse the supplied bitmap only when it is meant to remain a background/hero asset
-   - Rebuild editable typography, data, and simple decoration with nodes/CSS/SVG
+   - Layout regions and **stack order** (title, cards, tip, CTA, …)
+   - **`referenceSpec`:** margins, gaps, radii, typeScale, stackOrder
+   - **`referenceImageInventory`:** every pictorial region → `image_N` + `imageRole` + `boxApprox`
+   - **Variable vs fixed:** copy/data → slots; pure chrome → decoration; pictures → image slots; glyphs → Icon Catalog
+   - Theme candidates (canvas/text/accent/muted, font feel) sampled from the reference
+4. Reverse-engineer a short shared philosophy (`workflows/DESIGN_PHILOSOPHY.md`) from the reference — movement name + space/color/rhythm/composition/type/craftBar. Write it into `design-plan.json` `philosophy`. Philosophy must **serve the measured layout**, not excuse a different grid.
+5. Treat the reconstruction as the selected concept (one concept is enough), with `philosophyExpression` describing how the rebuilt zones express that philosophy **and** match the reference zones. Then follow `workflows/ASSET_PLAN.md` and `workflows/SURFACE_REVIEW.md`:
+   - Pictorial regions → `image` slots (`user_upload` / import) with `assetPlan[].slotKey`, not `css_svg` stand-ins
+   - Icons/glyphs → Icon Catalog confirm → `get_icon`
+   - Rebuild editable typography, data, and **geometric** decoration with nodes/CSS
    - Never flatten replaceable text or data into a generated image
    - Never keep third-party temporary image URLs in Authoring Source
-   - Write and validate `design-plan.json`; `image_reference` may contain one concept
+   - Write `referenceSpec` + `referenceImageInventory` + `assetPlan`, then `node scripts/validate-design-v2.mjs design-plan.json` (must pass); `image_reference` may contain one concept
    - When co-creating Theme, run `THEME_FROM_BRAND.md` (sample colors from reference → `brandHex`) and validate `theme-tokens.json`
 6. Build **P0 selection metadata** (`references/CATALOG_METADATA.md`) — infer, then confirm with the user.
 7. Build an explicit **slot table** (`references/SLOTS.md`):
    - Types: `text` | `number` | `image` only
    - Keys may be `text_0`, `image_0`, …
    - Every `text` slot includes `maxLines` (+ `maxCharacters` when known)
+   - Every inventoried picture has a corresponding `image_*` entry
    - No `list` type — repeated lines → `text_1`…`text_n` + `fixedItemCount` when checklist/steps
-8. Map regions to **flat absolutely positioned** canvas siblings (no absolute-inside-absolute groups; card chrome = decoration sibling). Set `bindingKey` on fillable nodes only. Put exact geometry and critical typography in inline `style={{...}}`; do not use Tailwind arbitrary-value layout classes. Fill `slotSummary` / `requiresImage` / `imageRoles`.
+8. Map regions to **flat absolutely positioned** canvas siblings (no absolute-inside-absolute groups; card chrome = decoration sibling). Set `data-variable` / binding on fillable nodes only. **Match the geometry spec** (positions/sizes within a tight tolerance of the measured reference, scaled to the chosen canvas). Put exact geometry and critical typography in inline `style={{...}}`; do not use Tailwind arbitrary-value layout classes. Fill `slotSummary` / `requiresImage` / `imageRoles`.
 9. Propose Theme reuse or `ThemeTokens` create from `theme-tokens.json` (`references/THEME_TOKENS.md`).
-10. Show the user: selection metadata, slots, Theme, and honesty about approximation limits. Proceed when they accept.
+10. Show the user: geometry summary, **image inventory → slot map**, selection metadata, Theme. Call out any region you could not match and why. Proceed when they accept.
 11. Run `scripts/validate-authoring-source.mjs <authoring-source.json>` and fix every error.
-12. Continue with `workflows/AUTHORING_STUDIO.md` (`source.kind = image_reference`, brief = path or short note); run Visual QA before handoff.
+12. Continue with `workflows/AUTHORING_STUDIO.md` (`source.kind = image_reference`, brief = path or short note) → **`MULTI_PLATFORM_FAMILY.md`** (derive + hand-tune other presets). Run Visual QA **including reference compare on the master** before handoff; still QA each derived variant for fit/clipping.
 
 ## Limits (state upfront when relevant)
 
-- Complex photography collages, heavy effects, or handwritten type → structure + Theme approximation; Studio required.
+- Complex photography collages, heavy effects, or handwritten type may still need Studio polish; still inventory pictures as image slots and match overall geometry.
 - Absolute layout: do not promise empty lines will pack upward.
 - Never Publish from Agent until the user has Saved in Studio and explicitly asked to publish (`PUBLISH_FROM_DRAFT.md`).
 
 ## Do not
 
-- Treat the reference bitmap as the template (must become slotted authoring source)
+- Treat the reference bitmap as the whole template (must become slotted authoring source)
+- Use the reference as a **mood board** while shipping a different composition/density
+- Replace pictorial regions with CSS fake people, emoji, or invented illustrations
+- Skip vision read of the reference / invent inventory from filename or memory alone
+- Skip `referenceSpec` / `referenceImageInventory` or skip image slots for detected pictures
 - Skip reverse-engineered philosophy / `philosophyExpression`
+- Skip reference-compare Visual QA (`sourceKind` + `referenceCompare` on `visual-qa.json`)
 - Copy private Binding/AST formats into Gateway requests
 - Use runtime Tailwind arbitrary-value classes for critical geometry or typography
 - Nest absolute frames inside wrapper cards/groups (flatten to canvas siblings instead)

package/skills/easysociable-template/workflows/AUTHORING_STUDIO.md

@@ -15,6 +15,15 @@ Complete intake first:
 - Optional draft-stage `selectionMetadata` (P0 can be completed at publish time)
 - References: `SLOTS.md`, `AUTHORING_SOURCE.md`, `THEME_TOKENS.md`, `CATALOG_METADATA.md`
 
+## Layout Family (multi-platform)
+
+New drafts create a **Layout Family** (`familyId`) plus a master canvas page.
+**Default create path:** after the master draft exists, follow `MULTI_PLATFORM_FAMILY.md` (derive + hand-tune variants) before handoff unless the user asked for one platform only.
+
+- Authoring URL: `/authoring/{draftId}?platform=…`. Top bar **platform chips** switch variants (do not resize one AST).
+- Preview skin = Family `preview_tokens` from `theme.create`; fill/render uses Brand snapshot first (ADR-0033).
+- Legacy drafts without `familyId` auto-wrap on `getDraft` / `listDrafts`. Bulk: `easysociable templates families migrate-legacy --json`.
+
 ## Flow
 
 1. Run the required local preflights (resolve scripts relative to this Skill directory):
@@ -36,48 +45,52 @@ The JSON file contains the public `name`, `source`, `authoringSource`, optional
 `selectionMetadata`, and optional `theme`/`themeId` fields. Do not pass private
 AST or Binding Maps.
 
-3. Read `data.id` / `data.templateId` / `data.themeId` / `data.authoringStudioUrl`.
+3. Read `data.id` / `data.templateId` / `data.familyId` / `data.authoringStudioUrl` (and `data.variants` when present).
+
+4. **Multi-platform (default):** run `workflows/MULTI_PLATFORM_FAMILY.md` — derive target presets, hand-tune each variant, QA each canvas. Skip only when the user asked for a single platform.
 
-4. **Before handoff, run `workflows/VISUAL_QA.md`.** Open the actual Studio render with available browser control and inspect the screenshot, not only source code. When the draft fails, fix `authoring-source.json`, validate it, update the same draft, and re-render:
+5. **Before handoff, run `workflows/VISUAL_QA.md`** on the master (and each variant from step 4). Open the actual Studio render; inspect screenshots, not only source. When a draft fails, fix authoring JSON, validate, update that page id, and re-render:
 
 ```bash
 node scripts/validate-authoring-source.mjs ./authoring-source.json
-easysociable templates update --id <id> --file ./draft-patch.json --json
+easysociable templates update-draft --id <id> --file ./draft-patch.json --json
 ```
 
-Stop after two automatic revisions unless the user explicitly requests more. Validate the passing QA artifact:
+Stop after two automatic revisions per page unless the user explicitly requests more. Validate the passing QA artifact:
 
 ```bash
 node scripts/validate-design-v2.mjs ./visual-qa.json
 ```
 
-5. **Required user handoff message** (paste only after QA — customize the URL):
+6. **Required user handoff message** (paste only after QA — customize URLs):
 
 ```text
-已创建草稿，请打开 Authoring Studio 预览/编辑：
+已创建多平台模板 Family（master + 变体）。请打开 Authoring Studio：
 {authoringStudioUrl}
 
-可直接在页面上改布局、文案占位和 Theme。满意后点 Save（页面上没有 Publish）。
-保存完成后回复我「publish」或「发布该模板」，我会分析画布、补齐选型元数据并发布到 Catalog。
+顶栏平台芯片可切换画布（如小红书 3:4 / IG·Threads 4:5 / TikTok 9:16 / LinkedIn 1:1）。
+可直接改当前变体的布局、文案和 Theme。满意后点 Save（页面上没有 Publish）。
+保存完成后回复我「publish」或「发布该模板」，我会补齐选型元数据并发布。
 ```
 
 English equivalent when the session is EN:
 
 ```text
-Draft created. Open Authoring Studio to preview/edit:
+Multi-platform template Family created (master + variants). Open Authoring Studio:
 {authoringStudioUrl}
 
-Edit layout, placeholders, and Theme directly on the page. When satisfied, click Save (there is no Publish button).
-Then reply “publish” and I will analyze the draft, complete catalog metadata, and publish to the Catalog.
+Use the top-bar platform chips to switch canvases (e.g. XHS 3:4 / IG·Threads 4:5 / TikTok 9:16 / LinkedIn 1:1).
+Edit the active variant’s layout, copy, and Theme. When satisfied, click Save (no Publish button).
+Then reply “publish” and I will complete catalog metadata and publish.
 ```
 
-6. User previews/edits in the **slim** Authoring Studio:
+7. User previews/edits in the **slim** Authoring Studio:
    - Canvas + right property panel
-   - Left: Theme tokens + optional Catalog hints
-   - Top bar: **Save** and **Fork** only. Final PNG rendering is delegated to the unified CLI/MCP after the user confirms the saved draft.
+   - Left: Theme / preview tokens + optional Catalog hints
+   - Top bar: **platform chips**, **Save**, **Fork**. Final PNG rendering is delegated to the unified CLI/MCP after the user confirms the saved draft.
    - **No** Publish button; **No** left SidebarMenu (no AI / select-template / typeset rail)
 
-7. When the user says publish → run `workflows/PUBLISH_FROM_DRAFT.md`.
+8. When the user says publish → run `workflows/PUBLISH_FROM_DRAFT.md`.
 
 ## SDK shape
 

package/skills/easysociable-template/workflows/DESIGN_BRIEF.md

@@ -16,11 +16,11 @@ Skip this workflow when `AUTHORING_FROM_IMAGE.md` applies and a reference image
 
 ### 1. Gather intent (batch questions; skip known answers)
 
-- Platforms (multi-select) + canvas from `references/PLATFORM_SPECS.md`
+- **Master** platform + canvas from `references/PLATFORM_SPECS.md`, plus default multi-platform derive targets (`MULTI_PLATFORM_FAMILY.md`) unless the user wants one platform only
 - Page roles (1–2) + contentFamily / archetypes / density (`CATALOG_METADATA.md`)
 - Content job: what must the viewer understand in one glance?
 - Must-have slots: title / metric / image / CTA / fixed N checklist lines…
-- Theme: reuse `themeId` or co-create direction (swiss / editorial / bold_promo / minimal / dark). If co-creating, note brand hex or archetype for `DESIGN_INTELLIGENCE.md` palette seeding.
+- Theme/preview direction (swiss / editorial / bold_promo / minimal / dark). Note brand hex or archetype for `DESIGN_INTELLIGENCE.md` palette seeding → Family `preview_tokens`
 
 ### 2. Write the Design Brief
 
@@ -31,7 +31,8 @@ Use this structure (Chinese or English to match the user):
 
 ## 1. Job to be done
 - One-sentence purpose of this page
-- Primary platform(s) + canvas (preset + pixels) — cite PLATFORM_SPECS recommended row
+- Master platform + canvas (preset + pixels) — cite PLATFORM_SPECS recommended row
+- Multi-platform targets (default vertical bucket unless user limited) — `MULTI_PLATFORM_FAMILY.md`
 
 ## 2. Visual constraints
 - Desired/forbidden moods or brand rules

package/skills/easysociable-template/workflows/MULTI_PLATFORM_FAMILY.md

@@ -0,0 +1,81 @@
+# Multi-platform Layout Family (default create path)
+
+**SoT for creating templates that ship on several platforms at once.**  
+One user-facing **Layout Family**; one **master** canvas page; additional **variant** pages per aspect preset. Studio switches variants with platform chips — it does not resize one AST (ADR-0033).
+
+Single-page ≠ single-platform. Still never create slideshow/carousel packs (`OUT_OF_SCOPE.md`).
+
+## Default when the user asks to create a template
+
+Unless they explicitly want **one platform only**:
+
+1. Lock a **master** platform + recommended canvas (`PLATFORM_SPECS.md`).
+2. Create the master draft (Family is created with it).
+3. **Derive** missing vertical presets for the family.
+4. **Hand-tune** each variant’s absolute layout (do not ship raw derive output for dense pages).
+5. Visual-QA master + each variant, then hand off Studio with chip switching.
+
+### Default vertical bucket (most social covers)
+
+| Role | Preset | Pixels | Platforms on that variant |
+|---|---|---|---|
+| Master (typical) | `3:4` | 1080×1440 | `xiaohongshu` |
+| Variant | `4:5` | 1080×1350 | `instagram` + `threads` (shared tree) |
+| Variant | `9:16` | 1080×1920 | `tiktok` |
+| Variant | `1:1` | 1080×1080 | `linkedin` |
+
+If the user’s primary platform is already `4:5` / `9:16` / `1:1`, that page is master; derive the other presets in the bucket (see Gateway `defaultDerivePolicyForPreset`).
+
+Skip or trim targets only when the user names a subset (“只要 IG 和 LinkedIn”).
+
+## CLI
+
+```bash
+# After create-draft, read familyId from the draft view (or families list)
+easysociable templates families get --id <familyId> --json
+
+# Create missing presets (idempotent; use --presets to limit)
+easysociable templates families derive --id <familyId> --presets 4:5,9:16,1:1 --json
+
+# Hand-tuned layout per variant pageId
+easysociable templates update-draft --id <variantPageId> --file ./variant-4x5.patch.json --json
+```
+
+Gateway equivalents: `GET/POST /v1/template-families/:id`, `POST /v1/template-families/:id/derive`.
+
+If CLI `--json` fails Zod on new family fields (`familyId`, `variants`, …) but HTTP succeeded, re-fetch with `families get` / `list-drafts` or raw Gateway — do not assume create/derive failed.
+
+## Hand-tune rules (required after derive)
+
+`derive` applies pin `v1_vertical` (scale + bottom/center corrections). That is a **starting point**, not shippable layout for dense covers.
+
+For **each** variant page:
+
+1. Keep the **same slots / copy / icons** as master (same `data-variable` keys).
+2. Rebuild absolute geometry for the target `canvas` (`width`/`height` + root Graphic size must match preset pixels).
+3. Distribute vertical rhythm across the full board: even section gaps; **no** packed header + empty foot.
+4. TikTok `9:16`: keep critical UI out of bottom ~120–160px chrome.
+5. JSX styles must be `style={{ ... }}` (double braces). Python f-strings turn `{{` into `{` — validate with Babel/`validate-authoring-source.mjs` before update.
+6. Per-variant `selectionMetadata.platforms` / `canvasPreset` / `canvas` must match that page only (IG+Threads both listed on the `4:5` page).
+7. Theme/preview tokens stay on the **Family** (`preview_tokens` via `theme.create` on draft) — not a TemplateTheme row (`THEME_TOKENS.md`, ADR-0033).
+
+```bash
+node scripts/validate-authoring-source.mjs ./variant-4x5.authoring.json
+easysociable templates update-draft --id <variantPageId> --file ./variant-4x5.patch.json --json
+```
+
+## Visual QA
+
+Run `VISUAL_QA.md` on the **master** and **each derived preset** (screenshot Studio at that draft URL / platform chip). Fail if any variant has clipped content, overlapping bands, or large empty voids with cramped clusters.
+
+## Handoff
+
+After QA, open the **master** Studio URL and tell the user they can switch platforms with the top-bar chips (each chip is a real canvas variant). Save still applies to the active variant; Agent publish remains post-Save (`PUBLISH_FROM_DRAFT.md`). Include every variant `pageId` + preset in the handoff notes.
+
+## Do not
+
+- Author one AST and claim it fits 3:4 + 9:16 + 1:1
+- Leave dense pages on raw derive output
+- Put Instagram and Threads on different presets when both are 4:5
+- Create a second Family for the same template identity
+- Treat multi-platform variants as a slideshow / carousel pack