docs: define host workspace and MCP access

README.md

@@ -23,6 +23,23 @@ Neovim, Termdebug, nvim-dap oraz MCP tmuxa i Neovima. Kod karty, wyniki i
 artefakty są bind-mountem na hoście. Kontenery nie dostają kluczy SSH, tokenów,
 socketu Podmana/Dockera ani całego `/dev`.
 
+## Pierwsza instalacja
+
+Pierwszy klon launchera również należy do workspace. Nie uruchamiamy
+`stemctl` z przypadkowego katalogu domowego ani z kontenera:
+
+```bash
+mkdir -p ~/dev/workspace/stem/tools
+git clone http://77.90.8.171:3001/edu-tools/stem-launcher.git \
+  ~/dev/workspace/stem/tools/stem-launcher
+cd ~/dev/workspace/stem/tools/stem-launcher
+./stemctl workspace sync
+```
+
+Od tego momentu wszystkie komendy `stemctl`, karty i repozytoria odpowiedzi
+pozostają pod `~/dev/workspace/stem`. Kontener dostaje wybraną kartę jako
+`/workspace`, ale nie jest miejscem przechowywania źródeł.
+
 ## Szybki start
 
 ```bash
@@ -69,6 +86,10 @@ Domyślny układ:
 └── tokens/tokens.json
 ```
 
+Pierwszym repozytorium w `tools/` jest `stem-launcher`; to ono pobiera
+workspace-info, źródła kart oraz repo środowiska. Pozostałe repozytoria są
+zarządzane przez `stemctl`, a nie klonowane wewnątrz kontenera.
+
 Jeżeli istnieje tylko starszy `~/dev/workspace/rv`, launcher wykrywa go bez
 niszczenia danych. Jawna migracja:
 
@@ -102,6 +123,30 @@ się w wybranym kontenerze:
 Oddzielne wpisy klienta MCP mogą wskazywać inne nazwy instancji, więc jeden
 Codex obsługuje kilka kontenerów bez globalnego „ostatniego socketu”.
 
+Klient MCP działający stale na hoście może także przełączać oba narzędzia
+atomowo przez wspólny wskaźnik `current`:
+
+```bash
+./stemctl mcp list
+./stemctl mcp select rp2350-pointers-final
+./stemctl mcp status
+./stemctl mcp select 3aca2c1c4c7a
+```
+
+Selektor przyjmuje nazwę instancji, nazwę kontenera albo co najmniej 12 znaków
+ID. Weryfikuje ID i label przez `podman inspect`, a także aktywnie sprawdza oba
+serwery. Dopiero wtedy atomowo przełącza:
+
+```text
+$XDG_RUNTIME_DIR/stem/mcp-selected/current/n.sock
+$XDG_RUNTIME_DIR/stem/mcp-selected/current/t.sock
+```
+
+Wskaźniki prowadzą do katalogu zawierającego aktualny `container12`, więc
+odtworzony kontener nie może przejąć socketów poprzednika. Neovim i tmux
+otwierają nowe połączenie przy każdym wywołaniu narzędzia MCP, dlatego zmiana
+działa bez restartowania klienta.
+
 ## Komputer zdalny
 
 Na komputer ucznia wchodzimy wyłącznie SSH z parą kluczy. Launcher, Git,
@@ -134,6 +179,7 @@ Nowe materiały powinny używać nazw kanonicznych.
 
 - [plan architektury](doc/architecture-plan.md)
 - [kontenery i interfejs](doc/containers.md)
+- [wytyczne dokumentowania debugowania](doc/debug-documentation-guidelines.md)
 - [migracja nazw i workspace](doc/migration-stem-launcher.md)
 - [serie i karty](doc/series.md)
 - [tokeny Gitea](doc/tokens.md)