Upload folder using huggingface_hub

.env.example

@@ -2,11 +2,19 @@
 
 # Gemma 4 12B Unified omni (vision + embed). Lamp: set URLs to the GPU box.
 # Does not fit on the Lamp (6 GB). GPU util cap 0.85.
+# Route: auto | direct | hermes | studio
 RECEIPT_LLM_BACKEND=gemma
+RECEIPT_LLM_ROUTE=auto
 RECEIPT_LLM_BASE_URL=http://127.0.0.1:8080/v1
 RECEIPT_LLM_MODEL=google/gemma-4-12B-it
 RECEIPT_LLM_ACCEPTS_IMAGES=true
 RECEIPT_LLM_MAX_TOKENS=8192
+# Lamp: POST snapshots here (Receipt Studio on the GPU box)
+# RECEIPT_STUDIO_URL=http://192.168.1.10:7860
+# RECEIPT_GPU_HOST=192.168.1.10
+# Hermes custom_providers discovery (optional)
+# RECEIPT_HERMES_BASE_URL=http://127.0.0.1:8080/v1
+# RECEIPT_HERMES_MODEL=google/gemma-4-12B-it
 
 RECEIPT_EMBED_BACKEND=omni
 RECEIPT_EMBED_BASE_URL=http://127.0.0.1:8080/v1
@@ -21,7 +29,8 @@ RECEIPT_CAMERA_URL=http://127.0.0.1:5001
 RECEIPT_SNAPSHOT_WIDTH=1280
 RECEIPT_SNAPSHOT_QUALITY=85
 
-# UI / inbox
+# UI / inbox. One-click (app.launch / oneshot) forces SHARE_LAN=true for iPhone.
+# Manual `python -m app.cli ui` needs true or the phone cannot reach this PC.
 RECEIPT_UI_HOST=127.0.0.1
 RECEIPT_UI_PORT=7860
 RECEIPT_UI_SHARE_LAN=false

.gitattributes

@@ -36,3 +36,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 docs/screenshots/05-iphone-home.jpg filter=lfs diff=lfs merge=lfs -text
 docs/screenshots/06-iphone-upload.jpg filter=lfs diff=lfs merge=lfs -text
 docs/screenshots/07-iphone-complete.jpg filter=lfs diff=lfs merge=lfs -text
+docs/promo/Keys-Auto-Receipts-Studio-promo.mp4 filter=lfs diff=lfs merge=lfs -text

.grok/skills/keys-receipt-scanner/SKILL.md

@@ -7,7 +7,8 @@ description: Scan receipts/docs via Lamp camera or inbox, Gemma 4 12B Unified om
 
 Work in `keys-automatic-receipt-doc-scanner`. Architecture is in `AGENTS.md`.
 
-- Lamp 6 GB: skill + camera only. Gemma 4 12B Unified stays on the GPU box.
+- Autonomous OS Lamp skill lives in `skills/keys-receipt-scanner/` (push to `/root/.openclaw/workspace/skills/keys-receipt-scanner/`).
+- Lamp 6 GB: skill + camera only. Gemma 4 12B Unified stays on the GPU box (direct vLLM, Hermes `custom_providers`, or Studio `/api/inbox`).
 - Default LLM/embed: Gemma 4 12B Unified, dim 3840, `embed_backend=omni`.
 - Qwen3.8-27B ADay777 is the vision fallback (`llm_backend=nvidia`). Lightning is text-only — never send images.
 - Do not download weights. Do not raise GPU util above 0.85.

.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

.pytest_cache/v/cache/lastfailed

@@ -0,0 +1 @@
+{}

.pytest_cache/v/cache/nodeids

@@ -0,0 +1,34 @@
+[
+  "tests/test_camera.py::test_aim_posts_direction",
+  "tests/test_camera.py::test_snapshot_reads_path",
+  "tests/test_db.py::test_schema_and_meta",
+  "tests/test_embed_prefix.py::test_embed_request_body_has_prefix_and_input_type",
+  "tests/test_embed_prefix.py::test_prefix_query_and_passage",
+  "tests/test_embed_prefix.py::test_wrong_dim_rejected",
+  "tests/test_extract_vision.py::test_gemma_sends_image_url",
+  "tests/test_extract_vision.py::test_lightning_never_sends_image",
+  "tests/test_match.py::test_bands",
+  "tests/test_match.py::test_exact_sku",
+  "tests/test_match.py::test_knn_auto",
+  "tests/test_route.py::test_looks_like_gemma",
+  "tests/test_route.py::test_parse_hermes_finds_gemma_only",
+  "tests/test_route.py::test_parse_live_hermes_config_does_not_crash",
+  "tests/test_route.py::test_resolve_auto_studio",
+  "tests/test_route.py::test_resolve_direct",
+  "tests/test_route.py::test_resolve_hermes",
+  "tests/test_scan_script.py::test_post_gemma_sends_image_url",
+  "tests/test_scan_script.py::test_post_studio_polls_job",
+  "tests/test_schema.py::test_bad_types",
+  "tests/test_schema.py::test_parse_fenced",
+  "tests/test_schema.py::test_parse_good",
+  "tests/test_schema.py::test_unknown_category_falls_back",
+  "tests/test_skill_frontmatter.py::test_skill_frontmatter",
+  "tests/test_ui_edit.py::test_as_text_joins_code_widget_lists",
+  "tests/test_ui_edit.py::test_parse_rid",
+  "tests/test_ui_edit.py::test_phone_page_splits_camera_and_library",
+  "tests/test_ui_edit.py::test_pretty_json_indents",
+  "tests/test_ui_edit.py::test_pretty_json_rejects_garbage",
+  "tests/test_ui_edit.py::test_table_rows_from_lists",
+  "tests/test_watcher.py::test_ignores_syncthing",
+  "tests/test_watcher.py::test_settles_after_idle"
+]

app/camera.py

@@ -32,3 +32,18 @@ def snapshot(settings: Settings, *, client: httpx.Client | None = None) -> Path:
     if not path:
         raise CameraError(f"snapshot JSON missing path: {payload!r}")
     return Path(path)
+
+
+def aim(settings: Settings, direction: str = "down", *, client: httpx.Client | None = None) -> None:
+    """HAL servo aim. Call before snapshot when the paper is on the desk."""
+    url = f"{settings.camera_url.rstrip('/')}/servo/aim"
+    own = client is None
+    http = client or httpx.Client(timeout=15.0)
+    try:
+        response = http.post(url, json={"direction": direction})
+        response.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise CameraError(f"Lamp servo aim failed: {exc}") from exc
+    finally:
+        if own:
+            http.close()

app/cli.py

@@ -6,7 +6,7 @@ import shutil
 import sys
 from pathlib import Path
 
-from app.camera import snapshot
+from app.camera import aim, snapshot
 from app.config import load_settings
 from app.db import get_receipt, list_line_items, list_receipts, open_db
 from app.pipeline import process_file
@@ -21,6 +21,8 @@ def _print_result(result: ProcessResult) -> None:
 
 def cmd_scan(args: argparse.Namespace) -> int:
     settings = load_settings()
+    if getattr(args, "aim_down", False) and not args.image:
+        aim(settings, "down")
     if args.image:
         image = Path(args.image)
     else:
@@ -93,6 +95,7 @@ def build_parser() -> argparse.ArgumentParser:
     scan = sub.add_parser("scan", help="process one image (Lamp camera if omitted)")
     scan.add_argument("--image", help="path to jpeg/png/pdf; omit to snapshot Lamp camera")
     scan.add_argument("--inbox", action="store_true", help="copy into inbox/ first")
+    scan.add_argument("--aim-down", action="store_true", help="HAL servo down before snapshot")
     scan.set_defaults(func=cmd_scan)
 
     query = sub.add_parser("query", help="list stored receipts")

app/config.py

@@ -62,6 +62,14 @@ class Settings(BaseSettings):
     llm_accepts_images: bool = True
     llm_max_tokens: int = 8192
     llm_timeout_s: float = 180.0
+    # auto: Studio API if up, else vLLM, else Hermes custom_providers.
+    # direct: RECEIPT_LLM_BASE_URL. hermes: Hermes-discovered Gemma. studio: POST /api/inbox.
+    llm_route: str = "auto"
+    studio_url: str = ""
+    gpu_host: str = ""
+    hermes_base_url: str = ""
+    hermes_model: str = "google/gemma-4-12B-it"
+    hermes_config_path: Path = Path.home() / ".hermes" / "config.yaml"
 
     embed_backend: str = "omni"
     embed_base_url: str = ""

app/route.py

@@ -0,0 +1,211 @@
+"""Resolve Gemma 4 12B Unified: direct vLLM, Hermes custom_providers, or Studio API."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+from urllib.parse import urlparse
+
+import httpx
+
+from app.config import Settings
+
+GEMMA_MODEL_MARKERS = ("gemma-4-12b", "gemma4-12b", "gemma-4-12B", "12b-it", "12B-it")
+
+
+@dataclass(frozen=True)
+class Brain:
+    kind: str  # direct | hermes | studio
+    base_url: str
+    model: str
+    source: str
+
+
+def _norm(url: str) -> str:
+    url = url.strip().rstrip("/")
+    if url and not url.endswith("/v1") and "/v1" not in urlparse(url).path:
+        url = url + "/v1"
+    return url
+
+
+def looks_like_gemma(name: str) -> bool:
+    lower = name.lower()
+    return any(m.lower() in lower for m in GEMMA_MODEL_MARKERS) or "gemma" in lower
+
+
+def parse_hermes_providers(text: str) -> list[Brain]:
+    """Pull OpenAI-compat custom_providers from a Hermes config.yaml."""
+    found: list[Brain] = []
+    block = text.split("custom_providers:", 1)
+    if len(block) < 2:
+        return found
+    body = block[1]
+    chunks = re.split(r"\n  - name:", body)
+    for chunk in chunks[1:]:
+        name_m = re.match(r"\s*([^\n]+)", chunk)
+        url_m = re.search(r"base_url:\s*(\S+)", chunk)
+        if not url_m:
+            continue
+        name = (name_m.group(1).strip() if name_m else "")
+        base = url_m.group(1).strip().strip("\"'")
+        models = re.findall(r"\n      - (\S+)", chunk)
+        if looks_like_gemma(name) or any(looks_like_gemma(m) for m in models):
+            model = next((m for m in models if looks_like_gemma(m)), models[0] if models else "google/gemma-4-12B-it")
+            found.append(
+                Brain(kind="hermes", base_url=_norm(base), model=model, source=f"hermes:{name}")
+            )
+    return found
+
+
+def brains_from_hermes_file(path: Path) -> list[Brain]:
+    if not path.is_file():
+        return []
+    try:
+        return parse_hermes_providers(path.read_text(encoding="utf-8"))
+    except OSError:
+        return []
+
+
+def probe_models(base_url: str, *, timeout_s: float = 1.5, client: httpx.Client | None = None) -> list[str]:
+    url = _norm(base_url)
+    own = client is None
+    http = client or httpx.Client(timeout=timeout_s)
+    try:
+        response = http.get(f"{url}/models")
+        if response.status_code >= 500:
+            return []
+        payload = response.json()
+        rows = payload.get("data", payload if isinstance(payload, list) else [])
+        ids: list[str] = []
+        for row in rows:
+            if isinstance(row, dict) and row.get("id"):
+                ids.append(str(row["id"]))
+            elif isinstance(row, str):
+                ids.append(row)
+        return ids
+    except (httpx.HTTPError, ValueError, TypeError):
+        return []
+    finally:
+        if own:
+            http.close()
+
+
+def probe_studio(studio_url: str, *, timeout_s: float = 1.5, client: httpx.Client | None = None) -> bool:
+    url = studio_url.rstrip("/")
+    own = client is None
+    http = client or httpx.Client(timeout=timeout_s)
+    try:
+        try:
+            response = http.get(f"{url}/api/health")
+            if response.status_code < 500:
+                return True
+        except httpx.HTTPError:
+            pass
+        try:
+            response = http.get(f"{url}/phone")
+            return response.status_code < 500
+        except httpx.HTTPError:
+            return False
+    finally:
+        if own:
+            http.close()
+
+
+ProbeFn = Callable[[str], list[str]]
+StudioProbeFn = Callable[[str], bool]
+
+
+def candidate_brains(settings: Settings) -> list[Brain]:
+    out: list[Brain] = []
+    seen: set[str] = set()
+
+    def add(brain: Brain) -> None:
+        key = f"{brain.kind}|{brain.base_url}|{brain.model}"
+        if key not in seen:
+            seen.add(key)
+            out.append(brain)
+
+    model = settings.llm_model
+    add(Brain("direct", _norm(settings.llm_base_url), model, "RECEIPT_LLM_BASE_URL"))
+    if settings.hermes_base_url:
+        add(Brain("hermes", _norm(settings.hermes_base_url), settings.hermes_model or model, "RECEIPT_HERMES_BASE_URL"))
+    for brain in brains_from_hermes_file(settings.hermes_config_path):
+        add(brain)
+    add(Brain("direct", "http://127.0.0.1:8080/v1", model, "localhost:8080"))
+    host = (settings.gpu_host or "").strip()
+    if host:
+        add(Brain("direct", _norm(f"http://{host}:8080/v1"), model, f"RECEIPT_GPU_HOST:{host}"))
+    return out
+
+
+def resolve_brain(
+    settings: Settings,
+    *,
+    probe: ProbeFn | None = None,
+    studio_probe: StudioProbeFn | None = None,
+) -> Brain:
+    """Pick Gemma 4 12B: studio (Lamp) vs direct vLLM vs Hermes-discovered provider."""
+    route = settings.llm_route.lower().strip()
+    model = settings.llm_model
+
+    if route == "studio":
+        url = (settings.studio_url or "").rstrip("/")
+        if not url:
+            raise RuntimeError("RECEIPT_LLM_ROUTE=studio requires RECEIPT_STUDIO_URL")
+        return Brain("studio", url, model, "RECEIPT_STUDIO_URL")
+
+    if route == "direct":
+        return Brain("direct", _norm(settings.llm_base_url), model, "RECEIPT_LLM_BASE_URL")
+
+    if route == "hermes":
+        hermes = [
+            b
+            for b in candidate_brains(settings)
+            if b.kind == "hermes" or b.source.startswith("hermes") or b.source == "RECEIPT_HERMES_BASE_URL"
+        ]
+        if settings.hermes_base_url:
+            hermes.insert(
+                0,
+                Brain("hermes", _norm(settings.hermes_base_url), settings.hermes_model or model, "RECEIPT_HERMES_BASE_URL"),
+            )
+        if not hermes:
+            hermes = brains_from_hermes_file(settings.hermes_config_path)
+        if not hermes:
+            raise RuntimeError(
+                "no Hermes Gemma 4 12B provider — run scripts/register-hermes-gemma.py "
+                "or set RECEIPT_HERMES_BASE_URL"
+            )
+        check = probe or probe_models
+        for brain in hermes:
+            ids = check(brain.base_url)
+            if ids is None:
+                continue
+            if not ids or any(looks_like_gemma(i) for i in ids) or brain.model in ids:
+                return brain
+        return hermes[0]
+
+    # auto
+    studio = (settings.studio_url or "").rstrip("/")
+    if studio:
+        ok = (studio_probe or (lambda u: probe_studio(u)))(studio)
+        if ok:
+            return Brain("studio", studio, model, "RECEIPT_STUDIO_URL")
+
+    check = probe or probe_models
+    for brain in candidate_brains(settings):
+        ids = check(brain.base_url)
+        if not ids:
+            continue
+        if any(looks_like_gemma(i) for i in ids) or brain.model in ids or brain.kind == "hermes":
+            if brain.model not in ids and ids:
+                gemma_id = next((i for i in ids if looks_like_gemma(i)), ids[0])
+                return Brain(brain.kind, brain.base_url, gemma_id, brain.source)
+            return brain
+        # OpenAI-compat that lists nothing useful but is up: keep configured model
+        if brain.source == "RECEIPT_LLM_BASE_URL":
+            return brain
+
+    # Prefer configured URL even if the probe failed (server may be starting).
+    return Brain("direct", _norm(settings.llm_base_url), model, "RECEIPT_LLM_BASE_URL")

app/ui.py

@@ -76,7 +76,7 @@ function add(cls, msg) {
   out.prepend(d);
 }
 async function waitDone(jobId) {
-  add('ok', 'Uploaded. Reading the receipt on the Spark…');
+  add('ok', 'Uploaded. Reading the receipt on the GPU box…');
   const deadline = Date.now() + 180000;
   while (Date.now() < deadline) {
     await new Promise(r => setTimeout(r, 2000));
@@ -240,6 +240,24 @@ def build_app(settings: Settings) -> FastAPI:
             }
         )
 
+    @api.get("/api/health")
+    async def api_health() -> JSONResponse:
+        from app.route import resolve_brain
+
+        try:
+            brain = resolve_brain(settings)
+            payload = {
+                "ok": True,
+                "route": settings.llm_route,
+                "kind": brain.kind,
+                "base_url": brain.base_url,
+                "model": brain.model,
+                "source": brain.source,
+            }
+        except Exception as exc:
+            payload = {"ok": False, "error": str(exc), "route": settings.llm_route}
+        return JSONResponse(payload)
+
     @api.get("/api/jobs/{job_id}")
     async def job_status(job_id: str) -> JSONResponse:
         with _JOBS_LOCK:

backends/__init__.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from app.config import Settings
+from app.route import resolve_brain
 from backends.apple import AppleEmbed, AppleLLM, AppleOCR
 from backends.base import EmbedBackend, LLMBackend, OCRBackend
 from backends.cpu import CpuOCR
@@ -18,9 +19,35 @@ __all__ = [
 ]
 
 
+def _with_brain(settings: Settings) -> Settings:
+    """Point llm/embed URLs at the resolved Gemma 4 12B (direct vLLM or Hermes)."""
+    route = settings.llm_route.lower().strip()
+    backend = settings.llm_backend.lower().strip()
+    if route == "studio":
+        return settings
+    if backend in {"ollama", "lightning", "apple"}:
+        return settings
+    try:
+        brain = resolve_brain(settings)
+    except RuntimeError:
+        return settings
+    if brain.kind == "studio":
+        return settings
+    updates: dict[str, object] = {}
+    if brain.base_url and brain.base_url != settings.llm_base_url:
+        updates["llm_base_url"] = brain.base_url
+        updates["embed_base_url"] = brain.base_url
+    if brain.model and brain.model != settings.llm_model:
+        updates["llm_model"] = brain.model
+        if settings.embed_backend.lower() in {"omni", "gemma", "gemma4"}:
+            updates["embed_model"] = brain.model
+    return settings.model_copy(update=updates) if updates else settings
+
+
 def build_llm(settings: Settings, *, client=None) -> LLMBackend:
+    settings = _with_brain(settings)
     name = settings.llm_backend.lower().strip()
-    if name in {"gemma", "gemma4", "unified"}:
+    if name in {"gemma", "gemma4", "unified", "hermes", "auto"}:
         return GemmaLLM(settings, client=client)
     if name in {"nvidia", "vllm", "qwen", "qwen38"}:
         return NvidiaLLM(settings, client=client)
@@ -32,6 +59,7 @@ def build_llm(settings: Settings, *, client=None) -> LLMBackend:
 
 
 def build_embed(settings: Settings, *, client=None) -> EmbedBackend:
+    settings = _with_brain(settings)
     name = settings.embed_backend.lower().strip()
     if name in {"omni", "gemma", "gemma4"}:
         return GemmaEmbed(settings, client=client)

docs/promo/Keys-Auto-Receipts-Studio-promo.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b2da8185b2ffeeca42e946b1c9a76d4fabeb68b4b2d656b809d7e6fc8f900f83
+size 19601635

oneshot.sh

@@ -35,14 +35,22 @@ fi
 .venv/bin/pip install -q -e ".[dev]"
 [[ -f .env ]] || cp .env.example .env
 
+HAVE_VLLM=0
+if curl -sf -m3 "http://127.0.0.1:$PORT_LLM/v1/models" >/dev/null 2>&1; then
+  HAVE_VLLM=1
+elif command -v vllm >/dev/null 2>&1; then
+  HAVE_VLLM=1
+fi
+
 say "2/5 Gemma 4 12B-it weights → $MODEL_DIR"
-if [[ -f "$MODEL_DIR/config.json" ]] && ls "$MODEL_DIR"/*.safetensors >/dev/null 2>&1; then
+if [[ "$HAVE_VLLM" != 1 ]]; then
+  echo "  skip (no vllm on PATH and nothing on :$PORT_LLM) — UI-only. Point .env at a GPU box."
+elif [[ -f "$MODEL_DIR/config.json" ]] && ls "$MODEL_DIR"/*.safetensors >/dev/null 2>&1; then
   echo "  present"
 else
-  command -v hf >/dev/null || .venv/bin/pip install -q huggingface_hub
+  .venv/bin/pip install -q huggingface_hub
   mkdir -p "$MODEL_DIR"
-  hf download "$MODEL_ID" --local-dir "$MODEL_DIR" \
-    || python3 - "$MODEL_ID" "$MODEL_DIR" <<'PY' || die "weight download failed (hf auth login)"
+  .venv/bin/python - "$MODEL_ID" "$MODEL_DIR" <<'PY' || die "weight download failed (run: .venv/bin/hf auth login)"
 import sys
 from huggingface_hub import snapshot_download
 snapshot_download(sys.argv[1], local_dir=sys.argv[2])
@@ -53,33 +61,45 @@ fi
 say "3/5 vLLM Gemma (util=$UTIL FP8, :$PORT_LLM)"
 if curl -sf -m3 "http://127.0.0.1:$PORT_LLM/v1/models" >/dev/null 2>&1; then
   echo "  already serving"
-else
-  command -v vllm >/dev/null || die "vllm not on PATH (pip install vllm, or use this Spark's install)"
+elif command -v vllm >/dev/null 2>&1 && [[ -f "$MODEL_DIR/config.json" ]]; then
   mkdir -p data
   nohup bash "$ROOT/scripts/serve-gemma.sh" >> data/vllm-gemma.log 2>&1 &
   echo "  pid $!  log data/vllm-gemma.log"
+else
+  echo "  skip — no local vLLM/Gemma. Set RECEIPT_LLM_BASE_URL in .env to the GPU box."
 fi
 
 say "4/5 wait until Gemma answers /v1/models (first boot compiles kernels)"
-ok=0
-for i in $(seq 1 120); do
-  if curl -sf -m3 "http://127.0.0.1:$PORT_LLM/v1/models" >/dev/null 2>&1; then
-    echo "  healthy ($i)"
-    ok=1
-    break
-  fi
-  sleep 5
-done
-[[ "$ok" = 1 ]] || die "vLLM not healthy — tail data/vllm-gemma.log"
+if curl -sf -m3 "http://127.0.0.1:$PORT_LLM/v1/models" >/dev/null 2>&1; then
+  echo "  already healthy"
+elif command -v vllm >/dev/null 2>&1 && [[ -f "$MODEL_DIR/config.json" ]]; then
+  ok=0
+  for i in $(seq 1 120); do
+    if curl -sf -m3 "http://127.0.0.1:$PORT_LLM/v1/models" >/dev/null 2>&1; then
+      echo "  healthy ($i)"
+      ok=1
+      break
+    fi
+    sleep 5
+  done
+  [[ "$ok" = 1 ]] || die "vLLM not healthy — tail data/vllm-gemma.log"
+else
+  echo "  skip wait (no local Gemma). UI will still start."
+fi
 
 say "5/5 UI on LAN :$PORT_UI"
+mkdir -p data
 export RECEIPT_UI_SHARE_LAN=true
-export RECEIPT_LLM_BASE_URL="http://127.0.0.1:${PORT_LLM}/v1"
-export RECEIPT_EMBED_BASE_URL="http://127.0.0.1:${PORT_LLM}/v1"
-export RECEIPT_LLM_MODEL="$MODEL_ID"
-export RECEIPT_EMBED_MODEL="$MODEL_ID"
-export RECEIPT_EMBED_DIM=3840
-export RECEIPT_EMBED_BACKEND=omni
+# Only pin LLM URLs to this machine when local Gemma is actually up.
+# UI-only boxes must keep .env pointing at the GPU box.
+if curl -sf -m3 "http://127.0.0.1:$PORT_LLM/v1/models" >/dev/null 2>&1; then
+  export RECEIPT_LLM_BASE_URL="http://127.0.0.1:${PORT_LLM}/v1"
+  export RECEIPT_EMBED_BASE_URL="http://127.0.0.1:${PORT_LLM}/v1"
+  export RECEIPT_LLM_MODEL="$MODEL_ID"
+  export RECEIPT_EMBED_MODEL="$MODEL_ID"
+  export RECEIPT_EMBED_DIM=3840
+  export RECEIPT_EMBED_BACKEND=omni
+fi
 if curl -sf -m2 "http://127.0.0.1:$PORT_UI/phone" >/dev/null 2>&1; then
   echo "  UI already up"
 else
@@ -106,7 +126,12 @@ PY
 printf '\n\033[1;32m✅ READY\033[0m  keys-Auto Receipts Studio\n'
 printf '   Review (this machine):  http://127.0.0.1:%s\n' "$PORT_UI"
 printf '   iPhone Safari:          http://%s:%s/phone\n' "$LAN" "$PORT_UI"
-printf '   Gemma /v1:              http://127.0.0.1:%s/v1  model %s  util=%s\n' "$PORT_LLM" "$MODEL_ID" "$UTIL"
+if curl -sf -m2 "http://127.0.0.1:$PORT_LLM/v1/models" >/dev/null 2>&1; then
+  printf '   Gemma /v1:              http://127.0.0.1:%s/v1  model %s  util=%s\n' "$PORT_LLM" "$MODEL_ID" "$UTIL"
+else
+  printf '   Gemma /v1:              not local — set RECEIPT_LLM_BASE_URL in .env to the GPU box\n'
+fi
 printf '   Desktop launcher:       bash scripts/install-launcher.sh\n'
-printf '\n   Hold a receipt up → Take photo on the phone page.\n'
-printf '   Lamp skill (optional):  skills/keys-receipt-scanner/  — 12B does not fit in 6GB RAM.\n'
+printf '   Windows desktop icon:   scripts\\install-launcher.bat\n'
+printf '\n   Hold a receipt up → Take photo on the phone page (Safari).\n'
+printf '   Lamp skill:             skills/keys-receipt-scanner/  — 12B does not fit in 6GB RAM.\n'

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "keys-automatic-receipt-doc-scanner"
 version = "1.0.0a1"
-description = "Lamp camera + Qwen3.8 vision extract + sqlite-vec receipt/doc scanner"
+description = "iPhone + desktop receipt scanner; Gemma 4 12B-it on a GPU box; optional Autonomous Lamp skill"
 readme = "README.md"
 requires-python = ">=3.12"
 license = { text = "Apache-2.0" }

scripts/install-launcher.bat

@@ -0,0 +1,14 @@
+@echo off
+REM Writes a Desktop shortcut that cds to this repo, then starts the UI.
+setlocal
+set "HERE=%~dp0"
+cd /d "%HERE%.."
+set "ROOT=%CD%"
+set "DEST=%USERPROFILE%\Desktop\Receipt Studio.bat"
+> "%DEST%" (
+  echo @echo off
+  echo cd /d "%ROOT%"
+  echo call "%ROOT%\scripts\start-ui.bat"
+)
+echo Wrote %DEST%
+echo Double-click Desktop\Receipt Studio.bat

scripts/install-launcher.sh

@@ -6,7 +6,12 @@ chmod +x "$ROOT/scripts/start-ui.sh" "$ROOT/scripts/start-ui.command"
 
 if [[ "$(uname -s)" == "Darwin" ]]; then
   DEST="$HOME/Desktop/Receipt Studio.command"
-  ln -sf "$ROOT/scripts/start-ui.command" "$DEST"
+  # Write a wrapper (not a symlink): Desktop double-click must not depend on $0.
+  cat > "$DEST" <<EOF
+#!/bin/bash
+cd "$ROOT"
+exec "$ROOT/scripts/start-ui.sh"
+EOF
   chmod +x "$DEST"
   echo "Mac: double-click Desktop/Receipt Studio.command (first time: right-click → Open)"
   exit 0

scripts/register-hermes-gemma.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Idempotently add Gemma 4 12B Unified to ~/.hermes/config.yaml custom_providers."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+SNIPPET = """
+  - name: gemma4-12b-it
+    base_url: {base_url}
+    api_key: EMPTY
+    models:
+      - google/gemma-4-12B-it
+"""
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", default=str(Path.home() / ".hermes" / "config.yaml"))
+    parser.add_argument("--base-url", default="http://127.0.0.1:8080/v1")
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args()
+    path = Path(args.config)
+    text = path.read_text(encoding="utf-8") if path.is_file() else "custom_providers: []\n"
+    if "gemma4-12b-it" in text or "google/gemma-4-12B-it" in text:
+        print(f"already registered in {path}")
+        return 0
+    block = SNIPPET.format(base_url=args.base_url.rstrip("/"))
+    if "custom_providers:" in text:
+        text = text.replace("custom_providers:\n", "custom_providers:\n" + block, 1)
+    else:
+        text = text.rstrip() + "\ncustom_providers:\n" + block
+    if args.dry_run:
+        print(block)
+        return 0
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    print(f"added gemma4-12b-it -> {args.base_url} in {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/start-ui.bat

@@ -1,6 +1,17 @@
 @echo off
-REM Windows: double-click this file.
-cd /d "%~dp0\.."
+REM Windows: double-click in the repo (scripts\) or run oneshot.bat at the repo root.
+setlocal
+set "HERE=%~dp0"
+if exist "%HERE%app\cli.py" (
+  cd /d "%HERE%"
+) else if exist "%HERE%..\app\cli.py" (
+  cd /d "%HERE%.."
+) else (
+  echo Run this from the cloned repo: scripts\start-ui.bat
+  echo Do not copy this file to the Desktop — use scripts\install-launcher.bat
+  pause
+  exit /b 1
+)
 if not exist ".venv\Scripts\python.exe" (
   echo Creating .venv (one time)...
   py -3.12 -m venv .venv || python -m venv .venv

scripts/start-ui.command

@@ -1,4 +1,11 @@
 #!/bin/bash
 # macOS: double-click this file (first time: right-click → Open).
-cd "$(dirname "$0")"
-exec ./start-ui.sh
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]:-$0}"
+while [[ -L "$SOURCE" ]]; do
+  DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+exec "$DIR/start-ui.sh"

scripts/start-ui.sh

@@ -1,7 +1,13 @@
 #!/usr/bin/env bash
 # Linux / macOS: double-click start-ui.command on Mac, or run this script.
 set -euo pipefail
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SOURCE="${BASH_SOURCE[0]:-$0}"
+while [[ -L "$SOURCE" ]]; do
+  DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [[ "$SOURCE" != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+ROOT="$(cd "$(dirname "$SOURCE")/.." && pwd)"
 cd "$ROOT"
 if [[ ! -x .venv/bin/python ]]; then
   echo "Creating .venv (one time)…"

skills/keys-receipt-scanner/SKILL.md

@@ -5,78 +5,66 @@ description: Scan receipts and paper documents with the Lamp camera, extract tot
 
 # keys-receipt-scanner
 
-Built-in Autonomous OS skill. The **Lamp camera** is the eye. The **GPU box** runs Gemma 4 12B Unified (omni vision + embed). Do **not** load 12B weights on the robot — Lamp has 6 GB RAM.
+This folder is the Autonomous OS skill. In this repo: `skills/keys-receipt-scanner/`. After `make push-skill` it is `/root/.openclaw/workspace/skills/keys-receipt-scanner/` (or `~/.openclaw/workspace/skills/keys-receipt-scanner/` if the robot user is not root).
+
+Lamp = camera only (6 GB). Gemma 4 12B Unified stays on the GPU box. Route via Receipt Studio (`RECEIPT_STUDIO_URL`) or direct/Hermes OpenAI-compat (`RECEIPT_LLM_BASE_URL` / Hermes `custom_providers`).
 
 ## When to use
 
-- User holds up a receipt, invoice, statement, or letter
-- "Scan this", "log this expense", "what did this cost", "save this document"
-- Phone/Syncthing drop is handled by the same `scan` CLI on the GPU box; on Lamp, still snapshot then scan
+User holds up a receipt/invoice/statement, or says scan this / log this expense / what did this cost.
+
+Do **not** use for "what do you see" about the room (`camera` skill) or privacy toggles.
 
-Do **not** use for "what do you see" about the room (that is `camera`) or privacy toggles (`camera` disable/enable).
+## Capture + extract
 
-## Capture (Lamp HAL)
+Reuse `[vision-image] <path>` if this turn already has one. Else run the skill script (stdlib, no 12B weights):
 
-Reuse `[vision-image] <path>` if this turn already has one. Otherwise:
+Desk ("it's on the table"):
 
 ```bash
-curl -s "http://127.0.0.1:5001/camera/snapshot?save=true&width=1280&quality=85"
+python skills/keys-receipt-scanner/scripts/scan.py --aim-down
 ```
 
-Read `path` from the JSON. Receipts need **1280** px, not 768 — small print.
-
-If they say it is on the desk: curl `POST http://127.0.0.1:5001/servo/aim` with `{"direction":"down"}` **before** snapshot (`[HW:…]` would move after the photo).
-
-Then:
+Held up to the camera:
 
-```
-[HW:/emotion:{"emotion":"curious","intensity":0.6}]
+```bash
+python skills/keys-receipt-scanner/scripts/scan.py
 ```
 
-## Extract + store
-
-From the skill checkout / install prefix (repo root on the GPU box, or `/opt/keys-receipt-scanner` on Lamp if you copied the package):
+Existing JPEG:
 
 ```bash
-python -m app.cli scan --image "$SNAP_PATH"
+python skills/keys-receipt-scanner/scripts/scan.py --image "$PATH"
 ```
 
-The CLI POSTs the JPEG to Gemma 4 12B Unified (`RECEIPT_LLM_BASE_URL`, default `http://127.0.0.1:8080/v1`) with `image_url`, categorizes, embeds on the same omni server (dim 3840), writes SQLite.
-
-On the Lamp, set `RECEIPT_LLM_BASE_URL` / `RECEIPT_EMBED_BASE_URL` to the GPU box (LAN). Never `api.x.ai`. Never Lightning with an image.
+If the workspace cwd is already the skill folder, `python scripts/scan.py` is the same.
 
-## Speak
-
-After JSON comes back, say in the user's language:
+The script snapshots HAL `GET :5001/camera/snapshot?save=true&width=1280&quality=85`, then POSTs the JPEG to Receipt Studio on the GPU box (`RECEIPT_STUDIO_URL`, default `http://$RECEIPT_GPU_HOST:7860/api/inbox`). Studio runs Gemma 4 12B (direct vLLM or Hermes-discovered). On a GPU-box checkout it falls back to `python -m app.cli scan`.
 
-- kind + category + vendor
-- date and total (with currency)
-- 1–2 notable line items
-- match band if SKU auto/review
+If they said it is on the desk, `--aim-down` must run **before** the photo.
 
 Then:
 
 ```
-[HW:/emotion:{"emotion":"acknowledge","intensity":0.7}]
+[HW:/emotion:{"emotion":"curious","intensity":0.6}]
 ```
 
-If `status` is `needs_extract` / `failed`, say you could not read it and ask them to hold it flatter / closer. Do not invent totals.
+## Speak
 
-## Query
+From the JSON, say in the user's language: kind + category + vendor, date and total, 1–2 line items. Do not invent totals. If `state` is `error` or `status` is `failed`, ask them to hold it flatter.
 
-```bash
-python -m app.cli query --category groceries --limit 10
-python -m app.cli show <id>
+```
+[HW:/emotion:{"emotion":"acknowledge","intensity":0.7}]
 ```
 
-## Privacy
+## Env on the Lamp
 
-Only snapshot when they asked to scan paper. Camera off stays a `camera` skill concern. `/camera/snapshot` auto-enables for the frame.
+```bash
+export RECEIPT_GPU_HOST=<spark-lan-ip>
+export RECEIPT_STUDIO_URL=http://<spark-lan-ip>:7860
+export RECEIPT_CAMERA_URL=http://127.0.0.1:5001
+```
 
-## Fit
+Direct Gemma (skip Studio): GPU box `RECEIPT_LLM_BASE_URL=http://127.0.0.1:8080/v1`. Via Hermes: `python scripts/register-hermes-gemma.py` on the GPU box, then `RECEIPT_LLM_ROUTE=auto` (reads `~/.hermes/config.yaml` `custom_providers`).
 
-| Piece | Runs on |
-|---|---|
-| This SKILL.md + snapshot curl | Lamp (Autonomous OS) |
-| `app.cli scan` HTTP client + SQLite | Lamp **or** GPU box |
-| Gemma 4 12B Unified weights | GPU box only |
+Never `api.x.ai`. Never Lightning with an image. Never load 12B on the Lamp.

skills/keys-receipt-scanner/references/hardware.md

@@ -1,7 +1,15 @@
 # Hardware split
 
-Lamp: 6 GB RAM. This skill + HAL snapshot only.
+Repo path: `skills/keys-receipt-scanner/`
+On Lamp after push: `/root/.openclaw/workspace/skills/keys-receipt-scanner/`
 
-Gemma 4 12B Unified (`hidden_size` 3840) and Qwen3.8-27B run on the GPU box.
+Lamp (6 GB): this skill + HAL snapshot only. Gemma 4 12B Unified stays on the GPU box.
 
 Camera: `GET http://127.0.0.1:5001/camera/snapshot?save=true&width=1280&quality=85`
+Desk aim: `POST http://127.0.0.1:5001/servo/aim` `{"direction":"down"}` before snapshot.
+
+Brain (pick one):
+
+- Studio (Lamp default): `RECEIPT_STUDIO_URL=http://<gpu>:7860` → POST `/api/inbox`
+- Direct vLLM: `RECEIPT_LLM_BASE_URL=http://<gpu>:8080/v1`
+- Hermes: `python scripts/register-hermes-gemma.py` then `RECEIPT_LLM_ROUTE=auto` reads `~/.hermes/config.yaml` `custom_providers`

skills/keys-receipt-scanner/scripts/scan.py

@@ -1,19 +1,206 @@
 #!/usr/bin/env python3
-"""Lamp/agent entry: python skills/keys-receipt-scanner/scripts/scan.py --image PATH"""
+"""Lamp entry. Snapshot HAL, then Gemma 4 12B on the GPU box (direct vLLM, Hermes, or Studio).
+
+Never loads 12B on the robot. Stdlib-only so it runs after `make push-skill`.
+"""
 
 from __future__ import annotations
 
+import argparse
+import json
+import os
 import sys
+import time
+import urllib.error
+import urllib.request
 from pathlib import Path
 
-ROOT = Path(__file__).resolve().parents[3]
-if str(ROOT) not in sys.path:
-    sys.path.insert(0, str(ROOT))
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+# Repo checkout: skills/keys-receipt-scanner/scripts/scan.py -> repo root
+REPO = Path(__file__).resolve().parents[3]
+
+
+def _env(name: str, default: str = "") -> str:
+    return os.environ.get(name, default).strip()
+
+
+def _json_req(url: str, *, data: bytes | None = None, headers: dict[str, str] | None = None, timeout: float = 30.0) -> dict:
+    req = urllib.request.Request(url, data=data, headers=headers or {})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read()
+    except urllib.error.HTTPError as exc:
+        detail = exc.read()[:400].decode("utf-8", "replace")
+        raise urllib.error.URLError(f"HTTP {exc.code} {url}: {detail}") from exc
+    if not raw:
+        return {}
+    return json.loads(raw.decode("utf-8"))
+
+
+def snapshot(camera_url: str, width: int = 1280, quality: int = 85) -> Path:
+    url = f"{camera_url.rstrip('/')}/camera/snapshot?save=true&width={width}&quality={quality}"
+    payload = _json_req(url, timeout=20.0)
+    path = payload.get("path")
+    if not path:
+        raise SystemExit(f"snapshot missing path: {payload!r}")
+    return Path(str(path))
+
+
+def aim_down(camera_url: str) -> None:
+    url = f"{camera_url.rstrip('/')}/servo/aim"
+    body = json.dumps({"direction": "down"}).encode()
+    try:
+        _json_req(url, data=body, headers={"Content-Type": "application/json"}, timeout=15.0)
+    except (urllib.error.URLError, json.JSONDecodeError, TimeoutError) as exc:
+        print(f"warn: servo aim failed ({exc})", file=sys.stderr)
+
+
+EXTRACT_USER = (
+    "Extract a receipt/invoice/document as one JSON object only. Keys: "
+    "doc_kind (receipt|invoice|document), category (groceries|dining|transport|"
+    "household|health|entertainment|utilities|office|travel|other), vendor, "
+    "date (YYYY-MM-DD), tax, total, currency, line_items "
+    "[{description, qty, unit_price, amount, sku}]. Unknown = null. No markdown."
+)
+
+
+def post_gemma(base_url: str, model: str, image: Path, api_key: str = "local") -> dict:
+    """Direct OpenAI-compat vision call (vLLM or Hermes custom_provider URL)."""
+    import base64
+
+    b64 = base64.b64encode(image.read_bytes()).decode("ascii")
+    root = base_url.rstrip("/")
+    if not root.endswith("/v1"):
+        root = root + "/v1"
+    payload = {
+        "model": model,
+        "messages": [
+            {
+                "role": "system",
+                "content": "You extract structured data from a receipt photo. JSON object only.",
+            },
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": f"data:image/jpeg;base64,{b64}"},
+                    },
+                    {"type": "text", "text": EXTRACT_USER},
+                ],
+            },
+        ],
+        "temperature": 0,
+        "max_tokens": 2048,
+        "response_format": {"type": "json_object"},
+    }
+    body = json.dumps(payload).encode()
+    result = _json_req(
+        f"{root}/chat/completions",
+        data=body,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+        timeout=180.0,
+    )
+    try:
+        content = result["choices"][0]["message"]["content"]
+        parsed = json.loads(content) if isinstance(content, str) else content
+    except (KeyError, IndexError, TypeError, json.JSONDecodeError) as exc:
+        raise SystemExit(f"Gemma response was not JSON: {result!r}") from exc
+    if not isinstance(parsed, dict):
+        raise SystemExit(f"Gemma JSON was not an object: {parsed!r}")
+    parsed.setdefault("state", "done")
+    parsed.setdefault("route", "direct")
+    return parsed
+
+
+def post_studio(studio_url: str, image: Path, timeout: float = 180.0) -> dict:
+    boundary = "----keysreceipt"
+    data = image.read_bytes()
+    filename = image.name or "snap.jpg"
+    parts = (
+        f"--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"{filename}\"\r\n"
+        f"Content-Type: image/jpeg\r\n\r\n"
+    ).encode() + data + f"\r\n--{boundary}--\r\n".encode()
+    inbox = _json_req(
+        f"{studio_url.rstrip('/')}/api/inbox",
+        data=parts,
+        headers={"Content-Type": f"multipart/form-data; boundary={boundary}"},
+        timeout=30.0,
+    )
+    job_id = inbox.get("job_id")
+    if not job_id:
+        return inbox
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        job = _json_req(f"{studio_url.rstrip('/')}/api/jobs/{job_id}", timeout=15.0)
+        if job.get("state") in {"done", "error"}:
+            return job
+        time.sleep(1.0)
+    raise SystemExit(f"studio job {job_id} timed out")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Lamp receipt scan → Gemma 4 12B on the GPU box")
+    parser.add_argument("--image", help="existing jpeg; omit to snapshot the Lamp camera")
+    parser.add_argument("--aim-down", action="store_true", help="aim servo down before snapshot (desk)")
+    parser.add_argument("--camera-url", default=_env("RECEIPT_CAMERA_URL", "http://127.0.0.1:5001"))
+    parser.add_argument("--studio-url", default=_env("RECEIPT_STUDIO_URL"))
+    parser.add_argument("--llm-url", default=_env("RECEIPT_LLM_BASE_URL", "http://127.0.0.1:8080/v1"))
+    parser.add_argument("--gpu-host", default=_env("RECEIPT_GPU_HOST"))
+    args = parser.parse_args(argv)
+
+    image = Path(args.image) if args.image else None
+    if image is None:
+        if args.aim_down:
+            aim_down(args.camera_url)
+        image = snapshot(args.camera_url)
+
+    studio = args.studio_url
+    if not studio and args.gpu_host:
+        studio = f"http://{args.gpu_host}:7860"
+
+    # 1) Receipt Studio on the GPU box (stores + Gemma extract + embed).
+    if studio:
+        try:
+            result = post_studio(studio, image)
+            json.dump(result, sys.stdout, indent=2)
+            sys.stdout.write("\n")
+            return 0 if result.get("state") != "error" else 1
+        except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+            print(f"studio route failed ({exc}); trying local package / direct Gemma", file=sys.stderr)
+
+    # 2) GPU-box git checkout: full pipeline (direct vLLM or Hermes-discovered Gemma).
+    if (REPO / "app" / "cli.py").is_file():
+        sys.path.insert(0, str(REPO))
+        from app.cli import main as cli_main
+
+        cli_main(["scan", "--image", str(image)])
+        return 0
+
+    # 3) Lamp without the app package: OpenAI-compat on the GPU box (vLLM or Hermes provider).
+    llm = args.llm_url
+    if args.gpu_host and ("127.0.0.1" in llm or "localhost" in llm):
+        llm = f"http://{args.gpu_host}:8080/v1"
+    hermes = _env("RECEIPT_HERMES_BASE_URL")
+    if hermes:
+        llm = hermes
+    model = _env("RECEIPT_LLM_MODEL") or _env("RECEIPT_HERMES_MODEL") or "google/gemma-4-12B-it"
+    try:
+        result = post_gemma(llm, model, image, api_key=_env("RECEIPT_LLM_API_KEY") or "local")
+        json.dump(result, sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        return 0
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+        raise SystemExit(
+            f"Gemma 4 12B unreachable at {llm} ({exc}). "
+            "On the Lamp set RECEIPT_STUDIO_URL=http://<gpu-box>:7860 "
+            "or RECEIPT_LLM_BASE_URL=http://<gpu-box>:8080/v1 "
+            "(Hermes: RECEIPT_HERMES_BASE_URL to the same OpenAI-compat URL)."
+        ) from exc
 
-from app.cli import main
 
 if __name__ == "__main__":
-    argv = sys.argv[1:]
-    if not argv or argv[0] not in {"scan", "query", "show", "snapshot", "ui"}:
-        argv = ["scan", *argv]
-    main(argv)
+    raise SystemExit(main())

tests/conftest.py

@@ -28,6 +28,7 @@ def settings(tmp_path: Path) -> Settings:
         exports_dir=tmp_path / "exports",
         idle_seconds=0.05,
         llm_backend="gemma",
+        llm_route="direct",
         llm_base_url="http://llm.test/v1",
         llm_model="google/gemma-4-12B-it",
         embed_backend="omni",

tests/test_camera.py

@@ -4,7 +4,7 @@ from pathlib import Path
 
 import httpx
 
-from app.camera import snapshot
+from app.camera import aim, snapshot
 from app.config import Settings
 
 
@@ -19,3 +19,17 @@ def test_snapshot_reads_path(settings: Settings, tmp_path: Path) -> None:
     client = httpx.Client(transport=httpx.MockTransport(handler), base_url="http://hal.test")
     settings = settings.model_copy(update={"camera_url": "http://hal.test"})
     assert snapshot(settings, client=client) == saved
+
+
+def test_aim_posts_direction(settings: Settings) -> None:
+    seen: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.append(request.method + " " + str(request.url))
+        assert b"down" in request.content
+        return httpx.Response(200, json={"ok": True})
+
+    client = httpx.Client(transport=httpx.MockTransport(handler), base_url="http://hal.test")
+    settings = settings.model_copy(update={"camera_url": "http://hal.test"})
+    aim(settings, "down", client=client)
+    assert any("servo/aim" in url for url in seen)

tests/test_route.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from app.config import Settings
+from app.route import (
+    Brain,
+    looks_like_gemma,
+    parse_hermes_providers,
+    resolve_brain,
+)
+
+HERMES = """
+custom_providers:
+  - name: qwen38-nvfp4
+    base_url: http://10.100.10.5:8078/v1
+    api_key: EMPTY
+    models:
+      - qwen38-nvfp4
+  - name: gemma4-12b-it
+    base_url: http://10.100.10.4:8080/v1
+    api_key: EMPTY
+    models:
+      - google/gemma-4-12B-it
+mcp_servers:
+  slate:
+    command: node
+"""
+
+
+def test_parse_hermes_finds_gemma_only() -> None:
+    brains = parse_hermes_providers(HERMES)
+    assert len(brains) == 1
+    assert brains[0].kind == "hermes"
+    assert brains[0].base_url == "http://10.100.10.4:8080/v1"
+    assert brains[0].model == "google/gemma-4-12B-it"
+    assert "gemma4-12b-it" in brains[0].source
+
+
+def test_looks_like_gemma() -> None:
+    assert looks_like_gemma("google/gemma-4-12B-it")
+    assert looks_like_gemma("gemma4-12b-it")
+    assert not looks_like_gemma("qwen38-nvfp4")
+
+
+def test_resolve_direct(settings: Settings) -> None:
+    settings = settings.model_copy(update={"llm_route": "direct"})
+    brain = resolve_brain(settings, probe=lambda _u: [])
+    assert brain.kind == "direct"
+    assert brain.base_url == "http://llm.test/v1"
+
+
+def test_resolve_hermes(settings: Settings, tmp_path: Path) -> None:
+    cfg = tmp_path / "config.yaml"
+    cfg.write_text(HERMES, encoding="utf-8")
+    settings = settings.model_copy(
+        update={"llm_route": "hermes", "hermes_config_path": cfg, "hermes_base_url": ""}
+    )
+    brain = resolve_brain(
+        settings,
+        probe=lambda url: ["google/gemma-4-12B-it"] if "8080" in url else [],
+    )
+    assert brain.kind == "hermes"
+    assert brain.base_url.endswith(":8080/v1")
+
+
+def test_parse_live_hermes_config_does_not_crash() -> None:
+    from app.route import brains_from_hermes_file
+
+    path = Path.home() / ".hermes" / "config.yaml"
+    brains = brains_from_hermes_file(path)
+    assert all(b.kind == "hermes" for b in brains)
+    for brain in brains:
+        assert "gemma" in brain.model.lower() or "gemma" in brain.source.lower()
+
+
+def test_resolve_auto_studio(settings: Settings) -> None:
+    settings = settings.model_copy(
+        update={"llm_route": "auto", "studio_url": "http://gpu.example:7860"}
+    )
+    brain = resolve_brain(
+        settings,
+        probe=lambda _u: [],
+        studio_probe=lambda _u: True,
+    )
+    assert brain == Brain("studio", "http://gpu.example:7860", settings.llm_model, "RECEIPT_STUDIO_URL")

tests/test_scan_script.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCAN_PATH = ROOT / "skills" / "keys-receipt-scanner" / "scripts" / "scan.py"
+
+
+def _load_scan():
+    spec = importlib.util.spec_from_file_location("lamp_scan", SCAN_PATH)
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def test_post_gemma_sends_image_url(tmp_path: Path, monkeypatch) -> None:
+    scan = _load_scan()
+    jpeg = tmp_path / "r.jpg"
+    jpeg.write_bytes(b"fake-jpeg")
+    captured: dict = {}
+
+    def fake_json_req(url, *, data=None, headers=None, timeout=30.0):
+        captured["url"] = url
+        captured["body"] = json.loads(data.decode())
+        captured["headers"] = headers
+        return {
+            "choices": [
+                {
+                    "message": {
+                        "content": json.dumps(
+                            {"doc_kind": "receipt", "vendor": "Cafe", "total": 3.5}
+                        )
+                    }
+                }
+            ]
+        }
+
+    monkeypatch.setattr(scan, "_json_req", fake_json_req)
+    out = scan.post_gemma("http://gpu:8080/v1", "google/gemma-4-12B-it", jpeg)
+    assert out["vendor"] == "Cafe"
+    assert captured["url"].endswith("/v1/chat/completions")
+    content = captured["body"]["messages"][1]["content"]
+    kinds = {p["type"] for p in content}
+    assert "image_url" in kinds
+    url = next(p["image_url"]["url"] for p in content if p["type"] == "image_url")
+    assert url.startswith("data:image/jpeg;base64,")
+
+
+def test_post_studio_polls_job(tmp_path: Path, monkeypatch) -> None:
+    scan = _load_scan()
+    jpeg = tmp_path / "r.jpg"
+    jpeg.write_bytes(b"fake-jpeg")
+    calls: list[str] = []
+
+    def fake_json_req(url, *, data=None, headers=None, timeout=30.0):
+        calls.append(url)
+        if url.endswith("/api/inbox"):
+            return {"ok": True, "job_id": "abc"}
+        if url.endswith("/api/jobs/abc"):
+            return {"state": "done", "vendor": "Whole Foods", "total": "12.00"}
+        raise AssertionError(url)
+
+    monkeypatch.setattr(scan, "_json_req", fake_json_req)
+    out = scan.post_studio("http://gpu:7860", jpeg)
+    assert out["vendor"] == "Whole Foods"
+    assert any(u.endswith("/api/inbox") for u in calls)
+    assert any("/api/jobs/abc" in u for u in calls)

tests/test_skill_frontmatter.py

@@ -15,6 +15,10 @@ def test_skill_frontmatter() -> None:
     assert "name: keys-receipt-scanner" in fm
     assert "Lamp camera" in fm or "scan" in fm.lower()
     body = parts[2]
+    assert "skills/keys-receipt-scanner" in body
+    assert "scripts/scan.py" in body
     assert "/camera/snapshot" in body
     assert "6 GB" in body
     assert "Gemma 4 12B" in body
+    assert "RECEIPT_STUDIO_URL" in body
+    assert "RECEIPT_GPU_HOST" in body

tests/test_ui_edit.py

@@ -47,3 +47,6 @@ def test_phone_page_splits_camera_and_library() -> None:
     assert "opacity:0" in PHONE_HTML
     assert "/api/jobs/" in PHONE_HTML
     assert "Completed:" in PHONE_HTML
+    assert "/api/inbox" in PHONE_HTML
+    assert "Safari" in PHONE_HTML
+    assert "heic" in PHONE_HTML.lower()