getculpa 1.0.7 → 1.0.10

package/README.md

@@ -5,7 +5,11 @@ money went, across models, features and users, on your own machine.
 
 **`npm i -g getculpa` provisions the full Culpa install — the same files,
 shortcuts, and registration the Windows installer lays down — and starts
-nothing.** `getculpa` is what wakes the stack up.
+nothing.** `getculpa` is what wakes the stack up. On npm 12 or newer, npm
+blocks install scripts by default: install with
+`npm i -g --allow-scripts=getculpa getculpa` (or run
+`npm config set allow-scripts=getculpa --location=user` once). If `getculpa`
+says Culpa was never provisioned, that is why.
 
 - `getculpa` / `getculpa start` — start (or resume) the Culpa stack
 - `getculpa stop` — stop the running stack (`docker compose stop`; recorded data is kept)
@@ -14,7 +18,7 @@ nothing.** `getculpa` is what wakes the stack up.
 - `getculpa doctor` — diagnose this install (version/platform, file integrity, Docker, container state, ports, health, license presence — never prints key material); exits 1 if a check fails
 - `getculpa repair` — re-stage any missing/corrupt install files (never touches an existing `docker-compose.yml` or recorded data); idempotent
 - `getculpa uninstall` — remove Culpa (recorded data is kept unless you confirm)
-- `getculpa scan` — zero-install local scan, no Docker, no network
+- `getculpa scan` — refresh the Culpa ledger scan (needs the running stack); `getculpa scan --preview` reads local logs offline: no Docker, no network
 - `getculpa connect` — print the topology-appropriate capture recipe (`--fly` also emits a ready-to-deploy Fly.io shape)
 - `getculpa update` — manage CLI launcher updates
 

package/assets/culpa-compose.yml

@@ -5,7 +5,7 @@
 # name is used when present, which is how these pins were verified before
 # publication.
 #
-# ── RELEASE STATE: v1.0.7 PUBLISHED AND SIGNED (2026-08-29) ─────────
+# ── RELEASE STATE: v1.0.10 PUBLISHED AND SIGNED (2026-09-05) ────────
 # The line above is REWRITTEN BY installers/publish.sh at real-publish time —
 # this file has shipped a hand-edited, wrong publication claim twice, so the
 # claim is now mechanical, never prose. While it reads NOT PUBLISHED, the pins
@@ -55,7 +55,7 @@ services:
     restart: unless-stopped
 
   server:
-    image: ghcr.io/myaigidev/culpa-server:v1.0.7
+    image: ghcr.io/myaigidev/culpa-server:v1.0.10
     container_name: culpa-server
     environment:
       DATABASE_URL: postgres://culpa:culpa@db:5432/culpa
@@ -129,7 +129,7 @@ services:
     # (D-072: never rebuild a tag that already exists). The example this note
     # used to give was CF14's v0.11.0/v0.11.1 pair, which no longer matches
     # either pin in this file.
-    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.7
+    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.10
     container_name: culpa-dashboard
     environment:
       CULPA_API_BASE: http://server:4545

package/assets/uninstall-culpa.ps1

@@ -1,227 +1,251 @@
-# Culpa uninstaller for Windows (T-087, T-IX-01).
-# Stops and removes the containers and shortcuts. Your recorded data is
-# KEPT unless you answer Y to the final question.
-# -FromUninstaller: run by the setup.exe's uninstaller - no interactive
-# prompts, data always kept (never delete data without an explicit yes).
-#
-# CR-PR5 round 2 (SAFETY ORDERING): the canonical-path check now gates EVERY
-# destructive action - docker down, the data-volume prompt, and file removal.
-# A copy of this script run from anywhere else previously could stop the real
-# `culpa` project and offer to delete culpa_pgdata, the shared data volume.
-# T-CF29-2 params:
-#   -Force                      proceed from THIS directory even when the
-#                               canonical check disagrees (explicit opt-in;
-#                               never automatic)
-#   -RecordedInstallLocation    inject what the registry would return, so the
-#                               resolution can be tested without touching HKCU
-#                               (same -Probe precedent as install-culpa.ps1)
-#   -CanonicalOverrideForTest   inject the fallback directory, for the same reason
-#   -PrintPlanOnly              resolve, print the decision as JSON, exit 0
-#                               BEFORE any destructive action
-param(
-    [switch]$FromUninstaller,
-    [switch]$Force,
-    [string]$RecordedInstallLocation,
-    [string]$CanonicalOverrideForTest,
-    [switch]$PrintPlanOnly
-)
-
-$ErrorActionPreference = "SilentlyContinue"
-$AppDir = $PSScriptRoot
-# CF5-F11: the install directory is the founder's choice now, so "canonical"
-# is what SETUP RECORDED, not a hardcoded path. Inno writes InstallLocation
-# into its own uninstall key; fall back to %LOCALAPPDATA%\Culpa for installs
-# made before the directory page existed, and for the zip layout.
-# The guard itself is unchanged and still load-bearing: a stray COPY of this
-# script must never stop containers or delete files belonging to the real
-# install.
-#
-# T-CF29-2: a recorded value that POINTS AT A DELETED DIRECTORY used to be
-# trusted anyway, so the guard below could never match and Culpa became
-# impossible to uninstall. That is not hypothetical — the CF20 npm gate
-# overwrote this shared value with a scratch dir which was then removed.
-# A path that does not exist cannot be shadowing a real install, so it is
-# ignored in favour of the default. Everything else about the guard stands.
-# T-CF29-2: the guard compared raw strings, so two spellings of the SAME
-# directory read as different installs — an 8.3 short path (C:\Users\ZOLANI~1)
-# versus its long form, a trailing backslash, or different casing. Each of
-# those turns the uninstaller into the same dead end a stale registry value
-# does. Resolve-Path returns the canonical long form for a path that exists;
-# a path that does not exist falls back to a trimmed, lowercased comparison.
-function Normalize-Dir {
-    param([string]$Path)
-    if ([string]::IsNullOrWhiteSpace($Path)) { return "" }
-    $trimmed = $Path.TrimEnd('\', '/')
-    # GetFullPath expands an 8.3 short component (ZOLANI~1) to its long form;
-    # Resolve-Path does NOT (verified on this machine), so it cannot be relied
-    # on for that. Both are best-effort: a path that cannot be expanded falls
-    # through to the trimmed, lowercased comparison.
-    try { $trimmed = [System.IO.Path]::GetFullPath($trimmed).TrimEnd('\', '/') } catch { }
-    return $trimmed.ToLowerInvariant()
-}
-
-function Resolve-CanonicalDir {
-    param(
-        [string]$Recorded,
-        [string]$Default,
-        [scriptblock]$PathExists = { param($p) Test-Path -LiteralPath $p }
-    )
-    if ([string]::IsNullOrWhiteSpace($Recorded)) {
-        return [PSCustomObject]@{ Dir = $Default; Source = "default" }
-    }
-    $trimmed = $Recorded.TrimEnd('\')
-    if (-not (& $PathExists $trimmed)) {
-        return [PSCustomObject]@{ Dir = $Default; Source = "stale-registry" }
-    }
-    return [PSCustomObject]@{ Dir = $trimmed; Source = "registry" }
-}
-
-# SAFETY (review of 8da2b2e, CRITICAL): -RecordedInstallLocation and
-# -CanonicalOverrideForTest are ordinary parameters on the SHIPPED script, so
-# they are reachable through exactly the `-File` invocation surface Inno and
-# the shortcuts use. As first written they fed the canonical decision directly,
-# which let a stray copy pass -CanonicalOverrideForTest <its own dir> and reach
-# `docker compose -p culpa down` and the culpa_pgdata prompt with NO -Force and
-# none of the -Force warnings. Proven by probe: wouldProceed:true, forced:false.
-# That is the precise scenario CR-PR5 round 2 exists to prevent, and the
-# -Probe precedent cited above does not excuse it: that one is a parameter of
-# an INTERNAL FUNCTION, reachable only by dot-sourcing, never a top-level flag.
-#
-# They are therefore honoured ONLY under -PrintPlanOnly, which cannot touch
-# docker, the data volume, the registry or any file. In a run that could do
-# something destructive they are ignored outright, so the canonical decision
-# always comes from the real registry or the real default.
-$InjectionRequested = $PSBoundParameters.ContainsKey('RecordedInstallLocation') -or
-                      -not [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)
-$InjectionHonoured = $InjectionRequested -and $PrintPlanOnly.IsPresent
-
-if ($InjectionHonoured -and $PSBoundParameters.ContainsKey('RecordedInstallLocation')) {
-    $Recorded = $RecordedInstallLocation
-} else {
-    $Recorded = (Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Name InstallLocation -ErrorAction SilentlyContinue).InstallLocation
-}
-$DefaultDir = if (-not $InjectionHonoured -or [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)) {
-    Join-Path $env:LOCALAPPDATA "Culpa"
-} else {
-    $CanonicalOverrideForTest.TrimEnd('\')
-}
-$Resolved = Resolve-CanonicalDir -Recorded $Recorded -Default $DefaultDir
-$Canonical = $Resolved.Dir
-$ComposeDst = Join-Path $AppDir "docker-compose.yml"
-
-$Matches_ = ((Normalize-Dir $AppDir) -eq (Normalize-Dir $Canonical))
-$WouldProceed = ($Matches_ -or $Force.IsPresent)
-
-if ($PrintPlanOnly) {
-    [PSCustomObject]@{
-        appDir          = $AppDir
-        canonical       = $Canonical
-        canonicalSource = $Resolved.Source
-        wouldProceed    = $WouldProceed
-        forced          = ($Force.IsPresent -and -not $Matches_)
-        # so plan output can never be mistaken for a real registry read
-        injected        = $InjectionHonoured
-    } | ConvertTo-Json -Compress
-    exit 0
-}
-
-if (-not $WouldProceed) {
-    # non-canonical copy: touch NOTHING (no docker, no volume, no files)
-    Write-Host "This copy is not the installed one - nothing was changed." -ForegroundColor Yellow
-    Write-Host "To uninstall Culpa: Windows Settings -> Installed apps -> Culpa,"
-    Write-Host "or run uninstall-culpa.ps1 in $Canonical."
-    if ($Resolved.Source -eq "stale-registry") {
-        Write-Host "(The recorded install location no longer exists, so the default was used.)"
-    }
-    # T-CF29-2: never leave the user with no way out. If the canonical
-    # directory is wrong or gone, this is the escape hatch — explicit, so it
-    # can never fire by accident on a stray copy.
-    Write-Host "If Culpa really is installed HERE, re-run with -Force:" -ForegroundColor Yellow
-    Write-Host "  powershell -ExecutionPolicy Bypass -File `"$AppDir\uninstall-culpa.ps1`" -Force"
-    if (-not $FromUninstaller) { Read-Host "Press Enter to close" }
-    exit 0
-}
-
-if ($Force.IsPresent -and -not $Matches_) {
-    Write-Host "-Force: uninstalling from $AppDir even though the recorded location is $Canonical." -ForegroundColor Yellow
-}
-
-# CF19 (CodeRabbit PR#16 #289): collector shutdown runs AFTER the
-# canonical-path guard — a stray COPY of this script must not change the real
-# installation, and stopping its collector is a change. Stopping capture is
-# otherwise always safe, so it precedes the container teardown.
-$CollectorCtl = Join-Path $AppDir "culpa-collector.ps1"
-if (Test-Path $CollectorCtl) { & $CollectorCtl -Stop }
-
-Write-Host "==> Stopping Culpa"
-# CR-PR5: judge the native exit code explicitly (SilentlyContinue does NOT
-# catch it), and NEVER infer "stopped" from a missing compose file - a prior
-# failed cleanup can leave containers running. Absent file => ask docker.
-$stackStopped = $false
-# CR-PR5 r4: check docker EXPLICITLY. SilentlyContinue swallows a missing
-# executable and leaves $LASTEXITCODE at its PRIOR value - verified on
-# Windows PowerShell 5.1: after any earlier successful native command that
-# value is 0, so the old implicit test would have read "stopped" having
-# stopped nothing, and deleted files while containers ran. Fail-closed now
-# by construction, not by the accident of call ordering.
-if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
-    Write-Host "Docker was not found on PATH - cannot confirm Culpa is stopped." -ForegroundColor Yellow
-} elseif (Test-Path $ComposeDst) {
-    docker compose -f $ComposeDst -p culpa down
-    $stackStopped = ($LASTEXITCODE -eq 0)
-} else {
-    Write-Host "No compose file here - checking for running Culpa containers directly."
-    docker compose -p culpa down
-    $stackStopped = ($LASTEXITCODE -eq 0)
-}
-if (-not $stackStopped) {
-    Write-Host "Culpa did not stop cleanly - leaving files in place so you can retry:" -ForegroundColor Yellow
-    Write-Host "  docker compose -p culpa down"
-}
-
-Write-Host "==> Removing shortcuts"
-Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa.lnk") -Force
-Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa Dashboard.url") -Force
-Remove-Item (Join-Path ([Environment]::GetFolderPath("StartMenu")) "Programs\Culpa") -Recurse -Force
-
-if (-not $FromUninstaller) {
-    $wipe = Read-Host "Also DELETE all recorded cost data? This cannot be undone. (y/N)"
-    if ($wipe -eq "y" -or $wipe -eq "Y") {
-        docker volume rm culpa_pgdata
-        Write-Host "Data volume removed."
-    } else {
-        Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
-    }
-    if ($stackStopped) {
-        $unins = Join-Path $AppDir "unins000.exe"
-        if (Test-Path $unins) {
-            # exe install: hand off so the Windows Settings entry is cleaned too
-            Start-Process $unins "/VERYSILENT"
-        } else {
-            # T-171 script install: WE own the Settings entry, so we remove it.
-            # An exe install never reaches here - Inno owns and removes its own
-            # key, and deleting it from this side would strand the wizard with
-            # a listing it can no longer clean up.
-            Remove-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Recurse -Force
-            Remove-Item $AppDir -Recurse -Force
-        }
-        Write-Host "Culpa removed."
-    } else {
-        Write-Host "Files kept because the stack is still running - stop it, then run this again."
-    }
-    Read-Host "Press Enter to close"
-} else {
-    # setup.exe's uninstaller removes the installed files itself; we only
-    # clean up what install-culpa.ps1 created at runtime - and ONLY when the
-    # stack actually stopped
-    # CR-PR5 round 3: SIGNAL the failure. Printing alone let Inno delete the
-    # scripts while containers were still running; culpa-setup.iss now runs
-    # this from InitializeUninstall and CANCELS the uninstall on a nonzero
-    # exit, so the files stay put and the retry is possible.
-    if (-not $stackStopped) {
-        Write-Host "Refusing to remove Culpa while its containers are running." -ForegroundColor Red
-        exit 1
-    }
-    Remove-Item $ComposeDst -Force
-    Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
-}
+# Culpa uninstaller for Windows (T-087, T-IX-01).
+# Stops and removes the containers and shortcuts. Your recorded data is
+# KEPT unless you answer Y to the final question.
+# -FromUninstaller: run by the setup.exe's uninstaller - no interactive
+# prompts, data always kept (never delete data without an explicit yes). Inno
+# removes the installed files and its own Add/Remove key itself, so this mode
+# only cleans the runtime compose file and refuses (exit 1) while running.
+# -Unattended: run by the npm `preuninstall` hook (D-126) - ALSO non-interactive
+# and data-always-kept, but there is NO Inno wizard to clean up after us, so this
+# mode removes the app dir and the (script-install) Add/Remove key itself.
+# Exactly one of these is set by a non-interactive caller; a human CLI run sets
+# neither and gets the prompts.
+#
+# CR-PR5 round 2 (SAFETY ORDERING): the canonical-path check now gates EVERY
+# destructive action - docker down, the data-volume prompt, and file removal.
+# A copy of this script run from anywhere else previously could stop the real
+# `culpa` project and offer to delete culpa_pgdata, the shared data volume.
+# T-CF29-2 params:
+#   -Force                      proceed from THIS directory even when the
+#                               canonical check disagrees (explicit opt-in;
+#                               never automatic)
+#   -RecordedInstallLocation    inject what the registry would return, so the
+#                               resolution can be tested without touching HKCU
+#                               (same -Probe precedent as install-culpa.ps1)
+#   -CanonicalOverrideForTest   inject the fallback directory, for the same reason
+#   -PrintPlanOnly              resolve, print the decision as JSON, exit 0
+#                               BEFORE any destructive action
+param(
+    [switch]$FromUninstaller,
+    [switch]$Force,
+    [string]$RecordedInstallLocation,
+    [string]$CanonicalOverrideForTest,
+    [switch]$PrintPlanOnly,
+    [switch]$Unattended
+)
+
+$ErrorActionPreference = "SilentlyContinue"
+$AppDir = $PSScriptRoot
+# A human CLI uninstall is the only INTERACTIVE caller: both -FromUninstaller
+# (Inno) and -Unattended (npm preuninstall hook) run without prompts. Every
+# Read-Host below is gated on this so a non-interactive caller can never block.
+$Interactive = (-not $FromUninstaller) -and (-not $Unattended)
+# CF5-F11: the install directory is the founder's choice now, so "canonical"
+# is what SETUP RECORDED, not a hardcoded path. Inno writes InstallLocation
+# into its own uninstall key; fall back to %LOCALAPPDATA%\Culpa for installs
+# made before the directory page existed, and for the zip layout.
+# The guard itself is unchanged and still load-bearing: a stray COPY of this
+# script must never stop containers or delete files belonging to the real
+# install.
+#
+# T-CF29-2: a recorded value that POINTS AT A DELETED DIRECTORY used to be
+# trusted anyway, so the guard below could never match and Culpa became
+# impossible to uninstall. That is not hypothetical — the CF20 npm gate
+# overwrote this shared value with a scratch dir which was then removed.
+# A path that does not exist cannot be shadowing a real install, so it is
+# ignored in favour of the default. Everything else about the guard stands.
+# T-CF29-2: the guard compared raw strings, so two spellings of the SAME
+# directory read as different installs — an 8.3 short path (C:\Users\ZOLANI~1)
+# versus its long form, a trailing backslash, or different casing. Each of
+# those turns the uninstaller into the same dead end a stale registry value
+# does. Resolve-Path returns the canonical long form for a path that exists;
+# a path that does not exist falls back to a trimmed, lowercased comparison.
+function Normalize-Dir {
+    param([string]$Path)
+    if ([string]::IsNullOrWhiteSpace($Path)) { return "" }
+    $trimmed = $Path.TrimEnd('\', '/')
+    # GetFullPath expands an 8.3 short component (ZOLANI~1) to its long form;
+    # Resolve-Path does NOT (verified on this machine), so it cannot be relied
+    # on for that. Both are best-effort: a path that cannot be expanded falls
+    # through to the trimmed, lowercased comparison.
+    try { $trimmed = [System.IO.Path]::GetFullPath($trimmed).TrimEnd('\', '/') } catch { }
+    return $trimmed.ToLowerInvariant()
+}
+
+function Resolve-CanonicalDir {
+    param(
+        [string]$Recorded,
+        [string]$Default,
+        [scriptblock]$PathExists = { param($p) Test-Path -LiteralPath $p }
+    )
+    if ([string]::IsNullOrWhiteSpace($Recorded)) {
+        return [PSCustomObject]@{ Dir = $Default; Source = "default" }
+    }
+    $trimmed = $Recorded.TrimEnd('\')
+    if (-not (& $PathExists $trimmed)) {
+        return [PSCustomObject]@{ Dir = $Default; Source = "stale-registry" }
+    }
+    return [PSCustomObject]@{ Dir = $trimmed; Source = "registry" }
+}
+
+# SAFETY (review of 8da2b2e, CRITICAL): -RecordedInstallLocation and
+# -CanonicalOverrideForTest are ordinary parameters on the SHIPPED script, so
+# they are reachable through exactly the `-File` invocation surface Inno and
+# the shortcuts use. As first written they fed the canonical decision directly,
+# which let a stray copy pass -CanonicalOverrideForTest <its own dir> and reach
+# `docker compose -p culpa down` and the culpa_pgdata prompt with NO -Force and
+# none of the -Force warnings. Proven by probe: wouldProceed:true, forced:false.
+# That is the precise scenario CR-PR5 round 2 exists to prevent, and the
+# -Probe precedent cited above does not excuse it: that one is a parameter of
+# an INTERNAL FUNCTION, reachable only by dot-sourcing, never a top-level flag.
+#
+# They are therefore honoured ONLY under -PrintPlanOnly, which cannot touch
+# docker, the data volume, the registry or any file. In a run that could do
+# something destructive they are ignored outright, so the canonical decision
+# always comes from the real registry or the real default.
+$InjectionRequested = $PSBoundParameters.ContainsKey('RecordedInstallLocation') -or
+                      -not [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)
+$InjectionHonoured = $InjectionRequested -and $PrintPlanOnly.IsPresent
+
+if ($InjectionHonoured -and $PSBoundParameters.ContainsKey('RecordedInstallLocation')) {
+    $Recorded = $RecordedInstallLocation
+} else {
+    $Recorded = (Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Name InstallLocation -ErrorAction SilentlyContinue).InstallLocation
+}
+$DefaultDir = if (-not $InjectionHonoured -or [string]::IsNullOrWhiteSpace($CanonicalOverrideForTest)) {
+    Join-Path $env:LOCALAPPDATA "Culpa"
+} else {
+    $CanonicalOverrideForTest.TrimEnd('\')
+}
+$Resolved = Resolve-CanonicalDir -Recorded $Recorded -Default $DefaultDir
+$Canonical = $Resolved.Dir
+$ComposeDst = Join-Path $AppDir "docker-compose.yml"
+
+$Matches_ = ((Normalize-Dir $AppDir) -eq (Normalize-Dir $Canonical))
+$WouldProceed = ($Matches_ -or $Force.IsPresent)
+
+if ($PrintPlanOnly) {
+    [PSCustomObject]@{
+        appDir          = $AppDir
+        canonical       = $Canonical
+        canonicalSource = $Resolved.Source
+        wouldProceed    = $WouldProceed
+        forced          = ($Force.IsPresent -and -not $Matches_)
+        # so plan output can never be mistaken for a real registry read
+        injected        = $InjectionHonoured
+    } | ConvertTo-Json -Compress
+    exit 0
+}
+
+if (-not $WouldProceed) {
+    # non-canonical copy: touch NOTHING (no docker, no volume, no files)
+    Write-Host "This copy is not the installed one - nothing was changed." -ForegroundColor Yellow
+    Write-Host "To uninstall Culpa: Windows Settings -> Installed apps -> Culpa,"
+    Write-Host "or run uninstall-culpa.ps1 in $Canonical."
+    if ($Resolved.Source -eq "stale-registry") {
+        Write-Host "(The recorded install location no longer exists, so the default was used.)"
+    }
+    # T-CF29-2: never leave the user with no way out. If the canonical
+    # directory is wrong or gone, this is the escape hatch — explicit, so it
+    # can never fire by accident on a stray copy.
+    Write-Host "If Culpa really is installed HERE, re-run with -Force:" -ForegroundColor Yellow
+    Write-Host "  powershell -ExecutionPolicy Bypass -File `"$AppDir\uninstall-culpa.ps1`" -Force"
+    if ($Interactive) { Read-Host "Press Enter to close" }
+    exit 0
+}
+
+if ($Force.IsPresent -and -not $Matches_) {
+    Write-Host "-Force: uninstalling from $AppDir even though the recorded location is $Canonical." -ForegroundColor Yellow
+}
+
+# CF19 (CodeRabbit PR#16 #289): collector shutdown runs AFTER the
+# canonical-path guard — a stray COPY of this script must not change the real
+# installation, and stopping its collector is a change. Stopping capture is
+# otherwise always safe, so it precedes the container teardown.
+$CollectorCtl = Join-Path $AppDir "culpa-collector.ps1"
+if (Test-Path $CollectorCtl) { & $CollectorCtl -Stop }
+
+Write-Host "==> Stopping Culpa"
+# CR-PR5: judge the native exit code explicitly (SilentlyContinue does NOT
+# catch it), and NEVER infer "stopped" from a missing compose file - a prior
+# failed cleanup can leave containers running. Absent file => ask docker.
+$stackStopped = $false
+# CR-PR5 r4: check docker EXPLICITLY. SilentlyContinue swallows a missing
+# executable and leaves $LASTEXITCODE at its PRIOR value - verified on
+# Windows PowerShell 5.1: after any earlier successful native command that
+# value is 0, so the old implicit test would have read "stopped" having
+# stopped nothing, and deleted files while containers ran. Fail-closed now
+# by construction, not by the accident of call ordering.
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "Docker was not found on PATH - cannot confirm Culpa is stopped." -ForegroundColor Yellow
+} elseif (Test-Path $ComposeDst) {
+    docker compose -f $ComposeDst -p culpa down
+    $stackStopped = ($LASTEXITCODE -eq 0)
+} else {
+    Write-Host "No compose file here - checking for running Culpa containers directly."
+    docker compose -p culpa down
+    $stackStopped = ($LASTEXITCODE -eq 0)
+}
+if (-not $stackStopped) {
+    Write-Host "Culpa did not stop cleanly - leaving files in place so you can retry:" -ForegroundColor Yellow
+    Write-Host "  docker compose -p culpa down"
+}
+
+Write-Host "==> Removing shortcuts"
+Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa.lnk") -Force
+Remove-Item (Join-Path ([Environment]::GetFolderPath("Desktop")) "Culpa Dashboard.url") -Force
+Remove-Item (Join-Path ([Environment]::GetFolderPath("StartMenu")) "Programs\Culpa") -Recurse -Force
+
+# The data-wipe question is the ONLY place data can be deleted, and it is
+# offered ONLY to an interactive human. Both non-interactive callers keep data.
+if ($Interactive) {
+    $wipe = Read-Host "Also DELETE all recorded cost data? This cannot be undone. (y/N)"
+    if ($wipe -eq "y" -or $wipe -eq "Y") {
+        docker volume rm culpa_pgdata
+        Write-Host "Data volume removed."
+    } else {
+        Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
+    }
+}
+
+if ($FromUninstaller) {
+    # setup.exe's uninstaller removes the installed files AND its own Add/Remove
+    # key itself; we only clean up the runtime compose file - and ONLY when the
+    # stack actually stopped.
+    # CR-PR5 round 3: SIGNAL the failure. Printing alone let Inno delete the
+    # scripts while containers were still running; culpa-setup.iss now runs
+    # this from InitializeUninstall and CANCELS the uninstall on a nonzero
+    # exit, so the files stay put and the retry is possible.
+    if (-not $stackStopped) {
+        Write-Host "Refusing to remove Culpa while its containers are running." -ForegroundColor Red
+        exit 1
+    }
+    Remove-Item $ComposeDst -Force
+    Write-Host "Data kept (volume culpa_pgdata). Reinstalling later will find it again."
+} else {
+    # An interactive CLI uninstall OR the npm preuninstall hook (-Unattended):
+    # there is NO Inno wizard to clean up after us, so WE remove the install dir
+    # and the (script-install) Add/Remove key - but ONLY when the stack stopped.
+    if (-not $stackStopped) {
+        Write-Host "Files kept because the stack is still running - stop it, then run this again."
+        # -Unattended (npm): nothing was removed, so report failure (exit 1) —
+        # lib/uninstall.mjs reads this and the hook then warns loudly; npm still
+        # removes the CLI. A human sees the message above and can retry.
+        if ($Unattended) { exit 1 }
+    } else {
+        $unins = Join-Path $AppDir "unins000.exe"
+        if (Test-Path $unins) {
+            # exe install: hand off so the Windows Settings entry is cleaned too
+            Start-Process $unins "/VERYSILENT"
+        } else {
+            # T-171 script/npm install: WE own the Settings entry, so we remove it.
+            # An exe install never reaches here - Inno owns and removes its own
+            # key, and deleting it from this side would strand the wizard with
+            # a listing it can no longer clean up.
+            Remove-Item -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1" -Recurse -Force
+            Remove-Item $AppDir -Recurse -Force
+        }
+        Write-Host "Culpa removed."
+    }
+    if ($Interactive) { Read-Host "Press Enter to close" }
+}

package/bin/getculpa.js

@@ -25,9 +25,11 @@ Usage:
   getculpa doctor          Diagnose this install
   getculpa repair          Re-stage missing/corrupt install files (no data touched)
   getculpa uninstall       Remove Culpa (data is kept unless you confirm)
-  getculpa scan            Zero-install local scan (no Docker, no network)
+  getculpa scan            Refresh the Culpa ledger (needs the running stack);
+                           --preview reads local logs offline: no Docker, no network
   getculpa connect         Print the topology-appropriate capture recipe
   getculpa update          Manage CLI launcher updates
+  getculpa <verb> --help   scan / connect / update / config: the culpa CLI's own help, under this name
   getculpa --help          Show this help
   getculpa --version       Show the getculpa package version
 `;
@@ -37,7 +39,7 @@ function printVersion() {
   console.log(pkg.version);
 }
 
-function runLauncherPassthrough(args) {
+function runLauncherPassthrough(args, env) {
   const exe = process.platform === "win32" ? ".exe" : "";
   const launcher = path.join(__dirname, "..", "vendor", `culpa-launcher${exe}`);
   if (!fs.existsSync(launcher)) {
@@ -45,7 +47,9 @@ function runLauncherPassthrough(args) {
     console.error("getculpa: run `npm rebuild getculpa` (or reinstall) to fetch it.");
     process.exit(1);
   }
-  const result = spawnSync(launcher, args, { stdio: "inherit" });
+  // T-182.8 (ISS-MAC-11): the launcher and the CLI spell their usage in
+  // the invoked name — the environment carries it (lib/dispatch.mjs)
+  const result = spawnSync(launcher, args, { stdio: "inherit", env });
   process.exit(result.status === null ? 1 : result.status);
 }
 
@@ -130,7 +134,7 @@ async function main(argv) {
   // uninstall-consent decisions now happen here, BEFORE anything is imported
   // or spawned. Passthrough verbs fall through untouched (the launcher owns
   // their help).
-  const { decideDispatch, verbHelp } = await import("../lib/dispatch.mjs");
+  const { decideDispatch, verbHelp, passthroughEnv } = await import("../lib/dispatch.mjs");
   const decision = decideDispatch(argv, {
     isTTY: process.stdin.isTTY === true && process.stdout.isTTY === true,
   });
@@ -166,7 +170,7 @@ async function main(argv) {
   // `uninstall` never reaches here — every argv shape is decided above.
   // scan / connect / update / config / anything unrecognized: the launcher
   // owns USAGE and exit-code semantics for its own surface, same as culpa.js.
-  return runLauncherPassthrough(argv);
+  return runLauncherPassthrough(argv, passthroughEnv(process.env));
 }
 
 main(process.argv.slice(2)).catch((e) => {

package/lib/dispatch.mjs

@@ -29,6 +29,13 @@ const VERB_HELP = {
     "Stop and REMOVE Culpa's containers and network. Asks for confirmation first; pass --yes to consent from a script (a non-interactive run without --yes refuses). Recorded cost data is kept unless you separately confirm deleting it.",
 };
 
+/** T-182.8 (ISS-MAC-11): the environment for a passthrough spawn — the
+ *  vendored launcher and the culpa CLI spell their usage in the invoked name
+ *  when CULPA_ARGV0 says `getculpa` (an allowlist on their side). Pure. */
+export function passthroughEnv(base) {
+  return { ...base, CULPA_ARGV0: "getculpa" };
+}
+
 /** One verb's help block, prefixed with its usage line. */
 export function verbHelp(verb) {
   const text = VERB_HELP[verb] ?? "No help recorded for this verb.";