Document containers command namespace

README.md

@@ -47,7 +47,8 @@ Sciezki i domyslne ustawienia sa trzymane w `workspace.json`.
 3. Uruchamianie srodowiska programistycznego w kontenerach
 
    Dla wybranej karty `rvctl` uruchamia sesje tmux i kontener z przygotowanym
-   srodowiskiem developerskim.
+   srodowiskiem developerskim. Docelowy model namespace `containers` jest w
+   `doc/containers.md`.
 
 ## Model katalogow
 
@@ -107,6 +108,7 @@ repo, zanim narzedzie cos zmieni.
   i przelaczniki
 - `doc/tokens.md` - model tokenow, synchronizacja remote <-> store
 - `doc/series.md` - docelowy model komend dla serii i kart pracy
+- `doc/containers.md` - docelowy model komend dla srodowisk kontenerowych
 - `doc/tokens.schema.json` - schemat `tokens/tokens.json`
 - `doc/workspace.md` - krotki opis konfiguracji workspace
 

doc/containers.md

@@ -0,0 +1,156 @@
+# Containers
+
+Ten dokument opisuje docelowy model komend `rvctl` do uruchamiania
+srodowiska programistycznego w kontenerach.
+
+## Zasada
+
+Kontener jest srodowiskiem pracy dla wybranej karty, opcjonalnie zawezonym do
+konkretnego zadania. `rvctl` uruchamia je przez sesje `tmux`, tak aby terminal
+z kontenerem byl latwy do ponownego podlaczenia.
+
+Uzywamy namespace `containers`, a nie `container`, bo jest spojny z pluralnymi
+namespace'ami `tokens`, `cards` i `tasks`.
+
+## Szybki Flow
+
+Typowy przeplyw pracy:
+
+```bash
+./rvctl tokens compare
+./rvctl series cards show inf 03
+./rvctl series cards tasks list inf 03
+./rvctl containers show inf 03
+./rvctl containers start inf 03 --session rv-inf03 --attach
+./rvctl containers list
+./rvctl containers stop rv-inf03
+```
+
+## Model
+
+Docelowo komendy `containers` pracuja na trzech warstwach:
+
+- karta pracy, np. `inf 03`
+- opcjonalne zadanie, np. `--task task1`
+- instancja srodowiska, np. `--instance shell`
+
+Domyslne wartosci pochodza z `workspace.json`:
+
+```text
+defaults.series
+defaults.card
+defaults.task
+defaults.instance
+defaults.tmux_session
+defaults.tmux_window
+```
+
+## Komendy
+
+### `containers show [SERIES] [CARD]`
+
+Pokazuje plan uruchomienia srodowiska bez tworzenia sesji `tmux`.
+
+```bash
+./rvctl containers show inf 03
+./rvctl containers show inf/03 --task task1
+```
+
+Typowe pola:
+
+```text
+selector        inf/03
+task            task1
+card_path       ~/dev/workspace/rv/series/inf/03
+task_path       ~/dev/workspace/rv/series/inf/03/task1
+tools_root      ~/dev/workspace/rv/tools/rv32i-hazard3-env
+session         rv-inf03
+window          rv
+instance        shell
+```
+
+Ta komenda jest odpowiednikiem obecnego trybu:
+
+```bash
+./rvctl tmux-container inf 03 --dry-run
+```
+
+### `containers start [SERIES] [CARD]`
+
+Uruchamia sesje `tmux` i kontener dla wybranej karty.
+
+```bash
+./rvctl containers start inf 03
+./rvctl containers start inf/03 --session rv-inf03
+./rvctl containers start inf 03 --task task1 --instance shell --attach
+```
+
+Przelaczniki:
+
+- `--task TASK`
+  Wybiera zadanie w karcie. Bez tego `rvctl` uzywa domyslnego zadania z
+  `workspace.json` albo pracuje na katalogu karty.
+- `--session NAME`
+  Nadpisuje nazwe sesji `tmux`.
+- `--window NAME`
+  Nadpisuje nazwe okna `tmux`.
+- `--instance NAME`
+  Ustawia wariant srodowiska, np. `shell`.
+- `--attach`
+  Po uruchomieniu od razu podlacza terminal do sesji.
+
+### `containers list`
+
+Listuje aktywne srodowiska uruchomione przez `rvctl`.
+
+```bash
+./rvctl containers list
+```
+
+Przykladowy wynik:
+
+```text
+session   selector  task   instance  window
+--------  --------  -----  --------  ------
+rv-inf03  inf/03    task1  shell     rv
+```
+
+### `containers attach SESSION`
+
+Podlacza terminal do istniejacej sesji.
+
+```bash
+./rvctl containers attach rv-inf03
+```
+
+Technicznie odpowiada to:
+
+```bash
+tmux attach -t rv-inf03
+```
+
+### `containers stop SESSION`
+
+Zamyka sesje `tmux`, a razem z nia uruchomiony w niej proces kontenera.
+
+```bash
+./rvctl containers stop rv-inf03
+```
+
+Technicznie odpowiada to:
+
+```bash
+tmux kill-session -t rv-inf03
+```
+
+## Aliasowanie Starej Komendy
+
+Stara komenda moze zostac jako alias kompatybilnosci:
+
+```text
+tmux-container inf 03 --dry-run      -> containers show inf 03
+tmux-container inf 03 --session NAME -> containers start inf 03 --session NAME
+tmux-container inf/03 --attach       -> containers start inf/03 --attach
+```
+
+Dokumentacja i nowe przyklady powinny promowac namespace `containers`.