From aba52f2b3c1d168395de87d795c0fc02725fb998 Mon Sep 17 00:00:00 2001
From: Sandro <mail@sandrodach.de>
Date: Sat, 24 Oct 2026 16:26:41 +0200
Subject: [PATCH] add brain.md

---
 BRAIN.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 169 insertions(+)
 create mode 100644 BRAIN.md

diff --git a/BRAIN.md b/BRAIN.md
new file mode 100644
index 0000000..c22addc
--- /dev/null
+++ b/BRAIN.md
@@ -0,0 +1,169 @@
+# 🧠 BRAIN.md — MindSift Internal Dev Cheat Sheet
+> **Zweck:** Rein internes, ungeschöntes Nachschlagewerk für uns Entwickler. Keine Marketing-Texte, nur knallharte Fakten, Farbwerte, State-Machines, Namenskonventionen und Quick-Commands.
+
+---
+
+## 🎨 1. Design-Tokens & Gemini-Dark-Theme (Copy & Paste)
+
+### Farbpalette (Strict Hex Values)
+```css
+/* Backgrounds */
+--bg-app:        #0b0f19;  /* Tiefstes Obsidian / OLED Base */
+--bg-surface:    #131314;  /* Leicht erhobene Panels, Sidebar */
+--bg-card:       #1e1f20;  /* Swipe-Karten, Dialoge, Dropdowns */
+--bg-card-hover: #282a2c;  /* Hover-Zustände */
+
+/* Borders & Dividers */
+--border-subtle: rgba(255, 255, 255, 0.08); /* 1px Standard-Kante */
+--border-focus:  rgba(138, 180, 248, 0.40); /* Gemini Blue Glow */
+
+/* Akzente & Status */
+--accent-blue:   #8ab4f8;  /* Gemini Primärblau (Buttons, Links, Active) */
+--accent-purple: #c58af9;  /* Gemini Voice / Magic Glow */
+--swipe-keep:    #81c995;  /* Swipe Rechts (Behalten / ToDo / Success) */
+--swipe-discard: #f28b82;  /* Swipe Links (Verwerfen / Archive / Danger) */
+
+/* Typografie */
+--text-primary:  #e3e3e3;  /* Haupttext (hoher Kontrast, augenschonend) */
+--text-muted:    #9aa0a6;  /* Sekundärtexte, Metadaten, Placeholders */
+--text-subtle:   #5f6368;  /* Timestamps, Footer, Deaktiviert */
+```
+
+### UI-Regeln & Radien
+* **Buttons / Pills:** Ausnahmslos `rounded-full` (`border-radius: 9999px`).
+* **Karten (Triage Deck):** `rounded-3xl` (`24px`), Padding `p-6`, Border `1px solid var(--border-subtle)`.
+* **Input-Feld (Instant Capture):** `rounded-full`, Höhe `h-14` (56px) für mobile Daumenbedienung, Autofokus bei Mount.
+* **Gesten-Physik (Framer Motion):**
+  * Swipe-Schwellenwert: `dragConstraints={{ left: -150, right: 150 }}`
+  * Spring-Config: `{ type: "spring", stiffness: 350, damping: 25 }`
+  * Swipe-Winkel-Rotation: `rotate = x * 0.1`
+
+---
+
+## ⚙️ 2. State-Machine: Gedanken-Lifecycle
+
+```
+           [ INSTANT CAPTURE ]
+                    │
+                    ▼
+             status: 'inbox'
+                    │
+        ┌───────────┴───────────┐
+        │ (Swipe Left)          │ (Swipe Right)
+        ▼                       ▼
+ status: 'discarded'      status: 'kept'
+ (Soft Delete)                  │
+                        ┌───────┴───────┐
+                        │ (Convert)     │ (Direct Task)
+                        ▼               ▼
+           status: 'converted'     due_date != null
+           ├── target: 'task'
+           ├── target: 'document'
+           └── target: 'list_item'
+```
+
+### Gültige Status-Enums
+* `inbox` – Frisch eingekippt, wartet auf Triage.
+* `discarded` – Nach links gewischt (bleibt für 30 Tage im Papierkorb, dann Hard Delete).
+* `kept` – Nach rechts gewischt, bleibt als To-Do oder Gedanke archiviert.
+* `converted` – In vollwertiges Dokument, Aufgabe oder Listen-Item transformiert.
+
+---
+
+## 📡 3. WebSocket Realtime Protocol (Family Lists)
+
+Verbindungs-URL: `wss://<host>/api/v1/ws/spaces/:spaceId`
+
+### Nachrichten-Format (JSON)
+```typescript
+interface WSMessage<T = unknown> {
+  event: 'ITEM_CREATED' | 'ITEM_UPDATED' | 'ITEM_TOGGLED' | 'ITEM_DELETED' | 'USER_PRESENCE';
+  space_id: string;
+  list_id: string;
+  payload: T;
+  timestamp: string; // ISO 8601
+}
+```
+
+### Schnelle Event-Referenz
+* `ITEM_TOGGLED`: Wenn jemand die Hafermilch abhakt:
+  `{ "item_id": "itm_123", "is_completed": true, "completed_by": "usr_sandro" }`
+* `Optimistic UI`: Frontend schlägt das Item sofort lokal durch und rollt nur bei WebSocket-Fehler zurück.
+
+---
+
+## 🗂️ 4. Ordnerstruktur & Code-Konventionen
+
+```
+mindsift/
+├── cmd/
+│   └── server/             # Go Main Entrypoint (bindet embed.FS ein)
+├── internal/
+│   ├── api/                # HTTP Chi Handler, Routing & Middleware
+│   ├── domain/             # Entities, Interfaces & Domain Logic
+│   ├── storage/            # SQLite / Postgres Adapter (sqlc generiert)
+│   ├── ws/                 # WebSocket Hub & Raumverwaltung
+│   └── webhook/            # Smarthome Ingestion Logic
+├── migrations/             # Reine .sql Migrationsdateien
+├── frontend/
+│   ├── src/
+│   │   ├── components/     # UI Primitives (Button, Pill, Input, Modal)
+│   │   ├── features/
+│   │   │   ├── capture/    # Instant-Input & Voice Recording
+│   │   │   ├── triage/     # Framer Motion Swipe Deck
+│   │   │   ├── workspace/  # Tiptap Block Editor
+│   │   │   └── lists/      # Realtime Shopping / Todo Lists
+│   │   ├── lib/            # WS Client, API Client, Sound/Haptics
+│   │   └── index.css       # Tailwind v4 & Gemini CSS Variablen
+├── .gitea/workflows/       # Gitea Actions CI/CD
+├── Dockerfile              # Multi-Stage Build (< 35 MB)
+├── docker-compose.yml
+├── README.md               # Öffentliche Doku & Vision
+└── BRAIN.md                # Dieses Dokument (Dev Cheat Sheet)
+```
+
+### Namens- & ID-Konventionen
+* **Entity IDs:** Präfix-basierte Strings für Lesbarkeit beim Debuggen:
+  * `usr_` = User (`usr_9k2m1a`)
+  * `th_`  = Thought (`th_4x8z19`)
+  * `doc_` = Document (`doc_81na72`)
+  * `lst_` = List (`lst_33fa09`)
+  * `itm_` = List Item (`itm_77bb41`)
+* **Datenbank:** `snake_case` (z. B. `is_completed`, `due_date`)
+* **JSON API:** `camelCase` (z. B. `isCompleted`, `dueDate`)
+* **Timestamps:** Immer UTC ISO-8601 (`2026-10-24T14:20:00Z`)
+
+---
+
+## ⌨️ 5. Power-User Tastatur-Shortcuts (Desktop)
+
+| Taste | Kontext | Aktion |
+| :--- | :--- | :--- |
+| `C` oder `/` | Überall | Fokus sofort auf das Capture-Eingabefeld |
+| `H` oder `←` | Triage | Karte nach links wischen (Verwerfen) |
+| `L` oder `→` | Triage | Karte nach rechts wischen (Behalten) |
+| `T` | Triage | Sofort in Aufgabe mit Fälligkeitsdatum verwandeln |
+| `D` | Triage | In Workspace-Dokument umwandeln |
+| `Esc` | Modal/Capture | Abbrechen / Eingabe leeren |
+
+---
+
+## ⚡ 6. Cheat Sheet: Lokale Entwickler-Befehle
+
+```bash
+# 1. Frontend Dev Server (Hot Reload)
+cd frontend && npm run dev
+
+# 2. Go Backend starten (Hot Reload via air oder go run)
+go run ./cmd/server
+
+# 3. Datenbank-Migrationen lokal ausführen
+go run ./cmd/migrate -direction=up
+
+# 4. Lokalen Multi-Stage Docker-Build testen
+docker build -t mindsift:dev .
+docker run -p 8080:8080 -v $(pwd)/dev-data:/data -e JWT_SECRET="dev-secret-12345" mindsift:dev
+
+# 5. SQLite DB direkt per CLI inspizieren
+sqlite3 ./dev-data/mindsift.db ".tables" "SELECT * FROM thoughts LIMIT 5;"
+```