@liustack/modlens 3.7.0 → 3.9.0

package/skills/modlens/references/find-image.md

@@ -0,0 +1,33 @@
+# Finding the image path in the chat
+
+Harnesses rarely hand you a clean path. Identify which harness you are in, then follow its branch. Never mix branches across harnesses.
+
+## Codex
+
+You see a text tag like `<image name=[Image #1] path="/tmp/xxxx.png">`:
+
+- Extract the `path` value from the tag and run modlens on it. Pasted images live in a temp file Codex already created; a stripped image keeps its path tag next to the placeholder.
+- Do NOT use `recover-paste` here: it detects Codex and refuses with this same guidance.
+
+## Claude Code with a `[Image: source: <path>]` line
+
+Newer Claude Code builds write every pasted image to `~/.claude/image-cache/<session-id>/` and, in the terminal (`cli`) entrypoint, inject that line as a user message. Undocumented internal behavior (observed on 2.1.201 through 2.1.231; the VSCode and desktop entrypoints do not inject it), so treat it as a shortcut, not a guarantee.
+
+- If the file at that path exists, run modlens on it directly and skip `recover-paste`. The file is Claude Code's own cache: read it, never delete or move it.
+- If the path is gone (the cache is cleaned after a while) or there is no such line, fall through to the next branch.
+
+## Claude Code, Pi, or OpenCode (no usable path anywhere)
+
+The image reads as `[Unsupported Image]`, a bare `[Image #1]`, or an attachment you simply cannot see. Whatever a gateway strips from the request, these harnesses persist user messages, image bytes included, in local session storage first: Claude Code and Pi in session JSONL files (`~/.claude/projects/`, `~/.pi/agent/sessions/`), OpenCode in a SQLite database (`~/.local/share/opencode/opencode.db`, read via node:sqlite, needs Node 22.5+; Bun cannot load node:sqlite, so a bunx-resolved launcher needs a real Node install for OpenCode recovery).
+
+- Run `modlens recover-paste` from the project directory the conversation is happening in (`--count <n>` for several images). It detects which harness it is running inside and reads ONLY that harness's storage. In Claude Code it targets your exact session automatically via the injected `CLAUDE_CODE_SESSION_ID`; `--session <id>` is only needed to override.
+- The output is JSON with real file paths, oldest to newest, so the LAST path is the most recent paste: analyze that one first. Entries carry `filename` when the harness stored one; match on it when the user's message mentions a name.
+- Run every command yourself, never ask the user to run modlens or relay paths.
+- When the analysis is done, delete the recovery output directory (each entry's `path` sits inside it): the files are private copies of the user's pastes, and nothing else cleans them up. Keep them only if the user asked.
+- If the output's `detected` field is absent, detection failed and every store was scanned: check `harness` and `filename` match what you expect, force `--harness <claude-code|pi|opencode>` if not, and when in doubt ask the user for the file instead of describing the wrong image.
+- Recovery is scoped to this project (the harness's own record of its working directory is checked), and recovered files are private to the user (0600).
+- If recovery fails, ask the user to drag the image file into the terminal or type its path.
+
+## Any other harness, or nothing matches
+
+No path tag and `recover-paste` reports no transcripts: do not guess. Ask the user for the image file path, or suggest dragging the file into the terminal.

package/skills/modlens/references/onboard.md

@@ -0,0 +1,51 @@
+# First run on this machine: inventory, ask, then configure
+
+Run this flow when `~/.modlens/config.json` does not exist, or `modlens config show` prints an empty config (`{"providers":{}}` with no `reuse` decisions). That check makes the flow idempotent: a machine that has been through it is never re-onboarded, and an existing config is never overwritten without the user asking for a change. The user can also request it by name ("set up modlens").
+
+## 1. Inventory, spending nothing
+
+```bash
+modlens doctor --json
+```
+
+Read three things from the report: which providers are `ready`, the Reuse section (per-harness decisions plus discovered logins and vision models; the harness this conversation runs inside is itself the first reusable engine), and the guard state. Doctor spends no quota and makes no network calls.
+
+## 2. Tell the user what their machine already has
+
+One line per finding, plain words, in the user's language. Name concrete things, not concepts:
+
+- An engine is ready: "modlens is ready to go: <provider> is configured (via <env var / config file / existing login>)."
+- Reusable vision found: "Your <harness> CLI is signed in and its model can read images. modlens can reuse it when needed, about <n> seconds per read, and it spends that account's quota."
+- Nothing at all: "No vision engine is set up yet. The fastest free option is a Gemini API key (three minutes, no card); Antigravity CLI works with no sign-up at all."
+
+Do not dump the raw doctor output on the user; summarize it. Do not describe options the machine does not have.
+
+## 3. Ask before touching anything
+
+Consent rules:
+
+- One question per decision, never a bundled yes. Reusing Codex and reusing pi credentials are two questions (or one question with independent options), not one.
+- Each question names the harness, whose quota it spends, and the accounting promise. Example wording: "Allow modlens to reuse your signed-in Codex CLI for image reads? Every reused read is labeled in the result so you always see whose quota was spent."
+- The do-nothing outcome must be safe and stated: "If you skip this, modlens just uses the engines you configure yourself."
+- If the user offers an API key, take exactly that key; never go looking for keys they did not hand over.
+
+## 4. Apply only what was consented to
+
+| The user agreed to | Run |
+| :-- | :-- |
+| Reusing a harness CLI | `modlens config set reuse.<claude\|codex\|opencode\|pi\|grok> true` (one per consent) |
+| A Gemini key they handed over | `modlens config set gemini-api.apiKey <key>` |
+| An OpenAI-compatible endpoint | `config set openai.baseUrl / openai.apiKey / openai.model` |
+| Guard rules for their text-only model | `modlens config set guards.allowModels '["<pattern>"]'` (patterns: `references/configure.md`) |
+
+A refusal is also an answer: record it with `modlens config set reuse.<harness> false` so the user is never asked again. Nothing decided at all: write nothing and stop.
+
+## 5. Close the loop
+
+Run `modlens doctor` once more and report in one or two sentences: what was written (always and only `~/.modlens/config.json`), what the chain now looks like, and the undo (`modlens config set reuse.<harness> false`, or editing that file). If an engine is ready, offer to prove it on a real image.
+
+## Never
+
+- Never set any `reuse.<harness>` to true without an explicit yes for that harness in this conversation.
+- Never write, move, or read files outside `~/.modlens/` during onboarding (doctor's read-only probing is the one exception).
+- Never present reusing another login as free: it spends the named account's quota, and the wording must say so.

package/skills/modlens/references/runtime.md

@@ -8,7 +8,7 @@ shell syntax.
 
 ## Pinned version
 
-- Pinned CLI version: 3.7.0
+- Pinned CLI version: 3.9.0
 - npm package: `@liustack/modlens`
 - CLI binary name: `modlens`
 

package/skills/modlens/scripts/run.ps1

@@ -24,7 +24,7 @@ $ErrorActionPreference = 'Stop'
 # package.json version, and the release script rewrites it on every bump.
 $Package = '@liustack/modlens'
 $Bin = 'modlens'
-$Pinned = '3.7.0'
+$Pinned = '3.9.0'
 # -------------------------------------------------------------------------------
 
 $NativeNote = 'no native artifact is published for this tool yet; phase A ships npm launch paths only'

package/skills/modlens/scripts/run.sh

@@ -22,7 +22,7 @@ set -eu
 # package.json version, and the release script rewrites it on every bump.
 PKG="@liustack/modlens"
 BIN="modlens"
-PINNED="3.7.0"
+PINNED="3.9.0"
 # -------------------------------------------------------------------------------
 
 NATIVE_NOTE="no native artifact is published for this tool yet; phase A ships npm launch paths only"