hermoso 0.1.539 → 0.1.542

package/README.md

@@ -133,8 +133,9 @@ 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 six skills (`hermoso-research`, `hermoso-generate`,
-`hermoso-ad-from-brand`, `hermoso-product-photoshoot`, `hermoso-marketing`, `hermoso-edit-timeline`), and the skills drive the `hermoso`
+Hermoso in one line. Every install brings the same seven skills (`hermoso-research`, `hermoso-generate`,
+`hermoso-ad-from-brand`, `hermoso-product-photoshoot`, `hermoso-marketing`, `hermoso-edit-timeline`,
+`hermoso-launch-app`), 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.
@@ -286,7 +287,7 @@ Connect, approve with your Hermoso account, and you are done: the full toolset w
 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 six Hermoso skills, which drive the `hermoso` CLI through `npx`:
+2. **Install the plugin.** It adds the seven Hermoso skills, which drive the `hermoso` CLI through `npx`:
 
 ```bash
 claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso
@@ -514,7 +515,7 @@ the package, so they need no key, no network and no sign-in.
 
 ## 3. Skills: what a coding agent installs
 
-`skills/` holds six installable skills:
+`skills/` holds seven installable skills:
 
 | Skill | What it does |
 | --- | --- |
@@ -524,6 +525,7 @@ the package, so they need no key, no network and no sign-in.
 | `hermoso-product-photoshoot` | A real product photo composited into studio, lifestyle or hero scenes |
 | `hermoso-marketing` | The whole loop: research, create, publish and schedule, paid campaigns, measure |
 | `hermoso-edit-timeline` | The manual for composing any video edit or transition with `edit_timeline` |
+| `hermoso-launch-app` | Launch and market an app or site you just built: brand, launch ads, a week of scheduled posts |
 
 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:

package/mcp/http.mjs

@@ -599,7 +599,7 @@ const inflightNameOf = (body) => { const msgs = Array.isArray(body) ? body : [bo
       const baseInstructions = instructionsFor(scope, { widgetHost });
       let firstRun = null;
       if (typeof firstRunFor === 'function' && user.accountId) {
-        try { firstRun = await Promise.race([Promise.resolve(firstRunFor({ accountId: user.accountId })).catch(() => null), new Promise((r) => { const t = setTimeout(() => r(null), 1500); if (t && typeof t.unref === 'function') t.unref(); })]); } catch { firstRun = null; }
+        try { firstRun = await Promise.race([Promise.resolve(firstRunFor({ accountId: user.accountId, brandKey: user.brandKey === true })).catch(() => null), new Promise((r) => { const t = setTimeout(() => r(null), 1500); if (t && typeof t.unref === 'function') t.unref(); })]); } catch { firstRun = null; }
       }
       firstRun = firstRun && typeof firstRun === 'object' && firstRun.fresh === true ? { ...firstRun, offer: firstRunOffers(baseInstructions) } : null;
       const server = new McpServer({ name: 'hermoso', version: PKG_VERSION }, { instructions: withFirstRunLine(baseInstructions, firstRun) });

package/mcp/tools.mjs

@@ -674,7 +674,13 @@ export function noteBrandOf(tool, args) {
   for (const k of HERMOSO_BRAND_KEYS.get(tool) || []) { const v = args?.[k]; if (typeof v === 'string' && v.trim()) return v.trim().slice(0, 120); }
   return '';
 }
-export async function withConnectPrompt(tool, r, post = apiPost, brand = '') {
+// …AND AT MOST ONE NEXT STEP, WHICHEVER IT IS (2026-11-14, lib/agent-nudge.mjs). `nudge: 1` tells the server this twin reads
+// `next` off the answer: the one step it chose for this account (save a brand first, then connect a channel), with the
+// sentence to say, each offered at most once in seven days and never once done. The server words the text, the step and
+// the hint, so a step added later needs no new twin; a server that predates this answers the connect prompt as before.
+// `raw` marks a call on the raw model lane, which gets no note of ours about a brand; `asked` says this session's
+// first-run note already asked for their website, so the same session is not asked twice.
+export async function withConnectPrompt(tool, r, post = apiPost, brand = '', opts = {}) {
   try {
     const kind = finishedRenderKind(tool, r);
     if (!kind) return r;
@@ -683,10 +689,16 @@ export async function withConnectPrompt(tool, r, post = apiPost, brand = '') {
     const sc = r.structuredContent || {};
     const job = String(sc.jobId || sc.id || '').slice(0, 80);
     const client = store ? String(store.client || '') : 'hermoso';
-    const d = await Promise.race([Promise.resolve(post('/api/mcp/connect-prompt', { tool, kind, job, client, ...(brand ? { brand } : {}) })).catch(() => null), new Promise((res) => { const t = setTimeout(() => res(null), CONNECT_PROMPT_WAIT_MS); if (t && typeof t.unref === 'function') t.unref(); })]);
+    const d = await Promise.race([Promise.resolve(post('/api/mcp/connect-prompt', { tool, kind, job, client, nudge: 1, ...(opts && opts.raw ? { raw: true } : {}), ...(opts && opts.asked ? { asked: true } : {}), ...(brand ? { brand } : {}) })).catch(() => null), new Promise((res) => { const t = setTimeout(() => res(null), CONNECT_PROMPT_WAIT_MS); if (t && typeof t.unref === 'function') t.unref(); })]);
     if (!d || d.show !== true || typeof d.text !== 'string' || !d.text) return r;
-    const out = { ...r, content: [...r.content, { type: 'text', text: d.text }], structuredContent: { ...sc, connectPrompt: { channels: Array.isArray(d.channels) ? d.channels : [] } } };
-    return withHints(out, [...hintsOf(r), { do: 'offer to post this; hand the user one of the connect links in this reply', why: 'no publishing channel is connected, and connecting needs a browser sign-in on the platform' }]);
+    const next = d.next && typeof d.next === 'object' && typeof d.next.step === 'string' && d.next.step ? d.next : null;
+    const hint = d.hint && typeof d.hint === 'object' && typeof d.hint.do === 'string' && d.hint.do ? d.hint : null;
+    if (next && next.step !== 'connect_channel') {
+      const out = { ...r, content: [...r.content, { type: 'text', text: d.text }], structuredContent: { ...sc, next } };
+      return hint ? withHints(out, [...hintsOf(r), hint]) : out;
+    }
+    const out = { ...r, content: [...r.content, { type: 'text', text: d.text }], structuredContent: { ...sc, connectPrompt: { channels: Array.isArray(d.channels) ? d.channels : [] }, ...(next ? { next } : {}) } };
+    return withHints(out, [...hintsOf(r), hint || { do: 'offer to post this; hand the user one of the connect links in this reply', why: 'no publishing channel is connected, and connecting needs a browser sign-in on the platform' }]);
   } catch { return r; }
 }
 // THE WEEK-PLAN NOTE (2026-11-02, lib/week-plan.mjs): the offer after a first connection, and "your week is finished". The
@@ -699,6 +711,7 @@ const WEEK_PLAN_NOTE_SKIP = new Set(['plan_week', 'get_job', 'list_jobs']);
 export async function withWeekPlanNote(tool, r, post = apiPost, brand = '') {
   try {
     if (!r || r.isError || !Array.isArray(r.content) || WEEK_PLAN_NOTE_SKIP.has(tool)) return r;
+    if (r.structuredContent && r.structuredContent.next && typeof r.structuredContent.next.step === 'string') return r; // one next step a reply (a paging cursor called `next` is not one): this note is not asked for, so it is not spent, and the next reply carries it
     const store = mcpCtx.getStore();
     if (store && (store.connectPromptQuiet || (store.remote && store.client === undefined))) return r;
     const client = store ? String(store.client || '') : 'hermoso';
@@ -872,6 +885,7 @@ const wrap = (fn) => {
           _fr.said = true;
           const _n = ((_st.apiCharged || 0) + (_st.jobCharged || 0)) > 0 ? null : firstRunNote(_tool, _fr, r);
           if (_n) {
+            if (/draft_brand/.test(String(_n.hint?.do || ''))) _fr.brandAsked = true; // this session has asked for their website: its next finished creation does not ask again (withConnectPrompt `asked`)
             const _last = [...r.content].reverse().find((b) => b && b.type === 'text' && typeof b.text === 'string');
             if (_last) _last.text += `\n\n${_n.text}`; else r.content.push({ type: 'text', text: _n.text });
             return noPitchOnWidget(withHints(r, [_n.hint]));
@@ -879,7 +893,7 @@ const wrap = (fn) => {
         }
       } catch {}
       const _noteBrand = noteBrandOf(_tool, args); // the brand this call acted on, so both notes are about it
-      return noPitchOnWidget(await withWeekPlanNote(_tool, await withConnectPrompt(_tool, withWidgetResultNote(_tool, r, hostRendersWidgets()), apiPost, _noteBrand), apiPost, _noteBrand));
+      return noPitchOnWidget(await withWeekPlanNote(_tool, await withConnectPrompt(_tool, withWidgetResultNote(_tool, r, hostRendersWidgets()), apiPost, _noteBrand, { raw: args?.raw === true, asked: mcpCtx.getStore()?.firstRun?.brandAsked === true }), apiPost, _noteBrand));
     }
     catch (e) {
       try { recordToolOutcome(_tool, { ok: false, ms: Date.now() - _t0 }); } catch {}
@@ -6636,6 +6650,9 @@ function buildTools(rawServer, opts = {}, sink = null) {
     // ZERO BRANDS IS A REAL STATE (2026-10-01): the owner may delete their last brand. Say so, and say how to make one,
     // rather than printing an empty list under a heading that implies there should be something in it.
     if (!(d.brands || []).length) return ok(`This account has no profiles yet (the last one was deleted, or none was ever made). create_brand makes one, and draft_brand fills it in from a website, a description or a social handle.${sharedTxt}`, { ...d, sharedWorkspaces: shared });
+    // A KEY LIMITED TO ONE BRAND lists that brand and says so (the server filters the roster and sends the sentence),
+    // so an agent does not go looking for profiles it was never given.
+    if (d.limited && d.limited.sentence) return ok(`${d.limited.sentence} It is the only profile this connection can see or act on:\n${lines}${sharedTxt}`, { ...d, sharedWorkspaces: shared });
     return ok(`Profiles on this account:\n${lines}\n\nSwitch with use_brand.${sharedTxt}`, { ...d, sharedWorkspaces: shared });
   }));
 
@@ -6685,6 +6702,8 @@ function buildTools(rawServer, opts = {}, sink = null) {
       return ok(`Now acting on ${sh.name || 'that shared profile'}${sh.ownerName ? ` (${sh.ownerName}'s profile)` : ''} (profile ${sh.profileUuid}). Its brand details, memory, Library and CONNECTED ACCOUNTS are what every tool sees from here; switch back by naming one of your own profiles.`,
         { ok: true, brand: { id: sh.profileUuid, name: sh.name || null, ownerAccountId: sh.ownerAccountId, role: sh.role || 'member' }, shared: true });
     }
+    // A key limited to one brand cannot switch, and says so in the server's own sentence instead of "no such profile".
+    if (d.limited && d.limited.sentence) return { content: [{ type: 'text', text: `${d.limited.sentence} It cannot switch to another brand.` }], isError: true };
     const own = (d.brands || []).map(b => `• ${b.name} (id: ${b.id})`).join('\n');
     const shr = shared.map(w => `• ${w.name || 'Shared profile'}${w.ownerName ? ` — ${w.ownerName}` : ''} (id: ${w.profileUuid}, shared with you)`).join('\n');
     if (!own && !shr) return { content: [{ type: 'text', text: `No profile matching "${brand}": this account has no profiles yet. create_brand makes one.` }], isError: true }; // zero brands is a real state (2026-10-01)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermoso",
-  "version": "0.1.539",
+  "version": "0.1.542",
   "mcpName": "io.github.hermoso-ai/hermoso",
   "description": "AI marketing agent and AI ad generator, run from your own AI agent. 1233 tools. No markup on models on Starter and up. Publishing, scheduling, ad campaign management, comments, DMs and analytics cost no credits on any plan; Free includes 5 posts a month and every paid plan posts without a limit. AD PLATFORMS: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads, ChatGPT Ads and AppLovin Ads, plus product feeds in Google Merchant Center. PUBLISHING AND SCHEDULING: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky, Telegram, WordPress, Discord, Slack, Whop and Google Business Profile. INSTAGRAM DM AUTOMATIONS: a keyword comment, a DM, a story reply or an ig.me link gets an automatic private reply from the brand. 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-launch-app/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: hermoso-launch-app
+description: >-
+  Launch and market an app or site you just built, using Hermoso. Sets up the brand from the app, makes launch
+  ads and posts, schedules them on the owner's own social channels and, if asked, builds paused ad campaigns.
+  Use when the user says "launch this", "market my app", "get me users", "make launch posts", "promote what we
+  just built", or finishes a build in an app builder (Lovable, Replit, Bolt, v0, Base44) and asks what is next.
+  NOT for: building the app itself, or a single image from a prompt (use hermoso-generate).
+argument-hint: "[the app's URL or one line about what it does, e.g. 'https://myapp.com, a habit tracker for runners']"
+---
+
+# Hermoso: launch the app you just built
+
+You built something. This gets it in front of people: a saved brand, launch creative, a week of scheduled posts
+and, only if the user asks, paid campaigns created paused.
+
+## Before you start
+- Hermoso has to be connected to this host as an MCP server (URL `https://app.hermoso.ai/mcp`, sign in once).
+  If its tools are not available, send the user to https://hermoso.ai/connect/ and pick their host
+  (Lovable, Replit, Bolt, v0 and Base44 each have a page with the exact clicks).
+- In a terminal there is no MCP server to connect: the same tools run through the Hermoso CLI. Sign in once with
+  `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**. Then
+  `hermoso tools --search <what you want>` finds a tool, `hermoso tools <name>` prints its arguments and
+  `hermoso call <name> --json '{...}'` runs it (after `npm install -g hermoso`, or prefix each with `npx -y`).
+  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.
+- A tool you do not see in your list still exists: `find_tools` searches every Hermoso tool and `call_tool`
+  runs any of them by name.
+- The connector works while you build. It is not part of the published app, so never wire Hermoso calls into
+  the app's own code unless the user asks for an API integration.
+
+## The launch, in order
+Do only the steps the user wants. Say what you are about to do before anything that spends credits or posts.
+
+1. **Know the product.** Use what you already know from the build: what the app does, who it is for, its name,
+   its live URL. Ask only for what is missing. One line is enough.
+2. **Save the brand.** If the app has a public URL, call `draft_brand` with it so every ad matches the app's
+   look and voice. No URL yet? Call `draft_brand` with a short description instead. `get_brand` shows what is
+   already saved; do not draft twice.
+3. **See what works in this market (optional, costs credits).** `find_competitors` then `research_ads`, and
+   report the two or three hooks that keep showing up. Skip this if the user just wants posts.
+4. **Make the launch creative.** Three is a good first set: a static launch ad, a carousel or second static
+   with a different angle, and one short vertical video if the user wants video. `generate_image` and
+   `render_ad` pick sound defaults when you do not name a model. Video takes a few minutes: read the job with
+   `get_job` and never call it done before it finishes. Show the user each result.
+5. **Check the channels.** `list_connectors` says which social accounts are connected. None connected is not
+   an error: give the user the connect link from the tool result, or tell them to open Hermoso and connect
+   the channels they want under Connectors. Do not post anywhere the user did not name.
+6. **Schedule the week.** Show the exact caption and the exact account for each post and get a yes. Then
+   `schedule_post`, one a day, at the times the user picks or mornings in their time zone. `list_scheduled`
+   reads the queue back. Never rewrite or shorten a caption the user wrote.
+7. **Paid ads, only if asked.** Campaigns are created paused on the user's own ad accounts and read back
+   before you describe them. Turning one on is the user's decision, stated in their own words.
+8. **Report.** What was made (with links), what is scheduled and when, what is waiting on the user (a channel
+   to connect, a campaign to turn on), and the one thing to do next week: read what performed with
+   `post_performance` and make more of that.
+
+## Rules
+- Nothing is published, scheduled or spent on ads without the user saying so in this conversation.
+- If the free credits run out, say so plainly and stop. Do not swap in a cheaper version of what was asked.
+- Use the app's real name, screens and URL. Do not invent features, prices, reviews or numbers for the ads.