Add GIF support in .gitattributes and include new media assets for gameplay, cover, and comic reveal

.gitattributes

@@ -4,3 +4,4 @@
 *.jpeg filter=lfs diff=lfs merge=lfs -text
 *.ico filter=lfs diff=lfs merge=lfs -text
 *.mp3 filter=lfs diff=lfs merge=lfs -text
+*.gif filter=lfs diff=lfs merge=lfs -text

README.md

@@ -10,109 +10,88 @@ license: mit
 short_description: Argue your way to $1M before the quarter ends
 ---
 
-# Brad Did Something
+# 🚀 Brad Did Something
 
-2D top-down office comedy game. You are the Head of Sales and Partnerships at
-Veloura Technologies. Five unhinged underlings, 15 events, one quarter, one
-million dollars. The Office meets Silicon Valley, in cozy daylight pixel art.
+![Brad Did Something](docs/media/cover.gif)
 
-All NPC dialogue and outcomes are generated by llama.cpp (Qwen3.5-9B)
-running on Modal, with JSON-schema-enforced output validated in Python before
-anything reaches the screen.
+> *Corporate bureaucracy is already a chaotic simulation — I just replaced middle management with an LLM to see if the company could survive the quarter.*
 
-## Run locally
+A 2D top-down **office comedy game** where every line your coworkers say, every
+unhinged decision, and every dollar of revenue is **generated live by an LLM**.
+You're the new Head of Sales at Veloura Technologies; your five underlings are
+enthusiastic, well-meaning, and completely off the rails. Survive **15 workplace
+crises** and one fiscal quarter, and hit **$1,000,000** — by literally *arguing
+your way there*.
 
-```
-pip install -r requirements.txt
-python app.py            # → http://localhost:7860
-```
+**🎮 [Play it now](https://huggingface.co/spaces/build-small-hackathon/brad-did-something) · ▶️ [Watch the trailer](https://youtu.be/BJSE5WDZvPs)**
 
-With no `MODAL_URL` set, the game runs in **mock mode** — fully playable, with
-a template-based offline generator standing in for the model.
+![Gameplay](docs/media/gameplay.gif)
 
-## Wire up live inference (Modal)
+## Not just a chatbot in a trenchcoat
 
-Already deployed to the `qfelix0112` workspace — endpoint:
-`https://qfelix0112--brad-did-something-llama-generate.modal.run`
-(L4 GPU, warm calls 2-4s, stays warm 5 min between calls). The auth token
-lives in `.bds_modal_token` (gitignored — never commit/upload it).
+- **🧠 The AI is load-bearing.** NPC dialogue isn't decoration — through strict
+  JSON-schema validation the model's output *directly drives the game economy*.
+  Talk Brad into rescuing a deal and revenue jumps; offend him and the pipeline
+  collapses. The server hides the morale & relationship scores, so the model
+  moves them without ever seeing (or gaming) them.
+- **🎨 Comics on the fly.** Each crisis, the text model writes a scene and a
+  second GPU renders a wordless **FLUX.2 [klein] 4B** comic panel that drops over
+  the office — the caption is drawn crisp by the UI (FLUX can't spell, so words
+  stay out of the image).
+- **🕹️ A genuinely custom frontend.** A hand-built HTML5-canvas + DOM pixel-art
+  game served through **`gr.Server`** — zero default Gradio widgets, desktop **and**
+  touch.
+- **⚙️ Small models, tight plumbing.** Qwen3.5-9B (llama.cpp) for text, FLUX.2-
+  klein-4B for art, both on Modal GPUs, JSON-grammar-locked with a one-shot retry
+  and a fast fallback so a slow call never kills the joke's timing.
 
-Play against it: `.\run_modal.ps1`
+📖 **The full build story** — the sub-4B model bake-off, fighting the model's
+"helpful AI" reflex, and the comic pipeline — is in the write-up: _[blog link]_.
 
-To redeploy after changing `modal_app/inference.py`:
-
-```
-set PYTHONUTF8=1                        # Windows: avoids a CLI encoding crash
-modal deploy modal_app/inference.py     # prints the web endpoint URL
-python tests/smoke_modal.py             # one real call per call type
-```
+---
 
-`MODAL_URL` is the full generate-endpoint URL (Modal gives each function its
-own URL). For the HF Space, set `MODAL_URL` + `MODAL_TOKEN` as Space secrets.
+## Run it yourself
 
-## Comic panels (FLUX image generation)
+```bash
+pip install -r requirements.txt
+python app.py     # → http://localhost:7860   (mock mode: fully playable, no keys)
+```
 
-When a crisis fires, the text model also writes a wordless `image_prompt` (a
-single-panel scene) plus a short `comic_caption`. A second Modal GPU app renders
-the panel with **FLUX.2 [klein] 4B**; the UI shows it centered over the office
-with the caption drawn as crisp text *above* the picture (the image stays
-wordless because FLUX garbles in-image text). The art style is prepended
-server-side in `/api/comic`, so the model spends its whole budget describing the
-scene. Setup renders during the walk to the NPC, payoff after the outcome. It's
-purely decorative: if FLUX is unset, slow, or fails, the game shows **no
-overlay** and the dialogue opens as usual — the outcome is never blocked.
+With no `MODAL_URL` set it uses a template-based offline generator. For the real
+AI, deploy the two Modal GPU apps and point the game at them:
 
-```
-set PYTHONUTF8=1
-modal secret create huggingface HF_TOKEN=<hf token>   # FLUX weights are gated
-modal deploy modal_app/image.py                        # prints the endpoint URL
-python tests/probe_comic.py                             # latency + saves a sample
+```bash
+modal deploy modal_app/inference.py   # Qwen3.5-9B text  → MODAL_URL / MODAL_TOKEN
+modal deploy modal_app/image.py       # FLUX.2-klein art → FLUX_URL / FLUX_TOKEN
 ```
 
-Then set `FLUX_URL` (the printed `generate_image` URL) and `FLUX_TOKEN` (the
-same `bds-auth` `BDS_TOKEN`) — locally or as Space secrets. The model is
-env-swappable at deploy: `FLUX_MODEL_ID=black-forest-labs/FLUX.1-schnell`
-(Apache-2.0) is a drop-in if FLUX.2's deps/VRAM are troublesome.
-**License:** the FLUX.2 line is typically non-commercial — fine for a hackathon
-demo; review before any commercial use.
+On the HF Space these four go in **Settings → Secrets**; locally, `.\run_modal.ps1`
+wires them up for you.
 
-## Deploy on Hugging Face (Docker)
+## Deploy (HF Docker Space)
 
-The app is built on **`gr.Server`** (Gradio's FastAPI-based server): it serves a
-fully custom canvas/DOM frontend from `static/` with zero default Gradio
-widgets, while staying a first-class Gradio app. The Space uses `sdk: docker`
-(see frontmatter) because HF's `sdk: gradio` runner only launches a module-level
-`demo`; the `Dockerfile` runs `uvicorn app:app` on port 7860 (the `gr.Server`
-instance is the ASGI app). Set `MODAL_URL`/`MODAL_TOKEN` and (optional)
-`FLUX_URL`/`FLUX_TOKEN` as Space secrets. Dry-run locally:
+Built on **`gr.Server`** so the custom FastAPI frontend *is* the app — HF's
+`sdk: gradio` runner only launches a bare `demo`, so the Space runs `sdk: docker`
+with a `Dockerfile` that does `uvicorn app:app` on port 7860. Dry-run locally:
+`docker build -t bds . && docker run -p 7860:7860 bds`.
 
-```
-docker build -t bds .
-docker run -p 7860:7860 bds          # → http://localhost:7860
-```
+## Controls
+
+**WASD/arrows** move · **SPACE** talk / answer / advance comic · **G** gift ·
+**1/2** choose · **ENTER** send a typed reply · **ESC** close · **M** mute.
+**📱 Mobile:** an on-screen joystick + ACT/GIFT buttons appear automatically, and
+tapping the floor walks you there.
 
 ## Tests
 
-```
-pytest tests/                          # unit tests (validator, economy, events, comic, idle)
-python tests/smoke_http.py             # full-quarter API playthrough
-python tests/smoke_browser.py          # headless-browser UI smoke (playwright)
-python tests/probe_mobile.py           # touch-controls smoke on an emulated phone
-python tests/probe_comic.py            # live FLUX render + saves sample panels
+```bash
+pytest tests/                  # unit: validator, economy, events, comic, idle
+python tests/smoke_http.py     # full-quarter API playthrough (mock)
+python tests/smoke_browser.py  # headless-browser UI smoke
 ```
 
-## Controls
-
-WASD / arrows move · SPACE talk / pick up / answer / advance comic · G gift ·
-1/2 choose options · ENTER send typed response · ESC close · M mute
-
-**Touch / mobile:** on phones and tablets an on-screen joystick (move) plus
-ACT (= SPACE) and GIFT buttons appear automatically; tapping the floor also
-walks the player. Portrait layout stacks the HUD and hides the paper-trail
-panel. Comics and dialogue are tap-dismissable.
-
-## Docs
+---
 
-Design docs (GAME_DESIGN, MECHANICS, EVENTS, …) and engineering docs
-(ARCHITECTURE, SCHEMAS, AI_PROMPTS, IMPLEMENTATION_PLAN) live in the repo
-root. Start with AGENTS.md.
+*Code MIT. Text model: Qwen3.5-9B (Apache-2.0). Image model: FLUX.2 [klein] 4B
+(non-commercial — fine for this demo). Built for the Hugging Face **Build Small
+Hackathon**, "An Adventure in Thousand Token Wood."*