foundry-osd · mchave3 · May 15, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
diff --git a/.gitignore b/.gitignore
@@ -422,6 +422,7 @@ FodyWeavers.xsd
 bin/
 obj/
 *.csproj.user
+*.lscache
 
 # Keep bundled 7-Zip architecture folders tracked.
 !src/Foundry/Assets/7z/[xX]64/

diff --git a/docs/implementation/autopilot-hardware-hash-upload.md b/docs/implementation/autopilot-hardware-hash-upload.md
@@ -0,0 +1,51 @@
+# Autopilot Hardware Hash Upload Implementation Plan
+
+This index is the entry point for the Autopilot hardware hash upload plan. The detailed plan is split into smaller documents so implementation agents can load only the context needed for the current phase.
+
+## Required Instructions
+- Implementation agents must follow the repository instructions in [AGENTS.md](../../AGENTS.md).
+- All PR titles, commit messages, code, and documentation changes must be in English.
+- Add XML documentation comments for public or non-obvious C# APIs when they clarify intent, contracts, or operational constraints.
+- Each phase branch must branch from `feature/autopilot-hash-upload-foundation` and merge back into that foundation branch before the next phase starts.
+- Do not merge, squash, or auto-squash pull requests automatically. The repository owner handles PR merges manually.
+- Do not run full solution tests during planning-only updates unless explicitly requested.
+
+## Plan Documents
+- [Overview](autopilot-hash-upload/00-overview.md): purpose, branch strategy, PR roadmap, non-goals, resolved decisions, and references.
+- [Feasibility And Current State](autopilot-hash-upload/01-feasibility-current-state.md): WinPE feasibility, constraints, current Foundry flow, and target data flow.
+- [UX And Runtime Model](autopilot-hash-upload/02-ux-runtime-model.md): Foundry OSD UX, Foundry Deploy UX, and proposed configuration/runtime records.
+- [Security And Graph](autopilot-hash-upload/03-security-graph.md): certificate handling, permission split, Graph import shape, and request rules.
+- [WinPE And Deploy Workflow](autopilot-hash-upload/04-winpe-deploy-workflow.md): OA3Tool strategy, `PCPKsp.dll`, retained artifacts, failure taxonomy, and ownership boundaries.
+- [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md): phase-by-phase checklist with PR titles and manual checks.
+- [Validation Risk And Documentation](autopilot-hash-upload/06-validation-risk-docs.md): automated test matrix, physical validation matrix, risk register, Docusaurus/user documentation deliverables.
+
+## Phase Order
+| Order | Branch | Pull request title | Detail |
+| --- | --- | --- | --- |
+| 0 | `feature/autopilot-hash-upload-foundation` | `docs(autopilot): plan hardware hash upload from WinPE` | [Overview](autopilot-hash-upload/00-overview.md) |
+| 1 | `feature/autopilot-hash-upload-config` | `feat(autopilot): add provisioning mode configuration` | [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md#phase-1-configuration-model) |
+| 2 | `feature/autopilot-hash-upload-security` | `feat(autopilot): add secure tenant upload onboarding` | [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md#phase-2-security-and-tenant-onboarding) |
+| 3 | `feature/autopilot-hash-upload-ui` | `feat(autopilot): add provisioning method selection` | [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md#phase-3-autopilot-page-ux) |
+| 4 | `feature/autopilot-hash-upload-media` | `feat(winpe): stage autopilot hash capture assets` | [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md#phase-4-media-build-and-winpe-assets) |
+| 5 | `feature/autopilot-hash-upload-runtime` | `feat(deploy): branch autopilot runtime by provisioning mode` | [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md#phase-5-foundry-deploy-runtime-branching) |
+| 6 | `feature/autopilot-hash-upload-capture` | `feat(deploy): capture autopilot hardware hash in WinPE` | [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md#phase-6-hash-capture-service) |
+| 7 | `feature/autopilot-hash-upload-graph` | `feat(autopilot): import hardware hashes with Graph` | [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md#phase-7-graph-upload-service) |
+| 8 | `feature/autopilot-hash-upload-docs` | `docs(autopilot): document WinPE hardware hash upload` | [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md#phase-8-documentation-and-release-guardrails) |
+
+## Implementation Progress Tracker
+Use this table as the cross-phase implementation status board. Detailed task, automated test, and manual checkboxes live in [Implementation Phases](autopilot-hash-upload/05-implementation-phases.md).
+
+| Phase | Branch created | Implementation complete | Verification complete | Manual checks complete | PR opened | Merged back |
+| --- | --- | --- | --- | --- | --- | --- |
+| 0 Foundation | [x] | [x] | [x] | [x] | [ ] | [ ] |
+| 1 Configuration model | [x] | [x] | [x] | [x] | [x] | [ ] |
+| 2 Security and tenant onboarding | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
+| 3 Autopilot page UX | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
+| 4 Media build and WinPE assets | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
+| 5 Foundry Deploy runtime branching | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
+| 6 Hash capture service | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
+| 7 Graph upload service | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
+| 8 Documentation and release guardrails | [ ] | [ ] | [ ] | [ ] | [ ] | [ ] |
+
+## Documentation Reminder
+Phase 8 must update the Docusaurus documentation when the implemented behavior affects user-facing OSD, Deploy, WinPE requirements, setup, troubleshooting, permissions, or release notes. The Docusaurus repository is `E:\Github\Foundry Project\foundry-osd.github.io`; create a dedicated worktree and branch for that repository before editing documentation.
diff --git a/docs/implementation/autopilot-hash-upload/00-overview.md b/docs/implementation/autopilot-hash-upload/00-overview.md
@@ -0,0 +1,76 @@
+# Autopilot Hardware Hash Upload - Overview
+
+Part of the [Autopilot hardware hash upload implementation plan](../autopilot-hardware-hash-upload.md).
+
+Implementation agents must follow the repository instructions in [AGENTS.md](../../../AGENTS.md). Add XML documentation comments for public or non-obvious C# APIs when they clarify intent, contracts, or operational constraints.
+
+## Purpose
+This document defines the feasibility, integration approach, and phased implementation plan for adding Windows Autopilot hardware hash capture and upload from WinPE to Foundry.
+
+This feature is intended to complement the existing offline Autopilot JSON profile staging flow. It must not replace the current behavior.
+
+
+## Branch Strategy
+- Foundation branch: `feature/autopilot-hash-upload-foundation`
+- Foundation worktree: `C:\Users\mchav\.config\superpowers\worktrees\foundry\autopilot-hash-upload-foundation`
+- Phase branches should branch from the foundation branch:
+  - `feature/autopilot-hash-upload-config`
+  - `feature/autopilot-hash-upload-security`
+  - `feature/autopilot-hash-upload-ui`
+  - `feature/autopilot-hash-upload-media`
+  - `feature/autopilot-hash-upload-runtime`
+  - `feature/autopilot-hash-upload-capture`
+  - `feature/autopilot-hash-upload-graph`
+  - `feature/autopilot-hash-upload-docs`
+
+The foundation branch should remain documentation-first. Implementation branches should be small, reviewable, and merged back into the foundation branch in phase order.
+Implementation agents must not merge, squash, or auto-squash pull requests automatically. The repository owner handles PR merges manually.
+
+
+## Pull Request Roadmap
+All PR titles must stay in English and use Conventional Commits. Each phase branch should be merged back into the foundation branch before the next phase branch starts.
+
+| Order | Branch | Pull request title | Scope |
+| --- | --- | --- | --- |
+| 0 | `feature/autopilot-hash-upload-foundation` | `docs(autopilot): plan hardware hash upload from WinPE` | Feasibility, phased integration plan, risk register, test matrix. |
+| 1 | `feature/autopilot-hash-upload-config` | `feat(autopilot): add provisioning mode configuration` | Expert and Deploy configuration models, backward compatibility, readiness rules. |
+| 2 | `feature/autopilot-hash-upload-security` | `feat(autopilot): add secure tenant upload onboarding` | Tenant sign-in, app registration creation, certificate lifecycle, secret handling, permission validation. |
+| 3 | `feature/autopilot-hash-upload-ui` | `feat(autopilot): add provisioning method selection` | Autopilot page expanders, mutually exclusive method selection, localized strings. |
+| 4 | `feature/autopilot-hash-upload-media` | `feat(winpe): stage autopilot hash capture assets` | WinPE optional component requirements, x64/ARM64 OA3Tool discovery, media payload layout. |
+| 5 | `feature/autopilot-hash-upload-runtime` | `feat(deploy): branch autopilot runtime by provisioning mode` | Deploy startup snapshot, launch validation, runtime state, late deployment step, dry-run manifests. |
+| 6 | `feature/autopilot-hash-upload-capture` | `feat(deploy): capture autopilot hardware hash in WinPE` | C# OA3Tool execution service, `PCPKsp.dll` copy, `OA3.xml` parsing, CSV/diagnostic artifacts. |
+| 7 | `feature/autopilot-hash-upload-graph` | `feat(autopilot): import hardware hashes with Graph` | C# Graph client, import polling, retry policy, operator-facing errors. |
+| 8 | `feature/autopilot-hash-upload-docs` | `docs(autopilot): document WinPE hardware hash upload` | User docs, permissions matrix, troubleshooting, screenshots, release notes. |
+
+Expected PR description structure:
+- Summary: one short paragraph.
+- Reason: why this phase is needed and what risk it removes.
+- Main changes: concise bullet list.
+- Testing notes: exact automated commands and manual checks.
+
+
+## Non-Goals
+- Do not remove or redesign the existing offline JSON profile workflow.
+- Do not involve Foundry Connect.
+- Do not implement hardware hash capture or upload with PowerShell scripts, PowerShell Gallery modules, or community wrapper modules.
+- Do not delete existing Intune, Autopilot, or Entra records automatically.
+- Do not add group membership automation.
+- Do not claim full Microsoft support for WinPE-based hash capture.
+- Do not limit the implementation to x64. x64 and ARM64 are both in scope.
+- Do not redistribute `PCPKsp.dll` in generated media. Copy it from the applied Windows image during deployment.
+
+
+## Resolved Decisions
+- No capture-only mode in the first implementation. Foundry always captures and uploads, while retaining OA3 and CSV diagnostics for troubleshooting.
+- `PCPKsp.dll` copy/load failure is blocking for the Autopilot hash upload workflow because it is a prerequisite for this capture path.
+- Duplicate device cleanup is not part of the final implementation. Foundry surfaces duplicate/import errors clearly, retains diagnostics, and continues OS deployment without deleting Intune, Autopilot, or Entra records.
+
+
+## Source References
+- Microsoft Learn: [Manually register devices with Windows Autopilot](https://learn.microsoft.com/en-us/autopilot/add-devices)
+- Microsoft Learn: [Microsoft Graph importedWindowsAutopilotDeviceIdentity import](https://learn.microsoft.com/en-us/graph/api/intune-enrollment-importedwindowsautopilotdeviceidentity-import?view=graph-rest-1.0)
+- Microsoft Learn: [Using the OA 3.0 tool on the factory floor](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/oa3-using-on-factory-floor?view=windows-11)
+- Microsoft Learn: [WinPE optional components reference](https://learn.microsoft.com/en-us/windows-hardware/manufacture/desktop/winpe-add-packages--optional-components-reference?view=windows-11)
+- Local artifact: `C:\Users\mchav\Downloads\foundry-autopilot-hash-winpe-en.md`
+- Local artifact: `C:\Users\mchav\Downloads\HashUpload_WinPE.ps1`
+
diff --git a/docs/implementation/autopilot-hash-upload/01-feasibility-current-state.md b/docs/implementation/autopilot-hash-upload/01-feasibility-current-state.md
@@ -0,0 +1,96 @@
+# Autopilot Hardware Hash Upload - Feasibility And Current State
+
+Part of the [Autopilot hardware hash upload implementation plan](../autopilot-hardware-hash-upload.md).
+
+Implementation agents must follow the repository instructions in [AGENTS.md](../../../AGENTS.md). Add XML documentation comments for public or non-obvious C# APIs when they clarify intent, contracts, or operational constraints.
+
+## Feasibility Summary
+- WinPE hardware hash capture is technically feasible with `OA3Tool.exe /Report`.
+- This is an operational workaround, not Microsoft's standard recommended Autopilot registration path.
+- The current Foundry architecture already has the right integration boundaries:
+  - Foundry OSD configures and builds WinPE media.
+  - Foundry Deploy runs inside WinPE and already stages the selected JSON profile into the applied Windows image.
+  - Foundry Connect is not part of the feature scope.
+- The final implementation should support x64 and ARM64 by using architecture-specific ADK assets.
+- The final implementation should support available WinPE networking, including Ethernet and Wi-Fi, and should avoid destructive cleanup of existing Intune, Autopilot, or Entra records.
+- Hash capture and upload should run near the end of the OS deployment workflow, after the Windows image is applied and the target Windows `System32` directory is available.
+
+
+## Feasibility Constraints
+WinPE capture is useful because it lets an operator register a device before the installed OS reaches OOBE. The tradeoff is that Microsoft documents the normal Autopilot hash capture path around a full Windows environment, OOBE diagnostics, Audit Mode, or OEM/reseller registration.
+
+Operational constraints:
+- Ethernet and Wi-Fi should be treated as equivalent supported network paths when WinPE has the required network stack, drivers, and credentials.
+- Network readiness validation should focus on actual connectivity to Microsoft Graph, not on the adapter type.
+- TPM-dependent scenarios require extra caution. Self-deploying and pre-provisioning depend heavily on correct TPM capture.
+- Drivers matter. Missing storage, chipset, NIC, or TPM visibility can produce an empty or incomplete hash.
+- ADK version and architecture matter. The OA3Tool staged into media should come from the same installed ADK family used to build the WinPE image, with separate x64 and ARM64 resolution.
+- `PCPKsp.dll` should not be bundled into media at build time. Foundry Deploy should copy it from `<target Windows>\Windows\System32\PCPKsp.dll` to `X:\Windows\System32\PCPKsp.dll` after the OS image has been applied.
+
+Support positioning:
+- Supported by Foundry as a best-effort workflow for user-driven Autopilot registration.
+- Not positioned as the Microsoft-standard or OEM-supported registration workflow.
+- Not recommended for self-deploying or pre-provisioning until physical validation proves TPM/EKPub capture quality.
+
+
+## Current State
+Foundry currently supports one Autopilot provisioning method:
+
+```text
+Foundry OSD -> WinPE media config -> Foundry Deploy -> Windows\Provisioning\Autopilot\AutopilotConfigurationFile.json
+```
+
+Key files:
+- `src/Foundry/Views/AutopilotPage.xaml`
+- `src/Foundry/ViewModels/AutopilotConfigurationViewModel.cs`
+- `src/Foundry.Core/Models/Configuration/AutopilotSettings.cs`
+- `src/Foundry.Core/Models/Configuration/Deploy/DeployAutopilotSettings.cs`
+- `src/Foundry.Core/Services/Configuration/DeployConfigurationGenerator.cs`
+- `src/Foundry.Core/Services/WinPe/WinPeMountedImageAssetProvisioningService.cs`
+- `src/Foundry.Deploy/Services/Autopilot/AutopilotProfileCatalogService.cs`
+- `src/Foundry.Deploy/Services/Deployment/DeploymentLaunchPreparationService.cs`
+- `src/Foundry.Deploy/Services/Deployment/Steps/StageAutopilotConfigurationStep.cs`
+
+Current data flow:
+
+```text
+Foundry app
+  -> ExpertDeployConfigurationStateService
+  -> DeployConfigurationGenerator
+  -> StartMediaViewModel
+  -> WinPeWorkspacePreparationService
+  -> WinPeMountedImageAssetProvisioningService
+  -> X:\Foundry\Config\foundry.deploy.config.json
+  -> X:\Foundry\Config\Autopilot\<profile>\AutopilotConfigurationFile.json
+  -> Foundry.Deploy startup
+  -> AutopilotProfileCatalogService
+  -> DeploymentLaunchPreparationService
+  -> StageAutopilotConfigurationStep
+  -> <offline Windows>\Windows\Provisioning\Autopilot\AutopilotConfigurationFile.json
+```
+
+Target hash upload data flow:
+
+```text
+Foundry Deploy deployment run
+  -> apply Windows image
+  -> configure target computer name, recovery, drivers, firmware, and partition sealing
+  -> enter the late Autopilot provisioning step
+  -> resolve the target Windows root
+  -> copy <target Windows>\Windows\System32\PCPKsp.dll to X:\Windows\System32\PCPKsp.dll
+  -> run C# OA3Tool capture service
+  -> parse OA3.xml and create diagnostic CSV
+  -> run C# Graph import service
+  -> poll import state when configured
+  -> retain OA3, CSV, and upload result logs under the applied OS
+  -> finalize deployment
+```
+
+Current assumptions to break carefully:
+- `IsAutopilotEnabled` currently implies "a JSON profile must be selected".
+- `AutopilotProfileCatalogService` only loads folder-based JSON profile assets.
+- `StageAutopilotConfigurationStep` has a profile-staging name and should become the late, mode-aware Autopilot provisioning boundary.
+- Media readiness only checks whether a selected profile exists when Autopilot is enabled.
+- Deploy summary and telemetry only track `autopilot_enabled`, not the provisioning method.
+
+