docs(os-recovery): document WinRE recovery flow

docs/deploy/deployment-flow.md

@@ -161,3 +161,4 @@ If deployment fails, Foundry Deploy shows the failed step and error message. Use
 
 - Review the [Expert Mode](../configure/expert-mode) section to understand which values can be staged from Foundry OSD.
 - Open [Catalog Overview](../reference/catalog-overview) to understand where operating system and driver choices come from.
+- Review [OS Recovery](./os-recovery) before enabling the WinRE last-resort redeployment path.

docs/deploy/os-recovery.md

@@ -0,0 +1,37 @@
+---
+title: OS Recovery
+description: Recover a machine using a WinRE-first, last-resort deployment flow.
+---
+
+# OS Recovery
+
+OS Recovery is the last-resort deployment path when normal provisioning cannot continue.
+
+It uses the Windows Recovery Environment (WinRE) as the entry point and follows a dedicated menu path:
+
+**Troubleshoot > Advanced options > Foundry Recovery**
+
+## What happens in WinRE
+
+When selected, WinRE starts the Foundry recovery image and runs the recovery bootstrap.
+
+- `Foundry.Connect`, the bootstrap script, 7-Zip, time zone data, and minimal sanitized configuration are embedded in the WinRE payload.
+- `Foundry.Deploy` is not embedded. It is downloaded during recovery boot, then used to redeploy the OS.
+- The recovery partition stays intact.
+- The existing Windows partition is replaced during redeployment.
+- A Foundry recovery marker is written next to `winre.wim`; recovery startup uses it to identify the provisioned disk and fails closed if the target is ambiguous.
+
+![WinRE OS recovery flow](/img/deploy/os-recovery-winre-flow.png)
+
+## Key limits
+
+- A single custom WinRE recovery tool is supported.
+- This is not a root recovery menu replacement.
+- No enterprise personalization payloads are applied from WinRE.
+- Autopilot payloads, network roaming profiles, certificates, OA3 tools, media secrets, and `Foundry.Deploy` binaries are not embedded in WinRE.
+- Network access is required for downloading the deployment payload.
+- BitLocker on the previous OS partition does not need to be readable for the recovery flow.
+
+## Validation
+
+Use `scripts/Test-FoundryOsRecoveryWinRe.ps1` to inspect a mounted or extracted WinRE image. The script checks the WinRE tool files, bootstrap, embedded `Foundry.Connect`, minimal configuration, 7-Zip runtime, and excluded payloads. By default it also checks `reagentc /info`; use `-SkipReAgentC` only when validating an offline image on a machine that is not the deployed target.

docs/technical/deployment-orchestrator.md

@@ -26,11 +26,12 @@ The deployment pipeline runs in this order:
 11. Download driver pack
 12. Extract driver pack
 13. Apply driver pack or stage deferred first-boot execution
-14. Download firmware update
-15. Apply firmware update
-16. Seal recovery partition
-17. Provision Autopilot
-18. Finalize deployment and write logs
+14. Provision OS Recovery, when enabled
+15. Download firmware update
+16. Apply firmware update
+17. Seal recovery partition
+18. Provision Autopilot
+19. Finalize deployment and write logs
 
 ## Runtime state
 
@@ -53,3 +54,21 @@ Interactive hardware hash upload mode stages the Foundry OOBE registration assis
 ## Failure behavior
 
 If a step fails, orchestration stops, the failure is logged, and Foundry Deploy reports the failed step to the operator. Logs are rebound to the final Windows target location when the Windows partition is available.
+## OS Recovery (WinRE)
+
+The deployment orchestrator also supports a WinRE-based recovery mode for devices that cannot complete normal deployment. This is surfaced as:
+
+`Troubleshoot > Advanced options > Foundry Recovery`
+
+The runtime in this mode differs from normal deployment:
+
+- `Foundry.Connect` is shipped inside the WinRE image and starts the recovery entrypoint.
+- `Foundry.Deploy` is not embedded; it is fetched during recovery to perform redeployment.
+- Recovery mode preserves EFI, MSR, and Recovery partitions, then formats and replaces the Windows partition.
+- Autopilot payloads, network roaming profiles, certificates, OA3 tools, media secrets, and enterprise personalization artifacts are intentionally excluded from the WinRE image.
+
+Operational limits:
+
+- Only one custom recovery tool entry is currently available.
+- Internet connectivity is required for bootstrap flow to download `Foundry.Deploy`.
+- The previous BitLocker-protected OS volume does not need to be readable during recovery.

sidebars.ts

@@ -71,7 +71,7 @@ const sidebars: SidebarsConfig = {
         slug: '/deploy',
         description: 'Select deployment options and run the Windows deployment.',
       },
-      items: ['deploy/deployment-flow'],
+      items: ['deploy/deployment-flow', 'deploy/os-recovery'],
     },
     {
       type: 'category',