Update internal PowerShell script documentation (#1993)

Co-authored-by: Claude <noreply@anthropic.com>

Author: flanakin

.github/copilot-instructions.md

@@ -13,18 +13,15 @@ This is the Microsoft FinOps toolkit - an open-source collection of tools and re
 - **Test coverage**: Ensure changes don't break existing functionality
 - **Microsoft standards**: Follow Microsoft style guide and development practices
 - **Document changes**: Always document changes in the [changelog](../docs-mslearn/toolkit/changelog.md)
-  - **Every change must have a changelog entry** - no exceptions for bug fixes, features, or improvements
+  - **Every change must have a changelog entry** unless the PR body contains `[x] ❎ Log not needed` and the PR does NOT change any meaningful externally-facing functionality; no exceptions for external bug fixes, features, or improvements
   - **Document in the next release section**, not the last release:
     - Check the current version in [package.json](../package.json) (e.g., if version is "12.0.0", document changes under v13)
     - Remove `-dev` from the version number when determining the next release
     - Create the next version section if it doesn't exist yet
   - Changelog entries must be under the correct tool and version (e.g., FinOps hubs v13)
   - For releases, include download and changelog links at the end of each release section using the format:
     ```markdown
-    > [!div class="nextstepaction"]
-    > [Download](https://github.com/microsoft/finops-toolkit/releases/tag/vX)
-    > [!div class="nextstepaction"]
-    > [Full changelog](https://github.com/microsoft/finops-toolkit/compare/vX-1...vX)
+    > [!div class="nextstepaction"] > [Download](https://github.com/microsoft/finops-toolkit/releases/tag/vX) > [!div class="nextstepaction"] > [Full changelog](https://github.com/microsoft/finops-toolkit/compare/vX-1...vX)
     ```
 
 ### Code style guidelines
@@ -38,7 +35,7 @@ This is the Microsoft FinOps toolkit - an open-source collection of tools and re
 ## 📁 Repository structure
 
 - `/src/` - Source code for all toolkit components
-- `/docs/` - Public website and deployment templates  
+- `/docs/` - Public website and deployment templates
 - `/docs-wiki/` - Developer guidelines and project documentation
 - `/docs-mslearn/` - Microsoft Learn documentation content
 - `/.github/` - GitHub workflows, templates, and configuration

src/scripts/Build-Bicep.ps1

@@ -6,14 +6,11 @@
     Builds all Bicep modules for publishing to the Bicep Registry.
 
     .PARAMETER Module
-    Path to the module to build.
+    Optional. Name of the module to build. Default = * (all modules).
 
     .PARAMETER Scope
     Optional. Scope to build. If not specified, all scopes will be built.
 
-    .PARAMETER Debug
-    Optional. Renders main module and test bicep code to the console instead of generating files. Line numbers map to original file.
-
     .EXAMPLE
     ./Build-Bicep module-name
 
@@ -29,6 +26,7 @@
 
     Renders main module and test bicep code to the console instead of generating files.
 #>
+[CmdletBinding()]
 Param (
     [Parameter(Position = 0)][string] $Module = "*",
     [string] $Scope

src/scripts/Build-PowerBI.ps1

@@ -6,13 +6,13 @@
     Creates PBIT files for each Power BI project.
 
     .PARAMETER Name
-    Name of the report to build. Wildcards supported. Default = * (all).
+    Optional. Name of the report to build. Wildcards supported. Default = * (all).
 
-    .PARAMETER -KQL
-    Indicates if the KQL reports should be generated. Default = false (will build all if no types are selected).
+    .PARAMETER KQL
+    Optional. Indicates if the KQL reports should be generated. Default = false (will build all if no types are selected).
 
-    .PARAMETER -Storage
-    Indicates if the storage reports should be generated. Default = false (will build all if no types are selected).
+    .PARAMETER Storage
+    Optional. Indicates if the storage reports should be generated. Default = false (will build all if no types are selected).
 
     .EXAMPLE
     ./Build-PowerBI

src/scripts/Build-Toolkit.ps1

@@ -6,7 +6,22 @@
     Builds all toolkit modules and templates for publishing to the Bicep Registry and Azure Quickstart Templates.
 
     .PARAMETER Template
-    Optional. Name of the module or template to publish. Default = "*" (all templates and modules).
+    Optional. Name of the module or template to build. Default = * (all templates and modules).
+
+    .PARAMETER Major
+    Optional. Increments the major version number (x.0).
+
+    .PARAMETER Minor
+    Optional. Increments the minor version number (0.x).
+
+    .PARAMETER Patch
+    Optional. Increments the patch version number (0.0.x).
+
+    .PARAMETER Prerelease
+    Optional. Increments the prerelease version number (0.0.0-ooo.x).
+
+    .PARAMETER Label
+    Optional. Indicates the label to use for prerelease versions. Allowed: dev, rc, alpha, preview.
 
     .EXAMPLE
     ./Build-Toolkit

src/scripts/Build-Workbook.ps1

@@ -5,15 +5,13 @@
     .SYNOPSIS
     Builds all workbook templates for publishing to Azure Quickstart Templates.
 
+    .PARAMETER Workbook
+    Optional. Name of the workbook folder to build.
+
     .EXAMPLE
     ./Build-Workbook workbook-name
-    Generates a template the specified workbook.
-
-    .PARAMETER Workbook
-    Name of the workbook folder.
 
-    .PARAMETER Debug
-    Optional. Renders main module and test bicep code to the console instead of generating files. Line numbers map to original file.
+    Generates a template for the specified workbook.
 #>
 Param (
   [Parameter(Position = 0)][string] $Workbook

src/scripts/Invoke-Task.ps1

@@ -9,10 +9,25 @@
     Run this from the /src/scripts folder.
 
     .PARAMETER Task
-    Required. Name of the task to execute.
+    Optional. Name of the task to execute.
 
-    .PARAMETER Silent
-    Optional. Indicates whether Invoke-Build should hide verbose build output. Default = false.
+    .PARAMETER Major
+    Optional. Increments the major version number (x.0). Only applies to version tasks.
+
+    .PARAMETER Minor
+    Optional. Increments the minor version number (0.x). Only applies to version tasks.
+
+    .PARAMETER Patch
+    Optional. Increments the patch version number (0.0.x). Only applies to version tasks.
+
+    .PARAMETER Prerelease
+    Optional. Increments the prerelease version number (0.0.0-ooo.x). Only applies to version tasks.
+
+    .PARAMETER Label
+    Optional. Indicates the label to use for prerelease versions. Allowed: dev, rc, alpha, preview. Only applies to version tasks.
+
+    .PARAMETER Version
+    Optional. Sets the version number to an explicit value. Only applies to version tasks.
 
     .PARAMETER Reset
     Optional. Indicates whether the BuildHelper module should be re-compiled. Use this when changing build tasks and scripts. Default = false.

src/scripts/New-Directory.ps1

@@ -2,10 +2,15 @@
 # Licensed under the MIT License.
 
 <#
-.SYNOPSIS
+    .SYNOPSIS
     Creates a new directory if it doesn't already exist. Does not return an object.
-.EXAMPLE
+
+    .PARAMETER Path
+    Path of the directory to create.
+
+    .EXAMPLE
     ./New-Directory foo
+
     Creates the "foo" directory.
 #>
 Param (

src/scripts/Publish-Toolkit.ps1

@@ -6,19 +6,25 @@
     Publishes a toolkit template, module, or documentation to its destination repo.
 
     .PARAMETER Template
-    Name of the template or module to publish. Default = * (all templates).
+    Optional. Name of the template or module to publish. Default = * (all templates).
 
     .PARAMETER QuickstartRepo
     Optional. Name of the folder where the Azure Quickstart Templates repo is cloned. Default = azure-quickstart-templates.
 
     .PARAMETER RegistryRepo
     Optional. Name of the folder where the Bicep Registry repo is cloned. Default = bicep-registry-modules.
 
+    .PARAMETER AppInsightsRepo
+    Optional. Name of the folder where the Application Insights Workbooks repo is cloned. Default = Application-Insights-Workbooks.
+
+    .PARAMETER DocsRepo
+    Optional. Name of the folder where the Partner Center documentation repo is cloned. Default = partner-center-pr.
+
     .PARAMETER Build
-    Optional. Indicates whether the the Build-Toolkit command should be executed first. Default = false.
+    Optional. Indicates whether the Build-Toolkit command should be executed first. Default = false.
 
     .PARAMETER Branch
-    Optional. Indicates whether the changes should be committed to a new branch in the Git repo. Default = false.
+    Optional. Indicates whether the changes should be committed to a new branch in the Git repo. Alias: Commit. Default = false.
 
     .EXAMPLE
     ./Publish-Toolkit "finops-hub"

src/scripts/README.md

@@ -300,13 +300,15 @@ Examples:
 
 [Publish-Toolkit.ps1](./Publish-Toolkit.ps1) publishes a toolkit template, module, or documentation to its destination repo.
 
-| Parameter         | Description                                                                                                             |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `‑Template`       | Name of the template or module to publish. Default = * (all templates).                                                 |
-| `‑QuickstartRepo` | Optional. Name of the folder where the Azure Quickstart Templates repo is cloned. Default = azure-quickstart-templates. |
-| `‑RegistryRepo`   | Optional. Name of the folder where the Bicep Registry repo is cloned. Default = bicep-registry-modules.                 |
-| `‑Build`          | Optional. Indicates whether the the Build-Toolkit command should be executed first. Default = false.                    |
-| `‑Branch`         | Optional. Indicates whether the changes should be committed to a new branch in the Git repo. Default = false.           |
+| Parameter          | Description                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `‑Template`        | Optional. Name of the template or module to publish. Default = * (all templates).                                               |
+| `‑QuickstartRepo`  | Optional. Name of the folder where the Azure Quickstart Templates repo is cloned. Default = azure-quickstart-templates.         |
+| `‑RegistryRepo`    | Optional. Name of the folder where the Bicep Registry repo is cloned. Default = bicep-registry-modules.                         |
+| `‑AppInsightsRepo` | Optional. Name of the folder where the Application Insights Workbooks repo is cloned. Default = Application-Insights-Workbooks. |
+| `‑DocsRepo`        | Optional. Name of the folder where the Partner Center documentation repo is cloned. Default = partner-center-pr.                |
+| `‑Build`           | Optional. Indicates whether the Build-Toolkit command should be executed first. Default = false.                                |
+| `‑Branch`          | Optional. Indicates whether the changes should be committed to a new branch in the Git repo. Alias: Commit. Default = false.    |
 
 Examples: