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](#überblick)
2. [Edge Vocabulary (`edge_vocabulary.md`)](#edge-vocabulary-edge_vocabularymd)
3. [Graph Schema (`graph_schema.md`)](#graph-schema-graph_schemamd)
4. [Interview Config (`interview_config.yaml`)](#interview-config-interview_configyaml)
5. [Chain Roles (`chain_roles.yaml`)](#chain-roles-chain_rolesyaml)
6. [Chain Templates (`chain_templates.yaml`)](#chain-templates-chain_templatesyaml)
7. [Analysis Policies (`analysis_policies.yaml`)](#analysis-policies-analysis_policiesyaml)

---

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

```markdown
# 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

```markdown
# 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

```markdown
# 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

```markdown
# 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](./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

```yaml
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

```yaml
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

```yaml
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

```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
```

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

```yaml
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 Severity-Policies für Findings pro Profil (discovery, decisioning).

### Format

**YAML-Datei** mit `profiles` und `severities` je Finding-Typ.

### Aktuelle Struktur

```yaml
version: 1
profiles:
  discovery:
    severities:
      missing_link_constraints: info
      weak_chain_roles: info
      unmapped_edge_types: info
      missing_slot_*: info
  decisioning:
    severities:
      missing_link_constraints: warn
      weak_chain_roles: info
      unmapped_edge_types: warn
      missing_slot_*: warn
```

### Felder

- **`version`** (number, optional): Config-Version
- **`profiles`** (object, required): Profil-Name → Severity-Overrides
  - **`severities`** (object): Finding-Code → Severity (`info`, `warn`, `error`)

### Verwendung

- **Severity Policy:** `severityPolicy.ts` nutzt diese Datei für Profil-spezifische Severities
- **Profil-Auswahl:** Plugin-Setting `templateMatchingProfile` (`discovery` | `decisioning`)

---

## Template-Matching-Gewichtung (chain_templates.yaml)

### Scoring-Logik (Implementierung)

Die Scoring-Logik ist in `src/analysis/templateMatching.ts` implementiert:

| Komponente | Punkte |
|------------|--------|
| Jeder zugewiesene Slot | +2 |
| Intra-Note-Bonus (alle Slots in derselben Note) | +5 |
| Erfüllter Link (mit erlaubter Edge-Role) | +10 |
| Fehlender Link (wenn `required_links: true`) | -5 |
| Falsche Role (wenn `required_links: true`) | -5 |

### Profil-Parameter (defaults.profiles)

| Parameter | discovery | decisioning | Beschreibung |
|-----------|-----------|-------------|--------------|
| `required_links` | false | true | Links sind Pflicht |
| `min_slots_filled_for_gap_findings` | 2 | 3 | Min. Slots für Gap-Findings |
| `min_score_for_gap_findings` | 8 | 18 | Min. Score für Gap-Findings |

### Matching-Parameter (defaults.matching)

| Parameter | Standard | Beschreibung |
|-----------|----------|--------------|
| `distinct_nodes` | true | Jeder Knoten nur einmal pro Template |
| `required_links` | true | Links erforderlich (profil-überschreibbar) |
| `max_candidate_nodes` | 30 | Max. Candidate Nodes pro Template |
| `max_matches_per_template` | 2 | Max. unterschiedliche Zuordnungen pro Template |
| `max_assignments_collected` | 1000 | Schleifenschutz beim Backtracking |

---

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