@luquimbo/bi-superpowers 3.1.1 → 4.1.0

package/bin/cli.js

@@ -1,21 +1,22 @@
 #!/usr/bin/env node
 
 /**
- * BI Agent Superpowers - Command Line Interface
+ * BI Agent Superpowers — Command Line Interface
  * ==============================================
  *
- * This is the main entry point for the BI Agent Superpowers CLI tool.
- * It provides commands to initialize, configure, and manage AI-powered
- * assistance for Power BI, Fabric, and Excel development.
+ * Main entry point for the `super` CLI. Provides commands to install
+ * skills and MCP servers into AI coding agents, and to generate the
+ * native Claude Code plugin into a project.
  *
  * Architecture:
- * - Single Source of Truth: Skills are defined ONCE in src/content/skills/
- *   and generated for the Claude Code plugin.
- * - Supports: Claude Code, 1code.dev, Claude Desktop (via MCPB).
+ * - Skills are authored once in src/content/skills/ and copied out to
+ *   each supported agent by `super install`.
+ * - `super kickoff` generates a full Claude Code plugin tree in a
+ *   user project (skills + commands + MCP config).
+ * - `super recharge` regenerates that plugin after local edits.
  *
- * Licensing:
- * - Open source (MIT) — no license activation required
- * - All skills and library content ship with the npm package
+ * Supported agents: Claude Code, GitHub Copilot, Codex, Gemini CLI, Kilo Code.
+ * License: MIT. This project is fully open source — no activation, no keys.
  *
  * @module cli
  * @author Lucas Sanchez (@luquimbo)
@@ -27,114 +28,124 @@ const path = require('path');
 const { execSync } = require('child_process');
 const { loadSkills } = require('./lib/skills');
 
-// Import lib modules (extracted from cli.js for better organization)
+// Background update check. update-notifier spawns a detached child process
+// that fetches the latest version from npm and caches it; the banner that
+// `notify()` schedules is printed at process exit, so this is zero-latency
+// on the command path. Errors are swallowed silently — the CLI must not
+// break because of a failed update check.
+let _updateNotifierNotify = null;
+try {
+  const updateNotifier = require('update-notifier');
+  const pkg = require('../package.json');
+  const notifier = updateNotifier({
+    pkg,
+    updateCheckInterval: 1000 * 60 * 60 * 24, // 24h
+    shouldNotifyInNpmScript: false,
+  });
+  _updateNotifierNotify = () =>
+    notifier.notify({
+      defer: true,
+      isGlobal: true,
+      message:
+        'Update available {currentVersion} → {latestVersion}\n' +
+        'Run {updateCommand} to update,\n' +
+        'then `super install --yes` to propagate the new skills.',
+    });
+} catch (_) {
+  // update-notifier not available during npm install phase, or network
+  // probe failed — skip silently.
+}
+
+// Optional lib import — may not be available during npm install phase.
 let generators;
 try {
   generators = require('./lib/generators');
-} catch (e) {
-  // Modules may not be available during npm install phase
+} catch (_) {
+  // Silent fallback; commands will report a useful error when invoked.
 }
 
-// Import command modules - these provide the xray, checkup, scan, sentinel, and mcp-setup commands
-// Wrapped in try-catch because they may not be available during initial npm install
-let searchCommand, lintCommand, diffCommand, watchCommand, mcpSetupCommand, tui;
-let setupCommand, addCommand, pullCommand, pushCommand, syncProfileCommand, syncSourceCommand;
-let changelogCommand, buildDesktopCommand, installCommand;
+// Optional command imports — each module may fail to load during npm
+// install before dependencies are wired up. The CLI still renders `help`
+// and `version` because those are hoisted, module-free functions.
+let lintCommand;
+let diffCommand;
+let watchCommand;
+let mcpSetupCommand;
+let buildDesktopCommand;
+let installCommand;
+let tui;
 try {
-  searchCommand = require('./commands/search'); // Fuzzy search across library content
-  lintCommand = require('./commands/lint'); // Skill file validation
-  diffCommand = require('./commands/diff'); // Compare source vs generated configs
-  watchCommand = require('./commands/watch'); // Auto-regenerate on file changes
+  lintCommand = require('./commands/lint'); // checkup: skill file validation
+  diffCommand = require('./commands/diff'); // scan: diff source vs generated
+  watchCommand = require('./commands/watch'); // sentinel: watch + auto regen
   mcpSetupCommand = require('./commands/mcp-setup'); // MCP server configuration
-  tui = require('./utils/tui'); // Terminal UI helpers (colors, tables, etc.)
-
-  // Repo multi-project commands (v3)
-  setupCommand = require('./commands/setup'); // Onboarding wizard for bi-repo
-  addCommand = require('./commands/add'); // Add project to repo
-  pullCommand = require('./commands/pull'); // Pull changes from original file
-  pushCommand = require('./commands/push'); // Push changes to original file
-  syncProfileCommand = require('./commands/sync-profile'); // Sync snippets to profile
-  syncSourceCommand = require('./commands/sync-source'); // Bidirectional sync
-  changelogCommand = require('./commands/changelog'); // Generate changelog from Git
-  buildDesktopCommand = require('./commands/build-desktop'); // Build MCPB for Claude Desktop
-  installCommand = require('./commands/install'); // Multi-agent skill installer
-} catch (e) {
-  // Silent fail - commands may not be available during npm install phase
-  // This is expected behavior, not an error condition
+  buildDesktopCommand = require('./commands/build-desktop'); // .mcpb for Claude Desktop
+  installCommand = require('./commands/install'); // multi-agent skill + MCP installer
+  tui = require('./utils/tui'); // colors, tables, boxes for CLI output
+} catch (_) {
+  // Expected during `npm install` — modules become available after deps are linked.
 }
 
 // ============================================
 // CONFIGURATION CONSTANTS
 // ============================================
 
-/** Package version from package.json */
+/** Package version (read from package.json at runtime) */
 const VERSION = require('../package.json').version;
 
-/** Dynamic skill/command counts from the plugin generator (avoids hardcoding) */
-let COMMAND_COUNT = 11;
-let TOTAL_SKILL_COUNT = 24;
+/**
+ * Skill and command counts used by the help text and dry-run previews.
+ * Pulled dynamically from the generator so we never hardcode outdated totals.
+ */
+let COMMAND_COUNT = 0;
+let TOTAL_SKILL_COUNT = 0;
 try {
   const { COMMAND_SKILLS, REFERENCE_SKILLS } = require('./lib/generators/claude-plugin');
   COMMAND_COUNT = COMMAND_SKILLS.size;
   TOTAL_SKILL_COUNT = COMMAND_SKILLS.size + REFERENCE_SKILLS.size;
 } catch (_) {
-  // Fallback to defaults during npm install phase
+  // Fallback during npm install phase — values stay at 0 until the module loads.
 }
 
-/** Directory where the npm package is installed */
+/** Absolute path to the installed package directory (one level above bin/) */
 const PACKAGE_DIR = path.dirname(__dirname);
 
-/** Directory containing skill source files (.md) */
+/** Directory containing the authoring source for each skill */
 const SKILLS_DIR = path.join(PACKAGE_DIR, 'src', 'content', 'skills');
 
-/** Directory containing code snippets, templates, and themes */
-const LIBRARY_DIR = path.join(PACKAGE_DIR, 'library');
-
-/** Project-local config file name (stores tool selections) */
+/** Project-local config file name used by kickoff/recharge */
 const CONFIG_FILE = '.bi-superpowers.json';
 
-/** npm package name for update commands */
+/** npm package name for the upgrade command */
 const PACKAGE_NAME = '@luquimbo/bi-superpowers';
+
+/** Default tool set generated by kickoff (currently only the Claude Code plugin) */
 const DEFAULT_TOOLS = ['claude-plugin'];
 
-/**
- * AI Tools Configuration - uses generators from lib/generators module
- * Falls back to empty object if module not loaded
- */
+/** Generator registry (populated from lib/generators if available) */
 const AI_TOOLS = generators ? generators.AI_TOOLS : {};
 
-/**
- * Command Routing Map
- *
- * Maps CLI command names to their handler functions.
- * Supports both branded names (kickoff, recharge) and legacy names (init, sync)
- * for backward compatibility.
- *
- * Command Categories:
- * - Core: Basic info commands (help, version, about, status)
- * - Setup: Project initialization and configuration (kickoff, recharge, upgrade)
- * - Developer: Advanced tools for content management (xray, checkup, scan, sentinel, powers)
- * - Legacy: Old command names maintained for backward compatibility
- */
-// Commands are registered in two phases to avoid TDZ (temporal dead zone) errors.
-// Phase 1: hoisted function declarations (showHelp, initProject, etc.) go directly
-// into the object literal below — safe because `function` declarations hoist.
-// Phase 2: wrapper-based commands that depend on `createCommandWrapper` (defined
-// further down in the file) are attached imperatively after that function exists.
-// See the `commands.xray = runSearch;` block after the wrapper `const`s.
+// ============================================
+// COMMAND ROUTING
+// ============================================
+// Commands are registered in two phases to avoid temporal-dead-zone errors.
+// Phase 1: hoisted function declarations (help, version, about, kickoff...)
+//          go directly into the object literal below.
+// Phase 2: wrapper-based commands that depend on createCommandWrapper
+//          (defined further below) are attached imperatively.
 const commands = {
-  // Core commands - basic info (hoisted functions, safe here)
+  // Core commands — hoisted functions, safe to reference here.
   help: showHelp,
   version: showVersion,
   about: showInfo,
 
-  // Setup & sync - project configuration (hoisted functions, safe here)
+  // Primary flow — also hoisted functions.
   kickoff: initProject,
   recharge: syncProject,
   upgrade: updatePackage,
   powers: listAgents,
 
-  // Legacy aliases (hoisted functions, safe here)
+  // Legacy aliases kept for backwards compatibility.
   init: initProject,
   sync: syncProject,
   update: updatePackage,
@@ -143,12 +154,20 @@ const commands = {
 };
 
 /**
- * Main entry point - parses CLI arguments and routes to appropriate command
+ * Main entry point — parses CLI arguments and routes to the handler.
  */
 function main() {
   const args = process.argv.slice(2);
   const command = args[0] || 'help';
 
+  // Schedule the update-notifier banner to print at process exit. Only fire
+  // for "normal" commands — skipping machine-readable and ultra-hot paths so
+  // tools that parse super output don't get surprised by the banner.
+  const SKIP_NOTIFY_COMMANDS = new Set(['version', 'help', 'about', 'info']);
+  if (_updateNotifierNotify && !SKIP_NOTIFY_COMMANDS.has(command)) {
+    _updateNotifierNotify();
+  }
+
   if (commands[command]) {
     commands[command](args.slice(1));
   } else {
@@ -163,67 +182,47 @@ function showHelp() {
 BI Agent Superpowers v${VERSION}
 ================================
 
-Claude Code plugin for Power BI, Fabric & Excel development.
+Open-source toolkit for Power BI Desktop development across 5 AI coding agents:
+Claude Code · GitHub Copilot · Codex · Gemini CLI · Kilo Code.
 
 Quick Start:
-  super kickoff                  # Genera el plugin en tu proyecto
-  claude --plugin-dir .          # Abrí Claude Code con el plugin
+  super install              # Install skills + MCPs for all your AI agents
+  super kickoff              # Generate the Claude Code plugin in a project
 
 Usage:
   super <command> [options]
 
-Primary commands (Claude Code):
-  kickoff [path]    Genera el plugin completo (skills + commands + MCPs)
-  recharge [path]   Regenerá el plugin tras editar skills fuente
-  build-desktop     Buildea la extensión .mcpb para Claude Desktop
-  mcp-setup         Configurá los MCP servers de Microsoft
-  powers            Listá skills y recursos disponibles
-  upgrade           Actualizá a la última versión
-  about             Info de la instalación
-  help              Mostrá esta ayuda
+Primary commands:
+  install           Install the 4 skills + 2 MCPs across your AI agents
+  kickoff [path]    Generate the full Claude Code plugin in a project
+  recharge [path]   Regenerate the plugin after editing source skills
+  build-desktop     Build the .mcpb extension for Claude Desktop
+  mcp-setup         Configure the official Microsoft MCP servers
+  powers            List available skills and MCPs
+  upgrade           Update to the latest version on npm
+  about             Show installation info
+  help              Show this help
 
 Developer tools:
-  xray <query>      Buscá snippets y contenido de la biblioteca
-  checkup [file]    Validá archivos de skills
-  scan              Diff entre source y generated
-  sentinel          Watch y auto-regenerá
-
-Repo Multi-Proyecto:
-  setup             Creá tu bi-repo para version control
-  add <file>        Agregá un proyecto .pbix/.xlsx al repo
-  pull [project]    Pull changes desde el archivo original
-  push [project]    Push changes al archivo original
-  sync-source       Bidirectional sync (detecta cuál es más nuevo)
-  sync-profile      Sync snippets al profile base
-
-Experimental (solo skills, sin commands ni MCPs):
-  install           Instalá skills en otros agentes AI (Copilot, Codex, Gemini, Kilo)
+  checkup [file]    Lint/validate skill source files
+  scan              Diff between source skills and generated plugin
+  sentinel          Watch skill sources and auto-regenerate
 
 Options:
-  --dry-run         Preview de cambios sin escribir archivos (kickoff, recharge)
+  --dry-run         Preview changes without writing files (kickoff, recharge)
 
 Examples:
-  super kickoff                  # Inicializá el plugin en el directorio actual
-  super kickoff ./my-project     # Inicializá en un directorio específico
-  super kickoff --dry-run        # Preview de qué archivos se crearían
-  super recharge                 # Regenerá el plugin tras editar skills
-  super build-desktop            # Buildeá .mcpb para Claude Desktop
-  super mcp-setup                # Configurá los MCPs de Microsoft
-  super powers                   # Mostrá todos los skills disponibles
-  claude --plugin-dir .          # Corré Claude Code con el plugin
-
-  super install                  # [Experimental] Instalá skills en otros agentes
-  super install -a claude-code   # Instalá solo para un agente específico
-
-Repo Multi-Proyecto:
-  super setup                    # Create your bi-repo (first time)
-  super add "Sales.pbix"         # Add project to repo
-  super pull                     # Pull changes from original
-  super push                     # Push changes to original
-  super sync-source              # Auto-detect and sync
-  super sync-profile             # Save snippets to profile
-
-Open source — MIT licensed
+  super install                    # Interactive installer for all agents
+  super install --all --yes        # Non-interactive install for every agent
+  super install -a claude-code     # Install only for Claude Code
+  super kickoff                    # Initialize plugin in current directory
+  super kickoff ./my-project       # Initialize in a specific directory
+  super kickoff --dry-run          # Preview what would be created
+  super recharge                   # Regenerate plugin after editing skills
+  super build-desktop              # Build .mcpb for Claude Desktop
+  super mcp-setup                  # Configure the local Power BI Modeling MCP
+
+Open source — MIT licensed.
 Documentation: https://github.com/luquimbo/bi-superpowers
 `);
 }
@@ -235,11 +234,11 @@ function showVersion() {
 function showInfo() {
   const skillCount = getSkillFiles().length;
   const aiToolsList = Object.entries(AI_TOOLS)
-    .map(([_k, v]) => `  - ${v.name}`)
+    .map(([, v]) => `  - ${v.name}`)
     .join('\n');
 
   console.log(`
-BI Agent Superpowers - Installation Info
+BI Agent Superpowers — Installation Info
 ========================================
 
 Version:        ${VERSION}
@@ -248,62 +247,41 @@ Package dir:    ${PACKAGE_DIR}
 Skills:         ${skillCount} available
 License:        MIT (open source)
 
-Architecture:   Single Source of Truth
-                Skills defined once, generated for the Claude Code plugin
+Supported AI agents:
+  - Claude Code        (native plugin + MCP)
+  - GitHub Copilot     (agent skills + MCP)
+  - Codex (OpenAI)     (agent skills + MCP)
+  - Gemini CLI         (agent skills + MCP)
+  - Kilo Code          (agent skills + MCP)
 
-Compatible with:
-  - Claude Code (plugin)
-  - GitHub Copilot (agent skills)
-  - Codex (OpenAI)
-  - Gemini CLI
-  - Kilo Code
-  - Claude Desktop (via MCPB extension)
-
-Plugin Generators:
+Plugin generators:
 ${aiToolsList}
 
 GitHub: https://github.com/luquimbo/bi-superpowers
 `);
 }
 
-// ============================================
-// LICENSE MANAGEMENT
-// ============================================
 // ============================================
 // SKILL FILE MANAGEMENT
 // ============================================
-// Functions for reading and parsing skill definition files.
-// Skills are markdown files in src/content/skills/ that define
-// AI assistant behaviors, triggers, and code patterns.
 
 /**
- * Get all skill files from the source directory
- *
- * Reads all .md files from the skills directory and returns their metadata.
- * Each skill file contains:
- * - Trigger keywords that activate the skill
- * - Identity/role description for the AI
- * - Mandatory rules and constraints
- * - Code examples and patterns
- *
- * @returns {Array<{name: string, path: string, content: string}>} Array of skill objects
+ * Load all skill source files from the package.
+ * @returns {Array<{name: string, path: string, content: string}>}
  */
 function getSkillFiles() {
-  return loadSkills({
-    packageDir: PACKAGE_DIR,
-    preferLocal: true,
-  });
+  return loadSkills({ packageDir: PACKAGE_DIR });
 }
 
 /**
- * Extract skill metadata from markdown content
- * Delegates to generators module if available
+ * Extract lightweight metadata (title, triggers, identity) from a skill's
+ * markdown content. Delegates to the generators module when available.
  */
 function parseSkillMetadata(content) {
   if (generators && generators.parseSkillMetadata) {
     return generators.parseSkillMetadata(content);
   }
-  // Fallback for when module not loaded
+  // Minimal fallback when the module isn't loaded yet.
   const metadata = { title: '', triggers: [], identity: '' };
   const titleMatch = content.match(/^#\s+(.+)/m);
   if (titleMatch) metadata.title = titleMatch[1];
@@ -311,23 +289,20 @@ function parseSkillMetadata(content) {
 }
 
 // ============================================
-// PROJECT INITIALIZATION
+// PROJECT INITIALIZATION (kickoff / recharge)
 // ============================================
-// Functions for setting up BI Agent Superpowers in a user's project.
-// This involves generating tool-specific config files and saving preferences.
 
 /**
- * Initialize project with interactive prompts (super kickoff)
+ * `super kickoff` — generate the Claude Code plugin in the target directory.
  *
- * This is the main setup wizard that:
- * 1. Generates config files for the Claude Code plugin in the target directory
- * 2. Saves the selected tools to .bi-superpowers.json
- * 3. Copies a default config.json template if none exists
+ * What it does:
+ *  1. Generates .claude-plugin/, .mcp.json, commands/, skills/ in the target.
+ *  2. Writes .bi-superpowers.json tracking tool selections.
+ *  3. Copies a default config.json template if none exists yet.
  *
- * Supports --dry-run flag to preview changes without writing files.
+ * Supports --dry-run to preview without writing files.
  *
- * @param {string[]} args - Command line arguments
- * @param {string} [args[0]] - Target directory (defaults to cwd)
+ * @param {string[]} args - CLI arguments (first positional = target dir)
  */
 async function initProject(args) {
   const dryRun = hasDryRunFlag(args);
@@ -345,7 +320,6 @@ Initializing in: ${targetDir}
 Skills available: ${skills.length}
 `);
 
-  // Show dry-run notice
   if (dryRun) {
     if (tui) {
       tui.dryRunNotice();
@@ -373,13 +347,9 @@ Skills available: ${skills.length}
     return;
   }
 
-  // Save selected tools to config
   saveToolConfig(targetDir, selectedTools);
-
-  // Ensure project-level config.json exists (used as AI preferences/context)
   ensureProjectConfigJson(targetDir);
 
-  // Generate configs for selected tools
   console.log('');
   for (const tool of selectedTools) {
     await generateForTool(tool, targetDir, skills);
@@ -389,20 +359,15 @@ Skills available: ${skills.length}
 }
 
 /**
- * Sync project - regenerate configs without prompts (super recharge)
- *
- * Regenerates the Claude Code plugin and any configured legacy adapters.
- * Uses the saved tool preferences from .bi-superpowers.json.
+ * `super recharge` — regenerate the Claude Code plugin without prompts.
  *
- * Use this command after:
- * - Editing skill files in src/content/skills/
- * - Updating the package to a new version
- * - Adding new AI tools to your project
+ * Re-reads the saved tool preferences from .bi-superpowers.json (or falls
+ * back to the default toolset) and regenerates everything. Useful after:
+ *  - editing files in src/content/skills/
+ *  - bumping the package version
+ *  - adding new supported tools
  *
- * Supports --dry-run flag to preview changes without writing files.
- *
- * @param {string[]} args - Command line arguments
- * @param {string} [args[0]] - Target directory (defaults to cwd)
+ * @param {string[]} args - CLI arguments (first positional = target dir)
  */
 async function syncProject(args) {
   const dryRun = hasDryRunFlag(args);
@@ -412,12 +377,11 @@ async function syncProject(args) {
   const skills = getSkillFiles();
 
   console.log(`
-BI Agent Superpowers - Sync
+BI Agent Superpowers — Sync
 ===========================
 Regenerating configs from ${skills.length} skills...
 `);
 
-  // Show dry-run notice
   if (dryRun) {
     if (tui) {
       tui.dryRunNotice();
@@ -429,12 +393,10 @@ Regenerating configs from ${skills.length} skills...
     }
   }
 
-  // Read saved config or default to plugin only
   const config = loadToolConfig(targetDir);
   const selectedTools = ensurePluginTool(config.tools || [...DEFAULT_TOOLS]);
 
   if (dryRun) {
-    // Preview what would be regenerated
     console.log('[DRY RUN] Would regenerate the following files:\n');
     previewGeneration(targetDir, selectedTools, skills);
     console.log('\nRun without --dry-run to apply changes.');
@@ -446,18 +408,16 @@ Regenerating configs from ${skills.length} skills...
   }
 
   console.log(`
-Done! Plugin regenerated for: ${selectedTools.map((t) => AI_TOOLS[t].name).join(', ')}
+Done. Plugin regenerated for: ${selectedTools.map((t) => AI_TOOLS[t].name).join(', ')}
 
-If you modified skills in src/content/skills/,
-your Claude Code plugin is now updated.
+If you modified skills in src/content/skills/, your Claude Code plugin is now up to date.
 
-Tip: Run 'super build-desktop' to rebuild the Claude Desktop extension.
+Tip: run 'super build-desktop' to rebuild the Claude Desktop MCPB extension.
 `);
 }
 
 /**
- * Preview what files would be generated (for dry-run mode)
- * Delegates to the generators module
+ * Delegate to the generators module to preview what would be written.
  */
 function previewGeneration(targetDir, tools, skills) {
   if (generators) {
@@ -466,9 +426,8 @@ function previewGeneration(targetDir, tools, skills) {
 }
 
 /**
- * Save tool configuration to project directory
- * @param {string} targetDir - Project directory path
- * @param {string[]} tools - Array of selected AI tool IDs
+ * Ensure the tool list always includes the Claude Code plugin as the
+ * primary target. Deduplicates and preserves order.
  */
 function ensurePluginTool(tools = []) {
   const normalized = Array.from(new Set((tools || []).filter(Boolean)));
@@ -479,15 +438,13 @@ function ensurePluginTool(tools = []) {
 }
 
 /**
- * Resolve generation options for a target directory.
- *
- * @param {string} targetDir - Target project directory
- * @returns {Object} Options passed into generators
+ * Build the options object passed into individual generators.
+ * If the target directory has its own local `library/` folder, skills
+ * will reference that; otherwise they reference the library bundled
+ * inside the installed npm package.
  */
 function getGenerationOptions(targetDir) {
   const usePluginRootLauncher = path.resolve(targetDir) === PACKAGE_DIR;
-  // If the project has a local library/ folder, use it; otherwise point to
-  // the library bundled inside the installed npm package.
   const libraryPrefix = fs.existsSync(path.join(targetDir, 'library'))
     ? 'library'
     : path.join(PACKAGE_DIR, 'library');
@@ -500,6 +457,9 @@ function getGenerationOptions(targetDir) {
   };
 }
 
+/**
+ * Write .bi-superpowers.json with the current tool selection and metadata.
+ */
 function saveToolConfig(targetDir, tools) {
   const configPath = path.join(targetDir, CONFIG_FILE);
   const normalizedTools = ensurePluginTool(tools);
@@ -509,7 +469,6 @@ function saveToolConfig(targetDir, tools) {
       name: 'bi-superpowers',
       enabled: true,
     },
-    legacyTools: normalizedTools.filter((tool) => tool !== 'claude-plugin'),
     version: VERSION,
     lastSync: new Date().toISOString(),
   };
@@ -517,16 +476,13 @@ function saveToolConfig(targetDir, tools) {
 }
 
 /**
- * Preview project-level config.json creation (for dry-run mode)
- * This file is used by AI assistants as preferences/context, not by the CLI runtime.
- * @param {string} targetDir - Project directory path
+ * Log what config.json the kickoff would create (dry-run only).
  */
 function previewProjectConfigJson(targetDir) {
   const projectConfigPath = path.join(targetDir, 'config.json');
   if (fs.existsSync(projectConfigPath)) {
     return;
   }
-
   if (tui) {
     tui.info(`Would create: ${tui.formatPath(projectConfigPath)}`);
   } else {
@@ -535,9 +491,8 @@ function previewProjectConfigJson(targetDir) {
 }
 
 /**
- * Ensure project-level config.json exists
- * Copies the package template config.json into the project directory if missing.
- * @param {string} targetDir - Project directory path
+ * Copy the package's config.json template into the target directory
+ * unless one already exists there.
  * @returns {{created: boolean, path: string, reason?: string, error?: string}}
  */
 function ensureProjectConfigJson(targetDir) {
@@ -566,9 +521,8 @@ function ensureProjectConfigJson(targetDir) {
 }
 
 /**
- * Load tool configuration from project directory
- * @param {string} targetDir - Project directory path
- * @returns {Object} Configuration object or empty object if not found
+ * Load the previously saved tool selection from .bi-superpowers.json.
+ * Falls back to the default toolset if the file is missing or invalid.
  */
 function loadToolConfig(targetDir) {
   const configPath = path.join(targetDir, CONFIG_FILE);
@@ -576,31 +530,22 @@ function loadToolConfig(targetDir) {
     try {
       const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
       config.tools = ensurePluginTool(config.tools || []);
-      config.legacyTools = config.tools.filter((tool) => tool !== 'claude-plugin');
       if (!config.plugin) {
-        config.plugin = {
-          name: 'bi-superpowers',
-          enabled: true,
-        };
+        config.plugin = { name: 'bi-superpowers', enabled: true };
       }
       return config;
-    } catch (e) {
+    } catch (_) {
       return {};
     }
   }
   return {
     tools: [...DEFAULT_TOOLS],
-    legacyTools: [],
-    plugin: {
-      name: 'bi-superpowers',
-      enabled: true,
-    },
+    plugin: { name: 'bi-superpowers', enabled: true },
   };
 }
 
 /**
- * Generate config for a specific AI tool
- * Delegates to the tool-specific generator from lib/generators module
+ * Dispatch to the tool-specific generator.
  */
 async function generateForTool(tool, targetDir, skills) {
   if (generators) {
@@ -615,10 +560,9 @@ function showCompletionMessage(targetDir, tools, skillCount) {
 ════════════════════════════════════════════════════════════
 
   Skills:     ${skillCount} skills generated
-  Library:    ${LIBRARY_DIR}
 
 ────────────────────────────────────────────────────────────
-  CLAUDE CODE / 1CODE.DEV
+  CLAUDE CODE
 ────────────────────────────────────────────────────────────
 
   Plugin files:
@@ -643,34 +587,90 @@ function showCompletionMessage(targetDir, tools, skillCount) {
 
 ────────────────────────────────────────────────────────────
 
-  Regenerate after changes:  super recharge
-  Free models (OpenRouter):  See docs/openrouter-free-models.md
+  Regenerate after edits:  super recharge
 
 ════════════════════════════════════════════════════════════
 `);
 }
 
 /**
- * Update the package to the latest version using detected package manager
+ * Detect the package manager the user ran from the npm_config_user_agent.
+ * Returns the pm name ('npm', 'pnpm', 'yarn', 'bun') and the install command
+ * string appropriate for a global install to @latest.
+ *
+ * Exported (via module.exports) so tests can exercise the detection without
+ * spawning a real install.
  */
-function updatePackage() {
-  console.log(`Updating ${PACKAGE_NAME}...\n`);
+function getUpgradeCommand(userAgent) {
+  const agent = userAgent || '';
+  let pm = 'npm';
+  if (agent.includes('pnpm')) pm = 'pnpm';
+  else if (agent.includes('yarn')) pm = 'yarn';
+  else if (agent.includes('bun')) pm = 'bun';
+
+  const cmd =
+    pm === 'yarn'
+      ? `yarn global add ${PACKAGE_NAME}@latest`
+      : `${pm} install -g ${PACKAGE_NAME}@latest`;
+
+  return { pm, cmd };
+}
 
+/**
+ * `super upgrade` — reinstall the package at the latest version.
+ *
+ * After the reinstall, prints a "next steps" block with both update paths
+ * (Claude Code `/plugin update` vs npm-based `super install --yes`) so
+ * users know how to propagate the new skills into their agents. We
+ * intentionally don't auto-chain into `super install`:
+ *   - Claude Code users who installed via the plugin marketplace refresh
+ *     from inside Claude Code (`/plugin update bi-superpowers`), they don't
+ *     need `super install`.
+ *   - npm users want to be able to opt out of re-propagation (e.g. testing
+ *     a version before rolling it across all agents).
+ */
+/**
+ * Wipe ~/.bi-superpowers/update-state.json after a successful upgrade so
+ * the new version starts with a clean cache (no stale snooze TTL, no
+ * cached "latest" from the previous version). Best-effort: any failure
+ * is swallowed — the reset is a convenience, not a correctness gate.
+ *
+ * Separate function + exported so tests can exercise it without spawning
+ * a real `super upgrade`.
+ */
+function resetUpdateCheckStateAfterUpgrade(homeDir) {
   try {
-    const userAgent = process.env.npm_config_user_agent || '';
-    let pm = 'npm';
-    if (userAgent.includes('pnpm')) pm = 'pnpm';
-    else if (userAgent.includes('yarn')) pm = 'yarn';
-    else if (userAgent.includes('bun')) pm = 'bun';
+    const { resetState } = require('./commands/update-check');
+    resetState(path.join(homeDir, '.bi-superpowers'));
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
 
-    const cmd =
-      pm === 'yarn'
-        ? `yarn global add ${PACKAGE_NAME}@latest`
-        : `${pm} install -g ${PACKAGE_NAME}@latest`;
+function updatePackage() {
+  console.log(`Updating ${PACKAGE_NAME}...\n`);
 
+  try {
+    const { cmd } = getUpgradeCommand(process.env.npm_config_user_agent);
     console.log(`Running: ${cmd}\n`);
     execSync(cmd, { stdio: 'inherit' });
-    console.log('\n✓ Update complete!');
+    console.log('\n✓ CLI upgraded.');
+
+    // Clear the update-check cache + snooze state so the newly-installed
+    // version gets a fresh read on next skill invocation.
+    resetUpdateCheckStateAfterUpgrade(require('os').homedir());
+
+    console.log('\nNext step — refresh the skills + MCPs in your agents:\n');
+    console.log('  Claude Code (installed via marketplace):');
+    console.log('    /plugin update bi-superpowers');
+    console.log('');
+    console.log('  Any other install path (npm + super install):');
+    console.log('    super install --yes');
+    console.log('');
+    console.log(
+      'If you only wanted the CLI updated (e.g. developing locally), you can skip the above.'
+    );
   } catch (error) {
     console.error('Update failed:', error.message);
     console.log(`\nTry manually: npm install -g ${PACKAGE_NAME}@latest`);
@@ -678,59 +678,32 @@ function updatePackage() {
   }
 }
 
+/**
+ * `super powers` — list the available skills (and their titles).
+ */
 function listAgents() {
   const skills = getSkillFiles();
 
   console.log(`
-BI Agent Superpowers - Skills & Resources
-=========================================
+BI Agent Superpowers — Skills
+=============================
 Single Source of Truth: ${skills.length} skills (open source)
 `);
 
-  console.log('Skills (source content for the plugin and optional adapters):');
+  console.log('Skills:');
   for (const skill of skills) {
     const meta = parseSkillMetadata(skill.content);
     console.log(`  /${skill.name.padEnd(20)} ${meta.title || ''}`);
   }
   console.log('');
 
-  // List snippets
-  const snippetsDir = path.join(LIBRARY_DIR, 'snippets');
-  if (fs.existsSync(snippetsDir)) {
-    console.log('Snippets:');
-    fs.readdirSync(snippetsDir).forEach((category) => {
-      const categoryPath = path.join(snippetsDir, category);
-      try {
-        if (fs.statSync(categoryPath).isDirectory()) {
-          const count = fs.readdirSync(categoryPath).filter((f) => f.endsWith('.md')).length;
-          console.log(`  📝 ${category} (${count} patterns)`);
-        }
-      } catch (e) {
-        // Skip directories that can't be read
-      }
-    });
-    console.log('');
-  }
-
-  // List themes
-  const themesDir = path.join(LIBRARY_DIR, 'themes', 'power-bi');
-  if (fs.existsSync(themesDir)) {
-    console.log('Themes:');
-    fs.readdirSync(themesDir).forEach((file) => {
-      if (file.endsWith('.json')) {
-        console.log(`  🎨 ${file.replace('.json', '')}`);
-      }
-    });
-    console.log('');
-  }
-
-  console.log('Supported AI Tools:');
-  Object.entries(AI_TOOLS).forEach(([, config]) => {
-    console.log(`  • ${config.name}`);
+  console.log('Supported AI tools:');
+  Object.entries(AI_TOOLS).forEach(([, cfg]) => {
+    console.log(`  • ${cfg.name}`);
   });
   console.log('');
 
-  console.log("Run 'bi-superpowers recharge' to regenerate configs after editing skills.");
+  console.log("Run 'super recharge' to regenerate configs after editing skills.");
 }
 
 // ============================================
@@ -738,24 +711,19 @@ Single Source of Truth: ${skills.length} skills (open source)
 // ============================================
 
 /**
- * Get configuration object for commands
+ * Shared config object passed into every command module.
  */
 function getCommandConfig() {
   return {
     skillsDir: SKILLS_DIR,
-    libraryDir: LIBRARY_DIR,
     packageDir: PACKAGE_DIR,
     version: VERSION,
   };
 }
 
 /**
- * Create a command wrapper with error handling
- * Factory pattern to reduce boilerplate in command handlers
- *
- * @param {Function|null} commandModule - The command module function
- * @param {string} commandName - Display name for error messages
- * @returns {Function} Wrapped command handler
+ * Factory that wraps a command module with a consistent "missing module"
+ * error so every non-core command fails the same way during `npm install`.
  */
 function createCommandWrapper(commandModule, commandName) {
   return (args) => {
@@ -767,44 +735,29 @@ function createCommandWrapper(commandModule, commandName) {
   };
 }
 
-// Command wrappers using factory pattern
-const runSearch = createCommandWrapper(searchCommand, 'Search');
+// Wrapper instances — created after createCommandWrapper is defined.
 const runLint = createCommandWrapper(lintCommand, 'Lint');
 const runDiff = createCommandWrapper(diffCommand, 'Diff');
 const runMcpSetup = createCommandWrapper(mcpSetupCommand, 'MCP setup');
-const runSetup = createCommandWrapper(setupCommand, 'Setup');
-const runAdd = createCommandWrapper(addCommand, 'Add');
-const runPull = createCommandWrapper(pullCommand, 'Pull');
-const runPush = createCommandWrapper(pushCommand, 'Push');
-const runSyncSource = createCommandWrapper(syncSourceCommand, 'Sync-source');
-const runSyncProfile = createCommandWrapper(syncProfileCommand, 'Sync-profile');
-const runChangelog = createCommandWrapper(changelogCommand, 'Changelog');
 const runBuildDesktop = createCommandWrapper(buildDesktopCommand, 'Build Desktop');
 const runInstall = createCommandWrapper(installCommand, 'Install');
 
-// Register commands that depend on createCommandWrapper (avoids TDZ in object literal)
+// Register wrapper-based commands into the command map (phase 2).
 commands.install = runInstall;
-commands.xray = runSearch;
 commands.checkup = runLint;
 commands.scan = runDiff;
 commands.sentinel = runWatch;
 commands['mcp-setup'] = runMcpSetup;
 commands.mcp = runMcpSetup;
 commands['build-desktop'] = runBuildDesktop;
-commands.setup = runSetup;
-commands.add = runAdd;
-commands.pull = runPull;
-commands.push = runPush;
-commands['sync-source'] = runSyncSource;
-commands['sync-profile'] = runSyncProfile;
-commands.changelog = runChangelog;
-commands.search = runSearch;
 commands.lint = runLint;
 commands.diff = runDiff;
 commands.watch = runWatch;
 
 /**
- * Run watch command (special case - needs additional context)
+ * `super sentinel` — watch skill sources and auto-regenerate the plugin.
+ * Needs extra context (a reference to the sync function) so it has its
+ * own wrapper instead of using createCommandWrapper.
  */
 function runWatch(args) {
   if (!watchCommand) {
@@ -812,14 +765,13 @@ function runWatch(args) {
     process.exit(1);
   }
 
-  // Create a reference to sync function for watch to use
   const cliModule = {
     syncProjectInternal: (targetDir, tools) => {
       const skills = getSkillFiles();
       for (const tool of tools) {
-        const config = AI_TOOLS[tool];
-        if (config && config.generate) {
-          config.generate(targetDir, skills, { packageDir: PACKAGE_DIR });
+        const cfg = AI_TOOLS[tool];
+        if (cfg && cfg.generate) {
+          cfg.generate(targetDir, skills, { packageDir: PACKAGE_DIR });
         }
       }
     },
@@ -829,14 +781,14 @@ function runWatch(args) {
 }
 
 /**
- * Check if --dry-run flag is present in args
+ * Check if --dry-run (or -n) is present in the argument list.
  */
 function hasDryRunFlag(args) {
   return args.includes('--dry-run') || args.includes('-n');
 }
 
 /**
- * Remove --dry-run flag from args
+ * Strip the --dry-run / -n flag from the argument list.
  */
 function removeDryRunFlag(args) {
   return args.filter((a) => a !== '--dry-run' && a !== '-n');
@@ -850,10 +802,14 @@ module.exports = {
   getSkillFiles,
   loadToolConfig,
   saveToolConfig,
+  getUpgradeCommand,
+  resetUpdateCheckStateAfterUpgrade,
   AI_TOOLS,
   SKILLS_DIR,
-  LIBRARY_DIR,
   VERSION,
 };
 
-main();
+// Only run main() when invoked as the binary (not when required from tests).
+if (require.main === module) {
+  main();
+}