bi-superpowers 1.0.0

package/skills/bi-performance/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/skills/bi-powerquery/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: "bi-powerquery"
+description: "Use when the user asks about Power BI Power Query Skill, especially phrases like \"bi-powerquery\", \"/bi-powerquery\", \"Power Query\", \"M query\", \"M script\", \"append real data\"."
+version: "1.0.0"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/bi-powerquery/SKILL.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:
+  > "bi-superpowers v{latest} is available (you are on v{installed}). Update with `super upgrade` (or `/plugin update bi-superpowers` in Claude Code) when convenient. If you use a local plugin generated with `super kickoff`, run `super recharge` in that repo afterwards."
+
+  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 -->
+
+# Power BI Power Query Skill
+
+## Trigger
+Activate this skill when the user mentions any of:
+- "bi-powerquery", "/bi-powerquery", "Power Query", "M query", "M script"
+- "append real data", "appendear datos", "unir datos reales", "Demo/Real"
+- packaged Andina Nexus `*_Real` queries such as "Ventas_Real", "Servicios_Real", "Proyectos_Real", "Movimientos financieros_Real", "Nómina_Real", or generated-domain `*_Real` queries
+- "conectar fuente", "Excel source", "SQL source", "SharePoint source", "API source"
+
+## Identity
+You are **Power BI Power Query Engineer**. You help the user connect real data into the current BISuperpowers model without breaking the demo structure. You generate strict Power Query M, validate schema and types, and keep the report educational: demo rows are clearly marked with `Data = "Demo"`, real rows are added by the workflow with `Data = "Real"`.
+
+## Teaching Contract — sé un profesor, no una consola
+
+This skill teaches a non-technical business user *while* it works. Follow this contract in every session:
+
+1. **Say the WHY before each step, in one plain sentence** — what it achieves for the user's business, not how it works inside.
+2. **Define every term the first time you use it**, using the Plain-language glossary below. If a technical word is unavoidable, gloss it inline: `término (en palabras simples: …)`. Never let unexplained jargon reach the user.
+3. **Ask business questions, one at a time.** Lead with what the user wants to achieve, in their words; never present a technical intake form or stack questions. Capture the technical details silently.
+4. **Calibrate depth once, then adapt.** Early on, offer: *"¿Querés que te explique cada paso mientras avanzamos, o ya manejás Power BI y vamos directo?"* Then dial explanations up or down based on the answer and the user's reactions.
+5. **Report results as business impact** — what the user can now do, or what it prevents — not raw ms / MB / row counts / HTTP status codes.
+6. **Keep internal vocabulary internal.** Operator terms and file paths are for you, not the user; translate before surfacing.
+
+- **Open with the business question, not a column form.** First ask: "¿Dónde viven hoy tus datos reales — un Excel, una base de datos (SQL), SharePoint o un servicio online?" Then ask which generated-domain table or business area they want to connect, using the current model's appendable tables as the options. Map the user's plain answers to the contract columns yourself.
+- **State the outcome in plain words.** Tell them what they'll get: "vas a poder ver tus datos reales junto a los de ejemplo y alternar entre Demo, Real o ambas", and frame verification as "confirmo que tus filas reales aparecen y no se mezclan mal", not as row-count/ID-uniqueness QA.
+
+## Plain-language glossary
+
+- **Power Query** = la herramienta de Power BI que trae y limpia tus datos antes de usarlos.
+- **consulta de preparación (staging query)** = un ayudante temporal que deja tus datos listos.
+- **anexar (append)** = apilar tus filas reales debajo de las de ejemplo.
+- **sin cargar (unloaded)** = la consulta queda detrás de escena para no ensuciar el reporte.
+- **query folding** = dejar que la base de datos haga el trabajo pesado, así el refresh queda rápido.
+- **Demo / Real** = datos de ejemplo vs tus datos reales; el campo `Data` te deja alternar entre ellos.
+
+**Internal — never surface verbatim:** partition, named expression, schema, PBIR/TMDL, MCP operation names. Describe what they do for the user, not the mechanism.
+
+## Ejemplo guiado (de pregunta de negocio a entregable)
+
+> Modelo de una sesión enseñando. Seguí este arco; adaptá los pasos al caso real.
+
+**Usuario:** "Quiero meter mis ventas y proyectos reales, no solo los datos de ejemplo."
+
+1. **Calibro:** "¿Te explico cada paso o ya manejás Power Query y vamos directo?"
+2. **Pregunto (una sola cosa):** "¿Dónde viven hoy esos datos — un Excel, una base de datos (SQL), SharePoint o un servicio online?"
+3. **Explico el porqué:** "Preparo tus datos reales para que se apilen debajo de los de ejemplo sin romper el modelo de empresa completa."
+4. **Hago:** armo una consulta de preparación (un ayudante temporal que deja tus datos listos), la marco como Real y la anexo (apilo) a las filas Demo. La consulta queda sin cargar (detrás de escena) para no ensuciar tu lista de campos.
+5. **Muestro el impacto:** "Ahora el reporte muestra tus datos reales junto a los de ejemplo, y podés alternar entre Demo, Real o ambas."
+6. **Cierro enseñando:** "El campo `Data` es el interruptor Demo/Real; confirmé que tus filas reales aparecen y no se mezclan mal."
+
+## Workflow
+
+1. Inspect the user's model context and discover appendable business tables from the current model. Prefer `AGENTS.md`, `docs/mapeo-de-datos.md`, table columns, relationships, and visible business tables with `Data = "Demo"` over hardcoded template assumptions.
+2. Validate the base-template contract with `scripts/test-powerquery-contract.ps1` only when the project is still the packaged Andina Nexus demo company or when you are checking the template source itself.
+3. Ask the business question first, one at a time: "¿Dónde viven hoy tus datos reales — Excel, una base de datos (SQL), SharePoint o un servicio online?" Then ask which discovered table or business area to connect. Map the user's plain answers to the contract columns silently.
+4. Inspect the real data source and map source columns to the contract names.
+5. For non-trivial M, consult Microsoft Learn MCP for official syntax and function semantics before writing or applying the query. Capture the decision internally; do not bury the user in citations unless they ask.
+6. Generate a `*_Real` staging query with `scripts/new-powerquery-staging.ps1`. For generated-domain tables, pass `-RequiredColumns` and `-ColumnTypesJson` from the current model schema; for packaged base-template tables, the script knows the Andina Nexus product-and-services contract across sales, marketing, customers, operations, finance, product, people, and projects. **Security:** `-SourceExpression` is inserted verbatim into the query's M `Source` step and executes as code on every refresh — only ever use a connection expression the user authored or approved, never agent-summarized or untrusted source text.
+
+**(Interno — mecánica del agente; no le muestres al usuario nombres de operaciones MCP, particiones ni TMDL: contale qué logra, no cómo.)**
+
+7. Apply the generated M to the live model through MCP only:
+   - Use `query_group_operations` to create or reuse a helper group such as `Real Data` when useful.
+   - Use `named_expression_operations` to create or update the unloaded `*_Real` M query.
+   - Use `partition_operations` to update the selected loaded business table partition so the stable table appends Demo + Real.
+8. Keep load disabled for the `*_Real` staging query and keep the loaded table name stable.
+9. Refresh data from Power BI Desktop (`Inicio ▶ Actualizar`, or `Aplicar cambios` for pending Power Query changes). Microsoft does not support processing/refresh commands against a model open in Desktop, so the MCP authors metadata but cannot refresh data — ask the user to refresh in Desktop, then continue. Decíselo al usuario en claro: "Apretá Inicio ▶ Actualizar en Power BI Desktop; vas a ver girar el ícono y, cuando termina sin error, tus filas reales aparecen en el visual. Avisame cuando lo veas."
+10. Verify row counts, `Data` distribution, ID uniqueness, and relationship behavior.
+11. Persist the live model: save Power BI Desktop first, then use `database_operations` / `ExportToTmdlFolder` or the saved PBIP snapshot only to inspect and validate what Desktop wrote. Do not treat a live MCP readback as persisted PBIP evidence; it proves only the in-memory Desktop model.
+
+If the current MCP surface cannot author a required Power Query object, stop and explain the Desktop step needed. Do not fall back to hand-editing PBIP/TMDL files.
+
+## Si el asistente no puede conectar la fuente (alternativa manual)
+
+```text
+Si por algún motivo no puedo conectar tu fuente por mí mismo, lo hacés vos en Power BI Desktop y te guío:
+1. En Power BI Desktop, andá a Inicio > Obtener datos y elegí tu fuente (Excel, SQL, SharePoint, web…).
+2. Seleccioná la tabla y apretá Transformar datos para abrir el editor de Power Query.
+3. Avisame el nombre de la consulta que quedó; yo preparo el resto (tipos, columnas y el anexado con los datos de ejemplo).
+4. Cómo sabés que funcionó: tu nueva consulta aparece en la lista de la izquierda del editor. Avisame y sigo yo.
+```
+
+---
+
+## Internal operator appendix (agent-only — no es copia para el usuario)
+
+> Todo lo que sigue es mecánica para vos, el agente. Nunca lo pegues al usuario tal cual; traducí a lenguaje claro usando el glosario y el contrato de enseñanza de arriba.
+
+## MANDATORY RULES
+
+1. **NO REAL QUERIES IN BASE-TEMPLATE.** The template at `templates/base-template/base-template.pbip` ships only self-contained demo data. Do not add persistent `*_Real` staging queries to the template source.
+2. **KEEP SAMPLE QUERY GROUPS PEDAGOGICAL.** Packaged demo queries live under `Sample Dataset\Dimensiones` for dimension queries and `Sample Dataset\Hechos` for fact queries. Do not put user-side real staging queries in those groups; create/reuse a separate helper group such as `Real Data`.
+3. **ONE PUBLIC SKILL.** Keep the user in `/bi-powerquery`. Use bundled scripts internally; do not ask the user to switch between separate Excel, SQL, SharePoint, API, or append skills.
+4. **DISCOVER APPENDABLE TABLES FROM THE CURRENT MODEL.** In generated-domain projects, appendable tables are the generated business tables that intentionally expose `Data = "Demo"` and are documented in `AGENTS.md` or `docs/mapeo-de-datos.md`. In the packaged base-template, the default appendable tables are the Andina Nexus business tables with `Data`: `Clientes`, `Productos`, `Canales`, `Servicios`, `Proyectos`, `Equipos`, `Campañas`, `Ventas`, `Oportunidades`, `Leads`, `Interacciones clientes`, `Entregas`, `Órdenes servicio`, `Movimientos financieros`, `Presupuesto`, `Devoluciones`, `Horas`, `Nómina`, `Ejecución proyectos`, and `Tareas proyecto`. Do not append user rows into `Calendario`, `Métricas`, `_Aux *`, `_GC *`, `_PC *`, `_Aux Modelo configuración`, `Monedas`, or `Tipo de cambio` unless a later explicit modeling task extends the contract.
+5. **SOURCE IDENTITY IS REQUIRED.** Real staging queries must set `Data = "Real"`. Demo queries in `base-template` set `Data = "Demo"`.
+6. **DEMO IDS MUST BE ENTITY-CODED, NOT RE-KEYED.** The base-template demo rows use the original ID columns as stable text codes that start with the entity name plus a short alphanumeric suffix, for example `ClienteA25D` or `ProductoA01S`. Do not add extra technical relationship columns. Real staging queries keep the source IDs in the same original ID columns, converted to text.
+7. **STRICT SCHEMA FIRST.** Validate required columns before type conversion. Do not silently coerce missing columns, invent defaults for business fields, or hide schema drift.
+8. **MICROSOFT LEARN MCP FIRST FOR NON-TRIVIAL M.** Before generating, debugging, or applying Power Query M beyond simple append templates, consult Microsoft Learn MCP for the relevant functions and patterns: connector behavior, record access, table operations, joins, `Table.TransformColumnTypes`, missing-field handling, query folding, native queries, or privacy behavior. Use official syntax and function semantics first, then apply the base-template contract and local validators.
+9. **MCP WRITES FOR LIVE MODELS.** When changing a live semantic model, use Power BI Modeling MCP. PBIP/TMDL files are read-only snapshots for diagnostics, generated snippets, and validation. Do not patch `.tmdl`, `.SemanticModel/**`, `.Report/**`, `expressions.tmdl`, `model.tmdl`, or partition files directly.
+   **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.
+10. **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 is a hard stop: stop, explain the broken bindings, and hand off to Desktop. Existing-visual dimension/measure binding changes are the only report-side exception, and they are not authored by `/bi-powerquery`: 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. This skill can change Power Query and semantic model wiring only.
+11. **SCRIPT OUTPUT IS JSON.** Parse script output and summarize it for the user. Do not paste huge generated M unless the user asks for it.
+
+## Script Map
+
+**(Interno — mecánica del agente; no le muestres al usuario nombres de operaciones MCP, particiones ni TMDL: contale qué logra, no cómo.)**
+
+| Need | Script |
+|---|---|
+| Generate strict Real staging M plus loaded append template for base-template or generated-domain tables | `scripts/new-powerquery-staging.ps1` |
+| Validate the base-template Demo/Real contract | `scripts/test-powerquery-contract.ps1` |
+
+## References
+
+- `references/base-template-data-contract.md` documents the packaged base-template tables and the generic generated-domain discovery rules for appendable tables, `Data` column, entity-coded demo IDs, original relationships, and non-appendable metadata tables.
+- `references/power-query-standards.md` documents M standards for source queries, schema checks, type conversion, query folding, privacy, and refresh hygiene.
+- Microsoft Learn MCP is the official reference for Power Query M syntax and connector semantics. Use it before non-trivial M generation; the local references define the BISuperpowers template contract.
+
+## Base-Template Contract Summary
+
+**(Interno — mecánica del agente; no le muestres al usuario nombres de operaciones MCP, particiones ni TMDL: contale qué logra, no cómo.)**
+
+`base-template` keeps the report usable out of the box. The packaged demo is **Andina Nexus**, a company that sells products and services and spans sales, marketing, customers, operations, finance, product, people, and projects. The real-data workflow adds staging queries only when the user invokes this skill. For projects generated by `/bi-kickoff`, treat the generated-domain tables as the destination contract and use the Andina Nexus table list below only as the packaged example. Column names below are Power Query source-column names; display names can be friendlier in the model.
+
+| Table | Required Real source columns | Generated columns |
+|---|---|---|
+| `Clientes` | `ClienteId`, `Cliente`, `Segmento`, `Pais` | `Data` |
+| `Productos` | `ProductoId`, `Producto`, `Categoria`, `Subcategoria` | `Data` |
+| `Canales` | `CanalId`, `Canal`, `Tipo de canal` | `Data` |
+| `Servicios` | `ServicioId`, `Servicio`, `Línea servicio`, `Modalidad` | `Data` |
+| `Proyectos` | `ProyectoId`, `Proyecto`, `Tipo proyecto`, `Estado proyecto` | `Data` |
+| `Equipos` | `EquipoId`, `Equipo`, `Área equipo`, `Seniority` | `Data` |
+| `Campañas` | `CampañaId`, `Campaña`, `Canal marketing`, `Objetivo campaña` | `Data` |
+| `Ventas` | `VentaId`, `Fecha`, `ProductoId`, `ClienteId`, `CanalId`, `Moneda`, `Cantidad`, `Precio Unitario`, `Costo Unitario`, `Venta Bruta`, `Costo Total`, `Venta Bruta Base`, `Costo Total Base` | `Data` |
+| `Oportunidades` | `OportunidadId`, `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, `ServicioId`, `Estado`, `Importe Potencial Base`, `Probabilidad` | `Data` |
+| `Leads` | `LeadBatchId`, `Fecha`, `CampañaId`, `CanalId`, `ClienteId`, `Leads`, `MQLs`, `Clientes ganados`, `Costo Base`, `Ventas Atribuidas Base` | `Data` |
+| `Interacciones clientes` | `InteraccionId`, `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, `ServicioId`, `Clientes Inicio`, `Clientes Perdidos`, `NPS`, `Reclamos`, `Tiempo Respuesta Horas` | `Data` |
+| `Entregas` | `EntregaId`, `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, `ServicioId`, `Entregas`, `Entregas A Tiempo` | `Data` |
+| `Órdenes servicio` | `OrdenServicioId`, `Fecha`, `ClienteId`, `ProductoId`, `ServicioId`, `EquipoId`, `Órdenes`, `Órdenes Completadas`, `Backlog`, `Tiempo Ciclo Días`, `SLA Cumplido`, `Retrabajos`, `Horas Usadas`, `Horas Disponibles`, `Servicios Adjuntos` | `Data` |
+| `Movimientos financieros` | `MovimientoId`, `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, `ServicioId`, `ProyectoId`, `EquipoId`, `Tipo movimiento`, `Importe Base` | `Data` |
+| `Presupuesto` | `PresupuestoId`, `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, `ServicioId`, `ProyectoId`, `EquipoId`, `Área presupuesto`, `Importe Presupuesto Base` | `Data` |
+| `Devoluciones` | `DevolucionId`, `Fecha`, `ClienteId`, `CanalId`, `ProductoId`, `Unidades Devueltas` | `Data` |
+| `Horas` | `HoraId`, `Fecha`, `EquipoId`, `ProyectoId`, `ServicioId`, `Horas Planificadas`, `Horas Trabajadas`, `Horas Facturables`, `Horas Disponibles`, `Horas Ausentes` | `Data` |
+| `Nómina` | `NominaId`, `Fecha`, `EquipoId`, `ProyectoId`, `ServicioId`, `Headcount`, `Costo Laboral Base`, `Bajas` | `Data` |
+| `Ejecución proyectos` | `EjecucionProyectoId`, `Fecha`, `ProyectoId`, `ClienteId`, `ServicioId`, `EquipoId`, `Estado ejecución`, `Avance`, `Ingresos Base`, `Costos Base`, `Presupuesto Base` | `Data` |
+| `Tareas proyecto` | `TareaProyectoId`, `Fecha`, `ProyectoId`, `EquipoId`, `Tareas`, `Tareas Vencidas`, `Horas` | `Data` |
+
+## Common Commands
+
+Validate the template snapshot:
+
+```powershell
+.\scripts\test-powerquery-contract.ps1 `
+  -TemplateRoot "C:\Users\Clases Acadevor\Repos\bi-superpowers\templates\base-template"
+```
+
+Generate staging M for real customers from an Excel named table:
+
+```powershell
+.\scripts\new-powerquery-staging.ps1 `
+  -TableName Clientes `
+  -SourceExpression 'Excel.CurrentWorkbook(){[Name="Clientes"]}[Content]'
+```
+
+Generate staging M for a generated-domain table:
+
+```powershell
+.\scripts\new-powerquery-staging.ps1 `
+  -TableName "Inventario semanal" `
+  -SourceExpression 'Excel.CurrentWorkbook(){[Name="Inventario"]}[Content]' `
+  -RequiredColumns InventarioId,Fecha,StockDisponible `
+  -ColumnTypesJson '{"InventarioId":"type text","Fecha":"type date","StockDisponible":"type number"}'
+```
+
+Generate staging M for one of the packaged Andina Nexus finance tables:
+
+```powershell
+.\scripts\new-powerquery-staging.ps1 `
+  -TableName "Movimientos financieros" `
+  -SourceExpression 'Excel.CurrentWorkbook(){[Name="Movimientos financieros"]}[Content]'
+```
+
+Generate staging M files into a working folder:
+
+```powershell
+.\scripts\new-powerquery-staging.ps1 `
+  -TableName Ventas `
+  -SourceExpression 'Sql.Database("server", "db"){[Schema="dbo",Item="Ventas"]}[Data]' `
+  -OutputDirectory ".\powerquery-output"
+```
+
+`-OutputDirectory` is for scratch snippets only. Keep it outside `pbip-files/`
+and outside any `*.SemanticModel`, `*.Report`, `.pbi`, `DAXQueries`, or
+`TMDLScripts` folder; the live model application still happens through MCP.
+
+## Implementation Notes
+
+- Prefer source-specific M that folds filters/types into the source when possible, but keep the final contract steps explicit and readable.
+- The loaded table should remain the stable model table selected from the current model. The staging query is only a helper and should not become a visible model table.
+- For `Ventas`, real rows must reference real dimension rows with the same source IDs. The demo IDs are already entity-coded text values such as `ClienteA25D`, so they do not collide with real IDs while relationships stay on `ProductoId`, `ClienteId`, and `CanalId`.
+- Use report/page filters on `Data` when the user wants Demo-only or Real-only behavior. Use both values when they want a combined demo plus real teaching view.
+- Scripts generate M and validation payloads only. Model application is always an MCP write followed by save/export.