hermoso 0.1.253 → 0.1.254

package/README.md

@@ -30,6 +30,51 @@ ad-build tool accepts); build and read campaigns on your own ad accounts with yo
 competitors with no brand drafted and no channel connected; or generate a file with nothing connected at all and
 just download it. Use the one piece you need, or all of it together.
 
+## Install in one command
+
+This repo is a plugin marketplace, a Gemini CLI extension and a skills package at once, so a coding agent takes
+Hermoso in one line. Every install brings the same four skills (`hermoso-research`, `hermoso-generate`,
+`hermoso-ad-from-brand`, `hermoso-product-photoshoot`), and the skills drive the `hermoso` CLI through `npx`. No
+tool list is loaded into your session: a CLI command costs nothing until it runs, and it reaches every tool.
+The first time, your agent runs `npx -y hermoso auth login`, which opens a browser to sign in.
+
+**Claude Code:**
+
+```bash
+claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso
+```
+
+Inside a session the same thing is `/plugin marketplace add hermoso-ai/hermoso` then `/plugin install hermoso@hermoso`.
+
+**Codex CLI** (it reads the same marketplace file):
+
+```bash
+codex plugin marketplace add hermoso-ai/hermoso && codex plugin add hermoso@hermoso
+```
+
+**Gemini CLI:**
+
+```bash
+gemini extensions install https://github.com/hermoso-ai/hermoso
+```
+
+**Cursor, OpenCode, GitHub Copilot, Windsurf and about 75 more agents**, through the open skills installer:
+
+```bash
+npx skills add hermoso-ai/hermoso
+```
+
+It asks which agents to install into; `-a opencode` (or `cursor`, `github-copilot`, `windsurf`) picks one, and
+`--skill hermoso-research` installs a single skill. VS Code agent plugins can also take this repo whole: run
+**Chat: Install Plugin From Source** and paste `https://github.com/hermoso-ai/hermoso`.
+
+**ChatGPT and Claude.ai** run in a browser and cannot run a CLI, so they use the hosted connector instead (see
+below). The ChatGPT desktop app and ChatGPT workspace admins can also read this repo's
+`.claude-plugin/marketplace.json`, which installs the skills.
+
+No browser on the machine? Create a key in the app under **MCP & CLI** and run
+`npx -y hermoso auth login --token <key>`.
+
 ## Which surface should your agent use?
 
 Two shapes, and the right one is decided by **what your client can do**, not by which we prefer.
@@ -315,6 +360,8 @@ the package, so they need no key, no network and no sign-in.
 `skills/` holds four installable skills: `hermoso-generate`, `hermoso-ad-from-brand`,
 `hermoso-product-photoshoot`, `hermoso-research`.
 
+The quickest way in is the one-command install at the top of this page. From a clone, copying works too:
+
 ```bash
 cp -r skills/* ~/.claude/skills/
 ```

package/mcp/tools.mjs

@@ -3419,7 +3419,10 @@ function buildTools(rawServer, opts = {}, sink = null) {
     const _pickLine = 'NAMING A MODEL IS HOW YOU GET ONE: a render that passes no `model` is routed by the server\'s own auto-pool, which is deliberately NARROWER than this catalog — the `best` flag and the longest-clip row do NOT decide it. If you need a particular model\'s length, resolution, audio or reference-count capability, pass its id in `model`; that is a deliberate pick and the server will not swap it without telling you.';
     // RESOLUTION IS PER MODEL, and asking outside the list is not an error — it is a quiet downgrade.
     const _resLine = 'RESOLUTION: each model\'s `resolutions` list is its REAL enum (and `creditsByRes` prices every tier). Ask for a tier a model does not list and the render is delivered at that model\'s best available tier instead — the reply does not say so — so read `resolutions` here before promising anyone 1080p or 4k.';
-    const text = `Image: ${d.image ? img : 'unavailable'}\nVideo: ${d.video ? vid : 'unavailable'}\n${_lenLine}\n${_pickLine}\n${_resLine}\nVoice engines (generate_voice): ${voice}\nWriting models (generate_text): ${llm}\ncanEdit:${d.canEdit} canAvatar:${d.canAvatar}\nRecipes (${(d.recipes || []).length}): ${(d.recipes || []).slice(0, 20).map(r => r.id).join(', ')}…\n\n${CAPABILITY_MAP}`;
+    // recast_motion's two tiers, priced off the same live quote the app's costs page reads (toolExamples), never a number here.
+    const _mq = (q) => (q ? Object.entries(q).map(([s, c]) => `${s}s=${c}cr`).join(' ') : null);
+    const _motionLine = _mq(d.toolExamples?.motion) ? `\nRecast motion (recast_motion, billed per output second): tier pro (default) ${_mq(d.toolExamples.motion)}${_mq(d.toolExamples.motionStandard) ? `; tier standard ${_mq(d.toolExamples.motionStandard)}` : ''}` : '';
+    const text = `Image: ${d.image ? img : 'unavailable'}\nVideo: ${d.video ? vid : 'unavailable'}\n${_lenLine}\n${_pickLine}\n${_resLine}${_motionLine}\nVoice engines (generate_voice): ${voice}\nWriting models (generate_text): ${llm}\ncanEdit:${d.canEdit} canAvatar:${d.canAvatar}\nRecipes (${(d.recipes || []).length}): ${(d.recipes || []).slice(0, 20).map(r => r.id).join(', ')}…\n\n${CAPABILITY_MAP}`;
     return ok(text + connLine, d);
   }));
 
@@ -19152,17 +19155,18 @@ function memoryNoteVerdict(text) {
 
   server.registerTool('recast_motion', {
     title: '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.",
+    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, billed per output second (the output is as long as the reference clip, 3-30s); a 5s clip takes about 5 minutes. Runs on the Pro tier by default: 1080p, and the person really handles the object the reference performer handles.",
     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"),
+      tier: z.enum(['pro', 'standard']).optional().describe("'pro' (default): 1080p and real hand-object interaction. 'standard': about 25% fewer credits and faster, but 720p, and it tends to mime a held object with empty hands. hermoso_capabilities lists the exact credits for both"),
     },
     outputSchema: { ...JOB_OUT },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-  }, wrap(async ({ image, video, prompt = '', orientation = 'video' }) => {
-    const r = await renderJob('motion', { image, video, prompt, orientation }, 'Motion recast');
+  }, wrap(async ({ image, video, prompt = '', orientation = 'video', tier }) => {
+    const r = await renderJob('motion', { image, video, prompt, orientation, ...(tier ? { tier } : {}) }, 'Motion recast');
     return okVideo(`Recast video: ${r.url}`, r);
   }));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermoso",
-  "version": "0.1.253",
+  "version": "0.1.254",
   "mcpName": "io.github.hermoso-ai/hermoso",
   "description": "Marketing on autopilot, run from your own AI agent. 841 tools. Publishing, scheduling, ad campaign management, comments, DMs and analytics cost no credits on every plan; credits are only for generating creative and for Ad Spy research. AD PLATFORMS: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads and ChatGPT Ads, plus product feeds in Google Merchant Center. PUBLISHING AND SCHEDULING: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky and Telegram. AD RESEARCH: the Meta, Google and LinkedIn ad libraries plus organic TikTok, Instagram, YouTube, Threads and Reddit. ANALYTICS: Google Analytics 4, Google Search Console and every connected platform's own post and campaign insights. Also brand onboarding, 50+ image and video generation models, ad scoring, competitor teardowns, Google Drive and OneDrive, a CLI and installable Claude skills.",
   "type": "module",

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

@@ -5,16 +5,18 @@ description: >-
   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']"
+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
+# 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` (opens your browser once; nothing to paste). On a machine with no browser: `hermoso auth login --token <your key>`, using a key from the app under **MCP & CLI**.. No account at all? An agent can sign itself up on a paid plan with `POST /v1/signup` at app.hermoso.ai, no browser needed; see the Hermoso README.
+## Setup (once)
+- Run the CLI through npx: `npx -y hermoso <command>`. The commands below are written `hermoso …`; if `hermoso` is not on PATH (`npm install -g hermoso` puts it there), prefix them with `npx -y`. No MCP server is needed.
+- Sign in once: `npx -y hermoso auth login` (opens a browser; nothing to paste). On a machine with no browser: `npx -y hermoso auth login --token <your key>`, using a key from app.hermoso.ai under **MCP & CLI**. No account at all? An agent can sign itself up on a paid plan with `POST /v1/signup` at app.hermoso.ai; see the Hermoso README.
+- For anything these steps do not cover: `hermoso tools --search <what you want>` finds the tool, `hermoso tools <name>` prints its arguments, `hermoso call <name> --json '{...}'` runs it. The CLI reaches every tool and costs no context until it runs.
 
 ## Procedure
 1. **Onboard the brand** (skip if the user already gave full brand details):
@@ -25,11 +27,11 @@ Drive the **Hermoso CLI** to go from a brand to a finished ad in three steps. Re
 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`
+   - 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.
+- Renders run on Hermoso's hosted API and come back as served URLs; `hermoso fetch <url> --out <file>` saves one to disk.

package/skills/hermoso-generate/SKILL.md

@@ -1,22 +1,23 @@
 ---
 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 /
+  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']"
+argument-hint: "[what to generate, e.g. 'a 9:16 video ad for our protein pancakes']"
 allowed-tools: Bash
 ---
 
-# Hermoso — generate ad creative
+# 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` (opens your browser once; nothing to paste). On a machine with no browser: `hermoso auth login --token <your key>`, using a key from the app under **MCP & CLI**. No account at all? An agent can sign itself up on a paid plan with `POST /v1/signup` at app.hermoso.ai, no browser needed; see the Hermoso README.
+- Run the CLI through npx: `npx -y hermoso <command>`. The commands below are written `hermoso …`; if `hermoso` is not on PATH (`npm install -g hermoso` puts it there), prefix them with `npx -y`. No MCP server is needed.
+- Sign in once: `npx -y hermoso auth login` (opens a browser; nothing to paste). On a machine with no browser: `npx -y hermoso auth login --token <your key>`, using a key from app.hermoso.ai under **MCP & CLI**. No account at all? An agent can sign itself up on a paid plan with `POST /v1/signup` at app.hermoso.ai; see the Hermoso README.
+- For anything these steps do not cover: `hermoso tools --search <what you want>` finds the tool, `hermoso tools <name>` prints its arguments, `hermoso call <name> --json '{...}'` runs it. The CLI reaches every tool and costs no context until it runs.
 
 ## 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.
@@ -26,7 +27,7 @@ You drive the **Hermoso CLI** (`hermoso`) to render images and videos. Always re
    - 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`.
+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

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

@@ -5,31 +5,33 @@ description: >-
   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']"
+argument-hint: "[product image + scene, e.g. './bag.png as a sunlit kitchen hero shot']"
 allowed-tools: Bash
 ---
 
-# Hermoso — product photoshoot
+# 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` (opens your browser once; nothing to paste). On a machine with no browser: `hermoso auth login --token <your key>`, using a key from the app under **MCP & CLI**.; run `hermoso capabilities` once to see image model ids + recipes. No account at all? An agent can sign itself up on a paid plan with `POST /v1/signup` at app.hermoso.ai, no browser needed; see the Hermoso README.
+## Setup (once)
+- Run the CLI through npx: `npx -y hermoso <command>`. The commands below are written `hermoso …`; if `hermoso` is not on PATH (`npm install -g hermoso` puts it there), prefix them with `npx -y`. No MCP server is needed.
+- Sign in once: `npx -y hermoso auth login` (opens a browser; nothing to paste). On a machine with no browser: `npx -y hermoso auth login --token <your key>`, using a key from app.hermoso.ai under **MCP & CLI**. No account at all? An agent can sign itself up on a paid plan with `POST /v1/signup` at app.hermoso.ai; see the Hermoso README.
+- Run `hermoso capabilities` once to see image model ids and recipes. For anything these steps do not cover: `hermoso tools --search <what you want>` finds the tool, `hermoso tools <name>` prints its arguments, `hermoso call <name> --json '{...}'` runs it.
 
 ## 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.
+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."
+- 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

@@ -5,16 +5,18 @@ description: >-
   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']"
+argument-hint: "[a brand/domain or a research question, e.g. 'longest-running protein-pancake ads']"
 allowed-tools: Bash
 ---
 
-# Hermoso — competitor & ad research
+# Hermoso: competitor & ad research
 
 This is Hermoso's discovery half (which most generators don't have). Drive the **Hermoso CLI**.
 
-## Setup
-- `hermoso auth login` (opens your browser once; nothing to paste). On a machine with no browser: `hermoso auth login --token <your key>`, using a key from the app under **MCP & CLI**.. No account at all? An agent can sign itself up on a paid plan with `POST /v1/signup` at app.hermoso.ai, no browser needed; see the Hermoso README.
+## Setup (once)
+- Run the CLI through npx: `npx -y hermoso <command>`. The commands below are written `hermoso …`; if `hermoso` is not on PATH (`npm install -g hermoso` puts it there), prefix them with `npx -y`. No MCP server is needed.
+- Sign in once: `npx -y hermoso auth login` (opens a browser; nothing to paste). On a machine with no browser: `npx -y hermoso auth login --token <your key>`, using a key from app.hermoso.ai under **MCP & CLI**. No account at all? An agent can sign itself up on a paid plan with `POST /v1/signup` at app.hermoso.ai; see the Hermoso README.
+- For anything these steps do not cover (organic search on TikTok, Instagram, YouTube, Reddit or Threads, creator search, a competitor teardown): `hermoso tools --search <what you want>` finds the tool, `hermoso tools <name>` prints its arguments, `hermoso call <name> --json '{...}'` runs it.
 
 ## Procedure
 Pick the tool that fits the ask:
@@ -24,7 +26,7 @@ Pick the tool that fits the ask:
    - 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`.
+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 credits (ad-library calls); keep platform scope to what's asked.