feat: LLM-driven infinite adventure loop

- Single generate_llm_turn() call produces story + choices + health delta
- Infinite gameplay until health <= 0, no fixed step cap
- Procedural fallback preserved during cooldown/failure

.gitignore

@@ -0,0 +1,10 @@
+# AINISH Coder Tooling Distribution - Git Ignore Patterns
+__pycache__/
+*.pyc
+venv/
+.venv/
+.DS_Store
+*.log
+tmp/
+models/
+*.gguf

PRD.md

@@ -0,0 +1,276 @@
+# DOX framework
+
+- DOX is a highly performant `llms.txt` hierarchy installed here
+- Agent must follow DOX instructions across any edits
+
+## Purpose
+
+- **Name:** Build Small Hackathon 2026 — Team nbiish
+- **Version:** 0.5.0 — Cedar-Copper Edition (HF Inference API)
+- **Aesthetic:** Cedar-copper visual language — sky-to-sunrise palette (water-blue → cedar → copper → sun-amber → birch-cream), biophilic motifs, sky-to-water gradient banners. Shared CSS variables live in `shared/cedar_copper_tokens.py`.
+- **Purpose:** Win prizes across tracks, badges, and sponsor categories by building delightful, useful AI apps that run locally.
+- **UX:** Gradio web apps (gr.Blocks + mount_gradio_app custom frontends), hosted on HF Spaces.
+- **Hack window:** June 5-15, 2026. Deadline: June 15.
+
+> This file is the master PRD and stays English-only. Per-project UIs and READMEs may use additional stylistic content for their own artifacts.
+
+## Core Contract
+
+- `llms.txt` files are binding work contracts for their subtrees
+- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable `llms.txt` plus every parent `llms.txt` above it
+
+## Read Before Editing
+
+1. Read the root `llms.txt`
+2. Identify every file or folder you expect to touch
+3. Walk from the repository root to each target path
+4. Read every `llms.txt` found along each route
+5. If a parent `llms.txt` lists a child `llms.txt` whose scope contains the path, read that child and continue from there
+6. Use the nearest `llms.txt` as the local contract and parent docs for repo-wide rules
+7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX
+
+Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.
+
+## Local Contracts
+
+### Naming & Comments
+
+- Descriptive project names: CritterCalm, FocusFriend, TinyBard
+- Docstrings on all public functions. Comments on non-obvious logic.
+
+### Always
+
+- Models ≤ 32B total params per project
+- Gradio app hosted as HF Space
+- Local-first (no cloud APIs = Off the Grid badge)
+- GGUF quantized models for local inference
+- Python 3.10+ with pinned requirements
+- Cedar-copper aesthetic consistency across all UIs (palette tokens in `shared/cedar_copper_tokens.py`)
+
+### Never
+
+- Cloud API calls in production path
+- Hardcoded secrets or API keys
+- Models > 32B params
+- Default Gradio look without customization attempt
+
+### If
+
+- If custom frontend is feasible → use `mount_gradio_app` for Off-Brand badge
+- If model ≤ 4B → tag Tiny Titan eligible
+- If using llama.cpp runtime → tag Llama Champion
+- If fine-tuning is done → publish model to HF Hub
+
+## Infrastructure
+
+### Gradio 6.0 + MCP Server
+
+- `gradio.Server` is **NOT** in Gradio 6.0 stable. Use `mount_gradio_app(fastapi_app, blocks, path="/gradio")` instead.
+- MCP server mode: `demo.launch(mcp_server=True)` or `GRADIO_MCP_SERVER=true` env var.
+- Custom frontends: Serve static HTML/CSS/JS via FastAPI, mount Gradio at `/gradio` for API + MCP.
+- `@gradio/client` CDN: `https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js` (ES module, use `type="module"`).
+- Theme parameters: `css`, `head`, `theme` moved from `gr.Blocks(...)` to `app.launch(...)` in Gradio 6.0.
+- Chatbot API: Gradio 6.0 requires `{"role": "user|assistant", "content": "..."}` dicts (not tuples).
+
+### HF Agents CLI
+
+- `hf` CLI is installed (v1.18.0). See `skill://hf-cli` for full command reference.
+- Install expert skills: `hf skills add --global` or `hf skills add --claude --global`.
+- Spaces managed via: `hf repos create <name> --type space --space-sdk gradio --public`.
+- Deploy: `git remote add hf https://huggingface.co/spaces/<user>/<space>` then `git push hf main`.
+- HF README metadata: `colorTo` must be one of `[red, yellow, green, blue, indigo, purple, pink, gray]` (no `emerald`/`amber`).
+- HF README metadata: `emoji` must match `/\p{Extended_Pictographic}/u` — only the standard emoji block is allowed; decorative Unicode glyphs (solar/astrological/typographic symbols) fail validation. Use a real emoji.
+
+### Inference Architecture (v0.5+)
+
+- **All LLM inference** is now via the **Hugging Face Inference API** (serverless). No more local GGUF, no `llama-cpp-python` compile step.
+- Shared module: `shared/inference_client.py` provides `cooldown_status()`, `cooldown_active()`, `generate()`, and `chat_messages()`.
+- Default model: `Qwen/Qwen2.5-1.5B-Instruct` (free tier, fast, well-suited to chat). Override via `INFERENCE_MODEL`.
+- Per-project model override: `TINYBARD_MODEL`, `FOCUSFRIEND_MODEL`, `CRITTERCALM_MODEL`.
+- **Cooldowns** enforce a per-project minimum gap between inference calls (protects HF/Modal credit budget):
+  - `tinybard`: 6s
+  - `focusfriend`: 10s
+  - `crittercalm`: 12s
+  - Override via `TINYBARD_COOLDOWN_SECONDS`, etc., or global `INFERENCE_COOLDOWN_SECONDS`.
+- **Always-fallback:** every LLM call falls back to procedural / template output if inference fails or is in cooldown. No LLM call ever blocks the UX.
+- HF Spaces are the dev/test environment — iterate live at `huggingface.co/spaces/nbiish/{tinybard,focusfriend,crittercalm}` rather than localhost.
+
+### Local Test Environment
+
+- Python: miniconda3 (Python 3.12)
+- Gradio: 6.0.0
+- `huggingface_hub` (for Inference API client)
+- Inference is serverless — no local model files needed unless you opt in to local mode
+
+### Local Servers (optional)
+
+Local servers were used during v0.4 development for visual inspection. v0.5+ prefers iterating on the live HF Spaces (which use your HF/Modal compute credits). Local servers can still be run for dev:
+
+| Project | URL | Stack | HF Space |
+|---|---|---|---|
+| TinyBard | http://localhost:7861/ | FastAPI + Gradio Blocks | nbiish/tinybard |
+| FocusFriend | http://localhost:7862/ | Gradio 6.0 | nbiish/focusfriend |
+| CritterCalm | http://localhost:7863/ | Gradio 6.0 | nbiish/crittercalm |
+
+## Projects
+
+### 1. CritterCalm (Backyard AI)
+
+- **Status:** Code complete. Deployed. HF Inference API + cooldowns wired for script generation. OmniVoice voice cloning still requires local install.
+- **Stack:** OmniVoice (0.6B, local optional) + Kokoro TTS (82M, local optional) + Qwen2.5-7B (default) via HF Inference API
+- **Badges:** Off the Grid, Well-Tuned (TBD), Field Notes, Off-Brand
+- **GitHub:** github.com/nbiish/crittercalm
+- **HF Space:** huggingface.co/spaces/nbiish/crittercalm
+- **Standalone repo:** /Volumes/1tb-sandisk/code-external/crittercalm-repo
+
+### 2. FocusFriend (Thousand Token Wood)
+
+- **Status:** Code complete. Deployed. HF Inference API + cooldowns wired. Gradio 6 Chatbot dict-format fixed.
+- **Stack:** Qwen2.5-7B (default) via HF Inference API
+- **Badges:** Off-Brand (sun-amber custom theme), Field Notes, Cooldowns badge
+- **GitHub:** github.com/nbiish/focusfriend
+- **HF Space:** huggingface.co/spaces/nbiish/focusfriend
+- **Standalone repo:** /Volumes/1tb-sandisk/code-external/focusfriend-repo
+
+### 3. TinyBard (Thousand Token Wood + Tiny Titan + Llama Champion)
+
+- **Status:** Code complete. Deployed. HF Inference API + cooldowns wired. Local test verified (procedural fallback + cooldown UI).
+- **Concept:** ≤4B LLM generates 5-min interactive text adventures in a CRT terminal aesthetic.
+- **Stack:** Qwen2.5-1.5B (default) via HF Inference API + procedural fallback engine
+
+## Work Guidance
+
+### TODO
+
+> Keep tasks atomic and testable.
+
+#### In Progress
+
+- [ ] Test CritterCalm voice cloning pipeline end-to-end
+- [ ] Test FocusFriend all 4 modes (Chat, Focus, Breathe, Meditate) with real model
+- [ ] Record demo videos (2-3 min each)
+- [ ] Post to social media
+- [ ] Write Field Notes blog posts (3 — one per project)
+- [ ] Share agent traces to HF Hub (Sharing is Caring badge)
+
+#### Completed
+
+- [x] CritterCalm v1 code complete (11 files) — Cedar-copper UI
+- [x] FocusFriend v1 code complete (16 files) — Cedar-copper UI + Gradio 6 dict Chatbot
+- [x] TinyBard v1 code complete (8 files) — LLM + procedural fallback, CRT UI, clean FastAPI JSON
+- [x] GitHub repos created (nbiish/crittercalm, nbiish/focusfriend, nbiish/tinybard)
+- [x] HF Spaces created and deployed (all 3)
+- [x] Monorepo structure with projects/ directory + shared/ aesthetic module
+- [x] INTELLIGENCE.md — full hackathon landscape analysis
+- [x] SUBMISSION_DRAFTS.md — social posts + Field Notes drafts
+- [x] HF CLI installed + skills configured (`hf skills add --global`)
+- [x] llama-cpp-python installed (conda-forge v0.3.16) — for reference; v0.5+ uses HF Inference API
+- [x] Local verification: all 3 apps run on ports 7861/7862/7863
+- [x] TinyBard end-to-end game loop verified (start → choose → next scene)
+- [x] FocusFriend chat verified (user message → Pip reply)
+- [x] CritterCalm UI navigation verified (all 3 tabs render)
+- [x] **v0.5: HF Inference API wired into all 3 apps** (no local GGUF, no build step)
+- [x] **v0.5: Cooldown system** in `shared/inference_client.py` to protect HF/Modal credit budget
+- [x] **v0.5: TinyBard local test** — procedural fallback works when no HF_TOKEN; cooldown UI shows in footer
+
+### Short-term Goals
+
+- Iterate on the live HF Spaces (nbiish/tinybard, nbiish/focusfriend, nbiish/crittercalm)
+- Set HF_TOKEN + INFERENCE_MODEL Space secrets to enable real LLM-backed adventures
+- Record demo videos and post to social media
+- Write and publish Field Notes blog posts
+- Share agent traces for Sharing is Caring badge
+- Polish UIs for demo appeal
+
+## Update After Editing
+
+Every meaningful change requires a DOX pass before the task is done.
+
+Update the closest owning `llms.txt` when a change affects:
+
+- purpose, scope, ownership, or responsibilities
+- durable structure, contracts, workflows, or operating rules
+- required inputs, outputs, permissions, constraints, side effects, or artifacts
+- user preferences about behavior, communication, process, organization, or quality
+- `llms.txt` creation, deletion, move, rename, or index contents
+
+Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.
+
+## Hierarchy
+
+- Root `llms.txt` is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
+- Child `llms.txt` files own domain-specific instructions and their own Child DOX Index
+- Each parent explains what its direct children cover and what stays owned by the parent
+- The closer a doc is to the work, the more specific and practical it must be
+
+## Child Doc Shape
+
+- Create a child `llms.txt` when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
+- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
+- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists
+
+Default section order:
+- Purpose
+- Ownership
+- Local Contracts
+- Work Guidance
+- Verification
+- Child DOX Index
+
+## Style
+
+- Keep docs concise, current, and operational
+- Document stable contracts, not diary entries
+- Put broad rules in parent docs and concrete details in child docs
+- Prefer direct bullets with explicit names
+- Do not duplicate rules across many files unless each scope needs a local version
+- Delete stale notes instead of explaining history
+- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist
+
+## Closeout
+
+1. Re-check changed paths against the DOX chain
+2. Update nearest owning docs and any affected parents or children
+3. Refresh every affected Child DOX Index
+4. Remove stale or contradictory text
+5. Run existing verification when relevant
+6. Report any docs intentionally left unchanged and why
+
+## Verification
+
+Run local servers to verify apps:
+- TinyBard: `cd projects/tinybard && python app.py` → http://localhost:7861/
+- FocusFriend: `cd projects/focusfriend && python app.py` → http://localhost:7862/
+- CritterCalm: `cd projects/crittercalm && python app.py` → http://localhost:7863/
+
+## Reference
+
+- CritterCalm: projects/crittercalm/ + github.com/nbiish/crittercalm
+- FocusFriend: projects/focusfriend/ + github.com/nbiish/focusfriend
+- TinyBard: projects/tinybard/ + github.com/nbiish/tinybard
+- Aesthetic module: shared/cedar_copper_tokens.py
+- Inference client: shared/inference_client.py
+- ML Intern: github.com/huggingface/ml-intern
+- HF Agents CLI: huggingface.co/docs/hub/en/agents-cli
+- Gradio MCP: gradio.app/guides/model-context-protocol
+
+## User Preferences
+
+When the user requests a durable behavior change, record it here or in the relevant child `llms.txt`
+
+## Child DOX Index
+
+### projects/crittercalm/
+- Backyard AI track — CritterCalm wildlife sound identifier
+- Stack: OmniVoice + Dolphin-X1-8B + Kokoro TTS
+
+### projects/focusfriend/
+- Thousand Token Wood track — FocusFriend productivity assistant
+- Stack: Gemma 4 12B via llama-cpp-python
+
+### projects/tinybard/
+- Thousand Token Wood + Tiny Titan + Llama Champion tracks
+- Stack: VibeThinker 1.5B + procedural fallback
+
+### shared/
+- Cedar-copper aesthetic tokens and shared utilities

README.md

@@ -1,13 +1,143 @@
 ---
-title: Tinybard
-emoji: 🏢
-colorFrom: indigo
-colorTo: indigo
+title: ᐴ TinyBard ᔔ
+emoji: ☀️
+colorFrom: blue
+colorTo: yellow
 sdk: gradio
-sdk_version: 6.17.3
-python_version: '3.13'
+sdk_version: 6.0.0
 app_file: app.py
 pinned: false
+license: apache-2.0
+tags:
+  - text-adventure
+  - interactive-fiction
+  - thousand-token-wood
+  - build-small-hackathon
+  - tiny-titan
+  - off-brand
+  - mcp-server
+  - anishinaabe
+  - solarpunk
+  - inference-api
+  - cooldowns
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ◈──◆──◇ ᐴ TINYBARD ᔔ AADIZOOKAAN-AKINOOMAAGEWIN / STORY-TELLING ENGINE ◇──◆──◈
+
+> **A small LLM fires five-minute interactive text adventures in a cedar-and-copper CRT terminal.**
+>
+> ᐴ The land remembers the stories. ᔔ  ☼ ☘ ≈
+
+TinyBard uses FastAPI + `mount_gradio_app` (Gradio 6.0) with a fully custom HTML/CSS/JS frontend, **MCP server mode** enabled, and an **HF Inference API** backend. Every adventure is procedurally generated — rooms, NPCs, items, and branching narratives on the fly.
+
+## ◆ GASHKITOONAN / CAPABILITIES ◈
+
+- **◇ Dynamic Adventures ◇** — LLM generates unique story beats for every playthrough
+- **◇ Three Aadizookaanan / Genres ◇** — Aadizookaan (Fantasy), Ish piming (Sci-Fi), Mashkodewaazibi (Cyberpunk)
+- **◇ Misko-Aki / CRT Terminal ◇** — Cedar-copper cabinet, sun-amber phosphor, frost-on-glass scanlines
+- **◇ MCP Kinoomaagewinan / Tools ◇** — `start_game` and `make_choice` exposed as MCP tools
+- **◇ Giiwenaabik / Inference API ◇** — Serverless HF Inference API; no local GGUF, no build step
+- **◇ Asabiikesiwin / Cooldown ◇** — 6s default between inference calls to protect your credit budget
+- **◇ Bmaad-ziibi / Procedural Fallback ◇** — Full engine works without the LLM
+- **◇ Anishinaabe-Solarpunk ◇** — Sky-to-sunrise palette, syllabic framings, biophilic motifs
+
+## ☼ NITAM-AABAJICHIGANAN / PREREQUISITES ◈
+
+- Python 3.10+
+- A Hugging Face token (for the Inference API; many small models work anonymously)
+- ~100MB disk, ~256MB RAM — the model is serverless, not local
+
+## ◇ AABAJITOOWINAN / INSTALLATION ◈
+
+```bash
+git clone https://github.com/nbiish/tinybard.git
+cd tinybard
+pip install -r requirements.txt
+
+# Optional: pick a model (default: Qwen/Qwen2.5-1.5B-Instruct — small + fast + free)
+export INFERENCE_MODEL="Qwen/Qwen2.5-1.5B-Instruct"
+# Or for the originally-intended VibeThinker 1.5B:
+# export INFERENCE_MODEL="mradermacher/VibeThinker-1.5B-GGUF"
+
+# Optional: set the HF token (anonymous works for many models)
+export HF_TOKEN="hf_..."
+
+# Optional: tune the cooldown
+export TINYBARD_COOLDOWN_SECONDS=6
+
+python app.py
+```
+
+Then open <http://localhost:7860/>.
+
+## ◈ WAABANDA'IWEWIN / EXAMPLES ◇
+
+```text
+╭─────────────────────────────────────╮
+│  ᐴ AADIZOOKAAN / FANTASY ᔔ          │
+╰─────────────────────────────────────╯
+
+You stand before the gates of the Whisperwood. The ancient trees
+hum with a faint violet energy...
+
+[ Take the golden key ]   [ Drink the mossy vial ]   [ Press forward ]
+```
+
+## ☼ NAANAAGADAWENINDIZOWIN / VERIFICATION ◈
+
+```bash
+curl -X POST http://localhost:7860/api/game/start \
+  -H "Content-Type: application/json" \
+  -d '{"genre": "fantasy"}'
+```
+
+Returns clean JSON: `{"story", "choices", "health", "step", "game_over", "history"}`.
+
+```bash
+curl http://localhost:7860/api/model_status
+```
+
+Returns: `{"model": "...", "cooldown": {"active": bool, "remaining_seconds": float, "window_seconds": float}}`.
+
+## ◈ MODEL ◇
+
+| Model (default) | Size | Purpose | License |
+|---|---|---|---|
+| Qwen2.5-1.5B-Instruct | 1.5B | Interactive story generation | Apache 2.0 |
+| VibeThinker 1.5B | 1.5B | Alternative — also tiny | Apache 2.0 |
+
+Override `INFERENCE_MODEL` to any model that supports `chat_completion` on the HF Inference API. The 1.5B defaults fit the **Tiny Titan** badge.
+
+## ◇ MCP KINOOMAAGEWINAN / TOOLS ◈
+
+TinyBard runs with `mcp_server=True`, exposing these tools (also available as FastAPI endpoints):
+
+- **`/api/game/start`** (POST `{"genre": "fantasy|scifi|cyberpunk"}`) — Start an adventure
+- **`/api/game/choice`** (POST `{choice, genre, step, health, history}`) — Submit a player choice
+- **`/api/model_status`** (GET) — Check the inference model + cooldown state
+
+Connect from any MCP client (Claude Desktop, Cursor, etc.) to the SSE endpoint at `/gradio/gradio_api/mcp/`.
+
+## ◇ GIIZHIITAA / BADGE TARGETS ◇
+
+- **◆ Tiny Titan** — Model ≤ 1.5B (well under 4B limit)
+- **◆ Off-Brand** — Fully custom FastAPI+Gradio frontend
+- **◆ Field Notes** — Blog post about tiny model interactive fiction
+
+## ☼ GANAWENDAAGWAD / SECURITY ◈
+
+PQC standard for any future API keys via the `pqc-secrets` skill (ML-KEM-768 + AES-256-GCM). At present, only the HF token is in flight (read from env var, never written to disk).
+
+## ◇ AABAAJICHIGANAN / COOLDOWNS ◈
+
+The `shared/inference_client.py` module enforces per-project cooldowns. Cooldown protects your HF/Modal credit budget from runaway re-rolls. Defaults:
+
+- `tinybard`: 6s
+- `focusfriend`: 10s
+- `crittercalm`: 12s
+
+Override per project via Space env vars (`TINYBARD_COOLDOWN_SECONDS`, etc.).
+
+---
+
+◈──◆──◇ ☼ TinyBard v1.1 · Cedar Edition · Anishinaabe Solarpunk · Inference API ◇──◆──◈

__init__.py

@@ -0,0 +1 @@
+"""TinyBard — Micro Interactive Text Adventure Generator."""

app.py

@@ -0,0 +1,550 @@
+#!/usr/bin/env python3
+"""
+ᐴ TinyBard ᔔ — Aanishinaabe Mikinaak-Aki / Fire-Fly Storyteller
+==================================================================
+Custom FastAPI app with Gradio Blocks mounted for MCP tool integration.
+Cedar-and-copper CRT terminal frontend served as static HTML.
+
+Aesthetic: Anishinaabe Solarpunk — sky-to-sunrise palette, syllabic framings,
+           biophilic motifs, solarpunk hope.
+
+Targets: Thousand Token Wood + Tiny Titan + Llama Champion tracks.
+Badges: Llama Champion, Tiny Titan, Off-Brand (custom frontend),
+        Off the Grid, Field Notes.
+"""
+
+import os
+import json
+import random
+import logging
+import re
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+import threading
+
+import gradio as gr
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from gradio import mount_gradio_app
+
+# Inference client with cooldown (no local GGUF, no llama-cpp-python build!)
+# Path layout: monorepo/shared/inference_client.py — go up two parents from this file.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
+from shared.inference_client import (
+    InferenceResult,
+    cooldown_status,
+    cooldown_remaining,
+    cooldown_active,
+    generate as inference_generate,
+    chat_messages,
+    INFERENCE_MODEL,
+)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+log = logging.getLogger("tinybard")
+
+# ---------------------------------------------------------------------------
+# Config & Paths
+# ---------------------------------------------------------------------------
+BASE_DIR = Path(__file__).parent
+STATIC_DIR = BASE_DIR / "static"
+
+# Use HF Inference API (VibeThinker 1.5B by default — small, fast, free tier).
+# Override via Space env var: INFERENCE_MODEL.
+# Cooldown enforced in shared.inference_client.
+TINYBARD_MODEL = os.environ.get("TINYBARD_MODEL", INFERENCE_MODEL)
+
+# ---------------------------------------------------------------------------
+# User-configurable inference (BYO token / model)
+# ---------------------------------------------------------------------------
+_USER_CONFIG_LOCK = threading.Lock()
+_USER_CONFIG: Dict[str, Optional[str]] = {
+    "hf_token": None,
+    "model": None,
+}
+
+
+def get_user_hf_token() -> Optional[str]:
+    with _USER_CONFIG_LOCK:
+        return _USER_CONFIG["hf_token"]
+
+
+def get_user_model() -> Optional[str]:
+    with _USER_CONFIG_LOCK:
+        return _USER_CONFIG["model"]
+
+
+# ---------------------------------------------------------------------------
+# Llama.cpp Inference Setup
+# ---------------------------------------------------------------------------
+# No local LLM state — every inference call goes through the HF Inference API
+# with cooldown enforcement. Procedural fallback is always available.
+
+
+def llm_available() -> bool:
+    """True if we *might* succeed at an inference call (cooldown not active,
+    HF_TOKEN configured, model id is set)."""
+    import os
+    token = get_user_hf_token() or os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACEHUB_API_TOKEN")
+    model = get_user_model() or TINYBARD_MODEL
+    # Inference API still works anonymously for some models, so don't gate hard.
+    return bool(model) and not cooldown_active("tinybard")
+
+
+def last_inference_status() -> dict:
+    """Snapshot of the current cooldown + model for /api/model_status."""
+    return {
+        "model": get_user_model() or TINYBARD_MODEL,
+        "cooldown": cooldown_status("tinybard"),
+        "has_user_token": bool(get_user_hf_token()),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Procedural Fallback Adventure Engine
+# ---------------------------------------------------------------------------
+GENRES = {
+    "fantasy": {
+        "start": "You stand before the gates of the Whisperwood. The ancient trees hum with a faint violet energy.",
+        "nodes": [
+            {
+                "story": "A glowing sprite appears, offering a golden key or a mossy vial.",
+                "choices": ["Take the golden key", "Drink the mossy vial", "Ignore the sprite and press forward"]
+            },
+            {
+                "story": "You encounter a moss-covered stone golem blocking the path. It speaks in riddles.",
+                "choices": ["Answer its riddle with a joke", "Use your golden key if you have it", "Try to climb over it"]
+            },
+            {
+                "story": "You discover a hidden pool reflecting stars that aren't in the sky.",
+                "choices": ["Drink from the star pool", "Rest by the shore", "Toss a coin into the water"]
+            }
+        ],
+        "win": "You find the heart of the forest and unlock the ancient relic. You are victorious!",
+        "lose": "The energy of the forest overwhelms you. You fade into the whispers of the wood."
+    },
+    "scifi": {
+        "start": "The emergency lights flicker red in the derelict cargo bay of USS Horizon. Gravity is failing.",
+        "nodes": [
+            {
+                "story": "A leaking fuel pipe blocks the corridor ahead. Sparking wires fill the air.",
+                "choices": ["Siphon the fuel", "Bypass the circuits", "Wait for the cycle to clear"]
+            },
+            {
+                "story": "An automated security drone activates, targeting you with its laser system.",
+                "choices": ["Hack the drone terminal", "Throw scrap metal to distract it", "Run for the airlock"]
+            },
+            {
+                "story": "You reach the main computer terminal. The AI core is corrupt but online.",
+                "choices": ["Initiate override protocol", "Ask the AI for help", "Pull the main power breaker"]
+            }
+        ],
+        "win": "You restore life support and secure the escape pod. You survive!",
+        "lose": "The hull breaches. You are swept into the cold embrace of outer space."
+    },
+    "cyberpunk": {
+        "start": "Acid rain beats against the neon signs of Sector 9. Your neural interface is glitching.",
+        "nodes": [
+            {
+                "story": "A street dealer offers to patch your wetware for a few credits or a favor.",
+                "choices": ["Accept the shady patch", "Decline and buy a neural booster", "Threaten him for info"]
+            },
+            {
+                "story": "A corporate agent corners you in a wet alleyway. He demands your datapad.",
+                "choices": ["Upload a virus to his cyber-eyes", "Hand over a fake datapad", "Sprint up the fire escape"]
+            },
+            {
+                "story": "You infiltrate the mainframe room of Shinra-Tech. The security grid is active.",
+                "choices": ["Jack in directly", "Use your backup deck", "Short-circuit the access node"]
+            }
+        ],
+        "win": "You upload the corporate secrets to the net. Sector 9 is free. You win!",
+        "lose": "Your brain fried due to feedback from the security grid. Game Over."
+    }
+}
+
+
+def generate_procedural_step(genre: str, step: int, health: int, choice: str = "") -> dict:
+    """Generate a fallback adventure step without LLM."""
+    genre_data = GENRES.get(genre.lower(), GENRES["fantasy"])
+
+    if step == 0:
+        return {
+            "story": genre_data["start"],
+            "choices": genre_data["nodes"][0]["choices"],
+            "health": health,
+            "step": 1,
+            "game_over": False
+        }
+
+    health_delta = random.choice([-15, 0, 10])
+    new_health = max(0, min(100, health + health_delta))
+
+    if new_health <= 0:
+        return {
+            "story": f"After choosing: '{choice}'. " + genre_data["lose"],
+            "choices": [],
+            "health": 0,
+            "step": step + 1,
+            "game_over": True
+        }
+
+    if step >= 4:
+        return {
+            "story": f"After choosing: '{choice}'. " + genre_data["win"],
+            "choices": [],
+            "health": new_health,
+            "step": step + 1,
+            "game_over": True
+        }
+
+    node = genre_data["nodes"][step % len(genre_data["nodes"])]
+    return {
+        "story": f"You choose: '{choice}'.\n\n{node['story']}",
+        "choices": node["choices"],
+        "health": new_health,
+        "step": step + 1,
+        "game_over": False
+    }
+
+
+# ---------------------------------------------------------------------------
+# LLM Generation Logic (HF Inference API + cooldown)
+# ---------------------------------------------------------------------------
+def _parse_messages(genre: str, history: List[Dict[str, str]], next_instruction: str) -> list[Dict[str, str]]:
+    """Translate internal history into OpenAI-style chat messages."""
+    system = (
+        "You are the narrator of an interactive text adventure game. "
+        f"Genre: {genre}. Write in the second person ('You...'). "
+        "Keep descriptions highly atmospheric but short (under 3 sentences). "
+        "Focus on action, mystery, and choice."
+    )
+    msgs: List[Dict[str, str]] = [{"role": "system", "content": system}]
+    for h in (history or []):
+        if h.get("role") == "player":
+            msgs.append({"role": "user", "content": h["text"]})
+        elif h.get("role") == "narrator":
+            msgs.append({"role": "assistant", "content": h["text"]})
+    msgs.append({"role": "user", "content": next_instruction})
+    return msgs
+
+
+def generate_llm_turn(
+    genre: str,
+    history: List[Dict[str, str]],
+    current_health: int,
+    next_instruction: str,
+) -> dict:
+    """Generate one full adventure turn via the LLM.
+
+    Returns a dict with keys: story, choices, health_delta, game_over.
+    health_delta is typically -15, 0, or +10 (the model decides).
+    """
+    if cooldown_active("tinybard"):
+        log.info("tinybard turn skipped (cooldown active)")
+        return {}
+    system = (
+        "You are the narrator of an interactive text adventure game. "
+        f"Genre: {genre}. Write in the second person ('You...'). "
+        "Keep descriptions highly atmospheric but short (under 3 sentences). "
+        "Focus on action, mystery, and choice. "
+        "After the story beat, output exactly 3 short distinct player choices on one line, "
+        "in the format: 1. <choice> | 2. <choice> | 3. <choice>"
+    )
+    user = (
+        f"Current health: {current_health}/100. "
+        f"History so far: {json.dumps(history[-4:])}. "
+        f"{next_instruction} "
+        "Also state a health delta of -15, 0, or +10 that reflects how risky this turn was."
+    )
+    try:
+        result = inference_generate(
+            project="tinybard",
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            max_new_tokens=220,
+            temperature=0.7,
+        )
+        text = result.text.strip()
+    except Exception as e:
+        log.warning(f"HF Inference error (fallback to procedural): {e}")
+        return {}
+
+    # Split story and choices
+    story = text
+    choices = []
+    health_delta = 0
+    for sep in ["\n1.", "\n1. ", " 1.", " Choices:"]:
+        if sep in text:
+            parts = text.split(sep, 1)
+            story = parts[0].strip()
+            rest = parts[1].strip()
+            choices = _parse_choices("1. " + rest)
+            break
+
+    if not choices:
+        choices = _parse_choices(text)
+
+    # Extract a simple health delta from the text when possible
+    m = re.search(r"health delta\s*[:=]\s*([+-]?\d+)", text, re.IGNORECASE)
+    if m:
+        try:
+            health_delta = int(m.group(1))
+        except Exception:
+            health_delta = 0
+    else:
+        health_delta = random.choice([-15, 0, 10])
+
+    new_health = max(0, min(100, current_health + health_delta))
+    game_over = new_health <= 0
+    return {
+        "story": story,
+        "choices": choices[:3] if len(choices) >= 2 else [],
+        "health_delta": health_delta,
+        "new_health": new_health,
+        "game_over": game_over,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Gradio Blocks — API endpoints (exposed as MCP tools)
+# ---------------------------------------------------------------------------
+def create_gradio_app() -> gr.Blocks:
+    """Build the Gradio Blocks app with API endpoints for MCP integration."""
+
+    with gr.Blocks(title="TinyBard API") as blocks:
+        # Hidden state — not rendered in UI, used by API
+        genre_input = gr.Textbox(label="Genre", visible=False)
+        step_input = gr.Number(label="Step", value=0, visible=False)
+        health_input = gr.Number(label="Health", value=100, visible=False)
+        choice_input = gr.Textbox(label="Choice", visible=False)
+        history_input = gr.Textbox(label="History JSON", value="[]", visible=False)
+
+        # Output fields
+        story_output = gr.Textbox(label="Story")
+        choices_output = gr.JSON(label="Choices")
+        health_output = gr.Number(label="Health")
+        step_output = gr.Number(label="Step")
+        game_over_output = gr.Checkbox(label="Game Over")
+        history_output = gr.Textbox(label="History JSON")
+
+        def api_start_game(genre: str):
+            """Start a new interactive text adventure. Exposed as MCP tool."""
+            genre = genre.lower()
+            if genre not in ["fantasy", "scifi", "cyberpunk"]:
+                genre = "fantasy"
+
+            # Try LLM first (will skip if cooldown is active)
+            instruction = "Narrate the beginning of the adventure. What happens first? Do not offer choices yet."
+            turn = generate_llm_turn(genre, [], 100, instruction)
+            if not turn:
+                result = generate_procedural_step(genre, 0, 100)
+                return (
+                    result["story"], result["choices"], result["health"],
+                    result["step"], result["game_over"],
+                    json.dumps(result.get("history", []))
+                )
+
+            history = [{"role": "narrator", "text": turn["story"]}]
+            choices = turn["choices"] if len(turn.get("choices", [])) >= 2 else ["Explore the area", "Check your equipment", "Proceed carefully"]
+            return (turn["story"], choices[:3], 100, 1, False, json.dumps(history))
+
+        def api_make_choice(choice: str, genre: str, step: int, health: int, history_json: str):
+            """Submit a player choice to advance the story. Exposed as MCP tool."""
+            try:
+                history = json.loads(history_json)
+            except Exception:
+                history = []
+
+            step = int(step)
+            health = int(health)
+
+            history.append({"role": "player", "text": choice})
+
+            instruction = "Narrate what happens next as a result of the player's choice."
+            turn = generate_llm_turn(genre, history, health, instruction)
+            if not turn:
+                result = generate_procedural_step(genre, step, health, choice)
+                return (
+                    result["story"], result["choices"], result["health"],
+                    result["step"], result["game_over"],
+                    json.dumps(result.get("history", history))
+                )
+
+            history.append({"role": "narrator", "text": turn["story"]})
+            choices = turn["choices"] if len(turn.get("choices", [])) >= 2 else ["Move forward", "Look around", "Rest a moment"]
+
+            return (turn["story"], choices[:3], turn["new_health"], step + 1, turn["game_over"], json.dumps(history))
+
+        # Register API endpoints
+        gr.Button("Start Game").click(
+            fn=api_start_game,
+            inputs=[genre_input],
+            outputs=[story_output, choices_output, health_output, step_output, game_over_output, history_output],
+            api_name="start_game"
+        )
+
+        gr.Button("Make Choice").click(
+            fn=api_make_choice,
+            inputs=[choice_input, genre_input, step_input, health_input, history_input],
+            outputs=[story_output, choices_output, health_output, step_output, game_over_output, history_output],
+            api_name="make_choice"
+        )
+
+    return blocks
+
+
+def _parse_choices(choices_text: str) -> List[str]:
+    """Parse LLM choice output into a list of choices."""
+    choices = []
+    if "|" in choices_text:
+        choices = [c.split(".")[-1].strip() for c in choices_text.split("|")]
+    else:
+        for line in choices_text.split("\n"):
+            if "." in line or any(d in line for d in "123"):
+                parts = line.split(".", 1)
+                if len(parts) > 1:
+                    choices.append(parts[1].strip())
+    return choices
+
+
+# ---------------------------------------------------------------------------
+# FastAPI App — Custom frontend + Gradio API
+# ---------------------------------------------------------------------------
+fastapi_app = FastAPI(title="TinyBard", docs_url="/docs")
+
+
+@fastapi_app.get("/", response_class=HTMLResponse)
+async def homepage():
+    """Serve the retro CRT terminal frontend."""
+    index_path = STATIC_DIR / "index.html"
+    if index_path.exists():
+        return index_path.read_text()
+    return HTMLResponse("<h1>TinyBard retro terminal under construction!</h1>")
+@fastapi_app.get("/api/model_status")
+async def model_status():
+    """Check the inference client + cooldown status."""
+    return last_inference_status()
+
+
+# ---------------------------------------------------------------------------
+# Game Logic — exposed as both FastAPI (clean JSON) and Gradio (MCP)
+# ---------------------------------------------------------------------------
+def _run_turn(choice: str, genre: str, step: int, health: int, history: List[Dict]) -> dict:
+    """Single source of truth for one adventure turn.
+
+    Returns a dict the frontend can consume directly. Used by both the
+    FastAPI /api/game/* endpoints and the Gradio MCP tools.
+    """
+    in_cooldown = cooldown_active("tinybard")
+
+    if step == 0:
+        if in_cooldown:
+            return generate_procedural_step(genre, 0, 100)
+        instruction = "Narrate the beginning of the adventure. What happens first? Do not offer choices yet."
+        turn = generate_llm_turn(genre, [], 100, instruction)
+        if not turn:
+            return generate_procedural_step(genre, 0, 100)
+        history = [{"role": "narrator", "text": turn["story"]}]
+        choices = turn["choices"] if len(turn.get("choices", [])) >= 2 else ["Explore the area", "Check your equipment", "Proceed carefully"]
+        return {
+            "story": turn["story"], "choices": choices[:3], "health": 100,
+            "step": 1, "game_over": False, "history": history,
+        }
+
+    if in_cooldown:
+        return generate_procedural_step(genre, step, health, choice)
+
+    history.append({"role": "player", "text": choice})
+    instruction = "Narrate what happens next as a result of the player's choice."
+    turn = generate_llm_turn(genre, history, health, instruction)
+    if not turn:
+        return generate_procedural_step(genre, step, health, choice)
+    history.append({"role": "narrator", "text": turn["story"]})
+    choices = turn["choices"] if len(turn.get("choices", [])) >= 2 else ["Move forward", "Look around", "Rest a moment"]
+    return {
+        "story": turn["story"], "choices": choices[:3],
+        "health": turn["new_health"], "step": step + 1,
+        "game_over": turn["game_over"], "history": history,
+    }
+
+
+@fastapi_app.post("/api/game/start")
+async def game_start(payload: dict):
+    """Start a new adventure. Returns clean JSON.
+
+    Body: {"genre": "fantasy|scifi|cyberpunk"}
+    """
+    genre = (payload.get("genre") or "fantasy").lower()
+    if genre not in ["fantasy", "scifi", "cyberpunk"]:
+        genre = "fantasy"
+    return _run_turn(choice="", genre=genre, step=0, health=100, history=[])
+
+
+@fastapi_app.post("/api/game/choice")
+async def game_choice(payload: dict):
+    """Submit a player choice. Returns clean JSON.
+
+    Body: {
+        "choice": str, "genre": str, "step": int, "health": int,
+        "history": [{"role": ..., "text": ...}, ...]
+    }
+    """
+    return _run_turn(
+        choice=payload.get("choice", ""),
+        genre=payload.get("genre", "fantasy"),
+        step=int(payload.get("step", 1)),
+        health=int(payload.get("health", 100)),
+        history=payload.get("history", []),
+    )
+
+@fastapi_app.post("/api/config")
+async def update_config(body: dict):
+    with _USER_CONFIG_LOCK:
+        if body.get("hf_token"):
+            _USER_CONFIG["hf_token"] = body["hf_token"].strip() or None
+        if body.get("model") and str(body["model"]).strip():
+            _USER_CONFIG["model"] = str(body["model"]).strip()
+        current = dict(_USER_CONFIG)
+    return {
+        "status": "ok",
+        "model": current["model"] or TINYBARD_MODEL,
+        "has_token": bool(current["hf_token"]),
+    }
+
+
+@fastapi_app.get("/api/config")
+async def get_config():
+    with _USER_CONFIG_LOCK:
+        current = dict(_USER_CONFIG)
+    return {
+        "model": current["model"] or TINYBARD_MODEL,
+        "has_token": bool(current["hf_token"]),
+    }
+
+
+# Mount static files
+fastapi_app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+# Mount Gradio app at /gradio — this creates the API + MCP endpoints
+gradio_blocks = create_gradio_app()
+mount_gradio_app(fastapi_app, gradio_blocks, path="/gradio")
+
+# ---------------------------------------------------------------------------
+# Exported for HF Spaces Gradio SDK (launches once on import)
+# ---------------------------------------------------------------------------
+app = fastapi_app
+
+# ---------------------------------------------------------------------------
+# HF Spaces entrypoint — keep the ASGI server alive
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

requirements.txt

@@ -0,0 +1,18 @@
+# TinyBard — Micro Text Adventure Generator
+# Python 3.10+
+#
+# Inference is via the Hugging Face Inference API (no local GGUF,
+# no llama-cpp-python compile). Cooldown is enforced in
+# `shared/inference_client.py` to protect your credit budget.
+#
+# Set these Space secrets/variables to configure:
+#   HF_TOKEN              — your HF token (anonymous works for many small models)
+#   INFERENCE_MODEL       — model id (default: Qwen/Qwen2.5-1.5B-Instruct)
+#   TINYBARD_COOLDOWN_SECONDS — gap between inference calls (default 6)
+#   INFERENCE_PROVIDER    — "hf-inference" (default, free serverless) or paid
+#   INFERENCE_MAX_TOKENS  — per-call token cap (default 220)
+
+gradio>=5.0
+fastapi>=0.110
+huggingface_hub>=0.20
+uvicorn[standard]>=0.27

shared/cedar_copper_tokens.py

@@ -0,0 +1,151 @@
+"""
+Cedar-Copper Design Tokens
+============================
+Shared palette + decorative-glyph module for the build-small-hackathon monorepo.
+
+Each project's own CSS/UI embeds the tokens it needs (this file is a
+reference, not imported at runtime).
+
+Decorative Unicode glyphs in this file are intentionally NOT used in HF
+Spaces metadata — see llms.txt "HF Agents CLI" notes.
+"""
+
+# ── DECORATIVE GLYPHS (in-app banners, not HF metadata) ───────────────────────
+PUU = "\u1438"   # ᐸ — left frame character
+SHOO = "\u1514"  # ᔔ — right frame character
+BII = "\u142A"   # ᐪ
+MII = "\u14A1"   # ᑡ
+WA = "\u1418"    # ᐘ
+GO = "\u1472"    # ᑲ
+AN = "\u14B0"    # ᒐ
+
+SUN_RAY = "\u263C"   # ☼
+SUN_BLACK = "\u2600" # ☀
+LEAF = "\u2618"      # ☘
+FLOWER = "\u2740"    # ❀
+MEDICINE_WHEEL = "\u2697" # ⚗
+ARROW_UP = "\u21B3"  # ↳
+CIRCUIT = "\u25C8"   # ◈
+DIAMOND = "\u25C6"   # ◆
+DIAMOND_O = "\u25C7" # ◇
+
+# ── COLOR PALETTE ──────────────────────────────────────────────────────────────
+PALETTE = {
+    # Sky and water
+    "sky":       "#5BA4D9",  # light morning sky
+    "water":     "#1B4965",  # deep lake water
+    "ice":       "#BEE9E8",  # spring thaw
+    "frost":     "#CAF0F8",  # winter light
+    # Sun
+    "sun":       "#F2A93B",  # rising sun amber
+    "sunlight":  "#FFB347",  # warm ray
+    "ember":     "#E76F51",  # dusk ember
+    # Earth
+    "birch":     "#F5F1E8",  # birchbark white
+    "terracotta":"#C8553D",  # clay red
+    "earth":     "#8B3A1F",  # deep earth / copper
+    "moss":      "#588157",  # forest moss
+    "forest":    "#3D6A4A",  # cedar forest
+    "spruce":    "#1B4332",  # deep spruce (night)
+    # Contrast
+    "night":     "#0F1A2C",  # deep night sky
+    "ash":       "#3A2E2A",  # woodsmoke
+    "stone":     "#A89F91",  # river stone
+    "ink":       "#1A1F2E",  # deep ink
+}
+
+# ── PROJECT FRAMING ───────────────────────────────────────────────────────────
+def header(title: str, en: str) -> str:
+    """Cedar-copper banner header for a project.
+
+    Usage:
+        header("TinyBard", "MICRO TEXT ADVENTURE")
+    """
+    line = f"{DIAMOND}{CIRCUIT}{DIAMOND_O}"
+    return (
+        f"\n{line}{CIRCUIT}{PUU} {title} {SHOO} [{en.upper()}] "
+        f"{CIRCUIT}{line}\n"
+    )
+
+
+def footer() -> str:
+    """Closing banner."""
+    return f"\n{DIAMOND_O}{CIRCUIT}{DIAMOND} {SUN_RAY} \u00b7 {LEAF} \u00b7 {WATER_ICON()} \u00b7 {SUN_BLACK} {CIRCUIT}{DIAMOND}{DIAMOND_O}\n"
+
+
+def WATER_ICON() -> str:
+    return "\u2248"  # ≈ (approx, like a wave)
+
+
+# ── THEME CONSTANTS (CSS variables) ──────────────────────────────────────────
+CSS_VARS = f"""
+:root {{
+  --cc-sky:       {PALETTE['sky']};
+  --cc-water:     {PALETTE['water']};
+  --cc-ice:       {PALETTE['ice']};
+  --cc-sun:       {PALETTE['sun']};
+  --cc-sunlight:  {PALETTE['sunlight']};
+  --cc-ember:     {PALETTE['ember']};
+  --cc-birch:     {PALETTE['birch']};
+  --cc-terra:     {PALETTE['terracotta']};
+  --cc-earth:     {PALETTE['earth']};
+  --cc-moss:      {PALETTE['moss']};
+  --cc-forest:    {PALETTE['forest']};
+  --cc-spruce:    {PALETTE['spruce']};
+  --cc-night:     {PALETTE['night']};
+  --cc-ash:       {PALETTE['ash']};
+  --cc-stone:     {PALETTE['stone']};
+  --cc-ink:       {PALETTE['ink']};
+}}
+"""
+
+
+# ── SHARED CSS SNIPPETS ───────────────────────────────────────────────────────
+def style_banner() -> str:
+    """A standard top-of-app banner with cedar-copper styling."""
+    return """
+/* === CEDAR-COPPER BANNER ============================================== */
+.cc-banner {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.6em;
+  padding: 14px 18px;
+  background: linear-gradient(95deg, var(--cc-sky) 0%, var(--cc-water) 100%);
+  color: var(--cc-birch);
+  border-bottom: 1px solid rgba(255, 179, 71, 0.35);
+  font-family: Georgia, 'Iowan Old Style', serif;
+  letter-spacing: 0.5px;
+  text-shadow: 0 1px 2px rgba(15, 26, 44, 0.35);
+}
+.cc-banner .syll { font-size: 1.4em; opacity: 0.85; }
+.cc-banner .title { font-size: 1.05em; font-weight: 600; }
+.cc-banner .glyph {
+  display: inline-block;
+  transform: translateY(-1px);
+  font-size: 1.1em;
+  color: var(--cc-sunlight);
+}
+/* ===================================================================== */
+"""
+
+
+# ── WELCOME TEXT ──────────────────────────────────────────────────────────────
+WELCOME = (
+    f"{PUU} Welcome {SHOO} \u2014 The land remembers you. "
+    f"{SUN_RAY} {LEAF} {WATER_ICON()}"
+)
+
+
+# ── CHARACTER (TinyBard, FocusFriend) ────────────────────────────────────────
+PIP_GREETING_CEDAR_COPPER = (
+    f"{PUU} Hello, friend {SHOO} \u2014 I am Pip, the friend of the moss "
+    f"and the small winds. Sit. Breathe. The sun is in no hurry. {SUN_BLACK}"
+)
+
+
+if __name__ == "__main__":
+    print(header("Build Small Hackathon", "CODER SANCTUARY"))
+    print(WELCOME)
+    print(PIP_GREETING_CEDAR_COPPER)
+    print(footer())

shared/inference_client.py

@@ -0,0 +1,179 @@
+"""
+Shared HF Inference Client + Cooldown
+======================================
+Lightweight wrapper around `huggingface_hub.InferenceClient` with:
+
+- Per-call cooldown to prevent credit burn on live HF Spaces
+- Async-friendly API
+- Auto-fallback to procedural/story-template engines when inference fails
+- Environment-driven config (works in HF Spaces and local)
+
+The cooldown model:
+- Each project has its own cooldown window (default 8s for cheap inference APIs)
+- Within a session, after a successful inference, no new call can run until cooldown expires
+- Failed inference does not start a cooldown (allow quick retry)
+- `cooldown_active()` is the public check; FastAPI handlers short-circuit on active cooldown
+"""
+from __future__ import annotations
+
+import os
+import time
+import logging
+import threading
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, Callable, List
+
+log = logging.getLogger("inference")
+
+# ── Environment knobs ─────────────────────────────────────────────────────────
+# Override these in your Space's "Settings → Variables and secrets".
+
+# The HF model id used for text generation (VibeThinker 1.5B, Gemma 4 12B, etc.)
+INFERENCE_MODEL = os.environ.get(
+    "INFERENCE_MODEL",
+    "Qwen/Qwen2.5-1.5B-Instruct",  # small, fast, free-tier friendly
+)
+
+# Provider: "hf-inference" (free serverless), "together", "fal-ai", "replicate"
+# Free HF inference works for many small models; otherwise use a paid provider.
+INFERENCE_PROVIDER = os.environ.get("INFERENCE_PROVIDER", "hf-inference")
+
+# Token — read from HF Space secrets at runtime.
+HF_TOKEN = os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACEHUB_API_TOKEN")
+
+# Default cooldown between inferences, in seconds.
+COOLDOWN_SECONDS = float(os.environ.get("INFERENCE_COOLDOWN_SECONDS", "8"))
+
+# Per-project override (keyed by app name)
+PROJECT_COOLDOWN_OVERRIDES = {
+    "tinybard": float(os.environ.get("TINYBARD_COOLDOWN_SECONDS", "6")),
+    "focusfriend": float(os.environ.get("FOCUSFRIEND_COOLDOWN_SECONDS", "10")),
+    "crittercalm": float(os.environ.get("CRITTERCALM_COOLDOWN_SECONDS", "12")),
+}
+
+# Max tokens to request (keeps costs bounded)
+MAX_NEW_TOKENS = int(os.environ.get("INFERENCE_MAX_TOKENS", "220"))
+# ── Cooldown registry ────────────────────────────────────────────────────────
+@dataclass
+class _CooldownState:
+    last_call: float = 0.0
+    lock: threading.Lock = field(default_factory=threading.Lock)
+_states: Dict[str, _CooldownState] = {}
+def _state(project: str) -> _CooldownState:
+    if project not in _states:
+        _states[project] = _CooldownState()
+    return _states[project]
+def cooldown_seconds_for(project: str) -> float:
+    return PROJECT_COOLDOWN_OVERRIDES.get(project, COOLDOWN_SECONDS)
+def cooldown_active(project: str) -> bool:
+    """Return True if the project is currently in cooldown (cannot run inference)."""
+    state = _state(project)
+    now = time.time()
+    if now - state.last_call < cooldown_seconds_for(project):
+        return True
+    return False
+def cooldown_remaining(project: str) -> float:
+    """Seconds left in the cooldown window (0 if not in cooldown)."""
+    state = _state(project)
+    elapsed = time.time() - state.last_call
+    remaining = cooldown_seconds_for(project) - elapsed
+    return max(0.0, remaining)
+def cooldown_status(project: str) -> dict:
+    """Snapshot of cooldown state for the UI."""
+    return {
+        "active": cooldown_active(project),
+        "remaining_seconds": round(cooldown_remaining(project), 2),
+        "window_seconds": cooldown_seconds_for(project),
+    }
+def _mark_called(project: str) -> None:
+    state = _state(project)
+    with state.lock:
+        state.last_call = time.time()
+# ── Inference client wrapper ─────────────────────────────────────────────────
+class InferenceResult:
+    """A small wrapper so callers don't need to know which API returned text."""
+    def __init__(self, text: str, model: str, provider: str, latency_s: float):
+        self.text = text
+        self.model = model
+        self.provider = provider
+        self.latency_s = latency_s
+
+    def __repr__(self) -> str:
+        return f"InferenceResult(text={self.text[:50]!r}…, model={self.model!r}, latency={self.latency_s:.2f}s)"
+def _get_client():
+    """Lazy-load the InferenceClient to keep boot fast."""
+    from huggingface_hub import InferenceClient
+    return InferenceClient(
+        model=INFERENCE_MODEL,
+        token=HF_TOKEN,  # provider kwarg removed for hf-inference default
+        
+    )
+def generate(
+    project: str,
+    messages: List[Dict[str, str]],
+    *,
+    max_new_tokens: Optional[int] = None,
+    temperature: float = 0.7,
+) -> InferenceResult:
+    """Run a chat-style inference call, with cooldown enforcement.
+
+    `messages` follows OpenAI chat format: [{"role": "user|assistant|system", "content": "..."}].
+    Returns InferenceResult with `.text` (string) on success, or raises on failure.
+    Caller is responsible for fallback handling.
+    """
+    if cooldown_active(project):
+        remaining = cooldown_remaining(project)
+        raise RuntimeError(
+            f"cooldown active for {project!r}: {remaining:.1f}s remaining. "
+            f"This protects your HF/Modal credit budget."
+        )
+
+    max_new_tokens = max_new_tokens or MAX_NEW_TOKENS
+    client = _get_client()
+    start = time.time()
+    response = client.chat_completion(
+        messages=messages,
+        max_tokens=max_new_tokens,
+        temperature=temperature,
+    )
+    latency = time.time() - start
+    text = response.choices[0].message.content or ""
+    text = text.strip()
+    _mark_called(project)
+    return InferenceResult(
+        text=text,
+        model=INFERENCE_MODEL,
+        provider=INFERENCE_PROVIDER,
+        latency_s=latency,
+    )
+def force_clear_cooldown(project: str) -> None:
+    """Manual escape hatch (e.g. for testing or admin overrides)."""
+    _state(project).last_call = 0.0
+# ── Convenience: build messages + format result ──────────────────────────────
+def chat_messages(system: str, user: str, history: Optional[List[Dict[str, str]]] = None) -> List[Dict[str, str]]:
+    """Build an OpenAI-style message list with optional prior turns.
+
+    `history` is in the same [{role, content}, ...] format. New turns are appended.
+    """
+    msgs: List[Dict[str, str]] = [{"role": "system", "content": system}]
+    if history:
+        msgs.extend(history)
+    msgs.append({"role": "user", "content": user})
+    return msgs
+__all__ = [
+    "InferenceResult",
+    "cooldown_active",
+    "cooldown_remaining",
+    "cooldown_seconds_for",
+    "cooldown_status",
+    "force_clear_cooldown",
+    "generate",
+    "chat_messages",
+    "INFERENCE_MODEL",
+    "INFERENCE_PROVIDER",
+    "MAX_NEW_TOKENS",
+]
+if __name__ == "__main__":
+    # Smoke test
+    for p in ("tinybard", "focusfriend", "crittercalm"):
+        print(p, "cooldown:", cooldown_status(p))

static/index.html

@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>ᐴ TinyBard ᔔ — Aanishinaabe Mikinaak-Aki</title>
+    <link rel="stylesheet" href="/static/style.css">
+</head>
+<body>
+    <header class="asp-banner">
+        <span class="syll">ᐴ</span>
+        <span class="glyph">☼</span>
+        <span class="title">TINYBARD</span>
+        <span class="glyph">☘</span>
+        <span class="subtitle">— a fire-fly storyteller in cedar and copper —</span>
+        <span class="syll">ᔔ</span>
+    </header>
+    <div class="crt-container">
+        <div class="crt-screen" id="screen">
+            <div class="scanlines"></div>
+            <div class="vignette"></div>
+
+            <div class="terminal" id="terminal">
+                <div class="terminal-header">
+                    <span class="prompt">ᐴ TINYBARD v1.0 ᔔ  ·  GIIZHI-AADIZOKED</span>
+                    <span class="status" id="health-bar">NOOSISKAAZOWIN: <span id="health-val">100</span></span><button id="config-btn" style="float:right;background:none;border:1px solid var(--asp-amber,#FFB347);color:var(--asp-sun,#F2A93B);cursor:pointer;font-family:monospace;font-size:0.75rem;padding:0.15rem 0.4rem;border-radius:2px;">⚙ CONFIG</button>
+                </div>
+
+                <div class="terminal-body" id="output">
+                    <div class="boot-sequence" id="boot">
+                        <span class="line">☼ &gt; INITIAINDIZOWIN / INITIALIZING NEURAL INTERFACE...</span>
+                        <span class="line">☼ &gt; AABAJICHIGANAN / LOADING NARRATIVE ENGINE...</span>
+                        <span class="line">☼ &gt; GIIWENAABIK / CONNECTING TO GRADIO SERVER...</span>
+                        <span class="line success">☼ &gt; MII-GIIWETA / CONNECTION ESTABLISHED</span>
+                        <span class="line">ᐴ &gt; INAABANDA'IWIN / SELECT GENRE TO BEGIN ᔔ</span>
+                    </div>
+                </div>
+
+                <div class="genre-selector" id="genre-selector">
+                    <div class="genre-option" data-genre="fantasy">
+                        <span class="icon">☼</span> AADIZOOKAAN / FANTASY
+                    </div>
+                    <div class="genre-option" data-genre="scifi">
+                        <span class="icon">◈</span> ISHPIMING / SCI-FI
+                    </div>
+                    <div class="genre-option" data-genre="cyberpunk">
+                        <span class="icon">◆</span> MASHKODEWAAZIBI / CYBERPUNK
+                    </div>
+                </div>
+
+                <div class="choices-container" id="choices" style="display: none;">
+                    <!-- Choices injected here -->
+                </div>
+
+                <div class="input-line" id="input-line" style="display: none;">
+                    <span class="prompt-char">ᐴ&gt;</span>
+                    <input type="text" id="cmd-input" autocomplete="off" spellcheck="false" />
+                    <span class="cursor">_</span>
+                </div>
+
+                <div class="terminal-footer">
+                    <span>ᐴ TinyBard · FastAPI + Gradio + MCP · llama.cpp ᔔ</span>
+                    <span id="model-status">☘ MODEL: AABAJICHIGE / LOADING...</span>
+                </div>
+            </div>
+        </div>
+
+        <div class="crt-reflection"></div>
+    </div>
+
+    <script type="module" src="/static/main.js"></script>
+
+    <!-- User config modal -->
+    <div id="tb-config-modal" class="tb-modal-overlay" style="display:none;">
+        <div class="tb-modal">
+            <button class="tb-close" id="tb-config-close">✕</button>
+            <h3>⚙ Inference Configuration</h3>
+            <p style="font-size:0.8rem;color:var(--asp-moss,#588157);">
+                Provide your own HuggingFace token to unlock models that need auth.
+                Your token lives in browser memory only — never sent anywhere except api.huggingface.co.
+            </p>
+            <label for="tb-model-input">Model ID</label>
+            <input type="text" id="tb-model-input" placeholder="Qwen/Qwen2.5-1.5B-Instruct" />
+
+            <label for="tb-token-input">HF Token (optional)</label>
+            <input type="password" id="tb-token-input" placeholder="hf_..." />
+
+            <button id="tb-config-save">Save & Reload</button>
+            <span id="tb-config-status" style="margin-left:0.5rem;color:var(--asp-moss,#588157);"></span>
+        </div>
+    </div>
+</body>
+</html>

static/main.js

@@ -0,0 +1,296 @@
+/**
+ * TinyBard — Frontend Client
+ * Connects to the gr.Server backend via @gradio/client.
+ * All game state is managed client-side and passed to the API.
+ */
+
+const GRADIO_CLIENT_URL = window.location.origin;
+
+// ---------------------------------------------------------------------------
+// Game State
+// ---------------------------------------------------------------------------
+let gameState = {
+    genre: "",
+    step: 0,
+    health: 100,
+    history: [],
+    gameActive: false
+};
+
+// ---------------------------------------------------------------------------
+// DOM refs
+// ---------------------------------------------------------------------------
+const output = document.getElementById("output");
+const choicesEl = document.getElementById("choices");
+const genreSelector = document.getElementById("genre-selector");
+const inputLine = document.getElementById("input-line");
+const cmdInput = document.getElementById("cmd-input");
+const healthVal = document.getElementById("health-val");
+const modelStatus = document.getElementById("model-status");
+const boot = document.getElementById("boot");
+
+// ---------------------------------------------------------------------------
+// API client — uses FastAPI clean-JSON endpoints
+// ---------------------------------------------------------------------------
+async function checkModelStatus() {
+    try {
+        const resp = await fetch(`${GRADIO_CLIENT_URL}/api/model_status`);
+        if (!resp.ok) return;
+        const s = await resp.json();
+        const model = s.model || "inference";
+        const cd = s.cooldown || { active: false, remaining_seconds: 0, window_seconds: 0 };
+        if (cd.active) {
+            modelStatus.textContent = `☘ ${model} / COOLDOWN ${cd.remaining_seconds.toFixed(1)}s`;
+            modelStatus.style.color = "var(--asp-ember)";
+        } else if (model) {
+            modelStatus.textContent = `☘ ${model} / READY`;
+            modelStatus.style.color = "var(--asp-sun)";
+        } else {
+            modelStatus.textContent = "☘ NO MODEL / FALLBACK";
+            modelStatus.style.color = "var(--asp-frost)";
+        }
+    } catch {
+        modelStatus.textContent = "☘ MODEL: ?";
+    }
+}
+
+// Poll model status every 2s so cooldown countdown updates
+setInterval(checkModelStatus, 2000);
+async function apiCall(endpoint, payload) {
+    // Use the FastAPI clean-JSON endpoints (returns a dict directly).
+    // /api/game/start  -> start_game
+    // /api/game/choice -> make_choice
+    const path = endpoint === "/start_game"
+        ? "/api/game/start"
+        : "/api/game/choice";
+    const resp = await fetch(`${GRADIO_CLIENT_URL}${path}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    if (!resp.ok) {
+        throw new Error(`HTTP ${resp.status}`);
+    }
+    return await resp.json();
+}
+
+// ---------------------------------------------------------------------------
+// UI Helpers
+// ---------------------------------------------------------------------------
+function scrollToBottom() {
+    output.scrollTop = output.scrollHeight;
+}
+
+function appendOutput(html, className = "") {
+    const el = document.createElement("div");
+    el.className = className;
+    el.innerHTML = html;
+    output.appendChild(el);
+    scrollToBottom();
+}
+
+function clearBoot() {
+    if (boot) boot.remove();
+}
+
+function updateHealth(hp) {
+    gameState.health = hp;
+    healthVal.textContent = hp;
+    if (hp <= 25) healthVal.style.color = "#ff0040";
+    else if (hp <= 50) healthVal.style.color = "#ffb000";
+    else healthVal.style.color = "#00ff41";
+}
+
+function showChoices(choices) {
+    choicesEl.innerHTML = "";
+    choicesEl.style.display = "flex";
+
+    choices.forEach((choice, i) => {
+        const btn = document.createElement("button");
+        btn.className = "choice-btn";
+        btn.textContent = choice;
+        btn.addEventListener("click", () => handleChoice(choice));
+        choicesEl.appendChild(btn);
+    });
+}
+
+function hideChoices() {
+    choicesEl.style.display = "none";
+    choicesEl.innerHTML = "";
+}
+
+function showInput() {
+    inputLine.style.display = "flex";
+    cmdInput.focus();
+}
+
+function hideInput() {
+    inputLine.style.display = "none";
+}
+
+// ---------------------------------------------------------------------------
+// Game Logic
+// ---------------------------------------------------------------------------
+async function startGame(genre) {
+    gameState = { genre, step: 0, health: 100, history: [], gameActive: true };
+    genreSelector.style.display = "none";
+    clearBoot();
+
+    appendOutput(`<span class="narrator-prefix">> STARTING ${genre.toUpperCase()} ADVENTURE...</span>`, "line amber");
+    updateHealth(100);
+
+    try {
+        const data = await apiCall("/start_game", { genre });
+
+        gameState.step = data.step || 1;
+        gameState.history = data.history || [];
+
+        const storyEl = document.createElement("div");
+        storyEl.className = "story-text";
+        storyEl.textContent = data.story;
+        output.appendChild(storyEl);
+
+        if (data.game_over) {
+            endGame(data);
+        } else {
+            showChoices(data.choices);
+        }
+    } catch (e) {
+        appendOutput(`<span class="error">ERROR: ${e.message}</span>`, "line error");
+        console.error(e);
+    }
+    scrollToBottom();
+}
+
+async function handleChoice(choice) {
+    if (!gameState.gameActive) return;
+
+    hideChoices();
+    appendOutput(`<span class="player-action">> You chose: ${choice}</span>`, "player-action");
+
+    try {
+        const data = await apiCall("/make_choice", {
+            choice,
+            genre: gameState.genre,
+            step: gameState.step,
+            health: gameState.health,
+            history_json: JSON.stringify(gameState.history)
+        });
+
+        gameState.step = data.step || gameState.step + 1;
+        gameState.history = data.history || gameState.history;
+        updateHealth(data.health ?? gameState.health);
+
+        const storyEl = document.createElement("div");
+        storyEl.className = "story-text";
+        storyEl.textContent = data.story;
+        output.appendChild(storyEl);
+
+        if (data.game_over) {
+            endGame(data);
+        } else {
+            showChoices(data.choices);
+        }
+    } catch (e) {
+        appendOutput(`<span class="error">ERROR: ${e.message}</span>`, "line error");
+        console.error(e);
+    }
+    scrollToBottom();
+}
+
+function endGame(data) {
+    gameState.gameActive = false;
+    hideChoices();
+
+    const isWin = data.health > 0;
+    const className = isWin ? "game-over-win" : "game-over-lose";
+    const label = isWin ? "★ VICTORY ★" : "☠ GAME OVER ☠";
+
+    appendOutput(`<div class="${className}">${label}<br><small>Final Health: ${data.health}</small></div>`, "");
+
+    // New game button
+    const btn = document.createElement("button");
+    btn.className = "new-game-btn";
+    btn.textContent = "[ NEW ADVENTURE ]";
+    btn.addEventListener("click", resetGame);
+    choicesEl.style.display = "flex";
+    choicesEl.appendChild(btn);
+}
+
+function resetGame() {
+    output.innerHTML = "";
+    hideChoices();
+    gameState = { genre: "", step: 0, health: 100, history: [], gameActive: false };
+    healthVal.textContent = "100";
+    healthVal.style.color = "#00ff41";
+    genreSelector.style.display = "flex";
+}
+
+// ---------------------------------------------------------------------------
+// Event Listeners
+// ---------------------------------------------------------------------------
+document.querySelectorAll(".genre-option").forEach(el => {
+    el.addEventListener("click", () => {
+        const genre = el.dataset.genre;
+        startGame(genre);
+    });
+});
+
+cmdInput.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && cmdInput.value.trim()) {
+        handleChoice(cmdInput.value.trim());
+        cmdInput.value = "";
+    }
+});
+
+
+// ---------------------------------------------------------------------------
+// User Config Modal
+// ---------------------------------------------------------------------------
+const configBtn = document.getElementById('config-btn');
+const configModal = document.getElementById('tb-config-modal');
+const configClose = document.getElementById('tb-config-close');
+const configSave = document.getElementById('tb-config-save');
+const modelInput = document.getElementById('tb-model-input');
+const tokenInput = document.getElementById('tb-token-input');
+const configStatus = document.getElementById('tb-config-status');
+
+if (configBtn && configModal) {
+    configBtn.addEventListener('click', async () => {
+        const cfg = await fetch('/api/config').then(r => r.json());
+        modelInput.value = cfg.model || '';
+        tokenInput.value = '';
+        configStatus.textContent = '';
+        configModal.style.display = 'flex';
+    });
+
+    configClose.addEventListener('click', () => {
+        configModal.style.display = 'none';
+    });
+
+    configModal.addEventListener('click', (e) => {
+        if (e.target === configModal) configModal.style.display = 'none';
+    });
+
+    configSave.addEventListener('click', async () => {
+        const body = {};
+        if (modelInput.value.trim()) body.model = modelInput.value.trim();
+        if (tokenInput.value.trim()) body.hf_token = tokenInput.value.trim();
+
+        const resp = await fetch('/api/config', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        const data = await resp.json();
+        configStatus.textContent = data.status === 'ok' ? '✓ Saved' : '✗ Failed';
+        configStatus.style.color = data.status === 'ok' ? 'var(--asp-sun)' : 'var(--asp-ember)';
+        setTimeout(() => { configModal.style.display = 'none'; }, 800);
+    });
+}
+
+// Boot
+// ---------------------------------------------------------------------------
+(async () => {
+    await checkModelStatus();
+})();

static/style.css

@@ -0,0 +1,500 @@
+/* =========================================================================
+   TinyBard — Anishinaabe Solarpunk CRT Terminal
+   ----------------------------------------------------------------------------
+   A retro CRT terminal reinterpreted through Anishinaabe + Solarpunk lenses.
+   Phosphor glow becomes "fire-fly light"; scanlines become "birch-bark rings";
+   the cabinet's amber becomes rising sun; the screen is the lake (Gichigami)
+   at dusk, framed in cedar and copper.
+   ========================================================================= */
+
+/* === ANISHINAABE-SOLARPUNK DESIGN TOKENS ============================== */
+:root {
+    /* Solarpunk palette */
+    --asp-sky:       #5BA4D9;
+    --asp-water:     #1B4965;
+    --asp-ice:       #BEE9E8;
+    --asp-frost:     #CAF0F8;
+    --asp-sun:       #F2A93B;
+    --asp-sunlight:  #FFB347;
+    --asp-ember:     #E76F51;
+    --asp-birch:     #F5F1E8;
+    --asp-terra:     #C8553D;
+    --asp-earth:     #8B3A1F;
+    --asp-moss:      #588157;
+    --asp-forest:    #3D6A4A;
+    --asp-spruce:    #1B4332;
+    --asp-night:     #0F1A2C;
+    --asp-ash:       #3A2E2A;
+    --asp-stone:     #A89F91;
+    --asp-ink:       #1A1F2E;
+
+    /* CRT / terminal legacy (re-anchored to solarpunk palette) */
+    --green:       var(--asp-sun);       /* phosphor -> rising sun amber */
+    --green-dim:   #C97F1E;              /* dim sun */
+    --green-dark:  #5E3A0E;              /* cedar-bark */
+    --green-glow:  rgba(242, 169, 59, 0.18);
+    --amber:       var(--asp-sunlight);
+    --red:         var(--asp-ember);
+    --bg:          var(--asp-night);
+    --terminal-bg: linear-gradient(160deg, #0F1A2C 0%, #1A2A1F 100%);
+    --scanline-opacity: 0.04;
+}
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+@font-face {
+    font-family: 'MonoFallback';
+    src: local('JetBrains Mono'), local('Fira Code'), local('SF Mono'), local('Menlo'), local('monospace');
+}
+
+body {
+    background:
+        radial-gradient(ellipse at top, #1B4965 0%, transparent 60%),
+        radial-gradient(ellipse at bottom right, #1B4332 0%, transparent 70%),
+        var(--bg);
+    font-family: 'MonoFallback', monospace;
+    color: var(--asp-birch);
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    overflow-x: hidden;
+    overflow-y: auto;
+}
+
+/* === ANISHINAABE-SOLARPUNK BANNER ===================================== */
+.asp-banner {
+    width: 90vw;
+    max-width: 900px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.7em;
+    padding: 12px 18px;
+    margin-top: 18px;
+    background: linear-gradient(95deg, var(--asp-sky) 0%, var(--asp-water) 100%);
+    color: var(--asp-birch);
+    border: 1px solid rgba(255, 179, 71, 0.3);
+    border-radius: 10px 10px 0 0;
+    font-family: Georgia, 'Iowan Old Style', serif;
+    letter-spacing: 0.5px;
+    text-shadow: 0 1px 2px rgba(15, 26, 44, 0.45);
+    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.4);
+}
+.asp-banner .syll { font-size: 1.5em; opacity: 0.9; }
+.asp-banner .title { font-size: 1.05em; font-weight: 600; }
+.asp-banner .glyph {
+    display: inline-block;
+    transform: translateY(-1px);
+    font-size: 1.15em;
+    color: var(--asp-sunlight);
+}
+.asp-banner .subtitle {
+    color: var(--asp-frost);
+    font-size: 0.85em;
+    font-style: italic;
+    opacity: 0.85;
+}
+
+/* === CRT MONITOR (cedar-copper cabinet) ================================ */
+.crt-container {
+    width: 90vw;
+    max-width: 900px;
+    height: 75vh;
+    max-height: 660px;
+    position: relative;
+    background:
+        linear-gradient(180deg, #8B3A1F 0%, #5E2710 100%);
+    border-radius: 18px 18px 30px 30px;
+    padding: 22px;
+    box-shadow:
+        0 0 80px rgba(91, 164, 217, 0.12),
+        inset 0 0 60px rgba(0, 0, 0, 0.5),
+        0 20px 60px rgba(0, 0, 0, 0.8);
+}
+
+/* decorative bezel rivets — medicine wheel */
+.crt-container::before,
+.crt-container::after {
+    content: "◈";
+    position: absolute;
+    top: 8px;
+    color: var(--asp-sunlight);
+    opacity: 0.6;
+    font-size: 0.9em;
+}
+.crt-container::before { left: 12px; }
+.crt-container::after { right: 12px; }
+
+.crt-screen {
+    width: 100%;
+    height: 100%;
+    background: var(--terminal-bg);
+    border-radius: 12px;
+    overflow: hidden;
+    position: relative;
+    border: 2px solid #1B4332;
+    box-shadow:
+        inset 0 0 80px rgba(27, 73, 50, 0.5),
+        inset 0 0 4px rgba(255, 179, 71, 0.2);
+}
+
+/* Scanlines — birch-bark rings reinterpreted */
+.scanlines {
+    position: absolute;
+    top: 0; left: 0; right: 0; bottom: 0;
+    background: repeating-linear-gradient(
+        0deg,
+        transparent,
+        transparent 2px,
+        rgba(91, 164, 217, var(--scanline-opacity)) 2px,
+        rgba(91, 164, 217, var(--scanline-opacity)) 4px
+    );
+    pointer-events: none;
+    z-index: 10;
+}
+
+/* Vignette — horizon glow */
+.vignette {
+    position: absolute;
+    top: 0; left: 0; right: 0; bottom: 0;
+    background: radial-gradient(
+        ellipse at 50% 30%,
+        rgba(242, 169, 59, 0.05) 0%,
+        transparent 50%,
+        rgba(15, 26, 44, 0.55) 100%
+    );
+    pointer-events: none;
+    z-index: 10;
+}
+
+/* CRT reflection/glare — frost on glass */
+.crt-reflection {
+    position: absolute;
+    top: 5%;
+    left: 5%;
+    width: 40%;
+    height: 30%;
+    background: linear-gradient(
+        135deg,
+        rgba(190, 233, 232, 0.05) 0%,
+        transparent 100%
+    );
+    pointer-events: none;
+    z-index: 20;
+    border-radius: 50%;
+}
+
+/* === TERMINAL LAYOUT ================================================== */
+.terminal {
+    width: 100%;
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    padding: 15px 20px;
+    position: relative;
+    z-index: 5;
+    color: var(--asp-birch);
+}
+
+.terminal-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding-bottom: 10px;
+    border-bottom: 1px solid rgba(91, 164, 217, 0.3);
+    margin-bottom: 10px;
+    font-size: 0.75rem;
+    color: var(--asp-frost);
+    text-transform: uppercase;
+    letter-spacing: 2px;
+    font-family: Georgia, serif;
+}
+.terminal-header .status {
+    color: var(--asp-sunlight);
+    text-shadow: 0 0 8px rgba(242, 169, 59, 0.35);
+}
+#health-val { color: var(--asp-sun); font-weight: bold; }
+
+/* === TERMINAL OUTPUT ================================================== */
+.terminal-body {
+    flex: 1;
+    overflow-y: auto;
+    overflow-x: hidden;
+    padding-right: 10px;
+    font-size: 0.88rem;
+    line-height: 1.65;
+    text-shadow: 0 0 6px rgba(242, 169, 59, 0.15);
+    scroll-behavior: smooth;
+}
+.terminal-body::-webkit-scrollbar { width: 6px; }
+.terminal-body::-webkit-scrollbar-track { background: transparent; }
+.terminal-body::-webkit-scrollbar-thumb {
+    background: rgba(91, 164, 217, 0.3);
+    border-radius: 3px;
+}
+
+.line {
+    display: block;
+    margin-bottom: 3px;
+    opacity: 0;
+    animation: typeIn 0.5s forwards;
+}
+.line.success { color: var(--asp-sunlight); }
+.line.error { color: var(--asp-ember); }
+.line.amber { color: var(--asp-sun); }
+
+.story-text {
+    display: block;
+    margin: 14px 0;
+    padding: 12px 16px;
+    border-left: 2px solid var(--asp-sun);
+    background: rgba(91, 164, 217, 0.06);
+    border-radius: 0 4px 4px 0;
+    white-space: pre-wrap;
+    color: var(--asp-birch);
+    animation: fadeSlideIn 0.6s ease-out;
+    box-shadow: inset 0 0 20px rgba(15, 26, 44, 0.3);
+}
+
+.narrator-prefix {
+    color: var(--asp-sun);
+    font-weight: bold;
+    text-shadow: 0 0 8px rgba(242, 169, 59, 0.4);
+}
+
+.player-action {
+    display: block;
+    color: var(--asp-frost);
+    margin: 5px 0;
+    font-style: italic;
+    border-left: 2px dashed rgba(190, 233, 232, 0.4);
+    padding-left: 8px;
+}
+
+.game-over-win {
+    color: var(--asp-sunlight);
+    text-shadow: 0 0 20px rgba(255, 179, 71, 0.6);
+    font-size: 1.15rem;
+    text-align: center;
+    padding: 20px;
+    animation: pulse 2s infinite;
+    font-family: Georgia, serif;
+}
+
+.game-over-lose {
+    color: var(--asp-ember);
+    text-shadow: 0 0 20px rgba(231, 111, 81, 0.5);
+    font-size: 1.15rem;
+    text-align: center;
+    padding: 20px;
+    animation: pulse 2s infinite;
+    font-family: Georgia, serif;
+}
+
+/* === GENRE SELECTOR =================================================== */
+.genre-selector {
+    display: flex;
+    gap: 15px;
+    padding: 15px 0;
+    justify-content: center;
+    flex-wrap: wrap;
+}
+
+.genre-option {
+    padding: 12px 25px;
+    border: 1px solid rgba(91, 164, 217, 0.4);
+    border-radius: 4px;
+    cursor: pointer;
+    transition: all 0.2s;
+    text-transform: uppercase;
+    letter-spacing: 1.5px;
+    font-size: 0.8rem;
+    color: var(--asp-frost);
+    background: rgba(15, 26, 44, 0.4);
+}
+
+.genre-option:hover {
+    background: linear-gradient(95deg, rgba(242, 169, 59, 0.2) 0%, rgba(91, 164, 217, 0.2) 100%);
+    color: var(--asp-sunlight);
+    border-color: var(--asp-sun);
+    text-shadow: 0 0 12px rgba(242, 169, 59, 0.6);
+    box-shadow: 0 0 18px rgba(242, 169, 59, 0.3);
+    transform: translateY(-1px);
+}
+
+.genre-option .icon { margin-right: 8px; font-size: 1.1em; color: var(--asp-sun); }
+
+/* === CHOICE BUTTONS =================================================== */
+.choices-container {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    padding: 10px 0;
+}
+
+.choice-btn {
+    display: block;
+    padding: 10px 15px;
+    border: 1px solid rgba(91, 164, 217, 0.4);
+    border-radius: 3px;
+    background: transparent;
+    color: var(--asp-frost);
+    font-family: 'MonoFallback', monospace;
+    font-size: 0.82rem;
+    cursor: pointer;
+    text-align: left;
+    transition: all 0.15s;
+    text-shadow: 0 0 3px rgba(91, 164, 217, 0.25);
+}
+
+.choice-btn:hover {
+    background: rgba(91, 164, 217, 0.1);
+    border-color: var(--asp-sun);
+    color: var(--asp-sunlight);
+    padding-left: 25px;
+    box-shadow: 0 0 12px rgba(242, 169, 59, 0.2);
+}
+
+.choice-btn::before {
+    content: '☼ ';
+    color: var(--asp-sun);
+    margin-right: 4px;
+}
+
+/* === INPUT LINE ======================================================= */
+.input-line {
+    display: flex;
+    align-items: center;
+    padding: 10px 0 5px;
+    border-top: 1px solid rgba(91, 164, 217, 0.3);
+    margin-top: 5px;
+}
+
+.prompt-char {
+    color: var(--asp-sun);
+    margin-right: 8px;
+    font-weight: bold;
+    text-shadow: 0 0 8px rgba(242, 169, 59, 0.5);
+}
+
+#cmd-input {
+    flex: 1;
+    background: transparent;
+    border: none;
+    color: var(--asp-birch);
+    font-family: 'MonoFallback', monospace;
+    font-size: 0.88rem;
+    outline: none;
+    caret-color: transparent;
+}
+
+.cursor {
+    color: var(--asp-sun);
+    text-shadow: 0 0 6px rgba(242, 169, 59, 0.6);
+    animation: blink 0.8s step-end infinite;
+}
+
+/* === TERMINAL FOOTER ================================================== */
+.terminal-footer {
+    display: flex;
+    justify-content: space-between;
+    padding-top: 8px;
+    border-top: 1px solid rgba(91, 164, 217, 0.2);
+    margin-top: 8px;
+    font-size: 0.65rem;
+    color: var(--asp-stone);
+    letter-spacing: 1.5px;
+}
+
+#model-status { color: var(--asp-moss); }
+
+/* === HEALTH BAR ====================================================== */
+.health-bar-visual {
+    width: 100%;
+    height: 4px;
+    background: rgba(15, 26, 44, 0.6);
+    border-radius: 2px;
+    margin-top: 5px;
+    overflow: hidden;
+    border: 1px solid rgba(91, 164, 217, 0.3);
+}
+
+.health-bar-fill {
+    height: 100%;
+    background: linear-gradient(90deg, var(--asp-sun) 0%, var(--asp-sunlight) 100%);
+    transition: width 0.5s ease, background-color 0.5s;
+    border-radius: 2px;
+    box-shadow: 0 0 8px rgba(242, 169, 59, 0.5);
+}
+
+.health-bar-fill.low { background: linear-gradient(90deg, var(--asp-ember) 0%, var(--asp-terra) 100%); }
+.health-bar-fill.mid { background: linear-gradient(90deg, var(--asp-sun) 0%, var(--asp-amber, #FFB347) 100%); }
+
+/* === NEW GAME BUTTON ================================================= */
+.new-game-btn {
+    display: inline-block;
+    padding: 10px 22px;
+    border: 1px solid rgba(91, 164, 217, 0.4);
+    border-radius: 3px;
+    background: transparent;
+    color: var(--asp-frost);
+    font-family: 'MonoFallback', monospace;
+    font-size: 0.78rem;
+    cursor: pointer;
+    text-transform: uppercase;
+    letter-spacing: 1.5px;
+    margin-top: 10px;
+    transition: all 0.2s;
+}
+
+.new-game-btn:hover {
+    background: linear-gradient(95deg, rgba(242, 169, 59, 0.2) 0%, rgba(91, 164, 217, 0.2) 100%);
+    color: var(--asp-sunlight);
+    border-color: var(--asp-sun);
+    box-shadow: 0 0 16px rgba(242, 169, 59, 0.35);
+}
+
+/* === ANIMATIONS ====================================================== */
+@keyframes typeIn {
+    from { opacity: 0; transform: translateY(5px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+@keyframes fadeSlideIn {
+    from { opacity: 0; transform: translateX(-10px); }
+    to { opacity: 1; transform: translateX(0); }
+}
+@keyframes blink {
+    50% { opacity: 0; }
+}
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.65; }
+}
+
+/* CRT power-on (sun rising) */
+.crt-screen {
+    animation: sunRise 0.7s ease-out;
+}
+@keyframes sunRise {
+    0%   { opacity: 0; transform: scaleY(0.01); box-shadow: inset 0 0 0 rgba(242, 169, 59, 0); }
+    40%  { opacity: 1; transform: scaleY(0.01); }
+    60%  { transform: scaleY(1.05); }
+    80%  { transform: scaleY(0.98); }
+    100% { transform: scaleY(1); box-shadow: inset 0 0 80px rgba(27, 73, 50, 0.5); }
+}
+
+/* === MOBILE ========================================================== */
+@media (max-width: 600px) {
+    .crt-container {
+        width: 95vw;
+        height: 78vh;
+        padding: 12px;
+        border-radius: 14px;
+    }
+    .genre-selector { flex-direction: column; gap: 8px; }
+    .genre-option { text-align: center; }
+    .terminal-body { font-size: 0.78rem; }
+    .asp-banner { font-size: 0.85em; }
+}