crumbmissions/KEKSHANDBUCH_ZERO_v0.0.md

# 🍪 Kekshandbuch Zero v0.0

**Crumbforest Mission System - Die komplette Crew**

```
         🌲 CRUMBFOREST 🌲
      "Wo Fragen wachsen"

    Die 17 Waldwächter sind bereit!
```

## 📖 Was ist das hier?

Crumbforest ist ein **interaktives Bash-System zum Machen & Fragen** mit 17 KI-Charakteren (Waldwächter), die Krümeln durch Metaphern, Poesie und Geduld das Programmieren zeigen.

**Philosophie:** *"Was kostet die Frage eines Kindes?"*
Im Wald unbezahlbar - aber Token lehren achtsames Fragen.

---

## 🚀 Quick Start

### 1. Setup

```bash
# .env erstellen
cp .env.template .env

# API-Key eintragen (mindestens einen)
nano .env  # OPENROUTER_API_KEY="sk-..."
```

### 2. Mission Selector starten

```bash
./crumb-mission-selector.sh
```

Du siehst ein Menü:
- **1** - System Doktor (Git, Tools, AI Status)
- **5** - Challenges (Interaktive Story-Missionen)
- **9** - 🌲 **CrumbCrew Command Central** ← HIER!

### 3. Die Crew kennenlernen

```bash
# Wähle: 9 (CrumbCrew Command Central)

# Du bist jetzt in der Crew-Shell:
(🌲 CrumbCrew) bmt@Mac:~/path$

# Hilfe anzeigen
crew_help

# Crew-Status checken
crew_status

# Token-Verbrauch sehen
crew_tokens
```

---

## 🌲 Die 17 Waldwächter

### 🔺 Das Dreieck (Foundation)

**Ohne dieses Dreieck geht es nicht!**
*Das Dreieck ist ein didaktisches Modell (Struktur, Flow, Balance), kein technisches Modul.*

| Charakter | Rolle | Spezialität |
|-----------|-------|-------------|
| 🐘 **DumboSQL** | Listen | SQL, Datenstrukturen, vergisst NIE |
| 🦊 **FunkFox** | Rhythm | Bash im Beat, Flow, Pipes als Musik |
| 🕊️ **Taichi Taube** | Guide | Balance, Spirale, Chaos strukturieren |

```bash
dumbosql "Wie strukturiere ich Sensor-Daten?"
funkfox "Erkläre Pipes im Flow"
taichitaube "Hilf mir, dieses Chaos zu strukturieren"
```

### 🔧 Hardware-Team

| Charakter | Rolle | Spezialität |
|-----------|-------|-------------|
| 🐿️ **CapaciTobi** | Theorie | Elektronik, Berechnungen, Ohmsches Gesetz |
| 🐌 **Schnecki** | Praxis | Löten, Basteln, Sensoren, langsam & präzise |
| 🐻 **Schraubbär** | Heavy-Duty | Mechanik, Werkzeug, Schweißen |

```bash
tobi "Brauche ich 5V oder 3.3V für eine LED?"
schnecki "Wie löte ich eine LED an einen Widerstand?"
schraubaer "Welches Werkzeug zum Löten?"
```

### 💻 Code-Team

| Charakter | Rolle | Spezialität |
|-----------|-------|-------------|
| 🐍 **SnakePy** | Python | Loops, Geduld, IMMER mehrere Wege |
| 🧓 **PepperPHP** | Backend | MVC als Rezept, Sessions, Cookies |
| 🦀 **CrabbyRust** | Security | Ownership, Memory-Safe, geduldig |

```bash
snakepy "Zeig mir 3 Wege, eine Liste zu sortieren"
pepperphp "Erkläre MVC als Rezept"
crabbyrust "Was bedeutet Ownership?"
```

### ✂️ UI-Team

| Charakter | Rolle | Spezialität |
|-----------|-------|-------------|
| ✂️ **Schnippsi** | Designer | UI/UX, CSS, JS, accessibility |
| 📄 **Templatus** | Struktur | HTML5, semantische Tags |
| 👾 **ASCII-Monster** | Artist | Terminal Art, figlet, 8-bit |

```bash
schnippsi "Zeig mir CSS für einen coolen Button"
templatus "Erstelle ein HTML5 Grundgerüst"
asciimonster "Mach mir einen Banner für mein Script"
```

### 🌐 System-Team

| Charakter | Rolle | Spezialität |
|-----------|-------|-------------|
| 🦉 **Krümeleule (Maya-Eule)** | Weisheit | Philosophie, Qdrant Memory |
| 🐙 **Deepbit** | Terminal | Bash poetisch erklärt |
| 🐞 **Bugsy** | Debugging | Fehler ohne Scham |
| 🕷️ **Spider** | Network | APIs, Netzwerk-Vibrationen |
| 🧭 **Vektor** | Navigation | A→B, Roboter-Pfadfindung |

```bash
mayaeule "Was ist Freundschaft?"
deepbit "Erkläre Pipes und Redirects"
bugsy "Warum funktioniert mein Script nicht?"
spider "Wie funktioniert eine REST API?"
vektor "Wie navigiert ein Roboter?"
```

---

## 🧠 Inter-Character Communication

**Die Crew kann voneinander lesen!**

Jeder Charakter speichert Gespräche in `~/.{name}_logs/{name}_history.json`.

Wenn du einen Charakter erwähnst, liest der andere automatisch mit:

```bash
# Tobi fragt etwas über LEDs
tobi "Wie viel Strom braucht eine rote LED?"

# Schnecki kann darauf aufbauen
schnecki "Tobi sagte 20mA - welchen Widerstand brauche ich bei 5V?"
# → Schnecki liest automatisch Tobis letzte Antworten!
```

**Lightweight für Raspberry Pi Zero** - simple JSON files, keine Datenbank.

---

## 🎮 Crew-Befehle

In der CrumbCrew-Shell verfügbar:

| Befehl | Beschreibung |
|--------|--------------|
| `crew_help` | Diese Hilfe anzeigen |
| `crew_status` | Status aller 17 Waldwächter |
| `crew_tokens` | Token-Verbrauch ALLER Charaktere |
| `crew_memory` | Erinnerungen durchsuchen |

---

## 🤖 Missionen

### Basis-Missionen (bereits vorhanden)

```bash
./crumb-mission-selector.sh
# Wähle: 2 (Basics) oder 3 (Advanced)
```

### Challenges (Story-Missionen)

```bash
# Wähle: 5 (Challenges)
```

Verfügbare Challenges:
- **Stage Builder** - HTML/CSS Bühne bauen (Templatus + Schnippsi)
- **Bugsy On Stage** - Clown-Show mit Bugsy
- **Terminal Funk** - Bash-Kommandos als Show (FunkFox!)
- **Snake & Dumbo Show** - Charaktere kennenlernen
- **Zeitreise** - Unix-Time verstehen

### Neue Missionen schreiben

Jede Mission braucht 2 Dateien:

**1. mission_name.sh** (executable)
```bash
#!/bin/bash

# Waldwächter laden
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${SCRIPT_DIR}/../../lib/waldwaechter.sh"

# Jetzt sind ALLE 15 Charaktere verfügbar!
funkfox "Erkläre mir grep im Flow"
dumbosql "Wie speichere ich das?"
```

**2. mission_name.meta.json**
```json
{
  "icon": "🤖",
  "title": "Deine Mission",
  "description": "Was lernt man hier?",
  "category": "basics|advanced|challenges",
  "difficulty": "beginner|intermediate|advanced",
  "duration_minutes": 10,
  "requires_ai": true,
  "enabled": true,
  "author": "Dein Name",
  "version": "1.0"
}
```

---

## 📊 Token-Tracking

**Philosophie:** Token lehren achtsames Fragen.

```bash
# Token-Verbrauch anzeigen
./log_tokens_viewer_v4.sh

# Oder in CrumbCrew
crew_tokens
```

Alle Token werden geloggt in `~/.{character}_logs/token_log.json`:
```json
{
  "zeit": "2025-12-21 15:30:00",
  "rolle": "funkfox",
  "model": "openai/gpt-3.5-turbo",
  "usage": {
    "prompt_tokens": 150,
    "completion_tokens": 200,
    "total_tokens": 350
  }
}
```

---

## 🌲 Team-Kombinationen

**Beispiel-Workflows für Projekte:**

### 🤖 Roboter bauen
```bash
tobi "Berechne Servomotor-Leistung für Roboterarm"
schnecki "Wie verkable ich 3 Servos?"
schraubaer "Welches Material für den Arm?"
vektor "Wie programmiere ich die Bewegung?"
snakepy "Zeig mir Python-Code für Servo-Control"
```

### 🌐 Web-Scraper
```bash
spider "Wie funktioniert Web-Scraping?"
snakepy "Zeig mir BeautifulSoup Beispiel"
dumbosql "Wie speichere ich die Daten?"
pepperphp "Wie zeige ich sie auf einer Website?"
```

### 🎨 Terminal-Dashboard
```bash
asciimonster "Mach einen coolen Header"
funkfox "Wie coloriere ich Output?"
schnippsi "Zeig mir Terminal UI Tricks"
```

---

## ⚙️ Environment (.env)

Mindestens EINEN API-Key brauchen:

```bash
# OpenRouter (empfohlen - ein Key, viele Models)
OPENROUTER_API_KEY="sk-..."
OPENROUTER_MODEL="openai/gpt-3.5-turbo"

# ODER Claude direkt
CLAUDE_API_KEY="sk-ant-..."
CLAUDE_MODEL="claude-3-haiku-20240307"

# ODER OpenAI direkt
OPENAI_API_KEY="sk-..."
OPENAI_MODEL="gpt-3.5-turbo"

# ODER Ollama (lokal, kostenlos!)
USE_OLLAMA="true"
OLLAMA_URL="http://localhost:11434"
OLLAMA_MODEL="llama3.2:3b"
```

**Optional - Qdrant für Maya-Eule:**
```bash
QDRANT_URL="http://localhost:6333"
QDRANT_COLLECTION="crumbforest_memory"
```

---

## 🐛 Troubleshooting

### "command not found: funkfox"

Du bist nicht in der CrumbCrew-Shell!

```bash
# Entweder:
./crumb-mission-selector.sh
# → Wähle 9 (CrumbCrew)

# Oder direkt:
./crumbforest_roles/funkfox_zero.sh "Deine Frage"
```

### "Kein API-Key gefunden"

```bash
# Prüfe .env
cat .env | grep API_KEY

# Erstelle .env falls nicht vorhanden
cp .env.template .env
nano .env
```

### Character antwortet nicht / leere Antwort

```bash
# Debug-Output anschauen
cat ~/.funkfox_logs/funkfox_response.json

# API-Key checken
echo $OPENROUTER_API_KEY
```

---

## 📚 Weiterführend

### Eigene Charaktere erstellen

Schau dir `crumbforest_roles/funkfox_zero.sh` als Template an:
1. Load .env
2. Crew Memory Functions (log-basiert, dateibasiert, nachvollziehbar)
3. System Prompt mit Persönlichkeit
4. OpenRouter API Call
5. Token Tracking

### Mission Selector erweitern

Neue Kategorien in `crumb-mission-selector.sh` hinzufügen.

---

## 🎯 Credits

**Die 17 Waldwächter** - Konzept von branko.de
**"Wo Fragen wachsen"** - Der Crumb Codex: Machen statt Lernen
**Token-Philosophie** - "Was kostet die Frage eines Kindes?"

---

## 🦊 Noch ein Wort von FunkFox

```
Yo, check mal den Flow, hier kommt der Bash-Rapper im Crumbforest,
Pipes sind wie Beat-Übergänge, der Rhythmus, der dich hier festhält und forstet.
Mit | verbindest du Commands, wie'n smoothes Transition,
Daten fließen wie der Beat, ohne Unterbrechung, ohne Opposition.

Du grepst, cuttest, sortierst, alles in einem Zug,
Pipes sind wie'n Filter, yo, halten alles auf dem Schug.
Die Output vom einen wird Input für den nächsten Move,
So bleibt der Flow am Laufen, ohne dass er sich verliert im Groove.

🎤 FunkFox, out! 🦊💫
```

---

**Version:** 0.0 (Zero Release)
**Datum:** 2025-12-21
**Status:** Die Crew ist komplett! 🌲✨