@sylphx/iris 0.2.0 → 0.3.0

package/README.md

@@ -1,261 +1,90 @@
-<div align="center">
-
 # Iris
 
-### Image evidence for agents
-
-Canonical package: **`@sylphx/iris`** · bin **`iris`** 
-
-**Iris** — **Rust-first** local image facts (`@sylphx/iris`) local image facts, not default VLM guesses. `sharp`/`exifr` are optional, not required for MCP.
-
-<p align="center">
-  <img src="https://mark.sylphx.com/api/v1/banner?type=holo&theme=tokyonight&text=image+reader+mcp&desc=Evidence-first+image+reading+for+AI+agents+%E2%80%94+metadata%2C+OCR+text%2C+regions%2C+and+ci&height=200&animation=rise&credit=0" alt="image-reader-mcp — Sylphx Mark banner" width="100%" />
-</p>
-
-### Your agent looked at the image. **Did it see the truth?**
-
-Evidence-first image reading for AI agents. One call turns any local image into an
-**Agent Media Twin** — dimensions, metadata, optional OCR with bounding boxes, and
-trust warnings you can cite without asking a vision LLM to guess.
-
-[![npm version](https://img.shields.io/npm/v/@sylphx/iris?style=flat-square)](https://www.npmjs.com/package/@sylphx/iris)
-[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](https://opensource.org/licenses/MIT)
-[![CI/CD](https://img.shields.io/github/actions/workflow/status/SylphxAI/image-reader-mcp/ci.yml?style=flat-square&label=CI/CD)](https://github.com/SylphxAI/image-reader-mcp/actions/workflows/ci.yml)
-[![TypeScript](https://img.shields.io/badge/TypeScript-7.0-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
-
-**Local-first** · **One smart `read_image` call** · **Evidence with bbox + provenance** · **23 tests**
-
-SOTA family roadmap: [docs/roadmap/sota-family-roadmap.md](docs/roadmap/sota-family-roadmap.md).
-
-[⭐ Star this repo](https://github.com/SylphxAI/image-reader-mcp) if agents should read images with facts, not vision-model guesses.
-· [Quick start](#quick-start) · [See it work](#see-it-work) · [Why not vision LLM guess?](#why-not-vision-llm-guess)
-
-This repository is product SSOT. Sibling agent tools live in separate repos.
-Each instrument is an independent repository (marketplace + stars).
-
-</div>
-
----
-
-
-
-## See objects (L2, optional)
-
-With a local Florence-class sidecar or Ollama, the same `read_image` can return **open-vocab objects** with pixel bboxes and scores:
-
-```json
-{ "path": "/abs/photo.jpg", "include_semantics": true, "semantics_prompt": "people and animals" }
-```
+### Image facts with pixel-level proof
 
-Objects are `scored_non_locator` evidence — deterministic L0/L1 facts (geometry/OCR/layout) stay authoritative and always on.
-
-## Read images (not vague vision)
-
-Iris is **local-first**: geometry + OCR + **layout blocks** + **agent_map** so a text-only agent can understand picture architecture without a vision model.
-
-Spec: [docs/specs/agent-image-read-contract.md](docs/specs/agent-image-read-contract.md)
-
-**Local-first frontier:** Rust decode, Tesseract native layout (no npm ML), optional Ollama VLM; cloud URL optional. Zero API key. Optional **L2 local semantics** (include_semantics) detects open-vocab objects (people/animals/things) with pixel bboxes via an official Florence-class sidecar (examples/florence-sidecar/) or Ollama -- never authority over OCR/layout locators.
-
-## Product docs
-
-| Doc | Purpose |
-| --- | --- |
-| [docs/POSITIONING.md](docs/POSITIONING.md) | Strategic positioning |
-| [docs/COMPETITIVE.md](docs/COMPETITIVE.md) | Peer anchors and wedge |
-| [docs/EVIDENCE_CONTRACT.md](docs/EVIDENCE_CONTRACT.md) | Evidence = result contract |
-| [docs/TOOL_SURFACE.md](docs/TOOL_SURFACE.md) | Few clear tools policy |
-| [docs/PRODUCT_INDEPENDENCE.md](docs/PRODUCT_INDEPENDENCE.md) | This repo is SSOT |
-| [docs/IPPB.md](docs/IPPB.md) | Independent public product bar |
-| [docs/PUBLISH.md](docs/PUBLISH.md) | npm/git publish status |
-
-## The problem
-
-Images are not filenames. They are pixels, EXIF, orientation, embedded GPS,
-hidden metadata, and text that only exists if you OCR it with geometry.
-
-Most agent stacks route images through a **vision LLM** and get a plausible
-description. Dimensions get rounded. OCR text gets paraphrased. Metadata
-disappears. Citations become "the model said so." Then the agent hallucinates —
-confidently.
-
-**Image Reader MCP is built for the moment your agent needs measurable facts about
-an image, not a creative caption.**
-
-## Why not vision LLM guess?
-
-| Typical vision path | Image Reader MCP |
-| --- | --- |
-| "Describe this image" | Return filename, mime, dimensions, and structured metadata |
-| Paraphrased OCR | Optional Tesseract lines with bounding boxes and confidence |
-| GPS and EXIF leak into context | GPS redacted; trust warnings for suspicious metadata |
-| No provenance | Agent Media Twin JSON with measurable, citeable fields |
-| Cloud API by default | **Local-first** — Rust decode + optional Tesseract OCR; sharp/exifr only optional fallbacks |
-| Ship and pray | **23** unit tests on schema, metadata, OCR hooks, safety limits, doctor, and release gate |
-
-## See it work
-
-### Install (30 seconds)
+Iris gives agents deterministic facts from screenshots, UI captures, forms,
+diagrams, charts, and other images. It returns dimensions, metadata, OCR
+regions, layout blocks, crops, and trust warnings without requiring a
+generative vision model.
 
 ```bash
-npm install -g @sylphx/iris
-iris doctor
-claude mcp add iris -- npx @sylphx/iris
+npx -y @sylphx/iris
 ```
 
-**Install once. Call once.**
+For Claude Code:
 
 ```bash
-claude mcp add image-reader -- npx @sylphx/iris
-```
-
-```json
-{
-  "path": "/absolute/path/to/photo.jpg",
-  "include_metadata": true,
-  "include_ocr": true
-}
+claude mcp add iris -- npx -y @sylphx/iris
 ```
 
-`read_image` inspects the file locally and returns an Agent Media Twin — no
-generative LLM required:
+## The fastest useful workflow
 
 ```json
 {
-  "filename": "photo.jpg",
-  "mime": "image/jpeg",
-  "dimensions": { "width": 4032, "height": 3024 },
-  "orientation": 1,
-  "metadata": {
-    "Make": "ExampleCamera",
-    "Model": "Pro X",
-    "DateTimeOriginal": "2026-03-15T14:22:10"
-  },
-  "ocr": {
-    "available": true,
-    "lines": [
-      {
-        "text": "INVOICE #1042",
-        "bbox": { "x": 120, "y": 48, "width": 310, "height": 36 },
-        "confidence": 92
-      }
-    ]
-  },
-  "trust_warnings": []
+  "path": "/absolute/path/to/screenshot.png",
+  "include_ocr": true
 }
 ```
 
-Abbreviated shape — optional OCR skips gracefully when Tesseract is not installed.
+The result includes image dimensions, hash, OCR lines with bounding boxes,
+layout blocks, a text map for agents, and explicit warnings or gaps.
 
-## MCP Tool Surface
+## Jobs Iris is built for
 
-| Tool | Use it when the agent needs to... |
+| Ask your agent | Iris returns |
 | --- | --- |
-| `read_image` | Read a local image and return dimensions, mime, metadata, optional OCR, and trust warnings. |
-
-Supported formats: PNG, JPEG, GIF, WebP, TIFF, and other formats the **Rust decode engine** supports (optional sharp covers additional formats when installed).
-
-## Quick Start
-
-### Claude Code
-
-```bash
-claude mcp add image-reader -- npx @sylphx/iris
-```
+| “Read this screenshot.” | text regions and layout facts |
+| “What changed between these UI captures?” | image diff evidence |
+| “Extract this form.” | OCR lines and boxes |
+| “Crop the important region.” | citeable pixel evidence |
+| “Check the image metadata.” | format, dimensions, EXIF trust warnings |
 
-### Claude Desktop
+## Tool surface
 
-Add this to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "image-reader": {
-      "command": "npx",
-      "args": ["@sylphx/iris"]
-    }
-  }
-}
-```
-
-### Any MCP Client
-
-```bash
-npx @sylphx/iris
-```
+| Tool | Purpose |
+| --- | --- |
+| `read_image` | Primary image facts and optional OCR |
+| `image_probe` | Cheap metadata and geometry probe |
+| `crop_region` | Extract a citeable pixel region |
+| `compare_images` | Report pixel and layout differences between two images |
 
-Node.js `>=22.13` is required. Optional OCR uses a local Tesseract adapter when
-installed — no cloud credentials required by default.
+## Predictable defaults
 
-## Security model
+- `fast` returns deterministic metadata, geometry, and layout.
+- `quality` explicitly enables OCR and local semantic helpers.
+- Generative captions and object detection are opt-in and never authoritative.
+- GPS metadata is redacted unless explicitly requested.
+- Oversized or unsupported files fail with a structured error.
 
-- **Local-first** — `read_image` resolves paths on the local machine; no cloud vision API by default.
-- **GPS redaction** — location metadata is stripped from agent-facing output unless explicitly opted in.
-- **Size and format limits** — oversized or unsupported inputs return structured errors, not partial guesses.
-- **Optional OCR** — Tesseract runs locally when installed; missing OCR is reported as `available: false`, not silent failure.
-- **Trust warnings** — suspicious EXIF, orientation, or metadata anomalies surface in `trust_warnings` for agent verification.
+## Why agents trust it
 
-## Release proof
+Every result keeps source path and hash, pixel locators, extraction route,
+confidence or warnings, and known gaps. OCR and optional model output never
+replace deterministic geometry.
 
-Claims are backed by CI `benchmark:release-gate` and the shipped-path matrix (Rust-default route, no legacy Node engine on primary tools).
+## Companion MCP tools
 
-```bash
-bun run benchmark:release-gate
-```
+| Product | Job |
+| --- | --- |
+| [Citra](https://github.com/SylphxAI/citra) | PDF answers with page-level proof |
+| [Cue](https://github.com/SylphxAI/cue) | Video timelines and timestamp evidence |
+| [Spine](https://github.com/SylphxAI/spine) | Repository architecture and impact |
+| [Locus](https://github.com/SylphxAI/locus) | Exact code-chunk retrieval |
+| [Lookout](https://github.com/SylphxAI/lookout) | Web research with source excerpts |
 
-Artifact: `benchmark-artifacts/image_reader_release_gate.json` — must report `status: passed` before release.
+Each product is independent. Install only the tools your agent needs.
 
 ## Development
 
 ```bash
-git clone https://github.com/SylphxAI/image-reader-mcp.git
-cd image-reader-mcp
 bun install
 bun run build
 bun test
-bun run doctor
-bun run benchmark:release-gate
-```
-
-Useful checks:
-
-```bash
-bun run check
-bun run typecheck
-bun run validate
+cargo test
+bun run benchmark:public-proof
 bun run benchmark:release-gate
 ```
 
-Example `read_image` requests live in [`examples/`](examples/).
-
-## Support
-
-- [Issues](https://github.com/SylphxAI/image-reader-mcp/issues)
-- [npm package](https://www.npmjs.com/package/@sylphx/iris)
-- Portfolio orchestration: [smart-reader-mcp](https://github.com/SylphxAI/smart-reader-mcp)
-
-## Help this reach more builders
-
-If vision-model guesses have wasted your context, your citations, or your trust
-in agent output, you are exactly who this project is for.
-
-**[⭐ Star the repo](https://github.com/SylphxAI/image-reader-mcp)** — it is the
-fastest way to help more agent builders find evidence-first image reading. Share
-it in your MCP client setup, team wiki, or agent stack README.
-
-### Discovery (in progress)
-
-| Channel | Status |
-| --- | --- |
-| [Glama MCP directory](https://glama.ai/mcp/servers/SylphxAI/image-reader-mcp) | Listed — [claim server](https://glama.ai/mcp/servers/SylphxAI/image-reader-mcp/admin) for full discoverability |
-| [Official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.SylphxAI/image-reader-mcp) | Listed — `io.github.SylphxAI/image-reader-mcp` @ v0.1.0 |
-| [TensorBlock MCP Index PR #1113](https://github.com/TensorBlock/awesome-mcp-servers/pull/1113) | Open — multimedia/document processing listing |
-| [MCP servers community issue #4500](https://github.com/modelcontextprotocol/servers/issues/4500) | Open — community server highlight |
-| [mcp.so listing issue #3068](https://github.com/chatmcp/mcpso/issues/3068) | Open — directory submission request |
-| [mcpservers.org submit](https://mcpservers.org/submit) | Not listed yet — free web-form submission |
-
-Know another MCP directory? [Open an issue](https://github.com/SylphxAI/image-reader-mcp/issues/new) with the link.
-
 ## License
 
-MIT © [SylphxAI](https://github.com/SylphxAI)
+MIT

package/dist/doctor-cli.js

@@ -20,12 +20,14 @@ var __toESM = (mod, isNodeMode, target) => {
   }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: __accessProp.bind(mod, key),
-        enumerable: true
-      });
+  if (mod && typeof mod === "object" || typeof mod === "function") {
+    for (let key of __getOwnPropNames(mod))
+      if (!__hasOwnProp.call(to, key))
+        __defProp(to, key, {
+          get: __accessProp.bind(mod, key),
+          enumerable: true
+        });
+  }
   if (canCache)
     cache.set(mod, to);
   return to;
@@ -93,7 +95,7 @@ var init_is = __esm(() => {
 });
 
 // node_modules/detect-libc/lib/process.js
-var require_process = __commonJS((exports, module) => {
+var require_process = __commonJS(function(exports, module) {
   var isLinux = () => process.platform === "linux";
   var report = null;
   var getReport = () => {
@@ -113,7 +115,7 @@ var require_process = __commonJS((exports, module) => {
 });
 
 // node_modules/detect-libc/lib/filesystem.js
-var require_filesystem = __commonJS((exports, module) => {
+var require_filesystem = __commonJS(function(exports, module) {
   var fs = __require("fs");
   var LDD_PATH = "/usr/bin/ldd";
   var SELF_PATH = "/proc/self/exe";
@@ -147,7 +149,7 @@ var require_filesystem = __commonJS((exports, module) => {
 });
 
 // node_modules/detect-libc/lib/elf.js
-var require_elf = __commonJS((exports, module) => {
+var require_elf = __commonJS(function(exports, module) {
   var interpreterPath = (elf) => {
     if (elf.length < 64) {
       return null;
@@ -181,7 +183,7 @@ var require_elf = __commonJS((exports, module) => {
 });
 
 // node_modules/detect-libc/lib/detect-libc.js
-var require_detect_libc = __commonJS((exports, module) => {
+var require_detect_libc = __commonJS(function(exports, module) {
   var childProcess = __require("child_process");
   var { isLinux, getReport } = require_process();
   var { LDD_PATH, SELF_PATH, readFile, readFileSync } = require_filesystem();
@@ -427,7 +429,7 @@ var require_detect_libc = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/internal/constants.js
-var require_constants = __commonJS((exports, module) => {
+var require_constants = __commonJS(function(exports, module) {
   var SEMVER_SPEC_VERSION = "2.0.0";
   var MAX_LENGTH = 256;
   var MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER || 9007199254740991;
@@ -455,13 +457,13 @@ var require_constants = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/internal/debug.js
-var require_debug = __commonJS((exports, module) => {
+var require_debug = __commonJS(function(exports, module) {
   var debug = typeof process === "object" && process.env && process.env.NODE_DEBUG && /\bsemver\b/i.test(process.env.NODE_DEBUG) ? (...args) => console.error("SEMVER", ...args) : () => {};
   module.exports = debug;
 });
 
 // node_modules/semver/internal/re.js
-var require_re = __commonJS((exports, module) => {
+var require_re = __commonJS(function(exports, module) {
   var {
     MAX_SAFE_COMPONENT_LENGTH,
     MAX_SAFE_BUILD_LENGTH,
@@ -546,7 +548,7 @@ var require_re = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/internal/parse-options.js
-var require_parse_options = __commonJS((exports, module) => {
+var require_parse_options = __commonJS(function(exports, module) {
   var looseOption = Object.freeze({ loose: true });
   var emptyOpts = Object.freeze({});
   var parseOptions = (options) => {
@@ -562,7 +564,7 @@ var require_parse_options = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/internal/identifiers.js
-var require_identifiers = __commonJS((exports, module) => {
+var require_identifiers = __commonJS(function(exports, module) {
   var numeric = /^[0-9]+$/;
   var compareIdentifiers = (a, b) => {
     if (typeof a === "number" && typeof b === "number") {
@@ -584,7 +586,7 @@ var require_identifiers = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/classes/semver.js
-var require_semver = __commonJS((exports, module) => {
+var require_semver = __commonJS(function(exports, module) {
   var debug = require_debug();
   var { MAX_LENGTH, MAX_SAFE_INTEGER } = require_constants();
   var { safeRe: re, t } = require_re();
@@ -866,7 +868,7 @@ var require_semver = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/parse.js
-var require_parse = __commonJS((exports, module) => {
+var require_parse = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var parse = (version, options, throwErrors = false) => {
     if (version instanceof SemVer) {
@@ -885,7 +887,7 @@ var require_parse = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/valid.js
-var require_valid = __commonJS((exports, module) => {
+var require_valid = __commonJS(function(exports, module) {
   var parse = require_parse();
   var valid = (version, options) => {
     const v = parse(version, options);
@@ -895,7 +897,7 @@ var require_valid = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/clean.js
-var require_clean = __commonJS((exports, module) => {
+var require_clean = __commonJS(function(exports, module) {
   var parse = require_parse();
   var clean = (version, options) => {
     const s = parse(version.trim().replace(/^[=v]+/, ""), options);
@@ -905,7 +907,7 @@ var require_clean = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/inc.js
-var require_inc = __commonJS((exports, module) => {
+var require_inc = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var inc = (version, release, options, identifier, identifierBase) => {
     if (typeof options === "string") {
@@ -923,7 +925,7 @@ var require_inc = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/diff.js
-var require_diff = __commonJS((exports, module) => {
+var require_diff = __commonJS(function(exports, module) {
   var parse = require_parse();
   var diff = (version1, version2) => {
     const v1 = parse(version1, null, true);
@@ -964,28 +966,28 @@ var require_diff = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/major.js
-var require_major = __commonJS((exports, module) => {
+var require_major = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var major = (a, loose) => new SemVer(a, loose).major;
   module.exports = major;
 });
 
 // node_modules/semver/functions/minor.js
-var require_minor = __commonJS((exports, module) => {
+var require_minor = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var minor = (a, loose) => new SemVer(a, loose).minor;
   module.exports = minor;
 });
 
 // node_modules/semver/functions/patch.js
-var require_patch = __commonJS((exports, module) => {
+var require_patch = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var patch = (a, loose) => new SemVer(a, loose).patch;
   module.exports = patch;
 });
 
 // node_modules/semver/functions/prerelease.js
-var require_prerelease = __commonJS((exports, module) => {
+var require_prerelease = __commonJS(function(exports, module) {
   var parse = require_parse();
   var prerelease = (version, options) => {
     const parsed = parse(version, options);
@@ -995,28 +997,28 @@ var require_prerelease = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/compare.js
-var require_compare = __commonJS((exports, module) => {
+var require_compare = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var compare = (a, b, loose) => new SemVer(a, loose).compare(new SemVer(b, loose));
   module.exports = compare;
 });
 
 // node_modules/semver/functions/rcompare.js
-var require_rcompare = __commonJS((exports, module) => {
+var require_rcompare = __commonJS(function(exports, module) {
   var compare = require_compare();
   var rcompare = (a, b, loose) => compare(b, a, loose);
   module.exports = rcompare;
 });
 
 // node_modules/semver/functions/compare-loose.js
-var require_compare_loose = __commonJS((exports, module) => {
+var require_compare_loose = __commonJS(function(exports, module) {
   var compare = require_compare();
   var compareLoose = (a, b) => compare(a, b, true);
   module.exports = compareLoose;
 });
 
 // node_modules/semver/functions/compare-build.js
-var require_compare_build = __commonJS((exports, module) => {
+var require_compare_build = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var compareBuild = (a, b, loose) => {
     const versionA = new SemVer(a, loose);
@@ -1027,63 +1029,63 @@ var require_compare_build = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/sort.js
-var require_sort = __commonJS((exports, module) => {
+var require_sort = __commonJS(function(exports, module) {
   var compareBuild = require_compare_build();
   var sort = (list, loose) => list.sort((a, b) => compareBuild(a, b, loose));
   module.exports = sort;
 });
 
 // node_modules/semver/functions/rsort.js
-var require_rsort = __commonJS((exports, module) => {
+var require_rsort = __commonJS(function(exports, module) {
   var compareBuild = require_compare_build();
   var rsort = (list, loose) => list.sort((a, b) => compareBuild(b, a, loose));
   module.exports = rsort;
 });
 
 // node_modules/semver/functions/gt.js
-var require_gt = __commonJS((exports, module) => {
+var require_gt = __commonJS(function(exports, module) {
   var compare = require_compare();
   var gt = (a, b, loose) => compare(a, b, loose) > 0;
   module.exports = gt;
 });
 
 // node_modules/semver/functions/lt.js
-var require_lt = __commonJS((exports, module) => {
+var require_lt = __commonJS(function(exports, module) {
   var compare = require_compare();
   var lt = (a, b, loose) => compare(a, b, loose) < 0;
   module.exports = lt;
 });
 
 // node_modules/semver/functions/eq.js
-var require_eq = __commonJS((exports, module) => {
+var require_eq = __commonJS(function(exports, module) {
   var compare = require_compare();
   var eq = (a, b, loose) => compare(a, b, loose) === 0;
   module.exports = eq;
 });
 
 // node_modules/semver/functions/neq.js
-var require_neq = __commonJS((exports, module) => {
+var require_neq = __commonJS(function(exports, module) {
   var compare = require_compare();
   var neq = (a, b, loose) => compare(a, b, loose) !== 0;
   module.exports = neq;
 });
 
 // node_modules/semver/functions/gte.js
-var require_gte = __commonJS((exports, module) => {
+var require_gte = __commonJS(function(exports, module) {
   var compare = require_compare();
   var gte = (a, b, loose) => compare(a, b, loose) >= 0;
   module.exports = gte;
 });
 
 // node_modules/semver/functions/lte.js
-var require_lte = __commonJS((exports, module) => {
+var require_lte = __commonJS(function(exports, module) {
   var compare = require_compare();
   var lte = (a, b, loose) => compare(a, b, loose) <= 0;
   module.exports = lte;
 });
 
 // node_modules/semver/functions/cmp.js
-var require_cmp = __commonJS((exports, module) => {
+var require_cmp = __commonJS(function(exports, module) {
   var eq = require_eq();
   var neq = require_neq();
   var gt = require_gt();
@@ -1130,7 +1132,7 @@ var require_cmp = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/coerce.js
-var require_coerce = __commonJS((exports, module) => {
+var require_coerce = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var parse = require_parse();
   var { safeRe: re, t } = require_re();
@@ -1173,7 +1175,7 @@ var require_coerce = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/truncate.js
-var require_truncate = __commonJS((exports, module) => {
+var require_truncate = __commonJS(function(exports, module) {
   var parse = require_parse();
   var constants = require_constants();
   var SemVer = require_semver();
@@ -1211,7 +1213,7 @@ var require_truncate = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/internal/lrucache.js
-var require_lrucache = __commonJS((exports, module) => {
+var require_lrucache = __commonJS(function(exports, module) {
   class LRUCache {
     constructor() {
       this.max = 1000;
@@ -1246,7 +1248,7 @@ var require_lrucache = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/classes/range.js
-var require_range = __commonJS((exports, module) => {
+var require_range = __commonJS(function(exports, module) {
   var SPACE_CHARACTERS = /\s+/g;
 
   class Range {
@@ -1628,7 +1630,7 @@ var require_range = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/classes/comparator.js
-var require_comparator = __commonJS((exports, module) => {
+var require_comparator = __commonJS(function(exports, module) {
   var ANY = Symbol("SemVer ANY");
 
   class Comparator {
@@ -1739,7 +1741,7 @@ var require_comparator = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/functions/satisfies.js
-var require_satisfies = __commonJS((exports, module) => {
+var require_satisfies = __commonJS(function(exports, module) {
   var Range = require_range();
   var satisfies = (version, range, options) => {
     try {
@@ -1753,14 +1755,14 @@ var require_satisfies = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/ranges/to-comparators.js
-var require_to_comparators = __commonJS((exports, module) => {
+var require_to_comparators = __commonJS(function(exports, module) {
   var Range = require_range();
   var toComparators = (range, options) => new Range(range, options).set.map((comp) => comp.map((c) => c.value).join(" ").trim().split(" "));
   module.exports = toComparators;
 });
 
 // node_modules/semver/ranges/max-satisfying.js
-var require_max_satisfying = __commonJS((exports, module) => {
+var require_max_satisfying = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var Range = require_range();
   var maxSatisfying = (versions, range, options) => {
@@ -1786,7 +1788,7 @@ var require_max_satisfying = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/ranges/min-satisfying.js
-var require_min_satisfying = __commonJS((exports, module) => {
+var require_min_satisfying = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var Range = require_range();
   var minSatisfying = (versions, range, options) => {
@@ -1812,7 +1814,7 @@ var require_min_satisfying = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/ranges/min-version.js
-var require_min_version = __commonJS((exports, module) => {
+var require_min_version = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var Range = require_range();
   var gt = require_gt();
@@ -1866,7 +1868,7 @@ var require_min_version = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/ranges/valid.js
-var require_valid2 = __commonJS((exports, module) => {
+var require_valid2 = __commonJS(function(exports, module) {
   var Range = require_range();
   var validRange = (range, options) => {
     try {
@@ -1879,7 +1881,7 @@ var require_valid2 = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/ranges/outside.js
-var require_outside = __commonJS((exports, module) => {
+var require_outside = __commonJS(function(exports, module) {
   var SemVer = require_semver();
   var Comparator = require_comparator();
   var { ANY } = Comparator;
@@ -1945,21 +1947,21 @@ var require_outside = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/ranges/gtr.js
-var require_gtr = __commonJS((exports, module) => {
+var require_gtr = __commonJS(function(exports, module) {
   var outside = require_outside();
   var gtr = (version, range, options) => outside(version, range, ">", options);
   module.exports = gtr;
 });
 
 // node_modules/semver/ranges/ltr.js
-var require_ltr = __commonJS((exports, module) => {
+var require_ltr = __commonJS(function(exports, module) {
   var outside = require_outside();
   var ltr = (version, range, options) => outside(version, range, "<", options);
   module.exports = ltr;
 });
 
 // node_modules/semver/ranges/intersects.js
-var require_intersects = __commonJS((exports, module) => {
+var require_intersects = __commonJS(function(exports, module) {
   var Range = require_range();
   var intersects = (r1, r2, options) => {
     r1 = new Range(r1, options);
@@ -1970,7 +1972,7 @@ var require_intersects = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/ranges/simplify.js
-var require_simplify = __commonJS((exports, module) => {
+var require_simplify = __commonJS(function(exports, module) {
   var satisfies = require_satisfies();
   var compare = require_compare();
   module.exports = (versions, range, options) => {
@@ -2017,7 +2019,7 @@ var require_simplify = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/ranges/subset.js
-var require_subset = __commonJS((exports, module) => {
+var require_subset = __commonJS(function(exports, module) {
   var Range = require_range();
   var Comparator = require_comparator();
   var { ANY } = Comparator;
@@ -2177,7 +2179,7 @@ var require_subset = __commonJS((exports, module) => {
 });
 
 // node_modules/semver/index.js
-var require_semver2 = __commonJS((exports, module) => {
+var require_semver2 = __commonJS(function(exports, module) {
   var internalRe = require_re();
   var constants = require_constants();
   var SemVer = require_semver();
@@ -4508,7 +4510,7 @@ var init_operation = __esm(() => {
 });
 
 // node_modules/@img/colour/color.cjs
-var require_color = __commonJS((exports, module) => {
+var require_color = __commonJS(function(exports, module) {
   var __defProp2 = Object.defineProperty;
   var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
   var __getOwnPropNames2 = Object.getOwnPropertyNames;
@@ -6084,7 +6086,7 @@ var require_color = __commonJS((exports, module) => {
 });
 
 // node_modules/@img/colour/index.cjs
-var require_colour = __commonJS((exports, module) => {
+var require_colour = __commonJS(function(exports, module) {
   module.exports = require_color().default;
 });
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sylphx/iris",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "mcpName": "io.github.SylphxAI/iris",
-  "description": "Iris \u2014 evidence-first image reading for AI agents. Metadata, OCR text, regions, citeable evidence. Local-first. No generative LLM authority.",
+  "description": "Iris — image facts with pixel-level proof. Local-first metadata, OCR boxes, layout, crops, and image diff evidence.",
   "type": "module",
   "bin": {
     "iris": "./bin/iris"
@@ -24,9 +24,9 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/SylphxAI/image-reader-mcp.git"
+    "url": "git+https://github.com/SylphxAI/iris.git"
   },
-  "homepage": "https://github.com/SylphxAI/image-reader-mcp#readme",
+  "homepage": "https://sylphxai.github.io/iris/",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -39,7 +39,7 @@
     "agent-media-twin"
   ],
   "engines": {
-    "node": ">=22.13.0"
+    "bun": ">=1.4.0"
   },
   "scripts": {
     "build:rust": "cargo build --release -p image-reader-core -p image-reader-cli -p image-reader-mcp-server && bun scripts/stage-rust-mcp.ts",
@@ -63,7 +63,10 @@
     "prepublishOnly": "bun run clean && bun run build && bun run build:rust",
     "release": "bun run typecheck && bun run check && bun run build && bun test && changeset publish",
     "benchmark:public-proof": "bun scripts/public-proof.ts",
-    "brand:pack-plan": "bun scripts/brand-pack-plan.ts"
+    "brand:pack-plan": "bun scripts/brand-pack-plan.ts",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -75,16 +78,17 @@
     "@changesets/cli": "^2.31.0",
     "@types/node": "^25.9.1",
     "bunup": "0.16.31",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitepress": "1.6.4"
   },
-  "packageManager": "bun@1.3.12",
+  "packageManager": "bun@1.4.0",
   "private": false,
   "optionalDependencies": {
     "sharp": "^0.35.0",
     "exifr": "^7.1.3",
-    "@sylphx/iris-darwin-arm64": "0.2.0",
-    "@sylphx/iris-darwin-x64": "0.2.0",
-    "@sylphx/iris-linux-x64-gnu": "0.2.0",
-    "@sylphx/iris-linux-arm64-gnu": "0.2.0"
+    "@sylphx/iris-darwin-arm64": "0.3.0",
+    "@sylphx/iris-darwin-x64": "0.3.0",
+    "@sylphx/iris-linux-x64-gnu": "0.3.0",
+    "@sylphx/iris-linux-arm64-gnu": "0.3.0"
   }
 }

package/src/handlers/readImage.ts

@@ -116,8 +116,9 @@ export const readImage = tool()
       const fileStat = await stat(resolvedPath);
       validateImageSafety({ fileSizeBytes: fileStat.size });
 
+      const profile = input.profile ?? 'fast';
       const includeMetadata = input.include_metadata ?? true;
-      const includeOcr = input.include_ocr ?? false;
+      const includeOcr = input.include_ocr ?? profile === 'quality';
       const ocrLanguages = input.ocr_languages ?? ['eng'];
       const useRustDecode = shouldUseRustDecodeEngine();
 
@@ -243,7 +244,11 @@ export const readImage = tool()
         };
       }
 
-      twin = await applyImageIntelligence(twin, resolvedPath, input, includeOcr);
+      const intelligenceInput =
+        profile === 'quality' && input.include_semantics === undefined
+          ? { ...input, include_semantics: true as const }
+          : input;
+      twin = await applyImageIntelligence(twin, resolvedPath, intelligenceInput, includeOcr);
 
       if (input.region !== undefined) {
         if (!useRustDecode) {

package/src/schemas/readImage.ts

@@ -20,6 +20,12 @@ export const imageDimensionsSchema = z.object({
 
 export const readImageArgsSchema = z.object({
   path: z.string().min(1).describe('Path to the local image file (absolute or relative to cwd).'),
+  profile: z
+    .enum(['fast', 'quality'])
+    .optional()
+    .describe(
+      'Predictable work profile. Fast is deterministic geometry; quality explicitly enables OCR and optional local semantics. '
+    ),
   include_metadata: z
     .boolean()
     .optional()