@luquimbo/bi-superpowers 3.2.0 → 4.1.0

package/src/content/skills/report-design/SKILL.md

@@ -0,0 +1,376 @@
+# 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/src/content/skills/report-design/references/cli-commands.md

@@ -0,0 +1,184 @@
+# `pbi` CLI — commands this skill still uses
+
+Historical context: this skill used to drive the entire report authoring via `pbi-cli-tool` (MIT, by MinaSaad1). That approach hit 3 regressions (see `native-visuals.md` → "Lo que este skill YA no hace via CLI"), so authoring moved to Node scripts (`apply-theme.js`, `create-visual.js`, `validate-pbir.js`).
+
+The CLI is still useful for:
+
+1. **Model introspection** via XMLA — `pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`. Microsoft Modeling MCP covers the same ground and is preferred when available.
+2. **Page creation** — `pbi report add-page` still works fine.
+3. **Schema-level sanity check** — `pbi report validate` catches malformed JSON, but NOT non-native visualTypes (use `validate-pbir.js` for that).
+
+Everything else (add visual, bind visual, set theme, set-container for style) is superseded. The sections below cover only the supported flows.
+
+All examples assume you're in the project root and `reportPath="./pbip-files/{proj}.Report"`.
+
+---
+
+## Global flags
+
+- `-p, --path <path>` — path to the `.Report` folder. Prefer explicit `-p` over CWD auto-detection.
+- `--no-sync` — skip Desktop auto-sync after writes. **Use during the generation loop** (Desktop is closed in PHASE 3 anyway).
+- `--json` — machine-readable output for scripting.
+
+---
+
+## Model introspection (preferred via Microsoft Modeling MCP)
+
+### Connect (once, after Desktop is open)
+
+```bash
+pbi connect
+```
+
+Auto-detects a running PBI Desktop instance on localhost and connects to its XMLA endpoint. Requires the standalone installer build (Microsoft Store version blocks this).
+
+### List measures / tables / columns
+
+```bash
+pbi measure list --json
+pbi table list --json
+pbi column list --table "{tableName}" --json
+```
+
+Returns arrays of `{table, name, description, ...}` suitable for building a `Table[Field]` ref map to pass to `create-visual.js --bind`.
+
+### Disconnect
+
+```bash
+pbi disconnect
+```
+
+Run before PHASE 3 (kill Desktop), otherwise the CLI keeps a stale socket.
+
+---
+
+## Pages (structure)
+
+### List pages
+
+```bash
+pbi report -p "$reportPath" list-pages
+```
+
+### Add a page
+
+```bash
+pbi report --no-sync -p "$reportPath" add-page \
+  --name "{pageName}" \
+  --display-name "{Display Name}"
+```
+
+- `--name` — internal identifier (also folder name). Short lowercase ASCII or 20-char hex.
+- `--display-name` — what shows on the page tab.
+
+---
+
+## Validation (two layers)
+
+Always run both.
+
+```bash
+# 1. Schema sanity (CLI)
+pbi report -p "$reportPath" validate
+
+# 2. Allowlist + role checks (Node script)
+node "{skillBundleDir}/scripts/validate-pbir.js" "$reportPath"
+```
+
+The CLI's `validate` reports `valid: True` even for `visualType: "stackedBarChart"` (not a native type — Desktop renders it as "objeto visual personalizado"). The Node validator catches that.
+
+---
+
+## Theme
+
+Inspect the current theme:
+
+```bash
+pbi report -p "$reportPath" get-theme
+```
+
+Apply a custom theme **with the bundled helper, NOT `pbi report set-theme`** (the CLI's `set-theme` writes invalid metadata for PBI Desktop March 2026):
+
+```bash
+node "{skillBundleDir}/scripts/apply-theme.js" \
+  --report-path "$reportPath" \
+  --theme-file "{skillBundleDir}/references/themes/BISuperpowers.json"
+```
+
+For the full canonical `report.json` theme shape and why `set-theme` was replaced, see `apply-theme.js` header comment.
+
+---
+
+## Reload Desktop
+
+```bash
+pbi report -p "$reportPath" reload
+```
+
+Sends `Ctrl+Shift+F5` via pywin32. **NOT enough** to pick up externally-written visuals — Desktop must be fully killed and relaunched (see `close-write-open-pattern.md`). Use `reload` only for small in-session refreshes.
+
+---
+
+## Visuals (superseded — use `create-visual.js`)
+
+`pbi visual add`, `pbi visual bind`, `pbi visual update`, `pbi visual delete`, `pbi visual bulk-bind`, `pbi visual set-container` are **no longer driven by this skill**. Reasons:
+
+- `add --type` advertises 5 aliases (`card, line_chart, bar_chart, table, matrix`) but internally accepts ~20 more with PascalCase names. The inconsistency caused the skill's docs to lag behind the CLI's real capabilities.
+- `add --type pie` silently creates a `donutChart` (alias bug).
+- `add --type stackedBarChart` creates a visual with `visualType: "stackedBarChart"` that Desktop rejects at render time — not a native type.
+- `bind` doesn't expose all PBIR roles (`--column`, `--line`, `--x`, `--y`, `--size`, `--breakdown` exist only in `bulk-bind`, not `bind`).
+
+The replacement is a single Node script:
+
+```bash
+node "{skillBundleDir}/scripts/create-visual.js" \
+  -p "$reportPath" \
+  --page "$pageName" \
+  --type "{nativeVisualType}" \
+  -n "{visualName}" \
+  --x {x} --y {y} --width {w} --height {h} \
+  --bind "{role}={Table[Field]}" \
+  [--bind ...]
+```
+
+See `native-visuals.md` for the 27 supported types and their `--bind` roles.
+
+---
+
+## Key conventions (unchanged)
+
+- **Binding syntax is `Table[Field]`**, quoting the table name with single quotes if it has spaces: `'Categorias Finanzas'[Categoria]`.
+- **`--no-sync` on every write** during the generation loop.
+- **`_Measures` prefix convention** — measures live in a hidden `_Measures` table (leading underscore); columns live in their fact or dim table. The Node scripts use this prefix as a disambiguation hint when a role accepts `any` kind (e.g. `tableEx.Values`).
+
+---
+
+## Full end-to-end example
+
+```bash
+# PHASE 0: model introspection
+pbi connect
+pbi measure list --json > measures.json
+
+# PHASE 4.1: page
+pbi report --no-sync -p ./pbip-files/Foo.Report add-page --name overview --display-name "Resumen"
+
+# PHASE 4.2: visuals (via Node script)
+node scripts/create-visual.js -p ./pbip-files/Foo.Report --page overview --type card \
+  -n kpi_revenue --x 24 --y 24 --width 280 --height 120 \
+  --bind values='_Measures[Total Revenue]' --title "Ingresos"
+
+node scripts/create-visual.js -p ./pbip-files/Foo.Report --page overview --type lineChart \
+  -n revenue_trend --x 24 --y 200 --width 816 --height 320 \
+  --bind category='Fecha[Fecha]' --bind y='_Measures[Total Revenue]'
+
+# PHASE 4.3: theme
+node scripts/apply-theme.js --report-path ./pbip-files/Foo.Report --theme-file references/themes/BISuperpowers.json
+
+# PHASE 4.4: validation (both layers)
+pbi report -p ./pbip-files/Foo.Report validate
+node scripts/validate-pbir.js ./pbip-files/Foo.Report
+
+# PHASE 5: relaunch Desktop
+powershell -Command "Start-Process -FilePath 'C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe' -ArgumentList '\"<abs-path.pbip>\"'"
+```

package/src/content/skills/report-design/references/cli-setup.md

@@ -0,0 +1,101 @@
+# CLI setup — installing `pbi-cli-tool`
+
+This skill requires the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI (MIT, by MinaSaad1) and its `pywin32` dependency for Power BI Desktop auto-sync. All commands below are idempotent — running them on an already-set-up system is safe.
+
+## Full setup sequence (run in order)
+
+Check each prerequisite; if it's already satisfied, skip to the next.
+
+### 1. Python 3.10+
+
+```bash
+python --version
+```
+
+If the output is `Python 3.10.x` or newer, continue. Otherwise install Python:
+
+**Microsoft Store** (easiest on Windows — adds to PATH automatically):
+- Open Microsoft Store → search "Python 3.13" (Publisher: Python Software Foundation) → Install
+- **Close and reopen the terminal** after install so `python` is on PATH
+
+**Manual from python.org**:
+- Download installer from https://www.python.org/downloads/
+- During install, check **"Add python.exe to PATH"**
+- Close and reopen the terminal
+
+### 2. `pipx`
+
+```bash
+pipx --version
+```
+
+If it reports a version, skip to step 3. Otherwise:
+
+```bash
+pip install --user pipx
+python -m pipx ensurepath
+```
+
+Close and reopen the terminal so the new PATH entries take effect. Then verify:
+
+```bash
+pipx --version
+```
+
+### 3. `pbi-cli-tool`
+
+```bash
+pbi --version
+```
+
+If it reports `3.10.x` or newer, skip to step 4. Otherwise:
+
+```bash
+pipx install pbi-cli-tool
+```
+
+### 4. Inject `pywin32` into the pbi-cli pipx environment
+
+The `pywin32` package lets `pbi` send keystrokes to Power BI Desktop for auto-sync. Without it, the CLI falls back to PowerShell-based signaling which is less reliable.
+
+```bash
+python -m pipx inject pbi-cli-tool pywin32
+```
+
+Verify the CLI picks it up:
+
+```bash
+pbi visual add --help
+# If the previous run printed "Error: pywin32 is not installed", run the inject.
+# If no such warning appears on subsequent runs, pywin32 is loaded.
+```
+
+### 5. Optional — upgrade later
+
+```bash
+pipx upgrade pbi-cli-tool
+python -m pipx inject pbi-cli-tool pywin32 --force   # refresh the injection
+```
+
+Run this periodically (monthly) since MinaSaad1 ships updates alongside Power BI Desktop schema bumps.
+
+## Troubleshooting
+
+**`pbi: command not found`** after install → terminal PATH needs refresh. Close and reopen. If still missing, `python -m pipx ensurepath` again.
+
+**`pip: command not found`** with Python installed → the Microsoft Store install sometimes doesn't put `pip` on PATH. Use `python -m pip ...` instead.
+
+**`Found a space in the pipx home path`** warning → harmless on Windows. The CLI works despite this.
+
+**`Error: pywin32 is not installed`** when running `pbi visual add` → you ran `pip install --user pywin32` (wrong scope). Instead run `python -m pipx inject pbi-cli-tool pywin32` so it lands in the CLI's isolated venv.
+
+## Sanity check (run after full setup)
+
+```bash
+pbi --version                    # should print a version
+pbi setup                        # should print "Environment is ready."
+pbi connect                      # should auto-detect running Power BI Desktop
+pbi disconnect                   # clean disconnect
+```
+
+If all four commands succeed, the skill can proceed to PHASE 1.