mindnet_obsidian/docs/01_Benutzerhandbuch.md

# Mindnet Causal Assistant - Benutzerhandbuch

> **Version:** 1.0.0  
> **Stand:** 2025-01-XX  
> **Zielgruppe:** Endnutzer des Mindnet Obsidian Plugins

---

## Inhaltsverzeichnis

1. [Einführung](#einführung)
2. [Schnellstart](#schnellstart)
3. [Hauptfunktionen](#hauptfunktionen)
4. [Workflows](#workflows)
5. [Commands im Detail](#commands-im-detail)
6. [Troubleshooting](#troubleshooting)

---

## Einführung

Das **Mindnet Causal Assistant** Plugin ist ein Authoring-Tool für Obsidian, das Sie dabei unterstützt:

- **Strukturierte Notes** anzulegen mit Frontmatter, IDs und Typen
- **Inhalte über konfigurierbare Interviews** zu erfassen
- **Semantische Kanten (Edges)** zu pflegen und zu validieren
- **Links und Edge-Zuordnungen** section-basiert zu gruppieren (Semantic Mapping)
- **Kausale Ketten** zu analysieren und zu validieren

### Hauptkonzepte

- **Profile**: Auswahl eines "Erstell-Profils" (kann mehrere Interviews pro Note-Typ geben)
- **Interview Config (YAML)**: Definiert Steps, Loops, Defaults, Frontmatter-Whitelist
- **ID-first**: Mindnet-Graph arbeitet über Frontmatter `id` als Schlüssel
- **Semantic Mapping**: Links in einer Section werden Edge-Typen zugeordnet und als Callouts strukturiert
- **Chain Templates**: Vordefinierte Muster für kausale Ketten (z.B. `trigger → transformation → outcome`)

---

## Schnellstart

### 1. Plugin aktivieren

1. Öffnen Sie **Settings → Community Plugins**
2. Stellen Sie sicher, dass "Restricted mode" ausgeschaltet ist
3. Aktivieren Sie das Plugin "Mindnet Causal Assistant"

### 2. Erste Konfiguration

Das Plugin benötigt Konfigurationsdateien im Vault. Diese sollten bereits vorhanden sein (siehe Administratorhandbuch). Standardpfade:

- `_system/dictionary/edge_vocabulary.md` - Edge-Typen-Vokabular
- `_system/dictionary/graph_schema.md` - Graph-Schema
- `_system/dictionary/interview_config.yaml` - Interview-Konfiguration
- `_system/dictionary/chain_roles.yaml` - Chain-Rollen-Mapping
- `_system/dictionary/chain_templates.yaml` - Chain-Templates

### 3. Erste Note erstellen

1. Öffnen Sie den Command Palette (`Ctrl+P` / `Cmd+P`)
2. Wählen Sie **"Mindnet: Create note from profile"**
3. Wählen Sie ein Profil aus
4. Geben Sie einen Titel ein
5. Wählen Sie einen Ordner (optional)
6. Die Note wird erstellt und geöffnet
7. Optional: Wizard startet automatisch (wenn konfiguriert)

---

## Hauptfunktionen

### 1. Note-Erstellung mit Profilen

**Zweck:** Erstellen strukturierter Mindnet-Notes mit korrektem Frontmatter.

**Verwendung:**
- Command: **"Mindnet: Create note from profile"**
- Profil wählen (z.B. "experience", "insight", "decision")
- Titel und Ordner festlegen
- Note wird mit Frontmatter erstellt (ID, Typ, Profil)

**Frontmatter-Beispiel:**
```yaml
---
id: note_1234567890_abc123
title: "Meine Erfahrung"
type: experience
interview_profile: experience_basic
---
```

### 2. Interview-Wizard

**Zweck:** Strukturierte Erfassung von Inhalten über konfigurierbare Interviews.

**Verwendung:**
- Startet automatisch nach Note-Erstellung (wenn aktiviert)
- Oder manuell über Command (geplant)
- Steps ausfüllen (Loops/Nested Loops möglich)
- Review → Apply & Finish
- Output wird in die Note geschrieben

**Features:**
- Verschachtelte Loops
- Section-basierte Ausgabe
- Frontmatter-Whitelist-Unterstützung

### 3. Semantic Mapping (Edger)

**Zweck:** Automatische Gruppierung von Links nach Edge-Typen in Mapping-Blöcken.

**Verwendung:**
- **Manuell:** Command **"Mindnet: Build semantic mapping blocks (by section)"**
- **Automatisch:** Nach Interview Finish (falls im Profil aktiviert)

**Output:**
- Pro Section ein Mapping-Block am Ende der Section:
  - Wrapper Callout (Default: `abstract`)
  - Gruppiert nach Edge-Typ
  - Gruppen getrennt durch Leerzeile

**Beispiel:**
```markdown
## Meine Section

Inhalt mit Links: [[Note1]] und [[Note2]]

> [!abstract] 🕸️ Semantic Mapping
> 
> > [!edge] causes
> > [[Note1]]
> > 
> > [!edge] influences
> > [[Note2]]
```

### 4. Chain Inspector

**Zweck:** Analyse kausaler Ketten um die aktuelle Section.

**Verwendung:**
- Command: **"Mindnet: Inspect Chains (Current Section)"**
- Analysiert lokale Nachbarschaft + Pfade im Graphen
- Template Matching gegen vordefinierte Kettenmuster
- Findings (Gap-Heuristiken) werden generiert

**Report enthält:**
- Context (aktuelle Datei/Section)
- Neighbors (incoming/outgoing)
- Paths (vorwärts/rückwärts)
- Template Matches
- Findings (fehlende Slots, Links, etc.)

**Findings-Beispiele:**
- `missing_slot_*` - Wichtige Slots fehlen
- `dangling_target` - Edge verweist auf nicht-existierende Datei
- `dangling_target_heading` - Edge verweist auf nicht-existierendes Heading
- `missing_link_constraints` - Erwartete Links fehlen
- `no_causal_roles` - Keine kausalen Rollen gefunden

### 5. Fix Findings

**Zweck:** Automatische Behebung von Findings.

**Verwendung:**
- Command: **"Mindnet: Fix Findings (Current Section)"**
- Zeigt verfügbare Fix-Actions für Findings
- Wählt Action aus → wird ausgeführt

**Verfügbare Actions:**
- **Create Missing Note** - Erstellt fehlende Note (skeleton oder mit Wizard)
- **Retarget Link** - Ersetzt Link zu existierender Note
- **Create Missing Heading** - Erstellt Heading in Target-Datei
- **Retarget to Existing Heading** - Ersetzt Link zu existierendem Heading
- **Promote Candidate Edge** - Befördert Candidate-Edge zu explizitem Edge

### 6. Unresolved Link Handling

**Zweck:** Automatische Note-Erstellung beim Klick auf nicht-existierende Links.

**Verwendung:**
- Klick auf `[[Neue Note]]` in Reading View oder Editor
- Plugin übernimmt Flow (wenn aktiviert)
- Profil-Auswahl → Note wird erstellt
- Optional: Wizard startet automatisch

**Modifier-Keys:**
- **Reading View:** Bypass-Modifier (Standard: `Alt`) - umgeht Plugin-Intercept
- **Editor:** Follow-Modifier (Standard: `Ctrl`) - aktiviert Plugin-Intercept

### 7. Edge-Type-Änderung

**Zweck:** Ändern des Edge-Typs für Links.

**Verwendung:**
- Command: **"Mindnet: Edge-Type ändern"**
- Kontext wird automatisch erkannt:
  - Cursor in Link → ändert diesen Link
  - Auswahl mit Links → ändert alle Links in Auswahl
  - Keine Auswahl → zeigt Edge-Type-Selector für neue Links

**Features:**
- Graph-Schema-basierte Empfehlungen
- Inline Micro-Suggester (wenn aktiviert)
- Typische/Prohibited Edge-Types

### 8. Note Adoption

**Zweck:** Automatische Konvertierung neu erstellter Notes zu Mindnet-Format.

**Verwendung:**
- Automatisch aktiviert (wenn konfiguriert)
- Erkennt neu erstellte Notes (klein, ohne ID)
- Zeigt Adoption-Modal (abhängig von Confidence)
- Profil-Auswahl → Frontmatter wird hinzugefügt
- Optional: Wizard startet

**Confidence-Levels:**
- **High:** Innerhalb Zeitfenster nach Link-Klick
- **Low:** Andere Fälle

---

## Workflows

### Workflow 1: Neue Note erstellen und ausfüllen

1. **Note erstellen:**
   - Command: "Mindnet: Create note from profile"
   - Profil wählen (z.B. "experience")
   - Titel: "Meine Erfahrung"
   - Ordner wählen

2. **Wizard ausfüllen:**
   - Wizard startet automatisch (wenn aktiviert)
   - Steps durchgehen
   - Review → Apply & Finish

3. **Semantic Mapping:**
   - Edger läuft automatisch (falls im Profil aktiviert)
   - Oder manuell: "Mindnet: Build semantic mapping blocks"

4. **Validierung:**
   - Command: "Mindnet: Validate current note"
   - Prüft Lint-Regeln
   - Zeigt Findings in Console

### Workflow 2: Kausale Kette analysieren

1. **Section öffnen:**
   - Cursor in relevante Section positionieren

2. **Chain Inspector ausführen:**
   - Command: "Mindnet: Inspect Chains (Current Section)"
   - Report wird in Console ausgegeben

3. **Findings prüfen:**
   - Console öffnen (F12)
   - Findings analysieren
   - Template Matches prüfen

4. **Findings beheben:**
   - Command: "Mindnet: Fix Findings (Current Section)"
   - Verfügbare Actions auswählen
   - Automatische Behebung

### Workflow 3: Unresolved Link → Note erstellen

1. **Link erstellen:**
   - `[[Neue Note]]` in Note schreiben

2. **Link anklicken:**
   - Reading View: Normaler Klick
   - Editor: `Ctrl` + Klick (wenn Follow-Modifier aktiviert)

3. **Profil wählen:**
   - Profile-Selection-Modal öffnet sich
   - Profil auswählen

4. **Note wird erstellt:**
   - Frontmatter wird hinzugefügt
   - Wizard startet (wenn aktiviert)

### Workflow 4: Edge-Type ändern

1. **Link markieren:**
   - Cursor in Link positionieren
   - Oder mehrere Links auswählen

2. **Command ausführen:**
   - "Mindnet: Edge-Type ändern"

3. **Edge-Type wählen:**
   - Modal zeigt verfügbare Types
   - Empfehlungen basierend auf Graph-Schema
   - Type auswählen

4. **Änderung wird angewendet:**
   - Link wird aktualisiert
   - Semantic Mapping wird aktualisiert (falls vorhanden)

---

## Commands im Detail

### Note-Erstellung & Interview

| Command | Beschreibung | Wann verwenden |
|---------|--------------|----------------|
| **Mindnet: Create note from profile** | Erstellt neue Note mit Profil | Neue Note von Grund auf erstellen |
| *(Geplant)* **Mindnet: Start interview wizard** | Startet Wizard für aktuelle Note | Interview manuell starten |

### Mapping & Edges

| Command | Beschreibung | Wann verwenden |
|---------|--------------|----------------|
| **Mindnet: Build semantic mapping blocks (by section)** | Baut Semantic Mapping Blöcke | Links nach Edge-Typen gruppieren |
| **Mindnet: Edge-Type ändern** | Ändert Edge-Type für Links | Edge-Typ korrigieren/zuordnen |
| **Mindnet: Reload edge vocabulary** | Lädt Edge-Vokabular neu | Nach Änderung an edge_vocabulary.md |

### Analyse & Validierung

| Command | Beschreibung | Wann verwenden |
|---------|--------------|----------------|
| **Mindnet: Inspect Chains (Current Section)** | Analysiert kausale Ketten | Chain-Analyse durchführen |
| **Mindnet: Fix Findings (Current Section)** | Behebt Findings automatisch | Findings automatisch beheben |
| **Mindnet: Validate current note** | Validiert aktuelle Note (Lint) | Note auf Fehler prüfen |

### Export & Debug

| Command | Beschreibung | Wann verwenden |
|---------|--------------|----------------|
| **Mindnet: Export graph** | Exportiert Graph als JSON | Graph exportieren |
| **Mindnet: Show chains from current note** | Zeigt Ketten von aktueller Note | Ketten-Exploration |
| **Mindnet: Debug Chain Roles (Loaded)** | Debug-Info für Chain Roles | Debugging |
| **Mindnet: Debug Chain Templates (Loaded)** | Debug-Info für Chain Templates | Debugging |

> **Detaillierte Referenz:** Siehe [07_Event_Handler_Commands.md](./07_Event_Handler_Commands.md) für vollständige Beschreibung aller Commands, Event Handler und Settings.

---

## Troubleshooting

### Wizard startet nicht

**Symptom:** Wizard startet nicht nach Note-Erstellung.

**Lösung:**
1. Prüfen Sie Settings: `autoStartInterviewOnCreate`
2. Prüfen Sie DevTools Console (F12) auf Fehler
3. Prüfen Sie Interview-Config-Pfad in Settings

### Edger schreibt Blöcke an falscher Stelle

**Symptom:** Semantic Mapping Blöcke erscheinen an falscher Position.

**Lösung:**
1. Prüfen Sie Heading-Parsing (Section-Erkennung)
2. Prüfen Sie, ob Wrapper-Block korrekt erkannt/ersetzt wird
3. Prüfen Sie Console-Logs für Details

### Schema-Empfehlungen fehlen

**Symptom:** Keine Empfehlungen beim Edge-Type-Ändern.

**Lösung:**
1. Prüfen Sie `graph_schema_path` in Settings
2. Prüfen Sie Schema-Loader Stats/Logging in Console
3. Prüfen Sie, ob Schema-Datei existiert und gültig ist

### Chain Inspector findet keine Matches

**Symptom:** Template Matches sind leer.

**Lösung:**
1. Prüfen Sie Chain-Templates-Pfad in Settings
2. Prüfen Sie Console-Logs für Template-Loading
3. Prüfen Sie, ob Note-Types korrekt im Frontmatter sind
4. Prüfen Sie, ob Edges korrekt gemappt sind (chain_roles.yaml)

### Unresolved Link wird nicht abgefangen

**Symptom:** Klick auf `[[Neue Note]]` öffnet Obsidian-Dialog statt Plugin-Flow.

**Lösung:**
1. Prüfen Sie Settings: `interceptUnresolvedLinkClicks`
2. **Reading View:** Bypass-Modifier nicht drücken
3. **Editor:** Follow-Modifier (`Ctrl`) drücken beim Klick
4. Prüfen Sie Console-Logs für Details

### Note Adoption funktioniert nicht

**Symptom:** Neu erstellte Notes werden nicht adoptiert.

**Lösung:**
1. Prüfen Sie Settings: `adoptNewNotesInEditor`
2. Prüfen Sie, ob Note klein genug ist (`adoptMaxChars`)
3. Prüfen Sie, ob Note bereits Frontmatter-ID hat (wird nicht adoptiert)
4. Prüfen Sie Console-Logs für Adoption-Confidence

---

## Weitere Ressourcen

- **Administratorhandbuch:** Konfiguration und Wartung
- **Entwicklerhandbuch:** Code-Struktur und Erweiterungen
- **Architektur-Dokumentation:** System-Übersicht
- **Installation & Deployment:** Setup-Anleitung

---

**Ende des Benutzerhandbuchs**