bi-superpowers 1.0.0

package/src/content/skills/bi-performance/scripts/install-tabular-editor.ps1

@@ -0,0 +1,159 @@
+# install-tabular-editor.ps1
+# Detects Tabular Editor 2 (free, MIT) at the expected install path.
+# With -Install, downloads the latest stable release ZIP from GitHub and
+# extracts it to %LOCALAPPDATA%\TabularEditor\.
+#
+# Outputs the absolute path to TabularEditor.exe on stdout.
+# Exit code: 0 = installed/found; non-zero = missing or infrastructure failure.
+#
+# Used by /bi-performance and /bi-modeling for Best Practice Analyzer
+# and VertiPaq Analyzer integration.
+
+#requires -Version 7.0
+
+[CmdletBinding()]
+param(
+    [switch]$Force,
+    [switch]$Install
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Get-LocalAppDataPath {
+    $localAppData = $env:LOCALAPPDATA
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        $localAppData = [Environment]::GetFolderPath('LocalApplicationData')
+    }
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        throw 'LOCALAPPDATA is not set and LocalApplicationData could not be resolved.'
+    }
+    return $localAppData
+}
+
+function Assert-ValidAuthenticodeSignature {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$FilePath
+    )
+
+    # Get-AuthenticodeSignature is a Windows-only cmdlet. If it is unavailable we
+    # cannot verify; warn and proceed rather than blocking an otherwise-working
+    # Tabular Editor install.
+    if (-not (Get-Command Get-AuthenticodeSignature -ErrorAction SilentlyContinue)) {
+        Write-Warning "Cannot check the Authenticode signature on this platform; skipping verification for ${FilePath}."
+        return
+    }
+
+    $signature = Get-AuthenticodeSignature -FilePath $FilePath
+
+    # Explicit tampering / trust failures are fatal — never run a binary that
+    # fails these.
+    $fatalStatuses = @('HashMismatch', 'NotTrusted', 'NotSigned')
+    if ($fatalStatuses -contains $signature.Status) {
+        throw "Authenticode signature validation failed for ${FilePath}: $($signature.Status)"
+    }
+
+    # 'Valid' is the happy path. Anything else (most often 'UnknownError' when the
+    # certificate revocation servers are unreachable on offline / locked-down
+    # corporate machines) is NOT evidence of tampering, so warn and continue
+    # instead of aborting the Best Practice Analyzer run on a setup that worked
+    # before.
+    if ($signature.Status -ne 'Valid') {
+        Write-Warning "Could not fully verify the Authenticode signature for ${FilePath} (status: $($signature.Status)). This is common on offline or locked-down machines; proceeding with the existing install."
+    }
+}
+
+function Invoke-TabularEditorInstall {
+    param(
+        [switch]$Force,
+        [switch]$Install
+    )
+
+    $installDir = Join-Path (Get-LocalAppDataPath) 'TabularEditor'
+    $exePath = Join-Path $installDir 'TabularEditor.exe'
+
+    if ((Test-Path $exePath) -and -not $Force) {
+        Assert-ValidAuthenticodeSignature -FilePath $exePath
+        Write-Output $exePath
+        return
+    }
+
+    if (-not $Install) {
+        throw "Tabular Editor 2 was not found at $exePath. Ask the user for permission, then rerun this script with -Install."
+    }
+
+    Write-Host "Tabular Editor 2 was not found at $installDir." -ForegroundColor Yellow
+    Write-Host "Downloading the latest stable release from GitHub..." -ForegroundColor Yellow
+
+    # GitHub API: latest release for the official Tabular Editor 2 repo
+    $apiUrl = 'https://api.github.com/repos/TabularEditor/TabularEditor/releases/latest'
+
+    try {
+        $headers = @{ 'User-Agent' = 'bi-superpowers-installer' }
+        if ($env:GITHUB_TOKEN) {
+            $headers['Authorization'] = "Bearer $env:GITHUB_TOKEN"
+        }
+        $release = Invoke-RestMethod -Uri $apiUrl -Headers $headers -UseBasicParsing
+    }
+    catch {
+        throw "Could not query the GitHub releases API: $($_.Exception.Message). If this is a rate-limit error, set GITHUB_TOKEN and rerun."
+    }
+
+    # Pick the standard Windows ZIP. Prefer the non-portable ZIP when both assets
+    # exist because it matches the expected TabularEditor.exe layout.
+    $asset = $release.assets |
+        Where-Object { $_.name -match '\.zip$' -and $_.name -notmatch 'portable' } |
+        Select-Object -First 1
+
+    if (-not $asset) {
+        throw "No Windows ZIP asset was found in release $($release.tag_name)."
+    }
+
+    $assetUri = [System.Uri]$asset.browser_download_url
+    if (-not $assetUri.IsAbsoluteUri -or $assetUri.Scheme -ne 'https' -or $assetUri.Host -notmatch '(^|\.)github\.com$') {
+        throw "Unexpected Tabular Editor asset host: $($assetUri.Host)"
+    }
+
+    $tempZip = Join-Path $env:TEMP "TabularEditor_$([guid]::NewGuid().ToString('N')).zip"
+
+    try {
+        Invoke-WebRequest -Uri $asset.browser_download_url -OutFile $tempZip -UseBasicParsing -Headers $headers
+    }
+    catch {
+        throw "Download failed for $($asset.browser_download_url): $($_.Exception.Message)"
+    }
+
+    if (-not (Test-Path $installDir)) {
+        New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+    }
+
+    try {
+        Expand-Archive -Path $tempZip -DestinationPath $installDir -Force
+    }
+    finally {
+        Remove-Item $tempZip -Force -ErrorAction SilentlyContinue
+    }
+
+    if (-not (Test-Path $exePath)) {
+        throw "Installation completed, but $exePath was not found. Check the contents of $installDir."
+    }
+
+    Assert-ValidAuthenticodeSignature -FilePath $exePath
+
+    Write-Host "Tabular Editor 2 installed: $exePath (version $($release.tag_name))" -ForegroundColor Green
+    Write-Output $exePath
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    try {
+        Invoke-TabularEditorInstall -Force:$Force -Install:$Install
+        exit 0
+    }
+    catch {
+        [Console]::Error.WriteLine($_.Exception.Message)
+        if (-not $Install -and $_.Exception.Message -match 'was not found') {
+            exit 2
+        }
+        exit 1
+    }
+}

package/src/content/skills/bi-performance/scripts/run-bpa.ps1

@@ -0,0 +1,265 @@
+# run-bpa.ps1
+# Runs the Microsoft Best Practice Rules (BPA) against the open
+# Power BI Desktop semantic model using Tabular Editor 2 CLI.
+#
+# Auto-detects the AS port from the local PBI Desktop workspace and
+# downloads the latest BPA rules JSON from microsoft/Analysis-Services.
+#
+# Usage:
+#   pwsh run-bpa.ps1                       # default rules, autodetect port
+#   pwsh run-bpa.ps1 -RulesUrl <url>       # override rules source
+#   pwsh run-bpa.ps1 -Port 51234           # override port autodetect
+#   pwsh run-bpa.ps1 -InstallTabularEditor # install TE2 after user consent
+#
+# Output: BPA findings to stdout. Exit 0 on success (regardless of finding count),
+#         non-zero on infrastructure failure.
+
+#requires -Version 7.0
+
+[CmdletBinding()]
+param(
+    [string]$RulesUrl = 'https://raw.githubusercontent.com/microsoft/Analysis-Services/master/BestPracticeRules/BPARules.json',
+    [switch]$AllowCustomRulesUrl,
+    [int]$Port = 0,
+    [string]$Database = '',
+    [switch]$InstallTabularEditor
+)
+
+$ErrorActionPreference = 'Stop'
+$here = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+function Assert-SafeRulesUri {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$Uri,
+
+        [switch]$AllowCustomRulesUrl
+    )
+
+    $parsed = [System.Uri]$Uri
+    if (-not $parsed.IsAbsoluteUri -or $parsed.Scheme -ne 'https') {
+        throw 'RulesUrl must use HTTPS.'
+    }
+
+    if (-not $AllowCustomRulesUrl) {
+        $expectedHost = 'raw.githubusercontent.com'
+        $expectedPrefix = '/microsoft/Analysis-Services/'
+        if ($parsed.Host -ne $expectedHost -or -not $parsed.AbsolutePath.StartsWith($expectedPrefix, [System.StringComparison]::OrdinalIgnoreCase)) {
+            throw 'RulesUrl must point to Microsoft Analysis-Services on raw.githubusercontent.com unless -AllowCustomRulesUrl is provided.'
+        }
+    }
+}
+
+function Get-LocalAppDataPath {
+    $localAppData = $env:LOCALAPPDATA
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        $localAppData = [Environment]::GetFolderPath('LocalApplicationData')
+    }
+    if ([string]::IsNullOrWhiteSpace($localAppData)) {
+        throw 'LOCALAPPDATA is not set and LocalApplicationData could not be resolved.'
+    }
+    return $localAppData
+}
+
+function Get-BpaRulesCachePath {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string]$RulesUrl,
+
+        [Parameter(Mandatory = $true)]
+        [string]$CacheRoot
+    )
+
+    $sha256 = [System.Security.Cryptography.SHA256]::Create()
+    try {
+        $bytes = [System.Text.Encoding]::UTF8.GetBytes($RulesUrl.Trim())
+        $hashBytes = $sha256.ComputeHash($bytes)
+        $hash = [System.BitConverter]::ToString($hashBytes).Replace('-', '').ToLowerInvariant()
+        return Join-Path $CacheRoot "BPARules-$($hash.Substring(0, 16)).json"
+    }
+    finally {
+        $sha256.Dispose()
+    }
+}
+
+# Step 2 — Detect the live Power BI Desktop AS port (if not provided)
+function Read-PowerBIPortFile {
+    param([string]$Path)
+
+    foreach ($encoding in @('Unicode', 'Default')) {
+        $text = Get-Content $Path -Raw -Encoding $encoding -ErrorAction SilentlyContinue
+        $digits = ($text -replace '[^\d]', '')
+        $port = 0
+        # TryParse + range guard: a corrupt/oversized port file must skip this
+        # workspace gracefully, not overflow [int] and abort autodetection.
+        if ($digits -and [int]::TryParse($digits, [ref]$port) -and $port -ge 1 -and $port -le 65535) {
+            return $port
+        }
+    }
+
+    return $null
+}
+
+function Test-LocalPort {
+    param([int]$CandidatePort)
+
+    $client = [System.Net.Sockets.TcpClient]::new()
+    try {
+        $async = $client.BeginConnect('127.0.0.1', $CandidatePort, $null, $null)
+        if (-not $async.AsyncWaitHandle.WaitOne(500)) { return $false }
+        $client.EndConnect($async)
+        return $true
+    }
+    catch {
+        return $false
+    }
+    finally {
+        $client.Close()
+    }
+}
+
+function Get-PowerBIPort {
+    $localAppData = Get-LocalAppDataPath
+    $candidates = @(
+        (Join-Path $localAppData 'Microsoft\Power BI Desktop\AnalysisServicesWorkspaces\*\Data\msmdsrv.port.txt'),
+        (Join-Path $localAppData 'Microsoft\Power BI Desktop Store App\AnalysisServicesWorkspaces\*\Data\msmdsrv.port.txt')
+    )
+    $portFiles = @()
+    foreach ($pattern in $candidates) {
+        $portFiles += Get-ChildItem -Path $pattern -ErrorAction SilentlyContinue
+    }
+    if (-not $portFiles) { return $null }
+
+    $reachable = @()
+    foreach ($file in $portFiles) {
+        $candidatePort = Read-PowerBIPortFile -Path $file.FullName
+        if ($candidatePort -and (Test-LocalPort -CandidatePort $candidatePort)) {
+            $reachable += [PSCustomObject]@{
+                Port = $candidatePort
+                Path = $file.FullName
+                LastWriteTime = $file.LastWriteTime
+            }
+        }
+    }
+
+    if (-not $reachable) { return $null }
+
+    if ($reachable.Count -gt 1) {
+        $details = ($reachable | Sort-Object LastWriteTime -Descending | ForEach-Object {
+            "localhost:$($_.Port) from $($_.Path)"
+        }) -join "`n  "
+        [Console]::Error.WriteLine("Multiple active Power BI Desktop workspaces were detected. Rerun with -Port for the target instance:`n  $details")
+        exit 5
+    }
+
+    return $reachable[0].Port
+}
+
+function Invoke-BpaRun {
+    param(
+        [string]$RulesUrl,
+        [switch]$AllowCustomRulesUrl,
+        [int]$Port,
+        [string]$Database,
+        [switch]$InstallTabularEditor
+    )
+
+    # Step 1 — Resolve Tabular Editor 2 (install if missing)
+    $installScript = Join-Path $here 'install-tabular-editor.ps1'
+    $installArgs = @()
+    if ($InstallTabularEditor) {
+        $installArgs += '-Install'
+    }
+    $exePath = & $installScript @installArgs
+    if (-not $exePath -or -not (Test-Path $exePath)) {
+        [Console]::Error.WriteLine("Could not resolve TabularEditor.exe. If the user approved installation, rerun with -InstallTabularEditor.")
+        exit 1
+    }
+
+    # Step 2 — Detect the live Power BI Desktop AS port (if not provided)
+    if ($Port -eq 0) {
+        $detected = Get-PowerBIPort
+        if (-not $detected) {
+            [Console]::Error.WriteLine("No active Power BI Desktop workspace was detected. Is the .pbip open?")
+            exit 2
+        }
+        $Port = [int]$detected
+    }
+
+    Write-Host "Connecting to Power BI Desktop at localhost:$Port" -ForegroundColor Cyan
+
+    # Step 3 — Download (or cache) the BPA rules JSON
+    Assert-SafeRulesUri -Uri $RulesUrl -AllowCustomRulesUrl:$AllowCustomRulesUrl
+
+    $cacheRoot = Join-Path (Join-Path (Get-LocalAppDataPath) 'BI Superpowers') 'Cache'
+    New-Item -ItemType Directory -Force -Path $cacheRoot | Out-Null
+    $rulesPath = Get-BpaRulesCachePath -RulesUrl $RulesUrl -CacheRoot $cacheRoot
+    $cacheStale = -not (Test-Path $rulesPath) -or `
+                  ((Get-Item $rulesPath).LastWriteTime -lt (Get-Date).AddDays(-7))
+
+    if ($cacheStale) {
+        Write-Host "Downloading BPA rules from $RulesUrl..." -ForegroundColor Cyan
+        try {
+            $headers = @{ 'User-Agent' = 'bi-superpowers-bpa' }
+            if ($env:GITHUB_TOKEN) {
+                $headers['Authorization'] = "Bearer $env:GITHUB_TOKEN"
+            }
+            Invoke-WebRequest -Uri $RulesUrl -OutFile $rulesPath -UseBasicParsing -Headers $headers
+        }
+        catch {
+            [Console]::Error.WriteLine("Failed to download BPA rules: $($_.Exception.Message). If this is a rate-limit error, set GITHUB_TOKEN and rerun.")
+            exit 3
+        }
+    }
+
+    # Step 4 — Run TE2 with -A (Analyze). TE2 connects to localhost:port and
+    # auto-discovers the database when only one is present (always the case for
+    # a Power BI Desktop instance).
+    $server = "localhost:$Port"
+    $argsList = @($server)
+    if ($Database) { $argsList += $Database }
+    $argsList += @('-A', $rulesPath)
+
+    Write-Host "Running: $exePath $($argsList -join ' ')" -ForegroundColor DarkGray
+    # Capture stdout and stderr separately. TE2 writes BPA findings (and a
+    # non-zero exit) to stdout for rule violations — the *normal* audit case —
+    # while connection/CLI failures go to stderr. Merging them with 2>&1 would
+    # let a failure's stderr text masquerade as findings and exit 0.
+    $stderrFile = [System.IO.Path]::GetTempFileName()
+    try {
+        $output = & $exePath @argsList 2>$stderrFile
+        $exitCode = $LASTEXITCODE
+        $stderr = Get-Content -LiteralPath $stderrFile -Raw -ErrorAction SilentlyContinue
+    }
+    finally {
+        Remove-Item -LiteralPath $stderrFile -Force -ErrorAction SilentlyContinue
+    }
+
+    # No findings on stdout AND a non-zero exit = infrastructure failure (bad
+    # port, unsupported -A, failed AS connection). Now that stderr is captured
+    # separately, an empty stdout reliably means "no findings", so a clean
+    # zero-finding audit (exit 0) is never treated as a failure even if TE2
+    # emitted an incidental warning to stderr (surfaced as a diagnostic below).
+    if ([string]::IsNullOrWhiteSpace($output) -and $exitCode -ne 0) {
+        $detail = if ([string]::IsNullOrWhiteSpace($stderr)) { 'no output' } else { $stderr.Trim() }
+        [Console]::Error.WriteLine("TE2 failed (exit code $exitCode) connecting to localhost:$Port. $detail")
+        exit 4
+    }
+
+    # Surface any stderr as a diagnostic without letting it pollute the findings.
+    if (-not [string]::IsNullOrWhiteSpace($stderr)) {
+        [Console]::Error.WriteLine($stderr.Trim())
+    }
+
+    Write-Output $output
+    exit 0
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    Invoke-BpaRun `
+        -RulesUrl $RulesUrl `
+        -AllowCustomRulesUrl:$AllowCustomRulesUrl `
+        -Port $Port `
+        -Database $Database `
+        -InstallTabularEditor:$InstallTabularEditor
+}

package/src/content/skills/bi-powerquery/SKILL.md

@@ -0,0 +1,202 @@
+# 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.