robisie 0.1.1 → 0.1.2

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,15 @@
1
1
  # Historia zmian klienta / Client changelog
2
2
 
3
+ ## 0.1.2 (2026-11-03)
4
+
5
+ Wydanie poprawek klienta i dokumentacji. / Client and documentation patch release.
6
+
7
+ - Publikacja rozpakowanego `package/` z kontrolą zgodności repacka przed publikacją i odczytem README z rejestru po publikacji (#689). / Publish the extracted `package/`, verify repack integrity before publication and read back the registry README afterwards (#689).
8
+ - Przewodniki pierwszej instalacji i przywracania tgz zachowują istniejące manifesty projektu, zatrzymują instalację po pierwszym błędzie i wskazują dokumentację zainstalowanej paczki. / First-install and tgz restore guides preserve existing project manifests, stop installation at the first error and point to the installed package documentation.
9
+ - Zimny start `doctor` prowadzi przez konto i `init`; walidacja pomocników odbywa się poza procesem doctor, a sprzątanie zachowuje bezpieczne błędy pomocników. / Cold-start `doctor` guides users through account setup and `init`; helper validation runs outside the doctor process and cleanup preserves safe helper failures.
10
+ - Limit rozmiaru odpowiedzi MCP; stałe błędy nieobsługiwanych zdarzeń OpenCode i diagnostyka bez nieznanych kluczy rejestru ról. / MCP response size budget; constant errors for unsupported OpenCode events and diagnostics without unknown role registry keys.
11
+ - Przykład konfiguracji ogranicza wynik do liczników; dokumentacja API zachowuje wynik operacji przy błędzie sprzątania. / Configuration example output is limited to counts; API documentation preserves operation outcomes when cleanup fails.
12
+
3
13
  ## 0.1.1 (2026-10-30)
4
14
 
5
15
  Wydanie utrzymaniowe: bezpieczniejsza instalacja, odzyskiwanie i diagnostyka oraz biblioteki klienta. Poniższe 45 kart ma odbiór **TAK lokalnie**; sprawdzenie wersji z rejestru npm pozostaje osobną bramką. / Maintenance release: safer installation, recovery and diagnostics, plus client libraries. The following 45 cards have **local acceptance**; verification of the npm registry release remains a separate gate.
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
- # robisie 0.1.0
1
+ # robisie
2
2
 
3
- Przewodniki: [PL — konto → odbiór → odinstalowanie](https://unpkg.com/robisie/docs/README.md) · [EN — account → acceptance → uninstall](https://unpkg.com/robisie/docs/README.en.md). Przygotuj Node.js 20+, npm, program jednego dostawcy AI oraz pusty katalog; strona i package.json nie są potrzebne. 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.
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
+
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/`.
4
6
 
5
7
  ## Przed init — konto i pierwszy projekt
6
8
 
@@ -12,16 +14,31 @@ Jeśli trasa przekierowała na /dashboard bez Planera, znajdź „Zacznij od pie
12
14
 
13
15
  ## Init — połącz agenta
14
16
 
15
- 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:
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:
16
18
 
17
19
  ```sh
18
- npm i robisie
19
- unset ROBISIE_KEY
20
- npx robisie init --agent claude
21
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] && export ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")"
20
+ cd "/ścieżka/do/pustego katalogu" &&
21
+ node -e 'try {
22
+ require("node:fs").writeFileSync("package.json", "{\"private\":true}\n", { flag: "wx" });
23
+ } catch (error) {
24
+ console.error(error.message);
25
+ process.exit(1);
26
+ }' &&
27
+ {
28
+ npm i robisie &&
29
+ unset ROBISIE_KEY &&
30
+ 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 &&
22
34
  npx robisie doctor
35
+ }
23
36
  ```
24
37
 
38
+ Ł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
+
40
+ W istniejącym projekcie zachowaj manifest i użyj instrukcji aktualizacji.
41
+
25
42
  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.
26
43
 
27
44
  ## Po init — sprawdź gotowość CEO
@@ -54,11 +71,25 @@ Codex: przejście do delivered wymaga niezależnej recenzji oraz zweryfikowanego
54
71
 
55
72
  Wszystkie trzy role muszą używać jednego dostawcy; mieszana mapa daje kod 1 doctor. Paczka nie uruchamia usług w tle ani nie zapewnia konta lub dostępu do AI.
56
73
 
57
- Aktualizuj w katalogu instalacji: `npm i robisie@latest` → `npx robisie init` → `npx robisie doctor`. Doctor sprawdza zgodność MAJOR kontraktu serwera; przy niezgodności wybierz zgodne wydanie. Awaryjnie otrzymany plik zainstaluj przez `npm i ./robisie-0.1.0.tgz`; lokalny powrót wymaga poprzedniego zgodnego tgz i kopii konfiguracji. Pełne instrukcje aktualizacji, powrotu i odinstalowania są w przewodnikach.
74
+ Aktualizuj w katalogu instalacji po prywatnej kopii opisanej w przewodnikach. Init nie czyta automatycznie pliku key: pierwszeństwo ma ROBISIE_KEY, potem ukryte pytanie, potem jawny `--key-stdin`. Wczytaj stary klucz przed init/doctor z tym samym XDG_CONFIG_HOME, bez xtrace i bez wydruku:
75
+
76
+ ```sh
77
+ 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 &&
81
+ npm i robisie@latest &&
82
+ npx robisie init &&
83
+ npx robisie doctor
84
+ ```
85
+
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.
87
+
88
+ 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.
58
89
 
59
- ## Lokalna walidacja rejestru wykonania K7
90
+ ## Lokalna walidacja konfiguracji wykonania
60
91
 
61
- Zapisz pełną konfigurację K2 i osobny rejestr wykonania w `robisie.config.json`:
92
+ Zapisz konfigurację projektu i osobny rejestr wykonania w `robisie.config.json`:
62
93
 
63
94
  ```json
64
95
  {
@@ -85,8 +116,8 @@ Zapisz pełną konfigurację K2 i osobny rejestr wykonania w `robisie.config.jso
85
116
  }
86
117
  ```
87
118
 
88
- Uruchom `npx robisie doctor --engine-config ./robisie.config.json` (także `--engine-config=./robisie.config.json`). Ścieżka pliku jest względem bieżącego katalogu, a `repo` i `stateDir` względem pliku konfiguracji. Role K2 `coordinator/owner/planner/advisor` zachowują domyślne nazwy; opcjonalne pole `roles` służy ich nazwom i odmianie, osobno od `roleRegistry`.
119
+ Uruchom `npx robisie doctor --engine-config ./robisie.config.json` (także `--engine-config=./robisie.config.json`). Ścieżka pliku jest względem bieżącego katalogu, a `repo` i `stateDir` względem pliku konfiguracji. Role projektu `coordinator/owner/planner/advisor` zachowują domyślne nazwy; opcjonalne pole `roles` służy ich nazwom i odmianie, osobno od `roleRegistry`.
89
120
 
90
- Kod 0 oznacza poprawną konfigurację K2 i dokładnie cztery kompletne przypisania K7; 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.
121
+ 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.
91
122
 
92
- 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 P-18/K3.
123
+ 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.
package/dist/cli.js CHANGED
@@ -1,11 +1,11 @@
1
1
  #!/usr/bin/env node
2
- import { realpathSync } from "node:fs";
3
- import { fileURLToPath, pathToFileURL } from "node:url";
2
+ import { lstatSync, realpathSync } from "node:fs";
3
+ import { fileURLToPath } from "node:url";
4
4
  import { AGENT_IDS, isAgentId } from "./agents.js";
5
5
  import { doctor, init, recoveryStep, uninstall } from "./commands.js";
6
6
  import { HELPER_SERVERS, PACKAGE_VERSION } from "./constants.js";
7
7
  import { RobisieError, errorMessage, nodeCtx } from "./context.js";
8
- import { helperPath, isHelperServer, runHelper } from "./helpers.js";
8
+ import { isHelperServer, runHelper } from "./helpers.js";
9
9
  import { ROLE_IDS, ROLE_STEP } from "./manifest.js";
10
10
  import { doctorEngineConfig } from "./role-registry.js";
11
11
  const HELP = `robisie ${PACKAGE_VERSION} — łączy Twojego agenta z tablicą robisie
@@ -112,15 +112,15 @@ export async function run(argv, ctx) {
112
112
  return doctorEngineConfig(ctx, args.engineConfig);
113
113
  if (ctx.env.ROBISIE_KEY) {
114
114
  try {
115
- const helper = await import(pathToFileURL(helperPath("client-launch-context")).href);
116
- if (!helper || typeof helper !== "object" || !("resolveProjectContext" in helper)
117
- || typeof helper.resolveProjectContext !== "function")
118
- throw new Error("Invalid project-context export");
119
- const result = helper.resolveProjectContext(ctx.env, ctx.cwd);
120
- if (!result || typeof result !== "object" || !("projectContext" in result)
121
- || typeof result.projectContext !== "string" || !("plannerAccess" in result)
122
- || result.plannerAccess !== "configured")
123
- throw new Error("Invalid project-context result");
115
+ // Match the helper's directory rules without executing its code in doctor.
116
+ const selected = ctx.env.ROBISIE_PROJECT_CONTEXT || ctx.cwd;
117
+ if (!selected.startsWith("/") || selected.includes("\n"))
118
+ throw new Error("Invalid project-context path");
119
+ const selectedStat = lstatSync(selected);
120
+ const stat = lstatSync(realpathSync(selected));
121
+ if (selectedStat.isSymbolicLink() || !stat.isDirectory() || stat.isSymbolicLink()) {
122
+ throw new Error("Invalid project-context directory");
123
+ }
124
124
  }
125
125
  catch {
126
126
  throw new RobisieError("Nie mogę potwierdzić kontekstu projektu używanego przez pomocnik klienta.", "W katalogu projektu wykonaj `unset ROBISIE_PROJECT_CONTEXT`, potem `npx robisie doctor`. Albo ustaw istniejący absolutny rzeczywisty katalog: `export ROBISIE_PROJECT_CONTEXT='/absolutna/sciezka/do/projektu'` (zastąp ścieżkę katalogiem projektu), potem `npx robisie doctor`.");
package/dist/commands.js CHANGED
@@ -175,11 +175,6 @@ export async function doctor(ctx) {
175
175
  await guard(async () => {
176
176
  manifest = readManifest(paths.manifest);
177
177
  });
178
- await guard(async () => {
179
- const version = await fetchContractVersion(ctx);
180
- assertCompatible(version);
181
- ctx.out(`✓ Wersja kontraktu serwera ${version} pasuje do paczki.`);
182
- });
183
178
  const envKey = ctx.env[KEY_ENV]?.trim() || null;
184
179
  let key = envKey;
185
180
  let keyRead = false;
@@ -188,8 +183,15 @@ export async function doctor(ctx) {
188
183
  keyRead = true;
189
184
  });
190
185
  const usableKey = key;
186
+ if (!manifest && !usableKey && keyRead)
187
+ fail("Brak klucza robisie.", "Załóż konto lub zaloguj się na https://robisie.app; " + NO_KEY_STEP);
188
+ await guard(async () => {
189
+ const version = await fetchContractVersion(ctx);
190
+ assertCompatible(version);
191
+ ctx.out(`✓ Wersja kontraktu serwera ${version} pasuje do paczki.`);
192
+ });
191
193
  if (!usableKey) {
192
- if (keyRead)
194
+ if (keyRead && manifest)
193
195
  fail("Brak klucza robisie.", NO_KEY_STEP);
194
196
  }
195
197
  else if (!KEY_PATTERN.test(usableKey))
@@ -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.1";
3
+ export declare const PACKAGE_VERSION = "0.1.2";
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.1"; // x-release-please-version
3
+ export const PACKAGE_VERSION = "0.1.2"; // 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/helpers.js CHANGED
@@ -52,14 +52,20 @@ export function runHelper(name) {
52
52
  if (settled)
53
53
  return;
54
54
  settled = true;
55
+ error = resultError ?? error;
55
56
  clearTimeout(timer);
56
57
  clearTimeout(parentTimer);
57
58
  process.off("SIGHUP", onHup);
58
59
  input.off("end", onEof);
59
60
  input.off("close", onEof);
60
61
  input.off("error", onStreamError);
61
- if (detached && child.stdin)
62
- input.unpipe(child.stdin);
62
+ try {
63
+ if (detached && child.stdin)
64
+ input.unpipe(child.stdin);
65
+ }
66
+ catch {
67
+ error ??= failure("strumień");
68
+ }
63
69
  process.off("SIGINT", onInt);
64
70
  process.off("SIGTERM", onTerm);
65
71
  child.off("exit", onExit);
@@ -157,16 +163,16 @@ export function runHelper(name) {
157
163
  return;
158
164
  }
159
165
  if (detached) {
160
- process.on("SIGINT", onInt);
161
- process.on("SIGTERM", onTerm);
162
- process.on("SIGHUP", onHup);
163
- // The agent may close npx rather than this CLI. Own the input pipe so EOF
164
- // interrupts active work even when npm does not forward process signals.
165
- input.on("end", onEof);
166
- input.on("close", onEof);
167
- input.on("error", onStreamError);
168
- child.stdin?.on("error", onStreamError);
169
166
  try {
167
+ process.on("SIGINT", onInt);
168
+ process.on("SIGTERM", onTerm);
169
+ process.on("SIGHUP", onHup);
170
+ // The agent may close npx rather than this CLI. Own the input pipe so EOF
171
+ // interrupts active work even when npm does not forward process signals.
172
+ input.on("end", onEof);
173
+ input.on("close", onEof);
174
+ input.on("error", onStreamError);
175
+ child.stdin?.on("error", onStreamError);
170
176
  if (!child.stdin)
171
177
  throw new Error("Missing helper stdin");
172
178
  input.pipe(child.stdin, { end: false });
package/dist/mcp.js CHANGED
@@ -1,6 +1,8 @@
1
1
  import { CONTRACT_VERSION_HEADER, PACKAGE_NAME, PACKAGE_VERSION, SUPPORTED_CONTRACT_MAJOR, mcpUrl, wellKnownUrl } from "./constants.js";
2
2
  import { RobisieError } from "./context.js";
3
3
  const TIMEOUT_MS = 15_000;
4
+ const RESPONSE_LIMIT_BYTES = 4_194_304;
5
+ const responseLimitErrors = new WeakSet();
4
6
  const UPDATE_STEP = "Zainstaluj z npm aktualną paczkę zgodną z kontraktem serwera; w katalogu instalacji wykonaj `npm i robisie@latest`, potem lokalne `npx robisie init` i `npx robisie doctor`.";
5
7
  /** Major of a semver string, or null when it is not one. */
6
8
  export function majorOf(version) {
@@ -33,11 +35,13 @@ export async function fetchContractVersion(ctx) {
33
35
  throw new RobisieError(`Serwer robisie odpowiedział błędem ${res.status} przy sprawdzaniu wersji.`, "Spróbuj ponownie za kilka minut; jeśli błąd zostaje, napisz do robisie.");
34
36
  }
35
37
  try {
36
- const body = await res.json();
38
+ const body = JSON.parse(await readText(res));
37
39
  const version = typeof body === "object" && body !== null ? body.contractVersion : undefined;
38
40
  return typeof version === "string" ? version : null;
39
41
  }
40
- catch {
42
+ catch (error) {
43
+ if (error instanceof RobisieError && responseLimitErrors.has(error))
44
+ throw error;
41
45
  return null;
42
46
  }
43
47
  }
@@ -50,6 +54,41 @@ function nonEmptyString(value) {
50
54
  function formatError() {
51
55
  return new RobisieError("Serwer robisie odpowiedział w nieznanym formacie.", UPDATE_STEP);
52
56
  }
57
+ /** Count actual bytes before decoding, including SSE frames already discarded by the parser. */
58
+ async function* readChunks(res) {
59
+ if (!res.body)
60
+ return;
61
+ const reader = res.body.getReader();
62
+ const decoder = new TextDecoder();
63
+ let bytes = 0;
64
+ try {
65
+ while (true) {
66
+ const { done, value } = await reader.read();
67
+ if (done) {
68
+ yield decoder.decode();
69
+ return;
70
+ }
71
+ bytes += value.byteLength;
72
+ if (bytes > RESPONSE_LIMIT_BYTES) {
73
+ const error = new RobisieError("Odpowiedź serwera robisie jest za duża (limit 4 MiB).", "Poproś administratora serwera o zmniejszenie odpowiedzi MCP do 4 MiB, potem uruchom ponownie `npx robisie doctor`.");
74
+ responseLimitErrors.add(error);
75
+ throw error;
76
+ }
77
+ yield decoder.decode(value, { stream: true });
78
+ }
79
+ }
80
+ finally {
81
+ // Cancellation may never settle; release ownership without delaying the result.
82
+ void reader.cancel().catch(() => { });
83
+ reader.releaseLock();
84
+ }
85
+ }
86
+ async function readText(res) {
87
+ let text = "";
88
+ for await (const chunk of readChunks(res))
89
+ text += chunk;
90
+ return text;
91
+ }
53
92
  /** Streamable HTTP answers either plain JSON or an SSE stream; pick our response out of either. */
54
93
  async function readRpc(res, id) {
55
94
  const matching = (candidate) => {
@@ -65,20 +104,12 @@ async function readRpc(res, id) {
65
104
  }
66
105
  return null;
67
106
  };
68
- let reader;
69
107
  try {
70
108
  if (!(res.headers.get("content-type") ?? "").includes("text/event-stream"))
71
- return matching(await res.text());
72
- if (!res.body)
73
- return null;
74
- reader = res.body.getReader();
75
- const decoder = new TextDecoder();
109
+ return matching(await readText(res));
76
110
  let buffer = "";
77
- while (true) {
78
- const { done, value } = await reader.read();
79
- if (done)
80
- return null; // EOF never completes an unterminated SSE event.
81
- buffer += decoder.decode(value, { stream: true });
111
+ for await (const chunk of readChunks(res)) {
112
+ buffer += chunk;
82
113
  let boundary;
83
114
  while ((boundary = /\r?\n\r?\n/.exec(buffer)) !== null) {
84
115
  const event = buffer.slice(0, boundary.index);
@@ -92,17 +123,13 @@ async function readRpc(res, id) {
92
123
  return message;
93
124
  }
94
125
  }
126
+ return null; // EOF never completes an unterminated SSE event.
95
127
  }
96
- catch {
128
+ catch (error) {
129
+ if (error instanceof RobisieError && responseLimitErrors.has(error))
130
+ throw error;
97
131
  throw new RobisieError("Nie mogę odczytać odpowiedzi serwera robisie.", "Sprawdź połączenie i uruchom ponownie `npx robisie doctor`.");
98
132
  }
99
- finally {
100
- if (reader) {
101
- // Cancellation may never settle; release ownership without delaying the RPC result.
102
- void reader.cancel().catch(() => { });
103
- reader.releaseLock();
104
- }
105
- }
106
133
  }
107
134
  async function rpc(ctx, key, id, method, params) {
108
135
  const res = await request(ctx, mcpUrl(ctx.origin), {
@@ -37,7 +37,7 @@ export function parseOpenCodeStream(raw, model) {
37
37
  sessionId = event.sessionID;
38
38
  const type = event.type, partType = part.type;
39
39
  if (!["step_start", "reasoning", "tool_use", "text", "step_finish"].includes(type)) {
40
- throw new Error(`OpenCode stream event is unsupported: ${String(type)}`);
40
+ throw new Error("OpenCode stream event is unsupported");
41
41
  }
42
42
  const messageId = part.messageID;
43
43
  if (messageId !== undefined && (typeof messageId !== "string" || !SAFE_STREAM_ID.test(messageId)))
@@ -1,7 +1,7 @@
1
1
  import { type Ctx } from "./context.js";
2
2
  import { type EngineConfig } from "./engine-config.js";
3
3
  declare const ROLES: readonly ["worker-client", "lead-client", "reviewer-client", "tester-client"];
4
- declare const PROVIDERS: readonly ["codex", "claude", "opencode", "grok"];
4
+ export declare const PROVIDERS: readonly ["codex", "claude", "opencode", "grok"];
5
5
  export type EngineRoleRegistry = Record<typeof ROLES[number], {
6
6
  name: string;
7
7
  provider: typeof PROVIDERS[number];
@@ -10,6 +10,12 @@ export type EngineRoleRegistry = Record<typeof ROLES[number], {
10
10
  }>;
11
11
  /** Separate from K2 roles (names/inflections) and K7's resource RoleRegistry. */
12
12
  export declare function parseRoleRegistry(raw: unknown, configPath: string): EngineRoleRegistry;
13
+ /** Select CLI/model/effort from the parsed registry; manufacturer and profile metadata belong to the caller. */
14
+ export declare function resolveRoleExecution(registry: EngineRoleRegistry, role: string): {
15
+ provider: typeof PROVIDERS[number];
16
+ model: string;
17
+ effortRequested: string;
18
+ };
13
19
  /** One read and one JSON object shared by the K2 and registry validators. */
14
20
  export declare function loadRoleRegistryConfig(path: string): {
15
21
  config: EngineConfig;
@@ -4,7 +4,7 @@ import { RobisieError, errorMessage } from "./context.js";
4
4
  import { CONFIG_FILE, parseEngineConfig } from "./engine-config.js";
5
5
  // K7 ROLE_NAMES; kept local so the package has no vendor runtime dependency.
6
6
  const ROLES = ["worker-client", "lead-client", "reviewer-client", "tester-client"];
7
- const PROVIDERS = ["codex", "claude", "opencode", "grok"];
7
+ export const PROVIDERS = ["codex", "claude", "opencode", "grok"];
8
8
  const FIELDS = ["name", "provider", "model", "effort"];
9
9
  function fail(configPath, field, reason) {
10
10
  throw new RobisieError(`${configPath}: ${field}: ${reason}`, `Popraw wskazane pole w pliku „${configPath}” i ponów \`npx robisie doctor --engine-config <path>\` z tą ścieżką.`);
@@ -20,7 +20,7 @@ export function parseRoleRegistry(raw, configPath) {
20
20
  const registry = raw.roleRegistry;
21
21
  for (const role of Object.keys(registry)) {
22
22
  if (!ROLES.includes(role))
23
- fail(configPath, `roleRegistry.${role}`, "nieznana rola; dozwolone: " + ROLES.join(", "));
23
+ fail(configPath, "roleRegistry", "nieznana rola; dozwolone: " + ROLES.join(", "));
24
24
  }
25
25
  const result = {};
26
26
  for (const role of ROLES) {
@@ -30,7 +30,7 @@ export function parseRoleRegistry(raw, configPath) {
30
30
  const entry = registry[role];
31
31
  for (const key of Object.keys(entry)) {
32
32
  if (!FIELDS.includes(key))
33
- fail(configPath, `${path}.${key}`, "nieznane pole; dozwolone: " + FIELDS.join(", "));
33
+ fail(configPath, path, "nieznane pole; dozwolone: " + FIELDS.join(", "));
34
34
  }
35
35
  for (const field of FIELDS) {
36
36
  if (!Object.hasOwn(entry, field) || typeof entry[field] !== "string" || !entry[field].trim()) {
@@ -45,6 +45,14 @@ export function parseRoleRegistry(raw, configPath) {
45
45
  }
46
46
  return result;
47
47
  }
48
+ /** Select CLI/model/effort from the parsed registry; manufacturer and profile metadata belong to the caller. */
49
+ export function resolveRoleExecution(registry, role) {
50
+ if (!ROLES.includes(role) || !Object.hasOwn(registry, role)) {
51
+ throw new RobisieError("Brak wybranej roli w rejestrze.", "Wybierz rolę obecną w sprawdzonej konfiguracji rejestru.");
52
+ }
53
+ const entry = registry[role];
54
+ return { provider: entry.provider, model: entry.model, effortRequested: entry.effort };
55
+ }
48
56
  /** One read and one JSON object shared by the K2 and registry validators. */
49
57
  export function loadRoleRegistryConfig(path) {
50
58
  const configPath = resolve(path);
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.1 \u2014 plik zarz\u0105dzany przez `npx robisie`; `npx robisie uninstall` go usunie -->";
20
+ export declare const MANAGED_LINE = "<!-- robisie:managed 0.1.2 \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;
@@ -4,6 +4,8 @@ Po instalacji `npm i robisie` używaj publicznego importu `robisie/dist/planer-c
4
4
 
5
5
  Caller przekazuje `config`: **dokładnie jedno z `origin` XOR `endpoint`**, np. `origin: 'https://robisie.app'` albo `endpoint: 'https://robisie.app/api/mcp'`, oraz własny `token`. Opcjonalne `fetch` pozwala wstrzyknąć transport (w teście wyłącznie fixture); bez niego SDK używa natywnego fetch. Opcjonalne `deadlineMs` ogranicza czas żądania. SDK nie pobiera tokena z pliku ani środowiska. Nie generuj, nie osadzaj i nie loguj tokena; przekaż go z bezpiecznego źródła callera poza rozmową i historią poleceń.
6
6
 
7
+ W obu przykładach wynik operacji i diagnostyka zamknięcia są oddzielne: błąd `close` nie zastępuje wyniku ani pierwotnego błędu operacji. Emituje tylko stałe ostrzeżenie, bez wyjątku, konfiguracji i patcha; awaria samej konsoli również nie zmienia wyniku. Błąd zamknięcia nie uzasadnia ponowienia append — zapis mógł już zostać wykonany.
8
+
7
9
  ## Odczyt i jednoznaczny wybór
8
10
 
9
11
  Wywołaj `readCard(config, selection)`. `selection` może zawierać `projectId`, `trackId` i `id` rozpoznane przez callera. Brak identyfikatora pozwala kontynuować tylko wtedy, gdy discovery zwraca dokładnie jedną pozycję na danym poziomie. Przy pustej liście, braku wskazanego ID albo wielu kandydatach wynik `wybierz-jednoznacznie` wskazuje etap; caller ustala wybór przed kolejnym odczytem. Nie wybieraj przypadkowej pierwszej pozycji. Ten odczyt niczego nie zapisuje ani nie tworzy brakujących obiektów.
@@ -37,7 +39,11 @@ export async function readCard(config, {
37
39
  const task = await client.getTask({ id: tasks[0].id, include });
38
40
  return { outcome: task === null ? 'brak-karty' : 'odczytano', task };
39
41
  } finally {
40
- await client.close();
42
+ try { await client.close(); }
43
+ catch {
44
+ try { console.warn('Nie udało się zamknąć klienta.'); }
45
+ catch { /* awaria diagnostyki nie zmienia wyniku */ }
46
+ }
41
47
  }
42
48
  }
43
49
  ```
@@ -65,7 +71,11 @@ export async function appendCard(config, { id, patch }) {
65
71
  }
66
72
  throw error;
67
73
  } finally {
68
- await client.close();
74
+ try { await client.close(); }
75
+ catch {
76
+ try { console.warn('Nie udało się zamknąć klienta.'); }
77
+ catch { /* awaria diagnostyki nie zmienia wyniku */ }
78
+ }
69
79
  }
70
80
  }
71
81
  ```
@@ -31,6 +31,8 @@ Spacje w argumencie i metaznaki są danymi. Przykładowe `a b` i `$(never-run)`
31
31
  mają pozostać dosłowne; nie sklejaj argv w polecenie powłoki. Poniższy odczyt
32
32
  nie wykonuje nawet testu, lintowania ani budowania. Komendy są ilustracyjne
33
33
  i wymagają podmiany przed wykorzystaniem konfiguracji do wykonywania pracy.
34
+ Nie wpisuj sekretów do argv — argumenty mogą trafić do listy procesów lub logów
35
+ narzędzi wykonujących komendy.
34
36
  `delivery: "pr"` opisuje sposób dostarczenia; sam odczyt nie tworzy PR.
35
37
 
36
38
  Role silnika to `coordinator`, `owner`, `planner`, `advisor`.
@@ -80,7 +82,7 @@ try {
80
82
  const configPath = process.argv[2];
81
83
  if (!configPath) throw new Error('Podaj ścieżkę do robisie.config.json');
82
84
  const config = loadEngineConfig(configPath);
83
- console.log(JSON.stringify(config));
85
+ console.log(`Konfiguracja poprawna. Tory: ${config.tracks.length}; komendy: ${Object.keys(config.engine.commands).length}; kontrole: ${config.engine.requiredChecks.length}.`);
84
86
  } catch (error) {
85
87
  console.error(error instanceof Error ? error.message : String(error));
86
88
  process.exitCode = 1;
@@ -95,20 +97,16 @@ node read-engine-config.mjs /absolutna/sciezka/robisie.config.json
95
97
  ```
96
98
 
97
99
  Katalog skryptu może być inny niż katalog konfiguracji. Sukces oznacza exit 0,
98
- pusty stderr i jeden obiekt JSON na stdout. Poniżej kształt wybranych pól wyniku
99
- dla powyższej ścieżki (pozostałe pola konfiguracji też są wypisywane):
100
+ pusty stderr i jedną linię na stdout: stałe etykiety oraz liczby torów, komend
101
+ i wymaganych kontroli. Wartości pól i nazwy kluczy konfiguracji nie są wypisywane.
102
+ Dla powyższego JSON wynik to:
100
103
 
101
104
  ```text
102
- configPath: "/absolutna/sciezka/robisie.config.json"
103
- stateDir: "/absolutna/state with spaces"
104
- engine.repo: "/absolutna/repo with spaces"
105
- engine.commands.test: ["node", "a b", "$(never-run)"]
106
- engine.delivery: "pr"
107
- roles.owner: {"name":"Ala","forms":["Ala","Ali"],"genitive":"Ali"}
105
+ Konfiguracja poprawna. Tory: 1; komendy: 3; kontrole: 3.
108
106
  ```
109
107
 
110
- Ścieżka pliku jest kanonizowana, więc przy dowiązaniach wynik wskazuje jego
111
- rzeczywistą lokalizację. Brak pliku, niepoprawny JSON lub błędne pola kończą
108
+ Ścieżka pliku jest kanonizowana we wczytanym obiekcie `config`, więc przy
109
+ dowiązaniach wskazuje jego rzeczywistą lokalizację. Brak pliku, niepoprawny JSON lub błędne pola kończą
112
110
  odczyt z niezerowym exit i komunikatem na stderr. Na przykład brak `test`
113
111
  w `engine.commands` daje błąd zawierający `engine.commands.test`, a
114
112
  `delivery: "invalid"` — `engine.delivery`. Odczyt nie dopisuje brakujących
package/docs/README.en.md CHANGED
@@ -1,19 +1,21 @@
1
- # robisie — from account to accepted card (package 0.1.0)
1
+ # robisie — from account to accepted card (package 0.1.2)
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.
9
+
8
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).
9
11
 
10
12
  <!-- sekcja: wymagania -->
11
13
  <a id="wymagania"></a>
12
14
  ## Requirements
13
15
 
14
- The human prepares Node.js 20+, npm, internet for dependencies and robisie, and one provider program: Claude Code, Codex CLI or OpenCode with their own AI access. Check `node --version`, `npm --version` and the chosen program's version (`claude --version`, `codex --version` or `opencode --version`). If absent from PATH, install it following its provider's instructions and check again; a configuration directory alone is insufficient. Use WSL on Windows (POSIX paths).
16
+ The human prepares Node.js 20+, npm, internet for dependencies and robisie, and one provider program: Claude Code, Codex CLI or OpenCode with their own AI access. Check `node --version`, `npm --version` and the chosen program's version (`claude --version`, `codex --version` or `opencode --version`). If absent from PATH, install it following its provider's instructions and check again; a configuration directory alone is insufficient. Windows/WSL are unverified; examples below use POSIX paths.
15
17
 
16
- Prepare an empty directory on disk. No website or `package.json` is needed; npm installation creates dependency files. This is the agents' working directory, separate from the dashboard project.
18
+ Prepare an empty directory on disk. You do not need a website or your own `package.json`; the Node.js step below creates it before installation. This is the agents' working directory, separate from the dashboard project.
17
19
 
18
20
  <!-- sekcja: konto -->
19
21
  <a id="konto"></a>
@@ -37,17 +39,32 @@ The package stores **one key for CEO, Builder and Quality Officer** as `ROBISIE_
37
39
  <a id="instalacja"></a>
38
40
  ## Install from npm
39
41
 
40
- After preparing the account and key, the human opens a terminal in the prepared directory. Three steps: 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:
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:
41
43
 
42
44
  ```sh
43
- npm i robisie
44
- unset ROBISIE_KEY
45
- npx robisie init --agent claude
46
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] && export ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")"
45
+ cd "/path/to/empty directory" &&
46
+ node -e 'try {
47
+ require("node:fs").writeFileSync("package.json", "{\"private\":true}\n", { flag: "wx" });
48
+ } catch (error) {
49
+ console.error(error.message);
50
+ process.exit(1);
51
+ }' &&
52
+ {
53
+ npm i robisie &&
54
+ unset ROBISIE_KEY &&
55
+ 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 &&
47
59
  npx robisie doctor
60
+ }
48
61
  ```
49
62
 
50
- 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. As a fallback, install a supplied file with `npm i ./robisie-0.1.0.tgz`. The agent starts `client-launch-context` and `ceo-client-launcher` via `npx -y robisie@0.1.0 mcp <name>`; the local package must be accessible from the session's cwd.
63
+ 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
+
65
+ In an existing project, keep the manifest and follow the update instructions.
66
+
67
+ 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.
51
68
 
52
69
  <!-- sekcja: init -->
53
70
  ## Connect your agent
@@ -73,7 +90,9 @@ npx robisie init --agent opencode --role ceo=opencode --role builder=opencode --
73
90
  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:
74
91
 
75
92
  ```sh
76
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] && export ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")"
93
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
94
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")" &&
95
+ export ROBISIE_KEY
77
96
  ```
78
97
 
79
98
  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.
@@ -144,9 +163,99 @@ In other CEO sessions, including Codex, moving to delivered requires independent
144
163
  The project owner can use Dashboard → Planer → card → Etap → “Zrobione” to move `delivered` to `done`, including when the agent uses a `worker` key. For the first card described here, the server does not enforce stored acceptance or evidence before a change to `done`: the dashboard lets the owner select “Zrobione” even without them. Do this only after checking and explicitly accepting the result. The dashboard cannot edit `details`; review and evidence are recorded through the supported board tool flow. This guide alone does not prove a customer has completed that flow.
145
164
 
146
165
  <!-- sekcja: aktualizacja -->
147
- ## Update
166
+ ## Update and private backup
167
+
168
+ Work in the installation directory. First prepare the backup below. Explicitly choose the previous release compatible with the server contract MAJOR; inspect the installed version with `node -p 'require("./node_modules/robisie/package.json").version'`. Replace the example `previous_version='0.1.1'` with that chosen version. `npm pack robisie@<wersja>` means pack the explicitly selected release, not an arbitrary tgz. Retain its filename and the backup directory. Disable xtrace; never print or paste secrets.
169
+
170
+ ```sh
171
+ set +x
172
+ umask 077 &&
173
+ config_home="${XDG_CONFIG_HOME:-$HOME/.config}" &&
174
+ codex_home="${CODEX_HOME:-$HOME/.codex}" &&
175
+ backup="$(mktemp -d "$HOME/robisie-backup.XXXXXX")" &&
176
+ mkdir -p "$backup/project" "$backup/robisie/backups" "$backup/robisie/roles/codex" \
177
+ "$backup/claude/agents" "$backup/codex" "$backup/opencode/agents" \
178
+ "$backup/opencode/plugins" "$backup/profile" "$backup/entries" &&
179
+ previous_version='0.1.1' &&
180
+ npm pack "robisie@$previous_version" --pack-destination "$backup"
181
+ ```
182
+
183
+ Keep the installation's HOME, XDG_CONFIG_HOME and CODEX_HOME values (the commands use HOME defaults when ENV is absent). Keep them for restore too. Inspect the local `$config_home/robisie/manifest.json`: `manifest.entries` records actual `path` and prior `backup` paths. Do not paste configuration containing a key into chat. A readable legacy manifest without roleProviders still has useful entries; its age alone does not require a new installation. `roleProviders: null` means unassigned — follow doctor without guessing the map.
184
+
185
+ 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
+
187
+ 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
+
189
+ 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.
190
+
191
+ | Source → private copy (before update) | Copy → restore destination (only after comparison) |
192
+ |---|---|
193
+ | `cp -p -- "$PWD/package.json" "$backup/project/package.json"` | `cp -p -- "$backup/project/package.json" "$PWD/package.json"` |
194
+ | `cp -p -- "$PWD/package-lock.json" "$backup/project/package-lock.json"` | `cp -p -- "$backup/project/package-lock.json" "$PWD/package-lock.json"` |
195
+ | `cp -p -- "$PWD/robisie.config.json" "$backup/project/robisie.config.json"` | `cp -p -- "$backup/project/robisie.config.json" "$PWD/robisie.config.json"` |
196
+ | `cp -p -- "$config_home/robisie/key" "$backup/robisie/key"` | `cp -p -- "$backup/robisie/key" "$config_home/robisie/key"` |
197
+ | `cp -p -- "$config_home/robisie/manifest.json" "$backup/robisie/manifest.json"` | `cp -p -- "$backup/robisie/manifest.json" "$config_home/robisie/manifest.json"` |
198
+ | `cp -Rp -- "$config_home/robisie/backups/." "$backup/robisie/backups/"` | `cp -Rp -- "$backup/robisie/backups/." "$config_home/robisie/backups/"` |
199
+ | `cp -Rp -- "$config_home/robisie/roles/codex/." "$backup/robisie/roles/codex/"` | `cp -Rp -- "$backup/robisie/roles/codex/." "$config_home/robisie/roles/codex/"` |
200
+ | `cp -p -- "$HOME/.claude.json" "$backup/claude/claude.json"` | `cp -p -- "$backup/claude/claude.json" "$HOME/.claude.json"` |
201
+ | `cp -p -- "$HOME/.claude/agents/ceo-client.md" "$backup/claude/agents/ceo-client.md"` | `cp -p -- "$backup/claude/agents/ceo-client.md" "$HOME/.claude/agents/ceo-client.md"` |
202
+ | `cp -p -- "$HOME/.claude/agents/manager-builder-client.md" "$backup/claude/agents/manager-builder-client.md"` | `cp -p -- "$backup/claude/agents/manager-builder-client.md" "$HOME/.claude/agents/manager-builder-client.md"` |
203
+ | `cp -p -- "$HOME/.claude/agents/quality-officer-client.md" "$backup/claude/agents/quality-officer-client.md"` | `cp -p -- "$backup/claude/agents/quality-officer-client.md" "$HOME/.claude/agents/quality-officer-client.md"` |
204
+ | `cp -p -- "$codex_home/config.toml" "$backup/codex/config.toml"` | `cp -p -- "$backup/codex/config.toml" "$codex_home/config.toml"` |
205
+ | `cp -p -- "$codex_home/AGENTS.md" "$backup/codex/AGENTS.md"` | `cp -p -- "$backup/codex/AGENTS.md" "$codex_home/AGENTS.md"` |
206
+ | `cp -p -- "$config_home/opencode/opencode.json" "$backup/opencode/opencode.json"` | `cp -p -- "$backup/opencode/opencode.json" "$config_home/opencode/opencode.json"` |
207
+ | `cp -p -- "$config_home/opencode/agents/ceo-client.md" "$backup/opencode/agents/ceo-client.md"` | `cp -p -- "$backup/opencode/agents/ceo-client.md" "$config_home/opencode/agents/ceo-client.md"` |
208
+ | `cp -p -- "$config_home/opencode/agents/manager-builder-client.md" "$backup/opencode/agents/manager-builder-client.md"` | `cp -p -- "$backup/opencode/agents/manager-builder-client.md" "$config_home/opencode/agents/manager-builder-client.md"` |
209
+ | `cp -p -- "$config_home/opencode/agents/quality-officer-client.md" "$backup/opencode/agents/quality-officer-client.md"` | `cp -p -- "$backup/opencode/agents/quality-officer-client.md" "$config_home/opencode/agents/quality-officer-client.md"` |
210
+ | `cp -p -- "$config_home/opencode/plugins/robisie-review-guard.js" "$backup/opencode/plugins/robisie-review-guard.js"` | `cp -p -- "$backup/opencode/plugins/robisie-review-guard.js" "$config_home/opencode/plugins/robisie-review-guard.js"` |
211
+ | `cp -p -- "$profile" "$backup/profile/selected"` | `cp -p -- "$backup/profile/selected" "$profile"` |
212
+ | `cp -p -- "$entry_path" "$backup/entries/$entry_id"` | `cp -p -- "$backup/entries/$entry_id" "$entry_path"` |
213
+
214
+ Once the tgz and selected copies are ready, update. Init does not read the key file automatically: ROBISIE_KEY takes priority, then the hidden terminal prompt, then explicit `--key-stdin` (for example automation without a terminal). A key file alone is insufficient. Load the old key BEFORE init/doctor using the same XDG_CONFIG_HOME; separate assignment before export and `&&` retain read failures without printing the key:
215
+
216
+ <!-- update:start -->
217
+ ```sh
218
+ set +x
219
+ XDG_CONFIG_HOME="$config_home" &&
220
+ 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 &&
226
+ npm i robisie@latest &&
227
+ npx robisie init &&
228
+ npx robisie doctor
229
+ ```
230
+ <!-- update:end -->
148
231
 
149
- In the installation directory run `npm i robisie@latest` → `npx robisie init` → `npx robisie doctor`. Doctor checks the server contract MAJOR; expect a compatible version, complete configuration and exit 0. If incompatible, choose a compatible release instead of repeating the same installation. For damaged files reinstall from npm; as a fallback install a supplied compatible tgz with `npm i ./robisie-0.1.0.tgz`. For a local return, retain the previous compatible tgz and a configuration backup, install it with the same command, then run init and doctor.
232
+ Doctor checks the contract MAJOR; exit 0 also requires its other checks. Choose a compatible release for a mismatch; reinstall damaged package files. Do not repeat the same incompatible installation.
233
+
234
+ ### Return to the previous release
235
+
236
+ 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
+
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:
239
+
240
+ <!-- restore:start -->
241
+ ```sh
242
+ set +x
243
+ npm i --no-save "$backup/robisie-$previous_version.tgz" &&
244
+ XDG_CONFIG_HOME="$config_home" &&
245
+ 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 &&
251
+ npx robisie init &&
252
+ npx robisie doctor
253
+ ```
254
+ <!-- restore:end -->
255
+
256
+ The `--no-save` option preserves the restored `package.json` and `package-lock.json` without recording a `file:` dependency on the private backup path.
257
+
258
+ Check the status of every separate table command; any error stops the recipe. The chain stops automatically. Never mask reads or combine key assignment with export. On failure preserve both copies and follow doctor before further overwrites.
150
259
 
151
260
  <!-- sekcja: odinstalowanie -->
152
261
  ## Uninstall
@@ -156,11 +265,13 @@ npx robisie uninstall
156
265
  npm uninstall robisie
157
266
  ```
158
267
 
159
- 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.
268
+ 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.
160
269
 
161
270
  <!-- sekcja: diagnoza -->
162
271
  ## Diagnosis
163
272
 
273
+ Without an installation, begin with the account and Connect → init; repeating doctor does not create an account. With an existing installation, doctor reads the record and key first (ENV takes priority over the file), then checks the network. Resolve record/key-read problems first while preserving data; a network failure on an existing installation does not call for a new account. Check connectivity and server access.
274
+
164
275
  CLI messages remain in Polish. Match the message, then follow the English explanation:
165
276
 
166
277
  | ID | CLI message | Next step |
@@ -168,16 +279,18 @@ CLI messages remain in Polish. Match the message, then follow the English explan
168
279
  | brak-klucza | `Brak klucza robisie.` | No key: generate one in Connect and supply it to init. |
169
280
  | 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. |
170
281
  | 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. |
171
- | major | `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.0 (obsługuje 1.x).` | Example of a MAJOR mismatch: install a release compatible with the server contract. |
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. |
172
283
  | 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. |
173
284
  | 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. |
174
285
  | brak-programu-i-katalogu | `brak programu w PATH i katalogu dostawcy` | Install the selected program, repeat init with the complete shared map and doctor. |
175
286
  | jsonc | `nie zmieniam automatycznie` | Preserve JSONC; prepare supported JSON or choose another provider for all roles. Remote MCP alone is insufficient. |
176
287
  | niepelna-instalacja | `Claude Code: niepełna instalacja` | Example of missing configuration: repeat init for your agent. |
177
288
 
178
- After repair, run local `npx robisie init` and `npx robisie doctor`; for missing files first reinstall the package from npm, for MAJOR obtain a compatible release. If the problem remains, send the team the message, version and cwd without the key. Uninstall success means removed entries and exit 0; exit 1 needs the indicated repair and does not mean complete removal.
289
+ After repair with an existing record, load the saved key as shown in Update before local `npx robisie init` and `npx robisie doctor`; reinstall missing package files from npm, and obtain a compatible release for MAJOR. For a missing record preserve data and follow doctor instead of blindly running init. If the problem remains, send the team the message, version and cwd without the key. Uninstall success means removed entries and exit 0; exit 1 needs the indicated repair and does not mean complete removal.
179
290
 
180
291
  <!-- sekcja: ograniczenia -->
181
292
  ## Limitations
182
293
 
183
294
  The installer does not start background services or the Builder on its own; after operator approval, the CEO can start the Builder through `spawn_builder`. Helpers run during agent sessions using the project directory (or `ROBISIE_PROJECT_CONTEXT`) as context. The installer contacts robisie to check the contract and key; the package file does not provide an account or AI provider access. One shared key identity does not provide three different permission levels. Acceptance requires independent review, evidence and the operator's approval.
295
+
296
+ Windows/WSL are unverified. Offline validation checks configuration structure, not project UUID, repo existence, model availability or provider execution.
package/docs/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # robisie — od konta do odebranej karty (paczka 0.1.0)
1
+ # robisie — od konta do odebranej karty (paczka 0.1.2)
2
2
 
3
3
  English: [README.en.md](README.en.md).
4
4
 
@@ -7,15 +7,17 @@ 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.
11
+
10
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).
11
13
 
12
14
  <!-- sekcja: wymagania -->
13
15
  <a id="wymagania"></a>
14
16
  ## Wymagania
15
17
 
16
- Człowiek przygotowuje Node.js 20+, npm, internet do zależności i robisie oraz program jednego dostawcy: Claude Code, Codex CLI albo OpenCode z własnym dostępem do AI. Sprawdź `node --version`, `npm --version` i wersję wybranego programu (`claude --version`, `codex --version` lub `opencode --version`). Jeśli programu nie ma w PATH, zainstaluj go według instrukcji dostawcy i sprawdź ponownie; sam katalog konfiguracji nie wystarcza. Na Windows używaj WSL (ścieżki POSIX).
18
+ Człowiek przygotowuje Node.js 20+, npm, internet do zależności i robisie oraz program jednego dostawcy: Claude Code, Codex CLI albo OpenCode z własnym dostępem do AI. Sprawdź `node --version`, `npm --version` i wersję wybranego programu (`claude --version`, `codex --version` lub `opencode --version`). Jeśli programu nie ma w PATH, zainstaluj go według instrukcji dostawcy i sprawdź ponownie; sam katalog konfiguracji nie wystarcza. Windows/WSL są niezweryfikowane; poniższe przykłady używają ścieżek POSIX.
17
19
 
18
- Przygotuj pusty katalog na dysku. Nie potrzebujesz strony ani pliku `package.json`; instalacja npm utworzy pliki zależności. To katalog pracy agentów, niezależny od projektu w panelu.
20
+ Przygotuj pusty katalog na dysku. Nie potrzebujesz strony ani własnego pliku `package.json`; przed instalacją utworzy go poniższy krok Node.js. To katalog pracy agentów, niezależny od projektu w panelu.
19
21
 
20
22
  <!-- sekcja: konto -->
21
23
  <a id="konto"></a>
@@ -39,17 +41,32 @@ Paczka zapisuje **jeden klucz dla CEO, Buildera i Quality Officera** jako `ROBIS
39
41
  <a id="instalacja"></a>
40
42
  ## Instalacja z npm
41
43
 
42
- Po przygotowaniu konta i klucza człowiek otwiera terminal w przygotowanym katalogu. Trzy kroki: 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:
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:
43
45
 
44
46
  ```sh
45
- npm i robisie
46
- unset ROBISIE_KEY
47
- npx robisie init --agent claude
48
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] && export ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")"
47
+ cd "/ścieżka/do/pustego katalogu" &&
48
+ node -e 'try {
49
+ require("node:fs").writeFileSync("package.json", "{\"private\":true}\n", { flag: "wx" });
50
+ } catch (error) {
51
+ console.error(error.message);
52
+ process.exit(1);
53
+ }' &&
54
+ {
55
+ npm i robisie &&
56
+ unset ROBISIE_KEY &&
57
+ 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 &&
49
61
  npx robisie doctor
62
+ }
50
63
  ```
51
64
 
52
- 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. Awaryjnie otrzymany plik zainstaluj przez `npm i ./robisie-0.1.0.tgz`. Pomocniki `client-launch-context` i `ceo-client-launcher` agent uruchamia przez `npx -y robisie@0.1.0 mcp <nazwa>`; lokalna paczka musi być dostępna z cwd sesji.
65
+ Ł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
+
67
+ W istniejącym projekcie zachowaj manifest i użyj instrukcji aktualizacji.
68
+
69
+ 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.
53
70
 
54
71
  <!-- sekcja: init -->
55
72
  ## Połączenie agenta
@@ -75,7 +92,9 @@ npx robisie init --agent opencode --role ceo=opencode --role builder=opencode --
75
92
  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:
76
93
 
77
94
  ```sh
78
- [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] && export ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")"
95
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
96
+ ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")" &&
97
+ export ROBISIE_KEY
79
98
  ```
80
99
 
81
100
  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.
@@ -146,9 +165,99 @@ W innych sesjach CEO, w tym Codex, przejście do delivered wymaga niezależnej r
146
165
  Właściciel projektu może w panelu: Dashboard → Planer → karta → Etap wybrać „Zrobione” i przesunąć `delivered` do `done`, także przy kluczu agenta `worker`. Dla opisanej pierwszej karty serwer nie wymusza zapisanej akceptacji ani dowodów przed zmianą na `done`: panel pozwala właścicielowi wybrać „Zrobione” także bez nich. Zrób to dopiero po sprawdzeniu wyniku i jawnym odbiorze. Panel nie edytuje szczegółów `details`; recenzję i dowody zapisuje się przez obsługiwany przepływ narzędzi tablicy. Sama instrukcja nie dowodzi, że ten przebieg przeszedł już u klienta.
147
166
 
148
167
  <!-- sekcja: aktualizacja -->
149
- ## Aktualizacja
168
+ ## Aktualizacja i prywatna kopia
169
+
170
+ Pracuj w katalogu instalacji. Najpierw przygotuj kopię poniżej. Wybierz jawnie poprzednią, zgodną z MAJOR kontraktu serwera wersję; sprawdź zainstalowaną przez `node -p 'require("./node_modules/robisie/package.json").version'`. Przykład `previous_version='0.1.1'` zastąp tą wybraną wersją. `npm pack robisie@<wersja>` pobiera właśnie to wydanie, nie przypadkowy plik tgz; zachowaj jego nazwę i katalog kopii. Nie wykonuj przepisu z włączonym xtrace, nie drukuj ani nie wklejaj sekretów.
171
+
172
+ ```sh
173
+ set +x
174
+ umask 077 &&
175
+ config_home="${XDG_CONFIG_HOME:-$HOME/.config}" &&
176
+ codex_home="${CODEX_HOME:-$HOME/.codex}" &&
177
+ backup="$(mktemp -d "$HOME/robisie-backup.XXXXXX")" &&
178
+ mkdir -p "$backup/project" "$backup/robisie/backups" "$backup/robisie/roles/codex" \
179
+ "$backup/claude/agents" "$backup/codex" "$backup/opencode/agents" \
180
+ "$backup/opencode/plugins" "$backup/profile" "$backup/entries" &&
181
+ previous_version='0.1.1' &&
182
+ npm pack "robisie@$previous_version" --pack-destination "$backup"
183
+ ```
184
+
185
+ Zachowaj te same wartości HOME, XDG_CONFIG_HOME i CODEX_HOME co podczas instalacji (gdy ENV brak, powyżej używane są domyślne HOME). Nie zmieniaj ich podczas powrotu. Sprawdź lokalny `$config_home/robisie/manifest.json`: `manifest.entries` wskazuje faktyczne ścieżki `path` i wcześniejsze kopie `backup`. Nie wypisuj treści konfiguracji z kluczem do czatu. Czytelny legacy manifest bez roleProviders nadal ma użyteczne entries; sama starsza postać nie wymaga nowej instalacji. `roleProviders: null` oznacza brak przypisania — doctor poda dalszy krok, bez zgadywania mapy.
186
+
187
+ 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
+
189
+ 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
+
191
+ `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.
192
+
193
+ | Źródło → prywatna kopia (przed aktualizacją) | Kopia → cel restore (dopiero po porównaniu) |
194
+ |---|---|
195
+ | `cp -p -- "$PWD/package.json" "$backup/project/package.json"` | `cp -p -- "$backup/project/package.json" "$PWD/package.json"` |
196
+ | `cp -p -- "$PWD/package-lock.json" "$backup/project/package-lock.json"` | `cp -p -- "$backup/project/package-lock.json" "$PWD/package-lock.json"` |
197
+ | `cp -p -- "$PWD/robisie.config.json" "$backup/project/robisie.config.json"` | `cp -p -- "$backup/project/robisie.config.json" "$PWD/robisie.config.json"` |
198
+ | `cp -p -- "$config_home/robisie/key" "$backup/robisie/key"` | `cp -p -- "$backup/robisie/key" "$config_home/robisie/key"` |
199
+ | `cp -p -- "$config_home/robisie/manifest.json" "$backup/robisie/manifest.json"` | `cp -p -- "$backup/robisie/manifest.json" "$config_home/robisie/manifest.json"` |
200
+ | `cp -Rp -- "$config_home/robisie/backups/." "$backup/robisie/backups/"` | `cp -Rp -- "$backup/robisie/backups/." "$config_home/robisie/backups/"` |
201
+ | `cp -Rp -- "$config_home/robisie/roles/codex/." "$backup/robisie/roles/codex/"` | `cp -Rp -- "$backup/robisie/roles/codex/." "$config_home/robisie/roles/codex/"` |
202
+ | `cp -p -- "$HOME/.claude.json" "$backup/claude/claude.json"` | `cp -p -- "$backup/claude/claude.json" "$HOME/.claude.json"` |
203
+ | `cp -p -- "$HOME/.claude/agents/ceo-client.md" "$backup/claude/agents/ceo-client.md"` | `cp -p -- "$backup/claude/agents/ceo-client.md" "$HOME/.claude/agents/ceo-client.md"` |
204
+ | `cp -p -- "$HOME/.claude/agents/manager-builder-client.md" "$backup/claude/agents/manager-builder-client.md"` | `cp -p -- "$backup/claude/agents/manager-builder-client.md" "$HOME/.claude/agents/manager-builder-client.md"` |
205
+ | `cp -p -- "$HOME/.claude/agents/quality-officer-client.md" "$backup/claude/agents/quality-officer-client.md"` | `cp -p -- "$backup/claude/agents/quality-officer-client.md" "$HOME/.claude/agents/quality-officer-client.md"` |
206
+ | `cp -p -- "$codex_home/config.toml" "$backup/codex/config.toml"` | `cp -p -- "$backup/codex/config.toml" "$codex_home/config.toml"` |
207
+ | `cp -p -- "$codex_home/AGENTS.md" "$backup/codex/AGENTS.md"` | `cp -p -- "$backup/codex/AGENTS.md" "$codex_home/AGENTS.md"` |
208
+ | `cp -p -- "$config_home/opencode/opencode.json" "$backup/opencode/opencode.json"` | `cp -p -- "$backup/opencode/opencode.json" "$config_home/opencode/opencode.json"` |
209
+ | `cp -p -- "$config_home/opencode/agents/ceo-client.md" "$backup/opencode/agents/ceo-client.md"` | `cp -p -- "$backup/opencode/agents/ceo-client.md" "$config_home/opencode/agents/ceo-client.md"` |
210
+ | `cp -p -- "$config_home/opencode/agents/manager-builder-client.md" "$backup/opencode/agents/manager-builder-client.md"` | `cp -p -- "$backup/opencode/agents/manager-builder-client.md" "$config_home/opencode/agents/manager-builder-client.md"` |
211
+ | `cp -p -- "$config_home/opencode/agents/quality-officer-client.md" "$backup/opencode/agents/quality-officer-client.md"` | `cp -p -- "$backup/opencode/agents/quality-officer-client.md" "$config_home/opencode/agents/quality-officer-client.md"` |
212
+ | `cp -p -- "$config_home/opencode/plugins/robisie-review-guard.js" "$backup/opencode/plugins/robisie-review-guard.js"` | `cp -p -- "$backup/opencode/plugins/robisie-review-guard.js" "$config_home/opencode/plugins/robisie-review-guard.js"` |
213
+ | `cp -p -- "$profile" "$backup/profile/selected"` | `cp -p -- "$backup/profile/selected" "$profile"` |
214
+ | `cp -p -- "$entry_path" "$backup/entries/$entry_id"` | `cp -p -- "$backup/entries/$entry_id" "$entry_path"` |
215
+
216
+ Gdy tgz i wszystkie wybrane kopie są gotowe, aktualizuj. Init nie czyta pliku key automatycznie: pierwszeństwo ma ROBISIE_KEY, potem ukryte pytanie w terminalu, potem jawny `--key-stdin` (np. automatyzacja bez terminala). Sam plik key nie wystarcza. Wczytaj stary klucz PRZED init/doctor z tego samego XDG_CONFIG_HOME; osobne przypisanie przed export i `&&` zachowują błąd odczytu bez wydruku klucza:
217
+
218
+ <!-- update:start -->
219
+ ```sh
220
+ set +x
221
+ XDG_CONFIG_HOME="$config_home" &&
222
+ 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 &&
228
+ npm i robisie@latest &&
229
+ npx robisie init &&
230
+ npx robisie doctor
231
+ ```
232
+ <!-- update:end -->
150
233
 
151
- W katalogu instalacji wykonaj `npm i robisie@latest` → `npx robisie init` → `npx robisie doctor`. Doctor sprawdza zgodność MAJOR kontraktu serwera; oczekiwany wynik to zgodna wersja, pełna konfiguracja i exit 0. Przy niezgodności wybierz zgodne wydanie zamiast ponawiać tę samą instalację. Przy uszkodzonych plikach przeinstaluj paczkę z npm; awaryjnie użyj otrzymanego zgodnego tgz przez `npm i ./robisie-0.1.0.tgz`. Do lokalnego powrotu zachowaj poprzedni zgodny tgz i kopię konfiguracji, zainstaluj go tą samą komendą, potem uruchom init i doctor.
234
+ Doctor sprawdza MAJOR kontraktu; exit 0 wymaga także pozostałych kontroli. Przy niezgodności wybierz zgodne wydanie, przy uszkodzonych plikach przeinstaluj paczkę. Nie ponawiaj tej samej niezgodnej instalacji.
235
+
236
+ ### Powrót do poprzedniego wydania
237
+
238
+ 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
+
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:
241
+
242
+ <!-- restore:start -->
243
+ ```sh
244
+ set +x
245
+ npm i --no-save "$backup/robisie-$previous_version.tgz" &&
246
+ XDG_CONFIG_HOME="$config_home" &&
247
+ 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 &&
253
+ npx robisie init &&
254
+ npx robisie doctor
255
+ ```
256
+ <!-- restore:end -->
257
+
258
+ Opcja `--no-save` zachowuje przywrócone `package.json` i `package-lock.json`, bez zapisywania zależności `file:` od ścieżki prywatnej kopii.
259
+
260
+ Po każdej osobnej komendzie tabeli sprawdź jej status; błąd zatrzymuje przepis. Łańcuch zatrzymuje się sam. Nie maskuj odczytu ani nie łącz przypisania klucza z export. W razie błędu zachowaj obie kopie i skorzystaj z porady doctor, bez dalszego nadpisywania.
152
261
 
153
262
  <!-- sekcja: odinstalowanie -->
154
263
  ## Odinstalowanie
@@ -158,11 +267,13 @@ npx robisie uninstall
158
267
  npm uninstall robisie
159
268
  ```
160
269
 
161
- 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.
270
+ 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.
162
271
 
163
272
  <!-- sekcja: diagnoza -->
164
273
  ## Diagnoza
165
274
 
275
+ Bez instalacji zacznij od konta i Connect → init; samo ponawianie doctor nie zakłada konta. Przy istniejącej instalacji doctor najpierw odczytuje ewidencję i klucz (ENV ma pierwszeństwo przed plikiem), a potem sprawdza sieć. Najpierw rozwiąż wskazany problem ewidencji/odczytu klucza, zachowując dane; błąd sieci przy istniejącej instalacji nie oznacza potrzeby nowego konta. Sprawdź połączenie i dostęp do serwera.
276
+
166
277
  Komunikaty CLI pozostają po polsku. Dopasuj komunikat, a potem wykonaj wskazaną czynność:
167
278
 
168
279
  | ID | Komunikat CLI | Następny krok |
@@ -170,16 +281,18 @@ Komunikaty CLI pozostają po polsku. Dopasuj komunikat, a potem wykonaj wskazan
170
281
  | brak-klucza | `Brak klucza robisie.` | Wygeneruj klucz w Connect i przekaż go do init. |
171
282
  | 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. |
172
283
  | 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. |
173
- | major | `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.0 (obsługuje 1.x).` | Przykład niezgodnego MAJOR: zainstaluj wydanie zgodne z kontraktem serwera. |
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. |
174
285
  | 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. |
175
286
  | brak-programu | `katalog jest, programu nie ma w PATH` | Zainstaluj program wskazanego dostawcy lub dodaj go do PATH; sam katalog konfiguracji nie wystarcza. |
176
287
  | 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. |
177
288
  | jsonc | `nie zmieniam automatycznie` | Zachowaj JSONC; przygotuj wspierany JSON albo wybierz innego dostawcę dla wszystkich ról. Sam zdalny MCP nie wystarcza. |
178
289
  | niepelna-instalacja | `Claude Code: niepełna instalacja` | Przykład brakującej konfiguracji: ponów init dla swojego agenta. |
179
290
 
180
- Po naprawie uruchom lokalne `npx robisie init` i `npx robisie doctor`; przy braku plików najpierw przeinstaluj paczkę z npm, przy MAJOR uzyskaj zgodne wydanie. Jeśli problem pozostaje, przekaż zespołowi komunikat, wersję i cwd bez klucza. Przy uninstall wynik to usunięte wpisy i exit 0; kod 1 wymaga wskazanej naprawy, nie oznacza pełnego usunięcia.
291
+ Po naprawie przy istniejącej ewidencji wczytaj zapisany klucz według Aktualizacji przed lokalnym `npx robisie init` i `npx robisie doctor`; przy braku plików paczki przeinstaluj ją z npm, przy MAJOR uzyskaj zgodne wydanie. Przy braku ewidencji zachowaj dane i zastosuj poradę doctor zamiast init w ciemno. Jeśli problem pozostaje, przekaż zespołowi komunikat, wersję i cwd bez klucza. Przy uninstall wynik to usunięte wpisy i exit 0; kod 1 wymaga wskazanej naprawy, nie oznacza pełnego usunięcia.
181
292
 
182
293
  <!-- sekcja: ograniczenia -->
183
294
  ## Ograniczenia
184
295
 
185
296
  Instalator nie uruchamia sam usług w tle ani Buildera; po zgodzie operatora CEO może uruchomić Buildera przez `spawn_builder`. Pomocniki działają podczas sesji agenta, z kontekstem katalogu projektu (lub `ROBISIE_PROJECT_CONTEXT`). Instalator łączy się z robisie w celu sprawdzenia kontraktu i klucza; plik paczki nie zapewnia konta ani dostępu do dostawcy AI. Jedna wspólna tożsamość klucza nie daje trzech różnych poziomów uprawnień. Odbiór wymaga niezależnej recenzji, dowodów i zgody operatora.
297
+
298
+ Windows/WSL są niezweryfikowane. Walidacja offline sprawdza strukturę konfiguracji, nie UUID projektu, istnienie repo, dostępność modeli ani uruchomienie dostawców.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "robisie",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
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",