Authoring — Wie schreibe ich ein Brain?

Kurzanleitung für Menschen und Agenten, die ein neues Brain anlegen oder bearbeiten.

Empfohlener Weg: die CLI (gts add, Phase 3). Dieses Dokument beschreibt, was die CLI automatisiert — und was du manuell beachten musst, wenn du direkt editierst.

1. Ort + ID-Schema

Jedes Brain bekommt eine global eindeutige ID im Format

<instance-slug>.<category>.<path>[.<subpath>...]

Beispiele: kuble.slow.werte, kuble.projekt.nori-v3, gustavo.private.werte, gustavo.business.kuble.werte.

Die ID spiegelt den Pfad im Instanz-Verzeichnis:

Kategorie Instanz-Typ Dateipfad (relativ zum Instanz-Root)
slow nur business brains/slow/<path>.md
kunde beide brains/rapid/kunden/<slug>/index.md (oder <slug>/<sub>.md für verschachtelte)
projekt beide brains/rapid/projekte/<slug>/index.md (dito)
knowledge beide brains/knowledge/<path>.md
inbox beide brains/inbox/<slug>.md
private nur personal soul/private/<path>.md (nie gesynct)
business nur personal soul/business/<business-slug>/<path>.md (read-only, one-way gepullt)

Regel: Pfad und ID müssen übereinstimmen. brains/rapid/projekte/nori-v3/index.md ↔ id: <instance>.projekt.nori-v3. Der Linter (Phase 3) rejected Commits, die das verletzen.

Siehe SCHEMAS.md für die vollständige Frontmatter-Referenz.

2. Frontmatter-Template

Minimal gültiges Frontmatter:

---
id: <instance>.<category>.<slug>
category: <category>
title: Lesbarer Titel
owner: deine@email.de
created: 2026-04-17
updated: 2026-04-17
---

Kategorie-spezifische Pflichtfelder:

  • kunde: zusätzlich status: prospect|active|paused|churned
  • projekt: zusätzlich status: active|paused|done|archived

Optional (alle Kategorien): tags, visibility, description, encrypted.

Vollständige Beispiele: ../examples/business-instance-kuble/, ../examples/personal-instance-gustavo/.

3. Inhalt strukturieren

  • H1 (# Titel): nur einmal, als Titel des Dokuments.
  • H2 (## Sektion): strukturelle Hauptteile. Diese Namen sind die Einheiten für selective sync.
  • H3+ (### Unter): Details.

Wichtig für Projekt-Brains mit Sync: H2-Namen in sync.fields müssen case-sensitive stimmen. Wenn fields: [Goals], muss die Sektion ## Goals heißen (nicht ## Ziele).

4. Speichern & commiten

Über CLI (empfohlen, ab Phase 3)

gts add <brain-id>                  # Neues Brain anlegen
gts edit <brain-id>                 # Bearbeiten

CLI schreibt, validiert, commitet atomar (core.brain.write — siehe INPUTS.md).

Manuell

  1. Datei schreiben an den korrekten Pfad.
  2. updated: auf heutiges Datum setzen.
  3. git add <datei> && git commit -m "brain(<scope>): <was>".
  4. Pre-commit-Hook (Phase 3) validiert Schema + Pfad-ID-Konsistenz + Links + Orphans.

5. Sync einrichten (nur Projekt-Brains)

Wenn ein Projekt in Business und Personal existieren soll:

  1. Lege das Brain auf beiden Instanzen an (kuble.projekt.x auf Business, <personal>.projekt.x auf jedem teilnehmenden Personal).

  2. In beiden Frontmattern sync-Block setzen, der jeweils auf den anderen zeigt:

    sync:
  target: <andere-seite>
  mode: selective
  fields: [Goals, Learnings]
  direction: bidirectional

  3. Sync wird über die verbundene API-Key-Connection ausgeführt (gts sync), nicht über git-Remote.

6. Naming-Regeln

  • Instance + Slug + Path-Segmente: lowercase-kebab ([a-z0-9][a-z0-9-]*).
  • Keine Umlaute in Pfaden oder IDs (Umlaute OK im title).
  • IDs sind global eindeutig pro Instanz. Zwei Brains mit derselben ID auf einer Instanz → Lint-Fehler.

7. Sensible Inhalte

  • **soul/private/**** wird nie gesynct. Physische Sicherheit = OS-Disk-Encryption (FileVault/LUKS).
  • Opt-in-Encryption via encrypted: true — aktuell Placeholder für zukünftige git-crypt-Integration (nicht im MVP, siehe DECISIONS.md D17).
  • Keine Passwörter, API-Keys, Tokens im Klartext in Brains. Dafür gibt es Secret-Stores.