bi-superpowers 1.0.0

package/README.md

@@ -0,0 +1,849 @@
+<div align="center">
+
+<pre>
+██████╗ ██╗
+██╔══██╗██║
+██████╔╝██║
+██╔══██╗██║
+██████╔╝██║
+╚═════╝ ╚═╝
+███████╗██╗   ██╗██████╗ ███████╗██████╗ ██████╗  ██████╗ ██╗    ██╗███████╗██████╗ ███████╗
+██╔════╝██║   ██║██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔═══██╗██║    ██║██╔════╝██╔══██╗██╔════╝
+███████╗██║   ██║██████╔╝█████╗  ██████╔╝██████╔╝██║   ██║██║ █╗ ██║█████╗  ██████╔╝███████╗
+╚════██║██║   ██║██╔═══╝ ██╔══╝  ██╔══██╗██╔═══╝ ██║   ██║██║███╗██║██╔══╝  ██╔══██╗╚════██║
+███████║╚██████╔╝██║     ███████╗██║  ██║██║     ╚██████╔╝╚███╔███╔╝███████╗██║  ██║███████║
+╚══════╝ ╚═════╝ ╚═╝     ╚══════╝╚═╝  ╚═╝╚═╝      ╚═════╝  ╚══╝╚══╝ ╚══════╝╚═╝  ╚═╝╚══════╝
+</pre>
+
+**Power BI superpowers for AI agents**
+
+[![npm version](https://img.shields.io/npm/v/bi-superpowers)](https://www.npmjs.com/package/bi-superpowers)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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)
+
+</div>
+
+> **Your AI assistant ships Power BI work that holds up in production.**
+> 9 specialist skills, 2 official Microsoft MCP servers, one CLI.
+
+```bash
+npm install -g bi-superpowers
+super install --all --yes
+```
+
+Restart your agent once after install. That's the whole setup.
+
+Works with **Codex**, **Claude Code**, **GitHub Copilot**, **Gemini CLI**, and **Kilo Code** — same operating contract across every agent.
+
+Fully open source under MIT. No account, no login, no license keys — every command works offline.
+
+> Status: `v1.0.x` is the current stable release line. Every public slash command lives under the `/bi-*` namespace.
+>
+> Validation baseline: developed and stress-tested first in **Codex**. Other agents are shipped as compatibility targets unless a release note says otherwise.
+
+---
+
+## Table of Contents
+
+- [Fundamentals](#fundamentals)
+- [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 & External Tools](#mcp-servers--external-tools)
+- [CLI Reference](#cli-reference)
+- [Plugin File Tree](#plugin-file-tree)
+- [Requirements](#requirements)
+- [Updates](#updates)
+- [What Ships To npm](#what-ships-to-npm)
+- [Development](#development)
+- [Project Validation Harness](#project-validation-harness)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+
+---
+
+## Fundamentals
+
+If you're new to AI coding agents, four words you need to know:
+
+- **Agent** — a conversational AI assistant that reads, writes, and modifies code in your project.
+- **Plugin** — an installable package that gives an agent new capabilities: specialist skills, MCP connections, configuration.
+- **Skill** — a focused expert inside a plugin. Each skill owns one thing (modeling, DAX, performance).
+- **MCP** — Model Context Protocol. An open standard that lets an agent talk to external tools.
+
+BI Agent Superpowers is a plugin: 9 skills, 2 MCPs, one CLI. The agent does the typing; the skills tell it which tools, files, prerequisites, and guardrails apply to Power BI work — so it ships work that holds up in production instead of inventing DAX, PBIR, or setup steps.
+
+---
+
+## Install From Terminal
+
+### All Supported Agents
+
+Use this when you want one command path for Codex and the compatibility adapters for Claude Code, GitHub Copilot, Gemini CLI, and Kilo Code.
+
+```bash
+npm install -g 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 bi-superpowers
+super install
+```
+
+### Install For One Agent Only
+
+```bash
+# Claude Code user-level skills + MCP config
+super install --agent claude-code --yes
+
+# GitHub Copilot
+super install --agent github-copilot --yes
+
+# Codex
+super install --agent codex --yes
+
+# Gemini CLI
+super install --agent gemini-cli --yes
+
+# Kilo Code
+super install --agent kilo --yes
+```
+
+### Claude Code Marketplace Install
+
+If you use Claude Code, the marketplace path is the cleanest install experience for that agent. Claude Code is a compatibility target; Codex remains the primary end-to-end validation baseline.
+
+```text
+/plugin marketplace add luquimbo/bi-superpowers
+/plugin install bi-superpowers
+```
+
+After that, start a new session and run:
+
+```text
+/bi-start
+```
+
+### 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
+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 bi-superpowers
+super kickoff
+
+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 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 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 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.
+```
+
+### Kilo Code
+
+```text
+Set up BI Agent Superpowers for Kilo Code on this machine.
+
+In the terminal, run:
+
+npm install -g bi-superpowers
+super install --agent kilo --yes
+
+After it finishes, verify that ~/.kilo/skills and ~/.config/kilo/kilo.jsonc 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 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
+
+Nine specialist skills. Each owns one thing — and each teaches as it works: it asks in plain business language, explains the *why* before each step, defines terms on first use, and shows a worked example, so a non-technical user learns while the work gets done.
+
+### `/bi-start` — Session Orchestrator
+
+Opens a clean session, checks for plugin updates, shows the skill menu, and routes the conversation to the right specialist.
+
+Use when starting a new session, when you don't know which skill to invoke, or when you want an update check before work begins.
+
+### `/bi-kickoff` — Project Bootstrap
+
+From zero to a working BI project. Bootstraps a fresh project from `base-template`, guides a short business intake, builds a domain semantic model with demo data through MCP, and keeps the project context Codex-first. For an existing PBIP/PBIX project, use `/bi-refactor` instead.
+
+Use when starting a brand-new Power BI project or bootstrapping a model from `base-template`. For an existing project, use `/bi-refactor`.
+
+### `/bi-refactor` — Refactor Specialist
+
+Cleans up an existing project. Diagnoses an existing PBIP/PBIX, proposes template-assisted fixes, and applies semantic-model cleanup through MCP — preserving report topology, never rebuilding visuals, pages, or bookmarks.
+
+Use when modernizing an existing model, migrating it toward `base-template` patterns, or repairing model issues without touching the report layout.
+
+### `/bi-modeling` — Model Architect
+
+Star schemas, relationships, TMDL. Designs and audits semantic models against a health checklist (date table, fact/dim split, relationship cardinality, hidden technical columns).
+
+Use when designing a new model, refactoring an existing one, or running a health audit before shipping.
+
+### `/bi-dax` — DAX Expert
+
+Measures that compute the right thing. Authors, debugs, and optimizes DAX — measures, calculation groups, SE/FE timing, Sallieri patterns, calculation items.
+
+Use when writing or fixing measures, untangling time-intelligence, or chasing a slow expression with DAX Studio timings.
+
+### `/bi-performance` — Performance Engineer
+
+Diagnose slow models. Fix them. Profiles refreshes and reports with Performance Analyzer, DAX Studio / VertiPaq Analyzer metrics, Tabular Editor 2, and Best Practice Analyzer.
+
+Use when reports are slow, when refresh blows up, or when you need a defensible "this is the bottleneck" answer before optimizing.
+
+### `/bi-connect` — MCP Connection Specialist
+
+Wire your agent to Power BI Desktop. Connects through the Microsoft Power BI Modeling MCP so the agent can read tables, columns, measures, and relationships, run DAX, and write user-defined functions using current Microsoft Learn syntax and DAXLIB patterns.
+
+Use when you need live model access, want to execute DAX queries, or are authoring DAX UDFs. Model writes go through MCP; PBIP files stay as saved/exported version-control snapshots.
+
+### `/bi-powerquery` — Power Query Engineer
+
+Connect real data without breaking the demo. Creates strict M staging queries for real business data and appends them to the current model's business tables using the `Data = "Demo"` / `Data = "Real"` contract.
+
+Use when wiring real Excel/SQL/SharePoint/API data to a generated BI model, generating `*_Real` staging queries, or keeping demo rows while the report switches between demo and real data. The packaged example knows the full Andina Nexus product-and-services contract; generated projects discover destination tables from the current model instead of assuming a fixed commercial schema.
+
+### `/bi-scorecard` — Scorecards Specialist
+
+Targets, goals, and check-ins in Power BI Service. Builds scorecard blueprints from the `base-template` metrics catalog, including the Andina Nexus `Dirección` executive lens and multi-team metric ownership, creates and updates scorecards and goals through REST scripts, and manages check-ins and status rules.
+
+Use when creating Power BI Scorecards/Goals from model metrics, defining owners, cadence, targets, and status rules, or refreshing connected goal values.
+
+The skill follows Microsoft Learn scorecard limits: no BYOK/RLS, max four subgoal levels, no publish-to-web, no SharePoint scorecard visual embed, no cross-tenant B2B sharing, no Multi-Geo, and no embedded analytics.
+
+## Quick Demos
+
+### Start A Session
+
+```text
+/bi-start
+```
+
+Expected result:
+
+- update check;
+- menu of 9 skills;
+- environment hints;
+- next-step recommendation.
+
+### Refactor An Existing Power BI Project
+
+```text
+/bi-refactor
+Diagnose this existing PBIP/PBIX project. Tell me what exists, what is missing, and what to clean up.
+```
+
+Expected result:
+
+- project map;
+- risks and missing context;
+- recommended cleanup path (model + measures);
+- report topology preserved — no destructive rebuilds.
+
+### Connect To Power BI Desktop
+
+```text
+/bi-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.
+
+### Write A DAX UDF With DAXLIB As Reference
+
+```text
+/bi-connect
+Write a reusable DAX UDF for gross margin percentage. Use Microsoft Learn for the current UDF syntax and consult DAXLIB patterns before proposing the function.
+```
+
+Expected result:
+
+- current UDF syntax/preview check;
+- existing function inspection when a model is connected;
+- DAXLIB-aware pattern selection without vendoring external code by default;
+- tested function draft and validation steps.
+
+## Supported Agents
+
+| Agent | Skill install path | MCP config path | Primary usage | Validation status |
+|---|---|---|---|---|
+| Codex | `~/.agents/skills/` | `~/.codex/config.toml` | Natural language with skills and MCPs | Primary end-to-end test baseline |
+| Claude Code | `~/.claude/skills/` or marketplace plugin | `~/.claude.json` | Slash commands and natural language | Compatibility target; not the primary end-to-end QA baseline |
+| GitHub Copilot | `~/.copilot/skills/` | `~/.copilot/mcp-config.json` | Natural language with skills and MCPs | Compatibility target; not the primary end-to-end QA baseline |
+| Gemini CLI | `~/.gemini/skills/` | `~/.gemini/settings.json` | Natural language | Compatibility target; not the primary end-to-end QA baseline |
+| Kilo Code | `~/.kilo/skills/` | `~/.config/kilo/kilo.jsonc` | Natural language | Compatibility target; not the primary end-to-end QA baseline |
+
+The installer always writes the universal skill copy to `~/.agents/skills/`, then links or copies agent-specific skill directories as needed.
+
+---
+
+## MCP Servers & External Tools
+
+Two official Microsoft MCPs ship pre-wired. One open-source CLI is invoked by `/bi-performance`.
+
+| Tool | Owner | Transport | Purpose |
+|---|---|---|---|
+| `powerbi-modeling-mcp` | Microsoft (official) | local stdio | Connects to Power BI Desktop through XMLA for model inspection, DAX queries, and model operations. |
+| `microsoft-learn` | Microsoft (official) | HTTP | Gives the agent access to Microsoft Learn documentation in context. |
+| `Tabular Editor 2 CLI` | Open-source, MIT | local CLI | Best Practice Analyzer runs for diagnostic rule checks; `/bi-performance` does not perform semantic-model or report writes. |
+
+You can install the MCPs manually, but `super install` writes the expected MCP config for each selected agent automatically.
+For Codex installs, it also pins per-tool approval gates for sensitive Power BI Modeling MCP calls: semantic-model writes and `trace_operations`, because traces can include query text and write JSON files locally. Connection discovery and DAX query/validation remain ungated by default because they do not mutate the model and are needed for smoke tests; stricter teams can still add host-level approvals for those read/query tools. Other agents rely on their own MCP permission prompts or allowlists.
+
+For DAX user-defined functions, `/bi-connect` also points agents at DAXLIB as an upstream reference:
+
+- https://github.com/daxlib/daxlib
+- https://docs.daxlib.org/
+
+BI Agent Superpowers does not vendor DAXLIB source code. Agents consult it as a reference and only import/adapt specific MIT-licensed functions when the user explicitly requests that.
+
+---
+
+## CLI Reference
+
+The package exposes both `super` and `bi-superpowers`:
+
+```bash
+super help
+bi-superpowers help
+```
+
+Common commands:
+
+```bash
+super install                # Install 9 skills + 2 MCPs for selected agents
+super uninstall              # Remove the skills + 2 MCPs (mirror of install)
+super uninstall --dry-run    # Preview what an uninstall would remove
+super kickoff                # Advanced: generate optional local Claude Code plugin files
+super recharge               # Regenerate optional local Claude Code plugin artifacts
+super create-from-template   # Scaffold a new PBIP project from templates/<name>/ into pbip-files/
+super powers                 # List available skills
+super scan                   # Compare source skills with generated artifacts
+super checkup                # Validate skill content
+super validate-cases         # List validation playbooks or print one
+super smoke-test             # Run the live base-template smoke test directly
+super validate-projects      # Validate repo fixtures + local private project refs
+super build-desktop          # Build the Claude Desktop .mcpb extension in the current dir
+super build-desktop --output dist
+super upgrade                # Update the global CLI and print refresh steps
+super autoupdate on          # Opt-in: silent self-update on each Claude Code session
+super autoupdate off         # Turn the auto-update hook back off
+super autoupdate status      # Show whether auto-update is enabled
+super help                   # Show full CLI help
+```
+
+### Auto-update (opt-in, Claude Code)
+
+Off by default. Run `super autoupdate on` (or `super install --auto-update`) to
+register a Claude Code `SessionStart` hook. From then on, each new Claude Code
+session checks **at most once per hour** and, if a newer version exists, silently
+upgrades via npm (`npm install -g bi-superpowers@latest`) and refreshes
+your agents (`super install --all --yes`) in a detached background process — so you
+never install by hand. It is npm-based, so it works even if the GitHub repo is
+private. Turn it off anytime with `super autoupdate off`. Other agents (Codex,
+Copilot, Gemini, Kilo) keep the notify-on-invocation flow plus manual `super upgrade`.
+
+### `super create-from-template`
+
+```bash
+super create-from-template --list
+super create-from-template --template base-template --name <projectName>
+super create-from-template --template base-template --name <projectName> --target /path/to/project
+super create-from-template --template base-template --name <projectName> --dry-run
+super create-from-template --template base-template --name <projectName> --force
+```
+
+Used by the `bi-kickoff` skill PHASE 0 Option A (start from template) so agents do not have to copy files by hand. The command copies `templates/<name>/` into `<target>/pbip-files/<projectName>.*`, renames the PBIP descriptor and the `.SemanticModel/` / `.Report/` folders, rewrites internal cross-references (`.pbip → Report.path`, `definition.pbir → datasetReference.byPath.path`), and regenerates the Fabric `logicalId` in both `.platform` files. It refuses to overwrite an existing PBIP unless `--force` is passed, skips the template's own `AGENTS.md`, skips local Desktop/editor state such as `.pbi`, `localSettings.json`, `cache.abf`, and `DAXQueries`, and when forced cleans only the destination `<projectName>.pbip`, `<projectName>.SemanticModel`, and `<projectName>.Report` paths before copying again.
+
+The packaged template is `base-template`, the canonical dynamic-first reference for new Power BI projects. Dynamic metric format strings stay safe and unscaled for numeric visuals; compact abbreviations live in dedicated text helper measures for KPI labels.
+
+`super mcp-setup` is intentionally not part of normal setup. It only refreshes MCP config inside an existing local Claude Code plugin created by `super kickoff`; it refuses to write repo-local config in arbitrary projects. For Codex, GitHub Copilot, Gemini CLI, Kilo Code, and normal Claude Code user-level installs, use `super install --all --yes`.
+
+---
+
+## 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
+│  ├─ bi-kickoff.md
+│  ├─ bi-connect.md
+│  ├─ bi-modeling.md
+│  ├─ bi-dax.md
+│  ├─ bi-performance.md
+│  ├─ bi-powerquery.md
+│  └─ bi-scorecard.md
+├─ skills/
+│  ├─ bi-start/
+│  │  ├─ SKILL.md
+│  │  └─ scripts/update-check.js
+│  ├─ bi-kickoff/
+│  │  ├─ SKILL.md
+│  │  └─ scripts/update-check.js
+│  ├─ bi-connect/
+│  │  ├─ SKILL.md
+│  │  └─ scripts/update-check.js
+│  ├─ bi-powerquery/
+│  │  ├─ SKILL.md
+│  │  ├─ references/
+│  │  └─ scripts/
+│  │     ├─ update-check.js
+│  │     ├─ new-powerquery-staging.ps1
+│  │     └─ test-powerquery-contract.ps1
+│  └─ bi-scorecard/
+│     ├─ SKILL.md
+│     └─ scripts/
+│        ├─ update-check.js
+│        ├─ powerbi-scorecards-api.ps1
+│        ├─ powerbi-goals-api.ps1
+│        ├─ powerbi-goal-values-api.ps1
+│        ├─ powerbi-goal-status-rules-api.ps1
+│        └─ new-scorecard-blueprint-from-base-template.ps1
+└─ config.json
+```
+
+### 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"]
+```
+
+---
+
+## Requirements
+
+### Base Requirements
+
+- Node.js 18 or newer.
+- At least one supported AI agent.
+
+### For `bi-connect`
+
+- Windows.
+- Power BI Desktop open.
+- Power BI Modeling MCP available to the agent.
+
+## Updates
+
+### Claude Code Marketplace
+
+```text
+/plugin update bi-superpowers
+```
+
+### npm / CLI Installs
+
+```bash
+super upgrade
+super install --all --yes
+```
+
+If you created a project-local plugin:
+
+```bash
+cd your-power-bi-project
+super recharge
+```
+
+`super upgrade` intentionally does not run `super install` or `super recharge` automatically. User-profile installs and project-local plugins are separate refresh targets.
+
+On Windows, if symlink creation is not available and the installer falls back to copying skills, each re-run mirrors the managed skill directories. Removed or renamed bundled scripts are deleted from the copied install during refresh.
+
+---
+
+## What Ships To npm
+
+The npm package includes:
+
+```text
+bin/
+.claude-plugin/
+.plugin/
+.mcp.json
+commands/
+skills/
+src/content/
+templates/
+desktop-extension/
+config.json
+config.example.json
+README.md
+CHANGELOG.md
+AGENTS.md
+LICENSE
+package.json
+```
+
+The npm package does not include:
+
+```text
+validation/
+validation.local.example.json
+validation.local.json
+node_modules/
+*.test.js
+**/.pbi/localSettings.json
+```
+
+`templates/` ships the canonical `templates/base-template/` PBIP package with `AGENTS.md`, semantic model, and report definition. It is the "template-as-reference" used by all specialist skills and the source for the `bi-kickoff` "create from template" branch invoked via `super create-from-template`, which copies `templates/base-template/` into `<user-repo>/pbip-files/<projectName>.*` with renaming, cross-reference rewriting, and regenerated logicalIds. The base template includes Power Query pre-converted currency base columns, packaged sample queries grouped under `Sample Dataset\Dimensiones` and `Sample Dataset\Hechos`, `_GC Métrica` / `_GC Tipo cálculo` calculation groups, guarded metric dispatch, metric-aware dynamic dimensions through `_PC Dimensión`, a `Equipos métricas[Equipo]` slicer for filtering the metric selector by team, multi-team metric memberships through `_Aux Métrica-Equipo`, nine Equipos (eight operating teams plus `Dirección`) for the Andina Nexus product-and-services demo company, team-specific model-view diagrams, safe unscaled numeric model formats, compact KPI label helpers, cleaned key metadata, and a `Data = "Demo"` contract on appendable business tables. Demo IDs are entity-coded text values such as `ClienteA25D`, so relationships stay on the original ID columns while real rows can append with `Data = "Real"` and their own source IDs. `/bi-powerquery` creates the user-side real staging queries; the template itself does not ship unloaded `*_Real` queries. `/bi-scorecard` uses `base-template` as a metrics-catalog reference for Service scorecards; it does not add a universal targets model to the template.
+`validation/` is repo-only. It stores sanitized validation descriptors and playbooks for project QA; private project paths live in `validation.local.json`, which must never be committed.
+
+---
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Regenerate plugin artifacts:
+
+```bash
+npm run build:plugin
+```
+
+Validate locally:
+
+```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.
+
+---
+
+## Project Validation Harness
+
+In a source checkout, the repo can validate BI Agent Superpowers against real
+Power BI work without committing customer repositories.
+
+Public fixtures live in:
+
+```text
+templates/base-template/
+```
+
+Sanitized validation metadata lives in:
+
+```text
+validation/projects/
+validation/cases/
+```
+
+Private local project paths live only in:
+
+```text
+validation.local.json
+```
+
+That file is gitignored. Copy `validation.local.example.json` when you want to
+map client projects on your own machine.
+Descriptors ending in `.example.json` are templates for humans and are ignored
+by validation runs, including `--strict`.
+
+Run the structural validation:
+
+```bash
+super validate-projects --project base-template
+```
+
+Run every descriptor, treating skipped private projects as failures:
+
+```bash
+super validate-projects --strict
+```
+
+For a live Power BI Desktop smoke test of the canonical template, use
+`validation/cases/base-template-smoke-test.md` after the structural validation
+passes. `super smoke-test` will probe the open Desktop sessions automatically
+and keep the one that matches the expected evidence, including seven metrics per
+team plus weekly fact, metric, and compatible dimension coverage for the last
+720 days.
+
+To discover the repo playbooks or print one in full:
+
+```bash
+super validate-cases
+super validate-cases --case base-template-smoke-test
+```
+
+This command is non-destructive. It checks project paths and required files; it
+does not open Power BI Desktop, edit PBIP files, or copy private repos.
+
+---
+
+## 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
+```
+
+The publish workflow runs on `v*` tag pushes. Manual dispatch is constrained to an already-tagged release commit on `main`.
+
+---
+
+## Troubleshooting
+
+### `super` is not found after npm install
+
+Check the global package:
+
+```bash
+npm list -g 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.
+
+---
+
+## FAQ
+
+### Does This Replace Power BI Desktop?
+
+No. Power BI Desktop remains the visual and report authoring tool. The plugin helps agents inspect project files and use MCPs for semantic-model work, but PBIP files are treated as version-control snapshots. Agents must not patch `.Report/**` PBIR JSON, `visual.json`, bookmarks, slicer/card settings, themes, or report resources directly.
+
+Existing-visual dimension/measure binding changes are the only report-side exception: they may happen in Power BI Desktop manually, or through a future dedicated rebind command that proves a binding-only diff with dry-run, backup, validation, and an explicit source-to-target mapping. No safe report rebind command currently ships with this plugin, so agents must not patch PBIR JSON by hand, even for a "simple measure replacement."
+
+Microsoft Learn's PBIP project guidance also marks `report.json`, `mobileState.json`, `semanticModelDiagramLayout.json`, and semantic-model `diagramLayout.json` as unsupported external-edit surfaces during preview. The plugin treats those files as diagnostic-only.
+
+**Report topology is locked.** Agents must never delete, rename, move, or recreate report pages, visuals, mobile layouts, or bookmarks to make a broken report look "fixed." They must not rebuild a "minimal functional report." Any added, deleted, or renamed path under `.Report/**` is a hard stop for semantic-model skills; the correct action is to preserve the report shell and hand the visual repair back to Power BI Desktop.
+
+### Does It Work Outside Windows?
+
+The CLI and several skills can run outside Windows. Workflows that depend on Power BI Desktop, especially `bi-connect`, are Windows-first.
+
+### Do I Need Claude Code?
+
+No. Codex is the primary development and end-to-end validation baseline for this plugin. Claude Code has a useful compatibility path through marketplace/local plugin artifacts, but it is not the canonical test base unless a release note explicitly says that release was tested there.
+
+### 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.
+
+---
+
+## 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/bi-superpowers
+
+Before large changes, read:
+
+- `AGENTS.md`
+- `ARCHITECTURE.md`
+- `src/content/`
+- `bin/`
+
+---
+
+## License
+
+MIT © Lucas Sanchez ([@luquimbo](https://github.com/luquimbo))
+
+---
+
+<div align="center">
+
+Open-source Power BI Desktop toolkit for AI coding agents. Built by Lucas Sanchez.
+
+[bi-superpowers.dev](https://bi-superpowers.dev) · [npm](https://www.npmjs.com/package/bi-superpowers) · [GitHub](https://github.com/luquimbo/bi-superpowers)
+
+</div>