@luquimbo/bi-superpowers 4.1.2 → 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 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
-  // 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 {
@@ -783,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);
 }
 
 /**
@@ -823,6 +800,8 @@ module.exports = {
   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/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/report-design.md

@@ -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)
 

package/desktop-extension/server.js

@@ -25,25 +25,58 @@ const server = new McpServer({
   version: '0.0.0-template',
 });
 
-// Load all skill markdown files from the bundled skills/ directory.
-const skillFiles = fs.existsSync(skillsDir)
-  ? fs.readdirSync(skillsDir).filter((f) => f.endsWith('.md'))
-  : [];
+function loadBundledSkills(directory) {
+  if (!fs.existsSync(directory)) {
+    return [];
+  }
+
+  const skills = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const entryPath = path.join(directory, entry.name);
+
+    if (entry.isFile() && entry.name.endsWith('.md')) {
+      skills.push({
+        name: path.basename(entry.name, '.md'),
+        bundleDir: directory,
+        content: fs.readFileSync(entryPath, 'utf8'),
+      });
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      const skillPath = path.join(entryPath, 'SKILL.md');
+      if (fs.existsSync(skillPath)) {
+        skills.push({
+          name: entry.name,
+          bundleDir: entryPath,
+          content: fs.readFileSync(skillPath, 'utf8'),
+        });
+      }
+    }
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
 
 // Register each skill as an MCP prompt that Claude Desktop can invoke.
-for (const file of skillFiles) {
-  const name = path.basename(file, '.md');
-  const content = fs.readFileSync(path.join(skillsDir, file), 'utf8');
+for (const skill of loadBundledSkills(skillsDir)) {
+  const { name, bundleDir, content } = skill;
 
   // Use the first non-header line as a short description for the prompt.
   const firstLine = content.split('\n').find((l) => l.trim() && !l.startsWith('#'));
   const description = firstLine ? firstLine.slice(0, 120).trim() : `BI Superpowers: ${name}`;
+  const promptText = [
+    `Bundled skill directory: ${bundleDir}`,
+    'Resolve this skill\'s references/ and scripts/ paths relative to that directory.',
+    '',
+    content,
+  ].join('\n');
 
   server.prompt(name, { description }, () => ({
     messages: [
       {
         role: 'user',
-        content: { type: 'text', text: content },
+        content: { type: 'text', text: promptText },
       },
     ],
   }));
@@ -73,7 +106,7 @@ into Claude Desktop, add the following to your \`claude_desktop_config.json\`
 \`\`\`json
 {
   "mcpServers": {
-    "powerbi-modeling": {
+    "powerbi-modeling-mcp": {
       "command": "node",
       "args": ["<absolute path to powerbi-modeling-launcher.js>"]
     },
@@ -85,7 +118,7 @@ into Claude Desktop, add the following to your \`claude_desktop_config.json\`
 }
 \`\`\`
 
-The \`powerbi-modeling\` server requires Power BI Desktop on Windows
+The \`powerbi-modeling-mcp\` server requires Power BI Desktop on Windows
 with a model open. If you prefer automated setup, run
 \`super install\` from the bi-superpowers CLI — it configures both
 servers across all 5 supported AI agents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luquimbo/bi-superpowers",
-  "version": "4.1.2",
+  "version": "4.1.3",
   "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": {
@@ -24,10 +24,9 @@
     "adm-zip": "^0.5.17",
     "boxen": "^5.1.2",
     "chalk": "^4.1.2",
-    "chokidar": "^3.6.0",
+    "chokidar": "^4.0.3",
     "cli-table3": "^0.6.5",
-    "ora": "^5.4.1",
-    "update-notifier": "^5.1.0"
+    "ora": "^5.4.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/skills/bi-start/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.2"
+version: "4.1.3"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/bi-start.md instead. -->

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

@@ -47,7 +47,7 @@ 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";
+const BUNDLED_INSTALLED_VERSION = "4.1.3";
 
 // ---------------------------------------------------------------------------
 // Argument parsing

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.2"
+version: "4.1.3"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/pbi-connect.md instead. -->

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

@@ -47,7 +47,7 @@ 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";
+const BUNDLED_INSTALLED_VERSION = "4.1.3";
 
 // ---------------------------------------------------------------------------
 // Argument parsing

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.2"
+version: "4.1.3"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/project-kickoff.md instead. -->

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

@@ -47,7 +47,7 @@ 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";
+const BUNDLED_INSTALLED_VERSION = "4.1.3";
 
 // ---------------------------------------------------------------------------
 // Argument parsing

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.2"
+version: "4.1.3"
 ---
 
 <!-- Generated by BI Agent Superpowers. Edit src/content/skills/report-design.md instead. -->
@@ -295,7 +295,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)
 

package/skills/report-design/references/layouts/finance.md

@@ -28,7 +28,7 @@ Roles used below (to be resolved via the MCP):
 | Scenario slicer | slicer (manual JSON — see `references/slicer.md`) | 848, 312, 336, 80 | `Scenario[Scenario]` |
 
 **Design notes:**
-- Variance KPI: conditional formatting (green positive, red negative) is deferred to v4.1 — render as plain card for v4.0.0.
+- Variance KPI: green/red conditional coloring is design intent only. Render as a plain card with theme/default colors unless a tested PBIR formatting implementation is available.
 - Year slicer default: current year (single-select).
 
 ---
@@ -61,5 +61,5 @@ Roles used below (to be resolved via the MCP):
 | Account × Month matrix | matrix | 16, 512, 1168, 144 | rows: `account-dim-column`, cols: `'Date'[Month]`, values: `variance-measure` with diverging gradient |
 
 **Design notes:**
-- Variance-sign coloring (diverging palette) is deferred to v4.1 — render bars/matrix with default theme colors for v4.0.0.
+- Variance-sign coloring (diverging palette) is design intent only. Render bars/matrix with theme/default colors unless a tested PBIR formatting implementation is available.
 - The bottom matrix is short (144px) so it acts as a "heatmap strip" rather than a scrollable table.

package/skills/report-design/references/native-visuals.md

@@ -311,7 +311,7 @@ Si PBI Desktop introduce un visualType nuevo (o encontrás uno nativo que falta
 
 ## Features de `visual.json` que `create-visual.js` NO soporta todavía
 
-Descubiertos al regenerar la smoke-test "Galería de Visuales" end-to-end con el script (backlog item 2, cycle v4.1). No bloquean el authoring — la shape que emite el script pasa `pbi report validate` y `validate-pbir.js` — pero sí dejan regresiones visuales si el `visual.json` hand-written aprovechaba alguno de estos features:
+Descubiertos al regenerar la smoke-test "Galería de Visuales" end-to-end con el script. No bloquean el authoring — la shape que emite el script pasa `pbi report validate` y `validate-pbir.js` — pero sí dejan regresiones visuales si el `visual.json` hand-written aprovechaba alguno de estos features:
 
 1. **`query.sortDefinition`** — sort explícito por medida/columna con dirección. `create-visual.js` no lo emite, así que un visual "ranking" tipo barChart ordenado descendente por una medida pierde el orden en la regeneración. **Workaround**: ordenar en Desktop manualmente después del `.pbip` abrir, o hand-extender el `visual.json` con `sortDefinition` post-creación. **Fix futuro**: `--sort-by "Role:Field" --sort-dir descending` en `create-visual.js`.
 
@@ -319,7 +319,7 @@ Descubiertos al regenerar la smoke-test "Galería de Visuales" end-to-end con el
 
 3. **`queryState.<Role>.projections[].active`** — las columnas siempre salen con `active: true`, las medidas nunca. Si un visual hand-written tenía `active: true` en una medida (para indicar que la medida es la "default Y") o `active: false` en una columna (hidden projection), el script normaliza. Rara vez significativo para el render pero cambia el shape JSON.
 
-4. **Formato condicional**: colores signados (positivo verde / negativo rojo), gradientes en matriz, data bars en tabla. Ninguno de estos expresa shape via `create-visual.js`. Quedó deferido a v4.1+ en `SKILL.md` PHASE 4.3.
+4. **Formato condicional**: colores signados (positivo verde / negativo rojo), gradientes en matriz, data bars en tabla. Ninguno de estos expresa shape via `create-visual.js`; tratarlos como diseño previsto hasta que exista una implementación PBIR testeada.
 
 Cualquier cambio en el script que cubra estos gaps debe: (a) agregar el flag a `parseArgs`, (b) cubrirlo con tests en `create-visual.test.js`, (c) documentarlo en este archivo, (d) regenerar la Galería para que ejercite el feature.
 

package/skills/report-design/references/slicer.md

@@ -86,4 +86,4 @@ cat > "<reportPath>/definition/pages/<pageName>/visuals/<visualName>/visual.json
 EOF
 ```
 
-A reusable helper script (`scripts/write-slicer.sh`) is a v4.1 candidate; v4.0.0 ships with the heredoc pattern.
+Prefer `scripts/create-visual.js --type slicer` for new slicers. Keep the heredoc pattern above only as a fallback when the helper script is unavailable.