mindnet_obsidian/docs/05_Installation_Deployment.md

# Mindnet Causal Assistant - Installation & Deployment

> **Version:** 1.0.0  
> **Stand:** 2025-01-XX  
> **Zielgruppe:** Administratoren, Entwickler, Erst-Installation

---

## Inhaltsverzeichnis

1. [Voraussetzungen](#voraussetzungen)
2. [Installation](#installation)
3. [Deployment](#deployment)
4. [Konfiguration](#konfiguration)
5. [Upgrade](#upgrade)
6. [Troubleshooting](#troubleshooting)

---

## Voraussetzungen

### System-Anforderungen

- **Betriebssystem:** Windows, macOS, Linux
- **Obsidian:** Desktop Version (0.15.0 oder höher)
- **Node.js:** LTS Version (18+ empfohlen) - nur für Entwicklung
- **Git:** Für Repository-Zugriff (nur für Entwicklung)

### Obsidian-Einstellungen

- **Community Plugins:** Aktiviert
- **Restricted Mode:** Deaktiviert (für lokale Plugins)
- **Safe Mode:** Deaktiviert (für Plugin-Loading)

---

## Installation

### Option 1: Lokale Installation (Entwicklung)

**Für Entwickler, die am Plugin arbeiten:**

#### Schritt 1: Repository klonen

```bash
git clone <repository-url> mindnet_obsidian
cd mindnet_obsidian
```

#### Schritt 2: Dependencies installieren

```bash
npm install
```

#### Schritt 3: Build

```bash
# Development Build (Watch Mode)
npm run dev

# Oder Production Build
npm run build
```

#### Schritt 4: Deployment in Vault

**Windows (PowerShell):**
```bash
npm run deploy:local
# oder
powershell -ExecutionPolicy Bypass -File scripts/deploy-local.ps1
```

**Manuell:**
1. Erstelle Plugin-Ordner: `<vault>/.obsidian/plugins/mindnet-causal-assistant/`
2. Kopiere Dateien:
   - `main.js` → Plugin-Ordner
   - `manifest.json` → Plugin-Ordner
   - Optional: `styles.css` → Plugin-Ordner (falls vorhanden)

#### Schritt 5: Plugin aktivieren

1. Öffne Obsidian
2. **Settings → Community Plugins**
3. Aktiviere "Mindnet Causal Assistant"
4. Plugin sollte jetzt geladen sein

### Option 2: Community Plugin Installation (Zukunft)

**Für Endnutzer (wenn Plugin im Community Store verfügbar):**

1. Öffne Obsidian
2. **Settings → Community Plugins**
3. **Browse** → Suche "Mindnet Causal Assistant"
4. **Install** → **Enable**

---

## Deployment

### Lokales Deployment (Entwicklung)

#### Automatisches Deployment (Windows)

**PowerShell-Script:** `scripts/deploy-local.ps1`

```powershell
# Script kopiert main.js, manifest.json nach Vault Plugin-Ordner
# Vault-Pfad muss in Script konfiguriert sein
```

**Verwendung:**
```bash
npm run deploy:local
```

#### Manuelles Deployment

**Schritte:**
1. Build ausführen: `npm run build`
2. Plugin-Ordner erstellen: `<vault>/.obsidian/plugins/mindnet-causal-assistant/`
3. Dateien kopieren:
   - `main.js`
   - `manifest.json`
   - Optional: `styles.css`
4. Obsidian Plugin reload (disable/enable)

### Production Deployment

#### Release-Prozess

**Schritt 1: Version bumpen**

```bash
npm version patch|minor|major
```

**Ergebnis:**
- `manifest.json` Version wird aktualisiert
- `package.json` Version wird aktualisiert
- `versions.json` Eintrag wird hinzugefügt

**Schritt 2: Build**

```bash
npm run build
```

**Ergebnis:**
- `main.js` wird erstellt (minified)
- TypeScript-Check wird ausgeführt

**Schritt 3: Git Commit**

```bash
git add manifest.json versions.json package.json
git commit -m "Release v1.0.1"
git tag v1.0.1
git push origin main --tags
```

**Schritt 4: GitHub Release**

1. Erstelle Release auf GitHub
2. **Tag:** `v1.0.1` (ohne `v` Prefix)
3. **Title:** `v1.0.1`
4. **Description:** Changelog
5. **Assets:** Upload `main.js`, `manifest.json`, optional `styles.css`

---

## Konfiguration

### Erste Konfiguration

Nach der Installation müssen Konfigurationsdateien im Vault vorhanden sein:

#### Standard-Pfade

```
_system/
  dictionary/
    edge_vocabulary.md
    graph_schema.md
    interview_config.yaml
    chain_roles.yaml
    chain_templates.yaml
    analysis_policies.yaml
```

#### Plugin-Settings

1. Öffne **Settings → Community Plugins → Mindnet Causal Assistant**
2. Prüfe Pfad-Settings:
   - `edgeVocabularyPath`: `_system/dictionary/edge_vocabulary.md`
   - `graphSchemaPath`: `_system/dictionary/graph_schema.md`
   - `interviewConfigPath`: `_system/dictionary/interview_config.yaml`
   - `chainRolesPath`: `_system/dictionary/chain_roles.yaml`
   - `chainTemplatesPath`: `_system/dictionary/chain_templates.yaml`

3. Passe Pfade an (falls abweichend)

#### Config-Dateien erstellen

**Falls Config-Dateien fehlen:**

1. Erstelle Ordner: `_system/dictionary/`
2. Erstelle Config-Dateien (siehe Administratorhandbuch)
3. Plugin lädt Configs automatisch beim Start

**Minimal-Beispiele:**

**edge_vocabulary.md:**
```markdown
# Edge Vocabulary

> [!edge-type] causes
> Canonical: causes
> Aliases: ausgelöst_durch
```

**interview_config.yaml:**
```yaml
version: "1.0"
frontmatter_whitelist: []
profiles:
  - key: experience_basic
    note_type: experience
    description: "Basic experience profile"
    defaults:
      folder: ""
    steps: []
```

**chain_roles.yaml:**
```yaml
version: "1.0"
roles:
  causal:
    edge_types:
      - causes
```

**chain_templates.yaml:**
```yaml
version: "1.0"
defaults:
  matching:
    required_links: false
templates: []
```

### Verifikation

**Plugin-Status prüfen:**
1. Öffne DevTools (`Ctrl+Shift+I` / `Cmd+Option+I`)
2. Prüfe Console-Logs:
   - `Vocabulary auto-loaded`
   - `Interview config auto-loaded`
   - `Chain roles loaded`
   - `Chain templates loaded`

**Commands testen:**
1. Command Palette (`Ctrl+P` / `Cmd+P`)
2. Suche "Mindnet"
3. Commands sollten verfügbar sein

---

## Upgrade

### Upgrade-Prozess

#### Option 1: Lokales Upgrade (Entwicklung)

**Schritte:**
1. Repository aktualisieren:
   ```bash
   git pull origin main
   ```
2. Dependencies aktualisieren (falls nötig):
   ```bash
   npm install
   ```
3. Build:
   ```bash
   npm run build
   ```
4. Deployment:
   ```bash
   npm run deploy:local
   ```
5. Obsidian Plugin reload (disable/enable)

#### Option 2: Community Plugin Upgrade (Zukunft)

**Automatisch:**
- Obsidian prüft automatisch auf Updates
- **Settings → Community Plugins → Updates**
- **Update** Button klicken

**Manuell:**
- Plugin deinstallieren → neu installieren

### Config-Migration

**Bei größeren Version-Updates:**

1. **Backup erstellen:**
   - Config-Dateien sichern
   - Vault-Backup erstellen

2. **Changelog prüfen:**
   - Breaking Changes beachten
   - Config-Format-Änderungen prüfen

3. **Configs aktualisieren:**
   - Neue Felder hinzufügen (falls nötig)
   - Deprecated Felder entfernen

4. **Plugin neu laden:**
   - Plugin disable/enable
   - Console-Logs prüfen

---

## Troubleshooting

### Plugin lädt nicht

**Symptom:** Plugin erscheint nicht in Settings oder zeigt Fehler.

**Lösung:**
1. Prüfe Obsidian-Version (min. 0.15.0)
2. Prüfe `manifest.json` Syntax
3. Prüfe `main.js` Existenz im Plugin-Ordner
4. Prüfe Console-Logs (DevTools F12)
5. Obsidian neustarten
6. Plugin disable/enable

### Config wird nicht geladen

**Symptom:** Console zeigt "Config not found" oder Fehler.

**Lösung:**
1. Prüfe Pfad in Settings
2. Prüfe Datei-Existenz im Vault
3. Prüfe Datei-Berechtigungen
4. Prüfe YAML-Syntax (für YAML-Dateien)
5. Prüfe Console-Logs für Details

### Build-Fehler

**Symptom:** `npm run build` schlägt fehl.

**Lösung:**
1. Prüfe Node.js-Version (`node --version`)
2. Dependencies neu installieren: `npm install`
3. Prüfe TypeScript-Fehler: `npm run build`
4. Prüfe `tsconfig.json` Syntax
5. Prüfe `esbuild.config.mjs` Syntax

### Deployment-Fehler

**Symptom:** `deploy-local.ps1` schlägt fehl.

**Lösung:**
1. Prüfe Vault-Pfad im Script
2. Prüfe PowerShell Execution Policy:
   ```powershell
   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   ```
3. Manuelles Deployment versuchen
4. Prüfe Plugin-Ordner-Berechtigungen

### Live-Reload funktioniert nicht

**Symptom:** Config-Änderungen werden nicht übernommen.

**Lösung:**
1. Prüfe Datei-Pfad (muss exakt mit Settings übereinstimmen)
2. Warte auf Debounce (200ms)
3. Manuelles Reload über Command
4. Plugin neu laden (disable/enable)

### Commands erscheinen nicht

**Symptom:** Commands sind nicht im Command Palette verfügbar.

**Lösung:**
1. Prüfe Plugin-Status (aktiviert?)
2. Prüfe Console-Logs für Fehler
3. Obsidian neustarten
4. Command Palette neu öffnen (`Ctrl+P`)

---

## Bekannte Probleme

### Windows: PowerShell Execution Policy

**Problem:** `deploy-local.ps1` wird blockiert.

**Lösung:**
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### macOS/Linux: Permissions

**Problem:** Plugin-Ordner kann nicht erstellt werden.

**Lösung:**
- Prüfe Vault-Ordner-Berechtigungen
- Manuell Plugin-Ordner erstellen

### Obsidian: Restricted Mode

**Problem:** Plugin wird nicht geladen.

**Lösung:**
- **Settings → Community Plugins → Restricted Mode** deaktivieren
- Für lokale Plugins erforderlich

---

## Best Practices

### Entwicklung

1. **Watch Mode verwenden:**
   ```bash
   npm run dev
   ```
   - Automatisches Rebuild bei Änderungen
   - Source Maps für Debugging

2. **Tests ausführen:**
   ```bash
   npm run test
   ```
   - Vor jedem Commit
   - Vor jedem Release

3. **Linting:**
   ```bash
   npm run lint
   ```
   - Code-Qualität prüfen
   - Vor jedem Commit

### Deployment

1. **Backup erstellen:**
   - Vor jedem Deployment
   - Config-Dateien sichern

2. **Staging testen:**
   - Test-Vault verwenden
   - Vor Production-Deployment

3. **Versionierung:**
   - SemVer verwenden
   - Changelog führen

### Wartung

1. **Regelmäßige Updates:**
   - Dependencies aktualisieren
   - Obsidian API Updates prüfen

2. **Monitoring:**
   - Console-Logs prüfen
   - User-Feedback sammeln

3. **Dokumentation:**
   - Änderungen dokumentieren
   - Breaking Changes hervorheben

---

## Weitere Ressourcen

- **Benutzerhandbuch:** Endnutzer-Workflows
- **Administratorhandbuch:** Konfiguration und Wartung
- **Entwicklerhandbuch:** Code-Struktur und Erweiterungen
- **Architektur-Dokumentation:** System-Übersicht

---

**Ende der Installation & Deployment Anleitung**