claudekit-cli 3.26.0 → 3.27.0

package/dist/index.js

@@ -16194,7 +16194,7 @@ var init_init_command_help = __esm(() => {
           },
           {
             flags: "--fresh",
-            description: "Completely remove .claude directory before downloading (requires confirmation)"
+            description: "Remove ClaudeKit directories (commands/, agents/, skills/, rules/, hooks/) and reinstall"
           }
         ]
       },
@@ -16442,7 +16442,7 @@ var init_update_command_help = __esm(() => {
     sections: [
       {
         title: "Note",
-        content: "'ck update' updates the CLI tool only. To update kit content (skills, commands, workflows), use 'ck init' for local or 'ck init -g' for global."
+        content: "'ck update' updates the CLI tool only. To update kit content (skills, commands, rules), use 'ck init' for local or 'ck init -g' for global."
       }
     ]
   };
@@ -16592,7 +16592,7 @@ function getPagerArgs(pagerCmd) {
   return [];
 }
 async function trySystemPager(content) {
-  return new Promise((resolve10) => {
+  return new Promise((resolve11) => {
     const pagerCmd = process.env.PAGER || "less";
     const pagerArgs = getPagerArgs(pagerCmd);
     try {
@@ -16602,20 +16602,20 @@ async function trySystemPager(content) {
       });
       const timeout = setTimeout(() => {
         pager.kill();
-        resolve10(false);
+        resolve11(false);
       }, 30000);
       pager.stdin.write(content);
       pager.stdin.end();
       pager.on("close", (code2) => {
         clearTimeout(timeout);
-        resolve10(code2 === 0);
+        resolve11(code2 === 0);
       });
       pager.on("error", () => {
         clearTimeout(timeout);
-        resolve10(false);
+        resolve11(false);
       });
     } catch {
-      resolve10(false);
+      resolve11(false);
     }
   });
 }
@@ -16642,16 +16642,16 @@ async function basicPager(content) {
       break;
     }
     const remaining = lines.length - currentLine;
-    await new Promise((resolve10) => {
+    await new Promise((resolve11) => {
       rl.question(`-- More (${remaining} lines) [Enter/q] --`, (answer) => {
         if (answer.toLowerCase() === "q") {
           rl.close();
           process.exitCode = 0;
-          resolve10();
+          resolve11();
           return;
         }
         process.stdout.write("\x1B[1A\x1B[2K");
-        resolve10();
+        resolve11();
       });
     });
   }
@@ -18542,7 +18542,7 @@ class PathResolver {
   }
   static buildComponentPath(baseDir, component, global2) {
     if (!PathResolver.isValidComponentName(component)) {
-      throw new Error(`Invalid component name: "${component}" contains path traversal patterns. Valid names are simple directory names like "agents", "commands", "workflows", "skills", or "hooks".`);
+      throw new Error(`Invalid component name: "${component}" contains path traversal patterns. Valid names are simple directory names like "agents", "commands", "rules", "skills", or "hooks".`);
     }
     const prefix = PathResolver.getPathPrefix(global2);
     if (prefix) {
@@ -18620,7 +18620,7 @@ async function scanClaudeKitDirectory(directoryPath) {
   const counts = {
     agents: 0,
     commands: 0,
-    workflows: 0,
+    rules: 0,
     skills: 0
   };
   try {
@@ -18638,10 +18638,14 @@ async function scanClaudeKitDirectory(directoryPath) {
       const commandFiles = await import_fs_extra.readdir(commandsPath);
       counts.commands = commandFiles.filter((file) => file.endsWith(".md")).length;
     }
-    if (items.includes("workflows")) {
+    if (items.includes("rules")) {
+      const rulesPath = join2(directoryPath, "rules");
+      const ruleFiles = await import_fs_extra.readdir(rulesPath);
+      counts.rules = ruleFiles.filter((file) => file.endsWith(".md")).length;
+    } else if (items.includes("workflows")) {
       const workflowsPath = join2(directoryPath, "workflows");
       const workflowFiles = await import_fs_extra.readdir(workflowsPath);
-      counts.workflows = workflowFiles.filter((file) => file.endsWith(".md")).length;
+      counts.rules = workflowFiles.filter((file) => file.endsWith(".md")).length;
     }
     if (items.includes("skills")) {
       const skillsPath = join2(directoryPath, "skills");
@@ -18682,12 +18686,12 @@ async function getClaudeKitSetup(projectDir = process.cwd()) {
     global: {
       path: "",
       metadata: null,
-      components: { agents: 0, commands: 0, workflows: 0, skills: 0 }
+      components: { agents: 0, commands: 0, rules: 0, skills: 0 }
     },
     project: {
       path: "",
       metadata: null,
-      components: { agents: 0, commands: 0, workflows: 0, skills: 0 }
+      components: { agents: 0, commands: 0, rules: 0, skills: 0 }
     }
   };
   const globalDir = getGlobalInstallDir();
@@ -19310,16 +19314,16 @@ function checkComponentCounts(setup) {
   const project = setup.project.components;
   const totalAgents = global2.agents + project.agents;
   const totalCommands = global2.commands + project.commands;
-  const totalWorkflows = global2.workflows + project.workflows;
+  const totalRules = global2.rules + project.rules;
   const totalSkills = global2.skills + project.skills;
-  const totalComponents = totalAgents + totalCommands + totalWorkflows + totalSkills;
+  const totalComponents = totalAgents + totalCommands + totalRules + totalSkills;
   return {
     id: "ck-component-counts",
     name: "ClaudeKit Components",
     group: "claudekit",
     priority: "standard",
     status: totalComponents > 0 ? "info" : "warn",
-    message: totalComponents > 0 ? `${totalAgents} agents, ${totalCommands} commands, ${totalWorkflows} workflows, ${totalSkills} skills` : "No components found",
+    message: totalComponents > 0 ? `${totalAgents} agents, ${totalCommands} commands, ${totalRules} rules, ${totalSkills} skills` : "No components found",
     suggestion: totalComponents === 0 ? "Install ClaudeKit: ck new --kit engineer" : undefined,
     autoFixable: false
   };
@@ -19680,7 +19684,7 @@ async function checkProjectConfigCompleteness(setup, projectDir) {
     };
   }
   const projectClaudeDir = join11(projectDir, ".claude");
-  const requiredDirs = ["agents", "commands", "workflows", "skills"];
+  const requiredDirs = ["agents", "commands", "skills"];
   const missingDirs = [];
   for (const dir of requiredDirs) {
     const dirPath = join11(projectClaudeDir, dir);
@@ -19688,9 +19692,14 @@ async function checkProjectConfigCompleteness(setup, projectDir) {
       missingDirs.push(dir);
     }
   }
+  const hasRulesOrWorkflows = existsSync10(join11(projectClaudeDir, "rules")) || existsSync10(join11(projectClaudeDir, "workflows"));
+  if (!hasRulesOrWorkflows) {
+    missingDirs.push("rules");
+  }
   const files = await readdir3(projectClaudeDir).catch(() => []);
   const hasOnlyClaudeMd = files.length === 1 && files.includes("CLAUDE.md");
-  if (hasOnlyClaudeMd || missingDirs.length === requiredDirs.length) {
+  const totalRequired = requiredDirs.length + 1;
+  if (hasOnlyClaudeMd || missingDirs.length === totalRequired) {
     return {
       id: "ck-project-config-complete",
       name: "Project Config Completeness",
@@ -19698,7 +19707,7 @@ async function checkProjectConfigCompleteness(setup, projectDir) {
       priority: "standard",
       status: "fail",
       message: "Incomplete configuration",
-      details: "Only CLAUDE.md found - missing agents, commands, workflows, skills",
+      details: "Only CLAUDE.md found - missing agents, commands, rules, skills",
       suggestion: "Run 'ck init' to install complete ClaudeKit in project",
       autoFixable: false
     };
@@ -24657,9 +24666,9 @@ async function promptDirectorySelection(global2 = false) {
     { key: "agents", label: "Agents", pattern: prefix ? `${prefix}/agents` : "agents" },
     { key: "commands", label: "Commands", pattern: prefix ? `${prefix}/commands` : "commands" },
     {
-      key: "workflows",
-      label: "Workflows",
-      pattern: prefix ? `${prefix}/workflows` : "workflows"
+      key: "rules",
+      label: "Rules",
+      pattern: prefix ? `${prefix}/rules` : "rules"
     },
     { key: "skills", label: "Skills", pattern: prefix ? `${prefix}/skills` : "skills" },
     { key: "hooks", label: "Hooks", pattern: prefix ? `${prefix}/hooks` : "hooks" }
@@ -24681,12 +24690,25 @@ async function promptDirectorySelection(global2 = false) {
   }
   return selectedCategories;
 }
-async function promptFreshConfirmation(targetPath) {
-  logger.warning("[!] WARNING: Fresh installation will completely remove the .claude directory!");
+async function promptFreshConfirmation(targetPath, analysis) {
+  logger.warning("[!] Fresh installation will remove ClaudeKit files:");
   logger.info(`Path: ${targetPath}`);
-  logger.info("All custom files, configurations, and modifications will be permanently deleted.");
+  if (analysis?.hasMetadata) {
+    const ckCount = analysis.ckFiles.length + analysis.ckModifiedFiles.length;
+    const userCount = analysis.userFiles.length;
+    logger.info(`  Remove: ${ckCount} CK-owned files`);
+    logger.info(`  Preserve: ${userCount} user-created files`);
+    if (userCount > 0) {
+      const samples = analysis.userFiles.slice(0, 3).map((f3) => f3.path);
+      const remaining = userCount - samples.length;
+      logger.info(`  Examples preserved: ${samples.join(", ")}${remaining > 0 ? ` (+${remaining} more)` : ""}`);
+    }
+  } else {
+    logger.info("  Remove: commands/, agents/, skills/, rules/, hooks/");
+    logger.info("  Preserve: settings.json, Claude Code data");
+  }
   const confirmation = await te({
-    message: "Type 'yes' to confirm complete removal:",
+    message: "Type 'yes' to confirm:",
     placeholder: "yes",
     validate: (value) => {
       if (value.toLowerCase() !== "yes") {
@@ -24884,8 +24906,8 @@ class PromptsManager {
       logger.info("You can install these manually later using npm install -g <package>");
     }
   }
-  async promptFreshConfirmation(targetPath) {
-    return promptFreshConfirmation(targetPath);
+  async promptFreshConfirmation(targetPath, analysis) {
+    return promptFreshConfirmation(targetPath, analysis);
   }
   async promptUpdateMode() {
     return promptUpdateMode();
@@ -26440,7 +26462,7 @@ var import_ignore = __toESM(require_ignore(), 1);
 // src/domains/installation/download/file-downloader.ts
 init_logger();
 init_output_manager();
-import { createWriteStream as createWriteStream2 } from "node:fs";
+import { createWriteStream as createWriteStream2, rmSync } from "node:fs";
 import { mkdir as mkdir9 } from "node:fs/promises";
 import { join as join28 } from "node:path";
 
@@ -26688,11 +26710,29 @@ class FileDownloader {
           downloadedSize += value.length;
           progressBar.update(downloadedSize);
         }
+        if (downloadedSize !== totalSize) {
+          fileStream.end();
+          await new Promise((resolve5) => fileStream.once("close", resolve5));
+          try {
+            rmSync(destPath, { force: true });
+          } catch (cleanupError) {
+            const errorMsg = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+            logger.debug(`Failed to clean up partial download ${destPath}: ${errorMsg}`);
+          }
+          throw new DownloadError(`Incomplete download: received ${formatBytes(downloadedSize)} of ${formatBytes(totalSize)}`);
+        }
         fileStream.end();
         progressBar.complete(`Downloaded ${asset.name}`);
         return destPath;
       } catch (error) {
-        fileStream.close();
+        fileStream.end();
+        await new Promise((resolve5) => fileStream.once("close", resolve5));
+        try {
+          rmSync(destPath, { force: true });
+        } catch (cleanupError) {
+          const errorMsg = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+          logger.debug(`Failed to clean up partial download ${destPath}: ${errorMsg}`);
+        }
         throw error;
       }
     } catch (error) {
@@ -26742,11 +26782,19 @@ class FileDownloader {
           progressBar.update(downloadedSize);
         }
       }
-      fileStream.end();
       const expectedSize = Number(response.headers.get("content-length"));
       if (expectedSize > 0 && downloadedSize !== expectedSize) {
+        fileStream.end();
+        await new Promise((resolve5) => fileStream.once("close", resolve5));
+        try {
+          rmSync(destPath, { force: true });
+        } catch (cleanupError) {
+          const errorMsg = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+          logger.debug(`Failed to clean up partial download ${destPath}: ${errorMsg}`);
+        }
         throw new DownloadError(`Incomplete download: received ${formatBytes(downloadedSize)} of ${formatBytes(expectedSize)}`);
       }
+      fileStream.end();
       if (progressBar) {
         progressBar.complete(`Downloaded ${name}`);
       } else {
@@ -26754,7 +26802,14 @@ class FileDownloader {
       }
       return destPath;
     } catch (error) {
-      fileStream.close();
+      fileStream.end();
+      await new Promise((resolve5) => fileStream.once("close", resolve5));
+      try {
+        rmSync(destPath, { force: true });
+      } catch (cleanupError) {
+        const errorMsg = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+        logger.debug(`Failed to clean up partial download ${destPath}: ${errorMsg}`);
+      }
       throw error;
     }
   }
@@ -34468,7 +34523,7 @@ async function getUninstallManifest(claudeDir, kit) {
     const installedFiles = detection.metadata.installedFiles || [];
     const hasFiles = legacyFiles2.length > 0 || installedFiles.length > 0;
     if (!hasFiles) {
-      const legacyDirs2 = ["commands", "agents", "skills", "workflows", "hooks", "scripts"];
+      const legacyDirs2 = ["commands", "agents", "skills", "rules", "workflows", "hooks", "scripts"];
       const legacyFileList = ["metadata.json"];
       return {
         filesToRemove: [...legacyDirs2, ...legacyFileList],
@@ -34486,7 +34541,7 @@ async function getUninstallManifest(claudeDir, kit) {
       remainingKits: []
     };
   }
-  const legacyDirs = ["commands", "agents", "skills", "workflows", "hooks", "scripts"];
+  const legacyDirs = ["commands", "agents", "skills", "rules", "workflows", "hooks", "scripts"];
   const legacyFiles = ["metadata.json"];
   return {
     filesToRemove: [...legacyDirs, ...legacyFiles],
@@ -40330,7 +40385,7 @@ Optional: DISCORD_WEBHOOK_URL, TELEGRAM_BOT_TOKEN`, "Configuration skipped");
 }
 // src/commands/init/phases/selection-handler.ts
 import { mkdir as mkdir20 } from "node:fs/promises";
-import { join as join66, resolve as resolve7 } from "node:path";
+import { join as join66, resolve as resolve8 } from "node:path";
 
 // src/domains/github/kit-access-checker.ts
 init_logger();
@@ -40457,38 +40512,196 @@ async function runPreflightChecks() {
 }
 
 // src/domains/installation/fresh-installer.ts
+import { existsSync as existsSync19, readdirSync, rmSync as rmSync2, rmdirSync, unlinkSync as unlinkSync3 } from "node:fs";
+import { dirname as dirname9, join as join65, resolve as resolve7 } from "node:path";
 init_logger();
-import { join as join65 } from "node:path";
 var import_fs_extra29 = __toESM(require_lib(), 1);
-var CLAUDEKIT_SUBDIRECTORIES = ["commands", "agents", "skills", "workflows", "hooks"];
+var CLAUDEKIT_SUBDIRECTORIES = ["commands", "agents", "skills", "rules", "hooks"];
+async function analyzeFreshInstallation(claudeDir) {
+  const metadata = await readManifest(claudeDir);
+  if (!metadata) {
+    return {
+      ckFiles: [],
+      ckModifiedFiles: [],
+      userFiles: [],
+      hasMetadata: false
+    };
+  }
+  const allFiles = getAllTrackedFiles(metadata);
+  if (allFiles.length === 0) {
+    return {
+      ckFiles: [],
+      ckModifiedFiles: [],
+      userFiles: [],
+      hasMetadata: false
+    };
+  }
+  const ckFiles = [];
+  const ckModifiedFiles = [];
+  const userFiles = [];
+  for (const file of allFiles) {
+    switch (file.ownership) {
+      case "ck":
+        ckFiles.push(file);
+        break;
+      case "ck-modified":
+        ckModifiedFiles.push(file);
+        break;
+      case "user":
+        userFiles.push(file);
+        break;
+    }
+  }
+  return {
+    ckFiles,
+    ckModifiedFiles,
+    userFiles,
+    hasMetadata: true
+  };
+}
+function cleanupEmptyDirectories(filePath, claudeDir) {
+  const normalizedClaudeDir = resolve7(claudeDir);
+  let currentDir = resolve7(dirname9(filePath));
+  while (currentDir !== normalizedClaudeDir && currentDir.startsWith(normalizedClaudeDir)) {
+    try {
+      const entries = readdirSync(currentDir);
+      if (entries.length === 0) {
+        rmdirSync(currentDir);
+        logger.debug(`Removed empty directory: ${currentDir}`);
+        currentDir = resolve7(dirname9(currentDir));
+      } else {
+        break;
+      }
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      logger.debug(`Could not remove directory ${currentDir}: ${errorMsg}`);
+      break;
+    }
+  }
+}
+async function removeFilesByOwnership(claudeDir, analysis, includeModified) {
+  const removedFiles = [];
+  const preservedFiles = [];
+  const filesToRemove = includeModified ? [...analysis.ckFiles, ...analysis.ckModifiedFiles] : analysis.ckFiles;
+  const filesToPreserve = includeModified ? analysis.userFiles : [...analysis.ckModifiedFiles, ...analysis.userFiles];
+  for (const file of filesToRemove) {
+    const fullPath = join65(claudeDir, file.path);
+    try {
+      if (existsSync19(fullPath)) {
+        unlinkSync3(fullPath);
+        removedFiles.push(file.path);
+        logger.debug(`Removed: ${file.path}`);
+        cleanupEmptyDirectories(fullPath, claudeDir);
+      }
+    } catch (error) {
+      logger.debug(`Failed to remove ${file.path}: ${error}`);
+    }
+  }
+  for (const file of filesToPreserve) {
+    preservedFiles.push(file.path);
+  }
+  await updateMetadataAfterFresh(claudeDir, removedFiles);
+  return {
+    success: true,
+    removedCount: removedFiles.length,
+    preservedCount: preservedFiles.length,
+    removedFiles,
+    preservedFiles
+  };
+}
+async function updateMetadataAfterFresh(claudeDir, removedFiles) {
+  const metadataPath = join65(claudeDir, "metadata.json");
+  if (!await import_fs_extra29.pathExists(metadataPath)) {
+    return;
+  }
+  let content;
+  try {
+    content = await import_fs_extra29.readFile(metadataPath, "utf-8");
+  } catch (readError) {
+    logger.warning(`Failed to read metadata.json: ${readError instanceof Error ? readError.message : String(readError)}`);
+    return;
+  }
+  let metadata;
+  try {
+    metadata = JSON.parse(content);
+  } catch (parseError) {
+    logger.warning(`Failed to parse metadata.json: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+    logger.info("Recommendation: Run 'ck init' to rebuild metadata");
+    return;
+  }
+  const removedSet = new Set(removedFiles);
+  if (metadata.kits) {
+    for (const kitName of Object.keys(metadata.kits)) {
+      const kit = metadata.kits[kitName];
+      if (kit?.files) {
+        kit.files = kit.files.filter((f3) => !removedSet.has(f3.path));
+      }
+    }
+  }
+  if (metadata.files) {
+    metadata.files = metadata.files.filter((f3) => !removedSet.has(f3.path));
+  }
+  try {
+    await import_fs_extra29.writeFile(metadataPath, JSON.stringify(metadata, null, 2));
+    logger.debug(`Updated metadata.json, removed ${removedFiles.length} file entries`);
+  } catch (writeError) {
+    logger.warning(`Failed to write metadata.json: ${writeError instanceof Error ? writeError.message : String(writeError)}`);
+    logger.info("Recommendation: Check file permissions and run 'ck init' to rebuild metadata");
+  }
+}
+async function removeSubdirectoriesFallback(claudeDir) {
+  const removedFiles = [];
+  let removedDirCount = 0;
+  for (const subdir of CLAUDEKIT_SUBDIRECTORIES) {
+    const subdirPath = join65(claudeDir, subdir);
+    if (await import_fs_extra29.pathExists(subdirPath)) {
+      rmSync2(subdirPath, { recursive: true, force: true });
+      removedDirCount++;
+      removedFiles.push(`${subdir}/ (entire directory)`);
+      logger.debug(`Removed subdirectory: ${subdir}/`);
+    }
+  }
+  const metadataPath = join65(claudeDir, "metadata.json");
+  if (await import_fs_extra29.pathExists(metadataPath)) {
+    unlinkSync3(metadataPath);
+    removedFiles.push("metadata.json");
+  }
+  return {
+    success: true,
+    removedCount: removedDirCount,
+    preservedCount: 0,
+    removedFiles,
+    preservedFiles: []
+  };
+}
 async function handleFreshInstallation(claudeDir, prompts) {
   if (!await import_fs_extra29.pathExists(claudeDir)) {
     logger.info(".claude directory does not exist, proceeding with fresh installation");
     return true;
   }
-  const confirmed = await prompts.promptFreshConfirmation(claudeDir);
+  const analysis = await analyzeFreshInstallation(claudeDir);
+  const confirmed = await prompts.promptFreshConfirmation(claudeDir, analysis);
   if (!confirmed) {
     logger.info("Fresh installation cancelled");
     return false;
   }
-  logger.info("Removing ClaudeKit-managed subdirectories...");
-  const spinner = createSpinner("Removing ClaudeKit subdirectories...").start();
+  const spinner = createSpinner("Removing ClaudeKit files...").start();
   try {
-    const { rmSync } = await import("node:fs");
-    let removedCount = 0;
-    for (const subdir of CLAUDEKIT_SUBDIRECTORIES) {
-      const subdirPath = join65(claudeDir, subdir);
-      if (await import_fs_extra29.pathExists(subdirPath)) {
-        rmSync(subdirPath, { recursive: true, force: true });
-        removedCount++;
-        logger.debug(`Removed subdirectory: ${subdir}/`);
-      }
+    let result;
+    if (analysis.hasMetadata && (analysis.ckFiles.length > 0 || analysis.ckModifiedFiles.length > 0)) {
+      result = await removeFilesByOwnership(claudeDir, analysis, true);
+      spinner.succeed(`Removed ${result.removedCount} CK files, preserved ${result.preservedCount} user files`);
+    } else {
+      result = await removeSubdirectoriesFallback(claudeDir);
+      spinner.succeed(`Removed ${result.removedCount} ClaudeKit directories`);
+    }
+    if (result.preservedCount > 0) {
+      logger.verbose(`Preserved user files: ${result.preservedFiles.slice(0, 5).join(", ")}${result.preservedFiles.length > 5 ? ` and ${result.preservedFiles.length - 5} more` : ""}`);
     }
-    spinner.succeed(`Successfully removed ${removedCount} ClaudeKit subdirectories (preserving user configs)`);
     return true;
   } catch (error) {
-    spinner.fail("Failed to remove ClaudeKit subdirectories");
-    throw new Error(`Failed to remove subdirectories: ${error instanceof Error ? error.message : "Unknown error"}`);
+    spinner.fail("Failed to remove ClaudeKit files");
+    throw new Error(`Failed to remove files: ${error instanceof Error ? error.message : "Unknown error"}`);
   }
 }
 
@@ -40517,6 +40730,18 @@ async function handleSelection(ctx) {
       release: release2
     };
   }
+  const downloadMethods = [];
+  if (ctx.options.useGit)
+    downloadMethods.push("--use-git");
+  if (ctx.options.archive)
+    downloadMethods.push("--archive");
+  if (ctx.options.kitPath)
+    downloadMethods.push("--kit-path");
+  if (downloadMethods.length > 1) {
+    logger.error(`Mutually exclusive download methods: ${downloadMethods.join(", ")}`);
+    logger.info("Use only one of: --use-git, --archive, or --kit-path");
+    return { ...ctx, cancelled: true };
+  }
   const config = await ConfigManager.get();
   let accessibleKits;
   if (!ctx.options.useGit && !ctx.options.kitPath && !ctx.options.archive) {
@@ -40652,7 +40877,7 @@ async function handleSelection(ctx) {
       }
     }
   }
-  const resolvedDir = resolve7(targetDir);
+  const resolvedDir = resolve8(targetDir);
   logger.info(`Target directory: ${resolvedDir}`);
   if (!ctx.options.global && PathResolver.isLocalSameAsGlobal(resolvedDir)) {
     logger.warning("You're at HOME directory. Installing here modifies your GLOBAL ClaudeKit.");
@@ -40724,15 +40949,16 @@ async function handleSelection(ctx) {
       return { ...ctx, cancelled: true };
     }
   }
-  const github = new GitHubClient;
+  const isOfflineMode = !!(ctx.options.kitPath || ctx.options.archive);
+  const github = isOfflineMode ? null : new GitHubClient;
   let selectedVersion = ctx.options.release;
-  if (!selectedVersion && ctx.isNonInteractive && !ctx.options.yes) {
+  if (!selectedVersion && ctx.isNonInteractive && !ctx.options.yes && !isOfflineMode) {
     throw new Error("Non-interactive mode requires either: --release <tag> OR --yes (uses latest)");
   }
-  if (!selectedVersion && ctx.options.yes) {
+  if (!selectedVersion && ctx.options.yes && !isOfflineMode) {
     logger.info("Using latest stable version (--yes flag)");
   }
-  if (!selectedVersion && !ctx.isNonInteractive) {
+  if (!selectedVersion && !ctx.isNonInteractive && !isOfflineMode) {
     logger.info("Fetching available versions...");
     let currentVersion = null;
     try {
@@ -40765,7 +40991,13 @@ async function handleSelection(ctx) {
     }
   }
   let release;
-  if (ctx.options.useGit && selectedVersion) {
+  if (isOfflineMode) {
+    release = undefined;
+    logger.verbose("Offline mode - skipping release fetch", {
+      kitPath: ctx.options.kitPath,
+      archive: ctx.options.archive
+    });
+  } else if (ctx.options.useGit && selectedVersion) {
     release = {
       id: 0,
       tag_name: selectedVersion,
@@ -40777,9 +41009,9 @@ async function handleSelection(ctx) {
       assets: []
     };
     logger.verbose("Using git clone mode with tag", { tag: selectedVersion });
-  } else if (selectedVersion) {
+  } else if (selectedVersion && github) {
     release = await github.getReleaseByTag(kit, selectedVersion);
-  } else {
+  } else if (github) {
     if (ctx.options.beta) {
       logger.info("Fetching latest beta release...");
     } else {
@@ -40804,8 +41036,8 @@ async function handleSelection(ctx) {
   };
 }
 // src/commands/init/phases/sync-handler.ts
-import { copyFile as copyFile6, mkdir as mkdir21, open, rename as rename3, stat as stat10, unlink as unlink7, writeFile as writeFile19 } from "node:fs/promises";
-import { dirname as dirname9, join as join67, resolve as resolve8 } from "node:path";
+import { copyFile as copyFile6, mkdir as mkdir21, open, rename as rename3, stat as stat10, unlink as unlink7, writeFile as writeFile20 } from "node:fs/promises";
+import { dirname as dirname10, join as join67, resolve as resolve9 } from "node:path";
 init_logger();
 var import_fs_extra31 = __toESM(require_lib(), 1);
 var import_picocolors19 = __toESM(require_picocolors(), 1);
@@ -40813,7 +41045,7 @@ async function handleSync(ctx) {
   if (!ctx.options.sync) {
     return ctx;
   }
-  const resolvedDir = ctx.options.global ? PathResolver.getGlobalKitDir() : resolve8(ctx.options.dir || ".");
+  const resolvedDir = ctx.options.global ? PathResolver.getGlobalKitDir() : resolve9(ctx.options.dir || ".");
   const claudeDir = ctx.options.global ? resolvedDir : join67(resolvedDir, ".claude");
   if (!await import_fs_extra31.pathExists(claudeDir)) {
     logger.error("Cannot sync: no .claude directory found");
@@ -40923,7 +41155,7 @@ async function acquireSyncLock(global3) {
   const lockPath = join67(cacheDir, ".sync-lock");
   const startTime = Date.now();
   const lockTimeout = getLockTimeout();
-  await mkdir21(dirname9(lockPath), { recursive: true });
+  await mkdir21(dirname10(lockPath), { recursive: true });
   while (Date.now() - startTime < lockTimeout) {
     try {
       const handle = await open(lockPath, "wx");
@@ -40947,7 +41179,7 @@ async function acquireSyncLock(global3) {
           }
           logger.debug(`Lock stat failed: ${statError}`);
         }
-        await new Promise((resolve9) => setTimeout(resolve9, 100));
+        await new Promise((resolve10) => setTimeout(resolve10, 100));
         continue;
       }
       throw err;
@@ -41066,7 +41298,7 @@ async function executeSyncMerge(ctx) {
         try {
           const tempPath = `${currentPath}.tmp.${Date.now()}`;
           try {
-            await writeFile19(tempPath, result.result, "utf-8");
+            await writeFile20(tempPath, result.result, "utf-8");
             await rename3(tempPath, currentPath);
           } catch (atomicError) {
             await unlink7(tempPath).catch(() => {});
@@ -41252,7 +41484,7 @@ async function renameFolders(dirsToRename, extractDir, options) {
 // src/services/transformers/folder-transform/path-replacer.ts
 init_logger();
 init_types2();
-import { readFile as readFile23, readdir as readdir23, writeFile as writeFile20 } from "node:fs/promises";
+import { readFile as readFile24, readdir as readdir23, writeFile as writeFile21 } from "node:fs/promises";
 import { join as join69, relative as relative13 } from "node:path";
 var TRANSFORMABLE_FILE_PATTERNS = [
   ".md",
@@ -41319,7 +41551,7 @@ async function transformFileContents(dir, compiledReplacements, options) {
       if (!shouldTransform)
         continue;
       try {
-        const content = await readFile23(fullPath, "utf-8");
+        const content = await readFile24(fullPath, "utf-8");
         let newContent = content;
         let changeCount = 0;
         for (const { regex: regex2, replacement } of compiledReplacements) {
@@ -41335,7 +41567,7 @@ async function transformFileContents(dir, compiledReplacements, options) {
           if (options.dryRun) {
             logger.debug(`[dry-run] Would update ${relative13(dir, fullPath)}: ${changeCount} replacement(s)`);
           } else {
-            await writeFile20(fullPath, newContent, "utf-8");
+            await writeFile21(fullPath, newContent, "utf-8");
             logger.debug(`Updated ${relative13(dir, fullPath)}: ${changeCount} replacement(s)`);
           }
           filesChanged++;
@@ -41441,7 +41673,7 @@ async function transformFolderPaths(extractDir, folders, options = {}) {
 
 // src/services/transformers/global-path-transformer.ts
 init_logger();
-import { readFile as readFile24, readdir as readdir24, writeFile as writeFile21 } from "node:fs/promises";
+import { readFile as readFile25, readdir as readdir24, writeFile as writeFile22 } from "node:fs/promises";
 import { platform as platform12 } from "node:os";
 import { extname as extname3, join as join70 } from "node:path";
 var IS_WINDOWS4 = platform12() === "win32";
@@ -41561,10 +41793,10 @@ async function transformPathsForGlobalInstall(directory, options = {}) {
         await processDirectory2(fullPath);
       } else if (entry.isFile() && shouldTransformFile3(entry.name)) {
         try {
-          const content = await readFile24(fullPath, "utf-8");
+          const content = await readFile25(fullPath, "utf-8");
           const { transformed, changes } = transformContent(content);
           if (changes > 0) {
-            await writeFile21(fullPath, transformed, "utf-8");
+            await writeFile22(fullPath, transformed, "utf-8");
             filesTransformed++;
             totalChanges += changes;
             if (options.verbose) {
@@ -41819,7 +42051,7 @@ init_types2();
 var import_picocolors20 = __toESM(require_picocolors(), 1);
 
 // src/commands/new/phases/directory-setup.ts
-import { resolve as resolve9 } from "node:path";
+import { resolve as resolve10 } from "node:path";
 init_logger();
 init_types2();
 var import_fs_extra33 = __toESM(require_lib(), 1);
@@ -41903,7 +42135,7 @@ async function directorySetup(validOptions, prompts) {
       targetDir = await prompts.getDirectory(targetDir);
     }
   }
-  const resolvedDir = resolve9(targetDir);
+  const resolvedDir = resolve10(targetDir);
   logger.info(`Target directory: ${resolvedDir}`);
   if (PathResolver.isLocalSameAsGlobal(resolvedDir)) {
     logger.warning("You're creating a project at HOME directory.");
@@ -42244,14 +42476,14 @@ async function detectInstallations() {
 }
 
 // src/commands/uninstall/removal-handler.ts
-import { readdirSync as readdirSync2, rmSync as rmSync2 } from "node:fs";
+import { readdirSync as readdirSync3, rmSync as rmSync4 } from "node:fs";
 import { join as join74 } from "node:path";
 init_logger();
 var import_fs_extra35 = __toESM(require_lib(), 1);
 
 // src/commands/uninstall/analysis-handler.ts
-import { readdirSync, rmSync } from "node:fs";
-import { dirname as dirname10, join as join73 } from "node:path";
+import { readdirSync as readdirSync2, rmSync as rmSync3 } from "node:fs";
+import { dirname as dirname11, join as join73 } from "node:path";
 init_logger();
 var import_picocolors21 = __toESM(require_picocolors(), 1);
 function classifyFileByOwnership(ownership, forceOverwrite, deleteReason) {
@@ -42266,17 +42498,17 @@ function classifyFileByOwnership(ownership, forceOverwrite, deleteReason) {
   }
   return { action: "preserve", reason: "user-created" };
 }
-async function cleanupEmptyDirectories(filePath, installationRoot) {
+async function cleanupEmptyDirectories2(filePath, installationRoot) {
   let cleaned = 0;
-  let currentDir = dirname10(filePath);
+  let currentDir = dirname11(filePath);
   while (currentDir !== installationRoot && currentDir.startsWith(installationRoot)) {
     try {
-      const entries = readdirSync(currentDir);
+      const entries = readdirSync2(currentDir);
       if (entries.length === 0) {
-        rmSync(currentDir, { recursive: true });
+        rmSync3(currentDir, { recursive: true });
         cleaned++;
         logger.debug(`Removed empty directory: ${currentDir}`);
-        currentDir = dirname10(currentDir);
+        currentDir = dirname11(currentDir);
       } else {
         break;
       }
@@ -42393,16 +42625,16 @@ async function removeInstallations(installations, options) {
           await import_fs_extra35.remove(filePath);
           removedCount++;
           logger.debug(`Removed: ${item.path}`);
-          cleanedDirs += await cleanupEmptyDirectories(filePath, installation.path);
+          cleanedDirs += await cleanupEmptyDirectories2(filePath, installation.path);
         }
       }
       if (options.kit && analysis.remainingKits.length > 0) {
         await ManifestWriter.removeKitFromManifest(installation.path, options.kit);
       }
       try {
-        const remaining = readdirSync2(installation.path);
+        const remaining = readdirSync3(installation.path);
         if (remaining.length === 0) {
-          rmSync2(installation.path, { recursive: true });
+          rmSync4(installation.path, { recursive: true });
           logger.debug(`Removed empty installation directory: ${installation.path}`);
         }
       } catch {}
@@ -42706,7 +42938,7 @@ var import_fs_extra36 = __toESM(require_lib(), 1);
 // package.json
 var package_default = {
   name: "claudekit-cli",
-  version: "3.26.0",
+  version: "3.27.0",
   description: "CLI tool for bootstrapping and updating ClaudeKit projects",
   type: "module",
   repository: {
@@ -43184,7 +43416,7 @@ function registerCommands(cli) {
 }
 
 // src/cli/version-display.ts
-import { existsSync as existsSync20, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync21, readFileSync as readFileSync7 } from "node:fs";
 import { join as join77 } from "node:path";
 
 // src/domains/versioning/checking/version-utils.ts
@@ -43210,8 +43442,8 @@ init_types2();
 
 // src/domains/versioning/version-cache.ts
 init_logger();
-import { existsSync as existsSync19 } from "node:fs";
-import { mkdir as mkdir22, readFile as readFile26, writeFile as writeFile22 } from "node:fs/promises";
+import { existsSync as existsSync20 } from "node:fs";
+import { mkdir as mkdir22, readFile as readFile27, writeFile as writeFile23 } from "node:fs/promises";
 import { join as join76 } from "node:path";
 class VersionCacheManager {
   static CACHE_FILENAME = "version-check.json";
@@ -43223,11 +43455,11 @@ class VersionCacheManager {
   static async load() {
     const cacheFile = VersionCacheManager.getCacheFile();
     try {
-      if (!existsSync19(cacheFile)) {
+      if (!existsSync20(cacheFile)) {
         logger.debug("Version check cache not found");
         return null;
       }
-      const content = await readFile26(cacheFile, "utf-8");
+      const content = await readFile27(cacheFile, "utf-8");
       const cache2 = JSON.parse(content);
       if (!cache2.lastCheck || !cache2.currentVersion || !cache2.latestVersion) {
         logger.debug("Invalid cache structure, ignoring");
@@ -43244,10 +43476,10 @@ class VersionCacheManager {
     const cacheFile = VersionCacheManager.getCacheFile();
     const cacheDir = PathResolver.getCacheDir(false);
     try {
-      if (!existsSync19(cacheDir)) {
+      if (!existsSync20(cacheDir)) {
         await mkdir22(cacheDir, { recursive: true, mode: 448 });
       }
-      await writeFile22(cacheFile, JSON.stringify(cache2, null, 2), "utf-8");
+      await writeFile23(cacheFile, JSON.stringify(cache2, null, 2), "utf-8");
       logger.debug(`Version check cache saved to ${cacheFile}`);
     } catch (error) {
       logger.debug(`Failed to save version check cache: ${error}`);
@@ -43266,7 +43498,7 @@ class VersionCacheManager {
   static async clear() {
     const cacheFile = VersionCacheManager.getCacheFile();
     try {
-      if (existsSync19(cacheFile)) {
+      if (existsSync20(cacheFile)) {
         const fs14 = await import("node:fs/promises");
         await fs14.unlink(cacheFile);
         logger.debug("Version check cache cleared");
@@ -43489,7 +43721,7 @@ async function displayVersion() {
   const prefix = PathResolver.getPathPrefix(false);
   const localMetadataPath = prefix ? join77(process.cwd(), prefix, "metadata.json") : join77(process.cwd(), "metadata.json");
   const isLocalSameAsGlobal = localMetadataPath === globalMetadataPath;
-  if (!isLocalSameAsGlobal && existsSync20(localMetadataPath)) {
+  if (!isLocalSameAsGlobal && existsSync21(localMetadataPath)) {
     try {
       const rawMetadata = JSON.parse(readFileSync7(localMetadataPath, "utf-8"));
       const metadata = MetadataSchema.parse(rawMetadata);
@@ -43503,7 +43735,7 @@ async function displayVersion() {
       logger.verbose("Failed to parse local metadata.json", { error });
     }
   }
-  if (existsSync20(globalMetadataPath)) {
+  if (existsSync21(globalMetadataPath)) {
     try {
       const rawMetadata = JSON.parse(readFileSync7(globalMetadataPath, "utf-8"));
       const metadata = MetadataSchema.parse(rawMetadata);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claudekit-cli",
-	"version": "3.26.0",
+	"version": "3.27.0",
 	"description": "CLI tool for bootstrapping and updating ClaudeKit projects",
 	"type": "module",
 	"repository": {