Migrate to Microsoft.PowerShell.PlatyPS and psake v5

.gitignore

@@ -19,3 +19,6 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 bun-error.log
+
+# psake v5 task cache
+.psake/

CLAUDE.md

@@ -33,6 +33,8 @@ The build system uses **PowerShell + psake** for orchestration, with Docusaurus/
 .\build.ps1 -Help
 ```
 
+> **Token efficiency**: Always prefer `.\build.ps1 -Quiet -Task <task>` when running builds from Claude Code. The `-Quiet` flag suppresses verbose console output and returns a structured `PsakeBuildResult` object, which dramatically reduces token usage while still capturing success/failure.
+
 **Important**: The `Server` task runs `bun run serve` which serves the production build. For local development with hot-reload, use:
 ```powershell
 .\build.ps1 -Task Init        # Install dependencies first
@@ -54,11 +56,11 @@ bun start                     # Then start dev server directly
 
 Command documentation is **auto-generated** from the psake PowerShell module:
 
-- **Generator**: `New-DocusaurusHelp` from `Alt3.Docusaurus.Powershell` module
+- **Generator**: `New-PsakeDocusaurusHelp` in `scripts/New-PsakeDocusaurusHelp.ps1`, powered by `Microsoft.PowerShell.PlatyPS`
 - **Source**: psake module help (from the main psake repository)
 - **Output**: `docs/commands/*.mdx` files
 - **Sidebar**: Auto-imported via `docs/commands/docusaurus.sidebar.js`
-- **Configuration**: See `$docusaurusOptions` in `psakeFile.ps1:12-34`
+- **Configuration**: See `$docusaurusOptions` in `psakeFile.ps1`
 
 **Never manually edit files in `docs/commands/`** - they will be overwritten. Edit the source help in the [psake repository](https://github.com/psake/psake) instead.
 

build.ps1

@@ -2,7 +2,7 @@
 param(
   # Build task(s) to execute
   [parameter(ParameterSetName = 'task', position = 0)]
-  [ArgumentCompleter( {
+  [ArgumentCompleter({
       param($Command, $Parameter, $WordToComplete, $CommandAst, $FakeBoundParams)
       try {
         Get-PSakeScriptTasks -BuildFile './psakeFile.ps1' -ErrorAction 'Stop' |
@@ -12,29 +12,40 @@ param(
         @()
       }
     })]
-  [string[]]$Task = 'default',
+  [string[]] $Task = 'default',
 
   # Bootstrap dependencies
-  [switch]$Bootstrap,
+  [switch] $Bootstrap,
 
   # List available build tasks
   [parameter(ParameterSetName = 'Help')]
-  [switch]$Help,
+  [switch] $Help,
+
+  # Suppress console output; returns structured PsakeBuildResult.
+  # LLM should prefer this option.
+  [switch] $Quiet,
+
+  # Bypass task caching for this run
+  [switch] $NoCache,
+
+  # Output format for CI integration
+  [ValidateSet('Default', 'JSON', 'GitHubActions')]
+  [string] $OutputFormat = 'Default',
 
   # Optional properties to pass to psake
-  [hashtable]$Properties,
+  [hashtable] $Properties,
 
   # Optional parameters to pass to psake
-  [hashtable]$Parameters
+  [hashtable] $Parameters
 )
 
 $ErrorActionPreference = 'Stop'
 
 # Bootstrap dependencies
-if ($Bootstrap.IsPresent) {
+if ($Bootstrap) {
   PackageManagement\Get-PackageProvider -Name Nuget -ForceBootstrap | Out-Null
   Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
-  if ((Test-Path -Path ./requirements.psd1)) {
+  if (Test-Path -Path './requirements.psd1') {
     if (-not (Get-Module -Name PSDepend -ListAvailable)) {
       Install-Module -Name PSDepend -Repository PSGallery -Scope CurrentUser -Force
     }
@@ -51,6 +62,16 @@ if ($PSCmdlet.ParameterSetName -eq 'Help') {
   Get-PSakeScriptTasks -BuildFile $psakeFile |
     Format-Table -Property Name, Description, Alias, DependsOn
 } else {
-  Invoke-Psake -BuildFile $psakeFile -TaskList $Task -NoLogo -Properties $Properties -Parameters $Parameters
-  exit ([int](-not $psake.build_success))
+  $invokeSplat = @{
+    BuildFile = $psakeFile
+    TaskList = $Task
+    NoLogo = $true
+    Properties = $Properties
+    Parameters = $Parameters
+    Quiet = $Quiet
+    NoCache = $NoCache
+    OutputFormat = $OutputFormat
+  }
+  $result = Invoke-Psake @invokeSplat
+  exit ([int](-not $result.Success))
 }

docs/commands/Assert.mdx

@@ -22,9 +22,10 @@ Helper function for "Design by Contract" assertion checking.
 
 ## SYNTAX
 
-```powershell
-Assert [-conditionToCheck] <Object> [-failureMessage] <String> [-ProgressAction <ActionPreference>]
- [<CommonParameters>]
+### __AllParameterSets
+
+```
+Assert [-ConditionToCheck] <Object> [-FailureMessage] <string> [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -39,6 +40,7 @@ This is a helper function that makes the code less noisy by eliminating many of
 Assert $false "This always throws an exception"
 ```
 
+
 Example of an assertion that will always fail.
 
 ### EXAMPLE 2
@@ -47,11 +49,12 @@ Example of an assertion that will always fail.
 Assert ( ($i % 2) -eq 0 ) "$i is not an even number"
 ```
 
+
 This exmaple may throw an exception if $i is not an even number
 
 Note:
 It might be necessary to wrap the condition with paranthesis to force PS to evaluate the condition
-so that a boolean value is calculated and passed into the 'conditionToCheck' parameter.
+so that a boolean value is calculated and passed into the 'ConditionToCheck' parameter.
 
 Example:
     Assert 1 -eq 2 "1 doesn't equal 2"
@@ -65,57 +68,54 @@ Assert (1 -eq 2) "1 doesn't equal 2"
 
 ## PARAMETERS
 
-### -conditionToCheck
+### -ConditionToCheck
 
 The boolean condition to evaluate
 
 ```yaml
-Type: Object
-Parameter Sets: (All)
-Aliases:
-
-Required: True
-Position: 1
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
+Type: System.Object
+DefaultValue: ''
+SupportsWildcards: false
+Aliases: []
+ParameterSets:
+- Name: (All)
+  Position: 0
+  IsRequired: true
+  ValueFromPipeline: false
+  ValueFromPipelineByPropertyName: false
+  ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
 ```
 
-### -failureMessage
+### -FailureMessage
 
-The error message used for the exception if the conditionToCheck parameter is false
+The error message used for the exception if the ConditionToCheck parameter is false
 
 ```yaml
-Type: String
-Parameter Sets: (All)
-Aliases:
-
-Required: True
-Position: 2
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
-### -ProgressAction
-
-\{\{ Fill ProgressAction Description \}\}
-
-```yaml
-Type: ActionPreference
-Parameter Sets: (All)
-Aliases: proga
-
-Required: False
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
+Type: System.String
+DefaultValue: ''
+SupportsWildcards: false
+Aliases: []
+ParameterSets:
+- Name: (All)
+  Position: 1
+  IsRequired: true
+  ValueFromPipeline: false
+  ValueFromPipelineByPropertyName: false
+  ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
 ```
 
 ### CommonParameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
+-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
+-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
+[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 
@@ -125,26 +125,5 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## RELATED LINKS
 
-[Exec](Exec.mdx)
-
-[FormatTaskName](FormatTaskName.mdx)
-
-[Framework](Framework.mdx)
-
-[Get-PSakeScriptTasks](Get-PSakeScriptTasks.mdx)
-
-[Include](Include.mdx)
-
-[Invoke-psake](Invoke-psake.mdx)
-
-[Properties](Properties.mdx)
-
-[Task](Task.mdx)
-
-[TaskSetup](TaskSetup.mdx)
-
-[TaskTearDown](TaskTearDown.mdx)
-
 ## VERSION
-
-*This page was generated using comment-based help in [Psake 4.9.0](https://github.com/psake/psake).*
+*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).*

docs/commands/BuildSetup.mdx

@@ -0,0 +1,104 @@
+---
+id: BuildSetup
+title: BuildSetup
+description: Help page for the PowerShell Psake "BuildSetup" command
+keywords:
+  - PowerShell
+  - Psake
+  - Help
+  - Documentation
+hide_title: false
+hide_table_of_contents: false
+custom_edit_url: null
+---
+
+:::info This page was generated
+Contributions are welcome in [Psake-repo](https://github.com/psake/psake).
+:::
+
+:::note Since Psake 5.0
+This command was introduced in Psake 5.0 and is not available in earlier versions.
+:::
+
+## SYNOPSIS
+
+Adds a scriptblock that will be executed once at the beginning of the build
+
+## SYNTAX
+
+### __AllParameterSets
+
+```
+BuildSetup [-Setup] <scriptblock> [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+This function will accept a scriptblock that will be executed once at the
+beginning of the build.
+
+## EXAMPLES
+
+### EXAMPLE 1
+
+```powershell
+Task default -Depends Test
+Task Test -Depends Compile, Clean {
+}
+Task Compile -Depends Clean {
+}
+Task Clean {
+}
+BuildSetup {
+    "Running 'BuildSetup'"
+}
+```
+
+
+The script above produces the following output:
+Running 'BuildSetup'
+Executing task, Clean...
+Executing task, Compile...
+Executing task, Test...
+Build Succeeded
+
+## PARAMETERS
+
+### -Setup
+
+A scriptblock to execute
+
+```yaml
+Type: System.Management.Automation.ScriptBlock
+DefaultValue: ''
+SupportsWildcards: false
+Aliases: []
+ParameterSets:
+- Name: (All)
+  Position: 0
+  IsRequired: true
+  ValueFromPipeline: false
+  ValueFromPipelineByPropertyName: false
+  ValueFromRemainingArguments: false
+DontShow: false
+AcceptedValues: []
+HelpMessage: ''
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
+-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,
+-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see
+[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS
+
+## VERSION
+*This page was generated using comment-based help in [Psake 5.0.3](https://github.com/psake/psake).*