@luquimbo/bi-superpowers 4.1.1 → 4.1.3

package/bin/cli.js

@@ -28,34 +28,6 @@ const path = require('path');
 const { execSync } = require('child_process');
 const { loadSkills } = require('./lib/skills');
 
-// Background update check. update-notifier spawns a detached child process
-// that fetches the latest version from npm and caches it; the banner that
-// `notify()` schedules is printed at process exit, so this is zero-latency
-// on the command path. Errors are swallowed silently — the CLI must not
-// break because of a failed update check.
-let _updateNotifierNotify = null;
-try {
-  const updateNotifier = require('update-notifier');
-  const pkg = require('../package.json');
-  const notifier = updateNotifier({
-    pkg,
-    updateCheckInterval: 1000 * 60 * 60 * 24, // 24h
-    shouldNotifyInNpmScript: false,
-  });
-  _updateNotifierNotify = () =>
-    notifier.notify({
-      defer: true,
-      isGlobal: true,
-      message:
-        'Update available {currentVersion} → {latestVersion}\n' +
-        'Run {updateCommand} to update,\n' +
-        'then `super install --yes` to propagate the new skills.',
-    });
-} catch (_) {
-  // update-notifier not available during npm install phase, or network
-  // probe failed — skip silently.
-}
-
 // Optional lib import — may not be available during npm install phase.
 let generators;
 try {
@@ -160,14 +132,6 @@ function main() {
   const args = process.argv.slice(2);
   const command = args[0] || 'help';
 
-  // Schedule the update-notifier banner to print at process exit. Only fire
-  // for "normal" commands — skipping machine-readable and ultra-hot paths so
-  // tools that parse super output don't get surprised by the banner.
-  const SKIP_NOTIFY_COMMANDS = new Set(['version', 'help', 'about', 'info']);
-  if (_updateNotifierNotify && !SKIP_NOTIFY_COMMANDS.has(command)) {
-    _updateNotifierNotify();
-  }
-
   if (commands[command]) {
     commands[command](args.slice(1));
   } else {
@@ -619,9 +583,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 +613,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 +645,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.'
     );
@@ -765,19 +747,32 @@ function runWatch(args) {
     process.exit(1);
   }
 
-  const cliModule = {
-    syncProjectInternal: (targetDir, tools) => {
-      const skills = getSkillFiles();
+  watchCommand(args, getCommandConfig(), createWatchCliModule());
+}
+
+/**
+ * Build the tiny adapter used by `super sentinel`.
+ * It intentionally delegates through generateForTool(), the same path as
+ * kickoff/recharge, so regenerated plugin files keep the real package version,
+ * library prefix, and MCP launcher mode.
+ *
+ * @param {Object} [deps] - Test seams
+ * @param {Function} [deps.getSkillFilesFn] - Skill loader
+ * @param {Function} [deps.generateForToolFn] - Tool generator
+ * @returns {{syncProjectInternal: Function}} Watch command adapter
+ */
+function createWatchCliModule(deps = {}) {
+  const getSkillFilesFn = deps.getSkillFilesFn || getSkillFiles;
+  const generateForToolFn = deps.generateForToolFn || generateForTool;
+
+  return {
+    syncProjectInternal: async (targetDir, tools) => {
+      const skills = getSkillFilesFn();
       for (const tool of tools) {
-        const cfg = AI_TOOLS[tool];
-        if (cfg && cfg.generate) {
-          cfg.generate(targetDir, skills, { packageDir: PACKAGE_DIR });
-        }
+        await generateForToolFn(tool, targetDir, skills);
       }
     },
   };
-
-  watchCommand(args, getCommandConfig(), cliModule);
 }
 
 /**
@@ -803,7 +798,10 @@ module.exports = {
   loadToolConfig,
   saveToolConfig,
   getUpgradeCommand,
+  getUpgradeRefreshSteps,
   resetUpdateCheckStateAfterUpgrade,
+  createWatchCliModule,
+  getGenerationOptions,
   AI_TOOLS,
   SKILLS_DIR,
   VERSION,

package/bin/commands/build-desktop.js

@@ -30,10 +30,10 @@ const DESKTOP_TEMPLATE_DIR = path.join(PACKAGE_DIR, 'desktop-extension');
  * Bundle skills into the Desktop extension's skills/ directory.
  *
  * Handles both flat `src/content/skills/<name>.md` and folder-based
- * `src/content/skills/<name>/SKILL.md` layouts by flattening each skill
- * to a single `<name>.md` file inside `skillsOutDir`. The Claude Desktop
- * MCP server loads those flat files as prompts — `references/` and
- * `scripts/` are distributed through `super install`, not bundled here.
+ * `src/content/skills/<name>/SKILL.md` layouts by writing each skill as
+ * `<name>/SKILL.md`. Folder-based skills also get their runtime
+ * `references/` and `scripts/` subtrees copied into the MCPB, so prompts
+ * never point Claude Desktop at files missing from the installed extension.
  *
  * @param {string} skillsOutDir - Destination directory (created if missing)
  * @param {string} packageDir - npm package root containing src/content/skills/
@@ -43,11 +43,63 @@ function bundleSkills(skillsOutDir, packageDir) {
   fs.mkdirSync(skillsOutDir, { recursive: true });
   const skills = loadSkills({ packageDir });
   for (const skill of skills) {
-    fs.writeFileSync(path.join(skillsOutDir, `${skill.name}.md`), skill.content);
+    const skillOutDir = path.join(skillsOutDir, skill.name);
+    fs.mkdirSync(skillOutDir, { recursive: true });
+    fs.writeFileSync(path.join(skillOutDir, 'SKILL.md'), skill.content);
+
+    if (skill.bundleDir) {
+      copyRuntimeTree(
+        path.join(skill.bundleDir, 'references'),
+        path.join(skillOutDir, 'references')
+      );
+      copyRuntimeTree(path.join(skill.bundleDir, 'scripts'), path.join(skillOutDir, 'scripts'));
+    }
   }
   return skills.map((s) => s.name);
 }
 
+/**
+ * Copy runtime skill assets, excluding test/build/editor artifacts.
+ *
+ * @param {string} source - Source file or directory
+ * @param {string} target - Destination file or directory
+ */
+function copyRuntimeTree(source, target) {
+  if (!fs.existsSync(source)) {
+    return;
+  }
+
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(target, { recursive: true });
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+      copyRuntimeTree(path.join(source, entry.name), path.join(target, entry.name));
+    }
+    return;
+  }
+
+  if (!stat.isFile() || shouldSkipRuntimeFile(source)) {
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+}
+
+/**
+ * @param {string} filePath - Runtime asset path
+ * @returns {boolean} True if this file should not ship in the MCPB
+ */
+function shouldSkipRuntimeFile(filePath) {
+  const base = path.basename(filePath);
+  return (
+    base.endsWith('.test.js') ||
+    base.endsWith('.spec.js') ||
+    base.endsWith('.bak') ||
+    base.endsWith('.tmp')
+  );
+}
+
 /**
  * Build the .mcpb extension for Claude Desktop.
  *
@@ -94,7 +146,7 @@ BI Agent Superpowers — Build Desktop Extension
 
     // Bundle every skill (flat + folder-based) into temp/skills/
     const bundledNames = bundleSkills(path.join(tmpDir, 'skills'), PACKAGE_DIR);
-    const skillFiles = bundledNames.map((n) => `${n}.md`);
+    const skillFiles = bundledNames.map((n) => `${n}/SKILL.md`);
     console.log(`  Bundled ${bundledNames.length} skills`);
 
     // Patch template placeholder versions with the real package version
@@ -185,3 +237,5 @@ BI Agent Superpowers — Build Desktop Extension
 
 module.exports = buildDesktop;
 module.exports.bundleSkills = bundleSkills;
+module.exports.copyRuntimeTree = copyRuntimeTree;
+module.exports.shouldSkipRuntimeFile = shouldSkipRuntimeFile;

package/bin/commands/diff.js

@@ -13,6 +13,7 @@ const fs = require('fs');
 const path = require('path');
 const tui = require('../utils/tui');
 const { readSkillDirectory, normalizeSkillName } = require('../lib/skills');
+const { buildCommandMarkdown } = require('../lib/generators/claude-plugin');
 
 /**
  * Generate a simple diff between two strings
@@ -113,6 +114,71 @@ function compareFiles(skillPath, generatedPath) {
   };
 }
 
+/**
+ * Compare a loaded skill against the content that should have been generated
+ * for a specific tool. This avoids false drift from generator-owned wrappers
+ * such as Claude command frontmatter, generated comments, and update-check
+ * preambles.
+ *
+ * @param {{name: string, path: string, content: string}} skill - Loaded source skill
+ * @param {string} generatedPath - Path to generated file
+ * @param {Object} [options] - Comparison options
+ * @param {string} [options.tool] - Tool id
+ * @param {string} [options.libraryPrefix] - Library prefix used by the generator
+ * @returns {Object} Comparison result
+ */
+function compareSkillToGenerated(skill, generatedPath, options = {}) {
+  if (!skill || !fs.existsSync(skill.path)) {
+    return {
+      skill: skill && skill.name ? skill.name : 'unknown',
+      status: 'missing-source',
+      message: 'Source skill file not found',
+    };
+  }
+
+  if (!fs.existsSync(generatedPath)) {
+    return {
+      skill: skill.name,
+      status: 'not-generated',
+      message: 'Generated file does not exist (will be created on sync)',
+    };
+  }
+
+  const generatedContent = fs.readFileSync(generatedPath, 'utf8');
+  const expectedContent = buildExpectedGeneratedContent(skill, options);
+
+  if (expectedContent === generatedContent) {
+    return {
+      skill: skill.name,
+      status: 'unchanged',
+      message: 'No changes',
+    };
+  }
+
+  const diff = generateDiff(generatedContent, expectedContent);
+
+  return {
+    skill: skill.name,
+    status: 'changed',
+    diff,
+    sourcePath: skill.path,
+    generatedPath,
+  };
+}
+
+/**
+ * @param {{name: string, content: string}} skill - Loaded source skill
+ * @param {Object} options - Comparison options
+ * @returns {string} Expected generated output for the scan target
+ */
+function buildExpectedGeneratedContent(skill, options = {}) {
+  if (options.tool === 'claude-code') {
+    return buildCommandMarkdown(skill, options.libraryPrefix || 'library');
+  }
+
+  return skill.content;
+}
+
 /**
  * Get generated file path for a skill based on tool
  * @param {string} skillName - Skill name (without .md)
@@ -291,6 +357,7 @@ function diffCommand(args, config) {
   // and `path.basename(...)` would return `SKILL`, breaking the diff.
   const results = skillFiles.map((skillPath) => {
     const skillName = skillNameByPath.get(skillPath) || path.basename(skillPath, '.md');
+    const skill = skillsByName.get(skillName);
     const generatedPath = getGeneratedPath(skillName, options.tool, targetDir);
 
     if (!generatedPath) {
@@ -301,7 +368,10 @@ function diffCommand(args, config) {
       };
     }
 
-    return compareFiles(skillPath, generatedPath);
+    return compareSkillToGenerated(skill, generatedPath, {
+      tool: options.tool,
+      libraryPrefix: getLibraryPrefix(targetDir, config.packageDir),
+    });
   });
 
   // Display results
@@ -340,6 +410,21 @@ function diffCommand(args, config) {
 module.exports = Object.assign(diffCommand, {
   generateDiff,
   compareFiles,
+  compareSkillToGenerated,
+  buildExpectedGeneratedContent,
   getGeneratedPath,
   parseArgs,
 });
+
+/**
+ * Match the Claude plugin generator's library reference behavior.
+ *
+ * @param {string} targetDir - Target project directory
+ * @param {string} packageDir - Package root
+ * @returns {string} Library prefix used in generated markdown
+ */
+function getLibraryPrefix(targetDir, packageDir) {
+  return fs.existsSync(path.join(targetDir, 'library'))
+    ? 'library'
+    : path.join(packageDir, 'library');
+}

package/bin/commands/watch.js

@@ -48,6 +48,42 @@ function parseArgs(args) {
   return options;
 }
 
+/**
+ * Chokidar v4 no longer supports glob paths. Watch the skill root and filter
+ * relevant runtime/source files in-process so folder-based skills are covered.
+ *
+ * @param {string} skillsDir - Directory containing skill sources
+ * @returns {string[]} Watch roots
+ */
+function getWatchRoots(skillsDir) {
+  return [skillsDir];
+}
+
+/**
+ * @param {string} changedPath - Changed file path
+ * @param {string} skillsDir - Watched skill root
+ * @returns {boolean} Whether the changed file should trigger regeneration
+ */
+function isRelevantSkillPath(changedPath, skillsDir) {
+  const relative = path.relative(skillsDir, changedPath);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    return false;
+  }
+
+  const base = path.basename(changedPath);
+  if (
+    base.endsWith('.test.js') ||
+    base.endsWith('.spec.js') ||
+    base.endsWith('.bak') ||
+    base.endsWith('.tmp') ||
+    base.startsWith('.')
+  ) {
+    return false;
+  }
+
+  return ['.md', '.js', '.json', '.sh'].includes(path.extname(changedPath));
+}
+
 /**
  * Main watch command handler
  * @param {string[]} args - Command arguments
@@ -91,7 +127,7 @@ function watchCommand(args, config, cliModule) {
   const pendingChanges = new Set();
 
   // Create watcher
-  const watcher = chokidar.watch(path.join(skillsDir, '*.md'), {
+  const watcher = chokidar.watch(getWatchRoots(skillsDir), {
     persistent: true,
     ignoreInitial: true,
     awaitWriteFinish: {
@@ -106,7 +142,11 @@ function watchCommand(args, config, cliModule) {
    * @param {string} eventType - Type of event (add, change, unlink)
    */
   function handleChange(changedPath, _eventType) {
-    const filename = path.basename(changedPath);
+    if (!isRelevantSkillPath(changedPath, skillsDir)) {
+      return;
+    }
+
+    const filename = path.relative(skillsDir, changedPath);
     pendingChanges.add(filename);
 
     // Clear existing timer
@@ -157,7 +197,7 @@ function watchCommand(args, config, cliModule) {
  * @param {string|null} specificTool - Specific tool or null for all
  * @param {Object} cliModule - CLI module reference
  */
-function regenerateConfigs(targetDir, specificTool, cliModule) {
+async function regenerateConfigs(targetDir, specificTool, cliModule) {
   const ora = require('ora');
   const spinner = ora('Regenerating configs...').start();
 
@@ -193,7 +233,7 @@ function regenerateConfigs(targetDir, specificTool, cliModule) {
 
     // Call the sync logic from CLI module
     if (cliModule && typeof cliModule.syncProjectInternal === 'function') {
-      cliModule.syncProjectInternal(targetDir, tools);
+      await cliModule.syncProjectInternal(targetDir, tools);
       spinner.succeed(`Regenerated configs for: ${tools.join(', ')}`);
     } else {
       // Fallback: just report what would be done
@@ -205,4 +245,9 @@ function regenerateConfigs(targetDir, specificTool, cliModule) {
   }
 }
 
-module.exports = watchCommand;
+module.exports = Object.assign(watchCommand, {
+  parseArgs,
+  getWatchRoots,
+  isRelevantSkillPath,
+  regenerateConfigs,
+});

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.

package/bin/postinstall.js

@@ -36,7 +36,7 @@ Funciona con los 5 agentes:
   /report-design     — Generá reportes PBIR para Power BI Desktop (Windows)
 
 2 MCP servers:
-  powerbi-modeling   — Conexión local a Power BI Desktop (XMLA)
+  powerbi-modeling-mcp — Conexión local a Power BI Desktop (XMLA)
   microsoft-learn    — Docs de Microsoft Learn en contexto
 
 Documentation: https://github.com/luquimbo/bi-superpowers

package/commands/bi-start.md

@@ -55,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.
 
@@ -180,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".
 
@@ -293,7 +293,7 @@ Do NOT hand-author `report.json` theme metadata. The canonical PBIR shape (for r
 - `resourcePackages` includes a `{name: "RegisteredResources", type: "RegisteredResources"}` package whose `items[]` has `{name: "<file>.json", path: "<file>.json", type: "CustomTheme"}`
 - the theme file itself lives at `<reportPath>/StaticResources/RegisteredResources/<file>.json`
 
-**Conditional formatting (variance KPI green/red, diverging matrix gradients, signed-color bars) is DEFERRED to v4.1.** The layouts mention conditional color in design notes; in v4.0.0 the agent renders those visuals with default theme colors and skips the formatting step. Do not call `pbi format` from this skill in v4.0.0 — the `pbi format` syntax is not yet documented or tested for our use cases. Better a plain report that renders than a fancy one that breaks.
+**Conditional formatting note.** Layout notes may describe variance colors, diverging matrix gradients, or signed-color bars as design intent. The current `report-design` flow does not author those formatting rules. Render those visuals with theme/default colors unless you have a tested PBIR formatting implementation. Do not invent `pbi format` calls from this skill.
 
 ### 4.4 Validate (two layers)
 
@@ -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.