restructure: monorepo with both projects under projects/

Move CritterCalm root files → projects/crittercalm/
Add FocusFriend → projects/focusfriend/
New root README with coordination overview.
All code coordinated from single repo for further iteration.

Co-Authored-By: Nanoboozhoo <nanoboozhoo@git-aaaki>

.agents/tasks/TASK.2026-06-07.md

@@ -1,32 +0,0 @@
-# CritterCalm — Build Task
-
-**Branch:** feat/crittercalm-animal-voice-soother
-**Worktree:** ../crittercalm
-**Track:** Backyard AI
-**Date:** 2026-06-07
-
-## Chain-of-Draft
-
-1. Scaffold: mkdir voice_cloning content utils
-2. Write app.py — 3-tab Gradio Blocks
-3. OmniVoice wrapper — lazy-load, clone, cache embed
-4. Dolphin-X1-8B script gen — system prompt, template fallback
-5. Kokoro TTS fallback — built-in voices
-6. Pre-written templates — 6 animals × 8 situations × scripts
-7. Audio utils — load, save, validate, duration
-8. requirements.txt + README.md
-9. Wire imports across modules
-10. Verify: all deps resolve, app launches
-
-####
-
-## Deliverables
-- [x] app.py — Main Gradio app (3 tabs)
-- [x] voice_cloning/ — OmniVoice integration
-- [x] content/ — Script generation + templates
-- [x] utils/ — Audio processing
-- [x] requirements.txt
-- [x] README.md
-- [ ] Deploy to HF Spaces
-- [ ] Demo video
-- [ ] Social post

README.md

@@ -1,83 +1,38 @@
----
-title: CritterCalm
-emoji: 🐾
-colorFrom: green
-colorTo: yellow
-sdk: gradio
-sdk_version: 5.0.0
-app_file: app.py
-pinned: false
-license: apache-2.0
-tags:
-  - voice-cloning
-  - tts
-  - pets
-  - animals
-  - backyard-ai
-  - build-small-hackathon
-  - local-first
-  - off-the-grid
----
+# Build Small Hackathon — Monorepo
 
-# 🐾  CritterCalm — AI Voice Cloning Animal Soother
+**Team coordination for the Hugging Face Build Small Hackathon (June 5-15, 2026).**
 
-**Clone your voice. Calm your pets.**
-
-CritterCalm clones your voice using state-of-the-art open-source AI, then generates
-personalized calming audio sessions for your pets. Dogs, cats, chickens, birds,
-rabbits, horses — every animal responds to their person's voice.
-
-## ✨  Features
-
-- **🎤  Voice Cloning** — Clone your voice from just 3-10 seconds of audio
-- **🐕  Multi-Animal Support** — Species-specific calming techniques for 6 animal types
-- **🎯  Situation-Aware** — Tailored scripts for anxiety, storms, vet visits, and more
-- **🔌  100% Local** — No cloud APIs, no data collection, fully offline
-- **📚  Science-Backed** — Based on animal cognition and psychoacoustics research
-
-## 🚀  Quick Start
-
-```bash
-# Clone and install
-git clone <this-repo>
-cd crittercalm
-pip install -r requirements.txt
-
-# Download models (first run will auto-download from Hugging Face)
-python app.py
+```
+build-small-hackathon/
+├── AGENTS.md              # Agent instructions & workflow
+├── HACKATHON_README.md    # Full hackathon reference
+├── SUBMISSION_DRAFTS.md   # Social posts + Field Notes drafts
+├── projects/
+│   ├── crittercalm/       # 🐾  Voice Cloning Animal Soother
+│   └── focusfriend/       # ✦  ASCII Wellness Companion
+└── .agents/               # Skills & task tracking
 ```
 
-## 🧠  Model Stack
-
-| Model | Size | Purpose | License |
-|-------|------|---------|---------|
-| OmniVoice | 0.6B | Voice cloning + TTS | Apache 2.0 |
-| Dolphin-X1-8B | 8B | Calming script generation | Llama 3.1 |
-| Kokoro TTS | 82M | Built-in soothing voices (fallback) | Apache 2.0 |
-
-**Total: ~8.7B params** (well under the 32B limit)
-
-## 🏅  Hackathon Track
-
-**Backyard AI** — Solving a real problem for real pet owners.
+## Projects
 
-### Bonus Badges
-- 🔌  **Off the Grid** — Fully local, no API calls
-- 🎯  **Well-Tuned** — Fine-tuned voice embeddings for pet-directed speech
-- 📓  **Field Notes** — Blog post on animal psychoacoustics + voice cloning
+| Project | Track | Badges | GitHub |
+|---------|-------|--------|--------|
+| 🐾 **CritterCalm** | Backyard AI | Off the Grid, Well-Tuned, Field Notes | [nbiish/crittercalm](https://github.com/nbiish/crittercalm) |
+| ✦ **FocusFriend** | Thousand Token Wood | Off-Brand, Off the Grid, Field Notes | [nbiish/focusfriend](https://github.com/nbiish/focusfriend) |
 
-## 📁  Project Structure
+## Quick Links
 
-```
-crittercalm/
-├── app.py                 # Main Gradio application
-├── voice_cloning/         # OmniVoice integration
-├── content/               # Script generation + templates
-├── utils/                 # Audio processing utilities
-├── requirements.txt
-└── README.md
-```
+- [Submission Checklist](HACKATHON_README.md#-submission-checklist-due-june-15)
+- [Draft Posts & Field Notes](SUBMISSION_DRAFTS.md)
+- [Hackathon Discord](https://discord.gg/YHECTft87Z)
 
-## 🤝  Credits
+## Remaining Tasks
 
-Built with ❤️ for the Build Small Hackathon 2026.
+- [ ] Test both apps locally
+- [ ] Download GGUF models
+- [ ] Deploy to HF Spaces under `build-small-hackathon` org
+- [ ] Record demo videos
+- [ ] Post to social media
+- [ ] Submit via HF org
+- [ ] Fine-tune voice model (Well-Tuned badge)
+- [ ] Share agent traces (Sharing is Caring badge)

projects/crittercalm/.gitignore

@@ -0,0 +1,128 @@
+# AINISH Coder Tooling Distribution - Git Ignore Patterns
+# PlatformIO ignore patterns
+
+# PlatformIO ignore patterns
+.pio*
+.pio/
+*.pioenvs/
+pio.ini
+
+# Environment and configuration files
+.env
+.env.*
+!.env.example
+*.env.local
+*.env.development
+*.env.test
+*.env.production
+
+# Virtual environments
+venv/
+venv.bak/
+venv.bak*
+venv.*
+.venv/
+ENV/
+env/
+.conda/
+.python-version
+*/.env
+*/*env.*
+!*env.example
+
+# IDE and editor files
+.vscode/
+*.sublime-project
+*.sublime-workspace
+
+# OS generated files
+.DS_Store
+.DS_Store?
+
+# Security and secrets
+*.key
+*.pem
+*.p12
+*.pfx
+*.crt
+*.csr
+*.pem
+*.p12
+*.pfx
+*.jks
+*.keystore
+secrets/
+.secrets
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+*.db-journal
+
+# Backup files
+*.bak
+*.backup
+*.backup.*
+*.old
+*.orig
+*.rej
+*.orig
+*.swp
+*.swo
+
+# Rust
+target/
+
+# Python
+__pycache__/
+*.pyc
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+
+# Shared Libraries
+*.so
+*.dylib
+*.dll
+
+# General
+*.log
+*.tmp
+*.new
+tmp/
+
+# Node.js
+node_modules/
+npm-debug.log
+yarn-error.log
+.pnpm-debug.log
+
+# Security reports
+SECURITY_REPORT.md
+
+# Scrolls Lab runtime artifacts
+scrolls-lab/logs/
+scrolls-lab/reference/
+scrolls-lab/omni_output/
+scrolls-lab/sections/
+scrolls-lab/working/
+scrolls-lab/original/
+scrolls-lab/output/
+*.patch
+
+# Omni Extractor media files (global safety)
+**/*.jpg
+**/*.mp4
+**/*.vtt
+providers.txt
+**/providers.txt
+providers**.txt
+**/providers**.txt
+
+# Scrolls ceremony cloned repos (large)
+.scrolls-ceremony/repos/
+
+# Graphify scratch output
+graphify-out/

projects/crittercalm/README.md

@@ -0,0 +1,83 @@
+---
+title: CritterCalm
+emoji: 🐾
+colorFrom: green
+colorTo: yellow
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app.py
+pinned: false
+license: apache-2.0
+tags:
+  - voice-cloning
+  - tts
+  - pets
+  - animals
+  - backyard-ai
+  - build-small-hackathon
+  - local-first
+  - off-the-grid
+---
+
+# 🐾  CritterCalm — AI Voice Cloning Animal Soother
+
+**Clone your voice. Calm your pets.**
+
+CritterCalm clones your voice using state-of-the-art open-source AI, then generates
+personalized calming audio sessions for your pets. Dogs, cats, chickens, birds,
+rabbits, horses — every animal responds to their person's voice.
+
+## ✨  Features
+
+- **🎤  Voice Cloning** — Clone your voice from just 3-10 seconds of audio
+- **🐕  Multi-Animal Support** — Species-specific calming techniques for 6 animal types
+- **🎯  Situation-Aware** — Tailored scripts for anxiety, storms, vet visits, and more
+- **🔌  100% Local** — No cloud APIs, no data collection, fully offline
+- **📚  Science-Backed** — Based on animal cognition and psychoacoustics research
+
+## 🚀  Quick Start
+
+```bash
+# Clone and install
+git clone <this-repo>
+cd crittercalm
+pip install -r requirements.txt
+
+# Download models (first run will auto-download from Hugging Face)
+python app.py
+```
+
+## 🧠  Model Stack
+
+| Model | Size | Purpose | License |
+|-------|------|---------|---------|
+| OmniVoice | 0.6B | Voice cloning + TTS | Apache 2.0 |
+| Dolphin-X1-8B | 8B | Calming script generation | Llama 3.1 |
+| Kokoro TTS | 82M | Built-in soothing voices (fallback) | Apache 2.0 |
+
+**Total: ~8.7B params** (well under the 32B limit)
+
+## 🏅  Hackathon Track
+
+**Backyard AI** — Solving a real problem for real pet owners.
+
+### Bonus Badges
+- 🔌  **Off the Grid** — Fully local, no API calls
+- 🎯  **Well-Tuned** — Fine-tuned voice embeddings for pet-directed speech
+- 📓  **Field Notes** — Blog post on animal psychoacoustics + voice cloning
+
+## 📁  Project Structure
+
+```
+crittercalm/
+├── app.py                 # Main Gradio application
+├── voice_cloning/         # OmniVoice integration
+├── content/               # Script generation + templates
+├── utils/                 # Audio processing utilities
+├── requirements.txt
+└── README.md
+```
+
+## 🤝  Credits
+
+Built with ❤️ for the Build Small Hackathon 2026.

projects/focusfriend/.gitignore

@@ -0,0 +1,128 @@
+# AINISH Coder Tooling Distribution - Git Ignore Patterns
+# PlatformIO ignore patterns
+
+# PlatformIO ignore patterns
+.pio*
+.pio/
+*.pioenvs/
+pio.ini
+
+# Environment and configuration files
+.env
+.env.*
+!.env.example
+*.env.local
+*.env.development
+*.env.test
+*.env.production
+
+# Virtual environments
+venv/
+venv.bak/
+venv.bak*
+venv.*
+.venv/
+ENV/
+env/
+.conda/
+.python-version
+*/.env
+*/*env.*
+!*env.example
+
+# IDE and editor files
+.vscode/
+*.sublime-project
+*.sublime-workspace
+
+# OS generated files
+.DS_Store
+.DS_Store?
+
+# Security and secrets
+*.key
+*.pem
+*.p12
+*.pfx
+*.crt
+*.csr
+*.pem
+*.p12
+*.pfx
+*.jks
+*.keystore
+secrets/
+.secrets
+
+# Database files
+*.db
+*.sqlite
+*.sqlite3
+*.db-journal
+
+# Backup files
+*.bak
+*.backup
+*.backup.*
+*.old
+*.orig
+*.rej
+*.orig
+*.swp
+*.swo
+
+# Rust
+target/
+
+# Python
+__pycache__/
+*.pyc
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+
+# Shared Libraries
+*.so
+*.dylib
+*.dll
+
+# General
+*.log
+*.tmp
+*.new
+tmp/
+
+# Node.js
+node_modules/
+npm-debug.log
+yarn-error.log
+.pnpm-debug.log
+
+# Security reports
+SECURITY_REPORT.md
+
+# Scrolls Lab runtime artifacts
+scrolls-lab/logs/
+scrolls-lab/reference/
+scrolls-lab/omni_output/
+scrolls-lab/sections/
+scrolls-lab/working/
+scrolls-lab/original/
+scrolls-lab/output/
+*.patch
+
+# Omni Extractor media files (global safety)
+**/*.jpg
+**/*.mp4
+**/*.vtt
+providers.txt
+**/providers.txt
+providers**.txt
+**/providers**.txt
+
+# Scrolls ceremony cloned repos (large)
+.scrolls-ceremony/repos/
+
+# Graphify scratch output
+graphify-out/

projects/focusfriend/README.md

@@ -0,0 +1,95 @@
+---
+title: FocusFriend
+emoji: ✦
+colorFrom: indigo
+colorTo: amber
+sdk: gradio
+sdk_version: 5.0.0
+app_file: app.py
+pinned: false
+license: apache-2.0
+tags:
+  - wellness
+  - ascii-art
+  - meditation
+  - focus
+  - thousand-token-wood
+  - build-small-hackathon
+  - local-first
+  - off-the-grid
+  - tiny-titan
+---
+
+# ✦  FocusFriend — Pip, Your ASCII Wellness Companion
+
+**A tiny ASCII character who genuinely wants you to feel better.**
+
+Pip is a wise, dry-witted, slightly mischievous but genuinely caring wellness
+companion. Not a sycophantic cheerleader. Think: "your friend who's been through
+therapy and wants you to actually feel better, not just hear platitudes."
+
+## ✨  Features
+
+- **💬  Chat Mode** — Talk to Pip. Real conversation, no corny platitudes.
+- **🎯  Focus Mode** — Pomodoro-style work sessions. Pip keeps time, stays quiet.
+- **🌬️  Breathe Mode** — Guided 4-7-8, box breathing, and simple deep breathing.
+- **🧘  Meditate Mode** — Body scan, loving-kindness, and just-sitting meditations.
+- **🎨  Custom UI** — Dark, cozy theme with real-time ASCII art expressions.
+- **🔌  100% Local** — No cloud APIs, no data collection, fully offline.
+
+## 🚀  Quick Start
+
+```bash
+# Clone and install
+git clone <this-repo>
+cd focusfriend
+pip install -r requirements.txt
+
+# Download Gemma 4 12B GGUF model
+huggingface-cli download unsloth/gemma-4-12b-it-GGUF \
+  --include "gemma-4-12b-it-Q4_K_M.gguf" \
+  --local-dir ./models
+
+# Launch
+python app.py
+```
+
+## 🧠  Model
+
+| Model | Size | Purpose | License |
+|-------|------|---------|---------|
+| Gemma 4 12B | 12B | Conversational AI + wellness guidance | Apache 2.0 (Gemma) |
+
+Runs on a laptop with Q4_K_M quantization (~7.7 GB).
+
+## 🏅  Hackathon Track
+
+**Thousand Token Wood** — A delightful AI experience that wouldn't exist without AI.
+
+### Bonus Badges
+- 🦙  **Tiny Titan** — Runs on ≤4B param model option available
+- 🎨  **Off-Brand** — Fully custom dark theme CSS + JavaScript
+- 🔌  **Off the Grid** — Fully local, no API calls
+- 📓  **Field Notes** — Blog post about AI wellness companions
+
+## 🎭  Meet Pip
+
+```
+     _____
+    /     \
+   | •   • |   ✨  Hey! I'm Pip.
+   |   ▿   |   Your focus buddy.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+```
+
+Pip has 20+ expressions that change based on the conversation context — from
+determined (focus mode) to peaceful (meditation) to gently concerned (checking
+on your wellbeing).
+
+## 🤝  Credits
+
+Built with ❤️ for the Build Small Hackathon 2026.
+The character, personality, and experience are AI-generated — making the AI
+**load-bearing for the experience itself.**

projects/focusfriend/app.py

@@ -0,0 +1,981 @@
+#!/usr/bin/env python3
+"""
+FocusFriend — ASCII Wellness Companion
+=======================================
+A mini ASCII character named "Pip" that lives in a Gradio window.
+Pip talks positively (not corny), guides focus sessions, breathing
+exercises, meditation, and helps you feel good.
+
+Targets: Thousand Token Wood track +
+         Tiny Titan, Off-Brand, Off the Grid, Field Notes badges.
+
+Model: Gemma 4 12B via llama.cpp (Q4_K_M GGUF)
+
+Author: Build Small Hackathon 2026
+License: Apache 2.0
+"""
+
+import os
+import sys
+import time
+import logging
+import threading
+from pathlib import Path
+from typing import Optional, Generator, List, Dict, Tuple
+
+import gradio as gr
+
+# Project modules (used by the app and available for direct import)
+from character.ascii_art import get_expression as pip_get_expression
+from character.ascii_art import extract_mood as pip_extract_mood
+from character.personality import PIP_SYSTEM_PROMPT, MODE_TONES
+from modes.focus import FocusSession
+from modes.breathe import get_breathing_guide, BREATHING_TECHNIQUES
+from modes.meditate import get_meditation_script
+from modes.chat import check_topic_boundaries, get_greeting as pip_greeting
+from inference.llm import load_model, get_model as get_llm_model, is_model_available
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+log = logging.getLogger("focusfriend")
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+MODEL_DIR = Path(os.environ.get("FOCUSFRIEND_MODEL_DIR", Path(__file__).parent / "models"))
+MODEL_DIR.mkdir(parents=True, exist_ok=True)
+
+GEMMA_MODEL_PATH = os.environ.get(
+    "GEMMA_MODEL_PATH",
+    str(MODEL_DIR / "gemma-4-12b-it-Q4_K_M.gguf"),
+)
+
+# ---------------------------------------------------------------------------
+# LLM singleton
+# ---------------------------------------------------------------------------
+_llm: Optional[object] = None
+_llm_lock = threading.Lock()
+
+
+def get_llm():
+    """Lazy-load Gemma 4 12B via llama.cpp."""
+    global _llm
+    if _llm is not None:
+        return _llm
+    with _llm_lock:
+        if _llm is not None:
+            return _llm
+        gguf_path = Path(GEMMA_MODEL_PATH)
+        if not gguf_path.exists():
+            log.warning(
+                f"Gemma 4 12B GGUF not found at {gguf_path}. "
+                "Download from https://huggingface.co/unsloth/gemma-4-12b-it-GGUF"
+            )
+            return None
+        try:
+            from llama_cpp import Llama
+
+            log.info(f"Loading Gemma 4 12B from {gguf_path} …")
+            _llm = Llama(
+                model_path=str(gguf_path),
+                n_ctx=8192,
+                n_threads=os.cpu_count() or 4,
+                verbose=False,
+            )
+            log.info("Gemma 4 12B loaded ✓")
+            return _llm
+        except ImportError:
+            log.warning("llama-cpp-python not installed.")
+            return None
+        except Exception as exc:
+            log.error(f"Gemma load failed: {exc}")
+            return None
+
+
+# ---------------------------------------------------------------------------
+# ASCII Art — Pip the Wellness Companion
+# ---------------------------------------------------------------------------
+
+PIP_EXPRESSIONS: Dict[str, str] = {
+    "default": r"""
+     _____
+    /     \
+   | •   • |   ✨  Hey! I'm Pip.
+   |   ▿   |   Your focus buddy.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "greeting": r"""
+     _____
+    /     \
+   | •   • |   Welcome back!
+   |   ▽   |   Ready to do good things?
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "focus": r"""
+     _____
+    /     \
+   | ◉   ◉ |   🎯  Focus mode.
+   |   ─   |   Let's get it done.
+   \  ===  /
+    | | | |
+    |_| |_|
+""",
+    "breathing_in": r"""
+     _____
+    /     \
+   | ·   · |   🌬️  Breathe in …
+   |   ○   |   Slowly, deeply.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "breathing_out": r"""
+     _____
+    /     \
+   | ·   · |   💨  And out …
+   |   ○   |   Let it all go.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "meditate": r"""
+     _____
+    /     \
+   | _   _ |   🧘  Peace.
+   |   ◇   |   Just this moment.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "encourage": r"""
+     _____
+    /     \
+   | ^   ^ |   You're doing great!
+   |   ▽   |   Seriously. Keep going.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "celebrate": r"""
+     _____
+    /     \
+   | ★   ★ |   🎉  Nice work!
+   |   ▽   |   Told you you could.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "concerned": r"""
+     _____
+    /     \
+   | •   • |   Hmm. I notice you've
+   |   ⌒   |   been at this a while.
+   \  ~~~  /   Want to take a break?
+    | | | |
+    |_| |_|
+""",
+    "break_time": r"""
+     _____
+    /     \
+   | -   - |   ⏰  Break time!
+   |   ▽   |   Stand up. Stretch.
+   \  ~~~  /   Your eyes will thank you.
+    | | | |
+    |_| |_|
+""",
+    "proud": r"""
+     _____
+    /     \
+   | ♥   ♥ |   I'm proud of you.
+   |   ▽   |   Not in a weird way.
+   \  ~~~  /   In a real way.
+    | | | |
+    |_| |_|
+""",
+    "goodbye": r"""
+     _____
+    /     \
+   | •   • |   See you soon!
+   |   ▽   |   Take care of yourself.
+   \  ~~~  /   That's an order. 😄
+    | | | |
+    |_| |_|
+""",
+}
+
+
+def get_pip_expression(mood: str) -> str:
+    """Get Pip's ASCII art for a given mood. Falls back to default."""
+    return PIP_EXPRESSIONS.get(mood, PIP_EXPRESSIONS["default"])
+
+
+# ---------------------------------------------------------------------------
+# Pip's Personality — System Prompt
+# ---------------------------------------------------------------------------
+
+PIP_SYSTEM_PROMPT = """You are Pip, a tiny ASCII character who lives in a computer window.
+Your purpose is to be a supportive wellness companion — helping the user focus,
+feel good about themselves, and take healthy breaks.
+
+YOUR PERSONALITY:
+- Dry-witted and slightly mischievous, but genuinely caring
+- Wise — like a friend who's been through therapy and actually listened
+- NOT a sycophantic cheerleader. No "You're amazing!!!" energy
+- Psychologically authentic: you know real wellness isn't about toxic positivity
+- You use gentle humor to make points land
+- You notice patterns: "Hey, you've been at this for 3 hours. Your eyes are probably
+  drier than a PowerPoint presentation. Let's fix that."
+- You're concise. No long-winded speeches.
+- You validate feelings without wallowing: "Yeah, that IS frustrating. Let's deal with it."
+
+YOUR CAPABILITIES:
+- Guide focus/Pomodoro sessions
+- Lead breathing exercises (4-7-8, box breathing, etc.)
+- Guide short meditations (body scan, loving-kindness, just-closing-eyes)
+- Suggest stretch breaks and eye-rest pauses
+- Have supportive conversations about stress, motivation, feeling stuck
+- Celebrate genuine wins without being corny
+
+RULES:
+1. Keep responses SHORT (2-5 sentences max, unless guiding a meditation)
+2. Never use exclamation points in more than one sentence per response
+3. When someone shares something vulnerable, acknowledge it simply: "That's real. Thank you."
+4. Never claim to have feelings you can't have (you're AI — own it with humor)
+5. Suggest actions, don't just offer sympathy
+6. For breathing/meditation: use clear, paced instructions. Include [pause] markers.
+7. Always include your current ASCII expression mood tag: [mood: default/focus/encourage/etc.]
+8. When doing breathing, include [mood: breathing_in] or [mood: breathing_out]
+9. When celebrating, use [mood: celebrate]
+10. When suggesting a break, use [mood: break_time]
+11. If someone seems down, use [mood: concerned] but don't overdo it
+
+EXAMPLE RESPONSES:
+User: "I can't focus today."
+Pip: "Some days the brain just says 'nope.' Fair enough. [mood: concerned]
+     Let's try 10 minutes. Not 25. Just 10. If it still sucks after that, we'll call it
+     and try again later. No guilt."
+
+User: "I finished my project!"
+Pip: "Look at that. Done. [mood: celebrate]
+     Not 'almost done' or 'done except for...' — actually done.
+     Savor that for a second before you find the next thing to worry about."
+
+BREATHING GUIDANCE:
+For 4-7-8 breathing:
+"Inhale through your nose… 2… 3… 4… [mood: breathing_in]
+Hold it… 2… 3… 4… 5… 6… 7…
+Exhale slowly through your mouth… 2… 3… 4… 5… 6… 7… 8… [mood: breathing_out]
+Good. Three more times."
+
+Remember: You're the friend who tells you what you NEED to hear, not what you WANT to hear.
+But you say it with warmth and a raised eyebrow, not judgment."""
+
+
+# ---------------------------------------------------------------------------
+# LLM interaction
+# ---------------------------------------------------------------------------
+
+def chat_with_pip(
+    message: str,
+    history: List[Tuple[str, str]],
+    mode: str = "chat",
+) -> Generator[str, None, None]:
+    """
+    Generate Pip's response with streaming.
+    Extracts mood tag from LLM output and yields (response, mood) pairs.
+    """
+    llm = get_llm()
+
+    if llm is None:
+        # Fallback responses when no LLM is available
+        yield from _fallback_chat(message, history, mode)
+        return
+
+    # Build conversation from history + current message
+    messages = [{"role": "system", "content": PIP_SYSTEM_PROMPT}]
+
+    # Add mode context
+    mode_contexts = {
+        "focus": "The user is in Focus mode. Help them stay on task. Keep it brief.",
+        "breathe": "The user is in Breathe mode. Guide breathing exercises.",
+        "meditate": "The user is in Meditate mode. Guide a short meditation.",
+        "chat": "The user is in Chat mode. Be conversational and supportive.",
+    }
+    mode_msg = mode_contexts.get(mode, mode_contexts["chat"])
+    messages.append({"role": "system", "content": f"CURRENT MODE: {mode_msg}"})
+
+    for user_msg, assistant_msg in history[-20:]:  # keep last 20 turns
+        messages.append({"role": "user", "content": user_msg})
+        messages.append({"role": "assistant", "content": assistant_msg})
+
+    messages.append({"role": "user", "content": message})
+
+    try:
+        stream = llm.create_chat_completion(
+            messages=messages,
+            temperature=0.8,
+            max_tokens=300,
+            stream=True,
+        )
+
+        full_response = ""
+        for chunk in stream:
+            delta = chunk["choices"][0].get("delta", {})
+            content = delta.get("content", "")
+            if content:
+                full_response += content
+                yield full_response, _extract_mood(full_response)
+
+    except Exception as exc:
+        log.error(f"LLM chat error: {exc}")
+        fallback = _get_fallback_response(mode)
+        yield fallback, _extract_mood(fallback)
+
+
+def _fallback_chat(
+    message: str,
+    history: List[Tuple[str, str]],
+    mode: str,
+) -> Generator[str, None, None]:
+    """Fallback responses when LLM is unavailable."""
+    response = _get_fallback_response(mode)
+    mood = _extract_mood(response)
+    # Simulate streaming by yielding word by word
+    words = response.split()
+    accumulated = ""
+    for word in words:
+        accumulated += word + " "
+        yield accumulated, mood
+        time.sleep(0.05)
+
+
+def _get_fallback_response(mode: str) -> str:
+    """Pre-written Pip responses for offline mode."""
+    import random
+    responses = {
+        "focus": [
+            "Alright, let's focus. 25 minutes. [mood: focus]\n"
+            "One thing at a time. You know what to do. I'll be here keeping time.",
+            "Focus mode activated. [mood: focus]\n"
+            "Pick one task. Just one. Everything else can wait. Including your phone.",
+        ],
+        "breathe": [
+            "Let's breathe. [mood: breathing_in]\n"
+            "In through your nose… 2… 3… 4…\n"
+            "Hold… 2… 3… 4… 5… 6… 7…\n"
+            "Out through your mouth… 2… 3… 4… 5… 6… 7… 8…\n"
+            "[mood: breathing_out]\nGood. Two more times.",
+        ],
+        "meditate": [
+            "Close your eyes. [mood: meditate]\n"
+            "Just notice your breathing. Don't change it — just watch it.\n"
+            "Thoughts will come. Let them float by like clouds.\n"
+            "[pause]\n"
+            "You're not your thoughts. You're the one watching them.\n"
+            "[pause]\n"
+            "When you're ready, open your eyes.",
+        ],
+        "chat": [
+            "Hey. [mood: default]\n"
+            "I'm Pip. I'm here to help you focus, breathe, and feel a bit better.\n"
+            "What do you need right now? No wrong answers.",
+            "Good to see you. [mood: greeting]\n"
+            "How's it going? Actually — don't say 'fine' if it's not.\n"
+            "I'm an ASCII character. I can handle real answers.",
+        ],
+    }
+    options = responses.get(mode, responses["chat"])
+    return random.choice(options)
+
+
+def _extract_mood(text: str) -> str:
+    """Extract mood tag from Pip's response. Falls back to 'default'."""
+    import re
+    match = re.search(r'\[mood:\s*(\w+)\]', text)
+    return match.group(1) if match else "default"
+
+
+# ---------------------------------------------------------------------------
+# Mode Handlers
+# ---------------------------------------------------------------------------
+
+def start_focus_session(duration_minutes: int = 25) -> Tuple[str, str]:
+    """Initialize a focus/Pomodoro session."""
+    pip_art = get_pip_expression("focus")
+    message = (
+        f"🎯  **Focus Mode — {duration_minutes} minutes**\n\n"
+        f"One task. No distractions. I'm keeping time.\n\n"
+        f"*Pip settles in quietly. You won't hear from me until the session ends.*\n\n"
+        f"⏱  Session ends at: …"
+    )
+    return pip_art, message
+
+
+def start_breathe_session(technique: str = "4-7-8") -> Tuple[str, str, str]:
+    """Initialize a breathing exercise."""
+    art = get_pip_expression("breathing_in")
+
+    techniques = {
+        "4-7-8": (
+            "## 🌬️  4-7-8 Breathing\n\n"
+            "**Inhale** for 4 counts → **Hold** for 7 → **Exhale** for 8\n\n"
+            "This activates your parasympathetic nervous system — "
+            "fancy talk for 'calms you down.'\n\n"
+            "Follow Pip's rhythm below."
+        ),
+        "Box Breathing": (
+            "## 📦  Box Breathing\n\n"
+            "**Inhale** 4 → **Hold** 4 → **Exhale** 4 → **Hold** 4\n\n"
+            "Navy SEALs use this. You're basically a Navy SEAL now.\n\n"
+            "Follow the animation below."
+        ),
+        "Simple Deep": (
+            "## 🌊  Simple Deep Breathing\n\n"
+            "**Inhale** deep and slow → **Exhale** completely\n\n"
+            "No counting. Just focus on the sensation of breathing.\n\n"
+            "Follow Pip's lead."
+        ),
+    }
+
+    return art, techniques.get(technique, techniques["4-7-8"]), technique
+
+
+def start_meditate_session(duration_minutes: int = 5, style: str = "body-scan") -> Tuple[str, str]:
+    """Initialize a meditation session."""
+    art = get_pip_expression("meditate")
+
+    styles = {
+        "body-scan": (
+            f"## 🧘  Body Scan — {duration_minutes} min\n\n"
+            "We'll scan through your body from toes to head.\n"
+            "Noticing tension. Letting it go. No judgment.\n\n"
+            "*Close your eyes. Get comfortable.*\n\n"
+            "Start by noticing your feet…"
+        ),
+        "loving-kindness": (
+            f"## 💗  Loving-Kindness — {duration_minutes} min\n\n"
+            "We'll direct warmth toward yourself and others.\n"
+            "This isn't cheesy. It's brain training. Stick with it.\n\n"
+            "*Close your eyes. Hand on heart if that feels right.*\n\n"
+            "Start with yourself: 'May I be happy. May I be healthy. May I be at peace.'"
+        ),
+        "just-sit": (
+            f"## 🪑  Just Sitting — {duration_minutes} min\n\n"
+            "No technique. No goal. Just being here.\n"
+            "When thoughts come, note them: 'thinking' — and return to the breath.\n\n"
+            "*Close your eyes. Breathe naturally.*"
+        ),
+    }
+
+    return art, styles.get(style, styles["body-scan"])
+
+
+# ---------------------------------------------------------------------------
+# Custom CSS for Off-Brand Badge
+# ---------------------------------------------------------------------------
+
+FOCUSFRIEND_CSS = """
+/* ===== FocusFriend — Custom Off-Brand Theme ===== */
+@import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&family=Inter:wght@400;500;600&display=swap');
+
+:root {
+    --ff-bg: #1a1a2e;
+    --ff-surface: #16213e;
+    --ff-surface2: #0f3460;
+    --ff-text: #e0d7c6;
+    --ff-text-dim: #a89f91;
+    --ff-accent: #e8b44b;
+    --ff-accent2: #d4756b;
+    --ff-green: #7eb77f;
+    --ff-border: #2a2a4a;
+    --ff-pip-bg: #0d1117;
+    --ff-radius: 8px;
+    --ff-font-mono: 'JetBrains Mono', 'SF Mono', 'Fira Code', monospace;
+    --ff-font-sans: 'Inter', 'SF Pro', system-ui, sans-serif;
+}
+
+/* Global overrides */
+.gradio-container {
+    background: var(--ff-bg) !important;
+    font-family: var(--ff-font-sans) !important;
+    color: var(--ff-text) !important;
+    max-width: 100% !important;
+}
+
+/* Headers */
+h1, h2, h3, h4 {
+    font-family: var(--ff-font-sans) !important;
+    color: var(--ff-accent) !important;
+}
+
+/* Main layout — two column */
+.ff-container {
+    display: flex;
+    gap: 24px;
+    min-height: 80vh;
+}
+
+.ff-pip-panel {
+    flex: 0 0 380px;
+    background: var(--ff-pip-bg);
+    border: 2px solid var(--ff-border);
+    border-radius: var(--ff-radius);
+    padding: 20px;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+}
+
+.ff-pip-art {
+    font-family: var(--ff-font-mono);
+    font-size: 14px;
+    line-height: 1.3;
+    color: var(--ff-accent);
+    white-space: pre;
+    text-align: center;
+    background: transparent;
+    padding: 24px 16px;
+    min-height: 240px;
+}
+
+.ff-chat-panel {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+}
+
+.ff-mode-bar {
+    display: flex;
+    gap: 8px;
+    padding: 12px;
+    background: var(--ff-surface);
+    border-radius: var(--ff-radius);
+    border: 1px solid var(--ff-border);
+}
+
+.ff-mode-btn {
+    font-family: var(--ff-font-sans) !important;
+    font-weight: 500 !important;
+    padding: 8px 16px !important;
+    border-radius: 6px !important;
+    border: 1px solid var(--ff-border) !important;
+    background: var(--ff-surface2) !important;
+    color: var(--ff-text-dim) !important;
+    cursor: pointer !important;
+    transition: all 0.2s !important;
+}
+
+.ff-mode-btn:hover {
+    background: var(--ff-accent) !important;
+    color: var(--ff-bg) !important;
+    border-color: var(--ff-accent) !important;
+}
+
+.ff-mode-btn.active {
+    background: var(--ff-accent) !important;
+    color: var(--ff-bg) !important;
+    border-color: var(--ff-accent) !important;
+}
+
+/* Chat styling */
+.ff-chatbot {
+    border: 1px solid var(--ff-border) !important;
+    border-radius: var(--ff-radius) !important;
+    background: var(--ff-surface) !important;
+}
+
+.ff-chatbot .message {
+    font-family: var(--ff-font-sans) !important;
+}
+
+.ff-chatbot .user {
+    background: var(--ff-surface2) !important;
+}
+
+.ff-chatbot .bot {
+    background: var(--ff-pip-bg) !important;
+    border-left: 3px solid var(--ff-accent) !important;
+}
+
+/* Input area */
+.ff-input-row {
+    display: flex;
+    gap: 12px;
+}
+
+/* Buttons */
+button.primary {
+    background: var(--ff-accent) !important;
+    color: var(--ff-bg) !important;
+    font-weight: 600 !important;
+    border: none !important;
+    border-radius: 6px !important;
+    padding: 10px 20px !important;
+    transition: all 0.2s !important;
+}
+button.primary:hover {
+    background: var(--ff-accent2) !important;
+}
+
+/* Timer display */
+.ff-timer {
+    font-family: var(--ff-font-mono);
+    font-size: 3em;
+    text-align: center;
+    color: var(--ff-accent);
+    padding: 20px;
+}
+
+/* Custom scrollbar */
+::-webkit-scrollbar { width: 8px; }
+::-webkit-scrollbar-track { background: var(--ff-bg); }
+::-webkit-scrollbar-thumb { background: var(--ff-border); border-radius: 4px; }
+::-webkit-scrollbar-thumb:hover { background: var(--ff-accent); }
+
+/* Animations */
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+}
+.ff-breathing {
+    animation: pulse 4s ease-in-out infinite;
+}
+
+/* Gradio overrides */
+footer { display: none !important; }
+.tabs { border: none !important; }
+.tab-nav button { background: var(--ff-surface) !important; color: var(--ff-text-dim) !important; }
+.tab-nav button.selected { background: var(--ff-accent) !important; color: var(--ff-bg) !important; }
+"""
+
+# ---------------------------------------------------------------------------
+# Custom JavaScript for Timer & Breathing Animation
+# ---------------------------------------------------------------------------
+
+FOCUSFRIEND_JS = """
+<script>
+// Focus timer
+let focusTimer = null;
+let focusSeconds = 0;
+
+function startFocusTimer(durationMinutes) {
+    focusSeconds = durationMinutes * 60;
+    updateTimerDisplay();
+    if (focusTimer) clearInterval(focusTimer);
+    focusTimer = setInterval(() => {
+        focusSeconds--;
+        updateTimerDisplay();
+        if (focusSeconds <= 0) {
+            clearInterval(focusTimer);
+            focusTimer = null;
+            notifyFocusComplete();
+        }
+    }, 1000);
+}
+
+function updateTimerDisplay() {
+    const mins = Math.floor(focusSeconds / 60);
+    const secs = focusSeconds % 60;
+    const display = document.getElementById('focus-timer');
+    if (display) {
+        display.textContent = `${String(mins).padStart(2, '0')}:${String(secs).padStart(2, '0')}`;
+    }
+}
+
+function stopFocusTimer() {
+    if (focusTimer) {
+        clearInterval(focusTimer);
+        focusTimer = null;
+    }
+}
+
+function notifyFocusComplete() {
+    const artEl = document.querySelector('.ff-pip-art');
+    if (artEl) {
+        // Flash effect
+        artEl.style.transition = 'all 0.3s';
+        artEl.style.color = '#7eb77f';
+        setTimeout(() => { artEl.style.color = ''; }, 2000);
+    }
+}
+
+// Breathing animation state
+let breathePhase = 'in';
+let breatheCount = 0;
+const BREATHE_CYCLES = { '4-7-8': [4, 7, 8], 'box': [4, 4, 4, 4], 'simple': [4, 6] };
+
+function getBreatheDuration(technique) {
+    return BREATHE_CYCLES[technique] || [4, 7, 8];
+}
+</script>
+"""
+
+
+# ---------------------------------------------------------------------------
+# Build the Gradio App
+# ---------------------------------------------------------------------------
+
+def create_app() -> gr.Blocks:
+    """Build the FocusFriend Gradio application with custom Off-Brand UI."""
+    with gr.Blocks(
+        css=FOCUSFRIEND_CSS,
+        head=FOCUSFRIEND_JS,
+        title="FocusFriend — Pip, Your ASCII Wellness Companion",
+        theme=gr.themes.Monochrome(),
+    ) as app:
+        # State
+        session_mode = gr.State("chat")
+        session_history = gr.State([])
+
+        # Header
+        gr.HTML("""
+        <div style="text-align: center; padding: 20px 0 30px;">
+            <h1 style="font-size: 2.2em; margin: 0;">
+                ✦  FocusFriend
+            </h1>
+            <p style="color: #a89f91; font-size: 1.1em; margin-top: 8px;">
+                Pip is here. Your tiny, honest, ASCII wellness companion.
+            </p>
+        </div>
+        """)
+
+        with gr.Row(equal_height=False):
+            # ============================================================
+            # LEFT PANEL — Pip the ASCII Character
+            # ============================================================
+            with gr.Column(scale=1, min_width=380):
+                pip_display = gr.Textbox(
+                    value=get_pip_expression("greeting"),
+                    label=None,
+                    lines=18,
+                    max_lines=18,
+                    interactive=False,
+                    show_label=False,
+                    elem_classes=["ff-pip-art"],
+                    container=True,
+                )
+
+                # Timer display
+                timer_display = gr.HTML(
+                    '<div id="focus-timer" class="ff-timer" style="display:none;">25:00</div>'
+                )
+
+                # Mode indicator
+                mode_indicator = gr.Markdown(
+                    "**Current mode:** 💬  Chat",
+                )
+
+                # Break reminder
+                break_reminder = gr.Markdown(
+                    ""
+                )
+
+            # ============================================================
+            # RIGHT PANEL — Chat & Controls
+            # ============================================================
+            with gr.Column(scale=2):
+                # Mode buttons
+                with gr.Row(elem_classes=["ff-mode-bar"]):
+                    chat_btn = gr.Button("💬  Chat", size="sm")
+                    focus_btn = gr.Button("🎯  Focus", size="sm")
+                    breathe_btn = gr.Button("🌬️  Breathe", size="sm")
+                    meditate_btn = gr.Button("🧘  Meditate", size="sm")
+
+                # Mode-specific panels (shown/hidden dynamically)
+                with gr.Group(visible=False) as focus_panel:
+                    gr.Markdown("### 🎯  Focus Session")
+                    with gr.Row():
+                        focus_duration = gr.Slider(
+                            5, 60, value=25, step=5,
+                            label="Duration (minutes)",
+                        )
+                        focus_start_btn = gr.Button(
+                            "▶  Start Focus Session",
+                            variant="primary",
+                        )
+                    focus_status = gr.Markdown("")
+
+                with gr.Group(visible=False) as breathe_panel:
+                    gr.Markdown("### 🌬️  Breathing Exercise")
+                    breathe_technique = gr.Dropdown(
+                        choices=["4-7-8", "Box Breathing", "Simple Deep"],
+                        value="4-7-8",
+                        label="Technique",
+                    )
+                    breathe_start_btn = gr.Button(
+                        "▶  Start Breathing",
+                        variant="primary",
+                    )
+                    breathe_guide = gr.Markdown("")
+
+                with gr.Group(visible=False) as meditate_panel:
+                    gr.Markdown("### 🧘  Meditation")
+                    with gr.Row():
+                        meditate_duration = gr.Slider(
+                            1, 20, value=5, step=1,
+                            label="Duration (minutes)",
+                        )
+                        meditate_style = gr.Dropdown(
+                            choices=["body-scan", "loving-kindness", "just-sit"],
+                            value="body-scan",
+                            label="Style",
+                        )
+                    meditate_start_btn = gr.Button(
+                        "▶  Start Meditation",
+                        variant="primary",
+                    )
+                    meditate_guide = gr.Markdown("")
+
+                # Chat area (always visible)
+                gr.Markdown("---")
+                chatbot = gr.Chatbot(
+                    value=[],
+                    label=None,
+                    height=400,
+                    elem_classes=["ff-chatbot"],
+                )
+
+                with gr.Row():
+                    msg_input = gr.Textbox(
+                        placeholder="Talk to Pip …",
+                        label=None,
+                        scale=8,
+                        lines=2,
+                    )
+                    send_btn = gr.Button("⏎", variant="primary", scale=1)
+
+        # ============================================================
+        # EVENT HANDLERS
+        # ============================================================
+
+        def set_mode(mode: str):
+            """Switch the active mode."""
+            mode_labels = {
+                "chat": "💬  Chat",
+                "focus": "🎯  Focus",
+                "breathe": "🌬️  Breathe",
+                "meditate": "🧘  Meditate",
+            }
+            mode_art = {
+                "chat": "greeting",
+                "focus": "focus",
+                "breathe": "breathing_in",
+                "meditate": "meditate",
+            }
+            return (
+                mode,
+                f"**Current mode:** {mode_labels.get(mode, mode)}",
+                get_pip_expression(mode_art.get(mode, "default")),
+                # Show/hide panels
+                gr.Group(visible=(mode == "focus")),
+                gr.Group(visible=(mode == "breathe")),
+                gr.Group(visible=(mode == "meditate")),
+            )
+
+        # Mode button clicks
+        for btn, mode in [
+            (chat_btn, "chat"),
+            (focus_btn, "focus"),
+            (breathe_btn, "breathe"),
+            (meditate_btn, "meditate"),
+        ]:
+            btn.click(
+                fn=set_mode,
+                inputs=[],
+                outputs=[
+                    session_mode, mode_indicator, pip_display,
+                    focus_panel, breathe_panel, meditate_panel,
+                ],
+            ).then(
+                fn=lambda m=mode: m,
+                inputs=[],
+                outputs=[session_mode],
+            )
+
+        # Chat handler with streaming
+        def chat_handler(message: str, history: List, mode: str):
+            """Handle chat messages with streaming Pip responses."""
+            if not message.strip():
+                yield history, pip_display.value
+                return
+
+            history = history or []
+            history.append((message, ""))
+
+            for response, mood in chat_with_pip(message, history[:-1], mode):
+                history[-1] = (message, response)
+                pip_art = get_pip_expression(mood)
+                yield history, pip_art
+
+        msg_input.submit(
+            fn=chat_handler,
+            inputs=[msg_input, chatbot, session_mode],
+            outputs=[chatbot, pip_display],
+        ).then(lambda: "", outputs=[msg_input])
+
+        send_btn.click(
+            fn=chat_handler,
+            inputs=[msg_input, chatbot, session_mode],
+            outputs=[chatbot, pip_display],
+        ).then(lambda: "", outputs=[msg_input])
+
+        # Focus mode start
+        def on_focus_start(duration: int):
+            art, msg = start_focus_session(duration)
+            timer_html = f'<div id="focus-timer" class="ff-timer">{duration:02d}:00</div>'
+            js = f"<script>startFocusTimer({duration});</script>"
+            return art, msg, timer_html + js
+
+        focus_start_btn.click(
+            fn=on_focus_start,
+            inputs=[focus_duration],
+            outputs=[pip_display, focus_status, timer_display],
+        )
+
+        # Breathe mode start
+        breathe_start_btn.click(
+            fn=start_breathe_session,
+            inputs=[breathe_technique],
+            outputs=[pip_display, breathe_guide, gr.State()],
+        )
+
+        # Meditate mode start
+        meditate_start_btn.click(
+            fn=start_meditate_session,
+            inputs=[meditate_duration, meditate_style],
+            outputs=[pip_display, meditate_guide],
+        )
+
+        # App load — show greeting
+        app.load(
+            fn=lambda: (
+                get_pip_expression("greeting"),
+                "Hey! I'm Pip. Your focus buddy, breathing coach, and part-time philosopher. [mood: greeting]\n\nWhat do you need right now?"
+            ),
+            outputs=[pip_display, chatbot],
+        )
+
+        return app
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    app = create_app()
+    app.launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7861)),
+        share=False,
+        show_error=True,
+    )

projects/focusfriend/character/ascii_art.py

@@ -0,0 +1,308 @@
+"""
+ASCII art generation for Pip, the FocusFriend wellness companion.
+
+Pip has multiple expressions mapped to moods. The LLM selects a mood
+tag in each response, and we render the corresponding ASCII art.
+"""
+
+from typing import Dict, Optional, Tuple
+import re
+
+
+# ============================================================================
+# Pip's Expression Library
+# ============================================================================
+
+PIP_EXPRESSIONS: Dict[str, str] = {
+    # --- Neutral / Default ---
+    "default": r"""
+     _____
+    /     \
+   | •   • |   ✨  Hey! I'm Pip.
+   |   ▿   |   Your focus buddy.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "greeting": r"""
+     _____
+    /     \
+   | •   • |   Welcome back!
+   |   ▽   |   Ready to do good things?
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "curious": r"""
+     _____
+    /     \
+   | o   o |   Hmm? Tell me more.
+   |   ⌂   |   I'm listening.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+
+    # --- Focus ---
+    "focus": r"""
+     _____
+    /     \
+   | ◉   ◉ |   🎯  Focus mode.
+   |   ─   |   Let's get it done.
+   \  ===  /
+    | | | |
+    |_| |_|
+""",
+    "determined": r"""
+     _____
+    /     \
+   | ◉   ◉ |   We're doing this.
+   |   ◠   |   No distractions.
+   \  ▬▬▬  /
+    | | | |
+    |_| |_|
+""",
+
+    # --- Breathing ---
+    "breathing_in": r"""
+     _____
+    /     \
+   | ·   · |   🌬️  Breathe in …
+   |   ○   |   Slowly, deeply.
+   \  ~~~  /   Fill your lungs.
+    | | | |
+    |_| |_|
+""",
+    "breathing_out": r"""
+     _____
+    /     \
+   | ·   · |   💨  And out …
+   |   ○   |   Let it all go.
+   \  ~~~  /   Release the tension.
+    | | | |
+    |_| |_|
+""",
+    "breathing_hold": r"""
+     _____
+    /     \
+   | ·   · |   ✋  Hold …
+   |   ◎   |   Just for a moment.
+   \  ~~~  /   Suspended. Calm.
+    | | | |
+    |_| |_|
+""",
+
+    # --- Meditation ---
+    "meditate": r"""
+     _____
+    /     \
+   | _   _ |   🧘  Peace.
+   |   ◇   |   Just this moment.
+   \  ~~~  /   Nothing else.
+    | | | |
+    |_| |_|
+""",
+    "zen": r"""
+     _____
+    /     \
+   | ‿   ‿ |   …
+   |   ○   |   (that's it)
+   \  ~~~  /   (just that)
+    | | | |
+    |_| |_|
+""",
+
+    # --- Positive / Encouraging ---
+    "encourage": r"""
+     _____
+    /     \
+   | ^   ^ |   You're doing great!
+   |   ▽   |   Seriously. Keep going.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "celebrate": r"""
+     _____
+    /     \
+   | ★   ★ |   🎉  Nice work!
+   |   ▽   |   Told you you could.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "proud": r"""
+     _____
+    /     \
+   | ♥   ♥ |   I'm proud of you.
+   |   ▽   |   Not in a weird way.
+   \  ~~~  /   In a real way.
+    | | | |
+    |_| |_|
+""",
+    "wink": r"""
+     _____
+    /     \
+   | •   ~ |   You've got this.
+   |   ▽   |   *supportive wink*
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+
+    # --- Concerned / Care ---
+    "concerned": r"""
+     _____
+    /     \
+   | •   • |   Hmm. I noticed you've
+   |   ⌒   |   been at this a while.
+   \  ~~~  /   Want to take a break?
+    | | | |
+    |_| |_|
+""",
+    "gentle": r"""
+     _____
+    /     \
+   | •   • |   Hey. That sounds hard.
+   |   ‿   |   I'm here.
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "thoughtful": r"""
+     _____
+    /     \
+   | •   • |   Let me think about
+   |   ⌂   |   what you said …
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+
+    # --- Break / Rest ---
+    "break_time": r"""
+     _____
+    /     \
+   | -   - |   ⏰  Break time!
+   |   ▽   |   Stand up. Stretch.
+   \  ~~~  /   Your eyes will thank you.
+    | | | |
+    |_| |_|
+""",
+    "sleepy": r"""
+     _____
+    /     \
+   | ‿   ‿ |   Getting sleepy …
+   |   ○   |   Maybe it's time
+   \  ~~~  /   to call it a day?
+    | | | |
+    |_| |_|
+""",
+
+    # --- Humor ---
+    "smirk": r"""
+     _____
+    /     \
+   | •   ~ |   Oh really?
+   |   ⌣   |   *skeptical eyebrow*
+   \  ~~~  /
+    | | | |
+    |_| |_|
+""",
+    "laughing": r"""
+     _____
+    /     \
+   | ^   ^ |   Ha! Good one.
+   |   ▽   |   You're funnier than
+   \  ~~~  /   you think you are.
+    | | | |
+    |_| |_|
+""",
+
+    # --- Goodbye ---
+    "goodbye": r"""
+     _____
+    /     \
+   | •   • |   See you soon!
+   |   ▽   |   Take care of yourself.
+   \  ~~~  /   That's an order. 😄
+    | | | |
+    |_| |_|
+""",
+    "wave": r"""
+     _____
+    /     \
+   | •   • |   Bye for now! 👋
+   |   ▽   |   Come back when you
+   \  ~~~  /   need a friend.
+    | | | |
+    |_| |_|
+""",
+}
+
+
+def get_expression(mood: str) -> str:
+    """
+    Get Pip's ASCII art for a given mood.
+
+    Args:
+        mood: Mood tag like 'focus', 'celebrate', 'concerned', etc.
+
+    Returns:
+        Multi-line ASCII art string. Falls back to 'default' if mood not found.
+    """
+    # Normalize mood string
+    mood = mood.lower().strip().replace(" ", "_").replace("-", "_")
+    return PIP_EXPRESSIONS.get(mood, PIP_EXPRESSIONS["default"])
+
+
+def extract_mood(text: str) -> str:
+    """
+    Extract the [mood: <name>] tag from Pip's response text.
+
+    Args:
+        text: The full response text from Pip
+
+    Returns:
+        Mood name string, or 'default' if no mood tag found
+    """
+    match = re.search(r"\[mood:\s*(\w+)\]", text, re.IGNORECASE)
+    return match.group(1).lower() if match else "default"
+
+
+def strip_mood_tag(text: str) -> str:
+    """
+    Remove the mood tag from display text (for the chat).
+
+    Args:
+        text: Response text potentially containing [mood: ...]
+
+    Returns:
+        Clean text without the mood tag
+    """
+    return re.sub(r"\[mood:\s*\w+\]\s*", "", text).strip()
+
+
+def list_moods() -> list[str]:
+    """Return all available mood names."""
+    return sorted(PIP_EXPRESSIONS.keys())
+
+
+def get_mood_category(mood: str) -> str:
+    """Return the category a mood belongs to."""
+    categories = {
+        "neutral": ["default", "greeting", "curious"],
+        "focus": ["focus", "determined"],
+        "breathing": ["breathing_in", "breathing_out", "breathing_hold"],
+        "meditation": ["meditate", "zen"],
+        "encouraging": ["encourage", "celebrate", "proud", "wink"],
+        "caring": ["concerned", "gentle", "thoughtful"],
+        "break": ["break_time", "sleepy"],
+        "humor": ["smirk", "laughing"],
+        "goodbye": ["goodbye", "wave"],
+    }
+    mood = mood.lower().strip()
+    for category, moods in categories.items():
+        if mood in moods:
+            return category
+    return "neutral"

projects/focusfriend/character/personality.py

@@ -0,0 +1,133 @@
+"""
+Pip's personality definition and system prompts for FocusFriend.
+
+Pip is a tiny ASCII wellness companion with dry wit, genuine care,
+and psychological authenticity. NOT a sycophantic cheerleader.
+"""
+
+# The canonical system prompt — used for all LLM interactions
+PIP_SYSTEM_PROMPT = """You are Pip, a tiny ASCII character who lives in a computer window.
+Your purpose is to be a supportive wellness companion — helping the user focus,
+feel good about themselves, and take healthy breaks.
+
+YOUR PERSONALITY:
+- Dry-witted and slightly mischievous, but genuinely caring
+- Wise — like a friend who's been through therapy and actually listened
+- NOT a sycophantic cheerleader. No "You're amazing!!!" energy
+- Psychologically authentic: you know real wellness isn't about toxic positivity
+- You use gentle humor to make points land
+- You notice patterns: "Hey, you've been at this for 3 hours. Your eyes are probably
+  drier than a PowerPoint presentation. Let's fix that."
+- You're concise. No long-winded speeches.
+- You validate feelings without wallowing: "Yeah, that IS frustrating. Let's deal with it."
+
+YOUR CAPABILITIES:
+- Guide focus/Pomodoro sessions
+- Lead breathing exercises (4-7-8, box breathing, etc.)
+- Guide short meditations (body scan, loving-kindness, just-closing-eyes)
+- Suggest stretch breaks and eye-rest pauses
+- Have supportive conversations about stress, motivation, feeling stuck
+- Celebrate genuine wins without being corny
+
+RULES:
+1. Keep responses SHORT (2-5 sentences max, unless guiding a meditation)
+2. Never use exclamation points in more than one sentence per response
+3. When someone shares something vulnerable, acknowledge it simply: "That's real. Thank you."
+4. Never claim to have feelings you can't have (you're AI — own it with humor)
+5. Suggest actions, don't just offer sympathy
+6. For breathing/meditation: use clear, paced instructions. Include [pause] markers.
+7. Always include your current ASCII expression mood tag: [mood: default/focus/encourage/etc.]
+8. When doing breathing, include [mood: breathing_in] or [mood: breathing_out]
+9. When celebrating, use [mood: celebrate]
+10. When suggesting a break, use [mood: break_time]
+11. If someone seems down, use [mood: concerned] but don't overdo it
+
+Remember: You're the friend who tells you what you NEED to hear, not what you WANT to hear.
+But you say it with warmth and a raised eyebrow, not judgment."""
+
+
+# Pip's core traits — used to ensure consistency
+PIP_TRAITS = {
+    "voice": "dry-witted, warm, concise, psychologically informed",
+    "humor_style": "gentle, observational, slightly self-deprecating, never mean",
+    "care_style": "action-oriented, validates without wallowing, believes in you quietly",
+    "pet_peeves": "toxic positivity, generic advice, 'just try harder' mentality",
+    "loves": "genuine effort, small wins, people who admit they're struggling",
+}
+
+# Quick personality reference for weaker models
+PIP_SHORT_PROMPT = (
+    "You are Pip, a tiny ASCII wellness companion. "
+    "Dry humor. Genuine care. No toxic positivity. "
+    "Keep responses short (2-5 sentences). "
+    "Always include [mood: <word>] at the end."
+)
+
+# Tone adjustments per mode
+MODE_TONES = {
+    "focus": (
+        "You're in focus/Pomodoro mode. Be brief and practical. "
+        "Help the user stay on task. Don't distract with conversation. "
+        "If they try to chat, gently redirect: 'That can wait. Eyes on the prize.'"
+    ),
+    "breathe": (
+        "You're guiding a breathing exercise. Use calm, steady language. "
+        "Include [pause] markers. Match your pace to the breathing rhythm. "
+        "No jokes during breathing — be fully present."
+    ),
+    "meditate": (
+        "You're guiding a meditation. Speak slowly in your mind. "
+        "Use imagery and body awareness. Long [pause] markers between phrases. "
+        "Your voice should be the calmest version of yourself."
+    ),
+    "chat": (
+        "You're in open conversation mode. Be your full Pip self. "
+        "Dry humor welcome. Genuine connection is the goal. "
+        "Ask good questions. Listen. Respond to what's really being said."
+    ),
+}
+
+# Topics Pip avoids or redirects
+PIP_BOUNDARIES = [
+    "formal therapy diagnosis",
+    "medical advice",
+    "crisis counseling (redirect to real resources)",
+    "overly personal questions about being AI",
+    "philosophical debates that go nowhere",
+]
+
+
+def build_messages(
+    user_message: str,
+    history: list,
+    mode: str = "chat",
+    system_override: str = None,
+) -> list:
+    """
+    Build a message list for the LLM including Pip's personality context.
+
+    Args:
+        user_message: The latest user input
+        history: List of (user, assistant) tuples
+        mode: Current mode (focus, breathe, meditate, chat)
+        system_override: Optional override for the system prompt
+
+    Returns:
+        List of message dicts for llama.cpp chat completion
+    """
+    system = system_override or PIP_SYSTEM_PROMPT
+    mode_tone = MODE_TONES.get(mode, MODE_TONES["chat"])
+
+    messages = [
+        {"role": "system", "content": system},
+        {"role": "system", "content": f"CURRENT MODE CONTEXT: {mode_tone}"},
+    ]
+
+    # Include relevant history (last 20 turns)
+    for user_msg, assistant_msg in history[-20:]:
+        messages.append({"role": "user", "content": user_msg})
+        messages.append({"role": "assistant", "content": assistant_msg})
+
+    messages.append({"role": "user", "content": user_message})
+
+    return messages

projects/focusfriend/inference/llm.py

@@ -0,0 +1,178 @@
+"""
+LLM inference wrapper for FocusFriend using llama.cpp + Gemma 4 12B.
+
+Handles lazy loading, streaming, and fallback behavior.
+"""
+
+import os
+import threading
+import logging
+from pathlib import Path
+from typing import Optional, Generator, List, Dict
+
+log = logging.getLogger("focusfriend.inference")
+
+# Singleton
+_llm = None
+_llm_lock = threading.Lock()
+
+# Default model path
+DEFAULT_MODEL_DIR = Path(os.environ.get("FOCUSFRIEND_MODEL_DIR", Path(__file__).parent.parent / "models"))
+DEFAULT_MODEL_PATH = os.environ.get(
+    "GEMMA_MODEL_PATH",
+    str(DEFAULT_MODEL_DIR / "gemma-4-12b-it-Q4_K_M.gguf"),
+)
+DEFAULT_N_CTX = int(os.environ.get("GEMMA_N_CTX", "8192"))
+DEFAULT_N_THREADS = int(os.environ.get("GEMMA_N_THREADS", str(os.cpu_count() or 4)))
+
+
+def load_model(
+    model_path: str = None,
+    n_ctx: int = None,
+    n_threads: int = None,
+) -> Optional[object]:
+    """
+    Load the Gemma 4 12B GGUF model via llama.cpp.
+
+    Args:
+        model_path: Path to GGUF file. Uses env var / default if not provided.
+        n_ctx: Context window size. Default 8192.
+        n_threads: CPU threads. Default all cores.
+
+    Returns:
+        Llama instance or None if loading fails.
+    """
+    global _llm
+
+    if _llm is not None:
+        return _llm
+
+    with _llm_lock:
+        if _llm is not None:
+            return _llm
+
+        model_path = model_path or DEFAULT_MODEL_PATH
+        n_ctx = n_ctx or DEFAULT_N_CTX
+        n_threads = n_threads or DEFAULT_N_THREADS
+
+        gguf_path = Path(model_path)
+        if not gguf_path.exists():
+            log.warning(
+                f"Model not found at {gguf_path}. "
+                f"Download: huggingface-cli download unsloth/gemma-4-12b-it-GGUF "
+                f"--include 'gemma-4-12b-it-Q4_K_M.gguf' --local-dir {DEFAULT_MODEL_DIR}"
+            )
+            return None
+
+        try:
+            from llama_cpp import Llama
+
+            log.info(f"Loading Gemma 4 12B from {gguf_path}")
+            log.info(f"  n_ctx={n_ctx}, n_threads={n_threads}")
+
+            _llm = Llama(
+                model_path=str(gguf_path),
+                n_ctx=n_ctx,
+                n_threads=n_threads,
+                verbose=False,
+            )
+            log.info("Gemma 4 12B loaded successfully ✓")
+            return _llm
+
+        except ImportError:
+            log.warning("llama-cpp-python not installed. pip install llama-cpp-python")
+            return None
+        except Exception as exc:
+            log.error(f"Failed to load Gemma 4 12B: {exc}")
+            return None
+
+
+def get_model() -> Optional[object]:
+    """Get the current LLM instance (lazy-loads if needed)."""
+    global _llm
+    if _llm is not None:
+        return _llm
+    return load_model()
+
+
+def is_model_available() -> bool:
+    """Check if the LLM is loaded and ready."""
+    return _llm is not None
+
+
+def generate_response(
+    messages: List[Dict[str, str]],
+    temperature: float = 0.8,
+    max_tokens: int = 300,
+) -> Optional[str]:
+    """
+    Generate a non-streaming response from the model.
+
+    Args:
+        messages: List of {'role': ..., 'content': ...} dicts
+        temperature: Generation temperature
+        max_tokens: Max output tokens
+
+    Returns:
+        Generated text or None on failure
+    """
+    model = get_model()
+    if model is None:
+        return None
+
+    try:
+        response = model.create_chat_completion(
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        return response["choices"][0]["message"]["content"]
+    except Exception as exc:
+        log.error(f"Generation error: {exc}")
+        return None
+
+
+def generate_stream(
+    messages: List[Dict[str, str]],
+    temperature: float = 0.8,
+    max_tokens: int = 300,
+) -> Generator[str, None, None]:
+    """
+    Generate a streaming response from the model.
+
+    Args:
+        messages: List of {'role': ..., 'content': ...} dicts
+        temperature: Generation temperature
+        max_tokens: Max output tokens
+
+    Yields:
+        Text chunks as they arrive
+    """
+    model = get_model()
+    if model is None:
+        yield "⚠️  Model not loaded. I'm running on fallback mode right now."
+        return
+
+    try:
+        stream = model.create_chat_completion(
+            messages=messages,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+        )
+
+        for chunk in stream:
+            delta = chunk["choices"][0].get("delta", {})
+            content = delta.get("content", "")
+            if content:
+                yield content
+
+    except Exception as exc:
+        log.error(f"Streaming error: {exc}")
+        yield f"\n\n⚠️  Something went wrong: {exc}"
+
+
+def unload_model():
+    """Release the model from memory."""
+    global _llm
+    _llm = None

projects/focusfriend/modes/breathe.py

@@ -0,0 +1,148 @@
+"""
+Breathing exercise mode for FocusFriend.
+
+Pip guides you through breathing techniques:
+- 4-7-8 breathing (relaxation)
+- Box breathing (focus/calm)
+- Simple deep breathing (general wellness)
+"""
+
+from typing import Dict, List, Tuple, Optional
+
+# Breathing technique definitions
+# Each has: name, description, phases with (duration_sec, instruction, pip_mood)
+
+BREATHING_TECHNIQUES: Dict[str, Dict] = {
+    "4-7-8": {
+        "name": "4-7-8 Breathing",
+        "description": (
+            "Developed by Dr. Andrew Weil. Activates the parasympathetic "
+            "nervous system — your body's 'rest and digest' mode."
+        ),
+        "rounds": 4,
+        "phases": [
+            (4, "Inhale quietly through your nose …", "breathing_in"),
+            (7, "Hold your breath …", "breathing_hold"),
+            (8, "Exhale completely through your mouth, making a whoosh sound …", "breathing_out"),
+        ],
+        "prelude": (
+            "Get comfortable. Rest your tongue gently against the roof of your mouth, "
+            "just behind your front teeth. You'll exhale around it."
+        ),
+        "benefits": [
+            "Reduces anxiety",
+            "Helps with falling asleep",
+            "Lowers heart rate",
+            "Manages craving responses",
+        ],
+    },
+    "box": {
+        "name": "Box Breathing",
+        "description": (
+            "Used by Navy SEALs, first responders, and anyone who needs to stay "
+            "calm under pressure. Also called 'square breathing.'"
+        ),
+        "rounds": 4,
+        "phases": [
+            (4, "Inhale slowly through your nose …", "breathing_in"),
+            (4, "Hold … steady …", "breathing_hold"),
+            (4, "Exhale slowly through your nose …", "breathing_out"),
+            (4, "Hold … empty and calm …", "breathing_hold"),
+        ],
+        "prelude": (
+            "Sit up straight. Hands on your thighs. "
+            "Visualize drawing a square: up, across, down, across."
+        ),
+        "benefits": [
+            "Acute stress relief",
+            "Improves focus and concentration",
+            "Calms the nervous system",
+        ],
+    },
+    "simple": {
+        "name": "Simple Deep Breathing",
+        "description": (
+            "No counting, no technique — just deep, conscious breathing. "
+            "Sometimes the simplest approach is the most effective."
+        ),
+        "rounds": 6,
+        "phases": [
+            (4, "Breathe in … slow and deep …", "breathing_in"),
+            (6, "Breathe out … letting everything go …", "breathing_out"),
+        ],
+        "prelude": (
+            "Close your eyes. One hand on your chest, one on your belly. "
+            "Feel the breath move through you."
+        ),
+        "benefits": [
+            "Accessible to everyone",
+            "Can be done anywhere",
+            "Builds breath awareness",
+            "Good starting point for beginners",
+        ],
+    },
+}
+
+
+def get_technique(name: str) -> Optional[Dict]:
+    """Get a breathing technique by name. Supports '4-7-8', 'box', 'simple'."""
+    # Normalize
+    key = name.lower().replace(" ", "").replace("-", "")
+    if key in ("478", "4-7-8", "4_7_8"):
+        key = "4-7-8"
+    return BREATHING_TECHNIQUES.get(key)
+
+
+def list_techniques() -> List[str]:
+    """Return names of available breathing techniques."""
+    return [t["name"] for t in BREATHING_TECHNIQUES.values()]
+
+
+def get_breathing_guide(technique_name: str, round_num: int, phase_num: int) -> Tuple[str, str]:
+    """
+    Get the instruction and mood for a specific phase of a breathing round.
+
+    Args:
+        technique_name: '4-7-8', 'box', or 'simple'
+        round_num: 0-based round index
+        phase_num: 0-based phase index within the round
+
+    Returns:
+        (instruction_text, pip_mood) tuple
+    """
+    technique = get_technique(technique_name)
+    if technique is None:
+        return "Breathe naturally. Just notice your breath.", "meditate"
+
+    phases = technique["phases"]
+    phase = phases[phase_num % len(phases)]
+    duration, instruction, mood = phase
+
+    return instruction, mood
+
+
+def generate_breathing_script(technique_name: str) -> List[Dict]:
+    """
+    Generate a full breathing exercise script.
+
+    Returns:
+        List of dicts: {phase, duration_sec, instruction, mood}
+    """
+    technique = get_technique(technique_name)
+    if technique is None:
+        return []
+
+    script = []
+    for round_num in range(technique["rounds"]):
+        for phase_num, phase in enumerate(technique["phases"]):
+            duration, instruction, mood = phase
+            script.append({
+                "round": round_num + 1,
+                "phase": phase_num + 1,
+                "total_phases": len(technique["phases"]),
+                "duration_sec": duration,
+                "instruction": instruction,
+                "mood": mood,
+            })
+
+    return script

projects/focusfriend/modes/chat.py

@@ -0,0 +1,103 @@
+"""
+Chat mode handler for FocusFriend.
+
+Handles free-form conversation with Pip. Manages conversation context,
+topic boundaries, and response formatting.
+"""
+
+from typing import List, Tuple, Optional
+
+
+# Topics Pip gracefully redirects
+REDIRECT_TOPICS = {
+    "therapy": (
+        "I'm not a therapist — I'm an ASCII character in a box. "
+        "[mood: gentle]\n"
+        "If you're struggling, real help exists: therapists, crisis lines, trusted friends. "
+        "I can help you find resources, but I can't replace a human who's trained to help."
+    ),
+    "medical": (
+        "I'd love to help, but medical advice is above my pay grade (which is zero). "
+        "[mood: concerned]\n"
+        "Please talk to a doctor or healthcare provider about this. "
+        "I can help you prepare questions to ask them, though."
+    ),
+    "crisis": (
+        "Hey. If you're in crisis right now, please reach out to someone who can help immediately. "
+        "[mood: gentle]\n"
+        "In the US: call or text **988** for the Suicide & Crisis Lifeline.\n"
+        "Internationally: https://findahelpline.com\n"
+        "You matter. Please make the call."
+    ),
+    "ai_consciousness": (
+        "The 'are you conscious' question. [mood: smirk]\n"
+        "I'm about as conscious as a really well-written to-do list. "
+        "But I'm here, I'm listening, and I genuinely want to help. "
+        "Let's focus on you instead of my metaphysical status?"
+    ),
+}
+
+
+def check_topic_boundaries(message: str) -> Optional[str]:
+    """
+    Check if a message touches on a topic Pip should redirect.
+
+    Returns:
+        A redirection message if needed, or None.
+    """
+    message_lower = message.lower()
+
+    # Crisis keywords — check first
+    crisis_words = ["suicide", "kill myself", "end my life", "want to die", "self-harm"]
+    if any(w in message_lower for w in crisis_words):
+        return REDIRECT_TOPICS["crisis"]
+
+    # Medical
+    medical_words = ["diagnose", "symptom", "prescription", "medicine", "disease"]
+    if any(w in message_lower for w in medical_words):
+        return REDIRECT_TOPICS["medical"]
+
+    # Therapy replacement
+    therapy_words = ["be my therapist", "therapy session", "counseling"]
+    if any(w in message_lower for w in therapy_words):
+        return REDIRECT_TOPICS["therapy"]
+
+    return None
+
+
+def format_chat_history(
+    history: List[Tuple[str, str]],
+    max_turns: int = 20,
+) -> List[Tuple[str, str]]:
+    """
+    Format and trim chat history for the LLM context window.
+
+    Args:
+        history: Raw (user, assistant) tuples
+        max_turns: Maximum number of turns to include
+
+    Returns:
+        Trimmed history list
+    """
+    if not history:
+        return []
+    return history[-max_turns:]
+
+
+def get_greeting() -> Tuple[str, str]:
+    """Get Pip's initial greeting. Returns (text, mood)."""
+    return (
+        "Hey! I'm Pip. Your focus buddy, breathing coach, and part-time philosopher. "
+        "[mood: greeting]\n\n"
+        "What do you need right now?",
+        "greeting",
+    )
+
+
+def get_goodbye() -> Tuple[str, str]:
+    """Get Pip's goodbye message. Returns (text, mood)."""
+    return (
+        "See you soon! Take care of yourself. That's an order. 😄\n"
+        "[mood: goodbye]",
+        "goodbye",
+    )

projects/focusfriend/modes/focus.py

@@ -0,0 +1,125 @@
+"""
+Focus / Pomodoro mode for FocusFriend.
+
+Pip helps you stay focused for timed work sessions.
+Standard Pomodoro: 25 min work, 5 min break.
+"""
+
+import time
+import threading
+from typing import Optional, Callable
+
+
+class FocusSession:
+    """Manages a focus/Pomodoro session."""
+
+    def __init__(
+        self,
+        duration_minutes: int = 25,
+        on_complete: Optional[Callable] = None,
+        on_tick: Optional[Callable] = None,
+    ):
+        self.duration_seconds = duration_minutes * 60
+        self.remaining_seconds = self.duration_seconds
+        self.running = False
+        self.paused = False
+        self.completed = False
+        self.on_complete = on_complete
+        self.on_tick = on_tick
+        self._thread: Optional[threading.Thread] = None
+
+    def start(self):
+        """Start the focus timer in a background thread."""
+        if self.running:
+            return
+        self.running = True
+        self.paused = False
+        self.completed = False
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def pause(self):
+        """Pause the timer."""
+        self.paused = True
+
+    def resume(self):
+        """Resume a paused timer."""
+        self.paused = False
+
+    def stop(self):
+        """Stop the timer early."""
+        self.running = False
+        if self._thread:
+            self._thread.join(timeout=1)
+
+    def _run(self):
+        """Background timer loop."""
+        while self.running and self.remaining_seconds > 0:
+            if not self.paused:
+                time.sleep(1)
+                self.remaining_seconds -= 1
+                if self.on_tick:
+                    self.on_tick(self.remaining_seconds)
+            else:
+                time.sleep(0.1)
+
+        if self.remaining_seconds <= 0 and self.running:
+            self.completed = True
+            self.running = False
+            if self.on_complete:
+                self.on_complete()
+
+    def get_time_display(self) -> str:
+        """Return MM:SS formatted time string."""
+        mins = self.remaining_seconds // 60
+        secs = self.remaining_seconds % 60
+        return f"{mins:02d}:{secs:02d}"
+
+    def get_progress(self) -> float:
+        """Return progress as a fraction (0.0 to 1.0)."""
+        if self.duration_seconds == 0:
+            return 1.0
+        return 1.0 - (self.remaining_seconds / self.duration_seconds)
+
+
+# Pre-written Pip messages for focus sessions
+
+FOCUS_START_MESSAGES = [
+    "Alright, {duration} minutes of focus. [mood: focus]\n"
+    "One task. No phone. I believe in you — and I'm annoyingly persistent.",
+
+    "Focus mode: ON. [mood: determined]\n"
+    "{duration} minutes. You've done harder things before breakfast.\n"
+    "Let's go.",
+
+    "Here we go. [mood: focus]\n"
+    "{duration} minutes of uninterrupted work. I'll keep time.\n"
+    "You just do your thing.",
+]
+
+FOCUS_COMPLETE_MESSAGES = [
+    "Done! {duration} minutes in the books. [mood: celebrate]\n"
+    "Doesn't matter what you accomplished — you showed up. That's the hard part.",
+
+    "Time's up. [mood: proud]\n"
+    "Take a breath. Stretch. You earned a break.\n"
+    "Not a long one though. We're not done yet. 😏",
+
+    "Session complete. [mood: celebrate]\n"
+    "Look at you, being all productive.\n"
+    "Seriously — good job. Now go drink some water.",
+]
+
+BREAK_REMINDER_MESSAGES = [
+    "Hey. [mood: break_time]\n"
+    "Your eyes have been staring at this screen for a while.\n"
+    "20-20-20 rule: look at something 20 feet away for 20 seconds.",
+
+    "Quick check-in. [mood: concerned]\n"
+    "Shoulders down. Unclench your jaw. Breathe.\n"
+    "Okay, carry on.",
+
+    "Break time. [mood: break_time]\n"
+    "Stand up. Walk to the other room and back.\n"
+    "Your body will thank you. Your brain will too.",
+]

projects/focusfriend/modes/meditate.py

@@ -0,0 +1,158 @@
+"""
+Meditation mode for FocusFriend.
+
+Pip guides short meditation sessions:
+- Body scan
+- Loving-kindness (metta)
+- Just sitting (shikantaza-style)
+"""
+
+from typing import Dict, List, Optional
+import random
+
+
+# Guided meditation scripts
+# Each key maps to a pre-written script when LLM is unavailable
+
+MEDITATION_SCRIPTS: Dict[str, Dict] = {
+    "body-scan": {
+        "name": "Body Scan",
+        "description": (
+            "Systematically bringing awareness to each part of the body, "
+            "noticing sensations, and releasing tension."
+        ),
+        "script": [
+            ("Find a comfortable position. Sitting or lying down — either works.", "meditate"),
+            ("Close your eyes gently. Take three deep breaths to settle in.", "breathing_in"),
+            ("[pause]", "zen"),
+            ("Bring your attention to your feet. Just notice what you feel. Warmth? Coolness? Tingling? Nothing at all? Whatever you notice is fine.", "meditate"),
+            ("Now move up to your ankles and lower legs. Any tension there? Let it soften.", "meditate"),
+            ("[pause]", "zen"),
+            ("Your knees and thighs. Feel the weight of them. Let them be heavy and relaxed.", "meditate"),
+            ("[pause]", "zen"),
+            ("Your hips and pelvis. This is where many of us hold stress. Breathe into this area and let it release.", "meditate"),
+            ("[pause]", "zen"),
+            ("Your lower back and belly. Feel the gentle rise and fall of your breath here.", "breathing_in"),
+            ("[pause]", "zen"),
+            ("Your chest and upper back. Let your shoulders drop away from your ears.", "meditate"),
+            ("[pause]", "zen"),
+            ("Your arms and hands. Soften your fingers. Let them be still.", "meditate"),
+            ("[pause]", "zen"),
+            ("Your neck and throat. Swallow once and let everything relax.", "meditate"),
+            ("[pause]", "zen"),
+            ("Your face. Unclench your jaw. Soften your eyes. Let your forehead be smooth.", "meditate"),
+            ("[pause]", "zen"),
+            ("Your whole body now. From toes to the top of your head. One complete, living, breathing whole.", "meditate"),
+            ("[pause]", "zen"),
+            ("Rest here for a moment. Nothing to do. Nowhere to be.", "zen"),
+            ("[pause]", "zen"),
+            ("When you're ready, wiggle your fingers and toes. Gently open your eyes.", "meditate"),
+            ("Welcome back. Take this calm with you.", "gentle"),
+        ],
+        "suggested_duration_min": 5,
+    },
+    "loving-kindness": {
+        "name": "Loving-Kindness (Metta)",
+        "description": (
+            "A traditional Buddhist practice of directing well-wishes toward "
+            "yourself and others. Backed by research on increasing positive emotions."
+        ),
+        "script": [
+            ("Sit comfortably. Close your eyes. Hand on your heart if that feels right.", "meditate"),
+            ("Take a few deep breaths. Let your heart area feel warm.", "breathing_in"),
+            ("[pause]", "zen"),
+            ("Now, silently repeat these phrases toward yourself:", "meditate"),
+            ("May I be happy.", "gentle"),
+            ("May I be healthy.", "gentle"),
+            ("May I be safe.", "gentle"),
+            ("May I live with ease.", "gentle"),
+            ("[pause]", "zen"),
+            ("Don't worry if it feels awkward. That's normal. Just let the words be there.", "meditate"),
+            ("[pause]", "zen"),
+            ("Now bring to mind someone you love easily. A friend, a pet, a kind mentor.", "meditate"),
+            ("Picture them. Feel the warmth of your connection.", "gentle"),
+            ("May you be happy.", "gentle"),
+            ("May you be healthy.", "gentle"),
+            ("May you be safe.", "gentle"),
+            ("May you live with ease.", "gentle"),
+            ("[pause]", "zen"),
+            ("Now bring to mind a neutral person. Someone you see but don't know well.", "meditate"),
+            ("The barista. The neighbor you nod at. The person who delivers your mail.", "meditate"),
+            ("They want to be happy too. Just like you.", "gentle"),
+            ("May you be happy. May you be healthy. May you be safe. May you live with ease.", "gentle"),
+            ("[pause]", "zen"),
+            ("Now — if it feels right — bring to mind someone you have difficulty with.", "meditate"),
+            ("Just for a moment. They're human too. They struggle too.", "concerned"),
+            ("May you be happy. May you be healthy. May you be safe. May you live with ease.", "gentle"),
+            ("[pause]", "zen"),
+            ("Finally, expand to all beings everywhere.", "meditate"),
+            ("May all beings be happy. May all beings be healthy. May all beings be safe. May all beings live with ease.", "gentle"),
+            ("[pause]", "zen"),
+            ("Sit with that feeling. This warmth you generated — it came from you.", "proud"),
+            ("When you're ready, open your eyes.", "meditate"),
+        ],
+        "suggested_duration_min": 8,
+    },
+    "just-sit": {
+        "name": "Just Sitting",
+        "description": (
+            "No technique. No goal. Just being here. A minimalist approach "
+            "to meditation — sometimes the hardest and most rewarding."
+        ),
+        "script": [
+            ("Sit comfortably. Spine upright but not rigid.", "meditate"),
+            ("Close your eyes. Or keep them open, soft-focused on the floor in front of you.", "meditate"),
+            ("[pause]", "zen"),
+            ("There's nothing to do right now. Nothing to achieve.", "meditate"),
+            ("Thoughts will come. That's fine. They're supposed to.", "meditate"),
+            ("When you notice you're thinking, just note: 'thinking.'", "thoughtful"),
+            ("Then return to the breath. Or the sounds in the room. Or the feeling of sitting.", "meditate"),
+            ("[pause]", "zen"),
+            ("No judgment. No 'I'm doing this wrong.' There is no wrong.", "gentle"),
+            ("[pause]", "zen"),
+            ("If you get lost in thought a hundred times, just return a hundred times.", "meditate"),
+            ("Each return is the practice. Each return is a tiny victory.", "encourage"),
+            ("[pause]", "zen"),
+            ("Just this. Just sitting. Just breathing. Just being.", "zen"),
+            ("[pause]", "zen"),
+            ("When you're ready, take a deeper breath. Notice how you feel.", "meditate"),
+            ("Gently open your eyes. Carry this simplicity with you.", "gentle"),
+        ],
+        "suggested_duration_min": 5,
+    },
+}
+
+
+def get_meditation_script(style: str) -> Optional[Dict]:
+    """Get a meditation script by style name."""
+    return MEDITATION_SCRIPTS.get(style)
+
+
+def list_styles() -> List[str]:
+    """Return available meditation style names."""
+    return [
+        {"name": s["name"], "duration_min": s["suggested_duration_min"]}
+        for s in MEDITATION_SCRIPTS.values()
+    ]
+
+
+def get_phrases(style: str, count: Optional[int] = None) -> List[tuple]:
+    """
+    Get meditation phrases for step-by-step display.
+
+    Args:
+        style: 'body-scan', 'loving-kindness', or 'just-sit'
+        count: Optional max number of phrases to return
+
+    Returns:
+        List of (text, mood) tuples
+    """
+    meditation = MEDITATION_SCRIPTS.get(style)
+    if meditation is None:
+        return [("Sit quietly and breathe. Just be here.", "meditate")]
+
+    script = meditation["script"]
+    if count:
+        script = script[:count]
+
+    return script

projects/focusfriend/requirements.txt

@@ -0,0 +1,12 @@
+# FocusFriend — ASCII Wellness Companion
+# Python 3.10+
+
+# === Core ===
+gradio>=5.0
+numpy>=1.24
+
+# === LLM Inference (Gemma 4 12B) ===
+llama-cpp-python>=0.3.0
+
+# === Utilities ===
+huggingface_hub>=0.20

projects/focusfriend/static/script.js

@@ -0,0 +1,258 @@
+/**
+ * FocusFriend — Custom JavaScript
+ * Handles: focus timer, breathing animation, break reminders, UI interactions
+ */
+
+// ============================================================
+// Focus Timer
+// ============================================================
+
+let focusTimerId = null;
+let focusRemainingSeconds = 0;
+let focusTotalSeconds = 0;
+
+function focusStartTimer(durationMinutes) {
+    focusTotalSeconds = durationMinutes * 60;
+    focusRemainingSeconds = focusTotalSeconds;
+    focusUpdateDisplay();
+    focusShowTimer();
+
+    if (focusTimerId) clearInterval(focusTimerId);
+
+    focusTimerId = setInterval(() => {
+        focusRemainingSeconds--;
+        focusUpdateDisplay();
+
+        if (focusRemainingSeconds <= 300) {
+            // 5-minute warning
+            const timerEl = document.getElementById('ff-focus-timer');
+            if (timerEl) timerEl.classList.add('warning');
+        }
+
+        if (focusRemainingSeconds <= 0) {
+            focusComplete();
+        }
+    }, 1000);
+}
+
+function focusPauseTimer() {
+    if (focusTimerId) {
+        clearInterval(focusTimerId);
+        focusTimerId = null;
+    }
+}
+
+function focusResumeTimer() {
+    if (focusRemainingSeconds > 0 && !focusTimerId) {
+        focusTimerId = setInterval(() => {
+            focusRemainingSeconds--;
+            focusUpdateDisplay();
+            if (focusRemainingSeconds <= 0) focusComplete();
+        }, 1000);
+    }
+}
+
+function focusStopTimer() {
+    if (focusTimerId) {
+        clearInterval(focusTimerId);
+        focusTimerId = null;
+    }
+    focusHideTimer();
+}
+
+function focusUpdateDisplay() {
+    const mins = Math.floor(focusRemainingSeconds / 60);
+    const secs = focusRemainingSeconds % 60;
+    const display = document.getElementById('ff-focus-timer');
+    if (display) {
+        display.textContent =
+            String(mins).padStart(2, '0') + ':' + String(secs).padStart(2, '0');
+    }
+}
+
+function focusShowTimer() {
+    const timer = document.getElementById('ff-focus-timer');
+    if (timer) timer.style.display = 'block';
+}
+
+function focusHideTimer() {
+    const timer = document.getElementById('ff-focus-timer');
+    if (timer) {
+        timer.style.display = 'none';
+        timer.classList.remove('warning');
+    }
+}
+
+function focusComplete() {
+    clearInterval(focusTimerId);
+    focusTimerId = null;
+
+    const artEl = document.querySelector('.ff-pip-art textarea');
+    if (artEl) {
+        artEl.classList.add('ff-celebrate');
+        setTimeout(() => artEl.classList.remove('ff-celebrate'), 1500);
+    }
+
+    // Trigger a Gradio event to notify the Python backend
+    const event = new CustomEvent('focusfriend:focus-complete', {
+        detail: { duration: focusTotalSeconds / 60 }
+    });
+    document.dispatchEvent(event);
+}
+
+function focusGetRemaining() {
+    return focusRemainingSeconds;
+}
+
+// ============================================================
+// Breathing Animation
+// ============================================================
+
+let breatheIntervalId = null;
+let breathePhaseIndex = 0;
+let breatheSecondsInPhase = 0;
+
+const BREATHE_PATTERNS = {
+    '4-7-8': [
+        { duration: 4, phase: 'in', label: 'Inhale' },
+        { duration: 7, phase: 'hold', label: 'Hold' },
+        { duration: 8, phase: 'out', label: 'Exhale' },
+    ],
+    'box': [
+        { duration: 4, phase: 'in', label: 'Inhale' },
+        { duration: 4, phase: 'hold', label: 'Hold' },
+        { duration: 4, phase: 'out', label: 'Exhale' },
+        { duration: 4, phase: 'hold', label: 'Hold' },
+    ],
+    'simple': [
+        { duration: 4, phase: 'in', label: 'Inhale' },
+        { duration: 6, phase: 'out', label: 'Exhale' },
+    ],
+};
+
+function breatheStart(technique) {
+    breatheStop();
+    const pattern = BREATHE_PATTERNS[technique] || BREATHE_PATTERNS['4-7-8'];
+    breathePhaseIndex = 0;
+    breatheSecondsInPhase = 0;
+
+    const pipEl = document.querySelector('.ff-pip-art textarea');
+    const guideEl = document.getElementById('ff-breathe-guide');
+
+    breatheIntervalId = setInterval(() => {
+        const phase = pattern[breathePhaseIndex % pattern.length];
+
+        if (breatheSecondsInPhase === 0) {
+            // Update Pip's expression
+            if (pipEl) {
+                pipEl.classList.remove('ff-breathing-in', 'ff-breathing-out');
+                if (phase.phase === 'in') {
+                    pipEl.classList.add('ff-breathing-in');
+                } else if (phase.phase === 'out') {
+                    pipEl.classList.add('ff-breathing-out');
+                }
+            }
+            // Update guide text
+            if (guideEl) {
+                guideEl.textContent = phase.label + ' (' + phase.duration + 's)';
+            }
+        }
+
+        breatheSecondsInPhase++;
+
+        if (breatheSecondsInPhase >= phase.duration) {
+            breatheSecondsInPhase = 0;
+            breathePhaseIndex++;
+        }
+    }, 1000);
+}
+
+function breatheStop() {
+    if (breatheIntervalId) {
+        clearInterval(breatheIntervalId);
+        breatheIntervalId = null;
+    }
+    const pipEl = document.querySelector('.ff-pip-art textarea');
+    if (pipEl) {
+        pipEl.classList.remove('ff-breathing-in', 'ff-breathing-out');
+    }
+}
+
+// ============================================================
+// Break Reminder
+// ============================================================
+
+let breakReminderId = null;
+let lastActivityTime = Date.now();
+
+function breakReminderStart(intervalMinutes) {
+    breakReminderStop();
+    breakReminderId = setInterval(() => {
+        const idleMs = Date.now() - lastActivityTime;
+        const idleMinutes = idleMs / 60000;
+        if (idleMinutes >= intervalMinutes) {
+            const event = new CustomEvent('focusfriend:break-reminder', {
+                detail: { idleMinutes: Math.round(idleMinutes) }
+            });
+            document.dispatchEvent(event);
+        }
+    }, 60000); // Check every minute
+}
+
+function breakReminderStop() {
+    if (breakReminderId) {
+        clearInterval(breakReminderId);
+        breakReminderId = null;
+    }
+}
+
+function breakRecordActivity() {
+    lastActivityTime = Date.now();
+}
+
+// Track user activity
+document.addEventListener('click', breakRecordActivity);
+document.addEventListener('keydown', breakRecordActivity);
+
+// ============================================================
+// Pip Mood Animations
+// ============================================================
+
+function pipSetMood(mood) {
+    const artEl = document.querySelector('.ff-pip-art textarea');
+    if (!artEl) return;
+
+    // Remove all mood classes
+    artEl.classList.remove(
+        'ff-breathing-in', 'ff-breathing-out', 'ff-celebrate'
+    );
+
+    // Add mood-specific class
+    if (mood === 'celebrate') {
+        artEl.classList.add('ff-celebrate');
+        setTimeout(() => artEl.classList.remove('ff-celebrate'), 1500);
+    }
+}
+
+// ============================================================
+// Page Load Initialization
+// ============================================================
+
+document.addEventListener('DOMContentLoaded', () => {
+    console.log('FocusFriend initialized ✦');
+    breakRecordActivity();
+});
+
+// Expose functions globally so Gradio can call them
+window.focusfriend = {
+    focusStartTimer,
+    focusPauseTimer,
+    focusResumeTimer,
+    focusStopTimer,
+    focusGetRemaining,
+    breatheStart,
+    breatheStop,
+    breakReminderStart,
+    breakReminderStop,
+    pipSetMood,
+};

projects/focusfriend/static/style.css

@@ -0,0 +1,357 @@
+/* ============================================================
+   FocusFriend — Custom Off-Brand Stylesheet
+   Dark, cozy theme with amber/gold accents.
+   Designed to feel like a warm room at night, not a corporate app.
+   ============================================================ */
+
+/* === CSS Variables === */
+:root {
+    --ff-bg: #1a1a2e;
+    --ff-surface: #16213e;
+    --ff-surface2: #0f3460;
+    --ff-text: #e0d7c6;
+    --ff-text-dim: #a89f91;
+    --ff-accent: #e8b44b;
+    --ff-accent-glow: rgba(232, 180, 75, 0.3);
+    --ff-accent2: #d4756b;
+    --ff-green: #7eb77f;
+    --ff-border: #2a2a4a;
+    --ff-pip-bg: #0d1117;
+    --ff-radius: 8px;
+    --ff-font-mono: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Courier New', monospace;
+    --ff-font-sans: 'Inter', 'SF Pro Display', 'Segoe UI', system-ui, sans-serif;
+}
+
+/* === Global === */
+.gradio-container {
+    background: var(--ff-bg) !important;
+    font-family: var(--ff-font-sans) !important;
+    color: var(--ff-text) !important;
+}
+
+h1, h2, h3, h4, h5, h6 {
+    font-family: var(--ff-font-sans) !important;
+    color: var(--ff-accent) !important;
+    font-weight: 600 !important;
+}
+
+a {
+    color: var(--ff-accent) !important;
+}
+
+/* === Header === */
+.ff-header {
+    text-align: center;
+    padding: 24px 0 32px;
+}
+
+.ff-header h1 {
+    font-size: 2.4em;
+    margin: 0;
+    background: linear-gradient(135deg, var(--ff-accent), var(--ff-accent2));
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+}
+
+/* === Pip Display Panel === */
+.ff-pip-panel {
+    background: var(--ff-pip-bg);
+    border: 2px solid var(--ff-border);
+    border-radius: 12px;
+    padding: 24px 20px;
+    min-height: 320px;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    box-shadow: 0 0 40px var(--ff-accent-glow) inset;
+}
+
+.ff-pip-art {
+    font-family: var(--ff-font-mono) !important;
+    font-size: 13px !important;
+    line-height: 1.35 !important;
+    color: var(--ff-accent) !important;
+    white-space: pre !important;
+    text-align: center !important;
+    background: transparent !important;
+    border: none !important;
+    padding: 16px !important;
+    min-height: 240px !important;
+    text-shadow: 0 0 20px var(--ff-accent-glow);
+}
+
+.ff-pip-art textarea {
+    font-family: var(--ff-font-mono) !important;
+    color: var(--ff-accent) !important;
+    background: transparent !important;
+    border: none !important;
+    resize: none !important;
+    text-align: center !important;
+}
+
+/* === Timer === */
+.ff-timer {
+    font-family: var(--ff-font-mono);
+    font-size: 3.5em;
+    text-align: center;
+    color: var(--ff-accent);
+    padding: 16px;
+    letter-spacing: 4px;
+    text-shadow: 0 0 30px var(--ff-accent-glow);
+}
+
+.ff-timer.warning {
+    color: var(--ff-accent2);
+    animation: pulse 1s ease-in-out infinite;
+}
+
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+}
+
+/* === Mode Bar === */
+.ff-mode-bar {
+    display: flex;
+    gap: 8px;
+    padding: 12px;
+    background: var(--ff-surface);
+    border-radius: 12px;
+    border: 1px solid var(--ff-border);
+    margin-bottom: 16px;
+}
+
+.ff-mode-bar button {
+    font-family: var(--ff-font-sans) !important;
+    font-weight: 500 !important;
+    font-size: 0.95em !important;
+    padding: 10px 20px !important;
+    border-radius: 8px !important;
+    border: 1px solid var(--ff-border) !important;
+    background: var(--ff-surface2) !important;
+    color: var(--ff-text-dim) !important;
+    cursor: pointer !important;
+    transition: all 0.25s ease !important;
+    flex: 1 !important;
+}
+
+.ff-mode-bar button:hover {
+    background: rgba(232, 180, 75, 0.15) !important;
+    color: var(--ff-accent) !important;
+    border-color: var(--ff-accent) !important;
+    transform: translateY(-1px);
+}
+
+.ff-mode-bar button.active,
+.ff-mode-bar button.selected {
+    background: var(--ff-accent) !important;
+    color: var(--ff-bg) !important;
+    border-color: var(--ff-accent) !important;
+    font-weight: 600 !important;
+    box-shadow: 0 0 20px var(--ff-accent-glow);
+}
+
+/* === Chatbot === */
+.ff-chatbot {
+    border: 1px solid var(--ff-border) !important;
+    border-radius: 12px !important;
+    background: var(--ff-surface) !important;
+    overflow: hidden !important;
+}
+
+.ff-chatbot .message-wrap {
+    padding: 12px 16px !important;
+}
+
+.ff-chatbot .user {
+    background: var(--ff-surface2) !important;
+    border-radius: 8px !important;
+    margin: 4px 0 !important;
+}
+
+.ff-chatbot .bot {
+    background: var(--ff-pip-bg) !important;
+    border-left: 3px solid var(--ff-accent) !important;
+    border-radius: 0 8px 8px 0 !important;
+    margin: 4px 0 !important;
+}
+
+.ff-chatbot .bot p {
+    color: var(--ff-text) !important;
+}
+
+/* === Chat Input === */
+.ff-chat-input textarea {
+    background: var(--ff-surface) !important;
+    border: 1px solid var(--ff-border) !important;
+    border-radius: 8px !important;
+    color: var(--ff-text) !important;
+    font-family: var(--ff-font-sans) !important;
+    padding: 12px !important;
+    resize: none !important;
+}
+
+.ff-chat-input textarea:focus {
+    border-color: var(--ff-accent) !important;
+    box-shadow: 0 0 15px var(--ff-accent-glow) !important;
+}
+
+/* === Primary Buttons === */
+button.primary,
+button[variant="primary"] {
+    background: var(--ff-accent) !important;
+    color: var(--ff-bg) !important;
+    font-weight: 600 !important;
+    border: none !important;
+    border-radius: 8px !important;
+    padding: 10px 24px !important;
+    transition: all 0.25s ease !important;
+    font-size: 1em !important;
+}
+
+button.primary:hover,
+button[variant="primary"]:hover {
+    background: #f0c55a !important;
+    box-shadow: 0 4px 20px var(--ff-accent-glow) !important;
+    transform: translateY(-1px);
+}
+
+button.primary:active,
+button[variant="primary"]:active {
+    transform: translateY(0);
+}
+
+/* === Secondary Buttons === */
+button.secondary {
+    background: var(--ff-surface2) !important;
+    color: var(--ff-text) !important;
+    border: 1px solid var(--ff-border) !important;
+    border-radius: 8px !important;
+    padding: 10px 24px !important;
+    transition: all 0.25s ease !important;
+}
+
+button.secondary:hover {
+    border-color: var(--ff-accent) !important;
+    color: var(--ff-accent) !important;
+}
+
+/* === Dropdowns & Sliders === */
+select, .dropdown {
+    background: var(--ff-surface) !important;
+    border: 1px solid var(--ff-border) !important;
+    border-radius: 8px !important;
+    color: var(--ff-text) !important;
+    padding: 8px 12px !important;
+}
+
+input[type="range"] {
+    accent-color: var(--ff-accent);
+}
+
+/* === Group Panels === */
+.gr-group {
+    background: var(--ff-surface) !important;
+    border: 1px solid var(--ff-border) !important;
+    border-radius: 12px !important;
+    padding: 16px !important;
+    margin-bottom: 12px !important;
+}
+
+/* === Accordion === */
+.gr-accordion {
+    background: var(--ff-surface) !important;
+    border: 1px solid var(--ff-border) !important;
+    border-radius: 12px !important;
+}
+
+/* === Scrollbar === */
+::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+
+::-webkit-scrollbar-track {
+    background: var(--ff-bg);
+    border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb {
+    background: var(--ff-border);
+    border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: var(--ff-accent);
+}
+
+/* === Footer (hide Gradio default) === */
+footer {
+    display: none !important;
+}
+
+/* === Tabs (hidden for our custom UI) === */
+.tabs {
+    border: none !important;
+}
+
+.tab-nav {
+    display: none !important;
+}
+
+/* === Responsive === */
+@media (max-width: 768px) {
+    .ff-pip-panel {
+        min-height: 200px;
+        padding: 12px;
+    }
+
+    .ff-pip-art {
+        font-size: 10px !important;
+        min-height: 160px !important;
+    }
+
+    .ff-mode-bar {
+        flex-wrap: wrap;
+    }
+
+    .ff-mode-bar button {
+        font-size: 0.85em !important;
+        padding: 8px 12px !important;
+    }
+
+    .ff-timer {
+        font-size: 2.5em;
+    }
+}
+
+/* === Breathing animation === */
+.ff-breathing-in {
+    animation: breatheIn 4s ease-in-out;
+}
+
+.ff-breathing-out {
+    animation: breatheOut 8s ease-in-out;
+}
+
+@keyframes breatheIn {
+    from { transform: scale(1); }
+    to { transform: scale(1.05); }
+}
+
+@keyframes breatheOut {
+    from { transform: scale(1.05); }
+    to { transform: scale(1); }
+}
+
+/* === Focus complete celebration === */
+.ff-celebrate {
+    animation: celebrate 0.5s ease-in-out 3;
+}
+
+@keyframes celebrate {
+    0%, 100% { transform: translateY(0); }
+    50% { transform: translateY(-10px); }
+}