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,34 +12,45 @@ 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
     }
     Import-Module -Name PSDepend -Verbose:$false
-    Invoke-PSDepend -Path './requirements.psd1' -Install -Import -Force -WarningAction SilentlyContinue
+    Invoke-PSDepend -Path './requirements.psd1' -Install -Force -WarningAction SilentlyContinue
   } else {
     Write-Warning 'No [requirements.psd1] found. Skipping build dependency installation.'
   }
@@ -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,14 +22,17 @@ 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
 
-This is a helper function that makes the code less noisy by eliminating many of the "if" statements that are normally required to verify assumptions in the code.
+This is a helper function that makes the code less noisy by eliminating many
+of the "if" statements that are normally required to verify assumptions in
+the code.
 
 ## EXAMPLES
 
@@ -39,6 +42,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,75 +51,82 @@ 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.
+This example may throw an exception if $i is not an even number
 
-Example:
-    Assert 1 -eq 2 "1 doesn't equal 2"
+It might be necessary to wrap the condition with parentheses to force
+PowerShell to evaluate the condition so that a boolean value is calculated
+and passed into the 'ConditionToCheck' parameter.
 
-PS will pass 1 into the condtionToCheck variable and PS will look for a parameter called "eq" and
-throw an exception with the following message "A parameter cannot be found that matches parameter name 'eq'"
+### EXAMPLE 3
 
-The solution is to wrap the condition in () so that PS will evaluate it first.
-
-Assert (1 -eq 2) "1 doesn't equal 2"
+```powershell
+Assert 1 -eq 2 "1 doesn't equal 2"
+```
 
-## PARAMETERS
 
-### -conditionToCheck
+PowerShell will pass 1 into the ConditionToCheck variable and PS will look
+for a parameter called "eq" and throw an exception with the following
+message "A parameter cannot be found that matches parameter name 'eq'"
 
-The boolean condition to evaluate
+The solution is to wrap the condition in () so that PowerShell will evaluate
+it first.
 
-```yaml
-Type: Object
-Parameter Sets: (All)
-Aliases:
-
-Required: True
-Position: 1
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
+```powershell
+Assert (1 -eq 2) "1 doesn't equal 2"
 ```
 
-### -failureMessage
+## PARAMETERS
 
-The error message used for the exception if the conditionToCheck parameter is false
+### -ConditionToCheck
+
+The boolean condition to evaluate
 
 ```yaml
-Type: String
-Parameter Sets: (All)
-Aliases:
-
-Required: True
-Position: 2
-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: ''
 ```
 
-### -ProgressAction
+### -FailureMessage
 
-\{\{ Fill ProgressAction Description \}\}
+The error message used for the exception if the ConditionToCheck parameter
+is false
 
 ```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 +136,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.4](https://github.com/psake/psake).*