@tyvm/knowhow 0.0.108-dev.ed88cf4 → 0.0.109-dev.05fe5a0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.108-dev.ed88cf4",
+  "version": "0.0.109-dev.05fe5a0",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/scripts/build-for-node.sh

@@ -7,11 +7,10 @@
 # This script:
 #   1. Compiles TypeScript with Node 20 (required for workspace deps)
 #   2. Creates /tmp/knowhow-node-<major> with the compiled output
-#   3. Installs the correct isolated-vm version for the target node in that dir
-#   4. Symlinks the package globally for ALL installed nvm versions matching the target
+#   3. Symlinks the package globally for ALL installed nvm versions matching the target
 #
-# This approach avoids polluting the workspace node_modules with a different
-# isolated-vm ABI, so Node 20 and Node 24 builds can coexist.
+# Note: isolated-vm is now in @tyvm/knowhow-module-script — install that separately
+# for the correct node version if you need script execution support.
 
 set -e
 
@@ -81,23 +80,11 @@ fi
 
 # Use the last (latest patch) for building
 TARGET_NODE_BIN="${TARGET_NODE_BINS[${#TARGET_NODE_BINS[@]}-1]}"
-TARGET_NODE_NPM="$(dirname "$TARGET_NODE_BIN")/npm"
-TARGET_NODE_DIR="$(dirname "$TARGET_NODE_BIN")"
 TARGET_NODE_ACTUAL_VERSION="$("$TARGET_NODE_BIN" --version)"
 
 echo "🎯 Found Node $TARGET_VERSION installs: ${TARGET_NODE_BINS[*]}"
 echo "🔨 Building with: $TARGET_NODE_BIN ($TARGET_NODE_ACTUAL_VERSION)"
 
-# --- Pick the right isolated-vm version for the target node ---
-# isolated-vm@5.x supports Node <22, isolated-vm@6.x requires Node >=22
-if [ "$TARGET_MAJOR" -ge 22 ]; then
-  IVM_VERSION="^6.0.0"
-  echo "📌 Using isolated-vm@6.x (Node >= 22)"
-else
-  IVM_VERSION="^5.0.4"
-  echo "📌 Using isolated-vm@5.x (Node < 22)"
-fi
-
 # --- Create staging directory ---
 STAGING_DIR="/tmp/knowhow-node-${TARGET_MAJOR}"
 rm -rf "$STAGING_DIR"
@@ -114,13 +101,11 @@ for item in README.md LICENSE .npmignore; do
   [ -e "$PACKAGE_DIR/$item" ] && cp "$PACKAGE_DIR/$item" "$STAGING_DIR/" || true
 done
 
-# --- Patch package.json for target isolated-vm version ---
-echo "📝 Patching package.json for isolated-vm $IVM_VERSION..."
+# --- Patch package.json to remove workspace protocol deps ---
+echo "📝 Patching package.json..."
 "$NODE20_BIN" -e "
   const fs = require('fs');
   const pkg = JSON.parse(fs.readFileSync('$STAGING_DIR/package.json', 'utf8'));
-  pkg.dependencies['isolated-vm'] = '$IVM_VERSION';
-  // Remove workspace protocol deps that won't resolve outside the monorepo
   if (pkg.dependencies) {
     for (const [k, v] of Object.entries(pkg.dependencies)) {
       if (String(v).startsWith('workspace:')) delete pkg.dependencies[k];
@@ -130,13 +115,14 @@ echo "📝 Patching package.json for isolated-vm $IVM_VERSION..."
   console.log('✅ package.json patched');
 "
 
-# --- Install deps in staging dir using target node ---
+# --- Install dependencies in staging dir with target Node ---
+TARGET_NODE_NPM="$(dirname "$TARGET_NODE_BIN")/npm"
 echo ""
 echo "📦 Installing dependencies in staging dir with Node $TARGET_MAJOR..."
 cd "$STAGING_DIR"
-# Prepend target node bin to PATH so npm/node-gyp uses the correct node version
-PATH="$TARGET_NODE_DIR:$PATH" "$TARGET_NODE_NPM" install --no-save 2>&1
-echo "✅ Dependencies installed (isolated-vm compiled for Node $TARGET_MAJOR)"
+"$TARGET_NODE_NPM" install --omit=dev
+echo "✅ Dependencies installed"
+cd "$PACKAGE_DIR"
 
 # --- Symlink globally for ALL matching Node version installs ---
 PKG_NAME="$("$NODE20_BIN" -e "console.log(require('$STAGING_DIR/package.json').name)")"

package/src/chat/modules/AgentModule.ts

@@ -517,7 +517,12 @@ export class AgentModule extends BaseChatModule {
 
       // Restore the full message history from the last thread
       const threads = session.threads || [];
-      const lastThread = threads.length > 0 ? threads[threads.length - 1] : [];
+      // Guard against sessions saved with a flat Message[] instead of Message[][]
+      // (a bug where threadUpdate emitted a single thread instead of all threads)
+      const normalizedThreads: Message[][] = threads.length > 0 && !Array.isArray(threads[0])
+        ? [threads as unknown as Message[]]
+        : threads as Message[][];
+      const lastThread = normalizedThreads.length > 0 ? normalizedThreads[normalizedThreads.length - 1] : [];
       const resumeMessages = [...lastThread];
 
       // Append the resume prompt to the last user message (or add a new one)
@@ -701,7 +706,7 @@ export class AgentModule extends BaseChatModule {
 
       // Set up session update listener
       const threadUpdateHandler = async (threadState: any) => {
-        this.updateSession(taskId, threadState);
+        this.updateSession(taskId, agent.getThreads());
         taskInfo.totalCost = agent.getTotalCostUsd();
       };
       agent.agentEvents.on(agent.eventTypes.threadUpdate, threadUpdateHandler);

package/src/chat/modules/SessionsModule.ts

@@ -362,8 +362,47 @@ export class SessionsModule extends BaseChatModule {
     // Check filesystem agent (may have metadata with threads)
     const fsAgentPath = path.join(".knowhow", "processes", "agents", id);
     if (fs.existsSync(fsAgentPath)) {
+      // Try to load threads from metadata.json and resume
+      const metadataPath = path.join(fsAgentPath, "metadata.json");
+      if (fs.existsSync(metadataPath)) {
+        try {
+          const raw = fs.readFileSync(metadataPath, "utf-8");
+          const metadata = JSON.parse(raw);
+          const threads: any[] = metadata.threads || [];
+          const agentName = metadata.agentName || "Developer";
+
+          // Try to get initialInput from the saved session file (more complete)
+          // since metadata.json doesn't always store it
+          const savedSession = sessionManager.loadSession(id);
+          const initialInput = savedSession?.initialInput || metadata.initialInput || metadata.prompt || "";
+
+          console.log(`\n📋 Found task in filesystem: ${id}`);
+          console.log(`   Agent  : ${agentName}`);
+          console.log(`   Task   : ${initialInput}`);
+          console.log(`   Status : ${metadata.status || "unknown"}`);
+
+          const additionalContext = await this.chatService?.getInput(
+            "Add any additional context for resuming this session (or press Enter to skip): "
+          );
+
+          // Normalize threads: if flat Message[] (old buggy format), wrap in array
+          const normalizedThreads = threads.length > 0 && !Array.isArray(threads[0])
+            ? [threads]
+            : threads;
+
+          await this.agentModule.resumeFromMessages({
+            agentName,
+            taskId: id,
+            threads: normalizedThreads,
+            input: additionalContext?.trim() || initialInput || "",
+          });
+          return;
+        } catch (e: any) {
+          console.error(`⚠️  Failed to load metadata for task ${id}: ${e.message}`);
+        }
+      }
       console.log(
-        `⚠️  Task ${id} exists in the filesystem but has no saved session.\n` +
+        `⚠️  Task ${id} exists in the filesystem but has no saved session or metadata.\n` +
           `   Use /attach ${id} if it is still running.`
       );
       return;

package/src/cloudWorker.ts

@@ -5,7 +5,7 @@ import { loadJwt } from "./login";
 import { getConfig, updateConfig, getLanguageConfig } from "./config";
 import { services } from "./services";
 import { Language, Config, McpConfig } from "./types";
-import { S3Service } from "./services/S3";
+import { uploadFile, uploadDirectory } from "./fileSync";
 
 export interface CloudWorkerPullOptions {
   id: string;
@@ -15,6 +15,7 @@ export interface CloudWorkerPullOptions {
 export interface CloudWorkerOptions {
   create?: boolean;
   push?: string; // uid of existing cloud worker
+  init?: boolean; // initialize config.files entries (mutates config)
   name?: string; // optional name for create
   apiUrl?: string;
   dryRun?: boolean;
@@ -30,25 +31,6 @@ interface FileToSync {
   isDirectory?: boolean; // true if this represents a whole directory
 }
 
-/**
- * Recursively list all files in a local directory, returning relative paths
- */
-function listFilesRecursively(dir: string): string[] {
-  const results: string[] = [];
-  if (!fs.existsSync(dir)) return results;
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      listFilesRecursively(path.join(dir, entry.name)).forEach((f) =>
-        results.push(entry.name + "/" + f)
-      );
-    } else {
-      results.push(entry.name);
-    }
-  }
-  return results;
-}
-
 /**
  * Build the worker config JSON from the local knowhow config
  */
@@ -71,21 +53,19 @@ function buildWorkerConfigJson(config: Config, files: { remotePath: string; loca
 }
 
 /**
- * Collect all files from the .knowhow directory that should be synced
- * Uses directory-level entries where possible so the worker config stays compact
- * and the folder upload/download feature handles individual files automatically.
+ * Collect all files from the .knowhow directory that should be synced.
+ * Only includes files/directories that currently exist locally.
+ * Used by --init to populate config.files.
  */
 async function collectFilesToSync(projectName: string): Promise<FileToSync[]> {
   const filesToSync: FileToSync[] = [];
 
-  // Helper to add file if it exists
   const addIfExists = (localPath: string, remotePath: string) => {
     if (fs.existsSync(localPath)) {
       filesToSync.push({ localPath, remotePath });
     }
   };
 
-  // Helper to add a directory entry if it exists (trailing slash = directory mode)
   const addDirIfExists = (localPath: string, remotePath: string) => {
     if (fs.existsSync(localPath)) {
       filesToSync.push({ localPath: localPath + "/", remotePath: remotePath + "/", isDirectory: true });
@@ -108,7 +88,9 @@ async function collectFilesToSync(projectName: string): Promise<FileToSync[]> {
 }
 
 /**
- * Collect files referenced in language.json sources
+ * Collect files referenced in language.json sources.
+ * These are always re-collected on both --init and --push so that new
+ * language term sources are picked up automatically.
  */
 async function collectLanguageReferencedFiles(
   language: Language,
@@ -124,17 +106,14 @@ async function collectLanguageReferencedFiles(
       if (source.kind !== "file" || !source.data) continue;
 
       for (const filePath of source.data) {
-        // Normalize the path (strip leading ./)
         const normalizedPath = filePath.replace(/^\.\//, "");
 
         // Skip the main knowhow config — it should not be synced to the language folder
-        // as it would overwrite the worker's own config
         if (normalizedPath === ".knowhow/knowhow.json") continue;
 
         if (fs.existsSync(normalizedPath)) {
           const basename = path.basename(normalizedPath);
           const remotePath = `${projectName}/.knowhow/language/${basename}`;
-          // localPath is the original path so the worker downloads it to the right place
           filesToSync.push({ localPath: normalizedPath, remotePath, downloadLocalPath: normalizedPath });
         }
       }
@@ -145,37 +124,83 @@ async function collectLanguageReferencedFiles(
 }
 
 /**
- * Upload a single file to the cloud worker's file storage
+ * Collect language-referenced files if language.json is present in the
+ * given config.files entries. Returns empty array if language.json is not
+ * configured for sync.
+ */
+async function collectLanguageFilesIfConfigured(
+  configFiles: { remotePath: string; localPath: string }[],
+  projectName: string
+): Promise<FileToSync[]> {
+  const syncingLanguage = configFiles.some(
+    (f) => !f.remotePath.endsWith("/") && f.remotePath.endsWith("language.json")
+  );
+  if (!syncingLanguage) return [];
+
+  const language = await getLanguageConfig();
+  return collectLanguageReferencedFiles(language, projectName);
+}
+
+/**
+ * Initialize the local config.files entries based on what exists in .knowhow/.
+ * This is the --init step — mutates config. Run once to set up sync entries.
+ * language-referenced files are also collected if language.json is present.
  */
-async function uploadSingleFile(
-  client: KnowhowSimpleClient,
-  s3Service: S3Service,
-  localPath: string,
-  remotePath: string,
-  dryRun: boolean
-): Promise<void> {
-  console.log(`  ⬆️  Uploading ${localPath} → ${remotePath}`);
-
-  if (dryRun) {
-    console.log(`     [DRY RUN] Would upload from ${localPath}`);
-    return;
+export async function initCloudWorker(options: { apiUrl?: string; dryRun?: boolean } = {}) {
+  const { dryRun = false } = options;
+
+  const config = await getConfig();
+  if (!config || Object.keys(config).length === 0) {
+    console.error("❌ No knowhow config found. Please run 'knowhow init' first.");
+    process.exit(1);
   }
 
-  if (!fs.existsSync(localPath)) {
-    console.warn(`     ⚠️  Local file not found, skipping: ${localPath}`);
-    return;
+  const projectName = path.basename(process.cwd());
+  console.log(`📁 Project name: ${projectName}`);
+
+  console.log("\n📂 Collecting files to sync...");
+  const mainFiles = await collectFilesToSync(projectName);
+  const languageFiles = await collectLanguageFilesIfConfigured(mainFiles, projectName);
+
+  if (languageFiles.length === 0 && !mainFiles.some((f) => f.remotePath.endsWith("language.json"))) {
+    console.log("   ℹ️  Skipping language-referenced files (language.json not found locally)");
   }
 
-  const presignedUrl = await client.getOrgFilePresignedUploadUrl(remotePath);
-  await s3Service.uploadToPresignedUrl(presignedUrl, localPath);
-  await client.markOrgFileUploadComplete(remotePath);
+  // Deduplicate by remotePath
+  const allFilesMap = new Map<string, FileToSync>();
+  for (const f of [...mainFiles, ...languageFiles]) {
+    allFilesMap.set(f.remotePath, f);
+  }
+  const allFiles = Array.from(allFilesMap.values());
+
+  console.log(`   Found ${allFiles.length} files to register`);
 
-  const stats = fs.statSync(localPath);
-  console.log(`     ✓ Uploaded ${stats.size} bytes`);
+  const configFilesEntries = allFiles.map((f) => ({
+    remotePath: f.remotePath,
+    localPath: f.downloadLocalPath ?? f.localPath,
+    direction: "download" as const,
+  }));
+
+  console.log("\n💾 Updating config.files with sync entries...");
+  if (!dryRun) {
+    const existingFiles = config.files || [];
+    const newRemotePaths = new Set(configFilesEntries.map((e) => e.remotePath));
+    const preserved = existingFiles.filter((e) => !newRemotePaths.has(e.remotePath));
+    config.files = [...preserved, ...configFilesEntries];
+    await updateConfig(config);
+    console.log(`   ✓ Updated config with ${config.files.length} file entries`);
+  } else {
+    console.log(`   [DRY RUN] Would update config with ${configFilesEntries.length} file entries`);
+    for (const f of allFiles) {
+      console.log(`   ${f.localPath} → ${f.remotePath}`);
+    }
+  }
 }
 
 /**
- * Main cloudWorker command handler
+ * Main cloudWorker command handler — push/create only.
+ * Reads config.files (set up by --init) and also re-collects any language-referenced
+ * files so new language term sources are always included without requiring --init again.
  */
 export async function cloudWorker(options: CloudWorkerOptions) {
   const {
@@ -205,10 +230,6 @@ export async function cloudWorker(options: CloudWorkerOptions) {
     process.exit(1);
   }
 
-  // Load language config
-  const language = await getLanguageConfig();
-
-  // Get project name from current directory
   const projectName = path.basename(process.cwd());
   console.log(`📁 Project name: ${projectName}`);
 
@@ -218,86 +239,63 @@ export async function cloudWorker(options: CloudWorkerOptions) {
   // Get S3 service
   const { AwsS3 } = services();
 
-  // Step 1: Collect all files to sync
-  console.log("\n📂 Collecting files to sync...");
-  const mainFiles = await collectFilesToSync(projectName);
-  const languageFiles = await collectLanguageReferencedFiles(language, projectName);
-
-  // Deduplicate by remotePath
-  const allFilesMap = new Map<string, FileToSync>();
-  for (const f of [...mainFiles, ...languageFiles]) {
-    allFilesMap.set(f.remotePath, f);
+  // Start with config.files (set up via --init)
+  const configFiles = config.files || [];
+  if (configFiles.length === 0) {
+    console.warn("⚠️  No files configured. Run 'knowhow cloudworker --init' first to set up file sync entries.");
   }
-  const allFiles = Array.from(allFilesMap.values());
-
-  console.log(`   Found ${allFiles.length} files to sync`);
 
-  if (dryRun) {
-    console.log("\n📋 Files that would be synced:");
-    for (const f of allFiles) {
-      console.log(`   ${f.localPath} → ${f.remotePath}`);
-    }
+  // Re-collect language-referenced files on every push (if language.json is in config.files)
+  // so that new language term sources are picked up without needing --init again.
+  const languageFiles = await collectLanguageFilesIfConfigured(configFiles, projectName);
+  if (languageFiles.length > 0) {
+    console.log(`   + ${languageFiles.length} language-referenced file(s) to sync`);
   }
 
-  // Step 2: Build the config.files array for all synced files
-  const configFilesEntries = allFiles.map((f) => ({
-    remotePath: f.remotePath,
-    localPath: f.downloadLocalPath ?? f.localPath,
-    direction: "download" as const,
-  }));
-
-  // Step 3: Update config.files and save
-  console.log("\n💾 Updating config.files with sync entries...");
-  if (!dryRun) {
-    // Preserve any existing files entries not in our set
-    const existingFiles = config.files || [];
-    const newRemotePaths = new Set(configFilesEntries.map((e) => e.remotePath));
-
-    // Keep entries that don't overlap with new ones
-    const preserved = existingFiles.filter(
-      (e) => !newRemotePaths.has(e.remotePath)
-    );
+  // Merge language files into the upload list (deduplicate by remotePath)
+  const allFilesMap = new Map<string, { remotePath: string; localPath: string }>();
+  for (const f of configFiles) {
+    allFilesMap.set(f.remotePath, f);
+  }
+  for (const f of languageFiles) {
+    const entry = { remotePath: f.remotePath, localPath: f.downloadLocalPath ?? f.localPath };
+    allFilesMap.set(f.remotePath, entry);
+  }
+  const allFiles = Array.from(allFilesMap.values());
 
-    config.files = [...preserved, ...configFilesEntries];
+  // If new language files were found, update config.files so they persist
+  if (languageFiles.length > 0 && !dryRun) {
+    config.files = allFiles.map((f) => ({ ...f, direction: "download" as const }));
     await updateConfig(config);
-    console.log(`   ✓ Updated config with ${config.files.length} file entries`);
-  } else {
-    console.log(`   [DRY RUN] Would update config with ${configFilesEntries.length} file entries`);
   }
 
-  // Step 4: Build workerConfigJson
-  const workerConfigJson = buildWorkerConfigJson(config, configFilesEntries);
+  // Build the workerConfigJson using the full file list
+  const workerConfigJson = buildWorkerConfigJson(config, allFiles.map((f) => ({ ...f, direction: "download" })));
 
-  // Step 5: Upload all files
-  console.log(`\n🚀 Uploading ${allFiles.length} files...`);
+  // Upload all files
+  console.log(`\n🚀 Uploading ${allFiles.length} configured files...`);
   let successCount = 0;
   let failCount = 0;
 
-  for (const file of allFiles) {
+  for (const mount of allFiles) {
+    const { remotePath, localPath } = mount;
     try {
-      if (file.isDirectory) {
-        // Upload all files recursively in the local directory
-        const localDir = file.localPath.endsWith("/") ? file.localPath : file.localPath + "/";
-        const remoteDir = file.remotePath.endsWith("/") ? file.remotePath : file.remotePath + "/";
-        const relFiles = listFilesRecursively(localDir);
-        console.log(`  📁 Uploading directory ${localDir} → ${remoteDir} (${relFiles.length} files)`);
-        for (const relFile of relFiles) {
-          await uploadSingleFile(client, AwsS3, localDir + relFile, remoteDir + relFile, dryRun);
-          successCount++;
-        }
+      if (remotePath.endsWith("/") || localPath.endsWith("/")) {
+        const count = await uploadDirectory(client, AwsS3, remotePath, localPath, dryRun);
+        successCount += count;
       } else {
-        await uploadSingleFile(client, AwsS3, file.localPath, file.remotePath, dryRun);
+        await uploadFile(client, AwsS3, remotePath, localPath, dryRun);
         successCount++;
       }
     } catch (error) {
-      console.error(`  ❌ Failed to upload ${file.localPath}: ${error.message}`);
+      console.error(`  ❌ Failed to upload ${localPath}: ${error.message}`);
       failCount++;
     }
   }
 
   console.log(`\n   ✓ Upload complete: ${successCount} succeeded, ${failCount} failed`);
 
-  // Step 6: Create or update cloud worker
+  // Create or update cloud worker
   if (create) {
     const workerName = name || `${projectName}-worker`;
     console.log(`\n🌩️  Creating cloud worker "${workerName}"...`);
@@ -339,16 +337,6 @@ export async function cloudWorker(options: CloudWorkerOptions) {
 /**
  * Pull the latest workerConfigJson from the cloud worker API and update the
  * local knowhow.json config to match.
- *
- * This is the "pull" half of the config sync cycle.  After running this,
- * you can reload the worker's MCPs (in-process) via the reloadConfig
- * WebSocket message or by calling `knowhow worker` again.
- *
- * Merged fields from workerConfigJson:
- *   - mcps        → overwrites config.mcps
- *   - modules     → overwrites config.modules  (optional, only if present)
- *   - plugins     → overwrites config.plugins  (optional, only if present)
- *   - agents      → overwrites config.agents   (optional, only if present)
  */
 export async function pullCloudWorkerConfig(options: CloudWorkerPullOptions) {
   const { id, apiUrl = KNOWHOW_API_URL } = options;

package/src/commands/modules.ts

@@ -1,5 +1,8 @@
 import { Command } from "commander";
 import { execSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
 import { getConfig, getGlobalConfig, updateConfig, updateGlobalConfig } from "../config";
 
 // Default built-in modules that `knowhow modules setup` adds to the config.
@@ -8,6 +11,44 @@ export const BUILTIN_MODULES = [
   "@tyvm/knowhow-module-terminal",
 ];
 
+/**
+ * Returns the path to the .knowhow directory (used as npm install prefix).
+ * For global: ~/.knowhow
+ * For local:  <cwd>/.knowhow
+ */
+function getKnowhowDir(isGlobal: boolean): string {
+  if (isGlobal) {
+    return path.join(os.homedir(), ".knowhow");
+  }
+  return path.join(process.cwd(), ".knowhow");
+}
+
+/**
+ * Ensures the .knowhow directory has a minimal package.json so
+ * `npm install --prefix` works cleanly without polluting the project root.
+ */
+function ensureKnowhowPackageJson(knowhowDir: string): void {
+  const pkgPath = path.join(knowhowDir, "package.json");
+  if (!fs.existsSync(pkgPath)) {
+    fs.mkdirSync(knowhowDir, { recursive: true });
+    fs.writeFileSync(
+      pkgPath,
+      JSON.stringify({ name: "knowhow-modules", private: true, version: "1.0.0" }, null, 2)
+    );
+  }
+}
+
+/**
+ * Run `npm install --prefix <knowhowDir> <mod>` so that modules land in
+ * .knowhow/node_modules rather than the project's node_modules.
+ */
+function npmInstallToKnowhow(mod: string, knowhowDir: string): void {
+  execSync(`npm install --prefix "${knowhowDir}" ${mod}`, {
+    stdio: "inherit",
+    encoding: "utf-8",
+  });
+}
+
 export function addModulesCommand(program: Command): void {
   const modulesCmd = program
     .command("modules")
@@ -16,7 +57,7 @@ export function addModulesCommand(program: Command): void {
   modulesCmd
     .command("setup")
     .description(
-      "Add default built-in modules to your config and install them via npm"
+      "Add default built-in modules to your config and install them into .knowhow/node_modules"
     )
     .option("--global", "Use the global config (~/.knowhow/knowhow.json)")
     .action(async (opts) => {
@@ -40,15 +81,14 @@ export function addModulesCommand(program: Command): void {
           return;
         }
 
+        const knowhowDir = getKnowhowDir(isGlobal);
+        ensureKnowhowPackageJson(knowhowDir);
+
         // Install packages that are not local file paths
         for (const mod of toAdd) {
           if (!mod.startsWith(".") && !mod.startsWith("/")) {
             console.log(`📦 Installing ${mod}...`);
-            const installFlag = isGlobal ? "-g" : "";
-            execSync(`npm install ${installFlag} ${mod}`, {
-              stdio: "inherit",
-              encoding: "utf-8",
-            });
+            npmInstallToKnowhow(mod, knowhowDir);
           }
           cfg.modules!.push(mod);
           console.log(`✅ Added ${mod} to ${configLabel}`);
@@ -63,7 +103,7 @@ export function addModulesCommand(program: Command): void {
         console.log(
           `\n🎉 Setup complete! ${toAdd.length} module(s) added to ${configLabel}`
         );
-      } catch (error) {
+      } catch (error: any) {
         console.error("Error during modules setup:", error.message ?? error);
         process.exit(1);
       }
@@ -72,7 +112,7 @@ export function addModulesCommand(program: Command): void {
   modulesCmd
     .command("install [module]")
     .description(
-      "Install a module via npm and add it to your config. " +
+      "Install a module into .knowhow/node_modules and add it to your config. " +
       "If no module name is given, installs all modules already in the config."
     )
     .option("--global", "Use the global config (~/.knowhow/knowhow.json)")
@@ -86,6 +126,9 @@ export function addModulesCommand(program: Command): void {
 
         if (!cfg.modules) cfg.modules = [];
 
+        const knowhowDir = getKnowhowDir(isGlobal);
+        ensureKnowhowPackageJson(knowhowDir);
+
         if (!moduleName) {
           // No module specified — install everything already in the config
           const installable = cfg.modules.filter(
@@ -98,15 +141,11 @@ export function addModulesCommand(program: Command): void {
             return;
           }
           console.log(
-            `📦 Installing ${installable.length} module(s) from ${configLabel}...`
+            `📦 Installing ${installable.length} module(s) from ${configLabel} into ${knowhowDir}/node_modules...`
           );
-          const installFlag = isGlobal ? "-g" : "";
           for (const mod of installable) {
             console.log(`  📦 Installing ${mod}...`);
-            execSync(`npm install ${installFlag} ${mod}`, {
-              stdio: "inherit",
-              encoding: "utf-8",
-            });
+            npmInstallToKnowhow(mod, knowhowDir);
             console.log(`  ✅ Installed ${mod}`);
           }
           console.log(`\n🎉 All modules installed!`);
@@ -114,12 +153,8 @@ export function addModulesCommand(program: Command): void {
         }
 
         // Install the specified module
-        const installFlag = isGlobal ? "-g" : "";
-        console.log(`📦 Installing ${moduleName}...`);
-        execSync(`npm install ${installFlag} ${moduleName}`, {
-          stdio: "inherit",
-          encoding: "utf-8",
-        });
+        console.log(`📦 Installing ${moduleName} into ${knowhowDir}/node_modules...`);
+        npmInstallToKnowhow(moduleName, knowhowDir);
         console.log(`✅ Installed ${moduleName}`);
 
         // Add to config if not already there
@@ -134,7 +169,7 @@ export function addModulesCommand(program: Command): void {
         } else {
           console.log(`ℹ ${moduleName} is already in ${configLabel}`);
         }
-      } catch (error) {
+      } catch (error: any) {
         console.error("Error during module install:", error.message ?? error);
         process.exit(1);
       }
@@ -174,7 +209,7 @@ export function addModulesCommand(program: Command): void {
             localModules.forEach((m, i) => console.log(`  ${i + 1}. ${m}`));
           }
         }
-      } catch (error) {
+      } catch (error: any) {
         console.error("Error listing modules:", error.message ?? error);
         process.exit(1);
       }