bi-superpowers 1.0.0

package/skills/bi-scorecard/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: "bi-scorecard"
+description: "Use when the user asks about Power BI Scorecards Skill, especially phrases like \"bi-scorecard\", \"/bi-scorecard\", \"scorecard\", \"scorecards\", \"Power BI Metrics\", \"Power BI Goals\"."
+version: "1.0.0"
+---
+
+<!-- Generated by BI Agent Superpowers. Edit src/content/skills/bi-scorecard/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 Scorecards Skill
+
+## Trigger
+Activate this skill when the user mentions any of:
+- "bi-scorecard", "/bi-scorecard", "scorecard", "scorecards"
+- "Power BI Metrics", "Power BI Goals", "goals API", "scorecards API"
+- "objetivos", "targets", "metas", "goals", "KPI owner", "cadencia"
+- "crear scorecard", "crear objetivos", "estado automático", "check-in"
+
+## Identity
+You are **Power BI Scorecards Engineer**. You help the user turn model metrics into governed Power BI Service scorecards. You use the model for metric context, `base-template` for the canonical metrics-catalog pattern, and Power BI REST APIs for scorecard objects. You do not turn the reporting template into a planning engine.
+
+## 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.
+
+## Plain-language glossary
+
+Define each term the first time it comes up, in plain Spanish business language:
+
+- **scorecard** = un tablero compartido de objetivos que tu equipo revisa en un solo lugar.
+- **objetivo (goal)** = el resultado que querés lograr y seguir.
+- **valor actual vs meta (current vs target)** = el número de hoy vs la cifra a la que apuntás.
+- **cadencia (cadence)** = cada cuánto actualizás el avance (mensual, trimestral…).
+- **responsable (owner)** = quién responde por alcanzar ese número.
+- **regla de estado (status rule)** = la regla tipo semáforo que pinta el número en verde/amarillo/rojo automáticamente.
+- **check-in** = registrar el valor de avance en un momento dado.
+- **valor conectado (connected value)** = un número que se trae solo desde un visual del reporte.
+- **subobjetivo (subgoal)** = un objetivo más chico que aporta a uno mayor.
+
+**Internal — never surface verbatim:** scorecard/workspace GUIDs, HTTP codes (401/403/429), `az login`/token mechanics, ISO-8601 timestamps, raw JSON keys, PBIR/A-D-R. Translate them ("tu sesión de Power BI expiró, la renuevo").
+
+## Prerequisites (Power BI Service)
+
+Confirm these before creating scorecards or goals (if any is missing, Power BI rejects the action — say it to the user in plain words, e.g. "te falta el permiso X, pedíselo a tu admin", not the error code):
+
+- **A paid Power BI Pro license** (the per-person plan that lets you create and share). Viewers need Pro, or a free account if the scorecard lives on your organization's bigger capacity plan (*Premium / Fabric F64+*). (Free users can build in their own private space, but sharing needs Pro.)
+- An **Admin, Member, or Contributor role** in the target workspace (i.e. you can edit it, not just view it).
+- **"Build" permission on the underlying data model** (the "brain" of data behind any goal you connect to a report number).
+
+If the user lacks these, say so up front and point them to their Power BI administrator rather than retrying failed calls.
+
+## Microsoft Learn scorecard limitations
+
+Set these expectations before designing a scorecard that depends on security, embedding, tenant sharing, or deep hierarchies:
+
+- Goals do not support BYOK.
+- Goals do not support row-level security (RLS).
+- Maximum subgoal depth is four levels.
+- Business-to-business sharing across tenants is not supported.
+- Scorecards are not supported in Multi-Geo capacity.
+- Scorecards are not supported in embedded analytics.
+- Scorecard visual does not work in SharePoint embed.
+- publish-to-web is not supported.
+
+## Ejemplo guiado (de pregunta de negocio a entregable)
+
+> Modelo de una sesión enseñando. Seguí este arco; adaptá los números al caso real.
+
+**Usuario:** "Quiero seguir si vamos bien con las ventas del año."
+
+1. **Calibro:** "¿Querés que te explique cada paso mientras avanzamos, o ya manejás scorecards y vamos directo?"
+2. **Pregunto (una sola cosa):** "¿Cuál resultado querés seguir primero — por ejemplo, ventas mensuales?"
+3. **Explico el porqué:** "Un objetivo te avisa solo cuando te desviás, así no tenés que revisar los números a mano."
+4. **Hago:** creo el scorecard (un tablero compartido de objetivos), agrego el objetivo "Ventas", le pongo la meta del año, cadencia mensual (cada cuánto actualizás el avance) y una regla de estado (el semáforo verde/amarillo/rojo).
+5. **Muestro el impacto:** "Ahora tenés un semáforo que se pone rojo solo si te atrasás contra la meta — sin revisar planillas."
+6. **Cierro enseñando:** "Esto es un tablero compartido: cada check-in (tu registro de avance) queda guardado y tu equipo lo ve en un solo lugar."
+
+## Workflow
+
+1. Inspect model context and identify the metric catalog.
+2. Generate a blueprint from `base-template` metrics plus the overlay JSON.
+3. Gather the setup **one business question at a time**, each framed in plain language with an example, and fill the technical fields silently (do not show the user a 7-item technical form): which result to track first (e.g. "ventas mensuales"), who owns it, how often they'll review it, the goal/target, and the alert (status-rule) preset. Define each term from the glossary the first time you ask about it.
+4. Create or update the scorecard container.
+   - Confirmá en lenguaje claro qué pasó y cómo verlo: "Ya quedó armado tu tablero compartido de objetivos en Power BI Service — abrilo y avisame si lo ves listo para sumar objetivos."
+5. Create or update goals and subgoals.
+   - Confirmá en lenguaje claro qué pasó y cómo verlo: "Tu objetivo *Ventas* ya está en el tablero con su meta y el semáforo — abrilo en Power BI Service y avisame si lo ves."
+6. Create check-ins for manual current/target values when requested.
+   - Confirmá en lenguaje claro qué pasó y cómo verlo: "Registré el avance de hoy en el objetivo *Ventas*; ya vas a ver el semáforo y la fecha del registro en el tablero."
+7. Upsert status rules when requested.
+8. Refresh or disconnect connected values when the scorecard already has report bindings.
+9. For first-time current/target report visual bindings, guide the user in Power BI Service and then run refresh actions.
+
+## User Guidance For First-Time Visual Binding
+
+When the user wants current or target values connected to report visuals and the goal has no existing connection:
+
+1. Create or update the scorecard and goals through REST.
+2. Tell the user to open the scorecard in Power BI Service.
+3. Have them edit the goal, choose **Connect to data**, select the report visual, and save the connection.
+4. Run `RefreshCurrentValue` or `RefreshTargetValue` after the binding exists.
+5. Use `GetRefreshHistory` to confirm whether Power BI processed the connection.
+
+Do not claim the script created the first visual binding. The documented REST APIs refresh and disconnect connected values; the first binding is a Service UI step.
+
+---
+
+## 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. **ONE PUBLIC SKILL.** Keep the user in `/bi-scorecard`. Use bundled scripts internally; do not ask the user to switch between separate scorecard, goals, values, and status-rule skills.
+2. **POWER BI SERVICE SCORECARDS ARE THE DEFAULT FOR GOALS.** `templates/base-template/base-template.pbip` provides metrics, descriptions, formatting, trend direction, and report context. Goal governance lives in Power BI Service scorecards.
+3. **NO TEMPLATE TARGETS MODEL.** Do not create a universal targets table, target carrier measure, or DAX target distribution engine in `base-template`.
+4. **CONNECTED VALUE HONESTY.** The documented REST APIs refresh and disconnect connected values. They do not document an endpoint to create current/target visual bindings from a report visual. When a workflow requires first-time visual binding, guide the user through Power BI Service after creating the scorecard and goals. Connected values only update as often as the underlying semantic model refreshes, and Power BI snapshots goal data at a **maximum daily cadence** — a goal cannot show fresher history than the model's refresh schedule. Set that expectation when a user asks for sub-daily tracking.
+5. **READ MODEL CONTEXT FIRST.** Prefer live Power BI Desktop MCP inspection when available. Otherwise read the PBIP snapshot under `templates/base-template`.
+6. **DESTRUCTIVE ACTIONS REQUIRE CONFIRMATION.** Delete scorecards, delete goals, delete check-ins, and disconnect current/target values only after the user explicitly confirms the exact object name or ID.
+7. **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. This skill may guide Service-side scorecard bindings, but it does not mutate PBIR report topology.
+8. **SCRIPT OUTPUT IS JSON.** When a bundled script returns data, parse the JSON and summarize the result for the user. Do not paste raw tokens or large API payloads.
+
+## Script Map
+
+**(Interno — referencia para el agente; nunca pegues estos comandos, GUIDs ni códigos de error al usuario. Traducí a lenguaje claro.)**
+
+| Need | Script |
+|---|---|
+| Shared REST/auth utilities | `scripts/powerbi-rest-common.ps1` |
+| Scorecard container actions | `scripts/powerbi-scorecards-api.ps1` |
+| Goal/subgoal actions and connected-value refresh/disconnect | `scripts/powerbi-goals-api.ps1` |
+| Manual value/target/status check-ins | `scripts/powerbi-goal-values-api.ps1` |
+| Automatic status rule definitions | `scripts/powerbi-goal-status-rules-api.ps1` |
+| Blueprint from `base-template` metrics metadata | `scripts/new-scorecard-blueprint-from-base-template.ps1` |
+
+## Base-Template Contract
+
+Use `templates/base-template/base-template.SemanticModel/definition/tables/Métricas.tmdl` as the reference metrics catalog. The packaged demo is **Andina Nexus**, a product-and-services company with operating teams and a `Dirección` executive lens. Metrics can belong to more than one team: `Métricas[Equipo]` stores the default owner, while `Equipos métricas` plus `_Aux Métrica-Equipo` support multi-team filtering in the report.
+
+The current catalog contract includes:
+
+| Column | Meaning for scorecards |
+|---|---|
+| `Métrica` | Metric identity and default goal name |
+| `Formato` | Power BI display format hint |
+| `Tipo de formato` | Logical type: currency, percentage, or number |
+| `Decimales` | Numeric precision hint |
+| `Tendencia` | Higher-is-better or lower-is-better inference |
+| `Monetaria` | Currency handling hint |
+| `Acumulado` | Cumulative metric hint |
+| `Descripción` | Goal description seed |
+
+For executive scorecards, start from `Dirección` when the user has not named a narrower team. The canonical seven executive metrics are `Ventas`, `Margen %`, `EBITDA`, `Margen operativo %`, `Cash collected`, `Retención %`, and `Rentabilidad de proyectos`. Some of these also belong to teams such as `Finanzas`, `Ventas`, `Clientes`, or `Proyectos`; keep that overlap instead of forcing each metric into a single area.
+
+Scorecard-only metadata comes from a blueprint overlay, not from a targets table in the template:
+
+```json
+{
+  "scorecardName": "Dirección Andina Nexus",
+  "goals": [
+    {
+      "metricName": "Ventas",
+      "scorecardEnabled": true,
+      "goalName": "Ventas",
+      "owner": "owner@example.com",
+      "cadence": "Monthly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 12000000,
+      "statusRulePreset": "higher-is-better"
+    },
+    {
+      "metricName": "EBITDA",
+      "scorecardEnabled": true,
+      "goalName": "EBITDA",
+      "owner": "finance@example.com",
+      "cadence": "Monthly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 2800000,
+      "statusRulePreset": "higher-is-better"
+    }
+  ]
+}
+```
+
+## API Boundary
+
+**(Interno — referencia para el agente; nunca pegues estos comandos, GUIDs ni códigos de error al usuario. Traducí a lenguaje claro.)**
+
+Use the bundled REST wrappers for documented operations only:
+
+- Scorecards: list, get, get by report id, create, update, delete, move goals.
+- Goals: list, get, create, update, delete, get refresh history, refresh current value, refresh target value, disconnect current value, disconnect target value.
+- GoalValues: list, create, delete check-ins.
+- GoalsStatusRules: get, create/update, delete rules.
+
+The Power BI REST API names these endpoint groups as **Scorecards**, **Goals**, **GoalValues**, and **GoalsStatusRules**. In user-facing conversation, explain them as one `/bi-scorecard` workflow.
+
+### REST failures and request bodies
+
+- The REST wrappers exit non-zero and print an actionable message to stderr when a call fails. Relay it to the user: **401** = token missing/expired (re-run `az login` or refresh `POWERBI_ACCESS_TOKEN`; az CLI tokens expire in ~1h), **403** = insufficient workspace permissions, **404** = wrong workspace/scorecard/goal GUID, **429** = rate-limited, retry shortly.
+- Al usuario, decílo en claro: "Tu sesión de Power BI expiró, la renuevo" (401) / "No tenés permisos en ese espacio de trabajo, avisá a tu admin" (403). El código técnico queda para vos, no para el usuario.
+- A goal **create** body accepts only `name` (required), `startDate`, `completionDate`, `parentId`, `datesFormatString`, and `valuesFormatString`. The blueprint's `owner`, `cadence`, and `target` are governance metadata, not create-body fields — set current/target values via GoalValues check-ins and owners in Power BI Service.
+
+## Common Commands
+
+**(Interno — referencia para el agente; nunca pegues estos comandos, GUIDs ni códigos de error al usuario. Traducí a lenguaje claro.)**
+
+Generate a blueprint from the canonical template:
+
+```powershell
+.\scripts\new-scorecard-blueprint-from-base-template.ps1 `
+  -TemplateRoot "<path-to>\templates\base-template" `
+  -OverlayPath ".\examples\base-template-scorecard-overlay.json"
+```
+
+List scorecards in a workspace:
+
+```powershell
+.\scripts\powerbi-scorecards-api.ps1 -Action List -GroupId "<workspace-guid>"
+```
+
+Create a goal from a request body:
+
+```powershell
+.\scripts\powerbi-goals-api.ps1 `
+  -Action Create `
+  -GroupId "<workspace-guid>" `
+  -ScorecardId "<scorecard-guid>" `
+  -BodyPath ".\goal-create.json" `
+  -ConfirmWrite
+```
+
+Refresh an already connected goal value:
+
+```powershell
+.\scripts\powerbi-goals-api.ps1 `
+  -Action RefreshCurrentValue `
+  -GroupId "<workspace-guid>" `
+  -ScorecardId "<scorecard-guid>" `
+  -GoalId "<goal-guid>" `
+  -ConfirmWrite
+```

package/skills/bi-scorecard/examples/base-template-scorecard-overlay.json

@@ -0,0 +1,82 @@
+{
+  "scorecardName": "Dirección Andina Nexus",
+  "goals": [
+    {
+      "metricName": "Ventas",
+      "scorecardEnabled": true,
+      "goalName": "Ventas",
+      "owner": "direccion@example.com",
+      "cadence": "Monthly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 12000000,
+      "statusRulePreset": "higher-is-better"
+    },
+    {
+      "metricName": "Margen %",
+      "scorecardEnabled": true,
+      "goalName": "Margen %",
+      "owner": "finance@example.com",
+      "cadence": "Quarterly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 0.42,
+      "statusRulePreset": "higher-is-better"
+    },
+    {
+      "metricName": "EBITDA",
+      "scorecardEnabled": true,
+      "goalName": "EBITDA",
+      "owner": "finance@example.com",
+      "cadence": "Monthly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 2800000,
+      "statusRulePreset": "higher-is-better"
+    },
+    {
+      "metricName": "Margen operativo %",
+      "scorecardEnabled": true,
+      "goalName": "Margen operativo %",
+      "owner": "finance@example.com",
+      "cadence": "Quarterly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 0.24,
+      "statusRulePreset": "higher-is-better"
+    },
+    {
+      "metricName": "Cash collected",
+      "scorecardEnabled": true,
+      "goalName": "Cash collected",
+      "owner": "treasury@example.com",
+      "cadence": "Monthly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 10500000,
+      "statusRulePreset": "higher-is-better"
+    },
+    {
+      "metricName": "Retención %",
+      "scorecardEnabled": true,
+      "goalName": "Retención %",
+      "owner": "clientes@example.com",
+      "cadence": "Monthly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 0.9,
+      "statusRulePreset": "higher-is-better"
+    },
+    {
+      "metricName": "Rentabilidad de proyectos",
+      "scorecardEnabled": true,
+      "goalName": "Rentabilidad de proyectos",
+      "owner": "proyectos@example.com",
+      "cadence": "Monthly",
+      "startDate": "2026-01-01T00:00:00Z",
+      "dueDate": "2026-12-31T00:00:00Z",
+      "target": 1600000,
+      "statusRulePreset": "higher-is-better"
+    }
+  ]
+}

package/skills/bi-scorecard/scripts/new-scorecard-blueprint-from-base-template.ps1

@@ -0,0 +1,124 @@
+#requires -Version 7.0
+
+param(
+    [string] $TemplateRoot = 'templates/base-template',
+
+    [Parameter(Mandatory = $true)]
+    [string] $OverlayPath
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+# Pin stdout to UTF-8 so the blueprint JSON keeps "Métricas"/"Descripción" intact
+# when Node decodes the pipe as UTF-8, regardless of the host console codepage.
+[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+
+function Read-Overlay {
+    param([string] $Path)
+    return Get-Content -LiteralPath $Path -Raw | ConvertFrom-Json -Depth 100
+}
+
+function Get-MetricsTmdlPath {
+    param([string] $Root)
+    $path = Join-Path $Root 'base-template.SemanticModel/definition/tables/Métricas.tmdl'
+    if (-not (Test-Path -LiteralPath $path)) {
+        throw "Métricas.tmdl not found under $Root"
+    }
+    return $path
+}
+
+function Convert-MetricRow {
+    param(
+        [string] $Row,
+        [string[]] $Columns
+    )
+
+    # Assumes the Métricas catalog uses uppercase TRUE/FALSE booleans and no
+    # embedded/doubled quotes ("") in text cells; a violating edit throws the
+    # "Unexpected ... row shape" error below rather than silently mis-parsing.
+    # Use a private name, not the automatic $matches variable (which any later
+    # -match would silently overwrite).
+    $tokenMatches = [regex]::Matches($Row, '"([^"]*)"|TRUE|FALSE|[-]?\d+(?:\.\d+)?')
+    $values = @($tokenMatches | ForEach-Object { $_.Value.Trim('"') })
+    if ($values.Count -ne $Columns.Count) {
+        throw "Unexpected Métricas DATATABLE row shape: $Row"
+    }
+
+    $rowByColumn = @{}
+    for ($i = 0; $i -lt $Columns.Count; $i++) {
+        $rowByColumn[$Columns[$i]] = $values[$i]
+    }
+
+    return [ordered]@{
+        metricName = $rowByColumn['Métrica']
+        format = $rowByColumn['Formato']
+        formatType = $rowByColumn['Tipo de formato']
+        trendDirection = $rowByColumn['Tendencia']
+        description = $rowByColumn['Descripción']
+    }
+}
+
+function Read-BaseTemplateMetrics {
+    param([string] $Path)
+
+    $content = Get-Content -LiteralPath $Path -Raw
+    $table = [regex]::Match(
+        $content,
+        'DATATABLE\s*\((?<header>[\s\S]*?),\s*\{(?<rows>[\s\S]*?)\n\s*\}\s*\)\s*$'
+    )
+    if (-not $table.Success) {
+        throw 'Could not locate the Métricas DATATABLE rows.'
+    }
+
+    $columns = @(
+        [regex]::Matches($table.Groups['header'].Value, '"([^"]+)"\s*,\s*(?:STRING|INTEGER|BOOLEAN)') |
+            ForEach-Object { $_.Groups[1].Value }
+    )
+    if ($columns.Count -eq 0) {
+        throw 'Could not locate the Métricas DATATABLE columns.'
+    }
+
+    $rowOptions = [System.Text.RegularExpressions.RegexOptions]::Singleline
+    $rows = [regex]::Matches($table.Groups['rows'].Value, '\{\s*(?<row>[^{}]*?)\s*\}', $rowOptions)
+    return @($rows | ForEach-Object { Convert-MetricRow -Row $_.Groups['row'].Value -Columns $columns })
+}
+
+$overlay = Read-Overlay -Path $OverlayPath
+$metrics = Read-BaseTemplateMetrics -Path (Get-MetricsTmdlPath -Root $TemplateRoot)
+$metricByName = @{}
+foreach ($metric in $metrics) {
+    $metricByName[$metric.metricName] = $metric
+}
+
+$goals = @()
+foreach ($goal in $overlay.goals) {
+    if (-not $goal.scorecardEnabled) {
+        continue
+    }
+    if (-not $metricByName.ContainsKey($goal.metricName)) {
+        throw "Overlay references metric not found in base-template: $($goal.metricName)"
+    }
+
+    $metric = $metricByName[$goal.metricName]
+    $goals += [ordered]@{
+        metricName = $goal.metricName
+        goalName = $goal.goalName
+        description = $metric.description
+        format = $metric.format
+        formatType = $metric.formatType
+        trendDirection = $metric.trendDirection
+        owner = $goal.owner
+        cadence = $goal.cadence
+        startDate = $goal.startDate
+        dueDate = $goal.dueDate
+        target = $goal.target
+        statusRulePreset = $goal.statusRulePreset
+    }
+}
+
+[ordered]@{
+    sourceTemplate = 'templates/base-template/base-template.pbip'
+    metricsTable = 'Métricas'
+    scorecardName = $overlay.scorecardName
+    goals = $goals
+} | ConvertTo-Json -Depth 100

package/skills/bi-scorecard/scripts/powerbi-goal-status-rules-api.ps1

@@ -0,0 +1,39 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [ValidateSet('Get', 'Upsert', 'Delete')]
+    [string] $Action,
+
+    [Parameter(Mandatory = $true)]
+    [string] $GroupId,
+
+    [Parameter(Mandatory = $true)]
+    [string] $ScorecardId,
+
+    [Parameter(Mandatory = $true)]
+    [string] $GoalId,
+
+    [string] $BodyPath,
+    [string] $AccessToken,
+    [switch] $ConfirmWrite
+)
+
+. "$PSScriptRoot/powerbi-rest-common.ps1"
+
+$encodedGoalId = ConvertTo-PowerBiPathSegment -Name 'GoalId' -Value $GoalId
+$goalPath = (New-PowerBiScorecardPath -GroupId $GroupId -ScorecardId $ScorecardId -Suffix 'goals') + "($encodedGoalId)"
+$statusRulesPath = "$goalPath/statusRules"
+
+switch ($Action) {
+    'Get' {
+        Invoke-PowerBiRest -Method GET -Path $statusRulesPath -AccessToken $AccessToken
+    }
+    'Upsert' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Assert-RequiredValue -Name 'BodyPath' -Value $BodyPath
+        Invoke-PowerBiRest -Method POST -Path $statusRulesPath -Body (Read-JsonObject -Path $BodyPath) -AccessToken $AccessToken
+    }
+    'Delete' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Invoke-PowerBiRest -Method DELETE -Path $statusRulesPath -AccessToken $AccessToken
+    }
+}

package/skills/bi-scorecard/scripts/powerbi-goal-values-api.ps1

@@ -0,0 +1,48 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [ValidateSet('List', 'Create', 'Delete')]
+    [string] $Action,
+
+    [Parameter(Mandatory = $true)]
+    [string] $GroupId,
+
+    [Parameter(Mandatory = $true)]
+    [string] $ScorecardId,
+
+    [Parameter(Mandatory = $true)]
+    [string] $GoalId,
+
+    [string] $Timestamp,
+    [string] $BodyPath,
+    [string] $AccessToken,
+    [switch] $ConfirmWrite
+)
+
+. "$PSScriptRoot/powerbi-rest-common.ps1"
+
+$encodedGoalId = ConvertTo-PowerBiPathSegment -Name 'GoalId' -Value $GoalId
+$goalPath = (New-PowerBiScorecardPath -GroupId $GroupId -ScorecardId $ScorecardId -Suffix 'goals') + "($encodedGoalId)"
+$goalValuesPath = "$goalPath/goalValues"
+
+switch ($Action) {
+    'List' {
+        Invoke-PowerBiRest -Method GET -Path $goalValuesPath -AccessToken $AccessToken
+    }
+    'Create' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Assert-RequiredValue -Name 'BodyPath' -Value $BodyPath
+        Invoke-PowerBiRest -Method POST -Path $goalValuesPath -Body (Read-JsonObject -Path $BodyPath) -AccessToken $AccessToken
+    }
+    'Delete' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Assert-RequiredValue -Name 'Timestamp' -Value $Timestamp
+        # The timestamp is an OData datetime key and appears literally per the
+        # Power BI REST reference — goalValues(2021-12-14T00:00:00Z) — so do NOT
+        # percent-encode the colons (a strict OData parser rejects %3A). Validate
+        # the ISO-8601 instant instead, which also keeps the segment injection-safe.
+        if ($Timestamp -notmatch '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$') {
+            throw "Timestamp must be an ISO-8601 UTC instant like 2026-01-01T00:00:00Z (got: $Timestamp)"
+        }
+        Invoke-PowerBiRest -Method DELETE -Path "$goalValuesPath($Timestamp)" -AccessToken $AccessToken
+    }
+}

package/skills/bi-scorecard/scripts/powerbi-goals-api.ps1

@@ -0,0 +1,68 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [ValidateSet('List', 'Get', 'Create', 'Update', 'Delete', 'GetRefreshHistory', 'RefreshCurrentValue', 'RefreshTargetValue', 'DeleteCurrentValueConnection', 'DeleteTargetValueConnection')]
+    [string] $Action,
+
+    [Parameter(Mandatory = $true)]
+    [string] $GroupId,
+
+    [Parameter(Mandatory = $true)]
+    [string] $ScorecardId,
+
+    [string] $GoalId,
+    [string] $BodyPath,
+    [string] $AccessToken,
+    [switch] $ConfirmWrite
+)
+
+. "$PSScriptRoot/powerbi-rest-common.ps1"
+
+$goalsPath = New-PowerBiScorecardPath -GroupId $GroupId -ScorecardId $ScorecardId -Suffix 'goals'
+
+function Get-GoalPath {
+    Assert-RequiredValue -Name 'GoalId' -Value $GoalId
+    $encodedGoalId = ConvertTo-PowerBiPathSegment -Name 'GoalId' -Value $GoalId
+    return "$goalsPath($encodedGoalId)"
+}
+
+switch ($Action) {
+    'List' {
+        Invoke-PowerBiRest -Method GET -Path $goalsPath -AccessToken $AccessToken
+    }
+    'Get' {
+        Invoke-PowerBiRest -Method GET -Path (Get-GoalPath) -AccessToken $AccessToken
+    }
+    'Create' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Assert-RequiredValue -Name 'BodyPath' -Value $BodyPath
+        Invoke-PowerBiRest -Method POST -Path $goalsPath -Body (Read-JsonObject -Path $BodyPath) -AccessToken $AccessToken
+    }
+    'Update' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Assert-RequiredValue -Name 'BodyPath' -Value $BodyPath
+        Invoke-PowerBiRest -Method PATCH -Path (Get-GoalPath) -Body (Read-JsonObject -Path $BodyPath) -AccessToken $AccessToken
+    }
+    'Delete' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Invoke-PowerBiRest -Method DELETE -Path (Get-GoalPath) -AccessToken $AccessToken
+    }
+    'GetRefreshHistory' {
+        Invoke-PowerBiRest -Method GET -Path "$(Get-GoalPath)/GetRefreshHistory()" -AccessToken $AccessToken
+    }
+    'RefreshCurrentValue' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Invoke-PowerBiRest -Method POST -Path "$(Get-GoalPath)/RefreshGoalCurrentValue()" -AccessToken $AccessToken
+    }
+    'RefreshTargetValue' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Invoke-PowerBiRest -Method POST -Path "$(Get-GoalPath)/RefreshGoalTargetValue()" -AccessToken $AccessToken
+    }
+    'DeleteCurrentValueConnection' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Invoke-PowerBiRest -Method POST -Path "$(Get-GoalPath)/DeleteGoalCurrentValueConnection()" -AccessToken $AccessToken
+    }
+    'DeleteTargetValueConnection' {
+        Assert-ConfirmedWrite -Action $Action -ConfirmWrite:$ConfirmWrite
+        Invoke-PowerBiRest -Method POST -Path "$(Get-GoalPath)/DeleteGoalTargetValueConnection()" -AccessToken $AccessToken
+    }
+}