Add Start-FinOpsMultitool — cross-platform terminal UI for FinOps scanning

.build/BuildHelper/Build-PsModule.ps1

@@ -20,8 +20,8 @@ function Build-PsModule
     $moduleName = 'FinOpsToolkit'
     $moduleFullName = "$moduleName.psm1"
     $modulePath = Join-Path -Path $rootPath -ChildPath "src/powershell/$moduleFullName"
-    $privatePath = Join-Path -Path $rootPath -ChildPath "src/powershell/private"
-    $publicPath = Join-Path -Path $rootPath -ChildPath "src/powershell/public"
+    $privatePath = Join-Path -Path $rootPath -ChildPath "src/powershell/Private"
+    $publicPath = Join-Path -Path $rootPath -ChildPath "src/powershell/Public"
     $stringsPath = Join-Path -Path $rootPath -ChildPath 'src/powershell/en-US'
     $releasePath = Join-Path -Path $rootPath -ChildPath "release/$moduleName/$baseVersion"
     $manifestPath = Join-Path -Path $releasePath -ChildPath "$moduleName.psd1"

.github/workflows/dev.yml

@@ -3,6 +3,11 @@ name: 'PowerShell Tests'
 on:
   pull_request:
     paths:
+      - '.github/workflows/dev.yml'
+      - '.build/BuildHelper/**'
+      - '.build/BuildHelper.psm1'
+      - 'package.json'
+      - 'src/scripts/Get-Version.ps1'
       - 'src/powershell/**'
       # KQL sources are covered by unit tests (HubsKqlOperators.Tests.ps1)
       - 'src/templates/finops-hub/**/*.kql'
@@ -11,6 +16,10 @@ on:
       - 'src/templates/finops-hub/**/timeZones.bicep'
       - 'docs/deploy/finops-hub-latest.json'
       - 'docs/deploy/finops-hub-preview.json'
+
+permissions:
+  contents: read
+
 jobs:
   run_pester_tests:
     name: Pester
@@ -25,3 +34,124 @@ jobs:
       - name: Run Tests
         shell: pwsh
         run: .build/start.ps1 -Task Test.PowerShell.All
+
+  multitool_native:
+    name: Multitool (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+    env:
+      DOTNET_CLI_TELEMETRY_OPTOUT: '1'
+      DOTNET_NOLOGO: '1'
+    steps:
+      - name: Install and cache test dependencies
+        uses: potatoqualitee/psmodulecache@9e4b63833c22c1768d648e115a9c849afdda22a5 # v6.3
+        with:
+          modules-to-cache: Pester:6.0.0, Az.Accounts, Az.Resources, Az.ResourceGraph, Az.Storage
+          shell: pwsh
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install SDK for native Parquet restore
+        if: runner.os == 'Linux'
+        uses: actions/setup-dotnet@26b0ec14cb23fa6904739307f278c14f94c95bf1 # v5
+        with:
+          dotnet-version: '8.0.x'
+      - name: Run native multitool tests
+        shell: pwsh
+        env:
+          TMPDIR: ${{ runner.temp }}
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Import-Module Pester -RequiredVersion 6.0.0 -Force
+          $names = @(
+              'AzGraphPagination', 'BudgetCoverage', 'CommitmentUtilizationDedupe'
+              'CostQueryPagination', 'CurrencyLabel', 'FOHubProvider', 'HubSizeProbe'
+              'MultitoolResultIntegrity', 'MultitoolSafety', 'ParquetPackageClient', 'PolicyEffect'
+              'RetryJitter', 'Start-FinOpsMultitool'
+          )
+          $paths = @($names | ForEach-Object {
+              Join-Path 'src/powershell/Tests/Unit' "$_.Tests.ps1"
+          })
+          foreach ($path in $paths) {
+              if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { throw "Missing test: $path" }
+          }
+          $configuration = New-PesterConfiguration
+          $configuration.Run.Path = $paths
+          $configuration.Run.PassThru = $true
+          $configuration.Run.Exit = $false
+          $configuration.Output.Verbosity = 'Detailed'
+            $configuration.TestResult.Enabled = $true
+            $configuration.TestResult.OutputFormat = 'NUnitXml'
+            $configuration.TestResult.OutputPath = Join-Path $env:RUNNER_TEMP 'multitool-unit.xml'
+          $result = Invoke-Pester -Configuration $configuration
+          $result | Select-Object Result, TotalCount, PassedCount, FailedCount, SkippedCount, FailedContainersCount
+            @(
+              '## Multitool validation'
+              "Tested merge commit: $env:GITHUB_SHA"
+              "Host: $([Runtime.InteropServices.RuntimeInformation]::OSDescription); PowerShell: $($PSVersionTable.PSVersion)"
+              "Unit tests: $($result.Result); passed $($result.PassedCount), failed $($result.FailedCount), skipped $($result.SkippedCount)."
+            ) | Add-Content -LiteralPath $env:GITHUB_STEP_SUMMARY
+          if ($null -eq $result -or $result.Result -ne 'Passed' -or
+              $result.TotalCount -le 0 -or $result.PassedCount -le 0 -or
+              $result.FailedCount -ne 0 -or $result.FailedContainersCount -ne 0 -or
+              $result.FailedBlocksCount -ne 0 -or $result.Containers.Count -ne $paths.Count) {
+              throw 'Native multitool tests failed or discovery was incomplete.'
+          }
+          exit 0
+      - name: Run package and real Parquet integration tests
+        if: ${{ !cancelled() }}
+        shell: pwsh
+        env:
+          TMPDIR: ${{ runner.temp }}
+        run: |
+          $ErrorActionPreference = 'Stop'
+          Import-Module Pester -RequiredVersion 6.0.0 -Force
+            $paths = @('src/powershell/Tests/Integration/MultitoolPackage.Tests.ps1')
+            $minimumPassed = 3
+            $parquetCoverage = 'Not run on macOS: NuGet signed-package verification is not supported. https://learn.microsoft.com/dotnet/core/tools/nuget-signed-package-verification#macos'
+            if (-not $IsMacOS) {
+              $paths += 'src/powershell/Tests/Integration/MultitoolParquet.Tests.ps1'
+              $minimumPassed += 2
+              $parquetCoverage = 'Real signed Parquet restore and cold/cached reads in separate processes.'
+            }
+          foreach ($path in $paths) {
+              if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { throw "Missing test: $path" }
+          }
+          $configuration = New-PesterConfiguration
+          $configuration.Run.Path = $paths
+          $configuration.Run.PassThru = $true
+          $configuration.Run.Exit = $false
+          $configuration.Output.Verbosity = 'Detailed'
+          $configuration.TestResult.Enabled = $true
+          $configuration.TestResult.OutputFormat = 'NUnitXml'
+          $configuration.TestResult.OutputPath = Join-Path $env:RUNNER_TEMP 'multitool-integration.xml'
+          $result = Invoke-Pester -Configuration $configuration
+          $result | Select-Object Result, TotalCount, PassedCount, FailedCount, SkippedCount, FailedContainersCount
+          @(
+              "Integration tests: $($result.Result); passed $($result.PassedCount), failed $($result.FailedCount), skipped $($result.SkippedCount)."
+              'Checks: isolated module build and public launch; CSV, HTML, and text reports.'
+              "Parquet coverage: $parquetCoverage"
+              'Azure access is replaced with synthetic responses. Package downloads and signature verification require network access.'
+          ) | Add-Content -LiteralPath $env:GITHUB_STEP_SUMMARY
+          if ($null -eq $result -or $result.Result -ne 'Passed' -or
+              $result.PassedCount -lt $minimumPassed -or $result.FailedCount -ne 0 -or
+              $result.SkippedCount -ne 0 -or $result.NotRunCount -ne 0 -or
+              $result.FailedContainersCount -ne 0 -or $result.FailedBlocksCount -ne 0 -or
+              $result.Containers.Count -ne $paths.Count) {
+              throw 'Multitool integration tests failed, were skipped, or discovery was incomplete.'
+          }
+          exit 0
+      - name: Upload multitool test evidence
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: multitool-tests-${{ matrix.os }}
+          path: |
+            ${{ runner.temp }}/multitool-unit.xml
+            ${{ runner.temp }}/multitool-integration.xml
+          if-no-files-found: error
+          retention-days: 14

docs-mslearn/TOC.yml

@@ -196,6 +196,12 @@
           href: toolkit/alerts/finops-alerts-overview.md
         - name: Configure alerts
           href: toolkit/alerts/configure-finops-alerts.md
+    - name: FinOps multitool
+      items:
+        - name: Overview
+          href: toolkit/multitool/finops-multitool-overview.md
+        - name: Commands
+          href: toolkit/powershell/multitool/finops-multitool-commands.md
     - name: Optimization engine
       items:
         - name: Overview
@@ -242,6 +248,12 @@
               href: toolkit/powershell/cost/remove-finopscostexport.md
             - name: Start-FinOpsCostExport
               href: toolkit/powershell/cost/start-finopscostexport.md
+        - name: FinOps multitool
+          items:
+            - name: FinOps multitool commands
+              href: toolkit/powershell/multitool/finops-multitool-commands.md
+            - name: Start-FinOpsMultitool
+              href: toolkit/powershell/multitool/start-finopsmultitool.md
         - name: FinOps hubs
           items:
             - name: FinOps hubs commands

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: 09/11/2026
+ms.date: 10/07/2026
 ms.topic: reference
 ms.service: finops
 ms.subservice: finops-toolkit
@@ -54,6 +54,60 @@ The following section lists features and enhancements that are currently in deve
 - **Fixed**
   - Made the idle application gateway and idle public IP query join kinds explicit so they no longer rely on the `innerunique` default ([#2225](https://github.com/microsoft/finops-toolkit/pull/2225)).
 
+### [FinOps multitool](multitool/finops-multitool-overview.md)
+
+- **Added**
+  - Added the FinOps multitool, which scans an Azure environment for cost optimization, governance, and FinOps insights through a PowerShell 7 terminal UI ([#2155](https://github.com/microsoft/finops-toolkit/pull/2155)).
+    - Included 30 read-only scan modules, with 26 available in the menu, covering orphaned resources, idle VMs, storage tier advice, Azure Hybrid Benefit, tag and policy inventory and recommendations, cost data, cost trend, cost by tag, resource costs, reservation advice, commitment utilization, estimated savings, budget status and history, anomaly alerts, Advisor recommendations, billing structure, and contract info.
+    - Added a companion set of agent skills that carry the investigation routing, the queries, and the interpretation rules so AI agents can run the same analysis through Azure CLI or an Azure MCP server.
+    - Added engine-side aggregation through the FinOps hub's Azure Data Explorer or Microsoft Fabric Kusto database for large environments, with a storage reader as a small-dataset fallback.
+    - Added a non-interactive mode for an already-authenticated pipeline or scheduled job, and automatic private CSV, HTML, and text reports. Consoles that can't render the arrow-key menus, such as PowerShell remoting sessions, fall back to numbered prompts.
+    - Added `-Accessible` to select numbered prompts without clearing the screen or repainting menus in cursor-capable terminals.
+    - Added a searchable KPI reference and in-report calculation details for cost shares, unit rates, VM and storage screening, and budget coverage and forecast availability.
+    - Added aggregate and per-subscription cost trend views with captured UTC periods, partial-month labels, and separate empty and unverified coverage states.
+    - Added sticky table headers, row numbers, sorting, resizable columns, and expanded views to the local HTML report without changing CSV data.
+    - Added an explicit ordinary Cost Management CSV export source without requiring a FinOps hub, with selected-scope coverage, reads limited to the chosen export folder, manifest-verified partitions, and no silent live-cost fallback. Discovery reports progress per scope and per storage account. If you choose exports from the menu and none can be verified, you're asked whether to use the Cost Management API instead. Interactive runs ask before scanning more than 100 storage accounts for exports.
+- **Fixed**
+  - Fixed literal `\u000D` text appearing at the ends of terminal table rows on Windows ([#2155](https://github.com/microsoft/finops-toolkit/pull/2155)).
+  - Fixed policy recommendations failing when a complete inventory contains no policy assignments ([#2155](https://github.com/microsoft/finops-toolkit/pull/2155)).
+  - Fixed incomplete billing-scope discovery appearing as complete commitment utilization.
+  - Kept unreadable Hub tags unverified instead of counting them as missing tags.
+  - Rejected explicit empty scan lists instead of running the default scans.
+  - Fixed malformed budget records counting toward confirmed budget coverage.
+  - Preserved budget inventory failures and partial coverage in budget history reports.
+  - Rejected unsafe export blob paths and invalid fallback container names, and escaped control characters in storage-discovery diagnostics.
+  - Made failed and unreadable Kusto discovery visible without changing the selected tenant or subscriptions.
+  - Rejected malformed Kusto responses and partial query failures instead of returning incomplete or empty success results.
+  - Rejected empty authentication tokens before sending Kusto queries and retained detailed Kusto HTTP errors on PowerShell 7.
+  - Reported the macOS Parquet signature-verification limitation before invoking a package client or downloading packages.
+  - Fixed AI token totals using inconsistent account and deployment measurements, and kept same-named deployments in different accounts separate.
+  - Fixed commitment SKU and kind metadata, incomplete fallback pagination, and unavailable utilization appearing as measured zero.
+  - Clarified budget sampling and CPU units, distinguished storage lookup failures from missing permissions, and added private launcher help and read-only regression checks.
+  - Hardened CSV exports against formula prefixes after whitespace or invisible characters and unsafe column names, while preserving numeric credits.
+  - Fixed storage-backed Parquet imports returning empty values or misaligning costs when an export contains nested metadata.
+  - Fixed measured zero unit-cost KPIs appearing unavailable.
+  - Fixed automatic Hub discovery failures aborting scans, including when every probe fails, while preserving explicit source choices and tenant boundaries ([#2155](https://github.com/microsoft/finops-toolkit/pull/2155)).
+  - Fixed provider-discovery exceptions aborting detected-Hub scans and preserved the selected storage fallback through scan execution ([#2155](https://github.com/microsoft/finops-toolkit/pull/2155)).
+  - Required a Y or N answer before switching to the Cost Management API when a detected FinOps hub's storage can't be reached.
+  - Limited estimated savings and unit costs to the selected subscriptions, querying subscriptions individually when a management group doesn't contain every selected subscription.
+  - Kept orphaned-resource costs and resource forecasts in their billing currencies instead of combining or relabeling them. Resource costs from the Cost Management API now include `ForecastSource`, which shows whether each forecast comes from a Cost Management forecast or a month-to-date projection. Forecasts stay empty when they're unavailable or can't be split across resources, and a failed forecast request keeps actual resource costs and reports the gap as limited data.
+  - Rejected partitioned export runs without a valid manifest, and read only the newest snapshot of a legacy unpartitioned export instead of adding snapshots together.
+  - Kept unattributed FinOps hub charges with their own subscription, and kept tag values that differ only by case separate.
+  - Counted the recommended `ApplicationName` and `OpsTeam` tags toward cost allocation.
+  - Reported incomplete Advisor recommendations and unreadable storage capacity instead of presenting partial results as complete.
+  - Stopped Advisor cost and reservation recommendations from being counted twice when the Resource Graph read fails partway through and the per-subscription fallback runs.
+  - Kept every resource cost row from the per-subscription Cost Management fallback, including unattributed charges and resource IDs that differ only by case, instead of keeping only the last row for each ID.
+  - Reported the count and amount in each currency of export rows that have no subscription, such as purchases or refunds billed outside a subscription. These rows aren't included in subscription totals.
+  - Confirmed billing account ownership before reporting contract details, and counted only enabled anomaly alert rules as detection coverage.
+  - Fixed FinOps hub CSV fallback reads to match hub ingestion: each export run counts toward the month in its manifest, and only the latest FOCUS cost run with rows is kept for each export scope and month, instead of adding runs together or dropping other scopes. Exports for unselected subscriptions are skipped, a manifest that can't be verified stops the read only when it could affect the months being read, and CSV files that no readable manifest lists are reported. The fallback checks at most 2,000 export manifests, doesn't download manifests over 1 MB, and stops instead of counting a file that two runs list. Fixed agreement detection from subscription metadata when billing account details can't be read.
+  - Corrected agent skill guidance on billed and effective cost and on when tags appear in cost data, and replaced references to unavailable tools with the terminal UI data sources.
+  - Stopped unresolved explicit subscription lookups from searching other tenants or widening the scan scope ([#2155](https://github.com/microsoft/finops-toolkit/pull/2155)).
+  - Fixed policy-definition read failures appearing as complete scan results; warnings and reports now identify unread definitions while retaining assignments and valid compliance data ([#2335](https://github.com/microsoft/finops-toolkit/issues/2335)).
+  - Limited management-group cost discovery to 25 candidates, including the tenant root, while preserving pagination, selected-subscription fallback, and tenant-specific caching ([#2335](https://github.com/microsoft/finops-toolkit/issues/2335)).
+  - Fixed crowded HTML reports for large subscription selections with bounded columns, compact scope lists, expandable tag and policy details, and local table filtering and pagination without reducing CSV detail.
+  - Fixed missing resource-cost periods and unclear resource identities by retaining the requested UTC window, displaying resource and reservation-charge labels, and preserving full IDs in HTML and CSV.
+  - Added verified subscription and management-group display names to policy locations while retaining scope IDs when name lookup fails.
+
 ### [Power BI reports](power-bi/reports.md)
 
 - **Changed**