workspai 0.43.0

package/dist/workspace-PR6VZRBG.js

@@ -0,0 +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-VRDF2J46.js';

package/dist/workspace-agent-sync-KTYF3HQR.js

@@ -0,0 +1 @@
+export{f as AGENT_CUSTOMIZATION_PACK_REPORT_PATH,d as AGENT_CUSTOMIZATION_PACK_SCHEMA,e as AGENT_REPORTS_INDEX_PATH,c as AGENT_REPORTS_INDEX_SCHEMA,g as AGENT_REPORT_CATALOG,h as buildWorkspaceAgentReportsIndex,i as parseAgentGroundingTargets,j as syncWorkspaceAgentGrounding}from'./chunk-XEJD4KCV.js';export{f as AGENT_GROUNDING_DOC_PATH,g as LEGACY_AGENT_GROUNDING_DOC_PATH,A as LEGACY_COPILOT_GROUNDING_SKILL_PATH,m as LEGACY_COPILOT_WORKSPACE_INSTRUCTIONS_PATH,C as LEGACY_COPILOT_WORKSPACE_INTELLIGENCE_SKILL_PATH,i as LEGACY_CURSOR_GROUNDING_RULE_PATH,E as LEGACY_MCP_DESIGN_REPORT_PATH,G as LEGACY_VSCODE_AGENT_HOOKS_PATH,z as WORKSPAI_COPILOT_GROUNDING_SKILL_PATH,l as WORKSPAI_COPILOT_WORKSPACE_INSTRUCTIONS_PATH,B as WORKSPAI_COPILOT_WORKSPACE_INTELLIGENCE_SKILL_PATH,h as WORKSPAI_CURSOR_GROUNDING_RULE_PATH,D as WORKSPAI_MCP_DESIGN_REPORT_PATH,F as WORKSPAI_VSCODE_AGENT_HOOKS_PATH}from'./chunk-DNAY5ALC.js';

package/dist/workspace-archive-GCZNI44O.js

@@ -0,0 +1,3 @@
+import {f,o,l as l$1,r}from'./chunk-5XATWNME.js';import M from'crypto';import H from'os';import l from'path';import T from'zlib';import u from'fs-extra';var y=".workspai/archive-manifest.json",k=".rapidkit/archive-manifest.json",R="workspai.workspace.archive",Z=new Set(["__pycache__",".venv","venv","node_modules",".git","dist","build","target",".pytest_cache",".mypy_cache",".ruff_cache","htmlcov",".next",".turbo",".cache"]),j=new Set([".DS_Store","Thumbs.db",".coverage","npm-debug.log","yarn-error.log","pnpm-debug.log"]),V=[/^\.env$/i,/^\.env\.(?!example$|sample$|template$).+/i,/^.*\.pem$/i,/^.*\.key$/i,/^id_rsa$/i,/^id_ed25519$/i];function A(e){return e.replace(/\\/g,"/")}function $(e){return e.replace(/\.workspai-archive\.zip$/i,"").replace(/\.rapidkit-archive\.zip$/i,"").replace(/\.zip$/i,"").trim().toLowerCase().replace(/[^a-z0-9._-]+/g,"-").replace(/-+/g,"-").replace(/^[-_.]+|[-_.]+$/g,"").slice(0,64)||"imported-workspace"}function q(e){let r=A(e).trim();if(!r||r.startsWith("/")||r.startsWith("~")||/^[a-zA-Z]:\//.test(r)||r.includes("\0"))return  false;let t=r.split("/").filter(Boolean);return t.length>0&&!t.some(a=>a===".."||a===".")}function S(e){if(!q(e))throw new Error(`Archive contains an unsafe path: ${e}`)}function K(e,r){let t=l.relative(r,e);return t===""||!!t&&!t.startsWith("..")&&!l.isAbsolute(t)}function J(e,r){let a=A(e).split("/").filter(Boolean);if((a[0]===".workspai"||a[0]===".rapidkit")&&["cache","reports"].includes(a[1]||"")||a.some(n=>Z.has(n)))return  true;let i=a[a.length-1]||"";return j.has(i)||!r?.includeEnv&&V.some(n=>n.test(i))?true:i.endsWith(".pyc")||i.endsWith(".log")}function U(e){return M.createHash("sha256").update(e).digest("hex")}var G=new Uint32Array(256).map((e,r)=>{let t=r;for(let a=0;a<8;a+=1)t=t&1?3988292384^t>>>1:t>>>1;return t>>>0});function N(e){let r=4294967295;for(let t of e)r=G[(r^t)&255]^r>>>8;return (r^4294967295)>>>0}function h(e){let r=Buffer.allocUnsafe(2);return r.writeUInt16LE(e,0),r}function p(e){let r=Buffer.allocUnsafe(4);return r.writeUInt32LE(e>>>0,0),r}function X(e){let r=Math.max(e.getFullYear(),1980),t=e.getHours()<<11|e.getMinutes()<<5|Math.floor(e.getSeconds()/2),a=r-1980<<9|e.getMonth()+1<<5|e.getDate();return {time:t,date:a}}async function _(e,r,t,a){let i=await u.readdir(r,{withFileTypes:true});for(let n of i){let s=l.join(r,n.name),o=A(l.relative(e,s));if(!(!o||J(o,a))){if(n.isDirectory()){await _(e,s,t,a);continue}n.isFile()&&t.push({relativePath:o,fullPath:s});}}}async function Y(e){for(let r of o(e,"workspace.json"))try{let t=await u.readJson(r);if(typeof t.workspace_name=="string"&&t.workspace_name.trim())return t.workspace_name.trim();if(typeof t.name=="string"&&t.name.trim())return t.name.trim()}catch{}return l.basename(l.resolve(e))}async function Q(e,r,t){let a=[];await _(e,e,a,t);let i=[];for(let s of a.sort((o,m)=>o.relativePath.localeCompare(m.relativePath))){let o=await u.readFile(s.fullPath);if(o.length>=4294967295)throw new Error(`File is too large for portable workspace archive: ${s.relativePath}`);r.files.push({path:s.relativePath,size:o.length,sha256:U(o)}),i.push({name:s.relativePath,data:o,crc32:N(o),size:o.length,offset:0});}let n=Buffer.from(`${JSON.stringify(r,null,2)}
+`,"utf-8");return i.push({name:y,data:n,crc32:N(n),size:n.length,offset:0}),i}function ee(e,r=new Date){let t=[],a=[],i=0,n=X(r);for(let f of e){let d=Buffer.from(f.name,"utf-8");f.offset=i;let w=Buffer.concat([p(67324752),h(20),h(2048),h(0),h(n.time),h(n.date),p(f.crc32),p(f.size),p(f.size),h(d.length),h(0),d]);t.push(w,f.data),i+=w.length+f.data.length;}let s=i;for(let f of e){let d=Buffer.from(f.name,"utf-8"),w=Buffer.concat([p(33639248),h(20),h(20),h(2048),h(0),h(n.time),h(n.date),p(f.crc32),p(f.size),p(f.size),h(d.length),h(0),h(0),h(0),h(0),p(0),p(f.offset),d]);a.push(w),i+=w.length;}let o=i-s,m=Buffer.concat([p(101010256),h(0),h(0),h(e.length),h(e.length),p(o),p(s),h(0)]);return Buffer.concat([...t,...a,m])}async function ge(e){let r=l.resolve(e.workspacePath);if(!f(r))throw new Error("Workspace export requires a Workspai workspace root with .workspai-workspace or a legacy .rapidkit-workspace marker.");let t=await Y(r),a=l.resolve(e.outputPath||`${$(t)}.workspai-archive.zip`),i={version:1,kind:R,workspaceName:t,exportedAt:(e.now??new Date).toISOString(),exportedBy:"workspai",archiveFormat:"zip-store",security:{envFilesIncluded:e.includeEnv===true,excludedByDefault:[".git","node_modules",".venv","dist","build","target",".env","*.pem","*.key","*.log"]},files:[]},n=await Q(r,i,{includeEnv:e.includeEnv===true}),s=ee(n,e.now??new Date);return await u.ensureDir(l.dirname(a)),await u.writeFile(a,s),{archivePath:a,manifest:i,bytesWritten:s.length}}function te(e){let r=Math.max(0,e.length-65535-22);for(let t=e.length-22;t>=r;t-=1)if(e.readUInt32LE(t)===101010256)return t;throw new Error("Invalid ZIP archive: end of central directory not found.")}function re(e){let r=te(e),t=e.readUInt16LE(r+10),a=e.readUInt32LE(r+16),i=[],n=a;for(let s=0;s<t;s+=1){if(e.readUInt32LE(n)!==33639248)throw new Error("Invalid ZIP archive: central directory is corrupted.");let o=e.readUInt16LE(n+10);if(o!==0&&o!==8)throw new Error("Unsupported ZIP archive: only stored/deflated entries are supported by Workspai.");let m=e.readUInt32LE(n+20),f=e.readUInt32LE(n+24),d=e.readUInt16LE(n+28),w=e.readUInt16LE(n+30),c=e.readUInt16LE(n+32),v=e.readUInt32LE(n+42),g=e.subarray(n+46,n+46+d).toString("utf-8");S(g);let O=g.endsWith("/");if(e.readUInt32LE(v)!==67324752)throw new Error(`Invalid ZIP archive: local header missing for ${g}.`);let F=e.readUInt16LE(v+26),L=e.readUInt16LE(v+28),W=v+30+F+L,E=e.subarray(W,W+m);if(E.length!==m)throw new Error(`Invalid ZIP archive: size mismatch for ${g}.`);if(O){if(m!==0||f!==0)throw new Error(`Invalid ZIP archive: directory entry contains data for ${g}.`);n+=46+d+w+c;continue}let z=o===8?T.inflateRawSync(E):E;if(z.length!==f)throw new Error(`Invalid ZIP archive: inflated size mismatch for ${g}.`);i.push({name:g,data:z,size:f}),n+=46+d+w+c;}return i}async function ae(e){if(/^https?:\/\//i.test(e)){let r=await fetch(e);if(!r.ok)throw new Error(`Failed to download workspace archive: HTTP ${r.status}`);let t=Buffer.from(await r.arrayBuffer()),a=await u.mkdtemp(l.join(H.tmpdir(),"workspai-workspace-archive-")),i=l.join(a,"workspace.workspai-archive.zip");return await u.writeFile(i,t),{archivePath:i,cleanup:a}}return {archivePath:l.resolve(e)}}function ie(e){let r=e.find(a=>a.name===y||a.name===k);if(!r)return null;let t=JSON.parse(r.data.toString("utf-8"));if(t.kind!==R)throw new Error("Archive manifest kind is not a RapidKit/Workspai workspace archive.");return t}function ne(e){return r(A(e))}function se(e){let r=new Map;for(let t of e){if(t.name===y||t.name===k)continue;let a=ne(t.name),i=r.get(a);if(!i){r.set(a,{sourceName:t.name,targetName:a,data:t.data,size:t.size});continue}let n=t.name===a,s=i.sourceName===i.targetName;if(n&&!s){r.set(a,{sourceName:t.name,targetName:a,data:t.data,size:t.size});continue}if(!i.data.equals(t.data)&&!s)throw new Error(`Workspace archive contains conflicting entries for ${a}: ${i.sourceName}, ${t.name}`)}return [...r.values()].sort((t,a)=>t.targetName.localeCompare(a.targetName))}async function P(e){let r=await ae(e);try{let t=await u.readFile(r.archivePath),a=re(t),i=ie(a);if(!i)throw new Error(`Workspace archive is missing ${l$1("","archive-manifest.json").replace(/^\//,"")}.`);return {archivePath:r.archivePath,entries:a,manifest:i,cleanup:r.cleanup}}catch(t){throw r.cleanup&&await u.remove(r.cleanup).catch(()=>{}),t}}async function x(e){e.cleanup&&await u.remove(e.cleanup).catch(()=>{});}async function oe(e){let r=await P(e.archivePathOrUrl);try{let t=new Map(r.entries.filter(i=>i.name!==y&&i.name!==k).map(i=>[i.name,i])),a=r.manifest.files.map(i=>({path:i.path,size:t.get(i.path)?.size??i.size,hasChecksum:typeof i.sha256=="string"&&i.sha256.length>0}));return {archivePath:r.archivePath,manifest:r.manifest,fileCount:a.length,totalBytes:a.reduce((i,n)=>i+n.size,0),entries:a}}finally{await x(r);}}async function D(e){let r=await P(e.archivePathOrUrl);try{let t=new Map(r.entries.filter(c=>c.name!==y&&c.name!==k).map(c=>[c.name,c])),a=new Set(r.manifest.files.map(c=>c.path)),i=[...t.keys()].filter(c=>!a.has(c)).sort(),n=[],s=[],o=[],m=0;for(let c of r.manifest.files){S(c.path);let v=t.get(c.path);if(!v){n.push(c.path);continue}let g={size:v.size,sha256:U(v.data)};if(v.size!==c.size){o.push({path:c.path,expected:{size:c.size,sha256:c.sha256},actual:g});continue}if(!c.sha256){s.push(c.path);continue}if(g.sha256!==c.sha256){o.push({path:c.path,expected:{size:c.size,sha256:c.sha256},actual:g});continue}m+=1;}let f=e.requireChecksums===true&&s.length>0,d=n.length>0||o.length>0||f||i.length>0,w=s.length>0;return {archivePath:r.archivePath,manifest:r.manifest,status:d?"failed":w?"warning":"passed",fileCount:r.manifest.files.length,totalBytes:r.manifest.files.reduce((c,v)=>c+v.size,0),verifiedFiles:m,missingChecksumFiles:s,missingArchiveEntries:n,extraArchiveEntries:i,mismatches:o}}finally{await x(r);}}async function we(e){let r=await oe({archivePathOrUrl:e.archivePathOrUrl}),t=await D({archivePathOrUrl:e.archivePathOrUrl,requireChecksums:e.strict===true}),a=[],i=[];a.push({id:"manifest-present",status:"passed",message:`Archive manifest found for workspace "${r.manifest.workspaceName}".`}),a.push({id:"integrity",status:t.status,message:t.status==="passed"?`Verified ${t.verifiedFiles}/${t.fileCount} files.`:"Archive integrity verification did not fully pass."});let n=r.manifest.security?.envFilesIncluded===true;a.push({id:"secrets-policy",status:n?"warning":"passed",message:n?"Archive manifest says environment/private files were intentionally included.":"Archive manifest excludes environment/private files by default."}),n&&i.push("Share this archive only through trusted internal channels."),t.missingChecksumFiles.length>0&&i.push("Re-export the archive with the latest RapidKit/Workspai tooling."),t.mismatches.length>0&&i.push("Reject this archive and request a fresh export from the owner."),(t.extraArchiveEntries.length>0||t.missingArchiveEntries.length>0)&&i.push("Regenerate the archive so ZIP entries and manifest entries match."),e.strict===true&&t.status!=="passed"&&i.push("Do not hydrate this archive in strict or production workflows.");let s=a.some(m=>m.status==="failed"),o=a.some(m=>m.status==="warning");return {archivePath:r.archivePath,status:s?"failed":o?"warning":"passed",workspaceName:r.manifest.workspaceName,fileCount:r.fileCount,totalBytes:r.totalBytes,checks:a,recommendedActions:i}}async function ce(e,r,t){if(!await u.pathExists(e)){t||await u.ensureDir(e);return}if((await u.readdir(e)).length>0&&!r)throw new Error(`Output directory is not empty: ${e}. Use --force to overwrite.`);t||await u.emptyDir(e);}async function ye(e){let r=await P(e.archivePathOrUrl);try{let t=await D({archivePathOrUrl:r.archivePath,requireChecksums:e.strict===true});if(t.status==="failed"){let s=[t.missingArchiveEntries.length?`missing entries: ${t.missingArchiveEntries.join(", ")}`:"",t.extraArchiveEntries.length?`unexpected entries: ${t.extraArchiveEntries.join(", ")}`:"",t.mismatches.length?`checksum/size mismatches: ${t.mismatches.map(o=>o.path).join(", ")}`:"",t.missingChecksumFiles.length&&e.strict===true?`missing checksums: ${t.missingChecksumFiles.join(", ")}`:""].filter(Boolean).join("; ");throw new Error(`Workspace archive verification failed${s?` (${s})`:""}.`)}if(t.status==="warning"&&e.strict===true)throw new Error(`Workspace archive verification requires checksums for every file: ${t.missingChecksumFiles.join(", ")}`);let a=se(r.entries),i=r.manifest,n=l.resolve(e.outputPath||$(i.workspaceName||"imported-workspace"));await ce(n,e.force===true,e.dryRun===true);for(let s of a){let o=l.resolve(n,s.targetName);if(!K(o,n))throw new Error(`Archive entry escapes output directory: ${s.targetName}`);e.dryRun||(await u.ensureDir(l.dirname(o)),await u.writeFile(o,s.data));}return {archivePath:r.archivePath,outputPath:n,dryRun:e.dryRun===true,manifest:i,files:a.map(s=>({path:s.targetName,size:s.size}))}}finally{await x(r);}}
+export{R as WORKSPACE_ARCHIVE_KIND,y as WORKSPACE_ARCHIVE_MANIFEST_PATH,we as doctorWorkspaceArchive,ge as exportWorkspaceArchive,ye as hydrateWorkspaceArchive,oe as inspectWorkspaceArchive,q as isSafeArchiveEntryName,$ as sanitizeWorkspaceArchiveName,J as shouldExcludeWorkspaceArchivePath,D as verifyWorkspaceArchive};

package/dist/workspace-context-QUTOP2XV.js

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

package/dist/workspace-contract-XUGMCUSQ.js

@@ -0,0 +1 @@
+export{b as WORKSPACE_CONTRACT_PATH,d as WORKSPACE_CONTRACT_SCHEMA_VERSION,c as WORKSPACE_CONTRACT_VERIFY_REPORT_PATH,e as WORKSPACE_CONTRACT_VERIFY_SCHEMA_VERSION,g as buildWorkspaceContract,k as buildWorkspaceContractGraph,f as discoverProjectJsonFiles,j as readWorkspaceContract,i as syncWorkspaceContract,l as verifyWorkspaceContract,h as writeWorkspaceContract,m as writeWorkspaceContractVerifyEvidence}from'./chunk-VZKSNUEE.js';

package/dist/workspace-explain-JEONEGZZ.js

@@ -0,0 +1 @@
+export{b as buildWorkspaceExplain,a as resolveWorkspaceExplainArtifactPath,c as writeWorkspaceExplainReport}from'./chunk-54XJNLYC.js';export{d as WORKSPACE_MODEL_DIFF_REPORT_PATH}from'./chunk-LYC6AIF2.js';export{c as WORKSPACE_EXPLAIN_REPORT_PATH,e as WORKSPACE_TRACE_REPORT_PATH,d as WORKSPACE_WHY_REPORT_PATH}from'./chunk-DNAY5ALC.js';

package/dist/workspace-explain-contract-DNS2YEL7.js

@@ -0,0 +1 @@
+export{a as WORKSPACE_EXPLAIN_SCHEMA_VERSION,b as WORKSPACE_EXPLAIN_TARGETS,e as isWorkspaceExplainReport,c as parseWorkspaceExplainTarget,d as resolveWorkspaceTraceTarget}from'./chunk-AQ4XZZC6.js';export{c as WORKSPACE_EXPLAIN_REPORT_PATH,e as WORKSPACE_TRACE_REPORT_PATH,d as WORKSPACE_WHY_REPORT_PATH}from'./chunk-DNAY5ALC.js';

package/dist/workspace-feedback-R6H4UFZB.js

@@ -0,0 +1 @@
+import {b}from'./chunk-ICGWHIMK.js';import {b as b$1,f,j}from'./chunk-SI3AQKIP.js';import o from'path';async function m(r){let t=o.resolve(r.workspacePath),n=b(r.payload);if(!n)return {ok:false,error:"Invalid agent-action-outcome payload",historyPath:o.join(t,b$1)};let c=f(n),p=o.join(t,b$1);return await j(t,c,{retention:r.retention}),{ok:true,entry:c,historyPath:p}}function l(r){let t=r.trim();if(!t)return null;try{return JSON.parse(t)}catch{return null}}async function h(){let r=[];for await(let t of process.stdin)r.push(typeof t=="string"?Buffer.from(t):t);return Buffer.concat(r).toString("utf8")}export{l as parseFeedbackStdinPayload,h as readStdinAll,m as recordWorkspaceFeedback};

package/dist/workspace-foundation-KGSV4E6D.js

@@ -0,0 +1 @@
+import {b}from'./chunk-LPZFK3Y6.js';import {a}from'./chunk-GSWPGELT.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-RUJE6RPH.js');return await y(t),{workspacePath:t,created:s,status:s.length>0?"passed":"skipped"}}export{W as ensureWorkspaceFoundation};

package/dist/workspace-graph-2A5THUCI.js

@@ -0,0 +1 @@
+export{d as buildGraphEmit,a as explainGraphNode,b as renderGraphDot,c as renderGraphMermaid}from'./chunk-JEI6BTZI.js';

package/dist/workspace-history-CGCK2DJI.js

@@ -0,0 +1 @@
+export{c as DEFAULT_HISTORY_RETENTION,b as WORKSPACE_HISTORY_PATH,a as WORKSPACE_HISTORY_SCHEMA_VERSION,i as appendHistoryEntry,f as historyEntryFromAgentAction,g as historyEntryFromDoctorFixResult,e as historyEntryFromVerify,d as normalizeHistoryEntry,h as readWorkspaceHistory,j as recordWorkspaceHistory}from'./chunk-SI3AQKIP.js';

package/dist/workspace-intelligence-QJGVL37U.js

@@ -0,0 +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-LYC6AIF2.js';

package/dist/workspace-marker-SMBC3Z2Q.js

@@ -0,0 +1 @@
+export{d as createNpmWorkspaceMarker,e as isValidWorkspaceMarker,a as readWorkspaceMarker,c as updateWorkspaceMetadata,b as writeWorkspaceMarker}from'./chunk-GSWPGELT.js';

package/dist/workspace-mcp-serve-AK4MYEHQ.js

@@ -0,0 +1,3 @@
+import {b}from'./chunk-54XJNLYC.js';import {b as b$1}from'./chunk-EWYYLJQY.js';import {d}from'./chunk-CVTCPPEF.js';import {c,e}from'./chunk-AQ4XZZC6.js';import {c as c$2,b as b$2}from'./chunk-DNAY5ALC.js';import {k}from'./chunk-5SWNSJGW.js';import {c as c$3}from'./chunk-VZKSNUEE.js';import {c as c$1}from'./chunk-NAAQMSO3.js';import u from'path';import P from'readline';import v from'fs-extra';var h=".workspai/reports/INDEX.json";function O(t,e){return t.kind!==e.kind?false:t.kind==="project"&&e.kind==="project"?t.project.toLowerCase()===e.project.toLowerCase():t.kind==="blocker"&&e.kind==="blocker"?t.blockerId===e.blockerId:t.kind==="trace"&&e.kind==="trace"?t.diffRef===e.diffRef:true}var C=[{name:"getWorkspaceModel",description:"Read workspace-model.json",inputSchema:{type:"object",properties:{}}},{name:"getEvidenceIndex",description:"Read agent reports INDEX.json",inputSchema:{type:"object",properties:{}}},{name:"getBlockers",description:"Aggregate blocking reasons from verify, explain, and contract-verify reports",inputSchema:{type:"object",properties:{}}},{name:"getSafeCommands",description:"Read safe commands from workspace-context-agent.json",inputSchema:{type:"object",properties:{}}},{name:"getProjectContext",description:"Read scoped project context from workspace-context-agent.json",inputSchema:{type:"object",properties:{project:{type:"string",description:"Optional project name; defaults to active scope"}}}},{name:"getArtifact",description:"Read one workspace-relative artifact path",inputSchema:{type:"object",properties:{relativePath:{type:"string"}},required:["relativePath"]}},{name:"listOperationalSkills",description:"Read workspace-skills-index.json",inputSchema:{type:"object",properties:{}}},{name:"getWorkspaceExplain",description:"Build or read workspace explain report",inputSchema:{type:"object",properties:{target:{type:"string",description:"release-blocked | project:<name> | blocker:<id> | trace:<diffRef> | <project>"}}}}];function _(t){let e=t.trim().replace(/\\/g,"/");return e.length>0&&!u.isAbsolute(e)&&!e.split("/").includes("..")&&(e.startsWith(".workspai/")||e.startsWith(".rapidkit/"))}async function l(t,e){if(!_(e))throw new Error(`Unsafe artifact path: ${e}`);let i=await c$1(t,e)??u.join(t,e);return await v.pathExists(i)?v.readJson(i):null}async function W(t){let e$1=[],i=new Set,s=((await l(t,d))?.blockingReasons??[]).filter(n=>typeof n=="string"&&n.trim().length>0);if(s.length>0){e$1.push({artifact:d,reasons:s});for(let n of s)i.add(n);}let a=await l(t,c$2);if(e(a)){let n=(a.blockingReasons??[]).filter(r=>typeof r=="string"&&r.trim().length>0);if(n.length>0){e$1.push({artifact:c$2,reasons:n});for(let r of n)i.add(r);}}let c=await l(t,c$3),p=(c?.violations??[]).filter(n=>typeof n=="string"&&n.trim().length>0);if(p.length>0||String(c?.status??"").toLowerCase()==="failed"){let n=p.length>0?p:["Workspace contract verification failed"];e$1.push({artifact:c$3,reasons:n});for(let r of n)i.add(r);}return {blockingReasons:[...i],sources:e$1}}async function A(t,e$1,i){switch(e$1){case "getWorkspaceModel":return l(t,k);case "getEvidenceIndex":return l(t,h);case "getBlockers":return W(t);case "getSafeCommands":return {safeCommands:(await l(t,b$1))?.safeCommands??[]};case "getProjectContext":{let o=await l(t,b$1);if(!o)return null;let s=String(i.project??"").trim(),a=o.scope?.activeProject??void 0,c=s||a,p=Array.isArray(o.projects)?o.projects:[],n=c&&p.find(r=>typeof r.name=="string"&&r.name.toLowerCase()===c.toLowerCase());return {workspace:o.workspace??null,scope:o.scope??null,validation:o.validation??null,project:n??null,safeCommands:o.safeCommands??[]}}case "getArtifact":{let o=String(i.relativePath??"").trim();return l(t,o)}case "listOperationalSkills":return l(t,b$2);case "getWorkspaceExplain":{let o=String(i.target??"release-blocked").trim(),s=c(o);if(!s)throw new Error(`Invalid explain target: ${o}`);let a=await l(t,c$2);return e(a)&&O(a.target,s)?a:b({workspacePath:t,target:s})}default:throw new Error(`Unknown tool: ${e$1}`)}}function R(t,e){process.stdout.write(`${JSON.stringify({jsonrpc:"2.0",id:t??null,result:e})}
+`);}function w(t,e){process.stdout.write(`${JSON.stringify({jsonrpc:"2.0",id:t??null,error:{code:-32e3,message:e}})}
+`);}async function z(t){let e=u.resolve(t.workspacePath),i=P.createInterface({input:process.stdin,terminal:false});for await(let o of i){let s=o.trim();if(!s)continue;let a;try{a=JSON.parse(s);}catch{w(null,"Invalid JSON-RPC request");continue}let{id:c,method:p,params:n}=a;try{if(p==="initialize"){R(c,{protocolVersion:"2024-11-05",capabilities:{tools:{}},serverInfo:{name:"workspai-workspace-mcp",version:"0.1.0"}});continue}if(p==="notifications/initialized")continue;if(p==="tools/list"){R(c,{tools:C.map(r=>({name:r.name,description:r.description,inputSchema:r.inputSchema}))});continue}if(p==="tools/call"){let r=String(n?.name??""),T=n?.arguments&&typeof n.arguments=="object"?n.arguments:{},E=await A(e,r,T);R(c,{content:[{type:"text",text:JSON.stringify(E,null,2)}],isError:E==null});continue}w(c,`Unsupported method: ${p??"unknown"}`);}catch(r){w(c,r instanceof Error?r.message:String(r));}}}async function U(t,e,i={}){return A(u.resolve(t),e,i)}export{C as WORKSPACE_MCP_READ_TOOLS,U as invokeMcpToolForTest,z as runWorkspaceMcpServe};

package/dist/workspace-model-PNXXOGPO.js

@@ -0,0 +1 @@
+export{k as WORKSPACE_MODEL_REPORT_PATH,j as WORKSPACE_MODEL_SCHEMA_VERSION,n as buildWorkspaceModel,o as buildWorkspaceModelCached,m as buildWorkspaceModelFacts,p as buildWorkspaceModelIncremental,l as validateWorkspaceModelStrict,q as writeWorkspaceModel}from'./chunk-5SWNSJGW.js';

package/dist/workspace-python-engine-state-MTWIIZPY.js

@@ -0,0 +1,2 @@
+import {a,b}from'./chunk-GSWPGELT.js';import {o}from'./chunk-5XATWNME.js';import l from'fs-extra';function c(n){return n&&typeof n=="object"&&!Array.isArray(n)?n:{}}async function m(n,e){if(!await l.pathExists(n))return  false;let o=c(await l.readJson(n));return await l.outputJson(n,e(o),{spaces:2}),await l.appendFile(n,`
+`,"utf-8"),true}async function f(n,e){let o$1=e.now??new Date().toISOString(),d=e.installMethod==="pip"?"venv":e.installMethod;for(let r of o(n,"workspace.json"))await m(r,a=>{let s=c(a.engine),i=c(s.python_core);return delete a.bootstrap_note,delete i.reason,{...a,engine:{...s,install_method:d,python_version:e.pythonVersion??s.python_version??null,python_core:{...i,status:"installed",installed_at:o$1,...e.coreVersion?{version:e.coreVersion}:{}}}}});for(let r of o(n,"toolchain.lock"))await m(r,a=>{let s=c(a.runtime),i=c(s.python),h=c(i.core);return delete h.reason,{...a,generated_at:o$1,runtime:{...s,python:{...i,version:e.pythonVersion??i.version??null,install_method:d,core:{...h,status:"installed",installed_at:o$1,...e.coreVersion?{version:e.coreVersion}:{}}}}}});let t=await a(n);if(t){let r={...t.metadata?.python??{}};delete r.coreReason,t.metadata={...t.metadata,python:{...r,coreStatus:"installed",...e.coreVersion?{coreVersion:e.coreVersion}:{},...e.pythonVersion?{pythonVersion:e.pythonVersion}:{},...e.venvPath?{venvPath:e.venvPath}:{}},npm:{...t.metadata?.npm??{},packageVersion:t.metadata?.npm?.packageVersion??t.version,installMethod:d,lastUsedAt:o$1}},await b(n,t);}}export{f as markWorkspacePythonEngineInstalled};

package/dist/workspace-registry-summary-RUJE6RPH.js

@@ -0,0 +1 @@
+import {a}from'./chunk-A5FBGRJA.js';import {b,j}from'./chunk-VZKSNUEE.js';import {c,d as d$1}from'./chunk-NAAQMSO3.js';import {p,r}from'./chunk-LZQNVH7D.js';import {o}from'./chunk-5XATWNME.js';import n from'path';import c$1 from'fs-extra';var k=".workspai/workspace-registry.v1.json",w="workspace-registry.v1";function d(r){return {slug:r.slug,relativePath:r.relativePath,framework:r.framework,kit:r.kit,source:r.source}}async function C(r){let t=o(r,"workspace.json").find(e=>c$1.pathExistsSync(e));if(!t)return {exists:false,legacyProjectCount:0};try{let e=await c$1.readJson(t),o=Array.isArray(e.projects)?e.projects.length:0,s=typeof e.workspace_name=="string"&&e.workspace_name.trim()||typeof e.name=="string"&&e.name.trim()||n.basename(r);return {exists:true,manifestPath:t,workspaceName:s,profile:typeof e.profile=="string"?e.profile:void 0,legacyProjectCount:o}}catch{return {exists:true,manifestPath:t,legacyProjectCount:0,workspaceName:n.basename(r)}}}async function A(r$1){let t=a(r$1);for(let e of r())if(await c$1.pathExists(e))try{let s=((await c$1.readJson(e)).workspaces||[]).find(a$1=>a(a$1.path)===t);if(s)return Array.isArray(s.projects)?s.projects.length:0}catch{continue}return 0}async function x(r){let t=n.resolve(r),e=await c(t,b),o=await C(t),s=await A(t),a=!!e,i=[];if(a)try{let{contract:S}=await j({workspacePath:t});i=S.projects||[];}catch{i=[];}let W={contract:{exists:a,projectCount:i.length,path:b},globalRegistry:{exists:s>0,projectCount:s,path:n.join(p(),"workspaces.json")},legacyWorkspaceJson:{exists:o.exists,projectCount:o.legacyProjectCount,path:o.manifestPath?n.relative(t,o.manifestPath):void 0}},p$1="none",m=[],g=0;return a?(p$1="workspace.contract.json",m=i.map(d),g=m.length):s>0?(p$1="global-registry",g=s):o.legacyProjectCount>0&&(p$1="legacy-workspace.json",g=o.legacyProjectCount),{contractExists:a,summary:{schemaVersion:w,kind:"rapidkit.workspace.registry",workspacePath:t,workspaceName:o.workspaceName||n.basename(t),profile:o.profile,projectCount:g,authority:p$1,contractPath:b,projects:m,sources:W}}}async function $(r){let t=await c(r,k);if(!t)return null;try{let e=await c$1.readJson(t);return e?.schemaVersion!==w?null:e}catch{return null}}async function G(r,t){let o={...(await x(r)).summary,generatedAt:(t?.now??new Date).toISOString(),registrySummaryPath:k};return await d$1(r,k,o),o}function J(r,t=""){return r.projectCount>0?r.authority==="workspace.contract.json"?`${r.projectCount} project(s) registered in workspace contract${t}.`:r.authority==="global-registry"?`${r.projectCount} project(s) registered in global workspace registry${t}.`:`${r.projectCount} project(s) registered in legacy workspace manifest${t}.`:`Workspace state exists, but no projects are registered yet${t}.`}export{k as WORKSPACE_REGISTRY_SUMMARY_RELATIVE_PATH,w as WORKSPACE_REGISTRY_SUMMARY_SCHEMA_VERSION,J as formatWorkspaceRegistrySyncSummary,G as publishWorkspaceRegistrySummary,$ as readWorkspaceRegistrySummary,x as resolveWorkspaceRegisteredProjects};

package/dist/workspace-run-Y7YMUIHX.js

@@ -0,0 +1 @@
+export{a as runWorkspaceStage}from'./chunk-WU4ZRRA5.js';export{a as WORKSPACE_RUN_LAST_REPORT_FILENAME}from'./chunk-753LOKFZ.js';

package/dist/workspace-verify-WSDUUTR5.js

@@ -0,0 +1 @@
+export{d as WORKSPACE_VERIFY_REPORT_PATH,c as WORKSPACE_VERIFY_SCHEMA_VERSION,f as buildWorkspaceVerify,e as computeAffectedSubgraphGate,h as evaluateWorkspaceVerifyGate,i as workspaceVerifyExitCode,g as writeWorkspaceVerify}from'./chunk-CVTCPPEF.js';

package/dist/workspace-watch-AGPOJ74Q.js

@@ -0,0 +1 @@
+import {a}from'./chunk-3KXW53QI.js';import {b as b$1,p}from'./chunk-5SWNSJGW.js';import w from'fs';var M="workspace-watch-event.v1";function g(t){return `${t.from}\0${t.to}\0${t.kind}`}function f(t){return (t.graph?.edges??[]).map(r=>({from:r.from,to:r.to,kind:r.kind}))}function m(t){let o=[...a(t).entries()].sort((a,n)=>a[0].localeCompare(n[0])).map(([a,n])=>({id:a,hash:n})),c=f(t).map(g).sort((a,n)=>a.localeCompare(n));return b$1({projects:o,edges:c})}function b(t,r){let o=a(r),c=t?a(t):new Map,a$1=[],n=[];for(let[e,s]of o.entries())c.has(e)?c.get(e)!==s&&a$1.push(e):n.push(e);let d=[];for(let e of c.keys())o.has(e)||d.push(e);let i=new Map(t?f(t).map(e=>[g(e),e]):[]),l=new Map(f(r).map(e=>[g(e),e])),p=[];for(let[e,s]of l.entries())i.has(e)||p.push(s);let h=[];for(let[e,s]of i.entries())l.has(e)||h.push(s);let u=(e,s)=>g(e).localeCompare(g(s));return a$1.sort((e,s)=>e.localeCompare(s)),n.sort((e,s)=>e.localeCompare(s)),d.sort((e,s)=>e.localeCompare(s)),p.sort(u),h.sort(u),{changedProjects:a$1,addedProjects:n,removedProjects:d,edgesAdded:p,edgesRemoved:h}}var k=class{model=null;sequence=0;rebuild;now;constructor(r,o){this.rebuild=o?.rebuild??(()=>p({...r})),this.now=o?.now??(()=>new Date);}get currentModel(){return this.model}async start(){let r=Date.now(),{model:o}=await this.rebuild();return this.model=o,this.buildEvent("ready","initial",null,o,Date.now()-r)}async pulse(){let r=Date.now(),o=this.model,{model:c,mode:a}=await this.rebuild(),n=this.buildEvent(this.hasStructuralChange(o,c)?"changed":"unchanged",a,o,c,Date.now()-r);return this.model=c,n}hasStructuralChange(r,o){return r?m(r)!==m(o):true}buildEvent(r,o,c,a,n){let d=b(c,a),i=m(a),l=c?m(c)!==i:true;return {schemaVersion:M,kind:r,sequence:this.sequence++,timestamp:this.now().toISOString(),mode:o,modelHash:i,modelHashChanged:l,changedProjects:d.changedProjects,addedProjects:d.addedProjects,removedProjects:d.removedProjects,graph:{nodeCount:a.graph?.nodes.length??0,edgeCount:a.graph?.edges.length??0,edgesAdded:d.edgesAdded,edgesRemoved:d.edgesRemoved},durationMs:n}}},P=new Set([".git",".hg",".svn","node_modules",".venv","venv","dist","build","out","target","coverage","htmlcov",".next",".turbo",".cache"]),R=new Set(["reports","cache","tmp",".cache"]);function y(t){if(!t)return  false;let r=t.split(/[\\/]/).filter(Boolean);if(r.some(o=>P.has(o)))return  false;for(let o=0;o<r.length-1;o+=1)if((r[o]===".workspai"||r[o]===".rapidkit")&&R.has(r[o+1]))return  false;return  true}async function G(t){let r=new k(t.buildOptions,t.engineOptions),o=await r.start();if(t.emit(o),t.once)return;let c=t.debounceMs??250,a=t.selfWriteSuppressionMs??Math.max(400,c+150),n=null,d=false,i=false,l=0,p=async()=>{if(d){i=true;return}d=true;try{let e=await r.pulse();t.emit(e);}catch(e){t.emit({schemaVersion:M,kind:"error",sequence:-1,timestamp:new Date().toISOString(),mode:"full",modelHash:r.currentModel?m(r.currentModel):"",modelHashChanged:false,changedProjects:[],addedProjects:[],removedProjects:[],graph:{nodeCount:0,edgeCount:0,edgesAdded:[],edgesRemoved:[]},durationMs:0,error:e instanceof Error?e.message:String(e)});}finally{d=false,l=Date.now()+a,i&&(i=false,p());}},h=e=>{y(e)&&(d||Date.now()<l||(n&&clearTimeout(n),n=setTimeout(()=>{n=null,p();},c)));};t.onProgress?.(`Watching ${t.workspacePath} for changes (Ctrl+C to stop).`);let u=w.watch(t.workspacePath,{recursive:true},(e,s)=>{typeof s=="string"?h(s):s&&h(Buffer.from(s).toString("utf8"));});await new Promise(e=>{let s=()=>{n&&clearTimeout(n),u.close(),e();};if(t.signal){if(t.signal.aborted){s();return}t.signal.addEventListener("abort",s,{once:true});}u.on("error",()=>s());});}export{M as WORKSPACE_WATCH_EVENT_SCHEMA_VERSION,k as WorkspaceWatchEngine,m as computeWatchModelHash,b as diffWatchModels,y as isWatchRelevantPath,G as runWorkspaceWatch};

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
+$ workspai 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
+$ workspai 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
+$ workspai ai recommend "blockchain integration"
+
+# Output:
+⚠️  No matching modules found in RapidKit Core 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/workspai/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
+workspai 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
+workspai ai recommend "authentication"
+
+# Should show: ⚠️ Using fallback catalog (baseline subset)
+```
+
+### Test 3: Cache Behavior
+
+```bash
+# First call (cold cache)
+time workspai ai recommend "auth"  # ~10 seconds
+
+# Second call (warm cache)
+time workspai ai recommend "database"  # <1 second
+
+# Wait 6 minutes, try again
+sleep 360
+time workspai 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
+workspai 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 by the Workspai Team**
+
+_Dynamic AI that grows with your framework._