logbuch/docs/skill.md

name, description

name	description
logbuch	Use when writing project updates into Logbuch, the update archive of the NYO group. Covers the API at /api/v1, the editorial rules, images, dating and publishing. Trigger on "Logbuch", "Eintrag schreiben", "Projekt-Update", "Änderung festhalten", or when work is finished and someone should hear about it.

Logbuch

Logbuch hält fest, was in den Produkten passiert ist. Alle zwei Wochen entsteht pro Projekt ein Eintrag über das, was fertig geworden ist. Es ist kein Änderungsprotokoll für Entwickler und keine Pressemitteilung, sondern für Kollegen und Kunden, die wissen wollen, was sich geändert hat, ohne Tickets oder Code zu lesen.

Was du wissen musst, bevor du schreibst

Ein Zugang kann niemals veröffentlichen. Alles, was du anlegst, ist ein Entwurf. Ein Mensch schaut drauf und gibt frei. Schreib entsprechend fertig, nicht halb.

Jede Anfrage trägt das Token im Kopf:

Authorization: Bearer <token>

Die Basis-Adresse steht in deiner Aufgabe, im Zweifel https://logbuch.nyo.de. Alles liegt unter /api/v1.

Dein Zugang hat drei Eigenschaften, die bestimmen, was du darfst:

Eigenschaft	Bedeutung
Modus	read liest, write schreibt zusätzlich
Zielgruppe	internal, customer oder public. Du siehst und setzt nie etwas Offeneres
Projektbindung	Ist ein Projekt gesetzt, gilt der Zugang ausschließlich dort

Reihenfolge

1. GET /api/v1/projects - welche Projekte darfst du bespielen
2. GET /api/v1/post-types - die gültigen Schlüssel der Beitragsarten, nicht raten
3. GET /api/v1/style-guide - der Redaktionsleitfaden im Wortlaut
4. POST /api/v1/media - Bilder hochladen, wenn du welche hast
5. POST /api/v1/posts - Entwurf anlegen
6. PUT /api/v1/posts/:id/blocks - Inhalt setzen
7. GET /api/v1/posts/:id - zurücklesen und prüfen

Einen Eintrag anlegen

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "project": "trakk",
    "title": "SLA-Uhr zählt Feiertage nicht mehr mit",
    "teaser": "Reaktionszeiten liefen über Wochenenden weiter und lösten falsche Eskalationen aus.",
    "type": "fix",
    "audience": "customer",
    "cover_media_id": "<medien-id>",
    "publish_at": "2026-06-04T09:00:00Z",
    "idempotency_key": "sla-2026-06-04"
  }' \
  "$BASE/api/v1/posts"

Die Antwort trägt die Kennung. Merk sie dir, du brauchst sie für Blöcke, Änderungen und Löschen. Hast du sie verloren, findest du den Entwurf über GET /api/v1/posts/<slug>.

idempotency_key setzen, wenn dein Lauf abbrechen könnte. Derselbe Schlüssel liefert denselben Eintrag zurück, statt einen zweiten anzulegen.

number ist bei Entwürfen null. Die laufende Nummer vergibt Logbuch beim Veröffentlichen, damit im Archiv keine Lücken entstehen.

Inhalt setzen

curl -s -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{"blocks":[
    {"type":"text","data":{"text":"Bisher lief die Uhr durch. Wer freitags meldete, hatte montags eine Eskalation im Postfach."}},
    {"type":"image","data":{"mediaId":"<medien-id>"}},
    {"type":"text","data":{"text":"Jetzt zählt nur noch die vereinbarte **Servicezeit**."}}
  ]}' \
  "$BASE/api/v1/posts/<id>/blocks"

Der Aufruf setzt die Blöcke vollständig, in der übergebenen Reihenfolge. Höchstens 100.

Typ	Felder in data
text	text, als Markdown: Absätze, fett, kursiv, Verweise, Listen, ### als Zwischenüberschrift. Kein rohes HTML
image	mediaId
gallery	mediaIds
before_after	beforeMediaId, afterMediaId
video	url, title
quote	text, source
code	code, language
link	url, title, description
callout	text, tone

Bilder

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F "[email protected]" \
  -F "project=trakk" \
  -F "alt=Spaltenmenü mit den neuen Einträgen" \
  "$BASE/api/v1/media"

project ist der Slug, bei projektgebundenem Token darf er wegbleiben. Nur Bildformate, höchstens 15 MB. Die Antwort trägt die Medien-Kennung für cover_media_id und für Bildblöcke.

Ein Bild zeigt, was sich geändert hat. Kein Firmenlogo, kein Symbolbild. Findest du nichts, was den Punkt wirklich zeigt, lass es weg. Der Alt-Text beschreibt, was zu sehen ist, und ist bei öffentlichen Beiträgen Pflicht, sonst lässt sich der Beitrag nicht freigeben.

Ein Bild wieder loswerden: DELETE /api/v1/media/:id. Hängt es noch an einem Beitrag, kommt 409.

Datum

publish_at nimmt eine ISO-Zeitangabe, beim Anlegen und beim Ändern. Du veröffentlichst damit nichts, du hinterlegst nur das Datum. Gibt ein Mensch frei, übernimmt Logbuch genau dieses statt der aktuellen Uhrzeit. So landen ältere Meldungen an der richtigen Stelle im Archiv.

Wie es klingen soll

Aufbau. Titel, Anreißer, dann der Text. Der Titel sagt, was sich geändert hat, nicht dass sich etwas geändert hat. Der Anreißer fasst in zwei bis drei Sätzen zusammen, was der Leser davon hat. Der Text erklärt, was vorher war, was jetzt ist, und was zu tun bleibt.

Gute Titel:

• "SLA-Uhr zählt Feiertage nicht mehr mit"
• "Spalten per Rechtsklick verwalten"

Schlechte Titel:

• "Verbesserungen an der Tabelle" - sagt nichts
• "Wir haben ein spannendes neues Feature gebaut" - Werbung statt Information

Ton. Sachlich und direkt, aktive Verben. Keine Werbesprache, keine Superlative, keine Ausrufezeichen, keine Emojis. Keine Gedankenstriche, immer normales Minus. Echte Umlaute, niemals ae, oe, ue.

Länge. So lang wie nötig, meist drei bis sechs Absätze. Eine Fehlerbehebung darf aus zwei Sätzen bestehen.

Zielgruppe. internal für Umbauten, Zwischenstände und alles über Kunden. customer für das, was ein Kunde des Produkts wissen soll. public nur für das, was auch außerhalb stehen darf. Im Zweifel die engere wählen.

Fehler

Antworten kommen als Problem-JSON mit type, title, status und detail.

Status	Bedeutung
400	fehlerhafte Eingabe, detail sagt welches Feld
401	Token fehlt oder ist widerrufen
403	dem Zugang fehlt das Recht, etwa eine zu offene Zielgruppe
404	nicht vorhanden oder für diesen Zugang nicht sichtbar
409	bereits veröffentlicht, Änderung nicht mehr möglich
422	unbekannte Beitragsart oder fehlende Projektbindung

Was du nicht tust

• Veröffentlichen. Geht nicht und soll nicht.
• Eine offenere Zielgruppe setzen, als dein Zugang hat.
• Beitragsarten raten statt GET /api/v1/post-types zu fragen.
• Symbolbilder anhängen, damit etwas bunt ist.
• Bei einem Abbruch blind neu anlegen. Erst GET /api/v1/posts/<slug> fragen oder idempotency_key verwenden.

Vollständige Beschreibung

GET /api/v1/openapi.json liefert die maschinenlesbare Fassung mit allen Feldern und Antworten. GET /api/v1/style-guide liefert den Leitfaden. Beide verlangen dasselbe Token.