Complete and standardize the PowerShell API surface

Build/Export-WebsiteArtifacts.ps1

@@ -181,6 +181,22 @@ try {
 $apiRoot = Join-Path $ArtifactsRoot 'apidocs\powershell'
 New-Item -ItemType Directory -Path $apiRoot -Force | Out-Null
 
+$sourceExamplesRoot = Join-Path $RepositoryRoot 'Examples'
+$apiExamplesRoot = Join-Path $apiRoot 'examples'
+$artifactsBoundary = [System.IO.Path]::GetFullPath($ArtifactsRoot).TrimEnd(
+    [System.IO.Path]::DirectorySeparatorChar,
+    [System.IO.Path]::AltDirectorySeparatorChar) + [System.IO.Path]::DirectorySeparatorChar
+$resolvedExamplesRoot = [System.IO.Path]::GetFullPath($apiExamplesRoot)
+if (-not $resolvedExamplesRoot.StartsWith($artifactsBoundary, [System.StringComparison]::OrdinalIgnoreCase)) {
+    throw "Refusing to refresh examples outside the website artifacts root: $resolvedExamplesRoot"
+}
+if (Test-Path -LiteralPath $apiExamplesRoot -PathType Container) {
+    [System.IO.Directory]::Delete($resolvedExamplesRoot, $true)
+}
+New-Item -ItemType Directory -Path $apiExamplesRoot -Force | Out-Null
+Get-ChildItem -LiteralPath $sourceExamplesRoot -Force |
+    Copy-Item -Destination $apiExamplesRoot -Recurse -Force
+
 $apiHelpPath = Join-Path $apiRoot "$moduleName-help.xml"
 $docsHelpPath = Join-Path $RepositoryRoot "Docs\Generated\$moduleName-help.xml"
 New-Item -ItemType Directory -Path (Split-Path -Parent $docsHelpPath) -Force | Out-Null

Build/Export-WebsiteDocumentationCatalog.ps1

@@ -48,13 +48,13 @@ $familyDefinitions = @(
         id = 'pdf'; title = 'PDF'; description = 'Author, inspect, transform, sign, annotate, extract, preflight, and combine PDF files.'
         docs = 'pdf'; api = '/api/powershell/'; examples = 'https://github.com/EvotecIT/PSWriteOffice/tree/main/Examples/Pdf'
         samples = @('New-OfficePdf', 'Join-OfficePdf', 'Get-OfficePdfPreflight', 'Set-OfficePdfSignature')
-        match = { param($name) $name -match 'OfficePdf' }
+        match = { param($name) $name -match 'OfficePdf|OfficeDocumentPdf' }
     }
     [ordered]@{
         id = 'reader'; title = 'Reader and extraction'; description = 'Detect formats and extract normalized documents, chunks, tables, visuals, assets, and ingest results.'
         docs = 'reader'; api = '/api/powershell/'; examples = 'https://github.com/EvotecIT/PSWriteOffice/tree/main/Examples/Reader'
         samples = @('New-OfficeDocumentReader', 'Get-OfficeDocumentChunk', 'Get-OfficeDocumentTable', 'Search-OfficeDocument')
-        match = { param($name) $name -match 'OfficeDocument' -and $name -ne 'Get-OfficeDocumentPageMarkdown' }
+        match = { param($name) ($name -match 'OfficeDocument' -and $name -notin 'Get-OfficeDocumentPageMarkdown', 'Export-OfficeDocumentPdf') -or $name -match 'OfficeReader' }
     }
     [ordered]@{
         id = 'confluence'; title = 'Confluence Cloud'; description = 'Plan and publish pages, preserve managed sections, and transfer attachments through OfficeIMO.Confluence.'
@@ -87,9 +87,9 @@ $familyDefinitions = @(
         match = { param($name) $name -match 'OfficeCsv' }
     }
     [ordered]@{
-        id = 'open-document'; title = 'OpenDocument'; description = 'Create, read, and save ODT, ODS, and ODP workflows.'
+        id = 'open-document'; title = 'OpenDocument'; description = 'Compose, read, convert, and save ODT, ODS, and ODP workflows.'
         docs = 'open-text-formats'; api = '/api/powershell/'; examples = 'https://github.com/EvotecIT/PSWriteOffice/tree/main/Examples'
-        samples = @('New-OfficeOpenDocument', 'Get-OfficeOpenDocument', 'Save-OfficeOpenDocument')
+        samples = @('New-OfficeOpenDocument', 'Add-OfficeOpenDocumentParagraph', 'Set-OfficeOpenDocumentCell', 'Save-OfficeOpenDocument')
         match = { param($name) $name -match 'OfficeOpenDocument' }
     }
     [ordered]@{
@@ -114,7 +114,7 @@ $familyDefinitions = @(
         id = 'html'; title = 'HTML assets'; description = 'Export images and review surfaces used by document-to-HTML workflows.'
         docs = 'open-text-formats'; api = '/api/powershell/'; examples = 'https://github.com/EvotecIT/PSWriteOffice/tree/main/Examples'
         samples = @('Export-OfficeHtmlImage')
-        match = { param($name) $name -eq 'Export-OfficeHtmlImage' }
+        match = { param($name) $name -match 'OfficeHtml' }
     }
     [ordered]@{
         id = 'visuals'; title = 'Cross-format visuals'; description = 'Convert reusable visual artifacts for Word, Excel, PowerPoint, and PDF placement.'

Docs/Add-OfficeExcelAutoFilter.md

@@ -11,12 +11,12 @@ Adds an AutoFilter to the current worksheet.
 ## SYNTAX
 ### Context (Default)
 ```powershell
-Add-OfficeExcelAutoFilter [-Range] <string> [-Criteria <hashtable>] [<CommonParameters>]
+Add-OfficeExcelAutoFilter [-Range] <string> [-Criteria <hashtable>] [-PassThru] [<CommonParameters>]
 ```
 
 ### Document
 ```powershell
-Add-OfficeExcelAutoFilter [-Range] <string> -Document <ExcelDocument> [-Sheet <string>] [-SheetIndex <Int32>] [-Criteria <hashtable>] [<CommonParameters>]
+Add-OfficeExcelAutoFilter [-Range] <string> -Document <ExcelDocument> [-Sheet <string>] [-SheetIndex <Int32>] [-Criteria <hashtable>] [-PassThru] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -72,6 +72,22 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
+### -PassThru
+Emit the object created or changed by the command.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: Context, Document
+Aliases: None
+Possible values:
+
+Required: False
+Position: named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Range
 A1 range to apply AutoFilter.
 

Docs/Add-OfficeExcelPackageMetadata.md

@@ -16,7 +16,7 @@ Add-OfficeExcelPackageMetadata -Kind <string> -Xml <string> [-WorksheetName <str
 
 ### Path
 ```powershell
-Add-OfficeExcelPackageMetadata [-InputPath] <string> -Kind <string> -Xml <string> [-WorksheetName <string>] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
+Add-OfficeExcelPackageMetadata [-Path] <string> -Kind <string> -Xml <string> [-WorksheetName <string>] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### Document
@@ -55,22 +55,6 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
-### -InputPath
-Workbook path to update.
-
-```yaml
-Type: String
-Parameter Sets: Path
-Aliases: Path, FilePath
-Possible values:
-
-Required: True
-Position: 0
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -Kind
 Metadata kind to add.
 
@@ -103,6 +87,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Path
+Workbook path to update.
+
+```yaml
+Type: String
+Parameter Sets: Path
+Aliases: InputPath, FilePath
+Possible values:
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -WorksheetName
 Worksheet for query-table metadata. Defaults to the current DSL sheet, or the first worksheet outside the DSL.
 

Docs/Add-OfficeExcelPageBreak.md

@@ -16,7 +16,7 @@ Add-OfficeExcelPageBreak [-Sheet <string>] [-SheetIndex <Int32>] [-Row <int[]>]
 
 ### Path
 ```powershell
-Add-OfficeExcelPageBreak [-InputPath] <string> [-Sheet <string>] [-SheetIndex <Int32>] [-Row <int[]>] [-Column <int[]>] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
+Add-OfficeExcelPageBreak [-Path] <string> [-Sheet <string>] [-SheetIndex <Int32>] [-Row <int[]>] [-Column <int[]>] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### Document
@@ -70,33 +70,33 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
-### -InputPath
-Workbook path to update.
+### -PassThru
+Emit page-break records after adding them.
 
 ```yaml
-Type: String
-Parameter Sets: Path
-Aliases: Path, FilePath
+Type: SwitchParameter
+Parameter Sets: Context, Path, Document
+Aliases: None
 Possible values:
 
-Required: True
-Position: 0
+Required: False
+Position: named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -PassThru
-Emit page-break records after adding them.
+### -Path
+Workbook path to update.
 
 ```yaml
-Type: SwitchParameter
-Parameter Sets: Context, Path, Document
-Aliases: None
+Type: String
+Parameter Sets: Path
+Aliases: InputPath, FilePath
 Possible values:
 
-Required: False
-Position: named
+Required: True
+Position: 0
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False

Docs/Add-OfficeExcelPowerQueryMetadata.md

@@ -16,7 +16,7 @@ Add-OfficeExcelPowerQueryMetadata -Name <string> [-WorksheetName <string>] [-Que
 
 ### Path
 ```powershell
-Add-OfficeExcelPowerQueryMetadata [-InputPath] <string> -Name <string> [-WorksheetName <string>] [-QueryTableName <string>] [-Description <string>] [-CommandText <string>] [-RefreshOnOpen] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
+Add-OfficeExcelPowerQueryMetadata [-Path] <string> -Name <string> [-WorksheetName <string>] [-QueryTableName <string>] [-Description <string>] [-CommandText <string>] [-RefreshOnOpen] [-PassThru] [-WhatIf] [-Confirm] [<CommonParameters>]
 ```
 
 ### Document
@@ -92,22 +92,6 @@ Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
-### -InputPath
-Workbook path to update.
-
-```yaml
-Type: String
-Parameter Sets: Path
-Aliases: Path, FilePath
-Possible values:
-
-Required: True
-Position: 0
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -Name
 Connection name stored in workbook metadata.
 
@@ -140,6 +124,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Path
+Workbook path to update.
+
+```yaml
+Type: String
+Parameter Sets: Path
+Aliases: InputPath, FilePath
+Possible values:
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -QueryTableName
 Optional query-table name.
 

Docs/Add-OfficeExcelReportCallout.md

@@ -11,7 +11,7 @@ Adds a colored callout block to the current Excel report sheet.
 ## SYNTAX
 ### __AllParameterSets
 ```powershell
-Add-OfficeExcelReportCallout [[-Kind] <string>] [-Title] <string> [-Body] <string> [-WidthColumns <int>] [<CommonParameters>]
+Add-OfficeExcelReportCallout [[-Kind] <string>] [-Title] <string> [-Body] <string> [-WidthColumns <int>] [-PassThru] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -64,6 +64,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -PassThru
+Emit the object created or changed by the command.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: __AllParameterSets
+Aliases: None
+Possible values:
+
+Required: False
+Position: named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Title
 Callout title.
 

Docs/Add-OfficeExcelReportKpiRow.md

@@ -11,7 +11,7 @@ Adds a KPI row to the current Excel report sheet.
 ## SYNTAX
 ### __AllParameterSets
 ```powershell
-Add-OfficeExcelReportKpiRow [-InputObject] <Object> [-PerRow <int>] [-LabelFillColor <string>] [<CommonParameters>]
+Add-OfficeExcelReportKpiRow [-InputObject] <Object> [-PerRow <int>] [-LabelFillColor <string>] [-PassThru] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -64,6 +64,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -PassThru
+Emit the object created or changed by the command.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: __AllParameterSets
+Aliases: None
+Possible values:
+
+Required: False
+Position: named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -PerRow
 Number of KPI cards per rendered row.
 

Docs/Add-OfficeExcelReportLegend.md

@@ -11,7 +11,7 @@ Adds a legend table to the current Excel report sheet.
 ## SYNTAX
 ### __AllParameterSets
 ```powershell
-Add-OfficeExcelReportLegend [[-Title] <string>] -Header <string[]> -InputObject <Object[]> [-FirstColumnFillByValue <hashtable>] [-HeaderFillColor <string>] [-CaseSensitive] [<CommonParameters>]
+Add-OfficeExcelReportLegend [[-Title] <string>] -Header <string[]> -InputObject <Object[]> [-FirstColumnFillByValue <hashtable>] [-HeaderFillColor <string>] [-CaseSensitive] [-PassThru] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -116,6 +116,22 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -PassThru
+Emit the object created or changed by the command.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: __AllParameterSets
+Aliases: None
+Possible values:
+
+Required: False
+Position: named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Title
 Optional legend title.
 

Docs/Add-OfficeExcelReportParagraph.md

@@ -11,7 +11,7 @@ Adds a paragraph line to the current Excel report sheet.
 ## SYNTAX
 ### __AllParameterSets
 ```powershell
-Add-OfficeExcelReportParagraph [-Text] <string> [<CommonParameters>]
+Add-OfficeExcelReportParagraph [-Text] <string> [-PassThru] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -33,6 +33,22 @@ Adds prose to an OfficeIMO-composed Excel report sheet.
 
 ## PARAMETERS
 
+### -PassThru
+Emit the object created or changed by the command.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: __AllParameterSets
+Aliases: None
+Possible values:
+
+Required: False
+Position: named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Text
 Paragraph text.