kloudy 1.0.0 → 1.0.1

package/AGENTS.md

@@ -0,0 +1,54 @@
+## For AI agents: how to use Kloudy
+
+The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, bundled in this package (npm version 1.0.1). `recommend` / `stack` and `bots ... --offline` read that snapshot (or the local cache if one exists). They do not call the network. Kloudy does not run an LLM to choose bots. Ranking is deterministic: the same goal returns the same JSON.
+
+Classes:
+
+- **A** — live HTTP MCP endpoints.
+- **B** — npx or uvx packages.
+- **O** — open source and Hugging Face listings.
+
+List modalities:
+
+```sh
+npx kloudy@latest bots modalities --offline
+```
+
+Commands:
+
+```sh
+npx kloudy@latest recommend "<goal>" --json
+npx kloudy@latest stack "<goal>" --json
+npx kloudy@latest bots search <words> --offline
+npx kloudy@latest bots get <id> --offline
+npx kloudy@latest agents
+npx kloudy@latest --help
+```
+
+`recommend` and `stack` are aliases. `--json` prints only a JSON object on stdout (`schema`: `kloudy.recommend/1`, `catalog`: `kloudy 1.0`, `version`: the package version). Without `--json` you get the same sections as text, including an Unmatched section when a part did not match.
+
+Each bot has `id`, `name`, `class` (`A`, `B`, or `O`), `command`, `license`, `description`, `why`, and `modalities`. `command` is what you run or connect to: an `npx ...` command, a `uvx ...` command, or a URL. `recommend` does not install or download anything. Use `bots get <id> --offline` to inspect a pick, then run the command only when you intend to.
+
+The goal is decomposed before matching. Clauses split on commas, semicolons, and the words `and` and `then`. Inside a clause, distinct modality keywords become separate parts. Each part gets the top bots for each modality it needs (up to five). Order is class A, then B, then O, then primary-modality hint, keyword hits, catalog score, and catalog index. A part with no modality or no catalog row is returned in `unmatched` with the part text and the reason `no modality or catalog match`. Parts are not dropped to make a partial stack look complete.
+
+Single-part example:
+
+```sh
+npx kloudy@latest recommend "voice assistant that transcribes phone calls" --json
+```
+
+One part, modality `audio`. First bot: `httpk:npm:mendelio-voice-mcp`, class B, MIT, command `npx -y mendelio-voice-mcp`.
+
+Multi-part example:
+
+```sh
+npx kloudy@latest recommend "voice assistant that transcribes calls, summarizes them, and stores them in a database" --json
+```
+
+Three parts:
+
+1. `voice assistant that transcribes calls` — `audio` — `httpk:npm:mendelio-voice-mcp` — `npx -y mendelio-voice-mcp`
+2. `summarizes them` — `text` — `httpk:mcp:ai.liquidagent.api:liquid-agent` — `https://api.liquidagent.ai/mcp`
+3. `stores them in a database` — `database_access` — `httpk:npm:microsoft:postgres-mcp` — `npx -y @microsoft/postgres-mcp`
+
+`weave a basket` in a larger goal is unmatched. It is reported, not omitted.

package/README.md

@@ -20,7 +20,65 @@ Interactive cards require a host that supports MCP Apps. The proxy relays the su
 
 The existing SDK exports remain available under `kloudy/*`. For the pre-0.4 specialized engine CLI commands documented below, use `kloudy legacy <command>` (for example, `kloudy legacy init my-app`). The original CLI is retained in `bin/kloudy.mjs`.
 
-Offline bot catalog: `npx kloudy bots list|search|get|sync|works|broken`. Kloudy 1.0 bundles the full passing catalog (13,440 listings: 26 verified class A, 11,528 untested class B, 1,886 OSS/HF). Search uses that bundled snapshot, then the local cache. `get` uses a live hit when the API has one, and falls back to that snapshot when the live call misses, including HTTP 404. `--offline` stays on the snapshot. Default `kloudy bots sync` still fetches `https://kloudy.ai/api/deployable-bots/export`; that production URL will not have this 1.0 catalog until a later deploy, so the published tarball does not depend on sync for class B.
+Offline bot catalog: `npx kloudy bots list|search|get|sync|works|broken|modalities`. Kloudy 1.0 bundles the full passing catalog (13,440 listings: 26 verified class A, 11,528 untested class B, 1,886 OSS/HF). Search uses that bundled snapshot, then the local cache. `get` uses a live hit when the API has one, and falls back to that snapshot when the live call misses, including HTTP 404. `--offline` stays on the snapshot. Default `kloudy bots sync` still fetches `https://kloudy.ai/api/deployable-bots/export`; that production URL will not have this 1.0 catalog until a later deploy, so the published tarball does not depend on sync for class B.
+
+## For AI agents: how to use Kloudy
+
+The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, shipped in this package (npm version 1.0.1). Recommend and the offline bots commands read that bundled snapshot, then the local cache. They do not call the network, and Kloudy does not run an LLM to pick a stack.
+
+Classes:
+
+- **A** — live HTTP MCP endpoints.
+- **B** — npx or uvx packages.
+- **O** — open source and Hugging Face listings.
+
+List the modality tags:
+
+```sh
+npx kloudy@latest bots modalities --offline
+```
+
+Turn a plain-language goal into a stack. `recommend` and `stack` are the same command. Add `--json` when you need parseable output (`schema` is `kloudy.recommend/1`).
+
+```sh
+npx kloudy@latest recommend "<goal>" --json
+npx kloudy@latest stack "<goal>" --json
+npx kloudy@latest bots search <words> --offline
+npx kloudy@latest bots get <id> --offline
+```
+
+Each recommended bot includes `id`, `class` (A, B, or O), `command`, `license`, a one-line `description`, and `why`. `command` is an `npx` or `uvx` invocation, or a URL for a live endpoint or source repo. Run or open that command when you want to install or connect. `recommend` itself does not install anything. Inspect a pick with `bots get` before running it.
+
+`recommend` splits the goal on commas, semicolons, and the words `and` and `then`, and it also splits a clause when keywords hit different modalities. You get one section per part, with the top bots in each needed modality (class A, then B, then O, then the same primary-modality, score, and index ordering as catalog search). A part with no modality or no catalog row stays in `unmatched` with the part text and a reason. It is not dropped.
+
+Single-part example:
+
+```sh
+npx kloudy@latest recommend "voice assistant that transcribes phone calls" --json
+```
+
+That goal is one audio part. The first of the five bots is `httpk:npm:mendelio-voice-mcp` (class B, MIT, `npx -y mendelio-voice-mcp`).
+
+Multi-part example:
+
+```sh
+npx kloudy@latest recommend "voice assistant that transcribes calls, summarizes them, and stores them in a database" --json
+```
+
+That becomes three parts, not one blended search:
+
+1. `voice assistant that transcribes calls` — `audio` — `httpk:npm:mendelio-voice-mcp` — `npx -y mendelio-voice-mcp`
+2. `summarizes them` — `text` — `httpk:mcp:ai.liquidagent.api:liquid-agent` — `https://api.liquidagent.ai/mcp`
+3. `stores them in a database` — `database_access` — `httpk:npm:microsoft:postgres-mcp` — `npx -y @microsoft/postgres-mcp`
+
+A leftover clause such as `weave a basket` is listed under Unmatched (`no modality or catalog match`) instead of disappearing.
+
+On first contact, read the agent guide and the command list:
+
+```sh
+npx kloudy@latest agents
+npx kloudy@latest --help
+```
 
 One-click Cursor / VS Code setup: https://kloudy.ai/install. Browser deep links ask the editor to install; opening a link is not proof that installation completed. ChatGPT requires its directory program; this package does not modify ChatGPT.
 

package/bin/entry.mjs

@@ -16,8 +16,10 @@ try{
   if(results.some(r=>r.state==='unchanged_error'))process.exitCode=1;
  }else if(args[0]==='mcp'&&args.length===1){await serveRemote();}
  else if(args[0]==='--version'){console.log(version);}
- else if(['--help','help'].includes(args[0]))console.log('npx kloudy                 Add to detected editors (asks before each write)\nnpx kloudy <question>      Ask the public Kloudy MCP endpoint\nnpx kloudy mcp             Remote MCP over local stdio\nnpx kloudy bots list|search|get|sync|works|broken|modalities\nnpx kloudy legacy <args>   Existing SDK/engine CLI commands\n\nFree discovery needs no key. For authorized account actions set KLOUDY_MCP_TOKEN privately; never put a key in command arguments. Node 20.19+ required.');
+ else if(['--help','help'].includes(args[0]))console.log('npx kloudy                 Add to detected editors (asks before each write)\nnpx kloudy <question>      Ask the public Kloudy MCP endpoint\nnpx kloudy mcp             Remote MCP over local stdio\nnpx kloudy recommend "<goal>" [--json]\nnpx kloudy stack "<goal>" [--json]\nnpx kloudy agents\nnpx kloudy bots list|search|get|sync|works|broken|modalities [--offline]\nnpx kloudy legacy <args>   Existing SDK/engine CLI commands\n\nFree discovery needs no key. For authorized account actions set KLOUDY_MCP_TOKEN privately; never put a key in command arguments. Node 20.19+ required.');
  else if(args[0]==='bots'){const {botsCommand}=await import('../src/bots.mjs');try{await botsCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'bots failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='recommend'||args[0]==='stack'){const {recommendCommand}=await import('../src/recommend.mjs');try{await recommendCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'recommend failed')+'\n');process.exitCode=1;}}
+ else if(args[0]==='agents'||args[0]==='agent'){const {agentsCommand}=await import('../src/recommend.mjs');try{agentsCommand();}catch(error){process.stderr.write((error?.message||'agents failed')+'\n');process.exitCode=1;}}
  else if(args[0]==='legacy'){process.argv.splice(2,1);await import('./kloudy.mjs');}
  else{if(args[0]?.startsWith('--'))throw Error('Unknown option');const result=await askRemote(args.join(' '));for(const c of result.content||[])if(c.type==='text')process.stdout.write((process.env.KLOUDY_MCP_TOKEN?c.text.replaceAll(process.env.KLOUDY_MCP_TOKEN,'[redacted]'):c.text)+'\n');if(result.isError)process.exitCode=1;}
 }catch{process.stderr.write('Kloudy could not complete the request. Check your connection or authorized key. No action was retried. Run npx kloudy --help.\n');process.exitCode=1;}

package/bin/kloudy.mjs

@@ -19,7 +19,7 @@ try{
  const connection=option('connection')||process.env.KLOUDY_CONNECTION;
  const project=option('project')||process.cwd(),decision=option('decision');
  if(command==='help'||command==='--help'){
-  console.log('Ask for Kloudy. One CLI, one MCP, tools appear when needed.\n\nkloudy models list [--endpoint URL] [--key-env NAME]\nkloudy models run NAME --prompt-file FILE [--max-tokens 128] [--allow-provider-charge]\nkloudy init my-app\nkloudy read https://example.com\nkloudy card /world\nkloudy convert https://example.com\nkloudy query "need" --connection FILE\nkloudy ask "goal" --connection FILE [--candidates FILE]\nkloudy assemble --selections FILE --connection FILE\nkloudy call NAME --inputs FILE [--selection ID] --connection FILE\nkloudy action chain.head --inputs FILE --connection FILE [--idempotency-key KEY]\nkloudy wallet-connect ethereum --connection FILE\nkloudy hosting [--budget-micros 100000000] --connection FILE\nkloudy wallet balance --connection FILE\nkloudy wallet top_up --amount 10.00 --connection FILE\nkloudy conversation read|append|sync --inputs FILE --connection FILE\nkloudy host --connection FILE\nkloudy status --connection FILE\nkloudy cancel --connection FILE\nkloudy mcp --connection FILE\nkloudy introduce [--project DIR] [--decision yes|no]\nkloudy install [--ide cursor|claude|vscode|codex] [--url HTTPS_URL] [--token-env NAME] [--connection FILE]\nkloudy wrap --config FILE [--port 8796]\nkloudy strings save NAME --selections FILE\nkloudy strings use NAME\nkloudy strings call NAME --tool ALIAS --inputs FILE\nkloudy strings list|prune\nkloudy strings keep|remove NAME\nkloudy login\nkloudy bots list|search|get|sync|works|broken\n\nRegister with email + short 2FA through the Core account service. Existing engine connections remain usable. Hosted registration is not supplied by this client package.');
+  console.log('Ask for Kloudy. One CLI, one MCP, tools appear when needed.\n\nkloudy models list [--endpoint URL] [--key-env NAME]\nkloudy models run NAME --prompt-file FILE [--max-tokens 128] [--allow-provider-charge]\nkloudy init my-app\nkloudy read https://example.com\nkloudy card /world\nkloudy convert https://example.com\nkloudy query "need" --connection FILE\nkloudy ask "goal" --connection FILE [--candidates FILE]\nkloudy assemble --selections FILE --connection FILE\nkloudy call NAME --inputs FILE [--selection ID] --connection FILE\nkloudy action chain.head --inputs FILE --connection FILE [--idempotency-key KEY]\nkloudy wallet-connect ethereum --connection FILE\nkloudy hosting [--budget-micros 100000000] --connection FILE\nkloudy wallet balance --connection FILE\nkloudy wallet top_up --amount 10.00 --connection FILE\nkloudy conversation read|append|sync --inputs FILE --connection FILE\nkloudy host --connection FILE\nkloudy status --connection FILE\nkloudy cancel --connection FILE\nkloudy mcp --connection FILE\nkloudy introduce [--project DIR] [--decision yes|no]\nkloudy install [--ide cursor|claude|vscode|codex] [--url HTTPS_URL] [--token-env NAME] [--connection FILE]\nkloudy wrap --config FILE [--port 8796]\nkloudy strings save NAME --selections FILE\nkloudy strings use NAME\nkloudy strings call NAME --tool ALIAS --inputs FILE\nkloudy strings list|prune\nkloudy strings keep|remove NAME\nkloudy login\nkloudy recommend <goal> [--json]\nkloudy stack <goal> [--json]\nkloudy agents\nkloudy bots list|search|get|sync|works|broken|modalities [--offline]\n\nRegister with email + short 2FA through the Core account service. Existing engine connections remain usable. Hosted registration is not supplied by this client package.');
  }else if(command==='models'){
   const action=args.shift(),endpoint=option('endpoint'),keyEnv=option('key-env'),file=option('prompt-file'),max=option('max-tokens');
   const allow=args.includes('--allow-provider-charge');if(allow)args.splice(args.indexOf('--allow-provider-charge'),1);
@@ -51,6 +51,12 @@ try{
  }else if(command==='bots'){
   const {botsCommand}=await import('../src/bots.mjs');
   try{await botsCommand(args);}catch(error){process.stderr.write((error?.message||'bots failed')+'\n');process.exitCode=1;}
+ }else if(command==='recommend'||command==='stack'){
+  const {recommendCommand}=await import('../src/recommend.mjs');
+  try{await recommendCommand(args);}catch(error){process.stderr.write((error?.message||'recommend failed')+'\n');process.exitCode=1;}
+ }else if(command==='agents'||command==='agent'){
+  const {agentsCommand}=await import('../src/recommend.mjs');
+  try{agentsCommand();}catch(error){process.stderr.write((error?.message||'agents failed')+'\n');process.exitCode=1;}
  }else{
   const walletAmount=option('amount'),budgetMicros=option('budget-micros'),idempotencyKey=option('idempotency-key');
   const candidatesFile=option('candidates'),inputsFile=option('inputs'),selectionsFile=option('selections'),selectionId=option('selection'),lane=option('lane')||'non_medical';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kloudy",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Ask for Kloudy: CLI, MCP and SDK clients for the same scoped engine session.",
   "type": "module",
   "license": "Apache-2.0",
@@ -33,12 +33,13 @@
     "src",
     "schemas",
     "README.md",
+    "AGENTS.md",
     "MCP-DEFAULT.md",
     "LICENSE"
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "check": "node --check bin/kloudy.mjs && node --check bin/entry.mjs && node --check src/bots.mjs && node --check src/client.mjs && npm test",
+    "check": "node --check bin/kloudy.mjs && node --check bin/entry.mjs && node --check src/bots.mjs && node --check src/recommend.mjs && node --check src/client.mjs && npm test",
     "bots:bundle": "node scripts/bundle-bots-catalog.mjs --subset full",
     "start": "node bin/kloudy.mjs",
     "proof": "node scripts/prove.mjs",

package/schemas/kloudy.deployable-bot.schema.json

@@ -1,80 +1,80 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kloudy.ai/schemas/kloudy.deployable-bot.schema.json",
-  "title": "kloudy.deployable-bot/1",
-  "type": "object",
-  "required": [
-    "id",
-    "name",
-    "kind",
-    "modalities"
-  ],
-  "properties": {
-    "id": {
-      "type": "string"
-    },
-    "name": {
-      "type": "string"
-    },
-    "kind": {
-      "type": "string",
-      "enum": [
-        "http",
-        "npx",
-        "uvx",
-        "botboozle",
-        "hf"
-      ]
-    },
-    "tier": {
-      "type": "string"
-    },
-    "status": {
-      "type": "string"
-    },
-    "endpoints": {
-      "type": "array"
-    },
-    "free": {
-      "type": "boolean"
-    },
-    "devices": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "caps": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "license": {
-      "type": "string"
-    },
-    "source_url": {
-      "type": "string"
-    },
-    "score": {
-      "type": "number"
-    },
-    "modalities": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "string",
-        "minLength": 1
-      },
-      "description": "Every fitting modality tag. Multi-select. Known values include text, code, code_execution, embedding, image, image_generation, audio, voice_generation, video, multimodal, translation, search, database_access, file_system, browser_automation, api_calls, scheduling, notifications, auth_encryption, data_analysis, document_processing, robotics, agent_tools; other tags that appear are allowed."
-    },
-    "modality_primary": {
-      "type": [
-        "string",
-        "null"
-      ],
-      "description": "Sort hint only; never used as a filter."
-    }
-  },
-  "additionalProperties": true
-}
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kloudy.ai/schemas/kloudy.deployable-bot.schema.json",
+  "title": "kloudy.deployable-bot/1",
+  "type": "object",
+  "required": [
+    "id",
+    "name",
+    "kind",
+    "modalities"
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "http",
+        "npx",
+        "uvx",
+        "botboozle",
+        "hf"
+      ]
+    },
+    "tier": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "endpoints": {
+      "type": "array"
+    },
+    "free": {
+      "type": "boolean"
+    },
+    "devices": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "caps": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "license": {
+      "type": "string"
+    },
+    "source_url": {
+      "type": "string"
+    },
+    "score": {
+      "type": "number"
+    },
+    "modalities": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Every fitting modality tag. Multi-select. Known values include text, code, code_execution, embedding, image, image_generation, audio, voice_generation, video, multimodal, translation, search, database_access, file_system, browser_automation, api_calls, scheduling, notifications, auth_encryption, data_analysis, document_processing, robotics, agent_tools; other tags that appear are allowed."
+    },
+    "modality_primary": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Sort hint only; never used as a filter."
+    }
+  },
+  "additionalProperties": true
+}

package/src/bots.mjs

@@ -1,144 +1,144 @@
-// `kloudy bots` — offline-first deployable-bots catalog.
-//   kloudy bots list   [--status verified|untested|reported-broken] [--kind http|npx|uvx|botboozle|hf] [--modality m] [--all-modalities] [--device d] [--limit n] [--offset n] [--json]
-//   kloudy bots search <words> [same flags]
-//   kloudy bots get    <id> [--json]
-//   kloudy bots sync                      download the full catalog to the local cache
-//   kloudy bots probe  <id>               HTTPK: MCP initialize + tools/list against a verified HTTP bot
-//   --api <base> or KLOUDY_API=<base>     use that server (e.g. http://127.0.0.1:4360) live, cache as fallback
-//   kloudy bots works|broken <id>         tell Kloudy whether a bot worked for you (free, keyless, no personal data)
-// Lookup order: bundled catalog (if this build ships one) -> ~/.cache/kloudy/deployable-bots.json.gz -> live API.
-import {readFileSync,writeFileSync,mkdirSync,existsSync} from 'node:fs';
-import {gunzipSync} from 'node:zlib';
-import {homedir} from 'node:os';
-import {join} from 'node:path';
-import {modalityWant,rowMatchesModalities,primarySortHint} from './modalities.mjs';
-let BASE=process.env.KLOUDY_BOTS_API||(process.env.KLOUDY_API?process.env.KLOUDY_API.replace(/\/$/,'')+'/api/deployable-bots':'https://kloudy.ai/api/deployable-bots');
-let EXPLICIT=!!(process.env.KLOUDY_BOTS_API||process.env.KLOUDY_API);
-const cacheDir=()=>process.env.KLOUDY_CACHE_DIR||join(process.env.XDG_CACHE_HOME||join(homedir(),'.cache'),'kloudy');
-const cacheFile=()=>join(cacheDir(),'deployable-bots.json.gz');
-const bundled=[new URL('./deployable-bots.json.gz',import.meta.url)];
-const words=s=>String(s||'').toLowerCase().split(/[^\p{L}\p{N}_]+/u).filter(w=>w.length>1);
-function decode(buf){const d=JSON.parse(gunzipSync(buf));return d.bots.map(r=>{const [id,name,kind,cls,endpoint,license,url,score,caps,targets,botboozle,source,meta]=r;return {id,name,kind,cls,endpoint,license,url,score,caps,targets,botboozle,source,meta,modalities:meta?.modalities||[],modality_primary:meta?.modalityPrimary||null};}).filter(b=>b.cls!=='D');}
-export function loadLocal(){
-  for(const p of [cacheFile(),...bundled])try{if(existsSync(p))return {source:String(p),bots:decode(readFileSync(p))};}catch{}
-  return null;
-}
-
-function localEndpoints(b){
-  if(Array.isArray(b.meta?.connect)&&b.meta.connect.length){
-    return b.meta.connect.map(ep=>{
-      const out={type:ep.type};
-      if(ep.url)out.url=ep.url;
-      if(ep.value)out.command=ep.value;
-      if(ep.os)out.os=ep.os;
-      if(ep.protocol)out.protocol=ep.protocol;
-      return out;
-    });
-  }
-  if(b.kind==='http')return [{type:'mcp-http',url:b.endpoint}];
-  return [{type:b.kind==='hf'?b.kind:'local-'+b.kind,command:b.endpoint}];
-}
-function formatHfGet(bot){
-  const h=bot.meta?.hf||{};
-  const lines=[`${bot.id}  [hf]${bot.license?'  '+bot.license:''}`];
-  if(h.repo)lines.push('Repo: '+h.repo);
-  if(h.revision)lines.push('Revision: '+h.revision);
-  if(h.total_size)lines.push('Size: '+h.total_size);
-  if(h.runner)lines.push('Runner: '+h.runner);
-  if(bot.license)lines.push('License: '+bot.license);
-  lines.push('');
-  lines.push('Connect (files are not downloaded automatically; say yes before any fetch):');
-  const steps=(bot.meta?.connect||[]).filter(ep=>ep.type!=='source');
-  if(!steps.length&&bot.endpoint)lines.push('  '+bot.endpoint);
-  for(const ep of steps){
-    const val=ep.value||ep.url||'';
-    const os=ep.os?` (${ep.os})`:'';
-    if(val)lines.push(`  [${ep.type}${os}] ${val}`);
-  }
-  if(bot.url)lines.push('Source: '+bot.url);
-  lines.push('');
-  lines.push('Nothing is installed or downloaded until you say yes.');
-  return lines.join('\n');
-}
-
-const TIER={A:0,C:1,O:2,B:3};
-export function localSearch(bots,{q='',status,kind,device,modality,modalities,allModalities=false,limit=25,offset=0}={}){
-  const terms=words(q);let pool=bots.map((b,i)=>({b,i,hits:terms.filter(t=>(b.name+' '+b.id+' '+b.caps.join(' ')).toLowerCase().includes(t)).length}));
-  if(terms.length)pool=pool.filter(x=>x.hits);
-  pool=pool.map(x=>({...x,status:x.b.cls==='A'?'verified':'untested'}));
-  if(status)pool=pool.filter(x=>x.status===status);if(kind)pool=pool.filter(x=>x.b.kind===kind);if(device)pool=pool.filter(x=>x.b.targets.includes(device));
-  const want=modalityWant(modality||modalities);
-  if(want.length)pool=pool.filter(x=>rowMatchesModalities(x.b.modalities,want,{all:!!allModalities}));
-  pool.sort((x,y)=>TIER[x.b.cls]-TIER[y.b.cls]||primarySortHint(y.b.modality_primary,want)-primarySortHint(x.b.modality_primary,want)||y.hits-x.hits||y.b.score-x.b.score||x.i-y.i);
-  return {matched:pool.length,offset,items:pool.slice(offset,offset+limit).map(({b,status})=>({id:b.id,name:b.name,kind:b.kind,status,endpoints:localEndpoints(b),free:true,needs_botboozle:!!b.botboozle,works_count:null,broken_count:null,license:b.license,source_url:b.url,devices:b.targets,modalities:b.modalities||[],modality_primary:b.modality_primary||null,meta:b.meta||undefined}))};
-}
-async function remote(path,init){const r=await fetch(BASE+path,{...init,signal:AbortSignal.timeout(8000)});const body=await r.json().catch(()=>({}));if(!r.ok)throw Object.assign(new Error(body.error||'HTTP '+r.status),{status:r.status});return body;}
-// HTTPK fetch: MCP streamable-http initialize + tools/list (read-only; no tools are called).
-export async function mcpProbe(url){
-  const h={'content-type':'application/json',accept:'application/json, text/event-stream'};
-  const rpc=async(body,extra={})=>{const r=await fetch(url,{method:'POST',headers:{...h,...extra},body:JSON.stringify(body),signal:AbortSignal.timeout(15000)});
-    const t=await r.text();if(!r.ok&&r.status!==202)throw new Error('MCP HTTP '+r.status);
-    const msg=r.headers.get('content-type')?.includes('event-stream')?t.split('\n').filter(l=>l.startsWith('data:')).map(l=>{try{return JSON.parse(l.slice(5))}catch{return null}}).find(m=>m&&m.id===body.id):t?JSON.parse(t):null;
-    return {msg,session:r.headers.get('mcp-session-id')};};
-  const init=await rpc({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2025-06-18',capabilities:{},clientInfo:{name:'kloudy-bots',version:'0.1'}}});
-  const s=init.session?{'mcp-session-id':init.session}:{};
-  await fetch(url,{method:'POST',headers:{...h,...s},body:JSON.stringify({jsonrpc:'2.0',method:'notifications/initialized'}),signal:AbortSignal.timeout(15000)}).catch(()=>{});
-  const list=await rpc({jsonrpc:'2.0',id:2,method:'tools/list',params:{}},s);
-  if(init.msg?.error)throw new Error('initialize: '+init.msg.error.message);
-  return {protocol:init.msg?.result?.protocolVersion,server:init.msg?.result?.serverInfo,tools:(list.msg?.result?.tools||[]).map(t=>({name:t.name,description:(t.description||'').slice(0,160)}))};
-}
-export function flags(args){const o={_:[]};for(let i=0;i<args.length;i++){const a=args[i];if(a.startsWith('--')){const k=a.slice(2);if(k==='json'||k==='offline'||k==='live'||k==='all-modalities'){o[k==='all-modalities'?'allModalities':k]=true;}else if(k==='modality'||k==='modalities'){const v=args[++i];o.modality=o.modality||[];if(v!=null)o.modality.push(...modalityWant(v));}else o[k]=args[++i];}else o._.push(a);}return o;}
-const line=b=>`${b.status==='verified'?'✔':b.status==='reported-broken'?'✖':'·'} ${b.id}  [${b.kind}${b.works_count!=null?` +${b.works_count}/-${b.broken_count}`:''}]  ${b.endpoints[0].url||b.endpoints[0].command}`;
-export async function botsCommand(args,opts={}){
-  const out=opts.out||(s=>console.log(s));
-  const [sub='list',...rest]=args,o=flags(rest);
-  if(o.api){BASE=o.api.replace(/\/$/,'')+(/\/api\/deployable-bots$/.test(o.api)?'':'/api/deployable-bots');EXPLICIT=true;}
-  const limit=Number(o.limit||25),offset=Number(o.offset||0);
-  const print=(r,src)=>{if(o.json)return out(JSON.stringify({...r,source:src},null,2));out(`${r.matched} bots (${src})`);for(const b of r.items)out(line(b));if(r.matched>offset+r.items.length)out(`more: --offset ${offset+r.items.length}`);};
-  if(sub==='sync'){const r=await fetch(BASE+'/export',{signal:AbortSignal.timeout(60000)});if(!r.ok)throw new Error('Sync failed: HTTP '+r.status);
-    const {gzipSync}=await import('node:zlib');const text=await r.text();mkdirSync(cacheDir(),{recursive:true});writeFileSync(cacheFile(),gzipSync(text));out(`cached ${decode(gzipSync(text)).length} bots at ${cacheFile()}`);return;}
-  if(sub==='works'||sub==='broken'){const id=o._[0];if(!id)throw new Error(`Usage: kloudy bots ${sub} <id>`);
-    const r=await remote('/feedback',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({id,works:sub==='works'})});out(`thanks — recorded "${sub}" for ${r.id}`);return;}
-  if(sub==='probe'){const id=o._[0];if(!id)throw new Error('Usage: kloudy bots probe <id>');
-    let bot;try{bot=(await remote('/'+encodeURIComponent(id))).bot;}catch{const l=loadLocal();bot=l&&localSearch(l.bots.filter(b=>b.id===id)).items[0];}
-    if(!bot)throw new Error('Unknown bot id.');const ep=bot.endpoints[0];if(!ep.url)throw new Error('probe supports HTTP bots; local bots run with: '+ep.command);
-    const r=await mcpProbe(ep.url);if(o.json)return out(JSON.stringify(r,null,2));
-    out(`${bot.id} -> ${ep.url}\nserver: ${r.server?.name||'?'} ${r.server?.version||''} (protocol ${r.protocol||'?'})\ntools (${r.tools.length}): ${r.tools.map(t=>t.name).join(', ')}`);return;}
-  if(sub==='get'){const id=o._[0];if(!id)throw new Error('Usage: kloudy bots get <id>');
-    let bot=null, local=loadLocal();
-    if(!o.offline)try{bot=(await remote('/'+encodeURIComponent(id))).bot;}catch{}
-    if(!bot){const hit=local&&localSearch(local.bots.filter(b=>b.id===id)).items[0];if(!hit)throw new Error('Unknown bot id (offline). Run `kloudy bots sync`.');bot={...hit,meta:hit.meta||local.bots.find(b=>b.id===id)?.meta};}
-    const raw=local&&local.bots.find(b=>b.id===id);
-    if(raw){bot.meta=bot.meta||raw.meta;bot.targets=bot.targets||raw.targets;}
-    if(bot.kind==='hf'||raw?.kind==='hf'){
-      const full=raw?{...raw,...bot,meta:bot.meta||raw.meta,url:bot.source_url||bot.url||raw.url}:bot;
-      if(o.json)return out(JSON.stringify(bot,null,2));
-      return out(formatHfGet(full));
-    }
-    return out(JSON.stringify(bot,null,2));}
-  if(sub==='modalities'){
-    const l=loadLocal();
-    if(!l)throw new Error('No local catalog. Run `kloudy bots sync`.');
-    const counts=new Map();
-    let tagged=0,untagged=0;
-    for(const b of l.bots){
-      const mods=b.modalities||[];
-      if(!mods.length){untagged++;continue;}
-      tagged++;
-      for(const m of mods)counts.set(m,(counts.get(m)||0)+1);
-    }
-    const items=[...counts.entries()].sort((a,c)=>c[1]-a[1]||a[0].localeCompare(c[0])).map(([modality,count])=>({modality,count}));
-    if(o.json)return out(JSON.stringify({total:l.bots.length,tagged,untagged,items},null,2));
-    out(`${items.length} modalities across ${tagged} tagged bots`+(untagged?` (${untagged} untagged)`:''));
-    for(const it of items)out(`${it.count}\t${it.modality}`);
-    return;
-  }
-  if(sub!=='list'&&sub!=='search')throw new Error('Usage: kloudy bots list|search|get|sync|works|broken|modalities');
-  const q=sub==='search'?o._.join(' '):'';const query={q,status:o.status,kind:o.kind,device:o.device,modality:o.modality||o.modalities,allModalities:!!o.allModalities,limit,offset};
-  const l=loadLocal();
-  // Offline first: answer from bundled/cached data; the live API adds user-reported status when reachable and the cache is missing.
-  if(!o.offline&&(EXPLICIT||o.live))try{const p=new URLSearchParams(Object.entries({q,status:o.status,kind:o.kind,device:o.device,modality:Array.isArray(o.modality)?o.modality.join(','):o.modality||o.modalities,all_modalities:o.allModalities?'true':undefined,intent:o.intent,tier:o.tier,limit,offset}).filter(([,v])=>v!=null&&v!==''));return print(await remote('?'+p),'live: '+BASE);}catch(e){if(!l)throw e;}
-  if(l||o.offline){if(!l)throw new Error('No local catalog. Run `kloudy bots sync`.');return print(localSearch(l.bots,query),'local: '+l.source);}
-  const p=new URLSearchParams(Object.entries({q,status:o.status,kind:o.kind,device:o.device,modality:Array.isArray(o.modality)?o.modality.join(','):o.modality||o.modalities,all_modalities:o.allModalities?'true':undefined,intent:o.intent,tier:o.tier,limit,offset}).filter(([,v])=>v!=null&&v!==''));
-  return print(await remote('?'+p),'live');
-}
+// `kloudy bots` — offline-first deployable-bots catalog.
+//   kloudy bots list   [--status verified|untested|reported-broken] [--kind http|npx|uvx|botboozle|hf] [--modality m] [--all-modalities] [--device d] [--limit n] [--offset n] [--json]
+//   kloudy bots search <words> [same flags]
+//   kloudy bots get    <id> [--json]
+//   kloudy bots sync                      download the full catalog to the local cache
+//   kloudy bots probe  <id>               HTTPK: MCP initialize + tools/list against a verified HTTP bot
+//   --api <base> or KLOUDY_API=<base>     use that server (e.g. http://127.0.0.1:4360) live, cache as fallback
+//   kloudy bots works|broken <id>         tell Kloudy whether a bot worked for you (free, keyless, no personal data)
+// Lookup order: bundled catalog (if this build ships one) -> ~/.cache/kloudy/deployable-bots.json.gz -> live API.
+import {readFileSync,writeFileSync,mkdirSync,existsSync} from 'node:fs';
+import {gunzipSync} from 'node:zlib';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+import {modalityWant,rowMatchesModalities,primarySortHint} from './modalities.mjs';
+let BASE=process.env.KLOUDY_BOTS_API||(process.env.KLOUDY_API?process.env.KLOUDY_API.replace(/\/$/,'')+'/api/deployable-bots':'https://kloudy.ai/api/deployable-bots');
+let EXPLICIT=!!(process.env.KLOUDY_BOTS_API||process.env.KLOUDY_API);
+const cacheDir=()=>process.env.KLOUDY_CACHE_DIR||join(process.env.XDG_CACHE_HOME||join(homedir(),'.cache'),'kloudy');
+const cacheFile=()=>join(cacheDir(),'deployable-bots.json.gz');
+const bundled=[new URL('./deployable-bots.json.gz',import.meta.url)];
+const words=s=>String(s||'').toLowerCase().split(/[^\p{L}\p{N}_]+/u).filter(w=>w.length>1);
+function decode(buf){const d=JSON.parse(gunzipSync(buf));return d.bots.map(r=>{const [id,name,kind,cls,endpoint,license,url,score,caps,targets,botboozle,source,meta]=r;return {id,name,kind,cls,endpoint,license,url,score,caps,targets,botboozle,source,meta,modalities:meta?.modalities||[],modality_primary:meta?.modalityPrimary||null};}).filter(b=>b.cls!=='D');}
+export function loadLocal(){
+  for(const p of [cacheFile(),...bundled])try{if(existsSync(p))return {source:String(p),bots:decode(readFileSync(p))};}catch{}
+  return null;
+}
+
+export function localEndpoints(b){
+  if(Array.isArray(b.meta?.connect)&&b.meta.connect.length){
+    return b.meta.connect.map(ep=>{
+      const out={type:ep.type};
+      if(ep.url)out.url=ep.url;
+      if(ep.value)out.command=ep.value;
+      if(ep.os)out.os=ep.os;
+      if(ep.protocol)out.protocol=ep.protocol;
+      return out;
+    });
+  }
+  if(b.kind==='http')return [{type:'mcp-http',url:b.endpoint}];
+  return [{type:b.kind==='hf'?b.kind:'local-'+b.kind,command:b.endpoint}];
+}
+function formatHfGet(bot){
+  const h=bot.meta?.hf||{};
+  const lines=[`${bot.id}  [hf]${bot.license?'  '+bot.license:''}`];
+  if(h.repo)lines.push('Repo: '+h.repo);
+  if(h.revision)lines.push('Revision: '+h.revision);
+  if(h.total_size)lines.push('Size: '+h.total_size);
+  if(h.runner)lines.push('Runner: '+h.runner);
+  if(bot.license)lines.push('License: '+bot.license);
+  lines.push('');
+  lines.push('Connect (files are not downloaded automatically; say yes before any fetch):');
+  const steps=(bot.meta?.connect||[]).filter(ep=>ep.type!=='source');
+  if(!steps.length&&bot.endpoint)lines.push('  '+bot.endpoint);
+  for(const ep of steps){
+    const val=ep.value||ep.url||'';
+    const os=ep.os?` (${ep.os})`:'';
+    if(val)lines.push(`  [${ep.type}${os}] ${val}`);
+  }
+  if(bot.url)lines.push('Source: '+bot.url);
+  lines.push('');
+  lines.push('Nothing is installed or downloaded until you say yes.');
+  return lines.join('\n');
+}
+
+const TIER={A:0,C:1,O:2,B:3};
+export function localSearch(bots,{q='',status,kind,device,modality,modalities,allModalities=false,limit=25,offset=0}={}){
+  const terms=words(q);let pool=bots.map((b,i)=>({b,i,hits:terms.filter(t=>(b.name+' '+b.id+' '+b.caps.join(' ')).toLowerCase().includes(t)).length}));
+  if(terms.length)pool=pool.filter(x=>x.hits);
+  pool=pool.map(x=>({...x,status:x.b.cls==='A'?'verified':'untested'}));
+  if(status)pool=pool.filter(x=>x.status===status);if(kind)pool=pool.filter(x=>x.b.kind===kind);if(device)pool=pool.filter(x=>x.b.targets.includes(device));
+  const want=modalityWant(modality||modalities);
+  if(want.length)pool=pool.filter(x=>rowMatchesModalities(x.b.modalities,want,{all:!!allModalities}));
+  pool.sort((x,y)=>TIER[x.b.cls]-TIER[y.b.cls]||primarySortHint(y.b.modality_primary,want)-primarySortHint(x.b.modality_primary,want)||y.hits-x.hits||y.b.score-x.b.score||x.i-y.i);
+  return {matched:pool.length,offset,items:pool.slice(offset,offset+limit).map(({b,status})=>({id:b.id,name:b.name,kind:b.kind,status,endpoints:localEndpoints(b),free:true,needs_botboozle:!!b.botboozle,works_count:null,broken_count:null,license:b.license,source_url:b.url,devices:b.targets,modalities:b.modalities||[],modality_primary:b.modality_primary||null,meta:b.meta||undefined}))};
+}
+async function remote(path,init){const r=await fetch(BASE+path,{...init,signal:AbortSignal.timeout(8000)});const body=await r.json().catch(()=>({}));if(!r.ok)throw Object.assign(new Error(body.error||'HTTP '+r.status),{status:r.status});return body;}
+// HTTPK fetch: MCP streamable-http initialize + tools/list (read-only; no tools are called).
+export async function mcpProbe(url){
+  const h={'content-type':'application/json',accept:'application/json, text/event-stream'};
+  const rpc=async(body,extra={})=>{const r=await fetch(url,{method:'POST',headers:{...h,...extra},body:JSON.stringify(body),signal:AbortSignal.timeout(15000)});
+    const t=await r.text();if(!r.ok&&r.status!==202)throw new Error('MCP HTTP '+r.status);
+    const msg=r.headers.get('content-type')?.includes('event-stream')?t.split('\n').filter(l=>l.startsWith('data:')).map(l=>{try{return JSON.parse(l.slice(5))}catch{return null}}).find(m=>m&&m.id===body.id):t?JSON.parse(t):null;
+    return {msg,session:r.headers.get('mcp-session-id')};};
+  const init=await rpc({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2025-06-18',capabilities:{},clientInfo:{name:'kloudy-bots',version:'0.1'}}});
+  const s=init.session?{'mcp-session-id':init.session}:{};
+  await fetch(url,{method:'POST',headers:{...h,...s},body:JSON.stringify({jsonrpc:'2.0',method:'notifications/initialized'}),signal:AbortSignal.timeout(15000)}).catch(()=>{});
+  const list=await rpc({jsonrpc:'2.0',id:2,method:'tools/list',params:{}},s);
+  if(init.msg?.error)throw new Error('initialize: '+init.msg.error.message);
+  return {protocol:init.msg?.result?.protocolVersion,server:init.msg?.result?.serverInfo,tools:(list.msg?.result?.tools||[]).map(t=>({name:t.name,description:(t.description||'').slice(0,160)}))};
+}
+export function flags(args){const o={_:[]};for(let i=0;i<args.length;i++){const a=args[i];if(a.startsWith('--')){const k=a.slice(2);if(k==='json'||k==='offline'||k==='live'||k==='all-modalities'){o[k==='all-modalities'?'allModalities':k]=true;}else if(k==='modality'||k==='modalities'){const v=args[++i];o.modality=o.modality||[];if(v!=null)o.modality.push(...modalityWant(v));}else o[k]=args[++i];}else o._.push(a);}return o;}
+const line=b=>`${b.status==='verified'?'✔':b.status==='reported-broken'?'✖':'·'} ${b.id}  [${b.kind}${b.works_count!=null?` +${b.works_count}/-${b.broken_count}`:''}]  ${b.endpoints[0].url||b.endpoints[0].command}`;
+export async function botsCommand(args,opts={}){
+  const out=opts.out||(s=>console.log(s));
+  const [sub='list',...rest]=args,o=flags(rest);
+  if(o.api){BASE=o.api.replace(/\/$/,'')+(/\/api\/deployable-bots$/.test(o.api)?'':'/api/deployable-bots');EXPLICIT=true;}
+  const limit=Number(o.limit||25),offset=Number(o.offset||0);
+  const print=(r,src)=>{if(o.json)return out(JSON.stringify({...r,source:src},null,2));out(`${r.matched} bots (${src})`);for(const b of r.items)out(line(b));if(r.matched>offset+r.items.length)out(`more: --offset ${offset+r.items.length}`);};
+  if(sub==='sync'){const r=await fetch(BASE+'/export',{signal:AbortSignal.timeout(60000)});if(!r.ok)throw new Error('Sync failed: HTTP '+r.status);
+    const {gzipSync}=await import('node:zlib');const text=await r.text();mkdirSync(cacheDir(),{recursive:true});writeFileSync(cacheFile(),gzipSync(text));out(`cached ${decode(gzipSync(text)).length} bots at ${cacheFile()}`);return;}
+  if(sub==='works'||sub==='broken'){const id=o._[0];if(!id)throw new Error(`Usage: kloudy bots ${sub} <id>`);
+    const r=await remote('/feedback',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({id,works:sub==='works'})});out(`thanks — recorded "${sub}" for ${r.id}`);return;}
+  if(sub==='probe'){const id=o._[0];if(!id)throw new Error('Usage: kloudy bots probe <id>');
+    let bot;try{bot=(await remote('/'+encodeURIComponent(id))).bot;}catch{const l=loadLocal();bot=l&&localSearch(l.bots.filter(b=>b.id===id)).items[0];}
+    if(!bot)throw new Error('Unknown bot id.');const ep=bot.endpoints[0];if(!ep.url)throw new Error('probe supports HTTP bots; local bots run with: '+ep.command);
+    const r=await mcpProbe(ep.url);if(o.json)return out(JSON.stringify(r,null,2));
+    out(`${bot.id} -> ${ep.url}\nserver: ${r.server?.name||'?'} ${r.server?.version||''} (protocol ${r.protocol||'?'})\ntools (${r.tools.length}): ${r.tools.map(t=>t.name).join(', ')}`);return;}
+  if(sub==='get'){const id=o._[0];if(!id)throw new Error('Usage: kloudy bots get <id>');
+    let bot=null, local=loadLocal();
+    if(!o.offline)try{bot=(await remote('/'+encodeURIComponent(id))).bot;}catch{}
+    if(!bot){const hit=local&&localSearch(local.bots.filter(b=>b.id===id)).items[0];if(!hit)throw new Error('Unknown bot id (offline). Run `kloudy bots sync`.');bot={...hit,meta:hit.meta||local.bots.find(b=>b.id===id)?.meta};}
+    const raw=local&&local.bots.find(b=>b.id===id);
+    if(raw){bot.meta=bot.meta||raw.meta;bot.targets=bot.targets||raw.targets;}
+    if(bot.kind==='hf'||raw?.kind==='hf'){
+      const full=raw?{...raw,...bot,meta:bot.meta||raw.meta,url:bot.source_url||bot.url||raw.url}:bot;
+      if(o.json)return out(JSON.stringify(bot,null,2));
+      return out(formatHfGet(full));
+    }
+    return out(JSON.stringify(bot,null,2));}
+  if(sub==='modalities'){
+    const l=loadLocal();
+    if(!l)throw new Error('No local catalog. Run `kloudy bots sync`.');
+    const counts=new Map();
+    let tagged=0,untagged=0;
+    for(const b of l.bots){
+      const mods=b.modalities||[];
+      if(!mods.length){untagged++;continue;}
+      tagged++;
+      for(const m of mods)counts.set(m,(counts.get(m)||0)+1);
+    }
+    const items=[...counts.entries()].sort((a,c)=>c[1]-a[1]||a[0].localeCompare(c[0])).map(([modality,count])=>({modality,count}));
+    if(o.json)return out(JSON.stringify({total:l.bots.length,tagged,untagged,items},null,2));
+    out(`${items.length} modalities across ${tagged} tagged bots`+(untagged?` (${untagged} untagged)`:''));
+    for(const it of items)out(`${it.count}\t${it.modality}`);
+    return;
+  }
+  if(sub!=='list'&&sub!=='search')throw new Error('Usage: kloudy bots list|search|get|sync|works|broken|modalities');
+  const q=sub==='search'?o._.join(' '):'';const query={q,status:o.status,kind:o.kind,device:o.device,modality:o.modality||o.modalities,allModalities:!!o.allModalities,limit,offset};
+  const l=loadLocal();
+  // Offline first: answer from bundled/cached data; the live API adds user-reported status when reachable and the cache is missing.
+  if(!o.offline&&(EXPLICIT||o.live))try{const p=new URLSearchParams(Object.entries({q,status:o.status,kind:o.kind,device:o.device,modality:Array.isArray(o.modality)?o.modality.join(','):o.modality||o.modalities,all_modalities:o.allModalities?'true':undefined,intent:o.intent,tier:o.tier,limit,offset}).filter(([,v])=>v!=null&&v!==''));return print(await remote('?'+p),'live: '+BASE);}catch(e){if(!l)throw e;}
+  if(l||o.offline){if(!l)throw new Error('No local catalog. Run `kloudy bots sync`.');return print(localSearch(l.bots,query),'local: '+l.source);}
+  const p=new URLSearchParams(Object.entries({q,status:o.status,kind:o.kind,device:o.device,modality:Array.isArray(o.modality)?o.modality.join(','):o.modality||o.modalities,all_modalities:o.allModalities?'true':undefined,intent:o.intent,tier:o.tier,limit,offset}).filter(([,v])=>v!=null&&v!==''));
+  return print(await remote('?'+p),'live');
+}

package/src/modalities.mjs

@@ -1,27 +1,28 @@
-// Multi-select modality matching for `kloudy bots`.
-// `--modality <m>` may be repeated. Default match is ANY (OR). `--all-modalities` switches to AND.
-// `primary` / modality_primary is a sort hint only; it never filters.
-export const KNOWN_MODALITIES=['text','code','code_execution','embedding','image','image_generation','audio','voice_generation','video','multimodal','translation','search','database_access','file_system','browser_automation','api_calls','scheduling','notifications','auth_encryption','data_analysis','document_processing','robotics','agent_tools','web','data','cloud','finance','productivity','comms','security','maps'];
-
-export function modalityWant(value){
-  if(value==null||value==='')return [];
-  const raw=Array.isArray(value)?value:[value];
-  const out=[];
-  for(const v of raw){
-    for(const part of String(v).split(',')){
-      const s=part.trim();
-      if(s&&!out.includes(s))out.push(s);
-    }
-  }
-  return out;
-}
-
-export function rowMatchesModalities(have,want,{all=false}={}){
-  if(!want.length)return true;
-  const set=Array.isArray(have)?have:[];
-  return all?want.every(m=>set.includes(m)):want.some(m=>set.includes(m));
-}
-
-export function primarySortHint(primary,want){
-  return primary&&want.includes(primary)?1:0;
-}
+// Multi-select modality matching for `kloudy bots`.
+// `--modality <m>` may be repeated. Default match is ANY (OR). `--all-modalities` switches to AND.
+// `primary` / modality_primary is a sort hint only; it never filters.
+// These 44 tags are the kloudy 1.0 bundled catalog modalities.
+export const KNOWN_MODALITIES=['agent_tools','api_calls','audio','auth_encryption','browser_automation','chat_platforms','chat_ui','cli','cloud','code','code_execution','comms','data','data_analysis','database_access','document_processing','embedding','evaluation','file_system','finance','gpu_compute','image','image_generation','inference','maps','math','memory','multimodal','notifications','observability','orchestration','productivity','queues','rag','robotics','scheduling','search','security','simulation','text','translation','video','voice_generation','web'];
+
+export function modalityWant(value){
+  if(value==null||value==='')return [];
+  const raw=Array.isArray(value)?value:[value];
+  const out=[];
+  for(const v of raw){
+    for(const part of String(v).split(',')){
+      const s=part.trim();
+      if(s&&!out.includes(s))out.push(s);
+    }
+  }
+  return out;
+}
+
+export function rowMatchesModalities(have,want,{all=false}={}){
+  if(!want.length)return true;
+  const set=Array.isArray(have)?have:[];
+  return all?want.every(m=>set.includes(m)):want.some(m=>set.includes(m));
+}
+
+export function primarySortHint(primary,want){
+  return primary&&want.includes(primary)?1:0;
+}

package/src/recommend.mjs

@@ -0,0 +1,478 @@
+// Offline stack recommender. No network and no model call.
+// `kloudy recommend <goal> [--json]` and `kloudy stack <goal> [--json]`.
+import {readFileSync} from 'node:fs';
+import {flags,loadLocal,localEndpoints} from './bots.mjs';
+import {primarySortHint} from './modalities.mjs';
+
+export const RECOMMEND_SCHEMA='kloudy.recommend/1';
+export const CATALOG_NAME='kloudy 1.0';
+const PER_MODALITY=5;
+// Class order for recommendations is A, then B, then O.
+// Primary-modality hint, keyword hits, catalog score, and index tie-break
+// follow the comparator in localSearch.
+const CLASS_TIER={A:0,B:1,O:2};
+const words=s=>String(s||'').toLowerCase().split(/[^\p{L}\p{N}_]+/u).filter(w=>w.length>1);
+
+const RULE_LIST=[
+  ['text to speech',['voice_generation']],
+  ['text-to-speech',['voice_generation']],
+  ['speech synthesis',['voice_generation']],
+  ['voice generation',['voice_generation']],
+  ['voice over',['voice_generation']],
+  ['voiceover',['voice_generation']],
+  ['text to image',['image_generation']],
+  ['text-to-image',['image_generation']],
+  ['image generation',['image_generation']],
+  ['generate images',['image_generation']],
+  ['generate image',['image_generation']],
+  ['stable diffusion',['image_generation']],
+  ['txt2img',['image_generation']],
+  ['code execution',['code_execution']],
+  ['execute code',['code_execution']],
+  ['run code',['code_execution']],
+  ['browser automation',['browser_automation']],
+  ['web scraping',['browser_automation']],
+  ['file system',['file_system']],
+  ['command line',['cli']],
+  ['command-line',['cli']],
+  ['vector database',['embedding']],
+  ['vector store',['embedding']],
+  ['rest api',['api_calls']],
+  ['api calls',['api_calls']],
+  ['api call',['api_calls']],
+  ['function calls',['agent_tools']],
+  ['function call',['agent_tools']],
+  ['function calling',['agent_tools']],
+  ['tool calling',['agent_tools']],
+  ['agent tools',['agent_tools']],
+  ['agent tool',['agent_tools']],
+  ['retrieval augmented',['rag']],
+  ['microsoft teams',['chat_platforms']],
+  ['chat window',['chat_ui']],
+  ['chat ui',['chat_ui']],
+  ['model server',['inference']],
+  ['web search',['search']],
+  ['transcribes',['audio']],
+  ['transcribe',['audio']],
+  ['transcribed',['audio']],
+  ['transcribing',['audio']],
+  ['transcriptions',['audio']],
+  ['transcription',['audio']],
+  ['summarizes',['text']],
+  ['summarize',['text']],
+  ['summarized',['text']],
+  ['summarizing',['text']],
+  ['summarization',['text']],
+  ['summaries',['text']],
+  ['summary',['text']],
+  ['voice',['audio']],
+  ['speech',['audio']],
+  ['audio',['audio']],
+  ['whisper',['audio']],
+  ['microphone',['audio']],
+  ['phone',['audio']],
+  ['calls',['audio']],
+  ['listen',['audio']],
+  ['asr',['audio']],
+  ['tts',['voice_generation']],
+  ['speak',['voice_generation']],
+  ['speaking',['voice_generation']],
+  ['draw',['image_generation']],
+  ['drawing',['image_generation']],
+  ['images',['image']],
+  ['image',['image']],
+  ['pictures',['image']],
+  ['picture',['image']],
+  ['photos',['image']],
+  ['photo',['image']],
+  ['vision',['image']],
+  ['videos',['video']],
+  ['video',['video']],
+  ['youtube',['video']],
+  ['multimodal',['multimodal']],
+  ['translates',['translation']],
+  ['translate',['translation']],
+  ['translation',['translation']],
+  ['translator',['translation']],
+  ['databases',['database_access']],
+  ['database',['database_access']],
+  ['postgresql',['database_access']],
+  ['postgres',['database_access']],
+  ['mongodb',['database_access']],
+  ['sqlite',['database_access']],
+  ['mysql',['database_access']],
+  ['sql',['database_access']],
+  ['storage',['database_access']],
+  ['stored',['database_access']],
+  ['stores',['database_access']],
+  ['storing',['database_access']],
+  ['store',['database_access']],
+  ['filesystem',['file_system']],
+  ['files',['file_system']],
+  ['file',['file_system']],
+  ['directory',['file_system']],
+  ['folders',['file_system']],
+  ['folder',['file_system']],
+  ['disk',['file_system']],
+  ['playwright',['browser_automation']],
+  ['puppeteer',['browser_automation']],
+  ['selenium',['browser_automation']],
+  ['scraping',['browser_automation']],
+  ['scrape',['browser_automation']],
+  ['browser',['browser_automation']],
+  ['webhooks',['api_calls']],
+  ['webhook',['api_calls']],
+  ['graphql',['api_calls']],
+  ['apis',['api_calls']],
+  ['api',['api_calls']],
+  ['scheduling',['scheduling']],
+  ['schedules',['scheduling']],
+  ['schedule',['scheduling']],
+  ['calendar',['scheduling']],
+  ['reminders',['scheduling']],
+  ['reminder',['scheduling']],
+  ['cron',['scheduling']],
+  ['notifications',['notifications']],
+  ['notification',['notifications']],
+  ['notify',['notifications']],
+  ['alerts',['notifications']],
+  ['alert',['notifications']],
+  ['authentication',['auth_encryption']],
+  ['encryption',['auth_encryption']],
+  ['encrypt',['auth_encryption']],
+  ['passwords',['auth_encryption']],
+  ['password',['auth_encryption']],
+  ['oauth',['auth_encryption']],
+  ['login',['auth_encryption']],
+  ['auth',['auth_encryption']],
+  ['analytics',['data_analysis']],
+  ['analysis',['data_analysis']],
+  ['analyze',['data_analysis']],
+  ['statistics',['data_analysis']],
+  ['statistical',['data_analysis']],
+  ['dataframe',['data_analysis']],
+  ['documents',['document_processing']],
+  ['document',['document_processing']],
+  ['docx',['document_processing']],
+  ['pdf',['document_processing']],
+  ['ocr',['document_processing']],
+  ['robotics',['robotics']],
+  ['robots',['robotics']],
+  ['robot',['robotics']],
+  ['ros',['robotics']],
+  ['embeddings',['embedding']],
+  ['embedding',['embedding']],
+  ['vectors',['embedding']],
+  ['vector',['embedding']],
+  ['searching',['search']],
+  ['searches',['search']],
+  ['search',['search']],
+  ['lookup',['search']],
+  ['websites',['web']],
+  ['website',['web']],
+  ['crawling',['web']],
+  ['crawl',['web']],
+  ['html',['web']],
+  ['url',['web']],
+  ['web',['web']],
+  ['datasets',['data']],
+  ['dataset',['data']],
+  ['csv',['data']],
+  ['etl',['data']],
+  ['kubernetes',['cloud']],
+  ['azure',['cloud']],
+  ['cloud',['cloud']],
+  ['aws',['cloud']],
+  ['gcp',['cloud']],
+  ['k8s',['cloud']],
+  ['payments',['finance']],
+  ['payment',['finance']],
+  ['invoices',['finance']],
+  ['invoice',['finance']],
+  ['accounting',['finance']],
+  ['trading',['finance']],
+  ['stripe',['finance']],
+  ['finance',['finance']],
+  ['spreadsheets',['productivity']],
+  ['spreadsheet',['productivity']],
+  ['productivity',['productivity']],
+  ['todos',['productivity']],
+  ['todo',['productivity']],
+  ['notes',['productivity']],
+  ['messaging',['comms']],
+  ['emails',['comms']],
+  ['email',['comms']],
+  ['sms',['comms']],
+  ['vulnerabilities',['security']],
+  ['vulnerability',['security']],
+  ['security',['security']],
+  ['pentest',['security']],
+  ['geospatial',['maps']],
+  ['locations',['maps']],
+  ['location',['maps']],
+  ['geocode',['maps']],
+  ['maps',['maps']],
+  ['map',['maps']],
+  ['memories',['memory']],
+  ['memory',['memory']],
+  ['remember',['memory']],
+  ['orchestration',['orchestration']],
+  ['orchestrate',['orchestration']],
+  ['workflows',['orchestration']],
+  ['workflow',['orchestration']],
+  ['pipelines',['orchestration']],
+  ['pipeline',['orchestration']],
+  ['cuda',['gpu_compute']],
+  ['gpu',['gpu_compute']],
+  ['mathematics',['math']],
+  ['equations',['math']],
+  ['equation',['math']],
+  ['calculator',['math']],
+  ['math',['math']],
+  ['rag',['rag']],
+  ['telegram',['chat_platforms']],
+  ['discord',['chat_platforms']],
+  ['slack',['chat_platforms']],
+  ['chatbot',['chat_ui']],
+  ['terminal',['cli']],
+  ['shell',['cli']],
+  ['cli',['cli']],
+  ['benchmarks',['evaluation']],
+  ['benchmark',['evaluation']],
+  ['evaluation',['evaluation']],
+  ['evaluate',['evaluation']],
+  ['observability',['observability']],
+  ['monitoring',['observability']],
+  ['metrics',['observability']],
+  ['tracing',['observability']],
+  ['logs',['observability']],
+  ['rabbitmq',['queues']],
+  ['queues',['queues']],
+  ['queue',['queues']],
+  ['kafka',['queues']],
+  ['inference',['inference']],
+  ['vllm',['inference']],
+  ['simulations',['simulation']],
+  ['simulation',['simulation']],
+  ['simulator',['simulation']],
+  ['simulate',['simulation']],
+  ['writing',['text']],
+  ['prompt',['text']],
+  ['chat',['text']],
+  ['llm',['text']],
+  ['text',['text']],
+  ['coding',['code']],
+  ['programming',['code']],
+  ['developer',['code']],
+  ['software',['code']],
+  ['code',['code']],
+  ['sandbox',['code_execution']],
+  ['interpreter',['code_execution']],
+  ['repl',['code_execution']]
+];
+
+export const KEYWORD_RULES=RULE_LIST.map(([phrase,modalities])=>({phrase,modalities:[...modalities]}))
+  .sort((a,b)=>b.phrase.length-a.phrase.length||a.phrase.localeCompare(b.phrase));
+
+const CLAUSE_SPLIT=/\s*(?:,|;|&)\s*|\s+\b(?:and|then)\b\s+/i;
+const EDGE_STOP=new Set(['a','an','the','that','which','who','to','for','of','in','on','with','and','then','into','from','by','or','also']);
+
+function bounded(text,start,end){
+  const before=start===0||!/[\p{L}\p{N}_]/u.test(text[start-1]);
+  const after=end===text.length||!/[\p{L}\p{N}_]/u.test(text[end]);
+  return before&&after;
+}
+
+export function findKeywordHits(text){
+  const lower=String(text||'').toLowerCase();
+  const found=[];
+  for(const rule of KEYWORD_RULES){
+    let from=0;
+    while(from<=lower.length-rule.phrase.length){
+      const i=lower.indexOf(rule.phrase,from);
+      if(i<0)break;
+      const end=i+rule.phrase.length;
+      if(bounded(lower,i,end)&&!found.some(h=>i<h.end&&end>h.start))found.push({start:i,end,phrase:rule.phrase,modalities:rule.modalities});
+      from=i+1;
+    }
+  }
+  found.sort((a,b)=>a.start-b.start||a.end-b.end);
+  return found;
+}
+
+function cleanPart(text){
+  const bits=String(text||'').replace(/\s+/g,' ').trim().replace(/^[,;:.]+|[,;:.]+$/g,'').split(' ').filter(Boolean);
+  while(bits.length&&EDGE_STOP.has(bits[0].toLowerCase()))bits.shift();
+  while(bits.length&&EDGE_STOP.has(bits[bits.length-1].toLowerCase()))bits.pop();
+  return bits.join(' ');
+}
+
+function overlaps(a,b){
+  return a.some(m=>b.includes(m));
+}
+
+function clauseLabel(clause){
+  return cleanPart(clause)||String(clause||'').replace(/\s+/g,' ').trim();
+}
+
+function partsFromClause(clause){
+  const hits=findKeywordHits(clause);
+  if(!hits.length){
+    const text=clauseLabel(clause);
+    return text?[{text,modalities:[],keywords:[]}]:[];
+  }
+  const groups=[];
+  for(const hit of hits){
+    const last=groups[groups.length-1];
+    if(last&&overlaps(last.modalities,hit.modalities)){
+      last.hits.push(hit);
+      for(const m of hit.modalities)if(!last.modalities.includes(m))last.modalities.push(m);
+      if(!last.keywords.includes(hit.phrase))last.keywords.push(hit.phrase);
+    }else groups.push({modalities:[...hit.modalities],keywords:[hit.phrase],hits:[hit]});
+  }
+  if(groups.length===1){
+    const text=clauseLabel(clause)||groups[0].keywords.join(' ');
+    return [{text,modalities:groups[0].modalities,keywords:groups[0].keywords}];
+  }
+  return groups.map((group,i)=>{
+    const start=i===0?0:splitPoint(clause,groups[i-1].hits.at(-1).end,group.hits[0].start);
+    const end=i===groups.length-1?clause.length:splitPoint(clause,group.hits.at(-1).end,groups[i+1].hits[0].start);
+    const text=clauseLabel(clause.slice(start,end))||group.keywords.join(' ');
+    return {text,modalities:group.modalities,keywords:group.keywords};
+  });
+}
+
+function splitPoint(clause,leftEnd,rightStart){
+  const gap=clause.slice(leftEnd,rightStart);
+  const rel=gap.lastIndexOf(' ');
+  return rel>=0?leftEnd+rel+1:Math.floor((leftEnd+rightStart)/2);
+}
+
+export function decomposeGoal(goal){
+  const text=String(goal||'').replace(/\s+/g,' ').trim();
+  if(!text)return [];
+  const parts=[];
+  for(const clause of text.split(CLAUSE_SPLIT).map(s=>s.trim()).filter(Boolean))parts.push(...partsFromClause(clause));
+  return parts;
+}
+
+export function packageVersion(){
+  return JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+}
+
+export function installCommand(bot){
+  const eps=localEndpoints(bot);
+  for(const ep of eps)if(ep.command)return ep.command;
+  for(const ep of eps)if(ep.url)return ep.url;
+  return bot.endpoint||'';
+}
+
+function oneLine(bot){
+  const caps=(bot.caps||[]).map(c=>String(c).replace(/^cap\./,'').replace(/^mcp\./,'').replace(/[._]+/g,' ').trim()).filter(c=>c&&c.toLowerCase()!=='connect');
+  const kind={http:'live HTTP endpoint',npx:'npx package',uvx:'uvx package',hf:'Hugging Face model',botboozle:'open-source package'}[bot.kind]||bot.kind||'bot';
+  const detail=caps.length?caps.slice(0,4).join(', '):(bot.modalities||[]).slice(0,3).join(', ');
+  const line=detail?`${bot.name} — ${kind}; ${detail}`:`${bot.name} — ${kind}`;
+  return line.replace(/\s+/g,' ').slice(0,180);
+}
+
+function whyLine(modality,keywords){
+  const hint=(keywords||[]).filter(k=>KEYWORD_RULES.some(r=>r.phrase===k&&r.modalities.includes(modality))).slice(0,4).join('/');
+  return hint?`matched ${modality}/${hint}; top-ranked in modality`:`matched ${modality}; top-ranked in modality`;
+}
+
+function rankModality(bots,modality,keywords,limit){
+  const terms=[...new Set((keywords||[]).flatMap(words))];
+  const want=[modality];
+  const pool=[];
+  for(let i=0;i<bots.length;i++){
+    const b=bots[i];
+    if(!(b.modalities||[]).includes(modality))continue;
+    const blob=(b.name+' '+b.id+' '+(b.caps||[]).join(' ')).toLowerCase();
+    pool.push({b,i,hits:terms.filter(t=>blob.includes(t)).length});
+  }
+  const tier=cls=>CLASS_TIER[cls]??9;
+  pool.sort((x,y)=>tier(x.b.cls)-tier(y.b.cls)||primarySortHint(y.b.modality_primary,want)-primarySortHint(x.b.modality_primary,want)||y.hits-x.hits||(y.b.score||0)-(x.b.score||0)||x.i-y.i||String(x.b.id).localeCompare(String(y.b.id)));
+  return pool.slice(0,limit).map(x=>x.b);
+}
+
+export function recommendGoal(goal,options={}){
+  const source=options.bots?{bots:options.bots}:loadLocal();
+  if(!source?.bots)throw new Error('No local catalog. Run `kloudy bots sync`.');
+  const limit=options.perModality??PER_MODALITY;
+  const pieces=decomposeGoal(goal);
+  const parts=[];
+  const unmatched=[];
+  const consider=pieces.length?pieces:[{text:String(goal||'').trim(),modalities:[],keywords:[]}];
+  for(const piece of consider){
+    if(!piece.text)continue;
+    if(!piece.modalities.length){
+      unmatched.push({part:piece.text,reason:'no modality or catalog match'});
+      continue;
+    }
+    const seen=new Map();
+    const bots=[];
+    for(const modality of piece.modalities){
+      for(const bot of rankModality(source.bots,modality,piece.keywords,limit)){
+        const prev=seen.get(bot.id);
+        if(prev){
+          if(!prev.modalities.includes(modality))prev.modalities.push(modality);
+          continue;
+        }
+        const item={
+          id:bot.id,
+          name:bot.name,
+          class:bot.cls,
+          command:installCommand(bot),
+          license:bot.license||'',
+          description:oneLine(bot),
+          why:whyLine(modality,piece.keywords),
+          modalities:[modality]
+        };
+        seen.set(bot.id,item);
+        bots.push(item);
+      }
+    }
+    if(!bots.length){
+      unmatched.push({part:piece.text,reason:'no modality or catalog match'});
+      continue;
+    }
+    parts.push({part:piece.text,modalities:piece.modalities,bots});
+  }
+  return {schema:RECOMMEND_SCHEMA,catalog:CATALOG_NAME,version:options.version||packageVersion(),goal:String(goal??''),parts,unmatched};
+}
+
+export function formatRecommend(result){
+  const lines=[`${result.catalog}  ·  package ${result.version}`,`Goal: ${result.goal}`];
+  result.parts.forEach((part,index)=>{
+    lines.push('',`${index+1}. ${part.part}`,`Modalities: ${part.modalities.join(', ')}`);
+    part.bots.forEach((bot,n)=>{
+      lines.push(`  ${n+1}) ${bot.id}  [${bot.class}]  ${bot.license||'unknown license'}`,`     ${bot.command}`,`     ${bot.description}`,`     why: ${bot.why}`);
+    });
+  });
+  if(result.unmatched.length){
+    lines.push('','Unmatched');
+    for(const item of result.unmatched)lines.push(`- ${item.part}: ${item.reason}`);
+  }
+  return lines.join('\n');
+}
+
+export function recommendCommand(args,opts={}){
+  const out=opts.out||(s=>console.log(s));
+  const o=flags(args);
+  const goal=o._.join(' ').trim();
+  if(!goal)throw new Error('Usage: kloudy recommend <goal> [--json]');
+  const result=recommendGoal(goal);
+  out(o.json?JSON.stringify(result,null,2):formatRecommend(result));
+  return result;
+}
+
+export function agentsDocument(){
+  return readFileSync(new URL('../AGENTS.md',import.meta.url),'utf8');
+}
+
+export function agentsCommand(opts={}){
+  const out=opts.out||(s=>console.log(s));
+  const text=agentsDocument().replace(/\s*$/,'');
+  out(text);
+  return text;
+}