CrumbCodex-v.0.0/waldmitte/crumbcore/crumbcore_onboarding.md

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)

{
  "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)

#!/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

[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

[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

[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)

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

Beispiel‑Response (gekürzt)

{
  "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)

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.