@keystrokehq/skills 0.0.1

package/keystroke-cli-workspace/references/credentials-and-connect.md

@@ -0,0 +1,79 @@
+# Credentials And Connect
+
+Read this file when the user needs Keystroke CLI guidance for integration connection or credential upload.
+
+## Connect an official integration
+
+Inspect first:
+
+```bash
+keystroke connect --help
+```
+
+Then connect:
+
+```bash
+keystroke connect slack
+keystroke connect github
+keystroke connect linear
+```
+
+Use `connect` for official Keystroke-managed connection flows.
+
+## Inspect credential requirements
+
+Inspect first:
+
+```bash
+keystroke credentials requirements --help
+```
+
+Then inspect:
+
+```bash
+keystroke credentials requirements --path <project-dir> --json
+```
+
+## Upload official integration credentials
+
+Inspect first:
+
+```bash
+keystroke credentials upload --help
+```
+
+Then upload:
+
+```bash
+keystroke credentials upload --integration slack --path <project-dir> --json
+keystroke credentials upload --integration github --path <project-dir> --json
+```
+
+## Upload a custom credential set
+
+```bash
+keystroke credentials upload --credential-set <id> --keys KEY_ONE,KEY_TWO --scope user --json
+```
+
+## Env mapping
+
+If the expected keys are:
+- `API_KEY`
+- `ACCOUNT_ID`
+
+then the env vars should be:
+- `KEYSTROKE_API_KEY`
+- `KEYSTROKE_ACCOUNT_ID`
+
+Example:
+
+```bash
+KEYSTROKE_API_KEY=secret KEYSTROKE_ACCOUNT_ID=acct_123 \
+keystroke credentials upload --credential-set billingApi --keys API_KEY,ACCOUNT_ID --scope organization --json
+```
+
+## Gotchas
+
+- Inspect `--help` before using credential commands.
+- Use `connect` for connection flows and `credentials upload` for upload flows.
+- Do not teach stale flags such as `--from-workflows` or `--no-verify`.

package/keystroke-cli-workspace/references/project-lifecycle.md

@@ -0,0 +1,85 @@
+# CLI Project Lifecycle
+
+Read this file when the user needs a practical command flow for authoring and operating a Keystroke project.
+
+## Initialize a project
+
+Inspect first:
+
+```bash
+keystroke init --help
+```
+
+Then initialize:
+
+```bash
+keystroke init
+```
+
+## Build workflows
+
+Inspect first:
+
+```bash
+keystroke workflows build --help
+```
+
+Then build:
+
+```bash
+keystroke workflows build
+```
+
+## Validate workflows
+
+Inspect first:
+
+```bash
+keystroke workflows validate --help
+```
+
+Then validate:
+
+```bash
+keystroke workflows validate
+```
+
+## Inspect or diff workflows
+
+```bash
+keystroke workflows inspect --help
+keystroke workflows diff --help
+```
+
+## Inspect workflow env or logs
+
+```bash
+keystroke workflows env --help
+keystroke workflows logs --help
+keystroke workflows paused --help
+```
+
+## Deploy workflows
+
+```bash
+keystroke deploy --help
+keystroke deploy
+```
+
+## Deploy tasks
+
+```bash
+keystroke deploy --help
+keystroke deploy --target path/to/task.task.ts
+```
+
+Use `deploy --target <task.task.ts>` when the project change is focused on an authored `Task` primitive rather than a full project deploy.
+
+## Sync Keystroke skills
+
+```bash
+keystroke skills sync --help
+keystroke skills sync
+```
+
+Use this when the local project should copy packaged Keystroke skills into `.cursor/skills` and `.claude/skills`.

package/keystroke-credential-binding/SKILL.md

@@ -0,0 +1,509 @@
+---
+name: keystroke-credential-binding
+description: Design and bind Keystroke credential sets across steps, tools, agents, tasks, triggers, gateways, and MCP servers. Use when the user needs to define a CredentialSet, wire credentials into authored primitives, inspect credential requirements, or upload credentials through the Keystroke CLI.
+---
+
+# Keystroke Credential Binding
+
+Use this skill when an agent needs to define, attach, inspect, or upload Keystroke credentials.
+
+This is the deep-dive credential skill. Workflow, agent, task, and trigger skills should link here instead of re-explaining the full credential story.
+
+## Quick start
+
+`crm-api.credential-set.ts`
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const crmCredentials = new CredentialSet({
+  id: 'crmApi',
+  name: 'CRM API',
+  auth: z.object({
+    apiKey: z.string(),
+  }),
+});
+```
+
+`load-customer.step.ts`
+
+```ts
+import { Step } from '@keystrokehq/core';
+import { z } from 'zod';
+import { crmCredentials } from './crm-api.credential-set';
+
+export const loadCustomer = new Step({
+  name: 'Load Customer',
+  description: 'Uses a typed credential set from step context.',
+  credentialSets: [crmCredentials],
+  input: z.object({
+    customerId: z.string(),
+  }),
+  output: z.object({
+    customerId: z.string(),
+    keyUsed: z.string(),
+  }),
+  run: async (input, ctx) => ({
+    customerId: input.customerId,
+    keyUsed: ctx.credentials.crmApi.apiKey,
+  }),
+});
+```
+
+## The drawer-label rule
+
+A `CredentialSet`'s `id` is a **label on a drawer in the vault**. Exactly one drawer per label, ever. Declaring `new CredentialSet({ id: 'stripe', ... })` twice does not make two drawers. Both references point at the same drawer, so whoever writes last wins and whoever reads gets whatever happens to be inside.
+
+The `auth` schema is the **contract on that drawer's contents**. If the contract changes and the drawer is not refilled to match, the next reader fails at Zod parse.
+
+Three consequences every author needs to know:
+
+1. Do not declare the same `id` in two files expecting two drawers. Either import the shared instance from one module or pick distinct ids.
+2. For "I want two of the same integration" situations (two HubSpot portals, two Slack workspaces), declare the credential set **once** and connect as many times as you need. The vault supports many rows per credential set. Per-step `credentialBindings` picks which row backs which step at run time. See [`references/patterns.md` §"Type vs instance: one `CredentialSet`, many connected accounts"`](./references/patterns.md#type-vs-instance-one-credentialset-many-connected-accounts).
+3. For "this provider exposes two authorization modalities" situations (OAuth vs pasted private-app token, bot token vs user token, live vs test key), declare the credential set **once** with a `stored` schema that accepts either input shape and a `resolve` hook that collapses them into a single runtime `auth` value. Splitting by modality would force every consuming step, tool, agent, and template to branch on which drawer is populated — leaking an authorization-modality detail that the provider's API itself does not expose. The HubSpot integration is the canonical example: `stored` accepts `ACCESS_TOKEN` (OAuth) or `API_KEY` (private app); `resolve` normalizes both into `{ HUBSPOT_ACCESS_TOKEN }`. Only split when the runtime shape, granted scopes, or target endpoints genuinely differ between modalities (e.g. HubSpot's separate `hubspot-developer` drawer for developer-app-scoped APIs that cannot accept a user access token).
+
+## Authoring model
+
+Teach this mental model clearly:
+- a `CredentialSet` defines typed auth values in code
+- authored primitives attach credential sets where they need them
+- runtime code reads credentials through typed context, not through `process.env`
+- upload and connect flows satisfy the authored credential requirements before deployment or execution
+
+## Where credentials can be attached
+
+Credential sets can show up on:
+- steps and tools
+- agents
+- tasks indirectly through the agent they reference
+- triggers
+- messaging gateways
+- MCP servers
+
+Do not assume one credential location covers every layer. An agent can need provider credentials, tool credentials, gateway credentials, and MCP credentials at the same time.
+
+## Runtime access
+
+Teach these rules:
+- steps and tools read credentials from `ctx.credentials`
+- only the trigger `verify` callback receives credentials through its callback context (`filter`, `idempotencyKey`, and `transform` do not receive credentials)
+- MCP servers map credentials through `credentialMapper`
+- authored code should not read secrets from `process.env`
+
+## Important id rule
+
+Call out this distinction when it matters:
+- `CredentialSet.id` is the raw authored id used in runtime credential context keys
+- `resolvedCredentialSetId` is the namespaced or manifest-facing id used for bindings and storage
+- runtime lookups still use the raw `id`
+
+This matters for integration authors and when explaining `createOperationFactory`.
+
+## Default credential process
+
+1. Group related auth values into a single credential set.
+2. Reuse an existing credential set when it already fits.
+3. Define the `CredentialSet` with `auth`, or with `stored` plus `resolve` when runtime auth must be derived.
+4. Attach the credential set to the primitive that needs it.
+5. Read credentials through typed runtime context.
+6. Inspect requirements before deploy.
+7. Upload or connect credentials through the CLI only when the user wants that step performed.
+
+## Credential rules
+
+- Keep each exported credential set in its own `*.credential-set.ts` file.
+- Use `auth` for direct runtime credential shapes.
+- If `stored` is present, `resolve` must also be present.
+- If `resolve` is present, `stored` must also be present.
+- Use `CredentialSet` instead of env-based secret handling inside authored primitives.
+- Follow Zod v4 syntax in examples and authored code. See `../../../.agents/rules/zod-v4-requirements.md`.
+- The drawer-label rule is enforced at three layers today: compile-time on a single primitive (`AssertUniqueCredentialSetIds`), build-time across the project (`assertUniqueCredentialSetResolvedIds`), and deploy-time schema-drift detection (`detectSchemaDrifts`). Cluster 07 of the reconciled credential plan adds two more layers: construction-time identity registry and vault-row schema fingerprint. You do not need to do anything special in authored code beyond following the rule above.
+
+### Vault-row schema mismatch
+
+Every vault row is stamped with the credential set's schema fingerprint at upload. When a workflow later resolves credentials against a credential set whose `auth` or `stored` shape has changed since the row was written, the credential runtime raises `CredentialSchemaMismatchError` with a copy-paste remediation command:
+
+```
+The credentials stored for "keystroke:acme-crm" were uploaded against a different schema than the workflow currently expects.
+
+  Uploaded at:    2026-01-15T12:34:56.000Z
+  Uploaded shape: abc123…
+  Current shape:  def456…
+
+To fix, re-upload credentials:
+  keystroke credentials upload --credential-set acme-crm --keys sessionToken,refreshToken
+```
+
+The CLI (`keystroke credentials upload`) and the web UI (`POST /api/v1/credentials/resolve`'s 422 response) both render this command verbatim. Preflight surfaces the same mismatch under `schemaMismatches[]` before any step dispatches, so operators don't hit the failure mid-run. Rotations against a stale row are skipped (the credential set is marked `needs_reconnect` until re-uploaded).
+
+You don't invoke the check yourself — it's wired into every resolver consumer. The only thing authored code does is what it already does: declare `auth` and `stored` honestly. When you change either, operators re-upload.
+
+### Caching `resolve`
+
+By default every step calls your `resolve` hook fresh. For shape-normalizing
+hooks (HubSpot, Notion) that is cheap and leaves authors on the plain-function
+form. Throw on missing input rather than falling back to an empty string — an
+empty token produces a confusing 401 at the provider instead of a clear
+"credentials not connected" error at the resolver boundary:
+
+```ts
+resolve: async (stored) => {
+  const token = stored.ACCESS_TOKEN ?? stored.API_KEY;
+  if (!token) {
+    throw new Error(
+      'Unable to resolve HubSpot credentials: provide either ACCESS_TOKEN (via OAuth) or API_KEY (private app)'
+    );
+  }
+  return { HUBSPOT_ACCESS_TOKEN: token };
+}
+```
+
+Pair the hook with a `.refine()` on the `stored` schema so Zod rejects
+"neither field populated" at upload time, before the resolver runs.
+
+For hooks that do real work (login exchange, KMS-signed JWT, ephemeral session
+token), use the object form:
+
+```ts
+resolve: async (stored) => mintToken(stored),
+resolveCacheMs: 10 * 60_000, // cache for 10 minutes within a single workflow run
+```
+
+A workflow run has a single cache; steps 2..N hit the cache. When the run
+ends, the cache is discarded.
+
+Pick `cacheMs` conservatively — under 75% of the provider's actual token
+validity window is a safe default. If the cached token expires mid-run, pair
+with top-level `onCredentialRevoked: 'retry-once'` on the credential set to self-heal.
+
+### Self-healing with `retry-once`
+
+When a step receives a 401 / 403 and the integration throws
+`CredentialRevokedError`, the default behavior fails the step and marks the
+connection broken. Sometimes the credential is actually fine — it just expired
+a moment ago, and re-running `resolve` would produce a working token.
+
+Opt in at the credential-set root (next to `connection`, not inside it):
+
+```ts
+onCredentialRevoked: 'retry-once',
+connection: {
+  kind: 'manual',
+}
+```
+
+Requires `resolve`. On `CredentialRevokedError`, the platform invalidates the
+run's cache for this credential set, re-runs `resolve`, and retries the step
+once. If the retry succeeds, the workflow continues and the connection is not
+marked broken. If the retry fails, the step fails normally and the connection
+status flips as today.
+
+The revoke-retry is orthogonal to the normal retry budget: a step with
+`retries: { attempts: 3 }` still gets its full three attempts after one
+revoke-retry fires.
+
+**When NOT to use.** For credential sets without a stateful `resolve` (Slack
+bot tokens, pasted API keys), re-running `resolve` on the same stored values
+produces the same output. `retry-once` would burn one extra attempt with the
+same result. Leave the default `'fail'`.
+
+### Workspace-authored OAuth integrations
+
+First-party (`namespace: 'keystroke'`) OAuth credential sets source
+`clientId` / `clientSecret` from the platform's shared provider apps.
+User-authored OAuth credential sets need to point at their own OAuth app,
+so they MUST declare `oauthClientSource` — construction fails otherwise.
+
+The pattern is two credential sets, both authored with the raw
+`CredentialSet` primitive:
+
+```ts
+// file 1 — the internal client-app credential set
+export const acmeClientApp = new CredentialSet({
+  id: 'acmeClientApp',
+  namespace: 'keystroke',
+  auth: z.object({ clientId: z.string(), clientSecret: z.string() }),
+  platformMetadata: { kind: 'provider-app', visibility: 'internal' },
+  // No `connection` — client-app credentials are provisioned out-of-band
+  // (operator env, admin upload), not through a user-facing connect flow.
+});
+
+// file 2 — the user-connection OAuth credential set
+export const acmeCrm = new CredentialSet({
+  id: 'acmeCrm',
+  namespace: 'keystroke',
+  platformMetadata: { kind: 'user-connection', visibility: 'user-visible' },
+  auth: z.object({ ACME_ACCESS_TOKEN: z.string() }),
+  connection: {
+    kind: 'oauth',
+    authUrl: 'https://auth.acme.example.com/oauth/authorize',
+    tokenUrl: 'https://auth.acme.example.com/oauth/token',
+    scopes: ['read:contacts'],
+    tokenType: 'refreshable',
+    vault: { accessToken: 'ACME_ACCESS_TOKEN' },
+    oauthClientSource: {
+      kind: 'workspace-provider-app',
+      credentialSet: acmeClientApp,
+    },
+  },
+});
+```
+
+Key rules:
+
+- The `clientApp` MUST be marked `platformMetadata: { kind: 'provider-app', visibility: 'internal' }`
+  so the sandbox refuses to inject `clientSecret` into user step code.
+  Construction of the user-connection set throws if its
+  `oauthClientSource.credentialSet` points at a non-internal set.
+- User-namespaced OAuth MUST declare `oauthClientSource`. Construction
+  throws with a clear error if it's missing.
+- If the `clientApp` schema uses alternate key names (e.g. `appId` /
+  `appSecret` instead of `clientId` / `clientSecret`), pass a `keyMap`:
+  `oauthClientSource: { kind: 'workspace-provider-app', credentialSet: acmeClientApp, keyMap: { clientId: 'appId', clientSecret: 'appSecret' } }`.
+
+The platform's initiate, callback, and refresh flows route workspace
+OAuth through the same `resolveOAuthClient` helper first-party
+integrations use — the end-to-end behavior is identical once the
+workspace provider app is registered (`keystroke integrations register <id> --client-app <credentialSetId>`).
+
+## Validating a credential at upload time
+
+Every `CredentialSet.connection` accepts an optional `validate` hook. It runs
+after Zod parses the submitted values and before the vault write commits.
+Throw with a helpful message to reject; the thrown message is shown verbatim
+to the operator in both the CLI and the OAuth callback UI.
+
+```ts
+// Manual
+connection: {
+  kind: 'manual',
+  instructions: '<where does the operator find this credential?>',
+  validate: async ({ credentials }) => {
+    const res = await fetch('<provider /me or /account endpoint>', {
+      headers: { Authorization: `Bearer ${credentials.AUTH_KEY}` },
+    });
+    if (!res.ok) {
+      throw new Error(
+        '<provider> rejected this credential. ' +
+        '<one actionable sentence about what to check>'
+      );
+    }
+  },
+}
+
+// OAuth — scope-delta check
+validate: async ({ grantedScopes, requestedScopes }) => {
+  const missing = requestedScopes.filter((s) => !grantedScopes.includes(s));
+  if (missing.length > 0) {
+    throw new Error(
+      `<provider> install is missing required scopes: ${missing.join(', ')}. ` +
+      'Reinstall the app and grant all requested permissions.'
+    );
+  }
+},
+```
+
+### When to use `validate`
+
+Reach for it when:
+
+- The provider has a cheap `whoami` / `/me` / `/account` endpoint.
+- Rejected credentials would otherwise surface at first workflow run.
+- Typoed keys, wrong-mode keys, revoked tokens, or missing OAuth scopes are
+  common failure modes.
+
+### When NOT to use `validate`
+
+Skip it when:
+
+- The provider does not offer a cheap validation endpoint.
+- Rate limits make validate calls expensive.
+- The credential can only be validated mid-workflow (e.g. per-operation
+  signing). Runtime 401 self-heal lives on a separate primitive
+  (`onCredentialRevoked`; see cluster 09 of the reconciled credential plan).
+
+### Timeouts
+
+The platform enforces an 8-second timeout for CLI uploads and a 6-second
+timeout for OAuth callbacks. Your hook should finish quickly; an
+unresponsive provider endpoint surfaces to the operator as "Credential
+validation timed out."
+
+Canonical adopter: `packages/integrations/integration-stripe/src/integration.ts`.
+
+## `credentials-exchange`
+
+Use `kind: 'credentials-exchange'` when a user submits credentials and *you* —
+not a third-party authorization server — exchange them for something else
+(session token, cookie, JWT). Three common shapes:
+
+1. **API-login.** Provider has a `POST /login` endpoint. Input: `username` /
+   `password`. Stored: session token + refresh token. Rotate via the refresh
+   endpoint. Expiry comes from the provider's TTL.
+
+2. **Browser-login.** Provider has no API; login requires a real browser.
+   Input: `username` / `password`. Stored: session cookie + Browserbase
+   context id. Rotate by probing the session and falling back to
+   `'needs-reinput'` when the cookie has expired. Use
+   `createBrowserLoginExchange` from `@keystroke/integration-browserbase`.
+
+3. **Service-account JWT.** User pastes a private-key PEM. Input:
+   `clientEmail` + `privateKeyPem`. Stored: freshly-minted JWT. Rotate by
+   re-minting from the PEM (if you keep the PEM in `stored`) or by
+   returning `'needs-reinput'` (if you discard the PEM after first mint).
+
+```ts
+connection: {
+  kind: 'credentials-exchange',
+  input: z.object({ username: z.email(), password: z.string().min(1) }),
+  exchange: async ({ input }) => {
+    const res = await fetch('https://acme.example.com/auth/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(input),
+    });
+    if (res.status === 401) {
+      return { status: 'needs-reinput', message: 'Invalid credentials.' };
+    }
+    if (!res.ok) throw new Error(`Login failed: ${res.status}`);
+    const body = await res.json();
+    return {
+      status: 'exchanged',
+      stored: { sessionToken: body.token, refreshToken: body.refresh },
+      expiresAt: new Date(Date.now() + body.ttlSec * 1000),
+    };
+  },
+  rotate: async ({ previous }) => {
+    const res = await fetch('https://acme.example.com/auth/refresh', {
+      method: 'POST',
+      body: JSON.stringify({ refresh: previous.refreshToken }),
+    });
+    if (!res.ok) return { status: 'needs-reinput' };
+    const body = await res.json();
+    return {
+      status: 'exchanged',
+      stored: { sessionToken: body.token, refreshToken: body.refresh },
+      expiresAt: new Date(Date.now() + body.ttlSec * 1000),
+    };
+  },
+}
+```
+
+### When to use
+
+Reach for `credentials-exchange` when:
+
+- The user inputs one thing and the vault stores a different thing.
+- There is a rotation lifecycle (TTL, refresh token, session renewal).
+- You want the platform to manage rotate cadence rather than re-running
+  the exchange per step.
+
+### When NOT to use
+
+Stick with `kind: 'manual'` + `stored` + `resolve` when:
+
+- What the user types is what you store (Stripe: paste secret key, store
+  secret key).
+- There is no rotation. (API keys that don't expire.)
+- The transform from `stored` to `auth` is pure and in-process (no
+  network).
+
+### When to use `kind: 'manual'` with a `resolve` hook instead
+
+`kind: 'manual'` + `stored` + `resolve` is still valid for non-lifecycle
+transforms: pure shape mapping or auth-modality normalization where no
+server handshake or rotation is involved. The HubSpot integration uses this
+pattern to collapse two authorization modalities (OAuth `ACCESS_TOKEN` or
+private-app `API_KEY`) into a single runtime `HUBSPOT_ACCESS_TOKEN` — note
+that HubSpot's `connection.kind` is `'oauth'` for the connect flow, but the
+`stored`/`resolve` pair is what lets a user skip OAuth and paste a
+private-app token via `keystroke credentials upload --credential-set hubspot
+--keys API_KEY=…` instead.
+
+Pick `credentials-exchange` only when the transform involves a server-side
+handshake and the resulting token has a lifecycle.
+
+### `'needs-reinput'` semantics
+
+`CredentialsExchangeResult` is a discriminated union. The non-success
+branch is `{ status: 'needs-reinput', message? }` — **not** a boolean.
+Returning it:
+
+- Preserves the prior vault row (if any) so the reconnect flow has
+  `previous` to reference.
+- Surfaces `message` verbatim to the CLI / web UI.
+- Marks the credential set `needs_reconnect` when it fires from the
+  rotate scheduler.
+
+## `resolveAtPlatform`
+
+Use `resolveAtPlatform` instead of `resolve` when the transform needs
+trusted network access (external secrets manager, STS `AssumeRole`,
+KMS / HSM signing) or platform env vars that must not be visible to
+user step code. The hook runs on the executor with a scoped `fetch`
+and an allowlisted `env`; the resolved `auth` values reach the sandbox
+but the stored inputs (vault path, platform IAM credentials) never do.
+
+```ts
+export const crmApi = new CredentialSet({
+  id: 'crmApi',
+  auth: z.object({ apiKey: z.string() }),
+  stored: z.object({ vaultPath: z.string() }),
+  resolveAtPlatform: async (stored, ctx) => {
+    const res = await ctx.fetch(`https://vault.internal/v1/${stored.vaultPath}`, {
+      headers: { 'X-Vault-Token': ctx.env.VAULT_TOKEN ?? '' },
+    });
+    const { data } = (await res.json()) as { data: { apiKey: string } };
+    return { apiKey: data.apiKey };
+  },
+  platformEnvAllowlist: ['VAULT_TOKEN'],
+});
+```
+
+**Reference Keystroke-official only in v1.** User-authored
+`resolveAtPlatform` is rejected at the runtime adapter boundary because
+the hook runs with unscoped network access on the trusted host. Add a
+new ADR before lifting this restriction.
+
+### `resolve` vs `resolveAtPlatform` vs neither
+
+- **Use `resolve`** when the transform is pure shape / mapping on
+  already-decrypted vault values — no network call, no platform env.
+  *Example:* HubSpot's `stored.ACCESS_TOKEN ?? stored.API_KEY`
+  modality-normalization hook.
+- **Use `resolveAtPlatform`** when the transform must call a service
+  the sandbox may not reach (HashiCorp Vault, AWS STS, GCP KMS,
+  1Password Connect) or read platform env vars the sandbox may not
+  see. The actual secret lives in the external manager; the Keystroke
+  vault holds only a reference. *Example:* AWS STS `AssumeRole` mints
+  15-minute per-run credentials.
+- **Use neither** when the stored values are already what steps need.
+  Most integrations fall here (Slack, GitHub, Stripe).
+
+See `references/patterns.md` for three worked examples (Vault, STS
+`AssumeRole`, KMS-signed JWT).
+
+## CLI flows to teach
+
+Teach only the current command surface:
+- `keystroke credentials list`
+- `keystroke credentials requirements --path <dir> --json`
+- `keystroke credentials upload --integration <public-id> --path <dir> --json`
+- `keystroke credentials upload --credential-set <id> --keys <KEY1,KEY2> --scope <scope> --json`
+
+When the user has env-backed values, explain the `KEYSTROKE_<KEY>` convention.
+
+Do not teach stale flows such as:
+- `--from-workflows`
+- `--no-verify`
+- invented commands like `credentials add`
+
+For wider command usage, cross-link to `../keystroke-cli-workspace/SKILL.md`.
+
+## References
+
+Read these files as needed:
+- `references/source-map.md` for the public credential surface
+- `references/cli.md` for the current credential command cookbook
+- `references/patterns.md` for field-by-field code examples