@luquimbo/bi-superpowers 4.1.2 → 4.1.4

package/README.md

@@ -5,192 +5,733 @@
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
 [![Power BI](https://img.shields.io/badge/Power%20BI-Desktop-F2C811?logo=powerbi)](https://powerbi.microsoft.com)
 
-Toolkit open-source para trabajar con **Power BI Desktop** desde Claude Code, GitHub Copilot, Codex, Gemini CLI y Kilo Code.
+**BI Agent Superpowers** is an open-source toolkit that gives AI coding agents practical Power BI Desktop capabilities.
 
-> **Estado:** `v4.1.x` — **primera versión estable**. Incluye 4 skills (`/bi-start` + 3 especialistas) y 2 MCP servers oficiales de Microsoft. `/report-design` usa scripts Node propios para visuales/theme, pero hoy todavía requiere `pbi-cli-tool` para connect, page ops y validate, además de Windows + Power BI Desktop.
->
-> _Nota de versionado_: las versiones 2.x, 3.x y 4.0.0 fueron iteraciones mientras el alcance y la arquitectura del plugin se estaban asentando. **Tratá a v4.1.x como si fuera la 1.0** del producto — es el primer release que el autor considera listo para uso real. El numeral se queda en la línea 4.x porque npm es estrictamente monotónico (no se puede bajar el número), pero la madurez del producto arranca acá.
+It installs reusable agent skills, configures Microsoft MCP servers, and provides a small CLI called `super` so Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code can work with Power BI projects using the same operating contract.
+
+This is not a loose prompt pack. It is a reproducible Power BI agent layer:
+
+- **4 skills** for session startup, BI project analysis, Power BI Desktop connection, and PBIR report generation.
+- **2 Microsoft MCP servers** for Power BI Desktop modeling and Microsoft Learn documentation.
+- **1 CLI** (`super`) for install, updates, local plugin generation, checks, and regeneration.
+- **Claude Code plugin artifacts** with slash commands, discoverable skills, and MCP configuration.
+
+> Status: `v4.1.x` is the first stable release line. Treat it as the practical 1.0 of the project, even though the npm version remains 4.x for monotonic versioning.
+
+---
+
+## Table of Contents
+
+- [What It Does](#what-it-does)
+- [Install From Terminal](#install-from-terminal)
+- [Ask Your Agent To Install It](#ask-your-agent-to-install-it)
+- [Skills Included](#skills-included)
+- [Quick Demos](#quick-demos)
+- [Supported Agents](#supported-agents)
+- [MCP Servers](#mcp-servers)
+- [CLI Reference](#cli-reference)
+- [Plugin File Tree](#plugin-file-tree)
+- [Requirements](#requirements)
+- [Report Design Runtime](#report-design-runtime)
+- [Updates](#updates)
+- [What Ships To npm](#what-ships-to-npm)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
 
 ---
 
-## Instalación
+## What It Does
+
+Power BI work with AI agents usually breaks down in predictable places:
+
+1. The agent does not understand the BI project structure.
+2. The agent does not know how to connect to Power BI Desktop.
+3. The agent invents DAX, PBIR, or setup steps without validating them against real tools.
+4. Each agent has different skill and MCP configuration paths.
+
+BI Agent Superpowers fixes that by giving each supported agent the same Power BI workflow:
+
+- project context through reusable skills;
+- Power BI Desktop access through the Microsoft Power BI Modeling MCP;
+- current Microsoft documentation through the Microsoft Learn MCP;
+- generated Claude Code plugin artifacts for local project work;
+- update checks so old plugin bundles do not silently stay stale.
+
+The goal is simple: open a Power BI project, ask your agent for help, and have the agent know what tools, files, prerequisites, and guardrails apply.
+
+---
+
+## Install From Terminal
+
+### All Supported Agents
+
+Use this when you want one command path for Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.
+
+```bash
+npm install -g @luquimbo/bi-superpowers
+super install --all --yes
+```
+
+Restart your agent after installation so it reloads skills and MCP configuration.
+
+### Interactive Install
+
+Use this when you want the installer to detect agents and ask where to install.
+
+```bash
+npm install -g @luquimbo/bi-superpowers
+super install
+```
+
+### Install For One Agent Only
+
+```bash
+# Claude Code user-level skills + MCP config
+super install --agent claude-code --yes
 
-Elegí el camino según tu agente principal:
+# GitHub Copilot
+super install --agent github-copilot --yes
 
-### 👉 Claude Code (recomendado para usuarios de Claude Code)
+# Codex
+super install --agent codex --yes
 
-Dentro de Claude Code, ejecutá:
+# Gemini CLI
+super install --agent gemini-cli --yes
 
+# Kilo Code
+super install --agent kilo --yes
 ```
+
+### Claude Code Marketplace Install
+
+If you only use Claude Code, the marketplace path is the cleanest install experience:
+
+```text
 /plugin marketplace add luquimbo/bi-superpowers
 /plugin install bi-superpowers
 ```
 
-Eso instala el plugin completo (4 skills + 2 MCPs) en el perfil de Claude Code. Después podés actualizar con `/plugin update bi-superpowers` directamente desde Claude Code — sin pasar por npm.
+After that, start a new session and run:
 
-Si también querés el plugin local de proyecto (con slash commands `/bi-start`, `/project-kickoff`, `/pbi-connect`, `/report-design` en un repo específico), corré `super kickoff` dentro del repo — requiere haber instalado la CLI via el otro path (abajo).
+```text
+/bi-start
+```
 
-### 👉 Otros agentes — Copilot, Codex, Gemini CLI, Kilo Code (o multi-agente)
+### Advanced: Optional Local Claude Code Plugin
+
+This is only for Claude Code users who deliberately want repo-local slash-command plugin files. Codex, GitHub Copilot, Gemini CLI, and Kilo Code should use `super install` above; do not run `super kickoff` for those agents.
+
+Inside a Power BI project repo:
 
 ```bash
-# 1. Instalá la CLI
+super kickoff
+```
+
+This generates project-local Claude Code plugin files:
+
+- `.claude-plugin/`
+- `.plugin/`
+- `.mcp.json`
+- `commands/`
+- `skills/`
+- `config.json`
+
+Regenerate them later with:
+
+```bash
+super recharge
+```
+
+---
+
+## Ask Your Agent To Install It
+
+If your agent has terminal access, paste one of these prompts.
+
+### Claude Code
+
+Use the marketplace path first:
+
+```text
+Install BI Agent Superpowers from the Claude Code marketplace.
+
+Run these Claude Code plugin commands:
+
+/plugin marketplace add luquimbo/bi-superpowers
+/plugin install bi-superpowers
+
+After installation, start the plugin with /bi-start and tell me if any restart or reload is needed.
+```
+
+If you also want project-local plugin files in the current repo for Claude Code only:
+
+```text
+Set up BI Agent Superpowers for this project as a local Claude Code plugin.
+
+In the terminal, run:
+
 npm install -g @luquimbo/bi-superpowers
+super kickoff
 
-# 2. Instalá skills + MCPs en todos tus agentes
-super install
+Then verify that .claude-plugin/, .plugin/, .mcp.json, commands/, skills/, and config.json were created in this repo. Do not modify unrelated files.
+```
+
+### GitHub Copilot
+
+```text
+Set up BI Agent Superpowers for GitHub Copilot on this machine.
+
+In the terminal, run:
+
+npm install -g @luquimbo/bi-superpowers
+super install --agent github-copilot --yes
+
+After it finishes, verify that the GitHub Copilot skills directory and MCP config were updated. Then remind me to restart VS Code or reload Copilot so it picks up the new skills and MCP servers.
+```
+
+### Codex
+
+```text
+Set up BI Agent Superpowers for Codex on this machine.
+
+In the terminal, run:
+
+npm install -g @luquimbo/bi-superpowers
+super install --agent codex --yes
+
+After it finishes, verify that the shared skills were installed under ~/.agents/skills and that the Codex MCP config was updated. Then summarize the installed skills and MCP servers.
+
+Do not run super kickoff or super mcp-setup for Codex; those commands are only for optional repo-local Claude Code plugin files.
+```
+
+### Gemini CLI
+
+```text
+Set up BI Agent Superpowers for Gemini CLI on this machine.
+
+In the terminal, run:
+
+npm install -g @luquimbo/bi-superpowers
+super install --agent gemini-cli --yes
+
+After it finishes, verify that ~/.gemini/skills and the Gemini MCP settings were updated. Then tell me to restart Gemini CLI before using the skills.
 ```
 
-El instalador:
+### Kilo Code
+
+```text
+Set up BI Agent Superpowers for Kilo Code on this machine.
+
+In the terminal, run:
+
+npm install -g @luquimbo/bi-superpowers
+super install --agent kilo --yes
+
+After it finishes, verify that ~/.kilo/skills and the Kilo MCP settings were updated. Then tell me to restart Kilo Code before using the skills.
+```
+
+### Multi-Agent Setup
+
+```text
+Set up BI Agent Superpowers for every supported agent installed on this machine.
+
+In the terminal, run:
+
+npm install -g @luquimbo/bi-superpowers
+super install --all --yes
+
+After it finishes, summarize which agents were configured, which MCP files were written, and whether any Windows symlink fallback copied files instead of creating symlinks.
+```
+
+---
+
+## Skills Included
+
+### `bi-start`
+
+Session opener. It gives the user a clean starting point, checks whether a newer BI Agent Superpowers version exists, shows the skill menu, and routes the conversation to the right specialist skill.
+
+Use it when:
+
+- you are starting a new session;
+- you do not know which skill to invoke;
+- you want the agent to check update status before work begins.
+
+### `project-kickoff`
+
+Project analysis and planning skill. It inspects a BI project, explains what exists, identifies gaps, and creates a sensible plan for the next work cycle.
+
+Use it when:
+
+- opening a Power BI repo for the first time;
+- starting a new PBIP project;
+- asking an agent to understand project structure before editing.
+
+### `pbi-connect`
+
+Power BI Desktop connection skill. It helps the agent connect to the open Power BI Desktop model through the Microsoft Power BI Modeling MCP.
+
+Use it when:
 
-1. Detecta qué agentes AI tenés instalados (Claude Code, Copilot, Codex, Gemini, Kilo).
-2. Te deja elegir para cuáles instalar (o hace todos con `--all --yes`).
-3. Copia los 4 skills en los directorios correctos de cada agente.
-4. Escribe los 2 MCPs en el config file correcto de cada agente (con el formato/schema que cada uno espera).
+- you need to list tables, columns, measures, or relationships;
+- you want to execute DAX queries;
+- you want the agent to inspect or modify the semantic model through Desktop.
 
-Reiniciá tu agente AI y ya tenés bi-superpowers funcionando.
+### `report-design`
 
-> **¿Por qué dos caminos?** El marketplace de Claude Code es la UX más limpia para usuarios de Claude Code — cero dependencias externas, updates nativos. La CLI via npm cubre los otros 4 agentes (que no tienen un marketplace equivalente) y funciona como denominador común cuando querés las mismas skills + MCPs en múltiples agentes. Los dos caminos son compatibles: podés combinar instalación via marketplace en Claude Code con instalación via CLI para los otros.
+PBIR report generation skill. It turns a ready semantic model into Power BI report pages using bundled Node scripts, PBIR references, visual allowlists, layouts, themes, and validation.
+
+Use it when:
+
+- the model is ready and you want pages;
+- you want native Power BI visuals generated as PBIR files;
+- you want a report draft that can be opened and reviewed in Power BI Desktop.
+
+Current runtime requirement: Windows + Power BI Desktop standalone + Python 3.10+ + `pipx` + `pbi-cli-tool`.
 
 ---
 
-## Qué viene incluido
+## Quick Demos
+
+### Start A Session
 
-### 4 Skills
+```text
+/bi-start
+```
+
+Expected result:
 
-| Skill | Para qué |
-|---|---|
-| `bi-start` | **Arrancar una sesión**: muestra el menú de skills, corre update-check, y (si detecta Power BI Desktop abierto) ofrece conectar vía MCP. Tu entrada por defecto en cada conversación nueva. |
-| `project-kickoff` | Analizá el estado de tu proyecto BI **nuevo** y armá `AGENTS.md` + modelo base |
-| `pbi-connect` | Conectá tu agente AI a Power BI Desktop vía MCP |
-| `report-design` | Generá páginas PBIR vía scripts Node propios (`create-visual.js`, `apply-theme.js`, `validate-pbir.js`), con allowlist de 28 visualTypes nativos |
+- update check;
+- menu of 4 skills;
+- environment hints;
+- next-step recommendation.
 
-Si no sabés por dónde empezar, decile a tu agente `/bi-start` — te muestra los 4 skills, chequea updates, y rutea al que necesites. `/project-kickoff` está reservado para cuando arrancás un proyecto BI desde cero.
+### Analyze A Power BI Project
+
+```text
+/project-kickoff
+Analyze this Power BI repo. Tell me what exists, what is missing, and what plan we should follow.
+```
 
-`report-design` requiere **Windows + Power BI Desktop** (standalone, no la versión de Microsoft Store) **+ Python 3.10+ + `pipx` + `pbi-cli-tool`**. Los scripts Node hacen el authoring de visuales/theme, pero el skill todavía usa `pbi` para connect, add-page/list-pages y validate.
+Expected result:
 
-### 2 MCP Servers (oficiales de Microsoft)
+- project map;
+- risks and missing context;
+- recommended implementation path;
+- handoff to `pbi-connect` or `report-design` when appropriate.
 
-| MCP | Para qué |
-|---|---|
-| `powerbi-modeling-mcp` | Conexión local a Power BI Desktop (XMLA). Leer/escribir modelo semántico, ejecutar DAX. |
-| `microsoft-learn` | HTTP MCP de Microsoft Learn — docs oficiales de Power BI/DAX/Fabric en contexto de la conversación. |
+### Connect To Power BI Desktop
+
+```text
+/pbi-connect
+Connect to the model currently open in Power BI Desktop and list tables, measures, columns, and relationships.
+```
+
+Expected result:
+
+- MCP connection check;
+- semantic model snapshot;
+- actionable diagnostics if Desktop or MCP wiring is not ready.
+
+### Generate A Report Page
+
+```text
+/report-design
+Create an executive sales page with KPI cards, monthly trend, product ranking, and a slicer panel.
+```
+
+Expected result:
+
+- prerequisite checks;
+- page/layout plan;
+- PBIR visual generation;
+- validation against native visual types;
+- instructions to open and verify in Power BI Desktop.
 
 ---
 
-## Agentes soportados
+## Supported Agents
 
-| Agente | Skills | MCP config path | Cómo se usa |
+| Agent | Skill install path | MCP config path | Primary usage |
 |---|---|---|---|
-| **Claude Code** | ✅ via `/plugin install` o `~/.claude/skills/` | `~/.claude.json` | Lenguaje natural o slash commands si corrés `super kickoff` |
-| **GitHub Copilot** | ✅ `~/.copilot/skills/` | `~/.copilot/mcp-config.json` | Lenguaje natural |
-| **Codex (OpenAI)** | ✅ `~/.agents/skills/` | `~/.codex/config.toml` | Lenguaje natural |
-| **Gemini CLI** | ✅ `~/.gemini/skills/` | `~/.gemini/settings.json` | Lenguaje natural |
-| **Kilo Code** | ✅ `~/.kilo/skills/` | `~/.kilo/mcp_settings.json` | Lenguaje natural |
+| Claude Code | `~/.claude/skills/` or marketplace plugin | `~/.claude.json` | Slash commands and natural language |
+| GitHub Copilot | `~/.copilot/skills/` | `~/.copilot/mcp-config.json` | Natural language with skills and MCPs |
+| Codex | `~/.agents/skills/` | `~/.codex/config.toml` | Natural language with skills and MCPs |
+| Gemini CLI | `~/.gemini/skills/` | `~/.gemini/settings.json` | Natural language |
+| Kilo Code | `~/.kilo/skills/` | `~/.kilo/mcp_settings.json` | Natural language |
+
+The installer always writes the universal skill copy to `~/.agents/skills/`, then links or copies agent-specific skill directories as needed.
+
+---
+
+## MCP Servers
+
+| MCP | Transport | Purpose |
+|---|---|---|
+| `powerbi-modeling-mcp` | local stdio | Connects to Power BI Desktop through XMLA for model inspection, DAX queries, and model operations. |
+| `microsoft-learn` | HTTP | Gives the agent access to Microsoft Learn documentation in context. |
 
-`super install` (npm path) escribe los skills + MCPs automáticamente para todos los agentes detectados.
+You can install these MCPs manually, but `super install` writes the expected MCP config for each selected agent automatically.
 
-### Instalación selectiva
+---
+
+## CLI Reference
+
+The package exposes both `super` and `bi-superpowers`:
 
 ```bash
-# Solo para Claude Code
-super install --agent claude-code --yes
+super help
+bi-superpowers help
+```
 
-# Solo para Claude Code y GitHub Copilot
-super install --agent claude-code --agent github-copilot --yes
+Common commands:
 
-# Todos sin prompts
-super install --all --yes
+```bash
+super install          # Install 4 skills + 2 MCPs for selected agents
+super kickoff          # Advanced: generate optional local Claude Code plugin files
+super recharge         # Regenerate optional local Claude Code plugin artifacts
+super powers           # List available skills
+super scan             # Compare source skills with generated artifacts
+super checkup          # Validate skill content
+super build-desktop    # Build the Claude Desktop .mcpb extension
+super upgrade          # Update the global CLI and print refresh steps
+super help             # Show full CLI help
 ```
 
 ---
 
-## Actualizar
+## Plugin File Tree
+
+### Local Claude Code Plugin
+
+Generated by `super kickoff` or `super recharge`:
+
+This tree is optional and Claude Code specific. It is not required for Codex, GitHub Copilot, Gemini CLI, or Kilo Code because those agents use the user-level install created by `super install`.
+
+```text
+project/
+├─ .claude-plugin/
+│  ├─ plugin.json
+│  ├─ marketplace.json
+│  └─ skill-manifest.json
+├─ .plugin/
+│  └─ plugin.json
+├─ .mcp.json
+├─ commands/
+│  ├─ bi-start.md
+│  ├─ project-kickoff.md
+│  ├─ pbi-connect.md
+│  └─ report-design.md
+├─ skills/
+│  ├─ bi-start/
+│  │  ├─ SKILL.md
+│  │  └─ scripts/update-check.js
+│  ├─ project-kickoff/
+│  │  ├─ SKILL.md
+│  │  └─ scripts/update-check.js
+│  ├─ pbi-connect/
+│  │  ├─ SKILL.md
+│  │  └─ scripts/update-check.js
+│  └─ report-design/
+│     ├─ SKILL.md
+│     ├─ scripts/
+│     │  ├─ apply-theme.js
+│     │  ├─ create-visual.js
+│     │  ├─ ensure-pbi-cli.sh
+│     │  ├─ update-check.js
+│     │  └─ validate-pbir.js
+│     └─ references/
+│        ├─ cli-commands.md
+│        ├─ cli-setup.md
+│        ├─ native-visuals.md
+│        ├─ pbi-desktop-installation.md
+│        ├─ troubleshooting.md
+│        ├─ layouts/
+│        └─ themes/
+└─ config.json
+```
 
-Dos caminos según cómo instalaste:
+### Build Pipeline
+
+```mermaid
+flowchart TD
+    A["src/content/"] --> B["npm run build:plugin"]
+    B --> C["commands/*.md"]
+    B --> D["skills/*/SKILL.md"]
+    B --> E[".claude-plugin/"]
+    B --> F[".plugin/"]
+    B --> G[".mcp.json"]
+    C --> H["Claude Code slash commands"]
+    D --> I["Agent skills"]
+    G --> J["Power BI Modeling MCP + Microsoft Learn MCP"]
+```
 
-### Claude Code (instalado via marketplace)
+---
 
-Dentro de Claude Code:
+## Requirements
 
-```
+### Base Requirements
+
+- Node.js 18 or newer.
+- At least one supported AI agent.
+
+### For `pbi-connect`
+
+- Windows.
+- Power BI Desktop open.
+- Power BI Modeling MCP available to the agent.
+
+### For `report-design`
+
+- Windows.
+- Power BI Desktop standalone, not the Microsoft Store build.
+- Python 3.10 or newer.
+- `pipx`.
+- `pbi-cli-tool`.
+- PBIR/TMDL enabled when applicable.
+
+---
+
+## Report Design Runtime
+
+`report-design` uses bundled Node scripts for PBIR visual and theme authoring:
+
+- `create-visual.js`
+- `apply-theme.js`
+- `validate-pbir.js`
+
+It still uses `pbi-cli-tool` for the current runtime flow:
+
+- `pbi connect`
+- `pbi measure list`
+- `pbi table list`
+- `pbi column list`
+- `pbi report add-page`
+- `pbi report list-pages`
+- `pbi report validate`
+
+This means `pbi-cli-tool` is not optional for `report-design` today.
+
+---
+
+## Updates
+
+### Claude Code Marketplace
+
+```text
 /plugin update bi-superpowers
 ```
 
-Eso trae la última versión publicada en el marketplace. Cero interacción con npm.
-
-### npm / CLI-managed installs
+### npm / CLI Installs
 
 ```bash
-# 1. Actualizá la CLI a la última versión
 super upgrade
+super install --all --yes
+```
 
-# 2. Si instalaste skills en el perfil del agente, propagá la nueva versión
-super install --yes
+If you created a project-local plugin:
 
-# 3. Si además generaste un plugin local con super kickoff, regeneralo en ese repo
+```bash
+cd your-power-bi-project
 super recharge
 ```
 
-`super upgrade` reinstala el paquete global y al final te imprime un recordatorio con los refresh paths relevantes. No los hace automáticos a propósito: hay usuarios que solo quieren actualizar la CLI (p.ej. desarrollando local) y no propagar todavía el cambio a todos sus agentes o plugins locales.
+`super upgrade` intentionally does not run `super install` or `super recharge` automatically. User-profile installs and project-local plugins are separate refresh targets.
 
-Equivalente manual si `super upgrade` falla:
+---
 
-```bash
-npm install -g @luquimbo/bi-superpowers@latest
-super install --yes
-# y, si tenés un plugin local en este repo/proyecto:
-super recharge
+## What Ships To npm
+
+The npm package includes:
+
+```text
+bin/
+.claude-plugin/
+.plugin/
+.mcp.json
+commands/
+skills/
+src/content/
+desktop-extension/
+config.json
+config.example.json
+README.md
+CHANGELOG.md
+AGENTS.md
+LICENSE
+package.json
 ```
 
+The npm package does not include:
+
+```text
+examples/smoke-test/
+coordination/
+node_modules/
+*.test.js
+```
+
+`examples/smoke-test/` is intentionally repo-only. It is used for QA and manual validation, not for user installs.
+
 ---
 
-## Alternativas para instalar los MCPs
+## Development
 
-`super install` escribe automáticamente los 2 MCPs en el config file de cada agente. Pero hay otras formas de instalar los mismos MCPs — cualquiera de estas funciona igual de bien:
+Install dependencies:
 
-### Para Power BI Modeling MCP (local)
+```bash
+npm install
+```
 
-- **Extensión de VS Code** — Microsoft publica "Power BI Modeling MCP" en el VS Code Marketplace. Si la instalás, VS Code + Copilot lo descubren automáticamente sin tocar archivos de config.
-- **Extensión de Cursor** — misma extensión, Cursor la detecta.
-- **Manual** — descargá el binario `.exe` y configurá `BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH` apuntando al ejecutable.
+Regenerate plugin artifacts:
 
-### Para Microsoft Learn MCP (HTTP)
+```bash
+npm run build:plugin
+```
 
-- **MCP marketplace oficial de Anthropic** — en Claude Code se puede hacer `/plugin marketplace add anthropic/mcp-registry` y después `/plugin install microsoft-learn` (según disponibilidad).
-- **Agregarlo a mano** en el config file del agente con la URL `https://learn.microsoft.com/api/mcp`.
+Validate locally:
 
-Si ya instalaste los MCPs por alguno de estos caminos, no necesitás correr `super install` — o, si lo corrés, los configs se mergean sin conflicto (cada agente tiene merge por clave, no por overwrite).
+```bash
+npm test
+npm run lint
+npm run format:check
+npm pack --dry-run --ignore-scripts
+```
+
+Source of truth:
+
+```text
+src/content/
+```
+
+Generated artifacts:
+
+```text
+commands/
+skills/
+.claude-plugin/
+.plugin/
+.mcp.json
+```
+
+Edit source files first, then regenerate generated outputs.
 
 ---
 
-## Requisitos
+## Publishing
+
+Publishing is handled by GitHub Actions. Do not run `npm publish` locally.
+
+Expected release flow:
+
+```bash
+npm version patch --no-git-tag-version
+npm run build:plugin
+npm test
+npm run lint
+npm run format:check
+git add package.json package-lock.json commands/ skills/ .claude-plugin/ .plugin/ .mcp.json
+git commit -m "chore: release vX.Y.Z"
+git tag -a vX.Y.Z -m "vX.Y.Z"
+git push origin main --follow-tags
+```
 
-- **Node.js ≥ 18**
-- **Power BI Desktop en Windows** (standalone, no Microsoft Store) para workflows locales contra Desktop (`powerbi-modeling-mcp` y `report-design`)
-- **Python 3.10+**, **`pipx`** y **`pbi-cli-tool`** son requeridos para `/report-design` hoy. Los scripts Node hacen el authoring de visuales/theme, pero el flujo completo sigue usando `pbi` para connect, page ops y validate.
-- Al menos uno de: Claude Code, GitHub Copilot, Codex, Gemini CLI, Kilo Code
+The publish workflow runs on `v*` tag pushes. Manual dispatch is constrained to an already-tagged release commit on `main`.
 
 ---
 
-## Comandos
+## Troubleshooting
+
+### `super` is not found after npm install
+
+Check the global package:
 
 ```bash
-super install          # Instalá 4 skills + 2 MCPs en tus agentes AI
-super kickoff          # Generá el plugin local de Claude Code con slash commands
-super recharge         # Regenerá el plugin tras editar skills fuente
-super powers           # Listá skills disponibles
-super upgrade          # Actualizá la CLI + recordatorio de /plugin update, super install o super recharge
-super help             # Ayuda completa
+npm list -g @luquimbo/bi-superpowers
 ```
 
+Try the long binary name:
+
+```bash
+bi-superpowers help
+```
+
+If npm's global bin directory is not in `PATH`, fix `PATH` or use your package manager's global binary setup instructions.
+
+### The Agent Does Not See The Skills
+
+1. Restart the agent.
+2. Run `super install --all --yes` again.
+3. Check the relevant skill directory.
+4. If using a local Claude Code plugin, run `super recharge` inside that repo.
+
+### Power BI Desktop Does Not Connect
+
+1. Open Power BI Desktop.
+2. Open the target `.pbix` or PBIP project.
+3. Confirm the Power BI Modeling MCP is installed.
+4. Restart the agent after MCP installation.
+
+### `report-design` Stops Because Power BI Desktop Is The Microsoft Store Build
+
+Install the standalone Power BI Desktop build. The Store build can block flows required by CLI/MCP tooling.
+
+### `pbi-cli-tool` Is Missing
+
+Install Python, `pipx`, and `pbi-cli-tool`:
+
+```bash
+python --version
+pipx --version
+pipx install pbi-cli-tool
+pbi --version
+```
+
+---
+
+## FAQ
+
+### Does This Replace Power BI Desktop?
+
+No. Power BI Desktop remains the visual/runtime verification tool. The plugin helps agents work with project files, MCPs, PBIR, and semantic-model context more reliably.
+
+### Does It Work Outside Windows?
+
+The CLI and several skills can run outside Windows. Workflows that depend on Power BI Desktop, especially `pbi-connect` and `report-design`, are Windows-first.
+
+### Do I Need Claude Code?
+
+No. Claude Code has the richest plugin/slash-command experience, but the npm installer supports GitHub Copilot, Codex, Gemini CLI, and Kilo Code too.
+
+### Do I Need `pbi-cli-tool`?
+
+For `report-design`, yes. For `bi-start`, `project-kickoff`, and `pbi-connect`, not necessarily.
+
+### Can I Use Only The MCP Servers?
+
+Yes. You can install Microsoft Learn MCP and Power BI Modeling MCP manually. This repo packages them with skills and operational workflows so agents know when and how to use them.
+
+### Does This Send Data To A SaaS Backend?
+
+No. The package installs local files, writes local agent config, and uses MCP servers configured on your machine. There is no BI Agent Superpowers SaaS backend.
+
 ---
 
-## Contribuir
+## Contributing
+
+Issues and pull requests are welcome:
+
+- GitHub: https://github.com/luquimbo/bi-superpowers
+- Issues: https://github.com/luquimbo/bi-superpowers/issues
+- npm: https://www.npmjs.com/package/@luquimbo/bi-superpowers
 
-Este proyecto está empezando. Si querés agregar skills, mejorar los existentes, o reportar bugs:
+Before large changes, read:
 
-- Abrí un issue en https://github.com/luquimbo/bi-superpowers/issues
-- Pull requests bienvenidas
+- `AGENTS.md`
+- `ARCHITECTURE.md`
+- `src/content/`
+- `bin/`
 
 ---