@keystrokehq/cli 0.1.15 → 0.1.16

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

@@ -1,12 +1,12 @@
 # keystroke (MCP)
 
-Keystroke is an AI automation server for agents and workflows.
+Keystroke is a code-first AI automation platform — build specialized AI agents and workflow automations as real TypeScript, then deploy them to a managed cloud where they run. Everything is actual code (not brittle JSON), so agents can build, test, and maintain it. There are 1,000+ built-in integrations (Slack, Google, Linear, …), and you can build a connection for any HTTP API (including private internal APIs) or MCP server.
 
 You are editing a **keystroke project** in a remote workspace via MCP. Author under `src/`, import from `@keystrokehq/*` npm packages. You do not have framework source — only this project and published deps.
 
 Use MCP tools to work on the project: `read_file`, `write_file`, `edit_file`, `list_files`, `delete_file`, `exec_command`, and `deploy_project`. Load authoring guidance with `search_skills` and `get_skill` (see skills map below). The workspace root also has `AGENTS.md` and `.agents/skills/` with the same skill content, readable via `read_file`.
 
-The **keystroke platform** is the hosted control plane. After you change code, run `deploy_project` to build and upload; that activates the cloud runtime.
+The **keystroke platform** is the hosted control plane. After you change code, run `deploy_project` to build and upload; that activates the cloud runtime. 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), so use filtered deploys and `@keystroke ignore` to iterate quickly.
 
 ## What you build
 
@@ -26,6 +26,10 @@ Draft or in-progress modules, full vs filtered deploy, and `@keystroke ignore`:
 
 **Actions are leaf units.** An action never calls another action (including integration actions like `postMessage`). Compose actions in a workflow, or attach an integration action directly as a workflow step / agent tool. An action may call an agent.
 
+**Workflow steps.** Workflows orchestrate actions, agent prompts, and LLM calls (`promptLlm`) as steps. There's no first-class "call another workflow" step — share logic by extracting it into `src/lib/` or an action, or expose a workflow as an agent tool (`defineWorkflowTool`) / over HTTP when you want it as its own tracked run.
+
+**Agent tools.** Agents can use actions, subagents (`defineSubagentTool`), workflows (`defineWorkflowTool`), and MCP tools as tools.
+
 ## Working habits
 
 A few things that are easy to skip and cause common failures:
@@ -46,7 +50,10 @@ keystroke workflow run <workflow-key> --input '{}'
 keystroke workflow runs list <workflow-key>
 keystroke workflow runs get <workflow-key> <run-id> --include steps,trace
 keystroke agent sessions list <agent-key>
+keystroke agent sessions get <agent-key> <session-id> --include messages,trace
 keystroke trigger list
+keystroke trigger url <trigger-key>
+keystroke trigger runs list <trigger-key>:<workflow-key>
 keystroke app list
 ```
 
@@ -64,7 +71,7 @@ Call `search_skills` then `get_skill` with the key below.
 | `keystroke-workflows` | Orchestration, action steps        |
 | `keystroke-actions`   | Shared steps, integration tools    |
 | `keystroke-triggers`  | Cron, webhook, poll automation     |
-| `keystroke-gateways`  | Slack / messaging bindings         |
+| `keystroke-channels`  | Slack / external channel bindings  |
 | `keystroke-skills`    | `src/skills/` playbooks            |
 | `keystroke-files`     | Agent workspace files              |
 | `keystroke-apps`      | Connectable apps, catalog, connect |

package/dist/skills-bundle/_AGENTS.md

@@ -1,121 +1,112 @@
 # keystroke
 
-Keystroke is an AI automation server for agents and workflows.
+This codebase is a Keystroke project.
 
-You are in a **keystroke project**. Author under `src/`, import from `@keystrokehq/*` npm packages. You do not have framework source — only your project and published deps.
+> Keystroke is a code-first AI automation platform, an n8n alternative built for agents. With it, anyone can build specialized AI agents and workflow automations as real TypeScript, then deploy them to a managed cloud platform where they run. Unlike tools like Zapier and n8n that hide logic behind brittle JSON, everything in Keystroke is actual code that coding agents (Cursor, Claude Code, Codex, etc.) can build, test, and maintain.
 
-A **keystroke server** runs this project (`keystroke start` / `keystroke dev`). The **keystroke platform** is the hosted control plane that manages many keystroke servers after deploy.
+- **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). You can also 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 inspect runs, manage credentials, and collaborate from a shared web platform.
 
-## Local vs cloud (CLI)
+## Keystroke projects
 
-The CLI routes runtime commands to one of two API targets:
+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 into, and inspect run history for.
 
-| Target                                        | Use for                                                                                            |
-| --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| **Local** (default `:3002`)      | **Development and testing** — iterate on `src/`, run workflows/agents on your machine              |
-| **Cloud** (`platformUrl` + `activeProjectId`) | **Invoking and listing deployed resources** — production runs, triggers, remote audit after deploy |
+Keystroke projects use two related ideas:
 
-```bash
-keystroke dev                   # local; other commands auto-target local while this runs
-keystroke config use local      # switch to local (cloud project id is preserved)
-keystroke config use cloud      # switch back to deployed project
-keystroke config use project <id>   # swap active cloud project
-keystroke --project <id> workflow run foo --input '{}'   # one-off cloud target
-keystroke config show           # inspect activeProjectId, apiTarget, dev session
-keystroke project list          # platform deploy targets in the active org
-keystroke project create --name "My app"   # new target (inactive until deploy)
-keystroke deploy --project <id> # build + upload; activates cloud runtime
-```
+- **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.
 
-`keystroke auth login` once — token is shared; switching targets does not require re-auth.
+`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 users can manage their projects, deployments, logs, credentials, etc.
 
-**Platform project** = cloud deploy target (managed by the control plane). **Local project** = this repo (`src/`, `keystroke.config.ts`). You need a platform project id before `keystroke deploy`.
+## How this codebase fits in
 
-Full routing rules: [cli skill](.agents/skills/keystroke-cli/SKILL.md) → [api-targets.md](.agents/skills/keystroke-cli/references/api-targets.md).
+This is the local codebase that defines your agents, workflows, triggers, actions, skills, and files.
 
-## Run locally (fastest path)
+Projects are scaffolded with an opinionated folder structure (like Next.js for building AI systems):
 
-```bash
-# .env is created from .env.example on init — set ANTHROPIC_API_KEY + integration keys
-keystroke start               # API :3002, dashboard :3000
-keystroke health
-keystroke agent prompt hello --message "Hi"
+```
+my-app/
+  keystroke.config.ts      # project configuration
+  src/
+    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
+  .agents/skills/          # Keystroke skills and best practices
 ```
 
-New project: `keystroke init my-app --yes`, then the steps above.
+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.
 
-## CLI auth
+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.
 
-```bash
-keystroke auth login
-```
+## How you work
 
-Required for cloud/platform commands and some trigger operations. Not required for typical local dev without auth enabled.
+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.
 
-## What you build
+```bash
+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"}'   # run on your project
+keystroke agent prompt hello --message "Hi"
+```
 
-| Piece          | Where                                  | Import from                                                                 |
-| -------------- | -------------------------------------- | --------------------------------------------------------------------------- |
-| Actions        | `src/actions/`                         | `@keystrokehq/keystroke/action`                                             |
-| Agents         | `src/agents/`                          | `@keystrokehq/keystroke/agent`                                              |
-| Workflows      | `src/workflows/`                       | `@keystrokehq/keystroke/workflow`                                           |
-| Triggers       | `src/triggers/`                        | `@keystrokehq/keystroke/trigger`                                            |
-| Apps           | `src/apps/`                            | `@keystrokehq/keystroke/app`, `keystroke app`, `keystroke connect`          |
-| Integrations   | npm packages + catalog                 | `@keystrokehq/exa`, `@keystrokehq/slack`, … — discover with `keystroke app search` |
-| Skills / files | `src/skills/`, `src/files/`            | attached on `defineAgent`                                                   |
+After a deploy, runtime commands (`workflow`, `agent`, `trigger`, `app`, `connect`) operate on that project automatically — no target to manage.
 
-Default-export each module — the server discovers files under `src/`.
+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 keep iterate quickly.
 
-Draft or in-progress modules, full vs filtered deploy, and `@keystroke ignore`: [deploy skill](.agents/skills/keystroke-deploy/SKILL.md).
+To create a new project: `keystroke init my-app --yes`, then deploy.
 
-**Actions are leaf units.** An action never calls another action (including integration actions like `postMessage`). Compose actions in a workflow, or attach an integration action directly as a workflow step / agent tool. An action may call an agent.
+Full deploy mechanics: [cli skill](.agents/skills/keystroke-cli/SKILL.md), [deploy skill](.agents/skills/keystroke-deploy/SKILL.md).
 
 ## Working habits
 
 A few things that are easy to skip and cause common failures:
 
 - **Research real APIs before mirroring them** — web search and fetch the actual reference & explore relevant docs; don't guess endpoints or payload shapes.
-- **Run before you depend or deploy** — run the workflow/agent locally and read the real output (`keystroke workflow runs get <key> <run-id> --include steps,trace`) before wiring dependent steps.
+- **Run before you depend on it** — run the workflow/agent and read the real output (`keystroke workflow runs get <workflow-slug> <run-id> --include steps,trace`) before wiring dependent steps or claiming you are finished building something.
 - **Cover obvious edge cases** and write simple tests as needed (null field, empty array, a step that throws) — see [workflows skill](.agents/skills/keystroke-workflows/SKILL.md).
-- **Connected apps aren't in `.env`** — `keystroke deploy` never uploads `.env`; connect apps on the cloud target with `keystroke connect <slug>`. See [apps skill](.agents/skills/keystroke-apps/SKILL.md).
-- **Shipping to prod** — full vs filtered deploy, WIP ignore directives: [deploy skill](.agents/skills/keystroke-deploy/SKILL.md).
+- **Connected apps aren't in `.env`** — `keystroke deploy` never uploads `.env`; connect apps (aka, integrations) for your project with `keystroke connect <slug>`. See [apps skill](.agents/skills/keystroke-apps/SKILL.md).
+- **Shipping to prod** — determine if you should do a full vs filtered deploy, or use WIP ignore directives: [deploy skill](.agents/skills/keystroke-deploy/SKILL.md).
+- **Actions are leaf units** - An action never calls another action (including integration actions like `slackSendMessage`). Compose actions in a workflow, or attach an integration action directly as a workflow step / agent tool. An action may call an agent.
+- **Workflow steps** - Workflows orchestrate actions, agent prompts, and LLM calls (`promptLlm`) as steps. There's no first-class "call another workflow" step — share logic by extracting it into `src/lib/` or an action, or expose a workflow as an agent tool (`defineWorkflowTool`) / over HTTP when you want it as its own tracked run.
+- **Agent tools** - Agents can use actions, subagents (`defineSubagentTool`), workflows (`defineWorkflowTool`), and MCP tools as tools.
 
 ## Audit & debug (CLI)
 
-Use the CLI against the correct target — do not call HTTP directly.
-
-**Local** (developing / testing):
+Use the CLI to inspect your deployed project.
 
 ```bash
-keystroke agent sessions list <agent-key>
-keystroke agent sessions get <agent-key> <session-id> --include messages,trace
-keystroke workflow run <workflow-key> --input '{}'
-keystroke workflow runs list <workflow-key>
-keystroke workflow runs get <workflow-key> <run-id> --include steps,trace
+keystroke workflow run <workflow-slug> --input '{}'
+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 app list
-```
-
-**Cloud** (deployed — `keystroke config use cloud` or after deploy):
-
-```bash
 keystroke trigger list
-keystroke trigger url <trigger-key>
-keystroke trigger runs list <trigger-key>:<workflow-key>
+keystroke trigger url <trigger-slug>
+keystroke trigger runs list <trigger-slug>:<workflow-slug>
 ```
 
-Read `src/` first — existing agents, workflows, actions, and triggers are your best map of how this project works.
+Read `src/` first; existing agents, workflows, actions, and triggers are your best map of how this project works.
+
+## Skills
 
-## Skills map
+Whenever you work with your Keystroke project, you should review relevant skills. Skills can be found in `.agents/skills/` and are folders named with the following format: `keystroke-[name]`.
 
 | Skill                                                        | Load when                          |
 | ------------------------------------------------------------ | ---------------------------------- |
-| [cli](.agents/skills/keystroke-cli/SKILL.md)                 | Local vs cloud CLI, config, projects |
+| [cli](.agents/skills/keystroke-cli/SKILL.md)                 | Deploy, run, inspect; projects & auth |
 | [deploy](.agents/skills/keystroke-deploy/SKILL.md)           | Build, full/filtered deploy, WIP ignore |
 | [agents](.agents/skills/keystroke-agents/SKILL.md)           | Building or debugging agents       |
 | [workflows](.agents/skills/keystroke-workflows/SKILL.md)     | Orchestration, action steps        |
 | [actions](.agents/skills/keystroke-actions/SKILL.md)         | Shared steps, integration tools    |
 | [triggers](.agents/skills/keystroke-triggers/SKILL.md)       | Cron, webhook, poll automation     |
-| [gateways](.agents/skills/keystroke-gateways/SKILL.md)       | Slack / messaging bindings         |
+| [channels](.agents/skills/keystroke-channels/SKILL.md)       | Slack / external channel bindings  |
 | [skills](.agents/skills/keystroke-skills/SKILL.md)           | `src/skills/` playbooks            |
 | [files](.agents/skills/keystroke-files/SKILL.md)             | Agent workspace files              |
 | [apps](.agents/skills/keystroke-apps/SKILL.md)               | Connectable apps, catalog, connect |

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

@@ -1,6 +1,6 @@
 ---
 name: keystroke-actions
-description: Define keystroke actions — workflow steps and agent tools. App-backed actions flow through synced apps (app.action); catalog integrations import from npm packages. Use when authoring src/actions/ or wiring integrations.
+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
 ---
@@ -9,28 +9,54 @@ metadata:
 
 One **executable unit** used everywhere: workflow steps, agent tools, and codemode host calls.
 
-Anything that calls an external API **flows through an app** — sync the app into `src/apps/` first, connect it, then author with `app.action()`. See [apps skill](.agents/skills/keystroke-apps/SKILL.md).
+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 `postMessage`). Composition belongs in a **workflow**; an integration action is used directly as a workflow step or agent tool — not wrapped in a custom 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 { postMessage } from "@keystrokehq/slack/actions";
+import { slackSendMessage } from "@keystrokehq/slack/actions";
 export const notify = defineAction({ slug: "notify",
-  run: async (input) => postMessage.run({ channel: input.channel, text: input.text }),
+  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 postMessage.run({ channel: input.channel, text: buildText(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.
 
-## App-backed actions (custom integrations)
+## 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))
@@ -51,14 +77,14 @@ export const kwatchListAlerts = kwatch.action({
 });
 ```
 
-Do not use bare `defineAction` for external API work — the app owns the connection.
+Use an app wrapper (over a standalone credential) when a family of actions should share one connection definition.
 
-## Pure actions (no app)
+## Pure actions (no credential)
 
-Use `defineAction` directly only when the step needs no app connection (pure logic, local transforms):
+Use `defineAction` with no `credentials` when the step needs no connection at all (pure logic, local transforms):
 
 ```ts
-import { defineAction } from "@keystrokehq/action";
+import { defineAction } from "@keystrokehq/keystroke/action";
 import { z } from "zod";
 
 export const triage = defineAction({
@@ -77,7 +103,7 @@ Official integrations ship as npm packages with pre-built actions. Discover with
 
 ```ts
 import { exaSearch } from "@keystrokehq/exa/actions";
-import { postMessage } from "@keystrokehq/slack/actions";
+import { slackSendMessage } from "@keystrokehq/slack/actions";
 ```
 
 Detail: [catalog-and-imports.md](references/catalog-and-imports.md).
@@ -98,6 +124,28 @@ export const researchSignup = defineAction({
 });
 ```
 
+## 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                                           |

package/dist/skills-bundle/skills/keystroke-actions/references/catalog-and-imports.md

@@ -9,15 +9,44 @@
 
 ```ts
 import { exaSearch, exaAnswer } from "@keystrokehq/exa/actions";
-import { postMessage } from "@keystrokehq/slack/actions";
+import { slackSendMessage } from "@keystrokehq/slack/actions";
 import { googlesuperSendEmail } from "@keystrokehq/googlesuper/actions";
 ```
 
 Catalog packages ship a pre-built app + actions — you do not author `src/apps/` for these.
 
-## Custom integrations (app-first)
+## Custom integrations
 
-All custom API work flows through a synced app:
+Two supported paths. Pick based on whether actions share a connection.
+
+### Standalone credential (simplest)
+
+Declare a `defineCredential` and consume it from a plain `defineAction`:
+
+```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 fetchStatus = defineAction({
+  slug: "fetch-status",
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+  credentials: [acme] as const,
+  async run(_input, credentials) {
+    const { apiKey } = credentials.acme;
+    return { ok: true };
+  },
+});
+```
+
+Connect it with `keystroke credentials set acme --set apiKey=@env:ACME_API_KEY --scope org`.
+
+### App wrapper (shared connection / synced apps)
+
+Use an app when several actions share one connection, or when you've synced a custom/catalog app:
 
 1. Create the app (dashboard or `keystroke app create --name ... --field ...`)
 2. Sync: `keystroke app sync <slug>` → `src/apps/<name>/app.ts`

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

@@ -14,7 +14,7 @@ Agents are **autonomous LLM runs** with a sandbox, optional skills/files, and **
 **Integration tools** — import actions from an integration package:
 
 ```ts
-import { defineAgent } from "@keystrokehq/agent";
+import { defineAgent } from "@keystrokehq/keystroke/agent";
 import { exaSearch, exaAnswer } from "@keystrokehq/exa/actions";
 
 export default defineAgent({
@@ -28,7 +28,8 @@ export default defineAgent({
 **Skills + files** — static playbooks and docs in the workspace:
 
 ```ts
-import { defineSandbox } from "@keystrokehq/sandbox";
+import { defineAgent } from "@keystrokehq/keystroke/agent";
+import { defineSandbox } from "@keystrokehq/keystroke/sandbox";
 
 defineAgent({
   slug: "support",
@@ -40,6 +41,46 @@ defineAgent({
 
 Import actions from `@keystrokehq/<integration>/actions` (e.g. `@keystrokehq/exa/actions`, `@keystrokehq/googlesuper/actions`).
 
+## Built-in capabilities (on by default)
+
+Two capabilities are enabled automatically — you don't add them to `tools`:
+
+- **Memory** — agents persist memory across sessions by default. Disable with `memory: false`.
+- **Web** — built-in `web_search` / `web_fetch` host tools are available by default. Disable with `web: false`.
+
+```ts
+defineAgent({
+  slug: "researcher",
+  systemPrompt: "…",
+  model: "anthropic/claude-sonnet-4-6",
+  memory: false, // opt out of persistent memory
+  web: false,    // opt out of built-in web tools
+});
+```
+
+Delegate to other agents with subagents (`defineSubagentTool`) — see [tools-mcp-codemode.md](references/tools-mcp-codemode.md).
+
+## Structured output (`outputSchema`)
+
+`outputSchema` is a **per-prompt** option, not a `defineAgent` field — the same agent can return free text on one call and a schema-validated object on the next. Pass a Zod schema to `prompt(...)` and read the parsed result from `result.output` (typed from the schema):
+
+```ts
+import { z } from "zod";
+import researcher from "../agents/signup-researcher";
+
+const Summary = z.object({ company: z.string(), summary: z.string() });
+
+const result = await researcher.prompt({
+  message: "Research Acme Corp",
+  outputSchema: Summary,
+});
+if (result.error) throw new Error(result.error);
+
+const { company, summary } = result.output!; // typed { company: string; summary: string }
+```
+
+Without `outputSchema`, `result.output` is `undefined` and you read the reply from `result.messages`. This is an in-process TypeScript API (workflows, actions, scripts) — structured output is **not** exposed over the HTTP route or `keystroke agent prompt`.
+
 ## Run & audit
 
 ```bash
@@ -54,19 +95,20 @@ Follow up in the same session: `--session-id <id>`.
 
 | From            | How                                                       |
 | --------------- | --------------------------------------------------------- |
-| CLI             | `keystroke agent prompt {key} --message "…"`              |
+| CLI             | `keystroke agent prompt {slug} --message "…"`             |
 | Workflow action | `await myAgent.prompt({ message })` inside `defineAction` |
-| Gateway         | Slack message to a bound agent (see gateways skill)       |
+| Channel         | Slack message to a bound agent (see channels skill)      |
+
+The agent's identity field is `slug` — it's also the route id (`POST /agents/{slug}`) and the CLI `<agentId>` argument.
 
 ## Workspace
 
-- Skills → `/workspace/agent/skills/{key}/`
-- Files from `src/files/{key}/` → `/workspace/agent/`
-- Pass `module: import.meta.url` so skills/files resolve in dev without a rebuild
+- Skills → `/workspace/agent/skills/{skill-name}/` (the skill's folder name)
+- Files from `src/files/{slug}/` → `/workspace/agent/` (`{slug}` is the agent slug when `files: true`)
 
 ## Next references
 
-- [models.md](references/models.md) — model ids, `.env` keys
+- [models.md](references/models.md) — model ids, platform LLM proxy
 - [tools-mcp-codemode.md](references/tools-mcp-codemode.md) — actions as tools, MCP, codemode
 - [workflows-and-testing.md](references/workflows-and-testing.md) — sessions, workflow handoff
 

package/dist/skills-bundle/skills/keystroke-agents/references/models.md

@@ -5,21 +5,19 @@ model: "google/gemini-2.5-flash"; // vendor/model-id — any pi-ai or gateway ca
 thinkingLevel: "high"; // optional — defaults to "medium"; use "none" to disable reasoning
 ```
 
-Per-prompt override via API: `{ "message": "...", "thinkingLevel": "low" }`.
-
-**Local dev (direct)** — set the provider key for each vendor you use (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, …). Only models in the pi-ai direct registry resolve without gateway.
+`thinkingLevel` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` (`off` disables reasoning).
 
-**Optional gateway** — set `AI_GATEWAY_API_KEY` to route all agents through Vercel AI Gateway with the same model string. Unlocks gateway-only ids (e.g. `moonshotai/kimi-k2`, `deepseek/deepseek-v3`, `zai/glm-4.5`).
+Per-prompt override via API: `{ "message": "...", "thinkingLevel": "low" }`.
 
-**Cloud** — hosted workers use the platform LLM proxy automatically; no provider keys in the container.
+Set `model` to any `vendor/model-id` and deploy — the platform routes agents through its managed LLM proxy automatically, so there are **no provider keys to configure**.
 
-| Vendor    | Example id                    | Direct key          |
-| --------- | ----------------------------- | ------------------- |
-| Anthropic | `anthropic/claude-sonnet-4.5` | `ANTHROPIC_API_KEY` |
-| OpenAI    | `openai/gpt-5.5`              | gateway only        |
-| Google    | `google/gemini-3.5-flash`     | gateway only        |
-| DeepSeek  | `deepseek/deepseek-v3`        | gateway only        |
-| Moonshot  | `moonshotai/kimi-k2.5`        | gateway only        |
-| Zhipu GLM | `zai/glm-4.5`                 | gateway only        |
+| Vendor    | Example id                    |
+| --------- | ----------------------------- |
+| Anthropic | `anthropic/claude-sonnet-4.5` |
+| OpenAI    | `openai/gpt-5.5`              |
+| Google    | `google/gemini-3.5-flash`     |
+| DeepSeek  | `deepseek/deepseek-v3`        |
+| Moonshot  | `moonshotai/kimi-k2.5`        |
+| Zhipu GLM | `zai/glm-4.5`                 |
 
 After changing model, smoke-test: `keystroke agent prompt <key> --message "Hi"`.

package/dist/skills-bundle/skills/keystroke-agents/references/tools-mcp-codemode.md

@@ -8,7 +8,7 @@ Most agents use imported integration actions:
 import { exaSearch, exaAnswer } from "@keystrokehq/exa/actions";
 import { googlesuperFetchEmails, googlesuperSendEmail } from "@keystrokehq/googlesuper/actions";
 
-tools: [exaSearch, exaAnswer, listEmails, sendEmail],
+tools: [exaSearch, exaAnswer, googlesuperFetchEmails, googlesuperSendEmail],
 ```
 
 See each integration package's `actions` export for available tools.
@@ -22,10 +22,52 @@ tools: [triage],
 
 Same action works in workflows and on agents.
 
+## Subagents (delegate to another agent)
+
+Wrap any agent as a tool with `defineSubagentTool` (from `@keystrokehq/keystroke/agent`) and add it to `tools`. The parent delegates a scoped task to the child agent:
+
+```ts
+import { defineAgent, defineSubagentTool } from "@keystrokehq/keystroke/agent";
+import { z } from "zod";
+import researcher from "./researcher";
+
+export default defineAgent({
+  slug: "planner",
+  systemPrompt: "Plan work. Delegate research to the researcher subagent.",
+  model: "anthropic/claude-sonnet-4-6",
+  tools: [
+    defineSubagentTool({
+      agent: researcher,
+      name: "research",
+      label: "Research a topic",
+      parameters: z.object({ message: z.string() }), // default toMessage reads params.message
+    }),
+  ],
+});
+```
+
 ## MCP
 
-Import MCP definitions from the integration package (e.g. `exaSearchMcp` from `@keystrokehq/exa/mcp`) and add them to `tools` alongside actions.
+Point an agent at an MCP server with `defineMcp` (from `@keystrokehq/keystroke/agent`) and add the definition to `tools` alongside actions. Each tool the server lists becomes available, prefixed with the server `key` (e.g. `mcp__deepwiki__ask_question`).
+
+```ts
+import { defineAgent, defineMcp } from "@keystrokehq/keystroke/agent";
+
+const deepwiki = defineMcp({
+  key: "deepwiki",
+  transport: { type: "http", url: "https://mcp.deepwiki.com/mcp" },
+});
+
+export default defineAgent({
+  slug: "researcher",
+  systemPrompt: "Use the DeepWiki tools to answer questions about repos.",
+  model: "anthropic/claude-sonnet-4-6",
+  tools: [deepwiki],
+});
+```
+
+For servers that require auth, declare credentials on the definition.
 
 ## Codemode (advanced)
 
-Default sandbox has bash. For batch tool calls, agents can run js-exec scripts that call `await tools['action-key'](args)`. Optional VM runtime via `defineAgent({ mode: 'vm' })`.
+Default sandbox has bash. For batch tool calls, agents can run js-exec scripts that call `await tools['action-slug'](args)` (the tool name is the action's slug; MCP tools keep their `mcp__<key>__<tool>` prefix). Optional VM runtime via `sandbox: defineSandbox({ mode: "vm" })` (from `@keystrokehq/keystroke/sandbox`).

package/dist/skills-bundle/skills/keystroke-agents/references/workflows-and-testing.md

@@ -14,7 +14,7 @@ keystroke agent prompt support --message "Summarize that" --session-id <id>
 keystroke agent sessions get support <session-id> --include messages,trace
 ```
 
-Use this when an agent misbehaves or a gateway reply looks wrong.
+Use this when an agent misbehaves or a channel reply looks wrong.
 
 ## Agent called from a workflow