@easysociable/cli 0.1.22 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easysociable/cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Agent-first CLI for EasySociable: Content Engine, Template, Slideshow, and MCP",
   "type": "module",
   "license": "MIT",

package/skills/easysociable-slideshow/SKILL.md

@@ -5,8 +5,8 @@ description: >
   EasySociable Studio. Research facts, pick a proven hook and structure
   (Formula), lay pages out from reference designs (the user's, a Formula's,
   or the catalog's, shuffled), render-check every page locally, then create the Run and hand the user a Studio link.
-  Ask the user only for what only they know (their Brand, once; their own
-  images/screenshots). Final pixels come only from Studio Download.
+  Never block on a question: a missing Brand shows as a bound sample the user
+  fills once in Studio. Final pixels come only from Studio Download.
 ---
 
 # EasySociable Slideshow Skill
@@ -16,10 +16,28 @@ enough to post, where every word is still editable. The output is editable,
 so **a wrong guess is cheap and a question is expensive**: decide platform,
 page count, arc, style and copy yourself; the user fixes details in Studio.
 
-Ask only for what only the user knows:
+What only the user has never blocks the Run; it becomes a visible, replaceable
+stand-in they fill in Studio:
 
-- their Brand (IP name, handle, avatar) — once, ever;
-- their own material (screenshots, photos) when a page needs it.
+- their Brand (name, handle, avatar) → bound samples (step 1);
+- their own material (screenshots, photos) → image placeholders (step 5).
+
+## Command output (`--json`)
+
+Read results from these paths; don't guess:
+
+| Command | Result |
+|---|---|
+| `auth status` | `authenticated`, `account.email` (no `data` wrapper) |
+| `brands list` / `brands get` | `data[]` / `data` (`id`, `name`, `handle`, `colors`, `logoUrl`) |
+| `hooks recommend` | `data.cards[]` (`id`, `hook_type`, `status`, `format`) |
+| `formulas recommend` | `data.cards[]` (`id`, `status`, `recipe`, `swipe`), `data.stop` |
+| `formulas get` | `data` (`beats[]`, `looks[].layouts`) |
+| `templates references` | a top-level array (`familyId`, `name`, `roles`, `style`, `requiresImage`) |
+| `templates source` | top level: `familyId`, `canvas`, `studioJson` |
+| `icons search --query <word>` | icon list for the word |
+| `images upload --path …` | `data[]` (`path`, `asset.url`, or `error`); exit 1 if any failed |
+| `slideshows create` | top level: `id`, `studioUrl` |
 
 ## Workflow
 
@@ -32,22 +50,25 @@ Ask only for what only the user knows:
 - `authenticated: true` → say once: "This Run will be created as
   `<account.email>` — open Studio with the same account."
 
-### 1. Brand (ask once, ever)
+### 1. Brand (never ask)
 
 `easysociable brands list --json`.
 
 - A Brand exists → use it (the most recently updated if several), silently.
-- None → ask in **one** message, everything skippable:
-  "What name and @handle should appear on your carousels? (Optional: an
-  avatar/logo image path.) Reply 'skip' to post without a signature."
-  Create it with `easysociable brands create --file brand.json`
-  (`{ "name", "handle", "colors", "logoAssetId" }`) using the default palette
-  that matches the deck's style (`references/REFERENCES.md`). An avatar: upload
-  it first (step 5's `images upload`) and pass the returned `asset.id` as
-  `logoAssetId`; `brands get` then returns its `logoUrl`.
-  Skipped → no Brand: header shows the topic, the CTA has no handle, and that
-  palette goes in `theme.json` (without a Brand or theme Studio falls back to
-  its dark default).
+  Its colours and fonts style the Run (`--brand-id` in step 7).
+- None, but the prompt gives a name / handle / avatar → create it:
+  `easysociable brands create --file brand.json`
+  (`{ "name", "handle", "colors", "logoAssetId" }`, colours = the deck style's
+  default palette in `references/REFERENCES.md`). An avatar: upload it first
+  (`images upload --path <file> --json`) and pass `data[0].asset.id` as
+  `logoAssetId`.
+- None and nothing given → no Brand, no question. The style's palette goes in
+  `theme.json`.
+
+Either way every Run carries the Brand spots (cover signature, CTA handle),
+bound with `data-brand`; whatever the Brand lacks shows the sample `Your Name`
+/ `@yourhandle` / sample avatar (`references/REFERENCES.md` rule 5). Studio
+asks the user for exactly those fields and updates every page when they fill them.
 
 ### 2. Facts and evidence
 
@@ -69,9 +90,11 @@ neither.
 - Take image URLs from pages you already opened (`og:image`, images in the
   body) and download them: `curl -sL -o assets/<name>.png <url>`. PNG, JPEG or
   WebP only (convert anything else to PNG), ≤ 20 MB.
-- Launch posts often show the product only in demo videos: download the video
-  and pull frames of the real UI (`ffmpeg -ss <seconds> -i demo.mp4 -frames:v 1
-  frame.png`), then crop to the phone or window. A frame where the key moment is
+- Launch posts often show the product only in demo videos: pull frames of the
+  real UI straight from the video URL, without downloading the whole file
+  (`ffmpeg -ss <seconds> -i <video url> -frames:v 1 frame.png`; a contact sheet
+  to find the moment: `ffmpeg -i <video url> -vf "fps=1/3,scale=240:-1,tile=6x2"
+  -frames:v 1 sheet.jpg`), then crop to the phone or window. A frame where the key moment is
   on screen (an approval prompt, a result) beats a generic screen.
 - **Look at every file** before keeping it. Drop it when it is off-topic,
   unreadable at phone size, would need more than 1.25× upscaling to fill its
@@ -172,10 +195,8 @@ Say 'same as this'. Want another look? Say 'different look'."
 - Fill each image area in this order:
   1. The user's own image, when they gave one.
   2. An evidence image from step 2. Upload it
-     (`easysociable images upload --file body.json` with
-     `{ "file": "data:image/png;base64,…", "filename": "x.png" }`; build it with
-     `node -e "const f=process.argv[1],t=f.match(/\.(jpe?g|webp)$/i)?(/webp/i.test(f)?'webp':'jpeg'):'png';console.log(JSON.stringify({file:'data:image/'+t+';base64,'+require('fs').readFileSync(f,'base64'),filename:require('path').basename(f)}))" assets/x.png > body.json`)
-     and use the returned `asset.url` as `src`.
+     (all at once: `easysociable images upload --path assets/a.png assets/b.jpg --json`)
+     and use each returned `data[i].asset.url` as `src`.
      Crop and scale it (`objectFit: 'cover'`, `objectPosition`), never alter
      what it shows. To point at something in it, add a separate element on top
      (a red ellipse border, an underline bar) so the user can move or delete it.
@@ -212,7 +233,11 @@ easysociable slideshows create --file pack.json --brand-id <brandId> --json
 # no Brand: --theme theme.json instead of --brand-id
 ```
 
-Reply once with: the `studioUrl`, the arc in one line, the sources (facts and
+Reply once with: the `studioUrl`, the arc in one line, any Brand sample
+left ("The name, handle and avatar on pages 1 and 6 are samples: fill them
+once in the bar at the top of Studio, or in Brands at
+https://my.easysociable.com/brands, and every page updates"; name only the
+fields that are samples), the sources (facts and
 each evidence image: "p1 image: <url>"), and each image placeholder to replace (page + what to upload). Tell them to edit in
 Studio and click **Download** for the PNG ZIP.
 

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

@@ -33,16 +33,26 @@ Roles overlap in the catalog, so pass related ones together: `hook,cover` ·
    not need a real one: keep the area's box and fill it from the content with a
    large number or keyword, a short quote with an oversized quote mark, an
    accent-colour block carrying one word, or one icon from
-   `easysociable icons search` on a tinted block. Never a grey placeholder or an
+   `easysociable icons search --query <word>` on a tinted block. Never a grey placeholder or an
    empty box on the cover. If nothing fits, delete the area and give the
    headline its space.
-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).
+5. Brand chrome — every Run carries the Brand, bound so one Brand edit updates
+   every page. The cover has a signature (avatar + name + handle); the CTA has
+   avatar + handle next to the action. Inner pages keep only the Brand spots
+   their reference already has (never add chrome by habit). Never leave a
+   reference's original name or handle (e.g. "Will.AI.m") on a page.
+   - The element holding only the name gets `data-brand="name"`, only the
+     handle `data-brand="handle"`, the avatar / logo `<img>` `data-brand="avatar"`.
+   - Value: the Brand's `name`, `@handle`, `logoUrl`. A field the Brand lacks
+     (or no Brand at all) → the sample: `Your Name`, `@yourhandle`, and the
+     sample avatar below, still bound. Studio swaps each sample the moment the
+     user fills that field, and asks for it until then.
+   - Size the spots for a real name (up to ~22 characters) — `check-pages`
+     renders them with a long one.
+
+   Sample avatar (`objectFit: 'cover'`, round it with `borderRadius: '50%'`):
+   `data:image/svg+xml;base64,PHN2ZyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnIHdpZHRoPScxNjAnIGhlaWdodD0nMTYwJyB2aWV3Qm94PScwIDAgMTYwIDE2MCc+PHJlY3Qgd2lkdGg9JzE2MCcgaGVpZ2h0PScxNjAnIGZpbGw9JyNDOUNERDMnLz48Y2lyY2xlIGN4PSc4MCcgY3k9JzYyJyByPScyOCcgZmlsbD0nI0Y0RjVGNycvPjxwYXRoIGQ9J00yOCAxNjBjMi0zNCAyNC01MiA1Mi01MnM1MCAxOCA1MiA1MnonIGZpbGw9JyNGNEY1RjcnLz48L3N2Zz4=`
+
 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`,

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

@@ -24,6 +24,8 @@ 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).
+// Brand spots render with the real Brand, or a long stand-in so a real name fits later.
+const BRAND = { name: brand?.name || 'Alexandra Montgomery', handle: brand?.handle ? `@${brand.handle.replace(/^@/, '')}` : '@alexandra.montgomery', avatar: brand?.logoUrl || null }
 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,
@@ -57,6 +59,7 @@ for (const [i, src] of SOURCES.entries()) {
   const box = document.createElement('div')
   box.setAttribute('data-authoring-theme', '')
   box.innerHTML = toHtml(src.json)
+  for (const el of box.querySelectorAll('[data-brand]')) { const f = el.dataset.brand; if (f === 'avatar') { if (BRAND.avatar) el.src = BRAND.avatar } else if (BRAND[f]) el.textContent = BRAND[f] }
   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)
 }
@@ -112,7 +115,7 @@ for (const page of pack.pages) if (!page.layout?.studioJson) console.log(`page $
 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>`
+<script>const SOURCES = ${JSON.stringify(pages).replace(/</g, '\\u003c')}, COLS = ${COLS}, BRAND = ${JSON.stringify(BRAND).replace(/</g, '\\u003c')};${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)
@@ -124,9 +127,13 @@ 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: [] }))
+// Every Run carries the Brand: a cover signature and a CTA handle (references/REFERENCES.md rule 5).
+const brandSpots = { 0: ['name', 'handle', 'avatar'], [pages.length - 1]: ['handle', 'avatar'] }
 let failed = false
 for (const [i, page] of pages.entries()) {
   const report = reports[i]
+  for (const f of (brandSpots[i] ?? []).filter(f => !page.json.includes(`data-brand="${f}"`)))
+    report.errors.push(`no Brand ${f}: the ${i ? 'last' : 'first'} page needs a data-brand="${f}" element`)
   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}`)