Update README files for HF router workflow

README.md

@@ -19,7 +19,7 @@ The current design has fully moved on from the old volcano/lava loop. The game i
 
 ## Core Idea
 
-1. Pick 2-6 models from Groq or supported Hugging Face sources.
+1. Pick 2-6 supported Hugging Face router models.
 2. Start a simulation and click the map to place the fire.
 3. Agents decide each tick whether to search water, collect water, extinguish fire, escape, or vote for a leader.
 4. Fire grows over time, but water collection and extinguishing reduce intensity.
@@ -41,12 +41,13 @@ The current design has fully moved on from the old volcano/lava loop. The game i
 | --- | --- |
 | Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS v4 |
 | Backend | FastAPI, Python, Uvicorn |
-| AI | Groq models, optional Hugging Face-backed model discovery |
+| AI | Hugging Face Router chat completions |
 | Realtime | WebSockets |
 
 ## Repository Layout
 
-- [backend](backend): FastAPI API, simulation engine, model state, WebSocket streaming
+- [app](app): FastAPI app used by the Hugging Face Space Docker runtime
+- [backend](backend): Local/backend mirror of the FastAPI app for development
 - [frontend](frontend): Next.js UI, map rendering, chat feed, model selection
 
 ## Local Setup
@@ -74,7 +75,7 @@ Then open http://localhost:3000.
 ### Backend
 
 ```env
-GROQ_API_KEY=your_groq_key
+HUGGINGFACE_API_TOKEN=your_hf_token
 ALLOWED_ORIGINS=http://localhost:3000
 ```
 
@@ -109,6 +110,9 @@ Each tick the backend:
 ## Notes
 
 - State is kept in memory, so simulations reset when the backend restarts.
+- The backend asks models for structured JSON decisions and short radio-style chat lines.
+- If the Hugging Face router starts returning `402 Payment Required`, the app switches to local fallback behavior until models become available again.
+- The Hugging Face Space deploys from the root `app/` package via the root `Dockerfile`.
 - The UI is designed around visible cooperation, not just survival.
 - Old lava/volcano docs are intentionally replaced by the fire/water scenario.
 

backend/README.md

@@ -30,7 +30,7 @@ FastAPI server driving the fire-suppression simulation.
 
 ## Environment Variables
 
-- `GROQ_API_KEY`: Required for agent decisions.
+- `HUGGINGFACE_API_TOKEN` or `HF_API_TOKEN`: Required for Hugging Face router model calls.
 - `ALLOWED_ORIGINS`: CORS whitelist.
 
 ## Local Run
@@ -45,4 +45,6 @@ python -m uvicorn app.main:app --reload --port 8000
 
 - Simulation state is in memory.
 - Fire growth, extinguish rate, and movement are tuned in `app/simulation.py`.
-- Model decisions are generated in `app/groq_client.py`.
+- Model decisions are generated in `app/groq_client.py` through `https://router.huggingface.co/v1/chat/completions`.
+- `/available-models` is backed by `app/hf_spaces.py` and filters a preferred model list against the live Hugging Face router catalog.
+- This `backend/` app is the local development copy; the Hugging Face Space runtime uses the root `app/` package.

frontend/README.md

@@ -4,10 +4,10 @@ Next.js UI for the fire-suppression simulation.
 
 ## What It Shows
 
-- Model selection and simulation start flow
+- Model selection from the backend's live Hugging Face model list
 - Map-based agent positions and fire placement
 - Water sources, coalition links, and leader markers
-- Live event chat with varied team messages
+- Live event chat with model-generated radio-style messages
 - End-of-game result banner with top performer info
 
 ## Run Locally
@@ -39,4 +39,5 @@ NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
 
 - The frontend expects the backend to be running before placing a fire.
 - If the browser shows `Failed to fetch`, verify `http://localhost:8000/wake` first.
+- The model picker reads `GET /available-models` from the backend and sends those model ids back into the simulation.
 - The old volcano terminology has been removed from the current gameplay flow.