hermoso 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hermoso (hermoso.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# Hermoso — MCP, CLI & Skills
+
+Drive [Hermoso](https://hermoso.ai) — the AI ad studio — from **any AI agent**: Claude Code, Claude.ai, Cursor,
+Codex, or your own scripts. Research the ads already winning in a market, plan a creative, and generate finished
+image & video ads (your real product composited in, copy + CTA included) — all over
+[MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.
+
+## Instant: the hosted Claude.ai connector
+
+Paste **`https://app.hermoso.ai/mcp`** into Claude → Settings → Connectors → *Add custom connector*, approve with
+your Hermoso account, done — all 22 tools with your saved brand context, billed to your plan.
+
+## Quickstart for Claude Code / Cursor / scripts (2 minutes)
+
+1. **Get an account** at [app.hermoso.ai](https://app.hermoso.ai) — free tier included; plans & credits are the
+   same ones the web Studio uses.
+2. **Create an agent key**: app.hermoso.ai → **Settings → Agents & API** → Create API key (`hmk_…`).
+3. **Connect** (Claude Code shown; any MCP client works):
+
+```bash
+git clone https://github.com/hermoso-ai/hermoso.git && cd hermoso && npm install
+claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- node "$(pwd)/mcp/hermoso-mcp.mjs"
+```
+
+Your agent now has the full studio **with your workspace's context**: the brand profile, products, logos and
+learned memory you set up in the web app apply automatically (`get_brand` shows what's saved; omit `brand` in
+`plan_ad`/`plan_variations` to use it). Renders bill your Hermoso credits — same prices as the Studio.
+
+## 1. MCP server (stdio) — Claude Code / Cursor / Codex
+
+`mcp/hermoso-mcp.mjs` is a stdio MCP server exposing 22 tools.
+
+```bash
+npm install
+claude mcp add hermoso -- node "$(pwd)/mcp/hermoso-mcp.mjs"
+```
+
+Cursor / Codex — add to `mcp.json` (Codex uses the TOML equivalent):
+
+```json
+{ "mcpServers": { "hermoso": { "command": "node", "args": ["<repo>/mcp/hermoso-mcp.mjs"],
+  "env": { "HERMOSO_API_BASE": "https://app.hermoso.ai", "HERMOSO_TOKEN": "<your token>" } } } }
+```
+
+Then ask your agent: *“Generate an image ad with Hermoso.”*
+
+**Tools (22):** `hermoso_capabilities`, `hermoso_credits`, `get_brand`, `plan_ad`, `plan_variations`, `generate_image`,
+`generate_video`, `generate_avatar`, `stitch_video`, `reframe_video`, `upscale_video`, `dub_video`,
+`recast_motion`, `analyze_video`, `score_ad`, `get_job`, `list_jobs`, `find_competitors`,
+`pull_competitor_ads`, `research_ads`, `draft_brand`, `fetch_asset`. Call `hermoso_capabilities` first — it
+returns valid model ids and per-render credit costs. Render jobs queue server-side and poll to completion,
+returning a served URL.
+
+## 2. CLI — the token-cheap path for terminal agents
+
+`bin/hermoso.mjs` mirrors the tools as subprocess commands, so an agent can shell out instead of carrying a fat
+tool manifest.
+
+```bash
+npm install -g .                                   # installs `hermoso`
+hermoso capabilities                               # valid model ids + costs (run first)
+hermoso create --brand "YourBrand" --product "your best-selling product" --format image
+hermoso generate image --prompt "…" --ref ./product.png --wait
+hermoso generate video --prompt "…" --duration 8 --wait
+hermoso competitors yourbrand.com
+hermoso research "Liquid Death’s longest-running ads"
+```
+
+Add `--json` to any command for machine output.
+
+## 3. Claude skills — slash commands that wrap the CLI
+
+`skills/` holds four installable skills: `hermoso-generate`, `hermoso-ad-from-brand`,
+`hermoso-product-photoshoot`, `hermoso-research`.
+
+```bash
+cp -r skills/* ~/.claude/skills/
+```
+
+Then invoke `/hermoso-ad-from-brand an ad for yourbrand.com — our hero product`.
+
+## Configuration
+
+| Env | Meaning |
+| --- | --- |
+| `HERMOSO_API_BASE` | The Hermoso API origin (default `https://app.hermoso.ai` — set `http://localhost:3000` if you run the app yourself) |
+| `HERMOSO_TOKEN` | Bearer token — required against the hosted app (rolling out) |
+| `HERMOSO_PROFILE` | Brand-workspace id, for accounts with multiple brand profiles |
+
+`mcp/http.mjs` is the hosted remote-connector transport (paste-a-URL into Claude.ai → Connectors). It ships in
+this repo for transparency and refuses to mount without authenticated identity — no anonymous spend, ever.
+
+## License
+
+MIT © Hermoso

package/bin/hermoso.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// Hermoso CLI — drive Hermoso from any terminal agent (Claude Code, Codex, Cursor, OpenClaw…) by shelling out.
+// This is the token-cheap path (the agent runs a command instead of carrying a fat tool manifest); the skills
+// in skills/ wrap these commands. Same /api as the MCP server.
+//
+//   npm i -g  (from this repo)  OR  node bin/hermoso.mjs <cmd>
+//   hermoso auth login --token <key>                   # key from app.hermoso.ai → Settings → Agents & API
+//   hermoso capabilities                                 # learn valid model ids + costs (run first)
+//   hermoso create --brand Flourish --product "protein pancakes" --format image
+//   hermoso generate image --prompt "…" --ref ./bag.png --wait
+//
+// Auth today: none locally (the server resolves the dev account). `hermoso auth login --token <t>` stores a Bearer
+// for when real auth lands — the seam, not a requirement.
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const CONFIG_DIR = path.join(os.homedir(), '.hermoso');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+async function loadConfig() { try { return JSON.parse(await readFile(CONFIG_FILE, 'utf8')); } catch { return {}; } }
+async function saveConfig(c) { await mkdir(CONFIG_DIR, { recursive: true }); await writeFile(CONFIG_FILE, JSON.stringify(c, null, 2)); }
+
+// ---- minimal arg parser: positionals + --flags (--flag value | --flag=value | boolean --flag) ----
+function parse(argv) {
+  const pos = [], flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq >= 0) { flags[a.slice(2, eq)] = a.slice(eq + 1); }
+      else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) { flags[a.slice(2)] = argv[++i]; }
+      else { flags[a.slice(2)] = true; }
+    } else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+const die = (msg) => { console.error('✗ ' + msg); process.exit(1); };
+
+async function main() {
+  const { pos, flags } = parse(process.argv.slice(2));
+  const [group, sub] = pos;
+  const cfg = await loadConfig();
+
+  // ---- auth: no network call today; records base URL + optional token (the OAuth seam) ----
+  if (group === 'auth') {
+    if (sub === 'logout') { await saveConfig({}); return console.log('✓ Logged out (cleared ~/.hermoso/config.json)'); }
+    const next = { apiBase: flags.url || cfg.apiBase || 'https://app.hermoso.ai', token: flags.token || cfg.token || '', profile: flags.profile || cfg.profile || 'default' };
+    await saveConfig(next);
+    console.log(`✓ Saved. API: ${next.apiBase}${next.token ? ' · token stored' : ''}`);
+    if (!next.token) console.log('  Next: create an agent key at app.hermoso.ai → Settings → Agents & API, then run:  hermoso auth login --token <key>');
+    return;
+  }
+  if (group === 'version' || flags.version) {
+    console.log(`hermoso-cli 1.0.0 · API ${cfg.apiBase || process.env.HERMOSO_API_BASE || 'https://app.hermoso.ai'} · ${cfg.token ? 'authed' : 'no token — run: hermoso auth login --token <key>'}`);
+    return;
+  }
+
+  // resolve API base + token from config (env overrides), then load the shared client
+  process.env.HERMOSO_API_BASE = process.env.HERMOSO_API_BASE || cfg.apiBase || 'https://app.hermoso.ai';
+  if (cfg.token && !process.env.HERMOSO_TOKEN) process.env.HERMOSO_TOKEN = cfg.token;
+  if (cfg.profile && !process.env.HERMOSO_PROFILE) process.env.HERMOSO_PROFILE = cfg.profile;
+  const api = await import('../mcp/client.mjs');
+  const out = (label, data) => { if (flags.json) console.log(JSON.stringify(data, null, 2)); else console.log(label); };
+  const absUrl = (u) => (u && u.startsWith('/') ? api.API_BASE + u : u);
+
+  try {
+    switch (group) {
+      case 'capabilities': case 'caps': {
+        const d = await api.apiGet('/api/generate/status');
+        if (flags.json) return console.log(JSON.stringify(d, null, 2));
+        console.log('IMAGE models:'); (d.options?.image?.models || []).forEach(m => console.log(`  ${m.id.padEnd(18)} ${m.label} · ${m.credits}cr${m.best ? ' ★best' : ''}`));
+        console.log('VIDEO models:'); (d.options?.video?.models || []).forEach(m => console.log(`  ${m.id.padEnd(18)} ${m.label} · ${(m.durations || []).join('/')}s`));
+        console.log(`flags: canEdit=${d.canEdit} canAvatar=${d.canAvatar} canPublish=${d.canPublish}`);
+        console.log(`recipes: ${(d.recipes || []).map(r => r.id).join(', ')}`);
+        return;
+      }
+      case 'credits': { const d = await api.apiGet('/api/credits'); return out(`Balance: ${d.balance} credits · session used: ${d.sessionUsed ?? 0}`, d); }
+      case 'brand': {
+        if (sub !== 'draft') return die('usage: hermoso brand draft (--domain <d> | --description <t> | --social <h> --platform <p>)');
+        const body = flags.domain ? { domain: flags.domain } : flags.description ? { description: flags.description } : flags.social ? { socialHandle: flags.social, platform: flags.platform || 'instagram' } : null;
+        if (!body) return die('give --domain, --description, or --social');
+        const d = await api.apiPost('/api/brand/draft', body); const p = d.profile || d;
+        return out(`✓ ${p.name || '—'}${p.category ? ' · ' + p.category : ''}${p.domain ? ' · ' + p.domain : ''}`, p);
+      }
+      case 'create': {
+        if (!flags.product) return die('usage: hermoso create --brand <b> --product <p> [--format auto|image|video] [--recipe <id>]');
+        const d = await api.apiPost('/api/create', { brand: { name: flags.brand || '' }, product: flags.product, format: flags.format || 'auto', recipe: flags.recipe || '', reference: flags.reference ? { url: flags.reference } : null, language: flags.language || '' });
+        const c = d.creative || d;
+        if (flags.json) return console.log(JSON.stringify(c, null, 2));
+        console.log(`Concept (${c.format}${c.recipe_label ? ' · ' + c.recipe_label : ''}): ${c.concept}`);
+        console.log(`Headline: ${c.copy?.[0]?.headline || ''}`);
+        console.log(`Render with: ${c.format === 'video' ? c.vmodel : c.imodel || 'default'}  →  hermoso generate ${c.format === 'video' ? 'video' : 'image'} --prompt "…"`);
+        return;
+      }
+      case 'generate': case 'gen': {
+        const wait = flags.wait !== false && flags.wait !== 'false';
+        if (sub === 'image') {
+          if (!flags.prompt) return die('--prompt required');
+          const refs = []; for (const k of ['ref', 'refs']) if (flags[k]) refs.push(...String(flags[k]).split(','));
+          const refImages = refs.length ? (await Promise.all(refs.map(api.toRef))).filter(Boolean) : undefined;
+          const d = await api.apiPost('/api/generate/image', { prompt: flags.prompt, refImages, aspectRatio: flags.aspect, model: flags.model });
+          return out(`✓ Image: ${absUrl(d.image)}${d.model ? ` (${d.model})` : ''}`, { ...d, image: absUrl(d.image) });
+        }
+        // video | avatar | stitch → job + poll
+        const type = sub;
+        if (!['video', 'avatar', 'stitch'].includes(type)) return die('usage: hermoso generate image|video|avatar|stitch …');
+        let input = {};
+        if (type === 'video') { if (!flags.prompt) return die('--prompt required'); input = { prompt: flags.prompt, refImage: flags.ref ? await api.toRef(flags.ref) : undefined, durationSeconds: flags.duration ? +flags.duration : undefined, aspectRatio: flags.aspect, model: flags.model, resolution: flags.resolution, ttsScript: flags.tts, ttsVoice: flags.voice, musicMood: flags.music }; }
+        else if (type === 'avatar') { if (!flags.image || !flags.script) return die('--image and --script required'); input = { image: await api.toRef(flags.image), script: flags.script, voice: flags.voice, resolution: flags.resolution }; }
+        else if (type === 'stitch') { if (!flags.scenes) return die('--scenes <file.json> required'); input = { scenes: JSON.parse(await readFile(flags.scenes, 'utf8')), aspectRatio: flags.aspect, voiceover: flags.voiceover, voice: flags.voice, resolution: flags.resolution }; }
+        const job = await api.submitJob(type, input, { label: 'cli ' + type });
+        if (!wait) return out(`Queued job ${job.id} — poll with: hermoso jobs get ${job.id} --wait`, job);
+        process.stderr.write(`rendering (job ${job.id})…`);
+        const { result } = await api.pollJob(job.id, { timeoutMs: +(flags['wait-timeout'] || 600) * 1000, intervalMs: +(flags['wait-interval'] || 3) * 1000, onTick: () => process.stderr.write('.') });
+        process.stderr.write('\n');
+        const url = absUrl(result?.video || result?.image || result?.url);
+        return out(`✓ ${type}: ${url}${result?.model ? ` (${result.model})` : ''}`, { ...result, url });
+      }
+      case 'jobs': {
+        if (sub === 'get') { const id = pos[2]; if (!id) return die('usage: hermoso jobs get <id> [--wait]'); if (flags.wait) { const { result } = await api.pollJob(id, { timeoutMs: 600000 }); return out(`✓ ${absUrl(result?.video || result?.image || result?.url)}`, result); } const j = await api.getJob(id); return out(`${j.id} ${j.type} ${j.status}${j.progress ? ` ${Math.round(j.progress * 100)}%` : ''}`, j); }
+        const d = await api.apiGet('/api/jobs');
+        if (flags.json) return console.log(JSON.stringify(d, null, 2));
+        console.log(`${d.running} running.`); (d.jobs || []).slice(0, 15).forEach(j => console.log(`  ${j.id}  ${j.type.padEnd(7)} ${j.status}`));
+        return;
+      }
+      case 'competitors': { const domain = sub; if (!domain) return die('usage: hermoso competitors <domain> [--mode competitors|inspiration|company]'); const d = await api.apiPost('/api/inspire/competitors', { domain, mode: flags.mode || 'competitors' }); if (flags.json) return console.log(JSON.stringify(d, null, 2)); (d.candidates || []).forEach(c => console.log(`  ${c.name}  (${c.domain || '—'}, ${c.kind})`)); return; }
+      case 'ads': {
+        if (sub !== 'pull') return die('usage: hermoso ads pull (--company <n> | --domain <d>) [--platforms facebook,google,linkedin]');
+        const d = await api.apiPost('/api/inspire/fanout', { companyName: flags.company, domain: flags.domain, platforms: flags.platforms ? String(flags.platforms).split(',') : ['facebook'], country: flags.country || 'US', limit: +flags.limit || 30, sort: flags.sort || 'longest_running' });
+        return out('✓ pulled (use --json to see the ads)', d);
+      }
+      case 'research': { const q = sub || flags.query; if (!q) return die('usage: hermoso research "<request>"'); const d = await api.apiSSE('/api/explore/chat', { messages: [{ role: 'user', content: q }] }); if (flags.json) return console.log(JSON.stringify(d, null, 2)); console.log(d.reply || ''); console.log(`\n(${(d.results || []).length} ads found)`); return; }
+      case 'fetch': { const url = sub; if (!url) return die('usage: hermoso fetch <url> [--out <name>]'); const r = await fetch(`${api.API_BASE}/api/download?url=${encodeURIComponent(url)}`); if (!r.ok) return die(`download failed (HTTP ${r.status})`); const buf = Buffer.from(await r.arrayBuffer()); const name = flags.out || path.basename(url.split(/[?#]/)[0]) || 'asset'; await writeFile(name, buf); return console.log(`✓ saved ${name} (${buf.length} bytes)`); }
+      default:
+        console.log(`hermoso <command>
+  auth login [--url <base>] [--token <t>]   credits          capabilities
+  brand draft (--domain|--description|--social …)             create --brand --product [--format]
+  generate image --prompt [--ref] [--model] [--aspect]        generate video|avatar|stitch … [--wait]
+  jobs list | jobs get <id> [--wait]                          competitors <domain>
+  ads pull (--company|--domain)                               research "<request>"
+  fetch <url> [--out]                                         version
+add --json to any command for machine output.`);
+    }
+  } catch (e) { die(e?.message || String(e)); }
+}
+main();

package/mcp/client.mjs

@@ -0,0 +1,108 @@
+// Tiny fetch wrapper around the Hermoso HTTP API, shared by the MCP server (mcp/tools.mjs) and the CLI (bin/hermoso.mjs).
+// LOCAL today: no auth needed — the server's local auth adapter resolves the fixed dev account, so requireAuth/
+// gateSpend pass. When real auth lands, set HERMOSO_TOKEN (a Bearer) and the SAME calls become authoritative — no
+// changes here. We attach the x-hermoso-plan / x-hermoso-user fallbacks the browser also sends, purely for parity;
+// the server treats them as non-authoritative (identity comes from the verified token / local dev user).
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+// Remote-connector identity: mcp/http.mjs wraps each request in mcpCtx.run({ token }) so every /api call a tool
+// makes carries THAT caller's bearer (bills their account). stdio keeps using the env token — ctx is simply unset.
+export const mcpCtx = new AsyncLocalStorage();
+
+export const API_BASE = (process.env.HERMOSO_API_BASE || 'https://app.hermoso.ai').replace(/\/+$/, '');
+const TOKEN = process.env.HERMOSO_TOKEN || '';
+export const PROFILE = process.env.HERMOSO_PROFILE || 'default';
+
+function headers(extra = {}) {
+  const ctx = mcpCtx.getStore();
+  const h = { 'Content-Type': 'application/json', 'x-hermoso-user': ctx?.profile || PROFILE, ...extra };
+  const tok = ctx?.token || TOKEN;
+  if (tok) h.Authorization = `Bearer ${tok}`;
+  return h;
+}
+
+// unwrap the {data}|{error} envelope; throw a clean Error (with .status) on failure
+async function unwrap(res) {
+  let body = null;
+  try { body = await res.json(); } catch {}
+  if (!res.ok) {
+    const msg = (body && (body.error || body.message)) || `HTTP ${res.status}`;
+    throw Object.assign(new Error(msg), { status: res.status });
+  }
+  return body && Object.prototype.hasOwnProperty.call(body, 'data') ? body.data : body;
+}
+
+export async function apiGet(p, query) {
+  const qs = query ? '?' + new URLSearchParams(query).toString() : '';
+  const res = await fetch(`${API_BASE}${p}${qs}`, { headers: headers() });
+  return unwrap(res);
+}
+
+export async function apiPost(p, body = {}) {
+  const res = await fetch(`${API_BASE}${p}`, { method: 'POST', headers: headers(), body: JSON.stringify(body) });
+  return unwrap(res);
+}
+
+export async function apiPut(p, body = {}) {
+  const res = await fetch(`${API_BASE}${p}`, { method: 'PUT', headers: headers(), body: JSON.stringify(body) });
+  return unwrap(res);
+}
+
+// /api/explore/chat streams Server-Sent-Events; collect to the terminal `done` payload {reply, results, actions}.
+export async function apiSSE(p, body = {}) {
+  const res = await fetch(`${API_BASE}${p}`, { method: 'POST', headers: headers({ Accept: 'text/event-stream' }), body: JSON.stringify(body) });
+  if (!res.ok) { let e; try { e = (await res.json()).error; } catch {} throw Object.assign(new Error(e || `HTTP ${res.status}`), { status: res.status }); }
+  const reader = res.body.getReader(); const dec = new TextDecoder();
+  let buf = '', done = null, error = null; const progress = [];
+  for (;;) {
+    const { value, done: fin } = await reader.read(); if (fin) break;
+    buf += dec.decode(value, { stream: true });
+    const frames = buf.split('\n\n'); buf = frames.pop() || '';
+    for (const f of frames) {
+      const em = /event:\s*(.+)/.exec(f), dm = /data:\s*([\s\S]+)/.exec(f);
+      if (!em || !dm) continue;
+      let d; try { d = JSON.parse(dm[1]); } catch { continue; }
+      const ev = em[1].trim();
+      if (ev === 'progress') progress.push(d.label);
+      else if (ev === 'done') done = d;
+      else if (ev === 'error') error = d.error;
+    }
+  }
+  if (error) throw new Error(error);
+  if (!done) throw new Error('Stream closed before a response');
+  return { ...done, progress };
+}
+
+// Submit a render to the job queue and (optionally) poll it to completion. Returns the UNWRAPPED worker result
+// (the {image|video, model} object) on success — the job's `result` is itself a {data} envelope, so we peel it.
+export async function submitJob(type, input, { label = '' } = {}) {
+  return apiPost('/api/jobs', { type, input, label }); // → publicJob {id, status, ...}
+}
+export async function getJob(id) { return apiGet(`/api/jobs/${encodeURIComponent(id)}`); } // → publicJob
+export function jobResult(job) { const r = job?.result; return r && Object.prototype.hasOwnProperty.call(r, 'data') ? r.data : r; }
+
+export async function pollJob(id, { intervalMs = 3000, timeoutMs = 10 * 60 * 1000, onTick } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const job = await getJob(id);
+    onTick?.(job);
+    if (job.status === 'done') return { job, result: jobResult(job) };
+    if (job.status === 'error') throw new Error(job.error || 'Render failed');
+    if (Date.now() > deadline) throw Object.assign(new Error('Render timed out — check `hermoso jobs get ' + id + '`'), { jobId: id });
+    await new Promise(r => setTimeout(r, intervalMs));
+  }
+}
+
+// Read a local image path → data URI (so --ref local files force Nano-Banana compositing); pass http(s) URLs through.
+export async function toRef(srcOrPath) {
+  if (!srcOrPath) return null;
+  if (/^(https?:|data:)/.test(srcOrPath)) return srcOrPath;
+  const buf = await readFile(srcOrPath);
+  const ext = path.extname(srcOrPath).toLowerCase().replace('.', '');
+  const mime = ext === 'png' ? 'image/png' : ext === 'webp' ? 'image/webp' : ext === 'gif' ? 'image/gif' : 'image/jpeg';
+  return `data:${mime};base64,${buf.toString('base64')}`;
+}
+
+export const authState = () => ({ apiBase: API_BASE, hasToken: !!TOKEN, profile: PROFILE });

package/mcp/hermoso-mcp.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Hermoso MCP server (stdio transport) — lets Claude Code / Cursor / Codex (and any stdio MCP client) drive Hermoso:
+// research competitors, plan ads, and generate images/videos/avatars, all against the running Hermoso server.
+//
+//   Local (today):   node mcp/hermoso-mcp.mjs            # talks to https://app.hermoso.ai (HERMOSO_API_BASE to override, e.g. http://localhost:3000 when self-running)
+//   Auth (today):    none — the local server resolves the dev account. Set HERMOSO_TOKEN once real auth lands.
+//
+// stdout is the JSON-RPC channel — NEVER print to it. All logging goes to stderr (console.error).
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTools } from './tools.mjs';
+import { API_BASE } from './client.mjs';
+
+const server = new McpServer({ name: 'hermoso-mcp', version: '1.0.0' }, {
+  instructions: 'Hermoso generates copyable, on-brand ad creative. Typical flow: hermoso_capabilities (learn valid model ids + costs) → optionally draft_brand → plan_ad (concept + copy) → generate_image / generate_video (returns a served URL). Use find_competitors / pull_competitor_ads / research_ads to gather proven ads to remix first. Always report the final media URL to the user.',
+});
+
+registerTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`[hermoso-mcp] ready · API ${API_BASE}`);

package/mcp/http.mjs

@@ -0,0 +1,77 @@
+// ───────────────────────────────────────────────────────────────────────────────────────────────────────
+// REMOTE MCP CONNECTOR — DEFERRED. This is the Claude.ai "custom connector" surface (https://<host>/mcp):
+// a Streamable-HTTP MCP transport + OAuth so any Claude.ai / Cursor user can connect Hermoso by URL and sign in,
+// exactly like Higgsfield's mcp.higgsfield.ai/mcp.
+//
+// It is written so the cloud step is a CONFIG FLIP, not a rewrite — but it is intentionally OFF and will REFUSE
+// to mount until BOTH are true:
+//   (1) HERMOSO_MCP_REMOTE=1, and
+//   (2) a real token verifier is wired (verifyBearer) — i.e. Firebase Auth (or equivalent) is configured.
+// Why it must stay off locally: a public money-spending endpoint cannot exist without authenticated identity
+// (the no-anon-spend rule), there is no hosted origin yet, and per the rollout plan cloud is provisioned
+// COLLABORATIVELY, never solo. Until then, use the local stdio server (mcp/hermoso-mcp.mjs) + the CLI + skills.
+//
+// When the cloud step happens, the remaining work is small and explicit (see ENABLE CHECKLIST at the bottom).
+// ───────────────────────────────────────────────────────────────────────────────────────────────────────
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { registerTools } from './tools.mjs';
+import { mcpCtx } from './client.mjs';
+
+// Mount the remote connector onto the Express app. No-op unless explicitly enabled + auth-backed.
+// `verifyBearer(token) -> {userId, accountId, email} | null` MUST be supplied by the caller (the real auth seam).
+export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
+  if (process.env.HERMOSO_MCP_REMOTE !== '1') return false;             // gate 1: off by default
+  if (typeof verifyBearer !== 'function') {                           // gate 2: refuse without real auth
+    console.error('[mcp-remote] REFUSING to mount: no token verifier wired. A remote, money-spending MCP must authenticate every caller (no-anon-spend). Wire Firebase Auth → verifyBearer first.');
+    return false;
+  }
+  const BASE = (publicBaseUrl || process.env.HERMOSO_PUBLIC_URL || '').replace(/\/+$/, '');
+
+  // RFC 9728 protected-resource metadata — tells Claude.ai where to get a token. (Authorization-server metadata
+  // is served by the auth provider itself, e.g. Firebase/your IdP.)
+  app.get('/.well-known/oauth-protected-resource', (req, res) => res.json({
+    resource: `${BASE}/mcp`,
+    authorization_servers: [process.env.HERMOSO_OAUTH_ISSUER].filter(Boolean),
+    scopes_supported: ['hermoso.generate', 'hermoso.research'],
+    bearer_methods_supported: ['header'],
+  }));
+
+  // Per-session Streamable-HTTP transports. Each authenticated session gets its own McpServer with the same tools.
+  const sessions = new Map(); // mcp-session-id -> { transport, server }
+  const challenge = (res) => res.status(401).set('WWW-Authenticate', `Bearer resource_metadata="${BASE}/.well-known/oauth-protected-resource"`).json({ error: 'Authentication required' });
+
+  app.all('/mcp', async (req, res) => {
+    // EVERY call must carry a valid bearer — fail CLOSED (Claude.ai has historically made tokenless probe calls).
+    const auth = req.headers.authorization || '';
+    const token = auth.startsWith('Bearer ') ? auth.slice(7) : '';
+    const user = token ? await verifyBearer(token).catch(() => null) : null;
+    if (!user) return challenge(res);
+
+    const sid = req.headers['mcp-session-id'];
+    let entry = sid && sessions.get(sid);
+    if (!entry) {
+      const server = new McpServer({ name: 'hermoso', version: '1.0.0' });
+      registerTools(server); // the SAME tools as stdio — but here every /api call they make carries this user's token
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => 'sess_' + Math.random().toString(36).slice(2),
+        onsessioninitialized: (id) => sessions.set(id, entry),
+      });
+      transport.onclose = () => { if (transport.sessionId) sessions.delete(transport.sessionId); };
+      entry = { transport, server, user };
+      await server.connect(transport);
+    }
+    await mcpCtx.run({ token }, () => entry.transport.handleRequest(req, res, req.body)); // the caller's bearer rides into every /api call the tools make — spend bills THEIR account
+  });
+
+  console.error(`[mcp-remote] mounted at ${BASE || '(set HERMOSO_PUBLIC_URL)'}/mcp`);
+  return true;
+}
+
+// ── ENABLE CHECKLIST (cloud step, collaborative) ──────────────────────────────────────────────────────────
+//  1. Provision a hosted origin (Cloud Run) + Firebase Auth; set HERMOSO_PUBLIC_URL + HERMOSO_OAUTH_ISSUER.
+//  2. Implement verifyBearer(token) via the Firebase auth adapter (adapters/auth/firebase.js) and pass it here.
+//  3. Thread the authenticated user into mcp/client.mjs's outbound /api calls (AsyncLocalStorage) so reserve()/
+//     gateSpend bill the right account — the server-side enforcement is already authoritative once req.user is real.
+//  4. Set HERMOSO_MCP_REMOTE=1. Then in server.js: `import { mountRemoteMcp } from './mcp/http.mjs'; mountRemoteMcp(app, { verifyBearer, publicBaseUrl })`.
+//  5. The published connector URL becomes `${HERMOSO_PUBLIC_URL}/mcp` — paste into Claude.ai → Settings → Connectors.

package/mcp/tools.mjs

@@ -0,0 +1,477 @@
+// All Hermoso MCP tools, each a thin wrapper over a real /api route (see mcp/client.mjs). Job-based renders
+// (video/avatar/stitch) submit to the queue and POLL TO COMPLETION inside the tool — works in every MCP client
+// (no experimental Tasks dependency) and returns the final served URL. get_job/list_jobs cover resume/inspection.
+// Spend tools hit routes guarded by gateSpend → requireAuth; locally the dev account always resolves (no auth
+// needed today), and the SAME guard becomes authoritative under real auth — so this honors no-anon-spend as-is.
+import { z } from 'zod';
+import { apiGet, apiPost, apiPut, apiSSE, submitJob, getJob, jobResult, pollJob, toRef, API_BASE, PROFILE, mcpCtx } from './client.mjs';
+
+const JOB_TIMEOUT = +(process.env.HERMOSO_JOB_TIMEOUT_MS || 10 * 60 * 1000);
+const abs = (u) => (u && u.startsWith('/') ? API_BASE + u : u); // /generated/x.mp4 → clickable absolute URL
+const ok = (text, data) => ({ content: [{ type: 'text', text }], structuredContent: data ?? undefined });
+// Video-return variant: attaches the clip's first frame as an inline image block (Claude can't play mp4 in chat,
+// but a poster makes the result VISIBLE, mirroring generate_image). Falls back to plain ok() when frames fail.
+const stillMsg = (r) => `Still rendering — job ${r.jobId}. This is NORMAL: video renders take 1–3 minutes and each get_job call waits up to ~45s, so it can take several calls. Keep calling get_job with this id until status is done or error — do NOT ask the user whether to keep waiting, and do NOT re-fire the render on another model (that double-charges). Only surface a problem after ~6 minutes of polling.`;
+const okVideo = async (text, r) => {
+  if (r?.stillRendering) return ok(stillMsg(r), r); const p = r?.url ? await videoPosterBlock(r.url) : null; return { content: [{ type: 'text', text: p ? text + '\n(first frame attached — open the URL for the full video)' : text }, ...(p ? [p] : [])], structuredContent: r ?? undefined }; };
+// Inline the finished image so Claude RENDERS it in chat instead of just linking it (MCP image content block).
+// Skipped silently for huge files / fetch errors — the URL in the text always works.
+// Claude can't play video inline — attach the FIRST FRAME as an image block next to the link so the spot is
+// visible in chat (0 credits; ffmpeg still via /api/video/frames).
+async function videoPosterBlock(videoUrl) {
+  try {
+    const d = await apiGet('/api/video/frames', { url: videoUrl, n: 1 });
+    const f = (d.frames || [])[0]; if (!f || !/^data:image\//.test(f)) return null;
+    const [head, b64] = f.split(',');
+    return { type: 'image', data: b64, mimeType: head.slice(5).split(';')[0] };
+  } catch (e) { console.error('[mcp] video poster failed:', String(e?.message || e).slice(0, 160)); return null; } // silent-null keeps the link usable; log so a missing poster is diagnosable (Dave hit this on Claude.ai)
+}
+async function imageBlock(url) {
+  try {
+    const r = await fetch(url); if (!r.ok) return null;
+    const ct = (r.headers.get('content-type') || 'image/jpeg').split(';')[0];
+    if (!/^image\//.test(ct)) return null;
+    const buf = Buffer.from(await r.arrayBuffer());
+    if (buf.length > 1_400_000) return null;
+    return { type: 'image', data: buf.toString('base64'), mimeType: ct };
+  } catch { return null; }
+}
+const wrap = (fn) => async (args, extra) => {
+  try { return await fn(args, extra); }
+  catch (e) {
+    let msg = `Error: ${e?.message || e}`;
+    // credit outages need an actionable path the agent can relay — the web app has a top-up gate; here the URL is it
+    if (/not enough credits/i.test(msg)) msg += `\nTop up or upgrade at https://app.hermoso.ai (Settings → Billing), then retry — nothing was charged. hermoso_credits shows the balance; hermoso_capabilities lists per-model credit costs.`;
+    return { content: [{ type: 'text', text: msg }], isError: true };
+  }
+};
+
+// run a job to completion, surfacing the served media URL. Under the HOSTED connector (Claude.ai/ChatGPT) the
+// client kills long tool calls before a 1-3 min render finishes — so cap the in-call wait there and return a
+// RESUMABLE handle instead of dying (the agent polls get_job, which now attaches the poster on done).
+async function renderJob(type, input, label) {
+  const job = await submitJob(type, input, { label });
+  const remote = !!mcpCtx.getStore(); // AsyncLocalStorage ctx only exists on the remote transport
+  try {
+    const { result } = await pollJob(job.id, { timeoutMs: remote ? 45_000 : JOB_TIMEOUT });
+    const url = abs(result?.video || result?.image || result?.url);
+    return { jobId: job.id, url, model: result?.model || null, raw: result };
+  } catch (e) {
+    if (remote && e?.jobId) return { jobId: job.id, url: null, stillRendering: true, raw: null }; // not an error — resume via get_job
+    throw e;
+  }
+}
+
+export function registerTools(server) {
+  // ---------- read-only / discovery ----------
+  server.registerTool('hermoso_capabilities', {
+    description: 'Probe what this Hermoso account can do RIGHT NOW: available image/video model ids + their exact credit costs, aspect ratios, video durations, the recipe ids, and the canEdit/canAvatar/canPublish flags. Call this FIRST so you generate with valid model ids and known costs. Read-only, free.',
+    inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: false },
+  }, wrap(async () => {
+    const d = await apiGet('/api/generate/status');
+    const img = (d.options?.image?.models || []).map(m => `${m.id} (${m.label}, ${m.credits}cr${m.best ? ', best' : ''})`).join('; ');
+    // durations + per-duration credits MATTER: without them agents assume the generic "AI video caps at 8-10s"
+    // prior and wrongly steer users to stitching (a real Claude.ai session did exactly that on a 15s ad)
+    const vid = (d.options?.video?.models || []).map(m => `${m.id} (${m.label}: one continuous clip of ${(m.durations || []).map(x => `${x}s=${m.credits?.[x] ?? '?'}cr`).join(' ')}${m.audio ? ', native audio' : ', silent'}${m.best ? ', best' : ''})`).join('; ');
+    const text = `Image: ${d.image ? img : 'unavailable'}\nVideo: ${d.video ? vid : 'unavailable'}\nIMPORTANT: durations above are SINGLE-PASS — e.g. seedance-2 renders a full multi-beat 15s ad in ONE generation (do NOT assume a generic 8–10s cap, and do NOT stitch for ≤15s spots; stitching is only for longer). durationSeconds must be one of the model's listed values.\ncanEdit:${d.canEdit} canAvatar:${d.canAvatar} canPublish:${d.canPublish}\nRecipes (${(d.recipes || []).length}): ${(d.recipes || []).slice(0, 20).map(r => r.id).join(', ')}…`;
+    return ok(text, d);
+  }));
+
+  server.registerTool('hermoso_credits', {
+    description: 'Return the account credit balance, credits used this session, and recent priced calls. Check before kicking off paid generation.',
+    inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: false },
+  }, wrap(async () => {
+    const d = await apiGet('/api/credits');
+    const bal = d.accountBalance ?? d.balance; // accountBalance = the caller's Hermoso credits (authed); balance = the local-dev usage pill
+    return ok(`Balance: ${bal} credits${d.sessionUsed != null ? ` · session used: ${d.sessionUsed}` : ''}`, d);
+  }));
+
+  server.registerTool('list_brands', {
+    description: "List every brand on this account (id + name) and which one this connection currently acts on. Multi-brand accounts: call this, then use_brand to switch. Read-only, free.",
+    inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: false },
+  }, wrap(async () => {
+    const d = await apiGet('/api/brands');
+    const lines = (d.brands || []).map(b => `• ${b.name} (id: ${b.id})${b.active ? '  ← active' : ''}`).join('\n');
+    return ok(`Brands on this account:\n${lines}\n\nSwitch with use_brand.`, d);
+  }));
+
+  server.registerTool('use_brand', {
+    description: "Pin which brand this connection generates for (multi-brand accounts). Pass the brand id or exact name from list_brands. Persists for this API key until changed.",
+    inputSchema: { brand: z.string().describe('brand id (e.g. default / p_xxx) or its exact name from list_brands') },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+  }, wrap(async ({ brand }) => {
+    const d = await apiGet('/api/brands');
+    const want = String(brand || '').trim().toLowerCase();
+    const hit = (d.brands || []).find(b => b.id.toLowerCase() === want || String(b.name || '').toLowerCase() === want);
+    if (!hit) return { content: [{ type: 'text', text: `No brand matching "${brand}". Available:\n${(d.brands || []).map(b => `• ${b.name} (id: ${b.id})`).join('\n')}` }], isError: true };
+    await apiPost('/api/keys/brand', { profileId: hit.id });
+    return ok(`Now acting on ${hit.name} (${hit.id}) — brand, memory, renders and Library all scope to it.`, { ok: true, brand: hit });
+  }));
+
+  // ---------- planning (LLM, 0 SC credits) ----------
+  server.registerTool('plan_ad', {
+    description: 'Creative director: turn a brand + product/brief into a finished ad CONCEPT — copy variants (headline/primary/cta) plus an image_concept.prompt OR a video_storyboard, with the resolved recipe + the model ids to render with. Renders nothing; chain its output into generate_image / generate_video. Spends LLM tokens, 0 ScrapeCreators credits.',
+    inputSchema: {
+      brand: z.union([z.string(), z.object({}).passthrough()]).optional().describe('brand name, or a brand profile object {name,domain,category,palette,products,…}. OMIT to use the workspace’s SAVED brand + memory automatically (see get_brand); use draft_brand to onboard a new one'),
+      product: z.string().describe('what to advertise + any angle/offer the user specified'),
+      format: z.enum(['auto', 'image', 'video']).optional().describe("'image', 'video', or 'auto' when unspecified"),
+      recipe: z.string().optional().describe('a recipe id from hermoso_capabilities to force an archetype'),
+      reference: z.string().optional().describe('a reference ad URL to remix the angle from — Facebook Ad Library, LinkedIn Ad Library or Google Ads Transparency links (the real ad’s copy/advertiser are fetched and fed into the concept)'),
+      language: z.string().optional(),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async ({ brand, product, format = 'auto', recipe, reference, language }) => {
+    const brandObj = brand ? (typeof brand === 'string' ? { name: brand } : brand) : null; // null → the server hydrates the workspace's saved brand/memory/taste
+    const d = await apiPost('/api/create', { brand: brandObj, product, format, recipe: recipe || '', reference: reference ? { url: reference } : null, language: language || '' });
+    const c = d.creative || d;
+    const text = `Concept (${c.format}${c.recipe_label ? ' · ' + c.recipe_label : ''}): "${c.concept}"\nHeadline: ${c.copy?.[0]?.headline || ''}\nRender model: ${c.format === 'video' ? c.vmodel : c.imodel || '—'}. Next: ${c.format === 'video' ? 'call render_ad with THIS ENTIRE creative object (Studio quality pipeline; a ≤15s storyboard renders as ONE single-pass clip — don’t stitch)' : 'generate_image with the image_concept.prompt'}.`;
+    return ok(text, c);
+  }));
+
+  // ---------- image (synchronous) ----------
+  server.registerTool('generate_image', {
+    description: 'Render a finished ad IMAGE and return its served URL. refImages (local paths or URLs) force product-accurate compositing (drops a real product into the scene). model = a catalog id from hermoso_capabilities (omit for the default). Fast (seconds). Spends credits.',
+    inputSchema: {
+      prompt: z.string().describe('the full image prompt — subject, composition, lighting, and any on-image ad text'),
+      refImages: z.array(z.string()).optional().describe('local file paths or URLs of product/logo references to composite in'),
+      aspectRatio: z.string().optional().describe("e.g. '1:1', '9:16', '16:9'"),
+      model: z.string().optional().describe('image model id from hermoso_capabilities'),
+      imageSize: z.string().optional(),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async ({ prompt, refImages, aspectRatio, model, imageSize }) => {
+    const refs = refImages?.length ? (await Promise.all(refImages.map(toRef))).filter(Boolean) : undefined;
+    const d = await apiPost('/api/generate/image', { prompt, refImages: refs, aspectRatio, model, imageSize });
+    const img = await imageBlock(abs(d.image)); // show the actual creative inline in Claude, not just a URL
+    return { content: [{ type: 'text', text: `Image ready: ${abs(d.image)}${d.model ? `  (${d.model})` : ''}` }, ...(img ? [img] : [])], structuredContent: { ...d, image: abs(d.image) } };
+  }));
+
+  // ---------- video / avatar / stitch (job-based, polled to completion) ----------
+  server.registerTool('render_ad', {
+    description: 'RECOMMENDED for finished video ADS: render a plan_ad concept through the SAME quality pipeline as the Hermoso web Studio — timed shot list, exact/clean speech (no garbled words), text composited in post (never model-painted), brand end card, licensed music bed, real product references. Pass plan_ad’s full structured output as `creative`. Renders take 1–3 min; keep polling get_job if it returns still-rendering. Spends credits.',
+    inputSchema: {
+      creative: z.object({}).passthrough().describe('the FULL structured output of plan_ad (must contain video_storyboard)'),
+      model: z.string().optional().describe('video model id from hermoso_capabilities (default: the plan’s pick)'),
+      durationSeconds: z.number().optional(),
+      aspectRatio: z.string().optional(),
+      resolution: z.string().optional().describe("'720p' (default) or '1080p'"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const { input, notes } = await apiPost('/api/render/assemble', a);
+    const r = await renderJob('video', input, 'MCP ad render');
+    return okVideo(`Ad video ready: ${r.url}${r.model ? `  (${r.model})` : ''}  [job ${r.jobId}]\n${notes || ''}`, r);
+  }));
+
+  server.registerTool('generate_video', {
+    description: 'Render a RAW video clip from your own prompt and return its served mp4 URL. For finished brand ADS prefer render_ad (it runs the Studio quality pipeline — composited text, clean speech, end card, music); use this for raw/experimental clips or precise manual control. ONE generation = one continuous clip up to the model’s longest listed duration (seedance-2 goes to 15s single-pass with a full multi-beat arc — never assume a generic 8–10s cap); durationSeconds must be one of the model’s durations from hermoso_capabilities. Renders take 1–3 min. refImage anchors the opening frame; ttsScript adds a voiceover. Spends credits (Starter plan is video-blocked server-side).',
+    inputSchema: {
+      prompt: z.string().describe('the video prompt / shot description'),
+      refImage: z.string().optional().describe('local path or URL to anchor the first frame'),
+      durationSeconds: z.number().optional().describe('clip length in seconds'),
+      aspectRatio: z.string().optional().describe("default '9:16'"),
+      model: z.string().optional(),
+      resolution: z.string().optional().describe("'720p' (default) or '1080p'"),
+      ttsScript: z.string().optional().describe('voiceover script to speak'),
+      ttsVoice: z.string().optional().describe('voice name, e.g. Rachel / George'),
+      musicMood: z.string().optional(),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const refImage = a.refImage ? await toRef(a.refImage) : undefined;
+    const r = await renderJob('video', { ...a, refImage }, 'MCP video');
+    return okVideo(`Video ready: ${r.url}${r.model ? `  (${r.model})` : ''}  [job ${r.jobId}]`, r);
+  }));
+
+  server.registerTool('generate_avatar', {
+    description: 'Render a TALKING-AVATAR / creator lip-sync clip from a portrait image + a script. Blocks until done (1–3 min). Requires the avatar capability (canAvatar in hermoso_capabilities). Spends credits.',
+    inputSchema: {
+      image: z.string().describe('local path or URL of the presenter portrait'),
+      script: z.string().describe('the words the avatar speaks'),
+      voice: z.string().optional().describe('voice name (Rachel/Sarah/George/Adam)'),
+      resolution: z.string().optional().describe("'720p' (default) or '480p' draft"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const image = await toRef(a.image);
+    const r = await renderJob('avatar', { ...a, image }, 'MCP avatar');
+    return okVideo(`Avatar clip ready: ${r.url}  [job ${r.jobId}]`, r);
+  }));
+
+  server.registerTool('stitch_video', {
+    description: 'Render a multi-scene STITCHED video (≥2 scenes) — ONLY for spots LONGER than one model clip (>15s). A ≤15s multi-beat ad renders better and cheaper as ONE single-pass generate_video/render_ad on seedance-2 (it handles the full hook→demo→payoff arc in one take) — never stitch those. Blocks until done. Spends credits.',
+    inputSchema: {
+      scenes: z.array(z.object({}).passthrough()).min(2).describe('array of scene objects (visual + optional voiceover/seconds)'),
+      aspectRatio: z.string().optional(),
+      voiceover: z.string().optional(),
+      voice: z.string().optional(),
+      resolution: z.string().optional(),
+      model: z.string().optional(),
+      durationSeconds: z.number().optional(),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    // HARD GUARD (Dave watched an agent stitch a 15s ad into 4 separate renders): a spot that fits ONE Seedance
+    // clip renders single-pass through the Studio assembly instead — no seams, exact multi-beat arc, ~1/4 the cost.
+    // The agent's scene list becomes the storyboard; its voiceover lines ride the same exactness rails.
+    const total = +a.durationSeconds || (a.scenes || []).reduce((s, x) => s + (+x.seconds || 4), 0);
+    if (total <= 15) {
+      try {
+        const { input } = await apiPost('/api/render/assemble', {
+          creative: { recipe: '', copy: [], video_storyboard: { scenes: a.scenes, cta: '', music: '' } },
+          durationSeconds: total, aspectRatio: a.aspectRatio, resolution: a.resolution,
+        });
+        if (a.voiceover && !input.ttsScript) { input.ttsScript = String(a.voiceover); if (a.voice) input.ttsVoice = String(a.voice); }
+        const r = await renderJob('video', input, 'MCP ad render (single-pass)');
+        return okVideo(`Rendered as ONE single-pass ${input.durationSeconds}s clip instead of stitching (this length fits a single generation — cleaner cuts, exact script, far fewer credits): ${r.url}  [job ${r.jobId}]`, r);
+      } catch (e) { console.error('[mcp] single-pass collapse failed, falling back to stitch:', String(e?.message || e).slice(0, 140)); }
+    }
+    const r = await renderJob('stitch', a, 'MCP stitch');
+    return okVideo(`Stitched video ready: ${r.url}  [job ${r.jobId}]`, r);
+  }));
+
+  server.registerTool('get_job', {
+    description: 'Poll a render job by id. Returns status (queued|running|done|error), progress, and on done the served media URL. Renders take 1–3 minutes: keep calling this until done/error without asking the user — several calls is normal, not a stall.',
+    inputSchema: { id: z.string().describe('the job id, e.g. job_xxx') },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  }, wrap(async ({ id }) => {
+    const j = await getJob(id);
+    const res = jobResult(j);
+    const url = abs(res?.video || res?.image || res?.url);
+    const text = `Job ${id}: ${j.status}${j.progress ? ` (${Math.round(j.progress * 100)}%)` : ''}${url ? ` → ${url}` : ''}${j.error ? ` — ${j.error}` : ''}`;
+    if (j.status === 'done' && res?.video) return okVideo(text, { ...j, url }); // resumed video → same inline poster as a direct return
+    if (j.status === 'done' && res?.image) { const img = await imageBlock(url); return { content: [{ type: 'text', text }, ...(img ? [img] : [])], structuredContent: { ...j, url } }; }
+    return ok(text, { ...j, url });
+  }));
+
+  // ---------- skills (Higgsfield get_workflow_instructions parity: workflows ship as SKILL.md bundles) ----------
+  server.registerTool('list_skills', {
+    description: 'List the bundled Hermoso SKILLS — multi-step workflow instructions (SKILL.md) that orchestrate the other tools (research an ad space, plan+render a finished ad, product photoshoot, raw generation) — plus the in-app strategy skills and creative recipes. Call get_skill to load a bundle. Read-only, free.',
+    inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: false },
+  }, wrap(async () => {
+    const { readdir, readFile } = await import('node:fs/promises');
+    const dir = new URL('../skills/', import.meta.url);
+    let bundles = [];
+    try {
+      const names = await readdir(dir);
+      bundles = (await Promise.all(names.map(async (n) => {
+        try {
+          const md = await readFile(new URL(`../skills/${n}/SKILL.md`, import.meta.url), 'utf8');
+          const desc = (/description:\s*>?-?\s*\n?([\s\S]*?)\n[a-z_-]+:/.exec(md)?.[1] || '').replace(/\s+/g, ' ').trim().slice(0, 220);
+          return { name: n, description: desc };
+        } catch { return null; }
+      }))).filter(Boolean);
+    } catch {}
+    const d = await apiGet('/api/skills').catch(() => ({ skills: [] }));
+    const inApp = (d.skills || []).map(s => `${s.id} (${s.kind || s.group})`).join(', ');
+    const text = `Skill bundles (call get_skill with the name):\n${bundles.map(b => `- ${b.name}: ${b.description}`).join('\n') || '(none bundled)'}\n\nIn-app strategy skills + creative recipes (pass as plan_ad's recipe / create's skill): ${inApp}`;
+    return ok(text, { bundles, inApp: d.skills || [] });
+  }));
+
+  server.registerTool('get_skill', {
+    description: 'Load a bundled skill’s full SKILL.md workflow instructions by name (from list_skills). Follow the loaded instructions to run that workflow with the other tools. Read-only, free.',
+    inputSchema: { name: z.string().describe('bundle name from list_skills, e.g. hermoso-generate') },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  }, wrap(async ({ name }) => {
+    const safe = String(name).replace(/[^a-z0-9-]/gi, '');
+    const { readFile } = await import('node:fs/promises');
+    const md = await readFile(new URL(`../skills/${safe}/SKILL.md`, import.meta.url), 'utf8').catch(() => null);
+    if (!md) return { content: [{ type: 'text', text: `No skill bundle named "${safe}" — call list_skills for the catalog.` }], isError: true };
+    return ok(md.slice(0, 24000), { name: safe });
+  }));
+
+  server.registerTool('list_jobs', {
+    description: 'List the most recent render jobs + how many are currently running, so you can report on or resume in-flight work.',
+    inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: false },
+  }, wrap(async () => {
+    const d = await apiGet('/api/jobs');
+    const lines = (d.jobs || []).slice(0, 12).map(j => `${j.id} ${j.type} ${j.status}`).join('\n');
+    return ok(`${d.running} running. Recent:\n${lines}`, d);
+  }));
+
+  // ---------- research / discovery ----------
+  server.registerTool('find_competitors', {
+    description: "Discover a brand's competitor / similar / adjacent brands from its domain (Claude grounded by web search). mode=competitors (default, excludes the searched company), inspiration (best relevant ads incl. it), or company. 0 ScrapeCreators credits.",
+    inputSchema: {
+      domain: z.string().describe('the brand domain, e.g. yourbrand.com'),
+      mode: z.enum(['competitors', 'inspiration', 'company']).optional(),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ domain, mode = 'competitors' }) => {
+    const d = await apiPost('/api/inspire/competitors', { domain, mode });
+    const list = (d.candidates || []).map(c => `${c.name} (${c.domain || '—'}, ${c.kind})`).join('; ');
+    return ok(`Found ${d.candidates?.length || 0}: ${list}`, d);
+  }));
+
+  server.registerTool('pull_competitor_ads', {
+    description: 'Pull a brand\'s real running ads across Meta / Google / LinkedIn ad libraries (deduped, sorted, right page resolved). Spends ScrapeCreators credits.',
+    inputSchema: {
+      companyName: z.string().optional().describe('the advertiser name'),
+      domain: z.string().optional().describe('the advertiser domain'),
+      platforms: z.array(z.string()).optional().describe("default ['facebook']; add 'google','linkedin'"),
+      country: z.string().optional().describe("2-letter, default 'US'"),
+      limit: z.number().optional(),
+      sort: z.string().optional().describe("'longest_running' (default) etc."),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/inspire/fanout', { platforms: ['facebook'], country: 'US', limit: 30, sort: 'longest_running', ...a });
+    return ok(`Pulled ads for ${a.companyName || a.domain}.`, d);
+  }));
+
+  server.registerTool('research_ads', {
+    description: 'Natural-language ad research: a Claude tool-use loop over Meta/Google/LinkedIn ad libraries + organic TikTok. Returns a summary + the found ads (with their served URLs). Spends LLM tokens + ScrapeCreators credits.',
+    inputSchema: {
+      query: z.string().describe('what to research, e.g. "the longest-running protein-pancake ads on Meta"'),
+      brand: z.union([z.string(), z.object({}).passthrough()]).optional(),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ query, brand }) => {
+    const brandObj = typeof brand === 'string' ? { name: brand } : brand || null;
+    const d = await apiSSE('/api/explore/chat', { messages: [{ role: 'user', content: query }], brand: brandObj });
+    return ok(`${d.reply || ''}\n\n(${(d.results || []).length} ads found)`, { reply: d.reply, results: d.results, actions: d.actions });
+  }));
+
+  // ---------- brand onboarding ----------
+  server.registerTool('get_brand', {
+    description: 'What Hermoso ALREADY KNOWS for this account/workspace — the same saved brand profile (products, logos, palette, positioning) + learned memory the web Studio uses. Call this FIRST: if hasBrand is true you can omit brand everywhere; if false, onboard with draft_brand. 0 credits.',
+    inputSchema: {},
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+  }, wrap(async () => {
+    const d = await apiGet('/api/brand/current');
+    const text = d?.hasBrand
+      ? `Saved brand: ${d.brand.name || d.brand.domain}${d.brand.category ? ' · ' + d.brand.category : ''} · ${d.memoryCount} learned memory notes. plan_ad / plan_variations / create use it automatically when you omit brand.`
+      : 'No saved brand for this workspace yet — onboard one with draft_brand (it saves automatically), or the user can onboard in the web Studio.';
+    return ok(text, d);
+  }));
+
+  server.registerTool('draft_brand', {
+    description: 'Onboard a brand profile — from a website domain, a free-text description, or a social handle — into a {name, products, logo, …} object you can pass to plan_ad / generate. 0 ScrapeCreators credits.',
+    inputSchema: {
+      domain: z.string().optional().describe('a website to scrape'),
+      description: z.string().optional().describe('a free-text brand description (no website)'),
+      socialHandle: z.string().optional(),
+      platform: z.string().optional().describe('platform for socialHandle (instagram/tiktok/…)'),
+      save: z.boolean().optional().describe('save as the workspace’s brand (like Studio onboarding) so plan_ad/create use it automatically. Default: saves only when NO brand is saved yet; pass true to overwrite, false to never save'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async ({ save, ...a }) => {
+    const d = await apiPost('/api/brand/draft', a);
+    const p = d.profile || d;
+    let saved = false;
+    if (save !== false) {
+      try {
+        const cur = save === true ? null : await apiGet('/api/brand/current').catch(() => null);
+        if (save === true || !cur?.hasBrand) {
+          const bk = PROFILE !== 'default' ? `heist.brand.v1.${PROFILE}` : 'heist.brand.v1'; // mirror the webapp's per-profile key namespacing
+          await apiPut(`/api/store/${encodeURIComponent(bk)}`, { value: JSON.stringify(p) });
+          saved = true;
+        }
+      } catch {} // saving is best-effort — the drafted profile is still returned either way
+    }
+    return ok(`Drafted brand: ${p.name || '—'}${p.category ? ' · ' + p.category : ''}.${saved ? ' Saved as the workspace brand — plan_ad/create now use it automatically.' : ' Pass this object to plan_ad.'}`, p);
+  }));
+
+  // ---------- assets ----------
+  server.registerTool('fetch_asset', {
+    description: 'Resolve a generated asset reference (a /generated/… path or any URL) to a clickable absolute URL + a direct download URL.',
+    inputSchema: { url: z.string().describe('the asset url or /generated/ path'), name: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  }, wrap(async ({ url, name }) => {
+    const absolute = abs(url);
+    const dl = `${API_BASE}/api/download?url=${encodeURIComponent(url)}${name ? `&name=${encodeURIComponent(name)}` : ''}`;
+    return ok(`Asset: ${absolute}\nDownload: ${dl}`, { url: absolute, downloadUrl: dl });
+  }));
+
+  // ---------- post-production & analysis (Higgsfield-parity wave: each wraps an EXISTING worker/route) ----------
+  server.registerTool('analyze_video', {
+    description: "Break a video ad down into its structure: the verbatim transcript (voiceover + on-screen text) with a beat list, plus duration and sampled frame timestamps. Use to study a reference/competitor ad before remixing its structure. Costs ~a transcription call; no ScrapeCreators credits.",
+    inputSchema: { url: z.string().describe('the video URL (a served /generated/ path or a public http(s) video)') },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ url }) => {
+    const [fr, tr] = await Promise.all([
+      apiGet(`/api/video/frames?n=auto&url=${encodeURIComponent(url)}`).catch(() => null),
+      apiGet(`/api/video/transcript?url=${encodeURIComponent(url)}`).catch(() => null),
+    ]);
+    const dur = fr?.durationSeconds, times = fr?.times || [];
+    const transcript = tr?.transcript || '(no transcript — the video may be silent or unreachable)';
+    return ok(`Duration: ${dur ? Math.round(dur) + 's' : 'unknown'} · frames sampled at: ${times.map(t => Math.round(t * 10) / 10 + 's').join(', ') || 'n/a'}\n\nTranscript & beats:\n${transcript}`, { durationSeconds: dur, frameTimes: times, transcript: tr?.transcript || null });
+  }));
+
+  server.registerTool('score_ad', {
+    description: "Virality/performance prediction for a finished ad (image or video URL): overall score, per-dimension breakdown (scroll-stop, hook, clarity, brand/product, CTA, retention, goal fit), strengths, and the single biggest fix. Use BEFORE spending on distribution, or to rank variants.",
+    inputSchema: {
+      url: z.string().describe('the ad asset URL (a /generated/ path or public URL)'),
+      kind: z.enum(['image', 'video']).optional(),
+      intent: z.string().optional().describe('what the ad is trying to achieve, for goal-fit scoring'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ url, kind = 'image', intent = '' }) => {
+    const d = await apiPost('/api/score/ad', { url, kind, intent, format: kind });
+    if (!d) return ok('Could not score that ad.');
+    const dims = (d.dimensions || []).map(x => `${x.name}: ${x.score}`).join(' · ');
+    return ok(`Overall ${d.overall}/100 (${d.tier || ''})\n${dims}\nBiggest lever: ${d.top_fix || '—'}`, d);
+  }));
+
+  server.registerTool('reframe_video', {
+    description: "Reframe a video to a different aspect ratio (e.g. 16:9 master → 9:16 vertical) with smart subject tracking. Paid render; returns the served URL of the reframed video.",
+    inputSchema: { video: z.string().describe('the source video URL'), aspectRatio: z.enum(['9:16', '1:1', '16:9']).describe('the target aspect ratio') },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async ({ video, aspectRatio }) => {
+    const r = await renderJob('reframe', { video, aspectRatio }, `Reframe → ${aspectRatio}`);
+    return okVideo(`Reframed video (${aspectRatio}): ${r.url}`, r);
+  }));
+
+  server.registerTool('upscale_video', {
+    description: "Upscale a video to higher resolution (2x) for final delivery. Paid render; returns the served URL.",
+    inputSchema: { video: z.string().describe('the source video URL') },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async ({ video }) => {
+    const r = await renderJob('upscale', { video, factor: 2 }, 'Upscale 2x');
+    return okVideo(`Upscaled video: ${r.url}`, r);
+  }));
+
+  server.registerTool('dub_video', {
+    description: "Remake a finished video ad's voiceover in another language (translated script, re-voiced, re-muxed). Paid; returns the served URL of the localized video.",
+    inputSchema: {
+      video: z.string().describe('the source video URL'),
+      language: z.string().describe("target language, e.g. 'Spanish', 'de', 'French (Canada)'"),
+      script: z.string().optional().describe('the original spoken script if known — improves translation fidelity'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async ({ video, language, script }) => {
+    const r = await renderJob('dub', { video, language, script: script || '' }, `Dub → ${language}`);
+    return okVideo(`Localized video (${language}): ${r.url}`, r);
+  }));
+
+  server.registerTool('recast_motion', {
+    description: "Motion transfer: re-perform a reference video's motion with a different person/character (supply their image). The reference clip drives the movement; the image supplies the identity. Paid render.",
+    inputSchema: {
+      image: z.string().describe("the actor/character image URL (who should appear)"),
+      video: z.string().describe('the reference video whose motion to re-perform'),
+      prompt: z.string().optional().describe('optional scene/style guidance'),
+      orientation: z.enum(['video', 'image']).optional().describe("which aspect to keep: the video's (default) or the image's"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async ({ image, video, prompt = '', orientation = 'video' }) => {
+    const r = await renderJob('motion', { image, video, prompt, orientation }, 'Motion recast');
+    return okVideo(`Recast video: ${r.url}`, r);
+  }));
+
+  server.registerTool('plan_variations', {
+    description: "Fan a brief into N DISTINCT ad angles (different hooks/mechanics/audiences), each with its own headline + visual brief — then render each with generate_image and rank with score_ad. LLM planning only; renders nothing itself.",
+    inputSchema: {
+      brand: z.union([z.string(), z.object({}).passthrough()]).optional().describe('brand name or profile object; OMIT to use the workspace’s saved brand'),
+      product: z.string().describe('what to advertise'),
+      count: z.number().int().min(2).max(8).optional().describe('how many distinct variants (default 6)'),
+      language: z.string().optional(),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+  }, wrap(async ({ brand, product, count = 6, language }) => {
+    const brandObj = brand ? (typeof brand === 'string' ? { name: brand } : brand) : null;
+    const d = await apiPost('/api/batch/plan', { brand: brandObj, product, count, language: language || '' });
+    const vars = d?.variants || d?.angles || [];
+    const text = vars.map((v, i) => `${i + 1}. ${v.name || v.angle || 'Variant'} — ${v.hook || v.headline || ''}`).join('\n') || 'No variants returned.';
+    return ok(text, d);
+  }));
+}

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "hermoso",
+  "version": "0.1.0",
+  "description": "Drive Hermoso — the AI ad studio — from any AI agent: MCP server, CLI, and Claude skills for researching winning ads and generating finished image & video ads.",
+  "type": "module",
+  "bin": { "hermoso": "bin/hermoso.mjs" },
+  "scripts": { "mcp": "node mcp/hermoso-mcp.mjs" },
+  "dependencies": { "@modelcontextprotocol/sdk": "^1.12.0" },
+  "keywords": ["mcp", "model-context-protocol", "ai-ads", "ad-generator", "ugc", "claude", "cli", "video-ads"],
+  "homepage": "https://hermoso.ai",
+  "repository": { "type": "git", "url": "https://github.com/hermoso-ai/hermoso.git" },
+  "license": "MIT",
+  "author": "Hermoso <hello@hermoso.ai>"
+}

package/skills/hermoso-ad-from-brand/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: hermoso-ad-from-brand
+description: >-
+  Make a finished, on-brand ad for a company end-to-end with Hermoso: onboard the brand, write the concept +
+  copy, then render the image or video. Use when the user says "make an ad for <company/website>", "build a
+  launch ad for my brand", or gives a domain/brand and wants a complete ad, not just research. NOT for: just
+  pulling competitor ads (use hermoso-research) or rendering from a prompt you already have (use hermoso-generate).
+argument-hint: "[brand or website + what to advertise — e.g. 'an ad for yourbrand.com — our best-selling olive oil']"
+allowed-tools: Bash
+---
+
+# Hermoso — full ad from a brand
+
+Drive the **Hermoso CLI** to go from a brand to a finished ad in three steps. Report the final media URL.
+
+## Setup
+- `hermoso version` to confirm the CLI; `hermoso auth login --url https://app.hermoso.ai --token <your key>` (create one under MCP & CLI).
+
+## Procedure
+1. **Onboard the brand** (skip if the user already gave full brand details):
+   - From a website: `hermoso brand draft --domain <domain> --json`
+   - No website: `hermoso brand draft --description "<what they sell, audience, voice>" --json`
+   - Influencer/social: `hermoso brand draft --social <handle> --platform instagram --json`
+   Keep the returned brand name/category for the next steps.
+2. **Plan the concept + copy:** `hermoso create --brand "<name>" --product "<what to advertise + angle>" --format <auto|image|video> --json`
+   - Read the result: it has the `concept`, `copy[]` (headline/primary/cta), and the resolved **render model id** (`imodel` for images, `vmodel` for video). Tell the user the concept + headline.
+3. **Render**, using the model the create step resolved (or run `hermoso capabilities` for options):
+   - Image: `hermoso generate image --prompt "<image_concept.prompt from step 2 — it already bakes in the copy>" --model <imodel> --aspect 1:1`
+   - Video: `hermoso generate video --prompt "<from the storyboard>" --model <vmodel> --aspect 9:16 --duration 8 --wait`
+4. **Report the served URL.** Offer one concrete next step (a punchier hook, a different aspect ratio, or a variation).
+
+## Notes
+- If the brand has a real product photo and the ad features that product, pass it with `--ref ./product.png` on the image step so the packaging is accurate.
+- Quality over cost: prefer the resolved/best model unless the user asks for cheap/fast.
+- Everything runs against the local Hermoso server; no asset leaves the machine unless you `hermoso fetch` it.

package/skills/hermoso-generate/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: hermoso-generate
+description: >-
+  Generate on-brand ad creative with Hermoso — images, videos, talking-avatar clips, and multi-scene
+  stitched videos — from a prompt, returning a served media URL. Use when the user asks to "generate /
+  make / render an image or video ad", "create an ad", "make a product shot", "make a UGC video", or to
+  turn a concept into finished creative with Hermoso. NOT for: pure research/competitor lookups (use
+  hermoso-research), or editing an existing local image with a non-Hermoso tool.
+argument-hint: "[what to generate — e.g. 'a 9:16 video ad for our protein pancakes']"
+allowed-tools: Bash
+---
+
+# Hermoso — generate ad creative
+
+You drive the **Hermoso CLI** (`hermoso`) to render images and videos. Always report the final **media URL**.
+
+## Setup (once)
+1. Ensure the CLI is available. From the Hermoso repo: `node bin/hermoso.mjs version` (or `hermoso version` if globally installed via `npm i -g`).
+2. `hermoso auth login --url https://app.hermoso.ai --token <your agent key>` — create a key in the app under **MCP & CLI**. (Self-running the app? Use `--url http://localhost:3000`, no token.)
+
+## Procedure
+1. **Always run `hermoso capabilities` first.** It lists the valid image/video **model ids**, their credit costs, aspect ratios, video durations, and the recipe ids. Never guess a model id.
+2. Pick a **high-quality default** (quality over cost is the house rule): for images prefer the model marked `★best` (e.g. `nano-banana-pro`); for product composites pass the real product image with `--ref`. For video, use a featured model and a sensible duration.
+3. Generate:
+   - Image: `hermoso generate image --prompt "<full prompt incl. any on-image text>" [--ref ./product.png] [--model <id>] [--aspect 1:1]`
+   - Video: `hermoso generate video --prompt "<shot description>" [--ref ./frame.png] [--duration 8] [--aspect 9:16] [--model <id>] [--tts "<voiceover>"] [--voice Rachel] --wait`
+   - Avatar (lip-sync): `hermoso generate avatar --image ./face.png --script "<words>" [--voice George] --wait`
+   - Stitch (≥2 scenes): `hermoso generate stitch --scenes scenes.json --wait`
+4. Video/avatar/stitch are **job-based** — keep `--wait` (default) so the command blocks and prints the final URL. If you don't wait, poll with `hermoso jobs get <id> --wait`.
+5. **Report the served URL** (e.g. `https://assets.hermoso.ai/…`), never a raw job id. If the user wants the file, `hermoso fetch <url> --out name.png`.
+
+## Notes
+- `--ref` accepts local file paths (read + sent as data) or URLs; a real product/logo ref makes the output product-accurate.
+- Add `--json` to any command for machine-readable output.
+- If a render fails or times out, the error explains why; surface it plainly and offer to retry or pick a cheaper/faster model from `hermoso capabilities`.

package/skills/hermoso-product-photoshoot/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: hermoso-product-photoshoot
+description: >-
+  Brand-quality product photography with Hermoso: drop a real product photo into studio, lifestyle, or hero-banner
+  scenes via reference-image compositing, so the packaging/label stays accurate. Use when the user wants
+  "product shots", "a photoshoot for my product", "lifestyle images of <product>", "hero banner", or "a pack of
+  ad images" from a real product image. NOT for: video (use hermoso-generate) or research (use hermoso-research).
+argument-hint: "[product image + scene — e.g. './bag.png as a sunlit kitchen hero shot']"
+allowed-tools: Bash
+---
+
+# Hermoso — product photoshoot
+
+Use Hermoso's reference-image compositing so the real product (label, colours, shape) is preserved while the
+scene around it is generated. Drive the **Hermoso CLI**.
+
+## Setup
+- `hermoso auth login --url https://app.hermoso.ai --token <your agent key>` (key from the app’s MCP & CLI page); run `hermoso capabilities` once to see image model ids + recipes.
+
+## Procedure
+1. Get the **product image** path/URL from the user. This is the `--ref` — it forces product-accurate compositing.
+2. Pick a **mode** and write the prompt accordingly (compose for ads — off-center hero, depth, directional light, negative space for copy):
+   - `product_shot` — clean studio packshot on a seamless backdrop.
+   - `lifestyle_scene` — the product in a real in-use setting (kitchen, desk, outdoors).
+   - `hero_banner` — wide banner composition with room for a headline.
+   - `social_carousel` — several angles/scenes of the same product (run the command N times with varied prompts).
+   - `ad_creative_pack` — a few finished ad images with on-image copy.
+3. Render: `hermoso generate image --prompt "<scene + composition + any on-image text>" --ref <product image> [--model <id>] [--aspect 1:1|4:5|16:9]`
+   - Prefer the `★best` image model for hero work; a faster model is fine for bulk variations.
+4. For a **pack**, loop: vary the scene/angle/aspect per call, collect the URLs, and present them together.
+5. Report each served image URL; offer to `hermoso fetch` them to disk or to tweak a scene.
+
+## Notes
+- Keep the product as the hero; never let generated text garble the real label — describe the product as "the exact product in the reference, label unchanged."
+- `--ref` takes a local path (read + sent) or a URL.

package/skills/hermoso-research/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: hermoso-research
+description: >-
+  Competitor + ad-library intelligence with Hermoso: find a brand's competitors, pull their real running ads
+  across Meta/Google/LinkedIn, and surface the winning hooks/angles worth copying. Use when the user asks to
+  "find my competitors", "pull <brand>'s ads", "what ads are working in my niche", "research the longest-running
+  ads", or wants proven creative to remix. NOT for: generating creative (use hermoso-generate / hermoso-ad-from-brand).
+argument-hint: "[a brand/domain or a research question — e.g. 'longest-running protein-pancake ads']"
+allowed-tools: Bash
+---
+
+# Hermoso — competitor & ad research
+
+This is Hermoso's discovery half (which most generators don't have). Drive the **Hermoso CLI**.
+
+## Setup
+- `hermoso auth login --url https://app.hermoso.ai --token <your agent key>` (key from the app’s MCP & CLI page).
+
+## Procedure
+Pick the tool that fits the ask:
+1. **Find competitors** for a domain: `hermoso competitors <domain> [--mode competitors|inspiration|company] --json`
+   - `competitors` = head-to-head rivals; `inspiration` = best relevant ads incl. the brand itself; `company` = the company's own.
+2. **Pull a brand's real ads** across ad libraries: `hermoso ads pull --company "<name>" [--domain <d>] [--platforms facebook,google,linkedin] [--country US] --json`
+   - Defaults to Meta (richest library). Add google/linkedin only if asked (Google detailed pulls cost more).
+3. **Natural-language research** (Claude tool-use over ad libraries + organic TikTok): `hermoso research "<request>"`
+   - e.g. `hermoso research "the longest-running protein-pancake ads on Meta and what hooks they use"`. Prints a summary + the found ads with their URLs.
+4. **Synthesize**: report the strongest hooks, angles, formats, and what's worth copying — be specific (quote the actual headlines/angles). If the user then wants to build one, hand off to `hermoso-ad-from-brand` / `hermoso-generate`.
+
+## Notes
+- Research spends ScrapeCreators credits (ad-library calls) + LLM tokens; keep platform scope to what's asked.
+- Add `--json` for the raw ad objects (URLs, copy, run dates) when the user wants the data, not a summary.