Write stable block-id links and always start the interview wizard.
Node.js build / build (20.x) (push) Failing after 8s
Node.js build / build (22.x) (push) Failing after 9s

New notes and workbench edges now emit [[Note#Heading ^block]] or [[#^id]] so vaults stay ingestible without mass relinks. Create-from-profile always opens the wizard; a command can restart it on the current note.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
LarsandCursor committed 2026-08-13 17:25:09 +02:00
1 parent c40a89096f
commit 56ae6a2407
29 files changed
+1448 -274

No files matched your search

+58
View File
@@ -0,0 +1,58 @@
# Module – technische Dokumentation
> **Zielgruppe:** Entwickler, Architekten
> **Übersicht:** Modul-basierte Dokumentation des Mindnet Causal Assistant Plugins
---
## Modul-Übersicht
| Modul | Pfad in `src/` | Kurzbeschreibung |
|-------|----------------|------------------|
| [Analysis](analysis.md) | `analysis/` | Chain Inspector, Template Matching, Scoring, Findings |
| [Dictionary](dictionary.md) | `dictionary/` | Config-Loader, Chain Roles, Chain Templates |
| [Interview](interview.md) | `interview/` | Wizard, Loop State, Renderer, Section Key Resolver |
| [Mapping](mapping.md) | `mapping/` | Semantic Mapping, Edge Type Selector |
| [Parser](parser.md) | `parser/` | Edges aus Callouts, Frontmatter, Links |
| [Graph](graph.md) | `graph/` | Graph Builder, Traversal, Resolution |
| [Vocabulary](vocabulary.md) | `vocab/` | Edge Vocabulary, Normalisierung |
| [Unresolved Link](unresolvedLink.md) | `unresolvedLink/` | Link-Handler, Adoption, Heading-Normalisierung |
| [Workbench](workbench.md) | `workbench/` | Chain Workbench, Todo-Generator, Status |
| [Lint](lint.md) | `lint/` | Lint Engine, Rules |
| [UI](ui.md) | `ui/` | Modals, Settings Tab, Entity Picker |
---
## Abhängigkeiten (vereinfacht)
```
main.ts
├── analysis ← dictionary, graph, parser
├── commands ← analysis, graph, mapping, ui, ...
├── dictionary ← vault
├── graph ← parser
├── interview ← dictionary, parser
├── mapping ← parser, schema
├── parser
├── vocab ← vault
├── lint ← vocab, parser
├── unresolvedLink ← interview, entityPicker
├── workbench ← analysis, interview, mapping
└── ui
```
---
## Weitere Module
- **schema/** – Graph Schema Loader
- **entityPicker/** – Note Index, Folder Tree, Filters
- **export/** – Graph Export
- **utils/** – Logger
---
## Siehe auch
- [04_Architektur](../04_Architektur.md) – System-Design
- [02_concepts/03_chain_identification_and_matching](../02_concepts/03_chain_identification_and_matching.md) – Template Matching, Scoring
+112
View File
@@ -0,0 +1,112 @@
# Modul: Analysis
> **Pfad:** `src/analysis/`
> **Zielgruppe:** Entwickler, Architekten
---
## Übersicht
Das Analysis-Modul enthält die Chain Inspector-Logik, Template Matching, Scoring und Findings-Erzeugung.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `chainInspector.ts` | Haupt-Analyse-Engine |
| `templateMatching.ts` | Template Matching, Scoring, Backtracking |
| `graphIndex.ts` | Graph-Indexierung, Edge-Erfassung |
| `sectionContext.ts` | Section-Context-Handling |
| `severityPolicy.ts` | Severity-Policy für Findings |
---
## Scoring-Logik (Template Matching)
### scoreAssignment
Die Funktion `scoreAssignment` bewertet jede Slot-Zuordnung:
| 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 |
### Link-Validierung
- **findEdgeBetween:** Sucht Edge zwischen zwei Nodes (file:heading)
- **headingsMatch:** Vergleicht Überschriften (normalisiert über `normalizeHeadingForMatch`)
- **Role-Mapping:** Edge-Typ → Role via `chain_roles.yaml`
### Profile-Auflösung
1. **Settings:** `templateMatchingProfile` (`discovery` | `decisioning`)
2. **Template:** `template.matching.required_links`
3. **Defaults:** `defaults.matching.required_links`
---
## Template-Matching-Profile
| Profil | required_links | min_slots_filled_for_gap_findings | min_score_for_gap_findings |
|--------|----------------|-----------------------------------|----------------------------|
| `discovery` | false | 2 | 8 |
| `decisioning` | true | 3 | 18 |
Profile werden in `chain_templates.yaml` unter `defaults.profiles` definiert.
---
## Confidence-Berechnung
| Confidence | Bedingung |
|------------|-----------|
| `confirmed` | slotsComplete AND linksComplete AND mind. eine causal-ish Role |
| `plausible` | slotsComplete, aber (nicht linksComplete ODER keine causal-ish Role) |
| `weak` | nicht slotsComplete |
**causal-ish Roles:** `["causal", "influences", "enables_constraints"]` (konfigurierbar in `chain_templates.yaml`)
---
## Analysis Policies
Datei: `analysis_policies.yaml` (Pfad via Settings `analysisPoliciesPath`)
```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
```
---
## Abhängigkeiten
- **Dictionary:** Chain Roles, Chain Templates
- **Graph:** Graph Index, Traversal
- **Parser:** Edge-Extraktion
- **Unresolved Link:** `headingsMatch`, `normalizeHeadingForMatch`
---
## Siehe auch
- [02_concepts/03_chain_identification_and_matching](../02_concepts/03_chain_identification_and_matching.md)
- [06_Konfigurationsdateien_Referenz](../06_Konfigurationsdateien_Referenz.md) – chain_templates, chain_roles, analysis_policies
+67
View File
@@ -0,0 +1,67 @@
# Modul: Dictionary
> **Pfad:** `src/dictionary/`
> **Zielgruppe:** Entwickler, Administratoren
---
## Übersicht
Das Dictionary-Modul lädt und parst alle Konfigurationsdateien (YAML, Markdown) und stellt sie den anderen Modulen zur Verfügung.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `DictionaryLoader.ts` | Generischer Loader mit Last-Known-Good |
| `ChainRolesLoader.ts` | Lädt chain_roles.yaml |
| `ChainTemplatesLoader.ts` | Lädt chain_templates.yaml |
| `ConfigPathManager.ts` | Pfad-Auflösung für Config-Dateien |
| `parseChainRoles.ts` | Parser für chain_roles |
| `parseChainTemplates.ts` | Parser für chain_templates |
| `types.ts` | TypeScript-Typen |
---
## Geladene Config-Dateien
| Datei | Pfad-Setting | Inhalt |
|-------|-------------|--------|
| edge_vocabulary | edgeVocabularyPath | Kanonische Edge-Typen, Aliases |
| graph_schema | graphSchemaPath | Empfehlungen für Edge-Typen |
| interview_config | interviewConfigPath | Profile, Steps, Loops |
| chain_roles | chainRolesPath | Edge-Typ → Role Mapping |
| chain_templates | chainTemplatesPath | Templates, Slots, Links, Profile |
| analysis_policies | analysisPoliciesPath | Severity-Policies pro Profil |
---
## Live-Reload
- **Debounced:** 200ms bei Dateiänderung
- **Last-Known-Good:** Bei Parse-Fehlern wird letzte gültige Config verwendet
- **Vault Modify Event:** Automatisches Neuladen bei Änderung im Vault
---
## Chain Templates – Struktur
- **defaults.matching:** required_links, distinct_nodes, max_candidate_nodes, max_matches_per_template, max_assignments_collected
- **defaults.profiles:** discovery, decisioning (min_slots_filled_for_gap_findings, min_score_for_gap_findings)
- **templates:** name, slots, links, matching (optional)
---
## Chain Roles – Struktur
- **roles:** Mapping Role-Name → edge_types[]
- **Standard-Rollen:** causal, influences, enables_constraints, provenance, epistemic, normative, structural, temporal
---
## Siehe auch
- [06_Konfigurationsdateien_Referenz](../06_Konfigurationsdateien_Referenz.md)
- [02_Administratorhandbuch](../02_Administratorhandbuch.md)
+28
View File
@@ -0,0 +1,28 @@
# Modul: Graph
> **Pfad:** `src/graph/`
> **Zielgruppe:** Entwickler
---
## Übersicht
Graph Building, Traversal, Target Resolution, Report Rendering.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `GraphBuilder.ts` | Baut Graph aus Vault |
| `GraphIndex.ts` | Indexierung für Traversal |
| `traverse.ts` | BFS/DFS Traversal |
| `resolveTarget.ts` | Link → File Auflösung |
| `renderChainReport.ts` | Report-Rendering |
---
## Siehe auch
- [analysis/graphIndex](../analysis.md) – Graph Index für Chain Inspector
+47
View File
@@ -0,0 +1,47 @@
# Modul: Interview
> **Pfad:** `src/interview/`
> **Zielgruppe:** Entwickler
---
## Übersicht
Interview-Wizard zur strukturierten Erfassung von Inhalten, Section-basierte Ausgabe, Frontmatter-Generierung.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `InterviewConfigLoader.ts` | Lädt interview_config.yaml |
| `parseInterviewConfig.ts` | YAML → InterviewConfig Parser |
| `wizardState.ts` | Wizard State (Steps, Loops) |
| `loopState.ts` | Nested Loops |
| `renderer.ts` | Output-Rendering (Section-basiert) |
| `writeFrontmatter.ts` | Frontmatter-Generierung |
| `sectionKeyResolver.ts` | Section-Key-Auflösung |
| `extractTargetFromAnchor.ts` | Target-Extraktion aus Anchors |
| `targetTypeResolver.ts` | Note-Type- und Section-Type-Auflösung |
| `slugify.ts` | Slug-Generierung für Dateinamen |
---
## Step-Typen
- `capture_frontmatter`, `capture_text`, `capture_text_line`
- `loop`, `review`, `instruction`
- `llm_dialog`, `entity_picker` (experimentell)
---
## WP-26 Features
- `section_type`, `block_id`, `generate_block_id`, `references`
---
## Siehe auch
- [Interview_Config_Guide](../Interview_Config_Guide.md)
+28
View File
@@ -0,0 +1,28 @@
# Modul: Lint
> **Pfad:** `src/lint/`
> **Zielgruppe:** Entwickler
---
## Übersicht
Linting Engine für Note-Validierung, regelbasierte Prüfungen, Findings.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `LintEngine.ts` | Haupt-Engine |
| `rules/` | Einzelne Regeln |
| `rule_hub_has_causality.ts` | Kausale Edges prüfen |
| `rule_missing_target.ts` | Fehlende Targets |
| `rule_unknown_edge.ts` | Unbekannte Edge-Types |
---
## Command
`mindnet-validate-current-note` – validiert aktuelle Note
+32
View File
@@ -0,0 +1,32 @@
# Modul: Mapping
> **Pfad:** `src/mapping/`
> **Zielgruppe:** Entwickler
---
## Übersicht
Semantic Mapping – Section-basierte Gruppierung von Links nach Edge-Typen, Edge-Type-Assignment.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `semanticMappingBuilder.ts` | Baut Mapping-Blöcke |
| `mappingExtractor.ts` | Extrahiert existierende Mappings |
| `mappingBuilder.ts` | Erstellt Mapping-Struktur |
| `edgeTypeSelector.ts` | Edge-Type-Auswahl (empfohlen via graph_schema) |
| `updateMappingBlocks.ts` | Aktualisiert Note |
| `sectionParser.ts` | Section-Parsing |
| `graphSchema.ts` | Schema-Lookup für Empfehlungen |
| `folderHelpers.ts` | Ordner-Hilfsfunktionen |
| `worklistBuilder.ts` | Worklist für Pending Assignments |
---
## Siehe auch
- [06_Konfigurationsdateien_Referenz](../06_Konfigurationsdateien_Referenz.md) – graph_schema
+37
View File
@@ -0,0 +1,37 @@
# Modul: Parser
> **Pfad:** `src/parser/`
> **Zielgruppe:** Entwickler
---
## Übersicht
Markdown-Parsing: Edges aus Callouts, Frontmatter, Links.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `parseEdgesFromCallouts.ts` | Parst `>> [!edge] type` Callouts, Targets |
| `parseFrontmatter.ts` | Frontmatter-Referenz |
| `parseRelLinks.ts` | Relative Links in Sections |
| `types.ts` | Parser-Typen |
---
## Edge-Callout-Format
```markdown
>> [!edge] resulted_in
>> [[#^impact]]
>> [[#^learning]]
```
---
## Siehe auch
- [mapping/sectionParser](../mapping.md) – Section-Parsing
+38
View File
@@ -0,0 +1,38 @@
# Modul: UI
> **Pfad:** `src/ui/`
> **Zielgruppe:** Entwickler
---
## Übersicht
UI-Komponenten: Modals, Settings Tab, Entity Picker, Markdown Toolbar.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `MindnetSettingTab.ts` | Plugin-Einstellungen |
| `InterviewWizardModal.ts` | Interview-Wizard |
| `ProfileSelectionModal.ts` | Profil-Auswahl |
| `EntityPickerModal.ts` | Note/Ordner-Auswahl |
| `ChainWorkbenchModal.ts` | Chain Workbench |
| `VaultTriageScanModal.ts` | Vault-Triage-Scan |
| `EdgeTypeChooserModal.ts` | Edge-Type-Auswahl |
| `AdoptNoteModal.ts` | Note-Adoption |
| `LinkPromptModal.ts` | Link-Prompt |
| `LinkTargetPickerModal.ts` | Link-Ziel-Auswahl |
| `ConfirmOverwriteModal.ts` | Überschreibbestätigung |
| `InlineEdgeTypeModal.ts` | Inline Edge-Type-Suggester |
| `FolderTreeModal.ts` | Ordnerbaum |
| `markdownToolbar.ts` | Markdown-Toolbar |
| `MindnetView.ts` | Mindnet-View |
---
## Siehe auch
- [01_Benutzerhandbuch](../01_Benutzerhandbuch.md)
+62
View File
@@ -0,0 +1,62 @@
# Modul: Unresolved Link
> **Pfad:** `src/unresolvedLink/`
> **Zielgruppe:** Entwickler
---
## Übersicht
Das Unresolved-Link-Modul behandelt das Abfangen von Klicks auf unaufgelöste Links, Note-Adoption und die Normalisierung von Überschriften für Matching.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `unresolvedLinkHandler.ts` | Haupt-Handler für Link-Clicks |
| `linkHelpers.ts` | Link-Parsing, Heading-Normalisierung, Matching |
| `adoptHelpers.ts` | Note-Adoption-Logik |
---
## Heading-Normalisierung (normalizeHeadingForMatch)
**Zweck:** Überschriften für Vergleich (Inspect Chains, Chain Workbench) auf kanonische Form bringen.
### Regeln
1. **Mit ^Block-ID:** `"Überschrift ^Block"` → `"Überschrift"` (Block-Suffix entfernen)
2. **Ohne ^:** Rückgabe unverändert (Idempotenz für bereits normalisierte Formen)
### Wichtige Eigenschaft: Idempotenz
`norm(norm(x)) === norm(x)` – mehrfache Normalisierung ändert nichts.
### Beispiele
| Input | Output |
|-------|--------|
| `"Lars ist gut ^PersLars"` | `"Lars ist gut"` |
| `"Lars ist gut"` | `"Lars ist gut"` |
| `"Nächster Schritt ^next"` | `"Nächster Schritt"` |
| `"Überschrift ^Block"` | `"Überschrift"` |
### headingsMatch
Vergleicht zwei Überschriften über `normalizeHeadingForMatch` – beide müssen nach Normalisierung identisch sein.
---
## Obsidian-Verhalten
- **Manuell verlinkt:** Obsidian erzeugt `[[Titel#Überschrift Block]]` (ohne `^`)
- **Empfehlung:** Für zuverlässiges Matching Links mit `^` verwenden: `[[Note#Überschrift ^Block]]`
---
## Siehe auch
- [12_Heading_Block_Link_Recommendation](../12_Heading_Block_Link_Recommendation.md)
- [Analysis-Modul](analysis.md) – Nutzung von headingsMatch
+32
View File
@@ -0,0 +1,32 @@
# Modul: Vocabulary
> **Pfad:** `src/vocab/`
> **Zielgruppe:** Entwickler
---
## Übersicht
Edge Vocabulary Loading, Normalisierung (Alias → Canonical), Inverse Edge Resolution.
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `Vocabulary.ts` | Lookup-Methoden |
| `VocabularyLoader.ts` | Lädt edge_vocabulary.md |
| `parseEdgeVocabulary.ts` | Parst Markdown zu EdgeVocabulary |
---
## Format
Markdown mit Tabellen oder Callouts. Kanonische Typen, Inverse, Aliases.
---
## Siehe auch
- [06_Konfigurationsdateien_Referenz](../06_Konfigurationsdateien_Referenz.md) – edge_vocabulary
+61
View File
@@ -0,0 +1,61 @@
# Modul: Workbench
> **Pfad:** `src/workbench/`
> **Zielgruppe:** Entwickler
---
## Übersicht
Das Workbench-Modul implementiert die **Chain Workbench** – eine UI zur Analyse von Ketten und zur Bearbeitung von Lücken (Todos, Actions).
---
## Komponenten
| Datei | Beschreibung |
|-------|--------------|
| `ChainWorkbenchModal.ts` | Haupt-Modal (in ui/) |
| `workbenchBuilder.ts` | Baut Workbench-Daten aus Template Matches |
| `todoGenerator.ts` | Erzeugt Todos (missing_slot, missing_link, weak_roles) |
| `statusCalculator.ts` | Berechnet Status (complete, near_complete, partial, weak) |
| `zoneDetector.ts` | Erkennt Zonen (note_links, candidates_only) |
| `createSectionAction.ts` | Aktion: Sektion erstellen |
| `linkExistingAction.ts` | Aktion: Bestehenden Knoten verlinken |
| `insertEdgeIntoSectionContent.ts` | Edge in Section-Content einfügen |
| `interviewOrchestration.ts` | Orchestriert Interview bei Create-Actions |
---
## Vault Triage Scan
- **Command:** `mindnet-vault-triage-scan`
- **Modal:** VaultTriageScanModal
- **Sortierung:** near_complete zuerst, dann nach Score absteigend
---
## Status-Werte
| Status | Bedingung |
|--------|-----------|
| `complete` | Slots + Links vollständig |
| `near_complete` | 1–2 Links fehlen oder 1 Slot fehlt |
| `partial` | Mehrere Lücken |
| `weak` | Nur structural/temporal Roles, keine causal Roles |
---
## Fix Actions
- **createMissingNote:** Skeleton, Create+Open, Create+Wizard
- **createMissingHeading:** Neues Heading mit konfigurierbarem Level
- **promoteCandidate:** Candidate als echten Slot übernehmen
---
## Siehe auch
- [09_Workbench_Analysis_Basis](../09_Workbench_Analysis_Basis.md)
- [10_Workbench_Findings_Integration](../10_Workbench_Findings_Integration.md)
- [Analysis-Modul](analysis.md) – Template Matching, Scoring