Merge remote-tracking branch 'origin/dev' into feature/finops-multitool

# Conflicts:
#	docs-mslearn/toolkit/changelog.md

Author: Zac Larsen

.github/workflows/dev.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: Windows-latest
     steps:
       - name: Install and cache PowerShell modules
-        uses: potatoqualitee/psmodulecache@ee5e9494714abf56f6efbfa51527b2aec5c761b8 # v6.2.1
+        uses: potatoqualitee/psmodulecache@9e4b63833c22c1768d648e115a9c849afdda22a5 # v6.3
         with:
           modules-to-cache: InvokeBuild, PSScriptAnalyzer, Pester:6.0.0, Az.Accounts, Az.Resources
           shell: pwsh

.github/workflows/opendata-instance-size-flexibility.yml

@@ -15,7 +15,6 @@ on:
 # so the subscription only serves as an API routing scope.
 permissions:
   contents: write
-  pull-requests: write
   id-token: write
 
 jobs:
@@ -45,25 +44,11 @@ jobs:
         shell: pwsh
         run: src/scripts/Update-InstanceSizeFlexibility.ps1
 
-      - name: Create PR if data changed
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_BODY: |
-            ## Summary
-
-            Weekly automated update of instance size flexibility (ISF) ratios from the
-            [Azure Reservations Catalogs API](https://learn.microsoft.com/azure/cost-management-billing/reservations/instance-size-flexibility#extract-instance-size-flexibility-ratios-using-azure-catalogs-api).
-
-            This file maps each ARM SKU to its instance size flexibility group and ratio,
-            replacing the deprecated `AutofitComboMeterData.csv` and `isfratioblob.csv` files
-            that were hosted on `ccmstorageprod.blob.core.windows.net` (retired 30 Aug 2026).
-
-            ## Test plan
-
-            - [ ] Review the diff for unexpected changes (large drops in group/SKU count, etc.)
-            - [ ] Spot-check a few SKUs against the Azure Pricing Calculator
-
-            🤖 Generated by the **Update Instance Size Flexibility** workflow
+      # GitHub Actions is not permitted to open pull requests in this org, so we push
+      # a branch and surface a one-click "create PR" link in the job summary for a
+      # maintainer to open. Opening the PR triggers Open Data CI and normal review.
+      # This mirrors opendata-commitment-eligibility.yml, which hit the same wall.
+      - name: Push branch and surface PR link if data changed
         run: |
           # Check for changes (handles both new file and modified file)
           if git diff --quiet --exit-code -- src/open-data/InstanceSizeFlexibility.csv 2>/dev/null && \
@@ -72,15 +57,50 @@ jobs:
             exit 0
           fi
 
-          BRANCH="opendata/instance-size-flexibility-$(date +%Y%m%d)"
+          # run_number keeps a re-run on the same day from colliding with the branch an
+          # earlier run already pushed; run_attempt does the same for a re-run of this
+          # run, which keeps run_number and only increments the attempt.
+          BRANCH="opendata/instance-size-flexibility-$(date +%Y%m%d)-${{ github.run_number }}.${{ github.run_attempt }}"
           git checkout -b "$BRANCH"
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add src/open-data/InstanceSizeFlexibility.csv
           git commit -m "chore: Update instance size flexibility ratios"
           git push origin "$BRANCH"
 
-          gh pr create \
-            --title "[Open Data] Update instance size flexibility ratios ($(date +'%B %Y'))" \
-            --base dev \
-            --body "$PR_BODY"
+          PR_URL="${{ github.server_url }}/${{ github.repository }}/compare/dev...${BRANCH}?expand=1"
+          {
+            echo "### Instance size flexibility ratios updated"
+            echo ""
+            echo "Pushed branch \`${BRANCH}\`. GitHub Actions cannot open PRs in this repo, so open it manually:"
+            echo ""
+            echo "[**Create pull request →**](${PR_URL})"
+            echo ""
+            echo "Suggested title:"
+            echo ""
+            echo '```'
+            echo "[Open Data] Update instance size flexibility ratios ($(date +'%B %Y'))"
+            echo '```'
+            echo ""
+            echo "Suggested body:"
+            echo ""
+            echo '```markdown'
+            echo "## Summary"
+            echo ""
+            echo "Weekly automated update of instance size flexibility (ISF) ratios from the"
+            echo "[Azure Reservations Catalogs API](https://learn.microsoft.com/azure/cost-management-billing/reservations/instance-size-flexibility#extract-instance-size-flexibility-ratios-using-azure-catalogs-api)."
+            echo ""
+            echo "This file maps each ARM SKU to its instance size flexibility group and ratio,"
+            echo "replacing the deprecated \`AutofitComboMeterData.csv\` and \`isfratioblob.csv\` files"
+            echo "that were hosted on \`ccmstorageprod.blob.core.windows.net\` (retired 30 Aug 2026)."
+            echo ""
+            echo "## Test plan"
+            echo ""
+            echo "- [ ] Review the diff for unexpected changes (large drops in group/SKU count, etc.)"
+            echo "- [ ] Spot-check a few SKUs against the Azure Pricing Calculator"
+            echo ""
+            echo "🤖 Generated by the **Update Instance Size Flexibility** workflow"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "Branch pushed: $BRANCH"
+          echo "Open a PR here: $PR_URL"

.github/workflows/publish.yml

@@ -7,7 +7,7 @@ jobs:
     runs-on: windows-latest
     steps:
       - name: Install and cache PowerShell modules
-        uses: potatoqualitee/psmodulecache@ee5e9494714abf56f6efbfa51527b2aec5c761b8 # v6.2.1
+        uses: potatoqualitee/psmodulecache@9e4b63833c22c1768d648e115a9c849afdda22a5 # v6.3
         with:
           modules-to-cache: InvokeBuild, PSScriptAnalyzer, Pester, Az.Accounts, Az.Resources
           shell: pwsh

docs-mslearn/TOC.yml

@@ -220,6 +220,8 @@
           href: toolkit/optimization-engine/faq.md
         - name: Troubleshooting guide
           href: toolkit/optimization-engine/troubleshooting.md
+        - name: Reference
+          href: toolkit/optimization-engine/reference.md
     - name: Open data
       href: toolkit/open-data.md
     - name: PowerShell

docs-mslearn/toolkit/changelog.md

@@ -3,7 +3,7 @@ title: FinOps toolkit changelog
 description: Review the latest features and enhancements in the FinOps toolkit, including updates to FinOps hubs, Power BI reports, and more.
 author: MSBrett
 ms.author: brettwil
-ms.date: 08/23/2026
+ms.date: 09/07/2026
 ms.topic: reference
 ms.service: finops
 ms.subservice: finops-toolkit
@@ -34,10 +34,12 @@ The following section lists features and enhancements that are currently in deve
   - Replaced redundant `tolower()` comparisons in hub KQL with case-insensitive operators (`has`, `=~`, `!~`) so the engine can use the term index instead of scanning every row ([#2213](https://github.com/microsoft/finops-toolkit/issues/2213)).
   - Replaced whole-term `contains` matches with `has` across hub KQL and the query catalog (resource ID paths, licensing phrases, SKU description terms) and added a per-row operator-equivalence regression harness with unit test coverage ([#2220](https://github.com/microsoft/finops-toolkit/pull/2220)).
 - **Fixed**
+  - Fixed managed exports failing with an `Unauthorized` error because the Role Based Access Control Administrator role was never assigned to the Data Factory identity. Roles requested by a hub app are now assigned on the publisher storage account even when the app doesn't create the storage account itself ([#2253](https://github.com/microsoft/finops-toolkit/issues/2253)).
   - Fixed private-network deployments that Azure Policy blocked when `defaultOutboundAccess` was omitted. Private mode subnets now set it to `false`, while an Azure Files private endpoint supports deployment-script storage and the NAT Gateway provides required container egress ([#2258](https://github.com/microsoft/finops-toolkit/issues/2258), [#2259](https://github.com/microsoft/finops-toolkit/pull/2259)).
   - Fixed the `ContractedCost` recompute guard to compare with a null-safe tolerance instead of exact float equality, eliminating millions of no-op rewrites that polluted the `x_SourceValues` audit trail while preserving the null-cost backfill and no longer overwriting an existing cost when the unit price is missing ([#2216](https://github.com/microsoft/finops-toolkit/issues/2216)).
   - Fixed the SQL VMs without Azure Hybrid Benefit recommendation query to join on the SQL VM `virtualMachineResourceId` instead of a case-sensitive VM name match that skipped VMs with uppercase names and dropped duplicate names, and made all Azure Resource Graph join kinds explicit so no query relies on the `innerunique` default ([#2225](https://github.com/microsoft/finops-toolkit/pull/2225)).
   - Switched dimension enrichment in the v1_0/v1_2 ingestion transforms (`PricingUnits`, `Regions`, `ResourceTypes`, `Services`) from `join` to the broadcast-optimized `lookup` operator and deduplicated the `Services` mapping per resource type to prevent cost row fan-out ([#2225](https://github.com/microsoft/finops-toolkit/pull/2225)).
+  - Fixed the v1_0 and v1_2 price transforms setting `x_CommitmentDiscountSpendEligibility` from reservation meters and `x_CommitmentDiscountUsageEligibility` from savings plan meters, the opposite of the FOCUS `CommitmentDiscountCategory` value the same transform assigns. The spend column now reports savings plan pricing and the usage column reports reservation pricing. Prices ingested after upgrading carry the corrected values; rows ingested earlier keep the old values until they are reingested ([#2279](https://github.com/microsoft/finops-toolkit/issues/2279)).
 
 ### [FinOps workbooks](workbooks/finops-workbooks-overview.md)
 
@@ -67,8 +69,12 @@ The following section lists features and enhancements that are currently in deve
 
 ### [Optimization Engine](optimization-engine/overview.md)
 
+- **Added**
+  - Added a comprehensive [Azure Optimization Engine reference](optimization-engine/reference.md) for runbooks, schedules, variables, Log Analytics tables, and SQL Database tables ([#1271](https://github.com/microsoft/finops-toolkit/issues/1271)).
 - **Changed**
   - Switched the reservations and benefits workbooks from the retired `ccmstorageprod` isfratioblob.csv to the FinOps toolkit [Instance size flexibility](open-data.md#instance-size-flexibility) open data file ([#2090](https://github.com/microsoft/finops-toolkit/issues/2090)).
+- **Fixed**
+  - Fixed a regression in the `AzureOptimizationConsumptionV1_CL` schema that was breaking the Reservations Usage workbook ([#2301](https://github.com/microsoft/finops-toolkit/issues/2301)).
 
 ### [PowerShell module](powershell/powershell-commands.md)
 
@@ -87,6 +93,7 @@ The following section lists features and enhancements that are currently in deve
 - **Fixed**
   - Fixed the commitment discount eligibility dataset refresh so it is reproducible and complete; retired meters now age out and previously missed meters are included ([#2164](https://github.com/microsoft/finops-toolkit/pull/2164)).
   - Fixed the weekly commitment discount eligibility refresh timing out before it could publish, which left the dataset unchanged since it first shipped in v14. The refresh now walks each price type directly instead of sharding by service family, and verifies completeness by comparing two independent traversals before writing ([#2251](https://github.com/microsoft/finops-toolkit/pull/2251)).
+  - Fixed `x_CommitmentDiscountSpendEligibility` and `x_CommitmentDiscountUsageEligibility` carrying each other's values. FOCUS classifies a reservation as a usage commitment (committed to a quantity of usage) and a savings plan as a spend commitment (committed to an amount of money), so the spend column now reports savings plan pricing and the usage column reports reservation pricing. The dataset shipped with the two reversed from v14 ([#2279](https://github.com/microsoft/finops-toolkit/issues/2279)).
 
 -->
 

docs-mslearn/toolkit/hubs/template.md

@@ -3,7 +3,7 @@ title: FinOps hub template
 description: Learn about what's included in the FinOps hub template including parameters, resources, and outputs.
 author: flanakin
 ms.author: micflan
-ms.date: 06/03/2026
+ms.date: 08/24/2026
 ms.topic: concept-article
 ms.service: finops
 ms.subservice: finops-toolkit
@@ -65,7 +65,7 @@ Ensure the following prerequisites are met before you deploy the template:
   | [Storage Account Contributor](/azure/role-based-access-control/built-in-roles#storage-account-contributor)                                   | Assigned to Data Factory to manage data in storage.                                                        |
   | [Storage Blob Data Contributor](/azure/role-based-access-control/built-in-roles#storage-blob-data-contributor)                               | Assigned to Data Factory and Data Explorer to manage data in storage.                                      |
   | [Storage File Data Privileged Contributor](/azure/role-based-access-control/built-in-roles/storage#storage-file-data-privileged-contributor) | Assigned to the deployment file upload identity that uploads files to the config container.                |
-  | [User Access Administrator](/azure/role-based-access-control/built-in-roles#user-access-administrator)                                       | Assigned to Data Factory to manage data in storage. Not applied when **enableManagedExports** is disabled. |
+  | [Role Based Access Control Administrator](/azure/role-based-access-control/built-in-roles/privileged#role-based-access-control-administrator) | Assigned to Data Factory on the storage account so it can create Cost Management exports, which grant their own identity access to the export destination. Not applied when **enableManagedExports** is disabled. |
 
 - The Microsoft.EventGrid resource provider must be registered in your subscription. For more information, see [Register a resource provider](/azure/azure-resource-manager/management/resource-providers-and-types#register-resource-provider).
 
@@ -97,7 +97,7 @@ Here are the parameters you can use to customize the deployment:
 | **dataExplorerFinalRetentionInMonths** | Int    | Optional. Number of months of data to retain in the Data Explorer \*_final_v\* tables.                                                                                                                                                                                                                                                 | 13                 |
 | **remoteHubStorageUri**                | String | Optional. Data Lake storage endpoint from the remote (primary) hub storage account. Used for cross-tenant cost data collection where this hub sends processed data to a central hub. Example: `https://primaryhub.dfs.core.windows.net/` |                    |
 | **remoteHubStorageKey**                | String | Optional. Storage account access key for the remote (primary) hub. Used with remoteHubStorageUri for cross-tenant scenarios. Must be kept secure as it provides full storage access.                                          |                    |
-| **enableManagedExports**               | Bool   | Optional. Enable managed exports where your FinOps hub instance will create and run Cost Management exports on your behalf. Not supported for Microsoft Customer Agreement (MCA) billing profiles. Requires the ability to grant User Access Administrator role to FinOps hubs, which is required to create Cost Management exports.                                                                                                                                                                      | True               |
+| **enableManagedExports**               | Bool   | Optional. Enable managed exports where your FinOps hub instance will create and run Cost Management exports on your behalf. Not supported for Microsoft Customer Agreement (MCA) billing profiles. Requires the ability to grant the Role Based Access Control Administrator role to FinOps hubs, which is required to create Cost Management exports.                                                                                                                                                                      | True               |
 | **enableRecommendations**              | Bool   | Optional. Enable recommendations ingested from Azure Resource Graph based on configurable queries. The Data Factory managed identity requires Reader role on management groups or subscriptions to execute Resource Graph queries.                                                                                                                                                                                                                                                                        | False              |
 | **enableAHBRecommendations**           | Bool   | Optional. Enable Azure Hybrid Benefit recommendations that flag VMs and SQL VMs without Azure Hybrid Benefit enabled. May generate noise if your organization does not have on-premises licenses. Requires enableRecommendations.                                                                                                                                                                                                                                                                         | False              |
 | **enableSpotRecommendations**          | Bool   | Optional. Enable non-Spot AKS cluster recommendations that flag AKS clusters with autoscaling but not using Spot VMs. May generate noise since Spot VMs are only appropriate for interruptible workloads. Requires enableRecommendations.                                                                                                                                                                                                                                                                 | False              |

docs-mslearn/toolkit/open-data.md

@@ -4,7 +4,7 @@ description: Use open data to normalize and enhance your FinOps reporting, ensur
 ms.topic: concept-article
 author: flanakin
 ms.author: micflan
-ms.date: 07/30/2026
+ms.date: 09/01/2026
 ms.service: finops
 ms.subservice: finops-toolkit
 ms.reviewer: micflan
@@ -162,13 +162,13 @@ Sample data:
 | MeterId                              | x_CommitmentDiscountSpendEligibility | x_CommitmentDiscountUsageEligibility |
 | ------------------------------------ | ------------------------------------ | ------------------------------------ |
 | 00003b45-e996-5b04-b673-a2db710f9237 | Eligible                             | Eligible                             |
-| 00020329-e657-5687-9d1a-0be9876e5116 | Eligible                             | Not Eligible                         |
-| 0003c425-b1df-551f-a855-9c95a08cb4ae | Not Eligible                         | Eligible                             |
+| 00020329-e657-5687-9d1a-0be9876e5116 | Not Eligible                         | Eligible                             |
+| 0003c425-b1df-551f-a855-9c95a08cb4ae | Eligible                             | Not Eligible                         |
 
 A few important notes about the data:
 
-- `x_CommitmentDiscountSpendEligibility` indicates whether the meter has Reserved Instance pricing.
-- `x_CommitmentDiscountUsageEligibility` indicates whether the meter has Savings Plan pricing.
+- `x_CommitmentDiscountSpendEligibility` indicates whether the meter has savings plan pricing. FOCUS classifies a savings plan as a spend commitment because you commit to an amount of money.
+- `x_CommitmentDiscountUsageEligibility` indicates whether the meter has reservation pricing. FOCUS classifies a reservation as a usage commitment because you commit to a quantity of usage.
 - Only primary meter regions are included to avoid duplicates.
 - Data is updated weekly via a GitHub Actions workflow.