From cee1f4c8f7f10029a9830d7dd67c9aee2e6a569e Mon Sep 17 00:00:00 2001 From: orfelorfel23 Date: Sat, 5 Sep 2026 10:41:22 +0200 Subject: [PATCH] Spec v0.4: Repository-Trennung Tool/Vault sauber dokumentiert MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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) --- 10 Wiki/SPEC.md | 131 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 98 insertions(+), 33 deletions(-) diff --git a/10 Wiki/SPEC.md b/10 Wiki/SPEC.md index 9ca390c..3345853 100644 --- a/10 Wiki/SPEC.md +++ b/10 Wiki/SPEC.md @@ -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 +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 ` +- 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 | ---