km/docs/konzept.md

# 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.