docs: define host workspace and MCP access

doc/containers.md

@@ -195,6 +195,29 @@ re-enumeracji. Nie przekazuje całego `/dev`. Build i test offline nie wymagają
 artefaktu. Bez niego odmawia wykonania, chyba że użytkownik jawnie zaakceptuje
 istniejący firmware. Zapobiega to testowaniu starego programu.
 
+## Źródła projektu
+
+Źródła kart i projektów pobiera wyłącznie `stemctl` na hoście, zawsze pod
+`~/dev/workspace` danego konta Unix. Kanoniczny workspace STEM ma postać
+`~/dev/workspace/stem`; nie używamy do pracy katalogów kontenera ani
+przypadkowych klonów poza `~/dev/workspace`. Pierwszy klon launchera trafia do
+`~/dev/workspace/stem/tools/stem-launcher` i od niego zaczyna się cały
+bootstrap workspace. Typowy przepływ to:
+
+```bash
+stemctl workspace sync
+stemctl series cards fetch inf pointers
+stemctl debug rp2350 inf pointers 4
+```
+
+Katalog karty pozostaje na hoście, na przykład
+`~/dev/workspace/stem/series/inf/pointers/`, i jest przekazywany kontenerowi
+jako bind-mount `/workspace`. Nie klonujemy repozytoriów źródłowych wewnątrz
+kontenera: kontenery są odtwarzalne i mogą zostać usunięte, natomiast host
+zachowuje Git, zmiany ucznia, odpowiedzi i historię pracy. W obrazie lub
+osobnym cache volume mogą znajdować się wyłącznie narzędzia, zależności i
+odtwarzalne cache budowania.
+
 ## Instancje i sockety MCP
 
 Stabilna nazwa logiczna:
@@ -227,6 +250,33 @@ Publiczne wejścia launchera to `stemctl mcp tmux INSTANCE` oraz
 zweryfikowanego kontenera. Neovim MCP publikuje również stan i komendy
 Termdebug/nvim-dap.
 
+Dla jednego stale działającego klienta hostowego dostępny jest również jawny,
+atomowy przełącznik obu socketów:
+
+```bash
+stemctl mcp list
+stemctl mcp select INSTANCE_OR_CONTAINER_ID
+stemctl mcp status
+```
+
+`mcp select` sprawdza registry, pełny ID i label kontenera, aktywnie testuje
+serwery Neovima i tmuxa, a następnie jednym `rename(2)` przełącza symlink
+`$XDG_RUNTIME_DIR/stem/mcp-selected/current`. Jeśli choć jeden serwer nie
+odpowiada, poprzedni wybór pozostaje bez zmian.
+
+Katalog socketów jest tworzony przez launcher na hoście i bind-mountowany do
+kontenera pod identyczną ścieżką. Dopiero `nvim` i `tmux` działające w
+kontenerze tworzą odpowiednio `n.sock` i `t.sock`; hostowy Codex łączy się z
+tym samym plikiem przez widok hosta. Sockety nie są przekazywane przez sieć ani
+nie dają kontenerowi dostępu do socketu Podmana.
+
+Połączenia MCP mają profil `observe`, `assist` albo `full`. `full` jest
+przeznaczony dla nauczyciela: może wykonywać dowolne działania dostępne w
+Neovimie, tmuxie i terminalu wybranego kontenera jako konto ucznia. Profile
+`observe` i `assist` muszą używać oddzielnych, ograniczonych providerów;
+nie wolno udawać ograniczenia przez samą zmienną środowiskową przy providerze
+udostępniającym ogólny Vimscript lub polecenia pane’a.
+
 MCP nie jest czwartym kontenerem. Bridge jest częścią `dev-ui-base`, a hostowy
 resolver jest częścią `stem-launcher`.