kloudy 1.0.1 → 1.0.2

package/AGENTS.md

@@ -1,6 +1,8 @@
 ## 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.
+The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, bundled in this package (npm version 1.0.2). `recommend` / `stack` and `bots ... --offline` read that snapshot (or the local cache if one exists). Kloudy never runs an LLM. Ranking is deterministic: the same goal and the same score overrides return the same JSON.
+
+When a network is available, `recommend` may GET `https://kloudy.ai/api/feedback/scores` and cache those overrides for about 24 hours in the Kloudy data directory (`~/.kloudy`, or `KLOUDY_DATA_DIR`). Overrides demote, exclude, or boost a bot after the class tier. `--offline`, a failed request, or a missing scores file leaves ranking on the bundled catalog order.
 
 Classes:
 
@@ -18,18 +20,43 @@ Commands:
 
 ```sh
 npx kloudy@latest recommend "<goal>" --json
-npx kloudy@latest stack "<goal>" --json
+npx kloudy@latest recommend "<goal>" --json --limit 5
+npx kloudy@latest stack "<goal>" --json --limit 5 --offline
+npx kloudy@latest feedback --stack <stackId> --bot <botId> --result worked|failed|partial [--reason <short>] [--client <name>]
+npx kloudy@latest feedback --flush
 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.
+`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. `--limit <n>` sets the per-part cap. `n` is an integer from 1 to 20. The default is 5. `--offline` skips the score-override request.
 
 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.
+Write the goal as one sentence per need, or as a comma-separated list of needs. A long sentence is still accepted. Clearer parts produce a clearer stack.
+
+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, then the list is capped per part. Each part includes `candidatesTotal` (how many eligible candidates existed before the cap) and `bots` (the capped list). Narrow that capped list with the project you have open: language, frameworks, licenses, and tools already in the repo. Kloudy never runs an LLM and does not read the project to pick a bot.
+
+Familiar modality words such as transcribe, summarize, and database still return the top bots in that modality. A narrower need, such as a watch, a timer, Android sync, a meal plan, or a social post, keeps only bots that share a real keyword or a clearly related catalog name, id, or cap with that part. Unrelated bots are not added as filler. Order is class A, then B, then O, then score override (boost, then unchanged, then demote), then primary-modality hint, keyword hits, catalog score, and catalog index. Exclude removes a bot before the cap. 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.
+
+`phone`, `call`, and `calls` map to `audio` only when an audio cue is in the same part or clause: transcribe, transcription, voice, speech, audio, whisper, microphone, asr, phone call, or call audio. Otherwise phone, Android, and mobile are a device-sync need, not audio.
+
+Every part has `confidence`: `match`, `weak`, or `none`. Top-level `complete` is true only when every part is `match` and `gaps` is empty. `complete` false means the stack is partial. `gaps` lists unmatched and weak parts. Each gap has the part text, `confidence`, and a reason. `kind` is `catalog integration` when a catalog bot with an install or run command is a real but weak hit. `kind` is `suggestion: build yourself / platform API` when the catalog does not cover the need, such as Wear OS sensor APIs, Health Connect, or the Facebook Graph API. That suggestion is unverified non-catalog guidance. It is not a catalog bot.
+
+Every recommend result includes `limit`, `stackId`, and `feedback`. `stackId` is a sha256 of the goal's parts plus the chosen bot ids. The same parts and the same picks always produce the same `stackId`. `feedback` is the command to run after you try a bot. Put that bot's id in place of `<id>`.
+
+After you try a stack, report whether it worked:
+
+```sh
+kloudy feedback --stack <stackId> --bot <botId> --result worked|failed|partial [--reason <short>] [--client <name>]
+```
+
+`--result` is `worked`, `failed`, or `partial`. `--reason` is optional and short: it is truncated to 80 characters, and a path, token, or email is dropped. `--client` is an optional tool name such as `cursor`, `claude`, `codex`, or `vscode`. It counts distinct clients. Do not pass a person, email, or account. The report is opt-in and anonymous. The payload may include only `stackId`, `botId`, `result`, an optional short `reason`, the kloudy version, and an optional client name. It never includes the goal text, personal info, file paths, environment, or tokens. The POST goes to `https://kloudy.ai/api/feedback`. If the network is down or the POST fails, the report is queued in the Kloudy data directory and sent on the next `kloudy feedback` or `kloudy feedback --flush`.
+
+Score overrides come from those anonymous reports. `scripts/aggregate-feedback-scores.mjs` is meant to run weekly Sunday 3:00 America/Phoenix. It writes `feedback-scores.json`. Bots with fewer than 3 reports are ignored. A bot is demoted after it fails for 3 or more distinct clients with a failure ratio of 60% or more. A bot is excluded after 10 or more reports with a failure ratio of 80% or more. A bot is boosted at 5 or more reports when at least 80% are `worked` and it is not demoted or excluded. `partial` counts as a report and counts as neither worked nor failed. Failure ratio is `failed` divided by all reports. Reports without a client still count toward ratios. They do not add a distinct client.
+
+Without `--json`, the text includes Confidence, Candidates, Gaps, `limit`, `stackId`, `feedback`, and `complete=true` or `complete=false`. `--json` still prints only the JSON object (`schema`: `kloudy.recommend/1`, `catalog`: `kloudy 1.0`, `version`: `1.0.2`).
 
 Single-part example:
 
@@ -51,4 +78,6 @@ Three parts:
 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.
+That control stack is `complete` true: each part is confidence `match`, and `gaps` is empty.
+
+`weave a basket` in a larger goal is unmatched. It is reported, not omitted. The goal is then `complete` false.

package/README.md

@@ -24,7 +24,9 @@ Offline bot catalog: `npx kloudy bots list|search|get|sync|works|broken|modaliti
 
 ## 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.
+The catalog is **kloudy 1.0**: 13,440 bots and 44 modality tags, shipped in this package (npm version 1.0.2). Recommend and the offline bots commands read that bundled snapshot, then the local cache. Kloudy never runs an LLM. Ranking is deterministic: the same goal and the same score overrides return the same JSON.
+
+When a network is available, `recommend` may GET `https://kloudy.ai/api/feedback/scores` and cache those overrides for about 24 hours in the Kloudy data directory (`~/.kloudy`, or `KLOUDY_DATA_DIR`). Overrides demote, exclude, or boost a bot after the class tier. `--offline`, a failed request, or a missing scores file leaves ranking on the bundled catalog order.
 
 Classes:
 
@@ -38,18 +40,43 @@ List the modality tags:
 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`).
+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`). `--limit <n>` caps each part (`n` is an integer from 1 to 20; the default is 5). `--offline` skips the score-override request.
 
 ```sh
 npx kloudy@latest recommend "<goal>" --json
-npx kloudy@latest stack "<goal>" --json
+npx kloudy@latest recommend "<goal>" --json --limit 5
+npx kloudy@latest stack "<goal>" --json --limit 5 --offline
+npx kloudy@latest feedback --stack <stackId> --bot <botId> --result worked|failed|partial [--reason <short>] [--client <name>]
+npx kloudy@latest feedback --flush
 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.
+Write the goal as one sentence per need, or as a comma-separated list of needs. A long sentence is still accepted. Clearer parts produce a clearer stack.
+
+`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. Each part includes `candidatesTotal` (how many eligible candidates existed before the cap) and `bots` (the capped list). Narrow that capped list with the project you have open: language, frameworks, licenses, and tools already in the repo. Kloudy never runs an LLM and does not read the project to pick a bot.
+
+Order is class A, then B, then O, then score override (boost, then unchanged, then demote), then the same primary-modality, keyword, score, and index ordering as catalog search. Exclude removes a bot before the cap. Familiar modality words such as transcribe, summarize, and database still return the top bots in that modality. A narrower need, such as a watch, a timer, Android sync, a meal plan, or a social post, keeps only bots that share a real keyword or a clearly related catalog name, id, or cap with that part. Unrelated bots are not filler. A part with no modality or no catalog row stays in `unmatched` with the part text and a reason. It is not dropped.
+
+`phone`, `call`, and `calls` are `audio` only when an audio cue is in the same part or clause (transcribe, transcription, voice, speech, audio, whisper, microphone, asr, phone call, or call audio). Otherwise phone, Android, and mobile are device sync, not audio.
+
+Each part includes `confidence` (`match`, `weak`, or `none`). Top-level `complete` is true only when every part is `match` and `gaps` is empty. `complete` false means the stack is partial. `gaps` lists unmatched and weak parts with the part text, confidence, and a reason. `kind` `catalog integration` means a catalog bot with an install or run command is a real but weak hit. `kind` `suggestion: build yourself / platform API` means the catalog does not cover the need (Wear OS sensor APIs, Health Connect, or the Facebook Graph API, for example). That suggestion is unverified non-catalog guidance, not a catalog bot.
+
+Every recommend result includes `limit`, `stackId`, and `feedback`. `stackId` is a sha256 of the goal's parts plus the chosen bot ids. The same parts and the same picks always produce the same `stackId`. `feedback` is the command to run after you try a bot. Put that bot's id in place of `<id>`.
+
+After you try a stack, report whether it worked:
+
+```sh
+kloudy feedback --stack <stackId> --bot <botId> --result worked|failed|partial [--reason <short>] [--client <name>]
+```
+
+`--result` is `worked`, `failed`, or `partial`. `--reason` is optional and short: it is truncated to 80 characters, and a path, token, or email is dropped. `--client` is an optional tool name such as `cursor`, `claude`, `codex`, or `vscode`. It counts distinct clients. Do not pass a person, email, or account. The report is opt-in and anonymous. The payload may include only `stackId`, `botId`, `result`, an optional short `reason`, the kloudy version, and an optional client name. It never includes the goal text, personal info, file paths, environment, or tokens. The POST goes to `https://kloudy.ai/api/feedback`. If the network is down or the POST fails, the report is queued in the Kloudy data directory and sent on the next `kloudy feedback` or `kloudy feedback --flush`.
+
+Score overrides come from those anonymous reports. `scripts/aggregate-feedback-scores.mjs` is meant to run weekly Sunday 3:00 America/Phoenix. It writes `feedback-scores.json`. Bots with fewer than 3 reports are ignored. A bot is demoted after it fails for 3 or more distinct clients with a failure ratio of 60% or more. A bot is excluded after 10 or more reports with a failure ratio of 80% or more. A bot is boosted at 5 or more reports when at least 80% are `worked` and it is not demoted or excluded. `partial` counts as a report and counts as neither worked nor failed. Failure ratio is `failed` divided by all reports. Reports without a client still count toward ratios. They do not add a distinct client.
+
+Text output includes Confidence, Candidates, Gaps, `limit`, `stackId`, `feedback`, and `complete=true` or `complete=false`. `--json` still prints only the JSON object.
 
 Single-part example:
 
@@ -57,7 +84,7 @@ Single-part example:
 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`).
+That goal is one audio part. The first bot in the capped list is `httpk:npm:mendelio-voice-mcp` (class B, MIT, `npx -y mendelio-voice-mcp`).
 
 Multi-part example:
 
@@ -71,7 +98,9 @@ That becomes three parts, not one blended search:
 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.
+That control stack is complete (`complete` true). Each part is confidence `match`.
+
+A leftover clause such as `weave a basket` is listed under Unmatched (`no modality or catalog match`) and under Gaps. The goal is then `complete` false.
 
 On first contact, read the agent guide and the command list:
 

package/bin/entry.mjs

@@ -16,9 +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 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(['--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] [--limit N] [--offline]\nnpx kloudy stack "<goal>" [--json] [--limit N] [--offline]\nnpx kloudy feedback --stack ID --bot ID --result worked|failed|partial [--reason TEXT] [--client NAME] [--flush]\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]==='feedback'){const {feedbackCommand}=await import('../src/feedback.mjs');try{await feedbackCommand(args.slice(1));}catch(error){process.stderr.write((error?.message||'feedback 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;}

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 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.');
+  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] [--limit N] [--offline]\nkloudy stack <goal> [--json] [--limit N] [--offline]\nkloudy feedback --stack ID --bot ID --result worked|failed|partial [--reason TEXT] [--client NAME] [--flush]\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);
@@ -54,6 +54,9 @@ try{
  }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==='feedback'){
+  const {feedbackCommand}=await import('../src/feedback.mjs');
+  try{await feedbackCommand(args);}catch(error){process.stderr.write((error?.message||'feedback 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;}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kloudy",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Ask for Kloudy: CLI, MCP and SDK clients for the same scoped engine session.",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,7 +39,7 @@
   ],
   "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/recommend.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/scores.mjs && node --check src/feedback.mjs && node --check scripts/aggregate-feedback-scores.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/src/feedback.mjs

@@ -0,0 +1,159 @@
+// Anonymous stack feedback. Opt-in. No goal text, paths, env, or tokens.
+// POST https://kloudy.ai/api/feedback and queue in the Kloudy data directory on failure.
+import {existsSync,mkdirSync,readFileSync,writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {dataDir} from './scores.mjs';
+
+export const FEEDBACK_URL='https://kloudy.ai/api/feedback';
+export const RESULTS=new Set(['worked','failed','partial']);
+export const REASON_MAX=80;
+const ALLOWED=new Set(['stackId','botId','result','reason','version','client']);
+const DISABLED=new Set(['','off','offline','0','false']);
+
+function packageVersion(){
+  return JSON.parse(readFileSync(new URL('../package.json',import.meta.url),'utf8')).version;
+}
+
+export function feedbackEndpoint(explicit){
+  const value=explicit??process.env.KLOUDY_FEEDBACK_URL??FEEDBACK_URL;
+  return DISABLED.has(String(value).trim())?null:value;
+}
+
+export function sanitizeReason(reason){
+  if(reason==null||reason==='')return undefined;
+  let text=String(reason).replace(/[\u0000-\u001f\u007f]/g,' ').replace(/\s+/g,' ').trim();
+  if(!text)return undefined;
+  if(/[\\/]|~|\.\.|[A-Za-z]:[\\/]|@[A-Za-z0-9.-]+\.[A-Za-z]{2,}|\b(?:bearer|token|secret|password|api[_-]?key)\b|-----BEGIN/i.test(text))return undefined;
+  if(/[A-Fa-f0-9]{24,}/.test(text))return undefined;
+  if(/(?:sk|pk|ghp|gho|xox[baprs])-/.test(text))return undefined;
+  if(text.length>REASON_MAX)text=text.slice(0,REASON_MAX).trim();
+  return text||undefined;
+}
+
+export function sanitizeClient(client){
+  if(client==null||client==='')return undefined;
+  const text=String(client).trim();
+  if(!/^[A-Za-z][A-Za-z0-9._-]{0,31}$/.test(text))return undefined;
+  return text;
+}
+
+export function buildFeedbackPayload(input={}){
+  const stackId=String(input.stackId||'').trim();
+  const botId=String(input.botId||'').trim();
+  const result=input.result;
+  if(!/^[a-f0-9]{64}$/.test(stackId))throw new Error('stack id must be the stackId from recommend --json');
+  if(!botId||botId.length>200||/[\s\\]/.test(botId)||botId.includes('..'))throw new Error('bot id is required');
+  if(!RESULTS.has(result))throw new Error('result must be worked, failed, or partial');
+  const payload={stackId,botId,result,version:input.version||packageVersion()};
+  const reason=sanitizeReason(input.reason===input.goal?undefined:input.reason);
+  if(reason)payload.reason=reason;
+  const client=sanitizeClient(input.client);
+  if(client)payload.client=client;
+  return payload;
+}
+
+export function queuePath(dir=dataDir()){
+  return join(dir,'feedback-queue.json');
+}
+
+function safeQueued(item){
+  if(!item||typeof item!=='object'||Array.isArray(item))return false;
+  const keys=Object.keys(item);
+  if(!keys.length||!keys.every(key=>ALLOWED.has(key)))return false;
+  if(typeof item.stackId!=='string'||typeof item.botId!=='string'||typeof item.version!=='string')return false;
+  if(!RESULTS.has(item.result))return false;
+  if(item.reason!=null&&typeof item.reason!=='string')return false;
+  if(item.client!=null&&typeof item.client!=='string')return false;
+  return true;
+}
+
+export function readQueue(dir=dataDir()){
+  const file=queuePath(dir);
+  try{
+    if(!existsSync(file))return [];
+    const data=JSON.parse(readFileSync(file,'utf8'));
+    return Array.isArray(data)?data.filter(safeQueued):[];
+  }catch{
+    return [];
+  }
+}
+
+function writeQueue(dir,items){
+  mkdirSync(dir,{recursive:true});
+  writeFileSync(queuePath(dir),JSON.stringify(items,null,2)+'\n');
+}
+
+async function postOne(payload,fetchImpl,url){
+  const response=await fetchImpl(url,{
+    method:'POST',
+    redirect:'error',
+    credentials:'omit',
+    headers:{'content-type':'application/json',accept:'application/json'},
+    body:JSON.stringify(payload),
+    signal:AbortSignal.timeout(8000)
+  });
+  if(!response?.ok)throw new Error('Feedback was not accepted');
+}
+
+export async function submitFeedback({payload,dir=dataDir(),fetchImpl=fetch,url=feedbackEndpoint()}={}){
+  const queued=readQueue(dir);
+  if(payload)queued.push(payload);
+  if(!queued.length)return {sent:0,queued:0,status:'empty'};
+  if(!url){
+    writeQueue(dir,queued);
+    return {sent:0,queued:queued.length,status:'queued'};
+  }
+  const pending=[];
+  let sent=0;
+  let failed=false;
+  for(const item of queued){
+    if(failed){pending.push(item);continue;}
+    try{
+      await postOne(item,fetchImpl,url);
+      sent++;
+    }catch{
+      failed=true;
+      pending.push(item);
+    }
+  }
+  writeQueue(dir,pending);
+  return {sent,queued:pending.length,status:pending.length?(sent?'partial':'queued'):'sent'};
+}
+
+export function parseFeedbackArgs(args){
+  const o={};
+  for(let i=0;i<args.length;i++){
+    const arg=args[i];
+    if(arg==='--flush'){o.flush=true;continue;}
+    if(arg==='--json'){o.json=true;continue;}
+    if(!arg.startsWith('--'))throw new Error('Usage: kloudy feedback --stack ID --bot ID --result worked|failed|partial [--reason TEXT] [--client NAME] [--flush]');
+    const key=arg.slice(2);
+    const value=args[++i];
+    if(value==null||String(value).startsWith('--'))throw new Error('Option value required');
+    if(!['stack','bot','result','reason','client'].includes(key))throw new Error('Unknown feedback option');
+    o[key]=value;
+  }
+  return o;
+}
+
+function statusLine(result){
+  if(result.status==='empty')return 'feedback queue is empty';
+  if(result.status==='sent')return `sent ${result.sent} feedback report${result.sent===1?'':'s'}`;
+  if(result.status==='partial')return `sent ${result.sent} feedback report${result.sent===1?'':'s'}; ${result.queued} still queued`;
+  return `queued ${result.queued} feedback report${result.queued===1?'':'s'}`;
+}
+
+export async function feedbackCommand(args,opts={}){
+  const out=opts.out||(s=>console.log(s));
+  const o=parseFeedbackArgs(args);
+  const hasReport=o.stack!=null||o.bot!=null||o.result!=null||o.reason!=null||o.client!=null;
+  if(!hasReport&&!o.flush)throw new Error('Usage: kloudy feedback --stack ID --bot ID --result worked|failed|partial [--reason TEXT] [--client NAME] [--flush]');
+  if(hasReport&&(!o.stack||!o.bot||!o.result))throw new Error('Feedback requires --stack, --bot, and --result');
+  const payload=hasReport?buildFeedbackPayload({stackId:o.stack,botId:o.bot,result:o.result,reason:o.reason,client:o.client,version:opts.version}):undefined;
+  const endpoint=opts.url===undefined?feedbackEndpoint():opts.url;
+  const result=await submitFeedback({payload,dir:opts.dataDir,fetchImpl:opts.fetch,url:endpoint||null});
+  const line=statusLine(result);
+  if(o.client!=null&&payload&&!payload.client)out(line+'\nclient omitted');
+  else out(line);
+  return {...result,payload};
+}

package/src/recommend.mjs

@@ -1,15 +1,23 @@
-// Offline stack recommender. No network and no model call.
-// `kloudy recommend <goal> [--json]` and `kloudy stack <goal> [--json]`.
+// Stack recommender. Kloudy never runs an LLM.
+// `kloudy recommend <goal> [--json] [--limit N] [--offline]`
+// `kloudy stack` is the same command.
+// Ranking reads the bundled catalog. recommendCommand may apply cached score overrides.
+import {createHash} from 'node:crypto';
 import {readFileSync} from 'node:fs';
 import {flags,loadLocal,localEndpoints} from './bots.mjs';
 import {primarySortHint} from './modalities.mjs';
+import {loadScoreOverrides,normalizeScores} from './scores.mjs';
 
 export const RECOMMEND_SCHEMA='kloudy.recommend/1';
 export const CATALOG_NAME='kloudy 1.0';
-const PER_MODALITY=5;
+export const DEFAULT_LIMIT=5;
+export const MIN_LIMIT=1;
+export const MAX_LIMIT=20;
+const PER_MODALITY=DEFAULT_LIMIT;
 // 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.
+// Score overrides apply after class: boost, then unchanged, then demote.
+// Exclude drops a bot before the cap. 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);
 
@@ -70,8 +78,6 @@ const RULE_LIST=[
   ['audio',['audio']],
   ['whisper',['audio']],
   ['microphone',['audio']],
-  ['phone',['audio']],
-  ['calls',['audio']],
   ['listen',['audio']],
   ['asr',['audio']],
   ['tts',['voice_generation']],
@@ -125,13 +131,13 @@ const RULE_LIST=[
   ['graphql',['api_calls']],
   ['apis',['api_calls']],
   ['api',['api_calls']],
-  ['scheduling',['scheduling']],
-  ['schedules',['scheduling']],
-  ['schedule',['scheduling']],
+  ['scheduling',['scheduling'],{family:'timer'}],
+  ['schedules',['scheduling'],{family:'timer'}],
+  ['schedule',['scheduling'],{family:'timer'}],
   ['calendar',['scheduling']],
   ['reminders',['scheduling']],
   ['reminder',['scheduling']],
-  ['cron',['scheduling']],
+  ['cron',['scheduling'],{family:'timer'}],
   ['notifications',['notifications']],
   ['notification',['notifications']],
   ['notify',['notifications']],
@@ -268,11 +274,72 @@ const RULE_LIST=[
   ['code',['code']],
   ['sandbox',['code_execution']],
   ['interpreter',['code_execution']],
-  ['repl',['code_execution']]
+  ['repl',['code_execution']],
+  // Phone and calls are audio only when an audio cue is in the same clause.
+  // Otherwise phone / Android / mobile are device sync, not voice tools.
+  ['phone call',['audio']],
+  ['phone calls',['audio']],
+  ['call audio',['audio']],
+  ['phone',['audio'],{when:'audio'}],
+  ['calls',['audio'],{when:'audio'}],
+  ['call',['audio'],{when:'audio'}],
+  ['phones',['notifications','comms'],{family:'sync',when:'no-audio'}],
+  ['phone',['notifications','comms'],{family:'sync',when:'no-audio'}],
+  ['android',['notifications','comms'],{family:'sync'}],
+  ['mobile',['notifications','comms'],{family:'sync'}],
+  ['syncing',['notifications','comms'],{family:'sync'}],
+  ['synced',['notifications','comms'],{family:'sync'}],
+  ['syncs',['notifications','comms'],{family:'sync'}],
+  ['sync',['notifications','comms'],{family:'sync'}],
+  ['push notification',['notifications','comms'],{family:'sync'}],
+  ['push notifications',['notifications','comms'],{family:'sync'}],
+  ['galaxy watch',['data'],{family:'wearable'}],
+  ['wear os',['data'],{family:'wearable'}],
+  ['health connect',['data'],{family:'wearable'}],
+  ['apple health',['data'],{family:'wearable'}],
+  ['smartwatch',['data'],{family:'wearable'}],
+  ['smart watch',['data'],{family:'wearable'}],
+  ['pedometer',['data'],{family:'wearable'}],
+  ['accelerometer',['data'],{family:'wearable'}],
+  ['wearable',['data'],{family:'wearable'}],
+  ['fitness',['data'],{family:'wearable'}],
+  ['steps',['data'],{family:'wearable',when:'not-device'}],
+  ['step',['data'],{family:'wearable',when:'not-device'}],
+  ['watch',['data'],{family:'wearable'}],
+  ['timers',['scheduling'],{family:'timer'}],
+  ['timer',['scheduling'],{family:'timer'}],
+  ['triggers',['scheduling'],{family:'timer',when:'timer'}],
+  ['trigger',['scheduling'],{family:'timer',when:'timer'}],
+  ['triggered',['scheduling'],{family:'timer',when:'timer'}],
+  ['movement',['scheduling'],{family:'timer',when:'movement-timer'}],
+  ['movement',['data'],{family:'wearable',when:'movement-sensor'}],
+  ['calories',['text'],{family:'nutrition'}],
+  ['calorie',['text'],{family:'nutrition'}],
+  ['nutrition',['text'],{family:'nutrition'}],
+  ['recipes',['text'],{family:'nutrition'}],
+  ['recipe',['text'],{family:'nutrition'}],
+  ['meals',['text'],{family:'nutrition'}],
+  ['meal',['text'],{family:'nutrition'}],
+  ['diets',['text'],{family:'nutrition'}],
+  ['diet',['text'],{family:'nutrition'}],
+  ['foods',['text'],{family:'nutrition'}],
+  ['food',['text'],{family:'nutrition'}],
+  ['facebook',['comms'],{family:'social'}],
+  ['instagram',['comms'],{family:'social'}],
+  ['twitter',['comms'],{family:'social'}],
+  ['shares',['comms'],{family:'social',when:'social'}],
+  ['shared',['comms'],{family:'social',when:'social'}],
+  ['sharing',['comms'],{family:'social',when:'social'}],
+  ['share',['comms'],{family:'social',when:'social'}],
+  ['posting',['comms'],{family:'social',when:'social'}],
+  ['posts',['comms'],{family:'social',when:'social'}],
+  ['posted',['comms'],{family:'social',when:'social'}],
+  ['post',['comms'],{family:'social',when:'social'}],
+  ['x',['comms'],{family:'social',when:'social-x'}]
 ];
 
-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));
+export const KEYWORD_RULES=RULE_LIST.map(([phrase,modalities,meta])=>({phrase,modalities:[...modalities],...(meta||{})}))
+  .sort((a,b)=>b.phrase.length-a.phrase.length||a.phrase.localeCompare(b.phrase)||(a.when||'').localeCompare(b.when||''));
 
 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']);
@@ -283,16 +350,38 @@ function bounded(text,start,end){
   return before&&after;
 }
 
+const AUDIO_CUE=/\b(?:transcri(?:be|bes|bed|bing|ption|ptions)?|voices?|speech|audio|whisper|microphones?|asr|listen(?:s|ing|ed)?|phone calls?|call audio)\b/i;
+const DEVICE_CUE=/\b(?:android|mobile|phones?|sync(?:ing|ed|s)?)\b/i;
+const TIMER_CUE=/\b(?:timers?|schedul\w*|cron|triggers?|triggered)\b/i;
+const DB_CUE=/\b(?:databases?|sql|postgres(?:ql)?|mysql|sqlite|mongodb)\b/i;
+const SOCIAL_NET=/\b(?:facebook|instagram|twitter)\b/i;
+const SOCIAL_X=/(?:\bx\.com\b|\b(?:post|share|tweet)(?:s|ed|ing)?\b[^.!?\n]{0,40}\bx\b|\bx\b[^.!?\n]{0,40}\b(?:post|share|tweet)(?:s|ed|ing)?\b)/i;
+
+function ruleApplies(rule,text){
+  switch(rule.when){
+    case 'audio':return AUDIO_CUE.test(text);
+    case 'no-audio':return !AUDIO_CUE.test(text);
+    case 'social':return SOCIAL_NET.test(text)||SOCIAL_X.test(text);
+    case 'social-x':return SOCIAL_X.test(text);
+    case 'timer':return TIMER_CUE.test(text)&&!DB_CUE.test(text);
+    case 'movement-timer':return TIMER_CUE.test(text);
+    case 'movement-sensor':return !TIMER_CUE.test(text);
+    case 'not-device':return !DEVICE_CUE.test(text);
+    default:return true;
+  }
+}
+
 export function findKeywordHits(text){
   const lower=String(text||'').toLowerCase();
   const found=[];
   for(const rule of KEYWORD_RULES){
+    if(!ruleApplies(rule,lower))continue;
     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});
+      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,family:rule.family||null});
       from=i+1;
     }
   }
@@ -319,7 +408,7 @@ function partsFromClause(clause){
   const hits=findKeywordHits(clause);
   if(!hits.length){
     const text=clauseLabel(clause);
-    return text?[{text,modalities:[],keywords:[]}]:[];
+    return text?[{text,modalities:[],keywords:[],family:null}]:[];
   }
   const groups=[];
   for(const hit of hits){
@@ -328,17 +417,18 @@ function partsFromClause(clause){
       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(hit.family&&!last.family)last.family=hit.family;
+    }else groups.push({modalities:[...hit.modalities],keywords:[hit.phrase],hits:[hit],family:hit.family||null});
   }
   if(groups.length===1){
     const text=clauseLabel(clause)||groups[0].keywords.join(' ');
-    return [{text,modalities:groups[0].modalities,keywords:groups[0].keywords}];
+    return [{text,modalities:groups[0].modalities,keywords:groups[0].keywords,family:groups[0].family}];
   }
   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};
+    return {text,modalities:group.modalities,keywords:group.keywords,family:group.family};
   });
 }
 
@@ -375,76 +465,259 @@ function oneLine(bot){
   return line.replace(/\s+/g,' ').slice(0,180);
 }
 
-function whyLine(modality,keywords){
+function whyLine(modality,keywords,tail='top-ranked in modality'){
   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`;
+  return hint?`matched ${modality}/${hint}; ${tail}`:`matched ${modality}; ${tail}`;
+}
+
+const KIND_CATALOG='catalog integration';
+const KIND_SUGGEST='suggestion: build yourself / platform API';
+const OPTIONAL_COVERAGE=new Set(['share','shares','shared','sharing','post','posts','posting','posted','send','sends','sending','sent','detect','detects','detecting','start','starts','starting','create','creates','use','uses','using','based','optionally','optional','results','data','experience','that','them']);
+const SUGGEST={
+  wearable:'Wear OS sensor APIs and Health Connect are not in the kloudy 1.0 catalog. Build the sensing yourself or call the platform API. Unverified non-catalog guidance, not a catalog bot.',
+  sync:'Health Connect is not in the kloudy 1.0 catalog. It is a platform API for sending step data to an Android phone. Unverified non-catalog guidance, not a catalog bot.',
+  social:'The Facebook Graph API, Instagram API, and X API are not catalog bots. Unverified non-catalog guidance. Build the post yourself or call the platform API.'
+};
+const WEAK_REASON={
+  wearable:'Nearest catalog bots match a related fitness wearable (Garmin, Fitbit, or Apple Health), not Galaxy Watch step sensing.',
+  timer:'Catalog timers or schedulers share a timer or schedule keyword, but none start a timer from movement.',
+  sync:'Catalog Android tools share the Android keyword, but they do not send step data to a phone.',
+  nutrition:'Catalog nutrition tools only partly overlap this meal or calorie need.',
+  social:'Catalog social tools only partly overlap this post or share need.'
+};
+const CAP_NOISE=new Set(['connect','mcp','llm','language','agents','agent','scheduling','notifications','notification','api','calls','call','data','text','code','web','database','audio','video','image','memory','search','orchestration','skill','vision','browser','filesystem','security','cloud','comms']);
+const SYNC_DENY=/\b(?:figma|frida|linkedin|phonepe|phonehome|phone-a-friend|phone-harness)\b/i;
+const WATCH_DENY=/opencode|watchtower|framewatch|filewatch|firewatch|cloudwatch|swatch|cybersec|rewatch|langwatch|webwatch|vibewatch/i;
+
+function contentKeywords(keywords){
+  const out=[];
+  for(const keyword of keywords||[]){
+    const text=String(keyword||'').toLowerCase();
+    if(!text||OPTIONAL_COVERAGE.has(text)||out.includes(text))continue;
+    out.push(text);
+  }
+  return out;
+}
+
+function botBlob(bot){
+  const caps=(bot.caps||[]).map(c=>String(c).replace(/^cap\./,'').replace(/^mcp\./,''));
+  return `${bot.name||''} ${bot.id||''} ${caps.join(' ')}`.toLowerCase();
+}
+
+function botTokens(bot){
+  return new Set(words(botBlob(bot)).filter(token=>!CAP_NOISE.has(token)));
+}
+
+function tokenCovers(tokens,raw,keyword){
+  const key=String(keyword||'').toLowerCase();
+  if(!key)return false;
+  if(key==='x')return tokens.has('twitter')||/(^|[^a-z0-9])x([^a-z0-9]|$)/.test(raw);
+  if(key.includes(' '))return raw.includes(key);
+  if(tokens.has(key))return true;
+  if(key.length>=6&&raw.includes(key))return true;
+  if(key.length>=4){
+    for(const token of tokens)if(token.startsWith(key)&&token.length<=key.length+3)return true;
+  }
+  return false;
+}
+
+function timerToken(token){
+  if(token==='timer'||token==='timers')return true;
+  if(token.startsWith('schedule')||token.includes('scheduler'))return true;
+  if(token==='cron'||(token.startsWith('cron')&&!token.startsWith('cronomet')&&token.length<=10))return true;
+  return false;
+}
+
+function familyHit(family,tokens,raw,keywords){
+  if(family==='wearable'){
+    const asked=(keywords||[]).join(' ').toLowerCase();
+    if(!/watch|step|fitness|pedometer|accelerometer|wear|health|garmin|fitbit|sensor/.test(asked))return null;
+    if(WATCH_DENY.test(raw))return null;
+    if([...tokens].some(token=>['garmin','fitbit','pedometer','accelerometer','smartwatch','wearable','fitness'].includes(token)))return 'related';
+    if(/apple-health|applehealth|health-connect|healthconnect|wear-os|wearos|galaxy-watch/.test(raw))return 'related';
+    return null;
+  }
+  if(family==='timer'){
+    const want=new Set((keywords||[]).map(keyword=>keyword.toLowerCase()));
+    if([...tokens].some(timerToken))return [...tokens].some(token=>token==='timer'||token==='timers')?'direct':'related';
+    if((want.has('trigger')||want.has('triggers')||want.has('triggered'))&&[...tokens].some(token=>token==='trigger'||token.startsWith('trigger')))return 'direct';
+    return null;
+  }
+  if(family==='sync'){
+    if(SYNC_DENY.test(raw))return null;
+    if([...tokens].some(token=>token==='android'||token==='adb'))return 'direct';
+    const want=new Set((keywords||[]).map(keyword=>keyword.toLowerCase()));
+    if(want.has('mobile')&&tokens.has('mobile'))return 'related';
+    if((want.has('phone')||want.has('phones'))&&(tokens.has('android')||tokens.has('adb')||tokens.has('sms')||[...tokens].some(token=>token.startsWith('push')||token.startsWith('notif'))))return 'related';
+    if((want.has('sync')||want.has('syncs')||want.has('synced')||want.has('syncing'))&&tokens.has('sync'))return 'related';
+    return null;
+  }
+  if(family==='nutrition'){
+    const want=new Set((keywords||[]).map(keyword=>keyword.toLowerCase()));
+    const allowed=new Set(['calorie','calories','nutrition','meal','meals','mealie','diet','diets','recipe','recipes']);
+    if(want.has('food')||want.has('foods')){allowed.add('food');allowed.add('foods');}
+    const hit=[...tokens].some(token=>allowed.has(token)||(allowed.has('meal')&&token.startsWith('meal')&&token.length<=7)||token.startsWith('calorie'));
+    return hit?'related':null;
+  }
+  if(family==='social'){
+    const want=new Set((keywords||[]).map(keyword=>keyword.toLowerCase()));
+    const nets=['facebook','instagram','twitter'].filter(net=>want.has(net)||(net==='twitter'&&want.has('x')));
+    const have=[...tokens].filter(token=>token==='facebook'||token==='instagram'||token==='twitter');
+    if(!have.length)return null;
+    if(nets.length&&!nets.some(net=>have.includes(net)))return null;
+    return 'direct';
+  }
+  return null;
+}
+
+function overrideRank(scores,id){
+  const action=scores?.bots?.[id]?.action;
+  if(action==='boost')return -1;
+  if(action==='demote')return 1;
+  return 0;
+}
+
+function excluded(scores,id){
+  return scores?.bots?.[id]?.action==='exclude';
 }
 
-function rankModality(bots,modality,keywords,limit){
+export function parseLimit(value){
+  if(value==null||value==='')return DEFAULT_LIMIT;
+  const text=String(value);
+  if(!/^\d+$/.test(text))throw new Error('Limit must be an integer from 1 to 20');
+  const n=Number(text);
+  if(!Number.isInteger(n)||n<MIN_LIMIT||n>MAX_LIMIT)throw new Error('Limit must be an integer from 1 to 20');
+  return n;
+}
+
+export function stackIdFor(parts,unmatched=[]){
+  const lines=[];
+  for(const part of parts){
+    lines.push('part:'+part.part);
+    for(const bot of part.bots)lines.push('bot:'+bot.id);
+  }
+  for(const item of unmatched)lines.push('unmatched:'+item.part);
+  return createHash('sha256').update(lines.join('\n')).digest('hex');
+}
+
+export function feedbackLine(stackId){
+  return `kloudy feedback --stack ${stackId} --bot <id> --result worked|failed|partial [--reason <short>]`;
+}
+
+function selectFamily(bots,piece,limit,scores){
+  const want=piece.modalities||[];
+  const pool=[];
+  for(let i=0;i<bots.length;i++){
+    const bot=bots[i];
+    if(!installCommand(bot)||excluded(scores,bot.id))continue;
+    const raw=botBlob(bot);
+    const tokens=botTokens(bot);
+    const hit=familyHit(piece.family,tokens,raw,piece.keywords);
+    if(!hit)continue;
+    const need=contentKeywords(piece.keywords);
+    const hits=need.filter(keyword=>tokenCovers(tokens,raw,keyword)).length;
+    pool.push({b:bot,i,hits,direct:hit==='direct'||need.some(keyword=>tokenCovers(tokens,raw,keyword))?1:0});
+  }
+  const tier=cls=>CLASS_TIER[cls]??9;
+  pool.sort((x,y)=>y.direct-x.direct||tier(x.b.cls)-tier(y.b.cls)||overrideRank(scores,x.b.id)-overrideRank(scores,y.b.id)||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)));
+  const chosen=pool.slice(0,limit).map(x=>x.b);
+  const need=contentKeywords(piece.keywords);
+  const confidence=!chosen.length?'none':!need.length||need.every(keyword=>chosen.some(bot=>tokenCovers(botTokens(bot),botBlob(bot),keyword)))?'match':'weak';
+  return {bots:chosen,confidence,candidatesTotal:pool.length};
+}
+
+function botItem(bot,modality,keywords,tail){
+  return {
+    id:bot.id,
+    name:bot.name,
+    class:bot.cls,
+    command:installCommand(bot),
+    license:bot.license||'',
+    description:oneLine(bot),
+    why:whyLine(modality,keywords,tail),
+    modalities:[modality]
+  };
+}
+
+function rankModality(bots,modality,keywords,scores){
   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;
+    if(!(b.modalities||[]).includes(modality)||excluded(scores,b.id))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);
+  pool.sort((x,y)=>tier(x.b.cls)-tier(y.b.cls)||overrideRank(scores,x.b.id)-overrideRank(scores,y.b.id)||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.map(x=>x.b);
+}
+
+function recordPiece(piece,bots,confidence,parts,unmatched,gaps,candidatesTotal=bots.length){
+  if(bots.length)parts.push({part:piece.text,modalities:piece.modalities,confidence,candidatesTotal,bots});
+  else unmatched.push({part:piece.text,reason:'no modality or catalog match'});
+  if(confidence==='match')return;
+  if(bots.length)gaps.push({part:piece.text,confidence,reason:WEAK_REASON[piece.family]||'Catalog hits only partly overlap this part.',kind:KIND_CATALOG});
+  const suggestKind=piece.family==='wearable'||piece.family==='sync'||piece.family==='social';
+  if(suggestKind&&SUGGEST[piece.family])gaps.push({part:piece.text,confidence:'none',reason:SUGGEST[piece.family],kind:KIND_SUGGEST});
+  else if(!bots.length)gaps.push({part:piece.text,confidence:'none',reason:'no modality or catalog match'});
 }
 
 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 limit=parseLimit(options.limit??options.perModality??PER_MODALITY);
+  const scores=normalizeScores(options.scores);
   const pieces=decomposeGoal(goal);
   const parts=[];
   const unmatched=[];
-  const consider=pieces.length?pieces:[{text:String(goal||'').trim(),modalities:[],keywords:[]}];
+  const gaps=[];
+  const consider=pieces.length?pieces:[{text:String(goal||'').trim(),modalities:[],keywords:[],family:null}];
   for(const piece of consider){
     if(!piece.text)continue;
+    if(piece.family){
+      const picked=selectFamily(source.bots,piece,limit,scores);
+      const modality=piece.modalities[0];
+      const bots=picked.bots.map(bot=>botItem(bot,modality,piece.keywords,'catalog name search'));
+      for(const bot of bots)bot.modalities=[...piece.modalities];
+      recordPiece(piece,bots,picked.confidence,parts,unmatched,gaps,picked.candidatesTotal);
+      continue;
+    }
     if(!piece.modalities.length){
-      unmatched.push({part:piece.text,reason:'no modality or catalog match'});
+      recordPiece(piece,[], 'none',parts,unmatched,gaps,0);
       continue;
     }
     const seen=new Map();
-    const bots=[];
+    const ranked=[];
     for(const modality of piece.modalities){
-      for(const bot of rankModality(source.bots,modality,piece.keywords,limit)){
+      for(const bot of rankModality(source.bots,modality,piece.keywords,scores)){
         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]
-        };
+        const item={bot,modalities:[modality]};
         seen.set(bot.id,item);
-        bots.push(item);
+        ranked.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});
+    const bots=ranked.slice(0,limit).map(({bot,modalities})=>{
+      const item=botItem(bot,modalities[0],piece.keywords);
+      item.modalities=modalities;
+      return item;
+    });
+    recordPiece(piece,bots,bots.length?'match':'none',parts,unmatched,gaps,ranked.length);
   }
-  return {schema:RECOMMEND_SCHEMA,catalog:CATALOG_NAME,version:options.version||packageVersion(),goal:String(goal??''),parts,unmatched};
+  const complete=parts.length>0&&parts.every(part=>part.confidence==='match')&&gaps.length===0&&unmatched.length===0;
+  const stackId=stackIdFor(parts,unmatched);
+  return {schema:RECOMMEND_SCHEMA,catalog:CATALOG_NAME,version:options.version||packageVersion(),goal:String(goal??''),limit,stackId,feedback:feedbackLine(stackId),complete,parts,unmatched,gaps};
 }
 
 export function formatRecommend(result){
-  const lines=[`${result.catalog}  ·  package ${result.version}`,`Goal: ${result.goal}`];
+  const lines=[`${result.catalog}  ·  package ${result.version}`,`Goal: ${result.goal}`,`complete=${result.complete?'true':'false'}`,`limit=${result.limit}`,`stackId: ${result.stackId}`,`feedback: ${result.feedback}`];
   result.parts.forEach((part,index)=>{
-    lines.push('',`${index+1}. ${part.part}`,`Modalities: ${part.modalities.join(', ')}`);
+    lines.push('',`${index+1}. ${part.part}`,`Modalities: ${part.modalities.join(', ')}`,`Confidence: ${part.confidence}`,`Candidates: ${part.candidatesTotal}`);
     part.bots.forEach((bot,n)=>{
       lines.push(`  ${n+1}) ${bot.id}  [${bot.class}]  ${bot.license||'unknown license'}`,`     ${bot.command}`,`     ${bot.description}`,`     why: ${bot.why}`);
     });
@@ -453,15 +726,20 @@ export function formatRecommend(result){
     lines.push('','Unmatched');
     for(const item of result.unmatched)lines.push(`- ${item.part}: ${item.reason}`);
   }
+  lines.push('','Gaps');
+  if(!result.gaps.length)lines.push('(none)');
+  else for(const gap of result.gaps)lines.push(`- ${gap.part} [${gap.confidence}]${gap.kind?` ${gap.kind}:`:''} ${gap.reason}`);
   return lines.join('\n');
 }
 
-export function recommendCommand(args,opts={}){
+export async 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);
+  if(!goal)throw new Error('Usage: kloudy recommend <goal> [--json] [--limit N]');
+  const limit=parseLimit(o.limit);
+  const scores=opts.scores!==undefined?opts.scores:await loadScoreOverrides({offline:!!o.offline,fetchImpl:opts.fetch,now:opts.now,dir:opts.dataDir,url:opts.scoresUrl});
+  const result=recommendGoal(goal,{limit,scores});
   out(o.json?JSON.stringify(result,null,2):formatRecommend(result));
   return result;
 }

package/src/scores.mjs

@@ -0,0 +1,80 @@
+// Optional recommend score overrides. No model call.
+// GET https://kloudy.ai/api/feedback/scores, cache about 24h, else bundled ranking.
+import {existsSync,mkdirSync,readFileSync,writeFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join} from 'node:path';
+
+export const SCORES_URL='https://kloudy.ai/api/feedback/scores';
+export const SCORES_SCHEMA='kloudy.feedback-scores/1';
+export const SCORE_TTL_MS=24*60*60*1000;
+const ACTIONS=new Set(['boost','demote','exclude']);
+const DISABLED=new Set(['','off','offline','0','false']);
+
+export function dataDir(){
+  return process.env.KLOUDY_DATA_DIR||join(homedir(),'.kloudy');
+}
+
+export function scoresCachePath(dir=dataDir()){
+  return join(dir,'feedback-scores-cache.json');
+}
+
+function botsOf(body){
+  if(body.bots&&typeof body.bots==='object'&&!Array.isArray(body.bots))return body.bots;
+  const scores=body.scores;
+  if(!scores||typeof scores!=='object'||Array.isArray(scores))return null;
+  if(scores.bots&&typeof scores.bots==='object'&&!Array.isArray(scores.bots))return scores.bots;
+  return scores;
+}
+
+export function normalizeScores(body){
+  if(!body||typeof body!=='object'||Array.isArray(body))return null;
+  const source=botsOf(body);
+  if(!source)return null;
+  const bots={};
+  for(const [id,row] of Object.entries(source)){
+    if(typeof id!=='string'||!id)continue;
+    const action=typeof row==='string'?row:row&&row.action;
+    if(ACTIONS.has(action))bots[id]={action};
+  }
+  return {schema:typeof body.schema==='string'?body.schema:SCORES_SCHEMA,bots};
+}
+
+function scoresUrl(explicit){
+  const value=explicit??process.env.KLOUDY_SCORES_URL??SCORES_URL;
+  return DISABLED.has(String(value).trim())?null:value;
+}
+
+function readCache(file,now){
+  try{
+    if(!existsSync(file))return null;
+    const wrapped=JSON.parse(readFileSync(file,'utf8'));
+    const scores=normalizeScores(wrapped.scores??wrapped);
+    const fetchedAt=Number(wrapped.fetchedAt);
+    if(!scores||!Number.isFinite(fetchedAt))return null;
+    return {fetchedAt,scores,fresh:now-fetchedAt>=0&&now-fetchedAt<SCORE_TTL_MS};
+  }catch{
+    return null;
+  }
+}
+
+function writeCache(file,fetchedAt,scores){
+  mkdirSync(join(file,'..'),{recursive:true});
+  writeFileSync(file,JSON.stringify({fetchedAt,scores})+'\n');
+}
+
+export async function loadScoreOverrides({fetchImpl=fetch,now=Date.now(),offline=false,dir=dataDir(),url}={}){
+  const cached=readCache(scoresCachePath(dir),now);
+  if(cached?.fresh)return cached.scores;
+  const endpoint=scoresUrl(url);
+  if(offline||!endpoint)return null;
+  try{
+    const response=await fetchImpl(endpoint,{method:'GET',redirect:'error',credentials:'omit',headers:{accept:'application/json'},signal:AbortSignal.timeout(4000)});
+    if(!response?.ok)return null;
+    const scores=normalizeScores(await response.json());
+    if(!scores)return null;
+    writeCache(scoresCachePath(dir),now,scores);
+    return scores;
+  }catch{
+    return null;
+  }
+}