@luquimbo/bi-superpowers 3.1.1 → 4.1.0

package/README.md

@@ -5,62 +5,87 @@
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 [![Power BI](https://img.shields.io/badge/Power%20BI-Desktop-F2C811?logo=powerbi)](https://powerbi.microsoft.com)
 
-Toolkit open-source para trabajar con **Power BI Desktop** desde tu agente AI favorito. Funciona con los 5 agentes soportados: Claude Code, GitHub Copilot, Codex, Gemini CLI y Kilo Code.
+Toolkit open-source para trabajar con **Power BI Desktop** desde Claude Code, GitHub Copilot, Codex, Gemini CLI y Kilo Code.
 
-> **Estado:** versión inicial. 2 skills y 2 MCP servers para empezar a iterar.
+> **Estado:** `v4.0.x`. Incluye 4 skills (`/bi-start` + 3 especialistas) y 2 MCP servers oficiales de Microsoft. `/report-design` genera PBIR via scripts Node propios (no depende de `pbi-cli-tool` para authoring — Windows + Power BI Desktop sí sigue siendo requisito runtime).
 
 ---
 
-## Quick Start
+## Instalación
+
+Elegí el camino según tu agente principal:
+
+### 👉 Claude Code (recomendado para usuarios de Claude Code)
+
+Dentro de Claude Code, ejecutá:
+
+```
+/plugin marketplace add luquimbo/bi-superpowers
+/plugin install bi-superpowers
+```
+
+Eso instala el plugin completo (4 skills + 2 MCPs) en el perfil de Claude Code. Después podés actualizar con `/plugin update bi-superpowers` directamente desde Claude Code — sin pasar por npm.
+
+Si también querés el plugin local de proyecto (con slash commands `/project-kickoff`, `/pbi-connect`, `/report-design` en un repo específico), corré `super kickoff` dentro del repo — requiere haber instalado la CLI via el otro path (abajo).
+
+### 👉 Otros agentes — Copilot, Codex, Gemini CLI, Kilo Code (o multi-agente)
 
 ```bash
 # 1. Instalá la CLI
 npm install -g @luquimbo/bi-superpowers
 
-# 2. Instalá skills y MCPs en todos tus agentes
+# 2. Instalá skills + MCPs en todos tus agentes
 super install
 ```
 
-Eso es todo. El instalador:
+El instalador:
 
 1. Detecta qué agentes AI tenés instalados (Claude Code, Copilot, Codex, Gemini, Kilo).
 2. Te deja elegir para cuáles instalar (o hace todos con `--all --yes`).
-3. Copia los 2 skills en los directorios correctos de cada agente.
+3. Copia los 4 skills en los directorios correctos de cada agente.
 4. Escribe los 2 MCPs en el config file correcto de cada agente (con el formato/schema que cada uno espera).
 
-Reiniciá tu agente AI, y ya tenés bi-superpowers funcionando.
+Reiniciá tu agente AI y ya tenés bi-superpowers funcionando.
+
+> **¿Por qué dos caminos?** El marketplace de Claude Code es la UX más limpia para usuarios de Claude Code — cero dependencias externas, updates nativos. La CLI via npm cubre los otros 4 agentes (que no tienen un marketplace equivalente) y funciona como denominador común cuando querés las mismas skills + MCPs en múltiples agentes. Los dos caminos son compatibles: podés combinar instalación via marketplace en Claude Code con instalación via CLI para los otros.
 
 ---
 
 ## Qué viene incluido
 
-### 2 Skills
+### 4 Skills
 
 | Skill | Para qué |
 |---|---|
-| `project-kickoff` | Analizá el estado de tu proyecto BI y decidí próximos pasos |
+| `bi-start` | **Arrancar una sesión**: muestra el menú de skills, corre update-check, y (si detecta Power BI Desktop abierto) ofrece conectar vía MCP. Tu entrada por defecto en cada conversación nueva. |
+| `project-kickoff` | Analizá el estado de tu proyecto BI **nuevo** y armá `AGENTS.md` + modelo base |
 | `pbi-connect` | Conectá tu agente AI a Power BI Desktop vía MCP |
+| `report-design` | Generá páginas PBIR vía scripts Node propios (`create-visual.js`, `apply-theme.js`, `validate-pbir.js`), con allowlist de 28 visualTypes nativos |
+
+Si no sabés por dónde empezar, decile a tu agente `/bi-start` — te muestra los 4 skills, chequea updates, y rutea al que necesites. `/project-kickoff` está reservado para cuando arrancás un proyecto BI desde cero.
+
+`report-design` requiere **Windows + Power BI Desktop** (standalone, no la versión de Microsoft Store). Los scripts Node son portables, pero el ciclo de verificación (relaunch, render) necesita Desktop. `pbi-cli-tool` es opcional y solo se usa para introspección del modelo (preferido: Microsoft Modeling MCP cuando está disponible).
 
 ### 2 MCP Servers (oficiales de Microsoft)
 
 | MCP | Para qué |
 |---|---|
-| `powerbi-modeling` | Conexión local a Power BI Desktop (XMLA). Leer/escribir modelo semántico, ejecutar DAX. |
+| `powerbi-modeling-mcp` | Conexión local a Power BI Desktop (XMLA). Leer/escribir modelo semántico, ejecutar DAX. |
 | `microsoft-learn` | HTTP MCP de Microsoft Learn — docs oficiales de Power BI/DAX/Fabric en contexto de la conversación. |
 
 ---
 
 ## Agentes soportados
 
-| Agente | Skills | MCP config path |
-|---|---|---|
-| **Claude Code** | ✅ `~/.claude/skills/` | `~/.claude.json` |
-| **GitHub Copilot** | ✅ `~/.copilot/skills/` | `~/.copilot/mcp-config.json` |
-| **Codex (OpenAI)** | ✅ `~/.agents/skills/` | `~/.codex/config.toml` |
-| **Gemini CLI** | ✅ `~/.gemini/skills/` | `~/.gemini/settings.json` |
-| **Kilo Code** | ✅ `~/.kilo/skills/` | `~/.kilo/mcp_settings.json` |
+| Agente | Skills | MCP config path | Cómo se usa |
+|---|---|---|---|
+| **Claude Code** | ✅ via `/plugin install` o `~/.claude/skills/` | `~/.claude.json` | Lenguaje natural o slash commands si corrés `super kickoff` |
+| **GitHub Copilot** | ✅ `~/.copilot/skills/` | `~/.copilot/mcp-config.json` | Lenguaje natural |
+| **Codex (OpenAI)** | ✅ `~/.agents/skills/` | `~/.codex/config.toml` | Lenguaje natural |
+| **Gemini CLI** | ✅ `~/.gemini/skills/` | `~/.gemini/settings.json` | Lenguaje natural |
+| **Kilo Code** | ✅ `~/.kilo/skills/` | `~/.kilo/mcp_settings.json` | Lenguaje natural |
 
-`super install` escribe todo esto automáticamente.
+`super install` (npm path) escribe los skills + MCPs automáticamente para todos los agentes detectados.
 
 ### Instalación selectiva
 
@@ -79,12 +104,35 @@ super install --all --yes
 
 ## Actualizar
 
+Dos caminos según cómo instalaste:
+
+### Claude Code (instalado via marketplace)
+
+Dentro de Claude Code:
+
+```
+/plugin update bi-superpowers
+```
+
+Eso trae la última versión publicada en el marketplace. Cero interacción con npm.
+
+### npm (todos los otros agentes)
+
 ```bash
-# Actualizar la CLI a la última versión
-npm install -g @luquimbo/bi-superpowers@latest
+# 1. Actualizá la CLI a la última versión
+super upgrade
 
-# Re-instalar skills y MCPs (sobrescribe los viejos)
-super install --all --yes
+# 2. Refrescá skills + MCPs en tus agentes (no se hace automático, es un paso separado)
+super install --yes
+```
+
+`super upgrade` reinstala el paquete global y al final te imprime un recordatorio con este segundo paso. No lo hace automático a propósito: los usuarios que solo quieren actualizar la CLI (p.ej. desarrollando local) pueden saltarlo.
+
+Equivalente manual si `super upgrade` falla:
+
+```bash
+npm install -g @luquimbo/bi-superpowers@latest
+super install --yes
 ```
 
 ---
@@ -111,7 +159,8 @@ Si ya instalaste los MCPs por alguno de estos caminos, no necesitás correr `sup
 ## Requisitos
 
 - **Node.js ≥ 18**
-- **Power BI Desktop en Windows** (para el MCP `powerbi-modeling` — el MCP `microsoft-learn` funciona en cualquier plataforma)
+- **Power BI Desktop en Windows** (standalone, no Microsoft Store) para workflows locales contra Desktop (`powerbi-modeling-mcp` y `report-design`)
+- **Python 3.10+**, **`pipx`** y **`pbi-cli-tool`** son **opcionales** — solo hacen falta para introspección del modelo via XMLA cuando el Microsoft Modeling MCP no está disponible. Para authoring de visuales, `report-design` usa scripts Node propios y no depende de esa cadena.
 - Al menos uno de: Claude Code, GitHub Copilot, Codex, Gemini CLI, Kilo Code
 
 ---
@@ -119,11 +168,11 @@ Si ya instalaste los MCPs por alguno de estos caminos, no necesitás correr `sup
 ## Comandos
 
 ```bash
-super install          # Instalá skills + MCPs en tus agentes AI
-super kickoff          # Generá el plugin de Claude Code en un proyecto (avanzado)
+super install          # Instalá 4 skills + 2 MCPs en tus agentes AI
+super kickoff          # Generá el plugin local de Claude Code con slash commands
 super recharge         # Regenerá el plugin tras editar skills fuente
 super powers           # Listá skills disponibles
-super upgrade          # Actualizá la CLI a la última versión
+super upgrade          # Actualizá la CLI a la última versión + imprime recordatorio de `super install`
 super help             # Ayuda completa
 ```
 

package/bin/build-plugin.js

@@ -3,9 +3,9 @@
 /**
  * Build the repository-root Claude Code plugin artifacts.
  *
- * Genera los archivos del plugin desde las fuentes en src/content/skills/
- * y valida que los outputs críticos hayan sido creados correctamente.
- * Este script corre en el prepack de npm publish.
+ * Generates plugin files from the sources in src/content/skills/ and
+ * verifies that all critical outputs were created successfully. This
+ * script runs as part of the `prepack` hook before `npm publish`.
  */
 
 const fs = require('fs');
@@ -15,9 +15,9 @@ const { loadSkills } = require('./lib/skills');
 const pkg = require('../package.json');
 
 /**
- * Verifica que todos los archivos críticos del plugin hayan sido generados.
- * @param {string} packageDir - Directorio raíz del paquete
- * @throws {Error} Si falta cualquier archivo crítico
+ * Verify that every critical plugin output has been generated.
+ * @param {string} packageDir - Package root directory
+ * @throws {Error} if any critical file is missing
  */
 function verifyPluginOutputs(packageDir) {
   const criticalFiles = [
@@ -84,7 +84,14 @@ async function main() {
   verifyPluginOutputs(packageDir);
 }
 
-main().catch((error) => {
-  console.error(error.message);
-  process.exit(1);
-});
+// Export for unit testing. The script is also invoked directly during
+// `npm run build:plugin` — we only run main() when it's the entry point,
+// otherwise the test suite would trigger a full build on every import.
+module.exports = { verifyPluginOutputs, main };
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}