Deploy clean Small Cuts fallback Space

.claude/launch.json

@@ -0,0 +1,16 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "small-cuts-mock",
+      "runtimeExecutable": "uv",
+      "runtimeArgs": ["run", "python", "app.py"],
+      "env": {
+        "SMALL_CUTS_BACKEND": "mock",
+        "SMALL_CUTS_TTS_BACKEND": "mock",
+        "GRADIO_SERVER_PORT": "7861"
+      },
+      "port": 7861
+    }
+  ]
+}

.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"7d2c60ca-a075-4ecc-b94d-738f0cf355cc","pid":9019,"procStart":"Sat Jun 13 22:58:53 2026","acquiredAt":1781392518293}

.claude/settings.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "defaultMode": "acceptEdits",
+    "allow": [
+      "Bash",
+      "Write",
+      "Edit",
+      "WebFetch"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash scripts/tailnet-connect.sh || true"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/deploy-space/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: deploy-space
+description: Deploy the Small Cuts app to the Hugging Face Space (build-small-hackathon/small-cuts) and smoke-test it. Use when shipping a new build to the Space.
+disable-model-invocation: true
+---
+
+# Deploy Small Cuts to the HF Space
+
+Ship the current build to `build-small-hackathon/small-cuts` and verify it. The Space is the judged
+artifact — never push red.
+
+## 1. Green gate first (must mirror CI)
+```bash
+uv run ruff check . && uv run ruff format --check . && uv run pytest
+```
+Stop if anything fails.
+
+## 2. Auth
+`hf auth whoami` must show a write-scoped login. If not, ask the user to run `! hf auth login`.
+(For exact `hf` CLI syntax, use the `huggingface-skills:hf-cli` skill.)
+
+## 3. Upload what the Space needs
+`app.py`, `src/` (including `src/small_cuts/seed_media/` — the seed clips are static files served via
+`gr.set_static_paths`), `requirements.txt`, and the Space `README.md` (its frontmatter carries the
+`track:` / `achievement:` / `sponsor:` tags). Either:
+```bash
+hf upload --repo-type space build-small-hackathon/small-cuts . . \
+  --include "app.py" --include "requirements.txt" --include "README.md" --include "src/**"
+```
+or push to the Space's git remote.
+
+## 4. Space variables (backends)
+```bash
+hf spaces variables build-small-hackathon/small-cuts        # list current
+# real models on the Space: SMALL_CUTS_BACKEND=transformers  SMALL_CUTS_TTS_BACKEND=kokoro
+```
+
+## 5. Smoke test (the fork-poison detector)
+After the Space restarts, run a `gradio_client` smoke: **narrate → TTS → narrate-again** — the third
+call is what catches kokoro fork-poisoning. Tail logs:
+```bash
+hf spaces logs build-small-hackathon/small-cuts --tail
+```
+
+## Reminders
+- ZeroGPU: `@spaces.GPU` marks must be on the handlers Gradio binds; no torch in the main process
+  (see `src/small_cuts/CLAUDE.md`).
+- Confirm `seed_media/*.mp4` actually shipped — the hero library is empty without them.

.gitattributes

@@ -33,3 +33,13 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/desk-laptop.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/desk-laptop.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/night-drive.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/night-drive.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/rayuela.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/rayuela.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/street-parked-car.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/street-parked-car.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/the-stumble.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/the-stumble.mp4 filter=lfs diff=lfs merge=lfs -text

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: ci
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  ci:
+    name: ci
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Tests
+        run: uv run pytest
+
+      - name: Secret scan (gitleaks)
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/eval-on-spark.yml

@@ -0,0 +1,64 @@
+name: eval-on-spark
+
+on:
+  workflow_dispatch:
+    inputs:
+      images_dir:
+        description: Directory of eval photos on the Spark
+        default: ~/eval-photos
+      models:
+        description: Space-separated model ids
+        default: "google/gemma-3-4b-it Qwen/Qwen2.5-VL-3B-Instruct"
+  # Cloud sessions can't dispatch workflows (403) but can push — pushing an
+  # eval/** branch runs the eval with the defaults below.
+  push:
+    branches: ["eval/**"]
+
+jobs:
+  eval:
+    runs-on: [self-hosted, spark]
+    timeout-minutes: 240
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: GPU + environment probe
+        run: |
+          uname -a
+          nvidia-smi || echo "WARN: nvidia-smi unavailable"
+
+      - name: Ensure uv
+        run: |
+          command -v uv >/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Install
+        run: uv sync --extra local
+
+      - name: Run eval (one process per model for crash isolation)
+        run: |
+          IMAGES_RAW="${{ inputs.images_dir || '~/eval-photos' }}"
+          IMAGES="${IMAGES_RAW/#\~/$HOME}"
+          MODELS="${{ inputs.models || 'google/gemma-3-4b-it Qwen/Qwen2.5-VL-3B-Instruct' }}"
+          ls -la "$IMAGES" || echo "Directory not found: $IMAGES"
+          rm -f eval-report.md
+          for M in $MODELS; do
+            SLUG="$(echo "$M" | tr '/' '_')"
+            echo "::group::eval $M"
+            # Each model runs in its own process: an OOM/segfault kills only
+            # this iteration, not the whole eval.
+            if uv run python -m small_cuts.eval --images "$IMAGES" \
+                 --models "$M" --out "eval-$SLUG.md"; then
+              cat "eval-$SLUG.md" >> eval-report.md
+            else
+              printf '\n## %s — CRASHED (non-Python failure, see logs)\n' "$M" >> eval-report.md
+            fi
+            echo "::endgroup::"
+          done
+          cat eval-report.md >> "$GITHUB_STEP_SUMMARY" 2>/dev/null || true
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: eval-report
+          path: eval-report.md

.github/workflows/fetch-eval-photos.yml

@@ -0,0 +1,33 @@
+name: fetch-eval-photos
+
+# Dispatch-only relay: uploads the Spark's eval photos as a short-lived
+# artifact so tailnet-less sessions (cloud, or local without SSH grants)
+# can score the eval report against the actual images.
+on:
+  workflow_dispatch:
+    inputs:
+      images_dir:
+        description: Directory of eval photos on the Spark
+        default: ~/eval-photos
+
+jobs:
+  upload:
+    runs-on: [self-hosted, spark]
+    timeout-minutes: 10
+    steps:
+      - name: Stage photos
+        env:
+          SRC_RAW: ${{ inputs.images_dir || '~/eval-photos' }}
+        run: |
+          SRC="${SRC_RAW/#\~/$HOME}"
+          rm -rf staged-photos && mkdir staged-photos
+          cp "$SRC"/* staged-photos/
+          ls -la staged-photos
+
+      - name: Upload photos artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: eval-photos
+          path: staged-photos/
+          if-no-files-found: error
+          retention-days: 1

.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+uv.lock
+
+# Models / large artifacts
+*.gguf
+models/
+flagged/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Env — never commit secrets
+.env
+.env.*
+.playwright-mcp/
+ui-proposal.jpeg
+aimode-content.yml

.hfignore

@@ -0,0 +1,13 @@
+.git/
+.venv/
+ios/
+docs/reviews/
+docs/superpowers/
+docs/submission-readiness-*.md
+docs/demo-readiness.md
+docs/submission-assets-2026-06-15.md
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.playwright-mcp/
+xcodebuild-*.log

CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md — Small Cuts (root, always-on)
+
+**Small Cuts** turns first-person moments into grounded, cinematic, *spoken* narration using only
+**small (≤32B) open models running off-grid**. Goal (single, dual-purpose): **win/place in the
+Build Small Hackathon AND/OR make this a portfolio-grade, door-opening applied-AI project.** It is
+the strategic successor to *Director's Cut*. Full essence, lineage, and the canonical architecture
+live in the **KB** — see Documentation map.
+
+> **Deadline: 2026-06-15 23:59 UTC.** Branch-of-record: `claude/adoring-clarke-49l3uk` → protected `main`.
+
+---
+
+## Documentation map (READ FIRST — anti-divergence policy)
+**One home per fact. Link, never copy.**
+- **Operational / as-built** (commands, env vars, conventions, contracts-as-enforced) → **these
+  CLAUDE.md files + `docs/`**, versioned with the code.
+- **Strategy, lineage, decisions, the architecture, coordination** → **the KB**
+  (`knowledge-base` MCP → `knowledge_read`/`knowledge_search`; notes under
+  `10-projects/small-cuts/`). The architecture's **single source of truth** is the interactive
+  artifact `10-projects/small-cuts/architecture/index.html`.
+- The **canonical command list lives once here** (below). Subproject CLAUDE.md files add only
+  module-local specifics and **reference** this — they never restate it. (We keep the shared list
+  in this always-loaded root rather than a separate `@import`-ed snippet so no extra repo file is
+  introduced; `@import` is the mechanism if a dedicated snippet file is added later.)
+- **Claude Code auto-memory is a third writer**: operational learnings may land there, but
+  **architecture/strategy stays in the KB**.
+- **Nested CLAUDE.md are lazy-loaded** (only when you open a file in that subdir):
+  `src/small_cuts/` (space) · `src/small_cuts/engine/` (inference) · `ios/SmallCuts/` (mobile) ·
+  `docs/contracts/` (contracts).
+
+## Repo map
+- `app.py` — HF Space entrypoint (Gradio, ZeroGPU). `requirements.txt` — Space runtime deps.
+- `src/small_cuts/` — Python product: `narrator.py` (VLM backends), `tts.py` (Kokoro), `styles.py`
+  (6 director styles + grounded prompt v3), `title_card.py`, `theme.py` (Off-Brand), `ui.py`,
+  `viewer.py` (streaming viewer; engine + upload modes), `frames.py` (PyAV), `eval.py`.
+- `src/small_cuts/engine/` — real-time home-node engine (FastAPI WS `/v1/session`, `library.py`
+  sqlite+media, SSE stream). Launch: `python -m small_cuts.engine`.
+- `ios/SmallCuts/` — Meta-glasses capture app (XcodeGen, DAT 0.7). See its `RUNBOOK.md`.
+- `docs/` — `contracts/` (v1.1.0 schemas), `product/architecture.md` (D1–D9 + the loop),
+  `architecture.md`, `product-strategy.md`, `hackathon-rules.md`, `eval/`, `progress.md`, `specs/`.
+- `tests/` — pytest incl. golden-sample contract tests. `kb/` — legacy mirror notes (canonical KB
+  is the `knowledge-base` MCP).
+
+## Canonical commands (author-once; subprojects reference these)
+```bash
+# install — CI-equivalent minimal:
+uv sync --extra dev
+# install — full local (engine + TTS + transformers):
+uv sync --extra dev --extra engine --extra tts --extra local
+
+# local gate — MUST mirror CI exactly (all three, in order):
+uv run ruff check . && uv run ruff format --check . && uv run pytest
+
+# run the Space/viewer locally (bare `uv run` prunes the tts extra — keep --no-sync):
+uv run --no-sync python app.py
+# serve on the tailnet:
+GRADIO_SERVER_NAME=0.0.0.0 GRADIO_SERVER_PORT=7861 uv run --no-sync python app.py   # http://mac-studio:7861
+
+# run the real-time engine (port 8077; needs `brew install llama.cpp` for llama-server):
+SMALL_CUTS_BACKEND=llama_cpp SMALL_CUTS_TTS_BACKEND=kokoro uv run python -m small_cuts.engine
+SMALL_CUTS_BACKEND=mock uv run python -m small_cuts.engine          # no-model smoke
+
+# iOS (see ios/SmallCuts/CLAUDE.md + RUNBOOK.md):
+DEVELOPER_DIR=/Volumes/mac-studio-ssd/Applications/Xcode.app/Contents/Developer xcodegen
+
+# branch-of-record sync AFTER every squash-merge into main:
+git fetch && git merge -s ours origin/main && git push
+gh pr merge --auto --squash
+```
+
+## Conventions
+- **Local gate must mirror CI**: `ruff check` **and** `ruff format --check` **and** `pytest`
+  (CI also runs gitleaks). Never trust a piped `gh pr checks --watch` exit code.
+- **Gradio 6**: `theme=` is a `launch()` kwarg, **not** `gr.Blocks()`.
+- **ruff isort gotcha**: not-yet-existing first-party modules classify as third-party (I001) in
+  pre-implementation test files — write imports in post-implementation order, ignore the early fail.
+- **Contracts** (`docs/contracts/`, v1.1.0) are the source of truth: bump schema + golden samples +
+  all consumers in **one** PR (lockstep minor); label `contract-change` ⇒ orchestrator review.
+- **No secrets, ever.** 1Password Connect (local dev) + HF Space secrets (deploy); gitleaks in CI.
+  Client-facing endpoints use **Tailnet MagicDNS HTTPS** (e.g. `https://mac-studio.tail48bab7.ts.net/…`),
+  never raw IPs.
+
+## Coordination (see KB `10-projects/small-cuts/coordination/`)
+- **Roles:** orchestrator = **Opus 4.8** (assumed the lead vacated by **Fable 5**, pending Carlos's
+  confirmation) · implementer = **Codex (GPT-5.x)** · reviewer = **GLM / opencode** · eval judge =
+  **agy (Gemini)** · optional independent check = **GPT-5.x red-teams the plan**. Keep orchestrator ≠
+  implementer (different model families).
+- **Peers:** codex, agy, agent, opencode, + Carlos.
+- **Surfaces:** GitHub Project board **#8**; epics **#36** team-space / **#37** team-mobile /
+  **#38** team-inference; labels `team-*` + `contract-change`.
+
+## Pointers
+- **KB tree** (via `knowledge-base` MCP, under `10-projects/small-cuts/`): `00-overview`,
+  `architecture/` (canonical + interactive `index.html`), `space/`, `mobile/`, `inference/`,
+  `contracts/`, `product/`, `coordination/`. Predecessor: `10-projects/directors-cut/`.
+- **Live device test:** `ios/SmallCuts/RUNBOOK.md`. **Hackathon rules:** `docs/hackathon-rules.md`.
+- **Live Space:** `build-small-hackathon/small-cuts`. **Model:** `Qwen/Qwen3-VL-8B-Instruct` (M1 pick).

README.md

@@ -1,13 +1,139 @@
 ---
-title: Small Cuts Live
-emoji: 🏢
-colorFrom: red
-colorTo: red
+title: Small Cuts
+emoji: 🎬
+colorFrom: indigo
+colorTo: purple
 sdk: gradio
 sdk_version: 6.18.0
-python_version: '3.13'
 app_file: app.py
-pinned: false
+pinned: true
+license: mit
+short_description: A deadpan narrator for your life, from small open models.
+tags:
+  - track:wood
+  - achievement:offgrid
+  - achievement:offbrand
+  - achievement:llama
+  - achievement:fieldnotes
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Small Cuts 🎬
+
+> *"And that was the moment Carlos realized the coffee had been decaf all along."*
+
+**Small Cuts** turns first-person moments into grounded, cinematic, **spoken** narration —
+an omniscient, slightly-too-honest narrator in the spirit of *The Invention of Lying* —
+using only **small (≤32B) open models**. No script, no cloud LLM: a small vision-language
+model watches your moment and a small TTS speaks the line, the way a film narrator would
+if your life were the film.
+
+There is exactly **one narrator** — a single deadpan, unnamed voice. No menus, no
+director to pick. You point at what's happening; it tells you what it means.
+
+This is the **challenger submission** for the
+[Build Small Hackathon](https://huggingface.co/build-small-hackathon)
+("Small Models, Big Adventures" — Gradio × Hugging Face, submissions close
+**June 15, 2026, 23:59 UTC**), the strategic successor to the original
+*Director's Cut* project.
+
+## The soul of it — the live loop
+
+Small Cuts was born wearing glasses. The intended experience is a **live loop**:
+
+```
+Ray-Ban Meta glasses  ──image frames──▶  home engine (small VLM + TTS)  ──▶  narration in your ear
+                                              │
+                                              └──── finished cuts ────▶  the Space (watch · library)
+```
+
+You walk through a moment; the narrator watches a selected first-person frame and speaks
+one grounded, deadpan line back in your ear while the moment is still *recent past*. The
+finished cut then lands in the Space as a short POV clip with synced captions, title, voice,
+and library thumbnail.
+
+**One pipeline, two surfaces:** the narration returns *in your ear* during capture, and lands
+in the **Space** below as a finished cut you can re-watch — with film-style subtitles that
+crawl in sync with the voice — and publish to a library.
+
+## What's in this Space
+
+The Space is the **view platform + library** half of the loop — a small streaming-channel UI:
+
+- **A live stage** with the current moment and **movie-style subtitles** (short
+  phrase-sized lines over a constant dark bar, advancing with the voice-over).
+- **Voice-over replay**, with a compact custom player whose video, sound, captions, and progress
+  share the same audio clock.
+- **A public library** of real Ray-Ban Meta glasses moments, generated through the same local
+  engine path so the channel is never empty. The source clips and mark points are curated; the
+  visible titles, narration, voice, thumbnails, and clips are produced by Small Cuts.
+- **"Try it"** — a tucked-away sandbox (open only on request) to narrate your *own* short video.
+
+## How it was built
+
+| Piece | Choice | Why |
+|---|---|---|
+| Narrator (VLM) | `Qwen/Qwen3-VL-8B-Instruct` | Strong grounded captioning at 8B — well under 32B |
+| Voice (TTS) | **Kokoro** (24 kHz) | Tiny, expressive, open; one signature deadpan delivery |
+| Space runtime | Gradio 6 on CPU, viewer-only for live demo | The judged canvas: public theater + library |
+| Local live engine | FastAPI WS home node, **llama.cpp** | The in-ear loop + demo video; no cloud LLM/TTS API |
+| Capture | iOS app for Ray-Ban Meta glasses (`ios/SmallCuts/`) | First-person moments, the way it's meant to be lived |
+
+Built by **Carlos Crespo Macaya** as architect and lead. Development was accelerated with an
+AI toolchain: Claude (Opus) for design critique, Codex (GPT-5.x) for paired implementation,
+GLM for review, and Gemini for eval, all directed by Carlos.
+
+## Hackathon compliance
+
+| Rule | How Small Cuts complies |
+|---|---|
+| Gradio app hosted as a Space under the org | The app **is** the product — this Space |
+| Every model < 32B | 8B VLM narrator + small Kokoro TTS, all open weights |
+| Demo video | Filmed POV with Ray-Ban Meta glasses → narrated by the app *(pending final link below)* |
+| Social post | Linked from this README *(pending final link below)* |
+| Track 2 — **Thousand Token Wood** (`track:wood`) | Whimsical, delightful, AI-load-bearing, original |
+| Off the Grid (`achievement:offgrid`) | Live inference/TTS runs on local hardware; public Space reads finished cuts only |
+| Llama (`achievement:llama`) | The live engine runs through `llama.cpp` |
+
+- 📹 **Demo video:** _TODO — add public link before submission_
+- 📣 **Social post:** _TODO — add link before submission_
+- 📝 **Field notes:** [hf.co/blog/macayaven/small-cuts-field-notes](https://huggingface.co/blog/macayaven/small-cuts-field-notes)
+
+**Bonus quests claimed:** Off-Brand (`offbrand`, custom cinematic frontend) · Off the Grid
+(`offgrid`, local small-model engine for the live loop) · Llama (`llama`, llama.cpp) · Field
+Notes (`fieldnotes`, the write-up above).
+
+## Quick start
+
+```bash
+# install (CI-equivalent minimal)
+uv sync --extra dev
+
+# run the Space/viewer locally with the deterministic mock backend (no model download)
+SMALL_CUTS_BACKEND=mock uv run --no-sync python app.py
+
+# run with the real local VLM (downloads weights)
+SMALL_CUTS_BACKEND=transformers uv run --no-sync python app.py
+
+# run the real-time engine (needs `brew install llama.cpp`)
+SMALL_CUTS_BACKEND=llama_cpp SMALL_CUTS_TTS_BACKEND=kokoro uv run python -m small_cuts.engine
+
+# the gate (mirrors CI exactly)
+uv run ruff check . && uv run ruff format --check . && uv run pytest
+```
+
+## Repository map
+
+- `app.py` — Hugging Face Space entrypoint (Gradio CPU viewer/library)
+- `src/small_cuts/` — the product: `viewer.py` (streaming viewer), `narrator.py` (VLM backends),
+  `tts.py` (Kokoro), `styles.py` (grounded prompt), `engine/` (real-time home node), `seed_media/`
+- `ios/SmallCuts/` — the Ray-Ban Meta glasses capture app
+- `docs/` — [hackathon rules](docs/hackathon-rules.md) · [architecture](docs/product/architecture.md) ·
+  [contracts](docs/contracts/) · [progress](docs/progress.md)
+- `CLAUDE.md` — operational conventions (the canonical command list lives here)
+
+## Engineering discipline
+
+- `main` is protected (PR-based workflow); CI runs ruff lint + format check, pytest, and a
+  gitleaks secret scan on every push/PR.
+- **No secrets in the repo, ever.** Secrets live in 1Password Connect (local dev) and HF Space
+  secrets (deployment). Client-facing endpoints use Tailnet MagicDNS HTTPS, never raw IPs.

app.py

@@ -0,0 +1,60 @@
+"""Hugging Face Space entrypoint for Small Cuts.
+
+Local dev keeps the lazy/mock defaults; on a Space this module wires the real
+backends eagerly so visitors never pay the model-load cost per click:
+
+- ``import spaces`` happens before anything touches torch (ZeroGPU hijack).
+- The narrator loads at module scope (ZeroGPU packs the weights at startup).
+- The narration hot path runs under ``@spaces.GPU``.
+- TTS runs inside @spaces.GPU workers too (kokoro's torch use poisons
+  worker forks if it ever runs in the main process).
+"""
+
+import os
+import sys
+import warnings
+from pathlib import Path
+
+from starlette.exceptions import StarletteDeprecationWarning
+
+ROOT = Path(__file__).resolve().parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+warnings.filterwarnings(
+    "ignore",
+    message=r".*HTTP_422_UNPROCESSABLE_ENTITY.*HTTP_422_UNPROCESSABLE_CONTENT.*",
+    category=StarletteDeprecationWarning,
+)
+
+ON_SPACE = bool(os.environ.get("SPACE_ID"))
+ENGINE_MODE = bool(os.environ.get("SMALL_CUTS_ENGINE_URL", "").strip())
+
+try:
+    import spaces  # noqa: F401  (must precede torch imports for ZeroGPU)
+except ImportError:  # local dev / CI: no ZeroGPU
+    spaces = None
+
+if ON_SPACE and not ENGINE_MODE:
+    os.environ.setdefault("SMALL_CUTS_BACKEND", "transformers")
+    os.environ.setdefault("SMALL_CUTS_TTS_BACKEND", "kokoro")
+
+from small_cuts import narrator  # noqa: E402
+from small_cuts.viewer import THEME, build_viewer_app  # noqa: E402
+
+# Eager load: download + pack weights at startup, not on the first click.
+# The @spaces.GPU mark lives on the viewer's go-live handler (via ui._gpu;
+# ZeroGPU's startup scan only finds GPU functions on what Gradio binds).
+if not ENGINE_MODE:
+    _backend = narrator.get_backend()
+    if spaces is not None and _backend.name == "transformers":
+        _backend._load()
+
+# In engine mode the Space is only a public reader for a private home-node engine, so it must not
+# warm local model weights or expose upload narration controls. No main-process TTS pre-warm:
+# kokoro's torch use must stay inside @spaces.GPU workers.
+demo = build_viewer_app()
+
+if __name__ == "__main__":
+    demo.launch(theme=THEME)

docs/architecture.md

@@ -0,0 +1,72 @@
+# Small Cuts — Architecture
+
+## Principle
+
+**The Space is the product.** Everything a judge touches runs inside the
+Hugging Face Space. All other machines (Mac Studio, DGX Spark, phones, glasses)
+are development, evaluation, and content-capture tools.
+
+```
+┌─────────────────────────── Hugging Face Space (judged artifact) ──────────────────────────┐
+│                                                                                           │
+│  Gradio UI (custom cinematic theme — "Off-Brand")                                         │
+│   │  image / clip frame / webcam            ┌──────────────────────────────┐              │
+│   ▼                                         │ styles.py                    │              │
+│  ui.py ──────► narrator.py ◄────────────────│ director presets +           │              │
+│                   │                         │ prompt builder               │              │
+│                   ▼                         └──────────────────────────────┘              │
+│            Backend (pluggable, env SMALL_CUTS_BACKEND)                                    │
+│              ├─ mock          deterministic, CI/tests, no weights                         │
+│              ├─ transformers  small VLM on ZeroGPU (e.g. SmolVLM2 / Qwen-VL ≤8B)          │
+│              └─ llama_cpp     GGUF via llama.cpp (CPU fallback + "Llama Champion")        │
+│                   │                                                                       │
+│                   ▼                                                                       │
+│            TTS (small, local — M2) ──► audio + title card ──► shareable output            │
+└───────────────────────────────────────────────────────────────────────────────────────────┘
+
+  Capture sources (feed the demo & the UI, never load-bearing):
+   • Ray-Ban Meta glasses → footage exported via phone → demo video + sample inputs
+   • iPhone 14 Pro / Redmi Note 14 Pro+ → mobile browser upload (Gradio is responsive)
+   • Webcam tab in the UI
+
+  Live Mode (confirmed direction; continuous mode is stretch M3.5):
+   • Audio out: phone browser plays the Space's TTS → Bluetooth → glasses speakers (free)
+   • Continuous: phone camera → Gradio streaming → scene-change gate → narrate → TTS stream
+   • Glasses-camera capture via Meta Wearables DAT: post-hackathon, unverified
+
+  Dev/eval machinery (not judged):
+   • Mac Studio M4 Max  → orchestration, dev, video editing
+   • DGX Spark 128GB    → candidate-model evaluation harness, optional LoRA fine-tune
+                          ("Well-Tuned" quest), batch frame preprocessing experiments
+   • 1Password Connect  → local dev secrets; HF Space secrets for deployment
+   • Tailnet            → access between Carlos's machines only
+```
+
+## Key decisions (and why)
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Demo surface | Gradio Space (only) | Hackathon hard rule; judges must run it |
+| Glasses role | Capture for demo video + sample content | Removes pairing fragility; preserves wow |
+| Most reliable capture path | Any phone browser → upload | No native app needed in 4 days |
+| Inference location | Inside the Space (ZeroGPU + CPU fallback) | "Off the Grid" quest; no cloud APIs |
+| DGX Spark role | Model eval + optional fine-tune | Can't serve judges; perfect for picking the best ≤8B narrator and for "Well-Tuned" |
+| Mac Studio role | Dev + demo video production | — |
+| Backend abstraction | `SMALL_CUTS_BACKEND` env, 3 implementations | CI runs without GPU; llama.cpp path is a quest multiplier; model swap is one env var |
+| Model candidates (M1 eval) | SmolVLM2-2.2B-Instruct · Qwen2.5-VL-3B/7B-Instruct · gemma-3-4b-it | All ≤8B, vision-capable, open weights; final pick by narration quality on a fixed eval set (unverified until run) |
+| TTS candidates (M2) | Kokoro-82M · other ≤1B open TTS | Tiny, fast, runs CPU-side |
+
+## Secrets
+
+No runtime secrets are required for the core app (local models only). HF token
+for deployment lives in 1Password Connect locally and in GitHub Actions / Space
+secrets remotely. `gitleaks` runs in CI on every push.
+
+## Verification commands
+
+```bash
+uv run pytest                          # unit tests (mock backend)
+uv run ruff check . && uv run ruff format --check .
+SMALL_CUTS_BACKEND=mock uv run python app.py        # UI smoke test
+SMALL_CUTS_BACKEND=transformers uv run python app.py  # real model (M1+)
+```

docs/contracts/CLAUDE.md

@@ -0,0 +1,25 @@
+# CLAUDE.md — `docs/contracts/` (inter-team contracts, v1.1.0)
+
+Module-local notes for the **contract schemas** — the *only* coupling between the space, mobile, and
+inference teams, and the **source of truth** for message shapes. Rationale + history are in the **KB**
+(`10-projects/small-cuts/contracts/` and `…/architecture/`).
+
+## The four message types
+- **MomentEnvelope** (mobile → engine) — `moment.schema.json`: frames (≤1024px) + gate + context.
+- **ControlFrame** (engine → mobile) — `control.schema.json`: `ack`
+  (`accepted|duplicate|rejected|dropped_coalesced`), `error` (stage/code/retryable), `status`
+  (busy/queue_depth).
+- **SceneAudio** (engine → mobile) — `scene-audio.schema.json`: audio + `play_by` freshness deadline.
+- **NarratedScene** (engine → viewer & library, SSE) — `narrated-scene.schema.json`: `seq` (resume),
+  `captured_at`, narration, media URLs, `visibility`.
+
+## Enforcement
+- Strict JSON Schema (`additionalProperties: false`) + **golden samples** in `tests/test_contracts.py`,
+  validated on every push (CI). Run locally: `uv run pytest tests/test_contracts.py`.
+
+## Change process (the one rule that matters)
+- Bump the schema `$id` (semver) **+** golden samples **+** ALL consumers (Python engine/viewer +
+  iOS `MomentBuilder`/`EngineSessionClient`) **in ONE PR**. Additive = **minor, lockstep**; breaking =
+  **major + migration note**.
+- Label the PR **`contract-change`** ⇒ **orchestrator review required**.
+- The ≤6 s streamed-audio stretch is a **future MAJOR** version (cross-team), not a v1 toggle.

docs/contracts/README.md

@@ -0,0 +1,84 @@
+# Inter-team contracts
+
+These schemas are the **only coupling** between the three teams
+([product architecture](../product/architecture.md)). Each team optimizes
+freely inside its boundary; the contracts keep the system aligned.
+Current contract set: **1.1.0** (post adversarial review — Codex + Gemini,
+2026-06-12).
+
+| Contract | Producer → Consumer | Schema |
+|---|---|---|
+| MomentEnvelope | Mobile → Engine | [moment.schema.json](moment.schema.json) |
+| ControlFrame (ack / error / status) | Engine → Mobile | [control.schema.json](control.schema.json) |
+| SceneAudio | Engine → Mobile | [scene-audio.schema.json](scene-audio.schema.json) |
+| NarratedScene | Engine → Viewer + Library | [narrated-scene.schema.json](narrated-scene.schema.json) |
+
+## Transport bindings
+
+### Mobile ↔ Engine — one WebSocket per wearing session (`ws://<engine>/v1/session`)
+
+- Client sends `MomentEnvelope` text frames. Engine answers **every**
+  envelope with a `ControlFrame{kind=ack}` whose `result` means *admission*:
+  `accepted` (in the pipeline), `duplicate` (idempotent resend ignored),
+  `rejected` (validation failure — never retry unchanged),
+  `dropped_coalesced` (replaced by a newer moment, D8).
+- Completion is signaled by `SceneAudio` (success) or
+  `ControlFrame{kind=error}` (stage, code, retryable) — the app is never
+  blind to downstream failures.
+- **Backpressure (D8):** engine emits `ControlFrame{kind=status}` with
+  `busy`/`queue_depth`; apps suppress the gate while `busy`. Engine policy:
+  queue depth ≤ 1, **coalesce-to-newest** (a queued, un-started moment is
+  replaced by a newer arrival and acked `dropped_coalesced` — narrating
+  stale moments is worse than skipping them).
+- **Reconnect & idempotency:** after reconnect the app may resend envelopes
+  that never received an ack; the engine dedupes on `moment_id`. Chronology
+  authority is `captured_at`, not arrival order; `prev_moment_id` and `seq`
+  are advisory.
+- **Playback (D9):** the app never overlaps clips; a clip whose `play_by`
+  passed before playback starts is dropped (engine default: `created_at`
+  + 60 s).
+
+### Engine → Viewer — SSE (`GET /v1/scenes/stream`)
+
+- Emits `NarratedScene` with the SSE `id:` field set to `seq`; clients
+  resume with `Last-Event-ID`. Pipeline failures appear as
+  `ControlFrame{kind=error}` events on the same stream so the timeline
+  stays honest.
+- Library reads: `GET /v1/scenes?session=…&visibility=…` (same schema,
+  ordered by `captured_at`).
+- **Visibility mutations** (the viewer's only write — metadata, never
+  media): `PATCH /v1/scenes/{scene_id}` body
+  `{"visibility": "private"|"shared"|"public"}`. Auth + `share_token`
+  enforcement specs land with the library milestone (#30); v1 engines are
+  single-user on the tailnet, and `owner`/`share_token` fields are already
+  reserved in the schema so sharing is additive.
+- Media URLs inside `NarratedScene.media` resolve against the engine origin.
+
+## Session context (D5)
+
+The engine owns session memory. Capture apps contribute only what is inside
+`MomentEnvelope.context` + the chronology chain (`captured_at`,
+`prev_moment_id`). The prompt builder may use: recent narrations for the
+session, time-of-day (via `tz_offset_min`), `location_label`, `user_hint`,
+gate trigger. Token budget for injected context: ≤ 400 tokens (inference
+team owns the selection policy — #20).
+
+## Enforcement
+
+1. **Schemas are the source of truth.** Implementation types are generated
+   from or validated against them — never hand-drifted.
+2. **Golden samples in CI.** Each producer keeps at least one golden sample
+   per message type; `tests/test_contracts.py` validates all samples
+   against these schemas on every push (jsonschema).
+3. **Versioning — strict + lockstep.** Schema version lives in the `$id`
+   path (`…/contracts/<semver>/…`). Schemas are strict
+   (`additionalProperties: false`) and live in ONE repo, so any field
+   change — additive included — is a **lockstep minor bump**: schemas,
+   golden samples, and all consumers update in the same `contract-change`
+   PR. Tolerant-reader semantics only become relevant if schemas are ever
+   vendored into separate repos; until then, drift fails CI loudly.
+   Breaking shape changes (removals, type changes, transport semantics)
+   are a major bump + migration note.
+4. **Change process.** Contract changes are PRs labeled `contract-change`,
+   reviewed by the orchestrator, announced in the KB
+   (`10-projects/small-cuts/`) before merge.

docs/contracts/control.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/macayaven/small-cuts/docs/contracts/1.1.0/control.schema.json",
+  "title": "ControlFrame",
+  "description": "Engine -> capture-app control messages on the session WebSocket: envelope acknowledgement, pipeline errors, and backpressure status (D8). Every MomentEnvelope receives exactly one ack; errors and status frames may arrive any time.",
+  "type": "object",
+  "required": ["contract_version", "kind"],
+  "additionalProperties": false,
+  "properties": {
+    "contract_version": { "type": "string", "pattern": "^1\\." },
+    "kind": { "enum": ["ack", "error", "status"] },
+    "moment_id": {
+      "type": ["string", "null"],
+      "description": "Set for ack and error; null for status frames."
+    },
+    "ack": {
+      "type": "object",
+      "description": "kind=ack: the envelope's fate at admission (NOT completion - completion is the SceneAudio/NarratedScene or an error frame).",
+      "additionalProperties": false,
+      "properties": {
+        "result": { "enum": ["accepted", "duplicate", "rejected", "dropped_coalesced"] },
+        "detail": { "type": "string", "maxLength": 200 }
+      }
+    },
+    "error": {
+      "type": "object",
+      "description": "kind=error: a pipeline failure for an accepted moment, so the app is never blind to downstream failures.",
+      "additionalProperties": false,
+      "properties": {
+        "stage": { "enum": ["validation", "narration", "tts", "storage"] },
+        "code": { "type": "string", "maxLength": 60 },
+        "message": { "type": "string", "maxLength": 300 },
+        "retryable": { "type": "boolean" }
+      }
+    },
+    "status": {
+      "type": "object",
+      "description": "kind=status: backpressure signal. Apps suppress the gate while busy=true (D8).",
+      "additionalProperties": false,
+      "properties": {
+        "busy": { "type": "boolean" },
+        "queue_depth": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

docs/contracts/moment.schema.json

@@ -0,0 +1,152 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/macayaven/small-cuts/docs/contracts/1.1.0/moment.schema.json",
+  "title": "MomentEnvelope",
+  "description": "One gated moment from a capture app to the narration engine (D1/D2). Sent as a WebSocket text frame (JSON); frame payloads are base64 JPEG.",
+  "type": "object",
+  "required": [
+    "contract_version",
+    "moment_id",
+    "session_id",
+    "captured_at",
+    "frames"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "pattern": "^1\\."
+    },
+    "moment_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "session_id": {
+      "type": "string",
+      "description": "One continuous wearing session (glasses on -> off)."
+    },
+    "captured_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "frames": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 24,
+      "description": "Selected narration frame first, followed by optional timestamped supplemental JPEG frames for a short just-happened POV clip. Longest decoded side must be <= 1024 px.",
+      "items": {
+        "type": "object",
+        "required": [
+          "jpeg_b64",
+          "width",
+          "height"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "jpeg_b64": {
+            "type": "string",
+            "contentEncoding": "base64"
+          },
+          "width": {
+            "type": "integer",
+            "maximum": 1024
+          },
+          "height": {
+            "type": "integer",
+            "maximum": 1024
+          },
+          "ts_offset_ms": {
+            "type": "integer",
+            "description": "Offset from captured_at for multi-frame moments."
+          }
+        }
+      }
+    },
+    "gate": {
+      "type": "object",
+      "description": "Why the gate fired - engine may use it for prompt salience; never required.",
+      "additionalProperties": false,
+      "properties": {
+        "scene_change_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "motion_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "trigger": {
+          "enum": [
+            "scene_change",
+            "interval",
+            "user",
+            "session_start"
+          ]
+        }
+      }
+    },
+    "context": {
+      "type": "object",
+      "description": "Capture-side context for the engine's session memory (D5).",
+      "additionalProperties": false,
+      "properties": {
+        "location_label": {
+          "type": "string",
+          "maxLength": 120
+        },
+        "user_hint": {
+          "type": "string",
+          "maxLength": 280
+        },
+        "style_key": {
+          "type": "string",
+          "description": "Director's cut requested for this session; engine default if absent."
+        },
+        "battery_pct": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "network": {
+          "enum": [
+            "wifi",
+            "cellular",
+            "tailnet"
+          ]
+        },
+        "tz_offset_min": {
+          "type": "integer",
+          "minimum": -840,
+          "maximum": 840
+        },
+        "orientation": {
+          "enum": [
+            "portrait",
+            "landscape",
+            "portrait_upside_down",
+            "landscape_flipped"
+          ]
+        }
+      }
+    },
+    "prev_moment_id": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Chain for the engine's chronology; null at session start."
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic per-session counter for diagnosis; ordering authority is captured_at (engine dedupes on moment_id - idempotent resends after reconnect are safe)."
+    },
+    "sent_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Upload instant, for capture->engine latency attribution."
+    }
+  }
+}

docs/contracts/narrated-scene.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/macayaven/small-cuts/docs/contracts/1.1.0/narrated-scene.schema.json",
+  "title": "NarratedScene",
+  "description": "One narrated scene, produced by the engine. The SAME object is the viewer's live SSE event (D7) and the library's stored entry (D6); media fields are engine-served URLs.",
+  "type": "object",
+  "required": [
+    "captured_at",
+    "contract_version",
+    "created_at",
+    "media",
+    "moment_id",
+    "narration",
+    "scene_id",
+    "seq",
+    "session_id",
+    "style_key",
+    "title",
+    "visibility"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "pattern": "^1\\."
+    },
+    "scene_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "moment_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "style_key": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string",
+      "maxLength": 80,
+      "description": "Model-generated short title for the slate/thumbnail text; engines may fall back to derive_title for legacy or malformed model output."
+    },
+    "narration": {
+      "type": "string",
+      "maxLength": 2000
+    },
+    "visibility": {
+      "enum": [
+        "private",
+        "shared",
+        "public"
+      ],
+      "default": "private"
+    },
+    "media": {
+      "type": "object",
+      "required": [
+        "frame_url"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "frame_url": {
+          "type": "string",
+          "format": "uri-reference"
+        },
+        "card_url": {
+          "type": "string",
+          "format": "uri-reference"
+        },
+        "audio_url": {
+          "type": "string",
+          "format": "uri-reference"
+        },
+        "clip_url": {
+          "type": "string",
+          "format": "uri-reference",
+          "description": "Short viewer clip for library revisit/share, either uploaded or assembled by the engine from timestamped capture frames."
+        }
+      }
+    },
+    "engine": {
+      "type": "object",
+      "description": "Provenance + latency breakdown (the inference team's scoreboard).",
+      "additionalProperties": false,
+      "properties": {
+        "narrator_model": {
+          "type": "string"
+        },
+        "narrator_backend": {
+          "enum": [
+            "llama_cpp",
+            "transformers",
+            "mock"
+          ]
+        },
+        "tts_model": {
+          "type": "string"
+        },
+        "latency_ms": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "queue": {
+              "type": "integer"
+            },
+            "narration": {
+              "type": "integer"
+            },
+            "tts": {
+              "type": "integer"
+            },
+            "total": {
+              "type": "integer"
+            }
+          }
+        }
+      }
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic engine event id - SSE id: field; clients resume with Last-Event-ID."
+    },
+    "captured_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "From the source MomentEnvelope - the library's chronology key (created_at is engine time)."
+    },
+    "owner": {
+      "type": "string",
+      "description": "Reserved for multi-user: identity that owns the scene. v1 single-user engines emit a constant."
+    },
+    "share_token": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Reserved: capability token for visibility=shared links. Enforcement spec lands with the library milestone."
+    }
+  }
+}

docs/contracts/scene-audio.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/macayaven/small-cuts/docs/contracts/1.1.0/scene-audio.schema.json",
+  "title": "SceneAudio",
+  "description": "Voice-over returned from the engine to the capture app for in-ear playback (D4). One complete clip per scene in 1.x; streamed delivery is a future MAJOR version with its own chunk semantics. Playback policy is D9: never overlap; drop if past play_by.",
+  "type": "object",
+  "required": [
+    "contract_version",
+    "scene_id",
+    "moment_id",
+    "created_at",
+    "play_by",
+    "format",
+    "audio_b64"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "contract_version": { "type": "string", "pattern": "^1\\." },
+    "scene_id": { "type": "string", "format": "uuid" },
+    "moment_id": { "type": "string", "format": "uuid" },
+    "created_at": { "type": "string", "format": "date-time" },
+    "play_by": {
+      "type": "string",
+      "format": "date-time",
+      "description": "Freshness deadline (D9): if playback has not started by this instant, the app drops the clip (engine default: created_at + 60s)."
+    },
+    "format": { "enum": ["wav_complete"] },
+    "audio_b64": { "type": "string", "contentEncoding": "base64" },
+    "sample_rate": { "type": "integer", "default": 24000 },
+    "narration": {
+      "type": "string",
+      "description": "The text being spoken - lets the app show captions without waiting for the viewer."
+    }
+  }
+}

docs/eval/prompt-ab-comparison.md

@@ -0,0 +1,35 @@
+# Prompt A/B: judged comparison of v1 (run-002) vs v2 (run-004)
+
+Judge: Codex (GPT-5 vision), scoring every narration against the actual photo,
+rubric S/G/V 1-5, pick rule S>=4 and G>=4. Same 10 photos, same judge, same
+model (gemma-3-4b-it) — only the system prompt differs between the two runs.
+
+## Result
+
+| Variant | n | mean S | mean G | mean V | S>=4 & G>=4 |
+|---|---|---|---|---|---|
+| gemma-3-4b-it @ v1 prompt (run-002, strict) | 30 | 3.37 | 2.57 | 2.53 | 2/30 |
+| gemma-3-4b-it @ v2 prompt (run-004, "find the story") | 30 | 2.60 | 1.90 | 2.53 | 0/30 |
+| Qwen2.5-VL-3B @ v2 prompt (run-004) | 30 | 2.73 | 2.70 | 2.50 | 4/30 |
+
+## Conclusions
+
+1. **v2 was a pure loss**: −0.77 S, −0.67 G, ±0.00 V for gemma. The style
+   examples already carry the voice; the extra "find the story / lead with the
+   human moment" license only licensed confabulation (invented rain, people,
+   actions). Reverted and hardened as v3 in `styles.py`.
+2. **Model size is the real ceiling**: even strict v1 passes only 2/30 cells.
+   Qwen2.5-VL-3B is the best so far (G 2.70). Qwen2.5-VL-7B is the most
+   important untested candidate (was blocked on torchvision, fixed in run-003).
+3. **Generation temperature was 0.7 with sampling in both runs** — a second
+   G-suppressor, lowered to 0.3 default (SMALL_CUTS_TEMPERATURE) for run-005.
+4. run-005 bundles prompt v3 + temp 0.3 + Qwen-7B. The v3-vs-v1 deltas are
+   confounded with the temperature change — accepted; both push G the same
+   way and the deadline is June 15.
+
+## Method note
+
+Scoring loop is fully automated: `fetch-eval-photos` workflow relays photos
+off the Spark → HEIC→JPEG → one `codex exec -i <photo>` call per image with
+the report's narrations → strict-JSON S/G/V → aggregate. Re-running a scoring
+pass on a new eval report costs ~7 minutes and zero manual effort.

docs/eval/run-002-gemma-baseline.md

@@ -0,0 +1,99 @@
+# Small Cuts — M1 Narrator Model Eval
+
+Generated 2026-06-11 21:13:27.
+
+Score each cell 1-5 on: **S**pecificity (names real visible things), **G**roundedness (no invented objects/people), **V**oice (style lands). A model needs S>=4 and G>=4 on most images to be the pick.
+
+## HEIF Image-46AC-B1CB-06-0.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A white wall is painted a dark gray. A security camera is mounted centrally on the wall. A blue plaque displays the rating “8.6” and the text “Mummy by Pillow.” Below the plaque, a rectangular white card sits on a small, terracotta pot containing dried lavender.  A map of the area is pinned to the wall beside a collection of photographs depicting buildings and streets. | 155.7s |  |  |  |
+| google/gemma-3-4b-it | noir | A white wall dominates the frame, painted a matte gray. A small, framed review card displays the number 8.6 and the words “Mum by Pillow.” Below it, a map of the city is pinned alongside a collection of black and white photographs. A promotional flyer for “Enjoy the Magic of Musical Theatre” is affixed to the right, and a small, terracotta pot holds a sprig of lavender. A security camera is mounted above the wall, its lens pointed downward. | 5.8s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A white wall dominates the frame, its surface reflecting the light from a recessed ceiling fixture. A small, rectangular plaque displays the rating “8.6” beneath the text “Mummer by Pillow.” Below that, a collection of photographs depicts a cityscape, and a map of the area is pinned to a corkboard. A potted plant with lavender flowers sits on a small, dark table to the left of the wall. | 5.0s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-1.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A woman stands before a brown wooden counter. She wears a black skirt and a black and white striped shirt, along with white sneakers. A printed sign on the counter reads “Reparación de PC y Tabletas” in Spanish. Behind her, shelves hold a collection of printed materials, including a laptop and a printer. | 3.9s |  |  |  |
+| google/gemma-3-4b-it | noir | A woman in a black skirt and a striped shirt stands before a wooden counter. She wears white sneakers and a denim jacket. A sign reads “REPARACION DE PC Y TELEFATAS” in Spanish. A laptop sits on the counter, and a small, framed photograph is visible on the wall behind her. | 3.8s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A woman stands before a wooden counter, the surface displaying a sign in Spanish. She wears a black skirt and a black and white striped shirt, and white sneakers. A laptop sits on the counter, facing her. To the left, a shelf holds stacks of printed documents, and a small, framed photograph is visible on the wall behind. | 4.1s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-2.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A white Ford Focus occupies the lower portion of the frame, its tires resting on a gray asphalt surface. A shadow stretches from the car’s underside, cast by the low angle of the afternoon sun. Brick buildings line the street, displaying darkened windows and a sign reading “Centro de Dia” above a doorway. A small, yellow parking sign with a red circle and diagonal slash is affixed to a white metal railing beside the road. | 5.2s |  |  |  |
+| google/gemma-3-4b-it | noir | A white Ford Focus occupies the right side of the frame, its tires resting on a grey asphalt surface. A shadow stretches from the vehicle’s underside, cast by the late afternoon sun. Across the street, a brick building rises, punctuated by rectangular windows and a wrought iron balcony. A small, yellow sign, partially obscured, reads “Plaza de Centro de Salud.” | 4.5s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A white Ford Focus occupies the right foreground, its chrome hubcaps reflecting the overcast sky. A shadow stretches from the vehicle’s lower portion across the grey pavement. Across the street, a brick building rises with a series of rectangular windows and a white wrought iron fence. A small, yellow sign is affixed to the building’s façade, displaying text in Spanish. | 4.4s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-3.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A dark laptop rests on a rumpled gray blanket. A white paper lantern hangs above, its shade casting a diffuse light across the ceiling. A denim jacket is draped over a wooden hanger beside the bed. | 2.6s |  |  |  |
+| google/gemma-3-4b-it | noir | A laptop rests open on a bed, the screen dark. A patterned sheet lies rumpled beneath it, and a denim jacket hangs on a wooden hanger. Above, a white paper lantern illuminates the ceiling, and a vent grille is visible in the plaster. | 3.1s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A dark-gray laptop rests on a bedspread of pale blue and white. A white ceiling hangs above, punctuated by a hanging light fixture with a white, paper-like shade. A denim jacket is draped over a wooden clothes rack to the right. | 3.2s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-4.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A man sits at a wooden table, wearing sunglasses and a black t-shirt. A small, dark pipe rests in his hand, and he holds a glass of amber liquid. Two bottles of Coca-Cola and a square, red “Gracias” box are positioned on the table surface. A glass of golden liquid sits to the right of the pipe and bottle. | 4.4s |  |  |  |
+| google/gemma-3-4b-it | noir | A man sits at a dark wooden table. He wears a black shirt and sunglasses, and a small, white pipe rests in his hand. Two bottles of Coca-Cola and a glass of Estrella beer sit on the table beside him, along with a small, red box that reads “Gracias.” Outside, a blue sky is visible through a leafy hedge, and a building with beige facades rises in the background. | 4.9s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A man sits at a gray outdoor table. He wears sunglasses and a black shirt with “Training” printed on the sleeve. A lit pipe rests in his mouth, and a dark-colored bottle rests on the table beside him. Two glasses of amber liquid sit on the table, one partially full, the other nearly empty. | 4.0s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-5.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A man in a dark gray t-shirt stands before a glass door. His hands are resting on the cool, gray concrete of a raised platform. A red neon sign reading “D&G” is visible through the glass, illuminating a dark interior.  A printed sign on the door advertises “Dog Friendly” and lists daily hours. | 4.2s |  |  |  |
+| google/gemma-3-4b-it | noir | A man stands before a glass door, his hands resting on the cool metal of the threshold. He wears a dark t-shirt and his hair is graying at the temples. A red sign, partially obscured by the glass, reads “D&G Friendly.”  The interior of a building is visible through the glass, showing a dimly lit space with tables and chairs. | 4.5s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A man stands before a glass door, his hand resting on the cool metal of the threshold. He wears a dark gray t-shirt and his hair is graying at the temples. The glass door reflects the interior of a brightly lit restaurant, showing a red awning and the words “D&G Friendly.” A small, hand-written sign above the door reads “De Dimous A Diurne.” | 4.9s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-6.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A light fixture with a circular diffuser emits a bright, white glow. A woven, spherical light hangs below it, casting a diffuse shadow on the wall. A gray, upholstered chair sits to the right, with a small, woven basket on its surface. A partial view of a dark wooden door is visible in the foreground. | 4.0s |  |  |  |
+| google/gemma-3-4b-it | noir | A circular ceiling light illuminates a section of the room, casting a stark white circle on the wall. A woven pendant light hangs below, its shade partially obscuring the bulb. A gray wall is visible to the right, with a recessed door frame. A portion of a patterned rug lies in the foreground, beneath a hand. | 3.9s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A pale circular light illuminates the ceiling. A woven light fixture hangs directly below, casting a patterned shadow on the wall. A grey sofa sits partially visible in the background, draped with a woven throw. The lower portion of a person’s hand rests on a patterned blanket. | 3.4s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-7.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A black backpack rests on the top of a white cabinet. The cabinet doors are closed, revealing a stainless steel oven and a blank, white shelf. A metal key hangs from a keyhole on the cabinet’s right side. Gray-toned wooden flooring extends across the lower portion of the frame. | 3.7s |  |  |  |
+| google/gemma-3-4b-it | noir | A black backpack rests on the surface of a white cabinet. The cabinet doors are closed, revealing the interior of the appliance and a blank, white space. A silver oven control panel is visible within the cabinet’s opening. A light gray floor runs beneath the cabinet, extending into the distance. | 3.6s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A black backpack rests on the top shelf of a white cabinet. The cabinet doors are closed, revealing a stainless steel oven with a mesh filter and a lower shelf. A light gray floor with a wood-grain pattern extends into the frame. A silver handle is visible on the cabinet door. | 3.6s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-8.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A white parasol shields a small table and four chairs from direct sunlight. A large, mature tree occupies the center of the frame, its branches extending over the seating area. A man sits at the table, facing away from the camera, wearing a dark blue shirt and white pants. Several bicycles are parked along the sidewalk in the background, and a green garbage bin sits to the left of the tree. | 4.9s |  |  |  |
+| google/gemma-3-4b-it | noir | A white parasol extends over a small table with four chairs. A man sits at the table, facing the street. A dark tree trunk dominates the left side of the frame, its branches covered in dense green leaves. Several bicycles are parked along the sidewalk, and a green waste bin sits beneath a building on the right. | 4.0s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A large white umbrella provides shade over a small table and four chairs. A man sits at the table, facing away from the camera. Green foliage overhangs the table and extends upward, partially obscuring a building on the left. A dark green trash receptacle stands to the left of the table. | 3.6s |  |  |  |
+
+## HEIF Image-46AC-B1CB-06-9.heic
+
+| Model | Style | Narration | Latency | S | G | V |
+|---|---|---|---|---|---|---|
+| google/gemma-3-4b-it | deadpan | A man sits at a wooden desk. He wears a gray, long-sleeved sweater and dark pants. A white plant sits on the desk to his left, and a folded document rests on the surface in front of him. A gray staircase curves upwards to the right, with a pale gray railing. | 3.7s |  |  |  |
+| google/gemma-3-4b-it | noir | A man sits at a wooden desk, his dark hair pulled back from his face. A beige document rests on the desk before him, partially obscured by a small, white branch. The steps leading upward are gray concrete, illuminated by a bright, rectangular window. A black elevator panel is mounted on the wall behind the man. | 4.0s |  |  |  |
+| google/gemma-3-4b-it | nature_doc | A dark-colored sweater covers the figure’s torso. The individual’s dark hair is pulled back from their face and rests against a wooden surface. A light-colored document is positioned on the surface in front of the individual. A white branch, covered in small green leaves, sits on a wooden box to the left. | 4.0s |  |  |  |
+
+## Failed models
+
+- HuggingFaceTB/SmolVLM2-2.2B-Instruct: ValueError: Unrecognized image processor in HuggingFaceTB/SmolVLM2-2.2B-Instruct. Should have a `image_processor_type` key in its preprocessor_config.json of config.json, or one of the following `model_type` keys in its config.json: aria, beit, bit, blip, bridgetower, chameleon, chinese_clip, chmv2, clip, cohere2_vision, conditional_detr, convnext, deepseek_ocr2, deepseek_vl, deepseek_vl_hybrid, deformable_detr, deit, depth_pro, detr, dinov3_vit, dpt, efficientloftr, efficientnet, eomt, ernie4_5_vl_moe, flava, fuyu, gemma3, gemma4, gemma4_unified, glm46v, glm4v, glm_image, glmga, glpn, got_ocr2, grounding-dino, idefics, idefics2, idefics3, imagegpt, janus, layoutlmv2, layoutlmv3, levit, lfm2_vl, lightglue, llama4, llava, llava_next, llava_onevision, mask2former, maskformer, minicpmv4_6, mllama, mobilenet_v1, mobilenet_v2, mobilevit, nougat, oneformer, ovis2, owlv2, owlvit, paddleocr_vl, perceiver, perception_lm, phi4_multimodal, pi0, pix2struct, pixtral, poolformer, pp_chart2table, pp_doclayout_v2, pp_doclayout_v3, pp_formulanet, pp_lcnet, pp_ocrv5_server_det, pp_ocrv5_server_rec, pp_ocrv6_small_rec, prompt_depth_anything, pvt, qwen2_vl, rf_detr, rt_detr, sam, sam2, sam3, sapiens2, segformer, seggpt, siglip, siglip2, slanext, smolvlm, superglue, superpoint, swin2sr, textnet, tvp, uvdoc, video_llama_3, videomae, vilt, vit, vitmatte, vitpose, yolos, zoedepth, aimv2, aimv2_vision_model, align, altclip, aya_vision, blip-2, clipseg, colpali, colqwen2, convnextv2, cosmos3_omni, cvt, data2vec-vision, deimv2, depth_anything, dinat, dinov2, donut-swin, edgetam, emu3, eomt_dinov3, exaone4_5, florence2, focalnet, gemma3n, git, granite4_vision, groupvit, hiera, ijepa, instructblip, internvl, kosmos-2, kosmos-2.5, layoutxlm, lighton_ocr, llava_next_video, lw_detr, metaclip_2, mgp-str, mistral3, mlcd, mm-grounding-dino, mobilevitv2, omdet-turbo, paligemma, pixio, pp_ocrv5_mobile_det, pp_ocrv5_mobile_rec, pp_ocrv6_medium_det, pp_ocrv6_small_det, pp_ocrv6_tiny_rec, pvt_v2, qianfan_ocr, qwen2_5_omni, qwen2_5_vl, qwen3_5, qwen3_5_moe, qwen3_omni_moe, qwen3_vl, regnet, resnet, sam2_video, sam3_lite_text, sam3_tracker, sam3_tracker_video, sam3_video, sam_hq, shieldgemma2, slanet, swiftformer, swin, swinv2, t5gemma2, t5gemma2_encoder, table-transformer, timesformer, timm_wrapper, trocr, udop, upernet, video_llava, vipllava, vit_mae, vit_msn, vivit, xclip
+- Qwen/Qwen2.5-VL-3B-Instruct: ImportError: 
+Qwen2VLVideoProcessor requires the Torchvision library but it was not found in your environment. Check out the instructions on the
+installation page: https://pytorch.org/get-started/locally/ and follow the ones that match your environment.
+Please note that you may need to restart your runtime after installation.
+
+- Qwen/Qwen2.5-VL-7B-Instruct: ImportError: 
+Qwen2VLVideoProcessor requires the Torchvision library but it was not found in your environment. Check out the instructions on the
+installation page: https://pytorch.org/get-started/locally/ and follow the ones that match your environment.
+Please note that you may need to restart your runtime after installation.
+

docs/eval/run-004-scored.md

@@ -0,0 +1,76 @@
+# Small Cuts — M1 Eval, Scored (run-004)
+
+Judge: Codex (GPT-5 vision) scoring each narration against the actual photo.
+Rubric: S(pecificity), G(roundedness), V(oice), 1-5. Pick rule: S>=4 and G>=4 on most images.
+
+## Verdict
+
+| Model | mean S | mean G | mean V | cells S>=4 & G>=4 | images passing (>=2/3 styles) |
+|---|---|---|---|---|---|
+| Qwen/Qwen2.5-VL-3B-Instruct | 2.73 | 2.70 | 2.50 | 4/30 | 1/10 |
+| google/gemma-3-4b-it | 2.60 | 1.90 | 2.53 | 0/30 | 0/10 |
+
+## Per-cell scores
+
+| Image | Model | Style | S | G | V | Judge note |
+|---|---|---|---|---|---|---|
+| img-46AC-B1CB-06-0 | google/gemma-3-4b-it | deadpan | 2 | 1 | 2 | Invents man, coffee, mug, robin; only rating and map align |
+| img-46AC-B1CB-06-0 | google/gemma-3-4b-it | noir | 3 | 2 | 4 | Good noir mood, but invents a person and actions |
+| img-46AC-B1CB-06-0 | google/gemma-3-4b-it | nature_doc | 2 | 1 | 2 | Invents hand, person, motion, dust, Tuscan photo |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 5 | 4 | 4 | Mostly accurate specifics; “digital sign” and office framing are shaky |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 3 | 4 | Noir lands, but stack of papers and desk are unsupported |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 1 | 1 | 3 | Invents male, coffee machine, cups, and ritual |
+| img-46AC-B1CB-06-1 | google/gemma-3-4b-it | deadpan | 2 | 2 | 3 | Brochures, travel guides, expression, and transaction are unsupported. |
+| img-46AC-B1CB-06-1 | google/gemma-3-4b-it | noir | 2 | 1 | 4 | Invents stapler, rain, window, tracing fingers, and emotional claims. |
+| img-46AC-B1CB-06-1 | google/gemma-3-4b-it | nature_doc | 3 | 2 | 1 | Sign is close, but paperback, tremor, and blue screen are invented. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 5 | 4 | 4 | Strong visible details; clothing and sign wording are slightly off. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 4 | 4 | 3 | Mostly grounded, but adds inner states and overstates noir mood. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 1 | 2 | 1 | Generic and invents walking, turning away, urgency, and sequence. |
+| img-46AC-B1CB-06-2 | google/gemma-3-4b-it | deadpan | 3 | 2 | 2 | Some visible shadow/car details, but invents damp pavement, sign text, man watching. |
+| img-46AC-B1CB-06-2 | google/gemma-3-4b-it | noir | 3 | 1 | 4 | Noir mood lands, but wet asphalt, overcast sky, cone, pothole, sign text invented. |
+| img-46AC-B1CB-06-2 | google/gemma-3-4b-it | nature_doc | 2 | 2 | 1 | Mostly not nature-documentary; invents wet pavement, overcast sky, clinic door focus. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 2 | 4 | 1 | Mentions visible red car and shadows, but tone is ominous, not deadpan. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 2 | 3 | Some glare and shadow fit, but invents a man walking past. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 2 | 4 | 2 | Mostly grounded but generic; weak nature-documentary framing. |
+| img-46AC-B1CB-06-3 | google/gemma-3-4b-it | deadpan | 4 | 3 | 3 | Good objects, but invents chair/person mood. |
+| img-46AC-B1CB-06-3 | google/gemma-3-4b-it | noir | 3 | 4 | 4 | Mostly grounded, noir mood lands. |
+| img-46AC-B1CB-06-3 | google/gemma-3-4b-it | nature_doc | 3 | 3 | 1 | Grounded objects, but not nature-documentary voice. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 3 | 2 | 2 | Invents desk, door, and air-conditioner sound. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 1 | 3 | Invents sleeping user and exaggerated lighting. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 3 | 3 | 1 | Some specifics, but invents figure and lacks documentary style. |
+| img-46AC-B1CB-06-4 | google/gemma-3-4b-it | deadpan | 2 | 1 | 2 | Invents cigarette, smoke, Coke bottle, unopened beer, and shirt location. |
+| img-46AC-B1CB-06-4 | google/gemma-3-4b-it | noir | 3 | 2 | 4 | Noir voice works, but cigarette packet and Coke bottle are invented. |
+| img-46AC-B1CB-06-4 | google/gemma-3-4b-it | nature_doc | 3 | 2 | 1 | Several visible anchors, but cigarette, smoke, condensation, and sleeve text are wrong. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 5 | 3 | 3 | Specific, but mislabels tray and invents prior visitor and precarious cap. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 5 | 4 | 2 | Mostly grounded specifics; beverage color is wrong and noir voice is weak. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 4 | 3 | 2 | Uses real objects, but invents untouched beer and bustling suburban context. |
+| img-46AC-B1CB-06-5 | google/gemma-3-4b-it | deadpan | 3 | 2 | 2 | Invents scent, knuckles, D&G neon; voice too lyrical. |
+| img-46AC-B1CB-06-5 | google/gemma-3-4b-it | noir | 2 | 1 | 4 | Noir lands, but rain and falling ID card are invented. |
+| img-46AC-B1CB-06-5 | google/gemma-3-4b-it | nature_doc | 4 | 3 | 2 | Good visible details; invents sweat and misses nature-documentary voice. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 4 | 2 | 4 | Flat and specific; invents masked cap-wearing man talking. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 3 | 3 | 3 | Some real pose details; rain and clothing colors are wrong. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 2 | 4 | 1 | Mostly grounded but generic; nature-documentary style barely appears. |
+| img-46AC-B1CB-06-6 | google/gemma-3-4b-it | deadpan | 3 | 3 | 2 | Vent and blanket grounded; phone beam and dust motes invented. |
+| img-46AC-B1CB-06-6 | google/gemma-3-4b-it | noir | 2 | 1 | 4 | Invents ceiling fan, paper, sheet, blue glow, and hum. |
+| img-46AC-B1CB-06-6 | google/gemma-3-4b-it | nature_doc | 2 | 2 | 1 | Some bedding detail, but invents sneaker and lacks documentary voice. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 2 | 1 | 2 | Invents ceiling fans, posture, armrests, and vent state. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 2 | 4 | Noir lands, but cigarette box, rain, and small table are invented. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 3 | 3 | 2 | Wicker lamps and circular light grounded; posture and vent phrasing wrong. |
+| img-46AC-B1CB-06-7 | google/gemma-3-4b-it | deadpan | 3 | 2 | 2 | Good backpack/cabinet details, but invents list, apple core, unseen events. |
+| img-46AC-B1CB-06-7 | google/gemma-3-4b-it | noir | 3 | 2 | 4 | Noir lands, but invents key and misstates oven/cabinet relation. |
+| img-46AC-B1CB-06-7 | google/gemma-3-4b-it | nature_doc | 3 | 2 | 1 | Invents bag contents and open oven; not nature-documentary style. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 3 | 3 | 2 | Mostly visible scene, but claims empty bag, key, departure speculation. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 1 | 3 | Invents cigarette, detective, breeze; only backpack/counter are grounded. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 2 | 4 | 1 | Mostly grounded but generic, with little actual nature-documentary voice. |
+| img-46AC-B1CB-06-8 | google/gemma-3-4b-it | deadpan | 2 | 2 | 2 | Umbrella and man fit, but glass, newspaper, timing invented. |
+| img-46AC-B1CB-06-8 | google/gemma-3-4b-it | noir | 2 | 1 | 4 | Noir tone works; glasses, lemon, briefcase, truck, exhaust hallucinated. |
+| img-46AC-B1CB-06-8 | google/gemma-3-4b-it | nature_doc | 2 | 1 | 2 | Mentions umbrella and paving, but briefcase, bottle, cyclist invented. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 3 | 3 | 2 | Tables, chairs, umbrella, tree visible; reflection and smile invented. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 2 | 3 | Solitary figure and cigarette are wrong; mood partly noir. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 1 | 3 | 2 | Mostly vague, misses visible details; falsely implies man is alone. |
+| img-46AC-B1CB-06-9 | google/gemma-3-4b-it | deadpan | 2 | 2 | 2 | Mostly invents hand, document, action; tone too literary. |
+| img-46AC-B1CB-06-9 | google/gemma-3-4b-it | noir | 2 | 2 | 4 | Noir works, but invents hands, paper, dust, waiting. |
+| img-46AC-B1CB-06-9 | google/gemma-3-4b-it | nature_doc | 3 | 2 | 2 | Good counter and staircase; invents bread flyer and inner state. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 3 | 3 | 3 | Braids and bowed head fit; yellow cushion is not visible. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 1 | 4 | Noir tone, but candle, papers, floorboards, detective are invented. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 2 | 2 | 1 | Invents sign text and cafe; little nature-documentary voice. |

docs/eval/run-005-scored.md

@@ -0,0 +1,107 @@
+# Small Cuts — M1 Eval, Scored (run-005)
+
+Judge: Codex (GPT-5 vision) scoring each narration against the actual photo.
+Rubric: S(pecificity), G(roundedness), V(oice), 1-5. Pick rule: S>=4 and G>=4 on most images.
+
+## Verdict
+
+| Model | mean S | mean G | mean V | cells S>=4 & G>=4 | images passing (>=2/3 styles) |
+|---|---|---|---|---|---|
+| Qwen/Qwen2.5-VL-3B-Instruct | 3.73 | 3.13 | 2.43 | 9/30 | 2/10 |
+| Qwen/Qwen2.5-VL-7B-Instruct | 3.47 | 3.40 | 3.03 | 7/30 | 1/10 |
+| google/gemma-3-4b-it | 3.33 | 2.70 | 2.63 | 5/30 | 1/10 |
+
+## Per-cell scores
+
+| Image | Model | Style | S | G | V | Judge note |
+|---|---|---|---|---|---|---|
+| img-46AC-B1CB-06-0 | google/gemma-3-4b-it | deadpan | 4 | 3 | 5 | Good objects, but poster text and pot color are wrong. |
+| img-46AC-B1CB-06-0 | google/gemma-3-4b-it | noir | 3 | 2 | 2 | TripAdvisor, pillow image, and poster text are invented. |
+| img-46AC-B1CB-06-0 | google/gemma-3-4b-it | nature_doc | 3 | 2 | 1 | Key text and pot color wrong; no nature-documentary voice. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 5 | 4 | 5 | Strong specifics; digital sign and 2026 are questionable. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 3 | 3 | 2 | Real objects, but shelf placement is wrong and noir is thin. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 4 | 3 | 2 | Good text, but office/digital display are invented and style is weak. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 5 | 5 | 4 | Accurate specifics; slightly too expressive for deadpan. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 4 | 3 | 4 | Noir lands, but corkboard and long shadows are shaky. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3 | 3 | 2 | Invents motion and lacks exact visible sign text. |
+| img-46AC-B1CB-06-1 | google/gemma-3-4b-it | deadpan | 3 | 3 | 5 | Plain and factual, but sign text is wrong. |
+| img-46AC-B1CB-06-1 | google/gemma-3-4b-it | noir | 4 | 3 | 2 | Good clothing/counter detail; wrong sign and weak noir. |
+| img-46AC-B1CB-06-1 | google/gemma-3-4b-it | nature_doc | 4 | 2 | 1 | Wrong sign and blue screen; no nature-documentary voice. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 5 | 3 | 4 | Many specifics, but jeans, tied hair, laptop, waiting are unsupported. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 5 | 4 | 2 | Mostly grounded specifics, but little noir atmosphere. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 5 | 3 | 1 | Specific but monitor/sign details blur together; no documentary voice. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 4 | 4 | 4 | Mostly accurate, though man and desk activity are inferred. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3 | 3 | 4 | Noir tone works; shadows and intrigue are embellished. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 2 | 2 | 2 | Mislabels store as office/workplace and stays generic. |
+| img-46AC-B1CB-06-2 | google/gemma-3-4b-it | deadpan | 3 | 3 | 4 | White car is right; sign text appears invented. |
+| img-46AC-B1CB-06-2 | google/gemma-3-4b-it | noir | 3 | 3 | 2 | Correct car and yellow line; sign text not visible. |
+| img-46AC-B1CB-06-2 | google/gemma-3-4b-it | nature_doc | 2 | 2 | 1 | Sign text is garbled and style is not nature documentary. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 3 | 4 | 4 | Mostly accurate scene description, but red car is foreground, not parked. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 4 | 4 | 2 | Good visible specifics; noir voice is weak. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 4 | 5 | 1 | Grounded specifics, but no nature-documentary framing. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 4 | 5 | 4 | Accurate concrete details with a suitably flat voice. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 2 | 3 | 4 | Noir tone lands, but relies on invented mystery atmosphere. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 2 | 4 | 2 | Mostly grounded but generic and not documentary-like. |
+| img-46AC-B1CB-06-3 | google/gemma-3-4b-it | deadpan | 4 | 4 | 5 | Concise and mostly accurate; wall location is slightly imprecise. |
+| img-46AC-B1CB-06-3 | google/gemma-3-4b-it | noir | 4 | 3 | 2 | Invents sheet spilling onto floor; noir voice is weak. |
+| img-46AC-B1CB-06-3 | google/gemma-3-4b-it | nature_doc | 5 | 3 | 1 | Good objects, but lantern glow and hanger are uncertain; not nature-doc. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 5 | 3 | 3 | Many specifics, but workspace, glow, and folded blanket are off. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 2 | 3 | Invents desk lamp, chair, and dim lighting. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 3 | 2 | 1 | Misreads bed as desk and room as clean office; not nature-doc. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 5 | 3 | 3 | Strong specifics, but wooden lamp, hook, and cool-room inference are unsupported. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 4 | 3 | 4 | Good noir mood, but glow and whispering shadows are invented. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3 | 3 | 2 | Some grounded objects, but vent sound and dancing shadows are invented. |
+| img-46AC-B1CB-06-4 | google/gemma-3-4b-it | deadpan | 2 | 1 | 4 | Invents pipe and Coca-Cola bottle; mostly generic. |
+| img-46AC-B1CB-06-4 | google/gemma-3-4b-it | noir | 2 | 1 | 2 | Invents cigarette, smoke, and Coca-Cola bottle. |
+| img-46AC-B1CB-06-4 | google/gemma-3-4b-it | nature_doc | 2 | 1 | 1 | Invents pipe and smoke; weak documentary voice. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 5 | 4 | 4 | Strong specifics; pink beer wording is questionable. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 5 | 4 | 1 | Grounded details, but almost no noir voice. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 4 | 3 | 2 | Misstates drinks; limited nature-documentary framing. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 5 | 3 | 2 | Mistakes napkin dispenser for bottle; adds interpretation. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3 | 3 | 3 | Some noir tone, but invents note implication and bottle. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 4 | 3 | 1 | Park and Coca-Cola bottle are wrong; not documentary style. |
+| img-46AC-B1CB-06-5 | google/gemma-3-4b-it | deadpan | 2 | 2 | 4 | Flat voice, but bench, awning, D&G, and hours are wrong. |
+| img-46AC-B1CB-06-5 | google/gemma-3-4b-it | noir | 2 | 3 | 3 | Some real door details, but bench and D&G sign are false. |
+| img-46AC-B1CB-06-5 | google/gemma-3-4b-it | nature_doc | 3 | 2 | 1 | Hours text is close, but bench and red D&G sign hallucinated. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 4 | 4 | 4 | Strong visible specifics; cap and inside-person claim are uncertain. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 3 | 2 | 3 | Wet street, held sign, and neon Yes You Can are false. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 4 | 3 | 1 | Good specifics, but Dog Friendly cap claim is wrong. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 3 | 3 | 4 | Mostly grounded, but walking individual and Spanish hours are unsupported. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 2 | 4 | 4 | Moody and mostly grounded, but low on concrete photo details. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3 | 3 | 2 | Some grounded details, but bustling street and nature-doc voice are weak. |
+| img-46AC-B1CB-06-6 | google/gemma-3-4b-it | deadpan | 4 | 4 | 5 | Mostly concrete and accurate; hand/directly-below details are shaky. |
+| img-46AC-B1CB-06-6 | google/gemma-3-4b-it | noir | 3 | 3 | 3 | Some specifics, but blanket floor and gray doorway are questionable. |
+| img-46AC-B1CB-06-6 | google/gemma-3-4b-it | nature_doc | 3 | 3 | 1 | Grounding slips on wall/floor/object; no documentary voice. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 3 | 2 | 2 | Invents floor lamp, footrest, bed sway; only partly deadpan. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 2 | 3 | Invents circular window and motion; noir mood is present. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 2 | 2 | 1 | Invents circular window and ajar door; lacks nature-documentary framing. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 3 | 3 | 4 | Accurate hand and lampshade, but person/table/checkered shirt are off. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 2 | 2 | 4 | No ceiling fan visible; mood fits noir better than facts. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 4 | 4 | 1 | Good visible-room details, but essentially no nature-documentary voice. |
+| img-46AC-B1CB-06-7 | google/gemma-3-4b-it | deadpan | 5 | 4 | 5 | Strong specifics, but invents a key on the cabinet door. |
+| img-46AC-B1CB-06-7 | google/gemma-3-4b-it | noir | 4 | 3 | 2 | Invents key and lock; voice is mostly plain description. |
+| img-46AC-B1CB-06-7 | google/gemma-3-4b-it | nature_doc | 5 | 3 | 1 | Specific, but key claim is false and nature-doc voice absent. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 4 | 5 | 4 | Grounded cabinet and backpack details; slightly interpretive at the end. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 4 | 3 | 4 | Noir tone works, but invents a doorway-like threshold. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 3 | 2 | 1 | Invents open-plan office setting and misses nature-documentary framing. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 5 | 3 | 4 | Many real details, but falsely says the oven is open. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 4 | 5 | 4 | Grounded details with a competent moody noir atmosphere. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 5 | 4 | 1 | Mostly grounded kitchen details, but nature-documentary voice is missing. |
+| img-46AC-B1CB-06-8 | google/gemma-3-4b-it | deadpan | 4 | 4 | 5 | Concrete and flat; likely one seated man, bin placement roughly right |
+| img-46AC-B1CB-06-8 | google/gemma-3-4b-it | noir | 4 | 3 | 2 | Pale rectangle and single chair are questionable; weak noir voice |
+| img-46AC-B1CB-06-8 | google/gemma-3-4b-it | nature_doc | 4 | 4 | 2 | Mostly accurate specifics, but barely nature-documentary narration |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 3 | 2 | 2 | Invents logo text, pedestrians, sound, and man alone |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 2 | 3 | 3 | Grounded broad scene, but invents solitude and inner reflection |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 3 | 3 | 1 | Some accurate setting details, but invents thoughts and lacks documentary voice |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 4 | 5 | 4 | Specific and grounded; relaxed urban setting is slightly interpretive |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 4 | 3 | 4 | Good noir tone, but invents readable Cafe text and some shadows |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3 | 3 | 2 | Invents rustling soundtrack and sky detail; style is generic pastoral |
+| img-46AC-B1CB-06-9 | google/gemma-3-4b-it | deadpan | 4 | 3 | 4 | Good desk, plant, staircase, box; invents hands/document and curved stairs. |
+| img-46AC-B1CB-06-9 | google/gemma-3-4b-it | noir | 3 | 2 | 2 | Counter is right, but hands, brown plant, curved stairs are shaky. |
+| img-46AC-B1CB-06-9 | google/gemma-3-4b-it | nature_doc | 2 | 2 | 1 | Wrong sweater color, hands/document, plant color; no nature-documentary voice. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-3B-Instruct | deadpan | 5 | 4 | 3 | Strong visible details; mental-state inference and glass railing weaken grounding. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-3B-Instruct | noir | 4 | 3 | 3 | Braids, sweater, chair work; desk lamp is invented. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-3B-Instruct | nature_doc | 4 | 3 | 1 | Good person/table details; sign is mislocated and voice misses nature-doc style. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 3 | 4 | 3 | Mostly grounded but generic, with contemplative inference instead of flat deadpan. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3 | 2 | 4 | Noir mood lands, but shadow, swaying braids, gaze are invented. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3 | 4 | 1 | Grounded broad scene, but poetic contemplation is not nature-documentary narration. |

docs/eval/run-006-scored.md

@@ -0,0 +1,107 @@
+# Small Cuts — M1 Eval, Scored (run-006, dual judge)
+
+Head-to-head: run-005 provisional pick **Qwen2.5-VL-7B** vs challenger **Qwen3-VL-8B** (prompt v3, temp 0.3, 10 glasses photos × 3 styles).
+
+Two independent judges, different model families, same rubric and photos:
+
+- **Judge A — Codex** (GPT-5 vision), same judge as run-004/005.
+- **Judge B — Antigravity** (Gemini 3.1 Pro vision), added to address the single-judge weakness of the earlier picks.
+
+Rubric: S(pecificity), G(roundedness), V(oice), 1-5. Pick rule: S>=4 and G>=4 on most images (>=2 of 3 styles per image).
+
+## Verdict — both judges, same ranking
+
+### Judge A: Codex (GPT-5)
+
+| Model | mean S | mean G | mean V | cells S>=4 & G>=4 | images passing |
+|---|---|---|---|---|---|
+| Qwen/Qwen2.5-VL-7B-Instruct | 3.10 | 3.53 | 3.03 | 4/30 | 0/10 |
+| Qwen/Qwen3-VL-8B-Instruct | 4.33 | 3.83 | 4.20 | 19/30 | 7/10 |
+
+### Judge B: Antigravity (Gemini 3.1 Pro)
+
+| Model | mean S | mean G | mean V | cells S>=4 & G>=4 | images passing |
+|---|---|---|---|---|---|
+| Qwen/Qwen2.5-VL-7B-Instruct | 3.20 | 3.07 | 3.57 | 1/30 | 0/10 |
+| Qwen/Qwen3-VL-8B-Instruct | 4.77 | 4.33 | 4.60 | 26/30 | 9/10 |
+
+**Final pick: `Qwen/Qwen3-VL-8B-Instruct`.** It passes the pick rule for both judges (7/10 and 9/10 images) while the run-005 provisional pick Qwen2.5-VL-7B passes 0/10 for both. The provisional pick is overturned; the two judged conclusions agree independently.
+
+## Inter-judge agreement
+
+| Dim | MAE | exact | within ±1 | Pearson r | Codex mean | Gemini mean |
+|---|---|---|---|---|---|---|
+| S | 0.50 | 53% | 97% | 0.76 | 3.72 | 3.98 |
+| G | 0.75 | 35% | 90% | 0.51 | 3.68 | 3.70 |
+| V | 0.60 | 60% | 85% | 0.70 | 3.62 | 4.08 |
+
+Cohen's kappa on the pass/fail decision per cell: **0.59** (moderate agreement). Gemini runs ~0.3-0.5 hotter on S and V; G means are nearly identical. Disagreements concentrate in V (style taste) — on factual grounding the judges typically flag the *same* errors and differ only in severity (see per-cell notes). The model ranking is unaffected by judge choice.
+
+## Per-cell scores (Codex / Gemini)
+
+| Image | Model | Style | S | G | V | Codex note | Gemini note |
+|---|---|---|---|---|---|---|---|
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 5/4 | 5/4 | 4/2 | Accurate visible details; slightly more polished than deadpan. | Flowery language like 'proudly displaying' breaks the requested deadpan style. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3/3 | 4/4 | 4/2 | Grounded but misses specifics like camera, 8,6, plant, flyers. | The phrase 'beacon of trust' completely contradicts the cynical noir tone. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 4/4 | 3/3 | 2/2 | Map location and pins are uncertain; style not documentary. | Misses the 'humans as observed species' angle and hallucinates map pins marking POIs. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 4/4 | 5/5 | Very specific; air conditioner brand appears misread. | Excellent specifics and deadpan tone; minor hallucination on AC brand name (ferroli). |
+| img-46AC-B1CB-06-0 | Qwen/Qwen3-VL-8B-Instruct | noir | 4/5 | 2/4 | 5/5 | Strong noir, but invents a man and story. | Incredible hardboiled tone with a very perceptive observation about the artificial plant. |
+| img-46AC-B1CB-06-0 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 5/5 | 4/5 | 4/5 | Detailed and mostly grounded; map place and lavender are uncertain. | Perfectly extracts and translates Catalan text while treating the room as a human habitat. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 4/4 | 4/3 | 4/5 | Good shop details; denim skirt and conversation are slightly off. | Misidentifies denim jacket tied at waist as a denim skirt. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3/4 | 4/3 | 3/5 | Mostly grounded, but generic noir and denim skirt is inaccurate. | Misidentifies the denim jacket tied at waist as a denim skirt. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 2/3 | 3/4 | 3/5 | Open-plan office is wrong; few concrete photo specifics. | Mischaracterizes the retail repair shop as an open-plan office. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 5/5 | 5/5 | Strong visible specifics: clothing, clerk, bag, accessories, extinguisher sign. | Perfectly identifies clothing layers, bag, and the EXTINTOR sign. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen3-VL-8B-Instruct | noir | 4/5 | 4/5 | 5/5 | Noir lands; typing and man are inferred beyond visible evidence. | Accurately captures pale yellow walls and the exact sign text. |
+| img-46AC-B1CB-06-1 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 4/5 | 4/4 | 5/5 | Style works; blinking devices and bowed heads are not clearly visible. | Hallucinates packaged goods on the shelves as 'blinking devices'. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 3/4 | 3/3 | 5/5 | Sign text is inaccurate; otherwise grounded and flat. | Misreads PLACES as Plaça and inaccurately describes the red car's shadow. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 2/3 | 4/3 | 4/5 | Mostly grounded, but light on photo-specific details. | Inaccurately claims the red car casts a shadow over the sidewalk. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 2/2 | 4/5 | 2/2 | Grounded but generic; nature documentary voice barely appears. | Fails the nature doc prompt by lacking the humans as species observational framing. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 5/4 | 5/5 | Strong visible specifics, including shadow, cars, sign, and facade. | Car is parked parallel, not angled; shadow shows both hands raised holding camera. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen3-VL-8B-Instruct | noir | 4/5 | 3/3 | 5/5 | Noir lands, but gender and movement are invented. | Hallucinates the brightly lit brick building as being a dark silhouette. |
+| img-46AC-B1CB-06-2 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 4/5 | 4/5 | 3/4 | Specific and mostly grounded, but more poetic than documentary. | Accurate details like the dual-tone facade and barred windows; decent documentary tone. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 4/4 | 4/3 | 3/3 | Good objects; lamp casting light is uncertain and prose slightly decorative. | Ends too editorial for deadpan; hallucinates lamp is woven and lit. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3/4 | 4/3 | 4/4 | Noir mood works; claims stay mostly visible but fairly generic. | Good noir mood but hallucinates an intricate, glowing lamp. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3/4 | 4/3 | 1/2 | Mostly grounded, but lacks nature-documentary framing. | Fails nature doc voice; hallucinates unlit lamp casting shadows. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 5/5 | 5/5 | Highly specific, accurate, and flatly observational. | Highly accurate specifics, correctly notes unlit lamp, perfect deadpan. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen3-VL-8B-Instruct | noir | 4/5 | 4/5 | 5/5 | Strong noir voice; face reflection wording slightly overstates. | Superb noir voice grounded perfectly in the actual visual elements. |
+| img-46AC-B1CB-06-3 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 4/5 | 3/3 | 2/3 | Invents rings of light; more poetic than documentary. | Animates objects instead of humans; hallucinates concentric lamp light. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 4/4 | 3/2 | 4/4 | Good specifics, but invents Coca-Cola bottle and sipping. | Mistakes Coca-Cola napkin dispenser for a bottle and hallucinates sipping action. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3/3 | 3/2 | 2/3 | Invents Coca-Cola bottle; noir voice is weak. | Hallucinates a Coca-Cola bottle; noir voice is somewhat generic. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3/4 | 4/3 | 2/4 | Mostly grounded, but style is not documentary-like. | Misidentifies the glasses of beer as a bottle. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 5/5 | 5/5 | Strong visible details and flat delivery. | Exceptional accuracy and specificity; perfectly maintains a deadpan tone. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen3-VL-8B-Instruct | noir | 5/5 | 3/4 | 4/5 | Strong voice, but beer counts/status and brand claim are wrong. | Great style but falsely claims the beer brand isn't in the frame. |
+| img-46AC-B1CB-06-4 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 3/5 | 2/4 | 2/5 | Overwritten, invents motion and untouched drinks. | Invented head movement and falsely claimed the partially empty drinks were untouched. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 3/3 | 3/2 | 4/4 | Mostly visible setup, but cap and sunglasses appear invented. | Hallucinates cap and sunglasses on the reflected person, likely confusing it with the sticker. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3/2 | 4/4 | 4/5 | Grounded scene with decent noir mood, limited concrete specifics. | Captures noir atmosphere well but relies on generic descriptions rather than specific image details. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 2/3 | 2/4 | 2/2 | Invents swaying leaves, breeze, and cool gray backdrop. | Fails the nature doc prompt, providing poetic observation instead of clinical species analysis. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 5/5 | 5/5 | Strong visible specifics: sticker, QR code, pipes, hanging lights. | Flawless deadpan delivery with highly accurate, specific observations of sticker text and interior details. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen3-VL-8B-Instruct | noir | 4/5 | 3/5 | 5/5 | Noir lands, but infers language meaning and shadow drama. | Masterful noir voice that brilliantly integrates specific real-world details like the foreign posted hours. |
+| img-46AC-B1CB-06-5 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 3/4 | 4/5 | 3/3 | Mostly grounded, but nature-documentary voice is weak and vague. | Good specifics, but the voice is too poetic and misses the detached clinical tone. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 3/4 | 3/2 | 3/3 | Good ceiling details, but invents seated person and table activity. | Hallucinates a person sitting at a table in the background; plaid is in foreground. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 2/2 | 4/4 | 4/4 | Mostly grounded, but sparse and ignores visible room specifics. | Captures the noir mood well but lacks specific details from the room. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3/3 | 4/5 | 1/2 | Grounded room details, but not nature-documentary narration. | Fails to capture the nature documentary persona, sounding more like a generic description. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 4/5 | 4/5 | Strong specifics; plaid shirt and pillow relation seem misread. | Excellent specific details and perfect, matter-of-fact deadpan delivery without hallucinations. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen3-VL-8B-Instruct | noir | 3/5 | 4/5 | 5/5 | Noir lands; concrete claims mostly check, with speculative gendered simile. | Evocative noir style grounded perfectly in the actual visual elements of the room. |
+| img-46AC-B1CB-06-6 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 3/4 | 3/4 | 1/5 | Poetic, not nature-doc; overstates unseen subject and plural lanterns. | Good documentary tone, but incorrectly claims the subject is unseen when legs are visible. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 5/4 | 5/3 | 4/4 | Accurate visible details; slightly more polished than flat deadpan | Hallucinates straps hanging over the edge. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3/3 | 2/1 | 3/5 | Invents ajar oven door and towel; noir only partly lands | Completely hallucinates an open oven and towel. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 2/2 | 4/4 | 1/2 | Mostly grounded but generic, not nature-documentary style | Reads like real estate copy, not nature documentary. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 5/4 | 5/5 | Specific, accurate, and flatly observational | Accurate and deadpan, but misses the leaning shelf. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen3-VL-8B-Instruct | noir | 5/5 | 4/4 | 5/5 | Strong noir with real TEKA detail; leather is uncertain | Excellent noir style and spots the TEKA logo. |
+| img-46AC-B1CB-06-7 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 4/4 | 4/4 | 2/2 | Grounded specifics, but poetic noir-adjacent rather than nature documentary | Tone is poetic and reverent, not nature documentary. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 4/4 | 3/2 | 4/4 | Good specifics, but men are not at separate tables. | Men are at the same table, not separate ones. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3/3 | 4/2 | 3/4 | Mostly grounded, but noir voice is mild. | Hallucinates dappled shadows and motion blur. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 3/2 | 3/3 | 2/2 | Generic, invents breeze and whispering ambiance. | Fails the nature doc voice; just sounds peaceful. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 4/3 | 5/5 | Strong visible details; passing cars are inferred. | Catches upside-down logo, but hallucinates dappled shadows. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen3-VL-8B-Instruct | noir | 3/3 | 2/2 | 5/5 | Strong noir, but invents drinks, roar, flickering streetlamp, damp pavement. | Hallucinates night tropes like yellow glow and damp pavement. |
+| img-46AC-B1CB-06-8 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 4/4 | 4/5 | 4/4 | Grounded and observant, though more poetic than documentary. | Accurate details with a solid observational documentary voice. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-7B-Instruct | deadpan | 4/3 | 3/2 | 3/4 | Good visible details, but invents readable Café sign. | Hallucinates 'Café' text on the sign. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-7B-Instruct | noir | 3/2 | 4/4 | 4/5 | Grounded mood, but light on concrete photo specifics. | Generic details but captures the moody noir tone well. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen2.5-VL-7B-Instruct | nature_doc | 2/2 | 2/2 | 2/4 | Invents plant-tending and a glass ceiling. | Hallucinates a glass ceiling and tending to a plant. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen3-VL-8B-Instruct | deadpan | 5/5 | 5/5 | 5/5 | Accurate, specific, and flatly observational. | Extremely accurate details with a perfectly flat, observant tone. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen3-VL-8B-Instruct | noir | 5/4 | 3/4 | 5/5 | Strong noir, but invents dust, smells, and cigarette traces. | Strong noir voice with great specifics; minor atmospheric embellishments. |
+| img-46AC-B1CB-06-9 | Qwen/Qwen3-VL-8B-Instruct | nature_doc | 5/5 | 4/5 | 2/2 | Specific and mostly grounded, but not nature-documentary voice. | Highly accurate details, but voice sounds more like architectural commentary. |
+
+## Method
+
+Same loop as run-004/005 (docs/eval/run-004-scored.md), run twice: photos relayed from the Spark, HEIC→JPEG, one judge call per photo with all six narrations + rubric, strict-JSON S/G/V, aggregated offline. Judge B uses the identical prompt with the photo opened from disk instead of attached.

docs/field-notes-small-cuts.md

@@ -0,0 +1,97 @@
+# Small Cuts: Building a narrator for the moments that just happened
+
+Small Cuts started from a simple product feeling: what if ordinary first-person moments could be
+given the treatment of a tiny film? Not a chatbot, not a camera filter, not a social caption after
+the fact. A narrator in your ear, speaking one dry, cinematic line about the thing that just
+happened, and leaving behind a short cut you can replay.
+
+The result is a glasses-to-ear-to-Space loop. Ray-Ban Meta glasses capture first-person image
+frames. An iPhone sends selected moments to a private Mac Studio engine. A small vision-language
+model writes a grounded deadpan narration, Kokoro turns it into speech, the wearer hears it, and
+the same finished POV cut appears in a Hugging Face Gradio Space with video, voice, captions, title,
+and library thumbnail.
+
+## The product shape
+
+The important decision was to keep the Space as the public product surface, not the capture path.
+The Space is a little streaming theater: the current cut plays in a 9:16 stage, the voice-over is
+the master clock, captions follow the audio, and the library shows real POV frames instead of
+generic generated cards.
+
+The glasses path stays private. During the live demo, the iPhone writes to the local engine over
+Tailnet. Public viewers and the Space only read finished scenes through a Cloudflare read gate:
+`GET /v1/scenes`, `GET /v1/scenes/stream`, and `/media/*`. The public hostname blocks the
+WebSocket capture path and visibility writes. That split is less glamorous than making everything
+public, but it is the right product boundary: private capture, public replay. For the hackathon
+demo this rides on a Cloudflare tunnel; a production version would turn that into durable auth,
+domain, and publishing controls rather than opening the capture path.
+
+## Why small models worked
+
+The model does not need to understand a whole movie. It needs to make one grounded observation from
+a selected frame and say it with taste. The current narrator uses Qwen3-VL-8B through llama.cpp for
+the live local path, with a prompt that is intentionally strict: only visible or directly inferable
+facts, no invented objects, no fake sounds, no unsupported drama. Kokoro handles the voice.
+
+That constraint became the voice of the product. Small Cuts is not trying to explain the world. It
+is trying to notice the one detail that makes a moment feel like a scene.
+
+## What was harder than expected
+
+The first hard part was synchronization. The native Gradio audio component is useful plumbing, but
+it cannot be treated as a whole custom player. The working solution was to make the browser's audio
+element the single playback clock and have the muted video, captions, and progress bar follow it.
+That also avoids pretending that browsers allow audible autoplay. The cut starts when the viewer
+clicks play.
+
+The second hard part was making the library feel alive. Title cards are cinematic, but a grid of
+title cards makes the product look like generated slides. Real POV thumbnails make it feel like a
+channel of lived moments. The engine now stores a selected key frame as `frame.jpg`, writes a short
+browser-playable `clip.mp4`, and serves both through the same media contract as the voice.
+
+The third hard part was latency and resilience. Scene audio must reach the wearer before the viewer
+storage work can matter. The engine sends the `SceneAudio` frame first, then stores the scene media
+for the Space. Supplemental frames for the viewer clip are useful, but they must never block the
+in-ear experience.
+
+## What the public Space shows
+
+The Space currently opens on a five-cut generated library of real first-person glasses moments.
+Each cut was sent through the regular WebSocket path with one selected mark frame plus a short
+POV buffer:
+
+- `A hand, palm up, blocks the camera's view, revealing a...`
+- `The camera lingers on a concrete alleyway at night, the...`
+- `The car door is open, revealing a black interior and a...`
+- `The driver grips the steering wheel with both hands, thumbs...`
+- `The yellow circle with numbers is painted on the floor...`
+
+Those cuts make the channel non-empty for first-time visitors without using human-written
+narration as the product sample. The live demo path uses the same public read surface: when a new
+local engine scene is created, the Space polls the read gate, fetches the media files, and replays
+the just-happened cut with synced video, audio, captions, and title.
+
+## What is v1, and what comes next
+
+This version sends image frames, not source audio. That is intentional for the hackathon build:
+source sound is not needed for the narrator concept, and excluding it keeps privacy and contracts
+simpler.
+
+The current live model reasons over sampled frames from an intentional Action-to-Cut take. The
+viewer can show a short POV clip assembled from those supplemental frames, but full video reasoning
+is a v2 direction. The next version should buffer a low-resolution clip directly into the Space,
+generate narration fragments with timestamps, and let the finished cut feel even closer to what the
+wearer experienced.
+
+Title generation now shares the model call with narration: the model returns a short grounded title
+and the spoken narration together, with deterministic title derivation kept as a fallback for
+malformed output. A later contract can add caption timing and confidence in the same structured
+response.
+
+## Why this matters
+
+The best version of Small Cuts is not a camera feature. It is a private narrator that notices the
+little cinematic beats a person usually walks past, says one honest line in the ear, and leaves
+behind a tiny film that feels like it happened on purpose.
+
+That is the small adventure: not making the model bigger, but making the moment feel seen.

docs/hackathon-rules.md

@@ -0,0 +1,111 @@
+# Build Small Hackathon — Rules Summary (verified 2026-06-12)
+
+Facts verified from primary sources:
+
+- **Field Guide** (official): https://huggingface.co/spaces/build-small-hackathon/field-guide
+  — read raw `details.md`, `faq.md`, `partner-resources.md`, and the site source
+  (`src/lib/data/content.ts`, `src/lib/readme.ts`) on 2026-06-12.
+- Organizer message in Discord (relayed by Carlos in issue #22, 2026-06-12).
+- Registration emails from `yuvraj@huggingface.co` (2026-06-03/04). Carlos **is registered**.
+- Official org: https://huggingface.co/build-small-hackathon (~1,916 members, 365 spaces on 2026-06-12).
+
+## Identity
+
+- **Name:** Build Small Hackathon — "Small Models, Big Adventures"
+- **Hosts:** Gradio · Hugging Face. Sponsors: OpenAI, NVIDIA, OpenBMB, Cohere, BFL, Modal, JetBrains.
+- **Hack window:** June 5 – June 15, 2026.
+- **Deadline (CONFIRMED, organizer in Discord): June 15, 23:59 UTC.**
+  The Space must be **public** and **moved under the org** by then — both have been
+  forgotten by participants in past events; ours is already created (see below).
+
+## Hard constraints
+
+1. **Model size:** every individual model **under 32B total parameters** (combinations fine;
+   each model's *total* — not active — count is what matters).
+2. **Platform:** Gradio app hosted as a Space under `build-small-hackathon/` (Docker allowed
+   only if the interface is still a Gradio Space).
+3. **Demo video:** required — judges must be able to evaluate even if GPU/API limits block a
+   live run. Upload to YouTube, as a file in the Space, or anywhere public.
+4. **Social post:** required — one post showcasing the app, **linked from the Space README**.
+5. **ZeroGPU limit:** max 10 ZeroGPU apps per user (we use 1).
+
+## Submission mechanics (CONFIRMED)
+
+Tracks/badges are claimed via **namespaced tags in the Space README frontmatter**
+(`src/lib/readme.ts` is the official parser):
+
+```yaml
+tags:
+  - track:wood          # or track:backyard
+  - sponsor:openai      # sponsor prizes you're entering
+  - achievement:offgrid # self-declared badges, verified at judging
+```
+
+Checklist from the Field Guide "submitting" page:
+
+- [x] Join the org (macayaven is a member)
+- [x] Space exists under the org: https://huggingface.co/spaces/build-small-hackathon/small-cuts
+      (public, RUNNING placeholder since 2026-06-12; real app lands in M3, #14)
+- [ ] Upload the real app (M3)
+- [ ] Demo video — public link (M4)
+- [ ] Social post — link it in the Space README (M4)
+- [ ] README: track/achievement tags + short write-up of idea, how it was built, tech used
+- [ ] Run the **submission analyzer** before the deadline (how-to: youtube.com/watch?v=1iR65sq0HmA)
+
+## Tracks
+
+- **Backyard AI** (`track:backyard`) — practical, problem-solving, daily-life apps.
+- **Thousand Token Wood** (`track:wood`) — whimsical, delightful, AI-native fun.
+
+**Small Cuts targets `track:wood`** (tag already on the placeholder Space).
+
+## Bonus achievements (self-declared tags, no prize, verified at judging)
+
+| id | name | our status |
+|---|---|---|
+| `offgrid` | Off the Grid — no cloud APIs at runtime | ✅ architecture complies (declared) |
+| `offbrand` | Off-Brand — custom UI past default Gradio | ✅ custom theme landed in #13 (declared) |
+| `llama` | Llama Champion — llama.cpp runtime | ⏳ pending M3 LlamaCppBackend |
+| `fieldnotes` | Field Notes — blog post / write-up | ⏳ draft created: hf.co/blog/macayaven/small-cuts-field-notes |
+| `sharing` | Sharing is Caring — agent trace on the Hub | 💡 optional: publish the dual-judge eval artifacts as a dataset |
+| `welltuned` | Well-Tuned — published fine-tune | ❌ not planned pre-deadline |
+
+These also feed **Bonus Quest Champion** ($2,000 — most bonus criteria met).
+
+## Prized bonus badges
+
+- Off-Brand $1,500 (judged; "gr.Server is your friend" — bar is higher than a theme)
+- **Tiny Titan $1,500 — models must be ≤ 4B. We are NOT eligible (8B narrator).**
+- Best Demo $1,000 · Best Agent $1,000 · Bonus Quest Champion $2,000 · Judges' Wildcard $1,000
+
+## Sponsor prizes relevant to us
+
+- **OpenAI ($10k pool):** requires **Codex-attributed commits** in the Space history or a
+  linked GitHub repo. We genuinely use Codex for implementation but commits are not
+  Codex-attributed. If we enter `sponsor:openai`: add Codex attribution to future commits
+  and describe the Codex workflow in the README.
+- **Modal ($20k credits prize):** requires using Modal for **development or runtime** + a
+  README note. FAQ explicitly confirms development-side Modal use (e.g. training/eval)
+  **stacks with `offgrid`** — offgrid is about the app's runtime only.
+- OpenBMB (MiniCPM) / NVIDIA (Nemotron): different model families — not pursuing.
+
+## Modal credits (participant perk — answered 2026-06-12)
+
+Carlos holds **$250 Modal credits** from registration (plus $20 HF credits, expire
+2026-07-31). **No Modal usage is planned in the current architecture**: dev/eval runs on
+the Spark + Mac Studio, runtime is ZeroGPU. Using Modal would only matter for the Modal
+prize (development-side use is rule-compatible with offgrid), but with a 3-day runway the
+recommendation is: ship M3–M5 first; only port an eval/fine-tune job to Modal if time
+remains. Redemption status of the credit code: Carlos to confirm.
+
+## Implications for architecture (unchanged, re-verified)
+
+- The **Space is the judged artifact** — Mac Studio / Spark / Tailnet are dev-only.
+- `offgrid` + `llama` ⇒ all-local inference inside the Space (ZeroGPU + llama.cpp CPU fallback).
+- Ray-Ban Meta glasses are a capture device for the demo video, not runtime infra.
+- ZeroGPU is shared: graceful CPU fallback + short inference. 40 min/day quota as org member.
+
+## Open questions
+
+1. Team rules (Topi/nojose registration status) — only matters if co-credit is wanted.
+2. Modal credit code redemption status — Carlos.

docs/implementation-plan.md

@@ -0,0 +1,53 @@
+# Implementation Plan (deadline: June 15, 2026)
+
+## M0 — Bootstrap ✅ (June 11, this session)
+
+- Repo scaffolding, CI (ruff + pytest + gitleaks), docs, KB notes.
+- Vertical slice: Gradio app runs end-to-end with the **mock backend**
+  (image → director style → deterministic narration → title card).
+- Pluggable backend interface with `transformers` and `llama_cpp` stubs wired.
+
+## M1 — Real narration (June 12)
+
+- Eval harness ✅ (`src/small_cuts/eval.py`): fixed set of ~12 personal photos ×
+  candidate VLMs (SmolVLM2-2.2B, Qwen2.5-VL-3B/7B, gemma-3-4b-it) × 3 styles.
+  **Run on DGX Spark** (CUDA — results transfer to ZeroGPU; 128GB fits all
+  candidates without juggling):
+  ```bash
+  git clone https://github.com/macayaven/small-cuts && cd small-cuts
+  uv sync --extra local
+  uv run python -m small_cuts.eval --images ~/eval-photos --out eval-report.md
+  ```
+  Score the report for specificity/groundedness/voice (rubric included).
+- Pick the model; tune the system prompt + per-style few-shots.
+- Acceptance: 8/12 eval images produce narration a human laughs or nods at,
+  zero hallucinated objects in 10/12.
+
+## M2 — Performance layer (June 13)
+
+- TTS (Kokoro-82M first candidate) behind the same backend pattern.
+- Title-card renderer (PIL) + custom Gradio theme/CSS → **Off-Brand** quest.
+- Streaming text reveal in UI.
+
+## M3 — Space live (June 13–14)
+
+- Create `build-small-hackathon/small-cuts` Space; ZeroGPU + CPU fallback.
+- Decide llama.cpp path (Llama Champion) based on VLM GGUF stability.
+- Load test: 3 concurrent narrations; cold-start measurement.
+
+## M3.5 — Continuous Live Mode (stretch, only if M0–M3 green)
+
+- Phone camera → Gradio streaming → scene-change gate → narration → streamed TTS
+  → played through Ray-Ban Metas via Bluetooth (audio path itself is free once
+  M2 TTS exists — use it in the demo video regardless).
+
+## M4 — Submission assets (June 14)
+
+- Film POV footage with Ray-Ban Metas; cut ≤90s demo video on Mac Studio.
+- Social post draft; Field Notes blog post draft (→ **Field Notes** quest).
+- Stretch only if green: clip input, day-reel, LoRA fine-tune (**Well-Tuned**).
+
+## M5 — Submit (June 15, morning — do not use the deadline day as buffer-free)
+
+- Final smoke test from both phones; submit Space + video + post.
+- Verify quest claiming mechanism and apply tags/metadata.

docs/product-strategy.md

@@ -0,0 +1,124 @@
+# Small Cuts — Product Strategy
+
+## Essence of the experience
+
+In *The Invention of Lying*, the world is narrated by people who can only say
+what is true — and the comedy and tenderness come from hearing ordinary moments
+described with omniscient, cinematic certainty. **Small Cuts gives you that
+narrator.** You show it a moment of your life; it tells you what kind of scene
+you are actually in.
+
+The emotional target is the gap between how a moment *feels* from inside and how
+it *reads* from outside: a narrator that is observant, specific, a little too
+honest, and unmistakably cinematic.
+
+## How the inspiration translates into UX
+
+1. **You bring a moment** — a photo or short clip from your phone, webcam, or
+   Ray-Ban Meta glasses footage.
+2. **You choose a director** — narration styles are *directors' cuts*: Noir
+   Detective, Nature Documentary, Trailer Voice, Deadpan Omniscient
+   (the *Invention of Lying* default), Telenovela, Wes Anderson Symmetrist…
+3. **The narrator speaks** — a small VLM looks at the scene and writes 2–4
+   sentences of narration grounded in what is actually visible; a small TTS
+   model performs it; the app renders a title card so the result is shareable.
+4. **One tap to re-cut** — same moment, different director. The re-cut is the
+   delight loop and the social loop ("show a friend" is literally the Track 2
+   judging criterion).
+
+## What the Director's Cut trajectory gets right
+
+- The core concept (cinematic POV narration of lived moments) is original and
+  emotionally strong — worth keeping intact.
+- The pivot toward Gradio (`wearables-gradio-poc`) correctly read the hackathon
+  rules: the judged artifact must be a Gradio Space.
+- The local-model option (Qwen3-Omni) was prescient: it is exactly what the
+  "Off the Grid" quest rewards.
+
+## What it gets wrong / under-exploits (unverified where noted)
+
+- **iOS companion app is unjudgeable.** Judges run a Space; a Swift app for
+  Ray-Ban Display can't be evaluated and consumes the remaining 4 days.
+- **Gemini Live (cloud) breaks the rules' spirit and the best quests.**
+  Cloud narration forfeits "Off the Grid" and weakens the small-model story.
+- **Glasses-as-infrastructure is fragile.** Device pairing on stage/video is a
+  demo killer; glasses should be a *capture source*, not a dependency.
+- (Unverified — peer notes unreachable from this environment: the exact state
+  of `wearables-gradio-poc` may already address some of this.)
+
+## Improved concept: why Small Cuts can beat the original
+
+- **Zero-friction for judges:** open the Space, drop any photo, get narrated.
+  No hardware, no account, no pairing.
+- **Rule-maximal:** ≤32B local models inside the Space → eligible for Off the
+  Grid, Llama Champion, Tiny Titan, Off-Brand, Field Notes on top of Track 2.
+  Quests are scoring multipliers; the original trajectory could claim almost none.
+- **The glasses still star** — in the demo video: Carlos walks through Madrid
+  wearing Ray-Ban Metas, the footage flows into the Space, and his day comes
+  back narrated. Emotional wow preserved, fragility removed.
+- **Small-model fit is honest:** scene → short narration is a task a 2–8B VLM
+  genuinely does well; nobody needs GPT-class weights to be wry about your coffee.
+
+## Core demo flow (the video, ≤90s)
+
+1. POV clip from Ray-Ban Metas: ordinary morning moment (coffee, street, desk).
+2. Cut to the Space: frame dropped in, "Deadpan Omniscient" selected.
+3. Narration appears word-by-word and is *spoken*: specific, true, funny.
+4. Re-cut as "Noir" → same moment, new genre. Show a second moment.
+5. Closing card: "Every model under 32B. Everything runs in this Space."
+
+## Minimum lovable submission (must ship by June 14)
+
+- Space under `build-small-hackathon/` org: image → styled narration → TTS audio
+  → shareable title card. 6 director styles. Custom cinematic theme.
+- Local VLM (≈2–8B) + local TTS, ZeroGPU with CPU fallback.
+- Demo video + social post + README.
+
+## Live Mode — narration in your ears, on the glasses (confirmed direction 2026-06-11)
+
+Carlos confirmed the strategy with one addition: if technically feasible, the
+narration should reach the wearer **in real time through the glasses**. Two
+layers, in order of cost:
+
+1. **Audio out through the glasses — nearly free.** Ray-Ban Metas pair to the
+   phone as Bluetooth audio. The Space's TTS, played in the phone browser,
+   plays through the glasses' open-ear speakers with zero extra code. The demo
+   video can honestly show "hearing your life narrated in the glasses" the
+   moment M2 (TTS) lands.
+2. **Continuous Live Mode — the real work (stretch, M3.5).** Phone camera
+   streams frames into the Space (Gradio streaming/WebRTC); a scene-change
+   detector samples a frame every few seconds and narrates only when the scene
+   meaningfully changes (otherwise the narrator babbles); TTS streams back and
+   plays through the glasses. Needs rate limiting to respect ZeroGPU quotas.
+3. **Glasses-camera capture (post-hackathon).** Real-time access to the
+   glasses' own camera requires the Meta Wearables Device Access Toolkit
+   (developer preview, iOS) — the original `directors-cut` territory.
+   Feasibility/timeline **unverified**; out of scope before June 15.
+
+## Stretch (only after MLS is live)
+
+- Continuous Live Mode (see above) — the highest-magic stretch.
+- Short-clip input (sample frames → narrate the sequence as a scene).
+- "Day reel": multiple moments stitched into one narrated cut.
+- **Well-Tuned:** LoRA fine-tune of the narrator voice on a style corpus,
+  published on the Hub.
+- llama.cpp runtime path for the Llama Champion badge (if VLM+GGUF is stable).
+
+## Riskiest assumptions
+
+1. A ≤8B VLM produces *specific, grounded* narration (not generic captions) —
+   prompt + few-shot needs early validation.
+2. ZeroGPU latency stays demo-acceptable under load; CPU fallback is tolerable.
+3. TTS quality carries the "performed narrator" feeling at small size.
+4. Space-under-org submission mechanics are as simple as they look (unverified).
+
+## First implementation milestones
+
+| # | Milestone | Target |
+|---|---|---|
+| M0 | Repo bootstrap: CI, lint, tests, docs, mock-backend Gradio app runs | **done in this session** |
+| M1 | Real VLM narration end-to-end locally (eval 2–3 candidate models, pick one) | June 12 |
+| M2 | TTS + title card + custom theme (Off-Brand) | June 13 |
+| M3 | Space live under org (ZeroGPU + CPU fallback), llama.cpp path decision | June 13–14 |
+| M4 | Demo video filmed/cut, social post, Field Notes blog draft | June 14 |
+| M5 | Submit + buffer day | June 15 |

docs/product/architecture.md

@@ -0,0 +1,152 @@
+# Small Cuts — Product Architecture (the real-time loop)
+
+> Scope: the **product** (post-hackathon #29). The hackathon Space remains
+> described by [docs/architecture.md](../architecture.md) — it is the public
+> demo shell of this architecture, with uploads standing in for the live
+> glasses stream.
+
+## Current state (2026-06-12)
+
+Batch pipeline, fully working: photo/clip upload → frame pick → Qwen3-VL-8B
+narration (ZeroGPU or llama.cpp) → title card + on-demand Kokoro TTS. Live on
+the hackathon Space. **No streaming, no session memory, no library, no mobile
+app yet** — those are exactly what the three teams build.
+
+## Components & teams
+
+| Component | Owner | Optimization goal |
+|---|---|---|
+| **Capture apps** (iOS/Android + Meta Wearables DAT) | Team Mobile | minimize signal sent, maximize moment quality, real-time delivery |
+| **Narration engine** (home node: llama.cpp + Kokoro + session context) | Team Inference | prompt + session context + frames → Wes-Anderson-grade voice-over; max quality, min latency |
+| **Viewer platform** (Gradio app: live view + library) + hackathon Space | Team Space | feel like a reference live-streaming platform (#28) |
+
+Coordination: contracts below are the only coupling. Each team optimizes
+freely inside its boundary; **contract changes are PRs labeled
+`contract-change` and require orchestrator review**.
+
+## The temporal diagram
+
+One narrated moment, end to end ("scene-gated discrete pipeline", see D1):
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant G as Glasses (DAT)
+    participant M as Mobile app
+    participant E as Engine (home node)
+    participant V as Viewer (Gradio)
+    participant L as Library
+
+    Note over G,M: continuous camera session (DAT stream)
+    G->>M: video frames (SDK callback)
+    M->>M: scene gate + frame select + downscale ≤1024px
+    M->>E: MomentEnvelope (WS) — frames + context metadata
+    E->>E: session context → prompt build
+    E->>E: narrate (llama.cpp, warm 2–4.5s)
+    E->>E: TTS (Kokoro, ~3.5s)
+    E-->>M: SceneAudio (WS) — voice-over
+    M->>G: play in ear (BT speakers)
+    E-->>V: NarratedScene event (SSE) — live view
+    E->>L: append NarratedScene (visibility: private)
+    Note over V,L: user revisits in library → share / make public / go public-live
+```
+
+**Latency budget v1** (gate fires → voice in ear), measured numbers in
+parentheses:
+
+| Stage | Budget |
+|---|---|
+| Phone: gate + select + encode + send | ≤ 1.0 s |
+| Engine: narration, warm llama.cpp on Metal | ≤ 4.5 s (measured 2.0–4.2 s) |
+| Engine: TTS, warm Kokoro CPU | ≤ 4.0 s (measured 3.6 s) |
+| Return + playback start | ≤ 0.5 s |
+| **End-to-end v1, warm p50 target** | **≤ 10 s** |
+| End-to-end p90 (queueing, cold worker, retries) | ≤ 15 s |
+| Stretch (sentence-pipelined narration→TTS, streamed audio) | ≤ 6 s |
+
+Honesty notes (from adversarial review): the phone-side stage and queueing
+are UNMEASURED — Team Mobile's first deliverable includes real upload
+numbers, and `sent_at`/`latency_ms` exist in the contracts precisely to
+attribute every millisecond. **A ~10 s voice is retrospective by nature**:
+the narrator comments on the moment just past — the deadpan-omniscient
+voice is written for exactly that register, the gate keeps moments sparse,
+and the ≤ 6 s stretch (a future MAJOR contract version with real chunk
+semantics — not a v1 toggle) closes the rest. Streamed audio is a
+cross-team feature: Mobile must build buffered playback for it; it goes
+through contract-change review, not a silent engine-side switch.
+
+## Decisions (status: adopted unless challenged via PR)
+
+- **D1 — Unit of work is a gated Moment, not continuous video.** The phone
+  runs the cheap signal processing (scene-change gate — #15's M3.5 work
+  becomes mobile-side; frame selection; downscale to ≤1024px longest side,
+  matching the verified Qwen-VL vision-token constraint) and emits discrete
+  `MomentEnvelope`s. Rationale: bandwidth (the "optimize signal sent" goal),
+  battery, and the validated single-frame narration strategy. Continuous
+  streaming later = same contract at higher envelope frequency.
+- **D2 — Transport is one bidirectional WebSocket per session** (phone ↔
+  engine, over the tailnet): envelopes up, audio + acks down. WebRTC only
+  becomes interesting if D1 flips to raw media. Team Mobile may challenge
+  with measurements.
+- **D3 — The engine lives on the home node (Mac Studio), llama.cpp-first.**
+  Measured: warm narration 2.0–4.2 s on Metal — faster than ZeroGPU warm.
+  The HF Space is the public demo shell, not the product engine.
+- **D4 — Audio returns as one complete clip per scene (v1).** Kokoro clips
+  are 5–15 s; streaming TTS buys ~2 s at real complexity cost AND requires
+  mobile-side buffered playback — so it is a future MAJOR contract version
+  decided cross-team, not an engine-side toggle.
+- **D5 — Session context lives engine-side; its v1 scope is the clip.** The
+  phone sends only moment metadata (time, optional location label, optional
+  user hint); the engine owns the context and prompt construction (Mobile
+  never sees prompts; Inference never sees raw streams). **Within a clip the
+  narration is built chunk-by-chunk** — each moment narrated in sequence, every
+  chunk carrying the chronological context of the clip's earlier chunks, so the
+  clip reads as one coherent, non-repeating little story rather than a string of
+  disconnected captions. The cadence is **human-digestible**: each chunk is short
+  enough to land as *recent past* (what just happened) — never racing ahead to
+  narrate a future event — at a pace a listener can follow and retain, and that
+  the viewer's subtitles mirror line-for-line. Cross-clip / day-timeline memory
+  (→ #20) is a later extension; v1 is **intra-clip only** (no cross-clip memory).
+- **D6 — Library is engine-side storage** (filesystem media + sqlite index),
+  entries are `NarratedScene`s with visibility `private | shared | public`
+  (default private). The viewer reads; it never writes media.
+- **D7 — Viewer subscribes over SSE** to the engine's scene stream; library
+  entries and live events share the same `NarratedScene` schema (`seq` +
+  `Last-Event-ID` for resume). The viewer's only write is visibility
+  metadata via `PATCH /v1/scenes/{id}` — never media. "Public live" later =
+  the same stream behind an auth/visibility check; `owner`/`share_token`
+  are reserved in the schema now (v1 engines are single-user on the
+  tailnet).
+- **D8 — Backpressure: queue depth ≤ 1, coalesce-to-newest.** The engine
+  acks every envelope at admission (`accepted | duplicate | rejected |
+  dropped_coalesced`), emits busy/ready status frames, and replaces a
+  queued un-started moment with a newer arrival. The phone suppresses its
+  gate while the engine is busy. Narrating stale moments is worse than
+  skipping them.
+- **D9 — Playback freshness.** `SceneAudio` carries `play_by`
+  (default created + 60 s); the app never overlaps clips and drops any
+  clip whose deadline passed before playback started. Failures arrive as
+  first-class error frames (stage, code, retryable) on both the session
+  socket and the viewer stream — consumers render an honest timeline, not
+  just the success path.
+
+## Contracts
+
+Defined and enforced in [docs/contracts/](../contracts/README.md):
+
+1. **MomentEnvelope** (Mobile → Engine) — `moment.schema.json`
+2. **ControlFrame** ack/error/status (Engine → Mobile) — `control.schema.json`
+3. **NarratedScene** (Engine → Viewer & Library) — `narrated-scene.schema.json`
+4. **SceneAudio** (Engine → Mobile) — `scene-audio.schema.json`
+5. **Session context spec** (engine-internal, but the metadata mobile must
+   supply is part of MomentEnvelope) — in the contracts README
+
+Contract set 1.1.0 incorporates the adversarial review (Codex GPT-5 +
+Gemini 3.1 Pro, both "needs_changes" → all blockers resolved): admission
+acks, error frames, backpressure, freshness deadlines, SSE resume,
+visibility-mutation endpoint, lockstep versioning policy.
+
+Enforcement: JSON Schemas are the source of truth; every team's CI validates
+its golden samples against them (`tests/test_contracts.py` pattern); schemas
+are semver'd in their `$id`; breaking changes bump major and require a
+migration note in the PR.

docs/product/rehearsal-2026-06-12.md

@@ -0,0 +1,47 @@
+# Dress rehearsal — 2026-06-12
+
+- Engine: `ws://127.0.0.1:8077` (session `rehearsal-20260612T183149Z`)
+- Video: `/Users/carlos/small-cuts-fixtures/videos/IMG_8175.MOV` — 3 gated moments, style `symmetrist`
+- Narrator: `Qwen/Qwen3-VL-8B-Instruct-GGUF` via `llama_cpp`
+- TTS: `hexgrad/Kokoro-82M`
+
+## Per-moment latency
+
+Engine numbers come from the persisted scene's `engine.latency_ms`; wall is the
+client-measured send→SceneAudio round trip (includes WS transfer + queueing).
+
+| # | Narration (first 80 chars) | narration_ms | tts_ms | total_ms (engine) | wall_ms (client) | narration ≤4500 | tts ≤4000 |
+|---|---|---|---|---|---|---|---|
+| 1 | The man in the foreground holds a glass tilted at precisely the angle a bartende | 9198 | 7657 | 16855 | 16935 | FAIL | FAIL |
+| 2 | The man’s hand rests just above his temple, fingers brushing the thick black fra | 3701 | 2022 | 5723 | 5792 | PASS | PASS |
+| 3 | The man’s hand hovers over a bottle with a coral cap, its label blurred like a f | 4226 | 2533 | 6759 | 6850 | PASS | PASS |
+
+## Budget comparison (docs/product/architecture.md, Latency budget v1)
+
+Warm = moments after the first; moment 1 pays the llama-server spawn and
+Kokoro weight load once per engine process.
+
+| Budget line | Target | Measured (warm max) | Verdict |
+|---|---|---|---|
+| Narration, warm llama.cpp | ≤ 4500 ms | 4226 ms | PASS |
+| TTS, warm Kokoro | ≤ 4000 ms | 2533 ms | PASS |
+| End-to-end warm p50 (client wall) | ≤ 10000 ms | 6321 ms | PASS |
+
+Cold first moment: narration 9198 ms, tts 7657 ms, wall 16935 ms (one-time per engine process).
+All-moments e2e p50 including the cold first moment: 6850 ms.
+Moments narrated: 3/3; audio: 40.8s, 34.4s, 43.9s.
+
+## Full narrations
+
+**Moment 1** (scene `ba7978ea-46e5-4117-a5c6-5f91af79e9b2`):
+
+> The man in the foreground holds a glass tilted at precisely the angle a bartender might approve, its rim catching the amber glow of the single, perfect circle of light above. Behind him, the bar’s menus—Cocktails and Shots—hang like miniature, illuminated maps, their text sharp against the dark wood. A neon sign to the left, glowing in a warm, slightly garish red, reads “LOVE, LOVE WILL APART” in a font that looks like it was cut from a child’s coloring book. The scene is framed with the quiet symmetry of a still life: the man’s glasses, the glass, the light, the menus, the sign—all arranged with the careful, slightly off-kilter precision of a Wes Anderson storyboard.
+
+**Moment 2** (scene `20f0dfb0-b2c7-4de5-912d-a1da648abdaf`):
+
+> The man’s hand rests just above his temple, fingers brushing the thick black frames of his glasses, as if adjusting them for a portrait. Two empty glasses, one with a star etched on its base, sit beside him on the table, catching the warm, amber glow from the bar’s recessed lighting. Behind him, the bar’s shelving is symmetrically arranged with bottles, and a single, glowing sign hangs above the counter like a tiny, silent lantern. The scene is framed with the quiet geometry of a storybook, where every angle is intentional and every shadow holds a secret.
+
+**Moment 3** (scene `0f514958-508e-4083-9ba2-58795f036885`):
+
+> The man’s hand hovers over a bottle with a coral cap, its label blurred like a forgotten story, while the amber glow of the overhead orb casts a warm, uneven light across his glasses and the rim of his glass. Behind him, the bar’s backlit menu glows with a faint, orderly precision, its rows of text standing like silent, illuminated tombstones in the dim. The scene is framed with the quiet symmetry of a still life—his elbow, the bottle, the glass, all aligned under the single, golden eye of the lamp. There is a small, formal detail: the red of the cap, the yellow of the light, the dark brown of his sweater, all arranged with the careful, melancholic balance of a Wes Anderson storyboard.
+

docs/progress.md

@@ -0,0 +1,36 @@
+# Progress Tracker
+
+| Date | Item | Status | Evidence |
+|---|---|---|---|
+| 2026-06-11 | Hackathon rules verified from primary sources | ✅ | docs/hackathon-rules.md |
+| 2026-06-11 | Product strategy + architecture decided | ✅ | docs/product-strategy.md, docs/architecture.md |
+| 2026-06-11 | Repo bootstrap: CI, lint, tests, secret scan, docs | ✅ | .github/workflows/ci.yml |
+| 2026-06-11 | Vertical slice: Gradio app w/ mock backend + tests | ✅ | `uv run pytest`, `app.py` |
+| 2026-06-11 | KB notes written (mirrored in `kb/`, pending import to canonical KB) | ✅ | kb/*.md |
+| 2026-06-11 | Strategy confirmed by Carlos (+ Live Mode requirement added) | ✅ | docs/product-strategy.md |
+| 2026-06-11 | `main` branch created (from bootstrap commit) | ✅ | `git push origin claude/adoring-clarke-49l3uk:main` |
+| 2026-06-11 | M1 eval harness built + tested | ✅ | `src/small_cuts/eval.py`, `tests/test_eval.py` |
+| 2026-06-11 | Self-hosted runner on Spark registered + verified (GB10, CUDA 13.0, uv OK) | ✅ | Actions run 27370230783 (eval-on-spark on `eval/run-001`) |
+| — | Branch protection on `main` | ⚠️ Carlos reruns the `gh api` command (docs/setup.md) | — |
+| 2026-06-12 | run-004 eval (gemma + Qwen-3B) on Spark, HEIC photos | ✅ | Actions run 27374284507, docs/eval/run-004-scored.md |
+| 2026-06-12 | Automated judge: Codex (GPT-5 vision) scores narrations vs actual photos | ✅ | photo relay workflow + codex exec loop, ~7 min/report |
+| 2026-06-12 | Prompt A/B judged: v2 "find the story" was a pure loss; reverted+hardened as v3, temp 0.7→0.3 | ✅ | docs/eval/prompt-ab-comparison.md |
+| 2026-06-12 | M2 title-card renderer: Claude spec+tests, Codex implementation, 22/22 green | ✅ | docs/specs/title-card.md, src/small_cuts/title_card.py |
+| 2026-06-12 | 5 real glasses videos staged (Spark `~/eval-videos`) + relayed locally | ✅ | fetch-eval-photos workflow |
+| 2026-06-12 | run-005 judged: v3+temp lifted all models (3B pass cells 13%→30%); none meets "most images" bar | ✅ | docs/eval/run-005-scored.md |
+| 2026-06-12 | M1 provisional pick: **Qwen2.5-VL-7B** (best G 3.40 + best V 3.03); DEFAULT_MODEL_ID updated | ✅ | src/small_cuts/narrator.py |
+| — | M1 confirm: run-006 challenger (Qwen3-VL-8B, the KB's original target) executing on Spark | ⏳ | Actions run 27399170174, issue #10 |
+| 2026-06-14 | Review-3 viewer: single playback clock (custom file-backed `<audio>` — gr.Audio plays via wavesurfer, can't be the clock) couples video+captions+progress; theater layout (stage + gallery rail, no scrollbars desktop+mobile); 9:16 preserved; Voice-Cut app icon | ✅ | `src/small_cuts/viewer.py`, KB `2026-06-14-small-cuts-review3-*`, 153 pytest, Playwright 1440+390 |
+| — | M2: TTS + title card + Off-Brand theme | ⬜ | — |
+| — | M3: Space live under hackathon org | ⬜ | — |
+| — | M4: demo video + social post + Field Notes | ⬜ | — |
+| — | M5: submission | ⬜ deadline June 15 | — |
+
+## Decisions Carlos must make / confirm
+
+1. ~~Confirm Track 2 + quest set~~ ✅ confirmed 2026-06-11, with Live Mode added as a requirement-if-feasible.
+2. ~~Solo vs. team~~ ✅ solo.
+3. ~~Claim credits~~ ✅ done.
+4. Enable branch protection — rerun the `gh api` command now that `main` exists (docs/setup.md).
+5. Verify exact submission deadline time + video/post requirements in Discord (Carlos, in progress).
+6. ~~Run the M1 eval on the DGX Spark~~ → infrastructure verified working (run 27370230783 reached the GB10). Remaining: stage ~12 personal photos in `/home/carlos/eval-photos` on the Spark, then re-trigger (`gh workflow run eval-on-spark` from a tailnet machine, or push an `eval/**` branch).

docs/regular-pipeline-library-2026-06-15.md

@@ -0,0 +1,78 @@
+# Regular Pipeline Library - 2026-06-15
+
+Working timestamp: 2026-06-15 08:34 UTC / 10:34 CEST.
+
+Purpose: replace curated seed narrations with scenes generated through the same `/v1/session`
+WebSocket path used by the iPhone capture app, while preserving an honest but more watchable
+library for the judged Space.
+
+## Runtime Changes
+
+- Active library root: `/private/tmp/small-cuts-demo-library-generated-24f-20260615`.
+- The first 24-frame run selected the final frame of each clip. It was technically valid but weaker
+  narratively, so its rows were archived into SQLite table
+  `hidden_scenes_20260615_final_frame_24f`.
+- The final public run uses key-marked moment envelopes: one selected frame plus 23 preceding
+  supplemental frames, matching the user pressing Mark when the moment is readable.
+- Curated hero rows remain archived in
+  `/private/tmp/small-cuts-demo-library-hero-20260615.pre-generated-backup-20260615T080924Z`.
+- Final generated session:
+  `regular-pipeline-24f-keymark-glasses-20260615T083000Z`.
+- Public Cloudflare read gate lists exactly five generated public scenes.
+
+## Generated Scenes
+
+| Seq | Source clip | Scene ID | Wall time | MP4 | Generated title |
+|---:|---|---|---:|---|---|
+| 0 | `desk-laptop.mp4` | `fea81fe7-da00-42e4-b68e-429038a10122` | 4573 ms | 24 frames @ 6 fps | A hand, palm up, blocks the camera's view, revealing a... |
+| 1 | `the-stumble.mp4` | `08318a62-8ae6-41f6-a518-bcc037ac4873` | 4285 ms | 24 frames @ 6 fps | The camera lingers on a concrete alleyway at night, the... |
+| 2 | `street-parked-car.mp4` | `906159c4-5ebd-4e76-9c45-c43e46b85913` | 4656 ms | 24 frames @ 6 fps | The car door is open, revealing a black interior and a... |
+| 3 | `night-drive.mp4` | `df71c033-9f24-4e41-a3e8-3e7c2a31620a` | 4494 ms | 24 frames @ 6 fps | The driver grips the steering wheel with both hands, thumbs... |
+| 4 | `rayuela.mp4` | `aead3e4d-2459-4638-81b8-74abddd2a149` | 4268 ms | 24 frames @ 6 fps | The yellow circle with numbers is painted on the floor... |
+
+All five scenes have `frame.jpg`, `card.webp`, `voice.wav`, and `clip.mp4`.
+
+## Generated Narrations
+
+**desk-laptop.mp4**
+
+> A hand, palm up, blocks the camera's view, revealing a translucent overlay of a retro video game with a small plane and a vertical stack of pixelated blocks. Behind it, a laptop keyboard and a smartphone lie on a desk, the phone screen showing a circular loading icon. The hand remains still, as if posing for a photo, though the game's score reads "S000 60s."
+
+**the-stumble.mp4**
+
+> The camera lingers on a concrete alleyway at night, the only light spilling from a doorway marked "MANCHESTER" and a glass door to the right. A single, slightly-too-bright bulb hangs overhead, casting long shadows across the wet pavement. The glass door is ajar, revealing a dimly lit interior. A small, yellow warning sign is taped to the pillar beside it.
+
+**street-parked-car.mp4**
+
+> The car door is open, revealing a black interior and a steering wheel with a logo, while the driver's hand rests on the edge of the door frame. A white SUV is parked directly behind, its rear bumper touching the car's front fender. A man in dark clothing walks past a small kiosk on the sidewalk, glancing toward the parked cars. The sun casts sharp, angular shadows across the pavement and the cars' surfaces.
+
+**night-drive.mp4**
+
+> The driver grips the steering wheel with both hands, thumbs resting on the top rim, as the car moves forward through a dimly lit parking garage. The dashboard lights glow blue, and the windshield shows streaks of artificial light from distant fixtures, blurred by motion. The steering wheel is black, and the driver's wrists are bare. The car's speedometer needle is steady, indicating a slow, deliberate pace.
+
+**rayuela.mp4**
+
+> The yellow circle with numbers is painted on the floor behind the metal grid, as if marking a spot for something that never happened. The grid itself is slightly bent, casting a distorted view of the empty court beyond. The blue padding on the pillars is faded, and the numbers on the circle are slightly smudged. The space is quiet, waiting for something that hasn't arrived.
+
+## Quality Read
+
+- Strongest current generated cut: `rayuela.mp4`; it is visually legible and has the best generated
+  deadpan line.
+- Strong physical POV cut: `street-parked-car.mp4`; the mark point now lands on the open car door.
+- `desk-laptop.mp4` remains literal because the overlay/game UI dominates the selected frame, but it
+  is coherent and useful as a builder/desk sample.
+- The key-marked run is materially better than the final-frame run while staying honest: no human
+  narration or title copy is injected.
+
+## Verification
+
+- Local Python gate: `uv run ruff check . && uv run ruff format --check . && uv run pytest` passed
+  with 172 tests.
+- iOS simulator gate: `xcodebuild test ... -scheme SmallCuts` passed with 64 tests, 1 live-engine
+  smoke skipped, 0 failures.
+- Public read gate returns five generated scenes.
+- Public `/v1/session` and `PATCH /v1/scenes/*` return `403`.
+- Public media smoke returns `200` for each scene's `clip.mp4`, `voice.wav`, `frame.jpg`, and
+  `card.webp`.
+- HF Space Gradio `_tick` returns the latest generated title, video stage, Cloudflare audio URL,
+  visibility `public`, and five gallery captions.

docs/setup.md

@@ -0,0 +1,92 @@
+# Setup Guide
+
+## Local development
+
+```bash
+git clone https://github.com/macayaven/small-cuts.git
+cd small-cuts
+uv sync --extra dev          # or: pip install -e ".[dev]"
+
+# fastest loop — deterministic mock backend, no model downloads
+SMALL_CUTS_BACKEND=mock uv run python app.py
+```
+
+Real-model backends (M1+):
+
+```bash
+uv sync --extra local        # transformers + torch
+SMALL_CUTS_BACKEND=transformers SMALL_CUTS_MODEL_ID=HuggingFaceTB/SmolVLM2-2.2B-Instruct \
+  uv run python app.py
+
+uv sync --extra llama        # llama-cpp-python
+SMALL_CUTS_BACKEND=llama_cpp SMALL_CUTS_GGUF_PATH=/path/to/model.gguf \
+  uv run python app.py
+```
+
+## Environment variables
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `SMALL_CUTS_BACKEND` | `mock` | `mock` \| `transformers` \| `llama_cpp` |
+| `SMALL_CUTS_MODEL_ID` | `HuggingFaceTB/SmolVLM2-2.2B-Instruct` | HF model id for the transformers backend |
+| `SMALL_CUTS_GGUF_PATH` | — | local GGUF path for the llama.cpp backend |
+
+## Secrets
+
+There are **no secrets in this repo** and the core app needs none at runtime.
+
+- Local dev: fetch tokens (HF write token for Space deploys) from **1Password
+  Connect** — never paste them into files or shell history that gets committed.
+- CI: `GITHUB_TOKEN` only (provided by Actions).
+- Space: set `HF_TOKEN`-class secrets in the Space settings UI if ever needed.
+- `gitleaks` runs in CI on every push and PR.
+
+## Branch protection (one-time admin step — ⚠️ pending)
+
+GitHub MCP tooling in the bootstrap session could not set branch protection.
+Carlos (or any session with `gh` + admin) must run once:
+
+```bash
+gh api -X PUT repos/macayaven/small-cuts/branches/main/protection \
+  -F required_status_checks[strict]=true \
+  -F 'required_status_checks[contexts][]=ci' \
+  -F enforce_admins=true \
+  -F required_pull_request_reviews[required_approving_review_count]=0 \
+  -F restrictions=null
+```
+
+(Zero required approvals keeps the PR-based workflow without blocking a
+solo builder on a 4-day deadline.)
+
+## Tailnet access from cloud Claude Code sessions
+
+Cloud session containers are not on the tailnet by default. `scripts/tailnet-connect.sh`
+fixes that: it installs Tailscale (userspace networking — no TUN in these
+containers), authenticates with `TS_AUTHKEY`, and writes an SSH config so
+`ssh spark` / `ssh mac-studio` dial through `tailscale nc`.
+
+One-time setup by Carlos:
+
+1. Tailscale admin console → **Settings → Keys → Generate auth key** with
+   **Reusable + Ephemeral + Pre-approved** (ephemeral nodes vanish when the
+   container dies), ideally tagged (e.g. `tag:claude-session`) with ACLs
+   limiting it to SSH toward `spark-caeb` and `mac-studio`.
+2. Add it as `TS_AUTHKEY` in the Claude Code **environment settings**
+   (code.claude.com → environment → secrets/env vars) — never in the repo.
+3. Recommended: enable **Tailscale SSH** on both machines
+   (`sudo tailscale set --ssh`) with a matching ACL `ssh` rule, so sessions
+   need no SSH keypair management at all.
+4. Optional, to auto-connect every session: add a `SessionStart` hook to
+   `.claude/settings.json` running `bash scripts/tailnet-connect.sh || true`.
+
+Each session then runs (or the hook runs): `bash scripts/tailnet-connect.sh`.
+
+## Deploying the Space (M3)
+
+1. Create the Space **under the hackathon org**: `build-small-hackathon/small-cuts`
+   (Gradio SDK, ZeroGPU hardware if available, CPU fallback otherwise).
+2. Push this repo's `app.py`, `src/`, `requirements.txt` to the Space
+   (`gradio deploy` or a `git push` to the Space remote).
+3. Set `SMALL_CUTS_BACKEND=transformers` (ZeroGPU) or `llama_cpp` (CPU) in
+   Space variables.
+4. Smoke-test from a phone browser — that is the judge experience.

docs/specs/llama-backend.md

@@ -0,0 +1,72 @@
+# Spec: LlamaCppBackend via llama-server (M3, issue #14 → achievement:llama)
+
+## Purpose
+
+Make `SMALL_CUTS_BACKEND=llama_cpp` real: the narrator runs through the
+llama.cpp runtime (Llama Champion badge). Verified end-to-end on 2026-06-12
+(see #14 comment): official `Qwen/Qwen3-VL-8B-Instruct-GGUF` Q4_K_M + mmproj
+through llama.cpp b9590 produces grounded, on-voice narrations.
+
+Design: a managed **`llama-server` subprocess** spoken to over its
+OpenAI-compatible HTTP API — NOT llama-cpp-python chat handlers (the Python
+wrapper lags upstream on new vision archs; the server tracks llama.cpp).
+
+## Contract (`src/small_cuts/narrator.py`, replace the stub)
+
+`LlamaCppBackend` keeps `name = "llama_cpp"` and the `Backend` protocol.
+
+### Configuration (env)
+
+- `SMALL_CUTS_LLAMA_URL` — if set (e.g. `http://127.0.0.1:8080`), use this
+  already-running llama-server and manage NO subprocess. This is the CI/test
+  seam and the local-dev path (`brew install llama.cpp; llama-server …`).
+- `SMALL_CUTS_LLAMA_SERVER` — path to a `llama-server` binary; default:
+  `shutil.which("llama-server")`. If neither URL nor binary is available,
+  `generate` raises `RuntimeError` with an actionable message (mention brew
+  and SMALL_CUTS_LLAMA_URL). Do NOT auto-download binaries in this package.
+- `SMALL_CUTS_GGUF_PATH` / `SMALL_CUTS_MMPROJ_PATH` — local GGUF paths; if
+  unset, resolve via `huggingface_hub.hf_hub_download` from
+  `Qwen/Qwen3-VL-8B-Instruct-GGUF` (`Qwen3VL-8B-Instruct-Q4_K_M.gguf`,
+  `mmproj-Qwen3VL-8B-Instruct-F16.gguf`). `model_id` reports the repo id or
+  the basename of the local GGUF.
+
+### Subprocess management (only when no SMALL_CUTS_LLAMA_URL)
+
+- Lazily started on first `generate` (constructing the backend must not
+  spawn anything — mirrors the lazy `_load` pattern).
+- Launch: `llama-server -m <gguf> --mmproj <mmproj> --port <free port>
+  -c 8192 --image-max-tokens 1024 --host 127.0.0.1`.
+  The image-token floor matters: llama.cpp warns Qwen-VL needs ≥ 1024 image
+  tokens for grounding accuracy. Keep exactly 1024.
+- Wait for readiness by polling `GET /health` (llama-server exposes it)
+  with a deadline (~120 s — model load takes a while); kill + RuntimeError
+  on timeout. Register `atexit` cleanup that terminates the child.
+
+### Request path
+
+- Reuse `build_messages(style_key, scene_hint)`; system message as-is; user
+  content = `[{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,…"}},
+  {"type": "text", "text": <user text>}]` (OpenAI vision shape llama-server accepts).
+- **Downscale before encoding**: new pure helper in narrator.py
+  `def _downscale(image: Image.Image, max_side: int = 1024) -> Image.Image`
+  — proportional thumbnail when the longest side exceeds `max_side`
+  (full-res portrait glasses frames blow up vision compute; see #14).
+  JPEG quality 90.
+- Body: `temperature` from `SMALL_CUTS_TEMPERATURE` (default 0.3),
+  `max_tokens: 160`. Parse `choices[0].message.content`, return `.strip()`.
+- Use `httpx` (already a Gradio dependency) with a generous timeout (120 s).
+- Connection/HTTP errors → `RuntimeError` mentioning the server URL.
+
+## Out of scope
+
+- NO ui.py changes (P1 rewrites the UI; backend selection stays env-based).
+- NO binary auto-download; NO Space wiring (separate deploy step).
+
+## Verification
+
+`tests/test_llama_backend.py` (committed alongside, uses a fake in-process
+HTTP server — no llama binary in CI) must pass, plus the full gate:
+`uv run pytest && uv run ruff check && uv run ruff format --check`.
+Do not modify tests or spec; if a test looks wrong, stop and explain.
+Manual (not CI): with a local `llama-server` running,
+`SMALL_CUTS_LLAMA_URL=http://127.0.0.1:8080 SMALL_CUTS_BACKEND=llama_cpp uv run python -c "…narrate(Image.open(...))…"`.

docs/specs/theme.md

@@ -0,0 +1,63 @@
+# Spec: Off-Brand custom Gradio theme (M2, issue #13)
+
+## Purpose
+
+Replace the placeholder `gr.themes.Monochrome` in `ui.py` with a custom
+cinematic theme — the **Off-Brand** quest (own visual identity). The house
+style already exists in `title_card.STYLE_CARDS`; the theme borrows from it:
+a dark screening-room canvas with gold marquee accents.
+
+## Contract
+
+### 1. `src/small_cuts/theme.py` (new module)
+
+```python
+class OffBrand(gr.themes.Base): ...
+
+def build_theme() -> gr.themes.Base
+```
+
+- `OffBrand.__init__` configures fonts: body/headings `Spectral`
+  (GoogleFont, serif fallback) — the existing house font — and
+  `IBM Plex Mono` (GoogleFont, monospace fallback) for code/metadata.
+- Then `.set()` overrides establishing the palette (light AND `*_dark`
+  variants set to the same values — the screening room ignores OS mode):
+  - `body_background_fill` / `body_background_fill_dark`: `#101014`
+    (charcoal, trailer card background)
+  - `body_text_color` / `body_text_color_dark`: `#E8E4D8` (bone white,
+    noir card text)
+  - `button_primary_background_fill` / `_dark`: `#D4AF37` (marquee gold)
+  - `button_primary_text_color` / `_dark`: `#101014`
+  - `block_background_fill` / `_dark`: a slightly lifted charcoal
+    (e.g. `#16161C`)
+  - `block_title_text_color` / `_dark`: `#D4AF37`
+  - plus whatever minimal extra overrides (borders, input fills, link
+    color) are needed so no component renders as a glaring white patch on
+    the dark canvas. Use STYLE_CARDS hexes where a choice is needed.
+- `build_theme()` returns a constructed `OffBrand()` instance.
+- Module stays small (≈60 lines); no new dependencies.
+
+### 2. `src/small_cuts/ui.py`
+
+Replace the placeholder assignment (and its comment):
+
+```python
+THEME = gr.themes.Monochrome(font=[gr.themes.GoogleFont("Spectral"), "serif"])
+```
+
+with an import from the new module:
+
+```python
+from .theme import build_theme
+THEME = build_theme()
+```
+
+`app.py` already does `demo.launch(theme=THEME)` (Gradio 6 API) — do not
+change it, and do not touch anything else in `ui.py` (parallel changes wire
+title cards and TTS into the same file; keep this diff to the THEME swap).
+
+## Verification
+
+`tests/test_theme.py` (committed alongside this spec) must pass, plus the
+full local gate: `uv run pytest && uv run ruff check && uv run ruff format --check`.
+Do not modify the tests; if a test looks wrong, flag it instead.

docs/specs/title-card-wiring.md

@@ -0,0 +1,51 @@
+# Spec: Title-card wiring + title derivation (M2, issue #12)
+
+## Purpose
+
+`title_card.render_title_card` exists but nothing calls it. Wire it into the
+Gradio app so every narration is accompanied by its movie-style title card,
+with the title derived from the narration's first clause (caller-side, per
+docs/specs/title-card.md "out of scope" note).
+
+## Contract
+
+### 1. `derive_title` (new, in `src/small_cuts/title_card.py`)
+
+```python
+def derive_title(text: str, max_len: int = 60) -> str
+```
+
+- Strips surrounding whitespace.
+- Strips one leading bracketed style tag if present (`"[Noir Detective] The
+  rain…"` → `"The rain…"`) — the mock backend emits narrations in this shape.
+- Returns the **first clause**: everything before the first sentence-ending
+  punctuation (`.`, `!`, `?`, `;`) or em-dash (`—`). The terminator itself is
+  not included. Trailing ellipsis in the source ("Lunch... changes") must not
+  produce an empty or one-word title: a `...`/`…` only terminates the clause
+  when followed by whitespace + an uppercase letter, otherwise it is kept.
+  (Simplification allowed: treat `...` like any terminator BUT only after the
+  clause already has ≥ 3 words.)
+- If the clause is longer than `max_len` characters, cut at the last word
+  boundary that fits and append `…` (single ellipsis char). Never cut
+  mid-word; never return more than `max_len` chars total.
+- Empty / whitespace-only input → `"Untitled Scene"`.
+- Pure + deterministic. No new dependencies.
+
+### 2. UI wiring (`src/small_cuts/ui.py`)
+
+- Right column gains a card display **above** the narration textbox:
+  `gr.Image(label="Title card", interactive=False)`.
+- `_narrate_handler` and `_narrate_video_handler` now return
+  `tuple[PIL.Image.Image, str]` = `(card, narration_text)`:
+  `card = render_title_card(derive_title(text), style_key)` at the default
+  1280×720 size, using the **requested** style key.
+- The no-image / no-video placeholder paths also render a card from the
+  placeholder text (the show must go on).
+- All three event wirings (`go.click`, `image.change`, `video.change`) get
+  `outputs=[card, narration]`.
+
+## Verification
+
+`tests/test_title_wiring.py` (committed alongside this spec) must pass, plus
+the full local gate: `uv run pytest && uv run ruff check && uv run ruff format --check`.
+Do not modify the tests; if a test looks wrong, flag it instead.

docs/specs/title-card.md

@@ -0,0 +1,60 @@
+# Spec: Title-card renderer (M2)
+
+## Purpose
+
+Every narration gets a movie-style title card: a 16:9 image shown beside the
+narration in the Gradio app, styled per director. Part of the **Off-Brand**
+quest (custom visual identity) — pure PIL, no model, no network.
+
+## Contract
+
+New module `src/small_cuts/title_card.py`:
+
+```python
+def render_title_card(
+    title: str,
+    style_key: str,
+    size: tuple[int, int] = (1280, 720),
+) -> PIL.Image.Image
+```
+
+- Returns an RGB image of exactly `size`.
+- `style_key` must be a key of `styles.STYLES`; unknown keys raise `KeyError`
+  (same behavior as `build_messages`).
+- **Deterministic**: identical inputs produce byte-identical output. No
+  randomness, no timestamps.
+- Layout: a kicker line (`A SMALL CUTS PICTURE`), the title (uppercased,
+  wrapped, centered, dominant), and a style label subtitle (from
+  `STYLES[style_key].label`).
+- Title text wraps to fit; very long titles (200+ chars) must render without
+  raising or overflowing the canvas.
+- Empty title renders the kicker + subtitle only (no crash).
+
+## Per-style art direction
+
+One palette + typographic treatment per style, keyed off `STYLES`:
+
+| style | background | text | treatment |
+|---|---|---|---|
+| deadpan | warm off-white `#F2EFE6` | near-black `#1A1A1A` | thin rule above+below title |
+| noir | black `#0D0D0F` | bone white `#E8E4D8` | hard white 2px frame inset |
+| nature_doc | deep green `#0E2A1B` | cream `#F0E9D2` | double-line frame |
+| trailer | charcoal `#101014` | gold `#D4AF37` | wide letter-spacing (inserted spaces) |
+| telenovela | crimson `#5C0A14` | rose white `#FFE9EC` | ornament line `♦ ─── ♦` under title |
+| symmetrist | pastel pink `#F7D6C9` | brown `#5B3A29` | perfectly centered, thin border 8px inset |
+
+Every key in `STYLES` must have an entry — add a module-level mapping and a
+test guards the invariant (new styles must add palettes).
+
+## Constraints
+
+- Fonts: `ImageFont.load_default(size=...)` (Pillow ≥ 10.1 scalable default)
+  — no bundled font files, no new dependencies.
+- Must work headless (no display) — CI runs it.
+- Keep the module under ~120 lines; this is a hackathon, not a layout engine.
+
+## Out of scope (M2 later steps)
+
+- Deriving the title from the narration text (caller's job).
+- Animated cards, gradients, photo-blending.
+- Gradio wiring (separate change).

docs/specs/tts.md

@@ -0,0 +1,78 @@
+# Spec: Kokoro TTS behind the backend pattern (M2, issue #11)
+
+## Purpose
+
+Give the narrator a voice. New module `src/small_cuts/tts.py` mirroring the
+`narrator.py` backend pattern exactly (Protocol + mock + real, env-var
+selection), plus an on-demand "read it to me" button in the Gradio app.
+All local — no cloud TTS (Off the Grid quest).
+
+## Contract
+
+### 1. `src/small_cuts/tts.py`
+
+```python
+@dataclass(frozen=True)
+class Speech:
+    sample_rate: int
+    audio: np.ndarray  # mono float32, values in [-1.0, 1.0]
+    backend: str
+    model_id: str
+    latency_s: float
+
+class TTSBackend(Protocol):
+    name: str
+    model_id: str
+    def synthesize(self, text: str) -> tuple[int, np.ndarray]: ...
+
+def get_tts_backend(name: str | None = None) -> TTSBackend
+def speak(text: str, backend: TTSBackend | None = None) -> Speech
+```
+
+- `get_tts_backend`: reads `SMALL_CUTS_TTS_BACKEND` env var, default `mock`;
+  unknown name → `ValueError("Unknown TTS backend …")` (mirror
+  `narrator.get_backend`).
+- `speak`: empty / whitespace-only text → `ValueError` mentioning "empty";
+  otherwise times the backend call and returns a `Speech`.
+
+### 2. `MockTTSBackend` — `name = "mock"`, `model_id = "mock-tts-0"`
+
+Deterministic, weightless, CI-safe:
+- 24_000 Hz mono float32 sine wave, amplitude ≤ 0.3.
+- Duration scales with text length, clamped to [0.2s, 2.0s].
+- Pitch derives from the text content (e.g. `220 + sum(text.encode()) % 220`
+  Hz) so different texts produce different audio, same text identical audio.
+
+### 3. `KokoroBackend` — `name = "kokoro"`, `model_id = "hexgrad/Kokoro-82M"`
+
+- Lazy: constructing the backend must NOT import `kokoro`; first
+  `synthesize` call does. If the import fails, raise `RuntimeError` with an
+  actionable message (mention `uv sync --extra tts`).
+- Uses `kokoro.KPipeline(lang_code="a")`, voice from `SMALL_CUTS_TTS_VOICE`
+  env var (default `af_heart`), 24_000 Hz output; concatenate segment audio
+  into one mono float32 array.
+- Add optional dependency group to `pyproject.toml`:
+  `tts = ["kokoro>=0.9", "soundfile>=0.12"]`. CI does NOT install it; no
+  import of kokoro at module import time (CI must stay green without it).
+
+### 4. UI wiring (`src/small_cuts/ui.py`)
+
+- Right column, under the narration textbox: a secondary button
+  `🔊 Read it to me` and `gr.Audio(label="The narrator speaks…", interactive=False)`.
+- New handler:
+  ```python
+  def _speak_handler(text: str) -> tuple[int, np.ndarray] | None
+  ```
+  Returns `None` when `text` is empty/whitespace (clears the player),
+  otherwise `(speech.sample_rate, speech.audio)` via `speak(text)`.
+- Wiring: `speak_btn.click(_speak_handler, inputs=[narration], outputs=[audio])`.
+- TTS is on-demand only — narration handlers stay untouched (a parallel
+  change wires title cards into them; do not modify their signatures).
+
+## Verification
+
+`tests/test_tts.py` (committed alongside this spec) must pass, plus the full
+local gate: `uv run pytest && uv run ruff check && uv run ruff format --check`.
+Do not modify the tests; if a test looks wrong, flag it instead.
+Manual sanity (optional, not CI): `uv sync --extra tts` then
+`SMALL_CUTS_TTS_BACKEND=kokoro uv run python -c "from small_cuts.tts import speak; print(speak('One man. One sandwich.').audio.shape)"`.

docs/specs/video-input.md

@@ -0,0 +1,77 @@
+# Spec: video input + device-free Live Mode tests (M3.5 prep)
+
+Image flow stays primary; video is additive. Ground truth measured from the
+five real glasses clips (relayed from the Spark, staged at
+`~/small-cuts-fixtures/videos/`, never committed):
+
+| Clip | Codec | Resolution | fps | Duration |
+|---|---|---|---|---|
+| IMG_8165.MOV | HEVC | 1424×1904 | 29.9 | 180.0s |
+| IMG_8175.MOV | HEVC | 1376×1824 | 29.7 | 180.0s |
+| IMG_8216.MOV | HEVC | 1552×2064 | 30.0 | 180.0s |
+| IMG_8292.MP4 | H.264 | 976×1296 | 30.0 | 46.9s |
+| IMG_8368.MOV | HEVC | 1504×2016 | 30.0 | 180.4s |
+
+Measured facts that override earlier guesses: frames are **natively portrait
+with no rotation side-data** — PyAV decodes them upright, no display-matrix
+handling needed (verified visually on IMG_8292 mid-frame). Real clips run to
+**180s** (glasses max) — the upload cap must be ≥180s, not 60s.
+
+## 1. Video ingest contract (minimal change, three edits)
+
+1. **Extract sampler** → new `src/small_cuts/frames.py`:
+   - `sample_frames(path, every_n_seconds=3.0, max_frames=None) -> list[PIL.Image]`
+   - Body lifted from `eval.py:_sample_video_frames` minus the sibling-JPEG
+     writes — return in-memory RGB PIL Images only.
+   - `pick_frame(frames) -> PIL.Image` — middle frame for v1.
+   - `eval.py:_sample_video_frames` becomes a thin wrapper that saves the
+     returned images (eval behavior unchanged).
+2. **UI** (`ui.py`): add `gr.Video(sources=["upload"])` beside the existing
+   image input; handler = `sample_frames(path)` → `pick_frame` → unchanged
+   `narrate()`. No changes to `narrator.py` or the Backend protocol.
+3. **Deps**: `av>=12.0` moves to core `[project.dependencies]` +
+   `requirements.txt` (the Space has no `av` today → instant ImportError).
+
+## 2. Frame→narration strategy
+
+- **v1 (ship)**: one narration per clip, middle sampled frame. Eval evidence
+  says groundedness is the weak axis on single frames already; multi-image
+  prompts add vision tokens and hallucination surface with no evidence yet.
+- **v1.5 (if time)**: sharpest-of-sampled via Laplacian variance, still one
+  frame.
+- **Deferred**: multi-frame prompts — gate behind the judged eval. A full
+  video eval naively costs 5 clips × ~60 frames × 3 styles × N models ≈
+  thousands of generations; `pick_frame` must land first.
+
+## 3. Device-free preliminary tests (real footage, no hardware)
+
+- `tests/test_frames.py` (CI-safe, synthetic clips encoded with PyAV into
+  tmp_path): frame count at cadence, short-clip ≥1 frame, no side-effect
+  files, RGB PIL output, eval wrapper still writes JPEGs.
+- Local-only smoke (skipif fixtures missing): parametrize over the five real
+  clips — decodes, ≥1 frame, portrait orientation preserved.
+- One manual Gradio smoke: upload IMG_8292.MP4 → narration appears, frame
+  upright, round-trip acceptable. Repeat once on the deployed Space (only
+  test that catches missing-`av`-class failures).
+
+## 4. Deferred to real-device work (post-hackathon)
+
+Live DAT capture (streaming off the glasses) is out of scope for v1 — clips
+enter via phone export → upload. When the native bridge starts, build against
+MockDeviceKit from day one (`pairRaybanMeta()`, `camera.setCameraFeed(fileURL:)`
+with HEVC fixtures) per the KB note
+`2026-06-11-directors-cut-claude-ios-dat-bridge-reference`. Genuinely needs
+hardware: Meta AI registration, Developer-Mode-after-firmware gotcha, real BT
+bandwidth degradation, tap/hinge quirks.
+
+## 5. Scene-change gate (M3.5, after video input)
+
+32×32 grayscale mean-abs-diff in `frames.py`, threshold tuned by replaying
+the five clips at 1s cadence. Proves frames → gate → narrate on recorded
+footage before any Gradio streaming work.
+
+## Open questions for Carlos
+
+1. Is `gr.Video` upload part of the judged demo, or insurance? If judged,
+   the deployed-Space smoke moves up.
+2. OK to pin Gradio to 6.x now so M3.5 streaming lands on a stable API?

kb/2026-06-11-directors-cut-peer-synthesis-for-small-cuts.md

@@ -0,0 +1,108 @@
+---
+projectId: directors-cut
+id: 2026-06-11-directors-cut-peer-synthesis-for-small-cuts
+status: PARTIAL — written from a cloud session without access to the canonical KB
+---
+
+# Director's Cut — Onboarding Synthesis for Small Cuts (2026-06-11)
+
+## ⚠️ Evidence limitation (read first)
+
+This synthesis was produced in a **cloud Claude Code session**, not on the Mac
+Studio. The following prescribed sources were **unreachable** and are NOT
+reflected below:
+
+- `.knowledge/INDEX.md`, `00-guidelines/agent-operating-contract.md`,
+  `30-resources/cli-app-setup.md`, `10-projects/directors-cut/*` (no `.knowledge/`
+  dir, no `knowledge_base-*` MCP tools in this environment)
+- Peer notes from Codex and Claude (live only in the KB above)
+- Source code of `macayaven/directors-cut` and `macayaven/wearables-gradio-poc`
+  (GitHub access in this session is scoped to `macayaven/small-cuts` only)
+
+Everything below comes from: GitHub repo metadata (names/descriptions/dates),
+Carlos's own emails (Gmail), the Notion workspace (SparkClaw lineage), and the
+official hackathon sources. Items that could not be verified are labeled
+**unverified**. **A Mac Studio session must re-run the prescribed KB reads and
+amend this note.**
+
+## 1. What Director's Cut is
+
+A cinematic POV narration product for Meta Ray-Ban (Display) glasses: an
+intelligent narrator that watches what you see and produces film-style
+commentary. Evidence: repo `macayaven/directors-cut` (created 2026-05-18) —
+"iOS companion for Meta Ray-Ban Display glasses — Director's Cut cinematic POV
+narration (Gemini Live cloud / Qwen3-Omni local)".
+
+## 2. Intended emotional/product experience
+
+The omniscient narrator characters of *The Invention of Lying*: lived moments
+transformed into meaningful, contextual, cinematic commentary (per Carlos's
+mission statement for this project).
+
+## 3. Hackathon/submission context
+
+**Confirmed:** Build Small Hackathon (Gradio × HF), submissions close June 15,
+2026; Gradio Space under org; ≤32B params; Carlos registered (credits email
+2026-06-04). **Unverified:** which sidequests Carlos previously "selected";
+whether any submission draft exists under the org (none found by name on
+2026-06-11); team status with Topi (invited by email 2026-06-03, outcome unknown).
+
+## 4. What Codex contributed
+
+**Unknown from this environment** — Codex's notes live in the canonical KB.
+(Repo commit history unreadable here.)
+
+## 5. What Claude contributed
+
+**Unknown from this environment** — same limitation. Notion shows extensive
+Claude-authored work on the *predecessor* wearables project (SparkClaw, April
+2026): bridge architecture, reply-envelope design, demo-thesis notes.
+
+## 6–7. Peer agreement / conflicts
+
+**Cannot be assessed without the peer notes.** Known objective tension in the
+trajectory itself: a native iOS + cloud Gemini Live path vs. hackathon rules
+that require a Gradio Space and reward local ≤32B inference. The existence of
+`wearables-gradio-poc` (created 2026-06-07, two days after the hack window
+opened) suggests the pivot was already understood.
+
+## 8. Current architecture (best available evidence)
+
+- `directors-cut`: Swift iOS companion; narration via Gemini Live (cloud) or
+  Qwen3-Omni (local). Details unverified.
+- `wearables-gradio-poc`: Gradio proof-of-concept, presumed hackathon pivot.
+  Contents unverified.
+- Prior art (SparkClaw, Notion-verified): Mac Studio/DGX local-first stack,
+  WhatsApp bridge to glasses, vLLM vision on DGX `:8000/v1`, Meta Wearables
+  Device Access Toolkit (github.com/facebook/meta-wearables-dat-ios).
+
+## 9. Current implementation state
+
+Unverified beyond repo metadata: directors-cut last pushed ~2026-05-21 (2 open
+issues); wearables-gradio-poc created 2026-06-07, no language stats visible.
+
+## 10. Highest-risk assumptions (for any successor)
+
+1. That glasses integration can be load-bearing in a judged demo (it can't —
+   judges run the Space).
+2. That cloud narration (Gemini Live) is acceptable — it forfeits Off the Grid
+   and weakens the small-model story.
+3. That a small VLM can narrate with grounded specificity (needs eval, M1).
+4. That the remaining 4 days suffice for any native-app work (they don't).
+
+## 11. First 5 actions before coding (executed in this session)
+
+1. ✅ Verify hackathon rules from primary sources (emails + org README).
+2. ✅ Inventory actually-reachable knowledge (Notion, Gmail, repo metadata).
+3. ✅ Decide track (2) and quest portfolio.
+4. ✅ Decide architecture: Space-is-the-product, glasses-as-capture.
+5. ✅ Bootstrap `small-cuts` repo with discipline + vertical slice.
+
+## 12. Evidence ledger
+
+- Gmail thread `19e8db3f17a5a437` (2026-06-03, rules + Carlos's forward to Topi)
+- Gmail thread `19e9480d1438494e` (2026-06-04, registration confirmed, credits, deadline)
+- https://huggingface.co/spaces/build-small-hackathon/README (raw fetch 2026-06-11)
+- https://huggingface.co/build-small-hackathon (org stats, no macayaven space found)
+- GitHub repo metadata via API search `user:macayaven` (2026-06-11)
+- Notion: "SparkClaw Documentation Hub - 2026-04-18" and children (prior project)

kb/2026-06-11-small-cuts-architecture-decision.md

@@ -0,0 +1,27 @@
+---
+projectId: small-cuts
+id: 2026-06-11-small-cuts-architecture-decision
+---
+
+# Small Cuts — Architecture Decisions (2026-06-11, post-confirmation)
+
+- **What changed:** Carlos confirmed Track 2 + quest portfolio and added a
+  requirement-if-feasible: real-time narration playback **on the glasses**.
+  Decisions taken: (a) Live Mode layered design — Bluetooth audio-out through
+  the glasses is free once TTS lands (M2); continuous camera-streaming Live
+  Mode is stretch M3.5; glasses-camera capture via Meta Wearables DAT is
+  post-hackathon. (b) **DGX Spark** is the M1 eval host (CUDA matches ZeroGPU;
+  128GB fits all candidate VLMs). (c) `main` created from the bootstrap commit
+  so branch protection can be applied; PR-based workflow from here on.
+- **Why:** preserves the "hearing your life narrated" magic without making
+  hardware load-bearing for judges; keeps the 4-day plan intact.
+- **Evidence / commands:** `git push origin claude/adoring-clarke-49l3uk:main`
+  (new branch `main` @ 7ca6d57); eval harness `src/small_cuts/eval.py` +
+  `tests/test_eval.py` (pytest green); tailnet unreachable from cloud sessions
+  (no MagicDNS resolution for `*.tail48bab7.ts.net`) — eval must run locally.
+- **Current status:** solo entry confirmed; credits claimed; Carlos verifying
+  deadline time + submission mechanics in Discord.
+- **Next action:** Carlos runs the eval one-liner on the Spark
+  (docs/implementation-plan.md M1) and reruns the branch-protection command.
+- **Risks:** continuous Live Mode could eat M2–M4 time — strictly gated behind
+  a green M3; scene-change detection quality unknown until prototyped.

kb/2026-06-11-small-cuts-hackathon-grounding.md

@@ -0,0 +1,31 @@
+---
+projectId: small-cuts
+id: 2026-06-11-small-cuts-hackathon-grounding
+---
+
+# Small Cuts — Hackathon Grounding (2026-06-11)
+
+Canonical detail lives in `docs/hackathon-rules.md` (same repo). Summary:
+
+- **Official name:** Build Small Hackathon — "Small Models, Big Adventures" (Gradio · Hugging Face)
+- **Official URL:** https://huggingface.co/build-small-hackathon
+- **Deadline:** submissions close **June 15, 2026** (time-of-day unverified)
+- **Submission format:** Gradio app as a **Space under the hackathon org** + demo video + social post
+- **Selected sidequests (decided 2026-06-11, pending Carlos confirmation):**
+  Off the Grid · Off-Brand · Llama Champion · Field Notes · (stretch: Well-Tuned)
+- **Judging criteria:** Track 2 — delight ("show a friend"), AI load-bearing,
+  originality, Gradio polish (verbatim in docs/hackathon-rules.md)
+- **Hard constraints:** total model params ≤ 32B; must be a Gradio Space
+- **Allowed/forbidden tools:** no explicit forbidden list found; "Off the Grid"
+  quest forbids cloud APIs *for that badge*. Modal credits provided ($250) but
+  using Modal at runtime would forfeit Off the Grid.
+- **Hardware/resources:** Ray-Ban Metas + 2 phones (capture/demo), Mac Studio
+  (dev/video), DGX Spark (model eval/fine-tune), $250 Modal + $20 HF credits,
+  40 min/day ZeroGPU via org membership.
+- **Implications:** Space-is-the-product; local small models inside the Space;
+  glasses are capture only. Full reasoning in docs/architecture.md.
+- **Open questions:** exact deadline time; video/post content requirements;
+  quest claiming mechanism; team status (Topi); Tiny Titan award definition.
+
+Evidence: Gmail threads 19e8db3f17a5a437 + 19e9480d1438494e (yuvraj@huggingface.co),
+raw README of build-small-hackathon/README space, org page (all fetched 2026-06-11).

kb/2026-06-11-small-cuts-product-strategy.md

@@ -0,0 +1,30 @@
+---
+projectId: small-cuts
+id: 2026-06-11-small-cuts-product-strategy
+---
+
+# Small Cuts — Product Strategy (2026-06-11)
+
+Canonical detail lives in `docs/product-strategy.md` (same repo). Essence:
+
+- **Experience:** an omniscient, slightly-too-honest cinematic narrator for
+  moments of your life (*The Invention of Lying*), delivered as a Gradio Space:
+  photo/clip in → director style → grounded 2–4 sentence narration → spoken TTS
+  → shareable title card. Re-cut with a different director = the delight loop.
+- **What the Director's Cut trajectory got right:** the concept; the Gradio
+  pivot; the local-model instinct (Qwen3-Omni).
+- **What it under-exploited:** iOS app is unjudgeable; Gemini Live forfeits
+  Off the Grid; glasses-as-infrastructure is demo-fragile; quests unclaimed.
+- **Why this can beat the original:** zero-friction judging, quest multipliers
+  (Off the Grid, Off-Brand, Llama Champion, Field Notes, + Well-Tuned stretch),
+  honest small-model fit, glasses preserved as the demo-video star.
+- **Core demo flow:** Ray-Ban POV footage → Space narrates it → re-cut in a
+  second genre → "everything under 32B, everything in this Space."
+- **Minimum lovable submission:** 6 styles, VLM+TTS local in Space, custom
+  theme, examples gallery — live by June 14.
+- **Stretch:** clip input, day reel, published LoRA narrator fine-tune.
+- **Riskiest assumptions:** small-VLM narration specificity; ZeroGPU latency;
+  TTS performance quality; submission mechanics.
+- **Milestones:** M0 bootstrap ✅ (today) · M1 real narration (Jun 12) ·
+  M2 TTS/theme (Jun 13) · M3 Space live (Jun 13–14) · M4 assets (Jun 14) ·
+  M5 submit (Jun 15 morning).

kb/2026-06-11-small-cuts-repo-bootstrap.md

@@ -0,0 +1,26 @@
+---
+projectId: small-cuts
+id: 2026-06-11-small-cuts-repo-bootstrap
+---
+
+# Small Cuts — Repo Bootstrap (2026-06-11)
+
+- **What changed:** `macayaven/small-cuts` went from empty to a working
+  skeleton on branch `claude/adoring-clarke-49l3uk`: Gradio vertical slice
+  (mock backend end-to-end), pluggable inference backends (mock /
+  transformers / llama_cpp), style presets + prompt builder, unit tests,
+  CI (ruff lint+format, pytest, gitleaks secret scan), full docs set, KB
+  note mirrors.
+- **Why:** 4 days to deadline; the judged artifact is a Gradio Space, so the
+  fastest path to a strong submission is a disciplined repo whose `app.py`
+  deploys to the Space unchanged, with CI guarding quality from commit one.
+- **Evidence / commands:** `uv run pytest` (green), `uv run ruff check .`
+  (clean), `SMALL_CUTS_BACKEND=mock python app.py` (UI smoke). CI workflow at
+  `.github/workflows/ci.yml` runs on push.
+- **Current status:** M0 complete. Branch pushed; PR + branch protection are
+  Carlos-side actions (no admin API in the bootstrap session).
+- **Next action:** M1 — model eval on DGX/Mac (3 candidate VLMs × fixed photo
+  set), pick narrator model, tune prompts.
+- **Risks:** narration specificity of small VLMs unvalidated; ZeroGPU latency;
+  submission mechanics unverified; canonical KB not yet updated (this note is
+  a mirror pending import).

kb/README.md

@@ -0,0 +1,14 @@
+# KB note mirrors
+
+The canonical knowledge base (`.knowledge/` + `knowledge_base-*` MCP tools)
+lives on the Mac Studio and was **not reachable from the cloud session that
+bootstrapped this repo** (no knowledge_base MCP server, no `.knowledge/`
+directory, no Tailnet).
+
+These markdown files are faithful, import-ready mirrors of the notes that the
+operating contract requires. Each file's front matter carries the intended
+`projectId` and `id`.
+
+**Action for the next Mac Studio session:** import each note via
+`knowledge_base-knowledge_save` using the front-matter `projectId`/`id`,
+then keep the canonical KB as source of truth (mirror here may lag).

pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "small-cuts"
+version = "0.1.0"
+description = "An omniscient cinematic narrator for moments of your life, powered by small open models (Build Small Hackathon)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "gradio>=5.0",
+    "pillow>=10.0",
+    "pillow-heif>=0.18",
+    "av>=12.0",
+    # core viewer dep: decodes seed durations + writes generated voice-overs (viewer.py),
+    # imported at module scope — must be in the base install (and CI), not just the tts extra.
+    "soundfile>=0.12",
+]
+
+[project.optional-dependencies]
+local = [
+    "transformers>=4.49",
+    "torch>=2.4",
+    "torchvision>=0.19",
+    "accelerate>=1.0",
+]
+tts = [
+    "kokoro>=0.9",
+    "soundfile>=0.12",
+]
+llama = [
+    "llama-cpp-python>=0.3",
+]
+engine = [
+    "fastapi>=0.110",
+    "uvicorn>=0.30",
+    "websockets>=12",
+    "jsonschema>=4.21",
+    "soundfile>=0.12",
+    "httpx>=0.27",
+]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8",
+    "jsonschema>=4.21",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/small_cuts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]

requirements.txt

@@ -0,0 +1,7 @@
+# Hugging Face Space runtime for live-demo viewer mode. Gradio + spaces are
+# platform-managed; inference and TTS run on the Mac Studio engine.
+pillow>=10.0
+pillow-heif>=0.18
+av>=12.0
+httpx>=0.27
+soundfile>=0.12

scripts/dress_rehearsal.py

@@ -0,0 +1,475 @@
+"""End-to-end dress rehearsal: simulate the iOS capture app against a RUNNING engine.
+
+Samples real glasses footage into N gated moments, sends contract-valid
+MomentEnvelopes over one ``/v1/session`` WebSocket, validates every frame the
+engine returns against docs/contracts, then audits the persisted library over
+HTTP. Emits a markdown latency report compared against the budget table in
+docs/product/architecture.md.
+
+Usage:
+    uv run python scripts/dress_rehearsal.py \
+        --engine ws://127.0.0.1:8077 \
+        --video /path/to/clip.MOV \
+        --moments 3 --style symmetrist \
+        --report docs/product/rehearsal.md
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+import io
+import json
+import statistics
+import sys
+import tempfile
+import time
+import uuid
+import wave
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+import httpx
+import jsonschema
+import websockets
+from PIL import Image
+
+from small_cuts.frames import sample_frames
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+CONTRACTS = REPO_ROOT / "docs" / "contracts"
+CONTRACT_VERSION = "1.1.0"
+MAX_FRAME_SIDE = 1024
+JPEG_QUALITY = 85
+MOMENT_TIMEOUT_S = 600.0  # first moment includes the llama-server cold spawn
+STATUS_IDLE_GRACE_S = 5.0
+PERSIST_GRACE_S = 15.0  # SceneAudio precedes the library write; allow it to land
+WS_MAX_MESSAGE_BYTES = 64 * 1024 * 1024  # SceneAudio WAVs are base64; default 1 MiB is too small
+
+# docs/product/architecture.md, "Latency budget v1"
+BUDGET_NARRATION_MS = 4_500
+BUDGET_TTS_MS = 4_000
+BUDGET_E2E_WARM_P50_MS = 10_000
+
+
+class RehearsalError(RuntimeError):
+    """Any contract or pipeline violation - the rehearsal fails loudly."""
+
+
+def _validator(name: str) -> jsonschema.Draft202012Validator:
+    schema = json.loads((CONTRACTS / name).read_text())
+    return jsonschema.Draft202012Validator(schema, format_checker=jsonschema.FormatChecker())
+
+
+MOMENT_VALIDATOR = _validator("moment.schema.json")
+CONTROL_VALIDATOR = _validator("control.schema.json")
+SCENE_AUDIO_VALIDATOR = _validator("scene-audio.schema.json")
+NARRATED_SCENE_VALIDATOR = _validator("narrated-scene.schema.json")
+
+
+@dataclass
+class MomentResult:
+    """Everything observed for one moment: outcome, audio, and timings."""
+
+    index: int
+    moment_id: str
+    wall_ms: int
+    scene_id: str = ""
+    narration: str = ""
+    wav_path: Path | None = None
+    wav_bytes: bytes = b""
+    wav_duration_s: float = 0.0
+    error: dict[str, Any] | None = None
+    engine_latency_ms: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+
+def pick_spread_frames(frames: list[Image.Image], count: int) -> list[Image.Image]:
+    """Pick `count` frames spread evenly across the clip (first..last)."""
+    if not frames:
+        raise RehearsalError("no frames sampled from the video")
+    if count <= 0:
+        raise RehearsalError(f"--moments must be positive, got {count}")
+    if len(frames) < count:
+        raise RehearsalError(f"video yielded {len(frames)} sampled frames; need {count}")
+    if count == 1:
+        return [frames[len(frames) // 2]]
+    step = (len(frames) - 1) / (count - 1)
+    return [frames[round(i * step)] for i in range(count)]
+
+
+def downscale(image: Image.Image) -> Image.Image:
+    """Longest side <= 1024 px, per the verified Qwen-VL constraint in the contract."""
+    image = image.convert("RGB")
+    if max(image.size) > MAX_FRAME_SIDE:
+        image.thumbnail((MAX_FRAME_SIDE, MAX_FRAME_SIDE), Image.Resampling.LANCZOS)
+    return image
+
+
+def build_envelope(
+    image: Image.Image,
+    session_id: str,
+    style_key: str,
+    seq: int,
+    captured_at: datetime,
+    prev_moment_id: str | None,
+) -> dict[str, Any]:
+    """One contract-valid MomentEnvelope; validation failure here is a harness bug."""
+    buffer = io.BytesIO()
+    image.save(buffer, format="JPEG", quality=JPEG_QUALITY)
+    envelope = {
+        "contract_version": CONTRACT_VERSION,
+        "moment_id": str(uuid.uuid4()),
+        "session_id": session_id,
+        "captured_at": captured_at.isoformat(),
+        "frames": [
+            {
+                "jpeg_b64": base64.b64encode(buffer.getvalue()).decode("ascii"),
+                "width": image.width,
+                "height": image.height,
+            }
+        ],
+        "gate": {"trigger": "interval"},
+        "context": {"style_key": style_key, "network": "wifi"},
+        "prev_moment_id": prev_moment_id,
+        "seq": seq,
+        "sent_at": datetime.now(timezone.utc).isoformat(),
+    }
+    error = jsonschema.exceptions.best_match(MOMENT_VALIDATOR.iter_errors(envelope))
+    if error is not None:
+        raise RehearsalError(f"harness built a contract-INVALID MomentEnvelope: {error.message}")
+    return envelope
+
+
+def validate_incoming(frame: dict[str, Any]) -> str:
+    """Validate one engine frame against the contracts; returns 'control' or 'scene_audio'."""
+    if "kind" in frame:
+        error = jsonschema.exceptions.best_match(CONTROL_VALIDATOR.iter_errors(frame))
+        if error is not None:
+            raise RehearsalError(f"contract-invalid ControlFrame from engine: {error.message}")
+        return "control"
+    error = jsonschema.exceptions.best_match(SCENE_AUDIO_VALIDATOR.iter_errors(frame))
+    if error is not None:
+        raise RehearsalError(f"contract-invalid SceneAudio from engine: {error.message}")
+    return "scene_audio"
+
+
+def verify_wav(data: bytes, label: str) -> float:
+    """RIFF/WAVE magic + nonzero duration; returns duration in seconds."""
+    if data[:4] != b"RIFF" or data[8:12] != b"WAVE":
+        raise RehearsalError(f"{label}: not a RIFF/WAVE file (magic {data[:12]!r})")
+    with wave.open(io.BytesIO(data)) as wav:
+        frames = wav.getnframes()
+        rate = wav.getframerate()
+    if frames <= 0 or rate <= 0:
+        raise RehearsalError(f"{label}: zero-duration WAV ({frames} frames @ {rate} Hz)")
+    return frames / rate
+
+
+async def drain_until_idle(ws: websockets.ClientConnection, results: list[str]) -> None:
+    """Honor backpressure: after a terminal frame, wait for status busy=false."""
+    deadline = time.monotonic() + STATUS_IDLE_GRACE_S
+    while time.monotonic() < deadline:
+        try:
+            raw = await asyncio.wait_for(ws.recv(), timeout=deadline - time.monotonic())
+        except (TimeoutError, asyncio.TimeoutError):
+            return  # engine already idle and silent - safe to proceed
+        frame = json.loads(raw)
+        validate_incoming(frame)
+        if frame.get("kind") == "status":
+            results.append(f"status busy={frame['status'].get('busy')}")
+            if not frame["status"].get("busy", False):
+                return
+
+
+async def run_moment(
+    ws: websockets.ClientConnection,
+    envelope: dict[str, Any],
+    index: int,
+    wav_dir: Path,
+) -> MomentResult:
+    """Send one envelope and await its terminal frame (SceneAudio or error)."""
+    moment_id = envelope["moment_id"]
+    started = time.perf_counter()
+    await ws.send(json.dumps(envelope))
+
+    acked = False
+    while True:
+        elapsed = time.perf_counter() - started
+        if elapsed > MOMENT_TIMEOUT_S:
+            raise RehearsalError(f"moment {index}: no terminal frame after {MOMENT_TIMEOUT_S}s")
+        raw = await asyncio.wait_for(ws.recv(), timeout=MOMENT_TIMEOUT_S - elapsed)
+        frame = json.loads(raw)
+        kind = validate_incoming(frame)
+
+        if kind == "control":
+            if frame["kind"] == "ack":
+                if frame["moment_id"] != moment_id:
+                    raise RehearsalError(f"moment {index}: ack for foreign id {frame['moment_id']}")
+                result = frame["ack"]["result"]
+                if result != "accepted":
+                    raise RehearsalError(f"moment {index}: not accepted ({result})")
+                acked = True
+                print(f"  moment {index}: accepted")
+            elif frame["kind"] == "error":
+                wall_ms = round((time.perf_counter() - started) * 1000)
+                print(f"  moment {index}: ERROR {frame['error']}")
+                return MomentResult(index, moment_id, wall_ms, error=frame["error"])
+            # status frames: informational while waiting on our own moment
+            continue
+
+        # SceneAudio: the success terminal frame
+        wall_ms = round((time.perf_counter() - started) * 1000)
+        if not acked:
+            raise RehearsalError(f"moment {index}: SceneAudio arrived before any ack")
+        if frame["moment_id"] != moment_id:
+            raise RehearsalError(f"moment {index}: SceneAudio for foreign id {frame['moment_id']}")
+        wav_bytes = base64.b64decode(frame["audio_b64"])
+        duration = verify_wav(wav_bytes, f"moment {index} SceneAudio WAV")
+        wav_path = wav_dir / f"moment-{index}-{frame['scene_id']}.wav"
+        wav_path.write_bytes(wav_bytes)
+        narration = frame.get("narration", "")
+        print(f"  moment {index}: SceneAudio in {wall_ms} ms ({duration:.1f}s audio)")
+        return MomentResult(
+            index=index,
+            moment_id=moment_id,
+            wall_ms=wall_ms,
+            scene_id=frame["scene_id"],
+            narration=narration,
+            wav_path=wav_path,
+            wav_bytes=wav_bytes,
+            wav_duration_s=duration,
+        )
+
+
+async def websocket_phase(
+    engine_ws: str, envelopes: list[dict[str, Any]], wav_dir: Path
+) -> list[MomentResult]:
+    """One session socket; moments sent sequentially for clean latency numbers."""
+    ws_url = f"{engine_ws.rstrip('/')}/v1/session"
+    print(f"connecting {ws_url}")
+    results: list[MomentResult] = []
+    status_log: list[str] = []
+    async with websockets.connect(ws_url, max_size=WS_MAX_MESSAGE_BYTES) as ws:
+        for index, envelope in enumerate(envelopes, start=1):
+            results.append(await run_moment(ws, envelope, index, wav_dir))
+            if index < len(envelopes):
+                await drain_until_idle(ws, status_log)
+    return results
+
+
+def http_phase(
+    http_base: str, session_id: str, results: list[MomentResult]
+) -> list[dict[str, Any]]:
+    """Verify persistence: /v1/scenes lists contract-valid scenes; media bytes match."""
+    ok_results = [r for r in results if r.ok]
+    with httpx.Client(base_url=http_base, timeout=30.0) as client:
+        # SceneAudio is sent to the client BEFORE the library sink commits, so
+        # the final write may still be in flight — poll briefly before failing.
+        deadline = time.monotonic() + PERSIST_GRACE_S
+        while True:
+            response = client.get("/v1/scenes", params={"session": session_id})
+            response.raise_for_status()
+            scenes = response.json()["scenes"]
+            if len(scenes) >= len(ok_results) or time.monotonic() > deadline:
+                break
+            time.sleep(0.25)
+        if len(scenes) != len(ok_results):
+            raise RehearsalError(
+                f"library has {len(scenes)} scenes for session {session_id}; "
+                f"expected {len(ok_results)}"
+            )
+        by_id = {scene["scene_id"]: scene for scene in scenes}
+        for result in ok_results:
+            scene = by_id.get(result.scene_id)
+            if scene is None:
+                raise RehearsalError(f"scene {result.scene_id} missing from /v1/scenes")
+            error = jsonschema.exceptions.best_match(NARRATED_SCENE_VALIDATOR.iter_errors(scene))
+            if error is not None:
+                raise RehearsalError(
+                    f"scene {result.scene_id} is contract-INVALID: {error.message}"
+                )
+            result.engine_latency_ms = scene["engine"]["latency_ms"]
+
+        # One media spot-check: the frame JPEG and the voice WAV must serve real bytes.
+        probe = ok_results[0]
+        jpg = client.get(f"/media/{probe.scene_id}/frame.jpg")
+        jpg.raise_for_status()
+        if jpg.content[:2] != b"\xff\xd8":
+            raise RehearsalError(f"/media frame.jpg is not a JPEG (magic {jpg.content[:4]!r})")
+        wav = client.get(f"/media/{probe.scene_id}/voice.wav")
+        wav.raise_for_status()
+        verify_wav(wav.content, "/media voice.wav")
+        if wav.content != probe.wav_bytes:
+            raise RehearsalError("/media voice.wav differs from the WS-delivered SceneAudio WAV")
+        print(
+            f"library check: {len(scenes)} scenes persisted; media verified "
+            f"(frame.jpg {len(jpg.content)} B, voice.wav {len(wav.content)} B)"
+        )
+    return scenes
+
+
+def _check(value: int | None, budget: int) -> str:
+    if value is None:
+        return "n/a"
+    return "PASS" if value <= budget else "FAIL"
+
+
+def build_report(
+    args: argparse.Namespace,
+    session_id: str,
+    results: list[MomentResult],
+    scenes: list[dict[str, Any]],
+) -> str:
+    """Markdown report: per-moment table, budget comparison, full narrations."""
+    engine_meta = scenes[0]["engine"] if scenes else {}
+    lines = [
+        f"# Dress rehearsal — {datetime.now(timezone.utc).date().isoformat()}",
+        "",
+        f"- Engine: `{args.engine}` (session `{session_id}`)",
+        f"- Video: `{args.video}` — {args.moments} gated moments, style `{args.style}`",
+        f"- Narrator: `{engine_meta.get('narrator_model', '?')}` "
+        f"via `{engine_meta.get('narrator_backend', '?')}`",
+        f"- TTS: `{engine_meta.get('tts_model', '?')}`",
+        "",
+        "## Per-moment latency",
+        "",
+        "Engine numbers come from the persisted scene's `engine.latency_ms`; wall is the",
+        "client-measured send→SceneAudio round trip (includes WS transfer + queueing).",
+        "",
+        "| # | Narration (first 80 chars) | narration_ms | tts_ms | total_ms (engine) "
+        "| wall_ms (client) | narration ≤4500 | tts ≤4000 |",
+        "|---|---|---|---|---|---|---|---|",
+    ]
+    for r in results:
+        if not r.ok:
+            err = r.error or {}
+            lines.append(
+                f"| {r.index} | ERROR {err.get('stage')}/{err.get('code')}: "
+                f"{str(err.get('message', ''))[:60]} | — | — | — | {r.wall_ms} | FAIL | FAIL |"
+            )
+            continue
+        narration_ms = r.engine_latency_ms.get("narration")
+        tts_ms = r.engine_latency_ms.get("tts")
+        total_ms = r.engine_latency_ms.get("total")
+        excerpt = r.narration[:80].replace("|", "\\|")
+        lines.append(
+            f"| {r.index} | {excerpt} | {narration_ms} | {tts_ms} | {total_ms} "
+            f"| {r.wall_ms} | {_check(narration_ms, BUDGET_NARRATION_MS)} "
+            f"| {_check(tts_ms, BUDGET_TTS_MS)} |"
+        )
+
+    ok = [r for r in results if r.ok]
+    # Moment 1 absorbs the cold start (llama-server spawn + Kokoro weight load);
+    # the architecture budgets are explicitly for WARM stages.
+    warm = ok[1:] if len(ok) > 1 else ok
+    p50_all = round(statistics.median(r.wall_ms for r in ok)) if ok else None
+    p50_warm = round(statistics.median(r.wall_ms for r in warm)) if warm else None
+    warm_narration = max((r.engine_latency_ms.get("narration", 0) for r in warm), default=None)
+    warm_tts = max((r.engine_latency_ms.get("tts", 0) for r in warm), default=None)
+    cold = ok[0] if ok else None
+    lines += [
+        "",
+        "## Budget comparison (docs/product/architecture.md, Latency budget v1)",
+        "",
+        "Warm = moments after the first; moment 1 pays the llama-server spawn and",
+        "Kokoro weight load once per engine process.",
+        "",
+        "| Budget line | Target | Measured (warm max) | Verdict |",
+        "|---|---|---|---|",
+        f"| Narration, warm llama.cpp | ≤ {BUDGET_NARRATION_MS} ms | {warm_narration} ms "
+        f"| {_check(warm_narration, BUDGET_NARRATION_MS)} |",
+        f"| TTS, warm Kokoro | ≤ {BUDGET_TTS_MS} ms | {warm_tts} ms "
+        f"| {_check(warm_tts, BUDGET_TTS_MS)} |",
+        f"| End-to-end warm p50 (client wall) | ≤ {BUDGET_E2E_WARM_P50_MS} ms | {p50_warm} ms "
+        f"| {_check(p50_warm, BUDGET_E2E_WARM_P50_MS)} |",
+        "",
+    ]
+    if cold is not None:
+        lines.append(
+            f"Cold first moment: narration {cold.engine_latency_ms.get('narration')} ms, "
+            f"tts {cold.engine_latency_ms.get('tts')} ms, "
+            f"wall {cold.wall_ms} ms (one-time per engine process)."
+        )
+    lines += [
+        f"All-moments e2e p50 including the cold first moment: {p50_all} ms.",
+        f"Moments narrated: {len(ok)}/{len(results)}; "
+        f"audio: {', '.join(f'{r.wav_duration_s:.1f}s' for r in ok)}.",
+        "",
+        "## Full narrations",
+        "",
+    ]
+    for r in results:
+        if r.ok:
+            lines += [f"**Moment {r.index}** (scene `{r.scene_id}`):", "", f"> {r.narration}", ""]
+        else:
+            lines += [f"**Moment {r.index}**: pipeline error `{r.error}`", ""]
+    return "\n".join(lines)
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--engine", default="ws://127.0.0.1:8077", help="engine WS base URL")
+    parser.add_argument("--video", required=True, help="source video (real glasses footage)")
+    parser.add_argument("--moments", type=int, default=3, help="gated moments to send")
+    parser.add_argument("--style", default="symmetrist", help="director style_key")
+    parser.add_argument("--report", default="", help="markdown report path (also printed)")
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    video = Path(args.video)
+    if not video.is_file():
+        raise RehearsalError(f"video not found: {video}")
+    http_base = args.engine.rstrip("/").replace("ws://", "http://").replace("wss://", "https://")
+    session_id = f"rehearsal-{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}"
+
+    print(f"sampling frames from {video.name} ...")
+    frames = sample_frames(video, every_n_seconds=2.0)
+    picked = pick_spread_frames(frames, args.moments)
+    print(f"sampled {len(frames)} frames; picked {len(picked)} spread-out moments")
+
+    base_capture = datetime.now(timezone.utc)
+    envelopes: list[dict[str, Any]] = []
+    prev_id: str | None = None
+    for seq, frame in enumerate(picked):
+        envelope = build_envelope(
+            downscale(frame),
+            session_id=session_id,
+            style_key=args.style,
+            seq=seq,
+            captured_at=base_capture + timedelta(seconds=seq),
+            prev_moment_id=prev_id,
+        )
+        prev_id = envelope["moment_id"]
+        envelopes.append(envelope)
+    print(f"built {len(envelopes)} contract-valid MomentEnvelopes (session {session_id})")
+
+    wav_dir = Path(tempfile.mkdtemp(prefix="dress-rehearsal-"))
+    results = asyncio.run(websocket_phase(args.engine, envelopes, wav_dir))
+    scenes = http_phase(http_base, session_id, results)
+
+    report = build_report(args, session_id, results, scenes)
+    print("\n" + report)
+    if args.report:
+        report_path = Path(args.report)
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(report + "\n")
+        print(f"\nreport written to {report_path}")
+
+    return 0 if all(r.ok for r in results) else 1
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except RehearsalError as exc:
+        print(f"DRESS REHEARSAL FAILED: {exc}", file=sys.stderr)
+        sys.exit(2)

scripts/hooks/block-secrets.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# PreToolUse guard — block edits/writes to secrets files (Small Cuts no-secrets policy).
+# Receives the hook payload as JSON on stdin; exit code 2 blocks the tool and shows stderr.
+f="$(python3 -c 'import json,sys
+try:
+    d = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+print((d.get("tool_input") or {}).get("file_path", "") or "")' 2>/dev/null)"
+b="$(basename -- "$f" 2>/dev/null)"
+case "$b" in
+  .env | .env.* | *.env | op-connect.env | op-service-account.env | *.pem | *.key | .npmrc)
+    echo "🚫 Blocked edit to '$f' — that looks like a secrets file. Small Cuts keeps secrets in 1Password Connect, never in the repo (gitleaks would also fail CI)." >&2
+    exit 2
+    ;;
+esac
+exit 0