@liustack/modlens 3.14.0 → 3.16.0

package/dsh/index.js

@@ -15,9 +15,7 @@ import { fileURLToPath } from 'node:url'
 const CLI_PATH = fileURLToPath(new URL('../dist/main.js', import.meta.url))
 // Kept in lockstep with src/schema.ts by a repo test; the plugin file cannot
 // import the TS source and stays fully dependency-free (node builtins only).
-const OUTPUT_SCHEMA = JSON.parse(
-  readFileSync(new URL('./vision-schema.json', import.meta.url), 'utf8'),
-)
+const OUTPUT_SCHEMA = JSON.parse(readFileSync(new URL('./vision-schema.json', import.meta.url), 'utf8'))
 
 const CLI_TIMEOUT_MS = 180_000
 
@@ -55,7 +53,9 @@ export function apply(ctx, config = {}) {
   if (config.pasteToPath !== false && typeof ctx.inject === 'function') {
     ctx.inject(['webServer'], (scope) => {
       try {
-        registerPasteRoute(scope)
+        // scope carries webServer; the plugin's own ctx carries llm for the
+        // takeover verdicts.
+        registerPasteRoute(scope, ctx)
       } catch (error) {
         console.error(`[modlens] paste-to-path route skipped: ${error}`)
       }
@@ -117,9 +117,7 @@ export function apply(ctx, config = {}) {
       }
       const { stdout, stderr, code } = await run(process.execPath, cliArgs, exec.signal)
       if (code !== 0) {
-        throw new Error(
-          `modlens failed (exit ${code}): ${(stderr || stdout).trim().slice(0, 500)}`,
-        )
+        throw new Error(`modlens failed (exit ${code}): ${(stderr || stdout).trim().slice(0, 500)}`)
       }
       let parsed
       try {
@@ -140,9 +138,7 @@ export function apply(ctx, config = {}) {
     if (preferred !== fallback && /already|duplicate/i.test(String(error))) {
       try {
         ctx.tools.register(readImageTool(fallback))
-        console.error(
-          `[modlens] tool name "${preferred}" is taken by the host; registered as "${fallback}" instead`,
-        )
+        console.error(`[modlens] tool name "${preferred}" is taken by the host; registered as "${fallback}" instead`)
       } catch (retryError) {
         console.error(`[modlens] read_image registration skipped: ${retryError}`)
       }
@@ -153,27 +149,188 @@ export function apply(ctx, config = {}) {
 }
 
 // Image magic bytes for the paste route: refuse anything that is not a real
-// image before a byte touches disk. Mirrors the CLI's sniffing table.
+// image before a byte touches disk. Mirrors the CLI's sniffing table
+// (src/imageInput.ts SNIFFERS) signature for signature: full PNG magic, both
+// GIF variants, and ftyp only with a known heic/heif brand — a generic BMFF
+// (`ftypmp42`, plain video) must not be saved as an image.
 const PASTE_SNIFFS = [
-  { ext: '.png', test: (b) => b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 },
+  {
+    ext: '.png',
+    test: (b) =>
+      b.length >= 8 &&
+      b[0] === 0x89 &&
+      b[1] === 0x50 &&
+      b[2] === 0x4e &&
+      b[3] === 0x47 &&
+      b[4] === 0x0d &&
+      b[5] === 0x0a &&
+      b[6] === 0x1a &&
+      b[7] === 0x0a,
+  },
   { ext: '.jpg', test: (b) => b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
-  { ext: '.gif', test: (b) => b.length >= 6 && b.toString('ascii', 0, 3) === 'GIF' },
-  { ext: '.webp', test: (b) => b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP' },
-  { ext: '.heic', test: (b) => b.length >= 12 && b.toString('ascii', 4, 8) === 'ftyp' },
+  {
+    ext: '.gif',
+    test: (b) => b.length >= 6 && ['GIF87a', 'GIF89a'].includes(b.toString('ascii', 0, 6)),
+  },
+  {
+    ext: '.webp',
+    test: (b) => b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP',
+  },
+  {
+    ext: '.heic',
+    test: (b) =>
+      b.length >= 12 &&
+      b.toString('ascii', 4, 8) === 'ftyp' &&
+      ['heic', 'heix', 'hevc', 'hevx'].includes(b.toString('ascii', 8, 12)),
+  },
+  {
+    ext: '.heif',
+    test: (b) =>
+      b.length >= 12 &&
+      b.toString('ascii', 4, 8) === 'ftyp' &&
+      ['mif1', 'msf1', 'heif'].includes(b.toString('ascii', 8, 12)),
+  },
 ]
 const PASTE_MAX_BYTES = 25 * 1024 * 1024
 
 /**
- * POST /modlens/paste: image bytes in, `{ path }` out. Bound to the dsh web
- * server, which listens on loopback by default; the file is private (0600)
- * in a fresh unpredictable temp dir, magic-byte checked and size-capped.
+ * Should the browser take a paste over for the model behind this selector
+ * label? Decided here, not in the browser, because only the host holds the
+ * structured model metadata: a name regex in the client called every vision
+ * model it did not recognize text-only and hijacked its native paste.
+ *
+ * The label carries no provider id, only prose plus a display name, so the
+ * host cannot know WHICH matching model is selected: a longest-match pick
+ * was still hijackable (a text route named "Current Pro" outscored a selected
+ * vision model named "Pro", because the label's own "current" prose completed
+ * the longer name). So no picking at all: the answer is true only when EVERY
+ * model whose name or id appears in the label is positively confirmed
+ * text-only. One image-capable match anywhere vetoes; a model with no
+ * declared inputModalities is UNKNOWN, not text-only; and a provider whose
+ * catalog cannot be read is unknown too, a veto rather than a shrug, since the
+ * unreadable route is exactly where the vision twin could live. Anything
+ * unresolvable answers false: the native path is the safe default, and a
+ * text-only model merely keeps its old error message.
  */
-function registerPasteRoute(ctx) {
+async function pasteTakeoverVerdict(host, label) {
+  if (typeof label !== 'string' || label.trim() === '') return false
+  // Our own wrappers convert pastes at request time with the thumbnail
+  // preserved; taking their paste over would defeat the better path.
+  if (/\(modlens vision\)/i.test(label)) return false
+  const llm = host.llm
+  if (!llm || typeof llm.listProviders !== 'function' || typeof llm.listModels !== 'function') {
+    return false
+  }
+  const lowered = label.toLowerCase()
+  let matchedAny = false
+  for (const info of llm.listProviders()) {
+    const providerId = info?.id
+    if (!providerId) continue
+    let models = []
+    try {
+      models = await llm.listModels(providerId)
+    } catch {
+      return false
+    }
+    for (const model of models) {
+      for (const candidate of [model?.name, model?.id]) {
+        if (typeof candidate !== 'string' || candidate.length === 0) continue
+        if (!lowered.includes(candidate.toLowerCase())) continue
+        // The veto has no length floor: a vision model named "AI" appears in
+        // the label just as legitimately as a long name does, and skipping
+        // short names let a longer text-only name confirm the takeover alone.
+        const modalities = model?.inputModalities
+        if (!Array.isArray(modalities) || modalities.includes('image')) {
+          return false
+        }
+        // Positive confirmation does have a floor: one- and two-character
+        // text-only names match label prose far too easily to identify the
+        // selected model.
+        if (candidate.length >= 3) {
+          matchedAny = true
+        }
+      }
+    }
+  }
+  return matchedAny
+}
+
+// Verdicts are stable for the lifetime of a model route but the inventory can
+// grow (llm-pi-ai mounts after settings load), so cache briefly, not forever.
+const PASTE_VERDICT_TTL_MS = 15_000
+const PASTE_VERDICT_CAP = 32
+
+/**
+ * The paste route. POST /modlens/paste: image bytes in, `{ path }` out; the
+ * file is private (0600) in a fresh unpredictable temp dir, magic-byte
+ * checked and size-capped. GET /modlens/paste?model=<selector label>:
+ * `{ takeover }`: the browser half asks before ever touching a paste, so a
+ * disabled route (pasteToPath: false, or no web profile) means the client
+ * stands down instead of swallowing pastes into a 404. Bound to the dsh web
+ * server, which listens on loopback by default.
+ */
+function registerPasteRoute(ctx, host) {
+  const verdicts = new Map()
+  // The cache key is only the selector label, which cannot tell two
+  // same-named models on different routes apart. A route mounting mid-TTL
+  // (llm-pi-ai lands after settings load) could therefore serve a stale
+  // verdict computed before its vision twin existed, so every topology
+  // change empties the cache at exactly the boundary that invalidates it.
+  // The epoch guards the async gap the clear cannot reach: a verdict whose
+  // computation STARTED before the event describes a registry that no longer
+  // exists, and without the counter it was written back into the just-
+  // emptied cache and served for a full TTL.
+  let topologyEpoch = 0
+  if (typeof host.on === 'function') {
+    host.on('llm/adapters-updated', () => {
+      topologyEpoch += 1
+      verdicts.clear()
+    })
+  }
   ctx.webServer.register({
     name: 'modlens-paste',
     kind: 'exact',
     path: '/modlens/paste',
     handler: async (req, res) => {
+      if (req.method === 'GET') {
+        try {
+          const label = new URL(req.url, 'http://localhost').searchParams.get('model') ?? ''
+          const cached = verdicts.get(label)
+          let takeover
+          if (cached && Date.now() - cached.at < PASTE_VERDICT_TTL_MS) {
+            takeover = cached.takeover
+          } else {
+            // Recompute while the topology moves under the computation: an
+            // answer read from a pre-event registry snapshot must be neither
+            // cached nor served. Bounded, and the give-up answer is the
+            // conservative one.
+            let attempts = 0
+            for (;;) {
+              const startedEpoch = topologyEpoch
+              takeover = await pasteTakeoverVerdict(host, label)
+              if (topologyEpoch === startedEpoch) {
+                verdicts.delete(label)
+                verdicts.set(label, { takeover, at: Date.now() })
+                if (verdicts.size > PASTE_VERDICT_CAP) {
+                  verdicts.delete(verdicts.keys().next().value)
+                }
+                break
+              }
+              attempts += 1
+              if (attempts >= 3) {
+                takeover = false
+                break
+              }
+            }
+          }
+          res.writeHead(200, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ takeover }))
+        } catch (error) {
+          res.writeHead(500, { 'content-type': 'application/json' })
+          res.end(JSON.stringify({ error: String(error?.message ?? error) }))
+        }
+        return
+      }
       if (req.method !== 'POST') {
         res.writeHead(405).end()
         return
@@ -208,7 +365,7 @@ function registerPasteRoute(ctx) {
         res.end(JSON.stringify({ path: file }))
       } catch (error) {
         res.writeHead(500, { 'content-type': 'application/json' })
-        res.end(JSON.stringify({ error: String(error && error.message ? error.message : error) }))
+        res.end(JSON.stringify({ error: String(error?.message ? error.message : error) }))
       }
     },
   })
@@ -220,15 +377,25 @@ function registerPasteRoute(ctx) {
  * text-only, so pastes are refused before any plugin hook runs. This wrapper
  * registers a NEW provider whose model metadata declares image input and
  * whose stream() is a one-line delegation back to the real route. Pick the
- * wrapped model in the model selector, paste, and the pre-step rewrite below
+ * wrapped model in the model selector, paste, and the request-time rewrite
  * turns the image into evidence text before the delegated request goes out;
  * the upstream serializer's own image rejection stays as the fail-closed
  * backstop. Guarded feature-detection: if the llm registration surface moved
  * (developer preview), the plugin quietly stays a read_image-only tool.
+ *
+ * Two modes (issue #29, design contributed by @zlycode01):
+ * - `config.upstream` set: wrap exactly that one route, legacy behavior.
+ * - unset: auto-discovery — every registered provider route carrying
+ *   wrappable text-only family models gets its own `modlens-<provider>`
+ *   wrapper, so a machine with several subscription packages (opencode-go,
+ *   zai, ...) wraps them all instead of hand-picking one. A `discover` array
+ *   of provider ids narrows the set. Routes that register late (llm-pi-ai
+ *   mounts its routes after settings load) are picked up by re-sweeping on
+ *   the registry's own `llm/adapters-updated` notification, no polling. The
+ *   deepseek-official wrap keeps its historical `deepseek-modlens` id, so a
+ *   selector remembering that provider survives the upgrade.
  */
 function registerVisionProvider(ctx, config) {
-  const upstream = config.upstream || 'deepseek-official'
-  const providerId = config.providerId || 'deepseek-modlens'
   // Wrap only the text-only members of these families. Their own vision
   // models (present or future: deepseek-vl/ocr/janus, glm-4.5v, glm-5v-...)
   // need no bridge and are excluded by name and by declared modality.
@@ -244,58 +411,144 @@ function registerVisionProvider(ctx, config) {
   if (typeof ctx.llm?.registerAdapter !== 'function' || typeof ctx.llm?.stream !== 'function') {
     return
   }
-  const withVision = (info) => ({
-    ...info,
-    provider: providerId,
-    inputModalities: ['text', 'image'],
-  })
-  try {
-    ctx.llm.registerAdapter([providerId], {
-      // Duck-typing LlmAdapter: providerInfo/providerRetryPolicy are base-class
-      // defaults a plain object must supply itself (their absence is exactly
-      // the silent registration failure this catch used to swallow).
-      providerInfo(provider) {
-        return { id: provider, name: 'DeepSeek (modlens vision)' }
-      },
-      providerRetryPolicy() {
-        return undefined
-      },
-      async listModels(_provider, signal) {
-        try {
-          const models = await ctx.llm.listModels(upstream, signal)
-          return models.filter(shouldWrap).map((model) => ({
-            ...withVision(model),
-            name: `${model.name ?? model.id} (modlens vision)`,
-          }))
-        } catch {
-          return []
-        }
-      },
-      async resolveModel(_provider, model, signal) {
-        const info = await ctx.llm.resolveModelInfo(upstream, model, signal)
-        if (!shouldWrap(info)) {
-          throw new Error(`model "${model}" is outside the modlens vision wrap scope`)
-        }
-        return { ...withVision(info), id: model }
-      },
-      stream(options) {
-        // Convert at request time, not at log time: the durable session log
-        // keeps the real image blocks (so the UI shows the paste natively),
-        // and only the wire messages carry evidence text. Cached per
-        // attachment, since the same history rides every later step.
-        const self = this
-        return (async function* () {
-          const messages = await convertImagesToEvidence(ctx, options.messages, options.signal, self)
-          yield* ctx.llm.stream({ ...options, provider: upstream, messages })
-        })()
-      },
-      evidenceCache: new Map(),
+
+  const registerWrapper = (upstream, providerId, displayName) => {
+    const withVision = (info) => ({
+      ...info,
+      provider: providerId,
+      inputModalities: ['text', 'image'],
+    })
+    try {
+      ctx.llm.registerAdapter([providerId], {
+        // Duck-typing LlmAdapter: providerInfo/providerRetryPolicy are
+        // base-class defaults a plain object must supply itself (their
+        // absence is exactly the silent registration failure this catch
+        // used to swallow).
+        providerInfo(provider) {
+          return { id: provider, name: displayName }
+        },
+        providerRetryPolicy() {
+          return undefined
+        },
+        async listModels(_provider, signal) {
+          try {
+            const models = await ctx.llm.listModels(upstream, signal)
+            return models.filter(shouldWrap).map((model) => ({
+              ...withVision(model),
+              name: `${model.name ?? model.id} (modlens vision)`,
+            }))
+          } catch {
+            return []
+          }
+        },
+        async resolveModel(_provider, model, signal) {
+          const info = await ctx.llm.resolveModelInfo(upstream, model, signal)
+          if (!shouldWrap(info)) {
+            throw new Error(`model "${model}" is outside the modlens vision wrap scope`)
+          }
+          return { ...withVision(info), id: model }
+        },
+        stream(options) {
+          // Convert at request time, not at log time: the durable session
+          // log keeps the real image blocks (so the UI shows the paste
+          // natively), and only the wire messages carry evidence text.
+          // Cached per attachment, since the same history rides every step.
+          const self = this
+          return (async function* () {
+            const messages = await convertImagesToEvidence(ctx, options.messages, options.signal, self)
+            yield* ctx.llm.stream({ ...options, provider: upstream, messages })
+          })()
+        },
+        evidenceCache: new Map(),
+      })
+      return true
+    } catch (error) {
+      // A duplicate means a concurrent or earlier registration already won:
+      // that is success for the claim, not a reason to retry forever.
+      if (/already|duplicate/i.test(String(error))) {
+        console.error(`[modlens] vision provider ${providerId} already registered, keeping the existing one`)
+        return true
+      }
+      // A preview-era surface change: degrade to the read_image-only plugin,
+      // but say so in the harness log instead of vanishing (a swallowed
+      // TypeError here once hid a missing base method).
+      console.error(`[modlens] vision provider registration skipped (${providerId}): ${error}`)
+      return false
+    }
+  }
+
+  if (config.upstream) {
+    registerWrapper(config.upstream, config.providerId || 'deepseek-modlens', 'DeepSeek (modlens vision)')
+    return
+  }
+
+  // Auto-discovery. `wrapped` guards duplicates across sweeps and the
+  // self-nesting case (our own wrappers appear in listProviders too). Two
+  // re-entrancy rules matter because registerAdapter itself broadcasts
+  // llm/adapters-updated, so every successful wrap re-triggers a sweep:
+  // an id is claimed in `wrapped` BEFORE any await (a concurrent sweep must
+  // skip it while this one is still probing), and sweeps are serialized on
+  // one promise chain so two can never interleave their probes at all.
+  const discover = Array.isArray(config.discover) ? new Set(config.discover) : null
+  const wrapped = new Set(['deepseek-modlens'])
+  const sweepOnce = async () => {
+    try {
+      await sweepBody()
+    } catch (error) {
+      // A sweep failure must never become an unhandled rejection inside the
+      // host process; the next topology notification simply tries again.
+      console.error(`[modlens] vision provider discovery sweep failed: ${error}`)
+    }
+  }
+  const sweepBody = async () => {
+    if (typeof ctx.llm.listProviders !== 'function') {
+      // Older registry surface: fall back to the single legacy wrap once.
+      if (!wrapped.has('__legacy_fallback__')) {
+        wrapped.add('__legacy_fallback__')
+        registerWrapper('deepseek-official', 'deepseek-modlens', 'DeepSeek (modlens vision)')
+      }
+      return
+    }
+    for (const info of ctx.llm.listProviders()) {
+      const id = info?.id
+      if (!id || wrapped.has(id) || String(id).startsWith('modlens-')) continue
+      if (discover && !discover.has(id)) continue
+      // Claim before the await: the probe may suspend, and the sweep a
+      // registration triggers must not probe the same id concurrently.
+      wrapped.add(id)
+      let models = []
+      try {
+        models = await ctx.llm.listModels(id)
+      } catch {
+        // Unreachable route today; release the claim so a later topology
+        // change retries it.
+        wrapped.delete(id)
+        continue
+      }
+      if (!models.some(shouldWrap)) {
+        // No eligible models yet: release, the route may gain some later.
+        wrapped.delete(id)
+        continue
+      }
+      const providerId = id === 'deepseek-official' ? 'deepseek-modlens' : `modlens-${id}`
+      const base = info.name ?? id
+      if (!registerWrapper(id, providerId, `${base} (modlens vision)`)) {
+        wrapped.delete(id)
+      }
+    }
+  }
+  // Serialize: a sweep triggered mid-sweep runs after, never interleaved.
+  // The first sweep is invoked directly so its synchronous prefix (the
+  // legacy fallback, the pre-await claims) completes during apply().
+  let sweeping = sweepOnce()
+  const sweep = () => {
+    sweeping = sweeping.then(sweepOnce, sweepOnce)
+    return sweeping
+  }
+  if (typeof ctx.on === 'function') {
+    ctx.on('llm/adapters-updated', () => {
+      void sweep()
     })
-  } catch (error) {
-    // DUPLICATE_ADAPTER or a preview-era surface change: degrade to the
-    // read_image-only plugin, but say so in the harness log instead of
-    // vanishing (a swallowed TypeError here once hid a missing base method).
-    console.error(`[modlens] vision provider registration skipped: ${error}`)
   }
 }
 
@@ -388,9 +641,7 @@ function abortableWait(promise, signal) {
 function contentHasImage(blocks) {
   return (
     Array.isArray(blocks) &&
-    blocks.some(
-      (b) => b?.type === 'image' || (b?.type === 'tool-result' && contentHasImage(b.content)),
-    )
+    blocks.some((b) => b?.type === 'image' || (b?.type === 'tool-result' && contentHasImage(b.content)))
   )
 }
 
@@ -474,9 +725,7 @@ async function readImageBlock(ctx, block, signal) {
     if (!stored?.data) {
       // Named failure instead of Buffer.from(undefined)'s bare TypeError the
       // next time a developer-preview release moves the field (issue #17).
-      throw new Error(
-        "attachments.readImage returned no 'data' bytes; the dsh attachment shape may have changed",
-      )
+      throw new Error("attachments.readImage returned no 'data' bytes; the dsh attachment shape may have changed")
     }
     const mediaType = stored.ref?.mediaType ?? block.attachment?.mediaType
     const ext = MEDIA_EXT[mediaType]

package/package.json

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

package/skills/modlens/SKILL.md

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

@@ -1,10 +1,12 @@
 # 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 > environment variables > config file > built-in defaults. The default provider with zero config is `antigravity-cli`.
+`~/.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`.
 
 ```bash
 modlens config init                     # write a starter config (refuses to overwrite; --force to redo)
@@ -54,7 +56,7 @@ Everything lives under four 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 means `antigravity-cli`.
+- `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.
 - `providers.<name>.<field>`: four fields exist, `apiKey`, `baseUrl`, `model`, and `extraBody`. 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 the schema enforcement are refused with an error naming the field. 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`.
 - `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: