@saifymatteo/pi-vision 0.0.0-stage → 0.1.0

package/skills/vision-tools/bin/vision-doctor

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""vision-doctor: validate the vision-tools config chain before a task, and
+diagnose any vision error afterwards.
+
+Resolves vision-toolkit.json the same way every tool in this skill does
+(model + fallbacks -> providers -> models.json/models-store.json ->
+package-provider configs -> auth.json), prints what each candidate resolved
+to, and can fire one real 1-token request (--smoke) to prove the chain
+end-to-end. On any vision error, run this first: never scrape auth.json and
+never hand-export VISION_* environment variables.
+"""
+
+import argparse
+import base64
+import sys
+import time
+from pathlib import Path
+
+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,
+    apply_resolved_to_env,
+    describe_image,
+    resolve_vision_config,
+)
+
+# 8x8 red PNG: a fixed tiny image so --smoke costs one token of attention.
+SMOKE_PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAYAAADED76LAAAAGElEQVR4nGP8z8Dwn4EIwESMolGK"
+    "SjEAAJ0QBAE5tHqKAAAAAElFTkSuQmCC"
+)
+
+SMOKE_PROMPT = "What colour is this square? Answer with one word."
+
+
+def fingerprint(key):
+    if not key:
+        return None
+    return key[:6] + "..." + key[-4:] if len(key) > 12 else "***"
+
+
+def print_resolution(resolution):
+    cfg = resolution["cfg"]
+    print("extensions/vision-toolkit.json (%s):" % resolution["agent_dir"])
+    shown = {k: v for k, v in cfg.items() if k != "providers"}
+    print("  " + repr(shown))
+    if cfg.get("providers"):
+        print("  providers overrides present for: %s" % ", ".join(cfg["providers"]))
+    print()
+    attempts = resolution["attempts"]
+    if not attempts:
+        print("no candidates found in vision-toolkit.json")
+        return
+    # Group by base spec: a bare-id primary resolves through several providers
+    # in search order (openrouter -> anthropic -> ... -> 9router); those
+    # attempts are one candidate's resolution trail, not configured fallbacks.
+    groups = []
+    for attempt in attempts:
+        base = attempt["spec"].split(" (as ")[0]
+        if not groups or groups[-1][0] != base:
+            groups.append((base, []))
+        groups[-1][1].append(attempt)
+    for gi, (base, group) in enumerate(groups):
+        head = "primary candidate" if gi == 0 else "fallback candidate %d" % gi
+        print("%s: %s" % (head, base))
+        ok = next((a for a in group if a.get("ok")), None)
+        for a in group:
+            if a is not ok:
+                print("  tried as %s" % a["spec"])
+                print("    FAILED: %s" % a["error"])
+        if ok is not None:
+            if len(group) > 1:
+                print("  resolved as %s" % ok["spec"])
+            _print_attempt(ok)
+        else:
+            print("  status    -> FAILED: %s" % group[0]["error"])
+        print()
+
+
+def _print_attempt(attempt):
+    print("  model     -> %s/%s" % (attempt["provider"], attempt["model_id"]))
+    print("  catalog   -> %s" % ("static catalog entry" if attempt.get("in_catalog")
+                                  else "runtime provider (id validated at request time)"))
+    print("  image     -> %s" % ({True: "yes", False: "NO - not vision-capable",
+                                  None: "unknown (runtime catalog)"}[attempt["image_capable"]]))
+    print("  baseUrl   -> %s  (from %s)" % (attempt["base_url"], attempt["base_source"]))
+    print("  apiKey    -> %s  (from %s)" % (fingerprint(attempt.get("key_fingerprint") or ""),
+                                            attempt["key_source"]))
+    print("  protocol  -> %s" % attempt["protocol"])
+    print("  status    -> OK")
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate the vision-tools config chain.")
+    parser.add_argument("--smoke", action="store_true",
+                        help="send one tiny real image request through the primary candidate")
+    parser.add_argument("--json", action="store_true", help="machine-readable resolution report")
+    args = parser.parse_args()
+
+    resolution = resolve_vision_config()
+    config = resolution["config"]
+
+    if args.json:
+        import json
+        report = {"config": None, "attempts": resolution["attempts"],
+                  "cfg": {k: v for k, v in resolution["cfg"].items() if k != "providers"}}
+        if config:
+            report["config"] = {k: v for k, v in config.items() if k != "api_key"}
+            report["config"]["key_fingerprint"] = fingerprint(config.get("api_key"))
+        print(json.dumps(report, indent=1, default=str))
+        return 0 if config else 1
+
+    print("vision-doctor: resolving the vision-tools chain\n")
+    print_resolution(resolution)
+
+    if not config:
+        print("SUMMARY: UNRESOLVED - no candidate has both a key and a baseUrl.")
+        print("Fix the first failing candidate above, then re-run vision-doctor.")
+        return 1
+
+    fallback_count = max(0, len(resolution["resolved"]) - 1)
+    extra = ""
+    if fallback_count:
+        extra = " (+%d fallback(s) resolved)" % fallback_count
+    print("SUMMARY: primary resolves%s." % extra)
+    primary = resolution["resolved"][0] if resolution["resolved"] else None
+    if primary and primary.get("image_capable") is False:
+        print("WARNING: the primary model is not vision-capable - pick one with "
+              '"image" input.')
+    if not args.smoke:
+        print("Run 'vision-doctor --smoke' to verify the API end-to-end.")
+        return 0
+
+    if fallback_count:
+        print("Note: --smoke tests the PRIMARY only; the CLIs fail over to "
+              "fallbacks automatically when it errors.")
+    apply_resolved_to_env(config)
+    import tempfile
+    with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as fh:
+        fh.write(SMOKE_PNG)
+        smoke_path = fh.name
+    try:
+        data_url = "data:image/png;base64," + base64.b64encode(SMOKE_PNG).decode()
+        started = time.time()
+        answer = describe_image(data_url, SMOKE_PROMPT, max_tokens=16)
+        elapsed = time.time() - started
+        print("SMOKE OK (%s, %.1fs): %s" % (config["model_id"], elapsed, answer.strip()[:80]))
+        return 0
+    except VisionError as exc:
+        print("SMOKE FAILED: %s" % exc)
+        print("The chain resolves but the API call failed. If this persists "
+              "(auth, model unknown, or upstream 4xx), fix the primary or let a "
+              'fallback take over by moving it up in "fallbacks".')
+        return 2
+    finally:
+        try:
+            Path(smoke_path).unlink()
+        except OSError:
+            pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/vision-tools/detect.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+try:
+    from PIL import Image
+except ImportError:
+    Image = None
+
+from ground import GroundError, _position, locate
+from vision_client import VisionError
+
+DEFAULT_CATEGORY = ("UI element (buttons, links, inputs, icons, labels, "
+                    "headings, images, badges)")
+
+
+def build_target(category: str | None) -> str:
+    return (f"every distinct {category or DEFAULT_CATEGORY} — "
+            "include the exact visible text in each label")
+
+
+def format_inventory(matches, width: int, height: int) -> list[str]:
+    lines = []
+    for index, match in enumerate(matches, 1):
+        x1, y1, x2, y2 = match.bbox
+        position = _position(match.bbox, width, height)
+        lines.append(f"{index}. {position} {match.label} x1: {x1}, y1: {y1}, x2: {x2}, y2: {y2}")
+    return lines or ["no elements detected"]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="detect",
+        description="Inventory the elements in an image (or a region) with pixel bounding boxes",
+    )
+    parser.add_argument("image", type=Path, help="path to the image")
+    parser.add_argument("category", nargs="?",
+                        help='restrict to a category, e.g. "buttons" or "icons" (default: all UI elements)')
+    parser.add_argument("--region", metavar="X1,Y1,X2,Y2",
+                        help="inventory only this pixel box; output stays in original-image coordinates")
+    args = parser.parse_args()
+    try:
+        matches = locate(args.image.expanduser(), build_target(args.category), region=args.region)
+        if Image is None:
+            raise GroundError("detect requires Pillow; install the optional dependency pillow first")
+        with Image.open(args.image.expanduser()) as image:
+            width, height = image.size
+    except (GroundError, VisionError) as exc:
+        parser.exit(1, f"detect: {exc}\n")
+    for line in format_inventory(matches, width, height):
+        print(line)
+
+
+if __name__ == "__main__":
+    main()

package/skills/vision-tools/ground.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import argparse
+import base64
+import io
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+try:
+    from PIL import Image
+except ImportError:
+    Image = None
+
+from vision_client import VisionError, describe_image, image_path_to_data_url, load_default_env
+
+
+@dataclass(frozen=True)
+class Match:
+    label: str
+    bbox: tuple[int, int, int, int]
+
+
+class GroundError(Exception):
+    pass
+
+
+def build_prompt(target: str) -> str:
+    return (
+        "Locate every visible object or region matching this target:\n"
+        f"{target}\n\n"
+        'Return only a JSON array. Each item must contain "box_2d" as '
+        '[y0, x0, y1, x1] on a 0-1000 grid and "label" as a short description. '
+        "Use tight boxes in the original image. Return [] when nothing matches."
+    )
+
+
+def _json_text(text: str) -> str:
+    cleaned = str(text or "").strip()
+    fenced = re.findall(r"```(?:json)?\s*(.*?)\s*```", cleaned, re.DOTALL | re.IGNORECASE)
+    return (fenced[-1] if fenced else cleaned).strip()
+
+
+def _fallback_items(text: str) -> list[dict[str, Any]]:
+    items = []
+    object_pattern = re.compile(r"\{[^{}]*['\"](?:box_2d|bbox_2d|box2d|bbox|box)['\"]\s*:\s*\[[^\]]+\][^{}]*\}", re.DOTALL)
+    box_pattern = re.compile(r"['\"](?:box_2d|bbox_2d|box2d|bbox|box)['\"]\s*:\s*\[([^\]]+)\]", re.DOTALL)
+    label_pattern = re.compile(r"['\"](?:label|caption|description)['\"]\s*:\s*['\"]([^'\"]+)['\"]", re.DOTALL)
+    for match in object_pattern.finditer(text):
+        block = match.group(0)
+        box_match = box_pattern.search(block)
+        if not box_match:
+            continue
+        numbers = re.findall(r"-?\d+(?:\.\d+)?", box_match.group(1))
+        if len(numbers) < 4:
+            continue
+        item: dict[str, Any] = {"box_2d": [float(value) for value in numbers[:4]]}
+        label_match = label_pattern.search(block)
+        if label_match:
+            item["label"] = label_match.group(1).strip()
+        items.append(item)
+    return items
+
+
+def _items(text: str) -> list[Any]:
+    cleaned = _json_text(text)
+    try:
+        payload = json.loads(cleaned)
+    except json.JSONDecodeError:
+        fallback = _fallback_items(cleaned)
+        if fallback:
+            return fallback
+        raise GroundError("Vision API did not return parseable bounding-box JSON")
+    if isinstance(payload, list):
+        return payload
+    if isinstance(payload, dict):
+        for key in ("boxes", "bounding_boxes", "bboxes", "objects", "items", "results"):
+            if isinstance(payload.get(key), list):
+                return payload[key]
+    raise GroundError("Vision API returned an incompatible bounding-box JSON structure")
+
+
+def _normalize_box(item: dict[str, Any], width: int, height: int) -> tuple[int, int, int, int] | None:
+    raw = item.get("box_2d")
+    if not isinstance(raw, list):
+        for key in ("bbox_2d", "box2d", "bbox", "box"):
+            if isinstance(item.get(key), list):
+                raw = item[key]
+                break
+    if not isinstance(raw, list) or len(raw) != 4:
+        return None
+    try:
+        y0, x0, y1, x1 = (float(value) for value in raw)
+    except (TypeError, ValueError):
+        return None
+    if x0 > x1:
+        x0, x1 = x1, x0
+    if y0 > y1:
+        y0, y1 = y1, y0
+    box = (
+        max(0, min(width, round(x0 / 1000 * width))),
+        max(0, min(height, round(y0 / 1000 * height))),
+        max(0, min(width, round(x1 / 1000 * width))),
+        max(0, min(height, round(y1 / 1000 * height))),
+    )
+    return box if box[2] > box[0] and box[3] > box[1] else None
+
+
+def parse_matches(text: str, width: int, height: int, target: str) -> list[Match]:
+    matches = []
+    for item in _items(text):
+        if not isinstance(item, dict):
+            continue
+        box = _normalize_box(item, width, height)
+        if box is None:
+            continue
+        label = str(item.get("label") or item.get("caption") or item.get("description") or target).strip()
+        matches.append(Match(label or target, box))
+    return matches
+
+
+def _parse_region(region: str, width: int, height: int) -> tuple[int, int, int, int]:
+    try:
+        x1, y1, x2, y2 = (int(value) for value in region.split(","))
+    except ValueError:
+        raise GroundError("--region expects four integers: X1,Y1,X2,Y2 (pixels)") from None
+    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 GroundError(f"--region {region} is empty after clamping to {width}x{height}")
+    return box
+
+
+def locate(image_path: Path, target: str, region: str | None = None) -> list[Match]:
+    if Image is None:
+        raise GroundError("ground requires Pillow; install the optional dependency pillow first")
+    load_default_env()
+    box = None
+    try:
+        with Image.open(image_path) as image:
+            width, height = image.size
+            if region:
+                box = _parse_region(region, width, height)
+                buffer = io.BytesIO()
+                image.crop(box).save(buffer, format="PNG")
+                url = "data:image/png;base64," + base64.b64encode(buffer.getvalue()).decode()
+    except (OSError, ValueError) as exc:
+        raise GroundError(f"Cannot read image: {image_path}") from exc
+    if box is None:
+        url = image_path_to_data_url(image_path)
+        width_used, height_used = width, height
+    else:
+        width_used, height_used = box[2] - box[0], box[3] - box[1]
+    # 8192 leaves room for exhaustive targets ("every UI element"): a dense
+    # screen can emit dozens of boxes and 2048 truncated the JSON mid-array.
+    response = describe_image(url, build_prompt(target), max_tokens=8192)
+    matches = parse_matches(response, width_used, height_used, target)
+    if box is None:
+        return matches
+    # Matches were parsed in crop coordinates; report them in the original image.
+    return [Match(m.label, (m.bbox[0] + box[0], m.bbox[1] + box[1],
+                            m.bbox[2] + box[0], m.bbox[3] + box[1])) for m in matches]
+
+
+def _position(box: tuple[int, int, int, int], width: int, height: int) -> str:
+    x1, y1, x2, y2 = box
+    x = (x1 + x2) / 2
+    y = (y1 + y2) / 2
+    horizontal = "left" if x < width / 3 else ("right" if x > width * 2 / 3 else "center")
+    vertical = "top" if y < height / 3 else ("bottom" if y > height * 2 / 3 else "center")
+    return {
+        ("left", "top"): "top-left", ("center", "top"): "top", ("right", "top"): "top-right",
+        ("left", "center"): "left", ("center", "center"): "center", ("right", "center"): "right",
+        ("left", "bottom"): "bottom-left", ("center", "bottom"): "bottom", ("right", "bottom"): "bottom-right",
+    }[(horizontal, vertical)]
+
+
+def format_matches(matches: list[Match], width: int, height: int) -> list[str]:
+    if len(matches) == 1:
+        x1, y1, x2, y2 = matches[0].bbox
+        return [f"x1: {x1}, y1: {y1}, x2: {x2}, y2: {y2}"]
+    lines = []
+    for index, match in enumerate(matches, 1):
+        x1, y1, x2, y2 = match.bbox
+        position = _position(match.bbox, width, height)
+        lines.append(f"{index}. {position} {match.label} x1: {x1}, y1: {y1}, x2: {x2}, y2: {y2}")
+    return lines
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="ground",
+        description="Locate targets in an image with natural language and output pixel coordinates",
+    )
+    parser.add_argument("image", type=Path, help="path to the image")
+    parser.add_argument("target", help="target object or region to locate")
+    parser.add_argument("--region", metavar="X1,Y1,X2,Y2",
+                        help="search only this pixel box; output stays in original-image coordinates")
+    args = parser.parse_args()
+    try:
+        matches = locate(args.image.expanduser(), args.target, region=args.region)
+        if Image is None:
+            raise GroundError("ground requires Pillow; install the optional dependency pillow first")
+        with Image.open(args.image.expanduser()) as image:
+            width, height = image.size
+    except (GroundError, VisionError) as exc:
+        parser.exit(1, f"ground: {exc}\n")
+    for line in format_matches(matches, width, height):
+        print(line)
+
+
+if __name__ == "__main__":
+    main()

package/skills/vision-tools/references/gui.md

@@ -0,0 +1,93 @@
+# Operating a GUI from screenshots
+
+**When to use**: the task is to act on a live screen — click, type,
+scroll — guided by screenshots: driving an app, automating a workflow,
+walking a bug reproduction. The vision layer answers "where is it" and
+"what state is it in"; the acting itself goes through whatever automation
+channel the task already has.
+
+Tool syntax lives in `SKILL.md`. This file is the sequence and the
+pass/fail test.
+
+## Steps
+
+**1. Calibrate coordinates once, before the first click.**
+
+Screenshot pixels and pointer coordinates are often different spaces: on
+HiDPI displays a screenshot is 2-3× the logical points the click API
+takes. Compare the screenshot's pixel width to the screen's logical width
+and divide every box by that ratio. Skipping this puts every click at half
+or double distance from the origin — consistently wrong in a way that
+looks like bad grounding.
+
+**2. Prefer the UI tree; fall back to vision.**
+
+If the environment exposes a UI tree (Android `uiautomator dump`, desktop
+accessibility tree, browser DOM), read coordinates and state from there —
+it is exact, fast, and carries semantic attributes (enabled, checked,
+focusable) that pixels cannot. Fall back to native screenshot inspection when:
+
+- No tree is available (games, custom-rendered canvases, remote desktops),
+- The target element is absent from the tree (canvas-drawn overlays,
+  non-standard widgets), or
+- You need to verify a visual state the tree doesn't expose (color, icon
+  appearance).
+
+Inspect the screenshot natively with the main agent's image reader. If a
+small target or state is unclear, crop the region and read it natively;
+translate crop coordinates back to the full screenshot before calibration.
+Use `ground` for an unresolved target box, `detect` for an inventory, or
+`glance` for a second opinion/OCR when needed.
+
+Model boxes are estimates: they can point at the wrong target or omit much
+of it, not just miss an edge by a few pixels. Verify the target visually
+before clicking its center. For tiny targets (checkboxes, close buttons),
+inspect a larger crop before acting.
+
+For elements that stay put across interactions (toolbar buttons, sidebar
+links, fixed panels), record verified center coordinates in a table with
+an id/label. Reuse them only while fresh screenshots confirm the layout is
+unchanged. Invalidate the table on resize, navigation, or scroll.
+
+**3. One screenshot per action — act, re-shoot, verify, then continue.**
+
+Every action invalidates the current screenshot: menus open, focus moves,
+content loads; scrolling invalidates every box at once. Chaining several
+clicks on one stale screenshot is how you click through where a dialog
+used to be.
+
+**4. Verify as a question about the expected state.**
+
+Read the fresh screenshot natively to answer the expected-state question,
+for example "is the settings dialog open?" If not, stop and inspect the
+current screen instead of pressing on against an assumed state. For a
+small change (a toggle, one badge), optionally use `pixel_diff` to locate
+the changed region, then crop and read it natively. A targeted `glance`
+question remains available for an unresolved state.
+
+**5. After typing, read the field back.**
+
+Focus loss eats keystrokes silently. Read the field value from the UI tree
+when available; otherwise inspect it natively, cropping if necessary.
+Use targeted OCR only if the text remains unclear. Confirm the text
+actually landed before submitting.
+
+## Verify
+
+The loop in steps 3-4 *is* the verification: no action counts as done
+until a fresh screenshot answers the expected-state question. For a
+multi-step flow, the final screenshot must show the end state the task
+defines — the confirmation page, the saved indicator. A completed action
+list is not evidence; the pixels are.
+
+## Boundaries
+
+- Loading is asynchronous: after an action that triggers it, poll —
+  re-screenshot until two consecutive shots stop differing (`pixel_diff`
+  near 0) — rather than trusting one fixed sleep.
+- Irreversible actions (send, delete, pay) follow the calling agent's own
+  confirmation policy. The vision layer reports what is on screen; it
+  never makes that call.
+- A screen the task didn't predict — an error dialog, a permission
+  prompt, a login wall — is a stop-and-surface, not an obstacle to click
+  through. Clicking through unknown dialogs is how automations do damage.

package/skills/vision-tools/references/long-screenshot-ocr.md

@@ -0,0 +1,103 @@
+# OCR a long screenshot without losing boundary text
+
+**Use for**: a vertically scrolling screenshot, chat history, long web page,
+requirements conversation, log view, or other image that would be downscaled too
+aggressively in one vision call. For a PDF or an exported document, prefer a
+format-aware document parser instead of screenshot OCR.
+
+## Run the workflow
+
+Read the source at its current path; copy it only when it needs to persist
+beyond a temporary file's lifetime. Inspect the script's help before choosing
+options:
+
+```bash
+python3 scripts/long_screenshot_ocr.py --help
+```
+
+Prefer native chunk reading by the main agent; the glance-backed script is
+available for automated transcription. Both paths use the same content-aware
+splitter; verify joins even when the cut falls in a low-content band.
+
+### Native chunk reading
+
+```bash
+python3 scripts/long_screenshot_ocr.py work/page.png --split-only
+```
+
+This writes ordered chunk images and `manifest.json` without vision calls.
+Read the chunks natively in manifest order and assemble `work/page.ocr.md`.
+For unresolved text, crop the relevant region and read it natively. Verify
+every join against both adjacent images, removing only confirmed overlap;
+preserve chat senders, timestamps, and quoted messages. Split-only does not
+produce merged OCR or `ocr_audit.md`, so record uncertain joins in the output.
+
+### Automated transcription with glance
+
+Choose the content mode; this path makes configured vision calls:
+
+```bash
+# Web pages, documents, logs, tables, and other general content
+python3 scripts/long_screenshot_ocr.py work/page.png -o work/page.ocr.md
+
+# Chat histories: preserve message grouping, senders, timestamps, and quotes
+python3 scripts/long_screenshot_ocr.py work/chat.png --mode chat -o work/chat.ocr.md
+```
+
+Without `-o`, write `<input-stem>.ocr.md`; store chunks, sidecars, the manifest,
+and the audit in `<input-stem>_chunks/` unless `--chunks-dir` overrides it.
+
+The script performs four operations:
+
+1. Measure per-row content density and find low-content cut bands near the
+   target height.
+2. Add pixel overlap only when no safe band exists, so text crossing a risky
+   cut appears in both adjacent chunks.
+3. Run `glance` on the chunks through the configured `vision-toolkit.json`
+   chain (or legacy `VISION_*` settings); chat mode requests structured messages
+   while general mode uses verbatim OCR.
+4. Merge only confident repeated lines or messages and write `manifest.json` plus
+   `ocr_audit.md` beside the chunks.
+
+Use `--resume` after an interrupted run. A chunk is reused only when its image,
+mode, and custom prompt fingerprint still match:
+
+```bash
+python3 scripts/long_screenshot_ocr.py work/chat.png --mode chat --resume -o work/chat.ocr.md
+```
+
+If the defaults produce awkward chunks, rerun with `--target-height`,
+`--min-height`, `--max-height`, or `--overlap`. Keep enough height for local
+context; do not make tiny OCR tiles unless the source text is unusually small.
+
+## Verify before delivering
+
+1. Read the merged Markdown from top to bottom and compare its opening and
+   ending lines with the source.
+2. For automated transcription, open `ocr_audit.md` and review every boundary
+   marked `yes` against the two adjacent `chunk_*.png` files. A marked boundary
+   used pixel overlap or fuzzy text matching and is not safe to accept blindly.
+   For native chunk reading, verify every join against adjacent images and the
+   manifest; no automated merge audit is generated.
+3. Check sender changes, timestamps, quoted messages, table row breaks, code
+   indentation, and paragraphs that cross chunk boundaries.
+4. For doubtful text, crop and read the region natively. If it remains
+   unresolved, targeted specialist OCR is available:
+
+   ```bash
+   glance work/page_chunks/chunk_002.png --ocr "Re-check the final five lines carefully."
+   glance work/page_chunks/chunk_002.png --region X1,Y1,X2,Y2 --ocr
+   ```
+
+5. Keep visible spelling and punctuation verbatim. Write `[unreadable]` for
+   text that remains illegible; do not silently guess or editorially repair it.
+
+## Output contract
+
+- Return the merged `.ocr.md` file as the primary result.
+- Keep the chunk directory until verification is complete; it is the evidence
+  for ordering and boundary decisions.
+- Report unresolved `[unreadable]` text and every boundary that still needs
+  human review.
+- Do not claim a complete transcription when the first or last screenshot edge
+  visibly clips content.