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

### Struktur

```yaml
version: "2.0"
frontmatter_whitelist:
  - tags
  - status

profiles:
  - key: experience_basic
    label: "Erfahrung (Basis)"
    note_type: experience
    description: "Basic experience profile"
    defaults:
      folder: "experiences"
      tags: ["experience"]
    steps:
      - id: context
        prompt: "Beschreibe den Kontext"
        input_type: textarea
        required: true
      - id: details
        prompt: "Weitere Details"
        input_type: textarea
        required: false
    post_run:
      edger: true
```

### Felder

#### Root-Level

- **`version`** (string, optional): Config-Version (Standard: "2.0")
- **`frontmatter_whitelist`** (array of strings, optional): Erlaubte Frontmatter-Keys (zusätzlich zu Standard)
- **`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`)
- **`description`** (string, optional): Beschreibung
- **`defaults`** (object, optional): Standardwerte
  - **`folder`** (string, optional): Standard-Ordner
  - **`tags`** (array of strings, optional): Standard-Tags
  - Weitere Felder möglich
- **`steps`** (array, optional): Interview-Steps
- **`post_run`** (object, optional): Post-Run-Actions
  - **`edger`** (boolean, optional): Semantic Mapping Builder ausführen

#### Step

- **`id`** (string, required): Eindeutige Step-ID
- **`prompt`** (string, required): Prompt-Text
- **`input_type`** (string, required): Input-Typ (`text`, `textarea`, `select`, etc.)
- **`required`** (boolean, optional): Ob Step erforderlich ist
- **`default`** (string, optional): Standardwert
- **`options`** (array, optional): Optionen für `select` Input-Type
- **`loop`** (object, optional): Loop-Konfiguration
  - **`key`** (string, required): Loop-Key
  - **`prompt`** (string, required): Loop-Prompt
  - **`min_items`** (number, optional): Minimale Anzahl Items
  - **`max_items`** (number, optional): Maximale Anzahl Items
  - **`nested_loops`** (array, optional): Verschachtelte Loops

### Beispiel

```yaml
version: "2.0"
frontmatter_whitelist:
  - tags
  - status

profiles:
  - key: experience_basic
    label: "Erfahrung (Basis)"
    note_type: experience
    description: "Basic experience profile"
    defaults:
      folder: "experiences"
      tags: ["experience"]
    steps:
      - id: context
        prompt: "Beschreibe den Kontext"
        input_type: textarea
        required: true
      - id: events
        prompt: "Wichtige Ereignisse"
        input_type: textarea
        loop:
          key: events
          prompt: "Ereignis"
          min_items: 1
          max_items: 10
    post_run:
      edger: true

  - key: insight_basic
    label: "Einsicht (Basis)"
    note_type: insight
    defaults:
      folder: "insights"
    steps:
      - id: insight
        prompt: "Beschreibe die Einsicht"
        input_type: textarea
        required: true
```

### Verwendung

- **Profil-Auswahl:** Profile werden in ProfileSelectionModal angezeigt
- **Wizard:** Steps werden als Wizard-Steps angezeigt
- **Frontmatter:** Frontmatter wird mit Whitelist generiert
- **Post-Run:** Actions werden nach Wizard ausgeführt

---

## 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 Policies für Findings (Severity, Unterdrückung, etc.).

### Format

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

### Geplante Struktur

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