robisie 0.1.0 → 0.1.1

package/docs/README.md

@@ -2,10 +2,12 @@
 
 English: [README.en.md](README.en.md).
 
+[API silnika](ENGINE-API.md).
+
 <!-- sekcja: dostepnosc -->
 ## Dostępność
 
-Ten przewodnik dotyczy otrzymanego pliku `robisie-0.1.0.tgz`, bez pobierania instalatora z rejestru npm. Wynik 404 z 20.10.2026 jest obserwacją historyczną. Zespół przekazuje tgz; wszystkie dalsze polecenia i sesje agentów uruchamiaj w katalogu, w którym zainstalujesz tę paczkę. [Przygotowanie](#wymagania) → [konto](#konto) → [klucz](#klucz) → [instalacja](#instalacja) → [odbiór](#recenzja-i-odbior).
+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).
 
 <!-- sekcja: wymagania -->
 <a id="wymagania"></a>
@@ -13,7 +15,7 @@ Ten przewodnik dotyczy otrzymanego pliku `robisie-0.1.0.tgz`, bez pobierania ins
 
 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).
 
-Przygotuj pusty katalog na dysku i umieść w nim tylko otrzymany tgz oraz README. 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.
+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.
 
 <!-- sekcja: konto -->
 <a id="konto"></a>
@@ -35,16 +37,19 @@ Paczka zapisuje **jeden klucz dla CEO, Buildera i Quality Officera** jako `ROBIS
 
 <!-- sekcja: instalacja -->
 <a id="instalacja"></a>
-## Instalacja pliku paczki
+## Instalacja z npm
 
-Człowiek otwiera terminal w przygotowanym katalogu z tgz i README:
+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:
 
 ```sh
-npm i ./robisie-0.1.0.tgz
-npx robisie version
+npm i robisie
+unset ROBISIE_KEY
+npx robisie init --agent claude
+[ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] && export ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key")"
+npx robisie doctor
 ```
 
-Oczekiwany wynik: 0.1.0. Jeśli npm nie znajduje pliku, sprawdź katalog i nazwę otrzymanego 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.
+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.
 
 <!-- sekcja: init -->
 ## Połączenie agenta
@@ -108,11 +113,15 @@ Doctor uruchamia plik pomocnika przez node, agent przez npx. `ROBISIE_PROJECT_CO
 <!-- sekcja: pierwsza-karta -->
 ## Pierwsza karta i start Buildera
 
-Człowiek uruchamia CEO w katalogu instalacji: `claude --agent ceo-client`, albo `codex` i prosi o rolę robisie CEO (odczyt pełnego pliku wskazanego w AGENTS.md), albo `opencode` i wybiera `ceo-client`. Po poprawnym discovery przekaż prośbę, która działa przy samym README i tgz:
+Człowiek uruchamia CEO w katalogu instalacji: `claude --agent ceo-client`, albo `codex` i prosi o rolę robisie CEO (odczyt pełnego pliku wskazanego w AGENTS.md), albo `opencode` i wybiera `ceo-client`. Po poprawnym discovery przekaż prośbę, która działa po instalacji npm z samym README:
 
 > Utwórz w tym katalogu plik wynik.txt z dokładną treścią „robisie działa” i końcowym znakiem nowej linii. Sprawdź odczytem, że treść jest dokładnie taka. Granice: tylko ten plik, bez zależności, kont i publikacji. Przygotuj zakres i zaczekaj na moją zgodę; po pracy potrzebuję niezależnej recenzji i mojego odbioru.
 
-Zgoda człowieka poprzedza Buildera: `draft` → `ready` → `in_progress` → `in_review` → niezależna recenzja i verified receipt → `delivered` → odbiór właściciela → `done`. CEO podaje polecenie, **człowiek uruchamia Buildera w nowym terminalu w katalogu instalacji**; automatyczny launcher zwykłego katalogu może pozostawić kartę ready.
+Po zgodzie człowieka CEO domyślnie wywołuje `spawn_builder` z ID karty potwierdzonej w `ready`. Pełny przebieg w Claude Code: `draft` → `ready` → `in_progress` → `in_review` → niezależna recenzja i verified receipt → `delivered` → odbiór właściciela → `done`; granice odbioru dla pozostałych sesji opisuje sekcja [Recenzja i jawny odbiór](#recenzja-i-odbior).
+
+Przy błędzie `spawn_builder` CEO zgłasza błąd i naprawia przyczynę przed ponowieniem; nie przełącza automatycznie na ręczny start.
+
+Ręczny start to wyłącznie jawny wybór operatora: wtedy CEO podaje polecenie do uruchomienia w nowym terminalu w katalogu instalacji.
 
 ID pochodzi z utworzonej lub odczytanej karty, nie z projektu ani sesji. Poniżej fikcyjny przykład małego kanonicznego UUID; zastąp go dokładnym ID karty. Przykład Codex zakłada XDG_CONFIG_HOME=/home/tester/Robisie config: zastąp całą ścieżkę rzeczywistą z instalacji (domyślnie $HOME/.config/robisie/roles/codex/manager-builder-client.md). Tylda wewnątrz cytowanego promptu nie rozwinie się. Wybierz jedno polecenie:
 
@@ -128,16 +137,18 @@ Oczekiwany wynik startu: świeży odczyt CEO potwierdza przydzieloną kartę in_
 <a id="recenzja-i-odbior"></a>
 ## Recenzja i jawny odbiór
 
-CEO uruchamia niezależnego Quality Officera przez `Agent(quality-officer-client)`, po świeżym odczycie in_review. Quality Officer niezależnie sprawdza wynik i zapisuje recenzję oraz dowody na karcie; Builder nie recenzuje własnej pracy. Sprawdzenie dowodów i jawna zgoda na odbiór to obowiązek operatora. Po zweryfikowanej recenzji i przejściu do delivered sprawdź kryteria odbioru; jeśli do odbioru brakuje dowodów lub Twojej zgody, pozostaw kartę w `delivered`.
+W Claude Code CEO uruchamia niezależnego Quality Officera przez `Agent(quality-officer-client)`, po świeżym odczycie in_review. Quality Officer niezależnie sprawdza wynik i zapisuje recenzję oraz dowody na karcie; Builder nie recenzuje własnej pracy. CEO weryfikuje potwierdzenie recenzji (verified receipt) i wykonuje świeże odczyty karty wymagane przez protokół przed przejściem do `delivered`; następnie jawny odbiór operatora pozwala przejść do `done`. Sprawdzenie dowodów i jawna zgoda na odbiór to obowiązek operatora. Po zweryfikowanej recenzji i przejściu do delivered sprawdź kryteria odbioru; jeśli do odbioru brakuje dowodów lub Twojej zgody, pozostaw kartę w `delivered`.
+
+OpenCode: karta pozostaje w `in_review` niezależnie od dostępności narzędzia Agent; brak wspieranego przejścia do `delivered`. Pełny odbiór wymaga opisanej wyżej ścieżki w Claude Code. Wynik task/VERIFIED, etykieta roli ani sam JSON receiptu nie otwierają tego przejścia; nie obchodź odmowy ręczną zmianą statusu ani samorecenzją.
 
-Przejście do delivered wymaga niezależnej recenzji oraz zweryfikowanego potwierdzenia (verified receipt). Jeśli w sesji CEO brakuje narzędzia Agent, w szczególności w Codex/OpenCode, karta pozostaje w `in_review`: to brak zdolności produktu wymagający naprawy CEO/CR. Nie zastępuj recenzji oceną Buildera ani ręczną zmianą etapu. Sama konfiguracja trzech ról nie zapewnia tej integracji.
+W innych sesjach CEO, w tym Codex, przejście do delivered wymaga niezależnej recenzji oraz zweryfikowanego potwierdzenia (verified receipt). Jeśli w sesji CEO brakuje narzędzia Agent, karta pozostaje w `in_review`: to brak zdolności produktu wymagający naprawy CEO/CR. Nie zastępuj recenzji oceną Buildera ani ręczną zmianą etapu. Sama konfiguracja trzech ról nie zapewnia tej integracji.
 
 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.
 
 <!-- sekcja: aktualizacja -->
 ## Aktualizacja
 
-Człowiek uzyskuje od zespołu plik tgz zgodny z MAJOR kontraktu serwera. W tym samym katalogu instaluje otrzymany plik przez `npm i ./robisie-0.1.0.tgz` (zastąp nazwę nazwą zgodnego wydania), potem `npx robisie init` i `npx robisie doctor`. Oczekiwany wynik: zgodna wersja, pełna konfiguracja i exit 0 doctor; przy niezgodności uzyskaj właściwe wydanie zamiast ponawiać tę samą instalację. Przy uszkodzonych plikach przeinstaluj otrzymany tgz tą samą komendą. Nie potrzebujesz wydania z rejestru npm.
+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.
 
 <!-- sekcja: odinstalowanie -->
 ## Odinstalowanie
@@ -159,16 +170,16 @@ Komunikaty CLI pozostają po polsku. Dopasuj komunikat, a potem wykonaj wskazan
 | brak-klucza | `Brak klucza robisie.` | Wygeneruj klucz w Connect i przekaż go do init. |
 | 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. |
 | 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. |
-| major | `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.0 (obsługuje 1.x).` | Przykład niezgodnego MAJOR: uzyskaj zgodny plik paczki od zespołu. |
+| 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. |
 | 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. |
 | brak-programu | `katalog jest, programu nie ma w PATH` | Zainstaluj program wskazanego dostawcy lub dodaj go do PATH; sam katalog konfiguracji nie wystarcza. |
 | 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. |
 | jsonc | `nie zmieniam automatycznie` | Zachowaj JSONC; przygotuj wspierany JSON albo wybierz innego dostawcę dla wszystkich ról. Sam zdalny MCP nie wystarcza. |
 | niepelna-instalacja | `Claude Code: niepełna instalacja` | Przykład brakującej konfiguracji: ponów init dla swojego agenta. |
 
-Po naprawie uruchom lokalne `npx robisie init` i `npx robisie doctor`; przy braku plików najpierw przeinstaluj otrzymany tgz, 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.
+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.
 
 <!-- sekcja: ograniczenia -->
 ## Ograniczenia
 
-Paczka nie uruchamia usług w tle ani Buildera automatycznie. 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.
+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.

package/docs/RELEASE-0.1.0.md

@@ -4,13 +4,17 @@
 
 Klient łączy Claude Code, Codex CLI lub OpenCode z tablicą robisie. `init` instaluje konfigurację MCP, role CEO, Builder i Quality Officer oraz polecenia pomocników `client-launch-context` i `ceo-client-launcher`; `doctor` sprawdza połączenie i instalację, a `uninstall` usuwa zarejestrowane zmiany. Obce ustawienia i instrukcje pozostają; pierwsze kopie zapasowe zachowują stan sprzed instalacji.
 
-Wymagania: Node.js >=20, npm i własny zainstalowany agent z dostępem do dostawcy AI; połączenie z robisie i klucz z Connect. Windows wymaga WSL (ścieżki POSIX). Klient rozumie kontrakt serwera 1.x, obecnie 1.0.0. Inny major, np. 2.0.0, jest odrzucany przed zapisem przez `init`; starszy klient nie obniża kontraktu serwera.
+Wymagania 0.1: macOS lub Linux, Node.js >=20, npm i własny zainstalowany agent z dostępem do dostawcy AI; połączenie z robisie i klucz z Connect. Windows/WSL nie mają zweryfikowanego wsparcia. Klient rozumie kontrakt serwera 1.x, obecnie 1.0.0. Inny major, np. 2.0.0, jest odrzucany przed zapisem przez `init`; starszy klient nie obniża kontraktu serwera.
 
-Dostępność: raportowany wynik `npm view robisie` z 20.10.2026 to E404 — nie można pobrać `robisie` z npm. Nie wykonano tu nowego pomiaru. Bez lokalnie zainstalowanej paczki `npx robisie` i pomocniki nie wystartują. Otrzymany plik `robisie-0.1.0.tgz` można zainstalować przez `npm i ./robisie-0.1.0.tgz` w projekcie; uruchamiaj agenta w tym samym katalogu, aby `npx -y robisie@0.1.0 mcp <nazwa>` znalazło lokalną paczkę. Szczegóły: [README](README.md).
+Dostępność: instalacja z npm przez `npm i robisie` w katalogu pracy agenta; dalsze kroki opisuje [README](README.md).
 
-Ograniczenia: wszystkie trzy role muszą obecnie używać jednego dostawcy; mieszana mapa daje błąd `doctor`. Operator uruchamia Buildera w nowym terminalu i jawnie odbiera wynik po niezależnej recenzji. Instalacja nie dowodzi przejścia całej pętli klienta ani uruchomienia pracy autonomicznej.
+Po zgodzie człowieka na kartę potwierdzoną w `ready` CEO domyślnie uruchamia Buildera przez `ceo-client-launcher` → `spawn_builder`. Ręczny start w nowym terminalu jest wyłącznie jawnym wyborem operatora; błąd pomocnika wymaga zgłoszenia i naprawy przyczyny przed ponowieniem, bez automatycznego przejścia na ręczny start. Instalator sam nie startuje usług w tle ani Buildera.
 
-Powrót lokalny: zachowaj poprzedni tgz i kopię własnej konfiguracji; w tym samym projekcie zainstaluj go przez `npm i ./robisie-0.1.0.tgz`, potem `npx robisie init --agent <agent>` i `npx robisie doctor`. Najpierw sprawdź zgodność kontraktu. Test 0.1.0 → syntetyczne 0.1.1 → 0.1.0 jest lokalną próbą reinstalacji i powrotu, nie rollbackiem opublikowanych wydań. `npx robisie uninstall` przywraca niezmienione role sprzed instalacji, zachowuje backupy, a role zmienione przez użytkownika pozostawia z ostrzeżeniem. Backupy mogą zawierać klucz — chroń je.
+Ograniczenia: wszystkie trzy role muszą obecnie używać jednego dostawcy; mieszana mapa daje błąd `doctor`. Sam `doctor` nie potwierdza dostępności narzędzi obu pomocników w sesji dostawcy — sprawdź je zgodnie z README. W Claude Code niezależny Quality Officer przez `Agent(quality-officer-client)`, dowody i verified receipt poprzedzają `delivered`, a jawny odbiór operatora poprzedza `done`. OpenCode pozostaje w `in_review` niezależnie od dostępności Agent, bez wspieranego przejścia do `delivered`; pełny odbiór wymaga ścieżki Claude Code. Codex wymaga integracji Agent, niezależnej recenzji i verified receipt; brak Agent pozostawia kartę w `in_review` do naprawy CEO/CR. Builder nie recenzuje własnej pracy.
+
+Biblioteki ESM w `dist/` obejmują parser konfiguracji `engine-config`, wyniki ról `role-results`, SDK tablicy `planer-client` ([API silnika](ENGINE-API.md)), rejestr ról, walidację zasiewu i reguły intencji, wybór i zakres pracy, ruchy i odzyskiwanie stanu, tożsamość prób/testera, środowisko Workera, źródła recenzji, wyniki CI oraz adaptery Claude/Codex/OpenCode i eksport sesji. `robisie.config.json` opisuje instancję: projekt, tory, katalog stanu i role; sekcja `engine` opisuje repo, gałąź, komendy, wymagane kontrole i sposób dostarczenia. Parser konfiguracji niczego nie uruchamia. Instalacja, import bibliotek i obecność pomocników nie dowodzą uruchomienia silnika ani pełnej autonomicznej pętli klienta.
+
+Powrót lokalny: zachowaj poprzedni tgz i kopię własnej konfiguracji; w tym samym projekcie zainstaluj go przez `npm i ./robisie-0.1.0.tgz`, potem `npx robisie init --agent <agent>` i `npx robisie doctor`. Najpierw sprawdź zgodność kontraktu. Test 0.1.0 → syntetyczne 0.1.1 → 0.1.0 jest lokalną próbą reinstalacji i powrotu, nie rollbackiem opublikowanych wydań. `npx robisie uninstall` usuwa zarejestrowane wpisy/bloki robisie, nie przywraca starych wpisów robisie; cofa niezmienione role, a zmienione przez użytkownika pozostawia z ostrzeżeniem. Backupy pozostają i mogą zawierać klucz — chroń je. Bez zapisu instalacji komenda nie usuwa pliku klucza; odmowa sprawdzenia konfiguracji Codex następuje przed usunięciem klucza, a po tym sprawdzeniu klucz jest usuwany nawet przy późniejszym błędzie. Kod różny od zera wymaga rozwiązania wskazanego problemu. Uninstall nie unieważnia klucza na serwerze (zrób to osobno w Connect); `npm uninstall robisie` usuwa paczkę z projektu, zgodnie z README.
 
 Ten dokument nie potwierdza tagu, GitHub Release ani publikacji npm.
 
@@ -18,12 +22,81 @@ Ten dokument nie potwierdza tagu, GitHub Release ani publikacji npm.
 
 The client connects Claude Code, Codex CLI or OpenCode to the robisie board. `init` installs MCP configuration, CEO, Builder and Quality Officer roles and the `client-launch-context` and `ceo-client-launcher` helper commands. `doctor` checks the connection and installation; `uninstall` removes recorded changes. Other settings and instructions survive; first backups retain the state before installation.
 
-Requirements: Node.js >=20, npm, an installed agent with your own AI provider access, a robisie connection and a Connect key. Windows requires WSL (POSIX paths). The client supports server contract 1.x, currently 1.0.0. `init` refuses another major, such as 2.0.0, before writing; an older client cannot downgrade the server contract.
+Requirements for 0.1: macOS or Linux, Node.js >=20, npm, an installed agent with your own AI provider access, a robisie connection and a Connect key. Windows/WSL support is unverified. The client supports server contract 1.x, currently 1.0.0. `init` refuses another major, such as 2.0.0, before writing; an older client cannot downgrade the server contract.
+
+Availability: install from npm with `npm i robisie` in the agent working directory; follow [README](README.en.md) for the next steps.
 
-Availability: the reported `npm view robisie` result on 20 October 2026 was E404: `robisie` cannot be downloaded from npm. No fresh registry check was performed here. Without a locally installed package, `npx robisie` and the helpers cannot start. Install a supplied `robisie-0.1.0.tgz` with `npm i ./robisie-0.1.0.tgz` in the project and run the agent from that directory so `npx -y robisie@0.1.0 mcp <name>` can resolve the local package. See [README](README.md).
+After human approval of a card confirmed in `ready`, the CEO starts the Builder by default through `ceo-client-launcher` → `spawn_builder`. Manual startup in a new terminal is only the operator's explicit choice; a helper error must be reported and its cause resolved before retrying, without automatically switching to manual startup. The installer itself starts neither background services nor the Builder.
 
-Limitations: all three roles currently need the same provider; `doctor` rejects mixed assignments. The operator starts the Builder in a new terminal and explicitly accepts the result after independent review. Installation does not prove the complete customer loop or autonomous execution.
+Limitations: all three roles currently need the same provider; `doctor` rejects mixed assignments. `doctor` alone does not confirm that both helpers' tools are available in the provider session — check them as described in README. In Claude Code, an independent Quality Officer through `Agent(quality-officer-client)`, evidence and a verified receipt precede `delivered`; explicit operator acceptance precedes `done`. OpenCode stays in `in_review` regardless of Agent availability, with no supported transition to `delivered`; full acceptance requires the Claude Code path. Codex requires Agent integration, independent review and a verified receipt; without Agent, the card stays in `in_review` pending CEO/CR repair. The Builder does not review its own work.
 
-Local return: retain the previous tgz and a copy of your configuration. Install it in the same project with `npm i ./robisie-0.1.0.tgz`, then run `npx robisie init --agent <agent>` and `npx robisie doctor`, checking contract compatibility first. The 0.1.0 → synthetic 0.1.1 → 0.1.0 test is a local reinstall and return rehearsal, not a rollback of published releases. `npx robisie uninstall` restores unchanged role files from before installation, keeps backups and leaves user-edited roles with a warning. Backups may contain a key; protect them.
+The ESM libraries in `dist/` include the `engine-config` configuration parser, `role-results` role outcomes, the `planer-client` board SDK ([engine API](ENGINE-API.md)), role registry, seed validation and intent rules, selection and dispatch scope, outcome moves and recovery, attempt/tester identity, Worker environment, review source packets, CI results, Claude/Codex/OpenCode adapters and session export. `robisie.config.json` describes an instance: project, tracks, state directory and roles; its `engine` section describes the repository, branch, commands, required checks and delivery mode. Parsing configuration starts nothing. Installation, library imports and shipped helpers do not prove a running engine or a complete autonomous customer loop.
+
+Local return: retain the previous tgz and a copy of your configuration. Install it in the same project with `npm i ./robisie-0.1.0.tgz`, then run `npx robisie init --agent <agent>` and `npx robisie doctor`, checking contract compatibility first. The 0.1.0 → synthetic 0.1.1 → 0.1.0 test is a local reinstall and return rehearsal, not a rollback of published releases. `npx robisie uninstall` removes recorded robisie entries/blocks without restoring old robisie entries; it restores unchanged role files and leaves user-edited roles with a warning. Backups remain and may contain a key; protect them. Without an installation record, the key file is not removed; Codex configuration refusal happens before key deletion, while after that check the key is removed even if a later step fails. A nonzero exit requires resolving the reported problem. Uninstall does not revoke the server key (revoke it separately in Connect); `npm uninstall robisie` removes the project package, as described in README.
 
 This document does not confirm a tag, GitHub Release or npm publication.
+
+## Wspólny przykład PL/EN / Shared PL/EN example
+
+Przykład zwraca konfigurację instancji bez uruchamiania silnika; `./state` jest liczone względem pliku konfiguracji. / The example returns instance configuration without starting the engine; `./state` is resolved relative to the configuration file.
+
+<!-- release-surface:example:start -->
+```js
+import { parseConfig } from 'robisie/dist/engine-config.js';
+
+export const config = parseConfig({
+  project: 'example-project',
+  tracks: [{ id: 'example-track', name: 'Praca' }],
+  stateDir: './state',
+}, '/example/robisie.config.json');
+```
+<!-- release-surface:example:end -->
+
+## Zawartość paczki / Package inventory
+
+Ścieżki bibliotek/CLI i pomocników; wpis przy launcherze wskazuje zarejestrowane narzędzie. Deklaracje `.d.ts` mogą towarzyszyć modułom JS. / Library/CLI and helper paths; the launcher entry names its registered tool. Type declarations may accompany JS modules.
+
+<!-- release-surface:inventory:start -->
+- `dist/active-recovery.js`
+- `dist/agents.js`
+- `dist/attempt-identity.js`
+- `dist/ci-failure-result.js`
+- `dist/claude-headless.js`
+- `dist/cli.js`
+- `dist/commands.js`
+- `dist/constants.js`
+- `dist/context.js`
+- `dist/dependency-readiness.js`
+- `dist/dispatch-scope.js`
+- `dist/done-evidence.js`
+- `dist/engine-config.js`
+- `dist/fsops.js`
+- `dist/helpers.js`
+- `dist/intent-rules/admission.js`
+- `dist/intent-rules/done-when-roles.js`
+- `dist/intent-rules/hooks.js`
+- `dist/k3-codex-role.js`
+- `dist/manifest.js`
+- `dist/mcp.js`
+- `dist/opencode-result.js`
+- `dist/opencode-review-guard.js`
+- `dist/opencode-session-export.js`
+- `dist/outcome-moves.js`
+- `dist/planer-client.js`
+- `dist/restart-recovery.js`
+- `dist/review-source-packet.js`
+- `dist/role-registry.js`
+- `dist/role-results.js`
+- `dist/roles.js`
+- `dist/seed-validation.js`
+- `dist/selection-result.js`
+- `dist/sparse-policy.js`
+- `dist/tester-identity.js`
+- `dist/worker-env.js`
+- `helpers/ceo-client-launcher-mcp.mjs` → `spawn_builder`
+- `helpers/client-launch-context-mcp.mjs`
+- `helpers/client-spawn-session.sh`
+- `helpers/client-spawn.sh`
+- `helpers/lib/client-review-receipt.mjs`
+- `helpers/lib/client-spawn-failure.mjs`
+<!-- release-surface:inventory:end -->

package/docs/RELEASE-0.1.1.md

@@ -0,0 +1,110 @@
+# robisie 0.1.1 — wydanie utrzymaniowe / maintenance release
+
+## Polski
+
+0.1.1 zbiera poprawki instalacji, uprawnień prywatnych plików, kopii zapasowych, odmowy przekierowania MCP z poświadczeniem, bezpiecznej diagnostyki i odzyskiwania oraz bibliotek API klienta. [CHANGELOG](https://github.com/chuppa12/robisie-app/blob/main/packages/client/CHANGELOG.md) wymienia dokładnie 45 kart z lokalnym odbiorem TAK (E3: 26, E4: 4, E5: 3, E6: 12). Lokalny odbiór nie potwierdza publikacji ani działania wersji pobranej z npm.
+
+Ograniczenia odbioru 0.1.1: `805aad70` — krok 5 z rolami i pomocnikami w prawdziwej sesji Claude Code nie został sprawdzony; pomocniki sprawdzono bezpośrednio przez `robisie mcp`. `80931e36` — profil Bash sprawdzono z symulacją macOS na Linuksie; rzeczywisty przebieg na Macu pozostaje otwarty. Dla `9d10bca2` i `13bafb12` lokalny odbiór dotyczy konsumenta paczki; integracja z usługą klienta to osobny odbiór. Odmowa `init` może pozostawić częściową instalację (`1bd3a86d`); rozwiąż zgłoszony problem i sprawdź stan, zanim ponowisz. Żadna z tych granic nie znika po instalacji.
+
+Klient łączy Claude Code, Codex CLI lub OpenCode z tablicą robisie. `init` instaluje konfigurację MCP, role CEO, Builder i Quality Officer oraz polecenia pomocników `client-launch-context` i `ceo-client-launcher`; `doctor` sprawdza połączenie i instalację, a `uninstall` usuwa zarejestrowane zmiany. Obce ustawienia i instrukcje pozostają; pierwsze kopie zapasowe zachowują stan sprzed instalacji.
+
+Wymagania 0.1: macOS lub Linux, Node.js >=20, npm i własny zainstalowany agent z dostępem do dostawcy AI; połączenie z robisie i klucz z Connect. Windows/WSL nie mają zweryfikowanego wsparcia. Klient rozumie kontrakt serwera 1.x, obecnie 1.0.0. Inny major, np. 2.0.0, jest odrzucany przed zapisem przez `init`; starszy klient nie obniża kontraktu serwera.
+
+Instalacja kandydata: `npm i ./robisie-0.1.1.tgz`; po potwierdzonej publikacji: `npm i robisie@0.1.1` w katalogu pracy agenta; dalsze kroki opisuje [README](README.md).
+
+Po zgodzie człowieka na kartę potwierdzoną w `ready` CEO domyślnie uruchamia Buildera przez `ceo-client-launcher` → `spawn_builder`. Ręczny start w nowym terminalu jest wyłącznie jawnym wyborem operatora; błąd pomocnika wymaga zgłoszenia i naprawy przyczyny przed ponowieniem, bez automatycznego przejścia na ręczny start. Instalator sam nie startuje usług w tle ani Buildera.
+
+Ograniczenia: wszystkie trzy role muszą obecnie używać jednego dostawcy; mieszana mapa daje błąd `doctor`. Sam `doctor` nie potwierdza dostępności narzędzi obu pomocników w sesji dostawcy — sprawdź je zgodnie z README. W Claude Code niezależny Quality Officer przez `Agent(quality-officer-client)`, dowody i verified receipt poprzedzają `delivered`, a jawny odbiór operatora poprzedza `done`. OpenCode pozostaje w `in_review` niezależnie od dostępności Agent, bez wspieranego przejścia do `delivered`; pełny odbiór wymaga ścieżki Claude Code. Codex wymaga integracji Agent, niezależnej recenzji i verified receipt; brak Agent pozostawia kartę w `in_review` do naprawy CEO/CR. Builder nie recenzuje własnej pracy.
+
+Biblioteki ESM w `dist/` obejmują parser konfiguracji `engine-config`, wyniki ról `role-results`, SDK tablicy `planer-client` ([API silnika](ENGINE-API.md)), rejestr ról, politykę sparse (`sparse-policy`), walidację zasiewu i reguły intencji, wybór i zakres pracy, ruchy i odzyskiwanie stanu, tożsamość prób/testera, środowisko Workera, źródła recenzji, wyniki CI oraz adaptery Claude/Codex/OpenCode i eksport sesji. `robisie.config.json` opisuje instancję: projekt, tory, katalog stanu i role; sekcja `engine` opisuje repo, gałąź, komendy, wymagane kontrole i sposób dostarczenia. Parser konfiguracji niczego nie uruchamia. Instalacja, import bibliotek i obecność pomocników nie dowodzą uruchomienia silnika ani pełnej autonomicznej pętli klienta.
+
+Powrót lokalny: zachowaj poprzedni tgz i kopię własnej konfiguracji; w tym samym projekcie zainstaluj go przez `npm i ./robisie-0.1.0.tgz`, potem `npx robisie init --agent <agent>` i `npx robisie doctor`. Najpierw sprawdź zgodność kontraktu. Test 0.1.0 → syntetyczne 0.1.1 → 0.1.0 jest lokalną próbą reinstalacji i powrotu, nie rollbackiem opublikowanych wydań. `npx robisie uninstall` usuwa zarejestrowane wpisy/bloki robisie, nie przywraca starych wpisów robisie; cofa niezmienione role, a zmienione przez użytkownika pozostawia z ostrzeżeniem. Backupy pozostają i mogą zawierać klucz — chroń je. Bez zapisu instalacji komenda nie usuwa pliku klucza; odmowa sprawdzenia konfiguracji Codex następuje przed usunięciem klucza, a po tym sprawdzeniu klucz jest usuwany nawet przy późniejszym błędzie. Kod różny od zera wymaga rozwiązania wskazanego problemu. Uninstall nie unieważnia klucza na serwerze (zrób to osobno w Connect); `npm uninstall robisie` usuwa paczkę z projektu, zgodnie z README.
+
+Ten dokument nie potwierdza tagu, GitHub Release ani publikacji npm.
+
+## English
+
+0.1.1 collects fixes for installation, private file permissions, backups, refusal of credential-bearing MCP redirects, safe diagnostics and recovery, plus client API libraries. [CHANGELOG](https://github.com/chuppa12/robisie-app/blob/main/packages/client/CHANGELOG.md) lists exactly 45 locally accepted cards (E3: 26, E4: 4, E5: 3, E6: 12). Local acceptance establishes neither publication nor behavior of the version installed from npm.
+
+0.1.1 acceptance limits: step 5 of `805aad70`, covering roles and helpers in a real Claude Code session, remains unverified; helpers were checked directly through `robisie mcp`. The Bash profile for `80931e36` was checked with macOS simulated on Linux; the real Mac run remains open. Local acceptance for `9d10bca2` and `13bafb12` covers the package consumer; integration with the customer service requires separate acceptance. A refused `init` may leave a partial installation (`1bd3a86d`); resolve the reported problem and check its state before retrying. Installation does not remove these limits.
+
+The client connects Claude Code, Codex CLI or OpenCode to the robisie board. `init` installs MCP configuration, CEO, Builder and Quality Officer roles and the `client-launch-context` and `ceo-client-launcher` helper commands. `doctor` checks the connection and installation; `uninstall` removes recorded changes. Other settings and instructions survive; first backups retain the state before installation.
+
+Requirements for 0.1: macOS or Linux, Node.js >=20, npm, an installed agent with your own AI provider access, a robisie connection and a Connect key. Windows/WSL support is unverified. The client supports server contract 1.x, currently 1.0.0. `init` refuses another major, such as 2.0.0, before writing; an older client cannot downgrade the server contract.
+
+Candidate installation: `npm i ./robisie-0.1.1.tgz`; after confirmed publication: `npm i robisie@0.1.1` in the agent working directory; follow [README](README.en.md) for the next steps.
+
+After human approval of a card confirmed in `ready`, the CEO starts the Builder by default through `ceo-client-launcher` → `spawn_builder`. Manual startup in a new terminal is only the operator's explicit choice; a helper error must be reported and its cause resolved before retrying, without automatically switching to manual startup. The installer itself starts neither background services nor the Builder.
+
+Limitations: all three roles currently need the same provider; `doctor` rejects mixed assignments. `doctor` alone does not confirm that both helpers' tools are available in the provider session — check them as described in README. In Claude Code, an independent Quality Officer through `Agent(quality-officer-client)`, evidence and a verified receipt precede `delivered`; explicit operator acceptance precedes `done`. OpenCode stays in `in_review` regardless of Agent availability, with no supported transition to `delivered`; full acceptance requires the Claude Code path. Codex requires Agent integration, independent review and a verified receipt; without Agent, the card stays in `in_review` pending CEO/CR repair. The Builder does not review its own work.
+
+The ESM libraries in `dist/` include the `engine-config` configuration parser, `role-results` role outcomes, the `planer-client` board SDK ([engine API](ENGINE-API.md)), role registry, sparse policy (`sparse-policy`), seed validation and intent rules, selection and dispatch scope, outcome moves and recovery, attempt/tester identity, Worker environment, review source packets, CI results, Claude/Codex/OpenCode adapters and session export. `robisie.config.json` describes an instance: project, tracks, state directory and roles; its `engine` section describes the repository, branch, commands, required checks and delivery mode. Parsing configuration starts nothing. Installation, library imports and shipped helpers do not prove a running engine or a complete autonomous customer loop.
+
+Local return: retain the previous tgz and a copy of your configuration. Install it in the same project with `npm i ./robisie-0.1.0.tgz`, then run `npx robisie init --agent <agent>` and `npx robisie doctor`, checking contract compatibility first. The 0.1.0 → synthetic 0.1.1 → 0.1.0 test is a local reinstall and return rehearsal, not a rollback of published releases. `npx robisie uninstall` removes recorded robisie entries/blocks without restoring old robisie entries; it restores unchanged role files and leaves user-edited roles with a warning. Backups remain and may contain a key; protect them. Without an installation record, the key file is not removed; Codex configuration refusal happens before key deletion, while after that check the key is removed even if a later step fails. A nonzero exit requires resolving the reported problem. Uninstall does not revoke the server key (revoke it separately in Connect); `npm uninstall robisie` removes the project package, as described in README.
+
+This document does not confirm a tag, GitHub Release or npm publication.
+
+## Wspólny przykład PL/EN / Shared PL/EN example
+
+Przykład zwraca konfigurację instancji bez uruchamiania silnika; `./state` jest liczone względem pliku konfiguracji. / The example returns instance configuration without starting the engine; `./state` is resolved relative to the configuration file.
+
+<!-- release-surface:example:start -->
+```js
+import { parseConfig } from 'robisie/dist/engine-config.js';
+
+export const config = parseConfig({
+  project: 'example-project',
+  tracks: [{ id: 'example-track', name: 'Praca' }],
+  stateDir: './state',
+}, '/example/robisie.config.json');
+```
+<!-- release-surface:example:end -->
+
+## Zawartość paczki / Package inventory
+
+Ścieżki bibliotek/CLI i pomocników; wpis przy launcherze wskazuje zarejestrowane narzędzie. Deklaracje `.d.ts` mogą towarzyszyć modułom JS. / Library/CLI and helper paths; the launcher entry names its registered tool. Type declarations may accompany JS modules.
+
+<!-- release-surface:inventory:start -->
+- `dist/active-recovery.js`
+- `dist/agents.js`
+- `dist/attempt-identity.js`
+- `dist/ci-failure-result.js`
+- `dist/claude-headless.js`
+- `dist/cli.js`
+- `dist/commands.js`
+- `dist/constants.js`
+- `dist/context.js`
+- `dist/dependency-readiness.js`
+- `dist/dispatch-scope.js`
+- `dist/done-evidence.js`
+- `dist/engine-config.js`
+- `dist/fsops.js`
+- `dist/helpers.js`
+- `dist/intent-rules/admission.js`
+- `dist/intent-rules/done-when-roles.js`
+- `dist/intent-rules/hooks.js`
+- `dist/k3-codex-role.js`
+- `dist/manifest.js`
+- `dist/mcp.js`
+- `dist/opencode-result.js`
+- `dist/opencode-review-guard.js`
+- `dist/opencode-session-export.js`
+- `dist/outcome-moves.js`
+- `dist/planer-client.js`
+- `dist/restart-recovery.js`
+- `dist/review-source-packet.js`
+- `dist/role-registry.js`
+- `dist/role-results.js`
+- `dist/roles.js`
+- `dist/seed-validation.js`
+- `dist/selection-result.js`
+- `dist/sparse-policy.js`
+- `dist/tester-identity.js`
+- `dist/worker-env.js`
+- `helpers/ceo-client-launcher-mcp.mjs` → `spawn_builder`
+- `helpers/client-launch-context-mcp.mjs`
+- `helpers/client-spawn-session.sh`
+- `helpers/client-spawn.sh`
+- `helpers/lib/client-review-receipt.mjs`
+- `helpers/lib/client-spawn-failure.mjs`
+<!-- release-surface:inventory:end -->

package/helpers/ceo-client-launcher-mcp.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 import { execFile } from "node:child_process";
-import { accessSync, constants, lstatSync, realpathSync } from "node:fs";
-import { resolve } from "node:path";
+import { accessSync, constants, lstatSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 
@@ -16,6 +16,7 @@ import { verifyReviewReceipt } from "./lib/client-review-receipt.mjs";
 import { createSpawnFailureRecord } from "./lib/client-spawn-failure.mjs";
 
 const execFileAsync = promisify(execFile);
+const CLIENT_SPAWN_PATH = fileURLToPath(new URL("./client-spawn.sh", import.meta.url));
 const UUID_PATTERN = /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/;
 const HISTORY_KEY_PATTERN =
   /^quality_review_[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/u;
@@ -23,12 +24,12 @@ const SHA_PATTERN = /^[0-9a-f]{64}$/u;
 const PLANER_ENDPOINT = new URL("https://robisie.app/api/mcp");
 const MCP_CALL_TIMEOUT_MS = 30_000;
 const MCP_CLOSE_TIMEOUT_MS = 5_000;
-const AGENT_COMMAND =
-  "claude --print --agent manager-builder-client --permission-mode dontAsk 'Start the assigned client task now. Read launch context first and follow the role contract through review handoff.'";
+const BUILDER_PROMPT = "Start the assigned client task now. Read launch context first and follow the role contract through review handoff.";
 const RESERVATION_TIMEOUT_MS = 30_000;
 const RESERVATION_POLL_MS = 500;
 const BASE_ENV_NAMES = [
   "HOME",
+  "CODEX_HOME",
   "LANG",
   "LC_ALL",
   "LC_CTYPE",
@@ -40,6 +41,7 @@ const BASE_ENV_NAMES = [
   "TMPDIR",
   "USER",
   "XDG_DATA_DIRS",
+  "XDG_CONFIG_HOME",
 ];
 const LAUNCH_ENV_NAMES = [
   ...BASE_ENV_NAMES,
@@ -91,6 +93,32 @@ export function validateLauncherResult(value, cardRef) {
   return result;
 }
 
+function builderCommand(environment) {
+  let configDir;
+  let provider;
+  try {
+    if (!environment.XDG_CONFIG_HOME && !environment.HOME) {
+      throw new Error("configuration directory is missing");
+    }
+    configDir = join(environment.XDG_CONFIG_HOME || join(environment.HOME, ".config"), "robisie");
+    const manifest = JSON.parse(readFileSync(join(configDir, "manifest.json"), "utf8"));
+    // Match init's migration of legacy single-provider installs; never guess an ambiguous assignment.
+    provider = Object.hasOwn(manifest, "roleProviders")
+      ? manifest.roleProviders?.builder
+      : Array.isArray(manifest.agents) && manifest.agents.length === 1 ? manifest.agents[0] : undefined;
+  } catch {
+    throw new Error("Builder configuration could not be read; run npx robisie init");
+  }
+  if (!["claude", "codex", "opencode"].includes(provider)) {
+    throw new Error("Builder provider is missing or invalid; configure builder with npx robisie init --role");
+  }
+  if (provider === "claude") return `claude --print --agent manager-builder-client --permission-mode dontAsk '${BUILDER_PROMPT}'`;
+  if (provider === "opencode") return `opencode run --agent manager-builder-client '${BUILDER_PROMPT}'`;
+  const rolePath = join(configDir, "roles", "codex", "manager-builder-client.md");
+  const prompt = `Act as the robisie Builder: read ${rolePath} in full and follow it. ${BUILDER_PROMPT}`;
+  return `codex exec '${prompt.replace(/'/g, "'\\''")}'`;
+}
+
 export function buildLaunchContract(cardRef, projectContext, sourceEnvironment) {
   const validatedCardRef = validateCardRef(cardRef);
   if (
@@ -101,12 +129,12 @@ export function buildLaunchContract(cardRef, projectContext, sourceEnvironment)
     throw new Error("project context must be one absolute directory path");
   }
   return {
-    file: resolve(projectContext, "scripts/client-spawn.sh"),
+    file: CLIENT_SPAWN_PATH,
     args: [validatedCardRef],
     cwd: projectContext,
     env: {
       ...copyLaunchEnvironment(sourceEnvironment),
-      ROBISIE_AGENT_COMMAND: AGENT_COMMAND,
+      ROBISIE_AGENT_COMMAND: builderCommand(sourceEnvironment),
       ROBISIE_PROJECT_CONTEXT: projectContext,
     },
   };
@@ -380,10 +408,10 @@ function validateRuntimeContract(contract) {
   if (!contextStat.isDirectory() || contextStat.isSymbolicLink()) {
     throw new Error("project context must be a real directory");
   }
-  const expectedLauncher = resolve(realpathSync(contract.cwd), "scripts/client-spawn.sh");
+  const expectedLauncher = realpathSync(CLIENT_SPAWN_PATH);
   const actualLauncher = realpathSync(contract.file);
   if (actualLauncher !== expectedLauncher) {
-    throw new Error("launcher resolves outside the selected project context");
+    throw new Error("launcher resolves outside the helper module location");
   }
   const launcherStat = lstatSync(actualLauncher);
   if (!launcherStat.isFile() || launcherStat.isSymbolicLink()) {