diff --git a/Docs/PowerForge.Web.ApiDocs.md b/Docs/PowerForge.Web.ApiDocs.md
index 2a3b59e6..1581f347 100644
--- a/Docs/PowerForge.Web.ApiDocs.md
+++ b/Docs/PowerForge.Web.ApiDocs.md
@@ -43,6 +43,11 @@ Overview identity and quick start:
   - `short` keeps short names only
   - `namespace-suffix` (default) disambiguates duplicates as `Type (Namespace.Part)`
   - `full` uses full type names
+- `generateGitFreshness` (pipeline) / `--git-freshness` (CLI) enables opt-in git freshness metadata:
+  - `gitFreshnessNewDays` / `--git-freshness-new-days` controls the `new` window (default `14`)
+  - `gitFreshnessUpdatedDays` / `--git-freshness-updated-days` controls the `updated` window (default `90`)
+  - emitted JSON adds `freshness.status`, `freshness.lastModifiedUtc`, `freshness.commitSha`, `freshness.ageDays`, and a normalized `freshness.sourcePath` (relative when possible; file-name fallback otherwise)
+  - HTML badges render only for `new` / `updated`; `stable` remains unbadged to avoid visual noise
 
 If your site uses `Navigation.Profiles` (route/layout specific menus), set:
 - `navContextPath` (defaults to `/`)
@@ -150,6 +155,13 @@ Overview chips:
 - `.type-chip` – type chip link
 - `.type-chip.<kind>` – kind class (`class`, `struct`, `enum`, `interface`, `delegate`)
 - `.type-chip` includes `data-kind` and `data-namespace` for filtering
+- `.freshness-badge` – freshness badge shell
+- `.freshness-badge.new` – recent/new state
+- `.freshness-badge.updated` – recently updated state
+- `.type-freshness-badge` – type detail header placement
+- `.type-list-freshness` – sidebar row placement
+- `.quick-card-freshness` – quick-start card placement
+- `.type-chip-freshness` – namespace chip placement
 
 Member layout:
 - `.member-toolbar` – member filter toolbar
@@ -203,6 +215,11 @@ Member layout:
 - `.derived-list` – derived types list
 - `.type-parameters` – type parameter section
 - `.type-examples` – example section
+- `.example-media` – example media figure wrapper
+- `.example-media-frame` – media surface (image/video/link frame)
+- `.example-media-link` – terminal/download link for non-inline example media
+- `.example-media-caption` – media caption
+- `.example-media-meta` – capture recency / freshness metadata line
 - `.type-see-also` – see also section
 
 ## JavaScript expectations
@@ -261,6 +278,24 @@ in the pipeline or pass `--documented-only` to the CLI.
 `<see cref="...">` and `<seealso cref="...">` tags are converted into links when the
 referenced type exists in the generated API docs.
 
+XML-doc `<example>` blocks can also include optional media nodes for richer API examples:
+
+```xml
+<example>
+  <code>Sample.Run();</code>
+  <image src="/images/sample-output.png" alt="Rendered output" caption="Example screenshot." />
+  <media kind="terminal" src="/casts/sample.cast" title="Terminal playback" caption="Recorded terminal output." poster="/images/sample-terminal.png" mimeType="application/x-asciicast" />
+</example>
+```
+
+Supported media nodes:
+- `<image ... />` / `<img ... />` / `<screenshot ... />`
+- `<video ... />`
+- `<terminal ... />`
+- `<media kind="image|video|terminal|link" ... />`
+
+Generated JSON keeps those entries under `examples[]` with `kind: "media"` and a structured `media` object (`type`, `url`, `title`, `alt`, `caption`, `posterUrl`, `mimeType`, `width`, `height`, optional `capturedAtUtc`, optional `sourceUpdatedAtUtc`).
+
 ## PowerShell help
 
 Set `type: PowerShell` and point `help`/`helpPath` to a PowerShell help XML file
@@ -352,6 +387,7 @@ Notes:
 - Source-link diagnostics also emit `[PFWEB.APIDOCS.SOURCE]` warnings for common misconfigurations:
   - `sourceUrlMappings` prefixes that never match discovered source paths
   - likely duplicated GitHub path prefixes (a common cause of 404 "Edit on GitHub" links)
+  - `sourceRoot` pointing one level above the GitHub repo while `sourceUrl` targets a single repo without `{root}`
   - source URL templates missing a path token (`{path}`, `{pathNoRoot}`, or `{pathNoPrefix}`)
   - unsupported source URL template tokens (anything outside `{path}`, `{line}`, `{root}`, `{pathNoRoot}`, `{pathNoPrefix}`)
 - Display + member diagnostics:
@@ -360,4 +396,43 @@ Notes:
 - PowerShell syntax signatures append `[<CommonParameters>]` for command kinds that support common parameters,
   and docs pages render a dedicated `Common Parameters` section with an `about_CommonParameters` reference.
 - PowerShell fallback examples are enabled by default (`generatePowerShellFallbackExamples:true`) and can source snippets from `psExamplesPath` or discovered `Examples/` folders.
+- When importing script-based fallback examples, command-specific files (for example `Invoke-Thing.ps1`) are preferred over generic demo scripts when multiple snippets match the same command.
+- When PowerShell help has no authored examples, generated fallback examples prefer the most user-friendly parameter sets and can emit multiple examples per command up to `powerShellFallbackExampleLimit`.
+- API docs now emit `[PFWEB.APIDOCS.POWERSHELL]` warnings when PowerShell commands rely only on generated fallback examples, so CI can distinguish “has some example” from “has authored examples”.
+- Optional PowerShell example validation can parse imported example scripts with the PowerShell parser before publish:
+  - CLI: `--validate-ps-examples`
+  - Pipeline: `validatePowerShellExamples: true`
+  - report path: `--ps-example-validation-report <file>` / `powerShellExampleValidationReport`
+  - timeout: `--ps-example-validation-timeout <seconds>` / `powerShellExampleValidationTimeoutSeconds`
+  - fail on invalid scripts: `--fail-on-ps-example-validation` / `failOnPowerShellExampleValidation: true`
+- Optional matched-example execution can run curated PowerShell example scripts after syntax validation:
+  - CLI: `--execute-ps-examples`
+  - Pipeline: `executePowerShellExamples: true`
+  - execution timeout: `--ps-example-execution-timeout <seconds>` / `powerShellExampleExecutionTimeoutSeconds`
+  - fail on execution failures: `--fail-on-ps-example-execution` / `failOnPowerShellExampleExecution: true`
+  - only scripts that both parse cleanly and reference documented commands are executed
+  - enabling execution implicitly enables validation
+- Validation reports default to `powershell-example-validation.json` under the API output root when validation is enabled.
+- Validation JSON normalizes help/example/artifact paths when possible, so reports do not leak build-agent absolute paths. Execution entries also include captured `executionStdOut`, `executionStdErr`, and `executionSkippedReason` when available.
+- When execution is enabled, report writing also emits reusable transcript artifacts under a sibling `powershell-example-validation-artifacts/` folder and records each path as `executionArtifactPath`.
+- When generated docs also receive that validation result, successful imported PowerShell examples can surface those transcript artifacts as terminal-style example media links in the rendered API reference.
+- Imported PowerShell example scripts can also ship richer playback sidecars next to the `.ps1` file: matching `.cast` / `.asciinema` files are staged into API output automatically, and matching `.png` / `.jpg` / `.jpeg` / `.webp` files are used as poster art when present.
+- When imported terminal media exists, PowerForge also writes `powershell-example-media-manifest.json` under the API output root so sites and CI jobs can diff capture history, health flags, and staged media linkage per command.
+- Generated PowerShell playback/transcript media also records `capturedAtUtc` and `sourceUpdatedAtUtc`, so rendered docs can show when a terminal asset was captured and when the backing example script last changed.
+- The generator also emits `[PFWEB.APIDOCS.POWERSHELL]` warnings when curated playback sidecars look unhealthy: unsupported same-name sidecars (for example `.gif` / `.mp4` / `.webm`), oversized casts/posters, or stale playback assets that are older than the `.ps1` script they document.
+- Validation emits `[PFWEB.APIDOCS.POWERSHELL]` warnings when imported example scripts fail syntax validation, when a script does not reference any documented command from the selected help file, or when a matched example script fails execution.
+- PowerShell `examples` entries in generated JSON now include an `origin` field when PowerForge can identify provenance:
+  - `AuthoredHelp` for examples from MAML help XML
+  - `ImportedScript` for examples imported from `psExamplesPath` / `Examples/`
+  - `GeneratedFallback` for auto-generated fallback examples
+- Docs-template HTML now surfaces that provenance with example badges, so readers can immediately tell whether a snippet was authored in help, imported from a curated script, or generated as fallback guidance.
+- Coverage reports now split PowerShell example coverage into `authoredHelpCodeExamples`, `importedScriptCodeExamples`, and `generatedFallbackCodeExamples`, alongside the existing `generatedFallbackOnlyExamples` guardrail.
+- Coverage reports also track richer imported playback quality via `importedScriptPlaybackMedia`, `importedScriptPlaybackMediaWithPoster`, and `importedScriptPlaybackMediaWithoutPoster`, plus command lists for playback media usage and posterless playback assets.
+- Coverage reports also track playback asset-health issues via `importedScriptPlaybackMediaUnsupportedSidecars`, `importedScriptPlaybackMediaOversizedAssets`, and `importedScriptPlaybackMediaStaleAssets`, with matching command lists so CI can flag rough media curation precisely.
+- API generation emits `[PFWEB.APIDOCS.POWERSHELL]` warnings when imported playback media exists without matching poster art, so teams can catch rough terminal embeds before publish.
+- API generation also emits `[PFWEB.APIDOCS.POWERSHELL]` warnings for unhealthy playback assets, but those issues are now measurable in coverage too instead of living only in console warnings.
+- Pipeline coverage thresholds can also gate provenance-specific example quality via `minPowerShellAuthoredHelpCodeExamplesPercent` and `minPowerShellImportedScriptCodeExamplesPercent`.
+- Pipeline coverage thresholds can also gate playback richness via `minPowerShellImportedScriptPlaybackMediaPercent`, `minPowerShellImportedScriptPlaybackMediaWithPosterPercent`, and `maxPowerShellImportedScriptPlaybackMediaWithoutPosterCount`.
+- Pipeline coverage thresholds can also gate playback asset health via `maxPowerShellImportedScriptPlaybackMediaUnsupportedSidecarCount`, `maxPowerShellImportedScriptPlaybackMediaOversizedAssetCount`, and `maxPowerShellImportedScriptPlaybackMediaStaleAssetCount`.
+- Pipeline coverage thresholds can now gate generated-fallback-only quality via `maxPowerShellGeneratedFallbackOnlyExamplePercent` or `maxPowerShellGeneratedFallbackOnlyExampleCount`.
 - In pipeline `apidocs` steps, you can gate quality with coverage thresholds (for example `minPowerShellCodeExamplesPercent`, `minMemberSummaryPercent`) and enforce via `failOnCoverage:true`.
diff --git a/Docs/PowerForge.Web.Pipeline.md b/Docs/PowerForge.Web.Pipeline.md
index 626b0637..aed86fcc 100644
--- a/Docs/PowerForge.Web.Pipeline.md
+++ b/Docs/PowerForge.Web.Pipeline.md
@@ -252,6 +252,10 @@ Notes:
   - `noindex` (default): keep compatibility alias pages, mark them `noindex,follow`
   - `redirect`: emit lightweight alias redirect pages to canonical `/api/<slug>/`
   - `omit`: do not emit flat alias pages
+- `generateGitFreshness` (`generate-git-freshness`) opt-in enables git-aware API freshness metadata/badges
+  - `gitFreshnessNewDays` / `git-freshness-new-days`: max age for `new` badges (default `14`)
+  - `gitFreshnessUpdatedDays` / `git-freshness-updated-days`: max age for `updated` badges (default `90`)
+  - best-effort only: if git metadata is unavailable, generation continues without freshness fields
 - `templateRoot` lets you override built-in templates/assets by placing files like
   `index.html`, `type.html`, `docs-index.html`, `docs-type.html`, `docs.js`,
   `search.js`, or `fallback.css` in that folder
@@ -286,11 +290,12 @@ Notes:
 - Full warning code catalog: `Docs/PowerForge.Web.WarningCodes.md`.
 - If `nav` is provided but your custom `headerHtml`/`footerHtml` fragments do not contain `{{NAV_LINKS}}` / `{{NAV_ACTIONS}}`, the generator emits `[PFWEB.APIDOCS.NAV]` warnings.
 - Source-link diagnostics emit `[PFWEB.APIDOCS.SOURCE]` warnings for mapping issues (for example unmatched `sourceUrlMappings.pathPrefix` or likely duplicated GitHub path prefixes causing 404 source/edit links).
+- Preflight also warns when `sourceRoot` appears to be one level above the targeted GitHub repo and `sourceUrl` does not use `{root}`. This usually means links will render as `<Repo>/<Repo>/...` and 404.
 - Source URL templates are validated preflight:
   - require at least one path token (`{path}`, `{pathNoRoot}`, `{pathNoPrefix}`)
   - warn on unsupported tokens (supported: `{path}`, `{line}`, `{root}`, `{pathNoRoot}`, `{pathNoPrefix}`)
 - Additional `apidocs` preflight checks emit warning codes before generation starts:
-  - `[PFWEB.APIDOCS.SOURCE]` for source-link config issues (for example `sourceUrlMappings` configured without `sourceRoot`/`sourceUrl`, missing `sourceRoot` directory, duplicate mapping prefixes)
+  - `[PFWEB.APIDOCS.SOURCE]` for source-link config issues (for example `sourceUrlMappings` configured without `sourceRoot`/`sourceUrl`, missing `sourceRoot` directory, duplicate mapping prefixes, or `sourceRoot` aimed above the repo root)
   - `[PFWEB.APIDOCS.NAV]` for nav config issues (for example `navSurface` configured without `nav`)
   - `[PFWEB.APIDOCS.POWERSHELL]` for missing PowerShell examples paths when `psExamplesPath` is set
 - `warningPreviewCount`: how many warnings to print to console (default `2` in dev, `5` otherwise)
@@ -309,12 +314,32 @@ Notes:
   - `generateMemberXrefs`: include member/parameter xref entries in the map (default: `true`)
   - `memberXrefKinds`: optional member-kind filter (`constructors,methods,properties,fields,events,extensions,parameters`)
   - `memberXrefMaxPerType`: optional cap for member xref entries per type/command (`0` = unlimited)
-  - coverage thresholds (0-100): `minTypeSummaryPercent`, `minTypeRemarksPercent`, `minTypeCodeExamplesPercent`, `minMemberSummaryPercent`, `minMemberCodeExamplesPercent`, `minPowerShellSummaryPercent`, `minPowerShellRemarksPercent`, `minPowerShellCodeExamplesPercent`, `minPowerShellParameterSummaryPercent`
+  - coverage thresholds (0-100): `minTypeSummaryPercent`, `minTypeRemarksPercent`, `minTypeCodeExamplesPercent`, `minMemberSummaryPercent`, `minMemberCodeExamplesPercent`, `minPowerShellSummaryPercent`, `minPowerShellRemarksPercent`, `minPowerShellCodeExamplesPercent`, `minPowerShellAuthoredHelpCodeExamplesPercent`, `minPowerShellImportedScriptCodeExamplesPercent`, `minPowerShellImportedScriptPlaybackMediaPercent`, `minPowerShellImportedScriptPlaybackMediaWithPosterPercent`, `minPowerShellParameterSummaryPercent`
   - source coverage thresholds (0-100): `minTypeSourcePathPercent`, `minTypeSourceUrlPercent`, `minMemberSourcePathPercent`, `minMemberSourceUrlPercent`, `minPowerShellSourcePathPercent`, `minPowerShellSourceUrlPercent`
+  - PowerShell example quality thresholds: `maxPowerShellGeneratedFallbackOnlyExamplePercent` (0-100), `maxPowerShellGeneratedFallbackOnlyExampleCount` (>=0), `maxPowerShellImportedScriptPlaybackMediaWithoutPosterCount` (>=0), `maxPowerShellImportedScriptPlaybackMediaUnsupportedSidecarCount` (>=0), `maxPowerShellImportedScriptPlaybackMediaOversizedAssetCount` (>=0), `maxPowerShellImportedScriptPlaybackMediaStaleAssetCount` (>=0)
   - source quality max-count thresholds (>=0): `maxTypeSourceInvalidUrlCount`, `maxMemberSourceInvalidUrlCount`, `maxPowerShellSourceInvalidUrlCount`, `maxTypeSourceUnresolvedTemplateCount`, `maxMemberSourceUnresolvedTemplateCount`, `maxPowerShellSourceUnresolvedTemplateCount`, `maxTypeSourceRepoMismatchHints`, `maxMemberSourceRepoMismatchHints`, `maxPowerShellSourceRepoMismatchHints`
   - `failOnCoverage`: fail step when thresholds are below minimums (default: `true` when any threshold is configured)
   - `coveragePreviewCount`: max failed coverage metrics shown in logs
   - PowerShell-only example inputs: `psExamplesPath`, `generatePowerShellFallbackExamples`, `powerShellFallbackExampleLimit`
+  - optional PowerShell example validation:
+    - `validatePowerShellExamples`: enable parser-based validation for imported example scripts
+    - `powerShellExampleValidationReport`: custom report path (default: `powershell-example-validation.json` under apidocs output)
+    - `powerShellExampleValidationTimeoutSeconds`: parser timeout (default: `60`)
+    - `failOnPowerShellExampleValidation`: fail the step when validation cannot run cleanly or when imported scripts contain syntax errors
+  - optional matched example execution:
+    - `executePowerShellExamples`: run matched PowerShell example scripts after syntax validation
+    - `powerShellExampleExecutionTimeoutSeconds`: per-example execution timeout (default: `60`)
+    - `failOnPowerShellExampleExecution`: fail the step when matched examples fail execution or execution cannot complete cleanly
+    - execution implicitly enables `validatePowerShellExamples`
+    - report writing emits per-example transcript artifacts beside `powershell-example-validation.json`
+    - validation JSON keeps paths normalized when possible and includes captured stdout/stderr/skip reasons for each executed script
+    - successful imported examples can reuse those transcript artifacts as terminal-style example media links in generated API docs
+    - curated `.cast` / `.asciinema` sidecars beside imported `.ps1` examples are also staged automatically, with matching image sidecars used as poster art when present
+    - asset-health warnings flag unsupported same-name sidecars, oversized playback assets, and stale captures/posters that are older than the current example script
+    - coverage reports can distinguish imported playback media from plain imported code examples, including whether poster art is present for every playback embed
+    - coverage can also track playback-sidecar health issues directly, so CI can fail on stale, oversized, or unsupported playback assets without depending on generic warning handling
+    - when imported terminal media exists, step summaries also include `ps-example-media: powershell-example-media-manifest.json` so CI logs expose the emitted media-manifest artifact directly
+  - validation also emits `[PFWEB.APIDOCS.POWERSHELL]` warnings when an imported example script fails syntax validation, does not reference any documented command from the selected help input, or fails execution after matching
 
 Multi-library batch example:
 ```json
diff --git a/PowerForge.Tests/WebApiDocsGeneratorContractTests.cs b/PowerForge.Tests/WebApiDocsGeneratorContractTests.cs
index d6f42dc5..61fa45ae 100644
--- a/PowerForge.Tests/WebApiDocsGeneratorContractTests.cs
+++ b/PowerForge.Tests/WebApiDocsGeneratorContractTests.cs
@@ -818,17 +818,29 @@ public void GenerateDocsHtml_WarnsWhenCssMissingScrollbarSelectors()
             .api-content{}
             .api-overview{}
             .api-overview-grid{}
+            .namespace-group-header{}
+            .namespace-group-actions{}
+            .overview-group-toggle{}
             .type-chips{}
             .type-chip{}
             .chip-icon{}
             .sidebar-count{}
             .sidebar-toggle{}
+            .pf-combobox{}
+            .pf-combobox-trigger{}
+            .pf-combobox-list{}
+            .pf-combobox-option{}
+            .pf-enhanced-native{}
             .type-item{}
             .type-detail-shell{}
             .type-detail-rail{}
+            .type-toc{}
+            .type-toc-header{}
+            .type-toc-toggle{}
             .filter-button{}
             .member-card{}
             .member-signature{}
+            .member-toggle input{}
             """);
 
         var outputPath = Path.Combine(root, "api");
diff --git a/PowerForge.Tests/WebApiDocsGeneratorPowerShellTests.cs b/PowerForge.Tests/WebApiDocsGeneratorPowerShellTests.cs
index 16bb6e02..2a865a54 100644
--- a/PowerForge.Tests/WebApiDocsGeneratorPowerShellTests.cs
+++ b/PowerForge.Tests/WebApiDocsGeneratorPowerShellTests.cs
@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using System.Text.Json;
 using PowerForge.Web;
 
@@ -106,6 +107,7 @@ public void Generate_PowerShellHelp_RendersExamplesAndNormalizesModuleNamespace(
                 ex => ex.GetProperty("kind").GetString() == "heading");
             Assert.Contains(examples.EnumerateArray(),
                 ex => ex.GetProperty("kind").GetString() == "code" &&
+                      ex.GetProperty("origin").GetString() == "AuthoredHelp" &&
                       ex.GetProperty("text").GetString()!.Contains("New-SampleCmdlet -Name \"Demo\"", StringComparison.Ordinal));
             Assert.True(rootElement.TryGetProperty("inputTypes", out _));
             Assert.True(rootElement.TryGetProperty("outputTypes", out _));
@@ -135,6 +137,8 @@ public void Generate_PowerShellHelp_RendersExamplesAndNormalizesModuleNamespace(
             Assert.Contains("prism-autoloader.min.js", html, StringComparison.OrdinalIgnoreCase);
             Assert.Contains("plugins.autoloader.languages_path", html, StringComparison.OrdinalIgnoreCase);
             Assert.Contains("setTimeout(run,delayMs)", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("Authored help example", html, StringComparison.Ordinal);
+            Assert.Contains("example-origin-badge example-origin-authored", html, StringComparison.Ordinal);
 
             var bootstrapIndex = html.IndexOf("window.Prism=window.Prism||{};window.Prism.manual=true;", StringComparison.Ordinal);
             var coreIndex = html.IndexOf("prism-core.min.js", StringComparison.OrdinalIgnoreCase);
@@ -151,8 +155,7 @@ public void Generate_PowerShellHelp_RendersExamplesAndNormalizesModuleNamespace(
         }
         finally
         {
-            if (Directory.Exists(root))
-                Directory.Delete(root, true);
+            TryDeleteDirectory(root);
         }
     }
 
@@ -200,7 +203,7 @@ public void Generate_PowerShellHelp_DoesNotInjectPrismAssets_WhenPrismModeOff()
                 Prism = new PrismSpec { Mode = "off" }
             };
 
-            WebApiDocsGenerator.Generate(options);
+            var result = WebApiDocsGenerator.Generate(options);
             var html = File.ReadAllText(Path.Combine(outputPath, "get-sampledata", "index.html"));
 
             Assert.Contains("language-powershell", html, StringComparison.OrdinalIgnoreCase);
@@ -211,8 +214,7 @@ public void Generate_PowerShellHelp_DoesNotInjectPrismAssets_WhenPrismModeOff()
         }
         finally
         {
-            if (Directory.Exists(root))
-                Directory.Delete(root, true);
+            TryDeleteDirectory(root);
         }
     }
 
@@ -296,8 +298,7 @@ function Invoke-SampleFunction {
         }
         finally
         {
-            if (Directory.Exists(root))
-                Directory.Delete(root, true);
+            TryDeleteDirectory(root);
         }
     }
 
@@ -587,6 +588,115 @@ function Invoke-SampleFunction {
         }
     }
 
+    [Fact]
+    public void Generate_PowerShellHelp_EmitsGitFreshnessMetadataForCommandsAndAboutTopics()
+    {
+        if (!IsGitAvailable())
+            return;
+
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-freshness-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpDirectory = Path.Combine(root, "en-US");
+            Directory.CreateDirectory(helpDirectory);
+            var helpPath = Path.Combine(helpDirectory, "Sample.Module-help.xml");
+            var aboutPath = Path.Combine(root, "about_SampleTopic.help.txt");
+
+            RunGit(root, "init");
+            RunGit(root, "config", "user.email", "tests@example.invalid");
+            RunGit(root, "config", "user.name", "PowerForge Tests");
+
+            File.WriteAllText(aboutPath,
+                """
+                # about_SampleTopic
+
+                Describes sample topic behavior.
+                """);
+            RunGit(root, "add", "about_SampleTopic.help.txt");
+            var olderCommitDate = DateTimeOffset.UtcNow.AddDays(-40).ToString("yyyy-MM-ddTHH:mm:ssK");
+            RunGit(root,
+                new Dictionary<string, string>
+                {
+                    ["GIT_AUTHOR_DATE"] = olderCommitDate,
+                    ["GIT_COMMITTER_DATE"] = olderCommitDate
+                },
+                "commit", "-m", "Add about topic");
+
+            File.WriteAllText(helpPath,
+                """
+                <?xml version="1.0" encoding="utf-8"?>
+                <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+                  <command:command>
+                    <command:details>
+                      <command:name>Get-SampleCmdlet</command:name>
+                      <maml:description><maml:para>Gets data.</maml:para></maml:description>
+                    </command:details>
+                    <maml:description>
+                      <maml:para>For more details, see about_SampleTopic.</maml:para>
+                    </maml:description>
+                    <command:syntax><command:syntaxItem><command:name>Get-SampleCmdlet</command:name></command:syntaxItem></command:syntax>
+                  </command:command>
+                </helpItems>
+                """);
+            RunGit(root, "add", "en-US/Sample.Module-help.xml");
+            var recentCommitDate = DateTimeOffset.UtcNow.AddDays(-3).ToString("yyyy-MM-ddTHH:mm:ssK");
+            RunGit(root,
+                new Dictionary<string, string>
+                {
+                    ["GIT_AUTHOR_DATE"] = recentCommitDate,
+                    ["GIT_COMMITTER_DATE"] = recentCommitDate
+                },
+                "commit", "-m", "Add help xml");
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = root,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both",
+                GenerateGitFreshness = true,
+                GitFreshnessNewDays = 14,
+                GitFreshnessUpdatedDays = 90
+            };
+
+            var result = WebApiDocsGenerator.Generate(options);
+            Assert.Equal(2, result.TypeCount);
+
+            using var commandJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "get-samplecmdlet.json")));
+            using var aboutJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "about-sampletopic.json")));
+
+            var commandFreshness = commandJson.RootElement.GetProperty("freshness");
+            var aboutFreshness = aboutJson.RootElement.GetProperty("freshness");
+
+            Assert.Equal("new", commandFreshness.GetProperty("status").GetString());
+            Assert.True(commandFreshness.GetProperty("ageDays").GetInt32() <= 14);
+            Assert.EndsWith("en-US/Sample.Module-help.xml", commandFreshness.GetProperty("sourcePath").GetString(), StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain(root, commandFreshness.GetProperty("sourcePath").GetString(), StringComparison.OrdinalIgnoreCase);
+
+            Assert.Equal("updated", aboutFreshness.GetProperty("status").GetString());
+            Assert.True(aboutFreshness.GetProperty("ageDays").GetInt32() >= 30);
+            Assert.EndsWith("about_SampleTopic.help.txt", aboutFreshness.GetProperty("sourcePath").GetString(), StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain(root, aboutFreshness.GetProperty("sourcePath").GetString(), StringComparison.OrdinalIgnoreCase);
+
+            var commandHtml = File.ReadAllText(Path.Combine(outputPath, "get-samplecmdlet", "index.html"));
+            var aboutHtml = File.ReadAllText(Path.Combine(outputPath, "about-sampletopic", "index.html"));
+            Assert.Contains("freshness-badge new", commandHtml, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains(">new<", commandHtml, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("freshness-badge updated", aboutHtml, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains(">updated<", aboutHtml, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
     [Fact]
     public void Generate_PowerShellHelp_UsesDetachedCommandMetadataForFunctionsAndAliases()
     {
@@ -721,7 +831,7 @@ public void Generate_PowerShellHelp_PrefersCommandTypeFromHelpXmlOverManifestHin
                 Format = "both"
             };
 
-            WebApiDocsGenerator.Generate(options);
+            var result = WebApiDocsGenerator.Generate(options);
             using var functionJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-samplefunction.json")));
             Assert.Equal("Function", functionJson.RootElement.GetProperty("kind").GetString());
         }
@@ -993,7 +1103,12 @@ public void Generate_PowerShellHelp_ImportsFallbackExamplesFromScriptsWhenHelpHa
             var examples = functionJson.RootElement.GetProperty("examples").EnumerateArray().ToArray();
             Assert.Contains(examples,
                 ex => ex.GetProperty("kind").GetString() == "code" &&
+                      ex.GetProperty("origin").GetString() == "ImportedScript" &&
                       ex.GetProperty("text").GetString()!.Contains("Invoke-SampleFunction -Name \"FromScript\"", StringComparison.Ordinal));
+
+            var html = File.ReadAllText(Path.Combine(outputPath, "invoke-samplefunction", "index.html"));
+            Assert.Contains("Imported script example", html, StringComparison.Ordinal);
+            Assert.Contains("example-origin-badge example-origin-imported", html, StringComparison.Ordinal);
         }
         finally
         {
@@ -1003,9 +1118,104 @@ public void Generate_PowerShellHelp_ImportsFallbackExamplesFromScriptsWhenHelpHa
     }
 
     [Fact]
-    public void Generate_ApiDocs_WritesCoverageReport()
+    public void Generate_PowerShellHelp_PrefersCommandSpecificExampleScriptsOverGenericOnes()
     {
-        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-coverage-" + Guid.NewGuid().ToString("N"));
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-fallback-ranking-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "en-US", "Sample.Module-help.xml");
+            Directory.CreateDirectory(Path.GetDirectoryName(helpPath)!);
+            File.WriteAllText(helpPath,
+                """
+                <?xml version="1.0" encoding="utf-8"?>
+                <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+                  <command:command>
+                    <command:details>
+                      <command:name>Invoke-SampleFunction</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Invokes data.</maml:para></maml:description>
+                    </command:details>
+                    <command:syntax>
+                      <command:syntaxItem>
+                        <command:name>Invoke-SampleFunction</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Name</maml:name>
+                          <command:parameterValue required="true">string</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                    </command:syntax>
+                    <command:parameters>
+                      <command:parameter required="true">
+                        <maml:name>Name</maml:name>
+                        <maml:description><maml:para>Name value.</maml:para></maml:description>
+                        <command:parameterValue required="true">string</command:parameterValue>
+                      </command:parameter>
+                    </command:parameters>
+                  </command:command>
+                </helpItems>
+                """);
+
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) }");
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Example.Generic.ps1"),
+                """
+                Invoke-SampleFunction -Name "FromGeneric"
+                """);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.ps1"),
+                """
+                Invoke-SampleFunction -Name "FromSpecific"
+                """);
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = root,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both",
+                PowerShellFallbackExampleLimitPerCommand = 1
+            };
+
+            WebApiDocsGenerator.Generate(options);
+            using var functionJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-samplefunction.json")));
+            var examples = functionJson.RootElement.GetProperty("examples").EnumerateArray().ToArray();
+            var codeExamples = examples
+                .Where(ex => ex.GetProperty("kind").GetString() == "code")
+                .Select(ex => ex.GetProperty("text").GetString())
+                .Where(static text => !string.IsNullOrWhiteSpace(text))
+                .ToArray();
+
+            Assert.Single(codeExamples);
+            Assert.Contains("FromSpecific", codeExamples[0], StringComparison.Ordinal);
+            Assert.DoesNotContain("FromGeneric", codeExamples[0], StringComparison.Ordinal);
+        }
+        finally
+        {
+            if (Directory.Exists(root))
+                Directory.Delete(root, true);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_GeneratesFallbackExamplesFromBestParameterSets()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-generated-fallback-" + Guid.NewGuid().ToString("N"));
         Directory.CreateDirectory(root);
 
         try
@@ -1017,14 +1227,74 @@ public void Generate_ApiDocs_WritesCoverageReport()
                 <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
                   <command:command>
                     <command:details>
-                      <command:name>Get-SampleCmdlet</command:name>
-                      <maml:description><maml:para>Gets data.</maml:para></maml:description>
+                      <command:name>Invoke-SampleFunction</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Invokes data.</maml:para></maml:description>
                     </command:details>
-                    <command:syntax><command:syntaxItem><command:name>Get-SampleCmdlet</command:name></command:syntaxItem></command:syntax>
+                    <command:syntax>
+                      <command:syntaxItem parameterSetName="ByName">
+                        <command:name>Invoke-SampleFunction</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Name</maml:name>
+                          <command:parameterValue required="true">string</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                      <command:syntaxItem parameterSetName="ById">
+                        <command:name>Invoke-SampleFunction</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Id</maml:name>
+                          <command:parameterValue required="true">int</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                      <command:syntaxItem parameterSetName="ByInputObject">
+                        <command:name>Invoke-SampleFunction</command:name>
+                        <command:parameter required="true">
+                          <maml:name>InputObject</maml:name>
+                          <command:parameterValue required="true">Sample.Module.Item</command:parameterValue>
+                        </command:parameter>
+                        <command:parameter required="false">
+                          <maml:name>Credential</maml:name>
+                          <command:parameterValue required="false">pscredential</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                    </command:syntax>
+                    <command:parameters>
+                      <command:parameter required="true">
+                        <maml:name>Name</maml:name>
+                        <maml:description><maml:para>Name value.</maml:para></maml:description>
+                        <command:parameterValue required="true">string</command:parameterValue>
+                      </command:parameter>
+                      <command:parameter required="true">
+                        <maml:name>Id</maml:name>
+                        <maml:description><maml:para>Identifier.</maml:para></maml:description>
+                        <command:parameterValue required="true">int</command:parameterValue>
+                      </command:parameter>
+                      <command:parameter required="true">
+                        <maml:name>InputObject</maml:name>
+                        <maml:description><maml:para>Pipeline object.</maml:para></maml:description>
+                        <command:parameterValue required="true">Sample.Module.Item</command:parameterValue>
+                      </command:parameter>
+                      <command:parameter required="false">
+                        <maml:name>Credential</maml:name>
+                        <maml:description><maml:para>Credential.</maml:para></maml:description>
+                        <command:parameterValue required="false">pscredential</command:parameterValue>
+                      </command:parameter>
+                    </command:parameters>
                   </command:command>
                 </helpItems>
                 """);
 
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name, [int]$Id, $InputObject, [pscredential]$Credential) }");
+
             var outputPath = Path.Combine(root, "_site", "api", "powershell");
             var options = new WebApiDocsOptions
             {
@@ -1033,17 +1303,44 @@ public void Generate_ApiDocs_WritesCoverageReport()
                 OutputPath = outputPath,
                 Title = "PowerShell API",
                 BaseUrl = "/api/powershell",
-                Format = "json",
-                CoverageReportPath = "reports/api-coverage.json"
+                Template = "docs",
+                Format = "both",
+                PowerShellFallbackExampleLimitPerCommand = 2
             };
 
-            var result = WebApiDocsGenerator.Generate(options);
-            Assert.False(string.IsNullOrWhiteSpace(result.CoveragePath));
-            Assert.True(File.Exists(result.CoveragePath!));
+            WebApiDocsGenerator.Generate(options);
 
-            using var coverage = JsonDocument.Parse(File.ReadAllText(result.CoveragePath!));
-            Assert.Equal(1, coverage.RootElement.GetProperty("types").GetProperty("count").GetInt32());
-            Assert.Equal(1, coverage.RootElement.GetProperty("powershell").GetProperty("commandCount").GetInt32());
+            using var functionJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-samplefunction.json")));
+            var examples = functionJson.RootElement.GetProperty("examples").EnumerateArray().ToArray();
+            var codeExamples = examples
+                .Where(ex => ex.GetProperty("kind").GetString() == "code")
+                .Select(ex => ex.GetProperty("text").GetString())
+                .Where(static text => !string.IsNullOrWhiteSpace(text))
+                .ToArray();
+            var textExamples = examples
+                .Where(ex => ex.GetProperty("kind").GetString() == "text")
+                .Select(ex => ex.GetProperty("text").GetString())
+                .Where(static text => !string.IsNullOrWhiteSpace(text))
+                .ToArray();
+
+            Assert.Equal(2, codeExamples.Length);
+            Assert.Contains(codeExamples, example => example!.Contains("Invoke-SampleFunction -Name 'Name'", StringComparison.Ordinal));
+            Assert.Contains(codeExamples, example => example!.Contains("Invoke-SampleFunction -Id 1", StringComparison.Ordinal));
+            Assert.DoesNotContain(codeExamples, example => example!.Contains("-InputObject", StringComparison.Ordinal));
+            Assert.Contains(textExamples, example => example!.Contains("parameter set 'ByName'", StringComparison.Ordinal));
+            Assert.Contains(textExamples, example => example!.Contains("parameter set 'ById'", StringComparison.Ordinal));
+            Assert.All(
+                examples.Where(ex =>
+                {
+                    var kind = ex.GetProperty("kind").GetString();
+                    return string.Equals(kind, "code", StringComparison.Ordinal) ||
+                           string.Equals(kind, "text", StringComparison.Ordinal);
+                }),
+                ex => Assert.Equal("GeneratedFallback", ex.GetProperty("origin").GetString()));
+
+            var html = File.ReadAllText(Path.Combine(outputPath, "invoke-samplefunction", "index.html"));
+            Assert.Contains("Generated fallback example", html, StringComparison.Ordinal);
+            Assert.Contains("example-origin-badge example-origin-generated", html, StringComparison.Ordinal);
         }
         finally
         {
@@ -1051,4 +1348,1422 @@ public void Generate_ApiDocs_WritesCoverageReport()
                 Directory.Delete(root, true);
         }
     }
+
+    [Fact]
+    public void Generate_PowerShellHelp_GeneratesCommandOnlyFallbackWhenSyntaxIsMissing()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-generated-command-only-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath,
+                """
+                <?xml version="1.0" encoding="utf-8"?>
+                <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+                  <command:command>
+                    <command:details>
+                      <command:name>Invoke-SampleFunction</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Invokes data.</maml:para></maml:description>
+                    </command:details>
+                  </command:command>
+                </helpItems>
+                """);
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both"
+            };
+
+            WebApiDocsGenerator.Generate(options);
+
+            using var functionJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-samplefunction.json")));
+            var examples = functionJson.RootElement.GetProperty("examples").EnumerateArray().ToArray();
+            Assert.Contains(examples, ex =>
+                ex.GetProperty("kind").GetString() == "code" &&
+                ex.GetProperty("origin").GetString() == "GeneratedFallback" &&
+                ex.GetProperty("text").GetString() == "Invoke-SampleFunction");
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void Generate_ApiDocs_WritesCoverageReport()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-coverage-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath,
+                """
+                <?xml version="1.0" encoding="utf-8"?>
+                <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+                  <command:command>
+                    <command:details>
+                      <command:name>Get-SampleCmdlet</command:name>
+                      <maml:description><maml:para>Gets data.</maml:para></maml:description>
+                    </command:details>
+                    <command:syntax><command:syntaxItem><command:name>Get-SampleCmdlet</command:name></command:syntaxItem></command:syntax>
+                  </command:command>
+                </helpItems>
+                """);
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Format = "json",
+                CoverageReportPath = "reports/api-coverage.json"
+            };
+
+            var result = WebApiDocsGenerator.Generate(options);
+            Assert.False(string.IsNullOrWhiteSpace(result.CoveragePath));
+            Assert.True(File.Exists(result.CoveragePath!));
+
+            using var coverage = JsonDocument.Parse(File.ReadAllText(result.CoveragePath!));
+            Assert.Equal(1, coverage.RootElement.GetProperty("types").GetProperty("count").GetInt32());
+            Assert.Equal(1, coverage.RootElement.GetProperty("powershell").GetProperty("commandCount").GetInt32());
+        }
+        finally
+        {
+            if (Directory.Exists(root))
+                Directory.Delete(root, true);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_CoverageDistinguishesAuthoredImportedAndGeneratedExamples()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-example-origins-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "en-US", "Sample.Module-help.xml");
+            Directory.CreateDirectory(Path.GetDirectoryName(helpPath)!);
+            File.WriteAllText(helpPath,
+                """
+                <?xml version="1.0" encoding="utf-8"?>
+                <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+                  <command:command>
+                    <command:details>
+                      <command:name>Get-AuthoredExample</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Gets authored example content.</maml:para></maml:description>
+                    </command:details>
+                    <command:syntax>
+                      <command:syntaxItem>
+                        <command:name>Get-AuthoredExample</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Name</maml:name>
+                          <command:parameterValue required="true">string</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                    </command:syntax>
+                    <command:parameters>
+                      <command:parameter required="true">
+                        <maml:name>Name</maml:name>
+                        <maml:description><maml:para>Name value.</maml:para></maml:description>
+                        <command:parameterValue required="true">string</command:parameterValue>
+                      </command:parameter>
+                    </command:parameters>
+                    <command:examples>
+                      <command:example>
+                        <maml:title>----------  Example 1: Authored.  ----------</maml:title>
+                        <dev:code>Get-AuthoredExample -Name "Alpha"</dev:code>
+                      </command:example>
+                    </command:examples>
+                  </command:command>
+                  <command:command>
+                    <command:details>
+                      <command:name>Invoke-ImportedExample</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Gets imported example content.</maml:para></maml:description>
+                    </command:details>
+                    <command:syntax>
+                      <command:syntaxItem>
+                        <command:name>Invoke-ImportedExample</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Name</maml:name>
+                          <command:parameterValue required="true">string</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                    </command:syntax>
+                    <command:parameters>
+                      <command:parameter required="true">
+                        <maml:name>Name</maml:name>
+                        <maml:description><maml:para>Name value.</maml:para></maml:description>
+                        <command:parameterValue required="true">string</command:parameterValue>
+                      </command:parameter>
+                    </command:parameters>
+                  </command:command>
+                  <command:command>
+                    <command:details>
+                      <command:name>Set-GeneratedExample</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Gets generated example content.</maml:para></maml:description>
+                    </command:details>
+                    <command:syntax>
+                      <command:syntaxItem parameterSetName="ByName">
+                        <command:name>Set-GeneratedExample</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Name</maml:name>
+                          <command:parameterValue required="true">string</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                    </command:syntax>
+                    <command:parameters>
+                      <command:parameter required="true">
+                        <maml:name>Name</maml:name>
+                        <maml:description><maml:para>Name value.</maml:para></maml:description>
+                        <command:parameterValue required="true">string</command:parameterValue>
+                      </command:parameter>
+                    </command:parameters>
+                  </command:command>
+                </helpItems>
+                """);
+
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Get-AuthoredExample', 'Invoke-ImportedExample', 'Set-GeneratedExample')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Get-AuthoredExample { param([string]$Name) }
+                function Invoke-ImportedExample { param([string]$Name) }
+                function Set-GeneratedExample { param([string]$Name) }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-ImportedExample.ps1"),
+                """
+                Invoke-ImportedExample -Name "FromScript"
+                """);
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = root,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Format = "json",
+                CoverageReportPath = "reports/api-coverage.json"
+            };
+
+            var result = WebApiDocsGenerator.Generate(options);
+            using var coverage = JsonDocument.Parse(File.ReadAllText(result.CoveragePath!));
+            var powershell = coverage.RootElement.GetProperty("powershell");
+
+            Assert.Equal(3, powershell.GetProperty("commandCount").GetInt32());
+            Assert.Equal(3, powershell.GetProperty("codeExamples").GetProperty("covered").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("authoredHelpCodeExamples").GetProperty("covered").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("importedScriptCodeExamples").GetProperty("covered").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("generatedFallbackCodeExamples").GetProperty("covered").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("generatedFallbackOnlyExamples").GetProperty("covered").GetInt32());
+
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingAuthoredHelpCodeExamples").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Get-AuthoredExample", StringComparison.Ordinal));
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingImportedScriptCodeExamples").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-ImportedExample", StringComparison.Ordinal));
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingGeneratedFallbackCodeExamples").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Set-GeneratedExample", StringComparison.Ordinal));
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingGeneratedFallbackOnlyExamples").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Set-GeneratedExample", StringComparison.Ordinal));
+        }
+        finally
+        {
+            if (Directory.Exists(root))
+                Directory.Delete(root, true);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_WarnsWhenCommandsRelyOnlyOnGeneratedFallbackExamples()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-generated-warning-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath,
+                """
+                <?xml version="1.0" encoding="utf-8"?>
+                <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+                  <command:command>
+                    <command:details>
+                      <command:name>Invoke-SampleFunction</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Invokes data.</maml:para></maml:description>
+                    </command:details>
+                    <command:syntax>
+                      <command:syntaxItem parameterSetName="ByName">
+                        <command:name>Invoke-SampleFunction</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Name</maml:name>
+                          <command:parameterValue required="true">string</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                    </command:syntax>
+                    <command:parameters>
+                      <command:parameter required="true">
+                        <maml:name>Name</maml:name>
+                        <maml:description><maml:para>Name value.</maml:para></maml:description>
+                        <command:parameterValue required="true">string</command:parameterValue>
+                      </command:parameter>
+                    </command:parameters>
+                  </command:command>
+                </helpItems>
+                """);
+
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) }");
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Format = "json",
+                CoverageReportPath = "reports/api-coverage.json"
+            };
+
+            var result = WebApiDocsGenerator.Generate(options);
+
+            Assert.Contains(result.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("rely only on generated fallback examples", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleFunction", StringComparison.OrdinalIgnoreCase));
+
+            using var coverage = JsonDocument.Parse(File.ReadAllText(result.CoveragePath!));
+            var generatedFallbackOnly = coverage.RootElement
+                .GetProperty("powershell")
+                .GetProperty("generatedFallbackOnlyExamples");
+            Assert.Equal(1, generatedFallbackOnly.GetProperty("covered").GetInt32());
+            var generatedFallback = coverage.RootElement
+                .GetProperty("powershell")
+                .GetProperty("generatedFallbackCodeExamples");
+            Assert.Equal(1, generatedFallback.GetProperty("covered").GetInt32());
+            Assert.Equal(0, coverage.RootElement.GetProperty("powershell").GetProperty("authoredHelpCodeExamples").GetProperty("covered").GetInt32());
+            Assert.Equal(0, coverage.RootElement.GetProperty("powershell").GetProperty("importedScriptCodeExamples").GetProperty("covered").GetInt32());
+            Assert.Contains(
+                coverage.RootElement.GetProperty("powershell").GetProperty("commandsUsingGeneratedFallbackOnlyExamples").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-SampleFunction", StringComparison.Ordinal));
+            Assert.Contains(
+                coverage.RootElement.GetProperty("powershell").GetProperty("commandsUsingGeneratedFallbackCodeExamples").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-SampleFunction", StringComparison.Ordinal));
+        }
+        finally
+        {
+            if (Directory.Exists(root))
+                Directory.Delete(root, true);
+        }
+    }
+
+    [Fact]
+    public void ValidatePowerShellExamples_FindsInvalidAndUnmatchedScripts_AndWritesReport()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-validate-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne', 'Invoke-SampleTwo')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) }
+                function Invoke-SampleTwo { param([string]$Name) }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.ps1"), "Invoke-SampleOne -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "BrokenExample.ps1"), "Invoke-SampleTwo -Name (");
+            File.WriteAllText(Path.Combine(examplesDir, "GenericDemo.ps1"), "Get-UnrelatedThing -Name 'Other'");
+
+            var validation = WebApiDocsGenerator.ValidatePowerShellExamples(new WebApiDocsPowerShellExampleValidationOptions
+            {
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                TimeoutSeconds = 60
+            });
+
+            Assert.True(validation.ValidationSucceeded);
+            Assert.Equal(3, validation.FileCount);
+            Assert.Equal(2, validation.ValidSyntaxFileCount);
+            Assert.Equal(1, validation.InvalidSyntaxFileCount);
+            Assert.Equal(2, validation.MatchedFileCount);
+            Assert.Equal(1, validation.UnmatchedFileCount);
+            Assert.Equal(2, validation.KnownCommandCount);
+            Assert.Contains(validation.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("failed syntax validation", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("BrokenExample.ps1", StringComparison.OrdinalIgnoreCase));
+            Assert.Contains(validation.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("did not reference any documented commands", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("GenericDemo.ps1", StringComparison.OrdinalIgnoreCase));
+
+            var broken = Assert.Single(
+                validation.Files,
+                file => string.Equals(Path.GetFileName(file.FilePath), "BrokenExample.ps1", StringComparison.OrdinalIgnoreCase));
+            Assert.False(broken.ValidSyntax);
+            Assert.Contains("Invoke-SampleTwo", broken.MatchedCommands, StringComparer.OrdinalIgnoreCase);
+            Assert.NotEmpty(broken.ParseErrors);
+
+            var generic = Assert.Single(
+                validation.Files,
+                file => string.Equals(Path.GetFileName(file.FilePath), "GenericDemo.ps1", StringComparison.OrdinalIgnoreCase));
+            Assert.True(generic.ValidSyntax);
+            Assert.Empty(generic.MatchedCommands);
+            Assert.Contains("Get-UnrelatedThing", generic.Commands, StringComparer.OrdinalIgnoreCase);
+
+            var reportRoot = Path.Combine(root, "_site", "api");
+            var reportPath = WebApiDocsGenerator.WritePowerShellExampleValidationReport(
+                reportRoot,
+                null,
+                validation,
+                new WebApiDocsPowerShellExampleValidationOptions
+                {
+                    HelpPath = helpPath,
+                    PowerShellExamplesPath = examplesDir,
+                    TimeoutSeconds = 60
+                });
+            Assert.True(File.Exists(reportPath));
+
+            using var report = JsonDocument.Parse(File.ReadAllText(reportPath));
+            Assert.DoesNotContain(root, report.RootElement.GetProperty("helpPath").GetString(), StringComparison.OrdinalIgnoreCase);
+            Assert.Equal("Sample.Module-help.xml", report.RootElement.GetProperty("helpPath").GetString());
+            Assert.Equal(1, report.RootElement.GetProperty("invalidSyntaxFileCount").GetInt32());
+            Assert.Equal(1, report.RootElement.GetProperty("unmatchedFileCount").GetInt32());
+            Assert.Equal(3, report.RootElement.GetProperty("fileCount").GetInt32());
+            var reportFiles = report.RootElement.GetProperty("files").EnumerateArray().ToArray();
+            Assert.All(reportFiles, file =>
+            {
+                Assert.DoesNotContain(root, file.GetProperty("filePath").GetString(), StringComparison.OrdinalIgnoreCase);
+                Assert.False(Path.IsPathRooted(file.GetProperty("filePath").GetString()));
+            });
+        }
+        finally
+        {
+            if (Directory.Exists(root))
+                Directory.Delete(root, true);
+        }
+    }
+
+    [Fact]
+    public void ValidatePowerShellExamples_ExecutesMatchedScripts_AndCapturesFailures()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-execute-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne', 'Invoke-SampleTwo')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                function Invoke-SampleTwo { param([string]$Name) "Ran two for $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.ps1"), "Invoke-SampleOne -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleTwo.Fail.ps1"), "Invoke-SampleTwo -Name 'Beta'; throw 'boom'");
+
+            var validation = WebApiDocsGenerator.ValidatePowerShellExamples(new WebApiDocsPowerShellExampleValidationOptions
+            {
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                TimeoutSeconds = 60,
+                ExecuteMatchedExamples = true,
+                ExecutionTimeoutSeconds = 60
+            });
+
+            Assert.True(validation.ValidationSucceeded);
+            Assert.True(validation.ExecutionRequested);
+            Assert.True(validation.ExecutionCompleted);
+            Assert.Equal(2, validation.ExecutedFileCount);
+            Assert.Equal(1, validation.PassedExecutionFileCount);
+            Assert.Equal(1, validation.FailedExecutionFileCount);
+            Assert.Contains(validation.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("failed execution", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleTwo.Fail.ps1", StringComparison.OrdinalIgnoreCase));
+
+            var passing = Assert.Single(
+                validation.Files,
+                file => string.Equals(Path.GetFileName(file.FilePath), "Invoke-SampleOne.ps1", StringComparison.OrdinalIgnoreCase));
+            Assert.True(passing.ExecutionAttempted);
+            Assert.True(passing.ExecutionSucceeded);
+            Assert.Equal(0, passing.ExecutionExitCode);
+            Assert.Contains("Ran one for Alpha", passing.ExecutionStdOut, StringComparison.Ordinal);
+
+            var failing = Assert.Single(
+                validation.Files,
+                file => string.Equals(Path.GetFileName(file.FilePath), "Invoke-SampleTwo.Fail.ps1", StringComparison.OrdinalIgnoreCase));
+            Assert.True(failing.ExecutionAttempted);
+            Assert.False(failing.ExecutionSucceeded);
+            Assert.NotEqual(0, failing.ExecutionExitCode);
+            Assert.Contains("boom", failing.ExecutionStdErr ?? string.Empty, StringComparison.OrdinalIgnoreCase);
+
+            var reportRoot = Path.Combine(root, "_site", "api");
+            var reportPath = WebApiDocsGenerator.WritePowerShellExampleValidationReport(
+                reportRoot,
+                null,
+                validation,
+                new WebApiDocsPowerShellExampleValidationOptions
+                {
+                    HelpPath = helpPath,
+                    PowerShellExamplesPath = examplesDir,
+                    TimeoutSeconds = 60,
+                    ExecuteMatchedExamples = true,
+                    ExecutionTimeoutSeconds = 60
+                });
+            using var report = JsonDocument.Parse(File.ReadAllText(reportPath));
+            Assert.True(report.RootElement.GetProperty("executionRequested").GetBoolean());
+            Assert.Equal(2, report.RootElement.GetProperty("executedFileCount").GetInt32());
+            Assert.Equal(1, report.RootElement.GetProperty("failedExecutionFileCount").GetInt32());
+            Assert.DoesNotContain(root, report.RootElement.GetProperty("helpPath").GetString(), StringComparison.OrdinalIgnoreCase);
+
+            var reportedFiles = report.RootElement.GetProperty("files").EnumerateArray().ToArray();
+            var passingReport = Assert.Single(reportedFiles, file =>
+                string.Equals(Path.GetFileName(file.GetProperty("filePath").GetString()), "Invoke-SampleOne.ps1", StringComparison.OrdinalIgnoreCase));
+            var failingReport = Assert.Single(reportedFiles, file =>
+                string.Equals(Path.GetFileName(file.GetProperty("filePath").GetString()), "Invoke-SampleTwo.Fail.ps1", StringComparison.OrdinalIgnoreCase));
+
+            var passingArtifactPath = passingReport.GetProperty("executionArtifactPath").GetString();
+            var failingArtifactPath = failingReport.GetProperty("executionArtifactPath").GetString();
+            Assert.False(string.IsNullOrWhiteSpace(passingArtifactPath));
+            Assert.False(string.IsNullOrWhiteSpace(failingArtifactPath));
+            Assert.DoesNotContain(root, passingArtifactPath, StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain(root, failingArtifactPath, StringComparison.OrdinalIgnoreCase);
+            Assert.False(Path.IsPathRooted(passingArtifactPath));
+            Assert.False(Path.IsPathRooted(failingArtifactPath));
+            var passingArtifactFullPath = Path.GetFullPath(Path.Combine(Path.GetDirectoryName(reportPath)!, passingArtifactPath!));
+            var failingArtifactFullPath = Path.GetFullPath(Path.Combine(Path.GetDirectoryName(reportPath)!, failingArtifactPath!));
+            Assert.True(File.Exists(passingArtifactFullPath));
+            Assert.True(File.Exists(failingArtifactFullPath));
+            Assert.Contains("File: Invoke-SampleOne.ps1", File.ReadAllText(passingArtifactFullPath), StringComparison.Ordinal);
+            Assert.Contains("Ran one for Alpha", File.ReadAllText(passingArtifactFullPath), StringComparison.Ordinal);
+            Assert.Contains("boom", File.ReadAllText(failingArtifactFullPath), StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void ValidatePowerShellExamples_WithExecutionRequestedAndNoScripts_MarksExecutionCompleted()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-execute-empty-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+
+            var validation = WebApiDocsGenerator.ValidatePowerShellExamples(new WebApiDocsPowerShellExampleValidationOptions
+            {
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                TimeoutSeconds = 60,
+                ExecuteMatchedExamples = true,
+                ExecutionTimeoutSeconds = 60
+            });
+
+            Assert.True(validation.ValidationSucceeded);
+            Assert.True(validation.ExecutionRequested);
+            Assert.True(validation.ExecutionCompleted);
+            Assert.Equal(0, validation.FileCount);
+            Assert.Equal(0, validation.ExecutedFileCount);
+            Assert.Equal(0, validation.FailedExecutionFileCount);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void ValidatePowerShellExamples_SkipsExecutionOutsideConfiguredExamplesPath()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-execute-rootguard-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                """);
+
+            var approvedExamplesDir = Path.Combine(root, "ApprovedExamples");
+            Directory.CreateDirectory(approvedExamplesDir);
+            File.WriteAllText(Path.Combine(approvedExamplesDir, "Invoke-SampleOne.Approved.ps1"), "Invoke-SampleOne -Name 'Approved'");
+
+            var discoveredExamplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(discoveredExamplesDir);
+            File.WriteAllText(Path.Combine(discoveredExamplesDir, "Invoke-SampleOne.ps1"), "Invoke-SampleOne -Name 'Discovered'");
+
+            var validation = WebApiDocsGenerator.ValidatePowerShellExamples(new WebApiDocsPowerShellExampleValidationOptions
+            {
+                HelpPath = helpPath,
+                PowerShellExamplesPath = approvedExamplesDir,
+                TimeoutSeconds = 60,
+                ExecuteMatchedExamples = true,
+                ExecutionTimeoutSeconds = 60
+            });
+
+            var approved = Assert.Single(
+                validation.Files,
+                file => string.Equals(Path.GetFileName(file.FilePath), "Invoke-SampleOne.Approved.ps1", StringComparison.OrdinalIgnoreCase));
+            Assert.True(approved.ExecutionAttempted);
+            Assert.True(approved.ExecutionSucceeded);
+
+            var discovered = Assert.Single(
+                validation.Files,
+                file => string.Equals(Path.GetFileName(file.FilePath), "Invoke-SampleOne.ps1", StringComparison.OrdinalIgnoreCase));
+            Assert.False(discovered.ExecutionAttempted);
+            Assert.Null(discovered.ExecutionSucceeded);
+            Assert.Equal("Outside configured PowerShell examples path.", discovered.ExecutionSkippedReason);
+            Assert.Contains(validation.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("outside the configured examples path", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleOne.ps1", StringComparison.OrdinalIgnoreCase));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_AttachesExecutionTranscriptMedia_ForSuccessfulImportedExamples()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-execute-media-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne', 'Invoke-SampleTwo')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                function Invoke-SampleTwo { param([string]$Name) "Ran two for $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.ps1"), "Invoke-SampleOne -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleTwo.Fail.ps1"), "Invoke-SampleTwo -Name 'Beta'; throw 'boom'");
+
+            var validation = WebApiDocsGenerator.ValidatePowerShellExamples(new WebApiDocsPowerShellExampleValidationOptions
+            {
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                TimeoutSeconds = 60,
+                ExecuteMatchedExamples = true,
+                ExecutionTimeoutSeconds = 60
+            });
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            WebApiDocsGenerator.WritePowerShellExampleValidationReport(outputPath, null, validation);
+
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                PowerShellExampleValidationResult = validation,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both"
+            };
+
+            WebApiDocsGenerator.Generate(options);
+
+            using var sampleOneJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-sampleone.json")));
+            var sampleOneExamples = sampleOneJson.RootElement.GetProperty("examples").EnumerateArray().ToArray();
+            var transcriptMedia = Assert.Single(sampleOneExamples, example =>
+                string.Equals(example.GetProperty("kind").GetString(), "media", StringComparison.OrdinalIgnoreCase) &&
+                example.TryGetProperty("media", out var media) &&
+                string.Equals(media.GetProperty("type").GetString(), "terminal", StringComparison.OrdinalIgnoreCase));
+            var mediaUrl = transcriptMedia.GetProperty("media").GetProperty("url").GetString();
+            Assert.Contains("/api/powershell/powershell-example-media/", mediaUrl, StringComparison.OrdinalIgnoreCase);
+            Assert.False(string.IsNullOrWhiteSpace(transcriptMedia.GetProperty("media").GetProperty("capturedAtUtc").GetString()));
+            Assert.False(string.IsNullOrWhiteSpace(transcriptMedia.GetProperty("media").GetProperty("sourceUpdatedAtUtc").GetString()));
+            Assert.Contains("Open execution transcript", transcriptMedia.GetProperty("media").GetProperty("title").GetString(), StringComparison.Ordinal);
+
+            var sampleOneHtml = File.ReadAllText(Path.Combine(outputPath, "invoke-sampleone", "index.html"));
+            Assert.Contains("example-media example-media-terminal", sampleOneHtml, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("Open execution transcript", sampleOneHtml, StringComparison.Ordinal);
+            Assert.Contains("Captured terminal transcript from executing Invoke-SampleOne.ps1.", sampleOneHtml, StringComparison.Ordinal);
+            Assert.Contains("Captured ", sampleOneHtml, StringComparison.Ordinal);
+
+            using var sampleTwoJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-sampletwo.json")));
+            var sampleTwoExamples = sampleTwoJson.RootElement.GetProperty("examples").EnumerateArray().ToArray();
+            Assert.DoesNotContain(sampleTwoExamples, example =>
+                string.Equals(example.GetProperty("kind").GetString(), "media", StringComparison.OrdinalIgnoreCase) &&
+                example.TryGetProperty("media", out var media) &&
+                string.Equals(media.GetProperty("type").GetString(), "terminal", StringComparison.OrdinalIgnoreCase));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_StagesExecutionTranscripts_WhenValidationReportLivesOutsideOutput()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-transcript-stage-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.ps1"), "Invoke-SampleOne -Name 'Alpha'");
+
+            var validation = WebApiDocsGenerator.ValidatePowerShellExamples(new WebApiDocsPowerShellExampleValidationOptions
+            {
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                TimeoutSeconds = 60,
+                ExecuteMatchedExamples = true,
+                ExecutionTimeoutSeconds = 60
+            });
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var reportPath = Path.Combine(root, "_reports", "powershell-example-validation.json");
+            WebApiDocsGenerator.WritePowerShellExampleValidationReport(outputPath, reportPath, validation);
+
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                PowerShellExampleValidationResult = validation,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both"
+            };
+
+            WebApiDocsGenerator.Generate(options);
+
+            using var sampleJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-sampleone.json")));
+            var sampleExamples = sampleJson.RootElement.GetProperty("examples").EnumerateArray().ToArray();
+            var transcriptMedia = Assert.Single(sampleExamples, example =>
+                string.Equals(example.GetProperty("kind").GetString(), "media", StringComparison.OrdinalIgnoreCase) &&
+                example.TryGetProperty("media", out var media) &&
+                string.Equals(media.GetProperty("type").GetString(), "terminal", StringComparison.OrdinalIgnoreCase));
+            var mediaUrl = transcriptMedia.GetProperty("media").GetProperty("url").GetString();
+            Assert.Contains("/api/powershell/powershell-example-media/", mediaUrl, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_PrefersPlaybackSidecars_ForImportedExamples()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-playback-media-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne', 'Invoke-SampleTwo')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                function Invoke-SampleTwo { param([string]$Name) "Ran two for $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.ps1"), "Invoke-SampleOne -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.cast"), "dummy cast");
+            File.WriteAllBytes(Path.Combine(examplesDir, "Invoke-SampleOne.png"), new byte[] { 1, 2, 3, 4 });
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both",
+                CoverageReportPath = "reports/api-coverage.json"
+            };
+
+            var result = WebApiDocsGenerator.Generate(options);
+
+            using var sampleOneJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-sampleone.json")));
+            var sampleOneExamples = sampleOneJson.RootElement.GetProperty("examples").EnumerateArray().ToArray();
+            var playbackMedia = Assert.Single(sampleOneExamples, example =>
+                string.Equals(example.GetProperty("kind").GetString(), "media", StringComparison.OrdinalIgnoreCase) &&
+                example.TryGetProperty("media", out var media) &&
+                string.Equals(media.GetProperty("type").GetString(), "terminal", StringComparison.OrdinalIgnoreCase));
+            var media = playbackMedia.GetProperty("media");
+            var mediaUrl = media.GetProperty("url").GetString();
+            var posterUrl = media.GetProperty("posterUrl").GetString();
+            Assert.Contains("/api/powershell/powershell-example-media/", mediaUrl, StringComparison.OrdinalIgnoreCase);
+            Assert.EndsWith(".cast", mediaUrl, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("/api/powershell/powershell-example-media/", posterUrl, StringComparison.OrdinalIgnoreCase);
+            Assert.EndsWith(".png", posterUrl, StringComparison.OrdinalIgnoreCase);
+            Assert.Equal("application/x-asciicast", media.GetProperty("mimeType").GetString());
+            Assert.False(string.IsNullOrWhiteSpace(media.GetProperty("capturedAtUtc").GetString()));
+            Assert.False(string.IsNullOrWhiteSpace(media.GetProperty("sourceUpdatedAtUtc").GetString()));
+            Assert.Contains("Open terminal playback", media.GetProperty("title").GetString(), StringComparison.Ordinal);
+
+            var castFileName = Path.GetFileName(new Uri("https://example.test" + mediaUrl).LocalPath);
+            var posterFileName = Path.GetFileName(new Uri("https://example.test" + posterUrl).LocalPath);
+            Assert.True(File.Exists(Path.Combine(outputPath, "powershell-example-media", castFileName)));
+            Assert.True(File.Exists(Path.Combine(outputPath, "powershell-example-media", posterFileName)));
+            Assert.False(string.IsNullOrWhiteSpace(result.PowerShellExampleMediaManifestPath));
+            Assert.True(File.Exists(result.PowerShellExampleMediaManifestPath!));
+
+            using var mediaManifest = JsonDocument.Parse(File.ReadAllText(result.PowerShellExampleMediaManifestPath!));
+            Assert.Equal(1, mediaManifest.RootElement.GetProperty("entryCount").GetInt32());
+            var manifestEntry = Assert.Single(mediaManifest.RootElement.GetProperty("entries").EnumerateArray());
+            Assert.Equal("Invoke-SampleOne", manifestEntry.GetProperty("commandName").GetString());
+            Assert.Equal("Invoke-SampleOne.ps1", manifestEntry.GetProperty("sourcePath").GetString());
+            Assert.Equal("Invoke-SampleOne.cast", manifestEntry.GetProperty("assetPath").GetString());
+            Assert.Equal("Invoke-SampleOne.png", manifestEntry.GetProperty("posterAssetPath").GetString());
+            Assert.True(manifestEntry.GetProperty("hasPoster").GetBoolean());
+
+            var sampleOneHtml = File.ReadAllText(Path.Combine(outputPath, "invoke-sampleone", "index.html"));
+            Assert.Contains("Open terminal playback", sampleOneHtml, StringComparison.Ordinal);
+            Assert.Contains("Captured terminal playback for Invoke-SampleOne.ps1.", sampleOneHtml, StringComparison.Ordinal);
+            Assert.Contains("example-media-poster", sampleOneHtml, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("Captured ", sampleOneHtml, StringComparison.Ordinal);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_UsesParentDirectoryWhenPowerShellExamplesPathPointsToSingleFile()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-single-file-manifest-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            var examplePath = Path.Combine(examplesDir, "Invoke-SampleOne.ps1");
+            File.WriteAllText(examplePath, "Invoke-SampleOne -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.cast"), "dummy cast");
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplePath,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both"
+            };
+
+            var result = WebApiDocsGenerator.Generate(options);
+
+            Assert.False(string.IsNullOrWhiteSpace(result.PowerShellExampleMediaManifestPath));
+            using var mediaManifest = JsonDocument.Parse(File.ReadAllText(result.PowerShellExampleMediaManifestPath!));
+            var manifestEntry = Assert.Single(mediaManifest.RootElement.GetProperty("entries").EnumerateArray());
+            Assert.Equal("Invoke-SampleOne.ps1", manifestEntry.GetProperty("sourcePath").GetString());
+            Assert.Equal("Invoke-SampleOne.cast", manifestEntry.GetProperty("assetPath").GetString());
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_RestagesPlaybackMediaWhenSourceTimestampChangesBackward()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-restage-playback-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            var examplePath = Path.Combine(examplesDir, "Invoke-SampleOne.ps1");
+            var castPath = Path.Combine(examplesDir, "Invoke-SampleOne.cast");
+            File.WriteAllText(examplePath, "Invoke-SampleOne -Name 'Alpha'");
+            File.WriteAllText(castPath, "newer capture");
+            File.SetLastWriteTimeUtc(castPath, DateTime.UtcNow.AddMinutes(5));
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both"
+            };
+
+            WebApiDocsGenerator.Generate(options);
+
+            File.WriteAllText(castPath, "older but current capture");
+            File.SetLastWriteTimeUtc(castPath, DateTime.UtcNow.AddMinutes(-30));
+
+            WebApiDocsGenerator.Generate(options);
+
+            var stagedCast = Directory.GetFiles(Path.Combine(outputPath, "powershell-example-media"), "*.cast").Single();
+            Assert.Equal("older but current capture", File.ReadAllText(stagedCast));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_WarnsWhenPlaybackAssetsAreOversizedStaleOrUnsupported()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-playback-health-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne', 'Invoke-SampleTwo')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                function Invoke-SampleTwo { param([string]$Name) "Ran two for $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+
+            var examplePath = Path.Combine(examplesDir, "Invoke-SampleOne.ps1");
+            var castPath = Path.Combine(examplesDir, "Invoke-SampleOne.cast");
+            var posterPath = Path.Combine(examplesDir, "Invoke-SampleOne.png");
+            var unsupportedPath = Path.Combine(examplesDir, "Invoke-SampleOne.gif");
+
+            File.WriteAllText(examplePath, "Invoke-SampleOne -Name 'Alpha'");
+            File.WriteAllBytes(castPath, new byte[(2 * 1024 * 1024) + 128]);
+            File.WriteAllBytes(posterPath, new byte[(1024 * 1024) + 128]);
+            File.WriteAllBytes(unsupportedPath, new byte[] { 1, 2, 3, 4 });
+
+            var now = DateTime.UtcNow;
+            File.SetLastWriteTimeUtc(castPath, now.AddMinutes(-20));
+            File.SetLastWriteTimeUtc(posterPath, now.AddMinutes(-30));
+            File.SetLastWriteTimeUtc(examplePath, now.AddMinutes(-5));
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both"
+            };
+
+            var result = WebApiDocsGenerator.Generate(options);
+
+            Assert.Contains(result.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("unsupported playback sidecar", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleOne.gif", StringComparison.OrdinalIgnoreCase));
+            Assert.Contains(result.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("playback sidecar", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("recommended 2 MiB", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleOne.cast", StringComparison.OrdinalIgnoreCase));
+            Assert.Contains(result.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("playback poster", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("recommended 1 MiB", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleOne.png", StringComparison.OrdinalIgnoreCase));
+            Assert.Contains(result.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("looks stale", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleOne.cast", StringComparison.OrdinalIgnoreCase));
+            Assert.Contains(result.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("looks stale", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleOne.png", StringComparison.OrdinalIgnoreCase));
+            Assert.False(string.IsNullOrWhiteSpace(result.PowerShellExampleMediaManifestPath));
+
+            using var sampleOneJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(outputPath, "types", "invoke-sampleone.json")));
+            var staleMedia = Assert.Single(sampleOneJson.RootElement.GetProperty("examples").EnumerateArray(), example =>
+                string.Equals(example.GetProperty("kind").GetString(), "media", StringComparison.OrdinalIgnoreCase));
+            Assert.False(string.IsNullOrWhiteSpace(staleMedia.GetProperty("media").GetProperty("capturedAtUtc").GetString()));
+            Assert.False(string.IsNullOrWhiteSpace(staleMedia.GetProperty("media").GetProperty("sourceUpdatedAtUtc").GetString()));
+
+            var sampleOneHtml = File.ReadAllText(Path.Combine(outputPath, "invoke-sampleone", "index.html"));
+            Assert.Contains("Script changed after this capture", sampleOneHtml, StringComparison.Ordinal);
+
+            using var mediaManifest = JsonDocument.Parse(File.ReadAllText(result.PowerShellExampleMediaManifestPath!));
+            var manifestEntry = Assert.Single(mediaManifest.RootElement.GetProperty("entries").EnumerateArray());
+            Assert.True(manifestEntry.GetProperty("hasUnsupportedSidecars").GetBoolean());
+            Assert.True(manifestEntry.GetProperty("hasOversizedAssets").GetBoolean());
+            Assert.True(manifestEntry.GetProperty("hasStaleAssets").GetBoolean());
+
+            using var coverage = JsonDocument.Parse(File.ReadAllText(result.CoveragePath!));
+            var powershell = coverage.RootElement.GetProperty("powershell");
+            Assert.Equal(1, powershell.GetProperty("importedScriptPlaybackMedia").GetProperty("covered").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("importedScriptPlaybackMediaUnsupportedSidecars").GetProperty("covered").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("importedScriptPlaybackMediaOversizedAssets").GetProperty("covered").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("importedScriptPlaybackMediaStaleAssets").GetProperty("covered").GetInt32());
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingImportedScriptPlaybackMediaUnsupportedSidecars").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-SampleOne", StringComparison.Ordinal));
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingImportedScriptPlaybackMediaOversizedAssets").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-SampleOne", StringComparison.Ordinal));
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingImportedScriptPlaybackMediaStaleAssets").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-SampleOne", StringComparison.Ordinal));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void Generate_PowerShellHelp_ReportsPlaybackCoverage_AndWarnsWhenPosterIsMissing()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-apidocs-powershell-playback-coverage-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath,
+                """
+                <?xml version="1.0" encoding="utf-8"?>
+                <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+                  <command:command>
+                    <command:details>
+                      <command:name>Invoke-SampleOne</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Runs the first sample.</maml:para></maml:description>
+                    </command:details>
+                    <command:syntax>
+                      <command:syntaxItem>
+                        <command:name>Invoke-SampleOne</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Name</maml:name>
+                          <command:parameterValue required="true">string</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                    </command:syntax>
+                    <command:parameters>
+                      <command:parameter required="true">
+                        <maml:name>Name</maml:name>
+                        <maml:description><maml:para>Name value.</maml:para></maml:description>
+                        <command:parameterValue required="true">string</command:parameterValue>
+                      </command:parameter>
+                    </command:parameters>
+                  </command:command>
+                  <command:command>
+                    <command:details>
+                      <command:name>Invoke-SampleTwo</command:name>
+                      <command:commandType>Function</command:commandType>
+                      <maml:description><maml:para>Runs the second sample.</maml:para></maml:description>
+                    </command:details>
+                    <command:syntax>
+                      <command:syntaxItem>
+                        <command:name>Invoke-SampleTwo</command:name>
+                        <command:parameter required="true">
+                          <maml:name>Name</maml:name>
+                          <command:parameterValue required="true">string</command:parameterValue>
+                        </command:parameter>
+                      </command:syntaxItem>
+                    </command:syntax>
+                    <command:parameters>
+                      <command:parameter required="true">
+                        <maml:name>Name</maml:name>
+                        <maml:description><maml:para>Name value.</maml:para></maml:description>
+                        <command:parameterValue required="true">string</command:parameterValue>
+                      </command:parameter>
+                    </command:parameters>
+                  </command:command>
+                </helpItems>
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleOne', 'Invoke-SampleTwo')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleOne { param([string]$Name) "Ran one for $Name" }
+                function Invoke-SampleTwo { param([string]$Name) "Ran two for $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.ps1"), "Invoke-SampleOne -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleOne.cast"), "dummy cast one");
+            File.WriteAllBytes(Path.Combine(examplesDir, "Invoke-SampleOne.png"), new byte[] { 1, 2, 3, 4 });
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleTwo.ps1"), "Invoke-SampleTwo -Name 'Beta'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleTwo.cast"), "dummy cast two");
+
+            var outputPath = Path.Combine(root, "_site", "api", "powershell");
+            var options = new WebApiDocsOptions
+            {
+                Type = ApiDocsType.PowerShell,
+                HelpPath = helpPath,
+                PowerShellExamplesPath = examplesDir,
+                OutputPath = outputPath,
+                Title = "PowerShell API",
+                BaseUrl = "/api/powershell",
+                Template = "docs",
+                Format = "both",
+                CoverageReportPath = "reports/api-coverage.json"
+            };
+
+            var result = WebApiDocsGenerator.Generate(options);
+
+            Assert.Contains(result.Warnings, warning =>
+                warning.Contains("[PFWEB.APIDOCS.POWERSHELL]", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("without poster art", StringComparison.OrdinalIgnoreCase) &&
+                warning.Contains("Invoke-SampleTwo", StringComparison.OrdinalIgnoreCase));
+
+            using var coverage = JsonDocument.Parse(File.ReadAllText(result.CoveragePath!));
+            var powershell = coverage.RootElement.GetProperty("powershell");
+            Assert.Equal(2, powershell.GetProperty("importedScriptPlaybackMedia").GetProperty("covered").GetInt32());
+            Assert.Equal(2, powershell.GetProperty("importedScriptPlaybackMedia").GetProperty("total").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("importedScriptPlaybackMediaWithPoster").GetProperty("covered").GetInt32());
+            Assert.Equal(2, powershell.GetProperty("importedScriptPlaybackMediaWithPoster").GetProperty("total").GetInt32());
+            Assert.Equal(1, powershell.GetProperty("importedScriptPlaybackMediaWithoutPoster").GetProperty("covered").GetInt32());
+            Assert.Equal(2, powershell.GetProperty("importedScriptPlaybackMediaWithoutPoster").GetProperty("total").GetInt32());
+            Assert.Equal(0, powershell.GetProperty("importedScriptPlaybackMediaUnsupportedSidecars").GetProperty("covered").GetInt32());
+            Assert.Equal(0, powershell.GetProperty("importedScriptPlaybackMediaOversizedAssets").GetProperty("covered").GetInt32());
+            Assert.Equal(0, powershell.GetProperty("importedScriptPlaybackMediaStaleAssets").GetProperty("covered").GetInt32());
+
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingImportedScriptPlaybackMedia").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-SampleOne", StringComparison.Ordinal));
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingImportedScriptPlaybackMedia").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-SampleTwo", StringComparison.Ordinal));
+            Assert.Contains(
+                powershell.GetProperty("commandsUsingImportedScriptPlaybackMediaWithoutPoster").EnumerateArray().Select(x => x.GetString()),
+                value => string.Equals(value, "Invoke-SampleTwo", StringComparison.Ordinal));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    private static string BuildMinimalPowerShellHelpForValidation()
+    {
+        return
+            """
+            <?xml version="1.0" encoding="utf-8"?>
+            <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+              <command:command>
+                <command:details>
+                  <command:name>Invoke-SampleOne</command:name>
+                  <command:commandType>Function</command:commandType>
+                  <maml:description><maml:para>Runs the first sample.</maml:para></maml:description>
+                </command:details>
+                <command:syntax>
+                  <command:syntaxItem>
+                    <command:name>Invoke-SampleOne</command:name>
+                    <command:parameter required="true">
+                      <maml:name>Name</maml:name>
+                      <command:parameterValue required="true">string</command:parameterValue>
+                    </command:parameter>
+                  </command:syntaxItem>
+                </command:syntax>
+                <command:parameters>
+                  <command:parameter required="true">
+                    <maml:name>Name</maml:name>
+                    <maml:description><maml:para>Name value.</maml:para></maml:description>
+                    <command:parameterValue required="true">string</command:parameterValue>
+                  </command:parameter>
+                </command:parameters>
+              </command:command>
+              <command:command>
+                <command:details>
+                  <command:name>Invoke-SampleTwo</command:name>
+                  <command:commandType>Function</command:commandType>
+                  <maml:description><maml:para>Runs the second sample.</maml:para></maml:description>
+                </command:details>
+                <command:syntax>
+                  <command:syntaxItem>
+                    <command:name>Invoke-SampleTwo</command:name>
+                    <command:parameter required="true">
+                      <maml:name>Name</maml:name>
+                      <command:parameterValue required="true">string</command:parameterValue>
+                    </command:parameter>
+                  </command:syntaxItem>
+                </command:syntax>
+                <command:parameters>
+                  <command:parameter required="true">
+                    <maml:name>Name</maml:name>
+                    <maml:description><maml:para>Name value.</maml:para></maml:description>
+                    <command:parameterValue required="true">string</command:parameterValue>
+                  </command:parameter>
+                </command:parameters>
+              </command:command>
+            </helpItems>
+            """;
+    }
+
+    private static bool IsGitAvailable()
+    {
+        try
+        {
+            var psi = new ProcessStartInfo
+            {
+                FileName = "git",
+                RedirectStandardOutput = true,
+                RedirectStandardError = true,
+                UseShellExecute = false,
+                CreateNoWindow = true
+            };
+            psi.ArgumentList.Add("--version");
+            using var process = Process.Start(psi);
+            if (process is null)
+                return false;
+
+            process.WaitForExit(2000);
+            return process.ExitCode == 0;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    private static void RunGit(string workingDirectory, params string[] args)
+    {
+        RunGit(workingDirectory, null, args);
+    }
+
+    private static void RunGit(string workingDirectory, IReadOnlyDictionary<string, string>? environment, params string[] args)
+    {
+        var psi = new ProcessStartInfo
+        {
+            FileName = "git",
+            WorkingDirectory = workingDirectory,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            UseShellExecute = false,
+            CreateNoWindow = true
+        };
+        foreach (var arg in args)
+            psi.ArgumentList.Add(arg);
+
+        if (environment is not null)
+        {
+            foreach (var pair in environment)
+                psi.Environment[pair.Key] = pair.Value;
+        }
+
+        using var process = Process.Start(psi);
+        if (process is null)
+            throw new InvalidOperationException("Failed to start git.");
+
+        var stdout = process.StandardOutput.ReadToEnd();
+        var stderr = process.StandardError.ReadToEnd();
+        process.WaitForExit(10000);
+        if (process.ExitCode != 0)
+            throw new InvalidOperationException($"git {string.Join(" ", args)} failed: {stderr}{Environment.NewLine}{stdout}");
+    }
+
+    private static void TryDeleteDirectory(string path)
+    {
+        try
+        {
+            if (Directory.Exists(path))
+                Directory.Delete(path, true);
+        }
+        catch
+        {
+            // best-effort cleanup for git temp repos on Windows
+        }
+    }
 }
diff --git a/PowerForge.Tests/WebApiDocsGeneratorSourceAndCssTests.cs b/PowerForge.Tests/WebApiDocsGeneratorSourceAndCssTests.cs
index 4950e04d..158a2aee 100644
--- a/PowerForge.Tests/WebApiDocsGeneratorSourceAndCssTests.cs
+++ b/PowerForge.Tests/WebApiDocsGeneratorSourceAndCssTests.cs
@@ -162,6 +162,59 @@ public void GenerateDocsHtml_UsesThemeCssLinksWithoutInliningFallback_WhenCustom
         }
     }
 
+    [Fact]
+    public void GenerateDocsHtml_OmitsOverviewWorkspaceRail_WhenUsingDocsTemplate()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-webapidocs-overview-layout-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        var xmlPath = Path.Combine(root, "test.xml");
+        File.WriteAllText(xmlPath,
+            """
+            <doc>
+              <assembly><name>Test</name></assembly>
+              <members>
+                <member name="T:MyNamespace.Sample">
+                  <summary>Sample.</summary>
+                </member>
+              </members>
+            </doc>
+            """);
+
+        var cssPath = Path.Combine(root, "css", "api.css");
+        Directory.CreateDirectory(Path.GetDirectoryName(cssPath)!);
+        File.WriteAllText(cssPath, ".api-layout { outline: 0; }");
+
+        var outputPath = Path.Combine(root, "api");
+        var options = new WebApiDocsOptions
+        {
+            XmlPath = xmlPath,
+            OutputPath = outputPath,
+            Format = "html",
+            Template = "docs",
+            BaseUrl = "/api",
+            CssHref = "/css/api.css"
+        };
+
+        try
+        {
+            var result = WebApiDocsGenerator.Generate(options);
+            Assert.True(result.TypeCount > 0);
+
+            var indexHtmlPath = Path.Combine(outputPath, "index.html");
+            Assert.True(File.Exists(indexHtmlPath), "Expected index.html to be generated.");
+            var html = File.ReadAllText(indexHtmlPath);
+
+            Assert.DoesNotContain("Workspace Stats", html, StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain("Browse smarter", html, StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain("Jump To", html, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
     [Fact]
     public void GenerateDocsHtml_SourceUrlMappings_UseMostSpecificPrefix_AndHonorStripPathPrefix()
     {
@@ -331,7 +384,9 @@ public void GenerateDocsHtml_WarnsWhenSourceUrlPatternLikelyDuplicatesPathPrefix
             var result = WebApiDocsGenerator.Generate(options);
             Assert.True(result.TypeCount > 0);
             Assert.Contains(result.Warnings, w =>
-                w.Contains("detected likely duplicated path prefixes in GitHub source URLs", StringComparison.OrdinalIgnoreCase));
+                w.Contains("detected likely duplicated path prefixes in GitHub source URLs", StringComparison.OrdinalIgnoreCase) &&
+                w.Contains("Example URLs:", StringComparison.OrdinalIgnoreCase) &&
+                w.Contains("https://github.com/example/PowerForge.Web/blob/main/PowerForge.Web/", StringComparison.OrdinalIgnoreCase));
         }
         finally
         {
@@ -414,6 +469,84 @@ public void GenerateDocsHtml_WarnsWhenSourceUrlMappingUsesUnsupportedToken()
             Assert.Contains(result.Warnings, w =>
                 w.Contains("[PFWEB.APIDOCS.SOURCE]", StringComparison.OrdinalIgnoreCase) &&
                 w.Contains("unsupported token(s): {branch}", StringComparison.OrdinalIgnoreCase));
+            Assert.Contains(result.Warnings, w =>
+                w.Contains("[PFWEB.APIDOCS.SOURCE]", StringComparison.OrdinalIgnoreCase) &&
+                w.Contains("generated source URLs still contain unresolved template tokens", StringComparison.OrdinalIgnoreCase) &&
+                w.Contains("{branch}", StringComparison.OrdinalIgnoreCase));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void GenerateDocsHtml_RendersXmlExampleMedia_InJsonAndHtml()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-webapidocs-example-media-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        var xmlPath = Path.Combine(root, "test.xml");
+        File.WriteAllText(xmlPath,
+            """
+            <doc>
+              <assembly><name>Test</name></assembly>
+              <members>
+                <member name="T:MyNamespace.Sample">
+                  <summary>Sample.</summary>
+                  <example>
+                    <code>Sample.Run();</code>
+                    <media kind="terminal" src="/casts/sample.cast" title="Terminal playback" caption="Recorded terminal output." poster="/images/sample-terminal.png" mimeType="application/x-asciicast" />
+                    <media kind="video" src="/videos/sample" title="Video playback" caption="Recorded video output." mimeType="video/mp4" />
+                    <image src="/images/sample-output.png" alt="Rendered sample output" caption="Example screenshot." width="1280" height="720" />
+                  </example>
+                </member>
+              </members>
+            </doc>
+            """);
+
+        var outputPath = Path.Combine(root, "api");
+        var options = new WebApiDocsOptions
+        {
+            XmlPath = xmlPath,
+            OutputPath = outputPath,
+            Format = "both",
+            Template = "docs",
+            BaseUrl = "/api"
+        };
+
+        try
+        {
+            var result = WebApiDocsGenerator.Generate(options);
+            Assert.True(result.TypeCount > 0);
+
+            var typeJsonFiles = Directory.GetFiles(Path.Combine(outputPath, "types"), "*.json", SearchOption.TopDirectoryOnly);
+            Assert.Single(typeJsonFiles);
+            var jsonPath = typeJsonFiles[0];
+            var json = File.ReadAllText(jsonPath);
+            Assert.Contains("\"kind\": \"media\"", json, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("\"type\": \"terminal\"", json, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("\"url\": \"/casts/sample.cast\"", json, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("\"posterUrl\": \"/images/sample-terminal.png\"", json, StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain("\"capturedAtUtc\":", json, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("\"type\": \"image\"", json, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("\"width\": 1280", json, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("\"height\": 720", json, StringComparison.OrdinalIgnoreCase);
+
+            var htmlPath = Path.Combine(outputPath, Path.GetFileNameWithoutExtension(jsonPath), "index.html");
+            Assert.True(File.Exists(htmlPath));
+            var html = File.ReadAllText(htmlPath);
+            Assert.Contains("class=\"example-media example-media-terminal\"", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("href=\"/casts/sample.cast\"", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("Recorded terminal output.", html, StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain("class=\"example-media-meta\"", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("class=\"example-media example-media-video\"", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("<source src=\"/videos/sample\" type=\"video/mp4\" />", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("class=\"example-media example-media-image\"", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("src=\"/images/sample-output.png\"", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("alt=\"Rendered sample output\"", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("width=\"1280\"", html, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("height=\"720\"", html, StringComparison.OrdinalIgnoreCase);
         }
         finally
         {
diff --git a/PowerForge.Tests/WebCliApiDocsPreflightTests.cs b/PowerForge.Tests/WebCliApiDocsPreflightTests.cs
index b7464300..2da75490 100644
--- a/PowerForge.Tests/WebCliApiDocsPreflightTests.cs
+++ b/PowerForge.Tests/WebCliApiDocsPreflightTests.cs
@@ -100,6 +100,73 @@ public void HandleSubCommand_ApiDocs_FailsWhenNavSurfaceConfiguredWithoutNav()
         }
     }
 
+    [Fact]
+    public void HandleSubCommand_ApiDocs_FailsWhenSourceRootLooksOneLevelAboveGitHubRepo()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-cli-apidocs-preflight-root-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            Directory.CreateDirectory(Path.Combine(root, "TestRepo"));
+            var xmlPath = Path.Combine(root, "test.xml");
+            File.WriteAllText(xmlPath, BuildMinimalXml());
+            var outPath = Path.Combine(root, "_site", "api");
+
+            var args = new[]
+            {
+                "--type", "CSharp",
+                "--xml", xmlPath,
+                "--out", outPath,
+                "--format", "json",
+                "--fail-on-warnings",
+                "--source-root", root,
+                "--source-url", "https://github.com/EvotecIT/TestRepo/blob/main/{path}#L{line}"
+            };
+
+            var exitCode = WebCliCommandHandlers.HandleSubCommand("apidocs", args, outputJson: true, logger: new WebConsoleLogger(), outputSchemaVersion: 1);
+            Assert.Equal(2, exitCode);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void HandleSubCommand_ApiDocs_AllowsSourceRootParentWhenSourceUrlUsesPathNoRoot()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-cli-apidocs-preflight-pathnoroot-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            Directory.CreateDirectory(Path.Combine(root, "TestRepo"));
+            var xmlPath = Path.Combine(root, "test.xml");
+            File.WriteAllText(xmlPath, BuildMinimalXml());
+            var outPath = Path.Combine(root, "_site", "api");
+
+            var args = new[]
+            {
+                "--type", "CSharp",
+                "--xml", xmlPath,
+                "--out", outPath,
+                "--format", "json",
+                "--fail-on-warnings",
+                "--source-root", root,
+                "--source-url", "https://github.com/EvotecIT/TestRepo/blob/main/{pathNoRoot}#L{line}"
+            };
+
+            var exitCode = WebCliCommandHandlers.HandleSubCommand("apidocs", args, outputJson: true, logger: new WebConsoleLogger(), outputSchemaVersion: 1);
+            Assert.Equal(0, exitCode);
+            Assert.True(File.Exists(Path.Combine(outPath, "index.json")));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
     [Fact]
     public void HandleSubCommand_ApiDocs_FailsWhenLegacyAliasModeIsInvalid()
     {
@@ -130,6 +197,143 @@ public void HandleSubCommand_ApiDocs_FailsWhenLegacyAliasModeIsInvalid()
         }
     }
 
+    [Fact]
+    public void HandleSubCommand_ApiDocs_FailsWhenPowerShellExampleValidationFindsInvalidScripts()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-cli-apidocs-ps-validate-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) }");
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "BrokenExample.ps1"), "Invoke-SampleFunction -Name (");
+
+            var outPath = Path.Combine(root, "_site", "api");
+            var args = new[]
+            {
+                "--type", "PowerShell",
+                "--help-path", helpPath,
+                "--out", outPath,
+                "--format", "json",
+                "--validate-ps-examples",
+                "--fail-on-ps-example-validation"
+            };
+
+            var exitCode = WebCliCommandHandlers.HandleSubCommand("apidocs", args, outputJson: true, logger: new WebConsoleLogger(), outputSchemaVersion: 1);
+
+            Assert.Equal(2, exitCode);
+            Assert.True(File.Exists(Path.Combine(outPath, "powershell-example-validation.json")));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void HandleSubCommand_ApiDocs_FailOnPowerShellExampleValidationImpliesValidation()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-cli-apidocs-ps-validate-implicit-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) }");
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "BrokenExample.ps1"), "Invoke-SampleFunction -Name (");
+
+            var outPath = Path.Combine(root, "_site", "api");
+            var args = new[]
+            {
+                "--type", "PowerShell",
+                "--help-path", helpPath,
+                "--out", outPath,
+                "--format", "json",
+                "--fail-on-ps-example-validation"
+            };
+
+            var exitCode = WebCliCommandHandlers.HandleSubCommand("apidocs", args, outputJson: true, logger: new WebConsoleLogger(), outputSchemaVersion: 1);
+            Assert.Equal(2, exitCode);
+            Assert.True(File.Exists(Path.Combine(outPath, "powershell-example-validation.json")));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void HandleSubCommand_ApiDocs_FailOnPowerShellExampleExecutionImpliesExecution()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-cli-apidocs-ps-execute-implicit-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleFunction { param([string]$Name) "Executed $Name" }
+                """);
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.Fail.ps1"), "Invoke-SampleFunction -Name 'Beta'; throw 'boom'");
+
+            var outPath = Path.Combine(root, "_site", "api");
+            var args = new[]
+            {
+                "--type", "PowerShell",
+                "--help-path", helpPath,
+                "--out", outPath,
+                "--format", "json",
+                "--fail-on-ps-example-execution"
+            };
+
+            var exitCode = WebCliCommandHandlers.HandleSubCommand("apidocs", args, outputJson: true, logger: new WebConsoleLogger(), outputSchemaVersion: 1);
+            Assert.Equal(2, exitCode);
+            Assert.True(File.Exists(Path.Combine(outPath, "powershell-example-validation.json")));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
     private static string BuildMinimalXml()
     {
         return
@@ -147,6 +351,39 @@ private static string BuildMinimalXml()
             """;
     }
 
+    private static string BuildMinimalPowerShellHelpForValidation()
+    {
+        return
+            """
+            <?xml version="1.0" encoding="utf-8"?>
+            <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+              <command:command>
+                <command:details>
+                  <command:name>Invoke-SampleFunction</command:name>
+                  <command:commandType>Function</command:commandType>
+                  <maml:description><maml:para>Invokes data.</maml:para></maml:description>
+                </command:details>
+                <command:syntax>
+                  <command:syntaxItem>
+                    <command:name>Invoke-SampleFunction</command:name>
+                    <command:parameter required="true">
+                      <maml:name>Name</maml:name>
+                      <command:parameterValue required="true">string</command:parameterValue>
+                    </command:parameter>
+                  </command:syntaxItem>
+                </command:syntax>
+                <command:parameters>
+                  <command:parameter required="true">
+                    <maml:name>Name</maml:name>
+                    <maml:description><maml:para>Name value.</maml:para></maml:description>
+                    <command:parameterValue required="true">string</command:parameterValue>
+                  </command:parameter>
+                </command:parameters>
+              </command:command>
+            </helpItems>
+            """;
+    }
+
     private static void TryDeleteDirectory(string path)
     {
         try
diff --git a/PowerForge.Tests/WebPipelineRunnerApiDocsPreflightTests.cs b/PowerForge.Tests/WebPipelineRunnerApiDocsPreflightTests.cs
index 141d59fe..e80ad31e 100644
--- a/PowerForge.Tests/WebPipelineRunnerApiDocsPreflightTests.cs
+++ b/PowerForge.Tests/WebPipelineRunnerApiDocsPreflightTests.cs
@@ -1,6 +1,8 @@
 using System;
+using System.Diagnostics;
 using System.IO;
 using System.Linq;
+using System.Text.Json;
 using PowerForge.Web.Cli;
 using Xunit;
 
@@ -143,16 +145,435 @@ public void RunPipeline_ApiDocsPreflight_FailsWhenNavSurfaceConfiguredWithoutNav
         }
     }
 
+    [Fact]
+    public void RunPipeline_ApiDocsPreflight_FailsWhenSourceRootLooksOneLevelAboveGitHubRepo()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-preflight-root-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            Directory.CreateDirectory(Path.Combine(root, "TestRepo"));
+            var xmlPath = Path.Combine(root, "test.xml");
+            File.WriteAllText(xmlPath, BuildMinimalXml());
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "CSharp",
+                      "xml": "./test.xml",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "failOnWarnings": true,
+                      "sourceRoot": ".",
+                      "sourceUrl": "https://github.com/EvotecIT/TestRepo/blob/main/{path}#L{line}"
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("[PFWEB.APIDOCS.SOURCE]", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("looks one level above repo 'TestRepo'", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
     [Fact]
     public void RunPipeline_ApiDocs_RespectsMemberXrefKindsAndMaxPerType()
     {
-        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-member-xref-" + Guid.NewGuid().ToString("N"));
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-member-xref-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var xmlPath = Path.Combine(root, "test.xml");
+            File.WriteAllText(xmlPath, BuildMinimalXmlWithMembers());
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "CSharp",
+                      "xml": "./test.xml",
+                      "out": "./_site/api",
+                      "format": "both",
+                      "memberXrefKinds": [ "methods", "properties" ],
+                      "memberXrefMaxPerType": 1
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.True(result.Success);
+            Assert.Single(result.Steps);
+            Assert.True(result.Steps[0].Success);
+
+            var xrefPath = Path.Combine(root, "_site", "api", "xrefmap.json");
+            Assert.True(File.Exists(xrefPath));
+            var json = File.ReadAllText(xrefPath);
+            Assert.Contains("M:TestNamespace.TestType.Run(System.String)", json, StringComparison.Ordinal);
+            Assert.DoesNotContain("P:TestNamespace.TestType.Name", json, StringComparison.Ordinal);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_FailsWhenLegacyAliasModeIsInvalid()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-legacy-mode-invalid-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var xmlPath = Path.Combine(root, "test.xml");
+            File.WriteAllText(xmlPath, BuildMinimalXml());
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "CSharp",
+                      "xml": "./test.xml",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "legacyAliasMode": "legacy"
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("legacy-alias-mode", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_FailsWhenGeneratedOnlyPowerShellExamplesExceedThreshold()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-generated-threshold-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpWithoutExamples());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) }");
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "failOnCoverage": true,
+                      "maxPowerShellGeneratedFallbackOnlyExampleCount": 0
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("PowerShell generated-only fallback example count", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("exceeds allowed 0", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_FailsWhenAuthoredPowerShellExampleCoverageFallsBelowThreshold()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-authored-threshold-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpWithoutExamples());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) }");
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "failOnCoverage": true,
+                      "minPowerShellAuthoredHelpCodeExamplesPercent": 100
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("PowerShell authored-help code examples coverage", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("below required 100%", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_FailsWhenImportedPlaybackMediaIsMissingPosterArt()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-playback-poster-threshold-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) \"Ran $Name\" }");
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.ps1"), "Invoke-SampleFunction -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.cast"), "dummy cast");
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "psExamplesPath": "./Examples",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "failOnCoverage": true,
+                      "maxPowerShellImportedScriptPlaybackMediaWithoutPosterCount": 0
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("PowerShell imported-script playback media without poster count", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("exceeds allowed 0", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_ReportsPowerShellExampleMediaManifestInStepMessage()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-media-manifest-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) \"Ran $Name\" }");
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.ps1"), "Invoke-SampleFunction -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.cast"), "dummy cast");
+            File.WriteAllBytes(Path.Combine(examplesDir, "Invoke-SampleFunction.png"), new byte[] { 1, 2, 3, 4 });
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "psExamplesPath": "./Examples",
+                      "out": "./_site/api",
+                      "format": "json"
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.True(result.Success);
+            Assert.Single(result.Steps);
+            Assert.True(result.Steps[0].Success);
+            Assert.Contains("ps-example-media: powershell-example-media-manifest.json", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.True(File.Exists(Path.Combine(root, "_site", "api", "powershell-example-media-manifest.json")));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_FailsWhenImportedPlaybackMediaAssetsLookStale()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-playback-stale-threshold-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) \"Ran $Name\" }");
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            var examplePath = Path.Combine(examplesDir, "Invoke-SampleFunction.ps1");
+            var castPath = Path.Combine(examplesDir, "Invoke-SampleFunction.cast");
+            File.WriteAllText(examplePath, "Invoke-SampleFunction -Name 'Alpha'");
+            File.WriteAllText(castPath, "dummy cast");
+
+            var now = DateTime.UtcNow;
+            File.SetLastWriteTimeUtc(castPath, now.AddMinutes(-20));
+            File.SetLastWriteTimeUtc(examplePath, now.AddMinutes(-5));
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "psExamplesPath": "./Examples",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "failOnCoverage": true,
+                      "maxPowerShellImportedScriptPlaybackMediaStaleAssetCount": 0
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("PowerShell imported-script playback media with stale assets count", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("exceeds allowed 0", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocsPreflight_AllowsSourceRootParentWhenSourceUrlUsesPathNoRoot()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-preflight-pathnoroot-" + Guid.NewGuid().ToString("N"));
         Directory.CreateDirectory(root);
 
         try
         {
+            Directory.CreateDirectory(Path.Combine(root, "TestRepo"));
             var xmlPath = Path.Combine(root, "test.xml");
-            File.WriteAllText(xmlPath, BuildMinimalXmlWithMembers());
+            File.WriteAllText(xmlPath, BuildMinimalXml());
             var pipelinePath = Path.Combine(root, "pipeline.json");
             File.WriteAllText(pipelinePath,
                 """
@@ -163,25 +584,78 @@ public void RunPipeline_ApiDocs_RespectsMemberXrefKindsAndMaxPerType()
                       "type": "CSharp",
                       "xml": "./test.xml",
                       "out": "./_site/api",
-                      "format": "both",
-                      "memberXrefKinds": [ "methods", "properties" ],
-                      "memberXrefMaxPerType": 1
+                      "format": "json",
+                      "failOnWarnings": true,
+                      "sourceRoot": ".",
+                      "sourceUrl": "https://github.com/EvotecIT/TestRepo/blob/main/{pathNoRoot}#L{line}"
                     }
                   ]
                 }
                 """);
 
             var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
-
             Assert.True(result.Success);
             Assert.Single(result.Steps);
             Assert.True(result.Steps[0].Success);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
 
-            var xrefPath = Path.Combine(root, "_site", "api", "xrefmap.json");
-            Assert.True(File.Exists(xrefPath));
-            var json = File.ReadAllText(xrefPath);
-            Assert.Contains("M:TestNamespace.TestType.Run(System.String)", json, StringComparison.Ordinal);
-            Assert.DoesNotContain("P:TestNamespace.TestType.Name", json, StringComparison.Ordinal);
+    [Fact]
+    public void RunPipeline_ApiDocs_FailsWhenPowerShellExampleValidationFindsInvalidScripts()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-validate-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) }");
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "BrokenExample.ps1"), "Invoke-SampleFunction -Name (");
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "validatePowerShellExamples": true,
+                      "failOnPowerShellExampleValidation": true
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("PowerShell example validation found 1 invalid script", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+
+            var reportPath = Path.Combine(root, "_site", "api", "powershell-example-validation.json");
+            Assert.True(File.Exists(reportPath));
         }
         finally
         {
@@ -190,15 +664,30 @@ public void RunPipeline_ApiDocs_RespectsMemberXrefKindsAndMaxPerType()
     }
 
     [Fact]
-    public void RunPipeline_ApiDocs_FailsWhenLegacyAliasModeIsInvalid()
+    public void RunPipeline_ApiDocs_FailOnPowerShellExampleValidationImpliesValidation()
     {
-        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-legacy-mode-invalid-" + Guid.NewGuid().ToString("N"));
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-validate-implicit-" + Guid.NewGuid().ToString("N"));
         Directory.CreateDirectory(root);
 
         try
         {
-            var xmlPath = Path.Combine(root, "test.xml");
-            File.WriteAllText(xmlPath, BuildMinimalXml());
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"), "function Invoke-SampleFunction { param([string]$Name) }");
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "BrokenExample.ps1"), "Invoke-SampleFunction -Name (");
+
             var pipelinePath = Path.Combine(root, "pipeline.json");
             File.WriteAllText(pipelinePath,
                 """
@@ -206,11 +695,72 @@ public void RunPipeline_ApiDocs_FailsWhenLegacyAliasModeIsInvalid()
                   "steps": [
                     {
                       "task": "apidocs",
-                      "type": "CSharp",
-                      "xml": "./test.xml",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
                       "out": "./_site/api",
                       "format": "json",
-                      "legacyAliasMode": "legacy"
+                      "failOnPowerShellExampleValidation": true
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("PowerShell example validation found 1 invalid script", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.True(File.Exists(Path.Combine(root, "_site", "api", "powershell-example-validation.json")));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_FailsWhenPowerShellExampleExecutionFindsFailingScripts()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-execute-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleFunction { param([string]$Name) "Executed $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.Good.ps1"), "Invoke-SampleFunction -Name 'Alpha'");
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.Fail.ps1"), "Invoke-SampleFunction -Name 'Beta'; throw 'boom'");
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "validatePowerShellExamples": true,
+                      "executePowerShellExamples": true,
+                      "failOnPowerShellExampleExecution": true
                     }
                   ]
                 }
@@ -221,7 +771,223 @@ public void RunPipeline_ApiDocs_FailsWhenLegacyAliasModeIsInvalid()
             Assert.False(result.Success);
             Assert.Single(result.Steps);
             Assert.False(result.Steps[0].Success);
-            Assert.Contains("legacy-alias-mode", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.Contains("PowerShell example execution failed for 1 script", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+
+            var reportPath = Path.Combine(root, "_site", "api", "powershell-example-validation.json");
+            Assert.True(File.Exists(reportPath));
+            using var report = JsonDocument.Parse(File.ReadAllText(reportPath));
+            Assert.True(report.RootElement.GetProperty("executionRequested").GetBoolean());
+            Assert.Equal(1, report.RootElement.GetProperty("failedExecutionFileCount").GetInt32());
+            var artifactPaths = report.RootElement.GetProperty("files")
+                .EnumerateArray()
+                .Select(file => file.TryGetProperty("executionArtifactPath", out var path) ? path.GetString() : null)
+                .Where(static path => !string.IsNullOrWhiteSpace(path))
+                .ToArray();
+            Assert.True(artifactPaths.Length >= 1);
+            var reportDirectory = Path.GetDirectoryName(reportPath)!;
+            Assert.All(artifactPaths, path =>
+            {
+                Assert.False(Path.IsPathRooted(path));
+                Assert.True(File.Exists(Path.GetFullPath(Path.Combine(reportDirectory, path!))));
+            });
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_FailOnPowerShellExampleExecutionImpliesExecution()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-powershell-execute-implicit-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psd1"),
+                """
+                @{
+                    CmdletsToExport = @()
+                    FunctionsToExport = @('Invoke-SampleFunction')
+                    AliasesToExport = @()
+                    RootModule = 'Sample.Module.psm1'
+                }
+                """);
+            File.WriteAllText(Path.Combine(root, "Sample.Module.psm1"),
+                """
+                function Invoke-SampleFunction { param([string]$Name) "Executed $Name" }
+                """);
+
+            var examplesDir = Path.Combine(root, "Examples");
+            Directory.CreateDirectory(examplesDir);
+            File.WriteAllText(Path.Combine(examplesDir, "Invoke-SampleFunction.Fail.ps1"), "Invoke-SampleFunction -Name 'Beta'; throw 'boom'");
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "failOnPowerShellExampleExecution": true
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("PowerShell example execution failed for 1 script", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+            Assert.True(File.Exists(Path.Combine(root, "_site", "api", "powershell-example-validation.json")));
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_FailsWhenPercentCoverageThresholdExceedsOneHundred()
+    {
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-threshold-percent-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpPath = Path.Combine(root, "Sample.Module-help.xml");
+            File.WriteAllText(helpPath, BuildMinimalPowerShellHelpForValidation());
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": "./Sample.Module-help.xml",
+                      "out": "./_site/api",
+                      "format": "json",
+                      "maxPowerShellGeneratedFallbackOnlyExamplePercent": 150
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+            Assert.False(result.Success);
+            Assert.Single(result.Steps);
+            Assert.False(result.Steps[0].Success);
+            Assert.Contains("must be less than or equal to 100", result.Steps[0].Message, StringComparison.OrdinalIgnoreCase);
+        }
+        finally
+        {
+            TryDeleteDirectory(root);
+        }
+    }
+
+    [Fact]
+    public void RunPipeline_ApiDocs_EmitsGitFreshnessMetadataWhenEnabled()
+    {
+        if (!IsGitAvailable())
+            return;
+
+        var root = Path.Combine(Path.GetTempPath(), "pf-web-pipeline-apidocs-freshness-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(root);
+
+        try
+        {
+            var helpDirectory = Path.Combine(root, "en-US");
+            Directory.CreateDirectory(helpDirectory);
+            var helpPath = Path.Combine(helpDirectory, "Sample.Module-help.xml");
+            var aboutPath = Path.Combine(root, "about_SampleTopic.help.txt");
+
+            RunGit(root, "init");
+            RunGit(root, "config", "user.email", "tests@example.invalid");
+            RunGit(root, "config", "user.name", "PowerForge Tests");
+
+            File.WriteAllText(aboutPath,
+                """
+                # about_SampleTopic
+
+                Topic body.
+                """);
+            RunGit(root, "add", "about_SampleTopic.help.txt");
+            var olderCommitDate = DateTimeOffset.UtcNow.AddDays(-35).ToString("yyyy-MM-ddTHH:mm:ssK");
+            RunGit(root,
+                new Dictionary<string, string>
+                {
+                    ["GIT_AUTHOR_DATE"] = olderCommitDate,
+                    ["GIT_COMMITTER_DATE"] = olderCommitDate
+                },
+                "commit", "-m", "Add about topic");
+
+            File.WriteAllText(helpPath,
+                """
+                <?xml version="1.0" encoding="utf-8"?>
+                <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+                  <command:command>
+                    <command:details>
+                      <command:name>Get-SampleCmdlet</command:name>
+                      <maml:description><maml:para>Gets data.</maml:para></maml:description>
+                    </command:details>
+                    <maml:description>
+                      <maml:para>For more details, see about_SampleTopic.</maml:para>
+                    </maml:description>
+                    <command:syntax><command:syntaxItem><command:name>Get-SampleCmdlet</command:name></command:syntaxItem></command:syntax>
+                  </command:command>
+                </helpItems>
+                """);
+            RunGit(root, "add", "en-US/Sample.Module-help.xml");
+            var recentCommitDate = DateTimeOffset.UtcNow.AddDays(-2).ToString("yyyy-MM-ddTHH:mm:ssK");
+            RunGit(root,
+                new Dictionary<string, string>
+                {
+                    ["GIT_AUTHOR_DATE"] = recentCommitDate,
+                    ["GIT_COMMITTER_DATE"] = recentCommitDate
+                },
+                "commit", "-m", "Add help xml");
+
+            var pipelinePath = Path.Combine(root, "pipeline.json");
+            File.WriteAllText(pipelinePath,
+                """
+                {
+                  "steps": [
+                    {
+                      "task": "apidocs",
+                      "type": "PowerShell",
+                      "help": ".",
+                      "out": "./_site/api",
+                      "format": "both",
+                      "template": "docs",
+                      "generateGitFreshness": true,
+                      "gitFreshnessNewDays": 14,
+                      "gitFreshnessUpdatedDays": 90
+                    }
+                  ]
+                }
+                """);
+
+            var result = WebPipelineRunner.RunPipeline(pipelinePath, logger: null);
+
+            Assert.True(result.Success);
+            Assert.Single(result.Steps);
+            Assert.True(result.Steps[0].Success);
+
+            using var commandJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(root, "_site", "api", "types", "get-samplecmdlet.json")));
+            using var aboutJson = JsonDocument.Parse(File.ReadAllText(Path.Combine(root, "_site", "api", "types", "about-sampletopic.json")));
+            Assert.Equal("new", commandJson.RootElement.GetProperty("freshness").GetProperty("status").GetString());
+            Assert.Equal("updated", aboutJson.RootElement.GetProperty("freshness").GetProperty("status").GetString());
+            Assert.DoesNotContain(root, commandJson.RootElement.GetProperty("freshness").GetProperty("sourcePath").GetString(), StringComparison.OrdinalIgnoreCase);
+            Assert.DoesNotContain(root, aboutJson.RootElement.GetProperty("freshness").GetProperty("sourcePath").GetString(), StringComparison.OrdinalIgnoreCase);
         }
         finally
         {
@@ -270,6 +1036,72 @@ private static string BuildMinimalXmlWithMembers()
             """;
     }
 
+    private static string BuildMinimalPowerShellHelpWithoutExamples()
+    {
+        return
+            """
+            <?xml version="1.0" encoding="utf-8"?>
+            <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+              <command:command>
+                <command:details>
+                  <command:name>Invoke-SampleFunction</command:name>
+                  <command:commandType>Function</command:commandType>
+                  <maml:description><maml:para>Invokes data.</maml:para></maml:description>
+                </command:details>
+                <command:syntax>
+                  <command:syntaxItem>
+                    <command:name>Invoke-SampleFunction</command:name>
+                    <command:parameter required="true">
+                      <maml:name>Name</maml:name>
+                      <command:parameterValue required="true">string</command:parameterValue>
+                    </command:parameter>
+                  </command:syntaxItem>
+                </command:syntax>
+                <command:parameters>
+                  <command:parameter required="true">
+                    <maml:name>Name</maml:name>
+                    <maml:description><maml:para>Name value.</maml:para></maml:description>
+                    <command:parameterValue required="true">string</command:parameterValue>
+                  </command:parameter>
+                </command:parameters>
+              </command:command>
+            </helpItems>
+            """;
+    }
+
+    private static string BuildMinimalPowerShellHelpForValidation()
+    {
+        return
+            """
+            <?xml version="1.0" encoding="utf-8"?>
+            <helpItems schema="maml" xmlns="http://msh" xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
+              <command:command>
+                <command:details>
+                  <command:name>Invoke-SampleFunction</command:name>
+                  <command:commandType>Function</command:commandType>
+                  <maml:description><maml:para>Invokes data.</maml:para></maml:description>
+                </command:details>
+                <command:syntax>
+                  <command:syntaxItem>
+                    <command:name>Invoke-SampleFunction</command:name>
+                    <command:parameter required="true">
+                      <maml:name>Name</maml:name>
+                      <command:parameterValue required="true">string</command:parameterValue>
+                    </command:parameter>
+                  </command:syntaxItem>
+                </command:syntax>
+                <command:parameters>
+                  <command:parameter required="true">
+                    <maml:name>Name</maml:name>
+                    <maml:description><maml:para>Name value.</maml:para></maml:description>
+                    <command:parameterValue required="true">string</command:parameterValue>
+                  </command:parameter>
+                </command:parameters>
+              </command:command>
+            </helpItems>
+            """;
+    }
+
     private static void TryDeleteDirectory(string path)
     {
         try
@@ -282,4 +1114,66 @@ private static void TryDeleteDirectory(string path)
             // ignore cleanup failures in tests
         }
     }
+
+    private static bool IsGitAvailable()
+    {
+        try
+        {
+            var psi = new ProcessStartInfo
+            {
+                FileName = "git",
+                RedirectStandardOutput = true,
+                RedirectStandardError = true,
+                UseShellExecute = false,
+                CreateNoWindow = true
+            };
+            psi.ArgumentList.Add("--version");
+            using var process = Process.Start(psi);
+            if (process is null)
+                return false;
+
+            process.WaitForExit(2000);
+            return process.ExitCode == 0;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    private static void RunGit(string workingDirectory, params string[] args)
+    {
+        RunGit(workingDirectory, null, args);
+    }
+
+    private static void RunGit(string workingDirectory, IReadOnlyDictionary<string, string>? environment, params string[] args)
+    {
+        var psi = new ProcessStartInfo
+        {
+            FileName = "git",
+            WorkingDirectory = workingDirectory,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            UseShellExecute = false,
+            CreateNoWindow = true
+        };
+        foreach (var arg in args)
+            psi.ArgumentList.Add(arg);
+
+        if (environment is not null)
+        {
+            foreach (var pair in environment)
+                psi.Environment[pair.Key] = pair.Value;
+        }
+
+        using var process = Process.Start(psi);
+        if (process is null)
+            throw new InvalidOperationException("Failed to start git.");
+
+        var stdout = process.StandardOutput.ReadToEnd();
+        var stderr = process.StandardError.ReadToEnd();
+        process.WaitForExit(10000);
+        if (process.ExitCode != 0)
+            throw new InvalidOperationException($"git {string.Join(" ", args)} failed: {stderr}{Environment.NewLine}{stdout}");
+    }
 }
diff --git a/PowerForge.Web.Cli/WebCliCommandHandlers.DocsCommands.cs b/PowerForge.Web.Cli/WebCliCommandHandlers.DocsCommands.cs
index 600dbae9..58edfe8f 100644
--- a/PowerForge.Web.Cli/WebCliCommandHandlers.DocsCommands.cs
+++ b/PowerForge.Web.Cli/WebCliCommandHandlers.DocsCommands.cs
@@ -66,6 +66,39 @@ private static int HandleApiDocs(string[] subArgs, bool outputJson, WebConsoleLo
         if (HasOption(subArgs, "--ps-fallback-examples-off"))
             generatePowerShellFallbackExamples = false;
         var powerShellFallbackLimit = ParseIntOption(TryGetOptionValue(subArgs, "--ps-fallback-limit"), 2);
+        var validatePowerShellExamples = HasOption(subArgs, "--validate-ps-examples") || HasOption(subArgs, "--validate-powershell-examples");
+        var powerShellExampleValidationReport = TryGetOptionValue(subArgs, "--ps-example-validation-report") ??
+                                                TryGetOptionValue(subArgs, "--powershell-example-validation-report");
+        var powerShellExampleValidationTimeoutSeconds = ParseIntOption(
+            TryGetOptionValue(subArgs, "--ps-example-validation-timeout") ??
+            TryGetOptionValue(subArgs, "--powershell-example-validation-timeout"),
+            60);
+        var failOnPowerShellExampleValidation = HasOption(subArgs, "--fail-on-ps-example-validation") ||
+                                                HasOption(subArgs, "--fail-on-powershell-example-validation");
+        var executePowerShellExamples = HasOption(subArgs, "--execute-ps-examples") || HasOption(subArgs, "--execute-powershell-examples");
+        var powerShellExampleExecutionTimeoutSeconds = ParseIntOption(
+            TryGetOptionValue(subArgs, "--ps-example-execution-timeout") ??
+            TryGetOptionValue(subArgs, "--powershell-example-execution-timeout"),
+            60);
+        var failOnPowerShellExampleExecution = HasOption(subArgs, "--fail-on-ps-example-execution") ||
+                                               HasOption(subArgs, "--fail-on-powershell-example-execution");
+        if (failOnPowerShellExampleValidation)
+            validatePowerShellExamples = true;
+        if (executePowerShellExamples || failOnPowerShellExampleExecution)
+            executePowerShellExamples = true;
+        if (executePowerShellExamples)
+            validatePowerShellExamples = true;
+        var generateGitFreshness = HasOption(subArgs, "--git-freshness") || HasOption(subArgs, "--generate-git-freshness");
+        if (HasOption(subArgs, "--no-git-freshness"))
+            generateGitFreshness = false;
+        var gitFreshnessNewDays = ParseIntOption(
+            TryGetOptionValue(subArgs, "--git-freshness-new-days") ??
+            TryGetOptionValue(subArgs, "--gitFreshnessNewDays"),
+            14);
+        var gitFreshnessUpdatedDays = ParseIntOption(
+            TryGetOptionValue(subArgs, "--git-freshness-updated-days") ??
+            TryGetOptionValue(subArgs, "--gitFreshnessUpdatedDays"),
+            90);
         var sourceMapValues = GetOptionValues(subArgs, "--source-map");
         var includeUndocumented = !HasOption(subArgs, "--documented-only") && !HasOption(subArgs, "--no-undocumented");
         if (HasOption(subArgs, "--include-undocumented"))
@@ -143,7 +176,10 @@ private static int HandleApiDocs(string[] subArgs, bool outputJson, WebConsoleLo
             XrefMapPath = xrefMapPath,
             GeneratePowerShellFallbackExamples = generatePowerShellFallbackExamples,
             PowerShellExamplesPath = powerShellExamplesPath,
-            PowerShellFallbackExampleLimitPerCommand = powerShellFallbackLimit > 0 ? powerShellFallbackLimit : 2
+            PowerShellFallbackExampleLimitPerCommand = powerShellFallbackLimit > 0 ? powerShellFallbackLimit : 2,
+            GenerateGitFreshness = generateGitFreshness,
+            GitFreshnessNewDays = gitFreshnessNewDays,
+            GitFreshnessUpdatedDays = gitFreshnessUpdatedDays
         };
         if (memberXrefKinds.Count > 0)
             options.MemberXrefKinds.AddRange(memberXrefKinds);
@@ -190,9 +226,62 @@ private static int HandleApiDocs(string[] subArgs, bool outputJson, WebConsoleLo
             return Fail(headline, outputJson, logger, "web.apidocs");
         }
 
+        WebApiDocsPowerShellExampleValidationResult? powerShellExampleValidation = null;
+        string? powerShellExampleValidationPath = null;
+        if (apiType == ApiDocsType.PowerShell && validatePowerShellExamples)
+        {
+            powerShellExampleValidation = WebApiDocsGenerator.ValidatePowerShellExamples(new WebApiDocsPowerShellExampleValidationOptions
+            {
+                HelpPath = helpPath ?? string.Empty,
+                PowerShellModuleManifestPath = powerShellManifestPath,
+                PowerShellExamplesPath = powerShellExamplesPath,
+                TimeoutSeconds = powerShellExampleValidationTimeoutSeconds,
+                ExecuteMatchedExamples = executePowerShellExamples,
+                ExecutionTimeoutSeconds = powerShellExampleExecutionTimeoutSeconds
+            });
+            powerShellExampleValidationPath = WebApiDocsGenerator.WritePowerShellExampleValidationReport(
+                outPath!,
+                powerShellExampleValidationReport,
+                powerShellExampleValidation,
+                new WebApiDocsPowerShellExampleValidationOptions
+                {
+                    HelpPath = helpPath ?? string.Empty,
+                    PowerShellModuleManifestPath = powerShellManifestPath,
+                    PowerShellExamplesPath = powerShellExamplesPath,
+                    TimeoutSeconds = powerShellExampleValidationTimeoutSeconds,
+                    PreferPwsh = true,
+                    ExecuteMatchedExamples = executePowerShellExamples,
+                    ExecutionTimeoutSeconds = powerShellExampleExecutionTimeoutSeconds
+                });
+            options.PowerShellExampleValidationResult = powerShellExampleValidation;
+        }
+
         var result = WebApiDocsGenerator.Generate(options);
+        if (!string.IsNullOrWhiteSpace(powerShellExampleValidationPath))
+            result.PowerShellExampleValidationPath = powerShellExampleValidationPath;
+
+        if (apiType == ApiDocsType.PowerShell && validatePowerShellExamples && powerShellExampleValidation is not null)
+        {
+            if (failOnPowerShellExampleValidation &&
+                (!powerShellExampleValidation.ValidationSucceeded || powerShellExampleValidation.InvalidSyntaxFileCount > 0))
+            {
+                var reason = !powerShellExampleValidation.ValidationSucceeded
+                    ? "PowerShell example validation did not complete successfully."
+                    : $"PowerShell example validation found {powerShellExampleValidation.InvalidSyntaxFileCount} invalid script(s).";
+                return Fail($"{reason} Report: {powerShellExampleValidationPath}", outputJson, logger, "web.apidocs");
+            }
+            if (failOnPowerShellExampleExecution &&
+                (!powerShellExampleValidation.ExecutionCompleted || powerShellExampleValidation.FailedExecutionFileCount > 0))
+            {
+                var reason = !powerShellExampleValidation.ExecutionCompleted
+                    ? "PowerShell example execution did not complete successfully."
+                    : $"PowerShell example execution failed for {powerShellExampleValidation.FailedExecutionFileCount} script(s).";
+                return Fail($"{reason} Report: {powerShellExampleValidationPath}", outputJson, logger, "web.apidocs");
+            }
+        }
         var generatorWarnings = result.Warnings ?? Array.Empty<string>();
         var combinedWarnings = filteredPreflightWarnings
+            .Concat(powerShellExampleValidation?.Warnings ?? Array.Empty<string>())
             .Concat(generatorWarnings)
             .Where(static w => !string.IsNullOrWhiteSpace(w))
             .ToArray();
@@ -214,7 +303,8 @@ private static int HandleApiDocs(string[] subArgs, bool outputJson, WebConsoleLo
 
         if (outputJson)
         {
-            if (filteredWarnings.Length != generatorWarnings.Length)
+            if (filteredWarnings.Length != generatorWarnings.Length ||
+                !string.Equals(powerShellExampleValidationPath, result.PowerShellExampleValidationPath, StringComparison.Ordinal))
             {
                 result = new WebApiDocsResult
                 {
@@ -224,6 +314,8 @@ private static int HandleApiDocs(string[] subArgs, bool outputJson, WebConsoleLo
                     TypesPath = result.TypesPath,
                     CoveragePath = result.CoveragePath,
                     XrefPath = result.XrefPath,
+                    PowerShellExampleValidationPath = powerShellExampleValidationPath,
+                    PowerShellExampleMediaManifestPath = result.PowerShellExampleMediaManifestPath,
                     TypeCount = result.TypeCount,
                     UsedReflectionFallback = result.UsedReflectionFallback,
                     Warnings = filteredWarnings
@@ -244,6 +336,10 @@ private static int HandleApiDocs(string[] subArgs, bool outputJson, WebConsoleLo
         logger.Success($"API docs generated: {result.OutputPath}");
         logger.Info($"Types: {result.TypeCount}");
         logger.Info($"Index: {result.IndexPath}");
+        if (!string.IsNullOrWhiteSpace(powerShellExampleValidationPath))
+            logger.Info($"PowerShell example validation: {powerShellExampleValidationPath}");
+        if (!string.IsNullOrWhiteSpace(result.PowerShellExampleMediaManifestPath))
+            logger.Info($"PowerShell example media manifest: {result.PowerShellExampleMediaManifestPath}");
         return 0;
     }
 
diff --git a/PowerForge.Web.Cli/WebCliHelpers.cs b/PowerForge.Web.Cli/WebCliHelpers.cs
index 00960dca..0768849d 100644
--- a/PowerForge.Web.Cli/WebCliHelpers.cs
+++ b/PowerForge.Web.Cli/WebCliHelpers.cs
@@ -80,6 +80,9 @@ internal static void PrintUsage()
         Console.WriteLine("                     [--coverage-report <file>] [--no-coverage-report]");
         Console.WriteLine("                     [--xref-map <file>] [--no-xref-map] [--no-member-xref] [--member-xref-kinds <list>] [--member-xref-max-per-type <n>]");
         Console.WriteLine("                     [--ps-examples <file|dir>] [--no-ps-fallback-examples] [--ps-fallback-limit <n>]");
+        Console.WriteLine("                     [--validate-ps-examples] [--ps-example-validation-timeout <n>] [--fail-on-ps-example-validation]");
+        Console.WriteLine("                     [--execute-ps-examples] [--ps-example-execution-timeout <n>] [--fail-on-ps-example-execution]");
+        Console.WriteLine("                     [--git-freshness] [--git-freshness-new-days <n>] [--git-freshness-updated-days <n>]");
         Console.WriteLine("                     [--fail-on-warnings] [--suppress-warning <pattern>]");
         Console.WriteLine("                     [--source-root <dir>] [--source-path-prefix <prefix>] [--source-url <pattern>] [--source-map <prefix[(:strip)]=pattern>] [--documented-only]");
         Console.WriteLine("                     (source-url/source-map tokens: {path} {line} {root} {pathNoRoot} {pathNoPrefix})");
diff --git a/PowerForge.Web.Cli/WebPipelineRunner.Tasks.Content.cs b/PowerForge.Web.Cli/WebPipelineRunner.Tasks.Content.cs
index ec3fca23..be63f776 100644
--- a/PowerForge.Web.Cli/WebPipelineRunner.Tasks.Content.cs
+++ b/PowerForge.Web.Cli/WebPipelineRunner.Tasks.Content.cs
@@ -39,6 +39,7 @@ private static void ExecuteApiDocs(
         var assembly = ResolvePath(baseDir, GetString(step, "assembly"));
         var title = GetString(step, "title");
         var baseUrl = GetString(step, "baseUrl") ?? GetString(step, "base-url") ?? "/api";
+        var languageCode = GetString(step, "language") ?? GetString(step, "languageCode") ?? GetString(step, "language-code");
         var format = GetString(step, "format");
         var css = GetString(step, "css") ?? GetString(step, "cssHref") ?? GetString(step, "css-href");
         var criticalCssPath = ResolvePath(baseDir, GetString(step, "criticalCssPath") ?? GetString(step, "critical-css-path") ?? GetString(step, "criticalCss") ?? GetString(step, "critical-css"));
@@ -75,6 +76,22 @@ private static void ExecuteApiDocs(
         var powerShellExamplesPath = ResolvePath(baseDir, GetString(step, "psExamplesPath") ?? GetString(step, "ps-examples-path") ?? GetString(step, "powerShellExamplesPath") ?? GetString(step, "powershell-examples-path"));
         var generatePowerShellFallbackExamples = GetBool(step, "generatePowerShellFallbackExamples") ?? GetBool(step, "generate-powershell-fallback-examples") ?? true;
         var powerShellFallbackExampleLimit = GetInt(step, "powerShellFallbackExampleLimit") ?? GetInt(step, "powershell-fallback-example-limit") ?? 2;
+        var validatePowerShellExamples = GetBool(step, "validatePowerShellExamples") ?? GetBool(step, "validate-powershell-examples") ?? false;
+        var powerShellExampleValidationReportPath = ResolvePath(baseDir, GetString(step, "powerShellExampleValidationReport") ?? GetString(step, "powershell-example-validation-report") ?? GetString(step, "powerShellExampleValidationReportPath") ?? GetString(step, "powershell-example-validation-report-path"));
+        var powerShellExampleValidationTimeoutSeconds = GetInt(step, "powerShellExampleValidationTimeoutSeconds") ?? GetInt(step, "powershell-example-validation-timeout-seconds") ?? 60;
+        var failOnPowerShellExampleValidation = GetBool(step, "failOnPowerShellExampleValidation") ?? GetBool(step, "fail-on-powershell-example-validation") ?? false;
+        var executePowerShellExamples = GetBool(step, "executePowerShellExamples") ?? GetBool(step, "execute-powershell-examples") ?? false;
+        var powerShellExampleExecutionTimeoutSeconds = GetInt(step, "powerShellExampleExecutionTimeoutSeconds") ?? GetInt(step, "powershell-example-execution-timeout-seconds") ?? 60;
+        var failOnPowerShellExampleExecution = GetBool(step, "failOnPowerShellExampleExecution") ?? GetBool(step, "fail-on-powershell-example-execution") ?? false;
+        if (failOnPowerShellExampleValidation)
+            validatePowerShellExamples = true;
+        if (executePowerShellExamples || failOnPowerShellExampleExecution)
+            executePowerShellExamples = true;
+        if (executePowerShellExamples)
+            validatePowerShellExamples = true;
+        var generateGitFreshness = GetBool(step, "generateGitFreshness") ?? GetBool(step, "generate-git-freshness") ?? false;
+        var gitFreshnessNewDays = GetInt(step, "gitFreshnessNewDays") ?? GetInt(step, "git-freshness-new-days") ?? 14;
+        var gitFreshnessUpdatedDays = GetInt(step, "gitFreshnessUpdatedDays") ?? GetInt(step, "git-freshness-updated-days") ?? 90;
         var sourceUrlMappings = GetApiDocsSourceUrlMappings(
             step,
             "sourceUrlMappings",
@@ -109,6 +126,7 @@ private static void ExecuteApiDocs(
         var socialCardPath = GetString(step, "socialCardPath") ?? GetString(step, "social-card-path");
         var socialCardWidth = GetInt(step, "socialCardWidth") ?? GetInt(step, "social-card-width");
         var socialCardHeight = GetInt(step, "socialCardHeight") ?? GetInt(step, "social-card-height");
+        var siteBaseUrl = GetString(step, "siteBaseUrl") ?? GetString(step, "site-base-url");
         var brandUrl = GetString(step, "brandUrl") ?? GetString(step, "brand-url");
         var brandIcon = GetString(step, "brandIcon") ?? GetString(step, "brand-icon");
         var suppressWarnings = GetArrayOfStrings(step, "suppressWarnings");
@@ -260,6 +278,7 @@ private static void ExecuteApiDocs(
                     : generatedCardsPath.TrimEnd('/') + "/api";
                 socialCardWidth ??= spec.Social?.GeneratedCardWidth;
                 socialCardHeight ??= spec.Social?.GeneratedCardHeight;
+                siteBaseUrl ??= spec.BaseUrl;
             }
             catch
             {
@@ -278,6 +297,8 @@ private static void ExecuteApiDocs(
             OutputPath = outPath,
             Title = string.IsNullOrWhiteSpace(title) ? "API Reference" : title,
             BaseUrl = baseUrl,
+            SiteBaseUrl = siteBaseUrl,
+            LanguageCode = languageCode,
             Format = format,
             CssHref = css,
             CriticalCssHtml = injectedCriticalCssHtml,
@@ -312,6 +333,9 @@ private static void ExecuteApiDocs(
             GeneratePowerShellFallbackExamples = generatePowerShellFallbackExamples,
             PowerShellExamplesPath = powerShellExamplesPath,
             PowerShellFallbackExampleLimitPerCommand = powerShellFallbackExampleLimit > 0 ? powerShellFallbackExampleLimit : 2,
+            GenerateGitFreshness = generateGitFreshness,
+            GitFreshnessNewDays = gitFreshnessNewDays,
+            GitFreshnessUpdatedDays = gitFreshnessUpdatedDays,
             IncludeUndocumentedTypes = includeUndocumented,
             NavJsonPath = nav,
             // Default to root context for profile selection to avoid accidental "API header has different nav"
@@ -388,11 +412,69 @@ private static void ExecuteApiDocs(
         if (memberXrefKindList.Count > 0)
             options.MemberXrefKinds.AddRange(memberXrefKindList);
 
+        WebApiDocsPowerShellExampleValidationResult? powerShellExampleValidation = null;
+        string? powerShellExampleValidationPath = null;
+        if (apiType == ApiDocsType.PowerShell && validatePowerShellExamples)
+        {
+            powerShellExampleValidation = WebApiDocsGenerator.ValidatePowerShellExamples(new WebApiDocsPowerShellExampleValidationOptions
+            {
+                HelpPath = help ?? string.Empty,
+                PowerShellModuleManifestPath = powerShellManifestPath,
+                PowerShellExamplesPath = powerShellExamplesPath,
+                TimeoutSeconds = powerShellExampleValidationTimeoutSeconds,
+                ExecuteMatchedExamples = executePowerShellExamples,
+                ExecutionTimeoutSeconds = powerShellExampleExecutionTimeoutSeconds
+            });
+            powerShellExampleValidationPath = WebApiDocsGenerator.WritePowerShellExampleValidationReport(
+                outPath!,
+                powerShellExampleValidationReportPath,
+                powerShellExampleValidation,
+                new WebApiDocsPowerShellExampleValidationOptions
+                {
+                    HelpPath = help ?? string.Empty,
+                    PowerShellModuleManifestPath = powerShellManifestPath,
+                    PowerShellExamplesPath = powerShellExamplesPath,
+                    TimeoutSeconds = powerShellExampleValidationTimeoutSeconds,
+                    PreferPwsh = true,
+                    ExecuteMatchedExamples = executePowerShellExamples,
+                    ExecutionTimeoutSeconds = powerShellExampleExecutionTimeoutSeconds
+                });
+            options.PowerShellExampleValidationResult = powerShellExampleValidation;
+        }
+
         var res = WebApiDocsGenerator.Generate(options);
+        if (!string.IsNullOrWhiteSpace(powerShellExampleValidationPath))
+            res.PowerShellExampleValidationPath = powerShellExampleValidationPath;
+
+        if (apiType == ApiDocsType.PowerShell && validatePowerShellExamples && powerShellExampleValidation is not null)
+        {
+            if (failOnPowerShellExampleValidation &&
+                (!powerShellExampleValidation.ValidationSucceeded || powerShellExampleValidation.InvalidSyntaxFileCount > 0))
+            {
+                var reason = !powerShellExampleValidation.ValidationSucceeded
+                    ? "PowerShell example validation did not complete successfully."
+                    : $"PowerShell example validation found {powerShellExampleValidation.InvalidSyntaxFileCount} invalid script(s).";
+                throw new InvalidOperationException($"{reason} Report: {powerShellExampleValidationPath}");
+            }
+            if (failOnPowerShellExampleExecution &&
+                (!powerShellExampleValidation.ExecutionCompleted || powerShellExampleValidation.FailedExecutionFileCount > 0))
+            {
+                var reason = !powerShellExampleValidation.ExecutionCompleted
+                    ? "PowerShell example execution did not complete successfully."
+                    : $"PowerShell example execution failed for {powerShellExampleValidation.FailedExecutionFileCount} script(s).";
+                throw new InvalidOperationException($"{reason} Report: {powerShellExampleValidationPath}");
+            }
+        }
         var note = res.UsedReflectionFallback ? " (reflection)" : string.Empty;
         var filteredWarnings = suppressWarnings is { Length: > 0 }
-            ? WebVerifyPolicy.FilterWarnings(res.Warnings, suppressWarnings)
-            : res.Warnings;
+            ? WebVerifyPolicy.FilterWarnings(
+                res.Warnings
+                    .Concat(powerShellExampleValidation?.Warnings ?? Array.Empty<string>())
+                    .ToArray(),
+                suppressWarnings)
+            : res.Warnings
+                .Concat(powerShellExampleValidation?.Warnings ?? Array.Empty<string>())
+                .ToArray();
 
         if (filteredWarnings.Length > 0)
         {
@@ -456,6 +538,10 @@ private static void ExecuteApiDocs(
         }
 
         stepResult.Success = true;
+        if (!string.IsNullOrWhiteSpace(powerShellExampleValidationPath))
+            note += $" (ps-example-validation: {Path.GetFileName(powerShellExampleValidationPath)})";
+        if (!string.IsNullOrWhiteSpace(res.PowerShellExampleMediaManifestPath))
+            note += $" (ps-example-media: {Path.GetFileName(res.PowerShellExampleMediaManifestPath)})";
         stepResult.Message = $"API docs {res.TypeCount} types{note}";
     }
 
@@ -568,6 +654,29 @@ internal static string[] ValidateApiDocsPreflight(
             warnings.Add("[PFWEB.APIDOCS.SOURCE] API docs source preflight: sourceUrl does not include a path token ({path}, {pathNoRoot}, or {pathNoPrefix}).");
         }
 
+        if (hasSourceRoot &&
+            hasSourceUrl &&
+            !hasMappings &&
+            sourceUrl!.IndexOf("{pathNoRoot}", StringComparison.OrdinalIgnoreCase) < 0 &&
+            sourceUrl!.IndexOf("{root}", StringComparison.OrdinalIgnoreCase) < 0)
+        {
+            var fullSourceRoot = Path.GetFullPath(sourceRoot!);
+            if (Directory.Exists(fullSourceRoot) &&
+                TryExtractGitHubRepoName(sourceUrl, out var repoName) &&
+                !string.IsNullOrWhiteSpace(repoName))
+            {
+                var sourceRootName = new DirectoryInfo(fullSourceRoot).Name;
+                var nestedRepoRoot = Path.Combine(fullSourceRoot, repoName);
+                if (!string.Equals(sourceRootName, repoName, StringComparison.OrdinalIgnoreCase) &&
+                    Directory.Exists(nestedRepoRoot))
+                {
+                    warnings.Add(
+                        $"[PFWEB.APIDOCS.SOURCE] API docs source preflight: sourceRoot '{fullSourceRoot}' looks one level above repo '{repoName}'. " +
+                        "Use the repo folder as sourceRoot, or switch sourceUrl to {root}/sourceUrlMappings for mixed-repo layouts.");
+                }
+            }
+        }
+
         if (hasMappings)
         {
             var seenPrefixes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
@@ -633,6 +742,31 @@ private static bool ContainsAnyPathToken(string value)
                value.IndexOf("{pathNoPrefix}", StringComparison.OrdinalIgnoreCase) >= 0;
     }
 
+    private static bool TryExtractGitHubRepoName(string pattern, out string repoName)
+    {
+        repoName = string.Empty;
+        if (string.IsNullOrWhiteSpace(pattern))
+            return false;
+
+        var candidate = pattern
+            .Replace("{path}", "sample/path.cs", StringComparison.OrdinalIgnoreCase)
+            .Replace("{pathNoRoot}", "sample/path.cs", StringComparison.OrdinalIgnoreCase)
+            .Replace("{pathNoPrefix}", "sample/path.cs", StringComparison.OrdinalIgnoreCase)
+            .Replace("{root}", "SampleRepo", StringComparison.OrdinalIgnoreCase)
+            .Replace("{line}", "1", StringComparison.OrdinalIgnoreCase);
+        if (!Uri.TryCreate(candidate, UriKind.Absolute, out var uri))
+            return false;
+        if (!string.Equals(uri.Host, "github.com", StringComparison.OrdinalIgnoreCase))
+            return false;
+
+        var segments = uri.AbsolutePath.Split('/', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (segments.Length < 2)
+            return false;
+
+        repoName = segments[1];
+        return !string.IsNullOrWhiteSpace(repoName);
+    }
+
     private static List<ApiDocsCoverageThreshold> GetApiDocsCoverageThresholds(JsonElement step)
     {
         var thresholds = new List<ApiDocsCoverageThreshold>();
@@ -644,6 +778,10 @@ private static List<ApiDocsCoverageThreshold> GetApiDocsCoverageThresholds(JsonE
         AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellSummaryPercent", "min-powershell-summary-percent", "powershell.summary.percent", "PowerShell command summary coverage", powerShellCommandMetric: true);
         AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellRemarksPercent", "min-powershell-remarks-percent", "powershell.remarks.percent", "PowerShell command remarks coverage", powerShellCommandMetric: true);
         AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellCodeExamplesPercent", "min-powershell-code-examples-percent", "powershell.codeExamples.percent", "PowerShell command code examples coverage", powerShellCommandMetric: true);
+        AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellAuthoredHelpCodeExamplesPercent", "min-powershell-authored-help-code-examples-percent", "powershell.authoredHelpCodeExamples.percent", "PowerShell authored-help code examples coverage", powerShellCommandMetric: true);
+        AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellImportedScriptCodeExamplesPercent", "min-powershell-imported-script-code-examples-percent", "powershell.importedScriptCodeExamples.percent", "PowerShell imported-script code examples coverage", powerShellCommandMetric: true);
+        AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellImportedScriptPlaybackMediaPercent", "min-powershell-imported-script-playback-media-percent", "powershell.importedScriptPlaybackMedia.percent", "PowerShell imported-script playback media coverage", powerShellCommandMetric: true);
+        AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellImportedScriptPlaybackMediaWithPosterPercent", "min-powershell-imported-script-playback-media-with-poster-percent", "powershell.importedScriptPlaybackMediaWithPoster.percent", "PowerShell imported-script playback media poster coverage", powerShellCommandMetric: true);
         AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellParameterSummaryPercent", "min-powershell-parameter-summary-percent", "powershell.parameters.percent", "PowerShell parameter summary coverage", powerShellCommandMetric: true);
         AddCoverageMinPercentThreshold(thresholds, step, "minTypeSourcePathPercent", "min-type-source-path-percent", "source.types.path.percent", "Type source path coverage");
         AddCoverageMinPercentThreshold(thresholds, step, "minTypeSourceUrlPercent", "min-type-source-url-percent", "source.types.url.percent", "Type source URL coverage");
@@ -651,6 +789,12 @@ private static List<ApiDocsCoverageThreshold> GetApiDocsCoverageThresholds(JsonE
         AddCoverageMinPercentThreshold(thresholds, step, "minMemberSourceUrlPercent", "min-member-source-url-percent", "source.members.url.percent", "Member source URL coverage");
         AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellSourcePathPercent", "min-powershell-source-path-percent", "source.powershell.path.percent", "PowerShell command source path coverage", powerShellCommandMetric: true);
         AddCoverageMinPercentThreshold(thresholds, step, "minPowerShellSourceUrlPercent", "min-powershell-source-url-percent", "source.powershell.url.percent", "PowerShell command source URL coverage", powerShellCommandMetric: true);
+        AddCoverageMaxThreshold(thresholds, step, "maxPowerShellGeneratedFallbackOnlyExamplePercent", "max-powershell-generated-fallback-only-example-percent", "powershell.generatedFallbackOnlyExamples.percent", "PowerShell generated-only fallback example percent", powerShellCommandMetric: true, formatAsPercent: true);
+        AddCoverageMaxThreshold(thresholds, step, "maxPowerShellGeneratedFallbackOnlyExampleCount", "max-powershell-generated-fallback-only-example-count", "powershell.generatedFallbackOnlyExamples.covered", "PowerShell generated-only fallback example count", powerShellCommandMetric: true);
+        AddCoverageMaxThreshold(thresholds, step, "maxPowerShellImportedScriptPlaybackMediaWithoutPosterCount", "max-powershell-imported-script-playback-media-without-poster-count", "powershell.importedScriptPlaybackMediaWithoutPoster.covered", "PowerShell imported-script playback media without poster count", powerShellCommandMetric: true);
+        AddCoverageMaxThreshold(thresholds, step, "maxPowerShellImportedScriptPlaybackMediaUnsupportedSidecarCount", "max-powershell-imported-script-playback-media-unsupported-sidecar-count", "powershell.importedScriptPlaybackMediaUnsupportedSidecars.covered", "PowerShell imported-script playback media with unsupported sidecars count", powerShellCommandMetric: true);
+        AddCoverageMaxThreshold(thresholds, step, "maxPowerShellImportedScriptPlaybackMediaOversizedAssetCount", "max-powershell-imported-script-playback-media-oversized-asset-count", "powershell.importedScriptPlaybackMediaOversizedAssets.covered", "PowerShell imported-script playback media with oversized assets count", powerShellCommandMetric: true);
+        AddCoverageMaxThreshold(thresholds, step, "maxPowerShellImportedScriptPlaybackMediaStaleAssetCount", "max-powershell-imported-script-playback-media-stale-asset-count", "powershell.importedScriptPlaybackMediaStaleAssets.covered", "PowerShell imported-script playback media with stale assets count", powerShellCommandMetric: true);
         AddCoverageMaxThreshold(thresholds, step, "maxTypeSourceInvalidUrlCount", "max-type-source-invalid-url-count", "source.types.invalidUrl.count", "Type source invalid URL count");
         AddCoverageMaxThreshold(thresholds, step, "maxMemberSourceInvalidUrlCount", "max-member-source-invalid-url-count", "source.members.invalidUrl.count", "Member source invalid URL count");
         AddCoverageMaxThreshold(thresholds, step, "maxPowerShellSourceInvalidUrlCount", "max-powershell-source-invalid-url-count", "source.powershell.invalidUrl.count", "PowerShell command source invalid URL count", powerShellCommandMetric: true);
@@ -697,7 +841,8 @@ private static void AddCoverageMaxThreshold(
         string aliasName,
         string metricPath,
         string label,
-        bool powerShellCommandMetric = false)
+        bool powerShellCommandMetric = false,
+        bool formatAsPercent = false)
     {
         var value = GetDouble(step, primaryName) ?? GetDouble(step, aliasName);
         if (!value.HasValue)
@@ -705,6 +850,8 @@ private static void AddCoverageMaxThreshold(
 
         if (value.Value < 0)
             throw new InvalidOperationException($"apidocs coverage threshold '{primaryName}' must be greater than or equal to 0.");
+        if (formatAsPercent && value.Value > 100)
+            throw new InvalidOperationException($"apidocs coverage threshold '{primaryName}' must be less than or equal to 100.");
 
         thresholds.Add(new ApiDocsCoverageThreshold
         {
@@ -712,7 +859,7 @@ private static void AddCoverageMaxThreshold(
             MetricPath = metricPath,
             TargetValue = value.Value,
             Comparison = ApiDocsCoverageComparison.Maximum,
-            FormatAsPercent = false,
+            FormatAsPercent = formatAsPercent,
             SkipWhenNoPowerShellCommands = powerShellCommandMetric
         });
     }
diff --git a/PowerForge.Web/Assets/ApiDocs/fallback.css b/PowerForge.Web/Assets/ApiDocs/fallback.css
index 7bf20a30..31ef77f3 100644
--- a/PowerForge.Web/Assets/ApiDocs/fallback.css
+++ b/PowerForge.Web/Assets/ApiDocs/fallback.css
@@ -102,6 +102,10 @@ body.pf-api-docs .type-icon-glyph,body.pf-api-docs .chip-icon-glyph{display:bloc
 .type-header{margin-bottom:10px}
 .type-title-row{display:flex;align-items:center;gap:10px}
 .type-badge{display:inline-flex;align-items:center;justify-content:center;background:#111827;border:1px solid rgba(148,163,184,.2);border-radius:999px;padding:4px 10px;font-size:.7rem;line-height:1;text-transform:uppercase;letter-spacing:.04em;color:#cbd5f5}
+.freshness-badge{display:inline-flex;align-items:center;justify-content:center;min-height:1.35rem;padding:2px 8px;border-radius:999px;border:1px solid rgba(148,163,184,.24);background:rgba(15,23,42,.45);color:#cbd5f5;font-size:.68rem;line-height:1;text-transform:uppercase;letter-spacing:.06em;font-weight:700;white-space:nowrap}
+.freshness-badge.new{border-color:rgba(34,197,94,.42);background:rgba(20,83,45,.22);color:#86efac}
+.freshness-badge.updated{border-color:rgba(56,189,248,.42);background:rgba(8,47,73,.28);color:#7dd3fc}
+.type-freshness-badge{margin-right:.15rem}
 .type-actions{margin-top:10px}
 .type-source-action{display:inline-flex;align-items:center;padding:6px 10px;border-radius:999px;border:1px solid rgba(167,139,250,.5);background:rgba(167,139,250,.14);color:#ddd6fe;font-size:.75rem;font-weight:600}
 .type-source-action:hover{border-color:#a78bfa;background:rgba(167,139,250,.22);color:#f5f3ff}
@@ -158,7 +162,22 @@ body.pf-api-docs .type-icon-glyph,body.pf-api-docs .chip-icon-glyph{display:bloc
 .member-source a,.type-meta-source a{color:#a78bfa}
 .member-summary{margin:0;color:#e2e8f0}
 .type-parameters,.type-examples,.type-see-also{margin:12px 0}
+.example-origin{margin:.35rem 0 .45rem}
+.example-origin-badge{font-size:.68rem;letter-spacing:.03em;text-transform:none}
+.example-origin-badge.example-origin-authored{border-color:rgba(34,197,94,.42);background:rgba(20,83,45,.22);color:#86efac}
+.example-origin-badge.example-origin-imported{border-color:rgba(56,189,248,.42);background:rgba(8,47,73,.28);color:#7dd3fc}
+.example-origin-badge.example-origin-generated{border-color:rgba(245,158,11,.42);background:rgba(120,53,15,.26);color:#fcd34d}
+.example-origin-badge.example-origin-other{border-color:rgba(148,163,184,.32);background:rgba(30,41,59,.5);color:#e2e8f0}
 .example-title{margin:8px 0 2px;font-size:1rem;color:#e6e9f3}
+.example-media{margin:12px 0;display:grid;gap:.6rem}
+.example-media-frame{background:#0f172a;border:1px solid rgba(148,163,184,.18);border-radius:12px;padding:.75rem;overflow:hidden}
+.example-media-frame img,.example-media-frame video{display:block;max-width:100%;height:auto;border-radius:10px}
+.example-media-frame video{width:100%;background:#020617}
+.example-media-frame-terminal{display:grid;gap:.75rem}
+.example-media-link{display:inline-flex;align-items:center;justify-content:center;min-height:2.5rem;padding:.7rem 1rem;border-radius:10px;background:#111827;border:1px solid rgba(148,163,184,.24);color:#e2e8f0;text-decoration:none;font-weight:600}
+.example-media-link:hover{border-color:rgba(167,139,250,.44);color:#fff}
+.example-media-caption{margin:0;color:#94a3b8;font-size:.92rem;line-height:1.6}
+.example-media-meta{margin:-.1rem 0 0;color:#64748b;font-size:.8rem;line-height:1.5}
 .typeparam-list,.exception-list,.see-also-list{list-style:none;padding:0;margin:0;display:grid;gap:6px}
 .typeparam-list dt{font-weight:600}
 .typeparam-list dd{margin:0;color:#94a3b8}
@@ -215,11 +234,16 @@ body.pf-api-docs .all-namespaces .namespace-group h3{display:flex;align-items:ba
 body.pf-api-docs .all-namespaces .namespace-group h3 .count{font-size:.9em;color:#94a3b8;font-weight:600}
 body.pf-api-docs .type-chips{gap:.5rem .55rem;align-items:flex-start}
 body.pf-api-docs .type-chip{display:inline-grid;grid-template-columns:auto minmax(0,1fr);align-items:center;gap:.45rem;min-height:1.9rem;padding:.32rem .72rem;line-height:1.2;vertical-align:middle;text-decoration:none}
+body.pf-api-docs .type-chip-freshness{font-size:.6rem;min-height:1.15rem;padding:1px 7px}
 body.pf-api-docs .chip-icon,
 body.pf-api-docs .type-icon{display:inline-flex;align-items:center;justify-content:center;line-height:1}
 body.pf-api-docs .chip-icon{width:1.1rem;height:1.1rem;font-size:.62rem;font-family:var(--pf-font-mono,ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace);font-weight:700}
 body.pf-api-docs .chip-name{display:block;line-height:1.2;font-weight:600;text-decoration:none}
 body.pf-api-docs .type-badge{display:inline-flex;align-items:center;justify-content:center;min-height:1.45rem;line-height:1}
+body.pf-api-docs .quick-card-header .quick-card-freshness{justify-self:start;margin-left:auto}
+body.pf-api-docs .type-item{justify-content:flex-start}
+body.pf-api-docs .type-item .type-name{min-width:0;flex:1 1 auto}
+body.pf-api-docs .type-list-freshness{margin-left:auto;font-size:.58rem;min-height:1.05rem;padding:1px 6px}
 body.pf-api-docs .quick-card-header strong{line-height:1.25}
 body.pf-api-docs .api-overview-grid{display:grid;grid-template-columns:minmax(0,1fr) minmax(250px,300px);gap:1.5rem;align-items:start}
 body.pf-api-docs .api-overview-main{min-width:0}
@@ -307,10 +331,19 @@ body.pf-api-docs .type-detail-rail .type-toc ul::-webkit-scrollbar-thumb:hover{b
 [data-theme="light"] body.pf-api-docs .inheritance-current,
 [data-theme="light"] body.pf-api-docs .member-summary,
 [data-theme="light"] body.pf-api-docs .example-title,
+[data-theme="light"] body.pf-api-docs .example-media-link,
 [data-theme="light"] body.pf-api-docs .type-toc a,
 [data-theme="light"] body.pf-api-docs .pf-combobox-option,
 [data-theme="light"] body.pf-api-docs .type-item,
 [data-theme="light"] body.pf-api-docs .current{color:var(--pf-ink,#0f172a)}
+[data-theme="light"] body.pf-api-docs .example-media-frame{background:var(--pf-card-bg,#ffffff);border-color:var(--pf-border,rgba(148,163,184,.45))}
+[data-theme="light"] body.pf-api-docs .example-media-link{background:#f8fafc;border-color:rgba(148,163,184,.45)}
+[data-theme="light"] body.pf-api-docs .example-media-caption{color:#475569}
+[data-theme="light"] body.pf-api-docs .example-media-meta{color:#64748b}
+[data-theme="light"] body.pf-api-docs .example-origin-badge.example-origin-authored{background:rgba(34,197,94,.12);border-color:rgba(34,197,94,.35);color:#166534}
+[data-theme="light"] body.pf-api-docs .example-origin-badge.example-origin-imported{background:rgba(56,189,248,.12);border-color:rgba(56,189,248,.34);color:#0f766e}
+[data-theme="light"] body.pf-api-docs .example-origin-badge.example-origin-generated{background:rgba(245,158,11,.12);border-color:rgba(245,158,11,.34);color:#92400e}
+[data-theme="light"] body.pf-api-docs .example-origin-badge.example-origin-other{background:#f8fafc;border-color:rgba(148,163,184,.4);color:#334155}
 [data-theme="light"] body.pf-api-docs .member-card pre code{color:var(--pf-ink,#0f172a)}
 [data-theme="light"] body.pf-api-docs .member-card pre{scrollbar-color:rgba(100,116,139,.5) rgba(226,232,240,.92)}
 [data-theme="light"] body.pf-api-docs .member-card pre::-webkit-scrollbar-track{background:rgba(226,232,240,.92)}
diff --git a/PowerForge.Web/Models/WebApiDocsPowerShellExampleValidationResult.cs b/PowerForge.Web/Models/WebApiDocsPowerShellExampleValidationResult.cs
new file mode 100644
index 00000000..b4165c36
--- /dev/null
+++ b/PowerForge.Web/Models/WebApiDocsPowerShellExampleValidationResult.cs
@@ -0,0 +1,96 @@
+namespace PowerForge.Web;
+
+/// <summary>Options for validating imported PowerShell example scripts used by API docs.</summary>
+public sealed class WebApiDocsPowerShellExampleValidationOptions
+{
+    /// <summary>Path to PowerShell help XML or folder.</summary>
+    public string HelpPath { get; set; } = string.Empty;
+    /// <summary>Optional path to a PowerShell module manifest used to discover example roots.</summary>
+    public string? PowerShellModuleManifestPath { get; set; }
+    /// <summary>Optional explicit path to a PowerShell examples folder or script file.</summary>
+    public string? PowerShellExamplesPath { get; set; }
+    /// <summary>Maximum allowed validation time in seconds.</summary>
+    public int TimeoutSeconds { get; set; } = 60;
+    /// <summary>When true, prefer pwsh over Windows PowerShell when both are available.</summary>
+    public bool PreferPwsh { get; set; } = true;
+    /// <summary>When true, execute matched example scripts after syntax validation.</summary>
+    public bool ExecuteMatchedExamples { get; set; }
+    /// <summary>Maximum allowed execution time in seconds for each matched example script.</summary>
+    public int ExecutionTimeoutSeconds { get; set; } = 60;
+}
+
+/// <summary>Validation result for PowerShell example scripts.</summary>
+public sealed class WebApiDocsPowerShellExampleValidationResult
+{
+    /// <summary>Resolved PowerShell help XML file used to infer documented commands.</summary>
+    public string? HelpPath { get; set; }
+    /// <summary>Resolved module manifest path, when one was found.</summary>
+    public string? ManifestPath { get; set; }
+    /// <summary>Executable used to perform syntax validation, when validation ran.</summary>
+    public string? Executable { get; set; }
+    /// <summary>True when the PowerShell parser process completed successfully.</summary>
+    public bool ValidationSucceeded { get; set; }
+    /// <summary>Number of documented commands inferred from help metadata.</summary>
+    public int KnownCommandCount { get; set; }
+    /// <summary>Known documented command names discovered from the help source.</summary>
+    public string[] KnownCommands { get; set; } = Array.Empty<string>();
+    /// <summary>Number of example files discovered for validation.</summary>
+    public int FileCount { get; set; }
+    /// <summary>Number of example files that parsed without syntax errors.</summary>
+    public int ValidSyntaxFileCount { get; set; }
+    /// <summary>Number of example files that failed syntax validation.</summary>
+    public int InvalidSyntaxFileCount { get; set; }
+    /// <summary>Number of example files that reference at least one documented command.</summary>
+    public int MatchedFileCount { get; set; }
+    /// <summary>Number of example files that do not reference any documented commands.</summary>
+    public int UnmatchedFileCount { get; set; }
+    /// <summary>Total parse error count across all validated files.</summary>
+    public int ParseErrorCount { get; set; }
+    /// <summary>True when matched example execution was requested.</summary>
+    public bool ExecutionRequested { get; set; }
+    /// <summary>True when the execution phase completed without runner-level failures.</summary>
+    public bool ExecutionCompleted { get; set; }
+    /// <summary>Executable used to run matched examples, when execution was requested.</summary>
+    public string? ExecutionExecutable { get; set; }
+    /// <summary>Number of example files that were executed.</summary>
+    public int ExecutedFileCount { get; set; }
+    /// <summary>Number of executed example files that exited successfully.</summary>
+    public int PassedExecutionFileCount { get; set; }
+    /// <summary>Number of executed example files that exited with failure.</summary>
+    public int FailedExecutionFileCount { get; set; }
+    /// <summary>Per-file validation results.</summary>
+    public WebApiDocsPowerShellExampleFileValidationResult[] Files { get; set; } = Array.Empty<WebApiDocsPowerShellExampleFileValidationResult>();
+    /// <summary>Warnings emitted while resolving or validating example files.</summary>
+    public string[] Warnings { get; set; } = Array.Empty<string>();
+}
+
+/// <summary>Validation result for a single PowerShell example script.</summary>
+public sealed class WebApiDocsPowerShellExampleFileValidationResult
+{
+    /// <summary>Full path to the example file.</summary>
+    public string FilePath { get; set; } = string.Empty;
+    /// <summary>True when the script parsed without syntax errors.</summary>
+    public bool ValidSyntax { get; set; }
+    /// <summary>Number of parse errors returned by the PowerShell parser.</summary>
+    public int ParseErrorCount { get; set; }
+    /// <summary>Short parse error messages returned by the PowerShell parser.</summary>
+    public string[] ParseErrors { get; set; } = Array.Empty<string>();
+    /// <summary>Command tokens discovered in the example file.</summary>
+    public string[] Commands { get; set; } = Array.Empty<string>();
+    /// <summary>Documented command names matched by this example file.</summary>
+    public string[] MatchedCommands { get; set; } = Array.Empty<string>();
+    /// <summary>True when the execution phase attempted to run this file.</summary>
+    public bool ExecutionAttempted { get; set; }
+    /// <summary>True when the executed example exited with code 0; null when not executed.</summary>
+    public bool? ExecutionSucceeded { get; set; }
+    /// <summary>Exit code returned by the example process, when executed.</summary>
+    public int? ExecutionExitCode { get; set; }
+    /// <summary>Captured standard output from execution, when available.</summary>
+    public string? ExecutionStdOut { get; set; }
+    /// <summary>Captured standard error from execution, when available.</summary>
+    public string? ExecutionStdErr { get; set; }
+    /// <summary>Reason this file was skipped during execution, when execution was requested but not attempted.</summary>
+    public string? ExecutionSkippedReason { get; set; }
+    /// <summary>Path to the written execution transcript artifact, when report writing emitted one.</summary>
+    public string? ExecutionArtifactPath { get; set; }
+}
diff --git a/PowerForge.Web/Models/WebLlmsResult.cs b/PowerForge.Web/Models/WebLlmsResult.cs
index e514fdcc..23206168 100644
--- a/PowerForge.Web/Models/WebLlmsResult.cs
+++ b/PowerForge.Web/Models/WebLlmsResult.cs
@@ -55,6 +55,10 @@ public sealed class WebApiDocsResult
     public string? CoveragePath { get; set; }
     /// <summary>Path to the xref map JSON file, when generated.</summary>
     public string? XrefPath { get; set; }
+    /// <summary>Path to the PowerShell example validation report JSON file, when generated.</summary>
+    public string? PowerShellExampleValidationPath { get; set; }
+    /// <summary>Path to the PowerShell example media manifest JSON file, when generated.</summary>
+    public string? PowerShellExampleMediaManifestPath { get; set; }
     /// <summary>Number of types documented.</summary>
     public int TypeCount { get; set; }
     /// <summary>True when reflection was used to populate types.</summary>
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.Models.cs b/PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.Models.cs
index 9e20262c..73141e08 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.Models.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.Models.cs
@@ -41,9 +41,11 @@ private sealed class ApiTypeModel
         public List<string> SeeAlso { get; } = new();
         public string Kind { get; set; } = "Class";
         public string Slug { get; set; } = string.Empty;
+        public ApiFreshnessModel? Freshness { get; set; }
         public bool IsStatic { get; set; }
         public bool IsAbstract { get; set; }
         public bool IsSealed { get; set; }
+        public List<string> OriginFiles { get; } = new();
         public List<ApiMemberModel> Methods { get; } = new();
         public List<ApiMemberModel> Constructors { get; } = new();
         public List<ApiMemberModel> Properties { get; } = new();
@@ -52,6 +54,15 @@ private sealed class ApiTypeModel
         public List<ApiMemberModel> ExtensionMethods { get; } = new();
     }
 
+    private sealed class ApiFreshnessModel
+    {
+        public string Status { get; set; } = "stable";
+        public DateTimeOffset LastModifiedUtc { get; set; }
+        public string? CommitSha { get; set; }
+        public int AgeDays { get; set; }
+        public string? SourcePath { get; set; }
+    }
+
     private sealed class ApiMemberModel
     {
         public string Name { get; set; } = string.Empty;
@@ -104,6 +115,36 @@ private sealed class ApiExampleModel
     {
         public string Kind { get; set; } = "text";
         public string Text { get; set; } = string.Empty;
+        public string? Origin { get; set; }
+        public ApiExampleMediaModel? Media { get; set; }
+    }
+
+    private sealed class ApiExampleMediaModel
+    {
+        public string Type { get; set; } = "link";
+        public string Url { get; set; } = string.Empty;
+        public string? Title { get; set; }
+        public string? Alt { get; set; }
+        public string? Caption { get; set; }
+        public string? PosterUrl { get; set; }
+        public string? MimeType { get; set; }
+        public int? Width { get; set; }
+        public int? Height { get; set; }
+        public string? SourcePath { get; set; }
+        public string? AssetPath { get; set; }
+        public string? PosterAssetPath { get; set; }
+        public DateTimeOffset? CapturedAtUtc { get; set; }
+        public DateTimeOffset? SourceUpdatedAtUtc { get; set; }
+        public bool HasUnsupportedSidecars { get; set; }
+        public bool HasOversizedAssets { get; set; }
+        public bool HasStaleAssets { get; set; }
+    }
+
+    private static class ApiExampleOrigins
+    {
+        public const string AuthoredHelp = "AuthoredHelp";
+        public const string ImportedScript = "ImportedScript";
+        public const string GeneratedFallback = "GeneratedFallback";
     }
 
     private sealed class ApiSourceLink
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.SourceValidation.cs b/PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.SourceValidation.cs
index 2800e5fd..2e775f3a 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.SourceValidation.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.ApiDocs.SourceValidation.cs
@@ -192,6 +192,7 @@ private static void ValidateSourceUrlDuplicatePathHints(
 
         var hintCount = 0;
         var samples = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var urlSamples = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
 
         void ObserveSource(ApiSourceLink? source)
         {
@@ -214,6 +215,9 @@ void ObserveSource(ApiSourceLink? source)
             hintCount++;
             if (samples.Count < 8 && !string.IsNullOrWhiteSpace(hint))
                 samples.Add(hint);
+            var trimmedUrl = source.Url.Trim();
+            if (urlSamples.Count < 4 && !string.IsNullOrWhiteSpace(trimmedUrl))
+                urlSamples.Add(trimmedUrl);
         }
 
         foreach (var type in types)
@@ -232,9 +236,12 @@ void ObserveSource(ApiSourceLink? source)
 
         var samplePreview = string.Join(", ", samples.Take(4));
         var more = samples.Count > 4 ? $" (+{samples.Count - 4} more samples)" : string.Empty;
+        var urlPreview = urlSamples.Count == 0
+            ? string.Empty
+            : $" Example URLs: {string.Join(" | ", urlSamples.Take(2))}.";
         warnings.Add(
             $"API docs source: detected likely duplicated path prefixes in GitHub source URLs for {hintCount} symbol(s) (samples: {samplePreview}{more}). " +
-            "Check sourceUrl/sourceUrlMappings/sourcePathPrefix; in mixed layouts prefer pathNoPrefix with stripPathPrefix:true.");
+            $"Check sourceUrl/sourceUrlMappings/sourcePathPrefix; in mixed layouts prefer pathNoPrefix with stripPathPrefix:true.{urlPreview}");
     }
 
     private static bool TryBuildPathDuplicationHint(string sourcePath, string githubFilePath, out string hint)
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.Coverage.cs b/PowerForge.Web/Services/WebApiDocsGenerator.Coverage.cs
index bd49ba7d..75123cc0 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.Coverage.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.Coverage.cs
@@ -36,6 +36,90 @@ public static partial class WebApiDocsGenerator
         }
     }
 
+    private static void AppendSourceCoverageWarnings(
+        IReadOnlyList<ApiTypeModel> types,
+        List<string> warnings)
+    {
+        if (types is null || warnings is null)
+            return;
+
+        var allMembers = types
+            .SelectMany(static t => t.Methods
+                .Concat(t.Constructors)
+                .Concat(t.Properties)
+                .Concat(t.Fields)
+                .Concat(t.Events)
+                .Concat(t.ExtensionMethods))
+            .ToArray();
+        var commandTypes = types.Where(IsPowerShellCommandType).ToArray();
+
+        var groups = new[]
+        {
+            new SourceCoverageGroup("types", AnalyzeSourceCoverage(types.Select(static t => t.Source))),
+            new SourceCoverageGroup("members", AnalyzeSourceCoverage(allMembers.Select(static m => m.Source))),
+            new SourceCoverageGroup("powershell", AnalyzeSourceCoverage(commandTypes.Select(static c => c.Source)))
+        };
+
+        AppendSourceCoverageWarning(
+            groups,
+            static group => group.Stats.UnresolvedTemplateTokenCount,
+            static group => group.Stats.UnresolvedTemplateSamples,
+            "generated source URLs still contain unresolved template tokens",
+            warnings);
+        AppendSourceCoverageWarning(
+            groups,
+            static group => group.Stats.InvalidUrlCount,
+            static group => group.Stats.InvalidUrlSamples,
+            "generated source URLs are not valid http/https URLs",
+            warnings);
+        AppendSourceCoverageWarning(
+            groups,
+            static group => group.Stats.RepoMismatchHintCount,
+            static group => group.Stats.RepoMismatchUrlSamples,
+            "generated GitHub source URLs look mismatched to the inferred repo and may 404",
+            warnings);
+    }
+
+    private static void AppendPowerShellExampleQualityWarnings(
+        IReadOnlyList<ApiTypeModel> types,
+        List<string> warnings)
+    {
+        if (types is null || warnings is null)
+            return;
+
+        var commands = types.Where(IsPowerShellCommandType).ToArray();
+        if (commands.Length == 0)
+            return;
+
+        var generatedOnly = commands
+            .Where(HasOnlyGeneratedPowerShellFallbackExamples)
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+        if (generatedOnly.Length > 0)
+        {
+            var preview = string.Join(", ", generatedOnly.Take(4));
+            var more = generatedOnly.Length > 4 ? $" (+{generatedOnly.Length - 4} more)" : string.Empty;
+            warnings.Add(
+                $"API docs PowerShell coverage: {generatedOnly.Length} command(s) rely only on generated fallback examples. " +
+                $"Add authored examples or example scripts for better docs quality (samples: {preview}{more}).");
+        }
+
+        var playbackWithoutPoster = commands
+            .Where(HasImportedPlaybackMediaWithoutPoster)
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+        if (playbackWithoutPoster.Length == 0)
+            return;
+
+        var posterPreview = string.Join(", ", playbackWithoutPoster.Take(4));
+        var posterMore = playbackWithoutPoster.Length > 4 ? $" (+{playbackWithoutPoster.Length - 4} more)" : string.Empty;
+        warnings.Add(
+            $"API docs PowerShell coverage: {playbackWithoutPoster.Length} command(s) expose imported playback media without poster art. " +
+            $"Add matching .png/.jpg/.jpeg/.webp sidecars for better docs quality (samples: {posterPreview}{posterMore}).");
+    }
+
     private static Dictionary<string, object?> BuildCoveragePayload(
         IReadOnlyList<ApiTypeModel> types,
         string? assemblyName,
@@ -74,15 +158,75 @@ public static partial class WebApiDocsGenerator
         var commandCount = commandTypes.Length;
         var commandsWithSummary = commandTypes.Count(static c => !string.IsNullOrWhiteSpace(c.Summary));
         var commandsWithRemarks = commandTypes.Count(static c => !string.IsNullOrWhiteSpace(c.Remarks));
-        var commandsWithCodeExamples = commandTypes.Count(static c => c.Examples.Any(static ex =>
-            ex.Kind.Equals("code", StringComparison.OrdinalIgnoreCase) &&
-            !string.IsNullOrWhiteSpace(ex.Text)));
+        var commandsWithCodeExamples = commandTypes.Count(HasCodeExamples);
+        var commandsWithAuthoredHelpCodeExamples = commandTypes.Count(static c => HasCodeExamplesFromOrigin(c, ApiExampleOrigins.AuthoredHelp));
+        var commandsWithImportedScriptCodeExamples = commandTypes.Count(static c => HasCodeExamplesFromOrigin(c, ApiExampleOrigins.ImportedScript));
+        var commandsWithGeneratedFallbackCodeExamples = commandTypes.Count(static c => HasCodeExamplesFromOrigin(c, ApiExampleOrigins.GeneratedFallback));
+        var commandsWithGeneratedFallbackOnlyExamples = commandTypes.Count(HasOnlyGeneratedPowerShellFallbackExamples);
+        var commandsWithImportedScriptPlaybackMedia = commandTypes.Count(HasImportedPlaybackMedia);
+        var commandsWithImportedScriptPlaybackMediaWithPoster = commandTypes.Count(HasImportedPlaybackMediaWithPoster);
+        var commandsWithImportedScriptPlaybackMediaWithoutPoster = commandTypes.Count(HasImportedPlaybackMediaWithoutPoster);
+        var commandsWithImportedScriptPlaybackMediaUnsupportedSidecars = commandTypes.Count(HasImportedPlaybackMediaWithUnsupportedSidecars);
+        var commandsWithImportedScriptPlaybackMediaOversizedAssets = commandTypes.Count(HasImportedPlaybackMediaWithOversizedAssets);
+        var commandsWithImportedScriptPlaybackMediaStaleAssets = commandTypes.Count(HasImportedPlaybackMediaWithStaleAssets);
         var commandSourceCoverage = AnalyzeSourceCoverage(commandTypes.Select(static c => c.Source));
 
         var commandsMissingExamples = commandTypes
-            .Where(static c => !c.Examples.Any(static ex =>
-                ex.Kind.Equals("code", StringComparison.OrdinalIgnoreCase) &&
-                !string.IsNullOrWhiteSpace(ex.Text)))
+            .Where(static c => !HasCodeExamples(c))
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingGeneratedFallbackOnlyExamples = commandTypes
+            .Where(HasOnlyGeneratedPowerShellFallbackExamples)
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingAuthoredHelpCodeExamples = commandTypes
+            .Where(static c => HasCodeExamplesFromOrigin(c, ApiExampleOrigins.AuthoredHelp))
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingImportedScriptCodeExamples = commandTypes
+            .Where(static c => HasCodeExamplesFromOrigin(c, ApiExampleOrigins.ImportedScript))
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingGeneratedFallbackCodeExamples = commandTypes
+            .Where(static c => HasCodeExamplesFromOrigin(c, ApiExampleOrigins.GeneratedFallback))
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingImportedScriptPlaybackMedia = commandTypes
+            .Where(HasImportedPlaybackMedia)
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingImportedScriptPlaybackMediaWithoutPoster = commandTypes
+            .Where(HasImportedPlaybackMediaWithoutPoster)
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingImportedScriptPlaybackMediaUnsupportedSidecars = commandTypes
+            .Where(HasImportedPlaybackMediaWithUnsupportedSidecars)
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingImportedScriptPlaybackMediaOversizedAssets = commandTypes
+            .Where(HasImportedPlaybackMediaWithOversizedAssets)
+            .Select(static c => c.FullName)
+            .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
+            .Take(100)
+            .ToArray();
+        var commandsUsingImportedScriptPlaybackMediaStaleAssets = commandTypes
+            .Where(HasImportedPlaybackMediaWithStaleAssets)
             .Select(static c => c.FullName)
             .OrderBy(static c => c, StringComparer.OrdinalIgnoreCase)
             .Take(100)
@@ -142,12 +286,150 @@ public static partial class WebApiDocsGenerator
                 ["summary"] = MakeCoverage(commandCount, commandsWithSummary),
                 ["remarks"] = MakeCoverage(commandCount, commandsWithRemarks),
                 ["codeExamples"] = MakeCoverage(commandCount, commandsWithCodeExamples),
+                ["authoredHelpCodeExamples"] = MakeCoverage(commandCount, commandsWithAuthoredHelpCodeExamples),
+                ["importedScriptCodeExamples"] = MakeCoverage(commandCount, commandsWithImportedScriptCodeExamples),
+                ["generatedFallbackCodeExamples"] = MakeCoverage(commandCount, commandsWithGeneratedFallbackCodeExamples),
+                ["generatedFallbackOnlyExamples"] = MakeCoverage(commandCount, commandsWithGeneratedFallbackOnlyExamples),
+                ["importedScriptPlaybackMedia"] = MakeCoverage(commandCount, commandsWithImportedScriptPlaybackMedia),
+                ["importedScriptPlaybackMediaWithPoster"] = MakeCoverage(commandsWithImportedScriptPlaybackMedia, commandsWithImportedScriptPlaybackMediaWithPoster),
+                ["importedScriptPlaybackMediaWithoutPoster"] = MakeCoverage(commandsWithImportedScriptPlaybackMedia, commandsWithImportedScriptPlaybackMediaWithoutPoster),
+                ["importedScriptPlaybackMediaUnsupportedSidecars"] = MakeCoverage(commandsWithImportedScriptPlaybackMedia, commandsWithImportedScriptPlaybackMediaUnsupportedSidecars),
+                ["importedScriptPlaybackMediaOversizedAssets"] = MakeCoverage(commandsWithImportedScriptPlaybackMedia, commandsWithImportedScriptPlaybackMediaOversizedAssets),
+                ["importedScriptPlaybackMediaStaleAssets"] = MakeCoverage(commandsWithImportedScriptPlaybackMedia, commandsWithImportedScriptPlaybackMediaStaleAssets),
                 ["parameters"] = MakeCoverage(commandParameterCount, commandParametersWithSummary),
-                ["commandsMissingCodeExamples"] = commandsMissingExamples
+                ["commandsMissingCodeExamples"] = commandsMissingExamples,
+                ["commandsUsingAuthoredHelpCodeExamples"] = commandsUsingAuthoredHelpCodeExamples,
+                ["commandsUsingImportedScriptCodeExamples"] = commandsUsingImportedScriptCodeExamples,
+                ["commandsUsingGeneratedFallbackCodeExamples"] = commandsUsingGeneratedFallbackCodeExamples,
+                ["commandsUsingGeneratedFallbackOnlyExamples"] = commandsUsingGeneratedFallbackOnlyExamples,
+                ["commandsUsingImportedScriptPlaybackMedia"] = commandsUsingImportedScriptPlaybackMedia,
+                ["commandsUsingImportedScriptPlaybackMediaWithoutPoster"] = commandsUsingImportedScriptPlaybackMediaWithoutPoster,
+                ["commandsUsingImportedScriptPlaybackMediaUnsupportedSidecars"] = commandsUsingImportedScriptPlaybackMediaUnsupportedSidecars,
+                ["commandsUsingImportedScriptPlaybackMediaOversizedAssets"] = commandsUsingImportedScriptPlaybackMediaOversizedAssets,
+                ["commandsUsingImportedScriptPlaybackMediaStaleAssets"] = commandsUsingImportedScriptPlaybackMediaStaleAssets
             }
         };
     }
 
+    private static void AppendSourceCoverageWarning(
+        IReadOnlyList<SourceCoverageGroup> groups,
+        Func<SourceCoverageGroup, int> countSelector,
+        Func<SourceCoverageGroup, IReadOnlyList<string>> sampleSelector,
+        string message,
+        List<string> warnings)
+    {
+        if (groups is null || groups.Count == 0 || string.IsNullOrWhiteSpace(message) || warnings is null)
+            return;
+
+        var active = groups
+            .Select(group => new
+            {
+                Group = group,
+                Count = Math.Max(0, countSelector(group)),
+                Samples = (sampleSelector(group) ?? Array.Empty<string>())
+                    .Where(static sample => !string.IsNullOrWhiteSpace(sample))
+                    .Distinct(StringComparer.OrdinalIgnoreCase)
+                    .ToArray()
+            })
+            .Where(static entry => entry.Count > 0)
+            .ToArray();
+        if (active.Length == 0)
+            return;
+
+        var breakdown = string.Join(", ", active.Select(static entry => $"{entry.Group.Label} {entry.Count}"));
+        var samples = active
+            .SelectMany(static entry => entry.Samples)
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .Take(3)
+            .ToArray();
+        var sampleText = samples.Length == 0
+            ? string.Empty
+            : $" (samples: {string.Join(" | ", samples)})";
+        warnings.Add($"API docs source coverage: {message} ({breakdown}){sampleText}.");
+    }
+
+    private static bool HasOnlyGeneratedPowerShellFallbackExamples(ApiTypeModel type)
+    {
+        if (type is null || type.Examples.Count == 0)
+            return false;
+
+        var codeExamples = type.Examples.Where(IsCodeExample).ToArray();
+        return codeExamples.Length > 0 &&
+               codeExamples.All(static example =>
+                   string.Equals(example.Origin, ApiExampleOrigins.GeneratedFallback, StringComparison.OrdinalIgnoreCase));
+    }
+
+    private static bool HasCodeExamples(ApiTypeModel type)
+    {
+        return type is not null && type.Examples.Any(IsCodeExample);
+    }
+
+    private static bool HasCodeExamplesFromOrigin(ApiTypeModel type, string origin)
+    {
+        return type is not null &&
+               !string.IsNullOrWhiteSpace(origin) &&
+               type.Examples.Any(example =>
+                   IsCodeExample(example) &&
+                   string.Equals(example.Origin, origin, StringComparison.OrdinalIgnoreCase));
+    }
+
+    private static bool HasImportedPlaybackMedia(ApiTypeModel type)
+    {
+        return GetImportedPlaybackMediaExamples(type).Any();
+    }
+
+    private static bool HasImportedPlaybackMediaWithPoster(ApiTypeModel type)
+    {
+        var examples = GetImportedPlaybackMediaExamples(type).ToArray();
+        return examples.Length > 0 &&
+               examples.All(static example => !string.IsNullOrWhiteSpace(example.Media?.PosterUrl));
+    }
+
+    private static bool HasImportedPlaybackMediaWithoutPoster(ApiTypeModel type)
+    {
+        return GetImportedPlaybackMediaExamples(type)
+            .Any(static example => string.IsNullOrWhiteSpace(example.Media?.PosterUrl));
+    }
+
+    private static bool HasImportedPlaybackMediaWithUnsupportedSidecars(ApiTypeModel type)
+    {
+        return GetImportedPlaybackMediaExamples(type)
+            .Any(static example => example.Media?.HasUnsupportedSidecars == true);
+    }
+
+    private static bool HasImportedPlaybackMediaWithOversizedAssets(ApiTypeModel type)
+    {
+        return GetImportedPlaybackMediaExamples(type)
+            .Any(static example => example.Media?.HasOversizedAssets == true);
+    }
+
+    private static bool HasImportedPlaybackMediaWithStaleAssets(ApiTypeModel type)
+    {
+        return GetImportedPlaybackMediaExamples(type)
+            .Any(static example => example.Media?.HasStaleAssets == true);
+    }
+
+    private static IEnumerable<ApiExampleModel> GetImportedPlaybackMediaExamples(ApiTypeModel? type)
+    {
+        if (type?.Examples is null || type.Examples.Count == 0)
+            return Enumerable.Empty<ApiExampleModel>();
+
+        return type.Examples.Where(static example =>
+            example is not null &&
+            example.Kind.Equals("media", StringComparison.OrdinalIgnoreCase) &&
+            string.Equals(example.Origin, ApiExampleOrigins.ImportedScript, StringComparison.OrdinalIgnoreCase) &&
+            example.Media is not null &&
+            example.Media.Type.Equals("terminal", StringComparison.OrdinalIgnoreCase) &&
+            string.Equals(example.Media.MimeType, "application/x-asciicast", StringComparison.OrdinalIgnoreCase));
+    }
+
+    private static bool IsCodeExample(ApiExampleModel example)
+    {
+        return example is not null &&
+               example.Kind.Equals("code", StringComparison.OrdinalIgnoreCase) &&
+               !string.IsNullOrWhiteSpace(example.Text);
+    }
+
     private static Dictionary<string, object?> BuildSourceCoveragePayload(int total, SourceCoverageStats coverage)
     {
         return new Dictionary<string, object?>
@@ -221,6 +503,16 @@ private static SourceCoverageStats AnalyzeSourceCoverage(IEnumerable<ApiSourceLi
                     stats.RepoMismatchHintCount++;
                     if (mismatchSamples.Count < sampleLimit && !string.IsNullOrWhiteSpace(mismatchHint))
                         mismatchSamples.Add(mismatchHint);
+                    if (stats.RepoMismatchUrlSamples.Length < sampleLimit)
+                    {
+                        var urlSample = url.Trim();
+                        if (!string.IsNullOrWhiteSpace(urlSample))
+                            stats.RepoMismatchUrlSamples = stats.RepoMismatchUrlSamples
+                                .Append(urlSample)
+                                .Distinct(StringComparer.OrdinalIgnoreCase)
+                                .Take(sampleLimit)
+                                .ToArray();
+                    }
                 }
             }
             else
@@ -294,5 +586,18 @@ private sealed class SourceCoverageStats
         public string[] InvalidUrlSamples { get; set; } = Array.Empty<string>();
         public string[] UnresolvedTemplateSamples { get; set; } = Array.Empty<string>();
         public string[] RepoMismatchSamples { get; set; } = Array.Empty<string>();
+        public string[] RepoMismatchUrlSamples { get; set; } = Array.Empty<string>();
+    }
+
+    private sealed class SourceCoverageGroup
+    {
+        public SourceCoverageGroup(string label, SourceCoverageStats stats)
+        {
+            Label = label;
+            Stats = stats;
+        }
+
+        public string Label { get; }
+        public SourceCoverageStats Stats { get; }
     }
 }
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.Freshness.cs b/PowerForge.Web/Services/WebApiDocsGenerator.Freshness.cs
new file mode 100644
index 00000000..03f330d8
--- /dev/null
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.Freshness.cs
@@ -0,0 +1,215 @@
+using PowerForge;
+
+namespace PowerForge.Web;
+
+public static partial class WebApiDocsGenerator
+{
+    private static void AppendGitFreshnessMetadata(
+        IReadOnlyList<ApiTypeModel> types,
+        WebApiDocsOptions options)
+    {
+        if (types is null || types.Count == 0 || options is null || !options.GenerateGitFreshness)
+            return;
+
+        var updatedDays = Math.Max(options.GitFreshnessNewDays, options.GitFreshnessUpdatedDays);
+        var newDays = Math.Clamp(options.GitFreshnessNewDays, 0, updatedDays);
+        var utcNow = DateTimeOffset.UtcNow;
+
+        var gitClient = new GitClient(defaultTimeout: TimeSpan.FromSeconds(10));
+        var repositoryRootCache = new Dictionary<string, string?>(StringComparer.OrdinalIgnoreCase);
+        var freshnessCache = new Dictionary<string, ApiFreshnessModel?>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var type in types)
+        {
+            var candidates = GetFreshnessCandidateFiles(type, options);
+            ApiFreshnessModel? best = null;
+            foreach (var candidate in candidates)
+            {
+                if (!freshnessCache.TryGetValue(candidate, out var freshness))
+                {
+                    freshness = TryGetGitFreshness(candidate, gitClient, repositoryRootCache, utcNow, newDays, updatedDays);
+                    freshnessCache[candidate] = freshness;
+                }
+
+                if (freshness is null)
+                    continue;
+
+                if (best is null || freshness.LastModifiedUtc > best.LastModifiedUtc)
+                    best = freshness;
+            }
+
+            type.Freshness = best;
+        }
+    }
+
+    private static ApiFreshnessModel? TryGetGitFreshness(
+        string filePath,
+        GitClient gitClient,
+        IDictionary<string, string?> repositoryRootCache,
+        DateTimeOffset utcNow,
+        int newDays,
+        int updatedDays)
+    {
+        if (string.IsNullOrWhiteSpace(filePath) || !File.Exists(filePath))
+            return null;
+
+        var fullPath = Path.GetFullPath(filePath);
+        var directory = Path.GetDirectoryName(fullPath);
+        if (string.IsNullOrWhiteSpace(directory))
+            return null;
+
+        if (!repositoryRootCache.TryGetValue(directory, out var repositoryRoot))
+        {
+            var topLevel = gitClient.ShowTopLevelAsync(directory).GetAwaiter().GetResult();
+            repositoryRoot = topLevel.Succeeded
+                ? topLevel.StdOut.Trim()
+                : null;
+            repositoryRootCache[directory] = repositoryRoot;
+        }
+
+        if (string.IsNullOrWhiteSpace(repositoryRoot) || !Directory.Exists(repositoryRoot))
+            return null;
+
+        var relativePath = Path.GetRelativePath(repositoryRoot, fullPath);
+        if (string.IsNullOrWhiteSpace(relativePath) ||
+            relativePath.StartsWith("..", StringComparison.Ordinal))
+            return null;
+
+        var log = gitClient.RunRawAsync(
+                repositoryRoot,
+                new[] { "log", "-1", "--format=%H%n%cI", "--", relativePath.Replace('\\', '/') },
+                TimeSpan.FromSeconds(10))
+            .GetAwaiter()
+            .GetResult();
+        if (!log.Succeeded || string.IsNullOrWhiteSpace(log.StdOut))
+            return null;
+
+        var lines = log.StdOut
+            .Split(new[] { "\r\n", "\n" }, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (lines.Length < 2 || !DateTimeOffset.TryParse(lines[1], out var lastModified))
+            return null;
+
+        var ageDays = Math.Max(0, (int)Math.Floor((utcNow - lastModified).TotalDays));
+        var status = ageDays <= newDays
+            ? "new"
+            : ageDays <= updatedDays
+                ? "updated"
+                : "stable";
+
+        return new ApiFreshnessModel
+        {
+            Status = status,
+            LastModifiedUtc = lastModified.ToUniversalTime(),
+            CommitSha = string.IsNullOrWhiteSpace(lines[0]) ? null : lines[0].Trim(),
+            AgeDays = ageDays,
+            SourcePath = fullPath
+        };
+    }
+
+    private static string[] GetFreshnessCandidateFiles(ApiTypeModel type, WebApiDocsOptions options)
+    {
+        var files = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        if (type is null)
+            return Array.Empty<string>();
+
+        AddFreshnessCandidate(files, type.Source?.Path, options.SourceRootPath);
+        foreach (var originFile in type.OriginFiles)
+            AddFreshnessCandidate(files, originFile, options.SourceRootPath);
+
+        foreach (var member in type.Methods)
+            AddFreshnessCandidate(files, member.Source?.Path, options.SourceRootPath);
+        foreach (var member in type.Constructors)
+            AddFreshnessCandidate(files, member.Source?.Path, options.SourceRootPath);
+        foreach (var member in type.Properties)
+            AddFreshnessCandidate(files, member.Source?.Path, options.SourceRootPath);
+        foreach (var member in type.Fields)
+            AddFreshnessCandidate(files, member.Source?.Path, options.SourceRootPath);
+        foreach (var member in type.Events)
+            AddFreshnessCandidate(files, member.Source?.Path, options.SourceRootPath);
+        foreach (var member in type.ExtensionMethods)
+            AddFreshnessCandidate(files, member.Source?.Path, options.SourceRootPath);
+
+        if (files.Count == 0)
+        {
+            if (options.Type == ApiDocsType.CSharp)
+                AddFreshnessCandidate(files, options.XmlPath);
+            else
+                AddFreshnessCandidate(files, options.HelpPath);
+        }
+
+        return files.OrderBy(static file => file, StringComparer.OrdinalIgnoreCase).ToArray();
+    }
+
+    private static void AddFreshnessCandidate(ISet<string> files, string? path, string? sourceRootPath = null)
+    {
+        if (files is null || string.IsNullOrWhiteSpace(path))
+            return;
+
+        try
+        {
+            var fullPath = Path.IsPathRooted(path)
+                ? Path.GetFullPath(path)
+                : !string.IsNullOrWhiteSpace(sourceRootPath)
+                    ? Path.GetFullPath(Path.Combine(sourceRootPath, path))
+                    : Path.GetFullPath(path);
+            if (File.Exists(fullPath))
+                files.Add(fullPath);
+        }
+        catch
+        {
+            // best effort only
+        }
+    }
+
+    private static Dictionary<string, object?>? BuildFreshnessJson(ApiFreshnessModel? freshness, WebApiDocsOptions options)
+    {
+        if (freshness is null)
+            return null;
+
+        return new Dictionary<string, object?>
+        {
+            ["status"] = freshness.Status,
+            ["lastModifiedUtc"] = freshness.LastModifiedUtc.ToString("O"),
+            ["commitSha"] = freshness.CommitSha,
+            ["ageDays"] = freshness.AgeDays,
+            ["sourcePath"] = NormalizeFreshnessSourcePath(freshness.SourcePath, options)
+        };
+    }
+
+    private static string? NormalizeFreshnessSourcePath(string? path, WebApiDocsOptions? options)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return null;
+
+        try
+        {
+            var fullPath = Path.GetFullPath(path);
+            foreach (var root in EnumerateFreshnessNormalizationRoots(options))
+            {
+                var relativePath = TryGetRelativePathWithinRoot(root, fullPath);
+                if (!string.IsNullOrWhiteSpace(relativePath))
+                    return relativePath;
+            }
+
+            return Path.GetFileName(fullPath);
+        }
+        catch
+        {
+            return Path.GetFileName(path);
+        }
+    }
+
+    private static IEnumerable<string> EnumerateFreshnessNormalizationRoots(WebApiDocsOptions? options)
+    {
+        if (options is null)
+            yield break;
+
+        foreach (var root in EnumerateNonEmptyDirectories(
+                     options.SourceRootPath,
+                     GetParentDirectory(options.HelpPath),
+                     GetParentDirectory(options.XmlPath)))
+        {
+            yield return root;
+        }
+    }
+}
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.Html.TypeDetail.cs b/PowerForge.Web/Services/WebApiDocsGenerator.Html.TypeDetail.cs
index 5ea6a646..261eefcf 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.Html.TypeDetail.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.Html.TypeDetail.cs
@@ -2,6 +2,7 @@
 using System.Reflection.Metadata;
 using System.Reflection.Metadata.Ecma335;
 using System.Diagnostics;
+using System.Globalization;
 using System.Text;
 using System.Text.Json;
 using System.Text.RegularExpressions;
@@ -46,6 +47,7 @@ private static string BuildDocsTypeDetail(
         var kindLabel = string.IsNullOrWhiteSpace(type.Kind) ? "Type" : type.Kind;
         sb.AppendLine("        <div class=\"type-title-row\">");
         sb.AppendLine($"          <span class=\"type-badge {NormalizeKind(type.Kind)}\">{System.Web.HttpUtility.HtmlEncode(kindLabel)}</span>");
+        AppendFreshnessBadge(sb, type.Freshness, "type-freshness-badge");
         sb.AppendLine($"          <h1>{System.Web.HttpUtility.HtmlEncode(displayName)}</h1>");
         sb.AppendLine("        </div>");
         AppendAliasInlineMeta(sb, type, "type-header-meta", "type-header-aliases");
@@ -121,6 +123,13 @@ private static string BuildDocsTypeDetail(
             sb.AppendLine($"          {RenderSourceLink(type.Source)}");
             sb.AppendLine("        </div>");
         }
+        if (type.Freshness is not null)
+        {
+            sb.AppendLine("        <div class=\"type-meta-row type-meta-freshness\">");
+            sb.AppendLine("          <span class=\"type-meta-label\">Updated</span>");
+            sb.AppendLine($"          <span>{RenderFreshnessText(type.Freshness)}</span>");
+            sb.AppendLine("        </div>");
+        }
         if (!string.IsNullOrWhiteSpace(type.BaseType))
         {
             sb.AppendLine("        <div class=\"type-meta-row type-meta-inheritance\">");
@@ -566,8 +575,15 @@ private static void AppendExamples(
         IReadOnlyDictionary<string, string> slugMap,
         string codeLanguage)
     {
+        string? lastOrigin = null;
         foreach (var example in examples)
         {
+            AppendExampleOriginBadge(sb, example, ref lastOrigin);
+            if (string.Equals(example.Kind, "media", StringComparison.OrdinalIgnoreCase) && example.Media is not null)
+            {
+                AppendExampleMedia(sb, example.Media, baseUrl, slugMap);
+                continue;
+            }
             if (string.IsNullOrWhiteSpace(example.Text)) continue;
             if (string.Equals(example.Kind, "code", StringComparison.OrdinalIgnoreCase))
             {
@@ -590,6 +606,144 @@ private static void AppendExamples(
         }
     }
 
+    private static void AppendExampleOriginBadge(
+        StringBuilder sb,
+        ApiExampleModel example,
+        ref string? lastOrigin)
+    {
+        if (sb is null || example is null)
+            return;
+
+        if (string.IsNullOrWhiteSpace(example.Origin))
+        {
+            lastOrigin = null;
+            return;
+        }
+
+        if (string.Equals(lastOrigin, example.Origin, StringComparison.OrdinalIgnoreCase))
+            return;
+
+        var (label, description, className) = GetExampleOriginPresentation(example.Origin);
+        if (string.IsNullOrWhiteSpace(label))
+        {
+            lastOrigin = example.Origin;
+            return;
+        }
+
+        var encodedOrigin = System.Web.HttpUtility.HtmlEncode(example.Origin);
+        var encodedClass = System.Web.HttpUtility.HtmlEncode(className);
+        var encodedLabel = System.Web.HttpUtility.HtmlEncode(label);
+        var encodedDescription = System.Web.HttpUtility.HtmlEncode(description);
+
+        sb.AppendLine($"        <div class=\"example-origin\" data-example-origin=\"{encodedOrigin}\">");
+        sb.AppendLine($"          <span class=\"param-meta-chip example-origin-badge {encodedClass}\" title=\"{encodedDescription}\">{encodedLabel}</span>");
+        sb.AppendLine("        </div>");
+        lastOrigin = example.Origin;
+    }
+
+    private static (string Label, string Description, string ClassName) GetExampleOriginPresentation(string? origin)
+    {
+        if (string.IsNullOrWhiteSpace(origin))
+            return (string.Empty, string.Empty, string.Empty);
+
+        if (string.Equals(origin, ApiExampleOrigins.AuthoredHelp, StringComparison.OrdinalIgnoreCase))
+            return ("Authored help example", "Example authored directly in source help.", "example-origin-authored");
+        if (string.Equals(origin, ApiExampleOrigins.ImportedScript, StringComparison.OrdinalIgnoreCase))
+            return ("Imported script example", "Example imported from a curated PowerShell script.", "example-origin-imported");
+        if (string.Equals(origin, ApiExampleOrigins.GeneratedFallback, StringComparison.OrdinalIgnoreCase))
+            return ("Generated fallback example", "Example generated from documented parameter sets.", "example-origin-generated");
+
+        return (origin.Trim(), $"Example origin: {origin.Trim()}.", "example-origin-other");
+    }
+
+    private static void AppendExampleMedia(
+        StringBuilder sb,
+        ApiExampleMediaModel media,
+        string baseUrl,
+        IReadOnlyDictionary<string, string> slugMap)
+    {
+        if (media is null || string.IsNullOrWhiteSpace(media.Url))
+            return;
+
+        var mediaType = string.IsNullOrWhiteSpace(media.Type) ? "link" : media.Type.Trim().ToLowerInvariant();
+        var safeType = System.Web.HttpUtility.HtmlEncode(mediaType);
+        var safeUrl = System.Web.HttpUtility.HtmlEncode(media.Url);
+        var caption = string.IsNullOrWhiteSpace(media.Caption) ? string.Empty : media.Caption.Trim();
+        var title = string.IsNullOrWhiteSpace(media.Title) ? string.Empty : media.Title.Trim();
+        var alt = string.IsNullOrWhiteSpace(media.Alt)
+            ? (!string.IsNullOrWhiteSpace(title) ? title : "Example media")
+            : media.Alt.Trim();
+        var safeAlt = System.Web.HttpUtility.HtmlEncode(alt);
+        var safeTitle = System.Web.HttpUtility.HtmlEncode(title);
+        var safePoster = string.IsNullOrWhiteSpace(media.PosterUrl) ? string.Empty : System.Web.HttpUtility.HtmlEncode(media.PosterUrl);
+        var safeMimeType = string.IsNullOrWhiteSpace(media.MimeType) ? string.Empty : System.Web.HttpUtility.HtmlEncode(media.MimeType);
+        var widthAttr = media.Width is > 0 ? $" width=\"{media.Width.Value}\"" : string.Empty;
+        var heightAttr = media.Height is > 0 ? $" height=\"{media.Height.Value}\"" : string.Empty;
+
+        sb.AppendLine($"        <figure class=\"example-media example-media-{safeType}\" data-example-media-type=\"{safeType}\">");
+        switch (mediaType)
+        {
+            case "image":
+                sb.AppendLine("          <div class=\"example-media-frame\">");
+                sb.AppendLine($"            <img src=\"{safeUrl}\" alt=\"{safeAlt}\" loading=\"lazy\" decoding=\"async\"{widthAttr}{heightAttr} />");
+                sb.AppendLine("          </div>");
+                break;
+            case "video":
+                sb.AppendLine("          <div class=\"example-media-frame\">");
+                sb.Append($"            <video controls preload=\"metadata\"");
+                if (!string.IsNullOrWhiteSpace(safePoster))
+                    sb.Append($" poster=\"{safePoster}\"");
+                if (!string.IsNullOrWhiteSpace(safeTitle))
+                    sb.Append($" title=\"{safeTitle}\"");
+                sb.AppendLine($"{widthAttr}{heightAttr}>");
+                sb.Append($"              <source src=\"{safeUrl}\"");
+                if (!string.IsNullOrWhiteSpace(safeMimeType))
+                    sb.Append($" type=\"{safeMimeType}\"");
+                sb.AppendLine(" />");
+                sb.AppendLine("            </video>");
+                sb.AppendLine("          </div>");
+                break;
+            case "terminal":
+                sb.AppendLine("          <div class=\"example-media-frame example-media-frame-terminal\">");
+                if (!string.IsNullOrWhiteSpace(safePoster))
+                    sb.AppendLine($"            <img src=\"{safePoster}\" alt=\"{safeAlt}\" loading=\"lazy\" decoding=\"async\" class=\"example-media-poster\"{widthAttr}{heightAttr} />");
+                sb.AppendLine($"            <a class=\"example-media-link\" href=\"{safeUrl}\">{System.Web.HttpUtility.HtmlEncode(string.IsNullOrWhiteSpace(title) ? "Open terminal recording" : title)}</a>");
+                sb.AppendLine("          </div>");
+                break;
+            default:
+                sb.AppendLine("          <div class=\"example-media-frame example-media-frame-link\">");
+                sb.AppendLine($"            <a class=\"example-media-link\" href=\"{safeUrl}\">{System.Web.HttpUtility.HtmlEncode(string.IsNullOrWhiteSpace(title) ? media.Url : title)}</a>");
+                sb.AppendLine("          </div>");
+                break;
+        }
+
+        if (!string.IsNullOrWhiteSpace(caption))
+            sb.AppendLine($"          <figcaption class=\"example-media-caption\">{RenderLinkedText(caption, baseUrl, slugMap)}</figcaption>");
+        var mediaMeta = BuildExampleMediaMeta(media);
+        if (!string.IsNullOrWhiteSpace(mediaMeta))
+            sb.AppendLine($"          <p class=\"example-media-meta\">{System.Web.HttpUtility.HtmlEncode(mediaMeta)}</p>");
+
+        sb.AppendLine("        </figure>");
+    }
+
+    private static string BuildExampleMediaMeta(ApiExampleMediaModel media)
+    {
+        if (media is null)
+            return string.Empty;
+
+        var parts = new List<string>();
+        if (media.CapturedAtUtc is not null)
+            parts.Add("Captured " + media.CapturedAtUtc.Value.UtcDateTime.ToString("yyyy-MM-dd HH:mm 'UTC'", CultureInfo.InvariantCulture));
+        if (media.HasStaleAssets)
+            parts.Add("Script changed after this capture");
+        else if (media.SourceUpdatedAtUtc is not null &&
+                 media.CapturedAtUtc is not null &&
+                 media.SourceUpdatedAtUtc.Value > media.CapturedAtUtc.Value)
+            parts.Add("Script changed after this capture");
+
+        return string.Join(" | ", parts.Where(static part => !string.IsNullOrWhiteSpace(part)));
+    }
+
     private static IEnumerable<string> SplitExampleParagraphs(string text)
     {
         if (string.IsNullOrWhiteSpace(text))
@@ -754,4 +908,33 @@ private static string BuildUniqueMemberId(string preferredId, ISet<string> usedI
 
         return candidate;
     }
+
+    private static void AppendFreshnessBadge(StringBuilder sb, ApiFreshnessModel? freshness, string cssClass)
+    {
+        if (sb is null || freshness is null)
+            return;
+
+        var status = (freshness.Status ?? string.Empty).Trim().ToLowerInvariant();
+        if (!status.Equals("new", StringComparison.Ordinal) &&
+            !status.Equals("updated", StringComparison.Ordinal))
+            return;
+
+        var label = status.Equals("new", StringComparison.Ordinal) ? "New" : "Updated";
+        var title = RenderFreshnessText(freshness);
+        sb.AppendLine($"          <span class=\"freshness-badge {System.Web.HttpUtility.HtmlEncode(status)} {System.Web.HttpUtility.HtmlEncode(cssClass)}\" title=\"{System.Web.HttpUtility.HtmlAttributeEncode(title)}\">{System.Web.HttpUtility.HtmlEncode(label)}</span>");
+    }
+
+    private static string RenderFreshnessText(ApiFreshnessModel freshness)
+    {
+        if (freshness is null)
+            return string.Empty;
+
+        var lastModified = freshness.LastModifiedUtc == default
+            ? string.Empty
+            : freshness.LastModifiedUtc.ToString("yyyy-MM-dd");
+        var ageText = freshness.AgeDays <= 0 ? "today" : $"{freshness.AgeDays} day{(freshness.AgeDays == 1 ? string.Empty : "s")} ago";
+        return string.IsNullOrWhiteSpace(lastModified)
+            ? ageText
+            : $"{lastModified} ({ageText})";
+    }
 }
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.Html.cs b/PowerForge.Web/Services/WebApiDocsGenerator.Html.cs
index 4c86b882..91b50950 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.Html.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.Html.cs
@@ -1016,8 +1016,9 @@ private static string BuildSidebarTypeItem(
         var ns = System.Web.HttpUtility.HtmlEncode(string.IsNullOrWhiteSpace(type.Namespace) ? "(global)" : type.Namespace);
         var href = BuildDocsTypeUrl(baseUrl, type.Slug);
         var aliasAttr = BuildAliasTitleAttribute(type);
+        var freshnessBadge = BuildFreshnessBadgeHtml(type.Freshness, "type-list-freshness");
         return $"          <a href=\"{href}\" class=\"type-item{active}\" data-search=\"{searchAttr}\" data-kind=\"{kind}\" data-namespace=\"{ns}\"{aliasAttr}>" +
-               $"{icon}<span class=\"type-name\">{name}</span></a>";
+               $"{icon}<span class=\"type-name\">{name}</span>{freshnessBadge}</a>";
     }
 
     private static string BuildDocsOverview(
@@ -1032,16 +1033,7 @@ private static string BuildDocsOverview(
             .GroupBy(static t => string.IsNullOrWhiteSpace(t.Namespace) ? "(global)" : t.Namespace)
             .OrderBy(static g => g.Key, StringComparer.OrdinalIgnoreCase)
             .ToList();
-        var aliasCount = types.Sum(static type => type.Aliases
-            .Where(static alias => !string.IsNullOrWhiteSpace(alias))
-            .Select(static alias => alias.Trim())
-            .Distinct(StringComparer.OrdinalIgnoreCase)
-            .Count());
         var primaryKindLabel = ResolvePrimaryKindLabel(types);
-        var primaryKindCount = types.Count(type =>
-            string.Equals(NormalizeKind(type.Kind), NormalizeKind(primaryKindLabel), StringComparison.OrdinalIgnoreCase) ||
-            (primaryKindLabel.Equals("Function", StringComparison.OrdinalIgnoreCase) &&
-             string.Equals(NormalizeKind(type.Kind), "function", StringComparison.OrdinalIgnoreCase)));
 
         sb.AppendLine("    <div class=\"api-overview ev-page-body\">");
         sb.AppendLine("      <header class=\"ev-docs-header api-overview-header\">");
@@ -1049,8 +1041,7 @@ private static string BuildDocsOverview(
         sb.AppendLine($"        <h1>{System.Web.HttpUtility.HtmlEncode(overviewTitle)}</h1>");
         sb.AppendLine("        <p class=\"lead\">Complete API documentation auto-generated from source documentation.</p>");
         sb.AppendLine("      </header>");
-        sb.AppendLine("      <div class=\"api-overview-grid\">");
-        sb.AppendLine("        <div class=\"api-overview-main\">");
+        sb.AppendLine("      <div class=\"api-overview-main api-overview-main--full\">");
 
         var mainTypes = GetMainTypes(types, options);
         if (mainTypes.Count > 0)
@@ -1069,6 +1060,9 @@ private static string BuildDocsOverview(
                 sb.AppendLine("            <div class=\"quick-card-header\">");
                 sb.AppendLine($"              {quickIcon}");
                 sb.AppendLine($"              <strong>{System.Web.HttpUtility.HtmlEncode(displayName)}</strong>");
+                var freshnessBadge = BuildFreshnessBadgeHtml(type.Freshness, "quick-card-freshness");
+                if (!string.IsNullOrWhiteSpace(freshnessBadge))
+                    sb.AppendLine($"              {freshnessBadge}");
                 sb.AppendLine("            </div>");
                 AppendAliasInlineMeta(sb, type, "quick-card-meta", "quick-card-aliases");
                 if (!string.IsNullOrWhiteSpace(summary))
@@ -1089,36 +1083,6 @@ private static string BuildDocsOverview(
             AppendOverviewNamespaceGroup(sb, group, baseUrl, typeDisplayNames);
         }
         sb.AppendLine("      </section>");
-        sb.AppendLine("        </div>");
-        sb.AppendLine("        <aside class=\"api-overview-rail\">");
-        sb.AppendLine("          <section class=\"api-overview-rail-card api-overview-rail-card--stats\">");
-        sb.AppendLine("            <p class=\"api-overview-rail-eyebrow\">Workspace Stats</p>");
-        sb.AppendLine("            <h2>Browse smarter</h2>");
-        sb.AppendLine("            <p>Use the left filter rail to narrow by name, kind, or namespace. Namespace sections below open in batches so large modules stay easier to scan.</p>");
-        sb.AppendLine("            <div class=\"overview-stat-grid\">");
-        AppendOverviewStat(sb, "Entries", types.Count.ToString("N0", CultureInfo.InvariantCulture));
-        AppendOverviewStat(sb, "Namespaces", namespaceGroups.Count.ToString("N0", CultureInfo.InvariantCulture));
-        AppendOverviewStat(sb, "Aliases", aliasCount.ToString("N0", CultureInfo.InvariantCulture));
-        if (primaryKindCount > 0)
-            AppendOverviewStat(sb, primaryKindLabel + "s", primaryKindCount.ToString("N0", CultureInfo.InvariantCulture));
-        sb.AppendLine("            </div>");
-        sb.AppendLine("          </section>");
-        if (namespaceGroups.Count > 0)
-        {
-            sb.AppendLine("          <section class=\"api-overview-rail-card api-overview-rail-card--jump\">");
-            sb.AppendLine("            <p class=\"api-overview-rail-eyebrow\">Jump To</p>");
-            sb.AppendLine("            <h3>Namespaces</h3>");
-            sb.AppendLine("            <div class=\"overview-jump-list\">");
-            foreach (var group in namespaceGroups.Take(10))
-            {
-                var anchor = BuildNamespaceAnchorId(group.Key);
-                var nsLabel = System.Web.HttpUtility.HtmlEncode(group.Key);
-                sb.AppendLine($"              <a href=\"#{anchor}\" class=\"overview-jump-link\">{nsLabel}<span>{group.Count().ToString("N0", CultureInfo.InvariantCulture)}</span></a>");
-            }
-            sb.AppendLine("            </div>");
-            sb.AppendLine("          </section>");
-        }
-        sb.AppendLine("        </aside>");
         sb.AppendLine("      </div>");
         sb.AppendLine("    </div>");
         return sb.ToString().TrimEnd();
@@ -1157,9 +1121,12 @@ private static void AppendOverviewNamespaceGroup(
             var chipIcon = RenderApiGlyphSpan("chip-icon", "chip-icon-glyph", GetTypeIcon(type.Kind));
             var aliasAttr = BuildAliasTitleAttribute(type);
             var overflowAttr = hasOverflow && index >= visibleLimit ? " data-overview-extra hidden" : string.Empty;
+            var freshnessBadge = BuildFreshnessBadgeHtml(type.Freshness, "type-chip-freshness");
             sb.AppendLine($"            <a href=\"{chipHref}\" class=\"type-chip {kind}\" data-search=\"{searchAttr}\" data-kind=\"{kind}\" data-namespace=\"{nsValue}\"{aliasAttr}{overflowAttr}>");
             sb.AppendLine($"              {chipIcon}");
             sb.AppendLine($"              <span class=\"chip-name\">{System.Web.HttpUtility.HtmlEncode(displayName)}</span>");
+            if (!string.IsNullOrWhiteSpace(freshnessBadge))
+                sb.AppendLine($"              {freshnessBadge}");
             AppendAliasInlineMeta(sb, type, "type-chip-meta", "type-chip-aliases");
             sb.AppendLine("            </a>");
         }
@@ -1174,17 +1141,6 @@ private static void AppendOverviewNamespaceGroup(
         sb.AppendLine("        </div>");
     }
 
-    private static void AppendOverviewStat(StringBuilder sb, string label, string value)
-    {
-        if (string.IsNullOrWhiteSpace(label) || string.IsNullOrWhiteSpace(value))
-            return;
-
-        sb.AppendLine("              <div class=\"overview-stat\">");
-        sb.AppendLine($"                <span class=\"overview-stat-label\">{System.Web.HttpUtility.HtmlEncode(label)}</span>");
-        sb.AppendLine($"                <strong class=\"overview-stat-value\">{System.Web.HttpUtility.HtmlEncode(value)}</strong>");
-        sb.AppendLine("              </div>");
-    }
-
     private static string BuildNamespaceAnchorId(string namespaceName)
     {
         var normalized = string.IsNullOrWhiteSpace(namespaceName) ? "global" : namespaceName.Trim().ToLowerInvariant();
@@ -1246,6 +1202,21 @@ private static string ResolvePrimaryKindLabel(IReadOnlyList<ApiTypeModel> types)
             : GetKindLabel(distinctKinds[0], 0).Split(' ', 2, StringSplitOptions.RemoveEmptyEntries)[0];
     }
 
+    private static string BuildFreshnessBadgeHtml(ApiFreshnessModel? freshness, string cssClass)
+    {
+        if (freshness is null)
+            return string.Empty;
+
+        var status = (freshness.Status ?? string.Empty).Trim().ToLowerInvariant();
+        if (!status.Equals("new", StringComparison.Ordinal) &&
+            !status.Equals("updated", StringComparison.Ordinal))
+            return string.Empty;
+
+        var label = status.Equals("new", StringComparison.Ordinal) ? "New" : "Updated";
+        var title = System.Web.HttpUtility.HtmlAttributeEncode(RenderFreshnessText(freshness));
+        return $"<span class=\"freshness-badge {System.Web.HttpUtility.HtmlEncode(status)} {System.Web.HttpUtility.HtmlEncode(cssClass)}\" title=\"{title}\">{System.Web.HttpUtility.HtmlEncode(label)}</span>";
+    }
+
     private static void AppendAliasInlineMeta(StringBuilder sb, ApiTypeModel type, string wrapperClass, string aliasesClass)
     {
         var aliases = type.Aliases
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.Parse.PowerShellExamples.cs b/PowerForge.Web/Services/WebApiDocsGenerator.Parse.PowerShellExamples.cs
index 9e17ab7d..48409058 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.Parse.PowerShellExamples.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.Parse.PowerShellExamples.cs
@@ -1,14 +1,74 @@
 using System.Text;
 using System.Text.RegularExpressions;
+using System.Security.Cryptography;
 
 namespace PowerForge.Web;
 
 public static partial class WebApiDocsGenerator
 {
+    private sealed record GeneratedPowerShellExample(string Label, string Code);
+    private sealed record ImportedPowerShellExampleCandidate(string Command, string Snippet, string FilePath, int Score, int LineNumber);
+    private sealed record PowerShellPlaybackAssetHealth(bool HasUnsupportedSidecars, bool HasOversizedAssets, bool HasStaleAssets);
+    private const int GeneratedExampleNoRequiredParameterBonus = 14;
+    private const int GeneratedExampleSingleRequiredTargetScore = 36;
+    private const int GeneratedExampleRequiredCountPenalty = 10;
+    private const int GeneratedExampleSimpleRequiredSetBonus = 8;
+    private const int GeneratedExampleLargeRequiredSetPenalty = 8;
+    private const int GeneratedExampleFriendlyParameterBonus = 12;
+    private const int GeneratedExampleUnfriendlyParameterPenalty = 16;
+    private const int GeneratedExampleSpecialParameterValueBonus = 8;
+    private const int GeneratedExampleSwitchPenalty = 6;
+    private const int GeneratedExamplePreferredNameBonus = 30;
+    private const int GeneratedExamplePreferredSuffixBonus = 22;
+    private const int GeneratedExampleAdvancedObjectPenalty = 28;
+    private const int GeneratedExampleCommonParameterPenalty = 40;
+    private const long RecommendedPowerShellPlaybackAssetMaxBytes = 2 * 1024 * 1024;
+    private const long RecommendedPowerShellPlaybackPosterMaxBytes = 1024 * 1024;
+    private static readonly string[] SupportedPowerShellPlaybackExtensions = [".cast", ".asciinema"];
+    private static readonly string[] SupportedPowerShellPlaybackPosterExtensions = [".png", ".jpg", ".jpeg", ".webp"];
+    private static readonly string[] UnsupportedPowerShellPlaybackSidecarExtensions = [".gif", ".mp4", ".webm", ".mov", ".avi", ".mkv", ".bmp", ".tif", ".tiff", ".svg"];
+    private static readonly HashSet<string> FriendlyPowerShellExampleTypes = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "String",
+        "Int32",
+        "int",
+        "Int64",
+        "long",
+        "UInt32",
+        "uint",
+        "UInt64",
+        "ulong",
+        "Int16",
+        "short",
+        "UInt16",
+        "ushort",
+        "Byte",
+        "SByte",
+        "Double",
+        "double",
+        "Single",
+        "float",
+        "Decimal",
+        "decimal",
+        "Boolean",
+        "Bool",
+        "Guid",
+        "Uri",
+        "DateTime",
+        "Hashtable",
+        "IDictionary",
+        "ScriptBlock",
+        "SwitchParameter"
+    };
+
     private static readonly Regex PowerShellCommandTokenRegex = new(
         @"\b[A-Za-z][A-Za-z0-9]*-[A-Za-z0-9][A-Za-z0-9_.-]*\b",
         RegexOptions.Compiled | RegexOptions.CultureInvariant,
         RegexTimeout);
+    private static readonly Regex PowerShellCultureFolderRegex = new(
+        @"^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$",
+        RegexOptions.Compiled | RegexOptions.CultureInvariant | RegexOptions.IgnoreCase,
+        RegexTimeout);
 
     private static void AppendPowerShellFallbackExamples(
         ApiDocModel apiDoc,
@@ -16,6 +76,7 @@ private static void AppendPowerShellFallbackExamples(
         string resolvedHelpPath,
         string? manifestPath,
         WebApiDocsOptions options,
+        WebApiDocsPowerShellExampleValidationResult? validationResult,
         List<string> warnings)
     {
         if (apiDoc is null || options is null || !options.GeneratePowerShellFallbackExamples)
@@ -34,34 +95,49 @@ private static void AppendPowerShellFallbackExamples(
         var commandNames = commandTypes.Select(type => type.Name).ToArray();
         var files = ResolvePowerShellExampleScriptFiles(inputHelpPath, resolvedHelpPath, manifestPath, options, warnings);
         var snippetsByCommand = CollectPowerShellExamplesFromScripts(files, commandNames, limit, warnings);
+        var validationByFile = BuildPowerShellExampleValidationLookup(validationResult);
+        var inspectedPlaybackMediaFiles = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
 
         foreach (var type in commandTypes)
         {
             if (snippetsByCommand.TryGetValue(type.Name, out var snippets) && snippets.Count > 0)
             {
+                var emittedArtifactPaths = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
                 foreach (var snippet in snippets.Take(limit))
                 {
                     type.Examples.Add(new ApiExampleModel
                     {
                         Kind = "code",
-                        Text = snippet
+                        Text = snippet.Snippet,
+                        Origin = ApiExampleOrigins.ImportedScript
                     });
+
+                    var mediaExample = BuildPowerShellImportedExampleMedia(
+                        snippet.FilePath,
+                        options,
+                        validationByFile,
+                        inspectedPlaybackMediaFiles,
+                        emittedArtifactPaths,
+                        warnings);
+                    if (mediaExample is not null)
+                        type.Examples.Add(mediaExample);
                 }
                 continue;
             }
 
-            var fallback = BuildGeneratedPowerShellExample(type);
-            if (!string.IsNullOrWhiteSpace(fallback))
+            foreach (var fallback in BuildGeneratedPowerShellExamples(type, limit))
             {
                 type.Examples.Add(new ApiExampleModel
                 {
                     Kind = "text",
-                    Text = "Generated fallback example from command syntax."
+                    Text = fallback.Label,
+                    Origin = ApiExampleOrigins.GeneratedFallback
                 });
                 type.Examples.Add(new ApiExampleModel
                 {
                     Kind = "code",
-                    Text = fallback
+                    Text = fallback.Code,
+                    Origin = ApiExampleOrigins.GeneratedFallback
                 });
             }
         }
@@ -122,8 +198,12 @@ private static IReadOnlyList<string> ResolvePowerShellExampleScriptFiles(
         {
             roots.Add(Path.GetFullPath(helpDir));
             var parent = Directory.GetParent(helpDir);
-            if (parent is not null && parent.Exists)
+            if (parent is not null &&
+                parent.Exists &&
+                ShouldProbePowerShellHelpParentDirectory(helpDir))
+            {
                 roots.Add(parent.FullName);
+            }
         }
 
         if (!string.IsNullOrWhiteSpace(manifestPath))
@@ -152,14 +232,31 @@ private static IReadOnlyList<string> ResolvePowerShellExampleScriptFiles(
         return files.OrderBy(static f => f, StringComparer.OrdinalIgnoreCase).ToArray();
     }
 
-    private static Dictionary<string, List<string>> CollectPowerShellExamplesFromScripts(
+    private static bool ShouldProbePowerShellHelpParentDirectory(string helpDirectory)
+    {
+        if (string.IsNullOrWhiteSpace(helpDirectory))
+            return false;
+
+        var folderName = Path.GetFileName(helpDirectory.TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar));
+        if (string.IsNullOrWhiteSpace(folderName))
+            return false;
+
+        return folderName.Equals("help", StringComparison.OrdinalIgnoreCase) ||
+               folderName.Equals("docs", StringComparison.OrdinalIgnoreCase) ||
+               folderName.Equals("reference", StringComparison.OrdinalIgnoreCase) ||
+               PowerShellCultureFolderRegex.IsMatch(folderName);
+    }
+
+    private static Dictionary<string, List<ImportedPowerShellExampleCandidate>> CollectPowerShellExamplesFromScripts(
         IReadOnlyList<string> files,
         IReadOnlyList<string> commandNames,
         int maxPerCommand,
         List<string> warnings)
     {
-        var results = new Dictionary<string, List<string>>(StringComparer.OrdinalIgnoreCase);
         var dedupe = new Dictionary<string, HashSet<string>>(StringComparer.OrdinalIgnoreCase);
+        var candidates = new Dictionary<string, List<ImportedPowerShellExampleCandidate>>(StringComparer.OrdinalIgnoreCase);
+        var limitPerCommand = Math.Max(1, maxPerCommand);
+        var results = new Dictionary<string, List<ImportedPowerShellExampleCandidate>>(StringComparer.OrdinalIgnoreCase);
         if (files.Count == 0 || commandNames.Count == 0)
             return results;
 
@@ -180,21 +277,11 @@ private static Dictionary<string, List<string>> CollectPowerShellExamplesFromScr
             for (var i = 0; i < lines.Length; i++)
             {
                 var line = lines[i];
-                if (string.IsNullOrWhiteSpace(line))
-                    continue;
-                var trimmed = line.TrimStart();
-                if (trimmed.StartsWith("#", StringComparison.Ordinal))
-                    continue;
-
-                foreach (Match match in PowerShellCommandTokenRegex.Matches(line))
+                foreach (var command in EnumeratePowerShellCommandTokensFromLine(line))
                 {
-                    var command = match.Value;
                     if (!commands.Contains(command))
                         continue;
 
-                    if (results.TryGetValue(command, out var existing) && existing.Count >= maxPerCommand)
-                        continue;
-
                     var snippet = CapturePowerShellExampleSnippet(lines, i);
                     if (string.IsNullOrWhiteSpace(snippet))
                         continue;
@@ -208,20 +295,574 @@ private static Dictionary<string, List<string>> CollectPowerShellExamplesFromScr
                     if (!dedupeSet.Add(snippet))
                         continue;
 
-                    if (!results.TryGetValue(command, out var snippets))
+                    if (!candidates.TryGetValue(command, out var commandCandidates))
                     {
-                        snippets = new List<string>();
-                        results[command] = snippets;
+                        commandCandidates = new List<ImportedPowerShellExampleCandidate>();
+                        candidates[command] = commandCandidates;
                     }
 
-                    snippets.Add(snippet);
+                    commandCandidates.Add(new ImportedPowerShellExampleCandidate(
+                        command,
+                        snippet,
+                        file,
+                        GetImportedPowerShellExampleScore(command, file, snippet, i),
+                        i));
+
+                    if (commandCandidates.Count > limitPerCommand * 3)
+                    {
+                        commandCandidates = commandCandidates
+                            .OrderByDescending(static candidate => candidate.Score)
+                            .ThenBy(static candidate => candidate.FilePath, StringComparer.OrdinalIgnoreCase)
+                            .ThenBy(static candidate => candidate.LineNumber)
+                            .Take(limitPerCommand)
+                            .ToList();
+                        candidates[command] = commandCandidates;
+                    }
                 }
             }
         }
 
+        foreach (var pair in candidates)
+        {
+            results[pair.Key] = pair.Value
+                .OrderByDescending(static candidate => candidate.Score)
+                .ThenBy(static candidate => candidate.FilePath, StringComparer.OrdinalIgnoreCase)
+                .ThenBy(static candidate => candidate.LineNumber)
+                .Take(limitPerCommand)
+                .ToList();
+        }
+
         return results;
     }
 
+    private static Dictionary<string, WebApiDocsPowerShellExampleFileValidationResult> BuildPowerShellExampleValidationLookup(
+        WebApiDocsPowerShellExampleValidationResult? validationResult)
+    {
+        var lookup = new Dictionary<string, WebApiDocsPowerShellExampleFileValidationResult>(StringComparer.OrdinalIgnoreCase);
+        if (validationResult?.Files is null || validationResult.Files.Length == 0)
+            return lookup;
+
+        foreach (var file in validationResult.Files)
+        {
+            if (file is null || string.IsNullOrWhiteSpace(file.FilePath))
+                continue;
+
+            lookup[Path.GetFullPath(file.FilePath)] = file;
+        }
+
+        return lookup;
+    }
+
+    private static ApiExampleModel? BuildPowerShellImportedExampleMedia(
+        string? exampleFilePath,
+        WebApiDocsOptions options,
+        IReadOnlyDictionary<string, WebApiDocsPowerShellExampleFileValidationResult> validationByFile,
+        ISet<string>? inspectedPlaybackMediaFiles,
+        ISet<string> emittedArtifactPaths,
+        List<string>? warnings)
+    {
+        if (string.IsNullOrWhiteSpace(exampleFilePath) ||
+            options is null ||
+            string.IsNullOrWhiteSpace(options.OutputPath))
+        {
+            return null;
+        }
+
+        var normalizedExamplePath = Path.GetFullPath(exampleFilePath);
+        var playbackAssetHealth = AnalyzePowerShellImportedPlaybackAssets(normalizedExamplePath, inspectedPlaybackMediaFiles, warnings);
+        var playbackMedia = TryBuildPowerShellImportedPlaybackMedia(
+            normalizedExamplePath,
+            options,
+            playbackAssetHealth,
+            emittedArtifactPaths,
+            warnings);
+        if (playbackMedia is not null)
+            return playbackMedia;
+
+        if (validationByFile is null || validationByFile.Count == 0)
+            return null;
+
+        if (!validationByFile.TryGetValue(normalizedExamplePath, out var validationFile) ||
+            validationFile.ExecutionSucceeded != true ||
+            string.IsNullOrWhiteSpace(validationFile.ExecutionArtifactPath))
+        {
+            return null;
+        }
+
+        var artifactPath = Path.GetFullPath(validationFile.ExecutionArtifactPath);
+        if (!File.Exists(artifactPath))
+            return null;
+        var stagedArtifactUrl = TryStageApiExampleAsset(
+            options.OutputPath,
+            options.BaseUrl,
+            artifactPath,
+            emittedAssetPaths: null,
+            warnings);
+        if (string.IsNullOrWhiteSpace(stagedArtifactUrl))
+            return null;
+
+        var stagedArtifactPath = TryResolveApiOutputPath(options.OutputPath, stagedArtifactUrl, options.BaseUrl) ?? artifactPath;
+        if (emittedArtifactPaths is not null && !emittedArtifactPaths.Add(stagedArtifactPath))
+            return null;
+
+        var artifactUrl = stagedArtifactUrl;
+
+        DateTimeOffset? capturedAtUtc = null;
+        DateTimeOffset? sourceUpdatedAtUtc = null;
+        TryReadFileTimestampUtc(stagedArtifactPath, out capturedAtUtc);
+        TryReadFileTimestampUtc(normalizedExamplePath, out sourceUpdatedAtUtc);
+
+        return new ApiExampleModel
+        {
+            Kind = "media",
+            Origin = ApiExampleOrigins.ImportedScript,
+            Media = new ApiExampleMediaModel
+            {
+                Type = "terminal",
+                Url = artifactUrl,
+                Title = "Open execution transcript",
+                Caption = $"Captured terminal transcript from executing {Path.GetFileName(exampleFilePath)}.",
+                Alt = "Execution transcript",
+                MimeType = "text/plain",
+                SourcePath = normalizedExamplePath,
+                AssetPath = stagedArtifactPath,
+                CapturedAtUtc = capturedAtUtc,
+                SourceUpdatedAtUtc = sourceUpdatedAtUtc
+            }
+        };
+    }
+
+    private static string? TryConvertApiOutputPathToRoute(string outputPath, string? baseUrl, string filePath)
+    {
+        if (string.IsNullOrWhiteSpace(outputPath) || string.IsNullOrWhiteSpace(filePath))
+            return null;
+
+        var root = Path.GetFullPath(outputPath);
+        var target = Path.GetFullPath(filePath);
+        var relative = Path.GetRelativePath(root, target);
+        if (string.IsNullOrWhiteSpace(relative) ||
+            relative.StartsWith("..", StringComparison.Ordinal) ||
+            Path.IsPathRooted(relative))
+        {
+            return null;
+        }
+
+        var normalizedBase = NormalizeApiRoute(baseUrl ?? "/api").TrimEnd('/');
+        return normalizedBase + "/" + relative.Replace('\\', '/');
+    }
+
+    private static string? TryResolveApiOutputPath(string outputPath, string route, string? baseUrl)
+    {
+        if (string.IsNullOrWhiteSpace(outputPath) || string.IsNullOrWhiteSpace(route))
+            return null;
+
+        var normalizedBase = NormalizeApiRoute(baseUrl ?? "/api").TrimEnd('/');
+        var normalizedRoute = route.Trim();
+        if (!normalizedRoute.StartsWith(normalizedBase + "/", StringComparison.OrdinalIgnoreCase))
+            return null;
+
+        var relative = normalizedRoute.Substring(normalizedBase.Length + 1).Replace('/', Path.DirectorySeparatorChar);
+        if (string.IsNullOrWhiteSpace(relative))
+            return null;
+
+        return Path.Combine(Path.GetFullPath(outputPath), relative);
+    }
+
+    private static ApiExampleModel? TryBuildPowerShellImportedPlaybackMedia(
+        string exampleFilePath,
+        WebApiDocsOptions options,
+        PowerShellPlaybackAssetHealth playbackAssetHealth,
+        ISet<string>? emittedAssetPaths,
+        List<string>? warnings)
+    {
+        if (string.IsNullOrWhiteSpace(exampleFilePath) || options is null || string.IsNullOrWhiteSpace(options.OutputPath))
+            return null;
+
+        var castPath = ResolvePowerShellExamplePlaybackSidecar(exampleFilePath, SupportedPowerShellPlaybackExtensions);
+        if (string.IsNullOrWhiteSpace(castPath))
+            return null;
+
+        var castUrl = TryStageApiExampleAsset(options.OutputPath, options.BaseUrl, castPath, emittedAssetPaths, warnings);
+        if (string.IsNullOrWhiteSpace(castUrl))
+            return null;
+
+        var posterPath = ResolvePowerShellExamplePlaybackSidecar(exampleFilePath, SupportedPowerShellPlaybackPosterExtensions);
+        var posterUrl = string.IsNullOrWhiteSpace(posterPath)
+            ? null
+            : TryStageApiExampleAsset(options.OutputPath, options.BaseUrl, posterPath, emittedAssetPaths, warnings);
+        DateTimeOffset? capturedAtUtc = null;
+        DateTimeOffset? sourceUpdatedAtUtc = null;
+        TryReadFileTimestampUtc(castPath, out capturedAtUtc);
+        TryReadFileTimestampUtc(exampleFilePath, out sourceUpdatedAtUtc);
+
+        return new ApiExampleModel
+        {
+            Kind = "media",
+            Origin = ApiExampleOrigins.ImportedScript,
+            Media = new ApiExampleMediaModel
+            {
+                Type = "terminal",
+                Url = castUrl,
+                Title = "Open terminal playback",
+                Caption = $"Captured terminal playback for {Path.GetFileName(exampleFilePath)}.",
+                Alt = "Terminal playback",
+                PosterUrl = posterUrl,
+                MimeType = "application/x-asciicast",
+                SourcePath = exampleFilePath,
+                AssetPath = castPath,
+                PosterAssetPath = posterPath,
+                CapturedAtUtc = capturedAtUtc,
+                SourceUpdatedAtUtc = sourceUpdatedAtUtc,
+                HasUnsupportedSidecars = playbackAssetHealth.HasUnsupportedSidecars,
+                HasOversizedAssets = playbackAssetHealth.HasOversizedAssets,
+                HasStaleAssets = playbackAssetHealth.HasStaleAssets
+            }
+        };
+    }
+
+    private static PowerShellPlaybackAssetHealth AnalyzePowerShellImportedPlaybackAssets(
+        string exampleFilePath,
+        ISet<string>? inspectedPlaybackMediaFiles,
+        List<string>? warnings)
+    {
+        if (string.IsNullOrWhiteSpace(exampleFilePath) || warnings is null)
+            return new PowerShellPlaybackAssetHealth(false, false, false);
+
+        var normalizedExamplePath = Path.GetFullPath(exampleFilePath);
+        if (inspectedPlaybackMediaFiles is not null && !inspectedPlaybackMediaFiles.Add(normalizedExamplePath))
+            return new PowerShellPlaybackAssetHealth(false, false, false);
+
+        var hasUnsupportedSidecars = WarnOnUnsupportedPowerShellPlaybackSidecars(normalizedExamplePath, warnings);
+        var hasOversizedAssets = false;
+        var hasStaleAssets = false;
+
+        var castPath = ResolvePowerShellExamplePlaybackSidecar(normalizedExamplePath, SupportedPowerShellPlaybackExtensions);
+        var posterPath = ResolvePowerShellExamplePlaybackSidecar(normalizedExamplePath, SupportedPowerShellPlaybackPosterExtensions);
+        if (string.IsNullOrWhiteSpace(castPath))
+            return new PowerShellPlaybackAssetHealth(hasUnsupportedSidecars, false, false);
+
+        hasOversizedAssets |= WarnOnOversizedPowerShellPlaybackAsset(
+            castPath,
+            RecommendedPowerShellPlaybackAssetMaxBytes,
+            "playback sidecar",
+            warnings);
+        hasStaleAssets |= WarnOnStalePowerShellPlaybackAsset(
+            normalizedExamplePath,
+            castPath,
+            "playback sidecar",
+            warnings);
+
+        if (string.IsNullOrWhiteSpace(posterPath))
+            return new PowerShellPlaybackAssetHealth(hasUnsupportedSidecars, hasOversizedAssets, hasStaleAssets);
+
+        hasOversizedAssets |= WarnOnOversizedPowerShellPlaybackAsset(
+            posterPath,
+            RecommendedPowerShellPlaybackPosterMaxBytes,
+            "playback poster",
+            warnings);
+
+        var referencePath = File.GetLastWriteTimeUtc(castPath) > File.GetLastWriteTimeUtc(normalizedExamplePath)
+            ? castPath
+            : normalizedExamplePath;
+        hasStaleAssets |= WarnOnStalePowerShellPlaybackAsset(
+            referencePath,
+            posterPath,
+            "playback poster",
+            warnings);
+
+        return new PowerShellPlaybackAssetHealth(hasUnsupportedSidecars, hasOversizedAssets, hasStaleAssets);
+    }
+
+    private static bool WarnOnUnsupportedPowerShellPlaybackSidecars(
+        string exampleFilePath,
+        List<string> warnings)
+    {
+        var directory = Path.GetDirectoryName(exampleFilePath);
+        var baseName = Path.GetFileNameWithoutExtension(exampleFilePath);
+        if (string.IsNullOrWhiteSpace(directory) || string.IsNullOrWhiteSpace(baseName))
+            return false;
+
+        var found = false;
+
+        foreach (var extension in UnsupportedPowerShellPlaybackSidecarExtensions)
+        {
+            var candidate = Path.Combine(directory, baseName + extension);
+            if (!File.Exists(candidate))
+                continue;
+
+            found = true;
+
+            warnings.Add(
+                $"API docs PowerShell coverage: unsupported playback sidecar '{Path.GetFileName(candidate)}'. " +
+                $"Supported playback assets are {string.Join(", ", SupportedPowerShellPlaybackExtensions)} with poster sidecars {string.Join(", ", SupportedPowerShellPlaybackPosterExtensions)}.");
+        }
+
+        return found;
+    }
+
+    private static bool WarnOnOversizedPowerShellPlaybackAsset(
+        string assetPath,
+        long recommendedMaxBytes,
+        string assetLabel,
+        List<string> warnings)
+    {
+        if (string.IsNullOrWhiteSpace(assetPath) || recommendedMaxBytes <= 0 || warnings is null)
+            return false;
+
+        try
+        {
+            var file = new FileInfo(assetPath);
+            if (!file.Exists || file.Length <= recommendedMaxBytes)
+                return false;
+
+            warnings.Add(
+                $"API docs PowerShell coverage: {assetLabel} '{file.Name}' is {FormatByteCount(file.Length)}, above the recommended {FormatByteCount(recommendedMaxBytes)}. " +
+                "Consider trimming or recompressing it to keep API pages lean.");
+            return true;
+        }
+        catch (Exception ex)
+        {
+            warnings.Add($"API docs PowerShell coverage: failed to inspect playback asset '{Path.GetFileName(assetPath)}' ({ex.GetType().Name}: {ex.Message})");
+            return false;
+        }
+    }
+
+    private static bool WarnOnStalePowerShellPlaybackAsset(
+        string referencePath,
+        string assetPath,
+        string assetLabel,
+        List<string> warnings)
+    {
+        if (string.IsNullOrWhiteSpace(referencePath) || string.IsNullOrWhiteSpace(assetPath) || warnings is null)
+            return false;
+        if (!File.Exists(referencePath) || !File.Exists(assetPath))
+            return false;
+
+        var referenceTimestamp = File.GetLastWriteTimeUtc(referencePath);
+        var assetTimestamp = File.GetLastWriteTimeUtc(assetPath);
+        if (assetTimestamp >= referenceTimestamp)
+            return false;
+
+        warnings.Add(
+            $"API docs PowerShell coverage: {assetLabel} '{Path.GetFileName(assetPath)}' looks stale because it is older than '{Path.GetFileName(referencePath)}'. " +
+            "Refresh the captured media so it matches the current example script.");
+        return true;
+    }
+
+    private static string FormatByteCount(long bytes)
+    {
+        if (bytes < 1024)
+            return $"{bytes} B";
+
+        var kib = bytes / 1024d;
+        if (kib < 1024d)
+            return $"{Math.Round(kib, 1, MidpointRounding.AwayFromZero):0.#} KiB";
+
+        var mib = kib / 1024d;
+        return $"{Math.Round(mib, 1, MidpointRounding.AwayFromZero):0.#} MiB";
+    }
+
+    private static bool TryReadFileTimestampUtc(string? filePath, out DateTimeOffset? timestampUtc)
+    {
+        timestampUtc = null;
+        if (string.IsNullOrWhiteSpace(filePath) || !File.Exists(filePath))
+            return false;
+
+        try
+        {
+            timestampUtc = new DateTimeOffset(File.GetLastWriteTimeUtc(filePath), TimeSpan.Zero);
+            return true;
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    private static string? ResolvePowerShellExamplePlaybackSidecar(string exampleFilePath, params string[] extensions)
+    {
+        if (string.IsNullOrWhiteSpace(exampleFilePath) || extensions is null || extensions.Length == 0)
+            return null;
+
+        var directory = Path.GetDirectoryName(exampleFilePath);
+        var baseName = Path.GetFileNameWithoutExtension(exampleFilePath);
+        if (string.IsNullOrWhiteSpace(directory) || string.IsNullOrWhiteSpace(baseName))
+            return null;
+
+        foreach (var extension in extensions)
+        {
+            if (string.IsNullOrWhiteSpace(extension))
+                continue;
+
+            var normalizedExtension = extension.StartsWith(".", StringComparison.Ordinal) ? extension : "." + extension;
+            var candidate = Path.Combine(directory, baseName + normalizedExtension);
+            if (File.Exists(candidate))
+                return candidate;
+        }
+
+        return null;
+    }
+
+    private static string? TryStageApiExampleAsset(
+        string outputPath,
+        string? baseUrl,
+        string sourceFilePath,
+        ISet<string>? emittedAssetPaths,
+        List<string>? warnings)
+    {
+        if (string.IsNullOrWhiteSpace(outputPath) || string.IsNullOrWhiteSpace(sourceFilePath) || !File.Exists(sourceFilePath))
+            return null;
+
+        try
+        {
+            var sourceFullPath = Path.GetFullPath(sourceFilePath);
+            var outputRoot = Path.GetFullPath(outputPath);
+            var stagedDirectory = Path.Combine(outputRoot, "powershell-example-media");
+            Directory.CreateDirectory(stagedDirectory);
+
+            var extension = Path.GetExtension(sourceFullPath);
+            var baseName = Path.GetFileNameWithoutExtension(sourceFullPath);
+            var fileName = $"{SanitizePowerShellExampleArtifactName(baseName)}-{ComputeStableShortHash(sourceFullPath)}{extension.ToLowerInvariant()}";
+            var destinationPath = Path.Combine(stagedDirectory, fileName);
+
+            if (!File.Exists(destinationPath) ||
+                File.GetLastWriteTimeUtc(sourceFullPath) != File.GetLastWriteTimeUtc(destinationPath))
+            {
+                File.Copy(sourceFullPath, destinationPath, overwrite: true);
+            }
+
+            if (emittedAssetPaths is not null && !emittedAssetPaths.Add(destinationPath))
+            {
+                // Already staged/referenced for this example group; still return the route.
+            }
+
+            return TryConvertApiOutputPathToRoute(outputRoot, baseUrl, destinationPath);
+        }
+        catch (Exception ex)
+        {
+            warnings?.Add($"API docs PowerShell coverage: failed to stage example media asset '{Path.GetFileName(sourceFilePath)}' ({ex.GetType().Name}: {ex.Message})");
+            return null;
+        }
+    }
+
+    private static string ComputeStableShortHash(string value)
+    {
+        var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(value ?? string.Empty));
+        return Convert.ToHexString(bytes[..4]).ToLowerInvariant();
+    }
+
+    private static string[] CollectPowerShellCommandTokensFromFile(string filePath, List<string>? warnings)
+    {
+        if (string.IsNullOrWhiteSpace(filePath))
+            return Array.Empty<string>();
+
+        try
+        {
+            return CollectPowerShellCommandTokens(File.ReadAllLines(filePath));
+        }
+        catch (Exception ex)
+        {
+            warnings?.Add($"API docs PowerShell coverage: skipped PowerShell examples file '{Path.GetFileName(filePath)}' ({ex.GetType().Name}: {ex.Message})");
+            return Array.Empty<string>();
+        }
+    }
+
+    private static string[] CollectPowerShellCommandTokens(IEnumerable<string> lines)
+    {
+        if (lines is null)
+            return Array.Empty<string>();
+
+        return lines
+            .SelectMany(EnumeratePowerShellCommandTokensFromLine)
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(static command => command, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+    }
+
+    private static IEnumerable<string> EnumeratePowerShellCommandTokensFromLine(string? line)
+    {
+        if (string.IsNullOrWhiteSpace(line))
+            yield break;
+
+        var trimmed = line.TrimStart();
+        if (trimmed.StartsWith("#", StringComparison.Ordinal))
+            yield break;
+
+        foreach (Match match in PowerShellCommandTokenRegex.Matches(line))
+        {
+            if (!string.IsNullOrWhiteSpace(match.Value))
+                yield return match.Value;
+        }
+    }
+
+    private static int GetImportedPowerShellExampleScore(string commandName, string filePath, string snippet, int lineNumber)
+    {
+        var score = 0;
+        var normalizedCommand = NormalizePowerShellExampleToken(commandName);
+        var commandNoun = GetPowerShellCommandNoun(commandName);
+        var normalizedNoun = NormalizePowerShellExampleToken(commandNoun);
+        var fileName = Path.GetFileNameWithoutExtension(filePath) ?? string.Empty;
+        var normalizedFileName = NormalizePowerShellExampleToken(fileName);
+        var normalizedPath = NormalizePowerShellExampleToken(filePath.Replace('\\', '/'));
+
+        if (!string.IsNullOrWhiteSpace(normalizedCommand))
+        {
+            if (string.Equals(normalizedFileName, normalizedCommand, StringComparison.Ordinal))
+                score += 140;
+            else if (normalizedFileName.Contains(normalizedCommand, StringComparison.Ordinal))
+                score += 100;
+
+            if (normalizedPath.Contains(normalizedCommand, StringComparison.Ordinal))
+                score += 35;
+        }
+
+        if (!string.IsNullOrWhiteSpace(normalizedNoun))
+        {
+            if (string.Equals(normalizedFileName, normalizedNoun, StringComparison.Ordinal))
+                score += 70;
+            else if (normalizedFileName.Contains(normalizedNoun, StringComparison.Ordinal))
+                score += 35;
+        }
+
+        if (!string.IsNullOrWhiteSpace(snippet))
+        {
+            var firstLine = snippet
+                .Split(new[] { "\r\n", "\n" }, StringSplitOptions.None)
+                .FirstOrDefault(static line => !string.IsNullOrWhiteSpace(line))
+                ?.Trim() ?? string.Empty;
+            if (firstLine.StartsWith(commandName + " ", StringComparison.OrdinalIgnoreCase) ||
+                string.Equals(firstLine, commandName, StringComparison.OrdinalIgnoreCase))
+                score += 18;
+        }
+
+        score -= Math.Max(0, lineNumber);
+        return score;
+    }
+
+    private static string NormalizePowerShellExampleToken(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            return string.Empty;
+
+        var chars = value
+            .Where(static ch => char.IsLetterOrDigit(ch))
+            .Select(static ch => char.ToLowerInvariant(ch))
+            .ToArray();
+        return new string(chars);
+    }
+
+    private static string GetPowerShellCommandNoun(string? commandName)
+    {
+        if (string.IsNullOrWhiteSpace(commandName))
+            return string.Empty;
+
+        var dash = commandName.IndexOf('-', StringComparison.Ordinal);
+        if (dash < 0 || dash + 1 >= commandName.Length)
+            return commandName;
+
+        return commandName[(dash + 1)..];
+    }
+
     private static string CapturePowerShellExampleSnippet(string[] lines, int startIndex)
     {
         if (lines is null || startIndex < 0 || startIndex >= lines.Length)
@@ -253,15 +894,49 @@ private static string CapturePowerShellExampleSnippet(string[] lines, int startI
         return string.Join(Environment.NewLine, snippet).Trim();
     }
 
-    private static string? BuildGeneratedPowerShellExample(ApiTypeModel type)
+    private static IReadOnlyList<GeneratedPowerShellExample> BuildGeneratedPowerShellExamples(ApiTypeModel type, int limit)
     {
-        if (type is null || string.IsNullOrWhiteSpace(type.Name))
-            return null;
+        if (type is null || string.IsNullOrWhiteSpace(type.Name) || limit <= 0)
+            return Array.Empty<GeneratedPowerShellExample>();
+
+        var examples = new List<GeneratedPowerShellExample>();
+        var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var methods = type.Methods
+            .Where(static method => method is not null)
+            .OrderByDescending(GetGeneratedPowerShellExampleScore)
+            .ThenBy(static method => method.Parameters.Count(static p => !p.IsOptional))
+            .ThenBy(static method => method.Parameters.Count)
+            .ThenBy(static method => method.ParameterSetName ?? string.Empty, StringComparer.OrdinalIgnoreCase)
+            .ToList();
+
+        if (methods.Count == 0)
+        {
+            return
+            [
+                new GeneratedPowerShellExample(
+                    "Generated fallback example from command name.",
+                    type.Name.Trim())
+            ];
+        }
 
-        var method = type.Methods
-            .OrderByDescending(static m => m.Parameters.Count(static p => !p.IsOptional))
-            .ThenByDescending(static m => m.Parameters.Count)
-            .FirstOrDefault();
+        foreach (var method in methods)
+        {
+            var code = BuildGeneratedPowerShellExample(type.Name, method);
+            if (string.IsNullOrWhiteSpace(code) || !seen.Add(code))
+                continue;
+
+            examples.Add(new GeneratedPowerShellExample(BuildGeneratedPowerShellExampleLabel(method), code));
+            if (examples.Count >= limit)
+                break;
+        }
+
+        return examples;
+    }
+
+    private static string? BuildGeneratedPowerShellExample(string commandName, ApiMemberModel? method)
+    {
+        if (string.IsNullOrWhiteSpace(commandName))
+            return null;
 
         var parameters = method?.Parameters ?? new List<ApiParameterModel>();
         var picked = parameters
@@ -271,19 +946,16 @@ private static string CapturePowerShellExampleSnippet(string[] lines, int startI
 
         if (picked.Count == 0)
         {
-            var candidate =
-                parameters.FirstOrDefault(p => p.Name.Equals("Path", StringComparison.OrdinalIgnoreCase)) ??
-                parameters.FirstOrDefault(p => p.Name.EndsWith("Path", StringComparison.OrdinalIgnoreCase)) ??
-                parameters.FirstOrDefault(p => p.Name.Equals("ModuleName", StringComparison.OrdinalIgnoreCase)) ??
-                parameters.FirstOrDefault(p => p.Name.Equals("Name", StringComparison.OrdinalIgnoreCase)) ??
-                parameters.FirstOrDefault(p => p.Name.Equals("Id", StringComparison.OrdinalIgnoreCase)) ??
-                parameters.FirstOrDefault();
+            var candidate = parameters
+                .OrderByDescending(GetGeneratedPowerShellExampleParameterScore)
+                .ThenBy(static p => p.Name ?? string.Empty, StringComparer.OrdinalIgnoreCase)
+                .FirstOrDefault();
 
             if (candidate is not null)
                 picked.Add(candidate);
         }
 
-        var parts = new List<string> { type.Name };
+        var parts = new List<string> { commandName };
         foreach (var parameter in picked)
         {
             if (string.IsNullOrWhiteSpace(parameter.Name))
@@ -298,6 +970,126 @@ private static string CapturePowerShellExampleSnippet(string[] lines, int startI
         return string.Join(" ", parts.Where(static p => !string.IsNullOrWhiteSpace(p)));
     }
 
+    private static string BuildGeneratedPowerShellExampleLabel(ApiMemberModel method)
+    {
+        if (!string.IsNullOrWhiteSpace(method?.ParameterSetName))
+            return $"Generated fallback example from parameter set '{method.ParameterSetName}'.";
+        return "Generated fallback example from command syntax.";
+    }
+
+    private static int GetGeneratedPowerShellExampleScore(ApiMemberModel method)
+    {
+        if (method is null)
+            return int.MinValue;
+
+        var parameters = method.Parameters
+            .Where(static parameter => parameter is not null)
+            .ToList();
+        var required = parameters.Where(static p => !p.IsOptional).ToList();
+        var optional = parameters.Where(static p => p.IsOptional).ToList();
+        var score = 0;
+
+        // Prefer parameter sets that read like a quick-start invocation: one clear required value,
+        // a small required surface area, and human-friendly parameter types.
+        if (required.Count == 0)
+        {
+            score += GeneratedExampleNoRequiredParameterBonus;
+        }
+        else
+        {
+            score += Math.Max(0, GeneratedExampleSingleRequiredTargetScore - Math.Abs(required.Count - 1) * GeneratedExampleRequiredCountPenalty);
+        }
+
+        if (required.Count <= 3)
+            score += GeneratedExampleSimpleRequiredSetBonus;
+        // Four required parameters is intentionally neutral; beyond that we start penalizing complexity.
+        if (required.Count > 4)
+            score -= (required.Count - 4) * GeneratedExampleLargeRequiredSetPenalty;
+
+        score += required.Sum(GetGeneratedPowerShellExampleParameterScore);
+        score += optional
+            .Select(GetGeneratedPowerShellExampleParameterScore)
+            .DefaultIfEmpty(0)
+            .Max() / 3;
+
+        return score;
+    }
+
+    private static int GetGeneratedPowerShellExampleParameterScore(ApiParameterModel? parameter)
+    {
+        if (parameter is null)
+            return int.MinValue;
+
+        var score = 0;
+        var name = parameter.Name?.Trim() ?? string.Empty;
+        var type = parameter.Type?.Trim() ?? string.Empty;
+
+        if (!string.IsNullOrWhiteSpace(name))
+        {
+            if (name.Equals("Name", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Path", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("LiteralPath", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Id", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Mode", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Uri", StringComparison.OrdinalIgnoreCase))
+                score += GeneratedExamplePreferredNameBonus;
+            else if (name.EndsWith("Name", StringComparison.OrdinalIgnoreCase) ||
+                     name.EndsWith("Path", StringComparison.OrdinalIgnoreCase) ||
+                     name.EndsWith("Id", StringComparison.OrdinalIgnoreCase) ||
+                     name.EndsWith("Uri", StringComparison.OrdinalIgnoreCase))
+                score += GeneratedExamplePreferredSuffixBonus;
+
+            if (name.Equals("InputObject", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Credential", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Session", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("CimSession", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("PSSession", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("ScriptBlock", StringComparison.OrdinalIgnoreCase))
+                score -= GeneratedExampleAdvancedObjectPenalty;
+
+            if (name.Equals("WhatIf", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Confirm", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Verbose", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("Debug", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("ErrorAction", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("WarningAction", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("InformationAction", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("ProgressAction", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("OutVariable", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("OutBuffer", StringComparison.OrdinalIgnoreCase) ||
+                name.Equals("PipelineVariable", StringComparison.OrdinalIgnoreCase))
+                score -= GeneratedExampleCommonParameterPenalty;
+        }
+
+        if (IsPowerShellFriendlyExampleType(type))
+            score += GeneratedExampleFriendlyParameterBonus;
+        else if (!string.IsNullOrWhiteSpace(type))
+            score -= GeneratedExampleUnfriendlyParameterPenalty;
+
+        if (parameter.PossibleValues.Count > 0)
+            score += GeneratedExampleSpecialParameterValueBonus;
+        // ScriptBlock is syntactically valid but usually too complex for a friendly default example,
+        // so a parameter literally named ScriptBlock is still scored down even though the type is "friendly".
+        if (IsPowerShellSwitchParameter(type))
+            score -= GeneratedExampleSwitchPenalty;
+
+        return score;
+    }
+
+    private static bool IsPowerShellFriendlyExampleType(string? typeName)
+    {
+        if (string.IsNullOrWhiteSpace(typeName))
+            return true;
+
+        var type = typeName.Trim();
+        if (type.EndsWith("[]", StringComparison.Ordinal))
+            return IsPowerShellFriendlyExampleType(type[..^2]);
+
+        return FriendlyPowerShellExampleTypes.Contains(type) ||
+               type.EndsWith(".String", StringComparison.OrdinalIgnoreCase) ||
+               type.EndsWith(".SwitchParameter", StringComparison.OrdinalIgnoreCase);
+    }
+
     private static bool IsPowerShellSwitchParameter(string? typeName)
         => !string.IsNullOrWhiteSpace(typeName) &&
            (typeName.Equals("SwitchParameter", StringComparison.OrdinalIgnoreCase) ||
@@ -340,9 +1132,16 @@ private static string GetPowerShellSampleValue(string parameterName, string? typ
         if (type.Equals("Boolean", StringComparison.OrdinalIgnoreCase) || type.Equals("Bool", StringComparison.OrdinalIgnoreCase))
             return "$true";
         if (type.Equals("Int32", StringComparison.OrdinalIgnoreCase) || type.Equals("Int64", StringComparison.OrdinalIgnoreCase) ||
-            type.Equals("UInt32", StringComparison.OrdinalIgnoreCase) || type.Equals("UInt64", StringComparison.OrdinalIgnoreCase))
+            type.Equals("UInt32", StringComparison.OrdinalIgnoreCase) || type.Equals("UInt64", StringComparison.OrdinalIgnoreCase) ||
+            type.Equals("Int16", StringComparison.OrdinalIgnoreCase) || type.Equals("UInt16", StringComparison.OrdinalIgnoreCase) ||
+            type.Equals("Byte", StringComparison.OrdinalIgnoreCase) || type.Equals("SByte", StringComparison.OrdinalIgnoreCase) ||
+            type.Equals("int", StringComparison.OrdinalIgnoreCase) || type.Equals("long", StringComparison.OrdinalIgnoreCase) ||
+            type.Equals("uint", StringComparison.OrdinalIgnoreCase) || type.Equals("ulong", StringComparison.OrdinalIgnoreCase) ||
+            type.Equals("short", StringComparison.OrdinalIgnoreCase) || type.Equals("ushort", StringComparison.OrdinalIgnoreCase) ||
+            type.Equals("byte", StringComparison.OrdinalIgnoreCase) || type.Equals("sbyte", StringComparison.OrdinalIgnoreCase))
             return "1";
-        if (type.Equals("Double", StringComparison.OrdinalIgnoreCase) || type.Equals("Single", StringComparison.OrdinalIgnoreCase) || type.Equals("Decimal", StringComparison.OrdinalIgnoreCase))
+        if (type.Equals("Double", StringComparison.OrdinalIgnoreCase) || type.Equals("Single", StringComparison.OrdinalIgnoreCase) || type.Equals("Decimal", StringComparison.OrdinalIgnoreCase) ||
+            type.Equals("double", StringComparison.OrdinalIgnoreCase) || type.Equals("float", StringComparison.OrdinalIgnoreCase) || type.Equals("decimal", StringComparison.OrdinalIgnoreCase))
             return "1";
         if (type.Equals("DateTime", StringComparison.OrdinalIgnoreCase))
             return "'2000-01-01'";
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.Parse.cs b/PowerForge.Web/Services/WebApiDocsGenerator.Parse.cs
index 8210e567..f0f55508 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.Parse.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.Parse.cs
@@ -157,6 +157,7 @@ private static ApiDocModel ParsePowerShellHelp(string helpPath, List<string> war
                 Summary = summary,
                 Remarks = remarks
             };
+            type.OriginFiles.Add(resolved);
             foreach (var alias in commandAliases)
                 type.Aliases.Add(alias);
             foreach (var inputType in inputTypes)
@@ -240,7 +241,14 @@ private static ApiDocModel ParsePowerShellHelp(string helpPath, List<string> war
             apiDoc.Types[type.FullName] = type;
         }
 
-        AppendPowerShellFallbackExamples(apiDoc, helpPath, resolved, manifestPath, options, warnings);
+        AppendPowerShellFallbackExamples(
+            apiDoc,
+            helpPath,
+            resolved,
+            manifestPath,
+            options,
+            options.PowerShellExampleValidationResult,
+            warnings);
         AppendPowerShellAboutTopics(apiDoc, helpPath, resolved, moduleName ?? string.Empty, manifestPath, warnings);
         return apiDoc;
     }
@@ -865,7 +873,8 @@ private static void AppendPowerShellExamples(
                 type.Examples.Add(new ApiExampleModel
                 {
                     Kind = "heading",
-                    Text = title
+                    Text = title,
+                    Origin = ApiExampleOrigins.AuthoredHelp
                 });
             }
 
@@ -874,7 +883,8 @@ private static void AppendPowerShellExamples(
                 type.Examples.Add(new ApiExampleModel
                 {
                     Kind = "text",
-                    Text = introduction
+                    Text = introduction,
+                    Origin = ApiExampleOrigins.AuthoredHelp
                 });
             }
 
@@ -888,7 +898,8 @@ private static void AppendPowerShellExamples(
                 type.Examples.Add(new ApiExampleModel
                 {
                     Kind = "code",
-                    Text = code
+                    Text = code,
+                    Origin = ApiExampleOrigins.AuthoredHelp
                 });
             }
 
@@ -897,7 +908,8 @@ private static void AppendPowerShellExamples(
                 type.Examples.Add(new ApiExampleModel
                 {
                     Kind = "text",
-                    Text = remark
+                    Text = remark,
+                    Origin = ApiExampleOrigins.AuthoredHelp
                 });
             }
 
@@ -908,7 +920,8 @@ private static void AppendPowerShellExamples(
                     type.Examples.Add(new ApiExampleModel
                     {
                         Kind = "text",
-                        Text = remark
+                        Text = remark,
+                        Origin = ApiExampleOrigins.AuthoredHelp
                     });
                 }
             }
@@ -1019,6 +1032,7 @@ private static void AppendPowerShellAboutTopics(
                 Summary = summary,
                 Remarks = remarks
             };
+            type.OriginFiles.Add(file);
 
             apiDoc.Types[type.FullName] = type;
             existing.Add(type.FullName);
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.PowerShellMediaManifest.cs b/PowerForge.Web/Services/WebApiDocsGenerator.PowerShellMediaManifest.cs
new file mode 100644
index 00000000..c213f2d3
--- /dev/null
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.PowerShellMediaManifest.cs
@@ -0,0 +1,114 @@
+namespace PowerForge.Web;
+
+public static partial class WebApiDocsGenerator
+{
+    private static string? WritePowerShellExampleMediaManifest(
+        string outputPath,
+        WebApiDocsOptions options,
+        IReadOnlyList<ApiTypeModel> types,
+        List<string> warnings)
+    {
+        if (string.IsNullOrWhiteSpace(outputPath) || options is null || types is null || warnings is null)
+            return null;
+
+        var entries = types
+            .Where(IsPowerShellCommandType)
+            .SelectMany(type => type.Examples
+                .Where(static example =>
+                    example is not null &&
+                    example.Kind.Equals("media", StringComparison.OrdinalIgnoreCase) &&
+                    string.Equals(example.Origin, ApiExampleOrigins.ImportedScript, StringComparison.OrdinalIgnoreCase) &&
+                    example.Media is not null &&
+                    example.Media.Type.Equals("terminal", StringComparison.OrdinalIgnoreCase) &&
+                    !string.IsNullOrWhiteSpace(example.Media.Url))
+                .Select(example => BuildPowerShellExampleMediaManifestEntry(type, example.Media!, options)))
+            .Where(static entry => entry is not null)
+            .Cast<Dictionary<string, object?>>()
+            .OrderBy(static entry => entry["commandName"]?.ToString(), StringComparer.OrdinalIgnoreCase)
+            .ThenBy(static entry => entry["mediaUrl"]?.ToString(), StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+
+        if (entries.Length == 0)
+            return null;
+
+        var manifestPath = Path.Combine(outputPath, "powershell-example-media-manifest.json");
+        try
+        {
+            var payload = new Dictionary<string, object?>
+            {
+                ["generatedAtUtc"] = DateTime.UtcNow.ToString("O"),
+                ["baseUrl"] = NormalizeApiRoute(options.BaseUrl ?? "/api"),
+                ["entryCount"] = entries.Length,
+                ["entries"] = entries
+            };
+            WriteJson(manifestPath, payload);
+            return manifestPath;
+        }
+        catch (Exception ex)
+        {
+            warnings.Add($"API docs PowerShell coverage: failed to write example media manifest '{manifestPath}' ({ex.GetType().Name}: {ex.Message})");
+            return null;
+        }
+    }
+
+    private static Dictionary<string, object?>? BuildPowerShellExampleMediaManifestEntry(
+        ApiTypeModel type,
+        ApiExampleMediaModel media,
+        WebApiDocsOptions options)
+    {
+        if (type is null || media is null || string.IsNullOrWhiteSpace(media.Url))
+            return null;
+
+        return new Dictionary<string, object?>
+        {
+            ["commandName"] = type.Name,
+            ["typeFullName"] = type.FullName,
+            ["typeSlug"] = type.Slug,
+            ["mediaType"] = media.Type,
+            ["mediaUrl"] = media.Url,
+            ["posterUrl"] = media.PosterUrl,
+            ["mimeType"] = media.MimeType,
+            ["sourcePath"] = NormalizePowerShellExampleManifestPath(media.SourcePath, options),
+            ["assetPath"] = NormalizePowerShellExampleManifestPath(media.AssetPath, options),
+            ["posterAssetPath"] = NormalizePowerShellExampleManifestPath(media.PosterAssetPath, options),
+            ["capturedAtUtc"] = media.CapturedAtUtc?.ToString("O"),
+            ["sourceUpdatedAtUtc"] = media.SourceUpdatedAtUtc?.ToString("O"),
+            ["hasPoster"] = !string.IsNullOrWhiteSpace(media.PosterUrl),
+            ["hasUnsupportedSidecars"] = media.HasUnsupportedSidecars,
+            ["hasOversizedAssets"] = media.HasOversizedAssets,
+            ["hasStaleAssets"] = media.HasStaleAssets
+        };
+    }
+
+    private static string? NormalizePowerShellExampleManifestPath(string? path, WebApiDocsOptions options)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return null;
+
+        try
+        {
+            var fullPath = Path.GetFullPath(path);
+            if (!string.IsNullOrWhiteSpace(options.PowerShellExamplesPath))
+            {
+                var examplesRoot = GetValidationExamplesRoot(options.PowerShellExamplesPath) ?? Path.GetFullPath(options.PowerShellExamplesPath);
+                var relativeToExamples = Path.GetRelativePath(examplesRoot, fullPath);
+                if (!relativeToExamples.StartsWith("..", StringComparison.Ordinal) && !Path.IsPathRooted(relativeToExamples))
+                    return relativeToExamples.Replace('\\', '/');
+            }
+
+            if (!string.IsNullOrWhiteSpace(options.OutputPath))
+            {
+                var outputRoot = Path.GetFullPath(options.OutputPath);
+                var relativeToOutput = Path.GetRelativePath(outputRoot, fullPath);
+                if (!relativeToOutput.StartsWith("..", StringComparison.Ordinal) && !Path.IsPathRooted(relativeToOutput))
+                    return relativeToOutput.Replace('\\', '/');
+            }
+
+            return Path.GetFileName(fullPath);
+        }
+        catch
+        {
+            return Path.GetFileName(path);
+        }
+    }
+}
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.PowerShellValidation.cs b/PowerForge.Web/Services/WebApiDocsGenerator.PowerShellValidation.cs
new file mode 100644
index 00000000..5e7dd512
--- /dev/null
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.PowerShellValidation.cs
@@ -0,0 +1,866 @@
+using System.Text;
+using System.Text.Json;
+using PowerForge;
+
+namespace PowerForge.Web;
+
+public static partial class WebApiDocsGenerator
+{
+    /// <summary>
+    /// Validates imported PowerShell example scripts by parsing them with an out-of-process PowerShell parser.
+    /// </summary>
+    /// <param name="options">Validation options.</param>
+    /// <param name="runner">Optional PowerShell runner override.</param>
+    /// <returns>Validation result.</returns>
+    public static WebApiDocsPowerShellExampleValidationResult ValidatePowerShellExamples(
+        WebApiDocsPowerShellExampleValidationOptions options,
+        IPowerShellRunner? runner = null)
+    {
+        if (options is null)
+            throw new ArgumentNullException(nameof(options));
+
+        var warnings = new List<string>();
+        var result = new WebApiDocsPowerShellExampleValidationResult();
+        if (string.IsNullOrWhiteSpace(options.HelpPath))
+        {
+            result.Warnings = new[] { NormalizeWarningCode("API docs PowerShell coverage: helpPath is required for example validation.") };
+            return result;
+        }
+
+        var resolvedHelpPath = ResolvePowerShellHelpFile(options.HelpPath, warnings);
+        result.HelpPath = resolvedHelpPath;
+        if (string.IsNullOrWhiteSpace(resolvedHelpPath) || !File.Exists(resolvedHelpPath))
+        {
+            result.Warnings = warnings
+                .Where(static warning => !string.IsNullOrWhiteSpace(warning))
+                .Select(NormalizeWarningCode)
+                .ToArray();
+            return result;
+        }
+
+        var moduleName = Path.GetFileNameWithoutExtension(resolvedHelpPath) ?? string.Empty;
+        if (moduleName.EndsWith("-help", StringComparison.OrdinalIgnoreCase))
+            moduleName = moduleName[..^5];
+        if (moduleName.EndsWith(".dll", StringComparison.OrdinalIgnoreCase))
+            moduleName = moduleName[..^4];
+
+        var manifestPath = ResolvePowerShellModuleManifestPath(resolvedHelpPath, moduleName, options.PowerShellModuleManifestPath);
+        result.ManifestPath = manifestPath;
+
+        var docsOptions = new WebApiDocsOptions
+        {
+            Type = ApiDocsType.PowerShell,
+            HelpPath = options.HelpPath,
+            PowerShellModuleManifestPath = manifestPath,
+            PowerShellExamplesPath = options.PowerShellExamplesPath,
+            GeneratePowerShellFallbackExamples = false
+        };
+        var apiDoc = ParsePowerShellHelp(options.HelpPath, warnings, docsOptions);
+        var knownCommands = apiDoc.Types.Values
+            .Where(IsPowerShellCommandType)
+            .Select(static type => type.Name)
+            .Where(static name => !string.IsNullOrWhiteSpace(name))
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(static name => name, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+        var knownCommandSet = new HashSet<string>(knownCommands, StringComparer.OrdinalIgnoreCase);
+        result.KnownCommands = knownCommands;
+        result.KnownCommandCount = knownCommands.Length;
+
+        var files = ResolvePowerShellExampleScriptFiles(options.HelpPath, resolvedHelpPath, manifestPath, docsOptions, warnings);
+        result.FileCount = files.Count;
+        result.ExecutionRequested = options.ExecuteMatchedExamples;
+        if (files.Count == 0)
+        {
+            result.ValidationSucceeded = true;
+            if (options.ExecuteMatchedExamples)
+                result.ExecutionCompleted = true;
+            result.Warnings = warnings
+                .Where(static warning => !string.IsNullOrWhiteSpace(warning))
+                .Select(NormalizeWarningCode)
+                .ToArray();
+            return result;
+        }
+
+        var timeoutSeconds = Math.Clamp(options.TimeoutSeconds, 5, 600);
+        var runnerToUse = runner ?? new PowerShellRunner();
+        Dictionary<string, string[]> parseErrorsByFile;
+
+        try
+        {
+            var parserResult = RunPowerShellExampleSyntaxValidation(files, TimeSpan.FromSeconds(timeoutSeconds), options.PreferPwsh, runnerToUse);
+            result.Executable = parserResult.Executable;
+            result.ValidationSucceeded = parserResult.ValidationSucceeded;
+            parseErrorsByFile = parserResult.ParseErrorsByFile;
+
+            if (!parserResult.ValidationSucceeded)
+            {
+                warnings.Add(
+                    $"API docs PowerShell coverage: PowerShell example validation did not complete successfully ({parserResult.ErrorMessage}).");
+            }
+        }
+        catch (Exception ex)
+        {
+            warnings.Add(
+                $"API docs PowerShell coverage: failed to validate PowerShell examples ({ex.GetType().Name}: {ex.Message}).");
+            result.Warnings = warnings
+                .Where(static warning => !string.IsNullOrWhiteSpace(warning))
+                .Select(NormalizeWarningCode)
+                .ToArray();
+            return result;
+        }
+
+        var fileResults = new List<WebApiDocsPowerShellExampleFileValidationResult>(files.Count);
+        foreach (var file in files)
+        {
+            parseErrorsByFile.TryGetValue(file, out var parseErrors);
+            parseErrors ??= Array.Empty<string>();
+            var commands = CollectPowerShellCommandTokensFromFile(file, warnings);
+            var matchedCommands = commands
+                .Where(knownCommandSet.Contains)
+                .Distinct(StringComparer.OrdinalIgnoreCase)
+                .OrderBy(static command => command, StringComparer.OrdinalIgnoreCase)
+                .ToArray();
+
+            fileResults.Add(new WebApiDocsPowerShellExampleFileValidationResult
+            {
+                FilePath = file,
+                ValidSyntax = parseErrors.Length == 0,
+                ParseErrorCount = parseErrors.Length,
+                ParseErrors = parseErrors,
+                Commands = commands,
+                MatchedCommands = matchedCommands
+            });
+        }
+
+        result.Files = fileResults
+            .OrderBy(static file => file.FilePath, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+        result.ValidSyntaxFileCount = result.Files.Count(static file => file.ValidSyntax);
+        result.InvalidSyntaxFileCount = result.Files.Length - result.ValidSyntaxFileCount;
+        result.MatchedFileCount = result.Files.Count(static file => file.MatchedCommands.Length > 0);
+        result.UnmatchedFileCount = result.Files.Length - result.MatchedFileCount;
+        result.ParseErrorCount = result.Files.Sum(static file => file.ParseErrorCount);
+
+        if (options.ExecuteMatchedExamples)
+        {
+            var executionResult = ExecuteMatchedPowerShellExamples(
+                result.Files,
+                manifestPath,
+                options.PowerShellExamplesPath,
+                TimeSpan.FromSeconds(Math.Clamp(options.ExecutionTimeoutSeconds, 5, 600)),
+                options.PreferPwsh,
+                runnerToUse,
+                result.Executable);
+            result.ExecutionCompleted = executionResult.ExecutionCompleted;
+            result.ExecutionExecutable = executionResult.Executable;
+            result.ExecutedFileCount = result.Files.Count(static file => file.ExecutionAttempted);
+            result.PassedExecutionFileCount = result.Files.Count(static file => file.ExecutionSucceeded == true);
+            result.FailedExecutionFileCount = result.Files.Count(static file => file.ExecutionSucceeded == false);
+            if (!executionResult.ExecutionCompleted && !string.IsNullOrWhiteSpace(executionResult.ErrorMessage))
+            {
+                warnings.Add(
+                    $"API docs PowerShell coverage: matched example execution did not complete successfully ({executionResult.ErrorMessage}).");
+            }
+        }
+
+        AppendPowerShellExampleValidationWarnings(result.Files, warnings);
+
+        result.Warnings = warnings
+            .Where(static warning => !string.IsNullOrWhiteSpace(warning))
+            .Select(NormalizeWarningCode)
+            .ToArray();
+        return result;
+    }
+
+    /// <summary>
+    /// Writes a PowerShell example validation report as JSON.
+    /// </summary>
+    /// <param name="outputPath">API docs output root.</param>
+    /// <param name="configuredPath">Optional relative or absolute report path.</param>
+    /// <param name="result">Validation result payload.</param>
+    /// <param name="options">Optional validation inputs used to normalize report paths.</param>
+    /// <returns>Full path to the written report.</returns>
+    public static string WritePowerShellExampleValidationReport(
+        string outputPath,
+        string? configuredPath,
+        WebApiDocsPowerShellExampleValidationResult result,
+        WebApiDocsPowerShellExampleValidationOptions? options = null)
+    {
+        if (string.IsNullOrWhiteSpace(outputPath))
+            throw new ArgumentException("Output path is required.", nameof(outputPath));
+        if (result is null)
+            throw new ArgumentNullException(nameof(result));
+
+        var resolvedConfiguredPath = string.IsNullOrWhiteSpace(configuredPath)
+            ? "powershell-example-validation.json"
+            : configuredPath.Trim();
+        var reportPath = Path.IsPathRooted(resolvedConfiguredPath)
+            ? Path.GetFullPath(resolvedConfiguredPath)
+            : Path.Combine(outputPath, resolvedConfiguredPath);
+        var parent = Path.GetDirectoryName(reportPath);
+        if (!string.IsNullOrWhiteSpace(parent))
+            Directory.CreateDirectory(parent);
+
+        WritePowerShellExampleExecutionArtifacts(reportPath, result);
+        var reportPayload = NormalizePowerShellExampleValidationResultForReport(reportPath, outputPath, result, options);
+        var json = JsonSerializer.Serialize(reportPayload, new JsonSerializerOptions
+        {
+            WriteIndented = true,
+            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
+        });
+        File.WriteAllText(reportPath, json, Encoding.UTF8);
+        return reportPath;
+    }
+
+    private static void WritePowerShellExampleExecutionArtifacts(
+        string reportPath,
+        WebApiDocsPowerShellExampleValidationResult result)
+    {
+        if (string.IsNullOrWhiteSpace(reportPath) || result?.Files is null || result.Files.Length == 0)
+            return;
+
+        var reportDirectory = Path.GetDirectoryName(reportPath);
+        if (string.IsNullOrWhiteSpace(reportDirectory))
+            return;
+
+        var artifactRoot = Path.Combine(
+            reportDirectory,
+            Path.GetFileNameWithoutExtension(reportPath) + "-artifacts");
+
+        var wroteAny = false;
+        for (var i = 0; i < result.Files.Length; i++)
+        {
+            var file = result.Files[i];
+            file.ExecutionArtifactPath = null;
+            if (!file.ExecutionAttempted)
+                continue;
+
+            if (file.ExecutionExitCode is null &&
+                string.IsNullOrWhiteSpace(file.ExecutionStdOut) &&
+                string.IsNullOrWhiteSpace(file.ExecutionStdErr))
+            {
+                continue;
+            }
+
+            Directory.CreateDirectory(artifactRoot);
+            var artifactName = $"{i + 1:D2}-{SanitizePowerShellExampleArtifactName(Path.GetFileNameWithoutExtension(file.FilePath))}.txt";
+            var artifactPath = Path.Combine(artifactRoot, artifactName);
+            File.WriteAllText(artifactPath, BuildPowerShellExampleExecutionArtifactContent(file), new UTF8Encoding(false));
+            file.ExecutionArtifactPath = artifactPath;
+            wroteAny = true;
+        }
+
+        if (!wroteAny && Directory.Exists(artifactRoot))
+            TryDeleteDirectory(artifactRoot);
+    }
+
+    private static string SanitizePowerShellExampleArtifactName(string? value)
+    {
+        var candidate = string.IsNullOrWhiteSpace(value) ? "example" : value.Trim();
+        var invalid = Path.GetInvalidFileNameChars();
+        var chars = candidate
+            .Select(ch => invalid.Contains(ch) ? '-' : ch)
+            .ToArray();
+        var sanitized = new string(chars).Trim();
+        return string.IsNullOrWhiteSpace(sanitized) ? "example" : sanitized;
+    }
+
+    private static string BuildPowerShellExampleExecutionArtifactContent(WebApiDocsPowerShellExampleFileValidationResult file)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine($"File: {Path.GetFileName(file.FilePath)}");
+        sb.AppendLine($"ExecutionSucceeded: {file.ExecutionSucceeded}");
+        if (file.ExecutionExitCode is not null)
+            sb.AppendLine($"ExitCode: {file.ExecutionExitCode.Value}");
+        if (file.MatchedCommands.Length > 0)
+            sb.AppendLine($"MatchedCommands: {string.Join(", ", file.MatchedCommands)}");
+        sb.AppendLine();
+
+        sb.AppendLine("[stdout]");
+        sb.AppendLine(string.IsNullOrWhiteSpace(file.ExecutionStdOut) ? "<empty>" : file.ExecutionStdOut);
+        sb.AppendLine();
+        sb.AppendLine("[stderr]");
+        sb.AppendLine(string.IsNullOrWhiteSpace(file.ExecutionStdErr) ? "<empty>" : file.ExecutionStdErr);
+        return sb.ToString().TrimEnd() + Environment.NewLine;
+    }
+
+    private static void AppendPowerShellExampleValidationWarnings(
+        IReadOnlyList<WebApiDocsPowerShellExampleFileValidationResult> files,
+        List<string> warnings)
+    {
+        if (files is null || warnings is null || files.Count == 0)
+            return;
+
+        var invalidFiles = files
+            .Where(static file => !file.ValidSyntax)
+            .Select(static file => Path.GetFileName(file.FilePath))
+            .Where(static name => !string.IsNullOrWhiteSpace(name))
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(static name => name, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+        if (invalidFiles.Length > 0)
+        {
+            warnings.Add(
+                $"API docs PowerShell coverage: {invalidFiles.Length} example script(s) failed syntax validation " +
+                $"(samples: {BuildPreviewList(invalidFiles, 4)}).");
+        }
+
+        var unmatchedFiles = files
+            .Where(static file => file.MatchedCommands.Length == 0)
+            .Select(static file => Path.GetFileName(file.FilePath))
+            .Where(static name => !string.IsNullOrWhiteSpace(name))
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(static name => name, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+        if (unmatchedFiles.Length > 0)
+        {
+            warnings.Add(
+                $"API docs PowerShell coverage: {unmatchedFiles.Length} example script(s) did not reference any documented commands " +
+                $"(samples: {BuildPreviewList(unmatchedFiles, 4)}).");
+        }
+
+        var failedExecutionFiles = files
+            .Where(static file => file.ExecutionAttempted && file.ExecutionSucceeded == false)
+            .Select(static file => Path.GetFileName(file.FilePath))
+            .Where(static name => !string.IsNullOrWhiteSpace(name))
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(static name => name, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+        if (failedExecutionFiles.Length > 0)
+        {
+            warnings.Add(
+                $"API docs PowerShell coverage: {failedExecutionFiles.Length} example script(s) failed execution " +
+                $"(samples: {BuildPreviewList(failedExecutionFiles, 4)}).");
+        }
+
+        var outsideConfiguredFiles = files
+            .Where(static file => string.Equals(file.ExecutionSkippedReason, "Outside configured PowerShell examples path.", StringComparison.OrdinalIgnoreCase))
+            .Select(static file => Path.GetFileName(file.FilePath))
+            .Where(static name => !string.IsNullOrWhiteSpace(name))
+            .Distinct(StringComparer.OrdinalIgnoreCase)
+            .OrderBy(static name => name, StringComparer.OrdinalIgnoreCase)
+            .ToArray();
+        if (outsideConfiguredFiles.Length > 0)
+        {
+            warnings.Add(
+                $"API docs PowerShell coverage: {outsideConfiguredFiles.Length} example script(s) were skipped during execution because they were outside the configured examples path " +
+                $"(samples: {BuildPreviewList(outsideConfiguredFiles, 4)}).");
+        }
+    }
+
+    private static string BuildPreviewList(IReadOnlyList<string> values, int previewCount)
+    {
+        if (values is null || values.Count == 0)
+            return string.Empty;
+
+        var limit = Math.Max(1, previewCount);
+        var preview = string.Join(", ", values.Take(limit));
+        var remaining = values.Count - Math.Min(values.Count, limit);
+        return remaining > 0 ? $"{preview} (+{remaining} more)" : preview;
+    }
+
+    private static PowerShellExampleExecutionProcessResult ExecuteMatchedPowerShellExamples(
+        IReadOnlyList<WebApiDocsPowerShellExampleFileValidationResult> files,
+        string? manifestPath,
+        string? configuredExamplesPath,
+        TimeSpan timeout,
+        bool preferPwsh,
+        IPowerShellRunner runner,
+        string? executableOverride)
+    {
+        if (files is null)
+            throw new ArgumentNullException(nameof(files));
+        if (runner is null)
+            throw new ArgumentNullException(nameof(runner));
+
+        var result = new PowerShellExampleExecutionProcessResult { ExecutionCompleted = true };
+        foreach (var file in files)
+        {
+            if (!file.ValidSyntax)
+            {
+                file.ExecutionSkippedReason = "Syntax validation failed.";
+                continue;
+            }
+
+            if (file.MatchedCommands.Length == 0)
+            {
+                file.ExecutionSkippedReason = "No documented commands matched.";
+                continue;
+            }
+
+            if (!IsWithinConfiguredPowerShellExamplesPath(file.FilePath, configuredExamplesPath))
+            {
+                file.ExecutionSkippedReason = "Outside configured PowerShell examples path.";
+                continue;
+            }
+
+            file.ExecutionAttempted = true;
+
+            try
+            {
+                var commandText = BuildPowerShellExampleExecutionCommand(file.FilePath, manifestPath);
+                var runResult = runner.Run(PowerShellRunRequest.ForCommand(
+                    commandText,
+                    timeout,
+                    preferPwsh: preferPwsh,
+                    workingDirectory: Path.GetDirectoryName(file.FilePath),
+                    executableOverride: string.IsNullOrWhiteSpace(executableOverride) ? null : executableOverride,
+                    captureOutput: true,
+                    captureError: true));
+
+                result.Executable ??= string.IsNullOrWhiteSpace(runResult.Executable) ? null : runResult.Executable;
+                file.ExecutionExitCode = runResult.ExitCode;
+                file.ExecutionSucceeded = runResult.ExitCode == 0;
+                file.ExecutionStdOut = NormalizeExecutionCapture(runResult.StdOut);
+                file.ExecutionStdErr = NormalizeExecutionCapture(runResult.StdErr);
+            }
+            catch (Exception ex)
+            {
+                result.ExecutionCompleted = false;
+                result.ErrorMessage ??= $"{ex.GetType().Name}: {ex.Message}";
+                file.ExecutionSucceeded = false;
+                file.ExecutionExitCode = -1;
+                file.ExecutionStdErr = NormalizeExecutionCapture($"{ex.GetType().Name}: {ex.Message}");
+            }
+        }
+
+        return result;
+    }
+
+    private static bool IsWithinConfiguredPowerShellExamplesPath(string? filePath, string? configuredExamplesPath)
+    {
+        if (string.IsNullOrWhiteSpace(filePath) || string.IsNullOrWhiteSpace(configuredExamplesPath))
+            return true;
+
+        try
+        {
+            var fullPath = Path.GetFullPath(filePath);
+            var configuredFullPath = Path.GetFullPath(configuredExamplesPath);
+
+            if (File.Exists(configuredFullPath))
+                return string.Equals(fullPath, configuredFullPath, StringComparison.OrdinalIgnoreCase);
+
+            var configuredDirectory = Directory.Exists(configuredFullPath)
+                ? configuredFullPath
+                : GetParentDirectory(configuredFullPath);
+            var relativePath = TryGetRelativePathWithinRoot(configuredDirectory, fullPath);
+            return !string.IsNullOrWhiteSpace(relativePath);
+        }
+        catch
+        {
+            return false;
+        }
+    }
+
+    private static string BuildPowerShellExampleExecutionCommand(string filePath, string? manifestPath)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine("$ErrorActionPreference = 'Stop'");
+        sb.AppendLine("$ProgressPreference = 'SilentlyContinue'");
+        var bootstrapModulePath = ResolvePowerShellExampleExecutionBootstrapModulePath(manifestPath);
+        if (!string.IsNullOrWhiteSpace(bootstrapModulePath) && File.Exists(bootstrapModulePath))
+        {
+            sb.Append("Import-Module -Name ");
+            sb.Append(ToPowerShellSingleQuotedLiteral(Path.GetFullPath(bootstrapModulePath)));
+            sb.AppendLine(" -Force | Out-Null");
+        }
+        else if (!string.IsNullOrWhiteSpace(manifestPath) && File.Exists(manifestPath))
+        {
+            sb.Append("Import-Module -Name ");
+            sb.Append(ToPowerShellSingleQuotedLiteral(Path.GetFullPath(manifestPath)));
+            sb.AppendLine(" -Force | Out-Null");
+        }
+
+        sb.Append("& ");
+        sb.Append(ToPowerShellSingleQuotedLiteral(Path.GetFullPath(filePath)));
+        return sb.ToString();
+    }
+
+    private static string? ResolvePowerShellExampleExecutionBootstrapModulePath(string? manifestPath)
+    {
+        if (string.IsNullOrWhiteSpace(manifestPath) || !File.Exists(manifestPath))
+            return null;
+
+        try
+        {
+            var text = File.ReadAllText(manifestPath);
+            var rootModule = ParseManifestScalarValue(text, "RootModule");
+            if (string.IsNullOrWhiteSpace(rootModule))
+                return null;
+
+            var manifestDirectory = Path.GetDirectoryName(manifestPath) ?? string.Empty;
+            var candidate = Path.IsPathRooted(rootModule)
+                ? rootModule
+                : Path.Combine(manifestDirectory, rootModule);
+            return candidate.EndsWith(".psm1", StringComparison.OrdinalIgnoreCase) && File.Exists(candidate)
+                ? candidate
+                : null;
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    private static string ToPowerShellSingleQuotedLiteral(string value)
+    {
+        return "'" + (value ?? string.Empty).Replace("'", "''", StringComparison.Ordinal) + "'";
+    }
+
+    private static string? NormalizeExecutionCapture(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            return null;
+
+        const int maxLength = 16000;
+        var normalized = value.Replace("\r\n", "\n", StringComparison.Ordinal).Trim();
+        if (normalized.Length <= maxLength)
+            return normalized;
+
+        return normalized[..maxLength] + "\n...[truncated]";
+    }
+
+    private static WebApiDocsPowerShellExampleValidationResult NormalizePowerShellExampleValidationResultForReport(
+        string reportPath,
+        string outputPath,
+        WebApiDocsPowerShellExampleValidationResult result,
+        WebApiDocsPowerShellExampleValidationOptions? options)
+    {
+        var reportDirectory = GetParentDirectory(reportPath);
+        var normalized = new WebApiDocsPowerShellExampleValidationResult
+        {
+            HelpPath = NormalizePowerShellValidationPath(result.HelpPath, outputPath, reportDirectory, options, result),
+            ManifestPath = NormalizePowerShellValidationPath(result.ManifestPath, outputPath, reportDirectory, options, result),
+            Executable = NormalizePowerShellExecutableValue(result.Executable),
+            ValidationSucceeded = result.ValidationSucceeded,
+            KnownCommandCount = result.KnownCommandCount,
+            KnownCommands = result.KnownCommands?.ToArray() ?? Array.Empty<string>(),
+            FileCount = result.FileCount,
+            ValidSyntaxFileCount = result.ValidSyntaxFileCount,
+            InvalidSyntaxFileCount = result.InvalidSyntaxFileCount,
+            MatchedFileCount = result.MatchedFileCount,
+            UnmatchedFileCount = result.UnmatchedFileCount,
+            ParseErrorCount = result.ParseErrorCount,
+            ExecutionRequested = result.ExecutionRequested,
+            ExecutionCompleted = result.ExecutionCompleted,
+            ExecutionExecutable = NormalizePowerShellExecutableValue(result.ExecutionExecutable),
+            ExecutedFileCount = result.ExecutedFileCount,
+            PassedExecutionFileCount = result.PassedExecutionFileCount,
+            FailedExecutionFileCount = result.FailedExecutionFileCount,
+            Files = result.Files?.Select(file => NormalizePowerShellExampleValidationFileForReport(file, outputPath, reportDirectory, options, result)).ToArray()
+                    ?? Array.Empty<WebApiDocsPowerShellExampleFileValidationResult>(),
+            Warnings = result.Warnings?.ToArray() ?? Array.Empty<string>()
+        };
+        return normalized;
+    }
+
+    private static WebApiDocsPowerShellExampleFileValidationResult NormalizePowerShellExampleValidationFileForReport(
+        WebApiDocsPowerShellExampleFileValidationResult file,
+        string outputPath,
+        string? reportDirectory,
+        WebApiDocsPowerShellExampleValidationOptions? options,
+        WebApiDocsPowerShellExampleValidationResult result)
+    {
+        return new WebApiDocsPowerShellExampleFileValidationResult
+        {
+            FilePath = NormalizePowerShellValidationPath(file.FilePath, outputPath, reportDirectory, options, result) ?? Path.GetFileName(file.FilePath),
+            ValidSyntax = file.ValidSyntax,
+            ParseErrorCount = file.ParseErrorCount,
+            ParseErrors = file.ParseErrors?.ToArray() ?? Array.Empty<string>(),
+            Commands = file.Commands?.ToArray() ?? Array.Empty<string>(),
+            MatchedCommands = file.MatchedCommands?.ToArray() ?? Array.Empty<string>(),
+            ExecutionAttempted = file.ExecutionAttempted,
+            ExecutionSucceeded = file.ExecutionSucceeded,
+            ExecutionExitCode = file.ExecutionExitCode,
+            ExecutionStdOut = file.ExecutionStdOut,
+            ExecutionStdErr = file.ExecutionStdErr,
+            ExecutionSkippedReason = file.ExecutionSkippedReason,
+            ExecutionArtifactPath = NormalizePowerShellValidationPath(file.ExecutionArtifactPath, outputPath, reportDirectory, options, result)
+        };
+    }
+
+    private static string? NormalizePowerShellValidationPath(
+        string? path,
+        string outputPath,
+        string? reportDirectory,
+        WebApiDocsPowerShellExampleValidationOptions? options,
+        WebApiDocsPowerShellExampleValidationResult? result)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return null;
+
+        try
+        {
+            var fullPath = Path.GetFullPath(path);
+            foreach (var root in EnumerateNonEmptyDirectories(
+                         reportDirectory,
+                         outputPath,
+                         GetValidationExamplesRoot(options?.PowerShellExamplesPath),
+                         GetParentDirectory(result?.HelpPath),
+                         GetParentDirectory(result?.ManifestPath),
+                         GetParentDirectory(options?.HelpPath),
+                         GetParentDirectory(options?.PowerShellModuleManifestPath)))
+            {
+                var relativePath = TryGetRelativePathWithinRoot(root, fullPath);
+                if (!string.IsNullOrWhiteSpace(relativePath))
+                    return relativePath;
+            }
+
+            return Path.GetFileName(fullPath);
+        }
+        catch
+        {
+            return Path.GetFileName(path);
+        }
+    }
+
+    private static IEnumerable<string> EnumerateNonEmptyDirectories(params string?[] candidates)
+    {
+        var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (var candidate in candidates)
+        {
+            if (string.IsNullOrWhiteSpace(candidate))
+                continue;
+
+            string? fullPath = null;
+            try
+            {
+                fullPath = Path.GetFullPath(candidate);
+            }
+            catch
+            {
+                // best effort only
+            }
+
+            if (!string.IsNullOrWhiteSpace(fullPath) && seen.Add(fullPath))
+                yield return fullPath;
+        }
+    }
+
+    private static string? TryGetRelativePathWithinRoot(string? root, string? fullPath)
+    {
+        if (string.IsNullOrWhiteSpace(root) || string.IsNullOrWhiteSpace(fullPath))
+            return null;
+
+        try
+        {
+            var relativePath = Path.GetRelativePath(root, fullPath);
+            if (relativePath.StartsWith("..", StringComparison.Ordinal) || Path.IsPathRooted(relativePath))
+                return null;
+
+            return relativePath.Replace('\\', '/');
+        }
+        catch
+        {
+            return null;
+        }
+    }
+
+    private static string? GetParentDirectory(string? path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return null;
+
+        try
+        {
+            return Path.GetDirectoryName(Path.GetFullPath(path));
+        }
+        catch
+        {
+            return Path.GetDirectoryName(path);
+        }
+    }
+
+    private static string? GetValidationExamplesRoot(string? path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return null;
+
+        try
+        {
+            var fullPath = Path.GetFullPath(path);
+            if (File.Exists(fullPath))
+                return Path.GetDirectoryName(fullPath);
+            return fullPath;
+        }
+        catch
+        {
+            return GetParentDirectory(path);
+        }
+    }
+
+    private static string? NormalizePowerShellExecutableValue(string? executable)
+    {
+        if (string.IsNullOrWhiteSpace(executable))
+            return null;
+
+        try
+        {
+            return Path.GetFileName(Path.GetFullPath(executable));
+        }
+        catch
+        {
+            return Path.GetFileName(executable);
+        }
+    }
+
+    private static PowerShellExampleSyntaxValidationProcessResult RunPowerShellExampleSyntaxValidation(
+        IReadOnlyList<string> files,
+        TimeSpan timeout,
+        bool preferPwsh,
+        IPowerShellRunner runner)
+    {
+        if (files is null)
+            throw new ArgumentNullException(nameof(files));
+        if (runner is null)
+            throw new ArgumentNullException(nameof(runner));
+
+        var tempRoot = Path.Combine(Path.GetTempPath(), "pf-web-ps-example-validate-" + Guid.NewGuid().ToString("N"));
+        Directory.CreateDirectory(tempRoot);
+
+        var inputPath = Path.Combine(tempRoot, "input.json");
+        var outputPath = Path.Combine(tempRoot, "output.json");
+        var scriptPath = Path.Combine(tempRoot, "validate-examples.ps1");
+
+        try
+        {
+            WriteJson(inputPath, new Dictionary<string, object?>
+            {
+                ["files"] = files
+            });
+            File.WriteAllText(scriptPath, PowerShellExampleValidationScript, new UTF8Encoding(false));
+
+            var runResult = runner.Run(new PowerShellRunRequest(
+                scriptPath,
+                new[] { inputPath, outputPath },
+                timeout,
+                preferPwsh: preferPwsh));
+
+            var result = new PowerShellExampleSyntaxValidationProcessResult
+            {
+                Executable = runResult.Executable,
+                ValidationSucceeded = runResult.ExitCode == 0
+            };
+
+            if (runResult.ExitCode != 0)
+            {
+                var error = string.IsNullOrWhiteSpace(runResult.StdErr) ? runResult.StdOut : runResult.StdErr;
+                result.ErrorMessage = string.IsNullOrWhiteSpace(error)
+                    ? $"PowerShell parser exited with code {runResult.ExitCode}."
+                    : error.Trim();
+                return result;
+            }
+
+            if (!File.Exists(outputPath))
+            {
+                result.ErrorMessage = "PowerShell parser did not write a validation report.";
+                result.ValidationSucceeded = false;
+                return result;
+            }
+
+            using var json = JsonDocument.Parse(File.ReadAllText(outputPath));
+            if (!json.RootElement.TryGetProperty("files", out var filesElement) ||
+                (filesElement.ValueKind != JsonValueKind.Array && filesElement.ValueKind != JsonValueKind.Object))
+            {
+                result.ErrorMessage = "PowerShell parser returned an invalid validation payload.";
+                result.ValidationSucceeded = false;
+                return result;
+            }
+
+            var fileEntries = filesElement.ValueKind == JsonValueKind.Array
+                ? filesElement.EnumerateArray().ToArray()
+                : new[] { filesElement };
+
+            foreach (var fileElement in fileEntries)
+            {
+                var filePath = fileElement.TryGetProperty("filePath", out var filePathElement)
+                    ? filePathElement.GetString()
+                    : null;
+                if (string.IsNullOrWhiteSpace(filePath))
+                    continue;
+
+                var errors = fileElement.TryGetProperty("parseErrors", out var errorsElement) &&
+                             errorsElement.ValueKind == JsonValueKind.Array
+                    ? errorsElement.EnumerateArray()
+                        .Select(static element => element.GetString())
+                        .Where(static value => !string.IsNullOrWhiteSpace(value))
+                        .Select(static value => value!)
+                        .ToArray()
+                    : Array.Empty<string>();
+                result.ParseErrorsByFile[filePath] = errors;
+            }
+
+            return result;
+        }
+        finally
+        {
+            TryDeleteDirectory(tempRoot);
+        }
+    }
+
+    private static void TryDeleteDirectory(string path)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+            return;
+
+        try
+        {
+            if (Directory.Exists(path))
+                Directory.Delete(path, true);
+        }
+        catch
+        {
+            // Best-effort temp cleanup.
+        }
+    }
+
+    private sealed class PowerShellExampleSyntaxValidationProcessResult
+    {
+        public string? Executable { get; set; }
+        public bool ValidationSucceeded { get; set; }
+        public string? ErrorMessage { get; set; }
+        public Dictionary<string, string[]> ParseErrorsByFile { get; } = new(StringComparer.OrdinalIgnoreCase);
+    }
+
+    private sealed class PowerShellExampleExecutionProcessResult
+    {
+        public string? Executable { get; set; }
+        public bool ExecutionCompleted { get; set; }
+        public string? ErrorMessage { get; set; }
+    }
+
+    private const string PowerShellExampleValidationScript =
+        """
+        param(
+            [string]$InputPath,
+            [string]$OutputPath
+        )
+
+        $payload = Get-Content -LiteralPath $InputPath -Raw | ConvertFrom-Json
+        $files = @($payload.files)
+        $results = foreach ($file in $files) {
+            $tokens = $null
+            $parseErrors = $null
+            [System.Management.Automation.Language.Parser]::ParseFile($file, [ref]$tokens, [ref]$parseErrors) | Out-Null
+            [ordered]@{
+                filePath = $file
+                parseErrors = @($parseErrors | ForEach-Object {
+                    if ($null -eq $_) {
+                        return
+                    }
+
+                    if ($_.Extent -and $_.Extent.StartLineNumber) {
+                        "$($_.Extent.StartLineNumber): $($_.Message)"
+                    } else {
+                        "$($_.Message)"
+                    }
+                })
+            }
+        }
+
+        [ordered]@{
+            files = @($results)
+        } | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $OutputPath -Encoding utf8
+        """;
+}
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.Reflection.Attributes.cs b/PowerForge.Web/Services/WebApiDocsGenerator.Reflection.Attributes.cs
index 0ba41ba8..481f30db 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.Reflection.Attributes.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.Reflection.Attributes.cs
@@ -112,7 +112,26 @@ private static ApiMemberModel CloneMember(ApiMemberModel source, bool isExtensio
         foreach (var tp in source.TypeParameters)
             clone.TypeParameters.Add(new ApiTypeParameterModel { Name = tp.Name, Summary = tp.Summary });
         foreach (var ex in source.Examples)
-            clone.Examples.Add(new ApiExampleModel { Kind = ex.Kind, Text = ex.Text });
+            clone.Examples.Add(new ApiExampleModel
+            {
+                Kind = ex.Kind,
+                Text = ex.Text,
+                Origin = ex.Origin,
+                Media = ex.Media is null
+                    ? null
+                    : new ApiExampleMediaModel
+                    {
+                        Type = ex.Media.Type,
+                        Url = ex.Media.Url,
+                        Title = ex.Media.Title,
+                        Alt = ex.Media.Alt,
+                        Caption = ex.Media.Caption,
+                        PosterUrl = ex.Media.PosterUrl,
+                        MimeType = ex.Media.MimeType,
+                        Width = ex.Media.Width,
+                        Height = ex.Media.Height
+                    }
+            });
         foreach (var ex in source.Exceptions)
             clone.Exceptions.Add(new ApiExceptionModel { Type = ex.Type, Summary = ex.Summary });
         foreach (var see in source.SeeAlso)
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.XmlAndHtml.cs b/PowerForge.Web/Services/WebApiDocsGenerator.XmlAndHtml.cs
index a54f2e91..fa6203f2 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.XmlAndHtml.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.XmlAndHtml.cs
@@ -217,6 +217,14 @@ private static List<ApiExampleModel> ParseExampleBlocks(XElement example)
                         if (!string.IsNullOrWhiteSpace(code))
                             results.Add(new ApiExampleModel { Kind = "code", Text = code });
                     }
+                    else if (TryParseExampleMedia(el, out var media))
+                    {
+                        results.Add(new ApiExampleModel
+                        {
+                            Kind = "media",
+                            Media = media
+                        });
+                    }
                     else
                     {
                         var textBlock = NormalizeXmlText(el);
@@ -237,6 +245,88 @@ private static List<ApiExampleModel> ParseExampleBlocks(XElement example)
         return results;
     }
 
+    private static bool TryParseExampleMedia(XElement element, out ApiExampleMediaModel? media)
+    {
+        media = null;
+        if (element is null)
+            return false;
+
+        var type = NormalizeExampleMediaType(element.Name.LocalName, element.Attribute("kind")?.Value, element.Attribute("type")?.Value, element.Attribute("provider")?.Value);
+        if (string.IsNullOrWhiteSpace(type))
+            return false;
+
+        var url = NormalizeInlineHref(
+            element.Attribute("src")?.Value ??
+            element.Attribute("url")?.Value ??
+            element.Attribute("href")?.Value ??
+            element.Attribute("file")?.Value);
+        if (string.IsNullOrWhiteSpace(url))
+            return false;
+
+        media = new ApiExampleMediaModel
+        {
+            Type = type,
+            Url = url,
+            Title = Normalize(element.Attribute("title")?.Value ?? element.Attribute("label")?.Value ?? string.Empty),
+            Alt = Normalize(element.Attribute("alt")?.Value ?? string.Empty),
+            Caption = Normalize(
+                element.Attribute("caption")?.Value ??
+                element.Attribute("description")?.Value ??
+                NormalizeXmlText(element) ??
+                string.Empty),
+            PosterUrl = NormalizeInlineHref(
+                element.Attribute("poster")?.Value ??
+                element.Attribute("thumbnail")?.Value ??
+                element.Attribute("thumb")?.Value),
+            MimeType = Normalize(
+                element.Attribute("mimeType")?.Value ??
+                element.Attribute("mime-type")?.Value ??
+                element.Attribute("contentType")?.Value ??
+                element.Attribute("content-type")?.Value ??
+                string.Empty),
+            Width = ParseNullableInt(element.Attribute("width")?.Value),
+            Height = ParseNullableInt(element.Attribute("height")?.Value)
+        };
+
+        return true;
+    }
+
+    private static string NormalizeExampleMediaType(string? elementName, params string?[] explicitCandidates)
+    {
+        foreach (var candidate in explicitCandidates)
+        {
+            var normalized = NormalizeExampleMediaTypeCandidate(candidate);
+            if (!string.IsNullOrWhiteSpace(normalized))
+                return normalized;
+        }
+
+        return NormalizeExampleMediaTypeCandidate(elementName);
+    }
+
+    private static string NormalizeExampleMediaTypeCandidate(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+            return string.Empty;
+
+        var normalized = value.Trim().ToLowerInvariant();
+        return normalized switch
+        {
+            "img" or "image" or "screenshot" => "image",
+            "video" => "video",
+            "terminal" or "terminalcast" or "asciinema" => "terminal",
+            "media" => "link",
+            "link" or "download" or "asset" => "link",
+            _ => string.Empty
+        };
+    }
+
+    private static int? ParseNullableInt(string? value)
+    {
+        return int.TryParse(value, out var parsed) && parsed > 0
+            ? parsed
+            : null;
+    }
+
     private static List<string> GetSeeAlso(
         XElement member,
         string memberKey,
diff --git a/PowerForge.Web/Services/WebApiDocsGenerator.cs b/PowerForge.Web/Services/WebApiDocsGenerator.cs
index f661be57..051468ef 100644
--- a/PowerForge.Web/Services/WebApiDocsGenerator.cs
+++ b/PowerForge.Web/Services/WebApiDocsGenerator.cs
@@ -24,6 +24,12 @@ public sealed class WebApiDocsOptions
     public string? PowerShellModuleManifestPath { get; set; }
     /// <summary>Optional path to exported PowerShell command metadata (kind + aliases).</summary>
     public string? PowerShellCommandMetadataPath { get; set; }
+    /// <summary>When true, compute git-based freshness metadata for API pages.</summary>
+    public bool GenerateGitFreshness { get; set; }
+    /// <summary>Max age in days for a page to be marked as <c>new</c>.</summary>
+    public int GitFreshnessNewDays { get; set; } = 14;
+    /// <summary>Max age in days for a page to be marked as <c>updated</c> before falling back to <c>stable</c>.</summary>
+    public int GitFreshnessUpdatedDays { get; set; } = 90;
     /// <summary>Optional assembly path for version metadata.</summary>
     public string? AssemblyPath { get; set; }
     /// <summary>Output directory for generated docs.</summary>
@@ -32,6 +38,10 @@ public sealed class WebApiDocsOptions
     public string Title { get; set; } = "API Reference";
     /// <summary>Base URL for API documentation routes.</summary>
     public string BaseUrl { get; set; } = "/api";
+    /// <summary>Optional absolute site base URL used for canonical/OpenGraph URL generation.</summary>
+    public string? SiteBaseUrl { get; set; }
+    /// <summary>Optional language code used for hreflang output on generated API pages.</summary>
+    public string? LanguageCode { get; set; }
       /// <summary>Optional docs home URL for the "Back to Docs" link.</summary>
       public string? DocsHomeUrl { get; set; }
       /// <summary>Sidebar position for docs template (left or right).</summary>
@@ -206,6 +216,10 @@ public sealed class WebApiDocsOptions
     /// </summary>
     public string? PowerShellExamplesPath { get; set; }
     /// <summary>
+    /// Optional PowerShell example validation result used to enrich imported examples with execution media.
+    /// </summary>
+    public WebApiDocsPowerShellExampleValidationResult? PowerShellExampleValidationResult { get; set; }
+    /// <summary>
     /// Maximum number of fallback code examples imported per PowerShell command.
     /// </summary>
     public int PowerShellFallbackExampleLimitPerCommand { get; set; } = 2;
@@ -258,18 +272,32 @@ public static partial class WebApiDocsGenerator
         ".api-sidebar",
         ".api-content",
         ".api-overview",
-        ".api-overview-grid",
+        ".namespace-group-header",
+        ".namespace-group-actions",
+        ".overview-group-toggle",
         ".type-chips",
         ".type-chip",
         ".chip-icon",
         ".sidebar-count",
         ".sidebar-toggle",
+        ".pf-combobox",
+        ".pf-combobox-trigger",
+        ".pf-combobox-list",
+        ".pf-combobox-option",
+        ".pf-enhanced-native",
         ".type-item",
         ".type-detail-shell",
         ".type-detail-rail",
+        ".type-toc",
+        ".type-toc-header",
+        ".type-toc-toggle",
         ".filter-button",
         ".member-card",
         ".member-signature",
+        ".example-origin",
+        ".example-origin-badge",
+        ".example-media-meta",
+        ".member-toggle input",
         ".member-header pre.member-signature",
         ".member-card pre::-webkit-scrollbar",
         ".member-card pre::-webkit-scrollbar-track",
@@ -364,6 +392,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
         ValidateSourceUrlPatternConsistency(options, types, warnings);
         ValidateConfiguredQuickStartTypes(types, options, warnings);
         ValidateDuplicateMemberSignatures(types, warnings);
+        AppendGitFreshnessMetadata(types, options);
 
         var index = new Dictionary<string, object?>
         {
@@ -387,6 +416,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                     ["fullName"] = t.FullName,
                     ["namespace"] = t.Namespace,
                     ["kind"] = t.Kind,
+                    ["freshness"] = BuildFreshnessJson(t.Freshness, options),
                     ["slug"] = t.Slug,
                     ["summary"] = t.Summary,
                     ["typeParameters"] = t.TypeParameters.Select(tp => new Dictionary<string, object?>
@@ -413,6 +443,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                 ["summary"] = t.Summary ?? string.Empty,
                 ["kind"] = t.Kind,
                 ["namespace"] = t.Namespace,
+                ["freshness"] = BuildFreshnessJson(t.Freshness, options),
                 ["slug"] = t.Slug,
                 ["url"] = $"{options.BaseUrl.TrimEnd('/')}/types/{t.Slug}.json"
             };
@@ -439,6 +470,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                 ["outputTypes"] = type.OutputTypes,
                 ["assembly"] = type.Assembly,
                 ["source"] = BuildSourceJson(type.Source),
+                ["freshness"] = BuildFreshnessJson(type.Freshness, options),
                 ["baseType"] = type.BaseType,
                 ["interfaces"] = type.Interfaces,
                 ["attributes"] = type.Attributes,
@@ -454,11 +486,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                     ["name"] = tp.Name,
                     ["summary"] = tp.Summary
                 }).ToList(),
-                ["examples"] = type.Examples.Select(ex => new Dictionary<string, object?>
-                {
-                    ["kind"] = ex.Kind,
-                    ["text"] = ex.Text
-                }).ToList(),
+                ["examples"] = SerializeExamples(type.Examples),
                 ["seeAlso"] = type.SeeAlso,
                 ["methods"] = type.Methods.Select(m => new Dictionary<string, object?>
                 {
@@ -487,11 +515,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                         ["name"] = tp.Name,
                         ["summary"] = tp.Summary
                     }).ToList(),
-                    ["examples"] = m.Examples.Select(ex => new Dictionary<string, object?>
-                    {
-                        ["kind"] = ex.Kind,
-                        ["text"] = ex.Text
-                    }).ToList(),
+                    ["examples"] = SerializeExamples(m.Examples),
                     ["exceptions"] = m.Exceptions.Select(ex => new Dictionary<string, object?>
                     {
                         ["type"] = ex.Type,
@@ -535,11 +559,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                         ["name"] = tp.Name,
                         ["summary"] = tp.Summary
                     }).ToList(),
-                    ["examples"] = m.Examples.Select(ex => new Dictionary<string, object?>
-                    {
-                        ["kind"] = ex.Kind,
-                        ["text"] = ex.Text
-                    }).ToList(),
+                    ["examples"] = SerializeExamples(m.Examples),
                     ["exceptions"] = m.Exceptions.Select(ex => new Dictionary<string, object?>
                     {
                         ["type"] = ex.Type,
@@ -574,11 +594,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                     ["access"] = p.Access,
                     ["modifiers"] = p.Modifiers,
                     ["valueSummary"] = p.ValueSummary,
-                    ["examples"] = p.Examples.Select(ex => new Dictionary<string, object?>
-                    {
-                        ["kind"] = ex.Kind,
-                        ["text"] = ex.Text
-                    }).ToList(),
+                    ["examples"] = SerializeExamples(p.Examples),
                     ["exceptions"] = p.Exceptions.Select(ex => new Dictionary<string, object?>
                     {
                         ["type"] = ex.Type,
@@ -602,11 +618,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                     ["modifiers"] = f.Modifiers,
                     ["value"] = f.Value,
                     ["valueSummary"] = f.ValueSummary,
-                    ["examples"] = f.Examples.Select(ex => new Dictionary<string, object?>
-                    {
-                        ["kind"] = ex.Kind,
-                        ["text"] = ex.Text
-                    }).ToList(),
+                    ["examples"] = SerializeExamples(f.Examples),
                     ["exceptions"] = f.Exceptions.Select(ex => new Dictionary<string, object?>
                     {
                         ["type"] = ex.Type,
@@ -628,11 +640,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                     ["isStatic"] = e.IsStatic,
                     ["access"] = e.Access,
                     ["modifiers"] = e.Modifiers,
-                    ["examples"] = e.Examples.Select(ex => new Dictionary<string, object?>
-                    {
-                        ["kind"] = ex.Kind,
-                        ["text"] = ex.Text
-                    }).ToList(),
+                    ["examples"] = SerializeExamples(e.Examples),
                     ["exceptions"] = e.Exceptions.Select(ex => new Dictionary<string, object?>
                     {
                         ["type"] = ex.Type,
@@ -665,11 +673,7 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
                         ["name"] = tp.Name,
                         ["summary"] = tp.Summary
                     }).ToList(),
-                    ["examples"] = m.Examples.Select(ex => new Dictionary<string, object?>
-                    {
-                        ["kind"] = ex.Kind,
-                        ["text"] = ex.Text
-                    }).ToList(),
+                    ["examples"] = SerializeExamples(m.Examples),
                     ["exceptions"] = m.Exceptions.Select(ex => new Dictionary<string, object?>
                     {
                         ["type"] = ex.Type,
@@ -702,8 +706,11 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
             ValidateCssContract(outputPath, options, warnings);
         }
 
+        AppendSourceCoverageWarnings(types, warnings);
+        AppendPowerShellExampleQualityWarnings(types, warnings);
         var coveragePath = WriteCoverageReport(outputPath, options, types, assemblyName, assemblyVersion, warnings);
         var xrefPath = WriteXrefMap(outputPath, options, types, assemblyName, assemblyVersion, warnings);
+        var powerShellExampleMediaManifestPath = WritePowerShellExampleMediaManifest(outputPath, options, types, warnings);
 
         var normalizedWarnings = warnings
             .Where(static w => !string.IsNullOrWhiteSpace(w))
@@ -718,12 +725,58 @@ public static WebApiDocsResult Generate(WebApiDocsOptions options)
             TypesPath = typesDir,
             CoveragePath = coveragePath,
             XrefPath = xrefPath,
+            PowerShellExampleMediaManifestPath = powerShellExampleMediaManifestPath,
             TypeCount = types.Count,
             UsedReflectionFallback = usedReflectionFallback,
             Warnings = normalizedWarnings
         };
     }
 
+    private static List<Dictionary<string, object?>> SerializeExamples(IEnumerable<ApiExampleModel> examples)
+    {
+        if (examples is null)
+            return new List<Dictionary<string, object?>>();
+
+        var items = new List<Dictionary<string, object?>>();
+        foreach (var example in examples)
+        {
+            if (example is null)
+                continue;
+
+            var payload = new Dictionary<string, object?>
+            {
+                ["kind"] = example.Kind,
+                ["text"] = example.Text
+            };
+
+            if (!string.IsNullOrWhiteSpace(example.Origin))
+                payload["origin"] = example.Origin;
+            if (example.Media is not null)
+            {
+                payload["media"] = new Dictionary<string, object?>
+                {
+                    ["type"] = example.Media.Type,
+                    ["url"] = example.Media.Url,
+                    ["title"] = example.Media.Title,
+                    ["alt"] = example.Media.Alt,
+                    ["caption"] = example.Media.Caption,
+                    ["posterUrl"] = example.Media.PosterUrl,
+                    ["mimeType"] = example.Media.MimeType,
+                    ["width"] = example.Media.Width,
+                    ["height"] = example.Media.Height
+                };
+                if (example.Media.CapturedAtUtc is not null)
+                    ((Dictionary<string, object?>)payload["media"]!)["capturedAtUtc"] = example.Media.CapturedAtUtc.Value.ToString("O");
+                if (example.Media.SourceUpdatedAtUtc is not null)
+                    ((Dictionary<string, object?>)payload["media"]!)["sourceUpdatedAtUtc"] = example.Media.SourceUpdatedAtUtc.Value.ToString("O");
+            }
+
+            items.Add(payload);
+        }
+
+        return items;
+    }
+
     private static string NormalizeWarningCode(string warning)
     {
         if (string.IsNullOrWhiteSpace(warning))
@@ -777,8 +830,12 @@ private static string NormalizeWarningCode(string warning)
             return "[PFWEB.APIDOCS.SOURCE] " + warning;
         if (trimmed.StartsWith("SourceUrlPattern repo", StringComparison.OrdinalIgnoreCase))
             return "[PFWEB.APIDOCS.SOURCE] " + warning;
+        if (trimmed.StartsWith("API docs source coverage:", StringComparison.OrdinalIgnoreCase))
+            return "[PFWEB.APIDOCS.SOURCE] " + warning;
         if (trimmed.StartsWith("API docs source:", StringComparison.OrdinalIgnoreCase))
             return "[PFWEB.APIDOCS.SOURCE] " + warning;
+        if (trimmed.StartsWith("API docs PowerShell coverage:", StringComparison.OrdinalIgnoreCase))
+            return "[PFWEB.APIDOCS.POWERSHELL] " + warning;
 
         if (trimmed.StartsWith("Failed to parse PowerShell help:", StringComparison.OrdinalIgnoreCase) ||
             trimmed.StartsWith("Multiple PowerShell help files found", StringComparison.OrdinalIgnoreCase))
diff --git a/Schemas/powerforge.web.pipelinespec.schema.json b/Schemas/powerforge.web.pipelinespec.schema.json
index 1b3a60a0..57e2b128 100644
--- a/Schemas/powerforge.web.pipelinespec.schema.json
+++ b/Schemas/powerforge.web.pipelinespec.schema.json
@@ -2304,6 +2304,18 @@
         "powershell-examples-path": { "type": "string", "description": "Alias of psExamplesPath." },
         "powerShellFallbackExampleLimit": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Max fallback examples per PowerShell command." },
         "powershell-fallback-example-limit": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Alias of powerShellFallbackExampleLimit." },
+        "executePowerShellExamples": { "type": "boolean", "description": "When true, execute matched PowerShell example scripts after syntax validation." },
+        "execute-powershell-examples": { "type": "boolean", "description": "Alias of executePowerShellExamples." },
+        "powerShellExampleExecutionTimeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 600, "description": "Per-example execution timeout in seconds for matched PowerShell example scripts." },
+        "powershell-example-execution-timeout-seconds": { "type": "integer", "minimum": 1, "maximum": 600, "description": "Alias of powerShellExampleExecutionTimeoutSeconds." },
+        "failOnPowerShellExampleExecution": { "type": "boolean", "description": "Fail the apidocs step when matched PowerShell example scripts fail execution or execution cannot complete." },
+        "fail-on-powershell-example-execution": { "type": "boolean", "description": "Alias of failOnPowerShellExampleExecution." },
+        "generateGitFreshness": { "type": "boolean", "description": "When true, compute git-based freshness metadata for API pages." },
+        "generate-git-freshness": { "type": "boolean", "description": "Alias of generateGitFreshness." },
+        "gitFreshnessNewDays": { "type": "integer", "minimum": 0, "description": "Max age in days for an API page to be marked as new." },
+        "git-freshness-new-days": { "type": "integer", "minimum": 0, "description": "Alias of gitFreshnessNewDays." },
+        "gitFreshnessUpdatedDays": { "type": "integer", "minimum": 0, "description": "Max age in days for an API page to be marked as updated before it becomes stable." },
+        "git-freshness-updated-days": { "type": "integer", "minimum": 0, "description": "Alias of gitFreshnessUpdatedDays." },
         "failOnWarnings": { "type": "boolean" },
         "failOnCoverage": { "type": "boolean", "description": "Fail apidocs step when configured coverage thresholds are not met." },
         "fail-on-coverage": { "type": "boolean", "description": "Alias of failOnCoverage." },
@@ -2325,6 +2337,14 @@
         "min-powershell-remarks-percent": { "type": "number", "minimum": 0, "maximum": 100 },
         "minPowerShellCodeExamplesPercent": { "type": "number", "minimum": 0, "maximum": 100 },
         "min-powershell-code-examples-percent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "minPowerShellAuthoredHelpCodeExamplesPercent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "min-powershell-authored-help-code-examples-percent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "minPowerShellImportedScriptCodeExamplesPercent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "min-powershell-imported-script-code-examples-percent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "minPowerShellImportedScriptPlaybackMediaPercent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "min-powershell-imported-script-playback-media-percent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "minPowerShellImportedScriptPlaybackMediaWithPosterPercent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "min-powershell-imported-script-playback-media-with-poster-percent": { "type": "number", "minimum": 0, "maximum": 100 },
         "minPowerShellParameterSummaryPercent": { "type": "number", "minimum": 0, "maximum": 100 },
         "min-powershell-parameter-summary-percent": { "type": "number", "minimum": 0, "maximum": 100 },
         "minTypeSourcePathPercent": { "type": "number", "minimum": 0, "maximum": 100 },
@@ -2357,6 +2377,18 @@
         "max-member-source-repo-mismatch-hints": { "type": "number", "minimum": 0 },
         "maxPowerShellSourceRepoMismatchHints": { "type": "number", "minimum": 0 },
         "max-powershell-source-repo-mismatch-hints": { "type": "number", "minimum": 0 },
+        "maxPowerShellGeneratedFallbackOnlyExamplePercent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "max-powershell-generated-fallback-only-example-percent": { "type": "number", "minimum": 0, "maximum": 100 },
+        "maxPowerShellGeneratedFallbackOnlyExampleCount": { "type": "number", "minimum": 0 },
+        "max-powershell-generated-fallback-only-example-count": { "type": "number", "minimum": 0 },
+        "maxPowerShellImportedScriptPlaybackMediaWithoutPosterCount": { "type": "number", "minimum": 0 },
+        "max-powershell-imported-script-playback-media-without-poster-count": { "type": "number", "minimum": 0 },
+        "maxPowerShellImportedScriptPlaybackMediaUnsupportedSidecarCount": { "type": "number", "minimum": 0 },
+        "max-powershell-imported-script-playback-media-unsupported-sidecar-count": { "type": "number", "minimum": 0 },
+        "maxPowerShellImportedScriptPlaybackMediaOversizedAssetCount": { "type": "number", "minimum": 0 },
+        "max-powershell-imported-script-playback-media-oversized-asset-count": { "type": "number", "minimum": 0 },
+        "maxPowerShellImportedScriptPlaybackMediaStaleAssetCount": { "type": "number", "minimum": 0 },
+        "max-powershell-imported-script-playback-media-stale-asset-count": { "type": "number", "minimum": 0 },
         "suppressWarnings": { "type": "array", "items": { "type": "string" } },
         "warningPreviewCount": { "type": "integer", "minimum": 0 },
         "inputs": {