@saifymatteo/pi-vision 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @saifymatteo/pi-vision
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Purpose and registrations
+
+Registers a `context` hook, not a tool or slash command. Preserves native images for image-capable session models by default. For text-only/unknown models it replaces image blocks with model-generated descriptions. Optional `describe` / `describe-old` policies self-describe all/older images using the current model on OpenAI Chat Completions connections.
+
+## Configuration and services
+
+Reads `<agent-dir>/extensions/vision-toolkit.json`: `model`, optional `fallbacks`, `imagePolicy` (native/describe/describe-old), `lang` (en/zh), and `providers` overrides. Example points at example.invalid and must be reviewed manually; it is never loaded automatically. Provider override keys support `$ENV_NAME` references (not brace syntax).
+
+Resolution also consults agent `models.json`, `models-store.json`, `auth.json`, and optional `haoyiyin/9router.json`. None of those real files are bundled. An explicit provider/model ID and override can resolve without a static catalog entry. Requires an image-capable OpenAI Chat Completions service; no CLI. Self-description requires current-model credentials in auth.json.
+
+## Bundled skill
+
+The package bundles the `vision-tools` skill (`skills/vision-tools`): `bin/` launcher CLIs (`crop`, `detect`, `glance`, `ground`, `trace`, `vision-doctor`), Python tools under `scripts/`, reference guides, and `SKILL.md`. The extension's guidance messages point the agent at `vision-doctor` and the skill. Requires Python 3 with Pillow (PIL); the CLIs are Python scripts, not compiled binaries. Based on [Anionex/agent-vision-toolkit](https://github.com/Anionex/agent-vision-toolkit) (MIT), modified in this repository — see [NOTICE.md](NOTICE.md).
+
+## Host limitations and security
+
+The hook expects host-cloned request messages; rewriting should not mutate stored sessions. No config files are created. Missing/broken config leaves native-capable models native, but text-only models receive explicit failure markers rather than images. Image pixels and focus hints from surrounding user/assistant messages are transmitted to the model service; descriptions enter main-model context. Do not pass sensitive screenshots. Up to four concurrent requests, in-process cache, 180s per-request timeout and transient retries; configured HTTP failures can fail over. This is a lossy bridge, not an image security boundary.
+
+Inherited caveats: cache keys include model ID but not provider/base URL; changing providers with the same ID can reuse cached descriptions until reload. The returned chain language is not propagated to individual candidates by the source. These behaviors were preserved, not repaired in this packaging work.
+
+## Tests
+
+From the repository root with its existing test dependencies available:
+
+```sh
+node --test packages/pi-vision/test/*.test.mjs
+```
+
+Tests use the shared test-only TypeScript/VM loader, fixtures, and host/service stubs. They do not prove compatibility with a live host, CLI, or model service.
+
+## Running locally
+
+From the repository root:
+
+```sh
+pi -e ./packages/pi-vision
+```
+
+Node >=24; host imports are peers, not bundled dependencies. Load only one copy: for an isolated session use `--no-extensions` with explicit `-e` paths so another installed copy is not also discovered. Set `PI_CODING_AGENT_DIR` to a disposable agent directory before launch; unset means the normal `~/.pi/agent` fallback. Extension config continues to resolve there, never relative to this package.
+
+Examples are manually authored, sanitized reference documents, not runtime defaults. Review and manually create only the needed files in the isolated agent directory; do not copy live credentials or endpoints. No example is automatically loaded or copied. Loading an extension grants Pi-process OS permissions. Licensed AGPL-3.0-only; see [NOTICE.md](NOTICE.md).

package/examples/vision-toolkit.example.json

@@ -0,0 +1,12 @@
+{
+  "model": "example-vision/example-model",
+  "fallbacks": [],
+  "imagePolicy": "native",
+  "lang": "en",
+  "providers": {
+    "example-vision": {
+      "baseUrl": "https://example.invalid/v1",
+      "apiKey": "$PI_VISION_API_KEY"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@saifymatteo/pi-vision",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE",
+    "skills"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=24"
+  },
+  "description": "Describe images for text-only models via a configured vision chain.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saifymatteo/pi-extensions.git",
+    "directory": "packages/pi-vision"
+  }
+}

package/skills/vision-tools/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anionex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/vision-tools/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: vision-tools
+description: >-
+  Native-first workflows for screenshot reconstruction, diagram extraction,
+  screenshot-driven GUI work, long-screenshot OCR, and image processing
+  (crops, pixel differences, palette measurements, SVG tracing, foreground
+  extraction). Use when a task needs these workflows or concrete image
+  artifacts; ordinary image questions can be answered with native vision.
+---
+
+# Vision tools
+
+Use the main model's native vision first. The tools here supplement it with
+image artifacts, measurements, or an optional separate-model opinion; they
+are not a required route for seeing images.
+
+## Workflow
+
+1. Inspect the image natively and identify what the task requires. If you only
+   have a description and need a missing detail, open the original image path.
+   If the file is gone, report the missing evidence.
+2. Zoom only when a relevant detail is unresolved. Crop that region and read
+   the crop natively; use `ground` only if its estimated box would help locate
+   the target. Stop inspecting once you have evidence for the requested answer.
+3. Use local image processing for numerical claims or reusable artifacts.
+   Treat model-generated boxes as estimates, not measured boundaries; verify
+   their target and coordinate space before acting on them.
+4. Verify the result against the task: readable text for OCR, nodes and edges
+   for diagrams, the expected UI state after an action, or a rendered comparison
+   for visual reconstruction. A low pixel-diff score alone is not correctness.
+
+For browser or accessible GUI work, prefer DOM/accessibility information for
+controls and state. Use screenshot coordinates when that information is
+unavailable or the task specifically concerns appearance.
+
+## Local tools: use when their output is needed
+
+Resolve `scripts/` paths relative to this skill directory. Use `--help` for
+additional options. These tools do not use the vision API; HTML rendering can
+load resources referenced by the page.
+
+| Need | Command |
+| --- | --- |
+| Reusable crop or close-up | `crop shot.png --region X1,Y1,X2,Y2 -o detail.png` |
+| Locate pixel differences | `python3 scripts/pixel_diff.py before.png after.png` |
+| Measure a region's palette | `python3 scripts/dominant_colors.py shot.png --region X1,Y1,X2,Y2` |
+| Vectorize a flat graphic | `trace icon.png -o icon.svg` |
+| Extract a transparent foreground | `python3 scripts/extract_fg.py shot.png --region X1,Y1,X2,Y2 -o icon.png` |
+| Render an HTML file | `python3 scripts/html_shot.py page.html --width 1440 --height 900 -o page.png` |
+
+- `crop --scale 4` enlarges a crop; it adds no missing detail. Coordinates
+  measured on that output use the enlarged grid, not the original image.
+- `pixel_diff` reports average intensity difference and ranked grid cells,
+  not the fraction of changed pixels or a semantic comparison. It rescales a
+  size-mismatched second image and reports that mismatch; match viewports
+  before judging visual fidelity.
+- `dominant_colors` clusters sampled pixels. `--candidates '#F9FAFA,#F5F5F5'`
+  selects the closest supplied palette value; it does not recover original CSS.
+- `trace` produces approximate vector paths from pixels, with filtering,
+  scaling and curve fitting. It is not an exact size/offset measurement tool.
+  It suits flat, high-contrast graphics; text becomes paths. Read the graphic
+  playbook before shipping its output.
+- `extract_fg` has manual-region and centered-icon auto modes. Inspect the
+  alpha edges and complete foreground on light and dark backgrounds before use.
+
+Use existing utilities when they fit. A small Pillow operation is also fine
+when it is the simplest way to obtain an output these tools do not provide.
+
+## Task playbooks: load only the matching one
+
+| Task | Read |
+| --- | --- |
+| Long screenshot or chat-history transcription, chunking and boundary checks | `references/long-screenshot-ocr.md` |
+| Rebuild or align a UI from a reference; fast approximation or close fidelity | `references/restore-ui.md` |
+| Extract or rebuild an isolated graphic as PNG/SVG | `references/restore-graphic.md` |
+| Convert a visual diagram into Mermaid, Graphviz or structured data | `references/restore-structure.md` |
+| Operate a GUI from screenshots: calibrate, act, verify | `references/gui.md` |
+
+## Optional model-backed CLIs
+
+Use these only for a requested second opinion, a needed box/list contract,
+scripted OCR, or a model without native image input. They send images to the
+separately configured vision chain, not to the main agent model automatically.
+Structured output does not guarantee better recognition or localization.
+
+```bash
+glance shot.png -q "Read the small status label."
+glance shot.png --region X1,Y1,X2,Y2 --ocr
+glance before.png after.png -q "What changed semantically?"
+ground shot.png "the send button"
+detect shot.png "buttons"
+```
+
+`ground` and `detect` return estimated boxes in original-image pixels, including
+with `--region`. They can miss objects or select the wrong target, not just
+round an edge incorrectly. `detect` is not an exhaustive inventory guarantee.
+For multi-image questions, pass the images in one call so the model sees them
+together. Native side-by-side inspection is also sufficient for semantic
+comparison; use pixel diff when numerical differences matter.
+
+The long-screenshot OCR script still uses `glance` for automated transcription.
+Its `--split-only` mode makes chunks without API requests for native inspection.
+Keep the `glance` client/config available if using the automated path.
+
+### Configuration and failures
+
+`extensions/vision-toolkit.json` under the Pi agent directory selects the CLI `model` and
+`fallbacks`. For image-capable main models, `imagePolicy` defaults to `native`:
+old and new images stay images, with no automatic description request.
+`describe-old` and `describe` are legacy, explicit opt-ins for lossy image-to-text
+conversion on supported connections. Text-only or unknown-capability models
+still use the configured compatibility bridge. This policy does not route CLI
+calls through the main model.
+
+On a model-backed CLI configuration/API error, run `vision-doctor`. Use
+`vision-doctor --smoke` only when a real diagnostic request is needed; it sends
+a test image. Relay failures honestly. Continue with native inspection when
+available; report if the scripted output cannot be produced. Keep provider
+changes user-controlled: do not scrape credentials, hand-export secret overrides,
+or silently switch to an unconfigured provider.
+
+Local tools need their optional dependencies (Pillow, NumPy, vtracer or a
+Chrome-family browser, depending on the tool). If a command is missing, use an
+already available equivalent or report the missing capability; API diagnostics
+do not fix local dependency errors.
+
+## Image lifetime
+
+Use temporary image paths directly for immediate inspection. Copy into durable
+work storage only when the file must survive its owner or session, or be kept
+with deliverables. Clipboard-image attachments are deleted at Pi session
+shutdown; preserve them beforehand only if needed beyond that session.
+
+Source: https://github.com/Anionex/agent-vision-toolkit

package/skills/vision-tools/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent Vision Toolkit"
+  short_description: "Native-first workflows and optional image processing"
+  default_prompt: "Use $vision-tools for native-first inspection, task-specific verification, and image-processing tools only when needed."

package/skills/vision-tools/bin/crop

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""crop: cut a pixel box out of an image into its own file.
+
+The other CLIs zoom by re-cropping in memory (glance --region, trace
+--region), but once the same box is needed twice — feed it to pixel_diff,
+dominant_colors, trace, or another agent — it earns a file. Coordinates are
+the same X1,Y1,X2,Y2 pixel boxes ground/detect print, and are clamped to
+the image bounds exactly like the --region flags elsewhere in the toolkit.
+"""
+
+import argparse
+import sys
+# Windows consoles default to cp1252; descriptions can contain any Unicode.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+from pathlib import Path
+
+
+def parse_region(region: str) -> tuple[int, int, int, int]:
+    parts = region.split(",")
+    if len(parts) != 4:
+        raise ValueError("--region expects four integers: X1,Y1,X2,Y2 (pixels)")
+    try:
+        return (int(parts[0]), int(parts[1]), int(parts[2]), int(parts[3]))
+    except ValueError:
+        raise ValueError("--region expects four integers: X1,Y1,X2,Y2 (pixels)") from None
+
+
+def clamp_box(box: tuple[int, int, int, int], width: int, height: int) -> tuple[int, int, int, int]:
+    x1, y1, x2, y2 = box
+    x1, x2 = sorted((x1, x2))
+    y1, y2 = sorted((y1, y2))
+    return (max(0, x1), max(0, y1), min(width, x2), min(height, y2))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="crop",
+        description="Cut a pixel box out of an image into its own file (local, no vision API)",
+    )
+    parser.add_argument("image", help="path to the image")
+    parser.add_argument("--region", metavar="X1,Y1,X2,Y2", required=True,
+                        help="pixel box to cut out (e.g. a box from ground); clamped to the image bounds")
+    parser.add_argument("-o", "--output",
+                        help="write the crop here (default: <image-stem>.crop.png next to the input)")
+    parser.add_argument("--scale", type=int, default=1, metavar="N",
+                        help="upscale the cut-out N times (LANCZOS) before writing; "
+                             "use 2-4 for small icons before ground/trace")
+    args = parser.parse_args()
+    if args.scale < 1:
+        parser.exit(1, "crop: --scale must be >= 1\n")
+
+    try:
+        from PIL import Image
+    except ImportError:
+        parser.exit(1, "crop: requires Pillow; install the optional dependency pillow first\n")
+
+    source = Path(args.image).expanduser()
+    if not source.is_file():
+        parser.exit(1, f"crop: Image not found: {source}\n")
+
+    try:
+        x1, y1, x2, y2 = parse_region(args.region)
+    except ValueError as exc:
+        parser.exit(1, f"crop: {exc}\n")
+
+    with Image.open(source) as image:
+        width, height = image.size
+        box = clamp_box((x1, y1, x2, y2), width, height)
+        if box[2] <= box[0] or box[3] <= box[1]:
+            parser.exit(1, f"crop: --region {args.region} is empty after clamping to {width}x{height}\n")
+        if box != (x1, y1, x2, y2):
+            print(f"note: region {x1},{y1},{x2},{y2} clamped to {box[0]},{box[1]},{box[2]},{box[3]}",
+                  file=sys.stderr)
+        if args.output:
+            output = Path(args.output).expanduser()
+        elif args.scale > 1:
+            output = source.with_name(source.stem + f".crop@{args.scale}x.png")
+        else:
+            output = source.with_name(source.stem + ".crop.png")
+        try:
+            crop = image.crop(box)
+            if args.scale > 1:
+                crop = crop.resize((crop.width * args.scale, crop.height * args.scale),
+                                   resample=Image.LANCZOS)
+            crop.save(output)
+        except OSError as exc:
+            parser.exit(1, f"crop: cannot write {output}: {exc}\n")
+    print(f"wrote {output} ({(box[2] - box[0]) * args.scale}x{(box[3] - box[1]) * args.scale})")
+
+
+if __name__ == "__main__":
+    main()

package/skills/vision-tools/bin/detect

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""detect: inventory the elements in an image and print pixel bounding boxes."""
+
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+# Windows consoles default to cp1252; descriptions can contain any Unicode.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+from detect import main  # noqa: E402
+
+
+if __name__ == "__main__":
+    main()

package/skills/vision-tools/bin/glance

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""glance: standalone image description, Q&A, and OCR CLI."""
+
+import argparse
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+# Windows consoles default to cp1252; descriptions can contain any Unicode.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+from vision_client import (  # noqa: E402
+    VisionError,
+    describe_image,
+    image_path_to_data_url,
+    load_default_env,
+)
+
+
+def region_data_url(path, region):
+    try:
+        from PIL import Image
+    except ImportError:
+        raise VisionError("--region requires Pillow; install the optional dependency pillow first")
+    try:
+        x1, y1, x2, y2 = (int(v) for v in region.split(","))
+    except ValueError:
+        raise VisionError("--region expects four integers: X1,Y1,X2,Y2 (pixels)")
+    import base64
+    import io
+    try:
+        with Image.open(Path(path).expanduser()) as image:
+            width, height = image.size
+            box = (max(0, min(x1, x2)), max(0, min(y1, y2)),
+                   min(width, max(x1, x2)), min(height, max(y1, y2)))
+            if box[2] <= box[0] or box[3] <= box[1]:
+                raise VisionError(f"--region {region} is empty after clamping to {width}x{height}")
+            buffer = io.BytesIO()
+            image.crop(box).save(buffer, format="PNG")
+    except (OSError, ValueError) as exc:
+        raise VisionError(f"Cannot read image: {path}") from exc
+    return "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode()
+
+
+def build_prompt(args, count):
+    if args.ocr is not None:
+        extra = f" Additional requirements: {args.ocr}" if args.ocr else ""
+        scope = "these images" if count > 1 else "this image"
+        return (
+            f"Transcribe every piece of visible text in {scope} verbatim (titles, body text, labels, watermarks, etc.), "
+            "line by line, without omitting any characters. Do not rewrite, summarize, or translate the text, "
+            "and do not add any preamble, explanation, or extra content."
+            + (" Label each image's text with its ordinal (Image 1, Image 2, ...)." if count > 1 else "")
+            + extra
+        )
+    if args.query:
+        return args.query
+    if count > 1:
+        return ("Describe each image in detail (label them Image 1, Image 2, ...), "
+                "then point out the notable differences between them.")
+    return None
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="glance",
+        description="Describe, answer questions about, or OCR an image with the configured vision model",
+    )
+    parser.add_argument("images", nargs="+", metavar="image",
+                        help="path(s) to the image(s); pass several to compare them in one call")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument("-q", "--query", help="ask a question about the image(s)")
+    group.add_argument("--ocr", nargs="?", const="", metavar="EXTRA", help="transcribe all visible text verbatim")
+    parser.add_argument("--region", metavar="X1,Y1,X2,Y2",
+                        help="crop to this pixel box (e.g. from ground) and send only the crop")
+    args = parser.parse_args()
+    load_default_env()
+    try:
+        if args.region and len(args.images) > 1:
+            raise VisionError("--region works with exactly one image")
+        urls = ([region_data_url(args.images[0], args.region)] if args.region
+                else [image_path_to_data_url(path) for path in args.images])
+        answer = describe_image(
+            urls,
+            build_prompt(args, len(urls)),
+            max_tokens=None,  # no output cap; the vision model decides
+            apply_lang=args.ocr is None,
+        )
+    except VisionError as exc:
+        parser.exit(1, f"glance: {exc}\n")
+    print(answer)
+
+
+if __name__ == "__main__":
+    main()

package/skills/vision-tools/bin/ground

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""ground: locate objects in an image and print pixel bounding boxes."""
+
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+# Windows consoles default to cp1252; descriptions can contain any Unicode.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+from ground import main  # noqa: E402
+
+
+if __name__ == "__main__":
+    main()

package/skills/vision-tools/bin/trace

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""trace: deterministic image-to-SVG tracing for exact shape geometry.
+
+Runs fully local (no vision API, no credentials): coordinates come from the
+actual pixels, so use this instead of asking a vision model for shapes,
+sizes, or outlines. Flat, high-contrast graphics only; text becomes curves.
+"""
+
+import argparse
+from pathlib import Path
+import re
+import sys
+import tempfile
+
+# Windows consoles default to cp1252; descriptions can contain any Unicode.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+WHITE_FILLS = {"#ffffff", "#fff", "white"}
+
+# Speckle filtering drops components under a fixed pixel area, so a 30px icon
+# binarizes to nothing at 1x while the same icon enlarged traces cleanly.
+# Enlarge anything smaller than this; full-size screenshots already clear it.
+TARGET_MIN_SIDE = 256
+
+
+def strip_background(svg):
+    """Drop the leading full-canvas white path vtracer emits for the background."""
+    match = re.search(r"<path [^>]*/>", svg)
+    if match:
+        fill = re.search(r'fill="([^"]+)"', match.group(0))
+        if fill and fill.group(1).strip().lower() in WHITE_FILLS:
+            return svg.replace(match.group(0), "", 1)
+    return svg
+
+
+def truncate_decimals(svg, places=2):
+    return re.sub(r"-?\d+\.\d{3,}", lambda m: f"{float(m.group()):.{places}f}", svg)
+
+
+def write_svg(path, svg):
+    """Write the exact UTF-8 payload whose byte count is reported to callers."""
+    payload = svg.encode("utf-8")
+    return Path(path).expanduser().write_bytes(payload)
+
+
+def prepare_input(path, region, scale):
+    """Crop/upscale with Pillow when asked; return the path vtracer reads and the scale used.
+
+    `scale` may be None, meaning "pick one from the size": small shapes are
+    enlarged until they survive speckle filtering. Without Pillow we cannot
+    measure the image, so that choice falls back to no upscale.
+    """
+    try:
+        from PIL import Image
+    except ImportError:
+        if region or (scale or 1) != 1:
+            sys.exit("trace: --region/--scale require Pillow; install the optional dependency pillow first")
+        return str(path), 1
+    with Image.open(path) as image:
+        if region:
+            try:
+                x1, y1, x2, y2 = (int(v) for v in region.split(","))
+            except ValueError:
+                sys.exit("trace: --region expects four integers: X1,Y1,X2,Y2 (pixels)")
+            box = (max(0, min(x1, x2)), max(0, min(y1, y2)),
+                   min(image.width, max(x1, x2)), min(image.height, max(y1, y2)))
+            if box[2] <= box[0] or box[3] <= box[1]:
+                sys.exit(f"trace: --region {region} is empty after clamping to {image.width}x{image.height}")
+            image = image.crop(box)
+        if scale is None:
+            shortest = max(min(image.width, image.height), 1)
+            scale = max(2 if region else 1, -(-TARGET_MIN_SIDE // shortest))
+        if not region and scale == 1:
+            return str(path), 1
+        if scale != 1:
+            image = image.resize((image.width * scale, image.height * scale), Image.LANCZOS)
+        handle = tempfile.NamedTemporaryFile(suffix=".png", delete=False)
+        image.save(handle.name)
+        return handle.name, scale
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="trace",
+        description="Trace an image into SVG with exact pixel-derived geometry (local, deterministic)",
+    )
+    parser.add_argument("image", help="path to the image")
+    parser.add_argument("--region", metavar="X1,Y1,X2,Y2",
+                        help="crop to this pixel box first (e.g. a box from ground)")
+    parser.add_argument("--scale", type=int, metavar="N",
+                        help="upscale N times before tracing (default: enough to clear "
+                             f"{TARGET_MIN_SIDE}px on the shorter side, so small icons survive)")
+    parser.add_argument("--polygon", action="store_true",
+                        help="polygon mode for boxy diagrams/wireframes (default: spline for curved shapes)")
+    parser.add_argument("--color", action="store_true",
+                        help="keep colors (default: black-and-white, which is far more compact)")
+    parser.add_argument("-o", "--output", help="write the SVG here instead of stdout")
+    args = parser.parse_args()
+    try:
+        import vtracer
+    except ImportError:
+        parser.exit(1, "trace: requires vtracer; install the optional dependency vtracer first\n")
+    source = Path(args.image).expanduser()
+    if not source.is_file():
+        parser.exit(1, f"trace: Image not found: {source}\n")
+    work, scale = prepare_input(source, args.region, args.scale)
+    with tempfile.NamedTemporaryFile(suffix=".svg", delete=False) as out:
+        vtracer.convert_image_to_svg_py(
+            work, out.name,
+            colormode="color" if args.color else "binary",
+            filter_speckle=8, corner_threshold=40,
+            mode="polygon" if args.polygon else "spline",
+        )
+        svg = Path(out.name).read_text()
+    svg = truncate_decimals(strip_background(svg))
+    paths = svg.count("<path")
+    if not paths:
+        # This is where an agent decides the tool cannot see the shape and goes
+        # back to guessing. Name the recoveries instead, cheapest first.
+        print("trace: 0 paths - nothing survived binarization. Try a larger --scale, "
+              "--region to crop closer to the shape, or pre-invert a light-on-dark image. "
+              "--color is a last resort: on an anti-aliased image it splits every gray "
+              "level into its own path.", file=sys.stderr)
+    if args.output:
+        bytes_written = write_svg(args.output, svg)
+        print(f"wrote {args.output} ({bytes_written} bytes, {paths} paths, traced at {scale}x)")
+    else:
+        print(svg)
+
+
+if __name__ == "__main__":
+    main()