@bolt-foundry/gambit 0.6.8 → 0.8.0

package/CHANGELOG.md

@@ -1,47 +1,16 @@
 +++
 [release]
-since = "225456917f75e92cc095af525201373c4be37944"
+since = "692534996df73790229b8303516d48be66136fce"
 +++
 
 # Changelog
 
-## Unreleased (v0.6.8)
+## Unreleased (v0.8.1)
 
-- Repl fixes.
-- Replaced voice front desk graders and expanded FAQ persona/grading coverage.
+- TBD
 
-### CLI and UX
+## v0.8.0
 
-- Added a grading command with test-bot hooks in the CLI.
-- `--message` now works without `--init` for object root schemas.
-- REPL/serve/CLI flags refreshed; `--verbose` logs tool call args/results.
+- chore(gambit): prepare 0.8.0 changelog
 
-### Fixes
-
-- Avoid extra assistant turn on test-bot resume; skip empty assistant turns in
-  grading; keep grader respond blocks last.
-- Fixed test-bot sidebar loading, grader score reads, and booking confirmation
-  placement.
-- Simulator UI polish: full-height layout, sourcemap adverts, locked init panel
-  behavior, and reconnect/permalink reloads.
-
-## v0.0
-
-- Authoring: TypeScript/Markdown decks and cards via `defineDeck`/`defineCard`;
-  embeds with cycle detection; card actions merge into decks (deck wins); card
-  schema fragments merge into deck schemas; non-root decks require input/output
-  schemas (root defaults to string-ish).
-- Runtime: compute and LLM decks share the surface; assistant-first flow seeds a
-  synthetic `gambit_init` tool; helpers `spawnAndWait`, `return`, `fail`; action
-  names validated against reserved prefix/pattern/length; default guardrails
-  depth=3/passes=3/timeout≈120s with per-deck overrides.
-- Handlers/events: optional `onError`/`onBusy`/`onIdle` decks emit structured
-  events (`gambit_complete` for handled errors, busy/idle updates) with default
-  delay 800ms and traces for fire/result (`onInterval` is deprecated alias for
-  `onBusy`).
-- IO/host: CLI supports `run`, `repl`, `serve` (WebSocket simulator UI); flags
-  for streaming, turn order via user message, trace to console/JSONL, state
-  load/save, model overrides; `deno task compile` builds a binary; OpenRouter
-  chat provider with streaming/tool calls.
-- Runtime + server tests for schemas/embeds/streaming/handlers; tasks for
-  fmt/lint/test/ci; root README with quick start.
+## 0.7.0 — Show HN launch

package/README.md

@@ -1,27 +1,40 @@
-# Gambit
+# <img src="./gambit_1color_bg.png" alt="Gambit logo" height="50" />
 
 Gambit helps you build reliable LLM workflows by composing small, typed “decks”\
 with clear inputs/outputs and guardrails. Run decks locally, stream traces, and\
 debug with a built-in UI.
 
+[Watch the demo video](https://youtu.be/J_hQ2L_yy60).
+
 ## Quickstart
 
-Requirements: Deno 2.2+ and `OPENROUTER_API_KEY` (set `OPENROUTER_BASE_URL` if\
+Requirements: Node.js 18+ and `OPENROUTER_API_KEY` (set `OPENROUTER_BASE_URL` if
 you proxy OpenRouter-style APIs).
 
-Run the CLI directly from JSR (no install):
+Run the CLI directly with npx (no install):
 
 ```
 export OPENROUTER_API_KEY=...
-deno run -A jsr:@bolt-foundry/gambit/cli init
+npx @bolt-foundry/gambit demo
 ```
 
-Downloads example files and sets environment variables.
+Downloads example files (hello decks plus the `examples/` gallery) and sets
+environment variables.
+
+To scaffold a starter project that you can customize, run:
+
+```
+npx @bolt-foundry/gambit init my-project
+```
+
+This creates a structured skeleton (`decks/`, `actions/`, `graders/`, `tests/`,
+`schemas/`, `.gambit/`) with README guides so you can start authoring your own
+workflows immediately.
 
 Run an example in the terminal (`repl`):
 
 ```
-deno run -A jsr:@bolt-foundry/gambit/cli repl examples/init/hello.deck.md
+npx @bolt-foundry/gambit repl gambit/hello.deck.md
 ```
 
 This example just says "hello" and repeats your message back to you.
@@ -29,7 +42,7 @@ This example just says "hello" and repeats your message back to you.
 Run an example in the browser (`serve`):
 
 ```
-deno run -A jsr:@bolt-foundry/gambit/cli serve examples/init/hello.deck.md
+npx @bolt-foundry/gambit serve gambit/hello.deck.md
 open http://localhost:8000/debug
 ```
 
@@ -65,40 +78,43 @@ open http://localhost:8000/debug
 
 Use the CLI to run decks locally, stream output, and capture traces/state.
 
-Install the CLI:
+Run with npx (no install):
 
 ```
-deno install -A -n gambit jsr:@bolt-foundry/gambit/cli
+npx @bolt-foundry/gambit <command>
 ```
 
 Run a deck once:
 
 ```
-gambit run <deck> --init <json|string> --message <json|string>
+npx @bolt-foundry/gambit run <deck> --context <json|string> --message <json|string>
 ```
 
+> `--context` replaces the old `--init` flag. The CLI still accepts `--init` as
+> a deprecated alias for now so existing scripts keep working.
+
 Drop into a REPL (streams by default):
 
 ```
-gambit repl <deck>
+npx @bolt-foundry/gambit repl <deck>
 ```
 
 Run a persona against a root deck (test bot):
 
 ```
-gambit test-bot <root-deck> --test-deck <persona-deck>
+npx @bolt-foundry/gambit test-bot <root-deck> --test-deck <persona-deck>
 ```
 
 Grade a saved session:
 
 ```
-gambit grade <grader-deck> --state <file>
+npx @bolt-foundry/gambit grade <grader-deck> --state <file>
 ```
 
 Start the Debug UI server:
 
 ```
-gambit serve <deck> --port 8000
+npx @bolt-foundry/gambit serve <deck> --port 8000
 ```
 
 Tracing and state: 
@@ -111,16 +127,16 @@ Tracing and state:
 
 The simulator is the local Debug UI that streams runs and renders traces.
 
-Install the CLI:
+Run with npx (no install):
 
 ```
-deno install -A -n gambit jsr:@bolt-foundry/gambit/cli
+npx @bolt-foundry/gambit <command>
 ```
 
 Start it:
 
 ```
-gambit serve <deck> --port 8000
+npx @bolt-foundry/gambit serve <deck> --port 8000
 ```
 
 Then open:
@@ -159,7 +175,7 @@ Define `inputSchema`/`outputSchema` with Zod to validate IO, and implement\
 
 ## Author your first deck
 
-### Minimal Markdown deck (model-powered):
+### Minimal Markdown deck (model-powered): `hello_world.deck.md`
 
 ```
 +++
@@ -176,12 +192,12 @@ You are a concise assistant. Greet the user and echo the input.
 Run it:
 
 ```
-deno run -A src/cli.ts run ./hello_world.deck.md --init '"Gambit"' --stream
+npx @bolt-foundry/gambit run ./hello_world.deck.md --context '"Gambit"' --stream
 ```
 
-### Compute deck in TypeScript (no model call):
+### Compute deck in TypeScript (no model call): `echo.deck.ts`
 
-```
+```typescript
 // echo.deck.ts
 import { defineDeck } from "jsr:@bolt-foundry/gambit";
 import { z } from "zod";
@@ -199,10 +215,10 @@ export default defineDeck({
 Run it:
 
 ```
-deno run -A src/cli.ts run ./echo.deck.ts --init '{"text":"ping"}'
+npx @bolt-foundry/gambit run ./echo.deck.ts --context '{"text":"ping"}'
 ```
 
-### Deck with a child action (calls a TypeScript tool):
+### Deck with a child action (calls a TypeScript tool): `agent_with_time.deck.md`
 
 ```
 +++
@@ -217,9 +233,9 @@ description = "Return the current ISO timestamp."
 A tiny agent that calls get_time, then replies with the timestamp and the input.
 ```
 
-And the child action:
+And the child action: `get_time.deck.ts`
 
-```
+```typescript
 // get_time.deck.ts
 import { defineDeck } from "jsr:@bolt-foundry/gambit";
 import { z } from "zod";
@@ -233,3 +249,38 @@ export default defineDeck({
   },
 });
 ```
+
+Run it:
+
+```
+npx @bolt-foundry/gambit run ./agent_with_time.deck.md --context '"hello"' --stream
+```
+
+## Deno
+
+If you prefer Deno, use the Deno commands below.
+
+Quickstart:
+
+```
+export OPENROUTER_API_KEY=...
+deno run -A jsr:@bolt-foundry/gambit/cli demo
+```
+
+Starter project:
+
+```
+deno run -A jsr:@bolt-foundry/gambit/cli init my-project
+```
+
+Run a deck:
+
+```
+deno run -A jsr:@bolt-foundry/gambit/cli run <deck> --context <json|string> --message <json|string>
+```
+
+Start the Debug UI:
+
+```
+deno run -A jsr:@bolt-foundry/gambit/cli serve <deck> --port 8000
+```