@keystrokehq/cli 0.1.112 → 0.1.114

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

@@ -118,17 +118,28 @@ To discover apps/integrations and their actions, query the live catalog with the
 ```bash
 keystroke apps search "{query}"                      # find an app and its slug in the full catalog — start here
 keystroke apps list                                  # apps registered/connectable in your org
-keystroke apps actions list <app> --search <q>       # actions an app exposes
-keystroke apps actions get <app> <tool>              # schema + how to run/import one action
+keystroke apps get <slug>                            # catalog toolkit OR custom org template (see kind)
+keystroke apps actions list <app> --search <q>       # catalog toolkit actions (custom org apps → kind:custom guidance)
+keystroke apps actions get <app> <tool>              # schema + how to run/import one catalog action
 keystroke apps execute <app> <tool> --input '{...}'  # run a connected catalog action (no server)
 keystroke credentials list                          # what's already connected — check before asking the user to connect
 ```
 
+Custom org apps (`{org}/{name}`) do not have catalog toolkit actions — use `apps get` / `apps sync` / `defineApp(...).action(...)` instead.
+
+**Gateway / channel binding:** to put an agent in a Slack channel, connect **`slackbot`** (not `slack`), then verify `channels accounts --platform slack` is non-empty before bind. Full detail: `search_docs "external channels"` → `/learn/agents/external-channels`.
+
 To connect an app's credentials, use the `connect_app` tool to get a link for the user — a browser cannot open in this workspace, so do not use `keystroke connect`. See `search_docs "use credentials"` for binding credentials to workflow steps and agent tools.
 
 Credentials are for secrets. Non-secret config — spreadsheet IDs, channel names, base URLs — belongs in code as a literal constant or a workflow input. Keystroke projects don't use `.env`.
 
-If an integration or a required action isn't supported, it is *extremely* easy to build a custom one — connections to any HTTP API or MCP server, including internal or private ones. Research the system's docs/spec first, then let `keystroke apps create --mcp|--openapi|--graphql <url>` scaffold it from the source, or hand-write it. `search_docs "custom integration"`.
+If a **credentialed** integration isn't supported, build a proper custom app — do not invent standalone `defineCredential` + a lone action. Research the system's docs/spec first, then:
+
+1. Register a connectable org app with `keystroke apps create --mcp|--openapi|--graphql <url>` (or manual `--name` / `--description` / `--field`) when the user should enter secrets in the Apps UI — URL create is catalog registration, not only code scaffolding.
+2. Author with `defineApp` in `src/apps/` + `app.action(...)`.
+3. Have the user connect (`connect_app` link), then deploy.
+
+Use `defineMcp` for MCP servers on agents. Credential-free project actions stay as plain `defineAction`. `search_docs "custom integration"`.
 
 ## Docs
 
@@ -150,6 +161,7 @@ Common pages to read with `query_docs` (e.g. `cat /learn/agents/build-agents.mdx
 | `/cli` | Full command reference, flags, JSON output |
 | `/explore-features` | Guide to find relevant feature documentation |
 | `/learn/agents/build-agents` | Models, tools, subagents, sandboxes, MCP tools on agents |
+| `/learn/agents/external-channels` | Slack vs Slackbot; connect `slackbot` and bind channels |
 | `/learn/workflows/build-workflows` | Steps, orchestration, sandboxes, durable waits |
 | `/learn/workflows/authoring-best-practices` | Canvas-legible, replayable workflow patterns (hard + soft rules) |
 | `/learn/actions/overview` | Action rules (leaf units, no action-in-action) |

package/dist/skills-bundle/_AGENTS.md

@@ -253,15 +253,16 @@ run: async ({ state, setState }) => {
 
 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). **Research first, then build:** search the catalog thoroughly before assuming an app is missing; for anything custom or unfamiliar, web-fetch/search the system's real docs — `llms.txt`, OpenAPI/GraphQL specs, API reference — before writing code. Never guess endpoints or payloads.
 
-Discover apps and actions with the CLI — the docs integration index is **not** reliable for discovery. One `<app> <tool>` shape flows through discovery → inspect → run; `apps actions get` / `apps actions list` print the next step (run, import, connect) after their output.
+Discover apps and actions with the CLI — the docs integration index is **not** reliable for discovery. One `<app> <tool>` shape flows through discovery → inspect → run for **catalog** apps; `apps actions get` / `apps actions list` print the next step after their output. Custom org apps (`{org}/{name}` from `apps create`) are different: `apps get` returns `kind:"custom"` (credential template); `apps actions list` returns guidance, not toolkit tools — actions live in project code via `defineApp(...).action(...)`.
 
 Think about testing as you build. Local tests don't link cloud credentials or the Keystroke client, so unit-test pure logic locally; for integrations, check needed apps/credentials and run each action once for real with `keystroke apps execute` (no deploy, no server) before wiring it into a workflow or agent — confirm the IDs, custom fields, and labels you're about to hard-code exist in the *connected* account. Schema inspection and dry-run flags prove nothing about the mutating path.
 
 ```bash
 keystroke apps list                          # all registered apps
 keystroke apps search "{query}"              # find an app + slug in the full catalog
-keystroke apps actions list <app> --search <q>    # actions an app exposes
-keystroke apps actions get <app> <tool>           # schema + how to run/import one action
+keystroke apps get <slug>                    # catalog toolkit OR custom credential template (kind)
+keystroke apps actions list <app> --search <q>    # catalog toolkit actions (custom → kind:custom guidance)
+keystroke apps actions get <app> <tool>           # schema + how to run/import one catalog action
 keystroke apps execute <app> <tool> --input '{...}'   # run a connected catalog action (no server)
 keystroke credentials list                  # what's already connected
 keystroke connect <slug>                    # connect an app credential (opens web OAuth/api key flow for the user)
@@ -270,7 +271,27 @@ keystroke credentials create <key> --set apiKey=@env:MY_KEY   # static API key
 
 `keystroke credentials list` is the **only** reliable connection check (`apps actions get` doesn't show status) — check it before connecting anything; the credential often already exists.
 
-Credentials are for secrets. Non-secret config — spreadsheet IDs, channel names, base URLs — belongs in code as a literal constant or a workflow input. Keystroke projects don't use `.env`. Missing a built-in integration? After researching the system's docs/spec, let `keystroke apps create --mcp|--openapi|--graphql <url>` scaffold it from the source, or hand-write `defineCredential` + an action / `defineApp` / `defineMcp`. See `/learn/credentials/custom-integrations`.
+### Gateway / channel binding
+
+To put an agent in a Slack channel, connect **`slackbot`** — not `slack`.
+
+```bash
+keystroke connect slackbot
+keystroke channels accounts --platform slack   # must be non-empty
+keystroke channels bind --agent <slug> --platform slack --account <team-id> --channel <channel-id>
+```
+
+Full detail: `/learn/agents/external-channels`.
+
+Credentials are for secrets. Non-secret config — spreadsheet IDs, channel names, base URLs — belongs in code as a literal constant or a workflow input. Keystroke projects don't use `.env`.
+
+Missing a built-in **credentialed** integration? After researching the system's docs/spec:
+
+1. **Catalog registration** (when the user should connect via Apps / `connect`) — `keystroke apps create --mcp|--openapi|--graphql <url>`, or manual `apps create --name … --description … --field …`. URL-based create registers a connectable org app; it is not only local code scaffolding.
+2. **Code authoring** — always `defineApp` in `src/apps/` + `app.action(...)`. Do **not** invent `src/credentials/foo.ts` + a lone `defineAction` for a new API.
+3. **Connect** — `keystroke connect <slug>` (or `credentials create` when you already have the secret), then deploy.
+
+Use `defineMcp` for MCP servers attached to agents. Plain `defineAction` (no credentials) does not need an app. See `/learn/credentials/custom-integrations`.
 
 ## Skills & files
 
@@ -337,6 +358,7 @@ Invoke/inspect commands print JSON to stdout (exit 0 on success, 1 on failure)
 9. **Missing `name`/`description`** — required on every primitive (agents, workflows, actions, trigger sources). Typecheck passes without them; module load throws at deploy.
 10. **Integration actions throw on failure** — prebuilt actions return their typed output directly (the shape `keystroke apps actions get` shows) and **throw** on failure; don't port `{ data, error, successful }` envelope checks from Composio docs.
 11. **`.default()` on an input field makes it required in the `run()` call type** — action/workflow `run` inputs are typed from the schema's *parsed* output, so a defaulted field must still be passed at the call site. When callers should be able to omit a field, use `.optional()` and apply the fallback inside `run`.
+12. **Slack gateway** — connect agents to Slack channels with `slackbot` (`keystroke connect slackbot`). See [Gateway / channel binding](#gateway--channel-binding).
 
 ## Documentation
 
@@ -353,7 +375,7 @@ Key pages (every `Full detail:` pointer in this guide is also a docs path; the i
 | `/cli` | Full command reference, flags, JSON output |
 | `/explore-features` | Map of all feature documentation |
 | `/learn/agents/build-agents` | Models, tools, subagents, sandboxes, MCP tools on agents |
-| `/learn/agents/external-channels` | Slack / external channel bindings |
+| `/learn/agents/external-channels` | Slack vs Slackbot; connect `slackbot` and bind channels |
 | `/learn/workflows/authoring-best-practices` | Canvas-legible, replayable workflow patterns |
 | `/learn/triggers/overview` | Choosing a trigger type (per-source pages live alongside) |
 | `/learn/credentials/connect-credentials` | `keystroke connect`, OAuth, project credentials |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/cli",
-  "version": "0.1.112",
+  "version": "0.1.114",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/keystrokehq/keystroke.git",
@@ -43,8 +43,8 @@
     "tsdown": "^0.22.0",
     "tsx": "^4.22.3",
     "@keystrokehq/oxlint-config": "0.0.4",
-    "@keystrokehq/tsdown-config": "0.0.5",
     "@keystrokehq/tsconfig": "0.0.3",
+    "@keystrokehq/tsdown-config": "0.0.5",
     "@keystrokehq/vitest-config": "0.0.7"
   },
   "scripts": {