@luquimbo/bi-superpowers 4.1.5 → 5.0.0

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "AI-powered skills for Power BI Desktop development. Works with Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code.",
-    "version": "4.1.5",
+    "version": "5.0.0",
     "repository": "https://github.com/luquimbo/bi-superpowers"
   },
   "plugins": [
@@ -16,10 +16,10 @@
       "source": "./",
       "strict": false,
       "skills": [
-        "./skills/bi-start",
-        "./skills/pbi-connect",
-        "./skills/project-kickoff",
-        "./skills/report-design"
+        "./skills/bi-connect",
+        "./skills/bi-kickoff",
+        "./skills/bi-report",
+        "./skills/bi-start"
       ]
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "bi-superpowers",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
-  "version": "4.1.5",
+  "version": "5.0.0",
   "author": {
     "name": "Lucas Sanchez"
   },

package/.claude-plugin/skill-manifest.json

@@ -1,39 +1,39 @@
 {
   "name": "bi-superpowers",
-  "version": "4.1.5",
+  "version": "5.0.0",
   "skillCount": 4,
   "skills": [
     {
-      "name": "bi-start",
-      "title": "BI Start Skill",
-      "description": "Use when the user asks about BI Start Skill, especially phrases like \"bi-start\", \"bi start\", \"/bi-start\", \"empezar\", \"comenzar\", \"arranco\".",
-      "category": "command",
-      "triggerCount": 22,
-      "path": "skills/bi-start/SKILL.md"
-    },
-    {
-      "name": "pbi-connect",
+      "name": "bi-connect",
       "title": "Power BI MCP Connection Skill",
-      "description": "Use when the user asks about Power BI MCP Connection Skill, especially phrases like \"connect Power BI\", \"PBI connection\", \"MCP connection\", \"Power BI MCP\", \"modeling mcp\", \"Power BI Modeling MCP\".",
+      "description": "Use when the user asks about Power BI MCP Connection Skill, especially phrases like \"connect Power BI\", \"PBI connection\", \"MCP connection\", \"Power BI MCP\", \"DAX UDF\", \"DAX user-defined function\".",
       "category": "command",
-      "triggerCount": 15,
-      "path": "skills/pbi-connect/SKILL.md"
+      "triggerCount": 26,
+      "path": "skills/bi-connect/SKILL.md"
     },
     {
-      "name": "project-kickoff",
+      "name": "bi-kickoff",
       "title": "Project Kickoff Skill",
       "description": "Use when the user asks about Project Kickoff Skill, especially phrases like \"I'm starting a brand-new BI project from scratch\", \"analizar proyecto\", \"analyze project\", \"project kickoff\", \"nuevo proyecto\", \"new project\".",
       "category": "command",
       "triggerCount": 15,
-      "path": "skills/project-kickoff/SKILL.md"
+      "path": "skills/bi-kickoff/SKILL.md"
     },
     {
-      "name": "report-design",
+      "name": "bi-report",
       "title": "Report Design Skill",
       "description": "Use when the user asks about Report Design Skill, especially phrases like \"crear reportes\", \"armar el reporte\", \"diseñar reporte\", \"report design\", \"create reports\", \"build dashboard\".",
       "category": "command",
       "triggerCount": 9,
-      "path": "skills/report-design/SKILL.md"
+      "path": "skills/bi-report/SKILL.md"
+    },
+    {
+      "name": "bi-start",
+      "title": "BI Start Skill",
+      "description": "Use when the user asks about BI Start Skill, especially phrases like \"bi-start\", \"bi start\", \"/bi-start\", \"empezar\", \"comenzar\", \"arranco\".",
+      "category": "command",
+      "triggerCount": 22,
+      "path": "skills/bi-start/SKILL.md"
     }
   ]
 }

package/.plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "spec": "open-plugin-spec@1",
   "name": "bi-superpowers",
-  "version": "4.1.5",
+  "version": "5.0.0",
   "description": "Claude Code plugin for Power BI, Microsoft Fabric, and semantic model workflows powered by the official Microsoft MCP servers.",
   "author": {
     "name": "Lucas Sanchez"

package/AGENTS.md

@@ -12,8 +12,10 @@
 
 ## Project Entry Points
 - `AGENTS.md` (this file)
-- `library/`
+- `src/content/`
+- `bin/`
 - `config.json`
+- `validation/` (repo-only project validation descriptors and playbooks)
 
 ## Publishing to npm (for AI agents)
 
@@ -40,14 +42,18 @@ The repo uses **GitHub Actions** to publish automatically. The `NPM_TOKEN` is st
    ```
 5. **Run the local validations** (these also run in CI, but fail fast locally):
    ```bash
+   npm test
    npm run build:plugin
    npm run lint
    npm run format:check
+   npm audit --omit=dev --audit-level=moderate
+   node bin/cli.js scan --verbose
+   npm pack --dry-run --ignore-scripts
    ```
 6. **Commit with conventional commit message:**
    ```bash
-   git add package.json package-lock.json [+ any regenerated files]
-   git commit -m "chore: bump version to X.Y.Z"
+   git add package.json package-lock.json [+ source, docs, tests, regenerated files]
+   git commit -m "fix: describe the release change"
    ```
 7. **Create the version tag:**
    ```bash
@@ -94,24 +100,24 @@ npm install -g @luquimbo/bi-superpowers
 super install
 ```
 
-The shared v4.1.x contract is:
-- **4 skills** — `bi-start` (session opener), `project-kickoff`, `pbi-connect`, `report-design`
+The shared v5.0.x contract is:
+- **4 skills** — `bi-start` (session opener), `bi-kickoff`, `bi-connect`, `bi-report`
 - **2 MCP servers** — `powerbi-modeling-mcp`, `microsoft-learn`
 
 Agent-specific behavior:
 - **All agents** — the primary install is user-level via `super install`, not repo-local.
-- **Claude Code** — `super kickoff` can optionally generate a project-local plugin with slash commands: `/bi-start`, `/project-kickoff`, `/pbi-connect`, `/report-design`.
+- **Claude Code** — `super kickoff` can optionally generate a project-local plugin with slash commands: `/bi-start`, `/bi-kickoff`, `/bi-connect`, `/bi-report`.
 - **GitHub Copilot** — uses the installed user-level skills + MCP config via natural-language prompts.
 - **Codex** — uses the installed user-level skills + MCP config via natural-language prompts. Do not run `super kickoff` for Codex setup.
 - **Gemini CLI** — uses the installed user-level skills + MCP config via natural-language prompts.
 - **Kilo Code** — uses the installed user-level skills + MCP config via natural-language prompts.
 
-`/report-design` has one extra runtime prerequisite on every agent: **Windows + Power BI Desktop (standalone) + Python 3.10+ + `pipx` + `pbi-cli-tool`**. The bundled Node scripts handle visual/theme authoring, but the current flow still uses `pbi` for connect, page ops, and validate. If that stack is not available yet, start with `bi-start`, `project-kickoff`, or `pbi-connect`.
+`/bi-report` has one extra runtime prerequisite on every agent: **Windows + Power BI Desktop (standalone) + Python 3.10+ + `pipx` + `pbi-cli-tool`**. The bundled Node scripts handle visual/theme authoring, but the current flow still uses `pbi` for connect, page ops, and validate. If that stack is not available yet, start with `bi-start`, `bi-kickoff`, or `bi-connect`.
 
 ### Claude Desktop
 
 ```bash
-super build-desktop
+super build-desktop --output dist
 # Double-click bi-superpowers.mcpb para instalar en Claude Desktop
 ```
 
@@ -137,6 +143,29 @@ Los 4 skills quedan disponibles como MCP prompts.
 5. **Document Results**: Add a review section when task tracking is in scope.
 6. **Capture Lessons**: Update lessons only when the repo uses it or the user requests it.
 
+## Project Validation Harness
+
+Use `validation/` when the user wants to test the plugin against public fixtures
+or private client projects. Keep this boundary:
+
+- `examples/smoke-test/` is the public fixture area.
+- `validation/projects/*.json` stores sanitized metadata only.
+- `validation/cases/*.md` stores manual validation playbooks.
+- `validation.local.json` stores private local repo paths and is gitignored.
+- `validation/runs/` stores local logs and is gitignored.
+
+Never copy customer repositories, `.pbix`, Excel files, credentials,
+screenshots with private data, or private Git remotes into this public repo. Run
+structural checks with:
+
+```bash
+super validate-projects --project super-test
+super validate-projects --strict
+```
+
+MCP-backed validation still happens in the external client repo or public
+fixture; this repo records only sanitized evidence and repeatable checks.
+
 ## Core Principles
 
 - **Simplicity First**: Minimal, clear changes.
@@ -148,9 +177,9 @@ Los 4 skills quedan disponibles como MCP prompts.
 | Skill | Purpose | Trigger |
 |-------|---------|---------|
 | `/bi-start` | Session opener: environment snapshot, update check, and routing to the specialist skills | "bi-start", "empezar", "start session" |
-| `/project-kickoff` | Analyze and plan BI projects | "analyze project", "new project" |
-| `/pbi-connect` | Connect to Power BI Desktop | "connect Power BI", "MCP" |
-| `/report-design` | Generate PBIR report pages via bundled Node scripts | "report design", "crear reportes" |
+| `/bi-kickoff` | Analyze and plan BI projects | "analyze project", "new project" |
+| `/bi-connect` | Connect to Power BI Desktop and guide DAX UDF authoring with Microsoft Learn + DAXLIB references | "connect Power BI", "MCP", "DAX UDF", "DAXLIB" |
+| `/bi-report` | Generate PBIR report pages via bundled Node scripts | "report design", "crear reportes" |
 
 ## MCP Servers (2)
 
@@ -165,6 +194,8 @@ Los 4 skills quedan disponibles como MCP prompts.
 
 BI Agent Superpowers installs skills and MCP configuration at the user level for all supported agents. It can also generate a native Claude Code plugin from the same source of truth when a user explicitly wants repo-local Claude Code plugin files.
 
+`super mcp-setup` is local-plugin maintenance only. It must run inside a repo already initialized by `super kickoff` (detected by `.bi-superpowers.json` or `.claude-plugin/plugin.json`). Do not use it for Codex, GitHub Copilot, Gemini CLI, Kilo Code, or normal Claude Code user-level setup; use `super install --all --yes` instead.
+
 ### Output Targets
 
 | Target | Format | Output |
@@ -179,10 +210,9 @@ BI Agent Superpowers installs skills and MCP configuration at the user level for
 project/
 ├── .claude-plugin/plugin.json   # Plugin manifest
 ├── .mcp.json                    # Power BI Modeling + Microsoft Learn MCPs
-├── commands/*.md                # 4 slash commands (bi-start, pbi-connect, project-kickoff, report-design)
+├── commands/*.md                # 4 slash commands (bi-start, bi-connect, bi-kickoff, bi-report)
 ├── skills/*/SKILL.md            # 4 skills (discoverable)
-├── config.json                  # User preferences
-└── library/ → symlink           # Snippets, templates, themes
+└── config.json                  # User preferences
 ```
 
 ### Desktop Extension (generated by build-desktop)
@@ -195,51 +225,15 @@ desktop-extension/
 └── skills/           # Bundled at build time
 ```
 
-Run `bi-superpowers recharge` after modifying skills to regenerate the plugin.
-
----
-
-## Library Resources
-
-The `library/` folder contains reusable assets:
-
-```
-library/
-├── snippets/           # Code patterns
-│   ├── dax/            # Time intelligence, rankings, CALCULATE
-│   ├── power-query/    # Transformations, error handling
-│   ├── excel-formulas/ # Dynamic arrays, lookups
-│   ├── report-design/  # Chart selection, accessibility, layouts
-│   └── governance/     # Naming conventions, review checklists
-├── templates/          # Project templates
-│   ├── power-bi/
-│   ├── excel/
-│   └── data-models/
-├── themes/             # Visual themes
-│   └── power-bi/       # JSON theme files
-└── examples/           # Reference implementations
-    ├── finance-reporting/
-    ├── hr-analytics/
-    ├── retail-analytics/
-    ├── supply-chain/
-    └── marketing-analytics/
-```
-
-Reference patterns in prompts:
-```
-"Using patterns from library/snippets/dax/time-intelligence.md,
-create a rolling 12-month average measure"
-```
-
----
+Run `npm run build:plugin` after modifying source skills, or `super recharge` when refreshing an initialized local Claude Code plugin in a user project.
 
 ## Configuration
 
-Project-local user preferences live in `config.json`:
+Optional project-local user preferences live in `config.json` when a local Claude Code plugin is initialized:
 
 - This file is meant to be read by your AI tool as **context** (experience level, language, domain terms).
-- `bi-superpowers kickoff` will create it automatically from the package template if it doesn't exist.
-- The CLI stores selected AI tools in `.bi-superpowers.json` (also project-local) so `bi-superpowers recharge` knows what to regenerate.
+- `super kickoff` creates it automatically from the package template if it doesn't exist.
+- The CLI stores local-plugin metadata in `.bi-superpowers.json` so `super recharge` and `super mcp-setup` can refresh the initialized plugin safely.
 
 ```json
 {
@@ -295,6 +289,8 @@ Connect AI assistants directly to Power BI and Excel:
 | MCP Protocol | https://modelcontextprotocol.io |
 | Power BI Docs | https://docs.microsoft.com/power-bi |
 | DAX Guide | https://dax.guide |
+| DAX UDF Docs | https://learn.microsoft.com/en-us/dax/best-practices/dax-user-defined-functions |
+| DAXLIB | https://github.com/daxlib/daxlib |
 
 ---
 

package/CHANGELOG.md

@@ -5,6 +5,73 @@ All notable changes to BI Agent Superpowers will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [5.0.0] — 2026-04-28
+
+### Breaking
+
+- Standardized all public slash commands under the `/bi-*` namespace:
+  `/project-kickoff` is now `/bi-kickoff`, `/pbi-connect` is now
+  `/bi-connect`, and `/report-design` is now `/bi-report`.
+- Regenerated the Claude Code plugin commands, user-level skills, skill
+  manifests, docs, and validation fixtures for the new command names.
+
+### Added
+
+- Added the project validation harness and public `super validate-projects`
+  QA command for checking the bundled smoke project plus private client
+  descriptors without vendoring client repositories.
+- `bi-connect` now includes a DAX UDF wiki that tells installed agents to use
+  Microsoft Learn for current UDF syntax and DAXLIB as an upstream reference for
+  reusable function patterns, without vendoring DAXLIB source by default.
+
+### Fixed
+
+- `super validate-projects` now fails fast when `validation/projects` is missing,
+  so running it from the wrong directory cannot false-green with `0 checked`.
+- Generated command and skill edit comments now point folder-based skills at the
+  real source path, for example `src/content/skills/bi-report/SKILL.md`.
+- README update instructions use a neutral project placeholder and the BI Report
+  runtime table-of-contents anchor now matches the heading.
+- Historical changelog entries were restored to the command and file names that
+  actually shipped in those older releases.
+
+## [4.1.6] — 2026-04-24
+
+### Fixed
+
+- `super mcp-setup` now rejects every repo-local target, including legacy
+  `--tool cursor`, `--tool vscode`, `--tool kilocode`, `--tool open-code`, and
+  `--tool claude-code`, unless the target repo already has a BI Superpowers
+  local plugin marker from `super kickoff`.
+- `super mcp-setup` now refuses to overwrite corrupt existing JSON configs and
+  writes through the same atomic backup path used by the user-level MCP config
+  writer.
+- `super install` copy-mode refreshes now mirror managed skill directories, so
+  runtime scripts and references removed in a newer package cannot remain
+  installed from an older package.
+- `super build-desktop --output <path>` now honors the documented output path.
+
+### Changed
+
+- README, AGENTS, CLAUDE, Getting Started, Architecture, Security, Contributing,
+  and Roadmap docs now consistently describe the user-level install contract and
+  the optional local Claude Code plugin path.
+
+## [4.1.5] — 2026-04-24
+
+### Fixed
+
+- Removed the obsolete `coordination/` QA shortcut from `AGENTS.md`.
+- `super mcp-setup --tool claude-plugin` no longer creates `.mcp.json` in an
+  arbitrary directory without an existing local plugin marker.
+- User-level MCP config writes validate the final path, `.tmp`, and `.bak`
+  paths before writing, rejecting pre-existing symlinks.
+- `super upgrade` now points users to the canonical
+  `super install --all --yes` refresh command.
+- Kilo Code path documentation now consistently uses `~/.kilo/mcp_settings.json`.
+
 ## [4.1.4] — 2026-04-24
 
 ### Fixed

package/README.md

@@ -16,7 +16,7 @@ This is not a loose prompt pack. It is a reproducible Power BI agent layer:
 - **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.
+> Status: `v5.0.x` is the current stable release line. The v5 line standardizes every public slash command under the `/bi-*` namespace.
 
 ---
 
@@ -32,10 +32,11 @@ 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)
+- [BI Report Runtime](#bi-report-runtime)
 - [Updates](#updates)
 - [What Ships To npm](#what-ships-to-npm)
 - [Development](#development)
+- [Project Validation Harness](#project-validation-harness)
 - [Troubleshooting](#troubleshooting)
 - [FAQ](#faq)
 
@@ -258,7 +259,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,7 +269,7 @@ 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.
 
@@ -277,8 +278,9 @@ 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.
+- you want to write or review DAX user-defined functions using current Microsoft Learn syntax and DAXLIB patterns.
 
-### `report-design`
+### `bi-report`
 
 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.
 
@@ -310,7 +312,7 @@ Expected result:
 ### 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 +321,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` or `bi-report` 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,10 +336,24 @@ Expected result:
 - 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.
+
 ### Generate A Report Page
 
 ```text
-/report-design
+/bi-report
 Create an executive sales page with KPI cards, monthly trend, product ranking, and a slicer panel.
 ```
 
@@ -374,6 +390,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
@@ -394,11 +418,15 @@ 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 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 help             # Show full CLI help
 ```
 
+`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
@@ -420,20 +448,20 @@ project/
 ├─ .mcp.json
 ├─ commands/
 │  ├─ bi-start.md
-│  ├─ project-kickoff.md
-│  ├─ pbi-connect.md
-│  └─ report-design.md
+│  ├─ bi-kickoff.md
+│  ├─ bi-connect.md
+│  └─ bi-report.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/
+│  └─ bi-report/
 │     ├─ SKILL.md
 │     ├─ scripts/
 │     │  ├─ apply-theme.js
@@ -476,13 +504,13 @@ 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`
+### For `bi-report`
 
 - Windows.
 - Power BI Desktop standalone, not the Microsoft Store build.
@@ -493,9 +521,9 @@ flowchart TD
 
 ---
 
-## Report Design Runtime
+## BI Report Runtime
 
-`report-design` uses bundled Node scripts for PBIR visual and theme authoring:
+`bi-report` uses bundled Node scripts for PBIR visual and theme authoring:
 
 - `create-visual.js`
 - `apply-theme.js`
@@ -511,7 +539,7 @@ It still uses `pbi-cli-tool` for the current runtime flow:
 - `pbi report list-pages`
 - `pbi report validate`
 
-This means `pbi-cli-tool` is not optional for `report-design` today.
+This means `pbi-cli-tool` is not optional for `bi-report` today.
 
 ---
 
@@ -539,6 +567,8 @@ 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
@@ -566,12 +596,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.
 
 ---
 
@@ -618,6 +653,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 super-test
+```
+
+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.
@@ -672,7 +751,7 @@ 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
+### `bi-report` 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.
 
@@ -697,7 +776,7 @@ No. Power BI Desktop remains the visual/runtime verification tool. The plugin he
 
 ### 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` and `bi-report`, are Windows-first.
 
 ### Do I Need Claude Code?
 
@@ -705,7 +784,7 @@ No. Claude Code has the richest plugin/slash-command experience, but the npm ins
 
 ### Do I Need `pbi-cli-tool`?
 
-For `report-design`, yes. For `bi-start`, `project-kickoff`, and `pbi-connect`, not necessarily.
+For `bi-report`, yes. For `bi-start`, `bi-kickoff`, and `bi-connect`, not necessarily.
 
 ### Can I Use Only The MCP Servers?