@luquimbo/bi-superpowers 3.2.0 → 4.1.0

package/skills/report-design/references/native-visuals.md

@@ -0,0 +1,341 @@
+# Native PBI visual types — canonical reference
+
+**Single source of truth for every native `visualType` accepted by Power BI Desktop (March 2026, PBIR schema 2.7.0) and the shape of its `query.queryState`.**
+
+The allowlist is implemented in `scripts/create-visual.js` (`NATIVE_VISUAL_TYPES` lookup) and enforced by `scripts/validate-pbir.js`. This doc is the human-readable mirror.
+
+If a type isn't in this table, it's not native — `create-visual.js` will reject it, and `validate-pbir.js` will flag it on any existing visual.json.
+
+**Related reference**: `references/visual-types.md` — tested-in-Desktop reference with render status per typeId. Cross-reference this doc when in doubt about whether a typeId actually renders on a given PBI Desktop build.
+
+---
+
+## The native visualTypes
+
+| # | `visualType` | Category | Required roles | Optional roles | Notes |
+|---|---|---|---|---|---|
+| 1 | `card` | Single | Values (measure) | — | KPI clásico, un valor. |
+| 2 | `cardVisual` | Single | Data (measure, multi) | — | New card March 2026. Multiple measures. |
+| 3 | `kpi` | Single | Indicator (measure) | Goal (measure), TrendLine (column) | KPI con goal + trend. |
+| 4 | `gauge` | Single | Y (measure) | MaxValue, TargetValue, MinValue (measures) | Arco radial. |
+| 5 | `multiRowCard` | Single | Values (measure, multi) | — | Card multi-valor apilado. |
+| 6 | `barChart` | Comparison | Category (column), Y (measure, multi) | Legend (column) | Agrega Legend para stacked. |
+| 7 | `clusteredBarChart` | Comparison | Category, Y | Legend | Side-by-side siempre. |
+| 8 | `columnChart` | Comparison | Category, Y | Legend | Agrega Legend para stacked. |
+| 9 | `clusteredColumnChart` | Comparison | Category, Y | Legend | Side-by-side siempre. |
+| 10 | `hundredPercentStackedBarChart` | Comparison | Category, Y, **Legend** | — | Legend es mandatorio. |
+| 11 | `hundredPercentStackedColumnChart` | Comparison | Category, Y, **Legend** | — | Legend es mandatorio. |
+| 12 | `lineChart` | Time | Category, Y (multi) | Legend | Time series. |
+| 13 | `areaChart` | Time | Category, Y (multi) | Legend | Agrega Legend para stacked. |
+| 14 | `lineClusteredColumnComboChart` | Time | Category, ColumnY, LineY (measures, multi) | Legend | ColumnY side-by-side. **Única variante combo que renderiza en Desktop** (la stacked está rota — ver blocklist). |
+| 15 | `ribbonChart` | Time | Category, Y | Legend | Ranking change over time. ⚠ Puede requerir preview flag. |
+| 16 | `pieChart` | Part-to-whole | Category, Y | — | Torta. |
+| 17 | `donutChart` | Part-to-whole | Category, Y | — | Dona (pie con hueco). |
+| 18 | `treemap` | Part-to-whole | Category, Values | — | Rectángulos proporcionales. |
+| 19 | `funnelChart` | Flow | Category, Y | — | Embudo / stages. |
+| 20 | `scatterChart` | Correlation | Details (column), X (measure), Y (measure) | Legend (column), Size (measure) | Con Size → bubble chart. |
+| 21 | `waterfallChart` | Flow | Category, Y | Breakdown (column) | Con Breakdown desglosa cada barra. |
+| 22 | `tableEx` | Tabular | Values (multi) | — | Tabla detalle. |
+| 23 | `pivotTable` | Tabular | Rows (column, multi), Values (measure, multi) | Columns (column, multi) | Matriz. |
+| 24 | `slicer` | Filter | Values (column) | `--slicer-mode basic\|horizontal\|dropdown\|between\|relative` | 5 modos. |
+| 25 | `advancedSlicerVisual` | Filter | Values (column) | — | New slicer March 2026. |
+| 26 | `listSlicer` | Filter | Values (column) | — | Legacy typeId list-only. Preferí `slicer` con `basic`. |
+| 27 | `textSlicer` | Filter | Values (column) | — | Text-input slicer (filtra por substring). |
+| — | `textbox` | Text | (no roles) | `--title`, `--description`, `--paragraph` | Sin query. |
+
+`textbox` es un caso especial sin `query.queryState` — usa `objects.general[0].properties.paragraphs[]`.
+
+---
+
+## Types that look native but are NOT
+
+These pass CLI validation (even `pbi report validate`) but Desktop rejects them as "objeto visual personalizado":
+
+| Fake type | Real pattern |
+|---|---|
+| `stackedBarChart` | `barChart` con Legend (el Legend actúa como Series y PBI apila automáticamente) |
+| `stackedColumnChart` | `columnChart` con Legend |
+| `stackedAreaChart` | `areaChart` con Legend |
+| `lineStackedColumnComboChart` | `lineClusteredColumnComboChart` (el combo clustered sí renderiza; el stacked pasa validate pero Desktop lo rechaza). Ver `visual-types.md` para el testing detrás de esta regla. |
+| `funnel` | `funnelChart` (el bare `funnel` es legacy typeId). |
+| `pie` | alias del CLI upstream que mapea a `donutChart` (bug) — usar `pieChart` nativo |
+| `donut` | alias del CLI — usar `donutChart` nativo |
+| `bar_chart`, `line_chart`, `column_chart`, `area_chart` | aliases CLI. Usar los nombres PascalCase nativos. |
+
+`create-visual.js` conoce estos aliases erróneos y devuelve un error amigable con la corrección. `validate-pbir.js` los flaggea en visual.json existentes.
+
+---
+
+## Shape canonical de un visual.json
+
+Todo visual.json tiene la misma estructura top-level:
+
+```json
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.7.0/schema.json",
+  "name": "<visualName>",
+  "position": {
+    "x": 24, "y": 24, "z": 0,
+    "height": 300, "width": 400,
+    "tabOrder": 0
+  },
+  "visual": {
+    "visualType": "<type>",
+    "query": { "queryState": { "<Role>": { "projections": [ ... ] } } },
+    "drillFilterOtherVisuals": true,
+    "visualContainerObjects": { "title": [ ... ] }
+  }
+}
+```
+
+### Projection shape
+
+Un `projection` tiene wrappers diferentes según si es Column o Measure:
+
+**Column** (con `active: true`):
+```json
+{
+  "field": {
+    "Column": {
+      "Expression": { "SourceRef": { "Entity": "Cuentas" } },
+      "Property": "Banco"
+    }
+  },
+  "queryRef": "Cuentas.Banco",
+  "nativeQueryRef": "Banco",
+  "active": true
+}
+```
+
+**Measure** (sin `active`):
+```json
+{
+  "field": {
+    "Measure": {
+      "Expression": { "SourceRef": { "Entity": "_Measures" } },
+      "Property": "Monto"
+    }
+  },
+  "queryRef": "_Measures.Monto",
+  "nativeQueryRef": "Monto"
+}
+```
+
+### Tablas con espacios
+
+Si la tabla tiene espacios en el nombre (`'Categorias Finanzas'`, `'Movimientos Financieros'`), el shape del projection **NO lleva las comillas** en el `Entity`. Solo lleva el nombre raw:
+
+```json
+{ "SourceRef": { "Entity": "Categorias Finanzas" } }
+```
+
+Pero en `queryRef` **NO** hay comillas: `Categorias Finanzas.Categoria`.
+
+`create-visual.js` maneja ambas notaciones en el input (`Tabla[Col]` y `'Tabla Con Espacios'[Col]`) y genera el shape correcto.
+
+---
+
+## Cómo crear un visual
+
+Siempre usar `create-visual.js`. Nunca escribir visual.json a mano (excepto para patrones que la allowlist aún no cubra — si te pasa, levantá un issue antes de improvisar).
+
+```bash
+node <skillBundleDir>/scripts/create-visual.js \
+  --report-path <path>/MyProj.Report \
+  --page <pageName> \
+  --type <nativeVisualType> \
+  --name <visualName> \
+  --x <x> --y <y> --width <w> --height <h> \
+  --bind <role>=<Table>[<Field>] \
+  [--bind ...] \
+  [--title "<container title>"]
+```
+
+Ejemplos por categoría (copy-paste ready):
+
+### KPI card
+
+```bash
+node 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 "Total Revenue"
+```
+
+### KPI con trend + goal
+
+```bash
+node create-visual.js -p ./pbip-files/Foo.Report --page overview --type kpi \
+  -n kpi_savings --x 320 --y 24 --width 280 --height 120 \
+  --bind indicator='_Measures[Ahorro Neto]' \
+  --bind goal='_Measures[Budget vs Actual]' \
+  --bind trendline='Fecha[Fecha]'
+```
+
+### Bar chart stacked (con Series)
+
+```bash
+# NO uses --type stackedBarChart. Usa barChart + Legend:
+node create-visual.js -p ./pbip-files/Foo.Report --page overview --type barChart \
+  -n gasto_por_banco --x 24 --y 200 --width 600 --height 300 \
+  --bind category='Cuentas[Banco]' \
+  --bind y='_Measures[Gastos]' \
+  --bind legend="'Categorias Finanzas'[TipoMovimiento]"
+```
+
+### 100% stacked bar
+
+```bash
+node create-visual.js -p ./pbip-files/Foo.Report --page overview --type hundredPercentStackedBarChart \
+  -n estado_okrs --x 640 --y 200 --width 400 --height 300 \
+  --bind category='OKRs[AreaVida]' \
+  --bind y='_Measures[KR Count]' \
+  --bind legend='OKRs[Estado]'
+```
+
+### Combo line + clustered column
+
+Nota: Desktop March 2026 **no** renderiza `lineStackedColumnComboChart` — usar la variante clustered.
+
+```bash
+node create-visual.js -p ./pbip-files/Foo.Report --page overview --type lineClusteredColumnComboChart \
+  -n revenue_vs_margin --x 24 --y 500 --width 800 --height 320 \
+  --bind category='Fecha[Fecha]' \
+  --bind columny='_Measures[Gastos]' \
+  --bind liney='_Measures[Ingresos]'
+```
+
+### Scatter / bubble
+
+```bash
+# Scatter simple (sin Size):
+node create-visual.js -p ./pbip-files/Foo.Report --page analysis --type scatterChart \
+  -n mood_vs_deepwork --x 24 --y 400 --width 600 --height 300 \
+  --bind details='Fecha[MesNombre]' \
+  --bind x='_Measures[Mood Avg]' \
+  --bind y='_Measures[Deep Work Avg]'
+
+# Bubble (con Size → burbuja proporcional):
+node create-visual.js ... --bind size='_Measures[Sleep Avg]'
+```
+
+### Waterfall con Breakdown
+
+```bash
+node create-visual.js -p ./pbip-files/Foo.Report --page analysis --type waterfallChart \
+  -n balance_cascada --x 640 --y 400 --width 600 --height 300 \
+  --bind category="'Categorias Finanzas'[GrupoCategoria]" \
+  --bind y='_Measures[Monto]' \
+  --bind breakdown="'Categorias Finanzas'[TipoMovimiento]"
+```
+
+### Textbox (título + descripción)
+
+```bash
+node create-visual.js -p ./pbip-files/Foo.Report --page overview --type textbox \
+  -n header --x 24 --y 0 --width 1232 --height 92 \
+  --title "Resumen Ejecutivo" \
+  --description "KPIs de finanzas personales, hábitos y OKRs del trimestre actual."
+```
+
+### Slicer (5 modos)
+
+```bash
+# 1. Basic (default: vertical list)
+node create-visual.js ... --type slicer --bind values='Fecha[Año]'
+
+# 2. Horizontal (tiles)
+node create-visual.js ... --type slicer --bind values='Fecha[Mes]' --slicer-mode horizontal
+
+# 3. Dropdown (ahorra espacio)
+node create-visual.js ... --type slicer --bind values="'Categorias Finanzas'[Categoria]" --slicer-mode dropdown
+
+# 4. Between (slider de rango, numérico o fecha)
+node create-visual.js ... --type slicer --bind values='Movimientos Financieros[Monto]' --slicer-mode between
+
+# 5. Relative date (últimos N días)
+node create-visual.js ... --type slicer --bind values='Fecha[Fecha]' --slicer-mode relative
+```
+
+---
+
+## Validación
+
+Después de crear visuales, correr las dos capas de validación:
+
+```bash
+# 1. CLI (schema sanity, existencia de archivos, JSON válido)
+pbi report -p <reportPath> validate
+
+# 2. Allowlist + role checks (lo que el CLI no detecta)
+node <skillBundleDir>/scripts/validate-pbir.js <reportPath>
+
+# 3. Apertura real en Desktop standalone (final sanity — la única que garantiza 0 "objeto visual personalizado")
+powershell -Command "Start-Process -FilePath 'C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe' -ArgumentList '\"<abs-path-to.pbip>\"'"
+```
+
+La validación 2 es la que reemplaza la confianza perdida en el CLI (ver SKILL.md → "Why this skill writes PBIR with Node scripts, not the pbi CLI").
+
+---
+
+## Agregar un tipo nuevo
+
+Si PBI Desktop introduce un visualType nuevo (o encontrás uno nativo que falta aquí):
+
+1. Generar un visual.json de referencia:
+   - Preferido: copiarlo de un .pbip real exportado por Desktop.
+   - Alternativo: usar `pbi visual add --type <X>` sobre un scratch `.Report` (si el CLI lo acepta) y copiar la shape del `query.queryState` resultante.
+
+2. Agregar entrada en `scripts/create-visual.js` → `NATIVE_VISUAL_TYPES`:
+
+   ```js
+   myNewChart: {
+     description: '…',
+     roles: {
+       Category: { kind: 'column', required: true, multi: false },
+       Y: { kind: 'measure', required: true, multi: true },
+       // …
+     },
+   },
+   ```
+
+3. Agregar fila a la tabla de arriba en este doc.
+
+4. `npm run build:plugin` para regenerar `skills/...` y `commands/...`.
+
+5. Agregar tests en `src/content/skills/report-design/scripts/create-visual.test.js` (roles required, shape generado, error case).
+
+6. Re-correr `npm test` + `npm run lint`.
+
+---
+
+## Features de `visual.json` que `create-visual.js` NO soporta todavía
+
+Descubiertos al regenerar la smoke-test "Galería de Visuales" end-to-end con el script (backlog item 2, cycle v4.1). No bloquean el authoring — la shape que emite el script pasa `pbi report validate` y `validate-pbir.js` — pero sí dejan regresiones visuales si el `visual.json` hand-written aprovechaba alguno de estos features:
+
+1. **`query.sortDefinition`** — sort explícito por medida/columna con dirección. `create-visual.js` no lo emite, así que un visual "ranking" tipo barChart ordenado descendente por una medida pierde el orden en la regeneración. **Workaround**: ordenar en Desktop manualmente después del `.pbip` abrir, o hand-extender el `visual.json` con `sortDefinition` post-creación. **Fix futuro**: `--sort-by "Role:Field" --sort-dir descending` en `create-visual.js`.
+
+2. **Textbox con tamaños custom (`fontSize`)** — el shortcut `--title TEXT --description TEXT` emite 19pt para el título y 10.5pt para el cuerpo, fijo. No hay flags para personalizar. Si necesitás una sección de 13pt o un callout de 28pt, perdés la jerarquía visual al regenerar. **Workaround**: usar `--paragraph` en vez de `--title/--description` (paragraphs planos sin estilado), y editar manualmente después si hace falta. **Fix futuro**: `--title-size 13pt --body-size 9pt` en el textbox shortcut.
+
+3. **`queryState.<Role>.projections[].active`** — las columnas siempre salen con `active: true`, las medidas nunca. Si un visual hand-written tenía `active: true` en una medida (para indicar que la medida es la "default Y") o `active: false` en una columna (hidden projection), el script normaliza. Rara vez significativo para el render pero cambia el shape JSON.
+
+4. **Formato condicional**: colores signados (positivo verde / negativo rojo), gradientes en matriz, data bars en tabla. Ninguno de estos expresa shape via `create-visual.js`. Quedó deferido a v4.1+ en `SKILL.md` PHASE 4.3.
+
+Cualquier cambio en el script que cubra estos gaps debe: (a) agregar el flag a `parseArgs`, (b) cubrirlo con tests en `create-visual.test.js`, (c) documentarlo en este archivo, (d) regenerar la Galería para que ejercite el feature.
+
+---
+
+## Lo que este skill YA no hace via CLI
+
+El plugin migró de `pbi-cli-tool` (MinaSaad1, upstream) a scripts Node propios para authoring PBIR, por 3 regresiones conocidas del CLI:
+
+1. **`pbi report set-theme`** escribe shape inválida → `apply-theme.js` la reemplaza.
+2. **`pbi visual add --type`** advertiza 5 tipos (acepta ~20 sin anunciarlos, y acepta tipos no nativos como `stackedBarChart`) → `create-visual.js` la reemplaza con allowlist explícita.
+3. **`pbi report validate`** pasa `valid: True` con tipos no nativos → `validate-pbir.js` la complementa.
+
+Lo que el CLI SÍ sigue aportando (y no hay plan de reemplazar):
+
+- `pbi connect` + `pbi measure list` + `pbi table list` + `pbi column list` — model introspection via XMLA endpoint. Requiere Analysis Services client libraries (pywin32), difícil de reimplementar en Node puro. Microsoft Modeling MCP cubre esta necesidad mejor — preferir ese cuando esté disponible.
+- `pbi disconnect` — limpia la conexión XMLA después de las operaciones de modelo.
+
+Los demás subcomandos (`report add-page`, `visual add/bind/update/delete`, `report validate`) están siendo reemplazados progresivamente.

package/skills/report-design/references/pbi-desktop-installation.md

@@ -0,0 +1,87 @@
+# Power BI Desktop installation — standalone vs Microsoft Store
+
+This skill **requires the standalone (installer) version of Power BI Desktop**, not the Microsoft Store version. Both look identical when running, but they behave differently for automation.
+
+## Why standalone is mandatory for this skill
+
+The Microsoft Store version sandboxes file access and command-line arguments. When the skill tries to relaunch Desktop with the `.pbip` path:
+
+```bash
+Start-Process -FilePath "...\pbidesktop.exe" -ArgumentList "<path>"
+```
+
+the Store version rejects it with **"No se puede iniciar Power BI Desktop — Error al analizar los argumentos de la línea de comandos"**. The standalone installer build accepts the same call without issues.
+
+## Why standalone is also recommended for daily BI work
+
+The "External Tools" tab in PBI Desktop only registers tools when they can write to a known install location. The Microsoft Store version blocks third-party writes to its app folder, so these tools **do not appear** under the External Tools ribbon when only the Store version is installed:
+
+- **Tabular Editor 2 / 3** — semantic model editing, batch operations, scripting
+- **DAX Studio** — DAX query analysis, performance tuning, server timings
+- **ALM Toolkit** — schema diff and deploy across model versions
+- **Bravo for Power BI** — model documentation and Best Practice Analyzer
+- **Measure Killer** — find unused measures and columns
+- **VertiPaq Analyzer** — model size and column cardinality reports
+
+If you write DAX professionally or care about model performance, you eventually need at least one of these. The standalone installer build is the only one that integrates with all of them out of the box.
+
+Other reasons agents prefer standalone:
+- **Update control** — Store auto-updates can break workflows mid-session. Installer updates are explicit downloads.
+- **Stable install path** — `C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe` doesn't change between versions. The Store path includes a versioned package ID that breaks scripts on every update.
+- **Better logging** — Crash logs and traces are written to a predictable location (`%LOCALAPPDATA%\Microsoft\Power BI Desktop\Traces`) instead of the Store sandbox.
+
+## Detection — what the skill checks in PHASE 0
+
+```powershell
+$standalone = "C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe"
+$store      = Get-ChildItem "C:\Program Files\WindowsApps" -Directory -ErrorAction SilentlyContinue |
+              Where-Object { $_.Name -like "Microsoft.MicrosoftPowerBIDesktop_*" }
+
+$hasStandalone = Test-Path $standalone
+$hasStore      = $null -ne $store
+```
+
+| `$hasStandalone` | `$hasStore` | Action |
+|---|---|---|
+| ✅ | ❌ | Continue. Use `$standalone` for all launches. |
+| ✅ | ✅ | Continue, but warn: Store install can interfere if launched manually. Recommend uninstall. |
+| ❌ | ✅ | **Stop.** Walk user through standalone install + Store uninstall. |
+| ❌ | ❌ | **Stop.** Walk user through standalone install. |
+
+## Install standalone (when missing)
+
+1. **Download the standalone installer**: https://www.microsoft.com/en-us/download/details.aspx?id=58494
+   - Pick **PBIDesktopSetup_x64.exe** (64-bit, what almost everyone needs). Microsoft currently ships this as an `.exe` wrapper; `aka.ms/pbiSingleInstaller` redirects there.
+   - Direct shortcut: https://aka.ms/pbiSingleInstaller
+2. Run the installer with default options.
+3. Verify:
+   ```powershell
+   Test-Path "C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe"
+   # Should print: True
+   ```
+
+## Uninstall the Microsoft Store version (after standalone is installed)
+
+Recommended even if you keep both — having only the standalone version eliminates ambiguity for the OS file association and external tools.
+
+**Option A — Settings UI:**
+- `Settings → Apps → Installed apps → Microsoft Power BI Desktop → ⋯ → Uninstall`
+
+**Option B — PowerShell (one command):**
+```powershell
+Get-AppxPackage *PowerBIDesktop* | Remove-AppxPackage
+```
+
+After uninstall, log out and log back in (or restart) so Windows refreshes the file association for `.pbip` / `.pbix` files. The standalone version then becomes the default opener.
+
+## Recommended canonical path
+
+Once installed, the skill always launches Desktop via:
+
+```powershell
+Start-Process `
+  -FilePath "C:\Program Files\Microsoft Power BI Desktop\bin\PBIDesktop.exe" `
+  -ArgumentList "`"<full-path-to.pbip>`""
+```
+
+Note the escaped inner quotes — paths with spaces (e.g. user folders, OneDrive sync folders) require the inner string to be quoted, otherwise PBI Desktop parses the path as multiple arguments and shows the "Error al analizar argumentos" dialog.

package/skills/report-design/references/pbir-preview-activation.md

@@ -0,0 +1,40 @@
+# PBIR Preview Activation
+
+The Power BI Enhanced Report (PBIR) format is a Public Preview feature as of 2025–2026. It must be activated in Power BI Desktop before `/report-design` can write report files.
+
+## How to check if it's already active
+
+If the project has a `pbip-files/{projectName}.Report/definition/` folder with files like `report.json`, `version.json`, and a `pages/` subfolder — PBIR is active.
+
+If the `.Report/` folder is missing or contains a single `report.json` file with a lot of binary-looking content at the root (no `definition/` subfolder), PBIR is NOT active.
+
+## How to activate it
+
+Ask the user to follow these steps in Power BI Desktop:
+
+1. **File → Options and settings → Options**
+2. In the left sidebar, select **Preview features**
+3. Check **"Power BI Project (.pbip) save format — Store report using enhanced metadata format (PBIR)"**
+4. Click **OK**
+5. **Close and reopen** Power BI Desktop for the change to take effect
+6. Re-open the `.pbip` file
+7. **File → Save** — this rewrites the file in PBIR format, creating the `definition/` folder structure
+
+Then verify by listing the folder:
+
+```
+pbip-files/{projectName}.Report/
+├── definition.pbir
+├── definition/
+│   ├── version.json
+│   ├── report.json
+│   └── pages/
+│       └── pages.json
+└── StaticResources/
+```
+
+Once that structure exists, `/report-design` can proceed.
+
+## Warning to surface to the user
+
+PBIR is in Public Preview. Microsoft can change the schema between Power BI Desktop releases. If `/report-design` suddenly stops producing files that render, update the plugin: `super upgrade`. We keep the plugin in sync with PBIR schema changes while the feature is in preview.

package/skills/report-design/references/slicer.md

@@ -0,0 +1,89 @@
+# Slicer visuals — manual JSON write (CLI exception)
+
+The `pbi-cli-tool` does not support `pbi visual add --type slicer`. The only valid `--type` values are `card`, `line_chart`, `bar_chart`, `table`, `matrix`. For slicers, the skill writes the visual.json directly — this is a **documented exception to MANDATORY RULE 2** ("never write visual.json by hand").
+
+Verified against PBIR schema 2.7.0. The 5 most common modes are tested live in `examples/smoke-test/pbip-files/super-test.Report/definition/pages/theme/visuals/slicer_*` — all render correctly in standalone PBI Desktop 2.152.x.
+
+## Slicer modes
+
+| Mode | UX in Desktop | When to use |
+|---|---|---|
+| List vertical (Basic) | Checkboxes apilados verticalmente | Default; 5–15 valores; user ve todas las opciones |
+| List horizontal (Tile) | Botones en fila horizontal | 3–7 categorías cortas; ahorra espacio vertical (tabs-like) |
+| Dropdown | Lista colapsada en dropdown | 50+ valores o cuando importa ahorrar espacio |
+| Between (range) | Slider de rango con dos controles | Fechas o columnas numéricas; permite zoom a un período |
+| Relative date | "Últimos N días/semanas/meses" | Dashboards en producción que siempre muestran "lo más reciente" |
+
+## Schema (common shape)
+
+```json
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.7.0/schema.json",
+  "name": "<visualName>",
+  "position": { "x": 16, "y": 16, "z": 0, "width": 540, "height": 360, "tabOrder": 26 },
+  "visual": {
+    "visualType": "slicer",
+    "query": {
+      "queryState": {
+        "Values": {
+          "projections": [
+            {
+              "field": {
+                "Column": {
+                  "Expression": { "SourceRef": { "Entity": "<TableName>" } },
+                  "Property": "<ColumnName>"
+                }
+              },
+              "queryRef": "<TableName>.<ColumnName>",
+              "nativeQueryRef": "<ColumnName>",
+              "active": true
+            }
+          ]
+        }
+      }
+    },
+    "objects": {
+      "data": [{ "properties": { "mode": { "expr": { "Literal": { "Value": "'<MODE>'" } } } } }],
+      "general": [{ "properties": { "orientation": { "expr": { "Literal": { "Value": "<N>" } } } } }]
+    },
+    "drillFilterOtherVisuals": true
+  }
+}
+```
+
+## Mode → property values
+
+| Mode | `data.mode` Value | `general.orientation` Value |
+|---|---|---|
+| List vertical | `'Basic'` | `1` |
+| List horizontal (Tile) | `'Basic'` | `2` |
+| Dropdown | `'Dropdown'` | (omit `general` block) |
+| Between (numeric/date) | `'Between'` | (omit `general` block) |
+| Relative date | `'Relative'` | (omit `general` block) |
+
+For Dropdown / Between / Relative, omit the `general.orientation` block entirely — just `data` under `objects`.
+
+## Field semantics
+
+- The single field goes under the **`Values`** data role (not `Category` like bar/line charts).
+- For **column-based slicers** (the common case): use the `Column` projection structure shown above.
+- For **measure-based slicers**: replace `Column` with `Measure` and adjust `queryRef` / `nativeQueryRef`. Rare — slicers usually filter on dim columns.
+- `position.z = 0`: same plane as data visuals (slicers are interactive, not overlays).
+
+## Pitfalls
+
+- For a **Between** slicer the column must be a real date or numeric column — `Transacciones[Monto]` works as a measure but not as a slicer between-range field. Use a plain numeric/date column.
+- For **Relative date** mode the column must be a date type. PBI parses "last N units" relative to system time on the viewing machine.
+- **Tile/Horizontal** with too many values overflows; PBI adds a horizontal scroll. Consider Dropdown for >7 values.
+- After every slicer write, run `pbi report -p "<reportPath>" validate` AND verify Desktop opens the .pbip without error.
+
+## Pattern the skill uses
+
+```bash
+mkdir -p "<reportPath>/definition/pages/<pageName>/visuals/<visualName>"
+cat > "<reportPath>/definition/pages/<pageName>/visuals/<visualName>/visual.json" <<'EOF'
+{ ...substituted body from the schema above... }
+EOF
+```
+
+A reusable helper script (`scripts/write-slicer.sh`) is a v4.1 candidate; v4.0.0 ships with the heredoc pattern.

package/skills/report-design/references/textbox.md

@@ -0,0 +1,101 @@
+# Textbox visuals — manual JSON write (CLI exception)
+
+The `pbi-cli-tool` does not support `pbi visual add --type textbox`. The only valid `--type` values are `card`, `line_chart`, `bar_chart`, `table`, `matrix`. For textboxes, the skill writes the visual.json directly — this is a **documented exception to MANDATORY RULE 2** ("never write visual.json by hand").
+
+Verified against PBIR schema 2.7.0. Tested live in `examples/smoke-test/pbip-files/super-test.Report/definition/pages/theme/visuals/txt_*` — all render correctly in standalone PBI Desktop 2.152.x (March 2026 release).
+
+## Schema
+
+The textbox lives at `<reportPath>/definition/pages/<pageName>/visuals/<visualName>/visual.json`:
+
+```json
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.7.0/schema.json",
+  "name": "<visualName>",
+  "position": {
+    "x": 16,
+    "y": 16,
+    "z": 1,
+    "width": 692,
+    "height": 80,
+    "tabOrder": 5
+  },
+  "visual": {
+    "visualType": "textbox",
+    "objects": {
+      "general": [
+        {
+          "properties": {
+            "paragraphs": [
+              {
+                "textRuns": [
+                  {
+                    "value": "Title text here",
+                    "textStyle": {
+                      "fontSize": "28pt",
+                      "fontWeight": "bold"
+                    }
+                  }
+                ]
+              },
+              {
+                "textRuns": [{ "value": "" }]
+              },
+              {
+                "textRuns": [
+                  {
+                    "value": "Body description text.",
+                    "textStyle": { "fontSize": "14pt" }
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Field semantics
+
+- `position.z = 1`: above other visuals on the page (data visuals default to `z = 0`).
+- `position.tabOrder`: sequential per page; bump for each visual to keep tab navigation predictable.
+- `objects.general[0].properties.paragraphs[]`: array of paragraphs — each becomes one display line.
+- Each paragraph contains `textRuns[]` — concatenated in order; each can carry its own `textStyle`.
+- An **empty paragraph** (`textRuns: [{ "value": "" }]`) inserts a blank line between paragraphs.
+- `textStyle` keys we've validated: `fontSize` ("8pt"–"40pt"), `fontWeight` ("bold"). Color, italic, underline likely supported but not tested.
+
+## Common pitfalls
+
+These are caught by **PBI Desktop on load**, NOT by `pbi report validate`:
+
+- **Do NOT use `vcObjects`** — the CLI validator accepts it, but Desktop rejects with `Property 'vcObjects' has not been defined and the schema does not allow additional properties`. Use `objects` (no `vc` prefix).
+- **Do NOT JSON-encode the paragraphs as a string in `expr.Literal.Value`**. The `paragraphs` field is a real array, not a serialized string.
+- After every textbox write, always run `pbi report -p "<reportPath>" validate` AND verify Desktop opens the .pbip without error. CLI validate alone is insufficient.
+
+## Pattern the skill uses
+
+In PHASE 4, after the data visuals are added via CLI, write each textbox via heredoc:
+
+```bash
+mkdir -p "<reportPath>/definition/pages/<pageName>/visuals/<visualName>"
+cat > "<reportPath>/definition/pages/<pageName>/visuals/<visualName>/visual.json" <<'EOF'
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/fabric/item/report/definition/visualContainer/2.7.0/schema.json",
+  "name": "<visualName>",
+  "position": {"x": 16, "y": 16, "z": 1, "width": 692, "height": 80, "tabOrder": 5},
+  "visual": {
+    "visualType": "textbox",
+    "objects": {
+      "general": [{"properties": {"paragraphs": [
+        {"textRuns": [{"value": "Title", "textStyle": {"fontSize": "28pt", "fontWeight": "bold"}}]}
+      ]}}]
+    }
+  }
+}
+EOF
+```
+
+A reusable helper script (`scripts/write-textbox.sh`) is a v4.1 candidate; v4.0.0 ships with the heredoc pattern.