@liustack/modlens 3.16.6 → 3.17.0

package/dsh/index.js

@@ -11,7 +11,9 @@
 // package.json `dsh.bundle` manifest). Providers, reuse grants, and guard
 // rules keep living in ~/.modlens/config.json, shared with every harness.
 import { spawn } from 'node:child_process'
-import { readFileSync } from 'node:fs'
+import { chmodSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const CLI_PATH = fileURLToPath(new URL('../dist/main.js', import.meta.url))
@@ -59,14 +61,29 @@ export function apply(ctx, config = {}) {
   // optional-inject form, so the route rides a scoped ctx.inject: the closure
   // runs when the service appears and never runs where it does not (headless
   // stays untouched, and the plugin itself never waits on it).
-  if (config.pasteToPath !== false && typeof ctx.inject === 'function') {
+  if (typeof ctx.inject === 'function') {
     ctx.inject(['webServer'], (scope) => {
-      try {
-        // scope carries webServer; the plugin's own ctx carries llm for the
-        // takeover verdicts.
-        registerPasteRoute(scope, ctx, ownProviders)
-      } catch (error) {
-        console.error(`[modlens] paste-to-path route skipped: ${error}`)
+      if (config.pasteToPath !== false) {
+        try {
+          // scope carries webServer; the plugin's own ctx carries llm for the
+          // takeover verdicts.
+          registerPasteRoute(scope, ctx, ownProviders)
+        } catch (error) {
+          console.error(`[modlens] paste-to-path route skipped: ${error}`)
+        }
+      }
+      // Same web server, a separate switch: turning paste-to-path off is a
+      // statement about how images enter, not about whether the engine can
+      // be configured. dsh's own settings surface renders a hardcoded set of
+      // cards and does not enumerate namespaces, so the card the browser half
+      // contributes talks to this route rather than to a settings schema
+      // (issue #39).
+      if (config.settingsCard !== false) {
+        try {
+          registerConfigRoute(scope)
+        } catch (error) {
+          console.error(`[modlens] settings card route skipped: ${error}`)
+        }
       }
     })
   }
@@ -850,3 +867,404 @@ function renderEvidence(value) {
   }
   return lines.join('\n')
 }
+
+// The engines a user can pick in the settings card, in the order the docs
+// introduce them. Kept to the names modlens itself uses so the card and
+// `modlens doctor` say the same words.
+const ENGINES = ['antigravity-cli', 'gemini-api', 'openai', 'anthropic', 'claude-cli']
+// The two CLI engines sign in through their own tool, so a key or an endpoint
+// would be a field with nothing behind it. Both still take a model.
+const KEYLESS_ENGINES = ['antigravity-cli', 'claude-cli']
+// Every accepted spelling, mirroring src/providers/index.ts. Settings saved
+// under an alias are the same engine's settings, and a provider pinned by an
+// alias is pinned to that engine: showing either as something else would put
+// the card at odds with what actually reads the images.
+const ENGINE_ALIASES = {
+  antigravity: 'antigravity-cli',
+  agy: 'antigravity-cli',
+  gemini: 'gemini-api',
+  'openai-compat': 'openai',
+  claude: 'anthropic',
+  'claude-code': 'claude-cli',
+}
+
+/** The canonical engine a stored name means, or '' when it names none. */
+function canonicalEngine(name) {
+  if (typeof name !== 'string') return ''
+  const trimmed = name.trim().toLowerCase()
+  if (ENGINES.includes(trimmed)) return trimmed
+  return ENGINE_ALIASES[trimmed] ?? ''
+}
+
+/** The config keys holding one engine's settings: its own, plus its aliases. */
+function settingsKeysFor(engine) {
+  const aliases = Object.keys(ENGINE_ALIASES).filter((alias) => ENGINE_ALIASES[alias] === engine)
+  return [...aliases, engine]
+}
+// Auto mode: the local harnesses whose logins a read may borrow. `claude`
+// absent counts as granted, since claude-cli predates the grant model.
+const REUSE_HARNESSES = ['claude', 'codex', 'opencode', 'pi', 'grok']
+
+// The variables that supply an engine while the file names no entry for it,
+// mirroring ENV_BINDINGS in src/config.ts. An engine takes its settings from
+// one source whole, so the card has to read the same two places a read does or
+// it shows an empty form for an engine that works.
+const ENGINE_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 engineEnvSettings(engine, env = process.env) {
+  const settings = {}
+  for (const [field, variable] of Object.entries(ENGINE_ENV_BINDINGS[engine] ?? {})) {
+    const value = typeof env[variable] === 'string' ? env[variable].trim() : ''
+    if (value !== '') settings[field] = value
+  }
+  return settings
+}
+
+/**
+ * Whether the file names this engine. The key existing is what counts, not
+ * what it holds: an entry emptied down to `{}` still takes the engine off its
+ * variables, the same rule fileKeysFor applies in src/config.ts.
+ */
+function engineConfiguredInFile(engine, config) {
+  return settingsKeysFor(engine).some((key) => config.providers?.[key] !== undefined)
+}
+
+/** ~/.modlens/config.json, the one file every harness shares. */
+function modlensConfigPath() {
+  return join(homedir(), '.modlens', 'config.json')
+}
+
+/**
+ * The shared config, or a thrown error. Only a missing file reads as empty:
+ * a file that exists but cannot be parsed or read is somebody's configuration,
+ * and a settings card that treated it as empty would overwrite it on the next
+ * save. The card shows the error instead.
+ */
+function readModlensConfig() {
+  let raw
+  try {
+    raw = readFileSync(modlensConfigPath(), 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {}
+    throw new Error(`cannot read ${modlensConfigPath()}: ${error?.message ?? error}`)
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`${modlensConfigPath()} is not valid JSON: ${error?.message ?? error}`)
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${modlensConfigPath()} does not hold a JSON object`)
+  }
+  return parsed
+}
+
+/**
+ * What the card is allowed to know. Every engine's endpoint and model, plus
+ * whether a key is stored, and never the key itself: a browser that cannot
+ * read a secret cannot leak one, and cannot write it back either.
+ */
+function engineSummary(config = readModlensConfig()) {
+  const engines = {}
+  for (const name of ENGINES) {
+    // One source, whole. The file when it names the engine, its variables
+    // otherwise: reading only the file showed an empty form for a container
+    // that exports its key, and the first save then wrote a partial entry
+    // that took the working variables away.
+    const inFile = engineConfiguredInFile(name, config)
+    // Alias first, canonical last: the canonical key wins on conflict, the
+    // same order resolveProviderSettings uses.
+    const settings = inFile
+      ? Object.assign({}, ...settingsKeysFor(name).map((key) => config.providers?.[key] ?? {}))
+      : engineEnvSettings(name)
+    engines[name] = {
+      baseUrl: typeof settings.baseUrl === 'string' ? settings.baseUrl : '',
+      model: typeof settings.model === 'string' ? settings.model : '',
+      hasKey: typeof settings.apiKey === 'string' && settings.apiKey !== '',
+      // '' means neither source holds anything, which is not the same as the
+      // file holding an empty entry: that one is already off its variables.
+      source: inFile ? 'file' : Object.keys(settings).length > 0 ? 'env' : '',
+    }
+  }
+  const reuse = {}
+  for (const harness of REUSE_HARNESSES) {
+    const granted = config.reuse?.[harness]
+    reuse[harness] = typeof granted === 'boolean' ? granted : harness === 'claude'
+  }
+  // Three states, kept apart: pinned to an engine, pinned by one of its
+  // aliases (reported canonically), or not pinned at all, which is its own
+  // answer and means the failover chain decides. Collapsing the third into
+  // the first pins an engine the user never chose.
+  return {
+    provider: canonicalEngine(config.provider),
+    engines,
+    keyless: KEYLESS_ENGINES,
+    reuse,
+  }
+}
+
+/**
+ * Apply one card submission to the shared file. Only the named engine's own
+ * three fields are touched, so switching engines in the card cannot copy one
+ * engine's endpoint onto another. An absent or empty `apiKey` leaves the
+ * stored one alone: the card never receives a key, so it must never be able
+ * to clear one by submitting the blank field it was shown.
+ */
+function applyEngineSettings(patch) {
+  const config = readModlensConfig()
+  // The pin moves only when the card says it moved. A save that carried the
+  // currently displayed engine regardless turned "not pinned" into a pin on
+  // whatever happened to be shown, changing which engine reads every later
+  // image without the user asking for it.
+  if (patch?.provider !== undefined) {
+    if (patch.provider === '') {
+      delete config.provider
+    } else if (ENGINES.includes(patch.provider)) {
+      config.provider = patch.provider
+    } else {
+      throw new Error(`unknown engine: ${patch.provider}`)
+    }
+  }
+  // Engine fields are edited one engine at a time, named by `engine`. Absent
+  // means this save touched no engine settings, which is what a reuse-only
+  // save looks like.
+  const engine = patch?.engine
+  if (engine !== undefined) {
+    if (!ENGINES.includes(engine)) {
+      throw new Error(`unknown engine: ${engine}`)
+    }
+    config.providers = { ...config.providers }
+    // Write where this engine's settings already live, so a key saved under
+    // an alias is updated rather than shadowed by a second copy.
+    // Write where the read takes effect. settingsKeysFor merges aliases
+    // first and the canonical key last, so the canonical value wins; picking
+    // the first existing key instead wrote a new value underneath an older
+    // canonical one, which saved successfully and changed nothing. Both CLI
+    // spellings existing at once is ordinary: `config set gemini.apiKey`
+    // then `config set gemini-api.apiKey` leaves exactly that.
+    const holders = settingsKeysFor(engine).filter((key) => config.providers[key] !== undefined)
+    const target = holders.length > 0 ? holders[holders.length - 1] : engine
+    // The first file entry for an engine the variables are supplying takes it
+    // off them whole, so their values move into the entry with it. Otherwise
+    // saving a model on a working environment-only engine deleted its key and
+    // endpoint from the run. Seeded here rather than in the browser because
+    // the key must never travel there.
+    const seed = holders.length > 0 ? {} : engineEnvSettings(engine)
+    const settings = { ...seed, ...config.providers[target] }
+    for (const field of ['baseUrl', 'model']) {
+      const value = typeof patch[field] === 'string' ? patch[field].trim() : ''
+      if (value === '') {
+        delete settings[field]
+      } else {
+        settings[field] = value
+      }
+    }
+    const apiKey = typeof patch.apiKey === 'string' ? patch.apiKey.trim() : ''
+    if (apiKey !== '') {
+      settings.apiKey = apiKey
+    }
+    config.providers[target] = settings
+  }
+  // Auto mode, when the card sent it: only the harnesses this build knows,
+  // only booleans, so an unexpected key cannot land in the shared file.
+  if (patch?.reuse !== null && typeof patch?.reuse === 'object') {
+    config.reuse = { ...config.reuse }
+    for (const harness of REUSE_HARNESSES) {
+      const granted = patch.reuse[harness]
+      if (typeof granted === 'boolean') {
+        config.reuse[harness] = granted
+      }
+    }
+  }
+  const file = modlensConfigPath()
+  // A symlink here would write through to wherever it points, so it is
+  // refused rather than followed: the CLI writes a real file, and anything
+  // else is a setup this card should not silently honor.
+  try {
+    if (lstatSync(file).isSymbolicLink()) {
+      throw new Error(`${file} is a symlink; edit the file it points at instead`)
+    }
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  try {
+    chmodSync(file, 0o600)
+  } catch {
+    // Windows has no POSIX bits; the mode on the write above is all there is.
+  }
+}
+
+/**
+ * GET /modlens/config: the engine summary above. POST: one submission.
+ *
+ * The dsh web server listens on loopback, but a page in the same browser can
+ * still reach it, so a write requires a same-origin request: a cross-site POST
+ * could otherwise repoint someone's engine at an endpoint of its choosing.
+ * A read is refused the same way for symmetry, though it carries no secret.
+ */
+/**
+ * The self-check behind the card's auto-mode section: which local harnesses
+ * exist to be borrowed at all. `doctor --json` already probes them without
+ * network or quota, so the route spawns the CLI this package ships and lifts
+ * its reuse section. Cached briefly, since one probe can take a second and
+ * re-expanding the card should not re-pay it.
+ */
+const DISCOVERY_TTL_MS = 60_000
+let discoveryCache = null
+async function discoverReuse() {
+  if (discoveryCache !== null && Date.now() - discoveryCache.at < DISCOVERY_TTL_MS) {
+    return discoveryCache.value
+  }
+  try {
+    const { stdout, code } = await run(process.execPath, [CLI_PATH, 'doctor', '--json'], AbortSignal.timeout(30_000))
+    if (code !== 0) return null
+    const reuse = JSON.parse(stdout)?.reuse
+    if (!reuse || !Array.isArray(reuse.probes)) return null
+    // doctor names the harness claude-code; the grant key is claude.
+    const probes = reuse.probes.map((probe) => ({
+      harness: probe.harness === 'claude-code' ? 'claude' : probe.harness,
+      cliFound: probe.cliFound === true,
+      loggedIn: probe.loggedIn,
+      cliPath: typeof probe.cliPath === 'string' ? probe.cliPath : '',
+    }))
+    discoveryCache = { at: Date.now(), value: probes }
+    return probes
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Open the shared config file in whatever the OS considers its editor. The
+ * card's "open config file" link lands here: the path never has to be
+ * explained to the user, they just get the file. Created empty first when
+ * missing, so the editor has something to open.
+ */
+function openConfigFile() {
+  const file = modlensConfigPath()
+  try {
+    lstatSync(file)
+  } catch {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, '{}\n', { mode: 0o600 })
+  }
+  const [command, args] =
+    process.platform === 'darwin'
+      ? ['open', [file]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', file]]
+        : ['xdg-open', [file]]
+  spawn(command, args, { detached: true, stdio: 'ignore' }).unref()
+}
+
+/** localhost, ::1, or anything in 127/8, matching dsh's own /api fence. */
+function isLoopbackHost(hostname) {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return (
+    parts.length === 4 && parts[0] === '127' && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+  )
+}
+
+/**
+ * The same fence dsh puts in front of its own /api, for the same two
+ * confused-deputy paths. Host is the header DNS rebinding cannot forge, so it
+ * must name a loopback authority: a rebound page reaches this socket carrying
+ * its own domain there. Origin and Sec-Fetch-Site then rule out a cross-site
+ * page on the machine itself. A dsh serving a LAN address configures
+ * trustedHosts for /api; this route stays loopback-only, since nothing about
+ * editing an API key wants a wider door.
+ */
+function isTrustedRequest(req) {
+  const host = req.headers?.host
+  if (typeof host !== 'string' || host === '') return false
+  let hostUrl
+  try {
+    hostUrl = new URL(`http://${host}`)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHost(hostUrl.hostname)) return false
+  if (req.headers?.['sec-fetch-site'] === 'cross-site') return false
+  const origin = req.headers?.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}
+
+function registerConfigRoute(ctx) {
+  ctx.webServer.register({
+    name: 'modlens-config',
+    kind: 'exact',
+    path: '/modlens/config',
+    handler: async (req, res) => {
+      const send = (status, body) => {
+        res.writeHead(status, { 'content-type': 'application/json' })
+        res.end(JSON.stringify(body))
+      }
+      if (!isTrustedRequest(req)) {
+        send(403, { error: 'request refused: this route answers same-origin loopback only' })
+        return
+      }
+      if (req.method === 'GET') {
+        try {
+          const summary = engineSummary()
+          const wantsDiscovery = new URL(req.url, 'http://localhost').searchParams.has('discover')
+          if (wantsDiscovery) {
+            // null when the probe failed: the card then falls back to the
+            // plain grant list rather than showing nothing.
+            summary.discovery = await discoverReuse()
+          }
+          send(200, summary)
+        } catch (error) {
+          send(409, { error: String(error?.message ?? error) })
+        }
+        return
+      }
+      if (req.method !== 'POST') {
+        res.writeHead(405).end()
+        return
+      }
+      try {
+        const chunks = []
+        let total = 0
+        for await (const chunk of req) {
+          total += chunk.length
+          if (total > 64 * 1024) {
+            send(413, { error: 'config payload too large' })
+            req.destroy()
+            return
+          }
+          chunks.push(chunk)
+        }
+        const patch = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+        // The card's "open config file" link: an action, not a setting.
+        if (patch?.open === true) {
+          openConfigFile()
+          send(200, { opened: true })
+          return
+        }
+        applyEngineSettings(patch)
+        send(200, engineSummary())
+      } catch (error) {
+        send(400, { error: String(error?.message ?? error) })
+      }
+    },
+  })
+}
+
+// The two halves of the settings card that live on this side of the socket,
+// reachable from the test suite the way client.js exposes `__card`. They read
+// and write a real file and a real environment, so they are tested against
+// both rather than through the HTTP route.
+export const __config = { engineSummary, applyEngineSettings, modlensConfigPath }

package/package.json

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

package/skills/modlens/SKILL.md

@@ -20,11 +20,11 @@ powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 <args>
 
 It resolves a working runtime (PATH `modlens`, then `npx`, then `bunx`) and forwards your arguments unchanged. Exit 78 means no runtime: relay the `nextSteps` from its stderr JSON instead of retrying.
 
-If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.16.6):
+If your harness forbids running scripts, reason through the same order by hand and run the first line that works (the pinned version is 3.17.0):
 
-1. A `modlens` on `PATH` whose major version is 3 and is at least 3.16.6: `modlens <args>`.
-2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.16.6 modlens <args>`.
-3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.16.6 <args>`.
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.17.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.17.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.17.0 <args>`.
 4. Otherwise tell the user no JavaScript runtime was found and that installing Node 22.19+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
 
 `references/runtime.md` documents the pin and the diagnostic fields.

package/skills/modlens/references/configure.md

@@ -6,7 +6,7 @@ Read this when the user asks how to set up, configure, or switch ModLens provide
 
 ## Where config lives
 
-`~/.modlens/config.json`, managed by the CLI. Precedence: CLI flags > environment variables > config file > built-in defaults. 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`.
+`~/.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)
@@ -58,16 +58,16 @@ Everything lives under five top-level keys, all optional. This example shows eve
 
 Field semantics:
 
-- `provider`: which provider runs when `-p` is not given. Canonical names or aliases both work (`agy`/`antigravity` for `antigravity-cli`, `gemini` for `gemini-api`, `openai-compat` for `openai`, `claude` for `anthropic`, `claude-code` for `claude-cli`). Empty or absent pins nothing: the failover chain decides, trying configured API providers before the agent CLIs.
+- `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.
 - `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.
-- `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 two CLI providers take no request body, so a run on `antigravity-cli` or `claude-cli` ignores it and says so in `meta.warnings`.
+- `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.
 - `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.*` allows the text line while `glm-*v*` catches `glm-5v-turbo`. 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.
-- Environment variables override the file for these bindings: `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`. Beyond those, modlens 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`).
+- `GEMINI_API_KEY`, `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. 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.
 
@@ -93,9 +93,12 @@ Any free Google account works; no Google AI Pro needed. Sign-in cannot be automa
 
 ```bash
 modlens config set gemini-api.apiKey <key>
-# or environment: export GEMINI_API_KEY=<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)
@@ -108,7 +111,7 @@ 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.
+`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:
 
@@ -122,12 +125,35 @@ The contract goes out as `response_format: json_schema` in strict form, derived
 
 ```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.
 
-**`ANTHROPIC_BASE_URL` trap.** modlens binds `ANTHROPIC_BASE_URL` to `anthropic.baseUrl`, so it inherits whatever that variable points at. If the user set it in their shell to route Claude Code through a text-only gateway (a common way to run a non-Claude model behind the Claude Code UI), then `-p anthropic` silently sends the vision request to that gateway too, where it fails or comes back blind, with no hint that the endpoint was swapped. Check `echo $ANTHROPIC_BASE_URL` when anthropic vision misbehaves. Fixes: unset it for the modlens call, pin the real endpoint with `modlens config set anthropic.baseUrl https://api.anthropic.com`, or use `-p gemini-api` instead.
+**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)