@easysociable/cli 0.1.2 → 0.1.4

package/skills/easysociable-slideshow/SKILL.md

@@ -2,83 +2,118 @@
 name: easysociable-slideshow
 description: >
   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 from a local Content Pack. Name the argument (arc) first, then
+  pick a Page Template per page by platform, canvas, slotSummary and density —
+  never default Cover→Point→Steps→Recap→CTA. Page 1 must be a cover or hook
+  class template; those templates must not appear on later pages. Use the
+  unified `easysociable` CLI or MCP, open Studio to preview and edit, then
+  ask the user to click Download for a PNG ZIP. CLI/MCP must not call
+  render/export or create_render_job for final pixels. Runs remain in the
+  owner dashboard until archive or hard delete.
 ---
 
 # EasySociable Slideshow Skill
 
-A Slideshow Run is a temporary composition of explicit single-page Templates.
+A Slideshow Run is a composition of explicit single-page Templates.
 It is not a reusable Carousel/Deck Template and it is not a public post.
+Page order is the argument of **this pack**, not a catalog recipe.
 
 ## Rules
 
-1. Read a local `content-pack.v1` from the Obsidian Content Engine.
+1. Read a local `content-pack.v1` from the Content Engine.
 2. Use the unified `easysociable` CLI or the unified MCP server. All hosted
    calls go through Gateway; never call Directus, R2, Stripe or private services.
-3. The Agent must choose a Profile, one Theme and an explicit Page Template for
-   every page. The server never silently chooses or replaces a Page Template.
-4. A Run has 1–20 pages, one supported platform (`tiktok`, `instagram`,
-   `linkedin` or `threads`) and one Profile/Theme across all pages.
-5. Topology is fixed after creation: no add, copy, delete, reorder or template
+3. Choose a Brand (or Profile/Theme) and an explicit Page Template for every
+   page. The server never silently chooses or replaces a Page Template.
+   Select by **platform + canvas + slotSummary + density**. `role` is a weak
+   retrieval tag, not sequence position.
+4. **Cover / hook placement (hard):** a template is cover/hook class when
+   `supportedRoles` includes `cover` or `hook`. `pages[0]` must use one.
+   Cover/hook class templates must not appear on any later page. Later pages
+   use metric / quote / compare / value / steps / cta / etc. Do not put a
+   Point or metric-only template on page 1 to “open with a number” — pick a
+   cover or hook template whose slots fit the opening copy.
+5. A Run has up to 8 pages on Free and 20 on paid, one supported platform
+   (`tiktok`, `instagram`, `linkedin` or `threads`) and one Brand across pages.
+6. Topology is fixed after creation: no add, copy, delete, reorder or template
    switch. Page-instance slot/layout/type/style/decoration edits remain allowed
    in Studio.
-6. Studio is preview-only. It has no final download, publish, unpublish, UGC,
-   SEO/GEO or social-posting action.
-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.
+7. Final pixels leave the product only from **Studio Download** (browser PNG
+   ZIP). Do not call `slideshows render`, `slideshows export`, `renders create`
+   or MCP `render_slideshow_run` / `create_render_job`. Those return
+   `HEADLESS_RENDER_DISABLED`.
+8. Before creating a new Run, list/find prior Runs by `contentSlug`. **Update**
+   the same Run only when page count, pageTemplateIds, and intended sequence
+   still match. A different arc or template set is a **new Run** — never PATCH
+   new copy into a locked Cover-Point-Steps-Recap-CTA skeleton.
+8b. **Knowledge hard gate (every create, not only the first Run):** before
+    `create_run` / `slideshows create`, read Identity (Role / What I build /
+    Point of view — no `(fill)`, non-empty) and `boundaries.md` (Not covering
+    and Never claim non-empty), or run
+    `easysociable engine validate --run <run-dir> --require-knowledge`.
+    If `needs/` exists, `needs/_index.md` ≥ 3 `N-` rows; if `needs/` is absent, skip that count. Fail → hand back to
+    **easysociable-content** / refuse create; list missing files. Do not add
+    Gateway or MCP params. User must say **强制继续** / **force continue**
+    to call Gateway.
+9. Preview is free. Free Download is 3 successful ZIPs per month and one
+   platform. Paid Download is unmetered.
+10. **Forbidden default:** do not assemble Cover → Point → Steps → Recap → CTA
+    because those are P0 family names. Name the arc first
+    (`references/ARC.md`). Page count follows the argument, not the catalog.
+    Rule 4 still applies: page 1 is cover/hook class, not “whatever family
+    is named Cover”.
 
 ## Workflow
 
-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. List existing Runs when the Pack has a stable content slug:
+1. Write one arc line (`references/ARC.md`). Do not skip this for a five-family fill-in.
+2. Validate the Pack and platform/page count.
+3. Resolve or create the user's Brand through the unified CLI/MCP.
+4. List the published catalog. `pages[0]` must be cover/hook class
+   (`supportedRoles` includes `cover` or `hook`). Remaining pages: platform +
+   canvas + slot counts + density — not `beat name == family name`. Never
+   place a cover/hook class template after page 1.
+5. List existing Runs when the Pack has a stable content slug:
 
    ```bash
    easysociable slideshows list --content-slug my-post --json
    ```
 
-5. Create or update:
+6. **Hard gate, then** create (new arc/templates) or update (same topology,
+   slot copy only). Check files or:
 
    ```bash
-   easysociable slideshows create --file ./pack.json --json
+   easysociable engine validate --run <run-dir> --require-pack --require-knowledge
    ```
 
-6. Open the returned `studioUrl` and inspect every page.
-7. Save Studio edits and wait for the saved revision.
-8. After explicit confirmation, call:
+   Fail → refuse; return to **easysociable-content**. **强制继续** / **force continue**
+   is the only override (conversational — not a CLI flag). Then:
 
    ```bash
-   easysociable slideshows render --id run_xxx --idempotency-key run_xxx-final-1 --json
-   easysociable slideshows export --id run_xxx --output ./exports/run_xxx/tiktok --json
+   easysociable slideshows create --file ./pack.json --json
    ```
 
-   Hosted finals use one Run capture session + one Imagine deck screenshot
-   (single browser load, N page PNGs). Require Studio Save (`layout.studioJson`
-   + `themeSnapshot`) before render. Single-page Template jobs still use
-   `renders create|wait|export`.
-
-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 while the Run remains listed for the owner.
+7. Open the returned `studioUrl` and inspect every page.
+8. Save Studio edits and wait for the saved revision.
+9. After explicit user confirmation, tell them to click **Download** in Studio.
+   Do not render or export from CLI/MCP.
 
 ## Failure handling
 
+- If the knowledge hard gate fails, do not create the Run. Hand back to
+  easysociable-content and list missing files unless the user said
+  **强制继续** / **force continue**.
+- If page 1 is not cover/hook class, or a later page uses a cover/hook
+  class template, stop and rebuild the Pack. Do not create the Run.
 - If a page template, slot or image is invalid, return the structured Gateway
   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 a Run was trashed, create a new Run from the Pack.
+- If Download is exhausted (`USAGE_LIMIT_REACHED`) or past due, tell the user
+  to upgrade or update billing.
+- If a Run was deleted, or Gateway returns `RUN_TOPOLOGY_LOCKED` because the
+  pack changed sequence/templates, 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 owns semantic copy, Pack creation, and the arc.
+The Template Skill owns single-page authoring and publish.
+This Skill composes explicit page instances and opens Studio for review/Download.
+It does not own a product-level story recipe.

package/skills/easysociable-slideshow/references/ARC.md

@@ -0,0 +1,44 @@
+# Arc (argument, then pages)
+
+A Slideshow Run is an argument that only works if the viewer turns the page.
+Page order is a property of **this piece of content**, not of the catalog.
+
+Do **not** invent a product-level `arc` field, Deck SKU, or
+`pageSequence: [cover, point, steps, recap, cta]`.
+
+## Forbidden default
+
+Never default a Pack to Cover → Point → Steps → Recap → CTA
+because those are P0 family names. That sequence is one possible recipe, not
+the product shape. Page count follows the argument (TikTok often 4–8), not
+the number of P0 families.
+
+## Before pages
+
+Write one arc line, then map each beat to slots.
+
+**Page 1 is cover/hook class.** A template is cover/hook class when
+`supportedRoles` includes `cover` or `hook`. That class belongs only on
+`pages[0]`. Opening copy may still be a cost, quote, or compare *line* —
+fill a cover or hook template whose `slotSummary` fits. Do not open with a
+metric/point/quote template.
+
+Later pages pick by slot shape (metric, quote, compare, value, steps, cta).
+
+## Recipes (swipe formulas, not system enums)
+
+Pick one, or name a new one-liner. Do not expand this into an official catalog.
+
+| Recipe | Beats |
+|---|---|
+| cost-mechanism | cost → mechanism → method → close → action |
+| listicle | hook + N items + CTA |
+| mistakes | hook + errors + fix + CTA |
+| claim-proof | claim → evidence → implication → CTA |
+| compare | old way / new way / why / CTA |
+
+## After create
+
+Topology is locked. Wrong arc or wrong templates → **new Run**.
+Do not PATCH copy into a locked Cover-Point-Steps-Recap-CTA skeleton.
+`contentSlug` finds prior drafts; it does not keep a bad sequence alive.

package/skills/easysociable-slideshow/references/CONTENT_PACK.md

@@ -1,5 +1,36 @@
 # ContentPack v1
 
+Page `role` is a **weak retrieval tag** (layout-ish), not sequence position.
+`pageTemplateId` is the explicit published single-page template chosen by the
+Agent. `slots` are public values only. Do not add a `deck_template_id`,
+`bindingMap`, AST, ContentDocument, or product `arc` / `pageSequence`.
+
+The Gateway validates each `role` against the closed enum and that slots exist.
+It does not require Cover → Point → Steps → Recap → CTA.
+
+This skill **does** require page 1 to be cover/hook class (`supportedRoles`
+includes `cover` or `hook`) and forbids that class on later pages.
+
+## Example: cost → mechanism (TikTok)
+
+Opening beat is cost; page 1 is still a hook-class template.
+
+```json
+{
+  "schemaVersion": "content-pack.v1",
+  "platform": "tiktok",
+  "title": "Stop briefing a blank canvas",
+  "pages": [
+    { "role": "hook", "pageTemplateId": "tpl_hook_001", "slots": { "text_0": "You finish the copy. Then you start over.", "text_1": "The design file kept none of the argument." } },
+    { "role": "point", "pageTemplateId": "tpl_stack_001", "slots": { "text_0": "Roles, Brand, Layouts persist" } },
+    { "role": "steps", "pageTemplateId": "tpl_stair_001", "slots": { "text_0": "Use them in that order" } },
+    { "role": "cta", "pageTemplateId": "tpl_close_001", "slots": { "text_0": "Don't brief a blank canvas" } }
+  ]
+}
+```
+
+## Example: hook → value → cta
+
 ```json
 {
   "schemaVersion": "content-pack.v1",
@@ -13,12 +44,9 @@
 }
 ```
 
-Page `role` is semantic and `pageTemplateId` is the explicit published
-single-page template chosen by the Agent. `slots` are public values only. Do not
-add a `deck_template_id`, `bindingMap`, AST or ContentDocument.
-
-The Gateway validates that each selected template supports the page role and
-belongs to the account-visible catalog. It never silently replaces a selection.
+Pick templates by **platform + canvas + slotSummary + density**, not by matching
+the beat name to a family named Cover / Point / Steps / Recap / CTA. Page 1
+must still be cover/hook class.
 
 The renderer accepts any supported page count within the platform cap. A newly
 published Page Template can be selected in a new Run without creating a

package/skills/easysociable-slideshow/workflows/CREATE_RUN.md

@@ -1,7 +1,26 @@
 # Create Run
 
-1. Build `content-pack.v1` from the agent's semantic outline.
-2. Check platform hardMin/hardMax.
-3. Call `create_run` or `run create` through Gateway.
-4. Save `runId`, `studioUrl`, and `status=draft`.
-5. Do not call a Deck API or create a carousel template.
+1. Write one arc line (`references/ARC.md`). Forbidden default:
+   Cover → Point → Steps → Recap → CTA.
+2. Build `content-pack.v1` from that argument. Page count follows the beats
+   (TikTok often 4–8), not the number of P0 families.
+3. Check platform hardMin/hardMax.
+4. List published Page Templates. `pages[0]` must be cover/hook class
+   (`supportedRoles` includes `cover` or `hook`). Do not use that class on
+   later pages. Remaining pages: platform + canvas + `slotSummary` + density.
+   `role` is a weak tag.
+5. If `contentSlug` already has a Run: update only when topology matches
+   (same page count and `pageTemplateId`s). Otherwise create a new Run.
+6. **Before** `create_run` / `slideshows create` (every create, not only the
+   first Run): check the knowledge hard gate — Identity Role / What I build /
+   Point of view have no `(fill)` and are non-empty; `boundaries.md` exists
+   with Not covering and Never claim non-empty; if `needs/` exists, ≥3 `N-`
+   rows, else skip. Read the files or run
+   `easysociable engine validate --run <run-dir> --require-knowledge`.
+   Fail → hand back to **easysociable-content** / refuse create; list missing
+   files. User must say **强制继续** / **force continue** to call Gateway.
+   No new Gateway or MCP params.
+7. Call `create_run` / `slideshows create` through Gateway.
+8. Save `runId`, `studioUrl`, and `status=draft`.
+9. Do not call a Deck API, create a carousel template, or send a product
+   `pageSequence` / `arc` field.

package/skills/easysociable-slideshow/workflows/OUT_OF_SCOPE.md

@@ -1,6 +1,9 @@
 # Out of scope
 
 - DeckTemplate creation, `list_decks`, `CREATE_DECK`, or `BIND_P0_DECKS`.
+- Product-level `arc` / Deck `pageSequence` SKUs (ADR-0026). Structure stays in the Content Pack.
+- Defaulting every Run to Cover → Point → Steps → Recap → CTA.
+- Cover/hook class templates on page 2+ (they belong on `pages[0]` only).
 - ContentDocument as a render input (ADR-0021).
 - Client-side RenderPlan or AST compilation.
 - Full cross-platform Page Template coverage and ad-placement variants.

package/skills/easysociable-template/SKILL.md

@@ -2,19 +2,15 @@
 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.
+  Template MCP or `easysociable` CLI. 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, write a shared visual
+  design philosophy, explore layout concepts, co-create Theme/preview tokens, pull icons
+  via search_icons/get_icon, open Authoring Studio, or publish. Do not use for
+  fill-slots hosted PNG jobs (`create_render_job` is retired), multi-slide slideshow
+  composition, ContentDocument as render input, or carousel packs. Customer PNG packs
+  come from Slideshow Studio Download.
 ---
 
 # EasySociable Template Skill
@@ -23,12 +19,12 @@ The public entry points are the unified `easysociable` CLI and one unified MCP
 server. Do not install or invoke `easysociable-template`, `easysociable-slideshow`,
 `easysociable-content`, or a separate Content/Slideshow MCP in V1.
 
-**This skill owns two single-page paths:**
+**This skill owns template authoring:**
 
-1. **Author** templates (Studio + Publish).
-2. **Fill slots → Hosted Render** for a published PageTemplate (`workflows/FILL_AND_RENDER.md`).
+1. **Author** templates as a **Layout Family** (master + multi-platform variants) → Studio + Publish (`workflows/MULTI_PLATFORM_FAMILY.md`).
+2. Fill-slots Hosted Render (`create_render_job`) is **retired** as a paid delivery path. Customer PNG packs come from Slideshow Studio Download.
 
-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. It is **not** a multi-slide slideshow compositor and it is **not** a PNG API.
 
 Every published page must carry **P0 catalog metadata** so Agents can filter and fill templates (`references/CATALOG_METADATA.md`).
 
@@ -45,22 +41,23 @@ 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.
+12. `supportedRoles` uses closed **pageRoles** as a **weak retrieval tag**, not sequence position. Family `name` describes **layout** (Poster / Stack / Count / Stair / Close), not a narrative beat. `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`.
-20. **Hosted Capture first:** default delivery is Hosted Artifact. Local capture only when the error includes `fallback.capture` — follow `workflows/FILL_AND_RENDER.md` §5 (CLI `capture` or same-URL Playwright). Do not use page html-to-image buttons as the Agent primary path.
+19. **Consumption is Slideshow Studio Download**, not fill-slots Hosted Render. `create_render_job` / CLI `renders create` return `HEADLESS_RENDER_DISABLED`. See `workflows/FILL_AND_RENDER.md`.
+20. **Do not** treat Hosted Capture or local html-to-image as the Agent primary PNG path.
 21. **Icons (hard rule — no shortcuts):**
     - Any **recognizable icon** (arrows, chevrons, checkmarks, social glyphs, UI symbols, “next page” cues, etc.) **MUST** use Gateway Icon Catalog:
       `search_icons` / CLI `icons search` → show ≤8 candidates → **user confirm** (or explicit “你定 / 用第 N 个”) → `get_icon` / CLI `icons get --idempotency-key …` → embed returned **`canonicalSvg`** and record **`iconAssetId`** / `iconId` on the decoration node.
@@ -79,11 +76,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 +89,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

@@ -5,9 +5,10 @@ Private AST/bindings stay server-side; this document is the **public selection c
 
 ## Design choices (locked)
 
-1. **One closed `pageRoles` set** (stored as `supportedRoles`) — narrative beat + layout kind in one enum. Do not maintain a second parallel taxonomy.
+1. **One closed `pageRoles` set** (stored as `supportedRoles`) — a **retrieval tag for layout kind**, not page position and not a story recipe. `cover` means poster-like slots, not “must be page 1”. Do not add a parallel `arc` / `pageSequence` taxonomy (ADR-0026).
 2. **`platforms` is a multi-select array**. Include `generic` when the page fits any platform at that aspect.
 3. **P0 fields are required to Publish.** P1 should be filled when known; P2 optional.
+4. **Family `name` describes layout**, not a narrative beat. Prefer Poster / Stack / Count / Stair / Close (plus platform). Do not name families Cover / Point / Steps / Recap / CTA — choosers will glue those five names into one default pack.
 
 Max **1–2** `supportedRoles` per page (primary + optional secondary).
 
@@ -33,25 +34,25 @@ Always also store exact `canvas: { width, height }`. Use `16:9` for X **1200×67
 
 ### Page roles (`supportedRoles` / pageRoles) — pick 1–2
 
-| Role | When to use |
+| Role | Layout kind (not sequence position) |
 |---|---|
-| `cover` | Cover / first-frame poster |
-| `hook` | Scroll-stop hook (often with cover) |
-| `setup` | Setup / problem framing |
-| `context` | Background / context |
-| `value` | Single takeaway / value page |
+| `cover` | Poster / first-frame-capable layout — may open a run, need not |
+| `hook` | Scroll-stop / short-copy layout |
+| `setup` | Problem-framing layout |
+| `context` | Background / context layout |
+| `value` | Single takeaway layout |
 | `point` | One sharp point (lighter than value) |
 | `checklist` | Fixed N text lines (no list binding type) |
-| `proof` | Proof / credibility |
+| `proof` | Proof / credibility layout |
 | `evidence` | Evidence artifacts (data, case) |
-| `compare` | Before/after or A/B compare |
+| `compare` | Before/after or A/B layout — valid as page 1 |
 | `screenshot` | App/web UI screenshot frame |
-| `metric` | Big number / KPI / milestone |
-| `quote` | Pull quote / testimonial |
-| `steps` | Fixed-step howto |
-| `cta` | Call to action |
-| `follow` | Follow / profile CTA |
-| `recap` | Summary / closing recap |
+| `metric` | Big number / KPI — valid as page 1 |
+| `quote` | Pull quote / testimonial — valid as page 1 |
+| `steps` | Fixed-step howto layout |
+| `cta` | Call to action layout |
+| `follow` | Follow / profile CTA layout |
+| `recap` | Summary / closing layout |
 
 Legacy-compatible: `cover`, `setup`, `value`, `proof`, `cta` remain valid.
 
@@ -98,7 +99,7 @@ hero | screenshot | avatar | product
 
 | Field | Type | Notes |
 |---|---|---|
-| `name` | string | Human title |
+| `name` | string | Human title — **layout**, not beat (e.g. `P0 Poster TikTok`, not `P0 Cover TikTok`) |
 | `shortDescription` | string | One sentence for chooser UI |
 | `platforms` | `Platform[]` | Multi-select; use `generic` when truly cross-platform |
 | `canvasPreset` | preset enum | Plus exact `canvas` pixels |
@@ -134,11 +135,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
@@ -189,7 +190,7 @@ Agent must produce a `selection-metadata.json` (or equivalent fields on the draf
 
 ```json
 {
-  "name": "XHS metric milestone 3:4",
+  "name": "XHS Count 3:4",
   "shortDescription": "大数字涨粉庆祝页，可选头像",
   "platforms": ["xiaohongshu", "generic"],
   "canvasPreset": "3:4",
@@ -207,7 +208,7 @@ Agent must produce a `selection-metadata.json` (or equivalent fields on the draf
   "visualStyle": "swiss",
   "bestFor": ["涨粉节点", "数据庆祝封面"],
   "notFor": ["长清单干货", "多步教程"],
-  "selectionHints": "Prefer when slide.role is metric or cover and a single KPI dominates.",
+  "selectionHints": "Prefer when slotSummary has one number + short text (KPI / cost hook), any page index.",
   "locale": "zh-CN"
 }
 ```
@@ -219,3 +220,5 @@ Agent must produce a `selection-metadata.json` (or equivalent fields on the draf
 - Checklist without `fixedItemCount`
 - `requiresImage: true` but `imageRoles` empty
 - Platforms empty or inventing values outside the enum
+- Naming a family Cover / Point / Steps / Recap / CTA so choosers assemble that sequence
+- Treating `supportedRoles` as “this page must appear at this beat in every Run”

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.