@liustack/modlens 3.0.0 → 3.1.1

package/docs/harness-setup.md

@@ -38,6 +38,12 @@ Running a text-only model behind `ANTHROPIC_BASE_URL` in Claude Code, a pasted i
 
 Symlinks work in all of them, so linking the skill folder once keeps every agent on the latest version.
 
+## Platform support
+
+macOS and Linux are fully supported and verified in CI on Node 22 and 24.
+
+Windows runs the same CI matrix. Detection there skips the process-ancestry pass, since there is no `ps`, and falls back to the environment fingerprints above, so a harness that sets none of them reads as undetected (force it with `--harness` or `MODLENS_HARNESS`). OpenCode paste recovery is covered on Windows, including the path-separator normalization from [#11](https://github.com/liustack/modlens/issues/11): opencode records `session.directory` with forward slashes while `path.resolve` returns backslashes there, and both sides are normalized before matching. The JSONL stores (Claude Code, Pi) key off `os.homedir()` and each harness's own on-disk slug, and are exercised on POSIX. External engines (Antigravity CLI, the Claude CLI) run only where they ship a Windows build.
+
 ## Gateway setups
 
 OpenCode with DeepSeek: `opencode auth login`, pick DeepSeek and paste the key (it lands in `~/.local/share/opencode/auth.json`), then set the default model in `~/.config/opencode/opencode.jsonc` to `deepseek/deepseek-v4-flash`. Pi reads its key from `~/.pi/agent/auth.json`.

package/docs/security.md

@@ -20,7 +20,9 @@ ModLens invokes `agy` with `--dangerously-skip-permissions` because prompt mode
 
 The `claude-cli` provider runs with `--allowedTools Read` only, so it can read local files and nothing else.
 
-Both subprocess providers also run in a throwaway directory containing only the one image, created fresh per call and removed afterward. Text inside an image is untrusted, so an injection could otherwise steer a broadly-permissioned agent into reading files that sit next to the original. A directory of one removes that reach. Passing `--workdir` opts out and runs where you point it.
+Both subprocess providers also run in a throwaway directory created fresh per call and removed afterward. For a local image it holds a private copy of that one image and nothing else, and it is a real copy, never a hardlink, so a provider writing to its temp path cannot touch the original. For a remote image the directory is empty and the agent downloads into it. Without this, text inside an image could steer a broadly-permissioned agent into reading files next to the original, or whatever project the caller happened to be in. Passing `--workdir` opts out and runs where you point it.
+
+This is exposure reduction, not an OS sandbox: the agent can still read absolute paths, reach the network, and spawn processes. Treat it as a narrower default, not a security boundary. For images you do not trust, prefer an inline API provider (`-p gemini-api`), which hands the bytes to an HTTP endpoint and runs no local agent.
 
 ## Image content is untrusted input
 

package/docs/troubleshooting.md

@@ -81,7 +81,7 @@ The output lists images oldest to newest, so the **last** entry is the most rece
 `recover-paste` auto-detects which harness it runs inside (process ancestry first, then environment fingerprints) and reads only that harness's storage. Two knobs override it:
 
 - **`MODLENS_HARNESS`** forces the storage scope without a flag: `claude-code`, `pi`, `opencode`, `codex`, or `none` (scan every store, no scoping). Detection reads it first, so it wins over ancestry and env fingerprints. `--harness` does the same for a single run.
-- **`--out-dir`** sets where recovered images land. By default each run mints a fresh, unpredictable `<tmpdir>/modlens-paste-*` directory (0700, holding 0600 files), so nobody can pre-create a shared path to intercept the bytes. Point it elsewhere when the system temp dir is not where you want them. An explicit `--out-dir` that already exists is rejected unless it is a real directory (not a symlink), owned by you, with no group or world access.
+- **`--out-dir`** sets where recovered images land. By default each run mints a fresh, unpredictable `<tmpdir>/modlens-paste-*` directory (0700, holding 0600 files), so nobody can pre-create a shared path to intercept the bytes. Point it elsewhere when the system temp dir is not where you want them. An explicit `--out-dir` that already exists is rejected unless it is a real directory (not a symlink), owned by you, with no group or world access. On Windows those ownership and permission checks are skipped, since the platform has no POSIX bits (see the Windows section below). The symlink guard still applies.
 
 ## This is a Codex session
 
@@ -127,6 +127,14 @@ antigravity-cli provider timed out after 210000 ms.
 
 Retry once with `--timeout 300000`. Dense images on agy legitimately take 15-40 seconds, and `-m gemini-3.1-pro-high` is slower still. Engines that ignore SIGTERM are escalated to SIGKILL, so a timeout returns promptly regardless.
 
+## Windows
+
+ModLens runs on Windows. Three platform differences are worth knowing:
+
+- **No POSIX permission checks.** Windows files carry no owner, group, or world bits (they read back as `0o666`/`0o777`, with access governed by ACLs), so `doctor` does not judge the config file's mode and `recover-paste --out-dir` does not reject a directory on ownership or group/world access. The symlink guard on `--out-dir` still applies.
+- **Harness detection uses environment fingerprints.** There is no `ps` to read the process tree, so detection relies on the environment variables each harness sets. If a run guesses wrong, force it with `--harness <name>` or `MODLENS_HARNESS`.
+- **Paste recovery.** OpenCode recovery is covered on Windows (issue #11). The Claude Code and Pi JSONL paths depend on `os.homedir()` and each harness's on-disk slug there. If recovery comes up empty, pass `--transcript` at the file, or drag the image into the terminal.
+
 ## Still stuck
 
 Include the exact command and the full error in an issue: https://github.com/liustack/modlens/issues

package/package.json

@@ -1,15 +1,29 @@
 {
   "name": "@liustack/modlens",
-  "version": "3.0.0",
+  "version": "3.1.1",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {
     "modlens": "./dist/main.js"
   },
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "lint": "biome check src scripts",
+    "format": "biome check --write src scripts",
+    "eval": "node evals/run.mjs",
+    "release": "node scripts/release.mjs",
+    "prepublishOnly": "pnpm build",
+    "docs:list": "node scripts/docs-list.js"
+  },
   "files": [
     "dist",
     "docs",
     "skills/modlens/SKILL.md",
+    "skills/modlens/scripts",
     "skills/modlens/references",
     "CHANGELOG.md",
     "SECURITY.md"
@@ -40,7 +54,8 @@
     "node": ">=22.13"
   },
   "dependencies": {
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "undici": "^8.10.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.7",
@@ -49,17 +64,5 @@
     "typescript": "^5.9.3",
     "vite": "^6.4.1",
     "vitest": "^3.2.7"
-  },
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "coverage": "vitest run --coverage",
-    "lint": "biome check src scripts",
-    "format": "biome check --write src scripts",
-    "eval": "node evals/run.mjs",
-    "release": "node scripts/release.mjs",
-    "docs:list": "node scripts/docs-list.js"
   }
 }

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.1.1):
 
-ModLens supports five vision providers. Check what is configured:
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.1.1: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.1.1 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.1.1 <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:
@@ -69,9 +84,10 @@ Harnesses rarely hand you a clean path. First identify which harness you are in,
 
 **Claude Code, Pi, or OpenCode** (no path tag anywhere; the image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see):
 
-- None of these harnesses writes pasted images to a regular temp file, but all of them persist user messages locally before any gateway strips them: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+). Run `modlens recover-paste` from the project directory the conversation is happening in (add `--count <n>` for several images). It detects which harness it is running inside (process ancestry, then env fingerprints) and reads ONLY that harness's storage, so another tool's old sessions cannot leak in. In Claude Code it also targets your exact session automatically via the injected CLAUDE_CODE_SESSION_ID; `--session <id>` (e.g. from the ${CLAUDE_SESSION_ID} substitution) is only needed to override.
+- None of these harnesses writes pasted images to a regular temp file, but all of them persist user messages locally before any gateway strips them: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+; Bun cannot load node:sqlite, so if the launcher resolved to bunx, OpenCode recovery needs a real Node install). Run `modlens recover-paste` from the project directory the conversation is happening in (add `--count <n>` for several images). It detects which harness it is running inside (process ancestry, then env fingerprints) and reads ONLY that harness's storage, so another tool's old sessions cannot leak in. In Claude Code it also targets your exact session automatically via the injected CLAUDE_CODE_SESSION_ID; `--session <id>` (e.g. from the ${CLAUDE_SESSION_ID} substitution) is only needed to override.
 - The output is JSON with real file paths, ordered oldest to newest, so the LAST path is the user's most recent paste. Analyze that one first. Entries carry `filename` (the original attachment name) when the harness stored one; if the user's message or an error mentions a filename, match on it.
 - Run every command yourself: `recover-paste`, then `modlens -i <path>` on the recovered file, then answer from the JSON. Never ask the user to run modlens or to relay paths.
+- When the analysis is done, delete the recovered files: they are private copies of the user's pasted images sitting in the temp dir, and nothing cleans them up until the OS does. Remove the recovery output directory (each entry's `path` sits inside it), unless the user asked to keep the files.
 - The output's `detected` field names the harness scope that was applied. If it is absent, detection failed and every store was scanned by newest-image timestamp: before describing anything, check that `harness` and `filename` match what you expect, force the scope with `--harness <claude-code|pi|opencode>` if they do not, and when in doubt ask the user for the file instead of describing the wrong image.
 - Recovery is scoped to this project: the harness's own record of its working directory is checked, not just the directory name, so images from a neighbouring project are never handed over. Recovered files are private to the user (0600).
 - If recovery fails (session storage is each harness's internals and may change), ask the user to drag the image file into the terminal or type its path.
@@ -101,7 +117,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,105 @@
+# 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.1
+- 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, and `node` meets the CLI's 22.13 floor** — `npx --yes --package @liustack/modlens@<pinned> modlens <args>`. An npx sitting on an older node is skipped: it would select a path known to fail at run time.
+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 ships no native artifact. The `npx` and `bunx` paths fetch the pinned
+npm package on first use and cache it (that is how those runners work); nothing
+else is ever downloaded. 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` — `{ present, path, nodeMeetsFloor }`; `nodeMeetsFloor` is whether
+  the local node satisfies the CLI's 22.13 floor, required for the npx path.
+- `checked.bunx` — `{ present, path }`.
+- `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` spends no quota. The launcher's own diagnosis is offline: it inspects
+the local environment and makes no network request of its own. Chaining the
+CLI's `doctor` through the npx or bunx path can download the pinned package the
+first time (that is how those runners work); after that it is served from the
+local cache.
+
+One capability note for the bunx path: Bun cannot load `node:sqlite`, which
+OpenCode paste recovery needs, so on a machine where the launcher resolved to
+bunx, `recover-paste` for OpenCode requires installing Node 22.13+ instead.
+
+## 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.