@keystrokehq/cli 0.1.24 → 0.1.26

package/dist/skills-bundle/skills/keystroke-deploy/references/build-and-full-deploy.md

@@ -1,30 +0,0 @@
-# Build and full deploy
-
-## What deploy does
-
-1. `walkProject` with `phase: "deploy"` — applies `@keystroke ignore:deploy`, collects source snapshot for the dashboard.
-2. `buildApp` — tsdown with `clean: true`; writes `dist/` and `dist/.keystroke/route-manifest.json`.
-3. `packProjectArtifact` — gzip tarball of `dist/`.
-4. Platform `artifacts.create` → PUT tarball → `complete` → blue/green promote.
-
-Source files upload in parallel (content-addressed); failure there warns but does not block deploy. The dashboard source snapshot is capped (per-file 256KB, total 8MB, 2000 files) and skips binaries, `.env`, and `.log` files — so `.env` is never uploaded.
-
-After upload, the CLI polls the project status (every ~2s, up to a 120s timeout) until it reports `active` or `failed`; on failure it surfaces the platform's `lastError`. A hang usually means the platform promotion is still in progress.
-
-## Entry keys
-
-Build entry keys mirror `dist/` paths without `.mjs`:
-
-| Source file                    | Entry key              |
-| ------------------------------ | ---------------------- |
-| `src/agents/support.ts`        | `agents/support`       |
-| `src/workflows/morning-check.ts` | `workflows/morning-check` |
-| `src/triggers/incoming-message.ts` | `triggers/incoming-message` |
-
-Nested agent dirs use the same `agents/<id>` pattern from discovery.
-
-## Freshness
-
-Full deploy always runs `buildApp` before pack. Default `clean: true` removes prior `dist/` output before rebuild. You do not need a separate `keystroke build` before deploy.
-
-Orphan files from removed modules are unlikely to affect routing — `route-manifest.json` is regenerated and drives HTTP routes.

package/dist/skills-bundle/skills/keystroke-deploy/references/filtered-deploy.md

@@ -1,50 +0,0 @@
-# Filtered deploy (`--filter`)
-
-Ship changes to one or a few modules without a full rebuild of every agent, workflow, and trigger.
-
-## Command
-
-```bash
-keystroke deploy --project <slug> --filter workflows/morning-check
-keystroke deploy --project <slug> --filter agents/support --filter workflows/signup-pipeline
-```
-
-(`--project` can go before or after `deploy`, and can be omitted after the first deploy.)
-
-- Exact entry keys only — no globs, no negation, no slug aliases.
-- First deploy for a project must be **full** (no `--filter`).
-- Without an active artifact, deploy errors: run a full deploy first.
-
-## Pipeline
-
-```text
-isolated single-entry build per --filter match (self-contained .mjs)
-  → download active prod tarball
-  → extract → overlay rebuilt files → merge route-manifest by moduleFile
-  → re-tar → normal artifacts.create / PUT / complete
-```
-
-## Isolated builds
-
-Each filtered module is built alone in a scratch dir. Output is self-contained (no shared `../chunk-*.mjs` imports). The merge overlays only `dist/<kind>/<id>.mjs` (+ `.map`) onto the extracted prod tree.
-
-## Manifest merge
-
-For each rebuilt module, base manifest entries with the same `moduleFile` are dropped; rebuilt entries are appended. Health, plugins, skills, integrations, and untouched modules stay from the active artifact.
-
-## What is not rebuilt
-
-- `config.mjs` and built-in integration routes
-- `dist/.keystroke/assets.mjs` and skill files on disk
-- Any module not listed in `--filter`
-
-Change `keystroke.config.ts` or project-wide assets → run a **full** deploy.
-
-## Verify
-
-```bash
-keystroke project deployments list --project <slug>   # new version active
-keystroke workflow run <workflow-slug> --input '{}'
-```
-
-Confirm untouched routes still work after a filtered deploy of a different module.

package/dist/skills-bundle/skills/keystroke-deploy/references/wip-ignore.md

@@ -1,35 +0,0 @@
-# WIP modules and `@keystroke ignore`
-
-Place the directive in the **leading comment block** of a module file under `src/agents/`, `src/workflows/`, or `src/triggers/` (the scan stops at the first non-comment line). Line (`//`) and block (`/* … */`, `*`) comments both work.
-
-```ts
-// @keystroke ignore
-// @keystroke ignore:deploy
-/** @keystroke ignore */
-```
-
-Only `ignore` and `ignore:deploy` are valid. Any other scope (e.g. `// @keystroke ignore:build`) throws `Unknown @keystroke ignore target "…"` at build time.
-
-## Directives
-
-| Directive              | Local build (`build`, `dev`, `start`) | Deploy (`phase: deploy`) |
-| ---------------------- | ------------------------------------- | ------------------------ |
-| `// @keystroke ignore` | Skipped                               | Skipped                  |
-| `// @keystroke ignore:deploy` | Included                      | Skipped                  |
-
-## When to use which
-
-- **`ignore`** — module is broken, experimental, or not ready to run anywhere.
-- **`ignore:deploy`** — safe to run locally; not ready for production yet.
-
-## Import guard
-
-If a **shipped** module imports a file marked `@keystroke ignore`, the build **fails in every phase**. If it imports an `@keystroke ignore:deploy` file, the local build/dev succeeds and only the **deploy** build fails (because `ignore:deploy` files are excluded only in the deploy phase). Compose in workflows instead of importing ignored actions from production modules.
-
-## Triggers
-
-A trigger attached to an ignored workflow should use the same ignore treatment, or the attachment will not behave as expected across build phases.
-
-## Filtered deploy note
-
-`ignore:deploy` omits a module from the **new** build. It does **not** keep the last prod version — full deploy replaces the entire artifact. Use filtered deploy when you want to update one live module while carrying forward the rest of prod.

package/dist/skills-bundle/skills/keystroke-files/SKILL.md

@@ -1,43 +0,0 @@
----
-name: keystroke-files
-description: Add static files to agent workspaces from src/files/ — product docs, instructions, context. Use with defineSandbox on defineAgent.
-metadata:
-  keystroke-domain: files
----
-
-# Files
-
-Files under `src/files/` mount into the agent sandbox at `/workspace/agent/`.
-
-## Layout
-
-```
-src/files/support/
-  product-guide.md
-  support-instructions.md
-  runbooks/
-    refunds.md
-```
-
-Nested directories are preserved — `src/files/support/runbooks/refunds.md` mounts at `/workspace/agent/runbooks/refunds.md`.
-
-```ts
-import { defineAgent } from "@keystrokehq/keystroke/agent";
-import { defineSandbox } from "@keystrokehq/keystroke/sandbox";
-
-export default defineAgent({
-  slug: "support",
-  systemPrompt: "Read /workspace/agent/product-guide.md before answering.",
-  sandbox: defineSandbox({ files: true }), // uses agent slug → src/files/support/
-});
-```
-
-Use `defineSandbox({ files: "shared" })` to mount `src/files/shared/` instead — the string value names the folder under `src/files/`.
-
-If the named folder doesn't exist, the build fails with a clear error — create the folder (it must contain at least one file) before deploying.
-
-Files are seeded **write-once** at sandbox startup: the agent can edit them at runtime, but those edits aren't persisted back to `src/files/` and reset on the next run. Treat `src/files/` as read-only seed content.
-
-Point the agent at paths in `systemPrompt`. After deploy, verify behavior with `keystroke agent prompt support --message "…"`.
-
-Related: [agents](.agents/skills/keystroke-agents/SKILL.md), [skills](.agents/skills/keystroke-skills/SKILL.md).

package/dist/skills-bundle/skills/keystroke-skills/SKILL.md

@@ -1,42 +0,0 @@
----
-name: keystroke-skills
-description: Add Agent Skills playbooks in src/skills/ for defineAgent — SKILL.md format, optional references. Use when giving agents domain-specific instructions.
-metadata:
-  keystroke-domain: skills
----
-
-# Project skills
-
-Skills are playbooks the agent loads on demand. Author in `src/skills/`, attach by folder name on the agent.
-
-## Layout
-
-```
-src/skills/support/
-  SKILL.md
-  references/refund-policy.md   # optional
-```
-
-```ts
-defineAgent({
-  slug: "support",
-  skills: ["support"] /* … */,
-});
-```
-
-At runtime → `/workspace/agent/skills/support/`.
-
-## SKILL.md
-
-Follow [Agent Skills](https://agentskills.io/specification): YAML frontmatter with `name` (matches the folder) and `description` are the required fields; everything else (e.g. `metadata`) is optional. Keep the body short; put detail in `references/`.
-
-## Two kinds of skills (don't confuse them)
-
-- **`src/skills/`** — *project* Agent Skills attached to your agents via `skills: [...]`. They deploy with your project; inspect deployed ones with `keystroke skill list`.
-- **`.agents/skills/`** — the *bundled coding-agent* guides (like this one) that `keystroke init` scaffolds. Refresh them to the current CLI version with `keystroke skills sync` (note the plural `skills`).
-
-## External registries
-
-Browse [skills.sh](https://skills.sh) — copy into `src/skills/{name}/` and fix `name` to match the folder.
-
-Related: [agents](.agents/skills/keystroke-agents/SKILL.md), [files](.agents/skills/keystroke-files/SKILL.md).

package/dist/skills-bundle/skills/keystroke-triggers/SKILL.md

@@ -1,143 +0,0 @@
----
-name: keystroke-triggers
-description: Wire keystroke workflows to cron, webhook, and poll sources in src/triggers/. Use when adding automation or auditing trigger runs.
-metadata:
-  keystroke-domain: triggers
----
-
-# Triggers
-
-Triggers **attach** a source to a target (a workflow or an agent). No business logic here — only schedule, endpoint, validation, and filters.
-
-Attachment id: `{sourceSlug}:{targetSlug}` (e.g. `signup:signup-pipeline`), where the suffix is the workflow's (or agent's) `slug`.
-
-## Cron
-
-```ts
-import { defineCronSource } from "@keystrokehq/keystroke/trigger";
-import workflow from "../workflows/morning-check";
-
-export default defineCronSource({
-  slug: "morning-check",
-  schedule: "0 9 * * *",
-}).attach({ workflow });
-```
-
-## Webhook
-
-```ts
-import { defineWebhookSource } from "@keystrokehq/keystroke/trigger";
-import { z } from "zod";
-import workflow from "../workflows/signup-pipeline";
-
-export default defineWebhookSource({
-  slug: "signup",
-  endpoint: "signup",
-  request: z.object({
-    name: z.string().trim().min(1),
-    email: z.string().email(),
-    company: z.string().trim().min(1),
-  }),
-}).attach({ workflow });
-```
-
-Use optional Zod `filter` for extra constraints beyond `request`:
-
-```ts
-filter: z.object({ type: z.literal("invoice.paid") }),
-```
-
-**Webhooks ack asynchronously.** The POST returns immediately — `202 { runId }` when a binding matches, or `{ ok: true, skipped: true }` when nothing does. The workflow runs in the background; its output is **not** returned in the HTTP response (there's no "respond to webhook"). To return data to the caller, make an outbound call from the workflow, or have the caller poll the run via the runs API / `keystroke workflow runs get`.
-
-### Shared endpoint (e.g. Stripe)
-
-Multiple trigger files can use the same `endpoint` — one URL `POST /triggers/{endpoint}`, each with its own `slug`, `request`, `filter`, and `transform`. Unmatched payloads return `{ ok: true, skipped: true }`.
-
-```ts
-// src/triggers/stripe-invoice-paid.ts
-export default defineWebhookSource({
-  slug: "stripe-invoice-paid",
-  endpoint: "stripe",
-  request: z.object({ type: z.string(), data: z.object({ id: z.string() }) }),
-  filter: z.object({ type: z.literal("invoice.paid") }),
-}).attach({ workflow: invoicePaidWorkflow, transform: (p) => ({ invoiceId: p.data.id }) });
-
-// src/triggers/stripe-subscription-deleted.ts — same endpoint, different slug/schema/filter
-```
-
-List or inspect all triggers on an endpoint:
-
-```bash
-keystroke trigger list --endpoint stripe
-keystroke trigger get stripe          # same rows as list --endpoint (shared route)
-keystroke trigger url stripe          # one webhook URL for the route
-```
-
-Use each trigger's `slug` for `trigger get` / run history (`keystroke trigger runs list stripe-invoice-paid:…`).
-
-## Poll
-
-```ts
-import { definePollSource } from "@keystrokehq/keystroke/trigger";
-import workflow from "../workflows/new-inbox";
-
-export default definePollSource({
-  slug: "new-inbox",
-  schedule: "*/5 * * * *",
-  run: () => ({ emails: [] }),
-}).attach({ workflow });
-```
-
-Poll filtering uses a **function predicate** (not a Zod schema like webhooks) — either `.filter((result) => …)` chained on the source, or a `filter:` option. Returning falsy skips the tick. Group polls that should run together with `definePollSource({ id: "...", … })`.
-
-### Ephemeral poll (agents)
-
-Agents can register a scheduled codemode script with `set_trigger`:
-
-```ts
-set_trigger({
-  kind: "poll",
-  slug: "inbox",
-  schedule: "*/5 * * * *",
-  code: [
-    'const emails = await tools["list-emails"]({ query: "is:unread" });',
-    "if (emails.items.length === 0) return;",
-    "console.log(JSON.stringify({ count: emails.items.length, items: emails.items }));",
-  ].join("\n"),
-  prompt: "You have {{payload.count}} unread emails.",
-  lifecycle: { maxExecutions: 10 }, // optional: cap runs (also `until`)
-});
-```
-
-- Write the script the same way you would for codemode (`bash` + `js-exec`).
-- `console.log(JSON.stringify(result))` when there is work to do.
-- Log nothing (or `null`) to skip — skipped ticks do not count toward `lifecycle.maxExecutions`.
-- Prompt interpolation matches webhooks (`{{payload.path}}`).
-
-## Attachment patterns
-
-- **Attach to an agent** instead of a workflow: `.attach({ agent, prompt })` — the source's payload drives the agent prompt (interpolated like webhooks).
-- **Fan-out to multiple targets**: chain `.attach(...).attach(...)` (or export an array of attachments) to bind one source to several workflows/agents.
-- **Shared source definitions** can live under `src/triggers/sources/` — that subfolder is excluded from attachment discovery, so it's a safe place for source defs you import elsewhere.
-- Sources also accept optional `name` / `description` metadata.
-
-## Develop & audit
-
-While building, invoke the workflow directly:
-
-```bash
-keystroke workflow run signup-pipeline --input '{"name":"Ada","email":"a@acme.com","company":"Acme"}'
-```
-
-Inspect trigger-driven runs:
-
-```bash
-keystroke trigger runs list signup:signup-pipeline   # --limit / --cursor / --trigger-type
-keystroke trigger runs get signup:signup-pipeline <run-id> --include workflows,trace
-keystroke trigger poll <poll-attachment-id>    # on-demand poll (--group to run a poll group)
-keystroke trigger attachment disable <trigger-slug> <attachment-id>   # pause; `enable` to resume
-```
-
-Check `src/triggers/` in your project for existing patterns before adding new ones.
-
-Related: [workflows](.agents/skills/keystroke-workflows/SKILL.md), [channels](.agents/skills/keystroke-channels/SKILL.md).

package/dist/skills-bundle/skills/keystroke-workflows/SKILL.md

@@ -1,78 +0,0 @@
----
-name: keystroke-workflows
-description: Build keystroke workflows with defineWorkflow — chain actions, call agents, typed Zod IO. Use when authoring src/workflows/ or auditing workflow runs.
-metadata:
-  keystroke-domain: workflows
----
-
-# Workflows
-
-Workflows are **deterministic orchestration**: Zod input/output, a `run` function, and **actions as steps**. Triggers and the CLI invoke them; agents can participate inside actions.
-
-## Example: action chain
-
-```ts
-import { defineWorkflow } from "@keystrokehq/keystroke/workflow";
-import { slackSendMessage } from "@keystrokehq/slack/actions";
-import { z } from "zod";
-import { researchSignup } from "../actions/research-signup";
-import { signupBriefMessage } from "../lib/signup";
-
-export default defineWorkflow({
-  slug: "signup-pipeline",
-  input: z.object({ name: z.string(), email: z.string().email(), company: z.string() }),
-  output: z.object({ brief: z.string(), channel: z.string(), ts: z.string() }),
-  async run(input) {
-    const { brief } = await researchSignup.run(input);
-    const sent = await slackSendMessage.run({
-      channel: "#pipeline",
-      markdown_text: signupBriefMessage({ ...input, brief }),
-    });
-    return { brief, ...sent }; // sent provides { channel, ts }; merge in brief for the output schema
-  },
-});
-```
-
-`research-signup` calls an agent; `slackSendMessage` is an integration action used **directly as a step** here — never wrapped in a custom action. Note the `run` return is spread to satisfy the `output` schema (the Slack action only returns `channel`/`ts`). Keep orchestration in the workflow; an action is a single leaf step and never calls another action.
-
-## Run & audit
-
-```bash
-keystroke workflow run signup-pipeline --input '{"name":"Ada","email":"ada@acme.com","company":"Acme"}'
-keystroke workflow runs list signup-pipeline
-keystroke workflow runs get signup-pipeline <run-id> --include steps,trace
-```
-
-## How workflows get invoked
-
-| From       | How                                                                   |
-| ---------- | --------------------------------------------------------------------- |
-| CLI        | `keystroke workflow run {slug} --input '{...}'`                       |
-| HTTP       | `POST /workflows/{slug}`                                              |
-| Trigger    | cron / webhook / poll attachment in `src/triggers/`                   |
-| Agent tool | import the workflow into an agent's `tools: [workflow]` |
-| Sub-workflow step | import the workflow and `await otherWorkflow.run(input)` inside another workflow's `run` body |
-
-To reuse a workflow inside another workflow, import it and call `await otherWorkflow.run(input)` — a first-class durable step, just like an action or agent (validates the sub-workflow's IO, checkpoints its output, gets its own trace span). The sub-workflow runs inline in the same run, so its inner steps and `ctx.sleep`/`ctx.hook` stay durable; it does **not** spawn a separate tracked run. Never thread `ctx` into it (`otherWorkflow.run(input, ctx)` is not a thing). To run a workflow as its *own* tracked run, import it into an agent's `tools` or invoke it over HTTP.
-
-The workflow `slug` is its identifier and route key. Slugs are unique per primitive kind, so a workflow can share a slug with an agent or trigger, but two workflows cannot share one.
-
-## Durability (the model you must design for)
-
-Workflows are **durable**: each `await` of an action, agent `.prompt()`, or `promptLlm` is recorded as a `step_completed` event. If a later step fails, the run **replays** the log — completed steps return their recorded result instead of running again — and resumes at the first unfinished step. Two rules follow:
-
-- **Side effects go inside steps.** Code in the `run` body that isn't a step (network calls, writes, `Date.now()`, random) re-executes on every replay. Wrap it in an action/agent/`promptLlm` call so it's recorded once.
-- **Keep control flow deterministic, steps idempotent.** Branch on input and recorded step results, not on values that change between attempts. A step can be retried after a transient failure, so design actions to tolerate being called twice with the same input. Retries are automatic — you don't write retry loops; the runtime emits `step_retrying` / `step_failed`.
-
-Step ids are correlation ids: `step:<slug>#<occurrence>` (`#0`, `#1`, …), or `step:<id>` when pinned with `.stepId()`. If an action's position can shift, pin a stable `.stepId()` so replays line up. Durable waits (`ctx.sleep`, `ctx.hook`) suspend the run without holding a process open. See [authoring.md](references/authoring.md).
-
-## Testing
-
-Unit-test through `executeWorkflow` from `@keystrokehq/keystroke/workflow` — never call `workflow.run(...)` directly at the top level of a test (outside a run it has no durable context). Stub costly actions by seeding `step_completed` events in a `MemoryEventLog`. See [testing.md](references/testing.md).
-
-## Next references
-
-- [authoring.md](references/authoring.md) — agents in actions, app connections, composition
-- [testing.md](references/testing.md) — unit tests, stubbing actions, run/trace debugging
-
-Related: [actions](.agents/skills/keystroke-actions/SKILL.md), [triggers](.agents/skills/keystroke-triggers/SKILL.md), [agents](.agents/skills/keystroke-agents/SKILL.md).

package/dist/skills-bundle/skills/keystroke-workflows/references/authoring.md

@@ -1,168 +0,0 @@
-# Workflow authoring
-
-## Keep steps in actions (when they are not agent prompts)
-
-Workflow `run` orchestrates — call actions for deterministic logic and integrations, call agents directly for LLM steps:
-
-```ts
-async run(input) {
-  const { brief } = await researchSignup.run(input);
-  const summary = await support.prompt({
-    message: `Summarize signup research:\n${brief}`,
-  });
-  const sent = await slackSendMessage.run({
-    channel: "#pipeline",
-    markdown_text: signupBriefMessage({ ...input, brief }),
-  });
-  return { brief, ...sent };
-}
-```
-
-Actions are leaf units: an action never calls another action — compose them in the workflow. Need formatting or shared logic between steps? Put it in `src/lib/`, not in a wrapper action.
-
-## Agents as workflow steps
-
-Import the agent and call `.prompt()` directly in the workflow `run`. Each call is a durable step keyed as `step:<agent-slug>#<occurrence>` (same scheme as actions). No wrapper action required when the step is just "prompt this agent."
-
-```ts
-const result = await support.prompt({
-  message: `From: ${input.sender}\nSubject: ${input.latestSubject}`,
-});
-```
-
-Use a wrapper action only when the agent call should also be an agent tool, or when the step bundles non-prompt logic.
-
-For an explicit step id, actions chain `.stepId("x")`; agent prompts take it as an option: `agent.prompt(input, { stepId: "x" })`.
-
-## LLM steps (`promptLlm`)
-
-For a one-shot LLM call without a full agent, use `promptLlm` (from `@keystrokehq/keystroke/workflow`). It's a first-class durable step keyed `step:promptLlm#<occurrence>`. The signature is `promptLlm(prompt, opts)` — the prompt string comes **first**, options second:
-
-```ts
-import { promptLlm } from "@keystrokehq/keystroke/workflow";
-
-// Returns a string when no outputSchema is given:
-const summary = await promptLlm(`Summarize:\n${brief}`, {
-  model: "anthropic/claude-sonnet-4.6",
-});
-```
-
-Pass `outputSchema` (Zod) to get a parsed, schema-validated object back instead of a string — the return type is inferred from the schema:
-
-```ts
-import { z } from "zod";
-
-const Category = z.object({ category: z.enum(["bug", "feature", "question"]) });
-
-const { category } = await promptLlm(`Classify this ticket:\n${ticket}`, {
-  model: "anthropic/claude-sonnet-4.6",
-  outputSchema: Category,
-});
-```
-
-Other options: `system`, `thinkingLevel`, `temperature`, `maxTokens`, `stepId`.
-
-## Sub-workflows as steps
-
-Reuse a whole workflow by importing it and awaiting `.run(input)` — a first-class durable step, same as an action. Keystroke validates the sub-workflow's `input`/`output`, records its output as a checkpoint keyed `step:<sub-slug>#<occurrence>`, and gives it a trace span.
-
-```ts
-import enrichLead from "./enrich-lead";
-
-async run(input) {
-  const enriched = await enrichLead.run({ email: input.email });
-  return { score: enriched.score };
-}
-```
-
-The sub-workflow runs **inline** in the same run: its inner action/agent/`promptLlm` steps and durable waits (`ctx.sleep` / `ctx.hook`) all stay durable, and it does **not** spawn a separate tracked run. Never thread `ctx` — `enrichLead.run(input, ctx)` is not the pattern; the engine supplies the context. Pin an explicit id with `.stepId("x")` when the call's position can shift. For an *independently tracked* run instead, import the workflow into an agent's `tools` or call it over HTTP.
-
-## Durability & retries
-
-As each step completes, its result is written to a run event log. If a later step fails and the run is retried, Keystroke replays the log: completed steps return their recorded result instead of running again, and execution resumes at the first unfinished step. Design for this:
-
-- **Put side effects inside steps.** Work in the `run` body that isn't an action / agent / `promptLlm` call (a raw `fetch`, a DB write, `Date.now()`, `Math.random()`) runs again on every replay. Move it into a step so it's recorded once.
-- **Steps should be idempotent.** A step can be retried after a transient failure, so an action should tolerate being called twice with the same input (use idempotency keys for external writes where it matters).
-- **Keep control flow deterministic.** Branch on the run's input and recorded step results — not on wall-clock time or randomness — so replays take the same path. Each step is recorded under `step:<slug>#<occurrence>`; pin `.stepId("x")` when an action's order can shift so replays still line up. Ids must be unique within a run.
-
-You don't manage retries yourself. The runtime records `step_completed`, `step_retrying`, and `step_failed` events and surfaces them in `keystroke workflow runs get <slug> <run-id> --include steps,trace`.
-
-## Parallel steps
-
-Independent steps run concurrently with `Promise.all` — each `.run()` / `.prompt()` / `promptLlm` inside it is still its own durable step, recorded and replayed individually:
-
-```ts
-const [enriched, scored] = await Promise.all([
-  enrichLead.run({ leadId }),
-  scoreLead.run({ leadId }),
-]);
-```
-
-Correlation ids are assigned per slug in array order (`step:enrich-lead#0`, `step:score-lead#0`). If the branches can change order between attempts (conditionally included, dynamic arrays), pin a stable `.stepId()` on each so replays line up:
-
-```ts
-const results = await Promise.all(
-  leads.map((lead) => enrichLead.run({ leadId: lead.id }).stepId(`enrich:${lead.id}`)),
-);
-```
-
-There's no built-in concurrency limit or fan-out helper — `Promise.all` runs everything at once. For bounded concurrency, batch the array yourself (e.g. chunk and `await` each chunk).
-
-## Handling failures
-
-Retries are **queue-level**: a failed run is re-enqueued (default 3 attempts, exponential backoff) and replays from the event log, so completed steps don't re-run. Each failed attempt emits `step_retrying`; the final failure emits `step_failed`. You don't write retry loops — make steps idempotent so a retried step is safe.
-
-There's no built-in saga, compensation engine, or dead-letter queue. When a later step fails and you need to undo earlier work, orchestrate it yourself with `try/catch` in `run` — catching the error lets the run complete normally (so attach a `compensated` flag to the output rather than rethrowing if you've handled it):
-
-```ts
-async run(input) {
-  await reserveBooking.run({ id: input.bookingId });
-  try {
-    await chargeCustomer.run({ id: input.bookingId });
-    return { ok: true };
-  } catch (error) {
-    await releaseBooking.run({ id: input.bookingId }); // best-effort cleanup
-    return { ok: false, compensated: true };
-  }
-}
-```
-
-If you let the error propagate instead, the run fails and the queue retries it — fine for transient failures, but it replays from the log, so any cleanup must itself be a recorded, idempotent step.
-
-## Durable run context (`ctx`)
-
-`run(input, ctx)` receives a second argument exposing `runId`, `trigger` (`api` | `cron` | `webhook` | `poll` | `retry`), and the durable wait primitives `ctx.sleep(...)` and `ctx.hook(...)`. Both **suspend** the run (the replay engine resumes it later) so long waits and external callbacks don't hold a process open.
-
-```ts
-// Durable delay: number (ms), duration string, or a Date
-await ctx.sleep("1h");
-
-// Durable hook: suspend until an external system POSTs to the resume URL
-async run(input, ctx) {
-  const approval = ctx.hook<{ approved: boolean }>();
-  await slackSendMessage.run({
-    channel: "#approvals",
-    markdown_text: `Approve deploy? ${approval.resumeUrl}`,
-  });
-  const { approved } = await approval; // suspends here until resumed
-  return { approved };
-}
-```
-
-`ctx.hook(options?)` takes an optional `token` (reuse a stable resume token) and `schema` (Zod validation of the resume payload). The returned handle exposes `token` and `resumeUrl` before you await it — surface that URL so the approver/callback can resume the run.
-
-## Agents inside actions
-
-When an action must call an agent (e.g. the action is reused as an agent tool), call `.prompt()` inside the action's `run`. That prompt is not a separate workflow step — the action is.
-
-## Connecting apps
-
-Sync the app into `src/apps/`, author with `app.action()`, then `keystroke connect <slug>` before testing. Catalog integration actions from npm packages work once the app is connected.
-
-## Slugs
-
-Slugs are scoped per primitive kind: a `slug` must be unique among workflows, among agents, and among triggers, but the same `slug` may be reused across kinds (a `pricing` agent and a `pricing` workflow can coexist). The workflow's `slug` is also its HTTP route segment (`POST /workflows/{slug}`).
-
-## Subscription mode
-
-`defineWorkflow` accepts an optional `subscription: { mode: "system" | "subscribable" }` to control how the workflow can be subscribed to. Omit it for the default behavior.