kloudy 1.0.1 → 1.0.3

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;
 }