robisie 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Historia zmian klienta / Client changelog
2
2
 
3
+ ## 0.1.3 (2026-11-04)
4
+
5
+ Wydanie poprawek dokumentacji i pomocy CLI. / Documentation and CLI help patch release.
6
+
7
+ - Przewodniki pierwszej instalacji PL/EN po zimnym teście E4 wyjaśniają wybór klucza worker, ponowną instalację z zachowaniem manifestu oraz wczytanie klucza przed przywróceniem tgz. / Following the E4 cold test, PL/EN first-install guides clarify worker key selection, reinstallation preserving the manifest and key loading before tgz restore.
8
+ - Pomoc `doctor --engine-config` opisuje kontrolę offline struktury konfiguracji i przypisań ról wykonania, jej ograniczenia oraz ścieżki do lokalnych przewodników. / Help for `doctor --engine-config` describes offline checks of configuration structure and execution role assignments, their limits and paths to local guides.
9
+ - Testy dokumentacji wykonują polecenia instalacji, aktualizacji i przywracania, sprawdzając błędne pliki klucza, ochronę manifestów i brak ujawnienia klucza; test pomocy CLI sprawdza opis walidacji offline. / Documentation tests execute install, update and restore commands, checking invalid key files, manifest preservation and absence of key disclosure; a CLI help test checks the offline validation description.
10
+
3
11
  ## 0.1.2 (2026-11-03)
4
12
 
5
13
  Wydanie poprawek klienta i dokumentacji. / Client and documentation patch release.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Przewodniki: [PL — konto → odbiór → odinstalowanie](docs/README.md) · [EN — account → acceptance → uninstall](docs/README.en.md). Przygotuj Node.js 20+, npm, program jednego dostawcy AI oraz pusty katalog; nie potrzebujesz strony ani własnego pliku `package.json` — utworzy go poniższy krok Node.js przed instalacją. Zacznij od konta i projektu w panelu. Projekt w panelu i katalog na dysku to osobne rzeczy; CEO wymaga dokładnie jednego projektu z discovery.
4
4
 
5
- Konto i klucz są potrzebne do init i pracy ról. Osobno `npx robisie doctor --engine-config ./robisie.config.json` sprawdza offline tylko strukturę: nie potwierdza UUID projektu, repo, modeli ani uruchomienia dostawców. Lokalne przewodniki są w `node_modules/robisie/docs/`.
5
+ Konto i klucz są potrzebne do init i pracy ról. Osobne wejście to walidacja offline, gdy CLI jest dostępne: nie sprawdza instalacji, nie uruchamia dostawców i nie wymaga podawania UUID projektu. Osobno `npx robisie doctor --engine-config ./robisie.config.json` sprawdza offline tylko strukturę: nie potwierdza UUID projektu, repo, modeli ani uruchomienia dostawców. Lokalne przewodniki są w `node_modules/robisie/docs/`.
6
6
 
7
7
  ## Przed init — konto i pierwszy projekt
8
8
 
@@ -14,7 +14,9 @@ Jeśli trasa przekierowała na /dashboard bez Planera, znajdź „Zacznij od pie
14
14
 
15
15
  ## Init — połącz agenta
16
16
 
17
- Człowiek generuje klucz worker z etykietą w https://robisie.app/dashboard/connect i podaje go poza rozmową do ukrytego pytania init, nigdy do czatu, argumentu polecenia ani historii powłoki. W zsh/bash usuń stary ENV, a po udanym init wczytaj zapisany klucz do bieżącej powłoki bez wyświetlania go — init nie ustawia jej środowiska. Dla nowej instalacji z Claude wejdź do wybranego pustego katalogu (zastąp przykładową ścieżkę poniżej). Poniższy krok Node.js tworzy lokalny `package.json` niezależnie od nazwy katalogu, także ze spacjami i polskimi znakami. Manifest ustala katalog instalacji także pod przodkiem z `node_modules`. Jeśli ścieżka `package.json` już istnieje (również jako link), krok odmawia zapisu; niczego nie nadpisuje. Błąd wejścia do katalogu lub utworzenia manifestu zatrzymuje dalszy blok:
17
+ Agent może sam założyć konto i wygenerować klucz na własnym koncie, w granicach zgody jego właściciela. Logowanie lub inny chroniony krok może wymagać potwierdzenia człowieka; po nim kontynuuj. Cudza otwarta sesja nie uprawnia do korzystania z jej konta ani klucza. Sekret pozostaje poza rozmową i historią poleceń; jeśli dostępne narzędzia nie pozwalają przekazać go bezpiecznie, człowiek wpisuje go w ukrytym pytaniu init.
18
+
19
+ Jawnie wybierz `worker` w Connect; kolejne klucze mają domyślnie `observer`, który tylko czyta. Człowiek generuje klucz worker z etykietą w https://robisie.app/dashboard/connect i podaje go poza rozmową do ukrytego pytania init, nigdy do czatu, argumentu polecenia ani historii powłoki. W zsh/bash usuń stary ENV, a po udanym init wczytaj zapisany klucz do bieżącej powłoki bez wyświetlania go — init nie ustawia jej środowiska. Dla nowej instalacji z Claude wejdź do wybranego pustego katalogu (zastąp przykładową ścieżkę poniżej). Poniższy krok Node.js tworzy lokalny `package.json` niezależnie od nazwy katalogu, także ze spacjami i polskimi znakami. Manifest ustala katalog instalacji także pod przodkiem z `node_modules`. Jeśli ścieżka `package.json` już istnieje (również jako link), krok odmawia zapisu; niczego nie nadpisuje. EEXIST oznacza istniejącą ścieżkę: wybierz drogę istniejącego projektu poniżej; link/katalog wymaga wyjaśnienia. Błąd wejścia do katalogu lub utworzenia manifestu zatrzymuje dalszy blok:
18
20
 
19
21
  ```sh
20
22
  cd "/ścieżka/do/pustego katalogu" &&
@@ -25,19 +27,63 @@ node -e 'try {
25
27
  process.exit(1);
26
28
  }' &&
27
29
  {
30
+ set +x
28
31
  npm i robisie &&
29
32
  unset ROBISIE_KEY &&
30
33
  npx robisie init --agent claude &&
31
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
32
- ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")" &&
33
- export ROBISIE_KEY &&
34
+ {
35
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
36
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
37
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
38
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
39
+ [ -n "$ROBISIE_KEY" ]; then
40
+ export ROBISIE_KEY
41
+ else
42
+ printf '%s\n' 'Nie można wczytać niepustego, zwykłego, czytelnego pliku klucza robisie.' 'Następny krok: sprawdź lokalnie plik klucza i jego odczyt; wyjaśnij link/katalog bez nadpisywania danych. Przy braku lub unieważnieniu klucza wróć do Connect i init z ukrytym pytaniem. Nie wklejaj klucza do rozmowy.' >&2
43
+ false
44
+ fi
45
+ } &&
34
46
  npx robisie doctor
35
47
  }
36
48
  ```
37
49
 
38
50
  Łańcuch `&&` zatrzymuje blok po pierwszym błędzie; osobne przypisanie przed `export` zachowuje błąd odczytu klucza. Po naprawieniu przyczyny ponów nieudany krok i wszystkie następne w tym samym katalogu. Jeśli manifest już powstał, nie twórz go ponownie ani go nie usuwaj. Nie włączaj xtrace ani nie drukuj sekretu.
39
51
 
40
- W istniejącym projekcie zachowaj manifest i użyj instrukcji aktualizacji.
52
+ Dla istniejącego projektu bez `package.json` wykonaj powyższy blok nowej instalacji w katalogu tego projektu: tworzy tylko prywatny manifest i zachowuje pozostałe pliki. Jeśli zwykły manifest już istnieje albo reinstalujesz z zachowanym poprawnym kluczem, użyj poniższego bloku w wybranym katalogu projektu. Wczytuje zapisany klucz przed npm/init/doctor, nie nadpisuje zwykłego manifestu podczas przygotowania i tworzy go przez `wx` tylko przy braku. Samo npm może następnie dopisać zależność robisie oraz zmienić lockfile. Link manifestu (także wiszący) lub katalog odrzuca z wyjaśnieniem. Po uninstall, gdy nie ma poprawnego klucza, wróć do Connect i ukrytego pytania init: przy istniejącym zwykłym manifeście wykonaj blok nowej instalacji od `set +x` do doctor, bez kroku `cd`/tworzenia manifestu. Nie usuwaj manifestu, żeby ponowić instalację.
53
+
54
+ <!-- reinstall:start -->
55
+ ```sh
56
+ set +x
57
+ {
58
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
59
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
60
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
61
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
62
+ [ -n "$ROBISIE_KEY" ]; then
63
+ export ROBISIE_KEY
64
+ else
65
+ printf '%s\n' 'Nie można wczytać niepustego, zwykłego, czytelnego pliku klucza robisie.' 'Następny krok: sprawdź lokalnie plik klucza i jego odczyt; wyjaśnij link/katalog bez nadpisywania danych. Przy braku lub unieważnieniu klucza wróć do Connect i init z ukrytym pytaniem. Nie wklejaj klucza do rozmowy.' >&2
66
+ false
67
+ fi
68
+ } &&
69
+ node -e 'try {
70
+ const fs = require("node:fs");
71
+ let existing;
72
+ try { existing = fs.lstatSync("package.json"); }
73
+ catch (error) { if (error.code !== "ENOENT") throw error; }
74
+ if (existing) {
75
+ if (!existing.isFile()) throw new Error("package.json: wymagany zwykły plik; link i katalog odrzucone");
76
+ } else fs.writeFileSync("package.json", "{\"private\":true}\n", { flag: "wx" });
77
+ } catch (error) {
78
+ console.error(error.message);
79
+ console.error("Następny krok: sprawdź lokalnie package.json; zachowaj plik i wyjaśnij ścieżkę przed ponowieniem.");
80
+ process.exit(1);
81
+ }' &&
82
+ npm i robisie &&
83
+ npx robisie init &&
84
+ npx robisie doctor
85
+ ```
86
+ <!-- reinstall:end -->
41
87
 
42
88
  Dla Codex lub OpenCode zastąp `claude` przez `codex` lub `opencode`. Sam `--agent` nie usuwa wcześniejszej mapy ról: przy wcześniejszej konfiguracji użyj pełnej mapy z sekcji init w przewodniku. Nowy terminal wymaga obsługi profilu zsh/bash bez `--no-shell`; w innych sesjach wczytaj środowisko zgodnie z przewodnikiem. Agenta uruchom z katalogu instalacji; szczegóły startu ról, pomocników i diagnozy są w przewodnikach PL/EN powyżej.
43
89
 
@@ -75,15 +121,24 @@ Aktualizuj w katalogu instalacji po prywatnej kopii opisanej w przewodnikach. In
75
121
 
76
122
  ```sh
77
123
  set +x
78
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
79
- ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")" &&
80
- export ROBISIE_KEY &&
124
+ {
125
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
126
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
127
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
128
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
129
+ [ -n "$ROBISIE_KEY" ]; then
130
+ export ROBISIE_KEY
131
+ else
132
+ printf '%s\n' 'Nie można wczytać niepustego, zwykłego, czytelnego pliku klucza robisie.' 'Następny krok: sprawdź lokalnie plik klucza i jego odczyt; wyjaśnij link/katalog bez nadpisywania danych. Przy braku lub unieważnieniu klucza wróć do Connect i init z ukrytym pytaniem. Nie wklejaj klucza do rozmowy.' >&2
133
+ false
134
+ fi
135
+ } &&
81
136
  npm i robisie@latest &&
82
137
  npx robisie init &&
83
138
  npx robisie doctor
84
139
  ```
85
140
 
86
- Doctor sprawdza MAJOR kontraktu. Przy niezgodności wybierz zgodne wydanie. Poprzedni zgodny tgz przygotuj przez `npm pack robisie@<wersja>`; komenda powrotu `npm i --no-save "$backup/robisie-$previous_version.tgz"` wymaga jawnie wybranej wersji, prywatnej kopii konfiguracji i porównania późniejszych własnych zmian według przewodników. Opcja `--no-save` zachowuje przywrócone `package.json` i `package-lock.json`, bez zapisywania zależności `file:` od ścieżki prywatnej kopii. Kolejność powrotu: konfiguracja i tgz → ENV starego klucza → init → doctor. To nie jest automatyczny rollback.
141
+ Doctor sprawdza MAJOR kontraktu. Przy niezgodności wybierz zgodne wydanie. Poprzedni zgodny tgz przygotuj przez `npm pack robisie@<wersja>`; komenda powrotu `npm i --no-save "$backup/robisie-$previous_version.tgz"` wymaga jawnie wybranej wersji, prywatnej kopii konfiguracji i porównania późniejszych własnych zmian według przewodników. Opcja `--no-save` zachowuje przywrócone `package.json` i `package-lock.json`, bez zapisywania zależności `file:` od ścieżki prywatnej kopii. Kolejność powrotu: konfiguracja i OBA manifesty projektu (`package.json`, `package-lock.json`) → ENV starego klucza → tgz → init → doctor. To nie jest automatyczny rollback.
87
142
 
88
143
  Pomocniki uruchamiaj z cwd instalacji przez `npx robisie mcp <nazwa>`; init nadal generuje transport dla wersji paczki. npx może pobrać brakującą wersję z sieci. Bez instalacji zacznij od konta → init; przy istniejącej instalacji rozwiąż błędy ewidencji i odczytu klucza przed błędami sieci. Odinstalowanie może zmienić package.json, package-lock.json i node_modules; cache npm może zostać, a npx może pobrać paczkę ponownie. Bez masowego kasowania. Windows/WSL są niezweryfikowane.
89
144
 
@@ -121,3 +176,5 @@ Uruchom `npx robisie doctor --engine-config ./robisie.config.json` (także `--en
121
176
  Kod 0 oznacza poprawną strukturę konfiguracji i dokładnie cztery kompletne przypisania wykonania; raport pokazuje rolę → imię / dostawcę / model / wysiłek. Kod 1 wskazuje plik, błędne pole (jeśli dotyczy) i następny krok. Ten tryb działa offline, bez klucza, uruchamiania dostawców, wykonywania komend silnika ani zapisu plików. Raport jawnie stwierdza: „sprawdzono konfigurację; nie sprawdzono uruchomienia dostawców”. Zwykły `doctor` zachowuje dotychczasową diagnozę instalacji.
122
177
 
123
178
  Modele i wysiłki to przykładowe, dosłowne etykiety, bez gwarancji dostępności lub obsługi przez CLI. `grok-cli`/`none` opisują obecny review-job; nie dowodzą sterowania modelem ani wysiłkiem Groka. Imię jest metadanymi rejestru; Execution v1 zachowuje `{contractVersion:1,provider,model,effort}`. Walidacja nie jest odbiorem wykonania karty, dostawców ani całego procesu pracy.
179
+
180
+ Backupy po uninstall mogą nadal zawierać klucz; zachowaj ich prywatność i własną retencję, bez automatycznego kasowania. Wpis CHANGELOG o readback README nie dowodzi niepustego README w rejestrze: E4 wykazał 0 B przy poprawnym tarballu. Użyj lokalnych przewodników w `node_modules/robisie/docs/`; naprawa rejestru i publikacja to osobny zakres wydania.
package/dist/cli.js CHANGED
@@ -17,8 +17,12 @@ const HELP = `robisie ${PACKAGE_VERSION} — łączy Twojego agenta z tablicą r
17
17
  pomocnik ról (serwer MCP stdio) — uruchamia go agent, nie Ty
18
18
 
19
19
  Opcje doctor:
20
- --engine-config <path> lokalnie i offline sprawdza K2 i rejestr wykonania czterech ról K7
20
+ --engine-config <path> offline sprawdza strukturę konfiguracji projektu i przypisania czterech ról wykonania
21
21
  --engine-config=<path> ta sama składnia; nie sprawdza uruchomienia dostawców
22
+ Przykład: npx robisie doctor --engine-config ./robisie.config.json
23
+ Bez klucza i kontroli instalacji; nie sprawdza UUID projektu, repo, dostępności modeli ani wykonania komend.
24
+ Role wykonania w tym pliku są osobne od mapy ceo/builder/quality ustawianej przez init.
25
+ Przewodniki i przykłady: node_modules/robisie/docs/README.md oraz README.en.md w tym samym katalogu.
22
26
 
23
27
  Opcje init:
24
28
  --agent <${AGENT_IDS.join("|")}> wybrany dostawca (można powtórzyć albo podać po przecinku); razem z dostawcami mapy, bez --agent również wykryci
@@ -1,6 +1,6 @@
1
1
  /** Package identity and the server contract it speaks. */
2
2
  export declare const PACKAGE_NAME = "robisie";
3
- export declare const PACKAGE_VERSION = "0.1.2";
3
+ export declare const PACKAGE_VERSION = "0.1.3";
4
4
  /**
5
5
  * MAJOR of the agent-API contract this package understands.
6
6
  * PARITY: src/lib/mcp/contract-version.ts (AGENT_API_CONTRACT_VERSION) on the server.
package/dist/constants.js CHANGED
@@ -1,6 +1,6 @@
1
1
  /** Package identity and the server contract it speaks. */
2
2
  export const PACKAGE_NAME = "robisie";
3
- export const PACKAGE_VERSION = "0.1.2"; // x-release-please-version
3
+ export const PACKAGE_VERSION = "0.1.3"; // x-release-please-version
4
4
  /**
5
5
  * MAJOR of the agent-API contract this package understands.
6
6
  * PARITY: src/lib/mcp/contract-version.ts (AGENT_API_CONTRACT_VERSION) on the server.
package/dist/roles.d.ts CHANGED
@@ -17,7 +17,7 @@ export interface Role {
17
17
  export declare function rolesDir(): string;
18
18
  export declare function parseRole(file: Role["file"], text: string): Role;
19
19
  export declare function loadRoles(dir?: string): Role[];
20
- export declare const MANAGED_LINE = "<!-- robisie:managed 0.1.2 \u2014 plik zarz\u0105dzany przez `npx robisie`; `npx robisie uninstall` go usunie -->";
20
+ export declare const MANAGED_LINE = "<!-- robisie:managed 0.1.3 \u2014 plik zarz\u0105dzany przez `npx robisie`; `npx robisie uninstall` go usunie -->";
21
21
  export type AgentFlavor = "claude" | "codex" | "opencode";
22
22
  /** How the operator starts the Builder for one card in its own session (the card id is not a secret). */
23
23
  export declare function builderStartCommand(flavor: AgentFlavor, codexRolePath?: string): string;
package/docs/README.en.md CHANGED
@@ -1,14 +1,16 @@
1
- # robisie — from account to accepted card (package 0.1.2)
1
+ # robisie — from account to accepted card (package 0.1.3)
2
2
 
3
3
  Polski: [README.md](README.md).
4
4
 
5
5
  <!-- sekcja: dostepnosc -->
6
6
  ## Availability
7
7
 
8
- An account and key are needed for init and the roles. Separately, `npx robisie doctor --engine-config ./robisie.config.json` checks only configuration structure offline: it does not confirm project UUID, repo, models or provider execution. The guides shipped in this package are local at `node_modules/robisie/docs/README.md` and `node_modules/robisie/docs/README.en.md`; no website fetch is needed.
8
+ An account and key are needed for init and the roles. Offline configuration validation is a separate entry point when the CLI is available: it does not check the installation, start providers or require a project UUID from you. Separately, `npx robisie doctor --engine-config ./robisie.config.json` checks only configuration structure offline: it does not confirm project UUID, repo, models or provider execution. The guides shipped in this package are local at `node_modules/robisie/docs/README.md` and `node_modules/robisie/docs/README.en.md`; no website fetch is needed.
9
9
 
10
10
  Install robisie from npm in the prepared directory; run subsequent commands and agent sessions there. [Preparation](#wymagania) → [account](#konto) → [key](#klucz) → [installation](#instalacja) → [acceptance](#recenzja-i-odbior).
11
11
 
12
+ The CHANGELOG entry about registry README readback describes a release check, not proof that a particular publication has a nonempty README. E4 observed an empty registry README while the tarball contained the guides; use `node_modules/robisie/docs/` locally. Registry metadata, publication and historical CHANGELOG correction require separate release work.
13
+
12
14
  <!-- sekcja: wymagania -->
13
15
  <a id="wymagania"></a>
14
16
  ## Requirements
@@ -23,15 +25,17 @@ Prepare an empty directory on disk. You do not need a website or your own `packa
23
25
 
24
26
  The human signs in at https://robisie.app with Google or an email link. Wait for the first project's readiness screen. If readiness is missing, use the fallback link to https://robisie.app/dashboard/plugins/planer and prepare a project in the dashboard; the bounded readiness checks are not a provisioning time guarantee.
25
27
 
26
- The CEO requires authenticated discovery to return exactly one project. A dashboard project is not a directory on disk: confirm with the CEO that both concern the same goal before work. With zero projects, the human checks readiness and the dashboard fallback; with several, the human must organize/archive extras until discovery returns one. Clicking a project does not bind it for the CEO. Do not supply a project UUID in chat; the CEO takes its identifier only from discovery. Result: one recognized project before any agent write.
28
+ Discovery is the authenticated read of active projects through `list_projects`; the key scopes what the agent sees. The CEO requires authenticated discovery to return exactly one project. A dashboard project is not a directory on disk: confirm with the CEO that both concern the same goal before work. With zero projects, the human checks readiness and the dashboard fallback; with several, the human must organize/archive extras until discovery returns one. Clicking a project does not bind it for the CEO. Do not supply a project UUID in chat; the CEO takes its identifier only from discovery. Result: one recognized project before any agent write.
27
29
 
28
30
  <!-- sekcja: klucz -->
29
31
  <a id="klucz"></a>
30
32
  ## Key in Connect
31
33
 
34
+ An agent may create its own account and generate its key, within the account owner’s authorization. A human may need to confirm sign-in or another protected step; then continue after that confirmation. Someone else’s open session does not authorize using their account or key. Keep secrets out of chat and command history; if the available tools cannot supply a secret safely, the human enters it in the hidden init prompt.
35
+
32
36
  At https://robisie.app/dashboard/connect the human selects `worker` and a recognizable label, such as “tester laptop”, then generates the key. It is shown only once: store it like a password. The human supplies it outside chat to init's hidden prompt, never to chat, a card, a command argument or shell history.
33
37
 
34
- `worker` is the minimal path: read, create/update projects, tracks and cards, reserve work; no setting `done` through create/update. `observer` only reads. `full` adds deletion and closing decision matters; `owner_validator` has the same access level as full. `seeder` has narrow access to `get_task` and valid seeding through `append_detail`, without `list_projects`/board reads, so it cannot follow this guide.
38
+ `worker` is the minimal path: read, create/update projects, tracks and cards, reserve work; no setting `done` through create/update. `observer` only reads. Explicitly choose `worker` each time: later keys default to `observer` (the first-key screen may preselect worker); do not infer permissions from that default. `full` adds deletion and closing decision matters; `owner_validator` has the same access level as full. `seeder` has narrow access to `get_task` and valid seeding through `append_detail`, without `list_projects`/board reads, so it cannot follow this guide.
35
39
 
36
40
  The package stores **one key for CEO, Builder and Quality Officer** as `ROBISIE_KEY`. Role names do not change permissions. Do not use full to bypass acceptance of `done`: the owner accepts in the dashboard without broadening the agent's key.
37
41
 
@@ -39,7 +43,7 @@ The package stores **one key for CEO, Builder and Quality Officer** as `ROBISIE_
39
43
  <a id="instalacja"></a>
40
44
  ## Install from npm
41
45
 
42
- After preparing the account and key, the human opens a terminal and enters the chosen empty directory (replace the example path below). The Node.js step below creates a local `package.json` regardless of the directory name, including spaces and Polish characters. The manifest sets the installation directory even under an ancestor containing `node_modules`. If the `package.json` path already exists (including a symlink), the step refuses to write; it never overwrites it. Failure to enter the directory or create the manifest stops the rest of the block. Then: install, init with the hidden key prompt, doctor. In zsh/bash clear stale ENV before init and load the saved key before doctor — init cannot set its parent environment:
46
+ After preparing the account and key, the human opens a terminal and enters the chosen empty directory (replace the example path below). The Node.js step below creates a local `package.json` regardless of the directory name, including spaces and Polish characters. The manifest sets the installation directory even under an ancestor containing `node_modules`. If the `package.json` path already exists (including a symlink), the step refuses to write; it never overwrites it. EEXIST means the path exists: use the existing-project route below; resolve a link/directory first. Failure to enter the directory or create the manifest stops the rest of the block. Then: install, init with the hidden key prompt, doctor. In zsh/bash clear stale ENV before init and load the saved key before doctor — init cannot set its parent environment:
43
47
 
44
48
  ```sh
45
49
  cd "/path/to/empty directory" &&
@@ -50,19 +54,63 @@ node -e 'try {
50
54
  process.exit(1);
51
55
  }' &&
52
56
  {
57
+ set +x
53
58
  npm i robisie &&
54
59
  unset ROBISIE_KEY &&
55
60
  npx robisie init --agent claude &&
56
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
57
- ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")" &&
58
- export ROBISIE_KEY &&
61
+ {
62
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
63
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
64
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
65
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
66
+ [ -n "$ROBISIE_KEY" ]; then
67
+ export ROBISIE_KEY
68
+ else
69
+ printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
70
+ false
71
+ fi
72
+ } &&
59
73
  npx robisie doctor
60
74
  }
61
75
  ```
62
76
 
63
77
  The `&&` chain stops the block at the first error; assigning the key separately before `export` preserves the read status so doctor cannot mask it. After resolving the cause, retry the failed step and every subsequent step from the block in the same directory. If the manifest was already created, do not repeat its creation or delete it.
64
78
 
65
- In an existing project, keep the manifest and follow the update instructions.
79
+ For an existing project without `package.json`, run the fresh-install block above in that project directory: it creates only a private manifest and preserves other project files. If a regular manifest already exists, or you are reinstalling with a retained valid key, use the block below in the chosen project directory. It loads the saved key before npm/init/doctor, does not overwrite a regular manifest during preparation, and creates one with `wx` only if absent. npm itself may then add the robisie dependency and change the lockfile. It refuses a manifest link (including a dangling link) or directory with an explanation. After uninstall, when no valid key remains, return to Connect and the hidden init prompt: for an existing regular manifest run the fresh-install block from `set +x` through doctor, without its `cd`/manifest creation step. Do not delete a manifest to repeat installation.
80
+
81
+ <!-- reinstall:start -->
82
+ ```sh
83
+ set +x
84
+ {
85
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
86
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
87
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
88
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
89
+ [ -n "$ROBISIE_KEY" ]; then
90
+ export ROBISIE_KEY
91
+ else
92
+ printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
93
+ false
94
+ fi
95
+ } &&
96
+ node -e 'try {
97
+ const fs = require("node:fs");
98
+ let existing;
99
+ try { existing = fs.lstatSync("package.json"); }
100
+ catch (error) { if (error.code !== "ENOENT") throw error; }
101
+ if (existing) {
102
+ if (!existing.isFile()) throw new Error("package.json: expected a regular file; links and directories refused");
103
+ } else fs.writeFileSync("package.json", "{\"private\":true}\n", { flag: "wx" });
104
+ } catch (error) {
105
+ console.error(error.message);
106
+ console.error("Next step: check package.json locally; preserve the file and resolve its path before retrying.");
107
+ process.exit(1);
108
+ }' &&
109
+ npm i robisie &&
110
+ npx robisie init &&
111
+ npx robisie doctor
112
+ ```
113
+ <!-- reinstall:end -->
66
114
 
67
115
  For Codex or OpenCode replace `claude` with `codex` or `opencode`. With existing configuration, use the complete map in the next section; `--agent` alone does not clear it. Expected doctor result: exit 0. Prepare a compatible fallback tgz using Update below. Init configures `client-launch-context` and `ceo-client-launcher` for the package version; a local invocation is `npx robisie mcp <name>` from the installation cwd. Agent entries retain the transport generated by the package; this guide does not change it. npx may download the package when the required version is not available locally.
68
116
 
@@ -90,9 +138,19 @@ npx robisie init --agent opencode --role ceo=opencode --role builder=opencode --
90
138
  Profile support is limited to zsh/bash without `--no-shell`. With another shell or `--no-shell`, the human sets the agent session's environment securely. A POSIX shell can load the stored file without displaying its contents:
91
139
 
92
140
  ```sh
93
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
94
- ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")" &&
95
- export ROBISIE_KEY
141
+ set +x
142
+ {
143
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
144
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
145
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
146
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
147
+ [ -n "$ROBISIE_KEY" ]; then
148
+ export ROBISIE_KEY
149
+ else
150
+ printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
151
+ false
152
+ fi
153
+ }
96
154
  ```
97
155
 
98
156
  A new terminal alone does not guarantee the key: retain the installation's XDG_CONFIG_HOME and check doctor in the target session. With only `opencode.jsonc`, init refuses before writing. A remote MCP entry in jsonc does not install roles or helpers. Preserve the configuration; the human prepares a supported `opencode.json` without comments according to OpenCode settings, or selects another installed provider for all roles. The package does not convert JSONC.
@@ -184,6 +242,13 @@ Keep the installation's HOME, XDG_CONFIG_HOME and CODEX_HOME values (the command
184
242
 
185
243
  Missing/null/empty/malformed project configuration or installation record cannot guarantee restore. Preserve available data, run local `npx robisie doctor` and follow its advice; new init cannot reconstruct a missing record. Resolve record or key-read errors before network errors. Never replace a damaged record with an empty one.
186
244
 
245
+ Follow four steps; the table is a reference for selecting files, not twenty mandatory copies:
246
+
247
+ 1. Preserve project manifests (`package.json` and `package-lock.json`), project configuration and robisie’s installation record/key. Record absent files in `absent.txt`.
248
+ 2. From `manifest.entries`, select only installed providers, the recorded profile, roles and prior backups. Apply all path, type and readability checks below.
249
+ 3. Make and check only those copies; retain their paths and the selected release tgz privately.
250
+ 4. Update only after the copies are complete. To restore, compare later changes and restore BOTH project manifests before the tgz command, then load the key → install tgz → init → doctor.
251
+
187
252
  The table contains separate commands for manual selection, not a block to run wholesale. Copy project and robisie files and only the providers used in the record, never all of `~/.claude/`, CODEX_HOME or the OpenCode directory. Before each command check the type and readability of source, destination and their ancestors. For `backups/` and `roles/codex/`, inspect every child as well. An unreadable file/entry or a symlink (including dangling links and linked ancestors) stops the recipe: preserve state and compare paths, never blindly cp through a link. A directory where a file is expected also needs investigation. If a file is absent, record its full path in `$backup/absent.txt`, e.g. `printf '%s\n' "$PWD/robisie.config.json" >> "$backup/absent.txt"`; skip cp in both directions. Do not delete files created later during restore.
188
253
 
189
254
  Set `profile` to the profile actually changed in manifest.entries: zsh `${ZDOTDIR:-$HOME}/.zshrc`; bash on macOS the first readable `$HOME/.bash_profile`, `$HOME/.bash_login`, `$HOME/.profile` (fallback `.bash_profile`); bash elsewhere `$HOME/.bashrc`. With `--no-shell`/another shell do not invent a profile; still preserve a prior profile entry if recorded. For each additional `path` and `backup` in entries, set `entry_path` to the exact absolute path, choose a unique numeric `entry_id`, and record that pair privately. Repeat the last row for every such file. Do not assume defaults cover prior installations or providers. Create only needed missing destination directories after the same path checks.
@@ -218,11 +283,18 @@ Once the tgz and selected copies are ready, update. Init does not read the key f
218
283
  set +x
219
284
  XDG_CONFIG_HOME="$config_home" &&
220
285
  export XDG_CONFIG_HOME &&
221
- [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
222
- [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
223
- [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
224
- ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key")" &&
225
- export ROBISIE_KEY &&
286
+ {
287
+ if [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
288
+ [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
289
+ [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
290
+ ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key" 2>/dev/null)" &&
291
+ [ -n "$ROBISIE_KEY" ]; then
292
+ export ROBISIE_KEY
293
+ else
294
+ printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
295
+ false
296
+ fi
297
+ } &&
226
298
  npm i robisie@latest &&
227
299
  npx robisie init &&
228
300
  npx robisie doctor
@@ -235,19 +307,26 @@ Doctor checks the contract MAJOR; exit 0 also requires its other checks. Choose
235
307
 
236
308
  Before overwriting, preserve later user edits in a NEW private copy (`umask 077`, e.g. `later="$(mktemp -d "$HOME/robisie-later.XXXXXX")"`). Repeat directory preparation and the left column, substituting `$later` for `$backup`, without altering the original backup. Compare locally and merge user edits with the previous release's copy; configuration can contain a key, so do not publish the diff. Stop overwriting for unreadable configuration, links or an unresolved comparison. There is no promise of automatic rollback.
237
309
 
238
- After comparison run the selected right-column commands to the same destinations, honoring absent.txt. Directory rows copy contents through `/.` without nesting another directory; before restore prepare checked destination directories if missing. When merging `backups/` and `roles/codex/`, do not delete additional later files. Then in the same cwd install the retained compatible tgz, load the restored old key into ENV, and only then run init and doctor:
310
+ After comparison run the selected right-column commands to the same destinations, honoring absent.txt. Directory rows copy contents through `/.` without nesting another directory; before restore prepare checked destination directories if missing. When merging `backups/` and `roles/codex/`, do not delete additional later files. Restore `package.json` AND `package-lock.json` first. Then in the same cwd load the restored old key into ENV, install the retained compatible tgz, and only then run init and doctor:
239
311
 
240
312
  <!-- restore:start -->
241
313
  ```sh
242
314
  set +x
243
- npm i --no-save "$backup/robisie-$previous_version.tgz" &&
244
315
  XDG_CONFIG_HOME="$config_home" &&
245
316
  export XDG_CONFIG_HOME &&
246
- [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
247
- [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
248
- [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
249
- ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key")" &&
250
- export ROBISIE_KEY &&
317
+ {
318
+ if [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
319
+ [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
320
+ [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
321
+ ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key" 2>/dev/null)" &&
322
+ [ -n "$ROBISIE_KEY" ]; then
323
+ export ROBISIE_KEY
324
+ else
325
+ printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
326
+ false
327
+ fi
328
+ } &&
329
+ npm i --no-save "$backup/robisie-$previous_version.tgz" &&
251
330
  npx robisie init &&
252
331
  npx robisie doctor
253
332
  ```
@@ -267,6 +346,8 @@ npm uninstall robisie
267
346
 
268
347
  The first command removes robisie entries and blocks from files recorded in the installation manifest and undoes role installation. It does not restore old robisie entries. User-edited roles remain with a warning; backups remain and may contain an old key. Without an installation record the command changes nothing and **does not delete the key file**. A refusal during the Codex configuration check occurs **before key deletion**; after that check the key file is removed even if a later undo fails. A nonzero exit requires preserving your edits and resolving the reported problem before retrying. Open a new terminal. Uninstall does not revoke the key on the server: revoke it separately in Connect. The second command removes the package from the project and may change `package.json`, `package-lock.json` and `node_modules`; the npm cache may remain. Do not mass-delete those files or the cache. A later npx call may download the package again.
269
348
 
349
+ Retained backups, including private update copies, may still contain the key after uninstall. Keep them private according to your retention needs; uninstall does not erase or revoke those copies. This guide does not delete them automatically.
350
+
270
351
  <!-- sekcja: diagnoza -->
271
352
  ## Diagnosis
272
353
 
@@ -279,7 +360,7 @@ CLI messages remain in Polish. Match the message, then follow the English explan
279
360
  | brak-klucza | `Brak klucza robisie.` | No key: generate one in Connect and supply it to init. |
280
361
  | odrzucony-klucz | `Serwer robisie odrzucił klucz (nieważny albo unieważniony).` | Generate a new worker key; in zsh/bash run `unset ROBISIE_KEY`, then init with the hidden prompt. |
281
362
  | brak-odczytu | `Ten klucz nie ma uprawnień do odczytu tablicy (np. rola seeder).` | Select worker in Connect; `unset ROBISIE_KEY`, then init with the hidden prompt. |
282
- | major | `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.2 (obsługuje 1.x).` | Example of a MAJOR mismatch: install a release compatible with the server contract. |
363
+ | major | `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.3 (obsługuje 1.x).` | Example of a MAJOR mismatch: install a release compatible with the server contract. |
283
364
  | brak-env | `Zmienna ROBISIE_KEY nie jest ustawiona — role i agenci jej potrzebują.` | Check profile support; with --no-shell/another shell load the key file into the session environment as shown in init, then doctor. |
284
365
  | brak-programu | `katalog jest, programu nie ma w PATH` | Install the named provider program or add it to PATH; a configuration directory alone is insufficient. |
285
366
  | brak-programu-i-katalogu | `brak programu w PATH i katalogu dostawcy` | Install the selected program, repeat init with the complete shared map and doctor. |
package/docs/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # robisie — od konta do odebranej karty (paczka 0.1.2)
1
+ # robisie — od konta do odebranej karty (paczka 0.1.3)
2
2
 
3
3
  English: [README.en.md](README.en.md).
4
4
 
@@ -7,10 +7,12 @@ English: [README.en.md](README.en.md).
7
7
  <!-- sekcja: dostepnosc -->
8
8
  ## Dostępność
9
9
 
10
- Konto i klucz są potrzebne do init i pracy ról. Osobno `npx robisie doctor --engine-config ./robisie.config.json` sprawdza offline tylko strukturę konfiguracji: nie potwierdza UUID projektu, repo, modeli ani uruchomienia dostawców. Przewodniki z tej paczki znajdziesz lokalnie w `node_modules/robisie/docs/README.md` i `node_modules/robisie/docs/README.en.md`; nie trzeba pobierać ich ze strony.
10
+ Konto i klucz są potrzebne do init i pracy ról. Osobne wejście to walidacja offline, gdy CLI jest dostępne: nie sprawdza instalacji, nie uruchamia dostawców i nie wymaga podawania UUID projektu. Osobno `npx robisie doctor --engine-config ./robisie.config.json` sprawdza offline tylko strukturę konfiguracji: nie potwierdza UUID projektu, repo, modeli ani uruchomienia dostawców. Przewodniki z tej paczki znajdziesz lokalnie w `node_modules/robisie/docs/README.md` i `node_modules/robisie/docs/README.en.md`; nie trzeba pobierać ich ze strony.
11
11
 
12
12
  Zainstaluj robisie z npm w przygotowanym katalogu; w nim uruchamiaj dalsze polecenia i sesje agentów. [Przygotowanie](#wymagania) → [konto](#konto) → [klucz](#klucz) → [instalacja](#instalacja) → [odbiór](#recenzja-i-odbior).
13
13
 
14
+ Wpis CHANGELOG o readback README z rejestru opisuje kontrolę wydania, nie dowód niepustego README konkretnej publikacji. E4 wykazał pusty README w rejestrze przy przewodnikach obecnych w tarballu; lokalnie użyj `node_modules/robisie/docs/`. Metadane rejestru, publikacja i korekta historii CHANGELOG wymagają osobnej pracy wydaniowej.
15
+
14
16
  <!-- sekcja: wymagania -->
15
17
  <a id="wymagania"></a>
16
18
  ## Wymagania
@@ -25,15 +27,17 @@ Przygotuj pusty katalog na dysku. Nie potrzebujesz strony ani własnego pliku `p
25
27
 
26
28
  Człowiek loguje się na https://robisie.app przez Google albo link e-mail. Zaczekaj na ekran gotowości pierwszego projektu. Przy braku gotowości użyj odnośnika do https://robisie.app/dashboard/plugins/planer i przygotuj projekt w panelu; liczba prób sprawdzania gotowości nie jest gwarancją czasu przygotowania.
27
29
 
28
- CEO wymaga, aby uwierzytelnione discovery zwróciło dokładnie jeden projekt. Projekt w panelu nie jest katalogiem na dysku: przed pracą potwierdź z CEO, że dotyczą tego samego celu. Przy zerze projektów człowiek sprawdza gotowość i fallback panelu; przy wielu porządkuje/archiwizuje nadmiarowe projekty, aż discovery zwróci jeden. Wybór kliknięciem w panelu nie wiąże projektu dla CEO. Nie podawaj UUID projektu w rozmowie; CEO bierze identyfikator wyłącznie z discovery. Wynik: jeden rozpoznany projekt, zanim agent zapisze cokolwiek.
30
+ Discovery to uwierzytelniony odczyt aktywnych projektów przez `list_projects`; klucz wyznacza, co agent widzi. CEO wymaga, aby uwierzytelnione discovery zwróciło dokładnie jeden projekt. Projekt w panelu nie jest katalogiem na dysku: przed pracą potwierdź z CEO, że dotyczą tego samego celu. Przy zerze projektów człowiek sprawdza gotowość i fallback panelu; przy wielu porządkuje/archiwizuje nadmiarowe projekty, aż discovery zwróci jeden. Wybór kliknięciem w panelu nie wiąże projektu dla CEO. Nie podawaj UUID projektu w rozmowie; CEO bierze identyfikator wyłącznie z discovery. Wynik: jeden rozpoznany projekt, zanim agent zapisze cokolwiek.
29
31
 
30
32
  <!-- sekcja: klucz -->
31
33
  <a id="klucz"></a>
32
34
  ## Klucz w Connect
33
35
 
36
+ Agent może sam założyć konto i wygenerować klucz na własnym koncie, w granicach zgody jego właściciela. Logowanie lub inny chroniony krok może wymagać potwierdzenia człowieka; po nim kontynuuj. Cudza otwarta sesja nie uprawnia do korzystania z jej konta ani klucza. Sekret pozostaje poza rozmową i historią poleceń; jeśli dostępne narzędzia nie pozwalają przekazać go bezpiecznie, człowiek wpisuje go w ukrytym pytaniu init.
37
+
34
38
  Człowiek w https://robisie.app/dashboard/connect wybiera `worker` i własną rozpoznawalną etykietę, np. „tester laptop”, następnie generuje klucz. Jest wyświetlany tylko raz: zachowaj go jak hasło. Człowiek przekazuje go poza rozmową do ukrytego pytania init, nigdy do czatu, karty, argumentu polecenia ani historii powłoki.
35
39
 
36
- `worker` to minimalna droga: odczyt oraz tworzenie/zmiana projektów, ścieżek i kart, rezerwacja pracy; bez ustawiania `done` przez create/update. `observer` tylko czyta. `full` dodaje usuwanie oraz zamykanie spraw decyzyjnych; `owner_validator` ma ten sam poziom dostępu co full. `seeder` ma wąski dostęp do `get_task` i poprawnego zasiewu przez `append_detail`, bez `list_projects`/odczytu tablicy — nie uruchomi tego przewodnika.
40
+ `worker` to minimalna droga: odczyt oraz tworzenie/zmiana projektów, ścieżek i kart, rezerwacja pracy; bez ustawiania `done` przez create/update. `observer` tylko czyta. Za każdym razem jawnie wybierz `worker`: kolejne klucze mają domyślnie `observer` (ekran pierwszego klucza może wskazywać worker); nie wywodź uprawnień z wartości domyślnej. `full` dodaje usuwanie oraz zamykanie spraw decyzyjnych; `owner_validator` ma ten sam poziom dostępu co full. `seeder` ma wąski dostęp do `get_task` i poprawnego zasiewu przez `append_detail`, bez `list_projects`/odczytu tablicy — nie uruchomi tego przewodnika.
37
41
 
38
42
  Paczka zapisuje **jeden klucz dla CEO, Buildera i Quality Officera** jako `ROBISIE_KEY`. Nazwa roli nie zmienia uprawnień. Nie używaj full jako obejścia odbioru `done`: właściciel odbiera wynik w panelu bez rozszerzania klucza agenta.
39
43
 
@@ -41,7 +45,7 @@ Paczka zapisuje **jeden klucz dla CEO, Buildera i Quality Officera** jako `ROBIS
41
45
  <a id="instalacja"></a>
42
46
  ## Instalacja z npm
43
47
 
44
- Po przygotowaniu konta i klucza człowiek otwiera terminal i wchodzi do wybranego pustego katalogu (zastąp przykładową ścieżkę poniżej). Poniższy krok Node.js tworzy lokalny `package.json` niezależnie od nazwy katalogu, także ze spacjami i polskimi znakami. Manifest ustala katalog instalacji także pod przodkiem z `node_modules`. Jeśli ścieżka `package.json` już istnieje (również jako link), krok odmawia zapisu; niczego nie nadpisuje. Błąd wejścia do katalogu lub utworzenia manifestu zatrzymuje dalszy blok. Następnie: instalacja, init z ukrytym pytaniem o klucz, doctor. W zsh/bash usuń stary ENV przed init i wczytaj zapisany klucz przed doctor — init nie ustawia środowiska rodzica:
48
+ Po przygotowaniu konta i klucza człowiek otwiera terminal i wchodzi do wybranego pustego katalogu (zastąp przykładową ścieżkę poniżej). Poniższy krok Node.js tworzy lokalny `package.json` niezależnie od nazwy katalogu, także ze spacjami i polskimi znakami. Manifest ustala katalog instalacji także pod przodkiem z `node_modules`. Jeśli ścieżka `package.json` już istnieje (również jako link), krok odmawia zapisu; niczego nie nadpisuje. EEXIST oznacza istniejącą ścieżkę: wybierz drogę istniejącego projektu poniżej; link/katalog wymaga wyjaśnienia. Błąd wejścia do katalogu lub utworzenia manifestu zatrzymuje dalszy blok. Następnie: instalacja, init z ukrytym pytaniem o klucz, doctor. W zsh/bash usuń stary ENV przed init i wczytaj zapisany klucz przed doctor — init nie ustawia środowiska rodzica:
45
49
 
46
50
  ```sh
47
51
  cd "/ścieżka/do/pustego katalogu" &&
@@ -52,19 +56,63 @@ node -e 'try {
52
56
  process.exit(1);
53
57
  }' &&
54
58
  {
59
+ set +x
55
60
  npm i robisie &&
56
61
  unset ROBISIE_KEY &&
57
62
  npx robisie init --agent claude &&
58
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
59
- ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")" &&
60
- export ROBISIE_KEY &&
63
+ {
64
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
65
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
66
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
67
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
68
+ [ -n "$ROBISIE_KEY" ]; then
69
+ export ROBISIE_KEY
70
+ else
71
+ printf '%s\n' 'Nie można wczytać niepustego, zwykłego, czytelnego pliku klucza robisie.' 'Następny krok: sprawdź lokalnie plik klucza i jego odczyt; wyjaśnij link/katalog bez nadpisywania danych. Przy braku lub unieważnieniu klucza wróć do Connect i init z ukrytym pytaniem. Nie wklejaj klucza do rozmowy.' >&2
72
+ false
73
+ fi
74
+ } &&
61
75
  npx robisie doctor
62
76
  }
63
77
  ```
64
78
 
65
79
  Łańcuch `&&` zatrzymuje blok po pierwszym błędzie; osobne przypisanie przed `export` zachowuje status odczytu klucza, więc doctor go nie maskuje. Po naprawieniu przyczyny ponów nieudany krok i wszystkie następne z bloku w tym samym katalogu. Jeśli manifest już powstał, nie ponawiaj jego tworzenia ani go nie usuwaj.
66
80
 
67
- W istniejącym projekcie zachowaj manifest i użyj instrukcji aktualizacji.
81
+ Dla istniejącego projektu bez `package.json` wykonaj powyższy blok nowej instalacji w katalogu tego projektu: tworzy tylko prywatny manifest i zachowuje pozostałe pliki. Jeśli zwykły manifest już istnieje albo reinstalujesz z zachowanym poprawnym kluczem, użyj poniższego bloku w wybranym katalogu projektu. Wczytuje zapisany klucz przed npm/init/doctor, nie nadpisuje zwykłego manifestu podczas przygotowania i tworzy go przez `wx` tylko przy braku. Samo npm może następnie dopisać zależność robisie oraz zmienić lockfile. Link manifestu (także wiszący) lub katalog odrzuca z wyjaśnieniem. Po uninstall, gdy nie ma poprawnego klucza, wróć do Connect i ukrytego pytania init: przy istniejącym zwykłym manifeście wykonaj blok nowej instalacji od `set +x` do doctor, bez kroku `cd`/tworzenia manifestu. Nie usuwaj manifestu, żeby ponowić instalację.
82
+
83
+ <!-- reinstall:start -->
84
+ ```sh
85
+ set +x
86
+ {
87
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
88
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
89
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
90
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
91
+ [ -n "$ROBISIE_KEY" ]; then
92
+ export ROBISIE_KEY
93
+ else
94
+ printf '%s\n' 'Nie można wczytać niepustego, zwykłego, czytelnego pliku klucza robisie.' 'Następny krok: sprawdź lokalnie plik klucza i jego odczyt; wyjaśnij link/katalog bez nadpisywania danych. Przy braku lub unieważnieniu klucza wróć do Connect i init z ukrytym pytaniem. Nie wklejaj klucza do rozmowy.' >&2
95
+ false
96
+ fi
97
+ } &&
98
+ node -e 'try {
99
+ const fs = require("node:fs");
100
+ let existing;
101
+ try { existing = fs.lstatSync("package.json"); }
102
+ catch (error) { if (error.code !== "ENOENT") throw error; }
103
+ if (existing) {
104
+ if (!existing.isFile()) throw new Error("package.json: wymagany zwykły plik; link i katalog odrzucone");
105
+ } else fs.writeFileSync("package.json", "{\"private\":true}\n", { flag: "wx" });
106
+ } catch (error) {
107
+ console.error(error.message);
108
+ console.error("Następny krok: sprawdź lokalnie package.json; zachowaj plik i wyjaśnij ścieżkę przed ponowieniem.");
109
+ process.exit(1);
110
+ }' &&
111
+ npm i robisie &&
112
+ npx robisie init &&
113
+ npx robisie doctor
114
+ ```
115
+ <!-- reinstall:end -->
68
116
 
69
117
  Dla Codex lub OpenCode zastąp `claude` przez `codex` lub `opencode`. Przy wcześniejszej konfiguracji użyj pełnej mapy z następnej sekcji; samo `--agent` jej nie kasuje. Oczekiwany wynik doctor: exit 0. Awaryjny zgodny tgz przygotuj według sekcji Aktualizacja. Pomocniki `client-launch-context` i `ceo-client-launcher` są konfigurowane przez init dla wersji paczki; lokalne wywołanie to `npx robisie mcp <nazwa>` z cwd instalacji. Wpisy agenta zachowują transport generowany przez paczkę; ta instrukcja go nie zmienia. npx może pobrać paczkę z sieci, gdy nie znajdzie wymaganej wersji lokalnie.
70
118
 
@@ -92,9 +140,19 @@ npx robisie init --agent opencode --role ceo=opencode --role builder=opencode --
92
140
  Profil dotyczy tylko zsh/bash bez `--no-shell`. W innej powłoce lub przy `--no-shell` człowiek ustawia środowisko sesji agenta samodzielnie, bez ujawniania klucza. W powłoce POSIX można bezpiecznie wczytać zapisany plik:
93
141
 
94
142
  ```sh
95
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
96
- ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")" &&
97
- export ROBISIE_KEY
143
+ set +x
144
+ {
145
+ if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
146
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
147
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
148
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
149
+ [ -n "$ROBISIE_KEY" ]; then
150
+ export ROBISIE_KEY
151
+ else
152
+ printf '%s\n' 'Nie można wczytać niepustego, zwykłego, czytelnego pliku klucza robisie.' 'Następny krok: sprawdź lokalnie plik klucza i jego odczyt; wyjaśnij link/katalog bez nadpisywania danych. Przy braku lub unieważnieniu klucza wróć do Connect i init z ukrytym pytaniem. Nie wklejaj klucza do rozmowy.' >&2
153
+ false
154
+ fi
155
+ }
98
156
  ```
99
157
 
100
158
  Nowy terminal sam nie gwarantuje klucza: zachowaj XDG_CONFIG_HOME z instalacji i sprawdź doctor w docelowej sesji. Jeśli OpenCode ma tylko `opencode.jsonc`, init odmawia przed zapisem. Sam wpis zdalnego MCP w jsonc nie instaluje ról ani pomocników. Zachowaj konfigurację; człowiek przygotowuje wspierany `opencode.json` bez komentarzy zgodnie z ustawieniami OpenCode albo wybiera innego zainstalowanego dostawcę dla wszystkich ról. Paczka nie konwertuje JSONC.
@@ -186,6 +244,13 @@ Zachowaj te same wartości HOME, XDG_CONFIG_HOME i CODEX_HOME co podczas instala
186
244
 
187
245
  Brak/null/pusta/wadliwa konfiguracja projektu lub ewidencja nie daje gwarancji restore. Zachowaj dostępne dane, uruchom lokalny `npx robisie doctor` i zastosuj jego poradę; nowy init nie odtworzy brakującej ewidencji. Przy błędzie ewidencji lub odczytu klucza rozwiąż go przed błędami sieci. Nie zamieniaj uszkodzonej ewidencji na pustą.
188
246
 
247
+ Przejdź cztery kroki; tabela to ściąga wyboru plików, nie dwadzieścia obowiązkowych kopii:
248
+
249
+ 1. Zachowaj manifesty projektu (`package.json` i `package-lock.json`), konfigurację projektu oraz ewidencję/klucz robisie. Braki odnotuj w `absent.txt`.
250
+ 2. Z `manifest.entries` wybierz tylko użytych dostawców, zapisany profil, role i wcześniejsze backupy. Zastosuj wszystkie kontrole ścieżek, typu i odczytu opisane poniżej.
251
+ 3. Wykonaj i sprawdź tylko te kopie; zachowaj prywatnie ich ścieżki oraz tgz wybranego wydania.
252
+ 4. Aktualizuj dopiero po wykonaniu kopii. Przy powrocie porównaj późniejsze zmiany i przywróć OBA manifesty projektu przed komendą tgz, potem klucz → instalacja tgz → init → doctor.
253
+
189
254
  Poniższa tabela to osobne komendy do ręcznego wyboru, nie blok do uruchomienia w całości. Kopiuj pliki projektu i robisie oraz tylko użytych dostawców z ewidencji, nigdy całe `~/.claude/`, `CODEX_HOME` ani katalog OpenCode. Dla każdego źródła i celu oraz ich katalogów nadrzędnych sprawdź wcześniej typ i odczyt. Dla `backups/` i `roles/codex/` sprawdź również wszystkie elementy wewnątrz. Nieczytelny plik/wpis lub dowiązanie (także wiszące, również w katalogu nadrzędnym) zatrzymuje przepis: zachowaj stan i porównaj ścieżki, bez ślepego cp przez link. Katalog w miejscu oczekiwanego pliku także wymaga wyjaśnienia. Jeśli pliku nie ma, odnotuj jego pełną ścieżkę w `$backup/absent.txt`, np. `printf '%s\n' "$PWD/robisie.config.json" >> "$backup/absent.txt"`; pomiń cp w obie strony. Przy restore nie kasuj plików, które powstały później.
190
255
 
191
256
  `profile` ustaw na faktycznie zmieniony profil z manifest.entries: zsh `${ZDOTDIR:-$HOME}/.zshrc`; bash na macOS pierwszy czytelny `$HOME/.bash_profile`, `$HOME/.bash_login`, `$HOME/.profile` (gdy żaden nie istnieje, `.bash_profile`); bash poza macOS `$HOME/.bashrc`. Przy `--no-shell`/innej powłoce nie dopisuj nowego profilu; zachowaj jednak wcześniejszy wpis profilu, jeśli jest w ewidencji. Każdy dodatkowy `path` i `backup` z entries skopiuj oddzielnie: ustaw `entry_path` na dokładną absolutną ścieżkę, `entry_id` na własny unikalny numer i zanotuj parę w prywatnej kopii. Ostatni wiersz powtórz dla każdego takiego pliku. Nie zakładaj, że lista domyślna pokrywa poprzednie instalacje i dostawców. Utwórz tylko potrzebne brakujące katalogi docelowe po tej samej kontroli ścieżek.
@@ -220,11 +285,18 @@ Gdy tgz i wszystkie wybrane kopie są gotowe, aktualizuj. Init nie czyta pliku k
220
285
  set +x
221
286
  XDG_CONFIG_HOME="$config_home" &&
222
287
  export XDG_CONFIG_HOME &&
223
- [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
224
- [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
225
- [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
226
- ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key")" &&
227
- export ROBISIE_KEY &&
288
+ {
289
+ if [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
290
+ [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
291
+ [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
292
+ ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key" 2>/dev/null)" &&
293
+ [ -n "$ROBISIE_KEY" ]; then
294
+ export ROBISIE_KEY
295
+ else
296
+ printf '%s\n' 'Nie można wczytać niepustego, zwykłego, czytelnego pliku klucza robisie.' 'Następny krok: sprawdź lokalnie plik klucza i jego odczyt; wyjaśnij link/katalog bez nadpisywania danych. Przy braku lub unieważnieniu klucza wróć do Connect i init z ukrytym pytaniem. Nie wklejaj klucza do rozmowy.' >&2
297
+ false
298
+ fi
299
+ } &&
228
300
  npm i robisie@latest &&
229
301
  npx robisie init &&
230
302
  npx robisie doctor
@@ -237,19 +309,26 @@ Doctor sprawdza MAJOR kontraktu; exit 0 wymaga także pozostałych kontroli. Prz
237
309
 
238
310
  Przed nadpisaniem zachowaj późniejsze własne zmiany w NOWEJ prywatnej kopii (`umask 077`, np. `later="$(mktemp -d "$HOME/robisie-later.XXXXXX")"`). Powtórz przygotowanie katalogów i lewą kolumnę, podstawiając `$later` zamiast `$backup`, bez zmiany starej kopii. Porównaj lokalnie i scal własne zmiany z kopią poprzedniego wydania; konfiguracja może zawierać klucz, więc bez publikowania diffu. Przy nieczytelnej konfiguracji, linku lub nierozstrzygniętym porównaniu przerwij nadpisywanie. Nie ma obietnicy automatycznego rollbacku.
239
311
 
240
- Po porównaniu wykonaj wybrane komendy z prawej kolumny do tych samych celów, zachowując pominięcia z absent.txt. Wiersze katalogów kopiują zawartość przez `/.`, bez zagnieżdżania kolejnego katalogu; przed restore przygotuj sprawdzone katalogi celów, jeśli ich brakuje. Przy scalaniu `backups/` i `roles/codex/` nie usuwaj dodatkowych późniejszych plików. Potem w tym samym cwd zainstaluj zachowany zgodny tgz, wczytaj przywrócony stary klucz do ENV i dopiero wykonaj init oraz doctor:
312
+ Po porównaniu wykonaj wybrane komendy z prawej kolumny do tych samych celów, zachowując pominięcia z absent.txt. Wiersze katalogów kopiują zawartość przez `/.`, bez zagnieżdżania kolejnego katalogu; przed restore przygotuj sprawdzone katalogi celów, jeśli ich brakuje. Przy scalaniu `backups/` i `roles/codex/` nie usuwaj dodatkowych późniejszych plików. Najpierw przywróć `package.json` ORAZ `package-lock.json`. Potem w tym samym cwd wczytaj przywrócony stary klucz do ENV, zainstaluj zachowany zgodny tgz i dopiero wykonaj init oraz doctor:
241
313
 
242
314
  <!-- restore:start -->
243
315
  ```sh
244
316
  set +x
245
- npm i --no-save "$backup/robisie-$previous_version.tgz" &&
246
317
  XDG_CONFIG_HOME="$config_home" &&
247
318
  export XDG_CONFIG_HOME &&
248
- [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
249
- [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
250
- [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
251
- ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key")" &&
252
- export ROBISIE_KEY &&
319
+ {
320
+ if [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
321
+ [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
322
+ [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
323
+ ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key" 2>/dev/null)" &&
324
+ [ -n "$ROBISIE_KEY" ]; then
325
+ export ROBISIE_KEY
326
+ else
327
+ printf '%s\n' 'Nie można wczytać niepustego, zwykłego, czytelnego pliku klucza robisie.' 'Następny krok: sprawdź lokalnie plik klucza i jego odczyt; wyjaśnij link/katalog bez nadpisywania danych. Przy braku lub unieważnieniu klucza wróć do Connect i init z ukrytym pytaniem. Nie wklejaj klucza do rozmowy.' >&2
328
+ false
329
+ fi
330
+ } &&
331
+ npm i --no-save "$backup/robisie-$previous_version.tgz" &&
253
332
  npx robisie init &&
254
333
  npx robisie doctor
255
334
  ```
@@ -269,6 +348,8 @@ npm uninstall robisie
269
348
 
270
349
  Pierwsza komenda usuwa wpisy i bloki robisie z plików zapisanych w rejestrze instalacji oraz cofa role. Nie przywraca starych wpisów robisie. Zmienione przez użytkownika role zostają z ostrzeżeniem; kopie zapasowe pozostają i mogą zawierać stary klucz. Bez zapisu instalacji komenda niczego nie zmienia i **nie usuwa pliku klucza**. Odmowa podczas sprawdzania konfiguracji Codex następuje **przed usunięciem klucza**; po tym sprawdzeniu plik klucza jest usuwany, nawet jeśli późniejsze cofanie zmian się nie uda. Kod różny od zera wymaga zachowania własnych zmian i rozwiązania wskazanego problemu przed ponowieniem. Otwórz nowy terminal. Odinstalowanie nie unieważnia klucza na serwerze: unieważnij go osobno w Connect. Druga komenda usuwa paczkę z projektu i może zmienić `package.json`, `package-lock.json` oraz `node_modules`; cache npm może pozostać. Nie kasuj masowo tych plików ani cache. Późniejsze npx może ponownie pobrać paczkę z sieci.
271
350
 
351
+ Zachowane backupy, także prywatne kopie aktualizacji, mogą nadal zawierać klucz po uninstall. Przechowuj je prywatnie zgodnie z własną retencją; uninstall nie wymazuje ani nie unieważnia tych kopii. Ta instrukcja nie kasuje ich automatycznie.
352
+
272
353
  <!-- sekcja: diagnoza -->
273
354
  ## Diagnoza
274
355
 
@@ -281,7 +362,7 @@ Komunikaty CLI pozostają po polsku. Dopasuj komunikat, a potem wykonaj wskazan
281
362
  | brak-klucza | `Brak klucza robisie.` | Wygeneruj klucz w Connect i przekaż go do init. |
282
363
  | odrzucony-klucz | `Serwer robisie odrzucił klucz (nieważny albo unieważniony).` | Wygeneruj nowy klucz worker; w zsh/bash wykonaj `unset ROBISIE_KEY`, potem init z ukrytym pytaniem. |
283
364
  | brak-odczytu | `Ten klucz nie ma uprawnień do odczytu tablicy (np. rola seeder).` | Wybierz worker w Connect; `unset ROBISIE_KEY`, potem init z ukrytym pytaniem. |
284
- | major | `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.2 (obsługuje 1.x).` | Przykład niezgodnego MAJOR: zainstaluj wydanie zgodne z kontraktem serwera. |
365
+ | major | `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.3 (obsługuje 1.x).` | Przykład niezgodnego MAJOR: zainstaluj wydanie zgodne z kontraktem serwera. |
285
366
  | brak-env | `Zmienna ROBISIE_KEY nie jest ustawiona — role i agenci jej potrzebują.` | Sprawdź obsługę profilu; przy --no-shell/innej powłoce wczytaj plik klucza do środowiska sesji jak w init, potem doctor. |
286
367
  | brak-programu | `katalog jest, programu nie ma w PATH` | Zainstaluj program wskazanego dostawcy lub dodaj go do PATH; sam katalog konfiguracji nie wystarcza. |
287
368
  | brak-programu-i-katalogu | `brak programu w PATH i katalogu dostawcy` | Zainstaluj wybrany program, ponów init z pełną wspólną mapą i doctor. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "robisie",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "Instalator klienta robisie: łączy agenta (Claude Code, Codex CLI, OpenCode) z tablicą robisie i instaluje role klienta.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",