@liustack/modlens 2.8.0 → 3.1.0

package/docs/commit.md

@@ -0,0 +1,76 @@
+---
+summary: 'Git Commit Conventions: Conventional Commits format, atomic commits, HEREDOC usage'
+read_when:
+  - Preparing to commit code
+  - Writing a commit message
+  - Need to understand commit conventions
+---
+
+# Git Commit Conventions
+
+## Commit Message Format
+
+```
+<type>[optional scope]: <imperative summary>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+- Use imperative mood in summary, max 72 characters
+- Do not end with a period
+- Use scope only when it adds clarity (e.g., `auth`, `api`, `ui`)
+- Mark breaking changes with `!` (e.g., `feat!:`) or a `BREAKING CHANGE:` footer
+
+## Available Types
+
+| Type | Description |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation update |
+| `style` | Formatting (no logic changes) |
+| `refactor` | Code restructuring (no behavior changes) |
+| `perf` | Performance improvement |
+| `test` | Testing related |
+| `build` | Build system or dependency changes |
+| `ci` | CI/CD changes |
+| `chore` | Maintenance tasks |
+| `revert` | Revert a commit |
+
+## Atomic Commit Principles
+
+1. One commit does one thing
+2. The repository should remain buildable/runnable after each commit
+3. Each commit should be independently revertible, affecting only that specific change
+4. Include related tests in the same commit when behavior changes
+5. Do not mix refactoring/formatting with behavior changes
+
+## Commit Workflow
+
+```bash
+# 1. Review changes
+git status --short
+git diff --staged --stat
+
+# 2. Stage selectively (avoid git add -A)
+git add <specific-files>
+
+# 3. Review what will be committed
+git diff --staged
+
+# 4. Commit (HEREDOC format)
+git commit -m "$(cat <<'EOF'
+<type>[scope]: <summary>
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Notes
+
+- Do not commit sensitive files such as `.env` or credentials
+- After a pre-commit hook failure, fix the issue and create a **new commit** (do not use `--amend`)
+- Do not push automatically; wait for user instructions

package/docs/harness-setup.md

@@ -0,0 +1,49 @@
+---
+summary: 'Harness setup: how images reach the model in Codex, Claude Code, Pi, and OpenCode'
+read_when:
+  - Setting modlens up inside a specific coding agent
+  - A pasted image is not reaching the model
+  - Understanding what recover-paste does per harness
+---
+
+# Harness setup
+
+Where a pasted image ends up differs per harness, and modlens takes a different route in each. `recover-paste` detects which harness it runs inside (process ancestry, then environment fingerprints) and reads only that harness's storage.
+
+## Codex
+
+Pasted images become real temp files, and the message carries a tag like `<image name=[Image #1] path="/tmp/xxxx.png">`. The skill reads the path out of the tag. `recover-paste` detects Codex and refuses, pointing back at the tag.
+
+One catch with text-only models: once `models.json` declares `input_modalities: ["text"]`, the Codex TUI blocks Ctrl+V paste outright. Drag the file into the terminal, type its path, or use `codex exec -i image.png "..."`.
+
+## Claude Code, Pi, OpenCode
+
+None of them writes a pasted image to a regular temp file, but all three persist the user message locally before any gateway strips it:
+
+| Harness | Storage | Notes |
+| :-- | :-- | :-- |
+| Claude Code | `~/.claude/projects/<slug>/<session>.jsonl` | images as base64. The injected `CLAUDE_CODE_SESSION_ID` targets the exact session |
+| Pi | `~/.pi/agent/sessions/--<encoded-cwd>--/*.jsonl` | same shape as Claude Code |
+| OpenCode | `~/.local/share/opencode/opencode.db` | SQLite, images as data URLs (read via `node:sqlite`) |
+
+Running a text-only model behind `ANTHROPIC_BASE_URL` in Claude Code, a pasted image arrives as a pathless `[Unsupported Image]` placeholder (on lenient gateways) or breaks the request outright ([#62009](https://github.com/anthropics/claude-code/issues/62009)). The bytes are not gone, and that is what `recover-paste` retrieves.
+
+## Skill locations
+
+| Harness | Reads skills from |
+| :-- | :-- |
+| Claude Code | `~/.claude/skills/` |
+| Codex | `~/.codex/skills/` |
+| Pi, OpenCode | `~/.agents/skills/` |
+
+Symlinks work in all of them, so linking the skill folder once keeps every agent on the latest version.
+
+## Platform support
+
+macOS and Linux are fully supported and verified in CI on Node 22 and 24.
+
+Windows runs the same CI matrix. Detection there skips the process-ancestry pass, since there is no `ps`, and falls back to the environment fingerprints above, so a harness that sets none of them reads as undetected (force it with `--harness` or `MODLENS_HARNESS`). OpenCode paste recovery is covered on Windows, including the path-separator normalization from [#11](https://github.com/liustack/modlens/issues/11): opencode records `session.directory` with forward slashes while `path.resolve` returns backslashes there, and both sides are normalized before matching. The JSONL stores (Claude Code, Pi) key off `os.homedir()` and each harness's own on-disk slug, and are exercised on POSIX. External engines (Antigravity CLI, the Claude CLI) run only where they ship a Windows build.
+
+## Gateway setups
+
+OpenCode with DeepSeek: `opencode auth login`, pick DeepSeek and paste the key (it lands in `~/.local/share/opencode/auth.json`), then set the default model in `~/.config/opencode/opencode.jsonc` to `deepseek/deepseek-v4-flash`. Pi reads its key from `~/.pi/agent/auth.json`.

package/docs/research-gemini-claude-skills.md

@@ -0,0 +1,48 @@
+---
+summary: 'Research Notes: Gemini CLI invocation mechanics + Claude Code skills model'
+read_when:
+  - Designing or updating ModLens runtime behavior
+  - Updating skill metadata/trigger strategy
+  - Verifying compatibility with Claude Code and Gemini CLI
+---
+
+> **HISTORICAL.** Written in the Gemini CLI era, before that free tier was shut
+> down in June 2026 and ModLens moved to Antigravity CLI. Kept for the reasoning
+> behind the skill-trigger design. For how things work now, read the README and
+> `troubleshooting.md`.
+
+# Research Notes: Gemini CLI + Claude Code Skills
+
+Date: 2026-02-22
+
+## 1) Gemini CLI Findings (v1 implementation impact)
+
+- Local environment verified: `gemini --version` is `0.24.0`.
+- CLI help shows `-p/--prompt` is deprecated but still supported; positional prompt is the recommended long-term mode.
+- `--output-format` supports `text | json | stream-json`; `json` is suitable for machine parsing.
+- Gemini CLI supports `@path` references in prompt. For file references, docs specify that `@` can force full content inclusion.
+- Package source inspection confirms images are handled as `inlineData` (base64 + MIME) when explicitly referenced by `@path` and passed through `read_many_files`.
+
+Implementation decision:
+- v1 keeps `gemini -p` (matching current project requirement) + `--output-format json`.
+- To avoid workspace-bound path misses, include `--include-directories <image-dir>`.
+
+## 2) Claude Code Skills Findings
+
+- Official docs define skills as foldered instruction packs with frontmatter metadata.
+- Triggering relies heavily on `name` and `description` in frontmatter.
+- Supported frontmatter controls include `allowed-tools`, `disable-model-invocation`, `model`, and `context` behaviors.
+- Skills can be project-level and chained by the agent when descriptions match user intent.
+
+Implementation decision:
+- `skills/modlens/SKILL.md` uses explicit trigger description for image tasks + non-vision model scenarios.
+- `allowed-tools: Bash` is set so the agent can deterministically call `modlens`.
+- Scope is intentionally limited to image parsing; no modsearch/modfetch logic is included.
+
+## 3) Primary Sources
+
+- Gemini CLI repo README: https://github.com/google-gemini/gemini-cli
+- Gemini CLI file management docs (`@` references): https://gemini-cli.xyz/docs/cli/file-management/
+- Claude Code skills docs: https://docs.claude.com/en/docs/claude-code/agent-skills
+- Anthropic skills examples repo: https://github.com/anthropics/skills
+- Claude help center (skills overview): https://support.claude.com/en/articles/11817219-what-are-skills

package/docs/security.md

@@ -0,0 +1,31 @@
+---
+summary: 'Security: what modlens runs, how recovered images are protected, image content as untrusted input'
+read_when:
+  - Reviewing what this tool does on your machine
+  - Recovering pastes on a shared machine
+  - Deciding how much to trust what a vision engine reports
+---
+
+# Security
+
+## Recovered images are private
+
+Images pulled out of session storage are written 0600 into a 0700 directory. By default that directory is a fresh, unpredictable `<tmpdir>/modlens-paste-*` minted per run, so nobody on a shared machine can pre-create a known path (`recursive` mkdir leaves an existing directory's mode alone) and read the bytes. A pasted screenshot can hold anything. An explicit `--out-dir` is honoured but refused when unsafe: it must be a real directory, not a symlink, owned by you, with no group or world access.
+
+Recovery is also scoped to one project: the working directory recorded inside the transcript is checked, not just the directory name, because directory slugs collide (`/tmp/a.b` and `/tmp/a-b` produce the same one). A neighbouring project's images are never handed over.
+
+## Permissions passed to engines
+
+ModLens invokes `agy` with `--dangerously-skip-permissions` because prompt mode fails in some environments without it. The prompt restricts the agent to reading the one image it was given, and instructs it to treat image content strictly as data.
+
+The `claude-cli` provider runs with `--allowedTools Read` only, so it can read local files and nothing else.
+
+Both subprocess providers also run in a throwaway directory containing only the one image, created fresh per call and removed afterward. Text inside an image is untrusted, so an injection could otherwise steer a broadly-permissioned agent into reading files that sit next to the original. A directory of one removes that reach. Passing `--workdir` opts out and runs where you point it.
+
+## Image content is untrusted input
+
+Text inside an image is untrusted, the same as a web page. A screenshot can contain instructions aimed at whatever reads it. The prompt says so explicitly, but that is mitigation, not a guarantee: analyze images you are willing to open, and prefer a sandboxed working directory when they came from elsewhere.
+
+## Evidence, not invention
+
+What the engine cannot read goes into `uncertainty` rather than being filled in. v2 dropped pixel coordinates and confidence scores entirely, because those are the two fields models fabricate most convincingly.

package/docs/testing.md

@@ -0,0 +1,29 @@
+---
+summary: 'Testing Guide: Vitest usage, co-located layout, conventions'
+read_when:
+  - Running tests
+  - Writing tests
+  - Troubleshooting test failures
+---
+
+# Testing Guide
+
+## Layout
+
+Tests are co-located with sources: every module gets an adjacent `*.test.ts` (for example `src/config.ts` and `src/config.test.ts`, `src/providers/geminiApi.ts` and `src/providers/geminiApi.test.ts`). There is no separate `test/` directory. Vite's lib build only follows the import graph from `src/main.ts`, so test files never enter `dist/`.
+
+## Commands
+
+```bash
+pnpm test                                   # run everything
+pnpm exec vitest run src/config.test.ts     # run a single file
+pnpm typecheck                              # tsc --noEmit, run before tests
+```
+
+## Conventions
+
+- No network in unit tests: stub `fetch` with `vi.stubGlobal('fetch', ...)` and clean up in `afterEach` via `vi.unstubAllGlobals()`.
+- ESM module namespaces cannot be spied on (`vi.spyOn(fs, ...)` throws). Use real temp files via `fs.mkdtempSync(path.join(os.tmpdir(), ...))` and remove them in the test.
+- To fake the home directory (config, transcripts), set `process.env.HOME` and restore it in `finally`; `os.homedir()` follows it on POSIX.
+- Providers with subprocess transports test `buildInvocation`/`parseOutput` as pure functions; API providers test `execute` against a stubbed `fetch`, asserting both the request body and the parsed result.
+- Real provider calls (agy, API keys, Claude login) are end-to-end verification, not unit tests. Keep them out of `pnpm test`.

package/docs/troubleshooting.md

@@ -0,0 +1,140 @@
+---
+summary: 'Troubleshooting: every error modlens can print, what causes it, what to do'
+read_when:
+  - A run failed and the message is not self-explanatory
+  - recover-paste found nothing, or found the wrong image
+  - Deciding whether a failure is setup, quota, or a bug
+---
+
+# Troubleshooting
+
+Start with `modlens doctor`: it checks your Node version, which providers are ready, which one will be selected and why, and the detected harness, all without spending quota or making a network request. It catches most setup problems before you read any further.
+
+Every message below is one modlens actually prints. Search this file for the words you saw.
+
+## Antigravity CLI cannot read its stored login token
+
+```
+Antigravity CLI cannot read its stored login token.
+
+On Linux this usually means the OS keyring is locked, which is normal for headless
+sessions (agents, cron, systemd, SSH without a desktop login) ...
+```
+
+agy keeps its token in the OS keyring. When the keyring is locked, agy reports itself as signed out and tries a browser sign-in that cannot finish without a display. Three ways forward:
+
+- Unlock the keyring, or run modlens from a desktop session.
+- Sign in again with `agy`.
+- Switch to a provider that needs no interactive login:
+
+```bash
+modlens config set gemini-api.apiKey <key>   # free key: https://aistudio.google.com
+modlens config set provider gemini-api
+```
+
+## Quota exhausted
+
+```
+Individual quota reached. ... Resets in 94h19m9s.
+
+agy's free tier is one weekly bucket shared by the desktop app, the CLI, and the SDK ...
+```
+
+Wait for the reset, or move to `gemini-api`, which has its own budget. Parallel subagents drain the shared bucket fast, so a heavy day can end it.
+
+## Provider CLI not found
+
+```
+Provider CLI not found: agy. Install it and sign in first.
+```
+
+The binary is not on PATH, or `--provider-bin` points somewhere wrong.
+
+```
+Working directory does not exist: /some/path
+```
+
+Different cause, same underlying error code from the OS: `--workdir` points at a directory that is not there. The binary is fine.
+
+## recover-paste found nothing
+
+```
+No pasted images found in any session storage for this directory (looked in: ...)
+```
+
+In order of likelihood:
+
+- **You are in the wrong directory.** Recovery is scoped to the project the conversation is happening in. Pass `--cwd /path/to/project`.
+- **Nothing was pasted.** Dragged files and typed paths are already real files, so there is nothing to recover: use the path directly.
+- **A setup problem is blocking one harness.** Anything blocking appears after `Blocked:` in the same message, for example OpenCode needing Node 22.13+ for `node:sqlite`.
+
+## recover-paste returned an image from another project
+
+This should not happen any more, and if it does it is a bug worth reporting. Recovery checks the working directory recorded inside the transcript, not just the directory name, because directory slugs collide (`/tmp/a.b` and `/tmp/a-b` produce the same one). Include the `harness` and `transcript` fields from the output in the issue.
+
+## Recovered the wrong image from the right project
+
+The output lists images oldest to newest, so the **last** entry is the most recent paste. Entries carry `filename` when the harness stored one: match on that when the user mentioned a name. `--count 3` gives you more to choose from.
+
+## recover-paste: overriding detection and output location
+
+`recover-paste` auto-detects which harness it runs inside (process ancestry first, then environment fingerprints) and reads only that harness's storage. Two knobs override it:
+
+- **`MODLENS_HARNESS`** forces the storage scope without a flag: `claude-code`, `pi`, `opencode`, `codex`, or `none` (scan every store, no scoping). Detection reads it first, so it wins over ancestry and env fingerprints. `--harness` does the same for a single run.
+- **`--out-dir`** sets where recovered images land. By default each run mints a fresh, unpredictable `<tmpdir>/modlens-paste-*` directory (0700, holding 0600 files), so nobody can pre-create a shared path to intercept the bytes. Point it elsewhere when the system temp dir is not where you want them. An explicit `--out-dir` that already exists is rejected unless it is a real directory (not a symlink), owned by you, with no group or world access. On Windows those ownership and permission checks are skipped, since the platform has no POSIX bits (see the Windows section below). The symlink guard still applies.
+
+## This is a Codex session
+
+```
+This is a Codex session: pasted images already exist as temp files, and each image
+tag in the message carries its path.
+```
+
+Working as intended. Codex writes pasted images to disk and puts the path in the message, so read the path out of the tag instead of recovering anything.
+
+## The openai provider rejected a result
+
+```
+OpenAI-compatible API returned JSON that does not match the vision schema
+(missing: ocr, ocr.full_text, ...)
+```
+
+That endpoint returned a partial result. Only agy, gemini-api, anthropic, and claude-cli enforce the schema server-side, so weaker gateways can produce half a result. Retry once, then switch:
+
+```bash
+modlens -i <image> -p gemini-api
+```
+
+## Config file problems
+
+```
+Cannot read /Users/you/.modlens/config.json: EACCES ... Fix the file or its permissions.
+```
+
+The file exists but is unreadable. A missing file is fine, so this is a real problem rather than something to ignore.
+
+```
+Failed to parse ... Fix or delete the file.
+```
+
+Invalid JSON. `modlens config init --force` writes a clean one, losing the old contents.
+
+## Timeouts
+
+```
+antigravity-cli provider timed out after 210000 ms.
+```
+
+Retry once with `--timeout 300000`. Dense images on agy legitimately take 15-40 seconds, and `-m gemini-3.1-pro-high` is slower still. Engines that ignore SIGTERM are escalated to SIGKILL, so a timeout returns promptly regardless.
+
+## Windows
+
+ModLens runs on Windows. Three platform differences are worth knowing:
+
+- **No POSIX permission checks.** Windows files carry no owner, group, or world bits (they read back as `0o666`/`0o777`, with access governed by ACLs), so `doctor` does not judge the config file's mode and `recover-paste --out-dir` does not reject a directory on ownership or group/world access. The symlink guard on `--out-dir` still applies.
+- **Harness detection uses environment fingerprints.** There is no `ps` to read the process tree, so detection relies on the environment variables each harness sets. If a run guesses wrong, force it with `--harness <name>` or `MODLENS_HARNESS`.
+- **Paste recovery.** OpenCode recovery is covered on Windows (issue #11). The Claude Code and Pi JSONL paths depend on `os.homedir()` and each harness's on-disk slug there. If recovery comes up empty, pass `--transcript` at the file, or drag the image into the terminal.
+
+## Still stuck
+
+Include the exact command and the full error in an issue: https://github.com/liustack/modlens/issues

package/package.json

@@ -1,15 +1,32 @@
 {
   "name": "@liustack/modlens",
-  "version": "2.8.0",
+  "version": "3.1.0",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {
     "modlens": "./dist/main.js"
   },
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "lint": "biome check src scripts",
+    "format": "biome check --write src scripts",
+    "eval": "node evals/run.mjs",
+    "release": "node scripts/release.mjs",
+    "prepublishOnly": "pnpm build",
+    "docs:list": "node scripts/docs-list.js"
+  },
   "files": [
     "dist",
+    "docs",
     "skills/modlens/SKILL.md",
-    "skills/modlens/references"
+    "skills/modlens/scripts",
+    "skills/modlens/references",
+    "CHANGELOG.md",
+    "SECURITY.md"
   ],
   "keywords": [
     "cli",
@@ -34,23 +51,17 @@
   },
   "homepage": "https://github.com/liustack/modlens#readme",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13"
   },
   "dependencies": {
     "commander": "^13.1.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.7",
     "@types/node": "^22.19.7",
+    "@vitest/coverage-v8": "^3.2.7",
     "typescript": "^5.9.3",
     "vite": "^6.4.1",
-    "vitest": "^3.2.4"
-  },
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "release": "node scripts/release.mjs",
-    "docs:list": "node scripts/docs-list.js"
+    "vitest": "^3.2.7"
   }
 }

package/skills/modlens/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: modlens
 description: "Plug-in vision for text-only models. Use whenever the user shares an image (local path, screenshot, photo, chart, document scan, or image URL) and the active model cannot see images or has no vision tool. Runs the modlens CLI to convert the image into structured JSON evidence: 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)."
-allowed-tools:
-  - Bash
+compatibility: Requires network access and one of node 22+/npx, bun/bunx, or a preinstalled modlens binary on PATH.
+allowed-tools: Bash
 ---
 
 # ModLens — Vision Bridge Skill
@@ -21,13 +21,28 @@ Do not use this skill for:
 
 ## Prerequisites
 
+Run every modlens command through the launcher bundled with this skill.
+Replace `<skill-dir>` with the directory this SKILL.md lives in:
+
 ```bash
-modlens --version
+bash <skill-dir>/scripts/run.sh -i <image-path-or-url>                              # macOS / Linux
+powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\run.ps1 -i <image>     # Windows
 ```
 
-If `modlens` is missing, run it via `npx @liustack/modlens` instead.
+The launcher finds a working way to run modlens and forwards your arguments to it unchanged. It tries, in order: a compatible `modlens` already on `PATH`, then `npx`, then `bunx`. If none of those exists it prints a JSON diagnosis to stderr and exits 78, with a `nextSteps` list for the user. Relay those steps instead of retrying. To see the full diagnosis, run `bash <skill-dir>/scripts/run.sh doctor --json` (on a machine that can launch the CLI it also chains modlens's own provider/config `doctor`).
+
+### If you cannot run the launcher script
+
+Some harnesses forbid running scripts. Reason through the same order by hand and run the first line that works (the pinned version is 3.0.0):
 
-ModLens supports five vision providers. Check what is configured:
+1. A `modlens` on `PATH` whose major version is 3 and is at least 3.0.0: `modlens <args>`.
+2. Otherwise, if `npx` exists: `npx --yes --package @liustack/modlens@3.0.0 modlens <args>`.
+3. Otherwise, if `bunx` exists: `bunx --bun @liustack/modlens@3.0.0 <args>`.
+4. Otherwise none of these runtimes is here. Tell the user no JavaScript runtime was found and that installing Node 22.13+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not claim modlens itself failed.
+
+`references/runtime.md` documents the version pin, the compatibility rule, and the diagnostic fields.
+
+ModLens supports five vision providers. Check what is configured (through the launcher, as above):
 
 ```bash
 modlens config show
@@ -43,12 +58,12 @@ modlens config show
 
 ## Command
 
+In the examples below, `modlens` means the command run through the launcher above (`bash <skill-dir>/scripts/run.sh ...`, or the PowerShell form on Windows).
+
 ```bash
 modlens -i <image-path-or-url>
 # pick a provider explicitly
 modlens -i <image> -p gemini-api
-# or without a global install
-npx @liustack/modlens -i <image-path-or-url>
 ```
 
 Optional flags:
@@ -101,7 +116,7 @@ Structure is enforced by schema on antigravity-cli and claude-cli (`--json-schem
 
 ## Failure Handling
 
-Every error this CLI prints is catalogued with its cause and fix in the project's `docs/troubleshooting.md`. Read the message first: most of them already name the fix.
+Every error this CLI prints names its cause, and most already name the fix, so read the message first.
 
 - `Provider CLI not found`: Antigravity CLI is not installed. Install it, or switch provider: `-p gemini-api`.
 - Missing key errors name the exact env var and `config set` command to run. Relay that to the user.

package/skills/modlens/references/cli.md

@@ -0,0 +1,77 @@
+# ModLens CLI manual
+
+The skill drives this CLI through its launcher. This page is for running it directly.
+
+## Direct usage
+
+With the skill installed you do not type commands: paste an image or drop a path, ask anything, and it fires on its own. By hand:
+
+```bash
+modlens -i screenshot.png                       # local image
+modlens -i https://example.com/chart.png        # remote image
+modlens -i chart.png --prompt "focus on axes"   # extra focus
+modlens recover-paste                           # pull a pasted image into a file
+```
+
+Output is a fixed JSON shape:
+
+```json
+{
+  "image": "/path/to/screenshot.png",
+  "provider": "gemini-api",
+  "result": {
+    "summary": "A workflow diagram with four nodes connected by labeled arrows.",
+    "ocr": { "full_text": "/shaping\nBEFORE YOU BUILD\n...", "lines": [] },
+    "layout": { "regions": [{ "reading_order": 1, "type": "title", "text": "/shaping" }] },
+    "uncertainty": []
+  },
+  "meta": {
+    "generatedAt": "2026-08-06T12:00:00.000Z",
+    "model": "gemini-3.6-flash",
+    "conversationId": null,
+    "durationSeconds": 6.4,
+    "usage": { "promptTokenCount": 1234, "candidatesTokenCount": 567 }
+  }
+}
+```
+
+`meta` records how the result was produced: when (`generatedAt`), which `model`, the provider's `conversationId` when it has one, wall-clock `durationSeconds`, and the raw `usage` the provider reported (shape varies by provider, `null` when none).
+
+## Flags
+
+`modlens analyze` (the default command):
+
+| Flag | Meaning | Default |
+| :-- | :-- | :-- |
+| `-i, --input <path\|url>` | Image to analyze (required) | |
+| `-p, --provider <name>` | Vision provider | `antigravity-cli` |
+| `-m, --model <name>` | Provider model | per provider (below) |
+| `-o, --output <path>` | Also write JSON to a file | |
+| `--prompt <text>` | Extra focus | |
+| `--timeout <ms>` | Provider timeout | `180000` |
+| `--provider-bin <path>` | Provider binary path | `agy` / `claude` |
+| `--workdir <path>` | Working directory for the provider | a fresh isolated directory per run |
+
+The default `-m` model depends on the provider:
+
+| Provider | Default model |
+| :-- | :-- |
+| `antigravity-cli` (default) | `gemini-3.6-flash-low` |
+| `gemini-api` | `gemini-3.6-flash` |
+| `anthropic` | `claude-haiku-4-5-20251001` |
+| `claude-cli` | `haiku` |
+| `openai` | none, `-m` is required |
+
+`modlens recover-paste`:
+
+| Flag | Meaning | Default |
+| :-- | :-- | :-- |
+| `--count <n>` | How many recent pasted images to recover | `1` |
+| `--out-dir <path>` | Where to write recovered images | a fresh private `<tmpdir>/modlens-paste-*` per run |
+| `--session <id>` | Session id for exact targeting | auto-detect |
+| `--transcript <path>` | Explicit transcript `.jsonl` or `.db` (overrides `--session`) | |
+| `--harness <name>` | Force storage scope: `claude-code`, `pi`, `opencode`, `none` | auto-detect |
+| `--cwd <path>` | Project directory the image was pasted in | current directory |
+
+Five providers: `antigravity-cli` (default, no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (uses your existing Claude subscription). Two more subcommands: `modlens config <init|set|show>`, and `modlens doctor` (checks Node, provider readiness, which provider will be selected and why, and the detected harness, without spending quota or touching the network. Add `--json` for a machine-readable report).
+

package/skills/modlens/references/configure.md

@@ -15,6 +15,40 @@ modlens config set <provider>.<field> <value>   # fields: apiKey, baseUrl, model
 
 `config set` writes the file with 0600 permissions.
 
+## The file's exact shape
+
+Everything lives under two top-level keys, both optional. 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",
+  "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"
+    },
+    "anthropic": { "apiKey": "sk-ant-..." },
+    "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`, `claude-code` for `claude-cli`). Empty or absent means `antigravity-cli`.
+- `providers.<name>.<field>`: only three fields exist, `apiKey`, `baseUrl`, `model`. 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.
+- Environment variables override the file for these bindings: `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`. Nothing else is read from the environment except `MODLENS_HARNESS` (paste-recovery scope, unrelated to this file).
+- 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)
@@ -61,6 +95,8 @@ 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.
 
+**`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.
+
 ### 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`.