@keystrokehq/cli 0.1.38 → 0.2.0

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

@@ -0,0 +1,71 @@
+# Integration actions
+
+## Official catalog integrations
+
+1. Discover: `keystroke app search <query>` → `app show <slug>` → `app actions <slug>`
+2. Connect: `keystroke connect <slug>`
+3. Add npm package (e.g. `@keystrokehq/exa`, `@keystrokehq/googlesuper`, `@keystrokehq/slack`)
+4. Import in `src/workflows/` or on `defineAgent` `tools` — not in `src/actions/`:
+
+```ts
+import { exaSearch, exaAnswer } from "@keystrokehq/exa/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
+
+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`
+3. Connect: `keystroke connect <slug>`
+4. Author actions in `src/actions/` with `app.action()`:
+
+```ts
+import { z } from "zod";
+import { internalApi } from "../apps/internal-api/app";
+
+export const fetchStatus = internalApi.action({
+  slug: "fetch-status",
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+  async run(_input, credentials) {
+    const { apiKey } = credentials["acme/internal-api"];
+    return { ok: true };
+  },
+});
+```
+
+Re-run `keystroke app sync <slug>` after template changes on the platform. Full app lifecycle: [apps skill](../../keystroke-apps/SKILL.md).

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

@@ -0,0 +1,115 @@
+---
+name: keystroke-agents
+description: Build keystroke agents with defineAgent — models, integration tools (Exa, Google, Slack), skills, files, and sandbox. Use when authoring src/agents/ or debugging agent sessions.
+metadata:
+  keystroke-domain: agents
+---
+
+# Agents
+
+Agents are **autonomous LLM runs** with a sandbox, optional skills/files, and **tools** (your actions + integration actions).
+
+## Typical patterns
+
+**Integration tools** — import actions from an integration package:
+
+```ts
+import { defineAgent } from "@keystrokehq/keystroke/agent";
+import { exaSearch, exaAnswer } from "@keystrokehq/exa/actions";
+
+export default defineAgent({
+  slug: "signup-researcher",
+  systemPrompt: "Research signups with Exa. Stay concise; cite sources.",
+  model: "anthropic/claude-sonnet-4.6",
+  tools: [exaSearch, exaAnswer],
+});
+```
+
+**Skills + files** — static playbooks and docs in the workspace:
+
+```ts
+import { defineAgent } from "@keystrokehq/keystroke/agent";
+import { defineSandbox } from "@keystrokehq/keystroke/sandbox";
+
+defineAgent({
+  slug: "support",
+  systemPrompt: "Read /workspace/agent/product-guide.md before answering.",
+  skills: ["support"],
+  sandbox: defineSandbox({ files: true }),
+});
+```
+
+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
+keystroke agent prompt signup-researcher --message "Research Acme Corp"
+keystroke agent sessions list signup-researcher
+keystroke agent sessions get signup-researcher <session-id> --include messages,trace
+```
+
+Follow up in the same session: `--session-id <id>`.
+
+## How agents get invoked
+
+| From            | How                                                       |
+| --------------- | --------------------------------------------------------- |
+| CLI             | `keystroke agent prompt {slug} --message "…"`             |
+| Workflow action | `await myAgent.prompt({ message })` inside `defineAction` |
+| 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/{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, 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
+
+Related: [actions](.agents/skills/keystroke-actions/SKILL.md), [workflows](.agents/skills/keystroke-workflows/SKILL.md), [files](.agents/skills/keystroke-files/SKILL.md), [apps](.agents/skills/keystroke-apps/SKILL.md).

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

@@ -0,0 +1,23 @@
+# Models
+
+```ts
+model: "google/gemini-2.5-flash"; // vendor/model-id — any pi-ai or gateway catalog id
+thinkingLevel: "high"; // optional — defaults to "medium"; use "none" to disable reasoning
+```
+
+`thinkingLevel` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh` (`off` disables reasoning).
+
+Per-prompt override via API: `{ "message": "...", "thinkingLevel": "low" }`.
+
+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                    |
+| --------- | ----------------------------- |
+| 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

@@ -0,0 +1,73 @@
+# Tools, MCP, and codemode
+
+## Integration actions as tools
+
+Most agents use imported integration actions:
+
+```ts
+import { exaSearch, exaAnswer } from "@keystrokehq/exa/actions";
+import { googlesuperFetchEmails, googlesuperSendEmail } from "@keystrokehq/googlesuper/actions";
+
+tools: [exaSearch, exaAnswer, googlesuperFetchEmails, googlesuperSendEmail],
+```
+
+See each integration package's `actions` export for available tools.
+
+## Your own actions as tools
+
+```ts
+import { triage } from "../actions/triage";
+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
+
+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-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

@@ -0,0 +1,26 @@
+# Sessions and workflow handoff
+
+## Multi-turn CLI
+
+```bash
+keystroke agent prompt support --message "What is the refund policy?"
+keystroke agent sessions list support
+keystroke agent prompt support --message "Summarize that" --session-id <id>
+```
+
+## Inspect a session
+
+```bash
+keystroke agent sessions get support <session-id> --include messages,trace
+```
+
+Use this when an agent misbehaves or a channel reply looks wrong.
+
+## Agent called from a workflow
+
+Actions invoke agents with `.prompt()` inside `defineAction`. Audit the workflow run, not just the agent session:
+
+```bash
+keystroke workflow runs list signup-pipeline
+keystroke workflow runs get signup-pipeline <run-id> --include steps,trace
+```

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

@@ -0,0 +1,151 @@
+---
+name: keystroke-apps
+description: Connectable apps — defineApp, app.action, catalog discovery via keystroke app search, custom app create/sync, and connect. Use when wiring integrations, OAuth, API keys, or a deployed run fails because an app is not connected.
+metadata:
+  keystroke-domain: apps
+---
+
+# Apps
+
+An **app** is a connectable integration: a slug, an auth kind, and (for custom apps) a field template. **Connected** = secrets for that app have been uploaded via the connect flow.
+
+Secrets never live in source or `.env`. `keystroke deploy` uploads code only, not connections — connect the apps your project needs with the connect flow.
+
+Custom actions that call external APIs need a **credential**. The simplest path is a standalone `defineCredential` declared on a `defineAction`. Reach for an **app** (`defineApp` + `app.action()`) when several actions share one connection, or when you've synced a catalog/custom app into `src/apps/`. See [actions skill](.agents/skills/keystroke-actions/SKILL.md).
+
+## Two sources of apps
+
+| Source | How you get it | Author in code |
+| ------ | -------------- | -------------- |
+| **Catalog** | ~1000 Composio integrations + first-party (`exa`, `slack`, `googlesuper`) | npm package `@keystrokehq/<slug>` — discover via CLI |
+| **Custom** | Dashboard UI or `keystroke app create`, then `keystroke app sync <slug>` | `src/apps/<name>/app.ts` from sync |
+
+## Discover catalog integrations
+
+```bash
+keystroke auth login
+keystroke app search github              # live Composio catalog
+keystroke app show github
+keystroke app actions github --search issue
+keystroke app action GITHUB_CREATE_ISSUE
+keystroke app list                       # apps registered in your org
+```
+
+Discovery is read-only — there is no `app install` yet. To connect an app, its slug must be in your org registry (`app list`).
+
+## Create and sync custom apps
+
+Create in the dashboard or CLI, then pull the template into your project:
+
+```bash
+# Manual custom app (api_key fields)
+keystroke app create \
+  --name "Internal API" \
+  --description "Our internal service" \
+  --field apiKey:secret
+
+# Auto-detect from URL (same as dashboard Create custom app)
+keystroke app create --mcp https://mcp.example.com/mcp --preview
+keystroke app create --openapi https://example.com/openapi.yaml --name "Example API"
+
+keystroke app sync acme/internal-api     # writes src/apps/internal-api/app.ts
+```
+
+Re-run `sync` after template changes on the platform. Then author actions with `app.action()` in `src/actions/`.
+
+## Author with defineApp
+
+Synced apps land as `defineApp` in `src/apps/<name>/app.ts`:
+
+```ts
+import { defineApp } from "@keystrokehq/keystroke/app";
+import { z } from "zod";
+
+export const kwatch = defineApp({
+  slug: "keystroke/kwatch",
+  auth: "api_key",
+  credential: { apiKey: z.string() },
+});
+```
+
+Actions use `app.action()` — the app binding is automatic:
+
+```ts
+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 };
+  },
+});
+```
+
+Auth kinds: `keystroke` (MCP/Composio catalog apps), `api_key` (custom fields), `oauth` (token resolved at runtime). In `run`, read connected fields as `credentials[app.slug]`.
+
+## Connect an app
+
+`keystroke connect <slug>` opens the web app connect flow (OAuth or API-key form, depending on the app). This is how secrets get attached to an app — not via `.env`.
+
+**Official integrations** — the cleanest path:
+
+```bash
+keystroke connect google
+keystroke connect slack
+keystroke connect exa
+```
+
+**Custom apps** — sync the template first, then connect:
+
+```bash
+keystroke app sync acme/internal-api
+keystroke connect acme/internal-api
+```
+
+The web app **Apps** page offers the same flow.
+
+Field names in the connect form match the app's synced template. You pick the scope (project / org / user) in the web connect flow — `keystroke connect` has no `--scope` flag. See [cli-and-catalog.md](references/cli-and-catalog.md).
+
+## Connect what your project needs
+
+A new project starts with **no connected apps**. After deploy, connect the apps it uses:
+
+```bash
+keystroke deploy --project <id>
+keystroke connect google
+keystroke connect exa
+keystroke app list
+```
+
+A runtime error about a missing connection almost always means the app hasn't been connected for this project.
+
+## Manage & bind credentials
+
+`keystroke credentials list / get / update --default / rotate-key / delete` manage instances. When several instances share a scope and none is the default, a run can't auto-resolve — set a default, or **bind** an exact instance to one step/tool:
+
+```bash
+keystroke credentials consumers list --workflow sync                                   # step:<slug>#<n>
+keystroke credentials assignments assign --workflow sync --credential org/work --consumer step:fetch-gmail#0
+keystroke credentials assignments assign --agent support --credential vault-prod --consumer vault-lookup   # tool slug
+```
+
+An assignment is the explicit selection at the top of the resolution order, so it overrides scope defaults. Full surface: [cli-and-catalog.md](references/cli-and-catalog.md).
+
+## Audit
+
+```bash
+keystroke app list                       # org-registered apps
+keystroke credentials list               # connected instances + scope + default
+keystroke credentials assignments list --workflow <slug>   # which instance is pinned where
+```
+
+Failed integration call → confirm the app is connected for your project, the action uses the right slug, and (if multiple instances) a default or assignment resolves the right one.
+
+## Next references
+
+- [cli-and-catalog.md](references/cli-and-catalog.md) — `keystroke app` commands, connect, scopes, credential management & binding
+
+Related: [cli](.agents/skills/keystroke-cli/SKILL.md), [actions](.agents/skills/keystroke-actions/SKILL.md), [channels](.agents/skills/keystroke-channels/SKILL.md).

package/dist/skills-bundle/skills/keystroke-apps/references/cli-and-catalog.md

@@ -0,0 +1,104 @@
+# CLI, catalog, connect
+
+## Log in once
+
+```bash
+keystroke auth login
+keystroke auth status
+```
+
+Token is stored in the OS keychain and reused for all CLI commands. See [cli skill](.agents/skills/keystroke-cli/SKILL.md).
+
+## keystroke app commands
+
+All org-scoped; output is JSON.
+
+| Command | Purpose |
+| ------- | ------- |
+| `app list` | Apps registered/connectable in your org |
+| `app search <query>` | Search live Composio catalog (`--category`, `--limit`, `--cursor`) |
+| `app show <slug>` | Single catalog app details |
+| `app actions [slug]` | List actions for an app, or global search with `--search` (no slug) |
+| `app action <tool-slug>` | Full input/output JSON schema for one action |
+| `app create` | Create custom org app — manual (`--name`, `--slug`, `--description`, `--field`) or auto-detect (`--mcp`, `--openapi`, `--graphql`, `--preview`, `--auth`) |
+| `app sync <slug>` | Write `src/apps/<name>/app.ts` from platform template (`--dir`) |
+
+`--field` syntax: `key`, `key:secret`, `key:optional`, `key:public`, or combinations like `key:secret:optional` (repeatable). A bare `key` is **secret by default**; `:public` forces a non-secret field. Manual custom apps require at least one `--field`, and at least one of them must be required (not `:optional`).
+
+With `--mcp`, `--openapi`, or `--graphql`, auth and credential fields are auto-detected from the URL (same as the dashboard Create custom app dialog). Use `--preview` to print the assembled request without creating; override detected values with `--name`, `--slug`, `--description`, `--field`, or `--auth` (`oauth` / `api_key`, MCP only).
+
+```bash
+keystroke app create --mcp https://mcp.example.com/mcp --preview
+keystroke app create --openapi https://example.com/openapi.yaml --name "Example API"
+```
+
+## Connect an app
+
+`keystroke connect <slug>` attaches secrets to an app via the web app connect flow:
+
+```bash
+keystroke connect google          # official OAuth
+keystroke connect slack
+keystroke connect exa             # official API key
+keystroke connect acme/internal-api   # custom app (sync first)
+keystroke connect <slug> --print-url  # deeplink without opening browser
+```
+
+- **Official integrations** — always prefer `keystroke connect <slug>`
+- **Custom apps** — `keystroke app sync <slug>` first, then `keystroke connect <slug>`
+- Slug must exist in your org registry (`app list`)
+- The web app **Apps** page offers the same flow
+
+## Scopes
+
+A connection is stored at one scope. `keystroke connect` has **no** `--scope` flag — you choose the scope in the web connect flow. To set scope from the CLI, use `keystroke credentials set <key> --scope <scope> [--project-slug <slug>]` (that command defaults to `org`).
+
+| Scope | When |
+| ----- | ---- |
+| `project` | Tie to one project |
+| `org` | Share with every user and project |
+| `user` | Single user's personal connection |
+
+At runtime resolution prefers the **project default first, then the org default**. Get the active project id from `keystroke config show`.
+
+## Manage & bind credentials
+
+Day-to-day management (output is JSON):
+
+```bash
+keystroke credentials list                                   # every instance + scope + default flag
+keystroke credentials get <credential-id>
+keystroke credentials update <credential-id> --label "Prod" --default
+keystroke credentials rotate-key <credential-id> --set apiKey=@env:ACME_API_KEY
+keystroke credentials delete <credential-id>
+```
+
+`--default` marks one instance as the default for its app + scope. When several instances share a scope and none is the default, a run can't auto-resolve — set a default, or **bind** a specific instance to the step/tool that needs it.
+
+### Bind a specific instance to a step or tool
+
+An assignment pins an exact credential instance to one consumer. It's the **explicit selection** at the top of the resolution order, so it wins over scope defaults. List the bindable consumers first, then assign:
+
+```bash
+# Workflow consumers are step correlation ids from recent runs (step:<slug>#<n>)
+keystroke credentials consumers list --workflow sync
+keystroke credentials assignments assign --workflow sync --credential org/work --consumer step:fetch-gmail#0
+
+# Agent consumers are tool slugs
+keystroke credentials consumers list --agent support
+keystroke credentials assignments assign --agent support --credential vault-prod --consumer vault-lookup
+
+# Omit --consumer (or pass "*") to bind every consumer on the target
+keystroke credentials assignments assign --workflow sync --credential work
+
+keystroke credentials assignments list --workflow sync       # inspect bindings
+keystroke credentials assignments unassign <assignment-id>   # remove one
+```
+
+- Exactly one of `--workflow <slug>` or `--agent <slug>` is required.
+- `--credential` takes an instance slug: `work`, `org/work`, or `<app>/<slug>` (e.g. `linear/work`).
+- Workflow consumer ids only appear after a run has produced `step_completed` events; `consumers list` reads them from recent runs.
+
+## Where secrets live
+
+App secrets are **not** read from `.env` and are **never** uploaded by `keystroke deploy` — it ships code only. Attach integration secrets by connecting the app with `keystroke connect <slug>`; they're resolved at runtime for your project.

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

@@ -0,0 +1,66 @@
+---
+name: keystroke-channels
+description: Let people use keystroke agents from Slack (external channels) — connect Slack, bind channels with `keystroke channel bind`, pick a listen mode. Use when setting up messaging for agents.
+metadata:
+  keystroke-domain: channels
+---
+
+# External channels
+
+External channels route **Slack (and similar) messages** to an agent — people chat in-channel instead of using the CLI. Slack is the only channel today.
+
+## Setup (Slack)
+
+1. Deploy the agent you want to chat with (`keystroke deploy`)
+2. Connect Slack once for the org: `keystroke connect slack` (or the web app **Apps** page); complete OAuth
+3. Bind a channel to the agent (CLI below, or the agent's **External Channels** panel in the web app)
+4. Message the bound channel per its listen mode
+
+## Bind from the CLI
+
+```bash
+keystroke channel platforms list                                  # supported platforms
+keystroke channel accounts --platform slack                       # connected workspaces (team ids)
+keystroke channel directory --platform slack --account <team-id>  # channels you can bind
+keystroke channel bind \
+  --agent support \
+  --platform slack \
+  --account <team-id> \
+  --channel <channel-id> \
+  --mode mention
+keystroke channel list --agent support                            # bindings for an agent
+```
+
+Listen modes (`--mode`): `mention` (only when @mentioned), `all` (every message), `dm` (direct messages). Update or remove a binding with `keystroke channel update-binding --agent <id> --binding <id> --mode all` / `keystroke channel unbind --agent <id> --binding <id>`.
+
+`channel bind` also takes an optional `--channel-name <name>` (defaults to the channel id). Every `keystroke channel` subcommand accepts `--project <slug>` to target a non-active project; otherwise they use the active project.
+
+## What happens at runtime
+
+Inbound Slack event → lookup channel binding → `runPrompt` for the bound agent → reply in thread.
+
+The agent acts **on behalf of the channel**, not the sender: it runs with its own tools, actions, and credentials regardless of who messaged. Only bind agents to channels whose members you trust with everything the agent can do.
+
+## Audit channel-driven sessions
+
+The CLI session source is still named `gateway`:
+
+```bash
+keystroke agent sessions list <agent-key> --source gateway
+keystroke agent sessions get <agent-key> <session-id> --include messages,trace
+```
+
+## Troubleshooting
+
+| Issue       | Check                                                               |
+| ----------- | ------------------------------------------------------------------- |
+| Bot silent  | `keystroke agent sessions list` for errors; agent on the binding    |
+| "Choose an agent" prompt | The channel has no agent bound — bind one with `keystroke channel bind` |
+| OAuth fails | Slack redirect URLs match your project's web app origin             |
+| Wrong agent | Re-bind with `keystroke channel bind` (or the web app panel)        |
+
+## Next references
+
+- [slack-setup.md](references/slack-setup.md) — connect flow, testing against a deployed project
+
+Related: [agents](.agents/skills/keystroke-agents/SKILL.md), [apps](.agents/skills/keystroke-apps/SKILL.md).

package/dist/skills-bundle/skills/keystroke-channels/references/slack-setup.md

@@ -0,0 +1,41 @@
+# Slack channel setup
+
+## Connect Slack
+
+Connect the Slack app once for the org with `keystroke connect slack` — the Slack app credentials are entered in the web connect flow, not in your project's `.env`. The connected workspace stays connected; adding more agents is just a bind step.
+
+Slack OAuth and the inbound routes mount automatically on your **deployed** project, so connecting against the cloud target works out of the box — you don't add Slack to `keystroke.config.ts`.
+
+## Bind a channel
+
+```bash
+keystroke channel accounts --platform slack                       # find the team id
+keystroke channel directory --platform slack --account <team-id>  # find the channel id
+keystroke channel bind --agent support --platform slack \
+  --account <team-id> --channel <channel-id> --mode mention
+```
+
+`--mode` is `mention`, `all`, or `dm`. Thread follow-up is on by default; toggle it with `keystroke channel update-binding --agent <id> --binding <id> --threads` / `--no-threads`.
+
+The web app offers the same flow from each agent's **External Channels** panel.
+
+## Testing
+
+Slack OAuth and the inbound event routes are handled by your **deployed** project — `keystroke dev` (local watch/rebuild) is not in the Slack delivery path. To test Slack end-to-end: `keystroke deploy`, `keystroke connect slack`, `keystroke channel bind …`, then message the bound channel and inspect the session (below).
+
+> Self-hosting the keystroke platform is a separate concern: that setup seeds Slack app credentials via platform env vars (`SLACK_CLIENT_ID/SECRET/SIGNING_SECRET`) and a public origin (`PUBLIC_PLATFORM_PROXY_URL`). Those are **platform** vars, not part of a scaffolded user project, and `keystroke dev` does not read them.
+
+## Audit
+
+```bash
+keystroke agent sessions list <agent-key> --source gateway
+keystroke agent sessions get <agent-key> <session-id> --include messages,trace
+```
+
+## Common fixes
+
+| Issue         | Fix                                                |
+| ------------- | -------------------------------------------------- |
+| 401 on events | Check the signing secret in the Slack connection   |
+| No reply      | Session errors via `keystroke agent sessions list` |
+| Wrong agent   | Re-bind with `keystroke channel bind`              |