@keystrokehq/skills 0.0.1

package/keystroke-credential-binding/references/patterns.md

@@ -0,0 +1,878 @@
+# Credential Examples
+
+Read this file when the user needs concrete examples for credential authoring or binding.
+
+Some later snippets reuse `crmCredentials` or `lookupTicketTool` from earlier snippets in this file.
+
+`Operation`, `Step`, and `Tool` are aliases for the same class. This reference shows both the workflow-oriented `Step` name and the agent-oriented `Tool` name so credential usage is clear in each context.
+
+File layout reminder:
+
+- keep each exported `CredentialSet` in its own `*.credential-set.ts` file
+- steps, tools, agents, triggers, and MCP servers should each live in their own typed files
+- when a snippet reuses `crmCredentials` or another primitive, import it from that primitive's own file
+
+## Minimal `CredentialSet`
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const crmCredentials = new CredentialSet({
+  id: 'crmApi',
+  auth: z.object({
+    apiKey: z.string(),
+  }),
+});
+```
+
+This is the smallest valid credential set:
+
+- `id` identifies the set
+- `auth` defines the runtime values the primitive will read
+
+## `name` and `description`
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const namedCredentials = new CredentialSet({
+  id: 'billingApi',
+  name: 'Billing API',
+  description: 'Credentials for the billing backend.',
+  auth: z.object({
+    apiKey: z.string(),
+    accountId: z.string(),
+  }),
+});
+```
+
+## `stored` and `resolve`
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+const refreshTokenSchema = z.object({
+  refreshToken: z.string(),
+});
+
+export const oauthCredentials = new CredentialSet({
+  id: 'oauthApi',
+  auth: z.object({
+    accessToken: z.string(),
+  }),
+  stored: refreshTokenSchema,
+  resolve: async (stored) => {
+    return {
+      accessToken: `access-for:${stored.refreshToken}`,
+    };
+  },
+});
+```
+
+Use `stored` and `resolve` together. Do not define one without the other.
+
+This pattern is useful when the stored values should not be the same values used at runtime.
+
+**Type flow.** The third generic on `CredentialSet` (`TStoredSchema`) narrows the
+`stored` argument to `z.output<TStoredSchema>`. Renaming a key on your `stored`
+schema flags the `resolve` hook at compile time, so the stored shape and hook
+body cannot silently drift apart.
+
+## Vault mapping (OAuth connections)
+
+An OAuth `CredentialSet` tells the platform where to persist each normalized
+token field by declaring a `vault` on its `connection`. Vault keys are typed
+against the set's stored schema (or auth schema when no stored schema is
+provided), so a typo in `vault.accessToken`, `vault.instanceUrl`, or any
+`vault.raw` key is a compile error at the `new CredentialSet({...})` call site
+and a runtime error if the type annotation is erased.
+
+### Declarative form
+
+Use the declarative form when `tokenResult.accessToken` (optionally
+`tokenResult.instanceUrl`) plus a handful of dotted-path reads off
+`tokenResult.raw` cover every vault slot.
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { createOAuth2Connection } from '@keystroke/credential-connection';
+import { z } from 'zod';
+
+export const salesforceCredentials = new CredentialSet({
+  id: 'salesforceApi',
+  auth: z.object({
+    SALESFORCE_ACCESS_TOKEN: z.string(),
+    SALESFORCE_INSTANCE_URL: z.string(),
+  }),
+  connection: createOAuth2Connection({
+    authUrl: 'https://login.salesforce.com/services/oauth2/authorize',
+    tokenUrl: 'https://login.salesforce.com/services/oauth2/token',
+    scopes: ['api', 'refresh_token', 'offline_access'],
+    tokenType: 'refreshable',
+    vault: {
+      accessToken: 'SALESFORCE_ACCESS_TOKEN',
+      instanceUrl: 'SALESFORCE_INSTANCE_URL',
+    },
+  }),
+});
+```
+
+Shopify adds a `raw` entry that reads the shop domain out of `tokenResult.raw`
+(the integration stashes it on a private `_shopifyShopDomain` key during
+`exchangeCode`):
+
+```ts
+vault: {
+  accessToken: 'SHOPIFY_ACCESS_TOKEN',
+  raw: { SHOPIFY_STORE_DOMAIN: '_shopifyShopDomain' },
+},
+```
+
+### Function form
+
+Use the function form as the escape hatch when the vault layout depends on
+derived values or on post-exchange userinfo stashed on `tokenResult.raw`.
+
+```ts
+connection: createOAuth2Connection({
+  authUrl: 'https://account.docusign.com/oauth/auth',
+  tokenUrl: 'https://account.docusign.com/oauth/token',
+  scopes: ['signature', 'extended'],
+  tokenType: 'refreshable',
+  vault: (tokenResult) => ({
+    DOCUSIGN_ACCESS_TOKEN: tokenResult.accessToken,
+    DOCUSIGN_ACCOUNT_ID: String(tokenResult.raw._docusignAccountId),
+    DOCUSIGN_BASE_URI: String(tokenResult.raw._docusignBaseUri),
+  }),
+}),
+```
+
+The function receives the full `TokenResult` and returns the full vault write
+map. Every returned key must appear on the stored (or auth) schema.
+
+Do not reach for the function form when a declarative mapping works; the
+declarative form stays readable in the manifest and keeps the vault layout
+visible to static analysis. `InstallationInfo` carries only platform identity
+fields (`externalInstallationId`, `externalWorkspaceId`, `externalBotUserId`,
+`metadata`); extra vault entries belong on `vault.raw` (declarative) or in the
+function-form return map.
+
+## `validate` hook
+
+Runs after Zod parse and before the vault write. Throws to reject; the
+thrown message is user-facing copy. Use it for behavior verification
+("does the provider accept this credential?"), not for shape validation —
+Zod already handled shape.
+
+```ts
+// Manual: Stripe secret key check
+connection: {
+  kind: 'manual',
+  instructions: 'Create a secret key at dashboard.stripe.com/apikeys.',
+  validate: async ({ credentials }) => {
+    const res = await fetch('https://api.stripe.com/v1/account', {
+      headers: { Authorization: `Bearer ${credentials.STRIPE_SECRET_KEY}` },
+    });
+    if (res.status === 401) {
+      throw new Error(
+        'Stripe rejected this secret key. Double-check it is copied exactly, ' +
+        'is from the right mode (live vs test), and has not been revoked.'
+      );
+    }
+    if (!res.ok) {
+      throw new Error(
+        `Stripe returned ${res.status} ${res.statusText} when validating the secret key.`
+      );
+    }
+  },
+},
+
+// OAuth: granted vs requested scope delta
+connection: {
+  kind: 'oauth',
+  // ...scopes, tokenType, vault...
+  validate: async ({ grantedScopes, requestedScopes }) => {
+    const missing = requestedScopes.filter((s) => !grantedScopes.includes(s));
+    if (missing.length > 0) {
+      throw new Error(
+        `Install is missing required scopes: ${missing.join(', ')}. ` +
+        'Reinstall the app and grant all requested permissions.'
+      );
+    }
+  },
+},
+```
+
+Canonical adopter: `packages/integrations/integration-stripe/src/integration.ts`.
+
+## Cached resolve
+
+Use the object form of `resolve` to cache the auth value across steps in a
+single workflow run. A 20-step workflow against a credential set with
+`cacheMs: 60_000` invokes `resolve` exactly once; steps 2..N hit the cache.
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { CredentialRevokedError } from '@keystrokehq/core/errors';
+import { z } from 'zod';
+
+export const legacyErp = new CredentialSet({
+  id: 'legacyErp',
+  auth: z.object({ sessionToken: z.string() }),
+  stored: z.object({ username: z.string(), password: z.string() }),
+  resolve: async ({ username, password }) => {
+    const res = await fetch('https://erp.example.com/login', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ username, password }),
+    });
+    if (!res.ok) throw new CredentialRevokedError('legacyErp', 'Login rejected');
+    const { token } = (await res.json()) as { token: string };
+    return { sessionToken: token };
+  },
+  resolveCacheMs: 10 * 60_000, // tokens valid ~15min; refresh at 10min
+  onCredentialRevoked: 'retry-once',
+  connection: {
+    kind: 'manual',
+    instructions: 'Enter service-account credentials.',
+  },
+});
+```
+
+## Revoke-retry
+
+```ts
+onCredentialRevoked: 'retry-once',
+connection: {
+  kind: 'manual',
+  instructions: 'Enter service-account credentials.',
+}
+```
+
+Requires `resolve`. On `CredentialRevokedError`, the platform invalidates the
+run's cache for this credential set, re-runs `resolve`, and retries the failing
+step once. Orthogonal to the normal retry budget.
+
+## `credentials-exchange` — API-login
+
+Provider offers a `POST /login` endpoint that returns a session token +
+refresh token. The user pastes `username` / `password`; the platform
+stores the exchanged session token and rotates via the refresh endpoint.
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const acmeCrm = new CredentialSet({
+  id: 'acmeCrm',
+  auth: z.object({ sessionToken: z.string() }),
+  stored: z.object({ sessionToken: z.string(), refreshToken: z.string() }),
+  resolve: async (stored) => ({ sessionToken: stored.sessionToken }),
+  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),
+      };
+    },
+  },
+});
+```
+
+## `credentials-exchange` — browser-login
+
+Provider has no API; login requires a real browser. Use
+`createBrowserLoginExchange` from `@keystroke/integration-browserbase` to
+drive Browserbase + Stagehand. The LLM never sees plaintext credentials —
+Stagehand substitutes `%fieldName%` at Chromium level.
+
+```ts
+import {
+  createBrowserLoginExchange,
+  type BrowserbaseCredentials,
+} from '@keystroke/integration-browserbase';
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+async function resolveBrowserbaseCredentials(): Promise<BrowserbaseCredentials> {
+  // Platform-owned Browserbase credentials, resolved via the internal
+  // provider-app credential set for Browserbase.
+  return { BROWSERBASE_API_KEY: process.env.BROWSERBASE_API_KEY ?? '' };
+}
+
+export const legacyPortal = new CredentialSet({
+  id: 'legacyPortal',
+  auth: z.object({ sessionCookie: z.string() }),
+  stored: z.object({
+    sessionCookie: z.string(),
+    cookieName: z.string(),
+    cookieDomain: z.string(),
+    browserbaseContextId: z.string(),
+  }),
+  resolve: async (stored) => ({ sessionCookie: stored.sessionCookie }),
+  connection: createBrowserLoginExchange({
+    input: z.object({
+      username: z.email(),
+      password: z.string().min(1),
+    }),
+    stored: z.object({
+      sessionCookie: z.string(),
+      cookieName: z.string(),
+      cookieDomain: z.string(),
+      browserbaseContextId: z.string(),
+    }),
+    loginUrl: 'https://portal.example.com/login',
+    fields: {
+      username: 'Type %username% into the email field',
+      password: 'Type %password% into the password field',
+    },
+    submit: 'Click the Sign in button',
+    successSignal: { waitForUrl: /\/dashboard/ },
+    cookie: { name: 'example_session', domain: 'portal.example.com' },
+    resolveBrowserbaseCredentials,
+  }),
+});
+```
+
+## `credentials-exchange` — service-account JWT
+
+User pastes a client email + private-key PEM; the platform mints a fresh
+JWT on exchange and re-mints on rotate. Persisting the PEM in `stored`
+lets rotate run without user input; discarding it forces a reconnect on
+every renewal.
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { SignJWT, importPKCS8 } from 'jose';
+import { z } from 'zod';
+
+async function mintJwt(privateKeyPem: string, clientEmail: string): Promise<string> {
+  const key = await importPKCS8(privateKeyPem, 'RS256');
+  return new SignJWT({ iss: clientEmail })
+    .setProtectedHeader({ alg: 'RS256' })
+    .setIssuedAt()
+    .setExpirationTime('1h')
+    .sign(key);
+}
+
+export const googleServiceAccount = new CredentialSet({
+  id: 'googleServiceAccount',
+  auth: z.object({ jwt: z.string() }),
+  stored: z.object({ jwt: z.string(), clientEmail: z.string(), privateKeyPem: z.string() }),
+  resolve: async (stored) => ({ jwt: stored.jwt }),
+  connection: {
+    kind: 'credentials-exchange',
+    input: z.object({
+      clientEmail: z.email(),
+      privateKeyPem: z.string().min(1),
+    }),
+    exchange: async ({ input }) => {
+      const jwt = await mintJwt(input.privateKeyPem, input.clientEmail);
+      return {
+        status: 'exchanged',
+        stored: { jwt, clientEmail: input.clientEmail, privateKeyPem: input.privateKeyPem },
+        expiresAt: new Date(Date.now() + 55 * 60_000),
+      };
+    },
+    rotate: async ({ previous }) => {
+      const jwt = await mintJwt(previous.privateKeyPem, previous.clientEmail);
+      return {
+        status: 'exchanged',
+        stored: { ...previous, jwt },
+        expiresAt: new Date(Date.now() + 55 * 60_000),
+      };
+    },
+  },
+});
+```
+
+Design decision: keeping the PEM in `stored` lets rotate run without user
+input. If your threat model requires discarding the PEM after first mint,
+drop it from `stored` and have `rotate` return `'needs-reinput'` instead.
+
+## External secrets sources: decision tree
+
+**Use `resolve` when:**
+
+- The transform is a pure shape / mapping adjustment on vault values.
+- The transform can be performed with no external network call.
+- No platform env vars are needed.
+- Example: HubSpot's auth-modality normalization — `stored` accepts
+  either `ACCESS_TOKEN` (OAuth) or `API_KEY` (private app); `resolve`
+  picks whichever is populated and returns `{ HUBSPOT_ACCESS_TOKEN }`.
+  Throws when neither is present so a missing credential surfaces as
+  an actionable resolver error rather than a provider 401. One
+  credential set covers both authorization paths; splitting into two
+  sets would force every consumer to branch on modality.
+
+**Use `resolveAtPlatform` when:**
+
+- The transform needs to call a service the sandbox must NOT reach
+  (HashiCorp Vault, AWS STS, GCP KMS, 1Password Connect).
+- The transform needs env vars that must NOT be visible to user step
+  code (Vault token, KMS IAM credentials).
+- The actual secret lives in an external secrets manager and the
+  Keystroke vault holds only a reference.
+- Example: AWS STS `AssumeRole` to mint 15-minute session credentials
+  per run.
+
+**Use neither when:**
+
+- The values in the vault are already what steps need.
+- Most integrations fall here (Slack, GitHub, Stripe).
+
+`resolveAtPlatform` is Keystroke-official only in v1 — the credential
+runtime rejects user-namespaced credential sets that declare the hook.
+
+### `resolveAtPlatform` — external secrets manager (HashiCorp Vault)
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const crmApi = new CredentialSet({
+  id: 'crmApi',
+  namespace: 'keystroke',
+  platformMetadata: { kind: 'user-connection', visibility: 'user-visible' },
+  auth: z.object({ apiKey: z.string() }),
+  stored: z.object({ vaultPath: z.string() }),
+  resolveAtPlatform: async (stored, ctx) => {
+    const response = await ctx.fetch(`https://vault.internal/v1/${stored.vaultPath}`, {
+      headers: { 'X-Vault-Token': ctx.env.VAULT_TOKEN ?? '' },
+    });
+    if (!response.ok) throw new Error(`Vault rejected path ${stored.vaultPath}`);
+    const { data } = (await response.json()) as { data: { apiKey: string } };
+    return { apiKey: data.apiKey };
+  },
+  platformEnvAllowlist: ['VAULT_TOKEN'],
+});
+```
+
+`VAULT_TOKEN` is in the executor's environment. `ctx.env.VAULT_TOKEN`
+exposes it to this one hook. User step code sees only
+`ctx.credentials.crmApi.apiKey` — the resolved value.
+
+### `resolveAtPlatform` — AWS STS AssumeRole
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+declare function assumeRole(params: {
+  roleArn: string;
+  sessionName: string;
+  awsAccessKeyId: string | undefined;
+  awsSecretAccessKey: string | undefined;
+}): Promise<{ accessKeyId: string; secretAccessKey: string; sessionToken: string }>;
+
+export const awsAssumed = new CredentialSet({
+  id: 'awsAssumed',
+  namespace: 'keystroke',
+  platformMetadata: { kind: 'user-connection', visibility: 'user-visible' },
+  auth: z.object({
+    accessKeyId: z.string(),
+    secretAccessKey: z.string(),
+    sessionToken: z.string(),
+  }),
+  stored: z.object({ roleArn: z.string(), sessionName: z.string() }),
+  resolveAtPlatform: async (stored, ctx) => {
+    // Calls STS with the platform's IAM credentials (never in the
+    // sandbox). The returned session credentials expire in 15 minutes.
+    const result = await assumeRole({
+      roleArn: stored.roleArn,
+      sessionName: stored.sessionName,
+      awsAccessKeyId: ctx.env.PLATFORM_AWS_ACCESS_KEY_ID,
+      awsSecretAccessKey: ctx.env.PLATFORM_AWS_SECRET_ACCESS_KEY,
+    });
+    return {
+      accessKeyId: result.accessKeyId,
+      secretAccessKey: result.secretAccessKey,
+      sessionToken: result.sessionToken,
+    };
+  },
+  platformEnvAllowlist: ['PLATFORM_AWS_ACCESS_KEY_ID', 'PLATFORM_AWS_SECRET_ACCESS_KEY'],
+});
+```
+
+### `resolveAtPlatform` — KMS-signed JWT
+
+```ts
+import { CredentialSet } from '@keystrokehq/core';
+import { z } from 'zod';
+
+declare function kmsSignJwt(params: {
+  keyArn: string;
+  payload: Record<string, unknown>;
+  platformAwsAccessKeyId: string | undefined;
+  platformAwsSecretAccessKey: string | undefined;
+}): Promise<string>;
+
+export const serviceJwt = new CredentialSet({
+  id: 'serviceJwt',
+  namespace: 'keystroke',
+  platformMetadata: { kind: 'user-connection', visibility: 'user-visible' },
+  auth: z.object({ jwt: z.string() }),
+  stored: z.object({ kmsKeyArn: z.string(), issuer: z.string(), audience: z.string() }),
+  resolveAtPlatform: async (stored, ctx) => {
+    const jwt = await kmsSignJwt({
+      keyArn: stored.kmsKeyArn,
+      payload: {
+        iss: stored.issuer,
+        aud: stored.audience,
+        exp: Math.floor(Date.now() / 1000) + 3600,
+      },
+      platformAwsAccessKeyId: ctx.env.PLATFORM_AWS_ACCESS_KEY_ID,
+      platformAwsSecretAccessKey: ctx.env.PLATFORM_AWS_SECRET_ACCESS_KEY,
+    });
+    return { jwt };
+  },
+  platformEnvAllowlist: ['PLATFORM_AWS_ACCESS_KEY_ID', 'PLATFORM_AWS_SECRET_ACCESS_KEY'],
+});
+```
+
+Signing key never leaves KMS. The sandbox sees only the freshly-signed
+JWT.
+
+## Customizing OAuth flows with presets
+
+When your OAuth provider deviates from generic OAuth 2.0, use `pipe` plus the
+`oauthPresets` catalog from `@keystroke/credential-connection` instead of hand-rolling
+the whole flow. Reach for presets for scope delimiters, authorize-URL
+parameters, Basic-auth + JSON-body token exchange, success-flag checks, and
+post-exchange identity fetches.
+
+```ts
+import {
+  buildDefaultAuthUrl,
+  exchangeCodeDefault,
+  oauthPresets as p,
+  pipe,
+} from '@keystroke/credential-connection';
+
+connection: {
+  kind: 'oauth',
+  // ...urls, scopes, tokenType, vault...
+  buildAuthUrl: pipe(buildDefaultAuthUrl, p.scopeDelimiter(',')),
+  exchangeCode: pipe(exchangeCodeDefault, p.requireSuccessFlag('ok')),
+},
+```
+
+See the "Customizing OAuth" section in `packages/credential-connection/README.md` for
+the preset catalog and worked examples from Slack, Linear, and Notion.
+
+## Step usage
+
+```ts
+import { Step } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const loadCustomer = new Step({
+  name: 'Load Customer',
+  description: 'Reads a CRM credential from step context.',
+  credentialSets: [crmCredentials],
+  input: z.object({
+    customerId: z.string(),
+  }),
+  output: z.object({
+    customerId: z.string(),
+    keyUsed: z.string(),
+  }),
+  run: async (input, ctx) => {
+    return {
+      customerId: input.customerId,
+      keyUsed: ctx.credentials.crmApi.apiKey,
+    };
+  },
+});
+```
+
+The same workflow example could also be written with `new Operation({...})` if the credential-backed unit is shared outside workflow code.
+
+## Tool usage
+
+```ts
+import { Tool } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const lookupTicketTool = new Tool({
+  name: 'Lookup Ticket',
+  description: 'Reads credentials from tool context.',
+  credentialSets: [crmCredentials],
+  input: z.object({
+    ticketId: z.string(),
+  }),
+  output: z.object({
+    ticketId: z.string(),
+    keyUsed: z.string(),
+  }),
+  run: async (input, ctx) => {
+    return {
+      ticketId: input.ticketId,
+      keyUsed: ctx.credentials.crmApi.apiKey,
+    };
+  },
+});
+```
+
+The same agent example could also be written with `new Operation({...})` if the credential-backed unit is shared outside agent code.
+
+## Agent usage
+
+```ts
+import { anthropic } from '@keystroke/integration-ai';
+import { Agent } from '@keystrokehq/core';
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  systemPrompt: 'Use the CRM credential-backed tools before answering.',
+  model: 'anthropic/claude-sonnet-4-20250514',
+  credentialSets: [anthropic, crmCredentials],
+  tools: [lookupTicketTool],
+});
+```
+
+This attaches credentials directly to the agent and also allows tools on the agent to have their own additional credential sets.
+
+## Trigger usage
+
+```ts
+import { WebhookTrigger } from '@keystrokehq/core';
+import { z } from 'zod';
+
+export const signedWebhook = new WebhookTrigger({
+  name: 'Signed Webhook',
+  description: 'Verifies a webhook with a credential-backed secret.',
+  path: '/signed',
+  method: 'POST',
+  credentialSets: [crmCredentials],
+  payload: z.object({
+    id: z.string(),
+  }),
+  verify: async (_request, ctx) => {
+    const secret = ctx.credentials.crmApi.apiKey;
+    if (!secret) {
+      throw new Error('Missing signing secret');
+    }
+  },
+});
+```
+
+This pattern is useful when the trigger itself must verify or authenticate incoming events.
+
+## MCP server usage
+
+```ts
+import { McpServer } from '@keystrokehq/core';
+
+export const crmMcpServer = new McpServer({
+  id: 'crm-mcp',
+  transport: {
+    type: 'http',
+    url: 'https://mcp.example.com',
+  },
+  credentialSets: [crmCredentials],
+  credentialMapper: (credentials) => ({
+    headers: {
+      Authorization: `Bearer ${credentials.crmApi.apiKey}`,
+    },
+  }),
+});
+```
+
+Use `credentialMapper(...)` to convert Keystroke credential values into transport-specific config such as headers, env vars, or query parameters.
+
+## `needsResolve`
+
+```ts
+const shouldResolve = oauthCredentials.needsResolve;
+```
+
+`needsResolve` is `true` only when the credential set was defined with both `stored` and `resolve`.
+
+## `describe()` and `toManifest()`
+
+```ts
+const summary = crmCredentials.describe();
+const manifest = crmCredentials.toManifest();
+```
+
+Use `describe()` for a short human-readable summary and `toManifest()` when the caller needs the manifest form.
+
+## Boundary reminder
+
+- `workflowGlobals` are not credentials
+- env vars are an input source for upload, not the primary primitive-level credential API
+- prefer `CredentialSet` plus typed context access inside Keystroke primitives
+- prefer `Step` or `Tool` naming only to communicate context; the underlying credential-backed primitive is still `Operation`
+
+## Type vs instance: one `CredentialSet`, many connected accounts
+
+One `CredentialSet` declared in code is a **type**. The platform can store many connected **instances** of that type in the vault, one per user, workspace, or explicit binding.
+
+```text
+┌───────────────────────────────────────────────────────────────────┐
+│  Credential Set TYPE                                              │
+│  Declared in code. One per integration.                           │
+│  Example: keystroke:gmail                                         │
+│    schema = { access_token: string, refresh_token: string }       │
+│    connection = OAuth 2.0 with Google                             │
+└───────────────────────────────────────────────────────────────────┘
+                               │
+                               │ (one-to-many)
+                               ▼
+  ┌──────────────────────┐    ┌──────────────────────┐
+  │ Credential Set       │    │ Credential Set       │
+  │ INSTANCE             │    │ INSTANCE             │
+  │ DB row               │    │ DB row               │
+  │ id: cset_personal    │    │ id: cset_work        │
+  │ name: "Personal"     │    │ name: "Work"         │
+  │ externalInst: me@..  │    │ externalInst: nate.. │
+  │ tokens: ...          │    │ tokens: ...          │
+  └──────────────────────┘    └──────────────────────┘
+```
+
+What authors often try first is the anti-pattern:
+
+```ts
+import { gmail } from '@keystroke/integration-google';
+import { Step } from '@keystrokehq/core';
+
+export const brokenStep = new Step({
+  name: 'Broken',
+  credentialSets: [gmail, gmail],
+  run: async () => undefined,
+});
+```
+
+That does not model two Gmail accounts. It declares the same credential type twice and collides on the same raw `id`.
+
+The supported path is **multi-step decomposition**: one credential set type, multiple steps, and explicit runtime bindings that select a different stored instance per step node.
+
+```ts
+// One credential set TYPE, declared exactly once (by the integration).
+import { gmail } from '@keystroke/integration-google';
+import { Step, Workflow } from '@keystrokehq/core';
+import { z } from 'zod';
+
+async function fetchInbox(_credentials: unknown) {
+  return [];
+}
+
+const readPersonal = new Step({
+  name: 'Read Personal Inbox',
+  credentialSets: [gmail],
+  input: z.object({}),
+  output: z.object({ messages: z.array(z.unknown()) }),
+  run: async (_, ctx) => ({ messages: await fetchInbox(ctx.credentials.gmail) }),
+});
+
+const readWork = new Step({
+  name: 'Read Work Inbox',
+  credentialSets: [gmail],
+  input: z.object({}),
+  output: z.object({ messages: z.array(z.unknown()) }),
+  run: async (_, ctx) => ({ messages: await fetchInbox(ctx.credentials.gmail) }),
+});
+
+const aggregate = new Step({
+  name: 'Aggregate Inbox Digest',
+  input: z.object({
+    personal: z.object({ messages: z.array(z.unknown()) }),
+    work: z.object({ messages: z.array(z.unknown()) }),
+  }),
+  output: z.object({
+    totalMessages: z.number(),
+  }),
+  run: async (input) => ({
+    totalMessages: input.personal.messages.length + input.work.messages.length,
+  }),
+});
+
+export const inboxDigest = new Workflow({
+  id: 'inbox-digest',
+  input: z.object({}),
+  output: z.object({ totalMessages: z.number() }),
+  run: async () => {
+    const personal = await readPersonal.run({});
+    const work = await readWork.run({});
+    return aggregate.run({ personal, work });
+  },
+});
+```
+
+At run time, the operator connects both Gmail accounts, which creates two vault rows under `resolvedCredentialSetId: 'keystroke:gmail'`, then chooses which one backs each call site:
+
+```jsonc
+{
+  "workflowId": "inbox-digest",
+  "credentialBindings": {
+    "readPersonal:keystroke:gmail": "cset_personal",
+    "readWork:keystroke:gmail": "cset_work"
+  }
+}
+```
+
+Each step node resolves its credential slot independently. `ctx.credentials.gmail` inside `readPersonal.run(...)` points at the personal account, while `ctx.credentials.gmail` inside `readWork.run(...)` points at the work account. No alias, no extra primitive, no collision.
+
+See `packages/test-workflows/src/e2e/07-reuse-step.e2e.test.ts` for an end-to-end test that exercises this mechanism with Slack.
+
+## The drawer-label rule
+
+One drawer per `id`, ever. A `CredentialSet` declaration is the label on the drawer, not an individual connection row. Two declarations with the same `id` do not create two drawers.
+
+When a collision is accidental, the platform is increasingly strict about catching it early:
+
+- compile-time on a single primitive via `AssertUniqueCredentialSetIds`
+- build-time across the project via `assertUniqueCredentialSetResolvedIds`
+- deploy-time via schema-drift detection
+- later in the reconciled credential roadmap, construction-time identity registry and vault-row schema fingerprinting close the remaining gaps
+
+When "same id" is actually a multi-instance requirement, the answer is still **one declaration, many connected rows**.
+
+```ts
+import { stripe } from '@keystroke/integration-stripe';
+
+// One declaration in code.
+export const billingCredential = stripe;
+
+// Two connected rows in storage:
+// - cset_stripe_test
+// - cset_stripe_live
+//
+// Bind the right one per step node at run time with credentialBindings.
+```
+
+Do **not** write two `CredentialSet`s just because you need two Stripe accounts. Write one credential set type, connect it twice, and bind the specific row you want for each step.