# Audyt zgodności (API · panel · env · npm)

**Data audytu:** stan repozytorium względem gałęzi `main` (generator: przegląd `backend/routes/*.js`, `frontend/js/*.js`, `tools/`, `lib/`, `package.json`, `.env.example`, `.env.complete.example`, `README.md`).

**Źródło prawdy dla zachowania:** kod (`backend/`, `frontend/js/`, `tools/`, `lib/`). README i pliki `.env*` mają charakter **dokumentacyjny** — mogą świadomie skracać listę (np. „API wybrane”).

---

## 1. REST API — backend vs frontend

| Metoda + ścieżka | Router | `app.js` (panel główny) | `install.js` | `_smoke_panel_api.mjs` |
|------------------|--------|--------------------------|--------------|------------------------|
| `POST /api/chat` | chat | tak | — | nie |
| `POST /api/gemini-stream` | chat | tak | — | nie |
| `GET /api/notes` | chat | tak | — | nie |
| `GET /api/notes/:name` | chat | tak | — | nie |
| `GET /api/workflow` | workflow | tak | — | nie |
| `GET /api/supervisor_registry` | workflow | tak | — | nie |
| `GET /api/workflow/commands` | workflow | tak | — | nie |
| `GET /api/health` | server.js | tak | tak | tak (install) |
| `GET /api/settings` | settings | tak | — | tak |
| `PUT /api/settings/env` | settings | tak | — | nie |
| `PUT /api/settings/config` | settings | tak | — | nie |
| `GET /api/windows_map` | sessions | tak | — | tak |
| `PUT /api/windows_map` | sessions | tak | — | nie |
| `GET /api/queue` | sessions | tak | — | nie |
| `POST /api/queue/pause|resume|clear` | sessions | tak | — | nie |
| `GET /api/profiles` | sessions | tak | — | tak |
| `GET /api/auto_push` | autoPush | tak | — | nie |
| `GET/PUT /api/auto_push/file` | autoPush | tak | — | GET tak |
| `POST /api/bootstrap_gema0` | projectBootstrap | nie (świadomie: panel używa `setup-project`) | nie | POST tak (400) |
| `GET /api/install/*` (summary, status, env-example, preview) | install | preview tak | reszta tak | nie |
| `POST /api/install/setup-project`, `link-project-env` | install | tak | tak | nie |
| `GET /api/npm_scripts/status` | npmScripts | tak | — | nie |
| `POST /api/npm_scripts/start|stop` | npmScripts | tak | — | nie |

**Wnioski**

- **Brak „martwych” tras w panelu głównym** w sensie krytycznym: wszystko używane w UI ma endpoint.
- **`POST /api/bootstrap_gema0`** — nadal w backendzie i smoke (krótsza ścieżka); **główny panel** idzie przez **`/api/install/setup-project`** — zgodne z README (sekcja Panel PRO).
- **Smoke** celowo montuje **podzbiór** routerów — nie weryfikuje chat/workflow/install/npm; to **ograniczenie narzędzia**, nie błąd produktu.

---

## 2. WebSocket

- Backend: `WebSocketServer` na ścieżce **`/ws`**, te same reguły tokenu co `/api/*` (`verifyClient`).
- Frontend: `frontend/js/ws.js` — `ws(s)://{host}/ws` + `?token=` z `panelApi.js`.
- **Zgodność:** tak.

---

## 3. `npm run …` vs panel „npm scripts”

| `package.json` script | Panel (`npm_scripts` id) | Uwagi |
|------------------------|---------------------------|--------|
| `supervisor:loop` | `supervisor_loop` | tak |
| `watch:cmd` | `watch_cmd` | tak |
| `orchestrate:handoff` | `orchestrate_handoff` | tak |
| `validate:handoff` | — | tylko terminal / przyciski „Kopiuj” w UI |
| `bootstrap:supervisor` | — | CLI / dokumentacja |
| `healthcheck` | — | CLI + przycisk Healthcheck w menu |
| `setup:first-project` | — | PowerShell, Windows |

**Wniosek:** zgodne z założeniem — panel nie uruchamia wszystkich skryptów (bezpieczeństwo / długość).

---

## 4. Zmienne środowiska — próbka pokrycia

| Obszar | Czytane w kodzie (skrót) | `.env.example` | `.env.complete.example` |
|--------|--------------------------|----------------|-------------------------|
| Port panelu | `server.js`, `lib/panelListenPort.mjs` | PORT | PORT |
| Notatki / git | `config.js`, orchestrate, supervisor, watch | GEMA0_NOTES_DIR, GEMA0_GIT_ROOT | tak |
| watch-cmd | GEMA0_FILE_CMD, CMD_TARGET, CMD_PUSH, debounce, hash dedupe, PUSH dedupe | tak | tak |
| Orchestracja | WRITE_NEXT_10, MEGA_STEP, APPEND, NO_VALIDATE, SAVE_PROMPT_AUDIT, FILE_* | część w .env.example | tak |
| Supervisor retry | GEMA0_SUPERVISOR_PUSH_RETRY_* | tak | tak |
| Gemini backoff | GEMA0_GEMINI_* w `lib/gemini/generateWithBackoff.mjs` | komentarz w .env.example | tak |
| Panel token / npm z UI | GEMA0_PANEL_TOKEN, GEMA0_ALLOW_PANEL_NPM_SCRIPTS | tak | tak |

**Drobne luki dokumentacyjne (nie blokują runtime)**

- **`.env.example`** — komentarze obejmują większość zmiennych z README; pełniejszy katalog opcjonalnych kluczy jest w **`.env.complete.example`** — to zamierzone rozdzielenie „minimalne vs pełne”.
- **`GEMA0_ORCHESTRATE_WRITE_NEXT_10` / `MEGA_STEP`** — są w `.env.complete.example` i w nagłówku `orchestrate-handoff.mjs`; w skróconym `.env.example` warto je mieć w bloku orkiestracji (jeśli brakuje jednej linii — kosmetyka).

---

## 5. README vs kod

- Sekcja **Panel PRO** opisuje główne API instalacji + profile + kolejka — **zgodna** z faktycznym UI.
- Lista **„API (wybrane)”** jest **celowo niepełna** (brak m.in. `POST /api/chat`, `GET /api/workflow`, `GET /api/queue`) — to skrót dla operatora, nie specyfikacja OpenAPI.
- **Struktura katalogu** w README po ostatnich poprawkach: `backend/utils`, `backend/config`, `lib/gemini`, `lib/panelListenPort.mjs` — **spójne** z repo.

---

## 6. Rekomendacje (priorytet)

1. **Utrzymanie:** przy nowych endpointach dodać wywołanie w panelu **albo** uzasadnić w `_docs/` (np. tylko CLI).
2. **Smoke (opcjonalnie):** rozszerzenie o `POST /api/chat` z `DRY PUSH` lub mock — niski priorytet (wymaga kolejki/workerów).
3. **Jedna linia w README przy „API (wybrane)”:** „Pełna lista tras: pliki `backend/routes/*.js` + `GET /api/health` w `server.js`” — redukcja wrażenia „niespójności”.

---

## 7. Szybka weryfikacja po zmianach

```bash
git checkout main && git pull origin main
npm test
node tools/_smoke_panel_api.mjs
```

Jeśli wyniki OK, **spójność runtime** między gałęziami jest zwykle zagwarantowana przez samo **`main`** — lokalne stare `cursor/*` bez `pull` mogą wyglądać jak „rozjechane pliki” (patrz [`GIT_I_GALEZIE.md`](GIT_I_GALEZIE.md)).