@easysociable/cli 0.1.2 → 0.1.4

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

@@ -8,15 +8,20 @@ easysociable auth status --json
 easysociable templates list --json
 easysociable templates get --id <id> --json
 easysociable templates create-draft --file ./draft.json --json
-easysociable templates update --id <id> --file ./patch.json --json
+easysociable templates update-draft --id <id> --file ./patch.json --json
 easysociable templates validate --id <id> --json
 easysociable templates publish --id <id> --json
+easysociable templates families get --id <familyId> --json
+easysociable templates families derive --id <familyId> --presets 4:5,9:16,1:1 --json
+easysociable templates families migrate-legacy --json
 easysociable icons search --query "arrow" --json
-easysociable icons get --icon-id <id> --idempotency-key <key> --json
+easysociable icons get --id <id> --idempotency-key <key> --json
 easysociable renders create --template-id <id> --slots ./slots.json --format png --idempotency-key render_1 --json
 easysociable renders wait --id <id> --json
 ```
 
+Multi-platform create flow (derive + hand-tune): `workflows/MULTI_PLATFORM_FAMILY.md`.
+
 All requests go through Gateway. The client receives public summaries, slot
 contracts, stable Image references and render Manifests only. It never receives
 AST, Binding Maps, private RenderPlans or provider credentials.

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