diff --git a/docs/Handbuch.md b/docs/Handbuch.md
new file mode 100644
index 0000000..b176c31
--- /dev/null
+++ b/docs/Handbuch.md
@@ -0,0 +1,142 @@
+# HANDBUCH — Mindnet Obsidian Plugin (MVP 1.0)
+
+## 1) Installation / Deployment (Neu aus Gitea)
+Dieses Kapitel beschreibt den Prozess, wenn du das Plugin komplett neu aus Gitea holst und in Obsidian bereitstellst.
+
+### 1.1 Voraussetzungen
+- Windows (Entwicklung) + Obsidian Desktop
+- Node.js installiert (CLI verfügbar)
+  - Falls PowerShell `npm` blockiert: `npm.cmd` nutzen
+- Git Zugriff auf dein Gitea Repo
+
+### 1.2 Repo klonen
+Beispiel:
+1) Ordner wählen (z.B. `C:\Dev\cursor\mindnet_obsidian`)
+2) Repo klonen:
+   - `git clone <gitea-url> mindnet_obsidian`
+3) In den Ordner wechseln:
+   - `cd mindnet_obsidian`
+
+### 1.3 Dependencies installieren
+Wenn PowerShell npm-scripts blockiert:
+- nutze `npm.cmd install`
+
+Standard:
+- `npm install`
+
+### 1.4 Build
+- `npm run build`
+
+Erwartetes Ergebnis:
+- Plugin-Bundle (typischerweise `main.js`) wird erzeugt (abhängig von eurer Build-Konfiguration).
+
+### 1.5 Deployment in einen Obsidian Vault (Dev)
+Zielpfad:
+- `<vault>/.obsidian/plugins/<plugin-id>/`
+
+Schritte:
+1) Im Vault sicherstellen:
+   - `.obsidian/plugins/` existiert
+2) Plugin-Ordner anlegen:
+   - `.obsidian/plugins/mindnet-causal-assistant/`
+3) Deployment (Copy):
+   - `manifest.json` → plugin folder
+   - `main.js` → plugin folder
+   - optional `styles.css` → plugin folder
+
+Wenn ihr ein Script habt (empfohlen):
+- `powershell -ExecutionPolicy Bypass -File scripts\deploy-local.ps1`
+
+### 1.6 Plugin aktivieren
+Obsidian:
+- Settings → Community Plugins
+- “Restricted mode” aus
+- Plugin aktivieren
+
+### 1.7 Typische Fehlerbilder
+- “Plugin lädt nicht”:
+  - Obsidian neustarten
+  - Plugin disable/enable
+  - prüfen, ob `main.js` im Plugin-Ordner aktuell ist
+- Keine Logs:
+  - DevTools öffnen: `Ctrl+Shift+I`
+  - Console Filter zurücksetzen
+
+---
+
+## 2) Konfiguration (Pfad-Settings)
+### 2.1 Vocabulary
+- `edge_vocabulary path` (z.B. `_system/dictionary/edge_vocabulary.md`)
+- Live reload bei Dateiänderung (debounced)
+
+### 2.2 Graph Schema
+- `graph_schema path` (z.B. `_system/dictionary/graph_schema.md`)
+- Wird für Empfehlungen (typical/prohibited) verwendet
+
+### 2.3 Interview Config
+- `interview_config path` (z.B. `_system/dictionary/interview_config.yaml`)
+- Profiles definieren Note-Type, Defaults, Steps, Loop-Layouts
+
+---
+
+## 3) Workflows
+
+### 3.1 Note erstellen
+- Command: “Create note from profile”
+- Profil wählen
+- Titel setzen
+- Folder wählen (oder default)
+- Note wird erstellt und geöffnet
+
+### 3.2 Interview durchführen
+- Wizard startet automatisch (wenn aktiviert) oder manuell per Command
+- Steps ausfüllen (Loops/Nested Loops möglich)
+- Review → Apply & Finish
+- Output wird geschrieben
+
+### 3.3 Semantic Mapping (Edger)
+**Manuell:**
+- Command: “Build semantic mapping blocks (by section)”
+
+**Automatisch (post-run):**
+- Nach Interview Finish wird der Edger ausgeführt (falls im Profil aktiviert)
+
+Output:
+- pro Section ein Mapping-Block am Ende der Section:
+  - Wrapper callout (Default: abstract)
+  - gruppiert nach Edge-Typ
+  - Gruppen getrennt durch Leerzeile
+
+### 3.4 Unresolved Link → Interview
+- Klick auf `[[Neue Note]]`
+- In Reading View: Plugin übernimmt Flow
+- In Editing View: Obsidian kann Note sofort erzeugen → Plugin “adoptiert” und startet Mindnet Flow
+
+---
+
+## 4) Entwicklung (Dev-Workflow)
+### 4.1 Build + Deploy lokal
+- `npm run build`
+- `scripts\deploy-local.ps1` ausführen (falls vorhanden)
+- Obsidian: Plugin reload (disable/enable)
+
+### 4.2 Tests
+- `npm run test`
+
+---
+
+## 5) Troubleshooting
+- Wizard startet nicht:
+  - Prüfe settings `autoStart...`
+  - DevTools Console auf Fehler prüfen
+- Edger schreibt Blöcke an falscher Stelle:
+  - Prüfe Heading Parsing + Section detection
+  - Prüfe, ob Wrapper Block korrekt erkannt/ersetzt wird
+- Schema Empfehlungen fehlen:
+  - Prüfe graph_schema path
+  - Prüfe schema loader stats/logging
+
+---
+
+# CHANGELOG (optional)
+- v1.0.0: MVP 1.0 Feature Freeze
\ No newline at end of file
diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 0000000..771fda6
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,45 @@
+# README — Mindnet Obsidian Plugin (MVP 1.0)
+
+## Überblick
+Das Mindnet Obsidian Plugin ist ein Authoring-Tool, das dich dabei unterstützt:
+- Mindnet-Notes strukturiert anzulegen (Frontmatter, IDs, Typen)
+- Inhalte über konfigurierbare Interviews zu erfassen
+- semantische Kanten (Edges) zu pflegen und zu validieren
+- Links und Edge-Zuordnungen innerhalb einer Note section-basiert zu gruppieren (Semantic Mapping)
+
+## Hauptkonzepte
+- **Profile**: Auswahl eines “Erstell-Profils” (kann mehrere Interviews pro Note-Typ geben).
+- **Interview Config (YAML)**: definiert Steps, Loops, Defaults, Frontmatter-Whitelist.
+- **ID-first**: Mindnet-Graph arbeitet über Frontmatter `id` als Schlüssel.
+- **Semantic Mapping**: links in einer Section werden Edge-Typen zugeordnet und als Callouts strukturiert.
+
+## Quickstart (User)
+1) Plugin installieren (siehe Handbuch: Deployment)
+2) Settings:
+   - `edge_vocabulary path` setzen
+   - `graph_schema path` setzen
+   - `interview_config path` setzen
+3) Neue Note:
+   - Command: **Mindnet: Create note from profile**
+   - Profil wählen, Titel setzen, Folder wählen
+   - Wizard ausfüllen, Finish
+   - Edger läuft optional post-run und baut Semantic Mapping Blöcke
+
+## Commands (Auszug)
+- Create/Interview:
+  - Mindnet: Create note from profile
+  - (Auto) Start Wizard nach Create (konfigurierbar)
+- Mapping/Edges:
+  - Mindnet: Build semantic mapping blocks (by section)
+  - Mindnet: Reload edge vocabulary
+  - (post-run) Edger nach Interview Finish
+- QA:
+  - Mindnet: Validate current note (Lint)
+- Export/Graph:
+  - Mindnet: Export graph (JSON)
+  - Mindnet: Show chains from current note
+
+## Konfigurationsdateien (typisch im Vault)
+- `_system/dictionary/edge_vocabulary.md`
+- `_system/dictionary/graph_schema.md`
+- `_system/dictionary/interview_config.yaml`