@easysociable/cli 0.1.12 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easysociable/cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Agent-first CLI for EasySociable: Content Engine, Template, Slideshow, and MCP",
   "type": "module",
   "license": "MIT",
@@ -16,12 +16,26 @@
   },
   "keywords": [
     "easysociable",
-    "cli",
     "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "cursor",
+    "carousel",
+    "social-carousel",
+    "slideshow",
+    "slideshow-generator",
     "social-media",
+    "tiktok",
+    "linkedin",
+    "instagram",
+    "threads",
+    "xiaohongshu",
     "templates",
-    "slideshow",
-    "agent"
+    "agent",
+    "content-engine",
+    "cli"
   ],
   "engines": {
     "node": ">=20.0.0"
@@ -37,13 +51,6 @@
     "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/"
@@ -52,13 +59,19 @@
     "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",
     "tsup": "^8.0.2",
     "typescript": "^5.8.3",
-    "vitest": "^1.3.1"
+    "vitest": "^1.3.1",
+    "@easysociable/mcp-server": "0.0.0",
+    "@easysociable/template-gateway-client": "0.0.0",
+    "@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"
   }
-}
+}

package/scripts/engine/contracts.mjs

@@ -23,7 +23,7 @@ export const PLATFORM_CAPS = {
 const FORBIDDEN_PACK_KEYS = ['deck_template_id', 'deckTemplateId']
 
 const PACK_KEYS = new Set(['schemaVersion', 'platform', 'title', 'pages'])
-const PAGE_KEYS = new Set(['pageTemplateId', 'role', 'slots'])
+const PAGE_KEYS = new Set(['layoutFamilyId', 'pageTemplateId', 'role', 'slots'])
 export const RUN_FILE_STATUSES = [
   'RUN_OPEN', 'BRIEF_WAIT', 'DRAFTED', 'EDIT_WAIT', 'SCORED',
   'READY_TO_POST', 'PUBLISHED', 'HOLD', 'KILLED', 'SUPERSEDED',
@@ -97,8 +97,9 @@ export function validateContentPack(pack, options = {}) {
     }
     pushUnknownKeys(errors, page, PAGE_KEYS, label)
     if (!PAGE_ROLES.includes(page.role)) errors.push(`${label}.role: invalid page role`)
-    if (typeof page.pageTemplateId !== 'string' || page.pageTemplateId.length === 0) {
-      errors.push(`${label}.pageTemplateId: required and must be a non-empty string`)
+    const layoutRef = page.layoutFamilyId ?? page.pageTemplateId
+    if (typeof layoutRef !== 'string' || layoutRef.length === 0) {
+      errors.push(`${label}.layoutFamilyId: required (or pageTemplateId) and must be a non-empty string`)
     }
     if (!isRecord(page.slots)) {
       errors.push(`${label}.slots: must be an object`)

package/skills/ONBOARDING.md

@@ -51,17 +51,13 @@ V1 expects an Agent (Grok Bot, Codex, Claude Code, …) to drive setup. The webs
 ## Lazy auth (Agent script)
 
 When a Gateway call returns `AUTH_REQUIRED`, `API_KEY_INVALID`, or the CLI says
-`Run easysociable auth login`, respond with:
+`Run easysociable auth login`, run `easysociable auth login` yourself (it waits
+up to 5 minutes for the browser approval) and tell the user:
 
 ```text
-EasySociable needs a workspace API key before it can create Brands, images, drafts or Slideshow Runs on the Gateway.
-
-1. Open https://my.easysociable.com/auth/signup (or sign in with Google).
-2. Verify your email if you used password signup (required before API keys).
-3. Dashboard → API Keys → Create API key → copy the secret once.
-4. Run: easysociable auth login --api-key <paste-key> --gateway-url https://gateway.easysociable.com
-
-Tell me when that is done and I will continue.
+EasySociable needs to connect to your account. I'm running `easysociable auth login` —
+a browser tab will open: sign in (Google works, free) and click "Authorize Agent".
+I'll continue as soon as you approve.
 ```
 
 After `auth login` succeeds, retry the failed operation with the same

package/skills/easysociable-content/SKILL.md

@@ -1,21 +1,20 @@
 ---
 name: easysociable-content
 description: >
-  Operate the EasySociable Content Engine (profile, needs, products, recommendations, topics, runs, workbench).
+  Operate the EasySociable Content Engine: Knowledge (Karpathy LLM Wiki), hook-led
+  Topics, formula-led Runs, profile, brand, media, workbench.
   Triggers: 采访我, 完善人设, interview me, who am I as a creator, 建立 profile
   — follow workflows/INTERVIEW.md (engine CLAUDE.md § Interview wins if present).
-  Triggers: 记需求, 扫需求选题, 扫关键词, 路由 Hit, capture audience quotes, user needs, 调研需求, 需求落库
-  — follow workflows/NEEDS.md + engine CLAUDE.md § Keywords / § Hits / § Needs.
-  Triggers: 更新产品, 产品库, product facts, product pricing, product offer
-  — follow the engine CLAUDE.md § Products and edit `products/`.
-  Triggers: 推荐产品, 评测工具, compare tools, review an AI product
-  — edit `recommendations/`; do not treat third-party subjects as owned Products.
-  Triggers: 做成选题, 开一单, 出图
-  — follow engine CLAUDE.md (§ Topics / § Open a run / § PagePack: Page Contracts → Media → Template Selection before templates).
+  Triggers: 记一下, 存资料, ingest, 问知识库, what do we know about, lint 知识库, 整理知识
+  — follow engine CLAUDE.md § Knowledge (Ingest / Query / Lint).
+  Triggers: 列出 hooks, 选 hook, 用 H-… 生成选题, 做成选题
+  — follow engine CLAUDE.md § Topics (Hook → Formula → Knowledge).
+  Triggers: 开一单, 用 T-… 开一单, 出图
+  — follow engine CLAUDE.md § Open a run (content straight from the Topic's Formula).
   If no engine exists, copy/clone the Content Engine core (see Create below;
   `easysociable engine init` is optional offline scaffold). Then follow
   Content Engine/CLAUDE.md. Render handoff: easysociable-template (1 page) or
-  easysociable-slideshow (2+). Never publish or post.
+  easysociable-slideshow (2+, Formula handoff). Never publish or post.
 ---
 
 # EasySociable Content
@@ -24,62 +23,33 @@ Entry card for agents. **Do not invent a parallel workflow.** Instance SoT is th
 
 ## Product boundary
 
-- Teach a **Content Engine** (signal → decision → draft → review → reusable learning).
-- **EasySociable** is the **visual production layer** inside that engine — not the content brain, not the whole system.
-- For `easysociable-builder` needs research, prefer **L1 system / L2 judgment-review** pains (sustainable publishing) over **L3 visual-tool** friction, unless the user asks for L3.
+- Teach a **Content Engine**: knowledge you own → a hook-led decision → formula-led content → feedback that updates knowledge.
+- **EasySociable** supplies the **Hooks / Formulas catalog** and the **visual production layer** (Studio). It is not the content brain.
 
-## Pipeline (do not collapse stages)
+## Three loops (do not collapse)
 
 ```text
-Profile / Audience
-  → Needs (verbatim audience quotes)
-  → optional Product (owned offer facts) or Recommendation (third-party review subject)
-  → Pillar (what this profile discusses) + Lane (how it publishes)
-  → Topic (decision summary + readable judgment + Score appendix)
-  → Run → Pack → Publish / feedback
+Knowledge   raw/ (immutable) → knowledge/pages (agent-maintained wiki) → index.md + log.md
+Topics      Hook (H-…) → one of its Formulas (F-…) → angle from knowledge pages → T-…
+Runs        Topic's Formula beats → content.md + content-pack.v1 → Studio → feedback
 ```
 
 | Stage | Owns | Does not |
 |-------|------|----------|
-| Needs `N-` | Verbatim reader/operator quotes | Watchlist hooks, Agent rewrites |
-| Products `P-` | Owned offer facts, pricing, boundaries | Audience demand or third-party reviews |
-| Recommendations `R-` | Third-party subject, evidence, limits, disclosure | Owned product claims |
-| Pillars / lanes | Durable subject / publishing mode | A replacement for Needs or evidence |
-| Topic `T-` | Human judgment card + opp gate | Being auto-created from heat |
-| Workbench | Read-only observatory | Source of truth (markdown indexes are) |
+| `raw/` | Verbatim sources + URL | Ever get edited after save |
+| `knowledge/pages` | `source` / `concept` / `entity` / `synthesis` pages with `[[links]]` | Viral-post teardowns; facts no raw source supports |
+| Topic `T-` | `hook_id` + `formula_id` + `knowledge_ids` + Beat plan | Exist without a hook and a formula |
+| Run | One platform; one page per formula beat | Re-pick hook/formula; idea → brief → packet → draft → editor → rubric chain |
+| Workbench | Read-only observatory (Knowledge graph, Topics, Runs) | Source of truth (markdown is) |
 
 ## Hard rules
 
-1. **No invented quotes** — Needs quote cell = verbatim only. Gloss is separate (`layer=L1|L2|L3` allowed in gloss).
-2. **Heat ≠ topic** — External source metrics never make `ready`.
-3. **Never invent `N-` from a product, vendor claim, or headline.** Match captured needs only.
-4. **Topic decision card first** — start with Verdict / Why this status / Who it’s for / Core judgment / Next step, then explain the problem, current belief, angle, timing, expected belief change, evidence gap, and recommended form. **Language:** readable judgment + `one_liner` = profile `voice.md` Language (else pillars / `engine.json` locale); verbatim Needs stay untranslated. Keep scores and IDs in the appendix. Chat output is the readable decision card, not a score walkthrough.
-5. **`N-` never in `capture_id`** — needs go in `need_ids` only.
-6. **Rebuild workbench** after markdown writes in the engine vault.
-7. **Keep ownership explicit** — `products/` is for offers we own or provide;
-   `recommendations/` is for third-party tools and products. A Topic may cite
-   `product_ids`, `recommendation_ids`, both, or neither.
-8. **Ask for Topic `generation_mode` before any `produce` write** — present the
-   six modes; recommend `demand` when Need-led; do not silently assume.
-   Product/recommendation inputs do not prove audience demand.
-9. **Scan stages Hits, not Needs/Topics** — default keyword scan is
-   `track=listen` only → `hits/` (`triage`); route to `needs/` or library
-   only after confirm. `search` = SEO, `ask` = GEO questions — not default
-   social scan. Hits are never Topic inputs.
-10. **Generate keywords from evidence** — propose listen/search/ask candidates
-    from Needs/audience in chat; write `keywords.md` only after confirm;
-    set `seed_from`. Google volume never gates listen.
-
-Topic modes (ask before `produce`; recommend `demand` when Need-led):
-
-```text
-demand             = Needs + Profile
-demand_to_offer    = Needs + Product + Profile
-demand_to_review   = Needs + Recommendation + Profile
-review             = Recommendation + evidence + Profile
-offer_education    = Product + mechanism + Profile
-profile_thesis     = Profile + Pillar
-```
+1. **No invented facts or quotes** — slot text and Beat plans come from knowledge pages only; gaps go in **Do not claim**.
+2. **No hook → no topic.** Never invent `H-` / `F-` ids; read them from `easysociable hooks list` / `formulas get`.
+3. **Knowledge is compiled, not re-derived** — ingest updates every touched page, records contradictions instead of overwriting, regenerates `knowledge/index.md`, appends `knowledge/log.md`.
+4. **Runs follow the Formula** — same beat count, order and roles; `layoutFamilyId = look.slides[n] ?? look.layouts[role]`.
+5. **Rebuild workbench** after markdown writes in the engine vault (`python3 workbench/build.py`); after knowledge writes also `python3 scripts/lint-knowledge.py --engine .`.
+6. Hook link for the user: `https://easysociable.com/hooks/<hook_id>`.
 
 ## Create / serve / build
 
@@ -102,56 +72,39 @@ repo into `<parent>/Content Engine` (never overwrites an existing engine).
 ```bash
 easysociable engine serve --engine <parent>/Content Engine --no-open
 easysociable engine build --engine <parent>/Content Engine
-# --sync-workbench refreshes workbench files from the public core checkout
 ```
 
-On a dedicated agent computer (e.g. Grok Bot), prefer `/workspace` + clone or
-`engine init`. Mixed→split vault: see `scripts/migrate-split-vault.py` in the
-public repo.
-
-`python3` is required for the workbench. Observatory: `http://127.0.0.1:8765/workbench/` — top tabs include **需求库 / Needs**. If `serve.py` is already up, do not start a second server; rebuild only.
-
-Engine methodology updates: `git pull` on the core (or `--sync-workbench`), not
-CLI republishes.
+`python3` is required for the workbench. Observatory: `http://127.0.0.1:8765/workbench/` — tabs **Knowledge** (graph) / Topics / Runs. If `serve.py` is already up, do not start a second server; rebuild only.
 
 ## Operate
 
 1. Resolve account → profile (engine `CLAUDE.md`).
 2. Route by intent (table below). Prefer engine `CLAUDE.md` sections; use `workflows/*` when that file is newer or the § is missing.
-3. Always return the structured chat card the section defines.
+3. Always return a short result card in chat.
 4. Rebuild workbench after writes.
 
 | Intent | Action |
 |--------|--------|
 | 采访我 / interview me / 完善人设 / 建立 profile | **workflows/INTERVIEW.md** (not a render) |
-| 记需求 / 用户原话 / capture audience quotes / 调研需求 / 需求落库 | **workflows/NEEDS.md** (not a render) |
-| 加关键词 / 生成 listen\|search\|ask 词 / 扫关键词 / 路由 Hit | Engine **§ Keywords** + **§ Hits** — three-track recipes; scan listen→Hits |
-| 更新产品 / 产品库 / product facts | Engine **§ Products** — update owned offer facts and dated pricing |
-| 推荐产品 / 评测工具 / compare or review | `recommendations/` — collect evidence and disclosure before Topic |
-| 扫需求选题 | **NEEDS.md** then Topics from `needs/` `status=captured` — **ask `generation_mode` first** |
-| 做成选题 / 生成 topic | engine **§ Topics** — explicit input; **ask `generation_mode` before write** |
-| 开一单 / 用 T-… 开一单 | engine **§ Open a run** (ask platform; multi → N runs) |
-| 1 page / `media_mode=single_visual` | **easysociable-template** (after hard gate) |
-| 2+ pages / `media_mode=multi_page_pack` (any platform, incl. X + `pack_hook`) | **easysociable-slideshow** (after hard gate + **ADR-0036 identity chain**: Studio login → API key → `easysociable auth login` → create) |
-| X / xiaohongshu text-only | No render skill — ship copy from the Run |
+| 记一下 / 存资料 / ingest + link or file | Engine **§ Knowledge · Ingest** |
+| 问知识库 / what do we know about X | Engine **§ Knowledge · Query** (offer to file back as `synthesis`) |
+| lint 知识库 / 整理知识 | Engine **§ Knowledge · Lint** |
+| 列出 hooks / 选 hook / 用 H-… 生成选题 | Engine **§ Topics** |
+| 开一单 / 用 T-… 开一单 | Hard gate → engine **§ Open a run** (ask platform; multi → N runs) |
+| 1 page | **easysociable-template** with `Formula: <id>` (after hard gate) |
+| 2+ pages (any platform) | **easysociable-slideshow** *Formula handoff* (after hard gate + **ADR-0036 identity chain**: Studio login → API key → `easysociable auth login` → create) |
+| X / xiaohongshu text-only | No render skill — ship copy from `content.md` |
 
 ## Render hard gate
 
-**Before any template/slideshow call:** Identity in `profiles/<active>/voice.md` — Role / What I build / Point of view — no `(fill)` and non-empty; `boundaries.md` exists with Not covering and Never claim both non-empty. If `needs/` exists, `needs/_index.md` ≥ **3** `N-` rows; if `needs/` is absent, skip that count. Public handle MAY stay `(fill)`.
+**Before any template/slideshow call:** Identity in `profiles/<active>/voice.md` — Role / What I build / Point of view — no `(fill)` and non-empty; `boundaries.md` exists with Not covering and Never claim both non-empty. Public handle MAY stay `(fill)`.
 
 On fail: **stay in this skill**. List missing files. Do not call template or slideshow. User must say **强制继续** / **force continue** to proceed.
 
 ```bash
-easysociable engine validate --run <run-dir> --require-pack --require-knowledge
+easysociable engine validate --root <engine> --require-knowledge
 ```
 
-Slideshow packs need an **Arc** line, then **Page Contracts** (no `templateId`), then Media, then Template Selection. Do not default Cover → Point → Steps → Recap → CTA. Page 1 is cover/hook class; later pages are not. Handoff: **easysociable-slideshow** (`references/ARC.md`). Validate with `python3 scripts/validate-pack.py`.
-
-## Research (Needs)
-
-- Prefer host research tools. On **X**: built-in `x_*` first; fall back to agent-reach / `twitter` only if insufficient.
-- Store **commenter** words when scraping threads. Do not invent `N-` when a platform tool is missing—stop and ask for paste.
-
 ## Out of scope
 
 No social posting, Content MCP, Local API, or SQLite content library.

package/skills/easysociable-content/workflows/INTERVIEW.md

@@ -2,7 +2,7 @@
 
 Not a fourth skill. If the engine `CLAUDE.md` already has **§ Interview**, follow that section. Otherwise follow this file.
 
-Do **not** ingest needs / quotes here. Do **not** scan the watchlist. Do **not** create a slideshow or call template/slideshow.
+Do **not** ingest sources into Knowledge here. Do **not** create a slideshow or call template/slideshow.
 
 ## Triggers
 
@@ -59,9 +59,9 @@ Do **not** ingest needs / quotes here. Do **not** scan the watchlist. Do **not**
 
 | Level | Condition | Behavior |
 |-------|-----------|----------|
-| **Hard gate** (refuse slideshow handoff / `create_run`) | Identity **only** Role / What I build / Point of view have no `(fill)` and are non-empty (Public handle and Not claiming MAY stay `(fill)` / starter copy) **and** `boundaries.md` exists with Not covering **and** Never claim both non-empty. If `needs/` exists, also `needs/_index.md` ≥ 3 `N-` rows; if `needs/` is absent, skip that count. | Refuse 出图 / PagePack handoff / `slideshows create`. List missing files. User must say **强制继续** / **force continue** to proceed. |
-| **First-session goal** | Hard gate **and** Persona has at least one personalized line **and** needs **target 5** (under 5 still passes the hard gate) **and** `stories.md` may be 0–1 | Open card `profile: partial`. May 扫需求选题. Still no graphics unless forced. |
-| **Complete seven dimensions** | Identity + Experience (≥2) + Values (≥3) + Persona/Do not say + `stories.md` ≥1 + `boundaries.md` + `expression.md` likes/dislikes ≥3 each + needs ≥5 | Open card `profile: complete`. Remaining gaps are draft reminders only — **not** a hard-stop on graphics. |
+| **Hard gate** (refuse slideshow handoff / `create_run`) | Identity **only** Role / What I build / Point of view have no `(fill)` and are non-empty (Public handle and Not claiming MAY stay `(fill)` / starter copy) **and** `boundaries.md` exists with Not covering **and** Never claim both non-empty. | Refuse 出图 / run handoff / `slideshows create`. List missing files. User must say **强制继续** / **force continue** to proceed. |
+| **First-session goal** | Hard gate **and** Persona has at least one personalized line **and** `stories.md` may be 0–1 | Open card `profile: partial`. May pick a hook and write Topics. Still no graphics unless forced. |
+| **Complete seven dimensions** | Identity + Experience (≥2) + Values (≥3) + Persona/Do not say + `stories.md` ≥1 + `boundaries.md` + `expression.md` likes/dislikes ≥3 each | Open card `profile: complete`. Remaining gaps are draft reminders only — **not** a hard-stop on graphics. |
 
 Experience / Values / expression are **not** the hard gate. Missing `stories.md` / `expression.md` = partial. Missing `boundaries.md` file = hard-gate fail.
 

package/skills/easysociable-slideshow/SKILL.md

@@ -3,9 +3,10 @@ name: easysociable-slideshow
 description: >
   Create, list, update and review durable multi-page Slideshow Runs for
   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
+  pick a Layout Family per page (one layout, adapted to every platform) by
+  role, slotSummary and density — never default Cover→Point→Steps→Recap→CTA.
+  A Formula with a Look already fixes each page's Layout Family. Page 1 must
+  be a cover or hook class family; those 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
@@ -14,7 +15,9 @@ description: >
 
 # EasySociable Slideshow Skill
 
-A Slideshow Run is a composition of explicit single-page Templates.
+A Slideshow Run is a composition of explicit Layout Families, one per page.
+A Layout Family is one layout whose templates differ only by platform canvas,
+so one Run yields the carousel for every platform (Studio switches variants).
 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.
 
@@ -23,12 +26,15 @@ Page order is the argument of **this pack**, not a catalog recipe.
 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. Choose a Brand (or Profile/Theme) and an explicit Page Template for every
-   page. The server never silently chooses or replaces a Page Template.
-   Prefer templates already chosen on the Content Engine pack (**Template
-   Selection** after **Page Contracts**). Otherwise get a shortlist from
+3. Choose a Brand (or Profile/Theme) and an explicit Layout Family for every
+   page, sent as `layoutFamilyId` in the pack (Gateway resolves it to the
+   family's template on the Run's native canvas; `pageTemplateId` is still
+   accepted). The server never silently chooses or replaces a layout.
+   Order of precedence: (a) a Formula **Look** (see Formula handoff),
+   (b) families already chosen on the Content Engine pack (**Template
+   Selection** after **Page Contracts**), (c) a shortlist from
    `easysociable slideshows recommend --file contracts.json --seed <slug>`
-   (MCP `recommend_slideshow_templates`) and pick one per page with a reason.
+   (MCP `recommend_slideshow_templates`) — pick one `familyId` per page with a reason.
    The recommender filters platform + native canvas + slotSummary + cover rule,
    demotes Layout Families used in the owner's recent Runs, and keeps one
    unused family per page. `role` / `supportedRoles` are weak retrieval tags,
@@ -41,8 +47,10 @@ Page order is the argument of **this pack**, not a catalog recipe.
    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.
+5. A Run has up to 8 pages on Free and 20 on paid, one native platform
+   (`tiktok`, `instagram`, `linkedin` or `threads`; it sets the page cap and
+   the canvas edited first) and one Brand across pages. Studio renders the
+   same Run for every platform its Layout Families support.
 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.
@@ -51,8 +59,8 @@ Page order is the argument of **this pack**, not a catalog recipe.
    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
+   the same Run only when page count, Layout Families, and intended sequence
+   still match. A different arc or family 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 /
@@ -62,13 +70,16 @@ Page order is the argument of **this pack**, not a catalog recipe.
     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.
+    to call Gateway. **Exempt:** Formula handoff Runs (prompt names
+    `Formula: F-…`) — the Formula supplies the arc and the user supplies the
+    topic, so a first-time user with no Content Engine is not blocked.
 8c. **Identity chain (ADR-0036, hard):** before create, the CLI must be
     logged in with the **user's Dashboard Workspace API key** (same account
     that will open Studio). Refuse fixture `workspace_local` / local
     `test-key` unless the user explicitly asked for a local fixture
-    (`--allow-local-fixture`). Order: Studio login → create API key →
-    `easysociable auth login --api-key <key>` → create Run → open
+    (`--allow-local-fixture`). Order: `easysociable auth login` (opens the
+    browser; the user approves once and the key is stored — use
+    `--api-key <key>` only when headless) → create Run → open
     `studioUrl` while logged in as that user. If Studio shows “belongs to
     another account”, recreate with the current key — do not invent
     cross-workspace access.
@@ -87,10 +98,10 @@ Page order is the argument of **this pack**, not a catalog recipe.
    `python3 scripts/validate-pack.py runs/<slug>/pack.md` (in the Content Engine).
    Refuse create if contracts are empty or contain `templateId`.
 3. Resolve or create the user's Brand through the unified CLI/MCP.
-4. Prefer pack **Template Selection** ids. Otherwise run
+4. Use the Formula Look's families, else pack **Template Selection**. Otherwise run
    `easysociable slideshows recommend --file contracts.json --seed <slug> --json`
-   and choose from each page's `candidates`; never place a cover/hook class
-   template after page 1. Report `gaps` (pages with < 2 role-matching
+   and choose a `familyId` from each page's `candidates`; never place a cover/hook class
+   family after page 1. Report `gaps` (pages with < 2 role-matching
    templates) to the user as authoring backlog. Record Layout Family evidence
    as `hypothesis` unless published comparable results support `tested` /
    `supported` — a template having been used before is not evidence.
@@ -108,7 +119,8 @@ Page order is the argument of **this pack**, not a catalog recipe.
    ```
 
    Fail → refuse; return to **easysociable-content**. **强制继续** / **force continue**
-   is the only override (conversational — not a CLI flag). Then:
+   is the only override (conversational — not a CLI flag). Formula handoff
+   Runs skip this knowledge check (rule 8b) but not the identity gate. Then:
 
    ```bash
    easysociable slideshows create --file ./pack.json --json
@@ -119,6 +131,29 @@ Page order is the argument of **this pack**, not a catalog recipe.
 9. After explicit user confirmation, tell them to click **Download** in Studio.
    Do not render or export from CLI/MCP.
 
+## Formula handoff (prompt names a `Formula: F-…` id)
+
+1. `easysociable formulas get --id <id> --json` (falls back to the hosted
+   catalog). Not found → tell the user; do not guess a structure.
+2. The formula's `beats` are the page order: one page per beat, same roles,
+   same count. Its `title_template` with `{X}` = the user's topic is the arc
+   line, so rule 10 is satisfied by the formula, not by P0 family names.
+3. Write each page's copy from `beat.fill` and the user's topic. Ask at most
+   one question when tip/point pages need facts the topic doesn't supply.
+   Never copy sentences from the formula's viral example posts.
+4. **Look = copy the layout.** If the prompt names `Look: L-…` (else use the
+   formula's first entry in `looks`), set each page's `layoutFamilyId` to
+   `look.slides["<1-based slide number>"]` if present, else
+   `look.layouts[beat.role]`. Do not run `slideshows recommend` for those
+   pages and ignore the "demote recently used families" preference — the
+   user asked for this layout. Only roles missing from the Look fall back to
+   the recommender. Copy layout only: colours and fonts come from the user's
+   Brand. If a Look family has image slots, ask the user for images (or say
+   which slots are empty) instead of delivering blank image slots.
+5. Turn beats into Page Contracts, then continue at Workflow step 3
+   (Brand → families → identity gate → create → Studio). The knowledge gate
+   (rule 8b) does not apply to Formula handoff Runs.
+
 ## Failure handling
 
 - If the knowledge hard gate fails, do not create the Run. Hand back to
@@ -128,6 +163,8 @@ Page order is the argument of **this pack**, not a catalog recipe.
   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.
+- `LAYOUT_FAMILY_NOT_FOUND`: the family has no template for the Run's
+  platform. Tell the user and pick another platform or family; do not guess.
 - 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

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

@@ -1,8 +1,11 @@
 # 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`,
+`layoutFamilyId` is the explicit Layout Family chosen by the Agent (from a
+Formula Look or the recommender's `familyId`); Gateway resolves it to that
+family's template on the pack platform's canvas, and Studio derives the other
+platforms from the same family. `pageTemplateId` (one exact template) is still
+accepted and wins when both are sent. `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.
@@ -21,10 +24,10 @@ Opening beat is cost; page 1 is still a hook-class template.
   "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" } }
+    { "role": "hook", "layoutFamilyId": "fam_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", "layoutFamilyId": "fam_stack_001", "slots": { "text_0": "Roles, Brand, Layouts persist" } },
+    { "role": "steps", "layoutFamilyId": "fam_stair_001", "slots": { "text_0": "Use them in that order" } },
+    { "role": "cta", "layoutFamilyId": "fam_close_001", "slots": { "text_0": "Don't brief a blank canvas" } }
   ]
 }
 ```
@@ -44,10 +47,10 @@ Opening beat is cost; page 1 is still a hook-class template.
 }
 ```
 
-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.
+Pick families by **slotSummary + density** (or take them from a Formula Look),
+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
+published Layout Family can be selected in a new Run without creating a
 carousel asset.

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

@@ -7,22 +7,23 @@
    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. Carry the chosen
-   `pageTemplateId`s from Template Selection (explicit — server must not
-   silent-replace).
+   (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 Template Selection on the pack → shortlist with
+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 per page and record the reason; `supportedRoles` is a
+   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 `pageTemplateId`s). Otherwise create a new Run.
-7. **Before** `create_run` / `slideshows create` (every create, not only the
-   first Run): check the knowledge hard gate — Identity Role / What I build /
+   (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
@@ -31,12 +32,13 @@
    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:
-    Studio login → Dashboard create key →
-    `easysociable auth login --api-key <key>`. Refuse create on fixture
+    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
-   template ids from the pack.
+   `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