@liustack/modlens 2.8.0 → 3.0.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,43 @@
+---
+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.
+
+## 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,132 @@
+---
+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.
+
+## 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.
+
+## Still stuck
+
+Include the exact command and the full error in an issue: https://github.com/liustack/modlens/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liustack/modlens",
-  "version": "2.8.0",
+  "version": "3.0.0",
   "description": "Plug-in vision for text-only LLMs, powered by the free Antigravity CLI",
   "type": "module",
   "bin": {
@@ -8,8 +8,11 @@
   },
   "files": [
     "dist",
+    "docs",
     "skills/modlens/SKILL.md",
-    "skills/modlens/references"
+    "skills/modlens/references",
+    "CHANGELOG.md",
+    "SECURITY.md"
   ],
   "keywords": [
     "cli",
@@ -34,22 +37,28 @@
   },
   "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"
+    "vitest": "^3.2.7"
   },
   "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",
     "docs:list": "node scripts/docs-list.js"
   }

package/skills/modlens/references/configure.md

@@ -61,6 +61,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`.