feat: add three-profile STEM container workflow

doc/agents.md

@@ -1,8 +1,8 @@
 # Agenci w środowisku kontenerowym
 
-Ten dokument zapisuje wnioski do przyszłej integracji agentów, takich jak
-Codex, Gemini i inne narzędzia asystujące. Integrację robimy po domknięciu
-kontenerów `rv32i` i `host`.
+Ten dokument zapisuje wnioski do integracji agentów, takich jak Codex, Claude,
+Gemini i inne narzędzia asystujące. Docelowo integracja obejmuje trzy profile:
+`native-amd64`, `hazard3-sim` i `rp2350`.
 
 ## Założenie
 
@@ -13,39 +13,40 @@ mieć wgląd w tę samą sesję, w której pracuje uczeń:
 - `nvim` - edycja plików i nawigacja po kodzie,
 - `gdb` lub `gdb-multiarch` - stan debuggera,
 - katalog karty pracy zamontowany w kontenerze,
-- stan sesji zapisany pod `.rv/<instance>/`.
+- stan sesji zapisany pod `.stem/instances/<instance>/`.
 
 Dzięki temu agent widzi środowisko debugowania, a nie tylko statyczne pliki.
 
 ## Aktualny fundament
 
-`rv32i-hazard3-student-env` ma już elementy potrzebne do takiego modelu:
+`rv32i-hazard3-student-env` dostarcza źródła wspólnego modelu:
 
-- profil `rv32i` jako usługa `env` w `docker compose`,
-- profil `host` jako osobna usługa `host`,
+- profile `native-amd64`, `hazard3-sim` i `rp2350` jako trzy usługi Compose;
+- jeden wieloetapowy Dockerfile budowany lokalnie, bez dystrybucji obrazów;
 - `tmux` jako warstwa sesji terminalowej,
 - `nvim` uruchamiany ze stabilnym socketem,
 - `gdb-multiarch` dla profilu `rv32i`,
 - `gdb` i opcjonalnie `lldb` dla profilu `host`,
-- katalog stanu `.rv/<instance>/`,
+- katalog stanu `.stem/instances/<instance>/`, z fallbackiem `.rv`;
 - skrypty MCP dla `tmux` i `nvim`:
   - `scripts/mcp-tmux.sh`,
   - `scripts/mcp-nvim.sh`,
   - `scripts/nvim-in-container.sh`.
 
-To oznacza, że kontenery są dobrym miejscem do podłączenia agentów. Brakuje
-jeszcze spójnej warstwy komend w `rvctl`.
+Serwery MCP są instalowane w kontenerze, a hostowe wrappery weryfikują label i
+bieżący ID Podmana przed `podman exec`. `stemctl` oraz wspólny kontrakt trzech
+profili są wdrożone; osobne komendy wyższego poziomu `agent start/attach`
+pozostają rozszerzeniem późniejszym.
 
 ## Docelowy model komend
 
-Docelowo `rvctl` powinien ukrywać szczegóły socketów, kontenerów i providerów.
+Docelowo `stemctl` powinien ukrywać szczegóły socketów, kontenerów i providerów.
 Przykładowy kierunek:
 
 ```bash
-./rvctl agent start codex rv32i inf bss 4
-./rvctl agent start codex host inf bss 4
-./rvctl agent start gemini rv32i inf bss 4
-./rvctl agent start gemini host inf bss 4
+./stemctl agent start codex native-amd64 inf bss 4
+./stemctl agent start codex hazard3-sim inf bss 4
+./stemctl agent start codex rp2350 inf bss 4 --target rp2350-rv
 ```
 
 Skróty mogą powstać później, ale podstawowy model powinien zostać jawny:
@@ -54,28 +55,27 @@ agent, profil środowiska, seria, karta i zadanie.
 Możliwy wariant dla już uruchomionej sesji:
 
 ```bash
-./rvctl agent attach codex --instance rv32i-inf-bss-t4-debug
-./rvctl agent attach gemini --instance host-inf-bss-t4-debug
+./stemctl agent attach codex --instance hazard3-sim-inf-bss-t4
 ```
 
-## Co powinien robić `rvctl`
+## Co powinien robić `stemctl`
 
 Przy `agent start` narzędzie powinno:
 
 1. rozwiązać serię, kartę i zadanie tak samo jak `debug`,
-2. wybrać profil `rv32i` albo `host`,
+2. wybrać jeden z trzech profili i właściwy target,
 3. nadać stabilną nazwę instancji, na przykład
-   `rv32i-inf-bss-t4-debug`,
+   `hazard3-sim-inf-bss-t4`,
 4. uruchomić kontener i sesję `tmux`,
 5. włączyć tryb agentowy przez zmienne środowiskowe, na przykład:
 
 ```text
-RV_AGENT=codex
-RV_CODEX=1
-RV_INSTANCE=rv32i-inf-bss-t4-debug
+STEM_AGENT=codex
+STEM_MCP=1
+STEM_INSTANCE=hazard3-sim-inf-bss-t4
 ```
 
-6. zapisać albo odczytać sockety z `.rv/<instance>/`,
+6. rozwiązać bieżący container ID i sockety z katalogu instancji,
 7. uruchomić bridge MCP dla `tmux` i `nvim`,
 8. przekazać agentowi minimalny kontekst:
    - ścieżka repo karty,
@@ -87,51 +87,60 @@ RV_INSTANCE=rv32i-inf-bss-t4-debug
 
 ## Sockety i stan sesji
 
-Dla każdej instancji powinniśmy konsekwentnie używać katalogu:
+Dla każdej instancji używamy dwóch poziomów tożsamości:
 
 ```text
-<card>/.rv/<instance>/
+$XDG_RUNTIME_DIR/stem/<thread-key>/<instance-key>/<cid12>/
 ```
 
 W nim mogą znajdować się:
 
 ```text
-tmux.sock
-nvim.sock
+t.sock
+n.sock
 gdb-sync.json
-vim-mcp.sock
-vim-mcp-registry.json
+container.json
 ```
 
-`rvctl` powinien traktować te pliki jako szczegóły implementacyjne. Użytkownik
-i agent powinni dostawać komendy wyższego poziomu.
+Pełna nazwa instancji pozostaje w label i registry. Krótkie klucze oraz
+12-znakowy prefiks container ID utrzymują ścieżkę AF_UNIX poniżej 100 bajtów.
+Aktualny ID uniemożliwia użycie socketu pozostałego po odtworzeniu kontenera.
+`stemctl` traktuje te pliki jako szczegóły implementacyjne. Użytkownik i agent
+dostają komendy wyższego poziomu.
 
 ## Role profili
 
-Profil `rv32i`:
+Profil `hazard3-sim`:
 
 - debugowanie kodu dla RISC-V/Hazard3,
 - `gdb-multiarch`,
 - symulator,
 - przykłady asemblerowe i mieszane C/ASM.
 
-Profil `host`:
+Profil `native-amd64`:
 
 - natywne uruchomienie i debugowanie kodu C,
 - szybkie testowanie algorytmów,
 - `clang` albo `gcc`,
 - `gdb`, opcjonalnie `lldb` i `valgrind`.
 
-Taski czysto asemblerowe pozostają w profilu `rv32i`.
+Profil `rp2350`:
+
+- debugowanie fizycznego Pico 2/Pico 2 W;
+- targety RISC-V Hazard3 i ARM Cortex-M33;
+- OpenOCD, probe, flash, serial i FreeRTOS;
+- dostęp tylko do jawnie wybranego urządzenia USB.
+
+Taski czysto asemblerowe RISC-V pozostają w `hazard3-sim` albo `rp2350-rv`.
 
 ## Kolejność wdrożenia
 
-1. Domknąć komendy kontenerowe `env`, `debug`, `run` i `shell`.
-2. Ustabilizować nazwy instancji i katalog `.rv/<instance>/`.
-3. Opisać kontrakt socketów dla `tmux` i `nvim`.
-4. Dodać `rvctl agent list`.
-5. Dodać `rvctl agent start`.
-6. Dodać `rvctl agent attach`.
+1. Domknąć trzy profile i komendy `build`, `test`, `run`, `debug`, `deploy`.
+2. Ustabilizować labels instancji i katalogi socketów z container ID.
+3. Zaimplementować resolver socketów dla `tmux` i `nvim`.
+4. Dodać `stemctl agent list`.
+5. Dodać `stemctl agent start`.
+6. Dodać `stemctl agent attach`.
 7. Dopiero potem podpinać konkretne providery: Codex, Gemini i kolejne.
 
 ## Zasada projektowa