@keystrokehq/cli 0.1.29 → 0.1.31

package/dist/skills-bundle/_AGENTS.mcp.md

@@ -59,6 +59,8 @@ Workflows are useful when you know the order of work: call an action, prompt an
 | **Durability**             | Completed steps are recorded and replayed, so retries resume instead of restarting         |
 | **Durable waits**          | `ctx.sleep()` and `ctx.hook()` suspend a run for a delay or until it is resumed externally |
 
+Workflows also render as an interactive **canvas** in the platform. Keep durable work in steps and orchestrate them directly in `run` — the build blocks steps called outside a workflow file or nested in another call's arguments, and warns on patterns that render as opaque blocks (`.map` over steps, `Promise.all(arr.map(...))`, reused helpers, spread step inputs). Read `search_docs "workflow best practices"` before writing non-trivial workflows.
+
 ### Common failures
 
 - **Research real APIs before mirroring them** — building actions for custom integrations is very common; web search and fetch the actual reference & explore relevant docs, don't guess endpoints or payload shapes.
@@ -132,6 +134,7 @@ Common pages to read with `query_docs` (e.g. `cat /learn/agents/build-agents.mdx
 | `/explore-features` | Guide to find relevant feature documentation |
 | `/learn/agents/build-agents` | Models, tools, subagents, sandboxes, MCP tools on agents |
 | `/learn/workflows/build-workflows` | Steps, orchestration, sandboxes, durable waits |
+| `/learn/workflows/authoring-best-practices` | Canvas-legible, replayable workflow patterns (hard + soft rules) |
 | `/learn/actions/overview` | Action rules (leaf units, no action-in-action) |
 | `/learn/triggers/overview` | Choosing a trigger type |
 | `/learn/credentials/connect-credentials` | Connecting apps, OAuth, project credentials |

package/dist/skills-bundle/_AGENTS.md

@@ -135,7 +135,28 @@ export default defineWorkflow({
 
 Use `promptLlm(...)` (import from `@keystrokehq/keystroke/workflow`) for one-shot generation/classification. Use `agent.prompt(...)` when the step needs tools, memory, or multi-turn reasoning.
 
-**Durability** — completed steps replay on retry: keep side effects inside steps; make steps idempotent; keep control flow deterministic (no `Date.now()` / randomness); pin `.stepId()` when the step set can change. `ctx.sleep`/`ctx.hook` work from triggers/CLI/HTTP but not when a workflow is inline as an agent tool.
+**Durability** — completed steps replay on retry: keep side effects inside steps; make steps idempotent; keep control flow deterministic (no `Date.now()` / randomness). Step ids are assigned automatically from each call's position in `run`, so adding or removing an unrelated step never shifts the others. `ctx.sleep`/`ctx.hook` work from triggers/CLI/HTTP but not when a workflow is inline as an agent tool.
+
+#### Canvas-legible, replayable workflows
+
+The platform renders every workflow as an interactive **canvas** (a deploy-time parser reads your source) and lights up each step in run history. These habits keep steps rendering as real nodes and keep runs replayable. Full detail: `/learn/workflows/authoring-best-practices`.
+
+**Principle** — put durable work in steps (`action.run`, `agent.prompt`, `promptLlm`, `ctx.sleep`, `ctx.hook`) and orchestrate them directly in `run` (or a same-file helper). Code between steps isn't checkpointed — it re-runs on every replay.
+
+**Hard rules (break them and the build fails):**
+
+1. **Never call a step outside a workflow file** — a `.run()` / `.prompt()` in `src/lib/**` or any imported module is invisible and uncorrelated. Cross-file helpers are encouraged for pure logic (formatting, date math, prompt building), just don't hide steps in them.
+2. **Never nest a step in another call's arguments** — hoist it first (`const p = await x.run({}); await y.run({ v: p.field })`).
+
+**Soft rules (build warns; the step still runs but renders as one opaque block):**
+
+- Call steps **directly in `run()`**; a same-file helper is fine only if called once (reused helpers collapse).
+- Iterate step work with **`for-of`**, not `.map` / `.filter` / `.forEach` / `.reduce`.
+- Parallelize with a **literal** `Promise.all([a.run(), b.run()])`, not `Promise.all(arr.map(...))` / `race` / `allSettled` / `any`.
+- List step **input fields explicitly** — no `...spread` or computed `[key]:` keys.
+- Branch with **`if` / `else` / `switch`**, not step-bearing ternaries.
+- Keep all side effects and non-determinism **inside steps**.
+- Do HTTP/IO through an **action** (prebuilt integration *or* your own `defineAction`/`defineApp`), never a bare `fetch` in `run` — an inline `fetch` is neither a durable step nor a canvas node.
 
 ### Action — `defineAction`
 
@@ -275,6 +296,7 @@ Below is a sample of some of the most common documentation pages.
 | `/learn/agents/test-agents` | Testing agents locally |
 | `/learn/agents/external-channels` | Slack / external channel bindings |
 | `/learn/workflows/build-workflows` | Steps, orchestration, sandboxes |
+| `/learn/workflows/authoring-best-practices` | Canvas-legible, replayable workflow patterns (hard + soft rules) |
 | `/learn/workflows/test-workflows` | Workflow tests |
 | `/learn/workflows/run-workflows` | Running workflows, inspecting output |
 | `/learn/actions/overview` | Action rules (leaf units, no action-in-action) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/cli",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/keystrokehq/keystroke.git",