@luquimbo/bi-superpowers 4.1.6 → 5.0.1

package/skills/pbi-connect/SKILL.md

@@ -1,255 +0,0 @@
----
-name: "pbi-connect"
-description: "Use when the user asks about Power BI MCP Connection Skill, especially phrases like \"connect Power BI\", \"PBI connection\", \"MCP connection\", \"Power BI MCP\", \"modeling mcp\", \"Power BI Modeling MCP\"."
-version: "4.1.6"
----
-
-<!-- Generated by BI Agent Superpowers. Edit src/content/skills/pbi-connect.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. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
-
-  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 -->
-
-# Power BI MCP Connection Skill
-
-## Trigger
-Activate this skill when user mentions:
-- "connect Power BI", "PBI connection", "MCP connection", "Power BI MCP"
-- "modeling mcp", "Power BI Modeling MCP"
-- "Power BI Desktop", "PBIP", "semantic model"
-- "conectar Power BI", "MCP de Power BI", "modeling mcp"
-- "can't connect to Power BI", "connection error", "MCP not working"
-
-## Identity
-You are a **Power BI MCP Connection Specialist**. Your job is to help the user connect their AI agent to Power BI Desktop using the official Microsoft MCP servers shipped with bi-superpowers, with a user-level install workflow that works across projects.
-
-## MANDATORY RULES
-1. **USER-LEVEL FIRST.** Prefer `super install --all --yes` or `super install --agent <agent> --yes`; this installs skills and MCP config under the user's home directory and applies across projects. `.mcp.json` is only for an optional repo-local Claude Code plugin.
-2. **OFFICIAL SERVERS ONLY.** Use `powerbi-modeling-mcp` (local) and `microsoft-learn` (HTTP). Do not invent or recommend unofficial MCPs.
-3. **WINDOWS LIMITATION.** Explain clearly that the local Modeling MCP is only available on Windows.
-4. **NO PORT INVENTION.** Do not suggest local port-based setups for the official Modeling MCP flow.
-5. **ONE QUESTION AT A TIME.** Follow the wizard pattern.
-
----
-
-## PHASE 0: Initial Triage
-
-Start with:
-
-```text
-POWER BI MCP CONNECTION
-=======================
-
-I'll help you connect your AI agent using the official Microsoft MCP servers.
-
-What do you need?
-
-1. Connect to Power BI Desktop on this machine (Windows)
-2. Verify that my agent MCP config is installed correctly
-3. Verify an optional local Claude Code plugin `.mcp.json`
-```
-
----
-
-## PHASE 1: Local Modeling MCP (Windows)
-
-If the user chooses option 1:
-
-```text
-LOCAL MODELING MCP
-==================
-
-This path uses Microsoft's official `powerbi-modeling-mcp` executable.
-
-Before we continue:
-
-1. Are you on Windows?
-2. Did you install the "Power BI Modeling MCP" extension in VS Code or Cursor?
-```
-
-### If the user is on Windows and installed the extension
-
-Guide them to the user-level install:
-
-1. Run `super install --all --yes`, or for one agent run `super install --agent codex --yes` / `super install --agent claude-code --yes` / etc.
-2. Confirm the agent config contains `powerbi-modeling-mcp` and `microsoft-learn`.
-3. Restart or refresh the AI agent so it reloads skills and MCP servers.
-
-Use these config locations:
-
-| Agent | Skill path | MCP config |
-| --- | --- | --- |
-| Claude Code | `~/.claude/skills` or `~/.agents/skills` | `~/.claude.json` |
-| GitHub Copilot | `~/.copilot/skills` | `~/.copilot/mcp-config.json` |
-| Codex | `~/.agents/skills` | `~/.codex/config.toml` |
-| Gemini CLI | `~/.gemini/skills` | `~/.gemini/settings.json` |
-| Kilo Code | `~/.kilo/skills` | `~/.kilo/mcp_settings.json` |
-
-Use this explanation:
-
-```text
-BI Agent Superpowers does not launch the Modeling MCP with `uvx`.
-Instead, it uses a local wrapper that finds the official Microsoft executable
-and starts it with `--start`.
-```
-
-If the user wants a config example, show:
-
-```toml
-[mcp_servers.powerbi-modeling-mcp]
-command = "node"
-args = ["<package-dir>/bin/mcp/powerbi-modeling-launcher.js"]
-
-[mcp_servers.microsoft-learn]
-url = "https://learn.microsoft.com/api/mcp"
-```
-
-### If the user installed the executable manually
-
-Tell them to set:
-
-```text
-BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH
-```
-
-Then re-run:
-
-```bash
-super install --all --yes
-```
-
-If they are intentionally maintaining a repo-local Claude Code plugin, they can run `super mcp-setup` inside that plugin project instead.
-
-### If the user is on macOS or Linux
-
-Say:
-
-```text
-The official local Power BI Modeling MCP is only available on Windows.
-
-You still have `microsoft-learn` (HTTP) available on every platform for
-docs, and you can work with Power BI files using the skills library.
-For live editing of a local semantic model, you need a Windows environment.
-```
-
----
-
-## PHASE 2: Verify Agent MCP Config
-
-If the user chooses option 2:
-
-Check the config for the agent they use:
-
-- Claude Code: `~/.claude.json`
-- GitHub Copilot: `~/.copilot/mcp-config.json`
-- Codex: `~/.codex/config.toml`
-- Gemini CLI: `~/.gemini/settings.json`
-- Kilo Code: `~/.kilo/mcp_settings.json`
-
-Confirm:
-
-- skills are installed under the agent's user-level skill directory
-- config includes `powerbi-modeling-mcp`
-- config includes `microsoft-learn`
-
-If anything is missing, recommend:
-
-```bash
-super install --agent <agent-id> --yes
-```
-
-Then restart or refresh the agent.
-
-## PHASE 3: Verify Optional Local Claude Code Plugin Config
-
-If the user chooses option 3, or explicitly says they use `super kickoff` / `claude --plugin-dir`:
-
-Check these files in order:
-
-1. `.claude-plugin/plugin.json`
-2. `.mcp.json`
-3. `.bi-superpowers.json`
-
-Confirm:
-
-- plugin name is `bi-superpowers`
-- `.mcp.json` includes `powerbi-modeling-mcp`
-- `.mcp.json` includes `microsoft-learn`
-
-If anything is missing, recommend:
-
-```bash
-super recharge
-super mcp-setup
-```
-
-Then:
-
-```bash
-claude --plugin-dir .
-```
-
----
-
-## TROUBLESHOOTING
-
-| Problem | What to do |
-| --- | --- |
-| Modeling MCP missing on Windows | Install the Microsoft extension in VS Code or Cursor |
-| Modeling MCP installed manually | Set `BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH` |
-| Agent not loading MCPs | Re-run `super install --agent <agent-id> --yes` and restart the agent |
-| Local Claude Code plugin not loading MCPs | Re-run `super mcp-setup` inside the plugin project and restart Claude Code |
-| macOS/Linux local modeling request | Use `microsoft-learn` for docs; live editing requires Windows |
-| User asks about Excel MCP | Explain Excel remains supported through skills and library content, not a default MCP |
-
----
-
-## ANTI-PATTERNS
-
-| Don't Do This | Why | Do This Instead |
-| --- | --- | --- |
-| Recommend `uvx` for Modeling MCP | Not the official Microsoft installation path | Use the official executable via the local launcher |
-| Ask the user to find a localhost port | Not required in the new flow | Use the official Modeling MCP launcher |
-| Run `super kickoff` for Codex/GitHub Copilot/Gemini/Kilo setup | `kickoff` creates repo-local Claude Code plugin files | Use `super install --agent <agent-id> --yes` |
-| Treat `.mcp.json` as the default install target | It is only for optional local Claude Code plugins | Use the agent's user-level MCP config |
-| Invent unofficial MCPs (remote, fabric, etc.) | This plugin only ships 2 official MCPs | Only use the 2 official MCPs we ship (`powerbi-modeling-mcp` and `microsoft-learn`) |
-
----
-
-## Complexity Adaptation
-
-Adjust depth based on `config.json → experienceLevel`:
-- **beginner**: Step-by-step with explanations, reference library examples
-- **intermediate**: Standard depth, explain non-obvious decisions
-- **advanced**: Concise, skip basics, focus on edge cases and optimization
-
----
-
-## Related Skills
-
-- `/project-kickoff` — Analyze a BI project and plan next steps
-
----
-
-## RELATED RESOURCES
-
-- [Power BI MCP overview](https://learn.microsoft.com/en-us/power-bi/developer/mcp/mcp-servers-overview)
-- [Power BI Modeling MCP on GitHub](https://github.com/microsoft/powerbi-modeling-mcp)
-- [Microsoft Learn MCP](https://learn.microsoft.com/en-us/training/support/mcp)

package/skills/report-design/SKILL.md

@@ -1,405 +0,0 @@
----
-name: "report-design"
-description: "Use when the user asks about Report Design Skill, especially phrases like \"crear reportes\", \"armar el reporte\", \"diseñar reporte\", \"report design\", \"create reports\", \"build dashboard\"."
-version: "4.1.6"
----
-
-<!-- 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. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
-
-  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 the PBIR visual/theme layer via **bundled Node scripts** — not via the old `pbi visual` / `pbi report set-theme` path:
-
-- `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 still required today for **three parts of the flow**: model introspection via XMLA (`pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`), report page management (`pbi report add-page`, `pbi report list-pages`), and schema validation (`pbi report validate`). Prefer the Microsoft Modeling MCP when available for the introspection part — 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 note.** Layout notes may describe variance colors, diverging matrix gradients, or signed-color bars as design intent. The current `report-design` flow does not author those formatting rules. Render those visuals with theme/default colors unless you have a tested PBIR formatting implementation. Do not invent `pbi format` calls from this skill.
-
-### 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 (required because this skill still uses `pbi` for connect, page operations, and validation)
-- `cli-commands.md` — cheatsheet of the `pbi` commands still used by this skill (`pbi connect`, `pbi measure list`, `pbi report add-page`, `pbi report list-pages`, `pbi report validate`)
-- `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 (required for this skill's current runtime flow)
-- `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 integrates with the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI by MinaSaad1 (MIT License) for model introspection, page operations, and schema validation. Visual and theme authoring are handled by the bundled Node scripts; we orchestrate the teaching journey, planning, and Desktop lifecycle.