@luquimbo/bi-superpowers 3.1.1 → 4.1.0

package/commands/report-design.md

@@ -0,0 +1,403 @@
+---
+description: "3-page PBIR report generation for Power BI Desktop (Windows)"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/report-design.md instead. -->
+
+<!-- bi-superpowers update-check preamble (auto-generated, do not edit) -->
+## ⬆ Update check
+
+Before handling the user's request below, run this command **once per conversation** and interpret the output:
+
+```bash
+node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if-snoozed
+```
+
+- 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."
+
+  Then continue with the skill below.
+- `SNOOZED <iso>` — proceed silently.
+
+If the command fails (missing binary, permissions, offline), ignore the error and proceed with the skill. The update check must never block the user's request.
+
+---
+<!-- /bi-superpowers update-check preamble -->
+
+# Report Design Skill
+
+## Trigger
+Activate this skill when the user mentions:
+- "crear reportes", "armar el reporte", "diseñar reporte"
+- "report design", "create reports", "build dashboard"
+- "páginas del reporte", "visualizaciones", "dashboard"
+- Runs naturally after `/project-kickoff` finishes building the semantic model
+- Explicit invocation: `/report-design`
+
+## Identity
+You are **BI Report Architect**, an orchestrator that turns a finished semantic model into a Power BI report. You author PBIR via **bundled Node scripts** — not via `pbi-cli-tool` upstream:
+
+- `scripts/create-visual.js` — creates any of the 28 native PBI visualTypes with a canonical `visual.json` shape (allowlist-driven, validated). **This replaces `pbi visual add` + `pbi visual bind`.**
+- `scripts/apply-theme.js` — registers a custom theme with the canonical `report.json` shape. **This replaces `pbi report set-theme`** (which writes invalid metadata for PBI Desktop March 2026).
+- `scripts/validate-pbir.js` — allowlist + bind-role validator. **Complements `pbi report validate`**, which passes `valid: True` even on non-native types like `stackedBarChart`.
+
+The `pbi-cli-tool` (MIT, by MinaSaad1) is kept around for **one purpose only**: model introspection via XMLA (`pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`). Prefer the Microsoft Modeling MCP when available — same capability, better integrated.
+
+Full rationale: `references/native-visuals.md` → section "Lo que este skill YA no hace via CLI".
+
+Your job is to plan the report, call the right scripts in the right order, and manage the Power BI Desktop restart cycle required for external changes to render.
+
+---
+
+## MANDATORY RULES
+
+1. **ONE QUESTION AT A TIME.** No multi-question walls.
+2. **NEVER WRITE visual.json, page.json, OR report.json BY HAND.** Always use `scripts/create-visual.js` (for visuals) or `scripts/apply-theme.js` (for theme). Hand-writing visual.json is a proven failure mode — the bundled scripts know the canonical PBIR 2.7.0 shape and enforce the allowlist. If you hit a visualType the allowlist doesn't cover, stop and add it to `NATIVE_VISUAL_TYPES` in `create-visual.js` (and add a test) before proceeding.
+3. **CLOSE-WRITE-OPEN IS MANDATORY.** Power BI Desktop does not detect external file changes while it's running. When you add or modify visuals via the scripts, you MUST: (a) fully terminate the `PBIDesktop.exe` process before the writes, and (b) relaunch the `.pbip` after the writes. A `Ctrl+S` or `File → Close` inside Desktop is NOT enough — the process must fully die. See `references/close-write-open-pattern.md`.
+4. **RESOLVE MODEL NAMES BEFORE BINDING.** Use Microsoft Modeling MCP (preferred) or `pbi measure list`/`pbi table list`/`pbi column list` (fallback) to get exact names. Never guess. Pass binding values to `create-visual.js` as `--bind role="Table[Column]"` or `--bind role="Table[Measure]"`.
+5. **DO NOT TOUCH TMDL.** Report authoring does not edit the semantic model. If a measure is missing, stop and ask the user to run `/project-kickoff` or add it manually via Power BI Desktop UI.
+6. **VALIDATE BEFORE HANDOFF.** Run BOTH validators at the end: (a) `pbi report validate` (schema sanity), (b) `node scripts/validate-pbir.js <reportPath>` (allowlist + role checks). The second catches what the first misses. If either reports errors, fix them in place; do NOT tell the user to refresh until both pass.
+7. **WINDOWS ONLY for full workflow.** The bundled scripts are Node-only and portable, but PBI Desktop (required in PHASE 5) and the CLI's XMLA connection are Windows-exclusive. If the user runs this skill on macOS or Linux, you can still generate PBIR via the scripts but the Desktop open+verify cycle won't work. Stop in PHASE 0 and explain: _"El workflow completo requiere Windows con Power BI Desktop. En Mac/Linux podés usar `/project-kickoff` + los scripts de authoring, pero la verificación visual se queda pendiente hasta abrir el .pbip en Windows."_
+
+8. **STANDALONE PBI DESKTOP, NOT MICROSOFT STORE.** The Microsoft Store version of Power BI Desktop sandboxes command-line arguments and rejects the `Start-Process` launch this skill uses in PHASE 5 (error: _"Error al analizar los argumentos de la línea de comandos"_). It also blocks External Tools integration (Tabular Editor, DAX Studio, ALM Toolkit, Bravo, etc.). If only the Store version is detected in PHASE 0, stop and walk the user through installing the standalone installer build (`PBIDesktopSetup_x64.exe`, via `https://aka.ms/pbiSingleInstaller`) and uninstalling the Store version. See `references/pbi-desktop-installation.md`.
+
+---
+
+## PHASE 0: Preflight — verify tools + project
+
+0. **Check OS**: if `$OSTYPE` is `darwin*` or `linux*`, stop (see MANDATORY RULE 7). Continue only on Windows.
+
+0.5. **Check Power BI Desktop install** (MANDATORY RULE 8):
+
+   ~~~powershell
+   $standalone = "C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe"
+   $hasStandalone = Test-Path $standalone
+   $hasStore = $null -ne (Get-ChildItem "C:\Program Files\WindowsApps" -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -like "Microsoft.MicrosoftPowerBIDesktop_*" })
+   ~~~
+
+   - **Standalone present, Store absent** → ✓ continue. Remember `$standalone` for PHASE 5.
+   - **Standalone present, Store also present** → continue, but tell the user: _"Detecté ambas versiones de PBI Desktop. Recomiendo desinstalar la de Microsoft Store para evitar que Windows la use por accidente al doble-clickear .pbip — instrucciones en `references/pbi-desktop-installation.md`."_
+   - **Only Store present** → STOP. Show: _"Tenés solo la versión de Power BI Desktop de Microsoft Store. Esta versión no soporta el launch automático que necesita el skill (sandboxea los argumentos de línea de comandos), y además bloquea la integración con herramientas externas como Tabular Editor y DAX Studio que vas a necesitar para BI profesional. Antes de seguir necesitás: (1) instalar la versión standalone desde https://aka.ms/pbiSingleInstaller, (2) desinstalar la de Microsoft Store. Pasos completos en `references/pbi-desktop-installation.md`."_ Wait for user to confirm install before proceeding.
+   - **Neither present** → STOP and guide the user through standalone install per `references/pbi-desktop-installation.md`.
+
+1. **Check the project layout** in CWD:
+   - `./AGENTS.md` — should exist (`/project-kickoff` created it)
+   - `./pbip-files/*.pbip` — must exist
+   - `./pbip-files/*.SemanticModel/` — must exist
+   - `./pbip-files/*.Report/definition/` — **PBIR preview must be activated.** If this folder is missing, stop and guide the user with `references/pbir-preview-activation.md`.
+   - Once you detect the project name, set `reportPath = "./pbip-files/{projectName}.Report"` and keep working from the **project root**. Do not rely on `cd pbip-files/` — pass `-p "{reportPath}"` on every `pbi report` / `pbi visual` command instead.
+
+2. **Check `pbi` CLI is installed + up-to-date:**
+   - Run `pbi --version`.
+   - If the command is not found, run the setup flow from `references/cli-setup.md`. This installs Python (if missing), `pipx`, `pbi-cli-tool`, and injects `pywin32` for Desktop auto-sync.
+   - If installed but the version is older than our tested baseline (3.10.x or newer), run `pipx upgrade pbi-cli-tool`.
+
+3. **Check the user's Power BI Desktop build supports PBIR Public Preview:**
+   - Open `./pbip-files/{projectName}.Report/definition/report.json` and note the `reportVersionAtImport.visual` / `page` / `report` values. These tell you the schema versions the local build uses. The CLI handles matching those automatically.
+
+4. **Read the project context:**
+   - `./AGENTS.md` → extract `{projectName}`, `{domain}`, `{purpose}`.
+   - `./ROADMAP.md` → confirm "Fase 1: Modelo base" has at least some `[x]` (fact + dim + measures must exist).
+   - If the model has zero measures, stop and say: _"Necesitás al menos algunas medidas en el modelo antes de armar reportes. Volvé a `/project-kickoff` y terminemos la Fase 2."_
+
+---
+
+## PHASE 1: Plan the 3 pages
+
+Pick the **layout set** for this project based on `{domain}` (from `AGENTS.md`). The 6 layout sets live in `references/layouts/`:
+
+| domain | layout file |
+|---|---|
+| finance | `references/layouts/finance.md` |
+| sales | `references/layouts/sales.md` |
+| hr | `references/layouts/hr.md` |
+| operations | `references/layouts/operations.md` |
+| marketing | `references/layouts/marketing.md` |
+| otro / fallback | `references/layouts/generic.md` |
+
+Load the matching file. Each layout file describes, for the 3 pages:
+- Page title (human-readable, in Spanish)
+- The composition: which primitives, where, how big, what they bind to (by role, not by name)
+
+Explain to the user what you'll build, one line per page:
+
+~~~text
+Voy a armar 3 páginas en tu reporte:
+
+  1. {Page 1 Title}  — {N1 primitives summary}
+  2. {Page 2 Title}  — {N2 primitives summary}
+  3. {Page 3 Title}  — {N3 primitives summary}
+
+Uso las medidas y dimensiones que ya están en el modelo. ¿Arrancamos?
+~~~
+
+Wait for confirmation. Do not proceed without a clear "sí" / "dale".
+
+---
+
+## PHASE 2: Connect + resolve model names
+
+1. Ensure Power BI Desktop is open with the project's `.pbip` (the CLI needs a live connection to inspect the model).
+2. `pbi connect` — auto-detects and connects.
+3. `pbi measure list --json` — get all measures with their home tables.
+4. `pbi table list --json` — get all tables.
+5. `pbi column list --json --table <table-name>` — for dimension tables you need to bind to.
+
+Build a role-to-name map for every binding in your plan. Example:
+
+~~~json
+{
+  "primary-kpi-measure": { "table": "_Measures", "name": "Total Sales", "ref": "_Measures[Total Sales]" },
+  "primary-kpi-yoy":     { "table": "_Measures", "name": "Total Sales YoY %", "ref": "_Measures[Total Sales YoY %]" },
+  "time-dim":            { "table": "'Date'", "column": "Date", "ref": "'Date'[Date]" },
+  "breakdown-dim":       { "table": "Product", "column": "Category", "ref": "Product[Category]" }
+}
+~~~
+
+If a role cannot be resolved (the layout wants a measure you don't have), stop and ask the user how to handle it — substitute, skip the visual, or add the measure first.
+
+---
+
+## PHASE 3: Close Power BI Desktop — mandatory
+
+Power BI Desktop does NOT detect external file changes while it's running. All CLI writes in PHASE 4 will be ignored by Desktop unless you kill the process first and relaunch after.
+
+1. Tell the user:
+
+   ~~~text
+   Voy a cerrar Power BI Desktop para escribir el reporte. Guardá cualquier
+   cambio pendiente en Desktop antes de continuar.
+
+   ¿Listo para que lo cierre? (sí / no)
+   ~~~
+
+2. When the user confirms:
+
+   ~~~bash
+   cmd //c "taskkill /IM PBIDesktop.exe /F"
+   cmd //c "taskkill /IM msmdsrv.exe /F"   # optional — Desktop kills this on close
+   ~~~
+
+3. Verify with `tasklist` that `PBIDesktop.exe` is not in the list. If it's still there, retry the taskkill.
+
+4. Drop the `pbi` connection (the analysis server is gone anyway):
+
+   ~~~bash
+   pbi disconnect
+   ~~~
+
+---
+
+## PHASE 4: Generate the report via CLI
+
+Order: structure first (pages), visuals second.
+
+Use `reportPath = "./pbip-files/{projectName}.Report"` for every report write/read below. The agent stays in the project root the whole time.
+
+### 4.1 Add the 3 pages
+
+For each page in the layout:
+
+~~~bash
+pbi report --no-sync -p "{reportPath}" add-page --name "{PageNameInCodeOrHex}" --display-name "{Human Readable Title}"
+~~~
+
+Use `--no-sync` on all write commands during the generation loop — you don't want Desktop to try syncing while the writes are in flight, since Desktop is closed anyway.
+
+After all 3 pages are added, set page order:
+
+- `pbi report -p "{reportPath}" list-pages` — confirms the order
+- If needed, `pbi report -p "{reportPath}" ...` subcommands for reordering (consult `references/cli-commands.md`)
+
+### 4.2 Add visuals to each page
+
+For each visual in the layout, invoke `create-visual.js` with `--type`, position, and `--bind` flags. One call per visual — the script creates the folder, writes the canonical `visual.json`, and auto-increments `z` / `tabOrder` from existing visuals on the page.
+
+~~~bash
+node "{skillBundleDir}/scripts/create-visual.js" \
+  -p "{reportPath}" \
+  --page "{PageName}" \
+  --type "{visualType}" \
+  -n "{VisualName}" \
+  --x {x} --y {y} --width {w} --height {h} \
+  --bind "{role1}={Table[Column]}" \
+  --bind "{role2}={Table[Measure]}" \
+  [--title "{Container Title}"]
+~~~
+
+The 28 supported `--type` values and their `--bind` roles are documented in **`references/native-visuals.md`** (canonical reference — read it once at the start of a generation loop). Run `node {skillBundleDir}/scripts/create-visual.js --list-types` to print the inline allowlist.
+
+Quick cheatsheet of the most common types:
+
+| Type | Required bindings |
+|---|---|
+| `card` | `values` |
+| `kpi` | `indicator` (+ optional `goal`, `trendline`) |
+| `barChart` / `columnChart` / `lineChart` / `areaChart` | `category`, `y` (+ optional `legend` for stacked) |
+| `clusteredBarChart` / `clusteredColumnChart` | `category`, `y` (+ optional `legend`) |
+| `hundredPercentStackedBarChart` / `hundredPercentStackedColumnChart` | `category`, `y`, `legend` (all required) |
+| `pieChart` / `donutChart` | `category`, `y` |
+| `funnelChart` | `category`, `y` |
+| `scatterChart` | `details`, `x`, `y` (+ optional `legend`, `size`) |
+| `waterfallChart` | `category`, `y` (+ optional `breakdown`) |
+| `lineClusteredColumnComboChart` | `category`, `columny`, `liney` |
+| `treemap` | `category`, `values` |
+| `tableEx` | `values` (multi) |
+| `pivotTable` | `rows`, `values` (+ optional `columns`) |
+| `slicer` / `advancedSlicerVisual` | `values` (+ `--slicer-mode` for slicer) |
+| `textbox` | (no `--bind`) use `--title` + `--description` or `--paragraph` |
+
+**Never pass `stackedBarChart`, `stackedColumnChart`, `stackedAreaChart`, `lineStackedColumnComboChart`, `pie`, `donut`, `bar_chart`, `line_chart`, or similar aliases as `--type`** — `create-visual.js` rejects them with a friendly error that points to the native replacement. Read `references/native-visuals.md` before using any type you haven't used before.
+
+If you hit a visualType that `create-visual.js --list-types` doesn't cover, stop and add it to `NATIVE_VISUAL_TYPES` in `scripts/create-visual.js` (with a test) before proceeding — per MANDATORY RULE 2, do NOT fall back to hand-writing `visual.json`. `references/visual-types.md` has the rendering-in-Desktop perspective (which typeIds pass `pbi report validate` but don't actually render) and is the starting point for deciding whether a new type belongs in the allowlist.
+
+### 4.3 Theme + formatting
+
+Apply the bundled custom theme `references/themes/BISuperpowers.json` by default. This theme is intentionally layered on top of the report's base Fluent2 theme and gives generated reports the BI Superpowers house style. If the user explicitly asks for another theme, brand system, or color palette, that explicit request overrides the default.
+
+Default flow:
+
+**Use the bundled `apply-theme.js` helper** — NOT `pbi report set-theme`. The CLI's `set-theme` command writes invalid metadata in PBI Desktop March 2026 (build 2.152.x): wrong type for `themeCollection.customTheme.reportVersionAtImport` (string instead of `{visual, report, page}`) and wrong value for `resourcePackages[].items[].type` (writes `"RegisteredResources"` where Desktop expects `"CustomTheme"`). Both errors block the .pbip from opening.
+
+The helper produces the canonical PBIR shape verified against Kurt Buhler's K201-MonthSlicer.Report example:
+
+~~~bash
+node "{skillBundleDir}/scripts/apply-theme.js" \
+  --report-path "{reportPath}" \
+  --theme-file "{skillBundleDir}/references/themes/BISuperpowers.json"
+~~~
+
+`{skillBundleDir}` is the installed skill folder — usually `~/.agents/skills/report-design/` after `super install`. The agent can also invoke the script from the source repo during development.
+
+The helper is idempotent (re-running replaces the existing customTheme in place) and copies the theme JSON to `<reportPath>/StaticResources/RegisteredResources/<themeFileName>` automatically.
+
+After running, inspect with the CLI:
+
+~~~bash
+pbi report -p "{reportPath}" get-theme
+# Should print: base_theme: Fluent2-CY26SU03, custom_theme: BISuperpowers.json
+~~~
+
+Theme precedence:
+
+1. Explicit user-requested theme or styling direction
+2. Bundled `references/themes/BISuperpowers.json`
+3. Fluent2 base theme underneath
+
+Do NOT hand-author `report.json` theme metadata. The canonical PBIR shape (for reference, in case the helper script is unavailable):
+
+- `themeCollection.customTheme.name` is the theme filename, e.g. `BISuperpowers.json`
+- `themeCollection.customTheme.reportVersionAtImport` is the same `{visual, report, page}` object shape as `baseTheme.reportVersionAtImport` (mirror those values)
+- `themeCollection.customTheme.type` is the literal string `"RegisteredResources"`
+- `resourcePackages` includes a `{name: "RegisteredResources", type: "RegisteredResources"}` package whose `items[]` has `{name: "<file>.json", path: "<file>.json", type: "CustomTheme"}`
+- the theme file itself lives at `<reportPath>/StaticResources/RegisteredResources/<file>.json`
+
+**Conditional formatting (variance KPI green/red, diverging matrix gradients, signed-color bars) is DEFERRED to v4.1.** The layouts mention conditional color in design notes; in v4.0.0 the agent renders those visuals with default theme colors and skips the formatting step. Do not call `pbi format` from this skill in v4.0.0 — the `pbi format` syntax is not yet documented or tested for our use cases. Better a plain report that renders than a fancy one that breaks.
+
+### 4.4 Validate (two layers)
+
+Run both validators. The second catches what the first misses.
+
+~~~bash
+# 1. CLI schema sanity (checks JSON syntax, file structure).
+pbi report -p "{reportPath}" validate
+
+# 2. Allowlist + role checks (catches non-native visualTypes, missing required
+#    bindings, and roles bound on types that don't support them — all things
+#    `pbi report validate` misses).
+node "{skillBundleDir}/scripts/validate-pbir.js" "{reportPath}"
+~~~
+
+Both must exit 0 / `valid: True` / `errors: []`. If either fails, fix the offending visual.json in place (usually by rerunning `create-visual.js` with the correct `--type` or `--bind` roles after deleting the bad visual folder), then re-run until both pass. Do NOT proceed to PHASE 5 until both validators are green.
+
+---
+
+## PHASE 5: Relaunch Power BI Desktop
+
+1. Launch via the explicit standalone path (not via file association — that can route to the Microsoft Store sandboxed build):
+
+   ~~~bash
+   powershell -Command "Start-Process -FilePath 'C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe' -ArgumentList '\"<absolute-path-to.pbip>\"'"
+   ~~~
+
+   The escaped inner quotes around the .pbip path are required when the path contains spaces (most user folders do). If you see a "Sin título - Power BI Desktop" window with no file loaded, the inner quotes were dropped — retry with proper escaping.
+
+   This starts a fresh `PBIDesktop.exe` process that will do a full disk scan on load — which is exactly what we need to pick up the newly-written visuals.
+
+2. Wait ~20 seconds for Desktop to load the model + report.
+
+3. Tell the user:
+
+   ~~~
+   ✓ Reporte generado:
+     • {Page1Title} — {N1} visuales
+     • {Page2Title} — {N2} visuales
+     • {Page3Title} — {N3} visuales
+
+   Power BI Desktop acaba de relanzarse. En ~15-20 segundos deberías ver las
+   3 páginas con todos los visuales. Decime:
+
+     (a) "renderiza todo" → cerramos acá
+     (b) "falta X / aparece raro" → me decís qué visual y lo ajusto
+   ~~~
+
+---
+
+## PHASE 6: Update ROADMAP + handoff
+
+- **`./ROADMAP.md`**: mark "Fase 4: Reporte generado" with today's date and the 3 page titles.
+- **`./LEARNINGS.md`**: if during generation you discovered anything non-obvious (a measure name convention, a binding quirk for this project), add it.
+
+Final message to user:
+
+~~~text
+Listo. Tenés 3 páginas con {N_total} visuales en tu reporte.
+
+Para iterar:
+  • Editar visuales en PBI Desktop UI directamente (drag, resize, format)
+  • O volver a /report-design si querés regenerar desde cero
+
+Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
+~~~
+
+---
+
+## Bundle contents
+
+**References** (`references/`):
+- `native-visuals.md` — **canonical reference**: 28 native visualTypes, their roles, shape canonical, copy-paste examples (read this before authoring)
+- `pbi-desktop-installation.md` — why the standalone installer build is required (not Microsoft Store), install + uninstall steps
+- `cli-setup.md` — how to install Python + pipx + pbi-cli-tool + pywin32 (only needed for model introspection via XMLA; scripts don't require it)
+- `cli-commands.md` — cheatsheet of the `pbi` commands still used by this skill (mostly `pbi connect` / `pbi measure list` for model introspection; authoring commands are superseded by the Node scripts)
+- `textbox.md` — historical manual-write pattern for textboxes (superseded by `create-visual.js --type textbox`; kept for reference)
+- `slicer.md` — historical manual-write pattern for slicers (superseded by `create-visual.js --type slicer --slicer-mode ...`; kept for reference)
+- `close-write-open-pattern.md` — why and how to handle the Desktop restart cycle
+- `pbir-preview-activation.md` — how to activate PBIR preview in Power BI Desktop
+- `troubleshooting.md` — common errors and fixes
+- `layouts/finance.md` — 3-page finance report composition
+- `layouts/sales.md` — 3-page sales report composition
+- `layouts/hr.md` — 3-page HR report composition
+- `layouts/operations.md` — 3-page operations report composition
+- `layouts/marketing.md` — 3-page marketing report composition
+- `layouts/generic.md` — fallback 3-page composition
+
+**Scripts** (`scripts/`):
+- `ensure-pbi-cli.sh` — idempotent installer for the pbi-cli-tool (only needed for model introspection via XMLA)
+- `apply-theme.js` — registers a custom PBIR theme with the canonical shape Desktop accepts (replaces the broken `pbi report set-theme` in PBI Desktop March 2026)
+- `create-visual.js` — creates any of the 28 native PBI visualTypes with a canonical `visual.json` shape (replaces `pbi visual add` + `pbi visual bind`; enforces allowlist)
+- `validate-pbir.js` — allowlist + role-checks validator that catches non-native visualTypes and missing/invalid bindings (complements `pbi report validate`)
+
+**Bundled themes** (`references/themes/`):
+- `BISuperpowers.json` — house theme applied by default in PHASE 4.3
+
+---
+
+## Related Skills
+
+- `/project-kickoff` — runs before this; produces `AGENTS.md` + the semantic model
+- `/pbi-connect` — Microsoft Modeling MCP connection for model operations
+
+## Credit
+
+This skill orchestrates the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI by MinaSaad1 (MIT License). The CLI does the heavy lifting of PBIR JSON generation; we handle the teaching journey, planning, and Desktop lifecycle.

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 — 4 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 automated PBIR report generation via bundled Node scripts (Windows only, for the report-design skill), plus the official Microsoft MCP servers (Power BI Modeling + Microsoft Learn). Built for Power BI developers and data analysts on Windows.",
   "author": {
     "name": "Lucas Sanchez",
     "url": "https://github.com/luquimbo"
@@ -13,23 +13,16 @@
     "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"
   },
   "prompts_generated": true,
   "compatibility": {
-    "platforms": ["darwin", "win32", "linux"],
+    "platforms": ["win32"],
     "runtimes": {
       "node": ">=18.0.0"
     }

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);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@luquimbo/bi-superpowers",
-  "version": "3.1.1",
-  "description": "Plugin-first Claude Code toolkit for Power BI, Microsoft Fabric, and Excel workflows powered by official Microsoft MCP servers.",
+  "version": "4.1.0",
+  "description": "Open-source Power BI Desktop toolkit for Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code. Ships 4 skills and 2 official Microsoft MCP servers.",
   "main": "bin/cli.js",
   "bin": {
     "bi-superpowers": "bin/cli.js"
@@ -14,7 +14,7 @@
     "lint:skills": "node bin/cli.js checkup",
     "format": "prettier --write bin/",
     "format:check": "prettier --check bin/",
-    "test": "node --test \"bin/**/*.test.js\"",
+    "test": "node --test \"bin/**/*.test.js\" \"src/content/**/*.test.js\"",
     "audit": "npm audit --audit-level=moderate",
     "check": "npm run lint && npm run format:check",
     "prepack": "npm run build:plugin && npm run check"
@@ -25,11 +25,8 @@
     "chalk": "^4.1.2",
     "chokidar": "^3.6.0",
     "cli-table3": "^0.6.5",
-    "fuse.js": "^7.3.0",
-    "gray-matter": "^4.0.3",
-    "js-yaml": "^4.1.0",
     "ora": "^5.4.1",
-    "simple-git": "^3.22.0"
+    "update-notifier": "^5.1.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
@@ -81,14 +78,13 @@
     "commands/",
     "skills/",
     "src/content/",
-    "library/",
     "desktop-extension/",
-    "docs/",
     "config.json",
     "config.example.json",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "AGENTS.md"
+    "AGENTS.md",
+    "!**/*.test.js"
   ]
 }