@keystrokehq/cli 0.1.15 → 0.1.17

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

@@ -1,132 +1,80 @@
 ---
 name: keystroke-cli
-description: Keystroke CLI — local dev vs cloud platform targets, config switching, deploy, and when to use each. Use when running keystroke commands against localhost or a deployed project.
+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. Most commands hit an **API target**: either **local** (your keystroke server) or **cloud** (keystroke platform control plane → deployed keystroke server for that project).
+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.
 
-## Local vs cloud
-
-| Target    | Use for                                                                                                | Default URL                           |
-| --------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------- |
-| **Local** | Development and testing — iterate on `src/`, run workflows/agents against your machine, debug sessions | `PUBLIC_PLATFORM_URL` in project `.env` (dev session when `keystroke dev` is running) |
-| **Cloud** | Invoking, listing, and operating a **deployed** project — production runs, trigger URLs, remote audit  | `{platformUrl}/api/projects/{id}`     |
-
-**Rule of thumb:** while you are building or validating changes, use **local**. After deploy, use **cloud** to invoke and inspect what is live.
-
-Auth (`keystroke auth login`) is **shared** — one login in the keychain. Switching local ↔ cloud or organizations does not require re-authenticating.
-
-**Organizations (cloud only)**
+## Log in
 
 ```bash
-keystroke auth login                 # auto-picks org if you have one; prompts if several
-keystroke auth login --org <id>      # headless org pick
-keystroke config org list           # list memberships
-keystroke config use org            # interactive switch
-keystroke config use org <id>       # switch active org
+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
 ```
 
-## Platform projects
+One login covers every command. `auth login` auto-picks your org if you have one and prompts if there are several.
 
-A **platform project** is a deploy target on the keystroke control plane — not your local repo directory (`keystroke init` scaffolds the latter).
+## 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; see deploy skill for --filter
-keystroke config use project <id>     # set default cloud target (works before deploy)
+keystroke deploy --project <id>       # build + upload src/; see deploy skill for --filter
 ```
 
-New projects are **inactive** until deploy. You can set the default project before deploy; runtime commands still require an active project. The CLI prints hints when the list is empty or when status is `inactive`.
-
-Full deploy, filtered module redeploy, and WIP ignore: [deploy skill](../keystroke-deploy/SKILL.md).
-
-## Quick start
+`--project` selects the deploy target. It's a global flag that works before or after the subcommand (`keystroke deploy --project <id>`).
 
-**Local development**
+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 dev                    # watch + rebuild; other CLI commands auto-target local while this runs
-keystroke start                  # or one-shot local server
-keystroke workflow run greeting --input '{"name":"Ada"}'
-keystroke agent prompt hello --message "Hi"
+keystroke config use project <id>
 ```
 
-**Cloud (deployed project)**
+To target a different project for a single command without changing the default:
 
 ```bash
-keystroke auth login
-keystroke project list                              # or: project create --name "My app"
-keystroke deploy --project <project-id>
-keystroke workflow run greeting --input '{"name":"Ada"}'   # hits cloud after deploy
-keystroke trigger list
-keystroke trigger list --endpoint stripe   # all webhooks on a shared endpoint
-keystroke trigger url stripe               # shared route URL (or use a trigger key)
+keystroke workflow runs list greeting --project <id>
 ```
 
-## Switch targets
+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.
 
-Config lives in `~/.keystroke`. Two settings work together:
-
-| Setting           | Purpose                                                                       |
-| ----------------- | ----------------------------------------------------------------------------- |
-| `activeProjectId` | Which cloud project you use (set by deploy; **not** cleared when going local) |
-| `apiTarget`       | `local` or `platform` — default routing for commands                          |
+Full deploy, filtered module redeploy, and WIP ignore: [deploy skill](../keystroke-deploy/SKILL.md).
 
-```bash
-keystroke config show
-keystroke config use local              # local dev; cloud project id preserved
-keystroke config use cloud              # back to stored activeProjectId
-keystroke config use project <id>       # swap active cloud project
-```
+## Run & inspect
 
-**One-off overrides** (do not change config):
+After deploy, runtime commands operate on your project:
 
 ```bash
-keystroke --local workflow runs list greeting
-keystroke --project other-id trigger list
+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)
 ```
 
-While `keystroke dev` is running, other commands auto-target **local** unless you pass `--project`.
-
-## Resolution order
-
-1. `--local` → local
-2. `keystroke dev` session active → local
-3. `--project <id>` → cloud (that project only)
-4. `apiTarget=local` → local
-5. `apiTarget=platform` + `activeProjectId` → cloud
-6. default → local
-
-Full detail: [api-targets.md](references/api-targets.md).
+Always use the CLI to inspect runs and sessions — do not hand-craft HTTP requests.
 
-## Commands by target
+## Commands at a glance
 
-| Command                                                            | Typical target                                             |
-| ------------------------------------------------------------------ | ---------------------------------------------------------- |
-| `dev`, `start`, `build`                                            | Local project only                                         |
-| `project list`, `project create`                                   | Platform control plane (org-scoped)                        |
-| `deploy`                                                           | Platform (sets `activeProjectId` + `apiTarget=platform`)   |
-| `workflow`, `agent`, `trigger`, `app`, `connect`, `health` | Follows resolved target                                    |
-| `auth login`                                                       | Web dashboard (`webUrl`); token reused for cloud API calls |
-
-## Audit & debug
-
-Always use the CLI — do not hand-craft HTTP against the wrong host.
-
-```bash
-# Local: default while developing
-keystroke workflow runs list signup-pipeline
-keystroke agent sessions get support <session-id> --include messages,trace
-
-# Cloud: after deploy or keystroke config use cloud
-keystroke trigger list
-keystroke trigger list --endpoint shared-hub
-keystroke trigger url incoming-message
-```
+| 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        |
+| `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](.agents/skills/keystroke-deploy/SKILL.md), [apps](.agents/skills/keystroke-apps/SKILL.md), [workflows](.agents/skills/keystroke-workflows/SKILL.md), [agents](.agents/skills/keystroke-agents/SKILL.md), [triggers](.agents/skills/keystroke-triggers/SKILL.md).
+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

@@ -7,7 +7,7 @@ metadata:
 
 # Deploy
 
-Deploy uploads a `dist/` tarball to the keystroke **platform** and promotes a new project-server runtime (blue/green). Local `keystroke start` / `keystroke dev` never deploy — use this skill when shipping to cloud.
+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
 
@@ -17,6 +17,8 @@ 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
@@ -24,10 +26,10 @@ Deploy always **builds before upload**. Full deploy wipes `dist/` (`clean: true`
 ```bash
 keystroke build                           # optional preview; deploy rebuilds anyway
 keystroke deploy --project <slug>
-keystroke deploy --dir ./my-app --project <slug>
+keystroke deploy --project <slug> --dir ./my-app
 ```
 
-After success: `activeProjectId` and `apiTarget=platform` are set. Verify with `keystroke config use cloud` and `keystroke workflow run <key> --input '{}'`.
+After success the project becomes the active target for later commands. Verify with `keystroke workflow run <key> --input '{}'`.
 
 ## Filtered deploy (one module)
 
@@ -58,7 +60,7 @@ Keep draft agents/workflows/triggers in `src/` but out of the runtime:
 - `ignore` — broken or not-ready; stays out of `dist/` everywhere.
 - `ignore:deploy` — runs locally; excluded from deploy only.
 
-A shipped module that **imports** an ignored file fails the build (import guard). Triggers attached to an ignored workflow need the same directive.
+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).
 
@@ -66,10 +68,10 @@ Detail: [wip-ignore.md](references/wip-ignore.md).
 
 | Command            | Phase   | Output                                      |
 | ------------------ | ------- | ------------------------------------------- |
-| `keystroke build`  | `build` | `dist/` for local inspection                |
+| `keystroke build`  | `build` | `dist/` for inspection                      |
 | `keystroke deploy` | `deploy`| `dist/` + upload; honors `ignore:deploy`    |
 
-`keystroke dev` / `keystroke start` use incremental builds (`clean: false`). Deploy always runs a fresh build first.
+Deploy always runs a fresh, clean build before upload.
 
 Detail: [build-and-full-deploy.md](references/build-and-full-deploy.md).
 
@@ -78,13 +80,12 @@ Detail: [build-and-full-deploy.md](references/build-and-full-deploy.md).
 - **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 on the cloud target. See [apps skill](../keystroke-apps/SKILL.md).
+- **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 config use cloud
-keystroke --project <slug> project deployments list
+keystroke project deployments list --project <slug>
 keystroke workflow run morning-check --input '{}'
 keystroke trigger list
 ```

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

@@ -7,7 +7,9 @@
 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.
+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
 

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

@@ -9,6 +9,8 @@ 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.
@@ -41,8 +43,7 @@ Change `keystroke.config.ts` or project-wide assets → run a **full** deploy.
 ## Verify
 
 ```bash
-keystroke --project <slug> project deployments list   # new version active
-keystroke config use cloud
+keystroke project deployments list --project <slug>   # new version active
 keystroke workflow run <workflow-slug> --input '{}'
 ```
 

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

@@ -1,12 +1,15 @@
 # WIP modules and `@keystroke ignore`
 
-Place the directive at the **top** of a module file under `src/agents/`, `src/workflows/`, or `src/triggers/`.
+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`) |
@@ -21,7 +24,7 @@ Place the directive at the **top** of a module file under `src/agents/`, `src/wo
 
 ## Import guard
 
-If a **shipped** module imports a file marked `@keystroke ignore` (either form), the build **fails**. Compose in workflows instead of importing ignored actions from production modules.
+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
 

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

@@ -15,11 +15,15 @@ Files under `src/files/` mount into the agent sandbox at `/workspace/agent/`.
 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/agent";
-import { defineSandbox } from "@keystrokehq/sandbox";
+import { defineAgent } from "@keystrokehq/keystroke/agent";
+import { defineSandbox } from "@keystrokehq/keystroke/sandbox";
 
 export default defineAgent({
   slug: "support",
@@ -28,8 +32,12 @@ export default defineAgent({
 });
 ```
 
-Use `defineSandbox({ files: "shared" })` to mount `src/files/shared/` instead.
+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 `keystroke start`, verify behavior with `keystroke agent prompt support --message "…"`.
+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

@@ -28,10 +28,15 @@ At runtime → `/workspace/agent/skills/support/`.
 
 ## SKILL.md
 
-Follow [Agent Skills](https://agentskills.io/specification): YAML frontmatter with `name` (matches folder) and `description`. Keep the body short; put detail in `references/`.
+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/{key}/` and fix `name` to match the folder.
+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

@@ -7,18 +7,18 @@ metadata:
 
 # Triggers
 
-Triggers **attach** a source to a workflow. No business logic here — only schedule, endpoint, validation, and filters.
+Triggers **attach** a source to a target (a workflow or an agent). No business logic here — only schedule, endpoint, validation, and filters.
 
-Attachment id: `{triggerKey}:{workflowKey}` (e.g. `signup:signup-pipeline`).
+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/trigger";
+import { defineCronSource } from "@keystrokehq/keystroke/trigger";
 import workflow from "../workflows/morning-check";
 
 export default defineCronSource({
-  key: "morning-check",
+  slug: "morning-check",
   schedule: "0 9 * * *",
 }).attach({ workflow });
 ```
@@ -26,12 +26,12 @@ export default defineCronSource({
 ## Webhook
 
 ```ts
-import { defineWebhookSource } from "@keystrokehq/trigger";
+import { defineWebhookSource } from "@keystrokehq/keystroke/trigger";
 import { z } from "zod";
 import workflow from "../workflows/signup-pipeline";
 
 export default defineWebhookSource({
-  key: "signup",
+  slug: "signup",
   endpoint: "signup",
   request: z.object({
     name: z.string().trim().min(1),
@@ -47,20 +47,22 @@ Use optional Zod `filter` for extra constraints beyond `request`:
 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 `key`, `request`, `filter`, and `transform`. Unmatched payloads return `{ ok: true, skipped: true }`.
+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({
-  key: "stripe-invoice-paid",
+  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 key/schema/filter
+// src/triggers/stripe-subscription-deleted.ts — same endpoint, different slug/schema/filter
 ```
 
 List or inspect all triggers on an endpoint:
@@ -71,21 +73,23 @@ keystroke trigger get stripe          # same rows as list --endpoint (shared rou
 keystroke trigger url stripe          # one webhook URL for the route
 ```
 
-Use each trigger's `key` for `trigger get` / run history (`keystroke trigger runs list stripe-invoice-paid:…`).
+Use each trigger's `slug` for `trigger get` / run history (`keystroke trigger runs list stripe-invoice-paid:…`).
 
 ## Poll
 
 ```ts
-import { definePollSource } from "@keystrokehq/trigger";
+import { definePollSource } from "@keystrokehq/keystroke/trigger";
 import workflow from "../workflows/new-inbox";
 
 export default definePollSource({
-  key: "new-inbox",
+  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`:
@@ -93,7 +97,7 @@ Agents can register a scheduled codemode script with `set_trigger`:
 ```ts
 set_trigger({
   kind: "poll",
-  key: "inbox",
+  slug: "inbox",
   schedule: "*/5 * * * *",
   code: [
     'const emails = await tools["list-emails"]({ query: "is:unread" });',
@@ -101,14 +105,22 @@ set_trigger({
     "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 `maxExecutions`.
+- 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:
@@ -120,11 +132,12 @@ keystroke workflow run signup-pipeline --input '{"name":"Ada","email":"a@acme.co
 Inspect trigger-driven runs:
 
 ```bash
-keystroke trigger runs list signup:signup-pipeline
+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
+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), [gateways](.agents/skills/keystroke-gateways/SKILL.md).
+Related: [workflows](.agents/skills/keystroke-workflows/SKILL.md), [channels](.agents/skills/keystroke-channels/SKILL.md).

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

@@ -12,8 +12,8 @@ Workflows are **deterministic orchestration**: Zod input/output, a `run` functio
 ## Example: action chain
 
 ```ts
-import { defineWorkflow } from "@keystrokehq/workflow";
-import { postMessage } from "@keystrokehq/slack/actions";
+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";
@@ -24,12 +24,16 @@ export default defineWorkflow({
   output: z.object({ brief: z.string(), channel: z.string(), ts: z.string() }),
   async run(input) {
     const { brief } = await researchSignup.run(input);
-    return postMessage.run({ channel: "#pipeline", text: signupBriefMessage({ ...input, brief }) });
+    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; `postMessage` is an integration action used **directly as a step** here — never wrapped in a custom action. Keep orchestration in the workflow; an action is a single leaf step and never calls another action.
+`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
 
@@ -41,18 +45,29 @@ keystroke workflow runs get signup-pipeline <run-id> --include steps,trace
 
 ## How workflows get invoked
 
-| From             | How                                                                   |
-| ---------------- | --------------------------------------------------------------------- |
-| CLI              | `keystroke workflow run {key} --input '{...}'`                        |
-| Trigger          | cron / webhook / poll attachment in `src/triggers/`                   |
-| Agent tool       | `defineWorkflowTool(workflow)` from `@keystrokehq/runtime` on an agent |
-| Another workflow | call from `run`                                                       |
+| 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 |
 
-`key` must be unique across agents, workflows, triggers, and actions.
+There is no first-class "call another workflow" step. To share logic between workflows, extract it into `src/lib/` (or an action, which adds typed IO and its own durable checkpoint). To run a workflow as its own tracked run, expose it as an agent tool (`defineWorkflowTool`) or invoke it over HTTP. Calling another workflow's `.run()` directly skips that workflow's input/output validation (the durable step context is preserved inside a run, but the IO schemas are not re-applied).
+
+The workflow `slug` is its identifier and route key, and must be unique across agents, workflows, triggers, and actions.
+
+## 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/workflow` — never call `workflow.run(...)` directly (skips validation + action context). Stub costly actions by seeding `step_completed` events in a `MemoryEventLog`. See [testing.md](references/testing.md).
+Unit-test through `executeWorkflow` from `@keystrokehq/keystroke/workflow` — never call `workflow.run(...)` directly (skips validation + action context). Stub costly actions by seeding `step_completed` events in a `MemoryEventLog`. See [testing.md](references/testing.md).
 
 ## Next references