@easysociable/cli 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easysociable/cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Agent-first CLI for EasySociable: Content Engine, Template, Slideshow, and MCP",
   "type": "module",
   "license": "MIT",
@@ -37,13 +37,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 +45,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/tsconfig": "0.0.0",
+    "@easysociable/template-gateway-client": "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/skills/ONBOARDING.md

@@ -11,28 +11,28 @@ V1 expects an Agent (Grok Bot, Codex, Claude Code, …) to drive setup. The webs
    # or: npm i -g @easysociable/cli
    ```
 
-2. **Create the Content Engine** (markdown + workbench)
+2. **Install Skills + MCP** (Template + Slideshow by default; for Codex / Claude Code)
 
    ```bash
-   easysociable engine init --root /workspace --yes
-   easysociable engine serve --engine /workspace/Content Engine --no-open
+   easysociable install --yes
    ```
 
-   On a laptop, use any parent path instead of `/workspace`.
+   Default skills:
 
-3. **Install hosted Skills + MCP** (Template + Slideshow by default; for Codex / Claude Code)
-
-   ```bash
-   easysociable install --yes
-   ```
+   - `easysociable-slideshow` — turns a draft into slideshow pages you preview and download in the dashboard
+   - `easysociable-template` — creates page templates
 
-   Optional pointer skill (discovery only — operations live in `Content Engine/CLAUDE.md`):
+   Optional Content Engine skill (pointer only — operations live in `Content Engine/CLAUDE.md`):
 
    ```bash
-   easysociable install --skills content --yes
+   easysociable install --skills content,template,slideshow --yes
+   easysociable engine init --root /workspace --yes
+   easysociable engine serve --engine /workspace/Content Engine --no-open
    ```
 
-4. **Ask the Agent to create graphics** — account creation is deferred until a hosted operation requires authentication.
+   On a laptop, use any parent path instead of `/workspace` for `engine init` / `serve`.
+
+3. **Ask the Agent to create graphics** — account creation is deferred until a hosted operation requires authentication. If you installed the content skill: interview and write the profile first, then capture audience quotes into `needs/` (at least 3, aim for 5); do not create a slideshow yet.
 
 ## Lazy auth (Agent script)
 
@@ -40,8 +40,7 @@ When a Gateway call returns `AUTH_REQUIRED`, `API_KEY_INVALID`, or the CLI says
 `Run easysociable auth login`, respond with:
 
 ```text
-EasySociable needs a workspace API key before it can preview or render on the
-Gateway.
+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).
@@ -64,4 +63,4 @@ idempotency key when applicable.
 ## What requires auth
 
 - Brands, Themes, images, drafts, Slideshow Runs
-- Hosted preview sessions and final PNG renders (`hosted_render_page` allowance)
+- Studio preview and Studio Download (Free: 3 Downloads/month)

package/skills/easysociable-content/SKILL.md

@@ -1,51 +1,132 @@
 ---
 name: easysociable-content
 description: >
-  Operate the EasySociable Content Engine (capture, discovery, topics, runs).
+  Operate the EasySociable Content Engine (profile, needs, products, recommendations, topics, runs, workbench).
+  Triggers: 采访我, 完善人设, interview me, who am I as a creator, 建立 profile
+  — follow workflows/INTERVIEW.md (engine CLAUDE.md § Interview wins if present).
+  Triggers: 记需求, 扫需求选题, capture audience quotes, user needs, 调研需求, 需求落库
+  — follow workflows/NEEDS.md (engine CLAUDE.md § Needs wins if present).
+  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).
   If no engine exists, run `easysociable engine init`. Then follow
   Content Engine/CLAUDE.md. Render handoff: easysociable-template (1 page) or
   easysociable-slideshow (2+). Never publish or post.
 ---
 
-# EasySociable Content (pointer)
+# EasySociable Content
 
-This skill is an entry card only. **Do not invent a parallel workflow.**
+Entry card for agents. **Do not invent a parallel workflow.** Instance SoT is that engine’s `Content Engine/CLAUDE.md`. Workflows here fill gaps or win when newer than the matching § in CLAUDE.md.
 
-## Create the engine
+## 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.
+
+## Pipeline (do not collapse stages)
+
+```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
+```
+
+| 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) |
+
+## 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 结论 / 状态原因 / 适合谁 / 核心判断 / 下一步, then explain the problem, current belief, angle, timing, expected belief change, evidence gap, and recommended form. 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. **Use the smallest honest Topic mode** — demand-led is the default;
+   product/recommendation inputs do not prove audience demand.
+
+Topic modes:
+
+```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
+```
+
+## Create / serve / build
 
 ```bash
 easysociable engine init --root <parent-or-engine> --yes
 easysociable engine serve --engine <parent>/Content Engine --no-open
+easysociable engine build --engine <parent>/Content Engine
+# or, inside the vault:
+python3 workbench/build.py
 ```
 
 On a dedicated agent computer (e.g. Grok Bot), prefer `--root /workspace`.
 
-Existing files are never overwritten. `python3` is required for the workbench.
+Existing files are never overwritten. `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.
 
-## Operate
+`engine init` adds missing `products/` and `recommendations/` starter files to
+older vaults without overwriting user files. It does not invent recommendation
+entries or migrate existing product notes.
 
-Read and follow `Content Engine/CLAUDE.md` (and `engine.json`, `platforms/<platform>.md`).
+## Operate
 
-Rebuild the observatory after markdown writes:
+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.
+4. Rebuild workbench after writes.
 
-```bash
-easysociable engine build --engine <Content Engine>
-```
+| Intent | Action |
+|--------|--------|
+| 采访我 / interview me / 完善人设 / 建立 profile | **workflows/INTERVIEW.md** (not a render) |
+| 记需求 / 用户原话 / capture audience quotes / 调研需求 / 需求落库 | **workflows/NEEDS.md** (not a render) |
+| 更新产品 / 产品库 / 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` |
+| 做成选题 / 生成 topic | engine **§ Topics** — explicit input |
+| 开一单 / 用 T-… 开一单 | engine **§ Open a run** (ask platform; multi → N runs) |
+| 1 page image | **easysociable-template** (after hard gate) |
+| 2+ pages on tiktok / instagram / linkedin / threads | **easysociable-slideshow** (after hard gate) |
+| x / xiaohongshu images | **easysociable-template** only (after hard gate) |
 
-## Render handoff
+## Render hard gate
 
-| Intent | Hand off |
-|--------|----------|
-| 1 page image | **easysociable-template** |
-| 2+ pages on tiktok / instagram / linkedin / threads | **easysociable-slideshow** |
-| x / xiaohongshu images | **easysociable-template** only |
+**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)`.
 
-Validate a run before slideshow create:
+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
+easysociable engine validate --run <run-dir> --require-pack --require-knowledge
 ```
 
+Slideshow packs need an **Arc** line first. Do not default Cover → Point → Steps → Recap → CTA. Page 1 is not automatically `cover`. Handoff: **easysociable-slideshow** (`references/ARC.md`).
+
+## 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

@@ -0,0 +1,70 @@
+# Interview (creator profile)
+
+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.
+
+## Triggers
+
+- 采访我
+- 完善人设
+- interview me
+- who am I as a creator
+- 建立 profile
+
+## Rules
+
+- Ask **one dimension at a time**. Persist that dimension **before** asking the next. Do not batch seven dimensions to the end.
+- Resume by reading files. Skip Public handle `(fill)` (done unless the user wants a handle). Continue from the first gated empty Identity cell (Role / What I build / Point of view) or the next unfinished dimension. Do not re-ask filled Identity rows.
+- Existing `voice.md` with Identity filled but no `## Experience` / `## Values`: **append those headings at the end**. Do not rewrite filled Identity rows.
+- Missing `boundaries.md`: write the empty starter (headings only), then interview. **Never invent boundaries.**
+- Missing `stories.md` / `expression.md`: create the starter file, mark `profile: partial`, continue.
+- `audience.md` / `pillars.md` in this workflow are **drafts only** (hypothesis). Do not invent a full ICP.
+- Never invent bio facts, stories, or values that the user did not say.
+
+## Dimensions → files (8–12 questions)
+
+| # | Dimension | Questions | Persist immediately to |
+|---|-----------|-----------|------------------------|
+| 1 | Identity (2) | 你对外是谁、做什么？你希望别人记住的那句 point of view 是什么？ | `voice.md` `## Identity` — Role / What I build / Point of view. Public handle MAY stay `(fill)`. |
+| 2 | Experience (1–2) | 文案可以引用的 2–3 件事实（年份、角色、做过的事）。没有的就写「not claiming」。 | `voice.md` `## Experience` (append heading if missing) |
+| 3 | Style (1–2) | 想听起来像谁；最讨厌的 AI 腔 / 营销腔。 | `voice.md` `## Persona` + `## Do not say` |
+| 4 | Values (1) | 你一定会说 / 一定不说的主张。 Repeatable topics → `pillars.md` names later, not a copy of this table. | `voice.md` `## Values` (append heading if missing) |
+| 5 | Boundaries (1) | 哪些话题、人群、承诺碰不得。 | `profiles/<id>/boundaries.md`. If the file is missing, write empty starter first, then fill. Never invent. |
+| 6 | Expression (1) | 举三个你喜欢的表达、三个你看到就烦的。 | `profiles/<id>/expression.md` |
+| 7 | Stories (1, skippable) | 一则你常讲、且愿意公开的故事（情境 → 选择 → 教训）。 | `profiles/<id>/stories.md` |
+| 8 | Audience draft (1) | 你以为在写给谁？ Mark `status: hypothesis`. | `audience.md` Primary readers |
+
+## Persist card (after each dimension)
+
+```text
+✅ Profile · Identity
+【File】 profiles/default/voice.md
+【Wrote】 Role … · POV …
+【Missing】 Experience, Values, stories.md
+【Next】 经历（2–3 条可引用事实）
+```
+
+### Example — boundaries file missing
+
+```text
+✅ Profile · Boundaries
+【File】 profiles/default/boundaries.md
+【Wrote】 empty starter (## Not covering / ## Never claim). Did not invent boundaries.
+【Missing】 Not covering, Never claim
+【Next】 边界（哪些话题、人群、承诺碰不得）
+```
+
+## Completion (single table — do not invent other numbers)
+
+| 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. |
+
+Experience / Values / expression are **not** the hard gate. Missing `stories.md` / `expression.md` = partial. Missing `boundaries.md` file = hard-gate fail.
+
+## Open card
+
+After the session (or on resume): `profile: partial | complete` from the table above.

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

@@ -0,0 +1,82 @@
+# Needs (audience quotes)
+
+Not a fourth skill. If the engine `CLAUDE.md` already has **§ Needs**, follow that section **unless this file is newer** — then this file wins for Needs-only rules.
+
+Do **not** invent quotes. Do **not** scan the watchlist to mint needs. Do **not** create a slideshow.
+
+## Triggers
+
+- 记需求 / 用户原话 / 评论导出
+- 扫需求选题
+- capture audience quotes / user needs
+- 调研需求 / 需求落库 / 重新调研并落库
+
+## Research axis (easysociable-builder default)
+
+Product teaches **Content Engines**; EasySociable is the **visual layer**. When researching or screening needs for this profile:
+
+| Layer | Means | Default |
+|-------|--------|---------|
+| **L1** | System / sustainability — what to say, what to publish next, memory, pipeline, consistency | **Prefer** |
+| **L2** | Judgment / review / approval — AI polished but empty; bottleneck moved to human check | **Prefer** |
+| **L3** | Visual / tool friction — Canva, Figma, “looks AI”, brand kit paste | Keep only if user asks; else do not promote as primary |
+
+Put `layer=L1|L2|L3` in **`## Our gloss` only** — never in the index `quote` cell.
+
+**Reject:** course/toolkit CTAs, product demos dressed as pains, watchlist viral titles as quotes, Agent-paraphrased “quotes”, wrong-ICP “idk what to post” with no system angle.
+
+## Rules
+
+- Quote cell = **verbatim**. Gloss goes in `## Our gloss`, never in the index `quote` column.
+- Status is only `captured` | `promoted` | `retired`. **Never** `clustered`. Merge is not a new status.
+- Synonym merge: propose, wait for user yes, then keep the surviving `N-` as `captured`, `frequency += 1`, append a sighting. Retire a mistaken duplicate and note it on the surviving sighting. No hosted clustering.
+- Do not mark `promoted` without a `T-` whose `need_ids` contain this `N-`. `topic_ids` non-empty ≡ `promoted`.
+- Never write `N-` into topic `capture_id`.
+- Hard gate (graphics): once `needs/` exists, `needs/_index.md` needs ≥ **3** `N-` rows. First-session **target** is **5** (under 5 still passes the hard gate). Do not invent quotes to hit the number.
+- Quotes may include DMs / students. Keep local. Redact PII if used as published copy.
+- After Needs writes: rebuild workbench (`python3 workbench/build.py` or `easysociable engine build`).
+
+## Delete vs retire
+
+- `retired` = soft discard while the user may still want the row visible.
+- If the user says **删除 / 删掉 retired / 可以直接删了**: **delete** the entry file(s) and remove the index row(s). Do not leave ghost `retired` rows. Rebuild workbench.
+- Do not delete `captured` or `promoted` without an explicit ask.
+
+## Ingest paths
+
+1. Pasted quote — 「记需求：……」 / “capture audience quotes: …”
+2. Comment / DM export or screenshot — extract quotes; one `N-` each; confirm with the user when unsure.
+3. URL / thread — fetch with host research tools; store the **commenter's** words, not the author's hook. On **X**: `x_*` first, then agent-reach if needed.
+4. After a consult — 「刚才那通咨询记需求」.
+5. Research pass — screen for L1/L2; write `N-` only for verbatim hits; update `_index.md` research note briefly.
+
+Forbidden: Agent-rewritten sentences as quote; watchlist viral titles as need; FAQ templates with no original quote.
+
+## Write
+
+1. New `needs/entries/N-YYYYMMDD-XX.md` from `needs/_template.md`
+2. New row at the top of `needs/_index.md`
+3. Rebuild workbench
+4. Chat card:
+
+```text
+✅ Need N-YYYYMMDD-XX
+【Quote】 …
+【Source】 comment | dm | consult | faq | student | other
+【Layer】 L1 | L2 | L3
+【Frequency】 1
+【Stored】 needs/_index + needs/entries/N-….md
+【Merge】 new | merged into N-… (frequency now k, status still captured)
+```
+
+## 扫需求选题
+
+Input set: `needs/_index.md` rows with `status=captured` (`topic_ids` empty). Max **5** `produce`. Prefer L1/L2 glosses for this profile unless the user asks otherwise.
+
+Then **§ Topics**: Input gate Need ID `N-…`; `source_type=need`; `need_ids` lists the `N-` (never in `capture_id`); default `scout_label=demand`. Still run hard filters.
+
+When `produce` creates a `T-` from an `N-`: update `needs/_index.md` + the entry to `status=promoted` and `topic_ids` containing that `T-`. Discard / library: leave `captured` or `retired` — do not mark `promoted` without a T-.
+
+Audience exception (first activation): `source_type=need` **and** `need_ids` non-empty → matching at least one need gloss counts as one strong audience check; do **not** require a full ICP from `audience.md` / `pillars.md`. `ready` still needs `opp_score ≥ 7.5` **and** `audience ≥ 6`.
+
+Prefer scanning needs before inbox. Inbox is structure / competitor context.

package/skills/easysociable-slideshow/SKILL.md

@@ -2,84 +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 Engine (`CLAUDE.md` + `easysociable engine …`) owns semantic copy
-and Pack creation. The Template Skill owns single-page authoring and fill-slots.
-This Skill only composes explicit page instances and coordinates preview/final
-render.
+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.