Update README: message flow charts, full deployment guide

- System architecture diagram (ASCII) showing browser → API → sim loop → LLM
- Message flow for one simulation tick (per-agent LLM call path)
- Agent cognition loop diagram (OBSERVE/REFLECT/PLAN/ACT/REMEMBER)
- Deployment guides: HF Spaces, Render, Railway, ngrok (local)
- Updated env vars table (GEMINI_API_KEY, SOCI_LLM_PROB, GEMINI_DAILY_LIMIT, etc.)
- LLM provider comparison table with free-tier limits
- Updated features list (Gemini, LLM probability slider, quota circuit-breaker)
- Updated live demo URL to HF Space

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

README.md

@@ -13,7 +13,7 @@ Simulates a diverse population of AI people living in a city using an LLM as the
 
 Inspired by [Stanford Generative Agents (Joon Park et al.)](https://arxiv.org/abs/2304.03442), CitySim, AgentSociety, and a16z ai-town.
 
-**Live demo:** https://soci-tl3c.onrender.com
+**Live demo:** https://huggingface.co/spaces/RayMelius/soci
 
 ---
 
@@ -27,156 +27,365 @@ Inspired by [Stanford Generative Agents (Joon Park et al.)](https://arxiv.org/ab
 - Road-based movement with L-shaped routing (agents walk along streets)
 - Agent animations: walking (profile/back view), sleeping on bed
 - Speed controls (1x → 50x) and real-time WebSocket sync across browsers
+- **LLM probability slider** — tune AI usage from 0–100% to stay within free-tier quotas
 - **Player login** — register an account, get your own agent on the map, chat with NPCs
-- Multi-LLM support: Groq (free tier), Anthropic Claude, Ollama (local)
+- Multi-LLM support: Gemini (free tier), Groq (free tier), Anthropic Claude, Ollama (local)
 - GitHub-based state persistence (survives server reboots and redeploys)
 - Cost-efficient model routing (Haiku for routine, Sonnet for novel situations)
+- Daily quota circuit-breaker with warnings at 50 / 70 / 90 / 99% usage
 
 ---
 
-## Tech Stack
+## System Architecture
 
-- Python 3.10+
-- Anthropic Claude API / Groq / Ollama
-- FastAPI + WebSocket
-- SQLite via aiosqlite
-- YAML config
+```
+┌─────────────────────────────────────────────────────────┐
+│  Browser  (web/index.html — single-file Vue-less UI)    │
+│  • Canvas city map  • Agent inspector  • Chat panel     │
+│  • Speed / LLM-probability sliders  • Login modal       │
+└────────┬──────────────────────────────┬─────────────────┘
+         │ REST  GET /api/*             │ WebSocket /ws
+         │ POST /api/controls/*         │ push events
+         ▼                              ▼
+┌──────────────────────────────────────────────────────────┐
+│  FastAPI Server  (soci/api/server.py)                    │
+│  • lifespan: load state → start sim loop                │
+│  • routes.py  — REST endpoints                          │
+│  • websocket.py — broadcast tick events                 │
+└────────────────────────┬─────────────────────────────────┘
+                         │ asyncio.create_task
+                         ▼
+┌──────────────────────────────────────────────────────────┐
+│  Simulation Loop  (background task)                      │
+│  tick every N sec  →  sim.tick()  →  sleep              │
+│  respects: _sim_paused / _sim_speed / llm_call_prob      │
+└────────────────────────┬─────────────────────────────────┘
+                         │
+                         ▼
+┌──────────────────────────────────────────────────────────┐
+│  Simulation.tick()  (engine/simulation.py)               │
+│                                                          │
+│  1. Entropy / world events                               │
+│  2. Daily plan generation  ──► LLM (if prob gate ✓)     │
+│  3. Agent needs + routine actions  (no LLM)             │
+│  4. LLM action decisions  ─────► LLM (if prob gate ✓)  │
+│  5. Conversation turns  ───────► LLM (if prob gate ✓)  │
+│  6. New conversation starts  ──► LLM (if prob gate ✓)  │
+│  7. Reflections  ──────────────► LLM (if prob gate ✓)  │
+│  8. Romance / relationship updates  (no LLM)            │
+│  9. Clock advance                                        │
+└────────────────────────┬─────────────────────────────────┘
+                         │ await llm.complete_json()
+                         ▼
+┌──────────────────────────────────────────────────────────┐
+│  LLM Client  (engine/llm.py)                             │
+│  • Rate limiter (asyncio.Lock, min interval per RPM)     │
+│  • Daily usage counter → warns at 50/70/90/99%          │
+│  • Quota circuit-breaker (expires midnight Pacific)      │
+│  • Providers: GeminiClient / GroqClient /                │
+│               ClaudeClient / HFInferenceClient /         │
+│               OllamaClient                               │
+└────────────────────────┬─────────────────────────────────┘
+                         │ HTTP (httpx async)
+                         ▼
+              External LLM API  (Gemini / Groq / …)
+```
 
 ---
 
-## Setup
+## Message Flow — One Simulation Tick
 
-1. **Clone the repo**
-   ```bash
-   git clone https://github.com/Bonum/Soci.git
-   cd Soci
-   ```
+```
+Browser poll (3s)          Simulation background loop
+      │                              │
+      │  GET /api/city              tick_delay (4s Gemini, 0.5s Ollama)
+      │◄────────────────────────────┤
+      │                             │ sim.tick()
+      │                             │
+      │                   ┌─────────┴──────────┐
+      │                   │  For each agent:   │
+      │                   │  tick_needs()      │
+      │                   │  check routine     │──► execute routine action (no LLM)
+      │                   │  roll prob gate    │
+      │                   │  _decide_action()  │──► LLM call ──► AgentAction JSON
+      │                   │  _execute_action() │
+      │                   └─────────┬──────────┘
+      │                             │
+      │                   ┌─────────┴──────────┐
+      │                   │  Conversations:    │
+      │                   │  continue_conv()   │──► LLM call ──► dialogue turn
+      │                   │  new conv start    │──► LLM call ──► opening line
+      │                   └─────────┬──────────┘
+      │                             │
+      │                   ┌─────────┴──────────┐
+      │                   │  Reflections:      │
+      │                   │  should_reflect()?  │──► LLM call ──► memory insight
+      │                   └─────────┬──────────┘
+      │                             │
+      │                        clock.tick()
+      │                             │
+      │  WebSocket push             │
+      │◄── events/state ────────────┘
+      │
+[browser updates map, event log, agent inspector]
+```
 
-2. **Install dependencies**
-   ```bash
-   pip install -r requirements.txt
-   ```
+---
 
-3. **Set your API key** (choose one provider)
-   ```bash
-   # Groq (free tier — recommended for cloud)
-   export GROQ_API_KEY=gsk_...
+## Agent Cognition Loop
 
-   # Anthropic Claude
-   export ANTHROPIC_API_KEY=sk-ant-...
-   ```
+```
+Every tick, each NPC agent runs:
+
+  ┌──────────────────────────────────────────────────────┐
+  │                                                      │
+  │   OBSERVE ──► perceive nearby agents, events,        │
+  │               location, time of day                  │
+  │      │                                               │
+  │      ▼                                               │
+  │   REFLECT ──► check memory.should_reflect()          │
+  │               LLM synthesises insight from recent    │
+  │               memories  →  stored as reflection      │
+  │      │                                               │
+  │      ▼                                               │
+  │   PLAN  ───► if no daily plan: LLM generates         │
+  │               ordered list of goals for the day      │
+  │               (or routine fills the plan — no LLM)   │
+  │      │                                               │
+  │      ▼                                               │
+  │   ACT  ────► routine slot?  → execute directly       │
+  │               no slot?      → LLM picks action       │
+  │               action types: move / work / eat /      │
+  │               sleep / socialise / leisure / rest     │
+  │      │                                               │
+  │      ▼                                               │
+  │   REMEMBER ► add_observation() to memory stream      │
+  │               importance 1–10, recency decay,        │
+  │               retrieved by relevance score           │
+  │                                                      │
+  └──────────────────────────────────────────────────────┘
+
+  LLM budget per tick (rate-limited providers):
+    max_llm_calls_this_tick = 1   (Gemini/Groq/HF)
+    llm_call_probability    = 0.45 (Gemini default → ~10h/day)
+```
 
 ---
 
-## Running
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Language | Python 3.10+ |
+| API server | FastAPI + Uvicorn |
+| Real-time | WebSocket (FastAPI) |
+| Database | SQLite via aiosqlite |
+| LLM providers | Gemini · Groq · Anthropic Claude · HF Inference · Ollama |
+| Config | YAML (city layout, agent personas) |
+| State persistence | GitHub API (simulation-state branch) |
+| Container | Docker (HF Spaces / Render) |
+
+---
+
+## Quick Start (Local)
+
+### Prerequisites
+- Python 3.10+
+- At least one LLM API key — or [Ollama](https://ollama.ai) installed locally (free, no key needed)
+
+### Install
 
-### Web UI (local)
 ```bash
-python -m uvicorn soci.api.server:app --host 0.0.0.0 --port 8000
+git clone https://github.com/Bonum/Soci.git
+cd Soci
+pip install -r requirements.txt
 ```
-Open `http://localhost:8000` in your browser.
 
-### Terminal simulation (no UI)
+### Configure
+
 ```bash
+# Pick ONE provider (Gemini recommended — free tier is generous):
+export GEMINI_API_KEY=AIza...        # https://aistudio.google.com/apikey
+# or
+export GROQ_API_KEY=gsk_...          # https://console.groq.com
+# or
+export ANTHROPIC_API_KEY=sk-ant-...
+# or install Ollama and pull a model — no key needed
+```
+
+### Run
+
+```bash
+# Web UI (recommended)
+python -m uvicorn soci.api.server:app --host 0.0.0.0 --port 8000
+# Open http://localhost:8000
+
+# Terminal only
 python main.py --ticks 20 --agents 5
 ```
 
 ---
 
-## Environment Variables
+## Deploying to the Internet
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SOCI_PROVIDER` | auto-detect | LLM provider: `groq`, `claude`, `ollama` |
-| `GROQ_API_KEY` | — | Groq API key |
-| `ANTHROPIC_API_KEY` | — | Anthropic API key |
-| `SOCI_AGENTS` | `50` | Starting agent count |
-| `SOCI_TICK_DELAY` | `0.5` | Seconds between simulation ticks |
-| `SOCI_DATA_DIR` | `data` | Directory for SQLite DB and snapshots |
-| `GITHUB_TOKEN` | — | GitHub PAT for state persistence across deploys |
-| `GITHUB_REPO` | — | `owner/repo` for state persistence |
-| `GITHUB_STATE_BRANCH` | `simulation-state` | Branch used for state (never touches main) |
+### Option 1 — Hugging Face Spaces (free, recommended)
+
+HF Spaces runs the Docker container for free with automatic HTTPS.
+
+1. **Create a Space** at https://huggingface.co/new-space
+   - SDK: **Docker**
+   - Visibility: Public
+
+2. **Add the HF remote** and push:
+   ```bash
+   git remote add hf https://YOUR_HF_USERNAME:YOUR_HF_TOKEN@huggingface.co/spaces/YOUR_HF_USERNAME/soci
+   git push hf master:main
+   ```
+   Get a write token at https://huggingface.co/settings/tokens (select *Write* + *Inference Providers* permissions).
+
+3. **Add Space secrets** (Settings → Variables and Secrets):
+
+   | Secret | Value |
+   |--------|-------|
+   | `SOCI_PROVIDER` | `gemini` |
+   | `GEMINI_API_KEY` | your AI Studio key |
+   | `GITHUB_TOKEN` | GitHub PAT (repo read/write) |
+   | `GITHUB_OWNER` | your GitHub username |
+   | `GITHUB_REPO_NAME` | `Soci` |
+
+4. Your Space rebuilds automatically on every push. Visit
+   `https://YOUR_HF_USERNAME-soci.hf.space`
+
+> **Free-tier tip:** Gemini free tier = 5 RPM, ~1500 requests/day (resets midnight Pacific).
+> The default LLM probability is set to **45%** which gives ~10 hours of AI-driven simulation per day.
+> Use the 🧠 slider in the toolbar to adjust at runtime.
 
 ---
 
-## Deploying to Render (free tier)
+### Option 2 — Render (free tier)
+
+1. Connect your GitHub repo at https://render.com/new
+2. Choose **Web Service** → Docker
+3. Set **Start Command**:
+   ```
+   python -m uvicorn soci.api.server:app --host 0.0.0.0 --port $PORT
+   ```
+4. Set environment variables in the Render dashboard:
+
+   | Variable | Value |
+   |----------|-------|
+   | `SOCI_PROVIDER` | `gemini` or `groq` |
+   | `GEMINI_API_KEY` | your key |
+   | `GITHUB_TOKEN` | GitHub PAT |
+   | `GITHUB_OWNER` | your GitHub username |
+   | `GITHUB_REPO_NAME` | `Soci` |
 
-1. Connect your GitHub repo in Render.
-2. Set **Start Command**: `python -m uvicorn soci.api.server:app --host 0.0.0.0 --port $PORT`
-3. Set env vars: `SOCI_PROVIDER`, `GROQ_API_KEY` (or `ANTHROPIC_API_KEY`), `GITHUB_TOKEN`, `GITHUB_REPO`
-4. Add an **Ignore Command** to prevent state-file commits from triggering redeploys:
+5. To prevent state-file commits from triggering redeploys, set **Ignore Command**:
    ```
    [ "$(git diff --name-only HEAD~1 HEAD | grep -v '^state/' | wc -l)" = "0" ]
    ```
 
-Simulation state is automatically saved to a `simulation-state` branch on shutdown and restored on the next startup — no persistent disk required.
+> **Note:** Render free tier spins down after 15 min of inactivity. Simulation state is saved to GitHub on shutdown and restored on the next boot — no data is lost.
 
 ---
 
-## Architecture
+### Option 3 — Railway
 
-```
-src/soci/
-  world/        — City map, simulation clock, world events
-  agents/       — Agent cognition: persona, memory, needs, relationships
-  actions/      — Movement, activities, conversation, social actions
-  engine/       — Simulation loop, scheduler, entropy, LLM client
-  persistence/  — SQLite database, save/load snapshots
-  api/          — FastAPI REST + WebSocket server
-config/
-  city.yaml     — City layout and building positions
-  personas.yaml — Named character definitions
-web/
-  index.html    — Single-file web UI
-```
+1. Go to https://railway.app → **New Project** → **Deploy from GitHub repo**
+2. Railway auto-detects the Dockerfile
+3. Add environment variables in the Railway dashboard (same as Render above)
+4. Railway assigns a public URL automatically
 
 ---
 
-## Web UI
+### Option 4 — Local + Ngrok (quick public URL for testing)
 
-| Action | How |
-|--------|-----|
-| Zoom | Scroll wheel or +/− buttons |
-| Fit view | Fit button |
-| Pan | Drag canvas or use sliders |
-| Rectangle zoom | Click ⬚, then drag |
-| Inspect agent | Click agent on map or in list |
-| **Login / play** | Register → your agent appears on the map |
-| **Talk to NPC** | Select any agent → "Talk to [Name]" button |
-| **Move** | Player panel → location dropdown → Go |
-| **Edit profile** | Player panel → Edit Profile |
-| **Add plans** | Player panel → My Plans |
+```bash
+# Start the server
+python -m uvicorn soci.api.server:app --host 0.0.0.0 --port 8000 &
+
+# Expose it publicly (install ngrok first: https://ngrok.com)
+ngrok http 8000
+# Copy the https://xxxx.ngrok.io URL and share it
+```
 
 ---
 
-## Player Mode
+## Environment Variables
 
-Register an account to join the simulation as a participant:
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SOCI_PROVIDER` | auto-detect | LLM provider: `gemini` · `groq` · `claude` · `hf` · `ollama` |
+| `GEMINI_API_KEY` | — | Google AI Studio key (free tier: 5 RPM, ~1500 RPD) |
+| `GROQ_API_KEY` | — | Groq API key (free tier: 30 RPM) |
+| `ANTHROPIC_API_KEY` | — | Anthropic Claude API key |
+| `SOCI_LLM_PROB` | per-provider | LLM call probability 0–1 (`0.45` Gemini · `0.7` Groq · `1.0` Ollama) |
+| `GEMINI_DAILY_LIMIT` | `1500` | Override Gemini daily request quota for warning thresholds |
+| `SOCI_AGENTS` | `50` | Starting agent count |
+| `SOCI_TICK_DELAY` | `0.5` | Seconds between simulation ticks (overridden to 4.0 for rate-limited providers) |
+| `SOCI_DATA_DIR` | `data` | Directory for SQLite DB and snapshots |
+| `GITHUB_TOKEN` | — | GitHub PAT for state persistence across deploys |
+| `GITHUB_OWNER` | — | GitHub repo owner (e.g. `alice`) |
+| `GITHUB_REPO_NAME` | — | GitHub repo name (e.g. `Soci`) |
+| `GITHUB_STATE_BRANCH` | `simulation-state` | Branch used for state snapshots (never touches main) |
+| `GITHUB_STATE_FILE` | `state/autosave.json` | Path inside repo for state file |
+| `PORT` | `8000` | HTTP port (set to `7860` on HF Spaces automatically) |
+
+---
 
-1. Click **Register** in the login modal (or skip to observe only).
-2. Your agent appears immediately on the map with a **gold ring** to identify you.
-3. Click **Edit Profile** to set your name, age, occupation, background, and personality traits.
-4. Click any NPC → **Talk to [Name]** to start a conversation — they reply in character via LLM.
-5. Use **My Plans** to add goals (e.g. *"Go to the park and meet new people"*).
+## Web UI Controls
 
-Multiple users can be logged in simultaneously — each controls their own agent.
+| Control | How |
+|---------|-----|
+| Zoom | Scroll wheel or **＋ / －** buttons |
+| Fit view | **Fit** button |
+| Pan | Drag canvas or use sliders |
+| Rectangle zoom | Click **⬚**, then drag |
+| Inspect agent | Click agent on map or in sidebar list |
+| Speed | **🐢 1x 2x 5x 10x 50x** buttons |
+| LLM usage | **🧠** slider (0–100%) — tune AI call frequency |
+| Switch LLM | Click the provider badge (e.g. **✦ Gemini 2.0 Flash**) |
+| **Login / play** | Register → your agent appears with a gold ring |
+| **Talk to NPC** | Select agent → **Talk to [Name]** button |
+| **Move** | Player panel → location dropdown → **Go** |
+| **Edit profile** | Player panel → **Edit Profile** |
+| **Add plans** | Player panel → **My Plans** |
 
 ---
 
-## Agent Cognition
+## LLM Provider Comparison
 
-Each simulation tick, every NPC agent runs:
+| Provider | Free tier | RPM | Daily limit | Best for |
+|----------|-----------|-----|-------------|----------|
+| **Gemini 2.0 Flash** | ✅ Yes | 5 | ~1500 req | Cloud demos (default) |
+| **Groq Llama 3.1 8B** | ✅ Yes | 30 | ~14k tokens/min | Fast responses |
+| **Ollama** | ✅ Local | ∞ | ∞ | Local dev, no quota |
+| **Anthropic Claude** | ❌ Paid | — | — | Highest quality |
+| **HF Inference** | ⚠️ PRO only | 5 | varies | Experimenting |
+
+---
+
+## Project Structure
 
 ```
-OBSERVE  — perceive nearby agents, events, environment
-REFLECT  — update beliefs and emotional state
-PLAN     — decide what to do next
-ACT      — execute action (move, talk, work, rest, sleep…)
-REMEMBER — store important events to memory stream
+Soci/
+├── src/soci/
+│   ├── world/          City map, simulation clock, world events
+│   ├── agents/         Agent cognition: persona, memory, needs, relationships
+│   ├── actions/        Movement, activities, conversation, social actions
+│   ├── engine/         Simulation loop, scheduler, entropy, LLM clients
+│   ├── persistence/    SQLite database, save/load snapshots
+│   └── api/            FastAPI REST + WebSocket server
+├── config/
+│   ├── city.yaml       City layout, building positions, zones
+│   └── personas.yaml   Named character definitions (20 hand-crafted agents)
+├── web/
+│   └── index.html      Single-file web UI (no framework)
+├── Dockerfile          For HF Spaces / Render / Railway deployment
+├── render.yaml         Render deployment config
+└── main.py             Terminal runner (no UI)
 ```
 
-Memory entries are scored by importance (1–10) with recency decay, retrieved by relevance score.
-
 ---
 
 ## License