From 73a362d89854c0f2d84e247b8ee3f76c8f1c8190 Mon Sep 17 00:00:00 2001
From: mpabi <mpabi@mpabi.pl>
Date: Wed, 29 Apr 2026 01:31:17 +0200
Subject: [PATCH] Document workspace bootstrap layout

---
 README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 104 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index c590e0e..e7ef963 100644
--- a/README.md
+++ b/README.md
@@ -52,32 +52,119 @@ Sciezki i domyslne ustawienia sa trzymane w `workspace.json`.
 
 ## Model katalogow
 
-Repozytoria zrodlowe trzymamy poza workspace:
-
-```bash
-~/dev/edu/repos/rv
-```
-
-Workspace sluzy do klonow roboczych, cwiczen, tokenow i socketow:
+Podstawowym miejscem pracy uzytkownika jest workspace:
 
 ```bash
 ~/dev/workspace/rv
 ```
 
-Typowy uklad:
+Minimalny uklad po starcie zawiera launcher, katalog tokenow i katalog na karty:
 
 ```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>
-~/dev/workspace/rv/tokens/tokens.json
+~/dev/workspace/rv
+|-- tools
+|   `-- rv-launcher
+|-- tokens
+`-- series
 ```
 
-`rvctl` pracuje na kartach z `series_root` w workspace. Repo zrodlowe w
-`~/dev/edu/repos/rv` sa punktem odniesienia i fallbackiem dla narzedzi.
+Sa dwie drogi startu.
+
+### Bez `tokens.json`
+
+Jesli nie masz jeszcze pliku z tokenem albo tokenami, zacznij od pustego repo
+launchera i remota z tokenem:
+
+```bash
+mkdir -p ~/dev/workspace/rv/tools/rv-launcher
+cd ~/dev/workspace/rv/tools/rv-launcher
+git init
+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
+```
+
+Potem wczytaj token z remota do lokalnego store:
+
+```bash
+./rvctl tokens sync remote r1
+./rvctl tokens update r1
+./rvctl tokens compare
+```
+
+Po tym kroku workspace ma juz lokalny store:
+
+```text
+~/dev/workspace/rv
+|-- tools
+|   `-- rv-launcher
+|-- tokens
+|   `-- tokens.json
+`-- series
+```
+
+### Z `tokens.json`
+
+Jesli masz gotowy plik `tokens.json`, zacznij od skopiowania go do workspace:
+
+```bash
+mkdir -p ~/dev/workspace/rv/tokens
+cp tokens.json ~/dev/workspace/rv/tokens/tokens.json
+chmod 600 ~/dev/workspace/rv/tokens/tokens.json
+```
+
+Nastepnie pobierz albo przygotuj `rv-launcher` w:
+
+```text
+~/dev/workspace/rv/tools/rv-launcher
+```
+
+Po wejsciu do repo launchera sprawdz store tokenow:
+
+```bash
+./rvctl tokens list store
+./rvctl tokens compare
+./rvctl tokens update r1
+```
+
+### Po pobraniu kart pracy
+
+Karty trafiaja do `series` w workspace:
+
+```text
+~/dev/workspace/rv
+|-- tools
+|   `-- rv-launcher
+|-- tokens
+|   `-- tokens.json
+`-- series
+    `-- inf
+        `-- 03
+```
+
+`rvctl` pracuje na kartach z `series_root`, czyli na katalogu
+`~/dev/workspace/rv/series`.
+
+### Po uruchomieniu srodowiska kontenerowego
+
+Repo `rv32i-hazard3-env` jest potrzebne dopiero przy uruchamianiu srodowiska
+kontenerowego. Wtedy pojawia sie pod `tools`:
+
+```text
+~/dev/workspace/rv
+|-- tools
+|   |-- rv-launcher
+|   `-- rv32i-hazard3-env
+|-- tokens
+|   `-- tokens.json
+`-- series
+    `-- inf
+        `-- 03
+```
+
+Repozytoria zrodlowe poza workspace, na przyklad `~/dev/edu/repos/rv`, sa
+zapleczem dla autora materialow albo fallbackiem dla narzedzi. Nie sa wymagane
+do zwyklej pracy w workspace.
 
 ## Szybki start