@@ -124,6 +124,23 @@ Tracing and state:
124124` --verbose ` to print events\
125125` --state <file> ` to persist a session.
126126
127+ ### Worker sandbox defaults
128+
129+ - Deck-executing CLI surfaces default to worker sandbox execution.
130+ - Use ` --no-worker-sandbox ` (or ` --legacy-exec ` ) to force legacy in-process
131+ execution.
132+ - ` --worker-sandbox ` explicitly forces worker execution on.
133+ - ` --sandbox ` / ` --no-sandbox ` are deprecated aliases.
134+ - ` gambit.toml ` equivalent:
135+ ``` toml
136+ [execution ]
137+ worker_sandbox = false # same as --no-worker-sandbox
138+ # legacy_exec = true # equivalent rollback toggle
139+ ```
140+
141+ The npm launcher (` npx @bolt-foundry/gambit ... ` ) runs the Gambit CLI binary for
142+ your platform, so these defaults and flags apply there as well.
143+
127144## Using the Simulator
128145
129146The simulator is the local Debug UI that streams runs and renders traces.
@@ -173,6 +190,59 @@ Define `contextSchema`/`responseSchema` with Zod to validate IO, and implement\
173190` ctx.spawnAndWait({ path, input }) ` . Emit structured trace events with\
174191` ctx.log(...) ` .
175192
193+ ### Runtime defaults for programmatic ` runDeck `
194+
195+ ` runDeck ` from ` @bolt-foundry/gambit ` now uses CLI-equivalent provider/model
196+ defaults (alias expansion, provider routing, fallback behavior).
197+
198+ Before (direct-provider setup in each caller):
199+
200+ ``` ts
201+ import { createOpenRouterProvider , runDeck } from " jsr:@bolt-foundry/gambit"
202+
203+ const = createOpenRouterProvider ({
204+ apiKey: Deno .env .get (" OPENROUTER_API_KEY" ! ,
205+ });
206+ await runDeck ({
207+ path: " ./root.deck.md"
208+ input: { message: " hi"
209+ modelProvider: provider ,
210+ });
211+ ```
212+
213+ After (defaulted wrapper):
214+
215+ ``` ts
216+ import { runDeck } from " jsr:@bolt-foundry/gambit"
217+
218+ await runDeck ({
219+ path: " ./root.deck.md"
220+ input: { message: " hi"
221+ });
222+ ```
223+
224+ Per-runtime override (shared runtime object):
225+
226+ ``` ts
227+ import { createDefaultedRuntime , runDeck } from " jsr:@bolt-foundry/gambit"
228+
229+ const = await createDefaultedRuntime ({
230+ fallbackProvider: " codex-cli"
231+ });
232+
233+ await runDeck ({
234+ runtime ,
235+ path: " ./root.deck.md"
236+ input: { message: " hi"
237+ });
238+ ```
239+
240+ Replacement mapping:
241+
242+ - Legacy direct core passthrough export: ` runDeck ` -> ` runDeckCore `
243+ - Defaulted wrapper export: ` runDeck `
244+ - Runtime builder: ` createDefaultedRuntime `
245+
176246---
177247
178248## Author your first deck
0 commit comments