sync(bfmono): docs(gambit): align snippet terminology and publish migration post (+19 more) (bfmono@e59c46b74)

This PR is an automated gambitmono sync of bfmono Gambit packages.

- Source: `packages/gambit/`
- Core: `packages/gambit/packages/gambit-core/`
- bfmono rev: e59c46b74

Changes:
- e59c46b74 docs(gambit): align snippet terminology and publish migration post
- 32c05988a chore(gambit): migrate demo and docs built-in URIs to snippets
- 0c3283e87 chore(gambit): rename legacy action/test deck keys in examples and docs
- e6cee968d chore(gambit-examples): adopt scenario participant snippet in user-turn decks
- 898e776f0 feat(gambit): add scenario participant snippet and scaffold adoption
- e61fcaa4e feat(gambit-simulator): add previous test run selectors for test and grade
- 4f0a61e0c fix(gambit): keep blank test runs and allow assistant starts in a workspace
- 5663a6c3e fix(gambit-simulator): prevent overlapping test status polls
- c7a262c7d fix(gambit): enable unstable worker options in gambit-core CI tests
- 5660b3269 test(gambit): harden codex cli test command config
- a9d5438f9 chore(gambit): cut 0.8.5-rc.1 release
- d6a149451 test(gambit): harden codex smoke + build stop tests
- 6c76075fa fix(gambit-serve): root workspace state in invocation directory
- de75a3987 feat(gambit): ship faq openresponses interoperability updates
- 11e0477a3 fix(gambit-sim): default test init when workspace has no saved messages
- 14df328c7 test(gambit-simulator): cover test tab JSON input gating and payload wiring
- 2e833821c feat(gambit-simulator): switch test tab schema inputs to JSON-only
- 126087519 fix(simulator-ui): keep activity toggle visible and prevent collapse jump
- 0c0366932 feat(simulator-ui): add test chat actions activity card parity
- 72bb726e5 fix(gambit): guard artifact restore typing and stabilize reset-abort test

Do not edit this repo directly; make changes in bfmono and re-run the sync.

Author: bft-codebot

docs/external/concepts/hourglass.md

@@ -20,7 +20,7 @@ the needed context and tone.
 
 ## Applying to Gambit
 
-- Use separate cards for assistant persona, user persona, and behavior; embed
+- Use separate snippets for assistant persona, user persona, and behavior; embed
   them into the deck body to keep concerns isolated.
 - Keep the “pinch” (behavior/constraints) closest to the model call, and keep
   personas above it so they influence style without diluting instructions.
@@ -29,11 +29,11 @@ the needed context and tone.
 - Keep schemas tight so actions/tools stay aligned with the narrow middle of the
   hourglass.
 
-## Skeleton (deck + cards)
+## Skeleton (deck + snippets)
 
 ```
 src/decks/
-  gambit-assistant.deck.md     # root deck embeds the cards below
+  gambit-assistant.deck.md     # root deck embeds the snippets below
   cards/
     assistant_persona.card.md  # who the assistant is
     user_persona.card.md       # who the user is / goals / constraints
@@ -42,15 +42,15 @@ src/decks/
 
 Deck body outline:
 
-1. Assistant persona card content.
-2. User persona card content.
-3. Behavior card content: steps/constraints/output shape.
+1. Assistant persona snippet content.
+2. User persona snippet content.
+3. Behavior snippet content: steps/constraints/output shape.
 4. (Optional) Examples or edge cases.
 
 ## Tips
 
 - Keep the behavior “pinch” short and specific; move narrative/tone into persona
-  cards.
+  snippets.
 - Declare turn order explicitly (assistant-first vs. user-seeded message).
 - Use numbered steps and bullets; avoid long prose in the middle section.
 - When adding tools/actions, restate when to call each and what to return after

docs/external/concepts/runtime.md

@@ -21,14 +21,14 @@ safe/observable.
 - `gambit_context`: sent once when `--context` (formerly `--init`) is provided;
   payload is the raw input. Useful for assistant-first flows so the model can
   read input without a user turn. `gambit_init` remains as a deprecated alias.
-- `gambit_respond`: enable with the `gambit://cards/respond.card.md` marker in
+- `gambit_respond`: enable with the `gambit://snippets/respond.md` marker in
   Markdown (or `respond: true` in TypeScript decks). Required for LLM decks that
   should finish with a structured envelope
   `{ payload, status?, message?, code?, meta? }`.
 - `gambit_complete`: emitted automatically for child completions and handled
   errors so the parent can see
   `{ runId, actionCallId, source, status?, payload?, message?, code?, meta? }`.
-- `gambit_end`: enable with `![end](gambit://cards/end.card.md)` in Markdown (or
+- `gambit_end`: enable with `![end](gambit://snippets/end.md)` in Markdown (or
   `allowEnd: true` in TypeScript decks). Calling it returns a sentinel
   `{ __gambitEnd: true, payload?, status?, message?, code?, meta? }` so
   CLI/scenario loops stop reinjecting the closing assistant turn.

docs/external/examples/agent_with_multi_actions.md

@@ -4,24 +4,24 @@ What it shows
 
 - Routing agent that picks exactly one tool from a mixed set of TS/MD child
   decks.
-- Cards contribute action decks and schema fragments that merge into the root
+- Snippets contribute action decks and schema fragments that merge into the root
   deck.
 
 Key files
 
 - `init/examples/advanced/agent_with_multi_actions/agent_with_multi_actions.deck.md`
   — root LLM router with brevity rules.
 - `init/examples/advanced/agent_with_multi_actions/actions/cards/*.card.md` —
-  cards declare action decks/labels/descriptions.
+  snippets declare action decks/labels/descriptions.
 - `init/examples/advanced/agent_with_multi_actions/actions/decks/*` — child
   decks (TS compute and MD LLM) with Zod schemas.
 - `init/examples/advanced/agent_with_multi_actions/schemas/*` — shared
   input/output schemas for tool calls.
 
 Why it’s structured this way
 
-- Action cards keep action-deck definitions close to their prompts and schemas;
-  the loader merges them so the model sees a unified tool list.
+- Action snippets keep action-deck definitions close to their prompts and
+  schemas; the loader merges them so the model sees a unified tool list.
 - Clear descriptions + strict schemas bias the model toward the right action and
   payload shape.
 - Root prompt enforces “exactly one action” to avoid tool-chaining and keeps

docs/external/examples/cold_emailer.md

@@ -32,9 +32,9 @@ Key files
 - `init/examples/advanced/cli_cold_emailer/cards/behavior.card.md` — behavior
   rules and output format guidance.
 - `init/examples/advanced/cli_cold_emailer/cards/send_email.card.md` — action
-  card for sending the drafted email.
+  snippet for sending the drafted email.
 - `init/examples/advanced/cli_cold_emailer/cards/log_revision_plan.card.md` —
-  action card for logging the revision plan.
+  action snippet for logging the revision plan.
 - `init/examples/advanced/cli_cold_emailer/lookup_profile.deck.ts` — TypeScript
   action with hard-coded demo profile data.
 - `init/examples/advanced/cli_cold_emailer/schemas/research_input.zod.ts` —

docs/external/examples/handlers_md.md

@@ -3,7 +3,7 @@
 What it shows
 
 - Busy/idle/error handlers authored in Markdown decks, paired with TS actions.
-- Using `gambit://cards/respond.card.md` in an error handler to force structured
+- Using `gambit://snippets/respond.md` in an error handler to force structured
   completion.
 
 Key files

docs/external/examples/internal_monolog.md

@@ -5,7 +5,7 @@ without tool calls) before completing its work.
 
 - `internal_monolog_parent.deck.md`: root deck that calls the child tool and
   relays its answer.
-- `monolog_child.deck.md`: LLM child with the `gambit://cards/respond.card.md`
+- `monolog_child.deck.md`: LLM child with the `gambit://snippets/respond.md`
   marker that first thinks aloud (monolog), then calls a compute action, then
   responds.
 - `lookup_fact.deck.ts`: simple compute action the child calls.

docs/external/examples/policy_support_bot.md

@@ -7,12 +7,12 @@ support bot grounded entirely in a curated FAQ.
 Key ideas:
 
 1. **FAQ ingestion** – `cards/faq_knowledge.card.md` is the canonical knowledge
-   base. The Markdown action deck `actions/search_faq.deck.md` reads that card
-   directly, selects the best entries, and emits structured matches with manual
-   confidence scores (no external vector store required).
+   base. The Markdown action deck `actions/search_faq.deck.md` reads that
+   snippet directly, selects the best entries, and emits structured matches with
+   manual confidence scores (no external vector store required).
 2. **Policy-aware orchestration** – `policy_support_bot.deck.md` embeds persona,
-   grounding, and refusal cards, calls `search_faq`, enforces citation
-   formatting, and uses `gambit://cards/respond.card.md` with a schema so the
+   grounding, and refusal snippets, calls `search_faq`, enforces citation
+   formatting, and uses `gambit://snippets/respond.md` with a schema so the
    UI/CLI always receives structured envelopes.
 3. **Tests + demos** – `tests/faq_dataset.test.ts` guards the FAQ knowledge base
    (category headings, IDs, entry counts), while `demo-script.md` lists prompts

docs/external/examples/voice_front_desk.md

@@ -4,7 +4,7 @@ What it shows
 
 - A modular voice receptionist that mirrors a patient call tree: identity,
   routing, and specialized task decks.
-- Persona/behavior cards that encode the architecture (identity behaviors,
+- Persona/behavior snippets that encode the architecture (identity behaviors,
   routing, scheduling/refill/insurance/billing guidance).
 - Deterministic TypeScript actions for each flow (patient lookup, new-patient
   capture, scheduling, results, billing, refills, insurance, FAQs, transfers,
@@ -22,7 +22,7 @@ Key files
   identity, routing, scheduling, results, billing, refills, insurance, FAQs,
   transfers, and callback logging.
 - `init/examples/advanced/voice_front_desk/cards/*.card.md` — persona, identity,
-  routing, and per-flow behavior cards that each deck imports as needed.
+  routing, and per-flow behavior snippets that each deck imports as needed.
 - `init/examples/advanced/voice_front_desk/actions/*.deck.ts` — deterministic
   TypeScript compute decks for patient lookup, new-patient capture,
   scheduling_ops, results_lookup, billing_support, refill_ops, insurance_check,
@@ -37,7 +37,7 @@ Why it’s structured this way
 - The modular voice architecture keeps the persona focused on the live caller
   while dedicated decks handle structured work such as lookup, scheduling,
   refills, or insurance.
-- Behavior cards keep identity gathering, routing, and per-flow questions
+- Behavior snippets keep identity gathering, routing, and per-flow questions
   separate, so you can edit the call tree without touching the deck body.
 - Deterministic actions make it easy to test scenarios locally; each tool
   exposes a narrow schema with predictable outputs that the assistant can read

docs/external/guides/README.md

@@ -2,4 +2,4 @@
 
 Active guides:
 
-- Authoring decks and cards: `./authoring.md`
+- Authoring decks and snippets: `./authoring.md`

docs/external/guides/authoring.md

@@ -8,8 +8,8 @@ verification.
 
 - Decks are single units of work. They can be LLM-powered (via `modelParams`) or
   compute-only (via `run`/`execute`).
-- Cards are reusable prompt fragments. Embedding cards merges their deck
-  references (action/test/grader) and schema fragments into the parent deck.
+- Snippets are reusable prompt fragments. Embedding snippets merges their deck
+  references (action/scenario/grader) and schema fragments into the parent deck.
 - Action decks are child decks exposed as model tools. Names must match
   `^[A-Za-z_][A-Za-z0-9_]*$` and avoid the `gambit_` prefix (reserved).
 - Persona/scenario decks may accept free-form user turns. Use the
@@ -19,12 +19,12 @@ verification.
 
 ## Pick a format
 
-- Markdown deck/card: great for quick prompt-first flows. Front matter declares
-  label/model/actions/scenarios/graders/handlers; body is the prompt. Embeds via
-  image syntax pull in cards or special markers.
-- TypeScript deck/card: best when you need compute logic or co-locate schemas.
-  Export `defineDeck`/`defineCard` with Zod schemas and a `run`/`execute` for
-  compute decks.
+- Markdown deck/snippet: great for quick prompt-first flows. Front matter
+  declares label/model/actions/scenarios/graders/handlers; body is the prompt.
+  Embeds via image syntax pull in snippets or special markers.
+- TypeScript deck/snippet: best when you need compute logic or co-locate
+  schemas. Export `defineDeck`/`defineCard` with Zod schemas and a
+  `run`/`execute` for compute decks.
 
 ## Minimal examples
 
@@ -36,7 +36,7 @@ label = "hello_world"
 modelParams = { model = "openai/gpt-4o-mini", temperature = 0 }
 +++
 
-![init](gambit://cards/context.card.md) # seed input if provided via CLI
+![init](gambit://snippets/context.md) # seed input if provided via CLI
 
 Rules:
 
@@ -64,8 +64,8 @@ export default defineDeck({
 
 - Non-root decks must declare `contextSchema` and `responseSchema` (Zod). Roots
   default to permissive string-ish input/output if omitted.
-- Card `contextFragment`/`responseFragment` merge into the deck’s schemas;
-  deck-level definitions win on conflicts.
+- Snippet `contextFragment`/`responseFragment` values merge into the deck’s
+  schemas; deck-level definitions win on conflicts.
 - LLM outputs are validated against `responseSchema`; compute decks validate
   returned payloads as well.
 
@@ -81,7 +81,7 @@ deno run -A packages/gambit/scripts/migrate-schema-terms.ts <repo-root>
 
 - Add action decks in front matter or TS definitions:
   `actions = [{ name = "get_time", path = "./get_time.deck.ts" }]`.
-- Action decks defined on embedded cards are merged into the deck; duplicates
+- Action decks defined on embedded snippets are merged into the deck; duplicates
   are overridden by the deck’s own entries.
 - In compute decks, call child decks with `ctx.spawnAndWait({ path, input })`.
 - In LLM decks, the model chooses action decks via tool calls. Provide clear
@@ -152,15 +152,16 @@ deno run -A packages/gambit/scripts/migrate-schema-terms.ts <repo-root>
   `handlers.onError` point to other decks. Inputs are structured (see
   `../reference/handlers.md`); errors inside handlers are swallowed.
 
-## Embeds (cards)
+## Embeds (snippets)
 
-- In Markdown, use image syntax to embed:
-  `![behavior](./cards/behavior.card.md)`. Special markers:
-  `gambit://cards/context.card.md` hints init tool,
-  `gambit://cards/respond.card.md` injects respond instructions, and
-  `gambit://cards/end.card.md` enables the `gambit_end` hang-up tool.
-- Cards can also be TS files exported with `defineCard`. They may contain
-  action/test/grader deck references and schema fragments, but no handlers.
+- In Markdown, use image syntax to embed snippets:
+  `![behavior](./cards/behavior.card.md)`. Local snippet files often still live
+  under `cards/` with a `.card.md` suffix for legacy compatibility. Special
+  markers: `gambit://snippets/context.md` hints init tool,
+  `gambit://snippets/respond.md` injects respond instructions, and
+  `gambit://snippets/end.md` enables the `gambit_end` hang-up tool.
+- Snippets can also be TS files exported with `defineCard`. They may contain
+  action/scenario/grader deck references and schema fragments, but no handlers.
 
 ## Running and debugging