velum-raycast/README.md

# Velum Raycast Extension

Raycast-Extension für PII-sichere Text- und Projekt-Workflows mit Velum: Inhalte werden über die konfigurierte Velum-API pseudonymisiert, bevor sie an externe KI-Modelle oder andere Tools weitergegeben werden. Die Velum-API sollte für vertrauliche Kundendaten in einer dafür geeigneten Umgebung betrieben werden.

## Projektdateien

`Projektdateien pseudonymisieren` übernimmt zuerst den geöffneten Finder-Ordner; bei Bedarf kann er im Formular erneut übernommen oder manuell gewählt werden. Im Formular werden die zu erkennenden Kategorien ausgewählt (Orte sind wegen häufiger Fehlalarme zunächst abgewählt). Danach analysiert Velum alle geeigneten Text-, DOCX-, XLSX-, PPTX- und PDF-Dateien sowie ihre Namen. Kleine Textdateien und Namen werden in Paketen analysiert, um die Anzahl der API-Aufrufe zu verringern. Die Prüfung zeigt jede eindeutige Zuordnung einmal, nach Kategorie gruppiert, mit der Anzahl ihrer Vorkommen. Eine Zuordnung an- oder abzuwählen gilt für alle betroffenen Dateien; einzelne Vorkommen lassen sich bei Bedarf ansehen. Nach der Auswahl lassen sich erkannte Personen optional zusammenfassen, sodass ihre Erwähnungen denselben Platzhalter erhalten. `Pseudonymisierte Kopien erstellen` schreibt Dateien in den Raycast-Support-Bereich außerhalb des Projektordners. Alternativ ersetzt `Originaldateien ersetzen` die Dateien und gegebenenfalls ihre Namen vor Ort; zuvor legt Velum eine private Sicherung der Originale im Raycast-Support-Bereich an. PDF wird dabei als DOCX ausgegeben.

Projektbegriffe werden zeilenweise als `BEGRIFF: KundenSuite` oder `PERSON: Max Mustermann` eingegeben, nur für dieses Projekt gespeichert und mit `force_masks` pro API-Aufruf übertragen. Die globale Velum-Regelliste bleibt unverändert. Beim Erstellen eines Projektstands werden abgewählte Treffer als typgebundene Projekt-Whitelist außerhalb des Quellordners gespeichert und bei späteren Läufen nicht erneut angeboten. Die Whitelist lässt sich im Startformular bearbeiten. Eine neue Projektbearbeitung übernimmt die bestätigten Zuordnungen des letzten Projektstands, sodass Platzhalter konsistent bleiben. Nach einem Lauf mit Kopien bleibt der Klartext-Quellordner erhalten und kann nach Dateiänderungen erneut bearbeitet werden. Nach dem Ersetzen vor Ort werden unveränderte bereits maskierte Dateien in den nächsten Stand übernommen; neue oder geänderte Dateien werden analysiert. Ein neuer Projektstand enthält auch die übernommenen Dateien für die Rückübersetzung.

`Projektdateien rückübersetzen` wählt einen Projektstand und einzelne Dateien und erstellt Klartext-Kopien unter `~/Downloads/Velum`. Der Quellordner bleibt unverändert. Die neue Projektfunktion benötigt eine Velum-API mit `/api/project-capabilities`, Trefferprüfung für Dokumente, projektbezogenen `force_masks` und `/api/depseudonymize-document`.

### Einmalige Übernahme aus KI Datenschutz

Velum enthält **keinen** Laufzeit-Zugriff auf die frühere Extension. Das eigenständige Skript `tools/migrate-ki-datenschutz.mjs` wandelt einen bereits anonymisierten KI-Datenschutz-Projektordner samt seiner eingefrorenen Variante-Tabelle in einen Velum-Projektstand um. Es verändert weder den alten Ordner noch die alte Tabelle. Der neue Stand erscheint anschließend unter `Projektdateien rückübersetzen`; Begriffe nur für dieses Projekt werden als Velum-Projektregeln übernommen. Alle Inhalte bleiben während der Migration lokal und werden nicht an eine API gesendet. Im Terminal protokolliert das Skript nur Zahlen, keine Werte oder Dateinamen.

1. In Raycast `Migrationsziel anzeigen` öffnen und den Velum-Datenordner kopieren.
2. Den alten Projektordner und die zugehörige Datei `projects/<Projekt-ID>.json` aus dem Datenordner von KI Datenschutz angeben. Mit `--preview-file` eine prüfbare Vorschau erstellen:

   ```bash
   node tools/migrate-ki-datenschutz.mjs --project "/Pfad/zum/Projekt" --manifest "/Pfad/zu/projects/abcdef0123456789.json" --target-support "/kopierter/Velum-Datenordner" --preview-file "$HOME/Downloads/Migrationsvorschau.md"
   ```

   Die Datei zeigt Quell- und Zielnamen, alte und neue Platzhalter samt Häufigkeit pro Datei sowie übersprungene Pfade mit Grund. Sie enthält keine Klartextwerte aus der Zuordnungstabelle. Da Dateinamen trotzdem vertraulich sein können, wird sie nur lokal mit eingeschränkten Dateirechten erstellt und eine vorhandene Datei nie überschrieben. Der Vorschaupfad muss außerhalb des Projekts liegen. Ohne `--preview-file` bleibt es bei der Zahlenausgabe im Terminal.

3. Nach Prüfung denselben Befehl **ohne** `--preview-file`, dafür mit `--apply` ausführen. Danach den neuen Stand in Velum öffnen und den Klartext-Export mit einem Testdokument prüfen.

Das Skript übernimmt Text- und Codedateien. Binäre Dateien und bisher nicht anonymisierte Office/PDF-Dateien werden gezählt und ausgelassen; sie müssen im neuen Projektdateien-Befehl geprüft werden. Platzhalter, die in technischen Bezeichnern kleben, behalten ein eigenes Rückübersetzungsverhalten. Wenn die alte Variante-Tabelle mehrere Klartext-Schreibweisen für denselben Platzhalter enthält, ist die exakte frühere Schreibweise nicht mehr rekonstruierbar; das Skript verwendet dieselbe kontextabhängige Kanonisierung wie der alte Klartext-Export. Die alte Extension kann nach erfolgreicher Prüfung entfernt werden.

## Konfiguration

Alle Werte sind in den Raycast-Einstellungen pro Extension einstellbar.

**Velum & Authentik (Pflicht):**
- `Velum Basis-URL` — z. B. `https://velum.example.com`
- `Authentik Token-URL` — z. B. `https://auth.example.com/application/o/token/`
- `OAuth Client-ID`
- `Dienstkonto-Benutzername`
- `Dienstkonto App-Passwort` (gespeichert als Raycast-Passwort-Preference)
- `OAuth Scope` — optional, Standard `profile`

**Verhalten:**
- `Standard-Sitzungsmodus` — `Aktive Sitzung wiederverwenden` (Default), `Neue Sitzung pro Anfrage`, `Tagessitzung`
- `Ausgabe der Schnellbefehle` — `In die Zwischenablage kopieren` (Default) oder `Am Cursor einfügen`
- `Eigener Name` — Default-Signatur für AI-generierte Email-Antworten, im Antwort-Befehl pro Aufruf überschreibbar

Das KI-Modell ist keine Preference: jeder AI-Befehl zeigt ein `KI-Modell`-Dropdown mit dem aktuellen Modell-Katalog aus `src/ai.ts`. Die Auswahl wird in `LocalStorage` (`velum.ai.last-model`) persistiert und ist beim nächsten Aufruf in jedem AI-Befehl vorausgewählt.
- `Maximale Anzahl gespeicherter Sitzungen` — älteste werden geprunt (Default 20)
- `Raycast nach Kopieren/Einfügen schließen` — Auto-Close und Pop-To-Root nach AI-Workflow-Abschluss (Default an)

Access-Tokens und Velum-Sitzungen liegen im Raycast-LocalStorage.

## Befehle

### AI-Workflows (Pseudonymisieren → Raycast AI → Wiederherstellen)

Jeder AI-Befehl pseudonymisiert die Eingabe via Velum, zeigt einen Confirm-Schritt (pseudonymisierter Text editierbar bevor er an die KI geht), streamt die AI-Antwort und ersetzt zum Schluss lokal alle Platzhalter mit den Originalen. Default-Output ist Rich Text (HTML, via osascript ans System-Pasteboard — siehe Raycast 2.0 Beta unten); zusätzlich gibt es eine Markdown-Copy-Action und eine Paste-Action.

- `Email-Konversation zusammenfassen` — strukturierte Markdown-Zusammenfassung eines Mailverlaufs (Teilnehmer, Anliegen, Verlauf, Action Items). HTML-Copy für Mail/Outlook.
- `Email-Antwort generieren` — verfasst eine deutsche Antwort auf einen markierten Mailverlauf, mit anpassbarer Anrede, Schluss, Tonalität und optionalem Hinweis auf den AI-Ursprung. Nutzt OAuth-Personen-Platzhalter aus dem Verlauf.
- `Briefing aus Notizen` — strukturiertes Briefing (Kontext, Teilnehmer, Entscheidungen, Action Items, Offene Punkte) aus Notizen, Stichpunkten oder Meeting-Transkripten.
- `Action Items extrahieren` — Markdown-Tabelle (Aufgabe / Verantwortlich / Deadline / Status) aus Transkripten, Threads oder Notizen.
- `Strukturierte Daten extrahieren` — JSON oder Markdown-Tabelle aus Freitext, gemäß einem frei beschriebenen Schema.
- `Projektstatusbericht erstellen` — Steering-Update für den Lenkungsausschuss aus Rohnotizen: Status (Ampel), Fortschritt, Top-Risiken, Entscheidung, nächste Schritte, GF-Summary. Triggerphrasen in den zusätzlichen Anweisungen: „Mach mir auch eine GF-Mail dazu.", „Wo sind blinde Flecken?", „Kürzer."

### Pseudonymisieren

- `Text pseudonymisieren` (View) — Text manuell eingeben, Sitzung und Entitätstypen wählen, Mapping inspizieren.
- `Markierten Text pseudonymisieren` (No-View) — Schnellbefehl: aktuelle Selektion wird pseudonymisiert und je nach Preference kopiert oder eingefügt.
- `Zwischenablage pseudonymisieren` (No-View) — analog für den Zwischenablage-Inhalt.

### Wiederherstellen

- `Text wiederherstellen` (View) — Platzhalter-Text und Sitzung wählen, Originale per Velum oder lokal einsetzen.
- `Markierten Text wiederherstellen` (No-View) — Selektion mit der aktiven Sitzung restaurieren.
- `Zwischenablage wiederherstellen` (No-View) — analog für die Zwischenablage.

### Sitzungen

- `Sitzungen verwalten` — Sitzungen anlegen, aktivieren, ansehen, leeren oder löschen. Zeigt das Mapping je Sitzung als Markdown-Tabelle.

## Sitzungen

Eine Sitzung ist eine wachsende Velum-Zuordnung zwischen Platzhaltern (`<PERSON_1>`, `<ORG_2>`, …) und Originalwerten. Welche Sitzung ein Schnellbefehl benutzt, regelt der Sitzungsmodus:

- `Aktive Sitzung wiederverwenden` — Konsistenz über mehrere Anfragen, ideal für längere Korrespondenzen.
- `Neue Sitzung pro Anfrage` — vollständige Isolation, jede Anfrage bekommt frische Platzhalter.
- `Tagessitzung` — eine Sitzung pro Tag, ein Kompromiss aus Konsistenz und Isolation.

Die View-Befehle bieten zusätzlich eine explizite Sitzungs-Auswahl plus eine `Neue Sitzung`-Option.

## Raycast 2.0 Beta

Die Extension läuft auf der stabilen Raycast-Version sowie der 2.0 Beta. Für die 2.0 Beta sind drei Workarounds in `src/selection.ts` und `src/ai-views.tsx` enthalten:

- **Selektion erfassen** — `getSelectedText()` braucht in 2.0 Beta einen vorangestellten `Clipboard.clear()`-Trigger plus einen `readText`-Fallback für Outlook und ähnliche Electron-Apps. Der Helper `getSelectedTextSafely` deckt das ab.
- **Rich Text Copy** — `Clipboard.copy({ html, text })` schreibt in 2.0 Beta nur Plain Text. `copyRichText` shellt aus zu `osascript -l JavaScript` und setzt `public.html` + `public.utf8-plain-text` direkt am NSPasteboard, sodass beim Einfügen in Word/Outlook eine echte gerenderte Tabelle landet.
- **Pop-To-Root nach Abschluss** — nach Copy/Paste wird mit `closeMainWindow({ popToRootType: PopToRootType.Immediate })` der Navigations-Stack geleert, damit beim nächsten Raycast-Öffnen nicht das alte Result-View wieder hochkommt. Per Preference `Raycast nach Kopieren/Einfügen schließen` abschaltbar.

## Entwicklung

```bash
npm install
npm run dev    # ray develop — live reload, lädt die Extension in den lokalen Raycast
npm run lint
npm run build  # ray build -e dist
```

Voraussetzungen: macOS, Node 22+, Raycast (Pro für die AI-Befehle).