From 758e4871fbd0cae708ee04f2d886643475622350 Mon Sep 17 00:00:00 2001
From: mpabi <mpabi@mpabi.pl>
Date: Sun, 26 Apr 2026 19:55:15 +0200
Subject: [PATCH] Clarify token scan pairs repo and store

---
 README.md     |  1 +
 doc/rvctl.md  |  7 ++++++-
 doc/tokens.md | 11 +++++++++--
 rvctl.py      |  6 +++---
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 7bac03f..0183f67 100644
--- a/README.md
+++ b/README.md
@@ -158,6 +158,7 @@ Podstawowe komendy tokenow:
 
 `tokens scan` wypisuje waska tabele. Dla jednego endpointu zobaczysz
 osobny wiersz `source=repo` oraz osobny wiersz `source=tokens.json`.
+Ten sam numer `item` laczy oba wiersze w pare dla jednego endpointu.
 
 ## Fetch i switch
 
diff --git a/doc/rvctl.md b/doc/rvctl.md
index 0afa228..89dd99c 100644
--- a/doc/rvctl.md
+++ b/doc/rvctl.md
@@ -291,7 +291,8 @@ Przyklady:
 
 ## `tokens scan`
 
-Skanuje remote URL-e w repo i zapisuje znalezione dane do `tokens/tokens.json`.
+Skanuje remote URL-e w repo oraz lokalny `tokens.json`, laczy wpisy w pary po
+endpoincie i pokazuje, gdzie przechowywany jest token.
 
 Przelaczniki:
 
@@ -315,6 +316,10 @@ w wierszu `repo` wartosci `kind=plain` i `result=no_credentials`. Jezeli
 ten sam endpoint istnieje w `tokens.json`, drugi wiersz tego samego `item`
 pokaze `source=tokens.json`, `token=t1` i `result=present`.
 
+Ten sam numer `item` oznacza jedna pare logiczna dla jednego endpointu. Wiersz
+`source=repo` pokazuje stan remote, a wiersz `source=tokens.json` pokazuje stan
+lokalnego store.
+
 Przyklad:
 
 ```bash
diff --git a/doc/tokens.md b/doc/tokens.md
index 86ae244..ec96b27 100644
--- a/doc/tokens.md
+++ b/doc/tokens.md
@@ -52,6 +52,8 @@ To pozwala odroznic:
 Przy `tokens scan` launcher:
 
 - czyta wszystkie remote URL-e w repo
+- czyta `tokens.json`
+- laczy remote i store w pary po endpoincie serwera
 - wybiera tylko `http` i `https`
 - jesli URL ma `LOGIN:TOKEN@...`, wyciaga login i token
 - zapisuje je pod odpowiednim endpointem w `tokens.json`
@@ -73,15 +75,17 @@ Przy skanowaniu launcher zapisuje tez metadane serwera:
 
 ### `tokens scan`
 
-Kierunek:
+Zrodla:
 
 ```text
-repo -> tokens.json
+repo + tokens.json
 ```
 
 Dzialanie:
 
 - skanuje remote URL-e w repo
+- czyta wpisy z `tokens.json`
+- laczy oba zrodla po endpoincie serwera
 - zapisuje znalezione tokeny do `tokens.json`
 - zapisuje je per endpoint serwera
 - wypisuje domyslnie tylko waska tabele `items`
@@ -93,6 +97,9 @@ moze miec dwa wiersze:
 - `source=repo` - stan remote URL-i w repo
 - `source=tokens.json` - stan lokalnego store tokenow
 
+Dzieki temu widac, dla ktorego endpointu token jest w remote, a dla ktorego
+jest tylko w `tokens.json`.
+
 Kolumny w tabeli `items`:
 
 - `item` - numer porownywanego endpointu
diff --git a/rvctl.py b/rvctl.py
index 3b96785..7b2eb2a 100644
--- a/rvctl.py
+++ b/rvctl.py
@@ -1332,7 +1332,7 @@ def print_main_overview(config_path: Path) -> None:
     print_table(
         ["step", "command", "result"],
         [
-            ["1", "./rvctl tokens scan", "read credentials from remotes if present"],
+            ["1", "./rvctl tokens scan", "pair repo remotes with tokens.json entries"],
             ["2", "./rvctl list-series", "choose a series"],
             ["3", "./rvctl list-cards inf", "choose a card"],
             ["4", "./rvctl tmux-container inf <card>", "start the working container"],
@@ -1359,7 +1359,7 @@ def print_tokens_overview() -> None:
     print_table(
         ["command", "common options", "direction", "purpose"],
         [
-            ["scan", "[--repo PATH]", "repo -> tokens.json", "scan remotes and store credentials found in URLs"],
+            ["scan", "[--repo PATH]", "repo + tokens.json", "pair endpoints and show where token refs are stored"],
             ["read", "[--server ENDPOINT]", "tokens.json", "show servers, users and token names"],
             ["stats", "[--repo PATH]", "repo + tokens.json", "compare remote URLs with local token store"],
             ["write", "--remote R [--replace]", "tokens.json -> repo", "write selected token into a remote URL"],
@@ -1467,7 +1467,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     tokens_scan_parser = tokens_subparsers.add_parser(
         "scan",
-        help="Scan remote URLs in a git repo and save discovered credentials into tokens.json.",
+        help="Scan repo remotes and tokens.json, then print paired endpoint rows.",
     )
     add_repo_option(tokens_scan_parser)
     tokens_scan_parser.add_argument("--verbose", action="store_true", help="Print context and scan counters before item rows.")