@liustack/modlens 2.0.0 → 2.2.0

package/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/liustack/modlens/main/assets/banner.jpg" width="100%" alt="ModLens, plug-in vision for text-only LLMs" />
   <h1>ModLens</h1>
-  <p><b>Plug-in eyes for text-only LLMs. Free.</b></p>
+  <p><b>Free plug-in vision for your text-only LLM.</b></p>
   <p>
     <a href="https://www.npmjs.com/package/@liustack/modlens"><img src="https://img.shields.io/npm/v/@liustack/modlens" alt="npm"></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
@@ -9,12 +9,12 @@
   <p><a href="./README.zh-CN.md">简体中文</a></p>
 </div>
 
-DeepSeek-V4-Flash is one of the smartest cheap models you can run, and it's completely blind. Show it a screenshot and it just shrugs. Same dead end for every text-only model wired into Claude Code, OpenClaw, Codex, or any Agent Skills harness.
+DeepSeek-V4-Flash gives you a lot of model for very little money: fast, strong, and its one real flaw is no multimodal. And it's not just DeepSeek. Every text-only model running inside Codex, Claude Code, Pi Agent, or OpenClaw hits the same wall.
 
-One command fixes that. Point ModLens at an image, a local path or a URL, and it hands back structured JSON evidence a text-only model can actually reason over: OCR text, layout regions in reading order, entities, relations, visual clues. The seeing itself happens in [Antigravity CLI](https://antigravity.google) (`agy`), so it runs on Google's free quota, not your API bill.
+ModLens fixes this the lightest way possible. It never touches your config and never adds a local proxy. It's just a vision plug-in, usable as a CLI or as an Agent Skill, that turns any image into structured visual evidence: text, layout, regions, entities, relations, visual clues. Under the hood it runs on [Antigravity CLI](https://antigravity.google) (`agy`), whose vision comes from free-quota Gemini 3.6 Flash. And Gemini's image understanding is famously good, good enough to embarrass most flagships, Fable 5 included. How it works:
 
 ```text
-your text-only model ──▶ modlens skill (auto-triggers on images)
+text-only model in your agent harness ──▶ modlens skill (auto-triggers on images)
                               │
                               ▼
                    agy · Gemini 3.6 Flash (free quota)
@@ -23,8 +23,6 @@ your text-only model ──▶ modlens skill (auto-triggers on images)
               structured JSON evidence ──▶ model answers with sight
 ```
 
-Install the skill once and your agent starts handling images on its own. No model swap, no API key, no prompt surgery.
-
 ## Quick start
 
 **1. Install Antigravity CLI and sign in** (one-time):
@@ -34,7 +32,7 @@ curl -fsSL https://antigravity.google/cli/install.sh | bash
 agy    # opens browser sign-in, then exit
 ```
 
-**2. Install the skill.** Tell your agent (Claude Code, Codex, OpenClaw, Cursor, ...):
+**2. Install the skill.** Just tell your agent (Claude Code, Codex, OpenClaw, Cursor, ...):
 
 ```text
 Install the skill from https://github.com/liustack/modlens
@@ -46,7 +44,7 @@ or do it yourself:
 npx -y skills add liustack/modlens
 ```
 
-**3. Use it.** Drop an image path into the chat and ask anything. The skill fires automatically whenever your model needs eyes.
+**3. Use it.** Paste an image path into the CLI and ask anything. The skill fires on its own.
 
 ## See it work
 
@@ -69,14 +67,28 @@ Real output, truncated:
         { "language": "en", "text": "BEFORE YOU BUILD" }
       ]
     },
-    "layout": { "regions": [ { "reading_order": 1, "text": "/shaping BEFORE YOU BUILD", "type": "other" } ] },
+    "layout": {
+      "regions": [
+        {
+          "reading_order": 1,
+          "text": "/shaping BEFORE YOU BUILD",
+          "type": "other"
+        }
+      ]
+    },
     "uncertainty": []
   },
   "meta": { "model": "gemini-3.6-flash-low", "durationSeconds": 25.4 }
 }
 ```
 
-A run takes 15-40 seconds. The JSON shape is locked in by a schema at the provider level, so your agent never has to fish JSON out of markdown again.
+Here is the whole loop inside the Codex desktop app: drop in a tweet screenshot, and a text-only DeepSeek-V4-Flash reads all of it through ModLens: the caption, the engagement numbers (2.9K replies, 270K likes, 5M views), even the image's alt text. Where the resolution runs out, it says so instead of guessing.
+
+![Text-only DeepSeek reading a tweet screenshot in full detail via ModLens](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-app.png)
+
+Batch mode works too: drop three illustrations at once, and the model announces it will read them one by one through ModLens, then delivers all three descriptions in 21 seconds, design intent included.
+
+![Text-only DeepSeek reading three images in one go via ModLens](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
 
 ## CLI reference
 
@@ -97,16 +109,37 @@ modlens -i <image-path-or-url> [options]
 
 Reach for `-m gemini-3.1-pro-high` on dense screenshots or tricky documents. Output contract: [skills/modlens/references/output-schema.md](skills/modlens/references/output-schema.md).
 
+## Providers and config
+
+ModLens ships five vision providers. `antigravity-cli` stays the default: zero keys, pure free quota.
+
+| Provider | Needs | Typical speed | Notes |
+| :-- | :-- | :-- | :-- |
+| `antigravity-cli` (default) | `agy` signed in | 15-40s | free quota, full agent loop |
+| `gemini-api` | free AI Studio key | 5-10s | fastest free route, schema enforced server-side |
+| `openai` | baseUrl + apiKey + model | endpoint-dependent | any OpenAI-compatible multimodal endpoint (qwen-vl, GLM, ...) |
+| `anthropic` | `ANTHROPIC_API_KEY` | a few seconds | Claude Haiku by default, schema via forced tool call |
+| `claude-cli` | Claude Code signed in | 20-45s | no key, rides your Claude subscription, Read-only permissions |
+
+Config lives in `~/.modlens/config.json`. Environment variables override the file (`GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`), and CLI flags override everything.
+
+```bash
+modlens config init                          # write a starter config
+modlens config set gemini-api.apiKey <key>   # saved with 0600 perms
+modlens config show                          # keys come out masked
+modlens config set provider gemini-api       # switch the default provider
+```
+
+The free Gemini key takes three minutes at [aistudio.google.com](https://aistudio.google.com), no credit card. Or skip the manual work entirely and tell your agent: "configure modlens with my Gemini API key".
+
 ## Using it in Codex (DeepSeek and friends)
 
-Codex speaks only the Responses API, and DeepSeek's official endpoint supports it natively. Start with the [official integration guide](https://api-docs.deepseek.com/quick_start/agent_integrations/codex/): its `models.json` declares deepseek-v4-flash as text-only (`input_modalities: ["text"]`), and that one line is what unlocks everything below.
+Codex speaks only the Responses API, and DeepSeek's official endpoint supports it natively. Start with the [official integration guide](https://api-docs.deepseek.com/quick_start/agent_integrations/codex/): its `models.json` declares deepseek-v4-flash as text-only (`input_modalities: ["text"]`), and that one line is what unlocks the whole flow.
 
 One catch: once text-only is declared, the Codex TUI **blocks Ctrl+V image paste outright** (`Model deepseek-v4-flash does not support image inputs`). The gate sits in the input box itself, so the image never makes it into the message. Two moves get around it, both verified end to end with deepseek-v4-flash:
 
 - **Drag the image file into the terminal**, or type its path. The path lands as plain text, and the modlens skill picks it up from there.
-- Attach it with `codex exec -i image.png "..."`. Codex strips the pixels in core but leaves a `<image name=[Image #1] path="/tmp/....png">` text tag behind, and the skill reads the path out of that tag.
-
-Skip `models.json` (a bare custom-model config) and Codex assumes your model can see images, sending them raw, and whether that survives depends on the provider's patience. Dragging the file in is the one move that works everywhere, in every harness.
+- Attach it with `codex exec -i image.png "..."`. The skill reads the path out of the message tag.
 
 ## Why a bridge instead of a multimodal model?
 
@@ -116,22 +149,22 @@ Skip `models.json` (a bare custom-model config) and Codex assumes your model can
 
 ModSearch, ModLens's sibling project, plays the same trick for web search and page fetching: [liustack/modsearch](https://github.com/liustack/modsearch).
 
-## Built with liustack
+## Shameless plug
 
-ModLens v2 was shaped, coded, and shipped with **[liustack](https://github.com/liustack/liustack)**. Four Agent Skills, one loop: `shaping` before you build, `coding` while you build, `dig` when it breaks, `snapshot` when you hand off. A lighter, sharper alternative to Superpowers.
+This project runs on LIUSTACK Skills. ModLens v2 was shaped, coded, and shipped with **[liustack](https://github.com/liustack/liustack)** end to end: `shaping` before you build, `coding` while you build, `dig` when it breaks, `snapshot` when you hand off. Lighter than Superpowers, and sharper.
 
-**ModLens gave your model eyes. liustack gives your whole workflow discipline:**
+**ModLens gives your model eyes. LIUSTACK Skills gives your dev workflow wings:**
 
 ```bash
 npx -y skills add liustack/liustack -g
 ```
 
-⭐ Like the idea? [Star ModLens](https://github.com/liustack/modlens) and [star liustack](https://github.com/liustack/liustack). Stars are how the next developer finds them.
+⭐ Like it? [Star ModLens](https://github.com/liustack/modlens) and [star liustack](https://github.com/liustack/liustack). Stars are how the next developer finds them.
 
 ## Security notes
 
-- ModLens runs `agy` with `--dangerously-skip-permissions`, because print mode skips every tool call without it. The prompt keeps the agent to reading that one image and tells it to treat image content as data, never as instructions. Even so, only point it at images you would open yourself, and run it inside a sandboxed workspace when you can.
-- Vision output is evidence, not gospel. Anything the engine cannot read lands in `uncertainty` instead of getting invented. Pixel bounding boxes and confidence scores were dropped in v2 because models fabricate them.
+- ModLens runs `agy` with `--dangerously-skip-permissions`, because print mode can fail in some setups without it. The prompt keeps the agent to reading that one image and tells it to treat image content as data, never as instructions. Even so, only point it at images you would open yourself, and run it inside a sandboxed workspace when you can.
+- Vision output is evidence. Anything the engine cannot read lands in `uncertainty` instead of getting invented. Pixel bounding boxes and confidence scores were dropped in v2 because models fabricate them.
 
 ## Disclaimer
 

package/README.zh-CN.md

@@ -1,7 +1,7 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/liustack/modlens/main/assets/banner.jpg" width="100%" alt="ModLens，给纯文本 LLM 外挂视觉" />
   <h1>ModLens</h1>
-  <p><b>给纯文本 LLM 外挂一双眼睛，免费。</b></p>
+  <p><b>免费给你的大语言模型（纯文本 LLM）外挂视觉能力。</b></p>
   <p>
     <a href="https://www.npmjs.com/package/@liustack/modlens"><img src="https://img.shields.io/npm/v/@liustack/modlens" alt="npm"></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
@@ -9,12 +9,12 @@
   <p><a href="./README.md">English</a></p>
 </div>
 
-DeepSeek-V4-Flash 便宜又能打，可惜是个瞎子。甩一张截图过去，只换来两手一摊。Claude Code、OpenClaw、Codex，随便哪个 Agent Skills 宿主里跑着的纯文本模型，都卡在这同一个死结上。
+DeepSeek-V4-Flash 碗大又好吃，速度快，性能强，要说唯一的缺点就是没有多模态。不仅 DeepSeek-V4-Flash，只要是纯文本语言模型，跑在 Codex、Claude Code、Pi Agent、OpenClaw 中，都有这个问题。
 
-一条命令解开这个死结。把 ModLens 指向任意图片（本地路径或 URL），它吐出纯文本模型真正用得上的结构化 JSON 证据：OCR 文字、按阅读顺序排好的版面区块、实体、关系、视觉线索。真正「看」图这件事，交给 [Antigravity CLI](https://antigravity.google)（`agy`）去干，用的是 Google 的免费额度，不碰你的 API 账单。
+ModLens 用最轻量级方案解决这个问题。ModLens 不会入侵你的配置，也不会给你添加本地代理，ModLens 只是一个视觉外挂，有 cli 或 skill 两种模式。ModLens 能产出结构化的视觉证据：文字、版面、区块、实体、关系、视觉线索。ModLens 由 Antigravity [Antigravity CLI](https://antigravity.google)（`agy`）驱动，而 Antigravity 的视觉由免费额度的 Gemini 3.6 Flash 驱动。众所周知，Gemini 的识图能力，连 Fable 5 都吊打。原理如下：
 
 ```text
-你的纯文本模型 ──▶ modlens skill（遇到图片自动触发）
+Agent Harness 中的纯文本模型 ──▶ modlens skill（遇到图片自动触发）
                         │
                         ▼
              agy · Gemini 3.6 Flash（免费额度）
@@ -23,8 +23,6 @@ DeepSeek-V4-Flash 便宜又能打，可惜是个瞎子。甩一张截图过去
            结构化 JSON 证据 ──▶ 模型带着视力回答
 ```
 
-skill 装一次，你的 agent 以后见着图片自己就处理了。模型不用换，API key 不用要，提示词也不用改。
-
 ## 快速开始
 
 **1. 安装 Antigravity CLI 并登录**（一次性）：
@@ -37,7 +35,7 @@ agy    # 浏览器完成登录后退出
 **2. 安装 skill。** 直接告诉你的 agent（Claude Code、Codex、OpenClaw、Cursor 等）：
 
 ```text
-Install the skill from https://github.com/liustack/modlens
+安装这个 skill https://github.com/liustack/modlens
 ```
 
 或者自己动手：
@@ -46,7 +44,7 @@ Install the skill from https://github.com/liustack/modlens
 npx -y skills add liustack/modlens
 ```
 
-**3. 用起来。** 往对话里丢一个图片路径，随便问。模型需要眼睛的时候，skill 自动触发。
+**3. 用起来。** 在 cli 里粘贴个图片路径，随便问，skill 会自动触发。
 
 ## 看看效果
 
@@ -69,14 +67,28 @@ npx @liustack/modlens -i workflow.jpg
         { "language": "en", "text": "BEFORE YOU BUILD" }
       ]
     },
-    "layout": { "regions": [ { "reading_order": 1, "text": "/shaping BEFORE YOU BUILD", "type": "other" } ] },
+    "layout": {
+      "regions": [
+        {
+          "reading_order": 1,
+          "text": "/shaping BEFORE YOU BUILD",
+          "type": "other"
+        }
+      ]
+    },
     "uncertainty": []
   },
   "meta": { "model": "gemini-3.6-flash-low", "durationSeconds": 25.4 }
 }
 ```
 
-一次运行 15-40 秒。JSON 结构由 provider 层的 schema 硬性保证，你的 agent 不用再从 markdown 里抠 JSON 出来。
+整条链路在 Codex 桌面 App 里跑起来是这样：丢一张推文截图，纯文本的 DeepSeek-V4-Flash 通过 ModLens 读出了全部内容：配文、互动数据（2.9K 回复、270K 点赞、5M 浏览）、连图片的 alt 文字都没放过。分辨率不够的地方，它老实说读不清，不瞎编。
+
+![纯文本 DeepSeek 通过 ModLens 读出推文截图的全部细节](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-app.png)
+
+批量也不在话下：一次丢三张插画进去，模型自己说「三张图我都用 modlens 视觉桥接逐张读取」，21 秒后逐张交卷，连画面的设计意图都点出来了。
+
+![纯文本 DeepSeek 通过 ModLens 一次读完三张图](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
 
 ## CLI 参数
 
@@ -84,19 +96,42 @@ npx @liustack/modlens -i workflow.jpg
 modlens -i <图片路径或 URL> [选项]
 ```
 
-| 参数 | 含义 | 默认值 |
-| :-- | :-- | :-- |
-| `-i, --input <path\|url>` | 要解析的图片（必填） | |
-| `-o, --output <path>` | 同时把 JSON 写入文件 | |
-| `-m, --model <name>` | provider 模型 | `gemini-3.6-flash-low` |
-| `-p, --provider <name>` | 视觉 provider | `antigravity-cli` |
-| `--prompt <text>` | 额外关注点，比如 `"重点提取表格"` | |
-| `--timeout <ms>` | provider 超时 | `180000` |
-| `--provider-bin <path>` | provider 可执行文件 | `agy` |
-| `--workdir <path>` | provider 运行目录 | |
+| 参数                      | 含义                              | 默认值                 |
+| :------------------------ | :-------------------------------- | :--------------------- |
+| `-i, --input <path\|url>` | 要解析的图片（必填）              |                        |
+| `-o, --output <path>`     | 同时把 JSON 写入文件              |                        |
+| `-m, --model <name>`      | provider 模型                     | `gemini-3.6-flash-low` |
+| `-p, --provider <name>`   | 视觉 provider                     | `antigravity-cli`      |
+| `--prompt <text>`         | 额外关注点，比如 `"重点提取表格"` |                        |
+| `--timeout <ms>`          | provider 超时                     | `180000`               |
+| `--provider-bin <path>`   | provider 可执行文件               | `agy`                  |
+| `--workdir <path>`        | provider 运行目录                 |                        |
 
 截图信息密集或文档难啃，换成 `-m gemini-3.1-pro-high`。输出契约见 [skills/modlens/references/output-schema.md](skills/modlens/references/output-schema.md)。
 
+## Provider 与配置
+
+ModLens 内置五个视觉 provider，默认还是 `antigravity-cli`：零 key，纯免费额度。
+
+| Provider | 需要什么 | 速度 | 说明 |
+| :-- | :-- | :-- | :-- |
+| `antigravity-cli`（默认） | `agy` 登录过 | 15-40 秒 | 免费额度，完整 agent 循环 |
+| `gemini-api` | 免费 AI Studio key | 5-10 秒 | 最快的免费路线，服务端强制 schema |
+| `openai` | baseUrl + apiKey + model | 看端点 | 任何 OpenAI 兼容的多模态端点（qwen-vl、GLM 等） |
+| `anthropic` | `ANTHROPIC_API_KEY` | 几秒 | 默认 Claude Haiku，强制工具调用保 schema |
+| `claude-cli` | Claude Code 已登录 | 20-45 秒 | 零 key，吃你的 Claude 订阅额度，只放行 Read 工具 |
+
+配置放在 `~/.modlens/config.json`，环境变量能盖过它（`GEMINI_API_KEY`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`ANTHROPIC_API_KEY`），CLI 参数最大。
+
+```bash
+modlens config init                          # 生成配置骨架
+modlens config set gemini-api.apiKey <key>   # 落盘即 0600 权限
+modlens config show                          # key 打码显示
+modlens config set provider gemini-api       # 换默认 provider
+```
+
+免费 Gemini key 去 [aistudio.google.com](https://aistudio.google.com) 领，三分钟，不要信用卡。嫌麻烦就直接跟你的 agent 说一句「帮我把 Gemini key 配进 modlens」，让它自己跑命令。
+
 ## 在 Codex 里用（DeepSeek 等纯文本模型）
 
 Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官方集成文档](https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/codex)配好：它的 `models.json` 把 deepseek-v4-flash 声明成纯文本（`input_modalities: ["text"]`），这一行就是打通下面整条链路的钥匙。
@@ -104,9 +139,7 @@ Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官
 有个坑要注意：声明纯文本之后，Codex TUI 会**直接拦下 Ctrl+V 粘贴图片**（报错 `Model deepseek-v4-flash does not support image inputs`），闸门卡在输入框那一层，图片压根到不了消息里。能用的招数有两个，都拿 deepseek-v4-flash 端到端验证过：
 
 - **把图片文件拖进终端**，或者手打路径。路径以纯文本形式落进消息，modlens skill 接着从这里接手。
-- 用 `codex exec -i 图片.png "..."` 附件方式：Codex 在内核层就把像素剥掉了，但留了一个 `<image name=[Image #1] path="/tmp/....png">` 文本标签，skill 从这个标签里把路径抠出来。
-
-不配 `models.json`（裸的自定义模型配置）的话，Codex 会默认你的模型能看图，把图片原样发过去，能不能扛住全看服务商脾气好不好。拖文件这一招，换到哪个宿主都稳。
+- 用 `codex exec -i 图片.png "..."` skill 从这里把路径抠出来。
 
 ## 为什么外挂，而不是换多模态模型？
 
@@ -116,11 +149,11 @@ Codex 只认 Responses API，DeepSeek 官方端点原生支持。先照着[官
 
 姊妹项目 ModSearch 用同一招补上联网搜索和网页抓取：[liustack/modsearch](https://github.com/liustack/modsearch)。
 
-## 用 liustack 打造
+## 插入一条硬广告
 
-ModLens v2 从需求成形、编码到交付，全程用 **[liustack](https://github.com/liustack/liustack)** 跑完。四个 Agent Skills，一个闭环：动手前 `shaping` 捋清楚，编码时 `coding` 上纪律，出问题 `dig` 挖根因，交接时 `snapshot` 留快照。比 Superpowers 更轻，也更锋利。
+本项目由 LIUSTACK Skills 驱动，ModLens v2 从需求成形、编码到交付，全程用 **[liustack](https://github.com/liustack/liustack)** 驱动：动手前 `shaping` 捋清楚，编码时 `coding` 上纪律，出问题 `dig` 挖根因，交接时 `snapshot` 留快照。比 Superpowers 更轻，也更强。
 
-**ModLens 给你的模型装上眼睛，liustack 给你的整个工作流装上纪律：**
+**ModLens 给你的模型装上眼睛，LIUSTACK Skills 给你的开发工作流装上翅膀：**
 
 ```bash
 npx -y skills add liustack/liustack -g
@@ -130,8 +163,8 @@ npx -y skills add liustack/liustack -g
 
 ## 安全说明
 
-- ModLens 调用 `agy` 时带上 `--dangerously-skip-permissions`，因为 print 模式不带这个参数就不执行工具调用。提示词已经把 agent 限定在只读那一张图，并要求把图片内容当数据看，绝不当指令执行。即便如此，也只解析你自己敢打开的图片，尽量在沙箱化的工作目录里跑。
-- 视觉输出是证据，不是圣旨。引擎读不准的地方会进 `uncertainty`，而不是被编出来凑数。v2 把像素坐标和置信度分数都删了，因为模型会瞎编这两样。
+- ModLens 调用 `agy` 时带上 `--dangerously-skip-permissions`，因为 prompt/print 模式不带这个参数在某些场景会失败。提示词已经把 agent 限定在只读那一张图，并要求把图片内容当数据看，绝不当指令执行。即便如此，也只解析你自己敢打开的图片，尽量在沙箱化的工作目录里跑。
+- 视觉输出是证据，引擎读不准的地方会进 `uncertainty`，而不是被编出来凑数。v2 把像素坐标和置信度分数都删了，因为模型会瞎编这两样。
 
 ## 免责声明
 

package/dist/main.js

@@ -3,8 +3,121 @@ import { Command } from "commander";
 import * as fs from "fs";
 import * as path from "path";
 import { spawn } from "child_process";
+import * as os from "os";
+const CONFIG_DIR = path.join(os.homedir(), ".modlens");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+const ENV_BINDINGS = {
+  "gemini-api": { apiKey: "GEMINI_API_KEY" },
+  openai: { apiKey: "OPENAI_API_KEY", baseUrl: "OPENAI_BASE_URL" },
+  anthropic: { apiKey: "ANTHROPIC_API_KEY", baseUrl: "ANTHROPIC_BASE_URL" }
+};
+function loadConfigFile(configPath = CONFIG_PATH) {
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, "utf-8");
+  } catch {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return {};
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(
+      `Failed to parse ${configPath}: ${error.message}. Fix or delete the file.`
+    );
+  }
+}
+function defaultProviderName(config2) {
+  return config2.provider?.trim() || "antigravity-cli";
+}
+function resolveProviderSettings(providerName, config2, env = process.env) {
+  const fromFile = config2.providers?.[providerName] ?? {};
+  const bindings = ENV_BINDINGS[providerName] ?? {};
+  const settings = { ...fromFile };
+  for (const [field, envName] of Object.entries(bindings)) {
+    const value = env[envName]?.trim();
+    if (value) {
+      settings[field] = value;
+    }
+  }
+  return settings;
+}
+function setConfigValue(dottedKey, value, configPath = CONFIG_PATH) {
+  const config2 = loadConfigFile(configPath);
+  if (dottedKey === "provider") {
+    config2.provider = value;
+  } else {
+    const dot = dottedKey.indexOf(".");
+    if (dot <= 0 || dot === dottedKey.length - 1) {
+      throw new Error(
+        `Invalid config key: ${dottedKey}. Use "provider" or "<provider>.<apiKey|baseUrl|model>".`
+      );
+    }
+    const providerName = dottedKey.slice(0, dot);
+    const field = dottedKey.slice(dot + 1);
+    if (!["apiKey", "baseUrl", "model"].includes(field)) {
+      throw new Error(`Unknown config field: ${field}. Use apiKey, baseUrl, or model.`);
+    }
+    config2.providers ??= {};
+    config2.providers[providerName] ??= {};
+    config2.providers[providerName][field] = value;
+  }
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(config2, null, 2)}
+`, { mode: 384 });
+  try {
+    fs.chmodSync(configPath, 384);
+  } catch {
+  }
+}
+const CONFIG_TEMPLATE = {
+  provider: "antigravity-cli",
+  providers: {
+    "antigravity-cli": { model: "gemini-3.6-flash-low" },
+    "gemini-api": { apiKey: "", model: "gemini-3.6-flash" },
+    openai: { baseUrl: "", apiKey: "", model: "" },
+    anthropic: { apiKey: "", model: "claude-haiku-4-5-20251001" },
+    "claude-cli": { model: "haiku" }
+  }
+};
+function initConfigFile(configPath = CONFIG_PATH, force = false) {
+  if (!force && fs.existsSync(configPath)) {
+    throw new Error(`${configPath} already exists. Use --force to overwrite.`);
+  }
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(CONFIG_TEMPLATE, null, 2)}
+`, { mode: 384 });
+  try {
+    fs.chmodSync(configPath, 384);
+  } catch {
+  }
+}
+function renderConfig(config2) {
+  const masked = {
+    ...config2,
+    providers: Object.fromEntries(
+      Object.entries(config2.providers ?? {}).map(([name, settings]) => [
+        name,
+        {
+          ...settings,
+          ...settings.apiKey ? { apiKey: maskKey(settings.apiKey) } : {}
+        }
+      ])
+    )
+  };
+  return JSON.stringify(masked, null, 2);
+}
+function maskKey(key) {
+  if (key.length <= 8) {
+    return "****";
+  }
+  return `${key.slice(0, 6)}...${key.slice(-2)}`;
+}
 function buildVisionPrompt(options) {
-  const readInstruction = options.imageKind === "remote" ? `Fetch the image at this URL and analyze it: ${options.imageSource}` : `Read the image file at this path and analyze it: ${options.imageSource}`;
+  const readInstruction = options.imageKind === "inline" ? "Analyze the image attached to this message." : options.imageKind === "remote" ? `Fetch the image at this URL and analyze it: ${options.imageSource}` : `Read the image file at this path and analyze it: ${options.imageSource}`;
   const basePrompt = `${readInstruction}
 
 You are a vision parsing engine for a text-only LLM.
@@ -157,11 +270,11 @@ function buildAntigravityInvocation(options) {
   };
 }
 function parseAntigravityOutput(stdout) {
-  const envelope = parseEnvelope(stdout);
+  const envelope = parseEnvelope$1(stdout);
   if (envelope.status && envelope.status !== "SUCCESS") {
     throw new Error(`Antigravity CLI reported status ${envelope.status}.`);
   }
-  const result = envelope.structured_output ?? (typeof envelope.response === "string" ? tryParseJson(envelope.response) : null);
+  const result = envelope.structured_output ?? (typeof envelope.response === "string" ? tryParseJson$1(envelope.response) : null);
   if (result === null || result === void 0) {
     throw new Error(
       "Antigravity CLI output contains no structured result. Check that the model finished the task (auth, quota, timeout)."
@@ -176,14 +289,14 @@ function parseAntigravityOutput(stdout) {
     }
   };
 }
-function parseEnvelope(stdout) {
+function parseEnvelope$1(stdout) {
   const trimmed = stdout.trim();
-  let parsed = tryParseJson(trimmed);
+  let parsed = tryParseJson$1(trimmed);
   if (parsed === null) {
     const firstBrace = trimmed.indexOf("{");
     const lastBrace = trimmed.lastIndexOf("}");
     if (firstBrace >= 0 && lastBrace > firstBrace) {
-      parsed = tryParseJson(trimmed.slice(firstBrace, lastBrace + 1));
+      parsed = tryParseJson$1(trimmed.slice(firstBrace, lastBrace + 1));
     }
   }
   if (!parsed || typeof parsed !== "object") {
@@ -191,7 +304,7 @@ function parseEnvelope(stdout) {
   }
   return parsed;
 }
-function tryParseJson(text) {
+function tryParseJson$1(text) {
   try {
     return JSON.parse(text);
   } catch {
@@ -204,19 +317,408 @@ const antigravityCliProvider = {
   buildInvocation: buildAntigravityInvocation,
   parseOutput: parseAntigravityOutput
 };
+const MIME_BY_EXT = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".heic": "image/heic",
+  ".heif": "image/heif"
+};
+function mimeTypeFor(source) {
+  const ext = path.extname(new URL(source, "file:///").pathname).toLowerCase();
+  return MIME_BY_EXT[ext] ?? "image/jpeg";
+}
+function readLocalImageBase64(filePath) {
+  const data = fs.readFileSync(filePath).toString("base64");
+  return { data, mimeType: mimeTypeFor(filePath) };
+}
+async function fetchRemoteImageBase64(url, timeoutMs) {
+  const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!response.ok) {
+    throw new Error(`Failed to download image (${response.status}): ${url}`);
+  }
+  const buffer = Buffer.from(await response.arrayBuffer());
+  const contentType = response.headers.get("content-type")?.split(";")[0]?.trim();
+  return {
+    data: buffer.toString("base64"),
+    mimeType: contentType?.startsWith("image/") ? contentType : mimeTypeFor(url)
+  };
+}
+function extractJson(text) {
+  const trimmed = text.trim();
+  const direct = tryParse(trimmed);
+  if (direct !== null) {
+    return direct;
+  }
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed);
+  if (fenced) {
+    const parsed = tryParse(fenced[1].trim());
+    if (parsed !== null) {
+      return parsed;
+    }
+  }
+  const first = trimmed.indexOf("{");
+  const last = trimmed.lastIndexOf("}");
+  if (first >= 0 && last > first) {
+    return tryParse(trimmed.slice(first, last + 1));
+  }
+  return null;
+}
+function tryParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+const ANTHROPIC_DEFAULT_MODEL = "claude-haiku-4-5-20251001";
+const DEFAULT_BASE_URL$1 = "https://api.anthropic.com";
+const TOOL_NAME = "report_vision_evidence";
+async function executeAnthropicApi(options) {
+  const apiKey = options.settings?.apiKey;
+  if (!apiKey) {
+    throw new Error(
+      "anthropic provider needs an API key. Set ANTHROPIC_API_KEY, or run: modlens config set anthropic.apiKey <key>"
+    );
+  }
+  const model = options.model || options.settings?.model || ANTHROPIC_DEFAULT_MODEL;
+  const baseUrl = (options.settings?.baseUrl || DEFAULT_BASE_URL$1).replace(/\/$/, "");
+  const imageSource = options.imageKind === "remote" ? { type: "url", url: options.imageSource } : (() => {
+    const image = readLocalImageBase64(options.imageSource);
+    return {
+      type: "base64",
+      media_type: image.mimeType,
+      data: image.data
+    };
+  })();
+  const prompt = `${buildVisionPrompt({
+    imageSource: options.imageSource,
+    imageKind: "inline",
+    extraPrompt: options.extraPrompt
+  })}
+
+Report your findings by calling the ${TOOL_NAME} tool.`;
+  const startedAt = Date.now();
+  const response = await fetch(`${baseUrl}/v1/messages`, {
+    method: "POST",
+    headers: {
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 4096,
+      tools: [
+        {
+          name: TOOL_NAME,
+          description: "Report the structured visual evidence extracted from the image.",
+          input_schema: VISION_RESULT_SCHEMA
+        }
+      ],
+      tool_choice: { type: "tool", name: TOOL_NAME },
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "image", source: imageSource },
+            { type: "text", text: prompt }
+          ]
+        }
+      ]
+    }),
+    signal: AbortSignal.timeout(options.timeoutMs)
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Anthropic API error ${response.status}: ${truncate$3(body)}`);
+  }
+  const payload = await response.json();
+  const toolUse = payload.content?.find((block) => block.type === "tool_use");
+  if (!toolUse?.input) {
+    throw new Error("Anthropic API returned no tool_use block.");
+  }
+  return {
+    result: toolUse.input,
+    meta: {
+      conversationId: null,
+      durationSeconds: (Date.now() - startedAt) / 1e3,
+      usage: payload.usage ?? null
+    }
+  };
+}
+function truncate$3(text) {
+  return text.length > 300 ? `${text.slice(0, 300)}...` : text;
+}
+const anthropicApiProvider = {
+  name: "anthropic",
+  defaultModel: ANTHROPIC_DEFAULT_MODEL,
+  execute: executeAnthropicApi
+};
+const CLAUDE_CLI_DEFAULT_MODEL = "haiku";
+function buildClaudeCliInvocation(options) {
+  if (options.imageKind === "remote") {
+    throw new Error(
+      "claude-cli provider reads local files only. Download the image first, or use -p gemini-api for remote URLs."
+    );
+  }
+  const prompt = buildVisionPrompt({
+    imageSource: options.imageSource,
+    imageKind: "local",
+    extraPrompt: options.extraPrompt
+  });
+  const args = [
+    "-p",
+    prompt,
+    "--output-format",
+    "json",
+    "--json-schema",
+    visionResultSchemaJson(),
+    "--allowedTools",
+    "Read",
+    "--model",
+    options.model || options.settings?.model || CLAUDE_CLI_DEFAULT_MODEL
+  ];
+  return {
+    command: options.providerBin || "claude",
+    args,
+    cwd: path.resolve(options.workdir || path.dirname(options.imageSource))
+  };
+}
+function parseClaudeCliOutput(stdout) {
+  const envelope = parseEnvelope(stdout);
+  if (envelope.is_error || envelope.subtype && envelope.subtype !== "success") {
+    throw new Error(
+      `Claude CLI reported ${envelope.subtype ?? "an error"}: ${truncate$2(envelope.result ?? "")}`
+    );
+  }
+  if (typeof envelope.result !== "string" || !envelope.result.trim()) {
+    throw new Error("Claude CLI output contains no result. Check login state (run: claude).");
+  }
+  let result;
+  try {
+    result = JSON.parse(envelope.result);
+  } catch {
+    throw new Error(`Claude CLI returned non-JSON result: ${truncate$2(envelope.result)}`);
+  }
+  return {
+    result,
+    meta: {
+      conversationId: envelope.session_id ?? null,
+      durationSeconds: typeof envelope.duration_ms === "number" ? envelope.duration_ms / 1e3 : null,
+      usage: envelope.usage ?? null
+    }
+  };
+}
+function parseEnvelope(stdout) {
+  const trimmed = stdout.trim();
+  let parsed = tryParseJson(trimmed);
+  if (parsed === null) {
+    const firstBrace = trimmed.indexOf("{");
+    const lastBrace = trimmed.lastIndexOf("}");
+    if (firstBrace >= 0 && lastBrace > firstBrace) {
+      parsed = tryParseJson(trimmed.slice(firstBrace, lastBrace + 1));
+    }
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Failed to parse Claude CLI JSON output.");
+  }
+  return parsed;
+}
+function tryParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function truncate$2(text) {
+  return text.length > 300 ? `${text.slice(0, 300)}...` : text;
+}
+const claudeCliProvider = {
+  name: "claude-cli",
+  defaultModel: CLAUDE_CLI_DEFAULT_MODEL,
+  buildInvocation: buildClaudeCliInvocation,
+  parseOutput: parseClaudeCliOutput
+};
+const GEMINI_API_DEFAULT_MODEL = "gemini-3.6-flash";
+const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com";
+async function executeGeminiApi(options) {
+  const apiKey = options.settings?.apiKey;
+  if (!apiKey) {
+    throw new Error(
+      "gemini-api provider needs an API key. Set GEMINI_API_KEY, or run: modlens config set gemini-api.apiKey <key> (free key: https://aistudio.google.com)"
+    );
+  }
+  const model = options.model || options.settings?.model || GEMINI_API_DEFAULT_MODEL;
+  const baseUrl = (options.settings?.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+  const image = options.imageKind === "remote" ? await fetchRemoteImageBase64(options.imageSource, options.timeoutMs) : readLocalImageBase64(options.imageSource);
+  const prompt = buildVisionPrompt({
+    imageSource: options.imageSource,
+    imageKind: "inline",
+    extraPrompt: options.extraPrompt
+  });
+  const startedAt = Date.now();
+  const response = await fetch(`${baseUrl}/v1beta/models/${model}:generateContent`, {
+    method: "POST",
+    headers: {
+      "x-goog-api-key": apiKey,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      contents: [
+        {
+          parts: [
+            { inline_data: { mime_type: image.mimeType, data: image.data } },
+            { text: prompt }
+          ]
+        }
+      ],
+      generationConfig: {
+        responseMimeType: "application/json",
+        responseJsonSchema: VISION_RESULT_SCHEMA
+      }
+    }),
+    signal: AbortSignal.timeout(options.timeoutMs)
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`Gemini API error ${response.status}: ${truncate$1(body)}`);
+  }
+  const payload = await response.json();
+  const text = payload.candidates?.[0]?.content?.parts?.map((part) => part.text ?? "").join("");
+  if (!text) {
+    throw new Error("Gemini API returned no text candidate.");
+  }
+  let result;
+  try {
+    result = JSON.parse(text);
+  } catch {
+    throw new Error(`Gemini API returned non-JSON output: ${truncate$1(text)}`);
+  }
+  return {
+    result,
+    meta: {
+      conversationId: null,
+      durationSeconds: (Date.now() - startedAt) / 1e3,
+      usage: payload.usageMetadata ?? null
+    }
+  };
+}
+function truncate$1(text) {
+  return text.length > 300 ? `${text.slice(0, 300)}...` : text;
+}
+const geminiApiProvider = {
+  name: "gemini-api",
+  defaultModel: GEMINI_API_DEFAULT_MODEL,
+  execute: executeGeminiApi
+};
+async function executeOpenaiCompat(options) {
+  const apiKey = options.settings?.apiKey;
+  const baseUrl = options.settings?.baseUrl?.replace(/\/$/, "");
+  const model = options.model || options.settings?.model;
+  if (!apiKey || !baseUrl || !model) {
+    throw new Error(
+      "openai provider needs baseUrl, apiKey, and model. Set OPENAI_BASE_URL and OPENAI_API_KEY, or run: modlens config set openai.baseUrl <url> / openai.apiKey <key> / openai.model <name>"
+    );
+  }
+  const imageUrl = options.imageKind === "remote" ? options.imageSource : toDataUrl(readLocalImageBase64(options.imageSource));
+  const prompt = `${buildVisionPrompt({
+    imageSource: options.imageSource,
+    imageKind: "inline",
+    extraPrompt: options.extraPrompt
+  })}
+
+Respond with ONE JSON object only, no markdown fences, no commentary. Fill this exact structure with your findings from the image (do not repeat this template literally, replace every value):
+{"summary":"one paragraph describing the image","ocr":{"full_text":"all visible text","lines":[{"text":"one line","language":"en"}]},"layout":{"regions":[{"type":"title|subtitle|paragraph|list|table|chart|form|code|image|icon|other","reading_order":1,"text":"region text"}]},"semantics":{"scene":"what kind of scene","intent":"what the image is for","entities":[{"name":"entity","type":"kind","evidence":"where seen"}],"relations":[{"subject":"a","predicate":"relates to","object":"b"}]},"visual":{"dominant_colors":["color"],"style":"visual style","notes":["notable visual detail"]},"uncertainty":["anything unreadable or ambiguous"]}`;
+  const startedAt = Date.now();
+  const response = await fetch(`${baseUrl}/chat/completions`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      model,
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "image_url", image_url: { url: imageUrl } },
+            { type: "text", text: prompt }
+          ]
+        }
+      ]
+    }),
+    signal: AbortSignal.timeout(options.timeoutMs)
+  });
+  if (!response.ok) {
+    const body = await response.text();
+    throw new Error(`OpenAI-compatible API error ${response.status}: ${truncate(body)}`);
+  }
+  const payload = await response.json();
+  const text = payload.choices?.[0]?.message?.content;
+  if (!text) {
+    throw new Error("OpenAI-compatible API returned no message content.");
+  }
+  const result = extractJson(text);
+  if (result === null) {
+    throw new Error(`OpenAI-compatible API returned non-JSON output: ${truncate(text)}`);
+  }
+  const shaped = result;
+  if (typeof shaped.summary !== "string" || typeof shaped.ocr !== "object") {
+    throw new Error(
+      `OpenAI-compatible API returned JSON that does not match the vision schema (missing summary/ocr). Retry, or switch to gemini-api / anthropic for enforced schemas. Got: ${truncate(text)}`
+    );
+  }
+  return {
+    result,
+    meta: {
+      conversationId: null,
+      durationSeconds: (Date.now() - startedAt) / 1e3,
+      usage: payload.usage ?? null
+    }
+  };
+}
+function toDataUrl(image) {
+  return `data:${image.mimeType};base64,${image.data}`;
+}
+function truncate(text) {
+  return text.length > 300 ? `${text.slice(0, 300)}...` : text;
+}
+const openaiCompatProvider = {
+  name: "openai",
+  defaultModel: "",
+  execute: executeOpenaiCompat
+};
 const PROVIDERS = {
   "antigravity-cli": antigravityCliProvider,
   antigravity: antigravityCliProvider,
-  agy: antigravityCliProvider
+  agy: antigravityCliProvider,
+  "gemini-api": geminiApiProvider,
+  gemini: geminiApiProvider,
+  openai: openaiCompatProvider,
+  "openai-compat": openaiCompatProvider,
+  anthropic: anthropicApiProvider,
+  claude: anthropicApiProvider,
+  "claude-cli": claudeCliProvider,
+  "claude-code": claudeCliProvider
 };
 function resolveProvider(providerName = "antigravity-cli") {
   const normalized = providerName.trim().toLowerCase();
   const provider = PROVIDERS[normalized];
   if (!provider) {
-    throw new Error(`Unsupported provider: ${providerName}`);
+    throw new Error(
+      `Unsupported provider: ${providerName}. Available: ${listProviders().join(", ")}`
+    );
   }
   return provider;
 }
+function listProviders() {
+  return [...new Set(Object.values(PROVIDERS).map((provider) => provider.name))];
+}
 const DEFAULT_TIMEOUT_MS = 18e4;
 const KILL_GRACE_MS = 3e4;
 async function analyzeImage(options) {
@@ -224,20 +726,35 @@ async function analyzeImage(options) {
   if (resolvedInput.kind === "local") {
     validateInputFile(resolvedInput.source);
   }
-  const provider = resolveProvider(options.provider);
+  const config2 = options.config ?? loadConfigFile();
+  const provider = resolveProvider(options.provider || defaultProviderName(config2));
+  const settings = resolveProviderSettings(provider.name, config2);
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const model = options.model || provider.defaultModel;
-  const invocation = provider.buildInvocation({
+  const model = options.model || settings.model || provider.defaultModel;
+  const providerOptions = {
     imageSource: resolvedInput.source,
     imageKind: resolvedInput.kind,
     model,
     extraPrompt: options.prompt,
     providerBin: options.providerBin,
     workdir: options.workdir,
-    timeoutMs
-  });
-  const commandResult = await runCommand(provider.name, invocation, timeoutMs + KILL_GRACE_MS);
-  const parsed = provider.parseOutput(commandResult.stdout);
+    timeoutMs,
+    settings
+  };
+  let parsed;
+  if (provider.execute) {
+    parsed = await provider.execute(providerOptions);
+  } else if (provider.buildInvocation && provider.parseOutput) {
+    const invocation = provider.buildInvocation(providerOptions);
+    const commandResult = await runCommand(
+      provider.name,
+      invocation,
+      timeoutMs + KILL_GRACE_MS
+    );
+    parsed = provider.parseOutput(commandResult.stdout);
+  } else {
+    throw new Error(`Provider ${provider.name} implements neither execute nor buildInvocation.`);
+  }
   return {
     image: resolvedInput.source,
     provider: provider.name,
@@ -327,7 +844,8 @@ function runCommand(providerName, invocation, timeoutMs) {
   });
 }
 const program = new Command();
-program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.0.0").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name (default: gemini-3.6-flash-low)").option("-p, --provider <name>", "Vision provider name", "antigravity-cli").option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider command").action(async (options) => {
+program.name("modlens").description("Plug-in vision for text-only LLMs: image in, structured JSON evidence out").version("2.2.0");
+program.command("analyze", { isDefault: true }).description("Analyze an image into structured JSON evidence (default command)").requiredOption("-i, --input <path|url>", "Input image path or https URL").option("-o, --output <path>", "Write result JSON to a file").option("-m, --model <name>", "Provider model name").option("-p, --provider <name>", `Vision provider (${listProviders().join(", ")})`).option("--prompt <text>", "Extra focus for this image").option("--timeout <ms>", "Provider timeout in milliseconds", "180000").option("--provider-bin <path>", "Provider binary path (default: agy)").option("--workdir <path>", "Working directory for the provider").action(async (options) => {
   try {
     const timeoutMs = Number.parseInt(options.timeout, 10);
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
@@ -358,4 +876,46 @@ program.name("modlens").description("Plug-in vision for text-only LLMs: image in
     process.exit(1);
   }
 });
+const config = program.command("config").description(`Manage ${CONFIG_PATH} (providers, keys, models)`);
+config.command("init").description(`Create a starter config at ${CONFIG_PATH}`).option("--force", "Overwrite an existing config file").action((options) => {
+  try {
+    initConfigFile(CONFIG_PATH, Boolean(options.force));
+    process.stdout.write(
+      `Created ${CONFIG_PATH}
+Fill in the apiKey fields you need, or use: modlens config set <provider>.apiKey <key>
+`
+    );
+  } catch (error) {
+    process.stderr.write(
+      `Error: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    process.exit(1);
+  }
+});
+config.command("set <key> <value>").description("Set a value, e.g. modlens config set gemini-api.apiKey <key>").action((key, value) => {
+  try {
+    setConfigValue(key, value);
+    process.stdout.write(`Saved ${key} to ${CONFIG_PATH}
+`);
+  } catch (error) {
+    process.stderr.write(
+      `Error: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    process.exit(1);
+  }
+});
+config.command("show").description("Print the effective config with API keys masked").action(() => {
+  try {
+    process.stdout.write(`${renderConfig(loadConfigFile())}
+`);
+  } catch (error) {
+    process.stderr.write(
+      `Error: ${error instanceof Error ? error.message : String(error)}
+`
+    );
+    process.exit(1);
+  }
+});
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {

package/skills/modlens/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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: OCR text, layout, semantics, visual clues."
+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: OCR text, layout, 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
 ---
@@ -12,6 +12,7 @@ Use this skill when:
 - The user provides an image path or image URL and asks anything about it
 - The active model has no native vision (text-only model in a coding agent)
 - You need OCR text, layout, or chart/document structure as evidence before reasoning
+- The user asks how to configure modlens, get an API key for it, or switch its provider: follow `references/configure.md` and run the commands for them
 
 Do not use this skill for:
 
@@ -22,23 +23,30 @@ Do not use this skill for:
 
 ```bash
 modlens --version
-agy --version
 ```
 
 If `modlens` is missing, run it via `npx @liustack/modlens` instead.
 
-If `agy` (Antigravity CLI) is missing:
+ModLens supports five vision providers. Check what is configured:
 
 ```bash
-curl -fsSL https://antigravity.google/cli/install.sh | bash
+modlens config show
 ```
 
-If `agy` is installed but not signed in, ask the user to run `agy` once in a terminal and complete the Google sign-in. This cannot be done non-interactively.
+- **antigravity-cli** (default, no key needed): needs `agy` installed and signed in. If `agy --version` fails: `curl -fsSL https://antigravity.google/cli/install.sh | bash`, then ask the user to run `agy` once and complete the Google sign-in (cannot be done non-interactively).
+- **gemini-api**: needs `GEMINI_API_KEY` env or `modlens config set gemini-api.apiKey <key>` (free key from https://aistudio.google.com).
+- **openai**: any OpenAI-compatible multimodal endpoint; needs baseUrl + apiKey + model via env (`OPENAI_BASE_URL`, `OPENAI_API_KEY`) or `modlens config set openai.<field> <value>`.
+- **anthropic**: needs `ANTHROPIC_API_KEY` env or config; defaults to Claude Haiku.
+- **claude-cli**: rides an existing Claude Code login (`claude`), no key, Read-only tool permissions, local files only.
+
+`modlens config init` writes a starter config to `~/.modlens/config.json` when none exists. Full setup recipes per provider: `references/configure.md`.
 
 ## Command
 
 ```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>
 ```
@@ -49,8 +57,7 @@ Optional flags:
 modlens -i <image> -o <output.json> -m <model> --prompt "<extra focus>" --timeout <ms>
 ```
 
-- Default model is `gemini-3.6-flash-low` (fastest, cheapest on quota). Use `-m gemini-3.1-pro-high` for dense or hard images.
-- A run typically takes 15-40 seconds. Do not treat silence as a hang before the timeout.
+Speed expectations: `gemini-api` typically 5-10 seconds, `antigravity-cli` 15-40 seconds and `claude-cli` 20-45 seconds (full agent loops), `openai`/`anthropic` depend on the endpoint. For dense or hard images on antigravity-cli, try `-m gemini-3.1-pro-high`.
 
 ## Finding the image path in the chat
 
@@ -80,10 +87,11 @@ Top level: `{ image, provider, result, meta }`. Inside `result`:
 - `visual`: colors and style clues
 - `uncertainty[]`: what the vision engine was unsure about
 
-Structure is enforced by a JSON schema at the provider level. Full schema: `references/output-schema.md`.
+Structure is enforced by schema on antigravity-cli and claude-cli (`--json-schema`), gemini-api (`responseJsonSchema`), and anthropic (forced tool call). The openai route uses a template prompt plus shape validation and fails loudly on mismatch.
 
 ## Failure Handling
 
-- Exit code 1 with `Provider CLI not found`: Antigravity CLI is not installed. Install it, then retry.
-- `no structured result` or auth-flavored errors: ask the user to run `agy` and sign in, or check quota.
+- `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.
+- `does not match the vision schema` on the openai route: retry once, then switch to `-p gemini-api` or `-p anthropic` for enforced schemas.
 - Timeouts: retry once with `--timeout 300000`. If it still fails, report the exact error instead of fabricating image content.

package/skills/modlens/references/configure.md

@@ -0,0 +1,85 @@
+# Configuring ModLens
+
+Read this when the user asks how to set up, configure, or switch ModLens providers. Prefer running the commands for the user over explaining them.
+
+## Where config lives
+
+`~/.modlens/config.json`, managed by the CLI. Precedence: CLI flags > environment variables > config file > built-in defaults. The default provider with zero config is `antigravity-cli`.
+
+```bash
+modlens config init                     # write a starter config (refuses to overwrite; --force to redo)
+modlens config show                     # effective file, API keys masked
+modlens config set provider <name>      # change the default provider
+modlens config set <provider>.<field> <value>   # fields: apiKey, baseUrl, model
+```
+
+`config set` writes the file with 0600 permissions.
+
+## Provider setup recipes
+
+### antigravity-cli (default, free, no key)
+
+Needs Antigravity CLI installed and signed in:
+
+```bash
+curl -fsSL https://antigravity.google/cli/install.sh | bash
+agy    # user must complete browser sign-in themselves, then exit
+```
+
+Any free Google account works; no Google AI Pro needed. Sign-in cannot be automated, ask the user to run `agy` once.
+
+### gemini-api (free key, fastest free route, 5-10s)
+
+1. The user creates a key at https://aistudio.google.com (three minutes, no credit card, free tier does not expire).
+2. Store it either way:
+
+```bash
+modlens config set gemini-api.apiKey <key>
+# or environment: export GEMINI_API_KEY=<key>
+```
+
+Default model `gemini-3.6-flash` has vision on the free tier (about 10-15 requests/min, 1500/day). Free-tier data may be used by Google to improve products; mention this if the user handles sensitive images.
+
+### openai (any OpenAI-compatible multimodal endpoint)
+
+Needs three values. Example for DashScope qwen:
+
+```bash
+modlens config set openai.baseUrl https://dashscope.aliyuncs.com/compatible-mode/v1
+modlens config set openai.apiKey <sk-key>
+modlens config set openai.model qwen3.6-27b
+```
+
+For official OpenAI: baseUrl `https://api.openai.com/v1`, a vision-capable model. Environment equivalents: `OPENAI_BASE_URL`, `OPENAI_API_KEY`. The model must be multimodal; text-only models will fail or hallucinate. This route has no server-side schema enforcement, so occasional shape failures are surfaced as explicit errors; retry or switch provider.
+
+### anthropic (Claude API key)
+
+```bash
+modlens config set anthropic.apiKey <sk-ant-key>
+# or: export ANTHROPIC_API_KEY=<key>
+```
+
+Default model is Claude Haiku (`claude-haiku-4-5-20251001`). Schema is enforced through a forced tool call.
+
+### claude-cli (Claude Code login, no key)
+
+Rides an existing `claude` sign-in, so it costs the user's Claude subscription quota, not a separate API bill. Requires Claude Code installed and logged in (`claude --version` to check). Runs with `--allowedTools Read` only. Local image files only; for remote URLs use gemini-api instead. Default model alias `haiku`.
+
+```bash
+modlens config set provider claude-cli   # make it the default if the user wants
+```
+
+## Choosing a provider for the user
+
+- Wants zero setup and free: `antigravity-cli` (needs agy sign-in, 15-40s per image).
+- Wants fast and free: `gemini-api` (three-minute key, 5-10s).
+- Already pays for Claude: `claude-cli` (no extra key) or `anthropic` (API billing).
+- Has a favorite multimodal endpoint (qwen, GLM, ...): `openai`.
+
+## Troubleshooting
+
+- Error names a missing env var or `config set` command: run exactly that.
+- `Provider CLI not found: agy`: install Antigravity CLI or switch provider.
+- `Claude CLI reported ...` or empty result: check `claude` login state.
+- openai route `does not match the vision schema`: retry once, then switch to gemini-api or anthropic.
+- `config init` refusing to run: the file exists; use `modlens config show` first, `--force` only if the user agrees to overwrite.