@luquimbo/bi-superpowers 3.1.1 → 3.2.0

package/bin/commands/install.js

@@ -1,18 +1,28 @@
 /**
- * Install Command - Multi-agent skill installer
- * ===============================================
+ * Install Command — Multi-agent skill + MCP installer
+ * =====================================================
  *
- * Instala los skills de BI Agent Superpowers en los directorios
- * correctos para cada agente AI. Inspirado en el CLI `npx skills` de
- * Vercel Labs.
+ * Installs the bi-superpowers skills and Microsoft MCP servers into
+ * every supported AI coding agent:
+ *   - Claude Code
+ *   - GitHub Copilot
+ *   - Codex (OpenAI)
+ *   - Gemini CLI
+ *   - Kilo Code
  *
- * Los skills siempre se instalan a nivel de usuario (~/) para no
- * contaminar el repo del proyecto. El usuario los obtiene una vez
- * y los comparte con todos sus proyectos.
+ * Everything is installed at the user level (~/) so it applies across
+ * all projects without polluting any specific repo. Skills land in
+ * ~/.agents/skills/ (universal path) and each agent's own skill dir is
+ * symlinked to that universal copy. MCPs are written to each agent's
+ * expected config file in the format that agent requires (JSON for
+ * most, TOML for Codex) — see `lib/mcp-config.js` for details.
  *
- * Open source: todo el contenido ship gratis con el paquete npm.
+ * Fully open source (MIT). The user-facing messages are in Spanish to
+ * match the primary Spanish-speaking audience of the project; code
+ * comments and JSDoc stay in English so contributors from any language
+ * can work on the source.
  *
- * Uso:
+ * Usage:
  *   npx @luquimbo/bi-superpowers install
  *   super install
  *   super install --agent claude-code --agent codex
@@ -29,9 +39,10 @@ const { AGENTS, UNIVERSAL_DIR } = require('../lib/agents');
 const { writeMcpConfigForAgent } = require('../lib/mcp-config');
 
 /**
- * Detecta qué agentes están instalados revisando sus directorios de config.
- * @param {string} baseDir - Directorio base (home del usuario)
- * @returns {string[]} IDs de agentes detectados
+ * Detect which agents are installed by checking their config directories.
+ * Used in the interactive installer to pre-select the detected agents.
+ * @param {string} baseDir - Base directory to scan (typically the user's home)
+ * @returns {string[]} IDs of detected agents
  */
 function detectAgents(baseDir) {
   const detected = [];
@@ -46,7 +57,7 @@ function detectAgents(baseDir) {
 }
 
 /**
- * Crea una interface de readline para prompts interactivos.
+ * Create a readline interface for interactive prompts.
  */
 function createReadline() {
   return readline.createInterface({
@@ -56,7 +67,7 @@ function createReadline() {
 }
 
 /**
- * Envuelve una pregunta de readline en una Promise.
+ * Promise-wrapped readline question.
  */
 function prompt(rl, question) {
   return new Promise((resolve) => {
@@ -65,11 +76,11 @@ function prompt(rl, question) {
 }
 
 /**
- * Muestra una lista numerada y deja al usuario elegir múltiples items.
+ * Render a numbered multi-select list and wait for the user's choice.
  * @param {readline.Interface} rl
  * @param {Array<{id: string, name: string}>} items
- * @param {string[]} preselected - IDs preseleccionados
- * @returns {Promise<string[]>} IDs seleccionados
+ * @param {string[]} preselected - IDs that should default to selected
+ * @returns {Promise<string[]>} Selected IDs
  */
 async function selectMultiple(rl, items, preselected = []) {
   items.forEach((item, i) => {
@@ -77,8 +88,8 @@ async function selectMultiple(rl, items, preselected = []) {
     console.log(`  ${i + 1}) ${marker} ${item.name}`);
   });
   console.log();
-  console.log('  Ingresa números separados por comas (ej: 1,2,3)');
-  console.log('  Presiona Enter para los detectados, o "a" para todos');
+  console.log('  Ingresá números separados por comas (ej: 1,2,3)');
+  console.log('  Presioná Enter para los detectados, o "a" para todos');
 
   const answer = await prompt(rl, '\n  > ');
 
@@ -99,10 +110,10 @@ async function selectMultiple(rl, items, preselected = []) {
 }
 
 /**
- * Copia un directorio de skill recursivamente.
- * Los errores de fs se propagan al caller para manejo centralizado.
- * @param {string} srcDir - Directorio de skill fuente (contiene SKILL.md)
- * @param {string} destDir - Directorio destino
+ * Recursively copy a skill directory (SKILL.md + references/ + scripts/).
+ * Filesystem errors propagate to the caller for centralized handling.
+ * @param {string} srcDir - Source skill directory
+ * @param {string} destDir - Destination directory
  */
 function copySkillDir(srcDir, destDir) {
   if (!fs.existsSync(destDir)) {
@@ -123,11 +134,12 @@ function copySkillDir(srcDir, destDir) {
 }
 
 /**
- * Formatea un error de filesystem con hint útil según el código.
+ * Format a filesystem error with a user-friendly hint based on the code.
+ * Keeps the underlying error message so debugging is still possible.
  */
 function formatFsError(err, context) {
   const codeHints = {
-    EACCES: 'Permiso denegado. Revisa los permisos del directorio.',
+    EACCES: 'Permiso denegado. Revisá los permisos del directorio.',
     EPERM: 'Operación no permitida. En Windows, probá ejecutar como Administrador.',
     ENOSPC: 'No hay espacio en disco.',
     ENOENT: 'Archivo o directorio no existe.',
@@ -138,8 +150,9 @@ function formatFsError(err, context) {
 }
 
 /**
- * Parsea las flags de CLI y devuelve un objeto de opciones.
- * Valida que cada --agent/-a tenga un valor asociado.
+ * Parse CLI arguments into an options object.
+ * Validates that each --agent / -a flag is followed by a real value
+ * so we don't silently accept dangling flags.
  */
 function parseArgs(args) {
   const opts = {
@@ -152,7 +165,7 @@ function parseArgs(args) {
     if (args[i] === '--agent' || args[i] === '-a') {
       const next = args[i + 1];
       if (next === undefined || next.startsWith('-')) {
-        // Falta valor para --agent; avisamos y seguimos sin ese flag
+        // Missing value — warn and skip this flag instead of crashing.
         console.warn(`⚠ Flag ${args[i]} sin valor. Uso: ${args[i]} <agente-id>. Ignorando.`);
         continue;
       }
@@ -165,8 +178,8 @@ function parseArgs(args) {
 }
 
 /**
- * Resuelve qué agentes instalar según las flags y el modo interactivo.
- * @returns {Promise<string[]>} IDs de agentes seleccionados
+ * Resolve which agents to install based on flags or interactive prompt.
+ * @returns {Promise<string[]>} IDs of the selected agents
  */
 async function resolveSelectedAgents(opts, baseDir, chalk) {
   if (opts.isAll) {
@@ -187,7 +200,7 @@ async function resolveSelectedAgents(opts, baseDir, chalk) {
     return Object.keys(AGENTS);
   }
 
-  // Modo interactivo
+  // Interactive mode — detect installed agents and prompt the user.
   const detected = detectAgents(baseDir);
   console.log(chalk.cyan('  Seleccioná los agentes donde querés instalar:\n'));
 
@@ -205,11 +218,13 @@ async function resolveSelectedAgents(opts, baseDir, chalk) {
 }
 
 /**
- * Instala los skills en los directorios seleccionados.
+ * Copy skills into the universal path first, then either symlink or copy
+ * each selected agent's skill directory to point at the universal copy.
  * @returns {{agentResults: Array, copyFallbacks: number}}
  */
 function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
-  // Siempre instalamos primero en el path universal
+  // Always install to the universal path first. This is the source of
+  // truth that all other agent dirs symlink to.
   const universalTarget = path.join(baseDir, UNIVERSAL_DIR);
   for (const skill of skillDirs) {
     const src = path.join(skillsSourceDir, skill);
@@ -217,17 +232,17 @@ function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
     copySkillDir(src, dest);
   }
 
-  // Symlinks o copias para los directorios específicos de agentes
   const agentResults = [];
   let copyFallbacks = 0;
 
   for (const agentId of selectedAgents) {
     const agent = AGENTS[agentId];
-    if (agent.dir === UNIVERSAL_DIR) continue; // Ya manejado por el universal
+    if (agent.dir === UNIVERSAL_DIR) continue; // Already handled above.
 
     const agentTarget = path.join(baseDir, agent.dir);
 
-    // Si ya existe y no es symlink, copiamos ahí directamente
+    // If a real directory already exists (not a symlink), copy into it
+    // directly so we don't destroy user data.
     if (fs.existsSync(agentTarget) && !fs.lstatSync(agentTarget).isSymbolicLink()) {
       for (const skill of skillDirs) {
         copySkillDir(path.join(skillsSourceDir, skill), path.join(agentTarget, skill));
@@ -241,22 +256,23 @@ function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
       fs.mkdirSync(parentDir, { recursive: true });
     }
 
-    // Eliminar symlink existente si hay uno (para poder recrearlo)
+    // Remove any pre-existing symlink so we can recreate it cleanly.
     if (fs.existsSync(agentTarget) || fs.lstatSync(agentTarget, { throwIfNoEntry: false })) {
       try {
         fs.unlinkSync(agentTarget);
       } catch (_) {
-        /* no existe, seguimos */
+        /* target didn't exist after all — that's fine */
       }
     }
 
     try {
-      // Symlink relativo del dir del agente al dir universal
+      // Relative symlink from the agent's dir to the universal dir.
       const relPath = path.relative(parentDir, universalTarget);
       fs.symlinkSync(relPath, agentTarget);
       agentResults.push({ agent: agent.name, method: 'symlinked', dir: agent.dir });
     } catch (symlinkErr) {
-      // Fallback a copia si el symlink falla (ej: Windows sin permisos)
+      // Windows without admin can't create symlinks. Fall back to copy
+      // and remember so we can warn the user at the end.
       copyFallbacks++;
       if (!fs.existsSync(agentTarget)) {
         fs.mkdirSync(agentTarget, { recursive: true });
@@ -277,18 +293,18 @@ function performInstall(skillsSourceDir, skillDirs, selectedAgents, baseDir) {
 }
 
 /**
- * Configura los 2 MCP servers (powerbi-modeling + microsoft-learn)
- * para cada agente seleccionado escribiendo el config file en el path
- * y formato que cada agente espera.
+ * Configure the 2 MCP servers (powerbi-modeling + microsoft-learn)
+ * for each selected agent by writing the config file in the path and
+ * format that agent expects.
  *
- * Los errores por agente no interrumpen el flujo: se recolectan en los
- * resultados para mostrarlos al final y que el caller decida qué hacer
- * con el exit code.
+ * Per-agent errors don't abort the whole flow: they're collected in the
+ * results array so the caller can display them and decide on the exit
+ * code.
  *
- * @param {string[]} selectedAgents - IDs de agentes seleccionados
- * @param {string} packageDir - Absolute path al paquete instalado
- * @param {string} baseDir - Home directory del usuario (para display)
- * @param {Object} chalk - chalk instance para colorear output
+ * @param {string[]} selectedAgents - Agent IDs to configure
+ * @param {string} packageDir - Absolute path to the installed package
+ * @param {string} baseDir - User's home directory (for display)
+ * @param {Object} chalk - chalk instance for colored output
  * @returns {Array<{agent: string, success: boolean, configPath?: string, error?: string}>}
  */
 function configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk) {
@@ -315,9 +331,9 @@ function configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk) {
 }
 
 /**
- * Handler principal del comando install.
- * @param {string[]} args - Argumentos CLI
- * @param {Object} config - Config del comando desde el CLI
+ * Main handler for the `super install` command.
+ * @param {string[]} args - CLI arguments
+ * @param {Object} config - Command config from the CLI (packageDir, version)
  */
 async function installCommand(args, config) {
   const chalk = require('chalk');
@@ -325,10 +341,11 @@ async function installCommand(args, config) {
 
   const opts = parseArgs(args);
 
-  // Siempre a nivel usuario (home) para proteger contenido licenciado
+  // Always install at the user level (home directory) — skills and MCPs
+  // apply across all projects without polluting any specific repo.
   const baseDir = os.homedir();
 
-  // Localizar los skills del paquete
+  // Locate the skills inside the installed package.
   const packageDir = config.packageDir || path.dirname(path.dirname(__dirname));
   const skillsSourceDir = path.join(packageDir, 'skills');
 
@@ -341,7 +358,7 @@ async function installCommand(args, config) {
     process.exit(1);
   }
 
-  // Leer skills disponibles
+  // Read the available skill directories from the package.
   let skillDirs;
   try {
     skillDirs = fs
@@ -355,7 +372,7 @@ async function installCommand(args, config) {
     process.exit(1);
   }
 
-  // Header
+  // Header box shown at the top of every install run.
   console.log(
     boxen(
       chalk.bold.cyan('BI Agent Superpowers') +
@@ -373,7 +390,7 @@ async function installCommand(args, config) {
   console.log(chalk.gray(`  Ruta de instalación: ~/${UNIVERSAL_DIR}/`));
   console.log(chalk.gray(`  Skills: ${skillDirs.length} disponibles\n`));
 
-  // Resolver qué agentes instalar
+  // Resolve which agents to configure.
   const selectedAgents = await resolveSelectedAgents(opts, baseDir, chalk);
 
   if (selectedAgents.length === 0) {
@@ -387,7 +404,7 @@ async function installCommand(args, config) {
     )
   );
 
-  // Instalar skills
+  // Phase 1: copy skills and create symlinks per agent.
   let agentResults;
   let copyFallbacks;
   try {
@@ -399,20 +416,20 @@ async function installCommand(args, config) {
     process.exit(1);
   }
 
-  // Universal skills path
+  // Report on the universal skills path.
   const universalAgents = selectedAgents
     .filter((id) => AGENTS[id] && AGENTS[id].dir === UNIVERSAL_DIR)
     .map((id) => AGENTS[id].name);
   const universalSuffix = universalAgents.length > 0 ? ` — ${universalAgents.join(', ')}` : '';
   console.log(chalk.green(`  ✓ ${UNIVERSAL_DIR}/ (${skillDirs.length} skills)${universalSuffix}`));
 
-  // Skills por agente
+  // Report per agent.
   for (const result of agentResults) {
     const icon = result.method === 'symlinked' ? '→' : '✓';
     console.log(chalk.green(`  ${icon} ${result.dir}/ (${result.method}) — ${result.agent}`));
   }
 
-  // Aviso si hubo fallbacks de symlink a copia
+  // Warn if any agent fell back from symlink to copy.
   if (copyFallbacks > 0) {
     console.log(
       chalk.yellow(
@@ -423,10 +440,10 @@ async function installCommand(args, config) {
     );
   }
 
-  // Configurar MCPs para cada agente seleccionado
+  // Phase 2: write the 2 MCP configs per agent.
   const mcpResults = configureMcpsForAgents(selectedAgents, packageDir, baseDir, chalk);
 
-  // Resumen
+  // Build the final summary box.
   const totalAgents = agentResults.length + (universalAgents.length > 0 ? 1 : 0);
   const mcpSuccess = mcpResults.filter((r) => r.success).length;
   const mcpFailures = mcpResults.filter((r) => !r.success);
@@ -457,7 +474,7 @@ async function installCommand(args, config) {
         '\n' +
         chalk.gray('  /project-kickoff  — Analizá tu proyecto BI') +
         '\n' +
-        chalk.gray('  /pbi-connect      — Conectá Claude a Power BI Desktop'),
+        chalk.gray('  /pbi-connect      — Conectá tu agente a Power BI Desktop'),
       {
         padding: 1,
         margin: { top: 1 },
@@ -468,14 +485,14 @@ async function installCommand(args, config) {
   );
 
   if (hasFailures) {
-    // Non-zero exit so CI/scripts know something went wrong, but skills
-    // still got installed — we use exit code 2 to distinguish from total
-    // failure (exit 1).
+    // Non-zero exit so CI/scripts know something went wrong. Exit code 2
+    // distinguishes partial failure (skills ok, some MCPs failed) from
+    // total failure (exit code 1).
     process.exitCode = 2;
   }
 }
 
-// Exports internos para testing
+// Internal exports for testing.
 module.exports = installCommand;
 module.exports.parseArgs = parseArgs;
 module.exports.detectAgents = detectAgents;

package/bin/lib/agents.js

@@ -22,6 +22,25 @@
 /**
  * Supported agents, in the order they appear in the interactive installer.
  * Object insertion order matters — the installer renders the list in this order.
+ *
+ * IMPORTANT: the `dir` values are the USER-LEVEL skill directories for each
+ * agent. They're relative to the user's home directory (installed with
+ * `super install` at ~/). Each path comes from official docs — if you
+ * change one, verify it against the linked source first.
+ *
+ * Source docs:
+ * - GitHub Copilot: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-skills
+ *   "For personal skills, shared across projects, use ~/.copilot/skills"
+ *   (NOT ~/.github/skills — that's project-level for the cloud agent.)
+ * - Claude Code: https://code.claude.com/docs/en/skills
+ *   "Personal skills go in ~/.claude/skills/"
+ * - Codex: https://developers.openai.com/codex/skills
+ *   "Personal skills go in ~/.codex/skills or ~/.agents/skills"
+ *   We use the universal ~/.agents/skills path.
+ * - Gemini CLI: https://geminicli.com/docs/cli/skills/
+ *   "User skills in $HOME/.gemini/skills"
+ * - Kilo Code: https://kilo.ai/docs/customize/skills
+ *   "Global skills in ~/.kilo/skills/" (NOT ~/.kilocode/)
  */
 const AGENTS = {
   'github-copilot': { name: 'GitHub Copilot', dir: '.copilot/skills' },

package/bin/lib/mcp-config.js

@@ -124,11 +124,19 @@ function escapeRegex(str) {
 //
 // We describe each agent in a single table and build the writer functions
 // from it so adding a new JSON agent is a one-line change.
+//
+// IMPORTANT: every entry below has a source URL pointing at the official
+// docs where the path/format comes from. If you change any of these,
+// verify the new value against the linked source first. Silent drift is
+// the hardest class of bug in this file because the writes succeed even
+// when the agent never reads the file.
 
 const JSON_AGENT_CONFIGS = {
   'claude-code': {
-    // Claude Code user-scope MCP config lives in ~/.claude.json under
-    // mcpServers. stdio entries omit `type`, HTTP entries include it.
+    // Source: https://code.claude.com/docs/en/mcp
+    // "User-scoped servers are stored in ~/.claude.json"
+    // Note: ~/.claude/settings.json does NOT work for MCPs (known docs bug).
+    // stdio entries omit `type` here; HTTP entries include it.
     configPath: () => path.join(os.homedir(), '.claude.json'),
     wrapperKey: 'mcpServers',
     stdioIncludesType: false,
@@ -136,7 +144,9 @@ const JSON_AGENT_CONFIGS = {
     httpField: 'url',
   },
   'github-copilot': {
-    // Copilot CLI uses `servers` (NOT mcpServers) and every server needs
+    // Source: https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers
+    // "MCP servers are saved to ~/.copilot/mcp-config.json"
+    // Copilot uses `servers` (NOT mcpServers) and every server needs
     // an explicit `type` field.
     configPath: () => path.join(os.homedir(), '.copilot', 'mcp-config.json'),
     wrapperKey: 'servers',
@@ -145,6 +155,8 @@ const JSON_AGENT_CONFIGS = {
     httpField: 'url',
   },
   'gemini-cli': {
+    // Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
+    // "MCP config goes in ~/.gemini/settings.json under mcpServers"
     // Gemini uses `httpUrl` (NOT `url`) for HTTP transports and omits
     // `type` — it's inferred from which key is present.
     configPath: () => path.join(os.homedir(), '.gemini', 'settings.json'),
@@ -154,10 +166,12 @@ const JSON_AGENT_CONFIGS = {
     httpField: 'httpUrl',
   },
   kilo: {
+    // Source: https://kilo.ai/docs/automate/mcp/using-in-kilo-code
     // Kilo Code uses ~/.kilo/ as the user config root (consistent with
     // ~/.kilo/skills/). The global MCP settings live at the natural
     // neighbor path — mcp_settings.json — which is what the Kilo VS Code
-    // extension and CLI both read.
+    // extension and CLI both read. (NOT ~/.kilocode/ — that path is
+    // project-level only.)
     configPath: () => path.join(os.homedir(), '.kilo', 'mcp_settings.json'),
     wrapperKey: 'mcpServers',
     stdioIncludesType: false,
@@ -226,6 +240,11 @@ function makeJsonWriter(agentId) {
 // ============================================
 // CODEX (OpenAI) — TOML format
 // ============================================
+// Source: https://developers.openai.com/codex/mcp
+// Also: https://github.com/openai/codex/blob/main/docs/config.md
+// "Codex CLI reads MCP server config from ~/.codex/config.toml, where
+//  each server gets its own section with format [mcp_servers.my-server]"
+//
 // Writes ~/.codex/config.toml, appending [mcp_servers.*] sections.
 // Preserves existing content by removing only our own sections before
 // appending the fresh ones.

package/desktop-extension/manifest.json

@@ -3,8 +3,8 @@
   "name": "bi-superpowers",
   "display_name": "BI Agent Superpowers",
   "version": "0.0.0-template",
-  "description": "AI-powered toolkit for Power BI, Microsoft Fabric & Excel development. 24 skills covering DAX, Power Query, data modeling, and more.",
-  "long_description": "BI Agent Superpowers brings 24 specialized skills to Claude Desktop, covering DAX writing, Power Query transformations, data modeling best practices, performance optimization, Excel formulas, report design, and more. Built for Power BI developers, data analysts, and BI professionals.",
+  "description": "Open-source Power BI Desktop toolkit for Claude Desktop — 2 skills and 2 official Microsoft MCP servers.",
+  "long_description": "BI Agent Superpowers brings focused Power BI Desktop skills to Claude Desktop: project kickoff analysis, direct Power BI Desktop connection, and official Microsoft MCP servers (Power BI Modeling + Microsoft Learn). Built for Power BI developers and data analysts.",
   "author": {
     "name": "Lucas Sanchez",
     "url": "https://github.com/luquimbo"
@@ -13,16 +13,9 @@
     "type": "git",
     "url": "https://github.com/luquimbo/bi-superpowers"
   },
-  "homepage": "https://acadevor.com/bi-superpowers",
+  "homepage": "https://github.com/luquimbo/bi-superpowers",
   "license": "MIT",
-  "keywords": [
-    "power-bi",
-    "dax",
-    "fabric",
-    "excel",
-    "data-modeling",
-    "business-intelligence"
-  ],
+  "keywords": ["power-bi", "power-bi-desktop", "mcp", "claude", "business-intelligence"],
   "server": {
     "type": "node",
     "entry_point": "server.js"

package/desktop-extension/server.js

@@ -3,10 +3,11 @@
 /**
  * BI Agent Superpowers — MCP Server for Claude Desktop
  *
- * Lightweight MCP server that exposes all 24 BI skills as prompts.
- * Bundled into a .mcpb extension via `super build-desktop`.
+ * Lightweight MCP server that exposes each bi-superpowers skill as a
+ * Claude Desktop prompt. Bundled into a .mcpb extension via
+ * `super build-desktop`.
  *
- * Skills are loaded from the ./skills/ directory (copied at build time).
+ * Skills are loaded from the ./skills/ directory (copied in at build time).
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -18,29 +19,25 @@ import { fileURLToPath } from 'url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const skillsDir = path.join(__dirname, 'skills');
 
-// Create the MCP server instance
+// Create the MCP server instance.
 const server = new McpServer({
   name: 'bi-superpowers',
   version: '0.0.0-template',
 });
 
-// Load all skill markdown files from the bundled skills/ directory
+// Load all skill markdown files from the bundled skills/ directory.
 const skillFiles = fs.existsSync(skillsDir)
   ? fs.readdirSync(skillsDir).filter((f) => f.endsWith('.md'))
   : [];
 
-// Register each skill as an MCP prompt that Claude Desktop can invoke
+// Register each skill as an MCP prompt that Claude Desktop can invoke.
 for (const file of skillFiles) {
   const name = path.basename(file, '.md');
   const content = fs.readFileSync(path.join(skillsDir, file), 'utf8');
 
-  // Extract first line as description (skip markdown headers)
-  const firstLine = content
-    .split('\n')
-    .find((l) => l.trim() && !l.startsWith('#'));
-  const description = firstLine
-    ? firstLine.slice(0, 120).trim()
-    : `BI Superpowers: ${name}`;
+  // Use the first non-header line as a short description for the prompt.
+  const firstLine = content.split('\n').find((l) => l.trim() && !l.startsWith('#'));
+  const description = firstLine ? firstLine.slice(0, 120).trim() : `BI Superpowers: ${name}`;
 
   server.prompt(name, { description }, () => ({
     messages: [
@@ -52,10 +49,15 @@ for (const file of skillFiles) {
   }));
 }
 
-// Register a setup-mcp helper prompt with Power BI/Fabric/Excel MCP instructions
+// Register a setup-mcp helper prompt that explains how to wire the
+// official Microsoft MCP servers (Power BI Modeling + Microsoft Learn)
+// into Claude Desktop.
 server.prompt(
   'setup-mcp',
-  { description: 'Instructions to configure Power BI, Fabric & Excel MCP servers in Claude Desktop' },
+  {
+    description:
+      'Instructions to configure the Power BI Modeling and Microsoft Learn MCP servers in Claude Desktop',
+  },
   () => ({
     messages: [
       {
@@ -64,25 +66,32 @@ server.prompt(
           type: 'text',
           text: `# Configure MCP Servers for Claude Desktop
 
-To connect Power BI, Fabric, and Excel to Claude Desktop, add the following
-to your \`claude_desktop_config.json\` (Settings > Developer > Edit Config):
+bi-superpowers ships two official Microsoft MCP servers. To wire them
+into Claude Desktop, add the following to your \`claude_desktop_config.json\`
+(Settings → Developer → Edit Config):
 
 \`\`\`json
 {
   "mcpServers": {
-    "powerbi-remote": {
-      "command": "npx",
-      "args": ["-y", "@anthropic-ai/mcp-remote", "https://mcp.powerbi.com/sse"]
+    "powerbi-modeling": {
+      "command": "node",
+      "args": ["<absolute path to powerbi-modeling-launcher.js>"]
     },
-    "fabric-mcp-server": {
-      "command": "npx",
-      "args": ["-y", "@anthropic-ai/mcp-remote", "https://mcp.fabric.microsoft.com/v1/sse"]
+    "microsoft-learn": {
+      "type": "http",
+      "url": "https://learn.microsoft.com/api/mcp"
     }
   }
 }
 \`\`\`
 
-After saving, restart Claude Desktop. The MCP servers will appear in your tools.
+The \`powerbi-modeling\` server requires Power BI Desktop on Windows
+with a model open. If you prefer automated setup, run
+\`super install\` from the bi-superpowers CLI — it configures both
+servers across all 5 supported AI agents.
+
+After saving, restart Claude Desktop. The MCP servers will appear in
+your tools.
 `,
         },
       },
@@ -90,6 +99,6 @@ After saving, restart Claude Desktop. The MCP servers will appear in your tools.
   })
 );
 
-// Start the server with stdio transport
+// Start the server with stdio transport.
 const transport = new StdioServerTransport();
 await server.connect(transport);