From c57c14ee63f55c6189b71d40783e71c737ce19e1 Mon Sep 17 00:00:00 2001
From: mpabi <mpabi@mpabi.pl>
Date: Sun, 26 Apr 2026 13:50:30 +0200
Subject: [PATCH] Add rvctl entrypoint and docs

---
 README.md        |  37 ++--
 doc/rvctl.md     | 531 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/tokens.md    |  18 +-
 doc/workspace.md | 521 +---------------------------------------------
 rvctl            |   4 +
 workspace        |   4 +
 workspace.py     |   5 +-
 wspace           |   4 +
 8 files changed, 586 insertions(+), 538 deletions(-)
 create mode 100644 doc/rvctl.md
 create mode 100755 rvctl
 create mode 100755 workspace
 create mode 100755 wspace

diff --git a/README.md b/README.md
index f3995b2..542469f 100644
--- a/README.md
+++ b/README.md
@@ -3,8 +3,8 @@
 Launcher do workspace `rv`.
 
 - `workspace.json` trzyma sciezki repo oryginalnych, workspace i tools
-- `workspace.py` listuje serie i karty
-- szczegolowy opis przelacznikow skryptu jest w `doc/workspace.md`
+- `rvctl` listuje serie i karty
+- szczegolowy opis CLI jest w `doc/rvctl.md`
 - model tokenow i synchronizacji repo <-> store jest w `doc/tokens.md`
 
 ## Model katalogow
@@ -60,6 +60,17 @@ cd ~/dev/workspace/rv/tools/rv-launcher
 git init
 ```
 
+Glowne entrypointy:
+
+```bash
+./rvctl
+./workspace
+./wspace
+```
+
+`rvctl` jest nazwa podstawowa. `workspace` i `wspace` sa aliasami do tego
+samego CLI.
+
 ## Autoryzacja
 
 Masz dwie drogi.
@@ -133,9 +144,9 @@ git remote add r1 http://77.90.8.171:3001/edu-tools/rv-launcher.git
 Podstawowe komendy tokenow:
 
 ```bash
-python3 workspace.py tokens scan
-python3 workspace.py tokens read
-python3 workspace.py tokens stats --repo ~/dev/workspace/rv/series/inf/03
+./rvctl tokens scan
+./rvctl tokens read
+./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03
 ```
 
 ## Fetch i switch
@@ -196,13 +207,13 @@ zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
 Przyklad planu dla ucznia `u1`:
 
 ```bash
-python3 workspace.py submission inf 03 --class 4i --nick u1
+./rvctl submission inf 03 --class 4i --nick u1
 ```
 
 Przyklad konfiguracji remote'ow w repo karty:
 
 ```bash
-python3 workspace.py submission inf 03 --class 4i --nick u1 --apply
+./rvctl submission inf 03 --class 4i --nick u1 --apply
 ```
 
 Launcher wtedy:
@@ -239,12 +250,12 @@ cd rv-launcher
 Przyklady:
 
 ```bash
-python3 workspace.py show-config
-python3 workspace.py list-series
-python3 workspace.py list-cards inf
-python3 workspace.py submission inf 03 --class 4i --nick u1
-python3 workspace.py tmux-container inf 03 --dry-run
-python3 workspace.py tmux-container inf 03 --session rv-inf03 --attach
+./rvctl show-config
+./rvctl list-series
+./rvctl list-cards inf
+./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`.
diff --git a/doc/rvctl.md b/doc/rvctl.md
new file mode 100644
index 0000000..e55f6e4
--- /dev/null
+++ b/doc/rvctl.md
@@ -0,0 +1,531 @@
+# RVCTL CLI
+
+Plik opisuje przelaczniki i liste komend skryptu `rvctl`.
+
+## Model katalogow
+
+Repo oryginalne trzymamy poza workspace:
+
+```bash
+~/dev/edu/repos/rv
+```
+
+Workspace sluzy do klonow roboczych i cwiczen:
+
+```bash
+~/dev/workspace/rv
+```
+
+Typowy uklad:
+
+```text
+~/dev/edu/repos/rv/rv-launcher
+~/dev/edu/repos/rv/rv32i-hazard3-env
+~/dev/edu/repos/rv/series/<seria>/<karta>
+~/dev/workspace/rv/tools/rv-launcher
+~/dev/workspace/rv/tools/rv32i-hazard3-env
+~/dev/workspace/rv/series/<seria>/<karta>
+```
+
+`rvctl` czyta karty z `series_root` w workspace. Tool repo
+`rv32i-hazard3-env` wybiera najpierw z workspace, a potem z fallbacku
+`~/dev/edu/repos/rv`, jesli taki klon roboczy jeszcze nie istnieje.
+
+Karty pracy tez sa rozdzielone:
+
+- `original_series_root` wskazuje repo zrodlowe kart, na przyklad `~/dev/edu/repos/rv/series`
+- `series_root` wskazuje klony testowe w workspace, na przyklad `~/dev/workspace/rv/series`
+
+Komendy launchera pracuja na `series_root`, czyli na klonach testowych.
+
+## Pobranie repo i przelaczenie galezi
+
+Repo treningowe launchera trzymaj pod:
+
+```bash
+~/dev/workspace/rv/tools/rv-launcher
+```
+
+Podstawowy bootstrap wyglada tak:
+
+```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
+```
+
+Glowne entrypointy:
+
+```bash
+./rvctl
+./workspace
+./wspace
+```
+
+`rvctl` jest nazwa podstawowa. `workspace` i `wspace` sa aliasami do tego
+samego CLI.
+
+### 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 zdalnego endpointu. Jesli launcher zobaczy URL w formacie
+`http://LOGIN:TOKEN@...`, zapisze ten token lokalnie do `tokens/tokens.json`.
+
+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`
+
+Przed operacjami wymagajacymi autoryzacji dodaj lokalny token do:
+
+```bash
+~/dev/workspace/rv/tokens/tokens.json
+```
+
+Minimalny format pliku:
+
+```json
+{
+  "version": 2,
+  "servers": {
+    "http://77.90.8.171:3001": {
+      "type": "gitea",
+      "scheme": "http",
+      "host": "77.90.8.171",
+      "port": 3001,
+      "users": {
+        "u1": {
+          "tokens": {
+            "t1": "TU_WSTAW_TOKEN"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Ten 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
+```
+
+Wariant z `tokens/tokens.json` jest wygodniejszy wtedy, gdy launcher ma
+sam wykonywac `clone`, `fetch` i `push`, albo gdy uzytkownik po zajeciach chce
+pracowac z wieloma repo na swoim koncie bez wpisywania tokena do kazdego
+remota.
+
+### Fetch i switch
+
+Domyslna galaz launchera to `main`.
+
+Po sklonowaniu:
+
+```bash
+git fetch origin main
+git switch main
+git pull --ff-only
+```
+
+Wariant przez `r1`:
+
+```bash
+git fetch r1 main
+git switch --track -c main r1/main
+git pull --ff-only r1 main
+```
+
+Jesli chcesz wejsc na inna galaz, na przyklad `feat/x`, uzyj:
+
+```bash
+git fetch origin feat/x
+git switch --track -c feat/x origin/feat/x
+```
+
+Wariant przez `r1`:
+
+```bash
+git fetch r1 feat/x
+git switch --track -c feat/x r1/feat/x
+```
+
+## Wywolanie glowne
+
+```bash
+./rvctl [--config PATH] <komenda> [opcje]
+```
+
+Globalne przelaczniki:
+
+- `--config PATH`
+  Uzywa innego pliku `workspace.json`.
+
+Komendy:
+
+- `show-config`
+- `list-series`
+- `list-cards [series]`
+- `tokens scan`
+- `tokens read`
+- `tokens stats`
+- `tokens write`
+- `tokens update`
+- `submission [series] [card]`
+- `tmux-container [series] [card]`
+
+## `show-config`
+
+Wypisuje rozwiazane sciezki z konfiguracji.
+
+Typowy format:
+
+```text
+config_path<TAB>...
+original_root<TAB>...
+original_series_root<TAB>...
+workspace_root<TAB>...
+series_root<TAB>...
+socket_root<TAB>...
+token_path<TAB>...
+tools_root<TAB>...
+git_base_url<TAB>...
+git_source_org<TAB>...
+git_answer_org<TAB>...
+git_source_remote<TAB>...
+git_answer_remote<TAB>...
+git_origin_remote<TAB>...
+git_fallback_branch<TAB>...
+tools_root_candidates
+  ...
+```
+
+Przyklad:
+
+```bash
+./rvctl show-config
+```
+
+## `list-series`
+
+Listuje katalogi serii znalezione w `series_root`.
+
+Kazda linia ma format:
+
+```text
+<series_id><TAB><liczba_kart><TAB><pelna_sciezka>
+```
+
+Przyklad:
+
+```bash
+./rvctl list-series
+```
+
+## `list-cards [series]`
+
+Listuje karty z wybranej serii.
+
+Argumenty:
+
+- `series`
+  Opcjonalne id serii, na przyklad `inf`.
+  Jesli go brak, brana jest domyslna seria z `workspace.json`.
+
+Format wyjscia:
+
+```text
+<card_no><TAB><tytul_z_README><TAB><pelna_sciezka>
+```
+
+Jesli `README.md` nie ma naglowka `#`, skrypt wypisuje:
+
+```text
+<card_no><TAB><pelna_sciezka>
+```
+
+Przyklady:
+
+```bash
+./rvctl list-cards
+./rvctl list-cards inf
+```
+
+## `tokens scan`
+
+Skanuje remote URL-e w repo i zapisuje znalezione dane do `tokens/tokens.json`.
+
+Przelaczniki:
+
+- `--repo PATH`
+  Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
+
+Typowy wynik:
+
+```text
+repo_root<TAB>...
+scanned<TAB>1
+added<TAB>1
+servers<TAB>1
+token_path<TAB>...
+```
+
+Przyklad:
+
+```bash
+./rvctl tokens scan
+./rvctl tokens scan --repo ~/dev/workspace/rv/series/inf/03
+```
+
+## `tokens read`
+
+Pokazuje zawartosc `tokens/tokens.json` w podziale na endpointy serwerow.
+
+Przelaczniki:
+
+- `--server ENDPOINT`
+  Ogranicza wynik do jednego endpointu.
+- `--show-secrets`
+  Pokazuje pelne wartosci tokenow zamiast maskowania.
+
+Typowy wynik:
+
+```text
+token_path<TAB>...
+endpoint<TAB>http://77.90.8.171:3001
+type<TAB>gitea
+scheme<TAB>http
+host<TAB>77.90.8.171
+port<TAB>3001
+users<TAB>1
+tokens<TAB>1
+user<TAB>u1
+token<TAB>t1<TAB>SE****23
+```
+
+Przyklad:
+
+```bash
+./rvctl tokens read
+./rvctl tokens read --server http://77.90.8.171:3001
+```
+
+## `tokens stats`
+
+Pokazuje statystyki endpointow z repo i `tokens.json`, a takze ich zgodnosc
+wzgledem siebie.
+
+Przelaczniki:
+
+- `--repo PATH`
+  Sciezka wewnatrz repo, z ktorego maja byc odczytane remote URL-e.
+- `--server ENDPOINT`
+  Ogranicza wynik do jednego endpointu.
+
+Typowy wynik:
+
+```text
+repo_root<TAB>...
+token_path<TAB>...
+repo_endpoints<TAB>1
+store_endpoints<TAB>1
+union_endpoints<TAB>1
+in_sync<TAB>0
+repo_only<TAB>0
+store_only<TAB>0
+repo_ahead<TAB>0
+store_ahead<TAB>1
+diverged<TAB>0
+
+endpoint<TAB>type<TAB>repo_remotes<TAB>repo_urls<TAB>repo_auth_urls<TAB>repo_plain_urls<TAB>repo_users<TAB>repo_tokens<TAB>store_users<TAB>store_tokens<TAB>repo_only_tokens<TAB>store_only_tokens<TAB>status
+http://77.90.8.171:3001<TAB>gitea<TAB>origin<TAB>1<TAB>0<TAB>1<TAB>0<TAB>0<TAB>1<TAB>1<TAB>0<TAB>1<TAB>store_ahead
+```
+
+Przyklad:
+
+```bash
+./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03
+```
+
+## `tokens write`
+
+Wpisuje dane z `tokens/tokens.json` do wybranego remota repo.
+
+Przelaczniki:
+
+- `--repo PATH`
+  Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
+- `--remote NAME`
+  Nazwa remota do aktualizacji lub utworzenia.
+- `--url URL`
+  URL remota, jesli remote jeszcze nie istnieje.
+- `--server ENDPOINT`
+  Endpoint serwera z `tokens.json`.
+- `--user NAME`
+  Uzytkownik z wybranego endpointu.
+- `--token-name NAME`
+  Nazwa tokena, na przyklad `t1`.
+- `--replace`
+  Nadpisuje inne dane auth juz wpisane w remote URL.
+- `--dry-run`
+  Pokazuje plan bez zapisu.
+
+Przyklad:
+
+```bash
+./rvctl tokens write --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
+```
+
+## `tokens update`
+
+Uruchamia synchronizacje w zadanym kierunku.
+
+Przelaczniki:
+
+- `--from remotes`
+  Skanuje remote URL-e i zapisuje wynik do `tokens.json`.
+- `--from store`
+  Bierze dane z `tokens.json` i wpisuje je do remota repo.
+- `--repo PATH`
+  Sciezka wewnatrz repo.
+- `--remote NAME`
+  Wymagane dla `--from store`.
+- `--url URL`
+  Opcjonalny URL dla `--from store`.
+- `--server ENDPOINT`
+  Opcjonalny wybor endpointu dla `--from store`.
+- `--user NAME`
+  Opcjonalny wybor usera dla `--from store`.
+- `--token-name NAME`
+  Opcjonalny wybor tokena dla `--from store`.
+- `--replace`
+  Nadpisuje inne auth przy `--from store`.
+- `--dry-run`
+  Pokazuje plan bez zapisu przy `--from store`.
+
+Przyklady:
+
+```bash
+./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
+./rvctl tokens update --from store --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
+```
+
+## `submission [series] [card]`
+
+Wylicza flow oddawania rozwiazan:
+
+- `r1` jako repo z materialem z `edu-inf`
+- `a1` jako repo odpowiedzi w `zsl-inf`
+- branch ucznia na podstawie jego nicku
+
+Nazwa repo odpowiedzi jest budowana z nazwy repo zrodlowego z `edu-inf`, klasy
+i daty:
+
+```text
+<repo_z_edu-inf>-<klasa>-<data>
+```
+
+Przyklad:
+
+```text
+lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
+```
+
+Argumenty pozycyjne:
+
+- `series`
+  Id serii albo pelny selector, na przyklad `inf` albo `inf/03`.
+- `card`
+  Numer karty, na przyklad `03`.
+
+Przelaczniki:
+
+- `--class NAME`
+  Id klasy, na przyklad `4i`.
+- `--nick NAME`
+  Nick ucznia. Domyslnie z niego powstaje nazwa brancha.
+- `--branch NAME`
+  Nadpisuje domyslna nazwe brancha.
+- `--date YYYY-MM-DD`
+  Data zajec uzywana w nazwie repo odpowiedzi. Domyslnie dzisiejsza.
+- `--source-url URL`
+  Nadpisuje URL repo zrodlowego. Bez tego launcher czyta `origin` z repo karty.
+- `--apply`
+  Dodaje albo aktualizuje remote `r1` i `a1` w repo karty.
+
+Typowy format wyjscia:
+
+```text
+selector<TAB>inf/03
+card_path<TAB>...
+source_repo<TAB>edu-inf/lab-rv32i-strlen-bss-data-stack
+source_remote<TAB>r1
+source_url<TAB>http://77.90.8.171:3001/edu-inf/lab-rv32i-strlen-bss-data-stack.git
+source_branch<TAB>deploy
+answer_remote<TAB>a1
+answer_repo<TAB>zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
+answer_url<TAB>http://77.90.8.171:3001/zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26.git
+student_branch<TAB>u1
+```
+
+Przyklady:
+
+```bash
+./rvctl submission inf 03 --class 4i --nick u1
+./rvctl submission inf 03 --class 4i --nick u1 --apply
+./rvctl submission inf/03 --class 4i --nick u2 --date 2026-04-26
+```
+
+## `tmux-container [series] [card]`
+
+Tworzy nowa sesje `tmux` i uruchamia kontener w `pane 0`.
+
+Argumenty pozycyjne:
+
+- `series`
+  Id serii albo pelny selector, na przyklad `inf` albo `inf/03`.
+- `card`
+  Numer karty, na przyklad `03`.
+
+Przelaczniki:
+
+- `--session NAME`
+  Nadpisuje nazwe sesji `tmux`.
+- `--window NAME`
+  Nadpisuje nazwe okna `tmux`.
+- `--instance NAME`
+  Ustawia `RV_INSTANCE` dla wrappera `rv`.
+- `--attach`
+  Po utworzeniu sesji robi `tmux attach`.
+- `--dry-run`
+  Nie uruchamia `tmux`; wypisuje selector, sciezki i koncowa komende.
+
+Reguly wyboru karty:
+
+- `tmux-container inf 03` -> seria `inf`, karta `03`
+- `tmux-container inf/03` -> pelny selector
+- `tmux-container 03` -> domyslna seria + karta `03`
+- `tmux-container inf` -> seria `inf` + domyslna karta
+- bez argumentow -> domyslna seria i domyslna karta
+
+Przyklady:
+
+```bash
+./rvctl tmux-container 03 --dry-run
+./rvctl tmux-container inf 03 --session rv-inf03
+./rvctl tmux-container inf/03 --attach
+```
diff --git a/doc/tokens.md b/doc/tokens.md
index 670ee55..a9adc4b 100644
--- a/doc/tokens.md
+++ b/doc/tokens.md
@@ -88,8 +88,8 @@ Dzialanie:
 Przyklad:
 
 ```bash
-python3 workspace.py tokens scan
-python3 workspace.py tokens scan --repo ~/dev/workspace/rv/series/inf/03
+./rvctl tokens scan
+./rvctl tokens scan --repo ~/dev/workspace/rv/series/inf/03
 ```
 
 ### `tokens read`
@@ -111,9 +111,9 @@ Oraz liste userow i nazw tokenow dla kazdego endpointu.
 Przyklad:
 
 ```bash
-python3 workspace.py tokens read
-python3 workspace.py tokens read --server http://77.90.8.171:3001
-python3 workspace.py tokens read --show-secrets
+./rvctl tokens read
+./rvctl tokens read --server http://77.90.8.171:3001
+./rvctl tokens read --show-secrets
 ```
 
 ### `tokens stats`
@@ -134,7 +134,7 @@ Wynik ma ten sam model co `tokens read`, ale w formie zbiorczej:
 Przyklad:
 
 ```bash
-python3 workspace.py tokens stats --repo ~/dev/workspace/rv/series/inf/03
+./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03
 ```
 
 ### `tokens write`
@@ -154,7 +154,7 @@ Dzialanie:
 Przyklad:
 
 ```bash
-python3 workspace.py tokens write \
+./rvctl tokens write \
   --repo ~/dev/workspace/rv/series/inf/03 \
   --remote r1 \
   --server http://77.90.8.171:3001 \
@@ -174,8 +174,8 @@ Dozwolone kierunki:
 Przyklad:
 
 ```bash
-python3 workspace.py tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
-python3 workspace.py tokens update --from store --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
+./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
+./rvctl tokens update --from store --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
 ```
 
 ## Konflikty
diff --git a/doc/workspace.md b/doc/workspace.md
index 3f4ccde..d9fbc63 100644
--- a/doc/workspace.md
+++ b/doc/workspace.md
@@ -1,520 +1,11 @@
-# RV Launcher CLI
+# Workspace CLI
 
-Plik opisuje przelaczniki i liste komend skryptu `workspace.py`.
+Skrot dokumentacji jest teraz w `doc/rvctl.md`.
 
-## Model katalogow
-
-Repo oryginalne trzymamy poza workspace:
+Glowne entrypointy:
 
 ```bash
-~/dev/edu/repos/rv
-```
-
-Workspace sluzy do klonow roboczych i cwiczen:
-
-```bash
-~/dev/workspace/rv
-```
-
-Typowy uklad:
-
-```text
-~/dev/edu/repos/rv/rv-launcher
-~/dev/edu/repos/rv/rv32i-hazard3-env
-~/dev/edu/repos/rv/series/<seria>/<karta>
-~/dev/workspace/rv/tools/rv-launcher
-~/dev/workspace/rv/tools/rv32i-hazard3-env
-~/dev/workspace/rv/series/<seria>/<karta>
-```
-
-`workspace.py` czyta karty z `series_root` w workspace. Tool repo
-`rv32i-hazard3-env` wybiera najpierw z workspace, a potem z fallbacku
-`~/dev/edu/repos/rv`, jesli taki klon roboczy jeszcze nie istnieje.
-
-Karty pracy tez sa rozdzielone:
-
-- `original_series_root` wskazuje repo zrodlowe kart, na przyklad `~/dev/edu/repos/rv/series`
-- `series_root` wskazuje klony testowe w workspace, na przyklad `~/dev/workspace/rv/series`
-
-Komendy launchera pracuja na `series_root`, czyli na klonach testowych.
-
-## Pobranie repo i przelaczenie galezi
-
-Repo treningowe launchera trzymaj pod:
-
-```bash
-~/dev/workspace/rv/tools/rv-launcher
-```
-
-Podstawowy bootstrap wyglada tak:
-
-```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
-```
-
-### 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 zdalnego endpointu. Jesli launcher zobaczy URL w formacie
-`http://LOGIN:TOKEN@...`, zapisze ten token lokalnie do `tokens/tokens.json`.
-
-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`
-
-Przed operacjami wymagajacymi autoryzacji dodaj lokalny token do:
-
-```bash
-~/dev/workspace/rv/tokens/tokens.json
-```
-
-Minimalny format pliku:
-
-```json
-{
-  "version": 2,
-  "servers": {
-    "http://77.90.8.171:3001": {
-      "type": "gitea",
-      "scheme": "http",
-      "host": "77.90.8.171",
-      "port": 3001,
-      "users": {
-        "u1": {
-          "tokens": {
-            "t1": "TU_WSTAW_TOKEN"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-Ten 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
-```
-
-Wariant z `tokens/tokens.json` jest wygodniejszy wtedy, gdy launcher ma
-sam wykonywac `clone`, `fetch` i `push`, albo gdy uzytkownik po zajeciach chce
-pracowac z wieloma repo na swoim koncie bez wpisywania tokena do kazdego
-remota.
-
-### Fetch i switch
-
-Domyslna galaz launchera to `main`.
-
-Po sklonowaniu:
-
-```bash
-git fetch origin main
-git switch main
-git pull --ff-only
-```
-
-Wariant przez `r1`:
-
-```bash
-git fetch r1 main
-git switch --track -c main r1/main
-git pull --ff-only r1 main
-```
-
-Jesli chcesz wejsc na inna galaz, na przyklad `feat/x`, uzyj:
-
-```bash
-git fetch origin feat/x
-git switch --track -c feat/x origin/feat/x
-```
-
-Wariant przez `r1`:
-
-```bash
-git fetch r1 feat/x
-git switch --track -c feat/x r1/feat/x
-```
-
-## Wywolanie glowne
-
-```bash
-python3 workspace.py [--config PATH] <komenda> [opcje]
-```
-
-Globalne przelaczniki:
-
-- `--config PATH`
-  Uzywa innego pliku `workspace.json`.
-
-Komendy:
-
-- `show-config`
-- `list-series`
-- `list-cards [series]`
-- `tokens scan`
-- `tokens read`
-- `tokens stats`
-- `tokens write`
-- `tokens update`
-- `submission [series] [card]`
-- `tmux-container [series] [card]`
-
-## `show-config`
-
-Wypisuje rozwiazane sciezki z konfiguracji.
-
-Typowy format:
-
-```text
-config_path<TAB>...
-original_root<TAB>...
-original_series_root<TAB>...
-workspace_root<TAB>...
-series_root<TAB>...
-socket_root<TAB>...
-token_path<TAB>...
-tools_root<TAB>...
-git_base_url<TAB>...
-git_source_org<TAB>...
-git_answer_org<TAB>...
-git_source_remote<TAB>...
-git_answer_remote<TAB>...
-git_origin_remote<TAB>...
-git_fallback_branch<TAB>...
-tools_root_candidates
-  ...
-```
-
-Przyklad:
-
-```bash
-python3 workspace.py show-config
-```
-
-## `list-series`
-
-Listuje katalogi serii znalezione w `series_root`.
-
-Kazda linia ma format:
-
-```text
-<series_id><TAB><liczba_kart><TAB><pelna_sciezka>
-```
-
-Przyklad:
-
-```bash
-python3 workspace.py list-series
-```
-
-## `list-cards [series]`
-
-Listuje karty z wybranej serii.
-
-Argumenty:
-
-- `series`
-  Opcjonalne id serii, na przyklad `inf`.
-  Jesli go brak, brana jest domyslna seria z `workspace.json`.
-
-Format wyjscia:
-
-```text
-<card_no><TAB><tytul_z_README><TAB><pelna_sciezka>
-```
-
-Jesli `README.md` nie ma naglowka `#`, skrypt wypisuje:
-
-```text
-<card_no><TAB><pelna_sciezka>
-```
-
-Przyklady:
-
-```bash
-python3 workspace.py list-cards
-python3 workspace.py list-cards inf
-```
-
-## `tokens scan`
-
-Skanuje remote URL-e w repo i zapisuje znalezione dane do `tokens/tokens.json`.
-
-Przelaczniki:
-
-- `--repo PATH`
-  Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
-
-Typowy wynik:
-
-```text
-repo_root<TAB>...
-scanned<TAB>1
-added<TAB>1
-servers<TAB>1
-token_path<TAB>...
-```
-
-Przyklad:
-
-```bash
-python3 workspace.py tokens scan
-python3 workspace.py tokens scan --repo ~/dev/workspace/rv/series/inf/03
-```
-
-## `tokens read`
-
-Pokazuje zawartosc `tokens/tokens.json` w podziale na endpointy serwerow.
-
-Przelaczniki:
-
-- `--server ENDPOINT`
-  Ogranicza wynik do jednego endpointu.
-- `--show-secrets`
-  Pokazuje pelne wartosci tokenow zamiast maskowania.
-
-Typowy wynik:
-
-```text
-token_path<TAB>...
-endpoint<TAB>http://77.90.8.171:3001
-type<TAB>gitea
-scheme<TAB>http
-host<TAB>77.90.8.171
-port<TAB>3001
-users<TAB>1
-tokens<TAB>1
-user<TAB>u1
-token<TAB>t1<TAB>SE****23
-```
-
-Przyklad:
-
-```bash
-python3 workspace.py tokens read
-python3 workspace.py tokens read --server http://77.90.8.171:3001
-```
-
-## `tokens stats`
-
-Pokazuje statystyki endpointow z repo i `tokens.json`, a takze ich zgodnosc
-wzgledem siebie.
-
-Przelaczniki:
-
-- `--repo PATH`
-  Sciezka wewnatrz repo, z ktorego maja byc odczytane remote URL-e.
-- `--server ENDPOINT`
-  Ogranicza wynik do jednego endpointu.
-
-Typowy wynik:
-
-```text
-repo_root<TAB>...
-token_path<TAB>...
-repo_endpoints<TAB>1
-store_endpoints<TAB>1
-union_endpoints<TAB>1
-in_sync<TAB>0
-repo_only<TAB>0
-store_only<TAB>0
-repo_ahead<TAB>0
-store_ahead<TAB>1
-diverged<TAB>0
-
-endpoint<TAB>type<TAB>repo_remotes<TAB>repo_urls<TAB>repo_auth_urls<TAB>repo_plain_urls<TAB>repo_users<TAB>repo_tokens<TAB>store_users<TAB>store_tokens<TAB>repo_only_tokens<TAB>store_only_tokens<TAB>status
-http://77.90.8.171:3001<TAB>gitea<TAB>origin<TAB>1<TAB>0<TAB>1<TAB>0<TAB>0<TAB>1<TAB>1<TAB>0<TAB>1<TAB>store_ahead
-```
-
-Przyklad:
-
-```bash
-python3 workspace.py tokens stats --repo ~/dev/workspace/rv/series/inf/03
-```
-
-## `tokens write`
-
-Wpisuje dane z `tokens/tokens.json` do wybranego remota repo.
-
-Przelaczniki:
-
-- `--repo PATH`
-  Sciezka wewnatrz docelowego repo. Domyslnie biezacy katalog.
-- `--remote NAME`
-  Nazwa remota do aktualizacji lub utworzenia.
-- `--url URL`
-  URL remota, jesli remote jeszcze nie istnieje.
-- `--server ENDPOINT`
-  Endpoint serwera z `tokens.json`.
-- `--user NAME`
-  Uzytkownik z wybranego endpointu.
-- `--token-name NAME`
-  Nazwa tokena, na przyklad `t1`.
-- `--replace`
-  Nadpisuje inne dane auth juz wpisane w remote URL.
-- `--dry-run`
-  Pokazuje plan bez zapisu.
-
-Przyklad:
-
-```bash
-python3 workspace.py tokens write --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
-```
-
-## `tokens update`
-
-Uruchamia synchronizacje w zadanym kierunku.
-
-Przelaczniki:
-
-- `--from remotes`
-  Skanuje remote URL-e i zapisuje wynik do `tokens.json`.
-- `--from store`
-  Bierze dane z `tokens.json` i wpisuje je do remota repo.
-- `--repo PATH`
-  Sciezka wewnatrz repo.
-- `--remote NAME`
-  Wymagane dla `--from store`.
-- `--url URL`
-  Opcjonalny URL dla `--from store`.
-- `--server ENDPOINT`
-  Opcjonalny wybor endpointu dla `--from store`.
-- `--user NAME`
-  Opcjonalny wybor usera dla `--from store`.
-- `--token-name NAME`
-  Opcjonalny wybor tokena dla `--from store`.
-- `--replace`
-  Nadpisuje inne auth przy `--from store`.
-- `--dry-run`
-  Pokazuje plan bez zapisu przy `--from store`.
-
-Przyklady:
-
-```bash
-python3 workspace.py tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
-python3 workspace.py tokens update --from store --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
-```
-
-## `submission [series] [card]`
-
-Wylicza flow oddawania rozwiazan:
-
-- `r1` jako repo z materialem z `edu-inf`
-- `a1` jako repo odpowiedzi w `zsl-inf`
-- branch ucznia na podstawie jego nicku
-
-Nazwa repo odpowiedzi jest budowana z nazwy repo zrodlowego z `edu-inf`, klasy
-i daty:
-
-```text
-<repo_z_edu-inf>-<klasa>-<data>
-```
-
-Przyklad:
-
-```text
-lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
-```
-
-Argumenty pozycyjne:
-
-- `series`
-  Id serii albo pelny selector, na przyklad `inf` albo `inf/03`.
-- `card`
-  Numer karty, na przyklad `03`.
-
-Przelaczniki:
-
-- `--class NAME`
-  Id klasy, na przyklad `4i`.
-- `--nick NAME`
-  Nick ucznia. Domyslnie z niego powstaje nazwa brancha.
-- `--branch NAME`
-  Nadpisuje domyslna nazwe brancha.
-- `--date YYYY-MM-DD`
-  Data zajec uzywana w nazwie repo odpowiedzi. Domyslnie dzisiejsza.
-- `--source-url URL`
-  Nadpisuje URL repo zrodlowego. Bez tego launcher czyta `origin` z repo karty.
-- `--apply`
-  Dodaje albo aktualizuje remote `r1` i `a1` w repo karty.
-
-Typowy format wyjscia:
-
-```text
-selector<TAB>inf/03
-card_path<TAB>...
-source_repo<TAB>edu-inf/lab-rv32i-strlen-bss-data-stack
-source_remote<TAB>r1
-source_url<TAB>http://77.90.8.171:3001/edu-inf/lab-rv32i-strlen-bss-data-stack.git
-source_branch<TAB>deploy
-answer_remote<TAB>a1
-answer_repo<TAB>zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26
-answer_url<TAB>http://77.90.8.171:3001/zsl-inf/lab-rv32i-strlen-bss-data-stack-4i-2026-04-26.git
-student_branch<TAB>u1
-```
-
-Przyklady:
-
-```bash
-python3 workspace.py submission inf 03 --class 4i --nick u1
-python3 workspace.py submission inf 03 --class 4i --nick u1 --apply
-python3 workspace.py submission inf/03 --class 4i --nick u2 --date 2026-04-26
-```
-
-## `tmux-container [series] [card]`
-
-Tworzy nowa sesje `tmux` i uruchamia kontener w `pane 0`.
-
-Argumenty pozycyjne:
-
-- `series`
-  Id serii albo pelny selector, na przyklad `inf` albo `inf/03`.
-- `card`
-  Numer karty, na przyklad `03`.
-
-Przelaczniki:
-
-- `--session NAME`
-  Nadpisuje nazwe sesji `tmux`.
-- `--window NAME`
-  Nadpisuje nazwe okna `tmux`.
-- `--instance NAME`
-  Ustawia `RV_INSTANCE` dla wrappera `rv`.
-- `--attach`
-  Po utworzeniu sesji robi `tmux attach`.
-- `--dry-run`
-  Nie uruchamia `tmux`; wypisuje selector, sciezki i koncowa komende.
-
-Reguly wyboru karty:
-
-- `tmux-container inf 03` -> seria `inf`, karta `03`
-- `tmux-container inf/03` -> pelny selector
-- `tmux-container 03` -> domyslna seria + karta `03`
-- `tmux-container inf` -> seria `inf` + domyslna karta
-- bez argumentow -> domyslna seria i domyslna karta
-
-Przyklady:
-
-```bash
-python3 workspace.py tmux-container 03 --dry-run
-python3 workspace.py tmux-container inf 03 --session rv-inf03
-python3 workspace.py tmux-container inf/03 --attach
+./rvctl
+./workspace
+./wspace
 ```
diff --git a/rvctl b/rvctl
new file mode 100755
index 0000000..19a1e6b
--- /dev/null
+++ b/rvctl
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec python3 "$SCRIPT_DIR/workspace.py" "$@"
diff --git a/workspace b/workspace
new file mode 100755
index 0000000..49fee02
--- /dev/null
+++ b/workspace
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/rvctl" "$@"
diff --git a/workspace.py b/workspace.py
index 1b0cefd..7578ef5 100755
--- a/workspace.py
+++ b/workspace.py
@@ -1040,7 +1040,10 @@ def add_store_selection_options(parser: argparse.ArgumentParser) -> None:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(description="Workspace launcher for rv cards and tools.")
+    parser = argparse.ArgumentParser(
+        prog="rvctl",
+        description="rvctl for rv cards and tools.",
+    )
     parser.add_argument(
         "--config",
         default=Path(__file__).with_name("workspace.json"),
diff --git a/wspace b/wspace
new file mode 100755
index 0000000..49fee02
--- /dev/null
+++ b/wspace
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/rvctl" "$@"