#Requires -Version 7.0
# PIM Manager 3.0.70 -- Start-PimManagerInstall.ps1, standalone (built by tools/setup/Build-PimSupportScripts.ps1; helpers inlined: _pimscriptdoc.ps1, _piminstallpropackage.ps1, ../../engine/_shared/invardiaupdate.verify.ps1, _pimloopbackanswer.ps1)

# BUILD-NO-OPTIONAL-LOADS

<#
.SYNOPSIS
  Install PIM Manager with one command: download the public PIM Manager release into a new folder, check the download, and run its guided installer (Install-PimManager) with the parameters you give.
  Two short lines: line 1 downloads this file from the public release, line 2 runs the install with your values.

.DESCRIPTION
  The ONE file a person downloads to install PIM Manager. It is a file of the public PIM Manager release on GitHub:
  line 1 downloads it, line 2 runs it with your values (see the examples). It:
    1. checks that this file is the one published with its release -- a difference stops here, nothing is installed;
    2. reads the public release from GitHub (the latest, or -Version), and downloads its zip into a NEW, empty folder in
       the temp folder;
    3. checks the download against the release -- a difference stops here, the folder is removed and nothing is installed;
    4. unpacks it and runs tools/setup/Install-PimManager.ps1 FROM that folder with exactly the parameters you gave (the
       same parameters as Install-PimManager; its help has the details), and ends with its exit code;
    5. prints where the files are. -Resume uses that folder again (no new download) only when it holds the SAME edition
       and the same version this copy installs now; the folder is remembered per tenant and subscription in the temp
       folder. When it is gone (a new Cloud Shell session), or holds another edition or version, -Resume says so in one
       line and downloads the release again -- the installation's own progress is kept in its state folder, so it still
       continues where it stopped.
  -ReleasePath <folder> runs the installer from a release you already have (nothing is downloaded).
  The copy Invardia gives Pro and trial customers does steps 2-3 with Invardia instead of GitHub: you sign in in the browser
  (an administrator of -TenantId), it asks Invardia for the PIM Manager Pro package of your update ring for that tenant, checks
  that Invardia sealed it (its signed manifest) and the download's size and SHA-256 against it, and then runs the installer from it the same
  way. If Invardia cannot be reached or refuses, it says so in one line and installs nothing -- it never falls back to GitHub.

  Browser sign-in (your own administrator account): no Azure CLI, no PowerShell modules, no secret, no certificate, no
  key and no licence in the command. PowerShell 7 (Azure Cloud Shell, or PowerShell 7 on Windows, macOS or Linux). Only
  -TenantId and -SubscriptionId are needed. The edition comes with the file, never with a parameter: the copy of the
  public GitHub release installs PIM Manager Community (free); the copy Invardia gives Pro and trial customers installs
  PIM Manager Pro, without a licence -- the installation asks Invardia for its licence by itself right after the
  install. Updates follow ring 3 (broad) unless -UpdateRing 2 is given. The Invardia Support app is named by its id with
  -SupportAppId, never found by name: it then gets 'troubleshoot' access unless -SupportAccess names another level;
  without -SupportAppId nothing is granted. -ViaSupportApp runs the install as the Invardia Support app: it needs a
  Connect-InvardiaSupport session for the same tenant in this PowerShell window. Several tenants (MSP) are set up with
  the managing-tenant build, not this command.
  Public network by default; -PrivateNetwork installs the private shape (no public address) with the same two lines, with
  SI's network parameters (-VnetId, -VnetAddressPrefix, -VnetName, -AppsSubnetName / -AppsSubnetPrefix,
  -EndpointsSubnetName / -EndpointsSubnetPrefix, -PrivateDnsZonesResourceGroupId, -HubVnetId with -PeerToHub /
  -LinkZonesToHub, -InternalRanges with -FirewallIp for the return route behind a hub firewall, -WebAppAccess);
  Install-PimManager's help has the details.

  Exit codes: those of Install-PimManager (0 done, 1 a step failed -- fix it and -Resume, 2 a check failed -- nothing was
  changed, 3 bad answers -- nothing was changed); 3 also when the release cannot be read or a check of the download fails.

.EXAMPLE
  Invoke-WebRequest https://invardia.com/support/pim/Start-PimManagerInstall.ps1 -OutFile Start-PimManagerInstall.ps1
  .\Start-PimManagerInstall.ps1 -TenantId '<tenant id>' -SubscriptionId '<subscription id>'
  The most common: PIM Manager Pro (or trial) in your own subscription, signed in in the browser, every other answer a default.
.EXAMPLE
  Invoke-WebRequest https://invardia.com/support/pim/Start-PimManagerInstall.ps1 -OutFile Start-PimManagerInstall.ps1
  .\Start-PimManagerInstall.ps1 -TenantId '<tenant id>' -SubscriptionId '<subscription id>' -WhatIf
  To see the plan first: the checks run, then every step the installation would take is printed, and nothing is changed.
.EXAMPLE
  Invoke-WebRequest https://invardia.com/support/pim/Start-PimManagerInstall.ps1 -OutFile Start-PimManagerInstall.ps1
  .\Start-PimManagerInstall.ps1 -TenantId '<tenant id>' -SubscriptionId '<subscription id>' -Location westeurope -ResourceGroup rg-pim-manager -SuperAdmins 'admin1@contoso.com','admin2@contoso.com' -AlertRecipients 'pim-alerts@contoso.com'
  When you choose the region and the resource group yourself, and name the PIM Manager administrators and who gets the alerts.
.EXAMPLE
  Invoke-WebRequest https://invardia.com/support/pim/Start-PimManagerInstall.ps1 -OutFile Start-PimManagerInstall.ps1
  .\Start-PimManagerInstall.ps1 -TenantId '<tenant id>' -SubscriptionId '<subscription id>' -SuperAdmins 'admin1@contoso.com' -ViaSupportApp
  Through the Invardia Support app, after Connect-InvardiaSupport for this tenant: the installation runs as that app, so name the PIM Manager administrators.
.EXAMPLE
  Invoke-WebRequest https://invardia.com/support/pim/Start-PimManagerInstall.ps1 -OutFile Start-PimManagerInstall.ps1
  .\Start-PimManagerInstall.ps1 -TenantId '<tenant id>' -SubscriptionId '<subscription id>' -Resume
  After a stop: run the same command with -Resume; the downloaded release is used again and finished steps are skipped.

.NOTES
  Requirements:
    PowerShell: 7.0 or later (pwsh; Azure Cloud Shell has it). Windows PowerShell 5.1 is not supported.
    Role: Owner on the target subscription (Azure); Privileged Role Administrator and Application Administrator
          (Microsoft Entra); Exchange Administrator only for the mail sender (optional).
    Hosts: github.com, api.github.com, objects.githubusercontent.com, release-assets.githubusercontent.com (the release);
           the Pro copy instead: login.microsoftonline.com (your browser sign-in) and invardia.com (the Pro package and the
           short-lived download link it names);
           then the installer's: login.microsoftonline.com, management.azure.com, graph.microsoft.com,
           *.database.windows.net (port 1433), *.azurecr.io, outlook.office365.com (mail sender)

    PERMISSIONS AND CHANGES (from Start-PimManagerInstall.ps1 manifest, PIM Manager 3.0.70; full page: https://invardia.com/docs/pim/scripts/Start-PimManagerInstall/)
    The person running it needs:
      - Owner [azureRbac, the target subscription] -- The installer it runs (Install-PimManager) creates the resource group and its resources and assigns Azure roles to the identities it creates (Contributor + User Access Administrator is the equivalent); its check stops before anything is created without it.
      - Privileged Role Administrator [entraRole, tenant] -- For the installer: Microsoft Graph application permissions for PIM Manager's identities and the SQL admin group. Without it the installation continues and ends with the command for the right person.
      - Application Administrator [entraRole, tenant] -- For the installer: the Manager's sign-in app registration (the same as Install-PimManager).
      - Exchange Administrator (optional) [exchange, Exchange Online] -- For the installer: only for the mail sender (a shared mailbox and its scoped send right). Without it the step is a warning with the command for an Exchange Administrator.
      - Signed in in the browser as yourself (no command-line tool, no PowerShell module, no secret, no certificate) [other, the tenant and subscription you name] -- The installer signs you in in the browser when it first needs Azure or Microsoft Graph. The Community copy itself reads only public release data and needs no sign-in; the Pro copy signs you in in the browser first (an administrator of -TenantId) to download the PIM Manager Pro package from Invardia for that tenant, and hands that sign-in to the installer.
    What it creates, changes or grants:
      - create a new folder in the temp folder (pim-manager-release-<version>-<random>) with the downloaded release zip and its unpacked files, and a small note (pim-manager-install-<id>.json in the temp folder) with that folder's path so -Resume uses it again (Local machine) -- The installer runs from the release it was downloaded with; -Resume needs no new download. Undo: Delete the folder and the note.
      - create the PIM Manager installation, made by Install-PimManager from the downloaded release (every object, permission and scope is listed on its page: https://invardia.com/docs/pim/scripts/Install-PimManager/) (Azure, Microsoft Entra ID, Azure SQL) -- This launcher only fetches the release and starts the installer with your parameters. Undo: As described for Install-PimManager (delete the resource group after exporting the database, and the Entra objects it created).
    -WhatIf: Downloads and unpacks the release into a new folder in the temp folder (the plan is read from it), then runs Install-PimManager -WhatIf from it: its checks (reads only) and every step it would take. No note is written and nothing in Azure, Microsoft Entra ID or the database is changed.
    Undo: Delete the release folder and the note in the temp folder; the installation itself is undone as described for Install-PimManager.

  Reads: the release metadata at api.github.com (public, no sign-in) and the release zip it names (the Pro copy: the signed
  package answer from invardia.com, with your sign-in, and the zip it names). Writes: a new folder
  in the temp folder (the zip and its unpacked files) and a small note there with that folder's path; everything else is
  the installer's (see Install-PimManager).

.LINK
    https://invardia.com/docs/pim/scripts/Start-PimManagerInstall/
#>
[CmdletBinding(SupportsShouldProcess)]
param(
    # --- the installer's parameters, passed through unchanged (Install-PimManager has the details) ---
    [string]$TenantId = '',
    [string]$SubscriptionId = '',
    [string]$Location = '',
    [string]$ResourceGroup = '',
    [string[]]$SuperAdmins = @(),
    [string[]]$AlertRecipients = @(),
    [string]$MailSender = '',
    [string[]]$PortalUsers = @(),
    [switch]$AllowAllMembers,
    [string]$VnetAddressPrefix = '',
    [Parameter(DontShow)][string]$SubnetAddressPrefix = '',   # old name of -AppsSubnetPrefix (one release)
    [Parameter(DontShow)][string]$Exposure = '',              # old name: -Exposure internal = -PrivateNetwork (one release)
    # --- PRIVATE NETWORK (framework INSTALL-1 item 5): SI's names, passed through unchanged; public without -PrivateNetwork ---
    [switch]$PrivateNetwork,
    [string]$VnetId = '',
    [string]$VnetName = '',
    [string]$AppsSubnetName = '',
    [string]$AppsSubnetPrefix = '',
    [string]$EndpointsSubnetName = '',
    [string]$EndpointsSubnetPrefix = '',
    [string]$PrivateDnsZonesResourceGroupId = '',
    [string]$HubVnetId = '',
    [switch]$LinkZonesToHub,
    [switch]$PeerToHub,
    # framework installer rule 11d (2026-11-04): the return route behind a hub firewall (private only, both or neither)
    [string[]]$InternalRanges = @(),
    [string]$FirewallIp = '',
    [ValidateSet('', 'external', 'internal')][string]$WebAppAccess = '',
    # INSTALL-1 ALIGN: not documented any more (the copy decides the edition, $script:PimInstallChannel below). Accepted for
    # ONE release so the 3.0.17 command lines keep working; when given it wins. Drop it in the next release.
    [ValidateSet('', 'Community', 'Trial', 'Pro')][string]$Edition = '',
    [ValidateSet('', '2', '3')][string]$UpdateRing = '3',
    [string]$KeyVaultName = '',
    [switch]$EngineAzureRootUserAccessAdmin,
    [string]$InstallId = '',
    [string]$SupportAppId = '',
    [ValidateSet('', 'troubleshoot', 'setup', 'asbuilt')][string]$SupportAccess = '',
    [scriptblock]$Reporter,
    [string]$StatePath = '',
    [switch]$Resume,
    [switch]$PreflightOnly,
    # run as the Invardia Support app: requires a Connect-InvardiaSupport session for -TenantId in this PowerShell window
    [switch]$ViaSupportApp,
    # --- this launcher's own ---
    # the release to install (e.g. 3.0.5); default: the latest public release
    [string]$Version = '',
    # a folder that already holds the unpacked release: nothing is downloaded
    [string]$ReleasePath = '',
    # --- test seams (offline tests/Test-PimGuidedInstall.ps1 + the -WhatIf case); omit them for a real install ---
    [scriptblock]$GetRelease,
    [scriptblock]$Download,
    [scriptblock]$RunInstaller,
    [string]$TestSelfVersion = '',
    # --- the Pro copy's seams (PRO-PACKAGE-FROM-INVARDIA): the sign-in { param($TenantId) } and Invardia's answer { param($Url, $Token) }
    [scriptblock]$GetInstallToken,
    [scriptblock]$InvardiaHttp
)
$ErrorActionPreference = 'Stop'
# INSTALL-1 ALIGN (owner 2026-11-02: "trial and pro are th same functionality. license is different in time (backend)"):
# the ONE line that differs between the two copies. The repository and the GitHub release say 'community'; the copy built
# for Invardia (Build-PimSupportScripts) says 'pro'. Trial and Pro are the same install -- Invardia decides by the licence.
$script:PimInstallChannel = 'pro'   # INSTALL-CHANNEL: 'community' (the GitHub release copy) | 'pro' (the copy handed to Invardia)
# ===== BEGIN inlined helper: _PimScriptDoc.ps1 =====
<#
.SYNOPSIS
    Framework 12.7 SCRIPT-DOC-1 + 12.10 item 11 -- the ONE place that knows where a PIM script's documentation page,
    download and checksum list live, the command form every surface shows (line 1 download, line 2+ run -- owner
    2026-10-11), and the run
    frame every script a person runs uses (the first line "<Script> version <x.y.z> - documentation: <page>",
    REQUIREMENTS 100.52, and a local transcript).

.DESCRIPTION
    PURE except Start-PimScriptRun / Stop-PimScriptRun (they print and start / stop a transcript in the temp folder).
    Loaded by every in-scope script (tools\setup + tools\pim-activator), by Build-PimSupportScripts.ps1 (it inlines this
    file into each standalone), by the Manager (Open-PimManager.ps1 hands the constants to the page) and by the engine
    libraries that build fix commands (PIM-PermissionHealth, PIM-MailTransport, PIM-WorkloadPrereqs).
    Change a URL HERE and only here: tests\Test-PimScriptDocs.ps1 fails on any script whose .LINK, page constant or
    manifest docUrl disagrees with it.

    The in-scope list ($script:PimScriptDocScripts) is the set of scripts a person runs that 12.7 covers: each has a
    manifest tools\setup\script-docs\<Script>.doc.json, a .LINK to its page, the Documentation line, -WhatIf, and a
    -WhatIf run case under tests\script-docs\.
#>

# --- the constants (Invardia confirmed 2026-10-09: page = <base><Script>/ with a trailing slash; index = <base>) -------
$script:PimScriptDocBaseUrl     = 'https://invardia.com/docs/pim/scripts/'
$script:PimSupportScriptBaseUrl = 'https://invardia.com/support/pim/'
# ONE-LINE-INSTALL (owner 2026-11-02): the installer launcher is a file of the public release (a release asset)
$script:PimInstallReleaseDownloadBase = 'https://github.com/KnudsenMorten/PIM4EntraPS/releases/latest/download/'
$script:PimSupportScriptSumsUrl = 'https://invardia.com/support/pim/SHA256SUMS.txt'

# --- the version the banner names (REQUIREMENTS 100.52, owner 2026-10-10: "do you provide the version in all scripts, so i
# can troubleshoot better"). Build-PimSupportScripts.ps1 rewrites the NEXT line in a standalone file to the version it was
# built from (the marker comment is what it looks for); in the repository it stays empty and Get-PimScriptVersion reads
# the solution's VERSION file next to this helper (tools\setup\..\..\VERSION).
$script:PimScriptDocVersion = '3.0.70'   # BUILD-VERSION stamped by Build-PimSupportScripts
$script:PimScriptDocHelperDir = "$PSScriptRoot"

# --- every script 12.7 covers: path relative to tools\ ; Standalone = published as one file by Build-PimSupportScripts --
$script:PimScriptDocScripts = @(
    @{ Path = 'setup/Initialize-PimSqlAdminGroup.ps1';             Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorBackend.ps1';      Standalone = $true }
    @{ Path = 'pim-activator/Publish-PimActivatorRemediation.ps1'; Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorClient.ps1';       Standalone = $true }
    @{ Path = 'setup/Grant-PimEnginePermissions.ps1';              Standalone = $true }
    @{ Path = 'setup/Initialize-PimWorkloadPrereqs.ps1';           Standalone = $true }
    @{ Path = 'setup/Initialize-PimMailSender.ps1';                Standalone = $true }
    @{ Path = 'setup/Set-PimSmtpRelayPassword.ps1';                Standalone = $true }
    @{ Path = 'setup/Set-PimSqlTier.ps1';                          Standalone = $true }
    @{ Path = 'setup/New-PimHubPrepareScript.ps1';                 Standalone = $true }
    @{ Path = 'setup/Install-PimManager.ps1';                      Standalone = $false }
    @{ Path = 'setup/Invoke-PimDeployAll.ps1';                     Standalone = $false }
    @{ Path = 'setup/Invoke-PimMspBuild.ps1';                      Standalone = $false }
    @{ Path = 'setup/Copy-PimSettings.ps1';                        Standalone = $false }
    @{ Path = 'setup/Export-PimSettings.ps1';                      Standalone = $false }   # 77.13 / 72.4 settings as code
    @{ Path = 'setup/Import-PimSettings.ps1';                      Standalone = $false }
    @{ Path = 'setup/Set-PimManagerAccess.ps1';                    Standalone = $false }
    @{ Path = 'setup/Set-PimBreakGlassAccounts.ps1';               Standalone = $false }
    @{ Path = 'setup/Set-PimEmergencyPassphrase.ps1';              Standalone = $false }
    @{ Path = 'setup/Find-PimStrayTestObjects.ps1';                Standalone = $false }
    @{ Path = 'setup/Move-PimIdentities.ps1';                      Standalone = $false }   # NAM-03 identity mover
    @{ Path = 'setup/Rename-PimJobs.ps1';                          Standalone = $false }   # JOB-RENAME 3.0.68 job rename (create, prove, switch, disable)
    @{ Path = 'setup/Set-PimLicense.ps1';                          Standalone = $true }
    @{ Path = 'pim-activator/Deploy-PimActivatorHybrid.ps1';       Standalone = $false }
    @{ Path = 'setup/Update-PimCommunity.ps1';                     Standalone = $false }
    @{ Path = 'setup/Grant-PimSupportAccess.ps1';                  Standalone = $false }
    @{ Path = 'setup/Confirm-PimInstall.ps1';                      Standalone = $false }
    @{ Path = 'setup/Set-PimManagerCustomHost.ps1';                Standalone = $false }
    @{ Path = 'setup/Deploy-PimRfaBroker.ps1';                     Standalone = $false }
    @{ Path = 'setup/Rebuild-PimEnvInternal.ps1';                  Standalone = $false }
    @{ Path = 'setup/Rebuild-PimEnvExternal.ps1';                  Standalone = $false }
    @{ Path = 'setup/Remove-PimContainerStack.ps1';                Standalone = $false }
    @{ Path = 'setup/New-PimHostingPrerequisites.ps1';             Standalone = $false }
    @{ Path = 'setup/Convert-PimToPrivate.ps1';                    Standalone = $false }
    @{ Path = 'setup/Set-PimSqlPublicAccess.ps1';                  Standalone = $false }
    @{ Path = 'setup/Grant-PimSupportSqlAccess.ps1';               Standalone = $true }
    @{ Path = 'setup/Invoke-PimSupportSqlAccessJob.ps1';           Standalone = $true }
    @{ Path = 'setup/Set-PimSigninFrontSqlState.ps1';              Standalone = $true }
    # HYBRID-DEPLOY-STANDALONE: one published file that carries the worker's other scripts (BUILD-CARRY) and runs them from a temp folder
    @{ Path = 'pim-hybrid-worker/Deploy-PimHybridWorker.ps1';      Standalone = $true }
    @{ Path = 'pim-hybrid-worker/New-PimHybridWorkerInfra.ps1';    Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Set-PimHybridWorkerPeering.ps1';  Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Set-PimHybridWorkerEgress.ps1';   Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Grant-PimHybridWorkerAccess.ps1'; Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Invoke-PimHybridWorkerRunCommand.ps1'; Standalone = $false }
    @{ Path = 'pim-hybrid-worker/Remove-PimHybridWorker.ps1';      Standalone = $false }
    # self-contained on the machine they run on (a domain controller; the worker itself): published as one file each
    @{ Path = 'pim-hybrid-worker/Initialize-PimHybridWorkerAd.ps1'; Standalone = $true }
    @{ Path = 'pim-hybrid-worker/Install-PimHybridWorker.ps1';     Standalone = $true }
    # INSTALL-SAMPLES (owner 2026-10-29): the one-file launcher of the installation (downloads the release, runs its installer)
    @{ Path = 'setup/Start-PimManagerInstall.ps1';                 Standalone = $true }
    # V1-IMPORT-PUBLISHED (Invardia per 0.1 B, 2026-11-03): import a PIM version 1 data folder (check + preview by default)
    @{ Path = 'setup/Import-PimV1Data.ps1';                        Standalone = $true }
)

function Get-PimScriptDocName {
    # PURE. 'Grant-PimEnginePermissions.ps1' / '.\x\Grant-PimEnginePermissions' -> 'Grant-PimEnginePermissions'.
    param([Parameter(Mandatory)][string]$Script)
    $leaf = "$Script".Trim() -replace '^.*[\\/]', ''
    return ($leaf -replace '(?i)\.ps1$', '')
}

function Get-PimScriptDocUrl {
    # PURE. The script's documentation page at Invardia: <base><Script>/ (no .ps1, trailing slash).
    param([Parameter(Mandatory)][string]$Script)
    return ($script:PimScriptDocBaseUrl + (Get-PimScriptDocName -Script $Script) + '/')
}

function Get-PimSupportScriptUrl {
    # PURE. The published standalone copy: <support base><Script>.ps1 -- except the installer launcher, which is a file of
    # the public GitHub release itself (ONE-LINE-INSTALL, owner 2026-11-02: line 1 downloads it from the release, never
    # from invardia.com), under a stable name so .../releases/latest/download/<name> always answers.
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ($name -eq 'Start-PimManagerInstall') { return "$script:PimInstallReleaseDownloadBase$name.ps1" }
    return ($script:PimSupportScriptBaseUrl + $name + '.ps1')
}

function Get-PimSupportScriptCommand {
    <#
      PURE. The lines every surface shows for a published script (owner 2026-10-11, framework 12.10 item 11):
        Invoke-WebRequest <url> -OutFile <Script>.ps1        line 1: download the file from Invardia
        <-Run lines>                                          line 2 (and more if a flow needs them): the cmdlet(s)
      Never a checksum / comment line in the shown block, never pipe-to-execute: the documentation page is the link
      shown NEXT to the command; SHA256SUMS.txt stays published for whoever verifies.
      The run line is LAST on purpose: callers that append parameters to the returned text extend the run line.
      -Run: the command line(s) that run the saved file, e.g. ".\Grant-PimEnginePermissions.ps1 -TenantId '...'";
      none = ".\<Script>.ps1". Returns string[] (join with a newline to show / send).
    #>
    param([Parameter(Mandatory)][string]$Script, [string[]]$Run = @())
    $name = Get-PimScriptDocName -Script $Script
    $file = "$name.ps1"
    $lines = New-Object System.Collections.Generic.List[string]
    # Owner 2026-10-11: TWO lines only -- line 1 downloads the file, line 2 runs it (the doc page is linked next to the
    # command on every surface; SHA256SUMS.txt stays published for whoever wants to verify).
    $lines.Add("Invoke-WebRequest $(Get-PimSupportScriptUrl -Script $name) -OutFile $file")
    $runs = @(@($Run) | Where-Object { "$_".Trim() })
    if (-not $runs.Count) { $runs = @(".\$file") }
    foreach ($r in $runs) { $lines.Add("$r") }
    return $lines.ToArray()
}

function Get-PimSupportScriptDocLine {
    # PURE. REQUIREMENTS 100.77 (owner 2026-10-11, "Yes, outside block"): the ONE plain line that goes UNDER a command block
    # in PLAIN TEXT (an install event / install mail, "Send to customer", a console fix, a report), where no link can sit
    # next to the block the way the Manager page shows it: "What does this script do: <the script's doc page>".
    param([Parameter(Mandatory)][string]$Script)
    return ('What does this script do: ' + (Get-PimScriptDocUrl -Script $Script))
}

function Add-PimSupportScriptDocLines {
    <#
      PURE. REQUIREMENTS 100.77. Plain text that carries one or more published-script command blocks (the lines
      Get-PimSupportScriptCommand returns: "Invoke-WebRequest <support base><Script>.ps1 -OutFile <Script>.ps1", then the
      ".\<Script>.ps1 ..." run line(s)) -> the same text with Get-PimSupportScriptDocLine inserted directly UNDER each
      block's last run line, at the block's indentation. The block itself is never changed (it stays exactly its download
      line + run line(s), framework 12.10 item 11): the doc line is a separate line outside it. Idempotent (a block already
      followed by its doc line is left alone); text without a block comes back unchanged; the newline style is kept.
      Use it ONLY where text leaves the page as plain text -- the Manager page shows the link next to the block instead.
    #>
    param([AllowNull()][AllowEmptyString()][string]$Text)
    $t = "$Text"
    if (-not $t) { return $t }
    $nl = if ($t.Contains("`r`n")) { "`r`n" } else { "`n" }
    $lines = @($t -split "\r?\n")
    $base = [regex]::Escape($script:PimSupportScriptBaseUrl)
    $out = New-Object System.Collections.Generic.List[string]
    $i = 0
    while ($i -lt $lines.Count) {
        $l = $lines[$i]; $out.Add($l); $i++
        $m = [regex]::Match($l, "^(?<ind>\s*)Invoke-WebRequest\s+$base(?<n>[A-Za-z0-9-]+)\.ps1\s+-OutFile\s+\k<n>\.ps1\s*$")
        if (-not $m.Success) { continue }
        $n = $m.Groups['n'].Value
        $runRx = '^\s*\.\\' + [regex]::Escape($n) + '\.ps1(\s|$)'
        while ($i -lt $lines.Count -and $lines[$i] -match $runRx) { $out.Add($lines[$i]); $i++ }
        $doc = Get-PimSupportScriptDocLine -Script $n
        if ($i -lt $lines.Count -and $lines[$i].Trim() -eq $doc) { continue }
        $out.Add($m.Groups['ind'].Value + $doc)
    }
    return ($out.ToArray() -join $nl)
}

function Get-PimScriptVersion {
    # The PIM version this script is: the build stamp in a standalone file, else the solution's VERSION file (resolved
    # from this helper's folder), else 'unknown' (a copied helper with nothing around it -- never a failure).
    param([string]$Stamp = "$($script:PimScriptDocVersion)", [string]$HelperDir = "$($script:PimScriptDocHelperDir)")
    if ("$Stamp".Trim()) { return "$Stamp".Trim() }
    if ("$HelperDir".Trim()) {
        try {
            $vf = Join-Path (Split-Path (Split-Path $HelperDir -Parent) -Parent) 'VERSION'
            if (Test-Path -LiteralPath $vf -PathType Leaf) {
                $v = "$([IO.File]::ReadAllText($vf))".Trim()
                if ($v) { return $v }
            }
        } catch { }
    }
    return 'unknown'
}

function Get-PimScriptBannerText {
    # PURE. The banner line: "<Script> version <x.y.z> - documentation: <doc page>".
    param([Parameter(Mandatory)][string]$Script, [Parameter(Mandatory)][string]$Version)
    $name = Get-PimScriptDocName -Script $Script
    return ('{0} version {1} - documentation: {2}' -f $name, $Version, (Get-PimScriptDocUrl -Script $name))
}

function Write-PimScriptBanner {
    <#
      REQUIREMENTS 100.52: the FIRST line every script a person runs prints -- its own name, version and documentation
      page -- so a transcript a customer sends shows exactly what ran. Called by Start-PimScriptRun (every in-scope script
      calls that first thing after loading its helpers), so it is written once, here.
      Write-Host = the host / Information stream: Start-Transcript records it, the pipeline (JSON, -PassThru) never sees
      it, -WhatIf does not change it.
      Printed by the OUTERMOST script only: a script called by another in the same process (the owner flag is set until
      the outer one's Stop-PimScriptRun) or in a child process it started (PIM_SCRIPT_BANNER_PID names a live parent)
      prints nothing. Returns $true when it printed.
    #>
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ("$($global:PimScriptBannerOwner)") { return $false }
    $parentPid = 0
    if ([int]::TryParse("$env:PIM_SCRIPT_BANNER_PID", [ref]$parentPid) -and $parentPid -gt 0 -and $parentPid -ne $PID) {
        if (Get-Process -Id $parentPid -ErrorAction SilentlyContinue) { return $false }
    }
    $global:PimScriptBannerOwner = $name
    $env:PIM_SCRIPT_BANNER_PID = "$PID"
    Write-Host (Get-PimScriptBannerText -Script $name -Version (Get-PimScriptVersion))
    return $true
}

function Start-PimScriptRun {
    <#
      12.7 + 12.10 item 11: call it right after the param block / helper loading, BEFORE anything else prints.
      Starts a transcript in <temp>\pim-manager-logs\<Script>-<utc>.log (nothing else on disk; the temp folder is the
      one place -WhatIf may write) and prints, as the first line, the banner (Write-PimScriptBanner, REQUIREMENTS 100.52:
      "<Script> version <x.y.z> - documentation: <doc page>"; the outermost script only), then "Log: <path>".
      Nested runs (one in-scope script calling another in the same process) keep the outer transcript.
      Returns the log path ('' when the transcript could not start -- the run goes on, with a warning).
      Scripts print no secret values (SECRET-IN-OUTPUT audit), so the transcript holds none either.
    #>
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    $path = ''
    if ("$($global:PimScriptRunLog)") {
        $path = "$($global:PimScriptRunLog)"
    } elseif ("$env:PIM_SCRIPT_NO_TRANSCRIPT" -ne '1') {
        try {
            $dir = Join-Path ([IO.Path]::GetTempPath()) 'pim-manager-logs'
            if (-not (Test-Path -LiteralPath $dir)) { New-Item -ItemType Directory -Path $dir -Force -WhatIf:$false -Confirm:$false | Out-Null }
            $path = Join-Path $dir ('{0}-{1}.log' -f $name, [DateTime]::UtcNow.ToString('yyyyMMdd-HHmmss'))
            Start-Transcript -LiteralPath $path -Append -WhatIf:$false -Confirm:$false | Out-Null
            $global:PimScriptRunLog = $path
            $global:PimScriptRunOwner = $name
        } catch { $path = '' }
    }
    $null = Write-PimScriptBanner -Script $name   # 100.52: "<Script> version <x.y.z> - documentation: <page>" (outermost only)
    if ($path) { Write-Host "Log: $path" } elseif ("$env:PIM_SCRIPT_NO_TRANSCRIPT" -ne '1') { Write-Warning 'No transcript could be started for this run.' }
    return $path
}

function Stop-PimScriptRun {
    # Call it in the script's finally block: prints "Log written: <path>" and stops the transcript this script started.
    param([Parameter(Mandatory)][string]$Script)
    $name = Get-PimScriptDocName -Script $Script
    if ("$($global:PimScriptBannerOwner)" -eq $name) {
        # 100.52: the outermost script is done -- the next script run in this session prints its banner again
        $global:PimScriptBannerOwner = $null
        if ("$env:PIM_SCRIPT_BANNER_PID" -eq "$PID") { $env:PIM_SCRIPT_BANNER_PID = $null }
    }
    if (-not "$($global:PimScriptRunLog)" -or "$($global:PimScriptRunOwner)" -ne $name) { return }
    $path = "$($global:PimScriptRunLog)"
    Write-Host "Log written: $path"
    try { Stop-Transcript | Out-Null } catch { }
    $global:PimScriptRunLog = $null
    $global:PimScriptRunOwner = $null
}

# ===== END inlined helper: _PimScriptDoc.ps1 =====
# ===== BEGIN inlined helper: _PimInstallProPackage.ps1 =====
<#
.SYNOPSIS
    PRO-PACKAGE-FROM-INVARDIA (2026-11-03; framework INSTALL-1 "github should be for community only" / "pro installs from
    invardia"; Invardia DESIGN ch 8 "BINDING SPEC - Pro installs download the Pro package from Invardia"): the Pro copy of
    Start-PimManagerInstall.ps1 takes the PIM Manager package from Invardia, never from GitHub.

.DESCRIPTION
    Loaded by Start-PimManagerInstall.ps1 (inlined into both published copies by Build-PimSupportScripts; only the Pro copy --
    $script:PimInstallChannel = 'pro' -- calls it, the Community copy keeps its GitHub path exactly as it was).

      1. SIGN-IN   the person's own browser sign-in (auth code + PKCE on the localhost loopback, the Azure CLI first-party
                   public client id over REST -- the same client PIM-Rest uses, so no module, no az, never device code), for
                   the TARGET tenant only, audience https://management.azure.com. The token's tid must be -TenantId.
      2. ASK       GET https://invardia.com/api/install/pim-manager/package?ring=<0-3>&tenantId=<guid>
                   Authorization: Bearer <that ARM token>. Invardia checks issuer, tid == tenantId, expiry, and audits it.
      3. VERIFY    the answer is the SAME signed manifest the ring serves the updater: RS256 over manifestB64 by a key in the
                   EMBEDDED trusted list (InvardiaUpdate.verify.ps1 -- Invardia's GET /api/updates/keys, embedded; a key
                   fetched at run time is never trusted), product pim-manager, kind code, THIS ring, a version, SHA-256, size.
      4. DOWNLOAD  the short-lived link into a NEW folder in the temp folder; the zip's size + SHA-256 must be the signed ones,
                   or the folder is removed and nothing runs.
    NO GitHub fallback: any failure is ONE calm line ("Invardia could not be reached" / "Invardia refused ...") and a non-zero
    exit. Nothing here writes outside the new temp folder; no token is printed, logged or written.

    !!! THE ANSWER'S SHAPE IS NOT FINAL. Invardia sends the exact fields and status codes when the route is live; until then
    ConvertFrom-PimInstallProPackageAnswer (below) reads the updater's manifest shape. It is the ONE place to change.
#>

# ===== BEGIN inlined helper: ../../engine/_shared/InvardiaUpdate.verify.ps1 =====
<#
.SYNOPSIS
  The product-NEUTRAL half of an Invardia update client: verify a signed update manifest and the archive it names.
  Framework contract UPDATE-1 (one signer for every product); Invardia docs/DESIGN.md §10 (the manifest + the pull).

.DESCRIPTION
  Copied BYTE-IDENTICAL into every product that takes updates from Invardia (PIM: engine/_shared/; SecurityInsight:
  engine/_shared/) and pinned there by a whole-file drift test. So: NO product names, settings, environment variables or
  layouts in this file -- the product is always PASSED IN (-Product). A change is made here first and copied.

  * the trusted update-signing public keys, EMBEDDED (a key fetched at run time is never trusted);
  * Test-InvardiaManifestSignature  RS256 (PKCS#1 v1.5, SHA-256) over the base64-DECODED manifest bytes;
  * Test-InvardiaManifest           signature + product + kind + version + SHA-256 + sequence (no replay) + https link;
                                    manualStep / minFromVersion HOLD;
  * Invoke-InvardiaManifestPull     POST <base>/api/updates/<product>/manifest {kind, licence, ring} + X-Invardia-Install-Key
                                    (+ X-Invardia-Install-Id when the product passes its lasting install id -- Invardia S16);
  * Save-InvardiaArchive / Test-InvardiaArchiveFile   the download is a zip of the SIGNED size + SHA-256.
  PS 5.1 + 7. No modules. Nothing here writes anything.
#>

$script:InvardiaUpdateDefaultBase = 'https://invardia.com'
# The trusted update-signing public keys (RSA, JWK n/e base64url), Invardia's list at GET /api/updates/keys, EMBEDDED.
# Add a key here -- never remove the old one in the same release.
# CN=Invardia-Updates (RSA 4096, valid to 2036-10-04, cert SHA-1 DDFF1C84930C290ECF234FB4C3F3C1D5B3F532F2), delivered by
# the Invardia session 2026-10-04 and checked here against Invardia's committed public certificate (modulus identical).
# Then verified against the LIVE GET https://invardia.com/api/updates/keys (same keyId, n and e).
$script:InvardiaUpdateTrustedKeys = @(
    @{ keyId = 'https://kv-invardia-gml64wkoe7np.vault.azure.net/keys/invardia-updates'; e = 'AQAB'
       n = 'tLDrlMq1et3H3vIomcjokhFXfkkyaYVT2F-BByLGk8Pa7lrN7xd-53AbJ3keqv0ZZSQG_V0rKFxbt5b0m7YTNKbBUXvsgLLFQQbouDu-Am-8blzNBjIyDKoQKYKYaYfCbL3Tjdil7RD5pFNV6Qt3wW54jzhPEmyArr2xRjVUOg2WYQe9CpD_pd6-ww9dFlGQwtT_VJvLs0xcXsJkitfxe5tJ7PV8BUKoDpXJQNl6j2M6iqILxAujBxFB3_fGHEfooDJGWu1jkqp2mW2yXots_3ZtKUlnAmwANQNAsVWAxLq-8bLy6b3VTIvMMWw9JyZubBhU8OriW3OBKK6O2k5CV_-O5b0zf_TaQSr64Mq2VPtKkzY1weiFRlwDzEfq-aiLzr-HWx1tB43QEISNoBkrdhC-G9wjCQRgWSoINWbnL--2HOnwdivT9GRaJ38Mng9gqPdrPFfrv6t2ZIn6g5X9GOz_ua1Fi0WyfRJ1ICzzQgiivB0bBdlUtxfV89b0TXwIT9JynV7VYS9uv5H56IXpcuDaWzIueq6bVlWqk6p-cEMviDKMdaME3JW_Q-qNBCF1Q-cCAGl269KtFWQt2aLU2f50JkwW8h5slY1I05PXbJaX26n-Zu9pdrq-us3la8D1v_V9ehsR2s6Xj4cKZRZAURd5ut42R8h7EIe7K17KeZE' }
)

function ConvertFrom-InvardiaBase64Url {
    <# PURE. base64url (or plain base64) text -> bytes. #>
    param([AllowEmptyString()][string]$Text)
    $t = "$Text".Trim().Replace('-', '+').Replace('_', '/')
    switch ($t.Length % 4) { 2 { $t += '==' } 3 { $t += '=' } }
    return [Convert]::FromBase64String($t)
}

function Compare-InvardiaReleaseVersion {
    <# PURE. -1 / 0 / 1 for two dotted numeric versions ('2.4.491'); a non-numeric part compares as 0. #>
    param([string]$A, [string]$B)
    $pa = @("$A".Trim() -split '\.'); $pb = @("$B".Trim() -split '\.')
    for ($i = 0; $i -lt [Math]::Max($pa.Count, $pb.Count); $i++) {
        $x = 0; $y = 0
        if ($i -lt $pa.Count) { [void][int]::TryParse($pa[$i], [ref]$x) }
        if ($i -lt $pb.Count) { [void][int]::TryParse($pb[$i], [ref]$y) }
        if ($x -lt $y) { return -1 }; if ($x -gt $y) { return 1 }
    }
    return 0
}

function Test-InvardiaManifestSignature {
    <#
      PURE (crypto only). RS256 over the bytes behind -ManifestB64, signature base64, by the key -KeyId of -TrustedKeys
      (@( @{ keyId; n; e } )). Returns @{ ok; reason }. PS 5.1-safe: RSAParameters + ImportParameters, no ImportFromPem.
    #>
    param([string]$ManifestB64, [string]$Signature, [string]$KeyId, [object[]]$TrustedKeys = $script:InvardiaUpdateTrustedKeys)
    $keys = @($TrustedKeys | Where-Object { $_ })
    if (-not $keys.Count) { return @{ ok = $false; reason = 'no trusted update-signing key is embedded in this version yet -- every manifest is refused until one is' } }
    $k = @($keys | Where-Object { "$($_.keyId)" -ceq "$KeyId" })[0]
    if (-not $k) { return @{ ok = $false; reason = "the manifest is signed by key '$KeyId', which this version does not trust" } }
    try {
        $data = [Convert]::FromBase64String("$ManifestB64".Trim())
        $sig = [Convert]::FromBase64String("$Signature".Trim())
        $p = New-Object System.Security.Cryptography.RSAParameters
        $p.Modulus = ConvertFrom-InvardiaBase64Url "$($k.n)"
        $p.Exponent = ConvertFrom-InvardiaBase64Url "$($k.e)"
        $rsa = [System.Security.Cryptography.RSA]::Create()
        try {
            $rsa.ImportParameters($p)
            $ok = $rsa.VerifyData($data, $sig, [System.Security.Cryptography.HashAlgorithmName]::SHA256, [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
        } finally { $rsa.Dispose() }
        if ($ok) { return @{ ok = $true; reason = '' } }
        return @{ ok = $false; reason = 'the manifest signature does not verify' }
    } catch { return @{ ok = $false; reason = "the manifest signature could not be checked: $($_.Exception.Message)" } }
}

function Test-InvardiaManifest {
    <#
      PURE (given the trusted keys). Everything about a 200 answer, before anything is downloaded. Returns
      @{ ok; hold; reason; version; sequence; sha256; size; downloadUrl; manifest }.
        ok=$false            refused (signature, shape, product, kind, replay) -- nothing moves
        ok=$true, hold=$true  verified, but the release asks for a manual step or a newer starting version -- nothing moves
    #>
    # -Ring (framework UPDATE-1.7, 2026-10-06: the solution decides the ring, Invardia relays): the ring this environment
    # asked for (0-3; every product caller passes the installation's own ring). A manifest for another ring, or one that names
    # no ring, is refused. -1 = the caller names no ring.
    param([Parameter(Mandatory)][object]$Response, [object[]]$TrustedKeys = $script:InvardiaUpdateTrustedKeys,
          [string]$Kind = 'code', [int]$AppliedSequence = 0, [string]$RunningVersion = '', [Parameter(Mandatory)][string]$Product, [int]$Ring = -1)
    $no = { param($why) @{ ok = $false; hold = $false; reason = $why; version = ''; sequence = 0; sha256 = ''; size = 0; downloadUrl = ''; manifest = $null } }
    $g = { param($o, $n) if ($null -eq $o) { return $null }; if ($o -is [System.Collections.IDictionary]) { return $o[$n] }; $pp = $o.PSObject.Properties[$n]; if ($pp) { $pp.Value } }
    $b64 = "$(& $g $Response 'manifestB64')".Trim()
    if (-not $b64) { return (& $no 'the answer carries no manifest') }
    $sv = Test-InvardiaManifestSignature -ManifestB64 $b64 -Signature "$(& $g $Response 'signature')" -KeyId "$(& $g $Response 'keyId')" -TrustedKeys $TrustedKeys
    if (-not $sv.ok) { return (& $no $sv.reason) }
    # Only the SIGNED bytes are read; the answer's own 'manifest' object is ignored.
    $m = $null; try { $m = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($b64)) | ConvertFrom-Json } catch { return (& $no 'the signed manifest is not JSON') }
    if ("$($m.product)" -cne $Product) { return (& $no "the manifest is for '$($m.product)', not $Product") }
    if ("$($m.kind)" -cne $Kind) { return (& $no "the manifest is kind '$($m.kind)', not $Kind") }
    if ($Ring -ge 0) {
        $mr = -1; if (-not [int]::TryParse("$($m.ring)", [ref]$mr)) { return (& $no "the manifest names no ring (this environment asked for ring $Ring)") }
        if ($mr -ne $Ring) { return (& $no "the manifest is for ring $mr, not ring $Ring that this environment asked for") }
    }
    $ver = "$($m.version)".Trim(); if ($ver -notmatch '^\d+\.\d+\.\d+$') { return (& $no "the manifest names no release version ('$ver')") }
    $sha = "$($m.sha256)".Trim().ToLowerInvariant(); if ($sha -notmatch '^[0-9a-f]{64}$') { return (& $no 'the manifest carries no SHA-256') }
    $seq = 0; if (-not [int]::TryParse("$($m.sequence)", [ref]$seq) -or $seq -lt 1) { return (& $no 'the manifest carries no sequence') }
    if ($seq -lt $AppliedSequence) { return (& $no "REPLAY refused: sequence $seq is lower than the $AppliedSequence already applied here") }
    # F4 (framework UPDATE-1.5, 2026-10-05): the SIGNED size is required -- a manifest without it (or with 0) is refused,
    # so the archive check below always compares the length, never only the hash.
    $size = [int64]0; if (-not [int64]::TryParse("$($m.size)", [ref]$size) -or $size -lt 1) { return (& $no 'the manifest carries no archive size') }
    $url = "$(& $g $Response 'downloadUrl')".Trim()
    if ($url -notmatch '^https://') { return (& $no 'the download link is not https') }
    $r = @{ ok = $true; hold = $false; reason = "signed manifest: $ver (ring $($m.ring), sequence $seq)"; version = $ver; sequence = $seq; sha256 = $sha; size = $size; downloadUrl = $url; manifest = $m }
    if ("$($m.manualStep)".Trim()) { $r.hold = $true; $r.reason = "HELD -- $ver asks for a manual step first: $("$($m.manualStep)".Trim())" ; return $r }
    $mf = "$($m.minFromVersion)".Trim()
    if ($mf -and "$RunningVersion".Trim() -and (Compare-InvardiaReleaseVersion "$RunningVersion" $mf) -lt 0) {
        $r.hold = $true; $r.reason = "HELD -- $ver can only be installed from $mf or later; this environment runs $RunningVersion"; return $r
    }
    return $r
}

function Get-InvardiaPullReason {
    <# PURE. The admin's sentence for a non-200 pull answer. #>
    param([int]$Status, [AllowNull()][object]$Body, [string]$ErrorText = '')
    $why = if ($Body -and $Body.PSObject.Properties['reason']) { " ($($Body.reason))" } else { '' }
    switch ($Status) {
        204 { return 'nothing is released to this environment''s ring yet' }
        401 { return 'Invardia refused the install key (revoked, reset or wrong) -- claim a new one, or set the install key again' }
        403 { return "Invardia refused the licence$why -- updates need a valid Invardia-issued Pro licence for this tenant" }
        404 { return 'Invardia does not know the product' }
        422 { return "Invardia refused the request$why -- the pull must carry this environment's ring (0-3)" }
        429 { return 'Invardia asked to wait (rate limit) -- the next run asks again' }
        0   { return "Invardia could not be reached: $ErrorText" }
        default { return "Invardia answered HTTP $Status$why" }
    }
}

function Invoke-InvardiaManifestPull {
    <# The pull. -Http { param($Method, $Url, $Body, $Headers) } -> @{ status; body; error } (the product's own HTTP helper). #>
    # -Ring (UPDATE-1.7): the environment's OWN ring (0-3), set in the product; Invardia answers with what the product
    # published for that ring (204 when nothing). Required -- Invardia answers 422 without it.
    # -InstallId (Invardia S16): the install's own LASTING id, kept by the product. Sent as X-Invardia-Install-Id only when it
    # is a GUID (lower-cased); '' = no header. Never made up here -- a wrong id would lock the install key.
    param([Parameter(Mandatory)][string]$Product, [Parameter(Mandatory)][scriptblock]$Http, [string]$BaseUrl = '', [Parameter(Mandatory)][string]$InstallKey, [Parameter(Mandatory)][string]$LicenceText, [string]$Kind = 'code',
          [AllowEmptyString()][AllowNull()][string]$InstallId = '',
          [Parameter(Mandatory)][ValidateRange(0, 3)][int]$Ring)
    $base = if ("$BaseUrl".Trim()) { "$BaseUrl".Trim().TrimEnd('/') } else { $script:InvardiaUpdateDefaultBase }
    $h = @{ 'X-Invardia-Install-Key' = $InstallKey }
    $iid = "$InstallId".Trim().ToLowerInvariant()
    if ($iid -match '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$') { $h['X-Invardia-Install-Id'] = $iid }
    $r = & $Http 'POST' "$base/api/updates/$Product/manifest" @{ kind = $Kind; licence = $LicenceText; ring = $Ring } $h
    $pullStatus = [int]$r.status
    return @{ status = $pullStatus; body = $r.body; reason = $(if ($pullStatus -eq 200) { '' } else { Get-InvardiaPullReason -Status $pullStatus -Body $r.body -ErrorText "$($r.error)" }) }
}

function Save-InvardiaArchive {
    <# Download the release zip and prove it is the one the manifest names (zip magic, size, SHA-256). @{ ok; bytes; reason }. #>
    param([Parameter(Mandatory)][string]$Url, [Parameter(Mandatory)][string]$OutFile, [Parameter(Mandatory)][string]$ExpectedSha256, [int64]$ExpectedSize = 0, [int]$TimeoutSeconds = 300)
    try { [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12 -bor [System.Net.ServicePointManager]::SecurityProtocol } catch { }
    try { Invoke-WebRequest -Uri $Url -OutFile $OutFile -UseBasicParsing -TimeoutSec $TimeoutSeconds -ErrorAction Stop }
    catch { return @{ ok = $false; bytes = 0; reason = "download failed: $($_.Exception.Message -replace '\?t=[^\s''"]+', '?t=***')" } }
    return (Test-InvardiaArchiveFile -Path $OutFile -ExpectedSha256 $ExpectedSha256 -ExpectedSize $ExpectedSize)
}

function Test-InvardiaArchiveFile {
    <# PURE (file read). The downloaded file is a zip of the size and SHA-256 the SIGNED manifest names. #>
    param([Parameter(Mandatory)][string]$Path, [Parameter(Mandatory)][string]$ExpectedSha256, [int64]$ExpectedSize = 0)
    # F4: the signed size is REQUIRED -- no expected size = refused (a caller that has none must not skip the length check)
    if ($ExpectedSize -lt 1) { return @{ ok = $false; bytes = 0; reason = 'no signed archive size to check the download against -- refused' } }
    if (-not (Test-Path -LiteralPath $Path)) { return @{ ok = $false; bytes = 0; reason = 'the download produced no file' } }
    $len = (Get-Item -LiteralPath $Path).Length
    $magic = New-Object byte[] 2
    $fs = [System.IO.File]::OpenRead($Path); try { [void]$fs.Read($magic, 0, 2) } finally { $fs.Dispose() }
    if ($magic[0] -ne 0x50 -or $magic[1] -ne 0x4B) { return @{ ok = $false; bytes = $len; reason = 'the downloaded file is not a zip' } }
    if ($len -ne $ExpectedSize) { return @{ ok = $false; bytes = $len; reason = "the archive is $len bytes, the signed manifest says $ExpectedSize" } }
    $sha = [System.Security.Cryptography.SHA256]::Create(); $fh = [System.IO.File]::OpenRead($Path)
    try { $h = ([BitConverter]::ToString($sha.ComputeHash($fh))).Replace('-', '').ToLowerInvariant() } finally { $fh.Dispose(); $sha.Dispose() }
    if ($h -ne "$ExpectedSha256".Trim().ToLowerInvariant()) { return @{ ok = $false; bytes = $len; reason = "the archive's SHA-256 ($h) is not the one the signed manifest names -- refused" } }
    return @{ ok = $true; bytes = $len; reason = '' }
}

# ===== END inlined helper: ../../engine/_shared/InvardiaUpdate.verify.ps1 =====
# ===== BEGIN inlined helper: _PimLoopbackAnswer.ps1 =====
# PIM-LoopbackAnswer.ps1 -- the ONE wait for a browser sign-in's answer on the localhost loopback (auth code + PKCE).
# Used by every PIM browser sign-in: the REST library's own (signed-in setup scripts), the mail setup (Initialize-PimMailSender,
# Set-PimSmtpRelayPassword, Set-PimSqlTier), the engine-permissions grant and the Activator deploy scripts. The tools load the
# identical copy in tools\setup (they may not load engine files). Build-PimSupportScripts inlines it into each published script.
#
# Owner 2026-10-30/31 ("people are reporting this error" -- "This site can't be reached"; "yes fix the sign-in page in all
# scripts"), the same fix as Invardia's Wait-AuthCode: the old loops took the FIRST request -- often the browser's preload
# of the address or its icon request -- and a request that never sent a line held the loop, and once the answer came the
# listener stopped at once, so the browser's real load or a reload got "This site can't be reached". Now:
#   1. only a request whose query carries code= or error= is the answer; the loop goes on until one comes;
#   2. EVERY request gets a page (waiting / signed in / failed), never a closed connection;
#   3. after the answer the listener keeps answering for -GraceSeconds (10), so a second load shows "Signed in" too;
#   4. it throws only when no answer came within -Seconds.
# A connection that sends nothing (a speculative preconnect) is dropped after -ReadTimeoutMs and never blocks the loop.

function Test-PimLoopbackAnswerQuery {
    # PURE. Is this request line the sign-in's answer? Returns the query string ('' when not).
    param([AllowEmptyString()][AllowNull()][string]$RequestLine)
    $m = [regex]::Match("$RequestLine", '^GET /[^?\s]*\?(?<q>\S+) HTTP')
    if (-not $m.Success) { return '' }
    $q = $m.Groups['q'].Value
    if ($q -match '(^|&)(code|error)=') { return $q }
    return ''
}

function Get-PimLoopbackPage {
    # PURE. The page for one request: before the answer 'waiting', after it 'done' (or 'failed' when the answer is an error).
    param([ValidateSet('waiting', 'done', 'failed')][string]$Kind, [string]$ReturnTo = 'PowerShell', [string]$ErrorText = '')
    $body = switch ($Kind) {
        'waiting' { '<h3>Waiting for the sign-in...</h3>Finish the sign-in in the other tab.' }
        'done'    { "<h3>Sign-in complete.</h3>You can close this tab and return to $([System.Net.WebUtility]::HtmlEncode($ReturnTo))." }
        'failed'  { "<h3>Sign-in failed</h3>$([System.Net.WebUtility]::HtmlEncode($ErrorText))<br>Return to $([System.Net.WebUtility]::HtmlEncode($ReturnTo))." }
    }
    "<html><head><meta charset=`"utf-8`"></head><body style=`"font-family:sans-serif`">$body</body></html>"
}

function Wait-PimLoopbackAnswer {
    <#
      Waits on the loopback listener(s) (TcpListener, started by the caller; both loopbacks may share one port) for the
      sign-in's answer and returns its raw query string. Throws only when no answer came within -Seconds. The caller still
      checks state / error / code and stops the listeners (this function does not stop them).
    #>
    param([Parameter(Mandatory)][object[]]$Listeners, [int]$Seconds = 300, [int]$GraceSeconds = 10, [int]$ReadTimeoutMs = 2000,
          [string]$ReturnTo = 'PowerShell', [string]$TimeoutMessage = '')
    $deadline = [DateTime]::UtcNow.AddSeconds($Seconds); $graceEnd = $null
    $answer = $null; $kind = 'waiting'; $errText = ''
    while ($true) {
        $now = [DateTime]::UtcNow
        if ($answer) { if ($now -ge $graceEnd) { break } } elseif ($now -ge $deadline) { break }
        $ready = @($Listeners | Where-Object { $_.Pending() })[0]
        if (-not $ready) { Start-Sleep -Milliseconds 100; continue }
        $client = $null
        try {
            $client = $ready.AcceptTcpClient()
            $client.ReceiveTimeout = $ReadTimeoutMs
            $stream = $client.GetStream()
            $reader = New-Object System.IO.StreamReader($stream)
            $line = $null
            try { $line = $reader.ReadLine() } catch { $line = $null }   # a connection that sends nothing: dropped, never waited on
            if ($null -eq $line) { continue }
            if (-not $answer) {
                $q = Test-PimLoopbackAnswerQuery -RequestLine $line
                if ($q) {
                    $answer = $q; $graceEnd = [DateTime]::UtcNow.AddSeconds($GraceSeconds)
                    if ($q -match '(^|&)error=') {
                        $kind = 'failed'
                        $d = [regex]::Match($q, '(^|&)error_description=(?<d>[^&]*)')
                        $errText = if ($d.Success) { [uri]::UnescapeDataString(($d.Groups['d'].Value -replace '\+', ' ')) } else { '' }
                    } else { $kind = 'done' }
                }
            }
            $html = Get-PimLoopbackPage -Kind $kind -ReturnTo $ReturnTo -ErrorText $errText
            $bytes = [Text.Encoding]::UTF8.GetBytes($html)
            $head = [Text.Encoding]::ASCII.GetBytes("HTTP/1.1 200 OK`r`nContent-Type: text/html; charset=utf-8`r`nContent-Length: $($bytes.Length)`r`nConnection: close`r`n`r`n")
            $stream.Write($head, 0, $head.Length); $stream.Write($bytes, 0, $bytes.Length); $stream.Flush()
        } catch { }   # a browser that closed the connection itself: nothing to answer
        finally { if ($client) { try { $client.Close() } catch { } } }
    }
    if (-not $answer) {
        throw $(if ("$TimeoutMessage".Trim()) { $TimeoutMessage } else { "Timed out ($([int]($Seconds / 60)) minutes) waiting for the browser to finish the sign-in." })
    }
    return $answer
}

# ===== END inlined helper: _PimLoopbackAnswer.ps1 =====

$script:PimInstallProBaseUrl = 'https://invardia.com'
$script:PimInstallProProduct = 'pim-manager'
$script:PimInstallArmAudience = 'https://management.azure.com'
# the Microsoft Azure CLI first-party public client APP ID, used over REST (not the az program) -- pre-authorised for ARM in
# every tenant; the same id PIM-Rest's browser sign-in uses (Get-PimInteractiveClientId)
$script:PimInstallSignInClientId = '04b07795-8ddb-461a-bbee-02f9e1bf7b46'
$script:PimInstallGuidRx = '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'

function Get-PimInstallProPackageUrl {
    <# PURE. The package route for -Ring and -TenantId (lower-cased). #>
    param([string]$BaseUrl = '', [Parameter(Mandatory)][ValidateRange(0, 3)][int]$Ring, [Parameter(Mandatory)][string]$TenantId)
    $base = if ("$BaseUrl".Trim()) { "$BaseUrl".Trim().TrimEnd('/') } else { $script:PimInstallProBaseUrl }
    return ("{0}/api/install/{1}/package?ring={2}&tenantId={3}" -f $base, $script:PimInstallProProduct, $Ring, "$TenantId".Trim().ToLowerInvariant())
}

function ConvertFrom-PimInstallProPackageAnswer {
    <#
      THE ONE PLACE THAT KNOWS THE SHAPE OF INVARDIA'S ANSWER (PRO-PACKAGE-FROM-INVARDIA). FINAL shape from Invardia
      2026-11-03 (apps/front/src/installpackage.ts), tests/Test-PimGuidedInstall.ps1 PP* pin it:
        200  FLAT { product; version; sequence; ring; manifest; manifestB64; signature; keyId; downloadUrl; sha256; size } --
             the signature is over manifestB64's bytes with keyId's key (/api/updates/keys); the archive is then checked
             against the SIGNED manifest's sha256 + size (never the unsigned top-level copies). 'package' nesting still read.
        401 notSignedIn | 403 wrongTenant (the token's tid != tenantId) | 404 noEnvironment / nothingReleased / notFound |
        422 invalid | 503 notConfigured -- each { error; message }: the message is shown, the launcher exits 3.
      PURE. Returns @{ ok; response (the object Test-InvardiaManifest reads); refused (Invardia said no) ; reason (one calm
      sentence, never a token) }.
    #>
    param([int]$Status, [AllowNull()][object]$Body, [string]$ErrorText = '', [int]$Ring = 3)
    $g = { param($o, $n) if ($null -eq $o) { return $null }; if ($o -is [System.Collections.IDictionary]) { return $o[$n] }; $pp = $o.PSObject.Properties[$n]; if ($pp) { $pp.Value } }
    # Invardia's refusal is { error; message }: its plain message first, then the code (older answers: 'reason')
    $why = "$(& $g $Body 'message')".Trim(); if (-not $why) { $why = "$(& $g $Body 'reason')".Trim() }; if (-not $why) { $why = "$(& $g $Body 'error')".Trim() }
    if ($why.Length -gt 300) { $why = $why.Substring(0, 297) + '...' }
    $whyTxt = if ($why) { " ($why)" } else { '' }
    switch ($Status) {
        200 {
            $o = $Body
            if (-not "$(& $g $o 'manifestB64')".Trim() -and $null -ne (& $g $o 'package')) { $o = & $g $o 'package' }
            if (-not "$(& $g $o 'manifestB64')".Trim()) { return @{ ok = $false; refused = $false; response = $null; reason = 'Invardia answered, but without a signed package manifest' } }
            return @{ ok = $true; refused = $false; response = [pscustomobject]@{ manifestB64 = "$(& $g $o 'manifestB64')"; signature = "$(& $g $o 'signature')"; keyId = "$(& $g $o 'keyId')"; downloadUrl = "$(& $g $o 'downloadUrl')" }; reason = '' }
        }
        204 { return @{ ok = $false; refused = $true; response = $null; reason = "Invardia has no PIM Manager release for ring $Ring yet" } }
        401 { return @{ ok = $false; refused = $true; response = $null; reason = "Invardia refused the sign-in$whyTxt -- sign in with an administrator account of the tenant you install into" } }
        403 { return @{ ok = $false; refused = $true; response = $null; reason = "Invardia refused the download for this tenant$whyTxt -- sign in with an account of the tenant you install into (-TenantId)" } }
        404 { return @{ ok = $false; refused = $true; response = $null; reason = "Invardia has no PIM Manager package for this tenant and ring $Ring$whyTxt" } }
        422 { return @{ ok = $false; refused = $true; response = $null; reason = "Invardia could not use the request$whyTxt" } }
        503 { return @{ ok = $false; refused = $false; response = $null; reason = "Invardia's install service is not ready$whyTxt -- run the command again later" } }
        429 { return @{ ok = $false; refused = $true; response = $null; reason = 'Invardia asked to wait (rate limit) -- run the command again in a few minutes' } }
        0   { return @{ ok = $false; refused = $false; response = $null; reason = "Invardia could not be reached$(if ("$ErrorText".Trim()) { " ($("$ErrorText".Trim()))" })" } }
        default { return @{ ok = $false; refused = ($Status -ge 400 -and $Status -lt 500); response = $null; reason = "Invardia answered HTTP $Status$whyTxt" } }
    }
}

function Invoke-PimInstallProHttp {
    <# The real seam: one GET with the bearer token, 60 s, @{ status; body; error }. A non-2xx is a status, never a throw;
       the error text never carries the token. #>
    param([Parameter(Mandatory)][string]$Url, [Parameter(Mandatory)][string]$Token)
    try { [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12 -bor [System.Net.ServicePointManager]::SecurityProtocol } catch { }
    try {
        $r = Invoke-WebRequest -Uri $Url -Method GET -Headers @{ Authorization = "Bearer $Token"; Accept = 'application/json'; 'User-Agent' = 'PIM-Manager-Installer' } -TimeoutSec 60 -UseBasicParsing -ErrorAction Stop
        $b = $null; if ("$($r.Content)".Trim()) { try { $b = "$($r.Content)" | ConvertFrom-Json } catch { $b = $null } }
        return @{ status = [int]$r.StatusCode; body = $b; error = '' }
    } catch {
        $code = 0; try { if ($_.Exception.Response) { $code = [int]$_.Exception.Response.StatusCode } } catch { $code = 0 }
        $b = $null; try { $t = "$($_.ErrorDetails.Message)".Trim(); if ($t.StartsWith('{')) { $b = $t | ConvertFrom-Json } } catch { $b = $null }
        $e = ((("$($_.Exception.Message)") -split "`n")[0]); if ($e.Contains($Token)) { $e = 'the request failed' }
        return @{ status = $code; body = $b; error = $e }
    }
}

function Get-PimInstallJwtClaims {
    # PURE. The payload claims of a JWT (claims read only, to ASSERT the tenant before it is used; the resource validates the token), or $null.
    param([string]$Token)
    try { $p = "$Token".Split('.')[1].Replace('-', '+').Replace('_', '/'); while ($p.Length % 4) { $p += '=' }; return ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($p)) | ConvertFrom-Json) } catch { return $null }
}

function Get-PimInstallSignInToken {
    <#
      The person's browser sign-in for the TARGET tenant: auth code + PKCE on the localhost loopback (IPv4 and, where the
      machine has it, IPv6 on the same port), the Azure CLI public client id over REST, -Audience (default ARM). An InPrivate
      Edge window when Edge is there (a saved profile account never signs in silently), else the default browser; the
      address is printed too. Never device code. Returns @{ token; expiresOn (epoch seconds) } in memory only; throws on a
      failed or timed-out sign-in, or a token for another tenant.
    #>
    param([Parameter(Mandatory)][string]$TenantId, [string]$Audience = $script:PimInstallArmAudience)
    $tenant = "$TenantId".Trim().ToLowerInvariant()
    $rnd = New-Object byte[] 32; [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($rnd)
    $b64u = { param([byte[]]$B) [Convert]::ToBase64String($B).TrimEnd('=').Replace('+', '-').Replace('/', '_') }
    $verifier = & $b64u $rnd
    $sha = [System.Security.Cryptography.SHA256]::Create(); try { $challenge = & $b64u ($sha.ComputeHash([Text.Encoding]::ASCII.GetBytes($verifier))) } finally { $sha.Dispose() }
    $state = [guid]::NewGuid().ToString('N')
    $v4 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::Loopback, 0); $v4.Start()
    $listeners = @($v4)
    $port = ([System.Net.IPEndPoint]$v4.LocalEndpoint).Port
    if ([System.Net.Sockets.Socket]::OSSupportsIPv6) { try { $v6 = New-Object System.Net.Sockets.TcpListener([System.Net.IPAddress]::IPv6Loopback, $port); $v6.Start(); $listeners += $v6 } catch { } }
    $redirect = "http://localhost:$port/"
    $scope = "$("$Audience".TrimEnd('/'))/.default offline_access openid profile"
    $authUrl = "https://login.microsoftonline.com/$tenant/oauth2/v2.0/authorize?client_id=$($script:PimInstallSignInClientId)&response_type=code&response_mode=query" +
               "&redirect_uri=$([uri]::EscapeDataString($redirect))&scope=$([uri]::EscapeDataString($scope))&state=$state" +
               "&code_challenge=$challenge&code_challenge_method=S256&prompt=select_account"
    Write-Host "Sign in in the browser as an administrator of tenant $tenant (PIM Manager Pro is downloaded from Invardia for that tenant)." -ForegroundColor Yellow
    Write-Host "  If the browser opens in the wrong profile or account, open this address in the right one: $authUrl" -ForegroundColor DarkGray
    $query = $null
    try {
        $edge = @((Join-Path "${env:ProgramFiles(x86)}" 'Microsoft\Edge\Application\msedge.exe'), (Join-Path "$env:ProgramFiles" 'Microsoft\Edge\Application\msedge.exe')) | Where-Object { $_ -and (Test-Path -LiteralPath $_) } | Select-Object -First 1
        if ("$env:PIM_SIGNIN_BROWSER".Trim() -ieq 'none') { }
        elseif ($edge) { Start-Process -FilePath $edge -ArgumentList @('--inprivate', '--new-window', $authUrl) -WhatIf:$false }
        else { try { Start-Process $authUrl -WhatIf:$false } catch { } }   # no browser here (Cloud Shell): the printed address
        $query = Wait-PimLoopbackAnswer -Listeners $listeners -Seconds 300 -TimeoutMessage 'the sign-in did not come back within 5 minutes'
    } finally { foreach ($l in $listeners) { try { $l.Stop() } catch { } } }
    $kv = @{}
    foreach ($pair in ("$query" -split '&')) { $k, $v = $pair -split '=', 2; $kv[$k] = if ($null -ne $v) { [uri]::UnescapeDataString(($v -replace '\+', ' ')) } else { '' } }
    if ($kv['error']) { throw "the sign-in failed: $($kv['error'])" }
    if ($kv['state'] -ne $state -or -not $kv['code']) { throw 'the sign-in answer was not this sign-in''s' }
    $r = Invoke-RestMethod -Method POST -Uri "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token" -ContentType 'application/x-www-form-urlencoded' -TimeoutSec 60 -Body @{
        client_id = $script:PimInstallSignInClientId; grant_type = 'authorization_code'; code = $kv['code']; redirect_uri = $redirect; code_verifier = $verifier; scope = $scope }
    $tok = "$($r.access_token)"
    $c = Get-PimInstallJwtClaims -Token $tok
    if (-not $c -or "$($c.tid)".Trim().ToLowerInvariant() -ne $tenant) { throw "you signed in to another tenant than $tenant -- sign in with an administrator account of $tenant" }
    $exp = [long]0; if (-not [long]::TryParse("$($c.exp)", [ref]$exp)) { $exp = [DateTimeOffset]::UtcNow.AddSeconds([int]$r.expires_in).ToUnixTimeSeconds() }
    return @{ token = $tok; expiresOn = $exp }
}

function Get-PimInstallEditionName {
    # PURE. 'pro' -> 'Pro', 'community' -> 'Community', anything else (a note of an older launcher) -> 'edition not recorded'
    param([string]$Channel)
    switch ("$Channel".Trim().ToLowerInvariant()) { 'pro' { 'Pro' } 'community' { 'Community' } default { '(edition not recorded)' } }
}

function Get-PimInstallResumeLine {
    <# PURE. Framework installer rule 12's ONE line when -Resume does NOT reuse the release downloaded before. #>
    param([string]$BeforeVersion, [string]$BeforeEdition, [string]$NowVersion, [string]$NowEdition)
    $bv = if ("$BeforeVersion".Trim()) { "$BeforeVersion".Trim().TrimStart('v') } else { '(version not recorded)' }
    $nv = if ("$NowVersion".Trim()) { "$NowVersion".Trim().TrimStart('v') } else { 'the current release' }
    return "Resume: the release downloaded before is $bv $(Get-PimInstallEditionName $BeforeEdition); this launcher installs $nv $(Get-PimInstallEditionName $NowEdition) - downloading it. The installation keeps its own progress, so it continues where it stopped."
}

function Get-PimInstallResumeChoice {
    <#
      FRAMEWORK INSTALLER RULE 12 (2026-11-04, "-Resume never reuses a different package"; PIM REQUIREMENTS OPEN-24). PURE.
      On -Resume the launcher reuses the release folder it downloaded before ONLY when that folder is still there, really
      holds the version its note says, was downloaded by the SAME edition (the note's 'edition' = this copy's
      $script:PimInstallChannel; a note without one -- an older launcher -- is never trusted), and -- when the version this
      launcher installs now is known (-WantVersion: -Version, or the release GitHub / the ring serves now) -- is that
      version. Anything else: download afresh, say so in ONE line, and the installation continues from its OWN saved
      progress (its state folder), which the download never touches.
        -Note        the folder note (path, version, edition) or $null      -Tree        the release tree found in note.path, or ''
        -TreeVersion that tree's VERSION file ('' = none)                   -Channel     'community' | 'pro' (this copy)
        -WantVersion the version this launcher installs now ('' = not known yet: folderOk tells whether the folder is still a
                     candidate, and the caller asks again with the version once GitHub / the ring has named it)
      Returns @{ reuse; folderOk; tree; version; edition; line } (line '' = nothing to say yet).
    #>
    param([AllowNull()][object]$Note, [string]$Tree = '', [string]$TreeVersion = '', [Parameter(Mandatory)][string]$Channel, [string]$WantVersion = '')
    $norm = { param($v) "$v".Trim().TrimStart('v') }
    $ch = "$Channel".Trim().ToLowerInvariant()
    $prop = { param($o, $n) if ($null -eq $o) { return '' }; if ($o -is [System.Collections.IDictionary]) { return "$($o[$n])" }; $pp = $o.PSObject.Properties[$n]; if ($pp) { "$($pp.Value)" } else { '' } }
    $nVer = & $norm (& $prop $Note 'version')
    $nEd = (& $prop $Note 'edition').Trim().ToLowerInvariant()
    $res = @{ reuse = $false; folderOk = $false; tree = "$Tree"; version = $nVer; edition = $nEd; line = '' }
    if (-not $Note -or -not "$Tree".Trim()) {
        $res.line = 'Resume: the release folder of the first run is not there any more, so the release is downloaded again. The installation keeps its own progress, so it still continues where it stopped.'
        return $res
    }
    if ((& $norm $TreeVersion) -and $nVer -and (& $norm $TreeVersion) -ne $nVer) {
        $res.line = "Resume: the release folder of the first run holds $(& $norm $TreeVersion), not the $nVer it was downloaded as, so the release is downloaded again. The installation keeps its own progress, so it continues where it stopped."
        return $res
    }
    $res.folderOk = $true
    $want = & $norm $WantVersion
    if (-not $want) { return $res }   # the caller resolves the version this launcher installs now, then asks again
    if ($nEd -ne $ch -or -not $nVer -or $want -ne $nVer) {
        $res.line = Get-PimInstallResumeLine -BeforeVersion $nVer -BeforeEdition $nEd -NowVersion $want -NowEdition $ch
        return $res
    }
    $res.reuse = $true
    $res.line = "Resume: using the release downloaded before ($nVer $(Get-PimInstallEditionName $nEd)) in $Tree -- nothing is downloaded."
    return $res
}

function Get-PimInstallProPackage {
    <#
      The Pro copy's whole download, every outside call a seam:
        -GetToken { param($TenantId) } -> @{ token; expiresOn } (or a token string)   default: Get-PimInstallSignInToken
        -Http     { param($Url, $Token) } -> @{ status; body; error }                 default: Invoke-PimInstallProHttp
        -Download { param($Url, $OutFile) }                                         the launcher's own download
      -ResumeFrom (framework installer rule 12, -Resume): @{ version; edition; tree } of the release downloaded before (the
      launcher's Get-PimInstallResumeChoice with folderOk). When it is the Pro package of exactly the version the ring serves
      now, nothing is downloaded (reused = $true); otherwise its ONE line is printed and the package the ring serves now is
      downloaded.
      Returns @{ ok; reused; line (the reuse line); reason; dir; zip; version; sha256; size; token; expiresOn }. ok=$false -> reason is ONE calm
      sentence (never a token, never a link); the new folder is removed. Nothing is ever asked of GitHub.
    #>
    param([Parameter(Mandatory)][AllowEmptyString()][string]$TenantId, [ValidateRange(0, 3)][int]$Ring = 3, [string]$Version = '',
          [scriptblock]$GetToken, [scriptblock]$Http, [Parameter(Mandatory)][scriptblock]$Download,
          [object[]]$TrustedKeys = $script:InvardiaUpdateTrustedKeys, [string]$BaseUrl = '', [string]$TempRoot = ([IO.Path]::GetTempPath()),
          [hashtable]$ResumeFrom)
    $res = @{ ok = $false; reused = $false; line = ''; reason = ''; dir = ''; zip = ''; version = ''; sha256 = ''; size = 0; token = ''; expiresOn = 0 }
    $tid = "$TenantId".Trim().ToLowerInvariant()
    if ($tid -notmatch $script:PimInstallGuidRx) { $res.reason = 'PIM Manager Pro is downloaded for a tenant: give -TenantId (the tenant id, a GUID)'; return $res }
    if (-not $GetToken) { $GetToken = { param($t) Get-PimInstallSignInToken -TenantId $t } }
    if (-not $Http) { $Http = { param($u, $k) Invoke-PimInstallProHttp -Url $u -Token $k } }
    # 1. sign-in
    $tk = $null
    try { $tk = & $GetToken $tid } catch { $res.reason = "the sign-in for the download did not complete ($((("$($_.Exception.Message)") -split "`n")[0]))"; return $res }
    $token = if ($tk -is [string]) { $tk } else { "$($tk.token)" }
    if (-not $token.Trim()) { $res.reason = 'the sign-in for the download did not complete (no token)'; return $res }
    $res.token = $token; $res.expiresOn = $(if ($tk -isnot [string]) { [long]"$($tk.expiresOn)" } else { 0 })
    # 2. ask Invardia
    $a = $null
    try { $a = & $Http (Get-PimInstallProPackageUrl -BaseUrl $BaseUrl -Ring $Ring -TenantId $tid) $token } catch { $a = @{ status = 0; body = $null; error = 'the request failed' } }
    $p = ConvertFrom-PimInstallProPackageAnswer -Status ([int]$a.status) -Body $a.body -ErrorText "$($a.error)" -Ring $Ring
    if (-not $p.ok) { $res.reason = $p.reason; return $res }
    # 3. verify the signed manifest exactly as the updater does (this ring, kind code)
    $v = Test-InvardiaManifest -Response $p.response -TrustedKeys $TrustedKeys -Kind 'code' -Product $script:PimInstallProProduct -Ring $Ring
    if (-not $v.ok) { $res.reason = "the package Invardia sent did not verify ($($v.reason)) -- refused"; return $res }
    if ($v.hold) { $res.reason = "the release Invardia holds for ring $Ring cannot be installed by this command ($($v.reason))"; return $res }
    if ("$Version".Trim() -and "$($v.version)" -ne "$Version".Trim().TrimStart('v')) { $res.reason = "ring $Ring holds PIM Manager $($v.version), not $Version"; return $res }
    # 3b. framework installer rule 12: -Resume reuses the package downloaded before only when the ring serves that version now
    if ($ResumeFrom) {
        $rc = Get-PimInstallResumeChoice -Note $ResumeFrom -Tree "$($ResumeFrom.tree)" -Channel 'pro' -WantVersion "$($v.version)"
        if ($rc.reuse) { $res.ok = $true; $res.reused = $true; $res.version = "$($v.version)"; $res.line = $rc.line; return $res }
        Write-Host $rc.line -ForegroundColor Yellow
    }
    # 4. download into a NEW folder; size + SHA-256 must be the signed ones
    $dir = Join-Path $TempRoot ("pim-manager-release-{0}-{1}" -f $v.version, [guid]::NewGuid().ToString('N').Substring(0, 6))
    [void][IO.Directory]::CreateDirectory($dir)
    $zip = Join-Path $dir 'release.zip'
    Write-Host "PIM Manager Pro $($v.version) (ring $Ring, signed by Invardia) -- downloading into $dir"
    try { & $Download "$($v.downloadUrl)" $zip } catch { Write-Verbose "download: $((("$($_.Exception.Message)") -split "`n")[0] -replace '\?\S+', '?***')" }
    $chk = if (Test-Path -LiteralPath $zip -PathType Leaf) { Test-InvardiaArchiveFile -Path $zip -ExpectedSha256 $v.sha256 -ExpectedSize $v.size } else { @{ ok = $false; reason = 'the download did not complete' } }
    if (-not $chk.ok) { try { [IO.Directory]::Delete($dir, $true) } catch { }; $res.reason = "$($chk.reason) -- nothing was installed, the folder is removed"; return $res }
    $res.ok = $true; $res.dir = $dir; $res.zip = $zip; $res.version = "$($v.version)"; $res.sha256 = $v.sha256; $res.size = $v.size
    return $res
}

# ===== END inlined helper: _PimInstallProPackage.ps1 =====
$null = Start-PimScriptRun -Script 'Start-PimManagerInstall'
$launchCode = 0
try {
    $pimRepo = 'KnudsenMorten/PIM4EntraPS'
    $selfAsset = 'Start-PimManagerInstall.ps1'
    if ($PSVersionTable.PSVersion.Major -lt 7) { Write-Host 'This runs best in PowerShell 7 (Azure Cloud Shell, or pwsh on your machine).' -ForegroundColor Yellow }
    if (-not $GetRelease) {
        $GetRelease = { param([string]$Url) Invoke-RestMethod -Method GET -Uri $Url -Headers @{ Accept = 'application/vnd.github+json'; 'User-Agent' = 'PIM-Manager-Installer' } -TimeoutSec 60 }
    }
    if (-not $Download) {
        $Download = { param([string]$Url, [string]$OutFile) Invoke-WebRequest -Method GET -Uri $Url -OutFile $OutFile -UseBasicParsing -Headers @{ 'User-Agent' = 'PIM-Manager-Installer' } -TimeoutSec 900 | Out-Null }
    }
    if (-not $RunInstaller) {
        $RunInstaller = { param([string]$Path, [hashtable]$A) $global:LASTEXITCODE = 0; & $Path @A | Out-Host; [int]$LASTEXITCODE }
    }
    $tempRoot = [IO.Path]::GetTempPath()
    $sha256Hex = {
        param([string]$Path)
        $sha = [System.Security.Cryptography.SHA256]::Create()
        $fs = [IO.File]::OpenRead($Path)
        try { return (-join ($sha.ComputeHash($fs) | ForEach-Object { $_.ToString('x2') })) } finally { $fs.Dispose(); $sha.Dispose() }
    }
    $publishedSha = { param($Asset) if ("$($Asset.digest)" -match '^(?i)sha256:([0-9a-f]{64})$') { $Matches[1].ToLowerInvariant() } else { '' } }
    $releaseUrl = { param([string]$Ver) if ("$Ver".Trim()) { "https://api.github.com/repos/$pimRepo/releases/tags/v$("$Ver".Trim().TrimStart('v'))" } else { "https://api.github.com/repos/$pimRepo/releases/latest" } }
    # the folder note: one per tenant + subscription, so -Resume finds the release it downloaded
    $noteKeySrc = if ("$TenantId".Trim() -and "$SubscriptionId".Trim()) { ("{0}|{1}" -f "$TenantId".Trim(), "$SubscriptionId".Trim()).ToLowerInvariant() } else { 'default' }
    $sha0 = [System.Security.Cryptography.SHA256]::Create()
    try { $noteKey = -join ($sha0.ComputeHash([Text.Encoding]::UTF8.GetBytes($noteKeySrc))[0..5] | ForEach-Object { $_.ToString('x2') }) } finally { $sha0.Dispose() }
    $notePath = Join-Path $tempRoot "pim-manager-install-$noteKey.json"
    $findTree = {
        # the release tree inside an unpacked folder: VERSION at the top, or in its one sub-folder -- and the REPO-SHAPED Pro
        # package from Invardia (pim-manager-src-<v>/SOLUTIONS/PIM4EntraPS/...: the tree is its SOLUTIONS/PIM4EntraPS, the
        # layout the installer runs from in the repository)
        param([string]$Dir)
        $cands = @($Dir)
        $tops = @(Get-ChildItem -LiteralPath $Dir -Directory -ErrorAction SilentlyContinue)
        if ($tops.Count -eq 1) { $cands += $tops[0].FullName }
        foreach ($c in $cands) {
            if (Test-Path -LiteralPath (Join-Path $c 'tools/setup/Install-PimManager.ps1')) { return $c }
            $sol = Join-Path (Join-Path $c 'SOLUTIONS') 'PIM4EntraPS'
            if (Test-Path -LiteralPath (Join-Path $sol 'tools/setup/Install-PimManager.ps1')) { return $sol }
        }
        return ''
    }

    # one pass; a stop on the way sets $launchCode and leaves it with 'break' (the exit code is set after the transcript closes)
    do {
    # ---------------------------------------------------------------- INSTALL-1 ALIGN (6): -ViaSupportApp needs the session
    # Without the switch nothing changes (a Support-app session is still used when there is one). With it, the run stops
    # here -- before anything is downloaded -- unless Connect-InvardiaSupport connected THIS tenant in this window.
    $isa = $global:InvardiaSupportState
    if ($ViaSupportApp -and -not ($isa -is [hashtable] -and "$TenantId".Trim() -and "$($isa.TenantId)".Trim() -ieq "$TenantId".Trim())) {
        Write-Host "-ViaSupportApp: this PowerShell window has no Invardia Support session for tenant '$TenantId' -- run Connect-InvardiaSupport.ps1 -Environment <handle> for that tenant first, then this command again. Nothing was installed." -ForegroundColor Red
        $launchCode = 2; break
    }
    # ---------------------------------------------------------------- 0. this file is the one its release publishes
    # A downloaded copy carries the release version it was published with; a copy run from a release folder or the source
    # tree carries none and is already part of that tree. -ReleasePath downloads nothing, so it is not checked here.
    # The Pro copy is not a GitHub release file (Invardia hands it out with its own SHA256SUMS), so it is not checked here.
    $selfVer = if ("$TestSelfVersion".Trim()) { "$TestSelfVersion".Trim() } else { "$($script:PimScriptDocVersion)".Trim() }
    if ($selfVer -and -not "$ReleasePath".Trim() -and "$script:PimInstallChannel" -ne 'pro') {
        $selfRel = $null
        try { $selfRel = & $GetRelease (& $releaseUrl $selfVer) } catch { $selfRel = $null; Write-Verbose "$($_.Exception.Message)" }
        if (-not $selfRel) { Write-Host "The PIM Manager release $selfVer could not be read from GitHub. Check the network and run the command again." -ForegroundColor Red; $launchCode = 3; break }
        $selfPub = & $publishedSha (@(@($selfRel.assets) | Where-Object { "$($_.name)" -eq $selfAsset }) | Select-Object -First 1)
        if (-not $selfPub -or (& $sha256Hex $PSCommandPath) -ne $selfPub) {
            Write-Host "This copy of $selfAsset is not the one published with PIM Manager release $selfVer. Nothing was installed. Download it again with the first line of the command, then run it again." -ForegroundColor Red
            $launchCode = 3; break
        }
        Write-Host "$selfAsset matches the one published with release $selfVer"
    }

    # ---------------------------------------------------------------- 1. the release folder: given, remembered, or new
    $tree = ''
    $resumeChoice = $null
    if ("$ReleasePath".Trim()) {
        $tree = & $findTree ([IO.Path]::GetFullPath("$ReleasePath".Trim()))
        if (-not $tree) { Write-Host "The folder '$ReleasePath' does not hold a PIM Manager release (tools/setup/Install-PimManager.ps1 is not there)." -ForegroundColor Red; $launchCode = 3; break }
        Write-Host "Using the release in $tree (nothing is downloaded)."
    } elseif ($Resume -and (Test-Path -LiteralPath $notePath)) {
        # FRAMEWORK INSTALLER RULE 12 (OPEN-24): the folder of the first run is reused ONLY for the SAME edition AND the
        # version this launcher installs now (Get-PimInstallResumeChoice decides; the version is compared again below once
        # GitHub / the ring has named it). Otherwise: ONE line, a fresh download -- the install's own progress is in its
        # state folder, never in this release folder, so it still continues where it stopped.
        $note = $null; try { $note = [IO.File]::ReadAllText($notePath) | ConvertFrom-Json } catch { $note = $null }
        $rTree = ''; $rTreeVer = ''
        if ($note -and "$($note.path)".Trim() -and (Test-Path -LiteralPath "$($note.path)")) {
            $rTree = & $findTree "$($note.path)"
            if ($rTree) { $rTreeVer = $(try { "$([IO.File]::ReadAllText((Join-Path $rTree 'VERSION')))".Trim() } catch { '' }) }
        }
        $resumeChoice = Get-PimInstallResumeChoice -Note $note -Tree $rTree -TreeVersion $rTreeVer -Channel "$script:PimInstallChannel" -WantVersion "$Version"
        if ($resumeChoice.reuse) { $tree = $resumeChoice.tree; Write-Host $resumeChoice.line }   # -Version names the release downloaded before
        elseif ("$($resumeChoice.line)".Trim()) { Write-Host $resumeChoice.line -ForegroundColor Yellow; $resumeChoice = $null }
        # else: the folder is still a candidate -- decided below once GitHub / the ring names the version it serves now
    }
    $proHandoff = $null
    if (-not $tree -and "$script:PimInstallChannel" -eq 'pro') {
        # PRO-PACKAGE-FROM-INVARDIA (framework INSTALL-1: "github should be for community only"): the Pro copy downloads the
        # Pro package from Invardia after a browser sign-in -- the SAME signed manifest + zip its ring serves the updater,
        # verified the same way. NO GitHub fallback: a failure is one calm line and exit 3.
        $proRing = if ("$UpdateRing".Trim()) { [int]"$UpdateRing".Trim() } else { 3 }
        if (-not $GetInstallToken) {
            $GetInstallToken = if ($ViaSupportApp -and (Get-Command Get-InvardiaSupportToken -ErrorAction SilentlyContinue)) { { param($t) Get-InvardiaSupportToken -Resource 'https://management.azure.com' } }
                               else { { param($t) Get-PimInstallSignInToken -TenantId $t } }
        }
        # -Resume (rule 12): the ring is asked which version it serves now; the package of the first run is reused only when
        # it is that version (one sign-in either way, handed to the installer below)
        $pro = Get-PimInstallProPackage -TenantId "$TenantId" -Ring $proRing -Version "$Version" -GetToken $GetInstallToken -Http $InvardiaHttp -Download $Download -TempRoot $tempRoot -ResumeFrom $(if ($resumeChoice) { @{ version = $resumeChoice.version; edition = $resumeChoice.edition; tree = $resumeChoice.tree } } else { $null })
        if (-not $pro.ok) { Write-Host "PIM Manager Pro could not be downloaded from Invardia: $($pro.reason). Nothing was installed." -ForegroundColor Red; $launchCode = 3; break }
        if ($pro.reused) {
            $tree = $resumeChoice.tree
            Write-Host $pro.line
        } else {
            Write-Host "SHA-256 $($pro.sha256) -- matches the SHA-256 Invardia signed"
            $unpack = Join-Path $pro.dir 'release'
            if (-not ('System.IO.Compression.ZipFile' -as [type])) { Add-Type -AssemblyName System.IO.Compression.FileSystem }
            [System.IO.Compression.ZipFile]::ExtractToDirectory($pro.zip, $unpack)
            $tree = & $findTree $unpack
            if (-not $tree) { Write-Host "The PIM Manager Pro package $($pro.version) does not hold tools/setup/Install-PimManager.ps1. Nothing was installed." -ForegroundColor Red; $launchCode = 3; break }
            $treeVer = $(try { "$([IO.File]::ReadAllText((Join-Path $tree 'VERSION')))".Trim() } catch { '' })
            if ($treeVer -and $treeVer -ne $pro.version) { Write-Host "The package holds version $treeVer, not the signed $($pro.version). Nothing was installed." -ForegroundColor Red; $launchCode = 3; break }
            if (-not $WhatIfPreference) {
                try { [IO.File]::WriteAllText($notePath, ([ordered]@{ path = $tree; version = $pro.version; edition = 'pro'; savedUtc = [datetime]::UtcNow.ToString('o') } | ConvertTo-Json), (New-Object Text.UTF8Encoding($false))) } catch { Write-Verbose "$($_.Exception.Message)" }
            }
        }
        # framework 8.13 INSTALL-HANDOFF: the person signed in once here -- the installer (same process) takes that ARM ACCESS
        # token from PIM_HANDOFF_TOKENS (checked on its own claims there, removed from the environment at once). Never with
        # -ViaSupportApp (the installer uses the Support session itself); never a refresh token.
        if (-not $ViaSupportApp -and "$($pro.token)".Trim() -and [long]$pro.expiresOn -gt 0) {
            $proHandoff = ([ordered]@{ 'https://management.azure.com/' = [ordered]@{ access_token = "$($pro.token)"; expires_on = [long]$pro.expiresOn } } | ConvertTo-Json -Compress)
        }
        $pro.token = ''
    } elseif (-not $tree) {
        $relUrl = & $releaseUrl $Version
        $rel = $null
        try { $rel = & $GetRelease $relUrl } catch { $rel = $null; Write-Verbose "$($_.Exception.Message)" }
        if (-not $rel) { Write-Host "The PIM Manager release could not be read from GitHub ($relUrl). Check the network and run the command again." -ForegroundColor Red; $launchCode = 3; break }
        $relVer = "$($rel.tag_name)".Trim().TrimStart('v')
        # -Resume (rule 12): the release of the first run is reused only when it IS the release GitHub serves now
        $rc2 = if ($resumeChoice) { Get-PimInstallResumeChoice -Note @{ version = $resumeChoice.version; edition = $resumeChoice.edition } -Tree $resumeChoice.tree -Channel "$script:PimInstallChannel" -WantVersion $relVer } else { $null }
        if ($rc2 -and $rc2.reuse) { $tree = $rc2.tree; Write-Host $rc2.line }
        elseif ($rc2) { Write-Host $rc2.line -ForegroundColor Yellow }
        if (-not $tree) {
            $asset = @(@($rel.assets) | Where-Object { "$($_.name)" -match '^PIM4EntraPS-v[0-9][0-9A-Za-z.+-]*\.zip$' }) | Select-Object -First 1
            if (-not $asset -or -not "$($asset.browser_download_url)".Trim()) { Write-Host "The release $relVer has no PIM Manager zip to download." -ForegroundColor Red; $launchCode = 3; break }
            $published = & $publishedSha $asset
            if (-not $published) { Write-Host "The release $relVer does not publish the checksum of its zip, so it cannot be checked. Nothing was installed." -ForegroundColor Red; $launchCode = 3; break }
            $dir = Join-Path $tempRoot ("pim-manager-release-{0}-{1}" -f $relVer, [guid]::NewGuid().ToString('N').Substring(0, 6))
            [void][IO.Directory]::CreateDirectory($dir)
            $zip = Join-Path $dir 'release.zip'
            Write-Host "PIM Manager release $relVer -- downloading $($asset.name) into $dir"
            try { & $Download "$($asset.browser_download_url)" $zip } catch { Write-Verbose "$($_.Exception.Message)" }
            if (-not (Test-Path -LiteralPath $zip -PathType Leaf)) { Write-Host 'The download did not complete. Check the network and run the command again.' -ForegroundColor Red; try { [IO.Directory]::Delete($dir, $true) } catch { }; $launchCode = 3; break }
            $got = & $sha256Hex $zip
            if ($got -ne $published) {
                Write-Host "The download does not match the SHA-256 the release publishes ($published; the download has $got). Nothing was installed; the folder is removed. Run the command again." -ForegroundColor Red
                try { [IO.Directory]::Delete($dir, $true) } catch { }
                $launchCode = 3; break
            }
            Write-Host "SHA-256 $got -- matches the SHA-256 the release publishes"
            $unpack = Join-Path $dir 'release'
            if (-not ('System.IO.Compression.ZipFile' -as [type])) { Add-Type -AssemblyName System.IO.Compression.FileSystem }
            [System.IO.Compression.ZipFile]::ExtractToDirectory($zip, $unpack)
            $tree = & $findTree $unpack
            if (-not $tree) { Write-Host "The release $relVer does not hold tools/setup/Install-PimManager.ps1." -ForegroundColor Red; $launchCode = 3; break }
            $treeVer = $(try { "$([IO.File]::ReadAllText((Join-Path $tree 'VERSION')))".Trim() } catch { '' })
            if ("$Version".Trim() -and $treeVer -and $treeVer -ne "$Version".Trim().TrimStart('v')) { Write-Host "The release holds version $treeVer, not $Version." -ForegroundColor Red; $launchCode = 3; break }
            # -WhatIf writes nothing outside this new temp folder: the note is written by a real run only
            if (-not $WhatIfPreference) {
                try { [IO.File]::WriteAllText($notePath, ([ordered]@{ path = $tree; version = $(if ($treeVer) { $treeVer } else { $relVer }); edition = 'community'; savedUtc = [datetime]::UtcNow.ToString('o') } | ConvertTo-Json), (New-Object Text.UTF8Encoding($false))) } catch { Write-Verbose "$($_.Exception.Message)" }
            }
        }
    }
    Write-Host "Release files: $tree"
    Write-Host '  (to continue after a stop, run the same command again with -Resume -- this folder is used again)' -ForegroundColor DarkGray

    # ---------------------------------------------------------------- 2. run the installer from the release, same parameters
    $pass = @{}
    foreach ($k in @('TenantId', 'SubscriptionId', 'Location', 'ResourceGroup', 'SuperAdmins', 'AlertRecipients', 'MailSender', 'PortalUsers', 'AllowAllMembers', 'VnetAddressPrefix', 'SubnetAddressPrefix', 'Exposure', 'Edition', 'UpdateRing', 'KeyVaultName', 'EngineAzureRootUserAccessAdmin', 'InstallId', 'SupportAppId', 'SupportAccess', 'Reporter', 'StatePath', 'Resume', 'PreflightOnly', 'ViaSupportApp')) {
        if ($PSBoundParameters.ContainsKey($k)) { $pass[$k] = $PSBoundParameters[$k] }
    }
    # PRIVATE NETWORK (INSTALL-1 item 5): the network parameters, passed through unchanged
    foreach ($k in @('PrivateNetwork', 'VnetId', 'VnetName', 'AppsSubnetName', 'AppsSubnetPrefix', 'EndpointsSubnetName', 'EndpointsSubnetPrefix', 'PrivateDnsZonesResourceGroupId', 'HubVnetId', 'LinkZonesToHub', 'PeerToHub', 'InternalRanges', 'FirewallIp', 'WebAppAccess')) {
        if ($PSBoundParameters.ContainsKey($k)) { $pass[$k] = $PSBoundParameters[$k] }
    }
    # INSTALL-1 ALIGN: the edition comes from this copy (a given -Edition still wins for one release); the ring defaults to 3
    if (-not "$($pass['Edition'])".Trim()) { $pass['Edition'] = $(if ("$script:PimInstallChannel" -eq 'pro') { 'Pro' } else { 'Community' }) }
    if (-not "$($pass['UpdateRing'])".Trim()) { $pass['UpdateRing'] = $UpdateRing }
    if ($WhatIfPreference) { $pass['WhatIf'] = $true }
    $installer = Join-Path $tree 'tools/setup/Install-PimManager.ps1'
    if ($proHandoff -and -not "$env:PIM_HANDOFF_TOKENS".Trim()) { $env:PIM_HANDOFF_TOKENS = $proHandoff }
    try { $launchCode = [int](@(& $RunInstaller $installer $pass) | Select-Object -Last 1) }
    finally { if ($proHandoff) { $env:PIM_HANDOFF_TOKENS = $null; $proHandoff = $null } }
    if ($launchCode -ne 0) { Write-Host "Release files: $tree -- the same command with -Resume continues from here." -ForegroundColor Yellow }
    } while ($false)
} finally {
    Stop-PimScriptRun -Script 'Start-PimManagerInstall'   # framework 12.7: "Log written: <path>" on every exit
}
$global:LASTEXITCODE = $launchCode
exit $launchCode