# mindnet v2 — Dokumentationsreview (vollständig & konsolidiert)

Dieses Dokument fasst alle notwendigen Anpassungen der mindnet-v2 Dokumentation zusammen.  
Der Fokus liegt ausschließlich auf Aspekten, die durch die aktuellen Arbeiten verändert wurden:

- neue Edge-Mechanik  
- neuer Importer  
- neues Verhalten von note_payload & chunk_payload  
- Default-Typregeln aus `types.yaml`  
- Inline- und Callout-Relations  
- WP04a – Einführung der Retriever-Schicht  
- neue Diagnose- und Testskripte  

Es handelt sich um eine strukturelle Analyse.  
Nichts davon überschreibt bestehende Inhalte — es markiert nur, **was angepasst werden muss**.

---

# 1) knowledge_design.md  
## Erforderliche Anpassungen

### 1.1 Neue Edge-Arten dokumentieren
Es müssen vier neue Kategorien beschrieben werden:

1. **Inline-Edges**
    
    Beispiel:  
        `[ [rel:depends_on Embeddings 101] ]`  
    (Leerzeichen hier zur Demonstration; im echten Dokument ohne Leerzeichen)

2. **Callout-Edges**
    
        > [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]

3. **Typbasierte Default-Kanten**  
   Aus `types.yaml` → `edge_defaults`

4. **Strukturkanten**
    - belongs_to
    - next
    - prev

### 1.2 Neue Edge-Felder ergänzen  
Jeder Edge enthält jetzt:

- `rule_id`
- `confidence`
- `scope = "chunk"`
- deterministischer `edge_id`

Diese Felder müssen vollständig erklärt werden.

### 1.3 Chunk-basierte Kanten  
Neu: **Alle Kanten entstehen ausschließlich zwischen Chunks**, nie zwischen Notes.  
Notes dienen nur noch als Metadatencontainer.

---

# 2) TYPE_REGISTRY_MANUAL.md  
## Erforderliche Anpassungen

### 2.1 Typauflösung dokumentieren
Die Regeln sind jetzt:

- Typ aus Frontmatter → höchste Priorität
- Falls nicht gesetzt: Typ aus Dateipfad ableiten
- Falls unbekannt: Fallback auf `types.default`
- Typ definiert:
    - retriever_weight
    - chunk_profile
    - edge_defaults

Diese müssen klar dokumentiert werden.

### 2.2 Neue Fallback-Regeln
Wenn Werte fehlen, werden sie ersetzt durch:

        types.default.retriever_weight
        types.default.chunk_profile
        types.default.edge_defaults

### 2.3 Beispiele aktualisieren  
Alle Beispiele müssen auf die neue Inline-Syntax angepasst werden.

---

# 3) wp04_retriever_scoring.md  
## Erforderliche Anpassungen

### 3.1 Neue Scoring-Formel  
        total_score =
            semantic_weight   * semantic_score
          + edge_weight       * edge_bonus
          + centrality_weight * centrality_bonus
          + type_weight       * retriever_weight

### 3.2 Bedeutung von `confidence`  
confidence wirkt multiplikativ bei edge_bonus.  
Inline > Callout > Default (Standardwerte im Code hinterlegt).

### 3.3 Pfadbegründungen  
Der Retriever gibt optional `paths[]` zurück:

        paths: [
            {
                "via": "depends_on",
                "confidence": 0.7,
                "hops": ["Note A", "Chunk A#01", "Note B"]
            }
        ]

Diese Funktion müssen dokumentiert werden.

---

# 4) mindnet_v2_implementation_playbook.md  
## Erforderliche Anpassungen

### 4.1 Neuer Import-Prozess vollständig dokumentieren
Der Importer läuft jetzt so:

1. Markdown lesen  
2. Frontmatter extrahieren  
3. Typauflösung via `types.yaml`  
4. Note-Payload generieren  
5. Chunking anwenden  
6. Inline-Kanten finden  
7. Callout-Kanten finden  
8. Default-Edges erzeugen  
9. Strukturkanten erzeugen  
10. Chunks in Qdrant upserten  
11. Edges upserten  
12. Diagnose laufen lassen:

        python3 -m scripts.payload_dryrun
        python3 -m scripts.edges_full_check

### 4.2 Erweiterte Testpipeline  
Neu zu dokumentieren:

        tests.test_edges_all
        scripts.edges_full_check
        scripts.payload_dryrun

Diese Testschritte sind jetzt Standardanforderung nach jeder Änderung.

---

# 5) mindnet_technical_architecture.md  
## Erforderliche Anpassungen

### 5.1 Aktualisiertes Schema für Qdrant Collections

#### Notes:
        note_id
        title
        type
        fulltext
        retriever_weight
        chunk_profile
        edge_defaults
        tags
        updated

#### Chunks:
        chunk_id
        note_id
        text
        window
        ord
        retriever_weight
        chunk_profile
        neighbors_prev
        neighbors_next

#### Edges:
        edge_id
        source_id
        target_id
        kind
        scope = "chunk"
        rule_id
        confidence

### 5.2 Dokumentation der Edge-Pipeline  
Neu beschreiben:

- Inline-Parser  
- Callout-Parser  
- Default-Edge-Resolver  
- Strukturkanten  
- Normalisierung für Qdrant  
- deterministische ID-Bildung  

---

# 6) mindnet_functional_architecture.md  
## Erforderliche Anpassungen

### 6.1 Inline-Relations – einzig gültige Syntax
Nur diese Syntax erzeugt Kanten:

        [[rel:depends_on Embeddings 101]]

Nicht unterstützt:

        rel:depends_on [[Embeddings 101]]

Dies muss klar dokumentiert werden.

### 6.2 Prioritäten der Kantenerzeugung  
Gültige Reihenfolge:

1. Inline  
2. Callout  
3. Typdefaults  
4. Strukturkanten  

### 6.3 Relaunch der Chunk-zentrierten Funktionslogik  
Alle Beispiele müssen angepasst werden.

---

# 7) chunking_strategy.md  
## Erforderliche Änderungen

### 7.1 Neues Verhalten der Chunks
- `ord` ist jetzt Sortierkriterium  
- `window` wird über chunk_config erzeugt  
- Chunkprofile kommen ausschließlich aus `types.yaml`

### 7.2 Best Practices erneuern
Empfehlung:

- keine manuelle Chunkprofile mehr im Frontmatter setzen  

---

# 8) docs_mindnet_retriever.md  
## Erforderliche Änderungen

### 8.1 Neue Ausgabeparameter dokumentieren  
Retriever liefert jetzt:

        semantic_score
        edge_bonus
        centrality_bonus
        type_score
        total_score
        paths[]

### 8.2 Graph-Expansion  
Dokumentieren:

- Seed-Auswahl  
- Depth-Limit  
- Edge-Filterung  
- Wirkung von `confidence` auf edge_bonus  

---

# 9) Handbuch.md  
## Erforderliche Änderungen

### 9.1 Neuer Import-Workflow  
Erläuterung der Parser:

- Inline-Parser  
- Callout-Parser  
- Default-Kanten  
- Struktur-Kanten  

### 9.2 Best Practices  
Ergänzen:

- Typenpflege erfolgt nur in `types.yaml`  
- Tests immer nach Änderungen ausführen  

---

# Gesamtübersicht der notwendigen Anpassungen

| Dokument | Anpassungsbedarf |
|---------|------------------|
| knowledge_design.md | neue Edge-Arten, Felder, Chunk-Edges |
| TYPE_REGISTRY_MANUAL.md | Typauflösung, neue Felder, neue Fallbacks |
| wp04_retriever_scoring.md | neue Score-Formel, Pfade, confidence |
| implementation_playbook.md | neuer Importprozess, Tests |
| technical_architecture.md | aktualisierte Schemas |
| functional_architecture.md | Syntax + Prioritäten |
| chunking_strategy.md | ord, window, neue Profile |
| docs_mindnet_retriever.md | neue API-Parameter |
| Handbuch.md | Parser + Best Practices |

---

# Empfehlung zur Umsetzung
1. Dieses Review-Dokument als Master-Referenz verwenden.  
2. Jedes Dokument strikt nur an den beschriebenen Stellen anpassen.  
3. Überprüfen, ob Wann/Wo Typen, Kanten und Parser erklärt werden.  
4. Nach jeder Anpassung Testlauf:

        python3 -m scripts.payload_dryrun
        python3 -m scripts.edges_full_check

5. Danach Playbook + Programmplan updaten.