@easysociable/cli 0.1.2 → 0.1.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@easysociable/cli",
-  "version": "0.1.2",
-  "description": "Agent-first CLI and MCP host for EasySociable Template and Slideshow V1",
+  "version": "0.1.3",
+  "description": "Agent-first CLI for EasySociable: Content Engine, Template, Slideshow, and MCP",
   "type": "module",
   "license": "MIT",
   "author": "EasySociable",
@@ -33,6 +33,7 @@
     "bin",
     "dist",
     "skills",
+    "content-engine",
     "LICENSE",
     "README.md"
   ],

package/skills/ONBOARDING.md

@@ -1,35 +1,38 @@
 # EasySociable agent-first onboarding
 
-V1 expects Codex or Claude Code to drive setup. The website is not the primary
-workspace.
+V1 expects an Agent (Grok Bot, Codex, Claude Code, …) to drive setup. The website is not the primary workspace.
 
-## User steps (3)
+## User steps
 
 1. **Install CLI**
 
    ```bash
    curl -fsSL https://easysociable.com/install.sh | bash
+   # or: npm i -g @easysociable/cli
    ```
 
-2. **Install hosted Skills + MCP** (Template + Slideshow by default)
+2. **Create the Content Engine** (markdown + workbench)
 
    ```bash
-   easysociable install --yes
+   easysociable engine init --root /workspace --yes
+   easysociable engine serve --engine /workspace/Content Engine --no-open
    ```
 
-3. **Ask the Agent to create graphics** — account creation is deferred until a
-   hosted operation requires authentication.
+   On a laptop, use any parent path instead of `/workspace`.
 
-Optional later:
+3. **Install hosted Skills + MCP** (Template + Slideshow by default; for Codex / Claude Code)
 
-```bash
-easysociable install --skills content --yes
-```
+   ```bash
+   easysociable install --yes
+   ```
+
+   Optional pointer skill (discovery only — operations live in `Content Engine/CLAUDE.md`):
+
+   ```bash
+   easysociable install --skills content --yes
+   ```
 
-Then run the `easysociable-content` setup workflow (Obsidian Vault + Content
-Engine). For a private copy to another machine, see
-`skills/easysociable-content/INSTALL.md`. Skipping Content does **not** block
-single-page or Slideshow renders.
+4. **Ask the Agent to create graphics** — account creation is deferred until a hosted operation requires authentication.
 
 ## Lazy auth (Agent script)
 
@@ -54,10 +57,11 @@ idempotency key when applicable.
 ## What works without auth
 
 - `easysociable install` / `update`
+- `easysociable engine init` / `serve` / `build` / `validate`
 - Reading installed Skill instructions
 - Public template catalog in the browser (`/templates`)
 
 ## What requires auth
 
-- Profiles, Themes, images, drafts, Slideshow Runs
+- Brands, Themes, images, drafts, Slideshow Runs
 - Hosted preview sessions and final PNG renders (`hosted_render_page` allowance)

package/skills/easysociable-content/SKILL.md

@@ -1,126 +1,51 @@
 ---
 name: easysociable-content
 description: >
-  Set up and operate a local Content Engine for EasySociable. English folder
-  tree only (Content Engine/). One platform = one Run. The Agent writes
-  markdown; workbench is the observatory UI. Hosted Template/Slideshow work
-  uses the unified easysociable CLI/MCP. No Obsidian requirement, no content
-  MCP, no content CLI.
+  Operate the EasySociable Content Engine (capture, discovery, topics, runs).
+  If no engine exists, run `easysociable engine init`. Then follow
+  Content Engine/CLAUDE.md. Render handoff: easysociable-template (1 page) or
+  easysociable-slideshow (2+). Never publish or post.
 ---
 
-# EasySociable Content Skill
-
-This Skill owns the user's local knowledge base. The Agent writes Markdown
-under `Content Engine/`. After writes, rebuild the workbench. Hosted Template
-and Slideshow operations stay with the unified `easysociable` CLI/MCP.
-
-**Operating manual lives in the engine:** `Content Engine/CLAUDE.md`. Follow it
-for capture, discovery, topics, 开一单, ingest, ship, and catalog evidence. This
-file is setup, routing, and hosted handoff only.
-
-## Non-negotiable rules
-
-1. English tree only: `Content Engine/`. Do not ask language.
-2. Obsidian is **not** required. Do not detect, install, or open it.
-3. Ask for a parent directory (or an existing `Content Engine/` path). Never create the engine silently in a random folder.
-4. Existing engine files are read-only during setup. Never overwrite user content, especially `workbench/template.html`.
-5. One platform = one Run (one folder). Same Topic, native rewrite for another network → **N runs**, shared `topic_id`.
-6. On **开一单**: **ask platform(s)** if unset. Multi-select → N runs. Do **not** silent-default to `x`.
-7. Before brief / draft / editor / pack: **read** `platforms/<platform>.md` (`instagram` → `ig.md`).
-8. Write selection into `idea.md` (`swipe_id` / `atoms` / `claim_id`). Chat cards are not citations.
-9. Pack JSON (`content-pack.v1`) only at **handoff to render**. Until then the run uses `pack.md` (slideshow platforms after SHIP).
-10. Final PNGs live under `exports/<run-slug>/`, never inside the run folder. V1 output is PNG only.
-11. Do not start a Local API, open SQLite, call a Content MCP, or call private Directus/R2/Stripe endpoints.
-12. Do not create a hosted Brand Profile during setup.
-
-## When this skill runs
-
-1. Resolve the engine (`--root` parent, or existing `Content Engine/`).
-2. If missing files: `node scripts/setup.mjs --root <path> --apply --json` (never overwrites).
-3. Ensure `workbench/` exists (copy skill `workbench/` files **only if missing**).
-4. `python3` is required. If missing, stop and tell the user.
-5. Run `python3 workbench/build.py`.
-6. If port **8765** is free: start `workbench/serve.py`. If it is already listening, reuse it — do not start a second server.
-7. Open `http://127.0.0.1:8765/workbench/`.
-8. After Agent writes markdown: run `build.py` again (leave serve running).
+# EasySociable Content (pointer)
 
-```bash
-node scripts/setup.mjs --root <parent-or-engine> --preview --json
-node scripts/setup.mjs --root <parent-or-engine> --apply --json
-node scripts/workbench.mjs start --engine "<path>/Content Engine" --json
-node scripts/workbench.mjs build --engine "<path>/Content Engine" --json
-```
+This skill is an entry card only. **Do not invent a parallel workflow.**
+
+## Create the engine
 
-`--no-open` skips the browser / server start.
-
-## Intent routing
-
-Defer the body of each flow to engine `CLAUDE.md`. Use these skill workflows only for setup and hosted handoff.
-
-| User intent | Action |
-|---|---|
-| First install / missing engine | Setup above → `workflows/GETTING_STARTED.md` |
-| capture / 记一下 | Engine `CLAUDE.md` § Capture |
-| Watchlist add | Engine `CLAUDE.md` § Topics (watchlist files) |
-| 扫 watchlist / 发现内容 | Engine `CLAUDE.md` § Discovery — Source Digest only; no Topics |
-| 选题 / score topics | Engine `CLAUDE.md` § Topics — explicit input; Scout→opportunity 5-dim; ready=opp≥7.5 and aud≥6; cap=5 produce |
-| 开一单 / open a run | Engine `CLAUDE.md` § Open a run — **ask platforms**; N platforms → N folders |
-| 收成 swipe/atom/claim | Engine `CLAUDE.md` § Library ingest |
-| Ship + URL + result | Engine `CLAUDE.md` § Published index + Catalog evidence |
-| 出图 / pack + render | Engine `CLAUDE.md` § PagePack, then handoff below |
-| Platform craft | `Content Engine/platforms/<platform>.md` + `references/PLATFORM_GUIDE.md` |
-| Single-page image | Hand off → **easysociable-template** |
-| Multi-page slideshow | Hand off → **easysociable-slideshow** (Pack JSON at this step) |
-| Export PNGs | `workflows/CONTENT_EXPORT.md` |
-| Hosted CLI/MCP | `workflows/MCP_FIRST.md` |
-| Out of scope | `workflows/OUT_OF_SCOPE.md` |
-
-### Single-page vs slideshow
-
-```text
-1 page                          → easysociable-template
-2+ pages + slideshow platform   → easysociable-slideshow
-x / xiaohongshu                 → easysociable-template only
+```bash
+easysociable engine init --root <parent-or-engine> --yes
+easysociable engine serve --engine <parent>/Content Engine --no-open
 ```
 
-Slideshow platforms: `tiktok`, `instagram`/`ig`, `linkedin`, `threads`.
+On a dedicated agent computer (e.g. Grok Bot), prefer `--root /workspace`.
 
-## Run model
+Existing files are never overwritten. `python3` is required for the workbench.
 
-```text
-ask platform(s) → N folders
-  runs/<YYYY-MM-DD-slug[-platform]>/idea.md   ← one platform, selection ids
-  brief.md → packet.md → draft.md → editor.md → rubric.md
-  pack.md (after SHIP, image decks only)
-  pack-<platform>.json                        ← only at Slideshow/Template handoff
-```
+## Operate
 
-Copy `runs/_template/` for each platform. Update `runs/_index.md` (one row per run).
+Read and follow `Content Engine/CLAUDE.md` (and `engine.json`, `platforms/<platform>.md`).
 
-Validate before slideshow handoff:
+Rebuild the observatory after markdown writes:
 
 ```bash
-node scripts/validate-run.mjs --run <run-dir> --json
-node scripts/validate-run.mjs --run <run-dir> --require-pack --json
+easysociable engine build --engine <Content Engine>
 ```
 
-## Handoff
+## Render handoff
 
-**Slideshow (multi-page):**
+| Intent | Hand off |
+|--------|----------|
+| 1 page image | **easysociable-template** |
+| 2+ pages on tiktok / instagram / linkedin / threads | **easysociable-slideshow** |
+| x / xiaohongshu images | **easysociable-template** only |
 
-1. Rubric SHIP on this run. Write `pack.md` (slots only).
-2. Hand off to `easysociable-slideshow`. It selects a Page Template per page and writes `pack-<platform>.json`.
-3. User confirms Studio preview.
-4. Final render + export to `{engine}/exports/<run-slug>/`.
+Validate a run before slideshow create:
 
-**Template (single-page):**
-
-1. Hand off slot values to `easysociable-template` `FILL_AND_RENDER`.
-
-Preview does not consume Render Page allowance. Final render does.
+```bash
+easysociable engine validate --run <run-dir> --require-pack
+```
 
-## Reference loading
+## Out of scope
 
-Always read engine `CLAUDE.md`, `engine.json`, `references/RUN_LAYOUT.md` and
-`references/PLATFORM_GUIDE.md`. Load `GETTING_STARTED` on first install,
-`PACK_AUTHORING` / `CONTENT_EXPORT` / `MCP_FIRST` only at render handoff.
+No social posting, Content MCP, Local API, or SQLite content library.

package/skills/easysociable-slideshow/SKILL.md

@@ -79,6 +79,7 @@ It is not a reusable Carousel/Deck Template and it is not a public post.
 
 ## Handoff boundary
 
-The Content Skill owns semantic copy and Pack creation. The Template Skill owns
-single-page authoring and fill-slots. This Skill only composes explicit page
-instances and coordinates preview/final render.
+The Content Engine (`CLAUDE.md` + `easysociable engine …`) owns semantic copy
+and Pack creation. The Template Skill owns single-page authoring and fill-slots.
+This Skill only composes explicit page instances and coordinates preview/final
+render.

package/skills/easysociable-template/SKILL.md

@@ -3,18 +3,17 @@ name: easysociable-template
 description: >
   Create single-page social image templates for EasySociable via the unified
   Template MCP or `easysociable` CLI, and fill published template slots to Hosted Render
-  (get_template → slots → create_render_job). Use when the user wants to author a
-  page template from a reference image or text brief, write a shared visual design
-  philosophy, explore 2–3 professional layout concepts as spatial expressions of that
-  philosophy, plan or generate visual assets, co-create/reuse a Theme with brand-hex
-  palette generation, choose a Surface (flat / Gateway gradient catalog / host
-  Unsplash·Pexels·Pinterest photo), pull icons via Template Gateway
-  search_icons/get_icon (internal Icon Catalog), run
-  screenshot-based visual QA, attach catalog metadata (platforms including
-  x/linkedin/threads, pageRoles, archetypes, density, slotSummary), open Authoring
-  Studio, publish a single-page template, or render a published template by filling
-  public slots. Do not use for multi-slide slideshow composition, ContentDocument as
-  render input, local content library, or carousel packs.
+  (get_template → slots → create_render_job). Default create path is a Layout Family:
+  one master canvas plus derived multi-platform variants (e.g. XHS 3:4, IG/Threads 4:5,
+  TikTok 9:16, LinkedIn 1:1) with hand-tuned layouts per preset. Use when the user wants
+  to author a page template from a reference image or text brief (including “做多平台
+  模板”), write a shared visual design philosophy, explore 2–3 professional layout
+  concepts, plan or generate visual assets, co-create Theme/preview tokens with brand-hex
+  palette generation, choose a Surface, pull icons via Template Gateway
+  search_icons/get_icon, run screenshot-based visual QA, attach catalog metadata, open
+  Authoring Studio, publish, or render by filling public slots. Do not use for multi-slide
+  slideshow composition, ContentDocument as render input, local content library, or
+  carousel packs.
 ---
 
 # EasySociable Template Skill
@@ -25,10 +24,10 @@ server. Do not install or invoke `easysociable-template`, `easysociable-slidesho
 
 **This skill owns two single-page paths:**
 
-1. **Author** templates (Studio + Publish).
+1. **Author** templates as a **Layout Family** (master + multi-platform variants) → Studio + Publish (`workflows/MULTI_PLATFORM_FAMILY.md`).
 2. **Fill slots → Hosted Render** for a published PageTemplate (`workflows/FILL_AND_RENDER.md`).
 
-It is a template factory **and** the Agent surface for single-page fill-slots out图 (ADR-0021). It is **not** a multi-slide slideshow compositor.
+It is a template factory **and** the Agent surface for single-page fill-slots rendering (ADR-0021). It is **not** a multi-slide slideshow compositor. Single-page ≠ single-platform.
 
 Every published page must carry **P0 catalog metadata** so Agents can filter and fill templates (`references/CATALOG_METADATA.md`).
 
@@ -45,18 +44,19 @@ Out of scope (hand off):
 2. Submit only public Gateway DTOs. Never invent or request private Safe AST / Binding Map / RenderPlan.
 3. Do not start Local Runtime, read content library SQLite, or call Content MCP/CLI for Template work.
 4. Catalog and create targets are **single-page** only. Never treat site Carousel packs as Agent templates.
-5. After `create` / `createDraft`, the primary authoring path is `authoringStudioUrl` (`/authoring/{draftId}`). Always send the handoff message in `AUTHORING_STUDIO.md` (edit → **Save** → tell Agent to publish). Do not require a Hosted Preview Job for interactive authoring.
+5. After `create` / `createDraft`, the primary authoring path is `authoringStudioUrl` (`/authoring/{draftId}`). **Default:** run `workflows/MULTI_PLATFORM_FAMILY.md` (derive + hand-tune variants) before handoff unless the user asked for one platform only. Always send the handoff in `AUTHORING_STUDIO.md` (edit → **Save** → tell Agent to publish). Do not require a Hosted Preview Job for interactive authoring.
 6. Studio has **Save only** — no Publish button. Publish only after the user saves and **explicitly** asks to publish; then run `workflows/PUBLISH_FROM_DRAFT.md`.
-7. **Do not Publish without complete P0 selection metadata** (`CATALOG_METADATA.md`). Gateway enforces this.
-8. Theme: reuse `themeId` **or** co-create full `ThemeTokens`. Colors/fonts belong in Theme; page nodes use semantic `--es-*` tokens where possible.
+7. **Do not Publish without complete P0 selection metadata** (`CATALOG_METADATA.md`). Gateway enforces this. Each family variant carries its own `platforms` / `canvasPreset` / `canvas`.
+8. Theme/preview: co-create `ThemeTokens` on draft create (`theme.create`) → Family `preview_tokens` (ADR-0033). No authoring TemplateTheme row. Colors/fonts via semantic `--es-*` on page nodes.
 9. Layout model is **absolute positioning** on a **flat canvas tree** (see prior authoring rules / `AUTHORING_SOURCE.md`).
 10. **Runtime layout CSS:** put exact geometry in JSX inline `style={{...}}`. Never depend on Tailwind arbitrary-value classes for geometry.
 11. Run `scripts/validate-authoring-source.mjs` before every create/update.
 12. `supportedRoles` uses closed **pageRoles**; `platforms` is a multi-select array.
 13. Canvas sizes must follow `references/PLATFORM_SPECS.md`.
 14. **Text-only V2.1 authoring:** `DESIGN_BRIEF` → Philosophy → Concepts → assets/surface → author → Visual QA.
-15. **Visual QA** before Studio handoff when authoring.
-16. Prefer **reusable/brand assets**, Gateway gradient recipes, and catalog icons for deterministic visuals. Geometric chrome (hairlines, rails, discs) may use plain CSS shapes — **not** as a substitute for named icons.
+15. **Visual QA** before Studio handoff when authoring. For `image_reference`, QA **must** side-by-side compare Studio canvas to the reference (`VISUAL_QA.md` § Reference compare).
+16. Prefer **reusable/brand assets**, Gateway gradient recipes, and catalog icons for deterministic visuals. Geometric chrome (hairlines, rails, discs) may use plain CSS shapes — **not** as a substitute for named icons **or** for pictorial regions on a reference-image rebuild.
+16b. **Reference image → template (hard):** follow `workflows/AUTHORING_FROM_IMAGE.md` as SoT. **Read the reference with a vision tool**, write `referenceSpec` + `referenceImageInventory` into `design-plan.json`, and place pictorial regions as **`image` slots** (empty frames matching the boxes). `validate-design-v2.mjs` rejects `image_reference` plans missing those fields or using `css_svg` stand-ins for inventoried pictures. Do not mood-board a different layout.
 17. Preserve `draftId`, `templateId`, `themeId`, `jobId`, `authoringStudioUrl`, and `previewUrl` across steps.
 18. **Theme / Surface confirmation gates** unchanged for authoring (see `PALETTE_REVIEW`, `SURFACE_REVIEW`).
 19. **Fill-slots render (primary consumption path):** `get_template` → fill `slots[]` → `create_render_job({ templateId, slots, output })` → poll Job/Manifest. Image slots always use an account-owned `imageId` from the existing Gateway → R2 + Directus `Image` flow. Never pass a third-party URL, local path, transient `renderAssetId`, ContentDocument or `contentDocumentHash`. See `workflows/FILL_AND_RENDER.md`.
@@ -79,11 +79,12 @@ easysociable auth status --json
 
 | User intent | Workflow |
 |---|---|
-| Text description → template | `DESIGN_BRIEF.md` → … → `AUTHORING_STUDIO.md` |
-| Reference image → template | `AUTHORING_FROM_IMAGE.md` → … → `AUTHORING_STUDIO.md` |
+| Text description → template (incl. multi-platform) | `DESIGN_BRIEF.md` → … → `AUTHORING_STUDIO.md` → **`MULTI_PLATFORM_FAMILY.md`** (derive + hand-tune) |
+| Reference image → template | `AUTHORING_FROM_IMAGE.md` → … → `AUTHORING_STUDIO.md` → **`MULTI_PLATFORM_FAMILY.md`** + reference-compare QA on master |
+| “只要某一个平台” | Same authoring path; skip derive / only named presets in `MULTI_PLATFORM_FAMILY.md` |
 | Need gradient / photo surface / icons only | `SURFACE_REVIEW.md` |
 | **Add / change an icon** (arrow, chevron, check, …) | **MUST** `SURFACE_REVIEW.md` § Icons — search → confirm → get_icon. **Do not** hand-draw SVG paths. |
-| Already have authoring payload / continue Studio | `workflows/AUTHORING_STUDIO.md` |
+| Already have authoring payload / continue Studio | `workflows/AUTHORING_STUDIO.md` (+ family derive if variants still missing) |
 | User says publish / 发布该模板 (after Save) | `workflows/PUBLISH_FROM_DRAFT.md` |
 | Browse published single-page templates | `list` / `get_template` + public metadata |
 | **Fill a published template → PNG/JPEG** | `workflows/FILL_AND_RENDER.md` |
@@ -91,13 +92,14 @@ easysociable auth status --json
 
 ## Core model
 
+- `workflows/MULTI_PLATFORM_FAMILY.md` — **default** multi-platform create (Family + derive + hand-tune)
 - `references/PLATFORM_SPECS.md`
 - `references/CATALOG_METADATA.md`
 - `references/SLOTS.md` — public slot contract for fill-slots render
 - `references/AUTHORING_SOURCE.md`
-- `references/THEME_TOKENS.md`
+- `references/THEME_TOKENS.md` — Family `preview_tokens` (no TemplateTheme)
 - `references/EXTERNAL_RESOURCES.md`
-- `references/GATEWAY.md` — CLI / MCP including `render` / `create_render_job`
+- `references/GATEWAY.md` — CLI / MCP including families derive + `render`
 - `workflows/FILL_AND_RENDER.md` — get_template → slots → Hosted Render
 - Authoring V2.1 workflows + validators as before
 

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

@@ -134,11 +134,11 @@ Derived from the slot table in `SLOTS.md`.
 | `notFor` | string[1..3] | Honest exclusions |
 | `selectionHints` | string | Short Agent-only hint |
 | `visualStyle` | enum | Look affinity |
-| `defaultThemeId` | string? | Soft preview theme |
-| `compatibleThemeIds` | string[]? | Optional |
 | `locale` | `zh-CN` \| `en` \| `bilingual` | |
 | `exampleFilledPreviewUrl` | url? | Filled sample beats empty shell |
 
+Do **not** put Theme FKs (`defaultThemeId`, `compatibleThemeIds`) on published selection metadata (ADR-0033). Runtime look comes from Brand `themeSnapshot`.
+
 ---
 
 ## P2 — optional

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

@@ -122,7 +122,8 @@ Rules:
 
 - `text_brief` requires 2–3 concepts; `image_reference` permits one.
 - `text_brief` requires root `philosophy` with non-empty `movementName`, `space`, `color`, `rhythm`, `composition`, `typographyAccent`, and `craftBar`.
-- `image_reference` should include a short reverse-engineered `philosophy` (same fields) so Visual QA has a craft bar.
+- `image_reference` requires the same `philosophy` fields (short reverse-engineer from the reference).
+- **`image_reference` also requires `referenceSpec` + `referenceImageInventory`** (see below). `validate-design-v2.mjs` enforces these.
 - Optional philosophy fields: `subtleReference`, `templateConstraints` (recommended).
 - Concepts must have unique IDs and all listed art-direction fields.
 - Every concept requires `philosophyExpression` (how this layout expresses the shared philosophy in space).
@@ -136,6 +137,48 @@ Rules:
 - Optional per concept: `paletteCandidates` — array of `{ brandHex, mode, name?, presetId?, bestFor?, notFor?, label? }` where `mode` is `light` or `dark`. Prefer `name` + `bestFor` when presenting choices.
 - Optional root: `themePreview` — `{ brandHex, activeMode, contrastPass, themeTokensPath, name?, presetId?, bestFor?, userConfirmed? }` after palette lock. Set `userConfirmed: true` only after explicit user choice (or waived).
 - Optional root: `surfacePreview` — `{ kind: flat|gradient|image, userConfirmed, … }`. When `kind` is `gradient` or `image`, require `userConfirmed: true` before authoring those nodes; `gradient` needs `recipeId`; `image` needs `imageId` (or documented pending import) and `imageMode` (`fixed` default for surface background).
+
+### `referenceSpec` + `referenceImageInventory` (`image_reference` only)
+
+Required when `sourceKind` is `image_reference`. Rebuild to this measured spec; do not mood-board a different layout.
+
+```json
+{
+  "referenceSpec": {
+    "stackOrder": ["title", "soft-card", "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"
+    }
+  ],
+  "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"
+    }
+  ]
+}
+```
+
+Rules:
+
+- `referenceSpec.stackOrder`: non-empty string array (region labels top→bottom or primary reading order).
+- `referenceSpec.margins` / `gaps` / `radii` / `typeScale`: non-empty strings (measured or tightly estimated).
+- `referenceImageInventory`: array required (empty only when the reference has **no** pictorial regions). Each item: `label`, `slotKey` (`image_N`), `imageRole` (`hero|screenshot|avatar|product`), `boxApprox`.
+- Every inventory `slotKey` must appear on an `assetPlan` entry with the same `slotKey` and source in `user_upload|brand_kit|external_photo|generated` — never `css_svg` stand-ins for pictures.
+- Procedure for filling these fields: `workflows/AUTHORING_FROM_IMAGE.md`.
 ## Companion `design-philosophy.md`
 
 Human-readable twin of `design-plan.json` → `philosophy`. Recommended structure:
@@ -246,7 +289,14 @@ Rules:
   "schemaVersion": "visual_qa_v2_1",
   "draftId": "draft_123",
   "iteration": 1,
+  "sourceKind": "image_reference",
   "screenshotEvidence": "/absolute/path/to/studio-render.png",
+  "referenceCompare": {
+    "performed": true,
+    "geometryMatch": true,
+    "imageSlotsMatchInventory": true,
+    "notes": "Card stack and image_0/image_1 frames match referenceSpec"
+  },
   "hardFailures": [],
   "scores": {
     "hierarchy": 18,
@@ -272,7 +322,8 @@ Score maxima total 100. `pass` requires:
 - no `hardFailures`
 - each score within its maximum
 - declared `total` equal to the calculated sum and at least 80
+- when `sourceKind` is `image_reference`: `referenceCompare` with `performed`, `geometryMatch`, and `imageSlotsMatchInventory` all `true`
 
 Use `verdict: "revise"` below threshold while iterating. Do not hand off a `revise` result as a reviewed template unless the user explicitly accepts it.
 
-Craft Pass (behavior, not new score fields): when `iteration >= 1`, prefer tightening existing nodes over adding decoration; score against `philosophy.craftBar` and `philosophyExpression` of the selected concept.
+Craft Pass (behavior, not new score fields): when `iteration >= 1`, prefer tightening existing nodes over adding decoration; score against `philosophy.craftBar` and `philosophyExpression` of the selected concept. Set `sourceKind` on `visual-qa.json` to match the design plan when authoring from a reference.

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": []
+}