@easysociable/cli 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easysociable/cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "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/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-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,20 +26,31 @@ 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 select by **platform +
-   canvas + slotSummary + density + layoutFamily**. `role` / `supportedRoles`
-   are weak retrieval tags, not sequence position.
+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`) — 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,
+   not sequence position. Never browse with bare `templates list` (first 20
+   ids only); use `--platform <p> --all` if you must see the full catalog.
+   Do not copy a previous pack's Template Selection as the default.
 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.
+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.
@@ -45,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 /
@@ -56,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.
@@ -81,10 +98,13 @@ 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. If re-listing the catalog, verify
-   hard filters and cover/hook placement; never place a cover/hook class
-   template after page 1. Record Layout Family evidence as `hypothesis` unless
-   comparable history supports `tested` / `supported`.
+4. Use the Formula Look's families, else pack **Template Selection**. Otherwise run
+   `easysociable slideshows recommend --file contracts.json --seed <slug> --json`
+   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.
 5. List existing Runs when the Pack has a stable content slug:
 
    ```bash
@@ -99,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
@@ -110,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
@@ -119,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,20 +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. List published Page Templates only to **verify** hard filters still hold:
-   platform → canvas → slotSummary → density → page-position cover/hook.
-   Prefer ranking by Layout Family (`layoutFamily`) + history; `supportedRoles`
-   is a weak tag. `pages[0]` must be cover/hook class. Do not use that class on
-   later pages. Prefer families already recorded on linked W- judgments
-   (`fits` / `avoid` / `trial`) when comparable evidence exists.
+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 `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
@@ -29,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