hermoso 0.1.253 → 0.1.255

package/README.md

@@ -3,7 +3,7 @@
 Run your whole marketing operation from **any AI agent**: Claude Code, Claude.ai, Cursor, Codex, or your own
 scripts. Research the ads already winning in a market, generate finished image & video ads (your real product
 composited in, copy + CTA included), publish them to your own social channels, and build & manage the ad
-campaigns behind them — all over [MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.
+campaigns behind them, all over [MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.
 
 **841 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
 catalog with exact per-render credit costs plus the full capability map.
@@ -30,46 +30,77 @@ 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.
 
 | Your client | Use | Why |
 | --- | --- | --- |
-| **Runs in a browser** — Claude.ai, ChatGPT, Claude Desktop | the hosted connector `https://app.hermoso.ai/mcp` | It cannot spawn a local process, so a URL is the only shape it has. Nothing to install, no key to paste, and the full toolset arrives with your saved brand context. This is the right answer for these clients, not a lesser one. |
-| **Can run a shell** — Claude Code, Cursor, Codex, Cline, OpenClaw, Hermes, your own scripts | the CLI, `npm install -g hermoso` | A tool manifest is loaded into every session whether or not a tool is called. A shell command costs nothing until it runs, and it reaches **every** tool rather than the default roster. |
+| **Runs in a browser**: Claude.ai, ChatGPT, Claude Desktop | the hosted connector `https://app.hermoso.ai/mcp` | It cannot spawn a local process, so a URL is the only shape it has. Nothing to install, no key to paste, and the full toolset arrives with your saved brand context. This is the right answer for these clients, not a lesser one. |
+| **Can run a shell**: Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, Hermes, your own scripts | the one-command install above, or the CLI itself (`npm install -g hermoso`) | A tool manifest is loaded into every session whether or not a tool is called. A shell command costs nothing until it runs, and it reaches **every** tool rather than the default roster. |
 
-**The measured difference** (2026-08-27, counted as real tool definitions rather than estimated from bytes):
-
-| | tools in range | loaded per session |
-| --- | --- | --- |
-| Hosted connector, default roster | 306 | **181,713 tokens** |
-| Hosted connector, `?tools=all` | 718 | **472,062 tokens** |
-| stdio server (`npx -y hermoso mcp`) | 306 | **181,713 tokens** |
-| **CLI** | **all 718** | **0** |
-
-The CLI answers the same questions on demand instead, and only when asked:
+The CLI answers the questions a tool manifest would, on demand and only when asked:
 
 ```bash
-npx -y hermoso tools --search reddit   # every matching tool, name + one line   2,459 tokens
-npx -y hermoso tools plan_ad           # one tool's full argument schema           633 tokens
+npx -y hermoso tools --search reddit   # every matching tool, name + one line
+npx -y hermoso tools plan_ad           # one tool's full argument schema
 npx -y hermoso call plan_ad --json '{"product":"…"}'   # run it
 ```
 
-So a terminal agent reaches its first call in roughly **3.4K tokens with the whole roster in range**, against
-**182K for a fraction of it**. `tools` and `tools <name>` read a registry bundled in the package — no key, no
-network, no sign-in — so an agent can browse the entire product before anyone signs in. Only `call` spends, and
-only that needs `hermoso auth login` once.
-
-**Both at once is fine, and is what we suggest for Claude Code.** One `hermoso auth login` covers the CLI *and*
-lets `claude mcp add hermoso -- npx -y hermoso mcp` pick the key up with no `env` block, so the agent can reach for
-a native tool when it wants structured results and shell out when it wants breadth. If you only want one, take the
-CLI: it covers strictly more.
+`tools` and `tools <name>` read a registry bundled in the package (no key, no network, no sign-in), so an agent
+can browse the entire product before anyone signs in. Only `call` spends, and only that needs
+`hermoso auth login` once.
 
-**When the connector is still the better trade on a shell-capable client:** a session that is going to make many
-calls into one area. `enable_tools({groups:['ads']})` turns campaign management on in a single free call and the
-tools are then native — no shell quoting, structured results. One shell round trip beats loading a 221K-token
-group for a single tool; the reverse is true once a session settles into that area.
+**Want the tools in your coding agent's own list as well?** That is the MCP server, and it is optional. One
+`hermoso auth login` covers the CLI *and* lets `claude mcp add hermoso -- npx -y hermoso mcp` pick the key up with
+no `env` block, so the agent can reach for a native tool when it wants structured results and shell out when it
+wants breadth. It costs context in every session, so add it when a session settles into one area and makes many
+calls there; `enable_tools({groups:['ads']})` then turns campaign management on in a single free call.
 
 ## Your agent can sign itself up
 
@@ -125,50 +156,56 @@ the routes.
 
 Paste **`https://app.hermoso.ai/mcp?src=readme`** into Claude → Settings → Connectors → *Add custom connector*, pick
 **Always required** when Claude asks about authentication (its detector suggests "None" because our discovery
-handshake is open; "None" would leave every tool call unauthenticated), approve with your Hermoso account, done — the full toolset with your saved brand context, billed to your plan.
+handshake is open; "None" would leave every tool call unauthenticated), approve with your Hermoso account, and you are done: the full toolset with your saved brand context, billed to your plan.
 
-## Quickstart for Claude Code (one line)
+## Quickstart for Claude Code (one command)
 
-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. Or skip the browser entirely and let your agent sign itself up on a paid plan
-   with `POST /v1/signup` (above).
-2. **Run one line.** Your browser opens once to sign in. Nothing to paste, and no key lands in `.claude.json`:
+1. **Get an account** at [app.hermoso.ai](https://app.hermoso.ai). The free tier is included; plans and credits
+   are the same ones the web Studio uses. Or skip the browser entirely and let your agent sign itself up on a paid
+   plan with `POST /v1/signup` (above).
+2. **Install the plugin.** It adds the four Hermoso skills, which drive the `hermoso` CLI through `npx`:
 
 ```bash
-npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcp
+claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso
 ```
 
-3. **Ask for what you want**, in your normal prompts. Claude Code reaches for a tool, or runs the `hermoso`
-   command in your terminal, whichever the job needs. You type neither.
-
-Ad campaign and analytics tools stay out of the tool list until you switch them on with `enable_tools`, which
-keeps it small. On a machine with no browser, sign in with `hermoso auth login --token hmk_…` using a key from
-**Settings → Agents & API**, or skip the sign-in and pass the key to the client instead:
+   Already inside a session? `/plugin marketplace add hermoso-ai/hermoso`, then `/plugin install hermoso@hermoso`.
+   Codex, Gemini CLI and the rest are in [Install in one command](#install-in-one-command).
+3. **Sign in once.** `npx -y hermoso auth login` opens your browser; your agent also runs it by itself the first
+   time it needs Hermoso. On a machine with no browser, use `npx -y hermoso auth login --token hmk_…` with a key
+   from **Settings → Agents & API**.
+4. **Ask for what you want**, in your normal prompts. Claude Code picks the Hermoso skill for the job and runs the
+   commands. You type none of them.
 
-```bash
-claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp
-```
+Rather install the CLI by hand? `npm install -g hermoso` puts the same `hermoso` command on your PATH, and the
+skills use it when it is there.
 
 The hosted URL works in Claude Code too, but it is the worse path there and it is worth knowing why:
 `claude mcp add --transport http hermoso "https://app.hermoso.ai/mcp?src=readme"` is accepted, and then `claude mcp list`
-reports `! Needs authentication` because the client will not start the OAuth flow by itself — you have to open a
+reports `! Needs authentication` because the client will not start the OAuth flow by itself: you have to open a
 session, run `/mcp`, find the server and press Authenticate. Measured against Claude Code 2.1.241 on 2026-08-23.
 
 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. Only AI model runs and Ad Spy research spend credits; publishing, scheduling, ads management and analytics are free on every plan (posting to X and reading X data are the one per-call exception, managing X ads is free).
+`plan_ad`/`plan_variations` to use it). Renders bill your Hermoso credits, at the same prices as the Studio. Only AI model runs and Ad Spy research spend credits; publishing, scheduling, ads management and analytics are free on every plan (posting to X and reading X data are the one per-call exception, managing X ads is free).
 
-## 1. MCP server (stdio) — Claude Code / Cursor / Codex
+## 1. MCP server (stdio), optional in a coding agent
 
-`hermoso mcp` runs a stdio MCP server exposing the full toolset. The published `hermoso` package means no clone —
-`npx -y hermoso mcp` fetches and runs it. Sign in once with the CLI and no key goes into any client config,
-because `hermoso mcp` reads the bearer `hermoso auth login` stored:
+`hermoso mcp` runs a stdio MCP server exposing the full toolset, for a client that wants Hermoso's tools in its own
+list. The published `hermoso` package means no clone: `npx -y hermoso mcp` fetches and runs it. Sign in once with
+the CLI and no key goes into any client config, because `hermoso mcp` reads the bearer `hermoso auth login` stored:
 
 ```bash
 npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcp
 ```
 
-Cursor / Codex — sign in the same way, then add to `mcp.json` (Codex uses the TOML equivalent). Drop the `env`
+On a machine with no browser, skip the sign-in and pass the key to the client instead:
+
+```bash
+claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp
+```
+
+Cursor / Codex: sign in the same way, then add to `mcp.json` (Codex uses the TOML equivalent). Drop the `env`
 block entirely if you signed in above; it is there for CI, where the process cannot read your home directory:
 
 ```json
@@ -278,7 +315,7 @@ consent screen, so the user does it in the app).
 
 Render jobs queue server-side and poll to completion, returning a served URL.
 
-## 2. CLI — the token-cheap path for terminal agents
+## 2. CLI: the context-free path for terminal agents
 
 `bin/hermoso.mjs` exposes the full MCP toolset as subprocess commands, so an agent can shell out instead of carrying a
 fat tool manifest.
@@ -307,19 +344,22 @@ hermoso create_meta_campaign --name "…"                   # same thing, shorte
 ```
 
 `call` goes through the same handler, the same argument validation and the same confirm/spend gates the MCP
-server uses — there is no second implementation to drift. `tools` and `tools <name>` read a registry bundled in
+server uses, so there is no second implementation to drift. `tools` and `tools <name>` read a registry bundled in
 the package, so they need no key, no network and no sign-in.
 
-## 3. Claude skills — slash commands that wrap the CLI
+## 3. Skills: what a coding agent installs
 
 `skills/` holds four installable skills: `hermoso-generate`, `hermoso-ad-from-brand`,
 `hermoso-product-photoshoot`, `hermoso-research`.
 
+They are what every one-command install at the top of this page adds, in Claude Code, Codex, Gemini CLI and
+through `npx skills add`. From a clone, copying works too:
+
 ```bash
 cp -r skills/* ~/.claude/skills/
 ```
 
-Then invoke `/hermoso-ad-from-brand an ad for yourbrand.com — our hero product`.
+Then invoke `/hermoso-ad-from-brand an ad for yourbrand.com, our hero product`.
 
 ## Configuration
 

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.255",
   "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.