README: demo video link, loading-time note, lean/full guidance, point to apprentice field notes

README.md

@@ -32,73 +32,76 @@ models:
 
 # The Apprentice — Build Small Hackathon
 
-> A pixel-art branching fairy-tale game. You inscribe five short oracles before the journey begins; an apprentice has to make every one of them save his life across five trials in a branching graph that converges on one of five distinct endings.
+> A pixel-art branching fairy-tale. You inscribe five short oracles before the journey begins; an apprentice has to make every one of them save his life across five trials in a tree that converges on one of five distinct endings.
 
-**Track**: Thousand Token Wood
-**Stack**: Gradio + Modal-hosted vLLM + Qwen2.5-14B + custom humor LoRA
-**Languages**: English + Simplified Chinese
-**Demo video**: _(to be added by submitter)_
-**Social post**: _(to be added by submitter)_
+- **Track**: Thousand Token Wood
+- **Stack**: Docker + Gradio + Modal-hosted vLLM + Qwen2.5-14B + custom humor LoRA
+- **Languages**: English + 简体中文
+- **Demo video**: https://youtu.be/Ica9BgX5ZDk
+- **Social post**: _(to be added by submitter)_
+- **Field notes**: [`docs/FIELD_NOTES_apprentice.md`](../docs/FIELD_NOTES_apprentice.md)
 
----
+> **⏱ Note on loading time**: this Space ships ~100 pixel-art sprites + theme backdrops. HF Space's free CPU tier has slow egress bandwidth, so first paint of a fresh container can take a minute or two; subsequent page transitions are faster as the browser caches assets. The front-page dropdown lets you flip between **Lean** (small payload, fast loading, default on the Space) and **Full** (parallax banner, scene landscapes, all decorative PNGs — recommended only on a fast connection or once the Space is warm).
 
-## What's in the box
+## What's inside
 
-| Component | Detail |
-|---|---|
-| **Frontend** | Single-file Gradio app (~5000 lines) with a hand-authored pixel-art aesthetic — Press Start 2P + VT323 fonts, NES-style sharp corners, layered animated scene composition, custom theme that suppresses every visible piece of Gradio chrome. |
-| **Backend** | Qwen2.5-14B-Instruct + custom humor LoRA (`AndrewRqy/oracles-wizard-14b-lora`) served via vLLM on Modal. OpenAI-compatible API; the frontend talks to it through the OpenAI SDK. |
-| **Tiny Titan path** | Qwen2.5-1.5B-Instruct + LoRA, also trained on the same 23k humor corpus (`AndrewRqy/oracles-wizard-1.5b-lora`). Eligible for the ≤4B prize. |
-| **Branching narrative** | Hand-authored 15-node story graph with 5 distinct endings. Each fork at trials 2–4 is picked by an LLM call seeded with the player's inscribed oracle, so the path the apprentice walks is shaped by what wisdom was inscribed. |
-| **6 themes × 2 languages** | Fantasy, Space-Cowboy, Galactic-Light, Black-Land, Mistgate, Quiet-Years — each with its own sprite set, finale boss, themed obstacle scenes (finale / arena / passage / trap), localized banner + oracle artifact + apprentice role title. All authored for both English and Chinese. |
-| **Klein-4B sprites** | All in-game art (~105 pixel-art sprites + 4 environment backdrops per theme) was generated locally via Klein-4B on a Modal H100, then chroma-keyed offline. No FLUX, no commercial generators. |
+- **Frontend** — Single-file Gradio app with a hand-authored pixel-art aesthetic. Press Start 2P + VT323 fonts, NES-style sharp corners, custom theme suppressing all default Gradio chrome.
+- **Backend** — Qwen2.5-14B + custom humor LoRA (`AndrewRqy/oracles-wizard-14b-lora`) served via vLLM on Modal. Frontend talks to it through the OpenAI SDK.
+- **Tiny Titan path** — Same 23k humor corpus trained into a Qwen2.5-1.5B LoRA (`AndrewRqy/oracles-wizard-1.5b-lora`). Eligible for the ≤4B prize.
+- **Branching narrative** — Hand-authored 15-node story tree with 5 endings. Each fork at trials 2–4 is decided by an LLM call seeded with one of the player's oracles, so the path the apprentice walks is shaped by what was inscribed.
+- **6 themes × 2 languages** — Fantasy, Space-Cowboy, Galactic-Light, Black-Land, Mistgate, Quiet-Years. Theme-neutral story nodes + per-theme vocabulary expansion at runtime.
+- **All art generated locally** — ~105 pixel-art sprites via Klein-4B on a Modal H100, chroma-keyed offline. No FLUX, no commercial generators.
 
 ## How to play
 
-1. **Inscribe** — pick a language, then a theme, then write five short oracles (any words, gibberish, emoji — whatever you want).
-2. **Send-off** — the mentor seals the parchments and the apprentice leaves.
-3. **Five trials** — at each obstacle, the apprentice draws ONE oracle. The model takes the obstacle + the oracle and writes a 200-word resolution in one of three humor modes (wild imagination / accidental trip / last-minute revelation).
-4. **Boss** — trial 5 is the world's finale (the dragon for fantasy; the warlord-king for space-cowboy; etc.). Different paths through the tree lead to different bosses.
-5. **Ending** — one of 5 distinct endings plays, each with its own preset framing (Why the boss behaved as it did + What the apprentice carried home) and an LLM-expanded 3-paragraph epilogue.
-6. **Summary** — clicking through reveals the story tree with the path you took lit gold and the four endings you didn't reach blurred behind "???" for replay motivation.
+1. **Inscribe** — pick a language, theme, visual mode, and narration length. Then write five short oracles. Any words; gibberish counts, emoji counts.
+2. **Send-off** — the mentor seals the parchments. The apprentice leaves.
+3. **Five trials** — at each obstacle, the apprentice draws ONE oracle. The model takes the obstacle + oracle and writes a ~200-word resolution in one of three humor modes (wild imagination / accidental trip / last-minute revelation).
+4. **Boss** — trial 5 is the world's finale (dragon, warlord-king, etc.). Different paths through the tree lead to different bosses.
+5. **Ending** — one of 5 distinct endings plays, each with a hand-authored framing (why the boss behaved as it did + what the apprentice carried home), expanded by the LLM into a 3-paragraph epilogue.
+6. **Summary** — the story tree shows the path you walked lit gold; the four endings you didn't reach blur behind "???" for replay.
 
 ## Badge claims
 
 | Badge | Why we claim it |
 |---|---|
-| **🎯 Well-Tuned** | Qwen2.5-14B + a hand-distilled 23k-example humor LoRA (rank 16, ~6.5 h on H100). The fine-tune visibly steers all three humor modes; the field-notes write-up below details the distillation pipeline. |
-| **🎨 Off-Brand** | ~2000 lines of bespoke CSS, Press Start 2P + VT323 fonts, hand-painted pixel-art sprites, sharp-corner theme that overrides every visible Gradio token, custom story-tree visualization, custom ending banner with five-pip "endings discovered" strip. No stock Gradio chrome reaches the rendered page. |
-| **📓 Field Notes** | See `docs/FIELD_NOTES_distillation.md` — a ~950-word blog post on the schema-locked Claude-Sonnet-4.5 → Qwen distillation pipeline, the three humor modes, the JSON enforcement layers, and what 98.4% reject-sampling acceptance got us. |
-| **⚡ Tiny Titan (prize)** | Same 23k corpus also trained into a Qwen2.5-1.5B LoRA on H100 (~$5.50, ~1.5 h). Eligible for the ≤4B prize. |
+| 🎯 **Well-Tuned** | Qwen2.5-14B + a hand-distilled 23k-example humor LoRA (rank 16, ~6.5h on H100). Visibly steers all three humor modes; details in field notes. |
+| 🎨 **Off-Brand** | ~2000 lines of bespoke CSS, Press Start 2P + VT323 fonts, hand-painted pixel-art sprites, custom story-tree visualization, custom ending banner. No stock Gradio chrome reaches the page. |
+| 📓 **Field Notes** | [`docs/FIELD_NOTES_apprentice.md`](../docs/FIELD_NOTES_apprentice.md) — a build diary covering what we designed and what broke. |
+| ⚡ **Tiny Titan** | Same 23k corpus trained into a Qwen2.5-1.5B LoRA (~$5.50, ~1.5h on H100). Eligible for the ≤4B prize. |
 
-## Running it (locally or on Space)
+## Running it
 
-Three environment variables need to be set as **secrets** (HF Space Settings → Variables and secrets):
+Three environment variables go in HF Space → **Settings → Variables and secrets** (or `.env.local` for local runs):
 
 ```
-MODAL_URL     = https://<modal-workspace>--<app-name>-serve.modal.run
+MODAL_URL     = https://<workspace>--<app>-serve.modal.run
 MODAL_KEY     = wk-…  (Modal proxy auth key)
 MODAL_SECRET  = ws-…  (Modal proxy auth secret)
 ```
 
-Once those are set, the Space spins up the Gradio app and the player can immediately walk a trial. No GPU is needed on the Space side — the LLM call streams in from Modal over HTTPS.
+Locally:
+
+```bash
+./run.sh              # lean mode, default
+./run.sh --full       # all visual assets enabled (recommended on fast connections)
+```
 
-If `MODAL_URL` is unset OR `ORACLES_FORCE_MOCK=1`, the app runs in **mock mode** — every LLM call returns a hand-written placeholder, the visuals still play, but the humor is dead. Useful for offline demos.
+If `MODAL_URL` is unset OR `ORACLES_FORCE_MOCK=1`, the app runs in **mock mode** — the UI still works, but narrations are hand-written placeholders.
 
-## Repository layout
+## Repo layout
 
 ```
 oracles_app/
-├── app.py                    main Gradio file (~5000 lines)
-├── README.md                 this file (HF Space metadata + write-up)
-├── requirements.txt          gradio + openai + Pillow
-├── .gitignore                excludes dev artifacts from the Space upload
-├── oracles/                  pure-Python package (state, LLM client, story graph, themes, i18n)
-├── prompts/                  LLM prompt templates (resolution / epilogue / interludes / obstacles)
-└── assets/sprites/           ~105 chroma-keyed pixel-art PNGs
+├── app.py                # main Gradio file
+├── Dockerfile            # HF Space Docker SDK entry
+├── requirements.txt
+├── oracles/              # state, LLM client, story graph, themes, i18n
+├── prompts/              # LLM prompt templates
+└── assets/sprites/       # ~105 chroma-keyed pixel-art PNGs
 ```
 
-The dev-only directories (`modal_backend/`, `scripts/`, `training/`, `tests/`, `lora-out/`, `*_raw.png`) live in this folder on local disk but are excluded from the HF Space upload by `.gitignore`.
+Dev-only dirs (`modal_backend/`, `scripts/`, `training/`, `tests/`, `lora-out/`) live on local disk but are `.gitignore`d from the Space upload.
 
 ## Credits