@keystrokehq/cli 0.1.15 → 0.1.17

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
 

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

@@ -9,9 +9,9 @@ metadata:
 
 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`. Each **target** (local server vs cloud project) has its own connections — `keystroke deploy` uploads code only, not connections. Connect apps on **every target** you run on.
+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 **must** go through an app — sync it into `src/apps/` first, then use `app.action()` in `src/actions/`. See [actions skill](.agents/skills/keystroke-actions/SKILL.md).
+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
 
@@ -83,7 +83,7 @@ Auth kinds: `keystroke` (MCP/Composio catalog apps), `api_key` (custom fields),
 
 ## Connect an app
 
-`keystroke connect <slug>` opens the dashboard connect flow (OAuth or API-key form, depending on the app). This is how secrets get attached to an app — not via `.env`.
+`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:
 
@@ -100,34 +100,47 @@ keystroke app sync acme/internal-api
 keystroke connect acme/internal-api
 ```
 
-Run `connect` against **each target** you deploy to (local while developing; cloud after `keystroke config use cloud`). The dashboard **Apps** page offers the same flow.
+The web app **Apps** page offers the same flow.
 
-Field names in the connect form match the app's synced template. Default scope is **project** — see [cli-and-catalog.md](references/cli-and-catalog.md).
+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).
 
-## Before deploy: connect on cloud
+## Connect what your project needs
 
-Cloud starts with **no connected apps**. After the first deploy:
+A new project starts with **no connected apps**. After deploy, connect the apps it uses:
 
 ```bash
 keystroke deploy --project <id>
-keystroke config use cloud
 keystroke connect google
 keystroke connect exa
 keystroke app list
 ```
 
-A runtime error about a missing connection almost always means the app was connected locally but not on the cloud target.
+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 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 target (`keystroke config show`), the app is connected on that target, and the action uses the right slug.
+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, local vs cloud
+- [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), [gateways](.agents/skills/keystroke-gateways/SKILL.md).
+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

@@ -7,7 +7,7 @@ keystroke auth login
 keystroke auth status
 ```
 
-Token is stored in the OS keychain and reused for **cloud** CLI commands. Switching local ↔ cloud does not require re-auth. See [cli skill](.agents/skills/keystroke-cli/SKILL.md).
+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
 
@@ -23,11 +23,11 @@ All org-scoped; output is JSON.
 | `app create` | Create custom org `api_key` app (`--name`, `--slug`, `--description`, `--field`) |
 | `app sync <slug>` | Write `src/apps/<name>/app.ts` from platform template (`--dir`) |
 
-`--field` syntax: `key`, `key:secret`, `key:optional`, or `key:secret:optional` (repeatable).
+`--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. `app create` requires at least one `--field`, and at least one of them must be required (not `:optional`).
 
 ## Connect an app
 
-`keystroke connect <slug>` attaches secrets to an app via the dashboard connect flow:
+`keystroke connect <slug>` attaches secrets to an app via the web app connect flow:
 
 ```bash
 keystroke connect google          # official OAuth
@@ -40,27 +40,58 @@ 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`)
-- Connect once per **target** (local dev server vs cloud deployed project)
-- Dashboard at `:3000` → **Apps** offers the same flow
+- The web app **Apps** page offers the same flow
 
 ## Scopes
 
-When you connect an app, the connection is stored at one scope:
+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` (default) | Tie to one project — use unless told otherwise |
-| `org` | Share with every user and project — only on explicit request |
+| `project` | Tie to one project |
+| `org` | Share with every user and project |
 | `user` | Single user's personal connection |
 
-At runtime resolution is **org first, then project**. Get the active project id from `keystroke config show`.
+At runtime resolution prefers the **project default first, then the org default**. Get the active project id from `keystroke config show`.
 
-## `.env` vs connected apps
+## Manage & bind credentials
 
-| Holds | `.env` | Connected apps (via connect) |
-| ----- | ------ | ------------------------------ |
-| Model keys (`ANTHROPIC_API_KEY`), DB URL, OAuth **provider** config (`SLACK_CLIENT_ID`, `GOOGLE_*`) | yes — local boot only | — |
-| Integration secrets resolved at runtime | — | yes |
-| Reaches the cloud? | no | yes, when connected on cloud target |
+Day-to-day management (output is JSON):
 
-App secrets are **not** read from `.env` — connect the app with `keystroke connect`. Connections follow the active target (local while `keystroke dev` runs; cloud after deploy). Re-connect on the cloud target after deploy.
+```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`              |