mindnet_obsidian/docs/07_Event_Handler_Commands.md

# Mindnet Causal Assistant - Event Handler & Commands Referenz

> **Version:** 1.0.0  
> **Stand:** 2025-01-XX  
> **Zielgruppe:** Entwickler, Administratoren

---

## Inhaltsverzeichnis

1. [Event Handler](#event-handler)
2. [Commands](#commands)
3. [Settings & Konfiguration](#settings--konfiguration)

---

## Event Handler

Das Plugin registriert mehrere Event Handler für automatische Funktionen:

### 1. Vault Modify Event

**Zweck:** Live-Reload von Konfigurationsdateien

**Registriert:** `this.app.vault.on("modify", ...)`

**Funktionsweise:**
- Überwacht alle Dateiänderungen im Vault
- Prüft, ob geänderte Datei einer Config-Datei entspricht
- Debounced Reload (200ms Delay)
- Lädt Config automatisch neu

**Überwachte Dateien:**
- `edge_vocabulary.md` (via `edgeVocabularyPath`)
- `interview_config.yaml` (via `interviewConfigPath`)
- `graph_schema.md` (via `graphSchemaPath`)
- `chain_roles.yaml` (via `chainRolesPath`)
- `chain_templates.yaml` (via `chainTemplatesPath`)

**Code:**
```typescript
this.registerEvent(
  this.app.vault.on("modify", async (file: TFile) => {
    // Prüft Datei-Pfad
    // Debounced Reload
    // Lädt Config neu
  })
);
```

### 2. Vault Create Event

**Zweck:** Note Adoption für neu erstellte Notes

**Registriert:** `this.app.vault.on("create", ...)` (nach `onLayoutReady`)

**Funktionsweise:**
- Wird nur ausgeführt, wenn `adoptNewNotesInEditor` aktiviert ist
- Prüft, ob neue Datei ein Adopt-Candidate ist
- Evaluates Adoption Confidence
- Zeigt Adoption-Modal (abhängig von Confidence)
- Startet Profil-Auswahl

**Bedingungen:**
- Datei muss `.md` Extension haben
- Datei darf nicht unter `.obsidian/` sein
- Datei muss klein sein (`adoptMaxChars`)
- Datei darf keine Frontmatter-ID haben

**Code:**
```typescript
this.app.workspace.onLayoutReady(() => {
  this.registerEvent(
    this.app.vault.on("create", async (file: TFile) => {
      await this.handleFileCreate(file);
    })
  );
});
```

### 3. Markdown Post Processor

**Zweck:** Unresolved Link Handling in Reading View

**Registriert:** `this.registerMarkdownPostProcessor(...)`

**Funktionsweise:**
- Wird nur ausgeführt, wenn `interceptUnresolvedLinkClicks` aktiviert ist
- Findet alle `a.internal-link` Elemente
- Prüft, ob Link unresolved ist
- Fügt Click-Handler hinzu
- Bypass-Modifier wird respektiert

**Bypass-Modifier:**
- Standard: `Alt` (konfigurierbar via `bypassModifier`)
- Wenn gedrückt: Obsidian behandelt Link normal

**Code:**
```typescript
this.registerMarkdownPostProcessor((el, ctx) => {
  const links = Array.from(el.querySelectorAll("a.internal-link"));
  for (const link of links) {
    // Prüft unresolved
    // Fügt Click-Handler hinzu
  }
});
```

### 4. DOM Click Event

**Zweck:** Unresolved Link Handling in Editor (Live Preview/Source)

**Registriert:** `this.registerDomEvent(document, "click", ...)`

**Funktionsweise:**
- Wird nur ausgeführt, wenn `interceptUnresolvedLinkClicks` aktiviert ist
- Prüft, ob Follow-Modifier gedrückt ist
- Prüft, ob Cursor in Wikilink ist
- Prüft, ob Link unresolved ist
- Startet Profil-Auswahl

**Follow-Modifier:**
- Standard: `Ctrl` (konfigurierbar via `editorFollowModifier`)
- Muss gedrückt sein, damit Handler aktiviert wird

**Code:**
```typescript
this.registerDomEvent(document, "click", async (evt: MouseEvent) => {
  // Prüft Follow-Modifier
  // Prüft Cursor-Position
  // Prüft Wikilink
  // Startet Profil-Auswahl
});
```

---

## Commands

Das Plugin registriert 11 Commands:

### 1. Mindnet: Reload edge vocabulary

**ID:** `mindnet-reload-edge-vocabulary`

**Typ:** Callback Command

**Funktionsweise:**
- Lädt `edge_vocabulary.md` neu
- Parst Markdown zu EdgeVocabulary
- Erstellt neue Vocabulary-Instanz
- Aktualisiert Cache
- Zeigt Notice mit Stats

**Verwendung:**
- Nach Änderungen an `edge_vocabulary.md`
- Für Debugging
- Manuelles Reload (falls automatisches Reload nicht funktioniert)

### 2. Mindnet: Validate current note

**ID:** `mindnet-validate-current-note`

**Typ:** Callback Command

**Funktionsweise:**
- Lädt Vocabulary (falls nicht geladen)
- Ruft `LintEngine.lintCurrentNote()` auf
- Zählt Findings nach Severity
- Zeigt Notice mit Summary
- Loggt Findings in Console

**Settings:**
- `showCanonicalHints`: Zeigt Canonical-Hints als INFO-Findings

**Output:**
- Notice: `"Lint: X errors, Y warnings, Z info"`
- Console: Detaillierte Findings-Liste

### 3. Mindnet: Export graph

**ID:** `mindnet-export-graph`

**Typ:** Callback Command

**Funktionsweise:**
- Lädt Vocabulary (falls nicht geladen)
- Baut Graph aus Vault
- Serialisiert zu JSON
- Schreibt Export-Datei
- Zeigt Notice

**Settings:**
- `exportPath`: Pfad für Export-Datei (Standard: `_system/exports/graph_export.json`)

**Output:**
- JSON-Datei mit Nodes und Edges
- Notice: `"Graph exported to <path>"`

### 4. Mindnet: Show chains from current note

**ID:** `mindnet-show-chains-from-current-note`

**Typ:** Callback Command

**Funktionsweise:**
- Extrahiert Frontmatter-ID aus aktueller Note
- Baut Graph aus Vault
- Baut Index für Traversal
- Führt Traversal aus (forward/backward/both)
- Rendert Chain Report
- Schreibt Report-Datei
- Öffnet Report-Datei

**Settings:**
- `chainDirection`: `"forward"` | `"backward"` | `"both"`
- `maxHops`: Maximale Anzahl Hops (Standard: 3)

**Output:**
- Markdown-Report: `_system/exports/chain_report.md`
- Notice: `"Chains: X paths, Y nodes, Z warnings"`

### 5. Mindnet: Create note from profile

**ID:** `mindnet-create-note-from-profile`

**Typ:** Callback Command

**Funktionsweise:**
- Lädt Interview Config (falls nicht geladen)
- Prüft, ob Profile verfügbar sind
- Extrahiert initialen Titel aus Selection (falls vorhanden)
- Öffnet ProfileSelectionModal
- Erstellt Note nach Profil-Auswahl
- Startet Wizard (falls aktiviert)

**Settings:**
- `autoStartInterviewOnCreate`: Ob Wizard automatisch startet
- `defaultNotesFolder`: Standard-Ordner für neue Notes

**Workflow:**
1. Profile-Selection-Modal öffnet sich
2. Profil wählen
3. Titel eingeben
4. Ordner wählen (optional)
5. Note wird erstellt
6. Wizard startet (falls aktiviert)

### 6. Mindnet: Edge-Type ändern

**ID:** `mindnet-change-edge-type`

**Typ:** Editor Callback Command

**Funktionsweise:**
- Erkennt Kontext (Cursor-Position, Selection)
- Prüft, ob Kontext erkannt werden kann
- Ruft `changeEdgeTypeForLinks()` auf
- Zeigt Edge-Type-Selector
- Aktualisiert Links

**Kontext-Modi:**
- `single-link`: Cursor in einem Link
- `selection-links`: Auswahl enthält Links
- `create-link`: Neuer Link soll erstellt werden
- `whole-note`: Ganze Note (falls kein spezifischer Kontext)

**Settings:**
- `inlineMicroEnabled`: Inline Micro-Suggester aktivieren
- `inlineMaxAlternatives`: Maximale Anzahl Alternativen

### 7. Mindnet: Debug Chain Roles (Loaded)

**ID:** `mindnet-debug-chain-roles`

**Typ:** Callback Command

**Funktionsweise:**
- Lädt Chain Roles (falls nicht geladen)
- Formatiert Debug-Output
- Loggt in Console
- Zeigt Notice

**Output:**
- Console: Detaillierte Debug-Info
  - Resolved Path
  - Status (loaded/error/using-last-known-good)
  - Loaded At (Timestamp)
  - Errors/Warnings
  - Roles-Übersicht
- Notice: `"Chain roles debug info logged to console (F12)"`

### 8. Mindnet: Debug Chain Templates (Loaded)

**ID:** `mindnet-debug-chain-templates`

**Typ:** Callback Command

**Funktionsweise:**
- Lädt Chain Templates (falls nicht geladen)
- Formatiert Debug-Output
- Loggt in Console
- Zeigt Notice

**Output:**
- Console: Detaillierte Debug-Info
  - Resolved Path
  - Status (loaded/error/using-last-known-good)
  - Loaded At (Timestamp)
  - Errors/Warnings
  - Templates-Übersicht
- Notice: `"Chain templates debug info logged to console (F12)"`

### 9. Mindnet: Fix Findings (Current Section)

**ID:** `mindnet-fix-findings`

**Typ:** Editor Callback Command

**Funktionsweise:**
- Lädt Chain Roles (falls nicht geladen)
- Lädt Interview Config (falls nicht geladen)
- Ruft `executeFixFindings()` auf
- Analysiert aktuelle Section
- Generiert Findings
- Zeigt verfügbare Fix-Actions
- Führt ausgewählte Action aus

**Fix-Actions:**
- **Create Missing Note:** Erstellt fehlende Note
- **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

**Settings:**
- `fixActions.createMissingNote.mode`: Modus für fehlende Notes
- `fixActions.createMissingNote.defaultTypeStrategy`: Strategie für Note-Type
- `fixActions.createMissingHeading.level`: Heading-Level
- `fixActions.promoteCandidate.keepOriginal`: Original behalten

### 10. Mindnet: Inspect Chains (Current Section)

**ID:** `mindnet-inspect-chains`

**Typ:** Editor Callback Command

**Funktionsweise:**
- Lädt Chain Roles (falls nicht geladen)
- Lädt Chain Templates (falls nicht geladen)
- Ruft `executeInspectChains()` auf
- Extrahiert Section-Context
- Baut Graph-Index
- Führt Traversal aus
- Führt Template Matching aus
- Generiert Findings
- Loggt Report in Console

**Settings:**
- `chainInspectorIncludeCandidates`: Ob Candidate-Edges einbezogen werden
- `chainInspectorMaxTemplateMatches`: Maximale Anzahl Template Matches
- `templateMatchingProfile`: `"discovery"` | `"decisioning"`

**Output:**
- Console: Detaillierter Chain Inspector Report
  - Context (file, heading)
  - Neighbors (incoming/outgoing)
  - Paths (forward/backward)
  - Template Matches
  - Findings
- Notice: `"Chain inspection complete. Check console (F12) for report."`

### 11. Mindnet: Build semantic mapping blocks (by section)

**ID:** `mindnet-build-semantic-mappings`

**Typ:** Editor Callback Command

**Funktionsweise:**
- Erkennt Kontext (Cursor-Position, Selection)
- Falls spezifischer Kontext: Verwendet Edge-Type-Selector
- Sonst: Verarbeitet ganze Note
- Prüft, ob Overwrite erlaubt ist
- Ruft `buildSemanticMappings()` auf
- Extrahiert existierende Mappings
- Parst Sections
- Extrahiert Links
- Weist Edge-Types zu
- Baut Mapping-Blöcke
- Aktualisiert Note

**Settings:**
- `mappingWrapperCalloutType`: Callout-Typ für Wrapper (Standard: `"abstract"`)
- `mappingWrapperTitle`: Titel für Wrapper (Standard: `"🕸️ Semantic Mapping"`)
- `mappingWrapperFolded`: Ob Wrapper gefaltet ist (Standard: `true`)
- `defaultEdgeType`: Standard-Edge-Type
- `unassignedHandling`: `"prompt"` | `"none"` | `"defaultType"` | `"advisor"`
- `allowOverwriteExistingMappings`: Ob existierende Mappings überschrieben werden dürfen

**Output:**
- Notice: `"Sections: X processed, Y with mappings | Links: Z total | Mappings: A kept, B new"`

---

## Settings & Konfiguration

### Alle Settings

| Setting | Typ | Standard | Beschreibung |
|---------|-----|----------|--------------|
| **Pfad-Settings** |
| `edgeVocabularyPath` | string | `"_system/dictionary/edge_vocabulary.md"` | Pfad zum Edge-Vokabular |
| `graphSchemaPath` | string | `"_system/dictionary/graph_schema.md"` | Pfad zum Graph-Schema |
| `interviewConfigPath` | string | `"_system/dictionary/interview_config.yaml"` | Pfad zur Interview-Config |
| `chainRolesPath` | string | `"_system/dictionary/chain_roles.yaml"` | Pfad zu Chain Roles |
| `chainTemplatesPath` | string | `"_system/dictionary/chain_templates.yaml"` | Pfad zu Chain Templates |
| `analysisPoliciesPath` | string | `"_system/dictionary/analysis_policies.yaml"` | Pfad zu Analysis Policies |
| **Graph & Chain Settings** |
| `maxHops` | number | `3` | Maximale Anzahl Hops für Traversal |
| `strictMode` | boolean | `false` | Strict Mode (noch nicht vollständig implementiert) |
| `showCanonicalHints` | boolean | `false` | Zeigt Canonical-Hints in Lint-Findings |
| `chainDirection` | string | `"forward"` | Traversal-Richtung: `"forward"` \| `"backward"` \| `"both"` |
| **Interview Settings** |
| `autoStartInterviewOnCreate` | boolean | `false` | Wizard automatisch nach Note-Erstellung starten |
| **Unresolved Link Settings** |
| `interceptUnresolvedLinkClicks` | boolean | `true` | Unresolved Links abfangen |
| `autoStartOnUnresolvedClick` | boolean | `true` | Wizard automatisch nach Link-Klick starten |
| `bypassModifier` | string | `"Alt"` | Bypass-Modifier für Reading View: `"Alt"` \| `"Ctrl"` \| `"Shift"` \| `"None"` |
| `editorFollowModifier` | string | `"Ctrl"` | Follow-Modifier für Editor: `"Alt"` \| `"Ctrl"` \| `"Shift"` \| `"None"` |
| `waitForFirstModifyAfterCreate` | boolean | `true` | Warten auf erste Änderung nach Erstellung (für Templater) |
| `waitForModifyTimeoutMs` | number | `1200` | Timeout für Warten auf Änderung (ms) |
| `debugLogging` | boolean | `false` | Debug-Logging für Unresolved Link Handling |
| **Note Adoption Settings** |
| `adoptNewNotesInEditor` | boolean | `true` | Neue Notes automatisch adoptieren |
| `adoptMaxChars` | number | `200` | Maximale Content-Länge für Adoption-Candidate |
| `adoptConfirmMode` | string | `"onlyLowConfidence"` | Adoption-Confirmation-Modus: `"always"` \| `"onlyLowConfidence"` \| `"never"` |
| `highConfidenceWindowMs` | number | `3000` | Zeitfenster für High-Confidence-Adoption (ms) |
| **Semantic Mapping Settings** |
| `mappingWrapperCalloutType` | string | `"abstract"` | Callout-Typ für Mapping-Wrapper |
| `mappingWrapperTitle` | string | `"🕸️ Semantic Mapping"` | Titel für Mapping-Wrapper |
| `mappingWrapperFolded` | boolean | `true` | Ob Mapping-Wrapper gefaltet ist |
| `defaultEdgeType` | string | `""` | Standard-Edge-Type |
| `unassignedHandling` | string | `"prompt"` | Handling für unzugewiesene Links: `"prompt"` \| `"none"` \| `"defaultType"` \| `"advisor"` |
| `allowOverwriteExistingMappings` | boolean | `false` | Existierende Mappings überschreiben dürfen |
| `defaultNotesFolder` | string | `""` | Standard-Ordner für neue Notes |
| **Inline Micro Edge Suggester Settings** |
| `inlineMicroEnabled` | boolean | `true` | Inline Micro-Suggester aktivieren |
| `inlineMaxAlternatives` | number | `6` | Maximale Anzahl Alternativen |
| `inlineCancelBehavior` | string | `"keep_link"` | Verhalten bei Cancel: `"keep_link"` |
| **Export Settings** |
| `exportPath` | string | `"_system/exports/graph_export.json"` | Pfad für Graph-Export |
| **Chain Inspector Settings** |
| `chainInspectorIncludeCandidates` | boolean | `false` | Candidate-Edges in Chain Inspector einbeziehen |
| `chainInspectorMaxTemplateMatches` | number | `3` | Maximale Anzahl Template Matches |
| `templateMatchingProfile` | string | `"discovery"` | Template-Matching-Profil: `"discovery"` \| `"decisioning"` |
| **Fix Actions Settings** |
| `fixActions.createMissingNote.mode` | string | `"skeleton_only"` | Modus für fehlende Notes: `"skeleton_only"` \| `"create_and_open_profile_picker"` \| `"create_and_start_wizard"` |
| `fixActions.createMissingNote.defaultTypeStrategy` | string | `"profile_picker"` | Strategie für Note-Type: `"profile_picker"` \| `"inference_then_picker"` \| `"default_concept_no_prompt"` |
| `fixActions.createMissingNote.includeZones` | string | `"none"` | Zonen einbeziehen: `"none"` \| `"note_links_only"` \| `"candidates_only"` \| `"both"` |
| `fixActions.createMissingHeading.level` | number | `2` | Heading-Level für neue Headings |
| `fixActions.promoteCandidate.keepOriginal` | boolean | `true` | Original bei Candidate-Promotion behalten |

### Settings-Wirkungsweise

#### Pfad-Settings

**Wirkungsweise:**
- Werden beim Plugin-Start geladen
- Werden für Live-Reload verwendet
- Werden für Config-Loading verwendet
- Pfade sind vault-relativ (forward slashes)

**Änderung:**
- Settings → Community Plugins → Mindnet Causal Assistant
- Pfad ändern
- Settings speichern
- Plugin lädt Config automatisch neu

#### Feature-Settings

**Wirkungsweise:**
- Steuern automatische Funktionen
- Werden bei jedem Aufruf geprüft
- Können zur Laufzeit geändert werden

**Beispiele:**
- `interceptUnresolvedLinkClicks`: Aktiviert/deaktiviert Link-Intercept
- `adoptNewNotesInEditor`: Aktiviert/deaktiviert Note-Adoption
- `autoStartInterviewOnCreate`: Aktiviert/deaktiviert automatischen Wizard-Start

#### Fix-Actions-Settings

**Wirkungsweise:**
- Steuern Fix-Action-Verhalten
- Werden bei `executeFixFindings()` verwendet
- Bestimmen, welche Actions verfügbar sind

**Beispiele:**
- `fixActions.createMissingNote.mode`: Bestimmt, wie fehlende Notes erstellt werden
- `fixActions.createMissingHeading.level`: Bestimmt Heading-Level für neue Headings

---

## Zusammenfassung

### Event Handler

- **Vault Modify:** Live-Reload von Config-Dateien
- **Vault Create:** Note Adoption
- **Markdown Post Processor:** Unresolved Link Handling (Reading View)
- **DOM Click Event:** Unresolved Link Handling (Editor)

### Commands

- **11 Commands** registriert
- **3 Editor Commands:** Erfordern aktiven Editor
- **8 Callback Commands:** Können überall ausgeführt werden

### Settings

- **40+ Settings** verfügbar
- **6 Pfad-Settings:** Für Config-Dateien
- **34 Feature-Settings:** Für Funktionalität
- **Alle Settings** sind in Settings Tab konfigurierbar

---

**Ende der Event Handler & Commands Referenz**