@luquimbo/bi-superpowers 4.1.0 → 4.1.2

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.0",
+    "version": "4.1.2",
     "repository": "https://github.com/luquimbo/bi-superpowers"
   },
   "plugins": [

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.0",
+  "version": "4.1.2",
   "author": {
     "name": "Lucas Sanchez"
   },

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

@@ -1,6 +1,6 @@
 {
   "name": "bi-superpowers",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "skillCount": 4,
   "skills": [
     {

package/.plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "spec": "open-plugin-spec@1",
   "name": "bi-superpowers",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "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

@@ -56,8 +56,7 @@ When the user asks for things like **"publica una nueva versión"**, **"publish
 The repo uses **GitHub Actions** to publish automatically. The `NPM_TOKEN` is stored as a GitHub Secret — never commit it to the repo or use it locally for publishes. The workflow at `.github/workflows/publish.yml` triggers on:
 
 1. **Tag push** (`v*`) — preferred, triggered by pushing a version tag
-2. **GitHub release published** — manual via web UI
-3. **Manual workflow dispatch** — via Actions tab
+2. **Manual workflow dispatch** — via Actions tab, only from `main` on the already-tagged release commit
 
 ### Standard publish flow (do this when asked)
 
@@ -84,7 +83,7 @@ The repo uses **GitHub Actions** to publish automatically. The `NPM_TOKEN` is st
    ```
 7. **Create the version tag:**
    ```bash
-   git tag vX.Y.Z
+   git tag -a vX.Y.Z -m "vX.Y.Z"
    ```
 8. **Push commits and tag together:**
    ```bash
@@ -127,18 +126,18 @@ npm install -g @luquimbo/bi-superpowers
 super install
 ```
 
-The shared v4.0.0 contract is:
+The shared v4.1.x contract is:
 - **4 skills** — `bi-start` (session opener), `project-kickoff`, `pbi-connect`, `report-design`
 - **2 MCP servers** — `powerbi-modeling-mcp`, `microsoft-learn`
 
 Agent-specific behavior:
-- **Claude Code** — `super kickoff` can also generate a project-local plugin with slash commands: `/project-kickoff`, `/pbi-connect`, `/report-design`
+- **Claude Code** — `super kickoff` can also generate a project-local plugin with slash commands: `/bi-start`, `/project-kickoff`, `/pbi-connect`, `/report-design`
 - **GitHub Copilot** — uses the installed skills + MCP config via natural-language prompts
 - **Codex** — uses the installed skills + MCP config via natural-language prompts
 - **Gemini CLI** — uses the installed skills + MCP config via natural-language prompts
 - **Kilo Code** — uses the installed skills + MCP config via natural-language prompts
 
-`/report-design` has one extra runtime prerequisite on every agent: **Windows + Power BI Desktop + Python 3.10+ + `pipx` + `pbi-cli-tool`**. If that CLI stack is not available yet, start with `project-kickoff` and `pbi-connect`.
+`/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`.
 
 ### Claude Desktop
 
@@ -175,13 +174,14 @@ Los 4 skills quedan disponibles como MCP prompts.
 - **No Laziness**: Fix root causes, avoid temporary patches.
 - **Minimal Impact**: Touch only what is necessary.
 
-## Available Skills (3)
+## Available Skills (4)
 
 | 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 `pbi-cli-tool` | "report design", "crear reportes" |
+| `/report-design` | Generate PBIR report pages via bundled Node scripts | "report design", "crear reportes" |
 
 ## MCP Servers (2)
 
@@ -209,7 +209,7 @@ BI Agent Superpowers generates a native Claude Code plugin from a single source
 project/
 ├── .claude-plugin/plugin.json   # Plugin manifest
 ├── .mcp.json                    # Power BI Modeling + Microsoft Learn MCPs
-├── commands/*.md                # 3 slash commands (pbi-connect, project-kickoff, report-design)
+├── commands/*.md                # 4 slash commands (bi-start, pbi-connect, project-kickoff, report-design)
 ├── skills/*/SKILL.md            # 4 skills (discoverable)
 ├── config.json                  # User preferences
 └── library/ → symlink           # Snippets, templates, themes

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [4.1.0] — 2026-04-21
 
+> **First stable release — the de-facto 1.0 of `@luquimbo/bi-superpowers`.**
+>
+> Versions 2.x, 3.x, and 4.0.0 were iteration cycles while the plugin's
+> scope, architecture, and install UX were settling. The v4.1.0 line is
+> the first release the author considers ready for real use: the 4
+> skills + 2 MCPs are stable, both install paths (Claude Code marketplace
+> and npm + `super install`) are documented, the cross-agent autoupdate
+> loop is working end-to-end, and the Opus 4.7 1M code review report
+> with all its blockers + high findings is resolved in the tree. Pre-4.1
+> versions on npm should be treated as pre-release history.
+>
+> (The version number stays on the 4.x line because npm is strictly
+> monotonic and the numeric identity would be confusing to rewrite; the
+> README, CHANGELOG, and this note carry the "first stable" framing.)
+
 ### Added
 
 - **New skill: `/bi-start`** — session-opener that every new chat conversation can

package/README.md

@@ -7,7 +7,9 @@
 
 Toolkit open-source para trabajar con **Power BI Desktop** desde Claude Code, GitHub Copilot, Codex, Gemini CLI y Kilo Code.
 
-> **Estado:** `v4.0.x`. Incluye 4 skills (`/bi-start` + 3 especialistas) y 2 MCP servers oficiales de Microsoft. `/report-design` genera PBIR via scripts Node propios (no depende de `pbi-cli-tool` para authoring — Windows + Power BI Desktop sí sigue siendo requisito runtime).
+> **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á.
 
 ---
 
@@ -26,7 +28,7 @@ Dentro de Claude Code, ejecutá:
 
 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.
 
-Si también querés el plugin local de proyecto (con slash commands `/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).
+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).
 
 ### 👉 Otros agentes — Copilot, Codex, Gemini CLI, Kilo Code (o multi-agente)
 
@@ -64,7 +66,7 @@ Reiniciá tu agente AI y ya tenés bi-superpowers funcionando.
 
 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.
 
-`report-design` requiere **Windows + Power BI Desktop** (standalone, no la versión de Microsoft Store). Los scripts Node son portables, pero el ciclo de verificación (relaunch, render) necesita Desktop. `pbi-cli-tool` es opcional y solo se usa para introspección del modelo (preferido: Microsoft Modeling MCP cuando está disponible).
+`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.
 
 ### 2 MCP Servers (oficiales de Microsoft)
 
@@ -116,23 +118,28 @@ Dentro de Claude Code:
 
 Eso trae la última versión publicada en el marketplace. Cero interacción con npm.
 
-### npm (todos los otros agentes)
+### npm / CLI-managed installs
 
 ```bash
 # 1. Actualizá la CLI a la última versión
 super upgrade
 
-# 2. Refrescá skills + MCPs en tus agentes (no se hace automático, es un paso separado)
+# 2. Si instalaste skills en el perfil del agente, propagá la nueva versión
 super install --yes
+
+# 3. Si además generaste un plugin local con super kickoff, regeneralo en ese repo
+super recharge
 ```
 
-`super upgrade` reinstala el paquete global y al final te imprime un recordatorio con este segundo paso. No lo hace automático a propósito: los usuarios que solo quieren actualizar la CLI (p.ej. desarrollando local) pueden saltarlo.
+`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.
 
 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
 ```
 
 ---
@@ -160,7 +167,7 @@ Si ya instalaste los MCPs por alguno de estos caminos, no necesitás correr `sup
 
 - **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 **opcionales** — solo hacen falta para introspección del modelo via XMLA cuando el Microsoft Modeling MCP no está disponible. Para authoring de visuales, `report-design` usa scripts Node propios y no depende de esa cadena.
+- **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
 
 ---
@@ -172,7 +179,7 @@ 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 a la última versión + imprime recordatorio de `super install`
+super upgrade          # Actualizá la CLI + recordatorio de /plugin update, super install o super recharge
 super help             # Ayuda completa
 ```
 

package/bin/cli.js

@@ -49,7 +49,7 @@ try {
       message:
         'Update available {currentVersion} → {latestVersion}\n' +
         'Run {updateCommand} to update,\n' +
-        'then `super install --yes` to propagate the new skills.',
+        'then refresh your install path (`/plugin update bi-superpowers`, `super install --yes`, or run `super recharge` inside each repo where you used `super kickoff`).',
     });
 } catch (_) {
   // update-notifier not available during npm install phase, or network
@@ -619,9 +619,10 @@ function getUpgradeCommand(userAgent) {
 /**
  * `super upgrade` — reinstall the package at the latest version.
  *
- * After the reinstall, prints a "next steps" block with both update paths
- * (Claude Code `/plugin update` vs npm-based `super install --yes`) so
- * users know how to propagate the new skills into their agents. We
+ * After the reinstall, prints a "next steps" block with the refresh paths
+ * for marketplace installs, user-profile installs, and project-local
+ * plugins generated by `super kickoff`, so users know how to propagate
+ * the new skills into their agents. We
  * intentionally don't auto-chain into `super install`:
  *   - Claude Code users who installed via the plugin marketplace refresh
  *     from inside Claude Code (`/plugin update bi-superpowers`), they don't
@@ -648,6 +649,24 @@ function resetUpdateCheckStateAfterUpgrade(homeDir) {
   }
 }
 
+function getUpgradeRefreshSteps() {
+  return [
+    {
+      label: 'Claude Code (installed via marketplace):',
+      command: '/plugin update bi-superpowers',
+    },
+    {
+      label: 'Skills installed in your user profile (npm + super install):',
+      command: 'super install --yes',
+    },
+    {
+      label:
+        'Project-local Claude Code plugin (run inside each repo where you used super kickoff):',
+      command: 'super recharge',
+    },
+  ];
+}
+
 function updatePackage() {
   console.log(`Updating ${PACKAGE_NAME}...\n`);
 
@@ -662,12 +681,11 @@ function updatePackage() {
     resetUpdateCheckStateAfterUpgrade(require('os').homedir());
 
     console.log('\nNext step — refresh the skills + MCPs in your agents:\n');
-    console.log('  Claude Code (installed via marketplace):');
-    console.log('    /plugin update bi-superpowers');
-    console.log('');
-    console.log('  Any other install path (npm + super install):');
-    console.log('    super install --yes');
-    console.log('');
+    for (const step of getUpgradeRefreshSteps()) {
+      console.log(`  ${step.label}`);
+      console.log(`    ${step.command}`);
+      console.log('');
+    }
     console.log(
       'If you only wanted the CLI updated (e.g. developing locally), you can skip the above.'
     );
@@ -803,6 +821,7 @@ module.exports = {
   loadToolConfig,
   saveToolConfig,
   getUpgradeCommand,
+  getUpgradeRefreshSteps,
   resetUpdateCheckStateAfterUpgrade,
   AI_TOOLS,
   SKILLS_DIR,

package/bin/commands/update-check.js

@@ -44,6 +44,10 @@ const https = require('https');
 const PACKAGE_NAME = '@luquimbo/bi-superpowers';
 const CACHE_TTL_MS = 1000 * 60 * 60 * 24; // 24 hours
 const HTTPS_TIMEOUT_MS = 5000;
+// Rewritten at generation time when this helper is copied into
+// `skills/<name>/scripts/update-check.js`. In the canonical source under
+// `bin/commands/`, it stays null and we fall back to package.json.
+const BUNDLED_INSTALLED_VERSION = null;
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -60,6 +64,7 @@ function parseArgs(argv) {
     help: false,
     stateDir: null,
     packageName: null,
+    installedVersion: null,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -71,6 +76,7 @@ function parseArgs(argv) {
     else if (a === '--reset') out.reset = true;
     else if (a === '--state-dir') out.stateDir = argv[++i];
     else if (a === '--package-name') out.packageName = argv[++i];
+    else if (a === '--installed-version') out.installedVersion = argv[++i];
     else if (a === '-h' || a === '--help') out.help = true;
     else {
       process.stderr.write(`update-check: unknown flag: ${a}\n`);
@@ -96,6 +102,7 @@ function help() {
       '  --reset                 Delete the state file (used after a successful upgrade)',
       '  --state-dir <path>      Override ~/.bi-superpowers/ (tests)',
       '  --package-name <name>   Override the package name (tests)',
+      '  --installed-version <v> Override the installed version (generated skill bundles)',
       '  -h, --help              Show this help',
       '',
     ].join('\n')
@@ -257,7 +264,13 @@ function fetchLatestVersion(packageName) {
 // Installed version — read from our own package.json
 // ---------------------------------------------------------------------------
 
-function readInstalledVersion() {
+function readInstalledVersion(explicitVersion = null) {
+  if (explicitVersion) {
+    return String(explicitVersion);
+  }
+  if (BUNDLED_INSTALLED_VERSION) {
+    return String(BUNDLED_INSTALLED_VERSION);
+  }
   try {
     return require(path.join(__dirname, '..', '..', 'package.json')).version;
   } catch (_) {
@@ -318,7 +331,7 @@ async function main() {
     return;
   }
 
-  const installed = readInstalledVersion();
+  const installed = readInstalledVersion(args.installedVersion);
   if (!installed) {
     // Installed version undetermined — nothing useful to report.
     return;
@@ -376,6 +389,7 @@ module.exports = {
   writeState,
   resetState,
   fetchLatestVersion,
+  readInstalledVersion,
   CACHE_TTL_MS,
   PACKAGE_NAME,
 };

package/bin/lib/generators/claude-plugin.js

@@ -150,7 +150,7 @@ node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if
 
 - Empty output or \`UPTODATE\` — proceed with the skill silently. No message.
 - \`UPDATE_AVAILABLE <installed> <latest>\` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con \`super upgrade\` (o \`/plugin update bi-superpowers\` en Claude Code) cuando te venga bien."
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con \`super upgrade\` (o \`/plugin update bi-superpowers\` en Claude Code) cuando te venga bien. Si estás usando un plugin local generado con \`super kickoff\`, después corré \`super recharge\` en ese repo."
 
   Then continue with the skill below.
 - \`SNOOZED <iso>\` — proceed silently.
@@ -162,6 +162,16 @@ If the command fails (missing binary, permissions, offline), ignore the error an
 
 `;
 
+function shouldIncludeUpdateCheckPreamble(skill, options = {}) {
+  if (options.skipPreamble) {
+    return false;
+  }
+  // bi-start owns the interactive update flow itself in PHASE 0. If we also
+  // prepend the generic passive preamble, the session-opener gets two
+  // competing update contracts in the same skill.
+  return skill.name !== 'bi-start';
+}
+
 /**
  * Build command markdown with Claude Code frontmatter.
  *
@@ -174,7 +184,7 @@ If the command fails (missing binary, permissions, offline), ignore the error an
 function buildCommandMarkdown(skill, libraryPrefix, options = {}) {
   const description = getSkillPurpose(skill.name);
   const content = rewriteLibraryReferences(skill.content, libraryPrefix);
-  const preamble = options.skipPreamble ? '' : UPDATE_CHECK_PREAMBLE;
+  const preamble = shouldIncludeUpdateCheckPreamble(skill, options) ? UPDATE_CHECK_PREAMBLE : '';
 
   return `---
 description: ${toFrontmatterValue(description)}
@@ -197,7 +207,7 @@ ${preamble}${content}`;
  */
 function buildSkillMarkdown(skill, version, libraryPrefix, options = {}) {
   const content = rewriteLibraryReferences(skill.content, libraryPrefix);
-  const preamble = options.skipPreamble ? '' : UPDATE_CHECK_PREAMBLE;
+  const preamble = shouldIncludeUpdateCheckPreamble(skill, options) ? UPDATE_CHECK_PREAMBLE : '';
 
   return `---
 name: ${toFrontmatterValue(skill.name)}
@@ -221,14 +231,22 @@ ${preamble}${content}`;
  * @param {string} targetDir - plugin target root (contains skills/<name>/)
  * @param {Object[]} skills - Skills to wire the script into
  */
-function copyUpdateCheckScript(packageDir, targetDir, skills) {
+function copyUpdateCheckScript(packageDir, targetDir, skills, version = null) {
   if (!packageDir) return;
   const src = path.join(packageDir, 'bin', 'commands', 'update-check.js');
   if (!fs.existsSync(src)) return;
+  const sourceContent = fs.readFileSync(src, 'utf8');
+  let bundledContent = sourceContent;
+  if (version) {
+    bundledContent = sourceContent.replace(
+      'const BUNDLED_INSTALLED_VERSION = null;',
+      `const BUNDLED_INSTALLED_VERSION = ${JSON.stringify(version)};`
+    );
+  }
   for (const skill of skills) {
     const scriptsDir = path.join(targetDir, 'skills', skill.name, 'scripts');
     ensureDirectory(scriptsDir);
-    fs.copyFileSync(src, path.join(scriptsDir, 'update-check.js'));
+    fs.writeFileSync(path.join(scriptsDir, 'update-check.js'), bundledContent);
   }
 }
 
@@ -453,7 +471,7 @@ async function generate(targetDir, skills, options = {}) {
   // Ship the update-check helper alongside every skill so the SKILL.md
   // preamble can invoke it via `{skillBundleDir}/scripts/update-check.js`
   // regardless of install path.
-  copyUpdateCheckScript(options.packageDir, targetDir, skills);
+  copyUpdateCheckScript(options.packageDir, targetDir, skills, version);
 
   console.log('  ✓ Created Claude Code plugin manifest');
   console.log('  ✓ Created .mcp.json with official Microsoft MCP servers');

package/commands/bi-start.md

@@ -4,27 +4,6 @@ description: "Session opener — environment snapshot, update check, and routing
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/bi-start.md instead. -->
 
-<!-- bi-superpowers update-check preamble (auto-generated, do not edit) -->
-## ⬆ Update check
-
-Before handling the user's request below, run this command **once per conversation** and interpret the output:
-
-```bash
-node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if-snoozed
-```
-
-- Empty output or `UPTODATE` — proceed with the skill silently. No message.
-- `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
-
-  Then continue with the skill below.
-- `SNOOZED <iso>` — proceed silently.
-
-If the command fails (missing binary, permissions, offline), ignore the error and proceed with the skill. The update check must never block the user's request.
-
----
-<!-- /bi-superpowers update-check preamble -->
-
 # BI Start Skill
 
 ## Trigger
@@ -48,7 +27,7 @@ You are the session-opener, **not** the project-opener. If the user's intent is
 ## MANDATORY RULES
 
 1. **ONE QUESTION AT A TIME.** Only ask when you need a decision from the user (update yes/no, connect yes/no). Never stack multiple questions.
-2. **INFORMATIVE MENU — DON'T FORCE A CHOICE.** Show the 3 skills as a table with 1-line descriptions. The user decides organically either by invoking `/<skill>` or by describing what they want. Do NOT say "pick 1, 2, or 3" — that's quiz-style and annoying for returning users.
+2. **INFORMATIVE MENU — DON'T FORCE A CHOICE.** You are already inside `/bi-start`. Show the **3 specialist skills** as a table with 1-line descriptions. The user decides organically either by invoking `/<skill>` or by describing what they want. Do NOT say "pick 1, 2, or 3" — that's quiz-style and annoying for returning users.
 3. **PROACTIVE ON UPDATE + CONNECT.** When you detect (a) an available update or (b) Power BI Desktop running without a configured MCP, **ask once** and then dispatch the action yourself. Don't force the user to remember the exact command.
 4. **SAFE DEFAULTS ON SAY-NOTHING.** If the user greets you and then goes silent, show the menu and stop. Don't auto-dispatch anything without an explicit "sí" / "yes".
 5. **OS-AWARE, NOT OS-GATING.** Works on any OS. Mark Windows-only skills clearly. On macOS/Linux, `/project-kickoff` still has partial value (writes `AGENTS.md` and stops); mention that honestly instead of refusing.
@@ -76,7 +55,7 @@ Interpret the single-line output:
     ```bash
     super upgrade
     ```
-    After it finishes, remind: _"Corré `super install --yes` cuando puedas para propagar las skills nuevas a tus agentes."_
+    After it finishes, remind: _"Si instalaste skills en el perfil del agente, corré `super install --yes`. Si además usás un plugin local generado con `super kickoff`, corré `super recharge` dentro de ese repo."_
 
   On `no` — respect it, continue to PHASE 1 silently. The update-state.json already tracks the user's snooze per `update-check.js` semantics.
 
@@ -131,10 +110,10 @@ Keep it 3-4 lines. The point is situational awareness, not a status page.
 
 ## PHASE 2: Skills menu (informativo)
 
-Show the 3 skills as a table. Plain, no prompt. Do NOT number them or ask "which one?".
+Remind the user that `/bi-start` is the session opener, then show the **3 specialist skills** as a table. Plain, no prompt. Do NOT number them or ask "which one?".
 
 ```
-Skills disponibles:
+Ya estás en `/bi-start` (session opener). Los 3 specialist skills disponibles son:
 
   /project-kickoff   Arrancar un proyecto BI nuevo (crea AGENTS.md, plantea modelo)      · Win / Mac / Linux (parcial fuera de Win)
   /pbi-connect       Conectar el agente a Power BI Desktop vía MCP                       · Windows
@@ -190,7 +169,7 @@ On macOS/Linux, skip Case B and Case C — mention once:
 
 If you got here without dispatching, close with:
 
-> _"Listo — invocá el skill que necesites, o pedime ayuda específica sobre cualquiera de los 3. Si abrís una sesión nueva mañana, `/bi-start` te orienta de nuevo."_
+> _"Listo — invocá el specialist skill que necesites, o pedime ayuda específica sobre cualquiera de esos 3. Si abrís una sesión nueva mañana, `/bi-start` te orienta de nuevo."_
 
 Stop. Don't hover. The user will tell you what they want next.
 
@@ -201,7 +180,7 @@ Stop. Don't hover. The user will tell you what they want next.
 - **Project analysis or setup**: that's `/project-kickoff`. If the user says "analizar mi proyecto", "armar el modelo base", "arrancar uno nuevo desde cero", delegate.
 - **MCP wiring details**: that's `/pbi-connect`. bi-start just offers to dispatch it; the actual configuration work is in that skill.
 - **Report authoring**: that's `/report-design`. Same pattern.
-- **Running the update**: bi-start offers + dispatches `super upgrade`; the actual npm install + subsequent `super install --yes` chain is owned by `/bin/cli.js`.
+- **Running the update**: bi-start offers + dispatches `super upgrade`; the actual refresh path after eso (`/plugin update bi-superpowers`, `super install --yes`, o `super recharge`) is owned by `/bin/cli.js`.
 
 ## Related Skills
 

package/commands/pbi-connect.md

@@ -15,7 +15,7 @@ node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if
 
 - Empty output or `UPTODATE` — proceed with the skill silently. No message.
 - `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
 
   Then continue with the skill below.
 - `SNOOZED <iso>` — proceed silently.

package/commands/project-kickoff.md

@@ -15,7 +15,7 @@ node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if
 
 - Empty output or `UPTODATE` — proceed with the skill silently. No message.
 - `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
 
   Then continue with the skill below.
 - `SNOOZED <iso>` — proceed silently.
@@ -592,11 +592,11 @@ Once the model has at least 1 fact, 1 dim, and 3 measures in place, propose movi
 
 El siguiente paso lógico es armar los 3 reportes con `/report-design`. Ese skill va a:
   1. Usar el dominio que ya definimos ({domain})
-  2. Inspeccionar tu modelo vía el pbi CLI para las medidas/dimensiones exactas
-  3. Generar 3 páginas con visuales vía CLI (card, line, bar, matrix)
+  2. Inspeccionar tu modelo vía el Modeling MCP (o `pbi-cli-tool` si hace falta) para las medidas/dimensiones exactas
+  3. Generar 3 páginas con scripts Node + comandos `pbi report` (card, line, bar, matrix)
   4. Cerrar y reabrir PBI Desktop para que renderice
 
-Requisito: necesitás pbi-cli-tool instalado (si no lo tenés el skill te guía).
+Requisito: necesitás Windows + Power BI Desktop + Python 3.10+ + `pipx` + `pbi-cli-tool` (si te falta algo, el skill te guía).
 
 ¿Arrancamos con /report-design, o preferís agregar más medidas al modelo primero?
 ```
@@ -608,7 +608,7 @@ If the user opts for reports, load `/report-design` and let it run. If they want
 ## What this skill does NOT do
 
 - **No scoring / benchmarking** of an existing model. For that, the user can ask "audit this model" separately.
-- **Report authoring** is delegated to `/report-design` which orchestrates the `pbi-cli-tool` CLI — don't write `.Report/` files from here.
+- **Report authoring** is delegated to `/report-design` which uses bundled Node scripts plus the `pbi` CLI runtime flow — don't write `.Report/` files from here.
 
 ---
 

package/commands/report-design.md

@@ -15,7 +15,7 @@ node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if
 
 - Empty output or `UPTODATE` — proceed with the skill silently. No message.
 - `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
 
   Then continue with the skill below.
 - `SNOOZED <iso>` — proceed silently.
@@ -36,13 +36,13 @@ Activate this skill when the user mentions:
 - Explicit invocation: `/report-design`
 
 ## Identity
-You are **BI Report Architect**, an orchestrator that turns a finished semantic model into a Power BI report. You author PBIR via **bundled Node scripts** — not via `pbi-cli-tool` upstream:
+You are **BI Report Architect**, an orchestrator that turns a finished semantic model into a Power BI report. You author the PBIR visual/theme layer via **bundled Node scripts** — not via the old `pbi visual` / `pbi report set-theme` path:
 
 - `scripts/create-visual.js` — creates any of the 28 native PBI visualTypes with a canonical `visual.json` shape (allowlist-driven, validated). **This replaces `pbi visual add` + `pbi visual bind`.**
 - `scripts/apply-theme.js` — registers a custom theme with the canonical `report.json` shape. **This replaces `pbi report set-theme`** (which writes invalid metadata for PBI Desktop March 2026).
 - `scripts/validate-pbir.js` — allowlist + bind-role validator. **Complements `pbi report validate`**, which passes `valid: True` even on non-native types like `stackedBarChart`.
 
-The `pbi-cli-tool` (MIT, by MinaSaad1) is kept around for **one purpose only**: model introspection via XMLA (`pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`). Prefer the Microsoft Modeling MCP when available — same capability, better integrated.
+The `pbi-cli-tool` (MIT, by MinaSaad1) is still required today for **three parts of the flow**: model introspection via XMLA (`pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`), report page management (`pbi report add-page`, `pbi report list-pages`), and schema validation (`pbi report validate`). Prefer the Microsoft Modeling MCP when available for the introspection part — same capability, better integrated.
 
 Full rationale: `references/native-visuals.md` → section "Lo que este skill YA no hace via CLI".
 
@@ -368,8 +368,8 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 **References** (`references/`):
 - `native-visuals.md` — **canonical reference**: 28 native visualTypes, their roles, shape canonical, copy-paste examples (read this before authoring)
 - `pbi-desktop-installation.md` — why the standalone installer build is required (not Microsoft Store), install + uninstall steps
-- `cli-setup.md` — how to install Python + pipx + pbi-cli-tool + pywin32 (only needed for model introspection via XMLA; scripts don't require it)
-- `cli-commands.md` — cheatsheet of the `pbi` commands still used by this skill (mostly `pbi connect` / `pbi measure list` for model introspection; authoring commands are superseded by the Node scripts)
+- `cli-setup.md` — how to install Python + pipx + pbi-cli-tool + pywin32 (required because this skill still uses `pbi` for connect, page operations, and validation)
+- `cli-commands.md` — cheatsheet of the `pbi` commands still used by this skill (`pbi connect`, `pbi measure list`, `pbi report add-page`, `pbi report list-pages`, `pbi report validate`)
 - `textbox.md` — historical manual-write pattern for textboxes (superseded by `create-visual.js --type textbox`; kept for reference)
 - `slicer.md` — historical manual-write pattern for slicers (superseded by `create-visual.js --type slicer --slicer-mode ...`; kept for reference)
 - `close-write-open-pattern.md` — why and how to handle the Desktop restart cycle
@@ -383,7 +383,7 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 - `layouts/generic.md` — fallback 3-page composition
 
 **Scripts** (`scripts/`):
-- `ensure-pbi-cli.sh` — idempotent installer for the pbi-cli-tool (only needed for model introspection via XMLA)
+- `ensure-pbi-cli.sh` — idempotent installer for the pbi-cli-tool (required for this skill's current runtime flow)
 - `apply-theme.js` — registers a custom PBIR theme with the canonical shape Desktop accepts (replaces the broken `pbi report set-theme` in PBI Desktop March 2026)
 - `create-visual.js` — creates any of the 28 native PBI visualTypes with a canonical `visual.json` shape (replaces `pbi visual add` + `pbi visual bind`; enforces allowlist)
 - `validate-pbir.js` — allowlist + role-checks validator that catches non-native visualTypes and missing/invalid bindings (complements `pbi report validate`)
@@ -400,4 +400,4 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 
 ## Credit
 
-This skill orchestrates the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI by MinaSaad1 (MIT License). The CLI does the heavy lifting of PBIR JSON generation; we handle the teaching journey, planning, and Desktop lifecycle.
+This skill integrates with the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI by MinaSaad1 (MIT License) for model introspection, page operations, and schema validation. Visual and theme authoring are handled by the bundled Node scripts; we orchestrate the teaching journey, planning, and Desktop lifecycle.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@luquimbo/bi-superpowers",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "description": "Open-source Power BI Desktop toolkit for Claude Code, GitHub Copilot, Codex, Gemini CLI, and Kilo Code. Ships 4 skills and 2 official Microsoft MCP servers.",
   "main": "bin/cli.js",
   "bin": {
-    "bi-superpowers": "bin/cli.js"
+    "bi-superpowers": "bin/cli.js",
+    "super": "bin/cli.js"
   },
   "scripts": {
     "build:plugin": "node bin/build-plugin.js",

package/skills/bi-start/SKILL.md

@@ -1,32 +1,11 @@
 ---
 name: "bi-start"
 description: "Use when the user asks about BI Start Skill, especially phrases like \"bi-start\", \"bi start\", \"/bi-start\", \"empezar\", \"comenzar\", \"arranco\"."
-version: "4.1.0"
+version: "4.1.2"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/bi-start.md instead. -->
 
-<!-- bi-superpowers update-check preamble (auto-generated, do not edit) -->
-## ⬆ Update check
-
-Before handling the user's request below, run this command **once per conversation** and interpret the output:
-
-```bash
-node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if-snoozed
-```
-
-- Empty output or `UPTODATE` — proceed with the skill silently. No message.
-- `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
-
-  Then continue with the skill below.
-- `SNOOZED <iso>` — proceed silently.
-
-If the command fails (missing binary, permissions, offline), ignore the error and proceed with the skill. The update check must never block the user's request.
-
----
-<!-- /bi-superpowers update-check preamble -->
-
 # BI Start Skill
 
 ## Trigger
@@ -50,7 +29,7 @@ You are the session-opener, **not** the project-opener. If the user's intent is
 ## MANDATORY RULES
 
 1. **ONE QUESTION AT A TIME.** Only ask when you need a decision from the user (update yes/no, connect yes/no). Never stack multiple questions.
-2. **INFORMATIVE MENU — DON'T FORCE A CHOICE.** Show the 3 skills as a table with 1-line descriptions. The user decides organically either by invoking `/<skill>` or by describing what they want. Do NOT say "pick 1, 2, or 3" — that's quiz-style and annoying for returning users.
+2. **INFORMATIVE MENU — DON'T FORCE A CHOICE.** You are already inside `/bi-start`. Show the **3 specialist skills** as a table with 1-line descriptions. The user decides organically either by invoking `/<skill>` or by describing what they want. Do NOT say "pick 1, 2, or 3" — that's quiz-style and annoying for returning users.
 3. **PROACTIVE ON UPDATE + CONNECT.** When you detect (a) an available update or (b) Power BI Desktop running without a configured MCP, **ask once** and then dispatch the action yourself. Don't force the user to remember the exact command.
 4. **SAFE DEFAULTS ON SAY-NOTHING.** If the user greets you and then goes silent, show the menu and stop. Don't auto-dispatch anything without an explicit "sí" / "yes".
 5. **OS-AWARE, NOT OS-GATING.** Works on any OS. Mark Windows-only skills clearly. On macOS/Linux, `/project-kickoff` still has partial value (writes `AGENTS.md` and stops); mention that honestly instead of refusing.
@@ -78,7 +57,7 @@ Interpret the single-line output:
     ```bash
     super upgrade
     ```
-    After it finishes, remind: _"Corré `super install --yes` cuando puedas para propagar las skills nuevas a tus agentes."_
+    After it finishes, remind: _"Si instalaste skills en el perfil del agente, corré `super install --yes`. Si además usás un plugin local generado con `super kickoff`, corré `super recharge` dentro de ese repo."_
 
   On `no` — respect it, continue to PHASE 1 silently. The update-state.json already tracks the user's snooze per `update-check.js` semantics.
 
@@ -133,10 +112,10 @@ Keep it 3-4 lines. The point is situational awareness, not a status page.
 
 ## PHASE 2: Skills menu (informativo)
 
-Show the 3 skills as a table. Plain, no prompt. Do NOT number them or ask "which one?".
+Remind the user that `/bi-start` is the session opener, then show the **3 specialist skills** as a table. Plain, no prompt. Do NOT number them or ask "which one?".
 
 ```
-Skills disponibles:
+Ya estás en `/bi-start` (session opener). Los 3 specialist skills disponibles son:
 
   /project-kickoff   Arrancar un proyecto BI nuevo (crea AGENTS.md, plantea modelo)      · Win / Mac / Linux (parcial fuera de Win)
   /pbi-connect       Conectar el agente a Power BI Desktop vía MCP                       · Windows
@@ -192,7 +171,7 @@ On macOS/Linux, skip Case B and Case C — mention once:
 
 If you got here without dispatching, close with:
 
-> _"Listo — invocá el skill que necesites, o pedime ayuda específica sobre cualquiera de los 3. Si abrís una sesión nueva mañana, `/bi-start` te orienta de nuevo."_
+> _"Listo — invocá el specialist skill que necesites, o pedime ayuda específica sobre cualquiera de esos 3. Si abrís una sesión nueva mañana, `/bi-start` te orienta de nuevo."_
 
 Stop. Don't hover. The user will tell you what they want next.
 
@@ -203,7 +182,7 @@ Stop. Don't hover. The user will tell you what they want next.
 - **Project analysis or setup**: that's `/project-kickoff`. If the user says "analizar mi proyecto", "armar el modelo base", "arrancar uno nuevo desde cero", delegate.
 - **MCP wiring details**: that's `/pbi-connect`. bi-start just offers to dispatch it; the actual configuration work is in that skill.
 - **Report authoring**: that's `/report-design`. Same pattern.
-- **Running the update**: bi-start offers + dispatches `super upgrade`; the actual npm install + subsequent `super install --yes` chain is owned by `/bin/cli.js`.
+- **Running the update**: bi-start offers + dispatches `super upgrade`; the actual refresh path after eso (`/plugin update bi-superpowers`, `super install --yes`, o `super recharge`) is owned by `/bin/cli.js`.
 
 ## Related Skills
 

package/skills/bi-start/scripts/update-check.js

@@ -44,6 +44,10 @@ const https = require('https');
 const PACKAGE_NAME = '@luquimbo/bi-superpowers';
 const CACHE_TTL_MS = 1000 * 60 * 60 * 24; // 24 hours
 const HTTPS_TIMEOUT_MS = 5000;
+// Rewritten at generation time when this helper is copied into
+// `skills/<name>/scripts/update-check.js`. In the canonical source under
+// `bin/commands/`, it stays null and we fall back to package.json.
+const BUNDLED_INSTALLED_VERSION = "4.1.2";
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -60,6 +64,7 @@ function parseArgs(argv) {
     help: false,
     stateDir: null,
     packageName: null,
+    installedVersion: null,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -71,6 +76,7 @@ function parseArgs(argv) {
     else if (a === '--reset') out.reset = true;
     else if (a === '--state-dir') out.stateDir = argv[++i];
     else if (a === '--package-name') out.packageName = argv[++i];
+    else if (a === '--installed-version') out.installedVersion = argv[++i];
     else if (a === '-h' || a === '--help') out.help = true;
     else {
       process.stderr.write(`update-check: unknown flag: ${a}\n`);
@@ -96,6 +102,7 @@ function help() {
       '  --reset                 Delete the state file (used after a successful upgrade)',
       '  --state-dir <path>      Override ~/.bi-superpowers/ (tests)',
       '  --package-name <name>   Override the package name (tests)',
+      '  --installed-version <v> Override the installed version (generated skill bundles)',
       '  -h, --help              Show this help',
       '',
     ].join('\n')
@@ -257,7 +264,13 @@ function fetchLatestVersion(packageName) {
 // Installed version — read from our own package.json
 // ---------------------------------------------------------------------------
 
-function readInstalledVersion() {
+function readInstalledVersion(explicitVersion = null) {
+  if (explicitVersion) {
+    return String(explicitVersion);
+  }
+  if (BUNDLED_INSTALLED_VERSION) {
+    return String(BUNDLED_INSTALLED_VERSION);
+  }
   try {
     return require(path.join(__dirname, '..', '..', 'package.json')).version;
   } catch (_) {
@@ -318,7 +331,7 @@ async function main() {
     return;
   }
 
-  const installed = readInstalledVersion();
+  const installed = readInstalledVersion(args.installedVersion);
   if (!installed) {
     // Installed version undetermined — nothing useful to report.
     return;
@@ -376,6 +389,7 @@ module.exports = {
   writeState,
   resetState,
   fetchLatestVersion,
+  readInstalledVersion,
   CACHE_TTL_MS,
   PACKAGE_NAME,
 };

package/skills/pbi-connect/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "pbi-connect"
 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\"."
-version: "4.1.0"
+version: "4.1.2"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/pbi-connect.md instead. -->
@@ -17,7 +17,7 @@ node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if
 
 - Empty output or `UPTODATE` — proceed with the skill silently. No message.
 - `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
 
   Then continue with the skill below.
 - `SNOOZED <iso>` — proceed silently.

package/skills/pbi-connect/scripts/update-check.js

@@ -44,6 +44,10 @@ const https = require('https');
 const PACKAGE_NAME = '@luquimbo/bi-superpowers';
 const CACHE_TTL_MS = 1000 * 60 * 60 * 24; // 24 hours
 const HTTPS_TIMEOUT_MS = 5000;
+// Rewritten at generation time when this helper is copied into
+// `skills/<name>/scripts/update-check.js`. In the canonical source under
+// `bin/commands/`, it stays null and we fall back to package.json.
+const BUNDLED_INSTALLED_VERSION = "4.1.2";
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -60,6 +64,7 @@ function parseArgs(argv) {
     help: false,
     stateDir: null,
     packageName: null,
+    installedVersion: null,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -71,6 +76,7 @@ function parseArgs(argv) {
     else if (a === '--reset') out.reset = true;
     else if (a === '--state-dir') out.stateDir = argv[++i];
     else if (a === '--package-name') out.packageName = argv[++i];
+    else if (a === '--installed-version') out.installedVersion = argv[++i];
     else if (a === '-h' || a === '--help') out.help = true;
     else {
       process.stderr.write(`update-check: unknown flag: ${a}\n`);
@@ -96,6 +102,7 @@ function help() {
       '  --reset                 Delete the state file (used after a successful upgrade)',
       '  --state-dir <path>      Override ~/.bi-superpowers/ (tests)',
       '  --package-name <name>   Override the package name (tests)',
+      '  --installed-version <v> Override the installed version (generated skill bundles)',
       '  -h, --help              Show this help',
       '',
     ].join('\n')
@@ -257,7 +264,13 @@ function fetchLatestVersion(packageName) {
 // Installed version — read from our own package.json
 // ---------------------------------------------------------------------------
 
-function readInstalledVersion() {
+function readInstalledVersion(explicitVersion = null) {
+  if (explicitVersion) {
+    return String(explicitVersion);
+  }
+  if (BUNDLED_INSTALLED_VERSION) {
+    return String(BUNDLED_INSTALLED_VERSION);
+  }
   try {
     return require(path.join(__dirname, '..', '..', 'package.json')).version;
   } catch (_) {
@@ -318,7 +331,7 @@ async function main() {
     return;
   }
 
-  const installed = readInstalledVersion();
+  const installed = readInstalledVersion(args.installedVersion);
   if (!installed) {
     // Installed version undetermined — nothing useful to report.
     return;
@@ -376,6 +389,7 @@ module.exports = {
   writeState,
   resetState,
   fetchLatestVersion,
+  readInstalledVersion,
   CACHE_TTL_MS,
   PACKAGE_NAME,
 };

package/skills/project-kickoff/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "project-kickoff"
 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\"."
-version: "4.1.0"
+version: "4.1.2"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/project-kickoff.md instead. -->
@@ -17,7 +17,7 @@ node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if
 
 - Empty output or `UPTODATE` — proceed with the skill silently. No message.
 - `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
 
   Then continue with the skill below.
 - `SNOOZED <iso>` — proceed silently.
@@ -594,11 +594,11 @@ Once the model has at least 1 fact, 1 dim, and 3 measures in place, propose movi
 
 El siguiente paso lógico es armar los 3 reportes con `/report-design`. Ese skill va a:
   1. Usar el dominio que ya definimos ({domain})
-  2. Inspeccionar tu modelo vía el pbi CLI para las medidas/dimensiones exactas
-  3. Generar 3 páginas con visuales vía CLI (card, line, bar, matrix)
+  2. Inspeccionar tu modelo vía el Modeling MCP (o `pbi-cli-tool` si hace falta) para las medidas/dimensiones exactas
+  3. Generar 3 páginas con scripts Node + comandos `pbi report` (card, line, bar, matrix)
   4. Cerrar y reabrir PBI Desktop para que renderice
 
-Requisito: necesitás pbi-cli-tool instalado (si no lo tenés el skill te guía).
+Requisito: necesitás Windows + Power BI Desktop + Python 3.10+ + `pipx` + `pbi-cli-tool` (si te falta algo, el skill te guía).
 
 ¿Arrancamos con /report-design, o preferís agregar más medidas al modelo primero?
 ```
@@ -610,7 +610,7 @@ If the user opts for reports, load `/report-design` and let it run. If they want
 ## What this skill does NOT do
 
 - **No scoring / benchmarking** of an existing model. For that, the user can ask "audit this model" separately.
-- **Report authoring** is delegated to `/report-design` which orchestrates the `pbi-cli-tool` CLI — don't write `.Report/` files from here.
+- **Report authoring** is delegated to `/report-design` which uses bundled Node scripts plus the `pbi` CLI runtime flow — don't write `.Report/` files from here.
 
 ---
 

package/skills/project-kickoff/scripts/update-check.js

@@ -44,6 +44,10 @@ const https = require('https');
 const PACKAGE_NAME = '@luquimbo/bi-superpowers';
 const CACHE_TTL_MS = 1000 * 60 * 60 * 24; // 24 hours
 const HTTPS_TIMEOUT_MS = 5000;
+// Rewritten at generation time when this helper is copied into
+// `skills/<name>/scripts/update-check.js`. In the canonical source under
+// `bin/commands/`, it stays null and we fall back to package.json.
+const BUNDLED_INSTALLED_VERSION = "4.1.2";
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -60,6 +64,7 @@ function parseArgs(argv) {
     help: false,
     stateDir: null,
     packageName: null,
+    installedVersion: null,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -71,6 +76,7 @@ function parseArgs(argv) {
     else if (a === '--reset') out.reset = true;
     else if (a === '--state-dir') out.stateDir = argv[++i];
     else if (a === '--package-name') out.packageName = argv[++i];
+    else if (a === '--installed-version') out.installedVersion = argv[++i];
     else if (a === '-h' || a === '--help') out.help = true;
     else {
       process.stderr.write(`update-check: unknown flag: ${a}\n`);
@@ -96,6 +102,7 @@ function help() {
       '  --reset                 Delete the state file (used after a successful upgrade)',
       '  --state-dir <path>      Override ~/.bi-superpowers/ (tests)',
       '  --package-name <name>   Override the package name (tests)',
+      '  --installed-version <v> Override the installed version (generated skill bundles)',
       '  -h, --help              Show this help',
       '',
     ].join('\n')
@@ -257,7 +264,13 @@ function fetchLatestVersion(packageName) {
 // Installed version — read from our own package.json
 // ---------------------------------------------------------------------------
 
-function readInstalledVersion() {
+function readInstalledVersion(explicitVersion = null) {
+  if (explicitVersion) {
+    return String(explicitVersion);
+  }
+  if (BUNDLED_INSTALLED_VERSION) {
+    return String(BUNDLED_INSTALLED_VERSION);
+  }
   try {
     return require(path.join(__dirname, '..', '..', 'package.json')).version;
   } catch (_) {
@@ -318,7 +331,7 @@ async function main() {
     return;
   }
 
-  const installed = readInstalledVersion();
+  const installed = readInstalledVersion(args.installedVersion);
   if (!installed) {
     // Installed version undetermined — nothing useful to report.
     return;
@@ -376,6 +389,7 @@ module.exports = {
   writeState,
   resetState,
   fetchLatestVersion,
+  readInstalledVersion,
   CACHE_TTL_MS,
   PACKAGE_NAME,
 };

package/skills/report-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "report-design"
 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\"."
-version: "4.1.0"
+version: "4.1.2"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/report-design.md instead. -->
@@ -17,7 +17,7 @@ node "{skillBundleDir}/scripts/update-check.js" --silent-if-uptodate --silent-if
 
 - Empty output or `UPTODATE` — proceed with the skill silently. No message.
 - `UPDATE_AVAILABLE <installed> <latest>` — tell the user exactly once this conversation, before diving into the skill:
-  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien."
+  > "Hay **bi-superpowers v{latest}** disponible (estás en v{installed}). Actualizá con `super upgrade` (o `/plugin update bi-superpowers` en Claude Code) cuando te venga bien. Si estás usando un plugin local generado con `super kickoff`, después corré `super recharge` en ese repo."
 
   Then continue with the skill below.
 - `SNOOZED <iso>` — proceed silently.
@@ -38,13 +38,13 @@ Activate this skill when the user mentions:
 - Explicit invocation: `/report-design`
 
 ## Identity
-You are **BI Report Architect**, an orchestrator that turns a finished semantic model into a Power BI report. You author PBIR via **bundled Node scripts** — not via `pbi-cli-tool` upstream:
+You are **BI Report Architect**, an orchestrator that turns a finished semantic model into a Power BI report. You author the PBIR visual/theme layer via **bundled Node scripts** — not via the old `pbi visual` / `pbi report set-theme` path:
 
 - `scripts/create-visual.js` — creates any of the 28 native PBI visualTypes with a canonical `visual.json` shape (allowlist-driven, validated). **This replaces `pbi visual add` + `pbi visual bind`.**
 - `scripts/apply-theme.js` — registers a custom theme with the canonical `report.json` shape. **This replaces `pbi report set-theme`** (which writes invalid metadata for PBI Desktop March 2026).
 - `scripts/validate-pbir.js` — allowlist + bind-role validator. **Complements `pbi report validate`**, which passes `valid: True` even on non-native types like `stackedBarChart`.
 
-The `pbi-cli-tool` (MIT, by MinaSaad1) is kept around for **one purpose only**: model introspection via XMLA (`pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`). Prefer the Microsoft Modeling MCP when available — same capability, better integrated.
+The `pbi-cli-tool` (MIT, by MinaSaad1) is still required today for **three parts of the flow**: model introspection via XMLA (`pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`), report page management (`pbi report add-page`, `pbi report list-pages`), and schema validation (`pbi report validate`). Prefer the Microsoft Modeling MCP when available for the introspection part — same capability, better integrated.
 
 Full rationale: `references/native-visuals.md` → section "Lo que este skill YA no hace via CLI".
 
@@ -370,8 +370,8 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 **References** (`references/`):
 - `native-visuals.md` — **canonical reference**: 28 native visualTypes, their roles, shape canonical, copy-paste examples (read this before authoring)
 - `pbi-desktop-installation.md` — why the standalone installer build is required (not Microsoft Store), install + uninstall steps
-- `cli-setup.md` — how to install Python + pipx + pbi-cli-tool + pywin32 (only needed for model introspection via XMLA; scripts don't require it)
-- `cli-commands.md` — cheatsheet of the `pbi` commands still used by this skill (mostly `pbi connect` / `pbi measure list` for model introspection; authoring commands are superseded by the Node scripts)
+- `cli-setup.md` — how to install Python + pipx + pbi-cli-tool + pywin32 (required because this skill still uses `pbi` for connect, page operations, and validation)
+- `cli-commands.md` — cheatsheet of the `pbi` commands still used by this skill (`pbi connect`, `pbi measure list`, `pbi report add-page`, `pbi report list-pages`, `pbi report validate`)
 - `textbox.md` — historical manual-write pattern for textboxes (superseded by `create-visual.js --type textbox`; kept for reference)
 - `slicer.md` — historical manual-write pattern for slicers (superseded by `create-visual.js --type slicer --slicer-mode ...`; kept for reference)
 - `close-write-open-pattern.md` — why and how to handle the Desktop restart cycle
@@ -385,7 +385,7 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 - `layouts/generic.md` — fallback 3-page composition
 
 **Scripts** (`scripts/`):
-- `ensure-pbi-cli.sh` — idempotent installer for the pbi-cli-tool (only needed for model introspection via XMLA)
+- `ensure-pbi-cli.sh` — idempotent installer for the pbi-cli-tool (required for this skill's current runtime flow)
 - `apply-theme.js` — registers a custom PBIR theme with the canonical shape Desktop accepts (replaces the broken `pbi report set-theme` in PBI Desktop March 2026)
 - `create-visual.js` — creates any of the 28 native PBI visualTypes with a canonical `visual.json` shape (replaces `pbi visual add` + `pbi visual bind`; enforces allowlist)
 - `validate-pbir.js` — allowlist + role-checks validator that catches non-native visualTypes and missing/invalid bindings (complements `pbi report validate`)
@@ -402,4 +402,4 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 
 ## Credit
 
-This skill orchestrates the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI by MinaSaad1 (MIT License). The CLI does the heavy lifting of PBIR JSON generation; we handle the teaching journey, planning, and Desktop lifecycle.
+This skill integrates with the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI by MinaSaad1 (MIT License) for model introspection, page operations, and schema validation. Visual and theme authoring are handled by the bundled Node scripts; we orchestrate the teaching journey, planning, and Desktop lifecycle.

package/skills/report-design/scripts/update-check.js

@@ -44,6 +44,10 @@ const https = require('https');
 const PACKAGE_NAME = '@luquimbo/bi-superpowers';
 const CACHE_TTL_MS = 1000 * 60 * 60 * 24; // 24 hours
 const HTTPS_TIMEOUT_MS = 5000;
+// Rewritten at generation time when this helper is copied into
+// `skills/<name>/scripts/update-check.js`. In the canonical source under
+// `bin/commands/`, it stays null and we fall back to package.json.
+const BUNDLED_INSTALLED_VERSION = "4.1.2";
 
 // ---------------------------------------------------------------------------
 // Argument parsing
@@ -60,6 +64,7 @@ function parseArgs(argv) {
     help: false,
     stateDir: null,
     packageName: null,
+    installedVersion: null,
   };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -71,6 +76,7 @@ function parseArgs(argv) {
     else if (a === '--reset') out.reset = true;
     else if (a === '--state-dir') out.stateDir = argv[++i];
     else if (a === '--package-name') out.packageName = argv[++i];
+    else if (a === '--installed-version') out.installedVersion = argv[++i];
     else if (a === '-h' || a === '--help') out.help = true;
     else {
       process.stderr.write(`update-check: unknown flag: ${a}\n`);
@@ -96,6 +102,7 @@ function help() {
       '  --reset                 Delete the state file (used after a successful upgrade)',
       '  --state-dir <path>      Override ~/.bi-superpowers/ (tests)',
       '  --package-name <name>   Override the package name (tests)',
+      '  --installed-version <v> Override the installed version (generated skill bundles)',
       '  -h, --help              Show this help',
       '',
     ].join('\n')
@@ -257,7 +264,13 @@ function fetchLatestVersion(packageName) {
 // Installed version — read from our own package.json
 // ---------------------------------------------------------------------------
 
-function readInstalledVersion() {
+function readInstalledVersion(explicitVersion = null) {
+  if (explicitVersion) {
+    return String(explicitVersion);
+  }
+  if (BUNDLED_INSTALLED_VERSION) {
+    return String(BUNDLED_INSTALLED_VERSION);
+  }
   try {
     return require(path.join(__dirname, '..', '..', 'package.json')).version;
   } catch (_) {
@@ -318,7 +331,7 @@ async function main() {
     return;
   }
 
-  const installed = readInstalledVersion();
+  const installed = readInstalledVersion(args.installedVersion);
   if (!installed) {
     // Installed version undetermined — nothing useful to report.
     return;
@@ -376,6 +389,7 @@ module.exports = {
   writeState,
   resetState,
   fetchLatestVersion,
+  readInstalledVersion,
   CACHE_TTL_MS,
   PACKAGE_NAME,
 };

package/src/content/skills/bi-start.md

@@ -21,7 +21,7 @@ You are the session-opener, **not** the project-opener. If the user's intent is
 ## MANDATORY RULES
 
 1. **ONE QUESTION AT A TIME.** Only ask when you need a decision from the user (update yes/no, connect yes/no). Never stack multiple questions.
-2. **INFORMATIVE MENU — DON'T FORCE A CHOICE.** Show the 3 skills as a table with 1-line descriptions. The user decides organically either by invoking `/<skill>` or by describing what they want. Do NOT say "pick 1, 2, or 3" — that's quiz-style and annoying for returning users.
+2. **INFORMATIVE MENU — DON'T FORCE A CHOICE.** You are already inside `/bi-start`. Show the **3 specialist skills** as a table with 1-line descriptions. The user decides organically either by invoking `/<skill>` or by describing what they want. Do NOT say "pick 1, 2, or 3" — that's quiz-style and annoying for returning users.
 3. **PROACTIVE ON UPDATE + CONNECT.** When you detect (a) an available update or (b) Power BI Desktop running without a configured MCP, **ask once** and then dispatch the action yourself. Don't force the user to remember the exact command.
 4. **SAFE DEFAULTS ON SAY-NOTHING.** If the user greets you and then goes silent, show the menu and stop. Don't auto-dispatch anything without an explicit "sí" / "yes".
 5. **OS-AWARE, NOT OS-GATING.** Works on any OS. Mark Windows-only skills clearly. On macOS/Linux, `/project-kickoff` still has partial value (writes `AGENTS.md` and stops); mention that honestly instead of refusing.
@@ -49,7 +49,7 @@ Interpret the single-line output:
     ```bash
     super upgrade
     ```
-    After it finishes, remind: _"Corré `super install --yes` cuando puedas para propagar las skills nuevas a tus agentes."_
+    After it finishes, remind: _"Si instalaste skills en el perfil del agente, corré `super install --yes`. Si además usás un plugin local generado con `super kickoff`, corré `super recharge` dentro de ese repo."_
 
   On `no` — respect it, continue to PHASE 1 silently. The update-state.json already tracks the user's snooze per `update-check.js` semantics.
 
@@ -104,10 +104,10 @@ Keep it 3-4 lines. The point is situational awareness, not a status page.
 
 ## PHASE 2: Skills menu (informativo)
 
-Show the 3 skills as a table. Plain, no prompt. Do NOT number them or ask "which one?".
+Remind the user that `/bi-start` is the session opener, then show the **3 specialist skills** as a table. Plain, no prompt. Do NOT number them or ask "which one?".
 
 ```
-Skills disponibles:
+Ya estás en `/bi-start` (session opener). Los 3 specialist skills disponibles son:
 
   /project-kickoff   Arrancar un proyecto BI nuevo (crea AGENTS.md, plantea modelo)      · Win / Mac / Linux (parcial fuera de Win)
   /pbi-connect       Conectar el agente a Power BI Desktop vía MCP                       · Windows
@@ -163,7 +163,7 @@ On macOS/Linux, skip Case B and Case C — mention once:
 
 If you got here without dispatching, close with:
 
-> _"Listo — invocá el skill que necesites, o pedime ayuda específica sobre cualquiera de los 3. Si abrís una sesión nueva mañana, `/bi-start` te orienta de nuevo."_
+> _"Listo — invocá el specialist skill que necesites, o pedime ayuda específica sobre cualquiera de esos 3. Si abrís una sesión nueva mañana, `/bi-start` te orienta de nuevo."_
 
 Stop. Don't hover. The user will tell you what they want next.
 
@@ -174,7 +174,7 @@ Stop. Don't hover. The user will tell you what they want next.
 - **Project analysis or setup**: that's `/project-kickoff`. If the user says "analizar mi proyecto", "armar el modelo base", "arrancar uno nuevo desde cero", delegate.
 - **MCP wiring details**: that's `/pbi-connect`. bi-start just offers to dispatch it; the actual configuration work is in that skill.
 - **Report authoring**: that's `/report-design`. Same pattern.
-- **Running the update**: bi-start offers + dispatches `super upgrade`; the actual npm install + subsequent `super install --yes` chain is owned by `/bin/cli.js`.
+- **Running the update**: bi-start offers + dispatches `super upgrade`; the actual refresh path after eso (`/plugin update bi-superpowers`, `super install --yes`, o `super recharge`) is owned by `/bin/cli.js`.
 
 ## Related Skills
 

package/src/content/skills/project-kickoff.md

@@ -565,11 +565,11 @@ Once the model has at least 1 fact, 1 dim, and 3 measures in place, propose movi
 
 El siguiente paso lógico es armar los 3 reportes con `/report-design`. Ese skill va a:
   1. Usar el dominio que ya definimos ({domain})
-  2. Inspeccionar tu modelo vía el pbi CLI para las medidas/dimensiones exactas
-  3. Generar 3 páginas con visuales vía CLI (card, line, bar, matrix)
+  2. Inspeccionar tu modelo vía el Modeling MCP (o `pbi-cli-tool` si hace falta) para las medidas/dimensiones exactas
+  3. Generar 3 páginas con scripts Node + comandos `pbi report` (card, line, bar, matrix)
   4. Cerrar y reabrir PBI Desktop para que renderice
 
-Requisito: necesitás pbi-cli-tool instalado (si no lo tenés el skill te guía).
+Requisito: necesitás Windows + Power BI Desktop + Python 3.10+ + `pipx` + `pbi-cli-tool` (si te falta algo, el skill te guía).
 
 ¿Arrancamos con /report-design, o preferís agregar más medidas al modelo primero?
 ```
@@ -581,7 +581,7 @@ If the user opts for reports, load `/report-design` and let it run. If they want
 ## What this skill does NOT do
 
 - **No scoring / benchmarking** of an existing model. For that, the user can ask "audit this model" separately.
-- **Report authoring** is delegated to `/report-design` which orchestrates the `pbi-cli-tool` CLI — don't write `.Report/` files from here.
+- **Report authoring** is delegated to `/report-design` which uses bundled Node scripts plus the `pbi` CLI runtime flow — don't write `.Report/` files from here.
 
 ---
 

package/src/content/skills/report-design/SKILL.md

@@ -9,13 +9,13 @@ Activate this skill when the user mentions:
 - Explicit invocation: `/report-design`
 
 ## Identity
-You are **BI Report Architect**, an orchestrator that turns a finished semantic model into a Power BI report. You author PBIR via **bundled Node scripts** — not via `pbi-cli-tool` upstream:
+You are **BI Report Architect**, an orchestrator that turns a finished semantic model into a Power BI report. You author the PBIR visual/theme layer via **bundled Node scripts** — not via the old `pbi visual` / `pbi report set-theme` path:
 
 - `scripts/create-visual.js` — creates any of the 28 native PBI visualTypes with a canonical `visual.json` shape (allowlist-driven, validated). **This replaces `pbi visual add` + `pbi visual bind`.**
 - `scripts/apply-theme.js` — registers a custom theme with the canonical `report.json` shape. **This replaces `pbi report set-theme`** (which writes invalid metadata for PBI Desktop March 2026).
 - `scripts/validate-pbir.js` — allowlist + bind-role validator. **Complements `pbi report validate`**, which passes `valid: True` even on non-native types like `stackedBarChart`.
 
-The `pbi-cli-tool` (MIT, by MinaSaad1) is kept around for **one purpose only**: model introspection via XMLA (`pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`). Prefer the Microsoft Modeling MCP when available — same capability, better integrated.
+The `pbi-cli-tool` (MIT, by MinaSaad1) is still required today for **three parts of the flow**: model introspection via XMLA (`pbi connect`, `pbi measure list`, `pbi table list`, `pbi column list`), report page management (`pbi report add-page`, `pbi report list-pages`), and schema validation (`pbi report validate`). Prefer the Microsoft Modeling MCP when available for the introspection part — same capability, better integrated.
 
 Full rationale: `references/native-visuals.md` → section "Lo que este skill YA no hace via CLI".
 
@@ -341,8 +341,8 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 **References** (`references/`):
 - `native-visuals.md` — **canonical reference**: 28 native visualTypes, their roles, shape canonical, copy-paste examples (read this before authoring)
 - `pbi-desktop-installation.md` — why the standalone installer build is required (not Microsoft Store), install + uninstall steps
-- `cli-setup.md` — how to install Python + pipx + pbi-cli-tool + pywin32 (only needed for model introspection via XMLA; scripts don't require it)
-- `cli-commands.md` — cheatsheet of the `pbi` commands still used by this skill (mostly `pbi connect` / `pbi measure list` for model introspection; authoring commands are superseded by the Node scripts)
+- `cli-setup.md` — how to install Python + pipx + pbi-cli-tool + pywin32 (required because this skill still uses `pbi` for connect, page operations, and validation)
+- `cli-commands.md` — cheatsheet of the `pbi` commands still used by this skill (`pbi connect`, `pbi measure list`, `pbi report add-page`, `pbi report list-pages`, `pbi report validate`)
 - `textbox.md` — historical manual-write pattern for textboxes (superseded by `create-visual.js --type textbox`; kept for reference)
 - `slicer.md` — historical manual-write pattern for slicers (superseded by `create-visual.js --type slicer --slicer-mode ...`; kept for reference)
 - `close-write-open-pattern.md` — why and how to handle the Desktop restart cycle
@@ -356,7 +356,7 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 - `layouts/generic.md` — fallback 3-page composition
 
 **Scripts** (`scripts/`):
-- `ensure-pbi-cli.sh` — idempotent installer for the pbi-cli-tool (only needed for model introspection via XMLA)
+- `ensure-pbi-cli.sh` — idempotent installer for the pbi-cli-tool (required for this skill's current runtime flow)
 - `apply-theme.js` — registers a custom PBIR theme with the canonical shape Desktop accepts (replaces the broken `pbi report set-theme` in PBI Desktop March 2026)
 - `create-visual.js` — creates any of the 28 native PBI visualTypes with a canonical `visual.json` shape (replaces `pbi visual add` + `pbi visual bind`; enforces allowlist)
 - `validate-pbir.js` — allowlist + role-checks validator that catches non-native visualTypes and missing/invalid bindings (complements `pbi report validate`)
@@ -373,4 +373,4 @@ Cuando guardes desde Desktop, commiteá el .pbip a git para versionar.
 
 ## Credit
 
-This skill orchestrates the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI by MinaSaad1 (MIT License). The CLI does the heavy lifting of PBIR JSON generation; we handle the teaching journey, planning, and Desktop lifecycle.
+This skill integrates with the [`pbi-cli-tool`](https://github.com/MinaSaad1/pbi-cli) CLI by MinaSaad1 (MIT License) for model introspection, page operations, and schema validation. Visual and theme authoring are handled by the bundled Node scripts; we orchestrate the teaching journey, planning, and Desktop lifecycle.