hermoso 0.1.113 → 0.1.139

package/README.md

@@ -5,9 +5,16 @@ scripts. Research the ads already winning in a market, generate finished image &
 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.
 
-**521 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**681 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.
 
+**What it connects to.** 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. Files: Google Drive, Sheets, Docs and OneDrive.
+
 **It is not all-or-nothing.** Research, creation, publishing/scheduling and ads management are four *independent*
 areas — no tool requires that you used another one first. Publish or schedule creative you already have and
 generate nothing here (`upload_file` turns any local or external file into a URL every publish, schedule and
@@ -53,7 +60,7 @@ Cursor / Codex — add to `mcp.json` (Codex uses the TOML equivalent):
 
 Then ask your agent: *“Generate an image ad with Hermoso.”*
 
-### What the 521 tools cover
+### What the 681 tools cover
 
 **Ad spy / research** — `find_competitors`, `competitor_teardown`, `pull_competitor_ads`, `research_ads`; the
 Meta / Google / LinkedIn ad libraries (`search_meta_ads`, `search_google_ads`, `search_linkedin_ads`); organic
@@ -97,6 +104,15 @@ change confirm-gated, on **eleven** platforms: **Meta**, **Google Ads**, **Linke
 `set_google_ads_status`). *Snapchat needs one extra step the others do not: an ad points at a CREATIVE, and every
 Snapchat creative must carry a Public Profile id — build it with `upload_snapchat_ads_creative`.*
 
+**Feed the shopping surfaces** — **Google Merchant Center** is the catalog a retail Performance Max or Shopping
+campaign advertises (`create_google_ads_performance_max_campaign` takes a `merchantCenterId`), and you manage it
+from here: accounts and account status, data sources, product upsert / update / delete, per-region inventory,
+quota, `merchant_report` for product-level performance, notifications and conversion sources, plus the disapproval
+loop — `list_merchant_issues` says what is wrong and `merchant_issue_help` returns Google's own documented fix.
+*Promotions need the merchant's own enrolment in Google's promotions program; without it Google refuses that
+sub-API outright.* **Microsoft Merchant Center** is covered on the same shape (stores, catalogs, products, issues)
+for Bing Shopping.
+
 **Measure what the ads achieved** — Google Analytics 4 closes the loop. Every other connector here reports what an
 ad *cost*; this is the one that reports what it *did*. `analytics_report` breaks sessions, users, conversions and
 revenue down by channel, source/medium, campaign, landing page, country, device or date, so the campaign Hermoso

package/bin/hermoso.mjs

@@ -9,6 +9,14 @@
 //   hermoso create --brand Flourish --product "protein pancakes" --format image
 //   hermoso generate image --prompt "…" --ref ./bag.png --wait
 //
+// EVERY tool the MCP server registers is also callable here. The terminal gets the same product as the connector,
+// reached a cheaper way:
+//   hermoso tools                                        # every tool, name + one line, grouped
+//   hermoso tools --group ads --search reddit            # narrow it
+//   hermoso tools post_to_x                              # one tool's full schema
+//   hermoso call post_to_x --json '{"text":"hello"}'     # run it
+// The curated subcommands above stay as ergonomics for the common path; `call` is the ceiling.
+//
 // 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, chmod } from 'node:fs/promises';
@@ -100,7 +108,12 @@ async function main() {
         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 'credits': { const d = await api.apiGet('/api/credits');
+        // accountBalance = the caller's Hermoso credits (authoritative when authed); balance = the local-dev usage
+        // pill. Reading only `balance` printed "Balance: undefined credits" against prod for every signed-in user
+        // (measured 2026-08-19). Same expression the hermoso_credits MCP tool uses, so the two cannot disagree.
+        const bal = d.accountBalance ?? d.balance;
+        return out(`Balance: ${bal ?? '—'} credits`, 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;
@@ -157,7 +170,89 @@ async function main() {
       }
       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)`); }
+      // ── TELLING US SOMETHING IS BROKEN OR MISSING ──────────────────────────────────────────────────────────
+      // `report_bug` / `request_feature` are reachable through the generic passthrough like everything else, and
+      // these two shortcuts exist anyway because of WHEN they get reached for: mid-task, right after something has
+      // just failed. `hermoso call report_bug --json '{"summary":"…","details":"…"}'` is a lot of ceremony at that
+      // moment, and a report that does not get written is the one case this whole channel exists to prevent.
+      //
+      // NOTHING IS INVENTED. With no --details, the text you typed becomes the details and its FIRST SENTENCE
+      // becomes the summary — your own words in both fields, under a rule stated here and in --help. It never
+      // writes a sentence you did not.
+      case 'bug': case 'feature': {
+        const tool = group === 'bug' ? 'report_bug' : 'request_feature';
+        const text = [sub, ...pos.slice(2)].filter(Boolean).join(' ').trim() || String(flags.summary || '').trim();
+        if (!text) return die(`usage: hermoso ${group} "what happened" [--details "…"]${group === 'bug' ? ' [--severity low|medium|high]' : ''}`);
+        const firstSentence = (text.split(/(?<=[.!?])\s/)[0] || text).trim();
+        const preset = {
+          summary: String(flags.summary || firstSentence).slice(0, 200),
+          details: String(flags.details || text),
+          ...(group === 'bug' && flags.severity ? { severity: String(flags.severity) } : {}),
+        };
+        const reg = await import('../mcp/registry.mjs');
+        return await runTool(reg, tool, flags, [], preset);
+      }
+      // ── FULL TOOL SURFACE ──────────────────────────────────────────────────────────────────────────────────
+      // `tools` is what replaces a tool manifest: the agent greps this list for the one tool it needs and reads
+      // that schema alone, instead of carrying several hundred schemas before the user has said anything.
+      case 'tools': {
+        const reg = await import('../mcp/registry.mjs');
+        const name = sub;
+        if (name) return await printToolSchema(reg, name, flags);
+        const inv = reg.inventory();
+        const q = String(flags.search || flags.grep || '').toLowerCase();
+        const wantGroup = flags.group ? String(flags.group).toLowerCase() : '';
+        if (wantGroup && !reg.TOOL_GROUP_NAMES.includes(wantGroup)) {
+          // Refused by name, never quietly ignored — a filter that silently matched everything would hand back the
+          // whole roster to someone who asked for one slice and believed they got it.
+          return die(`Unknown group "${wantGroup}". Groups: ${reg.TOOL_GROUP_NAMES.join(', ')}.`);
+        }
+        // Sorted by group (in the order enable_tools names them) then by name, so a group heads its own block
+        // exactly once. Registration order interleaves the sections and prints `core` four times.
+        const order = (g) => { const i = reg.TOOL_GROUP_NAMES.indexOf(g); return i < 0 ? 99 : i; };
+        const rows = inv.filter((t) => (!wantGroup || t.group === wantGroup)
+          && (!q || t.name.includes(q) || t.description.toLowerCase().includes(q) || (t.title || '').toLowerCase().includes(q)))
+          .sort((a, b) => order(a.group) - order(b.group) || a.name.localeCompare(b.name));
+        if (flags.json === true) return console.log(JSON.stringify(rows, null, 2));
+        if (flags.names) return console.log(rows.map((t) => t.name).join('\n'));
+        if (!rows.length) return console.log(`No tool matches${wantGroup ? ` in ${wantGroup}` : ''}${q ? ` "${q}"` : ''}. Try: hermoso tools`);
+        const counts = {};
+        for (const t of inv) counts[t.group] = (counts[t.group] || 0) + 1;
+        console.log(`${inv.length} tools · ${reg.TOOL_GROUP_NAMES.map((g) => `${g}(${counts[g] || 0})`).join(' ')}`);
+        if (rows.length !== inv.length) console.log(`showing ${rows.length}`);
+        const width = Math.max(40, (process.stdout.columns || 100) - 30);
+        let last = null;
+        for (const t of rows) {
+          if (t.group !== last) {
+            // The group's own one-line purpose, straight from the table `enable_tools` uses, so an agent scanning
+            // for where to look is reading the same description the connector shows.
+            const blurb = reg.TOOL_GROUPS[t.group] || '';
+            console.log(`\n${t.group}${blurb ? `  ${blurb}` : ''}`);
+            last = t.group;
+          }
+          const one = t.description.split(/(?<=[.!?])\s|\n/)[0].trim();
+          console.log(`  ${t.name.padEnd(34)} ${one.length > width ? one.slice(0, width - 1) + '…' : one}`);
+        }
+        console.log(`\nhermoso tools <name>            one tool's full schema`);
+        console.log(`hermoso call <name> --json '{…}'  run it`);
+        return;
+      }
+      // `call` runs ANY registered tool through the same handler, the same argument validation and the same
+      // confirm/spend gates the MCP twins use. There is no second implementation here to drift or to bypass.
+      case 'call': {
+        if (!sub) return die(`usage: hermoso call <tool_name> --json '{"key":"value"}'   ·   hermoso tools  lists them`);
+        const reg = await import('../mcp/registry.mjs');
+        return await runTool(reg, sub, flags, pos.slice(2));
+      }
       default:
+      {
+        // A BARE TOOL NAME IS A CALL. `hermoso post_to_x --text hi` is the same thing as
+        // `hermoso call post_to_x --text hi`, so an agent that read a name out of `hermoso tools` can just run it.
+        // Checked against the REAL registry, so nothing has to be listed here and kept in step.
+        if (group) {
+          const reg = await import('../mcp/registry.mjs');
+          if (reg.inventory().some((t) => t.name === group)) return await runTool(reg, group, flags, pos.slice(1));
+        }
         console.log(`hermoso <command>
   auth login [--url <base>] [--token <t>]   credits          capabilities
   brand draft (--domain|--description|--social …)             create --brand --product [--format]
@@ -165,12 +260,120 @@ async function main() {
   jobs list | jobs get <id> [--wait]                          competitors <domain>
   ads pull (--company|--domain)                               research "<request>"
   fetch <url> [--out]                                         mcp   (run the stdio MCP server)
+  bug "what broke" [--details] [--severity]                   feature "what you need" [--details]
   version
+
+The full tool surface (every tool the MCP server has):
+  tools [--group <g>] [--search <q>] [--names]               list every tool, name + one line
+  tools <name>                                               that tool's full input schema
+  call <name> --json '{"key":"value"}'                       run it
+  <name> --key value                                         same thing, shorter
 add --json to any command for machine output.`);
+        if (group) console.error(`\n✗ Unknown command "${group}". It is not a subcommand and not a tool name. Try: hermoso tools --search ${JSON.stringify(String(group).slice(0, 24))}`);
+        if (group) process.exitCode = 1;
+        return;
+      }
     }
   } catch (e) { die(e?.message || String(e)); }
 }
 
+// ---- the full-tool-surface commands ---------------------------------------------------------------------------
+// Flags THIS command consumes. Everything else is a tool argument, so the list stays as short as it can be:
+// `--raw` is a real property on generate_image / generate_text / generate_video, and reserving it would make three
+// tools uncallable from the shorthand. A tool that ever needs a `--json` or `--args` argument can still pass it
+// inside --args '{"json":…}'.
+const CALL_FLAGS = new Set(['json', 'args', 'args-file', 'structured']);
+
+async function readArgsPayload(flags) {
+  let src = null;
+  if (typeof flags.args === 'string') src = flags.args;
+  else if (typeof flags.json === 'string') src = flags.json;      // `--json '{…}'`; a bare `--json` means machine output
+  if (flags['args-file']) src = await readFile(String(flags['args-file']), 'utf8');
+  if (src === '-') src = await new Promise((res, rej) => { let b = ''; process.stdin.setEncoding('utf8'); process.stdin.on('data', (c) => { b += c; }); process.stdin.on('end', () => res(b)); process.stdin.on('error', rej); });
+  if (src == null || String(src).trim() === '') return {};
+  let parsed;
+  try { parsed = JSON.parse(src); }
+  catch (e) { throw new Error(`arguments are not valid JSON: ${e.message}. Wrap the whole object in single quotes: --json '{"key":"value"}'`); }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('arguments must be a JSON object, e.g. --json \'{"key":"value"}\'');
+  return parsed;
+}
+
+async function printToolSchema(reg, name, flags) {
+  const { client, close } = await reg.openRegistry();
+  try {
+    const all = await reg.listTools(client);
+    const tool = all.find((t) => t.name === name);
+    if (!tool) return die(suggestTool(reg, name));
+    const group = reg.inventory().find((t) => t.name === name)?.group || '?';
+    if (flags.json === true) return console.log(JSON.stringify({ ...tool, group }, null, 2));
+    console.log(`${tool.name}   [${group}]${tool.title ? '  ·  ' + tool.title : ''}`);
+    console.log(`\n${tool.description || ''}\n`);
+    const fields = reg.schemaFields(tool.inputSchema);
+    if (!fields.length) console.log('Arguments: none.');
+    else {
+      console.log('Arguments:');
+      const width = Math.max(40, (process.stdout.columns || 100) - 40);
+      for (const f of fields) {
+        const head = `  ${f.required ? '*' : ' '} ${f.name}${f.type ? ` <${f.type}>` : ''}`;
+        const d = f.enum ? `one of: ${f.enum.join(' | ')}` : f.description;
+        console.log(`${head.padEnd(38)} ${d.length > width ? d.slice(0, width - 1) + '…' : d}`);
+      }
+      console.log('  (* = required)');
+    }
+    const req = fields.filter((f) => f.required);
+    const example = Object.fromEntries(req.map((f) => [f.name, f.enum ? f.enum[0] : f.type === 'number' || f.type === 'integer' ? 0 : f.type === 'boolean' ? true : f.type === 'array' ? [] : '…']));
+    console.log(`\nhermoso call ${tool.name} --json '${JSON.stringify(example)}'`);
+    console.log(`hermoso tools ${tool.name} --json      the raw JSON Schema`);
+  } finally { await close(); }
+}
+
+function suggestTool(reg, name) {
+  const inv = reg.inventory();
+  const needle = String(name).toLowerCase();
+  const near = inv.filter((t) => t.name.includes(needle) || needle.includes(t.name.split('_')[0])).slice(0, 6).map((t) => t.name);
+  return `No tool named "${name}".${near.length ? ` Did you mean: ${near.join(', ')}?` : ''} Run: hermoso tools --search ${JSON.stringify(needle.slice(0, 24))}`;
+}
+
+// RUN A TOOL. The arguments are assembled here and passed through UNTOUCHED — nothing is defaulted, injected or
+// dropped on the way. That is what keeps a confirm-gated tool confirm-gated from a terminal: the gate lives in the
+// handler, and the CLI is not allowed to answer it on the caller's behalf.
+// `preset` is the ONLY way anything reaches the arguments other than the caller's own --json/--flags, and it is
+// supplied by exactly two call sites: the `bug` and `feature` shortcuts, which shape text the user typed into the
+// two fields those tools require. A caller's own value always wins over it. It is deliberately not a general
+// mechanism — every other command either passes the arguments through untouched or does not use runTool at all,
+// which is what keeps a confirm-gated tool something only the caller can answer.
+async function runTool(reg, name, flags, extraPos = [], preset = null) {
+  const { client, close } = await reg.openRegistry();
+  try {
+    const all = await reg.listTools(client);
+    const tool = all.find((t) => t.name === name);
+    if (!tool) return die(suggestTool(reg, name));
+    const args = { ...(preset || {}), ...(await readArgsPayload(flags)) };
+    // Per-flag arguments, coerced against the TOOL'S OWN schema and refused by name when unrecognised. The SDK
+    // builds a non-strict object, so an unknown key would otherwise be stripped in silence — a typo'd `--confrim`
+    // would send an unconfirmed call and read as a clean success.
+    const bad = [];
+    for (const [k, v] of Object.entries(flags)) {
+      if (CALL_FLAGS.has(k)) continue;
+      const c = reg.coerceArg(tool.inputSchema, k, v);
+      if (c.ok) { args[k] = c.value; continue; }
+      bad.push(c.unknown ? `--${k} is not an argument of ${name}` : c.message);
+    }
+    if (extraPos.length) bad.push(`unexpected value${extraPos.length > 1 ? 's' : ''} ${extraPos.map((v) => JSON.stringify(v)).join(', ')} . Every argument is a --flag or goes inside --json`);
+    if (bad.length) return die(`${bad.join('\n  ')}\n  Run: hermoso tools ${name}`);
+
+    const res = await client.callTool({ name, arguments: args });
+    const text = (res.content || []).filter((c) => c.type === 'text').map((c) => c.text).join('\n');
+    if (flags.json === true) console.log(JSON.stringify(res, null, 2));
+    else if (flags.structured) console.log(JSON.stringify(res.structuredContent ?? null, null, 2));
+    else if (text) console.log(text);
+    else console.log(JSON.stringify(res.structuredContent ?? res, null, 2));
+    // A TOOL THAT FAILED MUST EXIT NON-ZERO. `isError` is how MCP reports a refused gate, a missing connector or a
+    // provider failure, and a shelling-out agent reads the exit code before it reads the text.
+    if (res.isError) process.exitCode = 1;
+  } finally { await close(); }
+}
+
 // ---- browser sign-in (loopback OAuth, like gh/firebase): spin a 127.0.0.1 server, open the app's cli-auth page,
 //      which mints an agent key and redirects the browser back to our loopback with ?key=&state=. Nothing is pasted;
 //      the key transits only the user's own machine. Times out after 3 min. Returns the hmk_ key, or null. ----

package/mcp/hermoso-mcp.mjs

@@ -18,9 +18,9 @@ const server = new McpServer({ name: 'hermoso-mcp', version: '1.0.0' }, {
 });
 
 // Roster scoping, same groups as the hosted connector's ?tools= (see registerTools). The DEFAULT is every group
-// except `ads` — 238 of the 436 tools and ~66% of the schema weight — which takes an eagerly-loading client from
-// ~235k tokens to ~83k. Nothing is lost: `enable_tools` switches a group on mid-session with no reconnect.
-// HERMOSO_TOOLS=all restores the full roster; HERMOSO_TOOLS=create,channels narrows it further.
+// except `ads` and `analytics` (OPT_IN_TOOL_GROUPS) — together ~254k of the ~365k full roster, so the default is
+// ~112k. Both are held out on SIZE alone, and nothing is lost: `enable_tools` switches either on mid-session with
+// no reconnect. HERMOSO_TOOLS=all restores the full roster; HERMOSO_TOOLS=create,channels narrows it further.
 // An unknown group EXITS rather than silently serving all of them — a scoped connection you did not get is
 // worse than one you were told you could not have.
 // Both env names are read: HERMOSO_TOOLS is the current prefix, HEIST_TOOLS the pre-rebrand one that is live in

package/mcp/http.mjs

@@ -110,8 +110,8 @@ export function mountRemoteMcp(app, { verifyBearer, publicBaseUrl } = {}) {
   // `?tools=research,create` narrows the roster this connection advertises (see registerTools). Read here rather
   // than inside registerTools so BOTH the anonymous discovery handshake and a real session honour the same query,
   // and so an unknown group is refused at the door with the valid list instead of silently serving every group.
-  // ABSENT, the DEFAULT is every group except `ads` (2026-08-16) — 238 tools and ~66% of the schema weight, which
-  // takes an eagerly-loading client from ~235k tokens to ~83k. `?tools=all` restores the full roster.
+  // ABSENT, the DEFAULT is every group except `ads` and `analytics` (OPT_IN_TOOL_GROUPS) — together ~254k of the
+  // ~365k full roster, so an eagerly-loading client gets ~112k. `?tools=all` restores the full roster.
   // The scope fixed here is the STARTING roster, not a cage: `enable_tools` widens it mid-session and the SDK
   // notifies the client. That is deliberate — the old comment's "tools/list must not change under a live client"
   // was the right instinct for a scope the SERVER changes silently, and the wrong one for a change the CLIENT

package/mcp/registry.mjs

@@ -0,0 +1,172 @@
+// THE CLI'S ROUTE INTO THE FULL TOOL ROSTER — one implementation, shared with the stdio MCP twin.
+//
+// WHY THIS EXISTS. The CLI shipped 12 hand-written subcommands against a roster of several hundred registered
+// tools, so a terminal agent had to choose between the full surface with a fat tool manifest (MCP) and a cheap
+// manifest with a sliver of the product (CLI). That is the [[mcp-is-the-complete-surface]] defect one level down:
+// a capability reachable on one agent surface and not another. `hermoso tools` and `hermoso call` close it — the
+// agent greps for the one tool it needs and pays for that schema alone, instead of carrying every schema up front.
+//
+// IT IS THE SAME CODE PATH, NOT A SECOND SET OF RULES. We build a real McpServer, register the real tools with the
+// real registerTools(), and drive it with a real MCP Client over an in-memory transport. So argument validation,
+// confirm gates, spend gates, workspace scoping, result shaping and error text are byte-identical to what a Claude
+// Code / Cursor / claude.ai session gets. There is no CLI-side reimplementation that could drift, and in
+// particular no CLI-side way around a gate: a confirm-gated tool is confirm-gated from a terminal too, because it
+// is literally the same handler.
+//
+// FREE AND OFFLINE UNTIL A TOOL IS CALLED. Registration touches no network; only the tool's own handler does.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { registerTools, MCP_INSTRUCTIONS, TOOL_GROUP_NAMES, TOOL_GROUPS } from './tools.mjs';
+
+export { TOOL_GROUP_NAMES, TOOL_GROUPS };
+
+// THE CLI ALWAYS REGISTERS EVERY GROUP, AND DELIBERATELY IGNORES HERMOSO_TOOLS.
+//
+// The MCP default roster leaves `ads` out because a client that loads every schema eagerly cannot afford it — that
+// is a MANIFEST cost, and a shelling-out agent pays no manifest at all. Honouring HERMOSO_TOOLS here would mean an
+// agent whose MCP config narrows the roster gets `hermoso call create_google_ads_campaign` → "no such tool", which
+// is the exact parity hole this file was written to close. Scoping was never an authorization boundary either
+// (`enable_tools` turns any group on mid-session with no reconnect), so ignoring it takes nothing away.
+const ALL_GROUPS = [...TOOL_GROUP_NAMES];
+
+/**
+ * Register every tool against an in-process MCP server and return a connected client.
+ * Callers MUST await close() — the transport keeps the event loop alive otherwise.
+ */
+export async function openRegistry() {
+  const server = new McpServer({ name: 'hermoso-cli', version: '1.0.0' }, { instructions: MCP_INSTRUCTIONS });
+  registerTools(server, { only: ALL_GROUPS });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  const client = new Client({ name: 'hermoso-cli', version: '1.0.0' }, { capabilities: {} });
+  await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+  return {
+    client,
+    async close() { try { await client.close(); } catch {} try { await server.close(); } catch {} },
+  };
+}
+
+/** Every tool with its full JSON Schema, exactly as an MCP client sees it. Pages through the cursor. */
+export async function listTools(client) {
+  const out = [];
+  let cursor;
+  do {
+    const page = await client.listTools(cursor ? { cursor } : {});
+    out.push(...(page.tools || []));
+    cursor = page.nextCursor;
+  } while (cursor);
+  return out;
+}
+
+// ── GROUP MEMBERSHIP IS DERIVED BY RUNNING THE REGISTRY, NEVER BY A LIST ────────────────────────────────────────
+// A tool's group is the `server.group()` marker it was written under, and registerTools keeps that map private. So
+// we ask the only question it answers from outside: register once per group and see which tools come back ENABLED.
+// A hand-kept name list would go stale the day someone adds a tool, which is the failure this repo has shipped
+// more than once ([[prompt-rosters-go-stale]]).
+//
+// The stub MUST implement disable(): out-of-scope tools are registered and then disabled rather than skipped, so a
+// stub that throws on disable() reports every group as the full roster and every answer below is silently wrong.
+function rosterFor(only) {
+  const handles = new Map();
+  const mk = (name) => {
+    const h = { enabled: true, enable() { h.enabled = true; return h; }, disable() { h.enabled = false; return h; } };
+    if (name != null) handles.set(name, h);
+    return h;
+  };
+  registerTools({ registerTool: (n, def) => { const h = mk(n); h.def = def; return h; }, registerResource: () => mk(null) },
+    only ? { only } : {});
+  return handles;
+}
+
+// A tool registered above the first `server.group()` marker has group `undefined` and belongs to no scoped MCP
+// roster. It is still callable from the CLI (which registers every group), so it is REPORTED as `?` rather than
+// quietly filed under a real group — an unreachable tool and an ungrouped one are different problems and must not
+// look the same. Pulled out as its own function so a check can RUN it: no tool is ungrouped today
+// (`mcp-tool-scope-check` fails if one ever is), so the branch is unreachable through `inventory()` and a check
+// that could only assert it through the roster would be asserting nothing.
+export const groupLabel = (g) => (g === undefined || g === null ? '?' : g);
+
+/**
+ * The whole inventory in one pass-set: every registered name, its group, its title/description.
+ *
+ * ONE registration per group plus one for the full roster — 8 passes, ~0.9s, and every number in it is measured
+ * rather than declared.
+ */
+export function inventory() {
+  const full = rosterFor(ALL_GROUPS);
+  const groupOf = Object.create(null);
+  for (const g of ALL_GROUPS) {
+    for (const [name, h] of rosterFor([g])) {
+      // `core` rides in every scoped roster (a roster without discovery is undriveable), so the FIRST group that
+      // claims a tool wins and core is asked first — otherwise every core tool would be relabelled by the last
+      // group to include it.
+      if (h.enabled && groupOf[name] === undefined) groupOf[name] = g;
+    }
+  }
+  return [...full.entries()].map(([name, h]) => ({
+    name,
+    group: groupLabel(groupOf[name]),
+    title: h.def?.title || '',
+    description: String(h.def?.description || ''),
+  }));
+}
+
+// ── ARGUMENTS ──────────────────────────────────────────────────────────────────────────────────────────────────
+// Coerce a --flag string against the tool's own JSON Schema. The CLI can only carry strings, and the MCP handler
+// is strict about types, so `--durationSeconds 30` has to become a number somewhere. Doing it from the schema
+// means the rules come from the tool, not from a guess here.
+//
+// AN UNKNOWN FLAG IS REFUSED BY NAME, NEVER DROPPED. The SDK builds a non-strict z.object, so an unrecognised key
+// is silently stripped: a typo'd `--confrim true` would send a call with no confirmation and read as success.
+export function coerceArg(schema, key, raw) {
+  const prop = schema?.properties?.[key];
+  if (!prop) return { unknown: true };
+  const type = Array.isArray(prop.type) ? prop.type.find((t) => t !== 'null') : prop.type;
+  if (raw === true) { // a bare `--flag` with no value
+    if (type === 'boolean') return { ok: true, value: true };
+    return { message: `--${key} needs a value` };
+  }
+  const s = String(raw);
+  if (type === 'boolean') {
+    if (/^(true|yes|1|on)$/i.test(s)) return { ok: true, value: true };
+    if (/^(false|no|0|off)$/i.test(s)) return { ok: true, value: false };
+    return { message: `--${key} expects true or false, got "${s}"` };
+  }
+  if (type === 'number' || type === 'integer') {
+    const n = Number(s);
+    if (!Number.isFinite(n)) return { message: `--${key} expects a number, got "${s}"` };
+    return { ok: true, value: n };
+  }
+  if (type === 'array') {
+    // JSON first so an array of objects is still expressible; comma-splitting is the convenience for the common
+    // array-of-strings case and must not silently mangle anything richer.
+    if (s.trim().startsWith('[')) { try { return { ok: true, value: JSON.parse(s) }; } catch { /* fall through to split */ } }
+    const items = Array.isArray(prop.items) ? prop.items[0] : prop.items;
+    const itemType = items?.type;
+    const parts = s.split(',').map((v) => v.trim()).filter(Boolean);
+    if (itemType === 'number' || itemType === 'integer') {
+      const nums = parts.map(Number);
+      if (nums.some((n) => !Number.isFinite(n))) return { message: `--${key} expects a list of numbers, got "${s}"` };
+      return { ok: true, value: nums };
+    }
+    if (itemType === 'object') return { message: `--${key} takes objects. Pass it inside --json '{"${key}":[…]}'` };
+    return { ok: true, value: parts };
+  }
+  if (type === 'object') {
+    try { return { ok: true, value: JSON.parse(s) }; }
+    catch { return { message: `--${key} takes an object. Pass it inside --json '{"${key}":{…}}'` }; }
+  }
+  return { ok: true, value: s };
+}
+
+/** The properties a caller may pass, in schema order, with the required ones marked. */
+export function schemaFields(schema) {
+  const req = new Set(schema?.required || []);
+  return Object.entries(schema?.properties || {}).map(([name, p]) => ({
+    name,
+    required: req.has(name),
+    type: Array.isArray(p.type) ? p.type.join('|') : (p.type || (p.anyOf ? 'any' : '')),
+    enum: p.enum || null,
+    description: String(p.description || ''),
+  }));
+}