fix(installer): stop it lying, stop it leaking, and make it findable

Nine fixes from a review of the installer against its actual audience: DT leads
at sister sites who are not Windows, IIS or Python specialists and who will lean
on an AI assistant to get through it.

TRUTHFULNESS. The preflight was advisory - an operator read 'IIS is not
installed', pressed Next, answered five more pages and the install died partway
through with Python already on the box. The results page now blocks while
anything is failing, repaints on every run instead of latching after the first,
and offers 'Check again' so a fixed problem does not mean starting over. On
failure the wizard said 'Nothing was left running', which is false in every path
because the stages run with -OnFailure never: it now says the server is
part-configured, that re-running is safe, and how to remove it. The final page no
longer reads 'ShopDB-Flask is ready' after a failed install.

SECRETS. The generated MySQL root password went to Write-Host in a process the
wizard runs hidden - so nobody saw it - and stdout is forwarded into the setup
log operators are told to send to support, so it was permanently recorded for
everyone who did not need it. It now goes to an ACL'd file. Database dumps, which
contain every user password hash, landed in a ProgramData directory readable by
every user on the box; the directory is now locked at creation.

UPGRADES ON REMOTE-DATABASE SITES. mysqldump was looked for only under local
MySQL install paths, so a site whose database is on another host silently skipped
every pre-upgrade backup - after stage 2 had already stopped the pool and
replaced the tree. Find-MysqlTool now prefers a client shipped in the bundle,
stage 2 stages it onto the server, preflight reports when it is missing, and
mysqlclient\ is an optional locked payload.

UNINSTALL. A subpath install is an IIS Application, not a site; removing only the
site left the application pointing at a deleted directory, so the parent site -
at West Jefferson, the live classic ASP - served 503 on that path forever while
Add/Remove Programs reported success. Uninstall now reads MOUNT_PATH and removes
the application. The firewall rule was created as "$SiteName $SitePort" and
removed as the literal 'ShopDB-Flask 8090', which matches nothing.

DAY-2 TOOLING. Every shortcut now passes -AppRoot and -SitePort, and the console
forwards them through its own elevation and 32-bit relaunches instead of
discarding them - a non-default directory or port made it report a healthy site
as broken, from a shortcut the installer wrote. 'Open ShopDB-Flask' resolved to a
hardcoded localhost:8090 that was wrong for every subpath install; it now asks
the console, which reads the address the installer recorded, and no longer
demands administrator to open a browser.

SMOKE TEST. The parent-site port lookup filtered for an http binding and
defaulted to 80, so an https-only parent site failed a working install with a red
dialog.

DOCS AND /api/docs. The installer was invisible: nothing in docs/, README.md or
CLAUDE.md mentioned it, so a DT lead or their assistant landed on the manual IIS
runbook and hand-built the very server the installer then refuses to upgrade.
docs/INSTALL-WINDOWS.md and docs/OPERATE-WINDOWS.md are now the canonical route,
the two manual runbooks are bannered as reference-only, README and CLAUDE.md
route by target, and llms.txt tells an assistant which document to follow and to
ask for 'check -Json' before diagnosing. Both ship on the server, along with
openapi.json and llms.txt - without those the self-hosted /api/docs was broken on
every installed box, which matters most to the sites least able to debug it.
Stage 5 now checks it actually serves.

shopdb-admin.ps1 gains 'check -Json': one structured, secret-free block covering
version, publishing method, IIS state, HTTP reachability, database, Python
version, plugins and errors. That is the cheapest useful answer to 'the operator
will ask an LLM' - it works with no infrastructure, which a install-time MCP
server could not.

deploy/windows/installer/shopdb-install.ps1

@@ -396,6 +396,19 @@ function Compare-Version {
 
 function Find-MysqlTool {
     param([string] $Name)   # mysql.exe or mysqldump.exe
+    # The BUNDLE first, then the install directory, then the local server.
+    #
+    # A site whose MySQL lives on another host has no client installed here at
+    # all, so mysqldump was never found - which meant every upgrade skipped the
+    # pre-upgrade backup, and it did so AFTER stage 2 had stopped the pool and
+    # replaced the application tree. Shipping the client makes the backup work
+    # on a remote-database site, which is the case that needs it most.
+    $bundled = @(
+        (Join-Path $BundleRoot ('mysqlclient\' + $Name)),
+        (Join-Path $AppRoot ('mysqlclient\' + $Name))
+    )
+    foreach ($b in $bundled) { if (Test-Path $b) { return $b } }
+
     $roots = @('C:\Program Files\MySQL', 'C:\mysql56\bin', 'C:\Program Files (x86)\MySQL')
     foreach ($r in $roots) {
         if (Test-Path $r) {
@@ -468,8 +481,14 @@ function Backup-Database {
     $dump = Find-MysqlTool 'mysqldump.exe'
     if (-not $dump) { Write-Log 'mysqldump not found; skipping backup' 'WARN'; return '' }
 
+    # A dump contains every row, including the users table and its password
+    # hashes. ProgramData is readable by every user on the box by default, so the
+    # directory is locked to Administrators and SYSTEM the moment it is created.
     $dir = Join-Path $env:ProgramData 'ShopDB-Flask\backups'
-    if (-not (Test-Path $dir)) { New-Item -ItemType Directory -Path $dir -Force | Out-Null }
+    if (-not (Test-Path $dir)) {
+        New-Item -ItemType Directory -Path $dir -Force | Out-Null
+        Protect-File $dir
+    }
     $file = Join-Path $dir ("{0}-{1}-{2}.sql" -f $db.Name, $Reason, (Get-Date -Format 'yyyyMMdd-HHmmss'))
 
     Write-Log "backing up $($db.Name) before migrating"
@@ -749,11 +768,28 @@ FLUSH PRIVILEGES;
     Write-Log "database $DbName and user $DbUser created" 'OK'
     Write-Log "app password written to $handoff (stage 2 consumes and deletes it)"
 
-    Write-Host ''
-    Write-Host '  MySQL root password (shown ONCE, not stored anywhere):' -ForegroundColor Yellow
-    Write-Host ("    {0}" -f $rootPass) -ForegroundColor Yellow
-    Write-Host '  Write it down now. It cannot be recovered.' -ForegroundColor Yellow
-    Write-Host ''
+    # NOT Write-Host. Under the wizard this process runs hidden, so nobody ever
+    # saw this - and every line of stdout is forwarded into the setup log that
+    # operators are told to send to support. The generated root password was
+    # therefore invisible to the person who needed it and permanently recorded
+    # for everyone who did not.
+    #
+    # Write it to a file only Administrators and SYSTEM can read, and let the
+    # wizard tell the operator where it is.
+    $rootFile = Join-Path $env:ProgramData 'ShopDB-Flask\mysql-root-password.txt'
+    $rootDir = Split-Path $rootFile -Parent
+    if (-not (Test-Path $rootDir)) { New-Item -ItemType Directory -Path $rootDir -Force | Out-Null }
+    New-Item -ItemType File -Force -Path $rootFile | Out-Null
+    Protect-File $rootFile
+    Set-Content -Path $rootFile -Value @(
+        'MySQL root password for this server, generated during installation.',
+        'It is not recorded anywhere else and cannot be recovered.',
+        'Move it into your password manager, then delete this file.',
+        '',
+        $rootPass
+    ) -Encoding UTF8
+    Write-Log "MySQL root password written to $rootFile (Administrators and SYSTEM only)" 'OK'
+    Write-Log 'MYSQLROOTFILE:' + $rootFile
     Write-Log 'stage 0 complete' 'OK'
 }
 
@@ -900,6 +936,17 @@ a page that cannot load its own assets. Rebuild with scripts/build-site.sh
     if (-not $WhatIfOnly) {
         $bundledLock = Join-Path $BundleRoot 'bundle-lock.json'
         if (Test-Path $bundledLock) { Copy-Item $bundledLock $AppRoot -Force }
+        # The MySQL client stays on the server. The bundle is extracted to a temp
+        # directory and deleted when Setup exits, so a copy that lived only there
+        # would leave `shopdb-admin backup` with nothing to run on a site whose
+        # database is on another host.
+        $bundledClient = Join-Path $BundleRoot 'mysqlclient'
+        if (Test-Path $bundledClient) {
+            $target = Join-Path $AppRoot 'mysqlclient'
+            if (-not (Test-Path $target)) { New-Item -ItemType Directory -Path $target -Force | Out-Null }
+            Copy-Item (Join-Path $bundledClient '*') $target -Recurse -Force
+            Write-Log 'MySQL client staged for backups' 'OK'
+        }
     }
     foreach ($sub in @('logs','instance')) {
         $p = Join-Path $AppRoot $sub
@@ -1659,15 +1706,44 @@ function Invoke-Stage5 {
     # requesting http://localhost:8090/ would test a site that does not exist.
     if ($MountAlias) {
         $alias = $MountAlias.Trim('/')
-        $parentPort = 80
+        # Prefer an http binding, but fall back to https. A parent site published
+        # ONLY over https - which is normal, and which the operator did nothing
+        # wrong to have - left this defaulting to port 80, requesting a URL that
+        # answers nothing, and failing a working install with a red dialog.
+        $parentScheme = 'http'
+        $parentPort = 0
         try {
-            $b = (Get-Website -Name $ParentSite -ErrorAction SilentlyContinue).bindings.Collection |
-                 Where-Object { $_.protocol -eq 'http' } | Select-Object -First 1
+            $bindings = (Get-Website -Name $ParentSite -ErrorAction SilentlyContinue).bindings.Collection
+            $b = $bindings | Where-Object { $_.protocol -eq 'http' } | Select-Object -First 1
+            if (-not $b) {
+                $b = $bindings | Where-Object { $_.protocol -eq 'https' } | Select-Object -First 1
+                if ($b) { $parentScheme = 'https' }
+            }
             if ($b -and ($b.bindingInformation -match '^[^:]*:(\d+):')) { $parentPort = [int]$Matches[1] }
         } catch { }
-        $targets = @("http://localhost:$parentPort/$alias/")
+        if ($parentPort -eq 0) { $parentPort = if ($parentScheme -eq 'https') { 443 } else { 80 } }
+
+        $targets = @("{0}://localhost:{1}/{2}/" -f $parentScheme, $parentPort, $alias)
         if ($hostName -and $hostName -ne 'localhost') {
-            $targets += "http://{0}:{1}/{2}/" -f $hostName, $parentPort, $alias
+            $targets += "{0}://{1}:{2}/{3}/" -f $parentScheme, $hostName, $parentPort, $alias
+        }
+        # An https parent almost certainly has a certificate for its real name,
+        # not for 'localhost', and a certificate complaint is not an application
+        # fault. Accept any certificate for the duration of the smoke test only.
+        if ($parentScheme -eq 'https') {
+            Write-Log 'parent site is https-only; certificate validation is skipped for this check' 'WARN'
+            try {
+                Add-Type -TypeDefinition @'
+using System.Net;
+using System.Security.Cryptography.X509Certificates;
+public class ShopdbSmokeTestCertPolicy : ICertificatePolicy {
+    public bool CheckValidationResult(ServicePoint sp, X509Certificate cert, WebRequest req, int problem) {
+        return true;
+    }
+}
+'@ -ErrorAction SilentlyContinue
+                [System.Net.ServicePointManager]::CertificatePolicy = New-Object ShopdbSmokeTestCertPolicy
+            } catch { }
         }
     } else {
         $targets  = @("http://localhost:$SitePort/")
@@ -1707,6 +1783,21 @@ function Invoke-Stage5 {
         }
     }
 
+    # The self-hosted API documentation. It is the thing an operator - or the
+    # assistant an operator is asking - reaches for on a server with no internet,
+    # and it is served from a file that has to have been staged into the build.
+    # A missing file makes /api/docs render an empty page, which nobody notices
+    # until it is needed. Warn, never fail: the application itself is fine.
+    $base = $targets[0].TrimEnd('/')
+    try {
+        $d = Invoke-WebRequest -Uri "$base/api/docs/openapi.json" -UseBasicParsing -TimeoutSec 20
+        if ($d.StatusCode -eq 200) { Write-Log 'API documentation is being served at /api/docs' 'OK' }
+        else { Write-Log "/api/docs/openapi.json returned $($d.StatusCode)" 'WARN' }
+    } catch {
+        Write-Log '/api/docs is NOT working - docs/openapi.json was not staged into this build' 'WARN'
+        Write-Log '  the site runs fine; offline API reference and LLM assistance will not' 'WARN'
+    }
+
     # The install is proven working, so the stage-0 handoff is no longer the only
     # copy of the generated password (.env has it and the app is running on it).
     # Safe to shred now, and only now - see the note in stage 2.
@@ -1806,6 +1897,34 @@ function Invoke-Uninstall {
 
     Import-Module WebAdministration -ErrorAction SilentlyContinue
 
+    # A SUBPATH install has no site of its own - it is an Application under an
+    # existing one. Removing only the site left the application in place, pointed
+    # at a directory this is about to delete, so the parent site (at West
+    # Jefferson, the live classic ASP) served 503 on that path forever and
+    # Add/Remove Programs reported success.
+    #
+    # The alias is whatever MOUNT_PATH says, which is the same value wsgi.py
+    # mounts on, so it cannot disagree with how the app was actually published.
+    $mount = ''
+    $envFile = Join-Path $AppRoot '.env'
+    if (Test-Path $envFile) {
+        $line = Get-Content $envFile -ErrorAction SilentlyContinue |
+                Where-Object { $_ -like 'MOUNT_PATH=*' } | Select-Object -First 1
+        if ($line) { $mount = $line.Substring('MOUNT_PATH='.Length).Trim().Trim('/') }
+    }
+    if ($mount) {
+        $removed = $false
+        foreach ($site in (Get-Website -ErrorAction SilentlyContinue)) {
+            $app = Get-WebApplication -Site $site.Name -Name $mount -ErrorAction SilentlyContinue
+            if ($app) {
+                Remove-WebApplication -Site $site.Name -Name $mount -ErrorAction SilentlyContinue
+                Write-Log "removed application /$mount from site '$($site.Name)'" 'OK'
+                $removed = $true
+            }
+        }
+        if (-not $removed) { Write-Log "application /$mount not present" }
+    }
+
     if (Get-Website -Name $SiteName -ErrorAction SilentlyContinue) {
         Remove-Website -Name $SiteName -ErrorAction SilentlyContinue
         Write-Log "removed site $SiteName" 'OK'
@@ -1820,11 +1939,22 @@ function Invoke-Uninstall {
         Write-Log "removed app pool $AppPool" 'OK'
     } else { Write-Log "app pool $AppPool not present" }
 
-    $rule = "ShopDB-Flask $SitePort"
+    # Stage 4 creates the rule as "$SiteName $SitePort". This looked for the
+    # literal "ShopDB-Flask 8090", which is not the same string as the default
+    # "shopdb-flask 8090" and matches nothing at all on a non-default port, so
+    # the rule outlived the uninstall. Build the name the same way stage 4 does,
+    # and sweep any rule left by a differently-ported install of the same site.
+    $rule = "$SiteName $SitePort"
     if (Get-NetFirewallRule -DisplayName $rule -ErrorAction SilentlyContinue) {
         Remove-NetFirewallRule -DisplayName $rule -ErrorAction SilentlyContinue
         Write-Log "removed firewall rule '$rule'" 'OK'
     } else { Write-Log "firewall rule '$rule' not present" }
+    Get-NetFirewallRule -ErrorAction SilentlyContinue |
+        Where-Object { $_.DisplayName -like "$SiteName *" -and $_.DisplayName -ne $rule } |
+        ForEach-Object {
+            Remove-NetFirewallRule -DisplayName $_.DisplayName -ErrorAction SilentlyContinue
+            Write-Log "removed leftover firewall rule '$($_.DisplayName)'" 'OK'
+        }
 
     if (Test-Path $AppRoot) {
         # .env holds the database password in plaintext by design (the app reads it