ci: build the module and check the docs against the build

The documentation check ran Update-MarkdownHelp against the NTFSSecurity
release from the PowerShell Gallery (4.2.6), so it failed for every
unreleased parameter change. PR #91 failed because 4.2.6 still has
Remove-Item2 -PassThur while the source and the docs have -PassThru.

- Build NTFSSecurity.csproj in Release on the Visual Studio 2022 image,
  using the .NET Framework 4.5.2 reference assemblies package instead of
  an installed targeting pack
- Check Docs/Cmdlets against the module built from source
- Pin platyPS 0.14.2 and MarkdownLinkCheck 0.2.0, and enable TLS 1.2 so
  the NuGet provider bootstrap works

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: AI Assistant <ai@example.com>

.memory-bank/activeContext.md

@@ -9,22 +9,22 @@ source: current task evidence
 
 ## Current focus
 
-Documentation aligned with the cmdlets at HEAD (branch `ai/docs-alignment`).
-Next candidates: ship generated MAML help, re-point the docs build, and fix
-the code defects the documentation work surfaced.
+PR #91 (`ai/docs-alignment`): CI fixed by building the module from source
+in `appveyor.yml` and checking the docs against that build.
 
 ## Evidence
 
-- All 36 cmdlet pages filled from the C# source; 142 examples; no `{{`
-  placeholders; examples checked against live parameter metadata.
-- `Update-MarkdownHelp` against release 4.2.6 leaves 35 of 36 pages
-  byte-identical; `Remove-Item2` differs only by `-PassThru` (HEAD) versus
-  `-PassThur` (4.2.6).
-- `New-ExternalHelp` builds `NTFSSecurity.dll-Help.xml` (36 commands);
-  `Get-Help` renders it when placed in `en-US` of a module copy.
-- Read the Docs project `ntfssecurity` and the AppVeyor project build the
-  fork `Sup3rlativ3/NTFSSecurity`; the last RTD build is about 5.75 years old.
+- AppVeyor build 54825990 failed in step 01: `Update-MarkdownHelp` against
+  the Gallery module 4.2.6 rewrote `Remove-Item2 -PassThru` to `-PassThur`.
+- Against a Release build of the source, `Update-MarkdownHelp` changes none
+  of the 36 pages; a simulation of all `appveyor.yml` steps in a fresh clone
+  passed, and a page with stale syntax made it fail as intended.
+- The link check (`Get-MarkdownLink -BrokenOnly`) finds 308 links, none
+  broken.
+- Read the Docs project `ntfssecurity` still builds the fork
+  `Sup3rlativ3/NTFSSecurity`.
 
 ## Next step
 
-Await the next task. Open follow-ups are listed in `progress.md`.
+Push `ai/docs-alignment` (only on request) and confirm the AppVeyor build of
+PR #91 passes on the Visual Studio 2022 image.

.memory-bank/progress.md

@@ -21,6 +21,9 @@ since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and
   home page, contributor guide, README rewritten; `mkdocs.yml` nav,
   `edit_uri`, and `.readthedocs.yml` (`build.os`) fixed; `CHANGELOG.md`
   created.
+- 2026-10-02: PR #91 build fixed: `appveyor.yml` builds the module from
+  source and checks the docs against that build instead of the Gallery
+  release (root cause of the `Remove-Item2 -PassThru` drift failure).
 
 ## Stable capabilities
 
@@ -34,9 +37,8 @@ since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and
 
 - Ship help: add the generated `en-US\NTFSSecurity.dll-Help.xml` to the
   build and drop the stale `NTFSSecurity-Help.xml`.
-- Publishing: re-point Read the Docs and AppVeyor from the fork
-  `Sup3rlativ3/NTFSSecurity`; `appveyor.yml` checks docs against the Gallery
-  module instead of the source.
+- Publishing: re-point Read the Docs from the fork `Sup3rlativ3/NTFSSecurity`
+  to this repository (or create a new Read the Docs project).
 - Manifest: remove `Show-NTFSSimpleAccess` and duplicates from
   `CmdletsToExport`; bump `ModuleVersion` (4.2.5 in source, 4.2.6 released).
 - Code defects found while documenting (each documented on its page):

.memory-bank/systemPatterns.md

@@ -76,6 +76,15 @@ NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2,
 - Rationale: No build toolchain was available to verify code changes, and
   the docs must describe current behavior.
 
+### Decision 6: CI checks the docs against a build of the source
+
+- Choice: `appveyor.yml` builds `NTFSSecurity.csproj` and runs
+  `Update-MarkdownHelp` against `NTFSSecurity\bin\Release`, not against the
+  module from the PowerShell Gallery.
+- Rationale: Checking against the last release fails for every unreleased
+  parameter change (PR #91 failed on `Remove-Item2 -PassThru`) and never
+  compiled the code.
+
 ### Pattern: verifying documentation
 
 - Run platyPS in Windows PowerShell 5.1 against a module build; a copy of

.memory-bank/techContext.md

@@ -28,8 +28,12 @@ source: repository evidence
 - Windows only (NTFS, Win32 security APIs).
 - The Debug build writes straight into
   `C:\Program Files\WindowsPowerShell\Modules\NTFSSecurity\`.
-- No MSBuild or .NET Framework targeting pack on the 2026-10-02 workstation;
-  the released module 4.2.6 and platyPS 0.14.2 were installed.
+- No Visual Studio MSBuild or .NET Framework targeting pack on the
+  workstation. A local build works with the .NET Framework MSBuild
+  (`%WINDIR%\Microsoft.NET\Framework64\v4.0.30319\MSBuild.exe`) plus
+  `/p:CscToolPath` to the Roslyn `csc.exe` of the `Microsoft.Net.Compilers`
+  package; the legacy C# 5 compiler fails with CS0136. `dotnet msbuild`
+  fails on the binary resources in `Resources.resx` (MSB3822, MSB3823).
 
 ## Constraints
 
@@ -41,22 +45,27 @@ source: repository evidence
   (WinForms code removed in `d3063de`), and repeats the inheritance cmdlets.
 - `NTFSSecurity/NTFSSecurity-Help.xml` is a stale pre-4.x MAML file for old
   command names; binary-module help must be named `NTFSSecurity.dll-Help.xml`.
-- Read the Docs (`ntfssecurity`) and AppVeyor are attached to the fork
-  `Sup3rlativ3/NTFSSecurity`, not to this repository.
+- CI: AppVeyor project `raandree/ntfssecurity` builds branches and pull
+  requests. Read the Docs (`ntfssecurity`) and a second AppVeyor project are
+  attached to the fork `Sup3rlativ3/NTFSSecurity`.
 - `Get-FileHash2` fails in PowerShell 7; all other cmdlets passed a smoke
   test in PowerShell 7.6.
 
 ## Validation
 
-- Docs drift check (mirrors `appveyor.yml`), run in Windows PowerShell 5.1
-  to avoid PowerShell 7.4+ `-ProgressAction` noise: copy `Docs/Cmdlets`, run
-  `Update-MarkdownHelp` on the copy against the module, and diff.
+- CI (`appveyor.yml`, image Visual Studio 2022): restore `packages.config`
+  per project plus `Microsoft.NETFramework.ReferenceAssemblies.net452`
+  1.0.3, build `NTFSSecurity.csproj` in Release with
+  `TargetFrameworkRootPath`/`FrameworkPathOverride`, import
+  `NTFSSecurity\bin\Release\NTFSSecurity.psd1`, run `Update-MarkdownHelp`,
+  and fail on `git diff -- Docs/Cmdlets`; then `Get-MarkdownLink -BrokenOnly`.
+- Run platyPS in Windows PowerShell 5.1 to avoid PowerShell 7.4+
+  `-ProgressAction` noise.
 - Placeholder check: no `{{` left in `Docs/Cmdlets/*.md`.
 - Help build check: `New-ExternalHelp -Path ./Docs/Cmdlets` to a temp folder.
 - Markdown lint: `npx markdownlint-cli2` with `MD013` limited to prose
   (tables, code, and headings excluded) on the conceptual pages.
-- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml` and
-  `.readthedocs.yml`; every `nav` target must exist.
-- Link check in CI: `Get-MarkdownLink -Path .\Docs\ -BrokenOnly`.
+- YAML: `ConvertFrom-Yaml` (powershell-yaml) on `mkdocs.yml`,
+  `.readthedocs.yml`, and `appveyor.yml`; every `nav` target must exist.
 - MkDocs needs Python, which this workstation does not have; `mkdocs build
   --strict` was not run.

Docs/Contributing/02-Writing.md

@@ -42,7 +42,8 @@ parameter descriptions, the examples, and the notes.
 
 When a cmdlet changes, build the module, import the build output, and update
 the pages in Windows PowerShell 5.1. A Release build writes the module to
-`NTFSSecurity\bin\Release`:
+`NTFSSecurity\bin\Release`; the `before_build` and `build_script` steps in
+`appveyor.yml` show the commands that the CI build uses:
 
 ```powershell
 Install-Module -Name platyPS -RequiredVersion 0.14.2

appveyor.yml

@@ -1,31 +1,48 @@
-install:
-    - ps: |
-        Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force
-        Install-Module platyPS -Force
-        Install-Module MarkdownLinkCheck -Force
-        Install-Module NTFSSecurity -Force 
-        Import-Module platyPS
-        Import-Module MarkdownLinkCheck
+# Builds the NTFSSecurity module from source and checks that the cmdlet
+# documentation in Docs/Cmdlets matches the cmdlets of that build.
+image: Visual Studio 2022
 
 init:
-    - ps: git config --global core.autocrlf true
+  - ps: git config --global core.autocrlf true
+
+install:
+  - ps: |
+      [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+      Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force | Out-Null
+      Install-Module -Name platyPS -RequiredVersion 0.14.2 -Force
+      Install-Module -Name MarkdownLinkCheck -RequiredVersion 0.2.0 -Force
+
+before_build:
+  - nuget restore NTFSSecurity\packages.config -PackagesDirectory packages -NonInteractive
+  - nuget restore Security2\packages.config -PackagesDirectory packages -NonInteractive
+  # Provides the .NET Framework 4.5.2 reference assemblies, so the build does
+  # not depend on a targeting pack installed on the build image.
+  - nuget install Microsoft.NETFramework.ReferenceAssemblies.net452 -Version 1.0.3 -OutputDirectory packages -NonInteractive
 
 build_script:
-    - ps: Import-Module -Force NTFSSecurity
+  - ps: |
+      $referenceAssemblies = "$env:APPVEYOR_BUILD_FOLDER\packages\Microsoft.NETFramework.ReferenceAssemblies.net452.1.0.3\build"
+      msbuild NTFSSecurity\NTFSSecurity.csproj /nologo /verbosity:minimal /p:Configuration=Release "/p:TargetFrameworkRootPath=$referenceAssemblies" "/p:FrameworkPathOverride=$referenceAssemblies\.NETFramework\v4.5.2"
+      if ($LASTEXITCODE -ne 0) {
+          throw "MSBuild failed with exit code $LASTEXITCODE."
+      }
 
 test_script:
-    - ps: |
-        $ErrorActionPreference = 'Stop'
+  - ps: |
+      $ErrorActionPreference = 'Stop'
+      Import-Module -Name platyPS
+      Import-Module -Name MarkdownLinkCheck
+      Import-Module -Name .\NTFSSecurity\bin\Release\NTFSSecurity.psd1 -Force
 
-        # 01. Test that documentation is up-to-date
-        Update-MarkdownHelp -Path ./Docs/Cmdlets
-        $Diff = git diff
-        if ($Diff) {
-            throw "Help is not up-to-date, run Update-MarkdownHelp: $diff"
-        }
+      # 01. Test that the documentation matches the cmdlets built from source
+      Update-MarkdownHelp -Path ./Docs/Cmdlets | Out-Null
+      $diff = git diff -- Docs/Cmdlets
+      if ($diff) {
+          throw "Help is not up-to-date, run Update-MarkdownHelp: $diff"
+      }
 
-        # 02. Verify hyperlinks
-        $BrokenLinks = Get-MarkdownLink -Path .\Docs\ -BrokenOnly
-        if ($brokenLinks) {
-            throw "Found broken hyperlinks $brokenLinks"
-        }
+      # 02. Verify hyperlinks
+      $brokenLinks = Get-MarkdownLink -Path .\Docs\ -BrokenOnly
+      if ($brokenLinks) {
+          throw "Found broken hyperlinks $brokenLinks"
+      }