@keystrokehq/cli 0.1.15 → 0.1.16

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

@@ -9,9 +9,9 @@ metadata:
 
 An **app** is a connectable integration: a slug, an auth kind, and (for custom apps) a field template. **Connected** = secrets for that app have been uploaded via the connect flow.
 
-Secrets never live in source or `.env`. Each **target** (local server vs cloud project) has its own connections — `keystroke deploy` uploads code only, not connections. Connect apps on **every target** you run on.
+Secrets never live in source or `.env`. `keystroke deploy` uploads code only, not connections — connect the apps your project needs with the connect flow.
 
-Custom actions that call external APIs **must** go through an app — sync it into `src/apps/` first, then use `app.action()` in `src/actions/`. See [actions skill](.agents/skills/keystroke-actions/SKILL.md).
+Custom actions that call external APIs need a **credential**. The simplest path is a standalone `defineCredential` declared on a `defineAction`. Reach for an **app** (`defineApp` + `app.action()`) when several actions share one connection, or when you've synced a catalog/custom app into `src/apps/`. See [actions skill](.agents/skills/keystroke-actions/SKILL.md).
 
 ## Two sources of apps
 
@@ -83,7 +83,7 @@ Auth kinds: `keystroke` (MCP/Composio catalog apps), `api_key` (custom fields),
 
 ## Connect an app
 
-`keystroke connect <slug>` opens the dashboard connect flow (OAuth or API-key form, depending on the app). This is how secrets get attached to an app — not via `.env`.
+`keystroke connect <slug>` opens the web app connect flow (OAuth or API-key form, depending on the app). This is how secrets get attached to an app — not via `.env`.
 
 **Official integrations** — the cleanest path:
 
@@ -100,34 +100,47 @@ keystroke app sync acme/internal-api
 keystroke connect acme/internal-api
 ```
 
-Run `connect` against **each target** you deploy to (local while developing; cloud after `keystroke config use cloud`). The dashboard **Apps** page offers the same flow.
+The web app **Apps** page offers the same flow.
 
-Field names in the connect form match the app's synced template. Default scope is **project** — see [cli-and-catalog.md](references/cli-and-catalog.md).
+Field names in the connect form match the app's synced template. You pick the scope (project / org / user) in the web connect flow — `keystroke connect` has no `--scope` flag. See [cli-and-catalog.md](references/cli-and-catalog.md).
 
-## Before deploy: connect on cloud
+## Connect what your project needs
 
-Cloud starts with **no connected apps**. After the first deploy:
+A new project starts with **no connected apps**. After deploy, connect the apps it uses:
 
 ```bash
 keystroke deploy --project <id>
-keystroke config use cloud
 keystroke connect google
 keystroke connect exa
 keystroke app list
 ```
 
-A runtime error about a missing connection almost always means the app was connected locally but not on the cloud target.
+A runtime error about a missing connection almost always means the app hasn't been connected for this project.
+
+## Manage & bind credentials
+
+`keystroke credentials list / get / update --default / rotate-key / delete` manage instances. When several instances share a scope and none is the default, a run can't auto-resolve — set a default, or **bind** an exact instance to one step/tool:
+
+```bash
+keystroke credentials consumers list --workflow sync                                   # step:<slug>#<n>
+keystroke credentials assignments assign --workflow sync --credential org/work --consumer step:fetch-gmail#0
+keystroke credentials assignments assign --agent support --credential vault-prod --consumer vault-lookup   # tool slug
+```
+
+An assignment is the explicit selection at the top of the resolution order, so it overrides scope defaults. Full surface: [cli-and-catalog.md](references/cli-and-catalog.md).
 
 ## Audit
 
 ```bash
-keystroke app list    # org-registered apps
+keystroke app list                       # org-registered apps
+keystroke credentials list               # connected instances + scope + default
+keystroke credentials assignments list --workflow <slug>   # which instance is pinned where
 ```
 
-Failed integration call → confirm target (`keystroke config show`), the app is connected on that target, and the action uses the right slug.
+Failed integration call → confirm the app is connected for your project, the action uses the right slug, and (if multiple instances) a default or assignment resolves the right one.
 
 ## Next references
 
-- [cli-and-catalog.md](references/cli-and-catalog.md) — `keystroke app` commands, connect, scopes, local vs cloud
+- [cli-and-catalog.md](references/cli-and-catalog.md) — `keystroke app` commands, connect, scopes, credential management & binding
 
-Related: [cli](.agents/skills/keystroke-cli/SKILL.md), [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), [channels](.agents/skills/keystroke-channels/SKILL.md).

package/dist/skills-bundle/skills/keystroke-apps/references/cli-and-catalog.md

@@ -7,7 +7,7 @@ keystroke auth login
 keystroke auth status
 ```
 
-Token is stored in the OS keychain and reused for **cloud** CLI commands. Switching local ↔ cloud does not require re-auth. See [cli skill](.agents/skills/keystroke-cli/SKILL.md).
+Token is stored in the OS keychain and reused for all CLI commands. See [cli skill](.agents/skills/keystroke-cli/SKILL.md).
 
 ## keystroke app commands
 
@@ -23,11 +23,11 @@ All org-scoped; output is JSON.
 | `app create` | Create custom org `api_key` app (`--name`, `--slug`, `--description`, `--field`) |
 | `app sync <slug>` | Write `src/apps/<name>/app.ts` from platform template (`--dir`) |
 
-`--field` syntax: `key`, `key:secret`, `key:optional`, or `key:secret:optional` (repeatable).
+`--field` syntax: `key`, `key:secret`, `key:optional`, `key:public`, or combinations like `key:secret:optional` (repeatable). A bare `key` is **secret by default**; `:public` forces a non-secret field. `app create` requires at least one `--field`, and at least one of them must be required (not `:optional`).
 
 ## Connect an app
 
-`keystroke connect <slug>` attaches secrets to an app via the dashboard connect flow:
+`keystroke connect <slug>` attaches secrets to an app via the web app connect flow:
 
 ```bash
 keystroke connect google          # official OAuth
@@ -40,27 +40,58 @@ keystroke connect <slug> --print-url  # deeplink without opening browser
 - **Official integrations** — always prefer `keystroke connect <slug>`
 - **Custom apps** — `keystroke app sync <slug>` first, then `keystroke connect <slug>`
 - Slug must exist in your org registry (`app list`)
-- Connect once per **target** (local dev server vs cloud deployed project)
-- Dashboard at `:3000` → **Apps** offers the same flow
+- The web app **Apps** page offers the same flow
 
 ## Scopes
 
-When you connect an app, the connection is stored at one scope:
+A connection is stored at one scope. `keystroke connect` has **no** `--scope` flag — you choose the scope in the web connect flow. To set scope from the CLI, use `keystroke credentials set <key> --scope <scope> [--project-slug <slug>]` (that command defaults to `org`).
 
 | Scope | When |
 | ----- | ---- |
-| `project` (default) | Tie to one project — use unless told otherwise |
-| `org` | Share with every user and project — only on explicit request |
+| `project` | Tie to one project |
+| `org` | Share with every user and project |
 | `user` | Single user's personal connection |
 
-At runtime resolution is **org first, then project**. Get the active project id from `keystroke config show`.
+At runtime resolution prefers the **project default first, then the org default**. Get the active project id from `keystroke config show`.
 
-## `.env` vs connected apps
+## Manage & bind credentials
 
-| Holds | `.env` | Connected apps (via connect) |
-| ----- | ------ | ------------------------------ |
-| Model keys (`ANTHROPIC_API_KEY`), DB URL, OAuth **provider** config (`SLACK_CLIENT_ID`, `GOOGLE_*`) | yes — local boot only | — |
-| Integration secrets resolved at runtime | — | yes |
-| Reaches the cloud? | no | yes, when connected on cloud target |
+Day-to-day management (output is JSON):
 
-App secrets are **not** read from `.env` — connect the app with `keystroke connect`. Connections follow the active target (local while `keystroke dev` runs; cloud after deploy). Re-connect on the cloud target after deploy.
+```bash
+keystroke credentials list                                   # every instance + scope + default flag
+keystroke credentials get <credential-id>
+keystroke credentials update <credential-id> --label "Prod" --default
+keystroke credentials rotate-key <credential-id> --set apiKey=@env:ACME_API_KEY
+keystroke credentials delete <credential-id>
+```
+
+`--default` marks one instance as the default for its app + scope. When several instances share a scope and none is the default, a run can't auto-resolve — set a default, or **bind** a specific instance to the step/tool that needs it.
+
+### Bind a specific instance to a step or tool
+
+An assignment pins an exact credential instance to one consumer. It's the **explicit selection** at the top of the resolution order, so it wins over scope defaults. List the bindable consumers first, then assign:
+
+```bash
+# Workflow consumers are step correlation ids from recent runs (step:<slug>#<n>)
+keystroke credentials consumers list --workflow sync
+keystroke credentials assignments assign --workflow sync --credential org/work --consumer step:fetch-gmail#0
+
+# Agent consumers are tool slugs
+keystroke credentials consumers list --agent support
+keystroke credentials assignments assign --agent support --credential vault-prod --consumer vault-lookup
+
+# Omit --consumer (or pass "*") to bind every consumer on the target
+keystroke credentials assignments assign --workflow sync --credential work
+
+keystroke credentials assignments list --workflow sync       # inspect bindings
+keystroke credentials assignments unassign <assignment-id>   # remove one
+```
+
+- Exactly one of `--workflow <slug>` or `--agent <slug>` is required.
+- `--credential` takes an instance slug: `work`, `org/work`, or `<app>/<slug>` (e.g. `linear/work`).
+- Workflow consumer ids only appear after a run has produced `step_completed` events; `consumers list` reads them from recent runs.
+
+## Where secrets live
+
+App secrets are **not** read from `.env` and are **never** uploaded by `keystroke deploy` — it ships code only. Attach integration secrets by connecting the app with `keystroke connect <slug>`; they're resolved at runtime for your project.

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

@@ -0,0 +1,66 @@
+---
+name: keystroke-channels
+description: Let people use keystroke agents from Slack (external channels) — connect Slack, bind channels with `keystroke channel bind`, pick a listen mode. Use when setting up messaging for agents.
+metadata:
+  keystroke-domain: channels
+---
+
+# External channels
+
+External channels route **Slack (and similar) messages** to an agent — people chat in-channel instead of using the CLI. Slack is the only channel today.
+
+## Setup (Slack)
+
+1. Deploy the agent you want to chat with (`keystroke deploy`)
+2. Connect Slack once for the org: `keystroke connect slack` (or the web app **Apps** page); complete OAuth
+3. Bind a channel to the agent (CLI below, or the agent's **External Channels** panel in the web app)
+4. Message the bound channel per its listen mode
+
+## Bind from the CLI
+
+```bash
+keystroke channel platforms list                                  # supported platforms
+keystroke channel accounts --platform slack                       # connected workspaces (team ids)
+keystroke channel directory --platform slack --account <team-id>  # channels you can bind
+keystroke channel bind \
+  --agent support \
+  --platform slack \
+  --account <team-id> \
+  --channel <channel-id> \
+  --mode mention
+keystroke channel list --agent support                            # bindings for an agent
+```
+
+Listen modes (`--mode`): `mention` (only when @mentioned), `all` (every message), `dm` (direct messages). Update or remove a binding with `keystroke channel update-binding --agent <id> --binding <id> --mode all` / `keystroke channel unbind --agent <id> --binding <id>`.
+
+`channel bind` also takes an optional `--channel-name <name>` (defaults to the channel id). Every `keystroke channel` subcommand accepts `--project <slug>` to target a non-active project; otherwise they use the active project.
+
+## What happens at runtime
+
+Inbound Slack event → lookup channel binding → `runPrompt` for the bound agent → reply in thread.
+
+The agent acts **on behalf of the channel**, not the sender: it runs with its own tools, actions, and credentials regardless of who messaged. Only bind agents to channels whose members you trust with everything the agent can do.
+
+## Audit channel-driven sessions
+
+The CLI session source is still named `gateway`:
+
+```bash
+keystroke agent sessions list <agent-key> --source gateway
+keystroke agent sessions get <agent-key> <session-id> --include messages,trace
+```
+
+## Troubleshooting
+
+| Issue       | Check                                                               |
+| ----------- | ------------------------------------------------------------------- |
+| Bot silent  | `keystroke agent sessions list` for errors; agent on the binding    |
+| "Choose an agent" prompt | The channel has no agent bound — bind one with `keystroke channel bind` |
+| OAuth fails | Slack redirect URLs match your project's web app origin             |
+| Wrong agent | Re-bind with `keystroke channel bind` (or the web app panel)        |
+
+## Next references
+
+- [slack-setup.md](references/slack-setup.md) — connect flow, testing against a deployed project
+
+Related: [agents](.agents/skills/keystroke-agents/SKILL.md), [apps](.agents/skills/keystroke-apps/SKILL.md).

package/dist/skills-bundle/skills/keystroke-channels/references/slack-setup.md

@@ -0,0 +1,41 @@
+# Slack channel setup
+
+## Connect Slack
+
+Connect the Slack app once for the org with `keystroke connect slack` — the Slack app credentials are entered in the web connect flow, not in your project's `.env`. The connected workspace stays connected; adding more agents is just a bind step.
+
+Slack OAuth and the inbound routes mount automatically on your **deployed** project, so connecting against the cloud target works out of the box — you don't add Slack to `keystroke.config.ts`.
+
+## Bind a channel
+
+```bash
+keystroke channel accounts --platform slack                       # find the team id
+keystroke channel directory --platform slack --account <team-id>  # find the channel id
+keystroke channel bind --agent support --platform slack \
+  --account <team-id> --channel <channel-id> --mode mention
+```
+
+`--mode` is `mention`, `all`, or `dm`. Thread follow-up is on by default; toggle it with `keystroke channel update-binding --agent <id> --binding <id> --threads` / `--no-threads`.
+
+The web app offers the same flow from each agent's **External Channels** panel.
+
+## Testing
+
+Slack OAuth and the inbound event routes are handled by your **deployed** project — `keystroke dev` (local watch/rebuild) is not in the Slack delivery path. To test Slack end-to-end: `keystroke deploy`, `keystroke connect slack`, `keystroke channel bind …`, then message the bound channel and inspect the session (below).
+
+> Self-hosting the keystroke platform is a separate concern: that setup seeds Slack app credentials via platform env vars (`SLACK_CLIENT_ID/SECRET/SIGNING_SECRET`) and a public origin (`PUBLIC_PLATFORM_PROXY_URL`). Those are **platform** vars, not part of a scaffolded user project, and `keystroke dev` does not read them.
+
+## Audit
+
+```bash
+keystroke agent sessions list <agent-key> --source gateway
+keystroke agent sessions get <agent-key> <session-id> --include messages,trace
+```
+
+## Common fixes
+
+| Issue         | Fix                                                |
+| ------------- | -------------------------------------------------- |
+| 401 on events | Check the signing secret in the Slack connection   |
+| No reply      | Session errors via `keystroke agent sessions list` |
+| Wrong agent   | Re-bind with `keystroke channel bind`              |

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

@@ -1,132 +1,80 @@
 ---
 name: keystroke-cli
-description: Keystroke CLI — local dev vs cloud platform targets, config switching, deploy, and when to use each. Use when running keystroke commands against localhost or a deployed project.
+description: Keystroke CLI — log in, manage projects, deploy your src/, and run/inspect what's deployed (workflows, agents, triggers, apps). Use when running keystroke commands for a project.
 metadata:
   keystroke-domain: cli
 ---
 
 # CLI
 
-The CLI is the primary interface for keystroke projects. Most commands hit an **API target**: either **local** (your keystroke server) or **cloud** (keystroke platform control plane → deployed keystroke server for that project).
+The CLI is the primary interface for keystroke projects. You build in `src/`, deploy to your project on the platform, then run and inspect what's deployed. The loop is **edit → deploy → run/inspect → repeat**; deploy often.
 
-## Local vs cloud
-
-| Target    | Use for                                                                                                | Default URL                           |
-| --------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------- |
-| **Local** | Development and testing — iterate on `src/`, run workflows/agents against your machine, debug sessions | `PUBLIC_PLATFORM_URL` in project `.env` (dev session when `keystroke dev` is running) |
-| **Cloud** | Invoking, listing, and operating a **deployed** project — production runs, trigger URLs, remote audit  | `{platformUrl}/api/projects/{id}`     |
-
-**Rule of thumb:** while you are building or validating changes, use **local**. After deploy, use **cloud** to invoke and inspect what is live.
-
-Auth (`keystroke auth login`) is **shared** — one login in the keychain. Switching local ↔ cloud or organizations does not require re-authenticating.
-
-**Organizations (cloud only)**
+## Log in
 
 ```bash
-keystroke auth login                 # auto-picks org if you have one; prompts if several
-keystroke auth login --org <id>      # headless org pick
-keystroke config org list           # list memberships
-keystroke config use org            # interactive switch
-keystroke config use org <id>       # switch active org
+keystroke auth login                 # once; token stored in the OS keychain and reused
+keystroke auth login --org <org-slug>  # headless org pick
+keystroke config org                 # list org memberships
+keystroke config use org <org-slug>  # switch active org
 ```
 
-## Platform projects
+One login covers every command. `auth login` auto-picks your org if you have one and prompts if there are several.
 
-A **platform project** is a deploy target on the keystroke control plane — not your local repo directory (`keystroke init` scaffolds the latter).
+## Projects
+
+A **project** is your deploy target on the platform. `keystroke init` scaffolds the local repo; the platform project is where it runs.
 
 ```bash
 keystroke project list
 keystroke project create --name "My app" --description "Optional"
-keystroke deploy --project <id>       # build + upload; see deploy skill for --filter
-keystroke config use project <id>     # set default cloud target (works before deploy)
+keystroke deploy --project <id>       # build + upload src/; see deploy skill for --filter
 ```
 
-New projects are **inactive** until deploy. You can set the default project before deploy; runtime commands still require an active project. The CLI prints hints when the list is empty or when status is `inactive`.
-
-Full deploy, filtered module redeploy, and WIP ignore: [deploy skill](../keystroke-deploy/SKILL.md).
-
-## Quick start
+`--project` selects the deploy target. It's a global flag that works before or after the subcommand (`keystroke deploy --project <id>`).
 
-**Local development**
+New projects are **inactive** until the first deploy. After a deploy, `keystroke deploy` remembers the project (saved in `~/.keystroke`), so later commands target it without `--project`. To switch which project later commands use:
 
 ```bash
-keystroke dev                    # watch + rebuild; other CLI commands auto-target local while this runs
-keystroke start                  # or one-shot local server
-keystroke workflow run greeting --input '{"name":"Ada"}'
-keystroke agent prompt hello --message "Hi"
+keystroke config use project <id>
 ```
 
-**Cloud (deployed project)**
+To target a different project for a single command without changing the default:
 
 ```bash
-keystroke auth login
-keystroke project list                              # or: project create --name "My app"
-keystroke deploy --project <project-id>
-keystroke workflow run greeting --input '{"name":"Ada"}'   # hits cloud after deploy
-keystroke trigger list
-keystroke trigger list --endpoint stripe   # all webhooks on a shared endpoint
-keystroke trigger url stripe               # shared route URL (or use a trigger key)
+keystroke workflow runs list greeting --project <id>
 ```
 
-## Switch targets
+By default the CLI targets the cloud platform. To run commands against a locally running server (`keystroke start` / `keystroke dev`), use the global `--local` flag for one command, or `keystroke config use local` / `keystroke config use cloud` to switch the default target.
 
-Config lives in `~/.keystroke`. Two settings work together:
-
-| Setting           | Purpose                                                                       |
-| ----------------- | ----------------------------------------------------------------------------- |
-| `activeProjectId` | Which cloud project you use (set by deploy; **not** cleared when going local) |
-| `apiTarget`       | `local` or `platform` — default routing for commands                          |
+Full deploy, filtered module redeploy, and WIP ignore: [deploy skill](../keystroke-deploy/SKILL.md).
 
-```bash
-keystroke config show
-keystroke config use local              # local dev; cloud project id preserved
-keystroke config use cloud              # back to stored activeProjectId
-keystroke config use project <id>       # swap active cloud project
-```
+## Run & inspect
 
-**One-off overrides** (do not change config):
+After deploy, runtime commands operate on your project:
 
 ```bash
-keystroke --local workflow runs list greeting
-keystroke --project other-id trigger list
+keystroke workflow run greeting --input '{"name":"Ada"}'
+keystroke workflow runs list greeting
+keystroke workflow runs get greeting <run-id> --include steps,trace
+keystroke agent prompt hello --message "Hi"
+keystroke agent sessions get support <session-id> --include messages,trace
+keystroke app list
+keystroke trigger list
+keystroke trigger list --endpoint stripe   # all webhooks on a shared endpoint
+keystroke trigger url stripe               # shared route URL (or a trigger key)
 ```
 
-While `keystroke dev` is running, other commands auto-target **local** unless you pass `--project`.
-
-## Resolution order
-
-1. `--local` → local
-2. `keystroke dev` session active → local
-3. `--project <id>` → cloud (that project only)
-4. `apiTarget=local` → local
-5. `apiTarget=platform` + `activeProjectId` → cloud
-6. default → local
-
-Full detail: [api-targets.md](references/api-targets.md).
+Always use the CLI to inspect runs and sessions — do not hand-craft HTTP requests.
 
-## Commands by target
+## Commands at a glance
 
-| Command                                                            | Typical target                                             |
-| ------------------------------------------------------------------ | ---------------------------------------------------------- |
-| `dev`, `start`, `build`                                            | Local project only                                         |
-| `project list`, `project create`                                   | Platform control plane (org-scoped)                        |
-| `deploy`                                                           | Platform (sets `activeProjectId` + `apiTarget=platform`)   |
-| `workflow`, `agent`, `trigger`, `app`, `connect`, `health` | Follows resolved target                                    |
-| `auth login`                                                       | Web dashboard (`webUrl`); token reused for cloud API calls |
-
-## Audit & debug
-
-Always use the CLI — do not hand-craft HTTP against the wrong host.
-
-```bash
-# Local: default while developing
-keystroke workflow runs list signup-pipeline
-keystroke agent sessions get support <session-id> --include messages,trace
-
-# Cloud: after deploy or keystroke config use cloud
-keystroke trigger list
-keystroke trigger list --endpoint shared-hub
-keystroke trigger url incoming-message
-```
+| Command                                            | What it does                                              |
+| -------------------------------------------------- | -------------------------------------------------------- |
+| `auth login`                                       | Authenticate; token reused for all commands              |
+| `project list`, `project create`                   | Manage deploy targets in the active org                  |
+| `deploy`                                           | Build `src/` and ship it; sets the active project        |
+| `workflow`, `agent`, `trigger`, `app`              | Run and inspect resources on your project                |
+| `connect <slug>`                                   | Connect an integration (see apps skill)                  |
+| `config use project <id>`, `config show`           | Set/inspect the active project                           |
 
-Related: [deploy](.agents/skills/keystroke-deploy/SKILL.md), [apps](.agents/skills/keystroke-apps/SKILL.md), [workflows](.agents/skills/keystroke-workflows/SKILL.md), [agents](.agents/skills/keystroke-agents/SKILL.md), [triggers](.agents/skills/keystroke-triggers/SKILL.md).
+Related: [deploy](../keystroke-deploy/SKILL.md), [apps](../keystroke-apps/SKILL.md), [workflows](../keystroke-workflows/SKILL.md), [agents](../keystroke-agents/SKILL.md), [triggers](../keystroke-triggers/SKILL.md).

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

@@ -7,7 +7,7 @@ metadata:
 
 # Deploy
 
-Deploy uploads a `dist/` tarball to the keystroke **platform** and promotes a new project-server runtime (blue/green). Local `keystroke start` / `keystroke dev` never deploy — use this skill when shipping to cloud.
+Deploy uploads a `dist/` tarball to the keystroke **platform** and promotes a new project-server runtime (blue/green). Use this skill when shipping your project to the platform.
 
 ## Prerequisites
 
@@ -17,6 +17,8 @@ keystroke project list                    # or: project create --name "My app"
 keystroke deploy --project <slug>         # first deploy must be full (no --filter)
 ```
 
+`--project` selects the deploy target; as a global flag it works before or after `deploy`. After a successful deploy the project becomes the active target (saved in `~/.keystroke`), so later commands (including subsequent deploys) can omit it.
+
 Deploy always **builds before upload**. Full deploy wipes `dist/` (`clean: true`), rebuilds all modules, regenerates `route-manifest.json`, then packs and uploads.
 
 ## Full deploy
@@ -24,10 +26,10 @@ Deploy always **builds before upload**. Full deploy wipes `dist/` (`clean: true`
 ```bash
 keystroke build                           # optional preview; deploy rebuilds anyway
 keystroke deploy --project <slug>
-keystroke deploy --dir ./my-app --project <slug>
+keystroke deploy --project <slug> --dir ./my-app
 ```
 
-After success: `activeProjectId` and `apiTarget=platform` are set. Verify with `keystroke config use cloud` and `keystroke workflow run <key> --input '{}'`.
+After success the project becomes the active target for later commands. Verify with `keystroke workflow run <key> --input '{}'`.
 
 ## Filtered deploy (one module)
 
@@ -58,7 +60,7 @@ Keep draft agents/workflows/triggers in `src/` but out of the runtime:
 - `ignore` — broken or not-ready; stays out of `dist/` everywhere.
 - `ignore:deploy` — runs locally; excluded from deploy only.
 
-A shipped module that **imports** an ignored file fails the build (import guard). Triggers attached to an ignored workflow need the same directive.
+Import guard: a shipped module that **imports** an `@keystroke ignore` file fails the build in **every** phase; importing an `@keystroke ignore:deploy` file builds fine locally and fails only at **deploy** time. Triggers attached to an ignored workflow need the same directive.
 
 Detail: [wip-ignore.md](references/wip-ignore.md).
 
@@ -66,10 +68,10 @@ Detail: [wip-ignore.md](references/wip-ignore.md).
 
 | Command            | Phase   | Output                                      |
 | ------------------ | ------- | ------------------------------------------- |
-| `keystroke build`  | `build` | `dist/` for local inspection                |
+| `keystroke build`  | `build` | `dist/` for inspection                      |
 | `keystroke deploy` | `deploy`| `dist/` + upload; honors `ignore:deploy`    |
 
-`keystroke dev` / `keystroke start` use incremental builds (`clean: false`). Deploy always runs a fresh build first.
+Deploy always runs a fresh, clean build before upload.
 
 Detail: [build-and-full-deploy.md](references/build-and-full-deploy.md).
 
@@ -78,13 +80,12 @@ Detail: [build-and-full-deploy.md](references/build-and-full-deploy.md).
 - **First deploy with `--filter`** — fails; run full deploy once.
 - **Wrong `--dir`** — builds a different tree than you edited.
 - **Expecting full refresh with `--filter`** — only matched modules rebuild; rest comes from active prod.
-- **Connected apps aren't in `.env`** — deploy never uploads `.env`; connect apps on the cloud target. See [apps skill](../keystroke-apps/SKILL.md).
+- **Connected apps aren't in `.env`** — deploy never uploads `.env`; connect apps for your project. See [apps skill](../keystroke-apps/SKILL.md).
 
 ## Audit deployed runtime
 
 ```bash
-keystroke config use cloud
-keystroke --project <slug> project deployments list
+keystroke project deployments list --project <slug>
 keystroke workflow run morning-check --input '{}'
 keystroke trigger list
 ```

package/dist/skills-bundle/skills/keystroke-deploy/references/build-and-full-deploy.md

@@ -7,7 +7,9 @@
 3. `packProjectArtifact` — gzip tarball of `dist/`.
 4. Platform `artifacts.create` → PUT tarball → `complete` → blue/green promote.
 
-Source files upload in parallel (content-addressed); failure there warns but does not block deploy.
+Source files upload in parallel (content-addressed); failure there warns but does not block deploy. The dashboard source snapshot is capped (per-file 256KB, total 8MB, 2000 files) and skips binaries, `.env`, and `.log` files — so `.env` is never uploaded.
+
+After upload, the CLI polls the project status (every ~2s, up to a 120s timeout) until it reports `active` or `failed`; on failure it surfaces the platform's `lastError`. A hang usually means the platform promotion is still in progress.
 
 ## Entry keys
 

package/dist/skills-bundle/skills/keystroke-deploy/references/filtered-deploy.md

@@ -9,6 +9,8 @@ keystroke deploy --project <slug> --filter workflows/morning-check
 keystroke deploy --project <slug> --filter agents/support --filter workflows/signup-pipeline
 ```
 
+(`--project` can go before or after `deploy`, and can be omitted after the first deploy.)
+
 - Exact entry keys only — no globs, no negation, no slug aliases.
 - First deploy for a project must be **full** (no `--filter`).
 - Without an active artifact, deploy errors: run a full deploy first.
@@ -41,8 +43,7 @@ Change `keystroke.config.ts` or project-wide assets → run a **full** deploy.
 ## Verify
 
 ```bash
-keystroke --project <slug> project deployments list   # new version active
-keystroke config use cloud
+keystroke project deployments list --project <slug>   # new version active
 keystroke workflow run <workflow-slug> --input '{}'
 ```
 

package/dist/skills-bundle/skills/keystroke-deploy/references/wip-ignore.md

@@ -1,12 +1,15 @@
 # WIP modules and `@keystroke ignore`
 
-Place the directive at the **top** of a module file under `src/agents/`, `src/workflows/`, or `src/triggers/`.
+Place the directive in the **leading comment block** of a module file under `src/agents/`, `src/workflows/`, or `src/triggers/` (the scan stops at the first non-comment line). Line (`//`) and block (`/* … */`, `*`) comments both work.
 
 ```ts
 // @keystroke ignore
 // @keystroke ignore:deploy
+/** @keystroke ignore */
 ```
 
+Only `ignore` and `ignore:deploy` are valid. Any other scope (e.g. `// @keystroke ignore:build`) throws `Unknown @keystroke ignore target "…"` at build time.
+
 ## Directives
 
 | Directive              | Local build (`build`, `dev`, `start`) | Deploy (`phase: deploy`) |
@@ -21,7 +24,7 @@ Place the directive at the **top** of a module file under `src/agents/`, `src/wo
 
 ## Import guard
 
-If a **shipped** module imports a file marked `@keystroke ignore` (either form), the build **fails**. Compose in workflows instead of importing ignored actions from production modules.
+If a **shipped** module imports a file marked `@keystroke ignore`, the build **fails in every phase**. If it imports an `@keystroke ignore:deploy` file, the local build/dev succeeds and only the **deploy** build fails (because `ignore:deploy` files are excluded only in the deploy phase). Compose in workflows instead of importing ignored actions from production modules.
 
 ## Triggers
 

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

@@ -15,11 +15,15 @@ Files under `src/files/` mount into the agent sandbox at `/workspace/agent/`.
 src/files/support/
   product-guide.md
   support-instructions.md
+  runbooks/
+    refunds.md
 ```
 
+Nested directories are preserved — `src/files/support/runbooks/refunds.md` mounts at `/workspace/agent/runbooks/refunds.md`.
+
 ```ts
-import { defineAgent } from "@keystrokehq/agent";
-import { defineSandbox } from "@keystrokehq/sandbox";
+import { defineAgent } from "@keystrokehq/keystroke/agent";
+import { defineSandbox } from "@keystrokehq/keystroke/sandbox";
 
 export default defineAgent({
   slug: "support",
@@ -28,8 +32,12 @@ export default defineAgent({
 });
 ```
 
-Use `defineSandbox({ files: "shared" })` to mount `src/files/shared/` instead.
+Use `defineSandbox({ files: "shared" })` to mount `src/files/shared/` instead — the string value names the folder under `src/files/`.
+
+If the named folder doesn't exist, the build fails with a clear error — create the folder (it must contain at least one file) before deploying.
+
+Files are seeded **write-once** at sandbox startup: the agent can edit them at runtime, but those edits aren't persisted back to `src/files/` and reset on the next run. Treat `src/files/` as read-only seed content.
 
-Point the agent at paths in `systemPrompt`. After `keystroke start`, verify behavior with `keystroke agent prompt support --message "…"`.
+Point the agent at paths in `systemPrompt`. After deploy, verify behavior with `keystroke agent prompt support --message "…"`.
 
 Related: [agents](.agents/skills/keystroke-agents/SKILL.md), [skills](.agents/skills/keystroke-skills/SKILL.md).