@easysociable/cli 0.1.1 → 0.1.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@easysociable/cli",
-  "version": "0.1.1",
-  "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,26 +33,32 @@
     "bin",
     "dist",
     "skills",
+    "content-engine",
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsup",
+    "prepack": "node scripts/prepack.mjs && pnpm build",
+    "pack:check": "npm pack --dry-run"
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "dependencies": {
+    "commander": "^11.1.0"
+  },
   "devDependencies": {
+    "@easysociable/mcp-server": "workspace:*",
+    "@easysociable/template-gateway-client": "workspace:*",
+    "@easysociable/tsconfig": "workspace:*",
+    "@easysociable/vitest-config": "workspace:*",
     "@types/node": "^22.14.0",
-    "commander": "^11.1.0",
     "tsup": "^8.0.2",
     "typescript": "^5.8.3",
-    "vitest": "^1.3.1",
-    "@easysociable/tsconfig": "0.0.0",
-    "@easysociable/vitest-config": "0.0.0"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "build": "tsup",
-    "pack:check": "npm pack --dry-run"
+    "vitest": "^1.3.1"
   }
-}
+}

package/skills/ONBOARDING.md

@@ -1,33 +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). 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)
 
@@ -52,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,115 +1,51 @@
 ---
 name: easysociable-content
 description: >
-  Set up and operate a local Obsidian-based Content Engine for EasySociable.
-  Obsidian is required. During setup, ask the user to choose 中文 or English;
-  that locale names the engine folders and starter notes. This Skill records
-  Runs, Packs and exports for the Template and Slideshow Skills. It does not
-  provide a hosted content backend, Content API, SQLite runtime, content MCP
-  server or 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. It is intentionally filesystem-
-first: the Agent writes Markdown and JSON under the user's existing Obsidian
-Vault, while hosted Template and Slideshow operations are performed later by
-the unified `easysociable` CLI/MCP.
-
-## Non-negotiable rules
-
-1. Obsidian must already be installed. If it is missing, stop and give the
-   official installation guidance; do not create a partial vault.
-2. Ask the user to choose **中文 (`zh`)** or **English (`en`)** before the first
-   preview. Do not default the locale silently.
-3. Ask the user to choose an existing Vault. Never create a new Vault silently.
-4. Create or validate only the locale root: `Content Engine/` (`en`) or
-   `内容引擎/` (`zh`). Never create both in one Vault.
-5. Existing Content Engine files are read-only during setup. Report differences
-   and ask before any migration; never auto-repair or overwrite user content.
-6. Do not start a Local API, open SQLite, call Content MCP, or call private
-   Directus/R2/Stripe endpoints.
-7. Every intent/run is saved under the locale runs folder (`runs/<slug>/` or
-   `成稿/<slug>/`). Every platform gets a Pack. Binary outputs belong only
-   under the locale exports folder.
-8. The host Agent owns copy and semantic decisions. Template and Slideshow Skills
-   own template selection, hosted preview and final rendering.
-9. V1 final output is PNG only. Never create ZIP, JPEG, WebP, PDF or video output.
-10. `content-pack.v1` JSON field names, `role` values and slot keys stay English
-    even when the vault language is 中文. Folder names and Markdown notes follow
-    the chosen locale.
-
-## Setup workflow
-
-1. Detect Obsidian.app.
-2. Ask: 内容引擎用中文还是 English？ Map the answer to `--locale zh` or `--locale en`.
-3. Ask for an existing Vault path.
-4. Preview with `scripts/setup.mjs --vault <path> --locale zh|en --preview --json`.
-5. Create the sanitized Starter and generalized `CLAUDE.md` only after confirmation,
-   using `--apply`.
-6. Open the Vault in Obsidian.
-7. Return the Vault path, locale, engine folder name, and the next workflow.
-
-The deterministic setup helper is `scripts/setup.mjs`. Use `--preview` before
-`--apply`; it never overwrites an existing file and refuses to create anything
-when Obsidian is not installed. It is a helper for the host Agent, not a
-separate product CLI.
-
-After setup, read `locale.json` in the engine root (or detect `内容引擎/` vs
-`Content Engine/`) and keep using that tree. Do not switch language later.
-
-The Starter contains empty indexes, templates and operating rules only. It must
-not contain the owner's personal examples, previous Runs or generated media.
-
-## Run and Pack workflow
-
-For each piece of content, create a local Run with:
-
-- a stable slug and title;
-- platform and language;
-- semantic outline and page roles;
-- generated copy and selected media references;
-- the chosen Profile/Theme identifiers when known;
-- links to the corresponding platform Pack and export Manifest.
-
-Write user-facing notes in the vault locale. The Pack is the handoff to
-`easysociable-slideshow`. It contains public page roles and slot values, never
-private AST, Binding Maps, RenderPlans or a hosted ContentDocument:
-
-```json
-{
-  "schemaVersion": "content-pack.v1",
-  "platform": "tiktok",
-  "title": "A short story",
-  "pages": [
-    { "role": "hook", "slots": { "text_0": "Hook", "text_1": "Support" } },
-    { "role": "value", "slots": { "text_0": "One idea" } }
-  ]
-}
+# EasySociable Content (pointer)
+
+This skill is an entry card only. **Do not invent a parallel workflow.**
+
+## Create the engine
+
+```bash
+easysociable engine init --root <parent-or-engine> --yes
+easysociable engine serve --engine <parent>/Content Engine --no-open
 ```
 
-## Handoff
+On a dedicated agent computer (e.g. Grok Bot), prefer `--root /workspace`.
+
+Existing files are never overwritten. `python3` is required for the workbench.
+
+## Operate
 
-For a single image, hand the selected published Page Template and slot values to
-the Template workflow. For a slideshow:
+Read and follow `Content Engine/CLAUDE.md` (and `engine.json`, `platforms/<platform>.md`).
 
-1. write the Pack to the Run folder;
-2. ask the Slideshow Skill to create/update a temporary Run;
-3. let the Agent review the returned Studio URL;
-4. after confirmation, let the Agent call `easysociable slideshows render`;
-5. let the Agent call `easysociable renders export` to atomically write PNGs and
-   `manifest.json` under the Run's exports directory.
+Rebuild the observatory after markdown writes:
 
-Preview is not a final local export and does not consume hosted Render Page
-allowance. The final render does.
+```bash
+easysociable engine build --engine <Content Engine>
+```
+
+## Render handoff
+
+| Intent | Hand off |
+|--------|----------|
+| 1 page image | **easysociable-template** |
+| 2+ pages on tiktok / instagram / linkedin / threads | **easysociable-slideshow** |
+| x / xiaohongshu images | **easysociable-template** only |
 
-Network research is optional. If the host does not expose a search tool, keep
-the source URL in the local note and continue with user-provided evidence; do
-not install an MCP server automatically and do not block vault setup.
+Validate a run before slideshow create:
+
+```bash
+easysociable engine validate --run <run-dir> --require-pack
+```
 
-## Required references
+## Out of scope
 
-- `references/PAGE_PACK.md`
-- `references/VAULT.md`
-- `workflows/CONTENT_EXPORT.md`
-- `workflows/MCP_FIRST.md` (for the unified CLI/MCP handoff only)
+No social posting, Content MCP, Local API, or SQLite content library.

package/skills/easysociable-slideshow/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: easysociable-slideshow
 description: >
-  Create and review temporary multi-page Slideshow Runs for EasySociable from a
-  local Obsidian Content Pack. Use the unified `easysociable` CLI or MCP, open
-  Studio for preview, and perform final PNG rendering only after confirmation.
-  There is no Slideshow Template product, UGC publishing, social posting or
-  separate Slideshow CLI/MCP in V1.
+  Create, list, update and review durable multi-page Slideshow Runs for
+  EasySociable from a local Obsidian Content Pack. Use the unified
+  `easysociable` CLI or MCP, open Studio for preview, and perform final PNG
+  rendering only after confirmation. Runs remain in the owner dashboard until
+  archive/trash. There is no Slideshow Template product, UGC publishing,
+  social posting or separate Slideshow CLI/MCP in V1.
 ---
 
 # EasySociable Slideshow Skill
@@ -27,8 +28,8 @@ It is not a reusable Carousel/Deck Template and it is not a public post.
    in Studio.
 6. Studio is preview-only. It has no final download, publish, unpublish, UGC,
    SEO/GEO or social-posting action.
-7. Agent revisions update the same unexpired Run. Studio activity extends the
-   seven-day TTL. Expired Runs are not recoverable through the public API.
+7. Before creating a new Run for an existing content intent, list/find prior Runs
+   by `contentSlug` and update the same Run when possible.
 8. Preview is free but rate/concurrency limited. Final rendering is PNG-only,
    uses one atomic reservation for all pages and charges only when every page
    succeeds.
@@ -38,15 +39,21 @@ It is not a reusable Carousel/Deck Template and it is not a public post.
 1. Validate the Pack and platform/page count.
 2. Resolve or create the user's Profile/Theme through the unified CLI/MCP.
 3. Select a compatible published Page Template for every page.
-4. Call:
+4. List existing Runs when the Pack has a stable content slug:
+
+   ```bash
+   easysociable slideshows list --content-slug my-post --json
+   ```
+
+5. Create or update:
 
    ```bash
    easysociable slideshows create --file ./pack.json --json
    ```
 
-5. Open the returned `studioUrl` and inspect every page.
-6. Save Studio edits and wait for the saved revision.
-7. After explicit confirmation, call:
+6. Open the returned `studioUrl` and inspect every page.
+7. Save Studio edits and wait for the saved revision.
+8. After explicit confirmation, call:
 
    ```bash
    easysociable slideshows render --id run_xxx --idempotency-key run_xxx-final-1 --json
@@ -60,7 +67,7 @@ It is not a reusable Carousel/Deck Template and it is not a public post.
 
 8. Verify checksums and the reconstruction `manifest.json` in the Obsidian
    Run export. The export is the local final deliverable; cloud artifacts expire
-   after 24 hours.
+   after 24 hours while the Run remains listed for the owner.
 
 ## Failure handling
 
@@ -68,10 +75,11 @@ It is not a reusable Carousel/Deck Template and it is not a public post.
   error to the Agent; do not substitute another template.
 - If any final page fails, there is no partial final set and no page charge.
 - Retry the same final request with the same idempotency key to reuse the Job.
-- If the Run is expired, create a new Run from the Pack.
+- If a Run was trashed, create a new Run from the Pack.
 
 ## 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-slideshow/references/VAULT.md

@@ -1,18 +1,20 @@
 # Obsidian export
 
-The local Obsidian Run folder is the final delivery mirror:
+Final PNGs are written at the **engine root exports directory**:
 
 ```text
-Content Engine/            or  内容引擎/
-└── runs/<slug>/           or  成稿/<slug>/
-    └── exports/<slug>/<platform>/   or  导出/<slug>/<platform>/
-        ├── 01.png
-        ├── 02.png
-        └── manifest.json
+Content Engine/exports/<slug>/<platform>/     (en)
+内容引擎/导出/<slug>/<platform>/               (zh)
+    ├── 01.png
+    ├── 02.png
+    └── manifest.json
 ```
 
-Read `locale.json` in the engine root (`en` or `zh`) and use that tree. Pack JSON keys stay English.
+Semantic work and Packs stay under `runs/<slug>/` or `成稿/<slug>/`. Do not
+write PNGs inside the run folder.
 
-The CLI verifies checksums and atomically replaces this directory only after a
-complete atomic Hosted Render succeeds. No ZIP is created. The cloud artifact
-may expire after 24 hours; the local PNGs remain the user's files.
+Read `locale.json` in the engine root. Pack JSON keys stay English.
+
+The CLI verifies checksums and atomically replaces the export directory only
+after a complete atomic Hosted Render succeeds. No ZIP is created. Cloud
+artifacts may expire after 24 hours; local PNGs remain the user's files.

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.