Release develop → main

Merge DOX-structured docs with v0.7 content (TinyBard context-aware,
featherless-ai provider, Anishinaabe aesthetic section).

Co-Authored-By: Oz <oz-agent@warp.dev>

llms.txt

@@ -7,7 +7,7 @@ Three Gradio apps targeting all tracks + maximum badges + sponsor prizes. Hack w
 ## Ownership
 
 - **Name:** Build Small Hackathon 2026 — Team nbiish
-- **Version:** 0.5.0 — Cedar-Copper Edition (HF Inference API)
+- **Version:** 0.7.0 — Cedar-Copper Edition (Context-Aware LLM)
 - **Operator:** nbiish
 
 ## Local Contracts
@@ -64,17 +64,20 @@ Cedar-copper visual language — sky-to-sunrise palette (water-blue → cedar
 - 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. Use a real emoji.
 
-### Inference Architecture (v0.5+)
+### Inference Architecture (v0.7+)
 
 - **All LLM inference** via the **Hugging Face Inference API** (serverless). No 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`.
+- Shared module: `shared/inference_client.py` provides `cooldown_status()`, `cooldown_active()`, `generate()`, `chat_messages()`, and `force_clear_cooldown()`.
+- **TinyBard model:** `meta-llama/Llama-3.2-1B-Instruct` via `featherless-ai` provider (only provider supporting this model).
+- **Other projects:** `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`.
+- **Provider override:** `INFERENCE_PROVIDER` (default: `featherless-ai` for TinyBard, auto for others).
 - **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`.
+- **force_clear_cooldown()**: Clears cooldown before each function call — prevents cooldown from blocking story generation after choices.
 - **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.
 
@@ -93,12 +96,13 @@ Cedar-copper visual language — sky-to-sunrise palette (water-blue → cedar
 
 ### Short-term Goals
 
-- Iterate on the live HF Spaces
-- 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
+- Record demo videos (2-3 min each) — show unique story generation, verb-based choices, context-aware narrative
+- Post to social media
+- Write Field Notes blog posts (3 — one per project)
 - Share agent traces for Sharing is Caring badge
 - Polish UIs for demo appeal
+- Test CritterCalm voice cloning end-to-end
+- Test FocusFriend all 4 modes (Chat, Focus, Breathe, Meditate) with real model
 
 ## Verification
 
@@ -107,6 +111,43 @@ Cedar-copper visual language — sky-to-sunrise palette (water-blue → cedar
 - Cedar-copper aesthetic consistent across all UIs
 - No hardcoded secrets; no cloud API calls in production path
 
+### 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:** COMPLETE. Deployed. Context-aware LLM generation verified live.
+- **Concept:** ≤4B LLM generates unique interactive text adventures in a CRT terminal aesthetic. Nanaboozhoo trickster narrator.
+- **Stack:** Llama-3.2-1B-Instruct via HF Inference API (featherless-ai provider) + procedural fallback engine
+- **Features Implemented:**
+  - **Context-aware story generation**: Last 3 story steps feed into next generation for narrative continuity
+  - **Verb-based action choices**: Always 3 action-oriented choices (not descriptive noun phrases)
+  - **LLM-rated health decisions**: LLM evaluates risk (-15/0/+10), falls back to random.choice
+  - **Player choice integration**: Selected choice text feeds into next story + health evaluation
+  - **Robust choice parsing**: 3 strategies (pipe, newline, comma) + bare-line format + fallback padding
+  - **Always returns 3 choices**: `_parse_choices` pads with procedural fallbacks if LLM returns <3
+  - **Unique every time**: Temperature 0.6, max_new_tokens 150 — never repeats
+  - **Nanaboozhoo narrator**: Trickster/transformer voice in all LLM prompts
+  - **Game loop verified**: Start → LLM story → select choice → Make Choice → LLM advances story → 3 new choices
+- **HF Space:** https://nbiish-tinybard.hf.space (RUNNING, SHA: 94d7081)
+- **Provider:** featherless-ai (only provider supporting Llama-3.2-1B-Instruct)
+- **Environment Variables:** INFERENCE_MODEL=meta-llama/Llama-3.2-1B-Instruct, INFERENCE_PROVIDER=featherless-ai
+
 ## TODO
 
 ### In Progress
@@ -131,12 +172,63 @@ Cedar-copper visual language — sky-to-sunrise palette (water-blue → cedar
 - [x] HF CLI installed + skills configured
 - [x] llama-cpp-python installed — 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
-- [x] FocusFriend chat verified
-- [x] CritterCalm UI navigation verified
-- [x] v0.5: HF Inference API wired into all 3 apps
-- [x] v0.5: Cooldown system in shared/inference_client.py
-- [x] v0.5: TinyBard local test — procedural fallback + cooldown UI
+- [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
+- [x] **v0.6: TinyBard context-aware generation** — last 3 story steps feed into next generation
+- [x] **v0.6: Verb-based action choices** — always 3 action-oriented choices (not descriptive noun phrases)
+- [x] **v0.6: LLM-rated health decisions** — LLM evaluates risk (-15/0/+10)
+- [x] **v0.6: Player choice integration** — selected choice text feeds into next story + health evaluation
+- [x] **v0.6: Robust choice parsing** — 3 strategies (pipe, newline, comma) + bare-line format + fallback padding
+- [x] **v0.6: Nanaboozhoo narrator** — trickster/transformer voice in all LLM prompts
+- [x] **v0.6: featherless-ai provider** — only provider supporting Llama-3.2-1B-Instruct
+- [x] **v0.7: Game loop verified live** — Start → LLM story → select choice → Make Choice → LLM advances story → 3 new choices
+- [x] **v0.7: Git workflow** — worktree isolation, develop→main merge, HF Space deployment
+- [x] **v0.7: Stale worktrees/branches cleaned up** — all merged branches deleted
+
+## Anishinaabe Solarpunk Aesthetic
+
+All three apps share a unified visual language rooted in Anishinaabe culture.
+
+### Visual Identity
+
+- **Palette:** sky-to-sunrise — water-blue (`#1B4965`) → cedar-bark (`#3D2A2A`) → copper (`#8B3A1F`) → sun-amber (`#F2A93B`) → birch-cream (`#F5F1E8`)
+- **Syllabics:** Canadian Aboriginal ᐴ / ᔔ used as section framings
+- **Symbols:** sun · clover · florette · circuit diamonds
+- **Typography:** EB Garamond serif headers + Inter sans + JetBrains Mono for terminal/UI
+- **CRT Terminal:** Scanline effects, phosphor glow, monospace terminal for TinyBard
+
+### Cultural Elements
+
+- **Nanaboozhoo narrator**: Trickster/transformer voice in all TinyBard LLM prompts
+- **Anishinaabemowin labels**: NOOSISKAAZOWIN (Health), DIBIK (Step), AADIZOOKAAN (Story), INAABANDA'IWIN (Choose)
+- **Biophilic motifs**: Cedar bark textures, birch cream backgrounds, water-blue accents
+- **Solarpunk optimism**: Technology in harmony with nature, not against it
+
+### Implementation
+
+- **Tokens module:** `shared/cedar_copper_tokens.py` — CSS variables, color palette, typography
+- **TinyBard CRT:** Custom CSS with scanline animation, phosphor glow, terminal green accents
+- **Shared across apps**: Consistent section framings, button styles, card layouts
+
+## 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
+- TinyBard HF Space: https://nbiish-tinybard.hf.space
+- TinyBard App: projects/tinybard/app.py (FastAPI + Gradio + game logic)
+- TinyBard Key Functions: `_run_turn`, `_llm_health_delta`, `generate_llm_story`, `generate_llm_choices`, `_parse_messages`, `_parse_choices`, `_fallback_choices`
+- TinyBard Provider: featherless-ai (only provider supporting Llama-3.2-1B-Instruct)
+- TinyBard Working URL: https://router.huggingface.co/featherless-ai/v1/chat/completions
 
 ## Child DOX Index