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 einen im Finder ausgewählten Ordner. Ohne Auswahl versucht der Befehl, den geöffneten Finder-Ordner zu übernehmen; andernfalls steht die Ordnerauswahl bereit. Danach werden geeignete Text-, DOCX-, XLSX-, PPTX- und PDF-Dateien ausgewählt. Alle erkannten Treffer einschließlich Datei- und Ordnernamen erscheinen mit Kontext und müssen vor dem Erstellen der Kopien geprüft werden. Personen, Orte und Organisationen sind zunächst abgewählt; explizite Projektbegriffe und strukturierte Treffer sind vorausgewählt. Erst `Kopien erstellen` schreibt Dateien in den Raycast-Support-Bereich außerhalb des Projektordners. 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. Eine neue Projektbearbeitung übernimmt die Zuordnung des letzten Projektstands, sodass Platzhalter konsistent bleiben.

`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).