foundry-osd · mchave3 · Jun 9, 2026 · Jun 27, 2026
diff --git a/docs/autopilot/zero-touch-hardware-hash-upload.md b/docs/autopilot/zero-touch-hardware-hash-upload.md
@@ -33,8 +33,8 @@ You need:
 - Foundry OSD.
 - Windows ADK and Windows PE add-on.
 - A Microsoft Entra tenant where the administrator can manage app registrations and service principal permissions.
-- An administrator who can grant admin consent for the delegated Microsoft Graph permissions used during tenant connection: `Application.ReadWrite.All`, `AppRoleAssignment.ReadWrite.All`, `DeviceManagementServiceConfig.Read.All`, and `User.Read`.
-- An app registration used by generated media with the Microsoft Graph application permission `DeviceManagementServiceConfig.ReadWrite.All` granted by admin consent.
+- An administrator who can grant admin consent for the delegated Microsoft Graph permissions used only by the Foundry OSD tenant onboarding session: `Application.ReadWrite.All`, `AppRoleAssignment.ReadWrite.All`, `DeviceManagementServiceConfig.Read.All`, and `User.Read`.
+- An app registration used by generated media with the Microsoft Graph application permission `DeviceManagementServiceConfig.ReadWrite.All` granted by admin consent. Deployment-time upload uses app-only certificate authentication against that app registration.
 - A Foundry-managed certificate that is not expired.
 - A PFX file and password selected during media creation.
 - Network access from WinPE to Microsoft Entra and Microsoft Graph during deployment.

diff --git a/docs/build-media/media-authoring-flow.md b/docs/build-media/media-authoring-flow.md
@@ -0,0 +1,83 @@
+---
+title: Media Authoring Flow
+description: Understand how Foundry OSD turns workstation settings into bootable media consumed by Foundry Connect and Foundry Deploy.
+---
+
+# Media authoring flow
+
+Foundry OSD is the media authoring application. It runs on the admin workstation before the target device boots.
+
+The goal of media authoring is to produce ISO or USB media that contains:
+
+- A prepared WinPE boot image.
+- Foundry Connect for runtime network readiness.
+- Foundry Deploy for the deployment wizard and execution pipeline.
+- Generated configuration for networking, deployment defaults, customization, and Autopilot.
+- Runtime payload and cache layout needed by the selected media type.
+
+## Authoring sequence
+
+Use this sequence when preparing media:
+
+1. Confirm the workstation meets [Requirements](../start/requirements).
+2. Decide whether the standard workflow is enough.
+3. Configure expert settings only when the media needs predefined behavior.
+4. Select the target architecture, WinPE language, driver vendors, and output type.
+5. Select Autopilot mode when the media must stage or upload Autopilot identity.
+6. Build ISO, create USB, or update an existing Foundry USB.
+7. Boot the target device from the generated media.
+8. Let Foundry Connect validate runtime networking.
+9. Let Foundry Deploy run the deployment workflow.
+
+:::info[Screenshot placeholder]
+Capture Foundry OSD with the media readiness summary visible after requirements, output type, architecture, language, drivers, Connect, Deploy, and Autopilot readiness have been evaluated.
+:::
+
+## Standard path
+
+Use [Standard Workflow](./standard-workflow) when the operator only needs normal ISO or USB media.
+
+Standard media still prepares the runtime applications and configuration files needed by Foundry Connect and Foundry Deploy. It avoids predefined deployment restrictions unless the environment requires them.
+
+## Expert path
+
+Use [Configure Media](../configure/expert-mode) when the media must carry predefined behavior.
+
+Expert settings are authored before the media is built. Foundry OSD persists those settings and generates the runtime configuration consumed later by Foundry Connect and Foundry Deploy.
+
+| Authoring page | Runtime consumer | What it influences |
+| --- | --- | --- |
+| General | Foundry OSD and Foundry Deploy | Media defaults, WinPE language, architecture, deployment time zone |
+| Network | Foundry Connect and Foundry Deploy | Wired 802.1X, Wi-Fi provisioning, Windows network profile roaming |
+| Customization | Foundry Deploy and Windows first boot | Machine naming, operating system selection policy, OOBE defaults, AI component removal, AppX removal |
+| Autopilot | Foundry OSD, Foundry Deploy, Windows OOBE | JSON profile staging, zero-touch hardware hash upload, interactive hardware hash upload |
+
+## Media outputs
+
+Foundry OSD supports three output flows:
+
+- **Create ISO** packages the prepared WinPE workspace into an ISO file.
+- **Create USB** partitions and formats the selected USB disk, then copies the prepared media.
+- **Update USB** refreshes an existing Foundry USB boot partition and runtime payloads without repartitioning or formatting the cache partition.
+
+Use [Media Creation](./media-creation) for the detailed ISO, USB, and update behavior.
+
+## Runtime boundary
+
+After the target boots, media authoring is finished.
+
+Foundry Connect and Foundry Deploy are runtime applications. They consume what Foundry OSD staged, but they do not return to the workstation authoring flow.
+
+The runtime order is:
+
+1. Foundry Connect validates networking.
+2. Foundry Deploy loads the generated deployment configuration.
+3. Foundry Deploy lets the operator confirm runtime choices.
+4. Foundry Deploy applies Windows and stages any post-WinPE handoff assets.
+5. Windows continues through first boot, OOBE, or Autopilot behavior.
+
+## Next steps
+
+- Open [Media Creation](./media-creation) for ISO, USB, and update details.
+- Open [Network Readiness](../runtime/network-readiness) for the first runtime step after boot.
+- Open [Deployment Flow](../runtime/deployment-flow) for the Foundry Deploy wizard.
diff --git a/docs/build-media/media-creation.md b/docs/build-media/media-creation.md
@@ -123,5 +123,6 @@ Capture the advanced media options section with CA2023, partition style, format
 
 ## Next steps
 
-- Open [Network Readiness](../connect/network-readiness) to understand what happens after the target boots.
-- Review the [Expert Mode](../configure/expert-mode) section when media should include predefined deployment behavior.
+- Open [Media Authoring Flow](./media-authoring-flow) to understand how generated media carries configuration into runtime.
+- Open [Network Readiness](../runtime/network-readiness) to understand what happens after the target boots.
+- Review [Configure Media](../configure/expert-mode) when media should include predefined deployment behavior.
diff --git a/docs/build-media/standard-workflow.md b/docs/build-media/standard-workflow.md
@@ -56,5 +56,6 @@ Even without expert configuration, Foundry OSD still:
 ## Next steps
 
 - Open [Media Creation](./media-creation) for ISO and USB details.
-- Review the [Expert Mode](../configure/expert-mode) section for predefined deployment settings.
+- Review [Media Authoring Flow](./media-authoring-flow) to understand what Foundry OSD stages into generated media.
+- Review [Configure Media](../configure/expert-mode) for predefined deployment settings.
 - Open [Quick Start](../start/quick-start) for the shortest end-to-end guide.
diff --git a/docs/configure/autopilot.md b/docs/configure/autopilot.md
diff --git a/docs/configure/customization.md b/docs/configure/customization.md
@@ -5,7 +5,7 @@ description: Configure machine naming, operating system selection, Windows OOBE
 
 # Customization
 
-Customization settings define deployment-time behavior that should be prepared before the target device boots.
+Customization settings define deployment-time behavior that should be authored before media is built and prepared before the target device boots.
 
 ## Machine naming
 
@@ -28,7 +28,7 @@ Capture the Customization page with the machine naming controls expanded.
 
 ## Operating system selection
 
-Foundry OSD can stage the Operating System Catalog choices shown later in Foundry Deploy.
+Foundry OSD can stage the operating system choices shown later in Foundry Deploy.
 
 Available controls include:
 
@@ -131,7 +131,7 @@ Capture the Customization page with the provisioned AppX removal controls expand
 
 Machine naming affects the Foundry Deploy wizard. OOBE customization is applied to the offline Windows installation during deployment by writing unattend and policy values.
 
-Operating system selection affects the Foundry Deploy Operating System Catalog page only when its main switch is enabled. Allowed values restrict the version, language, license channel, and edition choices available to the deployment operator. Default values preselect choices only when those values are valid in the current catalog scope. A group with exactly one allowed value is treated as both the allowed value and the default value.
+Operating system selection affects the Foundry Deploy `Operating system` page only when its main switch is enabled. Allowed values restrict the version, language, license channel, and edition choices available to the deployment operator. Default values preselect choices only when those values are valid in the current catalog scope. A group with exactly one allowed value is treated as both the allowed value and the default value.
 
 AI component removal is split across the deployment phases. Foundry Deploy writes AI policy values into the offline target registry hives while it is still running in WinPE. Machine-wide policies are written through the offline `SOFTWARE` and `SYSTEM` hives, and future-user defaults are written by loading `Users\Default\NTUSER.DAT` under a temporary `HKU\FoundryDefault` mount. Foundry does not write these defaults through `HKEY_USERS\.DEFAULT`.
 
@@ -155,4 +155,4 @@ Staging this behavior from Foundry OSD makes the live deployment path faster and
 
 ## Next step
 
-Open [Deployment Flow](../deploy/deployment-flow) to see where customization can affect runtime choices.
+Open [Deployment Flow](../runtime/deployment-flow) to see where customization can affect runtime choices.
diff --git a/docs/configure/expert-mode.md b/docs/configure/expert-mode.md
@@ -1,16 +1,16 @@
 ---
-title: Expert Mode
-description: Use expert mode in Foundry OSD when deployment media needs predefined network, time zone, operating system selection, Autopilot, or customization behavior.
+title: Expert Mode Overview
+description: Use Foundry OSD expert mode to author configuration that is staged into generated deployment media.
 ---
 
-# Expert mode
+# Expert mode overview
 
-Expert mode turns Foundry OSD into a configuration authoring surface.
+Expert mode turns Foundry OSD into a pre-boot media configuration surface.
 
-Use it only when the standard workflow is not enough.
+Use it only when the generated media needs predefined runtime behavior.
 
 :::note[Do not start here by default]
-Create media with the standard workflow first unless the deployment environment requires predefined runtime behavior.
+Create media with the standard workflow first unless the deployment environment requires predefined network, deployment, customization, or Autopilot behavior.
 :::
 
 ## Expert sections
@@ -37,6 +37,8 @@ When you build ISO or USB media, Foundry OSD generates the runtime configuration
 
 Those files are written into the boot image during media creation. No operator action is required to create the Foundry Connect or Foundry Deploy runtime configuration files.
 
+After the target boots, these values are consumed by Foundry Connect, Foundry Deploy, Windows setup, or the Autopilot assistant. They are not edited from the workstation while deployment is running.
+
 ## Staged deployment preferences
 
 Use expert mode when the WinPE deployment session should start with predefined preferences for:

diff --git a/docs/configure/general.md b/docs/configure/general.md
@@ -7,6 +7,8 @@ description: Configure media creation defaults and deployment time zone behavior
 
 General settings control media creation defaults and deployment behavior that is not specific to networking, Autopilot, or customization.
 
+Foundry OSD stages these values into generated media. Foundry Deploy consumes the deployment time zone later during the WinPE runtime.
+
 ## Media defaults
 
 Use General to choose the boot media architecture, WinPE language, boot signature, and WinPE driver options before creating ISO or USB media.
@@ -26,4 +28,4 @@ Foundry OSD stores the time zone identifier used by Foundry Deploy. During deplo
 
 - Open [Network Configuration](./network) for wired and Wi-Fi settings.
 - Open [Customization](./customization) for machine naming, operating system selection, Windows OOBE behavior, AI component removal, and provisioned AppX removal.
-- Open [Deployment Flow](../deploy/deployment-flow) to see where these settings affect runtime behavior.
+- Open [Deployment Flow](../runtime/deployment-flow) to see where these settings affect runtime behavior.
diff --git a/docs/configure/network.md b/docs/configure/network.md
@@ -5,7 +5,7 @@ description: Configure wired 802.1X, Wi-Fi, and Windows profile roaming settings
 
 # Network configuration
 
-Network settings are authored in Foundry OSD and used later by Foundry Connect in WinPE and Foundry Deploy after Windows has been applied.
+Network settings are authored in Foundry OSD before media is built. They are used later by Foundry Connect in WinPE and by Foundry Deploy after Windows has been applied.
 
 :::note[Configure before boot]
 Network settings are selected on the admin workstation, but they are validated on the target device after boot.
@@ -93,4 +93,4 @@ Profile roaming imports the captured profile material into Windows. Personal Wi-
 
 ## Next step
 
-Open [Network Readiness](../connect/network-readiness) to understand how these settings are used after boot.
+Open [Network Readiness](../runtime/network-readiness) to understand how these settings are used after boot.
diff --git a/docs/deploy/autopilot-hash-upload.md b/docs/deploy/autopilot-hash-upload.md
diff --git a/docs/developer/local-winpe-testing.md b/docs/developer/local-winpe-testing.md
@@ -25,21 +25,25 @@ These scripts publish self-contained single-file builds for:
 
 The repository also includes `Enable-LocalWinPeDeploy.ps1`, which is intended for development workflows where the desktop app should embed or reference debug WinPE application builds instead of normal release assets.
 
-## What the helper script actually sets
+## Runtime override contract
 
-When you run `Enable-LocalWinPeDeploy.ps1`, it enables debug runtime overrides and sets the project paths that `Foundry` uses later during media staging:
+Foundry's media staging code reads these debug runtime override variables:
 
 - `FOUNDRY_WINPE_DEBUG_CONNECT=1`
 - `FOUNDRY_WINPE_DEBUG_CONNECT_PROJECT=<repo>\\src\\Foundry.Connect\\Foundry.Connect.csproj`
 - `FOUNDRY_WINPE_DEBUG_DEPLOY=1`
 - `FOUNDRY_WINPE_DEBUG_DEPLOY_PROJECT=<repo>\\src\\Foundry.Deploy\\Foundry.Deploy.csproj`
 
-If you also provide archive paths, the script sets these optional overrides:
+If you use archive paths instead of project publishing, set these optional overrides:
 
 - `FOUNDRY_WINPE_DEBUG_CONNECT_ARCHIVE`
 - `FOUNDRY_WINPE_DEBUG_DEPLOY_ARCHIVE`
 
-That means debug testing can be driven from project builds, from prebuilt archives, or from a mix of both.
+Debug testing can be driven from project builds, from prebuilt archives, or from a mix of both. Archive overrides take precedence over project paths for the matching runtime.
+
+:::warning[Helper script variable mismatch]
+The current `Enable-LocalWinPeDeploy.ps1` helper exports `FOUNDRY_WINPE_LOCAL_*` variables, while the media staging code reads `FOUNDRY_WINPE_DEBUG_*` variables. Until the app source aligns that helper with the runtime override contract, set the `FOUNDRY_WINPE_DEBUG_*` variables directly in the shell that launches Foundry OSD.
+:::
 
 ## Script inputs
 
@@ -66,7 +70,3 @@ This debug flow is useful when you are changing:
 ## Scope of the debug flow
 
 The debug override path exists for development and validation. It is not the normal user workflow and should not be confused with the release-based media creation path.
-
-:::info[Screenshot placeholder]
-Add a capture of the terminal after `Enable-LocalWinPeDeploy.ps1` runs, with the debug override environment variables visible.
-:::
diff --git a/docs/intro.md b/docs/intro.md
@@ -32,12 +32,11 @@ Open [Requirements](./start/requirements) first, then follow [Quick Start](./sta
 
 - [Start Here](./start/requirements): install Foundry OSD and complete the first deployment.
 - [Build Media](./build-media/standard-workflow): create ISO or USB deployment media.
-- [Connect](./connect/network-readiness): validate runtime networking before deployment.
-- [Deploy](./deploy/deployment-flow): select deployment options and run the Windows deployment.
+- [Configure Media](./configure/expert-mode): author advanced settings before media creation.
+- [Runtime](./runtime/network-readiness): validate networking, run deployment, and inspect post-WinPE behavior.
 - [Autopilot](./autopilot/overview): choose JSON profile injection, zero-touch hardware hash upload, or interactive hardware hash upload.
-- [Configure Deployment](./configure/expert-mode): use expert settings only when the standard path is not enough.
 - [Reference](./reference/product-boundaries): review product boundaries and runtime behavior.
-- [Technical Deep Dives](./technical): read implementation-level details for advanced troubleshooting and maintainers.
+- [Deployment Orchestrator](./reference/deployment-orchestrator): read implementation-level deployment ordering details for advanced troubleshooting and maintainers.
 
 ## What to read next
 

diff --git a/docs/reference/architecture-overview.md b/docs/reference/architecture-overview.md
@@ -11,19 +11,20 @@ This page is reference material. Start with [Quick Start](../start/quick-start)
 
 | Component | Runs where | Role |
 | --- | --- | --- |
-| Foundry OSD | Admin workstation | Checks prerequisites, builds media, and provisions Foundry Connect |
+| Foundry OSD | Admin workstation | Checks prerequisites, builds media, and provisions runtime configuration |
 | Foundry Connect | WinPE target device | Validates network readiness before deployment continues |
 | Foundry Deploy | WinPE target device | Loads catalogs, collects deployment choices, and executes deployment |
 | catalog | Separate automation repository | Generates XML feeds for operating system, driver pack, and WinPE metadata |
 
 ## Runtime sequence
 
-1. Foundry OSD prepares ISO or USB media and provisions Foundry Connect for the selected architecture.
+1. Foundry OSD prepares ISO or USB media and provisions runtime assets for the selected architecture.
 2. The target device boots WinPE.
 3. Bootstrap launches Foundry Connect.
 4. Foundry Connect validates network readiness.
 5. Bootstrap resolves Foundry Deploy from release assets or an available USB cache.
 6. Bootstrap opens Foundry Deploy, which loads catalogs and runs the deployment workflow.
+7. Windows consumes staged post-WinPE assets during first boot when deployment options require them.
 
 ## Why the split exists
 

diff --git a/docs/reference/catalog-overview.md b/docs/reference/catalog-overview.md
@@ -29,4 +29,4 @@ The runtime consumes normalized XML outputs instead of hardcoding vendor-specifi
 
 ## Next step
 
-Open [Deployment Flow](../deploy/deployment-flow) to see where catalog-backed choices appear.
+Open [Deployment Flow](../runtime/deployment-flow) to see where catalog-backed choices appear.
diff --git a/docs/technical/deployment-orchestrator.md → docs/reference/deployment-orchestrator.md b/docs/technical/deployment-orchestrator.md → docs/reference/deployment-orchestrator.md
@@ -25,12 +25,13 @@ The deployment pipeline runs in this order:
 10. Configure recovery environment
 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
+13. Stage pre-OOBE customization
+14. Apply driver pack or stage deferred first-boot execution
+15. Download firmware update
+16. Apply firmware update
+17. Seal recovery partition
+18. Provision Autopilot
+19. Finalize deployment and write logs
 
 ## Runtime state
Original file line number	Diff line number	Diff line change
Expand Up		@@ -29,4 +29,4 @@ The runtime consumes normalized XML outputs instead of hardcoding vendor-specifi

		## Next step

		Open [Deployment Flow](../deploy/deployment-flow) to see where catalog-backed choices appear.
		Open [Deployment Flow](../runtime/deployment-flow) to see where catalog-backed choices appear.