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

[Zac larsen (z-larsen)]

🛠️ Description

Adds the FinOps multitool to the FinOps toolkit. Discussed with Brett Wilson (@MSBrett), who suggested contributing the tool into the official toolkit.

The multitool scans an Azure environment for cost optimization, governance, and FinOps insights — cost trends, orphaned resources, idle VMs, tag hygiene, reservation and savings plan utilization, Azure Hybrid Benefit opportunities, budgets, anomaly alerts, and policy compliance — and grounds its findings in live resource state.

Everything in this PR is read-only. It needs Reader or Cost Management Reader on the target scope and never creates, changes, or deletes a resource. Remediation and the MCP server were split out to a separate branch and will follow as their own PR.

One scanner engine, two consumers:

Interface	Entry point	Best for
Terminal UI	Start-FinOpsMultitool	A person who wants a full assessment
Agent skills	src/templates/agent-skills/	AI agents answering a single question through az or an Azure MCP server

A separate WPF GUI is maintained outside this repo. This PR contributes the terminal UI and the agent skills.

Running it

The terminal UI uses arrow-key menus when the console supports them. Consoles that can't render those menus — PowerShell remoting sessions, some editor terminals — fall back to numbered prompts, which is also what a screen reader can follow. Both paths run the same scans and produce the same results.

For automation, -NonInteractive with -Scans, -DataSource, -SubscriptionId, and -OutputPath supplies every choice, so the tool runs from a pipeline or a scheduled job:

Start-FinOpsMultitool -NonInteractive `
    -SubscriptionId '00000000-0000-0000-0000-000000000000' `
    -Scans Get-OrphanedResources, Get-IdleVMs `
    -DataSource API `
    -OutputPath './results'

FinOps hub data paths

This addresses Brett Wilson (@MSBrett)'s scaling review. When a FinOps hub is present, cost scans prefer the hub's Kusto database — an Azure Data Explorer or Fabric cluster, auto-discovered through Resource Graph, or a local ftklocal emulator via FINOPS_HUB_KUSTO_URI — and push aggregation into the engine, returning only summarized result sets. Raw cost rows are never materialized in PowerShell on that path.

The storage-export reader remains as a small-dataset fallback rather than the scalable path, and the terminal UI warns before using it on a hub with no reachable cluster, offering the live Cost Management API instead.

Scans

30 scan modules across optimization, governance, cost analysis, commitments, monitoring, Advisor, account, AI and ML, and sustainability. The terminal UI surfaces 26 of them. Results render in the terminal and export to one CSV per scan, a FinOpsReport.html summary, and a ScanSummary.txt file.

📦 Files added / changed

Path	Purpose
Public/Start-FinOpsMultitool.ps1	Public cmdlet — launches the cross-platform terminal UI
Invoke-FinOpsMultitool.ps1 + FinOpsMultitool.psm1	Terminal UI + module loader
modules/	30 read-only scanner modules
helpers/Get-FOHubProvider.ps1 + Invoke-FOHubKustoQuery.ps1	Scalable FinOps hub Kusto data path (ADX / Fabric / ftklocal)
agent-skills/finops-multitool/ + references/	Routing hub skill and its investigation references
agent-skills/cost-data-source/	Cost data-source routing skill (Kusto vs storage vs API)
agent-skills/{power-bi-finops, cost-allocation, …}/	11 FinOps-adjacent skills
Tests/Unit/Start-FinOpsMultitool.Tests.ps1 + FOHubProvider.Tests.ps1	Pester unit tests
docs-mslearn/.../powershell/multitool/ + docs/multitool.md	Documentation (command reference, landing page, TOC, changelog)

📸 Screenshots

Screenshots are in the public repo README.

📋 Checklist

🧪 How did you test this change?

• 🧹 Lint tests
• 👍 PS -WhatIf / az validate
• 🔌 Manually deployed + verified
• 🧪 Unit tests
• 👀 Integration tests

🐳 Deploy to test?

N/A — standalone PowerShell tooling, not a template deployment.

🏷️ Do any of the following that apply?

• 🚨 This is a breaking change.
• 🐣 The change is less than 20 lines of code.

📄 Did you update docs/changelog.md?

• ✅ Updated changelog
• ❌ Log not needed (small/internal change)

📖 Did you update documentation?

• ✅ Documentation updated — FinOps multitool reference under docs-mslearn/.../powershell/multitool/, a Jekyll landing page, overview/TOC/changelog entries, and the module README plus the finops-multitool and cost-data-source skills.
• ❌ Docs not needed (small/internal change)

[Zac larsen (z-larsen)]

@microsoft-github-policy-service agree company="Microsoft"

[Michael Flanakin (flanakin)]

Zac larsen (@z-larsen) This is exciting! I don't know much about the tool, but would love to learn more. Can you join us at the contributor sync next Wednesday to share?

https://aka.ms/ftk/contrib-sync

[Zac larsen (z-larsen)]

Thanks, Michael! Would love to join.

[Zac larsen (z-larsen)]

Thanks Brett - all three are fixed in b336ab0c.

1. TUI data-source selection fails before scans start
Select-DataSource's return value now lands in $sourceChoice, so it no longer collides with the [ValidateSet] $DataSource parameter. Added an AST regression test in Start-FinOpsMultitool.Tests.ps1 that fails if any ValidateSet parameter is assigned to anywhere in Invoke-FinOpsMultitool - it guards the class of bug rather than this one instance.

2. MACC results are not bounded by the selected scope
Get-MaccCommitment now correlates billing accounts to the selected subscriptions through a shared Get-FinOpsBillingScope helper instead of ignoring $Subscriptions.

3. Billing Structure drops a readable EA enrollment
Dropped the billingInfo/default dependency. It is not a valid resource type and 404s on every api-version, which is what left the account set empty. Get-BillingStructure now lists billing accounts and correlates them through the same Get-FinOpsBillingScope helper Get-ContractInfo uses, and warns when correlation fails.

Unit suite: 2433 passed / 0 failed / 7 skipped.