spine/km: das Zuhause fuer den Wissensdienst

Andreas: "lass uns ein repo in spine machen, fuer das knowledge
management thema. Darin sollen images gebaut werden und ein compose und
charts, sodass daraus dann km.lan betrieben werden kann. alles zu dem
thema kann dann da rein wandern, als doku und als tickets."

Vier Verzeichnisse: image/ fuer den Dienst, deploy/ fuer den Betrieb
heute (LXC und podman ueber oci), chart/ fuer den Betrieb spaeter (hive
und k8s), docs/ fuer Konzept und Entscheidungen.

Compose und Chart sind ausdruecklich gleichrangig und beschreiben
DENSELBEN Dienst. Beim Teamspace hat genau das getragen: Das hive-Chart
war die Vorlage, und seine drei teuer gelernten Einstellungen liefen in
der 42i ohne eine einzige eigene Entdeckung durch. Driften sie, wird der
Umzug nach k8s ein Neubau statt eines Wechsels.

docs/konzept.md fuehrt spine/core#8 zusammen: Andreas Entwurf woertlich,
dazu die Praezisierungen aus den Kommentaren -- Konzepte als eigene
Kategorie, Projekt als zweite Achse, und dass ein Eintrag ohne
Projekt-Tag der Organisation gehoert statt keinem. Mit den offenen
Punkten, die noch niemand entschieden hat.

Das README benennt zwei Dinge, die man sonst spaeter diskutiert: warum
das Repo von der spine-Konvention abweicht (Image und Chart liegen sonst
zentral -- km ist eigene Entwicklung, kein fertiges Upstream-Produkt),
und dass hive den Dienst verwenden kann, weil er nichts 42i-spezifisches
eingebaut hat.

README.md

@@ -0,0 +1,81 @@
+# km — Knowledge Management
+
+Der gemeinsame Wissensdienst: **eine** Ablage für das, was Agenten und Menschen
+über die 42i wissen — statt je Werkzeug eine eigene, die niemand sonst sieht.
+
+Betrieben wird er als `km.lan`. Dieses Repo trägt alles dazu: das Image, die
+Betriebsform für heute (compose), die für später (Chart), die Konzepte und die
+Tickets.
+
+> **Stand: Entwurf.** Es läuft noch nichts. Was hier steht, ist der Bauplan aus
+> [spine/core#8](https://git.42i.org/spine/core/issues/8), zusammengeführt und
+> fortgeschrieben — siehe [docs/konzept.md](docs/konzept.md).
+
+## Warum das gebraucht wird
+
+Nicht vermutet, sondern gemessen. Am 2026-09-01 suchte der XO-Gesprächsfaden
+nach fehlenden Übersetzungsschlüsseln, während die Messung dazu seit Stunden
+vorlag — dieselbe Persona, zwei Körper, kein gemeinsames Gedächtnis. Am selben
+Abend kamen drei weitere Fälle dazu, alle bei einem Agenten, der die Regel
+*„erst suchen, dann bauen"* selbst geschrieben hatte:
+
+| Fall | Was gefehlt hat |
+|---|---|
+| Eine Vorgabe (`oci`) übersehen, obwohl die Seite offen war | „Für *diese Art* Aufgabe gibt es hier eine Vorgabe" — **vor** dem Bauen |
+| Im falschen Verzeichnis gebaut, das richtig aussah | „Diese Datei ist nicht die Quelle" — beim Anfassen |
+| Dasselbe Problem zweimal gelöst, zwei Tickets dafür | „Daran arbeitet gerade jemand" — beim Anlegen |
+
+Alle drei sind **nicht** durch bessere Dokumentation lösbar: Die Information
+existierte jedes Mal, korrekt und auffindbar. Was fehlte, war die Zustellung im
+richtigen Moment. Das ist der Unterschied zwischen einem Index und einem
+Bibliothekar — der Index beantwortet Fragen, der Bibliothekar sagt, welche Frage
+man hätte stellen sollen.
+
+## Was wohin gehört
+
+| Verzeichnis | Inhalt |
+|---|---|
+| `image/` | Das Container-Image: API, Ablage, MCP-Endpunkt, prüfende Schreibfunktion |
+| `deploy/` | **Heute:** LXC mit podman-compose, wie jeder andere Dienst im Haus (`oci`) |
+| `chart/` | **Später:** Helm-Chart, damit hive denselben Dienst fahren kann |
+| `docs/` | Konzept, Entscheidungen, Betriebswissen |
+
+Die Aufteilung ist Absicht und folgt dem, was beim Teamspace funktioniert hat:
+Compose und Chart beschreiben **denselben** Dienst mit denselben Bildern und
+Einstellungen. Wer eines ändert, ändert das andere mit — sonst driften sie, und
+der Umzug nach k8s wird ein Neubau statt eines Wechsels.
+
+## Verhältnis zu hive
+
+**hive kann diesen Dienst verwenden.** Er ist bewusst nicht 42i-spezifisch: Was
+ihn kennt, sind Namespaces (`42i`, `familie`, …) und Projekt-Tags — beides
+Konfiguration, keine eingebaute Annahme.
+
+Für hive ist `chart/` der Einstieg; `deploy/` ist die Übergangsform der 42i,
+solange dort kein k8s produktiv läuft. Die Rollen sind dieselben wie beim
+Teamspace: hive baut Charts und k8s, die 42i fährt bis dahin LXC und podman —
+mit **demselben Image und demselben Bootstrapping**, damit die Erfahrung
+übertragbar bleibt.
+
+Anschluss auf hive-Seite: [hive/core](https://git.42i.org/hive/core) —
+insbesondere die Bibliothekars-Rolle (dort *Bob*), aus der dieser Dienst
+hervorgegangen ist.
+
+## Verhältnis zur spine-Konvention
+
+In spine liegen Images sonst zentral in `spine/images` und Charts in
+`spine/charts`, benannt nach der Fähigkeit. Hier liegt beides beisammen, weil km
+kein fertiges Upstream-Produkt ist, sondern **eigene Entwicklung** — API,
+Ablageform und die prüfende Schreibfunktion entstehen hier, und sie gehören zu
+den Konzepten und Tickets, die sie begründen.
+
+Ist der Dienst reif und stabil, kann das Image nach `spine/images` und das Chart
+nach `spine/charts` wandern; dieses Repo behielte Konzepte und Vorgänge. Das ist
+eine Entscheidung für später, keine Vorfestlegung.
+
+## Tickets
+
+Alles zum Thema gehört hierher — auch das, was heute noch in
+[spine/core#8](https://git.42i.org/spine/core/issues/8) und
+[spine/core#1](https://git.42i.org/spine/core/issues/1) steht. Die beiden
+bleiben als Ursprung stehen und verweisen hierher.

chart/README.md

@@ -0,0 +1,13 @@
+# chart — der Betrieb für später
+
+Helm-Chart, damit **hive** denselben Dienst fahren kann.
+
+**Noch leer.** Wenn es entsteht, gilt das Muster von `spine/charts`: ein
+`values.yaml`, das den Preis benennt statt ihn zu verstecken, und Kommentare,
+die sagen *warum* eine Einstellung so ist — nicht nur *dass* sie so ist. Das
+`team`-Chart ist dafür die Vorlage; seine drei teuer gelernten Einstellungen
+haben beim Nachbau in der 42i ohne eine einzige eigene Entdeckung getragen.
+
+Das Chart ist nicht die Zweitverwertung des Compose, sondern gleichrangig:
+`deploy/` ist die Übergangsform der 42i, solange dort kein k8s produktiv läuft.
+Beide beschreiben denselben Dienst mit denselben Images und Einstellungen.

deploy/README.md

@@ -0,0 +1,24 @@
+# deploy — der Betrieb für heute
+
+`km.lan` als LXC mit podman-compose, wie jeder andere Dienst im Haus.
+
+**Noch leer.** Wenn es soweit ist, gehört hierher eine `compose.yml` nach dem
+Muster von `info/deployment/team/` — und der Betrieb läuft über **`oci`**
+(`42i-oci`), nicht über eine eigene systemd-Unit. Das ist die Hausvorgabe; ich
+habe sie beim Teamspace übersehen und eine eigene Unit gebaut, die dem Muster
+zufällig fast glich.
+
+Was dort außerdem gelernt wurde und hier gelten wird:
+
+- **Rechte am Volume.** Läuft der Prozess im Image unter einer eigenen UID,
+  muss das Datenverzeichnis ihr gehören. Im Chart erledigt das `fsGroup`; bei
+  podman gibt es niemanden, der es von selbst tut, und der Fehler zeigt sich
+  erst bei der ersten Schreiboperation — wortlos.
+- **Konfiguration in die Datenbank oder ins Volume, nicht in eine Datei im
+  Container.** Sonst ist jede Einstellung nach dem nächsten Neustart weg, und
+  es sieht aus, als wäre sie nie gemacht worden.
+- **Secrets aus OpenBao**, nie in der compose-Datei und nie in argv.
+
+Die compose-Datei und das Chart in `../chart/` beschreiben **denselben** Dienst.
+Wer eines ändert, ändert das andere mit — sonst driften sie, und der Umzug nach
+k8s wird ein Neubau statt eines Wechsels.

docs/konzept.md

@@ -0,0 +1,108 @@
+# Konzept
+
+Zusammengeführt aus [spine/core#8](https://git.42i.org/spine/core/issues/8)
+(Entwurf und vier Kommentare, 2026-09-01). Der Entwurf steht wörtlich, die
+Präzisierungen darunter.
+
+## Der Entwurf im Original
+
+> nehmen wir https://km.lan. `https://km.lan/api/v1/` bekommt ein paar
+> endpunkte: write, read, search, summary
+>
+> das alles in namespaces („42i", „familie", …). Zugriff per RBAC,
+> `namespace:verb`, mit Token → role → grant
+>
+> es wird alles als md auf platte gespeichert, in den kategorien mission,
+> knowledge, status. In den passenden verzeichnissen. in jedem verzeichnis gibt
+> es eine `index.md` mit dem verzeichnis. Jedes write schreibt die index.md um.
+> Sortiert ist die index.md nach datum. Neuste Änderungen oben. Bei History
+> basierten Sachen ist der jeweils gültige Kurs und Status oben zusammengefasst
+> und veraltete einträge sind als depricated markiert.
+>
+> Die summary funktion gibt ein md mit einem Kapitel pro Kategorie und fasst die
+> Inhalte aus den index.md zusammen. jeder eintrag hat einen autor und ein datum.
+>
+> km.lan selber ist ein image. Das wird in spine/images angelegt und wird ein
+> übergreifender service. die ablage ist ein volume. Gehosted in einem lxc, darin
+> ein podman service in /srv wie aktuell alle anderen auch. Hive macht daraus dann
+> irgendwann ein K8s Chart Ding, aber das ist dann hive. Hier machen wir erstmal
+> den fachlichen prototyp und schauen ob das geht.
+>
+> Dann noch einen mcp endpoint. Den hängen wir in den aggregator rein, oder noch
+> prominenter. Das muss zwingend proprietäre memory funktionen von claude oder
+> opencode ersetzen. also müssen wir die eingebauten tools abschalten.
+>
+> die write funktion muss dann ein llm aufrufen (url wird in der compose.yml
+> definiert, key aus openbao). der aufruf hat einen minimalen prompt, der
+> kategorisiert und gegen den aktuellen stand prüft, konflikte findet und meldet.
+> Bei Konflikten wird abgewiesen. Dann kann der Einreicher aber bewusst
+> übersteuern und force mitgeben. Dann wird diese Info als neuer gesicherter Stand
+> übernommen und ersetzt den alten stand (also update der doku oder
+> kurskorrektur). Neuer Status (Fortschrittsmeldung) fürs log geht auch ohne force.
+
+## Präzisierungen
+
+### Konzepte sind eine eigene Kategorie
+
+Genannt waren `mission`, `knowledge`, `status`. **Konzepte** gehören dazu und
+sind nicht dasselbe wie Wissen:
+
+| | Knowledge | Konzept |
+|---|---|---|
+| **Was** | wie etwas **ist** | wie etwas **gedacht** ist |
+| **Beispiel** | „`:low` ist ein Pool aus drei Quellen" | „Aufträge haben zwei Bestätigungsachsen" |
+| **Widerspruch dazu** | ein Irrtum, wird korrigiert | eine **Abweichung**, wird gemeldet |
+
+Der Unterschied trägt eine ganze Rolle: Ein Navigator prüft Umsetzung gegen
+Konzept. Läge das Konzept unter „Wissen", wäre jede Abweichung nur ein
+widersprüchlicher Fakt statt eines Befunds.
+
+### Projekt als zweite Achse — und was ohne sie gilt
+
+Namespaces trennen Mandanten (`42i`, `familie`). Innerhalb eines Namespace
+braucht es eine zweite Achse: `live`, `hive`, `spine`, `inka`, `infra`. Ein
+Eintrag gehört zu einem Projekt, aber ein Projekt hat Einträge in **allen**
+Kategorien. Das ist die Trennung aus 42i/intern#860: Owner-Pfad (genau einer,
+hart) gegen Tags (viele, weich).
+
+**Ein Eintrag ohne Projekt-Tag gehört der Organisation** — nicht keinem
+(Andreas, 2026-09-01):
+
+> „sonst könnte ja die 42i keine Einträge bekommen und dann sind wir wieder bei
+> Krücken wie in gitea, wo man orga tickets nicht an die orga hängen kann
+> sondern ein repo braucht. Und dann bauen wir core oder intern. Beides
+> Krücken."
+
+Die Ebenen sind also `42i/` (Sache der Organisation, gültig) und `42i/live/`
+(Sache des Projekts). Praktisch:
+
+| Aufruf | liefert |
+|---|---|
+| `summary(ns="42i")` | alles |
+| `summary(ns="42i", projekt="live")` | nur live |
+| `summary(ns="42i", projekt=None)` | **nur die Orga-Ebene** — Kurs, Mission, was über allen Projekten steht |
+
+Der dritte Fall ist der wichtige: Genau danach fragt ein Agent, der wissen will,
+was hier überhaupt gilt, bevor er in ein Projekt einsteigt.
+
+### Status braucht laufende Vorgänge, nicht nur Fakten
+
+Der dritte Beleg aus dem Ticket — zwei Agenten lösen dasselbe Problem und legen
+zwei Tickets an — ist mit Fakten allein nicht zu verhindern. Er verlangt, dass
+`summary` auch **offene Arbeit** kennt, nicht nur abgeschlossene. Ohne das
+beantwortet der Dienst „was gilt", aber nicht „woran arbeitet gerade jemand".
+
+## Offene Punkte
+
+- **Volltext oder Vektor?** Andreas: *„auf dem Volume muss das checkout liegen
+  … außerdem wäre eine volltext db (oder vektor db) gut."* Der vorhandene
+  Wissens-MCP nutzt Qdrant mit `bge-m3` über den LLM-Knoten — Erfahrung und
+  Kosten sind dort dokumentiert (`info/docs/lan/infra/wissens-mcp.md`).
+- **Verhältnis zum bestehenden `wissens_learn`.** Der legt Drafts in die
+  info-Basis, die ein Mensch promoten müsste — was niemand tut. Andreas:
+  *„das macht heute niemand. Ich wüsste nicht einmal, wo das liegt."*
+- **Welches LLM prüft die Schreibfunktion**, und was passiert bei Ausfall:
+  abweisen oder durchlassen? Ein Dienst, der ohne Modell nichts annimmt, ist
+  bei jedem Gateway-Ausfall stumm.
+- **Ablösung der eingebauten Memory-Funktionen** von Claude und opencode. Ohne
+  das bleibt die proprietäre Ablage der bequemere Weg.

image/README.md

@@ -0,0 +1,31 @@
+# image — der Dienst selbst
+
+Hier entsteht `git.42i.org/spine/km`: die API, die Ablage, der MCP-Endpunkt und
+die prüfende Schreibfunktion.
+
+**Noch leer.** Was hineingehört, steht in [../docs/konzept.md](../docs/konzept.md).
+Die Reihenfolge, in der es sinnvoll wächst:
+
+1. `read` und `search` über eine Ablage aus Markdown-Dateien — ohne die beiden
+   ist nichts nachprüfbar.
+2. `write` **ohne** LLM-Prüfung, aber mit Kategorie und Namespace. Ab hier ist
+   der Dienst benutzbar und kann die ersten Einträge aufnehmen.
+3. Die `index.md` je Verzeichnis, die jedes `write` fortschreibt.
+4. `summary` über die `index.md`.
+5. Die prüfende Schreibfunktion (LLM, Konflikte, `force`).
+6. Der MCP-Endpunkt.
+
+Die Reihenfolge ist nicht beliebig: Schritt 5 ist der einzige, der ein Modell
+braucht und ausfallen kann. Er kommt zuletzt, damit der Dienst vorher schon
+trägt — und damit man beim Abschalten der Prüfung sieht, was sie eigentlich
+verhindert hat.
+
+## Zwei Dinge, die beim Bauen schon feststehen
+
+**Benannt nach der Fähigkeit, nicht nach dem Produkt** — die Regel aus
+`spine/images`. `km` ist ein Versprechen auf Wissensverwaltung, keine Wette auf
+eine bestimmte Ablage oder Suchmaschine.
+
+**Die Ablage ist ein Volume, kein Datenbankgeheimnis.** Markdown auf Platte,
+lesbar ohne den Dienst. Wer nur nachsehen will, was gespeichert ist, soll dafür
+kein laufendes System brauchen.