@keystrokehq/cli 0.0.111 → 0.0.112

package/dist/skills-bundle/_AGENTS.md

@@ -68,6 +68,15 @@ Default-export each module — the server discovers files under `src/`.
 
 **Actions are leaf units.** An action never calls another action (including integration actions like `postMessage`). Compose actions in a workflow, or attach an integration action directly as a workflow step / agent tool. An action may call an agent.
 
+## Working habits
+
+A few things that are easy to skip and cause common failures:
+
+- **Research real APIs before mirroring them** — web search and fetch the actual reference & explore relevant docs; don't guess endpoints or payload shapes.
+- **Run before you depend or deploy** — run the workflow/agent locally and read the real output (`keystroke workflow runs get <key> <run-id> --include steps,trace`) before wiring dependent steps.
+- **Cover obvious edge cases** and write simple tests as needed (null field, empty array, a step that throws) — see [workflows skill](.agents/skills/keystroke-workflows/SKILL.md).
+- **Cloud creds aren't in `.env`** — `keystroke deploy` never uploads `.env`; credentials that run in the cloud must be set against the cloud target. See [credentials skill](.agents/skills/keystroke-credentials/SKILL.md).
+
 ## Audit & debug (CLI)
 
 Use the CLI against the correct target — do not call HTTP directly.

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

@@ -20,7 +20,7 @@ import { exaSearch, exaAnswer } from "@keystrokehq/exa/actions";
 export default defineAgent(
   {
     systemPrompt: "Research signups with Exa. Stay concise; cite sources.",
-    model: { provider: "anthropic", id: "claude-sonnet-4-6" },
+    model: "anthropic/claude-sonnet-4-6",
     tools: [exaSearch, exaAnswer],
   },
   { key: "signup-researcher", module: import.meta.url },

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

@@ -1,18 +1,25 @@
 # Models
 
 ```ts
-model: { provider: "anthropic", id: "claude-sonnet-4-6" }
-thinkingLevel: "high" // optional — defaults to "medium"; use "off" to disable reasoning
+model: "google/gemini-2.5-flash"; // vendor/model-id — any pi-ai or gateway catalog id
+thinkingLevel: "high"; // optional — defaults to "medium"; use "off" to disable reasoning
 ```
 
 Per-prompt override via API: `{ "message": "...", "thinkingLevel": "low" }`.
 
-Set provider API keys in `.env` (e.g. `ANTHROPIC_API_KEY`).
+**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.
 
-| Use case       | Tip                                               |
-| -------------- | ------------------------------------------------- |
-| General agents | `claude-sonnet-4-6` or your provider's fast model |
-| Heavy tool use | Strong tool-use model + focused system prompt     |
-| Cost in dev    | Cheaper model id in local `.env` only             |
+**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`).
+
+**Cloud** — hosted workers use the platform LLM proxy automatically; no provider keys in the container.
+
+| 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        |
 
 After changing model, smoke-test: `keystroke agent prompt <key> --message "Hi"`.

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

@@ -1,30 +1,55 @@
 ---
 name: keystroke-credentials
-description: Manage keystroke credentials — vault secrets, OAuth via integration plugins, keystroke connect and credentials CLI. Use when wiring Exa, Google, Slack, or custom API keys.
+description: Manage keystroke credentials — vault API keys and OAuth via keystroke credentials / keystroke connect, scopes, and getting creds into the cloud. Use when wiring Exa, Google, Slack, or custom API keys, and when a deployed run fails with missing credentials.
 metadata:
   keystroke-domain: credentials
 ---
 
 # Credentials
 
-Secrets live in the **server vault** and OAuth stores — not in source.
+Secrets live in a **credential store** (vault for API keys, OAuth stores for tokens) — never in source.
 
-## Enable integrations
+There are **two separate stores**: your **local** keystroke server and the **cloud** platform. `keystroke deploy` uploads your built code only — it never copies `.env` or local credentials. Provision creds for **every target you run on**.
 
-```ts
-// keystroke.config.ts
-import { defineConfig } from "@keystrokehq/config";
-import { googleManaged } from "@keystrokehq/google";
-import { slackManaged } from "@keystrokehq/slack";
+## `.env` vs the credential store
 
-export default defineConfig({
-  plugins: [slackManaged(), googleManaged()],
-});
+| Holds                                                                                                             | `.env`                | Credential store        |
+| ----------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------- |
+| Model keys (`ANTHROPIC_API_KEY`), DB URL, OAuth **app** config (`SLACK_CLIENT_ID`, `GOOGLE_*`, `SLACK_BOT_TOKEN`) | yes — local boot only | —                       |
+| API-key + OAuth credential **instances** resolved by actions at runtime                                           | —                     | yes                     |
+| Reaches the cloud?                                                                                                | no                    | yes, when set vs. cloud |
+
+The local server reads `.env` at boot; OAuth **app** env auto-seeds the local OAuth app so you can `connect`. **API-key credentials (Exa, custom) are not read from `.env`** — create them with `keystroke credentials set`.
+
+## Scopes — default to `project`
+
+A credential is stored at one scope:
+
+| Scope                 | CLI                                 | Means                                                                                                        |
+| --------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| **project** (default) | `--scope project --project-id <id>` | Tied to one project. **Use this unless told otherwise** — you're provisioning the project you're working in. |
+| **org**               | `--scope org`                       | Shared by **every user and project in the org**. Only set org scope when the user explicitly asks for it.    |
+| **user**              | `--scope user`                      | A single user's personal credential — a different use case, not project/deploy setup.                        |
+
+`--scope` is required (there is no implicit default), so always pass it — pick `project` by default. Get the active project id from `keystroke config show`.
+
+At runtime an action resolves a credential by checking the **org** scope first, then the **project** scope.
+
+## Set an API key
+
+```bash
+# default: scope to the project you're deploying; read the value from your shell / .env
+keystroke credentials set exa --scope project --project-id <id> --set apiKey=@env:EXA_API_KEY
+
+# or paste the value directly
+keystroke credentials set exa --scope project --project-id <id> --set apiKey=sk-...
 ```
 
-Set provider env vars in `.env` (app ids, secrets, API keys). Model keys like `ANTHROPIC_API_KEY` also go in `.env`.
+- The field name (`apiKey`) comes from the integration's `defineCredential`.
+- `@env:VAR` reads from your shell or project `.env`.
+- `set` always creates a **new** instance. To change an existing one: `keystroke credentials update <id>`. A second instance in the same scope needs `--label <name>` (and `--default` to pick the one to resolve).
 
-## OAuth connect
+## Connect OAuth (Google, Slack, etc)
 
 ```bash
 keystroke auth login
@@ -32,13 +57,26 @@ keystroke connect google
 keystroke connect slack
 ```
 
-## Manual vault secrets
+`connect` completes the browser flow and stores the OAuth token in the active target's store, ready for any action that uses that integration. Run it against each target you deploy to.
+
+## Targets: local vs cloud
+
+`keystroke credentials` and `keystroke connect` follow the active runtime, exactly like other commands: **local** while `keystroke dev` runs or after `config use local`; the **deployed project** after `config use cloud` or with `--project`. A credential set locally does not exist in the cloud, and vice versa. See [cli skill](.agents/skills/keystroke-cli/SKILL.md).
+
+## Before deploy: provision the cloud
+
+The cloud store starts **empty**. After the first deploy:
 
 ```bash
-keystroke credentials list
-keystroke credentials set exa-api-key --value '...'
+keystroke deploy --project <id>          # uploads code only — no creds, no .env
+keystroke config use cloud               # target the deployed project
+keystroke connect google                 # OAuth against cloud
+keystroke credentials set exa --scope project --project-id <id> --set apiKey=@env:EXA_API_KEY
+keystroke credentials list               # verify against the active (cloud) target
 ```
 
+A missing-credential error on a deployed run almost always means a credential set locally was never set in the cloud.
+
 ## Use in actions
 
 ```ts
@@ -53,18 +91,18 @@ export const notify = defineAction({
 });
 ```
 
-Integration actions (Exa search, Gmail send, Slack post) resolve credentials automatically when the plugin is configured.
+Integration actions (Exa search, Gmail send, Slack post) resolve credentials automatically from the active target's store when the plugin is configured.
 
 ## Audit
 
 ```bash
-keystroke credentials list
+keystroke credentials list   # instances for the active target
 ```
 
-Failed integration calls → check missing env vars, OAuth not completed, or wrong credential key on the action.
+Failed integration call → confirm you are on the right target (`keystroke config show`), the credential exists **for that target and scope**, OAuth was completed, and the action declares the right credential key.
 
 ## Next references
 
-- [cli-and-oauth.md](references/cli-and-oauth.md) — auth, connect, dashboard
+- [cli-and-oauth.md](references/cli-and-oauth.md) — auth, connect, local vs cloud stores
 
-Related: [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), [gateways](.agents/skills/keystroke-gateways/SKILL.md).

package/dist/skills-bundle/skills/keystroke-credentials/references/cli-and-oauth.md

@@ -16,22 +16,36 @@ keystroke connect google
 keystroke connect slack
 ```
 
-Complete the browser flow once per provider. Tokens are stored server-side.
+Complete the browser flow once per provider. The token is stored server-side in the active target's store, ready for actions that use the integration. Run `connect` against each target you deploy to.
 
-## Manual secrets
+## Set an API key
 
-For API keys that are not OAuth (e.g. Exa):
+For API keys that are not OAuth (e.g. Exa). The field name (`apiKey`) comes from the integration's `defineCredential`:
 
 ```bash
-keystroke credentials set exa-api-key --value '...'
+# default to project scope — provision the project you're working in
+keystroke credentials set exa --scope project --project-id <id> --set apiKey=@env:EXA_API_KEY
 keystroke credentials list
 ```
 
-## `.env` vs vault
+`--scope` is required; there is no implicit default, so always pass it:
 
-| Store         | For                                                                                  |
-| ------------- | ------------------------------------------------------------------------------------ |
-| `.env`        | Server bootstrap — `ANTHROPIC_API_KEY`, Slack app id/secret, database URL            |
-| Vault / OAuth | Per-user or per-workspace tokens via `keystroke credentials` and `keystroke connect` |
+| Scope               | When                                                                         |
+| ------------------- | ---------------------------------------------------------------------------- |
+| `project` (default) | Tie the credential to one project — use this unless told otherwise.          |
+| `org`               | Share with **every user and project** in the org — only on explicit request. |
+| `user`              | A single user's personal credential — different use case.                    |
+
+`set` always creates a new instance; use `keystroke credentials update <id>` to change one, and `--label <name>` to add a second in the same scope. At runtime a credential resolves **org first, then project**.
+
+## `.env` vs the credential store
+
+| Holds                                                                                          | `.env`                | Credential store        |
+| ---------------------------------------------------------------------------------------------- | --------------------- | ----------------------- |
+| Model keys (`ANTHROPIC_API_KEY`), DB URL, OAuth **app** config (`SLACK_CLIENT_ID`, `GOOGLE_*`) | yes — local boot only | —                       |
+| API-key + OAuth credential instances resolved at runtime                                       | —                     | yes                     |
+| Reaches the cloud?                                                                             | no                    | yes, when set vs. cloud |
+
+API-key credentials are **not** read from `.env` — create them with `keystroke credentials set`. `keystroke credentials` / `keystroke connect` target the **active** runtime (local while `keystroke dev` runs or after `config use local`; cloud after deploy / `config use cloud` / `--project`). The stores are independent; `keystroke deploy` never copies `.env` or local credentials, so re-provision against the cloud target after deploy.
 
 Dashboard at `:3000` can also manage credentials and gateway attachments.

package/dist/templates/hello-world/src/agents/hello.ts

@@ -3,7 +3,7 @@ import { defineAgent } from "@keystrokehq/keystroke/agent";
 export default defineAgent(
   {
     systemPrompt: "You are a friendly hello-world agent. Keep replies short.",
-    model: { provider: "anthropic", id: "claude-sonnet-4-6" },
+    model: "anthropic/claude-sonnet-4-6",
   },
   { key: "hello", module: import.meta.url },
 );

package/package.json

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