docs: document pinned workspace sources

README.md

@@ -90,6 +90,29 @@ 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.
 
+Karta jest montowana jako całe `/workspace`, łącznie z przypiętymi źródłami
+symulatora i trwałymi artefaktami:
+
+```text
+~/dev/workspace/stem/series/<seria>/<karta>/
+├── src/
+├── vendor/Hazard3/
+├── vendor/lab-runtime/
+└── .stem/instances/.../build/
+```
+
+Przygotowanie i kontrola bez uruchamiania kontenera:
+
+```bash
+./stemctl env sources inf pointers
+./stemctl env sources inf pointers --check
+```
+
+Każda zwykła akcja `build/test/run/debug` wykonuje przygotowanie automatycznie.
+Launcher nie klonuje źródeł w kontenerze, nie tworzy symlinków do `/opt` i nie
+nadpisuje zmodyfikowanego katalogu `vendor/`. Przypięcie pochodzi z
+`sources.lock.json` repo środowiska.
+
 Jeżeli istnieje tylko starszy `~/dev/workspace/rv`, launcher wykrywa go bez
 niszczenia danych. Jawna migracja:
 

doc/containers.md

@@ -218,6 +218,15 @@ 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.
 
+Dla Hazard3 po przygotowaniu przez `stemctl env sources SERIES CARD` ten sam
+bind-mount zawiera również rzeczywiste (niebędące symlinkami) katalogi
+`vendor/Hazard3` i `vendor/lab-runtime`. Program, testbench oraz GDB korzystają
+wyłącznie z nich. Build testbencha i ELF trafia do
+`.stem/instances/<instance>/build`, a DWARF zachowuje ścieżki
+`/workspace/vendor/Hazard3/...` i `/workspace/src/...`. `/opt` pozostaje
+miejscem toolchainów i programów obrazu; nie jest źródłem kodu wyświetlanego w
+Neovimie ani GDB.
+
 ## Instancje i sockety MCP
 
 Stabilna nazwa logiczna: