@liustack/modlens 3.10.0 → 3.12.0

package/docs/cli.md

@@ -30,6 +30,8 @@ Output is a fixed JSON shape:
     "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" }] },
+    "semantics": { "scene": "workflow diagram", "entities": [], "relations": [] },
+    "visual": { "dominant_colors": ["white", "black"], "style": "flat", "notes": [] },
     "uncertainty": []
   },
   "meta": {
@@ -65,7 +67,7 @@ Output is a fixed JSON shape:
 `--extra-body` is how vendor-specific knobs get through, turning thinking off
 being the common one. It applies to the three API providers and replaces the
 configured `extraBody` for that run. Per-vendor spellings and the fields it
-refuses to touch are in [Configuration](configure.md).
+refuses to touch are in [Configuration](../skills/modlens/references/configure.md).
 
 The default `-m` model depends on the provider:
 
@@ -88,11 +90,11 @@ The default `-m` model depends on the provider:
 | `--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` (no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (uses your existing Claude subscription). Without `-p`, a run tries every provider that is set up, inline API providers first (5-10s), then the agents; the first good result wins and `meta.attempts` records the rest. Harnesses granted via `reuse.<harness>` contribute reused engines to the same regions (pi credentials inline, agent CLIs behind), with no priority over the user's own; details and the `guards` deny/allow lists are in [Configuration](configure.md).
+Five providers: `antigravity-cli` (no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (uses your existing Claude subscription). Without `-p`, a run tries every provider that is set up, inline API providers first (5-10s), then the agents; the first good result wins and `meta.attempts` records the rest. Harnesses granted via `reuse.<harness>` contribute reused engines to the same regions (pi credentials inline, agent CLIs behind), with no priority over the user's own; details and the `guards` deny/allow lists are in [Configuration](../skills/modlens/references/configure.md).
 
 Other subcommands:
 
 - `modlens guard [--model <id>]`: should the engine run for the active model at all? Exit 0 allow, 1 deny, verdict as JSON.
-- `modlens config <init|set|show>`: keys are `provider`, `reuse.<claude|codex|opencode|pi|grok>`, `guards.<denyModels|allowModels|denyWhenUnknown>`, and `<provider>.<apiKey|baseUrl|model|extraBody>`.
+- `modlens config <init|set|show>`: keys are `provider`, `proxy` (HTTP/HTTPS proxy for the API providers, `HTTPS_PROXY`/`HTTP_PROXY` also honored), `reuse.<claude|codex|opencode|pi|grok>`, `guards.<denyModels|allowModels|denyWhenUnknown>`, and `<provider>.<apiKey|baseUrl|model|proxy|extraBody>`.
 - `modlens doctor`: Node and node:sqlite, provider readiness, the failover chains for this machine, the detected harness, the guard's rules with a live verdict, and the Reuse section with per-harness grant decisions and discovered vision. Spends no quota; `--json` for a machine-readable report.
 

package/docs/harness-setup.md

@@ -18,7 +18,7 @@ One catch with text-only models: once `models.json` declares `input_modalities:
 
 ## Claude Code, Pi, OpenCode
 
-None of them writes a pasted image to a regular temp file, but all three persist the user message locally before any gateway strips it:
+None of them hands the model a usable temp-file path the way Codex does (newer Claude Code builds do write pastes to their own `~/.claude/image-cache/`, injected as a path line only in the terminal entrypoint), but all three persist the user message locally before any gateway strips it:
 
 | Harness | Storage | Notes |
 | :-- | :-- | :-- |
@@ -53,7 +53,7 @@ OpenCode with DeepSeek: `opencode auth login`, pick DeepSeek and paste the key (
 dsh is different from the other harnesses: modlens plugs in as a native tool, not a prompt-triggered skill. The package itself is a dsh bundle, so one command installs it into a profile:
 
 ```sh
-npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens
+npx -y @deepseek-ai/dsh plugin --profile web add @liustack/modlens@latest
 ```
 
-This registers a `read_image` tool whose schema reaches the model on every request (no trigger heuristics), runs the modlens CLI shipped inside the same package, and returns the structured evidence as the tool's canonical JSON output. Engines, reuse grants, and guard rules stay in `~/.modlens/config.json`, shared with every other harness. dsh is in developer preview and its plugin surface may change; the plugin touches only `ctx.tools.register` to keep that surface minimal.
+This registers a `read_image` tool whose schema reaches the model on every request (no trigger heuristics), runs the modlens CLI shipped inside the same package, and returns the structured evidence as the tool's canonical JSON output. Engines, reuse grants, and guard rules stay in `~/.modlens/config.json`, shared with every other harness. dsh is in developer preview and its plugin surface may change; the plugin keeps its touch small (raw tool registration, the llm adapter surface for the vision variants, the attachment reader, and one agent pre-step hook) and degrades loudly if any of them moves.

package/docs/output-schema.md

@@ -67,6 +67,6 @@ The CLI prints one JSON object to stdout:
 }
 ```
 
-Required fields: `summary`, `ocr`, `layout`, `semantics`, `uncertainty`. `visual` is optional.
+Required fields: `summary`, `ocr`, `layout`, `semantics`, `visual`, `uncertainty` — every top-level field, `visual` included. (Earlier docs called `visual` optional; the enforced schema has always required it, so build to the schema.)
 
 Changes from v1: pixel `bbox` coordinates and numeric `confidence` scores were removed. Vision models fabricate both, so v2 stops pretending to provide them. `layout.regions[].type` gained `code`.

package/docs/security.md

@@ -22,7 +22,15 @@ The `claude-cli` provider runs with `--allowedTools Read` only, so it can read l
 
 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. Remote URLs already prefer that path: the failover chain for a remote URL tries the inline API providers first and the agent last, because the inline path downloads the image itself, behind the private-address guards, the magic-byte image check, and the size cap, none of which apply when an agent fetches the URL on its own. An explicit `-p` pins one provider and overrides the chain.
+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 `-p gemini-api`, which downloads the bytes itself and runs no local agent. Remote URLs already prefer the inline region: the failover chain for a remote URL tries the inline API providers first and the agents last. Who actually fetches a remote URL differs per provider, and only a local download can be guarded locally:
+
+| Provider | Who fetches a remote URL | Local guards |
+| :-- | :-- | :-- |
+| `gemini-api` | modlens downloads, sends bytes inline | private-address guards, magic-byte check, 25 MB cap |
+| `openai`, `anthropic` | the URL is passed to the vendor, which fetches it | none locally; the vendor's own fetching policy applies |
+| `antigravity-cli`, agent CLIs | the agent fetches on its own | none locally |
+
+So the private-address guards, the magic-byte check, and the size cap protect exactly the paths where modlens itself downloads: every local file read, and gemini-api's remote fetch. An explicit `-p` pins one provider and overrides the chain.
 
 ## Image content is untrusted input
 

package/docs/troubleshooting.md

@@ -119,6 +119,64 @@ One known blind spot: storage detection reads the newest assistant turn recorded
 
 Note that the hard refusal above only fires on an actual `denyModels` match against the explicit `MODLENS_MODEL` value. Storage detection and the `denyWhenUnknown` policy never block `analyze`, they only speak through `modlens guard`, whose deny is advice to the agent rather than a locked door.
 
+## dsh says "declares no dsh.bundle — installed as a plain dependency"
+
+The dsh profile installed an old modlens version. The `dsh.bundle` declaration
+exists since 3.9.0, and pnpm v11's release-age gate (`minimumReleaseAge`,
+quarantining recently published versions, with a 10-day window measured on pnpm 11.21) silently falls back to an older version when every
+recent one is inside the window. That old version has no bundle declaration,
+so dsh correctly treats it as a plain dependency and none of the tools appear.
+
+The fix: name the version explicitly. pnpm applies the age gate when resolving
+a range, but an explicit version or dist-tag skips it ([pnpm#9989](https://github.com/pnpm/pnpm/issues/9989), verified on pnpm 11.21), which is why the install
+command carries `@latest`:
+
+```sh
+npx -y @deepseek-ai/dsh plugin --profile <name> add @liustack/modlens@latest
+```
+
+dsh's reconcile notices the bundle declaration on the new version and
+activates it; restart dsh afterwards. Verify with
+`npx -y @deepseek-ai/dsh plugin --profile <name> list` — the version shown
+should be 3.9.0 or newer.
+
+If a future pnpm closes that skip, the durable alternative is a one-time
+exclusion in `~/.dsh/profiles/<name>/pnpm-workspace.yaml` — the bare package
+name, not `name@version`, so it survives future releases:
+
+```yaml
+minimumReleaseAgeExclude:
+  - '@liustack/modlens'
+```
+
+then `npx -y @deepseek-ai/dsh plugin --profile <name> update @liustack/modlens`.
+The trade-off is honest either way: an explicit `@latest` (or the exclusion)
+opts modlens out of pnpm's supply-chain cooling-off window, so new releases
+install immediately.
+
+## fetch failed, or could not connect
+
+```
+Could not connect to generativelanguage.googleapis.com (UND_ERR_CONNECT_TIMEOUT). The request never reached the network. ...
+```
+
+The API request never left the machine. On networks that reach the internet
+through a proxy this is expected: Node's fetch ignores the proxy environment
+variables by default. modlens honors them once you ask it to route that way,
+in either form:
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:7890 modlens -i shot.png -p gemini-api   # env (NO_PROXY honored too)
+modlens config set proxy http://127.0.0.1:7890                        # persistent, all API providers
+modlens config set openai.proxy http://127.0.0.1:7890                 # one provider only
+```
+
+The proxy applies to API provider requests only. The remote-image download
+path keeps its direct, IP-pinned connection on purpose: its SSRF guards
+validate the exact address being contacted, and a proxy would blind them. On
+a proxied machine, prefer local files or let the failover chain hand remote
+URLs to a provider that fetches them upstream.
+
 ## Config file problems
 
 ```

package/dsh/index.js

@@ -24,11 +24,13 @@ const CLI_TIMEOUT_MS = 180_000
 export const name = 'modlens'
 export const inject = ['tools', 'agents', 'attachments', 'llm']
 
-const MEDIA_EXT = {
+export const MEDIA_EXT = {
   'image/png': '.png',
   'image/jpeg': '.jpg',
   'image/webp': '.webp',
   'image/gif': '.gif',
+  'image/heic': '.heic',
+  'image/heif': '.heif',
 }
 
 export function apply(ctx, config = {}) {
@@ -191,6 +193,84 @@ function registerVisionProvider(ctx, config) {
   }
 }
 
+// The same pasted attachment rides every later step of its session, but the
+// cache must never make a failure permanent or run the engine twice for
+// concurrent steps. So it stores promises (concurrent readers join the first
+// run), evicts failed reads on settle (a fixed config gets a fresh chance),
+// and caps itself LRU-style so a long-lived Web profile cannot hoard
+// evidence text forever.
+const EVIDENCE_CACHE_LIMIT = 64
+
+function cachedEvidence(ctx, adapter, block) {
+  const key = JSON.stringify(block.attachment ?? block)
+  const hit = adapter.evidenceCache.get(key)
+  if (hit !== undefined) {
+    // Refresh recency: Map iteration order is insertion order.
+    adapter.evidenceCache.delete(key)
+    adapter.evidenceCache.set(key, hit)
+    return hit
+  }
+  // Deliberately no caller signal: a shared entry must not die with its first
+  // caller (their abort used to cancel every concurrent joiner). A cancelled
+  // caller simply stops awaiting; the read finishes and the cache keeps it.
+  const pending = readImageBlock(ctx, block, undefined).then(
+    (evidence) => {
+      // Only evict our own entry: this promise may have been LRU-evicted and
+      // the key re-populated by a newer read meanwhile.
+      if (!evidence.ok && adapter.evidenceCache.get(key) === pending) {
+        adapter.evidenceCache.delete(key)
+      }
+      return evidence.block
+    },
+    (error) => {
+      // readImageBlock never rejects by contract; this is the belt for a
+      // future refactor breaking that, so a rejected promise cannot lodge in
+      // the cache forever.
+      if (adapter.evidenceCache.get(key) === pending) {
+        adapter.evidenceCache.delete(key)
+      }
+      return {
+        type: 'text',
+        text: `[A pasted image could not be read by modlens: ${
+          error instanceof Error ? error.message.slice(0, 300) : String(error)
+        }]`,
+      }
+    },
+  )
+  adapter.evidenceCache.set(key, pending)
+  while (adapter.evidenceCache.size > EVIDENCE_CACHE_LIMIT) {
+    adapter.evidenceCache.delete(adapter.evidenceCache.keys().next().value)
+  }
+  return pending
+}
+
+/**
+ * Wait on a shared promise without inheriting its lifetime: the caller's
+ * abort rejects THIS wait immediately, while the underlying read keeps
+ * running and lands in the cache for the retry.
+ */
+function abortableWait(promise, signal) {
+  if (!signal) return promise
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(signal.reason ?? new Error('aborted'))
+      return
+    }
+    const onAbort = () => reject(signal.reason ?? new Error('aborted'))
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(value)
+      },
+      (error) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(error)
+      },
+    )
+  })
+}
+
 async function convertImagesToEvidence(ctx, messages, signal, adapter) {
   const out = []
   for (const message of messages) {
@@ -204,13 +284,7 @@ async function convertImagesToEvidence(ctx, messages, signal, adapter) {
         content.push(block)
         continue
       }
-      const key = JSON.stringify(block.attachment ?? block)
-      let text = adapter.evidenceCache.get(key)
-      if (text === undefined) {
-        text = (await readImageBlock(ctx, block, signal)).text
-        adapter.evidenceCache.set(key, text)
-      }
-      content.push({ type: 'text', text })
+      content.push(await abortableWait(cachedEvidence(ctx, adapter, block), signal))
     }
     out.push({ ...message, content })
   }
@@ -251,7 +325,7 @@ function registerAutoRead(ctx) {
           content.push(block)
           continue
         }
-        content.push(await readImageBlock(ctx, block, payload.signal))
+        content.push((await readImageBlock(ctx, block, payload.signal)).block)
       }
       messages.push({ ...message, content })
     }
@@ -259,6 +333,12 @@ function registerAutoRead(ctx) {
   })
 }
 
+/**
+ * Read one image block into an evidence text block. Never throws: failures
+ * degrade to an explanatory block with `ok: false`, so callers can decide
+ * what a failure means (the pre-step keeps the step going, the cache refuses
+ * to memoize it).
+ */
 async function readImageBlock(ctx, block, signal) {
   const { mkdtemp, rm, writeFile } = await import('node:fs/promises')
   const { tmpdir } = await import('node:os')
@@ -275,9 +355,15 @@ async function readImageBlock(ctx, block, signal) {
         "attachments.readImage returned no 'data' bytes; the dsh attachment shape may have changed",
       )
     }
-    dir = await mkdtemp(join(tmpdir(), 'modlens-dsh-'))
     const mediaType = stored.ref?.mediaType ?? block.attachment?.mediaType
-    const file = join(dir, `paste${MEDIA_EXT[mediaType] ?? '.png'}`)
+    const ext = MEDIA_EXT[mediaType]
+    if (!ext) {
+      // Refusing beats disguising: a fake .png suffix would make the CLI (and
+      // the provider behind it) judge mislabelled bytes.
+      throw new Error(`unsupported pasted media type ${mediaType ?? '(none declared)'}`)
+    }
+    dir = await mkdtemp(join(tmpdir(), 'modlens-dsh-'))
+    const file = join(dir, `paste${ext}`)
     await writeFile(file, Buffer.from(stored.data), { mode: 0o600 })
     const cli = process.env.MODLENS_DSH_CLI || CLI_PATH
     const { stdout, stderr, code } = await run(
@@ -290,15 +376,21 @@ async function readImageBlock(ctx, block, signal) {
     }
     const parsed = JSON.parse(stdout)
     return {
-      type: 'text',
-      text: `[Pasted image, read by the modlens vision bridge]\n${renderEvidence(parsed.result)}`,
+      ok: true,
+      block: {
+        type: 'text',
+        text: `[Pasted image, read by the modlens vision bridge]\n${renderEvidence(parsed.result)}`,
+      },
     }
   } catch (error) {
     return {
-      type: 'text',
-      text: `[A pasted image could not be read by modlens: ${
-        error instanceof Error ? error.message.slice(0, 300) : String(error)
-      }. Tell the user, and suggest running \`npx @liustack/modlens doctor\`.]`,
+      ok: false,
+      block: {
+        type: 'text',
+        text: `[A pasted image could not be read by modlens: ${
+          error instanceof Error ? error.message.slice(0, 300) : String(error)
+        }. Tell the user, and suggest running \`npx @liustack/modlens doctor\`.]`,
+      },
     }
   } finally {
     if (dir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "coverage": "vitest run --coverage",
-    "lint": "biome check src scripts",
+    "lint": "biome check src scripts dsh",
     "format": "biome check --write src scripts",
     "eval": "node evals/run.mjs",
     "release": "node scripts/release.mjs",

package/skills/modlens/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modlens
-description: "Plug-in vision for text-only models. Hard rule: when a file path or URL with an image extension (.png, .jpg, .jpeg, .webp, .gif, .bmp, .heic) appears anywhere in the conversation (typed by the user, injected as a `[Image: source: <path>]` line, or inside a tag) and you cannot see that image's content, run this skill on it before any other approach: no self-built OCR, no PIL, no tesseract. Also triggers on pasted-image placeholders such as `[Image #1]` and `[Unsupported Image]`. If you can actually see the image, do not use this skill. When unsure, run `modlens guard` before the first read of a session: a deny verdict means the active model has native vision and must read the image itself. 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)."
+description: "Plug-in vision for text-only models. Hard rule: when a file path or URL with an image extension (.png, .jpg, .jpeg, .webp, .gif, .heic, .heif) appears anywhere in the conversation (typed by the user, injected as a `[Image: source: <path>]` line, or inside a tag) and you cannot see that image's content, run this skill on it before any other approach: no self-built OCR, no PIL, no tesseract. Also triggers on pasted-image placeholders such as `[Image #1]` and `[Unsupported Image]`. If you can actually see the image, do not use this skill. When unsure, run `modlens guard` before the first read of a session: a deny verdict means the active model has native vision and must read the image itself. 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)."
 compatibility: Requires network access and one of node 22+/npx, bun/bunx, or a preinstalled modlens binary on PATH.
 allowed-tools: Bash
 ---
@@ -20,11 +20,11 @@ powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>
 
 It resolves a working runtime (PATH `modlens`, then `npx`, then `bunx`) and forwards your arguments unchanged. Exit 78 means no runtime: relay the `nextSteps` from its stderr JSON instead of retrying.
 
-If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.10.0):
+If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.12.0):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.10.0: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.10.0 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.10.0 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.12.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.12.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.12.0 <args>`.
 4. Otherwise 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 pin and the diagnostic fields.

package/skills/modlens/references/configure.md

@@ -22,7 +22,8 @@ Everything lives under four top-level keys, all optional. This example shows eve
 ```json
 {
   "provider": "gemini-api",
-  "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true },
+  "proxy": "http://127.0.0.1:7890",
+  "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true, "grok": true },
   "guards": {
     "allowModels": ["deepseek-v4-*", "glm-5.*", "minimax-m2.5*", "qwen3-coder*"],
     "denyModels": ["glm-*v*", "deepseek-vl*"],

package/skills/modlens/references/find-image.md

@@ -18,7 +18,7 @@ Newer Claude Code builds write every pasted image to `~/.claude/image-cache/<ses
 
 ## Claude Code, Pi, or OpenCode (no usable path anywhere)
 
-The image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see. Whatever a gateway strips from the request, these harnesses persist user messages, image bytes included, in local session storage first: 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 a bunx-resolved launcher needs a real Node install for OpenCode recovery).
+The image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see. Whatever a gateway strips from the request, these harnesses persist user messages, image bytes included, in local session storage first: 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.13+; Bun cannot load node:sqlite, so a bunx-resolved launcher needs a real Node install for OpenCode recovery).
 
 - Run `modlens recover-paste` from the project directory the conversation is happening in (`--count <n>` for several images). It detects which harness it is running inside and reads ONLY that harness's storage. In Claude Code it targets your exact session automatically via the injected `CLAUDE_CODE_SESSION_ID`; `--session <id>` is only needed to override.
 - The output is JSON with real file paths, oldest to newest, so the LAST path is the most recent paste: analyze that one first. Entries carry `filename` when the harness stored one; match on it when the user's message mentions a name.

package/skills/modlens/references/onboard.md

@@ -8,7 +8,7 @@ Run this flow when `~/.modlens/config.json` does not exist, or `modlens config s
 modlens doctor --json
 ```
 
-Read three things from the report: which providers are `ready`, the Reuse section (per-harness decisions plus discovered logins and vision models; the harness this conversation runs inside is itself the first reusable engine), and the guard state. Doctor spends no quota and makes no network calls.
+Read three things from the report: each provider's `status` (`ready` means verified, `installed` means a CLI is on PATH with its sign-in unverified until the first real read, rendered as `[ok?]` in the text report), the Reuse section (per-harness decisions plus discovered logins and vision models, where the harness this conversation runs inside is itself the first reusable engine), and the guard state. Doctor spends no quota and makes no network calls.
 
 ## 2. Tell the user what their machine already has
 
@@ -16,9 +16,9 @@ One line per finding, plain words, in the user's language. Name concrete things,
 
 - An engine is ready: "modlens is ready to go: <provider> is configured (via <env var / config file / existing login>)."
 - Reusable vision found: "Your <harness> CLI is signed in and its model can read images. modlens can reuse it when needed, about <n> seconds per read, and it spends that account's quota."
-- Nothing at all: "No vision engine is set up yet. The fastest free option is a Gemini API key (three minutes, no card); Antigravity CLI works with no sign-up at all."
+- Nothing at all: "No vision engine is set up yet. The fastest free option is a Gemini API key (three minutes, no card). Antigravity CLI works with no sign-up at all."
 
-Do not dump the raw doctor output on the user; summarize it. Do not describe options the machine does not have.
+Do not dump the raw doctor output on the user, summarize it. Do not describe options the machine does not have.
 
 ## 3. Ask before touching anything
 
@@ -27,7 +27,7 @@ Consent rules:
 - One question per decision, never a bundled yes. Reusing Codex and reusing pi credentials are two questions (or one question with independent options), not one.
 - Each question names the harness, whose quota it spends, and the accounting promise. Example wording: "Allow modlens to reuse your signed-in Codex CLI for image reads? Every reused read is labeled in the result so you always see whose quota was spent."
 - The do-nothing outcome must be safe and stated: "If you skip this, modlens just uses the engines you configure yourself."
-- If the user offers an API key, take exactly that key; never go looking for keys they did not hand over.
+- If the user offers an API key, take exactly that key, and never go looking for keys they did not hand over.
 
 ## 4. Apply only what was consented to
 

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.10.0
+- Pinned CLI version: 3.12.0
 - npm package: `@liustack/modlens`
 - CLI binary name: `modlens`
 

package/skills/modlens/scripts/run.ps1

@@ -24,7 +24,7 @@ $ErrorActionPreference = 'Stop'
 # package.json version, and the release script rewrites it on every bump.
 $Package = '@liustack/modlens'
 $Bin = 'modlens'
-$Pinned = '3.10.0'
+$Pinned = '3.12.0'
 # -------------------------------------------------------------------------------
 
 $NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'

package/skills/modlens/scripts/run.sh

@@ -22,7 +22,7 @@ set -eu
 # package.json version, and the release script rewrites it on every bump.
 PKG="@liustack/modlens"
 BIN="modlens"
-PINNED="3.10.0"
+PINNED="3.12.0"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"