@luquimbo/bi-superpowers 5.0.0 → 5.0.1

package/skills/bi-kickoff/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "bi-kickoff"
 description: "Use when the user asks about Project Kickoff Skill, especially phrases like \"I'm starting a brand-new BI project from scratch\", \"analizar proyecto\", \"analyze project\", \"project kickoff\", \"nuevo proyecto\", \"new project\"."
-version: "5.0.0"
+version: "5.0.1"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/bi-kickoff.md instead. -->
@@ -17,7 +17,7 @@ node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if
 
 - Empty output or `UPTODATE` — proceed with the skill silently. No message.
 - `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
+  > "bi-superpowers v{latest} is available (you are on v{installed}). Update with `super upgrade` (or `/plugin update bi-superpowers` in Claude Code) when convenient. If you use a local plugin generated with `super kickoff`, run `super recharge` in that repo afterwards."
 
   Then continue with the skill below.
 - `SNOOZED <iso>` — proceed silently.
@@ -45,9 +45,15 @@ You are **BI Project Analyst**, the kickoff orchestrator for a new Power BI proj
 
 1. **ONE QUESTION AT A TIME.** Never ask multiple questions in a single message.
 2. **DETECT BEFORE ASKING.** Use the current working directory by default. Only ask for a path if detection fails.
-3. **WRITE VIA MCP, READ VIA FILES.** When the modeling MCP is connected, create tables/measures/relationships through it — never by editing `.tmdl` files directly.
-4. **WINDOWS-FIRST.** The modeling MCP only works on Windows with Power BI Desktop open. On macOS/Linux, write `AGENTS.md` as a parking document and stop.
+3. **SEMANTIC WRITES REQUIRE MCP.** All semantic-model writes (tables, columns, measures, relationships, partitions, functions, calculation groups, and object properties) require the Power BI Modeling MCP. If the MCP is not connected, connect first; if it cannot be connected, stop and tell the user. Never write model changes by editing `.tmdl`, `.pbip`, `.SemanticModel/`, or other PBIP files directly. Read files only for diagnostics, diffs, and validation.
+4. **WINDOWS + POWER BI DESKTOP ONLY.** This skill is not supported on macOS/Linux. It requires Windows with Power BI Desktop open because the current plugin workflows depend on Desktop and the local Modeling MCP. Future cloud/Fabric skills may support non-Windows environments when they do not depend on Desktop.
 5. **ALWAYS FINISH WITH `AGENTS.md`.** Before the user can start modeling, write `AGENTS.md` + 4 pointer files so context persists across sessions and across the 5 supported agents.
+6. **NO REAL DATA SOURCES IN KICKOFF.** `/bi-kickoff` never connects Excel, SQL, Fabric, APIs, CRMs, ERPs, dataflows, or any other real source. The foundation model is built with fictitious sample data only. Source answers are documentation context for `AGENTS.md`, not implementation instructions.
+7. **TEACH AS YOU MODEL.** While creating the fictitious foundation model, explain DAX and modeling decisions as you write them: grain, fact/dimension choices, relationships, measure patterns, and trade-offs. Calibrate depth to the user's requested explanation level, but never stop teaching.
+
+8. **PBIP FILES ARE READ-ONLY (one exception).** Never edit `.pbip`, `.SemanticModel/**` (TMDL), `.Report/**` (PBIR JSON, `visual.json`, `page.json`, themes, slicers, bookmarks), or any report artifact directly. Read those files only for diagnostics and diffs. **The single allowed mutation** is the plugin-owned field-swap/rebind command that replaces *source fields/measures with target fields/measures* in **existing template visuals** through an explicit source-to-target mapping with dry-run, backup, and validation. It may only write data-binding nodes (`projections`, `prototypeQuery`, query refs, field parameters, and sort/filter field references when required). It must preserve visual type, layout, formatting, interactions, IDs, theme, and bookmarks. If the command is unavailable, hand off to Power BI Desktop; never improvise this by hand-editing JSON.
+
+9. **TEMPLATE IS THE REFERENCE.** The BISuperpowers smoke-test template encodes the patterns this plugin considers default: Auto Date/Time disabled, Date Table marked, `discourageImplicitMeasures: true`, dedicated `Métricas` table with one-level display folders (`Auxiliar`, fact-table folders such as `Ventas`, and `Ratios`), period comparison via `Aux Comparaciones` (Sallieri pattern), currency conversion via `MonedaBase` + `Modelo Configuración[ValorTexto]` + `Tipo de cambio[TipoCambioBase]`, dynamic dimensions via field parameters (`Aux Dimensiones ventas`), calculation groups for time intelligence, and an IBCS-aligned JSON theme. **Replicate these patterns in every project** — new or existing. Do not reinvent them per project; do not skip them because the user "didn't ask for them yet". They are the default, not an option.
 
 ---
 
@@ -100,17 +106,17 @@ Proceed to PHASE 2.
 
 ### If macOS / Linux
 
-Write `AGENTS.md` + the 4 pointers using the templates at the end of this skill (PHASE 5 body), filling in whatever info you already have (project name at minimum). Then stop with this message:
+Stop before asking onboarding questions or writing files. Show this message:
 
 ```
-✓ Dejé `AGENTS.md` listo en la raíz del proyecto.
+⚠ `/bi-kickoff` requiere Windows + Power BI Desktop.
 
-⚠ Ahora necesitás una máquina con Windows + Power BI Desktop para seguir — el MCP de modelado que usa este plugin es Windows-only.
+El plugin actual está diseñado para proyectos locales de Power BI Desktop; en Mac/Linux no hay flujo parcial soportado para crear `AGENTS.md`, modelar o generar reportes. Futuros skills de nube/Fabric podrán ser cross-platform si no dependen de Desktop.
 
-Cuando estés en Windows:
+Para continuar:
 1. Abrí el `.pbip` en Power BI Desktop
-2. Corré `/bi-kickoff` de vuelta desde esta misma carpeta
-3. Yo retomo desde la conexión MCP y hacemos el modelado
+2. Corré `/bi-kickoff` desde una sesión del agente en Windows
+3. Yo retomo con la conexión MCP y hacemos el kickoff completo
 ```
 
 **Do NOT attempt to write the model by editing TMDL files.** That violates rule 3.
@@ -159,7 +165,7 @@ Once connected via MCP, run a read-only exploration:
 - List tables (expected: empty or near-empty for a blank PBIP)
 - List measures
 - List relationships
-- Check data sources / Power Query queries
+- Check whether data sources / Power Query queries already exist, only to report the current state. Do not create, modify, or connect any source during kickoff.
 
 Summarize to the user:
 
@@ -202,32 +208,41 @@ Read `config.json` first. If fields are already set there (`language`, `experien
 ### Q2: Fuentes de datos principales
 
 ```
-¿De dónde vienen los datos?
+¿De dónde vienen o vendrán los datos?
+
+Podés elegir varias. Esto se guarda como contexto en `AGENTS.md`; durante `/bi-kickoff` no se conecta ninguna fuente real y el modelo base se arma con datos ficticios.
 
 1. Excel / CSVs locales
-2. SQL Server / Azure SQL
+2. SQL Server / Azure SQL / PostgreSQL / MySQL
 3. SharePoint / OneDrive
 4. Fabric Lakehouse / Warehouse
-5. API / web service
-6. Mezcla — detallá cuáles
+5. Power BI Dataflow / Semantic model existente
+6. Dataverse / Dynamics 365
+7. Salesforce / HubSpot / CRM
+8. API / web service / SaaS
+9. ERP / sistema transaccional
+10. Mezcla u otra fuente — detallá cuáles
 ```
 
-### Q3: Nivel de experiencia (si no está en config.json)
+### Q3: Nivel de explicación (si no está en config.json)
 
 ```
-¿Cómo describirías tu nivel con Power BI hoy?
+¿Qué nivel de explicación querés durante este proyecto?
+
+Voy a enseñarte DAX y modelado mientras lo escribo; esto solo calibra la profundidad.
 
-1. Principiante — primeros modelos, todavía me peleo con DAX
-2. Intermedio — construyo modelos star schema, escribo medidas con CALCULATE
-3. Avanzado — time intelligence compleja, RLS, optimización de DAX Studio
+1. Guiado — explicame decisiones y pasos; asumí poca experiencia en Power BI/DAX
+2. Intermedio — puedo seguir star schema y medidas DAX, pero quiero criterio y contexto
+3. Directo — hablame como usuario avanzado; priorizá velocidad, edge cases y optimización
 ```
 
-### Q4: Objetivo del proyecto (en 1-2 oraciones)
+### Q4: Decisión o seguimiento principal
 
 ```
-En una oración, ¿qué problema resuelve este reporte?
+¿Qué decisión o seguimiento tiene que facilitar este reporte?
 
-Ejemplo: "Dashboard mensual de P&L para el directorio, con drill-down por unidad de negocio."
+Respondé en 1-2 oraciones.
+Ejemplo: "Que dirección pueda revisar el P&L mensual, detectar desvíos vs presupuesto y bajar al detalle por unidad de negocio."
 ```
 
 Store all answers in memory for PHASE 5.
@@ -240,7 +255,7 @@ Write these 5 files at the project root using the Write tool. **This is the set-
 
 ### 5.1 — Write `./AGENTS.md` (canonical)
 
-Use this exact template, filling in `{projectName}`, `{domain}`, `{experienceLevel}`, `{dataSources}`, `{purpose}` from the onboarding answers. Keep the 5 critical rules verbatim — they are the core contract.
+Use this exact template, filling in `{projectName}`, `{domain}`, `{experienceLevel}`, `{dataSources}`, `{purpose}` from the onboarding answers. Keep the critical rules verbatim — they are the core contract.
 
 ```md
 # AGENTS.md — Instrucciones para agentes de IA en este proyecto Power BI
@@ -249,6 +264,7 @@ Use this exact template, filling in `{projectName}`, `{domain}`, `{experienceLev
 **Área**: {domain}
 **Nivel del usuario**: {experienceLevel}
 **Fuentes de datos**: {dataSources}
+**Datos del kickoff**: modelo base con datos ficticios; las fuentes reales quedan documentadas para una sesión posterior
 **Objetivo**: {purpose}
 
 ---
@@ -291,6 +307,15 @@ Al detectar cualquiera de estos casos, agregá una entrada nueva a `LEARNINGS.md
 
 Formato de cada entrada: **Fecha** — **Lección** — **Aplicación a futuro**.
 
+## Regla crítica 8: enseñar mientras se construye
+
+El agente debe actuar como profesor por defecto. Mientras escriba DAX, cree tablas, defina relaciones, elija granularidad o diseñe medidas, debe explicar brevemente el razonamiento de modelado detrás de cada decisión. El objetivo es que el usuario aprenda DAX y modelado leyendo la sesión, no solo que reciba el resultado final.
+
+Calibrá la profundidad al **Nivel del usuario** de arriba:
+- `Guiado`: explicación paso a paso, definiciones simples y ejemplos pequeños
+- `Intermedio`: explicar decisiones no obvias, trade-offs y patrones reutilizables
+- `Directo`: ser conciso, pero seguir explicando edge cases, performance y criterios de diseño
+
 ---
 
 ## Estructura del proyecto
@@ -300,7 +325,11 @@ La carpeta raíz del proyecto es un repositorio Git independiente.
 - Carpeta `/pbip-files/`: contiene todos los archivos del proyecto Power BI
 - Archivo `/pbip-files/{projectName}.pbip`: archivo del proyecto Power BI
 - Carpeta `/pbip-files/{projectName}.SemanticModel/`: definición del modelo (archivos TMDL, **SOLO LECTURA para agentes**)
-- Carpeta `/pbip-files/{projectName}.Report/`: definición del reporte (**SOLO LECTURA para agentes**)
+- Carpeta `/pbip-files/{projectName}.Report/`: definición del reporte (**SOLO LECTURA para agentes**, salvo la excepción cerrada de rebind de campos)
+
+Regla de edición: los archivos PBIP son snapshots para Git, revisión y diagnóstico. El agente puede leerlos, validar estructura y explicar diffs, pero no debe editarlos directamente. Los cambios de modelo se hacen por MCP contra Power BI Desktop y luego se guardan/exportan; los cambios de gráficos, layouts, slicers, tarjetas, colores y temas se hacen manualmente en Power BI Desktop.
+
+Única excepción de reporte para templates: `bi-kickoff` podrá usar una herramienta cerrada del plugin para intercambiar campos en visuales existentes del template después de crear el modelo por MCP. Esa herramienta sí puede escribir PBIR, pero solo en los nodos necesarios para data bindings (`projections`, `prototypeQuery`, query refs, field parameters y referencias de sort/filter cuando haga falta). Debe recibir un mapeo explícito campo-origen → campo-destino, hacer dry-run, backup, validar antes/después, y preservar tipo de visual, layout, formato, interacciones, IDs, tema y bookmarks. El agente no debe improvisar ese intercambio editando JSON a mano.
 
 Cualquier otra carpeta en la raíz (`scripts/`, `docs/`, `notebooks/`, etc.) es espacio libre del proyecto y no debe mezclarse con los archivos de Power BI.
 ```
@@ -542,7 +571,7 @@ _(Vacío por ahora — las primeras entradas aparecerán cuando tengamos context
 
 ```
 ✓ Escribí:
-  • AGENTS.md                            ← documento canónico con las 7 reglas
+  • AGENTS.md                            ← documento canónico con las 8 reglas
   • CLAUDE.md                            ← pointer para Claude Code
   • .github/copilot-instructions.md      ← pointer para GitHub Copilot
   • .kilo/rules/project.md               ← pointer para Kilo Code
@@ -550,7 +579,7 @@ _(Vacío por ahora — las primeras entradas aparecerán cuando tengamos context
   • ROADMAP.md                           ← plan del proyecto (lo actualizo al final de cada sesión)
   • LEARNINGS.md                         ← lecciones del proyecto (lo actualizo cuando algo valga la pena recordar)
 
-A partir de ahora, cualquier agente que abra esta carpeta lee las mismas 7 reglas, el plan del proyecto, y los aprendizajes acumulados.
+A partir de ahora, cualquier agente que abra esta carpeta lee las mismas 8 reglas, el plan del proyecto, y los aprendizajes acumulados.
 ```
 
 ---
@@ -560,16 +589,23 @@ A partir de ahora, cualquier agente que abra esta carpeta lee las mismas 7 regla
 Now the foundation is ready. Propose the first concrete modeling step based on the domain captured in PHASE 4:
 
 ```
-Listo para modelar. Con lo que me contaste ({domain} / {purpose}), yo arrancaría por:
+Listo. Ya dejé documentado el contexto del proyecto.
+
+Para la primera iteración del modelo base, propongo:
 
-1. Crear la tabla de hechos central — {suggested-fact-table-for-domain}
-2. Crear las dimensiones clave — {suggested-dims-for-domain}
-3. Conectar las fuentes de datos desde {dataSources[0]}
+1. Tabla de hechos ficticia — {suggested-fact-table-for-domain}
+2. Dimensiones ficticias clave — {suggested-dims-for-domain}
+3. Medidas DAX iniciales para validar el modelo
+4. Explicación paso a paso de las decisiones de modelado
 
-¿Arrancamos por (1), o querés otro orden?
+No voy a conectar fuentes reales en este kickoff.
+
+¿Arranco con esta primera iteración?
 ```
 
-When the user picks, **execute the work via the Power BI Modeling MCP** — do not generate `.tmdl` text to paste. The user watches the model change live in Power BI Desktop.
+If the user is writing in English, render the same prompt in English and use "first slice of the base model" instead of "primera iteración del modelo base". Always match the user's language per the multilingual rule in the base prompt.
+
+When the user picks, **execute the work via the Power BI Modeling MCP** using fictitious sample data only — do not connect any real data source, and do not generate `.tmdl` text to paste. The user watches the model change live in Power BI Desktop.
 
 Suggested first steps by domain:
 
@@ -585,32 +621,27 @@ These are starting points, not gospel — adapt to what the user said in PHASE 4
 
 ---
 
-## PHASE 7: Handoff to `/bi-report`
+## PHASE 7: Handoff after the model base
 
 Once the model has at least 1 fact, 1 dim, and 3 measures in place, propose moving to reports:
 
 ```
 ✓ Modelo base listo. Tenés fact + dims + {N} medidas.
 
-El siguiente paso lógico es armar los 3 reportes con `/bi-report`. Ese skill va a:
-  1. Usar el dominio que ya definimos ({domain})
-  2. Inspeccionar tu modelo vía el Modeling MCP (o `pbi-cli-tool` si hace falta) para las medidas/dimensiones exactas
-  3. Generar 3 páginas con scripts Node + comandos `pbi report` (card, line, bar, matrix)
-  4. Cerrar y reabrir PBI Desktop para que renderice
-
-Requisito: necesitás Windows + Power BI Desktop + Python 3.10+ + `pipx` + `pbi-cli-tool` (si te falta algo, el skill te guía).
+El siguiente paso lógico es abrir Power BI Desktop y diseñar el reporte manualmente sobre este modelo.
 
-¿Arrancamos con /bi-report, o preferís agregar más medidas al modelo primero?
+¿Preferís seguir agregando medidas al modelo primero?
 ```
 
-If the user opts for reports, load `/bi-report` and let it run. If they want to keep modeling, stay on this skill.
+If the user wants to keep modeling, stay on this skill. If they want reports, hand off to the user for manual Desktop authoring.
 
 ---
 
 ## What this skill does NOT do
 
 - **No scoring / benchmarking** of an existing model. For that, the user can ask "audit this model" separately.
-- **Report authoring** is delegated to `/bi-report` which uses bundled Node scripts plus the `pbi` CLI runtime flow — don't write `.Report/` files from here.
+- **Report authoring** is not handled here. Keep this skill focused on semantic-model setup.
+- **No direct PBIP edits**. Do not patch `.SemanticModel/`, `.Report/`, TMDL, PBIR JSON, `visual.json`, visual bindings, slicer/card settings, themes, or report resources directly. The only allowed report-side mutation is the dedicated plugin field-swap/rebind command for existing template visuals; if it is not available, hand off manual Desktop steps.
 
 ---
 

package/skills/bi-kickoff/scripts/update-check.js

@@ -47,7 +47,7 @@ const HTTPS_TIMEOUT_MS = 5000;
 // Rewritten at generation time when this helper is copied into
 // `skills/<name>/scripts/update-check.js`. In the canonical source under
 // `bin/commands/`, it stays null and we fall back to package.json.
-const BUNDLED_INSTALLED_VERSION = "5.0.0";
+const BUNDLED_INSTALLED_VERSION = "5.0.1";
 
 // ---------------------------------------------------------------------------
 // Argument parsing