# Przepływ danych

## Kierunek: panel / Gemini → notatka → Cursor

1. **Wejście tekstu** — komenda `ZAPISZ`, odpowiedź Gemini lub treść z pola „body”.
2. **Zapis** — pliki `.md` w katalogu notatek przez `writeNoteVersioned` (wersjonowanie `_v2`, `_v3` zamiast nadpisywania). Domyślnie [`gema0/storage/notes/`](../gema0/); możliwy **folder w workspace Cursora** przez zmienną `GEMA0_NOTES_DIR` (patrz [`gema0/README.md`](../gema0/README.md)).
3. **Kolejka** — zadanie PUSH nie może się ścigać z innym RPA na tej samej maszynie; [`TaskQueue`](../gema0/backend/services/queue.js) realizuje to sekwencyjnie.
4. **Worker Python** — [`push_to_cursor.py`](../gema0/rpa_workers/push_to_cursor.py): aktywacja okna, `Ctrl+L`, schowek, opcjonalnie sekwencja `@nazwa.md`, `Ctrl+Enter`.
5. **Cursor** — interpretacja `@` zależy od workspace; plik musi być osiągalny w kontekście projektu otwartego w Cursorze.

## Kierunek zwrotny: Cursor → panel (wizja docelowa)

**Stan obecny:** brak niezawodnego odczytu odpowiedzi z UI Cursor przez API.

**Opcje do rozstrzygnięcia w tej wizji:**

| Metoda | Zalety | Wady |
|--------|--------|------|
| Użytkownik kopiuje odpowiedź → schowek → [`clipboard_watcher.py`](../gema0/rpa_workers/clipboard_watcher.py) | Worker + [`clipboardBridge.js`](../gema0/backend/services/clipboardBridge.js) (start przy starcie panelu, **opcjonalnie** w `config.json`) | Wymaga `clipboard_watcher.enabled: true`; domyślnie wyłączone (świadomy opt-in). |
| Zapis zmian w repo (git) jako „odpowiedź” | Obiektywne | To nie jest „tekst czatu” |
| Przyszły parser ekranu / OCR | Automat | Kruchy, kosztowny |

### Kontrakt handoff (wdrożenie)

Zamiast zdarzenia „agent skończył” stosujemy **raport w pliku** w katalogu notatek workspace (np. `20_agent_report.md`). Skrypt [`orchestrate-handoff`](../gema0/tools/orchestrate-handoff.mjs) (`npm run orchestrate:handoff`) wczytuje raport + `10_step_current.md` + skrót `git`, **domyślnie waliduje kontrakt** (nagłówki sekcji, `STEP-…`, zgodność ID — patrz [`CONTRACT.md`](../gema0/workspace-notes.example/CONTRACT.md)), wywołuje Gemini, zapisuje `30_gemini_brief.md` i może dopisać `cmd.md` — szablon: [`workspace-notes.example`](../gema0/workspace-notes.example/). Ręczna kontrola bez Gemini: `npm run validate:handoff`.

## Do uzupełnienia

- [ ] Docelowy format „jednej sesji” (session_id, powiązanie Gemini ↔ Cursor).
- [ ] Czy notatki wyjściowe z Cursor mają mieć szablon nazwy (np. `cursor_reply_<ts>.md`).

Powiązane: [03_panel_ui_historia.md](03_panel_ui_historia.md), [05_mapowanie_na_gema0.md](05_mapowanie_na_gema0.md).