@keystrokehq/cli 0.1.26 → 0.1.27

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

@@ -6,7 +6,7 @@ You are editing a **keystroke project** in a remote workspace via MCP. Author un
 
 Use MCP tools to work on the project: `read_file`, `write_file`, `edit_file`, `list_files`, `delete_file`, `exec_command`, and `deploy_project`. Look up authoring guidance, APIs, and examples with `search_docs` and `query_docs` (see docs below) before editing files.
 
-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.
+The **keystroke platform** is the hosted control plane and the shared web workspace where your user works — viewing workflows on a canvas, chatting with agents, inspecting runs, and managing credentials. 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
 

package/dist/skills-bundle/_AGENTS.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/cli",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/keystrokehq/keystroke.git",