mindnet_obsidian/docs/WP26_Plugin_Interface_Specification.md

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:

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

## Situation ^sit
> [!section] experience

Text der Situation...

## Reflexion ^ref
> [!section] insight

Text der Reflexion...

---

2.2 Edge-Callout ([!edge])

Syntax (einfach):

> [!edge] edge-kind
> [[Target]]
> [[Target#Section]]
> [[#^block-id]]

Syntax (verschachtelt):

> [!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):

## Überschrift ^block-id

Referenzierung:

> [!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:

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

   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:

   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:

   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:

   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:

   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:

   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:

   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:

   interface WorkbenchMatch extends TemplateMatch {
     // ... existing fields ...
     sectionTypes?: Map<string, string>; // NEU: Map von Slot-ID → Section-Type
   }
   

2. Section-Type-Validierung:

   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:

   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:

   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:

   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:

   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:

   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:

   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:

   function getTypicalEdgeFor(
     sourceType: string,
     targetType: string
   ): string | null {
     // Lookup im Schema
     // Fallback-Logik: exact → "any" → "default"
   }
   

3. Topology Info:

   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:

   function validateSectionType(type: string): boolean {
     // Prüfe gegen types.yaml
     // Zeige Warnung bei unbekannten Types
   }
   

2. Type-Autovervollständigung:

   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:

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

// 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)