robisie 0.1.0 → 0.1.1

package/dist/selection-result.js

@@ -0,0 +1,144 @@
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+export function stripFence(text) {
+    let s = text.trim();
+    const lead = s.match(/^```(?:[a-zA-Z0-9]+)?\n?/);
+    if (lead)
+        s = s.slice(lead[0].length);
+    const trail = s.match(/\n?```\s*$/);
+    if (trail)
+        s = s.slice(0, s.length - trail[0].length);
+    return s.trim();
+}
+export function extractJsonObject(raw) {
+    const stripped = stripFence(raw);
+    try {
+        JSON.parse(stripped);
+        return stripped;
+    }
+    catch {
+        // Odpowiedź może zawierać prozę przed właściwym obiektem.
+    }
+    const starts = [];
+    const marker = /\{\s*"proposals"\s*:/g;
+    for (let match = marker.exec(stripped); match; match = marker.exec(stripped))
+        starts.push(match.index);
+    for (let candidateIndex = starts.length - 1; candidateIndex >= 0; candidateIndex -= 1) {
+        const start = starts[candidateIndex];
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let index = start; index < stripped.length; index += 1) {
+            const char = stripped[index];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (char === "\\")
+                    escaped = true;
+                else if (char === '"')
+                    inString = false;
+                continue;
+            }
+            if (char === '"') {
+                inString = true;
+                continue;
+            }
+            if (char === "{")
+                depth += 1;
+            else if (char === "}")
+                depth -= 1;
+            if (depth !== 0)
+                continue;
+            const candidate = stripped.slice(start, index + 1);
+            try {
+                const parsed = record(JSON.parse(candidate));
+                if (parsed && Array.isArray(parsed["proposals"]))
+                    return candidate;
+            }
+            catch {
+                break;
+            }
+            break;
+        }
+    }
+    return null;
+}
+export function parseProposals(raw, goals, nsIds = [], qualifyCard) {
+    const jsonText = extractJsonObject(raw);
+    if (jsonText === null)
+        return { ok: [], rejected: [], warnings: [], rawCount: 0, prose: raw.trim(), error: "nie-JSON: brak obiektu proposals" };
+    const stripped = stripFence(raw);
+    const proseIndex = stripped.lastIndexOf(jsonText);
+    const prose = proseIndex > 0 ? stripped.slice(0, proseIndex).trim() : "";
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch (error) {
+        return { ok: [], rejected: [], warnings: [], rawCount: 0, prose, error: `nie-JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const parsedRecord = record(parsed);
+    const arr = parsedRecord?.["proposals"];
+    if (!Array.isArray(arr))
+        return { ok: [], rejected: [], warnings: [], rawCount: 0, prose, error: "brak pola proposals[]" };
+    const emptyReason = typeof parsedRecord?.["empty_reason"] === "string" ? parsedRecord["empty_reason"].trim() : "";
+    if (arr.length === 0 && !emptyReason && !prose)
+        return { ok: [], rejected: [], warnings: [], rawCount: 0, prose, error: "brak empty_reason dla zera" };
+    const canon = new Set(goals.map((g) => g.canon));
+    const nsCanon = new Set(nsIds.map((id) => id.trim().toUpperCase()).filter(Boolean));
+    const ok = [];
+    const rejected = [];
+    const warnings = [];
+    for (const it of arr) {
+        if (typeof it !== "object" || it === null || Array.isArray(it)) {
+            rejected.push({ title: "", reason: "propozycja nie jest obiektem" });
+            continue;
+        }
+        const p = it;
+        const title = String(p.title ?? "").trim();
+        if (title.length < 10) {
+            rejected.push({ title, reason: "tytuł < 10 znaków" });
+            continue;
+        }
+        if (!canon.has(String(p.servesGoal))) {
+            rejected.push({ title, reason: `servesGoal "${String(p.servesGoal)}" poza kanonem ${[...canon].join("|")}` });
+            continue;
+        }
+        const goalRef = String(p.goal_ref ?? "").trim();
+        if (!goalRef) {
+            rejected.push({ title, reason: "brak goal_ref" });
+            continue;
+        }
+        const dw = Array.isArray(p.done_when) ? p.done_when.map(String).filter((s) => s.trim().length > 5) : [];
+        if (dw.length === 0) {
+            rejected.push({ title, reason: "brak mierzalnego done_when" });
+            continue;
+        }
+        const scope = Array.isArray(p.scope) ? p.scope.map(String) : [];
+        const qualification = qualifyCard({ id: "selector-proposal", title, details: { scope } });
+        if (!qualification.effort || !qualification.trackName) {
+            rejected.push({ title, reason: qualification.reasons.join("; ") });
+            continue;
+        }
+        const requestedNS = typeof p.servesNS === "string" ? p.servesNS.trim().toUpperCase() : "";
+        const servesNS = requestedNS && nsCanon.has(requestedNS) ? requestedNS : null;
+        if (servesNS === null) {
+            rejected.push({ title, reason: "brak servesNS z kanonu North Star" });
+            continue;
+        }
+        const nsProof = typeof p.ns_proof === "string" ? p.ns_proof.trim() : "";
+        if (!nsProof) {
+            rejected.push({ title, reason: "brak ns_proof" });
+            continue;
+        }
+        ok.push({
+            title, servesGoal: String(p.servesGoal), servesNS, ns_proof: nsProof, goal_ref: goalRef, why_now: String(p.why_now ?? "").trim(),
+            done_when: dw, scope, out: Array.isArray(p.out) ? p.out.map(String) : [],
+            codex_effort: qualification.effort, proposed_track: qualification.trackName, qualification,
+        });
+    }
+    return { ok, rejected, warnings, rawCount: arr.length, prose, ...(emptyReason ? { empty_reason: emptyReason } : {}) };
+}

package/dist/sparse-policy.d.ts

@@ -0,0 +1,8 @@
+/** Null oznacza nieczytelny/pusty scope i zachowanie pełnego checkoutu. Pusta tablica = tylko pliki korzeniowe. */
+export declare function sparseDirectoriesFromScope(scope: unknown): string[] | null;
+/** Odczyt całego HEAD nie rezerwuje zakresu zapisu karty. */
+export declare const SPARSE_EXCLUDED_DIRS: readonly [];
+export declare function sparseReadSet(scope: unknown, topLevelDirectories: readonly string[]): string[] | null;
+export declare function sparseDirectoryError(directory: string): string;
+/** Chroni przed plikiem-widmem utworzonym w katalogu, którego karta nie materializuje. */
+export declare function sparseScopeWriteError(scope: unknown, untrackedPaths: readonly string[]): string | null;

package/dist/sparse-policy.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+/** Null oznacza nieczytelny/pusty scope i zachowanie pełnego checkoutu. Pusta tablica = tylko pliki korzeniowe. */
+export function sparseDirectoriesFromScope(scope) {
+    if (!Array.isArray(scope) || scope.length === 0 || scope.some((entry) => typeof entry !== "string"))
+        return null;
+    const directories = new Set();
+    for (const entry of scope) {
+        const token = entry.trim().split(/\s+/, 1)[0].replace(/`/g, "").replace(/:\d+(?:[-:]\d+)*$/, "");
+        if (!token || path.posix.isAbsolute(token))
+            return null;
+        const normalized = path.posix.normalize(token);
+        if (normalized === "." || normalized === ".." || normalized.startsWith("../"))
+            return null;
+        if (token.includes("/"))
+            directories.add(normalized.split("/", 1)[0]);
+    }
+    return [...directories].sort();
+}
+/** Odczyt całego HEAD nie rezerwuje zakresu zapisu karty. */
+export const SPARSE_EXCLUDED_DIRS = [];
+export function sparseReadSet(scope, topLevelDirectories) {
+    const scopedDirectories = sparseDirectoriesFromScope(scope);
+    if (scopedDirectories === null)
+        return null;
+    const excluded = new Set(SPARSE_EXCLUDED_DIRS);
+    const readSet = new Set(topLevelDirectories.filter((directory) => directory && !excluded.has(directory)));
+    for (const directory of scopedDirectories)
+        readSet.add(directory);
+    return [...readSet].sort();
+}
+export function sparseDirectoryError(directory) {
+    return `katalog \`${directory}/\` poza sparse checkout — dopisz go do \`details.scope\` karty`;
+}
+/** Chroni przed plikiem-widmem utworzonym w katalogu, którego karta nie materializuje. */
+export function sparseScopeWriteError(scope, untrackedPaths) {
+    const allowed = sparseDirectoriesFromScope(scope);
+    if (allowed === null)
+        return null;
+    const allowedSet = new Set(allowed);
+    for (const candidate of untrackedPaths) {
+        const normalized = path.posix.normalize(candidate);
+        if (path.posix.isAbsolute(normalized) || normalized === ".." || normalized.startsWith("../"))
+            continue;
+        const segments = normalized.split("/");
+        if (segments.length > 1 && !allowedSet.has(segments[0]))
+            return sparseDirectoryError(segments[0]);
+    }
+    return null;
+}

package/dist/tester-identity.d.ts

@@ -0,0 +1,11 @@
+type CardLike = {
+    id: string;
+    details?: Record<string, unknown> | null;
+};
+export declare const TESTER_IDENTITY_DETAILS_KEYS: readonly ["landed", "land_receipt", "decision_queue"];
+export declare const TESTER_IDENTITY_EVENT_FIELDS: readonly ["card_id", "event_type", "proof"];
+/** Recover only a unique receipt or a card-labelled commit already on main. No fetch. */
+export declare function resolveTesterLandedSha(card: CardLike, git: (args: string[]) => string): string | null;
+export declare function validTestSha(value: unknown): value is string;
+export declare function landedSha(card: CardLike): string | null;
+export {};

package/dist/tester-identity.js

@@ -0,0 +1,53 @@
+export const TESTER_IDENTITY_DETAILS_KEYS = ["landed", "land_receipt", "decision_queue"];
+export const TESTER_IDENTITY_EVENT_FIELDS = ["card_id", "event_type", "proof"];
+const recordValue = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+/** Recover only a unique receipt or a card-labelled commit already on main. No fetch. */
+export function resolveTesterLandedSha(card, git) {
+    const existing = landedSha(card);
+    if (existing)
+        return existing;
+    try {
+        const details = card.details ?? {};
+        const landed = recordValue(details.landed);
+        const candidates = [recordValue(landed.receipt).sha, landed.merge_sha, landed.merge_commit, recordValue(details.land_receipt).sha];
+        for (const raw of Object.values(recordValue(details.decision_queue))) {
+            const event = recordValue(raw);
+            const proof = recordValue(event.proof);
+            if (event.card_id === card.id && event.event_type === "land" && proof.key === "landed")
+                candidates.push(recordValue(proof.value).sha);
+        }
+        const receipts = [...new Set(candidates.filter((value) => validTestSha(value)))];
+        if (receipts.length > 1)
+            return null;
+        if (receipts.length === 1) {
+            git(["merge-base", "--is-ancestor", receipts[0], "origin/main"]);
+            return receipts[0];
+        }
+        const branch = `masz-${card.id.slice(0, 8)}`;
+        // Bound visited commits, not grep matches: --grep could walk all of main.
+        const parts = git(["log", "origin/main", "--first-parent", "--max-count=200", "--format=%H%x00%B%x00"]).split("\0");
+        const escaped = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const matches = new RegExp(`(^|[^a-zA-Z0-9_-])(?:${escaped(card.id)}|${escaped(branch)})(?=$|[^a-zA-Z0-9_-])`);
+        const commits = [];
+        for (let index = 0; index + 1 < parts.length; index += 2) {
+            const sha = parts[index].trim(), message = parts[index + 1];
+            if (validTestSha(sha) && matches.test(message))
+                commits.push(sha);
+        }
+        return commits.length === 1 ? commits[0] : null;
+    }
+    catch (error) {
+        console.error(`tester identity ${card.id}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+export function validTestSha(value) {
+    return typeof value === "string" && /^[a-f0-9]{7,40}$/i.test(value);
+}
+export function landedSha(card) {
+    const landed = card.details?.landed;
+    return record(landed) && validTestSha(landed.sha) ? landed.sha : null;
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/worker-env.d.ts

@@ -0,0 +1,5 @@
+export declare function makeWorkerTmpdir(base?: string, identity?: string): string;
+/** The brief and child process must use this same path, with no per-command override. */
+export declare function workerTmpdirForBrief(env: NodeJS.ProcessEnv): string;
+/** Pass an already allocated directory only when retaining a task's existing ownership. */
+export declare function workerEnv(base: NodeJS.ProcessEnv, tmp?: string): NodeJS.ProcessEnv;

package/dist/worker-env.js

@@ -0,0 +1,34 @@
+import { mkdtempSync } from "node:fs";
+import path from "node:path";
+// Darwin's sockaddr_un has a 104-byte path budget, including the trailing NUL.
+const SOCKET_SUFFIX = `/tsx-4294967295/${"x".repeat(40)}`;
+export function makeWorkerTmpdir(base = "/tmp", identity = "") {
+    try {
+        if (!path.isAbsolute(base))
+            throw new Error("wymagana absolutna ścieżka bazowa");
+        if (identity && !/^[a-f0-9]{8}$/.test(identity))
+            throw new Error("niepoprawna tożsamość katalogu");
+        const prefix = path.join(base, `rw-${identity ? `${identity}-` : ""}`);
+        if (Buffer.byteLength(`${prefix}XXXXXX${SOCKET_SUFFIX}`) >= 104)
+            throw new Error("ścieżka za długa dla gniazda Unix");
+        // mkdtemp creates a unique directory with mode 0700, independently of the worktree.
+        return mkdtempSync(prefix);
+    }
+    catch (error) {
+        throw new Error(`ACTIONABLE: TMPDIR Workera: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** The brief and child process must use this same path, with no per-command override. */
+export function workerTmpdirForBrief(env) {
+    const tmp = env.TMPDIR;
+    if (!tmp || !path.isAbsolute(tmp) || env.TMP !== tmp || env.TEMP !== tmp) {
+        throw new Error("ACTIONABLE: sprzeczne TMPDIR/TMP/TEMP Workera");
+    }
+    return tmp;
+}
+/** Pass an already allocated directory only when retaining a task's existing ownership. */
+export function workerEnv(base, tmp = makeWorkerTmpdir()) {
+    const env = { ...base, TMPDIR: tmp, TMP: tmp, TEMP: tmp };
+    workerTmpdirForBrief(env);
+    return env;
+}

package/docs/ENGINE-API.md

@@ -0,0 +1,78 @@
+# API silnika z paczki robisie
+
+Po instalacji `npm i robisie` używaj publicznego importu `robisie/dist/planer-client.js` w module ESM. Nie potrzebujesz checkoutu aplikacji ani aliasów repozytorium. Poniższe bloki można zapisać jako osobne pliki `.mjs`; eksportują funkcje, a sam import nie wykonuje odczytów ani zapisów.
+
+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ń.
+
+## Odczyt i jednoznaczny wybór
+
+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.
+
+`detailsKeys` w `listTasks` oraz `include` w `getTask` są jawnymi listami kluczy, np. `detailsKeys: ['seed_brief']` i `include: ['seed_brief', 'scope']`. Puste `[]` oznacza brak `details` w wyniku. Wybrane `details` mogą być `null`; brak wybranego klucza nie oznacza błędu. SDK sam wysyła `full: true` w `list_tasks`. Przykład jawnie przekazuje wszystkie statusy, łącznie z `done`, które serwer domyślnie wyklucza z listy; dzięki temu można odczytać także zakończoną kartę po ID. `getTask` zwracające `null` oznacza brak karty. Wadliwa odpowiedź powoduje istniejący `PlanerClientError` SDK (np. `INVALID_RESPONSE`), bez normalizowania legacy ani dopisywania stanu HOLD. Funkcja przekazuje błąd callerowi i zamyka klienta w `finally`, także przy błędzie connect.
+
+<!-- engine-api:read:start -->
+```js
+import { PlanerClient } from 'robisie/dist/planer-client.js';
+
+export async function readCard(config, {
+  projectId, trackId, id, detailsKeys = [], include = [],
+} = {}) {
+  const client = new PlanerClient(config);
+  try {
+    await client.connect();
+    const projects = (await client.listProjects())
+      .filter(project => projectId === undefined || project.id === projectId);
+    if (projects.length !== 1) return { outcome: 'wybierz-jednoznacznie', stage: 'list_projects' };
+    const project = projects[0];
+    const tracks = (await client.listTracks({ projectId: project.id }))
+      .filter(track => trackId === undefined || track.id === trackId);
+    if (tracks.length !== 1) return { outcome: 'wybierz-jednoznacznie', stage: 'list_tracks' };
+    const track = tracks[0];
+    const tasks = (await client.listTasks({
+      projectId: project.id, trackId: track.id, detailsKeys,
+      statuses: ['draft', 'ready', 'in_progress', 'in_review', 'blocked', 'delivered', 'done'],
+    }))
+      .filter(task => id === undefined || task.id === id);
+    if (tasks.length !== 1) return { outcome: 'wybierz-jednoznacznie', stage: 'list_tasks' };
+    const task = await client.getTask({ id: tasks[0].id, include });
+    return { outcome: task === null ? 'brak-karty' : 'odczytano', task };
+  } finally {
+    await client.close();
+  }
+}
+```
+<!-- engine-api:read:end -->
+
+## Jeden append, osobny wynik odczytu
+
+Caller przekazuje rozpoznane `id` i `patch` do `appendCard(config, { id, patch })` dopiero po uzyskaniu zgody na ten zapis. `appendDetail` wykonuje jeden zapis i osobny readback tylko kluczy patcha. `write` jest potwierdzeniem zapisu, a `readback` wynikiem późniejszego odczytu. Gdy `readback.ok === false`, zachowaj `write`; nie powtarzaj append, aby naprawić odczyt. Caller może później wykonać wyłącznie dodatkowy `getTask({ id, include: Object.keys(patch) })`, przez połączonego klienta z `close` w `finally`.
+
+`PlanerClientError.uncertain === true` oznacza, że zapis mógł dojść do serwera mimo utraty odpowiedzi lub błędu narzędzia. Wynik `wynik-niepewny` kończy automatyczne pisanie. Caller odczytuje stan i podejmuje decyzję; funkcja nie ponawia append ani żadnej innej mutacji. Pozostałe błędy są przekazywane callerowi. Nie loguj konfiguracji ani argumentów z tokenem.
+
+<!-- engine-api:append:start -->
+```js
+import { PlanerClient, PlanerClientError } from 'robisie/dist/planer-client.js';
+
+export async function appendCard(config, { id, patch }) {
+  const client = new PlanerClient(config);
+  try {
+    await client.connect();
+    const result = await client.appendDetail({ id, patch });
+    return { outcome: 'zapis-potwierdzony', ...result };
+  } catch (error) {
+    if (error instanceof PlanerClientError && error.uncertain) {
+      return { outcome: 'wynik-niepewny', error };
+    }
+    throw error;
+  } finally {
+    await client.close();
+  }
+}
+```
+<!-- engine-api:append:end -->
+
+Serwer stosuje **płytki merge**: patch zastępuje całą wartość pod wskazanym kluczem, bez deep merge. `null` jest wartością literalną, a brak klucza w patchu nie kasuje dotychczasowej wartości. Przykładowo patch `{ notes: { nowa: 2 }, literal: null }` zastąpi całe poprzednie `notes`, zapisze literalne `null` i pozostawi inne klucze.
+
+Osobna operacja `updateTask({ id, status: 'ready', expected: { status: 'draft' } })` przekazuje warunek oczekiwanego statusu. Warunek, przejście statusu i uprawnienia rozstrzyga serwer; SDK nie implementuje własnego CAS. Powyższe przykłady nie wykonują update.
+
+SDK nie tworzy projektu ani karty, nie nadaje uprawnień, nie dowodzi odbioru `done` i nie uruchamia silnika. Potwierdzenie append nie jest dowodem wykonania zadania ani niezależnej recenzji. Role, odbiór i uruchomienie pracy wymagają ich własnych kontraktów.

package/docs/ENGINE-CONFIG.md

@@ -0,0 +1,115 @@
+# Konfiguracja silnika z paczki
+
+Ten przykład korzysta z modułu `robisie/dist/engine-config.js` z lokalnie
+zainstalowanej paczki `robisie`. Wymaga Node.js 20 lub nowszego. Odczytuje
+i waliduje plik; nie wykonuje komend z konfiguracji ani połączeń sieciowych.
+Nie uruchamia silnika w tle i nie zapewnia samodzielnej realizacji zadań.
+
+Opis operacji na tablicy znajdziesz w [API silnika](ENGINE-API.md),
+a konfigurację agenta i instalatora w [przewodniku klienta](README.md).
+
+## Zapisz konfigurację
+
+Zapisz poniższy blok jako `robisie.config.json`, np. w `config/setup/`.
+UUID projektu i toru są **fikcyjne** — nie wskazują rzeczywistych danych.
+Przed użyciem własnej konfiguracji podmień:
+
+- `project` na UUID swojego projektu; `tracks` na UUID i nazwy jego torów;
+- `engine.repo` na ścieżkę swojego repozytorium i `engine.branch` na jego gałąź;
+- `stateDir` na katalog stanu swojej instancji;
+- `engine.commands.test`, `lint`, `build` na własne programy i argumenty;
+- `engine.requiredChecks` na nazwy wymaganych kontroli CI;
+- `roles` na własne nazwy i dokładne formy ról, `coordinator.id` na swój
+  identyfikator koordynatora, a `owner.genitive` na dopełniacz imienia właściciela.
+
+`stateDir` i `engine.repo` są liczone względem **katalogu pliku konfiguracji**,
+nie katalogu, z którego uruchamiasz Node. Dla `config/setup/robisie.config.json`
+wartość `../repo with spaces` wskazuje `config/repo with spaces`.
+
+Każda komenda to niepuste **argv**: program, następnie osobne argumenty.
+Spacje w argumencie i metaznaki są danymi. Przykładowe `a b` i `$(never-run)`
+mają pozostać dosłowne; nie sklejaj argv w polecenie powłoki. Poniższy odczyt
+nie wykonuje nawet testu, lintowania ani budowania. Komendy są ilustracyjne
+i wymagają podmiany przed wykorzystaniem konfiguracji do wykonywania pracy.
+`delivery: "pr"` opisuje sposób dostarczenia; sam odczyt nie tworzy PR.
+
+Role silnika to `coordinator`, `owner`, `planner`, `advisor`.
+`forms` zawierają dosłowne formy z uwzględnieniem wielkości liter, a
+`owner.genitive` służy m.in. do zapisu „Efekt dla Ali”. To osobne ustawienia
+od `roleProviders` instalatora dla ról `ceo`, `builder`, `quality`.
+
+<!-- engine-config:json:start -->
+```json
+{
+  "project": "11111111-1111-4111-8111-111111111111",
+  "tracks": [
+    { "id": "22222222-2222-4222-8222-222222222222", "name": "Mój tor" }
+  ],
+  "stateDir": "../state with spaces",
+  "roles": {
+    "coordinator": { "id": "przystan", "name": "Przystań", "forms": ["Przystań", "Przystani"] },
+    "owner": { "name": "Ala", "forms": ["Ala", "Ali"], "genitive": "Ali" },
+    "planner": { "name": "Mapa", "forms": ["Mapa", "Mapy"] },
+    "advisor": { "name": "Latarnia", "forms": ["Latarnia", "Latarni"] }
+  },
+  "engine": {
+    "repo": "../repo with spaces",
+    "branch": "main",
+    "commands": {
+      "test": ["node", "a b", "$(never-run)"],
+      "lint": ["npm", "run", "lint"],
+      "build": ["npm", "run", "build:check"]
+    },
+    "requiredChecks": ["Test", "Lint", "Build"],
+    "delivery": "pr"
+  }
+}
+```
+<!-- engine-config:json:end -->
+
+## Odczytaj plik
+
+W katalogu, w którym dostępna jest paczka `robisie` w `node_modules`, zapisz
+poniższy kod jako `read-engine-config.mjs`.
+
+<!-- engine-config:esm:start -->
+```js
+import { loadEngineConfig } from 'robisie/dist/engine-config.js';
+
+try {
+  const configPath = process.argv[2];
+  if (!configPath) throw new Error('Podaj ścieżkę do robisie.config.json');
+  const config = loadEngineConfig(configPath);
+  console.log(JSON.stringify(config));
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
+```
+<!-- engine-config:esm:end -->
+
+Uruchom lokalnie, podając absolutną ścieżkę do zapisanego JSON:
+
+```sh
+node read-engine-config.mjs /absolutna/sciezka/robisie.config.json
+```
+
+Katalog skryptu może być inny niż katalog konfiguracji. Sukces oznacza exit 0,
+pusty stderr i jeden obiekt JSON na stdout. Poniżej kształt wybranych pól wyniku
+dla powyższej ścieżki (pozostałe pola konfiguracji też są wypisywane):
+
+```text
+configPath: "/absolutna/sciezka/robisie.config.json"
+stateDir: "/absolutna/state with spaces"
+engine.repo: "/absolutna/repo with spaces"
+engine.commands.test: ["node", "a b", "$(never-run)"]
+engine.delivery: "pr"
+roles.owner: {"name":"Ala","forms":["Ala","Ali"],"genitive":"Ali"}
+```
+
+Ścieżka pliku jest kanonizowana, więc przy dowiązaniach wynik wskazuje jego
+rzeczywistą lokalizację. Brak pliku, niepoprawny JSON lub błędne pola kończą
+odczyt z niezerowym exit i komunikatem na stderr. Na przykład brak `test`
+w `engine.commands` daje błąd zawierający `engine.commands.test`, a
+`delivery: "invalid"` — `engine.delivery`. Odczyt nie dopisuje brakujących
+komend ani nie zastępuje błędnego sposobu dostarczenia wartością domyślną.

package/docs/README.en.md

@@ -5,7 +5,7 @@ Polski: [README.md](README.md).
 <!-- sekcja: dostepnosc -->
 ## Availability
 
-This guide uses a supplied `robisie-0.1.0.tgz`, without obtaining the installer from npm. The 404 observed on 20 October 2026 is historical evidence. The team supplies the tgz; run subsequent commands and agent sessions in the directory where you install it. [Preparation](#wymagania) → [account](#konto) → [key](#klucz) → [installation](#instalacja) → [acceptance](#recenzja-i-odbior).
+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).
 
 <!-- sekcja: wymagania -->
 <a id="wymagania"></a>
@@ -13,7 +13,7 @@ This guide uses a supplied `robisie-0.1.0.tgz`, without obtaining the installer
 
 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).
 
-Prepare an empty directory on disk containing only the supplied tgz and README. No website or `package.json` is needed; npm installation creates dependency files. This is the agents' working directory, separate from the dashboard project.
+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.
 
 <!-- sekcja: konto -->
 <a id="konto"></a>
@@ -35,16 +35,19 @@ The package stores **one key for CEO, Builder and Quality Officer** as `ROBISIE_
 
 <!-- sekcja: instalacja -->
 <a id="instalacja"></a>
-## Install the package file
+## Install from npm
 
-The human opens a terminal in the prepared directory containing the tgz and README:
+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:
 
 ```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
 ```
 
-Expected result: 0.1.0. If npm cannot find the file, check the directory and supplied filename. 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.
+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.
 
 <!-- sekcja: init -->
 ## Connect your agent
@@ -108,11 +111,15 @@ Doctor runs the helper file via node, the agent via npx. `ROBISIE_PROJECT_CONTEX
 <!-- sekcja: pierwsza-karta -->
 ## First card and Builder startup
 
-The human starts the CEO in the installation directory: `claude --agent ceo-client`, or `codex` and requests the robisie CEO role (reading the full file referenced by AGENTS.md), or `opencode` and selects `ceo-client`. After successful discovery use this request, which works with just README and tgz:
+The human starts the CEO in the installation directory: `claude --agent ceo-client`, or `codex` and requests the robisie CEO role (reading the full file referenced by AGENTS.md), or `opencode` and selects `ceo-client`. After successful discovery use this request, which works after npm installation with just README:
 
 > Create wynik.txt in this directory with exactly “robisie działa” followed by a newline. Read it back and verify the exact contents. Boundaries: this file only, no dependencies, accounts or publication. Prepare the scope and wait for my approval; after the work I need independent review and my acceptance.
 
-Human approval precedes the Builder: `draft` → `ready` → `in_progress` → `in_review` → independent review and verified receipt → `delivered` → owner acceptance → `done`. The CEO supplies a command; **the human starts the Builder in a new terminal in the installation directory**; automatic launch in an ordinary directory may leave the card ready.
+After human approval, the CEO by default calls `spawn_builder` with the ID of the card confirmed in `ready`. The full flow in Claude Code is: `draft` → `ready` → `in_progress` → `in_review` → independent review and verified receipt → `delivered` → owner acceptance → `done`; see [Review and explicit acceptance](#recenzja-i-odbior) for acceptance limits in other sessions.
+
+If `spawn_builder` fails, the CEO reports the error and resolves the cause before retrying; it does not automatically switch to manual startup.
+
+Manual startup is available only as the operator's explicit choice: the CEO then provides a command to run in a new terminal in the installation directory.
 
 The ID comes from the created or freshly read card, not the project or session. Below is a fictitious lowercase canonical UUID; replace it with the exact card ID. The Codex example assumes XDG_CONFIG_HOME=/home/tester/Robisie config: replace the entire path with the actual installed path (default $HOME/.config/robisie/roles/codex/manager-builder-client.md). A tilde inside the quoted prompt will not expand. Choose one command:
 
@@ -128,16 +135,18 @@ Expected startup result: a fresh CEO read confirms the assigned card in_progress
 <a id="recenzja-i-odbior"></a>
 ## Review and explicit acceptance
 
-The CEO starts an independent Quality Officer through `Agent(quality-officer-client)` after a fresh in_review read. The Quality Officer independently checks the result and records review and evidence on the card; the Builder does not review its own work. Checking evidence and explicitly accepting the result is the operator's responsibility. After verified review and delivery, check the acceptance criteria; if evidence needed for your acceptance or your approval is missing, leave the card in `delivered`.
+In Claude Code, the CEO starts an independent Quality Officer through `Agent(quality-officer-client)` after a fresh in_review read. The Quality Officer independently checks the result and records review and evidence on the card; the Builder does not review its own work. The CEO verifies the review confirmation (verified receipt) and performs the fresh card reads required by the protocol before moving to `delivered`; then explicit acceptance by the operator permits moving to `done`. Checking evidence and explicitly accepting the result is the operator's responsibility. After verified review and delivery, check the acceptance criteria; if evidence needed for your acceptance or your approval is missing, leave the card in `delivered`.
+
+OpenCode: the card stays in `in_review` regardless of the availability of the Agent tool; there is no supported transition to `delivered`. Full acceptance requires the Claude Code route described above. A task/VERIFIED result, role label or receipt JSON alone does not open this transition; do not bypass a refusal with a manual status change or self-review.
 
-Moving to delivered requires independent review and a verified receipt. If the CEO session lacks the Agent tool, particularly in Codex/OpenCode, the card stays in `in_review`: this is a product capability gap for CEO/CR to resolve. Do not substitute Builder self-review or a manual status change. Installing three roles does not provide that integration.
+In other CEO sessions, including Codex, moving to delivered requires independent review and a verified receipt. If the CEO session lacks the Agent tool, the card stays in `in_review`: this is a product capability gap for CEO/CR to resolve. Do not substitute Builder self-review or a manual status change. Installing three roles does not provide that integration.
 
 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.
 
 <!-- sekcja: aktualizacja -->
 ## Update
 
-The human obtains a tgz compatible with the server contract MAJOR from the team. Install the supplied file in the same directory using `npm i ./robisie-0.1.0.tgz` (replace the filename with the compatible release), then `npx robisie init` and `npx robisie doctor`. Expected result: compatible version, complete configuration and doctor exit 0; if incompatible, obtain the right release instead of repeating the same installation. For damaged package files, reinstall the supplied tgz with the same command. No registry release is needed.
+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.
 
 <!-- sekcja: odinstalowanie -->
 ## Uninstall
@@ -159,16 +168,16 @@ CLI messages remain in Polish. Match the message, then follow the English explan
 | brak-klucza | `Brak klucza robisie.` | No key: generate one in Connect and supply it to init. |
 | 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. |
 | 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. |
-| major | `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.0 (obsługuje 1.x).` | Example of a MAJOR mismatch: obtain a compatible package file from the team. |
+| 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. |
 | 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. |
 | 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. |
 | brak-programu-i-katalogu | `brak programu w PATH i katalogu dostawcy` | Install the selected program, repeat init with the complete shared map and doctor. |
 | jsonc | `nie zmieniam automatycznie` | Preserve JSONC; prepare supported JSON or choose another provider for all roles. Remote MCP alone is insufficient. |
 | niepelna-instalacja | `Claude Code: niepełna instalacja` | Example of missing configuration: repeat init for your agent. |
 
-After repair, run local `npx robisie init` and `npx robisie doctor`; for missing files first reinstall the supplied tgz, 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.
+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.
 
 <!-- sekcja: ograniczenia -->
 ## Limitations
 
-The package starts no background services and does not start the Builder automatically. 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.
+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.