@liustack/modlens 2.8.0 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,186 @@
+# Changelog
+
+## 3.0.0 - 2026-08-06
+
+A code-review pass. Two user-facing bugs, a stack of doc corrections, and the tooling a public repo is expected to carry.
+
+- BREAKING: requires Node 22.13+. The floor was Node 18 with a special note that OpenCode paste recovery needed 22.13 for `node:sqlite`. That split is gone: 22.13 is the single minimum, `node:sqlite` is always available, and the CI matrix now runs Node 22 and 24 (dropping 18 and 20). The defensive runtime guard in the OpenCode adapter and the `describe.skipIf` in its tests stay, harmless, in case someone runs below the stated floor. README (both languages), CONTRIBUTING, AGENTS, and the harness doc drop the per-feature Node caveat.
+- New `evals/` scaffolding makes "every experiment leaves a reproducible artifact" a format and a tool rather than a slogan. Seed cases (dense bilingual text, a dense chart, a clean diagram, a stylized banner, and a dependency-free generated prompt-injection image) live under `evals/cases/`, and `pnpm eval` drives the built CLI over them, writing one evidence artifact per case (command, tool version and commit, provider and model, input SHA-256, raw output, expected points and scoring, latency, usage, errors and degradation) to a git-ignored `evals/results/<date>/`. It reports transcription and schema pass rates and a latency summary, and `--dry-run` validates cases without spending quota. Local and on-demand by design: it spends real quota and never runs in CI.
+- New `modlens doctor` command diagnoses local config and routing without spending a byte of provider quota or making a network request. It reports the Node version against the 22.13 floor, node:sqlite availability, each provider's readiness (agy/claude on PATH, and whether each API key comes from env or the config file, with a copy-paste fix for what is missing), which provider will be selected and from which layer (flag, config, or default), the detected harness and whether the verdict came from process ancestry or an environment fingerprint, and the config file's path and permission bits. Add `--json` for a machine-readable report. Troubleshooting now opens by pointing at it.
+- OpenCode paste recovery works on Windows again (issue #11). Matching a session compared `path.resolve(cwd)`, which is backslash-separated on Windows, against opencode's forward-slash `session.directory`, so the equality and both prefix checks missed every row and recovery returned nothing. The v2.8.0 change that turned `--session` into a directory-narrowing filter meant the old `--session` workaround stopped helping too. Both sides are normalized to forward slashes before matching now, with the LIKE wildcard escaping preserved.
+- A provider that ignores SIGTERM on timeout is now actually killed. The SIGKILL backstop checked `child.killed`, which turns true the moment a signal is delivered, not when the process exits, so a child that trapped SIGTERM read as already dead and was never escalated. It now tracks whether the process has exited and sends SIGKILL when it has not.
+- The published npm package now includes `docs/`, `CHANGELOG.md`, and `SECURITY.md`. The README links to the harness, security, and troubleshooting docs, but the `files` allow-list left them out of the tarball, so those links 404'd for anyone reading the package on npm.
+- CI now runs on macOS as well as Linux across the Node 18/20/22 matrix, so a macOS-only regression (path handling, `mkdtemp`, file modes) is caught before release.
+- `vitest` moves to 3.2.7 to match `@vitest/coverage-v8`, silencing the version-mismatch warning `pnpm coverage` printed when the two drifted.
+- The `node:sqlite` requirement for OpenCode paste recovery is stated correctly: Node **22.13+**, not 22.5. The module was added in 22.5 but behind `--experimental-sqlite`, and only became available without a flag in 22.13. Both READMEs, CONTRIBUTING, the harness and troubleshooting docs, the runtime error message, and the CI comment now agree.
+- Publishing happens in exactly one place now. `scripts/release.mjs` and the tag-triggered `release.yml` workflow both ran `npm publish` and created the GitHub Release, a race that could double-publish or leave a half-finished release. `release.mjs` keeps every guard, the version bump, commit, tag, and push, but stops at the tag: pushing it hands off to CI, which publishes with provenance and cuts the GitHub Release from the matching CHANGELOG section.
+- The subprocess providers (`antigravity-cli`, `claude-cli`) now run in a throwaway directory holding only the input image, not in the image's own directory. `agy` runs with `--dangerously-skip-permissions`, so an injection in an image sitting beside other files could in principle steer the agent into reading them. Each call now hardlinks (or copies) the one image into a fresh `mkdtemp` directory, runs there, and removes it afterward. An explicit `--workdir` keeps the old behaviour.
+- Structural schema validation now runs for every provider, not just `openai`. The shape check that caught half-filled results lived inside the OpenAI-compatible path, so a malformed result from gemini, anthropic, agy, or claude-cli could slip through if the server-side schema was not honoured. The check moved into `schema.ts`, and the analyzer runs it over every provider's result, naming the provider when a field is missing.
+- Remote image downloads are now capped at 25 MB and their type is confirmed from the file header rather than guessed. `fetchRemoteImageBase64` read the whole response into memory with no ceiling (a memory-exhaustion vector) and trusted a server's `content-type`, defaulting to `image/jpeg` for anything else. It now rejects an oversized `content-length` up front, enforces the cap while streaming, sniffs the magic bytes (png/jpeg/gif/webp) as the authority over a faked extension or lying header, and refuses a type outside the allow list instead of relabelling it. Local reads go through the same type check.
+- `recover-paste` no longer writes to a fixed, shared `<tmpdir>/modlens-paste` by default. A `recursive` mkdir does not re-apply its mode to a directory that already exists, so on a shared machine another user could pre-create that path and read every screenshot recovered into it. Each run now mints a private `mkdtemp` directory instead. An explicit `--out-dir` is still honoured, but an existing one is rejected unless it is a real directory (not a symlink), owned by the current user, with no group or world access. Recovered files are deliberately left in place for `modlens -i` to read.
+
+- `config show` prints the effective config now, merging environment variables over the file and tagging each value file or env. Reading only the file hid keys set through `GEMINI_API_KEY` and the other bound vars, so the value modlens actually used never appeared.
+- Local image paths containing `#` or `?` keep their real extension. Routing them through `new URL()` read the character as a fragment or query and dropped the extension, mislabelling the type as JPEG.
+- The disclaimer no longer contradicts the MIT license it ships beside. It withholds warranty and endorsement without withholding the commercial-use right MIT grants, and points at the upstream engines' own terms.
+- Docs caught up with the code. Both READMEs gained `--provider-bin`, `--workdir`, a per-provider default-model table, a full `recover-paste` flag table, and the `meta` output fields, with `MODLENS_HARNESS` and `--out-dir` written up in troubleshooting. The anthropic recipe warns that `ANTHROPIC_BASE_URL` can silently reroute a vision request to a text-only gateway. AGENTS.md drops three claims that had gone stale.
+- Internals, all behavior-preserving: the duplicated JSON helpers (parse, extract, truncate) collapsed into one `util/json` module, and the 710-line `recoverPaste` split into per-harness modules. An always-true branch and a few lint findings cleared.
+- Tooling: Biome for formatting and linting on the repo's 4-space style, a Node 18/20/22 CI matrix that skips the `node:sqlite` tests where the module is unavailable, `@vitest/coverage-v8` with a `coverage` script, tests for the CLI assembly, and a tag-triggered release workflow that publishes with provenance. Adds the collaboration files a public repo expects: CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, issue and pull-request templates, and Dependabot.
+- The Chinese README's plug now invites readers to the WeChat public account rather than installing the liustack skills.
+- `release.mjs` matches the CHANGELOG again: version dots are escaped literally and the section ends at end of file, so the newest entry (and versions like `2.8.0`) match instead of being missed.
+
+## 2.8.0 - 2026-08-06
+
+- README rebuilt against how widely used projects actually write theirs: install command inside the first screen, a nav row and badges in the hero, short scannable highlights, and roughly 1,000 words instead of a long read. Harness specifics and security detail moved into `docs/harness-setup.md` and `docs/security.md`, with a Documentation table pointing at them.
+
+## 2.7.11 - 2026-08-06
+
+- Stops calling it OCR. A vision model reading an image is not OCR, which is a specific and different technology, and the word was borrowed for convenience across the README, the skill, and both articles. The prose now says what actually happens: every word in the image is transcribed. The `ocr` field in the output contract keeps its familiar name, with a note that a vision model does the reading.
+
+## 2.7.10 - 2026-08-06
+
+- README rewritten rather than patched again. The hero buried the one thing that sets this apart (you can paste) under a generic pitch, then repeated it in a feature list and again in its own section. The opening now leads with pasting, the feature list is gone as duplication, and the comparison against swapping models or running a vision MCP server sits where a reader weighing options will find it.
+
+## 2.7.9 - 2026-08-06
+
+- The flow diagram says something again. Replacing ASCII art with an abstract illustration removed the labels along with the alignment chore, which was a bad trade. It is now a rendered diagram with real labels, one per language, generated from HTML so nothing drifts.
+
+## 2.7.8 - 2026-08-06
+
+- Releases are now one command: `pnpm release <version|patch|minor|major>` refuses a dirty tree, a non-main branch, a duplicate tag, or a version with no CHANGELOG entry, then runs typecheck, tests, and build before anything irreversible happens, and finishes with tag, push, npm publish, and a GitHub release. Publishing by hand is how a version once reached npm with no changelog and no tag behind it.
+- Every previously published version now has a git tag, reconstructed from the commit that carried it.
+
+## 2.7.7 - 2026-08-05
+
+- README: leads with a scannable feature block (paste support, evidence rather than a description, honest uncertainty, no model swap, zero-key start, four harnesses) and states requirements. Adds a comparison against swapping in a multimodal model and against vision MCP servers, our own weaknesses included.
+- New `docs/troubleshooting.md`: every error this CLI prints, with cause and fix, linked from the README and the skill.
+- The ASCII flow diagram is now a real illustration. Its alignment had needed repair across several releases, which is a poor trade for a picture.
+- The Gemini CLI era research doc is marked historical so it is not read as current design.
+
+## 2.7.6 - 2026-08-05
+
+- `config init` now writes only the shape (`{"provider": "", "providers": {}}`) instead of all five providers with their fields pre-filled. Baked-in defaults in a config file silently outrank later changes to those defaults, and the placeholders hid the one decision that matters. The command prints what can be set instead.
+
+## 2.7.5 - 2026-08-05
+
+A verification pass on the 2.7.4 fixes (same external reviewer) found four that did not hold and three bugs the fixes themselves introduced. All seven are addressed here.
+
+**Fixes that did not hold**
+
+- Unreadable config files still became empty configs: the 2.7.4 edit never applied, because this file is indented differently from its sibling project. Permissions errors now surface.
+- Harness detection still matched a flag's value: `node --require pi app.js` read as Pi. The script behind a node shim must now look like a path to a script.
+- agy log evidence was scoped by file mtime alone, so a concurrent call or an older failure in the same file still misdiagnosed this run. Lines are now filtered by their own glog timestamps.
+- The openai schema check only looked at top-level keys, so `{"ocr":{}}` passed. Nested required fields are checked.
+
+**Bugs introduced by the 2.7.4 fixes**
+
+- `transcriptBelongsTo` returned on the first recorded cwd, so a transcript whose first line matched could still hand over another project's images. Any matching line now decides, and a transcript with cwd lines that all mismatch is rejected.
+- That check also read every transcript in full, then the image scan read it again. Each file is read once.
+- The alias table added for config lookups was written by hand and did not match the real provider aliases (`claude` resolves to `anthropic`, not `claude-cli`, and `claude-code` and `openai-compat` were missing), so settings landed on the wrong provider. The table now comes from the provider registry.
+- `--transcript` skipped harness validation, so `--harness bogus` silently parsed the file as Claude Code.
+
+## 2.7.4 - 2026-08-05
+
+Correctness and privacy pass after an external review (gpt-5.6-sol) that proved every finding with a probe.
+
+**Recovering the wrong project's images**
+
+- OpenCode directory matching passed the project path straight into SQL `LIKE`, where `_` and `%` are wildcards, so a path containing either matched other projects. Patterns are escaped now.
+- `--session <id>` dropped the directory condition entirely, and session slugs are not unique across projects. The reviewer found two colliding slugs in a real local database. A session now narrows the directory match instead of replacing it.
+- Claude Code and Pi directory slugs are lossy: `/tmp/project.alpha` and `/tmp/project-alpha` produce the same slug. Both harnesses record the real cwd inside the transcript, which is now checked before a transcript is trusted.
+
+**Privacy**
+
+- Recovered images landed as 0644 inside a 0755 directory, so on a shared `/tmp` any local user could read them. They are written 0600 into a 0700 directory, and re-chmodded because the filenames are content hashes and an existing file keeps its old mode.
+
+**Correctness**
+
+- A successful run could be reported as a timeout: the timer stayed armed while output drained, so a slow drain turned exit code 0 into a timeout error. It is cleared when the child exits.
+- A timeout sent one SIGTERM and then waited, so an engine ignoring signals hung the CLI. It now settles immediately and escalates to SIGKILL.
+- Output decoding kept no state across chunks, so a multi-byte character split across a chunk boundary became replacement characters.
+- The OpenCode "needs Node 22.5" message was swallowed by an empty catch, leaving only "no pasted images". Setup problems now travel with the error.
+- `--harness` was ignored when `--transcript` was given, so a copied Pi transcript was parsed as Claude Code. `--transcript <db>` also ignored `--cwd`.
+- Harness detection scanned the first eight command tokens, so a command that merely mentioned "pi" in its arguments was detected as Pi. Only the executable, plus the script path behind a node shim, is read now.
+- agy log evidence was accepted if the file was under two minutes old, which let a previous quota failure or a concurrent agy call misdiagnose an unrelated error. Evidence must now postdate the start of this run.
+- The `claude-cli` provider inherited a 30 second kill grace meant for agy's own `--print-timeout`, silently extending `--timeout`. The grace applies only to engines with an internal deadline.
+- The openai provider's "schema validation" accepted `{"summary":"x","ocr":null}` and anything missing layout, semantics, visual, or uncertainty. All required fields are checked.
+- Settings saved under a provider alias (`config set gemini.apiKey`) were invisible once the name resolved to `gemini-api`.
+- An unmapped image type was relabelled `.png`, so downstream tools reading the extension got the wrong type.
+- `ENOENT` from spawn was always reported as a missing CLI, even when the real cause was a missing working directory.
+- A config file that exists but cannot be read (permissions) silently became an empty config.
+
+## 2.7.3 - 2026-08-05
+
+- Fix: a failing `antigravity-cli` run now explains itself instead of reporting a bare exit code ([#3](https://github.com/liustack/modlens/issues/3), thanks @mtongle). Providers gained a `describeFailure` hook, and the agy provider uses it to surface agy's own error text and classify the two failures users actually hit: a locked OS keyring in headless sessions (the report's case, where agy claims to be signed out) and an exhausted weekly quota. Both messages end with the exact commands to switch to a keyless, quota-independent provider. Diagnosis only reads agy's log when this run produced an agy error envelope and the log is fresh, so stale logs cannot misdiagnose an unrelated failure.
+- Docs: README leads with paste support, recommends the free AI Studio key over the slower agy default, and documents that the skill configures modlens for you on request.
+
+## 2.7.2 - 2026-08-05
+
+- Fix: runs with the `antigravity-cli` provider hung until the timeout killed them ([#1](https://github.com/liustack/modlens/issues/1), thanks @hawkmor for the diagnosis). agy exits cleanly but leaves a language server holding the inherited stdout pipe, so the child's `close` event never fires. The provider run now settles on `exit` plus a short drain window, and releases the pipes afterwards so a lingering descendant cannot keep the CLI process alive either.
+
+## 2.7.1 - 2026-08-04
+
+- Docs: per-harness skill discovery paths (`~/.claude/skills/`, `~/.codex/skills/`, `~/.agents/skills/` for Pi and OpenCode), OpenCode + DeepSeek setup recipe, and the four-harness live verification matrix (Claude Code session-id recovery, OpenCode full skill loop on DeepSeek, Pi store isolation, Codex refusal).
+
+## 2.7.0 - 2026-08-04
+
+- `recover-paste` now identifies the harness it is running inside before touching any storage: process ancestry first (the nearest known harness among parent processes, which also resolves nested setups to the innermost tool), env fingerprints second (`CLAUDECODE`, `PI_CODING_AGENT`, `CODEX_THREAD_ID`). Detection scopes recovery to that harness's store only, so another tool's stale sessions can never hijack a paste; Codex is refused outright with path-tag guidance. `--harness <name|none>` overrides, output gains a `detected` field.
+- In Claude Code, recovery auto-targets the exact session from the injected `CLAUDE_CODE_SESSION_ID`, falling back to newest-image scanning when that transcript holds no images (subagent sessions).
+
+## 2.6.1 - 2026-08-03
+
+- Fix: opencode runs shell commands at the repo root while sessions record the directory they were launched in. Exact directory matching made recovery miss the real paste and fall through to stale Claude Code transcripts of the same project, recovering the wrong images (caught in a live session). Directories now match by prefix in both directions, and recovery is scoped to the single opencode session owning the newest image.
+- Recovered entries report `filename` (the original attachment name) when the harness stored one.
+- Skill: recovered paths are oldest to newest so analyze the last one first, match `filename` when present, run every command yourself instead of delegating to the user, and treat a `harness` value that differs from the harness you are running in as suspect.
+
+## 2.6.0 - 2026-08-03
+
+- `recover-paste` now supports OpenCode: pasted/attached images are read from its SQLite store (`~/.local/share/opencode/opencode.db`) via node:sqlite (Node 22.5+, lazy-loaded so older Nodes keep the JSONL harnesses). Recovery internals refactored into per-harness adapters (Claude Code, Pi, OpenCode) sharing one newest-image picker. Verified against a real opencode + deepseek session.
+
+## 2.5.0 - 2026-08-03
+
+- `recover-paste` now supports Pi (Armin Ronacher's coding agent) alongside Claude Code: both store pasted images as base64 in per-session JSONL files, and recovery auto-detects which harness owns the newest pasted image. Verified live against a real pi + deepseek session. Result JSON gains a `harness` field.
+
+## 2.4.3 - 2026-08-03
+
+- Docs: the Claude Code paste-recovery loop is now marked as verified end to end in a real DeepSeek-gateway session (placeholder spotted, file recovered by session id, image answered in full).
+
+## 2.4.2 - 2026-08-03
+
+- Project hygiene: CHANGELOG, GitHub Actions CI, AGENTS.md rewrite, testing guide rewrite, recover-paste and config command reference in READMEs, dead code removal, auto-externalized Node built-ins in the build.
+
+## 2.4.1 - 2026-08-03
+
+- Skill: path-finding is now a per-harness decision tree. Codex path tags never trigger transcript recovery, unknown harnesses are told to ask for a path instead of guessing.
+
+## 2.4.0 - 2026-08-03
+
+- `recover-paste --session <id>`: exact transcript targeting. Skills relay `${CLAUDE_SESSION_ID}` (substituted by Claude Code since v2.1.9); without it, recovery falls back to newest-image-timestamp scanning.
+
+## 2.3.2 - 2026-08-03
+
+- Tests co-located with sources, one module one `.test.ts` (31 to 50 tests). First direct coverage for `prompt` and `imageInput`.
+- Skill explains why `recover-paste` takes no session id.
+
+## 2.3.1 - 2026-08-03
+
+- `recover-paste` locates the session by newest pasted-image timestamp instead of file mtime, immune to concurrent sessions in the same project.
+
+## 2.3.0 - 2026-08-03
+
+- New `recover-paste` command: recovers images pasted into Claude Code from the local session transcript (they never hit a regular temp file), prints real file paths as JSON.
+
+## 2.2.0 - 2026-08-03
+
+- New `claude-cli` provider: rides an existing Claude Code login, `--allowedTools Read` only, `--json-schema` enforced, haiku default.
+- Skill routes configuration questions to `references/configure.md`.
+
+## 2.1.0 - 2026-08-02
+
+- Three direct-API providers: `gemini-api` (free AI Studio key, `responseJsonSchema`), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic` (forced tool call, Claude Haiku default). 3-10s per image versus 15-40s agent loops.
+- Layered config: `~/.modlens/config.json` via `config init/set/show` (0600, masked), env vars override the file, flags override everything.
+
+## 2.0.0 - 2026-08-01
+
+- Breaking: vision engine migrated from the discontinued Gemini CLI free tier to Antigravity CLI (`agy`).
+- Provider layer (`buildInvocation` + `parseOutput`), schema-enforced structured output via `--json-schema`, no markdown scraping.
+- Output contract v2: `result`/`meta` envelope; fabricated bbox and confidence fields dropped.

package/README.md

@@ -27,15 +27,15 @@ npx -y skills add liustack/modlens             # install the skill
 npx @liustack/modlens -i screenshot.png        # or just use the CLI
 ```
 
-Models like DeepSeek-V4-Flash are cheap, fast, capable, and blind. Throw one a screenshot of an error and it sees nothing. ModLens turns the image into evidence it can quote, and **you just paste**: every other bridge makes you save a file and report its path, while ModLens pulls the pasted image back out of session storage.
+Models like DeepSeek-V4-Flash are cheap, fast, capable, and blind. Throw one a screenshot of an error and it sees nothing. ModLens hands the image to a real vision engine and brings back evidence your model can quote: every word transcribed, the layout mapped, the doubts declared. And **you just paste**: other bridges make you save a file and report its path, while ModLens pulls the pasted image straight back out of session storage.
 
 ## Highlights
 
-- **Pasting works.** Vision MCP servers cannot catch a paste (the client encodes and sends it the moment it lands), so ModLens reads it from local session storage instead.
-- **Evidence, not an impression.** Every word transcribed, layout cut into regions in reading order, entities and relations listed, all of it quotable.
-- **It says when it cannot read something.** Uncertain parts land in `uncertainty`. Pixel coordinates and confidence scores, the two things models fabricate most, were dropped in v2.
+- **Pasting works.** A pasted image never becomes a file, which is why other vision bridges cannot see it. ModLens recovers it from the harness's local session storage instead.
+- **Evidence, not an impression.** Every word transcribed, layout cut into regions in reading order, entities and relations listed. Your model quotes specifics instead of trusting a vibe.
+- **It says when it cannot read something.** Uncertain parts land in `uncertainty`. Pixel coordinates and confidence scores, the two things vision models fabricate most, were deliberately dropped.
 - **Keep your model.** You picked it for price and reasoning, not eyesight. That choice stays.
-- **Starts with no key.** agy needs none. A free Gemini key makes it 5 to 10 seconds per image.
+- **Starts with no key.** The default engine (Antigravity CLI) needs none. A free Gemini key cuts a read to 5-10 seconds.
 - **Install once, works everywhere.** Verified on real machines in Claude Code, Codex, Pi, and OpenCode.
 
 ## Installation
@@ -46,20 +46,20 @@ npx -y skills add liustack/modlens
 
 Or tell your agent: "Install the skill from https://github.com/liustack/modlens".
 
-Then give it a vision engine. A free **[AI Studio](https://aistudio.google.com) Gemini key** is the fast answer (three minutes, no credit card, 5 to 10 seconds per image):
+Then give it a vision engine. A free **[AI Studio](https://aistudio.google.com) Gemini key** is the fast answer (three minutes, no credit card, 5-10 seconds per image):
 
 ```bash
 modlens config set gemini-api.apiKey <key>
 modlens config set provider gemini-api
 ```
 
-Skipping the sign-up is fine: **Antigravity CLI** works with no key, it is just slower (15 to 40 seconds) with a tight free quota:
+Skipping the sign-up is fine: **Antigravity CLI** works with no key, it is just slower (15-40 seconds) with a tight free quota:
 
 ```bash
 curl -fsSL https://antigravity.google/cli/install.sh | bash && agy   # sign in, then exit
 ```
 
-Requires Node 18+ (22.5+ for OpenCode paste recovery), macOS or Linux.
+Requires Node 22.13+, macOS or Linux.
 
 ## Usage
 
@@ -83,24 +83,56 @@ Output is a fixed JSON shape:
     "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 }
   }
 }
 ```
 
-Inside the Codex desktop app: drop in a tweet screenshot and a text-only DeepSeek reads the caption, the engagement numbers (2.9K replies, 270K likes, 5M views), even the image's alt text. Where the resolution runs out, it says so.
+`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).
+
+## See it work
+
+Unedited runs, all driving a text-only DeepSeek-V4-Flash.
+
+A tweet screenshot in the Codex desktop app. It reads the caption, the engagement numbers (2.9K replies, 270K likes, 5M views), even the image's alt text. Where the resolution runs out, it says so instead of guessing.
 
 ![Text-only DeepSeek reading a tweet screenshot in full detail via ModLens](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-app.png)
 
+Three images pasted at once. The model queues them up and reads them one by one, design intent included.
+
+![Three images dropped together, read one by one](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
+
+The stress test: a scatter plot of 128 models. It identifies the chart, both axes, the log scale, and picks the one highlighted point out of the crowd with its coordinates (about $0.028, intelligence score 50). Dense charts are where vision models usually fold.
+
+![The 128-model scatter plot, highlighted point read with exact coordinates](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-chart.png)
+
+And the paste path, end to end: Claude Code on a DeepSeek gateway, two images pasted straight into the chat. The UI shows nothing but placeholders, the skill recovers both from session storage and reads them, down to the color values on a slide cover.
+
+![Two pasted images recovered from session storage and read in a gateway Claude Code session](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-claude-paste-recovery.png)
+
 ## How it works
 
 ![A text-only model hands an image to the vision engine through the modlens skill and gets structured JSON evidence back](https://raw.githubusercontent.com/liustack/modlens/main/assets/flow.en.png)
 
-Pasting works here because of a different route. The paste itself is handled end to end by the client: the image is encoded and sent the moment it lands, so an MCP server never gets a chance, which is why their docs tell you to save a file and report the path. But before those bytes go anywhere, the harness has already written them to local session storage, and that is where `recover-paste` goes. Each harness stores them differently (JSONL in Claude Code and Pi, SQLite in OpenCode, real temp files in Codex): see [harness setup](docs/harness-setup.md).
+No magic, four steps:
+
+1. The skill triggers when an image shows up: a path, a URL, or the bare placeholder a text-only model gets left with after a paste.
+2. It runs the `modlens` CLI, which hands the image to a vision engine. Five to choose from, the free Antigravity CLI by default.
+3. The engine's reading is forced into a fixed JSON schema: transcription, layout, semantics, uncertainty. Output that does not match the schema is rejected, never patched up.
+4. Your model quotes the evidence and answers.
+
+The paste trick is the part nobody else does. A pasted image is handled inside the client: encoded and sent the moment it lands, gone before any outside tool can touch it, which is why other bridges tell you to save a file and report the path. But before those bytes leave, the harness has already written them into its local session record. `recover-paste` reads them back from there: JSONL in Claude Code and Pi, SQLite in OpenCode, and Codex needs no recovery at all because its pastes already land as temp files. Details in [harness setup](docs/harness-setup.md).
 
-| | Swap in a multimodal model | Vision MCP servers | ModLens |
+| | Swap in a multimodal model | Other vision bridges (MCP servers etc.) | ModLens |
 | :-- | :-- | :-- | :-- |
 | Your chosen model | has to change | stays | stays |
-| An image pasted into the chat | visible if the model supports it | out of reach | handled directly |
+| An image pasted into the chat | visible if the model supports it | out of reach | recovered and read |
 | What you get back | the model's own reading | usually a description | transcription, layout regions, entities |
 | Where it cannot read | may invent | may invent | says so in `uncertainty` |
 | Cost | multimodal model pricing | usually per API call | agy's free quota or a free Gemini key |
@@ -109,16 +141,41 @@ The weaknesses, in the same place: agy's free tier is a weekly quota and heavy u
 
 ## CLI reference
 
+`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 | `gemini-3.6-flash-low` |
+| `-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 | image's directory |
+
+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 |
 
-Five providers: `antigravity-cli` (default, no key), `gemini-api` (fastest free route), `openai` (any OpenAI-compatible multimodal endpoint), `anthropic`, and `claude-cli` (rides your Claude subscription). Two more subcommands: `modlens config <init|set|show>` and `modlens recover-paste`.
+`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` (rides your 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).
 
 ## Documentation
 
@@ -132,6 +189,13 @@ Five providers: `antigravity-cli` (default, no key), `gemini-api` (fastest free
 | [CHANGELOG](CHANGELOG.md) | Finding what changed in a version |
 | [AGENTS.md](AGENTS.md) | Working on this codebase |
 
+## Contributing
+
+ModLens does not accept pull requests. It is a small tool with one pair of hands on it, and every line stays author-owned: that tight loop is what keeps it dependable. Two ways to contribute that genuinely help:
+
+- **[Open an issue](https://github.com/liustack/modlens/issues).** Bugs, ideas, a confusing error, docs that read wrong. Issues get read and drive what gets built.
+- **Fork it.** MIT means your copy is fully yours: rename it, rewire it, ship it.
+
 ## Shameless plug
 
 This project runs on LIUSTACK Skills: `shaping` before you build, `coding` while you build, `dig` when it breaks, `snapshot` when you hand off. Lighter than Superpowers, and stronger.
@@ -144,7 +208,7 @@ npx -y skills add liustack/liustack -g
 
 ## Disclaimer
 
-For personal study and experimentation, not commercial use. Antigravity CLI usage is bound by your own Google account terms and quota.
+Provided as-is under the MIT License below. The author makes no warranty and gives no endorsement for any particular use, commercial use included. Your use of upstream engines (Antigravity CLI, the Gemini, OpenAI, and Anthropic APIs, and any OpenAI-compatible endpoint) is governed by their own terms and quotas, which you are responsible for.
 
 ## License
 

package/README.zh-CN.md

@@ -27,15 +27,15 @@ npx -y skills add liustack/modlens                # 装 skill
 npx @liustack/modlens -i screenshot.png           # 或者直接当 CLI 用
 ```
 
-DeepSeek-V4-Flash 这类模型便宜、快、能打，唯独看不见图。你甩过去一张报错截图，它一片漆黑。ModLens 把图读成能引用的证据交给它，而且**你直接粘贴就行**：别的方案都要你先存成文件再报路径，ModLens 从会话存储里把粘贴的图捞回来。
+DeepSeek-V4-Flash 这类模型便宜、快、能打，唯独看不见图。你甩过去一张报错截图，它一片漆黑。ModLens 把图交给真正的视觉引擎，带回你的模型能引用的证据：图里的字一句不落地转录，版面切好，读不准的地方明说。而且**你直接粘贴就行**：别的方案都要你先存成文件再报路径，ModLens 直接从会话存储里把粘贴的图捞回来。
 
 ## 亮点
 
-- **粘贴就能用。** 识图类 MCP server 接不住粘贴（图一进对话框就被客户端发走了），ModLens 从本地会话存储里捞。
-- **给的是证据，不是印象。** 图里的字一句不落地转录、版面按阅读顺序切块、实体和关系单列，模型能引用具体内容。
-- **读不准就说读不准。** 拿不准的地方进 `uncertainty`。像素坐标和置信度分数这两样模型最爱编的，v2 直接删了。
+- **粘贴就能用。** 粘贴的图从来不会落成文件，所以别的识图外挂都接不住。ModLens 换了条路，从 harness 的本地会话存储里捞。
+- **给的是证据，不是印象。** 全文转录、版面按阅读顺序切块、实体和关系单列。模型引用的是具体内容，不是大概感觉。
+- **读不准就说读不准。** 拿不准的地方进 `uncertainty`。像素坐标和置信度分数这两样视觉模型最爱编的字段，v2 直接删了。
 - **模型不用换。** 你选 DeepSeek 图的是价格和推理，不是视力，这个选择不用动。
-- **零 key 起步。** agy 不要 key；想快就领个免费 Gemini key，识图 5 到 10 秒。
+- **零 key 起步。** 默认引擎 Antigravity CLI 不要 key；领个免费 Gemini key，识图缩到 5 到 10 秒。
 - **一次装好，处处能用。** Claude Code、Codex、Pi、OpenCode 都在真机上验证过。
 
 ## 安装
@@ -59,7 +59,7 @@ modlens config set provider gemini-api
 curl -fsSL https://antigravity.google/cli/install.sh | bash && agy   # 浏览器登录后退出
 ```
 
-需要 Node 18+（OpenCode 的粘贴恢复需要 22.5+），macOS 或 Linux。
+需要 Node 22.13+，macOS 或 Linux。
 
 ## 用法
 
@@ -83,24 +83,56 @@ modlens recover-paste                          # 把刚粘贴的图捞成文件
     "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 }
   }
 }
 ```
 
-Codex 桌面 App 里的实拍：丢一张推文截图，纯文本的 DeepSeek 读出了配文、互动数据（2.9K 回复、270K 点赞、5M 浏览），连图片的 alt 文字都没放过。分辨率不够的地方它老实说读不清。
+`meta` 记录这份结果是怎么来的：生成时间（`generatedAt`）、用的 `model`、provider 给的 `conversationId`（没有就是 null）、实际耗时 `durationSeconds`、以及 provider 报告的原始 `usage`（结构随 provider 而定，没有就是 null）。
+
+## 实测
+
+以下全是原样实录，驱动的都是纯文本的 DeepSeek-V4-Flash。
+
+Codex 桌面 App 里丢一张推文截图。配文、互动数据（2.9K 回复、270K 点赞、5M 浏览），连图片的 alt 文字都没放过。分辨率不够的地方它老实说读不清，不硬编。
 
 ![纯文本 DeepSeek 通过 ModLens 读出推文截图的全部细节](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-app.png)
 
+一次粘三张图。模型自己排队逐张读，连设计意图都点出来了。
+
+![一次丢三张图，逐张读取](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-batch.png)
+
+压力测试：128 个模型的散点图。它认出了图表类型、双轴定义、对数刻度，还把高亮的那个点从点堆里精准拎出来（成本约 $0.028，智能指数 50）。密集图表是识图模型最容易露怯的地方。
+
+![128 个模型的散点图，精确读出高亮点的坐标](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-codex-chart.png)
+
+粘贴链路的端到端实录：接了 DeepSeek 的 Claude Code，两张图直接粘进对话。界面里只剩占位符，skill 从会话存储把两张图都捞回来读了，连 PPT 封面的配色色值都读出来了。
+
+![接了 DeepSeek 的 Claude Code 里粘贴的两张图被捞回并逐张读出](https://raw.githubusercontent.com/liustack/modlens/main/assets/demo-claude-paste-recovery.png)
+
 ## 它是怎么干活的
 
 ![纯文本模型经 modlens skill 把图片交给视觉引擎，回来的是结构化 JSON 证据](https://raw.githubusercontent.com/liustack/modlens/main/assets/flow.zh.png)
 
-粘贴之所以只有它接得住，是因为走了另一条路：粘贴从头到尾是客户端办的事，图一进对话框就被转码发走，MCP server 连插手的机会都没有，所以它们只能教你存文件报路径。而图片字节在发走之前，早被 harness 原样写进了本地会话存储，`recover-paste` 直接去那儿捞。四家 harness 的存储各不相同（Claude Code 和 Pi 是 JSONL，OpenCode 是 SQLite，Codex 本来就有临时文件），细节见[宿主接入](docs/harness-setup.md)。
+没有魔法，四步：
+
+1. 图片出现时 skill 触发：一个路径、一个 URL，或者纯文本模型粘贴后剩下的那个占位符。
+2. skill 跑 `modlens` 命令，把图交给视觉引擎。五个引擎可选，默认是免费的 Antigravity CLI。
+3. 引擎的识读结果被强制装进固定的 JSON 结构：转录、版面、语义、不确定项。不合规的输出直接拒收，绝不凑合。
+4. 模型引用证据，回答问题。
 
-| | 换个多模态模型 | 识图类 MCP server | ModLens |
+粘贴这一手是别家都没有的。粘贴从头到尾在客户端内部完成：图一落进对话框就被编码发走，外部工具根本没机会碰到，所以别的方案只能教你存文件报路径。但字节发走之前，harness 已经把它原样写进了本地会话记录，`recover-paste` 就是去那里捞：Claude Code 和 Pi 存 JSONL，OpenCode 存 SQLite，Codex 的粘贴本来就落成临时文件所以不需要捞。细节见[宿主接入](docs/harness-setup.md)。
+
+| | 换个多模态模型 | 其他识图外挂（MCP server 这类） | ModLens |
 | :-- | :-- | :-- | :-- |
 | 你选的模型 | 得换掉 | 不用换 | 不用换 |
-| 粘贴进对话的图 | 模型支持才看得见 | 接不住 | 直接接住 |
+| 粘贴进对话的图 | 模型支持才看得见 | 接不住 | 捞回来直接读 |
 | 拿到手的是什么 | 模型自己的理解 | 通常一段描述 | 全文转录、版面区块、实体关系 |
 | 读不准的地方 | 可能编 | 可能编 | 进 `uncertainty` |
 | 花费 | 多模态模型的价格 | 多数按 API 计费 | agy 免费额度或免费 Gemini key |
@@ -109,16 +141,41 @@ Codex 桌面 App 里的实拍：丢一张推文截图，纯文本的 DeepSeek
 
 ## CLI 参数
 
+`modlens analyze`（默认命令）：
+
 | 参数 | 含义 | 默认值 |
 | :-- | :-- | :-- |
 | `-i, --input <path\|url>` | 要解析的图片（必填） | |
 | `-p, --provider <name>` | 视觉 provider | `antigravity-cli` |
-| `-m, --model <name>` | provider 模型 | `gemini-3.6-flash-low` |
+| `-m, --model <name>` | provider 模型 | 按 provider（见下） |
 | `-o, --output <path>` | 同时把 JSON 写入文件 | |
 | `--prompt <text>` | 额外关注点 | |
 | `--timeout <ms>` | provider 超时 | `180000` |
+| `--provider-bin <path>` | provider 可执行文件路径 | `agy` / `claude` |
+| `--workdir <path>` | provider 的工作目录 | 图片所在目录 |
+
+`-m` 的默认模型取决于 provider：
 
-五个 provider 可选：`antigravity-cli`（默认，零 key）、`gemini-api`（最快的免费路线）、`openai`（任何 OpenAI 兼容多模态端点）、`anthropic`、`claude-cli`（吃你的 Claude 订阅）。另有 `modlens config <init|set|show>` 管配置，`modlens recover-paste` 抢救粘贴的图。
+| Provider | 默认模型 |
+| :-- | :-- |
+| `antigravity-cli`（默认） | `gemini-3.6-flash-low` |
+| `gemini-api` | `gemini-3.6-flash` |
+| `anthropic` | `claude-haiku-4-5-20251001` |
+| `claude-cli` | `haiku` |
+| `openai` | 无默认，必须指定 `-m` |
+
+`modlens recover-paste`：
+
+| 参数 | 含义 | 默认值 |
+| :-- | :-- | :-- |
+| `--count <n>` | 恢复最近几张粘贴的图 | `1` |
+| `--out-dir <path>` | 恢复的图写到哪个目录 | 每次运行新建的私有目录 `<tmpdir>/modlens-paste-*` |
+| `--session <id>` | 精确锁定的 session id | 自动检测 |
+| `--transcript <path>` | 显式指定 `.jsonl` 或 `.db`（优先于 `--session`） | |
+| `--harness <name>` | 强制存储范围：`claude-code`、`pi`、`opencode`、`none` | 自动检测 |
+| `--cwd <path>` | 图片是在哪个项目目录粘贴的 | 当前目录 |
+
+五个 provider 可选：`antigravity-cli`（默认，零 key）、`gemini-api`（最快的免费路线）、`openai`（任何 OpenAI 兼容多模态端点）、`anthropic`、`claude-cli`（吃你的 Claude 订阅）。另有两个子命令：`modlens config <init|set|show>` 管配置，`modlens doctor` 体检本机（Node 版本、各 provider 就绪状态、最终会选哪个 provider 及原因、检测到的 harness），不消耗额度、不发网络请求，加 `--json` 输出机器可读报告。
 
 ## 文档
 
@@ -132,19 +189,26 @@ Codex 桌面 App 里的实拍：丢一张推文截图，纯文本的 DeepSeek
 | [更新日志](CHANGELOG.md) | 想知道某个版本改了什么 |
 | [AGENTS.md](AGENTS.md) | 要改这个项目的代码 |
 
-## 插入一条硬广告
+## 参与方式
 
-本项目由 LIUSTACK Skills 驱动：动手前 `shaping` 捋清楚，编码时 `coding` 上纪律，出问题 `dig` 挖根因，交接时 `snapshot` 留快照。比 Superpowers 更轻，也更强。
+本仓不收 PR。工具小，一双手维护，每一行代码都要作者自己背，这个闭环收紧了它才可靠。真正帮得上忙的两条路：
 
-```bash
-npx -y skills add liustack/liustack -g
-```
+- **[提 issue](https://github.com/liustack/modlens/issues)。** bug、想法、看不懂的报错、读着别扭的文档都算。issue 一定会被读，也真的会影响接下来做什么。
+- **Fork。** MIT 协议下你的副本完全归你：改名、魔改、发布都随意。
+
+## 关注公众号
+
+AI 工具、实践与想法，第一时间推送。微信扫码，或搜一搜「liustack」关注：
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/liustack/modlens/main/assets/wechat-qrcode.png" width="420" alt="微信公众号 liustack" />
+</p>
 
-⭐ 好用的话给 [ModLens](https://github.com/liustack/modlens) 和 [liustack](https://github.com/liustack/liustack) 各点一个 star。star 是下一个开发者找到它们的方式。
+⭐ 好用的话给 [ModLens](https://github.com/liustack/modlens) 点个 star，这是下一个开发者找到它的方式。
 
 ## 免责声明
 
-仅供个人学习与实验，不用于商业用途。Antigravity CLI 的使用受你自己的 Google 账号条款和额度约束。
+本项目依下方 MIT 协议按现状提供。作者不对任何特定用途（含商业使用）提供保证或背书。上游引擎（Antigravity CLI，Gemini、OpenAI、Anthropic 的 API，以及任何 OpenAI 兼容端点）的使用受各自条款和额度约束，由使用者自行负责。
 
 ## License
 

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately, not in a public issue.
+
+Use [GitHub Security Advisories](https://github.com/liustack/modlens/security/advisories/new) to open a private report. That keeps the details between you and the maintainers until a fix is out.
+
+Include the exact command, the full output, and the modlens and Node versions, the same detail a bug report needs. We will acknowledge the report, work on a fix, and credit you unless you prefer otherwise.
+
+## Supported versions
+
+This is a fast-moving CLI. Fixes land on the latest published version on npm (`@liustack/modlens`), so upgrade to the newest release before reporting.
+
+## What to keep in mind
+
+modlens runs vision engines over images on your machine and can recover pasted image bytes from local session storage. The security model, what it runs, how recovered images are protected, and why image content is untrusted input, is documented in [docs/security.md](docs/security.md). Read it before reporting behavior that may be working as intended.