Dateien nach "docs" hochladen

docs/CHANGELOG_TYPE_REGISTRY.md

@@ -0,0 +1,21 @@
+# Changelog — WP-03 Type-Registry (2025-11-08)
+
+## Added
+- `app/core/type_registry.py` — Loader & Helper (cached), robust Fallbacks.
+- `config/types.yaml` — Beispiel-Registry (version 1.0).
+- `scripts/import_markdown.py` v3.8.0 — Registry-Integration:
+  - typvalidierung (unbekannt → `concept`, Warnung)
+  - `chunk_profile` → an `make_chunk_payloads(...)`
+  - `retriever_weight` → persistiert im Note-Payload
+  - `edge_defaults["references"]` schaltet Note-Scope-Refs additiv ein
+- `app/core/chunk_payload.py` v2.3.0 — optionales `chunk_profile` für
+  synthetische Overlaps (keine Schemaänderung).
+- `app/core/derive_edges.py` v1.5.0 — Type-Registry aktiviert note-scope
+  References/Backlinks additiv.
+
+## Changed
+- Keine Breaking Changes. Alle CLI-Flags, ENV-Variablen und Collection-
+  Prefix-Logik bleiben unverändert.
+
+## Removed
+- N/A

docs/TYPE_REGISTRY_MANUAL.md

@@ -0,0 +1,74 @@
+# Kurzhandbuch — Type-Registry (WP-03)
+
+## Zweck
+Die Type-Registry macht den `type:`-Wert im Frontmatter maschinenlesbar
+und steuert:
+- Chunk-Profile (indirekt über Overlap bei fensterlosen Chunks),
+- typabhängige Default-Kanten (hier: Aktivierung von Note-Scope-References),
+- optionale Retriever-Gewichtungen (`retriever_weight`) für WP‑04.
+
+## Aktivierung
+1. Legen Sie `config/types.yaml` an (siehe Beispiel in diesem Paket).
+2. Starten Sie Import/Server neu. Die Registry wird beim Prozessstart
+   geladen und gecached.
+
+Fehlt die Datei oder ist sie defekt, bleibt das System voll funktionsfähig
+(der Typ `concept` wird genutzt; Warnhinweis im Log).
+
+## Schema (Beispiel)
+```yaml
+version: 1.0
+types:
+  concept:
+    chunk_profile: long
+    edge_defaults: ["references", "related_to"]
+    retriever_weight: 1.0
+  task:
+    chunk_profile: short
+    edge_defaults: ["depends_on", "belongs_to"]
+    retriever_weight: 0.8
+  experience:
+    chunk_profile: medium
+    edge_defaults: ["derived_from", "inspired_by"]
+    retriever_weight: 0.9
+  project:
+    chunk_profile: medium
+    edge_defaults: ["references", "depends_on"]
+    retriever_weight: 0.95
+```
+
+## Verhalten
+- **Chunking**: Die eigentliche Chunk-Länge bleibt weiterhin typabhängig über
+  `chunk_config.get_sizes(type)` gesteuert. Falls der Chunker keine Fenster
+  mit Overlap liefert, werden in `chunk_payload` synthetische Fenster erzeugt.
+  Hier greift das `chunk_profile` mit folgenden Overlap-Empfehlungen:
+  - short → (20,30), medium → (40,60), long → (60,80).
+- **Edges**: Enthält `edge_defaults` den Eintrag `references`, werden Note-
+  Scope-References/Backlinks additiv aktiviert (kein Abbruch, keine Duplikate).
+  Weitere Kantenarten bleiben unverändert.
+- **Retriever**: `retriever_weight` wird in der Note gespeichert und kann von
+  WP‑04 im Ranking/Scoring berücksichtigt werden.
+
+## Tests / Validierung
+- Dry-Run:
+  ```bash
+  python3 -m scripts.import_markdown --vault ./test_vault
+  ```
+- Vollimport + Purge:
+  ```bash
+  python3 -m scripts.import_markdown --vault ./test_vault --apply --purge-before-upsert --prefix "$COLLECTION_PREFIX"
+  ```
+- Chunks-Qualität (Window vs Text):
+  ```bash
+  python3 tests/check_chunks_window_vs_text.py --prefix "$COLLECTION_PREFIX"
+  ```
+- Roundtrip:
+  ```bash
+  python3 -m scripts.export_markdown --out ./_exportVault --prefix "$COLLECTION_PREFIX"
+  python3 tests/compare_vaults.py --src ./test_vault --dst ./_exportVault --focus body
+  ```
+
+## Fallbacks & Robustheit
+- Registry nicht vorhanden/ungültig → `concept`, Warnung, keine Abbrüche.
+- Alle bestehenden ENV/Flags bleiben identisch.
+- Keine Änderungen an Punkt-IDs, Feldern oder Vektoren.