getculpa 0.0.1 → 1.0.1

package/README.md

@@ -1,18 +1,37 @@
-# Culpa
-
-**LLM spend forensics and forecasting, local-first.**
-
-## Coming soon
-
-This package reserves the name. It prints a notice and does nothing else —
-no network calls, no files written.
-
-```bash
-npx getculpa
-```
-
-Culpa answers where your LLM spend actually went: which feature, which
-customer, which conversation — priced from a versioned price book rather than
-from provider-reported totals, with the money kept in exact decimals.
-
-More at **[getculpa.com](https://getculpa.com)**.
+# getculpa
+
+`packaging/npm-getculpa` supersedes the `installers/npm@0.0.1` name-claim
+placeholder (that package's contents are frozen; this one is the real
+package published as `getculpa` on npm).
+
+**`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.
+
+- `getculpa` / `getculpa start` — start (or resume) the Culpa stack
+- `getculpa stop` — stop the running stack (`docker compose stop`; recorded data is kept)
+- `getculpa restart` — stop, then start
+- `getculpa status` — install/docker/stack/license status (never prints key material)
+- `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 connect` — print the topology-appropriate capture recipe (`--fly` also emits a ready-to-deploy Fly.io shape)
+- `getculpa update` — manage CLI launcher updates
+
+Why two layers? The npm package installs two things: the platform's `culpa`
+launcher binary (trust level: HTTPS to one hardcoded GitHub Releases origin +
+a published SHA-256 checksum — the same trust as `npm install` itself) and
+the capture collector (same trust model; its absence only turns capture off,
+nothing else degrades). Every subsequent launcher update then flows through
+a stricter path: an Ed25519-signed release manifest verified against a key
+embedded in the launcher, staged installs with a self-test, next-launch
+activation, and `culpa update rollback`.
+
+- `culpa update --check` — check for a new version (never installs)
+- `culpa update` — download, verify, stage, self-test; activates next launch
+- `culpa update --status` / `rollback`
+- `culpa config set updates.mode <auto|notify|off>` (default: notify)
+
+The package name is `getculpa` because the `culpa` npm name is not ours; the
+installed commands are `getculpa` and `culpa`.

package/assets/culpa-collector.ps1

@@ -0,0 +1,137 @@
+# CF18 (D-088 items 4/5) - the capture collector's lifecycle on a Windows
+# host install. ONE implementation; install-culpa.ps1, launch-culpa.ps1 and
+# uninstall-culpa.ps1 each make a one-line call, so the three can never drift.
+#
+#   culpa-collector.ps1 -Start [-MailboxUrl http://127.0.0.1:4545]
+#   culpa-collector.ps1 -Stop
+#   culpa-collector.ps1 -Status
+#
+# WHY A HOST PROCESS AND NOT A COMPOSE SERVICE: collectord binds 127.0.0.1
+# ONLY, by design (D-082 privacy boundary - raw observation material crosses
+# loopback IPC and nothing else). Docker port-publishing cannot expose a
+# loopback-bound process, so a containerized collector beside the server is
+# unreachable by an app running on the host - the common case this installer
+# serves. The native binary on the host IS the loopback the app shares.
+# (Containerized apps use deploy/capture/capture-compose.yml's netns-sharing
+# sidecar instead; `culpa connect` prints which applies.)
+#
+# The token authenticates the collector to the mailbox target. Against the
+# local culpa-api it is not currently checked (capture is never gated,
+# D-031 section 7), but collectord requires one at boot and a future hosted target
+# does check it - so a real one is generated once and persisted beside the
+# install, never a hardcoded placeholder.
+
+param(
+    [switch]$Start,
+    [switch]$Stop,
+    [switch]$Status,
+    [string]$MailboxUrl = "http://127.0.0.1:4545",
+    # CodeRabbit PR#16: overridable when 4752 is taken on the host
+    [int]$Port = 4752
+)
+
+$ErrorActionPreference = "Stop"
+$AppDir = $PSScriptRoot
+$Exe = Join-Path $AppDir "culpa-collectord-win32-x64.exe"
+$RegisterMjs = Join-Path $AppDir "register.mjs"
+$PidFile = Join-Path $AppDir "collector.pid"
+$TokenFile = Join-Path $AppDir "collector-token.txt"
+$LogFile = Join-Path $AppDir "collector.log"
+
+function Get-RunningCollectorId {
+    if (-not (Test-Path $PidFile)) { return $null }
+    $savedPid = (Get-Content $PidFile -ErrorAction SilentlyContinue | Select-Object -First 1)
+    # CodeRabbit PR#16: a corrupt PID file (partial write, manual edit) used to
+    # TERMINATE the script - Get-Process's [int] binding fails under
+    # ErrorActionPreference=Stop and SilentlyContinue does not cover binding
+    # errors. Parse defensively: garbage means "not running", never a crash.
+    $parsedPid = 0
+    if (-not [int]::TryParse("$savedPid", [ref]$parsedPid) -or $parsedPid -le 0) { return $null }
+    $proc = Get-Process -Id $parsedPid -ErrorAction SilentlyContinue
+    # PID reuse guard: only claim it is ours if the image name matches
+    if ($proc -and $proc.ProcessName -like "culpa-collectord*") { return $proc.Id }
+    return $null
+}
+
+if ($Status) {
+    $running = Get-RunningCollectorId
+    if ($running) { Write-Host "collector: running (pid $running, port $Port)" }
+    else { Write-Host "collector: not running" }
+    exit 0
+}
+
+if ($Stop) {
+    $running = Get-RunningCollectorId
+    if ($running) {
+        Stop-Process -Id $running -Force -ErrorAction SilentlyContinue
+        Write-Host "collector: stopped (pid $running)"
+    } else {
+        Write-Host "collector: was not running"
+    }
+    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
+    exit 0
+}
+
+if (-not $Start) {
+    Write-Host "usage: culpa-collector.ps1 -Start [-MailboxUrl <url>] | -Stop | -Status"
+    exit 2
+}
+
+# -- Start --------------------------------------------------------------------
+if (-not (Test-Path $Exe)) {
+    # an older zip layout without the capture plane - say so, never fail the
+    # caller's install; the stack itself is unaffected
+    Write-Host "collector: $((Split-Path $Exe -Leaf)) not present in this package - skipping capture setup" -ForegroundColor Yellow
+    exit 0
+}
+
+$existing = Get-RunningCollectorId
+if ($existing) {
+    Write-Host "collector: already running (pid $existing)"
+    exit 0
+}
+
+if (-not (Test-Path $TokenFile)) {
+    # 64 hex chars from the cryptographic RNG; persisted so restarts keep the
+    # same credential (a hosted mailbox target checks it)
+    $bytes = New-Object byte[] 32
+    [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
+    ($bytes | ForEach-Object { $_.ToString("x2") }) -join "" | Set-Content $TokenFile -NoNewline
+}
+$token = Get-Content $TokenFile -Raw
+
+$env:CULPA_MAILBOX_URL = $MailboxUrl
+$env:CULPA_MAILBOX_TOKEN = $token
+$env:CULPA_COLLECTOR_PORT = "$Port"
+$proc = Start-Process -FilePath $Exe -WindowStyle Hidden -PassThru `
+    -RedirectStandardOutput $LogFile -RedirectStandardError "$LogFile.err"
+Set-Content $PidFile $proc.Id
+
+# bounded readiness wait: collectord prints "LISTENING <port>" on stdout
+$ready = $false
+for ($i = 0; $i -lt 20; $i++) {
+    Start-Sleep -Milliseconds 250
+    if ((Test-Path $LogFile) -and (Select-String -Path $LogFile -Pattern "LISTENING" -Quiet)) { $ready = $true; break }
+    if ($proc.HasExited) { break }
+}
+if (-not $ready) {
+    $detail = if (Test-Path "$LogFile.err") { Get-Content "$LogFile.err" -Raw } else { "(no log)" }
+    Write-Host "collector: failed to start - capture is OFF, everything else still works." -ForegroundColor Yellow
+    Write-Host "           $($detail.Trim())" -ForegroundColor Yellow
+    Remove-Item $PidFile -Force -ErrorAction SilentlyContinue
+    exit 0   # never fail the caller's install over capture
+}
+
+Write-Host "collector: running (pid $($proc.Id), 127.0.0.1:$Port -> $MailboxUrl)"
+Write-Host ""
+# The preload MUST be a file:// URL with forward slashes: on Windows, Node
+# parses a bare `--import=C:\...` as a URL whose scheme is `c:` and the app
+# CRASHES AT BOOT with ERR_UNSUPPORTED_ESM_URL_SCHEME. Proven live on this
+# machine during the CF18 host-path gate - this line is why the guidance
+# below is not simply $RegisterMjs.
+$RegisterUrl = "file:///" + ($RegisterMjs -replace "\\", "/")
+Write-Host "To capture a Node app on this machine, set on THAT app and restart it:" -ForegroundColor Cyan
+Write-Host "  NODE_OPTIONS=--import=$RegisterUrl"
+Write-Host "  CULPA_COLLECTOR_URL=http://127.0.0.1:$Port"
+Write-Host "(containerized app, or 2+ machines? run: culpa connect --machines <N>)"
+exit 0

package/assets/culpa-compose.yml

@@ -0,0 +1,144 @@
+# Culpa — release compose file shipped inside the installers (T-087/T-088).
+# Net effect is identical to running the stack from the repository:
+# same services, same container names, same ports, same privacy default.
+# Images are pulled from ghcr.io; a locally built/tagged image with the same
+# name is used when present, which is how these pins were verified before
+# publication.
+#
+# ── RELEASE STATE: v1.0.1 PUBLISHED AND SIGNED (2026-08-16) ─────────
+# 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
+# below resolve only against locally built images and this file must not be
+# distributed. v0.11.0 is the CF9-CF12 round (UI alignment fixes, forecast
+# uncertainty-calibration repair + kappa bound + cohort/centring explain,
+# cache coverage flags, relay-mesh W1/W2c groundwork — feature-gated out of
+# shipped binaries) on top of v0.10.0, the CF7/CF8 round (forecast P50-anchor + cache
+# counterfactual math repair, founder UI list U-1..U-8 + P-1, founder
+# palette + card "i" tooltips, native CLI auto-update Option A, QW-1..4
+# container-upgrade guards, CodeRabbit PR#13 triage) on top of v0.9.0.
+# The relay and license-server carry NO changes since v0.9.0 and keep
+# their v0.9.0 images — a version is only claimed where a real diff
+# exists. A signed tag is never rebuilt (D-072), so new contents mean a
+# new version.
+#
+# Once the state line reads PUBLISHED AND SIGNED, verify before you run:
+#   cosign verify \
+#     --certificate-identity 'info@myaigi.ai' \
+#     --certificate-oidc-issuer 'https://github.com/login/oauth' \
+#     ghcr.io/myaigidev/culpa-server:v1.0.1
+# Repeat for culpa-dashboard. Both must report VERIFIED.
+#
+# If a pull fails with an authentication or "denied" error rather than a
+# missing manifest, the package has not been made public yet — the images
+# exist. Check with:
+#   gh api user/packages/container/culpa-server --jq .visibility
+# Do NOT use `docker manifest inspect` with an emptied DOCKER_CONFIG to test
+# this: on Docker Desktop for Windows the daemon authenticates through its own
+# credential store, so that check reports a false PUBLIC.
+
+services:
+  db:
+    image: postgres:16-alpine
+    container_name: culpa-db
+    environment:
+      POSTGRES_USER: culpa
+      POSTGRES_PASSWORD: culpa
+      POSTGRES_DB: culpa
+    volumes:
+      - culpa_pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U culpa -d culpa"]
+      interval: 2s
+      timeout: 2s
+      retries: 30
+    restart: unless-stopped
+
+  server:
+    image: ghcr.io/myaigidev/culpa-server:v1.0.1
+    container_name: culpa-server
+    environment:
+      DATABASE_URL: postgres://culpa:culpa@db:5432/culpa
+      # full forensic capture is the default (A5); set metadata-only to opt out
+      # CF24-T1 (S2): the server binds 127.0.0.1 by DEFAULT
+      # (native/culpa-api/src/bind.rs — the binary the image actually runs).
+      # Inside a container that is unreachable through the published port, so
+      # containers must say 0.0.0.0 explicitly. The host-side `ports:` mapping
+      # below binds 127.0.0.1, so nothing OFF THIS MACHINE can reach it —
+      # reachable-by-design is always an operator's written choice, never a
+      # default.
+      #
+      # Say precisely what that does and does not cover (CF25, CodeRabbit
+      # PR #18): the `ports:` mapping governs HOST exposure only. Because the
+      # listener inside the container is 0.0.0.0, any other container attached
+      # to this Compose network reaches the server directly on 4545, without
+      # traversing the published port at all. That is ordinary Docker
+      # networking and it is fine for the services defined here — but adding a
+      # container to this network grants it API access, and the port mapping
+      # will not stop it.
+      CULPA_API_BIND: "0.0.0.0"
+      CULPA_PRIVACY_MODE: full
+      # T-120: the machine secret encrypting the customer key at rest lives
+      # here as a file — a VOLUME, so it survives container recreation
+      CULPA_SECRET_DIR: /var/lib/culpa
+      # T-M1/T-M2: scan the mounted host logs; live sweep every 5 minutes
+      CULPA_SCAN_HOME: /host
+      CULPA_SCAN_EVERY_MS: "300000"
+      # LAUNCH CONFIG (founder go, 2026-07-31 — D-041 enforcement flip;
+      # gating scope corrected 2026-08-03 by D-055): every customer-facing
+      # READ of the customer's own spend data requires a valid entitlement.
+      # Capture (ingest, scan, imports) and licensing lifecycle routes (claim,
+      # activation, license, checkout, billing-portal, entitlement, terms)
+      # are NEVER gated — a licensing failure must never break the
+      # customer's production traffic or block them from activating. Fail
+      # open ONLY on infrastructure failure (license server unreachable, DB
+      # blip, WASM missing), where the cached entitlement stands; an ABSENT
+      # or CANCELLED entitlement refuses. Activation: buy → claim in-app (or
+      # set CULPA_LICENSE_KEY, or paste the key in the dashboard under
+      # Account -> Plan & Billing -> Activate); the license server below is where the app
+      # syncs counts-only and refreshes the signed entitlement. Remove the
+      # license-server line and nothing ever leaves this machine — paid
+      # reads then stay degraded (that is the deal).
+      CULPA_TRUST_ENFORCE: "1"
+      CULPA_LICENSE_SERVER: https://culpa.fly.dev
+      # T-CF4-12 (Culpaflight4 #15): current model prices pull on first boot
+      # and refresh daily. This is a DOWNLOAD of the public price list —
+      # nothing about your usage goes anywhere (D-034). Remove the line and
+      # the committed snapshot + seeds keep pricing working offline.
+      CULPA_PRICING_SYNC: "1"
+    ports:
+      - "127.0.0.1:4545:4545"
+    volumes:
+      - culpa_data:/var/lib/culpa
+      # T-M3 ("+ See a cost"): the host's AI-tool session logs, READ-ONLY —
+      # this is what lets the in-dashboard scan see Claude Code/Codex history
+      # and keep it live. Only these two dirs, never the whole home.
+      # NARROW scope (review M2): only the session-log subdirs — ~/.claude
+      # also holds credentials/settings, which the container must never see
+      - ${CULPA_HOST_HOME:-${USERPROFILE:-${HOME}}}/.claude/projects:/host/.claude/projects:ro
+      - ${CULPA_HOST_HOME:-${USERPROFILE:-${HOME}}}/.codex/sessions:/host/.codex/sessions:ro
+    depends_on:
+      db:
+        condition: service_healthy
+    restart: unless-stopped
+
+  dashboard:
+    # CF14 (2026-08-12): dashboard-only bump. v0.11.1 is v0.11.0 plus the dark
+    # black-surface palette — no server, migration or API change, so the server
+    # above deliberately stays at v0.11.0 rather than being re-tagged for a
+    # release it has no diff in (D-072: never rebuild a tag that already exists).
+    image: ghcr.io/myaigidev/culpa-dashboard:v1.0.1
+    container_name: culpa-dashboard
+    environment:
+      CULPA_API_BASE: http://server:4545
+    ports:
+      - "127.0.0.1:3000:3000"
+    depends_on:
+      - server
+    restart: unless-stopped
+
+volumes:
+  culpa_pgdata:
+    name: culpa_pgdata
+  culpa_data:
+    name: culpa_data

package/assets/install-culpa.ps1

@@ -0,0 +1,310 @@
+# Culpa installer for Windows (T-087).
+# CR: Compose on Windows is brittle with backslashed bind sources - hand it a
+# forward-slashed home explicitly
+#
+# CF20-T3: -DeferStart / -NonInteractive let `getculpa` (npm) delegate to
+# this EXACT script for shortcuts + HKCU registration, without ever showing
+# a dialog, starting anything, or overwriting an existing live
+# docker-compose.yml (the live file owns the pin - QW-1; see section 3).
+# The Inno [Run] line passes neither switch, so the interactive installer's
+# own behavior is unchanged (culpa-setup.iss:60).
+param(
+    [switch]$DeferStart,
+    [switch]$NonInteractive
+)
+
+$env:CULPA_HOST_HOME = $env:USERPROFILE -replace "\\", "/"
+
+# Net effect = the CLI install: docker compose up on the release stack.
+# Non-technical flow: checks Docker Desktop, starts the stack, adds
+# shortcuts, opens the dashboard. Bounded waits everywhere; loud failures.
+
+$ErrorActionPreference = "Stop"
+
+$AppName = "Culpa"
+# CF5-F11: install where the founder chose. When this script was INSTALLED
+# (setup.exe drops it into {app} beside the compose and the uninstaller), the
+# install directory is simply where it lives. The LOCALAPPDATA default is kept
+# for the zip layout, where the script runs from a scratch folder.
+$InstalledHere = (Test-Path (Join-Path $PSScriptRoot "culpa-compose.yml")) -or
+                 (Test-Path (Join-Path $PSScriptRoot "unins000.exe"))
+$AppDir = if ($InstalledHere) { $PSScriptRoot } else { Join-Path $env:LOCALAPPDATA $AppName }
+# zip layout keeps the compose one level up; the setup.exe installs it beside us
+$ComposeSrc = Join-Path $PSScriptRoot "..\culpa-compose.yml"
+if (-not (Test-Path $ComposeSrc)) { $ComposeSrc = Join-Path $PSScriptRoot "culpa-compose.yml" }
+$ComposeDst = Join-Path $AppDir "docker-compose.yml"
+$DashboardUrl = "http://localhost:3000"
+
+function Write-Step([string]$msg) { Write-Host "==> $msg" }
+
+function Fail([string]$msg) {
+    Write-Host ""
+    Write-Host "INSTALL STOPPED: $msg" -ForegroundColor Red
+    Write-Host "Nothing was broken. Fix the item above and run the installer again."
+    # -NonInteractive (CF20-T3): never block an automated caller on a keypress.
+    if (-not $NonInteractive) { Read-Host "Press Enter to close" }
+    exit 1
+}
+
+Write-Host ""
+Write-Host "  CULPA --- local install" -ForegroundColor Cyan
+Write-Host "  Your prompts and responses never leave this machine."
+Write-Host ""
+
+# --- 1. Docker Desktop present? (CF6-9: scan, then authorize before any download) ---
+# Test-DockerInstalled takes an overridable -Probe so this exact detection can
+# be exercised with a fake "not found" result without touching a real install.
+function Test-DockerInstalled {
+    param([scriptblock]$Probe = { Get-Command docker -ErrorAction SilentlyContinue })
+    return ($null -ne (& $Probe))
+}
+
+# Real WPF dialog - not a console prompt. Names what's missing, what would be
+# downloaded, and from where; returns $false unless the user explicitly agrees.
+function Show-DockerAuthorizationModal {
+    Add-Type -AssemblyName PresentationFramework
+    $msg = "Culpa needs Docker Desktop and it was not found on this machine.`n`n" +
+        "If you authorize, Culpa will install it via winget (Windows Package Manager) " +
+        "using the official package 'Docker.DockerDesktop', or open the official " +
+        "download page at https://www.docker.com/products/docker-desktop/ if winget " +
+        "is unavailable.`n`nNothing is downloaded until you click Yes."
+    $btns = [System.Windows.MessageBoxButton]::YesNo
+    $icon = [System.Windows.MessageBoxImage]::Warning
+    $result = [System.Windows.MessageBox]::Show($msg, "Culpa - Docker Desktop required", $btns, $icon)
+    return ($result -eq [System.Windows.MessageBoxResult]::Yes)
+}
+
+# Only called after explicit authorization. Prefers winget (the user's own,
+# auditable package manager); falls back to opening the official vendor page.
+#
+# Returns WHICH path it took, not just pass/fail. Review finding: the caller used
+# to print "the official download page has been opened" for every failure, but
+# the page is only opened when winget is ABSENT. With winget present and the
+# install failing (UAC declined, no network, a transient winget error) the user
+# was sent to look for a browser tab that was never opened — during exactly the
+# moment this flow exists to make trustworthy.
+#   "installed"   - winget reported success
+#   "page-opened" - no winget; the vendor page was opened instead
+#   "failed:<n>"  - winget ran and exited <n>; nothing else was opened
+function Install-DockerDesktop {
+    $winget = Get-Command winget -ErrorAction SilentlyContinue
+    if ($null -eq $winget) {
+        Start-Process "https://www.docker.com/products/docker-desktop/"
+        return "page-opened"
+    }
+    Write-Step "Installing Docker Desktop via winget (Docker.DockerDesktop)"
+    $wingetArgs = @("install", "--id", "Docker.DockerDesktop", "-e", "--accept-package-agreements", "--accept-source-agreements")
+    $p = Start-Process -FilePath "winget" -ArgumentList $wingetArgs -Wait -PassThru -NoNewWindow
+    if ($p.ExitCode -eq 0) { return "installed" }
+    return "failed:$($p.ExitCode)"
+}
+
+Write-Step "Checking Docker Desktop"
+if (-not (Test-DockerInstalled)) {
+    if ($NonInteractive -and $DeferStart) {
+        # CF20-T3: no dialog, no winget without a TTY consent - refuse and
+        # instruct instead, then let the rest of provisioning proceed. Only
+        # safe with -DeferStart: provisioning never reaches the engine check
+        # below. Without -DeferStart, "continue" would walk straight into
+        # Test-DockerEngine with no `docker` binary on PATH - fail here
+        # instead (CF20-R review).
+        Write-Host "Docker Desktop was not found. Culpa is installed but needs Docker Desktop to run." -ForegroundColor Yellow
+        Write-Host "Install it from https://www.docker.com/products/docker-desktop/, then run 'getculpa' (or this installer) again."
+    } elseif ($NonInteractive) {
+        Fail "Docker Desktop was not found. Install it from https://www.docker.com/products/docker-desktop/, then run this installer again."
+    } else {
+        if (-not (Show-DockerAuthorizationModal)) {
+            Fail "Docker Desktop download was not authorized. Nothing was changed. Install Docker Desktop yourself, then run this installer again."
+        }
+        $outcome = Install-DockerDesktop
+        if ($outcome -eq "page-opened") {
+            Fail "winget is not available, so Docker Desktop could not be installed automatically. The official download page has been opened - install it, start it once, then run this installer again."
+        }
+        if ($outcome -ne "installed") {
+            $code = $outcome -replace "^failed:", ""
+            Fail "winget could not install Docker Desktop (exit code $code). No download page was opened and nothing was changed. Install Docker Desktop from https://www.docker.com/products/docker-desktop/, start it once, then run this installer again."
+        }
+        Fail "Docker Desktop was installed. Close this window, open a NEW PowerShell window (so PATH picks it up), then run this installer again to finish setup."
+    }
+}
+
+# --- 2. Docker engine running? (start it if not, wait up to 3 minutes) ---
+function Test-DockerEngine {
+    # docker prints warnings to stderr even when healthy; merge streams so
+    # strict error mode never mistakes a warning for a dead engine.
+    $old = $ErrorActionPreference
+    $ErrorActionPreference = "Continue"
+    try {
+        $null = docker info --format "ok" 2>&1
+        return ($LASTEXITCODE -eq 0)
+    } finally {
+        $ErrorActionPreference = $old
+    }
+}
+
+# -DeferStart (CF20-T3): provisioning-only, never starts the engine - that
+# is getculpa's / launch-culpa.ps1's job at actual start time.
+if (-not $DeferStart) {
+    $engineUp = Test-DockerEngine
+    if (-not $engineUp) {
+        Write-Step "Starting Docker Desktop (this can take a minute)"
+        $desktop = Join-Path $env:ProgramFiles "Docker\Docker\Docker Desktop.exe"
+        if (Test-Path $desktop) { Start-Process $desktop } else { Fail "Docker Desktop is installed but could not be started automatically. Start it yourself, then run this installer again." }
+        for ($i = 0; $i -lt 36; $i++) {
+            Start-Sleep -Seconds 5
+            if (Test-DockerEngine) { $engineUp = $true; break }
+        }
+        if (-not $engineUp) { Fail "Docker Desktop did not become ready within 3 minutes. Wait for its whale icon to settle, then run this installer again." }
+    }
+}
+
+# --- 3. Install files (always - -DeferStart still performs dir/compose) ---
+Write-Step "Installing to $AppDir"
+New-Item -ItemType Directory -Force -Path $AppDir | Out-Null
+# CF20-T3 review (Critical): under -DeferStart an EXISTING live compose is
+# never overwritten. The live file owns the pin (QW-1); version deltas are
+# reconciled by launch-culpa.ps1 at next start, where QW-3 can refuse a
+# downgrade and QW-4 takes a backup first. A blind copy here would silently
+# re-pin (or downgrade) a customer's stack on every npm reinstall/update with
+# no refusal, no backup, and no trace. The interactive installer path (no
+# -DeferStart) keeps its historical refresh behavior unchanged.
+if ($DeferStart -and (Test-Path $ComposeDst)) {
+    Write-Step "Existing live docker-compose.yml preserved (version reconciliation happens at next launch)"
+} else {
+    Copy-Item $ComposeSrc $ComposeDst -Force
+}
+
+# --- 4/5. Start the stack + wait for the dashboard (skipped under -DeferStart) ---
+if (-not $DeferStart) {
+    Write-Step "Starting Culpa (docker compose up -d)"
+    # Culpa's images are PRIVATE during the testing phase, so an unauthenticated
+    # machine dies at the pull with a bare "denied" that means nothing to a
+    # founder. Capture the output and name that case explicitly.
+    # EAP note (Culpaflight #2 lesson): native stderr under Stop kills compose
+    # progress - drop to Continue for the call and judge the exit code instead.
+    $composeOutput = ""
+    $oldEap = $ErrorActionPreference
+    $ErrorActionPreference = "Continue"
+    try {
+        $composeOutput = (docker compose -f $ComposeDst -p culpa up -d 2>&1 | Out-String)
+    } finally {
+        $ErrorActionPreference = $oldEap
+    }
+    Write-Host $composeOutput
+    if ($LASTEXITCODE -ne 0) {
+        if ($composeOutput -match "denied|unauthorized|403|authentication required") {
+            Fail @"
+Culpa's images are private while it is in testing, and this machine is not signed in to the registry.
+
+One-time fix:
+  1. Create a GitHub token with ONLY the 'read:packages' scope:
+     https://github.com/settings/tokens/new?scopes=read:packages
+  2. Sign in (paste the token when it asks for a password):
+     docker login ghcr.io -u YOUR_GITHUB_USERNAME
+  3. Run this installer again.
+
+Nothing was changed on this machine.
+"@
+        }
+        Fail "Docker could not start the Culpa services. The message above says why (most often: no internet to pull images, or ports 3000/4545 already in use)."
+    }
+
+    Write-Step "Waiting for the dashboard to come up"
+    $ready = $false
+    for ($i = 0; $i -lt 24; $i++) {
+        Start-Sleep -Seconds 5
+        try {
+            $resp = Invoke-WebRequest -Uri $DashboardUrl -UseBasicParsing -TimeoutSec 5
+            if ($resp.StatusCode -eq 200) { $ready = $true; break }
+        } catch {}
+    }
+    if (-not $ready) { Fail "The services started but the dashboard did not answer within 2 minutes. Run 'docker logs culpa-server' and 'docker logs culpa-dashboard' to see why." }
+}
+
+# --- 6. Shortcuts (Desktop + Start Menu) ---
+# Culpaflight #2: shortcuts run the LAUNCHER, not a bare URL — a .url dead-ends
+# at "connection refused" whenever Docker Desktop is off; the launcher starts
+# Docker (bounded wait), brings the stack up, THEN opens the dashboard.
+Write-Step "Creating shortcuts"
+# setup.exe already installed the scripts into $AppDir — copying a file onto
+# itself is an error under Stop, so only copy from the zip layout
+if ($PSScriptRoot -ne $AppDir) { Copy-Item (Join-Path $PSScriptRoot "launch-culpa.ps1") (Join-Path $AppDir "launch-culpa.ps1") -Force }
+$launcher = Join-Path $AppDir "launch-culpa.ps1"
+$shell = New-Object -ComObject WScript.Shell
+foreach ($dir in @([Environment]::GetFolderPath("Desktop"), (Join-Path ([Environment]::GetFolderPath("StartMenu")) "Programs\Culpa"))) {
+    New-Item -ItemType Directory -Force -Path $dir | Out-Null
+    $lnk = $shell.CreateShortcut((Join-Path $dir "Culpa.lnk"))
+    $lnk.TargetPath = "powershell.exe"
+    $lnk.Arguments = "-NoProfile -ExecutionPolicy Bypass -File `"$launcher`""
+    $lnk.WorkingDirectory = $AppDir
+    $lnk.Description = "Culpa - LLM spend forensics (starts Docker if needed)"
+    $lnk.Save()
+    # the old bare-URL shortcut from earlier installs is superseded
+    Remove-Item -Path (Join-Path $dir "Culpa Dashboard.url") -ErrorAction SilentlyContinue
+}
+if ($PSScriptRoot -ne $AppDir) { Copy-Item (Join-Path $PSScriptRoot "uninstall-culpa.ps1") (Join-Path $AppDir "uninstall-culpa.ps1") -Force }
+
+# --- 7. Register in Add/Remove Programs (T-171) ---
+# This path wrote NO registry key at all, so a machine installed by the script
+# (or by the documented CLI/compose route) never appeared in Windows Settings
+# -> Installed apps - even though installers/README.md names that as THE
+# uninstall route. setup.exe installs are already listed, because Inno writes
+# its own key; a second key would show two Culpas whose uninstallers each
+# delete the other's files. The wizard's own uninstaller is the signal to skip.
+$UninsExe = Join-Path $AppDir "unins000.exe"
+if (Test-Path $UninsExe) {
+    Write-Step "Add/Remove Programs entry belongs to the installer - not adding a second"
+} else {
+    Write-Step "Registering in Add/Remove Programs"
+    # the SAME key name Inno uses ({AppId}_is1), so the two paths can never
+    # both be listed: a later exe install overwrites this entry instead of
+    # racing it, and its uninstaller then removes the only one there is
+    $ArpKey = "HKCU:\Software\Microsoft\Windows\CurrentVersion\Uninstall\{B7A6F2C4-9D31-4E5A-A0C8-52C1E7D94F60}_is1"
+    # the version is the PINNED image tag in the compose just installed - the
+    # release this machine actually runs. A literal here would drift at every
+    # release and then report the wrong version forever, silently.
+    $installedVersion = "unknown"
+    $composeText = Get-Content $ComposeDst -Raw
+    if ($composeText -match 'culpa-server:([^"\s]+)') { $installedVersion = $Matches[1] }
+    $uninstaller = Join-Path $AppDir "uninstall-culpa.ps1"
+    $psRun = "powershell.exe -NoProfile -ExecutionPolicy Bypass -File `"$uninstaller`""
+    New-Item -Path $ArpKey -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "DisplayName" -Value "Culpa - LLM spend forensics" -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "DisplayVersion" -Value $installedVersion -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "Publisher" -Value "Myaigi" -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "InstallLocation" -Value $AppDir -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "UninstallString" -Value $psRun -PropertyType String -Force | Out-Null
+    # what Settings runs for its unattended path. -FromUninstaller is the
+    # branch that ALWAYS keeps the data volume, so a click in Settings can
+    # never silently destroy recorded spend.
+    New-ItemProperty -Path $ArpKey -Name "QuietUninstallString" -Value "$psRun -FromUninstaller" -PropertyType String -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "NoModify" -Value 1 -PropertyType DWord -Force | Out-Null
+    New-ItemProperty -Path $ArpKey -Name "NoRepair" -Value 1 -PropertyType DWord -Force | Out-Null
+}
+
+# --- 7b. Start the capture collector (CF18, D-088 items 4/5; skipped under -DeferStart) ---
+# The capture plane wires itself: no hand-assembly. Never fails the install —
+# the helper degrades to "capture OFF, everything else works" loudly.
+if (-not $DeferStart) {
+    $CollectorCtl = Join-Path $PSScriptRoot "culpa-collector.ps1"
+    if (Test-Path $CollectorCtl) {
+        Write-Step "Starting the capture collector"
+        & $CollectorCtl -Start
+    } else {
+        Write-Step "Capture collector not in this package - skipping (zip layout pre-CF18)"
+    }
+}
+
+# --- 8. Open it (skipped under -DeferStart: provisioning leaves Culpa dormant) ---
+if ($DeferStart) {
+    Write-Step "Done. Culpa is installed but not started (deferred)."
+    Write-Host ""
+    Write-Host "Culpa is installed. Run 'getculpa' (or launch-culpa.ps1 in $AppDir) to start it." -ForegroundColor Green
+} else {
+    Write-Step "Done. Opening the dashboard."
+    Start-Process $DashboardUrl
+    Write-Host ""
+    Write-Host "Culpa is running. It starts again automatically when Docker Desktop starts." -ForegroundColor Green
+}
+Write-Host "To remove it later: run uninstall-culpa.ps1 in $AppDir"
+if (-not $NonInteractive) { Read-Host "Press Enter to close" }