docs: define container attach semantics

README.md

@@ -71,8 +71,10 @@ Pełną sesję lekcji można wybrać i kontrolować numerami z CLI:
 
 `current:0` jest domyślnym pane: pane `0` okna tmuxa, w którym działa
 wywołujący Codex. `session stage`/`session checkpoint` ustawia dowolny etap UML
-online w Termdebug albo tylko na stronie z `--offline`. Szczegóły i wszystkie
+online w Termdebug albo tylko na stronie z `--offline`. Semantykę poleceń,
-selektory opisuje [dokumentacja sesji](doc/session.md).
+w tym podpinanie kontenera przez `attach/detach`, opisuje
+[referencja stemctl](doc/stemctl.md), a wybór checkpointów
+[dokumentacja sesji](doc/session.md).
 
 Wymuszenie samego przygotowania środowiska:
 

doc/session.md

@@ -38,7 +38,7 @@ Tabele zawierają kolumnę `status`:
 # Zachowaj kontener i ponownie podepnij istniejący debugger.
 ./stemctl session refresh hazard3-sim --series inf --card 7 --task 4
 
-# Podepnij/odepnij tylko klienta w zewnętrznym tmuxie. Serwer debuggera żyje dalej.
+# Podepnij/odepnij kontener od pane zewnętrznego tmuxa. Procesy wewnątrz żyją dalej.
 ./stemctl session attach hazard3-sim --series inf --card 7 --task 4
 ./stemctl session detach hazard3-sim --series inf --card 7 --task 4
 ```
@@ -51,8 +51,9 @@ PID-em pane w opcjach tmuxa; jawne `%ID` podane z innego terminala również
 zostanie odrzucone. Świadome obejście tej drugiej ochrony wymaga
 `--force-pane`; nie da się nim zastąpić pane wykonującego bieżącą komendę.
 
-`detach` odłącza wyłącznie zewnętrznego klienta tmuxa. Nie zatrzymuje
+`attach` i `detach` operują na połączeniu pane z kontenerem. Neovim i
-kontenera, symulatora, GDB, Neovima ani wewnętrznej sesji tmuxa.
+Termdebug są zawartością jego sesji. `detach` nie zatrzymuje kontenera,
+symulatora, GDB, Neovima ani wewnętrznej sesji tmuxa.
 
 ## Wybór stanu UML
 

doc/stemctl.md

@@ -0,0 +1,88 @@
+# `stemctl` — sterowanie sesją zajęć
+
+`stemctl session` łączy wybór materiału, kontenera, stanu UML i zewnętrznego
+pane tmuxa. Szczegółowy opis wyboru checkpointów znajduje się w
+[`session.md`](session.md); ten dokument definiuje znaczenie poleceń cyklu
+życia.
+
+## Model połączenia
+
+```text
+pane tmuxa na hoście
+        │
+        │ attach / detach
+        ▼
+wybrany kontener
+        └── wewnętrzny tmux → Neovim + Termdebug/GDB + symulator lub RP2350
+```
+
+Obiektem operacji `attach` i `detach` jest **połączenie pane z kontenerem**.
+Neovim i Termdebug są zawartością sesji kontenera, a nie osobnym obiektem
+podpinanym przez launcher.
+
+- `attach` podpina wybrany, działający kontener do wskazanego pane i pokazuje
+  jego istniejącą sesję Neovim/Termdebug;
+- `detach` zastępuje widok kontenera zwykłą powłoką hosta w tym pane;
+- `detach` nie zatrzymuje kontenera, wewnętrznego tmuxa, Neovima, GDB,
+  symulatora ani połączenia z RP2350;
+- ponowne `attach` wraca do tej samej działającej sesji;
+- `stop` i `rm`, a nie `detach`, zmieniają cykl życia kontenera.
+
+## Polecenia sesji
+
+| Polecenie | Znaczenie |
+| --- | --- |
+| `session choices` | Wyświetla numerowane serie, karty, Taski i etapy UML. |
+| `session status` | Sprawdza kontener, MCP, tożsamość karty i bieżący etap. |
+| `session start` | Uruchamia kontener i jego środowisko pracy. |
+| `session reset` | Usuwa i odtwarza kontener, następnie opcjonalnie odtwarza checkpoint. |
+| `session refresh` | Zachowuje kontener i odnawia jego podpięcie oraz wybór MCP. |
+| `session attach` | Podpina istniejący kontener do pane tmuxa na hoście. |
+| `session detach` | Odpina kontener od pane bez zatrzymywania czegokolwiek wewnątrz. |
+| `session stage` | Ustawia wybrany etap UML; alias: `session checkpoint`. |
+
+## Wybór celu
+
+Serię, kartę, Task i elementy UML można wskazywać stabilnym ID albo numerem
+pokazanym przez `choices`:
+
+```bash
+stemctl session choices --series inf --card 7 --task 4
+
+stemctl session reset hazard3-sim \
+  --series inf --card 7 --task 4 \
+  --step 12 --pane current:0
+```
+
+Najważniejsze selektory:
+
+- środowisko: `profile`, `--target`, `--instance`;
+- materiał: `--series`, `--card`, `--task`;
+- UML: `--stage`, `--block`, `--phase`, `--step`, `--snapshot`, `--first`;
+- widok: `--pane`, `--focus`, `--offline`, `--control`;
+- wykonanie: `--card-url`, `--timeout`, `--force-pane`, `--dry-run`.
+
+`--pane current:0` oznacza pane `0` tego okna tmuxa, w którym uruchomiono
+Codexa. Można także podać `%ID` albo `sesja:okno.pane`. Launcher chroni pane
+wykonujące bieżącą komendę i pane oznaczone jako należące do innej sesji
+Codexa.
+
+## Przykłady attach i detach
+
+```bash
+# Podepnij działający kontener Task04 do pane 0 bieżącego okna.
+stemctl session attach hazard3-sim \
+  --series inf --card 7 --task 4 --pane current:0
+
+# Wróć w pane 0 do powłoki hosta. Kontener i debugowanie nadal działają.
+stemctl session detach hazard3-sim \
+  --series inf --card 7 --task 4 --pane current:0
+```
+
+## Status materiału
+
+`session choices` pokazuje jedną z trzech wartości:
+
+- `opracowane` — kompletny materiał wraz z receptą checkpointu;
+- `robocze` — źródło lub metadane istnieją, ale nie są kompletne;
+- `brak` — materiał nie jest jeszcze dostępny w workspace.

rvctl.py

@@ -5840,11 +5840,11 @@ def build_parser() -> argparse.ArgumentParser:
 
     session_actions = {
         "status": "Show the resolved container, MCP and current browser/UML state.",
-        "start": "Start the debugger UI in a host tmux pane.",
+        "start": "Start the selected container and optionally connect it to a host tmux pane.",
-        "reset": "Remove and recreate the container, then start its debugger UI.",
+        "reset": "Remove and recreate the selected container, then optionally connect it.",
-        "refresh": "Reuse the container and reattach or recreate its debugger UI.",
+        "refresh": "Reuse the selected container and refresh its host-pane connection.",
-        "attach": "Attach an existing container debugger UI to a host tmux pane.",
+        "attach": "Attach the running selected container to a host tmux pane.",
-        "detach": "Detach the host pane without stopping the container debugger.",
+        "detach": "Detach the selected container from the host pane without stopping it.",
         "stage": "Select and replay one UML stage (alias: checkpoint).",
     }
     for session_action, help_text in session_actions.items():