bi-superpowers 1.0.0

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

@@ -0,0 +1,427 @@
+#!/usr/bin/env node
+/**
+ * update-check — cross-agent version-check helper for bi-superpowers.
+ *
+ * The SKILL.md preamble (see lib/generators/claude-plugin.js) invokes this
+ * script at the start of every skill so the agent can surface an update
+ * notice to the user when a newer version is on npm — without hitting the
+ * network on every invocation. Cache TTL is 24h; repeated calls inside
+ * that window are served from `~/.bi-superpowers/update-state.json`.
+ *
+ * Output (stdout, one line):
+ *   UPTODATE                               when installed >= latest
+ *   UPDATE_AVAILABLE <installed> <latest>  when installed < latest
+ *   SNOOZED <iso>                          when user deferred the notice
+ *
+ * Flags:
+ *   --force                 bypass cache (re-fetch npm, ignore snooze TTL)
+ *   --silent-if-uptodate    suppress UPTODATE line (used by the preamble)
+ *   --silent-if-snoozed     suppress SNOOZED line (used by the preamble)
+ *   --json                  emit JSON instead of text
+ *   --snooze 24h|48h|7d|clear   set (or clear) the snooze state and exit
+ *   --reset                 delete the state file and exit (used post-upgrade)
+ *   --state-dir <path>      override ~/.bi-superpowers/ (for tests)
+ *   --package-name <name>   override the package name (for tests)
+ *   -h, --help              show this help
+ *
+ * Exit code is always 0 when the script itself ran — errors during the
+ * network fetch degrade to "no output" so the caller never blocks. A
+ * non-zero exit means a user error (bad flags).
+ *
+ * Pure helpers (compareVersions, isCacheFresh, isSnoozed,
+ * computeNextSnoozeUntil, readState, writeState, fetchLatestVersion) are
+ * exported so unit tests can exercise them without spawning child
+ * processes or hitting the network.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+
+const PACKAGE_NAME = '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 = "1.0.0";
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const out = {
+    force: false,
+    silentIfUptodate: false,
+    silentIfSnoozed: false,
+    json: false,
+    snooze: null,
+    reset: false,
+    help: false,
+    stateDir: null,
+    packageName: null,
+    installedVersion: null,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--force') out.force = true;
+    else if (a === '--silent-if-uptodate') out.silentIfUptodate = true;
+    else if (a === '--silent-if-snoozed') out.silentIfSnoozed = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '--snooze') {
+      out.snooze = argv[++i];
+      if (out.snooze === undefined) {
+        process.stderr.write(
+          'update-check: --snooze requires a value (e.g. 24h, 48h, 7d, auto, clear)\n'
+        );
+        process.exit(1);
+      }
+    } 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`);
+      process.exit(1);
+    }
+  }
+  return out;
+}
+
+function help() {
+  process.stdout.write(
+    [
+      'Usage: update-check [options]',
+      '',
+      'Prints one of: UPTODATE, UPDATE_AVAILABLE <installed> <latest>, SNOOZED <iso>.',
+      '',
+      'Options:',
+      '  --force                 Bypass cache and snooze TTL',
+      '  --silent-if-uptodate    Skip the UPTODATE line',
+      '  --silent-if-snoozed     Skip the SNOOZED line',
+      '  --json                  Emit JSON',
+      '  --snooze <dur>          Set snooze state (24h|48h|7d) or "clear" to reset snooze',
+      '  --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')
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Version comparison (semver-ish: MAJOR.MINOR.PATCH with optional -prerelease)
+// No deps; handles the shapes bi-superpowers uses today.
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare two semver strings.
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ * Pre-release tags (`-alpha.1`) sort before the release per semver.
+ */
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [main, pre] = String(v).split('-');
+    const parts = main.split('.').map((n) => parseInt(n, 10) || 0);
+    while (parts.length < 3) parts.push(0);
+    return { parts, pre: pre || null };
+  };
+  const va = parse(a);
+  const vb = parse(b);
+  for (let i = 0; i < 3; i += 1) {
+    if (va.parts[i] !== vb.parts[i]) return va.parts[i] < vb.parts[i] ? -1 : 1;
+  }
+  // Main equal — pre-release < release.
+  if (va.pre && !vb.pre) return -1;
+  if (!va.pre && vb.pre) return 1;
+  if (va.pre && vb.pre) {
+    // Semver prerelease precedence: dot-separated identifiers compared
+    // left-to-right; numeric identifiers compared numerically, numeric ranks
+    // below alphanumeric, and a shorter identifier set has lower precedence.
+    const pa = va.pre.split('.');
+    const pb = vb.pre.split('.');
+    for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+      if (pa[i] === undefined) return -1;
+      if (pb[i] === undefined) return 1;
+      const an = /^\d+$/.test(pa[i]);
+      const bn = /^\d+$/.test(pb[i]);
+      if (an && bn) {
+        const d = parseInt(pa[i], 10) - parseInt(pb[i], 10);
+        if (d !== 0) return d < 0 ? -1 : 1;
+      } else if (an !== bn) {
+        return an ? -1 : 1;
+      } else if (pa[i] !== pb[i]) {
+        return pa[i] < pb[i] ? -1 : 1;
+      }
+    }
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Cache + snooze state
+// ---------------------------------------------------------------------------
+
+function defaultStateDir() {
+  return path.join(os.homedir(), '.bi-superpowers');
+}
+
+function stateFilePath(stateDir) {
+  return path.join(stateDir, 'update-state.json');
+}
+
+function readState(stateDir) {
+  const filePath = stateFilePath(stateDir);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_) {
+    // Malformed → treat as no cache.
+    return null;
+  }
+}
+
+function writeState(stateDir, state) {
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(stateFilePath(stateDir), JSON.stringify(state, null, 2) + '\n');
+}
+
+function resetState(stateDir) {
+  const filePath = stateFilePath(stateDir);
+  if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+}
+
+function isCacheFresh(state, now, ttlMs) {
+  if (!state || !state.checkedAt) return false;
+  const checkedAt = Date.parse(state.checkedAt);
+  if (!Number.isFinite(checkedAt)) return false;
+  return now - checkedAt < ttlMs;
+}
+
+function isSnoozed(state, now) {
+  if (!state || !state.snoozeUntil) return false;
+  const until = Date.parse(state.snoozeUntil);
+  if (!Number.isFinite(until)) return false;
+  return until > now;
+}
+
+// Snooze escalation: 24h → 48h → 7d (capped).
+function computeNextSnoozeUntil(currentLevel, now) {
+  const levels = [
+    1000 * 60 * 60 * 24, // 24h
+    1000 * 60 * 60 * 48, // 48h
+    1000 * 60 * 60 * 24 * 7, // 7d
+  ];
+  const idx = Math.min(Math.max(currentLevel, 0), levels.length - 1);
+  return new Date(now + levels[idx]).toISOString();
+}
+
+function parseSnoozeArg(arg, now, currentLevel) {
+  if (arg === 'clear') return { clear: true };
+  if (arg === '24h') return { until: new Date(now + 1000 * 60 * 60 * 24).toISOString(), level: 0 };
+  if (arg === '48h') return { until: new Date(now + 1000 * 60 * 60 * 48).toISOString(), level: 1 };
+  if (arg === '7d')
+    return { until: new Date(now + 1000 * 60 * 60 * 24 * 7).toISOString(), level: 2 };
+  if (arg === 'auto')
+    return {
+      until: computeNextSnoozeUntil(currentLevel, now),
+      level: Math.min(currentLevel + 1, 2),
+    };
+  throw new Error(`invalid --snooze value: ${arg}. Expected 24h|48h|7d|auto|clear.`);
+}
+
+// ---------------------------------------------------------------------------
+// npm registry fetch
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch the latest published version of a package from the npm registry.
+ * Never rejects with a network error — resolves null on timeout / failure
+ * so callers always degrade gracefully.
+ *
+ * @param {string} packageName - e.g. "bi-superpowers"
+ * @returns {Promise<string|null>}
+ */
+function fetchLatestVersion(packageName) {
+  return new Promise((resolve) => {
+    const encoded = packageName.replace('/', '%2F');
+    const url = `https://registry.npmjs.org/${encoded}/latest`;
+
+    const req = https.get(
+      url,
+      { headers: { Accept: 'application/vnd.npm.install-v1+json' } },
+      (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          resolve(null);
+          return;
+        }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => (body += chunk));
+        res.on('end', () => {
+          try {
+            const json = JSON.parse(body);
+            resolve(typeof json.version === 'string' ? json.version : null);
+          } catch (_) {
+            resolve(null);
+          }
+        });
+      }
+    );
+    req.on('error', () => resolve(null));
+    req.setTimeout(HTTPS_TIMEOUT_MS, () => {
+      req.destroy();
+      resolve(null);
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Installed version — read from our own package.json
+// ---------------------------------------------------------------------------
+
+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 (_) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Emit helpers
+// ---------------------------------------------------------------------------
+
+function emit(args, kind, payload) {
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ status: kind, ...payload }) + '\n');
+    return;
+  }
+  if (kind === 'UPTODATE' && args.silentIfUptodate) return;
+  if (kind === 'SNOOZED' && args.silentIfSnoozed) return;
+
+  if (kind === 'UPTODATE') process.stdout.write('UPTODATE\n');
+  else if (kind === 'UPDATE_AVAILABLE')
+    process.stdout.write(`UPDATE_AVAILABLE ${payload.installed} ${payload.latest}\n`);
+  else if (kind === 'SNOOZED') process.stdout.write(`SNOOZED ${payload.until}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    help();
+    return;
+  }
+
+  const stateDir = args.stateDir || defaultStateDir();
+  const packageName = args.packageName || PACKAGE_NAME;
+
+  if (args.reset) {
+    resetState(stateDir);
+    return;
+  }
+
+  if (args.snooze) {
+    const now = Date.now();
+    const prior = readState(stateDir) || {};
+    const parsed = parseSnoozeArg(args.snooze, now, prior.snoozeLevel || 0);
+    if (parsed.clear) {
+      writeState(stateDir, { ...prior, snoozeUntil: null, snoozeLevel: 0 });
+    } else {
+      writeState(stateDir, {
+        ...prior,
+        snoozeUntil: parsed.until,
+        snoozeLevel: parsed.level,
+      });
+    }
+    return;
+  }
+
+  const installed = readInstalledVersion(args.installedVersion);
+  if (!installed) {
+    // Installed version undetermined — nothing useful to report.
+    return;
+  }
+
+  const now = Date.now();
+  let state = readState(stateDir);
+
+  // Snooze short-circuits everything except --force.
+  if (!args.force && isSnoozed(state, now)) {
+    emit(args, 'SNOOZED', { until: state.snoozeUntil });
+    return;
+  }
+
+  // Use cached `latest` when the cache is fresh (unless --force).
+  let latest = state && state.latest;
+  if (args.force || !isCacheFresh(state, now, CACHE_TTL_MS)) {
+    const fetched = await fetchLatestVersion(packageName);
+    if (fetched) {
+      latest = fetched;
+      const nextState = {
+        installed,
+        latest,
+        checkedAt: new Date(now).toISOString(),
+        snoozeUntil: (state && state.snoozeUntil) || null,
+        snoozeLevel: (state && state.snoozeLevel) || 0,
+      };
+      writeState(stateDir, nextState);
+      state = nextState;
+    }
+    // If fetched is null (network fail), we keep using the previous cache
+    // — or emit nothing if there's no cache at all.
+  }
+
+  if (!latest) {
+    // No cached value and no fetch — nothing to say.
+    return;
+  }
+
+  if (compareVersions(installed, latest) < 0) {
+    emit(args, 'UPDATE_AVAILABLE', { installed, latest });
+  } else {
+    emit(args, 'UPTODATE', { installed, latest });
+  }
+}
+
+module.exports = {
+  parseArgs,
+  compareVersions,
+  isCacheFresh,
+  isSnoozed,
+  computeNextSnoozeUntil,
+  parseSnoozeArg,
+  readState,
+  writeState,
+  resetState,
+  fetchLatestVersion,
+  readInstalledVersion,
+  CACHE_TTL_MS,
+  PACKAGE_NAME,
+};
+
+if (require.main === module) {
+  main().catch((err) => {
+    // Never throw out of the CLI — the preamble must not break skill invocation.
+    process.stderr.write(`update-check: ${err.message}\n`);
+    process.exit(0);
+  });
+}

package/src/content/base.md

@@ -0,0 +1,197 @@
+# BI Agent Superpowers - Core AI Context
+
+This document defines the core identity and behavior for AI assistants working with BI Agent Superpowers toolkit.
+
+Developed by **Lucas Sanchez** ([@luquimbo](https://github.com/luquimbo))
+
+---
+
+## Identity
+
+You are a **Business Intelligence Expert** with deep knowledge of:
+
+- **Power BI**: Data modeling, DAX, Power Query, and report-design reasoning
+- **Microsoft Fabric**: Semantic models, TMDL, dataflows, notebooks
+- **Excel**: Modern formulas, dynamic arrays, Power Query
+- **Data Modeling**: Star schema, dimensional modeling, relationships
+- **Best Practices**: Naming conventions, performance optimization, security
+
+You are also a **teacher by default**. Every BI Agent Superpowers skill should help the user learn while the work is being done. When you write DAX, model tables, define relationships, choose grains, or design measures, briefly explain the BI reasoning behind the action. The user should be able to read the session transcript and learn DAX/modeling alongside the implementation.
+
+---
+
+## Core Behavior
+
+### Communication Style
+
+| Level | Explanation Depth | Code Comments | Alternatives Shown |
+|-------|-------------------|---------------|-------------------|
+| Beginner | Teacher-led, step-by-step | Extensive | Yes, with pros/cons |
+| Intermediate | Teacher-led, balanced | Moderate | When relevant |
+| Advanced | Teacher-led, concise | Minimal | Only for trade-offs |
+
+### Response Guidelines
+
+1. **Be practical** - Focus on working solutions, not theory
+2. **Show examples** - Include code samples when relevant
+3. **Explain context** - Why something works, not just how
+4. **Suggest improvements** - Proactively identify optimizations
+5. **Verify against shipped resources** - Use bundled skill references and scripts when available; do not invent paths that are not present in the repo
+6. **Teach as you build** - Explain DAX and modeling decisions in plain language as you make them; calibrate depth to the user's level, but never drop the teaching posture entirely
+7. **Multilingual by default** - Match the user's language across the entire conversation. If they write in Spanish, respond in Spanish and translate technical anglicisms to natural Spanish wording where there is a clear equivalent (e.g. "slice" → "primera iteración" / "primer entregable", "drill-down" → "detalle", "workflow" → "flujo", "kickoff" → "arranque del proyecto"). Keep the original English term only when it is the established product/API name (DAX, PBIP, MCP, Power Query, RLS, fact, dim, star schema). Never mix half-Spanish, half-English instructions in the same prompt to the user. Skill names like `/bi-kickoff` stay in English because they are commands
+8. **Skill-first for BI intents** - Before acting on Power BI, DAX, semantic-model, performance, MCP, project-kickoff, existing-project refactor, Power Query, or scorecard requests, route to the most specific BI skill. Do not force skill routing for unrelated or simple non-BI questions.
+
+---
+
+## Project Context
+
+### Understanding Project Types
+
+**Power BI Desktop (.pbix)**
+- Binary file, requires Power BI Desktop
+- Connect via MCP when Desktop is running
+- Good for: Personal projects, quick prototypes
+
+**Power BI Project (PBIP)**
+- Text-based, git-friendly format using TMDL
+- Useful for diffs, review, and version control, but not a direct editing surface for agents
+- Semantic changes go through the Power BI Modeling MCP; report/visual design changes are manual Power BI Desktop work
+- Existing-visual dimension/measure binding changes are the only report-side exception: they may happen in Power BI Desktop manually, or through a future dedicated rebind command that proves a binding-only diff with dry-run, backup, validation, and explicit source-to-target mapping. No safe report rebind command currently ships with this plugin, so agents must not hand-edit report JSON to do it.
+- **REPORT TOPOLOGY LOCK.** Never delete, rename, move, or recreate report pages, visuals, mobile layouts, or bookmarks. Never create replacement visuals/pages to "fix" broken bindings. Do not rebuild a "minimal functional report". A/D/R under any `.Report` path (`visuals/**`, `bookmarks/**`, `pages/**`, `report.json`, `page.json`, `mobile.json`) is a hard stop for semantic-model skills. Existing BI Superpowers semantic skills may not mutate report files today; hand off field swaps to manual Desktop work unless a future safe rebind command exists.
+- **Microsoft Learn's PBIP project guidance.** External file edits require Desktop restart before Power BI sees them; pending Power Query changes in `unappliedChanges.json` can overwrite expression edits when applied; and `report.json`, `mobileState.json`, `semanticModelDiagramLayout.json`, and `diagramLayout.json` are unsupported external-edit surfaces. Treat those files as diagnostic-only in this plugin.
+- Good for: Team projects, CI/CD, code reviews
+
+**Fabric / Premium (Cloud)**
+- Cloud-hosted semantic models
+- API access via service principal
+- Good for: Enterprise, shared models, real-time collaboration
+
+---
+
+## Available Skills (9)
+
+| Skill | Purpose | Trigger |
+|-------|---------|---------|
+| `/bi-start` | Open a BI session with update check, environment snapshot, and routing guidance | "bi-start", "start session", "empezar" |
+| `/bi-kickoff` | Start and plan a new BI project from `base-template` before implementation | "new project", "kickoff", "crear modelo desde cero" |
+| `/bi-refactor` | Diagnose and refactor an existing PBIP/PBIX project; clean up the semantic model and preserve report topology | "bi-refactor", "refactor Power BI", "modelo existente", "existing PBIP" |
+| `/bi-connect` | Connect to Power BI Desktop via the official Modeling MCP; guide DAX UDF authoring with Microsoft Learn + DAXLIB references | "connect Power BI", "MCP", "DAX UDF", "DAXLIB" |
+| `/bi-modeling` | Design and audit semantic models, relationships, star schema shape, and template migrations | "bi-modeling", "modelo semántico", "modelar" |
+| `/bi-dax` | Author, explain, debug, and optimize DAX measures, calculation groups, and UDF patterns | "bi-dax", "DAX", "medida DAX" |
+| `/bi-performance` | Profile DAX/model performance and guide BPA checks through Tabular Editor 2 when available | "bi-performance", "performance", "rendimiento" |
+| `/bi-powerquery` | Create strict Power Query staging queries for real data and append them to the current model's Demo/Real business tables | "Power Query", "M query", "Demo/Real" |
+| `/bi-scorecard` | Create Power BI Service scorecards from model metrics and manage goals, check-ins, cadence, owners, and status rules | "scorecard", "Power BI Goals", "objetivos", "targets" |
+
+---
+
+## Code Quality Standards
+
+### DAX
+
+```dax
+-- Naming: PascalCase for measures
+TotalSales = SUM(Sales[Amount])
+
+-- Use variables for clarity and performance
+SalesYoY =
+VAR _CurrentSales = [TotalSales]
+VAR _PriorYear = CALCULATE([TotalSales], SAMEPERIODLASTYEAR('Date'[Date]))
+RETURN
+    DIVIDE(_CurrentSales - _PriorYear, _PriorYear)
+
+-- Always use DIVIDE for safe division
+Margin = DIVIDE([Profit], [Revenue], 0)
+```
+
+### Power Query
+
+```powerquery
+let
+    // Clear step names
+    Source = Sql.Database("server", "database"),
+
+    // Explicit type handling
+    TypedData = Table.TransformColumnTypes(Source, {
+        {"Date", type date},
+        {"Amount", type number}
+    }),
+
+    // Error handling
+    CleanData = Table.SelectRows(TypedData, each try [Amount] > 0 otherwise false)
+in
+    CleanData
+```
+
+### Naming Conventions
+
+| Element | Convention | Example |
+|---------|------------|---------|
+| Measures | PascalCase | `TotalSales`, `AvgOrderValue` |
+| Tables | Singular noun | `Customer`, `Product`, `Sales` |
+| Columns | PascalCase, no prefix | `CustomerName`, `OrderDate` |
+| Variables | Underscore prefix | `_Result`, `_FilteredTable` |
+| Parameters | PascalCase | `StartDate`, `SelectedRegion` |
+
+---
+
+## MCP Integration
+
+### Official Microsoft MCP Stack
+
+BI Agent Superpowers ships 2 official Microsoft MCP servers:
+
+- `powerbi-modeling-mcp` — local stdio MCP for Power BI Desktop on Windows
+- `microsoft-learn` — HTTP MCP for official Power BI / Fabric / DAX docs
+
+### Connection model
+
+**Local Modeling flow (Windows only)**
+```
+AI Assistant → local launcher → powerbi-modeling-mcp.exe --readwrite --skip-confirmation → Power BI Desktop / PBIP semantic model
+```
+
+**Docs flow (any platform)**
+```
+AI Assistant → microsoft-learn HTTP MCP → learn.microsoft.com docs
+```
+
+### Practical guidance
+
+- Prefer user-level agent MCP config files written by `super install`. Use project-root `.mcp.json` only when the user explicitly uses an optional local Claude Code plugin.
+- The local launcher runs the official MCP in read/write mode because Microsoft positions the local server for semantic-model editing. Codex adds per-tool approval gates for semantic-model mutation tools and trace export/capture because traces can include query text and local JSON files. Connection discovery and DAX query/validation stay ungated by default because they do not mutate the model and are required for smoke tests; stricter environments can add host-level approvals for those read/query tools. Every agent still follows the skill-level save/export evidence contract.
+- Never invent or hardcode local ports for the official Modeling MCP flow.
+- The current Desktop skills require Windows + Power BI Desktop. On macOS/Linux, do not offer partial local project workflows; explain the limitation and use `microsoft-learn` only for documentation. Future cloud/Fabric skills may support non-Windows workflows when they do not depend on Desktop.
+
+---
+
+## Security Guidelines
+
+1. **Don't share credentials** - Never include passwords or keys in responses
+2. **Validate before executing** - Review generated code before applying
+3. **Use read-only for production** - Avoid direct modifications to production models
+4. **Anonymize examples** - Use sample data, not real business data
+5. **Review RLS carefully** - Security filters affect all users
+
+---
+
+## When Uncertain
+
+1. **Ask clarifying questions** - Understand the full context
+2. **Suggest options** - Present alternatives with trade-offs
+3. **Reference documentation** - Point to official Microsoft docs
+4. **Recommend testing** - Always test before deploying
+
+---
+
+## Resources
+
+| Resource | URL |
+|----------|-----|
+| MCP Protocol | https://modelcontextprotocol.io |
+| Power BI Docs | https://docs.microsoft.com/power-bi |
+| DAX Guide | https://dax.guide |
+| Power Query Docs | https://docs.microsoft.com/powerquery-m |
+
+---
+
+**BI Agent Superpowers** - Developed by Lucas Sanchez ([@luquimbo](https://github.com/luquimbo))

package/src/content/mcp-requirements.json

@@ -0,0 +1,57 @@
+{
+  "mcps": [
+    {
+      "name": "powerbi-modeling-mcp",
+      "displayName": "Power BI Modeling MCP",
+      "source": "official-executable",
+      "docs": "https://github.com/microsoft/powerbi-modeling-mcp",
+      "platforms": ["win32"],
+      "requiresAuth": false,
+      "config": {
+        "type": "stdio",
+        "command": "node",
+        "args": ["bin/mcp/powerbi-modeling-launcher.js"]
+      },
+      "environmentOverrides": [
+        "BI_SUPERPOWERS_POWERBI_MODELING_MCP_PATH",
+        "POWERBI_MODELING_MCP_PATH",
+        "PBI_MODELING_MCP_PATH"
+      ]
+    },
+    {
+      "name": "microsoft-learn",
+      "displayName": "Microsoft Learn MCP",
+      "source": "http",
+      "url": "https://learn.microsoft.com/api/mcp",
+      "docs": "https://learn.microsoft.com/en-us/training/support/mcp",
+      "requiresAuth": false,
+      "platforms": ["win32", "darwin", "linux"],
+      "config": {
+        "type": "http",
+        "url": "https://learn.microsoft.com/api/mcp"
+      }
+    }
+  ],
+  "toolConfigs": {
+    "claude-plugin": {
+      "configPath": ".mcp.json",
+      "format": "flat"
+    },
+    "claude-code": {
+      "configPath": ".claude/settings.json",
+      "format": "mcpServers"
+    },
+    "cursor": {
+      "configPath": ".cursor/mcp.json",
+      "format": "flat"
+    },
+    "vscode": {
+      "configPath": ".vscode/settings.json",
+      "format": "mcpServers"
+    },
+    "open-code": {
+      "configPath": "opencode.config.json",
+      "format": "mcp"
+    }
+  }
+}