mindnet_obsidian/docs/06_Konfigurationsdateien_Referenz.md

Mindnet Causal Assistant - Konfigurationsdateien Referenz

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

---

Inhaltsverzeichnis

1. Überblick
2. Edge Vocabulary (edge_vocabulary.md)
3. Graph Schema (graph_schema.md)
4. Interview Config (interview_config.yaml)
5. Chain Roles (chain_roles.yaml)
6. Chain Templates (chain_templates.yaml)
7. Analysis Policies (analysis_policies.yaml)

---

Überblick

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

• Edge Vocabulary: 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
• Analysis Policies: Policies für Findings (Severity, Unterdrückung)

---

Edge Vocabulary (edge_vocabulary.md)

Zweck

Definiert kanonische Edge-Typen und ihre Aliases für Normalisierung und Lookup.

Format

Markdown-Datei mit Tabellen-Struktur.

Struktur

# Edge Vocabulary

### Kategorie 1

| System-Typ (Canonical) | Inverser Typ | Erlaubte Aliasse (User) | Beschreibung | Kategorie |
| :--- | :--- | :--- | :--- | :--- |
| **`causes`** | `caused_by` | `verursacht`, `führt_zu` | Direkte Kausalität | Kausal |
| **`caused_by`** | `causes` | `ausgelöst_durch`, `wegen` | Umgekehrte Kausalität | Kausal |

### Kategorie 2

| System-Typ (Canonical) | Inverser Typ | Erlaubte Aliasse (User) | Beschreibung | Kategorie |
| :--- | :--- | :--- | :--- | :--- |
| **`influences`** | `influenced_by` | `beeinflusst`, `wirkt_auf` | Einfluss-Beziehung | Einfluss |

Parsing-Regeln

1. H3-Überschriften (###) werden als Kategorien erkannt
2. Tabellen werden geparst:
   • Erste Spalte: Canonical Type (kann mit ** fett formatiert sein)
   • Zweite Spalte: Inverse Type (optional)
   • Dritte Spalte: Aliases (komma-separiert, optional)
   • Weitere Spalten: Beschreibung, Kategorie (optional)
3. Backticked Tokens (\type``) werden extrahiert
4. Header-Zeilen werden übersprungen (enthält "Canonical", "System-Typ", etc.)
5. Leere Zeilen oder Zeilen ohne Tokens werden übersprungen

Beispiel

# Edge Vocabulary

### Kausale Beziehungen

| System-Typ (Canonical) | Inverser Typ | Erlaubte Aliasse (User) | Beschreibung |
| :--- | :--- | :--- | :--- |
| **`causes`** | `caused_by` | `verursacht`, `führt_zu` | Direkte Kausalität |
| **`caused_by`** | `causes` | `ausgelöst_durch`, `wegen` | Umgekehrte Kausalität |

### Einfluss-Beziehungen

| System-Typ (Canonical) | Inverser Typ | Erlaubte Aliasse (User) | Beschreibung |
| :--- | :--- | :--- | :--- |
| **`influences`** | `influenced_by` | `beeinflusst`, `wirkt_auf` | Einfluss-Beziehung |

Verwendung

• Normalisierung: vocabulary.normalize("ausgelöst_durch") → { canonical: "caused_by", inverse: "causes" }
• Lookup: vocabulary.getCanonical("verursacht") → "causes"
• Inverse: vocabulary.getInverse("causes") → "caused_by"

---

Graph Schema (graph_schema.md)

Zweck

Definiert Empfehlungen für Edge-Typen basierend auf Source- und Target-Note-Typen.

Format

Markdown-Datei mit Sections und Tabellen.

Struktur

# Graph Schema

## Source: `experience`

| Target Type | Typical | Prohibited |
| :--- | :--- | :--- |
| `insight` | `causes`, `influences` | `part_of`, `instance_of` |
| `decision` | `influences` | `causes` |

## Source: `insight`

| Target Type | Typical | Prohibited |
| :--- | :--- | :--- |
| `decision` | `causes`, `enables` | `influences` |

Parsing-Regeln

1. H2-Überschriften mit Pattern ## Source: \type`` werden als Source-Typ erkannt
2. Tabellen werden geparst:
   • Erste Spalte: Target Type (in Backticks)
   • Zweite Spalte: Typical Edge Types (komma-separiert)
   • Dritte Spalte: Prohibited Edge Types (komma-separiert)
3. Header-Zeilen werden übersprungen
4. Leere Zeilen werden übersprungen

Beispiel

# Graph Schema

## Source: `experience`

| Target Type | Typical | Prohibited |
| :--- | :--- | :--- |
| `insight` | `causes`, `influences` | `part_of` |
| `decision` | `influences` | `causes` |

## Source: `insight`

| Target Type | Typical | Prohibited |
| :--- | :--- | :--- |
| `decision` | `causes`, `enables` | `influences` |

Verwendung

• Edge-Type-Selector: Zeigt Empfehlungen basierend auf Source-Note-Type
• Warnungen: Zeigt Warnungen bei prohibited Types
• Lookup: schema.getTypicalEdgeTypes("experience", "insight") → ["causes", "influences"]

---

Interview Config (interview_config.yaml)

Zweck

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

Format

YAML-Datei mit strukturierter Hierarchie.

Vollständige Dokumentation

→ Interview_Config_Guide.md - Vollständige Anleitung mit:

• Alle Step-Typen (capture_frontmatter, capture_text, capture_text_line, loop, review, etc.)
• WP-26 Features (Section Types, Block-IDs, Referenzen)
• Beispiele für verschiedene Note-Typen (experience, insight, decision, principle)
• Best Practices & Patterns
• GenAI-Prompt-Template

Kurzübersicht

Root-Level

• version (string, optional): Config-Version (aktuell: 3)
• frontmatter_whitelist (array of strings, optional): Erlaubte Frontmatter-Keys
• ui_defaults (object, optional): Standard-UI-Einstellungen
• profiles (array, required): Liste von Profilen

Profile

• key (string, required): Eindeutiger Profil-Schlüssel
• label (string, required): Anzeige-Name
• note_type (string, required): Note-Type (z.B. experience, insight, decision)
• group (string, optional): Gruppierung für UI
• defaults (object, optional): Standardwerte (status, folder, chunking_profile, etc.)
• edging (object, optional): Semantic Mapping Konfiguration (mode, wrapperCalloutType, etc.)
• steps (array, required): Liste von Steps

Step-Typen

• capture_frontmatter: Frontmatter-Feld erfassen
• capture_text: Mehrzeiligen Text erfassen (mit Section-Header)
• capture_text_line: Einzeiligen Text erfassen (optional mit Heading-Level)
• loop: Wiederholbare Steps für Listen
• review: Review & Apply Step
• instruction: Anweisung anzeigen
• llm_dialog: LLM-Dialog (experimentell)
• entity_picker: Entity-Auswahl (experimentell)

WP-26 Features (nur für capture_text und capture_text_line)

• section_type (string, optional): Section-Type (überschreibt note_type)
• block_id (string, optional): Explizite Block-ID
• generate_block_id (boolean, optional): Automatische Block-ID-Generierung
• references (array, optional): Explizite Referenzen zu vorherigen Sections

Beispiel

version: 3

profiles:
  - key: experience_basic
    group: experience
    label: "Erfahrung (Basis)"
    note_type: experience
    defaults:
      status: active
      folder: "03_experience"
    edging:
      mode: both
    steps:
      - id: title
        kind: capture_frontmatter
        field: title
        label: "Titel"
        required: true

      - id: context
        kind: capture_text
        section: "## 📖 Kontext"
        label: "Kontext"
        required: true
        prompt: "Beschreibe den Kontext"
        section_type: experience
        generate_block_id: true

      - id: review
        kind: review
        label: "Review & Apply"
        checks:
          - lint_current_note
          - missing_targets

Verwendung

• Profil-Auswahl: Profile werden in ProfileSelectionModal angezeigt
• Wizard: Steps werden als Wizard-Steps angezeigt
• Frontmatter: Frontmatter wird mit Whitelist generiert
• WP-26: Section-Types und Block-IDs werden für Edge-Vorschläge verwendet

Wann erscheint der Dialog „Verbindungen bearbeiten“ (Sektions-Links)?

Der Dialog zum Ändern der Sektions-Verbindungen (Section-Edges) erscheint beim Klick auf „Apply & Finish“ im Review-Step – aber nur wenn beides erfüllt ist:

1. Mindestens zwei Sections im Profil
   Das gewählte Interview-Profil muss mindestens zwei Steps haben, die eine Section erzeugen:

   • capture_text mit Feld section (z. B. section: "## 📖 Kontext").
   • capture_text_line mit heading_level.enabled: true und (block_id oder generate_block_id: true).

2. Edge-Vocabulary geladen
   Die Datei edge_vocabulary.md muss existieren und der Pfad in den Plugin-Einstellungen stimmen (z. B. _system/dictionary/edge_vocabulary.md).

Beispiel: Ein Profil mit drei capture_text-Steps mit je section (z. B. Kontext, Auslöser, Transformation) erzeugt drei Sections → der Dialog erscheint. Optional können Sie section_type, block_id oder generate_block_id setzen, damit Block-IDs und Edge-Vorschläge aus dem Graph-Schema genutzt werden.

---

Chain Roles (chain_roles.yaml)

Zweck

Mappt Edge-Typen zu kausalen Rollen für Template Matching.

Format

YAML-Datei mit strukturierter Hierarchie.

Struktur

version: "1.0"

roles:
  causal:
    description: "Direkte kausale Beziehungen"
    edge_types:
      - causes
      - caused_by
      - resulted_in
  influences:
    description: "Einfluss-Beziehungen"
    edge_types:
      - influences
      - affects
  enables_constraints:
    description: "Ermöglicht/Beschränkt-Beziehungen"
    edge_types:
      - enables
      - constrains
  provenance:
    description: "Herkunfts-Beziehungen"
    edge_types:
      - derived_from
      - based_on

Felder

Root-Level

• version (string, optional): Config-Version
• roles (object, required): Mapping von Rollen-Namen zu Rollen-Definitionen

Role

• description (string, optional): Beschreibung der Rolle
• edge_types (array of strings, required): Liste von Edge-Typen, die zu dieser Rolle gehören

Standard-Rollen

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

Beispiel

version: "1.0"

roles:
  causal:
    description: "Direkte kausale Beziehungen"
    edge_types:
      - causes
      - caused_by
      - resulted_in
      - resulted_from
  influences:
    description: "Einfluss-Beziehungen"
    edge_types:
      - influences
      - affects
      - impacts
  enables_constraints:
    description: "Ermöglicht/Beschränkt-Beziehungen"
    edge_types:
      - enables
      - constrains
      - limits
  provenance:
    description: "Herkunfts-Beziehungen"
    edge_types:
      - derived_from
      - based_on
      - originates_from

Verwendung

• Template Matching: Edge-Typen werden zu Rollen gemappt für Link-Constraints
• Findings: no_causal_roles Finding wird generiert, wenn keine causal Rollen gefunden werden
• Lookup: chainRoles.getRoleForEdgeType("causes") → "causal"

---

Chain Templates (chain_templates.yaml)

Zweck

Definiert vordefinierte Kettenmuster für Template Matching.

Format

YAML-Datei mit strukturierter Hierarchie.

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

Felder

Root-Level

• version (string, optional): Config-Version
• defaults (object, optional): Standardwerte
  • matching (object, optional): Standard-Matching-Parameter
    • required_links (boolean, optional): Ob Links erforderlich sind (Standard: false)
  • profiles (object, optional): Profil-spezifische Defaults
    • discovery (object, optional): Discovery-Profil-Parameter
    • decisioning (object, optional): Decisioning-Profil-Parameter
• templates (array, required): Liste von Templates

Template

• name (string, required): Template-Name
• description (string, optional): Beschreibung
• slots (array, required): Slot-Definitionen
• links (array, optional): Link-Constraints
• matching (object, optional): Matching-Parameter (überschreibt Defaults)
  • required_links (boolean, optional): Ob Links erforderlich sind

Slot

• id (string, required): Slot-ID
• allowed_node_types (array of strings, required): Erlaubte Note-Types für diesen Slot

Link

• from (string, required): Source-Slot-ID
• to (string, required): Target-Slot-ID
• allowed_edge_roles (array of strings, required): Erlaubte Edge-Rollen

Beispiel

version: "1.0"

defaults:
  matching:
    required_links: false
  profiles:
    discovery:
      required_links: false
      min_slots_filled_for_gap_findings: 1
      min_score_for_gap_findings: 0
    decisioning:
      required_links: true
      min_slots_filled_for_gap_findings: 2
      min_score_for_gap_findings: 10

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

  - name: loop_learning
    description: "Learning loop: experience → learning → behavior → feedback"
    slots:
      - id: experience
        allowed_node_types: ["experience"]
      - id: learning
        allowed_node_types: ["insight", "learning"]
      - id: behavior
        allowed_node_types: ["decision", "action"]
      - id: feedback
        allowed_node_types: ["experience", "event"]
    links:
      - from: experience
        to: learning
        allowed_edge_roles: ["causal", "influences"]
      - from: learning
        to: behavior
        allowed_edge_roles: ["causal"]
      - from: behavior
        to: feedback
        allowed_edge_roles: ["causal", "influences"]
      - from: feedback
        to: experience
        allowed_edge_roles: ["causal", "influences"]

Verwendung

• Template Matching: Templates werden gegen lokalen Subgraph gematcht
• Findings: missing_slot_* Findings werden generiert, wenn Slots fehlen
• Link Constraints: missing_link_constraints Finding wird generiert, wenn Links fehlen (wenn required_links=true)

---

Analysis Policies (analysis_policies.yaml)

Zweck

Definiert Policies für Findings (Severity, Unterdrückung, etc.).

Format

YAML-Datei (geplant, noch nicht vollständig implementiert).

Geplante Struktur

version: "1.0"

findings:
  missing_slot_*:
    default_severity: warn
    profiles:
      discovery:
        severity: info
        suppress_if:
          - slots_filled < 2
      decisioning:
        severity: warn
        suppress_if: []
  dangling_target:
    default_severity: error
    suppress_if: []
  missing_link_constraints:
    default_severity: warn
    suppress_if:
      - required_links == false
  no_causal_roles:
    default_severity: info
    suppress_if: []

Felder (geplant)

Root-Level

• version (string, optional): Config-Version
• findings (object, required): Mapping von Finding-Codes zu Policies

Finding Policy

• default_severity (string, required): Standard-Severity (error, warn, info)
• profiles (object, optional): Profil-spezifische Overrides
  • discovery (object, optional): Discovery-Profil-Parameter
  • decisioning (object, optional): Decisioning-Profil-Parameter
• suppress_if (array, optional): Bedingungen für Unterdrückung

Status

Noch nicht vollständig implementiert. Aktuell wird Severity-Policy teilweise in severityPolicy.ts gehandhabt.

---

Validierung & Fehlerbehandlung

YAML-Dateien

• Syntax-Fehler: Werden beim Laden erkannt und geloggt
• Last-Known-Good: Letzte gültige Config wird bei Fehlern verwendet
• Warnings: Ungültige Felder werden als Warnings geloggt, nicht als Fehler

Markdown-Dateien

• Parsing-Fehler: Werden beim Laden erkannt und geloggt
• Fehlende Felder: Werden ignoriert oder mit Defaults gefüllt
• Warnings: Ungültige Zeilen werden übersprungen

Live-Reload

• Debounced: 200ms Delay für Performance
• Automatisch: Bei Dateiänderungen
• Manuell: Über Commands möglich

---

Best Practices

Versionierung

• Verwenden Sie Versionsnummern in Config-Dateien
• Dokumentieren Sie Änderungen
• Testen Sie Änderungen in Test-Vault

Struktur

• Verwenden Sie klare, konsistente Namen
• Kommentieren Sie komplexe Konfigurationen
• Gruppieren Sie verwandte Einträge

Wartung

• Regelmäßige Backups
• Git-Versionierung empfohlen
• Dokumentation von Custom-Konfigurationen

---

Ende der Konfigurationsdateien Referenz