@@ -0,0 +1,169 @@
+name: Power BI connector
+
+on:
+  pull_request:
+    paths:
+      - "automation/powerbi/**"
+      - ".github/workflows/powerbi-connector.yml"
+  push:
+    branches: [main]
+    paths:
+      - "automation/powerbi/**"
+    tags:
+      - "powerbi-v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Check tag matches connector version
+        if: startsWith(github.ref, 'refs/tags/powerbi-v')
+        shell: pwsh
+        run: |
+          $pq = Get-Content automation/powerbi/connector/CisoAssistant.pq -Raw
+          if ($pq -notmatch '\[Version = "(\d+\.\d+\.\d+)"\]') { throw "no [Version] attribute in CisoAssistant.pq" }
+          $version = $Matches[1]
+          $tag = $env:GITHUB_REF_NAME -replace '^powerbi-v', ''
+          if ($version -ne $tag) { throw "tag $env:GITHUB_REF_NAME does not match connector [Version = `"$version`"]" }
+
+      - name: Build .mez (zip of connector sources)
+        shell: pwsh
+        run: |
+          $connector = "automation/powerbi/connector"
+          $staging = "obj/mez"
+          New-Item -ItemType Directory -Force -Path $staging, "dist" | Out-Null
+          Copy-Item "$connector/CisoAssistant.pq", "$connector/resources.resx", "$connector/*.png" -Destination $staging
+          Compress-Archive -Path "$staging/*" -DestinationPath "dist/CisoAssistant.zip" -Force
+          Move-Item "dist/CisoAssistant.zip" "dist/CisoAssistant.mez"
+
+      - name: Install Power Query SDK tools
+        shell: pwsh
+        run: |
+          # Version-pinned: this tool is handed the signing certificate, so
+          # "latest" is a supply-chain risk. Bump deliberately (and re-check
+          # the binding-redirect patch below still applies).
+          nuget install Microsoft.PowerQuery.SdkTools -Version 2.155.2 -OutputDirectory sdktools -NonInteractive
+          $makepqx = Get-ChildItem -Path sdktools -Recurse -Filter MakePQX.exe | Select-Object -First 1
+          if (-not $makepqx) { throw "MakePQX.exe not found" }
+          Add-Content $env:GITHUB_ENV "MAKEPQX=$($makepqx.FullName)"
+
+      # SdkTools 2.155.2 ships MakePQX.exe.config without binding redirects
+      # for the System.Text.Json dependency chain, so `MakePQX verify`
+      # crashes (FileLoadException on System.Threading.Tasks.Extensions)
+      # while printing its report. Generate the redirects from the DLLs
+      # actually present in the tools folder.
+      - name: Patch MakePQX binding redirects
+        shell: pwsh
+        run: |
+          $toolsDir = Split-Path $env:MAKEPQX
+          $configPath = "$env:MAKEPQX.config"
+          [xml]$cfg = if (Test-Path $configPath) { Get-Content $configPath -Raw } else { "<configuration />" }
+          $ns = "urn:schemas-microsoft-com:asm.v1"
+          $nsm = New-Object System.Xml.XmlNamespaceManager($cfg.NameTable)
+          $nsm.AddNamespace("a", $ns)
+          $runtime = $cfg.SelectSingleNode("/configuration/runtime")
+          if (-not $runtime) { $runtime = $cfg.DocumentElement.AppendChild($cfg.CreateElement("runtime")) }
+          $ab = $runtime.SelectSingleNode("a:assemblyBinding", $nsm)
+          if (-not $ab) { $ab = $runtime.AppendChild($cfg.CreateElement("assemblyBinding", $ns)) }
+          $names = @(
+            "System.Threading.Tasks.Extensions", "System.Runtime.CompilerServices.Unsafe",
+            "System.Memory", "System.Buffers", "System.Numerics.Vectors",
+            "System.Text.Json", "System.Text.Encodings.Web", "Microsoft.Bcl.AsyncInterfaces"
+          )
+          foreach ($name in $names) {
+            $dll = Join-Path $toolsDir "$name.dll"
+            if (-not (Test-Path $dll)) { continue }
+            $an = [Reflection.AssemblyName]::GetAssemblyName($dll)
+            $token = -join ($an.GetPublicKeyToken() | ForEach-Object { $_.ToString("x2") })
+            foreach ($old in @($ab.SelectNodes("a:dependentAssembly[a:assemblyIdentity/@name='$name']", $nsm))) {
+              $ab.RemoveChild($old) | Out-Null
+            }
+            $da = $ab.AppendChild($cfg.CreateElement("dependentAssembly", $ns))
+            $ai = $da.AppendChild($cfg.CreateElement("assemblyIdentity", $ns))
+            $ai.SetAttribute("name", $name)
+            $ai.SetAttribute("publicKeyToken", $token)
+            $ai.SetAttribute("culture", "neutral")
+            $br = $da.AppendChild($cfg.CreateElement("bindingRedirect", $ns))
+            $br.SetAttribute("oldVersion", "0.0.0.0-$($an.Version)")
+            $br.SetAttribute("newVersion", $an.Version.ToString())
+            Write-Host "redirect: $name -> $($an.Version) ($token)"
+          }
+          $cfg.Save($configPath)
+
+      - name: Pack .pqx
+        shell: pwsh
+        run: |
+          & $env:MAKEPQX pack -mz "dist/CisoAssistant.mez" -t "dist/CisoAssistant.pqx"
+          if ($LASTEXITCODE -ne 0) { throw "MakePQX pack failed ($LASTEXITCODE)" }
+          if (-not (Test-Path "dist/CisoAssistant.pqx")) { throw "pack produced no .pqx" }
+
+      - name: Check signing secrets
+        id: signing
+        shell: pwsh
+        env:
+          PBI_SIGNING_CERT: ${{ secrets.PBI_SIGNING_CERT }}
+        run: |
+          if ([string]::IsNullOrEmpty($env:PBI_SIGNING_CERT)) {
+            Add-Content $env:GITHUB_OUTPUT "enabled=false"
+          } else {
+            Add-Content $env:GITHUB_OUTPUT "enabled=true"
+          }
+
+      - name: Sign and verify .pqx
+        if: steps.signing.outputs.enabled == 'true' && github.event_name != 'pull_request'
+        shell: pwsh
+        env:
+          PBI_SIGNING_CERT: ${{ secrets.PBI_SIGNING_CERT }}
+          PBI_SIGNING_PASSWORD: ${{ secrets.PBI_SIGNING_PASSWORD }}
+        run: |
+          $pfx = Join-Path $env:RUNNER_TEMP "signing.pfx"
+          [IO.File]::WriteAllBytes($pfx, [Convert]::FromBase64String($env:PBI_SIGNING_CERT))
+          & $env:MAKEPQX sign "dist/CisoAssistant.pqx" --certificate $pfx --password $env:PBI_SIGNING_PASSWORD --replace
+          $signExit = $LASTEXITCODE
+          Remove-Item $pfx
+          if ($signExit -ne 0) { throw "MakePQX sign failed ($signExit)" }
+          & $env:MAKEPQX verify "dist/CisoAssistant.pqx"
+          if ($LASTEXITCODE -ne 0) { throw "MakePQX verify failed ($LASTEXITCODE)" }
+
+      - name: Check artifacts exist
+        shell: pwsh
+        run: |
+          foreach ($f in "dist/CisoAssistant.mez", "dist/CisoAssistant.pqx") {
+            if (-not (Test-Path $f) -or (Get-Item $f).Length -eq 0) { throw "missing or empty artifact: $f" }
+          }
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: powerbi-connector
+          path: |
+            dist/CisoAssistant.mez
+            dist/CisoAssistant.pqx
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/powerbi-v')
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: powerbi-connector
+          path: dist
+      - name: Publish release assets
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          tag="${GITHUB_REF_NAME}"
+          gh release view "$tag" >/dev/null 2>&1 || gh release create "$tag" --title "Power BI connector $tag" --generate-notes
+          gh release upload "$tag" dist/CisoAssistant.mez dist/CisoAssistant.pqx --clobber
@@ -34,3 +34,9 @@ backend.ps1
 backend/.win_native_dev_runserver.py
 # > Tools
 tools/convert_library_v2.bat
+
+# > Power BI (working files embed instance data; only the .pbit template ships)
+automation/powerbi/**/*.pbix
+automation/powerbi/connector/bin/
+automation/powerbi/connector/obj/
+*.pfx
@@ -0,0 +1,135 @@
+# Developing the Power BI connector
+
+## Layout
+
+```text
+automation/powerbi/
+├── DESIGN.md            # architecture decisions — read first
+├── README.md            # user-facing install/usage doc
+├── contract.json        # data contract shared by the connector and backend tests
+├── connector/           # Power Query SDK project (CisoAssistant.pq + assets)
+├── signing/             # certificate generation + customer trust runbooks
+└── samples/             # starter .pbit template
+```
+
+The backend contract test lives at
+`backend/app_tests/api/test_api_powerbi_contract.py` and runs with the
+regular backend test suite: it asserts that every JSON path consumed by
+`connector/CisoAssistant.pq` (as declared in `contract.json`) is present in
+the live serializer output. **When you change columns, update
+`CisoAssistant.pq` and `contract.json` together.**
+
+## Environment: Windows required for build/test
+
+The M source (`CisoAssistant.pq`) can be edited anywhere (VS Code +
+`PowerQuery.vscode-powerquery` for syntax/IntelliSense on macOS/Linux), but
+building and evaluating requires Windows:
+
+- The **Power Query SDK** VS Code extension (`PowerQuery.vscode-powerquery-sdk`)
+  is Windows-only (wraps `PQTest.exe` / `MakePQX.exe`; not available for
+  Mac Silicon, Rosetta doesn't work).
+- **Power BI Desktop** is Windows-only.
+
+On Apple Silicon: Parallels Desktop + Windows 11 ARM (~5 GB RAM is enough),
+repo mounted via Parallels shared folders.
+
+## Build & test loop (Windows VM)
+
+1. Open `automation/powerbi/connector/` as the VS Code workspace.
+2. Install the **Power Query SDK** extension; run its *Setup workspace*
+   task if prompted (regenerates `.vscode/settings.json`).
+3. **Set credential** task → auth kind *Key* → paste a PAT from your dev
+   instance. Credentials bind to the exact base URL in the query file —
+   change the URL and the SDK may prompt again (*Clear ALL credentials*
+   resets a confused state).
+4. **Point the test query at your dev instance**: the URL is the literal on
+   the last line of `CisoAssistant.query.pq`. This is a local, uncommitted
+   edit — the repo keeps the neutral `https://localhost:8443` placeholder;
+   never commit your instance URL. From a VM, `localhost` is the VM itself:
+   target the host instead (Parallels: the Mac is `10.211.55.2`; run
+   `ALLOWED_HOSTS=localhost,127.0.0.1,10.211.55.2 python manage.py runserver 0.0.0.0:8000`
+   on the host and use `http://10.211.55.2:8000`). Plain `http://` is
+   accepted for loopback/private hosts only; the connector rejects it for
+   public hosts (PAT travels in a header).
+5. *Evaluate current file* task → results appear in the panel. To inspect a
+   specific table or debug a filter, replace the last line with a drill
+   expression, e.g.
+   `CisoAssistant.Contents("...") {[Name = "Facts"]}[Data] {[Name = "Applied Controls"]}[Data]`
+   (optionally wrapped in `Table.SelectRows(..., each [updated_at] >= #datetime(...))`
+   to watch fold behaviour in the backend logs) — same rule: revert before
+   committing.
+6. *Build* task (pick **MakePQX**, not MSBuild) → `bin/AnyCPU/Debug/connector.mez`.
+   MakePQX names the output after the workspace *folder*; the MSBuild path
+   (`CisoAssistant.proj`) names it `CisoAssistant.mez` after the project.
+   `.vscode/settings.json` points at the MakePQX name.
+7. Copy the `.mez` to the Custom Connectors folder — resolve it via the
+   known folder (OneDrive may redirect Documents, especially on fresh VMs):
+   ```powershell
+   $dir = Join-Path ([Environment]::GetFolderPath("MyDocuments")) "Power BI Desktop\Custom Connectors"
+   New-Item -ItemType Directory -Force $dir | Out-Null
+   Copy-Item bin\AnyCPU\Debug\connector.mez "$dir\CisoAssistant.mez" -Force
+   ```
+   Allow uncertified extensions in Power BI Desktop's security options,
+   restart Desktop, and test **Get Data → CISO Assistant** end-to-end.
+8. Run *TestConnection* task before touching gateway-related code.
+
+### Testing the signed .pqx locally
+
+Pack + sign with the extension's bundled MakePQX (path under
+`%USERPROFILE%\.vscode\extensions\...powerquery-sdk...\.nuget\...\tools\`),
+then validate through Power BI Desktop, not MakePQX:
+
+1. `MakePQX pack -mz bin\AnyCPU\Debug\connector.mez -t bin\AnyCPU\Debug\CisoAssistant.pqx`
+2. `MakePQX sign <pqx> --certificate <pfx> --password <pwd> --replace`
+3. Put the `.pqx` in the Custom Connectors folder and **remove the `.mez`**
+   there (both present = duplicate connector).
+4. Add the signing thumbprint to
+   `HKLM:\Software\Policies\Microsoft\Power BI Desktop\TrustedCertificateThumbprints`
+   (see `../signing/trust-thumbprint.md`), set Desktop's Data Extensions
+   security to **(Recommended)**, restart. Desktop refusing to load the
+   connector at Recommended = signature or trust problem; loading = the
+   full customer path works.
+
+Known quirk (SdkTools 2.155.2, any host): `MakePQX verify` crashes with a
+`System.Threading.Tasks.Extensions` assembly-binding error while printing
+its report — the package's `MakePQX.exe.config` lacks binding redirects
+for the System.Text.Json dependency chain. CI patches the redirects into
+the config before running the tools (see the "Patch MakePQX binding
+redirects" step in the workflow); locally, either apply the same patch or
+skip `verify` and use the Desktop trust test above, which is the
+authoritative check anyway.
+
+`.mez` is just a zip of the connector folder contents — CI
+(`.github/workflows/powerbi-connector.yml`) builds it with
+`Compress-Archive`, packs it to `.pqx` with `MakePQX`, and signs it when
+the signing secrets are configured (see `signing/generate-cert.md`).
+
+## Local backend for testing
+
+Any running CISO Assistant works. For a filter/pagination sanity check
+without Power BI:
+
+```bash
+curl -H "Authorization: Token $PAT" \
+  "https://localhost:8443/api/applied-controls/?limit=2&offset=0&updated_at__gte=2026-01-01T00:00:00Z" -k
+```
+
+## Versioning & release
+
+The connector version is the `[Version = "x.y.z"]` attribute on the first
+line of `CisoAssistant.pq` — semver, aligned with the compatibility policy:
+
+- **patch** — fixes, no contract change
+- **minor** — additive only (new tables/columns/bridges); never breaks an
+  existing report
+- **major** — renames/removals in the contract, auth or data source kind
+  changes; requires migration notes and should be avoided (`contract.json`
+  + the backend contract test exist to keep changes additive)
+
+Release: bump `[Version]` (and `contract.json`/docs if the surface changed),
+merge, then tag `powerbi-v<x.y.z>`. CI refuses tags that don't match the
+`.pq` version, then builds, packs, signs (if the signing secrets are
+present), uploads artifacts, and attaches `CisoAssistant.mez` +
+`CisoAssistant.pqx` to the GitHub Release. Customer upgrade = replace the
+file, restart Power BI (reports and credentials bind to the data source
+kind, not the file or version).