konzept vertraulich owner: matus

brainversum: Second-Brain-Konsum für TuxAmetrics

Second-Brain-Tool brainversum (C:\dev\brainversum, eigenständiges Werkzeug, kein Zwirn-Plattformprodukt — siehe dessen guidelines/adr/0006-kein-zwirn-plattform-produkt.md) macht Architekturregeln/Doku programmatisch abfragbar, z.B. regeln_fuer_kontext (deterministischer Trigger-Abgleich auf Dateipfad/Code-Ausschnitt, kein Volltext-Leck — siehe guidelines/adr/0024-trigger-basierte-kontext-freigabe.md und guidelines/adr/0026-zwirn-konsum-http-und-mcp.md im brainversum-Repo). Entwurfsstand: --vault bei brainversum mcp und die HTTP-Route POST /api/v1/sources/{alias}/regeln-fuer- kontext sind dort noch nicht gebaut, nur konzipiert.

Infrastruktur laut Alcatraz-Backlog ("Brain-Dreiklang"): tuxametrics-vm (VMID 107, Runtime, hält den brainversum-node) + tuxametrics-dev-vm (VMID 108, liest per gateway-mcp mit genau einem Peer) — Firewall-Paar bereits erlaubt (ADR-0007 in Alcatraz).

Wichtig für dieses Projekt: vor jeder Umsetzung den Regulatorik-Guard beachten (TUXAMETRICS_REGULATORIK_EINSTUFUNG/TUXAMETRICS_PILOT_BETRIEBSMODUS müssen UNGEKLAERT bleiben) — ein brainversum-Deployment darf diese Variablen nicht versehentlich überschreiben oder deren Prüfung umgehen.

Offen, Entscheidung liegt bei diesem Projekt: ob/wie/wann brainversum hier tatsächlich deployt und in CI/Agenten eingebunden wird — keine zentrale Vorgabe aus brainversum oder Alcatraz. Läuft ohnehin frühestens nach dem App-Deployment selbst (siehe tuxametrics-vm, "macht bewusst eine andere Session", Alcatraz-Backlog).

Stand 2026-08-26: Quelle deployt, Föderation bewusst nicht

Die Entscheidung „ob" ist getroffen und umgesetzt — die Quelle läuft. Auf tuxametrics-vm stehen drei Container (tuxametrics-brainversum-ingest/-web/-mcp, Web 8135, MCP 8136) mit genau einer Quelle: der Doku dieses Repos, 56 kuratierte Markdown-Dateien. Umfang, Auswahlbegründung und Betrieb: ../../brainversum/README.md, Eintrag in der Service-Landschaft.

Der Regulatorik-Guard ist unberührt, wie oben verlangt: die drei Services haben überhaupt keinen environment:-Block, setzen also weder TUXAMETRICS_REGULATORIK_EINSTUFUNG noch TUXAMETRICS_PILOT_BETRIEBSMODUS. Nach dem Deploy geprüft — beide stehen in der .env der VM und im laufenden laborauswertung-service weiterhin auf UNGEKLAERT.

Was bewusst NICHT gebaut wurde — und was dafür noch fehlt

Der oben skizzierte „Brain-Dreiklang" ist damit nicht erfüllt. Er sieht auf tuxametrics-vm einen brainversum node vor (das /api/v1/*-Peer-Protokoll, brainversum-ADR-0015/-0016), den tuxametrics-dev-vm per gateway-mcp mit genau einem Peer liest. Gebaut ist stattdessen der Ein-Prozess-Spezialfall (web/mcp) — er bedient den Menschen und einen lokalen Agenten direkt, aber er ist kein Peer: gateway-mcp kann ihn nicht anbinden, weil /api/v1/sources fehlt.

Das ist Absicht und keine Lücke aus Versehen — die Föderation ist ausdrücklich als eigener Schritt zurückgestellt. Wer sie angeht, braucht einen vierten Service neben den bestehenden, kein Umbauen: dasselbe Image, derselbe Store (data_tuxametrics_brainversum, read-only genügt), nur ein anderes Kommando —

exec brainversum node --peer-id tuxametrics-vm --host 0.0.0.0 --port 8765 --registry-path "$REGISTRY"

— auf einem freien Host-Port (z.B. 8137). Zwei Punkte, die dabei zu klären sind und die schon jetzt feststehen:

Alias-Kollision. Die zentrale Instanz führt bereits tuxametrics (Code-Wiki) und tuxametrics-doku (dieselben Dateien als lokaler :ro-Mount). Ein Gateway schlüsselt seine Backends nach Alias (brainversum-ADR-0017) — der Alias dieses Knotens kollidiert also. Naheliegend ist, den lokalen tuxametrics-doku-Mount dort zu entfernen und durch diesen Peer zu ersetzen; es sind dieselben Dateien.
Keine Authentifizierung. brainversum bringt keine mit, und das node-Protokoll ist ein reiner Lesepfad ohne Principal-Prüfung (Autorisierung über Prozessgrenzen ist laut brainversum-ADR-0016 ausdrücklich nicht Teil dieser Phase). Trägt der Peer-Port über das Homelab-Netz hinaus, ist das eine eigene Entscheidung — hier liegt ausschließlich Engineering-Doku und kein Patientenbezug.

Stand 2026-08-27: der Vault ist ein Build-Artefakt — befristet

Der Live-Sync von gestern ist nach einem Tag wieder abgebaut. Nicht weil er nicht funktionierte — er lief —, sondern weil er eine Frage beantwortete, die dieses Repo gerade nicht mehr stellt.

Was jetzt gilt. Der kuratierte Markdown-Baum wird zur Build-Zeit ins Image kopiert (COPY --from=docs in ../../brainversum/Dockerfile, Build-Context docs: ./brainversum-docs), zusammen mit sources.yaml. Der Ingest ist ein Init-Container (brainversum apply + brainversum ingest, dann Exit 0, restart: "no"); web und mcp warten per service_completed_successfully auf sein Ende. Weg sind: drei :ro-Bind-Mounts, der --vm-Zweig von scripts/brainversum-quelle-sync.sh (der zweite Übertragungsweg neben dem Deploy), der 300-Sekunden-Poll und ein dauerhaft laufender Prozess.

Warum. Die Doku dieses Repos ändert sich nicht mehr täglich — die Phase, in der stündlich neue ADRs und Backlog-Dateien entstanden, ist vorbei. Damit ist ihr Inhalt dasselbe wie dist/ beim UI-Service oder ein JAR bei den Quarkus-Services: ein lieferbares Artefakt. Aktualität = Stand des letzten Deploys. Niemand pollt ein JAR, und niemand pflegt für ein JAR einen zweiten Übertragungsweg neben dem Deploy. Ein Live-Sync auf statischen Inhalt ist kein zusätzlicher Komfort, sondern ein zweiter Mechanismus, der auseinanderlaufen kann: bis gestern konnte die VM einen Doku-Stand tragen, den kein Image und kein Commit belegte.

Was das kostet — ehrlich benannt. Eine Doku-Änderung wirkt jetzt erst nach Build und Deploy, nicht mehr binnen fünf Minuten. Und die Frische-Ampel entfällt: brainversum daemon schreibt je Lauf eine frische.json (brainversum-ADR-0030), brainversum ingest nicht — und sie wäre hier falsch, weil Frische.veraltet() an einem Intervall hängt, das es nicht mehr gibt. Ohne Loop liefe jeder Stand binnen Minuten auf „rot" und behauptete bis auf die Startseite einen Ausfall, den es nicht gibt. Der Init-Container räumt die Datei deshalb aktiv weg; GET /health/frische meldet für diese Quelle folgerichtig 503 („kein Herzschlag ist kein Erfolg"). An ihre Stelle tritt die Frage, die zu einem Artefakt passt: welcher Stand steckt im Image (TUXAMETRICS_DOCS_GIT_SHA).

Offen: wann lohnt sich Live-Sync wieder?

Diese Vereinfachung ist befristet und soll zurückgenommen werden, sobald einer der folgenden Punkte eintritt. Wer einen davon beobachtet, hat damit die Begründung für den Rückbau in der Hand — er ist klein: additional_contexts/COPY gegen :ro-Mount tauschen, ingest gegen daemon --all --intervall N tauschen, depends_on zurück auf service_started, restart zurück auf unless-stopped, und den --vm-Zweig aus der Historie dieses Skripts zurückholen.

Die Doku ändert sich wieder häufig. Faustregel: mehr als ein oder zwei Deploys pro Woche, die nur wegen Doku-Änderungen stattfinden. Dann kostet das Artefakt-Modell mehr, als es spart.
Es gibt echtes Online-Editing. brainversum kann das bereits (Editier-Schreibpfad, brainversum-ADR-0019) — hier ist es abgeschaltet, weil die Wahrheit dieser Dateien git ist. Wird das je gewünscht, ist ein Image-Mount ein Widerspruch in sich: man kann in eine Image-Schicht nicht sinnvoll schreiben.
Der Store wandert nach Neo4j. Dann ist der Graph kein Nebenprodukt eines Container-Starts mehr, sondern eine eigene, laufende Datenbank mit eigenem Lebenszyklus — und ein Ingest, der sie füttert, ist wieder ein Dienst statt eines Init-Schritts.

Punkt 2 und 3 sind der eigentliche Zielzustand; Punkt 1 ist der Rückfall, falls sich die Annahme über das Änderungstempo als falsch erweist. Die Föderation (Abschnitt oben) ist von alldem unberührt — ein node-Service liest denselben Store und interessiert sich nicht dafür, wer ihn gefüllt hat.