chore: initialize the memory bank

Add the canonical .memory-bank base with evidence-based project context:
purpose and scope, workflows, stack and validation commands, architecture
map, decisions, and the open work found while documenting the cmdlets.

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

.memory-bank/activeContext.md

@@ -0,0 +1,30 @@
+---
+status: current
+last-verified: 2026-10-02
+owner: active-agent
+source: current task evidence
+---
+
+# Active context
+
+## 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.
+
+## 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.
+
+## Next step
+
+Await the next task. Open follow-ups are listed in `progress.md`.

.memory-bank/index.md

@@ -0,0 +1,46 @@
+---
+schema-version: 1
+loading-mode: routed
+status: accepted
+owner: shared
+last-verified: 2026-10-02
+source: repository evidence
+---
+
+# Memory Bank index
+
+Read this file first. It routes tasks to the smallest relevant set of Memory
+Bank files.
+
+## Full-read fallback
+
+Set `loading-mode` to `full` to restore complete-base loading. Also fail open
+when this index is missing or invalid, the task is ambiguous, routes conflict,
+a listed file is missing, or a critical fact cannot be found. Full mode also
+reads every existing `decisions/*.md` record.
+
+## Routing table
+
+Combine routes when a task spans topics. For durable repository writes, also
+read `activeContext.md` before editing.
+
+| Route | Task signals | Read |
+|---|---|---|
+| `general` | General Q&A with no project decision | Index only |
+| `continuation` | Resume, current focus, next step | `activeContext.md`, `progress.md` |
+| `scope` | Purpose, scope, requirements, Acceptance criteria | `projectbrief.md` |
+| `product` | Users, problem, workflow, experience goal | `productContext.md` |
+| `implementation` | Code, configuration, build, test, dependency, deployment | `techContext.md`, `activeContext.md` |
+| `architecture` | Design, pattern, decision, migration, integration | `systemPatterns.md`, relevant `decisions/*.md` |
+| `status` | Progress, recent change, open work | `progress.md`, `activeContext.md` |
+| `language` | Canonical terms in authored artifacts | `glossary.md` |
+| `interaction-history` | Session analysis, prompt trends, Memory Bank evals | `promptHistory.md`, `progress.md` |
+| `role` | Active Custom agent domain workflow | Only that agent's declared role files |
+
+## Authority order
+
+1. The user's current request controls task constraints.
+2. Repository source, configuration, tests, and evidence control facts.
+3. Accepted decision records control durable architectural choices.
+4. Core Memory Bank files control only their assigned topic.
+5. Historical logs never override current source.

.memory-bank/productContext.md

@@ -0,0 +1,42 @@
+---
+status: current
+last-verified: 2026-10-02
+owner: shared
+source: repository evidence
+---
+
+# Product context
+
+## Problem
+
+PowerShell ships only `Get-Acl` and `Set-Acl`; everything between reading
+and writing an ACL (permission reports, adding or removing one entry,
+inheritance, ownership, orphaned SIDs) needs custom .NET code. The module
+provides task-level cmdlets for these jobs (`README.md` summary).
+
+## Users
+
+- People who manage NTFS file and folder permissions with PowerShell
+  (README summary). Specific personas: To confirm.
+
+## Core workflows
+
+1. Report permissions: `Get-NTFSAccess`, `Get-NTFSSimpleAccess`,
+   `Get-NTFSEffectiveAccess`.
+2. Change permissions: `Add-NTFSAccess`, `Remove-NTFSAccess`,
+   `Clear-NTFSAccess`; the audit equivalents manage the SACL.
+3. Back up and restore explicit permissions through CSV
+   (`Get-NTFSAccess | Export-Csv`, `Import-Csv | Add-NTFSAccess`).
+4. Find and remove orphaned entries: `Get-NTFSOrphanedAccess`.
+5. Repair inheritance and ownership: `*-NTFSAccessInheritance`,
+   `Set-NTFSInheritance`, `Set-NTFSOwner`, using backup/restore privileges.
+6. Work with paths longer than 260 characters: `Get-ChildItem2` and the other
+   `*-Item2` cmdlets.
+
+## Experience goals
+
+- Pipeline first: item cmdlets emit objects whose `FullName` binds to `-Path`.
+- Accept account names and SIDs; output shows both when resolvable.
+- Output formatted like `Get-ChildItem` (`NTFSSecurity.format.ps1xml`).
+- Work on files the caller cannot normally open by enabling the Backup,
+  Restore, TakeOwnership, and Security privileges automatically.

.memory-bank/progress.md

@@ -0,0 +1,51 @@
+---
+status: current
+last-verified: 2026-10-02
+owner: active-agent
+source: repository evidence
+---
+
+# Progress
+
+## Current status
+
+Documentation matches the cmdlets at HEAD. The module source is unchanged
+since the 4.2.6 release except the `Remove-Item2 -PassThru` rename and
+`CompatiblePSEditions`.
+
+## Recent milestones
+
+- 2026-10-02: Memory Bank initialized.
+- 2026-10-02: Documentation aligned with the code: 36 cmdlet pages filled
+  from the C# source and checked at runtime in a sandbox; Concepts, Examples,
+  home page, contributor guide, README rewritten; `mkdocs.yml` nav,
+  `edit_uri`, and `.readthedocs.yml` (`build.os`) fixed; `CHANGELOG.md`
+  created.
+
+## Stable capabilities
+
+- 36 cmdlets: access (7), audit (5), inheritance (6), owner and security
+  descriptor (4), privileges (3), long-path items (6), links, hash, and
+  disk space (5).
+- Works in Windows PowerShell 5.1 and PowerShell 7 (smoke-tested), except
+  `Get-FileHash2`, which fails in PowerShell 7 (missing `RIPEMD160` type).
+
+## Open work
+
+- 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.
+- 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):
+  `Add-NTFSAudit` duplicate position 2; SD parameter sets of
+  `Add/Remove-NTFSAccess/Audit` need `-AppliesTo`; `Set-NTFSInheritance`
+  nullable crash and hard-coded removal; inheritance cmdlets ignore
+  `EnablePrivileges = $false`; `Get-NTFSEffectiveAccess`
+  `-ExcludeNoneAccessEntries` and SD set ineffective; `-Account`/SD ignored by
+  `Get-NTFSOrphanedAccess/Audit` and `Get-NTFSSimpleAccess`; `Copy-Item2`
+  fails on folders with files; `Get-ChildItem2` throws on a file path;
+  `return` instead of `continue` in several `ProcessRecord` loops; wrong
+  `OutputType` on several cmdlets; `Get-FileHash2` in PowerShell 7.

.memory-bank/projectbrief.md

@@ -0,0 +1,42 @@
+---
+status: current
+last-verified: 2026-10-02
+owner: shared
+source: repository evidence
+---
+
+# Project brief
+
+## Purpose
+
+NTFSSecurity is a binary (C#) PowerShell module that fills the gap between
+`Get-Acl` and `Set-Acl`: cmdlets to read, add, remove, and clear NTFS
+permissions (DACL) and audit rules (SACL), manage inheritance and ownership,
+copy security descriptors, control process privileges, and work with long
+paths (`*-Item2` cmdlets via AlphaFS), hard links, and symbolic links.
+Source: `README.md`, `NTFSSecurity/NTFSSecurity.psd1`.
+
+## Scope
+
+- In scope: module source (`NTFSSecurity`, `Security2`, `PrivilegeControl`,
+  `ProcessPrivileges`), module manifest and type/format data, the MkDocs
+  documentation site in `Docs/`, and `README.md`.
+- Out of scope: registry security. `Security2/Registry/RegistrySecurity.cs`
+  exists, but no registry cmdlet is exported.
+- Distribution: PowerShell Gallery package `NTFSSecurity` and GitHub releases.
+
+## Stakeholders
+
+- Maintainer and author: Raimund Andree (`raandree`), per the manifest.
+- Documentation contributors: James Smith (`mkdocs.yml` `site_author`);
+  the AppVeyor documentation build runs under the `Sup3rlativ3` account.
+- End users: To confirm beyond the README summary.
+
+## Acceptance criteria
+
+1. Every exported cmdlet has an accurate platyPS page in `Docs/Cmdlets`.
+2. `Update-MarkdownHelp` against the module produces no parameter drift
+   (the check in `appveyor.yml`).
+3. The module imports in Windows PowerShell 5.1 and PowerShell 7
+   (`CompatiblePSEditions = 'Core', 'Desktop'`).
+4. Further release criteria: To confirm.

.memory-bank/systemPatterns.md

@@ -0,0 +1,86 @@
+---
+status: current
+last-verified: 2026-10-02
+owner: active-agent
+source: repository evidence
+---
+
+# System patterns
+
+## Architecture
+
+```text
+NTFSSecurity.psd1 ─┬─ ScriptsToProcess: NTFSSecurity.Init.ps1
+                   │    Add-Type: Security2.dll, PrivilegeControl.dll,
+                   │    ProcessPrivileges.dll, inline NTFS.DriveInfoExt;
+                   │    Update-FormatData -PrependPath format.ps1xml
+                   ├─ TypesToProcess: NTFSSecurity.types.ps1xml
+                   │    (Owner, IsInheritanceBlocked, LengthOnDisk on
+                   │    FileInfo/DirectoryInfo; AccountType on ACEs)
+                   ├─ ModuleToProcess: NTFSSecurity.psm1 (aliases)
+                   └─ NestedModules: NTFSSecurity.dll (36 cmdlets)
+NTFSSecurity.dll ── cmdlets ──> Security2.dll (FileSystemAccessRule2,
+                                FileSystemAuditRule2, IdentityReference2,
+                                FileSystemInheritanceInfo, EffectiveAccess)
+                 ── long paths ──> AlphaFS
+                 ── privileges ──> PrivilegeControl / ProcessPrivileges
+```
+
+- `BaseCmdlet` resolves relative paths against `$PWD`.
+- `BaseCmdletWithPrivControl` (access, audit, inheritance, owner, security
+  descriptor, and privilege cmdlets) enables Backup, Restore, TakeOwnership,
+  and Security in `BeginProcessing` when `PrivateData.EnablePrivileges` is
+  `$true`, and disables the ones it enabled in `EndProcessing`.
+- `PrivateData` switches: `EnablePrivileges` (base cmdlet),
+  `GetInheritedFrom` (`Get-NTFSAccess`, `Get-NTFSAudit`),
+  `GetFileSystemModeProperty` and `IdentifyHardLinks` (`Get-ChildItem2`),
+  `ShowAccountSid` (format file).
+- Cmdlets accept either `-Path` (alias `FullName`) or `-SecurityDescriptor`
+  (from `Get-NTFSSecurityDescriptor`); SD sets change the in-memory object
+  until `Set-NTFSSecurityDescriptor` writes it back.
+
+## Decisions
+
+### Decision 1: Use the canonical Memory Bank base
+
+- Choice: Keep durable project context in .memory-bank.
+- Rationale: Preserve evidence-backed context across sessions.
+
+### Decision 2: Cmdlet reference stays platyPS markdown
+
+- Choice: `Docs/Cmdlets/*.md` keep the platyPS 0.14 schema 2.0.0 layout
+  (upper-case section headings, YAML parameter blocks, one paragraph per
+  line) so `Update-MarkdownHelp` and `New-ExternalHelp` round-trip.
+- Rationale: `appveyor.yml` checks the pages with `Update-MarkdownHelp`;
+  the same files can generate MAML help.
+
+### Decision 3: Document the source at HEAD
+
+- Choice: Docs describe the code on `master`. Where HEAD differs from the
+  latest Gallery release, the page says which version changed.
+- Rationale: The user asked to align docs with the actual code; the only
+  current difference is `Remove-Item2 -PassThru` (4.2.6 spells `-PassThur`).
+
+### Decision 4: Online help points to GitHub
+
+- Choice: `online version` of every cmdlet page is
+  `https://github.com/raandree/NTFSSecurity/blob/master/Docs/Cmdlets/<Name>.md`.
+- Rationale: The Read the Docs project builds a stale fork, so its URLs show
+  outdated pages; GitHub always shows `master`.
+
+### Decision 5: Document defects, don't fix them in docs work
+
+- Choice: Code defects found while documenting are described on the affected
+  page (workaround or limitation) and listed in `progress.md`; source code is
+  changed only in separate, tested work.
+- Rationale: No build toolchain was available to verify code changes, and
+  the docs must describe current behavior.
+
+### Pattern: verifying documentation
+
+- Run platyPS in Windows PowerShell 5.1 against a module build; a copy of
+  `Docs/Cmdlets` must round-trip through `Update-MarkdownHelp` unchanged.
+- platyPS rewrites non-ASCII punctuation such as em dashes; keep cmdlet pages
+  ASCII-only.
+- Verify examples in a `$env:TEMP` sandbox, never on real data; parse every
+  example and check its parameters against `Get-Command` metadata.

.memory-bank/techContext.md

@@ -0,0 +1,62 @@
+---
+status: current
+last-verified: 2026-10-02
+owner: active-agent
+source: repository evidence
+---
+
+# Tech context
+
+## Stack
+
+- C# class libraries, old-style `.csproj`, .NET Framework 4.5.2,
+  solution `NTFSSecurity.sln` (Visual Studio 2017 format).
+- Projects: `NTFSSecurity` (cmdlets), `Security2` (ACL object model, Win32
+  interop), `PrivilegeControl` and `ProcessPrivileges` (token privileges),
+  `Log`, `TestClient`, `NTFSSecurityTest` (MSTest, minimal coverage).
+- NuGet (`packages.config`): AlphaFS 2.2.x for long paths;
+  `System.Management.Automation.dll` 10.0.10586.0.
+- Module: `NTFSSecurity.psd1` loads `NTFSSecurity.psm1` (aliases `dir2`,
+  `gi2`, `rm2`, `del2`), `NTFSSecurity.Init.ps1` (Add-Type of the helper
+  assemblies, prepends `NTFSSecurity.format.ps1xml`), and `NTFSSecurity.dll`.
+- Documentation: MkDocs (`mkdocs.yml`, theme `readthedocs`, `docs_dir: ./Docs`)
+  built by Read the Docs (`.readthedocs.yml` v2); cmdlet pages are platyPS
+  0.14 markdown (schema 2.0.0) in `Docs/Cmdlets`.
+
+## Environment
+
+- 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.
+
+## Constraints
+
+- `ModuleVersion` in the source manifest is `4.2.5`; the latest tag and
+  Gallery release is `4.2.6`.
+- HEAD differs from tag `4.2.6` only by the `Remove-Item2 -PassThur` to
+  `-PassThru` rename and `CompatiblePSEditions` in the manifest.
+- `CmdletsToExport` lists `Show-NTFSSimpleAccess`, which no longer exists
+  (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.
+- `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.
+- 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`.
+- MkDocs needs Python, which this workstation does not have; `mkdocs build
+  --strict` was not run.