Spec v0.4: Repository-Trennung Tool/Vault sauber dokumentiert

- 2 Repos: Tool-Repo (dieses Repo, Code) + Vault-Repo (Daten, separat) - § 1: expliziter Hinweis auf zwei Repositories - § 3: neue Tabelle 'Was es tut - und wo es lebt' - § 4: Architektur-Tabelle um Repo-Spalte erweitert - § 5: in 5.1 Vault-Repo und 5.2 Tool-Repo aufgeteilt - § 12: QMD-Realitaetstest dokumentiert (verifiziert 2026-09-05) - § 15: Bau-Reihenfolge in Sub-Phasen 1a/1b/1c (Tool-Code, Vault-Init, Indexer+Webapp) - § 16: 3 neue Klaerungs-Eintraege (Repository-Trennung, Vault-Pfad, QMD-Realitaet) - § 17: 3 neue offene Punkte (Vault-Init-Skript, Deployment-Mechanik, Vault-Pfad-Discovery)
2026-09-05 10:41:22 +02:00
1 parent 15bb77d7a8
commit cee1f4c8f7
@@ -1,18 +1,20 @@
-# Mind-o-Mat — Spezifikation v0.3
+# Mind-o-Mat — Spezifikation v0.4

-> Stand: 2026-09-05 — Konzept-Phase erweitert (Cloud, Mobile, PWA, Minimax).
-> Vorherige Version: v0.2 vom 2026-09-05. Mobile- und KI-Integration ergänzt.
+> Stand: 2026-09-05 — Konzept-Phase abgeschlossen + Vault/Tool-Trennung dokumentiert.
+> Vorherige Version: v0.3 vom 2026-09-05. QMD-Realität verifiziert, Repository-Trennung ergänzt.
 > Diese Spec ist verbindlich für die Implementierung. Änderungen werden in der Klärungen-Sektion (§ 16) dokumentiert.

 ## 1. Zweck

-Lokales Second-Brain-System für einen Obsidian-kompatiblen Markdown-Vault mit Cloud-Sync und Mobile-Zugriff. Es nimmt drei Dinge ab:
+Lokales Second-Brain-System für einen Obsidian-kompatiblen Markdown-Vault mit Cloud-Sync und Mobile-Zugriff. Es nimmt vier Dinge ab:

 - **Wissen wiederfinden**, auch wenn das exakte Wort nicht mehr einfällt (Bedeutungssuche).
 - **Dem Wissen vertrauen können**, weil Widersprüche, Duplikate und veraltete Stände sichtbar markiert werden.
 - **Überblick behalten** über ein wachsendes Wissensgebilde über eine Graph-Ansicht mit Clustern und Verbindungen.
 - **Von überall arbeiten** — Desktop, Mobile, geteiltes Wissen.

+**Wichtig: zwei Repositories.** „Mind-o-Mat" ist der **Name des Tools** (Code-Basis, dieses Repo). Der **Vault** mit den Notizen lebt in einem **separaten Repo**. Details in § 2.
+
 ## 2. Fähigkeiten (was das System können muss)

 | # | Fähigkeit | Was es konkret tut |
@@ -28,11 +30,22 @@ Lokales Second-Brain-System für einen Obsidian-kompatiblen Markdown-Vault mit C

 ### Was es tut

- **Cloud-Sync** über gitea (`git.orfel.de/Jannik/Mind-o-Mat`). Vault liegt auf dem Desktop, in gitea als Remote, auf Mobile über die PWA.
+- **Cloud-Sync** über gitea. **Der Vault** synct zu seinem eigenen gitea-Repo (z. B. `git.orfel.de/Jannik/Mind-o-Mat-Vault`). Auf Mobile über die PWA.
 - **Mobile-Client** auf **Android** (PWA, installierbar). Windows-Browser funktioniert genauso. **Kein iOS.**
- **Externe KI** über den **Minimax TokenPlan** für Wiki-Pflege und Ingest-Operationen.
+- **Externe KI** über den **Minimax TokenPlan** (HTTP-API) für Wiki-Pflege und Ingest-Operationen.
 - **Eigene PWA** statt Obsidian direkt — Obsidian-ähnlich (Markdown + Frontmatter + Wikilinks + Graph), aber selbstgebaut, kostenlos, self-hosted.

+### Was es tut — und wo es lebt
+
+| Komponente | Was | Wo (welches Repo) |
+|---|---|---|
+| **Tool-Code** | Webapp, Indexer, Ingest, sync.mjs, npm-Pakete | **`C:\GitHub\Mind-o-Mat`** (dieses Repo, Code-Basis) |
+| **Vault-Daten** | Notizen, Wiki, Konfig, Logs | **Vault-Repo** (z. B. `C:\GitHub\Mind-o-Mat-Vault`) |
+| **Vault-Sync** | git-Operationen, push zu gitea | **Vault-Repo** (`sync.mjs` läuft im Vault) |
+| **PWA** | Browser-App, Mobile, Graph, Editor | Wird **vom Tool-Repo** gebaut, **im Vault-Repo** deployed (oder als statische Files) |
+| **QMD** | Lokale Suche, ~2 GB Modelle | Installiert im **Vault-Repo** (operiert auf den Notizen) |
+| **Minimax-API** | Externe KI für Wiki-Pflege | Aufgerufen **vom Vault-Repo** (über Ingest-Skript) |
+
 ### Was es NICHT tut

 - **Kein iOS-Client** (kein PWA-Wrapper für iOS, kein Swift).
@@ -41,22 +54,24 @@ Lokales Second-Brain-System für einen Obsidian-kompatiblen Markdown-Vault mit C
 - **Kein automatisches Generieren von Notizen.** Du schreibst selbst, das System organisiert.
 - **Kein Obsidian als Editor.** Stattdessen die eigene PWA (sonst Lizenz- und UX-Inkonsistenz).

-## 4. Architektur (5 Bausteine)
+## 4. Architektur (5 Bausteine + 2 Repos)

-| # | Baustein | Zweck | KI drin? |
-|---|---|---|---|
-| 1 | **Vault** | Markdown-Dateien als Single Source of Truth. Git-Repository mit gitea als Remote. | nein |
-| 2 | **Indexer** | Deterministisch: `readdir` → Frontmatter parsen → Wikilinks extrahieren → `landkarte.json` + beide `Index.md`. | nein |
-| 3 | **QMD** | Lokale Hybridsuche (BM25 + Vektor + LLM-Re-Ranking) über `@tobilu/qmd`. CLI + optional MCP-Server. | nein (lokale GGUF-Modelle) |
-| 4 | **Wiki** (Karpathy-Pattern) | Ingest pflegt Markdown-Seiten nach festen Regeln aus `10_Wiki/_Schema.md`. Ruft **Minimax** für Verstehens-Aufgaben auf. | ja (Minimax) |
-| 5 | **Webapp / PWA** | Liest `landkarte.json` + QMD-Such-API, rendert Graph **und ist gleichzeitig der Editor**. Installierbar als PWA auf Android. | nein |
+| # | Baustein | Zweck | KI drin? | Repo |
+|---|---|---|---|---|
+| 1 | **Vault** | Markdown-Dateien als Single Source of Truth. Git-Repository mit gitea als Remote. | nein | **Vault-Repo** |
+| 2 | **Indexer** | Deterministisch: `readdir` → Frontmatter parsen → Wikilinks extrahieren → `landkarte.json` + beide `Index.md`. | nein | **Tool-Repo** (Skript), läuft im **Vault-Repo** |
+| 3 | **QMD** | Lokale Hybridsuche (BM25 + Vektor + LLM-Re-Ranking) über `@tobilu/qmd`. CLI + optional MCP-Server. | nein (lokale GGUF-Modelle) | Installiert im **Vault-Repo** (operiert auf Vault-Inhalten) |
+| 4 | **Wiki** (Karpathy-Pattern) | Ingest pflegt Markdown-Seiten nach festen Regeln aus `10_Wiki/_Schema.md`. Ruft **Minimax** für Verstehens-Aufgaben auf. | ja (Minimax, im **Vault-Repo**) |
+| 5 | **Webapp / PWA** | Liest `landkarte.json` + QMD-Such-API, rendert Graph **und ist gleichzeitig der Editor**. Installierbar als PWA auf Android. | nein | **Tool-Repo** (Quellcode), läuft im Browser und liest aus **Vault-Repo** |

 **Sync-Mechanik:** Vault ist ein Git-Repo, `origin` zeigt auf gitea. PWA auf Mobile und Webapp auf Desktop pushen/pullen via `99_System/Skripte/sync.mjs`. Trigger manuell oder per Cron.

-## 5. Datenstruktur
+## 5. Datenstruktur (zwei Repos)
+
+### 5.1 Vault-Repo (Daten)

 ```
-C:\GitHub\Mind-o-Mat\
+C:\GitHub\Mind-o-Mat-Vault\
 ├── 00_Inbox\                 # Eingangskorb, unsortiert
 │   ├── Verarbeitet\          # nach Ingest, chronologisch
 │   │   └── YYYY-MM-DD\
@@ -65,22 +80,45 @@ C:\GitHub\Mind-o-Mat\
 ├── 10_Wiki\                  # von Ingest gepflegt
 │   ├── Index.md
 │   ├── _Schema.md
-│   ├── SPEC.md               # diese Datei
 │   └── Seiten\
 ├── 20_Projekte\              # aktive Initiativen
 ├── 90_Templates\             # Notiz-Vorlagen
 ├── 99_System\
-│   ├── Skripte\              # indexer.mjs, ingest.mjs, sync.mjs
-│   ├── Logs\                 # Ingest- und Sync-Protokolle
-│   ├── Cache\                # QMD-Embeddings, Zwischen-Caches
+│   ├── Skripte\              # indexer.mjs, ingest.mjs, sync.mjs (vom Tool deployed)
+│   ├── Logs\                 # Ingest- und Sync-Protokolle (gitignored)
+│   ├── Cache\                # QMD-Embeddings, Zwischen-Caches (gitignored)
 │   ├── Index.md              # Katalog, von Suchleiter zuerst gelesen
 │   └── Konfig.md             # zentrale Konfiguration (Settings)
+├── .qmd\                     # QMD-Index (gitignored)
 ├── CLAUDE.md                 # Brain-First-Suchleiter
-├── package.json
-├── .gitignore
-└── README.md
+├── README.md
+└── .gitignore
 ```

+### 5.2 Tool-Repo (Code) — dieses Repo
+
+```
+C:\GitHub\Mind-o-Mat\
+├── src\                      # Node.js-Quellcode
+│   ├── indexer.mjs           # Vault-Indexer (deterministisch)
+│   ├── ingest.mjs            # Vault-Ingest (LLM-pflichtig)
+│   └── sync.mjs              # Vault-Sync (gitea)
+├── webapp\                   # Vite + React + TypeScript
+│   ├── src\                  # UI-Code
+│   ├── public\               # PWA-Assets
+│   └── package.json
+├── bin\                      # CLI-Wrapper (z. B. `mindomat` / `mindomat-vault`)
+├── docs\                     # diese Spec, README, weitere Doku
+│   └── 10_Wiki\
+│       └── SPEC.md           # diese Datei
+├── package.json              # Tool-Pakete
+├── tsconfig.json
+├── README.md                 # Install-Anleitung für Vault-User
+└── .gitignore
+```
+
+**Kommunikation zwischen Tool und Vault:** Das Tool liest und schreibt in den Vault-Pfad (z. B. via `process.env.MINDOMAT_VAULT_PATH` oder Argument). Die Skripte werden **vom Tool-Repo ins Vault-Repo deployed** (z. B. nach `99_System/Skripte/`) oder direkt aus dem Tool-Repo aufgerufen.
+
 **Konfig.md** ist die zentrale Konfigurationsdatei im Vault. Beispiel:

 ```yaml
@@ -385,16 +423,21 @@ Quellen mit `status: konflikt` oder ⚠️-Veraltet bekommen automatisch eine Wa
 - **MCP-Server** optional für direkte Integration
 - Cache-Pfad: `99_System/Cache/` (aus `Konfig.md`)

+**Wichtig:** QMD wird im **Vault-Repo** installiert und operiert auf den Vault-Inhalten. Die Skripte (Indexer, Ingest) aus dem Tool-Repo rufen QMD im Vault auf.
+
 ### 12.4 QMD-Collections (Vorschlag)

 ```
-qmd collection add C:\GitHub\Mind-o-Mat\00_Inbox      --name inbox
-qmd collection add C:\GitHub\Mind-o-Mat\01_Daily      --name daily
-qmd collection add C:\GitHub\Mind-o-Mat\10_Wiki       --name wiki
-qmd collection add C:\GitHub\Mind-o-Mat\20_Projekte   --name projekte
+cd <VAULT_PATH>
+qmd collection add 00_Inbox      --name inbox
+qmd collection add 01_Daily      --name daily
+qmd collection add 10_Wiki       --name wiki
+qmd collection add 20_Projekte   --name projekte
 qmd embed
 ```

+**Realitätstest (verifiziert am 2026-09-05):** QMD 2.8.3 läuft mit 3 Demo-Notizen, deutsche Umlaute und Wikilinks funktionieren, Hybrid-Query liefert korrekte Reihenfolge (Score 1.0 für direkten Treffer, 0.38 für verlinkte, 0.25 für entfernte). 3 GGUF-Modelle (~2.15 GB) installiert sich automatisch beim ersten Lauf.
+
 (Endgültige Konfiguration beim Bauen.)

 ## 13. Webapp / PWA
@@ -473,16 +516,27 @@ qmd embed

 ## 15. Bau-Reihenfolge (4 Phasen)

-### Phase 1: MVP (Erfolgskriterium: Graph sichtbar)
+**Reihenfolge der Schritte:** Erst das **Tool-Repo** bauen, dann mit dem Tool einen **Vault initialisieren**. So trennen wir Code-Entwicklung von Daten-Setup.

- Vault-Struktur anlegen (Ordner, .gitignore-Erweiterung)
- `package.json` mit Scripts (`index`, `ingest`, `dev`, `sync`)
- QMD installieren + Collections anlegen
+### Phase 1: Tool-Repo MVP
+
+**Sub-Phase 1a — Tool-Code:**
+- `package.json` mit Scripts (`build`, `dev`, `test`)
+- `tsconfig.json` für TypeScript
+- Tool-Quellcode-Struktur: `src/`, `webapp/`, `bin/`, `docs/`
+- README mit Install-Anleitung
+
+**Sub-Phase 1b — Vault-Initialisierung:**
+- Tool-Skript `init-vault` anbieten: `npx mindomat init <Pfad>`
+- Erstellt Vault-Struktur (Ordner, .gitignore, README, Konfig.md mit Defaults)
+- Optional: gitea-Remote setzen, erster Commit
+
+**Sub-Phase 1c — Indexer + Webapp:**
 - Indexer (Node.js, deterministisch) → `landkarte.json` + beide `Index.md`
+- QMD-Installations-Anleitung (manuell, einmalig)
 - Webapp v0.1: Force-directed Graph, liest `landkarte.json`
- gitea als Git-Remote, `sync.mjs` als Skript

-**Fertig wenn:** Webapp öffnet, zeigt deine Notizen als verbundenen Graph. Sync zu gitea funktioniert.
+**Fertig wenn:** Vault ist initialisiert, Indexer läuft, Webapp zeigt Notizen als Graph, gitea-Sync funktioniert.

 ### Phase 2: Wiki + Ingest

@@ -520,6 +574,9 @@ qmd embed

 | Datum | Wer | Frage / Stichwort | Antwort / Begründung |
 |---|---|---|---|
+| 2026-09-05 | User | Repository-Trennung | **zwei Repos**: Tool-Repo (Code, dieses Repo) + Vault-Repo (Daten, separates Repo). Daten-Repo synced zu gitea. Tool-Repo veröffentlicht Code. |
+| 2026-09-05 | User | Vault-Pfad | `C:\GitHub\Mind-o-Mat-Vault` |
+| 2026-09-05 | User | QMD-Realität lokal | verifiziert auf Test-Vault, 2.15 GB Modelle installiert, Hybrid-Query liefert Score 1.0 für direkten Treffer |
 | 2026-09-05 | User | Naming-Konvention | Pascal_Snake_Case, `-` nur in ISO-Datum |
 | 2026-09-05 | User | Wiki-Status-Sprache | Deutsch: neu, aktuell, konflikt, entwurf, archiv |
 | 2026-09-05 | User | Folder-Sprache | DE |
@@ -572,6 +629,14 @@ qmd embed
 | 13 | Minimax-API: exakte Endpoints, Request/Response-Format, Rate-Limits, Token-Kosten pro Operation | Phase 2, vor Ingest-Bau |
 | 14 | API-Key-Setup für Dev-Umgebung (`.env`-Datei, `direnv`, oder Windows-Env-Vars) | Phase 1, mit `sync.mjs` |
 | 15 | Verifizierung: persistiert Minimax Notizinhalte? Datenschutz-Klausel prüfen | Phase 2, vor Ingest-Bau |
+| 16 | **Vault-Init-Skript** im Tool: erstellt komplette Vault-Struktur inkl. Konfig, README, .gitignore | Phase 1b |
+| 17 | **Deployment-Mechanik** Tool→Vault: werden Skripte ins Vault kopiert oder aus dem Tool-Pfad aufgerufen? | Phase 1b |
+| 18 | **Vault-Pfad-Discovery**: Wie findet das Tool den Vault? (Env-Var, CLI-Argument, oder explizite Pfad-Konfig im Tool) | Phase 1a |
+| 11 | Konflikt-Auflösung-UI in PWA | Phase 4 |
+| 12 | Offline-Modus für Editor (PWA) | Phase 4 |
+| 13 | Minimax-API: exakte Endpoints, Request/Response-Format, Rate-Limits, Token-Kosten pro Operation | Phase 2, vor Ingest-Bau |
+| 14 | API-Key-Setup für Dev-Umgebung (`.env`-Datei, `direnv`, oder Windows-Env-Vars) | Phase 1, mit `sync.mjs` |
+| 15 | Verifizierung: persistiert Minimax Notizinhalte? Datenschutz-Klausel prüfen | Phase 2, vor Ingest-Bau |

 ---