@keystrokehq/cli 0.1.38 → 0.1.39

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

@@ -38,7 +38,7 @@ Agents are useful when a task needs judgment, language understanding, tool use,
 | -------------------- | --------------------------------------------------- |
 | **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 |
+| **File system**      | Isolated workspace per session — `/workspace/agent` persists across sessions (skills, files); `/workspace/session` is per-session scratch. 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/` |
@@ -66,6 +66,7 @@ Workflows also render as an interactive **canvas** in the platform. Keep durable
 - **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 with `deploy_project`, run it in the cloud via `exec_command`, and read the real output before activating live triggers or claiming you are finished. Chat with agents and run workflows to confirm they behave correctly.
 - **Cover obvious edge cases** and write simple tests as needed (null field, empty array, a step that throws).
+- **Verify integration prerequisites** — before composing a catalog action into a workflow, run it once with `keystroke app execute` (via `exec_command`) to confirm the IDs and fields exist in the connected account.
 - **Connected apps aren't in `.env`** — deploy never uploads `.env`; use the `connect_app` tool to get a link for the user to connect integrations in the web app (a browser cannot open in this workspace).
 - **Filtered deploys** — determine if you should do a full vs filtered deploy, or use WIP ignore directives (`search_docs "filtered deploy"`).
 - **Dependencies** — use the project's existing package manager (`package.json` `packageManager` field or lockfile); default to npm only on a freshly created project with no lockfile.
@@ -107,11 +108,13 @@ keystroke app search <query>                        # find an app and its slug i
 keystroke app actions <app> --search <q>            # actions an app exposes
 keystroke app action <app> <tool>                   # schema + how to run/import one action
 keystroke app execute <app> <tool> --input '{...}'  # run a connected catalog action (no server)
-keystroke credentials list                          # stored credential instances
+keystroke credentials list                          # what's already connected — check before asking the user to connect
 ```
 
 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. There is no platform variable store and deploy never uploads `.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. `search_docs "custom integration"`.
 
 ## Docs

package/dist/skills-bundle/_AGENTS.md

@@ -53,11 +53,12 @@ Each primitive imports from `@keystrokehq/keystroke/<piece>` (`/agent`, `/action
 Keystroke is deploy-first: build, ship, then run and inspect what's live. 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 "..."` / `keystroke app execute <app> <tool> --input '{...}'` (connected catalog actions only).
-5. **Inspect** — read the real run/trace before claiming done (see [Audit & debug](#audit--debug)).
-6. Repeat.
+2. **Verify prerequisites** — `keystroke app execute <app> <tool> --input '{...}'` runs any connected catalog action against the cloud with no deploy and no server. Before wiring an integration into a workflow, execute it once for real: confirm the IDs, custom fields, and labels you're about to hard-code actually exist in the *connected* account. Schema inspection and hand-rolled dry-run flags prove nothing about the mutating path.
+3. **Edit** primitives under `src/`. Unit-test workflow logic in-process with `executeWorkflow` (`/learn/workflows/test-workflows`) — that's the fast loop; deploying is the shipping checkpoint.
+4. **Deploy** — `keystroke deploy` (full) or `keystroke deploy --filter agents/support` (one module).
+5. **Run** — `keystroke workflow run <slug> --input '{...}'` / `keystroke agent prompt <slug> --message "..."`.
+6. **Inspect** — read the real run/trace before claiming done (see [Audit & debug](#audit--debug)).
+7. Repeat.
 
 ```bash
 keystroke auth status                                     # current user + org
@@ -99,7 +100,7 @@ export default defineAgent({
 
 - **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.
+- **Built in**: isolated workspace with file + `bash` tools — `/workspace/agent` persists across sessions (skills, `src/files/`, anything worth keeping); `/workspace/session` is per-session scratch. Plus session + persistent memory (`memory: false` to disable), `web_search`/`web_fetch` when configured, and 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).
 
@@ -195,12 +196,14 @@ export default defineWebhookSource({
 
 | Source | Use when |
 | --- | --- |
-| **Schedule** (`defineCronSource`) | Time alone starts the run (cron is UTC in prod). Passes `{}` — workflow `input` must accept an empty object. |
+| **Schedule** (`defineCronSource`) | The workflow should run **every** tick, unconditionally — no filters exist on cron (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. |
+| **Poll** (`definePollSource`) | Check an external system each tick and fire the workflow **only when the result passes `.filter(...)`**. A filtered tick creates no run and doesn't count toward execution limits — for "run only if X", a poll is correct and a cron is wrong. |
 
 Filters live on the source; `transform` lives on the workflow attachment. Agents use `.attach({ agent, prompt })` (not `transform`). Attachment id: `{sourceSlug}:{targetSlug}`.
 
+**Deploy timing** — webhooks are passive and safe to deploy any time. A poll fires immediately on deploy; a cron waits for its next scheduled slot, then runs unattended. Until the workflow is verified, pause with `keystroke trigger attachment disable` — the disabled state survives redeploys.
+
 ## Integrations & credentials
 
 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).
@@ -215,12 +218,14 @@ keystroke app search <query>                # find an app + slug in the full cat
 keystroke app actions <app> --search <q>    # actions an app exposes
 keystroke app action <app> <tool>           # schema + how to run/import one action
 keystroke app 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
 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
 ```
 
-`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`.
+Check `keystroke credentials list` before telling the user to connect anything — the credential often already exists (each row shows the app and scope; `app action` output does *not* show connection status, so the list is the only reliable check).
+
+Credentials are for secrets. Non-secret config — spreadsheet IDs, channel names, base URLs — belongs in code as a literal constant or a workflow input. There is no platform variable store and `keystroke deploy` **never uploads `.env`**, so a constant in source is the correct home, not a workaround. Missing a built-in integration? Use `defineCredential` + an action, `defineApp`, or `defineMcp`. See `/learn/credentials/custom-integrations`.
 
 ## Skills & files
 
@@ -261,8 +266,9 @@ Invoke/inspect commands print JSON to stdout (exit 0 on success, 1 on failure)
 - [ ] 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.
+- [ ] Executed each mutating integration action once via `keystroke app execute` before composing it — a passing dry-run flag doesn't count.
 - [ ] 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`).
+- [ ] Checked `keystroke credentials list` before connecting; 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/cli",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/keystrokehq/keystroke.git",
@@ -40,10 +40,10 @@
     "tsdown": "^0.22.0",
     "tsx": "^4.22.3",
     "vitest": "^4.1.7",
-    "@keystrokehq/oxlint-config": "0.0.4",
     "@keystrokehq/tsconfig": "0.0.3",
     "@keystrokehq/tsdown-config": "0.0.5",
-    "@keystrokehq/vitest-config": "0.0.7"
+    "@keystrokehq/vitest-config": "0.0.7",
+    "@keystrokehq/oxlint-config": "0.0.4"
   },
   "scripts": {
     "build": "tsx scripts/generate-catalog-versions.ts && tsdown && node scripts/copy-templates.mjs && node scripts/copy-skills-bundle.mjs",