# Instalacja GEMA-0 dla operatora (Windows + Cursor)

Dokument dla **Ciebie**: od zera do pierwszej działającej pętli (panel → notatki `.gema0` → orchestracja → PUSH). Zakładamy repozytorium **Gema0** sklonowane na dysk (np. `C:\tools\Gema0`).

---

## 1. Wymagania

| Składnik | Minimum |
|----------|---------|
| System | Windows 10 / 11 (RPA steruje oknami Cursora) |
| Node.js | 18+ (`node -v`) |
| Python | 3.11+ na PATH (`python --version`) — pakiety wg `README.md` / `tools/install.ps1` |
| Cursor | Zainstalowany; okno z **tytułem** możliwym do mapowania w panelu |

---

## 2. Zależności Node

W folderze **głównym repozytorium Gema0** (tam gdzie jest `package.json`):

```powershell
cd C:\ścieżka\do\Gema0
npm install
```

---

## 3. Plik `.env` (sekrety i ścieżki)

1. Skopiuj **`.env.example`** → **`.env`** w tym samym folderze co `package.json`. (Opcjonalnie: przejrzyj też **`.env.complete.example`** — pełniejszy komentowany katalog zmiennych do ręcznego przenoszenia linii.)
2. Uzupełnij przynajmniej:
   - **`GEMINI_API_KEY`** — jeśli chcesz `ASK GEMINI` i `npm run orchestrate:handoff`.
   - **`GEMA0_NOTES_DIR`** — **absolutna** ścieżka do folderu **`.gema0`** *wewnątrz projektu*, który masz otwarty w Cursorze (np. `C:\Projekty\MojaAplikacja\.gema0`).  
     Bez tego `ZAPISZ` i `@…` w czacie trafią w domyślny `storage/notes` panelu — Cursor **nie** zobaczy tych plików jako części projektu.
3. Opcjonalnie **`GEMA0_GIT_ROOT`** — root repo z `.git` (zwykle folder **nad** `.gema0`).
4. Opcjonalnie **`PYTHON_EXE`** — jeśli `python` nie jest na PATH.

**Szybka ścieżka:** uruchom panel, wejdź w **[Instalacja](/install)** — krok **Projekt + szablon** ustawia ścieżki przez **scalenie** `.env`. Podgląd `.env.example` służy tylko do **dopisania** brakujących linii (nie zastępuj całego pliku, jeśli masz już klucze).

---

## 4. Pierwsze uruchomienie panelu

```powershell
cd C:\ścieżka\do\Gema0
npm start
```

W przeglądarce:

- **Panel główny:** [http://127.0.0.1:7878](http://127.0.0.1:7878) (port z `PORT` lub `config.json`). U góry strony: zwijany blok **„Start i instalacja”** (skrót + link do kreatora `/install`).
- **Kreator instalacji:** [http://127.0.0.1:7878/install](http://127.0.0.1:7878/install)

Na górze panelu kliknij **Healthcheck** — sprawdź status **Python**, **Cursor**, **Gemini**.

Gdy w **`gema0/.env`** włączysz **`GEMA0_PANEL_TOKEN`** (≥16 znaków — zalecane przy tunelu / WAN), po pierwszym `401` wkleisz ten sam sekret w pasku przeglądarki. Skrypty **`npm run watch:cmd`** i **`npm run supervisor:loop`** wczytują token z tego samego `.env` i do `POST /api/chat` dokładają nagłówek `Authorization: Bearer …`, żeby automaty działały przy włączonej ochronie API.

---

## 5. Szablon `.gema0` w projekcie

**Opcja A — z panelu (zalecane)**  
W panelu w sekcji **Nowy projekt**: wklej pełną ścieżkę do folderu projektu → wybierz **szablon** (notatki `workspace-notes`, lekcja HTML `toy`, albo tylko ścieżki) → **Zastosuj szablon + ścieżki** (serwer **scala** `GEMA0_NOTES_DIR` / `GEMA0_GIT_ROOT` w `gema0/.env` — **nie kasuje** `GEMINI_API_KEY`) → **zrestartuj** `npm start`.  
Pełniejszy kreator z opisami: **[Instalacja](/install)** (`/install`).

**Opcja B — ręcznie**  
Skopiuj cały katalog **`workspace-notes.example`** z repozytorium Gema0 do `TwojProjekt\.gema0` i ustaw `GEMA0_NOTES_DIR` jak w pkt 3.

W projekcie dopisz do `.gitignore` np.:

```gitignore
.gema0/.gema0_state/
```

---

## 6. Mapowanie okien (RPA)

W panelu: **Mapowanie okien** — dla `CURSOR_1` wpisz unikalny fragment **tytułu okna** Cursora (pasek Windows), w którym masz otwarty **ten** projekt. Zapisz mapowanie.  
**Dry Push** z panelu — test bez wysyłania klawiatury; potem zwykły **PUSH**.

---

## 7. Pierwsza pętla (skrót)

Szczegółowy scenariusz: **`00_IDEALNY_START.md`** w skopiowanym `.gema0`.

Skrót poleceń (z katalogu Gema0, z ustawionym `GEMA0_NOTES_DIR`):

```powershell
npm run validate:handoff
npm run orchestrate:handoff
```

Potem w panelu wyślij komendę `PUSH TO CURSOR_1 @cmd.md …` albo uruchom w drugim oknie terminala:

```powershell
npm run watch:cmd
```

---

## 8. Problemy

| Objaw | Co sprawdzić |
|--------|----------------|
| `@cmd.md` w Cursorze nie znajduje pliku | Czy workspace = folder z `.gema0` lub wyżej tak, by ścieżka `@…` była widoczna; czy plik jest w `GEMA0_NOTES_DIR`. |
| Orchestrator: brak klucza | `GEMINI_API_KEY` w `gema0/.env`. |
| Orchestrator: walidacja | Sekcje `##` w `20_agent_report.md` — dokładne nagłówki z [CONTRACT.md](../workspace-notes.example/CONTRACT.md). |
| PUSH nie trafia w okno | `windows_map.json`, tytuł okna, **Healthcheck**. |
| Gemini 429 | `rate_limit_per_minute` w `backend/config/config.json`. |
| Start supervisora / watch z API panelu: **403** | `GEMA0_ALLOW_PANEL_NPM_SCRIPTS=false` w `.env` — wyłączone uruchamianie `npm run …` z poziomu HTTP (zostaw `true` albo usuń zmienną, domyślnie włączone). |
| PUSH: HTTP 200 ale Cursor nic nie dostał | `push` w odpowiedzi = tylko **kolejka**; faktyczny wynik RPA jest w logu WebSocket (`rpa_worker_done`, ewentualnie `timeout` / `max_buffer`). |

---

## 9. Dokumentacja w repo

- Główny **README** w katalogu Gema0 — komendy panelu, `watch:cmd`, orchestracja.
- **`_docs/gema0_vision_v2.md`** — wizja autonomii i supervisora (architektura).

Po pierwszej udanej pętli możesz skrócić własny rytuał do: *agent kończy → `validate` → `orchestrate` → (watch lub PUSH)*.