@keystrokehq/cli 0.1.38 → 0.2.0

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

@@ -0,0 +1,93 @@
+---
+name: keystroke-cli
+description: Keystroke CLI — log in, manage projects, deploy your src/, and run/inspect what's deployed (workflows, agents, triggers, apps). Use when running keystroke commands for a project.
+metadata:
+  keystroke-domain: cli
+---
+
+# CLI
+
+The CLI is the primary interface for keystroke projects. You build in `src/`, deploy to your project on the platform, then run and inspect what's deployed. The loop is **edit → deploy → run/inspect → repeat**; deploy often.
+
+## Log in
+
+```bash
+keystroke auth login                 # once; token stored in the OS keychain and reused
+keystroke auth login --org <org-slug>  # headless org pick
+keystroke config org                 # list org memberships
+keystroke config use org <org-slug>  # switch active org
+```
+
+One login covers every command. `auth login` auto-picks your org if you have one and prompts if there are several.
+
+## Projects
+
+A **project** is your deploy target on the platform. `keystroke init` scaffolds the local repo; the platform project is where it runs.
+
+```bash
+keystroke project list
+keystroke project create --name "My app" --description "Optional"
+keystroke deploy --project <id>       # build + upload src/; see deploy skill for --filter
+```
+
+`--project` selects the deploy target. It's a global flag that works before or after the subcommand (`keystroke deploy --project <id>`).
+
+New projects are **inactive** until the first deploy. After a deploy, `keystroke deploy` remembers the project (saved in `~/.keystroke`), so later commands target it without `--project`. To switch which project later commands use:
+
+```bash
+keystroke config use project <id>
+```
+
+To target a different project for a single command without changing the default:
+
+```bash
+keystroke workflow runs list greeting --project <id>
+```
+
+By default the CLI targets the cloud platform. To run commands against a locally running server (`keystroke start` / `keystroke dev`), use the global `--local` flag for one command, or `keystroke config use local` / `keystroke config use cloud` to switch the default target.
+
+Full deploy, filtered module redeploy, and WIP ignore: [deploy skill](../keystroke-deploy/SKILL.md).
+
+## Pull an existing project
+
+`keystroke pull` is the inverse of `deploy`: it downloads a project's **active deploy source** into a local directory, installs dependencies, and syncs bundled skills. Use it to start working on a project that was created or deployed elsewhere (e.g. on a fresh machine).
+
+```bash
+keystroke pull --project <id>            # into the current directory
+keystroke pull --project <id> --dir ./my-app
+keystroke pull --project <id> --force    # overwrite an existing local tree
+```
+
+It targets the active project when `--project` is omitted. A directory that already holds an unrelated project is refused unless you pass `--force`; a directory from a prior pull of the **same** project refreshes in place, and a no-op pull (already on the active artifact) exits without changes.
+
+## Run & inspect
+
+After deploy, runtime commands operate on your project:
+
+```bash
+keystroke workflow run greeting --input '{"name":"Ada"}'
+keystroke workflow runs list greeting
+keystroke workflow runs get greeting <run-id> --include steps,trace
+keystroke agent prompt hello --message "Hi"
+keystroke agent sessions get support <session-id> --include messages,trace
+keystroke app list
+keystroke trigger list
+keystroke trigger list --endpoint stripe   # all webhooks on a shared endpoint
+keystroke trigger url stripe               # shared route URL (or a trigger key)
+```
+
+Always use the CLI to inspect runs and sessions — do not hand-craft HTTP requests.
+
+## Commands at a glance
+
+| Command                                            | What it does                                              |
+| -------------------------------------------------- | -------------------------------------------------------- |
+| `auth login`                                       | Authenticate; token reused for all commands              |
+| `project list`, `project create`                   | Manage deploy targets in the active org                  |
+| `deploy`                                           | Build `src/` and ship it; sets the active project        |
+| `pull`                                             | Download a project's active deploy source into a local dir |
+| `workflow`, `agent`, `trigger`, `app`              | Run and inspect resources on your project                |
+| `connect <slug>`                                   | Connect an integration (see apps skill)                  |
+| `config use project <id>`, `config show`           | Set/inspect the active project                           |
+
+Related: [deploy](../keystroke-deploy/SKILL.md), [apps](../keystroke-apps/SKILL.md), [workflows](../keystroke-workflows/SKILL.md), [agents](../keystroke-agents/SKILL.md), [triggers](../keystroke-triggers/SKILL.md).

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

@@ -0,0 +1,93 @@
+---
+name: keystroke-deploy
+description: Build and deploy keystroke projects — full deploy, filtered module redeploy, @keystroke ignore for WIP modules. Use when shipping to the platform or keeping draft code out of production.
+metadata:
+  keystroke-domain: deploy
+---
+
+# Deploy
+
+Deploy uploads a `dist/` tarball to the keystroke **platform** and promotes a new project-server runtime (blue/green). Use this skill when shipping your project to the platform.
+
+## Prerequisites
+
+```bash
+keystroke auth login
+keystroke project list                    # or: project create --name "My app"
+keystroke deploy --project <slug>         # first deploy must be full (no --filter)
+```
+
+`--project` selects the deploy target; as a global flag it works before or after `deploy`. After a successful deploy the project becomes the active target (saved in `~/.keystroke`), so later commands (including subsequent deploys) can omit it.
+
+Deploy always **builds before upload**. Full deploy wipes `dist/` (`clean: true`), rebuilds all modules, regenerates `route-manifest.json`, then packs and uploads.
+
+## Full deploy
+
+```bash
+keystroke build                           # optional preview; deploy rebuilds anyway
+keystroke deploy --project <slug>
+keystroke deploy --project <slug> --dir ./my-app
+```
+
+After success the project becomes the active target for later commands. Verify with `keystroke workflow run <key> --input '{}'`.
+
+## Filtered deploy (one module)
+
+Redeploy a single agent/workflow/trigger without rebuilding everything. Requires an **active** artifact from a prior full deploy.
+
+```bash
+keystroke deploy --project <slug> --filter workflows/morning-check
+keystroke deploy --project <slug> --filter agents/support --filter workflows/signup-pipeline
+```
+
+`--filter` matches exact build entry keys (`agents/foo`, `workflows/bar`, `triggers/baz`) — the paths under `src/` without extension. Repeat the flag for multiple modules. No globs.
+
+**How it works:** isolated rebuild of each matched module → download active prod tarball → overlay rebuilt `.mjs` files → merge `route-manifest.json` by module → upload as a normal full deploy.
+
+**Carried forward from prod:** `config.mjs`, bundled assets, skills metadata, and all untouched modules. Skill/asset drift is not validated in v1.
+
+Detail: [filtered-deploy.md](references/filtered-deploy.md).
+
+## WIP modules (`@keystroke ignore`)
+
+Keep draft agents/workflows/triggers in `src/` but out of the runtime:
+
+```ts
+// @keystroke ignore          // skip local build, dev, and deploy
+// @keystroke ignore:deploy   // local build + dev only; omitted from deploy
+```
+
+- `ignore` — broken or not-ready; stays out of `dist/` everywhere.
+- `ignore:deploy` — runs locally; excluded from deploy only.
+
+Import guard: a shipped module that **imports** an `@keystroke ignore` file fails the build in **every** phase; importing an `@keystroke ignore:deploy` file builds fine locally and fails only at **deploy** time. Triggers attached to an ignored workflow need the same directive.
+
+Detail: [wip-ignore.md](references/wip-ignore.md).
+
+## Build vs deploy
+
+| Command            | Phase   | Output                                      |
+| ------------------ | ------- | ------------------------------------------- |
+| `keystroke build`  | `build` | `dist/` for inspection                      |
+| `keystroke deploy` | `deploy`| `dist/` + upload; honors `ignore:deploy`    |
+
+Deploy always runs a fresh, clean build before upload.
+
+Detail: [build-and-full-deploy.md](references/build-and-full-deploy.md).
+
+## Common mistakes
+
+- **First deploy with `--filter`** — fails; run full deploy once.
+- **Wrong `--dir`** — builds a different tree than you edited.
+- **Expecting full refresh with `--filter`** — only matched modules rebuild; rest comes from active prod.
+- **Connected apps aren't in `.env`** — deploy never uploads `.env`; connect apps for your project. See [apps skill](../keystroke-apps/SKILL.md).
+
+## Audit deployed runtime
+
+```bash
+keystroke project deployments list --project <slug>
+keystroke workflow run morning-check --input '{}'
+keystroke trigger list
+```
+
+Related: [cli skill](../keystroke-cli/SKILL.md), [apps skill](../keystroke-apps/SKILL.md).

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

@@ -0,0 +1,30 @@
+# 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

@@ -0,0 +1,50 @@
+# 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

@@ -0,0 +1,35 @@
+# 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

@@ -0,0 +1,43 @@
+---
+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

@@ -0,0 +1,42 @@
+---
+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

@@ -0,0 +1,143 @@
+---
+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

@@ -0,0 +1,78 @@
+---
+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 | `defineWorkflowTool(workflow)` from `@keystrokehq/runtime` on an agent |
+| 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, expose it as an agent tool (`defineWorkflowTool`) 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).