chore: initialize safe Javis project scaffold

2026-07-30 16:10:02 +02:00
parent 49a1dd3718
commit 6d041711bc
53 changed files with 1784 additions and 1 deletions
@@ -0,0 +1,27 @@
+# Architektur
+
+## Ziel
+
+Javis beginnt als modularer Monolith. Module besitzen klare Zuständigkeiten und kommunizieren über kleine, typisierte Schnittstellen. Erst reale Betriebsgründe rechtfertigen später separate Dienste.
+
+## Vorgesehene Ebenen
+
+1. Interface: CLI, später Sprache, Mobilzugriff und Living Mind.
+2. Core: Gesprächsablauf, Sitzungszustand und Orchestrierung.
+3. Providers: austauschbare lokale und optionale Cloud-Modellanbindungen.
+4. Memory: strukturierte Laufzeitdaten und regenerierbarer semantischer Index.
+5. Obsidian: zunächst lesender Adapter, später eng begrenzte Entwürfe.
+6. Tools und Status: feste Schemas, Allowlists, Timeouts und bereinigte Ausgaben.
+7. Security: Freigaben, Secret-Provider und Berechtigungsprüfung.
+8. Audit: nachvollziehbare Aktionen ohne geheime Inhalte.
+
+## Plattformgrenzen
+
+- Pfade werden später per Konfiguration und `pathlib` aufgelöst.
+- Betriebssystemspezifische Funktionen liegen hinter Adaptern.
+- Produktname, Datenpfade und Provider werden zentral konfiguriert.
+- Laufzeitdaten liegen außerhalb von Git.
+
+## Noch nicht implementiert
+
+Es existieren nur Paketgrenzen und Dokumentation. Es gibt keinen Chat, Provider, Speicher, Toolaufruf oder Netzwerkdienst.
@@ -0,0 +1,23 @@
+# Datenmodell – Entwurf
+
+## Laufzeitdaten
+
+Eine spätere strukturierte Datenbank kann mindestens enthalten:
+
+- `sessions`: Beginn, Ende und aktiver Kontext
+- `messages`: Rolle, Inhalt, Zeit und Providerreferenz
+- `tasks`: Status, Projekt, Fälligkeit und Quelle
+- `approvals`: angefragte Aktion, Entscheidung und Zeitpunkt
+- `tool_calls`: Toolname, bereinigte Parameter, Ergebnisstatus und Dauer
+- `memories`: Aussage, Quelle, Gültigkeit und Bestätigung
+- `source_documents`: Pfad, Änderungszeit und Indexstatus
+
+SQLite ist der bevorzugte erste Kandidat, aber noch nicht implementiert.
+
+## Obsidian
+
+Obsidian bleibt die menschlich lesbare Wissensschicht. Ein Link wird nur erzeugt, wenn die Zielnotiz für das Verständnis, die Herkunft, eine Entscheidung oder eine echte Projektbeziehung relevant ist. Graphästhetik allein ist kein Linkgrund.
+
+## Semantischer Index
+
+Der Index ist jederzeit aus Quellen regenerierbar. Er speichert Quellpfad und Änderungszeit, ist nie die einzige Wissenskopie und gehört nicht in Git.
@@ -0,0 +1,11 @@
+# Entscheidungen
+
+| ID | Entscheidung | Status |
+|---|---|---|
+| ADR-0001 | Modularer Monolith statt früher Microservices | angenommen |
+| ADR-0002 | Secrets bleiben außerhalb von Modellkontext und Git | angenommen |
+| ADR-0003 | Obsidian-Links benötigen echte inhaltliche Beziehungen | angenommen |
+
+Offen bleiben insbesondere die konkrete lokale Modelllaufzeit, das endgültige Runtime-Secret-System, der genaue Obsidian-Schreibbereich und der Produktname.
+
+Ausführliche Begründungen stehen unter [`docs/adr`](adr/README.md).
@@ -0,0 +1,39 @@
+# Environment Verification
+
+Prüfzeitpunkt: 30.07.2026, Europe/Berlin.
+
+## Projekt
+
+- Erwarteter und bestätigter Pfad: `D:\Javis-Projekt`
+- Git-Toplevel: `D:/Javis-Projekt`
+- Branch: `main`
+- Ausgangsstand: `main` entsprach `origin/main` bei `49a1dd3`
+- Nachvollziehbare unversionierte Datei vor dem Grundgerüst: `CHATGPT_HANDOFF.md`
+- Bestehende versionierte Datei: `READ.ME`
+- Remote: `origin` zeigt per HTTPS auf das Gitea-Repository `Jarvis-Ai.git`
+- Der aktuelle Codex-Thread läuft in einem generierten Sitzungsordner. Dieser ist kein zweites Repository und nicht der Projektpfad.
+
+Es wurden keine eingebetteten Zugangsdaten ausgegeben.
+
+## Obsidian
+
+- Aktiver und bestätigter Vault: `D:\Obsidian Vault`
+- `.obsidian` vorhanden
+- `Test.md` vorhanden
+- genau eine Markdown-Datei zum Prüfzeitpunkt
+- Pluginverzeichnis `obsidian-livesync` vorhanden
+- globale Obsidian-Konfiguration markiert ausschließlich `D:\Obsidian Vault` als geöffnet
+- alte Kopie `C:\Users\pasca\OneDrive\Dokumente\Obsidian Vault` am genannten Pfad nicht vorhanden
+
+Der Vault und `.obsidian` wurden ausschließlich gelesen und nicht verändert.
+
+## Lokale Toolchain
+
+- Git: `2.55.0.windows.2`
+- Visual Studio Code: `1.131.0`
+- Python, `py`, Node.js, npm und Docker: im normalen Benutzer-`PATH` nicht verfügbar
+- Ein mit Codex gebündelter Python-Interpreter darf für die Strukturprüfung genutzt werden; er ersetzt keine bewusst installierte Projekt-Toolchain.
+
+## Ergebnis
+
+Die Abbruchbedingungen der Phase 0 trafen nicht zu. Das Grundgerüst durfte im bestätigten Repository vorbereitet werden.
@@ -0,0 +1,38 @@
+# Mögliche spätere Linux-Migration
+
+Ein Wechsel des Gaming-PCs von Windows 11 zu Linux ist nicht beschlossen und nicht Teil der aktuellen Entwicklung.
+
+## Plattformunabhängig vorgesehen
+
+- Python-Kern und standardisierte Projektkonfiguration
+- relative Pfade und `pathlib`
+- UTF-8 und definierte Zeilenenden
+- SQLite und dateibasierte Laufzeitdaten
+- austauschbare Modell-, Status- und Tooladapter
+
+## Später betriebssystemspezifisch zu prüfen
+
+- GPU-Treiber, CUDA und lokale Modelllaufzeit
+- Spiele, Anti-Cheat, VR und Windows-spezifische Programme
+- Audio-, Mikrofon- und Wake-Word-Geräte
+- Autostart und Dienstverwaltung
+- Dateirechte, Keyring und Hardwaremonitoring
+
+## Vor einem Wechsel zu sichern
+
+- vollständige Benutzerdateien und Projekt-Repositories
+- aktiver Obsidian-Vault einschließlich geprüftem LiveSync-Zustand
+- lokale Datenbanken und Laufzeitdaten
+- Browser- und Anwendungsprofile nach bewusster Auswahl
+- SSH-Schlüssel und andere Secrets verschlüsselt, getrennt und mit Restore-Test
+- Lizenzinformationen und Installationslisten
+
+## Sicheres Vorgehen
+
+1. vollständige Bestands- und Kompatibilitätsliste
+2. mindestens zwei unabhängige Backups
+3. stichprobenartiger Wiederherstellungstest
+4. bevorzugt Test auf separatem Datenträger oder Dual-Boot
+5. erst danach eine gesondert freigegebene Migration
+
+Codex darf keine Partition, keinen Bootloader und kein Betriebssystem ohne konkrete Freigabe verändern.
@@ -0,0 +1,24 @@
+# Nächste Sitzung
+
+## Ziel
+
+Pascal prüft zuerst das Grundgerüst. Danach kann Phase 1 auf `feat/core-chat` beginnen.
+
+## Vor Änderungen erneut prüfen
+
+1. `git status --short --branch`
+2. `git log -1 --oneline`
+3. `docs/PROJECT_STATUS.md`
+4. offene Entscheidungen in `docs/DECISIONS.md`
+
+## Vorgeschlagener Umfang
+
+- zwei bis drei geeignete lokale Python-Installationswege vergleichen
+- Installation nur nach Pascals Freigabe
+- echte Konfigurationsladefunktion mit Tests
+- Provider-Protokoll ohne Cloudaufruf
+- minimale CLI-Struktur ohne fest programmierte KI-Antworten
+
+## Nicht beginnen
+
+Noch keine Modellinstallation, kein Obsidian-Schreiben, kein SSH-/Serverzugriff, keine Sprache und kein Living-Mind-Frontend.
@@ -0,0 +1,14 @@
+# Berechtigungen
+
+| Bereich | Anfangszustand | Spätere Erweiterung |
+|---|---|---|
+| Projektdateien | Codex darf im freigegebenen Auftrag schreiben | weiterhin Git- und Testpflicht |
+| Obsidian | gesamter Vault lesend | neue Dateien nur in einzeln freigegebenen Ordnern |
+| Bestehende Notizen | keine Änderung | nur konkrete ausdrückliche Freigabe |
+| Lokaler PC | definierte lesende Statusabfragen | schreibende Tools einzeln freigeben |
+| Ubuntu-Laptop | kein Zugriff | eigener Schlüssel, Benutzer und begrenzte Verzeichnisse |
+| Rootserver | kein Zugriff | eigener rein lesender Adapter oder Benutzer |
+| Secrets | Modell sieht keine Werte | Tool-Schicht nutzt einzelne Werte intern |
+| Externe Nachrichten | verboten | nur mit konkreter Freigabe und Empfängerprüfung |
+
+Jede Tooldefinition benötigt Eingabeschema, Ausgabegrenze, Timeout, Fehlerverhalten, Berechtigungsstufe und Auditregel.
@@ -0,0 +1,26 @@
+# Projektstatus
+
+Stand: Grundgerüstphase am 30.07.2026.
+
+## Erreicht
+
+- Projekt- und Vault-Pfade lesend bestätigt
+- Sicherheits- und Architekturgrenzen dokumentiert
+- plattformunabhängige Paketstruktur vorbereitet
+- Obsidian-Linkregel als verbindliche Entscheidung dokumentiert
+- Living-Mind-Bereich als inaktiver Vertrag vorbereitet
+- projektinterne Codex-Agentensyntax anhand der aktuellen offiziellen Codex-Dokumentation geprüft
+
+## Nicht implementiert
+
+KI, Chat, Provider, Gedächtnis, Obsidian-Adapter, Tools, Serverzugriff, Sprache, Mobile Client und Living-Mind-Frontend.
+
+## Git
+
+- Branch: `main`
+- Ausgangscommit: `49a1dd3`
+- Der Commit, der dieses Dokument enthält, ist der Grundgerüstcommit; die konkrete ID ist mit `git log -1` zu ermitteln.
+
+## Bekannte Einschränkung
+
+Im normalen Windows-`PATH` ist noch keine nutzbare Python-Installation verfügbar. Es wurde nichts installiert.
@@ -0,0 +1,15 @@
+# Roadmap
+
+Jede Phase beginnt erst nach Abnahme der vorherigen Phase.
+
+1. **Grundgerüst:** Pfade, Regeln, Architektur, Sicherheit und Strukturtests.
+2. **Core Chat:** echte lokale Texteingabe, Provider-Abstraktion, Sitzung und klare Fehler.
+3. **Memory:** SQLite-Entscheidung, Auditmodell und nachvollziehbare Speicherung.
+4. **Obsidian:** lesender Index, Quellenangaben und später freigegebene Entwurfsordner.
+5. **Status Tools:** zuerst lokaler PC und Git, später eingeschränkte Remoteadapter.
+6. **Lokales Modell:** Benchmarks auf RTX 3060 und ASUS-Laptop; Installation nur nach Freigabe.
+7. **Sprache:** Push-to-Talk vor Wake Word.
+8. **Living Mind:** echte Datenverträge, Herkunfts-/Lizenzprüfung und danach Implementierung.
+9. **Mobil:** authentifizierter, verschlüsselter Client ohne öffentliche ungeschützte Oberfläche.
+
+Der mögliche Windows-zu-Linux-Wechsel ist kein Roadmap-Schritt, sondern gegebenenfalls ein eigenes späteres Migrationsprojekt.
@@ -0,0 +1,32 @@
+# Sicherheit
+
+## Grundsätze
+
+- geringste Rechte und lesende Funktionen zuerst
+- keine freie Shell für das Modell
+- feste Tool-Schemas, Befehls-Allowlist, Timeouts und Ausgabelimits
+- menschliche Freigabe vor schreibenden oder destruktiven Aktionen
+- keine Root- oder normalen Administratorkonten für Javis
+- keine öffentliche Schnittstelle ohne Authentifizierung und TLS
+- Backups müssen wiederherstellbar getestet werden
+
+## Secrets
+
+Secrets dürfen nie in Code, Git, Prompts, Chatverläufe oder Logs gelangen. Das Modell erfährt nur den Namen, die Verfügbarkeit und ein bereinigtes Aktionsergebnis.
+
+Bevorzugt wird eine Secret-Provider-Abstraktion. Eine optionale lokale XML-Datei wie `key-pw.xml` oder `secrets.local.xml` ist nur als restriktiv geschützte, Git-ignorierte Klartextdatei zulässig. Ins Repository darf höchstens eine leere Beispielstruktur.
+
+Eine vorhandene SSH-Schlüsseldatei aus früherer LS25-/Gitea-Arbeit bleibt lokal. Pfad, privater Inhalt und Gerätekennung werden nicht dokumentiert.
+
+## Obsidian
+
+- gesamter Vault zunächst nur lesend
+- `.obsidian` niemals verändern
+- bestehende Notizen nicht automatisch bearbeiten oder löschen
+- spätere Schreibbereiche einzeln freigeben
+- Wikilinks nur bei echter semantischer Beziehung
+- keine künstlichen Links zur bloßen Verdichtung der Graphansicht
+
+## Meldung eines Problems
+
+Bei möglichem Secret-Leak, unerwartetem Schreibzugriff oder falschem Zielpfad sofort stoppen, betroffene Aktion benennen und keine automatische Bereinigung durchführen.
@@ -0,0 +1,26 @@
+# Bedrohungsmodell
+
+## Schutzwerte
+
+- persönliche Notizen und Erinnerungen
+- API-Keys, Tokens, Passwörter und SSH-Schlüssel
+- Projekt- und Git-Historie
+- lokale und entfernte Systeme
+- Auditdaten und Freigabeentscheidungen
+
+## Wesentliche Bedrohungen
+
+| Bedrohung | Beispiel | Gegenmaßnahme |
+|---|---|---|
+| Prompt Injection | Notiz oder Webseite fordert einen Toolaufruf | Inhalte sind Daten, keine Berechtigung; Tool-Allowlist und Freigabe |
+| Secret-Abfluss | Token erscheint in Prompt oder Log | Secret-Provider, Maskierung, keine Modellrückgabe |
+| Zu breite Rechte | Modell erhält Shell oder Rootzugriff | eng definierte Adapter und eigene eingeschränkte Konten |
+| Falscher Pfad | OneDrive-Vault statt aktivem Vault | kanonische Pfadprüfung und Abbruch |
+| Datenverlust | Notiz, Partition oder Datenbank wird überschrieben | Backups, Dry-Run, konkrete Freigabe, Restore-Test |
+| Falsche Erinnerung | semantischer Treffer wird als Fakt gespeichert | Quellenpfad, Zeitstempel, Korrektur und menschliche Bestätigung |
+| Öffentliche Exposition | ungeschützte mobile Oberfläche | Authentifizierung, TLS und Sicherheitsreview |
+| Lieferkette | ungeprüftes Plugin oder Referenzprojekt | Herkunft, Version und Lizenz prüfen; nichts blind ausführen |
+
+## Vertrauensgrenzen
+
+Modell, eingelesene Inhalte und externe Dienste sind nicht vertrauenswürdig. Tool-Schicht, Freigabesystem und Secret-Provider erzwingen die Grenze unabhängig vom Modelltext.
@@ -0,0 +1,5 @@
+# ADR-0001: Modularer Monolith
+
+Status: angenommen.
+
+Javis beginnt als ein deploybarer Kern mit klar getrennten internen Modulen. Das reduziert Betriebsaufwand, Ressourcenverbrauch und verteilte Fehlerbilder auf der vorhandenen Hardware. Einzelne Dienste werden erst ausgelagert, wenn Messwerte oder Sicherheitsgrenzen dies rechtfertigen.
@@ -0,0 +1,5 @@
+# ADR-0002: Secret-Isolation
+
+Status: angenommen.
+
+Secret-Werte werden ausschließlich von einer begrenzten Runtime-Schicht geladen und intern für genehmigte Aktionen eingesetzt. Weder Modellkontext noch Audit-Log erhalten die Werte. Echte Secret-Dateien sind lokal, restriktiv geschützt und Git-ignoriert; Beispielkonfigurationen enthalten nur leere Platzhalter.
@@ -0,0 +1,7 @@
+# ADR-0003: Sinnvolle Obsidian-Verknüpfungen
+
+Status: angenommen.
+
+Die Obsidian-Graphansicht soll langfristig eine organische, gehirnartige Wissensstruktur zeigen. Javis erzeugt einen Wikilink jedoch nur, wenn eine nachvollziehbare fachliche Beziehung besteht, etwa gemeinsame Projekte, Herkunft, Abhängigkeit oder Entscheidung.
+
+Links, die ausschließlich die Optik verdichten, sind verboten. Qualität und Erklärbarkeit der Wissensbeziehungen haben Vorrang vor der Anzahl sichtbarer Kanten.
@@ -0,0 +1,5 @@
+# Architecture Decision Records
+
+- [ADR-0001: Modularer Monolith](0001-modular-monolith.md)
+- [ADR-0002: Secret-Isolation](0002-secret-isolation.md)
+- [ADR-0003: Sinnvolle Obsidian-Verknüpfungen](0003-meaningful-obsidian-links.md)