docs: move API contract to application level

README.md

@@ -29,6 +29,7 @@ card-layouts/
 ├── tools/render_card.py
 ├── docs/
 │   ├── CARD.md
+│   ├── api.md
 │   └── SERIES.md
 └── examples/
     ├── card/
@@ -113,8 +114,9 @@ z `doc/assets`). Generator wstawia je do TeX/PDF i HTML, zachowuje podpis,
 tekst alternatywny i stabilną etykietę oraz przygotowuje link do pełnego
 obrazu w wersji ekranowej.
 
-Szczegóły modelu karty opisuje [docs/CARD.md](docs/CARD.md), a manifestu
+Szczegóły modelu karty opisuje [docs/CARD.md](docs/CARD.md), manifestu
-serii [docs/SERIES.md](docs/SERIES.md).
+serii [docs/SERIES.md](docs/SERIES.md), a wspólnego serwera aplikacji
+[docs/api.md](docs/api.md).
 
 ## Słowniki podstaw programowych
 

docs/api.md

@@ -0,0 +1,122 @@
+# API aplikacji kart
+
+Wspólna aplikacja Fastify wystawia stan dowolnej karty, nawigację UML,
+checkpointy oraz Neovim wybrany przez MCP. Domyślny adres lokalnej instancji
+to `http://127.0.0.1:8080`. Kontrakt nie zależy od serii ani konkretnej karty;
+dane i recepty pochodzą z jej `card_source.json`.
+
+API nie zarządza cyklem życia kontenera i nie podpina pane tmuxa. Za operacje
+`start/reset/refresh/attach/detach` odpowiada `stemctl session`. API korzysta z
+kontenera wskazanego przez bieżący wybór MCP i steruje zawartością jego sesji:
+Neovimem, Termdebugiem/GDB i checkpointami maszyny.
+
+## Tożsamość i stan
+
+| Metoda i endpoint | Znaczenie |
+| --- | --- |
+| `GET /api/identity` | `id`, UUID, wersja i SHA-256 źródłowego JSON-a karty. |
+| `GET /api/card-revision` | Rewizja plików używana do automatycznego odświeżania strony. |
+| `GET /api/state` | Złożony stan nawigacji, widoku, checkpointu i dostępności Neovima. |
+| `GET /api/control/state` | Lekki stan synchronizacji strony z klientem sterującym. |
+
+Serwer jest przeznaczony do pracy lokalnej. Nie ma warstwy uwierzytelnienia,
+dlatego nie należy wystawiać go bezpośrednio poza zaufany host.
+
+## Nawigacja UML
+
+Hierarchia nawigacji jest stała:
+
+```text
+task → block → phase → step → snapshot
+```
+
+| Metoda i endpoint | Znaczenie |
+| --- | --- |
+| `GET /api/keyboard` | Skróty i obsługiwane poziomy nawigacji. |
+| `GET /api/navigation/catalog` | Wszystkie prawidłowe pozycje i ich indeksy. |
+| `GET /api/navigation/current` | Bieżąca pozycja oraz status checkpointu. |
+| `PUT /api/navigation/current` | Ustawia dokładną pozycję i poziom fokusu. |
+| `POST /api/navigation/move` | Przesuwa kursor o `delta` na wybranym poziomie. |
+
+Przykład ustawienia kroku — identyfikatory są danymi konkretnej karty:
+
+```json
+{
+  "task_id": "<task-id>",
+  "block_id": "<block-id>",
+  "phase_id": "<phase-id>",
+  "step_id": "<step-id>",
+  "snapshot_ref": "<snapshot-ref>",
+  "focus_level": "step",
+  "sync_requested": true,
+  "actor": "stemctl"
+}
+```
+
+## Checkpointy
+
+| Metoda i endpoint | Znaczenie |
+| --- | --- |
+| `GET /api/checkpoint/status` | Aktywna operacja, ostatni wynik i generacja. |
+| `POST /api/checkpoint/activate` | Odtwarza stan GDB przypisany do snapshotu. |
+
+Wywołanie orkiestratora przypina zarówno kontener, jak i rewizję karty:
+
+```json
+{
+  "snapshot_ref": "<snapshot-ref>",
+  "generation": 1784280000000,
+  "expected_binding": {
+    "container_id": "<container-id>",
+    "instance": "<instance-id>",
+    "profile": "hazard3-sim",
+    "target": "hazard3-baremetal"
+  },
+  "expected_identity": {
+    "id": "<card-id>",
+    "uuid": "<card-uuid>",
+    "version": "<card-version>",
+    "source_sha256": "<sha256>"
+  }
+}
+```
+
+Replay kończy się powodzeniem wyłącznie ze statusem `ready`. Zmiana kontenera,
+socketu MCP albo źródłowego JSON-a podczas operacji powoduje odrzucenie
+wyniku; pozycja strony i `SYNC ON` nie są wtedy publikowane.
+
+## Widok i Neovim
+
+| Metoda i endpoint | Znaczenie |
+| --- | --- |
+| `GET/PUT /api/viewer/state` | Skala, scroll oraz `visible/sync/control/expanded/fit`. |
+| `GET /api/nvim/state` | Bieżący bufor, okno, kursor i tryb Neovima. |
+| `PUT /api/nvim/cursor` | Ustawia `row`, `column` i opcjonalnie `window`. |
+| `POST /api/nvim/input` | Przekazuje do 256 znaków przez `nvim_input`. |
+| `WS /api/nvim-ui` | Strumień zewnętrznego UI Neovima do panelu WWW. |
+
+Wyłączenie `viewer.nvim.sync` automatycznie wyłącza również
+`viewer.nvim.control`. Samo ponowne włączenie synchronizacji nie uzbraja
+sterowania klawiaturą bez jawnego `control: true`.
+
+## Postęp zajęć i raport
+
+| Metoda i endpoint | Znaczenie |
+| --- | --- |
+| `GET /api/progress` | Katalog, statusy i podsumowanie wykonania. |
+| `PUT /api/progress/:itemId` | Ustawia `pending` albo `approved`, notatkę i aktora. |
+| `GET /api/report/teams.md` | Generuje bieżący raport Markdown do Teams. |
+
+## Planowane strategie i adnotacje
+
+Strategie debugowania będą przypinane do pełnego klucza
+`task/block/phase/step/snapshot`. Adnotacja pozostanie osobnym rekordem:
+
+```text
+strategy: id, label, commands, expected_observations
+annotation: id, strategy_id, target, geometry, style, text, visible
+```
+
+Planowane operacje `show/hide/toggle` zmienią wyłącznie `visible`.
+`add/remove` będą osobnymi, audytowalnymi operacjami. Dzięki temu ukrycie
+warstwy objaśnień nie usuwa przygotowanych oznaczeń.