From f121ef232f371f7ef59623cee2accb98a0cc3a97 Mon Sep 17 00:00:00 2001
From: mpabi <mpabi@mpabi.pl>
Date: Mon, 27 Apr 2026 21:10:23 +0200
Subject: [PATCH] Rework token workflow documentation

---
 doc/tokens.md | 578 +++++++++++++++++++++++++++-----------------------
 1 file changed, 311 insertions(+), 267 deletions(-)

diff --git a/doc/tokens.md b/doc/tokens.md
index c1cb18c..3867ca2 100644
--- a/doc/tokens.md
+++ b/doc/tokens.md
@@ -1,134 +1,268 @@
 # Tokens
 
-Ten dokument opisuje model tokenow uzywany przez `rvctl`.
+Ten dokument opisuje praktyczna obsluge tokenow Gitea w `rvctl`.
 
-## Zasada
+`rvctl` traktuje `tokens.json` jako lokalny store tokenow. Rekord tokena zawiera
+sekret, endpoint serwera, login uzytkownika oraz docelowe `org/repo`. Git remote
+jest tylko miejscem, z ktorego token mozna jednorazowo wczytac albo do ktorego
+mozna go tymczasowo wpisac, gdy Git ma wykonac `fetch` albo `push`.
 
-`tokens.json` synchronizujemy z repo `rv-launcher`. Remoty kart pracy i repo
-odpowiedzi sa generowane jako pochodne konfiguracji launchera, a nie jako osobne
-zrodla prawdy dla tokenow.
+Operacyjnie sa dwa zrodla stanu:
 
-W praktyce oznacza to:
+- `tokens.json` - lokalny store sekretow i metadanych API
+- `.git/config` - konfiguracja git remotes w wybranym repo
 
-- `r1` w repo `rv-launcher` jest miejscem startowym do pobrania tokena z remote
-- `tokens.json` jest lokalnym store sekretow i metadanych tokenow
-- karty pracy dostaja remote na podstawie ustawien launchera i komend typu `submission`
-- `tokens scan` i `tokens compare` sa read-only i niczego nie zapisuja
+`rv-launcher` jest domyslnym repo, na ktorym dzialaja komendy tokenow bez
+`--repo`. Dla kart pracy albo innych repo trzeba podac `--repo PATH`.
 
-## Zrodlo Prawdy
+## Szybki Flow
 
-Sa dwa miejsca, ktore `rvctl` potrafi porownac:
+Startujemy od git remota z tokenem w URL-u:
 
-- git remote w repo `rv-launcher`, np. `http://u1:SECRET@host/org/repo.git`
-- lokalny plik `~/dev/workspace/rv/tokens/tokens.json`
-
-Kierunek jest jawny:
-
-- `tokens list store` pokazuje tylko rekordy w `tokens.json`
-- `tokens list remote` pokazuje tylko git remotes
-- `tokens sync remote r1` czyta git remote `r1` i zapisuje rekord do `tokens.json`
-- `tokens sync store r1` czyta `tokens.json` i zapisuje auth do git remote `r1`
-- `tokens update r1` nie synchronizuje sekretu, tylko pobiera metadane z API
-- `tokens remove store r1` usuwa rekord z `tokens.json`
-- `tokens remove remote r1` usuwa git remote
-- `tokens remove both r1` usuwa rekord ze store i git remote
-
-## Format `tokens.json`
-
-Aktualny format to `version: 3`. Glownym rekordem jest jeden remote-token.
-Pole `id` jest obowiazkowe i musi byc takie samo jak nazwa git remote, np.
-`r1` albo `r1a`.
-
-```json
-{
-  "version": 3,
-  "tokens": [
-    {
-      "id": "r1",
-      "value": "SECRET",
-      "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",
-      "valid": "forever",
-      "scope": {
-        "a": "-",
-        "A": "-",
-        "i": "-",
-        "m": "-",
-        "n": "-",
-        "o": "-",
-        "p": "-",
-        "r": "w",
-        "u": "-"
-      },
-      "org_perm": {
-        "o": "+",
-        "a": "+",
-        "w": "+",
-        "r": "+",
-        "c": "+"
-      },
-      "repo_perm": {
-        "o": "+",
-        "a": "+",
-        "w": "+",
-        "r": "+"
-      }
-    }
-  ]
-}
+```bash
+git remote add r1 http://u1:TOKEN@77.90.8.171:3001/edu-tools/rv-launcher.git
 ```
 
-Pelny schemat jest w `doc/tokens.schema.json`.
+Sprawdzamy, co jest zapisane w remote i store:
 
-## Pola
+```bash
+./rvctl tokens list remote
+./rvctl tokens list store
+./rvctl tokens list both
+```
 
-Pola synchronizowane z git remote:
+Kopiujemy token z remota do `tokens.json`:
 
-- `id` - nazwa git remote, np. `r1`; to jest klucz rekordu
-- `server.endpoint` - endpoint serwera, np. `http://77.90.8.171:3001`
-- `server.type` - typ serwera, np. `gitea`, `github`, `gitlab`, `unknown`
-- `user` - login z URL-a, czyli lewa strona `http://u1:SECRET@...`
-- `value` - sekret tokena
-- `org` - organizacja z URL-a
-- `repo` - repo z URL-a
+```bash
+./rvctl tokens sync remote r1
+```
 
-Pola pobierane z API przez `tokens update r1`:
+Pobieramy z API metadane tokena:
 
-- `valid` - `forever`, data wygasniecia, `invalid`, `?` albo `!`
-- `scope` - mapa scope tokena
-- `org_perm` - mapa praw uzytkownika w organizacji
-- `repo_perm` - mapa praw uzytkownika w repo
+```bash
+./rvctl tokens update r1
+```
+
+Sprawdzamy zgodnosc remote i store:
+
+```bash
+./rvctl tokens compare
+```
+
+Po poprawnej synchronizacji `compare` powinien pokazac `*` przy `r1`.
+
+## Dwa Zrodla
+
+`rvctl` rozroznia dwa miejsca:
+
+- git remote w repo, np. `http://u1:SECRET@host/org/repo.git`
+- lokalny store `~/dev/workspace/rv/tokens/tokens.json`
+
+Kierunki sa jawne:
+
+- `sync remote r1` czyta git remote i zapisuje rekord do `tokens.json`
+- `sync store r1` czyta `tokens.json` i zapisuje auth do git remota
+- `update r1` nie synchronizuje sekretu, tylko odswieza metadane z API
+- `remove remote r1` usuwa git remote
+- `remove store r1` usuwa rekord z `tokens.json`
+
+## Listowanie
+
+`list` pokazuje zrodla bez porownywania:
+
+```bash
+./rvctl tokens list store
+./rvctl tokens list remote
+./rvctl tokens list both
+```
+
+Znaczenie:
+
+- `store` - rekordy zapisane w `tokens.json`
+- `remote` - git remotes zapisane w `.git/config`
+- `both` - oba zrodla jako osobne wiersze
+
+Dla innego repo podaj `--repo`:
+
+```bash
+./rvctl tokens list remote --repo ~/dev/workspace/rv/series/inf/03
+```
+
+## Synchronizacja
+
+### Remote -> Store
+
+Uzyj, gdy token jest w git remote i chcesz go zapisac w store:
+
+```bash
+./rvctl tokens sync remote r1
+```
+
+Ta komenda kopiuje sekret, usera, endpoint, org i repo z URL-a remota do
+`tokens.json`. Nie pyta API o uprawnienia.
+
+### Store -> Remote
+
+Uzyj, gdy token jest juz w `tokens.json`, a chcesz utworzyc albo odswiezyc git
+remote:
+
+```bash
+./rvctl tokens sync store r1
+```
+
+Jesli remote `r1` nie istnieje, `rvctl` buduje URL z pol `server.endpoint`,
+`org` i `repo` w `tokens.json`, na przyklad:
+
+```text
+http://77.90.8.171:3001/edu-tools/rv-launcher.git
+```
+
+Opcjonalnie mozna podac URL recznie:
+
+```bash
+./rvctl tokens sync store r1 --url http://77.90.8.171:3001/edu-tools/rv-launcher.git
+```
+
+Jesli remote ma juz inne credentials, uzyj:
+
+```bash
+./rvctl tokens sync store r1 --replace
+```
+
+## Aktualizacja Metadanych
+
+Po zapisaniu tokena w store odswiez jego metadane z API:
+
+```bash
+./rvctl tokens update r1
+```
+
+`update` zapisuje w `tokens.json`:
+
+- `valid`
+- `scope`
+- `org_perm`
+- `repo_perm`
+
+Ta komenda nie zmienia git remota i nie kopiuje sekretu.
 
 ## Porownanie
 
-`tokens compare` porownuje git remote i `tokens.json` po:
+`compare` sprawdza zgodnosc store i remote:
 
-```text
-server.endpoint + id + user + value + org + repo
+```bash
+./rvctl tokens compare
 ```
 
-Znacznik w kolumnie `token_ref`:
+Marker w kolumnie `token_ref`:
 
-- `*` - remote i `tokens.json` sa zgodne
-- `R` - wpis istnieje tylko w git remote
-- `S` - wpis istnieje tylko w `tokens.json`
-- `!` - wpis jest sparowany, ale token jest `invalid` albo ma blad sprawdzania
+- `*` - store i remote sa zgodne
+- `S` - token jest tylko w store
+- `R` - token jest tylko w remote
+- `!` - wpis jest sparowany, ale token jest `invalid` albo wystapil blad API
 
-Dla niesparowanych wpisow `rvctl` pokazuje `?` w kolumnach `valid`, `scope`,
-`org` i `repo`, bo metadane API sa wiarygodne dopiero dla rekordu ze store.
+Gdy marker to `S`, token nie jest bledny. To znaczy tylko, ze nie ma
+odpowiadajacego git remota.
+
+## Store-only
+
+Po pierwszej konfiguracji wygodny tryb pracy to trzymanie tokena tylko w
+`tokens.json`.
+
+```bash
+./rvctl tokens remove remote r1
+./rvctl tokens list store
+./rvctl tokens compare
+```
+
+Wtedy `compare` pokazuje `S`, a `list store` nadal pokazuje znane metadane
+tokenu. Gdy trzeba wykonac operacje git przez remote, odtworz remote:
+
+```bash
+./rvctl tokens sync store r1
+```
+
+Po operacji mozna go znowu usunac:
+
+```bash
+./rvctl tokens remove remote r1
+```
+
+## Usuwanie
+
+Usuwaj tylko to miejsce, ktore naprawde chcesz wyczyscic:
+
+```bash
+./rvctl tokens remove remote r1
+./rvctl tokens remove store r1
+./rvctl tokens remove both r1
+```
+
+Znaczenie:
+
+- `remove remote` usuwa git remote i sekret z `.git/config`, ale zostawia store
+- `remove store` usuwa rekord z `tokens.json`, ale nie dotyka git remota
+- `remove both` usuwa oba miejsca
+
+## Inne Repo
+
+Domyslnie komendy tokenow pracuja na repo zawierajacym `rvctl`. Dla kart pracy
+albo innych repo podaj `--repo`.
+
+```bash
+./rvctl tokens list remote --repo ~/dev/workspace/rv/series/inf/03
+./rvctl tokens compare --repo ~/dev/workspace/rv/series/inf/03
+./rvctl tokens sync store r1 --repo ~/dev/workspace/rv/series/inf/03
+```
+
+Store tokenow nadal pozostaje jeden:
+
+```text
+~/dev/workspace/rv/tokens/tokens.json
+```
+
+## Pozostale Komendy
+
+### `tokens read`
+
+Pokazuje zawartosc `tokens.json`.
+
+```bash
+./rvctl tokens read
+./rvctl tokens read --server http://77.90.8.171:3001
+./rvctl tokens read --show-secrets
+```
+
+### `tokens add`
+
+Dodaje szkielet rekordu do `tokens.json`. `REMOTE_ID` musi odpowiadac nazwie
+git remote. Przelaczniki sa opcjonalne; jesli ich nie podasz, `rvctl` zapisuje
+puste wartosci do pozniejszego uzupelnienia. Wyjatkiem jest `server`, ktory
+domyslnie pochodzi z `workspace.json`.
+
+```bash
+./rvctl tokens add r1
+./rvctl tokens add r1 --server http://77.90.8.171:3001 --user u1 --org edu-tools --repo rv-launcher
+```
+
+Najczesciej pusty szkielet ma sens wtedy, gdy chcesz recznie wpisac token w
+`tokens.json`. `sync store r1` nie uzyje pustego tokena. Najpierw trzeba
+uzupelnic co najmniej `value` i `user`. Jesli remote ma byc tworzony bez `--url`,
+potrzebne sa tez `org` i `repo`.
+
+### `tokens stats`
+
+Pokazuje kontekst, tabele `tokens` i podsumowanie statusow endpointow.
+
+```bash
+./rvctl tokens stats
+./rvctl tokens stats --repo ~/dev/workspace/rv/tools/rv-launcher
+```
 
 ## Uprawnienia
 
-W `tokens.json` uprawnienia sa zapisane jako mapy klucz-wartosc. W tabeli CLI sa
-pokazywane jako zwarte maski.
+W `tokens.json` uprawnienia sa zapisane jako mapy klucz-wartosc. W tabelach CLI
+sa pokazywane jako zwarte maski.
 
 Naglowki masek:
 
@@ -182,173 +316,83 @@ Wartosci w `org_perm` i `repo_perm`:
 - `?` - nie wczytano
 - `!` - blad wczytania
 
-## Typowy Flow
+## Model Danych
 
-W repo `rv-launcher`:
+`tokens.json` ma format `version: 3`. Glownym rekordem jest jeden remote-token.
+Pole `id` jest obowiazkowe i musi byc takie samo jak nazwa git remote, np.
+`r1` albo `r1a`.
 
-```bash
-git remote add r1 http://u1:TOKEN@77.90.8.171:3001/edu-tools/rv-launcher.git
-./rvctl tokens scan
-./rvctl tokens compare
-./rvctl tokens sync remote r1
-./rvctl tokens update r1
-./rvctl tokens compare
+Pola synchronizowane z git remote:
+
+- `id` - nazwa git remote, np. `r1`
+- `server.endpoint` - endpoint serwera, np. `http://77.90.8.171:3001`
+- `server.type` - typ serwera, np. `gitea`, `github`, `gitlab`, `unknown`
+- `user` - login z URL-a, czyli lewa strona `http://u1:SECRET@...`
+- `value` - sekret tokena
+- `org` - organizacja z URL-a
+- `repo` - repo z URL-a
+
+Pola pobierane z API przez `tokens update r1`:
+
+- `valid` - `forever`, data wygasniecia, `invalid`, `?` albo `!`
+- `scope` - mapa scope tokena
+- `org_perm` - mapa praw uzytkownika w organizacji
+- `repo_perm` - mapa praw uzytkownika w repo
+
+Minimalny przyklad:
+
+```json
+{
+  "version": 3,
+  "tokens": [
+    {
+      "id": "r1",
+      "value": "SECRET",
+      "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"
+    }
+  ]
+}
 ```
 
-Po `sync remote` sekret jest w `tokens.json`. Po `update` `rvctl` dopisuje
-`valid`, `scope`, `org_perm` i `repo_perm`.
+Przyklad po `tokens update r1` moze dodatkowo zawierac:
 
-Jesli chcesz tylko zobaczyc jedno zrodlo, bez porownywania:
-
-```bash
-./rvctl tokens list remote
-./rvctl tokens list store
-./rvctl tokens list both
+```json
+{
+  "valid": "forever",
+  "scope": {
+    "a": "w",
+    "A": "w",
+    "i": "w",
+    "m": "w",
+    "n": "w",
+    "o": "w",
+    "p": "w",
+    "r": "w",
+    "u": "w"
+  },
+  "org_perm": {
+    "o": "+",
+    "a": "+",
+    "w": "+",
+    "r": "+",
+    "c": "+"
+  },
+  "repo_perm": {
+    "o": "+",
+    "a": "+",
+    "w": "+",
+    "r": "+"
+  }
+}
 ```
 
-Jesli token ma zostac tylko w `tokens.json`, usun git remote:
-
-```bash
-./rvctl tokens remove remote r1
-```
-
-Jesli trzeba ponownie utworzyc remote z sekretem ze store:
-
-```bash
-./rvctl tokens sync store r1
-```
-
-## Komendy
-
-### `tokens scan`
-
-Read-only. Czyta git remotes i wypisuje diagnostyczna tabele URL-i:
-`auth`, `plain` i `unsupported`. Nie porownuje ich z `tokens.json`. Bez
-`--repo` czyta repo zawierajace `rvctl`.
-
-```bash
-./rvctl tokens scan
-./rvctl tokens scan --repo ~/dev/workspace/rv/tools/rv-launcher
-```
-
-### `tokens compare`
-
-Read-only. Czyta git remote i `tokens.json`, laczy wpisy w pary i wypisuje
-tabele `tokens`. Nie tworzy i nie modyfikuje `tokens.json`. Bez `--repo`
-czyta repo zawierajace `rvctl`.
-
-```bash
-./rvctl tokens compare
-./rvctl tokens compare --repo ~/dev/workspace/rv/tools/rv-launcher
-```
-
-### `tokens list store|remote|both`
-
-Read-only. Wypisuje jedno zrodlo bez porownywania go z drugim. To odroznia
-`list` od `compare`: `list` odpowiada na pytanie "co jest zapisane tutaj", a
-`compare` odpowiada na pytanie "czy store i remote sa zgodne".
-
-```bash
-./rvctl tokens list store
-./rvctl tokens list remote
-./rvctl tokens list both
-./rvctl tokens list remote --repo ~/dev/workspace/rv/tools/rv-launcher
-```
-
-Przelaczniki:
-
-- `--repo PATH` - repo, z ktorego listowane sa git remotes; bez tej opcji uzywane jest repo zawierajace `rvctl`
-- `--server ENDPOINT` - ogranicza wynik do jednego endpointu
-
-### `tokens sync remote REMOTE_ID`
-
-Kopiuje dane dostepowe z git remote do `tokens.json`. Nie pobiera metadanych z
-API. Bez `--repo` czyta repo zawierajace `rvctl`.
-
-```bash
-./rvctl tokens sync remote r1
-./rvctl tokens sync remote r1 --repo ~/dev/workspace/rv/tools/rv-launcher
-```
-
-### `tokens update REMOTE_ID`
-
-Pobiera z API metadane dla rekordu `REMOTE_ID` zapisanego w `tokens.json`.
-Nie zmienia git remote URL-a i nie kopiuje sekretu z remote.
-
-```bash
-./rvctl tokens update r1
-./rvctl tokens update r1 --dry-run
-```
-
-### `tokens sync store REMOTE_ID`
-
-Zapisuje dane z rekordu `REMOTE_ID` w `tokens.json` do git remote o tej samej
-nazwie. Jesli remote jeszcze nie istnieje, URL jest budowany z pol
-`server.endpoint`, `org` i `repo` w `tokens.json`. Bez `--repo` zapisuje do repo
-zawierajacego `rvctl`.
-
-```bash
-./rvctl tokens sync store r1
-./rvctl tokens sync store r1 --replace
-```
-
-### `tokens remove store|remote|both REMOTE_ID`
-
-Usuwa rekord ze store, git remote albo oba miejsca. Bez `--repo` operacje
-`remote` i `both` dzialaja na repo zawierajacym `rvctl`.
-
-```bash
-./rvctl tokens remove store r1
-./rvctl tokens remove remote r1
-./rvctl tokens remove both r1
-```
-
-Przelaczniki:
-
-- `--server ENDPOINT` - rozroznia rekord w `tokens.json`, jezeli ten sam `id` wystepuje dla wielu serwerow
-- `--repo PATH` - repo, z ktorego usuwany jest git remote
-- `--dry-run` - pokazuje plan bez usuwania
-
-### `tokens read`
-
-Pokazuje zawartosc `tokens.json`.
-
-```bash
-./rvctl tokens read
-./rvctl tokens read --server http://77.90.8.171:3001
-./rvctl tokens read --show-secrets
-```
-
-### `tokens add`
-
-Dodaje pusty szkielet rekordu do `tokens.json`. `REMOTE_ID` musi odpowiadac
-nazwie git remote.
-
-```bash
-./rvctl tokens add r1
-./rvctl tokens add r1 --server http://77.90.8.171:3001 --user u1 --org edu-tools --repo rv-launcher
-```
-
-`tokens sync store r1` nie uzyje pustego tokena. Najpierw trzeba uzupelnic
-`value` i `user`.
-
-### `tokens stats`
-
-Pokazuje kontekst, tabele `tokens` i podsumowanie statusow endpointow. Bez
-`--repo` czyta repo zawierajace `rvctl`.
-
-```bash
-./rvctl tokens stats
-./rvctl tokens stats --repo ~/dev/workspace/rv/tools/rv-launcher
-```
-
-### Komendy zgodnosci
-
-Stare komendy nadal dzialaja, ale w nowych instrukcjach preferujemy jawne
-`sync remote`, `sync store` i `update REMOTE_ID`.
-
-```bash
-./rvctl tokens update --from remotes --repo PATH
-./rvctl tokens update --from store --repo PATH --remote r1 --server http://77.90.8.171:3001
-./rvctl tokens write --repo PATH --remote r1 --server http://77.90.8.171:3001
-```
+Pelny schemat pliku jest w `doc/tokens.schema.json`.