From 360db420d79ade4b004712e0162b79d7e6ee08fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20CHAVE?= Date: Tue, 9 Jun 2026 17:34:22 +0200 Subject: [PATCH 1/2] docs(audit): align documentation with current behavior --- .../autopilot/zero-touch-hardware-hash-upload.md | 4 ++-- docs/configure/customization.md | 4 ++-- docs/deploy/deployment-flow.md | 6 +++--- docs/developer/local-winpe-testing.md | 16 ++++++++-------- docs/start/quick-start.md | 2 +- docs/technical/deployment-orchestrator.md | 13 +++++++------ docs/technical/post-winpe-handoff.md | 4 ++-- 7 files changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/autopilot/zero-touch-hardware-hash-upload.md b/docs/autopilot/zero-touch-hardware-hash-upload.md index 3186457..daa978d 100644 --- 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/configure/customization.md b/docs/configure/customization.md index 692a186..62b36c6 100644 --- a/docs/configure/customization.md +++ b/docs/configure/customization.md @@ -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`. diff --git a/docs/deploy/deployment-flow.md b/docs/deploy/deployment-flow.md index 5183e29..48f62ed 100644 --- a/docs/deploy/deployment-flow.md +++ b/docs/deploy/deployment-flow.md @@ -18,7 +18,7 @@ Deployment choices affect the target disk and operating system installation. Rev Follow the wizard in order: 1. Target -2. Operating System Catalog +2. Operating system 3. Driver Pack 4. Summary @@ -45,9 +45,9 @@ Select only the disk that should be erased and receive Windows. Foundry Deploy b ![Foundry Deploy target selection](/img/docs/foundry-deploy/target-selection.png) -## Operating System Catalog +## Operating system -Use the `Operating System Catalog` page to choose the Windows image from the catalog-backed filters. +Use the `Operating system` page to choose the Windows image from the catalog-backed filters. Review or set: diff --git a/docs/developer/local-winpe-testing.md b/docs/developer/local-winpe-testing.md index e9f6566..845c44f 100644 --- 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=\\src\\Foundry.Connect\\Foundry.Connect.csproj` - `FOUNDRY_WINPE_DEBUG_DEPLOY=1` - `FOUNDRY_WINPE_DEBUG_DEPLOY_PROJECT=\\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/start/quick-start.md b/docs/start/quick-start.md index 48056c7..9bfb527 100644 --- a/docs/start/quick-start.md +++ b/docs/start/quick-start.md @@ -79,7 +79,7 @@ Read [Network Readiness](../connect/network-readiness) for the runtime behavior. When Foundry Deploy opens, follow the wizard in order: 1. Target -2. Operating System Catalog +2. Operating system 3. Driver Pack 4. Summary diff --git a/docs/technical/deployment-orchestrator.md b/docs/technical/deployment-orchestrator.md index a41baee..103931a 100644 --- a/docs/technical/deployment-orchestrator.md +++ b/docs/technical/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 diff --git a/docs/technical/post-winpe-handoff.md b/docs/technical/post-winpe-handoff.md index 7c477ed..ee74a77 100644 --- a/docs/technical/post-winpe-handoff.md +++ b/docs/technical/post-winpe-handoff.md @@ -46,7 +46,7 @@ The runner executes enabled PowerShell scripts in deterministic order: 1. Script priority 2. Script id -Driver provisioning is priority `100` and runs before customization scripts. Customization scripts are registered only when the corresponding Foundry OSD or Foundry Deploy configuration enables them. +Driver provisioning is priority `100` and runs before network profile import and customization scripts. Network profile import is priority `200`, customization scripts are priority `300`, and cleanup is priority `900`. Customization scripts are registered only when the corresponding Foundry OSD or Foundry Deploy configuration enables them. Provisioned AppX removal is a customization script. It runs before OOBE and uses online provisioned package removal so new user profiles are created without the selected packages. Foundry stages only supported provisioned package identifiers, such as `Microsoft.BingWeather`, in `Data\Remove-AppX.packages.json`; the script skips packages that are not provisioned in the applied image. @@ -78,7 +78,7 @@ Most driver packs are applied offline with DISM. Some packages, such as selected The pre-OOBE runner then invokes the driver PowerShell script during first boot. -When deferred driver provisioning and customization scripts are both enabled, Foundry stages one shared pre-OOBE runner. Driver provisioning runs first, AppX removal and AI AppX removal run in the customization bucket, and cleanup runs last. +When deferred driver provisioning, network profile roaming, and customization scripts are enabled, Foundry stages one shared pre-OOBE runner. Driver provisioning runs first, network profile import runs next, AppX removal and AI AppX removal run in the customization bucket, and cleanup runs last. ## Operational artifacts From a2fa125b552400e8a71dc5f2e5783fb7725231ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micka=C3=ABl=20CHAVE?= Date: Sat, 27 Jun 2026 18:52:29 +0200 Subject: [PATCH 2/2] docs: reorganize documentation structure --- docs/build-media/media-authoring-flow.md | 83 +++++++++++ docs/build-media/media-creation.md | 5 +- docs/build-media/standard-workflow.md | 3 +- docs/configure/autopilot.md | 15 -- docs/configure/customization.md | 4 +- docs/configure/expert-mode.md | 14 +- docs/configure/general.md | 4 +- docs/configure/network.md | 4 +- docs/deploy/autopilot-hash-upload.md | 14 -- docs/intro.md | 7 +- docs/reference/architecture-overview.md | 5 +- docs/reference/catalog-overview.md | 2 +- .../deployment-orchestrator.md | 0 docs/reference/product-boundaries.md | 2 +- docs/{deploy => runtime}/deployment-flow.md | 19 ++- docs/runtime/logs-and-artifacts.md | 139 ++++++++++++++++++ .../{connect => runtime}/network-readiness.md | 2 +- .../post-winpe-handoff.md | 4 +- docs/start/quick-start.md | 6 +- docusaurus.config.ts | 1 + sidebars.ts | 77 ++++------ src/pages/index.tsx | 22 ++- ...ystem-catalog.png => operating-system.png} | Bin 23 files changed, 321 insertions(+), 111 deletions(-) create mode 100644 docs/build-media/media-authoring-flow.md delete mode 100644 docs/configure/autopilot.md delete mode 100644 docs/deploy/autopilot-hash-upload.md rename docs/{technical => reference}/deployment-orchestrator.md (100%) rename docs/{deploy => runtime}/deployment-flow.md (84%) create mode 100644 docs/runtime/logs-and-artifacts.md rename docs/{connect => runtime}/network-readiness.md (97%) rename docs/{technical => runtime}/post-winpe-handoff.md (95%) rename static/img/docs/foundry-deploy/{operating-system-catalog.png => operating-system.png} (100%) diff --git a/docs/build-media/media-authoring-flow.md b/docs/build-media/media-authoring-flow.md new file mode 100644 index 0000000..a3115b3 --- /dev/null +++ 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 index 7749b84..f1ae065 100644 --- 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 index 9385e67..e54c2fe 100644 --- 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 deleted file mode 100644 index c5ea405..0000000 --- a/docs/configure/autopilot.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Autopilot -description: Legacy Autopilot configuration page. Use the dedicated Autopilot section for current mode guides. ---- - -# Autopilot - -Autopilot documentation has moved to the dedicated [Autopilot](../autopilot/overview) section. - -Use the new guides: - -- [JSON Profile Injection](../autopilot/json-profile-injection) -- [Zero-touch Hardware Hash Upload](../autopilot/zero-touch-hardware-hash-upload) -- [Interactive Hardware Hash Upload](../autopilot/interactive-hardware-hash-upload) -- [Autopilot Troubleshooting](../autopilot/troubleshooting) diff --git a/docs/configure/customization.md b/docs/configure/customization.md index 62b36c6..2a61097 100644 --- 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 @@ -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 index f54785e..84cff72 100644 --- 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 index be6aa92..84f1581 100644 --- 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 index cec391f..cab70f7 100644 --- 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 deleted file mode 100644 index 22b93c9..0000000 --- a/docs/deploy/autopilot-hash-upload.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Autopilot Hardware Hash Upload -description: Legacy hardware hash upload page. Use the dedicated Autopilot mode guides for current workflows. ---- - -# Autopilot hardware hash upload - -Hardware hash upload documentation has moved to the dedicated Autopilot section. - -Use: - -- [Zero-touch Hardware Hash Upload](../autopilot/zero-touch-hardware-hash-upload) for certificate-based upload from Foundry Deploy. -- [Interactive Hardware Hash Upload](../autopilot/interactive-hardware-hash-upload) for OOBE technician sign-in. -- [Autopilot Troubleshooting](../autopilot/troubleshooting) for logs and common failures. diff --git a/docs/intro.md b/docs/intro.md index 291add3..0ea6a46 100644 --- 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 index 8b11709..4cc7b55 100644 --- 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 index 4c8fae1..3305348 100644 --- 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 b/docs/reference/deployment-orchestrator.md similarity index 100% rename from docs/technical/deployment-orchestrator.md rename to docs/reference/deployment-orchestrator.md diff --git a/docs/reference/product-boundaries.md b/docs/reference/product-boundaries.md index a25afb8..a4ca2f1 100644 --- a/docs/reference/product-boundaries.md +++ b/docs/reference/product-boundaries.md @@ -11,7 +11,7 @@ Use this page when you need to understand which part of Foundry Project owns a b | Surface | Owns | Does not own | | --- | --- | --- | -| Foundry OSD | ADK readiness, media creation, WinPE customization, expert settings, Foundry Connect staging, Autopilot mode configuration, and media staging | Live deployment execution on the target device | +| Foundry OSD | ADK readiness, media creation, WinPE customization, expert settings, runtime configuration generation, Autopilot mode configuration, and media staging | Live deployment execution on the target device | | Foundry Connect | Runtime network readiness, provisioned wired and Wi-Fi setup, bootstrap continuation | OS deployment logic, media authoring, or Microsoft Graph upload | | Foundry Deploy | Catalog loading, target disk selection, OS selection, deployment execution, zero-touch Autopilot hash capture and upload, and interactive Autopilot assistant staging | Building the original ISO or USB media | | catalog | XML feed generation for operating system, driver, and WinPE metadata | UI, media creation, or deployment execution | diff --git a/docs/deploy/deployment-flow.md b/docs/runtime/deployment-flow.md similarity index 84% rename from docs/deploy/deployment-flow.md rename to docs/runtime/deployment-flow.md index 48f62ed..76a94c4 100644 --- a/docs/deploy/deployment-flow.md +++ b/docs/runtime/deployment-flow.md @@ -65,7 +65,7 @@ When no default is configured, Foundry Deploy keeps its normal catalog default o License channel and edition values use English catalog labels. `RET` is shown as `Retail`, `VOL` is shown as `Volume`, and edition names such as `Pro` and `Enterprise` remain English. -![Foundry Deploy operating system catalog](/img/docs/foundry-deploy/operating-system-catalog.png) +![Foundry Deploy operating system selection](/img/docs/foundry-deploy/operating-system.png) ## Driver Pack @@ -135,6 +135,20 @@ Autopilot provisioning is mode-aware: Read [Autopilot Overview](../autopilot/overview) before using an Autopilot mode in production. +## Authored values and runtime choices + +Foundry Deploy consumes configuration that Foundry OSD staged during media creation, then lets the operator confirm or complete runtime choices. + +| Value area | Source | Runtime behavior | +| --- | --- | --- | +| Time zone | Foundry OSD General settings | Applied through `unattend.xml` during Windows specialize | +| Network profile roaming | Foundry OSD Network settings and Foundry Connect runtime capture | Imported during the pre-OOBE first-boot handoff | +| Machine naming | Foundry OSD Customization settings | Pre-fills, generates, or locks the target computer name | +| Operating system policy | Foundry OSD Customization settings | Restricts or preselects catalog filters when enabled | +| OOBE and privacy defaults | Foundry OSD Customization settings | Written offline before reboot | +| AI and AppX removal | Foundry OSD Customization settings | Applied offline or staged for pre-OOBE execution | +| Autopilot mode | Foundry OSD Autopilot settings | Reviewed and executed according to the selected provisioning mode | + ![Foundry Deploy target validation progress](/img/docs/foundry-deploy/progress-validate-target.png) ![Foundry Deploy operating system download progress](/img/docs/foundry-deploy/progress-download-operating-system.png) @@ -159,5 +173,6 @@ If deployment fails, Foundry Deploy shows the failed step and error message. Use ## Next steps -- Review the [Expert Mode](../configure/expert-mode) section to understand which values can be staged from Foundry OSD. +- Review [Configure Media](../configure/expert-mode) 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. +- Open [Logs and Artifacts](./logs-and-artifacts) to locate runtime evidence after deployment. diff --git a/docs/runtime/logs-and-artifacts.md b/docs/runtime/logs-and-artifacts.md new file mode 100644 index 0000000..e03ea40 --- /dev/null +++ b/docs/runtime/logs-and-artifacts.md @@ -0,0 +1,139 @@ +--- +title: Logs and Artifacts +description: Locate the deployment logs, summaries, Autopilot diagnostics, and post-WinPE handoff artifacts written by Foundry runtime components. +--- + +# Logs and artifacts + +Foundry runtime writes evidence to the deployed Windows image so deployment behavior can be reviewed after WinPE exits. + +Use this page when a deployment fails, Autopilot upload is skipped, post-WinPE work does not run, or an operator needs to collect support evidence. + +## Main location + +Foundry stores runtime artifacts under the applied Windows image: + +```text +Windows\Temp\Foundry +``` + +The most important subfolders are: + +| Path | Purpose | +| --- | --- | +| `Windows\Temp\Foundry\Logs` | Deployment, Autopilot, and pre-OOBE logs | +| `Windows\Temp\Foundry\PreOobe` | Generated first-boot runner, manifest, scripts, and data | +| `Windows\Temp\Foundry\PreOobe\Data` | JSON data files consumed by pre-OOBE scripts | +| `Windows\Temp\Foundry\DriverPack` | Deferred driver packages when first-boot execution is required | +| `Windows\Temp\Foundry\AutopilotRegistration` | Interactive hardware hash upload assistant assets | + +:::info[Screenshot placeholder] +Capture the Foundry Deploy runtime menu or failure screen with the log access action visible. +::: + +## Deployment summary + +Foundry Deploy writes a deployment summary after execution. + +Use the summary to confirm: + +- Target disk. +- Selected operating system. +- Selected driver pack. +- Firmware setting. +- Autopilot mode and selected values. +- Final deployment outcome. + +If deployment fails after the Windows partition is available, Foundry attempts to rebind logs to the final target location before reporting the failure. + +## Deployment logs + +Deployment logs are written under: + +```text +Windows\Temp\Foundry\Logs +``` + +Collect these logs when: + +- Target disk validation fails. +- Operating system download or apply fails. +- Driver pack download, extraction, or application fails. +- Firmware update handling fails. +- Autopilot provisioning fails or is skipped. +- Final deployment state is unclear. + +## Autopilot diagnostics + +Zero-touch hardware hash upload writes status and diagnostics under the retained Foundry logs and artifacts. + +Useful files include: + +| File | Purpose | +| --- | --- | +| `autopilot-hash-upload-status.json` | Final zero-touch hardware hash upload state | +| `AutopilotUploadResult.json` | Microsoft Graph upload result details when available | + +Interactive hardware hash upload writes OOBE assistant logs under: + +```text +Windows\Temp\Foundry\Logs\AutopilotRegistration +``` + +Useful files include: + +| File | Purpose | +| --- | --- | +| `registration.log` | Main assistant flow | +| `graph.log` | Microsoft Graph request failures | +| `OOBE.log` | Windows OOBE launcher call | +| `oobe-launcher.log` | OOBE launcher startup | +| `oobe-waiter.log` | OOBE session wait and ServiceUI launch | +| `foreground.log` | OOBE foreground preparation | +| `registration-state.json` | Current assistant state | +| `registration-result.json` | Final assistant result | + +## Pre-OOBE logs + +Post-WinPE first-boot work writes logs under: + +```text +Windows\Temp\Foundry\Logs\PreOobe +``` + +Expected files can include: + +| File | Purpose | +| --- | --- | +| `SetupComplete.log` | Launcher log for the generated pre-OOBE runner | +| `Install-DriverPack.transcript.log` | Deferred driver pack installation transcript | +| `Import-NetworkProfiles.transcript.log` | Windows network profile roaming transcript | +| `Remove-AppX.transcript.log` | Provisioned AppX removal transcript | +| `Remove-AiComponents.transcript.log` | AI component AppX removal transcript | +| `Cleanup-PreOobe.transcript.log` | Cleanup transcript | + +If no Foundry pre-OOBE logs exist after first boot, check: + +```text +Windows\Panther\UnattendGC\Setupact.log +``` + +Windows can skip `SetupComplete.cmd` for some OEM product key scenarios. When that happens, Windows setup logs the skip reason. + +## What not to expect in logs + +Retained runtime logs must not contain: + +- Access tokens. +- Authorization headers. +- PFX bytes. +- PFX passwords. +- Private key material. +- Media secret keys. +- Raw Microsoft Graph payloads. + +## Next steps + +- Open [Deployment Flow](./deployment-flow) for the runtime execution sequence. +- Open [Post-WinPE Handoff](./post-winpe-handoff) for first-boot behavior. +- Open [Autopilot Troubleshooting](../autopilot/troubleshooting) for mode-specific failures. diff --git a/docs/connect/network-readiness.md b/docs/runtime/network-readiness.md similarity index 97% rename from docs/connect/network-readiness.md rename to docs/runtime/network-readiness.md index cf7b62c..9aec54f 100644 --- a/docs/connect/network-readiness.md +++ b/docs/runtime/network-readiness.md @@ -113,6 +113,6 @@ Use the screen state to determine whether the issue is: ## Next step -After Foundry Connect reports **Network ready**, select **Continue** or let auto-continue return success to the bootstrap. The bootstrap then opens [Deployment Flow](../deploy/deployment-flow). Closing Foundry Connect before that controlled exit stops the bootstrap flow. +After Foundry Connect reports **Network ready**, select **Continue** or let auto-continue return success to the bootstrap. The bootstrap then opens [Deployment Flow](./deployment-flow). Closing Foundry Connect before that controlled exit stops the bootstrap flow. If the media was built for zero-touch hardware hash upload, keep network access available through deployment. Foundry Deploy must reach Microsoft Entra and Microsoft Graph after Windows has been applied. If the media was built for interactive hardware hash upload, network access must also be available during Windows OOBE. Tenant workflows that use Microsoft Graph also require an administrator who can grant the required consent in the tenant. Read [Autopilot Overview](../autopilot/overview) before using an Autopilot mode. diff --git a/docs/technical/post-winpe-handoff.md b/docs/runtime/post-winpe-handoff.md similarity index 95% rename from docs/technical/post-winpe-handoff.md rename to docs/runtime/post-winpe-handoff.md index ee74a77..90b8cf2 100644 --- a/docs/technical/post-winpe-handoff.md +++ b/docs/runtime/post-winpe-handoff.md @@ -5,7 +5,7 @@ description: Understand what Foundry stages before reboot and what Windows execu # Post-WinPE handoff -This page is a technical deep dive. It explains what happens after Foundry Deploy finishes in WinPE and the target device boots into the applied Windows image. +This page explains what happens after Foundry Deploy finishes in WinPE and the target device boots into the applied Windows image. ## Handoff boundary @@ -87,3 +87,5 @@ Foundry stores logs, deployment summaries, staged packages, and pre-OOBE manifes `Windows\Temp\Foundry` These files exist to make the deployment handoff auditable after WinPE exits. + +Open [Logs and Artifacts](./logs-and-artifacts) for the operator-facing collection checklist. diff --git a/docs/start/quick-start.md b/docs/start/quick-start.md index 9bfb527..73d3cc2 100644 --- a/docs/start/quick-start.md +++ b/docs/start/quick-start.md @@ -72,7 +72,7 @@ Foundry Connect checks whether the WinPE runtime network state is ready. If networking is ready, allow Foundry Connect to continue. The bootstrap then opens Foundry Deploy. If networking is not ready, resolve the network state before deployment starts. -Read [Network Readiness](../connect/network-readiness) for the runtime behavior. +Read [Network Readiness](../runtime/network-readiness) for the runtime behavior. ## 7. Run deployment @@ -90,5 +90,5 @@ The wizard enables forward movement only when the required selections for the cu ## Next steps - Open [Standard Workflow](../build-media/standard-workflow) for the normal operator path. -- Review the [Expert Mode](../configure/expert-mode) section when standard mode is not enough. -- Open [Deployment Flow](../deploy/deployment-flow) for the Foundry Deploy wizard sequence. +- Review the [Configure Media](../configure/expert-mode) section when standard mode is not enough. +- Open [Deployment Flow](../runtime/deployment-flow) for the Foundry Deploy wizard sequence. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 6c25202..c12c301 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -83,6 +83,7 @@ const config: Config = { {label: 'Quick Start', to: '/docs/start/quick-start'}, {label: 'Requirements', to: '/docs/start/requirements'}, {label: 'Build Media', to: '/docs/build-media/media-creation'}, + {label: 'Runtime', to: '/docs/runtime/network-readiness'}, ], }, { diff --git a/sidebars.ts b/sidebars.ts index 7e28544..da63ab0 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -27,19 +27,30 @@ const sidebars: SidebarsConfig = { slug: '/build-media', description: 'Create ISO or USB deployment media with Foundry OSD.', }, - items: ['build-media/standard-workflow', 'build-media/media-creation'], + items: [ + 'build-media/standard-workflow', + 'build-media/media-authoring-flow', + 'build-media/media-creation', + ], }, { type: 'category', - label: 'Connect', - description: 'Validate WinPE networking before deployment continues.', + label: 'Configure Media', + description: + 'Author the settings that Foundry OSD stages into generated media.', link: { type: 'generated-index', - title: 'Connect', - slug: '/connect', - description: 'Validate WinPE networking before deployment continues.', + title: 'Configure Media', + slug: '/configure', + description: + 'Author the settings that Foundry OSD stages into generated media.', }, - items: ['connect/network-readiness'], + items: [ + 'configure/expert-mode', + 'configure/general', + 'configure/network', + 'configure/customization', + ], }, { type: 'category', @@ -63,51 +74,40 @@ const sidebars: SidebarsConfig = { }, { type: 'category', - label: 'Deploy', - description: 'Select deployment options and run the Windows deployment.', - link: { - type: 'generated-index', - title: 'Deploy', - slug: '/deploy', - description: 'Select deployment options and run the Windows deployment.', - }, - items: ['deploy/deployment-flow'], - }, - { - type: 'category', - label: 'Configure Deployment', + label: 'Runtime', description: - 'Use expert settings only when the standard path is not enough.', + 'Understand what happens after the target boots into Foundry media.', link: { type: 'generated-index', - title: 'Configure Deployment', - slug: '/configure', + title: 'Runtime', + slug: '/runtime', description: - 'Use expert settings only when the standard path is not enough.', + 'Understand what happens after the target boots into Foundry media.', }, items: [ - 'configure/expert-mode', - 'configure/general', - 'configure/network', - 'configure/customization', + 'runtime/network-readiness', + 'runtime/deployment-flow', + 'runtime/post-winpe-handoff', + 'runtime/logs-and-artifacts', ], }, { type: 'category', label: 'Reference', description: - 'Architecture, product boundaries, runtime sequence, and catalog behavior.', + 'Architecture, product boundaries, orchestration, catalog behavior, and telemetry.', link: { type: 'generated-index', title: 'Reference', slug: '/reference', description: - 'Architecture, product boundaries, runtime sequence, and catalog behavior.', + 'Architecture, product boundaries, orchestration, catalog behavior, and telemetry.', }, items: [ 'reference/architecture-overview', 'reference/product-boundaries', 'reference/catalog-overview', + 'reference/deployment-orchestrator', 'reference/telemetry', ], }, @@ -123,23 +123,6 @@ const sidebars: SidebarsConfig = { }, items: ['developer/build-from-source', 'developer/local-winpe-testing'], }, - { - type: 'category', - label: 'Technical Deep Dives', - description: - 'Implementation-level details for Foundry runtime behavior, orchestration, and handoff internals.', - link: { - type: 'generated-index', - title: 'Technical Deep Dives', - slug: '/technical', - description: - 'Implementation-level details for Foundry runtime behavior, orchestration, and handoff internals.', - }, - items: [ - 'technical/deployment-orchestrator', - 'technical/post-winpe-handoff', - ], - }, ], }; diff --git a/src/pages/index.tsx b/src/pages/index.tsx index bb5dfe4..372c703 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -63,19 +63,29 @@ const documentationSections = [ { icon: icons.media, title: 'Build Media', - text: 'Create bootable media and choose between ISO and USB outputs.', + text: 'Create bootable media and understand how authored settings become runtime configuration.', links: [ + ['Media Authoring Flow', '/docs/build-media/media-authoring-flow'], ['Media Creation', '/docs/build-media/media-creation'], - ['Standard Workflow', '/docs/build-media/standard-workflow'], + ], + }, + { + icon: icons.media, + title: 'Configure Media', + text: 'Author advanced network, deployment, customization, and Autopilot behavior before media creation.', + links: [ + ['Expert Mode Overview', '/docs/configure/expert-mode'], + ['Network Configuration', '/docs/configure/network'], ], }, { icon: icons.runtime, - title: 'WinPE Runtime', - text: 'The bootstrap opens Foundry Connect and Foundry Deploy after booting the target device.', + title: 'Runtime', + text: 'The bootstrap opens Foundry Connect and Foundry Deploy after the target boots.', links: [ - ['Foundry Connect', '/docs/connect/network-readiness'], - ['Foundry Deploy', '/docs/deploy/deployment-flow'], + ['Network Readiness', '/docs/runtime/network-readiness'], + ['Deployment Flow', '/docs/runtime/deployment-flow'], + ['Logs and Artifacts', '/docs/runtime/logs-and-artifacts'], ], }, { diff --git a/static/img/docs/foundry-deploy/operating-system-catalog.png b/static/img/docs/foundry-deploy/operating-system.png similarity index 100% rename from static/img/docs/foundry-deploy/operating-system-catalog.png rename to static/img/docs/foundry-deploy/operating-system.png