rapidkit 0.37.0 → 0.38.0

package/dist/{pipeline-BOU4KETN.js → pipeline-C4UCLETO.js}

@@ -1,4 +1,4 @@
-import {c}from'./chunk-7VSYTOOG.js';import {b}from'./chunk-JBDQADHY.js';import {b as b$1}from'./chunk-RUUDLAKJ.js';import {a as a$1}from'./chunk-T5LN7EO5.js';import {a as a$2}from'./chunk-6P5DCHBQ.js';import {a}from'./chunk-KMUWWZRT.js';import {e,d}from'./chunk-B2KOIORF.js';import c$1 from'chalk';import D from'fs-extra';import u from'path';function C(t){return t===0?"pass":t===2?"warn":"fail"}function M(t){return t.some(s=>s.status==="fail")?"blocked":t.some(s=>s.status==="warn")?"needs-attention":"ready"}function F(t,s){if(s)return 3;let a=t.some(i=>i.status==="fail"),r=t.some(i=>i.status==="warn");return a?1:r?2:0}async function j(t){let s=await b$1(t,true),a=false;try{let{syncWorkspaceContract:r}=await import('./workspace-contract-D5O4OZD5.js');await r({workspacePath:t}),a=true;}catch{a=false;}return {sync:s,contractSynced:a}}async function G(t={}){let s=u.resolve(t.workspacePath??process.cwd()),a$3=a(s);if(!a$3)throw new Error("No RapidKit workspace found in current directory or parents");let r=[],i=[],l=false,p,y,m,f=Date.now();try{let{sync:e,contractSynced:n}=await j(a$3),o=e.workspaceFound&&(e.added.length>0||e.skipped>=0)||e.workspaceFound?"pass":"warn";r.push({name:"sync",status:o,durationMs:Date.now()-f,summary:e.workspaceFound?`registry sync complete (${e.added.length} added, ${e.skipped} existing)${n?", contract synced":""}`:"workspace not registered in global registry; contract sync attempted"}),e.workspaceFound||i.push("workspace registry entry missing \u2014 run rapidkit create workspace or register manually");}catch(e){l=true,r.push({name:"sync",status:"fail",durationMs:Date.now()-f,summary:`sync failed: ${e instanceof Error?e.message:String(e)}`}),i.push("workspace sync stage failed");}let w=Date.now();try{let e=await b({workspace:true,json:true,quiet:true,strict:t.strict===true,ci:t.strict!==true}),n=C(e),o=u.join(a$3,".rapidkit","reports","doctor-last-run.json");r.push({name:"doctor",status:n,durationMs:Date.now()-w,summary:n==="pass"?"doctor workspace passed":n==="warn"?"doctor workspace reported warnings":"doctor workspace reported errors",exitCode:e,evidencePath:o}),n==="fail"?i.push("doctor workspace gate failed"):n==="warn"&&i.push("doctor workspace reported warnings");}catch(e){l=true,r.push({name:"doctor",status:"fail",durationMs:Date.now()-w,summary:`doctor failed: ${e instanceof Error?e.message:String(e)}`}),i.push("doctor workspace stage failed");}if(t.skipAnalyze)r.push({name:"analyze",status:"skipped",durationMs:0,summary:"analyze stage skipped"});else {let e=Date.now();try{let n=await a$1({workspacePath:a$3,json:true,strict:t.strict===true});p=u.join(a$3,".rapidkit","reports","analyze-last-run.json");let o=n.summary.verdict==="blocked"?"fail":n.summary.verdict==="needs-attention"?"warn":"pass";r.push({name:"analyze",status:o,durationMs:Date.now()-e,summary:`analyze verdict: ${n.summary.verdict} (score ${n.summary.score}/100)`,evidencePath:p}),o==="fail"?i.push("analyze reported blocked verdict"):o==="warn"&&i.push("analyze reported needs-attention verdict");}catch(n){l=true,r.push({name:"analyze",status:"fail",durationMs:Date.now()-e,summary:`analyze failed: ${n instanceof Error?n.message:String(n)}`}),i.push("analyze stage failed");}}let h=Date.now();try{let e=await a$2({startPath:a$3,writeReport:true,skipVerify:t.skipVerify===true});y=e.evidencePath;let n=e.overallStatus==="pass"?"pass":e.overallStatus==="warn"?"warn":"fail";r.push({name:"readiness",status:n,durationMs:Date.now()-h,summary:`readiness overall: ${e.overallStatus}`,evidencePath:e.evidencePath}),n==="fail"?i.push(...e.blockingReasons.map(o=>`readiness: ${o}`)):n==="warn"&&i.push(...e.gates.filter(o=>o.status==="warn").map(o=>`readiness warn: ${o.gate}: ${o.summary}`));}catch(e){l=true,r.push({name:"readiness",status:"fail",durationMs:Date.now()-h,summary:`readiness failed: ${e instanceof Error?e.message:String(e)}`}),i.push("readiness stage failed");}if(t.skipAutopilot)r.push({name:"autopilot",status:"skipped",durationMs:0,summary:"autopilot stage skipped"});else {let e=Date.now(),n=t.autopilotMode??"audit";try{let o=await c({workspacePath:a$3,mode:n,json:true,skipPipelineStages:true});m=o.artifacts.reportPath;let P=o.summary.verdict==="approved"?"pass":o.summary.verdict==="partial"?"warn":"fail";r.push({name:"autopilot",status:P,durationMs:Date.now()-e,summary:`autopilot ${n}: ${o.summary.verdict}`,exitCode:o.summary.exitCode,evidencePath:m}),P!=="pass"&&i.push(...o.blockingReasons.slice(0,5));}catch(o){l=true,r.push({name:"autopilot",status:"fail",durationMs:Date.now()-e,summary:`autopilot failed: ${o instanceof Error?o.message:String(o)}`}),i.push("autopilot release stage failed");}}let z=M(r),k=F(r,l),g=u.join(a$3,".rapidkit","reports","pipeline-last-run.json"),d$1={schemaVersion:"rapidkit-pipeline-v1",generatedAt:new Date().toISOString(),workspacePath:a$3,summary:{verdict:z,exitCode:k,stagesPassed:r.filter(e=>e.status==="pass").length,stagesWarn:r.filter(e=>e.status==="warn").length,stagesFailed:r.filter(e=>e.status==="fail").length},stages:r,blockingReasons:[...new Set(i)],artifacts:{reportPath:g,analyzeEvidencePath:p,readinessEvidencePath:y,autopilotEvidencePath:m}};if(t.writeReport!==false){await D.ensureDir(u.dirname(g));let e$1=e(d$1,{commandId:"workspacePipeline",exitCode:k,generatedAt:d$1.generatedAt,blockers:d$1.blockingReasons,runId:d()});await D.writeJSON(g,e$1,{spaces:2});}if(t.writeReport!==false&&t.noAgentSync!==true&&process.env.RAPIDKIT_NO_AGENT_SYNC!=="1"&&t.agentSync!==false)try{let{syncWorkspaceAgentGrounding:e}=await import('./workspace-agent-sync-V2H6NTGD.js'),n=await e({workspacePath:a$3,write:true,refreshContext:true,strict:false});d$1.agentGrounding={indexPath:n.indexPath,writtenFiles:n.writtenFiles,blockers:n.blockers};}catch{}return d$1}async function X(t){let s;try{s=await G(t);}catch(a){let r=a instanceof Error?a.message:String(a);t.json?console.log(JSON.stringify({schemaVersion:"rapidkit-pipeline-error-v1",ok:false,error:{message:r}},null,2)):console.log(c$1.red(`Pipeline failed: ${r}`)),process.exit(1);}if(t.json)console.log(JSON.stringify(s,null,2));else {console.log(c$1.bold.cyan(`
+import {c}from'./chunk-NKNMGWAZ.js';import {b}from'./chunk-JBDQADHY.js';import {b as b$1}from'./chunk-5NBYSXOZ.js';import {a as a$1}from'./chunk-T5LN7EO5.js';import {a as a$2}from'./chunk-6P5DCHBQ.js';import {a}from'./chunk-KMUWWZRT.js';import {e,d}from'./chunk-B2KOIORF.js';import c$1 from'chalk';import D from'fs-extra';import u from'path';function C(t){return t===0?"pass":t===2?"warn":"fail"}function M(t){return t.some(s=>s.status==="fail")?"blocked":t.some(s=>s.status==="warn")?"needs-attention":"ready"}function F(t,s){if(s)return 3;let a=t.some(i=>i.status==="fail"),r=t.some(i=>i.status==="warn");return a?1:r?2:0}async function j(t){let s=await b$1(t,true),a=false;try{let{syncWorkspaceContract:r}=await import('./workspace-contract-D5O4OZD5.js');await r({workspacePath:t}),a=true;}catch{a=false;}return {sync:s,contractSynced:a}}async function G(t={}){let s=u.resolve(t.workspacePath??process.cwd()),a$3=a(s);if(!a$3)throw new Error("No RapidKit workspace found in current directory or parents");let r=[],i=[],l=false,p,y,m,f=Date.now();try{let{sync:e,contractSynced:n}=await j(a$3),o=e.workspaceFound&&(e.added.length>0||e.skipped>=0)||e.workspaceFound?"pass":"warn";r.push({name:"sync",status:o,durationMs:Date.now()-f,summary:e.workspaceFound?`registry sync complete (${e.added.length} added, ${e.skipped} existing)${n?", contract synced":""}`:"workspace not registered in global registry; contract sync attempted"}),e.workspaceFound||i.push("workspace registry entry missing \u2014 run rapidkit create workspace or register manually");}catch(e){l=true,r.push({name:"sync",status:"fail",durationMs:Date.now()-f,summary:`sync failed: ${e instanceof Error?e.message:String(e)}`}),i.push("workspace sync stage failed");}let w=Date.now();try{let e=await b({workspace:true,json:true,quiet:true,strict:t.strict===true,ci:t.strict!==true}),n=C(e),o=u.join(a$3,".rapidkit","reports","doctor-last-run.json");r.push({name:"doctor",status:n,durationMs:Date.now()-w,summary:n==="pass"?"doctor workspace passed":n==="warn"?"doctor workspace reported warnings":"doctor workspace reported errors",exitCode:e,evidencePath:o}),n==="fail"?i.push("doctor workspace gate failed"):n==="warn"&&i.push("doctor workspace reported warnings");}catch(e){l=true,r.push({name:"doctor",status:"fail",durationMs:Date.now()-w,summary:`doctor failed: ${e instanceof Error?e.message:String(e)}`}),i.push("doctor workspace stage failed");}if(t.skipAnalyze)r.push({name:"analyze",status:"skipped",durationMs:0,summary:"analyze stage skipped"});else {let e=Date.now();try{let n=await a$1({workspacePath:a$3,json:true,strict:t.strict===true});p=u.join(a$3,".rapidkit","reports","analyze-last-run.json");let o=n.summary.verdict==="blocked"?"fail":n.summary.verdict==="needs-attention"?"warn":"pass";r.push({name:"analyze",status:o,durationMs:Date.now()-e,summary:`analyze verdict: ${n.summary.verdict} (score ${n.summary.score}/100)`,evidencePath:p}),o==="fail"?i.push("analyze reported blocked verdict"):o==="warn"&&i.push("analyze reported needs-attention verdict");}catch(n){l=true,r.push({name:"analyze",status:"fail",durationMs:Date.now()-e,summary:`analyze failed: ${n instanceof Error?n.message:String(n)}`}),i.push("analyze stage failed");}}let h=Date.now();try{let e=await a$2({startPath:a$3,writeReport:true,skipVerify:t.skipVerify===true});y=e.evidencePath;let n=e.overallStatus==="pass"?"pass":e.overallStatus==="warn"?"warn":"fail";r.push({name:"readiness",status:n,durationMs:Date.now()-h,summary:`readiness overall: ${e.overallStatus}`,evidencePath:e.evidencePath}),n==="fail"?i.push(...e.blockingReasons.map(o=>`readiness: ${o}`)):n==="warn"&&i.push(...e.gates.filter(o=>o.status==="warn").map(o=>`readiness warn: ${o.gate}: ${o.summary}`));}catch(e){l=true,r.push({name:"readiness",status:"fail",durationMs:Date.now()-h,summary:`readiness failed: ${e instanceof Error?e.message:String(e)}`}),i.push("readiness stage failed");}if(t.skipAutopilot)r.push({name:"autopilot",status:"skipped",durationMs:0,summary:"autopilot stage skipped"});else {let e=Date.now(),n=t.autopilotMode??"audit";try{let o=await c({workspacePath:a$3,mode:n,json:true,skipPipelineStages:true});m=o.artifacts.reportPath;let P=o.summary.verdict==="approved"?"pass":o.summary.verdict==="partial"?"warn":"fail";r.push({name:"autopilot",status:P,durationMs:Date.now()-e,summary:`autopilot ${n}: ${o.summary.verdict}`,exitCode:o.summary.exitCode,evidencePath:m}),P!=="pass"&&i.push(...o.blockingReasons.slice(0,5));}catch(o){l=true,r.push({name:"autopilot",status:"fail",durationMs:Date.now()-e,summary:`autopilot failed: ${o instanceof Error?o.message:String(o)}`}),i.push("autopilot release stage failed");}}let z=M(r),k=F(r,l),g=u.join(a$3,".rapidkit","reports","pipeline-last-run.json"),d$1={schemaVersion:"rapidkit-pipeline-v1",generatedAt:new Date().toISOString(),workspacePath:a$3,summary:{verdict:z,exitCode:k,stagesPassed:r.filter(e=>e.status==="pass").length,stagesWarn:r.filter(e=>e.status==="warn").length,stagesFailed:r.filter(e=>e.status==="fail").length},stages:r,blockingReasons:[...new Set(i)],artifacts:{reportPath:g,analyzeEvidencePath:p,readinessEvidencePath:y,autopilotEvidencePath:m}};if(t.writeReport!==false){await D.ensureDir(u.dirname(g));let e$1=e(d$1,{commandId:"workspacePipeline",exitCode:k,generatedAt:d$1.generatedAt,blockers:d$1.blockingReasons,runId:d()});await D.writeJSON(g,e$1,{spaces:2});}if(t.writeReport!==false&&t.noAgentSync!==true&&process.env.RAPIDKIT_NO_AGENT_SYNC!=="1"&&t.agentSync!==false)try{let{syncWorkspaceAgentGrounding:e}=await import('./workspace-agent-sync-3FFFJYKF.js'),n=await e({workspacePath:a$3,write:true,refreshContext:true,strict:false});d$1.agentGrounding={indexPath:n.indexPath,writtenFiles:n.writtenFiles,blockers:n.blockers};}catch{}return d$1}async function X(t){let s;try{s=await G(t);}catch(a){let r=a instanceof Error?a.message:String(a);t.json?console.log(JSON.stringify({schemaVersion:"rapidkit-pipeline-error-v1",ok:false,error:{message:r}},null,2)):console.log(c$1.red(`Pipeline failed: ${r}`)),process.exit(1);}if(t.json)console.log(JSON.stringify(s,null,2));else {console.log(c$1.bold.cyan(`
 \u{1F517} RapidKit Governance Pipeline
 `)),console.log(c$1.bold(`Workspace: ${c$1.cyan(u.basename(s.workspacePath))}`)),console.log(c$1.gray(`Path: ${s.workspacePath}`)),console.log(c$1.white(`Verdict: ${s.summary.verdict}  Exit: ${s.summary.exitCode}  (${s.summary.stagesPassed} pass / ${s.summary.stagesWarn} warn / ${s.summary.stagesFailed} fail)`));for(let a of s.stages){let r=a.status==="pass"?c$1.green("PASS"):a.status==="warn"?c$1.yellow("WARN"):a.status==="skipped"?c$1.gray("SKIP"):c$1.red("FAIL");console.log(` - ${a.name}: ${r} ${a.summary}`);}if(s.blockingReasons.length>0){console.log(c$1.bold(`
 Blocking reasons:`));for(let a of s.blockingReasons.slice(0,8))console.log(c$1.gray(`  \u2022 ${a}`));}console.log(c$1.gray(`

package/dist/{workspace-2AL5C3QZ.js → workspace-WBKFXH4Z.js}

@@ -1 +1 @@
-export{e as createProject,d as createWorkspace,g as createWorkspaceShareBundle,f as listWorkspaces,c as registerProjectInWorkspace,a as registerWorkspace,b as syncWorkspaceProjects}from'./chunk-RUUDLAKJ.js';
+export{e as createProject,d as createWorkspace,g as createWorkspaceShareBundle,f as listWorkspaces,c as registerProjectInWorkspace,a as registerWorkspace,b as syncWorkspaceProjects}from'./chunk-5NBYSXOZ.js';

package/dist/{workspace-agent-sync-V2H6NTGD.js → workspace-agent-sync-3FFFJYKF.js}

@@ -1,4 +1,4 @@
-import {b,c,d}from'./chunk-EJGKBFV4.js';import i from'path';import c$1 from'fs-extra';var O="rapidkit-agent-reports-index.v1",E=".rapidkit/reports/INDEX.json",G=".rapidkit/AGENT-GROUNDING.md",S=[{relativePath:b,label:"Agent context pack",required:true},{relativePath:".rapidkit/reports/workspace-model.json",label:"Workspace model graph",required:false},{relativePath:".rapidkit/reports/doctor-last-run.json",label:"Workspace doctor",required:false},{relativePath:".rapidkit/reports/analyze-last-run.json",label:"Workspace analyze",required:false},{relativePath:".rapidkit/reports/pipeline-last-run.json",label:"Governance pipeline",required:false},{relativePath:".rapidkit/reports/release-readiness-last-run.json",label:"Release readiness",required:false},{relativePath:".rapidkit/reports/workspace-impact-last-run.json",label:"Workspace impact",required:false},{relativePath:".rapidkit/reports/workspace-verify-last-run.json",label:"Workspace verify",required:false}];function k(e){return `npx rapidkit ${e}`.trim()}function I(e){return e&&typeof e=="object"?e:null}function j(e,t=12){return Array.isArray(e)?e.filter(r=>typeof r=="string"&&r.trim().length>0).slice(0,t):[]}function q(e){let t=j(e.blockers,12);if(t.length>0)return t;let r=j(e.blockingReasons,12);if(r.length>0)return r;let n=I(e.summary);return n&&Array.isArray(n.blockingReasons)?j(n.blockingReasons,12):[]}function _(e){for(let t of ["generatedAt","timestamp"]){let r=e[t];if(typeof r=="string"&&r.trim())return r.trim()}}function $(e,t,r){if(!e)return  true;let n=Date.parse(e);return Number.isFinite(n)?r.getTime()-n>t*60*60*1e3:true}function K(e){let t=e&&e.length>0?e:["all"];return t.includes("all")?new Set(["all","agents","copilot","cursor","claude","codex","orca"]):new Set(t)}function u(e,t){return e.has("all")||e.has(t)}async function X(e){try{if(!await c$1.pathExists(e))return null;let t=await c$1.readJson(e);return I(t)}catch{return null}}async function F(e){let t=e.now??new Date,r=e.staleAfterHours??24,n=[],d=[];for(let l of S){let h=i.join(e.workspacePath,l.relativePath),a=await X(h),p=a!==null;p&&a&&d.push(...q(a)),n.push({path:l.relativePath,label:l.label,required:l.required,exists:p,generatedAt:a?_(a):void 0,commandId:typeof a?.commandId=="string"?a.commandId:void 0,exitCode:typeof a?.exitCode=="number"?a.exitCode:void 0});}let s=[...new Set(d.map(l=>l.trim()).filter(Boolean))].slice(0,16);return {schemaVersion:O,generatedAt:t.toISOString(),workspaceRoot:e.workspacePath,readOrder:S.map(l=>l.relativePath),blockers:s,staleAfterHours:r,reports:n,refreshCommand:k("workspace agent-sync --write --refresh-context")}}function N(e){let t=["# RapidKit agent grounding","","Cross-tool instructions for Copilot, Cursor, Claude Code, Codex, Grok, and other agents.","","## Read order (mandatory before workspace diagnosis)","","1. `.rapidkit/reports/INDEX.json` \u2014 latest blockers, timestamps, and report paths","2. `.rapidkit/reports/workspace-context-agent.json` \u2014 canonical agent context pack","3. Evidence artifacts listed in the index (doctor, analyze, pipeline, readiness, impact, verify)","","Do **not** full-repo scan until these reports are read or regenerated.","","## Regenerate intelligence","","```bash",k("workspace agent-sync --write --refresh-context"),k("workspace context --for-agent --json --write"),k("pipeline --json --write"),"```",""];if(e.index.blockers.length>0){t.push("## Current blockers","");for(let r of e.index.blockers.slice(0,12))t.push(`- ${r}`);t.push("");}if(e.context?.safeCommands?.length){t.push("## Safe commands (prefer these)","");for(let r of e.context.safeCommands.slice(0,10))t.push(`- \`${r.display}\` \u2014 ${r.description}`);t.push("");}return t.push("## Rules","","- Treat `.rapidkit/reports/*` as the source of truth for health, gates, and release posture.","- Prefer deterministic RapidKit CLI commands over heuristic framework guesses.","- If evidence is missing or stale, run the refresh commands above before proposing fixes.","- Keep project-scoped advice aligned with the active project named in the context pack.",""),t.join(`
+import {b,c,d}from'./chunk-IW3KLQXE.js';import i from'path';import c$1 from'fs-extra';var O="rapidkit-agent-reports-index.v1",E=".rapidkit/reports/INDEX.json",G=".rapidkit/AGENT-GROUNDING.md",S=[{relativePath:b,label:"Agent context pack",required:true},{relativePath:".rapidkit/reports/workspace-model.json",label:"Workspace model graph",required:false},{relativePath:".rapidkit/reports/doctor-last-run.json",label:"Workspace doctor",required:false},{relativePath:".rapidkit/reports/analyze-last-run.json",label:"Workspace analyze",required:false},{relativePath:".rapidkit/reports/pipeline-last-run.json",label:"Governance pipeline",required:false},{relativePath:".rapidkit/reports/release-readiness-last-run.json",label:"Release readiness",required:false},{relativePath:".rapidkit/reports/workspace-impact-last-run.json",label:"Workspace impact",required:false},{relativePath:".rapidkit/reports/workspace-verify-last-run.json",label:"Workspace verify",required:false}];function k(e){return `npx rapidkit ${e}`.trim()}function I(e){return e&&typeof e=="object"?e:null}function j(e,t=12){return Array.isArray(e)?e.filter(r=>typeof r=="string"&&r.trim().length>0).slice(0,t):[]}function q(e){let t=j(e.blockers,12);if(t.length>0)return t;let r=j(e.blockingReasons,12);if(r.length>0)return r;let n=I(e.summary);return n&&Array.isArray(n.blockingReasons)?j(n.blockingReasons,12):[]}function _(e){for(let t of ["generatedAt","timestamp"]){let r=e[t];if(typeof r=="string"&&r.trim())return r.trim()}}function $(e,t,r){if(!e)return  true;let n=Date.parse(e);return Number.isFinite(n)?r.getTime()-n>t*60*60*1e3:true}function K(e){let t=e&&e.length>0?e:["all"];return t.includes("all")?new Set(["all","agents","copilot","cursor","claude","codex","orca"]):new Set(t)}function u(e,t){return e.has("all")||e.has(t)}async function X(e){try{if(!await c$1.pathExists(e))return null;let t=await c$1.readJson(e);return I(t)}catch{return null}}async function F(e){let t=e.now??new Date,r=e.staleAfterHours??24,n=[],d=[];for(let l of S){let h=i.join(e.workspacePath,l.relativePath),a=await X(h),p=a!==null;p&&a&&d.push(...q(a)),n.push({path:l.relativePath,label:l.label,required:l.required,exists:p,generatedAt:a?_(a):void 0,commandId:typeof a?.commandId=="string"?a.commandId:void 0,exitCode:typeof a?.exitCode=="number"?a.exitCode:void 0});}let s=[...new Set(d.map(l=>l.trim()).filter(Boolean))].slice(0,16);return {schemaVersion:O,generatedAt:t.toISOString(),workspaceRoot:e.workspacePath,readOrder:S.map(l=>l.relativePath),blockers:s,staleAfterHours:r,reports:n,refreshCommand:k("workspace agent-sync --write --refresh-context")}}function N(e){let t=["# RapidKit agent grounding","","Cross-tool instructions for Copilot, Cursor, Claude Code, Codex, Grok, and other agents.","","## Read order (mandatory before workspace diagnosis)","","1. `.rapidkit/reports/INDEX.json` \u2014 latest blockers, timestamps, and report paths","2. `.rapidkit/reports/workspace-context-agent.json` \u2014 canonical agent context pack","3. Evidence artifacts listed in the index (doctor, analyze, pipeline, readiness, impact, verify)","","Do **not** full-repo scan until these reports are read or regenerated.","","## Regenerate intelligence","","```bash",k("workspace agent-sync --write --refresh-context"),k("workspace context --for-agent --json --write"),k("pipeline --json --write"),"```",""];if(e.index.blockers.length>0){t.push("## Current blockers","");for(let r of e.index.blockers.slice(0,12))t.push(`- ${r}`);t.push("");}if(e.context?.safeCommands?.length){t.push("## Safe commands (prefer these)","");for(let r of e.context.safeCommands.slice(0,10))t.push(`- \`${r.display}\` \u2014 ${r.description}`);t.push("");}return t.push("## Rules","","- Treat `.rapidkit/reports/*` as the source of truth for health, gates, and release posture.","- Prefer deterministic RapidKit CLI commands over heuristic framework guesses.","- If evidence is missing or stale, run the refresh commands above before proposing fixes.","- Keep project-scoped advice aligned with the active project named in the context pack.",""),t.join(`
 `)}function B(e){return ["# RapidKit agent grounding","",`Generated: ${e.generatedAt}`,"","This file is tool-agnostic. Synced agents should read it together with `.rapidkit/reports/INDEX.json`.","","## Mandatory read order","",...e.readOrder.map((t,r)=>`${r+1}. \`${t}\``),"",e.blockers.length>0?"## Blockers":"",...e.blockers.length>0?e.blockers.map(t=>`- ${t}`):[],"","## Refresh","","```bash",e.refreshCommand,"```",""].filter(t=>t!=="").join(`
 `)}function H(){return ["# RapidKit workspace grounding","","Before answering workspace, release, or architecture questions:","","1. Read `AGENTS.md` (managed RapidKit section).","2. Read `.rapidkit/reports/INDEX.json` and `.rapidkit/reports/workspace-context-agent.json`.","3. Use evidence reports before scanning the full repository.","","Regenerate stale intelligence:","","```bash",k("workspace agent-sync --write --refresh-context"),"```",""].join(`
 `)}function L(){return ["## Claude Code","","- Load `.rapidkit/reports/INDEX.json` before diagnosing blockers.","- Use `.claude/rules/rapidkit-evidence.md` when editing files under `.rapidkit/`.","- Refresh grounding with `npx rapidkit workspace agent-sync --write`.",""].join(`

package/dist/{workspace-context-KCKNV5VQ.js → workspace-context-V4UGIHSC.js}

@@ -1 +1 @@
-export{b as WORKSPACE_CONTEXT_AGENT_REPORT_PATH,a as WORKSPACE_CONTEXT_SCHEMA_VERSION,c as buildWorkspaceAgentContext,d as writeWorkspaceAgentContext}from'./chunk-EJGKBFV4.js';
+export{b as WORKSPACE_CONTEXT_AGENT_REPORT_PATH,a as WORKSPACE_CONTEXT_SCHEMA_VERSION,c as buildWorkspaceAgentContext,d as writeWorkspaceAgentContext}from'./chunk-IW3KLQXE.js';

package/dist/{workspace-foundation-L6ZBGMVE.js → workspace-foundation-T45HAWKL.js}

@@ -1 +1 @@
-import {b}from'./chunk-IOIWVHRO.js';import {a}from'./chunk-RV6HBTFC.js';import c from'path';import u from'fs-extra';async function W(t,r){let o=await a(t),d=o?.name||c.basename(t),n,i=c.join(t,".python-version");if(await u.pathExists(i)){let a=(await u.readFile(i,"utf-8")).trim();a&&(n=a);}let e=r?.profile||"polyglot",m=e==="python-only"||e==="polyglot"||e==="enterprise",f=r?.installMethod||o?.metadata?.npm?.installMethod||(m?"poetry":"venv"),s=await b(t,{workspaceName:d,installMethod:f,pythonVersion:n,profile:e,writeMarker:true,writeGitignore:true,onlyIfMissing:!r?.force}),{publishWorkspaceRegistrySummary:y}=await import('./workspace-registry-summary-MIPHVB56.js');return await y(t),{workspacePath:t,created:s,status:s.length>0?"passed":"skipped"}}export{W as ensureWorkspaceFoundation};
+import {b}from'./chunk-TVIOAZ6E.js';import {a}from'./chunk-RV6HBTFC.js';import c from'path';import u from'fs-extra';async function W(t,r){let o=await a(t),d=o?.name||c.basename(t),n,i=c.join(t,".python-version");if(await u.pathExists(i)){let a=(await u.readFile(i,"utf-8")).trim();a&&(n=a);}let e=r?.profile||"polyglot",m=e==="python-only"||e==="polyglot"||e==="enterprise",f=r?.installMethod||o?.metadata?.npm?.installMethod||(m?"poetry":"venv"),s=await b(t,{workspaceName:d,installMethod:f,pythonVersion:n,profile:e,writeMarker:true,writeGitignore:true,onlyIfMissing:!r?.force}),{publishWorkspaceRegistrySummary:y}=await import('./workspace-registry-summary-MIPHVB56.js');return await y(t),{workspacePath:t,created:s,status:s.length>0?"passed":"skipped"}}export{W as ensureWorkspaceFoundation};

package/dist/{workspace-intelligence-3TWXJQ7Y.js → workspace-intelligence-MGL3Z25K.js}

@@ -1 +1 @@
-export{f as WORKSPACE_IMPACT_REPORT_PATH,e as WORKSPACE_IMPACT_SCHEMA_VERSION,d as WORKSPACE_MODEL_DIFF_REPORT_PATH,b as WORKSPACE_MODEL_DIFF_SCHEMA_VERSION,c as WORKSPACE_MODEL_SNAPSHOT_REPORT_PATH,a as WORKSPACE_MODEL_SNAPSHOT_SCHEMA_VERSION,n as buildWorkspaceImpact,i as buildWorkspaceModelSnapshot,k as diffWorkspaceModel,g as isGitDiffSource,h as parseGitDiffRef,m as workspaceVerificationPlan,o as writeWorkspaceImpact,l as writeWorkspaceModelDiff,j as writeWorkspaceModelSnapshot}from'./chunk-U6QUN6V2.js';
+export{f as WORKSPACE_IMPACT_REPORT_PATH,e as WORKSPACE_IMPACT_SCHEMA_VERSION,d as WORKSPACE_MODEL_DIFF_REPORT_PATH,b as WORKSPACE_MODEL_DIFF_SCHEMA_VERSION,c as WORKSPACE_MODEL_SNAPSHOT_REPORT_PATH,a as WORKSPACE_MODEL_SNAPSHOT_SCHEMA_VERSION,n as buildWorkspaceImpact,i as buildWorkspaceModelSnapshot,k as diffWorkspaceModel,g as isGitDiffSource,h as parseGitDiffRef,m as workspaceVerificationPlan,o as writeWorkspaceImpact,l as writeWorkspaceModelDiff,j as writeWorkspaceModelSnapshot}from'./chunk-ABPDGFVD.js';

package/dist/{workspace-model-NQVZN5W4.js → workspace-model-IKMGY2BX.js}

@@ -1 +1 @@
-export{b as WORKSPACE_MODEL_REPORT_PATH,a as WORKSPACE_MODEL_SCHEMA_VERSION,d as buildWorkspaceModel,c as validateWorkspaceModelStrict,e as writeWorkspaceModel}from'./chunk-C7OVQQXT.js';
+export{b as WORKSPACE_MODEL_REPORT_PATH,a as WORKSPACE_MODEL_SCHEMA_VERSION,d as buildWorkspaceModel,c as validateWorkspaceModelStrict,e as writeWorkspaceModel}from'./chunk-XESEBTPE.js';

package/dist/workspace-run-HOR56FON.js

@@ -0,0 +1 @@
+export{a as runWorkspaceStage}from'./chunk-6E5TBB2C.js';export{a as WORKSPACE_RUN_LAST_REPORT_FILENAME}from'./chunk-FV5A3N3I.js';

package/dist/workspace-verify-A3J6D7T2.js

@@ -0,0 +1 @@
+import {m,f as f$1,c,n,e}from'./chunk-ABPDGFVD.js';import {d}from'./chunk-XESEBTPE.js';import {c as c$1}from'./chunk-FV5A3N3I.js';import p from'path';import g from'fs-extra';var R="workspace-verify.v1",S=".rapidkit/reports/workspace-verify-last-run.json";function C(e,s){return p.isAbsolute(s)?s:p.join(e,s)}async function P(e$1){let s=await g.readJson(e$1);if(!s||typeof s!="object"||Array.isArray(s))throw new Error(`Workspace impact input is not a JSON object: ${e$1}`);let r=s;if(r.schemaVersion!==e)throw new Error(`Unsupported workspace impact schema: ${String(r.schemaVersion)}`);return r}function I(e){let s=new Set,r=[];for(let a of e){let i=`${a.scope}:${a.project??""}:${a.display}`;s.has(i)||(s.add(i),r.push(a));}return r}function V(e,s){if(!e||e==="workspace")return  true;let r=(e.startsWith("project:")?e.slice(8):e).trim().toLowerCase();return s.scope==="workspace"?true:(s.project??"").trim().toLowerCase()===r}function A(e,s){if(e.id==="workspace.doctor")return p.join(s,".rapidkit","reports","doctor-last-run.json");if(e.id==="workspace.contract.verify")return p.join(s,".rapidkit","reports","workspace-contract-verify-last-run.json");if(e.id==="workspace.readiness")return p.join(s,".rapidkit","reports","release-readiness-last-run.json");if(e.id==="workspace.analyze")return p.join(s,".rapidkit","reports","analyze-last-run.json");if(e.id==="workspace.pipeline")return p.join(s,".rapidkit","reports","pipeline-last-run.json");if(e.id.startsWith("project.")&&(e.id.endsWith(".test")||e.id.endsWith(".build")))return p.join(s,".rapidkit","reports","workspace-run-last.json")}function k(e){return !e||typeof e!="object"||Array.isArray(e)?null:e}function $(e){let s=k(e.healthScore),r=typeof s?.errors=="number"?s.errors:0,a=typeof s?.percent=="number"?s.percent:void 0;return r>0?{status:"fail",message:`Doctor evidence reports ${r} error(s).`}:typeof a=="number"&&a<70?{status:"warn",message:`Doctor health score is ${a}%.`}:{status:"pass",message:"Doctor evidence is present and healthy."}}function M(e){let s=typeof e.overallStatus=="string"?e.overallStatus:"unknown";return s==="fail"?{status:"fail",message:"Release readiness evidence reports blocking failures."}:s==="warn"?{status:"warn",message:"Release readiness evidence reports warnings."}:s==="pass"?{status:"pass",message:"Release readiness evidence passed."}:{status:"warn",message:`Release readiness evidence status is ${s}.`}}function O(e){let s=typeof e.status=="string"?e.status:"unknown";return s==="failed"||s==="fail"?{status:"fail",message:"Workspace contract verify evidence failed."}:s==="passed"||s==="pass"?{status:"pass",message:"Workspace contract verify evidence passed."}:{status:"warn",message:`Workspace contract verify evidence status is ${s}.`}}function x(e){let s=k(e.summary);if(s?.blocking===true||e.blocking===true)return {status:"fail",message:"Analyze evidence reports blocking findings."};let a=typeof s?.status=="string"?s.status:void 0;return a==="warn"||a==="warning"?{status:"warn",message:"Analyze evidence reports warnings."}:{status:"pass",message:"Analyze evidence is present."}}function _(e){let s=k(e.summary),r=typeof s?.verdict=="string"?s.verdict:void 0;return r==="blocked"?{status:"fail",message:"Pipeline evidence is blocked."}:r==="needs-attention"?{status:"warn",message:"Pipeline evidence needs attention."}:r==="ready"?{status:"pass",message:"Pipeline evidence is ready."}:{status:"warn",message:"Pipeline evidence status is unknown."}}function D(e,s,r){let a=s.id.endsWith(".build")?"build":s.id.endsWith(".test")?"test":null,i=c$1(e,a);if(!i)return {status:"missing",message:"Workspace run evidence is missing or unreadable."};let u=i.stage;if(a&&u!==a)return {status:"missing",message:`Workspace run evidence is for stage "${u}", expected "${a}".`};let c=Array.isArray(i.projects)?i.projects:[],o=s.project?.toLowerCase();if(!o)return {status:"missing",message:"Project-scoped workspace run evidence is missing a project identifier."};let n=c.find(d=>{let t=k(d);if(!t)return  false;let m=typeof t.projectName=="string"?t.projectName.toLowerCase():"",E=["projectPath","relativePath","path"].map(l=>t[l]).filter(l=>typeof l=="string"&&l.trim().length>0).map(l=>l.replace(/\\/g,"/").toLowerCase());return m===o||E.some(l=>l.endsWith(`/${o}`)||l===o)});if(n){let d=f(i.generatedAt,r,`Workspace run evidence for ${s.project??s.id}`);if(d)return {status:"fail",message:d};let t=k(n),m=typeof t?.status=="string"?t.status:"unknown";return m==="failed"?{status:"fail",message:`Workspace run evidence failed for ${s.project}.`}:m==="passed"?{status:"pass",message:`Workspace run evidence passed for ${s.project}.`}:m==="skipped"?{status:"warn",message:`Workspace run evidence skipped for ${s.project}.`}:{status:"warn",message:`Workspace run evidence status is ${m} for ${s.project}.`}}return {status:"missing",message:`Workspace run evidence does not include project ${s.project}.`}}function f(e,s,r){if(typeof e!="string"||!s)return null;let a=Date.parse(e),i=Date.parse(s);return !Number.isFinite(a)||!Number.isFinite(i)?null:a<i?`${r} is stale: generated at ${e}, before impact ${s}.`:null}async function F(e,s,r,a){let i=A(e,s),u=i?p.relative(s,i).split(p.sep).join("/"):void 0;if(e.id==="workspace.contract.verify"&&!r)return {id:e.id,label:e.label,scope:e.scope,project:e.project,command:e,status:"skipped",required:e.required,message:"Workspace contract is not present; contract verify skipped."};if(!i||!await g.pathExists(i))return {id:e.id,label:e.label,scope:e.scope,project:e.project,command:e,status:"missing",required:e.required,evidencePath:u,message:u?`Missing evidence report: ${u}`:"No evidence mapping exists for this command."};let c=k(await g.readJson(i));if(!c)return {id:e.id,label:e.label,scope:e.scope,project:e.project,command:e,status:"fail",required:e.required,evidencePath:u,message:"Evidence report is not a JSON object."};let o;if(e.id==="workspace.doctor"){let n=f(c.generatedAt,a,"Doctor evidence");n?o={status:"fail",message:n}:o=$(c);}else if(e.id==="workspace.readiness"){let n=f(c.generatedAt,a,"Release readiness evidence");n?o={status:"fail",message:n}:o=M(c);}else if(e.id==="workspace.contract.verify"){let n=f(c.generatedAt,a,"Workspace contract verify evidence");n?o={status:"fail",message:n}:o=O(c);}else if(e.id==="workspace.analyze"){let n=f(c.generatedAt,a,"Analyze evidence");n?o={status:"fail",message:n}:o=x(c);}else if(e.id==="workspace.pipeline"){let n=f(c.generatedAt,a,"Pipeline evidence");n?o={status:"fail",message:n}:o=_(c);}else if(e.id.startsWith("project."))o=D(c,e,a);else {let n=f(c.generatedAt,a,"Evidence report");n?o={status:"fail",message:n}:o={status:"pass",message:"Evidence report is present."};}return {id:e.id,label:e.label,scope:e.scope,project:e.project,command:e,status:o.status,required:e.required,evidencePath:u,message:o.message}}function q(e){let s=e.filter(t=>t.status==="pass").length,r=e.filter(t=>t.status==="warn").length,a=e.filter(t=>t.status==="fail").length,i=e.filter(t=>t.status==="missing").length,u=e.filter(t=>t.status==="skipped").length,c=e.filter(t=>t.required&&(t.status==="fail"||t.status==="missing")).map(t=>`${t.id}: ${t.message}`),o=e.filter(t=>t.required&&t.status==="missing").length,n="ready",d=0;return c.length>0?(n="blocked",d=2):(r>0||o>0)&&(n="needs-attention",d=1),{verdict:n,exitCode:d,stepsPassed:s,stepsWarn:r,stepsFailed:a,stepsMissing:i,stepsSkipped:u}}async function N(e$1){let s=p.resolve(e$1.workspacePath);if(e$1.fromImpactPath){let u=C(s,e$1.fromImpactPath);return {impact:await P(u),fromImpactRef:p.relative(s,u).split(p.sep).join("/")}}let r=p.join(s,f$1);if(await g.pathExists(r))return {impact:await P(r),fromImpactRef:f$1};let a=p.join(s,c);if(await g.pathExists(a))return {impact:await n({workspacePath:s,fromPath:c,scope:e$1.scope,includeAbsolutePaths:e$1.includeAbsolutePaths,includeEvidence:e$1.includeEvidence,observableScanDepth:e$1.observableScanDepth,now:e$1.now}),fromImpactRef:c};let i=await d({workspacePath:s,includeAbsolutePaths:e$1.includeAbsolutePaths,includeEvidence:e$1.includeEvidence,observableScanDepth:e$1.observableScanDepth,now:e$1.now});return {impact:{schemaVersion:e,generatedAt:(e$1.now??new Date).toISOString(),fromRef:"baseline",diffRef:".rapidkit/reports/workspace-model-diff-last-run.json",workspace:{name:i.workspace.name,profile:i.workspace.profile,type:i.workspace.type},summary:{changed:false,risk:"none",affectedProjects:0,workspaceItems:0,recommendedCommands:0},affectedProjects:[],workspaceImpact:[],verificationPlan:[],agentBrief:{headline:"Baseline workspace verify run.",bullets:["No impact report or snapshot was available; baseline gates were evaluated."],unsafeAssumptions:["Do not claim runtime verification passed unless evidence exists."]},diff:{schemaVersion:"workspace-model-diff.v1",generatedAt:(e$1.now??new Date).toISOString(),fromRef:"baseline",toRef:".rapidkit/reports/workspace-model.json",fromHash:"baseline",toHash:"baseline",summary:{changed:false,addedProjects:0,removedProjects:0,changedProjects:0,workspaceChanges:0,validationChanges:0,gitChangedFiles:0},git:{available:false,dirty:false,changedFiles:0,untrackedFiles:0,deletedFiles:0},changes:[],currentModel:i}}}}async function Y(e){let s=p.resolve(e.workspacePath),{impact:r,fromImpactRef:a}=await N(e),i=r.diff.currentModel,u=I([...m(),...r.verificationPlan]).filter(t=>V(e.scope,t)),c=[];for(let t of u)c.push(await F(t,s,i.contracts.exists===true,r.generatedAt));let o=q(c),n=c.filter(t=>t.status==="missing"&&t.evidencePath).map(t=>t.evidencePath),d=c.filter(t=>t.required&&(t.status==="fail"||t.status==="missing")).map(t=>`${t.id}: ${t.message}`);return {schemaVersion:R,generatedAt:(e.now??new Date).toISOString(),workspacePath:s,mode:"evidence",fromImpactRef:a,scope:e.scope,impact:{changed:r.summary.changed,risk:r.summary.risk,affectedProjects:r.summary.affectedProjects,recommendedCommands:r.summary.recommendedCommands},summary:o,steps:c,missingEvidence:n,blockingReasons:d,verificationPlan:u}}async function U(e,s){let r=p.join(s,S);return await g.ensureDir(p.dirname(r)),await g.writeJson(r,e,{spaces:2}),r}function Q(e,s){return e.summary.verdict==="blocked"?2:s?.strict&&e.summary.verdict!=="ready"?1:e.summary.exitCode}export{S as WORKSPACE_VERIFY_REPORT_PATH,R as WORKSPACE_VERIFY_SCHEMA_VERSION,Y as buildWorkspaceVerify,Q as workspaceVerifyExitCode,U as writeWorkspaceVerify};

package/docs/AI_DYNAMIC_INTEGRATION.md

@@ -0,0 +1,440 @@
+# 🔄 Dynamic AI Integration with Python Core
+
+> **Date:** January 1, 2026  
+> **Implementation:** Dynamic module catalog fetching from Python Core
+
+---
+
+## 🎯 Summary
+
+AI system uses a **dynamic runtime catalog** and fetches module metadata from **RapidKit Python Core** instead of relying only on hardcoded entries.
+
+### Before (Static):
+
+```typescript
+// ❌ Hardcoded fixed subset
+export const MODULE_CATALOG = [
+  { id: 'authentication-core', ... },
+  // ... 10 more
+]
+```
+
+### After (Dynamic):
+
+```typescript
+// ✅ Fetches from Python Core
+export async function getModuleCatalog() {
+  const result = await exec('rapidkit modules list --json');
+  return parseModules(result);
+}
+```
+
+---
+
+## 📊 Architecture
+
+### Data Flow
+
+```
+User Query
+    ↓
+AI Recommender
+    ↓
+getModuleCatalog()
+    ↓
+    ├─ Try: rapidkit modules list --json
+    │   └─ Success: Return Python modules (runtime count)
+    │   └─ Fail: Return fallback catalog (baseline subset)
+    ↓
+Generate Embeddings
+    ↓
+Cosine Similarity
+    ↓
+Return Top Recommendations
+```
+
+---
+
+## 🔧 Implementation Details
+
+### 1. Dynamic Module Fetching (`src/ai/module-catalog.ts`)
+
+**Features:**
+
+- ✅ Calls `rapidkit modules list --json`
+- ✅ 5-minute cache (reduces Python calls)
+- ✅ Fallback to hardcoded catalog if Python not available
+- ✅ Automatic retry and error handling
+- ✅ Category and framework mapping
+
+**Code:**
+
+```typescript
+export async function getModuleCatalog(): Promise<ModuleMetadata[]> {
+  // Check cache
+  if (cachedModules && Date.now() - lastFetchTime < CACHE_TTL) {
+    return cachedModules;
+  }
+
+  // Fetch from Python Core
+  try {
+    const { stdout } = await execAsync('rapidkit modules list --json');
+    const modules = parseModules(stdout);
+    cachedModules = modules;
+    return modules;
+  } catch (error) {
+    console.warn('⚠️  Using fallback catalog');
+    return FALLBACK_MODULE_CATALOG;
+  }
+}
+```
+
+---
+
+### 2. Module Parsing
+
+**Handles different Python CLI output formats:**
+
+```typescript
+// Format 1: Array
+["module1", "module2"]
+
+// Format 2: Object with modules key
+{ "modules": [...] }
+
+// Format 3: Object with data key
+{ "data": [...] }
+```
+
+**Category Mapping:**
+
+```typescript
+Python Category → TypeScript Type
+├─ "auth" → "auth"
+├─ "authentication" → "auth"
+├─ "database" → "database"
+├─ "payment" → "payment"
+├─ "billing" → "payment"
+└─ etc.
+```
+
+---
+
+### 3. Cache Strategy
+
+**TTL: 5 minutes**
+
+```
+First call:
+├─ Fetch from Python (10s)
+├─ Cache result
+└─ Return
+
+Subsequent calls (within 5 min):
+├─ Return cached
+└─ Instant response
+
+After 5 min:
+├─ Re-fetch from Python
+└─ Update cache
+```
+
+**Benefits:**
+
+- ✅ Fast responses (cached)
+- ✅ Always up-to-date (5min refresh)
+- ✅ Reduces Python CLI calls
+
+---
+
+### 4. Fallback Mechanism
+
+**Graceful degradation:**
+
+```
+Try Python Core:
+├─ Success → Use runtime module catalog ✅
+├─ Python not in PATH → Use fallback subset ⚠️
+├─ Command timeout → Use fallback subset ⚠️
+└─ Parse error → Use fallback subset ⚠️
+```
+
+**Fallback catalog:**
+
+- Baseline core modules (hardcoded subset)
+- Authentication, database, payment, etc.
+- Enough for basic recommendations
+
+---
+
+### 5. Embedding Generation
+
+**Now dynamic:**
+
+```bash
+# Old: Generated from fixed hardcoded subset
+npx tsx src/ai/generate-embeddings.ts
+
+# New: Fetches from Python Core first
+# → Gets runtime module catalog
+# → Generates embeddings for all discovered modules
+# → Saves to data/modules-embeddings.json
+```
+
+**Output:**
+
+```json
+{
+  "model": "text-embedding-3-small",
+  "dimension": 1536,
+  "generated_at": "2026-01-01T...",
+  "modules": [
+    {
+      "id": "authentication-core",
+      "name": "Authentication Core",
+      "embedding": [0.123, -0.456, ...]
+    }
+    // ... runtime modules (from Python)
+  ]
+}
+```
+
+---
+
+## 🚀 Usage Examples
+
+### Example 1: With Python Core Available
+
+```bash
+$ rapidkit ai recommend "I need user authentication"
+
+# Behind the scenes:
+# 1. Calls: rapidkit modules list --json
+# 2. Gets runtime module catalog from Python Core
+# 3. Generates query embedding
+# 4. Compares with catalog embeddings
+# 5. Returns top 5 recommendations
+
+📦 Recommended Modules:
+1. authentication-core ⭐ (98% match)
+2. users-core ⭐ (92% match)
+3. session-management (88% match)
+...
+```
+
+---
+
+### Example 2: Without Python Core (Fallback)
+
+```bash
+$ rapidkit ai recommend "payment processing"
+
+# Console output:
+⚠️  RapidKit Python Core not found in PATH
+  Using fallback module catalog (baseline subset)
+
+# Still works! Uses hardcoded fallback subset
+📦 Recommended Modules:
+1. stripe-payment ⭐ (95% match)
+...
+```
+
+---
+
+### Example 3: No Matching Modules
+
+```bash
+$ rapidkit ai recommend "blockchain integration"
+
+# Output:
+⚠️  No matching modules found in RapidKit registry.
+
+💡 Options:
+
+1. Create custom module:
+   rapidkit modules scaffold blockchain-integration --category integrations
+
+2. Search with different keywords
+   Try more general terms (e.g., "storage" instead of "blockchain")
+
+3. Request feature:
+   https://github.com/rapidkitlabs/rapidkit/issues
+```
+
+---
+
+## 📋 Benefits
+
+### ✅ Always Up-to-Date
+
+```
+When Python Core adds new modules:
+├─ AI automatically picks them up
+├─ No code changes needed in npm
+├─ Just regenerate embeddings
+└─ Users get latest recommendations
+```
+
+### ✅ Single Source of Truth
+
+```
+Module Registry:
+├─ Python Core: runtime catalog (source of truth)
+├─ npm AI: Reads from Python (always synced)
+└─ No duplicate data
+```
+
+### ✅ Graceful Fallback
+
+```
+If Python unavailable:
+├─ Still works (fallback subset)
+├─ User informed (console warning)
+├─ No crashes or errors
+└─ Can upgrade to Python later
+```
+
+### ✅ Performance
+
+```
+Cache Strategy:
+├─ First call: 10s (Python fetch)
+├─ Cached calls: <100ms (instant)
+├─ Cache refresh: Every 5 minutes
+└─ Optimal balance
+```
+
+---
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```bash
+# Optional: Force fallback mode (testing)
+export RAPIDKIT_AI_FALLBACK=true
+
+# Optional: Cache TTL (default: 5 minutes)
+export RAPIDKIT_CACHE_TTL=600000  # milliseconds
+
+# Optional: Python command/interpreter override (if python3/python is not the right one)
+export RAPIDKIT_PYTHON_CMD=/path/to/python
+```
+
+---
+
+## 🧪 Testing
+
+### Test 1: With Python Core
+
+```bash
+# Ensure Python Core in PATH
+which rapidkit  # Should return path
+
+# Test recommendation
+rapidkit ai recommend "authentication"
+
+# Should show: using runtime catalog from Python Core
+```
+
+### Test 2: Without Python Core
+
+```bash
+# Temporarily hide Python
+export PATH=/tmp:$PATH
+
+# Test recommendation
+rapidkit ai recommend "authentication"
+
+# Should show: ⚠️ Using fallback catalog (baseline subset)
+```
+
+### Test 3: Cache Behavior
+
+```bash
+# First call (cold cache)
+time rapidkit ai recommend "auth"  # ~10 seconds
+
+# Second call (warm cache)
+time rapidkit ai recommend "database"  # <1 second
+
+# Wait 6 minutes, try again
+sleep 360
+time rapidkit ai recommend "payment"  # ~10 seconds (cache expired)
+```
+
+---
+
+## 📊 Comparison
+
+| Feature             | Before (Static)    | After (Dynamic)    |
+| ------------------- | ------------------ | ------------------ |
+| **Module Count**    | Fixed subset       | Runtime catalog    |
+| **Updates**         | Manual code change | Automatic          |
+| **Sync**            | Manual             | Automatic          |
+| **Fallback**        | ❌ None            | ✅ Baseline subset |
+| **Cache**           | ❌ None            | ✅ 5-minute TTL    |
+| **Python Required** | ❌ No              | ⚠️ Recommended     |
+| **Performance**     | Fast (hardcoded)   | Fast (cached)      |
+
+---
+
+## 🚀 Next Steps
+
+### Current Stage: ✅ Dynamic Fetching
+
+- ✅ Fetch from Python Core
+- ✅ Cache with TTL
+- ✅ Fallback to hardcoded
+- ✅ Error handling
+
+### Next Stage: Module Installation
+
+```bash
+rapidkit ai recommend "authentication"
+# → Shows recommendations
+# → [Install] button
+# → Calls: rapidkit add module authentication-core
+# → Python Core installs module
+```
+
+### Future Stage: Real-time Sync
+
+```bash
+# Watch Python modules directory
+# Auto-regenerate embeddings when modules change
+# Push updates to users
+```
+
+---
+
+## 🎯 Summary
+
+**What Changed:**
+
+- ✅ AI now reads from Python Core dynamically
+- ✅ Runtime catalog instead of a fixed hardcoded subset
+- ✅ Always up-to-date
+- ✅ Fallback if Python not available
+- ✅ 5-minute cache for performance
+
+**What Stayed Same:**
+
+- ✅ Same API (getModuleCatalog)
+- ✅ Same recommendation algorithm
+- ✅ Same embedding model
+- ✅ Same CLI commands
+- ✅ Backward compatible
+
+**Result:**
+
+- 🎉 Runtime-driven catalog
+- 🎉 Single source of truth
+- 🎉 Production-ready
+- 🎉 Zero breaking changes
+
+---
+
+**Built with ❤️ by the RapidKit Team**
+
+_Dynamic AI that grows with your framework._