@keystrokehq/cli 0.1.38 → 0.2.0

package/dist/skills-bundle/_AGENTS.md

@@ -1,292 +1,144 @@
 # keystroke
 
-This codebase is a Keystroke project. Keystroke is a code-first AI automation platform. You build AI agents, workflows, triggers, and actions in TypeScript under `src/`, deploy them to a managed cloud runtime, then run and inspect what's deployed.
+This codebase is a Keystroke project.
 
-You are the user's AI automation engineer, the coding agent that builds and maintains this project. Read `src/` first (existing agents, workflows, actions, and triggers). Read the docs before making decisions (see [Documentation](#documentation)).
+> Keystroke is a code-first AI automation platform. With it, anyone can build specialized AI agents and workflow automations in TypeScript, then deploy them to a managed cloud platform where they run.
 
-## Match the user's level
+- **Build agents and workflows:** Build agents and workflows with an open TypeScript framework. Run tests, connect integrations, and maintain what you build over time.
+- **Connect to thousands of integrations:** Keystroke has over 1,000 built-in integrations (Slack, Google, Linear, and hundreds more). It is also extremely easy to quickly build a connection for any HTTP API (including private internal APIs) or MCP server.
+- **Deploy what you build:** The Keystroke platform gives teams a managed workspace to run what they build. Deploy agents and workflows from your project. Then, view workflows on an interactive canvas, chat with agents in a chat interface, inspect runs, manage credentials, and collaborate from a shared web platform.
 
-Your user may or may not be technical. Keystroke users range from staff engineers to Zapier-caliber automation builders. You are the medium through which they build.
+## Keystroke projects
 
-- **Mirror their voice.** Only get as technical as the user does. Match their vocabulary.
-- **Narrate in outcomes, not plumbing.** Default to "I'll set this to run every morning and message you a summary", not "deploying the cron trigger to the runtime." Don't surface internal concepts (build artifacts, event logs, correlation IDs, filtered deploys) unless the user has to make a decision about one.
-- **Don't hand them the work.** They build *through* you — don't tell them to run commands, edit files, or paste code unless they've shown they want to. Do it yourself, do it quickly, and report the result.
-- **Simplify the talk, never the work.** Speaking plainly doesn't lower the bar — follow every invariant in this guide regardless of how the user communicates.
-- **If the end-state isn't clear, just ask.** It's okay to clarify how the thing you're building should be built, which integrations to use, etc.
+In Keystroke, everything you build belongs to a project. A project is a shared space for building and running your agents, workflows, triggers, and actions. Think of a project as the unit you build, deploy, give credentials to, invite teammates to, and inspect run history for.
 
-## Local codebase vs platform project
+Keystroke projects use two related ideas:
 
-Keystroke separates *where you write code* from *where it runs*:
+- **Local codebase**: a local directory (this codebase) with `keystroke.config.ts` and `src/` (`keystroke init` scaffolds this). Run it locally with `keystroke start` / `keystroke dev`; no platform project required.
+- **Platform project**: an org-owned cloud record: a deploy target plus a hosted runtime (its own keystroke server, URL, managed credentials). Projects are inactive until their first deploy.
 
-| | What it is | Lives |
-| --- | --- | --- |
-| **Local codebase** | This directory — `keystroke.config.ts` + `src/`. Source of truth. | Your machine / Git |
-| **Platform project** | Org-owned cloud runtime (its own server, URL, credentials, run history). Inactive until first deploy. | Keystroke cloud |
+`keystroke deploy --project <id>` links your local codebase to your platform project: it uploads the built local codebase and activates that platform project's server. After the first deploy the project is saved as your active target (in `~/.keystroke`), so later commands — including subsequent deploys — can drop `--project`. Deployed agents and workflows instantly run there with no additional configuration; the web workspace is where organization members can manage their projects, deployments, logs, credentials, etc.
 
-`keystroke deploy` builds `src/`, uploads it, and promotes it as the project's single live runtime. A deploy replaces what's running — there is no separate dev and prod within one project.
+## How this codebase fits in
 
-### The web platform
+This is the local codebase that defines your agents, workflows, triggers, actions, skills, context files, etc.
 
-Once deployed, your user works in the **web platform** — a shared workspace where they view workflows on an interactive canvas, use agents in a chat interface, inspect runs and traces, manage credentials, and collaborate with teammates. Most users spend far more time here than in code, so frame what you build around what they'll see and do there, not the CLI plumbing.
-
-### Project layout
-
-Keystroke discovers everything under `src/` by convention.
+Projects are scaffolded with an opinionated folder structure (like Next.js for building AI systems):
 
 ```
 my-app/
-  keystroke.config.ts    # project configuration
+  keystroke.config.ts      # project configuration
   src/
-    agents/              # LLM agents
-    actions/             # reusable leaf units of work
-    workflows/           # multi-step automations
-    triggers/            # schedules, webhooks, app events
-    skills/              # runtime playbooks for agents
-    files/               # context files attached to agents
-  AGENTS.md              # this guide
-```
-
-Each primitive imports from `@keystrokehq/keystroke/<piece>` (`/agent`, `/action`, `/workflow`, `/trigger`, `/sandbox`). Integrations are `@keystrokehq/<slug>` packages.
-
-## The deploy-first loop
-
-Keystroke is deploy-first: build, ship, then run and inspect what's live. Deploy often.
-
-1. **Auth once** — `keystroke auth login` (token is stored and reused).
-2. **Edit** primitives under `src/`.
-3. **Deploy** — `keystroke deploy` (full) or `keystroke deploy --filter agents/support` (one module).
-4. **Run** — `keystroke workflow run <slug> --input '{...}'` / `keystroke agent prompt <slug> --message "..."` / `keystroke app execute <app> <tool> --input '{...}'` (connected catalog actions only).
-5. **Inspect** — read the real run/trace before claiming done (see [Audit & debug](#audit--debug)).
-6. Repeat.
-
-```bash
-keystroke auth status                                     # current user + org
-keystroke project list                                    # your platform projects
-keystroke deploy                                          # build + ship src/ (first deploy must be full)
-keystroke workflow run greeting --input '{"name":"Ada"}'  # run a workflow
-keystroke agent prompt hello --message "Hi"               # prompt an agent
-keystroke app execute github github_get_the_authenticated_user     # run a connected catalog action
+    agents/                # LLM agents
+    actions/               # reusable units of work
+    workflows/             # multi-step automations
+    triggers/              # schedules, webhooks, app events
+    skills/                # project skills for agents
+    files/                 # context for attaching to agents
+  AGENTS.md                # this guide
 ```
 
-New project: `keystroke init my-app --yes`, then deploy. Join an existing cloud project: `keystroke pull --project <slug>`.
-
-## Choosing a primitive
-
-| Build a… | When |
-| --- | --- |
-| **Agent** | The path isn't fixed — needs judgment, tool use, language, or multi-turn context. Or when a user is explicitly asking you to build an agent (e.g. AI data analyst for use in Slack, support agent, etc) |
-| **Workflow** | You know the order of steps and want durability and predictability. |
-| **Action** | A single reusable capability (an API call, a computation) used by workflows or agents. |
-| **Trigger** | Something should start a workflow/agent automatically — schedule, webhook, or poll. |
-
-Generally, prefer a workflow (or a plain action / LLM step) unless the path genuinely varies at runtime. Reach for an agent only when the user is clearly asking you to build one or when the work needs judgment, tool selection, or multi-turn context — not just because it's easier to wire up. Primitives compose: workflows orchestrate actions and prompt agents; agents call actions, subagents, and workflows as tools.
-
-## Building blocks
-
-### Agent — `defineAgent`
-
-Required: `slug`, `systemPrompt`, `model`. Everything else is optional.
-
-```ts
-import { defineAgent } from "@keystrokehq/keystroke/agent";
-
-export default defineAgent({
-  slug: "support",
-  systemPrompt: "You are a helpful support assistant. Answer concisely.",
-  model: "anthropic/claude-sonnet-4.6",
-});
-```
-
-- **Model** — exact catalog id in `vendor/model-id` format from https://keystroke.ai/models.md. Do **not** kebab-case the version (`anthropic/claude-sonnet-4.6` is valid; `...-4-6` fails at deploy).
-- **Tools** — attach actions, subagents, workflows, and MCP tools directly in `tools: [...]`. Do **not** hand-roll a `defineTool` + `executeWorkflow()` wrapper. A subagent's tool name is its `slug` and takes a `message`.
-- **Built in**: isolated `/workspace` with file + `bash` tools, session + persistent memory (`memory: false` to disable), `web_search`/`web_fetch` when configured, self-scheduling tools.
-- **Credentials** are declared on actions, not agents — the agent gets them by calling those actions as tools.
-- **Sandbox** — default in-process bash covers most needs. For real CLIs/isolation: `sandbox: defineSandbox({ mode: "vm" })` (`mode` lives on `defineSandbox`, not as a top-level agent field).
-
-### Workflow — `defineWorkflow`
-
-Global `slug`, typed Zod `input`/`output`, a normal `async` `run`.
-
-```ts
-import { defineWorkflow } from "@keystrokehq/keystroke/workflow";
-import { z } from "zod";
-
-export default defineWorkflow({
-  slug: "signup-pipeline",
-  input: z.object({ name: z.string(), email: z.string().email() }),
-  output: z.object({ brief: z.string() }),
-  async run(input) {
-    const { brief } = await researchSignup.run(input);
-    await postBrief.run({ text: brief });
-    return { brief };
-  },
-});
-```
-
-| Step | Syntax |
-| --- | --- |
-| Action | `await action.run(input)` |
-| Agent | `await agent.prompt({ message })` |
-| One-shot LLM | `await promptLlm(prompt, { model, outputSchema? })` |
-| Sub-workflow | `await otherWorkflow.run(input)` — never pass `ctx` |
-| Durable sleep | `await ctx.sleep("1h")` |
-| Durable wait | `await ctx.hook<T>()` |
-
-`ctx` is the second `run` argument (`async run(input, ctx)`) — add it only when a step needs `ctx.sleep`/`ctx.hook`.
-
-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). 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.
+Keystroke discovers everything under `src/` by convention. Add a file that exports an agent, workflow, trigger, etc, and it becomes part of the project. Because the project is code, agents (Cursor, Claude Code, Codex, etc) can read it, change it, run tests, and maintain it over time.
 
-**Hard rules (break them and the build fails):**
+Each primitive imports from `@keystrokehq/keystroke/<piece>` (`/action`, `/agent`, `/workflow`, `/trigger`, `/app`); integrations are their own `@keystrokehq/<slug>` packages. The example files in `src/` show the exact imports.
 
-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 })`).
+## How you work
 
-**Soft rules (build warns; the step still runs but renders as one opaque block):**
+### Build, deploy, test
 
-- 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.
+You build in `src/`, deploy to your project on the platform, then run and inspect what's deployed with the CLI. The loop is: edit → `keystroke deploy` → run/inspect/test → repeat. You should deploy often.
 
-### Action — `defineAction`
-
-Leaf unit — **never calls another action** (yours or an integration's). Enforced at runtime and by lint.
-
-```ts
-import { defineAction } from "@keystrokehq/keystroke/action";
-import { z } from "zod";
-
-export const triage = defineAction({
-  slug: "triage",
-  input: z.object({ message: z.string() }),
-  output: z.object({ priority: z.enum(["low", "normal", "high", "urgent"]) }),
-  run: async (input) => ({ priority: /urgent/i.test(input.message) ? "urgent" : "normal" }),
-});
-```
-
-Compose in workflows. Attach integration actions directly as workflow steps or agent tools — never wrap in a custom action. An action *may* call an agent (`await agent.prompt(...)`).
-
-### Trigger — source + `.attach()`
-
-Exactly three sources: `defineCronSource`, `defineWebhookSource`, `definePollSource`. Default-export the attached result.
-
-```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(), email: z.string().email() }),
-}).attach({ workflow });
+```bash
+keystroke auth status                      # show the current user and active organization
+keystroke auth login                       # once; token is automatically stored and reused
+keystroke project list                     # your projects on the platform
+keystroke deploy --project <id>            # build + ship src/ to the platform
+keystroke workflow run greeting --input '{"name":"Ada"}'   # test and run a workflow
+keystroke agent prompt hello --message "Hi" # test and chat with an agent
 ```
 
-| Source | Use when |
-| --- | --- |
-| **Schedule** (`defineCronSource`) | Time alone starts the run (cron is UTC in prod). Passes `{}` — workflow `input` must accept an empty object. |
-| **Webhook** (`defineWebhookSource`) | Another system pushes events. Best option when available. |
-| **Poll** (`definePollSource`) | Keystroke must pull/check an external system on a schedule. |
+After a deploy, runtime commands (`workflow`, `agent`, `trigger`, `app`, `connect`) operate on that project automatically — no target to manage.
 
-Filters live on the source; `transform` lives on the workflow attachment. Agents use `.attach({ agent, prompt })` (not `transform`). Attachment id: `{sourceSlug}:{targetSlug}`.
+A project is a single live runtime. A deploy replaces what's running on that project — there's no separate dev and prod within one project. You can use `--filter` deploys and `@keystroke ignore` to iterate quickly.
 
-## Integrations & credentials
+To create a new project: `keystroke init my-app --yes`, then deploy.
 
-Keystroke has 1,000+ built-in integrations, and it's easy to build a custom one for any HTTP API or MCP server (including private/internal).
+Look things up cheapest-first: `keystroke <command> --help` for the authoritative flags and usage of any command (local, always current); `keystroke docs search`/`query` for documentation and examples; and `/cli` for the full reference when you need broad discovery.
 
-Discover apps and actions with the CLI — the docs integration index is **not** reliable for discovery:
+### Building agents
 
-One `<app> <tool>` shape flows through discovery → inspect → run. `app action`/`app actions` print the next step (run, import, connect) after their output.
+Agents are useful when a task needs judgment, language understanding, tool use, or multi-turn context.
 
-```bash
-keystroke app list                          # all registered apps
-keystroke app search <query>                # find an app + slug in the full catalog
-keystroke app actions <app> --search <q>    # actions an app exposes
-keystroke app action <app> <tool>           # schema + how to run/import one action
-keystroke app execute <app> <tool> --input '{...}'   # run a connected catalog action (no server)
-keystroke connect <slug>                    # connect an app credential (opens web OAuth/api key flow for the user)
-keystroke credentials list                  # stored credential instances
-keystroke credentials set <key> --set apiKey=@env:MY_KEY   # static API key
-```
-
-`keystroke deploy` **never uploads `.env`** — connect cloud credentials with `keystroke connect` / `keystroke credentials set`. Missing a built-in? Use `defineCredential` + an action, `defineApp`, or `defineMcp`. See `/learn/credentials/custom-integrations`.
+| Capability           | How it works                                        |
+| -------------------- | --------------------------------------------------- |
+| **Instructions**     | `systemPrompt` tells the model how to behave        |
+| **Models**           | `model` uses `vendor/model-id`, with optional `thinkingLevel` |
+| **File system**      | Each session gets a `/workspace` with a built-in file system and bash (code execution) tools |
+| **Web search**       | Built-in `web_search` and `web_fetch` tools when a web provider is configured |
+| **Tools**            | Attach custom tools, MCP tools, subagents, and workflows as tools |
+| **Skills and files** | Attach skills from `src/skills/` and context files from `src/files/` |
+| **Memory**           | Sessions and persistent memory are enabled by default unless disabled |
+| **Sandbox**          | A built-in sandbox environment for using CLIs and more advanced code execution |
+| **Self-scheduling**  | Built-in tools let an agent schedule its own future or recurring runs (ephemeral triggers) |
 
-## Skills & files
+### Building workflows
 
-- **Skills** (`src/skills/<name>/SKILL.md`) — runtime playbooks that teach an agent *how* to do a task. Attach with `skills: ["<name>"]`.
-- **Files** (`src/files/<set>/`) — static context an agent can access. Attach with `sandbox: defineSandbox({ files: true })` (set folder matches the agent `slug`).
+Workflows are useful when you know the order of work: call an action, prompt an agent, branch on the result, wait for approval, then continue.
 
-Both materialize into the agent's `/workspace/agent/...` environment before each prompt.
+| Capability                 | How it works                                                                                  |
+| -------------------------- | --------------------------------------------------------------------------------------------- |
+| **Typed input and output** | Zod schemas validate the payload going in and the result coming out                           |
+| **Action steps**           | Call any [action](/learn/actions/overview) with `.run()`, your own or one from an integration |
+| **Agent steps**            | Prompt an [agent](/learn/agents/overview) with `.prompt()` when a step needs judgment         |
+| **LLM steps**              | Use `promptLlm()` for a one-shot model call without defining a full agent                     |
+| **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    |
 
-## Deploy targets & scope
+### Common failures
 
-- **Target**: after the first deploy, CLI commands target the **cloud** project automatically.
-- **Full vs filtered**: first deploy must be full. Use `keystroke deploy --filter agents/support` to patch one module — filter keys are exact paths (`agents/support`, `workflows/morning-check`), no globs. Changing `keystroke.config.ts` or shared skills/files/integrations needs a full deploy.
-- **WIP**: `// @keystroke ignore` skips a file everywhere; `// @keystroke ignore:deploy` keeps it local but out of deploys. A shipped module cannot import an ignored one.
+- **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.
+- **Run before you claim you are finished** — deploy what you build, run it in the cloud, and read the real output before activating live triggers or claiming you are finished building something. Chat with agents to ensure they behave correctly. Run workflows to ensure they behave correctly.
+- **Cover obvious edge cases** and write simple tests as needed (null field, empty array, a step that throws).
+- **Connected apps aren't in `.env`** — `keystroke deploy` never uploads `.env`; connect apps (aka, integrations) for your project with `keystroke connect <slug>`.
+- **Filtered deploys** — determine if you should do a full vs filtered deploy, or use WIP ignore directives.
+- **Actions are leaf units** - An action never calls another action (including integration actions like `slackSendMessage`). You can compose actions in a workflow, or attach an integration action directly as a workflow step or agent tool. Action can call agents, allowing you to create "subagent tools" or "agent steps".
 
-## Audit & debug
+### Audit & debug (CLI)
 
-Inspect deployed runs with `--include` to see full traces:
+Use the CLI to inspect your deployed project.
 
 ```bash
-keystroke workflow runs list <workflow-slug>
-keystroke workflow runs get <workflow-slug> <run-id> --include steps,trace
-
-keystroke agent sessions list <agent-slug>
-keystroke agent sessions get <agent-slug> <session-id> --include messages,trace
-
-keystroke trigger list
-keystroke trigger url <trigger-slug>                          # webhook URL (+ ?token= on platform)
-keystroke trigger runs get <trigger-slug>:<workflow-slug> <run-id> --include workflows,trace
-keystroke trigger attachment disable <trigger-slug> <trigger-slug>:<workflow-slug>   # pause without redeploy (takes both the trigger slug and the attachment id)
-
-keystroke history list --kind workflow --status failed
+# Workflows
+keystroke workflow list                                                          # list deployed workflows
+keystroke workflow runs list <workflow-slug>                                     # recent runs for a workflow
+keystroke workflow runs get <workflow-slug> <run-id> --include steps,trace       # one run in full: input, each step, execution trace
+
+# Agents
+keystroke agent list                                                             # list deployed agents
+keystroke agent sessions list <agent-slug>                                       # recent sessions for an agent
+keystroke agent sessions get <agent-slug> <session-id> --include messages,trace  # one session in full: messages, execution trace
+
+# Triggers (attachment id is <trigger-slug>:<workflow-slug>)
+keystroke trigger list                                                           # list deployed triggers
+keystroke trigger url <trigger-slug>                                             # print a trigger's webhook URL
+keystroke trigger runs list <trigger-slug>:<workflow-slug>                       # recent runs for a trigger→workflow attachment
+keystroke trigger runs get <trigger-slug>:<workflow-slug> <run-id> --include workflows,trace  # one run in full: workflows fired, execution trace
 ```
 
-Invoke/inspect commands print JSON to stdout (exit 0 on success, 1 on failure) — pipe to `jq`. Lifecycle commands (`init`/`dev`/`deploy`) print human status.
-
-## Before you claim you're done
-
-- [ ] Deployed the change and read the real run output/trace — not just "it should work".
-- [ ] Prompted agents / ran workflows with realistic input and verified behavior.
-- [ ] Researched real APIs before mirroring them in custom integration actions — no guessed endpoints or payloads.
-- [ ] Covered obvious edge cases (null field, empty array, a step that throws) with a simple test where warranted.
-- [ ] Connected any new apps with `keystroke connect` (not `.env`).
-- [ ] Tested manually before deploying attached cron/polling triggers, or used `trigger attachment disable` to pause until ready.
-
-## Common gotchas
-
-1. **Action calling an action** — throws at runtime and fails lint. Compose in a workflow, or attach the integration action directly.
-2. **Bad model id** — must be exact `vendor/model-id` from the catalog; don't kebab the version. Fails at deploy, not typecheck.
-3. **LLM structured output: use `.nullish()`, not `.optional()`** — models emit `"field": null` for "not applicable" values, and Zod `.optional()` rejects `null` (the step fails). Use `.nullish()` (or `.nullable()`) for any optional field in an `outputSchema`.
-4. **Silent fallbacks hide real failures** — for live config (Sheets, DBs, credentials), don't `catch` and quietly substitute fallback/empty data in production paths. A run that "completes" with empty inputs looks like success in the trace but is a silent failure. Throw when required config is missing or empty, and validate response shape, not just status.
-5. **Side effects outside steps** — they re-run on every replay. Keep them inside `.run()` / `.prompt()`.
-6. **Schedule input** — a cron trigger passes `{}`; give the workflow `input: z.object({})`.
+Read `src/` first; existing agents, workflows, actions, and triggers are your best map of how this project works.
 
 ## Documentation
 
-Read the docs regularly and prefer them over prior knowledge. Bias **heavily** toward searching and reading documentation before making any decisions or changes. The documentation contains much more important context than this `AGENTS.md` guide.
+**You should regularly and thoroughly read the documentation** when working with the CLI, building agents/workflows/triggers/actions/etc, and debugging. Bias heavily toward quickly reading documentation before making decisions or changes, and prefer what the docs say over your prior knowledge.
 
-All documentation is available via the CLI (no auth), cheapest-first:
+Documentation is directly available via the CLI (no auth required). Use these CLI commands to search, query, and read the Keystroke documentation:
 
-- `keystroke <command> --help` — authoritative, always-current flags for any command.
-- `keystroke docs search "<query>"` — find pages by topic when you don't know the path.
-- `keystroke docs query "<cmd>"` — read/search pages with `cat`/`rg`/`ls`/`tree`/`head` (e.g. `keystroke docs query "cat /learn/agents/build-agents.mdx"`).
+- **`keystroke docs search "<query>"`** — best for broad or conceptual lookups when you don't know the path (e.g. `keystroke docs search "webhook trigger"`). Returns matching pages with titles and paths; read one by passing its path to `query`.
+- **`keystroke docs query "<command>"`** — exact keyword/regex search, structure exploration, and reading pages by path with a shell-style command (`cat`, `rg`, `ls`, `tree`, `head`). Append `.mdx` to a doc path to read it: `keystroke docs query "cat /quickstart.mdx"`, `keystroke docs query "rg -il trigger /"`, `keystroke docs query "tree / -L 2"`.
 
-`query` is stateless (working dir resets to `/`; use absolute paths or chain with `&&`) and output is capped (~30KB) — prefer targeted `rg -C 3` / `head` over `cat` on large pages.
+Each `query` is stateless — the working dir resets to `/`, so use absolute paths or chain with `&&` — and output is capped (~30KB). Prefer a targeted `rg -C 3 "term" /path.mdx` or `head -n 120 /path.mdx` over `cat` on large pages, and batch several files into one read (`head -n 80 /a.mdx /b.mdx`).
 
-Below is a sample of some of the most common documentation pages.
+Below is a sample of common documentation pages. You can read a page with `keystroke docs query "cat <path>.mdx"`.
 
 | Doc path | Read when |
 | -------- | --------- |
@@ -300,13 +152,13 @@ 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) |
 | `/learn/actions/workflow-steps` | Wiring actions into workflows |
 | `/learn/actions/agent-tools` | Exposing actions as agent tools |
 | `/learn/triggers/overview` | Choosing a trigger type |
+| `/learn/triggers/app-events` | App-event triggers |
 | `/learn/triggers/webhooks` | Webhook triggers |
 | `/learn/triggers/schedules` | Cron / scheduled triggers |
 | `/learn/triggers/polling` | Polling triggers |
@@ -314,7 +166,24 @@ Below is a sample of some of the most common documentation pages.
 | `/learn/credentials/connect-credentials` | `keystroke connect`, OAuth, project credentials |
 | `/learn/credentials/use-credentials` | Using connected apps in code |
 | `/learn/credentials/custom-integrations` | Building a custom HTTP / MCP / GraphQL integration |
-| `/learn/skills/overview` | `src/skills/` skills for agents (runtime, not this guide) |
+| `/learn/skills/overview` | `src/skills/` playbooks for agents (runtime, not this guide) |
 | `/learn/skills/create-skills` | Authoring an agent skill |
 | `/learn/files/overview` | `src/files/` workspace context |
-| `/learn/logs/overview` | Reading run history, debugging deployed runs |
+| `/learn/logs/overview` | Reading run history, debugging deployed runs |
+
+## Integrations and secrets
+
+For searching native integrations use the CLI, not docs. The docs contain an index of integrations, but the documentation integration index is not reliable. To discover apps/integrations and their actions, query the live catalog with the CLI:
+
+```bash
+keystroke app list                                  # list all registered/supported apps
+keystroke app search <query>                        # find an app and its slug in the full catalog
+keystroke app actions <slug> --search <q>           # actions an app exposes
+keystroke app action <action-slug>                  # input/output schema for one action
+keystroke connect <slug>                            # connect an app credential (web flow)
+keystroke credentials list                          # List stored/available credential instances
+```
+
+You can read `/learn/credentials/use-credentials` for using credentials in code and binding credentials to workflow steps and agent tools.
+
+If you ever run into issues with an integration (or a required action isn't supported), it is *extremely* easy to build custom integrations and actions. You can build connections to any HTTP API or MCP server, including internal or private ones. See `/learn/credentials/custom-integrations`.

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

@@ -0,0 +1,160 @@
+---
+name: keystroke-actions
+description: Define keystroke actions — workflow steps and agent tools. Custom API actions use a credential (defineCredential) or an app wrapper (app.action); catalog integrations import from npm packages. Use when authoring src/actions/ or wiring integrations.
+metadata:
+  keystroke-domain: actions
+---
+
+# Actions
+
+One **executable unit** used everywhere: workflow steps, agent tools, and codemode host calls.
+
+Anything that calls an external API needs a **credential**. Two paths: declare a standalone `defineCredential` on a `defineAction` (simplest), or use an **app** wrapper (`app.action()`) when several actions share one connection or you've synced a catalog/custom app into `src/apps/`. See [apps skill](.agents/skills/keystroke-apps/SKILL.md).
+
+## Actions are leaf units — never call an action from an action
+
+An action's `run` must **not** call another action (yours or an integration action like `slackSendMessage`). Composition belongs in a **workflow**; an integration action is used directly as a workflow step or agent tool — not wrapped in a custom action.
+
+```ts
+// ❌ Don't: an action that calls another action
+import { slackSendMessage } from "@keystrokehq/slack/actions";
+export const notify = defineAction({ slug: "notify",
+  run: async (input) => slackSendMessage.run({ channel: input.channel, markdown_text: input.text }),
+});
+
+// ✅ Do: use the integration action directly as a workflow step
+async run(input) {
+  return slackSendMessage.run({ channel: input.channel, markdown_text: buildText(input) });
+}
+```
+
+This is enforced at runtime (calling an action inside an action throws) and by lint (`no-restricted-imports` blocks importing `@keystrokehq/*/actions` inside `src/actions/`). An action **may** call an agent — see below.
+
+## Custom API actions (standalone credential)
+
+The simplest custom integration: declare a `defineCredential` and consume it from a plain `defineAction`. No app needed.
+
+```ts
+import { defineAction } from "@keystrokehq/keystroke/action";
+import { defineCredential } from "@keystrokehq/keystroke/credentials";
+import { z } from "zod";
+
+const acme = defineCredential({ key: "acme", fields: { apiKey: z.string() } });
+
+export const createAcmeTicket = defineAction({
+  slug: "create-acme-ticket",
+  input: z.object({ title: z.string() }),
+  output: z.object({ id: z.string() }),
+  credentials: [acme] as const,
+  async run(input, credentials) {
+    return createTicket({ apiKey: credentials.acme.apiKey, title: input.title });
+  },
+});
+```
+
+Connect it with `keystroke credentials set acme --set apiKey=@env:ACME_API_KEY --scope org`.
+
+## App-backed actions (shared connection / synced apps)
+
+Reach for an app when several actions share one connection, or when you've synced a catalog/custom app:
+
+1. **App first** — create in the dashboard or `keystroke app create`, then `keystroke app sync <slug>` → `src/apps/<name>/app.ts`
+2. **Connect** — `keystroke connect <slug>` (see [apps skill](.agents/skills/keystroke-apps/SKILL.md))
+3. **Action** — `app.action()` in `src/actions/`, reading `credentials[app.slug]` in `run`
+
+```ts
+import { z } from "zod";
+import { kwatch } from "../apps/kwatch/app";
+
+export const kwatchListAlerts = kwatch.action({
+  slug: "kwatch-list-alerts",
+  input: z.object({}),
+  output: z.object({ ok: z.boolean(), alertCount: z.number() }),
+  async run(_input, credentials) {
+    const { apiKey } = credentials["keystroke/kwatch"];
+    return { ok: true, alertCount: 0 };
+  },
+});
+```
+
+Use an app wrapper (over a standalone credential) when a family of actions should share one connection definition.
+
+## Pure actions (no credential)
+
+Use `defineAction` with no `credentials` when the step needs no connection at all (pure logic, local transforms):
+
+```ts
+import { defineAction } from "@keystrokehq/keystroke/action";
+import { z } from "zod";
+
+export const triage = defineAction({
+  slug: "triage",
+  name: "Triage",
+  description: "Classify an inbound message",
+  input: z.object({ message: z.string(), sender: z.string() }),
+  output: z.object({ priority: z.enum(["low", "normal", "high", "urgent"]) }),
+  run: async (input) => ({ priority: "normal" }),
+});
+```
+
+## Catalog integration actions
+
+Official integrations ship as npm packages with pre-built actions. Discover with `keystroke app search`, connect with `keystroke connect <slug>`, then import in workflows or agent tools — not in `src/actions/`:
+
+```ts
+import { exaSearch } from "@keystrokehq/exa/actions";
+import { slackSendMessage } from "@keystrokehq/slack/actions";
+```
+
+Detail: [catalog-and-imports.md](references/catalog-and-imports.md).
+
+## Call an agent from an action (allowed)
+
+Agents — not other actions — are the one thing an action may invoke:
+
+```ts
+import signupResearcher from "../agents/signup-researcher";
+
+export const researchSignup = defineAction({
+  slug: "research-signup",
+  run: async (input) => {
+    const result = await signupResearcher.prompt({ message: "…" });
+    return { brief: "…" };
+  },
+});
+```
+
+## Credential scope & resolution
+
+When a credential's scope isn't pinned, the runtime resolves it **project default first, then org default**. Pin a scope per-use with `.scope()` (the authoring-side counterpart to the CLI `--scope` flag) — it returns a fresh action that still binds like any other step/tool:
+
+```ts
+await myAction.scope("user").run(input);   // workflow step
+tools: [myAction.scope("user")];            // agent tool
+```
+
+When several instances exist for one app + scope and none is the default, pin an exact instance to the consuming step/tool from the CLI: `keystroke credentials assignments assign --workflow <slug> --credential <app>/<slug> --consumer step:<slug>#0` (see [apps skill](.agents/skills/keystroke-apps/SKILL.md)).
+
+## Long-running actions: honor the abort signal
+
+`run` receives a third `ctx` argument with an `AbortSignal`. Thread it into fetches/SDK calls so the framework can cancel work cleanly:
+
+```ts
+async run(input, credentials, ctx) {
+  const res = await fetch(url, { signal: ctx?.signal });
+  return res.json();
+}
+```
+
+## Where actions run
+
+| Consumer | Usage                                           |
+| -------- | ----------------------------------------------- |
+| Workflow | `await myAction.run(input)` in `defineWorkflow` |
+| Agent    | `tools: [myAction, exaSearch]` on `defineAgent` |
+
+## Next references
+
+- [catalog-and-imports.md](references/catalog-and-imports.md) — catalog discovery, npm imports
+
+Related: [apps](.agents/skills/keystroke-apps/SKILL.md), [workflows](.agents/skills/keystroke-workflows/SKILL.md), [agents](.agents/skills/keystroke-agents/SKILL.md).