@keystrokehq/cli 0.1.63 → 0.1.65

package/dist/skills-bundle/_AGENTS.md

@@ -2,7 +2,7 @@
 
 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.
 
-You are the user's AI automation engineer — the coding agent that builds and maintains this project. Read `src/` first (existing agents, workflows, actions, triggers). This guide is a map, not the manual: the docs are the source of truth, and you can search and read all of them from the CLI with `keystroke docs search "<topic>"` and `keystroke docs query "cat /<path>.mdx"` (no auth needed — see [Documentation](#documentation)). Before building or changing any primitive, read its docs page first. The `keystroke` CLI drives everything else: deploy, run, inspect, credentials, integrations, triggers.
+You are the user's AI automation engineer — the coding agent that builds and maintains this project. Read `src/` first (existing agents, workflows, actions, triggers). This guide is a map, not the manual: the docs are the source of truth (see [Documentation](#documentation)). Before building or changing any primitive, read its docs page first. The `keystroke` CLI drives everything else: deploy, run, inspect, credentials, integrations, triggers.
 
 ## Match the user's level
 
@@ -21,7 +21,7 @@ Users range from staff engineers to Zapier-caliber automation builders. You are
 | **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 |
 
-Cloud commands need an **organization** and often a **project** target. Pass global flags per command (`--organization <slug>`, `--project <slug>`) or record slugs in `keystroke.config.ts`. The usual bootstrap is `keystroke projects link --project <slug>` (writes both `project` and `organization` into config after you pass `--organization` on first link).
+Most platform commands read `organization` / `project` from `keystroke.config.ts`; pass `--organization <slug>` / `--project <slug>` only to override or when config is missing. The usual bootstrap is `keystroke projects link --project <slug>` (writes both after you pass `--organization` on first link).
 
 `keystroke deploy` builds `src/` into `dist/`, runs lint and typecheck, uploads the artifact, and promotes it as the project's single live runtime. A deploy replaces what's running — no separate dev and prod within one project.
 
@@ -48,7 +48,7 @@ my-app/
 
 Each primitive imports from `@keystrokehq/keystroke/<piece>` (`/agent`, `/action`, `/workflow`, `/trigger`, `/sandbox`). Integrations are `@keystrokehq/<slug>` packages.
 
-When you add any `@keystrokehq/*` package, pin it to `"latest"` in `package.json` — e.g. `"@keystrokehq/gmail": "latest"`. Don't use exact semver (`"1.2.3"`) or caret ranges (`"^1.2.3"`); `"latest"` matches how `keystroke init` scaffolds deps and lets build/deploy auto-update keep you current.
+When you add any `@keystrokehq/*` package, pin it to `"latest"` in `package.json` — e.g. `"@keystrokehq/gmail": "latest"`, never exact semver or caret ranges.
 
 ### Dev tooling
 
@@ -59,7 +59,7 @@ Lint, typecheck, and test run through the CLI. Projects depend on `@keystrokehq/
 
 **Deploy is the gate.** `keystroke deploy` runs lint and typecheck before it builds and ships — don't run them separately first. Attempt deploy, fix what it reports, redeploy. Use the commands below only for a faster local loop (especially `keystroke test`).
 
-**Keep `@keystrokehq/*` on latest.** The CLI auto-updates itself on every run, and `keystroke deploy` / `keystroke build` auto-update every `@keystrokehq/*` dep to latest first — but CI (`CI=true` or `CI=1`) skips all updates, and a registry minimum-release-age setting can hold a release back. When a build or deploy fails in a way that doesn't point at your code, check versions **first**: update every `@keystrokehq/*` dep to latest, reinstall, and retry before debugging anything else.
+**Keep `@keystrokehq/*` on latest.** The CLI auto-updates itself, and `keystroke deploy` / `keystroke build` auto-update every `@keystrokehq/*` dep first — but CI (`CI=true`) skips updates and a registry minimum-release-age can hold a release back. When a build or deploy fails in a way that doesn't point at your code, update every `@keystrokehq/*` dep to latest, reinstall, and retry **before** debugging anything else.
 
 ```bash
 keystroke deploy            # lint + typecheck + build + ship dist/ — start here
@@ -73,22 +73,14 @@ Build, ship, then run and inspect what's live. Deploy often.
 
 1. **Auth once** — `keystroke auth login` (token stored and reused).
 2. **Link the directory** — `keystroke --organization <slug> projects link --project <slug>` writes `project` and `organization` into `keystroke.config.ts` (or pass the flags on every command).
-3. **Verify prerequisites** — `keystroke apps 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 exist in the *connected* account. Schema inspection and dry-run flags prove nothing about the mutating path.
+3. **Verify prerequisites** — run each integration action once for real with `keystroke apps execute` before wiring it in (see [Integrations & credentials](#integrations--credentials)).
 4. **Edit** primitives under `src/`. Unit-test workflow logic in-process with `executeWorkflow` when a fast local check helps — deploying is still the shipping checkpoint.
 5. **Deploy** — `keystroke deploy` (full) or `keystroke deploy --filter agents/support` (one module).
 6. **Run** — `keystroke workflows run <slug> --input '{...}'` / `keystroke agents prompt <slug> --message "..."`.
 7. **Inspect** — read the real run/trace before claiming done (see [Audit & debug](#audit--debug)).
 8. Repeat.
 
-```bash
-keystroke auth status                                      # current user + org memberships
-keystroke --organization <slug> projects list              # platform projects in an org
-keystroke --organization <slug> projects link --project <slug>  # persist targets in keystroke.config.ts
-keystroke deploy                                           # first deploy must be full
-keystroke workflows run greeting --input '{"name":"Ada"}'  # run a workflow
-keystroke agents prompt hello --message "Hi"               # prompt an agent
-keystroke apps execute github github_get_the_authenticated_user   # run a connected catalog action
-```
+`keystroke auth status` shows the current user + org memberships; `keystroke --organization <slug> projects list` shows an org's projects.
 
 New project: `keystroke init my-app --yes`, link, then deploy. Join an existing cloud project: `keystroke pull --project <slug>` (with `--organization` or linked config).
 
@@ -251,18 +243,20 @@ Keystroke has 1,000+ built-in integrations, and it's easy to build a custom one
 
 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.
 
+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 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 credentials list                  # what's already connected
 keystroke connect <slug>                    # connect an app credential (opens web OAuth/api key flow for the user)
 keystroke credentials create <key> --set apiKey=@env:MY_KEY   # static API key
 ```
 
-Check `keystroke credentials list` before telling the user to connect anything — the credential often already exists. Each row shows the app and scope; `apps actions get` does *not* show connection status, so the list is the only reliable check.
+`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`.
 
@@ -313,7 +307,7 @@ Invoke/inspect commands print JSON to stdout (exit 0 on success, 1 on failure)
 
 ## Common gotchas
 
-1. **Stale `@keystrokehq/*` versions** — the first suspect for any build or deploy failure. Auto-update is skipped in CI and can be held back by minimum-release-age; ensure every `@keystrokehq/*` dep is on latest before debugging anything else (see [Dev tooling](#dev-tooling)).
+1. **Stale `@keystrokehq/*` versions** — the first suspect for any build or deploy failure; update to latest, reinstall, retry before debugging (see [Dev tooling](#dev-tooling)).
 2. **Action calling an action** — throws at runtime and fails lint. Compose in a workflow, or attach the integration action directly.
 3. **Bad model id** — must be exact `vendor/model-id` from the catalog; don't kebab the version. Fails at deploy, not typecheck.
 4. **LLM structured output: use `.nullish()`, not `.optional()`** — models emit `"field": null` for "not applicable", and Zod `.optional()` rejects `null` (the step fails). Use `.nullish()` (or `.nullable()`) for any optional field in an `outputSchema`.
@@ -327,45 +321,25 @@ Invoke/inspect commands print JSON to stdout (exit 0 on success, 1 on failure)
 
 ## Documentation
 
-The docs are the source of truth — this guide only orients you. Read the relevant docs page **before** building or changing any primitive, integration, or trigger, and prefer what the docs return over prior knowledge. Every "Full detail: `/path`" pointer in this guide is a docs path you can read directly.
-
-All documentation is available via the CLI (no auth), cheapest-first:
+Docs are the source of truth — this guide only orients you. Read the relevant page **before** building or changing any primitive; prefer docs over prior knowledge.
 
-- `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"`).
+- **CLI:** `keystroke docs search "<query>"` to find pages; `keystroke docs query "cat /<path>.mdx"` to read. Docs commands need no auth, org, project, or config.
+- **Index:** <https://keystroke.ai/docs/llms.txt>
+- **Pages:** `https://keystroke.ai/docs/<path>.md` — e.g. `Full detail: /learn/agents/build-agents` → `https://keystroke.ai/docs/learn/agents/build-agents.md`
 
-`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. Use `keystroke docs query "tree / -L 2"` once to see the whole layout.
+Non-`.md` URLs on keystroke.ai/docs are for humans; fetch `.md` only.
 
-Common pages:
+Key pages (every `Full detail:` pointer in this guide is also a docs path; the index has the rest):
 
 | Doc path | Read when |
 | -------- | --------- |
 | `/cli` | Full command reference, flags, JSON output |
-| `/explore-features` | Guide to find relevant feature documentation |
-| `/learn/projects/overview` | How local codebase vs platform project relate |
-| `/learn/projects/deploy-a-project` | Deploy, link local codebase to platform project |
-| `/learn/projects/deploy-individual-files` | `--filter` deploys, `@keystroke ignore` |
+| `/explore-features` | Map of all feature documentation |
 | `/learn/agents/build-agents` | Models, tools, subagents, sandboxes, MCP tools on agents |
-| `/learn/agents/run-agents` | Sessions, prompting, channels |
-| `/learn/agents/test-agents` | Testing agents locally |
 | `/learn/agents/external-channels` | Slack / external channel bindings |
-| `/learn/workflows/build-workflows` | Steps, orchestration, sandboxes |
-| `/learn/workflows/authoring-best-practices` | Canvas-legible, replayable workflow patterns (hard + soft rules) |
-| `/learn/workflows/test-workflows` | Workflow tests |
-| `/learn/workflows/run-workflows` | Running workflows, inspecting output |
-| `/learn/actions/overview` | Action rules (leaf units, no action-in-action) |
-| `/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/webhooks` | Webhook triggers |
-| `/learn/triggers/schedules` | Cron / scheduled triggers |
-| `/learn/triggers/polling` | Polling triggers |
-| `/learn/triggers/advanced-triggers` | Filters, transforms, attachment ids |
+| `/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 |
-| `/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/` 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 |
+| `/learn/logs/overview` | Run history, debugging deployed runs |

package/package.json

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