# Mindnet Causal Assistant - Administratorhandbuch

> **Version:** 1.0.0  
> **Stand:** 2025-01-XX  
> **Zielgruppe:** Administratoren, Config-Manager, Vault-Verwalter

---

## Inhaltsverzeichnis

1. [Überblick](#überblick)
2. [Plugin-Konfiguration](#plugin-konfiguration)
3. [Konfigurationsdateien](#konfigurationsdateien)
4. [Pfad-Management](#pfad-management)
5. [Live-Reload](#live-reload)
6. [Wartung & Troubleshooting](#wartung--troubleshooting)

---

## Überblick

Das Mindnet Causal Assistant Plugin benötigt mehrere Konfigurationsdateien, die im Vault gespeichert werden. Diese Dateien definieren:

- **Edge-Vokabular:** Kanonische Edge-Typen und Aliases
- **Graph-Schema:** Empfehlungen für Edge-Typen basierend auf Note-Typen
- **Interview-Config:** Profile, Steps, Loops für Note-Erstellung
- **Chain Roles:** Mapping von Edge-Typen zu kausalen Rollen
- **Chain Templates:** Vordefinierte Kettenmuster für Template Matching

---

## Plugin-Konfiguration

### Settings-Zugriff

**Settings → Community Plugins → Mindnet Causal Assistant**

### Wichtige Settings

#### Pfad-Settings

| Setting | Standard | Beschreibung |
|---------|----------|--------------|
| `edgeVocabularyPath` | `_system/dictionary/edge_vocabulary.md` | Pfad zum Edge-Vokabular |
| `graphSchemaPath` | `_system/dictionary/graph_schema.md` | Pfad zum Graph-Schema |
| `interviewConfigPath` | `_system/dictionary/interview_config.yaml` | Pfad zur Interview-Config |
| `chainRolesPath` | `_system/dictionary/chain_roles.yaml` | Pfad zu Chain Roles |
| `chainTemplatesPath` | `_system/dictionary/chain_templates.yaml` | Pfad zu Chain Templates |
| `analysisPoliciesPath` | `_system/dictionary/analysis_policies.yaml` | Pfad zu Analysis Policies |

#### Feature-Settings

| Setting | Standard | Beschreibung |
|---------|----------|--------------|
| `interceptUnresolvedLinkClicks` | `true` | Unresolved Links abfangen |
| `autoStartInterviewOnCreate` | `false` | Wizard automatisch starten |
| `adoptNewNotesInEditor` | `true` | Neue Notes automatisch adoptieren |
| `chainInspectorIncludeCandidates` | `false` | Candidate-Edges in Chain Inspector einbeziehen |
| `templateMatchingProfile` | `"discovery"` | Template-Matching-Profil (`discovery` / `decisioning`) |

#### Fix-Actions-Settings

| Setting | Standard | Beschreibung |
|---------|----------|--------------|
| `fixActions.createMissingNote.mode` | `"skeleton_only"` | Modus für fehlende Notes |
| `fixActions.createMissingHeading.level` | `2` | Heading-Level für neue Headings |
| `fixActions.promoteCandidate.keepOriginal` | `true` | Original bei Candidate-Promotion behalten |

---

## Konfigurationsdateien

> **Detaillierte Referenz:** Siehe [06_Konfigurationsdateien_Referenz.md](./06_Konfigurationsdateien_Referenz.md) für vollständige Format-Beschreibungen.

### 1. Edge Vocabulary (`edge_vocabulary.md`)

**Zweck:** Definiert kanonische Edge-Typen und Aliases.

**Format:** Markdown mit Callout-Struktur

**Beispiel:**
```markdown
# Edge Vocabulary

> [!edge-type] causes
> Canonical: causes
> Aliases: ausgelöst_durch, verursacht

> [!edge-type] influences
> Canonical: influences
> Aliases: beeinflusst, wirkt_auf
```

**Struktur:**
- `[!edge-type]` Callout mit kanonischem Namen
- `Canonical:` Zeile mit kanonischem Typ
- `Aliases:` Zeile mit komma-separierten Aliases

**Wartung:**
- Neue Edge-Types hinzufügen: Neuen Callout-Block hinzufügen
- Aliases hinzufügen: Komma-separiert zur `Aliases:` Zeile
- Live-Reload: Automatisch nach Dateiänderung (debounced)

---

### 2. Graph Schema (`graph_schema.md`)

**Zweck:** Empfehlungen für Edge-Typen basierend auf Source-Note-Typen.

**Format:** Markdown mit Callout-Struktur

**Beispiel:**
```markdown
# Graph Schema

> [!schema] experience
> Typical: causes, influences
> Prohibited: part_of, instance_of
```

**Struktur:**
- `[!schema]` Callout mit Note-Type als Titel
- `Typical:` Komma-separierte typische Edge-Types
- `Prohibited:` Komma-separierte verbotene Edge-Types

**Verwendung:**
- Edge-Type-Selector zeigt Empfehlungen basierend auf Source-Note-Type
- Warnungen bei prohibited Types

**Wartung:**
- Neue Note-Types hinzufügen: Neuen Callout-Block hinzufügen
- Empfehlungen anpassen: `Typical:` / `Prohibited:` Zeilen ändern
- Live-Reload: Automatisch nach Dateiänderung (debounced)

---

### 3. Interview Config (`interview_config.yaml`)

**Zweck:** Definiert Profile, Steps, Loops für Note-Erstellung und Interviews.

**Format:** YAML

**Struktur:**
```yaml
version: "1.0"
frontmatter_whitelist:
  - tags
  - status

profiles:
  - key: experience_basic
    note_type: experience
    description: "Basic experience profile"
    defaults:
      folder: "experiences"
    steps:
      - id: context
        prompt: "Beschreibe den Kontext"
        input_type: textarea
    post_run:
      edger: true
```

**Wichtige Felder:**

- **`version`:** Config-Version
- **`frontmatter_whitelist`:** Erlaubte Frontmatter-Keys (zusätzlich zu Standard)
- **`profiles`:** Liste von Profilen
  - **`key`:** Eindeutiger Profil-Schlüssel
  - **`note_type`:** Note-Type (z.B. `experience`, `insight`, `decision`)
  - **`defaults`:** Standardwerte (z.B. `folder`)
  - **`steps`:** Interview-Steps
  - **`post_run`:** Post-Run-Actions (z.B. `edger: true`)

**Wartung:**
- Neue Profile hinzufügen: Neuen Eintrag unter `profiles` hinzufügen
- Steps anpassen: `steps` Array modifizieren
- Loops hinzufügen: `loop` Feld in Steps verwenden
- Live-Reload: Automatisch nach Dateiänderung (debounced)

**Validierung:**
- YAML-Syntax wird beim Laden geprüft
- Fehler werden in Console geloggt
- Last-Known-Good wird verwendet bei Fehlern

---

### 4. Chain Roles (`chain_roles.yaml`)

**Zweck:** Mapping von Edge-Typen zu kausalen Rollen für Template Matching.

**Format:** YAML

**Struktur:**
```yaml
version: "1.0"

roles:
  causal:
    edge_types:
      - causes
      - caused_by
      - resulted_in
  influences:
    edge_types:
      - influences
      - affects
  enables_constraints:
    edge_types:
      - enables
      - constrains
```

**Rollen:**
- **`causal`:** Direkte kausale Beziehungen
- **`influences`:** Einfluss-Beziehungen
- **`enables_constraints`:** Ermöglicht/Beschränkt-Beziehungen
- **`provenance`:** Herkunfts-Beziehungen

**Wartung:**
- Neue Rollen hinzufügen: Neuen Eintrag unter `roles` hinzufügen
- Edge-Types zuordnen: `edge_types` Array erweitern
- Live-Reload: Automatisch nach Dateiänderung (debounced)

**Validierung:**
- YAML-Syntax wird beim Laden geprüft
- Fehler werden in Console geloggt
- Last-Known-Good wird verwendet bei Fehlern

---

### 5. Chain Templates (`chain_templates.yaml`)

**Zweck:** Vordefinierte Kettenmuster für Template Matching.

**Format:** YAML

**Struktur:**
```yaml
version: "1.0"

defaults:
  matching:
    required_links: false

templates:
  - name: trigger_transformation_outcome
    description: "Causal chain template"
    slots:
      - id: trigger
        allowed_node_types: ["experience"]
      - id: transformation
        allowed_node_types: ["insight"]
      - id: outcome
        allowed_node_types: ["decision"]
    links:
      - from: trigger
        to: transformation
        allowed_edge_roles: ["causal"]
      - from: transformation
        to: outcome
        allowed_edge_roles: ["causal"]
    matching:
      required_links: true
```

**Wichtige Felder:**

- **`defaults.matching.required_links`:** Standard für required_links (strict/soft)
- **`templates`:** Liste von Templates
  - **`name`:** Template-Name
  - **`slots`:** Slot-Definitionen mit `allowed_node_types`
  - **`links`:** Link-Constraints mit `allowed_edge_roles`
  - **`matching`:** Matching-Parameter (überschreibt Defaults)

**Wartung:**
- Neue Templates hinzufügen: Neuen Eintrag unter `templates` hinzufügen
- Slots anpassen: `slots` Array modifizieren
- Link-Constraints anpassen: `links` Array modifizieren
- Live-Reload: Automatisch nach Dateiänderung (debounced)

**Validierung:**
- YAML-Syntax wird beim Laden geprüft
- Fehler werden in Console geloggt
- Last-Known-Good wird verwendet bei Fehlern

---

### 6. Analysis Policies (`analysis_policies.yaml`)

**Zweck:** Policies für Findings (Severity, Unterdrückung, etc.).

**Format:** YAML (geplant)

**Status:** Noch nicht vollständig implementiert

**Geplante Struktur:**
```yaml
version: "1.0"

findings:
  missing_slot_*:
    default_severity: warn
    profiles:
      discovery:
        severity: info
      decisioning:
        severity: warn
  dangling_target:
    default_severity: error
    suppress_if: []
```

---

## Pfad-Management

### Standard-Pfade

Alle Konfigurationsdateien werden standardmäßig unter `_system/dictionary/` erwartet:

```
_system/
  dictionary/
    edge_vocabulary.md
    graph_schema.md
    interview_config.yaml
    chain_roles.yaml
    chain_templates.yaml
    analysis_policies.yaml
```

### Pfad-Änderung

**Vorgehen:**
1. Settings öffnen: **Settings → Community Plugins → Mindnet Causal Assistant**
2. Pfad-Setting ändern (z.B. `edgeVocabularyPath`)
3. Settings speichern
4. Plugin lädt Config automatisch neu

**Hinweise:**
- Pfade sind vault-relativ (beginnen mit `/` oder ohne)
- Forward-Slashes werden normalisiert
- Dateien müssen existieren (sonst Fehler beim Laden)

---

## Live-Reload

### Automatisches Reload

**Funktionsweise:**
- Plugin überwacht Konfigurationsdateien auf Änderungen
- Bei Änderung: Debounced Reload (200ms Delay)
- Last-Known-Good wird verwendet bei Fehlern

**Überwachte Dateien:**
- `edge_vocabulary.md`
- `graph_schema.md`
- `interview_config.yaml`
- `chain_roles.yaml`
- `chain_templates.yaml`

### Manuelles Reload

**Commands:**
- **"Mindnet: Reload edge vocabulary"** - Lädt Edge-Vokabular neu

**Verwendung:**
- Nach größeren Änderungen
- Wenn automatisches Reload nicht funktioniert
- Für Debugging

### Reload-Status prüfen

**Console-Logs:**
- Öffnen Sie DevTools (F12)
- Prüfen Sie Console-Logs nach Reload-Events
- Fehler werden geloggt

**Beispiel-Logs:**
```
Vocabulary loaded { canonicalCount: 10, aliasCount: 5 }
Interview config reloaded: 3 profile(s)
Chain roles reloaded: 4 roles
Chain templates reloaded: 2 templates
```

---

## Wartung & Troubleshooting

### Konfigurationsdateien prüfen

**YAML-Syntax prüfen:**
```bash
# Mit yamllint (falls installiert)
yamllint _system/dictionary/interview_config.yaml
```

**Markdown-Syntax prüfen:**
- Manuelle Prüfung der Callout-Struktur
- Prüfen auf korrekte Formatierung

### Häufige Probleme

#### 1. Config wird nicht geladen

**Symptom:** Plugin zeigt Fehler "Config not found".

**Lösung:**
1. Prüfen Sie Pfad in Settings
2. Prüfen Sie, ob Datei existiert
3. Prüfen Sie Datei-Berechtigungen
4. Prüfen Sie Console-Logs für Details

#### 2. YAML-Syntax-Fehler

**Symptom:** Config wird mit Fehlern geladen.

**Lösung:**
1. Prüfen Sie YAML-Syntax (z.B. mit yamllint)
2. Prüfen Sie Console-Logs für Fehlerdetails
3. Last-Known-Good wird verwendet (prüfen Sie Logs)
4. Korrigieren Sie Syntax-Fehler

#### 3. Live-Reload funktioniert nicht

**Symptom:** Änderungen werden nicht übernommen.

**Lösung:**
1. Prüfen Sie, ob Datei-Pfad korrekt ist
2. Warten Sie auf Debounce (200ms)
3. Manuelles Reload über Command
4. Plugin neu laden (disable/enable)

#### 4. Last-Known-Good wird verwendet

**Symptom:** Console zeigt "using-last-known-good".

**Lösung:**
1. Prüfen Sie YAML-Syntax-Fehler
2. Korrigieren Sie Fehler
3. Reload wird automatisch versucht
4. Oder manuelles Reload über Command

### Best Practices

#### 1. Versionierung

**Empfehlung:**
- Verwenden Sie Versionsnummern in Config-Dateien
- Dokumentieren Sie Änderungen
- Testen Sie Änderungen in Test-Vault

#### 2. Backup

**Empfehlung:**
- Regelmäßige Backups der Config-Dateien
- Git-Versionierung empfohlen
- Vor größeren Änderungen Backup erstellen

#### 3. Testing

**Empfehlung:**
- Testen Sie Änderungen in Test-Vault
- Prüfen Sie Console-Logs nach Änderungen
- Validieren Sie YAML-Syntax vor Commit

#### 4. Dokumentation

**Empfehlung:**
- Dokumentieren Sie Custom-Profile
- Dokumentieren Sie Custom-Templates
- Kommentare in YAML-Dateien verwenden

---

## Debug-Commands

### Chain Roles Debug

**Command:** "Mindnet: Debug Chain Roles (Loaded)"

**Output:** Console-Log mit:
- Resolved Path
- Status (loaded/error/using-last-known-good)
- Loaded At (Timestamp)
- Errors/Warnings
- Roles-Übersicht

### Chain Templates Debug

**Command:** "Mindnet: Debug Chain Templates (Loaded)"

**Output:** Console-Log mit:
- Resolved Path
- Status (loaded/error/using-last-known-good)
- Loaded At (Timestamp)
- Errors/Warnings
- Templates-Übersicht

---

## Weitere Ressourcen

- **Benutzerhandbuch:** Endnutzer-Workflows
- **Entwicklerhandbuch:** Code-Struktur und Erweiterungen
- **Architektur-Dokumentation:** System-Übersicht
- **Installation & Deployment:** Setup-Anleitung

---

**Ende des Administratorhandbuchs**