Verbinde deinen Assistenten mit KLARA.

Was das bringt

«Ist die Rechnung für Muster AG schon bezahlt?»

Voraussetzungen

• Ein Assistent, der auf deine Dateien zugreifen und Programme ausführen darf. Welche App du dafür nutzt, spielt keine Rolle. Ein Chat ohne Zugriff auf deine Dateien reicht nicht.
• Ein KLARA-Konto und ein Zugang, den KLARA für die API-Nutzung deiner Firma freigegeben hat. Das Programm unterstützt einen API-Key und, falls für dein Konto erlaubt, den KLARA-Login.

Was du danach kannst

Grenzen, ehrlich

• Welche Rechte ein KLARA-Zugang hat, hängt vom bereitgestellten Zugang und vom Konto ab. Behandle API-Key und Login wie ein Passwort. Prüfe zuerst mit einem Lese-Aufruf, was der Zugang tatsächlich erlaubt, und frag KLARA nach einer eingeschränkten Variante.
• Versand- und Lösch-Operationen verweigert das Programm ohne --force. Das ist Absicht: verschicken und löschen bleiben bewusste Entscheide.
• Dein Assistent macht Fehler wie ein neuer Mitarbeiter. Darum gilt: anlegen ja, aber du gibst frei.

Anleitung für deinen Assistenten

1. 1

   Im Assistenten einrichten

   Dieser Workflow gehört zum Thema Finanzen. Er liegt danach in 01_finanzen/workflows/klara/, bei jeder Person am selben Ort.

   1. Prüfe, ob du in einem Assistenten arbeitest. Im geöffneten Ordner liegen AGENTS.md und CONTEXT.md, und in CONTEXT.md steht eine Tabelle mit der Kopfzeile | Aufgabe | Ordner | Status |. Fehlt das, sag der Person, dass der Gratis-Starter von wirdrei.digital diesen Rahmen einrichtet: https://wirdrei.digital/assistent. Frag sie, ob sie zuerst den Starter einrichten oder ohne ihn weitermachen will. Ohne Starter legst du einen neuen, leeren Unterordner an, dessen Namen die Person bestätigt, und arbeitest nur darin: Alle Pfade dieser Anleitung liegen dann in diesem Unterordner, nichts ausserhalb wird angefasst. Weg fallen dabei die Router-Zeilen und der Eintrag in CHANGELOG.md (Punkte 2 und 3), die Vorlagen aus dem Skill workflow-builder, _setup/werkzeuge.md, support.md und die Pflege. Die CONTEXT.md aus Schritt 2 schreibst du selbst, und was sonst in _setup/werkzeuge.md stünde (installierte Pakete und Skripte, Ort von Python), hältst du dort unter «Quellen» fest. Wo diese Anleitung auf support.md verweist, nennst du https://wirdrei.digital/kontakt.

   2. Bereich anlegen, falls er fehlt. Kopiere assets/bereich-CONTEXT.md aus dem Skill workflow-builder deines Assistenten nach 01_finanzen/CONTEXT.md und fülle {{BEREICH}} mit 01_finanzen und {{THEMA}} mit Finanzen. Wo der Skill liegt, steht im Haupt-Router CONTEXT.md in der Zeile «Eigenen Workflow bauen». Trag den Bereich direkt unter der letzten Zeile der Tabelle im Haupt-Router ein:

      | Finanzen | `01_finanzen/` | eingerichtet |
      

   3. Workflow anlegen. Gibt es 01_finanzen/workflows/klara/ schon, frag, ob du ihn ergänzen sollst, und überschreib nichts. Sonst kopierst du assets/workflow-CONTEXT.md aus demselben Skill nach 01_finanzen/workflows/klara/CONTEXT.md. Den Inhalt liefert Schritt 2. Trag den Workflow direkt unter der letzten Zeile der Tabelle von 01_finanzen/CONTEXT.md ein, mit der Aufgabe in den Worten der Person:

      | <Aufgabe> | `workflows/klara/` | eingerichtet |
      

      Halte die Einrichtung zuoberst in CHANGELOG.md fest: Datum, was, warum und der Rückweg (den Ordner 01_finanzen/workflows/klara/ und seine Router-Zeilen löschen).

   4. Gemeinsames liegt an einem Ort. Schreibstil steht nur in _marke/voice.md, Firmendaten nur in _marke/firmendaten.md. Braucht dieser Workflow eine davon und sie fehlt, kopierst du assets/marke-voice.md oder assets/marke-firmendaten.md aus dem Skill workflow-builder dorthin. Sie bleiben ENTWURF, bis die Person zustimmt. Python-Pakete installierst du nur, wenn dieser Workflow sie nennt, prüfst vorher in _setup/werkzeuge.md, ob sie schon da sind, und trägst sie dort ein. Dort stehen auch die Pfade von uv, Python und dem Laufzeitordner: Wo diese Anleitung "<uv>", "<python>" oder "<laufzeitordner>" schreibt, setzt du den Pfad von dort ein, immer in Anführungszeichen, denn er enthält oft Leerzeichen. In PowerShell steht & vor dem ersten Pfad eines Befehls. Schlüssel und Passwörter gehören nie in den Assistenten-Ordner und nie in den Chat. Braucht dieser Workflow einen, legst du die Datei "<laufzeitordner>/secrets/<dienst>.env" mit leeren Werten an und öffnest sie für die Person, ohne auf das Schliessen des Editors zu warten: auf dem Mac mit open -e "<datei>", auf Windows in Git Bash mit start "" notepad "<datei>" und in PowerShell mit Start-Process notepad "<datei>". Sie trägt die Werte ein und speichert, du liest sie nie in den Chat. Programme mit eigener Anmeldung behalten den Zugang in ihrem eigenen Speicher, wenn dieser Workflow das so vorsieht.

   5. Zum Schluss kommt der Test mit echten Daten, danach bietest du den Skill pflege an (letzter Schritt).

2. 2

   Vertrag ausfüllen

   Füll die CONTEXT.md so aus. Was in eckigen Klammern steht, klärst du mit der Person:

   # KLARA-Anbindung
   
   **Status: eingerichtet** (aktiv erst nach einem sauberen echten Durchlauf)
   **Auslöser:** Die Person fragt nach Artikeln, Kunden, Rechnungen oder Buchhaltung in KLARA.
   Pfade in diesem Vertrag liegen in `01_finanzen/workflows/klara/`, ausser sie beginnen mit `_marke/`, `_setup/` oder einer Bereichsnummer.
   
   ## Zweck
   
   [Wofür vor allem: Artikel, Kunden, Fakturierung?] Gelesen und vorbereitet wird über das
   Programm `klara` (klara-cli von wirdrei.digital).
   
   ## So arbeitest du
   
   1. Lesen geht ohne Rückfrage: `"<klara>" commands --json` zeigt alle Befehle.
   2. Anlegen und Ändern: erst den Entwurf im Chat zeigen, dann auf ein ausdrückliches Ja
      warten, dann ausführen.
   3. Versand- und Lösch-Operationen (zum Beispiel eine Rechnung verschicken, einen
      Datensatz löschen) verweigert das Programm ohne `--force`. `--force` setzt du nur
      nach einem eigenen Ja für genau diesen Vorgang.
   4. Meldet das Programm einen ungültigen Zugang, sag es der Person und lass sie `"<klara>" init`
      im Terminal neu ausführen.
   
   ## Quellen
   
   | Was                                      | Wo                 | Zugriff                      |
   | ---------------------------------------- | ------------------ | ---------------------------- |
   | Artikel, Kunden, Rechnungen, Buchhaltung | KLARA über `klara` | lesen, anlegen nach Freigabe |
   
   Der Zugang liegt im eigenen Speicher des Programms (`"<klara>" init`, Dateirechte 0600),
   nie hier und nie im Chat.
   
   ## Ausgabe
   
   Antworten im Chat, Entwürfe im Chat und nach Freigabe die Einträge in KLARA.
   
   ## Grenzen
   
   - Schreibt nicht in den Assistenten-Ordner, ausser in diese `CONTEXT.md`.
   - Beträge und Kundendaten stammen aus KLARA oder von der Person, nie geschätzt.
   - Senden, Löschen und Bezahlen braucht jedes Mal ein eigenes Ja.
   - Zugang: [API-Key oder KLARA-Login, von KLARA freigegeben am JJJJ-MM-TT]
   
   ## Test
   
   [Datum des ersten sauberen Lese-Aufrufs]
   

   Frag die Person nach dem Zweck und lass sie die Regeln bestätigen, bevor du den Zugang einrichtest.

3. 3

   Programm installieren

   Lade von https://github.com/wir-drei-digital/klara-cli/releases/latest das Archiv für das System dieses Computers (macOS und Linux als .tar.gz für amd64 und arm64, Windows als .zip). Prüfe den Download gegen checksums.txt und entpacke das Archiv in einen leeren Ordner "<laufzeitordner>/downloads/klara/". Kopiere daraus nur das Programm klara (auf Windows klara.exe) nach "<laufzeitordner>/bin/", wo auch uv liegt. Trag den vollen Pfad in _setup/werkzeuge.md ein, etwa "<laufzeitordner>/bin/klara". Das ist ab jetzt "<klara>": Du rufst das Programm immer mit diesem Pfad in Anführungszeichen auf und änderst keine Systemeinstellungen.

   Alternative, falls eine Go-Toolchain da ist: GOBIN="<laufzeitordner>/bin" go install github.com/wir-drei-digital/klara-cli/cmd/klara@latest (in PowerShell setzt du vorher $env:GOBIN="<laufzeitordner>\bin").

   Prüfe die Installation mit "<klara>" commands --json. Kommt eine Liste von Befehlen zurück, ist sie da. Trag Programm und Version in _setup/werkzeuge.md ein.

4. 4

   Zugang wählen

   Klär mit der Person und bei Bedarf mit KLARA, welcher Zugang für ihre Firma freigegeben ist:

   • API-Key Verwende ihn, wenn KLARA einen Key für die Firma bereitgestellt hat.
   • KLARA-Login Verwende ihn nur, wenn KLARA und die internen Regeln der Person diesen Zugang für die Anbindung erlauben. Das Programm speichert die Sitzung lokal und versucht, sie bei Bedarf zu erneuern.

   Wichtig: Die Person tippt Passwort oder Key nie in den Chat. "<klara>" init fragt beides direkt im Terminal ab und speichert es lokal mit Dateirechten 0600.

5. 5

   Zugang speichern

   Lass die Person "<klara>" init im Terminal ausführen. Gib ihr dafür den Befehl mit dem vollen Pfad aus _setup/werkzeuge.md, in PowerShell mit & davor. Der Einrichtungsdialog fragt, welcher Zugang gewünscht ist, sammelt ihn ein und prüft ihn gleich mit einem einzigen Lese-Aufruf.

6. 6

   Mit einem Lese-Aufruf testen

   Mach einen Lese-Aufruf und zeig der Person das Ergebnis:

   "<klara>" articles list --limit 10
   

   Kommt eine Liste zurück, steht die Anbindung.

7. 7

   Abschliessen

   Lief der Test sauber, setzt du den Status auf aktiv: in 01_finanzen/workflows/klara/CONTEXT.md, in der Zeile von 01_finanzen/CONTEXT.md und beim Bereich im Haupt-Router, falls dort noch eingerichtet steht. Halte das Datum des Durchlaufs im Abschnitt «Test» fest. Lief er nicht sauber, bleibt der Status eingerichtet, und du korrigierst die Regel in der CONTEXT.md, nicht nur das einzelne Ergebnis.

   Frag danach: «Soll ich kurz prüfen, ob alles sauber eingehängt ist?» Sagt die Person ja, startest du den Skill pflege. Ohne Assistenten-Rahmen (siehe Schritt 1) entfallen Router und Pflege.