# WP-26 Plugin-Schnittstellenspezifikation

**Version:** 1.0  
**Datum:** 25. Januar 2026  
**Status:** Implementierungsleitfaden für mindnet_obsidian Plugin  
**Basis:** Lastenheft WP-26 v1.3 (Section Types & Intra-Note-Edges)

---

## 1. Überblick

Diese Spezifikation definiert die **Schnittstelle zwischen dem mindnet-Backend und dem Obsidian-Plugin** für WP-26 Features. Sie beschreibt:

1. **Backend-Erwartungen:** Welche Markdown-Formate das Backend interpretiert
2. **Plugin-Anforderungen:** Was das Plugin implementieren muss
3. **Betroffene Bereiche:** Interview, Editing, Chain Workbench, Edge Parsing, etc.

---

## 2. Backend-Schnittstelle (Markdown-Formate)

### 2.1 Section-Type-Callout (`[!section]`)

**Syntax:**
```markdown
## Überschrift ^block-id
> [!section] type-name
```

**Backend-Interpretation:**
- Callout kann **an beliebiger Stelle** innerhalb der Section stehen
- Section-Type gilt **retroaktiv** ab der Überschrift
- Scope endet bei nächster Überschrift **gleicher oder höherer Ebene**
- Fallback: Wenn kein `[!section]` vorhanden → `note_type` wird verwendet

**Valide Types:** Müssen in `types.yaml` definiert sein (z.B. `experience`, `insight`, `decision`, `value`, `event`)

**Beispiele:**
```markdown
## Situation ^sit
> [!section] experience

Text der Situation...

## Reflexion ^ref
> [!section] insight

Text der Reflexion...
```

---

### 2.2 Edge-Callout (`[!edge]`)

**Syntax (einfach):**
```markdown
> [!edge] edge-kind
> [[Target]]
> [[Target#Section]]
> [[#^block-id]]
```

**Syntax (verschachtelt):**
```markdown
> [!abstract] Semantic Edges
>> [!edge] derives
>> [[#^sit]]
>> [[#^react]]
>
>> [!edge] supports
>> [[Externe Note]]
```

**Backend-Interpretation:**
- Verschachtelte Callouts werden korrekt erkannt
- Block-References (`[[#^block-id]]`) haben Priorität vor Heading-Links (`[[#Section]]`)
- Intra-Note-Links (`[[#^id]]`) werden als `is_internal: true` markiert

**Valide Edge-Kinds:** Aus `edge_vocabulary.md` (z.B. `caused_by`, `derives`, `solves`, `guides`, `related_to`)

---

### 2.3 Block-References

**Deklaration (in Überschrift):**
```markdown
## Überschrift ^block-id
```

**Referenzierung:**
```markdown
> [!edge] derives
> [[#^block-id]]
```

**Backend-Interpretation:**
- Block-ID wird aus Überschrift extrahiert: `^([a-zA-Z0-9_-]+)`
- Bei Referenzen wie `[[#📖 Diagnose ^kontext]]` wird nur `kontext` verwendet
- Fallback: Wenn Block-ID fehlt → Heading-Name wird verwendet

---

## 3. Plugin-Anforderungen nach Bereich

### 3.1 Edge Parsing (`src/parser/`)

#### 3.1.1 Erweiterte Edge-Erkennung

**Betroffene Dateien:**
- `src/parser/parseEdgesFromCallouts.ts`

**Anforderungen:**

1. **Block-ID-Extraktion aus Links:**
   ```typescript
   // Erweitere parseEdgesFromCallouts() um Block-ID-Erkennung
   function extractBlockId(link: string): string | null {
     // [[#^block-id]] → "block-id"
     // [[#Section Name ^block-id]] → "block-id"
     // [[#Section]] → null (Fallback auf Heading)
   }
   ```

2. **Intra-Note-Edge-Erkennung:**
   ```typescript
   interface ParsedEdge {
     rawType: string;
     targets: string[];
     lineStart: number;
     lineEnd: number;
     isInternal?: boolean; // NEU: Flag für Intra-Note-Edges
     blockIds?: string[];  // NEU: Extrahierte Block-IDs
   }
   ```

**Implementierung:**
- Erkenne `[[#^block-id]]` Format
- Markiere als `isInternal: true` wenn alle Targets Block-IDs sind
- Extrahiere Block-IDs für spätere Validierung

---

### 3.2 Section Parsing (`src/mapping/sectionParser.ts`)

#### 3.2.1 Section-Type-Erkennung

**Betroffene Dateien:**
- `src/mapping/sectionParser.ts`

**Anforderungen:**

1. **Section-Type-Callout-Parsing:**
   ```typescript
   interface NoteSection {
     heading: string | null;
     headingLevel: number;
     content: string;
     startLine: number;
     endLine: number;
     links: string[];
     sectionType?: string;  // NEU: Aus [!section] Callout
     blockId?: string;      // NEU: Aus Heading ^block-id
   }
   ```

2. **Section-Type-Extraktion:**
   ```typescript
   function extractSectionType(content: string): string | null {
     // Suche nach > [!section] type-name
     // Kann an beliebiger Stelle in der Section stehen
     // Gilt retroaktiv ab der Überschrift
   }
   ```

3. **Block-ID-Extraktion:**
   ```typescript
   function extractBlockId(heading: string): string | null {
     // ## Heading ^block-id → "block-id"
     // Regex: /\^([a-zA-Z0-9_-]+)/
   }
   ```

**Implementierung:**
- Parse `[!section]` Callouts innerhalb von Sections
- Extrahiere Block-IDs aus Headings
- Propagiere Section-Type retroaktiv zur Überschrift

---

### 3.3 Interview Wizard (`src/interview/`)

#### 3.3.1 Section-Type-Unterstützung

**Betroffene Dateien:**
- `src/interview/renderer.ts`
- `src/interview/types.ts`
- `src/interview/wizardState.ts`

**Anforderungen:**

1. **Section-Type-Auswahl:**
   ```typescript
   interface CaptureTextStep {
     type: "capture_text";
     key: string;
     label?: string;
     required?: boolean;
     section?: string;
     sectionType?: string;  // NEU: Vorgeschlagener Section-Type
     prompt?: string;
     output?: {
       template?: string;
       includeSectionCallout?: boolean; // NEU: Automatisch [!section] einfügen
     };
   }
   ```

2. **Automatische Block-ID-Generierung:**
   ```typescript
   interface CaptureTextLineStep {
     type: "capture_text_line";
     // ... existing fields ...
     output?: {
       template?: string;
       generateBlockId?: boolean; // NEU: Automatisch ^block-id generieren
       blockIdFromKey?: boolean;  // NEU: Block-ID aus step.key ableiten
     };
   }
   ```

3. **Rendering mit Section-Types:**
   ```typescript
   function renderSectionWithType(
     heading: string,
     sectionType: string | null,
     blockId: string | null
   ): string {
     // Generiere: ## Heading ^block-id\n> [!section] type\n
   }
   ```

**Implementierung:**
- Erweitere Interview-Steps um Section-Type-Optionen
- Generiere automatisch Block-IDs basierend auf Step-Keys
- Füge `[!section]` Callouts automatisch ein, wenn `sectionType` definiert ist

---

### 3.4 Chain Workbench (`src/workbench/`)

#### 3.4.1 Section-Type-basierte Chain-Analyse

**Betroffene Dateien:**
- `src/workbench/types.ts`
- `src/workbench/todoGenerator.ts`
- `src/analysis/chainInspector.ts`

**Anforderungen:**

1. **Section-Type in Chain-Matching:**
   ```typescript
   interface WorkbenchMatch extends TemplateMatch {
     // ... existing fields ...
     sectionTypes?: Map<string, string>; // NEU: Map von Slot-ID → Section-Type
   }
   ```

2. **Section-Type-Validierung:**
   ```typescript
   interface MissingLinkTodo extends WorkbenchTodo {
     // ... existing fields ...
     fromSectionType?: string;  // NEU: Section-Type der Quelle
     toSectionType?: string;    // NEU: Section-Type des Ziels
     suggestedEdgeTypes: string[]; // Basierend auf graph_schema.md
   }
   ```

3. **Intra-Note-Edge-Erkennung:**
   ```typescript
   function detectIntraNoteEdges(
     file: string,
     sections: NoteSection[]
   ): ParsedEdge[] {
     // Finde alle Edges innerhalb derselben Note
     // Markiere mit isInternal: true
   }
   ```

**Implementierung:**
- Berücksichtige Section-Types bei Chain-Matching
- Nutze `graph_schema.md` für Edge-Type-Vorschläge
- Erkenne Intra-Note-Edges für bessere Chain-Analyse

---

### 3.5 Edge Editing (`src/ui/`)

#### 3.5.1 Edge-Type-Chooser mit Section-Type-Awareness

**Betroffene Dateien:**
- `src/ui/EdgeTypeChooserModal.ts`
- `src/ui/InlineEdgeTypeModal.ts`

**Anforderungen:**

1. **Section-Type-basierte Vorschläge:**
   ```typescript
   function getSuggestedEdgeTypes(
     sourceSectionType: string,
     targetSectionType: string
   ): string[] {
     // Nutze graph_schema.md für "typical" Edges
     // Zeige nur relevante Edge-Types basierend auf Section-Types
   }
   ```

2. **Block-ID-Autovervollständigung:**
   ```typescript
   function suggestBlockIds(
     currentNote: string,
     query: string
   ): Array<{blockId: string, heading: string, sectionType: string}> {
     // Zeige verfügbare Block-IDs aus aktueller Note
     // Format: "heading (sectionType) ^block-id"
   }
   ```

**Implementierung:**
- Lade `graph_schema.md` für Edge-Type-Vorschläge
- Zeige Block-IDs aus aktueller Note in Autovervollständigung
- Validiere Edge-Types gegen Schema (Warnung bei "prohibited")

---

### 3.6 Mapping & Semantic Edges (`src/mapping/`)

#### 3.6.1 Section-Type-basierte Mapping-Logik

**Betroffene Dateien:**
- `src/mapping/mappingBuilder.ts`
- `src/mapping/semanticMappingBuilder.ts`
- `src/mapping/updateMappingBlocks.ts`

**Anforderungen:**

1. **Section-Type-Tracking:**
   ```typescript
   interface MappingContext {
     // ... existing fields ...
     sectionTypes: Map<string, string>; // Map von Heading → Section-Type
     blockIds: Map<string, string>;     // Map von Heading → Block-ID
   }
   ```

2. **Intra-Note-Edge-Generierung:**
   ```typescript
   function generateIntraNoteEdges(
     sections: NoteSection[],
     sectionTypes: Map<string, string>
   ): ParsedEdge[] {
     // Generiere automatische Edges zwischen Sections
     // Nutze graph_schema.md für Default-Edge-Types
     // Nur wenn keine expliziten Edges vorhanden
   }
   ```

**Implementierung:**
- Tracke Section-Types während Mapping
- Generiere Default-Edges basierend auf Section-Transitions
- Nutze `graph_schema.md` für Edge-Type-Auswahl

---

## 4. Dictionary-Integration

### 4.1 graph_schema.md Parsing

**Betroffene Dateien:**
- `src/schema/GraphSchemaLoader.ts` (neu zu erstellen)

**Anforderungen:**

1. **Schema-Loader:**
   ```typescript
   interface GraphSchema {
     [sourceType: string]: {
       [targetType: string]: {
         typical: string[];
         prohibited: string[];
       };
     };
   }

   function loadGraphSchema(): GraphSchema {
     // Parse Dictionary/graph_schema.md
     // Extrahiere "typical" und "prohibited" Edge-Types
   }
   ```

2. **Typical Edge Lookup:**
   ```typescript
   function getTypicalEdgeFor(
     sourceType: string,
     targetType: string
   ): string | null {
     // Lookup im Schema
     // Fallback-Logik: exact → "any" → "default"
   }
   ```

3. **Topology Info:**
   ```typescript
   function getTopologyInfo(
     sourceType: string,
     targetType: string
   ): {typical: string[], prohibited: string[]} {
     // Gibt vollständige Topology-Info zurück
   }
   ```

**Implementierung:**
- Erstelle `GraphSchemaLoader.ts` analog zu `ChainRolesLoader.ts`
- Parse `graph_schema.md` Format
- Implementiere Fallback-Logik wie im Backend

---

### 4.2 types.yaml Integration

**Anforderungen:**

1. **Section-Type-Validierung:**
   ```typescript
   function validateSectionType(type: string): boolean {
     // Prüfe gegen types.yaml
     // Zeige Warnung bei unbekannten Types
   }
   ```

2. **Type-Autovervollständigung:**
   ```typescript
   function getAvailableSectionTypes(): string[] {
     // Lade types.yaml
     // Zeige alle verfügbaren Types für Autovervollständigung
   }
   ```

---

## 5. UI-Komponenten

### 5.1 Section-Type-Editor

**Neue Komponente:** `src/ui/SectionTypeModal.ts`

**Funktionalität:**
- Auswahl eines Section-Types aus `types.yaml`
- Vorschau: Wie die Section im Backend interpretiert wird
- Block-ID-Generierung/-Bearbeitung

**UI:**
```typescript
interface SectionTypeModalProps {
  heading: string;
  currentSectionType: string | null;
  currentBlockId: string | null;
  onSave: (sectionType: string | null, blockId: string | null) => void;
}
```

---

### 5.2 Block-ID-Autovervollständigung

**Erweiterung:** `src/ui/LinkPromptModal.ts`

**Funktionalität:**
- Zeige verfügbare Block-IDs aus aktueller Note
- Format: `[[#^block-id]]` mit Heading-Vorschau
- Filterung nach Section-Type (optional)

---

### 5.3 Edge-Validierung (Visual Feedback)

**Erweiterung:** `src/ui/EdgeTypeChooserModal.ts`

**Funktionalität:**
- Zeige Schema-Validierung in Echtzeit
- Warnung bei "prohibited" Edges
- Vorschlag für "typical" Edges basierend auf Section-Types

**UI-Indikatoren:**
- ✅ Typisch (grün)
- ⚠️ Atypisch (gelb)
- ❌ Verboten (rot)

---

## 6. Commands

### 6.1 Neue Commands

#### 6.1.1 "Add Section Type"

**Command-ID:** `mindnet:add-section-type`

**Funktionalität:**
- Fügt `[!section]` Callout zur aktuellen Section hinzu
- Öffnet `SectionTypeModal` für Type-Auswahl
- Generiert automatisch Block-ID falls nicht vorhanden

---

#### 6.1.2 "Add Block ID to Heading"

**Command-ID:** `mindnet:add-block-id`

**Funktionalität:**
- Fügt Block-ID zur aktuellen Überschrift hinzu
- Format: `## Heading ^block-id`
- Generiert ID aus Heading-Text (slugified)

---

#### 6.1.3 "Insert Intra-Note Edge"

**Command-ID:** `mindnet:insert-intra-note-edge`

**Funktionalität:**
- Fügt `[!edge]` Callout mit Block-Reference hinzu
- Zeigt Autovervollständigung für Block-IDs
- Vorschläge basierend auf Section-Types

---

### 6.2 Erweiterte Commands

#### 6.2.1 Chain Workbench

**Betroffene Dateien:**
- `src/commands/chainWorkbenchCommand.ts`

**Erweiterungen:**
- Berücksichtige Section-Types bei Chain-Matching
- Zeige Section-Types in Match-Details
- Vorschläge für Intra-Note-Edges basierend auf Schema

---

#### 6.2.2 Interview Wizard

**Betroffene Dateien:**
- `src/interview/renderer.ts`

**Erweiterungen:**
- Automatische Section-Type-Zuweisung basierend auf Step-Konfiguration
- Block-ID-Generierung für alle Sections
- Automatische Intra-Note-Edges zwischen Sections

---

## 7. Validierung & Linting

### 7.1 Section-Type-Validierung

**Neue Rules:** `src/lint/rules/rule_section_type.ts`

**Validierung:**
- Section-Type muss in `types.yaml` existieren
- Warnung bei fehlenden Block-IDs für referenzierte Sections
- Warnung bei Section-Types ohne explizite Edges (könnte Default-Edge nutzen)

---

### 7.2 Edge-Validierung

**Erweiterung:** `src/lint/rules/rule_unkown_edge.ts`

**Validierung:**
- Prüfe Edge-Types gegen `edge_vocabulary.md`
- Prüfe Edge-Types gegen `graph_schema.md` (prohibited)
- Warnung bei atypischen Edges (nicht in "typical")

---

### 7.3 Block-ID-Validierung

**Neue Rule:** `src/lint/rules/rule_block_id.ts`

**Validierung:**
- Warnung bei fehlenden Block-IDs für referenzierte Sections
- Warnung bei doppelten Block-IDs innerhalb einer Note
- Warnung bei Block-IDs, die nicht referenziert werden

---

## 8. Integration mit bestehenden Features

### 8.1 Vault Triage Scan

**Betroffene Dateien:**
- `src/workbench/vaultTriageScan.ts`
- `src/commands/vaultTriageScanCommand.ts`

**Erweiterungen:**
- Erkenne Notes ohne Section-Types (könnten von WP-26 profitieren)
- Erkenne fehlende Block-IDs bei referenzierten Sections
- Erkenne Intra-Note-Edges, die noch nicht explizit sind

---

### 8.2 Chain Inspector

**Betroffene Dateien:**
- `src/analysis/chainInspector.ts`

**Erweiterungen:**
- Berücksichtige Section-Types bei Chain-Matching
- Nutze Section-Types für bessere Edge-Type-Vorschläge
- Erkenne Intra-Note-Chains innerhalb einer Note

---

## 9. Implementierungsreihenfolge

### Phase 1: Grundlagen (Kern-Parsing)

1. ✅ **Section-Type-Parsing** (`sectionParser.ts`)
   - `[!section]` Callout-Erkennung
   - Block-ID-Extraktion aus Headings
   - Section-Type-Propagation

2. ✅ **Edge-Parsing-Erweiterung** (`parseEdgesFromCallouts.ts`)
   - Block-ID-Erkennung in Links
   - Intra-Note-Edge-Flag

3. ✅ **Graph-Schema-Loader** (`GraphSchemaLoader.ts`)
   - Parse `graph_schema.md`
   - Implementiere Lookup-Funktionen

---

### Phase 2: UI-Komponenten

4. ✅ **Section-Type-Modal** (`SectionTypeModal.ts`)
   - Type-Auswahl
   - Block-ID-Generierung

5. ✅ **Block-ID-Autovervollständigung** (Erweiterung `LinkPromptModal.ts`)
   - Zeige verfügbare Block-IDs
   - Filterung nach Section-Type

6. ✅ **Edge-Type-Chooser-Erweiterung** (`EdgeTypeChooserModal.ts`)
   - Section-Type-basierte Vorschläge
   - Schema-Validierung (Visual Feedback)

---

### Phase 3: Feature-Integration

7. ✅ **Interview-Wizard-Integration** (`renderer.ts`)
   - Section-Type-Unterstützung
   - Automatische Block-ID-Generierung

8. ✅ **Chain-Workbench-Integration** (`chainWorkbenchCommand.ts`)
   - Section-Type-basierte Chain-Analyse
   - Intra-Note-Edge-Erkennung

9. ✅ **Mapping-Integration** (`mappingBuilder.ts`)
   - Section-Type-Tracking
   - Automatische Intra-Note-Edge-Generierung

---

### Phase 4: Validierung & Linting

10. ✅ **Lint-Rules** (`src/lint/rules/`)
    - Section-Type-Validierung
    - Edge-Validierung gegen Schema
    - Block-ID-Validierung

11. ✅ **Vault-Triage-Erweiterung** (`vaultTriageScan.ts`)
    - WP-26-Feature-Erkennung
    - Verbesserungsvorschläge

---

## 10. Test-Strategie

### 10.1 Unit-Tests

**Neue Test-Dateien:**
- `src/tests/parser/parseSectionCallouts.test.ts`
- `src/tests/mapping/sectionTypeParser.test.ts`
- `src/tests/schema/graphSchemaLoader.test.ts`

**Bestehende Tests erweitern:**
- `src/tests/parser/parseEdgesFromCallouts.test.ts` (Block-ID-Support)
- `src/tests/interview/renderer.test.ts` (Section-Type-Support)

---

### 10.2 Integration-Tests

**Test-Szenarien:**
1. Interview-Wizard mit Section-Types
2. Chain-Workbench mit Intra-Note-Edges
3. Edge-Editing mit Schema-Validierung

---

## 11. Migration & Abwärtskompatibilität

### 11.1 Bestehende Notes

**Garantie:** Notes ohne `[!section]` Callouts funktionieren weiterhin:
- Fallback auf `note_type`
- Keine Breaking Changes

### 11.2 Graduelle Migration

**Empfehlung:**
1. Plugin zeigt Optionen für WP-26 Features
2. Nutzer kann schrittweise migrieren
3. Vault-Triage-Scan zeigt Verbesserungspotenzial

---

## 12. Dokumentation für Plugin-Nutzer

### 12.1 Quick-Start-Guide

**Inhalt:**
- Wie füge ich Section-Types hinzu?
- Wie erstelle ich Intra-Note-Edges?
- Wie nutze ich Block-IDs?

### 12.2 Best Practices

**Inhalt:**
- Wann Section-Types verwenden?
- Block-ID-Namenskonventionen
- Schema-konforme Edge-Types

---

## 13. Anhang: TypeScript-Interfaces

### 13.1 Erweiterte Types

```typescript
// src/parser/types.ts
export interface ParsedEdge {
  rawType: string;
  targets: string[];
  lineStart: number;
  lineEnd: number;
  isInternal?: boolean;      // WP-26: Intra-Note-Edge-Flag
  blockIds?: string[];       // WP-26: Extrahierte Block-IDs
  sectionTypes?: {           // WP-26: Section-Types von Source/Target
    source?: string;
    target?: string;
  };
}

// src/mapping/sectionParser.ts
export interface NoteSection {
  heading: string | null;
  headingLevel: number;
  content: string;
  startLine: number;
  endLine: number;
  links: string[];
  sectionType?: string;      // WP-26: Aus [!section] Callout
  blockId?: string;          // WP-26: Aus Heading ^block-id
}

// src/schema/types.ts (neu)
export interface GraphSchema {
  [sourceType: string]: {
    [targetType: string]: {
      typical: string[];
      prohibited: string[];
    };
  };
}
```

---

**Ende der Spezifikation**

**Nächste Schritte:**
1. Review der Spezifikation
2. Priorisierung der Implementierungsphasen
3. Start mit Phase 1 (Grundlagen)