# Crumbcore – Crew Onboarding v0.1

**Ziel:** Alle Rollen (FunkFox, Bugsy, SnakePy, DumboSQL, CrabbyRust, PepperPHP, Schnippsi, Deepbit, Taube, Schraubär…) sauber an den Kern andocken: identisch startbar, messbar, kindgerecht, offline‑fähig.

---

## 0. Prinzipien

* **Herz‑Freigabe zuerst:** Kein auton. Handeln ohne namentliche Freigabe.
* **Offline‑First:** Seeds/Defaults, später Cloud.
* **Beweis statt Behauptung:** Jeder Output hat Herkunft/Beleg.
* **Kostenmeter:** Sichtbare Token‑/Zeit‑Kosten.
* **Einfacher Bus:** Eine gemeinsame „Sprache“ für Messages.

---

## 1. Ordnerstruktur (Vorschlag)

```
/opt/crumbcore/
  bus/                   # MQTT/UDP/TCP-Brücken
  roles/                 # alle Rollen als Unterordner
    funkfox/
    bugsy/
    snakepy/
    dumbosql/
    crabbyrust/
    pepperphp/
    schnippsi/
  policy/
    whitelist_topics.txt
    block_keywords.txt
  seeds/                 # Offline-Seeds (Texte, Antworten, Reime, Beispiele)
  logs/
    crumbcore.log        # zentraler, zeilenbasierter Log
  etc/
    crumbcore.env        # gemeinsame ENV
```

> Hinweis: Rollen dürfen außerhalb liegen; jede Rolle erhält aber einen **symlink** nach `/opt/crumbcore/roles/<name>` und liest gemeinsame ENV aus `etc/crumbcore.env`.

---

## 2. Crew‑Rollen‑Vertrag (CRC‑1.0)

**Zweck:** Einheitliche Schnittstelle pro Rolle – egal ob Bash, Python, PHP, Rust.

**Pflicht‑Kommandos / Endpunkte**

* `--health`  → Exit 0 + JSON: `{ "ok":true, "role":"funkfox", "version":"0.3" }`
* `--about`   → Kurzprofil (Name, Kinderschutz, Seeds, Modelle)
* `--act`     → Hauptaktion (Parameter via CLI/JSON)
* `--policy`  → aktive Whitelist/Blocklist anzeigen
* `--cost`    → letzte Schätzung `{tokens, est_eur, duration_ms}`

**JSON‑I/O‑Schema (`CRCMessage v1`)**

```json
{
  "role": "funkfox",
  "mode": "rap|teach|echo",
  "topic": "regenbogen",
  "req_id": "uuid",
  "context": {"lang":"de","kid_safe":true},
  "input": {},
  "output": {"text":"...", "lines":16},
  "evidence": ["seed:basis_v1","llm:openrouter:4o"],
  "cost": {"tokens": 312, "est_eur": 0.004},
  "approval": {"by":"NAME","time":"ISO8601"}
}
```

---

## 3. Event‑Bus (leichtgewichtig)

**MQTT‑Topics (empfohlen):**

* `crumb/req/<role>` → Requests (Payload: `CRCMessage v1` ohne `output`)
* `crumb/res/<role>` → Responses (Payload: vollständiges `CRCMessage v1`)
* `crumb/status/<role>` → Health/Heartbeat `{ok, version, ts}`
* `crumb/audit` → nur Metadaten/Costs

**UDP‑Chant (optional, Workshop):** Multicast `239.1.1.1:5005` – nur Kurz‑Refrain (4 Zeilen), keine PII.

---

## 4. Crumbcore‑Supervisor (prozessneutral)

Minimaler Supervisor ruft Rollen an, sammelt Kosten, schreibt Audit.

### `crumbcore_supervisor.sh` (Skizze)

```bash
#!/usr/bin/env bash
set -euo pipefail
ROLE="$1"; shift || true
REQ_JSON="${1:-}"  # optional JSON, sonst stdin
BIN="/opt/crumbcore/roles/${ROLE}/${ROLE}_hardened.sh"
[[ -x "$BIN" ]] || { echo "role bin missing"; exit 3; }
REQ="${REQ_JSON:-$(cat)}"
# Aufruf
OUT="$($BIN --act 2>/dev/null <<<"$REQ")"
# Audit (Zeile)
echo "$(date -Is)\t$ROLE\t$(echo "$OUT" | jq -r '.cost.est_eur // 0')" >> /opt/crumbcore/logs/crumbcore.log
printf '%s' "$OUT"
```

---

## 5. systemd‑Templates

**Service:** `/etc/systemd/system/crumb-role@.service`

```ini
[Unit]
Description=Crumb Role %i
After=network-online.target

[Service]
Type=simple
EnvironmentFile=/opt/crumbcore/etc/crumbcore.env
WorkingDirectory=/opt/crumbcore/roles/%i
ExecStart=/opt/crumbcore/roles/%i/%i_hardened.sh --health-loop
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

**Timer (Heartbeat):** `/etc/systemd/system/crumb-role-heartbeat@.timer`

```ini
[Unit]
Description=Heartbeat for %i

[Timer]
OnBootSec=30
OnUnitActiveSec=60
Unit=crumb-role-heartbeat@%i.service

[Install]
WantedBy=timers.target
```

**Heartbeat‑Service:** `/etc/systemd/system/crumb-role-heartbeat@.service`

```ini
[Service]
Type=oneshot
EnvironmentFile=/opt/crumbcore/etc/crumbcore.env
ExecStart=/opt/crumbcore/roles/%i/%i_hardened.sh --health | \
  mosquitto_pub -l -t crumb/status/%i
```

> macOS: `launchd`‑Plist analog; Docker: `HEALTHCHECK` + `cron`.

---

## 6. HTTP‑Brücke zur CrumbAPI

**Webhook‑Skeleton (FastAPI/CakePHP geht auch):**

* `POST /crumbcore/act/<role>` → Body: `CRCMessage v1` (ohne `output`)
* `GET  /crumbcore/status` → Liste aller Rollen + ok/version
* `GET  /crumbcore/policy` → aktive Whitelist/Blocklist

Antwort: `CRCMessage v1` (mit `output`, `cost`, `approval`)

---

## 7. Rolle exemplarisch: FunkFox

**Bin:** `/opt/crumbcore/roles/funkfox/funkfox_hardened.sh`
**Erfüllt CRC‑1.0:** `--health --about --act --policy --cost`
**Seeds:** `/opt/crumbcore/seeds/funkfox.txt` (symlink)
**Policy:** nutzt `/opt/crumbcore/policy/*.txt`

**Beispiel‑Request (`CRCMessage v1`)**

```json
{
  "role":"funkfox",
  "mode":"rap",
  "topic":"regenbogen",
  "req_id":"b3b1-…",
  "context":{"lang":"de","kid_safe":true},
  "input":{}
}
```

**Beispiel‑Response (gekürzt)**

```json
{
  "role":"funkfox",
  "output":{"text":"…16 Zeilen…","lines":16},
  "cost":{"tokens":320,"est_eur":0.004},
  "evidence":["seed:basis_v1"],
  "approval":{"by":"Mentor","time":"2025-09-25T19:59:00+02:00"}
}
```

---

## 8. Sicherheit & Kinderschutz

* **PII‑Gate:** Jede Rolle muss `--scrub` akzeptieren → PII‑Ersatz (`[redacted]`).
* **Blocklist vorrangig vor Seeds & LLM.**
* **Freigabe‑Token:** Kleine Einmal‑Tokens („Herz“), die der Supervisor an Antworten anhängt.

---

## 9. Kosten‑/Ressourcen‑Metriken

* `duration_ms`, `cpu_ms`, `mem_peak_mb`, `tokens_in/out`, `est_eur`
* Export: MQTT `crumb/audit` + Zeilenlog `/opt/crumbcore/logs/crumbcore.log`

---

## 10. Onboarding‑Checkliste (pro Rolle)

1. Binär/Script liegt unter `roles/<name>/<name>_hardened.*` und ist **executable**.
2. `--health` gibt gültiges JSON.
3. `--about` enthält Version, Seeds, Policy‑Pfad.
4. `--act` kann `CRCMessage v1` von stdin lesen.
5. Block/Whitelist greift (Testfälle).
6. Offline‑Seed funktioniert.
7. Kostenmeter sichtbar.
8. MQTT‑Status sendet ok/version.
9. Audit‑Log schreibt Zeile.
10. Ein manueller Freigabe‑Token wird korrekt angehängt.

---

## 11. Schnellstart (Demo‑Pfad)

```bash
sudo mkdir -p /opt/crumbcore/{roles,policy,seeds,logs,etc}
cp topic_whitelist.txt /opt/crumbcore/policy/whitelist_topics.txt
cp block_keywords.txt /opt/crumbcore/policy/block_keywords.txt
cp bars_seed.txt /opt/crumbcore/seeds/funkfox.txt
ln -s /opt/crumb/fox /opt/crumbcore/roles/funkfox   # oder echtes Verzeichnis

# Health Probe (Supervisor)
echo '{"role":"funkfox"}' | /opt/crumbcore/crumbcore_supervisor.sh funkfox
```

---

## 12. Nächste Schritte

* `CRC‑1.0` in README festschreiben + kurze Testsuite (`crc_check.sh`).
* Zwei weitere Rollen migrieren (Bugsy, SnakePy) → **End‑to‑End** über MQTT + Webhook.
* A4‑Cheatposter „Crew → Crumbcore“ (für Workshops) – mit QR zu `--about` jeder Rolle.

> **Leitlinie:** *So wenig Magie wie möglich, so viel Klarheit wie nötig.*
