# Configuring ModLens

English | [中文](configure.zh-CN.md)

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 > this file > built-in defaults. A provider's settings come from one source, whole: since 3.17.0 the file is that source whenever it mentions the provider, and the bound environment variables are when it does not. With no `provider` set, runs walk the failover chain in order (an available `gemini-api` key is tried before the agent CLIs); a machine with nothing configured at all ends up on `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, proxy, extraBody, structuredOutput
modlens config set proxy http://127.0.0.1:7890          # default for every API provider
modlens config set openai.proxy ""                      # make one provider connect directly
```

`config set` writes the file with 0600 permissions.

## The file's exact shape

Everything lives under seven top-level keys, all optional. This example shows every supported key and field at once (a real file only needs what you use). 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",
  "cooldown": "on",
  "proxy": "http://127.0.0.1:7890",
  "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true, "grok": true },
  "saved": {
    "openai": {
      "dashscope": { "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-...", "model": "qwen3-vl-plus" }
    }
  },
  "guards": {
    "allowModels": ["deepseek-v4-*", "glm-5.2*", "*/glm-5.2*", "glm-5.3", "*/glm-5.3", "minimax-m2.5*", "qwen3-coder*"],
    "denyModels": ["glm-*v*", "*/glm-*v*", "glm-5.3-flash", "glm-5.3-flash-*", "glm-5.3-flash:*", "*/glm-5.3-flash", "*/glm-5.3-flash-*", "*/glm-5.3-flash:*", "deepseek-vl*"],
    "denyWhenUnknown": false
  },
  "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",
      "proxy": "http://127.0.0.1:7890",
      "extraBody": { "thinking": { "type": "disabled" } },
      "structuredOutput": true
    },
    "anthropic": {
      "apiKey": "sk-ant-...",
      "baseUrl": "https://api.anthropic.com",
      "model": "claude-haiku-4-5-20251001"
    },
    "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`, `kimi`/`kimi-code` for `kimi-cli`, `claude-code` for `claude-cli`). Empty or absent pins nothing: the failover chain decides, trying configured API providers before the agent CLIs.
- `cooldown`: `'on'` (default) or `'off'`. On, a quota-spent key is remembered in `~/.modlens/state.json` and tried last until it recovers (45 minutes by default, 24 hours for monthly HTTP 432/433, or the engine-reported `Resets in` clause). Off, that file is neither read nor written. `modlens state clear` forgets every cooldown.
- `proxy`: the default route for all API providers. When it is absent, `HTTPS_PROXY` or `HTTP_PROXY` supplies the default instead. `NO_PROXY` is honored on that environment route.
- `providers.<name>.proxy`: a three-state override. An absent field inherits the default above, an empty string forces a direct connection, and a non-empty URL selects a proxy for this provider alone. This lets an internal endpoint stay reachable when the shared proxy fails. To restore inheritance, remove the field from the file or choose the inherited route in the dsh settings card. `config show` renders the empty state as `direct`, and the card exposes all three choices without sending a stored proxy URL to the browser.
- `providers.<name>.<field>`: six fields exist, `apiKey`, `baseUrl`, `model`, `proxy`, `extraBody`, and `structuredOutput` (the openai route only). 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. `apiKey` accepts a comma-separated list. Requests use the configured order and rotate only after authentication, rate-limit, or quota failures. Other failures skip remaining keys and keep provider failover.
- `providers.<name>.extraBody`: a JSON object merged into the request body of the API providers (`gemini-api`, `openai`, `anthropic`), for whatever knobs that vendor has and modlens has no flag for. Turning thinking off is the usual reason, see the section below. Nested objects merge key by key, so adding one knob leaves the rest of that block alone. The fields carrying the image, the prompt, and each route's own enforcement machinery are refused with an error naming the field. `response_format` on the `openai` route is not one of them: setting it there deliberately replaces the schema modlens would otherwise send. The three CLI providers take no request body, so a run on `antigravity-cli`, `claude-cli` or `kimi-cli` ignores it and says so in `meta.warnings`.
- `providers.openai.structuredOutput`: `true` asks an OpenAI-compatible gateway to enforce the vision contract itself, as `response_format: json_schema` in the strict form those endpoints require. Off by default, since a gateway without structured-output support answers 400 for the field. A `response_format` you set in `extraBody` wins over it.
- `saved.openai.<label>`: named saved copies of the openai slot, written only by `modlens config save openai <label>` and swapped in whole by `modlens config use openai <label>`. Switching gateways used to mean overwriting `providers.openai` and losing the previous key; a saved copy is where it survives. `use` refuses to overwrite an active slot that no label holds (pass `--discard` to drop it deliberately), and nothing in resolution, guards, or the env bindings reads this section: the active slot stays the only openai route in any run.
- `guards`: the invocation guard, for people who run both text-only and vision-capable models through the same client. Both lists hold glob patterns (`*` and `?`, case-insensitive, matched against the model name and `provider/model`), set with `modlens config set guards.denyModels '["gemini-3*"]'` or `guards.allowModels` (a JSON array or a comma-separated list, empty clears). Two ways to express the same intent, pick the shorter list:
  - `denyModels` alone: everything runs the engine except the listed vision models. Right when text-only models are the majority of what you plug in.
  - `allowModels` non-empty (allowlist mode): only the listed models run the engine, every other identified model is denied. Right for the actual 2026 landscape, where text-only models are the short list. A deny pattern still wins over an allow match, so a broad allow can have its vision variants carved out, as in the example above: `glm-5.2*` and `*/glm-5.2*` cover the 5.2 line on bare and namespaced ids (`z-ai/glm-5.2:free`), `glm-5.3` and `*/glm-5.3` cover GLM-5.3 itself, while `glm-*v*` and `*/glm-*v*` catch `glm-5v-turbo`, `z-ai/glm-5.2v`, and `z-ai/glm-5.2-vision`, and the delimited `glm-5.3-flash` / `glm-5.3-flash-*` / `glm-5.3-flash:*` patterns (and the `*/` forms) catch `glm-5.3-flash`. The guard matches the id as stored, it does not strip a vendor prefix, so a namespaced text model needs its `*/` twin, and a namespaced vision variant needs its deny twin too. Do not write `glm-5.*` or `glm-5.3-flash*`: the first also matches `glm-5.3-flash`, the second also matches a run-on name like `glm-5.3-flashlight`. Anchor allow patterns tightly (`deepseek-v4-*`, not `deepseek*`) so a vendor's next multimodal generation falls off the list and steps aside until you have checked it.
  - List a model by what actually reaches it, not by what it could see: a multimodal model behind a gateway that strips images still needs modlens, and your session transcript records the model name the gateway reports. `modlens doctor`'s Guard section shows the rules and a live verdict for checking the result.
  - `denyWhenUnknown` (default `false`) decides what happens when no signal identifies the active model, in either mode: `false` proceeds, `true` denies. The active model is detected from, strongest first: the `MODLENS_MODEL` env var (`none` means "treat as unknown"), the harness's session storage, the `--model` self-report.
- `GEMINI_API_KEY`, `GEMINI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` configure a provider this file says nothing about, and are ignored entirely for one it does. They used to merge field by field, which built pairings that existed nowhere: a baseUrl and an apiKey are one credential. The key variables accept a comma-separated list the same way the file field does. modlens still reads `MODLENS_HARNESS` (paste-recovery and guard scope), `MODLENS_MODEL` (guard override, see `guards`), and the fingerprints harnesses inject themselves, which pin the guard's storage lookup to the current session: `CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, plus the presence markers harness detection relies on (`CLAUDECODE`, `PI_CODING_AGENT`, `CODEX_SANDBOX`).
- `reuse.<claude|codex|opencode|pi|grok>`: per-harness grants for spending other local logins, written by the onboarding conversation (`references/onboard.md`). `true` lets reads reuse that harness (pi credentials join the inline region with every guard intact; a signed-in Codex, an OpenCode vision model, or pi driven directly join the agent region before `claude-cli`), `false` records a refusal so the user is never re-asked, absent means never asked and nothing runs. `claude` absent counts as granted: `claude-cli` predates this model as a built-in provider, and `reuse.claude false` removes it from the chain (`-p claude-cli` still pins). Reused engines get no priority over the user's own: regions order by speed class only. Every reused answer adds a `meta.warnings` line naming whose quota it spent, and `modlens doctor`'s Reuse section shows each harness's decision plus what discovery found (probe results cache for 6 hours in `~/.modlens/auto-cache.json`; doctor always re-probes). Set with `modlens config set reuse.codex true` (empty clears back to never-asked).
- 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)

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>
# value omitted: a hidden prompt, so the key skips argv, shell history, and this chat
modlens config set gemini-api.apiKey
```

Offer the hidden prompt first when the user is at their own terminal. Most users paste the key into the chat because it is convenient, and that works too: take it and store it. The prompt is for the ones who would rather not.

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
```

`baseUrl` is required, official OpenAI included (`https://api.openai.com/v1`): this route serves any compatible endpoint, and guessing one would send a key meant for another vendor, and the image beside it, somewhere the user never named. The model must be multimodal; text-only models will fail or hallucinate.

This route enforces nothing server-side by default, so a weaker model can answer with half the contract and the run fails with an explicit error. If that happens, ask the gateway to enforce it:

```bash
modlens config set openai.structuredOutput true
```

The contract goes out as `response_format: json_schema` in strict form, derived from the schema modlens checks against. Off by default because a gateway without structured-output support answers 400 for the field, so turn it back off if the endpoint refuses it. Turning thinking off (below) makes the shape failures more likely, so the two often go together.

### anthropic (Claude API key)

```bash
modlens config set anthropic.apiKey <sk-ant-key>
```

Default model is Claude Haiku (`claude-haiku-4-5-20251001`). Schema is enforced through a forced tool call.

**The `ANTHROPIC_BASE_URL` trap is defused.** modlens used to bind that variable to `anthropic.baseUrl` field by field, so a shell that routed Claude Code through a text-only gateway silently sent vision requests there too, even beside a key set in the config file. The moment the file names `anthropic`, the file is this route's whole source and that variable no longer reaches it: set `anthropic.baseUrl` when you do want a different endpoint. `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` still configure this route on their own while the file says nothing about `anthropic`, both halves coming from the same place. A run caught between the two, with the variable set and the file naming `anthropic` without a `baseUrl`, refuses and prints the command that keeps the endpoint you were using.

### kimi-cli (Kimi Code login, no key)

Rides an existing `kimi` sign-in, so it spends the user's Kimi Code subscription
rather than a key. Install from https://moonshotai.github.io/kimi-code/, run
`kimi` once and `/login`, then:

```bash
modlens config set provider kimi-cli
modlens config set kimi-cli.model <alias>   # optional; kimi's own default otherwise
```

Naming it is what turns it on. Unlike the other CLI routes it never joins the failover chain on its own, because it spends a subscription and installing the CLI is not agreement to spend it.

The model alias is kimi's, in `<provider>/<model>` form as `kimi provider list`
shows it, and it has to accept image input. This route enforces no schema (the
CLI has no `--json-schema`), so the contract travels as a filled-in JSON
template and a weaker model can answer with half of it; `-p gemini-api` is the
fallback when that happens.

One implementation note worth knowing if you debug it: modlens runs `kimi` with
skill discovery pointed at an empty directory. Otherwise kimi can find the
modlens skill in the shared skill directories and read the image by calling
modlens, which is modlens calling itself.

### 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
```

## Turning thinking off

A reasoning model spends its thinking budget before it answers. Reading text out of an image needs none of that, so on a model that thinks by default the run is slower and more expensive for nothing. Every vendor names the switch differently, and there is no portable one, so modlens sends whatever you put in `extraBody` and leaves the naming to the vendor's own docs.

```bash
modlens config set openai.extraBody '{"thinking":{"type":"disabled"}}'   # persist it
modlens -i shot.png --extra-body '{"thinking":{"type":"disabled"}}'      # one run only
modlens config set openai.extraBody ''                                   # clear it
```

`--extra-body` replaces the stored object for that run rather than merging into it.

Known spellings, current as of August 2026:

| Endpoint | Field to send |
| :-- | :-- |
| MiMo official API (`api.xiaomimimo.com/v1`) | `{"thinking":{"type":"disabled"}}` |
| MiMo Responses-format route | `{"reasoning":{"effort":"none"}}` |
| Qwen, GLM, MiMo and friends self-hosted on vLLM or SGLang (GLM-5.3 and GLM-5.3-Flash cannot disable thinking) | `{"chat_template_kwargs":{"enable_thinking":false}}` |
| OpenAI-style gateways that accept an effort level | `{"reasoning_effort":"low"}` |
| `gemini-api`, Gemini 3 family | `{"generationConfig":{"thinkingConfig":{"thinkingLevel":"LOW"}}}` |
| `gemini-api`, Gemini 2.5 Flash and Flash Lite | `{"generationConfig":{"thinkingConfig":{"thinkingBudget":0}}}` |
| `anthropic` | nothing to do, thinking is off unless it is asked for |

Three things that bite:

- Not every model can turn it off. Gemini 3 Pro and Gemini 2.5 Pro have no off switch, only a lower level. Some models ignore an effort field entirely and think anyway.
- Strict clouds (Groq and Cerebras among them) reject fields they do not recognize with a 400. If a request that worked before now fails with a 400 naming your field, that gateway wants a different spelling, not this one.
- Others accept an unknown field and quietly ignore it, so check that it took effect instead of assuming. Compare `meta.durationSeconds` and the token counts in `meta.usage` against a run without `extraBody`. If neither moved, the field did not land.
- A weaker model may need its thinking to fill the schema. Measured on one flowchart: `gemini-3.6-flash` at `thinkingLevel: LOW` came back in 5.7s instead of 12s with the same regions and the same transcription, but `qwen3.6-27b` on DashScope with `enable_thinking: false` started omitting the required `type` on layout regions, which modlens rejects rather than passing off as evidence. If shape errors appear right after you turn thinking off, that is the trade, so turn it back on for that model or move to a route with server-side schema enforcement.

## Choosing a provider for the user

- Wants zero setup and free: `antigravity-cli` (needs agy sign-in, 15-40s per image; for dense or hard images try `-m gemini-3.1-pro-high`).
- Wants fast and free: `gemini-api` (three-minute key, 5-10s).
- Already pays for Claude: `claude-cli` (no extra key, 20-45s agent loop) or `anthropic` (API billing).
- Has a favorite multimodal endpoint (qwen, GLM, ...): `openai`.

Every configured provider also backs up the others: a run tries them in a
fixed order (inline API providers first at 5-10s, then the agents; for remote
URLs the order is also a security boundary) and fails over on an error, a
timeout, or a schema-violating result.
`config set provider <name>` moves a provider to the front of its allowed
region; `-p <name>` pins exactly one with no fallback. `doctor` prints the
chains, and the result's `meta.attempts` shows what a run actually tried.

## 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.
- `extraBody cannot override "<field>"`: that field carries the image, the prompt, or the schema. Drop it from the object and keep the vendor knobs.
- A 400 that names a field you set in `extraBody`: that gateway does not know it. See the thinking section above for the other spellings.
- `config init` refusing to run: the file exists; use `modlens config show` first, `--force` only if the user agrees to overwrite.

# 配置 ModLens

[English](configure.md) | 中文

用户询问如何安装、配置或切换 ModLens provider 时读这份文档。优先替用户把命令跑掉，而不是解释给他听。

## 配置放在哪

`~/.modlens/config.json`，由 CLI 管理。优先级：CLI 参数 > 本文件 > 内置默认值。一个 provider 的设置整份来自单一来源：自 3.17.0 起，本文件提到过它就以本文件为准，只字未提才用绑定的环境变量。不设 `provider` 时按失败切换链依次尝试（有 `gemini-api` key 会先于 agent CLI 被试到），机器上什么都没配才会落在 `antigravity-cli`。

```bash
modlens config init                     # 写入一份起步配置（已存在则拒绝，--force 重写）
modlens config show                     # 生效的配置文件，API key 打码显示
modlens config set provider <name>      # 更改默认 provider
modlens config set <provider>.<field> <value>   # 字段：apiKey、baseUrl、model、proxy、extraBody、structuredOutput
modlens config set proxy http://127.0.0.1:7890          # 所有 API provider 的默认代理
modlens config set openai.proxy ""                      # 让一个 provider 强制直连
```

`config set` 写文件时权限为 0600。

## 配置文件的完整形状

所有内容都在七个顶层键之下，全部可选。下面的示例一次性展示了所有支持的键和字段（真实文件只需要写你用到的部分）。文件不存在就全用默认值。provider 的设置放在 `providers.<name>` 下面，不在顶层，手工编辑最常犯的就是这个错。

```json
{
  "provider": "gemini-api",
  "cooldown": "on",
  "proxy": "http://127.0.0.1:7890",
  "reuse": { "claude": true, "codex": true, "opencode": false, "pi": true, "grok": true },
  "saved": {
    "openai": {
      "dashscope": { "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", "apiKey": "sk-...", "model": "qwen3-vl-plus" }
    }
  },
  "guards": {
    "allowModels": ["deepseek-v4-*", "glm-5.2*", "*/glm-5.2*", "glm-5.3", "*/glm-5.3", "minimax-m2.5*", "qwen3-coder*"],
    "denyModels": ["glm-*v*", "*/glm-*v*", "glm-5.3-flash", "glm-5.3-flash-*", "glm-5.3-flash:*", "*/glm-5.3-flash", "*/glm-5.3-flash-*", "*/glm-5.3-flash:*", "deepseek-vl*"],
    "denyWhenUnknown": false
  },
  "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",
      "proxy": "http://127.0.0.1:7890",
      "extraBody": { "thinking": { "type": "disabled" } },
      "structuredOutput": true
    },
    "anthropic": {
      "apiKey": "sk-ant-...",
      "baseUrl": "https://api.anthropic.com",
      "model": "claude-haiku-4-5-20251001"
    },
    "claude-cli": { "model": "haiku" }
  }
}
```

字段含义：

- `provider`：不传 `-p` 时由哪个 provider 执行。标准名和别名都行（`agy`/`antigravity` 对应 `antigravity-cli`，`gemini` 对应 `gemini-api`，`openai-compat` 对应 `openai`，`claude` 对应 `anthropic`，`kimi`/`kimi-code` 对应 `kimi-cli`，`claude-code` 对应 `claude-cli`）。留空或缺失表示不钉任何一个：由失败切换链决定，已配置的 API provider 先于 agent CLI 被尝试。
- `cooldown`：`'on'`（默认）或 `'off'`。打开时，配额耗尽的密钥会记入 `~/.modlens/state.json`，恢复前放到队尾再试（默认 45 分钟，月度 HTTP 432/433 为 24 小时，引擎回报的 `Resets in` 子句优先）。关闭时不读也不写那个文件。`modlens state clear` 会忘掉全部冷却。
- `proxy`：所有 API provider 的默认代理。它缺失时改由 `HTTPS_PROXY` 或 `HTTP_PROXY` 提供默认值，环境变量路线会遵守 `NO_PROXY`。
- `providers.<name>.proxy`：有三种状态。字段缺失表示继承上述默认值，空字符串表示强制直连，非空 URL 表示只给这个 provider 使用的代理。这样共享代理失效时，内网端点仍然可以直连。要恢复继承，删除配置文件中的这个字段，或在 dsh 设置卡中选择继承。`config show` 会把空值显示成 `direct`，设置卡会提供三种选择，而且不会把已保存的代理地址发送给浏览器。
- `providers.<name>.<field>`：共六个字段，`apiKey`、`baseUrl`、`model`、`proxy`、`extraBody`、`structuredOutput`（仅 openai 路线）。每个 provider 条目都可选，条目里的每个字段也都可选。别名键同样会被读取（存在 `gemini` 下的设置在解析到 `gemini-api` 时也能找到），冲突时标准键胜出。`apiKey` 接受英文逗号分隔的列表。请求按配置顺序使用，只在鉴权、限流或配额失败后轮换。其他失败会跳过剩余密钥，并继续走现有的 provider 故障转移。
- `providers.<name>.extraBody`：一个 JSON 对象，合并进 API provider（`gemini-api`、`openai`、`anthropic`）的请求体，用来传厂商有而 modlens 没有对应参数的开关。最常见的用途是关掉思考，见下文小节。嵌套对象逐键合并，所以加一个开关不会动到该块里的其他内容。承载图片、提示词和各路线自身强制机制的字段会被拒绝，报错会点名该字段。`openai` 路线上的 `response_format` 不在此列：在那里设置它就是有意替换掉 modlens 本来会发的那份 schema。三个 CLI provider 不发请求体，所以在 `antigravity-cli`、`claude-cli` 或 `kimi-cli` 上运行时它会被忽略，并在 `meta.warnings` 里说明。
- `providers.openai.structuredOutput`：设为 `true` 时，让 OpenAI 兼容网关自己强制执行视觉契约，以 `response_format: json_schema` 的严格形式发出。默认关闭，因为不支持结构化输出的网关会对这个字段返回 400。你在 `extraBody` 里设的 `response_format` 优先级更高。
- `saved.openai.<标签>`：openai 槽的命名存档，只有 `modlens config save openai <标签>` 写入、`modlens config use openai <标签>` 整包换入。切换网关不再丢上一个端点的 key：`use` 拒绝覆盖没有任何标签保存过的活跃槽（`--discard` 表示明确放弃）。解析、guard、failover、环境变量规则都不读这个区，活跃槽始终是唯一生效的 openai 路由。
- `guards`：调用 guard，给在同一个客户端里既跑纯文本模型又跑视觉模型的人用。两个列表都放 glob 模式（支持 `*` 和 `?`，不区分大小写，同时匹配模型名和 `provider/model`），用 `modlens config set guards.denyModels '["gemini-3*"]'` 或 `guards.allowModels` 设置（JSON 数组或逗号分隔的列表都行，传空则清除）。两种写法表达同一个意图，选列表更短的那种：
  - 只用 `denyModels`：除了列出的视觉模型，其余全部运行引擎。适合你接入的模型大多是纯文本的情况。
  - `allowModels` 非空（白名单模式）：只有列出的模型运行引擎，其他所有已识别的模型一律拒绝。适合 2026 年的实际格局，纯文本模型才是那份短名单。deny 模式仍然优先于 allow 匹配，所以宽泛的 allow 可以把视觉变体剔出去，正如上面的示例：`glm-5.2*` 和 `*/glm-5.2*` 覆盖裸名和带命名空间的 5.2 系列（`z-ai/glm-5.2:free`），`glm-5.3` 和 `*/glm-5.3` 覆盖 GLM-5.3 本体，`glm-*v*` 和 `*/glm-*v*` 抓住 `glm-5v-turbo`、`z-ai/glm-5.2v` 与 `z-ai/glm-5.2-vision`，带分隔符的 `glm-5.3-flash` / `glm-5.3-flash-*` / `glm-5.3-flash:*`（以及对应的 `*/` 形式）抓住 `glm-5.3-flash`。guard 按存下来的 id 匹配，不会剥掉厂商前缀，所以带命名空间的文本型号需要那条 `*/` 配对，带命名空间的视觉变体也需要对应的 deny 配对。不要写 `glm-5.*` 或 `glm-5.3-flash*`：前者也会匹配 `glm-5.3-flash`，后者也会匹配 `glm-5.3-flashlight` 这种连写。allow 模式要锚定得紧一些（写 `deepseek-v4-*` 而不是 `deepseek*`），这样厂商下一代多模态型号会自动掉出名单，等你检查过再上场。
  - 按真正抵达模型的内容来列名单，而不是按它本来能看到什么：多模态模型如果躲在一个剥离图片的网关后面，照样需要 modlens，而你的会话记录里存的是网关上报的模型名。`modlens doctor` 的 Guard 一节会显示规则和一条实时判定，方便核对结果。
  - `denyWhenUnknown`（默认 `false`）决定在两种模式下，当没有任何信号能识别当前模型时怎么办：`false` 放行，`true` 拒绝。当前模型的检测来源从强到弱依次是：`MODLENS_MODEL` 环境变量（`none` 表示「按未知处理」）、harness 的会话存储、`--model` 自报。
- `GEMINI_API_KEY`、`GEMINI_BASE_URL`、`OPENAI_API_KEY`、`OPENAI_BASE_URL`、`ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL` 用来配置本文件只字未提的 provider。本文件提到过的，它们完全不生效。过去它们逐字段覆盖，拼出的组合在哪儿都不存在：地址和密钥本是一副凭据。密钥变量和文件字段一样接受英文逗号分隔的列表。modlens 仍然读取 `MODLENS_HARNESS`（粘贴恢复和 guard 的作用范围）、`MODLENS_MODEL`（guard 覆盖，见 `guards`），以及各 harness 自己注入的指纹，它们把 guard 的存储查询钉在当前 session 上：`CLAUDE_CODE_SESSION_ID`、`CODEX_THREAD_ID`，加上 harness 检测依赖的存在性标记（`CLAUDECODE`、`PI_CODING_AGENT`、`CODEX_SANDBOX`）。
- `reuse.<claude|codex|opencode|pi|grok>`：按 harness 记录的授权，决定能否花费本机其他登录态，由引导对话（`references/onboard.md`）写入。`true` 允许读图时复用该 harness（pi 的凭据加入 inline 区且所有 guard 照常生效，已登录的 Codex、OpenCode 的视觉模型或直接驱动的 pi 加入 agent 区，排在 `claude-cli` 之前），`false` 记下一次拒绝，用户不会被再次询问，缺失表示从未问过，什么都不会运行。`claude` 缺失视为已授权：`claude-cli` 作为内置 provider 早于这套模型存在，`reuse.claude false` 会把它移出链条（`-p claude-cli` 仍可钉死）。复用来的引擎不比用户自己的优先：分区只按速度档次排序。每个复用得来的答案都会在 `meta.warnings` 里加一行，说明花的是谁的额度，`modlens doctor` 的 Reuse 一节会显示每个 harness 的决定和探测发现的结果（探测结果在 `~/.modlens/auto-cache.json` 里缓存 6 小时，doctor 每次都重新探测）。用 `modlens config set reuse.codex true` 设置（传空恢复为从未问过）。
- 未知的顶层键和未知的 provider 名会被忽略而不是报错，所以敲错字会无声失败：手工编辑后跑一下 `modlens doctor`，它会显示哪些文件值和环境变量真正生效。

手工编辑没问题（保持文件是合法 JSON，权限 0600）。`modlens config set` 做的是同一件事，只是多了护栏。

## 各 provider 配置步骤

### antigravity-cli（默认，免费，无需 key）

需要装好 Antigravity CLI 并完成登录：

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
agy    # 用户需自己在浏览器完成登录，然后退出
```

任何免费 Google 账号都行，不需要 Google AI Pro。登录无法自动化，请让用户自己跑一次 `agy`。

### gemini-api（免费 key，最快的免费通道，5-10 秒）

1. 用户到 https://aistudio.google.com 创建一个 key（约三分钟，无需信用卡，免费额度不过期）。
2. 两种方式任选其一保存：

```bash
modlens config set gemini-api.apiKey <key>
# 省略值：进入隐藏输入，密钥不进 argv、不进 shell 历史，也不进这段对话
modlens config set gemini-api.apiKey
```

用户就在自己终端前时，先给隐藏输入这条。大多数人图方便还是会把 key 直接贴进对话，那也没问题：照收照存。隐藏输入是留给在乎的人的。

默认模型 `gemini-3.6-flash` 在免费档就有视觉能力（约每分钟 10-15 次请求，每天 1500 次）。免费档的数据可能被 Google 用于改进产品，用户要处理敏感图片时请提醒这一点。

### openai（任意 OpenAI 兼容的多模态端点）

需要三个值。以 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
```

`baseUrl` 必填，用官方 OpenAI 也要写（`https://api.openai.com/v1`）：这条路线服务任意兼容端点，替用户猜一个，就等于把本该发给别家的密钥连同图片一起送到用户从没指定过的地方。模型必须是多模态的，纯文本模型会失败或产生幻觉。

这条路线默认在服务端不做任何约束，能力弱一些的模型可能只答出契约的一半，运行就会以明确报错失败。真遇到就让网关自己强制执行：

```bash
modlens config set openai.structuredOutput true
```

契约会以 `response_format: json_schema` 的严格形式发出去，schema 由 modlens 校验用的那份推导而来。默认关闭，因为不支持结构化输出的网关会对这个字段返回 400，端点拒绝就关回去。关掉思考（见下）会让结构错误更容易出现，所以这两项常常一起用。

### anthropic（Claude API key）

```bash
modlens config set anthropic.apiKey <sk-ant-key>
```

默认模型是 Claude Haiku（`claude-haiku-4-5-20251001`）。schema 通过强制工具调用来约束。

**`ANTHROPIC_BASE_URL` 陷阱已经拆掉了。**modlens 过去把这个变量按字段绑到 `anthropic.baseUrl`，于是一个为了把 Claude Code 路由到纯文本网关而设的变量，会让视觉请求也无声地发到那里，哪怕密钥是在配置文件里设的。现在只要文件里出现 `anthropic`，文件就是这条路线的全部来源，那个变量再也够不着它，确实想换端点就设 `anthropic.baseUrl`。而在文件对 `anthropic` 只字未提时，`ANTHROPIC_API_KEY` 和 `ANTHROPIC_BASE_URL` 仍然能独立配好这条路线，两半来自同一处。卡在中间的情况（变量设着、文件里有 `anthropic` 却没有 `baseUrl`）会直接报错，并给出保留原端点的那条命令。

### kimi-cli（复用 Kimi Code 登录，无需密钥）

搭在已有的 `kimi` 登录上，花的是用户的 Kimi Code 订阅而不是密钥。先从 https://moonshotai.github.io/kimi-code/ 安装，跑一次 `kimi` 并 `/login`，然后：

```bash
modlens config set provider kimi-cli
modlens config set kimi-cli.model <alias>   # 可选，不设就用 kimi 自己的默认模型
```

点名它才会启用。和其他 CLI 路线不同，它不会自己加入故障转移链：它花的是订阅，而装了 CLI 不等于同意花它。

模型别名用 kimi 自己的那套，形如 `<provider>/<model>`，`kimi provider list` 能看到，而且必须支持图片输入。这条路线没有服务端 schema 约束（该 CLI 没有 `--json-schema`），契约是以填好的 JSON 模板随提示词发过去的，能力弱的模型可能只答出一半，遇到就用 `-p gemini-api` 兜底。

有一个实现细节，调试时值得知道：modlens 运行 `kimi` 时把 skill 发现指向了一个空目录。否则 kimi 可能在共享的 skill 目录里找到 modlens skill，然后通过调用 modlens 来读图，也就是 modlens 自己调自己。

### claude-cli（Claude Code 登录态，无需 key）

借用已有的 `claude` 登录态，花的是用户的 Claude 订阅额度，不产生单独的 API 账单。需要装好并登录 Claude Code（用 `claude --version` 检查）。运行时只带 `--allowedTools Read`。只支持本地图片文件，远程 URL 请改用 gemini-api。默认模型别名 `haiku`。

```bash
modlens config set provider claude-cli   # 用户愿意的话把它设为默认
```

## 关闭思考

推理模型答题前要先花掉思考预算。从图片里读文字用不上这些，所以在默认思考的模型上，一次识别白白变得又慢又贵。每家厂商给这个开关起的名字都不一样，也没有通用写法，所以 modlens 只负责把你放进 `extraBody` 的内容原样发出去，名字怎么写去查厂商自己的文档。

```bash
modlens config set openai.extraBody '{"thinking":{"type":"disabled"}}'   # 持久保存
modlens -i shot.png --extra-body '{"thinking":{"type":"disabled"}}'      # 仅本次运行
modlens config set openai.extraBody ''                                   # 清除
```

`--extra-body` 在该次运行中整体替换已存储的对象，而不是合并进去。

已知写法，截至 2026 年 8 月：

| 端点 | 要发送的字段 |
| :-- | :-- |
| MiMo 官方 API（`api.xiaomimimo.com/v1`） | `{"thinking":{"type":"disabled"}}` |
| MiMo Responses 格式路由 | `{"reasoning":{"effort":"none"}}` |
| Qwen、GLM、MiMo 等自建在 vLLM 或 SGLang 上（GLM-5.3 与 GLM-5.3-Flash 不支持关闭思考） | `{"chat_template_kwargs":{"enable_thinking":false}}` |
| 接受 effort 档位的 OpenAI 风格网关 | `{"reasoning_effort":"low"}` |
| `gemini-api`，Gemini 3 系列 | `{"generationConfig":{"thinkingConfig":{"thinkingLevel":"LOW"}}}` |
| `gemini-api`，Gemini 2.5 Flash 与 Flash Lite | `{"generationConfig":{"thinkingConfig":{"thinkingBudget":0}}}` |
| `anthropic` | 什么都不用做，不主动要求就不思考 |

三个会咬人的地方：

- 不是每个模型都能关。Gemini 3 Pro 和 Gemini 2.5 Pro 没有关闭开关，只能调低档位。有些模型完全无视 effort 字段，照样思考。
- 严格的云（Groq 和 Cerebras 都在内）遇到不认识的字段会直接返回 400。以前能跑的请求现在报 400 并点名你的字段，说明那个网关要的是另一种写法，不是这一种。
- 另一些则会接受未知字段然后悄悄忽略，所以要验证它是否生效，别想当然。把 `meta.durationSeconds` 和 `meta.usage` 里的 token 数与不带 `extraBody` 的一次运行对比，两者都没变，就是字段没起作用。
- 较弱的模型可能得靠思考才能填满 schema。在同一张流程图上实测：`gemini-3.6-flash` 在 `thinkingLevel: LOW` 下从 12 秒缩到 5.7 秒，区块和转录内容不变，但 DashScope 上的 `qwen3.6-27b` 设了 `enable_thinking: false` 后开始漏掉版面区块必填的 `type`，modlens 会拒绝这种结果而不是当作证据放行。刚关掉思考就出现结构错误，说明这就是代价，给那个模型把思考打开，或换到有服务端 schema 约束的路线。

## 替用户选 provider

- 想零配置且免费：`antigravity-cli`（需要 agy 登录，每张图 15-40 秒，密集或困难的图可试 `-m gemini-3.1-pro-high`）。
- 想又快又免费：`gemini-api`（三分钟领 key，5-10 秒）。
- 已经在给 Claude 付费：`claude-cli`（无需额外 key，agent 循环 20-45 秒）或 `anthropic`（API 计费）。
- 有偏好的多模态端点（qwen、GLM 等）：`openai`。

每个配好的 provider 也互为后备：一次运行按固定顺序尝试它们（5-10 秒的 inline API provider 先上，然后是 agent 类，对远程 URL 来说这个顺序同时也是一道安全边界），遇到报错、超时或违反 schema 的结果就故障转移。`config set provider <name>` 把某个 provider 提到它所在允许分区的最前面，`-p <name>` 钉死唯一一个，不做回退。`doctor` 会打印这些故障转移链，结果里的 `meta.attempts` 显示一次运行实际试了什么。

## 故障排查

- 报错点名了缺失的环境变量或某条 `config set` 命令：照着运行即可。
- `Provider CLI not found: agy`：安装 Antigravity CLI 或换 provider。
- `Claude CLI reported ...` 或结果为空：检查 `claude` 的登录状态。
- openai 路线报 `does not match the vision schema`：重试一次，仍不行就换 gemini-api 或 anthropic。
- `extraBody cannot override "<field>"`：该字段承载图片、提示词或 schema。把它从对象里去掉，留下厂商开关即可。
- 400 报错点名了你在 `extraBody` 里设的字段：那个网关不认识它。其他写法见上文关闭思考一节。
- `config init` 拒绝执行：文件已存在。先用 `modlens config show` 查看，只有用户同意覆盖时才加 `--force`。

# Finding the image path in the chat

Harnesses rarely hand you a clean path. Identify which harness you are in, then follow its branch. Never mix branches across harnesses.

## Codex

You see a text tag like `<image name=[Image #1] path="/tmp/xxxx.png">`:

- Extract the `path` value from the tag and run modlens on it. Pasted images live in a temp file Codex already created; a stripped image keeps its path tag next to the placeholder.
- Do NOT use `recover-paste` here: it detects Codex and refuses with this same guidance.

## Claude Code with a `[Image: source: <path>]` line

Newer Claude Code builds write every pasted image to `~/.claude/image-cache/<session-id>/` and, in the terminal (`cli`) entrypoint, inject that line as a user message. Undocumented internal behavior (observed on 2.1.201 through 2.1.231; the VSCode and desktop entrypoints do not inject it), so treat it as a shortcut, not a guarantee.

- If the file at that path exists, run modlens on it directly and skip `recover-paste`. The file is Claude Code's own cache: read it, never delete or move it.
- If the path is gone (the cache is cleaned after a while) or there is no such line, fall through to the next branch.

## 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.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.
- Run every command yourself, never ask the user to run modlens or relay paths.
- When the analysis is done, delete the recovery output directory (each entry's `path` sits inside it): the files are private copies of the user's pastes, and nothing else cleans them up. Keep them only if the user asked.
- If the output's `detected` field is absent, detection failed and every store was scanned: check `harness` and `filename` match what you expect, force `--harness <claude-code|pi|opencode>` if 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), and recovered files are private to the user (0600).
- If recovery fails, ask the user to drag the image file into the terminal or type its path.

## Any other harness, or nothing matches

No path tag and `recover-paste` reports no transcripts: do not guess. Ask the user for the image file path, or suggest dragging the file into the terminal.

# First run on this machine: inventory, ask, then configure

Run this flow when `~/.modlens/config.json` does not exist, or `modlens config show` prints an empty config (`{"providers":{}}` with no `reuse` decisions). That check makes the flow idempotent: a machine that has been through it is never re-onboarded, and an existing config is never overwritten without the user asking for a change. The user can also request it by name ("set up modlens").

## 1. Inventory, spending nothing

```bash
modlens doctor --json
```

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

One line per finding, plain words, in the user's language. Name concrete things, not concepts:

- 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."

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

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."
- When a key is needed, offer the clean path first, in one line: "Run `modlens config set gemini-api.apiKey` in your terminal and paste the key at the hidden prompt. It stays out of this chat and out of your shell history, and I never see it." Most users will paste the key into the chat anyway, because that is the convenient path, and that is fine: take exactly the key they hand over, use it, and never go looking for keys they did not. The offer is for the users who care, not a gate.

## 4. Apply only what was consented to

| The user agreed to | Run |
| :-- | :-- |
| Reusing a harness CLI | `modlens config set reuse.<claude\|codex\|opencode\|pi\|grok> true` (one per consent) |
| A Gemini key they handed over | `modlens config set gemini-api.apiKey <key>` |
| An OpenAI-compatible endpoint | `config set openai.baseUrl / openai.apiKey / openai.model` |
| Guard rules for their text-only model | `modlens config set guards.allowModels '["<pattern>"]'` (patterns: `references/configure.md`) |

A refusal is also an answer: record it with `modlens config set reuse.<harness> false` so the user is never asked again. Nothing decided at all: write nothing and stop.

## 5. Close the loop

Run `modlens doctor` once more and report in one or two sentences: what was written (always and only `~/.modlens/config.json`), what the chain now looks like, and the undo (`modlens config set reuse.<harness> false`, or editing that file). If an engine is ready, offer to prove it on a real image.

## Never

- Never set any `reuse.<harness>` to true without an explicit yes for that harness in this conversation.
- Never write, move, or read files outside `~/.modlens/` during onboarding (doctor's read-only probing is the one exception).
- Never present reusing another login as free: it spends the named account's quota, and the wording must say so.

# 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.26.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.19 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.19 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.19+, 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 (unflagged in Node since 22.13), so on a machine
where the launcher resolved to bunx, `recover-paste` for OpenCode requires a
real Node install — 22.19+, since that is the floor this launcher accepts.

## 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.

#!/bin/sh
# modlens skill launcher (macOS / Linux).
#
# One stable action for the agent ("run modlens"); this script picks a working
# way to run it in the current environment. Written to POSIX sh so it runs under
# dash, busybox ash, and bash alike. Invoke it with `bash run.sh ...` (or plain
# `sh run.sh ...`) so a lost execute bit after a file copy never matters.
#
# Resolution order (kept identical in run.ps1):
#   1. A compatible modlens already on PATH  -> run it directly.
#   2. npx present                             -> run the pinned npm version.
#   3. bunx present                            -> run the pinned version via Bun.
#   4. (phase B placeholder) a native artifact -> not published yet.
#   5. Nothing usable                          -> structured diagnosis, exit 78.
#
# It never writes PATH, never needs admin rights, never fetches a second script,
# and has no postinstall step.
set -eu

# --- Version constants: stamped by scripts/release.mjs at release time. --------
# Do not edit PINNED by hand; scripts/stamp.test.mjs asserts it equals the
# package.json version, and the release script rewrites it on every bump.
PKG="@liustack/modlens"
BIN="modlens"
PINNED="3.26.1"
# -------------------------------------------------------------------------------

NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"

# Split "X.Y.Z" (extra suffix ignored) into the globals _MAJ, _MIN, _PAT.
# Any non-numeric component becomes 0 so integer tests below never abort.
parse_semver() {
  _raw="$1"
  _MAJ="${_raw%%.*}"
  _rest="${_raw#*.}"
  if [ "$_rest" = "$_raw" ]; then
    _MIN=0
    _PAT=0
  else
    _MIN="${_rest%%.*}"
    _rest2="${_rest#*.}"
    if [ "$_rest2" = "$_rest" ]; then _PAT=0; else _PAT="${_rest2%%.*}"; fi
  fi
  case "$_MAJ" in '' | *[!0-9]*) _MAJ=0 ;; esac
  case "$_MIN" in '' | *[!0-9]*) _MIN=0 ;; esac
  case "$_PAT" in '' | *[!0-9]*) _PAT=0 ;; esac
}

# Compatible = same major version as PINNED AND not older than PINNED.
# Same major keeps a globally installed CLI usable without a forced re-download;
# not-older refuses a stale build that predates the version this skill needs.
compatible() {
  parse_semver "$1"
  _f_maj=$_MAJ
  _f_min=$_MIN
  _f_pat=$_PAT
  parse_semver "$PINNED"
  [ "$_f_maj" = "$_MAJ" ] || return 1
  if [ "$_f_min" -gt "$_MIN" ]; then return 0; fi
  if [ "$_f_min" -lt "$_MIN" ]; then return 1; fi
  [ "$_f_pat" -ge "$_PAT" ]
}

# First "X.Y.Z" token printed by `$BIN --version`.
cli_version() {
  "$BIN" --version 2>/dev/null | head -n 1 |
    sed -n 's/.*\([0-9][0-9]*\.[0-9][0-9]*\.[0-9][0-9]*\).*/\1/p'
}

# The npx path runs the CLI on this machine's node, so npx is only usable when
# node itself meets the CLI's floor. An old node with a working npx used to be
# selected anyway, a path known to fail at run time.
NODE_FLOOR="22.19.0"
node_meets_floor() {
  command -v node >/dev/null 2>&1 || return 1
  _nv="$(node --version 2>/dev/null | sed 's/^v//')"
  [ -n "$_nv" ] || return 1
  parse_semver "$NODE_FLOOR"
  _floor_maj="$_MAJ"
  _floor_min="$_MIN"
  parse_semver "$_nv"
  if [ "$_MAJ" -gt "$_floor_maj" ]; then return 0; fi
  if [ "$_MAJ" -lt "$_floor_maj" ]; then return 1; fi
  [ "$_MIN" -ge "$_floor_min" ]
}

# Echo exactly one word: the chosen launch path.
resolve() {
  if command -v "$BIN" >/dev/null 2>&1; then
    _v="$(cli_version)"
    if [ -n "$_v" ] && compatible "$_v"; then
      echo "path"
      return
    fi
  fi
  if command -v npx >/dev/null 2>&1 && node_meets_floor; then
    echo "npx"
    return
  fi
  if command -v bunx >/dev/null 2>&1; then
    echo "bunx"
    return
  fi
  # Phase B goes here: check a versioned user cache, then download and verify a
  # native artifact into it. Any such download must use curl (never a piped
  # second script), which does not stamp quarantine / Mark-of-the-Web the way a
  # browser does, matching design.md 8.3.
  echo "none"
}

# Run the resolved CLI without exec, so its output can be captured (used to
# chain the CLI's own doctor). Passes every argument through untouched.
run_cli() {
  case "$G_SEL" in
    path) "$BIN" "$@" ;;
    npx) npx --yes --package "$PKG@$PINNED" "$BIN" "$@" ;;
    bunx) bunx --bun "$PKG@$PINNED" "$@" ;;
  esac
}

detect_os() { uname -s 2>/dev/null | tr '[:upper:]' '[:lower:]'; }

detect_arch() {
  _a="$(uname -m 2>/dev/null)"
  case "$_a" in
    x86_64 | amd64) echo "x64" ;;
    aarch64 | arm64) echo "arm64" ;;
    *) echo "$_a" ;;
  esac
}

# Escape a value for a JSON string literal (backslash and double quote).
json_escape() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g'; }

# Render "null" for an empty value, else an escaped JSON string.
jstr() {
  if [ -z "$1" ]; then printf 'null'; else printf '"%s"' "$(json_escape "$1")"; fi
}

# 1 -> true, anything else -> false.
jbool() { if [ "$1" = "1" ]; then printf 'true'; else printf 'false'; fi; }

# Probe the environment once into G_* globals shared by the emitters.
collect() {
  G_OS="$(detect_os)"
  G_ARCH="$(detect_arch)"

  G_CLI_PRESENT=0
  G_CLI_PATH=""
  G_CLI_VER=""
  G_CLI_COMPAT=0
  if command -v "$BIN" >/dev/null 2>&1; then
    G_CLI_PRESENT=1
    G_CLI_PATH="$(command -v "$BIN")"
    G_CLI_VER="$(cli_version)"
    if [ -n "$G_CLI_VER" ] && compatible "$G_CLI_VER"; then G_CLI_COMPAT=1; fi
  fi

  G_NPX_PRESENT=0
  G_NPX_PATH=""
  if command -v npx >/dev/null 2>&1; then
    G_NPX_PRESENT=1
    G_NPX_PATH="$(command -v npx)"
  fi

  G_BUNX_PRESENT=0
  G_BUNX_PATH=""
  if command -v bunx >/dev/null 2>&1; then
    G_BUNX_PRESENT=1
    G_BUNX_PATH="$(command -v bunx)"
  fi

  G_NODE_PRESENT=0
  G_NODE_VER=""
  if command -v node >/dev/null 2>&1; then
    G_NODE_PRESENT=1
    G_NODE_VER="$(node --version 2>/dev/null | sed 's/^v//')"
  fi

  G_NODE_FLOOR_OK=0
  if node_meets_floor; then G_NODE_FLOOR_OK=1; fi

  G_SEL="$(resolve)"
}

# Build the nextSteps JSON array body (without the brackets) into G_NEXTSTEPS.
compute_next_steps() {
  if [ "$G_SEL" = "none" ]; then
    if [ "$G_NPX_PRESENT" = 1 ] && [ "$G_NODE_FLOOR_OK" = 0 ]; then
      _s1="npx is present but node ${G_NODE_VER:-missing} is below the $NODE_FLOOR floor this CLI needs. Upgrade Node at https://nodejs.org, then re-run this launcher."
    else
      _s1="Install Node 22.19+ from https://nodejs.org so npx can run $PKG@$PINNED, then re-run this launcher."
    fi
    _s2="No JavaScript runtime? Install Bun from https://bun.sh to use bunx, or put a compatible $BIN (major ${PINNED%%.*}, at or above $PINNED) on PATH."
    G_NEXTSTEPS="$(printf '"%s", "%s"' "$(json_escape "$_s1")" "$(json_escape "$_s2")")"
  else
    G_NEXTSTEPS=""
  fi
}

# Emit the structured diagnosis. $1, when a JSON object, is embedded as cliDoctor.
emit_json() {
  _chained="${1:-}"
  compute_next_steps
  printf '{\n'
  printf '  "tool": %s,\n' "$(jstr "$BIN")"
  printf '  "package": %s,\n' "$(jstr "$PKG")"
  printf '  "pinnedVersion": %s,\n' "$(jstr "$PINNED")"
  printf '  "os": %s,\n' "$(jstr "$G_OS")"
  printf '  "arch": %s,\n' "$(jstr "$G_ARCH")"
  printf '  "checked": {\n'
  printf '    "pathCli": { "present": %s, "path": %s, "version": %s, "compatible": %s },\n' \
    "$(jbool "$G_CLI_PRESENT")" "$(jstr "$G_CLI_PATH")" "$(jstr "$G_CLI_VER")" "$(jbool "$G_CLI_COMPAT")"
  printf '    "npx": { "present": %s, "path": %s, "nodeMeetsFloor": %s },\n' "$(jbool "$G_NPX_PRESENT")" "$(jstr "$G_NPX_PATH")" "$(jbool "$G_NODE_FLOOR_OK")"
  printf '    "bunx": { "present": %s, "path": %s },\n' "$(jbool "$G_BUNX_PRESENT")" "$(jstr "$G_BUNX_PATH")"
  printf '    "node": { "present": %s, "version": %s }\n' "$(jbool "$G_NODE_PRESENT")" "$(jstr "$G_NODE_VER")"
  printf '  },\n'
  printf '  "nativeArtifact": { "available": false, "note": %s },\n' "$(jstr "$NATIVE_NOTE")"
  printf '  "selected": %s,\n' "$(jstr "$G_SEL")"
  printf '  "nextSteps": [%s],\n' "$G_NEXTSTEPS"
  # First character of the captured output, via POSIX parameter expansion
  # (cut -c1 would take the first char of every line, not of the whole string).
  _first="${_chained%"${_chained#?}"}"
  if [ -n "$_chained" ] && [ "$_first" = "{" ]; then
    printf '  "cliDoctor": %s\n' "$_chained"
  else
    printf '  "cliDoctor": null\n'
  fi
  printf '}\n'
}

# Human-readable diagnosis for `doctor` without --json.
emit_text() {
  printf '%s launcher diagnosis\n\n' "$BIN"
  printf '  os / arch:      %s / %s\n' "$G_OS" "$G_ARCH"
  printf '  pinned version: %s (%s)\n' "$PINNED" "$PKG"
  if [ "$G_CLI_PRESENT" = 1 ]; then
    printf '  %s on PATH:  %s (version %s, %s)\n' "$BIN" "$G_CLI_PATH" \
      "${G_CLI_VER:-unknown}" "$([ "$G_CLI_COMPAT" = 1 ] && echo compatible || echo incompatible)"
  else
    printf '  %s on PATH:  no\n' "$BIN"
  fi
  _npx_desc="no"
  if [ "$G_NPX_PRESENT" = 1 ]; then
    if [ "$G_NODE_FLOOR_OK" = 1 ]; then
      _npx_desc="$G_NPX_PATH"
    else
      _npx_desc="$G_NPX_PATH (unusable: node ${G_NODE_VER:-missing} is below $NODE_FLOOR)"
    fi
  fi
  printf '  npx:            %s\n' "$_npx_desc"
  printf '  bunx:           %s\n' "$([ "$G_BUNX_PRESENT" = 1 ] && echo "$G_BUNX_PATH" || echo no)"
  printf '  node:           %s\n' "$([ "$G_NODE_PRESENT" = 1 ] && echo "${G_NODE_VER:-yes}" || echo no)"
  printf '  selected path:  %s\n' "$G_SEL"
  if [ "$G_SEL" = "none" ]; then
    printf '\nNo runtime can launch %s here. %s\n' "$BIN" "$NATIVE_NOTE"
    printf 'Next steps:\n'
    printf '  - Install Node 22.19+ from https://nodejs.org, then re-run this launcher.\n'
    printf '  - Or install Bun from https://bun.sh, or put a compatible %s on PATH.\n' "$BIN"
  fi
}

# `doctor [--json] [extra...]`: launcher selection diagnosis. When a CLI is
# resolvable, chain the CLI's own doctor (engine/config diagnosis) so one call
# reports both layers. Extra flags pass through to the chained CLI doctor.
doctor() {
  collect
  _json=0
  for _a in "$@"; do
    if [ "$_a" = "--json" ]; then _json=1; fi
  done
  if [ "$_json" = 1 ]; then
    _chained=""
    if [ "$G_SEL" != "none" ]; then
      _chained="$(run_cli doctor "$@" 2>/dev/null)" || _chained=""
    fi
    emit_json "$_chained"
  else
    emit_text
    if [ "$G_SEL" != "none" ]; then
      printf '\n--- %s doctor ---\n' "$BIN"
      run_cli doctor "$@" || true
    fi
  fi
}

# Default action: forward every argument to the resolved CLI, inheriting stdio
# and exit code. No usable runtime -> structured diagnosis on stderr, exit 78
# (EX_CONFIG) so the agent never mistakes the diagnosis for a result.
run() {
  _sel="$(resolve)"
  case "$_sel" in
    path) exec "$BIN" "$@" ;;
    npx) exec npx --yes --package "$PKG@$PINNED" "$BIN" "$@" ;;
    bunx) exec bunx --bun "$PKG@$PINNED" "$@" ;;
    none)
      collect
      emit_json "" >&2
      exit 78
      ;;
  esac
}

case "${1:-}" in
  doctor)
    shift
    doctor "$@"
    ;;
  where)
    resolve
    ;;
  *)
    run "$@"
    ;;
esac