Add field notes (lessons learned) to README and FIELD_NOTES.md

FIELD_NOTES.md

@@ -0,0 +1,75 @@
+# Field Notes — Building Tabras
+
+What I learned building a small-model card duel for the Build Small hackathon.
+
+## 1. ZeroGPU is a GPU-sharing mechanism, not a hosted GPU provider
+
+This was my biggest wall, and I hit it late. I built Tabras assuming a Hugging Face
+ZeroGPU Space would behave like a hosted GPU I could just run my models on. It does
+not. ZeroGPU *time-slices* a shared GPU and only grants it inside `@spaces.GPU`
+functions — and it ships args/returns between processes by pickling them. That
+breaks the moment you try to hand it a `trust_remote_code` model (MiniCPM) or a
+diffusers pipeline: they aren't picklable, and low-level CUDA init isn't allowed in
+the main process at all. I burned real time learning this through a wall of
+`PicklingError` and "CUDA init reached" tracebacks.
+
+The last-minute fix was to **re-architect**: make the Space a thin HTTP client and
+move every model onto **Modal** GPU endpoints (MiniCPM for cards, Nemotron for the
+boss, SDXL-Turbo for art), each autoscaled on its own dedicated GPU. The Space just
+POSTs prompts and renders the results. Lesson: understand the *execution model* of
+your compute before you design around it, not after.
+
+Crucially, Tabras still runs **fully local / off-grid** — a `MODE` switch flips
+between LOCAL (in-process Transformers/Diffusers, or a local `llama.cpp` server for
+MiniCPM) and MODAL (the hosted endpoints). The README has the local instructions.
+Small and local was always the point, and keeping that path alive mattered to me.
+
+## 2. Small models: surprisingly powerful, with sharp edges
+
+- **Image models punch way above their size.** SDXL-Turbo, in ~4 denoising steps,
+  produced genuinely striking card art and theme backgrounds. The visual identity of
+  the whole game is carried by a tiny, fast diffusion model.
+- **Nemotron was the standout for agentic / tool-calling work.** Giving it the public
+  board state and a constrained JSON action schema, it reliably reads the situation
+  and returns valid, sensible plays. A 4B model running a competent opponent was the
+  part I expected to be flaky and wasn't.
+- **The text model owns meaning, not structure.** MiniCPM writes evocative names and
+  flavor, but it leans on lazy patterns ("Fire Card"), leaks prompt vocabulary, and
+  truncates its own JSON. The single highest-leverage fix was reordering the requested
+  JSON so `effects` and `name` come *first* — they survive a token cutoff that used to
+  silently collapse a whole card to a fallback. Design around what the model is bad at.
+
+## 3. Perceived latency beats raw latency
+
+Small/local inference isn't instant, and the variance (some packs fast, some slow)
+looked worse than a consistent wait. The fixes that made the demo feel *good* were
+mostly UX, not compute:
+
+- A **minimum loading window** on each draft transition, so every pick shows the same
+  deliberate "forging" beat — that uniform pause hides the slow ones behind the same
+  animation the fast ones use.
+- **Prefetching every branch** of the draft during idle time (the reveal/rules screens,
+  and while you read the current pack), so whichever card you pick, its next pack is
+  already generating.
+- **Pre-baking static art** for the fixed backbone cards once and bundling it, so they
+  never spend a live generation or shimmer.
+
+A consistent 2s always beats an unpredictable 0–8s.
+
+## 4. Card-game design is hard — and a ton of fun
+
+Balancing a generative card game is genuinely difficult. The core principle that made
+it tractable: **the LLM owns meaning, the engine owns math.** The model picks *which*
+effects a card has and writes its identity; deterministic Python prices every number
+against a point budget, so cards are balanced-by-construction no matter what the model
+invents. The draft is deck-aware — it reads the build you're assembling and shapes
+packs toward it, sometimes dangling a tempting off-archetype card. Getting that loop to
+feel fair *and* surprising was the most fun part of the whole project.
+
+## 5. Ambition under a deadline
+
+This was an ambitious build for the time window — three small models, a custom UI, a
+last-minute compute re-architecture, and a real game loop. The thing that saved me was
+treating the **demo video as the deliverable** and optimizing the local recording
+surface hard, rather than betting everything on a flawless live Space. I'm proud of how
+much of it came together, and I had a lot of fun doing it.

README.md

@@ -54,6 +54,34 @@ Demo video: https://youtu.be/qHuk9XjaFWU
 
 Social post: https://x.com/yewzoid/status/2066647997740691678?s=20
 
+## Field Notes — What I Learned
+
+Full write-up in [FIELD_NOTES.md](FIELD_NOTES.md). The short version:
+
+- **ZeroGPU is a GPU-*sharing* mechanism, not a hosted GPU provider.** I found this out
+  late. ZeroGPU time-slices a shared GPU inside `@spaces.GPU` calls and pickles
+  args/returns between processes — which breaks on `trust_remote_code` models and
+  diffusers pipelines (unpicklable), and forbids CUDA init in the main process. I had to
+  **re-architect at the last minute**: make the Space a thin HTTP client and move every
+  model onto **Modal** GPU endpoints. It still runs **fully local / off-grid** through a
+  `MODE` switch (in-process Transformers/Diffusers, or a local `llama.cpp` server for
+  MiniCPM) — small-and-local was always the point.
+- **Small models are surprisingly capable, with sharp edges.** SDXL-Turbo makes genuinely
+  striking art in ~4 steps; Nemotron was impressive at agentic, tool-calling boss play
+  from a constrained JSON action schema. MiniCPM owns *meaning* (names, flavor) but not
+  *structure* — the biggest fix was reordering the requested JSON so `effects`/`name`
+  come first and survive a token cutoff.
+- **Perceived latency beats raw latency.** A minimum loading window per draft pick (a
+  uniform "forging" beat) hides the slow packs behind the same animation as the fast
+  ones; prefetching every branch during idle screens makes picks feel instant; and
+  pre-baking the fixed backbone-card art means it never shimmers.
+- **Generative card-game design is hard and a ton of fun.** The principle that made it
+  tractable: *the LLM owns meaning, the engine owns math* — the model invents the card,
+  deterministic code prices every number, so cards are balanced by construction.
+- **Ambitious for the deadline, and I'm happy with it.** Three small models, a custom UI,
+  a compute re-architecture, and a real game loop. Treating the demo video as the
+  deliverable — and optimizing the local recording surface — is what made it land.
+
 ## What Makes It AI-Native
 
 - **MiniCPM authors draft cards.** It proposes card concepts, names, flavor text, and effect shapes for the current deck.