Upload README.md with huggingface_hub

README.md

@@ -18,6 +18,26 @@ iPhone (or desktop) photo → local **Gemma 4 12B-it** vision extract → SQLite
 GitHub: [`drowzeys/keys-Auto-Receipts-Studio`](https://github.com/drowzeys/keys-Auto-Receipts-Studio)  
 Hugging Face: [`drowzeys/keys-Auto-Receipts-Studio`](https://huggingface.co/drowzeys/keys-Auto-Receipts-Studio)
 
+## Pathways (pick a recipe)
+
+Gemma 4 12B-it **never** runs on the Lamp (6 GB) and typically **not** on a Windows/Mac laptop. The GPU box is the brain. PC / Mac / Linux run the inbox + Review UI. iPhone is a Safari capture client on the same Wi‑Fi.
+
+| Pathway | One-shot recipe | Gemma 4 12B | iPhone page |
+|---|---|---|---|
+| **A. Linux NVIDIA GPU box** (Spark / Omen) | `bash oneshot.sh` | started here (`:8080`, util **0.15**, FP8, never above **0.85**) | `http://<this-box-lan-ip>:7860/phone` |
+| **B. Linux, no NVIDIA** | `bash oneshot.sh` then edit `.env` | skip local vLLM; point `.env` at pathway A | same, this machine’s LAN IP |
+| **C. Windows PC** | `oneshot.bat` then `scripts\install-launcher.bat` | on pathway A (or WSL2) | `http://<this-pc-lan-ip>:7860/phone` |
+| **D. macOS** | venv + `bash scripts/install-launcher.sh` | on pathway A | `http://<this-mac-lan-ip>:7860/phone` |
+| **E. iPhone** | Safari only, after A/B/C/D UI is up | n/a (uploads to the UI box) | `/phone` — **Take photo** or **Choose file** |
+| **F. Autonomous Lamp** | `skills/keys-receipt-scanner/` | on pathway A | n/a (HAL camera → Studio `/api/inbox`) |
+
+```bash
+git clone https://github.com/drowzeys/keys-Auto-Receipts-Studio.git
+cd keys-Auto-Receipts-Studio
+```
+
+Desktop icon after first UI start: Linux/macOS `bash scripts/install-launcher.sh` · Windows `scripts\install-launcher.bat`. Step-by-step for each letter is [below](#a-linux-nvidia-gpu-box-gemma--ui--iphone).
+
 ## Screenshots (v1.0 alpha)
 
 iPhone Safari — take a photo, then completion notice:
@@ -40,34 +60,57 @@ Inbox drop zone, catalog SKUs, and backend health:
 <img src="docs/screenshots/04-settings.png" alt="Settings backends" width="420"/>
 </p>
 
-## One-shot (Linux GPU box — NVIDIA + vLLM)
+## Promo (v1.0 alpha)
 
-This is the Spark/Omen path. It installs the app, fetches **google/gemma-4-12B-it** if missing, starts vLLM at **`--gpu-memory-utilization 0.15`** (FP8, max-model-len 8192, never above 0.85), and opens the UI.
+[~50s story cut](docs/promo/Keys-Auto-Receipts-Studio-promo.mp4) — messy dorm → iPhone (lay the receipt flat, then photograph) → charcoal Autonomous Lamp scans the last receipt → trash → clean room. Bed: Beethoven Symphony No. 5, I. Allegro con brio (public-domain recording).
+
+Also attached on the [v1.0-alpha-promo release](https://github.com/drowzeys/keys-Auto-Receipts-Studio/releases/tag/v1.0-alpha-promo) (plays in the browser).
+
+## Pathway details
+
+One-click / `app.launch` binds the UI on the LAN (`RECEIPT_UI_SHARE_LAN=true`) and opens Review in the browser. Phone URL is printed in the terminal.
+
+Desktop icons (do **not** copy `scripts/start-ui.bat` itself to the Desktop):
+
+| OS | Command | Opens |
+|---|---|---|
+| Linux | `bash scripts/install-launcher.sh` | Desktop **Receipt Studio.desktop** |
+| macOS | `bash scripts/install-launcher.sh` | Desktop **Receipt Studio.command** (first time: right-click → **Open**) |
+| Windows | `scripts\install-launcher.bat` | Desktop **Receipt Studio.bat** |
+
+### A. Linux NVIDIA GPU box (Gemma + UI + iPhone)
 
 ```bash
-git clone https://github.com/drowzeys/keys-Auto-Receipts-Studio.git
-cd keys-Auto-Receipts-Studio
 bash oneshot.sh
 ```
 
+Idempotent. Installs `.venv`, fetches **google/gemma-4-12B-it** to `~/models-gemma4-12b-it` if missing (`hf auth login` once), starts `scripts/serve-gemma.sh` if `:8080` is down, starts the UI on **0.0.0.0:7860**.
+
 When it prints READY:
 
 | | |
 |---|---|
 | Review | http://127.0.0.1:7860 |
-| iPhone (same Wi‑Fi, **Safari**) | http://&lt;this-pc-lan-ip&gt;:7860/phone |
+| iPhone Safari (same Wi‑Fi) | http://&lt;this-box-lan-ip&gt;:7860/phone |
+| Gemma OpenAI-compat | http://127.0.0.1:8080/v1 |
 
-`hf auth login` once if the Gemma weights are not already at `~/models-gemma4-12b-it`.
+vLLM flags (also used by `scripts/start-ui.sh` on a CUDA box if Gemma is down):
 
-Desktop icon after that: `bash scripts/install-launcher.sh`
+- `--gpu-memory-utilization **0.15**` (~18.3 GiB of 121.7 GiB; **never above 0.85**)
+- **FP8** (BF16 weights ~23 GB cannot fit in that pool)
+- `--max-model-len **8192**`
 
-## Windows (PC)
+If Gemma is already running, oneshot / launch leave it alone. To apply the 0.15 cap: stop that `vllm` process, then `bash oneshot.sh` again.
 
-12B does **not** run on a typical Windows GPU from this script. Run Gemma on a Linux NVIDIA box (`oneshot.sh` there), then this PC is the UI + iPhone hotspot.
+Gemma-only (UI already running): `bash scripts/serve-gemma.sh`
 
-1. Install [Python 3.12](https://www.python.org/downloads/) — check **Add python.exe to PATH**.
-2. Double-click `oneshot.bat` (or `scripts\start-ui.bat`).
-3. Edit `.env`:
+### B. Linux without NVIDIA (UI + iPhone only)
+
+```bash
+bash oneshot.sh
+```
+
+If `vllm` is not on PATH and nothing answers on `:8080`, oneshot **skips** weights and vLLM (it does **not** die) and still starts the UI. Then set `.env` at the GPU box from pathway A:
 
 ```
 RECEIPT_LLM_BASE_URL=http://<spark-lan-ip>:8080/v1
@@ -77,171 +120,126 @@ RECEIPT_EMBED_MODEL=google/gemma-4-12B-it
 RECEIPT_EMBED_DIM=3840
 ```
 
-4. Phone: `http://<this-windows-lan-ip>:7860/phone`
+Restart the UI (`./scripts/start-ui.sh` or the desktop icon).
 
-If this PC **is** an NVIDIA box with `vllm` on PATH, set the same `.env` to `127.0.0.1:8080` and run `bash scripts/serve-gemma.sh` from Git Bash, or install WSL2 and use the Linux one-shot.
+### C. Windows PC (UI + iPhone hotspot)
 
-## macOS
+12B is **not** started by the Windows scripts. Serve Gemma on pathway A (or WSL2 + `bash oneshot.sh`).
 
-Same split: Gemma on the Linux GPU box; Mac is UI + iPhone.
+1. Install [Python 3.12](https://www.python.org/downloads/) — check **Add python.exe to PATH**.
+2. In the cloned repo, double-click **`oneshot.bat`** (creates `.venv`, opens Review).
+3. Edit `.env` as in pathway B (Spark LAN IP, port **8080**).
+4. Optional desktop icon: `scripts\install-launcher.bat` → **Desktop\Receipt Studio.bat**.
+5. iPhone: `http://<this-windows-lan-ip>:7860/phone` in **Safari**.
+
+Do not copy `scripts\start-ui.bat` to the Desktop; it must run from the repo (or from the wrapper `install-launcher.bat` writes).
+
+If this PC **is** NVIDIA + `vllm` on PATH (Git Bash / WSL): point `.env` at `127.0.0.1:8080` and `bash scripts/serve-gemma.sh`.
+
+### D. macOS (UI + iPhone)
+
+Apple Silicon does not load 12B with this vLLM-NVIDIA recipe. Use pathway A for Gemma.
 
 ```bash
-git clone https://github.com/drowzeys/keys-Auto-Receipts-Studio.git
-cd keys-Auto-Receipts-Studio
 python3 -m venv .venv
 .venv/bin/pip install -e ".[dev]"
 cp .env.example .env
-# point RECEIPT_LLM_BASE_URL at the Spark, then:
+# edit RECEIPT_LLM_BASE_URL / RECEIPT_EMBED_BASE_URL like pathway B
 bash scripts/install-launcher.sh
 ```
 
-Double-click **Desktop → Receipt Studio.command** (first time: right-click → **Open**).
+Double-click **Desktop → Receipt Studio.command** (first time: right-click → **Open**). Same as `./scripts/start-ui.sh`.
 
-Apple Silicon will not load 12B next to this app as vLLM-NVIDIA. Use the Spark.
+### E. iPhone (Safari)
 
-## Linux without NVIDIA
+Works against **whichever machine runs the UI** (A, B, C, or D), same Wi‑Fi. Chrome/Firefox on iOS are not the supported path.
 
-Same as Mac: `bash oneshot.sh` will install the UI and skip/fail vLLM if `vllm` is missing. Point `.env` at a machine that already serves Gemma.
+1. Open `http://<ui-machine-lan-ip>:7860/phone`
+2. **Take photo** (camera) or **Choose file** (Photos / Files, including HEIC)
+3. Wait for **Completed: vendor · total · category · #id**
+4. Confirm / edit / delete on the desktop **Review** tab
 
----
+The phone page POSTs `/api/inbox` and polls `/api/jobs/{id}`. The GPU box (or the UI machine talking to Gemma) does extract + embed. Inbox drop and Syncthing into `inbox/` use the same pipeline (files idle 30s unless the phone API processes immediately).
 
-Built-in **Autonomous OS** skill for **Autonomous Lamp**: hold up a receipt; Lamp snapshots; the GPU box runs Gemma 4 12B-it. Also a Mac / Windows / Linux inbox (phone upload + Gradio).
+### F. Autonomous Lamp skill
 
-## Does Gemma 4 12B Unified fit on the Lamp?
-
-**No.** Lamp is 8-core ARM64 with **6 GB RAM**. Gemma 4 12B Unified is a 12B dense omni model (`Gemma4UnifiedForConditionalGeneration`, hidden size **3840**). Weights alone will not boot beside Autonomous OS + HAL.
-
-| Piece | Fits on Lamp? | Fits on GPU box? |
-|---|---|---|
-| `skills/keys-receipt-scanner/` (this skill) | yes — built-in skill format | yes |
-| HAL `GET /camera/snapshot` | yes | n/a |
-| SQLite + sqlite-vec + HTTP client | yes | yes |
-| **Gemma 4 12B Unified weights** | **no** | yes (vLLM, util **0.15**) |
-| Qwen3.8-27B ADay777 VLM | no | yes |
-| Nemotron-3-Embed-1B | no | yes |
-
-The skill is **built-in to Autonomous OS** (markdown + `skill.json` `capabilities: ["vision"]`). The brain is remote. Intern has no camera, so this skill will not install there.
-
-## Built-in skill (Lamp)
+Repo path: **`skills/keys-receipt-scanner/`** (`SKILL.md`, `skill.json` `capabilities: ["vision"]`, `scripts/scan.py`).
 
 ```
 skills/keys-receipt-scanner/
-  SKILL.md          # agent instructions + HAL camera contract
-  skill.json        # {"capabilities": ["vision"]}
+  SKILL.md
+  skill.json
   scripts/scan.py
+  references/hardware.md
 ```
 
-Install onto a robot (no reboot):
+Install (no reboot):
 
 ```bash
 make push-skill SKILL=./skills/keys-receipt-scanner TARGET=pi@lamp-xxxx.local
 ```
 
-On the Lamp, point the brain at the GPU box:
+On the Lamp (camera only — **do not** load 12B):
 
 ```bash
-export RECEIPT_LLM_BASE_URL=http://<spark-or-omen>:8080/v1
-export RECEIPT_EMBED_BASE_URL=http://<spark-or-omen>:8080/v1
-export RECEIPT_LLM_MODEL=google/gemma-4-12B-it
-export RECEIPT_EMBED_MODEL=google/gemma-4-12B-it
-export RECEIPT_EMBED_DIM=3840
-export RECEIPT_EMBED_BACKEND=omni
+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
 ```
 
-Say **“scan this receipt”** while holding paper to the camera.
+Say **“scan this receipt”**. `scripts/scan.py` snapshots HAL (`:5001/camera/snapshot`, 1280 px), then POSTs to Receipt Studio `/api/inbox` on the GPU box. Fallback: `RECEIPT_LLM_BASE_URL=http://<spark-lan-ip>:8080/v1` (direct vLLM) or `RECEIPT_HERMES_BASE_URL` (same OpenAI-compat URL Hermes registered). On the GPU box, `python scripts/register-hermes-gemma.py` adds `custom_providers` `gemma4-12b-it`.
 
-To ship it in a fork of [autonomous-os](https://github.com/autonomous-ai/autonomous-os): copy `skills/keys-receipt-scanner/` into `skills/`, run their `python skills/skill-creator/scripts/quick_validate.py`, `make skills-catalog`, open the PR.
+Intern has no camera; this skill will not install there.
 
-## GPU box — Gemma 4 12B Unified (omni)
+To ship in a fork of [autonomous-os](https://github.com/autonomous-ai/autonomous-os): copy `skills/keys-receipt-scanner/` into `skills/`, run `python skills/skill-creator/scripts/quick_validate.py`, `make skills-catalog`, open the PR.
 
-One server for vision extract **and** embeddings. Do not raise util above **0.85**.
-
-```bash
-bash scripts/serve-gemma.sh
-# util 0.15, FP8, max-model-len 8192  (or: bash oneshot.sh)
-```
-
-If `/v1/embeddings` 404s on a generate-only runner, either:
-
-- serve a pooling convert on another port and set `RECEIPT_EMBED_BASE_URL`, or
-- set `RECEIPT_EMBED_BACKEND=nvidia`, `RECEIPT_EMBED_DIM=2048`, and run Nemotron-3-Embed-1B. **Never mix 3840 and 2048 in one DB.**
-
-### Fallback: Qwen3.8-27B ADay777 (vision only)
-
-```bash
-export RECEIPT_LLM_BACKEND=nvidia
-export RECEIPT_LLM_BASE_URL=http://127.0.0.1:8078/v1
-export RECEIPT_LLM_MODEL=qwen38-nvfp4
-# thinking off is sent automatically
-```
+---
 
-Lightning is **text-only**. This skill will not attach images to it.
+## Does Gemma 4 12B Unified fit on the Lamp?
 
-## One-click (Windows / macOS / Linux)
+**No.** Lamp is 8-core ARM64 with **6 GB RAM**. Gemma 4 12B Unified is a 12B dense omni model (`Gemma4UnifiedForConditionalGeneration`, hidden size **3840**).
 
-Does **not** start Gemma. Point `.env` at the GPU box, then double-click:
+| Piece | Lamp (6 GB) | GPU box |
+|---|---|---|
+| `skills/keys-receipt-scanner/` | yes | yes |
+| HAL snapshot | yes | n/a |
+| SQLite + HTTP client | yes | yes |
+| **Gemma 4 12B Unified weights** | **no** | yes (vLLM util **0.15**) |
 
-| OS | One-click |
-|---|---|
-| **Linux** | `bash scripts/install-launcher.sh` once → Desktop **Receipt Studio** |
-| **macOS** | `bash scripts/install-launcher.sh` once → Desktop **Receipt Studio.command** (first time: right-click → Open) |
-| **Windows** | Copy `scripts/start-ui.bat` to the Desktop (or double-click it in the repo). First run creates `.venv`. |
+## Gemma 4 12B Unified (omni) on the GPU box
 
-Same entry from a terminal:
+One OpenAI-compat server: vision `POST /v1/chat/completions` **and** `POST /v1/embeddings` (dim **3840**). Do not raise util above **0.85**.
 
 ```bash
-# Linux / macOS
-./scripts/start-ui.sh
-
-# Windows
-scripts\start-ui.bat
+bash scripts/serve-gemma.sh
+# util 0.15, FP8, max-model-len 8192
 ```
 
-That starts the UI on the LAN if needed and opens **Review** in the browser. Phone page: `http://<this-machine-lan-ip>:7860/phone`.
-
-On a **CUDA box** (this Spark), the same click also starts Gemma 4 12B if `:8080` is down:
-
-- `--gpu-memory-utilization **0.15**` (~18.3 GiB of 121.7 GiB; never above **0.85**)
-- **FP8** — BF16 weights are ~23GB and cannot fit in that pool
-- `--max-model-len **8192**` (receipt photo is ~280 vision tokens + JSON)
-
-Context at util 0.15 (after ~12.5GB FP8 weights):
+Context at util 0.15 (after ~12.5 GB FP8 weights):
 
 | Estimate | Tokens |
 |---|---|
-| Conservative (all 48 layers full attn) | **~12k** |
+| Conservative (48 layers full attn) | **~12k** |
 | Hybrid (8 full + 40× sliding-1024) | **~65k** |
 | Model native window | 262,144 (not at 0.15) |
 
-A receipt scan uses ~1–2k tokens. Raise `RECEIPT_VLLM_MAX_MODEL_LEN` only after a boot log shows `GPU KV cache size` large enough.
-
-If Gemma is already running, the launcher leaves it alone. To apply the 15GB cap, stop the current `vllm` process, then click again.
+A receipt scan uses ~1–2k tokens. Raise `RECEIPT_VLLM_MAX_MODEL_LEN` only after the boot log shows a large enough `GPU KV cache size`.
 
-```bash
-# apply 15GB cap (stops the current unconstrained serve)
-pkill -x vllm   # only if you intend to restart it
-./scripts/start-ui.sh
-```
+If `/v1/embeddings` 404s, either serve a pooling convert on another port (`RECEIPT_EMBED_BASE_URL`) or `RECEIPT_EMBED_BACKEND=nvidia` + Nemotron-3-Embed-1B at dim **2048**. **Never mix 3840 and 2048 in one DB.**
 
-On a Mac/Windows laptop with no GPU, set in `.env`:
-
-```
-RECEIPT_LLM_BASE_URL=http://<spark-lan-ip>:8080/v1
-RECEIPT_EMBED_BASE_URL=http://<spark-lan-ip>:8080/v1
-```
+Fallback vision (not omni embed): Qwen3.8-27B ADay777 at `:8078` (`RECEIPT_LLM_BACKEND=nvidia`, `RECEIPT_LLM_MODEL=qwen38-nvfp4`). Lightning is **text-only** — never send images.
 
-## Desktop / phone (same pipeline)
+## Manual UI (any OS, after venv)
 
 ```bash
-python -m venv .venv && source .venv/bin/activate
+python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -e ".[dev]"
 cp .env.example .env
-python -m app.cli ui
+# set RECEIPT_LLM_* like pathway B unless Gemma is local
+RECEIPT_UI_SHARE_LAN=true python -m app.cli ui
 ```
 
-- Inbox watcher: files idle **30s** in `inbox/` then process
-- Phone on LAN: `RECEIPT_UI_SHARE_LAN=true` → `http://<lan-ip>:7860/phone`
-- Syncthing: phone camera/share folder → `inbox/`
+CLI:
 
 ```bash
 python -m app.cli scan --image path/to/receipt.jpg
@@ -249,11 +247,13 @@ python -m app.cli query --category groceries
 pytest
 ```
 
+Syncthing: camera/share folder → `inbox/` (idle **30s** then process).
+
 ## What you still run yourself
 
-- Serve Gemma 4 12B Unified (or Qwen) on the GPU box
-- Pair Lamp on Wi-Fi via the Autonomous app
-- `make push-skill` (or Skill Store / PR) for the built-in skill
-- Optional: Syncthing on iOS/Android
+- Pathway A (or equivalent) so Gemma is reachable on the LAN
+- iPhone on the **same Wi‑Fi**, Safari
+- Lamp: pair in the Autonomous app, `make push-skill`, set `RECEIPT_STUDIO_URL`
+- Optional: Syncthing
 
 No model weights in this repo. No PyInstaller in this release.