mindnet_obsidian/docs/02_Administratorhandbuch.md

Mindnet Causal Assistant - Administratorhandbuch

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

---

Inhaltsverzeichnis

1. Überblick
2. Plugin-Konfiguration
3. Konfigurationsdateien
4. Pfad-Management
5. Live-Reload
6. 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 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:

# 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:

# 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:

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:

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:

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:

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:

# 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