diff --git a/README.md b/README.md
index 42ab55e..49cda54 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,55 @@
 # RV Launcher
 
-Launcher do workspace `rv`.
+`rv-launcher` jest narzedziem do pracy z workspace RISC-V. Wlasciwym skryptem
+CLI jest wykonywalny plik `rvctl.py`; to on implementuje listowanie serii i
+kart, obsluge tokenow, przygotowanie repo odpowiedzi i start kontenera.
 
-- `workspace.json` trzyma sciezki repo oryginalnych, workspace i tools
-- `rvctl.py` zawiera implementacje CLI
-- `rvctl` listuje serie i karty
-- szczegolowy opis CLI jest w `doc/rvctl.md`
-- model tokenow i synchronizacji repo <-> store jest w `doc/tokens.md`
+Publicznym entrypointem dla uzytkownika jest krotki wrapper:
+
+```bash
+./rvctl
+```
+
+Wrapper uruchamia `python3 rvctl.py "$@"`. `rvctl.py` mozna tez uruchomic
+bezposrednio:
+
+```bash
+./rvctl.py
+```
+
+Sciezki i domyslne ustawienia sa trzymane w `workspace.json`.
+
+## Co robi narzedzie
+
+CLI porzadkuje prace w trzech obszarach.
+
+1. Zarzadzanie tokenami
+
+   Narzedzie obsluguje lokalny store `tokens/tokens.json`, porownuje go z git
+   remotes i potrafi synchronizowac token w obie strony. Szczegoly modelu,
+   format pliku i opis komend sa w `doc/tokens.md`.
+
+2. Listowanie i pobieranie kart pracy
+
+   `rvctl.py` czyta serie i karty z workspace, pomaga wybrac material do pracy
+   oraz przygotowuje remotes potrzebne do repo odpowiedzi. Szczegoly komend
+   `list-series`, `list-cards` i `submission` sa w `doc/rvctl.md`.
+
+3. Uruchamianie srodowiska programistycznego w kontenerach
+
+   Dla wybranej karty `rvctl.py` uruchamia sesje tmux i kontener z przygotowanym
+   srodowiskiem developerskim. Szczegoly komendy `tmux-container` sa w
+   `doc/rvctl.md`.
 
 ## Model katalogow
 
-Repo oryginalne trzymamy poza workspace:
+Repozytoria zrodlowe trzymamy poza workspace:
 
 ```bash
 ~/dev/edu/repos/rv
 ```
 
-Workspace sluzy do klonow roboczych i cwiczen:
+Workspace sluzy do klonow roboczych, cwiczen, tokenow i socketow:
 
 ```bash
 ~/dev/workspace/rv
@@ -31,273 +64,41 @@ Typowy uklad:
 ~/dev/workspace/rv/tools/rv-launcher
 ~/dev/workspace/rv/tools/rv32i-hazard3-env
 ~/dev/workspace/rv/series/<seria>/<karta>
-```
-
-Launcher szuka `rv32i-hazard3-env` najpierw w workspace, a jesli nie znajdzie
-klona roboczego, moze uzyc repo oryginalnego z `~/dev/edu/repos/rv`.
-
-Karty pracy tez sa rozdzielone:
-
-- `~/dev/edu/repos/rv/series/...` to checkouty zrodlowe, nad ktorymi pracujemy
-- `~/dev/workspace/rv/series/...` to klony testowe pobierane z Gitea
-
-Launcher wykonuje `list-series`, `list-cards`, `submission` i `tmux-container`
-na kartach z workspace, nie na repo zrodlowych.
-
-## Przygotowanie katalogu
-
-Repo treningowe launchera trzymaj pod:
-
-```bash
-~/dev/workspace/rv/tools/rv-launcher
-```
-
-Bootstrap bez `git clone`:
-
-```bash
-mkdir -p ~/dev/workspace/rv/tools
-mkdir -p ~/dev/workspace/rv/tools/rv-launcher
-cd ~/dev/workspace/rv/tools/rv-launcher
-git init
-```
-
-Glowne pliki CLI:
-
-```bash
-./rvctl
-rvctl.py
-```
-
-`rvctl` jest jedynym publicznym entrypointem. `rvctl.py` jest implementacja
-uruchamiana przez wrapper i nie wymaga osobnego wywolywania przez ucznia.
-
-Uruchomienie bez argumentow pokazuje tabelaryczny skrot komend:
-
-```bash
-./rvctl
-./rvctl tokens
-```
-
-## Autoryzacja
-
-Masz dwie drogi.
-
-### Droga 1: remote `r1` z tokenem w URL
-
-To jest wariant dydaktyczny, jesli uczen ma cwiczyc reczne dodawanie remota z
-tokenem do konkretnego zdalnego endpointu. Jesli launcher zobaczy URL w formacie
-`http://LOGIN:TOKEN@...`, mozesz zapisac ten token lokalnie komenda
-`tokens sync remote r1`.
-
-Przyklad:
-
-```bash
-git remote add r1 http://u1:TOKEN@77.90.8.171:3001/edu-tools/rv-launcher.git
-git fetch r1 main
-git switch --track -c main r1/main
-```
-
-### Droga 2: lokalny `tokens/tokens.json`
-
-To jest wariant alternatywny, wygodniejszy wtedy, gdy launcher ma sam wykonywac
-`clone`, `fetch` i `push`, albo gdy uzytkownik po zajeciach chce pracowac juz na
-wlasnych repo bez wpisywania tokena do kazdego remota.
-
-Przed operacjami wymagajacymi autoryzacji dodaj lokalny token do:
-
-```bash
 ~/dev/workspace/rv/tokens/tokens.json
 ```
 
-Minimalny format:
+`rvctl.py` pracuje na kartach z `series_root` w workspace. Repo zrodlowe w
+`~/dev/edu/repos/rv` sa punktem odniesienia i fallbackiem dla narzedzi.
 
-```json
-{
-  "version": 3,
-  "tokens": [
-    {
-      "id": "r1",
-      "value": "TU_WSTAW_TOKEN",
-      "server": {
-        "type": "gitea",
-        "endpoint": "http://77.90.8.171:3001",
-        "scheme": "http",
-        "host": "77.90.8.171",
-        "port": 3001
-      },
-      "user": "u1",
-      "org": "edu-tools",
-      "repo": "rv-launcher"
-    }
-  ]
-}
-```
+## Szybki start
 
-Pelny schemat pliku jest w `doc/tokens.schema.json`.
-
-Plik powinien byc lokalny, niewersjonowany i miec prawa `600`.
-
-Przyklad:
-
-```bash
-mkdir -p ~/dev/workspace/rv/tokens
-chmod 700 ~/dev/workspace/rv/tokens
-chmod 600 ~/dev/workspace/rv/tokens/tokens.json
-```
-
-Jesli token jest trzymany tylko w `tokens/tokens.json`, remote `r1` moze
-byc zapisany bez sekretu:
-
-```bash
-git remote add r1 http://77.90.8.171:3001/edu-tools/rv-launcher.git
-```
-
-Podstawowe komendy tokenow:
-
-```bash
-./rvctl tokens scan
-./rvctl tokens compare
-./rvctl tokens list store
-./rvctl tokens list remote
-./rvctl tokens sync remote r1
-./rvctl tokens update r1
-./rvctl tokens sync store r1
-./rvctl tokens remove store r1
-./rvctl tokens remove remote r1
-./rvctl tokens add r1
-./rvctl tokens read
-./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03
-```
-
-`tokens scan` wypisuje diagnostyczny skan git remotes i niczego nie zapisuje:
-pokazuje URL-e typu `auth`, `plain` i `unsupported`.
-`tokens compare` wypisuje tabele `tokens` i niczego nie zapisuje: jeden wiersz
-na logiczny remote tokena.
-`tokens list store|remote|both` wypisuje jedno zrodlo bez porownywania.
-`tokens.json` synchronizujemy z repo `rv-launcher`; remotes kart pracy i
-odpowiedzi sa generowane jako pochodne tego ustawienia.
-`token_ref` laczy nazwe tokena z markerem po prawej stronie: `*` oznacza, ze
-remote i `tokens.json` sa zgodne, `R` oznacza token tylko w remote, a `S`
-token tylko w `tokens.json`. Kolumny `scope`, `org` i `repo` sa maskami
-uprawnien; bez zgodnego wpisu maja wartosc `?????????`, `?????` albo `????`.
-Zapis z remote do `tokens.json` robi `tokens sync remote r1`.
-Odczyt `valid` i uprawnien z API robi `tokens update r1`.
-Zapis z `tokens.json` do remota robi `tokens sync store r1`.
-Usuniecie wpisu robi `tokens remove store r1`, a usuniecie git remota
-`tokens remove remote r1`.
-Kolumna `valid` oznacza, czy token zostal zaakceptowany przez API teraz.
-Jesli przy tokenie w `tokens.json` zapiszesz `expires_at`, `valid` moze pokazac
-date wygasniecia; bez daty poprawny token pokazuje `forever`.
-
-## Fetch i switch
-
-Domyslna galaz launchera to `main`.
-
-Wariant preferowany przez `r1`:
-
-```bash
-git fetch r1 main
-git switch --track -c main r1/main
-git pull --ff-only r1 main
-```
-
-Jesli repo bylo sklonowane klasycznie i pracujesz przez `origin`, odpowiednikiem
-jest:
-
-```bash
-git fetch origin main
-git switch main
-git pull --ff-only origin main
-```
-
-Jesli chcesz wejsc na inna galaz, na przyklad `feat/x`, uzyj:
-
-```bash
-git fetch r1 feat/x
-git switch --track -c feat/x r1/feat/x
-```
-
-Wariant przez `origin`:
-
-```bash
-git fetch origin feat/x
-git switch --track -c feat/x origin/feat/x
-```
-
-## Repo odpowiedzi kart pracy
-
-Model pracy kart jest taki:
-
-- `r1` wskazuje repo z materialem z `edu-inf`
-- `a1` wskazuje wspolne repo odpowiedzi w `zsl-inf`
-- kazdy uczen wysyla swoja prace na branch o nazwie swojego nicku
-
-Repo odpowiedzi nie zawiera nicku w nazwie. Launcher buduje je w formacie:
-
-```text
-zsl-inf/<repo_z_edu-inf>-<klasa>-<data>
-```
-
-Przyklad:
-
-```text
-zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
-```
-
-Przyklad planu dla ucznia `u1`:
-
-```bash
-./rvctl submission inf 03 --class 4i --nick u1
-```
-
-Przyklad konfiguracji remote'ow w repo karty:
-
-```bash
-./rvctl submission inf 03 --class 4i --nick u1 --apply
-```
-
-Launcher wtedy:
-
-- czyta URL zrodlowego repo z `origin` aktualnej karty i ustawia go jako `r1`
-- bierze basename tego repo z `edu-inf` i z niego buduje nazwe repo odpowiedzi
-- wylicza repo odpowiedzi w `zsl-inf` i ustawia je jako `a1`
-- proponuje branch ucznia, na przyklad `u1`
-
-Typowy wynik to:
-
-```text
-source_repo    edu-inf/lab-rv32i-strlen-bss-data-stack
-source_remote  r1
-answer_remote  a1
-answer_repo    zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
-student_branch u1
-```
-
-## Wariant alternatywny: `git clone`
-
-Jesli celem nie jest cwiczenie `remote add` i `fetch`, repo treningowe mozna
-tez sklonowac klasycznie:
-
-```bash
-mkdir -p ~/dev/workspace/rv/tools
-cd ~/dev/workspace/rv/tools
-git clone http://77.90.8.171:3001/edu-tools/rv-launcher.git
-cd rv-launcher
-```
-
-## Podstawowe komendy
-
-Przyklady:
+Najpierw zobacz konfiguracje i dostepne komendy:
 
 ```bash
 ./rvctl
 ./rvctl show-config
-./rvctl list-series
-./rvctl list-cards inf
-./rvctl tokens
-./rvctl submission inf 03 --class 4i --nick u1
-./rvctl tmux-container inf 03 --dry-run
-./rvctl tmux-container inf 03 --session rv-inf03 --attach
 ```
 
-Skrypt nie trzyma listy kart w JSON-ie. Czyta `series/*/*` z `series_root`.
+Typowy przeplyw pracy:
+
+```bash
+./rvctl tokens scan
+./rvctl list-series
+./rvctl list-cards inf
+./rvctl tmux-container inf 03 --dry-run
+./rvctl tmux-container inf 03 --session rv-inf03 --attach
+./rvctl submission inf 03 --class 4i --nick u1
+```
+
+`--dry-run` jest przydatny przy sprawdzaniu planu uruchomienia lub konfiguracji
+repo, zanim narzedzie cos zmieni.
+
+## Dokumentacja
+
+- `doc/rvctl.md` - komendy CLI, przelaczniki i przyklady uzycia
+- `doc/tokens.md` - model tokenow, synchronizacja remote <-> store
+- `doc/tokens.schema.json` - schemat `tokens/tokens.json`
+- `doc/workspace.md` - krotki opis konfiguracji workspace
+
+README jest tylko mapa projektu. Szczegoly operacyjne trzymamy w `doc/`, zeby
+nie dublowac instrukcji w kilku miejscach.
diff --git a/rvctl.py b/rvctl.py
old mode 100644
new mode 100755