@liustack/modlens 3.0.0 → 3.1.0

package/skills/modlens/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: modlens
 description: "Plug-in vision for text-only models. Use whenever the user shares an image (local path, screenshot, photo, chart, document scan, or image URL) and the active model cannot see images or has no vision tool. Runs the modlens CLI to convert the image into structured JSON evidence: every word transcribed, layout regions, semantics, visual clues. Also use when the user asks how to install, configure, or switch modlens providers (Gemini API key, OpenAI-compatible endpoints, Claude API or Claude Code CLI)."
-allowed-tools:
-  - Bash
+compatibility: Requires network access and one of node 22+/npx, bun/bunx, or a preinstalled modlens binary on PATH.
+allowed-tools: Bash
 ---
 
 # ModLens — Vision Bridge Skill
@@ -21,13 +21,28 @@ Do not use this skill for:
 
 ## Prerequisites
 
+Run every modlens command through the launcher bundled with this skill.
+Replace `<skill-dir>` with the directory this SKILL.md lives in:
+
 ```bash
-modlens --version
+bash <skill-dir>/scripts/run.sh -i <image-path-or-url>                              # macOS / Linux
+powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 -i <image>     # Windows
 ```
 
-If `modlens` is missing, run it via `npx @liustack/modlens` instead.
+The launcher finds a working way to run modlens and forwards your arguments to it unchanged. It tries, in order: a compatible `modlens` already on `PATH`, then `npx`, then `bunx`. If none of those exists it prints a JSON diagnosis to stderr and exits 78, with a `nextSteps` list for the user. Relay those steps instead of retrying. To see the full diagnosis, run `bash <skill-dir>/scripts/run.sh doctor --json` (on a machine that can launch the CLI it also chains modlens's own provider/config `doctor`).
+
+### If you cannot run the launcher script
+
+Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.0.0):
 
-ModLens supports five vision providers. Check what is configured:
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.0.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.0.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.0.0 <args>`.
+4. Otherwise none of these runtimes is here. Tell the user no JavaScript runtime was found and that installing Node 22.13+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
+
+`references/runtime.md` documents the version pin, the compatibility rule, and the diagnostic fields.
+
+ModLens supports five vision providers. Check what is configured (through the launcher, as above):
 
 ```bash
 modlens config show
@@ -43,12 +58,12 @@ modlens config show
 
 ## Command
 
+In the examples below, `modlens` means the command run through the launcher above (`bash <skill-dir>/scripts/run.sh ...`, or the PowerShell form on Windows).
+
 ```bash
 modlens -i <image-path-or-url>
 # pick a provider explicitly
 modlens -i <image> -p gemini-api
-# or without a global install
-npx @liustack/modlens -i <image-path-or-url>
 ```
 
 Optional flags:
@@ -101,7 +116,7 @@ Structure is enforced by schema on antigravity-cli and claude-cli (`--json-schem
 
 ## Failure Handling
 
-Every error this CLI prints is catalogued with its cause and fix in the project's `docs/troubleshooting.md`. Read the message first: most of them already name the fix.
+Every error this CLI prints names its cause, and most already name the fix, so read the message first.
 
 - `Provider CLI not found`: Antigravity CLI is not installed. Install it, or switch provider: `-p gemini-api`.
 - Missing key errors name the exact env var and `config set` command to run. Relay that to the user.

package/skills/modlens/references/cli.md

@@ -0,0 +1,77 @@
+# ModLens CLI manual
+
+The skill drives this CLI through its launcher. This page is for running it directly.
+
+## Direct usage
+
+With the skill installed you do not type commands: paste an image or drop a path, ask anything, and it fires on its own. By hand:
+
+```bash
+modlens -i screenshot.png                       # local image
+modlens -i https://example.com/chart.png        # remote image
+modlens -i chart.png --prompt "focus on axes"   # extra focus
+modlens recover-paste                           # pull a pasted image into a file
+```
+
+Output is a fixed JSON shape:
+
+```json
+{
+  "image": "/path/to/screenshot.png",
+  "provider": "gemini-api",
+  "result": {
+    "summary": "A workflow diagram with four nodes connected by labeled arrows.",
+    "ocr": { "full_text": "/shaping\nBEFORE YOU BUILD\n...", "lines": [] },
+    "layout": { "regions": [{ "reading_order": 1, "type": "title", "text": "/shaping" }] },
+    "uncertainty": []
+  },
+  "meta": {
+    "generatedAt": "2026-08-06T12:00:00.000Z",
+    "model": "gemini-3.6-flash",
+    "conversationId": null,
+    "durationSeconds": 6.4,
+    "usage": { "promptTokenCount": 1234, "candidatesTokenCount": 567 }
+  }
+}
+```
+
+`meta` records how the result was produced: when (`generatedAt`), which `model`, the provider's `conversationId` when it has one, wall-clock `durationSeconds`, and the raw `usage` the provider reported (shape varies by provider, `null` when none).
+
+## Flags
+
+`modlens analyze` (the default command):
+
+| Flag | Meaning | Default |
+| :-- | :-- | :-- |
+| `-i, --input <path\|url>` | Image to analyze (required) | |
+| `-p, --provider <name>` | Vision provider | `antigravity-cli` |
+| `-m, --model <name>` | Provider model | per provider (below) |
+| `-o, --output <path>` | Also write JSON to a file | |
+| `--prompt <text>` | Extra focus | |
+| `--timeout <ms>` | Provider timeout | `180000` |
+| `--provider-bin <path>` | Provider binary path | `agy` / `claude` |
+| `--workdir <path>` | Working directory for the provider | a fresh isolated directory per run |
+
+The default `-m` model depends on the provider:
+
+| Provider | Default model |
+| :-- | :-- |
+| `antigravity-cli` (default) | `gemini-3.6-flash-low` |
+| `gemini-api` | `gemini-3.6-flash` |
+| `anthropic` | `claude-haiku-4-5-20251001` |
+| `claude-cli` | `haiku` |
+| `openai` | none, `-m` is required |
+
+`modlens recover-paste`:
+
+| Flag | Meaning | Default |
+| :-- | :-- | :-- |
+| `--count <n>` | How many recent pasted images to recover | `1` |
+| `--out-dir <path>` | Where to write recovered images | a fresh private `<tmpdir>/modlens-paste-*` per run |
+| `--session <id>` | Session id for exact targeting | auto-detect |
+| `--transcript <path>` | Explicit transcript `.jsonl` or `.db` (overrides `--session`) | |
+| `--harness <name>` | Force storage scope: `claude-code`, `pi`, `opencode`, `none` | auto-detect |
+| `--cwd <path>` | Project directory the image was pasted in | current directory |
+
+Five providers: `antigravity-cli` (default, no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (uses your existing Claude subscription). Two more subcommands: `modlens config <init|set|show>`, and `modlens doctor` (checks Node, provider readiness, which provider will be selected and why, and the detected harness, without spending quota or touching the network. Add `--json` for a machine-readable report).
+

package/skills/modlens/references/configure.md

@@ -15,6 +15,40 @@ modlens config set <provider>.<field> <value>   # fields: apiKey, baseUrl, model
 
 `config set` writes the file with 0600 permissions.
 
+## The file's exact shape
+
+Everything lives under two top-level keys, both optional. A missing file means all defaults. Provider settings sit under `providers.<name>`, not at the top level, which is the mistake hand-editors make most.
+
+```json
+{
+  "provider": "gemini-api",
+  "providers": {
+    "antigravity-cli": { "model": "gemini-3.6-flash-low" },
+    "gemini-api": {
+      "apiKey": "AIza...",
+      "baseUrl": "https://generativelanguage.googleapis.com",
+      "model": "gemini-3.6-flash"
+    },
+    "openai": {
+      "apiKey": "sk-...",
+      "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      "model": "qwen3.6-27b"
+    },
+    "anthropic": { "apiKey": "sk-ant-..." },
+    "claude-cli": { "model": "haiku" }
+  }
+}
+```
+
+Field semantics:
+
+- `provider`: which provider runs when `-p` is not given. Canonical names or aliases both work (`agy`/`antigravity` for `antigravity-cli`, `gemini` for `gemini-api`, `openai-compat` for `openai`, `claude` for `anthropic`, `claude-code` for `claude-cli`). Empty or absent means `antigravity-cli`.
+- `providers.<name>.<field>`: only three fields exist, `apiKey`, `baseUrl`, `model`. Every provider entry is optional, and every field inside it is optional. Alias keys are read too (settings saved under `gemini` are found when `gemini-api` resolves), with the canonical key winning on conflict.
+- Environment variables override the file for these bindings: `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`. Nothing else is read from the environment except `MODLENS_HARNESS` (paste-recovery scope, unrelated to this file).
+- Unknown top-level keys and unknown provider names are ignored rather than rejected, so a typo fails quiet: run `modlens doctor` after hand-editing, it shows which file and env values are actually in effect.
+
+Hand-editing is fine (keep the file valid JSON and its permissions 0600). `modlens config set` does the same thing with guardrails.
+
 ## Provider setup recipes
 
 ### antigravity-cli (default, free, no key)

package/skills/modlens/references/runtime.md

@@ -0,0 +1,95 @@
+# modlens runtime reference
+
+How the skill launches the `modlens` CLI, what version it pins, and how it
+diagnoses a machine where nothing can run. The launchers `scripts/run.sh`
+(macOS / Linux) and `scripts/run.ps1` (Windows) implement everything below and
+must stay byte-for-byte identical apart from their version constants and their
+shell syntax.
+
+## Pinned version
+
+- Pinned CLI version: 3.1.0
+- npm package: `@liustack/modlens`
+- CLI binary name: `modlens`
+
+The pinned version line above and the constants inside both launchers are
+stamped by `scripts/release.mjs` at release time from `package.json`. Do not
+edit them by hand. `scripts/stamp.test.mjs` fails the build if the three
+launcher/reference copies ever drift from `package.json`.
+
+## Resolution order
+
+Each call resolves a way to run the CLI, in this order:
+
+1. **A compatible `modlens` already on `PATH`** — run it directly, by name.
+2. **`npx` present** — `npx --yes --package @liustack/modlens@<pinned> modlens <args>`.
+3. **`bunx` present** — `bunx --bun @liustack/modlens@<pinned> <args>`.
+4. **A native artifact** — reserved for phase B. None is published yet, so this
+   branch reports `nativeArtifact.available: false` and moves on.
+5. **Nothing usable** — print a structured diagnosis and exit `78` (`EX_CONFIG`).
+
+The launcher forwards stdin, stdout, stderr, and the exit code unchanged, so the
+CLI's JSON output contract is identical however it was launched.
+
+## Compatibility rule
+
+A `modlens` found on `PATH` counts as compatible only when it is **the same
+major version as the pinned version and not older than it**. Same major keeps a
+user who already installed a matching CLI from being forced through an `npx`
+re-download (the "no regression" requirement in the design). Not-older refuses a
+stale global build that predates the version this skill was written against; in
+that case the launcher skips `PATH` and uses the pinned `npx` / `bunx` version
+instead.
+
+## Cache and permissions (phase B, not active yet)
+
+Phase A never downloads anything. When native artifacts land in phase B, the
+launchers will cache them per user, keyed by version, and launch them by
+absolute path:
+
+- macOS: `~/Library/Caches/liustack/modlens/<version>/`
+- Linux: `${XDG_CACHE_HOME:-$HOME/.cache}/liustack/modlens/<version>/`
+- Windows: `%LOCALAPPDATA%\liustack\modlens\<version>\`
+
+With these constraints: no `sudo` or admin rights, no system directories, no
+`PATH` edits, download to a temp file and verify SHA-256 before an atomic move,
+and keep no unverified executable on failure. Any download uses `curl` (on
+Windows, `curl.exe` written in full), which does not stamp quarantine or
+Mark-of-the-Web, and the launcher never removes a security marker a browser
+would have set.
+
+## Diagnostic fields
+
+`run.sh doctor --json` (and `run.ps1 doctor --json`) print this shape:
+
+- `tool`, `package`, `pinnedVersion` — what this skill targets.
+- `os`, `arch` — normalized host identity (`darwin` / `linux` / `windows`,
+  `arm64` / `x64`).
+- `checked.pathCli` — `{ present, path, version, compatible }` for a `modlens`
+  on `PATH`, with `compatible` applying the rule above.
+- `checked.npx`, `checked.bunx` — `{ present, path }` visibility of each runner.
+- `checked.node` — `{ present, version }`.
+- `nativeArtifact` — `{ available, note }`; `available` is `false` in phase A.
+- `selected` — the resolved path: `path`, `npx`, `bunx`, or `none`.
+- `nextSteps` — when `selected` is `none`, one or two plain-language actions for
+  the user (install Node 22.13+, or Bun); empty otherwise.
+- `cliDoctor` — when a CLI is resolvable, the CLI's own `doctor --json` report
+  (provider, config, and harness diagnosis) is nested here; `null` otherwise.
+
+`doctor` is offline and spends no quota: it inspects the local environment and,
+when it can, chains the CLI's own offline `doctor`. It makes no network request
+of its own.
+
+## Delivery form: local CLI, long term
+
+modlens stays a local CLI on purpose, and section 10 of the distribution design
+(move capabilities to a remote MCP when they need no local execution) does
+**not** apply to it. The reasons are the product itself: the vision-provider key
+is held on the user's machine, the quota billed is the user's own, and there is
+no central service in the middle. modlens also reads local files directly. Its
+`recover-paste` pulls pasted images out of the harness's own session storage on
+disk, which a remote service structurally cannot reach. A hosted MCP would move
+the key and the quota off the user's machine and still could not see those local
+files, which is the opposite of what this tool is for. Phase D may retire native
+artifacts for some future tool, but modlens keeps its local-CLI form for as long
+as those properties hold.

package/skills/modlens/scripts/run.ps1

@@ -0,0 +1,250 @@
+# modlens skill launcher (Windows, PowerShell 5.1 compatible).
+#
+# The Windows twin of run.sh: identical resolution order, identical diagnostic
+# fields, identical exit codes. One stable action for the agent ("run
+# modlens"); this script picks a working way to run it here.
+#
+# Invoke it per-process so no global policy is touched:
+#   powershell -ExecutionPolicy Bypass -File run.ps1 -q "test"
+#
+# Resolution order (kept identical in run.sh):
+#   1. A compatible modlens already on PATH  -> run it directly.
+#   2. npx present                             -> run the pinned npm version.
+#   3. bunx present                            -> run the pinned version via Bun.
+#   4. (phase B placeholder) a native artifact -> not published yet.
+#   5. Nothing usable                          -> structured diagnosis, exit 78.
+#
+# It never writes PATH, never needs admin rights, never fetches a second script,
+# and has no postinstall step.
+
+$ErrorActionPreference = 'Stop'
+
+# --- Version constants: stamped by scripts/release.mjs at release time. --------
+# Do not edit $Pinned by hand; scripts/stamp.test.mjs asserts it equals the
+# package.json version, and the release script rewrites it on every bump.
+$Package = '@liustack/modlens'
+$Bin = 'modlens'
+$Pinned = '3.1.0'
+# -------------------------------------------------------------------------------
+
+$NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'
+
+# Environment snapshot, filled by Collect and read by the emitters.
+$script:Arch = ''
+$script:CliPresent = $false
+$script:CliPath = $null
+$script:CliVer = $null
+$script:CliCompat = $false
+$script:NpxPresent = $false
+$script:NpxPath = $null
+$script:BunxPresent = $false
+$script:BunxPath = $null
+$script:NodePresent = $false
+$script:NodeVer = $null
+$script:Selected = 'none'
+
+# First "X.Y.Z" token printed by `$Bin --version`.
+function Get-CliVersion {
+    try { $out = & $Bin --version 2>$null } catch { return '' }
+    if (-not $out) { return '' }
+    $line = [string]($out | Select-Object -First 1)
+    $m = [regex]::Match($line, '[0-9]+\.[0-9]+\.[0-9]+')
+    if ($m.Success) { return $m.Value } else { return '' }
+}
+
+# Compatible = same major version as $Pinned AND not older than $Pinned.
+# Same major keeps a globally installed CLI usable without a forced re-download;
+# not-older refuses a stale build that predates the version this skill needs.
+function Test-Compatible {
+    param([string] $Ver)
+    $f = $Ver -split '\.'
+    $p = $Pinned -split '\.'
+    if ($f.Count -lt 3 -or $p.Count -lt 3) { return $false }
+    $fMaj = [int]$f[0]; $fMin = [int]$f[1]; $fPat = [int]$f[2]
+    $pMaj = [int]$p[0]; $pMin = [int]$p[1]; $pPat = [int]$p[2]
+    if ($fMaj -ne $pMaj) { return $false }
+    if ($fMin -gt $pMin) { return $true }
+    if ($fMin -lt $pMin) { return $false }
+    return ($fPat -ge $pPat)
+}
+
+# Return exactly one word: the chosen launch path.
+function Resolve-LaunchKind {
+    $cli = Get-Command $Bin -ErrorAction SilentlyContinue
+    if ($cli) {
+        $v = Get-CliVersion
+        if ($v -and (Test-Compatible $v)) { return 'path' }
+    }
+    if (Get-Command npx -ErrorAction SilentlyContinue) { return 'npx' }
+    if (Get-Command bunx -ErrorAction SilentlyContinue) { return 'bunx' }
+    # Phase B goes here: check a versioned user cache, then download and verify a
+    # native artifact into it. Any such download must use curl.exe (written in
+    # full so PowerShell 5.1 does not resolve `curl` to its Invoke-WebRequest
+    # alias), never Invoke-WebRequest, which stamps Mark-of-the-Web; see
+    # design.md 8.3.
+    return 'none'
+}
+
+# Run the resolved CLI and return its output (used to chain the CLI's own
+# doctor). Passes every argument through untouched.
+function Invoke-Cli {
+    param([string[]] $CliArgs)
+    switch ($script:Selected) {
+        'path' { & $Bin @CliArgs }
+        'npx' { & npx --yes --package "$Package@$Pinned" $Bin @CliArgs }
+        'bunx' { & bunx --bun "$Package@$Pinned" @CliArgs }
+    }
+}
+
+function Get-Arch {
+    switch ($env:PROCESSOR_ARCHITECTURE) {
+        'AMD64' { return 'x64' }
+        'ARM64' { return 'arm64' }
+        'x86' { return 'x86' }
+        default { return $env:PROCESSOR_ARCHITECTURE }
+    }
+}
+
+# Probe the environment once into the $script:* snapshot.
+function Collect {
+    $script:Arch = Get-Arch
+
+    $cli = Get-Command $Bin -ErrorAction SilentlyContinue
+    if ($cli) {
+        $script:CliPresent = $true
+        $script:CliPath = $cli.Source
+        $script:CliVer = Get-CliVersion
+        $script:CliCompat = [bool]($script:CliVer -and (Test-Compatible $script:CliVer))
+    }
+
+    $npx = Get-Command npx -ErrorAction SilentlyContinue
+    if ($npx) { $script:NpxPresent = $true; $script:NpxPath = $npx.Source }
+
+    $bunx = Get-Command bunx -ErrorAction SilentlyContinue
+    if ($bunx) { $script:BunxPresent = $true; $script:BunxPath = $bunx.Source }
+
+    $node = Get-Command node -ErrorAction SilentlyContinue
+    if ($node) {
+        $script:NodePresent = $true
+        try { $script:NodeVer = ((& node --version 2>$null) -replace '^v', '') } catch { $script:NodeVer = $null }
+    }
+
+    $script:Selected = Resolve-LaunchKind
+}
+
+# Assemble the structured diagnosis. $Chained, when a parsed object, becomes
+# cliDoctor; otherwise cliDoctor is null.
+function Build-DiagnosisJson {
+    param($Chained)
+    $checked = [ordered]@{
+        pathCli = [ordered]@{ present = $script:CliPresent; path = $script:CliPath; version = $script:CliVer; compatible = $script:CliCompat }
+        npx     = [ordered]@{ present = $script:NpxPresent; path = $script:NpxPath }
+        bunx    = [ordered]@{ present = $script:BunxPresent; path = $script:BunxPath }
+        node    = [ordered]@{ present = $script:NodePresent; version = $script:NodeVer }
+    }
+    $steps = @()
+    if ($script:Selected -eq 'none') {
+        $major = $Pinned.Split('.')[0]
+        $steps = @(
+            "Install Node 22.13+ from https://nodejs.org so npx can run $Package@$Pinned, then re-run this launcher.",
+            "No JavaScript runtime? Install Bun from https://bun.sh to use bunx, or put a compatible $Bin (major $major, at or above $Pinned) on PATH."
+        )
+    }
+    $obj = [ordered]@{
+        tool           = $Bin
+        package        = $Package
+        pinnedVersion  = $Pinned
+        os             = 'windows'
+        arch           = $script:Arch
+        checked        = $checked
+        nativeArtifact = [ordered]@{ available = $false; note = $NativeNote }
+        selected       = $script:Selected
+        nextSteps      = @($steps)
+        cliDoctor      = $Chained
+    }
+    return ($obj | ConvertTo-Json -Depth 20)
+}
+
+# Human-readable diagnosis for `doctor` without --json.
+function Write-DiagnosisText {
+    Write-Output "$Bin launcher diagnosis"
+    Write-Output ''
+    Write-Output ("  os / arch:      windows / {0}" -f $script:Arch)
+    Write-Output ("  pinned version: {0} ({1})" -f $Pinned, $Package)
+    if ($script:CliPresent) {
+        $verdict = if ($script:CliCompat) { 'compatible' } else { 'incompatible' }
+        Write-Output ("  {0} on PATH:  {1} (version {2}, {3})" -f $Bin, $script:CliPath, $script:CliVer, $verdict)
+    }
+    else {
+        Write-Output ("  {0} on PATH:  no" -f $Bin)
+    }
+    Write-Output ("  npx:            {0}" -f $(if ($script:NpxPresent) { $script:NpxPath } else { 'no' }))
+    Write-Output ("  bunx:           {0}" -f $(if ($script:BunxPresent) { $script:BunxPath } else { 'no' }))
+    Write-Output ("  node:           {0}" -f $(if ($script:NodePresent) { $script:NodeVer } else { 'no' }))
+    Write-Output ("  selected path:  {0}" -f $script:Selected)
+    if ($script:Selected -eq 'none') {
+        Write-Output ''
+        Write-Output ("No runtime can launch {0} here. {1}" -f $Bin, $NativeNote)
+        Write-Output 'Next steps:'
+        Write-Output '  - Install Node 22.13+ from https://nodejs.org, then re-run this launcher.'
+        Write-Output ("  - Or install Bun from https://bun.sh, or put a compatible {0} on PATH." -f $Bin)
+    }
+}
+
+# `doctor [--json] [extra...]`: launcher selection diagnosis. When a CLI is
+# resolvable, chain the CLI's own doctor so one call reports both layers. Extra
+# flags pass through to the chained CLI doctor.
+function Invoke-Doctor {
+    param([string[]] $DocArgs)
+    Collect
+    $json = $false
+    foreach ($a in $DocArgs) { if ($a -eq '--json') { $json = $true } }
+    if ($json) {
+        $chained = $null
+        if ($script:Selected -ne 'none') {
+            try {
+                $raw = (Invoke-Cli -CliArgs (@('doctor') + $DocArgs) 2>$null | Out-String).Trim()
+                if ($raw.StartsWith('{')) { $chained = ($raw | ConvertFrom-Json) }
+            }
+            catch { $chained = $null }
+        }
+        Write-Output (Build-DiagnosisJson $chained)
+    }
+    else {
+        Write-DiagnosisText
+        if ($script:Selected -ne 'none') {
+            Write-Output ''
+            Write-Output "--- $Bin doctor ---"
+            Invoke-Cli -CliArgs (@('doctor') + $DocArgs)
+        }
+    }
+}
+
+# Default action: forward every argument to the resolved CLI and exit with its
+# code. No usable runtime -> structured diagnosis on stderr, exit 78 (EX_CONFIG)
+# so the agent never mistakes the diagnosis for a result.
+function Invoke-Run {
+    param([string[]] $CliArgs)
+    $sel = Resolve-LaunchKind
+    switch ($sel) {
+        'path' { & $Bin @CliArgs; exit $LASTEXITCODE }
+        'npx' { & npx --yes --package "$Package@$Pinned" $Bin @CliArgs; exit $LASTEXITCODE }
+        'bunx' { & bunx --bun "$Package@$Pinned" @CliArgs; exit $LASTEXITCODE }
+        'none' {
+            Collect
+            [Console]::Error.WriteLine((Build-DiagnosisJson $null))
+            exit 78
+        }
+    }
+}
+
+$Command = ''
+if ($args.Count -ge 1) { $Command = [string]$args[0] }
+$Rest = @()
+if ($args.Count -gt 1) { $Rest = $args[1..($args.Count - 1)] }
+
+switch ($Command) {
+    'doctor' { Invoke-Doctor -DocArgs $Rest }
+    'where' { Collect; Write-Output $script:Selected }
+    default { Invoke-Run -CliArgs $args }
+}