@luquimbo/bi-superpowers 4.1.6 → 5.0.1

package/README.md

@@ -7,16 +7,19 @@
 
 **BI Agent Superpowers** is an open-source toolkit that gives AI coding agents practical Power BI Desktop capabilities.
 
-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.
+It installs reusable agent skills, configures Microsoft MCP servers, and provides a small CLI called `super` so Codex, Claude Code, GitHub Copilot, 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.
+- **6 skills** for Power BI/project work: session startup, project bootstrap, semantic-model design and audit, DAX authoring and optimization, performance profiling with Tabular Editor 2 / BPA integration, and Power BI Desktop MCP connection.
 - **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.
+- **Codex-first skill and MCP installation**, plus compatibility adapters for other agents.
+- **Claude Code plugin artifacts** for users who explicitly want that local plugin format.
 
-> 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.
+> Status: `v5.0.x` is the current stable release line. The v5 line standardizes every public slash command under the `/bi-*` namespace.
+>
+> Validation baseline: BI Agent Superpowers is developed and stress-tested first in **Codex**. Other agent adapters are shipped as compatibility targets and may work, but they are not currently tested end-to-end with the same depth unless a release note says otherwise.
 
 ---
 
@@ -32,10 +35,10 @@ This is not a loose prompt pack. It is a reproducible Power BI agent layer:
 - [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)
+- [Project Validation Harness](#project-validation-harness)
 - [Troubleshooting](#troubleshooting)
 - [FAQ](#faq)
 
@@ -50,12 +53,12 @@ Power BI work with AI agents usually breaks down in predictable places:
 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:
+BI Agent Superpowers fixes that by giving Codex the primary tested Power BI workflow and exposing the same operating contract to compatible agents:
 
 - 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;
+- optional 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.
@@ -66,7 +69,7 @@ The goal is simple: open a Power BI project, ask your agent for help, and have t
 
 ### All Supported Agents
 
-Use this when you want one command path for Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.
+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 @luquimbo/bi-superpowers
@@ -105,7 +108,7 @@ super install --agent kilo --yes
 
 ### Claude Code Marketplace Install
 
-If you only use Claude Code, the marketplace path is the cleanest install experience:
+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
@@ -258,7 +261,7 @@ Use it when:
 - you do not know which skill to invoke;
 - you want the agent to check update status before work begins.
 
-### `project-kickoff`
+### `bi-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.
 
@@ -268,29 +271,16 @@ Use it when:
 - starting a new PBIP project;
 - asking an agent to understand project structure before editing.
 
-### `pbi-connect`
+### `bi-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.
+Power BI Desktop connection skill. It helps the agent connect to the open Power BI Desktop model through the Microsoft Power BI Modeling MCP. Model writes go through MCP; PBIP files are treated as saved/exported version-control snapshots.
 
 Use it when:
 
 - 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.
-
-### `report-design`
-
-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`.
-
----
+- you want to write or review DAX user-defined functions using current Microsoft Learn syntax and DAXLIB patterns.
 
 ## Quick Demos
 
@@ -303,14 +293,14 @@ Current runtime requirement: Windows + Power BI Desktop standalone + Python 3.10
 Expected result:
 
 - update check;
-- menu of 4 skills;
+- menu of 6 skills;
 - environment hints;
 - next-step recommendation.
 
 ### Analyze A Power BI Project
 
 ```text
-/project-kickoff
+/bi-kickoff
 Analyze this Power BI repo. Tell me what exists, what is missing, and what plan we should follow.
 ```
 
@@ -319,12 +309,12 @@ Expected result:
 - project map;
 - risks and missing context;
 - recommended implementation path;
-- handoff to `pbi-connect` or `report-design` when appropriate.
+- handoff to `bi-connect` when appropriate.
 
 ### Connect To Power BI Desktop
 
 ```text
-/pbi-connect
+/bi-connect
 Connect to the model currently open in Power BI Desktop and list tables, measures, columns, and relationships.
 ```
 
@@ -334,32 +324,29 @@ Expected result:
 - semantic model snapshot;
 - actionable diagnostics if Desktop or MCP wiring is not ready.
 
-### Generate A Report Page
+### Write A DAX UDF With DAXLIB As Reference
 
 ```text
-/report-design
-Create an executive sales page with KPI cards, monthly trend, product ranking, and a slicer panel.
+/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:
 
-- prerequisite checks;
-- page/layout plan;
-- PBIR visual generation;
-- validation against native visual types;
-- instructions to open and verify in Power BI Desktop.
-
----
+- 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 |
-|---|---|---|---|
-| 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 |
+| 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/` | `~/.kilo/mcp_settings.json` | 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.
 
@@ -374,6 +361,14 @@ The installer always writes the universal skill copy to `~/.agents/skills/`, the
 
 You can install these MCPs manually, but `super install` writes the expected MCP config for each selected agent automatically.
 
+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/
+- https://github.com/daxlib
+
+BI Agent Superpowers does not vendor DAXLIB source code. Agents should consult it as a reference and only import/adapt specific MIT-licensed functions when the user explicitly requests that.
+
 ---
 
 ## CLI Reference
@@ -388,12 +383,13 @@ bi-superpowers help
 Common commands:
 
 ```bash
-super install          # Install 4 skills + 2 MCPs for selected agents
+super install          # Install 6 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 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
@@ -423,35 +419,18 @@ project/
 ├─ .mcp.json
 ├─ commands/
 │  ├─ bi-start.md
-│  ├─ project-kickoff.md
-│  ├─ pbi-connect.md
-│  └─ report-design.md
+│  ├─ bi-kickoff.md
+│  └─ bi-connect.md
 ├─ skills/
 │  ├─ bi-start/
 │  │  ├─ SKILL.md
 │  │  └─ scripts/update-check.js
-│  ├─ project-kickoff/
+│  ├─ bi-kickoff/
 │  │  ├─ SKILL.md
 │  │  └─ scripts/update-check.js
-│  ├─ pbi-connect/
+│  ├─ bi-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
 ```
 
@@ -479,45 +458,12 @@ flowchart TD
 - Node.js 18 or newer.
 - At least one supported AI agent.
 
-### For `pbi-connect`
+### For `bi-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
@@ -571,12 +517,17 @@ package.json
 The npm package does not include:
 
 ```text
+docs/superpowers/
 examples/smoke-test/
+validation/
+validation.local.example.json
+validation.local.json
 node_modules/
 *.test.js
 ```
 
 `examples/smoke-test/` is intentionally repo-only. It is used for QA and manual validation, not for user installs.
+`validation/` is also 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.
 
 ---
 
@@ -623,6 +574,50 @@ 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
+examples/smoke-test/
+```
+
+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.
+
+Run the structural validation:
+
+```bash
+super validate-projects --project template
+```
+
+Run every descriptor, treating skipped private projects as failures:
+
+```bash
+super validate-projects --strict
+```
+
+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.
@@ -677,10 +672,6 @@ If npm's global bin directory is not in `PATH`, fix `PATH` or use your package m
 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`:
@@ -698,19 +689,17 @@ pbi --version
 
 ### 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.
+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.
+
+The only report-side exception is template adaptation through the dedicated plugin field-swap/rebind command. Agents must not patch PBIR JSON by hand, even for a "simple measure replacement." The command may write PBIR only for data bindings (`projections`, `prototypeQuery`, query refs, field parameters, and sort/filter field references when required), with dry-run, backup, validation, and an explicit source-to-target mapping. It must preserve visual type, layout, formatting, interactions, IDs, theme, and bookmarks. Until that tool exists, report field swaps remain manual Desktop work.
 
 ### 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.
+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. 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.
+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?
 

package/bin/cli.js

@@ -45,6 +45,7 @@ let watchCommand;
 let mcpSetupCommand;
 let buildDesktopCommand;
 let installCommand;
+let validateProjectsCommand;
 let tui;
 try {
   lintCommand = require('./commands/lint'); // checkup: skill file validation
@@ -53,6 +54,7 @@ try {
   mcpSetupCommand = require('./commands/mcp-setup'); // MCP server configuration
   buildDesktopCommand = require('./commands/build-desktop'); // .mcpb for Claude Desktop
   installCommand = require('./commands/install'); // multi-agent skill + MCP installer
+  validateProjectsCommand = require('./commands/validate-projects'); // repo/project validation harness
   tui = require('./utils/tui'); // colors, tables, boxes for CLI output
 } catch (_) {
   // Expected during `npm install` — modules become available after deps are linked.
@@ -157,7 +159,7 @@ Usage:
   super <command> [options]
 
 Primary commands:
-  install           Install the 4 skills + 2 MCPs user-level across your AI agents
+  install           Install ${TOTAL_SKILL_COUNT || 'the'} skills + 2 MCPs user-level across your AI agents
   kickoff [path]    Optional: generate a repo-local Claude Code plugin
   recharge [path]   Optional: regenerate an existing repo-local Claude Code plugin
   build-desktop     Build the .mcpb extension for Claude Desktop
@@ -171,6 +173,7 @@ Developer tools:
   checkup [file]    Lint/validate skill source files
   scan              Diff between source skills and generated plugin
   sentinel          Watch skill sources and auto-regenerate
+  validate-projects Validate public fixtures + local private project references
 
 Options:
   --dry-run         Preview changes without writing files (kickoff, recharge)
@@ -187,6 +190,7 @@ Examples:
   super build-desktop              # Build .mcpb for Claude Desktop
   super build-desktop --output dist
   super mcp-setup                  # Existing local Claude Code plugin only
+  super validate-projects          # Developer QA against validation/ descriptors
 
 Open source — MIT licensed.
 Documentation: https://github.com/luquimbo/bi-superpowers
@@ -757,6 +761,7 @@ const runDiff = createCommandWrapper(diffCommand, 'Diff');
 const runMcpSetup = createCommandWrapper(mcpSetupCommand, 'MCP setup');
 const runBuildDesktop = createCommandWrapper(buildDesktopCommand, 'Build Desktop');
 const runInstall = createCommandWrapper(installCommand, 'Install');
+const runValidateProjects = createCommandWrapper(validateProjectsCommand, 'Validate projects');
 
 // Register wrapper-based commands into the command map (phase 2).
 commands.install = runInstall;
@@ -766,6 +771,7 @@ commands.sentinel = runWatch;
 commands['mcp-setup'] = runMcpSetup;
 commands.mcp = runMcpSetup;
 commands['build-desktop'] = runBuildDesktop;
+commands['validate-projects'] = runValidateProjects;
 commands.lint = runLint;
 commands.diff = runDiff;
 commands.watch = runWatch;

package/bin/commands/diff.js

@@ -331,8 +331,8 @@ function diffCommand(args, config) {
   let skillFiles = [];
 
   if (options.skill) {
-    // normalizeSkillName accepts `dax`, `dax.md`, `report-design`, or
-    // `report-design/SKILL.md` and returns the canonical skill name.
+    // normalizeSkillName accepts `dax`, `dax.md`, `folder-skill`, or
+    // `folder-skill/SKILL.md` and returns the canonical skill name.
     const skill = skillsByName.get(normalizeSkillName(options.skill));
     if (skill) {
       skillFiles = [skill.path];