@easysociable/cli 0.1.17 → 0.1.19

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

@@ -0,0 +1,97 @@
+# Reference designs
+
+A reference is a published catalog design (one canvas: the source post's) made
+from a real post. Pages are **adapted from references**: you keep a reference's
+composition, type scale, spacing and chrome, and replace content, colours
+(Brand) and canvas size. You never copy one verbatim and never draw a page with
+no reference at all.
+
+Find references for a page role, shuffled, as short summaries:
+
+```bash
+easysociable templates references --role hook,cover [--no-image] [--style <style>] [--exclude <familyIds>] --json
+easysociable templates source --family <familyId> --json   # the design's Studio source
+```
+
+Roles overlap in the catalog, so pass related ones together: `hook,cover` ·
+`point,value,steps,checklist` · `metric,proof,evidence` · `compare` ·
+`screenshot` (needs an image) · `recap` · `cta,follow`. Styles: `minimal`,
+`editorial`, `swiss`, `dark`, `bold_promo`.
+
+## Adapting a reference (the rules that make it look designed)
+
+1. Start from the reference's source. Keep its chrome (header, pill, page
+   number, rule, footer) only if the deck keeps it on every page; keep its
+   margins (`left` of the first column), type scale and fonts.
+2. Fit the Run's canvas: a reference made for another canvas (3:4, 9:16, 4:5)
+   keeps its left margin and type scale; re-space vertically, never squash text.
+3. Change text, then fix each text box: explicit `<br />` line breaks, and
+   `height` = lines × lineHeight + ~12% of fontSize for descenders.
+4. Remove what you do not need; add only elements copied from another reference
+   with the same `style` (rule rows, a stat row).
+5. Brand chrome: the header label is the Brand name (or the topic when there is
+   no Brand); the CTA names the Brand handle. Never leave a reference's original
+   name or handle (e.g. "Will.AI.m") on a page. **Bind them** so a Brand change
+   updates every page: the element holding only the Brand name gets
+   `data-brand="name"`, only the handle `data-brand="handle"`, and an avatar /
+   logo `<img>` gets `data-brand="avatar"` with the Brand's `logoUrl` as `src`.
+   Without a Brand, leave them unbound (the topic is not the Brand).
+6. Accent colour only on large text (≥ 36px, or ≥ 28px bold) and blocks. Small
+   labels use the text or muted colour.
+7. Semantic `data-type` values (`title`, `subtitle`, `kicker`, `metric`,
+   `caption`) get Brand colours forced by Studio. Text on an accent or image
+   block uses `label`, `body` or `statement` with an explicit colour.
+8. One deck = one `style`. No reference twice in a Run unless the page purpose
+   repeats (several numbered points), and no two adjacent pages with the same
+   composition.
+
+## Avoid (what makes every Run look the same)
+
+- The same cover composition as this Brand's previous Run, unless the user
+  asked for "same as last time".
+- Header label + pill + page number + "SWIPE →" on every page by habit: chrome
+  comes from the chosen reference, or there is none.
+- An accent-coloured second half of the headline on more than two pages.
+- A deck that is only left-aligned text stacks: at least one page's focal point
+  is not a headline (a big number, an image, a quote, a comparison).
+- A generic "Save this / Follow for more" CTA when the content suggests a
+  specific action (comment a word, try the prompt, read the source).
+
+## Default palettes (no Brand)
+
+Use one in `theme.json` as `{ "color": { "canvas", "text", "textMuted", "accent", "primary" } }`
+(`primary` = `accent`), matched to the deck's style:
+
+| Style | canvas / text / textMuted / accent |
+|---|---|
+| `editorial` | `#F4EEE7` / `#121A2B` / `#4A4F5C` / `#D4450F` |
+| `minimal`, `swiss` | `#FFFFFF` / `#15191E` / `#384352` / `#445164` |
+| `dark` | `#06080C` / `#FFFFFF` / `#C7CBD3` / `#4C9BFF` |
+| `bold_promo` | `#F9F9F9` / `#0A0A0A` / `#555555` / `#0066DD` |
+
+## Image placeholder
+
+A replaceable image slot for a real screenshot or photo the user will add.
+Studio shows an upload button when it is selected.
+
+```jsx
+<img data-type="image" data-variable="image_0" data-image-mode="slot_default"
+  alt="Add: <what goes here>" src="data:image/svg+xml;base64,<SVG>"
+  style={{ position: 'absolute', left: 88, top: 760, width: 904, height: 388, objectFit: 'cover', borderRadius: 24 }} />
+```
+
+`<SVG>` is base64 of a grey box with an image icon and the label, sized to the slot:
+
+```xml
+<svg xmlns='http://www.w3.org/2000/svg' width='904' height='388' viewBox='0 0 904 388'>
+  <rect width='904' height='388' fill='#DDD6CC'/>
+  <g transform='translate(416,124)' fill='none' stroke='#8C8781' stroke-width='5' stroke-linejoin='round'>
+    <rect width='72' height='56' rx='8'/><path d='M6 50 L26 28 L40 42 L50 34 L66 50'/><circle cx='52' cy='16' r='6'/>
+  </g>
+  <text x='50%' y='230' text-anchor='middle' font-family='Inter, Arial, sans-serif' font-size='32' font-weight='600' fill='#6F6A64'>Add: Grok Bot app screenshot</text>
+</svg>
+```
+
+Put the same data URL in the page's `slots` under `image_N`. Number slots
+`image_0`, `image_1`, … per page. Use the style's own colours for the box
+(canvas-adjacent grey on light styles, `#1A1F27` on dark ones).

package/skills/easysociable-slideshow/scripts/check-pages.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// Render every page of a content-pack.v1 with the system Chrome (no npm deps) and check it
+// the way a phone viewer sees it. Exit 0 = pass, 1 = errors (fix before create), 2 = no Chrome.
+//
+//   node check-pages.mjs pack.json --out ./shots [--brand brand.json | --theme theme.json]
+//
+// --brand takes `easysociable brands get --id <id> --json` output; without it the Studio
+// default (dark) theme is used, same as a Run without a Brand.
+import { execFileSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const args = process.argv.slice(2)
+const flag = name => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined }
+const packPath = args.find(a => !a.startsWith('--') && a !== flag('--out') && a !== flag('--brand') && a !== flag('--theme'))
+if (!packPath) { console.error('usage: node check-pages.mjs pack.json --out <dir> [--brand brand.json]'); process.exit(1) }
+const outDir = resolve(flag('--out') ?? 'shots')
+mkdirSync(outDir, { recursive: true })
+
+const pack = JSON.parse(readFileSync(packPath, 'utf8'))
+const themeFile = flag('--brand') ?? flag('--theme')
+const brandRaw = themeFile ? JSON.parse(readFileSync(themeFile, 'utf8')) : null
+const brand = brandRaw?.data ?? brandRaw
+const c = brand?.colors ?? brand?.color ?? {}
+// Studio default theme (apps/easysociable/app/lib/themeTokens.ts DEFAULT_AUTHORING_THEME_TOKENS).
+const colors = { canvas: c.canvas ?? '#0f1419', text: c.text ?? '#e8eef5', muted: c.textMuted ?? c.muted ?? '#8b9bb0', accent: c.accent ?? '#5b8cff', primary: c.primary ?? c.accent ?? '#5b8cff' }
+
+const chrome = [process.env.CHROME_PATH,
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'].find(p => p && existsSync(p))
+if (!chrome) { console.error('No Chrome/Chromium found (set CHROME_PATH). Render checks skipped.'); process.exit(2) }
+
+// ponytail: mirrors Studio's forced semantic colors by data-type; update if themeTokens.ts changes.
+const themeCss = `[data-authoring-theme]{--es-color-canvas:${colors.canvas};--es-color-text:${colors.text};--es-color-muted:${colors.muted};--es-color-accent:${colors.accent};--es-color-primary:${colors.primary}}
+[data-authoring-theme] [data-type="post"]{background-color:var(--es-color-canvas);color:var(--es-color-text)}
+[data-authoring-theme] [data-type="title"],[data-authoring-theme] [data-type="subtitle"]{color:var(--es-color-text)!important}
+[data-authoring-theme] [data-type="kicker"]{color:var(--es-color-accent)!important}
+[data-authoring-theme] [data-type="metric"]{color:var(--es-color-primary)!important}
+[data-authoring-theme] [data-type="caption"]{color:var(--es-color-muted)!important}
+html,body{margin:0;background:#fff}#report{display:none}`
+
+// Runs inside the Chrome page: JSX source → DOM, then measure. Source is evaluated in the page sandbox, not in Node.
+const pageScript = String.raw`
+const UNITLESS = new Set(['fontWeight','lineHeight','opacity','zIndex','flex','flexGrow','flexShrink'])
+const toCss = o => Object.entries(o).map(([k,v]) => k.replace(/[A-Z]/g, m => '-' + m.toLowerCase()) + ':' + (typeof v === 'number' && !UNITLESS.has(k) ? v + 'px' : v)).join(';')
+const toHtml = jsx => jsx
+  .replace(/style=\{\{([\s\S]*?)\}\}/g, (_, body) => 'style="' + toCss(Function('return {' + body + '}')()).replace(/"/g, "'") + '"')
+  .replace(/style="([^"]*)"/g, (_, body) => 'style="' + body.replace(/(^|;)\s*([a-z]+[A-Z][A-Za-z]*)\s*:/g, (m, sep, k) => sep + k.replace(/[A-Z]/g, c => '-' + c.toLowerCase()) + ':') + '"')
+  .replace(/className=/g, 'class=').replace(/\{' '\}/g, ' ')
+  .replace(/<(div|p|h1|h2|h3|span|img)(\s[^>]*?)\s*\/>/g, (_, t, a) => t === 'img' ? '<img' + a + '>' : '<' + t + a + '></' + t + '>')
+const stage = document.getElementById('stage'), GRID = location.hash === '#grid', S = 0.5
+for (const [i, src] of SOURCES.entries()) {
+  const box = document.createElement('div')
+  box.setAttribute('data-authoring-theme', '')
+  box.innerHTML = toHtml(src.json)
+  if (GRID) { box.style.cssText = 'width:' + src.width * S + 'px;height:' + src.height * S + 'px;overflow:hidden'; box.firstElementChild.style.transform = 'scale(' + S + ')'; box.firstElementChild.style.transformOrigin = '0 0' }
+  stage.appendChild(box)
+}
+if (GRID) stage.style.cssText = 'display:grid;grid-template-columns:repeat(' + COLS + ',max-content);gap:16px;padding:16px;background:#888'
+const lum = rgb => { const [r,g,b] = rgb.map(v => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 }); return 0.2126*r + 0.7152*g + 0.0722*b }
+const parse = s => { const m = s.match(/rgba?\(([^)]+)\)/); if (!m) return null; const p = m[1].split(/[ ,\/]+/).filter(Boolean).map(Number); return { rgb: p.slice(0,3), a: p[3] ?? 1 } }
+const ratio = (a, b) => { const [x,y] = [lum(a), lum(b)].sort((m,n) => n - m); return (x + 0.05) / (y + 0.05) }
+function measure(root) {
+  const R = root.getBoundingClientRect(), W = R.width, H = R.height, k = W / 1080
+  const errors = [], warnings = []
+  const texts = [...root.querySelectorAll('[data-variable^="text"], p, h1, h2, h3')].filter((e, i, all) => e.textContent.trim() && !all.some(o => o !== e && o.contains(e)))
+  const label = e => (e.dataset.variable ? e.dataset.variable + ' ' : '') + JSON.stringify(e.textContent.trim().slice(0, 40))
+  let words = 0
+  for (const e of texts) {
+    const cs = getComputedStyle(e), r = e.getBoundingClientRect(), size = parseFloat(cs.fontSize), n = e.textContent.trim().split(/\s+/).length
+    if (e.dataset.type !== 'decoration' && e.dataset.type !== 'label') words += n
+    if (e.scrollHeight > e.clientHeight + 2 || e.scrollWidth > e.clientWidth + 2) errors.push('overflow: ' + label(e) + ' needs ' + e.scrollWidth + 'x' + e.scrollHeight + ', box ' + e.clientWidth + 'x' + e.clientHeight)
+    if (r.left < R.left - 2 || r.top < R.top - 2 || r.right > R.right + 2 || r.bottom > R.bottom + 2) errors.push('off-canvas: ' + label(e))
+    if (n >= 6 && size < 28 * k) warnings.push('small text (' + size + 'px, min ' + Math.round(28 * k) + '): ' + label(e))
+    // Contrast: the element and each coloured span against the first opaque background under its centre.
+    const stack = document.elementsFromPoint(r.left + r.width / 2, r.top + Math.min(r.height / 2, size))
+    let bg = null
+    for (const el of stack) { if (el.tagName === 'IMG') break; const p = parse(getComputedStyle(el).backgroundColor); if (p && p.a > 0.5) { bg = p.rgb; break } }
+    if (bg) for (const part of [e, ...e.querySelectorAll('span')]) {
+      if (part !== e && !part.textContent.trim()) continue
+      const pc = getComputedStyle(part), fg = parse(pc.color), fs = parseFloat(pc.fontSize), large = fs >= 36 * k || (fs >= 28 * k && Number(pc.fontWeight) >= 700)
+      const cr = fg && ratio(fg.rgb, bg)
+      if (cr && cr < 3) errors.push('contrast ' + cr.toFixed(2) + ':1 (min ' + (large ? 3 : 4.5) + '): ' + label(part))
+      else if (cr && !large && cr < 4.5) warnings.push('contrast ' + cr.toFixed(2) + ':1 on small text (min 4.5): ' + label(part))
+    }
+  }
+  for (let i = 0; i < texts.length; i++) for (let j = i + 1; j < texts.length; j++) {
+    const a = texts[i].getBoundingClientRect(), b = texts[j].getBoundingClientRect()
+    const ix = Math.min(a.right, b.right) - Math.max(a.left, b.left), iy = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top)
+    if (ix > 4 && iy > 4) errors.push('text overlap: ' + label(texts[i]) + ' / ' + label(texts[j]))
+  }
+  if (words > 60) warnings.push(words + ' words on one page (aim <= 45): split it')
+  // Largest empty horizontal band, ignoring full-bleed backgrounds.
+  const spans = [...root.querySelectorAll('*')].map(e => e.getBoundingClientRect()).filter(r => r.width * r.height > 0 && r.width * r.height < 0.8 * W * H).map(r => [r.top - R.top, r.bottom - R.top]).sort((a, b) => a[0] - b[0])
+  let cursor = 0, gap = 0
+  for (const [t, b] of spans) { gap = Math.max(gap, t - cursor); cursor = Math.max(cursor, b) }
+  gap = Math.max(gap, H - cursor)
+  if (gap > 0.25 * H) warnings.push('empty band ' + Math.round(gap) + 'px (' + Math.round(100 * gap / H) + '% of height): rebalance the layout')
+  return { errors, warnings }
+}
+if (!GRID) document.fonts.ready.then(() => {
+  document.getElementById('report').textContent = JSON.stringify([...stage.children].map(box => { try { return measure(box.firstElementChild) } catch (e) { return { errors: ['render failed: ' + e.message], warnings: [] } } }))
+})
+`
+
+const pages = pack.pages.map((page, i) => ({ n: i + 1, role: page.role, json: page.layout?.studioJson, ...(page.layout?.canvas ?? { width: 1080, height: 1350 }) })).filter(p => p.json)
+for (const page of pack.pages) if (!page.layout?.studioJson) console.log(`page ${pack.pages.indexOf(page) + 1}: no layout.studioJson (catalog page) — skipped`)
+const COLS = 4
+const html = `<!doctype html><meta charset="utf-8"><link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=block">
+<style>${themeCss}</style><div id="stage"></div><pre id="report"></pre>
+<script>const SOURCES = ${JSON.stringify(pages).replace(/</g, '\\u003c')}, COLS = ${COLS};${pageScript}</script>`
+const file = join(outDir, 'pages.html')
+writeFileSync(file, html)
+const W = Math.max(...pages.map(p => p.width)), Hs = pages.map(p => p.height)
+const base = ['--headless=new', '--disable-gpu', '--hide-scrollbars', '--virtual-time-budget=5000']
+// Measure at full size (all pages stacked, so every page is inside the viewport).
+const dom = execFileSync(chrome, [...base, `--window-size=${W},${Hs.reduce((a, b) => a + b, 0)}`, '--dump-dom', pathToFileURL(file).href], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 << 20 })
+// One contact sheet at 50% for the visual review.
+const rows = Math.ceil(pages.length / COLS)
+execFileSync(chrome, [...base, `--window-size=${Math.min(COLS, pages.length) * (W / 2 + 16) + 16},${rows * (Math.max(...Hs) / 2 + 16) + 16}`, `--screenshot=${join(outDir, 'grid.png')}`, pathToFileURL(file).href + '#grid'], { stdio: 'ignore' })
+const raw = dom.match(/<pre id="report">([\s\S]*?)<\/pre>/)?.[1]?.replace(/&quot;/g, '"').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&')
+const reports = raw ? JSON.parse(raw) : pages.map(() => ({ errors: ['no report (page script did not finish)'], warnings: [] }))
+let failed = false
+for (const [i, page] of pages.entries()) {
+  const report = reports[i]
+  if (report.errors.length) failed = true
+  console.log(`page ${page.n} (${page.role}): ${report.errors.length ? 'FAIL' : 'ok'}`)
+  for (const e of report.errors) console.log(`  ERROR ${e}`)
+  for (const w of report.warnings) console.log(`  warn  ${w}`)
+}
+console.log(`contact sheet: ${join(outDir, 'grid.png')} — look at it before creating the Run.`)
+process.exit(failed ? 1 : 0)

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

@@ -1,45 +1,14 @@
 # Create Run
 
-1. Write one arc line (`references/ARC.md`). Forbidden default:
-   Cover → Point → Steps → Recap → CTA.
-2. Prefer a Content Engine `pack.md` that already has **Page Contracts**,
-   **Media**, and **Template Selection** filled. If contracts are missing,
-   stop and hand back to **easysociable-content** — do not invent page
-   purposes from catalog family names.
-3. Build `content-pack.v1` from that argument. Page count follows the beats
-   (TikTok often 4–8), not the number of P0 families. Each page carries an
-   explicit `layoutFamilyId` (explicit — server must not silent-replace):
-   Formula handoff with a Look → `look.slides[slideNumber] ?? look.layouts[beat.role]`; else the pack's
-   Template Selection. One Run covers every platform the families support.
-4. Check platform hardMin/hardMax.
-5. No Look and no Template Selection → shortlist with
-   `easysociable slideshows recommend --file contracts.json --seed <slug> --json`
-   (MCP `recommend_slideshow_templates`). Input is the Page Contracts:
-   `{ platform, pages: [{ role, density?, slotSummary?: { text, number, image }, requiresImage? }] }`.
-   Pick one candidate `familyId` per page and record the reason; `supportedRoles` is a
-   weak tag. `pages[0]` must be cover/hook class. Do not use that class on
-   later pages. W- judgments (`fits` / `avoid`) with comparable evidence may
-   override the recommender's order. Surface `gaps` to the user.
-6. If `contentSlug` already has a Run: update only when topology matches
-   (same page count and Layout Families). Otherwise create a new Run.
-7. **Before** `create_run` / `slideshows create` (every create except
-   Formula handoff Runs): 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.
-7b. **Identity chain (ADR-0036):** confirm CLI auth is the user's Dashboard
-    Workspace API key (not `workspace_local` / `test-key`). If needed run
-    `easysociable auth login` (browser approval; `--api-key <key>` only when
-    headless). Refuse create on fixture
-    identity unless the user asked for `--allow-local-fixture`.
-8. Call `create_run` / `slideshows create` through Gateway with the explicit
-   `layoutFamilyId`s from the pack. `LAYOUT_FAMILY_NOT_FOUND` → the family has
-   no template for this platform; tell the user, do not guess.
-9. Save `runId`, `studioUrl`, and `status=draft`. Tell the user to open
-   `studioUrl` **while logged into the same Studio account**.
-10. Do not call a Deck API, create a carousel template, or send a product
-    `pageSequence` / `arc` field.
+Follow the Workflow in `SKILL.md` (login → Brand → facts → hook/structure →
+look + pages from references → images → `scripts/check-pages.mjs` → create).
+
+Notes for updates:
+
+- Revise the same Run (SKILL.md step 8): `slideshows get`, then `slideshows
+  update` with `baseRevision` and only the changed `pages[]` (`pageIndex`,
+  `layout`, `slots`). Page count and order stay fixed; a new Run only for a
+  new topic or an alternative the user asked for.
+- Save `runId` and `studioUrl`; the user opens `studioUrl` while logged into
+  the same account.
+- Do not call a Deck API or send a product `pageSequence` / `arc` field.

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

@@ -5,9 +5,7 @@ Fallback commands use the same Gateway client:
 
 ```bash
 easysociable slideshows create --file ./pack.json --json
-easysociable slideshows render --id run_xxx --idempotency-key run_xxx-final-1 --json
-easysociable renders wait --id job_xxx --json
-easysociable renders export --id job_xxx --output ./exports/run_xxx/tiktok --json
+easysociable slideshows get --id run_xxx --json
 ```
 
 Neither path may call a private service, Local API, Directus, R2 or a separate

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

@@ -1,7 +1,7 @@
 # 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.
+- Product-level `arc` / Deck `pageSequence` SKUs. 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).

package/skills/easysociable-template/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: easysociable-template
 description: >
-  Create single-page social image templates for EasySociable via the unified
-  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
+  Internal tool (opt-in install): turn a real post's page (reference image) or a
+  text brief into a single-canvas reference design for the slideshow skill's
+  reference library, then bind it to a Formula Look. One canvas only (the
+  source post's size, e.g. TikTok 9:16); no multi-platform variants. Use when the
+  maintainer wants to author a reference 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
@@ -21,7 +21,7 @@ server. Do not install or invoke `easysociable-template`, `easysociable-slidesho
 
 **This skill owns template authoring:**
 
-1. **Author** templates as a **Layout Family** (master + multi-platform variants) → Studio + Publish (`workflows/MULTI_PLATFORM_FAMILY.md`).
+1. **Author** reference designs: **one canvas**, the source post's size → Studio + Publish, then bind to a Formula Look (`workflows/BIND_FORMULA_LOOK.md`). Other platforms are re-laid out by the slideshow agent at generation time, so never derive variants.
 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. It is **not** a multi-slide slideshow compositor and it is **not** a PNG API.
@@ -41,9 +41,9 @@ 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}`). **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.
+5. After `create` / `createDraft`, the primary authoring path is `authoringStudioUrl` (`/authoring/{draftId}`). One canvas only (never `families derive`). 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. Each family variant carries its own `platforms` / `canvasPreset` / `canvas`.
+7. **Do not Publish without complete P0 selection metadata** (`CATALOG_METADATA.md`). Gateway enforces this. What the slideshow agent filters on must be right: `supportedRoles`, `contentArchetypes`, `requiresImage`, `visualStyle`, `bestFor`.
 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.
@@ -76,12 +76,12 @@ easysociable auth status --json
 
 | User intent | Workflow |
 |---|---|
-| 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` |
+| Text description → reference | `DESIGN_BRIEF.md` → … → `AUTHORING_STUDIO.md` → publish |
+| Reference image (a real post's page) → reference | `AUTHORING_FROM_IMAGE.md` → … → `AUTHORING_STUDIO.md` (reference-compare QA) → publish |
+| A viral post → its Formula's Look | each page via `AUTHORING_FROM_IMAGE.md` → publish → **`BIND_FORMULA_LOOK.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` (+ family derive if variants still missing) |
+| Already have authoring payload / continue Studio | `workflows/AUTHORING_STUDIO.md` |
 | 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` |
@@ -89,14 +89,14 @@ easysociable auth status --json
 
 ## Core model
 
-- `workflows/MULTI_PLATFORM_FAMILY.md` — **default** multi-platform create (Family + derive + hand-tune)
+- `workflows/BIND_FORMULA_LOOK.md` — published references → a Formula's Look (role → design)
 - `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` — Family `preview_tokens` (no TemplateTheme)
 - `references/EXTERNAL_RESOURCES.md`
-- `references/GATEWAY.md` — CLI / MCP including families derive + `render`
+- `references/GATEWAY.md` — CLI / MCP
 - `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,7 +5,7 @@ Private AST/bindings stay server-side; this document is the **public selection c
 
 ## Design choices (locked)
 
-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).
+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.
 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.
@@ -99,7 +99,7 @@ hero | screenshot | avatar | product
 
 | Field | Type | Notes |
 |---|---|---|
-| `name` | string | Human title — **layout**, not beat (e.g. `P0 Poster TikTok`, not `P0 Cover TikTok`) |
+| `name` | string | Public card title: what the layout is + style, then the ratio (e.g. `Five-Step How-To List — Quiet Ledger 9:16`). No internal prefixes (`P0`), no single platform name — the family spans platforms; the ratio suffix is stripped on cards. Keep equal to the page `name` |
 | `shortDescription` | string | One sentence for chooser UI |
 | `platforms` | `Platform[]` | Multi-select; use `generic` when truly cross-platform |
 | `canvasPreset` | preset enum | Plus exact `canvas` pixels |

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

@@ -12,15 +12,13 @@ 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 --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`.
+One canvas per reference; binding to a Formula: `workflows/BIND_FORMULA_LOOK.md`.
 
 All requests go through Gateway. The client receives public summaries, slot
 contracts, stable Image references and render Manifests only. It never receives

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

@@ -120,20 +120,18 @@ No platform chrome assumptions. Still pick a concrete preset (`1:1`, `4:5`, `3:4
 
 ---
 
-## Layout Family (multi-platform create)
+## One canvas per reference
 
-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.
+A reference design has exactly one canvas: the source post's (a TikTok post → `9:16`).
+Never derive other presets; the slideshow agent re-lays a reference out for the
+Run's platform.
 
 ## Selection rules for Agents
 
-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`).  
+1. Canvas = the source post's platform **Recommended** row (text brief with no post → TikTok 9:16).  
+2. One canvas only; no `families derive`.  
 3. Never mix presets across slides of one deck without an explicit user choice (IG/Threads/TikTok crop to first slide).  
-4. Each family variant’s P0 `selectionMetadata` must list only platforms that match that page’s `canvasPreset`.  
+4. P0 `selectionMetadata` lists only platforms that match the 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/workflows/AUTHORING_FROM_BRIEF.md

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

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

@@ -79,7 +79,7 @@ If unsure whether a region is “illustration” vs “icon”: prefer **image s
 9. Propose Theme reuse or `ThemeTokens` create from `theme-tokens.json` (`references/THEME_TOKENS.md`).
 10. Show the user: geometry summary, **image inventory → slot map**, selection metadata, Theme. Call out any region you could not match and why. Proceed when they accept.
 11. Run `scripts/validate-authoring-source.mjs <authoring-source.json>` and fix every error.
-12. Continue with `workflows/AUTHORING_STUDIO.md` (`source.kind = image_reference`, brief = path or short note) → **`MULTI_PLATFORM_FAMILY.md`** (derive + hand-tune other presets). Run Visual QA **including reference compare on the master** before handoff; still QA each derived variant for fit/clipping.
+12. Continue with `workflows/AUTHORING_STUDIO.md` (`source.kind = image_reference`, brief = path or short note) Run Visual QA **including reference compare** before handoff. One canvas only; after publish, bind it with `BIND_FORMULA_LOOK.md` when it comes from a Formula's post.
 
 ## Limits (state upfront when relevant)
 

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

@@ -18,11 +18,11 @@ Complete intake first:
 ## Layout Family (multi-platform)
 
 New drafts create a **Layout Family** (`familyId`) plus a master canvas page.
-**Default create path:** after the master draft exists, follow `MULTI_PLATFORM_FAMILY.md` (derive + hand-tune variants) before handoff unless the user asked for one platform only.
+One canvas per reference: never derive platform variants.
 
 - Authoring URL: `/authoring/{draftId}?platform=…`. Top bar **platform chips** switch variants (do not resize one AST).
 - Preview skin = Family `preview_tokens` from `theme.create`; fill/render uses Brand snapshot first (ADR-0033).
-- Legacy drafts without `familyId` auto-wrap on `getDraft` / `listDrafts`. Bulk: `easysociable templates families migrate-legacy --json`.
+- Legacy drafts without `familyId` auto-wrap on `getDraft` / `listDrafts`.
 
 ## Flow
 
@@ -47,9 +47,9 @@ AST or Binding Maps.
 
 3. Read `data.id` / `data.templateId` / `data.familyId` / `data.authoringStudioUrl` (and `data.variants` when present).
 
-4. **Multi-platform (default):** run `workflows/MULTI_PLATFORM_FAMILY.md` — derive target presets, hand-tune each variant, QA each canvas. Skip only when the user asked for a single platform.
+4. One canvas only: do not run `families derive`.
 
-5. **Before handoff, run `workflows/VISUAL_QA.md`** on the master (and each variant from step 4). Open the actual Studio render; inspect screenshots, not only source. When a draft fails, fix authoring JSON, validate, update that page id, and re-render:
+5. **Before handoff, run `workflows/VISUAL_QA.md`** on the page. Open the actual Studio render; inspect screenshots, not only source. When a draft fails, fix authoring JSON, validate, update that page id, and re-render:
 
 ```bash
 node scripts/validate-authoring-source.mjs ./authoring-source.json

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

@@ -0,0 +1,39 @@
+# Bind references to a Formula Look
+
+A Formula is the structure distilled from a real viral post; its **Look** says
+which reference design each slide uses. The slideshow skill reads it
+(`look.slides["<n>"]`, else `look.layouts[<role>]`) whenever that Formula is used.
+
+## When
+
+After publishing the references for a post's pages (one reference per distinct
+page layout, via `AUTHORING_FROM_IMAGE.md`).
+
+## Steps
+
+1. `easysociable formulas get --id <F-…> --json` — note its `beats` (slide order
+   and roles) and existing `looks`.
+2. Map each beat to a published design's `familyId`
+   (`easysociable templates list --canvas 9:16 --json` shows `familyId`):
+   - `layouts`: one design per role (`hook`, `point`, `cta`, …);
+   - `slides`: only for a slide whose design differs from its role's default
+     (1-based slide number → `familyId`).
+3. Write the Look:
+
+   ```json
+   { "id": "L-<short-name>",
+     "ref": { "platform": "tiktok", "platform_post_id": "<the post's id>" },
+     "layouts": { "hook": "fam_…", "point": "fam_…", "cta": "fam_…" },
+     "slides": { "2": "fam_…" } }
+   ```
+
+4. There is no public write API for Formulas: hand the JSON to the maintainer
+   to append to that Formula's `looks` in the Directus admin (a new Look goes
+   last, so the Formula's default Look — the first — does not change unless
+   they choose to reorder).
+5. Check: `easysociable formulas get --id <F-…> --json` shows the Look, and
+   every `familyId` in it resolves with
+   `easysociable templates source --family <familyId> --json`.
+
+Never bind an agent-authored design that was not made from a real post: the
+reference library only holds proven designs.

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

@@ -16,7 +16,7 @@ Skip this workflow when `AUTHORING_FROM_IMAGE.md` applies and a reference image
 
 ### 1. Gather intent (batch questions; skip known answers)
 
-- **Master** platform + canvas from `references/PLATFORM_SPECS.md`, plus default multi-platform derive targets (`MULTI_PLATFORM_FAMILY.md`) unless the user wants one platform only
+- Platform + canvas from `references/PLATFORM_SPECS.md` (one canvas: the source post's)
 - Page roles (1–2) + contentFamily / archetypes / density (`CATALOG_METADATA.md`)
 - Content job: what must the viewer understand in one glance?
 - Must-have slots: title / metric / image / CTA / fixed N checklist lines…
@@ -31,8 +31,7 @@ Use this structure (Chinese or English to match the user):
 
 ## 1. Job to be done
 - One-sentence purpose of this page
-- Master platform + canvas (preset + pixels) — cite PLATFORM_SPECS recommended row
-- Multi-platform targets (default vertical bucket unless user limited) — `MULTI_PLATFORM_FAMILY.md`
+- Platform + canvas (preset + pixels) — cite PLATFORM_SPECS recommended row
 
 ## 2. Visual constraints
 - Desired/forbidden moods or brand rules